tao-cameras.h

/*
 * tao-cameras.h --
 *
 * Definitions and API for cameras in TAO.
 *
 *-----------------------------------------------------------------------------
 *
 * This file if part of TAO real-time software licensed under the MIT license
 * (https://git-cral.univ-lyon1.fr/tao/tao-rt).
 *
 * Copyright (C) 2019-2021, Éric Thiébaut.
 */

#ifndef _TAO_CAMERAS_H_
#define _TAO_CAMERAS_H_ 1

#include <limits.h>
#include <tao-shared.h>
#include <tao-options.h>

_TAO_BEGIN_DECLS

/**
 * @addtogroup Cameras
 *
 * There are several kinds of objects to manage cameras in TAO:
 *
 * - `tao_framegrabber_t` emulates a virtual frame grabber.
 *
 * - `tao_camera_t` provides a unified interface to a camera device.
 *
 * - `tao_shared_camera_t` stores the current state of a camera in shared
 *   memory.
 *
 * @{
 */

/*---------------------------------------------------------------------------*/
/* COMMON TYPES AND METHODS */

/**
 * @addtogroup CamerasCommon
 *
 * Common types and methods for cameras.
 *
 * @{
 */

/**
 * Region of interest on a camera.
 */
typedef struct _tao_camera_roi {
    long   xbin;/**< Horizontal binning (in physical pixels). */
    long   ybin;/**< Vertical binning (in physical pixels). */
    long   xoff;/**< Horizontal offset of the acquired images with respect to
                     the left border of the detector (in physical pixels). */
    long   yoff;/**< Vertical offset of the acquired images with respect to the
                     bottom border of the detector (in physical pixels). */
    long  width;/**< Number of pixels per line of the acquired images (in
                     macro-pixels). */
    long height;/**< Number of lines of pixels in the acquired images (in
                     macro-pixels). */
} tao_camera_roi_t;

/**
 * Copy the settings of a region of interest.
 *
 * This function copies the settings of the source @b src into the destination
 * @b dest and returns @b dest.
 *
 * @param dest   Address of destination.
 * @param  src   Address of source.
 *
 * @return The destination @b dest.
 *
 * @see tao_camera_roi_t, tao_check_camera_roi(),
 * tao_define_camera_roi().
 */
extern tao_camera_roi_t* tao_copy_camera_roi(tao_camera_roi_t* dest,
                                             const tao_camera_roi_t* src);

/**
 * Set a region of interest.
 *
 * This function set the members of @b roi and returns @b roi.
 *
 * @param   dest   Address of region of interest.
 * @param   xbin   Horizontal binning (in physical pixels).
 * @param   ybin   Vertical binning (in physical pixels).
 * @param   xoff   Horizontal offset of ROI (in physical pixels).
 * @param   yoff   Vertical offset of ROI (in physical pixels).
 * @param  width   Horizontal size of ROI (in macro-pixels).
 * @param height   Vertical size of ROI (in macro-pixels).
 *
 * @return The region of interest @b roi.
 *
 * @see tao_camera_roi_t, tao_copy_camera_roi(),
 * tao_check_camera_roi().
 */
extern tao_camera_roi_t* tao_define_camera_roi(tao_camera_roi_t* roi,
                                               long xbin, long ybin,
                                               long xoff, long yoff,
                                               long width, long height);

/**
 * Check a region of interest.
 *
 * This function check whether the region of interest settings in @b roi are
 * valid and compatible with the sensor dimensions given by @b sensorwidth and
 * @b sensorheight.
 *
 * @param          roi   Address of the region of interest to check.
 * @param  sensorwidth   Horizontal size of detector (in pixels).
 * @param sensorheight   Vertical size of detector (in pixels).
 *
 * @return @ref TAO_OK if the ROI is valid, @ref TAO_ERROR otherwise.
 *
 * @see tao_camera_roi_t, tao_copy_camera_roi(),
 * tao_define_camera_roi().
 */
extern tao_status_t tao_check_camera_roi(const tao_camera_roi_t* roi,
                                         long sensorwidth,
                                         long sensorheight);

/**
 * Possible states of a remote camera.
 *
 * These represent the tasks that are currently been executed by the
 * frame-grabber thread in charge of the acquisition of images.  The meanings
 * of the different states are as follow:
 *
 * - @b initializing: the tread is not yet ready;
 * - @b sleeping: acquisition has not yet started, setting configuration
 *      parameters is possible;
 * - @b starting: acquisition is about to start;
 * - @b acquiring: acquisition of images is running;
 * - @b stopping: acquisition is about to stop;
 * - @b aborting: acquisition is about to abort;
 * - @b finished: thread is about to quit or no longer reachable.
 */
