Devices

DeviceGroup

typedef struct fluxEngine_C_v1_DeviceGroup fluxEngine_C_v1_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 fluxEngine_C_v1_DeviceGroup_get_primary_device() 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.

ConnectionParameter

struct fluxEngine_C_v1_ConnectionParameter

Connection parameter.

A parameter that may be supplied to fluxEngine_C_v1_DeviceGroup_connect(). Some devices require that some parameters are set, while other devices have optional parameters, while yet others may not require any parameters at all.

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

Public Members

char const *name

The name of the parameter.

This must be identical to the name of the parameter returned by the fluxEngine_C_v1_ParameterInfo accessors while inspecting connection parameters.

char const *value

The value of the parameter.

The value must be a serialized string of the parameter’s value.

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.

ConnectionSettings

struct fluxEngine_C_v1_ConnectionSettings

Connection settings.

This structure must be passed to fluxEngine_C_v1_DeviceGroup_connect() and contains the required information to connect to a given device. Future-proof code should always initialize this structure with 0 bytes and then fill out the fields it knows about.

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

Public Members

size_t structure_size

The size of the structure.

This must be filled by the user to contain sizeof(fluxEngine_C_v1_ConnectionSettings) as a future proofing mechanism.

char const *driver_name

The name of the driver.

This should be the value returned by fluxEngine_C_v1_EnumeratedDriver_get_name().

fluxEngine_C_v1_DriverType driver_type

The type of the driver.

This should be the value returned by fluxEngine_C_v1_EnumeratedDriver_get_type().

void const *id

The id of the device to connect to.

This should be the value returned by fluxEngine_C_v1_EnumeratedDevice_get_id().

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.

size_t id_length

The length of the id in bytes.

This should be the length returned by fluxEngine_C_v1_EnumeratedDevice_get_id().

fluxEngine_C_v1_ConnectionParameter const *parameters

The connection parameters to use.

This is a C array of length parameter_count. The following code shows how this could be allocated:

fluxEngine_C_v1_ConnectionParameter* params =
    (fluxEngine_C_v1_ConnectionParameter*)
    calloc(2, sizeof(fluxEngine_C_v1_ConnectionParameter));
params[0].name = "Parameter1";
params[0].value = "Value1";
params[1].name = "Parameter2";
params[1].value = "Value2";

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.

size_t parameter_count: The number of parameters.

int64_t connect_timeout_ms

The connection timeout in milliseconds.

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 pass_through_error_output

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.

This member was not present in fluxEngine versions before 4.3.6, and fluxEngine is binary compatible with the previous verison of this structure that doesn’t include this member.

DeviceGroup_connect

int fluxEngine_C_v1_DeviceGroup_connect(fluxEngine_C_v1_Handle *handle, fluxEngine_C_v1_ConnectionSettings const *settings, fluxEngine_C_v1_DeviceGroup **device_group, fluxEngine_C_v1_Error **error)

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.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_HandleNoLongerValid
fluxEngine_C_v1_ErrorCode_DriverNotFound
fluxEngine_C_v1_ErrorCode_DeviceConnectionEnumerationTimeout
fluxEngine_C_v1_ErrorCode_DeviceConnectionParametrizationError
fluxEngine_C_v1_ErrorCode_NotImplemented
fluxEngine_C_v1_ErrorCode_DeviceConnectionFailed
fluxEngine_C_v1_ErrorCode_DeviceParameterReadError
fluxEngine_C_v1_ErrorCode_DeviceParameterNotFound
fluxEngine_C_v1_ErrorCode_DeviceParameterTypeError

Parameters:

handle – The fluxEngine handle
settings – The settings that select the device and the connection parameters.
device_group – [out] The resulting device group
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

DeviceGroup_disconnect

void fluxEngine_C_v1_DeviceGroup_disconnect(fluxEngine_C_v1_DeviceGroup *device_group, int64_t timeout_ms)

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

device_group – The device group to disconnect
timeout_ms – 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 (5000).

DeviceGroup_unload

void fluxEngine_C_v1_DeviceGroup_unload(fluxEngine_C_v1_DeviceGroup *device_group)

Force-unload the driver isolation process of a device group.

This will force a disconnect of the device group by terminating the driver isolation process immediately, without invoking any disconnection function. This should typically not be called, and fluxEngine_C_v1_DeviceGroup_disconnect() is the preferred manner to disconnect from a device, as terminating a driver process is

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:

device_group – The device group to forcibly disconnect

DeviceGroup_get_primary_device

int fluxEngine_C_v1_DeviceGroup_get_primary_device(fluxEngine_C_v1_DeviceGroup *device_group, fluxEngine_C_v1_Device **device, fluxEngine_C_v1_Error **error)

Get the primary device of the device group.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument

Parameters:

device_group – The device group
device – [out] 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.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

DeviceGroup_get_driver_name

int fluxEngine_C_v1_DeviceGroup_get_driver_name(fluxEngine_C_v1_DeviceGroup *device_group, char **name, fluxEngine_C_v1_Error **error)

Get the name of the driver.

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

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument

Parameters:

device_group – The device group to query
name – [out] The name of the driver. The user must free the result with the fluxEngine_C_v1_string_free() function.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

DeviceGroup_get_driver_type

int fluxEngine_C_v1_DeviceGroup_get_driver_type(fluxEngine_C_v1_DeviceGroup *device_group, fluxEngine_C_v1_DriverType *type, fluxEngine_C_v1_Error **error)

Get the type of the driver.

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

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument

Parameters:

device_group – The device group to query
type – [out] The type of the driver
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

DeviceGroup_get_driver_description

int fluxEngine_C_v1_DeviceGroup_get_driver_description(fluxEngine_C_v1_DeviceGroup *device_group, char **description, fluxEngine_C_v1_Error **error)

Get the driver description.

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

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument

Parameters:

device_group – The device group to query
description – [out] The description of the driver. The user must free the result with the fluxEngine_C_v1_string_free() function.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

DeviceGroup_get_driver_version

int fluxEngine_C_v1_DeviceGroup_get_driver_version(fluxEngine_C_v1_DeviceGroup *device_group, char **version, fluxEngine_C_v1_Error **error)

Get the driver version.

Returns a human-readable version string of the driver.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument

Parameters:

device_group – The device group to query
version – [out] The version of the driver. The user must free the result with the fluxEngine_C_v1_string_free() function.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

DeviceNotificationType

enum fluxEngine_C_v1_DeviceNotificationType

Device notification type.

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

Values:

enumerator fluxEngine_C_v1_DeviceNotificationType_None

No notification.

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

enumerator fluxEngine_C_v1_DeviceNotificationType_IrrecoverableError

Irrecoverable error.

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

enumerator fluxEngine_C_v1_DeviceNotificationType_RecoverableError

Recoverable error.

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

enumerator fluxEngine_C_v1_DeviceNotificationType_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.

DeviceGroup_get_notification_event

int fluxEngine_C_v1_DeviceGroup_get_notification_event(fluxEngine_C_v1_DeviceGroup *device_group, FLUXENGINE_EVENT_HANDLE *handle, fluxEngine_C_v1_Error **error)

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 fluxEngine_C_v1_DeviceGroup_get_notification().

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 fluxEngine_C_v1_DeviceGroup_get_notification() 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 fluxEngine_C_v1_DeviceGroup_get_notification() 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.)

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument

Parameters:

device_group – The device group
handle – [out] 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.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

DeviceGroup_get_notification

int fluxEngine_C_v1_DeviceGroup_get_notification(fluxEngine_C_v1_DeviceGroup *device_group, fluxEngine_C_v1_DeviceNotificationType *type, fluxEngine_C_v1_Device **device, char **message, fluxEngine_C_v1_Error **error)

