From 9b65b8182769c7cf993e256444d331ffec9f2d02 Mon Sep 17 00:00:00 2001 From: Matthias Vogelgesang Date: Tue, 1 Mar 2011 09:47:10 +0100 Subject: Documentation added --- src/cameras/pco.c | 4 ++-- src/grabbers/me4.c | 2 +- src/uca-cam.h | 21 ++++++++++++++++++++- src/uca-grabber.h | 12 +++++++++++- src/uca.h | 8 ++++---- test/grab.c | 2 +- 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); -- cgit v1.2.3