Parameter Access Functions

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.

Available Functions

• Generic access:
  • pl_get_param - returns the value of any attribute
  • pl_set_param - sets new value of 'current' attribute
• Enumeration items listing:
  • pl_enum_str_length - returns the enumerated parameter description string length
  • pl_get_enum_param - returns numeric value and string for an enumerated parameter

Parameter Attributes

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:

• ATTR_CURRENT - current parameter value, the only attribute that can be modified via pl_set_param for writable parameters

The following three attributes are guaranteed to not fail when accessed:

• ATTR_AVAIL - before the application accesses parameter values, the parameter availability in the current PVCAM version and with the camera used should be checked. Errors will be reported if an unavailable parameter is accessed with other functions.
  The returned value type is always rs_bool.
• ATTR_ACCESS - defines parameter access mode (read-only, read-write etc.). All access types are listed in PL_PARAM_ACCESS enum.
  The returned value type is always uns16.
• ATTR_TYPE - the data type of values returned for all attributes other than ATTR_COUNT. Type definitions can be found in pvcam.h header file.
  The returned value type is always 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.

• ATTR_TYPE of a parameter can be one of the following:
  • numeric - integral or floating-point, described by a range <min,max> and step (increment)
  • boolean - described by a range <min,max>, step not applicable
  • string - described by the length reported via ATTR_COUNT
  • enumeration - See Enumeration Parameters section
  • special - e.g. returns smart_stream_type structure, see SMART Streaming chapter

Reading Parameters

Prior to reading any parameter value, its availability should be checked via ATTR_AVAIL:

bool PvcamWrapperClass::IsParamAvailable(int16 hcam, uns32 paramID)
{
    // Ensure that access to PVCAM is synchronized
    std::lock_guard<std::mutex> lock(m_pvcamApiMutex);

    rs_bool isAvail;
    if (PV_OK != pl_get_param(hcam, paramID, ATTR_AVAIL, &isAvail))
    {
        // TODO: Handle error
        return false;
    }
    return isAvail == TRUE;
}

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.

#ifdef DEBUG
    // Optional check, ensure the type is as expected
    uns16 type;
    if (PV_OK != pl_get_param(hcam, PARAM_TEMP_SETPOINT, ATTR_TYPE, (void*)&type))
        return false;
    assert(type == TYPE_INT16);
#endif

    int16 min, max, inc;
    if (PV_OK != pl_get_param(hcam, PARAM_TEMP_SETPOINT, ATTR_MIN, (void*)&min))
        return false;
    if (PV_OK != pl_get_param(hcam, PARAM_TEMP_SETPOINT, ATTR_MAX, (void*)&max))
        return false;
    if (PV_OK != pl_get_param(hcam, PARAM_TEMP_SETPOINT, ATTR_INCREMENT, (void*)&inc))
        return false;

Setting Parameters

Setting a parameter may fail if value passed in exceeds the parameter range, parameter is not writable, or it is not available.

int16 newTempSetpoint = -550; // -5.50 deg C
if (PV_OK != pl_set_param(hcam, PARAM_TEMP_SETPOINT, (void*)&newTempSetpoint))
    return false;

Enumeration Parameters

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.

bool PvcamWrapperClass::DumpEnumParamItems(int16 hcam, uns32 paramID)
{
    // Ensure that access to PVCAM is synchronized
    std::lock_guard<std::mutex> lock(m_pvcamApiMutex);

    uns32 count;
    if (PV_OK != pl_get_param(hcam, paramID, ATTR_COUNT, (void*)&count))
    {
        // TODO: Handle error
        return false;
    }
    for (uns32 n = 0; n < count; ++n)
    {
        uns32 strLength;
        if (PV_OK != pl_enum_str_length(hcam, paramID, n, &strLength))
        {
            // TODO: Handle error
            return false;
        }
        char* text = new (std::nothrow) char[strLength];
        if (!text)
        {
            // TODO: Handle error
            return false;
        }
        int32 value;
        if (PV_OK != pl_get_enum_param(hcam, paramID, n, &value, text, strLength))
        {
            // TODO: Handle error
            delete [] text;
            return false;
        }
        printf("Item at index %u, value: %d, text: '%s'\n", n, value, text);
        delete [] text;
    }
    return true;
}

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.