Devices

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.

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.

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.

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

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

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

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

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

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

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

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

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.

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

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

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.

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.

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

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

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

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

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

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

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

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

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

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.

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

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

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

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

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

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

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

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

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

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

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

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

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.

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

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.

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

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

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

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

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

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

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

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

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

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

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

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

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" or "DarkReference".

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

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

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

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

bool(FLUXENGINE_CB * 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

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

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

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

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.

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

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

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

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

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

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

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

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.

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

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

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

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

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

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

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

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

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.

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

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

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

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

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

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

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

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

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

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

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

int fluxEngine_C_v1_BufferContainer_copy_into_buffer(fluxEngine_C_v1_BufferContainer *buffer_container, size_t uint64_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

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