typedef enum {
    TAO_CAMERA_STATE_INITIALIZING = 0,
    TAO_CAMERA_STATE_SLEEPING     = 1,
    TAO_CAMERA_STATE_STARTING     = 2,
    TAO_CAMERA_STATE_ACQUIRING    = 3,
    TAO_CAMERA_STATE_STOPPING     = 4,
    TAO_CAMERA_STATE_ABORTING     = 5,
    TAO_CAMERA_STATE_FINISHED     = 6,
} tao_camera_state_t;

/**
 * Yield the literal name of a camera state.
 *
 * @param state   A camera state value.
 *
 * @return The literal name of the camera state or `"unknown"`.
 */
extern const char* tao_get_camera_state_name(tao_camera_state_t state);

/**
 * Pending events for a camera.
 *
 * Pending events are given as a combination of bits.  The following events
 * are implemented:
 *
 * - @b TAO_EVENT_START: Start acquisition.
 * - @b TAO_EVENT_FRAME: A new frame is available.
 * - @b TAO_EVENT_ERROR: Some (recoverable) error occured.
 * - @b TAO_EVENT_STOP: Stop acquisition.
 * - @b TAO_EVENT_ABORT: Abort acquisition.
 * - @b TAO_EVENT_QUIT: Acquisition thread must quit.
 */
typedef unsigned int tao_event_t;

#define TAO_EVENT_COMMAND (((tao_event_t)1) << 0) /* Command sent */
#define TAO_EVENT_FRAME   (((tao_event_t)1) << 1) /* New frame available */
#define TAO_EVENT_ERROR   (((tao_event_t)1) << 2) /* Some error occured */

/**
 * Common camera configuration.
 *
 * This structure contains the (usually) configurable parameters common to any
 * kind of camera.
 */
typedef struct _tao_camera_config {
    tao_camera_roi_t          roi;/**< Region of interest on the detector. */
    tao_eltype_t        pixeltype;/**< Pixel type in pre-processed images. */
    tao_encoding_t sensorencoding;/**< Pixel encoding in images acquired by the
                                       sensor. */
    tao_encoding_t bufferencoding;/**< Pixel encoding for acquisition
                                       buffers. */
    int                   buffers;/**< Number of acquisition buffers. */
    double              framerate;/**< Acquisition rate in frames per
                                       second. */
    double           exposuretime;/**< Exposure time in seconds. */
    bool                 weighted;/**< True if pre-processed images have
                                       associated weights. */
} tao_camera_config_t;

/**
 * Print camera configuration.
 *
 * @param out   The output file stream where to print.
 * @param cfg   Address of camera configuration structure.
 *
 * @return @ref TAO_OK on success; @ref TAO_ERROR in case of failure.
 *
 * @see tao_print_camera_information().
 */
extern tao_status_t tao_print_camera_configuration(FILE* out,
                                                   const tao_camera_config_t* cfg);

/**
 * Common camera information.
 *
 * This structure contains the parameters common to any kind of camera.
 */
typedef struct _tao_camera_info {
    long           sensorwidth;/**< Number of physical pixels per row of the
                                    detector. */
    long          sensorheight;/**< Number of physical pixels per column of the
                                    detector. */
    tao_camera_config_t config;/**< Configurable parameters. */
    tao_camera_state_t   state;/**< State of the camera. */
    double         temperature;/**< Camera temperature (in degrees Celsius). */
    tao_time_t          origin;/**< Origin of time. */
    int64_t             frames;/**< Number of frames received so far. */
    int64_t           overruns;/**< Number of frames lost so far because of
                                    overruns. */
    int64_t         lostframes;/**< Number of lost frames. */
    int64_t          overflows;/**< Number of overflows. */
    int64_t          lostsyncs;/**< Number of synchronization losts so far. */
    int64_t           timeouts;/**< Number of timeouts so far. */
} tao_camera_info_t;

/**
 * Print camera configuration.
 *
 * This function prints the contents of a given camera information and calls
 * tao_print_camera_configuration() to print the configuration part.
 *
 * @param out   The output file stream where to print.
 * @param inf   Address of camera information structure.
 *
 * @return @ref TAO_OK on success; @ref TAO_ERROR in case of failure.
 *
 * @see tao_print_camera_configuration().
 */
extern tao_status_t tao_print_camera_information(FILE* out,
                                                 const tao_camera_info_t* inf);


/** @} */

/*---------------------------------------------------------------------------*/
/* REMOTE CAMERAS */

/**
 * @addtogroup RemoteCameras
 *
 * Remote/shared cameras.
 *
 * A TAO remote, or shared, camera is a structure stored in shared memory which
 * contains the current camera settings and which can be used to obtain an
 * image from the remote camera.
 *
 * @{
 */

