Devices

EventHandle

using fluxEngine::EventHandle = FLUXENGINE_EVENT_HANDLE

Event handle.

This type definition wraps the operating system event handle used in the device event notification API. On Windows system this will be a HANDLE object, on all other operating systems this will be a file descriptor. See the documentation for Device::notificationEventHandle() for further details.

DeviceType

enum class fluxEngine::DeviceType

The type of the device.

Values:

enumerator Instrument

Instrument device.

The device in question is an instrument, e.g. a camera or a spectrometer.

enumerator LightControl: Light control device.

BufferScalarType

enum class fluxEngine::BufferScalarType

Buffer scalar data type.

Buffers that are retrieved from instruments may have a specific scalar type associated with them. This is a superset of the DataType enumeration, which only covers the data types that can be used in processing.

However, some drivers may write the transported data directly into the buffer — and sometimes the transported data is of a specific packed type.

There are currently no drivers that return data of a type that is not also a standard scalar type, and the enumeration currently does not contain any types other than those also in the DataType enumeration, this will change in future versions.

See also

expandedDataType()

Values:

enumerator Unsupported

The scalar type is not supported by the public API.

The type that the driver returns is not supported by the public API of fluxEngine. This could be because fluxEngine does not support the type yet due to being older than the driver, or because support to the public API has not been added yet.

enumerator UInt8: 8bit unsigned integer

enumerator UInt16: 16bit unsigned integer

enumerator UInt32: 32bit unsigned integer

enumerator UInt64: 64bit unsigned integer

enumerator Int8: 8bit signed integer

enumerator Int16: 16bit signed integer

enumerator Int32: 32bit signed integer

enumerator Int64: 64bit signed integer

enumerator Float32: 32bit IEEE 754 single-precision floating point number

enumerator Float64: 64bit IEEE 754 double-precision floating point number

ConnectionSettings

struct ConnectionSettings

Connection settings.

This structure must be passed to connectDeviceGroup() and contains the required information to connect to a given device.

The contents of this structure may be freed after the connect function has completed.

Public Members

std::string driverName

The name of the driver.

This should be the value taken from the EnumeratedDriver::name field.

DriverType driverType

The type of the driver.

This should be the value taken from the EnumeratedDriver::type field.

std::vector<std::uint8_t> id

The id of the device to connect to.

This should be the value taken from the EnumeratedDevice::id field.

Note that while it may be tempting to hard-code this id instead of reenumerating devices each time, and even if it appears to be the case right now, there is no guarantee that the id is stable across reboots of the machine or even different versions of fluxEngine.

std::unordered_map<std::string, std::string> connectionParameters

The connection parameters to use.

The key of this map is the name of the parameter; it must be identical to the name of the parameter returned by ParameterInfo::parameterNames() or the ParameterInfo::Parameter::name field.

The value of this map is the serialized string of the value of the parameter:

For boolean this must be "True", "On", "Yes" or "1" for true and "False", "Off", "No" or "0" for false.
For integer parameters this must be the integer converted to a string, e.g. "123" or "-1".
For floating point parameters this must be the floating point value serialized as a string, scientific notation with e is allowed, using . as the decimal separator; the following are valid floating point values: "123", "42.6" and "-146.1468e-43".
For enumeration parameters this must contain the name (not the display name!) of the selected enumeration entry. The name is case-sensitive.
For file parameters (e.g. calibration files) the file name must be specified in the following manner:
- On Windows it must be encoded as UTF-8 (not the local 8bit encoding), so that it can be converted back to a wide (Unicode) file name internally before being accessed.
- On all other platforms the local 8bit encoding of the file name must be used.

If a parameter is not specified here, its default will be used. There are no defaults for file parameters, and if a file is required for the connection process, the connection attempt will fail.

std::chrono::milliseconds timeout

The connection timeout.

Typically a value of 60 seconds is a good option here; some devices may be able to connect in less time, but anything less than 10 seconds will nearly always be too short, and for some cameras even 10 seconds is not enough. The actual time required to connect can vary, so it is prudent to use at least three times the amount of time that it takes in a lab environment to connect to a specific device.

If this timeout occurs while the connection is still in progress, the driver subprocess will be terminated (as there is no other way to abort the connection attempt), which could leave the device in an undefined state. It is therefore not recommended to make this extremely short.

bool passThroughErrorOutput = {false}

Pass through error output.

By default the stderr output stream of the driver will not be passed through to the user. If this is set to true though the error output will be passed through to the error output of the application. This may be useful for debugging.

connectDeviceGroup

inline DeviceGroup fluxEngine::connectDeviceGroup(Handle &h, ConnectionSettings const &settings)

Connect to a device (group)

This method attempts to connect to a device (group). If successful a device group handle is returned to the user.

If the fluxEngine license was tied to a instrument device serial number, and the connected device is an instrument, a license check will be performed at this point. If it fails the device will be disconnected again. If it succeeds the user will be able to create processing contexts and process data, even if the data is not from the device. When the device group is disconnected the user will not be able to continue processing at this point.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

h – The fluxEngine handle
settings – The settings that select the device and the connection parameters.

Returns:

The device group after a successful connection

DeviceGroup

class DeviceGroup

Device Group.

This structure describes a device group, the result of a connection process. When connecting to a device the actual result of a connection is a device group: the device itself and potentially some subdevices. For example, an instrument device might have a subdevice that is actually a light control device.

Each device group has a primary device that can be obtained via the DeviceGroup::primaryDevice() function. The primary device will have the type correpsonding to the driver’s primary type. A subdevice may be of a completely different type.

It is possible to completely ignore subdevices.

Public Types

enum class NotificationType

Device notification type.

This enumeration describes the various types of notifications that devices can generate. Notifications must be retrieved by the user manually via DeviceGroup::nextNotification(), but the handle returned by DeviceGroup::notificationEventHandle() may be used to add notifications to the event loop.

Values:

enumerator None

No notification.

This type is returned by DeviceGroup::nextNotification() if there currently is no notification pending for the device.

enumerator IrrecoverableError

Irrecoverable error.

This notification is generated whenever the device switches into an irrecoverable error state.

enumerator RecoverableError

Recoverable error.

This notification is generated whenever the device switches into a recoverable error state.

enumerator Warning

Warning.

This notification is generated whenever the device encounters a warning. This could for example be that the temperature is outside of the operating range in the specifications. For example, if an instrument requires a stabilized sensor, and that temperature should be at 20C, if the device measures a value that is not around that value, the device could generate a warning.

Public Functions

DeviceGroup() = default

Default constructor.

This will create an invalid object that exists mainly to later have a valid object moved into.

inline DeviceGroup(DeviceGroup &&other) noexcept

Move constructor.

Parameters:: other – The device group to move

inline DeviceGroup &operator=(DeviceGroup &&other) noexcept

Move assignment operator.

Parameters:: other – The device group to move
Returns:: A reference to *this

inline ~DeviceGroup() noexcept

Destructor.

Note that this will forcibly unload the driver instead of performing an orderly disconnect. The user should call DeviceGroup::disconnect() to perform a proper disconnect from the device.

inline void disconnect(std::chrono::milliseconds timeout) noexcept

Disconnect from the device group.

This method attempts to disconnect from a device group. If that does not succeed within the specified timeout, the driver isolation process is force-unloaded.

Important: all handles of the device group and all devices in the group will no longer be valid after this point. This means the user must not access any of the following objects belonging to this device group after a call to this function:

The device group itself
Any device within the device group
Any instrument buffer retrieved from the device
The notification event handle of the device group

The user does, however, need to explicitly free any processing contexts they created for a device in this group, any reference buffer and any parameter list.

Parameters:: timeout – The timeout in milliseconds, after which the device will be forcibly disconnected by terminating the driver isolation process. A sensible value here is 5 seconds.

inline Device *primaryDevice()

Get the primary device of the device group.

If an error occurs, an exception will be thrown. The following exceptions may occur:

EmptyWrapperError

Returns:: The primary device of the device group. The handle of this device will be valid as long as the device group is not disconnected. Multiple calls to this method will result in the same device pointer.

inline std::string driverName() const

Get the name of the driver.

