ltiFireWireDCAM.h

/*
 * Copyright (C) 2004, 2005, 2006
 * Lehrstuhl fuer Technische Informatik, RWTH-Aachen, Germany
 *
 * This file is part of the LTI-Computer Vision Library (LTI-Lib)
 *
 * The LTI-Lib is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public License (LGPL)
 * as published by the Free Software Foundation; either version 2.1 of
 * the License, or (at your option) any later version.
 *
 * The LTI-Lib is distributed in the hope that it will be
 * useful, but WITHOUT ANY WARRANTY; without even the implied warranty
 * of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with the LTI-Lib; see the file LICENSE.  If
 * not, write to the Free Software Foundation, Inc., 59 Temple Place -
 * Suite 330, Boston, MA 02111-1307, USA.
 */


/*--------------------------------------------------------------------
 * project ....: LTI-Lib: Image Processing and Computer Vision Library
 * file .......: ltiFireWireDCAM.h
 * authors ....: Arnd Hannemann
 * organization: LTI, RWTH Aachen
 * creation ...: 21.10.2004
 * revisions ..: $Id: ltiFireWireDCAM.h,v 1.7 2008/08/17 22:20:12 alvarado Exp $
 */

#ifndef _LTI_FIRE_WIRE_D_C_A_M_H_
#define _LTI_FIRE_WIRE_D_C_A_M_H_

#include "ltiHardwareConfig.h"

#ifdef _USE_FIRE_WIRE_DCAM

#include <libraw1394/raw1394.h>
#include <libdc1394/dc1394_control.h>

#include <string>
#include <vector>
#include <set>
#include <map>
#include "ltiFrameGrabber.h"
#include "ltiMergeYCbCrToImage.h"
#include "ltiBayerDemosaicing.h"
#include "ltiMutex.h"


namespace lti {
  /**
   * Grab imags from FireWire Cameras.
   *
   * This functor permits to interact with standard FireWire DCAM cameras (aka
   * IIDC v1.3x).  It is a wrapper of the libdc1394 library in (linux).  You
   * may find the information of the IIDC standard useful, which can be found
   * on the net (for instance, in 
   * http://damien.douxchamps.net/ieee1394/libdc1394/iidc_specifications.php ).
   *
   *  System requirements:
   *    - linux kernel modules ieee1394, ohci1394, raw1394 and video1394
   *    - libdc1394 (>= 1.0.0, < 2.x)
   *    - libraw1394 (>= 0.9.0)
   *  Since the version 2.x of libdc1394 still is beta, no migration has been
   *  done for it yet.  Several changes are required, but the version control
   *  of that library isn't supported yet.
   *
   *  Installation:
   *    -# compile or install above kernel modules for your kernel (usually
   *       they are in most distributions ready)
   *    -# create video devicefiles for video1394
   *       (e.g. /dev/video1394).  This is also usually automatically done.
   *    -# compile or install libdc1394 and libraw1394.  Most distributions
   *       provide packages for them.  Do not forget to install the "dev" or
   *       "devel" packages of the library as well.
   *    -# edit extrapaths.mk in the linux directory of your ltilib to permit
   *       the use of this functor.
   *       (example can be found in extrapaths_template.mk)
   *    -# compile ltilib
   *    -# all kernel modules must be loaded before running any code that uses
   *       this class.
   *
   * Example:
   *  \code
   *    // viewer to display taken shot
   *    viewer view("FireWireDCAM");
   * 
   *    fireWireDCAM::parameters camPar;
   *    fireWireDCAM cam;

   *    // will be preserved by init()
   *    camPar.deviceFile = "/dev/video1394/0";
   *    camPar.oneShot = true;
   *    camPar.brightness = 22;
   *
   *    // as the camera is initialized now, the new parameters will be written
   *    // into the camera
   *    cam.setParameters(camPar);
   *    // take picture
   *    image img;
   *    cam.apply(img);
   *
   *    // show image
   *    view.show(img);
   *
   *  \endcode
   *
   *  Not yet implemented:
   *  - format7 (scalable image)
   *  - color modes: Mono16, RGB, YUV444
   *  - camera features: (see fireWireDCAM::parameters)
   *
   *  Other things to do:
   *  - get feature constraints
   *  - it would be much better to use a wrapper class instead of including
   *    raw1394.h and dc1394_control.h directly (namespace)
   *  - better error handling (e.g. remember setup_capture failures etc..)
   *
   * \warning Even if some code has been developed for support of
   * one-push and format7 features, we haven't got a camera that
   * supports them and therefore that code may not work.  Please
   * report any problems, or even better, submit a patch with fixes if
   * they are necessary.
   */
  class fireWireDCAM : public frameGrabber {
  public:
    // ------------------------------------------------
    // enumerations
    // ------------------------------------------------
    
    /**
     * Auto correction modes for parameters
     *
     * While setting the parameters for a camera, you can decide how to behave
     * on invalid parameters.
     */
    enum eFixMode {
      NoFix,   /**< Use the parameters as they are given, and if something is
                    invalid, return an error */
      AutoFix, /**< Try to use the parameters as they are given, but is
                    something is invalid or not supported by the active camera,
                    change it to a valid configuration */
      Upload   /**< Ignore the parameters given, and simply upload the values
                    in use in the camera indicated by the parameters set, which
                    is set as active. */
    };

    /**
     * Feature state
     *
     * Most features, following the IIDC standard, can be used in one of the
     * following states.
     *
     * Several notes on the values:
     * - The FeatureOff can under circumstances be used to check if a
     *   feature can be turned off.  The use of any other state implies that
     *   the feature is on.
     * - The FeatureOnePush activates the "one-push" adjustment when the
     *   functor parameters are updated (setParameters() do that too, of 
     *   course), or when one specific methods for direct camera control
     *   (like setBrightness()) is used.
     * - The FeatureAbsolute is identical to manual, except that, if a camera
     *   supports it, the values are given in certain units specified by the
     *   standard, like \b degrees for hue, pan and tilt, \b percentage for 
     *   brightness and saturation, \b meters for focus, and so on.
     * - FeatureNA is used to indicate that a feature is not available or
     *   that the user wants this functor not to touch the configuration of
     *   a given feature.
     */
    enum eFeatureState {
      FeatureNA=0,     /**< Feature not available */
      FeatureOff=1,    /**< Feature is deactivated */
      FeatureAuto=2,   /**< Feature adjustments are taken automatically */
      FeatureManual=4, /**< Feature adjustments are done by the user */
      FeatureOnePush=8,/**< Feature is automatically adjusted but only once */
      FeatureAbsolute=16 /**< Feature is manually controled but using absolute
                              values */
    };

    /**
     * Enumeration of encoding methods allowed by the IIDC standard of the IEEE
     * 1394.  Many of these constants are available for Format7 modes only,
     * i.e., if the camera supports scalable image sizes.
     *
     * Some of the following encoding methods are not supported by the LTI-Lib
     * yet, specially those with 16 bits.  Hence, the equivalent formats with
     * lower precision would be used instead.
     */
    enum eColorMode {
      Mono8 = 0, /**< Monochromatic with 8 bits (unsigned) per pixel */
      Mono16,    /**< Monochromatic with 16 bits (unsigned) per pixel */
      Mono16s,   /**< Monochromatic with 16 bits (signed) per pixel */
      YUV411,    /**< Yuv color space with 4:1:1 ratio */
      YUV422,    /**< Yuv color space with 4:2:2 ratio */
      YUV444,    /**< Yuv color space with 4:4:4 ratio */
      RGB8,      /**< RGB encoding with 8 bits per color channel */
      RGB16,     /**< RGB encoding with 16 bits (unsigned) per color channel */
      RGB16s,    /**< RGB encoding with 16 bits (signed) per color channel */
      Raw8,      /**< Raw data in 8 bits */
      Raw16,     /**< Raw data in 16 bits */
      UnknownEncoding   /**< Dummy value for an unknown encoding */
    };

    /**
     * The parameters for the class fireWireDCAM
     */
    class parameters : public frameGrabber::parameters {
    public:
 
      /**
       * Default constructor
       */
      parameters();

      /**
       * Copy constructor
       * @param other the parameters object to be copied
       */
      parameters(const parameters& other);

      /**
       * Destructor
       */
      ~parameters();

      /**
       * Returns name of this type
       */
      const char* getTypeName() const;

      /**
       * Copy the contents of a parameters object
       * @param other the parameters object to be copied
       * @return a reference to this parameters object
       */
      parameters& copy(const parameters& other);

      /**
       * Copy the contents of a parameters object
       * @param other the parameters object to be copied
       * @return a reference to this parameters object
       */
      parameters& operator=(const parameters& other);


