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

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

handle :

identifier :

value :

Returns :

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
Generated by GTK-Doc V1.14