The driver name is the same that was supplied with the connection settings.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
EmptyWrapperError

Returns:: The name of the driver.

inline DriverType driverType() const

Get the type of the driver.

The driver type is the same that was supplied with the connection settings.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
EmptyWrapperError

Returns:: The type of the driver.

inline std::string driverDescription() const

Get the driver description.

Returns a human-readable name/description of the driver.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
EmptyWrapperError

Returns:: The driver description

inline std::string driverVersion() const

Get the driver version.

Returns a human-readable version string of the driver.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
EmptyWrapperError

Returns:: The driver version

inline EventHandle notificationEventHandle() const

Get a notification event handle.

This will return an operating system event handle that may be used to integrate device notifications into the user’s native event loop. This is optional, the user may also decide to periodically query whether a notification occurred via DeviceGroup::nextNotification().

Windows systems: this will return a HANDLE of a manually resetting event object (create via CreateEvent()) that may be used in an event loop, e.g. via WaitForMultipleObjects. Important: the event handle must not be closed by the user and must not be reset by the user. Whenever this event handle is set the user should call DeviceGroup::nextNotification() to determine the device notification. When the last notification has been retrieved the event handle is reset automatically.

Other systems: this will return a file descriptor (int) that can be polled (via select(2), poll(2) or epoll/kqueue or similar) for read events. (The file descriptor is opened with O_CLOEXEC flags on operating systems that support it.) Important: the user must not close the file descriptor and must not read from it themselves. Whenever the file descriptor is ready to be read the user should call DeviceGroup::nextNotification() to determine the device notification. When the last notification has been retrieved the file descriptor will not be ready to be read from anymore. (Internally this is implemented via an eventfd() on Linux systems and an anonymous pipe on other operating systems.)

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
EmptyWrapperError

Returns:: The event handle. Important: when the device group is disconnected the event handle is no longer valid (and automatically closed), so the user should always remove the event handle from their event loop before disconnecting a device group handle.

inline Notification nextNotification() const

Retrieve the last notification.

Retrieves the last notification in the internal notification buffer of the device group. If the type retrieved is DeviceGroup::NotificationType::None then no notification is currently present in the notification buffer, and the DeviceGroup::Notification::device and DeviceGroup::Notification::message parameters will not be set.

The event handle that can be obtained via DeviceGroup::notificationEventHandle() is automatically reset by this function once the last event in the internal event buffer has been retrieved.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
EmptyWrapperError

Returns:: The next notification in the internal notification buffer

struct Notification

Device notification.

Public Members

Device *device = {}

The device the notification has occurred for.

This will be the same pointer that can also be obtained by either DeviceGroup::primaryDevice() or Device::subDevices().

NotificationType type = {}

The type of the notification.

If this is DeviceGroup::NotificationType::None this indicates that no notification was queued for the device group.

std::string message: The notification message.

Device

class Device

A device.

This base class describes a device that has been connected. The actual class of the device object will be a subclass of this class, depending on the precise type of device.

In addition to attempting to dynamically cast the object to a subclass of the Device class, it is also possible to use the Device::type() method to obtain the device type as an enumeration value.

Pointers to device objects are only valid as long as the device group is still connected. Once the device group is disconnected or the driver unloaded, all device handles will cease to be valid. Accessing them will result in undefined behavior.

A device object should never be created by the user directly, it is always returned by other methods.

Subclassed by fluxEngine::InstrumentDevice, fluxEngine::LightControlDevice

Public Types

enum class ParameterListType

Parameter list type.

While all device parameters live in the same namespace, there are specific lists of parameters for different purposes. This enumeration describes the different purposes, and parameter information lists can be queried for each type.

When reading and/or writing a parameter it is of no consequence to which type of list the parameter belongs to. A parameter could also be a part of multiple lists.

Values:

enumerator Parameter

A standard parameter.

This list will contain the parameters that change the behavior of a device. This could be the exposure time of a camera, or the intensity of a light control device.

enumerator MetaInfo

Meta information.

This list will contain the read-only meta information that is fixed and won’t change while the device is connected. This could be calibration data for the device, but also information about the manufacturer and similar items.

enumerator Status

Status information.

This list will contain read-only parameters that describe the device’s current status, such as built-in temperature sensors that allow the user to verify the device is in its correct operating range.

Public Functions

inline virtual ~Device(): Destructor.

inline void ping()

Ping a device.

This method ensures that the device is still responsive, without actually performing an action.

This may be used by the user to verify that everything is still OK with the device without performing an action that change something on the device. The user should query the state of the device after this method, even if it is successful.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
ObjectNoLongerValidError

inline void resetError()

Reset a recoverable error.

Reset a recoverable error of a device. This method will only work if the device is in a recoverable error state and the error condition has since disappeared.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
ObjectNoLongerValidError
EmptyWrapperError
DeviceError

inline DeviceType type() const

Get the device type.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
ObjectNoLongerValidError
EmptyWrapperError

Returns:: The device type

inline std::string manufacturer() const

Get the device’s manufacturer.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
ObjectNoLongerValidError
EmptyWrapperError

Returns:: The device’s manufacturer

inline std::string model() const

Get the device model.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
ObjectNoLongerValidError
EmptyWrapperError

Returns:: The device model

inline std::string description() const

Get the device’s description.

Some devices may have an additional description that they may return.

This may be empty.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
ObjectNoLongerValidError
EmptyWrapperError

Returns:: The device’s description.

inline std::string serialNumber() const

Get the device’s serial number.

Some devices may have no serial number (in which case this will be empty), but instrument devices will typically all have one.

If a serial number is available during device enumeration it will be identical to the serial number returned here. However it is possible for a device to have a serial number that cannot be obtained during enumeration, so that it is only accessible after the device has already been connected.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
ObjectNoLongerValidError
EmptyWrapperError

Returns:: The device’s serial number

inline ParameterInfo parameterList(ParameterListType type)

Get a specific parameter list of the device.

The resulting parameter list is dynamically tied to this device; changing a parameter may change the limits of other parameters and the list will always return the most current data.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
ObjectNoLongerValidError
EmptyWrapperError
ParameterError

Parameters:: type – The type of parameter list to get
Returns:: The parameter list

inline ParameterInfo::Type parameterType(std::string const &name)

Get the type of a parameter.

In order to not have to query all parameter lists (and obtain the types of all parameters), this helper method allows the user to quickly determine the type of a parameter by the parameter’s name.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
ObjectNoLongerValidError
EmptyWrapperError
ParameterError

Parameters:: name – The name of the parameter
Returns:: The parameter’s type

inline std::string getParameterString(std::string const &name)

Get a parameter (as a string)

This will return the parameter’s value as a string.

This method will fail for parameters that are inaccessible or write-only (the latter being the case for most command parameters).

If the parameter type is not iself of string type, the value will be converted into a string. See the documentation of ConnectionSettings::connectionParameters for details on how this conversion takes place.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
ObjectNoLongerValidError
EmptyWrapperError
ParameterError

Parameters:: name – The name of the parameter
Returns:: The parameter’s value, as a string

inline int64_t getParameterInteger(std::string const &name)

Get a parameter (as an integer)

This will work for integer and enumeration parameters. In the case of a enumeration parameter this will return the value of the current enumeration entry.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
ObjectNoLongerValidError
EmptyWrapperError
ParameterError

Parameters:: name – The name of the parameter
Returns:: The parameter’s value, as an integer

inline double getParameterFloat(std::string const &name)

Get a parameter (as an floating point value)

This will only work for floating point parameters.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
ObjectNoLongerValidError
EmptyWrapperError
ParameterError

Parameters:: name – The name of the parameter
Returns:: The parameter’s value, as an floating point value

inline bool getParameterBoolean(std::string const &name)

Get a parameter (as an boolean value)

This will only work for boolean parameters.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
ObjectNoLongerValidError
EmptyWrapperError
ParameterError

Parameters:: name – The name of the parameter
Returns:: The parameter’s value, as an boolean

inline bool isParameterCommandComplete(std::string const &name)

Is a command parameter complete.

