|
|
|
Unicap Reference Manual | |
|---|---|---|---|---|
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
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 |
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 |
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; |
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 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 *priv; |
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 min;
double max;
} unicap_property_range_t;
double min; |
minimum value |
double max; |
maximum value |
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 |
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 |
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;
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 |
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);
event : |
|
handle : |
|
buffer : |
|
user_ptr : |
void (*unicap_drop_frame_callback_t) (unicap_event_t event, unicap_handle_t handle, void *user_ptr);
event : |
|
handle : |
|
user_ptr : |
void (*unicap_new_device_callback_t) (unicap_event_t event, unicap_device_t *device, void *user_ptr);
event : |
|
device : |
|
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 : |
major version to check against |
minor : |
minor version to check against |
micro : |
micro version to check against |
| Returns : | TRUE if compatible |
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_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_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_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_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_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_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_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_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_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_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_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_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_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_status_t unicap_set_property_value (unicap_handle_t handle,
char *identifier,
double value);
Set a RANGE or VALUE_LIST property
handle : |
A handle |
identifier : |
identifier of the property to set |
value : |
new value |
| Returns : | status |
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_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_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_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_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_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_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_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_status_t unicap_stop_capture (unicap_handle_t handle);
Stop the capture device
handle : |
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
handle : |
A handle |
data_buffer : |
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.
handle : |
A handle |
data_buffer : |
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.
handle : |
A handle |
data_buffer : |
A pointer to the location where the returned buffer should be stored |
| Returns : | status |