## unicap

unicap

## Synopsis

    enum                unicap_buffer_type_t;
    typedef             unicap_device_t;
    typedef             unicap_rect_t;
    typedef             unicap_format_t;
    typedef             unicap_data_buffer_t;
    typedef             unicap_property_range_t;
    typedef             unicap_property_value_list_t;
    typedef             unicap_property_menu_t;
    enum                unicap_property_type_enum_t;
    typedef             unicap_property_t;
    enum                unicap_event_t;
    #define             UNICAP_FLAGS_MANUAL
    #define             UNICAP_FLAGS_AUTO
    #define             UNICAP_FLAGS_ONE_PUSH
    #define             UNICAP_FLAGS_READ_OUT
    #define             UNICAP_FLAGS_ON_OFF
    #define             UNICAP_FLAGS_READ_ONLY
    #define             UNICAP_FLAGS_FORMAT_CHANGE
    void                (*unicap_callback_t)                (unicap_event_t event,
                                                             ...);
    void                (*unicap_new_frame_callback_t)      (unicap_event_t event,
                                                             unicap_handle_t handle,
                                                             unicap_data_buffer_t *buffer,
                                                             void *user_ptr);
    void                (*unicap_drop_frame_callback_t)     (unicap_event_t event,
                                                             unicap_handle_t handle,
                                                             void *user_ptr);
    void                (*unicap_new_device_callback_t)     (unicap_event_t event,
                                                             unicap_device_t *device,
                                                             void *user_ptr);
    unicap_status_t     unicap_check_version                (unsigned int major,
                                                             unsigned int minor,
                                                             unsigned int micro);
    unicap_status_t     unicap_reenumerate_devices          (int *count);
    unicap_status_t     unicap_enumerate_devices            (unicap_device_t *specifier,
                                                             unicap_device_t *device,
                                                             int index);
    unicap_status_t     unicap_open                         (unicap_handle_t *handle,
                                                             unicap_device_t *device);
    unicap_status_t     unicap_register_callback            (unicap_handle_t handle,
                                                             unicap_event_t event,
                                                             unicap_callback_t func,
                                                             void *user_ptr);
    unicap_status_t     unicap_close                        (unicap_handle_t handle);
    unicap_status_t     unicap_get_device                   (unicap_handle_t handle,
                                                             unicap_device_t *device);
    unicap_handle_t     unicap_clone_handle                 (unicap_handle_t old_handle);
    unicap_status_t     unicap_reenumerate_formats          (unicap_handle_t handle,
                                                             int *count);
    unicap_status_t     unicap_enumerate_formats            (unicap_handle_t handle,
                                                             unicap_format_t *specifier,
                                                             unicap_format_t *format,
                                                             int index);
    unicap_status_t     unicap_set_format                   (unicap_handle_t handle,
                                                             unicap_format_t *format);
    unicap_status_t     unicap_get_format                   (unicap_handle_t handle,
                                                             unicap_format_t *format);
    unicap_status_t     unicap_reenumerate_properties       (unicap_handle_t handle,
                                                             int *count);
    unicap_status_t     unicap_enumerate_properties         (unicap_handle_t handle,
                                                             unicap_property_t *specifier,
                                                             unicap_property_t *property,
                                                             int index);
    unicap_status_t     unicap_set_property                 (unicap_handle_t handle,
                                                             unicap_property_t *property);
    unicap_status_t     unicap_set_property_value           (unicap_handle_t handle,
                                                             char *identifier,
                                                             double value);
    unicap_status_t     unicap_set_property_manual          (unicap_handle_t handle,
                                                             char *identifier);
    unicap_status_t     unicap_set_property_auto            (unicap_handle_t handle,
                                                             char *identifier);
    unicap_status_t     unicap_set_property_one_push        (unicap_handle_t handle,
                                                             char *identifier);
    unicap_status_t     unicap_get_property                 (unicap_handle_t handle,
                                                             unicap_property_t *property);
    unicap_status_t     unicap_get_property_value           (unicap_handle_t handle,
                                                             const char *identifier,
                                                             double *value);
    unicap_status_t     unicap_get_property_menu            (unicap_handle_t handle,
                                                             const char *identifier,
                                                             char **value);
    unicap_status_t     unicap_get_property_auto            (unicap_handle_t handle,
                                                             const char *identifier,
                                                             int *enabled);
    unicap_status_t     unicap_start_capture                (unicap_handle_t handle);
    unicap_status_t     unicap_stop_capture                 (unicap_handle_t handle);
    unicap_status_t     unicap_queue_buffer                 (unicap_handle_t handle,
                                                             unicap_data_buffer_t *data_buffer);
    unicap_status_t     unicap_dequeue_buffer               (unicap_handle_t handle,
                                                             unicap_data_buffer_t **data_buffer);
    unicap_status_t     unicap_wait_buffer                  (unicap_handle_t handle,
                                                             unicap_data_buffer_t **data_buffer);
    unicap_status_t     unicap_poll_buffer                  (unicap_handle_t handle,
                                                             int *count);