/**
 * Shared camera information.
 *
 * This structure describes the shared data storing the resources of a remote
 * camera.  After querying the shared memory identifier to the server (the
 * frame grabber), clients can attach this shared data part with
 * tao_attach_shared_camera().  When a client no longer needs this shared data,
 * it shall call tao_detach_shared_camera().
 *
 * This structure **must** be considered as read-only by the clients and
 * information provided by this structure is only valid as long as the client
 * locks this shared structure by calling tao_rdlock_shared_camera() and until
 * the client unlock the structure by calling tao_unlock_shared_camera().
 * Beware to not call tao_detach_shared_camera() while the shared data is
 * locked by the caller.
 *
 * If @n counter > 0, the index in the list of shared arrays memorized by the
 * virtual frame-grabber owning the shared camera is given by:
 *
 * ```.c
 * index = (counter - 1) % length
 *```
 *
 */
struct _tao_shared_camera {
    tao_shared_object_t base;/**< Shared object backing storage of the
                                  structure. */
    tao_camera_info_t   info;/**< Camera information. */
    const uint64_t    length;/**< Lenght of the list of shared arrays memorized
                                  by the virtual frame-grabber owning the
                                  shared camera. */
    volatile
    uint64_t         counter;/**< Number of images posted by virtual
                                  frame-grabber since its creation.  It is a
                                  unique, monotically increasing number,
                                  starting at 1 (0 means no images have been
                                  provided yet).  This value can be used to
                                  determine the index of the corresponding
                                  shared image in the cyclic list of
                                  frame-grabber shared arrays. */
    volatile
    tao_shmid_t    lastframe;/**< Identifier of the shared array backing the
                                  storage of the last acquired image, -1 means
                                  unused or invalid. */
    volatile
    tao_shmid_t    nextframe;/**< Identifier of the shared array backing the
                                  storage of the next acquired image, -1 means
                                  unused or invalid. */
};

/**
 * Attach an existing shared camera to the address space of the caller.
 *
 * This function attaches an existing shared camera to the address space of the
 * caller.  As a result, the number of attachments of the shared camera is
 * incremented by one.  When the camera is no longer used by the caller, the
 * caller must call tao_detach_shared_camera() to detach the camera from its
 * address space, decrement its number of attachments by one and eventually
 * free the shared memory associated with the camera.
 *
 * @warning The same process must not attach a shared camera more than once.
 *
 * @param shmid  Unique identifier of the shared object.
 *
 * @return The address of the shared camera in the address space of the caller;
 * `NULL` on failure.
 *
 * @see tao_detach_shared_camera, tao_get_shared_camera_shmid.
 */
extern tao_shared_camera_t* tao_attach_shared_camera(tao_shmid_t shmid);

/**
 * Detach a shared camera.
 *
 * Detach a shared camera from the address space of the caller and decrement
 * the number of attachments of the shared camera.
 *
 * @warning Detaching a shared camera does not detach shared arrays backing the
 * storage of the images acquired by this camera.  They have to be explicitly
 * detached.
 *
 * @param cam    Pointer to a shared camera attached to the address space of
 *               the caller.
 *
 * @return @ref TAO_OK on success; @ref TAO_ERROR on failure.
 *
 * @see tao_attach_shared_camera.
 */
extern tao_status_t tao_detach_shared_camera(tao_shared_camera_t* cam);

/**
 * Get the identifier of shared camera data.
 *
 * @param cam    Pointer to a shared camera attached to the address space of
 *               the caller and locked by the caller.
 *
 * @return The identifier of the shared camera data.  This value can be used
 *         by another process to attach to its address space the shared camera.
 *         `TAO_BAD_SHMID` is returned if @a cam is `NULL`.
 *
 * @see tao_attach_shared_camera.
 */
extern tao_shmid_t tao_get_shared_camera_shmid(const tao_shared_camera_t* cam);

/**
 * Get the name of the owner/creator of a shared camera.
 *
 * @param cam    Pointer to a shared camera attached to the address space of
 *               the caller.
 *
 * @return The name of the shared camera owner.
 */
extern const char* tao_get_shared_camera_owner(const tao_shared_camera_t* cam);

/**
 * Get the accesspoint of the server owning a shared camera.
 *
 * @param cam    Pointer to a shared camera attached to the address space of
 *               the caller.
 *
 * @return The name of the shared camera owner.
 */
extern const char* tao_get_shared_camera_accesspoint(const tao_shared_camera_t* cam);