      /**
       * Returns a pointer to a clone of the parameters
       */
      virtual functor::parameters* clone() const;

      /**
       * Write the parameters in the given ioHandler
       * @param handler the ioHandler to be used
       * @param complete if true (the default) the enclosing begin/end will
       *        be also written, otherwise only the data block will be written.
       * @return true if write was successful
       */
      virtual bool write(ioHandler& handler,const bool complete=true) const;

      /**
       * Read the parameters from the given ioHandler
       * @param handler the ioHandler to be used
       * @param complete if true (the default) the enclosing begin/end will
       *        be also written, otherwise only the data block will be written.
       * @return true if write was successful
       */
      virtual bool read(ioHandler& handler,const bool complete=true);

#     ifdef _LTI_MSC_6
      /**
       * This function is required by MSVC only, as a workaround for a
       * very awful bug, which exists since MSVC V.4.0, and still by
       * V.6.0 with all bugfixes (so called "service packs") remains
       * there...  This method is also public due to another bug, so please
       * NEVER EVER call this method directly: use read() instead
       */
      bool readMS(ioHandler& handler,const bool complete=true);

      /**
       * This function is required by MSVC only, as a workaround for a
       * very awful bug, which exists since MSVC V.4.0, and still by
       * V.6.0 with all bugfixes (so called "service packs") remains
       * there...  This method is also public due to another bug, so please
       * NEVER EVER call this method directly: use write() instead
       */
      bool writeMS(ioHandler& handler,const bool complete=true) const;
#     endif

      // ------------------------------------------------
      // the parameters
      // ------------------------------------------------

      /**
       * Indicate how to behave if invalid parameters are given.
       *
       * You can choose if you want your parameters to be taken exactly as they
       * are given, and if there is an invalid configuration to report an error
       * (NoFix).  You can also indicate that those invalid parameters should
       * be automatically modified to valid ones (AutoFix).  A third
       * possibility is to upload the configuration within the physical camera
       * exactly as they are, overwriting everything is given here.
       *
       * Default value: Upload
       */
      eFixMode fixMode;

      /**
       * Size of the image to be acquired.
       *
       * The standard IIDC establishes a finite set of valid resolutions for
       * IEEE1394 cameras, and groups them in so called \e formats.  These
       * formats have the following names:
       * 
       * - Format 0: VGA non compressed, for resolutions less than or equal
       *   to 640x480
       * - Format 1: SVGA non compressed, for resolutions greater than Format 0
       *   and less than or equal to 1024x768
       * - Format 2: SVGA non compressed, for resolutions greater than Format 1
       *   and less than or equal to 1600x1200
       * - Format 6: Still image
       * - Format 7: Scalable image size
       *
       * The set of accepted image sizes is
       *
       * - 160x120   (format 0)
       * - 320x240   (format 0)
       * - 640x480   (format 0)
       * - 800x600   (format 1)
       * - 1024x768  (format 1)
       * - 1280x960  (format 2)
       * - 1600x1200 (format 2)
       *
       * For each format, only a subset of valid pixel encodings are valid.
       * (see the documentation of attribute \c parameters::encoding for a
       * detailed list).
       *
       * Default: 640x480
       */
      ipoint resolution;

      /**
       * Pixel color encoding.
       *
       * Each resolution in IIDC standard supports only a subset of the
       * possible encodings and each camera usually supports just a subset of
       * those.
       * 
       * The following table summarizes the possible combinations of
       * resolutions and encodings (red means "not allowed", F# indicates 
       * the format #).
       *
       * <table align="center" frame="box" border=1>
       *   <tr>
       *     <td></td>
       *     <td>Mono8</td>
       *     <td>Mono16</td>
       *     <td>YUV411</td>
       *     <td>YUV422</td>
       *     <td>YUV444</td>
       *     <td>RGB8</td>
       *     <td>RGB16</td>
       *   </tr>
       *   <tr>
       *     <td>160x120</td>
       *     <td bgcolor="red"></td>
       *     <td bgcolor="red"></td>
       *     <td bgcolor="red"></td>
       *     <td bgcolor="red"></td>
       *     <td bgcolor="gray">F0</td>
       *     <td bgcolor="red"></td>
       *     <td bgcolor="red"></td>
       *   </tr>
       *   <tr>
       *     <td>320x240</td>
       *     <td bgcolor="red"></td>
       *     <td bgcolor="red"></td>
       *     <td bgcolor="red"></td>
       *     <td bgcolor="gray">F0</td>
       *     <td bgcolor="red"></td>
       *     <td bgcolor="red"></td>
       *     <td bgcolor="red"></td>
       *   </tr>
       *   <tr>
       *     <td>640x480</td>
       *     <td bgcolor="gray">F0</td>
       *     <td bgcolor="gray">F0</td>
       *     <td bgcolor="gray">F0</td>
       *     <td bgcolor="gray">F0</td>
       *     <td bgcolor="red"></td>
       *     <td bgcolor="gray">F0</td>
       *     <td bgcolor="red"></td>
       *   </tr>
       *   <tr>
       *     <td>800x600</td>
       *     <td bgcolor="darkGray">F1</td>
       *     <td bgcolor="darkGray">F1</td>
       *     <td bgcolor="red"></td>
       *     <td bgcolor="darkGray">F1</td>
       *     <td bgcolor="red"></td>
       *     <td bgcolor="darkGray">F1</td>
       *     <td bgcolor="red"></td>
       *   </tr>
       *   <tr>
       *     <td>1024x768</td>
       *     <td bgcolor="darkGray">F1</td>
       *     <td bgcolor="darkGray">F1</td>
       *     <td bgcolor="red"></td>
       *     <td bgcolor="darkGray">F1</td>
       *     <td bgcolor="red"></td>
       *     <td bgcolor="darkGray">F1</td>
       *     <td bgcolor="red"></td>
       *   </tr>
       *   <tr>
       *     <td>1280x960</td>
       *     <td bgcolor="lightGray">F2</td>
       *     <td bgcolor="lightGray">F2</td>
       *     <td bgcolor="red"></td>
       *     <td bgcolor="lightGray">F2</td>
       *     <td bgcolor="red"></td>
       *     <td bgcolor="lightGray">F2</td>
       *     <td bgcolor="red"></td>
       *   </tr>
       *   <tr>
       *     <td>1600x1200</td>
       *     <td bgcolor="lightGray">F2</td>
       *     <td bgcolor="lightGray">F2</td>
       *     <td bgcolor="red"></td>
       *     <td bgcolor="lightGray">F2</td>
       *     <td bgcolor="red"></td>
       *     <td bgcolor="lightGray">F2</td>
       *     <td bgcolor="red"></td>
       *   </tr>
       * </table>
       *
       * Default value: YUV422
       */
      eColorMode encoding;
      
      /**
       * Desired framerate.
       *
       * Only a finite set of framerates are allowed:
       *
       * - 1.875
       * - 3.75
       * - 7.5
       * - 15
       * - 30
       * - 60
       * - 120
       * - 240
       *
       * If you give another value then the nearest one will be used.
       * If the nearest value of the above list is not supported by the
       * current camera, then the behaviour will depend on \c autofix.
       * 
       * Default: 15
       */
      float framerate;
       
      /**
       * @name Camera features
       *
       * The following attributes give access to most of the features supported
       * by the libdc1394.
       *
       * Each particular camera usually support just a subset of these
       * features.  You can use the method
       * lti::fireWireDCAM::isFeatureAvailable() to check if a particular
       * feature is supported by your camera or not.
       *
       * The attributes with the word "State" control the "state" in which the
       * feature is to be used (see the IIDC 1.3x specifications for details,
       * which can be found at 
       *http://damien.douxchamps.net/ieee1394/libdc1394/iidc_specifications.php
       *
       * Not all cameras support all possible states of a particular feature.
       * You can use the method lti::fireWireDCAM::checkFeatureStates() to test
       * the camera support for the on-off, auto, manual, one-push and absolute
       * states.
       *
       * If a camera supports the one-push state, then the corresponding values
       * for the feature will be automatically adjusted exaclty once, just when
       * you set the parameters or update them.  Then the camera automatically
       * returns into the manual state.  You can use the dumpParameters()
       * method to obtain the adjusted values.
       *
       * Please note that the LTI-Lib uses float values for the features to
       * cover directly the values that a "absolute-setting capable" camera
       * would admit.
       *
       * The supported features of the IIDC specification are:
       * 
       * - FEATURE_BRIGHTNESS
       * - FEATURE_EXPOSURE
       * - FEATURE_SHARPNESS
       * - FEATURE_WHITE_BALANCE
       * - FEATURE_HUE
       * - FEATURE_SATURATION
       * - FEATURE_GAMMA
       * - FEATURE_SHUTTER
       * - FEATURE_GAIN
       * - FEATURE_IRIS
       * - FEATURE_FOCUS
       * - FEATURE_ZOOM
       * - FEATURE_PAN
       * - FEATURE_TILT
       *
       * The yet unsupported features are (patches to add support for these
       * missing features are always welcome).
       *
       * - FEATURE_TEMPERATURE
       * - FEATURE_TRIGGER
       * - FEATURE_TRIGGER_DELAY
       * - FEATURE_WHITE_SHADING
       * - FEATURE_FRAME_RATE
       * - FEATURE_OPTICAL_FILTER
       * - FEATURE_CAPTURE_SIZE
       * - FEATURE_CAPTURE_QUALITY
       */
      //@{