## Description

## Details

### enum unicap_buffer_type_t

    typedef enum
    {
    	UNICAP_BUFFER_TYPE_USER = 0,
    	UNICAP_BUFFER_TYPE_SYSTEM,
    } unicap_buffer_type_t;

`UNICAP_BUFFER_TYPE_USER` | buffer is provided by the application
`UNICAP_BUFFER_TYPE_SYSTEM` | buffer is provided by the driver or library

### unicap_device_t

    typedef struct unicap_device_t unicap_device_t;

a struct defining a device

### unicap_rect_t

    typedef struct unicap_rect_t unicap_rect_t;

A struct defining a rectangle

### unicap_format_t

    typedef struct unicap_format_t unicap_format_t;

### unicap_data_buffer_t

    typedef struct unicap_data_buffer_t unicap_data_buffer_t;

### unicap_property_range_t

    typedef struct unicap_property_range_t unicap_property_range_t;

### unicap_property_value_list_t

    typedef struct unicap_property_value_list_t unicap_property_value_list_t;

### unicap_property_menu_t

    typedef struct unicap_property_menu_t unicap_property_menu_t;

### enum unicap_property_type_enum_t

    typedef enum
    {
    	UNICAP_PROPERTY_TYPE_RANGE = 0,
    	UNICAP_PROPERTY_TYPE_VALUE_LIST,
    	UNICAP_PROPERTY_TYPE_MENU,
    	UNICAP_PROPERTY_TYPE_DATA,
    	UNICAP_PROPERTY_TYPE_FLAGS,

    	UNICAP_PROPERTY_TYPE_UNKNOWN
    } unicap_property_type_enum_t;

`UNICAP_PROPERTY_TYPE_RANGE` | a property with a value in a given range
`UNICAP_PROPERTY_TYPE_VALUE_LIST` | a property with a value out of a list of values
`UNICAP_PROPERTY_TYPE_MENU` |
`UNICAP_PROPERTY_TYPE_DATA` |
`UNICAP_PROPERTY_TYPE_FLAGS` | a property where only the flags are valid
`UNICAP_PROPERTY_TYPE_UNKNOWN` |

### unicap_property_t

    typedef struct unicap_property_t unicap_property_t;