Some commands can be executed in the background (returning from the execute command call earlier than execution is done) and whether they are done can be queried with this method. If the command has already completed, is always executed synchronously (and thus has completed after the command execution function returned), or has never been executed, this method will return as if the command has completed.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
ObjectNoLongerValidError
EmptyWrapperError
ParameterError

Parameters:: name – The name of the parameter
Returns:: Whether the command has completed

inline void setParameterString(std::string const &name, std::string const &value)

Set a parameter to a string value.

If the parameter type is not iself of string type, the value will be converted from a string into its target type. See ConnectionSettings::connectionParameters for rules on how different types of parameters are converted.

Note that changing some parameters will cause instrument devices to internally stop acquisition. In that case the status of the device will switch to InstrumentDevice::Status::ForcedStop to indicate this. The user must then call InstrumentDevice::stopAcquisition() to stop acquisition on fluxEngine’s side and may then use InstrumentDevice::startAcquisition() to restart acquisition in that case. This will definitely happen when a parameter changes the size or structure of the buffer that is returned, but some drivers may require this to be the case for all parameters. To avoid having to check for this state it is therefore recommended that parameters be changed only when acquisition is stopped, although that is not a requirement.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
ObjectNoLongerValidError
EmptyWrapperError
ParameterError

Parameters:

name – The name of the parameter
value – The new value of the parameter

inline void setParameterInteger(std::string const &name, int64_t value)

Set a parameter to an integer value.

This only works for integer and enumeration parameters. In the case of an enumeration parmaeter the value of the selected enumeration entry must be provided, and there must be an enumeration entry with that value.

Note that changing some parameters will cause instrument devices to internally stop acquisition. In that case the status of the device will switch to InstrumentDevice::Status::ForcedStop to indicate this. The user must then call InstrumentDevice::stopAcquisition() to stop acquisition on fluxEngine’s side and may then use InstrumentDevice::startAcquisition() to restart acquisition in that case. This will definitely happen when a parameter changes the size or structure of the buffer that is returned, but some drivers may require this to be the case for all parameters. To avoid having to check for this state it is therefore recommended that parameters be changed only when acquisition is stopped, although that is not a requirement.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
ObjectNoLongerValidError
EmptyWrapperError
ParameterError

Parameters:

name – The name of the parameter
value – The new value of the parameter

inline void setParameterFloat(std::string const &name, double value)

Set a parameter to a floating point value.

This only works for floating point parameters.

Note that changing some parameters will cause instrument devices to internally stop acquisition. In that case the status of the device will switch to InstrumentDevice::Status::ForcedStop to indicate this. The user must then call InstrumentDevice::stopAcquisition() to stop acquisition on fluxEngine’s side and may then use InstrumentDevice::startAcquisition() to restart acquisition in that case. This will definitely happen when a parameter changes the size or structure of the buffer that is returned, but some drivers may require this to be the case for all parameters. To avoid having to check for this state it is therefore recommended that parameters be changed only when acquisition is stopped, although that is not a requirement.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
ObjectNoLongerValidError
EmptyWrapperError
ParameterError

Parameters:

name – The name of the parameter
value – The new value of the parameter

inline void setParameterBoolean(std::string const &name, bool value)

Set a parameter to a boolean value.

This only works for boolean parameters.

Note that changing some parameters will cause instrument devices to internally stop acquisition. In that case the status of the device will switch to InstrumentDevice::Status::ForcedStop to indicate this. The user must then call InstrumentDevice::stopAcquisition() to stop acquisition on fluxEngine’s side and may then use InstrumentDevice::startAcquisition() to restart acquisition in that case. This will definitely happen when a parameter changes the size or structure of the buffer that is returned, but some drivers may require this to be the case for all parameters. To avoid having to check for this state it is therefore recommended that parameters be changed only when acquisition is stopped, although that is not a requirement.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
ObjectNoLongerValidError
EmptyWrapperError
ParameterError

Parameters:

name – The name of the parameter
value – The new value of the parameter

inline void executeParameterCommand(std::string const &name)

Execute a command parameter.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
ObjectNoLongerValidError
EmptyWrapperError
ParameterError

Parameters:: name – The name of the parameter

LightControlDevice

class LightControlDevice : public fluxEngine::Device 

Light control device.

A light control device allows the user to control whether a light source is active and possibly also the intensity of that light source. This may be helpful for measuring a dark reference (by disabling the light source before the start of the measurement).

As this is a subclass of the Device class it provides all of the functionality of that class (especially when it comes to changing parameters) as well as functionality specific to light control devices.

Light control devices are controlled in two manners:

The parameters indicate the normal setting of the device. This should typically be configured by the user for the specific use case.
In addition a “force state” may be set programmatically that allows the user to force the light control device to be either off (regardless of the current parameter settings) or to perform a ramp that starts the light at the off and then gradually increase the light intensity to the setting in the parameters. This may be used for nonlinearity correction reference measurements. (See the documentation about advanced features for more details on this topic.)

Public Types

enum class Status

Light control device status.

Values:

enumerator Invalid

The device handle is invalid.

This can happen if the fluxEngine handle is closed while the device was still connected. In that case the device is forcibly disconnected and will have this status.

enumerator IrrecoverableError

Irrecoverable error occurred.

An error occurred that can’t be easily recovered from. For example, if a device is unplugged mid-use, this will be the status the device will have.

Note that it may be possible to reconnect to the device in that case, but the device group must be disconnected first if the state of a device changes in this manner.

enumerator RecoverableError

Recoverable error occurred.

If an error occurred (for example a strict temperature limit has been exceeded) that can be recovered from (by resetting the device via Device::resetError()) then this will be the status the device will have.

enumerator Off

The light is off.

Some light control devices are initialized to be off by default, for example because they could be a hazard if automatically switched on during connection. In that case the use must explicitly set a parameter to turn the light on.

This can only be the status of the light after initial connection to indicate this. If the light is on by default after connecting to it, it will be in the state LightControlDevice::Status::Parametrized instead. If the light is switched off again via parameters it will still remain in the LightControlDevice::Status::Parametrized state.

enumerator Parametrized

The light is controlled via parameters.

Various settings control whether the light is on or off; if there are multiple lights potentially whether each individual light is on or off; and if lights can be dimmed, what their intensity is.

enumerator ForcedOff

The light has been forced off.

The light has been forced off regardless of the parametrization settings.

enumerator ForcedRamp

The light has been forced into a ramp.

The light has been forced to perform a ramp from being switched off completely to being on up to the intensity specified by the settings. This can be used to record references for non-linearity corrections.

This state will always be temporary, after the ramp is complete the device will automatically switch back into the LightControlDevice::Status::Parametrized state.

enum class ForceState

The force state of the light control device.

This describes whether / how the parameters of the device are to be overwritten temporarily.

Values:

enumerator None

The device should be parametrized.

The light will be on or off depending on its parameters.

enumerator Off

The light should be forced off.

The light will be forced off, regardless of its parameters, and can only be turned on again by changing the force state.

enumerator Ramp

The light should perform a ramp-up.

The should perform a ramp-up from being off to going to the level of intensity described by its parameters. This force state will automatically reset to LightControlDevice::ForceState::None once the ramp has completed.

Public Functions

inline Status status() const

Get the status of a light control device.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
EmptyWrapperError
DeviceError

Returns:: The status of the light control device

inline void setForceState(ForceState state, std::chrono::milliseconds rampDuration)

Set the force state of the light control device.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

state – The new force state
rampDuration – The ramp duration in milliseconds, if the device supports it. If the device can only switch the light on and off (but not vary its intensity) this will be ignored and the light will just be switched on; the duration of that process will be fixed within the driver (as that will depend on the hardware and can’t be influenced). If the light’s intensity can be modified the driver will gradually adjust the intensity from zero to the parametrized value with a speed that is adjusted to this time.

inline bool waitForRamp()

Wait for the device to complete its ramp.

This may be called after setting a ramp force state to wait until the ramp is complete.

If the ramp has already completed (or no ramp has been set) this method will return false immediately. If the ramp is active when this method is called it will return only once the ramp has completed.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Returns:: false if the ramp was not active when this was first called (potentially because the ramp was already over), true if the ramp was active when this method was called.

InstrumentDevice

