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;
 };