Retrieve the last notification.

Retrieves the last notification in the internal notification buffer of the device group. If the type retrieved is fluxEngine_C_v1_DeviceNotificationType_None then no notification is currently present in the notification buffer, and the device and message parameters will not be set (and need thus not be freed by the user).

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

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument

Parameters:

device_group – The device group
type – [out] The type of the notification
device – [out] The device the notification has occurred for. This will be the same pointer that can also be obtained by either fluxEngine_C_v1_DeviceGroup_get_primary_device() or fluxEngine_C_v1_Device_get_subdevice().
message – [out] The notification message. This must be freed via fluxEngine_C_v1_string_free().
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

Device

typedef struct fluxEngine_C_v1_Device fluxEngine_C_v1_Device

Device.

This opaque handle describes a device that the user has connected to. There are several functions (mostly related to reading and writing parameters) that are generic to all types of devices, while other functions are specific to individual device types.

DeviceType

enum fluxEngine_C_v1_DeviceType

The type of the device.

Values:

enumerator fluxEngine_C_v1_DeviceType_Instrument

Instrument device.

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

enumerator fluxEngine_C_v1_DeviceType_LightControl: Light control device.

Device_num_subdevices

int fluxEngine_C_v1_Device_num_subdevices(fluxEngine_C_v1_Device *device, fluxEngine_C_v1_Error **error)

Get the number of subdevices of a device.

Devices are organized in a tree structure: each device group has a primary device, and each device can have any number of subdeviecs. In practice the tree will be one level deep at most, with typically not more than one or two subdevices for the primary devices, if at all.

Note that the result will be returned as the (non-negative) return value of this function and not as an output parameter. Please check for success of this function via the rc < 0 condition and not the rc != 0 check that may be used for other functions.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument

Parameters:

device – The device to query for subdevices
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

The number of subdevices in this list on success, -1 on failure

Device_get_subdevice

int fluxEngine_C_v1_Device_get_subdevice(fluxEngine_C_v1_Device *device, int index, fluxEngine_C_v1_Device **sub_device, fluxEngine_C_v1_Error **error)

Get a specific subdevice of a device.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument

Parameters:

device – The device
index – The index of the subdevice, starting at 0, ending at one less than the number of subdevices of the given device.
sub_device – [out] The subdevice. The handle of this subdevice will be valid as long as the device group is not disconnected. Multiple calls to this method with the same device and index parameters will result in the same subdevice pointer.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

Device_ping

int fluxEngine_C_v1_Device_ping(fluxEngine_C_v1_Device *device, fluxEngine_C_v1_Error **error)

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.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_DeviceNoLongerValid

Parameters:

device – The device to ping
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

Device_reset_error

int fluxEngine_C_v1_Device_reset_error(fluxEngine_C_v1_Device *device, fluxEngine_C_v1_Error **error)

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.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_DeviceNoLongerValid
fluxEngine_C_v1_ErrorCode_DeviceResetError

Parameters:

device – The device for which to reset the error
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

Device_get_type

int fluxEngine_C_v1_Device_get_type(fluxEngine_C_v1_Device *device, fluxEngine_C_v1_DeviceType *type, fluxEngine_C_v1_Error **error)

Get the device type.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument

Parameters:

device – The device
type – [out] The type of the device
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

Device_get_manufacturer

int fluxEngine_C_v1_Device_get_manufacturer(fluxEngine_C_v1_Device *device, char **name, fluxEngine_C_v1_Error **error)

Get the device’s manufacturer.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument

Parameters:

device – The device
name – [out] The name of the manufacturer, which must be freed via fluxEngine_C_v1_string_free(). The result will never be NULL on success, though it might be an empty string.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

Device_get_model

int fluxEngine_C_v1_Device_get_model(fluxEngine_C_v1_Device *device, char **name, fluxEngine_C_v1_Error **error)

Get the device’s model name.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument

Parameters:

device – The device
name – [out] The name of the manufacturer, which must be freed via fluxEngine_C_v1_string_free(). The result will never be NULL on success, though it might be an empty string.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

Device_get_description

int fluxEngine_C_v1_Device_get_description(fluxEngine_C_v1_Device *device, char **description, fluxEngine_C_v1_Error **error)

Get the device’s description.

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

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument

Parameters:

device – The device
description – [out] The description of the device, or NULL if the device does not have one. If the description is returned, it must be freed via fluxEngine_C_v1_string_free().
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

Device_get_serial_number

int fluxEngine_C_v1_Device_get_serial_number(fluxEngine_C_v1_Device *device, char **serial_number, fluxEngine_C_v1_Error **error)

Get the device’s serial number.

Some devices may have no serial number, but instrument devices will typically all have one.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument

Parameters:

device – The device
serial_number – [out] The serial number of the device, or NULL if the device does not have one. If the description is returned, it must be freed via fluxEngine_C_v1_string_free().
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

ParameterListType

enum fluxEngine_C_v1_ParameterListType

Parameter list type.

While devices have a single parameter namespace, and they can be read directly regardless of in which list they appear, there are separate parameter lists that can be obtained that have different meanings. This type must be supplied to fluxEngine_C_v1_Device_get_parameter_list() to obtain the list the user is interested in.

Values:

enumerator fluxEngine_C_v1_ParameterListType_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 fluxEngine_C_v1_ParameterListType_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 fluxEngine_C_v1_ParameterListType_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.

Device_get_parameter_list

int fluxEngine_C_v1_Device_get_parameter_list(fluxEngine_C_v1_Device *device, fluxEngine_C_v1_ParameterListType type, fluxEngine_C_v1_ParameterInfo **parameter_info, fluxEngine_C_v1_Error **error)

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.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_DeviceNoLongerValid
fluxEngine_C_v1_ErrorCode_DeviceParameterListNotFound

Parameters:

device – The device
type – The type of parameter list to get
parameter_info – [out] The parameter list of the device. It must be freed by the user via fluxEngine_C_v1_ParameterInfo_free(). If the device group is disconnected the parameter list object will still exist, albeit be quite useless. It must still be freed in that case.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

Device_get_parameter_type

int fluxEngine_C_v1_Device_get_parameter_type(fluxEngine_C_v1_Device *device, char const *name, fluxEngine_C_v1_ParameterType *type, fluxEngine_C_v1_Error **error)

Get the type of a specific parameter.

This exists to allow the user to easily determine the type of a specific parameter without having to first obtain all three parameter lists to determine that information.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_DeviceNoLongerValid
fluxEngine_C_v1_ErrorCode_DeviceParameterNotFound

Parameters:

device – The device
name – The name of the parameter
type – [out] The type of the parameter
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

Device_get_parameter_string

int fluxEngine_C_v1_Device_get_parameter_string(fluxEngine_C_v1_Device *device, char const *name, char **value, fluxEngine_C_v1_Error **error)

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 fluxEngine_C_v1_ConnectionParameter::value for rules on how different types of parameters are converted.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_DeviceNoLongerValid
fluxEngine_C_v1_ErrorCode_DeviceParameterNotFound
fluxEngine_C_v1_ErrorCode_DeviceParameterAccessError
fluxEngine_C_v1_ErrorCode_DeviceParameterReadError

Parameters:

device – The device
name – The name of the parameter
value – [out] The value of the parameter, which must be freed via fluxEngine_C_v1_string_free().
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

Device_get_parameter_integer