class InstrumentDevice : public fluxEngine::Device 

Instrument Device.

An instrument device is a device that allows the user to perform measurements and use the measured data. This includes spectrometers, cameras, but also other sensors.

Each measurement result is stored in a buffer (see the BufferInfo structure for details) that can be retrieved from the instrument. The measurements are added to a queue, and the user may retrieve each measurement from that queue, use that data, and then return the buffer to the system so it may be used for future measurements.

In order to obtain data from an instrument device, the following steps need to be taken:

The buffers need to be set up initially. This may be done via the InstrumentDevice::setupInternalBuffers() method.
The user starts acquisition using the InstrumentDevice::startAcquisition() method.
In a loop the user first retrieves a buffer via the InstrumentDevice::retrieveBuffer() method, then uses that buffer, and finally returns the buffer via the InstrumentDevice::returnBuffer() method
The user may stop data acquisition via the InstrumentDevice::stopAcquisition() method

Public Types

enum class Status

Instrument device status.

Values:

enumerator Invalid

The device handle is invalid.

This can happen if the fluxEngine handle is closed while the device was still connected. In that case the device is forcibly disconnected and will have this status.

enumerator IrrecoverableError

Irrecoverable error occurred.

An error occurred that can’t be easily recovered from. For example, if a device is unplugged mid-use, this will be the status the device will have.

Note that it may be possible to reconnect to the device in that case, but the device group must be disconnected first if the state of a device changes in this manner.

enumerator RecoverableError

Recoverable error occurred.

If an error occurred (for example a strict temperature limit has been exceeded) that can be recovered from (by resetting the device via Device::resetError()) then this will be the status the device will have.

enumerator Idle

The instrument is idle.

The instrument is idle and not returning data.

enumerator Busy

The instrument is busy with an operation.

This state will never last very long, but in some cases a parameter change may trigger an operation that happens on the device in the background, and during that operation this will be the state of the device. The device will automatically return to its previous state after the operation has completed. (This is rare.)

enumerator Streaming

The instrument is streaming data.

The instrument is streaming data to the user.

enumerator ForcedStop

The instrument was forced to stop.

A parameter change caused the instrument to stop. In that case the user must also stop acquisition on their end and start it again. The structure of the individual buffers that the instrument returns may have changed.

Any processing context created for use with the instrument may not be applicable anymore. (It may still be possible to supply the device’s data to the processing context if the size and scalar type match, but the processing context will likely not perform the correct operations.)

Public Functions

inline Status status() const

Get the status of an instrument device.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
EmptyWrapperError
DeviceError
InstrumentDeviceError

Returns:: The status of the instrument device

inline std::size_t maxBufferSize() const

Get the maximum buffer size (in bytes) that the instrument may return.

This will return the maximum size (in bytes) that the device may require to return data to the user. This size is guaranteed to be large enough that regardless of how the device is parametrized it will always be able to hold the data of a single buffer.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
ObjectNoLongerValidError
EmptyWrapperError
DeviceError

Returns:: The maximum buffer size the instrument may return

inline std::size_t recommendedBufferCount() const

Get the number of recommended buffers.

This will return a number that the driver recommends the user use for operating the device. This does not apply to recording mode, where it is convenient to use a larger number of buffers.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
ObjectNoLongerValidError
EmptyWrapperError
DeviceError

Returns:: The number of recommended buffers

inline std::vector<int64_t> rawBufferDimensions() const

Get the current dimensions of the buffer returned by an instrument.

The tensor order will correspond to the number of elements in the resulting vector. An empty vector is a valid result: there can be instruments that just return a single scalar value.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Returns:: The current dimensions of the buffer

inline void getRawBufferDimensions(std::array<int64_t, 5> &dimensions, int &order) const

Get the current dimensions of the buffer returned by an instrument (non-allocating override)

This exists as a means to obtain the same information as InstrumentDevice::rawBufferDimensions() without having to allocate a std::vector.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

dimensions – Where to store the dimensions
order – Where to store the tensor order

inline DimensionLabelInfo rawBufferDimensionLabels(int dimension) const

Get the labels associated with a dimension of the raw buffer of an instrument device.

This information may be useful if the raw image of the camera is to be displayed to the user. For example, if the instrument is a HSI PushBroom type camera, one of the two dimensions of the raw frame will correspond to the wavelengths (before corrections are applied) of the device. While corrections may be applied during the pre-processing steps on top of this, it may still be useful to give the user an indication of what they are looking at at the moment.

See the DimensionLabelInfo structure for further details.

If an error occurs, an exception will be thrown. The following exceptions may occur:

See also

DimensionLabelInfo

Parameters:: dimension – Which dimension to obtain the label information for. It must be between 0 and one less than the tensor order of the raw data, as may be obtained via InstrumentDevice::rawBufferDimensions().
Returns:: The labels associated with the selected dimensions

inline std::pair<float, float> rawBufferValueRange() const

Get the value range associated with the data in the raw buffer of an instrument device.

This will return the lowest possible value (which will likely be 0) and the highest possible value that a given instrument device may return in a raw buffer.

This information may be used to provide automatic scaling of raw data of the instrument that is being shown to the user, for example.

Note that this information must be provided by the driver and it may not always be possible to obtain it. In that case the limits will be set to exactly the same value to indicate this.

Returns:: A pair that contains the value range of the device. The first entry is the lower limit, the second entry is the upper limit of the value range.

inline BufferScalarType rawBufferScalarType() const

Get the current scalar type of the buffer returned by an instrument.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Returns:: The scalar type of the buffer

inline PersistentBufferInfo allocatePersistentBuffer()

Allocate a persistent buffer info.

Allocate a memory region that is large enough to fit a buffer that is returned by the instrument upon acquisition. This may be used by the user to pre-allocate memory to later copy data into.

Note that the allocated PersistentBufferInfo will have the size of the instrument with respect to the current set of parameters — if a parameter is changed that causes the size to change, the buffers returned by the instrument will no longer match the persistent buffer.

The contents of the persistent buffer will be initialized with zero and the buffer number will be set to -1.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Returns:: The newly allocated persistent buffer

inline void setupInternalBuffers(std::size_t count)

Setup internal buffers for the device.

This will allocate the shared memory region that is used by the driver and fluxEnigne to transfer data from the instrument. The number of buffers can be specified in the count parameter, but must be at least 5. The size of the shared memory region will be buffer_size_page * count + overhead, where buffer_size_page is the size returned by InstrumentDevice::maxBufferSize() rounded up to the minimal size of a virtual memory mapping (on Windows this will always be 65536 bytes, on other operating systems this will be the page size, which is typically between 4096 bytes and 65536 bytes), and overhead is as comparatively small overhead used for bookkeeping. As the amount of shared memory in the system is limited, the user should never specify an excessively large number of buffers, but numbers ranging from 5 to 100 are typically considered acceptable in their memory consumption, assuming that a buffer will only have a size of at most a couple of MB.

Important: this method may only be called once and the device group has to be disconnected to choose a different number of buffers. It is recommended to use the largest number that may be requried here, because the number of buffers that is actually used can be varied when starting acquisition.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:: count – The number of buffers to allocate

inline void startAcquisition(AcquisitionParameters const &parameters)

Start acquisition.

Starts acquisition on the device. Once data is received from the driver the internal buffer queue will start to fill and data may be retrieved via the InstrumentDevice::retrieveBuffer() method.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:: parameters – The parameters for starting acquisition, such as the number of buffers to use for this specific acquisition. See the documentation of the structure on the various parameters.

inline void stopAcquisition()

Stop acquisition.

It is safe to call this method if acquisition is not active, in which case this method will not do anything.

If an error occurs, an exception will be thrown. The following exceptions may occur:

inline BufferInfo retrieveBuffer(std::chrono::milliseconds timeout)

Retrieve a buffer from the device.

Acquisition must be active for this to succeed.

The buffer retrieved here must be returned via InstrumentDevice::returnBuffer() after the user has no more use for it, otherwise data acquisition from the device will stall.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:: timeout – How long to wait before returning without a buffer. The actual wait might be larger than this, depending on the scheduler of the operating system.
Returns:: The buffer that was retrieved. The user must check if the BufferInfo::ok member is true before using the buffer. If that member is false this indicates that no buffer was returned within the specified timeout.