/**
 * Lock a shared camera for reading or writing.
 *
 * Lock a shared camera for read-only or read-write access.  The caller is
 * responsible for eventually releasing the lock with
 * tao_unlock_shared_camera().
 *
 * @param cam    Pointer to a shared camera attached to the address space of
 *               the caller.
 * @param access The requested access mode: `TAO_READ_ACCESS` or
 *               `TAO_WRITE_ACCESS`.
 *
 * @return @ref TAO_OK on success; @ref TAO_ERROR on failure.
 */
extern tao_status_t tao_rdlock_shared_camera(tao_shared_camera_t* cam);

/**
 * Attempt to lock a shared camera for reading or writing.
 *
 * Try to lock a shared camera for read-only or read-write access without
 * blocking.  The caller is responsible for eventually releasing the lock with
 * tao_unlock_shared_camera().
 *
 * @param cam    Pointer to a shared camera attached to the address space of
 *               the caller.
 *
 * @param access The requested access mode: `TAO_READ_ACCESS` or
 *               `TAO_WRITE_ACCESS`.
 *
 * @return @ref TAO_OK on success, @ref TAO_TIMEOUT if the lock cannot be
 *         immediately acquired or @ref TAO_ERROR on failure.
 */
extern tao_status_t tao_try_rdlock_shared_camera(tao_shared_camera_t* cam);

/**
 * Lock a shared camera for reading or writing with a timeout.
 *
 * Try to lock a shared camera for read-only or read-write access without
 * blocking more than a given duration.  The caller is responsible for
 * eventually releasing the lock with tao_unlock_shared_camera().
 *
 * @param cam    Pointer to a shared camera attached to the address space of
 *               the caller.
 *
 * @param access The requested access mode: `TAO_READ_ACCESS` or
 *               `TAO_WRITE_ACCESS`.
 *
 * @param secs   Maximum time to wait (in seconds).  If this amount of time is
 *               very large, e.g. more than @ref TAO_MAX_TIME_SECONDS, the
 *               effect is the same as calling tao_rdlock_shared_camera().  If
 *               this amount of time is very short, the effect is the same as
 *               calling tao_try_rdlock_shared_camera().
 *
 * @return @ref TAO_OK if the lock has been locked by the caller before the
 *         specified number of seconds, @ref TAO_TIMEOUT if timeout occured
 *         before or @ref TAO_ERROR in case of error.
 */
extern tao_status_t tao_abstimed_rdlock_shared_camera(tao_shared_camera_t* cam,
                                                      const tao_time_t* abstime);

extern tao_status_t tao_timed_rdlock_shared_camera(tao_shared_camera_t* cam,
                                                   double secs);

extern tao_status_t tao_wrlock_shared_camera(tao_shared_camera_t* cam);

extern tao_status_t tao_try_wrlock_shared_camera(tao_shared_camera_t* cam);

extern tao_status_t tao_abstimed_wrlock_shared_camera(tao_shared_camera_t* cam,
                                                      const tao_time_t* abstime);

extern tao_status_t tao_timed_wrlock_shared_camera(tao_shared_camera_t* cam,
                                                   double secs);
/**
 * Unlock a shared camera.
 *
 * @param cam    Pointer to a shared camera attached to the address space of
 *               the caller.
 *
 * @return @ref TAO_OK on success; @ref TAO_ERROR on failure.
 *
 * @see tao_unlock_shared_object.
 */
extern tao_status_t tao_unlock_shared_camera(tao_shared_camera_t* cam);

/**
 * Get the current state of the camera.
 *
 * @param cam   Address of shared camera in address space of caller.
 *
 * @return `-1` if @a cam is `NULL`; otherwise, `0` if device not yet open, `1`
 *         if device open but no acquisition is running, `2` if acquisition is
 *         running.
 */
extern tao_camera_state_t tao_get_shared_camera_state(const tao_shared_camera_t* cam);

/**
 * Get the pixel type for the captured images after pre-processing.
 *
 * @param cam   Address of shared camera in address space of caller.
 *
 * @return The pixel type for the captured images after pre-processing, `-1`
 *         if @a cam is `NULL`.
 */
extern tao_eltype_t tao_get_shared_camera_pixeltype(const tao_shared_camera_t* cam);

/**
 * Get the encoding of pixels in images sent by the camera.
 *
 * @param cam   Address of shared camera in address space of caller.
 *
 * @return The encoding of pixels in the raw captured images,
 *         `TAO_ENCODING_UNKNOWN` if @a cam is `NULL`.
 */
extern tao_encoding_t tao_get_shared_camera_sensorencoding(const tao_shared_camera_t* cam);

