Parameter Introspection

Several places in fluxEngine allow the user to generically set parameters. For now this consists of:

• Device connection parameters: the parameters that are passed to the driver when connecting to a device.

  In this case, as all the parameters are required in a single step, they are passed as a string to string map to fluxEngine (std::unordered_map<std::string, std::string>).

  However, internally fluxEngine uses the same description language to describe which parameters exist and what their properties are.

  See Connecting to a Device for details.

• Device parameters: the parameters of a device that exist when it has already been connected, and the user may dynamically change these parameters.

  In this case special accessor methods exist to read and write the parameters for the device.

  See Accessing Device Parameters for details.

In either case if the parameters are already known to the user, it is not necessary to perform any introspection, because it is possible to simply set the parameters to their desired values manually.

However, fluxEngine also provides the user with the ability to query which parameters are available, their type, as well as their limits.

This is abstracted away in the fluxEngine::ParameterInfo class that provides this information. There are multiple accessors that obtain such a structure:

• The result of fluxEngine::enumerateDevices() will return a set of structures that contain objects of this type. They describe which connection parameters are available for individual devices.

• For connected devices fluxEngine::Device::parameterList() provides a means of obtaining such a structure.

Note

The introspection information provided for connected devices is dynamic. For example, if changing a parameter A changes the allowed limits of a parameter B, the information returne when querying the fluxEngine::ParameterInfo object will change together with a change to parameter A. The fluxEngine::ParameterInfo object will track the current device state internally.

Parameter Types

There are several different parameter types. These describe how data is stored for a given parameter. The following types are currently exposed by fluxEngine’s public API:

• Boolean: a true or false value

• Integer: an integer value

• Float: a floating point value

• Enumeration: a value that is selected from a list of allowed values (each entry in the list of allowed values has an integer value and a name, which is a string)

• String: a string (typically these are read-only strings that may be read from devices to obtain metadata, such as the firmware version, but it is possible to have read-write string parameters)

• File: only for connection parameters: a file name that should be specified by the user. These are treated as strings internally, but the type indicates that a file name is actually requested. For example, the connection GUI in fluxTrainer and fluxRecorder uses the information that the parameter is of this type to provide the user with a file selection box

• Command: not for connection parameters: these parameters allow the user to execute a specific action. For example, this could be a command that issues a device reset.

• Unknown: any parameter type that is currently not exposed to fluxEngine’s public API

Information about Parameters

There are several means of obtaining information about a specific parameter from fluxEngine.

• For all supported C++ standard versions: there are several accessor methods to access the various bits of information from the fluxEngine::ParameterInfo class. The various accessor will be discussed below.

• For C++17 and higher: there is ParameterInfo::parameter() and ParameterInfo::parameters() to obtain all information at the same time. See the reference documentation of the fluxEngine::ParameterInfo::Parameter structure for further details.

To obtain the number of parameters in a fluxEngine::ParameterInfo object the method ParameterInfo::parameterCount() exists. As long as the fluxEngine::ParameterInfo is valid the ordering of the parameters will not change. Each parameter will therefore have an index that starts at 0 and goes up to one less than the value returned by parameterCount().

Each parameter also has a unique name that identifies it. That name is case sensitive. A list of the names of all parameters (in the order they are currently in) may be obtained via parameterNames().

Note

The order of the parameters is guaranteed to be the same as long as each fluxEngine::ParameterInfo object is kept around (or copied). But retrieving a new fluxEngine::ParameterInfo object might change the order (though unlikely), and users should assume that the order will have changed when disconnecting from a device and then connecting to it again. The index is therefore only valid for the lifetime of the fluxEngine::ParameterInfo object.

Given the name or the index of a parameter it is now possible to query further information. The following generic information is stored for all parameters:

• parameterType(): the type of the parameter.

• parameterAccessMode(): whether the parameter is currently available, and whether it is read-only, read-write or write-only. (The latter is typically only the case for Command parameters.) This may change dynamically for device parameters, depending on the settings of other parameters.

  For example, many cameras support limiting the frame rate explictly, but that must be enabled by a setting. If that setting is enabled the frame rate parameter is writeable, otherwise it is either read-only or entirely not available.