int fluxEngine_C_v1_Device_get_parameter_integer(fluxEngine_C_v1_Device *device, char const *name, int64_t *value, fluxEngine_C_v1_Error **error)

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.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_DeviceNoLongerValid
fluxEngine_C_v1_ErrorCode_DeviceParameterNotFound
fluxEngine_C_v1_ErrorCode_DeviceParameterTypeError
fluxEngine_C_v1_ErrorCode_DeviceParameterAccessError
fluxEngine_C_v1_ErrorCode_DeviceParameterReadError

Parameters:

device – The device
name – The name of the parameter
value – [out] The value of the parameter
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

Device_get_parameter_float

int fluxEngine_C_v1_Device_get_parameter_float(fluxEngine_C_v1_Device *device, char const *name, double *value, fluxEngine_C_v1_Error **error)

Get a parameter (floating point)

This will only work for floating point parameters.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_DeviceNoLongerValid
fluxEngine_C_v1_ErrorCode_DeviceParameterNotFound
fluxEngine_C_v1_ErrorCode_DeviceParameterTypeError
fluxEngine_C_v1_ErrorCode_DeviceParameterAccessError
fluxEngine_C_v1_ErrorCode_DeviceParameterReadError

Parameters:

device – The device
name – The name of the parameter
value – [out] The value of the parameter
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

Device_get_parameter_bool

int fluxEngine_C_v1_Device_get_parameter_bool(fluxEngine_C_v1_Device *device, char const *name, bool *value, fluxEngine_C_v1_Error **error)

Get a parameter (boolean)

This will only work for boolean parameters.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_DeviceNoLongerValid
fluxEngine_C_v1_ErrorCode_DeviceParameterNotFound
fluxEngine_C_v1_ErrorCode_DeviceParameterTypeError
fluxEngine_C_v1_ErrorCode_DeviceParameterAccessError
fluxEngine_C_v1_ErrorCode_DeviceParameterReadError

Parameters:

device – The device
name – The name of the parameter
value – [out] The value of the parameter
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

Device_is_parameter_command_complete

int fluxEngine_C_v1_Device_is_parameter_command_complete(fluxEngine_C_v1_Device *device, char const *name, fluxEngine_C_v1_Error **error)

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.

Note that the result will be returned as the (non-negative) return value of this function and not as an output parameter. Please check for success of this function via the rc < 0 condition and not the rc != 0 check that may be used for other functions.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_DeviceNoLongerValid
fluxEngine_C_v1_ErrorCode_DeviceParameterNotFound
fluxEngine_C_v1_ErrorCode_DeviceParameterTypeError
fluxEngine_C_v1_ErrorCode_DeviceParameterAccessError
fluxEngine_C_v1_ErrorCode_DeviceParameterReadError

Parameters:

device – The device
name – The name of the parameter
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 if the command is not complete, 1 if it is, and -1 if this call failed

Device_set_parameter_string

int fluxEngine_C_v1_Device_set_parameter_string(fluxEngine_C_v1_Device *device, char const *name, char const *value, fluxEngine_C_v1_Error **error)

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 fluxEngine_C_v1_ConnectionParameter::value 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 fluxEngine_C_v1_InstrumentDeviceStatus_ForcedStop to indicate this. The user must then call fluxEngine_C_v1_InstrumentDevice_stop_acquisition() to stop acquisition on fluxEngine’s side and may then use fluxEngine_C_v1_InstrumentDevice_start_acquisition() 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.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_DeviceNoLongerValid
fluxEngine_C_v1_ErrorCode_DeviceParameterNotFound
fluxEngine_C_v1_ErrorCode_DeviceParameterAccessError
fluxEngine_C_v1_ErrorCode_DeviceParameterReadError
fluxEngine_C_v1_ErrorCode_DeviceParameterWriteError

Parameters:

device – The device
name – The name of the parameter
value – The value of the parameter
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

Device_set_parameter_integer

int fluxEngine_C_v1_Device_set_parameter_integer(fluxEngine_C_v1_Device *device, char const *name, int64_t value, fluxEngine_C_v1_Error **error)

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 fluxEngine_C_v1_InstrumentDeviceStatus_ForcedStop to indicate this. The user must then call fluxEngine_C_v1_InstrumentDevice_stop_acquisition() to stop acquisition on fluxEngine’s side and may then use fluxEngine_C_v1_InstrumentDevice_start_acquisition() 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.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_DeviceNoLongerValid
fluxEngine_C_v1_ErrorCode_DeviceParameterNotFound
fluxEngine_C_v1_ErrorCode_DeviceParameterTypeError
fluxEngine_C_v1_ErrorCode_DeviceParameterAccessError
fluxEngine_C_v1_ErrorCode_DeviceParameterReadError
fluxEngine_C_v1_ErrorCode_DeviceParameterWriteError

Parameters:

device – The device
name – The name of the parameter
value – The value of the parameter
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

Device_set_parameter_float

int fluxEngine_C_v1_Device_set_parameter_float(fluxEngine_C_v1_Device *device, char const *name, double value, fluxEngine_C_v1_Error **error)

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 fluxEngine_C_v1_InstrumentDeviceStatus_ForcedStop to indicate this. The user must then call fluxEngine_C_v1_InstrumentDevice_stop_acquisition() to stop acquisition on fluxEngine’s side and may then use fluxEngine_C_v1_InstrumentDevice_start_acquisition() 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.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_DeviceNoLongerValid
fluxEngine_C_v1_ErrorCode_DeviceParameterNotFound
fluxEngine_C_v1_ErrorCode_DeviceParameterTypeError
fluxEngine_C_v1_ErrorCode_DeviceParameterAccessError
fluxEngine_C_v1_ErrorCode_DeviceParameterReadError
fluxEngine_C_v1_ErrorCode_DeviceParameterWriteError

Parameters:

device – The device
name – The name of the parameter
value – The value of the parameter
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

Device_set_parameter_bool

int fluxEngine_C_v1_Device_set_parameter_bool(fluxEngine_C_v1_Device *device, char const *name, bool value, fluxEngine_C_v1_Error **error)

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 fluxEngine_C_v1_InstrumentDeviceStatus_ForcedStop to indicate this. The user must then call fluxEngine_C_v1_InstrumentDevice_stop_acquisition() to stop acquisition on fluxEngine’s side and may then use fluxEngine_C_v1_InstrumentDevice_start_acquisition() 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.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_DeviceNoLongerValid
fluxEngine_C_v1_ErrorCode_DeviceParameterNotFound
fluxEngine_C_v1_ErrorCode_DeviceParameterTypeError
fluxEngine_C_v1_ErrorCode_DeviceParameterAccessError
fluxEngine_C_v1_ErrorCode_DeviceParameterReadError
fluxEngine_C_v1_ErrorCode_DeviceParameterWriteError

Parameters:

device – The device
name – The name of the parameter
value – The value of the parameter
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

Device_execute_parameter_command

int fluxEngine_C_v1_Device_execute_parameter_command(fluxEngine_C_v1_Device *device, char const *name, fluxEngine_C_v1_Error **error)

Execute a command parameter.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_DeviceNoLongerValid
fluxEngine_C_v1_ErrorCode_DeviceParameterNotFound
fluxEngine_C_v1_ErrorCode_DeviceParameterTypeError
fluxEngine_C_v1_ErrorCode_DeviceParameterAccessError
fluxEngine_C_v1_ErrorCode_DeviceParameterReadError
fluxEngine_C_v1_ErrorCode_DeviceParameterWriteError

Parameters:

device – The device
name – The name of the parameter
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

LightControlDeviceStatus

enum fluxEngine_C_v1_LightControlDeviceStatus

Light control device status.

Values:

enumerator fluxEngine_C_v1_LightControlDeviceStatus_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 fluxEngine_C_v1_LightControlDeviceStatus_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 fluxEngine_C_v1_LightControlDeviceStatus_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 fluxEngine_C_v1_Device_reset_error()) then this will be the status the device will have.