/**
 * Get the encoding of pixels in acquisition buffers.
 *
 * @param cam   Address of shared camera in address space of caller.
 *
 * @return The encoding of pixels in acquisition buffers,
 *         `TAO_ENCODING_UNKNOWN` if @a cam is `NULL`.
 */
extern tao_encoding_t tao_get_shared_camera_bufferencoding(const tao_shared_camera_t* cam);

/**
 * Get the width of the detector.
 *
 * This function yields the number of pixels per line of the detector which is
 * the maximum width for captured iamges.
 *
 * @param cam   Address of shared camera in address space of caller.
 *
 * @return The number of pixels per line of the detector, `0` if @a cam is
 *         `NULL`.
 */
extern long tao_get_shared_camera_sensorwidth(const tao_shared_camera_t* cam);

/**
 * Get the height of the detector.
 *
 * This function yields the number of lines of pixels of the detector which is
 * the maximum height for captured iamges.
 *
 * @param cam   Address of shared camera in address space of caller.
 *
 * @return The number of lines of pixels of the detector, `0` if @a cam is
 *         `NULL`.
 */
extern long tao_get_shared_camera_sensorheight(const tao_shared_camera_t* cam);

/**
 * Get the horizontal binning factor.
 *
 * @param cam   Address of shared camera in address space of caller.
 *
 * @return The horizontal binning factor in physical pixels, `0` if
 *         @a cam is `NULL`.
 */
extern long tao_get_shared_camera_xbin(const tao_shared_camera_t* cam);

/**
 * Get the vertical binning factor.
 *
 * @param cam   Address of shared camera in address space of caller.
 *
 * @return The vertical binning factor in physical pixels, `0` if
 *         @a cam is `NULL`.
 */
extern long tao_get_shared_camera_ybin(const tao_shared_camera_t* cam);

/**
 * Get the horizontal offset of captured images.
 *
 * @param cam   Address of shared camera in address space of caller.
 *
 * @return The horizontal offset in physical pixels of the region of interest
 *         set for the captured images, `0` if @a cam is `NULL`.
 */
extern long tao_get_shared_camera_xoff(const tao_shared_camera_t* cam);

/**
 * Get the vertical offset of captured images.
 *
 * @param cam   Address of shared camera in address space of caller.
 *
 * @return The vertical offset in physical pixels of the region of interest
 *         set for the captured images, `0` if @a cam is `NULL`.
 */
extern long tao_get_shared_camera_yoff(const tao_shared_camera_t* cam);

/**
 * Get the width of the captured images.
 *
 * This function yields the number of macro-pixels per line of the captured
 * images.  If no sub-sampling nor re-binning of physical pixels is used a
 * macro-pixel corresponds to a physical pixel.
 *
 * @param cam   Address of shared camera in address space of caller.
 *
 * @return The number of macro-pixels per line of the captured images, `0` if
 *         @a cam is `NULL`.
 */
extern long tao_get_shared_camera_width(const tao_shared_camera_t* cam);

/**
 * Get the height of the captured images.
 *
 * This function yields the number of lines of macro-pixels in the captured
 * images.  If no sub-sampling nor re-binning of physical pixels is used a
 * macro-pixel corresponds to a physical pixel.
 *
 * @param cam   Address of shared camera in address space of caller.
 *
 * @return The number of lines of macro-pixels in the captured images, `0` if
 *         @a cam is `NULL`.
 */
extern long tao_get_shared_camera_height(const tao_shared_camera_t* cam);

/**
 * Get the frame rate.
 *
 * @param cam   Address of shared camera in address space of caller.
 *
 * @return The number of frame per seconds, `0` if @a cam is `NULL`.
 */
extern double tao_get_shared_camera_framerate(const tao_shared_camera_t* cam);

/**
 * Get the duration of the exposure.
 *
 * @param cam   Address of shared camera in address space of caller.
 *
 * @return The exposure time in seconds for the captured images, `0` if @a cam
 *         is `NULL`.
 */
extern double tao_get_shared_camera_exposuretime(const tao_shared_camera_t* cam);

/**
 * Get the length of the list of shared arrays memorized by the owner of
 * a shared camera.
 *
 * @param cam    Pointer to a shared camera attached to the address space of
 *               the caller and locked by the caller.
 *
 * @note The length of the list is immutable, the caller does not have to lock
 * the shared camera to insure consistency of the result.
 *
 * @return The length of the list of shared arrays memorized by the owner of
 * the shared camera, `0` if @a cam is `NULL`.
 *
 * @see tao_rdlock_shared_camera.
 */
extern uint64_t tao_get_image_list_length(const tao_shared_camera_t* cam);

