unicap

unicap

Synopsis

enum                unicap_buffer_type_t;
typedef             unicap_device_t;
typedef             unicap_rect_t;
typedef             unicap_format_t;
typedef             unicap_data_buffer_t;
typedef             unicap_property_range_t;
typedef             unicap_property_value_list_t;
typedef             unicap_property_menu_t;
enum                unicap_property_type_enum_t;
typedef             unicap_property_t;
enum                unicap_event_t;
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);

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


unicap_rect_t

typedef struct unicap_rect_t unicap_rect_t;

A struct defining a rectangle


unicap_format_t

typedef struct unicap_format_t unicap_format_t;


unicap_data_buffer_t

typedef struct unicap_data_buffer_t unicap_data_buffer_t;


unicap_property_range_t

typedef struct unicap_property_range_t unicap_property_range_t;


unicap_property_value_list_t

typedef struct unicap_property_value_list_t unicap_property_value_list_t;


unicap_property_menu_t

typedef struct unicap_property_menu_t unicap_property_menu_t;


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

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: when enumerated, this field contains the 
flags_mask:
property_data:
property_data_size:
 


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_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 :

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 func,
                                                         void *user_ptr);

handle :

event :

func :

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 :

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 :

device :

Returns :

status

unicap_clone_handle ()

unicap_handle_t     unicap_clone_handle                 (unicap_handle_t old_handle);

Copies the handle, increment the reference count

old_handle :

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 :

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 :

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

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

unicap_status_t     unicap_get_format                   (unicap_handle_t handle,
                                                         unicap_format_t *format);

Get the current format

handle :

format :

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 :

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 :

specifier :

property :

index :

Returns :

status

unicap_set_property ()

unicap_status_t     unicap_set_property                 (unicap_handle_t handle,
                                                         unicap_property_t *property);

Set a device property

handle :

property :

Returns :

status

unicap_get_property ()

unicap_status_t     unicap_get_property                 (unicap_handle_t handle,
                                                         unicap_property_t *property);

Get a device property

handle :

property :

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 :

Returns :


unicap_stop_capture ()

unicap_status_t     unicap_stop_capture                 (unicap_handle_t handle);

Stop the capture device

handle :

Returns :


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 :

data_buffer :

Returns :


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 :

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 :

data_buffer :

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 :

count :

Returns :

status