Add grabber documentation and callback registration

3 files changed, 69 insertions, 14 deletions

diff --git a/src/grabbers/me4.c b/src/grabbers/me4.c
index f588298..d6419e0 100644
--- a/src/grabbers/me4.c
+++ b/src/grabbers/me4.c
@@ -145,9 +145,16 @@ uint32_t uca_me4_grab(struct uca_grabber_t *grabber, void **buffer)
     return UCA_NO_ERROR;
 }
 
+uint32_t uca_me4_register_callback(struct uca_grabber_t *grabber, uca_grabber_grab_callback cb)
+{
+    grabber->callback = cb;
+
+    /* TODO: add me4 registerApc stuff */
+    return UCA_NO_ERROR;
+}
+
 uint32_t uca_me4_init(struct uca_grabber_t **grabber)
 {
-    /* FIXME: find out if this board/grabber is running */
     Fg_Struct *fg = Fg_Init("libFullAreaGray8.so", 0);
     if (fg == NULL)
         return UCA_ERR_GRABBER_NOT_FOUND;
@@ -165,6 +172,7 @@ uint32_t uca_me4_init(struct uca_grabber_t **grabber)
     uca->acquire = &uca_me4_acquire;
     uca->stop_acquire = &uca_me4_stop_acquire;
     uca->grab = &uca_me4_grab;
+    uca->callback = NULL;
     
     *grabber = uca;
     return UCA_NO_ERROR;
diff --git a/src/uca-cam.h b/src/uca-cam.h
index 80bf4e7..7a18b3d 100644
--- a/src/uca-cam.h
+++ b/src/uca-cam.h
@@ -141,6 +141,9 @@ typedef uint32_t (*uca_cam_stop_recording) (struct uca_camera_t *cam);
 typedef uint32_t (*uca_cam_grab) (struct uca_camera_t *cam, char *buffer);
 
 
+/**
+ * Represents a camera abstraction, that concrete cameras must implement.
+ */
 struct uca_camera_t {
     /**
      * Points to the next available camera in a linked-list fashion.
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;
 };