/**
 * Get the number of posted images.
 *
 * @param cam    Pointer to a shared camera attached to the address space of
 *               the caller and locked by the caller.
 *
 * @warning Since the last image may change (because acquisition is running),
 * the caller must have locked the shared camera.  For efficiency reasons, this
 * function does not perform error checking.
 *
 * @return The the number of images posted by the owner of the shared camera
 * `0` if none or if @a cam is `NULL`.
 *
 * @see tao_rdlock_shared_camera.
 */
extern uint64_t tao_get_last_image_counter(const tao_shared_camera_t* cam);

/**
 * Get the identifier of the last acquired image.
 *
 * This function yields the shared memory identifier of the last image acquired
 * by a remote camera.  Since the last image may change (because acquisition is
 * running), the caller is assumed to have locked the shared camera, at least
 * for read-only access.
 *
 * @param cam    Pointer to a shared camera attached to the address space of
 *               the caller and locked by the caller.
 *
 * @return The identifier of the last acquired image or @ref TAO_BAD_SHMID if
 *         none or if @a cam is `NULL`.
 *
 * @see tao_rdlock_shared_camera, tao_attach_last_image.
 */
extern tao_shmid_t tao_get_last_image_shmid(const tao_shared_camera_t* cam);

/**
 * Get the identifier of the next acquired image.
 *
 * @param cam    Pointer to a shared camera attached to the address space of
 *               the caller and locked by the caller.
 *
 * @warning Since the next image may change (because acquisition is running),
 *          the caller is assumed to have locked the shared camera, at least
 *          for read-only access.
 *
 * @return The identifier of the last acquired image or @ref TAO_BAD_SHMID if
 *         none or if @a cam is `NULL`.
 *
 * @see tao_rdlock_shared_camera.
 */
extern tao_shmid_t tao_get_next_image_shmid(const tao_shared_camera_t* cam);

/**
 * Attach the last acquired image to the address space of the caller.
 *
 * This function attaches the last image acquired by a frame grabber to the
 * address space of the caller.  The caller is responsible of calling
 * tao_detach_shared_array() to detach the image from its address space.
 *
 * Since the last image may change (because acquisition is running), the caller
 * is assumed to have locked the shared camera, at least for read-only access.
 * It is the caller responsability to lock the returned image to make sure it
 * is not overwritten while reading its contents.
 *
 * @param cam    Address of a shared camera attached to the address space of
 *               the caller.
 *
 * The following example shows how to retrieve the last image data provided
 * the image counter has increased since previous image:
 *
 * ```.c
 * tao_shared_camera_t* cam = ...;
 * uint64_t previous_counter = ...;
 * tao_shared_array_t* arr = NULL;
 * tao_rdlock_shared_camera(NULL, cam);
 * {
 *     uint64_t last_counter = tao_get_last_image_counter(cam);
 *     if (last_counter > previous_counter) {
 *         arr = tao_attach_last_image(NULL, cam);
 *         previous_counter = last_counter;
 *     }
 * }
 * tao_unlock_shared_camera(NULL, cam);
 * ```
 *
 * Note the use of braces to emphasizes the block of statements protected by
 * the lock.  Also note that `NULL` is passed as the address of the variable to
 * track errors so any error will be considered as fatal in this example.
 *
 * The same example without tao_attach_last_image():
 *
 * ```.c
 * tao_shared_camera_t* cam = ...;
 * uint64_t previous_counter = ...;
 * tao_shared_array_t* arr = NULL;
 * tao_rdlock_shared_camera(NULL, cam);
 * {
 *     uint64_t last_counter = tao_get_last_image_counter(cam);
 *     if (last_counter > previous_counter) {
 *         tao_shmid_t shmid = tao_get_last_image_shmid(cam);
 *         if (shmid != TAO_BAD_SHMID) {
 *             arr = tao_attach_shared_array(NULL, shmid);
 *             previous_counter = last_counter;
 *         }
 *     }
 * }
 * tao_unlock_shared_camera(NULL, cam);
 * ```
 *
 * @return The address of the shared camera in the address space of the caller;
 *         `NULL` on failure or if there is no valid last image.
 *
 * @see tao_get_last_image_shmid, tao_get_last_image_counter,
 *      tao_attach_next_image.
 */
extern tao_shared_array_t* tao_attach_last_image(tao_shared_camera_t* cam);