template<typename Callable> inline BufferInfo retrieveBuffer(std::chrono::milliseconds timeout, Callable &&abortCheckFunction)

Retrieve a buffer from the device.

Acquisition must be active for this to succeed.

The buffer retrieved here must be returned via InstrumentDevice::returnBuffer() after the user has no more use for it, otherwise data acquisition from the device will stall.

This method will call an abort check function during the wait time to see if the user has externally aborted acquisition in the mean time. That function will be called quite often and should be light-weight, such as reading an atomic flag.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:

timeout – How long to wait before returning without a buffer. The actual wait might be larger than this, depending on the scheduler of the operating system.
abortCheckFunction – The function that checks whether an external abort has been initiated. If the function returns true an external abort has been requested.

Returns:

The buffer that was retrieved. The user must check if the BufferInfo::ok member is true before using the buffer. If that member is false this indicates that no buffer was returned within the specified timeout, or the abort check function returned true.

inline void returnBuffer(void *bufferId)

Return a buffer to the instrument.

This returns a buffer to the instrument device. The user must not attempt to access the buffer after they have returned it via this method.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:: bufferId – The id of the buffer to return. This must correspond to the BufferInfo::id field.

inline void setCalibrationInfo(CalibrationInfo const &calibrationInfo)

Set the current calibration info for an instrument device.

The calibration info is not used immediately, but stored, so that any processing context that is created for this device in the future will use that calibration info.

This will not affect any processing context that has already been created.

If an error occurs, an exception will be thrown. The following exceptions may occur:

Parameters:: calibrationInfo – The calibration information to set for the device

struct AcquisitionParameters

Acquisition parameters.

These parameters are to be supplied when starting acquisition. They may influence the acquisition process in some manner.

Public Members

std::string referenceName

The name of the reference to measure.

Some drivers may react differently when they know a reference is to be measured during the next acquisition. For example, the virtual pushbroom camera driver will return the data of the reference cubes instead of the main cube when a reference is to be measured. But even drivers for real hardware may react differently: some cameras may have an integrated shutter that they can close, and during dark reference measurement this is what will happen in that case.

If this is NULL this indicates that a normal (non-reference) measurement is to be performed.

Otherwise this must be either "WhiteReference", "IlluminationReference", or "DarkReference".

In most cases it does not make any difference whether a reference measurement is to be performed or not, and there is no effect of this setting. The user is also not required to perform the reference measurements in this manner — if the special functionality associated (e.g. shutter for dark reference measurements) is not required (because the user just shuts off the light, for example), then the user may perform the reference measurement by just normal acquisition.

std::size_t bufferCount = {}

The number of buffers to use.

If this is 0, all of the buffers that have been created in the shared memory region will be used during acquisition. If this is non-zero only this amount of buffers will be used, instead. If this is larger than the amount of buffers allocated in shared memory, starting acquisition will fail.

This may be useful to allocate more buffers for recording purposes while setting up the shared memory, but only use a lesser amount during processing.

The amount of buffers trades off latency for dropped buffers: the more buffers are used in shared memory, the less likely it is that a buffer may be dropped due to timing issues, as more buffers are available. For recording data it is generally useful to use more buffers. (Though too many buffers will result in too much RAM usage.) Unfortunately more buffers increases the latency of data processing, so if a low latency is required it is better to use less buffers.

The minimum number of buffers that may be used is 5; if the number is lower 5 buffers will be used regardless.

BufferInfo

struct BufferInfo

Buffer Info.

This structure describes a buffer the user has retrieved from an instrument device during acquisition.

Any buffer that has been successfully retrieved must be returned to the instrument via InstrumentDevice::returnBuffer().

Note that InstrumentDevice::retrieveBuffer always returns this structure, even if no buffer could be retrieved, and the user should first check the BufferInfo::ok field to verify that a buffer was actually retrieved. (If the BufferInfo::ok field is false then no buffer was retrieved and all other fields are invalid.)

Public Functions

inline void copyRawData(void *memory, DataType dataType, std::array<int64_t, 5> strides)

Copy and expand the raw data of the buffer into a user-supplied memory area.

Calling this method is useful if the user wants to use the raw data of the buffer, but does not want to handle all possible scalar types (especially packed types) that fluxEngine supports. In that case the user may set the dataType parameter to a floating point type (32bit or 64bit) and the data will automatically be converted into that format.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
EmptyWrapperError
InstrumentDeviceError

Parameters:

memory – Where to store the data of the buffer. The user must have preallocated it to have the correct size for the given data type (given the dimensions of this buffer)
dataType – The target data type of the memory area provided by the user. An automatic conversion will take place if the type is not the same as the type of the data in the buffer
strides – The stride structure of the user-supplied memory area

inline void copyRawData(void *memory, DataType dataType)

Copy and expand the raw data of the buffer into a user-supplied memory area.

Calling this method is useful if the user wants to use the raw data of the buffer, but does not want to handle all possible scalar types (especially packed types) that fluxEngine supports. In that case the user may set the dataType parameter to a floating point type (32bit or 64bit) and the data will automatically be converted into that format.

This overload of the method assumes that the strides of the target memory area are trivial (i.e. the tensor will be stored contiguously in that area).

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
EmptyWrapperError
InstrumentDeviceError

Parameters:

memory – Where to store the data of the buffer. The user must have preallocated it to have the correct size for the given data type (given the dimensions of this buffer)
dataType – The target data type of the memory area provided by the user. An automatic conversion will take place if the type is not the same as the type of the data in the buffer

inline PersistentBufferInfo copy() const

Copy the contents of the buffer into a persistent buffer.

As instrument buffers must be returned to the device, in order to keep the data of a buffer around for longer, its data may be copied into a persistent buffer.

This method allocates a new persistent buffer that has the correct size and type for the data in the buffer and returns the result.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
EmptyWrapperError
InstrumentDeviceError

Returns:: The new persistent buffer

inline void copyInto(PersistentBufferInfo &target) const

Copy the contents of the buffer into a persistent buffer.

As instrument buffers must be returned to the device, in order to keep the data of a buffer around for longer, its data may be copied into a persistent buffer.

This function copies the data of a buffer into a pre-allocated persistent buffer. The user must ensure that the dimensions and type of the persistent buffer match the source buffer.

All data in the persistent buffer will be overwritten.

Important: it is up to the user to ensure that this function is not called while the target persistent buffer is accessed from another thread.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
EmptyWrapperError
InstrumentDeviceError

Parameters:: target – The persistent buffer to copy the data into

Public Members

void *id = {}

The id of the buffer.

This must be passed to InstrumentDevice::returnBuffer() to return the buffer.

int64_t number = {}

The number of the buffer.

For cameras this corresponds to the frame number of the recorded frame. This may be used to detect frame drops.

BufferScalarType scalarType = {}: The scalar type of the data in the buffer.

int order = {}

The tensor order of the buffer.

For spectrometers this will be 1.

For cameras this will be 2.

std::array<int64_t, 5> dimensions = {}

The dimensions of the data in the buffer.

Only the first BufferInfo::order entries will have valid values.

std::array<int64_t, 5> strides = {}

The strides of the data in the buffer.

Only the first BufferInfo::order entries will have valid values.

void const *dataPointer = {}: The pointer to the first element in the buffer.

size_t dataByteCount = {}

The number of bytes in the buffer.

This is useful if the user wants to make a copy of the data in the buffer for later use, without having to care about the specific data type.

bool ok = false

Whether the buffer was actually retrieved.

All other fields will not contain valid data if this is false.

PersistentBufferInfo

class PersistentBufferInfo

Persistent Buffer Info.

This structure describes a buffer that was copied into is own allocated memory region from a device buffer.

The user will never create such a buffer directly, but will obtain it via one of the following methods:

InstrumentDevice::allocatePersistentBuffer()
BufferInfo::copy()
PersistentBufferInfo::copy()
BufferContainer::copyBuffer()

