## unicap unicap |

## Synopsis

    enum                unicap_buffer_type_t;
                        unicap_device_t;
                        unicap_rect_t;
                        unicap_format_t;
                        unicap_data_buffer_t;
    enum                unicap_property_flags_t;
                        unicap_property_range_t;
                        unicap_property_value_list_t;
                        unicap_property_menu_t;
    enum                unicap_property_type_enum_t;
                        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 callback,
                                                             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 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 {
    	char identifier[128];
    	char model_name[128];
    	char vendor_name[128];

    	unsigned long long model_id;
    	unsigned int vendor_id;

    	char cpi_layer[1024];
    	char device[1024];

    	unsigned int flags;
    } unicap_device_t;

A struct defining a device

char `identifier`[128]; | unique textual ID of a device
char `model_name`[128]; | model name of the device
char `vendor_name`[128]; | name of the device vendor
unsigned int `vendor_id`; | numerical ID of the vendor ( eg. USB Vendor ID )
char `cpi_layer`[1024]; | name of the plugin used to communicate with the device
char `device`[1024]; | name of the device file, if any
unsigned int `flags`; | flags

### unicap_rect_t

    typedef struct {
    	int x;
    	int y;
    	int width;
    	int height;
    } unicap_rect_t;

A struct defining a rectangle

int `x`; | horizontal position
int `y`; | vertical position
int `width`; | width of the rectangle
int `height`; | height of the rectangle

### unicap_format_t

    typedef struct {
          char identifier[128];

          unicap_rect_t size;

          unicap_rect_t min_size;
          unicap_rect_t max_size;

          int h_stepping;
          int v_stepping;
          unicap_rect_t *sizes;
          int size_count;

          int bpp;
          unsigned int fourcc;
          unicap_format_flags_t flags;

          unsigned int buffer_types;
          int system_buffer_count;

          size_t buffer_size;

          unicap_buffer_type_t buffer_type;
    } unicap_format_t;

char `identifier`[128]; | unique textual identifier of this format
unicap_rect_t `size`; | size of the format
unicap_rect_t `min_size`; | minimum size
unicap_rect_t `max_size`; | maximum size
int `h_stepping`; | horizontal stepping
int `v_stepping`; | vertical stepping
unicap_rect_t *`sizes`; | array of allowed sizes. Might be NULL
int `size_count`; | number of element in the sizes array
int `bpp`; | bits per pixel
unsigned int `fourcc`; | FOURCC describing the colour format
unicap_format_flags_t `flags`; |
unsigned int `buffer_types`; |
int `system_buffer_count`; |
size_t `buffer_size`; | amount of memory required by one data buffer of this format
unicap_buffer_type_t `buffer_type`; |

### unicap_data_buffer_t

    typedef struct {
       unicap_format_t format;

       int frame_number;
       struct timeval fill_time;
       struct timeval duration;
       struct timeval capture_start_time;

       unsigned char *data;
       size_t buffer_size;

       unicap_buffer_type_t type;

       unicap_buffer_flags_t flags;

       unicap_data_buffer_private_t *private;
    } unicap_data_buffer_t;

unicap_format_t `format`; | a unicap_format_t describing the layout of the data buffer
int `frame_number`; |
struct timeval `fill_time`; | the time when capturing completed on this buffer
struct timeval `duration`; | frame duration of this buffer ( might not be present on all devices )
struct timeval `capture_start_time`; | the time when the capturing started on this buffer ( might not be supported on all devices )
unsigned char *`data`; | the image data
size_t `buffer_size`; | size of the memory buffer pointed to by data
unicap_buffer_type_t `type`; |
unicap_buffer_flags_t `flags`; |
unicap_data_buffer_private_t *`private`; |

### enum unicap_property_flags_t

    typedef enum
    {
       UNICAP_FLAGS_MANUAL              = 1ULL,
       UNICAP_FLAGS_AUTO                = (1ULL<<1ULL),
       UNICAP_FLAGS_ONE_PUSH            = (1ULL<<2ULL),
       UNICAP_FLAGS_READ_OUT            = (1ULL<<3ULL),
       UNICAP_FLAGS_ON_OFF              = (1ULL<<4ULL),
       UNICAP_FLAGS_READ_ONLY           = (1ULL<<5ULL),
       UNICAP_FLAGS_FORMAT_CHANGE       = (1ULL<<6ULL),
       UNICAP_FLAGS_WRITE_ONLY          = (1ULL<<7ULL),

       UNICAP_FLAGS_CHECK_STEPPING      = (1ULL<<32ULL),

       UNICAP_FLAGS_DUMMY_VALUE         = (0xffffffffffffffffULL)
    } unicap_property_flags_t;