enumerator fluxEngine_C_v1_LightControlDeviceStatus_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 fluxEngine_C_v1_LightControlDeviceStatus_Parametrized instead. If the light is switched off again via parameters it will still remain in the fluxEngine_C_v1_LightControlDeviceStatus_Parametrized state.

enumerator fluxEngine_C_v1_LightControlDeviceStatus_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 fluxEngine_C_v1_LightControlDeviceStatus_ForcedOff

The light has been forced off.

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

enumerator fluxEngine_C_v1_LightControlDeviceStatus_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 fluxEngine_C_v1_LightControlDeviceStatus_Parametrized state.

LightControlDevice_get_status

int fluxEngine_C_v1_LightControlDevice_get_status(fluxEngine_C_v1_Device *device, fluxEngine_C_v1_LightControlDeviceStatus *status, fluxEngine_C_v1_Error **error)

Get the status of a light control device.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_DeviceTypeError
fluxEngine_C_v1_ErrorCode_DeviceStatusQueryError

Parameters:

device – The light control device
status – [out] The device’s status
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

LightControlDeviceForceState

enum fluxEngine_C_v1_LightControlDeviceForceState

The force state of the light control device.

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

Values:

enumerator fluxEngine_C_v1_LightControlDeviceForceState_None

The device should be parametrized.

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

enumerator fluxEngine_C_v1_LightControlDeviceForceState_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 fluxEngine_C_v1_LightControlDeviceForceState_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 fluxEngine_C_v1_LightControlDeviceForceState_None once the ramp has completed.

LightControlDevice_set_force_state

int fluxEngine_C_v1_LightControlDevice_set_force_state(fluxEngine_C_v1_Device *device, fluxEngine_C_v1_LightControlDeviceForceState state, int64_t ramp_duration_ms, fluxEngine_C_v1_Error **error)

Set a light control device’s force state.

See the explanations of the different force states for further details.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_DeviceNoLongerValid
fluxEngine_C_v1_ErrorCode_DeviceTypeError
fluxEngine_C_v1_ErrorCode_LightControlDeviceForceStateError

Parameters:

device – The light control device
state – The new force state
ramp_duration_ms – 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.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

LightControlDevice_wait_for_ramp

int fluxEngine_C_v1_LightControlDevice_wait_for_ramp(fluxEngine_C_v1_Device *device, fluxEngine_C_v1_Error **error)

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 immediately but return 0. If the ramp is active when this function is called it will return only once the ramp has completed.

Note that the result will be returned as the (non-negative) return value of this function and not as an output parameter. Please check for success of this function via the rc < 0 condition and not the rc != 0 check that may be used for other functions.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_DeviceNoLongerValid
fluxEngine_C_v1_ErrorCode_DeviceTypeError
fluxEngine_C_v1_ErrorCode_LightControlDeviceRampError

Parameters:

device – The light control device
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 if no ramp was in progress, 1 if the ramp has completed during a call to this method, and -1 on failure

BufferScalarType

enum fluxEngine_C_v1_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 fluxEngine_C_v1_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 fluxEngine_C_v1_DataType enumeration, this will change in future versions.

See also

fluxEngine_C_v1_expandedDataType()

Values:

enumerator fluxEngine_C_v1_BufferScalarType_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 fluxEngine_C_v1_BufferScalarType_UInt8: 8bit unsigned integer

enumerator fluxEngine_C_v1_BufferScalarType_UInt16: 16bit unsigned integer

enumerator fluxEngine_C_v1_BufferScalarType_UInt32: 32bit unsigned integer

enumerator fluxEngine_C_v1_BufferScalarType_UInt64: 64bit unsigned integer

enumerator fluxEngine_C_v1_BufferScalarType_Int8: 8bit signed integer

enumerator fluxEngine_C_v1_BufferScalarType_Int16: 16bit signed integer

enumerator fluxEngine_C_v1_BufferScalarType_Int32: 32bit signed integer

enumerator fluxEngine_C_v1_BufferScalarType_Int64: 64bit signed integer

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

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

expandedDataType

fluxEngine_C_v1_DataType fluxEngine_C_v1_expandedDataType(fluxEngine_C_v1_BufferScalarType type)

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 fluxEngine_C_v1_Buffer_copy_raw_data() if the user wants to show the raw data. (Though the user could always force fluxEngine_C_v1_Buffer_copy_raw_data() 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

InstrumentDeviceStatus

enum fluxEngine_C_v1_InstrumentDeviceStatus

Instrument device status.

Values:

enumerator fluxEngine_C_v1_InstrumentDeviceStatus_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 fluxEngine_C_v1_InstrumentDeviceStatus_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 fluxEngine_C_v1_InstrumentDeviceStatus_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 fluxEngine_C_v1_Device_reset_error()) then this will be the status the device will have.

enumerator fluxEngine_C_v1_InstrumentDeviceStatus_Idle

The instrument is idle.

The instrument is idle and not returning data.

enumerator fluxEngine_C_v1_InstrumentDeviceStatus_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 fluxEngine_C_v1_InstrumentDeviceStatus_Streaming

The instrument is streaming data.

The instrument is streaming data to the user.

enumerator fluxEngine_C_v1_InstrumentDeviceStatus_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.)

InstrumentDevice_get_status

int fluxEngine_C_v1_InstrumentDevice_get_status(fluxEngine_C_v1_Device *device, fluxEngine_C_v1_InstrumentDeviceStatus *status, fluxEngine_C_v1_Error **error)

Get the status of an instrument device.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_DeviceTypeError
fluxEngine_C_v1_ErrorCode_DeviceStatusQueryError

Parameters:

device – The instrument device
status – [out] The device’s status
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

InstrumentDevice_get_max_buffer_size

int fluxEngine_C_v1_InstrumentDevice_get_max_buffer_size(fluxEngine_C_v1_Device *device, size_t *size, fluxEngine_C_v1_Error **error)

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.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_DeviceTypeError
fluxEngine_C_v1_ErrorCode_DeviceNoLongerValid

Parameters:

device – The instrument device
size – [out] The maximum buffer size the instrument may return
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

InstrumentDevice_get_recommended_buffer_count

int fluxEngine_C_v1_InstrumentDevice_get_recommended_buffer_count(fluxEngine_C_v1_Device *device, size_t *size, fluxEngine_C_v1_Error **error)

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.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_DeviceTypeError
fluxEngine_C_v1_ErrorCode_DeviceNoLongerValid

Parameters:

device – The instrument device
size – [out] The number of recommended buffers
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

InstrumentDevice_get_raw_buffer_dimensions

int fluxEngine_C_v1_InstrumentDevice_get_raw_buffer_dimensions(fluxEngine_C_v1_Device *device, int64_t dimensions[5], int *order, fluxEngine_C_v1_Error **error)

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

Given the current device parameters return the dimensions of the buffer that will be returned by the device.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_DeviceTypeError
fluxEngine_C_v1_ErrorCode_DeviceNoLongerValid
fluxEngine_C_v1_ErrorCode_InstrumentDeviceIncompatibleError

Parameters:

device – The instrument device
dimensions – [out] The user must provide an array of 5 64bit integers where the dimensions will be stored in. Only the first order entries will have any meaning.
order – [out] The tensor order of the buffer. For cameras this will typically be 2, for spectrometers 1.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

InstrumentDevice_get_raw_buffer_scalar_type

int fluxEngine_C_v1_InstrumentDevice_get_raw_buffer_scalar_type(fluxEngine_C_v1_Device *device, fluxEngine_C_v1_BufferScalarType *type, fluxEngine_C_v1_Error **error)

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

