![]() |
![]() |
![]() |
Unicap Reference Manual | |
---|---|---|---|---|
enum unicap_buffer_type_t; struct unicap_device_t; struct unicap_rect_t; struct unicap_format_t; struct unicap_data_buffer_t; struct unicap_property_range_t; struct unicap_property_value_list_t; struct unicap_property_menu_t; enum unicap_property_type_enum_t; struct 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_get_property (unicap_handle_t handle, unicap_property_t *property); 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;
struct unicap_device_t { 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; };
char identifier [128]; |
unique textual if 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 ; |
ID of the vendor like USB Vendor ID for example |
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 ; |
struct unicap_rect_t { int x; int y; int width; int height; };
A struct defining a rectangle
struct unicap_format_t { char identifier[128]; // default unicap_rect_t size; // min and max extends unicap_rect_t min_size; unicap_rect_t max_size; // stepping: // 0 if no free scaling available int h_stepping; int v_stepping; // array of possible sizes unicap_rect_t *sizes; int size_count; int bpp; unsigned int fourcc; unsigned int flags; unsigned int buffer_types; // available buffer types int system_buffer_count; size_t buffer_size; unicap_buffer_type_t buffer_type; };
char identifier [128]; |
unique textual identifier of this format |
unicap_rect_t max_size ; |
|
int v_stepping ; |
vertical stepping |
int size_count ; |
number of element in the sizes array |
int bpp ; |
bits per pixel |
unsigned int fourcc ; |
FOURCC describing the colour format |
unsigned int flags ; |
|
unsigned int buffer_types ; |
|
size_t buffer_size ; |
amount of memory required by one data buffer of this format |
unicap_buffer_type_t buffer_type ; |
struct unicap_data_buffer_t { unicap_format_t format; int frame_number; struct timeval fill_time; // struct timeval duration; struct timeval capture_start_time;// optional, time of first copy action of image data of this frame unsigned char *data; size_t buffer_size; unicap_buffer_type_t type; // system pointers or user pointers unsigned int reserved[8]; };
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 capture_start_time ; |
the time when the capturing started on this buffer ( might not be supported on all devices ) |
size_t buffer_size ; |
size of the memory buffer pointed to by data |
unicap_buffer_type_t type ; |
struct unicap_property_range_t { double min; double max; };
double min ; |
minimum value |
double max ; |
maximum value |
struct unicap_property_value_list_t { double *values; int value_count; };
double *values ; |
array of values |
int value_count ; |
number of elements in values array |
struct unicap_property_menu_t { char **menu_items; int menu_item_count; };
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;
struct unicap_property_t { 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]; };
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: flags_mask: property_data: property_data_size:
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 : |
|
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 func, void *user_ptr);
handle : |
|
event : |
|
func : |
|
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 : |
|
Returns : | status |
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_handle_t unicap_clone_handle (unicap_handle_t old_handle);
Copies the handle, increment the reference count
old_handle : |
|
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 : |
|
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 : |
|
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_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_status_t unicap_get_format (unicap_handle_t handle, unicap_format_t *format);
Get the current format
handle : |
|
format : |
|
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 : |
|
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 : |
|
specifier : |
|
property : |
|
index : |
|
Returns : | status |
unicap_status_t unicap_set_property (unicap_handle_t handle, unicap_property_t *property);
Set a device property
handle : |
|
property : |
|
Returns : | status |
unicap_status_t unicap_get_property (unicap_handle_t handle, unicap_property_t *property);
Get a device property
handle : |
|
property : |
|
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 : |
|
Returns : |
unicap_status_t unicap_stop_capture (unicap_handle_t handle);
Stop the capture device
handle : |
|
Returns : |
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_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_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 |