//
// File   : EyeEvent.hh
//
// Purpose: Header file for EyeEvent.cc, containing TEyeEvent class decl.
//
// $Id: EyeEvent.hh 12083 2011-02-21 17:11:42Z mathes $
//


#ifndef _EyeEvent_hh_
#define _EyeEvent_hh_

/** @file EyeEvent.hh
  * Declaration of the class TEyeEvent.
  * @author H.-J. Mathes, FzK
  */

#include <iostream>

#include <TObject.h>

#ifndef NO_VERSION
# include <EyeEventVersion.hh>
#endif // NO_VERSION

#include <FdNumbering.hh>
#include <TTimeStamp.hh>


/** @mainpage FD Eye Event Data Format Library
   
    @subsection intro Introduction
   
    This document contains the description of the FD eye event data format 
    library which is used to describe all components of a FD eye event.
    This library is built on top of the FD Mirror Event Data Format Library
    which is therefor required to build this library.

    To create this documentation again you need at least doxygen 1.4.0.
    @see http://www.stack.nl/~dimitri/doxygen/index.html

    The library is divided into the following parts:
    @li the classes describing the different constituents of an eye event, 
        namely the classes TEyeEvent, TEyeEventHeader, TEyePixelList, 
	TEyePixelData and TEyeFADCData.
    @li the class TEyeEventFile which provides means to load and save all
        event related objects from/to a file.
    @li the classes TEyeEventHeader and TEyeEventTrailer which contain
        information relevant for describing static parameters of a data 
	taking RUN.
    
    Please note that the class TEyeTriggerData contains optional data and the 
    access to it is done in a different way. In order to mark the object as 
    filled (could be done also by testing for reasonable
    data) the Set*Data() method has to be used.
    
    @subsection usage Usage
   
    The library package is used by including:
    \code
    #include <MiEvent.hh>
    #include <EyeEvent.hh>
    #include <EyeEventFile.hh>
    \endcode
    
    and linking with:
    \code
    -L$(EYELIBDIR) -lEyeEvent
    \endcode
    where EYELIBDIR must be set properly to the correct directory which
    contains <i>libEyeEvent.a</i> or <i>libEyeEvent.so</i>. This path is 
    usually set to <i>\$(FD_ROOT)/lib</i> or <i>\$(FD_ROOT)/eye/lib</i>.
    
    @subsection feature Features

    A FDs TEyeEvent consists of:
    @li an event header object named TEyeEventHeader
    @li a list of all pixels present in the current event named TEyePixelList
    @li a copy of the TMirrorPixelData objects into an object
        named TEyePixelData.
    @li a container for the FADC data traces named TEyeFADCData which contains
        copies of the passed TFADCData objects from the mirrors
    @li TEyeT3Data
    @li TEyeTriggerDtata (not yet used)
    @li TEyeGeometryData

    @subsection compile Compilation and Installation
    
    <b>Preconditions:</b>
     @li the package 'FD Mirror Event Data Format Library' must be present,
         its header files and resulting libraries must be installed in
	 <i>\$(FDINCDIR)</i> and <i>\$(FDLIBDIR)</i>, respectively.

     @li the package 'FD-DAQ C++ Utility Libraries' must be present, its header
         files and resulting libraries must be installed in
	 <i>\$(FDUTILINCDIR)</i> and <i>\$(FDLIBDIR)</i>, respectively.<br>
	 The libraries are namely <i>libUtillib.a</i> and
	 <i>libRootUtillib.a</i> or <i>libRootUtillib.so</i>.

    @subsection changes Changes
    
    The list of changes is maintained in the file CHANGES
    @verbinclude CHANGES
    
  */


// ----- some constant definitions ...

/** Constant to define the data structure version. */

#define EyeEVENTVERSIONv1      1   // v0r1 .. v0r5
#define EyeEVENTVERSIONv2      2   // v0r6
#define EyeEVENTVERSIONv3      3   // v0r7
#define EyeEVENTVERSIONv4      4   // v0r8
#define EyeEVENTVERSIONv5      5   // v0r9
#define EyeEVENTVERSIONv6      6   // v1r1
#define EyeEVENTVERSIONv7      7   // v1r2
#define EyeEVENTVERSIONv8      8   // v1r5
//#define EyeEVENTVERSIONv9      9   // v1r6p6 njet!
#define EyeEVENTVERSIONv9      9   // v2r0
#define EyeEVENTVERSIONv10    10   // v2r1