      /**
       * Brightness feature state.
       *
       * The brightness usually refers to an offset value that is added to the
       * CCD signal before the A/D conversion, and is used to remove residual
       * offsets in the signal chain.  Therefore, is is also known as "black
       * level".  You may check, however, which use is being assigned to this
       * feature in your camera.
       *
       * - FeatureOff: Brightness level will have a fixed value.
       * - FeatureAuto: Camera will control the brightness level automatically.
       * - FeatureManual: User sets the brightness level manually with the
       *                  attribute \c parameters::brightness
       * - FeatureOnePush: Brightness value is automatically set and then
       *                   returns to manual state.
       *
       * Default value: FeatureAuto
       */
      eFeatureState brightnessState;

      /**
       * Overall brightness.
       *
       * Default value: 0
       */
      float brightness;

      /**
       * Auto Exposure state
       *
       * - FeatureOff: Exposure will be manually controlled by gain, iris and 
       *               shutter features.
       * - FeatureAuto: reference level is automatically adjusted continuously.
       * - FeatureManual: exposure level automatically set, but the user 
       *                  selects the reference level in parameters::exposure
       * - FeatureOnePush: reference level is set once automatically and then
       *                   the state returns to manual.
       *
       * Default value: FeatureAuto
       */
      eFeatureState exposureState;
      
      /**
       * Auto exposure control.
       *
       * Reference level used for the auto exposure control
       *
       * Default value: 0
       */
      float exposure;

      /**
       * Sharpness control state.
       *
       * - FeatureOff: sharpness level will have a fixed value
       * - FeatureAuto: camera controls sharpness level automatically.
       * - FeatureManual: Sharpness level is set to the value in 
       *                  parameters::sharpness
       * - FeatureOnePush: sharpness level is set once automatically and then
       *                   the state returns to manual.
       *
       * Default value: FeatureAuto
       */
      eFeatureState sharpnessState;

      /**
       * Sharpness control value
       *
       * Default value: 0
       */
      float sharpness;

      /**
       * Automatic white balance.
       *
       * - FeatureOff: white balance will have fixed values.
       * - FeatureAuto: camera controls white balance automatically.
       * - FeatureManual: white balance will be manually controlled through
       *                  the values parameters::redGain and 
       *                  parameters::blueGain.
       * - FeatureOnePush: white balance is set once automatically and then
       *                   the state returns to manual.
       *
       * Default value: FeatureAuto
       */
      eFeatureState whiteBalanceState;

      /**
       * Gain applied to red (or V) components if the
       * parameters::whiteBalanceState requires it.
       *
       * Default value: 0
       */
      float redGain;

      /**
       * Gain applied to blue (or U) components if the
       * parameters::whiteBalanceState requires it.
       *
       * Default value: 0
       */
      float blueGain;

      /**
       * Hue control state
       *
       * - FeatureOff: hue control will have fixed values.
       * - FeatureAuto: camera controls hue automatically.
       * - FeatureManual: hue will be manually controlled through
       *                  the value parameters::hue.
       * - FeatureOnePush: hue is set once automatically and then
       *                   the state returns to manual.
       *
       * Default value: FeatureAuto
       */
      eFeatureState hueState;

      /**
       * Hue control value
       *
       * Controls color phase of the picture
       *
       * Default value: 0
       */
      float hue;

      /**
       * Saturation control state
       *
       * - FeatureOff: saturation control will have fixed values.
       * - FeatureAuto: camera controls saturation automatically.
       * - FeatureManual: saturation will be manually controlled through
       *                  the value parameters::saturation.
       * - FeatureOnePush: saturation is set once automatically and then
       *                   the state returns to manual.
       *
       * Default value: FeatureAuto
       */
      eFeatureState saturationState;

      /**
       * Saturation control value
       *
       * Controls color saturation of the picture
       *
       * Default value: 0
       */
      float saturation;

      /**
       * Gamma control state
       *
       * - FeatureOff: gamma control will have fixed values.
       * - FeatureAuto: camera controls gamma automatically.
       * - FeatureManual: gamma will be manually controlled through
       *                  the value parameters::gamma.
       * - FeatureOnePush: gamma is set once automatically and then
       *                   the state returns to manual.
       *
       * Default value: FeatureAuto
       */
      eFeatureState gammaState;

      /**
       * Gamma control value
       *
       * Controls gamma value used in the adjustment between incomming light
       * level and output picture level.
       *
       * Default value: 0
       */
      float gamma;

      /**
       * State for the shutter control.
       *
       * "Shutter" means the integration time of the incomming light.
       * 
       * - FeatureOff: integration time will have fixed values.
       * - FeatureAuto: camera controls shutter automatically.
       * - FeatureManual: shutter will be manually controlled through
       *                  the value parameters::shutter.
       * - FeatureOnePush: shutter is set once automatically and then
       *                   the state returns to manual.
       *
       * Default value: FeatureAuto
       */
      eFeatureState shutterState;

      /**
       * Integration time of the incomming light.
       *
       * Influences shutter speed of the camera, higher values
       * usually mean lower shutter speed.
       *
       * Default value: 0
       */
      float shutter;

      /**
       * State used for gain control.
       *
       * Gain is usually a factor used to multiply the CCD signal, modifying
       * the entire dynamic range.
       *
       * - FeatureOff: gain control will have fixed values.
       * - FeatureAuto: camera controls gain automatically.
       * - FeatureManual: gain will be manually controlled through
       *                  the value parameters::gain.
       * - FeatureOnePush: gain is set once automatically and then
       *                   the state returns to manual.
       *
       * Default value: FeatureAuto
       */
       eFeatureState gainState;

      /**
       * Gain of the camera, usually applied on all colors.
       *
       * Default: 0
       */
      float gain;

      /**
       * State used for mechanical iris control.
       *
       * - FeatureOff: iris control will have fixed values.
       * - FeatureAuto: camera controls iris automatically.
       * - FeatureManual: iris will be manually controlled through
       *                  the value parameters::iris.
       * - FeatureOnePush: iris is set once automatically and then
       *                   the state returns to manual.
       *
       * Default value: FeatureAuto
       */
      eFeatureState irisState;

      /**
       * Manually set value for the mechanical iris control.
       *
       * Default: 0
       */
      float iris;

      /**
       * State used for lens focus control.
       *
       * - FeatureOff: focus control will have fixed values.
       * - FeatureAuto: camera controls focus automatically.
       * - FeatureManual: focus will be manually controlled through
       *                  the value parameters::focus.
       * - FeatureOnePush: focus is set once automatically and then
       *                   the state returns to manual.
       *
       * Default value: FeatureAuto
       */
      eFeatureState focusState;

      /**
       * Value used for manual lens focus control.
       *
       * Default: 0
       */
      float focus;

      /**
       * State used for lens zoom control.
       *
       * - FeatureOff: zoom control will have fixed values.
       * - FeatureAuto: camera controls zoom automatically.
       * - FeatureManual: zoom will be manually controlled through
       *                  the value parameters::zoom.
       * - FeatureOnePush: zoom is set once automatically and then
       *                   the state returns to manual.
       *
       * Default value: FeatureAuto
       */
      eFeatureState zoomState;

      /**
       * Value used for manual lens zoom control.
       *
       * Default: 0
       */
      float zoom;

      /**
       * State used for lens pan control.
       *
       * - FeatureOff: pan control will have fixed values.
       * - FeatureAuto: camera controls pan automatically.
       * - FeatureManual: pan will be manually controlled through
       *                  the value parameters::pan.
       * - FeatureOnePush: pan is set once automatically and then
       *                   the state returns to manual.
       *
       * Default value: FeatureAuto
       */
      eFeatureState panState;

