![]() |
PVCAM
3.9.x
Programmable Virtual Camera Access Method library
|
In PVCAM, most of the functionality is controlled via parameters. Instead of multiple getter and setter functions, PVCAM provides a few generic functions that use parameter ID to access specific parameter values. The value itself is then passed in or out via void pointers, therefore care has to be taken to avoid any data-size issues.
Each parameter is fully described by a set of values. The pl_get_param function returns attribute values based on the attribute specified in the argument passed in. Available attributes are described in PL_PARAM_ATTRIBUTES enum.
The most frequently used attribute:
The following three attributes are guaranteed to not fail when accessed:
rs_bool
.uns16
.uns16
.The meaning of remaining attributes changes based on the parameter type. As an example, ATTR_COUNT value defines number of enumeration items of TYPE_ENUM parameter, while number of characters in string is returned for TYPE_CHAR_PTR parameter. For numeric parameters, the count holds number of valid values with zero being reported where ATTR_INCREMENT is 0 thus number of available values cannot be calculated, or where all values in a given range are allowed.
Prior to reading any parameter value, its availability should be checked via ATTR_AVAIL:
Due to the fact that PVCAM parameter types do not change dynamically and their values are documented, reading the type attribute is optional. E.g. PARAM_TEMP_SETPOINT is documented to provide the desired sensor temperature in hundredths of degrees Celsius as int16
value.
Setting a parameter may fail if value passed in exceeds the parameter range, parameter is not writable, or it is not available.
Enumeration type parameter values may not be sequential or ordered.
The number of items in an enumeration is reported via ATTR_COUNT attribute. Iterating from 0 through count-1
passed in to pl_get_enum_param function as index provides the value together with a short descriptive string for every item. The length of the string can be read via pl_enum_str_length call which allows dynamic buffer allocation before reading the string.
If the enumeration type parameter is writable, the valid value passed to pl_set_param function should be one of the values returned from pl_get_enum_param as shown in above snippet, not the index. The same value is also returned by pl_get_param for ATTR_CURRENT.