summaryrefslogtreecommitdiffstats
path: root/src/uca-grabber.h
diff options
context:
space:
mode:
authorMatthias Vogelgesang <matthias.vogelgesang@ipe.fzk.de>2011-03-15 15:58:47 +0100
committerMatthias Vogelgesang <matthias.vogelgesang@ipe.fzk.de>2011-03-15 15:58:47 +0100
commit98511f7a77e7b37f9508b66298d99d7d1103e422 (patch)
treecade4dd76adea2d081147aa8811ea8c11e07f8fa /src/uca-grabber.h
parent45290e0c8d2bb0750fb5d78414477aefa5d28c5c (diff)
downloadlibuca-98511f7a77e7b37f9508b66298d99d7d1103e422.tar.gz
libuca-98511f7a77e7b37f9508b66298d99d7d1103e422.tar.bz2
libuca-98511f7a77e7b37f9508b66298d99d7d1103e422.tar.xz
libuca-98511f7a77e7b37f9508b66298d99d7d1103e422.zip
Add grabber documentation and callback registration
Diffstat (limited to 'src/uca-grabber.h')
-rw-r--r--src/uca-grabber.h70
1 files changed, 57 insertions, 13 deletions
diff --git a/src/uca-grabber.h b/src/uca-grabber.h
index bf6bf31..f29b950 100644
--- a/src/uca-grabber.h
+++ b/src/uca-grabber.h
@@ -3,6 +3,11 @@
#include <stdbool.h>
+/**
+ * \file uca-grabber.h
+ * \brief Abstract frame grabber model
+ */
+
enum uca_grabber_constants {
UCA_GRABBER_INVALID = -1,
/* properties */
@@ -32,51 +37,59 @@ enum uca_grabber_constants {
*/
/**
- * \brief Camera probing and initialization
- * \return UCA_ERR_INIT_NOT_FOUND if camera is not found or could not be initialized
+ * Camera probing and initialization.
+ *
+ * \return UCA_ERR_INIT_NOT_FOUND if grabber is not found or could not be initialized
*/
typedef uint32_t (*uca_grabber_init) (struct uca_grabber_t **grabber);
/**
- * \brief Free camera resouces
+ * Free frame grabber resouces.
*/
typedef uint32_t (*uca_grabber_destroy) (struct uca_grabber_t *grabber);
/**
- * \brief Set a property
- * \param[in] property_name Name of the property as defined in XXX
+ * Set a frame grabber property.
+ *
+ * \param[in] prop Name of the property as defined in uca_grabber_constants
+ *
* \return UCA_ERR_PROP_INVALID if property is not supported on the frame
- * grabber or UCA_ERR_PROP_VALUE_OUT_OF_RANGE if value cannot be set.
+ * grabber or UCA_ERR_PROP_VALUE_OUT_OF_RANGE if value cannot be set.
*/
typedef uint32_t (*uca_grabber_set_property) (struct uca_grabber_t *grabber, enum uca_grabber_constants prop, void *data);
/**
- * \brief Set a property
- * \param[in] property_name Name of the property as defined in XXX
+ * Get a frame grabber property.
+ *
+ * \param[in] prop Name of the property as defined in uca_grabber_constants
+ *
* \return UCA_ERR_PROP_INVALID if property is not supported on the frame grabber
*/
typedef uint32_t (*uca_grabber_get_property) (struct uca_grabber_t *grabber, enum uca_grabber_constants prop, void *data);
/**
- * \brief Allocate buffers with current width, height and bitdepth
- * \note Subsequent changes of width and height might corrupt memory
+ * Allocate buffers with current width, height and bitdepth.
+ *
+ * \warning Subsequent changes of width and height might corrupt memory.
*/
typedef uint32_t (*uca_grabber_alloc) (struct uca_grabber_t *grabber, uint32_t pixel_size, uint32_t n_buffers);
/**
- * \brief Begin acquiring frames
+ * Begin acquiring frames.
+ *
* \param[in] n_frames Number of frames to acquire, -1 means infinite number
+ *
* \param[in] async Grab asynchronous if true
*/
typedef uint32_t (*uca_grabber_acquire) (struct uca_grabber_t *grabber, int32_t n_frames);
/**
- * \brief Stop acquiring frames
+ * Stop acquiring frames.
*/
typedef uint32_t (*uca_grabber_stop_acquire) (struct uca_grabber_t *grabber);
/**
- * \brief Grab a frame
+ * Grab a frame.
*
* This method is usually called through the camera interface and not directly.
*
@@ -84,7 +97,36 @@ typedef uint32_t (*uca_grabber_stop_acquire) (struct uca_grabber_t *grabber);
*/
typedef uint32_t (*uca_grabber_grab) (struct uca_grabber_t *grabber, void **buffer);
+/**
+ * Function pointer to a grab callback.
+ *
+ * Register such a callback function with uca_grabber_register_callback() to
+ * receive data as soon as it is delivered.
+ *
+ * \param[in] image_number Current frame number
+ *
+ * \param[in] buffer Image data
+ */
+typedef void (*uca_grabber_grab_callback) (uint32_t image_number, void *buffer);
+/**
+ * Register callback for given frame grabber.
+ *
+ * \param[in] grabber The grabber for which the callback should be installed
+ *
+ * \param[in] cb Callback function for when a frame arrived
+ */
+typedef uint32_t (*uca_grabber_register_callback) (struct uca_grabber_t *grabber, uca_grabber_grab_callback cb);
+
+
+/**
+ * Represents a frame grabber abstraction, that concrete frame grabber
+ * implementations must implement.
+ *
+ * A uca_grabber_t structure is never used directly but only via the
+ * uca_camera_t interface in order to keep certain duplicated properties in sync
+ * (e.g. image dimensions can be set on frame grabber and camera).
+ */
struct uca_grabber_t {
struct uca_grabber_t *next;
@@ -96,8 +138,10 @@ struct uca_grabber_t {
uca_grabber_acquire acquire;
uca_grabber_stop_acquire stop_acquire;
uca_grabber_grab grab;
+ uca_grabber_register_callback register_callback;
/* Private */
+ uca_grabber_grab_callback callback;
bool asynchronous;
void *user;
};