Add extensive documentation

2 files changed, 197 insertions, 28 deletions

diff --git a/src/uca-cam.h b/src/uca-cam.h
index 367b7ab..80bf4e7 100644
--- a/src/uca-cam.h
+++ b/src/uca-cam.h
@@ -7,17 +7,30 @@
 extern "C" {
 #endif
 
+/**
+ * \file uca-cam.h
+ * \brief Abstract camera model
+ *
+ * The uca_camera_t structure represents a common interface for cameras regardless of
+ * their connectivity. Each camera that adheres to this model must provide an
+ * initialization function implementing uca_cam_init() that probes the device
+ * and sets all function pointers to their respective implementations.
+ */
+
 struct uca_camera_t;
 struct uca_grabber_t;
 struct uca_property_t;
 
 enum uca_property_ids;
 
+/**
+ * Describes the current state of the camera.
+ */
 enum uca_cam_state {
-    UCA_CAM_ERROR,
-    UCA_CAM_CONFIGURABLE,
-    UCA_CAM_ARMED,
-    UCA_CAM_RECORDING,
+    UCA_CAM_ERROR,          /**< Camera is not working correctly */
+    UCA_CAM_CONFIGURABLE,   /**< Camera can be configured and is not recording */
+    UCA_CAM_ARMED,          /**< Camera is ready for recording */
+    UCA_CAM_RECORDING,      /**< Camera is currently recording */
 };
 
 
@@ -26,11 +39,25 @@ enum uca_cam_state {
  */
 
 /**
- * \brief Allocates buffer memory for the internal frame grabber
- * \param[in] n_buffers Number of sub-buffers with size frame_width*frame_height
+ * Allocates buffer memory for the internal frame grabber.
+ *
+ * The allocation is just a hint to the underlying camera driver. It might
+ * ignore this or pass this information on to a related frame grabber.
+ *
+ * \param[in] cam A camera structure.
+ * 
+ * \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);
 
+/**
+ * Retrieve current state of the camera.
+ *
+ * \param[in] cam A camera structure.
+ *
+ * \return A value from the uca_cam_state enum representing the current state of
+ *   the camera.
+ */
 enum uca_cam_state uca_cam_get_state(struct uca_camera_t *cam);
 
 
@@ -39,41 +66,68 @@ enum uca_cam_state uca_cam_get_state(struct uca_camera_t *cam);
  */
 
 /**
- * \brief Camera probing and initialization
- * \return UCA_ERR_INIT_NOT_FOUND if camera is not found or could not be initialized
+ * Function pointer for camera probing and initialization. 
+ *
+ * \param[out] cam On success, *cam holds the newly created uca_camera_t
+ *   structure.
+ *
+ * \param[in] grabber Grabber structure to access the cam. Can be NULL to
+ *   specify devices without frame grabber access.
+ *
+ * \return 
+ *   UCA_ERR_INIT_NOT_FOUND if camera is not found or could not be initialized
+ *
+ * \note This is a private function and should be called exclusively by uca_init().
  */
 typedef uint32_t (*uca_cam_init) (struct uca_camera_t **cam, struct uca_grabber_t *grabber);
 
 /**
- * \brief Free camera resouces
+ * \brief Function pointer to free camera resources.
+ *
+ * \param[in] cam The camera to close.
+ *
+ * \note This is a private function and should be called exclusively by uca_init().
  */
 typedef uint32_t (*uca_cam_destroy) (struct uca_camera_t *cam);
 
 /**
- * \brief Set a property
+ * Function pointer to set a camera property.
+ *
+ * \param[in] cam The camera whose properties are to be set.
+ *
  * \param[in] property ID of the property as defined in XXX
+ *
  * \param[out] data Where to read the property's value from
+ *
  * \return UCA_ERR_PROP_INVALID if property is not supported on the camera or
- * UCA_ERR_PROP_VALUE_OUT_OF_RANGE if value cannot be set.
+ *   UCA_ERR_PROP_VALUE_OUT_OF_RANGE if value cannot be set.
  */
 typedef uint32_t (*uca_cam_set_property) (struct uca_camera_t *cam, enum uca_property_ids property, void *data);
 
 /**
- * \brief Get a property
+ * Function pointer to get a property.
+ *
+ * \param[in] cam The camera whose properties are to be retrieved.
+ *
  * \param[in] property ID of the property as defined in XXX
+ *
  * \param[out] data Where to store the property's value
+ *
  * \return UCA_ERR_PROP_INVALID if property is not supported on the camera
  */
 typedef uint32_t (*uca_cam_get_property) (struct uca_camera_t *cam, enum uca_property_ids property, void *data);
 
 /**
- * \brief Begin recording
+ * 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);
 
+/**
+ * Stop recording.
+ */
 typedef uint32_t (*uca_cam_stop_recording) (struct uca_camera_t *cam);
 
 /**
@@ -88,20 +142,53 @@ typedef uint32_t (*uca_cam_grab) (struct uca_camera_t *cam, char *buffer);
 
 
 struct uca_camera_t {
+    /**
+     * Points to the next available camera in a linked-list fashion.
+     *
+     * End of list is specified with next == NULL.
+     */
     struct uca_camera_t     *next;
 
     /* Function pointers to camera-specific methods */
+    /**
+     * Method to set a property.
+     * \see uca_cam_set_property
+     */
     uca_cam_set_property    set_property;
+
+    /**
+     * Method to get a property.
+     * \see uca_cam_get_property
+     */
     uca_cam_get_property    get_property;
+
+    /**
+     * Method to start recording.
+     * \see uca_cam_start_recording
+     */
     uca_cam_start_recording start_recording;
+
+    /**
+     * Method to stop recording.
+     * \see uca_cam_stop_recording
+     */
     uca_cam_stop_recording  stop_recording;
+
+    /**
+     * Method to grab a frame.
+     * \see uca_cam_grab
+     */
     uca_cam_grab            grab;
 
     /* Private */
+    /**
+     * Method to close the camera.
+     * \see uca_cam_destroy
+     */
     uca_cam_destroy         destroy;
 
-    struct uca_grabber_t    *grabber;
-    enum uca_cam_state      state;
+    struct uca_grabber_t    *grabber;   /**< grabber associated with this camera */
+    enum uca_cam_state      state;      /**< camera state */
     uint32_t                frame_width;
     uint32_t                frame_height;
 
diff --git a/src/uca.h b/src/uca.h
index fd7c079..ab59dc7 100644
--- a/src/uca.h
+++ b/src/uca.h
@@ -15,6 +15,54 @@ extern "C" {
  * to their respective implementation.
  */
 
+/**
+ * \mainpage
+ *
+ * \section intro_sec Introduction
+ *
+ * libuca is a thin wrapper to make different cameras and their access
+ * interfaces (via CameraLink, PCIe, Thunderbolt …) accessible in an easy way.
+ * It builds support for cameras, when it can find the necessary dependencies,
+ * so there is no need to have camera SDKs installed when you don't own a
+ * camera. 
+ *
+ * \section intro_quickstart Quick Start
+ *
+ * First you would create a new uca_t structure
+ *
+ * \code struct uca_t *uca = uca_init() \endcode
+ *
+ * and see if it is not NULL. If it is NULL, no camera or frame grabber was
+ * found. If you build with HAVE_DUMMY_CAMERA, there will always be at least the
+ * dummy camera available.
+ *
+ * You can then iterate through all available cameras using
+ * 
+ * \code
+ * struct uca_camera_t *i = uca->cameras;
+ * while (i != NULL) {
+ *     // do something with i
+ *     i = i->next;
+ * }
+ * \endcode
+ *
+ * With such a uca_camera_t structure, you can set properties, retrieve
+ * properties or start grabbing frames. Be aware, to check bit depth and frame 
+ * dimensions in order to allocate enough memory.
+ *
+ * \section intro_usage Adding new cameras
+ *
+ * Up to now, new cameras have to be integrated into libuca directly. Later on,
+ * we might provide a plugin mechanism. To add a new camera, add
+ * cameras/new-cam.c and cameras/new-cam.h to the source tree and change
+ * CMakeLists.txt to include these files. Furthermore, if this camera relies on
+ * external dependencies, these have to be found first via the CMake system.
+ *
+ * The new camera must export exactly one function: uca_new_camera_init() which
+ * checks if (given the grabber) the camera is available and sets the function
+ * pointers to access the camera accordingly.
+ */
+
 struct uca_t;
 struct uca_camera_t;
 struct uca_property_t;
@@ -73,7 +121,8 @@ enum uca_property_ids {
 };
 
 /**
- * \brief Initialize the unified camera access interface
+ * Initialize the unified camera access interface.
+ *
  * \return Pointer to a uca_t structure
  */
 struct uca_t *uca_init(void);
@@ -119,34 +168,62 @@ struct uca_property_t *uca_get_full_property(enum uca_property_ids property_id);
 
 
 /**
- * \brief Describe a property used by cameras and frame grabbers
+ * A uca_property_t describes a vendor-independent property used by cameras and
+ * frame grabbers. It basically consists of a human-readable name, a physical
+ * unit, a type and some access rights.
  */
 struct uca_property_t {
+    /**
+     * A human-readable string for this property.
+     *
+     * A name is defined in a tree-like structure, to build some form of
+     * hierarchical namespace. To define a parent-child-relationship a dot '.'
+     * is used. For example "image.width.min" might be the name for the minimal
+     * acceptable frame width.
+     */
     const char *name;
 
+    /**
+     * The physical unit of this property.
+     *
+     * This is important in order to let the camera drivers know, how to convert
+     * the values into their respective target value. It is also used for human
+     * interfaces.
+     */
     enum uca_unit {
-        uca_pixel = 0,
-        uca_bits,
-        uca_ns,     /**< nano seconds */
-        uca_us,     /**< micro seconds */
-        uca_ms,     /**< milli seconds */
-        uca_s,
-        uca_rows,
+        uca_pixel,  /**< number of pixels */
+        uca_bits,   /**< number of bits */
+        uca_ns,     /**< nanoseconds */
+        uca_us,     /**< microseconds */
+        uca_ms,     /**< milliseconds */
+        uca_s,      /**< seconds */
+        uca_rows,   /**< number of rows */
         uca_fps,    /**< frames per second */
         uca_dc,     /**< degree celsius */
-        uca_na
+        uca_na      /**< no unit available (for example modes) */
     } unit;
 
+    /**
+     * The data type of this property.
+     *
+     * When using uca_cam_set_property() and uca_cam_get_property() this field
+     * must be respected and correct data transfered, as the values are
+     * interpreted like defined here.
+     */
     enum uca_types {
         uca_uint32t,
         uca_uint8t,
         uca_string
     } type;
 
+    /**
+     * Access rights determine if uca_cam_get_property() and/or
+     * uca_cam_set_property() can be used with this property.
+     */
     enum uca_access_rights {
-        uca_read = 0x01,
-        uca_write = 0x02,
-        uca_readwrite = 0x01 | 0x02
+        uca_read = 0x01,                /**< property can be read */
+        uca_write = 0x02,               /**< property can be written */
+        uca_readwrite = 0x01 | 0x02     /**< property can be read and written */
     } access;
 };
 
@@ -167,8 +244,13 @@ enum uca_errors {
     UCA_ERR_GRABBER_NOMEM               /**< no memory was allocated using uca_grabber->alloc() */
 };
 
+/**
+ * Keeps a list of cameras and grabbers.
+ */
 struct uca_t {
     struct uca_camera_t *cameras;
+
+    /* private */
     struct uca_grabber_t *grabbers;
 };