/** Current data structure version (always the last one from above!). */

#define EyeEVENTVERSION        EyeEVENTVERSIONv9

#include <EyeRunHeader.hh>
#include <EyeRunTrailer.hh>

// ----- forward declarations

class TEyeEventHeader;
class TEyeFADCData;
class TEyeGeometryData;
class TEyePixelList;
class TEyePixelData;
class TEyeTriggerData;
class TEyeT3Data;

class TMirrorEvent;

//#ifndef __CINT__   // passed to cint via cmd line
#include <EyeEventHeader.hh>
#include <EyeFadcData.hh>
#include <EyeGeometryData.hh>
#include <EyePixelList.hh>
#include <EyePixelData.hh>
#include <EyeT3Data.hh>
//#endif // __CINT__

/** Class to represent a complete FD Eye event.
  *
  * An Eye event (class TEyeEvent) consists of:
  * @li an event header object (TEyeEventHeader)
  * @li a pixel list object (TEyePixeliIst), indicating from which pixels data
  *     are present in the current event.
  * @li an (optional) pixel data object (TEyePixelData). With pixel data the
  *     data read out from the SLT memories is meant.
  * @li a FADC data object (TEyeFADCData) containing each pixels ADC data trace.
  * @li the TEyeT3Data containing more detailed output of the T3 stage
  * @li the TEyeGeometryData contains some geometry information used
  *     during T3 evaluation
  *
  * In addition the TEyeEvent might contain additional data structures, which
  * are:
  * @li the TEyeTriggerData containing the merged trigger information read
  *     from the front-end crates (not used nor filled)
  *
  * @todo
  * @li set the FADC trace start time of each single TFADCData object
  */
class TEyeEvent : public TObject {
    friend class TEyeEventFile;
    
    // to access TEyeEvent::fgPrintLevel
    friend class TEyeEventHeader;

    // to access TEyeEvent::fgPrintLevel
    friend class TEyePixelList;
    
public:
    /** Default constructor for the class TEyeEvent.
      *
      * The following actions are taken:
      * @li no storage for the sub-objects is reserved.
      * @li the pointers to the sub-objects are set to NULL.
      *
      * Note: Allocating no storage for the sub-objects follows the
      *       recommandations of ROOT. If a getter is called, storage will be 
      *       allocated if not already done by reading from a file.
      */
    TEyeEvent();

    /** Copy constructor of the class TEyeEvent.
      */
    TEyeEvent(const TEyeEvent&);

    /** Assignment operator for the class TEyeEvent.
      */
    TEyeEvent& operator=(const TEyeEvent&);

    /** Destructor for the class TEyeEvent. The storage for all internally hold
      * objects is released.
      */
    virtual ~TEyeEvent();

    /** operator==() for the class TEyeEvent.
      */
    bool operator==(const TEyeEvent& rhs) const
     { return this == &rhs; }
    
    /** Add a TMirrorEvent to the TEyeEvent object.
      *
      * Some of the fields of the TMirrorEvent data structure are added to the
      * TEyeEvent. The following actions are taken:
      * @li TMirrorEventHeader is not copied
      * @li a 'IsMirrorDataPresent bit' is set for each mirror from where a 
      *     TMirrorEvent was received
      * @li optional: TMirrorPixelData are added. This depends on:
      *     @li a TMirrorPixelData object must be present
      *     @li this behaviour must be explicitely enabled (is the case)
      * @li the TMirrorPixelList is appended to the TEyePixelList
      * @li steered by the TMirrorPixelList the individual  FADC traces
      *     (hold by the TMirrorFADCData objects) are added to TEyeFADCData
      *
      * @return true if the event was added
      */
    virtual bool AddEvent(TMirrorEvent*,bool force=false);

    /** Clear the contents of the TEyeEvent. */
    virtual void Clear(Option_t *option="");
    	
    /** Apply some corrections to the data (read). */
    static void DoCorrections(TEyeEvent*);
    
   // --- getters ...

    /** Get a pointer to the TEyeEventHeader sub-object. */
    virtual TEyeEventHeader* GetEventHeader();

    /** Get a pointer to the TEyeFADCData sub-object. */
    virtual TEyeFADCData* GetFADCData();