• getParameterDisplayName(): the display name of the parameter, i.e. how the parameter should be displayed to the user.

  This method returns a bool to indicate whether this information exists for the given parameter – if not there is no display name and the name of the parameter should be used. See also parameterEffectiveDisplayName().

• getParameterShortDescription(): a short description of the parameter that is often displayed in the form of a tool-tip.

  This is optional and this method may return false to indicate that no such information is available for the parameter.

• getParameterLongDescription(): a longer description of the parameter.

  This is optional and this method may return false to indicate that no such information is available for the parameter.

• affectedParameters(): when changing a parameter this may also change either the limits, the availability or the value of other parameters. If any such effects exist for this parameter,

  This will return a list of the names of the parameters that might be affected when the selected parameter is changed. Note that this list might contain more parameters than are often actually affected, because sometimes only specific values will cause specific changes in other parameters, but this list will always contain all parameters that might change due to a change of the given parameter.

  For example, if a camera has a boolean parameter AcquisitionFrameRateEnabled to control whether the camera is frame rate limited, calling parameterInfo.affectedParameters("AcquisitionFrameRateEnabled") would yield a list that would contain at least the parameter AcquisitionFrameRate to indicate that that parameter will be affected by enabling / disabling the frame rate – in that case most likely by making that parameter read-only or read-write.

• defaultStringValue(), parameterDefaultIntegerValue(), parameterDefaultFloatValue(), parameterDefaultBooleanValue(): device connection parameters only: the default value of a given parameter. The correct function depending on the parameter’s type must be called here. (Though obtaining the default value as a string is always possible.)

  If this is called for a parameter information object that does not wrap connection parameters (e.g. live device parameters) an exception will be thrown, as there is no clear definition for default values in that case.

Numeric Parameters

The following settings exist only for numeric parameters (integer, floating point):

• getParameterUnit(): the (physical) unit associated with the parameter, such as the exposure time being in "ms" (for milliseconds). The precise string is up to the driver, but many drivers attempt to use the standard convention for how these units are represented.

  This is optional and this method may return false to indicate that no such information is available for the parameter.

• parameterIntegerIncrement(), parameterFloatIncrement(): the increment of the parameter.

  For integer parameters this is an active restriction: the parameter may only be changed in thsee increments. (Though the increment may be 1 to indicate that there is no restriction.)

  For floating point parameters this is a hint for the user interface. As floating point values are not exact anyway, this exists as a hint to indicate by how much a GUI element should increment the parameter when requested.

  Note that internal rounding may occur while setting a floating point parameter, so the user should always re-read a given floating point parameter after setting it to obtain the actual value it was set to.

  The increment may change depending on the values of other parameters.

• parameterIntegerMinimum(), parameterFloatMinimum(): the minimum value of the parameter. It is not possible to set the value of the parameter below this value.

  The minimum may change depending on the values of other parameters.

• parameterIntegerMaximum(), parameterFloatMaximum(): the maximum value of the parameter. It is not possible to set the value of the parameter above this value.

  The maximum may change depending on the values of other parameters.

Enumeration Parameters

For enumeration parameters it is possible to obtain a list of allowed values (enumeration entries). First call the method enumerationEntryNames() to obtain a list of the names of all of these values. An enumeration entry is uniquely identified by a pair of the following information: the index or name of the enumeration parameter it is a part of, and name or index (within the list of entry names) of the enumeration entry itself. Given those two quantities the following methods may be used to query additional information for any given enumeration entry:

• enumerationEntryValue(): get the integer value associated with the enumeration entry.

• getEnumerationEntryDisplayName(): the display name of the enumeration entry, i.e. how the entry should be displayed to the user.

  This method returns a bool to indicate whether this information exists for the given enumeration entry – if not there is no display name and the name of the entry should be used. See also enumerationEntryEffectiveDisplayName().