Devices

enum 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.

enum 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

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

struct fluxEngine::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.

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:

Return

The device group after a successful connection

Parameters

  • h: The fluxEngine handle

  • settings: The settings that select the device and the connection parameters.

class fluxEngine::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.

Note: currently there are no drivers that actually provide subdevices.

Public Types

enum 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.

See

LightControlDevice::Status::IrrecoverableError

See

InstrumentDevice::Status::IrrecoverableError

enumerator RecoverableError

Recoverable error.

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

See

LightControlDevice::Status::RecoverableError

See

InstrumentDevice::Status::RecoverableError

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.

Return

A reference to *this

Parameters

  • other: The device group to move

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:

Return

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:

Return

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:

Return

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:

Return

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:

Return

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:

Return

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:

Return

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.

class fluxEngine::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 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:

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:

inline DeviceType type() const

Get the device type.

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

Return

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:

Return

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:

Return

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:

Return

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:

Return

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:

Return

The parameter list

Parameters

  • type: The type of parameter list to get

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:

Return

The parameter’s type

Parameters

  • name: The name of the parameter

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:

Return

The parameter’s value, as a string

Parameters

  • name: The name of the parameter

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:

Return

The parameter’s value, as an integer

Parameters

  • name: The name of the parameter

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:

Return

The parameter’s value, as an floating point value

Parameters

  • name: The name of the parameter

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:

Return

The parameter’s value, as an boolean

Parameters

  • name: The name of the parameter

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:

Return

Whether the command has completed

Parameters

  • name: The name of the parameter

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:

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:

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:

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:

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:

Parameters

  • name: The name of the parameter

class fluxEngine::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 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 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:

Return

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:

Return

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.

class fluxEngine::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:

Public Types

enum 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:

Return

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:

Return

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:

Return

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 insetruments that just retun a single scalar value.

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

Return

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 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:

Return

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:

Return

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:

Return

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.

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.

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:

Return

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.

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.

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.

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" 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 of 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.

struct fluxEngine::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:

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 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:

Return

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:

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.

class fluxEngine::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:

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.

Return

A reference to *this

Parameters

  • other: The persistent buffer to move

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:

Return

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:

Return

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:

Return

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:

Return

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:

Return

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:

Return

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:

Return

The number of bytes in the 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:

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 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:

Return

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:

Parameters

  • target: The persistent buffer to copy the data into

class fluxEngine::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.

Return

A reference to *this

Parameters

  • other: The object to move

inline ~BufferContainer() noexcept

Destructor.

inline std::size_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 an error occurs, an exception will be thrown. The following exceptions may occur:

Return

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:

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:

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:

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:

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:

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:

Return

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:

Return

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:

Return

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:

Return

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:

Return

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:

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(size_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:

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(size_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:

Return

The new persistent buffer

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

inline void copyIntoBuffer(size_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:

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

Warning

doxygenfunction: Unable to resolve function “fluxEngine::createBufferContainer” with arguments None in doxygen xml output for project “fluxEngineAPI” from directory: /root/.conan/data/fluxEnginePublicDoc/4.8.0/luxflux/stable/build/5deba6ec0b5861186cd5f3983320ef40ad940a1e/xml. Potential matches: 

- BufferContainer createBufferContainer(InstrumentDevice *device, std::size_t bufferCount)
- BufferContainer createBufferContainer(ProcessingContext &recordingContext, std::size_t bufferCount)