unicap

unicap

Functions

void (*unicap_callback_t) ()
void (*unicap_new_frame_callback_t) ()
void (*unicap_drop_frame_callback_t) ()
void (*unicap_new_device_callback_t) ()
unicap_status_t unicap_check_version ()
unicap_status_t unicap_reenumerate_devices ()
unicap_status_t unicap_enumerate_devices ()
unicap_status_t unicap_open ()
unicap_status_t unicap_register_callback ()
unicap_status_t unicap_close ()
unicap_status_t unicap_get_device ()
unicap_handle_t unicap_clone_handle ()
unicap_status_t unicap_reenumerate_formats ()
unicap_status_t unicap_enumerate_formats ()
unicap_status_t unicap_set_format ()
unicap_status_t unicap_get_format ()
unicap_status_t unicap_reenumerate_properties ()
unicap_status_t unicap_enumerate_properties ()
unicap_status_t unicap_set_property ()
unicap_status_t unicap_set_property_value ()
unicap_status_t unicap_set_property_manual ()
unicap_status_t unicap_set_property_auto ()
unicap_status_t unicap_set_property_one_push ()
unicap_status_t unicap_get_property ()
unicap_status_t unicap_get_property_value ()
unicap_status_t unicap_get_property_menu ()
unicap_status_t unicap_get_property_auto ()
unicap_status_t unicap_start_capture ()
unicap_status_t unicap_stop_capture ()
unicap_status_t unicap_queue_buffer ()
unicap_status_t unicap_dequeue_buffer ()
unicap_status_t unicap_wait_buffer ()
unicap_status_t unicap_poll_buffer ()

Types and Values

Description

Functions

unicap_callback_t ()

void
(*unicap_callback_t) (unicap_event_t 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);

unicap_drop_frame_callback_t ()

void
(*unicap_drop_frame_callback_t) (unicap_event_t event,
                                 unicap_handle_t handle,
                                 void *user_ptr);

unicap_new_device_callback_t ()

void
(*unicap_new_device_callback_t) (unicap_event_t event,
                                 unicap_device_t *device,
                                 void *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

Parameters

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.

Parameters

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

Parameters

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.

Parameters

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

Parameters

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

 

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.

Parameters

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

Parameters

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

Parameters

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().

Parameters

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

Parameters

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.

Parameters

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

Parameters

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

Parameters

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"

Parameters

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

Parameters

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

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

Parameters

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

Parameters

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

Parameters

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

Parameters

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

Parameters

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.

Parameters

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

Parameters

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

Parameters

handle

a handle

 

Returns

status


unicap_stop_capture ()

unicap_status_t
unicap_stop_capture (unicap_handle_t handle);

Stop the capture device

Parameters

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

Parameters

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.

Parameters

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.

Parameters

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

Parameters

handle

A handle

 

count

A pointer to the location where return value should be stored

 

Returns

status

Types and Values

enum unicap_buffer_type_t

Members

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

Members

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

Members

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;

Members

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;

Members

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

Members

UNICAP_FLAGS_MANUAL

   

UNICAP_FLAGS_AUTO

   

UNICAP_FLAGS_ONE_PUSH

   

UNICAP_FLAGS_READ_OUT

   

UNICAP_FLAGS_ON_OFF

   

UNICAP_FLAGS_READ_ONLY

   

UNICAP_FLAGS_FORMAT_CHANGE

   

UNICAP_FLAGS_WRITE_ONLY

   

UNICAP_FLAGS_CHECK_STEPPING

   

UNICAP_FLAGS_DUMMY_VALUE

   

unicap_property_range_t

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

Members

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;

Members

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;

Members

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

Members

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;

Members

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

Members

UNICAP_EVENT_FIRST

   

UNICAP_EVENT_DEVICE_REMOVED

   

UNICAP_EVENT_NEW_DEVICE

   

UNICAP_EVENT_NEW_FRAME

   

UNICAP_EVENT_DROP_FRAME

   

UNICAP_EVENT_LAST

   

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)