The persistent buffer has move-only semantics, even though it may be copied via the PersistentBufferInfo::copy() and PersistentBufferInfo::copyInto() methods. This is due to the fact that we wrap a native C handle and use move semantics to follow the movement of the ownership of the handle, and not the movement of the contained data.

Public Functions

PersistentBufferInfo() = default

Default constructor.

Creates an invalid persistent buffer handle. This exists only so that the user may create a variable that will hold a persistent buffer at a later point in time.

inline PersistentBufferInfo(PersistentBufferInfo &&other)

Move constructor.

Parameters:: other – The persistent buffer to move

inline PersistentBufferInfo &operator=(PersistentBufferInfo &&other)

Move assignment operator.

Parameters:: other – The persistent buffer to move
Returns:: A reference to *this

inline ~PersistentBufferInfo(): Destructor.

inline int64_t number() const

Get the number of the buffer.

For cameras this corresponds to the frame number of the recorded frame. This may be used to detect frame drops.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
EmptyWrapperError

Returns:: The number of the buffer

inline int order() const

Get the tensor order of the buffer.

For spectrometers this will be 1.

For cameras this will be 2.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
EmptyWrapperError

Returns:: The tensor order of the buffer

inline std::array<int64_t, 5> dimensions() const

Get the dimensions of the data in the buffer.

Only the first PersistentBufferInfo::order() entries will have valid values.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
EmptyWrapperError

Returns:: The dimensions of the data in the buffer

inline std::array<int64_t, 5> strides() const

Get the strides of the data in the buffer.

Only the first PersistentBufferInfo::order() entries will have valid values.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
EmptyWrapperError

Returns:: The strides of the data in the buffer

inline BufferScalarType scalarType() const

Get the scalar type of the data in the buffer.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
EmptyWrapperError

Returns:: The scalar type of the data in the buffer

inline void const *rawData() const

Get the pointer to the first element in the buffer.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
EmptyWrapperError

Returns:: The pointer to the first element in the buffer

inline size_t rawDataByteCount() const

Get the number of bytes in the buffer.

This is useful if the user wants to make a copy of the data in the buffer for later use, without having to care about the specific data type.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
EmptyWrapperError

Returns:: The number of bytes in the buffer

inline TensorData tensorView() const &

Get a tensor view of the persistent buffer.

This will only succeed if the data type of the persistent buffer is a standard data type.

Returns:: The tensor view of the current buffer

inline void copyRawData(void *memory, DataType dataType, std::array<int64_t, 5> strides)

Copy and expand the raw data of the buffer into a user-supplied memory area.

Calling this method is useful if the user wants to use the raw data of the buffer, but does not want to handle all possible scalar types (especially packed types) that fluxEngine supports. In that case the user may set the dataType parameter to a floating point type (32bit or 64bit) and the data will automatically be converted into that format.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
EmptyWrapperError

Parameters:

memory – Where to store the data of the buffer. The user must have preallocated it to have the correct size for the given data type (given the dimensions of this buffer)
dataType – The target data type of the memory area provided by the user. An automatic conversion will take place if the type is not the same as the type of the data in the buffer
strides – The stride structure of the user-supplied memory area

inline void copyRawData(void *memory, DataType dataType)

Copy and expand the raw data of the buffer into a user-supplied memory area.

Calling this method is useful if the user wants to use the raw data of the buffer, but does not want to handle all possible scalar types (especially packed types) that fluxEngine supports. In that case the user may set the dataType parameter to a floating point type (32bit or 64bit) and the data will automatically be converted into that format.

This overload of the method assumes that the strides of the target memory area are trivial (i.e. the tensor will be stored contiguously in that area).

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
EmptyWrapperError

Parameters:

memory – Where to store the data of the buffer. The user must have preallocated it to have the correct size for the given data type (given the dimensions of this buffer)
dataType – The target data type of the memory area provided by the user. An automatic conversion will take place if the type is not the same as the type of the data in the buffer

inline PersistentBufferInfo copy() const

Copy the contents of the persistent buffer into a new persistent buffer.

This effectively clones the persistent buffer.

This method allocates a new persistent buffer that has the correct size and type for the data in the buffer and returns the result.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
EmptyWrapperError

Returns:: The new persistent buffer

inline void copyInto(PersistentBufferInfo &target) const

Copy the contents of the persistent buffer into a different persistent buffer.

This function copies the data of a persistent buffer into another persistent buffer. The user must ensure that the dimensions and type of the target buffer match the source buffer.

All data in the target will be overwritten.

Important: it is up to the user to ensure that this function is not called while the target persistent buffer is accessed from another thread.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
EmptyWrapperError

Parameters:: target – The persistent buffer to copy the data into

DimensionLabelInfo

struct DimensionLabelInfo

Dimension Label Information.

Contains the information about a dimension’s labels that may be queried from fluxEngine. This is the return value of InstrumentDevice::rawBufferDimensionLabels() that indicates how dimensions of a raw buffer returned from an instrument may roughly be interpreted.

Public Members

bool haveType = {}

Whether the type member is present.

If this is false the user should consider the type member to not be present. This is an indication that the type could not be determined or the current version of fluxEngine does not understand the type provided by the driver.

bool haveUnit = {}

Whether the unit member is present.

If this is false the user should consider the unit member to not be present. This is an indication that the unit could not be determined or the current version of fluxEngine does not understand the unit provided by the driver.

std::string type

The label type.

This member is only valid if haveType is true.

This may be one of the following strings:

"" (empty string): indicates that there is no special type for this specific dimension
"YPixel": the buffer dimension describes the y dimension of an image. For example, a simple grayscale imager camera will return a raw buffer with 2 dimensions, the first having the type "YPixel" and the second having the type "XPixel".
"XPixel": the buffer dimension describes the x dimension of an image or a line. For example, a simple grayscale imager camera will return a raw buffer with 2 dimensions, the first having the type "YPixel" and the second having the type "XPixel". On the other hand, a grayscale line camera will return one dimension with just the type "XPixel". Finally, a HSI PushBroom camera will return two dimensions, one having the type "XPixel", and the other having the type "Wavelength". (Which one is which in the case of a PushBroom camera will depend on the specific camera model; the preprocessing steps done by processing contexts in fluxEngine will ensure that the data will be normalized.)
"Wavelength": the dimension describes the wavelengths of a spectrometer or a HSI camera

std::string unit

The label values’ unit.

This member is only valid if haveUnit is true.

This may be one of the following strings.

"" (empty string): indicates that the dimension labels have no unit. In this case it is likely that no specific label values are provided.
"px": indicates that the dimension labels are pixels. In this case it is likely that no specific label values are provided, as pixels are typically always just integers that correspond to the index
"nm": the labels of this dimension are measured in nanometers.

std::vector<double> values

The values of the labels.

This will either contain numeric values that label the dimension in question, or it may be empty, indicating that the user should consider an ascending list of indices, e.g. [0, 1, 2, ….] the labels of that specific dimension.

BufferContainer

class BufferContainer

Buffer Container.

This structure describes a buffer that may be used to record multiple measurements. It abstracts away the required data type handling and may be supplied as reference data when creating processing contexts for device processing.

To create a BufferContainer the user should use the createBufferContainer() function that creates a buffer container for the current buffer size of a given instrument device.

Public Functions

BufferContainer() = default: Default constructor.

inline BufferContainer(BufferContainer &&other) noexcept

Move constructor.

Parameters:: other – The object to move

inline BufferContainer &operator=(BufferContainer &&other) noexcept

Move assignment operator.

Parameters:: other – The object to move
Returns:: A reference to *this

inline ~BufferContainer() noexcept: Destructor.

inline std::uint64_t count() const

Get the number of buffers stored in the buffer container.

Immediately after creation or after a call to BufferContainer::clear() this will be 0.

If the buffer container was created as a ring buffer this will return the total number of entries added, even if some older entries have since been overwritten.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
EmptyWrapperError

Returns:: The number of buffers in the container

inline void clear()

Clear the buffer container.

This remove all data in the buffer container, allowing it to be reused.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
EmptyWrapperError

inline void add(BufferInfo const &buffer)

Add a device buffer to the buffer container.

Add a device buffer to the buffer container. This will increase the count of the buffer container by 1.