      /**
       * Value used for manual lens pan control.
       *
       * Default: 0
       */
      float pan;

      /**
       * State used for lens tilt control.
       *
       * - FeatureOff: tilt control will have fixed values.
       * - FeatureAuto: camera controls tilt automatically.
       * - FeatureManual: tilt will be manually controlled through
       *                  the value parameters::tilt.
       * - FeatureOnePush: tilt is set once automatically and then
       *                   the state returns to manual.
       *
       * Default value: FeatureAuto
       */
      eFeatureState tiltState;

      /**
       * Value used for manual lens tilt control.
       *
       * Default: 0
       */
      float tilt;
      //@}

      /**
       * @name One-Push related parameters.
       *
       * When you set a feature state in "FeatureOnePush", then the camera is
       * told to switch into a "one-push" state.  You can indicate with the
       * following attributes, first, if you want to wait for the camera to
       * automatically return to the manual control state; second, if you do
       * want to wait, then how often you want to check if the camera returned
       * from the "one-push" state, and for how long.
       */
      //@{
      /**
       * Wait for one-push state ready
       *
       * This indicates if you want to way for a one-push capable feature
       * to finish the automatic configuration.
       *
       * Default value: false;
       */
      bool waitOnePush;

      /**
       * Frequency (in Herz) of tests if the one-push features are ready.
       * 
       * Default value: 2 (twice a second)
       */
      float onePushUpdateRate;

      /**
       * Time-out for the one-push checks (in seconds)
       *
       * Default value: 10 (seconds)
       */
      float onePushTimeout;
     
      //@}


      /**
       * Whether one shot mode should be used.
       *
       * In oneShot mode the computer advises the camera to shot
       * one picture and transfer it to the computer. 
       * If oneShot is false, the camera will transfer pictures
       *
       * all the time, thus using a lot of fireWire bandwith.
       * The latter mode should be faster and recommended if high
       * framerates are desired.
       *
       * If the camera does not support the one shot mode, then
       * it will be assumed as if this value were set to false.
       *
       * Default: true
       */
      bool oneShot;

      /**
       * DMA buffer size in frames.
       *
       * For DMA access provided by the video1394 library, a buffer ring of the
       * given number of images is used.  This means, the higher this number,
       * the higher the latency of the read images (i.e. the time-shift between
       * the image provided by the apply method and the actual time in which
       * that image was taken is much higher), as it will be the given number
       * of frames in the past.
       * 
       * Default: 2
       */
      int dmaBufferSize;

      /**
       * Whether frames will be dropped to keep down latency.
       *
       * This indicates what to do if the ring buffer is full: should the
       * last image there be kept until read (false), or should the buffer
       * be overwritten with the incomming images.
       *
       * Default: true
       */
      bool dropFrames;

      /**
       * Device file for video capture.
       *
       * Default: "/dev/video1394/0"
       */
      std::string deviceFile;

      /**
       * Parameters for the Bayer pattern demosaicing method.
       *
       * Default values: NearestNeighbor and RGGB
       */      
      bayerDemosaicing::parameters bayerParameters;

      /**
       * Camera names file.
       *
       * To provide an easy way to identify your cameras, this functor manages
       * a very simple table of camera names associated with a 64bit number.
       * The table is stored in the file with the name given here.  You can
       * provide an absolute path with the file if you want a system-wide
       * name convention for your cameras.
       *
       * If a new camera has been detected, and the \c cameraName is not
       * in the current table, then a new line will be added with that name.
       * If the file is in use, then a name "Camera-x" will be added with "x" a
       * sequence number.
       *
       * The first camera in the file will always be the default one used.
       *
       * Please note that this is a class attribute (a static attribute), which
       * means that all instances share the same file, since it makes sense
       * that all cameras can be addressed using the same names.
       *
       * Default value: "cameras.txt"
       */
      static std::string cameraNamesFile;

      /**
       * Camera name.
       *
       * The camera with the given name in the cameraNamesFile will be used.
       * If the name has not yet been registered in the cameraNamesFiles, then
       * the first available camera will be taken and asigned this \c
       * cameraName, which can be later modified by hand in the corresponding
       * names file.
       *
       * Default value: "Default"
       */
      std::string cameraName;

    protected:
      /**
       * Write the name of the encoding method into a string
       */
      const char* encodingName(const eColorMode& code) const;
      /**
       * Convert the name of an encoding type to the corresponding
       * enum value.
       */
      const eColorMode getEncoding(const std::string& name) const;

      /**
       * Get a string for the fix mode
       */
      const char* fixModeName(const eFixMode& mode) const;

      /**
       * For the given string, return a valid fix mode 
       */
      const eFixMode getFixMode(const std::string& name) const;

    };

    /**
     * Default constructor
     *
     * You usually avoid using this constructor.  Using fireWireDCAM(const
     * parameters&) you can provide directly for which camera the constructed
     * instance should work.
     */
    fireWireDCAM();

    /**
     * Construct with the given parameters instance.
     *
     * You can give directly in the parameters object for which camera
     * the instance should be created, therefore this is the most used
     * constructor of this functor.
     */
    fireWireDCAM(const parameters& par);


    /**
     * Copy constructor
     * @param other the object to be copied
     */
    fireWireDCAM(const fireWireDCAM& other);

    /**
     * Destructor
     */
    virtual ~fireWireDCAM();

    /**
     * Returns the name of this type ("fireWireDCAM")
     */
    virtual const char* getTypeName() const;
    
    /**
     * Gets one frame from camera.
     * @param dest image the result will be left here.
     * @return true if apply successful or false otherwise. 
     */
    bool apply(image& dest);

    /**
     * Gets one frame from camera.
     * @param dest channel8 the result be left here.
     * @return true if apply successful or false otherwise.
     */
    bool apply(channel8& dest);


    /**
     * Grabs a raw frame from camera.
     * @param dest channle8 where the result will be left.
     * @return true if apply successful or false otherwise.
     */
    bool grabRaw(matrix<ubyte>& dest);

    /**
     * write parameters in camera
     */
    bool updateParameters();

    /**
     * @name Direct access to camera features.
     *
     * These methods access the camera registers directly, and they try to
     * update the internal parameters.  However, since the cameras may adjust
     * themselves, you may find the method fireWireDCAM::dumpParameters()
     * useful, which asks the camera for all parameters in use at once.
     *
     * If a feature supports the "one-push state", then the automatic
     * configuration will begin as soon as you call the corresponding method
     * with the value \c FeatureOnePush as state (for example
     * setWhiteBalance(FeatureOnePush) ).
     *
     * If you set the state of one or more features to one-push, then you may
     * want to wait for them to be ready with the method onePushWait().  Of
     * course, this will work if and only if the camera supports this feature
     * state.
     *
     * The methods to query information from the camera do indeed ask the
     * camera for the corresponding value (if and only if this is possible).
     * There are cameras which do not support the readout capability for the
     * registers holding the feature values.  In that case, the get* methods
     * will return \c false.
     */
    //@{

    /**
     * Set brightness control state and register in camera directly.
     *
     * @param state Camera desired state (@see eFeatureState)
     * @param brightness If state is manual, the value to be used.
     *
     * @return true if operation was successfull, false otherwise
     */
    bool setBrightness(const eFeatureState state,
                       const float brightness=0);

    /**
     * Get brightness state and value directly out of camera.
     *
     * @param state Variable where the current brightness state is to be 
     *              written.
     * @param brightness Variable where the brightness value is to be written.
     *
     * @return true if operation was successfull, false otherwise
     */ 
    bool getBrightness(eFeatureState& state,
                       float& brightness) const;

    /**
     * Set exposure control state and register in camera directly.
     *
     * @param state Camera desired state (@see eFeatureState)
     * @param exposure If state is manual, the value to be used.
     *
     * @return true if operation was successfull, false otherwise
     */
    bool setExposure(const eFeatureState state,
                     const float exposure=0);

    /**
     * Get exposure state and value directly out of camera.
     *
     * @param state Variable where the current exposure state is to be 
     *              written.
     * @param exposure Variable where the exposure value is to be written.
     *
     * @return true if operation was successfull, false otherwise
     */ 
    bool getExposure(eFeatureState& state,
                     float& exposure) const;

    /**
     * Set sharpness control state and register in camera directly.
     *
     * @param state Camera desired state (@see eFeatureState)
     * @param sharpness If state is manual, the value to be used.
     *
     * @return true if operation was successfull, false otherwise
     */
    bool setSharpness(const eFeatureState state,
                      const float sharpness=0);