/**
 * Attach the next acquired image to the address space of the caller.
 *
 * This function attaches the next image that will be acquired by a frame
 * grabber to the address space of the caller.  The caller is responsible of
 * calling tao_detach_shared_array() to detach the image from its address
 * space.
 *
 * Since the next image may change (because acquisition is running), the caller
 * is assumed to have locked the shared camera, at least for read-only access.
 *
 * The next image is locked for writing by the camera server until the next
 * image is acquired and pre-processed.  In order to wait for the acquisition
 * to complete, the caller shall attempt to lock the returned image for reading
 * (possibly with a timeout) this also ensure it is not overwritten while
 * reading its contents.  Note that the frame counter of the shared image is
 * updated by the camera server just before unlocking the image.
 *
 * @param cam    Address of a shared camera attached to the address space of
 *               the caller.
 *
 * The following example shows how to retrieve the next images data while
 * acquisition is running and making sure the image counter does increase
 * between successive images:
 *
 * ```.c
 * tao_shared_camera_t* cam = ...;
 * uint64_t previous_counter = 0;
 * tao_shared_array_t* arr = NULL;
 * bool acquiring = true;
 * while (acquiring) {
 *     tao_rdlock_shared_camera(NULL, cam);
 *     {
 *         arr = tao_attach_next_image(NULL, cam);
 *     }
 *     tao_unlock_shared_camera(NULL, cam);
 *     tao_rdlock_shared_array(NULL, arr); // block until acquisition done
 *     {
 *         uint64_t counter = tao_get_shared_array_counter(arr);
 *         if (counter > previous_counter) {
 *             ...; // do something with the image data
 *             previous_counter = counter;
 *         } else if (counter == 0) {
 *             // acquisition has been stopped
 *             acquiring = false;
 *         }
 *     }
 *     tao_unlock_shared_array(NULL, arr);
 *     tao_detach_shared_array(NULL, arr);
 * }
 * ```
 *
 * Note the use of braces to emphasizes the block of statements protected by
 * the lock.  Also note that `NULL` is passed as the address of the variable to
 * track errors so any error will be considered as fatal in this example.
 *
 * @return The address of the shared camera in the address space of the caller;
 *         `NULL` on failure or if there is no valid last image.
 *
 * @see tao_get_next_image_shmid, tao_attach_last_image.
 */
extern tao_shared_array_t* tao_attach_next_image(tao_shared_camera_t* cam);

/** @} */

/*---------------------------------------------------------------------------*/
/* UNIFIED INTERFACE FOR CAMERA DEVICES */

/**
 * @addtogroup UnifiedCameras
 *
 * Unified cameras.
 *
 * TAO provides generic structures and functions to operate real cameras.
 *
 * The @ref tao_camera_t structure has its own error stack which is used by
 * most functions operating on this class of cameras to store error
 * information.  This is needed because the camera device may be operated by
 * another thread.
 *
 * @{
 */

/**
 * Acquisition buffer information.
 *
 * This structure is used to store all needed information about an acquisition
 * buffer returned by tao_wait_camera().  The contents is considered as purely
 * informative by the high-level interface.  For instance the high-level
 * interface does not attempt to alloc or free the acquisition buffer data,
 * these tasks are performed by the low-level interface (e.g. by the "start"
 * and "finalize" virtual methods).
 *
 * A valid buffer counter should be equal to the corresponding frame counter
 * which is greater or equal 1.  When acquisition is started by
 * tao_acquisition_start(), all buffer counters are set to 0.
 */
typedef struct _tao_acquisition_buffer {
    void*                   data;/**< Address of buffer data. */
    long                    size;/**< Number of bytes in buffer. */
    long                  offset;/**< Offset (in bytes) of first pixel in
                                      ROI. */
    long                   width;/**< Number of pixel per line in ROI. */
    long                  height;/**< Number of lines in ROI. */
    long                  stride;/**< Bytes per line in buffer. */
    tao_encoding_t      encoding;/**< Pixel encoding in buffer. */
    uint64_t        frame_number;/**< Number of frames so far. */
    tao_time_t       frame_start;/**< Start time of frame. */
    tao_time_t         frame_end;/**< End time of frame. */
    tao_time_t      buffer_ready;/**< Buffer ready time. */
} tao_acquisition_buffer_t;

/**
 * Opaque camera structure.
 */
typedef struct _tao_camera tao_camera_t;