The data in the buffer is copied into the container.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
EmptyWrapperError
InstrumentDeviceError

Parameters:: buffer – The buffer to add

inline void add(PersistentBufferInfo const &buffer)

Add a persistent buffer to the buffer container.

Add a persistent buffer to the buffer container. This will increase the count of the buffer container by 1.

The data in the buffer is copied into the container.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
EmptyWrapperError
InstrumentDeviceError

Parameters:: buffer – The persistent buffer to add

inline void addRaw(void const *data, BufferScalarType type, int order, std::array<int64_t, 5> dimensions, std::array<int64_t, 5> strides)

Add raw data to the buffer container.

This exists mainly for the case where the user wants to copy the data of a device buffer into internal memory and then later add it to a buffer container object.

The data provided is copied into the container.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
EmptyWrapperError
InstrumentDeviceError

Parameters:

data – A pointer to the data to add
type – The scalar type of the data to add
order – The order of the data to add. This must match what the buffer container expects
dimensions – The dimensions of the data to add. This must match what the buffer container expects
strides – The strides of the data to add.

inline void addRaw(void const *data, BufferScalarType type, std::vector<int64_t> dimensions, std::vector<int64_t> strides = {})

Add raw data to the buffer container.

This exists mainly for the case where the user wants to copy the data of a device buffer into internal memory and then later add it to a buffer container object.

The data provided is copied into the container.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
EmptyWrapperError
InstrumentDeviceError

Parameters:

data – A pointer to the data to add
type – The scalar type of the data to add
dimensions – The dimensions of the data to add. This must match what the buffer container expects
strides – The strides of the data to add. If this is empty the stride structure will be calculated under the assumption that the data is contiguous in memory

inline void addLastResult(ProcessingContext &context)

Add the last result of a recording context to a BufferContainer.

Given a buffer container that was allocated via the overload of createBufferContainer() that accepts a ProcessingContext, add the last result of data standardization to the buffer container. The processing context provided here must either be the same as the one used to create the buffer container, or at the very least have exactly the same output structure.

Parameters:: context – The processing context whose data to add

inline int order() const

Get the tensor order of the buffer container.

The tensor order will be one more than the tensor order of the device buffers.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
EmptyWrapperError

Returns:: The tensor order of the buffer container

inline BufferScalarType scalarType() const

Get the scalar type of the buffer container.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
EmptyWrapperError

Returns:: The scalar type of the buffer container

inline std::array<int64_t, 5> dimensions() const

Get the dimensions of the buffer container.

Only the first BufferContainer::order() entries will have a valid value.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
EmptyWrapperError

Returns:: The dimensions of the buffer container

inline std::size_t bytesPerBuffer() const

Get the number of bytes for an individual buffer.

Returns the number of bytes an individual buffer would take up if its data were to be copied out without any holes (trivial stride structure). This information is available even if there are currently no buffers in the buffer container.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
EmptyWrapperError

Returns:: The number of bytes for an individual buffer

inline std::size_t bytesTotal() const

Get the number of bytes required to copy the all data in the buffer container.

This will change if the BufferContainer::count() changes.

Returns the number of bytes required to copy the data of all buffers that are stored in the buffer container into memory, assuming the target memory does not have any holes (trivial stride structure). If no buffers are in the container this will return zero.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
EmptyWrapperError

Returns:: The number of total bytes required for the data in the container

inline void copyData(void *data, size_t dataSize)

Copy the data of the buffer container into a new memory region.

This will copy all data in the buffer container into a new memory region. If the buffer container is empty this function will have no effect.

The memory region the data is copied into will hold the data of the buffer container with a trivial stride structure, i.e. no holes in memory at all.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
EmptyWrapperError
InstrumentDeviceError

Parameters:

data – The memory region to copy the data into
dataSize – The size of the memory region. This must be provided so that this function can check the region is large enough to hold the data

inline void copySingleData(uint64_t bufferId, void *data, size_t dataSize)

Copy the data of an individual buffer stored in the buffer container into a new memory region.

This will copy all data of an individual buffer stored in the buffer container into a new memory region. The specified buffer id must be smaller than the number of buffers stored in the container.

The memory region the data is copied into will hold the data of the buffer with a trivial stride structure, i.e. no holes in memory at all.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
std::out_of_range
Error
EmptyWrapperError
InstrumentDeviceError

Parameters:

bufferId – The id of the buffer to copy
data – The memory region to copy the data into
dataSize – The size of the memory region. This must be provided so that this function can check the region is large enough to hold the data

inline PersistentBufferInfo copyBuffer(uint64_t bufferId, int64_t overrideBufferNumber = -1)

Copy a buffer stored in a buffer container into a new persistent buffer.

Allocates a new persistent buffer and copies the data of a single buffer stored in the buffer container into it. The specified buffer id must be smaller than the number of buffers stored in the container.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
std::out_of_range
Error
EmptyWrapperError
InstrumentDeviceError

Parameters:

bufferId – The id of the buffer to copy
overrideBufferNumber – If this is non-negative it will be stored as the buffer number of the persistent buffer; otherwise the value of bufferId will be used as the buffer number

Returns:

The new persistent buffer

inline PersistentBufferInfo allocateBuffer()

Allocate a new persistent buffer object that may hold data from this buffer container.

The newly allocated persistent buffer will be empty.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
EmptyWrapperError

Returns:: The new persistent buffer

inline void copyIntoBuffer(uint64_t bufferId, int64_t overrideBufferNumber, PersistentBufferInfo &target)

Copy a buffer stored in a buffer container into an existing persistent buffer.

Copies the data of a single buffer stored in the buffer container into an existing persistent buffer. The specified buffer id must be smaller than the number of buffer stored in the container. The user must ensure that the dimensions and type of the target buffer match that of an individual buffer of the buffer container.

Important: it is up to the user to ensure that this function is not called while the target persistent buffer is accessed from another thread.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
std::out_of_range
Error
EmptyWrapperError
InstrumentDeviceError

Parameters:

bufferId – The id of the buffer to copy
overrideBufferNumber – If this is non-negative it will be stored as the buffer number of the persistent buffer; otherwise the value of bufferId will be used as the buffer number
target – The persistent buffer to copy the data into

inline void averageIntoMemory(Handle &handle, DataType targetDataType, void *data, std::array<std::int64_t, 5> const &strides)

Average the contents of a buffer container into a memory region provided by the user.

Calculates the average of all buffers in a buffer container and stores the average buffer in a memory region provided by the user.

This may be useful when measung references (e.g. a white reference) and an average over all measured buffers is to be displayed to the user.

The resulting data will effectively be a single buffer that contains the average over all buffers stored in the buffer container.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
EmptyWrapperError
InstrumentDeviceError

Parameters:

handle – The handle. The default processing queue set of the handle will be used to perform the averaging.
targetDataType – The data type of the averaged data. Note that if an integer type is specified here (even though the original data is an integer) this may result in a loss of precision as the fractional part of values will be truncated.
data – The memory region to store the result in
strides – The stride structure of the user-supplied memory area

inline void averageIntoMemory(Handle &handle, DataType targetDataType, void *data)

Average the contents of a buffer container into a memory region provided by the user.

Calculates the average of all buffers in a buffer container and stores the average buffer in a memory region provided by the user.

This may be useful when measung references (e.g. a white reference) and an average over all measured buffers is to be displayed to the user.

The resulting data will effectively be a single buffer that contains the average over all buffers stored in the buffer container.

This overload of the method assumes that the strides of the target memory area are trivial (i.e. the tensor will be stored contiguously in that area).

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
EmptyWrapperError
InstrumentDeviceError

Parameters:

handle – The handle. The default processing queue set of the handle will be used to perform the averaging.
targetDataType – The data type of the averaged data. Note that if an integer type is specified here (even though the original data is an integer) this may result in a loss of precision as the fractional part of values will be truncated.
data – The memory region to store the result in

inline void averageIntoMemory(ProcessingQueueSet &pqs, DataType targetDataType, void *data, std::array<std::int64_t, 5> const &strides)

Average the contents of a buffer container into a memory region provided by the user.

