![]() |
![]() |
![]() |
Unicap Reference Manual | |
---|---|---|---|---|
Top | Description |
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
);
typedef enum { UNICAP_BUFFER_TYPE_USER = 0, UNICAP_BUFFER_TYPE_SYSTEM, } unicap_buffer_type_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
unique textual ID of a device | |
model name of the device | |
name of the device vendor | |
numerical ID of the vendor ( eg. USB Vendor ID ) | |
name of the plugin used to communicate with the device | |
name of the device file, if any | |
flags |
typedef struct { int x; int y; int width; int height; } unicap_rect_t;
A struct defining a rectangle
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;
unique textual identifier of this format | |
unicap_rect_t |
size of the format |
unicap_rect_t |
minimum size |
unicap_rect_t |
maximum size |
horizontal stepping | |
vertical stepping | |
unicap_rect_t * |
array of allowed sizes. Might be NULL |
number of element in the sizes array | |
bits per pixel | |
FOURCC describing the colour format | |
amount of memory required by one data buffer of this format | |
unicap_buffer_type_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 *priv; } unicap_data_buffer_t;
unicap_format_t |
a unicap_format_t describing the layout of the data buffer |
the time when capturing completed on this buffer | |
frame duration of this buffer ( might not be present on all devices ) | |
the time when the capturing started on this buffer ( might not be supported on all devices ) | |
the image data | |
size of the memory buffer pointed to by data | |
unicap_buffer_type_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;
typedef struct { double *values; int value_count; } unicap_property_value_list_t;
typedef struct { char **menu_items; int menu_item_count; } unicap_property_menu_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;
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;
unique textual identifier of this properties | |
a category for this property, for example: 'Lens Control' for zoom and focus properties | |
optional unit, for example: 's' for Exposure denoting the Exposure time in seconds | |
properties that might their state or value when changing this property | |
size of the relations array | |
for UNICAP_PROPERTY_TYPE_MENU properties: selected menu entry | |
unicap_property_value_list_t |
for UNICAP_PROPERTY_TYPE_VALUE_LIST properties: list of valid values |
unicap_property_menu_t |
for UNICAP_PROPERTY_TYPE_MENU properties: menu |
for UNICAP_PROPERTY_TYPE_RANGE properties: stepping | |
the type of the property | |
unicap_property_flags_t |
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 |
when enumerated, this field contains the allowed flags for the property; for get/set operations, this field acts as a mask |
a pointer to an opaque data structure | |
size of the data structure pointed at by property_data |
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;
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
);
Checks that the unicap library version is compatible with given version
|
major version to check against |
|
minor version to check against |
|
micro version to check against |
Returns : |
TRUE if compatible |
unicap_status_t unicap_reenumerate_devices (int *count
);
Rebuild internal list of devices.
|
if not NULL, receives number of devices found |
Returns : |
status |
unicap_status_t unicap_enumerate_devices (unicap_device_t *specifier
,unicap_device_t *device
,int index
);
Enumerates currently connected video capture devices
|
specifies which devices should be returned, or NULL |
|
receives the device |
|
number of the device to be enumerated |
Returns : |
status |
unicap_status_t unicap_open (unicap_handle_t *handle
,unicap_device_t *device
);
Acquire a handle to a device.
|
receives the new handle |
|
device to open, as returned by unicap_enumerate_devices |
Returns : |
status |
unicap_status_t unicap_register_callback (unicap_handle_t handle
,unicap_event_t event
,unicap_callback_t callback
,void *user_ptr
);
|
a handle |
|
event to register a callback for |
|
the callback function to call when the event occurs |
|
user provided data that gets passed to the callback function |
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.
|
a handle |
Returns : |
status |
unicap_status_t unicap_get_device (unicap_handle_t handle
,unicap_device_t *device
);
Gets the device controled by handle
|
a handle |
|
a pointer to the location where the device should be stored |
Returns : |
status |
unicap_handle_t unicap_clone_handle (unicap_handle_t handle
);
Copies the handle, increment the reference count
|
the handle to clone |
Returns : |
new handle |
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()
.
|
A handle |
|
Receives the number of formats currently supported by the device. Might be NULL |
Returns : |
status |
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
|
A handle |
|
limits the enumerated formats to the ones matching the fields in specifier. Fields set to -1 in the specifier are ignored |
|
A pointer to allocated storage where the enumerated format shoudl be stored |
|
index of the format in the enumeration |
Returns : |
STATUS_NO_MORE_FORMATS: end of the list of matching formats has been reached |
unicap_status_t unicap_set_format (unicap_handle_t handle
,unicap_format_t *format
);
Set a format.
|
a handle |
|
the format to set |
Returns : |
STATUS_NO_MATCH: given format not valid for device |
unicap_status_t unicap_get_format (unicap_handle_t handle
,unicap_format_t *format
);
Get the current format
|
a handle |
|
a pointer to the location where the returned format should be stored |
Returns : |
status |
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()
|
a handle |
|
receives number of properties supported by the device. Might be NULL |
Returns : |
status |
unicap_status_t unicap_enumerate_properties (unicap_handle_t handle
,unicap_property_t *specifier
,unicap_property_t *property
,int index
);
Enumerate properties matching "specifier"
|
a handle |
|
specifier |
|
a pointer to the location where the enumerated property should be stored |
|
index of the property |
Returns : |
status |
unicap_status_t unicap_set_property (unicap_handle_t handle
,unicap_property_t *property
);
Set a device property
|
a handle |
|
the property to set |
Returns : |
status |
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
);
Sets a property to manual mode, disabling the automatic mode
|
A handle |
|
identifier of the property to set |
Returns : |
status |
unicap_status_t unicap_set_property_auto (unicap_handle_t handle
,char *identifier
);
Sets the property to automatic mode
|
A handle |
|
identifier of the property to set |
Returns : |
status |
unicap_status_t unicap_set_property_one_push (unicap_handle_t handle
,char *identifier
);
Enable one push mode on a property
|
a handle |
|
identifier of the property to set |
Returns : |
status |
unicap_status_t unicap_get_property (unicap_handle_t handle
,unicap_property_t *property
);
Get a device property
|
a handle |
|
a pointer to the location where the returned property should be stored |
Returns : |
status |
unicap_status_t unicap_get_property_value (unicap_handle_t handle
,const char *identifier
,double *value
);
Returns the value of a property
|
a handle |
|
identifier of the property to query |
|
a pointer to the location where the value should be stored |
Returns : |
status |
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.
|
A handle |
|
identifier of the property to query |
|
pointer to store the string location |
Returns : |
status |
unicap_status_t unicap_get_property_auto (unicap_handle_t handle
,const char *identifier
,int *enabled
);
Retrieve the current property auto mode
|
a handle |
|
identifier of the property to query |
|
location to store the enabled flag |
Returns : |
status |
unicap_status_t unicap_start_capture (unicap_handle_t handle
);
Start the capture device. After this call, unicap_wait_buffer calls are allowed
|
a handle |
Returns : |
status |
unicap_status_t unicap_stop_capture (unicap_handle_t handle
);
Stop the capture device
|
A handle |
Returns : |
status |
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
|
A handle |
|
A pointer to the buffer to queue |
Returns : |
status |
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.
|
A handle |
|
receives the dequeued buffer or NULL if no buffer was queued |
Returns : |
status |
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.
|
A handle |
|
A pointer to the location where the returned buffer should be stored |
Returns : |
status |