FIXME: gtk-doc fails to parse structs with anonymous unions.

          char identifier[128]; //mandatory
          char category[128];
          char unit[128]; //

          // list of properties identifier which value / behaviour may change if this property changes
          char **relations;
          int relations_count;

          union
          {
    	    double value; // default if enumerated
    	    char menu_item[128]; };

          union{
    	    unicap_property_range_t range; // if UNICAP_USE_RANGE is asserted
    	    unicap_property_value_list_t value_list; // if UNICAP_USE_VALUE_LIST is asserted
    	    unicap_property_menu_t menu; };

          double stepping;

          unicap_property_type_enum_t type;
          u_int64_t flags;        // defaults if enumerated
          u_int64_t flags_mask;	// defines capabilities if enumerated

          // optional data
          void *property_data;
          size_t property_data_size;

    identifier:   unique textual identifier of this properties
    category:     a category for this property, for example: 'Lens Control' for zoom and focus properties
    unit:         optional unit, for example: 's' for Exposure
    denoting the Exposure time in seconds
    relations:    properties that might their state or value when
    changing this property
    relations_count: size of the relations array
    value:           for UNICAP_PROPERTY_TYPE_RANGE and
    UNICAP_PROPERTY_TYPE_VALUE_LIST properties: current value
    menu_item:       for UNICAP_PROPERTY_TYPE_MENU properties: selected menu entry
    range:           for UNICAP_PROPERTY_TYPE_RANGE properties: valid range for value
    value_list:      for UNICAP_PROPERTY_TYPE_VALUE_LIST properties: list
    of valid values
    menu:            for UNICAP_PROPERTY_TYPE_MENU properties: menu
    stepping:        for UNICAP_PROPERTY_TYPE_RANGE properties: stepping
    type:
    flags: when enumerated, this field contains the
    flags_mask:
    property_data:
    property_data_size:

### enum unicap_event_t

    typedef enum
    {
    	UNICAP_EVENT_FIRST = 0,
    	UNICAP_EVENT_DEVICE_REMOVED = 0,
    	UNICAP_EVENT_NEW_DEVICE,
    	UNICAP_EVENT_NEW_FRAME,
    	UNICAP_EVENT_DROP_FRAME,
    	UNICAP_EVENT_LAST
    } unicap_event_t;

### UNICAP_FLAGS_MANUAL

    #define UNICAP_FLAGS_MANUAL         (1ULL)

### UNICAP_FLAGS_AUTO

    #define UNICAP_FLAGS_AUTO           (1ULL<<1ULL)

### UNICAP_FLAGS_ONE_PUSH

    #define UNICAP_FLAGS_ONE_PUSH       (1ULL<<2ULL)

### UNICAP_FLAGS_READ_OUT

    #define UNICAP_FLAGS_READ_OUT       (1ULL<<3ULL)

### UNICAP_FLAGS_ON_OFF

    #define UNICAP_FLAGS_ON_OFF         (1ULL<<4ULL)

### UNICAP_FLAGS_READ_ONLY

    #define UNICAP_FLAGS_READ_ONLY      (1ULL<<5ULL)

### UNICAP_FLAGS_FORMAT_CHANGE

    #define UNICAP_FLAGS_FORMAT_CHANGE  (1ULL<<6ULL)

### unicap_callback_t ()

    void                (*unicap_callback_t)                (unicap_event_t event,
                                                             ...);

`event` : |
`...` : |

### unicap_new_frame_callback_t ()

    void                (*unicap_new_frame_callback_t)      (unicap_event_t event,
                                                             unicap_handle_t handle,
                                                             unicap_data_buffer_t *buffer,
                                                             void *user_ptr);

`event` : |
`handle` : |
`buffer` : |
`user_ptr` : |

### unicap_drop_frame_callback_t ()

    void                (*unicap_drop_frame_callback_t)     (unicap_event_t event,
                                                             unicap_handle_t handle,
                                                             void *user_ptr);

`event` : |
`handle` : |
`user_ptr` : |

### unicap_new_device_callback_t ()

    void                (*unicap_new_device_callback_t)     (unicap_event_t event,
                                                             unicap_device_t *device,
                                                             void *user_ptr);

`event` : |
`device` : |
`user_ptr` : |

### unicap_check_version ()

    unicap_status_t     unicap_check_version                (unsigned int major,
                                                             unsigned int minor,
                                                             unsigned int micro);

Checks that the unicap library version is compatible with given version

`major` : | major version to check against
`minor` : | minor version to check against
`micro` : | micro version to check against
Returns : | TRUE if compatible

### unicap_reenumerate_devices ()

    unicap_status_t     unicap_reenumerate_devices          (int *count);

Rebuild internal list of devices.

`count` : | if not NULL, receives number of devices found
Returns : | status