    /**
     * Get sharpness state and value directly out of camera.
     *
     * @param state Variable where the current sharpness state is to be 
     *              written.
     * @param sharpness Variable where the sharpness value is to be written.
     *
     * @return true if operation was successfull, false otherwise
     */ 
    bool getSharpness(eFeatureState& state,
                      float& sharpness) const;

    /**
     * Set whiteBalance control state and register in camera directly.
     *
     * Depending on the color space used by the camera (RGB or YUV), the
     * color gains are applied to UV or to BR.
     *
     * @param state Camera desired state (@see eFeatureState)
     * @param ubGain gain for the blue channel (or U channel)
     * @param vrGain gain for the red channel (or V channel)
     *
     * @return true if operation was successfull, false otherwise
     */
    bool setWhiteBalance(const eFeatureState state,
                         const float ubGain=0,
                         const float vrGain=0);
    
    /**
     * Get whiteBalance state and value directly out of camera.
     *
     * @param state Variable where the current whiteBalance state is to be 
     *              written.
     * @param ubGain gain for the blue channel (or U channel)
     * @param vrGain gain for the red channel (or V channel)
     *
     * @return true if operation was successfull, false otherwise
     */ 
    bool getWhiteBalance(eFeatureState& state,
                         float& ubGain,
                         float& vrGain);

    /**
     * Set hue control state and register in camera directly.
     *
     * @param state Camera desired state (@see eFeatureState)
     * @param hue If state is manual, the value to be used.
     *
     * @return true if operation was successfull, false otherwise
     */
    bool setHue(const eFeatureState state,
                const float hue=0);

    /**
     * Get hue state and value directly out of camera.
     *
     * @param state Variable where the current hue state is to be 
     *              written.
     * @param hue Variable where the hue value is to be written.
     *
     * @return true if operation was successfull, false otherwise
     */ 
    bool getHue(eFeatureState& state,
                float& hue) const;

    /**
     * Set saturation control state and register in camera directly.
     *
     * @param state Camera desired state (@see eFeatureState)
     * @param saturation If state is manual, the value to be used.
     *
     * @return true if operation was successfull, false otherwise
     */
    bool setSaturation(const eFeatureState state,
                       const float saturation=0);

    /**
     * Get saturation state and value directly out of camera.
     *
     * @param state Variable where the current saturation state is to be 
     *              written.
     * @param saturation Variable where the saturation value is to be written.
     *
     * @return true if operation was successfull, false otherwise
     */ 
    bool getSaturation(eFeatureState& state,
                       float& saturation) const;
    
    /**
     * Set gamma control state and register in camera directly.
     *
     * @param state Camera desired state (@see eFeatureState)
     * @param gamma If state is manual, the value to be used.
     *
     * @return true if operation was successfull, false otherwise
     */
    bool setGamma(const eFeatureState state,
                  const float gamma=0);

    /**
     * Get gamma state and value directly out of camera.
     *
     * @param state Variable where the current gamma state is to be 
     *              written.
     * @param gamma Variable where the gamma value is to be written.
     *
     * @return true if operation was successfull, false otherwise
     */ 
    bool getGamma(eFeatureState& state,
                  float& gamma) const;

    /**
     * Set shutter control state and register in camera directly.
     *
     * @param state Camera desired state (@see eFeatureState)
     * @param shutter If state is manual, the value to be used.
     *
     * @return true if operation was successfull, false otherwise
     */
    bool setShutter(const eFeatureState state,
                    const float shutter=0);

    /**
     * Get shutter state and value directly out of camera.
     *
     * @param state Variable where the current shutter state is to be 
     *              written.
     * @param shutter Variable where the shutter value is to be written.
     *
     * @return true if operation was successfull, false otherwise
     */ 
    bool getShutter(eFeatureState& state,
                    float& shutter) const;

    /**
     * Set gain control state and register in camera directly.
     *
     * @param state Camera desired state (@see eFeatureState)
     * @param gain If state is manual, the value to be used.
     *
     * @return true if operation was successfull, false otherwise
     */
    bool setGain(const eFeatureState state,
                 const float gain=0);

    /**
     * Get gain state and value directly out of camera.
     *
     * @param state Variable where the current gain state is to be 
     *              written.
     * @param gain Variable where the gain value is to be written.
     *
     * @return true if operation was successfull, false otherwise
     */ 
    bool getGain(eFeatureState& state,
                 float& gain) const;

    /**
     * Set iris control state and register in camera directly.
     *
     * @param state Camera desired state (@see eFeatureState)
     * @param iris If state is manual, the value to be used.
     *
     * @return true if operation was successfull, false otherwise
     */
    bool setIris(const eFeatureState state,
                 const float iris=0);

    /**
     * Get iris state and value directly out of camera.
     *
     * @param state Variable where the current iris state is to be 
     *              written.
     * @param iris Variable where the iris value is to be written.
     *
     * @return true if operation was successfull, false otherwise
     */ 
    bool getIris(eFeatureState& state,
                 float& iris) const;

    /**
     * Set focus control state and register in camera directly.
     *
     * @param state Camera desired state (@see eFeatureState)
     * @param focus If state is manual, the value to be used.
     *
     * @return true if operation was successfull, false otherwise
     */
    bool setFocus(const eFeatureState state,
                  const float focus=0);

    /**
     * Get focus state and value directly out of camera.
     *
     * @param state Variable where the current focus state is to be 
     *              written.
     * @param focus Variable where the focus value is to be written.
     *
     * @return true if operation was successfull, false otherwise
     */ 
    bool getFocus(eFeatureState& state,
                  float& focus) const;

    /**
     * Set zoom control state and register in camera directly.
     *
     * @param state Camera desired state (@see eFeatureState)
     * @param zoom If state is manual, the value to be used.
     *
     * @return true if operation was successfull, false otherwise
     */
    bool setZoom(const eFeatureState state,
                 const float zoom=0);

    /**
     * Get zoom state and value directly out of camera.
     *
     * @param state Variable where the current zoom state is to be 
     *              written.
     * @param zoom Variable where the zoom value is to be written.
     *
     * @return true if operation was successfull, false otherwise
     */ 
    bool getZoom(eFeatureState& state,
                 float& zoom) const;

    /**
     * Set pan control state and register in camera directly.
     *
     * @param state Camera desired state (@see eFeatureState)
     * @param pan If state is manual, the value to be used.
     *
     * @return true if operation was successfull, false otherwise
     */
    bool setPan(const eFeatureState state,
                const float pan=0);

    /**
     * Get pan state and value directly out of camera.
     *
     * @param state Variable where the current pan state is to be 
     *              written.
     * @param pan Variable where the pan value is to be written.
     *
     * @return true if operation was successfull, false otherwise
     */ 
    bool getPan(eFeatureState& state,
                float& pan) const;

    /**
     * Set tilt control state and register in camera directly.
     *
     * @param state Camera desired state (@see eFeatureState)
     * @param tilt If state is manual, the value to be used.
     *
     * @return true if operation was successfull, false otherwise
     */
    bool setTilt(const eFeatureState state,
                 const float tilt=0);

    /**
     * Get tilt state and value directly out of camera.
     *
     * @param state Variable where the current tilt state is to be 
     *              written.
     * @param tilt Variable where the tilt value is to be written.
     *
     * @return true if operation was successfull, false otherwise
     */ 
    bool getTilt(eFeatureState& state,
                 float& tilt) const;

    //@}
    
    /**
     * Get current video mode directly out of camera.
     *
     * The IIDC enum value read from the camera is decoded into a
     * resolution and a pixel encoding value.
     *
     * \param resolution ipoint with the image resolution.
     * \param encoding encoding type of each pixel (YUV422, RGB, etc.)
     *
     * @return true if operation was successfull, false otherwise
     */ 
    bool getVideoMode(ipoint& resolution,eColorMode& encoding) const;

    /**
     * Get current frame rate directly out of camera.
     * @return true if operation was successfull, false otherwise
     */
    bool getFramerate(float& framerate) const;

    /**
     * Initializes the IEEE Bus and checks for available cameras.
     *
     * This method will be called automatically, when necessary.  Hence,
     * you do not need to worry about it.
     *
     * @return true if operation was successfull, false otherwise
     */
    bool init();

    /**
     * Member function that prints informations about camera features on
     * stdout.
     * @return true if operation was successfull, false otherwise
     */
    bool printFeatures() const;

    /**
     * Read the actual hardware settings of the \b active camera and leave them
     * into the given parameter instance.
     *
     * @param par the parameters instance on which the gained information
     * will be stored.
     *
     * @return true if operation was successfull, false otherwise (for
     * instance, if there is no active camera to be read)
     */
    bool dumpParameters(parameters &par);

