#ifndef __UNIFIED_CAMERA_ACCESS_CAM_H #define __UNIFIED_CAMERA_ACCESS_CAM_H #include #ifdef __cplusplus extern "C" { #endif /** * \file uca-cam.h * \brief Abstract camera model * * The uca_camera_t structure represents a common interface for cameras regardless of * their connectivity. Each camera that adheres to this model must provide an * initialization function implementing uca_cam_init() that probes the device * and sets all function pointers to their respective implementations. */ enum uca_property_ids; /** * Describes the current state of the camera. */ enum uca_cam_state { UCA_CAM_ERROR, /**< Camera is not working correctly */ UCA_CAM_CONFIGURABLE, /**< Camera can be configured and is not recording */ UCA_CAM_ARMED, /**< Camera is ready for recording */ UCA_CAM_RECORDING, /**< Camera is currently recording */ }; /* * --- non-virtual methods ---------------------------------------------------- */ /** * Allocates buffer memory for the internal frame grabber. * * The allocation is just a hint to the underlying camera driver. It might * ignore this or pass this information on to a related frame grabber. * * \param[in] cam A camera structure. * * \param[in] n_buffers Number of sub-buffers with size frame_width*frame_height. */ /* FIXME: put this into vtable?! */ uint32_t uca_cam_alloc(struct uca_camera *cam, uint32_t n_buffers); /** * Retrieve current state of the camera. * * \param[in] cam A camera structure. * * \return A value from the uca_cam_state enum representing the current state of * the camera. */ enum uca_cam_state uca_cam_get_state(struct uca_camera *cam); /** * Allocates memory for a new uca_camera structure and initializes all fields to * sane values. * * \return Pointer to block of memory for a uca_camera structure * * \note This is is a utility function used internally by drivers */ struct uca_camera *uca_cam_new(void); /* * --- virtual methods -------------------------------------------------------- */ /** * Function pointer for camera probing and initialization. * * \param[out] cam On success, *cam holds the newly created uca_camera_t * structure. * * \param[in] grabber Grabber structure to access the cam. Can be NULL to * specify devices without frame grabber access. * * \return * UCA_ERR_INIT_NOT_FOUND if camera is not found or could not be initialized * * \note This is a private function and should be called exclusively by uca_init(). */ typedef uint32_t (*uca_cam_init) (struct uca_camera **cam, struct uca_grabber *grabber); /** * \brief Function pointer to free camera resources. * * \param[in] cam The camera to close. * * \note This is a private function and should be called exclusively by uca_init(). */ typedef uint32_t (*uca_cam_destroy) (struct uca_camera *cam); /** * Function pointer to set a camera property. * * \param[in] cam The camera whose properties are to be set. * * \param[in] property ID of the property as defined in XXX * * \param[out] data Where to read the property's value from * * \return UCA_ERR_PROP_INVALID if property is not supported on the camera or * UCA_ERR_PROP_VALUE_OUT_OF_RANGE if value cannot be set. */ typedef uint32_t (*uca_cam_set_property) (struct uca_camera *cam, enum uca_property_ids property, void *data); /** * Function pointer to get a property. * * \param[in] cam The camera whose properties are to be retrieved. * * \param[in] property ID of the property as defined in XXX * * \param[out] data Where to store the property's value * * \param[in] num Number of bytes of string storage. Ignored for uca_uint8t * and uca_uint32t properties. * * \return UCA_ERR_PROP_INVALID if property is not supported on the camera */ typedef uint32_t (*uca_cam_get_property) (struct uca_camera *cam, enum uca_property_ids property, void *data, size_t num); /** * Begin recording. * * Usually this also involves the frame acquisition of the frame grabber but is * hidden by this function. */ typedef uint32_t (*uca_cam_start_recording) (struct uca_camera *cam); /** * Stop recording. */ typedef uint32_t (*uca_cam_stop_recording) (struct uca_camera *cam); /** * Send a software trigger signal to start a sensor read-out. * * This method is only useful when UCA_PROP_TRIGGER_MODE is set to * UCA_TRIGGER_SOFTWARE. */ typedef uint32_t (*uca_cam_trigger) (struct uca_camera *cam); /** * Function pointer to a grab callback. * * Register such a callback function with uca_cam_register_callback() to * receive data as soon as it is delivered. * * \param[in] image_number Current frame number * * \param[in] buffer Image data * * \param[in] meta_data Meta data provided by the camera specifying per-frame * data. * * \param[in] user User data registered in uca_cam_register_callback() * * \note The meta data parameter is not yet specified but just a place holder. */ typedef void (*uca_cam_grab_callback) (uint64_t image_number, void *buffer, void *meta_data, void *user); /** * Register callback for given frame grabber. To actually start receiving * frames, call uca_grabber_acquire(). * * \param[in] grabber The grabber for which the callback should be installed * * \param[in] callback Callback function for when a frame arrived * * \param[in] user User data that is passed to the callback function */ typedef uint32_t (*uca_cam_register_callback) (struct uca_camera *cam, uca_cam_grab_callback callback, void *user); /** * \brief Grab one image from the camera * * The grabbing involves a memory copy because we might have to decode the image * coming from the camera, which the frame grabber is not able to do. * * \param[in] buffer Destination buffer * * \param[in] meta_data Meta data provided by the camera specifying per-frame * data. * * \note The meta data parameter is not yet specified but just a place holder. * */ typedef uint32_t (*uca_cam_grab) (struct uca_camera *cam, char *buffer, void *meta_data); /** * Represents a camera abstraction, that concrete cameras must implement. */ typedef struct uca_camera { /** * Points to the next available camera in a linked-list fashion. * * End of list is specified with next == NULL. */ struct uca_camera *next; /* Function pointers to camera-specific methods */ /** * Method to set a property. * \see uca_cam_set_property */ uca_cam_set_property set_property; /** * Method to get a property. * \see uca_cam_get_property */ uca_cam_get_property get_property; /** * Method to start recording. * \see uca_cam_start_recording */ uca_cam_start_recording start_recording; /** * Method to stop recording. * \see uca_cam_stop_recording */ uca_cam_stop_recording stop_recording; /** * Method to issue a software trigger signal. * \see uca_cam_trigger */ uca_cam_trigger trigger; /** * Method to grab a frame. * \see uca_cam_grab */ uca_cam_grab grab; /** * Method to register an frame acquisition callback. * * \see uca_cam_register_callback */ uca_cam_register_callback register_callback; /* Private */ /** * Method to close the camera. * \see uca_cam_destroy */ uca_cam_destroy destroy; /* private */ struct uca_grabber *grabber; /**< grabber associated with this camera */ enum uca_cam_state state; /**< camera state */ uint32_t frame_width; /**< current frame width */ uint32_t frame_height; /**< current frame height */ uint64_t current_frame; /**< last grabbed frame number */ uca_cam_grab_callback callback; void *callback_user; /**< user data for callback */ void *user; /**< private user data to be used by the camera driver */ } uca_camera_t; #ifdef __cplusplus } #endif #endif