/**
 * Table of virtual methods for a camera.
 *
 * An instance of this structure is specific to each combination of camera
 * model and frame-grabber.
 *
 * Camera @b run-level has only 5 levels: @b 0 when initialization is not
 * complete, @b 1 when initialized but acquisition not started, @b 2 when
 * acquiring, @b 3 if an error occured that requires an explicit reset to
 * return to run-level 1 or @b 4 if camera is no longer usable and can only be
 * finalized (e.g. upon unrecoverable error).
 *
 * The following transitions are possible:
 *
 *    0 -> 1  is done when successfully calling the "initialize" virtual method
 *            which is only called once during the lifetime of the camera
 *            instance; so `runlevel != 0` means camera has been initialized;
 *
 *    1 -> 2 is done when successfully calling the "start" virtual method;
 *
 *    2 -> 1  is done when successfully calling the "stop" virtual method;
 *
 *    3 -> 1  is done when successfully calling the "reset" virtual method;
 *
 *    x -> 3  (with x neither 0, nor 4) may result from a recoverable error
 *            that requires an explicit reset;
 *
 *    x -> 4  (with x not 0) may result from an unrecoverable error.
 *
 * Except in case of errors (and when explicitly indicated), the virtual
 * methods are not allowed to change the camera run-level.  Changing the
 * run-level is done by the higher level TAO functions which call virtual
 * methods as needed and which also ensure that the camera is in a proper
 * run-level before calling a specific virtual method.  These rules are to
 * simplify the writting of virtual methods and to implement a common and
 * consistent behavior.
 *
 * Virtual methods must be all implemented (provided a `NULL` address is not
 * allowed).  If some method makes no sense for a specific kind of camera, the
 * implemented method shall returns an error.
 *
 * Initialization failure results in run-level being stuck at 0, subsequent
 * operations on the camera yield @ref TAO_NOT_READY error code.
 */
typedef struct _tao_camera_ops {
    const char* name; /**< Camera model/family name */

    tao_status_t (*initialize)(tao_camera_t* cam);
    /**< Initialize the members of this structure (including the
         configuration).  This method is only called once during the lifetime
         of the camera instance.  It shall return @ref TAO_OK on success or @ref
         TAO_ERROR on failure.  It is assumed that any allocated specific
         resources are destroyed in case of failure (the `finalize` method is
         not called if initialization fails). */

    void (*finalize)(tao_camera_t* cam);
    /**< Free device resources.  This method is only called once at the end of
         the lifetime of the camera instance.  This method is not called by the
         generic constructor tao_create_camera() in case of errors during the
         construction. */

    tao_status_t (*reset)(tao_camera_t* cam);
    /**< Reset camera to run-level 1 (sleeping) in case of recoverable error.
         This method shall only be called when the camera run-level is 3.  On
         success, the method shall set the run-level to 1 and return TAO_OK;
         otherwise it shall return @ref TAO_ERROR to indicate a failure. */

    tao_status_t (*update_config)(tao_camera_t* cam);
    /**< Retrieve camera current device settings, never called while
         acquisition is running.  It shall return @ref TAO_OK on success or
         @ref TAO_ERROR on failure. */

    tao_status_t (*check_config)(tao_camera_t* cam,
                                 const tao_camera_config_t* cfg);
    /**< Check camera settings.  Camera error stack may be used to report which
         parameters are invalid.  It shall return @ref TAO_OK on success or
         @ref TAO_ERROR on failure. */

    tao_status_t (*set_config)(tao_camera_t* cam,
                               const tao_camera_config_t* cfg);
    /**< Set camera settings.  This method is called to set the camera
         configuration.  It is never called while acquitring.  It shall return
         @ref TAO_OK on success or @ref TAO_ERROR on failure. */

    tao_status_t (*start)(tao_camera_t* cam);
    /**< Start acquisition.  This method is only called after initialization
         and if the camera is not acquiring.  It shall return @ref TAO_OK on
         success or @ref TAO_ERROR on failure. */

    tao_status_t (*stop)(tao_camera_t* cam);
    /**< Stop acquisition.  This method shall stop acquisition immediately,
         without waiting for the current frame. This method is only called when
         the camera is acquiring.  It shall return @ref TAO_OK on success or
         @ref TAO_ERROR on failure. */

    tao_status_t (*wait_buffer)(tao_camera_t* cam, double secs);
    /**< Wait for the next frame.  This method is only called when the camera
         is acquiring.  It shall not wait more than `secs` seconds.  It shall
         return @ref TAO_OK on success, @ref TAO_TIMEOUT on timeout or @ref
         TAO_ERROR on failure.  This method may assume that arguments have been
         checked for correctness.  This method shall update `cam->last` and
         `cam->pending`. */

    tao_status_t (*release_buffer)(tao_camera_t* cam);
    /**< Release the first pending acquisition buffer.  This method is only
         called when the camera is acquiring.  It shall return @ref TAO_OK on
         success or @ref TAO_ERROR on failure.  This method shall update
         `cam->last` and `cam->pending`. */
} tao_camera_ops_t;

/**
 * Generic camera.
 *
 * A camera has its own mutex and condition variable because it is often
 * necessary to operate the camera in separate threads.  However these threads
 * belongs to the same process so the mutex and condition variable associated
 * to a camera are not sharable between processes.
 *