### unicap_enumerate_devices ()

    unicap_status_t     unicap_enumerate_devices            (unicap_device_t *specifier,
                                                             unicap_device_t *device,
                                                             int index);

Enumerates currently connected video capture devices

`specifier` : | specifies which devices should be returned, or NULL
`device` : | receives the device
`index` : |
Returns : | status

### unicap_open ()

    unicap_status_t     unicap_open                         (unicap_handle_t *handle,
                                                             unicap_device_t *device);

Acquire a handle to a device.

`handle` : | receives the new handle
`device` : | device to open, as returned by unicap_enumerate_devices
Returns : | status

### unicap_register_callback ()

    unicap_status_t     unicap_register_callback            (unicap_handle_t handle,
                                                             unicap_event_t event,
                                                             unicap_callback_t func,
                                                             void *user_ptr);

`handle` : |
`event` : |
`func` : |
`user_ptr` : | user provided data that gets passed to the callback function
Returns : |

### unicap_close ()

    unicap_status_t     unicap_close                        (unicap_handle_t handle);

Clsoing a handle decrements the reference count on the device. If the reference count is 0, all resources associated with the device get freed.

`handle` : |
Returns : | status

### unicap_get_device ()

    unicap_status_t     unicap_get_device                   (unicap_handle_t handle,
                                                             unicap_device_t *device);

Gets the device controled by handle

`handle` : |
`device` : |
Returns : | status

### unicap_clone_handle ()

    unicap_handle_t     unicap_clone_handle                 (unicap_handle_t old_handle);

Copies the handle, increment the reference count

`old_handle` : |
Returns : | new handle

### unicap_reenumerate_formats ()

    unicap_status_t     unicap_reenumerate_formats          (unicap_handle_t handle,
                                                             int *count);

Re-create the list of formats supported by the device. Invalidates all data returned by prior calls to `unicap_emumerate_formats()` and `unicap_get_format()`.

`handle` : |
`count` : | Receives the number of formats currently supported by the device. Might be NULL
Returns : | status

### unicap_enumerate_formats ()

    unicap_status_t     unicap_enumerate_formats            (unicap_handle_t handle,
                                                             unicap_format_t *specifier,
                                                             unicap_format_t *format,
                                                             int index);

Enumerate formats known to the device

`handle` : |
`specifier` : | limits the enumerated formats to the ones matching the fields in specifier. Fields set to -1 in the specifier are ignored
`format` : |
`index` : | index of the format in the enumeration
Returns : | STATUS_NO_MORE_FORMATS: end of the list of matching formats has been reached

### unicap_set_format ()

    unicap_status_t     unicap_set_format                   (unicap_handle_t handle,
                                                             unicap_format_t *format);

Set a format.

`handle` : |
`format` : |
Returns : | STATUS_NO_MATCH: given format not valid for device

### unicap_get_format ()

    unicap_status_t     unicap_get_format                   (unicap_handle_t handle,
                                                             unicap_format_t *format);

Get the current format

`handle` : |
`format` : |
Returns : | status

### unicap_reenumerate_properties ()

    unicap_status_t     unicap_reenumerate_properties       (unicap_handle_t handle,
                                                             int *count);

Re-create the list of properties supported by the device. This invalidates all data returned by prior calls to `unicap_enumerate_properties()` and `unicap_get_property()`

`handle` : |
`count` : | receives number of properties supported by the device. Might be NULL
Returns : | status

### unicap_enumerate_properties ()

    unicap_status_t     unicap_enumerate_properties         (unicap_handle_t handle,
                                                             unicap_property_t *specifier,
                                                             unicap_property_t *property,
                                                             int index);

Enumerate properties matching "specifier"

`handle` : |
`specifier` : |
`property` : |
`index` : |
Returns : | status

### unicap_set_property ()

    unicap_status_t     unicap_set_property                 (unicap_handle_t handle,
                                                             unicap_property_t *property);

Set a device property

`handle` : |
`property` : |
Returns : | status

### unicap_set_property_value ()

    unicap_status_t     unicap_set_property_value           (unicap_handle_t handle,
                                                             char *identifier,
                                                             double value);