    /**
     * Copy data of "other" functor.
     * @param other the functor to be copied
     * @return a reference to this functor object
     */
    fireWireDCAM& copy(const fireWireDCAM& other);

    /**
     * Alias for copy member
     * @param other the functor to be copied
     * @return a reference to this functor object
     */
    fireWireDCAM& operator=(const fireWireDCAM& other);

    /**
     * Returns a pointer to a clone of this functor.
     */
    virtual functor* clone() const;

    /**
     * Returns used parameters
     */
    const parameters& getParameters() const;

    /**
     * \name Access to internal data structures
     *
     * The following methods can be found useful by GUI programmers who want
     * to ask for availability of several features in order to set-up properly
     * GUI elements.
     */
    //@{
    /**
     * Check if a camera has been activated for this functor.
     *
     * @return true if a camera has been successfully activated, or false
     * otherwise.
     */
    bool isCameraActive() const;

    /**
     * Check if the active camera supports format 7
     */
    bool hasCameraFormat7() const;

    /**
     * Check if a particular feature is available in the current active
     * camera.
     *
     * You have to ensure that a camera is already active (see
     * isCameraActive()).
     *
     * \param featureId The identification of the feature expects one of the
     *                  following values, defined in the libdc1394:
     *                  - FEATURE_BRIGHTNESS
     *                  - FEATURE_EXPOSURE
     *                  - FEATURE_SHARPNESS
     *                  - FEATURE_WHITE_BALANCE
     *                  - FEATURE_HUE
     *                  - FEATURE_SATURATION
     *                  - FEATURE_GAMMA
     *                  - FEATURE_SHUTTER
     *                  - FEATURE_GAIN
     *                  - FEATURE_IRIS
     *                  - FEATURE_FOCUS
     *                  - FEATURE_TEMPERATURE
     *                  - FEATURE_TRIGGER
     *                  - FEATURE_TRIGGER_DELAY
     *                  - FEATURE_WHITE_SHADING
     *                  - FEATURE_FRAME_RATE
     *                  - FEATURE_ZOOM
     *                  - FEATURE_PAN
     *                  - FEATURE_TILT
     *                  - FEATURE_OPTICAL_FILTER
     *                  - FEATURE_CAPTURE_SIZE
     *                  - FEATURE_CAPTURE_QUALITY
     */
    bool isFeatureAvailable(const unsigned int featureId) const;

    /**
     * Check if a feature is available and is read-out capable.
     *
     * \param featureId identification for the feature to be queried.
     *                  (see fireWireDCAM::isFeatureAvailable() for a list of
     *                   valid values)
     * \return \c true if feature is read-out capable or \c false if it is not
     *         available at all, or if it is not readable.
     */
    bool isFeatureReadable(const unsigned int featureId) const;

    /**
     * Check for availability of feature states
     *
     * Following the IIDC 1.3x standard, a given feature (see the list of
     * valid identifiers in lti::fireWireDCAM::isFeatureAvailable() ) can
     * have one of four states:
     * - Off state: the feature is deactivated (some features cannot be
     *              deactivated).
     * - Auto state: the feature is automatically adjusted
     * - Manual state: the user controls the values a feature can get
     * - One-Push state: the feature is automatically adjusted but only once.
     *
     * This method asks the active camera which states are supported and
     * returns a bitwise combination of fireWireDCAM::eFeatureState constants.
     *
     * You have to ensure that a camera is active (see
     * fireWireDCAM::isCameraActive()).
     *
     * \param featureId identification for the feature to be modified
     *                  (see fireWireDCAM::isFeatureAvailable() for a list of
     *                   valid values)
     *
     */
    unsigned int checkFeatureStates(const unsigned int featureId) const;

    /**
     * Get feature state of the camera
     *
     * @return \c true if feature state could be successfully read, or \c false
     *         if this was not possible (maybe the camera does not support
     *         the given feature at all).
     */
    bool getFeatureState(const unsigned int featureId,
                         eFeatureState& state) const;

    /**
     * Set feature state of the camera
     *
     * @return \c true if feature state could be successfully set, or \c false
     *         if this was not possible (maybe the camera does not support
     *         the given state for the feature.
     */
    bool setFeatureState(const unsigned int featureId,
                         const eFeatureState state);

    /**
     * Set control state and value of a particular feature.
     *
     * This method does not support those features that require two values,
     * like white balance.
     *
     * This private method does not modify the internal parameters.
     *
     * @param featureId identification for the feature to be modified
     *                  (see fireWireDCAM::isFeatureAvailable() for a list of
     *                   valid values)
     * @param state Camera desired state (@see eFeatureState)
     * @param value If state is manual, the value to be used.
     *
     * @return true if operation was successfull, false otherwise
     */
    inline bool setFeatureValue(const unsigned int featureId,
                                const eFeatureState state,
                                const float value=0);
    
    /**
     * Get control state and value of a particular feature.
     *
     * This method does not support those features that require two values,
     * like white balance.
     *
     * @param featureId identification for the feature to be queried.
     * @param state State in which the feature is being used
     * @param value if state is manual, the value to be used.
     *
     * @return \c true if operation was successfull, \c false otherwise (for
     *         example, if the feature is not supported by the camera).
     */
    inline bool getFeatureValue(const unsigned int featureId,
                                eFeatureState& state,
                                float& value) const;

    /**
     * Check the valid value range for a specified feature.
     *
     * You have to ensure that there is an active camera before calling this
     * method. (see fireWireDCAM::isCameraActive() )
     *
     * @param featureId identification for the feature to be modified
     *                  (see fireWireDCAM::isFeatureAvailable() for a list of
     *                   valid values)
     * @param minValue minimum value accepted for the specified feature.
     * @param maxValue maximum value accepted for the specified feature.
     *
     * @return \c true if successful or \c false otherwise.
     */
    bool checkFeatureValueRange(const unsigned int featureId,
                                int& minValue,
                                int& maxValue) const;
    //@}

  protected:
    /**
     * Returns modifieable parameters
     */
    parameters& getRWParameters();

    /**
     * For a bitwise combination of available states and a desired state,
     * return a valid supported state.
     */
    eFeatureState fixState(const unsigned int states,
                           const eFeatureState desired) const;

    void fixFeature(const unsigned int featureId,
                    float& value,
                    eFeatureState& state) const;
      /**
     * Analyse the given parameters instance and change its attributes to
     * contain values supported by the active camera.
     *
     * This method will work only if the camera of the given parameters is
     * connected and found.  Otherwise there will be no way to determine
     * which values are appropriate for the camera.
     */
    bool fixParameters(parameters& par) const;

    /**
     * Get the closest framerate of the libdc1394 set of enums to the
     * given framerate value coded in a float of fps.
     *
     * This method does not consider the camera supported framerates, but
     * the simple convertion.
     */
    unsigned int convertFramerate(const float fps) const;

    /**
     * Get the float value in fps equivalent to the framerate enum value
     * of the libdc1394
     */ 
    float convertFramerate(const unsigned int eFR) const;

    /**
     * Get "nearest" IIDC mode value from the given resolution and encoding.
     * 
     * As "nearest" it will be taken the resolution with the
     * most similar number of pixels and within that resolution, the "nearest"
     * encoding will be chosen (RGBs are in a group, Mono in another and YUV
     * in another.
     * 
     */
    unsigned int convertMode(const ipoint& resolution,
                             const eColorMode& encoding) const;

    /**
     * From the given value for format/mode after IIDC encoding, get
     * the equivalent resolution and pixel encoding.
     */
    void convertMode(const unsigned int value,
                     ipoint& resolution,
                     eColorMode& encoding) const;

    /**
     * For a mode of the formats 0, 1 or 2, indicate if it is a color
     * mode.
     * 
     * @return \c true if the mode is a color mode (RGB or YUV), or \c false
     *         if the mode is monochrome.
     */
    bool isModeColor(const unsigned int mode) const;
 
    /**
     * Compute the closest supported mode to a given IIDC valid mode.
     *
     * the approximation is done with the following priorities:
     *  
     * -# keep the mono or color attribute (unless your camera is
     *    monochrome, of course)
     * -# select the closest resolution.
     */
    unsigned int computeClosestMode(const unsigned int mode) const;

    /**
     * Compute the closest supported framerate for a given mode
     */
    float computeClosestFrameRate(const unsigned int mode,
                                  const float fr) const;