Given the current parameters return the scalar type of the data returned by the device.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_DeviceTypeError
fluxEngine_C_v1_ErrorCode_DeviceNoLongerValid
fluxEngine_C_v1_ErrorCode_InstrumentDeviceIncompatibleError

Parameters:

device – The instrument device
type – [out] The scalar type of the buffer
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

InstrumentDevice_get_raw_buffer_value_range

int fluxEngine_C_v1_InstrumentDevice_get_raw_buffer_value_range(fluxEngine_C_v1_Device *device, float *lower_value, float *upper_value, fluxEngine_C_v1_Error **error)

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.

Parameters:

device – The instrument device
lower_value – [out] The smallest value that the user may encounter in a raw instrument buffer
upper_value – [out] The largest value that the user may encounter in a raw instrument buffer
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

InstrumentDevice_get_raw_buffer_dimension_labels

int fluxEngine_C_v1_InstrumentDevice_get_raw_buffer_dimension_labels(fluxEngine_C_v1_Device *device, int dimension, char **type, char **unit, size_t *count, double **values, fluxEngine_C_v1_Error **error)

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.

This method will allocate various strings, as well as a vector of labels. The strings may be freed via fluxEngine_C_v1_string_free(), while the labels vector may be freed via fluxEngine_C_v1_wavelengths_free() by the user.

The type parameter will be filled with a string that may be one of the following values:

NULL: indicates that the type could not be determined or that the current version of fluxEngine does not understand the type the driver provides
"" (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

The unit parameter will be filled with a string that may be one of the following values:

NULL: indicates that the unit could not be determined or that the current version of fluxEngine does not understand te unit the driver provides. In this case it is likely that no specific label values are provided.
"" (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.

The values parameter will be filled if there are useful numeric values available for a dimension. For dimensions that correspond to pixels this will typically not be the case, so in that case the values parameter will be set to 0. That will indicate that the labels should be considered by the user to be just a list of indexes, [0, 1, 2, …].

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_DeviceTypeError
fluxEngine_C_v1_ErrorCode_DeviceNoLongerValid
fluxEngine_C_v1_ErrorCode_InstrumentDeviceIncompatibleError

Parameters:

device – The instrument device
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 fluxEngine_C_v1_InstrumentDevice_get_raw_buffer_dimensions().
type – [out] The type of the labels. fluxEngine may set the variable the user provides here to NULL. If a string is returned, the user must later free it via fluxEngine_C_v1_string_free().
unit – [out] The unit of the labels. fluxEngine may set the variable the user provides here to NULL. If a string is returned, the user must later free it via fluxEngine_C_v1_string_free().
count – [out] The number of lables present. This will either be set to the same value as the size of the dimension, as may be obtained via fluxEngine_C_v1_InstrumentDevice_get_raw_buffer_dimensions(), or it may be set to 0 to indicate that no numeric label values are available for that dimension.
values – [out] The labels of the dimension. This will be set to a vector of values (the size will be stored in count), or to NULL to indicate that no numeric label values are available for that dimension. If a vector is stored in this user-provided parameter, it must be freed via fluxEngine_C_v1_wavelengths_free() by the user.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

InstrumentDevice_allocate_PersistentBuffer

int fluxEngine_C_v1_InstrumentDevice_allocate_PersistentBuffer(fluxEngine_C_v1_Device *device, fluxEngine_C_v1_PersistentBufferInfo **result, fluxEngine_C_v1_Error **error)

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.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_DeviceTypeError
fluxEngine_C_v1_ErrorCode_DeviceNoLongerValid
fluxEngine_C_v1_ErrorCode_InstrumentDeviceIncompatibleError

Parameters:

device – The instrument device
result – [out] The persistent buffer info
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

InstrumentDevice_setup_internal_buffers

int fluxEngine_C_v1_InstrumentDevice_setup_internal_buffers(fluxEngine_C_v1_Device *device, size_t count, fluxEngine_C_v1_Error **error)

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 fluxEngine_C_v1_InstrumentDevice_get_max_buffer_size() 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.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_DeviceTypeError
fluxEngine_C_v1_ErrorCode_DeviceNoLongerValid
fluxEngine_C_v1_ErrorCode_InstrumentDeviceShmAlreadySetup
fluxEngine_C_v1_ErrorCode_InstrumentDeviceShmSetupError

Parameters:

device – The instrument device
count – The number of buffers to allocate
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

InstrumentDeviceAcquisitionParameters

struct fluxEngine_C_v1_InstrumentDeviceAcquisitionParameters

Acquisition parameters.

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

Future-proof code should always initialize this structure with 0 bytes and then fill out the fields it knows about.

Public Members

size_t structure_size

The size of the structure.

This must be filled by the user to contain sizeof(fluxEngine_C_v1_InstrumentDeviceAcquisitionParameters) as a future proofing mechanism.

size_t buffer_count

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.

char const *reference_name

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) measuremnet is to be performed.

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

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.

InstrumentDevice_start_acquisition

int fluxEngine_C_v1_InstrumentDevice_start_acquisition(fluxEngine_C_v1_Device *device, fluxEngine_C_v1_InstrumentDeviceAcquisitionParameters const *parameters, fluxEngine_C_v1_Error **error)

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 fluxEngine_C_v1_InstrumentDevice_retrieve_buffer() and fluxEngine_C_v1_InstrumentDevice_retrieve_buffer_ex() functions.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_DeviceTypeError
fluxEngine_C_v1_ErrorCode_DeviceNoLongerValid
fluxEngine_C_v1_ErrorCode_InstrumentDeviceShmNotSetupError
fluxEngine_C_v1_ErrorCode_InstrumentDeviceInvalidReferenceName
fluxEngine_C_v1_ErrorCode_InstrumentDeviceAcquisitionStartError

Parameters:

device – The instrument device
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. The fluxEngine_C_v1_InstrumentDeviceAcquisitionParameters::structure_size must be filled though.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

InstrumentDevice_stop_acquisition

int fluxEngine_C_v1_InstrumentDevice_stop_acquisition(fluxEngine_C_v1_Device *device, fluxEngine_C_v1_Error **error)

Stop acquisition.

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

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_DeviceTypeError
fluxEngine_C_v1_ErrorCode_DeviceNoLongerValid
fluxEngine_C_v1_ErrorCode_InstrumentDeviceAcquisitionStopError

Parameters:

device – The instrument device
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

InstrumentDevice_retrieve_buffer

int fluxEngine_C_v1_InstrumentDevice_retrieve_buffer(fluxEngine_C_v1_Device *device, fluxEngine_C_v1_BufferInfo **buffer_info, int64_t timeout_ms, fluxEngine_C_v1_Error **error)

Retrieve a buffer from the device.

Acquisition must be active for this to succeed.

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

Note that the result will be returned as the (non-negative) return value of this function and not as an output parameter. Please check for success of this function via the rc < 0 condition and not the rc != 0 check that may be used for other functions.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_DeviceTypeError
fluxEngine_C_v1_ErrorCode_DeviceNoLongerValid
fluxEngine_C_v1_ErrorCode_InstrumentDeviceInternalBufferError

Parameters:

device – The instrument device
buffer_info – [out] The buffer handle. This will be NULL if this function returns 0, but will contain a valid handle if this function returns 1.
timeout_ms – 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.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

1 on success, 0 if no buffer is in the queue, -1 on failure

AbortCheckCallback

typedef bool (*fluxEngine_C_v1_AbortCheckCallback)(void *context)

Abort check callback.

This callback may be supplied by the user while retrieving buffers and/or returning buffers, in case these operations have to wait. This allows the user to cancel the operations while they are active without having to specify a very short timeout.

If this check function is provided it will be called in various intervals until a buffer has become available (while retrieving a buffer) or until there was space in the return queue to return the buffer.

Any such callback must behave in an idempotent manner.

Param context:: A user-provided context that will be passed to this callback
Return:: true if an abort has been requested in the mean time, false otherwise

InstrumentDevice_retrieve_buffer_ex

int fluxEngine_C_v1_InstrumentDevice_retrieve_buffer_ex(fluxEngine_C_v1_Device *device, fluxEngine_C_v1_BufferInfo **buffer_info, int64_t timeout_ms, fluxEngine_C_v1_AbortCheckCallback abort_check_function, void *abort_check_context, fluxEngine_C_v1_Error **error)

Retrieve a buffer from the device (with abort checks)

Acquisition must be active for this to succeed.

The buffer retrieved here must be returned via fluxEngine_C_v1_InstrumentDevice_return_buffer() 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.

Note that the result will be returned as the (non-negative) return value of this function and not as an output parameter. Please check for success of this function via the rc < 0 condition and not the rc != 0 check that may be used for other functions.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_DeviceTypeError
fluxEngine_C_v1_ErrorCode_DeviceNoLongerValid
fluxEngine_C_v1_ErrorCode_InstrumentDeviceInternalBufferError

Parameters:

device – The instrument device
buffer_info – [out] The buffer handle. This will be NULL if this function returns 0, but will contain a valid handle if this function returns 1.
timeout_ms – 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.
abort_check_function – The function that checks whether an external abort has been initiated. If the function returns true an external abort has been requested.
abort_check_context – A context to pass to the abort check function
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

1 on success, 0 if no buffer is in the queue or the abort check function indicated that acquisition should be aborted, -1 on failure

InstrumentDevice_return_buffer

int fluxEngine_C_v1_InstrumentDevice_return_buffer(fluxEngine_C_v1_Device *device, fluxEngine_C_v1_BufferInfo *buffer_info, fluxEngine_C_v1_Error **error)

Return a buffer to the instrument device.

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.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_DeviceTypeError
fluxEngine_C_v1_ErrorCode_DeviceNoLongerValid
fluxEngine_C_v1_ErrorCode_BufferAlreadyReturned

Parameters:

device – The instrument device
buffer_info – The buffer to return
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

InstrumentDevice_set_calibration_info

int fluxEngine_C_v1_InstrumentDevice_set_calibration_info(fluxEngine_C_v1_Device *device, fluxEngine_C_v1_CalibrationInfo const *calibration_info, fluxEngine_C_v1_Error **error)

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.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_DeviceTypeError
fluxEngine_C_v1_ErrorCode_DeviceNoLongerValid

Parameters:

device – The instrument device
calibration_info – The calibration info to use. Specify NULL here to clear any existing calibration info. The information will be copied, so the structure supplied here may be freed after a call to this method.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

BufferInfo

typedef struct fluxEngine_C_v1_BufferInfo fluxEngine_C_v1_BufferInfo

Buffer Info.

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

Buffer_get_number

int fluxEngine_C_v1_Buffer_get_number(fluxEngine_C_v1_BufferInfo const *buffer_info, int64_t *number, fluxEngine_C_v1_Error **error)

Get the number of the buffer.

The buffer number is a consecutive counter that indicates the amount of buffers the instrument has generated since start of the acquisition. For cameras this is the frame counter. This will typically start at 0 for the first buffer after acquisition start, but the user should not rely on this.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_BufferAlreadyReturned

Parameters:

buffer_info – The buffer
number – [out] The buffer number / frame number
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

Buffer_get_raw_dimensions

int fluxEngine_C_v1_Buffer_get_raw_dimensions(fluxEngine_C_v1_BufferInfo const *buffer_info, int64_t dimensions[5], int64_t strides[5], int *order, fluxEngine_C_v1_Error **error)

Get the raw dimensions of the buffer.

This will return the raw dimensions of the buffer that was retrieved.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_BufferAlreadyReturned

Parameters:

buffer_info – The buffer
dimensions – [out] An array of 5 64bit integers where the dimensions of the buffer are stored; only the first order dimensions are relevant.
strides – [out] An array of 5 64bit integers where the strides of the buffer are stored; only the first order dimensions are relevant. Note that with packed scalar buffer types the strides may have a non-obvious meanning
order – [out] The order of the raw data in the buffer. For cameras this is 2, for spectrometers this is 1.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

Buffer_get_raw_scalar_type

int fluxEngine_C_v1_Buffer_get_raw_scalar_type(fluxEngine_C_v1_BufferInfo const *buffer_info, fluxEngine_C_v1_BufferScalarType *type, fluxEngine_C_v1_Error **error)

Get the scalar type of the data in the buffer.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_BufferAlreadyReturned

Parameters:

buffer_info – The buffer
type – [out] The scalar type of the data in the buffer
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

Buffer_get_raw_data

int fluxEngine_C_v1_Buffer_get_raw_data(fluxEngine_C_v1_BufferInfo const *buffer_info, void const **data, size_t *size_bytes, fluxEngine_C_v1_Error **error)

Get the raw data of the buffer.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_BufferAlreadyReturned

Parameters:

buffer_info – The buffer
data – [out] Where to store a pointer to the current data of the buffer. This points to an internal region in the shared memory and should not be accessed once the buffer has been returned. Important: the precise location of this pointer depends on many things and the user should not make any assumptions about it
size_bytes – [out] The minimal number of bytes required to create a copy of the buffer with the same stride structure in another part of memory
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

Buffer_copy_raw_data

int fluxEngine_C_v1_Buffer_copy_raw_data(fluxEngine_C_v1_BufferInfo const *buffer_info, void *buffer, fluxEngine_C_v1_DataType data_type, int64_t const *strides, fluxEngine_C_v1_Error **error)

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 data_type parameter to a floating point type (32bit or 64bit) and the data will automatically be converted into that format.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_BufferAlreadyReturned

Parameters:

buffer_info – The buffer
buffer – [out] Where to store the data of the buffer
data_type – 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
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

Buffer_copy

int fluxEngine_C_v1_Buffer_copy(fluxEngine_C_v1_BufferInfo const *buffer_info, fluxEngine_C_v1_PersistentBufferInfo **result, fluxEngine_C_v1_Error **error)

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 allocates a new persistent buffer that has the correct size and type for the data in the buffer and returns the result.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_BufferAlreadyReturned

Parameters:

buffer_info – The buffer to copy
result – [out] The handle to the new persistent buffer
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

Buffer_copy_into

int fluxEngine_C_v1_Buffer_copy_into(fluxEngine_C_v1_BufferInfo const *buffer_info, fluxEngine_C_v1_PersistentBufferInfo *target, fluxEngine_C_v1_Error **error)

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.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_BufferAlreadyReturned
fluxEngine_C_v1_ErrorCode_BufferStructureMismatch

Parameters:

buffer_info – The buffer to copy
target – The handle to the persistent buffer to copy the data into
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

PersistentBufferInfo

typedef struct fluxEngine_C_v1_PersistentBufferInfo fluxEngine_C_v1_PersistentBufferInfo

Persistent buffer info.

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

PersistentBuffer_get_number

int fluxEngine_C_v1_PersistentBuffer_get_number(fluxEngine_C_v1_PersistentBufferInfo const *persistent_buffer_info, int64_t *number, fluxEngine_C_v1_Error **error)

Get the number of the persistent buffer.

The buffer number is a consecutive counter that indicates the amount of buffers the instrument has generated since start of the acquisition. For cameras this is the frame counter. This will typically start at 0 for the first buffer after acquisition start, but the user should not rely on this.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument

Parameters:

persistent_buffer_info – The persistent buffer
number – [out] The buffer number / frame number
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

PersistentBuffer_get_raw_dimensions

int fluxEngine_C_v1_PersistentBuffer_get_raw_dimensions(fluxEngine_C_v1_PersistentBufferInfo const *persistent_buffer_info, int64_t dimensions[5], int64_t strides[5], int *order, fluxEngine_C_v1_Error **error)

Get the raw dimensions of a persistent buffer.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument

Parameters:

persistent_buffer_info – The persistent buffer
dimensions – [out] An array of 5 64bit integers where the dimensions of the buffer are stored; only the first order dimensions are relevant.
strides – [out] An array of 5 64bit integers where the strides of the buffer are stored; only the first order dimensions are relevant. Note that with packed scalar buffer types the strides may have a non-obvious meanning
order – [out] The order of the raw data in the buffer. For cameras this is 2, for spectrometers this is 1.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

PersistentBuffer_get_raw_scalar_type

int fluxEngine_C_v1_PersistentBuffer_get_raw_scalar_type(fluxEngine_C_v1_PersistentBufferInfo const *persistent_buffer_info, fluxEngine_C_v1_BufferScalarType *type, fluxEngine_C_v1_Error **error)

Get the scalar type of the data in a persistent buffer.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument

Parameters:

persistent_buffer_info – The persistent buffer
type – [out] The scalar type of the data in the buffer
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

PersistentBuffer_get_raw_data

int fluxEngine_C_v1_PersistentBuffer_get_raw_data(fluxEngine_C_v1_PersistentBufferInfo const *persistent_buffer_info, void const **data, size_t *size_bytes, fluxEngine_C_v1_Error **error)

Get the raw data of a persistent buffer.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument

Parameters:

persistent_buffer_info – The persistent buffer
data – [out] Where to store a pointer to the current data of the buffer. This points to an internal region in the shared memory and should not be accessed once the buffer has been returned. Important: the precise location of this pointer depends on many things and the user should not make any assumptions about it
size_bytes – [out] The minimal number of bytes required to create a copy of the buffer with the same stride structure in another part of memory
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

PersistentBuffer_copy_raw_data

int fluxEngine_C_v1_PersistentBuffer_copy_raw_data(fluxEngine_C_v1_PersistentBufferInfo const *persistent_buffer_info, void *buffer, fluxEngine_C_v1_DataType data_type, int64_t const *strides, fluxEngine_C_v1_Error **error)

Copy and expand the raw data of a persistent 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 data_type parameter to a floating point type (32bit or 64bit) and the data will automatically be converted into that format.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument

Parameters:

persistent_buffer_info – The persistent buffer
buffer – [out] Where to store the data of the buffer
data_type – 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
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

PersistentBuffer_copy

int fluxEngine_C_v1_PersistentBuffer_copy(fluxEngine_C_v1_PersistentBufferInfo const *persistent_buffer_info, fluxEngine_C_v1_PersistentBufferInfo **result, fluxEngine_C_v1_Error **error)

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

This function allocates a new persistent buffer that is a duplicate of the persistent buffer provided.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument

Parameters:

persistent_buffer_info – The persistent buffer to copy
result – [out] The handle to the new persistent buffer
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

PersistentBuffer_copy_into

int fluxEngine_C_v1_PersistentBuffer_copy_into(fluxEngine_C_v1_PersistentBufferInfo const *persistent_buffer_info, fluxEngine_C_v1_PersistentBufferInfo *target, fluxEngine_C_v1_Error **error)

Copy the contents of the persistent buffer into another persistent buffer.

This function overwrites the data of the target persistent buffer with the data of the source persistent buffer. The user must ensure that the dimensions and type of the target buffer match the source buffer.

All data in the target 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.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_BufferStructureMismatch

Parameters:

persistent_buffer_info – The source persistent buffer
target – The handle to the target persistent buffer to copy the data into
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

PersistentBuffer_free

void fluxEngine_C_v1_PersistentBuffer_free(fluxEngine_C_v1_PersistentBufferInfo *persistent_buffer_info)

Free a persistent buffer.

The buffer must not be used after a call to this function.

Parameters:

persistent_buffer_info – The persistent buffer to free

BufferContainer

typedef struct fluxEngine_C_v1_BufferContainer fluxEngine_C_v1_BufferContainer

Buffer Container.

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

BufferContainer_create

int fluxEngine_C_v1_BufferContainer_create(fluxEngine_C_v1_Device *device, size_t count, fluxEngine_C_v1_BufferContainer **buffer_container, fluxEngine_C_v1_Error **error)

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 count device buffers.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_DeviceNoLongerValid
fluxEngine_C_v1_ErrorCode_DeviceTypeError
fluxEngine_C_v1_ErrorCode_InstrumentDeviceIncompatibleError

Parameters:

device – The device to create the buffer container for
count – The capacity of the buffer container in number of device buffers. A larger number will lead to the usage of more RAM.
buffer_container – [out] The newly created buffer container, which must be freed via fluxEngine_C_v1_BufferContainer_free().
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

BufferContainer_create_rb

int fluxEngine_C_v1_BufferContainer_create_rb(fluxEngine_C_v1_Device *device, size_t count, fluxEngine_C_v1_BufferContainer **buffer_container, fluxEngine_C_v1_Error **error)

Create a buffer container (ring buffer)

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. This function creates a container that is a ring buffer, so that data may be added continually. Only the last count 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 count 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 count elements will be used.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_DeviceNoLongerValid
fluxEngine_C_v1_ErrorCode_DeviceTypeError
fluxEngine_C_v1_ErrorCode_InstrumentDeviceIncompatibleError

Parameters:

device – The device to create the buffer container for
count – The capacity of the buffer container in number of device buffers. A larger number will lead to the usage of more RAM.
buffer_container – [out] The newly created buffer container, which must be freed via fluxEngine_C_v1_BufferContainer_free().
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

BufferContainer_get_count

int fluxEngine_C_v1_BufferContainer_get_count(fluxEngine_C_v1_BufferContainer *buffer_container, uint64_t *count, fluxEngine_C_v1_Error **error)

Get the number of buffers stored in the buffer container.

Immediately after creation or after a call to fluxEngine_C_v1_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.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument

Parameters:

buffer_container – The buffer container
count – [out] The number of buffers stored
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

BufferContainer_clear

int fluxEngine_C_v1_BufferContainer_clear(fluxEngine_C_v1_BufferContainer *buffer_container, fluxEngine_C_v1_Error **error)

Clear the buffer container.

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

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument

Parameters:

buffer_container – The buffer container
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

BufferContainer_add

int fluxEngine_C_v1_BufferContainer_add(fluxEngine_C_v1_BufferContainer *buffer_container, fluxEngine_C_v1_BufferInfo const *buffer_info, fluxEngine_C_v1_Error **error)

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 following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_BufferAlreadyReturned
fluxEngine_C_v1_ErrorCode_BufferContainerFull
fluxEngine_C_v1_ErrorCode_BufferStructureMismatch

Parameters:

buffer_container – The buffer container
buffer_info – The device buffer to add
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

BufferContainer_add_persistent

int fluxEngine_C_v1_BufferContainer_add_persistent(fluxEngine_C_v1_BufferContainer *buffer_container, fluxEngine_C_v1_PersistentBufferInfo const *persistent_buffer_info, fluxEngine_C_v1_Error **error)

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 following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_BufferContainerFull
fluxEngine_C_v1_ErrorCode_BufferStructureMismatch

Parameters:

buffer_container – The buffer container
persistent_buffer_info – The persistent buffer to add
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

BufferContainer_add_raw

int fluxEngine_C_v1_BufferContainer_add_raw(fluxEngine_C_v1_BufferContainer *buffer_container, void const *data, fluxEngine_C_v1_BufferScalarType scalar_type, int order, int64_t dimensions[5], int64_t strides[5], fluxEngine_C_v1_Error **error)

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 following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_BufferContainerFull
fluxEngine_C_v1_ErrorCode_BufferStructureMismatch

Parameters:

buffer_container – The buffer container
data – A pointer to the data to add
scalar_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.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

BufferContainer_get_structure

int fluxEngine_C_v1_BufferContainer_get_structure(fluxEngine_C_v1_BufferContainer *buffer_container, fluxEngine_C_v1_BufferScalarType *scalar_type, int *order, int64_t dimensions[5], size_t *bytes_per_buffer, size_t *bytes_total, fluxEngine_C_v1_Error **error)

Get the structure of the buffer container.

The buffer container will have the one dimension more than the buffers it stores: its first dimension will denote the different buffers.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument

Parameters:

buffer_container – The buffer container
scalar_type – [out] The scalar type of the data in the buffer container
order – [out] The tensor order of the buffer container, which will be one larger than the tensor order of an individual buffer
dimensions – [out] The dimensions of the buffer container
bytes_per_buffer – [out] 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
bytes_total – [out] 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 be set to zero
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

BufferContainer_copy_data

int fluxEngine_C_v1_BufferContainer_copy_data(fluxEngine_C_v1_BufferContainer *buffer_container, void *data, size_t data_size, fluxEngine_C_v1_Error **error)

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.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_BufferTargetMemoryTooSmallError

Parameters:

buffer_container – The buffer container to copy
data – [out] The memory region to copy the data into
data_size – The size of the memory region (in bytes). This must be provided so that this function can check the region is large enough to hold the data
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

BufferContainer_copy_single_data

int fluxEngine_C_v1_BufferContainer_copy_single_data(fluxEngine_C_v1_BufferContainer *buffer_container, uint64_t buffer_id, void *data, size_t data_size, fluxEngine_C_v1_Error **error)

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.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_IndexOutOfRange
fluxEngine_C_v1_ErrorCode_BufferTargetMemoryTooSmallError
fluxEngine_C_v1_ErrorCode_BufferContainerPastRingBufferSize

Parameters:

buffer_container – The buffer container to copy out of
buffer_id – The id of the buffer to copy
data – [out] The memory region to copy the data into
data_size – The size of the memory region (in bytes). This must be provided so that this function can check the region is large enough to hold the data
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

BufferContainer_copy_buffer

int fluxEngine_C_v1_BufferContainer_copy_buffer(fluxEngine_C_v1_BufferContainer *buffer_container, uint64_t buffer_id, int64_t override_buffer_number, fluxEngine_C_v1_PersistentBufferInfo **result, fluxEngine_C_v1_Error **error)

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.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_IndexOutOfRange

Parameters:

buffer_container – The buffer container to extract the data from
buffer_id – The id of the buffer to copy
override_buffer_number – If this is non-negative it will be stored as the buffer number of the persistent buffer; otherwise the value of buffer_id will be used as the buffer number
result – [out] The new persistent buffer
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

BufferContainer_copy_into_buffer

int fluxEngine_C_v1_BufferContainer_copy_into_buffer(fluxEngine_C_v1_BufferContainer *buffer_container, size_t buffer_id, int64_t override_buffer_number, fluxEngine_C_v1_PersistentBufferInfo *target, fluxEngine_C_v1_Error **error)

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.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_IndexOutOfRange
fluxEngine_C_v1_ErrorCode_BufferStructureMismatch

Parameters:

buffer_container – The buffer container to extract the data from
buffer_id – The id of the buffer to copy
override_buffer_number – If this is non-negative it will be stored as the buffer number of the persistent buffer; otherwise the value of buffer_id will be used as the buffer number
target – The persistent buffer to copy the data into
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

BufferContainer_allocate_buffer

int fluxEngine_C_v1_BufferContainer_allocate_buffer(fluxEngine_C_v1_BufferContainer *buffer_container, fluxEngine_C_v1_PersistentBufferInfo **result, fluxEngine_C_v1_Error **error)

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

The newly allocated persistent buffer will be empty.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument

Parameters:

buffer_container – The buffer container
result – [out] The new persistent buffer
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

BufferContainer_average_data_into_memory

int fluxEngine_C_v1_BufferContainer_average_data_into_memory(fluxEngine_C_v1_BufferContainer *buffer_container, fluxEngine_C_v1_Handle *handle, fluxEngine_C_v1_DataType target_data_type, void *data, int64_t const *strides, fluxEngine_C_v1_Error **error)

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.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_HandleNoLongerValid
fluxEngine_C_v1_ErrorCode_BufferTargetMemoryTooSmallError

Parameters:

buffer_container – The buffer container to average
handle – The handle. The default processing queue set of the handle will be used to perform the averaging.
target_data_type – 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 – [out] The memory region to store the result in
strides – The stride structure of the user- supplied memory area
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

BufferContainer_average_data_into_memory_pqs

int fluxEngine_C_v1_BufferContainer_average_data_into_memory_pqs(fluxEngine_C_v1_BufferContainer *buffer_container, fluxEngine_C_v1_ProcessingQueueSet *processing_queue_set, fluxEngine_C_v1_DataType target_data_type, void *data, int64_t const *strides, fluxEngine_C_v1_Error **error)

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 variant of the function allows the user to specify a processing queue set that is to be used to perform the averaging.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_HandleNoLongerValid
fluxEngine_C_v1_ErrorCode_BufferTargetMemoryTooSmallError

Parameters:

buffer_container – The buffer container to average
processing_queue_set – The processing queue set to use to perform the averaging operation
target_data_type – 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 – [out] The memory region to store the result in
strides – The stride structure of the user- supplied memory area
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

BufferContainer_average_data_into_new_buffer

int fluxEngine_C_v1_BufferContainer_average_data_into_new_buffer(fluxEngine_C_v1_BufferContainer *buffer_container, fluxEngine_C_v1_Handle *handle, fluxEngine_C_v1_DataType target_data_type, fluxEngine_C_v1_PersistentBufferInfo **buffer, fluxEngine_C_v1_Error **error)

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.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_HandleNoLongerValid
fluxEngine_C_v1_ErrorCode_BufferTargetMemoryTooSmallError

Parameters:

buffer_container – The buffer container to average
handle – The handle. The default processing queue set of the handle will be used to perform the averaging.
target_data_type – 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.
buffer – [out] The resulting persistent buffer that will contain the averaged data of the buffer container
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

BufferContainer_average_data_into_new_buffer_pqs

int fluxEngine_C_v1_BufferContainer_average_data_into_new_buffer_pqs(fluxEngine_C_v1_BufferContainer *buffer_container, fluxEngine_C_v1_ProcessingQueueSet *processing_queue_set, fluxEngine_C_v1_DataType target_data_type, fluxEngine_C_v1_PersistentBufferInfo **buffer, fluxEngine_C_v1_Error **error)

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 variant of the function allows the user to specify a processing queue set that is to be used to perform the averaging.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_HandleNoLongerValid
fluxEngine_C_v1_ErrorCode_BufferTargetMemoryTooSmallError

Parameters:

buffer_container – The buffer container to average
processing_queue_set – The processing queue set to use to perform the averaging operation
target_data_type – 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.
buffer – [out] The resulting persistent buffer that will contain the averaged data of the buffer container
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

BufferContainer_free

void fluxEngine_C_v1_BufferContainer_free(fluxEngine_C_v1_BufferContainer *buffer_container)

Free a buffer container.

The buffer container must not be used after a call to this function.

Parameters:

buffer_container – The buffer container to free