Set a RANGE or VALUE_LIST property

`handle` : |
`identifier` : | identifier of the property to set
`value` : | new value
Returns : | status

### unicap_set_property_manual ()

    unicap_status_t     unicap_set_property_manual          (unicap_handle_t handle,
                                                             char *identifier);

Sets a property to manual mode, disabling the automatic mode

`handle` : |
`identifier` : | identifier of the property to set
Returns : | status

### unicap_set_property_auto ()

    unicap_status_t     unicap_set_property_auto            (unicap_handle_t handle,
                                                             char *identifier);

Sets the property to automatic mode

`handle` : |
`identifier` : | identifier of the property to set
Returns : | status

### unicap_set_property_one_push ()

    unicap_status_t     unicap_set_property_one_push        (unicap_handle_t handle,
                                                             char *identifier);

Enable one push mode on a property

`handle` : |
`identifier` : | identifier of the property to set
Returns : | status

### unicap_get_property ()

    unicap_status_t     unicap_get_property                 (unicap_handle_t handle,
                                                             unicap_property_t *property);

Get a device property

`handle` : |
`property` : |
Returns : | status

### unicap_get_property_value ()

    unicap_status_t     unicap_get_property_value           (unicap_handle_t handle,
                                                             const char *identifier,
                                                             double *value);

Returns the value of a property

`handle` : |
`identifier` : | identifier of the property to query
`value` : |
Returns : | status

### unicap_get_property_menu ()

    unicap_status_t     unicap_get_property_menu            (unicap_handle_t handle,
                                                             const char *identifier,
                                                             char **value);

Returns the menu string of a property. Property must be of UNICAP_PROPERTY_TYPE_MENU type. The returned string is owned by the unicap library and might be overwritten by subsequent calls to unicap_get_property_menu.

`handle` : |
`identifier` : | identifier of the property to query
`value` : | pointer to store the string location
Returns : | status

### unicap_get_property_auto ()

    unicap_status_t     unicap_get_property_auto            (unicap_handle_t handle,
                                                             const char *identifier,
                                                             int *enabled);

`handle` : |
`identifier` : | identifier of the property to query
`enabled` : | location to store the enabled flag
Returns : | whether the auto mode of a property is enabled.

### unicap_start_capture ()

    unicap_status_t     unicap_start_capture                (unicap_handle_t handle);

Start the capture device. After this call, unicap_wait_buffer calls are allowed

`handle` : |
Returns : |

### unicap_stop_capture ()

    unicap_status_t     unicap_stop_capture                 (unicap_handle_t handle);

Stop the capture device

`handle` : |
Returns : |

### unicap_queue_buffer ()

    unicap_status_t     unicap_queue_buffer                 (unicap_handle_t handle,
                                                             unicap_data_buffer_t *data_buffer);

Queue a buffer to be filled by the capture device. The queued buffer must not be touched ( especially not be freed ) until it is in the ready queue or dequeued. Supplied buffer must be at least of the buffer size returned by get_format

`handle` : |
`data_buffer` : |
Returns : |

### unicap_dequeue_buffer ()

    unicap_status_t     unicap_dequeue_buffer               (unicap_handle_t handle,
                                                             unicap_data_buffer_t **data_buffer);

Removes the first buffer from the queue. Depending on the device:Can only be called if the capture device is stopped.

`handle` : |
`data_buffer` : | receives the dequeued buffer or NULL if no buffer was queued
Returns : | status

### unicap_wait_buffer ()

    unicap_status_t     unicap_wait_buffer                  (unicap_handle_t handle,
                                                             unicap_data_buffer_t **data_buffer);

Removes a buffer from the ready queue. If no buffer is available, this function blocks until a buffer got filled.

`handle` : |
`data_buffer` : |
Returns : | status

### unicap_poll_buffer ()

    unicap_status_t     unicap_poll_buffer                  (unicap_handle_t handle,
                                                             int *count);

Poll for buffers in the fill queue

`handle` : |
`count` : |
Returns : | status