    /**
     * From the given value for format7/mode after IIDC encoding, get
     * the equivalent resolution and pixel encoding.
     *
     * This method ask only for format 7 resolutions and encodings.  For this
     * task it has to ask the camera for that information.
     *
     * The resolution returned will be the largest the camera supports.
     */
    void convertMode7(const unsigned int value,
                     ipoint& resolution,
                     eColorMode& encoding) const;

    /**
     * Get a functor valid code for a color space given in the libdc1394
     * enumeration for a Format7 color code.
     */
    eColorMode getColorCode7(const unsigned int code) const;

    /**
     * Get the corresponding format for the given resolution
     */
    unsigned int getFormat(const ipoint& resolution) const;


    /**
     * converts YUV411 to RGB
     */
    void yuv411toRGB(image& srcdest) const;

    /**
     * converts YUV422 to RGB
     */
    void yuv422toRGB(image& srcdest) const;

    /**
     * Check if a specific feature is set to "auto"
     *
     * See lti::fireWireDCAM::isFeatureAvailable() for a list of the valid
     * \c featureId and their meanings.
     *
     * \param featureId identification for the feature to be modified
     *                  (see fireWireDCAM::isFeatureAvailable() for a list of
     *                   valid values)
     *
     * @return \c true if the feature is set to "auto" or false otherwise.
     */
    bool isFeatureAuto(const unsigned int featureId) const;

    /**
     * Set a feature to "auto"
     *
     * @param featureId identification for the feature to be modified
     *                  (see fireWireDCAM::isFeatureAvailable() for a list of
     *                   valid values)
     * @param on (default true) if \c true, the auto state is activated.
     *              If \c false, the auto state is turned off.
     */
    bool setFeatureAuto(const unsigned int featureId, 
                        const bool on=true) const;

    /**
     * Turn a feature on or off.
     *
     * @param featureId identification for the feature to be modified
     *                  (see fireWireDCAM::isFeatureAvailable() for a list of
     *                   valid values)
     * @param on if \c true the feature is turned on, if \c false then it is
     *           turned off
     *
     * @return \c true if feature state could be modified, of false otherwise.
     */
    bool setFeatureOn(const unsigned int featureId,
                      const bool on=true);

    /**
     * Turn a feature absolute state on or off
     *
     * @param featureId identification for the feature to be modified
     *                  (see fireWireDCAM::isFeatureAvailable() for a list of
     *                   valid values)
     * @param on if \c true the absolute mode is turned on, if \c false then 
     *           it is turned off
     *
     * @return \c true if feature state could be modified, of false otherwise.
     */
    bool setFeatureAbsoluteState(const unsigned int featureId,
                                 const bool on=true);

    /**
     * Just capture a frame through libdc1394
     */
    bool captureFrame();

    /**
     * @name Initialization methods and attributes for the library libdc1394
     *
     * The following methods are used in the initialization of the IEEE1394 bus
     * and cameras.  They are inspired on the code of "coriander"
     * (http://damien.douxchamps.net/ieee1394/coriander/index.php)
     */
    //@{

    /**
     * IEEE 1394 Bus Information Class
     */
    class busInfo {
    public:
      /** 
       * Default constructor
       *
       * Initializes everything with NULL o zero
       */
      busInfo();

      /**
       * Destructor
       *
       * Takes care of deallocation
       */
      ~busInfo();
      
      /**
       * Array of bus handles (type declared in file libraw1394/raw1394.h).
       *
       * The number of elements in the array is given by portNum.
       */
      raw1394handle_t *handles;
      
      /**
       * Nodes
       *
       * Array of pointers to nodeid_t structures.  This array will
       * have portNum number of elements.
       */
      nodeid_t **cameraNodes;

      /**
       * Total camera number (should be the sum of all elements in the
       * portCameraNum array.
       */
      int cameraNum;

      /**
       * Array with the number of cameras for each port.
       *
       * The number of elements of this array is given by portNum.
       */
      int *portCameraNum;
      
      /**
       * Port number
       *
       * Number of ports available.  The portCameraNum and cameraNodes
       * attributes are arrays with this number of elements.
       */
      int portNum;

      /**
       * Flag to indicate if a camera was found.
       */
      bool cardFound;

      /**
       * Fill the structure with information about the bus, nodes and cameras
       */
      bool get();

      /**
       * Get camera nodes.
       *
       * Returns false if no card could be found (which also sets the
       * attribute cardFound to false
       */
      bool getNodes();

    protected:
      /**
       * Delete the camera nodes.
       *
       * \returns false if nothing was deleted or true otherwise.
       */
      bool deleteCameraNodes();

      /**
       * Bus reset handler
       *
       * TODO: we have to decide what is to be done when the cameras are
       * life plugged/unplugged!
       */
      static int busResetHandler(raw1394handle_t handle,
                                 unsigned int generation);
    };

    /**
     * Structure to hold format 7 mode information
     *
     * This structure will be replicated in an array, of which each
     * component will hold information about one particular format7 mode
     * (there are at this time only 8 available).
     */
    struct format7ModeInfo {
      /**
       * Corresponding format7 mode is available
       */
      bool present;
      
      /**
       * Current image size in use.
       */
      uipoint size;

      /**
       * Maximum image size.
       */
      uipoint maxSize;

      /**
       * Position of subimage in the total CCD image size.
       */
      uipoint pos;
      
      /**
       * Unit size
       */
      uipoint unitSize;

      /**
       * Unit position
       */
      uipoint unitPos;
      
      /**
       * ID number of the color coding
       */
      unsigned int colorCodingId;

      /**
       * Bitwise combination of color coding modes supported.
       */
      quadlet_t colorCoding;
      
      /**
       * Number of pixels
       */
      unsigned int pixnum;
      
      /**
       * Number of bytes per packet
       */
      unsigned int bpp; // bpp is byte_per_packet

      /**
       * Minimum number of bytes per packet
       */
      unsigned int minBpp;

      /**
       * Maximum number of bytes per packet.
       */
      unsigned int maxBpp;
      
      /**
       * Total number of bytes
       */
      uint64 totalBytes;
    };

    /**
     * Structure to hold format 7 information
     */
    struct format7Info {
      /**
       * Flag to indicate if the format7 is available at all.
       */
      bool available;

      /**
       * Array of structures representing each of the format7 modes.
       */
      format7ModeInfo mode[NUM_MODE_FORMAT7];
    };

    /**
     * The camera information class
     *
     * For each camera detected in the bus a set of information is extracted
     * which is encapsulated in objects of this type.
     */
    class cameraInfo {
    public:
      /**
       * Default constructor
       */
      cameraInfo();

      /**
       * Destructor
       */
      ~cameraInfo();

      /**
       * Information about the camera
       */
      dc1394_camerainfo info;
      
      /**
       * Set of features of the current camera
       */
      dc1394_feature_set featureSet;

      /**
       * Other information
       */
      dc1394_miscinfo miscInfo;

      /**
       * Information about format 7
       */
      format7Info format7;

      /**
       * Basic functionality of the camera
       *
       * This includes most importantly three features:
       * - Bit 16: camera process power ON/OFF capability
       * - Bit 19: one shot transmission capability
       * - Bit 20: multishot transmission capability
       */
      quadlet_t basics;

      /**
       * Flag to indicate if this camera is already being used by an instance
       */
      bool inUse;
      
      /**
       * Error string
       */
      std::string errorStr;

      /**
       * Store the modes supported.
       *
       * This information is generated when get() is called.
       */
      std::set<uint32> supportedModes;

      /**
       * Store the framerates supported for each supported mode.
       *
       * The map key is a given mode, using the IIDC value for them, and the
       * value for that key is a set containing the framerates supported.
       *
       * This information is generated when get() is called.
       */
      std::map<uint32,std::set<float> > supportedFramerates;

      /**
       * Get camera information from the given port and node.
       *
       * \return true if successful or false if an error occurred,
       *          in which case the errorStr will contain an appropriate
       *          message.
       */
      bool get(const int port,const nodeid_t& node);

    protected:
      /**
       * Get information about the format 7 capabilities
       */
      bool getFormat7Capabilities();

      /**
       * Get information on a specific format7 mode
       *
       * @param format Format code, which should lie between MODE_FORMAT7_MIN
       *               and MODE_FORMAT7_MAX (usually from MODE_FORMAT7_0 to
       *               MODE_FORMAT7_7).
       */
      bool getFormat7ModeInfo(const unsigned int format);

      /**
       * Get information on the supported modes.
       *
       * \return true if successful or false otherwise
       */
      bool getSupportedModesAndFramerates(const nodeid_t& node);
    };

    /**
     * Set of cameras
     * 
     * This class represents the set of all available cameras
     */
    class cameraSet {
    public:
      /**
       * Default constructor
       */
      cameraSet();