Calculates the average of all buffers in a buffer container and stores the average buffer in a memory region provided by the user.

This may be useful when measung references (e.g. a white reference) and an average over all measured buffers is to be displayed to the user.

The resulting data will effectively be a single buffer that contains the average over all buffers stored in the buffer container.

This overload of the method allows the user to specify a processing queue set that is to be used to perform the averaging.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
EmptyWrapperError
InstrumentDeviceError

Parameters:

pqs – The processing queue set to use to perform the averaging operation
targetDataType – The data type of the averaged data. Note that if an integer type is specified here (even though the original data is an integer) this may result in a loss of precision as the fractional part of values will be truncated.
data – The memory region to store the result in
strides – The stride structure of the user-supplied memory area

inline void averageIntoMemory(ProcessingQueueSet &pqs, DataType targetDataType, void *data)

Average the contents of a buffer container into a memory region provided by the user.

Calculates the average of all buffers in a buffer container and stores the average buffer in a memory region provided by the user.

This may be useful when measung references (e.g. a white reference) and an average over all measured buffers is to be displayed to the user.

The resulting data will effectively be a single buffer that contains the average over all buffers stored in the buffer container.

This overload of the method allows the user to specify a processing queue set that is to be used to perform the averaging.

This overload of the method assumes that the strides of the target memory area are trivial (i.e. the tensor will be stored contiguously in that area).

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
EmptyWrapperError
InstrumentDeviceError

Parameters:

pqs – The processing queue set to use to perform the averaging operation
targetDataType – The data type of the averaged data. Note that if an integer type is specified here (even though the original data is an integer) this may result in a loss of precision as the fractional part of values will be truncated.
data – The memory region to store the result in

inline PersistentBufferInfo averageIntoNewBuffer(Handle &handle, DataType targetDataType)

Average the contents of a buffer container into a newly allocated persistent buffer.

Calculates the average of all buffers in a buffer container and stores the average buffer in a newly allocated persistent buffer.

This may be useful when measung references (e.g. a white reference) and an average over all measured buffers is to be displayed to the user.

The resulting data will effectively be a single buffer that contains the average over all buffers stored in the buffer container.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
EmptyWrapperError
InstrumentDeviceError

Parameters:

handle – The handle. The default processing queue set of the handle will be used to perform the averaging.
targetDataType – The data type of the averaged data. Note that if an integer type is specified here (even though the original data is an integer) this may result in a loss of precision as the fractional part of values will be truncated.

Returns:

The resulting persistent buffer that will contain the averaged data of the buffer container

inline PersistentBufferInfo averageIntoNewBuffer(ProcessingQueueSet &pqs, DataType targetDataType)

Average the contents of a buffer container into a newly allocated persistent buffer.

Calculates the average of all buffers in a buffer container and stores the average buffer in a newly allocated persistent buffer.

This may be useful when measung references (e.g. a white reference) and an average over all measured buffers is to be displayed to the user.

The resulting data will effectively be a single buffer that contains the average over all buffers stored in the buffer container.

This overload of the method allows the user to specify a processing queue set that is to be used to perform the averaging.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
EmptyWrapperError
InstrumentDeviceError

Parameters:

pqs – The processing queue set to use to perform the averaging operation
targetDataType – The data type of the averaged data. Note that if an integer type is specified here (even though the original data is an integer) this may result in a loss of precision as the fractional part of values will be truncated.

Returns:

The resulting persistent buffer that will contain the averaged data of the buffer container

createBufferContainer

inline BufferContainer fluxEngine::createBufferContainer(InstrumentDevice *device, std::size_t bufferCount)

Create a buffer container.

A buffer container is an object that the user may use to automatically copy data from device buffers into to create a multi-buffer measurement. That may be passed to newly created device processing contexts as reference data, or may later be used to extract individual measurements.

A buffer container is always created with the current dimensions and scalar type of the instrument; if the user changes the instrument’s parameters it may be the case that it does not fit the buffers of the device anymore.

A buffer container can hold at most the data of bufferCount device buffers.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
ObjectNoLongerValidError
EmptyWrapperError
InstrumentDeviceError

Parameters:

device – The device to create the buffer container for
bufferCount – The capacity of the buffer container in number of device buffers. A larger number will lead to the usage of more RAM.

Returns:

The newly created buffer container

inline BufferContainer fluxEngine::createBufferContainer(ProcessingContext &recordingContext, std::size_t bufferCount)

Create a buffer container from a recording context.

This allows the user to create a buffer container that may be used in conjunction with recording processing contexts (created via ProcessingContext::createInstrumentProcessingContext()) to record the standardized data.

For example, this may be used to record a HSI cube from a hyperspectral camera, and later save it.

Use BufferContainer::addLastResult() to add the last result of a recording context (after processing a device buffer) to the current buffer container.

Parameters:

recordingContext – The processing context to create the buffer container for. It must be a recording context, and the device must be a line camera or similar.
bufferCount – The capacity of the buffer container in number of results of the recording context. A larger number will lead to the usage of more RAM.

Returns:

The newly created buffer container

createRingBufferContainer

inline BufferContainer fluxEngine::createRingBufferContainer(InstrumentDevice *device, std::size_t capacity)

Create a ring buffer container.

A buffer container is an object that the user may use to automatically copy data from device buffers into to create a multi-buffer measurement. That may be passed to newly created device processing contexts as reference data, or may later be used to extract individual measurements.

This function creates a container that is a ring buffer, so that data may be added continually. Only the last capacity entries may be retrieved, but the index will always increase.

A buffer container is always created with the current dimensions and scalar type of the instrument; if the user changes the instrument’s parameters it may be the case that it does not fit the buffers of the device anymore.

When passing a ring buffer into fluxEngine (e.g. as a white reference), if less than capacity elements have been added to the ring buffer since the last reset, the buffer behaves identically to a standard buffer container. Otherwise only the last capacity elements will be used.

If an error occurs, an exception will be thrown. The following exceptions may occur:

std::bad_alloc
std::invalid_argument
Error
ObjectNoLongerValidError
EmptyWrapperError
InstrumentDeviceError

Parameters:

device – The device to create the buffer container for
capacity – The capacity of the buffer container in number of device buffers. A larger number will lead to the usage of more RAM.

Returns:

The newly created buffer container

inline BufferContainer fluxEngine::createRingBufferContainer(ProcessingContext &recordingContext, std::size_t capacity)

Create a ring buffer container from a recording context.

This allows the user to create a buffer container that may be used in conjunction with recording processing contexts (created via ProcessingContext::createInstrumentProcessingContext()) to record the standardized data.

For example, this may be used to record a HSI cube from a hyperspectral camera, and later save it.

Use BufferContainer::addLastResult() to add the last result of a recording context (after processing a device buffer) to the current buffer container.

This function creates a container that is a ring buffer, so that data may be added continually. Only the last capacity entries may be retrieved, but the index will always increase.

When passing a ring buffer into fluxEngine (e.g. when creating a measurement), if less than capacity elements have been added to the ring buffer since the last reset, the buffer behaves identically to a standard buffer container. Otherwise only the last capacity elements will be used.

Parameters:

recordingContext – The processing context to create the buffer container for. It must be a recording context, and the device must be a line camera or similar.
capacity – The capacity of the buffer container in number of results of the recording context. A larger number will lead to the usage of more RAM.

Returns:

The newly created buffer container

expandedDataType

inline DataType fluxEngine::expandedDataType(BufferScalarType type) noexcept

Get the expanded data type corresponding to a buffer scalar data type.

This will return the nearest type that a buffer scalar data type can be expanded into. For example, a 12bit packed integer can be expanded into a 16bit integer. If the buffer scalar data type has a direct correspondence, the direct type will be returned.

This function is intended for single-channel data.

For multi-channel packed data (such as RGB) future versions of fluxEngine will provide an alternative function.

This method exists primarily to automatically obtain a useful scalar type for the use in conjunction with BufferInfo::copyRawData() if the user wants to show the raw data. (Though the user could always force BufferInfo::copyRawData() to expand the data into a floating point type.)

Parameters:: type – The buffer scalar type to expand
Returns:: The processing data type that the buffer type can be expanded into