Callback function have to notify caller about buffer

If they return a UCA_BUFFER_KEEP they have to call uca_cam_release_buffer() in
the future. If returning UCA_BUFFER_RELEASE, this is done by the caller.

5 files changed, 42 insertions, 4 deletions

diff --git a/NEWS b/NEWS
index 65623ea..5420ecf 100644
--- a/NEWS
+++ b/NEWS
@@ -3,3 +3,12 @@ Changes in libuca 0.5.0
 -----------------------
 
 - Put work under LGPL 2.1
+
+- Adapt cameras/ipe.c to support the current driver API
+
+- uca_cam_grab_callback()s have to return UCA_BUFFER_KEEP or UCA_BUFFER_RELEASE
+  now
+
+- New symbols:
+    - uca_cam_release_buffer()
+    
diff --git a/src/uca-cam.h b/src/uca-cam.h
index cba0305..08b7941 100644
--- a/src/uca-cam.h
+++ b/src/uca-cam.h
@@ -63,6 +63,7 @@ typedef struct uca_camera_priv {
     uint32_t (*stop_recording) (struct uca_camera_priv *cam);
     uint32_t (*trigger) (struct uca_camera_priv *cam);
     uint32_t (*register_callback) (struct uca_camera_priv *cam, uca_cam_grab_callback callback, void *user);
+    uint32_t (*release_buffer) (struct uca_camera_priv *cam, void *buffer);
     uint32_t (*grab) (struct uca_camera_priv *cam, char *buffer, void *meta_data);
     uint32_t (*readout) (struct uca_camera_priv *cam);
 
diff --git a/src/uca.c b/src/uca.c
index 4a23e69..1d07ea4 100644
--- a/src/uca.c
+++ b/src/uca.c
@@ -341,6 +341,13 @@ uint32_t uca_cam_register_callback(struct uca_camera *cam, uca_cam_grab_callback
     return priv->register_callback(priv, callback, user);
 }
 
+uint32_t uca_cam_release_buffer(struct uca_camera *cam, void *buffer)
+{
+    struct uca_camera_priv *priv = cam->priv;
+    if (priv->release_buffer != NULL)
+        return priv->release_buffer(priv, buffer);
+}
+
 uint32_t uca_cam_grab(struct uca_camera *cam, char *buffer, void *meta_data)
 {
     struct uca_camera_priv *priv = cam->priv;
diff --git a/src/uca.h b/src/uca.h
index 5baf472..6721e58 100644
--- a/src/uca.h
+++ b/src/uca.h
@@ -216,6 +216,15 @@ enum uca_cam_state {
     UCA_CAM_READOUT         /**< Camera recorded and is currently in readout mode */
 };
 
+/**
+ * Specify if the callback function keeps the buffer and will call
+ * ufo_cam_release_buffer() at later time or if after returning the buffer can
+ * be released automatically.
+ */
+enum uca_buffer_status {
+    UCA_BUFFER_KEEP,
+    UCA_BUFFER_RELEASE
+};
 
 /**
  * A uca_property_t describes a vendor-independent property used by cameras and
@@ -253,14 +262,14 @@ union uca_value {
  * receive data as soon as it is delivered.
  *
  * \param[in] image_number Current frame number
- * \param[in] buffer Image data
+ * \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);
+typedef enum uca_buffer_status (*uca_cam_grab_callback) (uint64_t image_number, void *buffer, void *meta_data, void *user);
 
 extern const char *uca_unit_map[];      /**< maps unit numbers to corresponding strings */
 
@@ -454,7 +463,6 @@ uint32_t uca_cam_stop_recording(struct uca_camera *cam);
  */
 uint32_t uca_cam_trigger(struct uca_camera *cam);
 
-
 /**
  * Register callback for given frame grabber. To actually start receiving
  * frames, call uca_grabber_acquire().
@@ -467,6 +475,17 @@ uint32_t uca_cam_trigger(struct uca_camera *cam);
 uint32_t uca_cam_register_callback(struct uca_camera *cam, uca_cam_grab_callback callback, void *user);
 
 /**
+ * Release the buffer that was given in the grab callback.
+ *
+ * \param[in] cam A uca_camera object
+ * \param[in] buffer The buffer that was passed to the callback
+ *
+ * \see uca_cam_register_callback(), uca_cam_grab_callback
+ * \since 0.5
+ */
+uint32_t uca_cam_release_buffer(struct uca_camera *cam, void *buffer);
+
+/**
  * \brief Grab one image from the camera
  * 
  * The grabbing involves a memory copy because we might have to decode the image
diff --git a/test/grab-async.c b/test/grab-async.c
index 43f9e1d..35ae5a4 100644
--- a/test/grab-async.c
+++ b/test/grab-async.c
@@ -26,7 +26,7 @@ struct image_props {
     uint32_t bits;
 };
 
-void grab_callback(uint64_t image_number, void *buffer, void *meta_data, void *user)
+enum uca_buffer_status grab_callback(uint64_t image_number, void *buffer, void *meta_data, void *user)
 {
     struct image_props *props = (struct image_props *) user;
     const int pixel_size = props->bits == 8 ? 1 : 2;
@@ -40,6 +40,8 @@ void grab_callback(uint64_t image_number, void *buffer, void *meta_data, void *u
     printf("grabbed picture %i at %p (%ix%i @ %i bits)\n", 
             (int) image_number, buffer, 
             props->width, props->height, props->bits);
+
+    return UCA_BUFFER_RELEASE;
 }
 
 int main(int argc, char *argv[])