    /** Get a pointer to the TEyeGeometryData sub-object. */
    virtual TEyeGeometryData* GetGeometryData();
    
    /** Get a pointer to a TMirrorFADCData object which is owned by the
      * TEyeEvent object (not yet implemented). 
      * @param mirror_id the Mirrors id in the range EYE_FIRST_MIRROR ...
      *   EYE_LAST_MIRROR.
      * @return a pointer to the requested or a NULL pointer if the object
      *   is not available (empty pixel list) or if that Mirror was not present
      *   in the DAQ/in that event.
      */
    virtual TMirrorFADCData* GetMirrorFADCData(UInt_t mirror_id);
    
    /** Get a pointer to the TEyePixelData sub-object. */
    virtual TEyePixelData* GetPixelData();

    /** Get a pointer to the TEyePixelList sub-object. */
    virtual TEyePixelList* GetPixelList();

    /** Get the trigger data of the current event.
      *
      * @return an empty TEyeTriggerData object if none was available, else
      *         the TEyeTriggerData of the current TEyeEvent
      */
    virtual TEyeTriggerData* GetTriggerData();

    /** Get the T3 data of the current event.
      *
      * @return an empty TEyeT3Data object if none was available, else
      *         the TEyeT3Data of the current TEyeEvent
      */
    virtual TEyeT3Data* GetT3Data();
    
    /** Returns true, if the TEyeEvent contains also pixel data. 
      * 
      * Note: TEyePixelData have been always been enabled, thus this
      *       (now obsolete) method returns always true.
      */
    bool IsEnabledPixelData()
     { return true; }

    /** Remove the TMirrorEvent for the specified telescope from the
      * TEyeEvent.
      *
      * @param mirror_id telescope id, range 1 ... 6
      * @param ev_ptr if specified, the removed TMirrorEvent will be stored
      *               there
      *
      * @return true if the event was successfully removed
      */
    virtual bool RemoveEvent(unsigned int,TMirrorEvent** evptr=NULL);
    
    /** Reset the contents of the TEyeEvent.
      *
      * This is achieved by erasing the contained objects.
      */
    virtual void Reset();
    
     /** Print the contents of a TEyeEvent to an ostream (usually cout).
      */
    void Show(std::ostream& ostr=std::cout);
	
    /** Set the geometry data for the current setup/event. */
    virtual void SetGeometryData(TEyeGeometryData*);
    
    /** Set the level of verbosity for all instances of this class. */
    static void SetPrintLevel(unsigned int level=1)
     { fgPrintLevel = level; }

    /** Set the trigger data for the current event. */
    virtual void SetTriggerData(TEyeTriggerData*);
    
    /** Set the T3 data for the current event. */
    virtual void SetT3Data(TEyeT3Data*);

protected:

#ifndef __CINT__
    /** Map Mirror event labels to Eye event classes.
      * (improved version, thjm 29.04.04)
      */
    void ConvertMirrorEventLabel(TMirrorEventHeader::EMiEventLabel);
#endif // __CINT__
    
    /** This enum defines the contents of the (in principle) obsolete attribute 
      * fDataPresentBits.
      */
    enum {
      kPixelDataPresent    = 0x0001,  ///< always present
      
      kWeatherDataPresent  = 0x0010,  ///< obsolete
      kTriggerDataPresent  = 0x0020,  ///< unused
      kT3DataPresent       = 0x0040,  ///< always present
      kGeometryDataPresent = 0x0080   ///< v2r0: always present
    };
    
private:

    Version_t               fStreamerVersion; //! version read from file
    
    TEyeEventHeader        *fEventHeader;  // Eye event header
    TEyeFADCData           *fFADCData;     // container of FADC traces
    TEyePixelList          *fPixelList;    // (compressed) list of pixels
    TEyePixelData          *fPixelData;    // container of TMirrorPixelData
    
    TEyeTriggerData        *fTriggerData;  // trigger info (unused) 
    TEyeT3Data             *fT3Data;       // T3 info (used) 
    TEyeGeometryData       *fGeometryData; // geometry info
    
    static unsigned int     fgPrintLevel;  //! print/verbosity level for TEye* classes
    
    ClassDef(TEyeEvent,EyeEVENTVERSIONv5)
};

#endif // _EyeEvent_hh_