      /**
       * Default destructor
       */
      ~cameraSet();
      
      /**
       * Get the information block of the camera identified with the given
       * index.
       */
      const cameraInfo& operator[](const int idx) const;

      /**
       * Get the information block of the camera identified with the given
       * index.
       */
      cameraInfo& operator[](const int idx);

      /**
       * Return the total number of cameras found
       */
      unsigned int size() const;

      /**
       * Evaluate the given bus and create all the necessary objects to
       * obtain and retain the information of all available cameras.
       */
      bool get(busInfo& bus);

      /**
       * Try to find a camera within the set with the given identification.
       * 
       * @param euID64 is the identification number used by the libdc1394 
       * @param camIdx if the id is found, this will contain the index to
       *               access the camera with the given id, otherwise it
       *               will be set to -1.
       *
       * \returns \c true if the camera is found, or false if not.
       */
      bool findCamera(const u_int64_t& euID64,
                      int& camIdx) const;

      /**
       * This method finds the first available camera.
       */
      bool findFreeCamera(int& camIdx) const;

      /**
       * Mark the camera with the given index as being in use.
       *
       * Only one instance of this functor can use a particular camera at
       * a time.
       */
      bool reserveIndex(const int idx);

      /**
       * Mark the camera with the given index as free to be used by other
       * instances.
       *
       */
      bool releaseIndex(const int idx);
                             
      /**
       * Error string
       */
      std::string errorStr;

    protected:
      /**
       * Camera array
       */
      std::vector<cameraInfo> cams_;

      /**
       * Protect the camera array
       */
      mutable mutex lock_;

    };
    //@}

    /**
     * Camera database
     *
     * Just one instance of this class is used to manage the names of
     * the available cameras.
     */
    class nameDB {
    public:
      /**
       * Default constructor 
       *
       * Does nothing
       */
      nameDB();

      /**
       * Default destructor
       *
       * Saves all new data acquired in the file indicated by the use() method.
       */
      ~nameDB();

      /**
       * Use the given file to serialize the data
       *
       * \returns \c true if the file can be successfully open and read, or
       * if it does not exist, if it can be successfully created.
       */
      bool use(const std::string& filename);

      /**
       * Query a camera id through a camera name.
       *
       * \returns \c true if the name could be found, in which case id will 
       *          contain the proper data.  \c false if the name could not
       *          be found.
       */
      bool query(const std::string& name,u_int64_t& id) const;

      /**
       * Add a name,id pair.
       *
       * \returns \c true if the pair could be successfully added or \c false
       * if there was a problem (usually, the name already existed!
       */
      bool add(const std::string& name,u_int64_t& id);

      /**
       * Delete an entry with the given name as key
       *
       * \returns \c true if the entry was removed or \c false if some problem
       * occured, for instance, the entry didn't exist.
       */
      bool del(const std::string& name);
      
    protected:
      /**
       * Map names to the identification numbers of cameras
       */
      std::map<std::string,u_int64_t> data_;

      /**
       * Filename in use (given by use() method)
       */
      std::string filename_;

      /**
       * Protect data
       */
      mutable mutex lock_;

      /**
       * Dump the data_ into the file with the name filename_.
       *
       * This does not lock!  Do it outside the method.
       *
       * \returns \c true if the file could be dumped or \c false if an error
       * occurred (like no use() called before)
       */
      bool dump();

      /**
       * Read the data_ from the file with the name \c filename.
       *
       * This does not lock!  Do it outside the method.
       *
       * \returns \c true if the file could be read or \c false if an error
       * occurred (like no use() called before)
       */
      bool read(const std::string& filename);

      /**
       * Convert a 64 integer into a hex chain
       *
       * Since not all compilers behave the same with 64 bit chains, we
       * better take charge ourselves of converting them into a chain of 16
       * nibbles preceded by 0x.
       */
      void hexToString(const u_int64_t& data,
                       std::string& str) const;

      /**
       * Convert a 16 nibble string into a u_int64_t value
       *
       * The string has to begin with "0x" and continue with a number
       * of less or exactly 16 hex digits
       */
      bool stringToHex(const std::string& str,
                       u_int64_t& data) const;

      /**
       * The file has to be read just once!
       *
       * This flag stores if it was read or not
       */
      bool init_;

      /**
       * Flag to indicate if the database has been modified since the last
       * read.
       */
      bool modified_;

    };


    /**
     * @name Hardware singletons
     *
     * The following attributes represent the IEEE 1394 bus and all
     * available cameras.
     */
    //@{
    /**
     * Flag set to true if the bus and camera set were already initialized or
     * false otherwise.
     */
    static bool hwCreated_;

    /**
     * The one and only instance for the IEEE1394 bus.
     */
    static busInfo bus_;

    /**
     * The camera set attached to the IEEE1394 bus found.
     */
    static cameraSet cams_;

    /**
     * The camera names database
     */
    static nameDB cameraNames_;

    /**
     * Initialize the hardware
     */
    bool initHardware();

    /**
     * Initialize the current camera
     */
    bool initCamera(const parameters& par);
    //@}

    /**
     * Store the index for cams_ of the camera represented by this instance
     *
     * If activeCamera_ is less than zero then it indicates that this functor
     * has not initialized its camera yet.
     */
    int activeCamera_;

    /**
     * Active camera name
     *
     * The index in activeCamera_ corresponds to the a camera with 
     * the name activeCameraName_, which is used to decide if setParameters
     * is telling this functor to change the camera being used.
     */
    std::string activeCameraName_;

    /**
     * Release the active camera.
     *
     * This allow that another instance can take control of this camera.
     */
    bool releaseCamera();

    /**
     * @name Shadow and pointers for active camera attributes
     *
     * This shadows are set in updateParameters()
     */
    //@{

    /**
     * Shadow value of current in use camera to indicate that it is capable of
     * oneShot capture.
     *
     * This is a shadow of cams_[activeCamera_].miscInfo.one_shot_capable;
     */
    bool oneShotCapable_;

    /**
     * FireWire handle for low level communication
     *
     * This is a pointer to cams_[activeCamera_].info.handle
     */
    const raw1394handle_t* handle_;

    /**
     * Saves what features are available.
     *
     * This is a pointer to cams_[activeCamera_].featureSet
     */
    const dc1394_feature_set* features_;

    /**
     * Shadow of the node id.
     *
     * This is a pointer to cams_[activeCamera_].info.id
     */
    const nodeid_t* node_;

    /**
     * FireWire channel used for the camera
     */
    unsigned int busChannel_;

    /**
     * FireWire bus speed used
     */
    unsigned int busSpeed_;

    /**
     * Flag to indicate if the ISO transmision has been started
     */
    bool isoTransStarted_;

    //@}

    /**
     * Colormode used for conversion to rgb image 
     */
    eColorMode colorMode_;

    /**
     * Just a buffer channel8
     */
    channel8 ch8_;

    /**
     * Capture handle with the camera node, buffer etc.
     */
    dc1394_cameracapture camera_;

    /**
     * If a setup capture succeeded
     */
    bool setupCapture_;

    /**
     * merger for YUV to RGB conversion
     */
    mergeYCbCrToImage merger_;

    /**
     * demosaicing functor for Mono to RGB conversion
     */
    bayerDemosaicing bayer_;

    /**
     * @name One-Push Wait Scheduler
     *
     * The following methods provide a very basic scheduler for
     * check of the successful automatic adjustment of features in the
     * one push mode
     */
    //@{

    /**
     * Feature list in waiting process
     */
    std::set<unsigned int> waitingFeatures_;

    /**
     * Protect the queue from multiple access.
     */
    mutex onePushLock_;

    /**
     * Insert the given feature into the waiting queue.
     * @param featureId identification of the feature that want to wait for
     *                  leaving the one-push state.
     * @return \c true if feature could be inserted or \c false if it was
     *         something wrong (not supported, or a real error).
     */
    bool onePushQueueInsert(const unsigned int featureId);

  public:
    /**
     * Wait until all features in the waiting queue have left the queue.
     *
     * @return \c true if all features left the one-push state on a time
     *         less than the time-out, or false otherwise.
     */
    bool onePushWait();
    
    //@}
  };

  /**
   * Read function for fireWireDCAM::eFeatureState type
   *
   * @ingroup gStorable
   */
  bool read(ioHandler& handler, fireWireDCAM::eFeatureState& data);

  /**
   * Write function for fireWireDCAM::eFeatureState type
   *
   * @ingroup gStorable
   */
  bool write(ioHandler& handler, const fireWireDCAM::eFeatureState& data);

}

#endif

#endif