List, Get and Set Device Properties

To control the settings of a device, unicap exports so called device properties. Like devices and video formats, a device property is identified by its identifier. Which properties are supported, how they are called and how exactly they work is determined by the video capture device or by the driver conrolling the device.

unicap tries to achieve a consistent interface to properties for all different kinds of video capture devices. However due to the different nature of many video capture devices ( a frame grabber has totally different settings compared to a camera ), there is no standard set of properties and they may behave differently on different devices.

The property is identified by the identifier field.

The category field contains a string with a category name which can be used by user interfaces to make it easier to navigate through the properties.

The relations is an array containing relations_count elements. Each element contains the identifier of a property which may also change when changing this property.

There are different types of properties which behave slightly different. There are range, value list, menu, data and flags properties. The type is determined by the type field.

range properties accept a value of type double. The value has to be in the range from property.range.min to property.range.max

value list properties also accept a value of type double. This value has to be the same as one element of the property.value_list.values array.

menu properties accept a string in the menu_item field. The string has to be the same as one element of the property.menu.menu_items array.

data properties accept an arbitrary amount of data pointed to in the property_data field. property_data_size should be set to the size of the data block in bytes. While all properties may accept optional data in the property_data field, data properties will not evaluate the value or menu_item field.

flags properties only evaluate the flags and flags_mask field.

The following code example shows how to get a list of all supported 'range' properties, inquire the current state of a property and set a new value for a range property:

Remarks:

1. Use unicap_enumerate_properties to get the supported device properties, one after another. The function will return STATUS_NO_MATCH when you reached the end of the list of supported properties.

2. The type field contains the type of the property. This example only handles range properties so they are filtered here.

3. Use unicap_get_property to read the current state of the property. The unicap_property_t structure passed to unicap needs to have the identifier field set to the identifier of the property requested.

4. Use unicap_set_property to set the new value on the device. Please note that sometimes the device may alter the actual value of the property. Some cameras for example can only set the exposure time in certain steps. Setting a value inbetween two steps will cause the device to adjust the value to the next available step. A subsequent call to unicap_get_property should give the actual value in such a case.

Menu Properties

The following code example shows how to get a list of all supported 'menu' properties, inquire the current state of a property and set a new menu item on the property:

Remarks:

1. The menu_item field contains the current setting of a menu property.

2. The menu.menu_item_count field contains the number of items present in the menu.menu_items array.

3. The menu.menu_items is an array of strings, one for each supported setting.

4. To set a menu item, copy the string to the menu_item field.