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 *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;

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);

Set a RANGE or VALUE_LIST property

handle : A 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 : 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