Documentation added

6 files changed, 39 insertions, 10 deletions

diff --git a/src/cameras/pco.c b/src/cameras/pco.c
index cfb5d6b..45d0f62 100644
--- a/src/cameras/pco.c
+++ b/src/cameras/pco.c
@@ -186,10 +186,10 @@ uint32_t uca_pco_stop_recording(struct uca_camera_t *cam)
         return UCA_ERR_PROP_GENERAL;
 }
 
-uint32_t uca_pco_grab(struct uca_camera_t *cam, char *buffer, size_t n_bytes)
+uint32_t uca_pco_grab(struct uca_camera_t *cam, char *buffer)
 {
     uint16_t *frame;
-    uint32_t err = cam->grabber->grab(cam->grabber, (void **) &frame, n_bytes);
+    uint32_t err = cam->grabber->grab(cam->grabber, (void **) &frame);
     if (err != UCA_NO_ERROR)
         return err;
     /* FIXME: choose according to data format */
diff --git a/src/grabbers/me4.c b/src/grabbers/me4.c
index e907014..b52b48f 100644
--- a/src/grabbers/me4.c
+++ b/src/grabbers/me4.c
@@ -71,7 +71,7 @@ uint32_t uca_me4_stop_acquire(struct uca_grabber_t *grabber)
     return UCA_NO_ERROR;
 }
 
-uint32_t uca_me4_grab(struct uca_grabber_t *grabber, void **buffer, size_t n_bytes)
+uint32_t uca_me4_grab(struct uca_grabber_t *grabber, void **buffer)
 {
     int32_t last_frame;
     if (grabber->asynchronous)
diff --git a/src/uca-cam.h b/src/uca-cam.h
index db780da..5710b0a 100644
--- a/src/uca-cam.h
+++ b/src/uca-cam.h
@@ -12,6 +12,11 @@ enum uca_property_ids;
 /*
  * --- non-virtual methods ----------------------------------------------------
  */
+
+/**
+ * \brief Allocates buffer memory for the internal frame grabber
+ * \param[in] n_buffers Number of sub-buffers with size frame_width*frame_height
+ */
 uint32_t uca_cam_alloc(struct uca_camera_t *cam, uint32_t n_buffers);
 
 enum uca_cam_state uca_cam_get_state(struct uca_camera_t *cam);
@@ -47,11 +52,25 @@ typedef uint32_t (*uca_cam_set_property) (struct uca_camera_t *cam, enum uca_pro
  */
 typedef uint32_t (*uca_cam_get_property) (struct uca_camera_t *cam, enum uca_property_ids property, void *data);
 
+/**
+ * \brief 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_t *cam);
 
 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, size_t n_bytes);
+/**
+ * \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
+ */
+typedef uint32_t (*uca_cam_grab) (struct uca_camera_t *cam, char *buffer);
 
 
 enum uca_cam_state {
diff --git a/src/uca-grabber.h b/src/uca-grabber.h
index dd68688..4485b07 100644
--- a/src/uca-grabber.h
+++ b/src/uca-grabber.h
@@ -46,9 +46,19 @@ typedef uint32_t (*uca_grabber_alloc) (struct uca_grabber_t *grabber, uint32_t n
  */
 typedef uint32_t (*uca_grabber_acquire) (struct uca_grabber_t *grabber, int32_t n_frames);
 
+/**
+ * \brief Stop acquiring frames
+ */
 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, size_t n_bytes);
+/**
+ * \brief Grab a frame
+ *
+ * This method is usually called through the camera interface and not directly.
+ *
+ * \param[in] buffer The pointer of the frame buffer is set here
+ */
+typedef uint32_t (*uca_grabber_grab) (struct uca_grabber_t *grabber, void **buffer);
 
 
 struct uca_grabber_t {
diff --git a/src/uca.h b/src/uca.h
index 893d51c..c65d509 100644
--- a/src/uca.h
+++ b/src/uca.h
@@ -124,11 +124,11 @@ enum uca_errors {
     UCA_ERR_PROP_GENERAL,               /**< error occured reading/writing the property */
     UCA_ERR_PROP_VALUE_OUT_OF_RANGE,    /**< error occured writing the property */
 
-    UCA_ERR_CAM_ARM,
-    UCA_ERR_CAM_RECORD,
+    UCA_ERR_CAM_ARM,                    /**< camera is not armed */
+    UCA_ERR_CAM_RECORD,                 /**< could not record */
 
-    UCA_ERR_GRABBER_ACQUIRE,
-    UCA_ERR_GRABBER_NOMEM
+    UCA_ERR_GRABBER_ACQUIRE,            /**< grabber couldn't acquire a frame */
+    UCA_ERR_GRABBER_NOMEM               /**< no memory was allocated using uca_grabber->alloc() */
 };
 
 struct uca_t {
diff --git a/test/grab.c b/test/grab.c
index aeed8c6..e2973dc 100644
--- a/test/grab.c
+++ b/test/grab.c
@@ -29,7 +29,7 @@ int main(int argc, char *argv[])
     uint16_t *buffer = (uint16_t *) malloc(width * height * 2);
 
     cam->start_recording(cam);
-    cam->grab(cam, (char *) buffer, width*height*2);
+    cam->grab(cam, (char *) buffer);
     cam->stop_recording(cam);
     uca_destroy(uca);