|  |  |  | Unicap Reference Manual | |
|---|---|---|---|---|
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; #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_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);
typedef enum
{
	UNICAP_BUFFER_TYPE_USER = 0, 
	UNICAP_BUFFER_TYPE_SYSTEM,
} unicap_buffer_type_t;
typedef struct unicap_property_value_list_t unicap_property_value_list_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;
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:
 
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;
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);
Checks that the unicap library version is compatible with given version
| 
 | major version to check against | 
| 
 | minor version to check against | 
| 
 | micro version to check against | 
| Returns : | TRUE if compatible | 
unicap_status_t unicap_reenumerate_devices (int *count);
Rebuild internal list of devices.
| 
 | if not NULL, receives number of devices found | 
| Returns : | status | 
unicap_status_t unicap_enumerate_devices (unicap_device_t *specifier, unicap_device_t *device, int index);
Enumerates currently connected video capture devices
| 
 | specifies which devices should be returned, or NULL | 
| 
 | receives the device | 
| 
 | |
| Returns : | status | 
unicap_status_t     unicap_open                         (unicap_handle_t *handle,
                                                         unicap_device_t *device);
Acquire a handle to a device.
| 
 | receives the new handle | 
| 
 | device to open, as returned by unicap_enumerate_devices | 
| Returns : | status | 
unicap_status_t     unicap_register_callback            (unicap_handle_t handle,
                                                         unicap_event_t event,
                                                         unicap_callback_t func,
                                                         void *user_ptr);
| 
 | |
| 
 | |
| 
 | |
| 
 | user provided data that gets passed to the callback function | 
| Returns : | 
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.
| 
 | |
| Returns : | status | 
unicap_status_t     unicap_get_device                   (unicap_handle_t handle,
                                                         unicap_device_t *device);
Gets the device controled by handle
| 
 | |
| 
 | |
| Returns : | status | 
unicap_handle_t unicap_clone_handle (unicap_handle_t old_handle);
Copies the handle, increment the reference count
| 
 | |
| Returns : | new handle | 
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().
| 
 | |
| 
 | Receives the number of formats currently supported by the device. Might be NULL | 
| Returns : | status | 
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
| 
 | |
| 
 | limits the enumerated formats to the ones matching the fields in specifier. Fields set to -1 in the specifier are ignored | 
| 
 | |
| 
 | index of the format in the enumeration | 
| Returns : | STATUS_NO_MORE_FORMATS: end of the list of matching formats has been reached | 
unicap_status_t     unicap_set_format                   (unicap_handle_t handle,
                                                         unicap_format_t *format);
Set a format.
| 
 | |
| 
 | |
| Returns : | STATUS_NO_MATCH: given format not valid for device | 
unicap_status_t     unicap_get_format                   (unicap_handle_t handle,
                                                         unicap_format_t *format);
Get the current format
| 
 | |
| 
 | |
| Returns : | status | 
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()
| 
 | |
| 
 | receives number of properties supported by the device. Might be NULL | 
| Returns : | status | 
unicap_status_t     unicap_enumerate_properties         (unicap_handle_t handle,
                                                         unicap_property_t *specifier,
                                                         unicap_property_t *property,
                                                         int index);
Enumerate properties matching "specifier"
| 
 | |
| 
 | |
| 
 | |
| 
 | |
| Returns : | status | 
unicap_status_t     unicap_set_property                 (unicap_handle_t handle,
                                                         unicap_property_t *property);
Set a device property
| 
 | |
| 
 | |
| Returns : | status | 
unicap_status_t     unicap_set_property_value           (unicap_handle_t handle,
                                                         char *identifier,
                                                         double value);
Set a RANGE or VALUE_LIST property
| 
 | |
| 
 | identifier of the property to set | 
| 
 | new value | 
| Returns : | status | 
unicap_status_t     unicap_set_property_manual          (unicap_handle_t handle,
                                                         char *identifier);
Sets a property to manual mode, disabling the automatic mode
| 
 | |
| 
 | identifier of the property to set | 
| Returns : | status | 
unicap_status_t     unicap_set_property_auto            (unicap_handle_t handle,
                                                         char *identifier);
Sets the property to automatic mode
| 
 | |
| 
 | identifier of the property to set | 
| Returns : | status | 
unicap_status_t     unicap_set_property_one_push        (unicap_handle_t handle,
                                                         char *identifier);
Enable one push mode on a property
| 
 | |
| 
 | identifier of the property to set | 
| Returns : | status | 
unicap_status_t     unicap_get_property                 (unicap_handle_t handle,
                                                         unicap_property_t *property);
Get a device property
| 
 | |
| 
 | |
| Returns : | status | 
unicap_status_t     unicap_get_property_value           (unicap_handle_t handle,
                                                         const char *identifier,
                                                         double *value);
Returns the value of a property
| 
 | |
| 
 | identifier of the property to query | 
| 
 | |
| Returns : | status | 
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.
| 
 | |
| 
 | identifier of the property to query | 
| 
 | pointer to store the string location | 
| Returns : | status | 
unicap_status_t     unicap_get_property_auto            (unicap_handle_t handle,
                                                         const char *identifier,
                                                         int *enabled);
| 
 | |
| 
 | identifier of the property to query | 
| 
 | location to store the enabled flag | 
| Returns : | whether the auto mode of a property is enabled. | 
unicap_status_t unicap_start_capture (unicap_handle_t handle);
Start the capture device. After this call, unicap_wait_buffer calls are allowed
| 
 | |
| Returns : | 
unicap_status_t unicap_stop_capture (unicap_handle_t handle);
Stop the capture device
| 
 | |
| Returns : | 
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
| 
 | |
| 
 | |
| Returns : | 
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.
| 
 | |
| 
 | receives the dequeued buffer or NULL if no buffer was queued | 
| Returns : | status | 
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.
| 
 | |
| 
 | |
| Returns : | status |