### unicap_property_range_t

    typedef struct {
    	double min;
    	double max;
    } unicap_property_range_t;

double `min`; | minimum value
double `max`; | maximum value

### unicap_property_value_list_t

    typedef struct {
    	double *values;
    	int value_count;
    } unicap_property_value_list_t;

double *`values`; | array of values
int `value_count`; | number of elements in values array

### unicap_property_menu_t

    typedef struct {
    	char **menu_items;
    	int menu_item_count;
    } unicap_property_menu_t;

char **`menu_items`; | an array of menu items
int `menu_item_count`; | number of elements in the menu_items array

### 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 {
          char identifier[128];
          char category[128];
          char unit[128];

          char **relations;
          int relations_count;

          union
    	    double value;
    	    char menu_item[128];

          union
    	    unicap_property_range_t range;
    	    unicap_property_value_list_t value_list;
    	    unicap_property_menu_t menu;

          double stepping;

          unicap_property_type_enum_t type;
          unicap_property_flags_t flags;
          unicap_property_flags_t flags_mask;

          void *property_data;
          size_t property_data_size;
    } unicap_property_t;

char `identifier`[128]; | unique textual identifier of this properties
char `category`[128]; | a category for this property, for example: 'Lens Control' for zoom and focus properties
char `unit`[128]; | optional unit, for example: 's' for Exposure denoting the Exposure time in seconds
char **`relations`; | properties that might their state or value when changing this property
int `relations_count`; | size of the relations array
char `menu_item`[128]; | for UNICAP_PROPERTY_TYPE_MENU properties: selected menu entry
unicap_property_value_list_t `value_list`; | for UNICAP_PROPERTY_TYPE_VALUE_LIST properties: list of valid values
unicap_property_menu_t `menu`; | for UNICAP_PROPERTY_TYPE_MENU properties: menu
double `stepping`; | for UNICAP_PROPERTY_TYPE_RANGE properties: stepping
unicap_property_type_enum_t `type`; | the type of the property
unicap_property_flags_t `flags`; | when enumerated, this field contains the default flags for the property; for get/set operations, this field contains the actual flags
unicap_property_flags_t `flags_mask`; | when enumerated, this field contains the allowed flags for the property; for get/set operations, this field acts as a mask
void *`property_data`; | a pointer to an opaque data structure
size_t `property_data_size`; | size of the data structure pointed at by property_data

### 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` : | number of the device to be enumerated
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 callback,
                                                             void *user_ptr);

`handle` : | a handle
`event` : | event to register a callback for
`callback` : | the callback function to call when the event occurs
`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` : | a 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` : | a handle
`device` : | a pointer to the location where the device should be stored
Returns : | status

### unicap_clone_handle ()

    unicap_handle_t     unicap_clone_handle                 (unicap_handle_t handle);

Copies the handle, increment the reference count

`handle` : | the handle to clone
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` : | A 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` : | A handle
`specifier` : | limits the enumerated formats to the ones matching the fields in specifier. Fields set to -1 in the specifier are ignored
`format` : | A pointer to allocated storage where the enumerated format shoudl be stored
`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` : | a handle
`format` : | the format to set
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` : | a handle
`format` : | a pointer to the location where the returned format should be stored
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` : | a 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` : | a handle
`specifier` : | specifier
`property` : | a pointer to the location where the enumerated property should be stored
`index` : | index of the property
Returns : | status

### unicap_set_property ()

    unicap_status_t     unicap_set_property                 (unicap_handle_t handle,
                                                             unicap_property_t *property);

Set a device property

`handle` : | a handle
`property` : | the property to set
Returns : | status

### unicap_set_property_value ()

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

`handle` : |
`identifier` : |
`value` : |
Returns : |

### 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` : | A 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` : | A 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` : | a 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` : | a handle
`property` : | a pointer to the location where the returned property should be stored
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` : | a handle
`identifier` : | identifier of the property to query
`value` : | a pointer to the location where the value should be stored
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` : | A 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);

Retrieve the current property auto mode

`handle` : | a handle
`identifier` : | identifier of the property to query
`enabled` : | location to store the enabled flag
Returns : | status

### 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` : | a handle
Returns : | status

### unicap_stop_capture ()

    unicap_status_t     unicap_stop_capture                 (unicap_handle_t handle);

Stop the capture device

`handle` : | A handle
Returns : | status

### 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` : | A handle
`data_buffer` : | A pointer to the buffer to queue
Returns : | status

### 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` : | A 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` : | A handle
`data_buffer` : | A pointer to the location where the returned buffer should be stored
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` : | A handle
`count` : | A pointer to the location where return value should be stored
Returns : | status