unicap

unicap

Synopsis




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

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

struct unicap_device_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

struct unicap_rect_t {
	int x;
	int y;	
	int width;
	int height;
};

A struct defining a rectangle


struct unicap_format_t

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

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

      unicap_buffer_flags_t flags;
      unsigned int reserved[7];		
};

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;
unsigned int reserved[7];

struct unicap_property_range_t

struct unicap_property_range_t {
	double min;
	double max;
};

double min; minimum value
double max; maximum value

struct unicap_property_value_list_t

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

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

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

struct unicap_property_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:
 


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