C Reference Documentation¶

Version Information¶

char const *fluxEngine_C_v1_version_string(void)¶

Get the version string for the currently loaded fluxEngine.

The string returned should not be parsed by the user, and the user should not make any assumptions based on the format of the string. It is purely for informational purposes, if the user of fluxEngine wants to show that string to the end-user, for example. If version-based checks are to be done, please use fluxEngine_C_v1_version_major() and fluxEngine_C_v1_version_minor() instead.

This function will never fail.

Return: A NUL-terminated string that contains the version of fluxEngine. The user should not free that string themselves, as it is statically allocated.

int fluxEngine_C_v1_version_major(void)¶

Get the major version of the currently loaded fluxEngine.

This function will never fail.

Return: The major version of fluxEngine

int fluxEngine_C_v1_version_minor(void)¶

Get the minor version of the currently loaded fluxEngine.

This function will never fail.

Return: The minor version of fluxEngine

Utilities¶

void fluxEngine_C_v1_string_free(char *string)¶

Free a string.

Frees the memory of a string returned by various functions of fluxEngine. This must be used to free the string, as the allocator that fluxEngine uses internally may not be the same as the allocator used by the user of fluxEngine.

This function must only be called for strings returned by functions that indicate that the string has to be freed. Some functions return C strings that have a lifetime that is coupled to a given object.

It is safe to pass a NULL pointer to this function, in which case nothing will happen.

Parameters

string: The string to free

Error Handling¶

typedef struct fluxEngine_C_v1_Error fluxEngine_C_v1_Error¶

Error information structure.

This opaque structure contains information about an error that occurred. It is allocated when an error occurs (and returned to the user) and must be freed with the fluxEngine_C_v1_Error_free() function once the user is done with it.

The structure stores at least the following information:

A text message in English that contains a description of the error that occurred (encoded in UTF-8)
An error code that gives an indication about the type of error This could be something like “file could not be opened”.
An operating system error code that gives more information about the error if the error was caused by a call to an operating system function - for example, if a file could not be opened, this will contain the operating system error code for the reason the file could not be opened

Most fluxEngine functions will have a signature that follows the following pattern:

int function_name(parameters..., fluxEngine_C_v1_Error** error);

The return value of this function will be 0 on success, or -1 on an error. In that case, if the error parameter of that function call is not NULL, a pointer to a newly allocated error structure will be stored there that the user can inspect to determine more information about the error. Hence there are two methods of calling a fluxEngine function with that type of signature:

Call it by supplying NULL to the error parameter, then the user can detect that an error occurred, but cannot detect any more information about the error:

int ret = fluxEngine_C_v1_some_function(param1, param2,
                                        NULL);
if (ret == 0) {
    // SUCCESS
} else {
    // ERROR (but no possibility to determine the type)
}

Call it by supplying a pointer to an error structure, then it is possible to determine the type of error:

fluxEngine_C_v1_Error* error = NULL;
int ret = fluxEngine_C_v1_some_function(param1, param2,
                                        &error);
if (ret == 0) {
    // SUCCESS
} else {
    // ERROR
    char* error_message = strdup(
        fluxEngine_C_v1_Error_get_message(error));
    int64_t error_code =
        fluxEngine_C_v1_Error_get_code(error);
    fluxEngine_C_v1_Error_free(error);
}

A special condition exists: if an out-of-memory condition occurs, the error structure will be NULL. This is due to the fact that if not enough memory was available to allocate something, there is likely also not enough memory available to allocate the error object. The fluxEngine_C_v1_Error_get_message(), fluxEngine_C_v1_Error_get_code() and fluxEngine_C_v1_Error_get_os_code() functions will treat a NULL pointer passed to them as an allocation error.

enum fluxEngine_C_v1_ErrorCode¶

Error code.

This enumeration describes possible error codes that give an indication what went wrong when calling specific functions.

Values:

fluxEngine_C_v1_ErrorCode_Success = 0¶

Success.

This error code will never be returned, but exists in this enumeration for the sake of completeness.

(Note that when a NULL error structure is returned when a function fails, it indicates an allocation failure, not the success of the operation.)

fluxEngine_C_v1_ErrorCode_Unknown = 1¶

Unknown error.

If an error occurred that has not yet been categorized with a specific error code, this code will be returned.

fluxEngine_C_v1_ErrorCode_AllocationFailure = 2¶

Allocation failure.

This code will never be stored in an actual error object, as allocation failures will be returned as NULL error structures. However, fluxEngine_C_v1_Error_get_code() will return this code when given a NULL pointer.

fluxEngine_C_v1_ErrorCode_InvalidArgument = 3¶

Invalid argument.

If an argument passed to a function is invalid (for example if a NULL pointer is passed where it should not have been, but also other cases), then this method will be returned.

fluxEngine_C_v1_ErrorCode_HandleNoLongerValid = 4¶

The handle is no longer valid.

If an operation is performed on a handle that has been destroyed, but where the metadata is still kept in memory because one or more models and/or processing contexts have not yet been freed, this error will be returned.

If this error occurs this indicates undefined behavior, as this essentially amounts to a use-after-free of the handle structure.

fluxEngine_C_v1_ErrorCode_ModelNoLongerValid = 5¶

The model is no longer valid.

If an operation is performed on a model whose handle has already been destroyed, this error will be returned.

In contrast to fluxEngine_C_v1_ErrorCode_HandleNoLongerValid occurring, this is only undefined behavior if the model that is being operated on has already been freed once.

fluxEngine_C_v1_ErrorCode_ProcessingContextNoLongerValid = 6¶

The processing context is no longer valid.

If an operation is performed on a model whose handle has already been destroyed, this error will be returned.

It is also possible that this error is returned if the number of processing threads of a given handle was changed after creating the processing context.

In contrast to fluxEngine_C_v1_ErrorCode_HandleNoLongerValid occurring, this is only undefined behavior if the model that is being operated on has already been freed once.

fluxEngine_C_v1_ErrorCode_IndexOutOfRange = 7¶

An index that was supplied is out of range.

When using functions that return information about an object that is indexed, such as fluxEngine_C_v1_Model_get_group_info() to obtain the information about a specific group within a model, if the index is out of range, this error code will be returned.

For example, if a model has 3 groups and the group_id parameter given to fluxEngine_C_v1_Model_get_group_info() is not 0, 1 or 2, then this error will be returned.

fluxEngine_C_v1_ErrorCode_FileAccessError = 32¶

Generic File I/O error.

If accessing a file fails, and the implementation cannot currently determine the precise type of error, this code will be returned to indciate any type of error related to accessing a given file.

fluxEngine_C_v1_ErrorCode_FileNotFoundError = 33¶

File Not Found.

This error code is returned if a file was not found when trying to access it.

Note that if the precise cause of failing to open a file could not be determined, the more generic fluxEngine_C_v1_ErrorCode_FileAccessError could also be returned.

fluxEngine_C_v1_ErrorCode_FileAccessDeniedError = 34¶

File Access Denied.

This error code is returned if a file could not be opened due to a lack of permissions for either the file itself, or a directory leading up to the file.

Note that if the precise cause of failing to open a file could not be determined, the more generic fluxEngine_C_v1_ErrorCode_FileAccessError could also be returned.

fluxEngine_C_v1_ErrorCode_FileTypeError = 35¶

File Type Error.

This error code is returned if the specified file is not actually a file, but for example a directory (or some other filesystem object that is not considered a file).

Note that if the precise cause of failing to open a file could not be determined, the more generic fluxEngine_C_v1_ErrorCode_FileAccessError could also be returned.

fluxEngine_C_v1_ErrorCode_FileInUseError = 36¶

File Is In Use.

This error code is returned if a file could not be opened because it is in use by another program.

Note that if the precise cause of failing to open a file could not be determined, the more generic fluxEngine_C_v1_ErrorCode_FileAccessError could also be returned.

fluxEngine_C_v1_ErrorCode_ReadOnlyFilesystem = 37¶

Read-Only Filesystem.

This error code is reserved for future use.

(Currently there are no functions in fluxEngine that write files.)

fluxEngine_C_v1_ErrorCode_IOError = 38¶

I/O Error.

This error code is returned if a file could not be opened or an I/O operation could not be perfomed due to an I/O error. This could be due to a hardware device malfunctioning, or a network drive suddenly becoming inaccessible.

Note that if the precise cause of failing to open a file could not be determined, the more generic fluxEngine_C_v1_ErrorCode_FileAccessError could also be returned.

fluxEngine_C_v1_ErrorCode_HandleAlreadyCreated = 512¶

A handle has already been created.

Current limitations of the fluxEngine library allow only for the creation of a single handle. If the user attempts to create a second handle, this error code will be returned.

fluxEngine_C_v1_ErrorCode_InvalidLicense = 513¶

Invalid license.

The supplied license is invalid, and could either not be parsed, or the parsed data did not make any sense. This is typically the case if something other than the correct license file is passed to fluxEngine_C_v1_init().

fluxEngine_C_v1_ErrorCode_LicenseWrongProduct = 514¶

License is for wrong product.

The supplied license is for the wrong product (for example, fluxTrainer), but not for fluxEngine.

fluxEngine_C_v1_ErrorCode_LicenseExpired = 515¶

License has expired.

If the license was issued only up to a certain date, and that date has passed, the license is expired and this error will be returned.

fluxEngine_C_v1_ErrorCode_LicenseUpdateExpired = 516¶

License is for previous versions of the software.

The supplied license is only valid for versions of fluxEngine that were built before a specific date, and the current version of fluxEngine has passed that date.

fluxEngine_C_v1_ErrorCode_LicenseIdentifierMismatch = 517¶

License identifier mismatch.

The supplied license does not match the current system. For example, when a license issued to the mainboard serial number of a given system is run on a system with a different mainboard serial number, this error will be returned.

fluxEngine_C_v1_ErrorCode_LicenseDongleRemoved = 518¶

The license dongle has been removed.

The license was tied to a dongle and that dongle has since been removed from the computer.

fluxEngine_C_v1_ErrorCode_ThreadCreationError = 528¶

Unable to create a background processing thread.

A background processing thread could not be created by fluxEngine, possibly due to resource exhaustion or an operating system limit.

fluxEngine_C_v1_ErrorCode_ThreadInitFunctionError = 529¶

The user-supplied thread initialization function returned a non-zero return code.

The user-supplied thread initialization function returned a non-zero return code, causing the thread creation to be aborted. It is up to the user to store further information about the failure to perform the per-thread initialization in the user-defined context.

fluxEngine_C_v1_ErrorCode_InvalidModelData = 1024¶

Invalid Model Data.

When loading a model (either from memory or from a file) this error code is returned if the model could not be loaded, for example because the data of the model was corrupt, or the file that was passed was not a LuxFlux Runtime Model (.fluxmdl).

fluxEngine_C_v1_ErrorCode_ModelContainsUnsupportedFilter = 1025¶

Model Contains Unsupported Filter.

The supplied model contains a filter that is not supported by the current version of fluxEngine. It was likely created with a newer version of fluxTrainer.

fluxEngine_C_v1_ErrorCode_ModelContainsUnlicensedFilter = 1026¶

Model Contains Unlicensed Filter.

The supplied model contains a filter that is not allowed by the currently loaded license, and can hence not be loaded.

fluxEngine_C_v1_ErrorCode_ModelNotConsistent = 1027¶

The supplied model is not consistent.

The model that was loaded is not in a consistent state. This indicates a problem during the export of the model.

fluxEngine_C_v1_ErrorCode_ModelSourceTypeUnsupported = 1028¶

The supplied model is for unsupported data.

The model that was loaded is for processing data of a type that is currently not supported by fluxEngine. Currently only hyperspectral data (Cubes or PushBroom frames) are supported.

fluxEngine_C_v1_ErrorCode_ModelWrongSourceType = 1536¶

The loaded model is not a HSI model.

When creating a processing context for HSI data, if the loaded model is not a HSI model, this error code will be returned.

At the moment, this will never happen, as only HSI models can be loaded. Future versions might return this error code though.

fluxEngine_C_v1_ErrorCode_FilterCreationError = 1537¶

Could not create required filter.

When creating a processing context, several filters are automatically created and added to the model to ensure that they can properly transform the input data to the format the model expects. This error is returned if one of these filters could not be created for any reason.

fluxEngine_C_v1_ErrorCode_WavelengthRangeDeterminationError = 1538¶

Could not determine wavelength range of model.

The wavelength setting of the source node in a given model could not be read during the creation of a processing context.

fluxEngine_C_v1_ErrorCode_InputDimensionError = 1539¶

The supplied dimensions of the input do not make sense.

The dimensions of the input supplied while either creating a processing context or providing the next input data pointer do not make sense, for example because a negative number was provided.

fluxEngine_C_v1_ErrorCode_InputStrideError = 1540¶

The supplied stride of the input does not fit.

The stride of the input supplied while providing the next input data pointer does not fit the dimension structure of the input data.

For example, if an entire cube is being processed, and the dimension structure of the cube is (500, 300, 200), then a stride structure of (60000, 200, 1) would be acceptable, but a stride structure of (50000, 200, 1) would not be, as the first stride is smaller than the second stride times the second dimension.

fluxEngine_C_v1_ErrorCode_WhiteReferenceMissingError = 1541¶

No white reference provided.

When creating a processing context for a model that is given in reflectances or absorbances, but the data provided by the user will be in raw intensities, a white reference must exist for fluxEngine to be able to automatically reference the input data. If no white reference is provided during processing context creation in that circumstance, this error will be returned.

Note: this error will not occur if the data provided by the user is already reflectance data or the model is set to process raw intensities and the user provides intensity data.

fluxEngine_C_v1_ErrorCode_WhiteReferenceDimensionError = 1542¶

The provided dimensions of the white reference are not acceptable.

When providing a white reference while setting up a processing context, the dimension of the provided reference must be supplied. If those dimensions are not congruent to the input dimensions, this error code will be returned.

Please note that references always have an additional dimension that allows fluxEngine to average over multiple reference measurements, so the reference for processing entire HSI cubes will be a tensor of order 4, for example.

fluxEngine_C_v1_ErrorCode_DarkReferenceDimensionError = 1544¶

The provided dimensions of the dark reference are not acceptable.

When providing a dark reference while setting up a processing context, the dimension of the provided reference must be supplied. If those dimensions are not congruent to the input dimensions, this error code will be returned.

Please note that references always have an additional dimension that allows fluxEngine to average over multiple reference measurements, so the reference for processing entire HSI cubes will be a tensor of order 4, for example.

fluxEngine_C_v1_ErrorCode_PreprocessingSetupError = 1545¶

An error occurred while setting up preprocessing.

While performing the final actions required to initialize the preprocessing steps for the input data, an error occurred.

fluxEngine_C_v1_ErrorCode_ProcessingSetupError = 1546¶

An error occurred while setting up processing.

While performing the final actions required to initialize the processing sequence, an error occurred.

fluxEngine_C_v1_ErrorCode_InputWavelengthValueError = 1547¶

Input wavelength value error.

One of the wavelengths supplied as the input data did not have a finite value. This happens if the list of input wavelengths contain NaN or infinities.

fluxEngine_C_v1_ErrorCode_OutputIdNotPresent = 1600¶

No output sink with the given output id is present.

This error will be returned by fluxengine_C_v1_ProcessingContext_find_output_sink() if there is no output sink in the loaded model with the requested output id.

fluxEngine_C_v1_ErrorCode_OutputIdNotUnique = 1601¶

Multiple outuput sinks with the given output id are present.

This error will be returned by fluxengine_C_v1_ProcessingContext_find_output_sink() if there is more than one output sink in the loaded model with the requested output id.

fluxEngine_C_v1_ErrorCode_StorageTypeMismatch = 1602¶

Storage type mismatch while introspecting an output sink.

When using either fluxEngine_C_v1_ProcessingContext_get_output_sink_tensor_structure() or fluxEngine_C_v1_ProcessingContext_get_output_sink_object_list_structure() to obtain more detailed information about an output sink, if the output sink has a different storage type, this error will be returned.

For example, calling fluxEngine_C_v1_ProcessingContext_get_output_sink_tensor_structure() for an output sink that will return a list of detected objects would result in this error.

fluxEngine_C_v1_ErrorCode_ProcessingContextTypeMismatch = 1632¶

The processing context is of the wrong type.

When setting the next input pointer by either fluxEngine_C_v1_ProcessingContext_set_source_data_hsi_cube() or fluxEngine_C_v1_ProcessingContext_set_source_data_pushbroom_frame() or their corresponding extended variants, if the context was created for a different type of data, this error will be returned.

For example, calling fluxEngine_C_v1_ProcessingContext_set_source_data_hsi_cube() on a context that was created to process PushBroom frames will result in this error.

fluxEngine_C_v1_ErrorCode_ProcessingUnknownError = 1664¶

An unknown error occurred during processing.

This happens when the actual processing step during a call to fluxEngine_C_v1_ProcessingContext_process_next() fails in an unknown manner.

fluxEngine_C_v1_ErrorCode_ProcessingInternalError = 1665¶

An internal error occurred during processing.

An internal error occurred during data processing.

fluxEngine_C_v1_ErrorCode_ProcessingAborted = 1666¶: Processing was aborted by the user.

fluxEngine_C_v1_ErrorCode_ProcessingSourceDataMissing = 1667¶

The source data for processing was not set by the user.

If the user has never called any of the fluxEngine_C_v1_ProcessingContext_set_source_data_hsi_cube() or fluxEngine_C_v1_ProcessingContext_set_source_data_pushbroom_frame() functions or their extended variants before a call to fluxEngine_C_v1_ProcessingContext_process_next() this error will occur.

This also occurs if the user has not set the source data again after a call to fluxEngine_C_v1_ProcessingContext_reset_state().

fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid = 2048¶

The parameter info is no longer valid.

If a given parameter info was obtained from a connected device the parameter information will only remain valid as long as the device is connected. If the device has since disconnected the parameter information will become invalid.

If that is the case this error will be returned by methods that return information about a parameter info.

fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange = 2049¶

The parameter index is out of range.

If information about a parameter is queried by index and the given parameter index is out of range, this error will occur.

Note that a negativ index will result in a fluxEngine_C_v1_ErrorCode_InvalidArgument instead of this error, as a negativ index is never valid.

fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist = 2050¶

A parameter with that name does not exist.

If information about a parameter is queried by name and that name does not describe a valid parameter, this error will occur.

Note that a null pointer supplied for the name will result in a fluxEngine_C_v1_ErrorCode_InvalidArgument instead of this error, as that can never be valid.

fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError = 2051¶

An internal error occurred while querying a parameter.

This indicates an internal error (and likely a bug) when querying information about a parameter.

fluxEngine_C_v1_ErrorCode_ParameterWrongType = 2052¶

When querying a parameter the wrong type was encountered.

When querying information about a parameter that requires the parameter to be of a specific type, and the parameter in question is of a different type, this error occurs.

fluxEngine_C_v1_ErrorCode_ParameterEnumerationIndexOutOfRange = 2053¶

The enumeration entry index is out of range.

If information about an enumeration entry is queried by index and the given enumeration entry index is out of range, this error will occur.

Note that a negativ index will result in a fluxEngine_C_v1_ErrorCode_InvalidArgument instead of this error, as a negativ index is never valid.

fluxEngine_C_v1_ErrorCode_ParameterEnumerationNameDoesNotExist = 2054¶

An enumeration entry with that name does not exist.

If information about an enumeration entry is queried by name and that name does not describe a valid enumeration entry, this error will occur.

Note that a null pointer supplied for the name will result in a fluxEngine_C_v1_ErrorCode_InvalidArgument instead of this error, as that can never be valid.

fluxEngine_C_v1_ErrorCode_ParameterAffectedIndexOutOfRange = 2055¶

The affected parameter index is out of range.

If information about an affected parameter is queried by index and the given affected parameter index is out of range, this error will occur.

Note that a negativ index will result in a fluxEngine_C_v1_ErrorCode_InvalidArgument instead of this error, as a negativ index is never valid.

fluxEngine_C_v1_ErrorCode_ParameterNoDefaults = 2057¶

No defaults are available for the given parameter info.

Parameter infos of connected devices do not contain information about default values. When querying default values of these parameter infos this error will occur.

fluxEngine_C_v1_ErrorCode_ParameterQueryError = 2058¶

Error querying parameter information.

An error occurred while querying parameter information. For example, when attempting to query the minimum value of a parameter that is currently not accessible, this error might occur.

fluxEngine_C_v1_ErrorCode_DeviceEnumerationInvalidIndex = 2560¶

An invalid index was supplied while querying an enumeration result.

While retrieving an enumeration result object (driver, device, warning, error) by its index, an invalid index was supplied by the user.

For example, if there were 2 devices found, but the user wants to query the device with index 15, this erorr will occur.

typedef int fluxEngine_C_v1_OsErrorCode¶

Operating system error code.

This typedef aliases the operating system’s type to report errors. On Windows systems this is DWORD, as that is returned by GetLastError(), on all other systems it is int, as that is the type of the errno variable.

char const *fluxEngine_C_v1_Error_get_message(fluxEngine_C_v1_Error *error)¶

Get a human-readable message associated with an error.

Returns a human-readable message associated with the given error. The human-readable message will be in English, encoded in UTF-8, and may be subject to change between versions. It must therefore not be parsed by the user, and only used for informational purposes - display the message for the user, log the message, or similar.

The pointer returned by this function must not be freed by the user directly. It is valid until the error object is freed, after that the user must not use it anymore. If the message is needed for a longer period of time, the string must be copied.

If a NULL pointer is passed to this function, it is assumed that an allocation error occurred, in which case this method will return the fixed string "Allocation failure".

Return

The message associated with the error object

Parameters

error: The error object to obtain the message from

int64_t fluxEngine_C_v1_Error_get_code(fluxEngine_C_v1_Error *error)¶

Get the code associated with an error.

Returns a generic code associated with an error. This code will be one of the values defined in fluxEngine_C_v1_ErrorCode.

If a NULL pointer is passed to this function, it is assumed that an allocation error occurred, in which case this method will return the fixed value fluxEngine_C_v1_ErrorCode_AllocationFailure.

Return

The error code stored in the object

Parameters

error: The error object to obtain the code from

fluxEngine_C_v1_OsErrorCode fluxEngine_C_v1_Error_get_os_code(fluxEngine_C_v1_Error *error)¶

Get the operating system code associated with an error.

If an error was caused by an operating system function, for example, while opening a file, this will contain the operating system error code underlying to the error.

On Windows systems this will correspond to the result of GetLastError() called immediately after the call to the operating system function that resulted in the error.

On other operating systems this will correspond to the value of the global errno variable read immediately after the call to the operating system function that resulted in the error.

Note that due to the usage of third-party libraries it is not always possible for fluxEngine to determine the underlying operating system error code of a failed operation, even if an operating system function is responsible for the error. In that case this may still be 0.

If a NULL pointer is passed to this function, it is assumed that an allocation error occurred, in which case this method will return ERROR_OUTOFMEMORY on Windows systems and ENOMEM on all other systems.

Return

The error code stored in the object, or 0 if the error was not caused by a call to an operating system function, or if the operating system error could not be determined for some reason.

Parameters

error: The error object to obtain the code from

void fluxEngine_C_v1_Error_free(fluxEngine_C_v1_Error *error)¶

Free an error object.

Frees all of the memory associated with a given error object. Any pointer returned by fluxEngine_C_v1_Error_get_message() is invalid after a call to this method.

It is safe to pass a NULL pointer to this function, in which case nothing will happen.

Parameters

error: The error object to free

Library Setup¶

typedef struct fluxEngine_C_v1_Handle fluxEngine_C_v1_Handle¶

fluxEngine Handle

This opaque data structure contains a handle to all fluxEngine functionality. It may be obtained via fluxEngine_C_v1_init() and should be destroyed by the user via fluxEngine_C_v1_destroy().

Currently only one handle may be created at a time. (This restriction will be relaxed in a future version.)

Each handle is associated with a number of processing threads that the user can manage. A handle may only be used to process a single model at the same time, though multiple models may be loaded for a given handle.

int fluxEngine_C_v1_init(void const *license_data, size_t license_data_size, fluxEngine_C_v1_Handle **handle, fluxEngine_C_v1_Error **error)¶

Initialize a fluxEngine handle.

Initializes fluxEngine. Valid license data must be passed to this function, otherwise fluxEngine will not initialize itself. It is up to the user to read the license data from the given license file, if they choose to store it in a file.

If the call is successful, a pointer to the newly created handle will be stored in handle. The following is the typical usage pattern of this method:

fluxEngine_C_v1_Error* error = NULL;
fluxEngine_C_v1_Handle* handle = NULL;
int ret = fluxEngine_C_v1_init(license_data, license_data_size,
                               &handle, &error);
if (ret != 0) {
    // perform error handling
    // ...
    // cleanup error structure
    fluxEngine_C_v1_Error_free(error);
    // don't proceed
    return;
}
// handle is now valid
// at the end, when the handle is no longer needed
fluxEngine_C_v1_destroy(handle);

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_HandleAlreadyCreated
fluxEngine_C_v1_ErrorCode_LicenseExpired
fluxEngine_C_v1_ErrorCode_LicenseWrongProduct
fluxEngine_C_v1_ErrorCode_LicenseUpdateExpired
fluxEngine_C_v1_ErrorCode_LicenseIdentifierMismatch
fluxEngine_C_v1_ErrorCode_InvalidLicense

Return

0 on success, -1 on failure

Parameters

license_data: The raw bytes of the license
license_data_size: The number of raw bytes of the license
handle: A pointer to the resulting handle, on success
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_create_processing_threads(fluxEngine_C_v1_Handle *handle, int thread_count, fluxEngine_C_v1_Error **error)¶

Create processing threads.

fluxEngine may use parallization to speed up processing. In order to achieve this background threads must be created to run on additional CPU cores.

Calling this function is optional: by default processing will be single-threaded.

This function will start thread_count - 1 threads when called, as the thread that asks for processing is always considered to be the first thread (with id 0). For example, if 4 is supplied to thread_count this function will start 3 threads that run in the background. The thread that the user uses to call fluxEngine_C_v1_ProcessingContext_process_next() will be considered the thread with id 0, making processing use a total of 4 threads, which is the value supplied for thread_count.

This function may only be called if there are currently no background threads associated with this handle. Otherwise fluxEngine_C_v1_stop_processing_threads() must be called first to change the number of threads.

Any processing context that was created before a call to this function was made is marked as invalid and can only be destroyed, but not used anymore.

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_ThreadCreationError

Return

0 on success, -1 on failure

Parameters

handle: The handle to create the threads for
thread_count: The number of threads to use for parallel processing (one less than this number will be created by this function, see the description for details)
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

typedef int (*fluxEngine_C_v1_ThreadInitFunction)(void *context, int thread_id, int thread_count)¶

Thread initialization function.

This callback may be passed to fluxEngine_C_v1_create_processing_threads_ex(). It will be called at the beginning of the newly created threads and allows the user to change properties of those threads before processing starts.

For example, this may be used to update the thread’s priority or to update its CPU pinning.

This function must not block for a long period of time, as fluxEngine_C_v1_create_processing_threads_ex() will wait on the completion of this function before it returns.

Important: any call to any fluxEngine function that accesses the handle in question during this callback will result in a deadlock.

This callback must not throw any C++ exception, or use longjmp() from within; that behavior is undefined.

Return

This callback should return 0 on success. Any other value will indicate a failure and cause the thread creation function to tear down the threads again and fail with an error itself.

Parameters

context: The context supplied as the init_function_context parameter. This may be used by the user to pass data into the callback.
thread_id: The id of the thread this is called for. 1 indicates the second thread, 2 the third, etc. Note that this function will never be called for the first thread, see the thread creation functions for details.
thread_count: The total number of threads being created.

int fluxEngine_C_v1_create_processing_threads_ex(fluxEngine_C_v1_Handle *handle, int thread_count, fluxEngine_C_v1_ThreadInitFunction init_function, void *init_function_context, fluxEngine_C_v1_Error **error)¶

Create processing threads (extended version)

Please read the documentation of fluxEngine_C_v1_create_processing_threads() for general details.

This extended function allows the user to supply a thread initialization function that will be called at the beginning of the newly created background threads. This allows the user to customize the thread properties (such as the thread priority or the CPU affinity) themselves.

This function will only return once all thread initialization functions have run.

The thread initialization functions are only called for the backgronud threads that are started by this function; this means that for a thread_count of 4 the initialization function will be called in 3 background threads, and it is up to the user to alter the thread in which they call fluxEngine_C_v1_ProcessingContext_process_next() to process data with fluxEngine.

The threads will be created sequentially, the next thread being created only after the previous thread’s initialization function has completed. This allows the user to directly modify global data structures in the initialization functions without the need for locking.

Important: any attempt to call function that accesses this handle inside the initialization functions will create a deadlock.

This function may only be called if there are currently no background threads associated with this handle. Otherwise fluxEngine_C_v1_stop_processing_threads() must be called first to change the number of threads.

Any processing context that was created before a call to this function was made is marked as invalid and can only be destroyed, but not used anymore.

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_ThreadCreationError
fluxEngine_C_v1_ErrorCode_ThreadInitFunctionError

See

fluxEngine_C_v1_create_processing_threads()

Return

0 on success, -1 on failure

Parameters

handle: The handle to create the threads for
thread_count: The number of threads to use for parallel processing (one less than this number will be created by this function, see the description for details)
init_function: The initialization function to call at the start of each newly created background thread
init_function_context: An arbitrary context that will be passed to the initialization function
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

void fluxEngine_C_v1_stop_processing_threads(fluxEngine_C_v1_Handle *handle)¶

Stop background threads of a handle.

This will stop any background threads that are currently associated with a given handle. If processing is currently active on the handle, it will be aborted, as if fluxEngine_C_v1_ProcessingContext_abort() had been called. In that case this method may take a bit of time, as abort operations are not immediate, and this method will wait until the abort has completed.

Any processing context that was created before a call to this function was made is marked as invalid and can only be destroyed, but not used anymore.

This method is always successful: the only errors that could occur when calling this method would be non-recoverable.

If NULL is passed to this method, it will do nothing.

Parameters

handle: The handle to stop the threads for

void fluxEngine_C_v1_destroy(fluxEngine_C_v1_Handle *handle)¶

Destroy a handle.

Destroy a library handle, freeing its resources. All background threads will be stopped in the same manner as if fluxEngine_C_v1_stop_processing_threads() had been called.

Any processing context associated with this handle will be marked as invalid and may hence not be used anymore. However, some memory associated with remaining processing contexts that have not been freed previous to a call to this method may still be in use until each remaining processing context is freed by the user.

If NULL is passed to this method, it will do nothing.

Parameters

handle: The handle to destroy

Models¶

typedef struct fluxEngine_C_v1_Model fluxEngine_C_v1_Model¶

Model.

This opaque data structure wraps a runtime model that has been loaded into fluxEngine.

int fluxEngine_C_v1_Model_load_memory(fluxEngine_C_v1_Handle *handle, void const *model_data, size_t model_size, fluxEngine_C_v1_Model **model, fluxEngine_C_v1_Error **error)¶

Load a model from data in memory.

This function allows the user to supply fluxEngine with a serialized runtime model that the user has already loaded into memory.

If the user destroys the library handle while this object still exists, this object will be marked as invalid. It must still be destroyed to avoid resource leaks.

A model object created by this function must be destroyed again using fluxEngine_C_v1_Model_destroy().

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_InvalidModelData
fluxEngine_C_v1_ErrorCode_ModelContainsUnsupportedFilter
fluxEngine_C_v1_ErrorCode_ModelContainsUnlicensedFilter
fluxEngine_C_v1_ErrorCode_ModelNotConsistent
fluxEngine_C_v1_ErrorCode_ModelSourceTypeUnsupported

Return

0 on success, -1 on failure

Parameters

handle: The fluxEngine handle for which to create the processing context
model_data: The raw binary data of the model
model_size: The number of bytes of the model
model: The resulting model
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_Model_load_file(fluxEngine_C_v1_Handle *handle, char const *model_file_name, fluxEngine_C_v1_Model **model, fluxEngine_C_v1_Error **error)¶

Load a model from disk.

This function allows the user to load a runtime model from a file.

If the user destroys the library handle while this object still exists, this object will be marked as invalid. It must still be destroyed to avoid resource leaks.

A model object created by this function must be destroyed again using fluxEngine_C_v1_Model_destroy().

Note to Windows users: the file path specified here must be encoded in the local codepage, which is not able to encode all possible file names that Windows supports. It is highly recommended to use the fluxEngine_C_v1_load_model_file_w() function on Windows, which accepts a wide (“Unicode”) file name and does support all possible file names that Windows supports. If this 8bit version is used on Windows with an encoding different from the local codepage, this method will very likely fail.

Note to non-Windows users: the encoding of the file name is highly dependent on the environment, and may or may not be UTF-8. It is up to the user to specify the file correctly; fluxEngine will pass it directly to the corresponding operating system 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_HandleNoLongerValid
fluxEngine_C_v1_ErrorCode_FileAccessError
fluxEngine_C_v1_ErrorCode_FileNotFoundError
fluxEngine_C_v1_ErrorCode_FileAccessDeniedError
fluxEngine_C_v1_ErrorCode_FileTypeError
fluxEngine_C_v1_ErrorCode_FileInUseError
fluxEngine_C_v1_ErrorCode_IOError
fluxEngine_C_v1_ErrorCode_InvalidModelData
fluxEngine_C_v1_ErrorCode_ModelContainsUnsupportedFilter
fluxEngine_C_v1_ErrorCode_ModelContainsUnlicensedFilter
fluxEngine_C_v1_ErrorCode_ModelNotConsistent
fluxEngine_C_v1_ErrorCode_ModelSourceTypeUnsupported

Return

0 on success, -1 on failure

Parameters

handle: The fluxEngine handle for which to create the model
model_file_name: The name of the model to load
model: The resulting model
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_Model_load_file_w(fluxEngine_C_v1_Handle *handle, wchar_t const *model_file_name, fluxEngine_C_v1_Model **model, fluxEngine_C_v1_Error **error)¶

Load a model from disk (Windows wide “Unicode” variant)

This function is identical to fluxEngine_C_v1_load_model_file(), other than it takes a wide (“Unicode”) filename on Windows systems, to support opening files that can’t be encoded in the local codepage.

Note

This function is only available on Windows and does not exist on other operating systems.

Please refer to the documentation of fluxEngine_C_v1_Model_load_file() for details on the behavior of this function beyond the encoding of the filename.

Return

0 on success, -1 on failure

Parameters

handle: The fluxEngine handle for which to create the model
model_file_name: The name of the model to load
model: The resulting model
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_Model_num_groups(fluxEngine_C_v1_Model *model, fluxEngine_C_v1_Error **error)¶

Get the number of groups in a model.

Returns the number of groups that were defined in a given model.

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_ModelNoLongerValid

Return

The number of groups on success, -1 on failure

Parameters

model: The model to introspect
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_Model_get_group_info(fluxEngine_C_v1_Model *model, int group_id, char **name, uint32_t *color, fluxEngine_C_v1_Error **error)¶

Get information about a group in a model.

Returns information about a group in a model. This consists of the name of the group (encoded as UTF-8) as well as a color value as a 32bit integer in the following encoding: 0xffRRGGBB. To obtain the red, green and blue values of the color the following formulas may be used:

uint8_t red_value   = (uint8_t) ((color >> 16u) & 0xffu);
uint8_t green_value = (uint8_t) ((color >>  8u) & 0xffu);
uint8_t blue_value  = (uint8_t) ((color >>  0u) & 0xffu);

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_ModelNoLongerValid
fluxEngine_C_v1_ErrorCode_IndexOutOfRange

Return

0 on success, -1 on failure

Parameters

model: The model to introspect
group_id: The group to obtain the information for
name: The name of the group will be stored here. The user must free the returned string using fluxEngine_C_v1_string_free().
color: The selected color of the group will be stored here.
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

void fluxEngine_C_v1_Model_destroy(fluxEngine_C_v1_Model *model)¶

Destroy a model.

Destroy a model, freeing its resources.

If NULL is passed to this method, it will do nothing.

Parameters

model: The model to destroy

Data Processing¶

typedef struct fluxEngine_C_v1_ProcessingContext fluxEngine_C_v1_ProcessingContext¶

Processing Context.

This opaque data structure describes a processing context.

enum fluxEngine_C_v1_DataType¶

A scalar data type.

This enumeration lists the supported scalar data types that may be used as input for HSI data, as well as the data types of the data that may be returned.

Values:

fluxEngine_C_v1_DataType_UInt8 = 0¶: 8bit Unsigned Integer

fluxEngine_C_v1_DataType_UInt16 = 1¶: 16bit Unsigned Integer

fluxEngine_C_v1_DataType_UInt32 = 2¶: 32bit Unsigned Integer

fluxEngine_C_v1_DataType_UInt64 = 3¶: 64bit Unsigned Integer

fluxEngine_C_v1_DataType_Int8 = 4¶: 8bit Signed Integer

fluxEngine_C_v1_DataType_Int16 = 5¶: 16bit Signed Integer

fluxEngine_C_v1_DataType_Int32 = 6¶: 32bit Signed Integer

fluxEngine_C_v1_DataType_Int64 = 7¶: 64bit Signed Integer

fluxEngine_C_v1_DataType_Float32 = 8¶: 32bit Single Precision IEEE 754 Floating Point

fluxEngine_C_v1_DataType_Float64 = 9¶: 64bit Double Precision IEEE 754 Floating Point

enum fluxEngine_C_v1_ValueType¶

The value type of a given input.

Determines what form the data that is supplied by the user has.

Values:

fluxEngine_C_v1_ValueType_Intensity = 0¶

Intensities.

The data supplied by the user are raw intensities. If the model is set to process reflectances and/or absorbances reference data must be provided before processing can occur.

fluxEngine_C_v1_ValueType_Reflectance = 1¶

Reflectances.

The data supplied by the user are reflectances.

struct fluxEngine_C_v1_ReferenceInfo¶

Information about references.

This information structure must be supplied when creating a processing context. It specifies the input value type of the processing context, as well as any references.

There are three primary ways to handle referencing of data:

The source in the model is set to raw intensities, and raw intensities are supplied by the user for the input data of the model while processing. In that case any references provided will be ignored
The source in the model is set to reflectances or absorbances, and the user provides reflectances for the input data of the model while processing. In that case any references provided will be ignored
The source in the model is set to reflectances or absorbances, and the user provides raw intensities for the input data of the model while processing. In that case a white reference must be provided to automatically reference the input data, and optionally a dark reference may be provided.

When referencing input data, if only a white reference is provided, reflectances are calculated with the following formula:

reflectance = intensity / white

If a dark reference is also present, reflectances are calculated with the following formula:

reflectance = (intensity - dark) / (white - dark)

Public Members

fluxEngine_C_v1_ValueType value_type¶: The value type of the input data.

void const *white_reference¶

The white reference data.

This must be a tensor that is contiguous in memory that contains the white reference that will be used in conjunction with the input data.

Since it is advantageous to average multiple reference measurements, this tensor has to have an additional dimension to denote a list of input frames.

For HSI cubes in BIP order, this means the dimensionality of this tensor has to be (N, height, width, bands).
For HSI cubes in BIL order the dimensionality of the tensor has to be (N, height, bands, width)
For HSI cubes in BSQ order the dimensionality of the tensor has to be (N, bands, height, width)
For PushBoom frames in LambdaX order the dimensionality of the tensor has to be (N, width, bands)
For PushBroom frames in LambdaY order the dimensionality of the tensor has to be (N, bands, width)

The number of averages, N, may be 1, indicating that no average is to be calculated.

int64_t white_reference_dimensions[5]¶

The dimensions of the white reference.

Not all elements may be used, depending on the order of the tensor that is required.

void const *dark_reference¶: The dark reference data.

int64_t dark_reference_dimensions[5]¶: The dimensions of the dark reference.

enum fluxEngine_C_v1_HSICube_StorageOrder¶

Hyperspectral data cube storage order.

Hyperspectral cubes consist of three dimensions, and the storage order defines how these dimensions are mapped into linear memory.

The introductory documentation also contains a visual depiction of the various storage orders of HSI cubes.

Values:

fluxEngine_C_v1_HSICube_StorageOrder_BIP = 0¶

Band Interleaved by Pixel Storage Order.

In this storage order all wavelengths of each pixel are next to each other in memory. This means that the linear memory address of an element may be caluclated by the following formula (assuming the cube is contiguous in memory, see fluxEngine_ProcessingContext_set_source_data_hsi_cube_ex() for more complicated cases):

(y * width + x) * band_count + band_index

A cube stored in this storage order can be considered a row-major tensor of order 3 indexed as (y, x, band).

fluxEngine_C_v1_HSICube_StorageOrder_BIL = 1¶

Band Interleaved by Line Storage Order.

In this storage order all pixels of a line are next to each other in memory, and wavelengths are grouped by line. This means that the linear memory address of an element may be by the following formula (assuming the cube is contiguous in memory, see fluxEngine_ProcessingContext_set_source_data_hsi_cube_ex() for more complicated cases):

(y * band_count + band_index) * width + x

A cube stored in this storage order can be considered a row-major tensor of order 3 indexed as (y, band, x).

fluxEngine_C_v1_HSICube_StorageOrder_BSQ = 2¶

Band Sequential Storage Order.

In this storage order all pixels of an individual band are next to each other in memory, and wavelengths are grouped by image. This means that the linear memory address of an element may be by the following formula (assuming the cube is contiguous in memory, see fluxEngine_ProcessingContext_set_source_data_hsi_cube_ex() for more complicated cases):

(band_index * height + y) * width + x

A cube stored in this storage order can be considered a row-major tensor of order 3 indexed as (band, y, x).

int fluxEngine_C_v1_ProcessingContext_create_hsi_cube(fluxEngine_C_v1_Model *model, fluxEngine_C_v1_HSICube_StorageOrder storage_order, fluxEngine_C_v1_DataType data_type, int64_t max_height, int64_t height, int64_t max_width, int64_t width, double const *wavelengths, size_t wavelength_count, fluxEngine_C_v1_ReferenceInfo const *reference_info, fluxEngine_C_v1_ProcessingContext **context, fluxEngine_C_v1_Error **error)¶

Create a new processing context for HSI cubes.

This function creates a new processing context that may be used to process HSI data cubes. The context may be used to process multiple cubes, as long as they have the same structure.

The cube will be processed as a whole, and depending on the complexity of the model a lot of temporary storage may be required to store all the intermediate processing results.

The following information must be known in advance to properly setup a fluxEngine processing context that can be used to process this type of HSI data:

The scalar data type
The storage order of the data in memory
The wavelengths
The maximum spatial dimensions that will be processed with this context

The user may choose to process cubes of the same size, or cubes of varying sizes. In the case of cubes that all have the same size, the user should specify the same value for both max_height and height, and for max_width and width, respectively. In the case the cube sizes vary, the user should specify -1 for both height and width, and specify the size of the largest cube they will ever want to process in max_height and max_width.

Larger values for max_height and max_width will lead to more RAM being required to fully process the 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_ModelNoLongerValid
fluxEngine_C_v1_ErrorCode_ModelWrongSourceType
fluxEngine_C_v1_ErrorCode_InputDimensionError
fluxEngine_C_v1_ErrorCode_InputWavelengthValueError
fluxEngine_C_v1_ErrorCode_FilterCreationError
fluxEngine_C_v1_ErrorCode_WavelengthRangeDeterminationError
fluxEngine_C_v1_ErrorCode_WhiteReferenceMissingError
fluxEngine_C_v1_ErrorCode_WhiteReferenceDimensionError
fluxEngine_C_v1_ErrorCode_DarkReferenceDimensionError
fluxEngine_C_v1_ErrorCode_PreprocessingSetupError
fluxEngine_C_v1_ErrorCode_ProcessingSetupError

Return

0 on success, -1 on failure

Parameters

model: The model to create the processing context for
storage_order: The storage order the input data will have when it is supplied to the processing context
data_type: The scalar data type of the input data when it is supplied to the processing context
max_height: The maximum height of a cube that will be processed using this context
height: Specify -1 here to leave the cube height dynamic (which might not be as efficient at runtime for some models), or the same value as maxHeight to fix the height and indicate it will always be the same for every cube that is being processed.
max_width: The maximum width of a cube that will be processed using this context
width: Specify -1 here to leave the cube width dynamic (which might not be as efficient at runtime for some models), or the same value as maxWidth to fix the width and indicate it will always be the same for every cube that is being processed.
wavelengths: A C array of wavelengths, stored as double precision floating point numbers, in the unit of nanometers.
wavelength_count: The number of wavelengths.
reference_info: How the data should be referenced
context: The resulting processing context
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

enum fluxEngine_C_v1_PushBroomFrame_StorageOrder¶

Hyperspectral PushBroom frame storage order.

A PushBroom camera is a hyperspectral camera that uses a 2D sensor to image a single line, where the optics project different wavelengths of the incoming light onto one of the sensor dimensions. The other sensor dimension is used to spatially resolve the line that is being imaged.

There are two possible orientations of the optics: the wavelengths could be mapped onto the x- or the y-direction of the camera sensor. This enumeration allows the user to select which of these storage orders is actually used.

Values:

fluxEngine_C_v1_PushBroomFrame_StorageOrder_LambdaX = 0¶

Wavelengths are in X-direction.

The y direction of the frame contains the spatial information.

fluxEngine_C_v1_PushBroomFrame_StorageOrder_LambdaY = 1¶

Wavelengths are in Y-direction.

The x direction of the frame contains the spatial information.

int fluxEngine_C_v1_ProcessingContext_create_pushbroom_frame(fluxEngine_C_v1_Model *model, fluxEngine_C_v1_PushBroomFrame_StorageOrder storage_order, fluxEngine_C_v1_DataType data_type, int64_t width, double const *wavelengths, size_t wavelength_count, fluxEngine_C_v1_ReferenceInfo const *reference_info, fluxEngine_C_v1_ProcessingContext **context, fluxEngine_C_v1_Error **error)¶

Create a new processing context for PushBroom frames.

This function creates a new processing context that may be used to sequentially process PushBroom frames. Each consecutive frame is considered to be part of a stream of lines that in principle could be used to construct a cube if concatenated.

The following information must be known in advance to properly setup a fluxEngine processing context that can be used to process this type of HSI data:

The scalar data type
The storage order of the data in memory
The wavelengths
The exact spatial dimension that will be processed with this context; as PushBroom frames should be able to be concatenated, the size of the frame may not be variable, but the number of frames being processed may vary

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_ModelNoLongerValid
fluxEngine_C_v1_ErrorCode_ModelWrongSourceType
fluxEngine_C_v1_ErrorCode_InputDimensionError
fluxEngine_C_v1_ErrorCode_InputWavelengthValueError
fluxEngine_C_v1_ErrorCode_FilterCreationError
fluxEngine_C_v1_ErrorCode_WavelengthRangeDeterminationError
fluxEngine_C_v1_ErrorCode_WhiteReferenceMissingError
fluxEngine_C_v1_ErrorCode_WhiteReferenceDimensionError
fluxEngine_C_v1_ErrorCode_DarkReferenceDimensionError
fluxEngine_C_v1_ErrorCode_PreprocessingSetupError
fluxEngine_C_v1_ErrorCode_ProcessingSetupError

Return

0 on success, -1 on failure

Parameters

model: The model to create the processing context for
storage_order: The storage order the input data will have when it is supplied to the processing context
data_type: The scalar data type of the input data when it is supplied to the processing context
width: The spatial dimension of each PushBroom frame that is supplied (if the storage order indicates that wavelengths are across the x direction of the frame, this indicates the size of the frame in the y direction, and vice-versa)
wavelengths: A C array of wavelengths, stored as double precision floating point numbers, in the unit of nanometers.
wavelength_count: The number of wavelengths.
reference_info: How the data should be referenced
context: The resulting processing context
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ProcessingContext_num_output_sinks(fluxEngine_C_v1_ProcessingContext *context, fluxEngine_C_v1_Error **error)¶

Obtain the number of output sinks in the model.

To retrieve data that has been processed via fluxEngine the designer of the model must add output sinks to the places where data is to be extracted.

This function returns the number of output sinks within the given model. This may be used to iterate over the output sinks and determine their data structure given the input data structure that is supplied.

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_ProcessingContextNoLongerValid

Return

The number of output sinks on success, -1 on failure

Parameters

context: The processing context for which to list the output sinks
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxengine_C_v1_ProcessingContext_find_output_sink(fluxEngine_C_v1_ProcessingContext *context, int output_id, fluxEngine_C_v1_Error **error)¶

Find the output sink with a given output id.

If there is exactly one output sink in the model with a given output id, this will return the index of that sink. If there are no output sinks with that id, or that output id is used multiple times, this will return an error.

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_ProcessingContextNoLongerValid
fluxEngine_C_v1_ErrorCode_OutputIdNotPresent
fluxEngine_C_v1_ErrorCode_OutputIdNotUnique

Return

The index of the output sink (that may be used as a sink_index for other calls) on success, -1 on failure

Parameters

context: The processing context for which to list the output sinks
output_id: The output_id of the output sink
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

enum fluxEngine_C_v1_OutputStorageType¶

The storage type of data at a given output sink.

When extracting data from fluxEngine, the data at a given output sink may be stored in different formats. This enumeration describes the possible formats the data is stored in. Please refer to the introductory information for a more detailed introduction on how data is returned from processing, and what kind of forms it may take.

Values:

fluxEngine_C_v1_OutputStorageType_Tensor = 0¶

Tensor data.

This is the most common case, where data at the end of processing is available as a tensor. For HSI data tensors will typically be of order 3, having a y dimension, x dimension and an additional dimension for e.g. spectral (wavelength) information.

fluxEngine_C_v1_OutputStorageType_ObjectList = 1¶

Object list.

A list of objects that is stored as an array of fluxEngine_C_v1_OutputObject objects.

int fluxEngine_C_v1_ProcessingContext_get_output_sink_meta_info(fluxEngine_C_v1_ProcessingContext *context, int sink_index, int *output_id, char **name, fluxEngine_C_v1_OutputStorageType *output_storage_type, int64_t *input_delay, fluxEngine_C_v1_Error **error)¶

Obtain meta information about a given output sink.

For a given output sink index that ranges between 0 and one less than the value returned by fluxEngine_C_v1_ProcessingContext_num_output_sinks(), this function will return meta information about the output sink.

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_ProcessingContextNoLongerValid
fluxEngine_C_v1_ErrorCode_IndexOutOfRange

Return

0 on success, -1 on failure

Parameters

context: The processing context for which to introspect the output sink
sink_index: The index of the output sink to introspect
output_id: The output id that is set for the the sink. This is purely for informational purposes
name: The name of the output sink will be stored here; the result must be freed with fluxEngine_C_v1_string_free(). If NULL is provided here, no name will be returned.
output_storage_type: The storage type of the data at this output sink
input_delay: The delay of this output sink relative to the input data given. See the advanced topics section of the documentation for more details.
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ProcessingContext_get_output_sink_tensor_structure(fluxEngine_C_v1_ProcessingContext *context, int sink_index, fluxEngine_C_v1_DataType *data_type, int *order, int64_t max_sizes[5], int64_t fixed_sizes[5], fluxEngine_C_v1_Error **error)¶

Obtain information about the tensor structure of a given output sink.

For an output sink with data of tensor type (see fluxEngine_C_v1_OutputStorageType_Tensor for details), this function will return the tensor structure of the data that will be returned via the output sink.

If the storage type does not match, this function will return an error.

Please see the documentation for fluxEngine_C_v1_ProcessingContext_get_output_sink_data() for more information how to process tensor 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_ProcessingContextNoLongerValid
fluxEngine_C_v1_ErrorCode_IndexOutOfRange
fluxEngine_C_v1_ErrorCode_ProcessingContextTypeMismatch

See

fluxEngine_C_v1_ProcessingContext_get_output_sink_data

Return

0 on success, -1 on failure

Parameters

context: The processing context for which to introspect the output sink
sink_index: The index of the output sink to introspect
data_type: The data type of the data returned by the sink
order: The order of the tensor that is being returned. This will typically be 2 or 3.
max_sizes: The maximum dimensions of the tensor that may be returned. Only elements up to order are filled in, the rest will be 0.
fixed_sizes: For each dimension within the order of the tensor, the entry here may either be -1 to indicate that that dimension is variable, or the same value as the corresponding entry in maxSizes to indicate that the dimension is static and will always be the same
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ProcessingContext_get_output_sink_object_list_structure(fluxEngine_C_v1_ProcessingContext *context, int sink_index, int64_t *max_object_count, int64_t *additional_data_size, fluxEngine_C_v1_DataType *additional_data_type, fluxEngine_C_v1_Error **error)¶

Obtain information about the object structure of a given output sink.

For any output sink with data of object list type (see fluxEngine_C_v1_OutputStorageType_ObjectList for details), this function will return information about the object list that is returned.

If the storage type does not match, this function will return an error.

Please see the documentation for fluxEngine_C_v1_ProcessingContext_get_output_sink_data() for more information how to process object list 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_ProcessingContextNoLongerValid
fluxEngine_C_v1_ErrorCode_IndexOutOfRange
fluxEngine_C_v1_ErrorCode_ProcessingContextTypeMismatch

See

fluxEngine_C_v1_ProcessingContext_get_output_sink_data

Return

0 on success, -1 on failure

Parameters

context: The processing context for which to introspect the output sink
sink_index: The index of the output sink to introspect
max_object_count: The maximum number of objects that will be returned after a single execution
additional_data_size: The number of additional data entries present per object (may be 0 to indicate no additional data is present)
additional_data_type: The scalar type of the additional data entries per object
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ProcessingContext_set_source_data_hsi_cube(fluxEngine_C_v1_ProcessingContext *context, int64_t height, int64_t width, void const *data, fluxEngine_C_v1_Error **error)¶

Set the next input data to be processed (HSI cube)

Set the next input data that should be processed by fluxEngine. The user must supply a pointer to a memory region that contains the input data stored contiguously in memory. (For non-contiguously stored data the user may use the alternative fluxEngine_C_v1_ProcessingContext_set_source_data_hsi_cube_ex().)

The user must ensure that the memory region that contains the input data is not altered while fluxEngine_C_v1_ProcessingContext_process_next() is active. (It may be altered after setting it here and before calling it though, as long as the dimensions don’t change.)

If the input cube size was fixed during the creation of the processing context, the height and width parameters must match the height and width specified during creation of the context, or an error will be thrown.

If the input cube size was variable during the creation of the processing context, the height and width parameters must be smaller than or equal to the maximum size specified during the creation of the context.

The storage order of the cube that has been specified during the creation of the processing context will be used. This means that the height and width parameters may refer to different dimensions of the cube depending on the storage order:

For a BIP cube, the cube will be indexed via (y, x, band), meaning the height parameter referes to the dimension 0, the width parameter to dimension 1 and the wavelength count supplied during creation of the cube to the dimension 2 of the cube.
For a BIL cube, the cube will be indexed via (y, band, x), meaning the height parameter referes to the dimension 0, the width parameter to dimension 2 and the wavelength count supplied during creation of the cube to the dimension 1 of the cube.
For a BSQ cube, the cube will be indexed via (band, y, x), meaning the height parameter referes to the dimension 1, the width parameter to dimension 2 and the wavelength count supplied during creation of the cube to the dimension 0 of the cube.

Between calls to fluxEngine_C_v1_ProcessingContext_process_next() this function may be used to change the source data region that is to be used during the next processing call.

If the processing context was not set up to process HSI cubes (e.g. because it was set up to process PushBroom frames), an error will be returned.

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_ProcessingContextNoLongerValid
fluxEngine_C_v1_ErrorCode_ProcessingContextTypeMismatch
fluxEngine_C_v1_ErrorCode_InputDimensionError

Return

0 on success, -1 on failure

Parameters

context: The processing context for which to set the source data region
height: The height of the HSI cube to process
width: The width of the HSI cube to process
data: A pointer to a region of memory that contains the HSI cube stored contiguously, and must be of size width * height * band_count * scalar_size in bytes.
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ProcessingContext_set_source_data_hsi_cube_ex(fluxEngine_C_v1_ProcessingContext *context, int64_t height, int64_t width, int64_t stride1, int64_t stride2, void const *data, fluxEngine_C_v1_Error **error)¶

Set the next input data to be processed (HSI cube, non-contiguous)

This is an extended version of the fluxEngine_C_v1_ProcessingContext_set_source_data_hsi_cube() function. Please see the documentation of that function for details that do not pertain to the strides.

It is possible to lay out cubes non-contiguously in memory. For example, take a 2x2x2 cube with the following 8 elements:

cube(0, 0, 0) = 0
cube(0, 0, 1) = 1
cube(0, 1, 0) = 2
cube(0, 1, 1) = 3
cube(1, 0, 0) = 4
cube(1, 0, 1) = 5
cube(1, 1, 0) = 6
cube(1, 1, 1) = 7

When layed out contiguously in memory, the cube will have the following structure:

 dimension 2
(increment by 1)   dimension 0
  +---+          (increment by 4)
  |   |       +---------------+
  |   |       |               |
  |   v       |               v
+---+---+---+---+---+---+---+---+
| 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 |
+---+---+---+---+---+---+---+---+
  |       ^
  |       |
  +-------+
 dimension 1
(increment by 2)

To increment dimension 2 (the inner-most dimension) the element pointer must be incremented by 1. To increment dimension 1 (the middle dimension) the element pointer must be incremented by 2. To increment dimension 0 (the outer-most dimension) the element pointer has to be incremented by 4.

For cubes that reside contiguously in memory the increments here are always given by the dimensions of the cube. For example, a contiguous cube of dimensions (A, B, C) will have a stride structure of (B * C, C, 1).

However, it is possible that the cube is not contiguous in memory. In the above example, the stride structure for the contiguous cube was (4, 2, 1) due to the size of the cube - but if the stride structure is chosen as (9, 3, 1) the memory layout of the cube would look differently:

 dimension 2
(increment by 1)   dimension 0
  +---+          (increment by 9)
  |   |       +-----------------------------------+
  |   |       |                                   |
  |   v       |                                   v
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
| 0 | 1 | _ | 2 | 3 | _ | _ | _ | _ | 4 | 5 | _ | 6 | 7 |
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
  |           ^
  |           |
  +-----------+
 dimension 1
(increment by 3)

For the HSI cube that is passed to this method, it will have the stride structure (stride1, stride2, 1).

As an example, if the cube is contiguous in memory (and fluxEngine_C_v1_ProcessingContext_set_source_data_hsi_cube() could have been used instead), the following stride structure is assumed:

For contiguous BIP cubes (dimensions (y, x, band)) stride1 would be width * band_count, stride2 would be band_count.
For contiguous BIP cubes (dimensions (y, band, x)) stride1 would be band_count * width, stride2 would be width.
For contiguous BSQ cubes (dimensions (band, y, x)) stride1 would be height * width, stride2 would be width.

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_ProcessingContextNoLongerValid
fluxEngine_C_v1_ErrorCode_ProcessingContextTypeMismatch
fluxEngine_C_v1_ErrorCode_InputDimensionError
fluxEngine_C_v1_ErrorCode_InputStrideError

Return

0 on success, -1 on failure

Parameters

context: The processing context for which to set the source data region
height: The height of the HSI cube to process
width: The width of the HSI cube to process
stride1: The number of scalar elements to skip to increment the left-most dimension of the cube by 1
stride2: The number of scalar elements to skip to increment the middle dimension of the cube by 1
data: A pointer to a region of memory that contains the HSI cube, and must be of size height * stride1 * scalar_size (BIP and BIL storage orders) or band_count * stride1 * scalar_size (BSQ storage order) in bytes
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ProcessingContext_set_source_data_pushbroom_frame(fluxEngine_C_v1_ProcessingContext *context, void const *data, fluxEngine_C_v1_Error **error)¶

Set the next input data to be processed (PushBroom frame)

Set the next input data that should be processed by fluxEngine. The user must supply a pointer to a memory region that contains the input data stored contiguously in memory. (For non-contiguously stored data the user may use the alternative fluxEngine_C_v1_ProcessingContext_set_source_data_pushbroom_frame_ex().)

The user must ensure that the memory region that contains the input data is not altered while fluxEngine_C_v1_ProcessingContext_process_next() is active. (It may be altered after setting it here and before calling it though, as long as the dimensions don’t change.)

The input PushBroom frame size had to be fixed during the creation of the processing context, and the size of the frame must be equal to width and band_count.

The storage order of the cube that has been specified during the creation of the processing context will be used. The supplied frame must be a 2D image with the following dimensions:

For LambdaX storage order, the width of the image must be equal to the wavelength count specified during the creation of the processing context, while the height of the image must be equal to the specified spatial width.
For LambdaY storage order, the height of the image must be equal to the wavelength count specified during the creation of the processing context, while the width of the image must be equal to the specified spatial width.

Between calls to fluxEngine_C_v1_ProcessingContext_process_next() this function may be used to change the source data region that is to be used during the next processing call.

If the processing context was not set up to process PushBroom frames (e.g. because it was set up to process HSI cubes), an error will be returned.

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_ProcessingContextNoLongerValid
fluxEngine_C_v1_ErrorCode_ProcessingContextTypeMismatch

Return

0 on success, -1 on failure

Parameters

context: The processing context for which to set the source data region
data: A pointer to a region of memory that contains the PushBroom frame stored contiguously, and must be of size width * band_count * scalar_size in bytes.
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ProcessingContext_set_source_data_pushbroom_frame_ex(fluxEngine_C_v1_ProcessingContext *context, int64_t stride, void const *data, fluxEngine_C_v1_Error **error)¶

Set the next input data to be processed (PushBroom frame, non-contiguous)

This is an extended version of the fluxEngine_C_v1_ProcessingContext_set_source_data_pushbroom_frame() function. Please see the documentation of that function for details that do not pertain to the strides.

An image may be layed out non-contiguously in memory. For example, take a 2x2 image with the following data:

image(y = 0, x = 0) = 0
image(y = 0, x = 1) = 1
image(y = 1, x = 0) = 2
image(y = 1, x = 1) = 3

This will have the following contiguous representation in memory:

 dimension 1
(increment by 1)
  +---+
  |   |
  |   |
  |   v
+---+---+---+---+
| 0 | 1 | 2 | 3 |
+---+---+---+---+
  |       ^
  |       |
  +-------+
 dimension 0
(increment by 2)

However, the memory may also be stored non-contiguously. For example, if 3 scalar elements are to be skipped whenever the y dimension of the image is incremented, the layout would look like this:

 dimension 1
(increment by 1)
  +---+
  |   |
  |   |
  |   v
+---+---+---+---+---+
| 0 | 1 | _ | 2 | 3 |
+---+---+---+---+---+
  |           ^
  |           |
  +-----------+
 dimension 0
(increment by 3)

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_ProcessingContextNoLongerValid
fluxEngine_C_v1_ErrorCode_ProcessingContextTypeMismatch
fluxEngine_C_v1_ErrorCode_InputStrideError

Return

0 on success, -1 on failure

Parameters

context: The processing context for which to set the source data region
data: A pointer to a region of memory that contains the PushBroom frame, and must be of size stride * band_count * scalar_size (LambdaY case) or stride * width * scalar_size (LambdaX case) in bytes.
stride: The number of scalar elements to skip to get to the next line within the PushBroom frame
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ProcessingContext_process_next(fluxEngine_C_v1_ProcessingContext *context, fluxEngine_C_v1_Error **error)¶

Process the next piece of data.

Processes the next piece of data. The source data must have previously been set via one of the following functions:

fluxEngine_C_v1_ProcessingContext_set_source_data_hsi_cube()
fluxEngine_C_v1_ProcessingContext_set_source_data_hsi_cube_ex()
fluxEngine_C_v1_ProcessingContext_set_source_data_pushbroom_frame()
fluxEngine_C_v1_ProcessingContext_set_source_data_pushbroom_frame_ex()

This method will return once processing of the current data has completed or an error has occurred. The current thread will be used as the thread 0 for parallelization purposes.

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_ProcessingContextNoLongerValid
fluxEngine_C_v1_ErrorCode_ProcessingSourceDataMissing
fluxEngine_C_v1_ErrorCode_ProcessingUnknownError
fluxEngine_C_v1_ErrorCode_ProcessingInternalError
fluxEngine_C_v1_ErrorCode_ProcessingAborted

Return

0 on success, -1 on failure

Parameters

context: The processing context to use
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ProcessingContext_reset_state(fluxEngine_C_v1_ProcessingContext *context, fluxEngine_C_v1_Error **error)¶

Reset the state of the processing context.

This function may only be called in between calls of fluxEngine_C_v1_ProcessingContext_process_next().

When the data to be processed is in the form of entire HSI cubes, that is, the context was created via the fluxEngine_C_v1_ProcessingContext_create_hsi_cube() function, this function will have no effect. (Unless processing was aborted via fluxEngine_C_v1_ProcessingContext_abort(), in which case this must be called to clean up the state.)

When the data to be processed is in the form of consecutive PushBroom frames, that is, the context was created via the fluxEngine_C_v1_ProcessingContext_create_pushbroom_frame() function, this function will reset the internal state and make the context appear as if it had been freshly created. This means that any operation that remembers past state to gain spatial information in the y direction will be reset to the beginning. This affects mostly object-based operations.

This would typically be called when a system with a PushBroom camera is started up again after a pause, and the previously processed data has no direct relation to the data to be processed from this point onwards.

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_ProcessingContextNoLongerValid

Return

0 on success, -1 on failure

Parameters

context: The processing context to use
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ProcessingContext_abort(fluxEngine_C_v1_ProcessingContext *context, fluxEngine_C_v1_Error **error)¶

Abort processing.

This function may be called from a different thread while processing is currently active. It will signal the processing context to abort processing. This function will return immediately, but the processing context is likely still active. Use the fluxEngine_C_v1_ProcessingContext_wait() function to wait until the processing context is no longer active.

After a call to this function the processing context needs to be reset via the function fluxEngine_C_v1_ProcessingContext_reset_state() before it may be used again.

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_ProcessingContextNoLongerValid

Return

0 on success, -1 on failure

Parameters

context: The processing context to use
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ProcessingContext_wait(fluxEngine_C_v1_ProcessingContext *context, fluxEngine_C_v1_Error **error)¶

Wait until processing or an abort is complete.

This function may be called from a different thread while processing is currently active. It will wait until the processing context is not in use anymore, either because processing has completed in the mean time, or an abort was requested and the abort has completed.

Note that fluxEngine_C_v1_ProcessingContext_process_next() already blocks and this method must only be used from different threads that also want to wait for the processing of a specific context to complete.

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_ProcessingContextNoLongerValid

Return

0 on success, -1 on failure

Parameters

context: The processing context to use
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

struct fluxEngine_C_v1_OutputObject¶

An object that is output.

If an output sink is configured to output object data, it will be an array of this structure, containing the information related to each object.

Subclassed by fluxEngine::OutputObject

Public Members

int64_t bounding_box_x¶: The object’s bounding box: x coordinate of the left boundary.

int64_t bounding_box_y¶

The object’s bounding box: y coordinate of the top boundary.

For PushBroom frames this will indicate the starting frame of the object since the last reset.

int64_t bounding_box_width¶: The object’s bounding box: total width.

int64_t bounding_box_height¶: The object’s bounding box: total height.

double gravity_center_x¶

The object’s center of gravity: x coordinate.

The following equation will always be true:

boundung_box_x <= gravity_center_x &&
    gravity_center_x < (bounding_box_x + bounding_box_width)

double gravity_center_y¶

The object’s center of gravity: y coordinate.

The following equation will always be true:

boundung_box_y <= gravity_center_y &&
    gravity_center_y < (bounding_box_y + bounding_box_height)

int64_t area¶: The object’s area in pixels.

int8_t const *mask¶

A pointer to the object’s mask.

This may not be present, in which case this will be NULL. If this is present this will point to a 2D matrix (row-major storage order, contiguous in memory) that has the size of the bounding box specified in this object, where a value of 0 indicates that a given pixel belongs to the object, and a value of -1 indicates that it does not belong to the object.

The following function demonstrates how to interpret the mask, by returning true if a given pixel is part of the object and false otherwise, where x and y are counted relative to the start of the object’s bounding box:

bool is_part_of_object(fluxEngine_C_v1_OutputObject* object,
                       int64_t x, int64_t y)
{
    if (x < 0 || x >= object->bounding_box_width
        || y < 0 || y >= object->bounding_box_height)
        return false;
    return mask[y * object->bounding_box_width + x] == 0;
}

int16_t primary_class¶

The primary class of the object.

If the object was subject to a classifier, this will contain the primary class of the object. Classes within a model are counted beginning at 0. A negative class indicates that the classifier could not find a primary class for the object.

This is only valid if primary_class_present is non-zero.

uint8_t primary_class_present¶

Is a primary class present?

If this is non-zero, it indicates that the object has a primary class and the value stored in primary_class is valid. Otherwise the value stored in primary_class should be ignored.

void const *additional_data¶

Additional data for the object.

This is an array of scalar values, the size being fixed after creation of the processing context, that contain additional data that is passed together with the object.

If this is not present it will be NULL.

int fluxEngine_C_v1_ProcessingContext_get_output_sink_data(fluxEngine_C_v1_ProcessingContext *context, int sink_index, int64_t fixed_sizes[5], void const **data, fluxEngine_C_v1_Error **error)¶

Get the resulting output sink data of a given processing context.

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_ProcessingContextNoLongerValid
fluxEngine_C_v1_ErrorCode_IndexOutOfRange

Return

0 on success, -1 on failure

Parameters

context: The processing context to obtain the output results from
sink_index: The index of the output sink to obtain the output data from
fixed_sizes: The actual amount of data at the output sink will be stored in this user-supplied array. For tensor data the array only the first N elements of the array, where N is the order of the tensor, will be filled. For object list data, the first element of the array will contain the number of objects. Any unused element of this array may be filled with an arbitrary value or left untouched by this method.
data: A pointer to the start of the data region will be stored in this user-supplied array. A memory region returned by this function will be invalidated the next time the user performs data processing again, resets the state of the context, or destroys the context
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

void fluxEngine_C_v1_ProcessingContext_destroy(fluxEngine_C_v1_ProcessingContext *context)¶

Destroy a processing cotext.

Destroy a processing context, freeing its resources.

If NULL is passed to this method, it will do nothing.

Parameters

context: The context to destroy

Driver Paths¶

int fluxEngine_C_v1_set_driver_base_directory(fluxEngine_C_v1_Handle *handle, char const *directory, fluxEngine_C_v1_Error **error)¶

Set the driver base directory.

When loading drivers this sets the base directory where the drivers may be found. If this function is not called, or an empty value or NULL is passed, the directory drivers one level above the directory of the currently running executable will be used. For example, if the executable is C:\App\bin\engine_test.exe, the default drivers directory would be C:\App\drivers. (This is the case on all platforms.)

Note that if this method is not used the user can also override the default via an environment variable per driver type. (See the introductory documentation for more details.)

The directory specified here must exist, otherwise it will not be used and an error will be raised.

Windows note: this will accept a path in the 8bit local file name encoding, which will not be able to represent all possible Unicode characters that may be used on Windows. Please use the fluxEngine_C_v1_set_driver_base_directory_w() function instead if possible, in order to supply a wide 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
fluxEngine_C_v1_ErrorCode_FileNotFoundError
fluxEngine_C_v1_ErrorCode_FileTypeError

Return

0 on success, -1 on failure

Parameters

handle: The handle to set the directory for
directory: The directory to use. If a relative path is supplied the absolute path will be calculated relative to the current directory before the path is stored
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_set_driver_base_directory_w(fluxEngine_C_v1_Handle *handle, wchar_t const *directory, fluxEngine_C_v1_Error **error)¶

Set the driver base directory (wide/Unicode variant for Windows)

When loading drivers this sets the base directory where the drivers may be found. If this function is not called, or an empty value or NULL is passed, the directory drivers one level above the directory of the currently running executable will be used. For example, if the executable is C:\App\bin\engine_test.exe, the default drivers directory would be C:\App\drivers. (This is the case on all platforms.)

Note that if this method is not used the user can also override the default via an environment variable per driver type. (See the introductory documentation for more details.)

The directory specified here must exist, otherwise it will not be used and an error will be raised.

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_FileNotFoundError
fluxEngine_C_v1_ErrorCode_FileTypeError

Return

0 on success, -1 on failure

Parameters

handle: The handle to set the directory for
directory: The directory to use. If a relative path is supplied the absolute path will be calculated relative to the current directory before the path is stored
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_set_driver_isolation_executable(fluxEngine_C_v1_Handle *handle, char const *executable, fluxEngine_C_v1_Error **error)¶

Set the path to the driver isolation executable.

Drivers are loaded via the fluxDriverIsolation executable (on Windows fluxDriverIsolation.exe), in case the default is not where the executable is deployed. The defaults are:

On Windows and macOS the fluxDriverIsolation executable is assumed to be in the same directory as the current executable by default. For example, if the executable is C:\App\bin\engine_test.exe on Windows, the default driver isolation path is assumed to be C:\App\bin\fluxDriverIsolation.exe. Similarly, on macOS, if the main executable is in /Applications/engine_test.app/Contents/MacOS/engine_test, the driver isolation executable is assumed to be in /Applications/engine_test.app/Contents/MacOS/fluxDriverIsolation.

On all other platforms (Linux) the executable is assumed to be in ../libexec/fluxDriverIsolation relative to the current executable path. For example, if the executable is in /opt/engine_test/bin/engine_test, the driver isolation executable will be looked for in /opt/engine_test/libexec/fluxDriverIsolation by default.

Windows note: this will accept a path in the 8bit local file name encoding, which will not be able to represent all possible Unicode characters that may be used on Windows. Please use the fluxEngine_C_v1_set_driver_isolation_executable_w() function instead if possible, in order to supply a wide 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
fluxEngine_C_v1_ErrorCode_FileNotFoundError
fluxEngine_C_v1_ErrorCode_FileTypeError

Return

0 on success, -1 on failure

Parameters

handle: The handle to set the executable path for
executable: The path of the fluxDriverIsolation executable. If a relative path is supplied the absolute path will be calculated relative to the current directory before the path is stored
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_set_driver_isolation_executable_w(fluxEngine_C_v1_Handle *handle, wchar_t const *executable, fluxEngine_C_v1_Error **error)¶

Set the path to the driver isolation executable (wide/Unicode variant for Windows)

Drivers are loaded via the fluxDriverIsolation executable (on Windows fluxDriverIsolation.exe), in case the default is not where the executable is deployed. The defaults are:

On Windows and macOS the fluxDriverIsolation executable is assumed to be in the same directory as the current executable by default. For example, if the executable is C:\App\bin\engine_test.exe on Windows, the default driver isolation path is assumed to be C:\App\bin\fluxDriverIsolation.exe. Similarly, on macOS, if the main executable is in /Applications/engine_test.app/Contents/MacOS/engine_test, the driver isolation executable is assumed to be in /Applications/engine_test.app/Contents/MacOS/fluxDriverIsolation.

On all other platforms (Linux) the executable is assumed to be in ../libexec/fluxDriverIsolation relative to the current executable path. For example, if the executable is in /opt/engine_test/bin/engine_test, the driver isolation executable will be looked for in /opt/engine_test/libexec/fluxDriverIsolation by default.

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_FileNotFoundError
fluxEngine_C_v1_ErrorCode_FileTypeError

Return

0 on success, -1 on failure

Parameters

handle: The handle to set the executable path for
executable: The path of the fluxDriverIsolation executable. If a relative path is supplied the absolute path will be calculated relative to the current directory before the path is stored
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Parameter Information¶

typedef struct fluxEngine_C_v1_ParameterInfo fluxEngine_C_v1_ParameterInfo¶

fluxEngine Parameter Information

This structure contains information about parameters that the user may use to influence behavior. Currently this is used in two places:

Connection parameters of devices. These cannot be explicitly set, but must be passed by the user as a list to fluxEngine_C_v1_DeviceGroup_connect(). These will typically include paths to calibration files that the user must provide.
Parameters that influence a device, such as the exposure time of a camera, the intensity of a light, etc.

Accessors to this structure provide information about the various parameters represented. There are no explicit functions to read or write parameter values, as these are highly context-dependent. For connection parameters there are no getters and setters, as the user must provide a list to the connect function. For device parameters there are various functions that will get or set a specific parameter value.

Note that in the case of device parameters this structure is dynamic - changing a device parameter might change the access mode of other parameters. See fluxEngine_C_v1_ParameterInfo_get_parameter_num_affected_parameters() and similar functions for details.

A note on the naming convention of accessors: whenever information is queried by index, there is typically also a function that queries by name. That function will have a _bn inserted into its signature and will take a name instead of the index. The only exception is the function that returns the actual name, which does not exist with a _bn variant, as that would just return itself.

enum fluxEngine_C_v1_ParameterType¶

The type of the parameter.

Values:

fluxEngine_C_v1_ParameterType_Unknown = -1¶

Unknown type.

This is returned if a specific parameter does not fall into one of the other parameter types.

fluxEngine_C_v1_ParameterType_Boolean = 0¶

Boolean.

The parameter can either be true or false.

fluxEngine_C_v1_ParameterType_Integer = 1¶

Integer.

The parameter is an integer value. There may be additional limits imposed on the range of the integer value.

fluxEngine_C_v1_ParameterType_Float = 2¶

Floating Point.

The parameter is a floating point value. There may be additional limits imposed on the range of the floating point value.

fluxEngine_C_v1_ParameterType_Enumeration = 3¶

Enumeration.

The parameter can be chosen from a set of predetermined values. Each predetermined value is associated with an integer value as well as a unique name.

fluxEngine_C_v1_ParameterType_String = 4¶

String.

The parameter is a string value. Note that strings have to be encoded as UTF-8.

fluxEngine_C_v1_ParameterType_File = 5¶

File.

The parameter is the path to a file in the filesystem. The path can be accessed like a string.

Windows: as string-like parameters are always represented in UTF-8, the path here must also be encoded as UTF-8, not the local 8bit encoding. The UTF-8 representation will internally be converted to wide strings that will be used to access the actual file.

All other platforms: the local 8bit encoding should be used.

fluxEngine_C_v1_ParameterType_Command = 6¶

Command.

A command parameter is a parmaeter that can be used to trigger an action on the device.

enum fluxEngine_C_v1_ParameterAccessMode¶

The access mode of a given parameter.

The access mode describes whether a parameter may be read from or written to.

Values:

fluxEngine_C_v1_ParameterAccessMode_NotAvailable = 0¶

The parameter is not available.

This indicates that the parameter can currently neither be read nor written.

fluxEngine_C_v1_ParameterAccessMode_ReadOnly = 1¶: The parameter is read-only.

fluxEngine_C_v1_ParameterAccessMode_WriteOnly = 2¶

The parameter is write-only.

This is typically only the case for fluxEngine_C_v1_ParameterType_Command type parameters.

fluxEngine_C_v1_ParameterAccessMode_ReadWrite = 3¶

The parameter may be read from and written to.

This is the case for most parameters.

int fluxEngine_C_v1_ParameterInfo_dup(fluxEngine_C_v1_ParameterInfo *pinfo, fluxEngine_C_v1_ParameterInfo **out, fluxEngine_C_v1_Error **error)¶

Duplicate a parameter information structure.

This will create a duplicate of the current structure. The duplicate structure will always return the same information as the original structure, even in the case that the structure represents dynamic device 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

Return

0 on success, -1 on failure

Parameters

pinfo: The structure to duplicate
out: The resulting duplicate structure
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

void fluxEngine_C_v1_ParameterInfo_free(fluxEngine_C_v1_ParameterInfo *pinfo)¶

Free a parameter information structure.

This will release the memory associated with the parameter information structure. The structure must not be used after a call to this function. Passing NULL is allowed, in which case this function function has no effect.

Parameters

pinfo: The structure to free

int fluxEngine_C_v1_ParameterInfo_num_parameters(fluxEngine_C_v1_ParameterInfo *pinfo, fluxEngine_C_v1_Error **error)¶

Get the number of parameters in this parameter list.

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_ParameterInfoNoLongerValid

Return

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

Parameters

pinfo: The parameter information structure to query
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ParameterInfo_get_parameter_name(fluxEngine_C_v1_ParameterInfo *pinfo, int index, char **name, fluxEngine_C_v1_Error **error)¶

Get the name of a parameter.

This will return the name of the parameter with the index index. A parameter’s name is an internal name that is used to uniquely identify the parameter. Please also take a look at the display name of a parameter when looking for something to display to the user.

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_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError

Return

0 on success, -1 on failure

Parameters

pinfo: The parameter information structure to query
index: The index of the parameter to query, starting at 0, and ending at one less than the number of parameters
name: The result as a NUL terminated string. The result must be freed with the fluxEngine_C_v1_string_free() function. This will never be set to NULL.
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ParameterInfo_get_parameter_type(fluxEngine_C_v1_ParameterInfo *pinfo, int index, fluxEngine_C_v1_ParameterType *type, fluxEngine_C_v1_Error **error)¶

Get the type of a parameter.

There is also a variant of this method that queries this information by the the parameter’s name, fluxEngine_C_v1_ParameterInfo_get_parameter_bn_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
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError

Return

0 on success, -1 on failure

Parameters

pinfo: The parameter information structure to query
index: The index of the parameter to query, starting at 0, and ending at one less than the number of parameters
type: The type of the parameter
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ParameterInfo_get_parameter_access_mode(fluxEngine_C_v1_ParameterInfo *pinfo, int index, fluxEngine_C_v1_ParameterAccessMode *access_mode, fluxEngine_C_v1_Error **error)¶

Get the access mode of a parameter.

There is also a variant of this method that queries this information by the the parameter’s name, fluxEngine_C_v1_ParameterInfo_get_parameter_bn_access_mode().

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_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError

Return

0 on success, -1 on failure

Parameters

pinfo: The parameter information structure to query
index: The index of the parameter to query, starting at 0, and ending at one less than the number of parameters
access_mode: The access mode of the parameter
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ParameterInfo_get_parameter_display_name(fluxEngine_C_v1_ParameterInfo *pinfo, int index, char **display_name, fluxEngine_C_v1_Error **error)¶

Get the display name of the parameter.

If set a parameter’s display name is human-readable name that indicates that may be shown to the user and is likely more useful for a person than the internal name. This might not be set though (and then this method will return NULL). There is also a function fluxEngine_C_v1_ParameterInfo_get_parameter_effective_display_name() that returns the display name, or the internal name if the former is not set.

There is also a variant of this method that queries this information by the the parameter’s name, fluxEngine_C_v1_ParameterInfo_get_parameter_bn_display_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
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError

Return

0 on success, -1 on failure

Parameters

pinfo: The parameter information structure to query
index: The index of the parameter to query, starting at 0, and ending at one less than the number of parameters
display_name: The result as a NUL terminated string. The result must be freed with the fluxEngine_C_v1_string_free() function. This may be set to NULL if no specific display name has been set for this parameter.
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ParameterInfo_get_parameter_effective_display_name(fluxEngine_C_v1_ParameterInfo *pinfo, int index, char **display_name, fluxEngine_C_v1_Error **error)¶

Get the effective display name of the parameter.

This will return the result of fluxEngine_C_v1_ParameterInfo_get_parameter_display_name(), unless that would be NULL, in which case the result of fluxEngine_C_v1_ParameterInfo_get_parameter_name() will be returned instead.

There is also a variant of this method that queries this information by the the parameter’s name, fluxEngine_C_v1_ParameterInfo_get_parameter_bn_effective_display_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
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError

Return

0 on success, -1 on failure

Parameters

pinfo: The parameter information structure to query
index: The index of the parameter to query, starting at 0, and ending at one less than the number of parameters
display_name: The result as a NUL terminated string. The result must be freed with the fluxEngine_C_v1_string_free() function. This will never be set to NULL.
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ParameterInfo_get_parameter_short_description(fluxEngine_C_v1_ParameterInfo *pinfo, int index, char **description, fluxEngine_C_v1_Error **error)¶

Get the short description of a parameter.

This will often be used as a tooltip in GUIs. Not all parameters will have a short description, in which case the result of this function will be NULL.

There is also a variant of this method that queries this information by the the parameter’s name, fluxEngine_C_v1_ParameterInfo_get_parameter_bn_short_description().

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_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError

Return

0 on success, -1 on failure

Parameters

pinfo: The parameter information structure to query
index: The index of the parameter to query, starting at 0, and ending at one less than the number of parameters
description: The result as a NUL terminated string. The result must be freed with the fluxEngine_C_v1_string_free() function. This may be set to NULL if no short description has been set for the parameter.
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ParameterInfo_get_parameter_long_description(fluxEngine_C_v1_ParameterInfo *pinfo, int index, char **description, fluxEngine_C_v1_Error **error)¶

Get the long description of a parameter.

This may be a longer text that can span multiple lines. Not all parameters will have a short description, in which case the result of this function will be NULL.

There is also a variant of this method that queries this information by the the parameter’s name, fluxEngine_C_v1_ParameterInfo_get_parameter_bn_long_description().

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_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError

Return

0 on success, -1 on failure

Parameters

pinfo: The parameter information structure to query
index: The index of the parameter to query, starting at 0, and ending at one less than the number of parameters
description: The result as a NUL terminated string. The result must be freed with the fluxEngine_C_v1_string_free() function. This may be set to NULL if no long description has been set for the parameter.
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ParameterInfo_get_parameter_num_affected_parameters(fluxEngine_C_v1_ParameterInfo *pinfo, int index, fluxEngine_C_v1_Error **error)¶

Get the number of parameters affected by changing this parameter.

When controlling devices certain parameters have an effect on other parameters. This could range from enabling or disabling the other parameter, changing the allowed range of the other parameter or even changing the value of the other parameter. For example, when changing the binning value of a camera device, the limits of the ROI are now also changed.

This function returns the number of parameters that are affected by the indicate parameter. For example: if there are three parameters in a device, "BinningHorziontal" (index 0), "OffsetX" (index 1) and "Width" (index 2), and changing the binning value would update both the "OffsetX" and "Width" parameters, then fluxEngine_C_v1_ParameterInfo_get_parameter_num_affected_parameters() would return 2 when index 0 is supplied, indicating that there are two parameters that are affected by the "BinningHorziontal" parameter.

It is possible that there are circulare references: a parameter A may affect a parameter B, which in turn might affect the parameter A again.

The list of affected parameters returned by fluxEngine’s public API will also cover indirect references: if a parameter A affects parameter B, and B itself affects C, then the list of affected parameters for A will include both B and C.

If a parameter A affects other parameters, the user should not rely on the other parameters having the same value, access mode and/or limits when A is changed, and should query that information again, if they require it.

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.

There is also a variant of this method that queries this information by the the parameter’s name, fluxEngine_C_v1_ParameterInfo_get_parameter_bn_num_affected_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_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError

Return

The number of parameters affected by the given parameter, -1 on failure

Parameters

pinfo: The parameter information structure to query
index: The index of the parameter to query, starting at 0, and ending at one less than the number of parameters
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ParameterInfo_get_parameter_affected_parameter_name(fluxEngine_C_v1_ParameterInfo *pinfo, int index, int affected_index, char **affected_name, fluxEngine_C_v1_Error **error)¶

Get the name of an affected parameter.

Please see the documentation for fluxEngine_C_v1_ParameterInfo_get_parameter_num_affected_parameters() for further details on affected parmaeters.

There is also a variant of this method that queries this information by the the parameter’s name, fluxEngine_C_v1_ParameterInfo_get_parameter_bn_affected_parameter_name(). (The affecting parameter still has to be passed per index, as this function queries the name of the affected 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_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterAffectedIndexOutOfRange

Return

0 on success, -1 on failure

Parameters

pinfo: The parameter information structure to query
index: The index of the parameter to query, starting at 0, and ending at one less than the number of parameters
affected_index: The index of the affected parameter, must be from 0 to one less than the number of affected parameters.
affected_name: The result as a NUL terminated string. The result must be freed with the fluxEngine_C_v1_string_free() function. This will never be set to NULL.
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ParameterInfo_get_parameter_default_string(fluxEngine_C_v1_ParameterInfo *pinfo, int index, char **value, fluxEngine_C_v1_Error **error)¶

Get the default value of a parameter as a string.

Connection parameters may have default values that can be queried. Note that device parameter do not have default values, and if this function is called for a parameter list of device parameters, the fluxEngine_C_v1_ErrorCode_ParameterNoDefaults error will be returned.

Except for Command parameters it is always possible to obtain a default value as a string, even if the parameter is not of string type:

In case of enumeration parameters the internal name of the enumeration entry will be returned.
In case of numeric parameters a string representation of that number will be returned.

There is also a variant of this method that queries this information by the the parameter’s name, fluxEngine_C_v1_ParameterInfo_get_parameter_bn_default_string().

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_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterNoDefaults
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterQueryError

Return

0 on success, -1 on failure

Parameters

pinfo: The parameter information structure to query
index: The index of the parameter to query, starting at 0, and ending at one less than the number of parameters
value: The result as a NUL terminated string. The result must be freed with the fluxEngine_C_v1_string_free() function. This will never be set to NULL.
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ParameterInfo_get_parameter_default_integer(fluxEngine_C_v1_ParameterInfo *pinfo, int index, int64_t *value, fluxEngine_C_v1_Error **error)¶

Get the default value of a parameter as an integer.

Connection parameters may have default values that can be queried. Note that device parameter do not have default values, and if this function is called for a parameter list of device parameters, the fluxEngine_C_v1_ErrorCode_ParameterNoDefaults error will be returned.

This will only work for integer and enumeration parameters. In the case of enumeration parameters the value of the default enumeration entry will be returned.

There is also a variant of this method that queries this information by the the parameter’s name, fluxEngine_C_v1_ParameterInfo_get_parameter_bn_default_integer().

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_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterNoDefaults
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterQueryError

Return

0 on success, -1 on failure

Parameters

pinfo: The parameter information structure to query
index: The index of the parameter to query, starting at 0, and ending at one less than the number of parameters
value: The default value of the parameter
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ParameterInfo_get_parameter_default_float(fluxEngine_C_v1_ParameterInfo *pinfo, int index, double *value, fluxEngine_C_v1_Error **error)¶

Get the default value of a parameter as a floating point value.

Connection parameters may have default values that can be queried. Note that device parameter do not have default values, and if this function is called for a parameter list of device parameters, the fluxEngine_C_v1_ErrorCode_ParameterNoDefaults error will be returned.

This will only work for floating point parameters.

There is also a variant of this method that queries this information by the the parameter’s name, fluxEngine_C_v1_ParameterInfo_get_parameter_bn_default_float().

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_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterNoDefaults
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterQueryError

Return

0 on success, -1 on failure

Parameters

pinfo: The parameter information structure to query
index: The index of the parameter to query, starting at 0, and ending at one less than the number of parameters
value: The default value of the parameter
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ParameterInfo_get_parameter_default_boolean(fluxEngine_C_v1_ParameterInfo *pinfo, int index, bool *value, fluxEngine_C_v1_Error **error)¶

Get the default value of a parameter as a boolean.

Connection parameters may have default values that can be queried. Note that device parameter do not have default values, and if this function is called for a parameter list of device parameters, the fluxEngine_C_v1_ErrorCode_ParameterNoDefaults error will be returned.

This will only work for boolean parameters.

There is also a variant of this method that queries this information by the the parameter’s name, fluxEngine_C_v1_ParameterInfo_get_parameter_bn_default_boolean().

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_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterNoDefaults
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterQueryError

Return

0 on success, -1 on failure

Parameters

pinfo: The parameter information structure to query
index: The index of the parameter to query, starting at 0, and ending at one less than the number of parameters
value:
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ParameterInfo_get_parameter_unit(fluxEngine_C_v1_ParameterInfo *pinfo, int index, char **unit, fluxEngine_C_v1_Error **error)¶

Get a parameter’s unit.

Numeric parameters (integer and floating point) may have a unit associated with them, such as Hz or ms. This function will return the unit of the parameter as a string, or NULL if no unit has been set for the parameter.

There is also a variant of this method that queries this information by the the parameter’s name, fluxEngine_C_v1_ParameterInfo_get_parameter_bn_default_unit().

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_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType

Return

0 on success, -1 on failure

Parameters

pinfo: The parameter information structure to query
index: The index of the parameter to query, starting at 0, and ending at one less than the number of parameters
unit: The result as a NUL terminated string. The result must be freed with the fluxEngine_C_v1_string_free() function. This may be be set to NULL if the given parameter does not have a unit
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ParameterInfo_get_parameter_num_enumeration_entries(fluxEngine_C_v1_ParameterInfo *pinfo, int index, fluxEngine_C_v1_Error **error)¶

Get the number of enumeration entries of this parameter.

If the supplied parameter is an enumeration parameter, this will return the number of entries in the enumeration.

There is also a variant of this method that queries this information by the the parameter’s name, fluxEngine_C_v1_ParameterInfo_get_parameter_bn_num_enumeration_entries().

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_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType

Return

The number of enumeration entries of the given enumeration parameter, -1 on failure

Parameters

pinfo: The parameter information structure to query
index: The index of the parameter to query, starting at 0, and ending at one less than the number of parameters
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_name(fluxEngine_C_v1_ParameterInfo *pinfo, int index, int entry_index, char **entry_name, fluxEngine_C_v1_Error **error)¶

Get the name of an enumeration entry.

For a given enumeration parameter and an index into the list of enumeration entries, return the name of that enumeration entry. The name of the entry will be unique within the enumeration, and, as with the parameter names, there will also be a display name for enumeration entries.

There is also a variant of this method that queries this information by the the parameter’s name (but not the entry’s name!), fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_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
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterEnumerationIndexOutOfRange

Return

0 on success, -1 on failure

Parameters

pinfo: The parameter information structure to query
index: The index of the parameter to query, starting at 0, and ending at one less than the number of parameters
entry_index: The index of the enumeration entry, starting at 0, ending at one less than the number of enumeration entries
entry_name: The result as a NUL terminated string. The result must be freed with the fluxEngine_C_v1_string_free() function. This will never be set to NULL.
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_value(fluxEngine_C_v1_ParameterInfo *pinfo, int index, int entry_index, int64_t *value, fluxEngine_C_v1_Error **error)¶

Get the value of an enumeration entry.

Return the integer value of a given enumeration entry.

There are four total variants of this method (including itself), depending on whether you want to specify the parameter by name or by index (indexing the list of all parameters) and whether you want to specify the enumeration entry by name or by index (indexing the list of enumeration entries of that parameter). The variants are:

fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_value(), specifying both the parameter and the enumeration entry by their respective indices
fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_value(), specifying the parameter by its name, but the enumeration entry by its index
fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_bn_value(), specifying the parameter by its index, but the enumeration entry by its name
fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_bn_value(), specifying both the parameter and the enumeration entry by their names

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_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterEnumerationIndexOutOfRange

Return

0 on success, -1 on failure

Parameters

pinfo: The parameter information structure to query
index: The index of the parameter to query, starting at 0, and ending at one less than the number of parameters
entry_index: The index of the enumeration entry, starting at 0, ending at one less than the number of enumeration entries
value: The value of the enumeration entry
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_display_name(fluxEngine_C_v1_ParameterInfo *pinfo, int index, int entry_index, char **display_name, fluxEngine_C_v1_Error **error)¶

Get the display name of an enumeration entry.

Return the display name of a given enumeration entry. An enumeration entry may not have a display name set, in which case this function will return a NULL value.

There is also the method fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_effective_display_name(), which will return the display name of the entry if set, otherwise the entry’s name.

There are four total variants of this method (including itself), depending on whether you want to specify the parameter by name or by index (indexing the list of all parameters) and whether you want to specify the enumeration entry by name or by index (indexing the list of enumeration entries of that parameter). The variants are:

fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_display_name(), specifying both the parameter and the enumeration entry by their respective indices
fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_display_name(), specifying the parameter by its name, but the enumeration entry by its index
fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_bn_display_name(), specifying the parameter by its index, but the enumeration entry by its name
fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_bn_display_name(), specifying both the parameter and the enumeration entry by their names

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_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterEnumerationIndexOutOfRange

Return

0 on success, -1 on failure

Parameters

pinfo: The parameter information structure to query
index: The index of the parameter to query, starting at 0, and ending at one less than the number of parameters
entry_index: The index of the enumeration entry, starting at 0, ending at one less than the number of enumeration entries
display_name: The result as a NUL terminated string. The result must be freed with the fluxEngine_C_v1_string_free() function. This may be set to NULL if no specific display name has been set for the enumeration entry.
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_effective_display_name(fluxEngine_C_v1_ParameterInfo *pinfo, int index, int entry_index, char **display_name, fluxEngine_C_v1_Error **error)¶

Get the effective display name of an enumeration entry.

Return the effective display name of a given enumeration entry, i.e. its display name if set, or its name otherwise.

There are four total variants of this method (including itself), depending on whether you want to specify the parameter by name or by index (indexing the list of all parameters) and whether you want to specify the enumeration entry by name or by index (indexing the list of enumeration entries of that parameter). The variants are:

fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_effective_display_name(), specifying both the parameter and the enumeration entry by their respective indices
fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_effective_display_name(), specifying the parameter by its name, but the enumeration entry by its index
fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_bn_effective_display_name(), specifying the parameter by its index, but the enumeration entry by its name
fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_bn_effective_display_name(), specifying both the parameter and the enumeration entry by their names

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_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterEnumerationIndexOutOfRange

Return

0 on success, -1 on failure

Parameters

pinfo: The parameter information structure to query
index: The index of the parameter to query, starting at 0, and ending at one less than the number of parameters
entry_index: The index of the enumeration entry, starting at 0, ending at one less than the number of enumeration entries
display_name: The result as a NUL terminated string. The result must be freed with the fluxEngine_C_v1_string_free() function. This will never be set to NULL.
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_bn_value(fluxEngine_C_v1_ParameterInfo *pinfo, int index, char const *entry_name, int64_t *value, fluxEngine_C_v1_Error **error)¶

Get the value of an enumeration entry.

Return the integer value of a given enumeration entry.

There are four total variants of this method (including itself), depending on whether you want to specify the parameter by name or by index (indexing the list of all parameters) and whether you want to specify the enumeration entry by name or by index (indexing the list of enumeration entries of that parameter). The variants are:

fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_value(), specifying both the parameter and the enumeration entry by their respective indices
fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_value(), specifying the parameter by its name, but the enumeration entry by its index
fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_bn_value(), specifying the parameter by its index, but the enumeration entry by its name
fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_bn_value(), specifying both the parameter and the enumeration entry by their names

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_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterEnumerationNameDoesNotExist

Return

0 on success, -1 on failure

Parameters

pinfo: The parameter information structure to query
index: The index of the parameter to query, starting at 0, and ending at one less than the number of parameters
entry_name: The name of the enumeration entry
value: The value of the enumeration entry
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_bn_display_name(fluxEngine_C_v1_ParameterInfo *pinfo, int index, char const *entry_name, char **display_name, fluxEngine_C_v1_Error **error)¶

Get the display name of an enumeration entry.

Return the display name of a given enumeration entry. An enumeration entry may not have a display name set, in which case this function will return a NULL value.

There is also the method fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_effective_display_name(), which will return the display name of the entry if set, otherwise the entry’s name.

There are four total variants of this method (including itself), depending on whether you want to specify the parameter by name or by index (indexing the list of all parameters) and whether you want to specify the enumeration entry by name or by index (indexing the list of enumeration entries of that parameter). The variants are:

fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_display_name(), specifying both the parameter and the enumeration entry by their respective indices
fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_display_name(), specifying the parameter by its name, but the enumeration entry by its index
fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_bn_display_name(), specifying the parameter by its index, but the enumeration entry by its name
fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_bn_display_name(), specifying both the parameter and the enumeration entry by their names

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_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterEnumerationNameDoesNotExist

Return

0 on success, -1 on failure

Parameters

pinfo: The parameter information structure to query
index: The index of the parameter to query, starting at 0, and ending at one less than the number of parameters
entry_name: The name of the enumeration entry
display_name: The result as a NUL terminated string. The result must be freed with the fluxEngine_C_v1_string_free() function. This may be set to NULL if no specific display name has been set for the enumeration entry.
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_bn_effective_display_name(fluxEngine_C_v1_ParameterInfo *pinfo, int index, char const *entry_name, char **display_name, fluxEngine_C_v1_Error **error)¶

Get the effective display name of an enumeration entry.

Return the effective display name of a given enumeration entry, i.e. its display name if set, or its name otherwise.

There are four total variants of this method (including itself), depending on whether you want to specify the parameter by name or by index (indexing the list of all parameters) and whether you want to specify the enumeration entry by name or by index (indexing the list of enumeration entries of that parameter). The variants are:

fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_effective_display_name(), specifying both the parameter and the enumeration entry by their respective indices
fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_effective_display_name(), specifying the parameter by its name, but the enumeration entry by its index
fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_bn_effective_display_name(), specifying the parameter by its index, but the enumeration entry by its name
fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_bn_effective_display_name(), specifying both the parameter and the enumeration entry by their names

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_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterEnumerationNameDoesNotExist

Return

0 on success, -1 on failure

Parameters

pinfo: The parameter information structure to query
index: The index of the parameter to query, starting at 0, and ending at one less than the number of parameters
entry_name: The name of the enumeration entry
display_name: The result as a NUL terminated string. The result must be freed with the fluxEngine_C_v1_string_free() function. This will never be set to NULL.
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ParameterInfo_get_parameter_integer_min(fluxEngine_C_v1_ParameterInfo *pinfo, int index, int64_t *v, fluxEngine_C_v1_Error **error)¶

Get the lower limit of the integer parameter.

If an explicit limit is set on the given parameter this will return that limit. Otherwise the lowest value that a signed 64bit integer will be returned.

There is also a variant of this method that queries this information by the the parameter’s name, fluxEngine_C_v1_ParameterInfo_get_parameter_bn_integer_min().

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_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterQueryError

Return

0 on success, -1 on failure

Parameters

pinfo: The parameter information structure to query
index: The index of the parameter to query, starting at 0, and ending at one less than the number of parameters
v: The lower limit of the parameter
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ParameterInfo_get_parameter_integer_max(fluxEngine_C_v1_ParameterInfo *pinfo, int index, int64_t *v, fluxEngine_C_v1_Error **error)¶

Get the upper limit of the integer parameter.

If an explicit limit is set on the given parameter this will return that limit. Otherwise the largest value that a signed 64bit integer will be returned.

There is also a variant of this method that queries this information by the the parameter’s name, fluxEngine_C_v1_ParameterInfo_get_parameter_bn_integer_max().

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_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterQueryError

Return

0 on success, -1 on failure

Parameters

pinfo: The parameter information structure to query
index: The index of the parameter to query, starting at 0, and ending at one less than the number of parameters
v: The upper limit of the parameter
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ParameterInfo_get_parameter_integer_increment(fluxEngine_C_v1_ParameterInfo *pinfo, int index, int64_t *v, fluxEngine_C_v1_Error **error)¶

Get the increment of the integer parameter.

If an increment other than 1 is specified, this means that the valid values of the parameter are given by the formula min_value + increment * N, where N is a natural number.

If an explicit increment is set on the given parameter this will return that increment, and 1 otherwise.

There is also a variant of this method that queries this information by the the parameter’s name, fluxEngine_C_v1_ParameterInfo_get_parameter_bn_integer_increment().

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_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterQueryError

Return

0 on success, -1 on failure

Parameters

pinfo: The parameter information structure to query
index: The index of the parameter to query, starting at 0, and ending at one less than the number of parameters
v: The increment of the parameter
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ParameterInfo_get_parameter_float_min(fluxEngine_C_v1_ParameterInfo *pinfo, int index, double *v, fluxEngine_C_v1_Error **error)¶

Get the lower limit of the floating point parameter.

If an explicit limit is set on the given parameter this will return that limit. Otherwise the lowest finite value that a double precision floating point number can represent will be returned.

There is also a variant of this method that queries this information by the the parameter’s name, fluxEngine_C_v1_ParameterInfo_get_parameter_bn_float_min().

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_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterQueryError

Return

0 on success, -1 on failure

Parameters

pinfo: The parameter information structure to query
index: The index of the parameter to query, starting at 0, and ending at one less than the number of parameters
v: The lower limit of the parameter
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ParameterInfo_get_parameter_float_max(fluxEngine_C_v1_ParameterInfo *pinfo, int index, double *v, fluxEngine_C_v1_Error **error)¶

Get the upper limit of the floating point parameter.

If an explicit limit is set on the given parameter this will return that limit. Otherwise the largest finite value that a double precision floating point number can represent will be returned.

There is also a variant of this method that queries this information by the the parameter’s name, fluxEngine_C_v1_ParameterInfo_get_parameter_bn_float_max().

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_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterQueryError

Return

0 on success, -1 on failure

Parameters

pinfo: The parameter information structure to query
index: The index of the parameter to query, starting at 0, and ending at one less than the number of parameters
v: The upper limit of the parameter
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ParameterInfo_get_parameter_float_increment(fluxEngine_C_v1_ParameterInfo *pinfo, int index, double *v, fluxEngine_C_v1_Error **error)¶

Get the upper limit of the floating point parameter.

If an explicit increment is set on the given parameter this will return that increment, and 1 otherwise.

For floating point values the increment is more of a hint to the user (as compared to the integer case), as the actual value will be adjusted to the nearest allowed value once it is set.

There is also a variant of this method that queries this information by the the parameter’s name, fluxEngine_C_v1_ParameterInfo_get_parameter_bn_float_increment().

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_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterQueryError

Return

0 on success, -1 on failure

Parameters

pinfo: The parameter information structure to query
index: The index of the parameter to query, starting at 0, and ending at one less than the number of parameters
v: The increment of the parameter
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ParameterInfo_get_parameter_bn_type(fluxEngine_C_v1_ParameterInfo *pinfo, char const *name, fluxEngine_C_v1_ParameterType *type, fluxEngine_C_v1_Error **error)¶

Get the type of a parameter.

There is also a variant of this method that queries this information by the the parameter’s index in the parameter list, fluxEngine_C_v1_ParameterInfo_get_parameter_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
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError

Return

0 on success, -1 on failure

Parameters

pinfo: The parameter information structure to query
name: The name of the parameter to query
type: The type of the parameter
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ParameterInfo_get_parameter_bn_access_mode(fluxEngine_C_v1_ParameterInfo *pinfo, char const *name, fluxEngine_C_v1_ParameterAccessMode *access_mode, fluxEngine_C_v1_Error **error)¶

Get the access mode of a parameter.

There is also a variant of this method that queries this information by the the parameter’s index in the parameter list, fluxEngine_C_v1_ParameterInfo_get_parameter_access_mode().

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_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError

Return

0 on success, -1 on failure

Parameters

pinfo: The parameter information structure to query
name: The name of the parameter to query
access_mode: The access mode of the parameter
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ParameterInfo_get_parameter_bn_display_name(fluxEngine_C_v1_ParameterInfo *pinfo, char const *name, char **display_name, fluxEngine_C_v1_Error **error)¶

Get the display name of the parameter

If set a parameter’s display name is human-readable name that indicates that may be shown to the user and is likely more useful for a person than the internal name. This might not be set though (and then this method will return NULL). There is also a function fluxEngine_C_v1_ParameterInfo_get_parameter_effective_display_name() that returns the display name, or the internal name if the former is not set.

There is also a variant of this method that queries this information by the the parameter’s index in the parameter list, fluxEngine_C_v1_ParameterInfo_get_parameter_display_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
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError

Return

0 on success, -1 on failure

Parameters

pinfo: The parameter information structure to query
name: The name of the parameter to query
display_name: The result as a NUL terminated string. The result must be freed with the fluxEngine_C_v1_string_free() function. This may be set to NULL if no specific display name has been set for this parameter.
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ParameterInfo_get_parameter_bn_effective_display_name(fluxEngine_C_v1_ParameterInfo *pinfo, char const *name, char **display_name, fluxEngine_C_v1_Error **error)¶

Get the effective display name of the parameter.

This will return the result of fluxEngine_C_v1_ParameterInfo_get_parameter_display_name(), unless that would be NULL, in which case the result of fluxEngine_C_v1_ParameterInfo_get_parameter_name() will be returned instead.

There is also a variant of this method that queries this information by the the parameter’s index in the parameter list, fluxEngine_C_v1_ParameterInfo_get_parameter_effective_display_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
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError

Return

0 on success, -1 on failure

Parameters

pinfo: The parameter information structure to query
name: The name of the parameter to query
display_name: The result as a NUL terminated string. The result must be freed with the fluxEngine_C_v1_string_free() function. This will never be set to NULL.
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ParameterInfo_get_parameter_bn_short_description(fluxEngine_C_v1_ParameterInfo *pinfo, char const *name, char **description, fluxEngine_C_v1_Error **error)¶

Get the short description of a parameter.

This will often be used as a tooltip in GUIs. Not all parameters will have a short description, in which case the result of this function will be NULL.

There is also a variant of this method that queries this information by the the parameter’s index in the parameter list, fluxEngine_C_v1_ParameterInfo_get_parameter_short_description().

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_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError

Return

0 on success, -1 on failure

Parameters

pinfo: The parameter information structure to query
name: The name of the parameter to query
description: The result as a NUL terminated string. The result must be freed with the fluxEngine_C_v1_string_free() function. This may be set to NULL if no short description has been set for the parameter.
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ParameterInfo_get_parameter_bn_long_description(fluxEngine_C_v1_ParameterInfo *pinfo, char const *name, char **description, fluxEngine_C_v1_Error **error)¶

Get the long description of a parameter.

This may be a longer text that can span multiple lines. Not all parameters will have a short description, in which case the result of this function will be NULL.

There is also a variant of this method that queries this information by the the parameter’s index in the parameter list, fluxEngine_C_v1_ParameterInfo_get_parameter_long_description().

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_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError

Return

0 on success, -1 on failure

Parameters

pinfo: The parameter information structure to query
name: The name of the parameter to query
description: The result as a NUL terminated string. The result must be freed with the fluxEngine_C_v1_string_free() function. This may be set to NULL if no long description has been set for the parameter.
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ParameterInfo_get_parameter_bn_num_affected_parameters(fluxEngine_C_v1_ParameterInfo *pinfo, char const *name, fluxEngine_C_v1_Error **error)¶

Get the number of parameters affected by changing this parameter.

When controlling devices certain parameters have an effect on other parameters. This could range from enabling or disabling the other parameter, changing the allowed range of the other parameter or even changing the value of the other parameter. For example, when changing the binning value of a camera device, the limits of the ROI are now also changed.

This function returns the number of parameters that are affected by the indicate parameter. For example: if there are three parameters in a device, "BinningHorziontal" (index 0), "OffsetX" (index 1) and "Width" (index 2), and changing the binning value would update both the "OffsetX" and "Width" parameters, then fluxEngine_C_v1_ParameterInfo_get_parameter_num_affected_parameters() would return 2 when index 0 is supplied, indicating that there are two parameters that are affected by the "BinningHorziontal" parameter.

It is possible that there are circulare references: a parameter A may affect a parameter B, which in turn might affect the parameter A again.

The list of affected parameters returned by fluxEngine’s public API will also cover indirect references: if a parameter A affects parameter B, and B itself affects C, then the list of affected parameters for A will include both B and C.

If a parameter A affects other parameters, the user should not rely on the other parameters having the same value, access mode and/or limits when A is changed, and should query that information again, if they require it.

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.

There is also a variant of this method that queries this information by the the parameter’s index in the parameter list, fluxEngine_C_v1_ParameterInfo_get_parameter_num_affected_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_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError

Return

The number of parameters affected by the given parameter, -1 on failure

Parameters

pinfo: The parameter information structure to query
name: The name of the parameter to query
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ParameterInfo_get_parameter_bn_affected_parameter_name(fluxEngine_C_v1_ParameterInfo *pinfo, char const *name, int affected_index, char **affected_name, fluxEngine_C_v1_Error **error)¶

Get the name of an affected parameter.

Please see the documentation for fluxEngine_C_v1_ParameterInfo_get_parameter_bn_num_affected_parameters() for further details on affected parmaeters.

There is also a variant of this method that queries this information by the the parameter’s index in the parameter list, fluxEngine_C_v1_ParameterInfo_get_parameter_affected_parameter_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
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterAffectedIndexOutOfRange

Return

0 on success, -1 on failure

Parameters

pinfo: The parameter information structure to query
name: The name of the parameter to query
affected_index: The index of the affected parameter, must be from 0 to one less than the number of affected parameters.
affected_name: The result as a NUL terminated string. The result must be freed with the fluxEngine_C_v1_string_free() function. This will never be set to NULL.
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ParameterInfo_get_parameter_bn_default_string(fluxEngine_C_v1_ParameterInfo *pinfo, char const *name, char **value, fluxEngine_C_v1_Error **error)¶

Get the default value of a parameter as a string.

Connection parameters may have default values that can be queried. Note that device parameter do not have default values, and if this function is called for a parameter list of device parameters, the fluxEngine_C_v1_ErrorCode_ParameterNoDefaults error will be returned.

Except for Command parameters it is always possible to obtain a default value as a string, even if the parameter is not of string type:

In case of enumeration parameters the internal name of the enumeration entry will be returned.
In case of numeric parameters a string representation of that number will be returned.

There is also a variant of this method that queries this information by the the parameter’s index in the parameter list, fluxEngine_C_v1_ParameterInfo_get_parameter_default_string().

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_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterNoDefaults
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterQueryError

Return

0 on success, -1 on failure

Parameters

pinfo: The parameter information structure to query
name: The name of the parameter to query
value: The result as a NUL terminated string. The result must be freed with the fluxEngine_C_v1_string_free() function. This will never be set to NULL.
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ParameterInfo_get_parameter_bn_default_integer(fluxEngine_C_v1_ParameterInfo *pinfo, char const *name, int64_t *value, fluxEngine_C_v1_Error **error)¶

Get the default value of a parameter as an integer.

Connection parameters may have default values that can be queried. Note that device parameter do not have default values, and if this function is called for a parameter list of device parameters, the fluxEngine_C_v1_ErrorCode_ParameterNoDefaults error will be returned.

This will only work for integer and enumeration parameters. In the case of enumeration parameters the value of the default enumeration entry will be returned.

There is also a variant of this method that queries this information by the the parameter’s index in the parameter list, fluxEngine_C_v1_ParameterInfo_get_parameter_default_integer().

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_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterNoDefaults
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterQueryError

Return

0 on success, -1 on failure

Parameters

pinfo: The parameter information structure to query
name: The name of the parameter to query
value: The default value of the parameter
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ParameterInfo_get_parameter_bn_default_float(fluxEngine_C_v1_ParameterInfo *pinfo, char const *name, double *value, fluxEngine_C_v1_Error **error)¶

Get the default value of a parameter as a floating point value.

Connection parameters may have default values that can be queried. Note that device parameter do not have default values, and if this function is called for a parameter list of device parameters, the fluxEngine_C_v1_ErrorCode_ParameterNoDefaults error will be returned.

This will only work for floating point parameters.

There is also a variant of this method that queries this information by the the parameter’s index in the parameter list, fluxEngine_C_v1_ParameterInfo_get_parameter_default_float().

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_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterNoDefaults
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterQueryError

Return

0 on success, -1 on failure

Parameters

pinfo: The parameter information structure to query
name: The name of the parameter to query
value: The default value of the parameter
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ParameterInfo_get_parameter_bn_default_boolean(fluxEngine_C_v1_ParameterInfo *pinfo, char const *name, bool *value, fluxEngine_C_v1_Error **error)¶

Get the default value of a parameter as a boolean.

Connection parameters may have default values that can be queried. Note that device parameter do not have default values, and if this function is called for a parameter list of device parameters, the fluxEngine_C_v1_ErrorCode_ParameterNoDefaults error will be returned.

This will only work for boolean parameters.

There is also a variant of this method that queries this information by the the parameter’s index in the parameter list, fluxEngine_C_v1_ParameterInfo_get_parameter_default_boolean().

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_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterNoDefaults
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterQueryError

Return

0 on success, -1 on failure

Parameters

pinfo: The parameter information structure to query
name: The name of the parameter to query
value: The default value of the parameter
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ParameterInfo_get_parameter_bn_unit(fluxEngine_C_v1_ParameterInfo *pinfo, char const *name, char **unit, fluxEngine_C_v1_Error **error)¶

Get a parameter’s unit.

Numeric parameters (integer and floating point) may have a unit associated with them, such as Hz or ms. This function will return the unit of the parameter as a string, or NULL if no unit has been set for the parameter.

There is also a variant of this method that queries this information by the the parameter’s index in the parameter list, fluxEngine_C_v1_ParameterInfo_get_parameter_default_unit().

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_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType

Return

0 on success, -1 on failure

Parameters

pinfo: The parameter information structure to query
name: The name of the parameter to query
unit: The result as a NUL terminated string. The result must be freed with the fluxEngine_C_v1_string_free() function. This may be be set to NULL if the given parameter does not have a unit
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ParameterInfo_get_parameter_bn_num_enumeration_entries(fluxEngine_C_v1_ParameterInfo *pinfo, char const *name, fluxEngine_C_v1_Error **error)¶

Get the number of enumeration entries of this parameter.

If the supplied parameter is an enumeration parameter, this will return the number of entries in the enumeration.

There is also a variant of this method that queries this information by the the parameter’s index in the parameter list, fluxEngine_C_v1_ParameterInfo_get_parameter_num_enumeration_entries().

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_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType

Return

The number of enumeration entries of the given enumeration parameter, -1 on failure

Parameters

pinfo: The parameter information structure to query
name: The name of the parameter to query
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_name(fluxEngine_C_v1_ParameterInfo *pinfo, char const *name, int entry_index, char **entry_name, fluxEngine_C_v1_Error **error)¶

Get the name of an enumeration entry.

For a given enumeration parameter and an index into the list of enumeration entries, return the name of that enumeration entry. The name of the entry will be unique within the enumeration, and, as with the parameter names, there will also be a display name for enumeration entries.

There is also a variant of this method that queries this information by the the parameter’s index in the parameter list, fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_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
fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterEnumerationIndexOutOfRange

Return

0 on success, -1 on failure

Parameters

pinfo: The parameter information structure to query
name: The name of the parameter to query
entry_index: The index of the enumeration entry, starting at 0, ending at one less than the number of enumeration entries
entry_name: The result as a NUL terminated string. The result must be freed with the fluxEngine_C_v1_string_free() function. This will never be set to NULL.
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_value(fluxEngine_C_v1_ParameterInfo *pinfo, char const *name, int entry_index, int64_t *value, fluxEngine_C_v1_Error **error)¶

Get the value of an enumeration entry.

Return the integer value of a given enumeration entry.

There are four total variants of this method (including itself), depending on whether you want to specify the parameter by name or by index (indexing the list of all parameters) and whether you want to specify the enumeration entry by name or by index (indexing the list of enumeration entries of that parameter). The variants are:

fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_value(), specifying both the parameter and the enumeration entry by their respective indices
fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_value(), specifying the parameter by its name, but the enumeration entry by its index
fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_bn_value(), specifying the parameter by its index, but the enumeration entry by its name
fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_bn_value(), specifying both the parameter and the enumeration entry by their names

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_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterEnumerationIndexOutOfRange

Return

0 on success, -1 on failure

Parameters

pinfo: The parameter information structure to query
name: The name of the parameter to query
entry_index: The index of the enumeration entry, starting at 0, ending at one less than the number of enumeration entries
value: The value of the enumeration entry
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_display_name(fluxEngine_C_v1_ParameterInfo *pinfo, char const *name, int entry_index, char **display_name, fluxEngine_C_v1_Error **error)¶

Get the display name of an enumeration entry.

Return the display name of a given enumeration entry. An enumeration entry may not have a display name set, in which case this function will return a NULL value.

There is also the method fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_effective_display_name(), which will return the display name of the entry if set, otherwise the entry’s name.

There are four total variants of this method (including itself), depending on whether you want to specify the parameter by name or by index (indexing the list of all parameters) and whether you want to specify the enumeration entry by name or by index (indexing the list of enumeration entries of that parameter). The variants are:

fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_display_name(), specifying both the parameter and the enumeration entry by their respective indices
fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_display_name(), specifying the parameter by its name, but the enumeration entry by its index
fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_bn_display_name(), specifying the parameter by its index, but the enumeration entry by its name
fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_bn_display_name(), specifying both the parameter and the enumeration entry by their names

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_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterEnumerationIndexOutOfRange

Return

0 on success, -1 on failure

Parameters

pinfo: The parameter information structure to query
name: The name of the parameter to query
entry_index: The index of the enumeration entry, starting at 0, ending at one less than the number of enumeration entries
display_name: The result as a NUL terminated string. The result must be freed with the fluxEngine_C_v1_string_free() function. This may be set to NULL if no specific display name has been set for the enumeration entry.
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_effective_display_name(fluxEngine_C_v1_ParameterInfo *pinfo, char const *name, int entry_index, char **display_name, fluxEngine_C_v1_Error **error)¶

Get the effective display name of an enumeration entry.

Return the effective display name of a given enumeration entry, i.e. its display name if set, or its name otherwise.

There are four total variants of this method (including itself), depending on whether you want to specify the parameter by name or by index (indexing the list of all parameters) and whether you want to specify the enumeration entry by name or by index (indexing the list of enumeration entries of that parameter). The variants are:

fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_effective_display_name(), specifying both the parameter and the enumeration entry by their respective indices
fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_effective_display_name(), specifying the parameter by its name, but the enumeration entry by its index
fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_bn_effective_display_name(), specifying the parameter by its index, but the enumeration entry by its name
fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_bn_effective_display_name(), specifying both the parameter and the enumeration entry by their names

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_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterEnumerationIndexOutOfRange

Return

0 on success, -1 on failure

Parameters

pinfo: The parameter information structure to query
name: The name of the parameter to query
entry_index: The index of the enumeration entry, starting at 0, ending at one less than the number of enumeration entries
display_name: The result as a NUL terminated string. The result must be freed with the fluxEngine_C_v1_string_free() function. This will never be set to NULL.
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_bn_value(fluxEngine_C_v1_ParameterInfo *pinfo, char const *name, char const *entry_name, int64_t *value, fluxEngine_C_v1_Error **error)¶

Get the value of an enumeration entry.

Return the integer value of a given enumeration entry.

There are four total variants of this method (including itself), depending on whether you want to specify the parameter by name or by index (indexing the list of all parameters) and whether you want to specify the enumeration entry by name or by index (indexing the list of enumeration entries of that parameter). The variants are:

fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_value(), specifying both the parameter and the enumeration entry by their respective indices
fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_value(), specifying the parameter by its name, but the enumeration entry by its index
fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_bn_value(), specifying the parameter by its index, but the enumeration entry by its name
fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_bn_value(), specifying both the parameter and the enumeration entry by their names

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_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterEnumerationNameDoesNotExist

Return

0 on success, -1 on failure

Parameters

pinfo: The parameter information structure to query
name: The name of the parameter to query
entry_name: The name of the enumeration entry
value: The value of the enumeration entry
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_bn_display_name(fluxEngine_C_v1_ParameterInfo *pinfo, char const *name, char const *entry_name, char **display_name, fluxEngine_C_v1_Error **error)¶

Get the display name of an enumeration entry.

Return the display name of a given enumeration entry. An enumeration entry may not have a display name set, in which case this function will return a NULL value.

There is also the method fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_effective_display_name(), which will return the display name of the entry if set, otherwise the entry’s name.

There are four total variants of this method (including itself), depending on whether you want to specify the parameter by name or by index (indexing the list of all parameters) and whether you want to specify the enumeration entry by name or by index (indexing the list of enumeration entries of that parameter). The variants are:

fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_display_name(), specifying both the parameter and the enumeration entry by their respective indices
fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_display_name(), specifying the parameter by its name, but the enumeration entry by its index
fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_bn_display_name(), specifying the parameter by its index, but the enumeration entry by its name
fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_bn_display_name(), specifying both the parameter and the enumeration entry by their names

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_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterEnumerationNameDoesNotExist

Return

0 on success, -1 on failure

Parameters

pinfo: The parameter information structure to query
name: The name of the parameter to query
entry_name: The name of the enumeration entry
display_name: The result as a NUL terminated string. The result must be freed with the fluxEngine_C_v1_string_free() function. This may be set to NULL if no specific display name has been set for the enumeration entry.
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_bn_effective_display_name(fluxEngine_C_v1_ParameterInfo *pinfo, char const *name, char const *entry_name, char **display_name, fluxEngine_C_v1_Error **error)¶

Get the effective display name of an enumeration entry.

Return the effective display name of a given enumeration entry, i.e. its display name if set, or its name otherwise.

There are four total variants of this method (including itself), depending on whether you want to specify the parameter by name or by index (indexing the list of all parameters) and whether you want to specify the enumeration entry by name or by index (indexing the list of enumeration entries of that parameter). The variants are:

fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_effective_display_name(), specifying both the parameter and the enumeration entry by their respective indices
fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_effective_display_name(), specifying the parameter by its name, but the enumeration entry by its index
fluxEngine_C_v1_ParameterInfo_get_parameter_enumeration_entry_bn_effective_display_name(), specifying the parameter by its index, but the enumeration entry by its name
fluxEngine_C_v1_ParameterInfo_get_parameter_bn_enumeration_entry_bn_effective_display_name(), specifying both the parameter and the enumeration entry by their names

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_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterEnumerationNameDoesNotExist

Return

0 on success, -1 on failure

Parameters

pinfo: The parameter information structure to query
name: The name of the parameter to query
entry_name: The name of the enumeration entry
display_name: The result as a NUL terminated string. The result must be freed with the fluxEngine_C_v1_string_free() function. This will never be set to NULL.
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ParameterInfo_get_parameter_bn_integer_min(fluxEngine_C_v1_ParameterInfo *pinfo, char const *name, int64_t *v, fluxEngine_C_v1_Error **error)¶

Get the lower limit of the integer parameter.

If an explicit limit is set on the given parameter this will return that limit. Otherwise the lowest value that a signed 64bit integer will be returned.

There is also a variant of this method that queries this information by the the parameter’s index in the parameter list, fluxEngine_C_v1_ParameterInfo_get_parameter_integer_min().

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_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterQueryError

Return

0 on success, -1 on failure

Parameters

pinfo: The parameter information structure to query
name: The name of the parameter to query
v: The lower limit of the parameter
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ParameterInfo_get_parameter_bn_integer_max(fluxEngine_C_v1_ParameterInfo *pinfo, char const *name, int64_t *v, fluxEngine_C_v1_Error **error)¶

Get the upper limit of the integer parameter.

If an explicit limit is set on the given parameter this will return that limit. Otherwise the largest value that a signed 64bit integer will be returned.

There is also a variant of this method that queries this information by the the parameter’s index in the parameter list, fluxEngine_C_v1_ParameterInfo_get_parameter_integer_max().

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_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterQueryError

Return

0 on success, -1 on failure

Parameters

pinfo: The parameter information structure to query
name: The name of the parameter to query
v: The upper limit of the parameter
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ParameterInfo_get_parameter_bn_integer_increment(fluxEngine_C_v1_ParameterInfo *pinfo, char const *name, int64_t *v, fluxEngine_C_v1_Error **error)¶

Get the increment of the integer parameter.

If an increment other than 1 is specified, this means that the valid values of the parameter are given by the formula min_value + increment * N, where N is a natural number.

If an explicit increment is set on the given parameter this will return that increment, and 1 otherwise.

There is also a variant of this method that queries this information by the the parameter’s index in the parameter list, fluxEngine_C_v1_ParameterInfo_get_parameter_integer_increment().

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_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterQueryError

Return

0 on success, -1 on failure

Parameters

pinfo: The parameter information structure to query
name: The name of the parameter to query
v: The increment of the parameter
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ParameterInfo_get_parameter_bn_float_min(fluxEngine_C_v1_ParameterInfo *pinfo, char const *name, double *v, fluxEngine_C_v1_Error **error)¶

Get the lower limit of the floating point parameter.

If an explicit limit is set on the given parameter this will return that limit. Otherwise the lowest finite value that a double precision floating point number can represent will be returned.

There is also a variant of this method that queries this information by the the parameter’s index in the parameter list, fluxEngine_C_v1_ParameterInfo_get_parameter_float_min().

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_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterQueryError

Return

0 on success, -1 on failure

Parameters

pinfo: The parameter information structure to query
name: The name of the parameter to query
v: The lower limit of the parameter
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ParameterInfo_get_parameter_bn_float_max(fluxEngine_C_v1_ParameterInfo *pinfo, char const *name, double *v, fluxEngine_C_v1_Error **error)¶

Get the upper limit of the floating point parameter.

If an explicit limit is set on the given parameter this will return that limit. Otherwise the largest finite value that a double precision floating point number can represent will be returned.

There is also a variant of this method that queries this information by the the parameter’s index in the parameter list, fluxEngine_C_v1_ParameterInfo_get_parameter_float_max().

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_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterQueryError

Return

0 on success, -1 on failure

Parameters

pinfo: The parameter information structure to query
name: The name of the parameter to query
v: The upper limit of the parameter
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ParameterInfo_get_parameter_bn_float_increment(fluxEngine_C_v1_ParameterInfo *pinfo, char const *name, double *v, fluxEngine_C_v1_Error **error)¶

Get the upper limit of the floating point parameter.

If an explicit increment is set on the given parameter this will return that increment, and 1 otherwise.

For floating point values the increment is more of a hint to the user (as compared to the integer case), as the actual value will be adjusted to the nearest allowed value once it is set.

There is also a variant of this method that queries this information by the the parameter’s index in the parameter list, fluxEngine_C_v1_ParameterInfo_get_parameter_float_increment().

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_ParameterInfoNoLongerValid
fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist
fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError
fluxEngine_C_v1_ErrorCode_ParameterWrongType
fluxEngine_C_v1_ErrorCode_ParameterQueryError

Return

0 on success, -1 on failure

Parameters

pinfo: The parameter information structure to query
name: The name of the parameter to query
v: The increment of the parameter
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Device Enumeration¶

typedef struct fluxEngine_C_v1_EnumerationResult fluxEngine_C_v1_EnumerationResult¶

Device enumeration result.

This structure contains the result of a device enumeration. It will contain a list of devices that were found, a list of drivers that were found (even if the drivers didn’t find any devices), and a list of warnings and errors of the various drivers.

enum fluxEngine_C_v1_DriverState¶

Driver state.

Describes the state of the driver at the end of the enumeration process. This can be used to detect issues with the driver.

Values:

fluxEngine_C_v1_DriverState_Unknown = -1¶

The state is unknown.

This likely indicates an internal error during enumeration.

fluxEngine_C_v1_DriverState_OK = 0¶

OK.

The driver could successfully perform the enumeration. This is a valid state even if the driver didn’t find any device.

fluxEngine_C_v1_DriverState_LoadTimeout = 1¶

Driver load timeout.

The driver didn’t respond at all within the specified enumeration timeout, indicating that it didn’t load in time. If a sufficiently long timeout has been provided (e.g. more than 3 seconds) this is typically an indication that there is an issue with the driver.

fluxEngine_C_v1_DriverState_LoadError = 2¶

Driver load error.

The driver could not be loaded, for example because the driver file is not valid, or the isolation executable could not be found (in which case all drivers will suffer from this error).

fluxEngine_C_v1_DriverState_EnumerationError = 3¶

Enumeration error.

The driver generated an error message during the enumeration process. That error can be queried from the enumeration result.

fluxEngine_C_v1_DriverState_Crashed = 4¶

Driver crashed.

The driver crashed during enumeration. This typically indicates that there is an issue with a missing dependency of the driver.

int fluxEngine_C_v1_enumerate_devices(fluxEngine_C_v1_Handle *handle, int type, fluxEngine_C_v1_EnumerationResult **out, int64_t timeoutMs, fluxEngine_C_v1_Error **error)¶

Enumerate devices.

This method enumerates all devices that are connected to the system for which drivers have been installed. Please note that fluxEngine_C_v1_set_driver_isolation_executable() and fluxEngine_C_v1_set_driver_base_directory() should be called before this method if the driver directory or the directory of the isolation executable are in non-standard paths.

The result of this function must be freed via fluxEngine_C_v1_EnumerationResult_free(). Note that a call to fluxEngine_C_v1_EnumerationResult_free() will also free the associated structures (except the device parameter info structure of an enumerated device, which must be freed separately).

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

Return

0 on success, -1 on failure

Parameters

handle: The fluxEngine handle
type: The type of drivers to identify. This may either be a value of type fluxEngine_C_v1_DriverType, or -1 to indicate that all driver types should be searched for
out: The enumeration result
timeoutMs: The time to wait for the enumeration to complete. Note that this method will always wait this amount of time before it returns.
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_EnumerationResult_num_devices(fluxEngine_C_v1_EnumerationResult *enumeration_result, fluxEngine_C_v1_Error **error)¶

Get the number of devices found.

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

Return

The number of devices on success, -1 on failure

Parameters

enumeration_result: The enumeration result
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_EnumerationResult_get_device(fluxEngine_C_v1_EnumerationResult *enumeration_result, int index, fluxEngine_C_v1_EnumeratedDevice **enumerated_device, fluxEngine_C_v1_Error **error)¶

Get a specific enumerated device.

Information about the enumerated device may be queried by the corresponding accessors. The pointer returned by this method may be used in comparisons with pointers returned from other methods, such as fluxEngine_C_v1_EnumeratedDriver_get_device(), that return enumerated devices of the same enumeration result.

Important: the device structure will be valid only as long as the enumeration result has not been freed.

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_DeviceEnumerationInvalidIndex

Return

0 on success, -1 on failure

Parameters

enumeration_result: The enumeration result
index: The index of the enumerated device, starting at 0, ending at one less than the number of enumerated devices
enumerated_device: The enumerated device
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_EnumerationResult_num_drivers(fluxEngine_C_v1_EnumerationResult *enumeration_result, fluxEngine_C_v1_Error **error)¶

Get the number of drivers.

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

Return

The number of drivers on success, -1 on failure

Parameters

enumeration_result: The enumeration result
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_EnumerationResult_get_driver(fluxEngine_C_v1_EnumerationResult *enumeration_result, int index, fluxEngine_C_v1_EnumeratedDriver **enumerated_driver, fluxEngine_C_v1_Error **error)¶

Get a specific driver.

Information about the driver may be queried by the corresponding accessors. The pointer returned by this method may be used in comparisons with pointers returned from other methods, such as fluxEngine_C_v1_EnumeratedDevice_get_driver(), that return drivers of the same enumeration result.

Important: the driver structure will be valid only as long as the enumeration result has not been freed.

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_DeviceEnumerationInvalidIndex

Return

0 on success, -1 on failure

Parameters

enumeration_result: The enumeration result
index: The index of the driver, starting at 0, ending at one less than the number of drivers
enumerated_driver: The driver
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_EnumerationResult_num_warnings(fluxEngine_C_v1_EnumerationResult *enumeration_result, fluxEngine_C_v1_Error **error)¶

Get the number of warnings during enumeration.

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

Return

The number of warnings on success, -1 on failure

Parameters

enumeration_result: The enumeration result
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_EnumerationResult_get_warning(fluxEngine_C_v1_EnumerationResult *enumeration_result, int index, fluxEngine_C_v1_EnumerationWarning **enumeration_warning, fluxEngine_C_v1_Error **error)¶

Get an enumeration warning.

Information about the warning may be queried by the corresponding accessors. Important: the warning structure will be valid only as long as the enumeration result has not been freed.

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_DeviceEnumerationInvalidIndex

Return

0 on success, -1 on failure

Parameters

enumeration_result: The enumeration result
index: The index of the warning, starting at 0, ending at one less than the number of warnings
enumeration_warning: The warning
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_EnumerationResult_num_errors(fluxEngine_C_v1_EnumerationResult *enumeration_result, fluxEngine_C_v1_Error **error)¶

Get the number of errors during enumeration.

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

Return

The number of errors on success, -1 on failure

Parameters

enumeration_result: The enumeration result
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_EnumerationResult_get_error(fluxEngine_C_v1_EnumerationResult *enumeration_result, int index, fluxEngine_C_v1_EnumerationError **enumeration_error, fluxEngine_C_v1_Error **error)¶

Get an enumeration error.

Information about the error may be queried by the corresponding accessors. Important: the error structure will be valid only as long as the enumeration result has not been freed.

The error returned when this method is successful is an error that occurred during the enumeration process, while the error structure that is filled if this method fails is an indication that something went wrong while retrieving the error. The following codes may be returned by this function in that case:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_DeviceEnumerationInvalidIndex

Return

0 on success, -1 on failure

Parameters

enumeration_result: The enumeration result
index: The index of the error, starting at 0, ending at one less than the number of errors
enumeration_error: The error
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

void fluxEngine_C_v1_EnumerationResult_free(fluxEngine_C_v1_EnumerationResult *enumeration_result)¶

Free an enumeration result.

Important: all of the structures retrieved from the enumeration result are invalid after a call to this method.

Passing NULL to this method is safe. (In that case this method has no effect.)

Parameters

enumeration_result: The enumeration result to free

typedef struct fluxEngine_C_v1_EnumeratedDevice fluxEngine_C_v1_EnumeratedDevice¶

Enumerated device.

This structure describes an enumerated device. The various accessors may be used to query the manufacturer, model, and serial number of the device, as well as information about the required connection parameters for it. Finally an id is provided that identifies the device to the connect method.

int fluxEngine_C_v1_EnumeratedDevice_get_id(fluxEngine_C_v1_EnumeratedDevice *enumerated_device, void **buffer, size_t *size, fluxEngine_C_v1_Error **error)¶

Get the id of the device.

This device id may be used to identify the device for the purpose of the fluxEngine_C_v1_DeviceGroup_connect() method. The id should be considered non-permanent: unplugging the device and plugging it back in again, or rebooting the computer will likely cause the same device to have a different id. It is guaranteed to be valid for long enough that after an enumeration process the user may use it to connect to that device.

The id should be considered opaque by the user: newer versions of fluxEngine may return a completely different id for the same device; even just updating the driver may result in a different id.

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

Return

0 on success, -1 on failure

Parameters

enumerated_device: The enumerated device to query
buffer: Where to store the pointer to the allocated id buffer. This must be freed via the fluxEngine_C_v1_id_free() function
size: Where to store the number of bytes the id uses
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_EnumeratedDevice_get_driver(fluxEngine_C_v1_EnumeratedDevice *enumerated_device, fluxEngine_C_v1_EnumeratedDriver **enumerated_driver, fluxEngine_C_v1_Error **error)¶

Get the driver associated with the device.

The pointer returned by this method in the enumerated_driver parameter will be equal to the pointer of a driver that can be obtained via the fluxEngine_C_v1_EnumerationResult_get_driver() 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

Return

0 on success, -1 on failure

Parameters

enumerated_device: The enumerated device to query
enumerated_driver: Where to store a pointer to the driver structure
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_EnumeratedDevice_get_display_name(fluxEngine_C_v1_EnumeratedDevice *enumerated_device, char **display_name, fluxEngine_C_v1_Error **error)¶

Get the display name of a device.

This will return a string that may be shown to the user that identifies the device. It will typically have the format Manufacturer Model (Serial Number), but if one or more of these quantities is empty or missing, they will be omitted.

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

Return

0 on success, -1 on failure

Parameters

enumerated_device: The enumerated device to query
display_name: The display name of the device. It must be freed by the user via the fluxEngine_C_v1_string_free() method.
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_EnumeratedDevice_get_manufacturer(fluxEngine_C_v1_EnumeratedDevice *enumerated_device, char **manufacturer, fluxEngine_C_v1_Error **error)¶

Get the manufacturer of a device.

This will never return a NULL string.

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

Return

0 on success, -1 on failure

Parameters

enumerated_device: The enumerated device to query
manufacturer: The manufacturer of the device. It must be freed by the user via the fluxEngine_C_v1_string_free() method.
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_EnumeratedDevice_get_model_name(fluxEngine_C_v1_EnumeratedDevice *enumerated_device, char **model_name, fluxEngine_C_v1_Error **error)¶

Get the device model.

This will never return a NULL string.

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

Return

0 on success, -1 on failure

Parameters

enumerated_device: The enumerated device to query
model_name: The model name of the device. It must be freed by the user via the fluxEngine_C_v1_string_free() method.
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_EnumeratedDevice_get_serial_number(fluxEngine_C_v1_EnumeratedDevice *enumerated_device, char **serial_number, fluxEngine_C_v1_Error **error)¶

Get the serial number of an enumerated device.

In some cases it is possible to obtain the serial number of a device just from enumerating it. This is often the case for devices that are plugged in via USB (as long as they provide their serial number in the USB descriptor) and for devices that can be found via an Ethernet protocol that supports discovery. This is typically not the case for devices that must be probed (such as devices that are controlled via a serial port).

In case it is possible to obtain a serial number of the device without first connecting to it, that serial number will be reported here. If that is not the case, or the device simply does not have a serial number, a NULL string will be returned. If the device does have a serial number, it will be reported once the device has been connected, even if NULL is returned here. The only guarantee is that if a non-NULL string is returned here, the serial number reported here will be identical to the serial number reported after the user has connected to that 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

Return

0 on success, -1 on failure

Parameters

enumerated_device: The enumerated device to query
serial_number: The serial number of the device. It must be freed by the user via the fluxEngine_C_v1_string_free() method.
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_EnumeratedDevice_get_parameter_info(fluxEngine_C_v1_EnumeratedDevice *enumerated_device, fluxEngine_C_v1_ParameterInfo **parameter_info, fluxEngine_C_v1_Error **error)¶

Get the connection parameter info of an enumerated device.

The resulting structure will describe all of the connection parameters that the device provides. For some devices the user must provide connection parameters (such as a calibration file), while they might be optional for other devices.

The resulting parameter information structure will remain valid even if the enumeration result is freed and must be freed explicitly via the fluxEngine_C_v1_ParameterInfo_free() method.

Multiple calls to this method will result in different parameter information structures that are equivalent to having called fluxEngine_C_v1_ParameterInfo_dup() on a single one, but must each be freed individually.

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

Return

0 on success, -1 on failure

Parameters

enumerated_device: The enumerated device to query
parameter_info: The parameter information structure
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

typedef struct fluxEngine_C_v1_EnumeratedDriver fluxEngine_C_v1_EnumeratedDriver¶

Enumerated driver.

This structure describes an enumerated driver. The accessors provide the (normalized) file name of the driver, the driver type, the driver description as well as the driver version.

int fluxEngine_C_v1_EnumeratedDriver_get_name(fluxEngine_C_v1_EnumeratedDriver *enumerated_driver, char **name, fluxEngine_C_v1_Error **error)¶

Get the normalized file name of the driver.

This must be passed to the fluxEngine_C_v1_DeviceGroup_connect() method to identify the driver that should 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

Return

0 on success, -1 on failure

Parameters

enumerated_driver: The driver to query
name: The normalized file name of the driver that is used to identify it in conjunction with the driver’s type
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_EnumeratedDriver_get_type(fluxEngine_C_v1_EnumeratedDriver *enumerated_driver, fluxEngine_C_v1_DriverType *type, fluxEngine_C_v1_Error **error)¶

Get the type 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

Return

0 on success, -1 on failure

Parameters

enumerated_driver: The driver to query
type: The type of the driver
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_EnumeratedDriver_get_description(fluxEngine_C_v1_EnumeratedDriver *enumerated_driver, char **description, fluxEngine_C_v1_Error **error)¶

Get a human-readable description of the driver.

If the driver could not be loaded at all, or the driver crashed before its description could be queried, this method will return NULL.

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

Return

0 on success, -1 on failure

Parameters

enumerated_driver: The driver to query
description: The description of the driver. It must be freed by the user via the fluxEngine_C_v1_string_free() method.
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_EnumeratedDriver_get_version(fluxEngine_C_v1_EnumeratedDriver *enumerated_driver, char **version, fluxEngine_C_v1_Error **error)¶

Get a human-readable version of the driver.

If the driver could not be loaded at all, or the driver crashed before its version could be queried, this method will return NULL.

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

Return

0 on success, -1 on failure

Parameters

enumerated_driver: The driver to query
version: The version of the driver. It must be freed by the user via the fluxEngine_C_v1_string_free() method.
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_EnumeratedDriver_get_state(fluxEngine_C_v1_EnumeratedDriver *enumerated_driver, fluxEngine_C_v1_DriverState *state, fluxEngine_C_v1_Error **error)¶

Get the driver state.

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

Return

0 on success, -1 on failure

Parameters

enumerated_driver: The driver to query
state: The state of the driver at the end of the enumeration process
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_EnumeratedDriver_get_num_devices(fluxEngine_C_v1_EnumeratedDriver *enumerated_driver, fluxEngine_C_v1_Error **error)¶

Get the number of devices the driver found.

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

Return

The number of devices on success, -1 on failure

Parameters

enumerated_driver: The driver to query
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_EnumeratedDriver_get_device(fluxEngine_C_v1_EnumeratedDriver *enumerated_driver, int index, fluxEngine_C_v1_EnumeratedDevice **enumerated_device, fluxEngine_C_v1_Error **error)¶

Get a device found by the driver.

If a driver found devices during enumeration, this method can be used to obtain the device structure associated with them. The index parameter will only count devices found by this specific driver, regardless of how many devices were found during the entirety of the enumeration process.

The pointer returned by this method in the enumerated_device parameter will be equal to the pointer of a device that can be obtained via the fluxEngine_C_v1_EnumerationResult_get_device() 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_DeviceEnumerationInvalidIndex

Return

0 on success, -1 on failure

Parameters

enumerated_driver: The driver to query
index: The index of the device, starting at 0, ending at one less than the number of devices this specific driver has found
enumerated_device: Where to store a pointer to the device structure
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

typedef struct fluxEngine_C_v1_EnumerationWarning fluxEngine_C_v1_EnumerationWarning¶

Enumeration warning.

This structure contains a warning message that a driver produced during the enumeration process.

int fluxEngine_C_v1_EnumerationWarning_get_driver(fluxEngine_C_v1_EnumerationWarning *enumeration_warning, fluxEngine_C_v1_EnumeratedDriver **enumerated_driver, fluxEngine_C_v1_Error **error)¶

Get the driver associated with the warning.

The pointer returned by this method in the enumerated_driver parameter will be equal to the pointer of a driver that can be obtained via the fluxEngine_C_v1_EnumerationResult_get_driver() 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

Return

0 on success, -1 on failure

Parameters

enumeration_warning: The enumeration warning to query
enumerated_driver: Where to store a pointer to the driver structure
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_EnumerationWarning_get_message(fluxEngine_C_v1_EnumerationWarning *enumeration_warning, char **message, fluxEngine_C_v1_Error **error)¶

Get the warning message.

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

Return

0 on success, -1 on failure

Parameters

enumeration_warning: The enumeration warning to query
message: The enumeration warning. It must be freed by the user via fluxEngine_C_v1_string_free().
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

typedef struct fluxEngine_C_v1_EnumerationError fluxEngine_C_v1_EnumerationError¶

Enumeration error.

This structure contains an error message that a driver produced during the enumeration process.

int fluxEngine_C_v1_EnumerationError_get_driver(fluxEngine_C_v1_EnumerationError *enumeration_error, fluxEngine_C_v1_EnumeratedDriver **enumerated_driver, fluxEngine_C_v1_Error **error)¶

Get the driver associated with the error.

The pointer returned by this method in the enumerated_driver parameter will be equal to the pointer of a driver that can be obtained via the fluxEngine_C_v1_EnumerationResult_get_driver() 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

Return

0 on success, -1 on failure

Parameters

enumeration_error: The enumeration error to query
enumerated_driver: Where to store a pointer to the driver structure
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_EnumerationError_get_message(fluxEngine_C_v1_EnumerationError *enumeration_error, char **message, fluxEngine_C_v1_Error **error)¶

Get the error message.

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

Return

0 on success, -1 on failure

Parameters

enumeration_error: The enumeration error to query
message: The enumeration error. It must be freed by the user via fluxEngine_C_v1_string_free().
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

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.

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.

Return

0 on success, -1 on failure

Parameters

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

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.

Return

0 on success, -1 on failure

Parameters

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

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.

Return

0 on success, -1 on failure

Parameters

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

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.

Return

0 on success, -1 on failure

Parameters

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

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.

Return

0 on success, -1 on failure

Parameters

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

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.

Return

0 on success, -1 on failure

Parameters

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

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:

fluxEngine_C_v1_DeviceNotificationType_None = -1¶

No notification.

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

fluxEngine_C_v1_DeviceNotificationType_IrrecoverableError = 0¶

Irrecoverable error.

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

See: fluxEngine_C_v1_LightControlDeviceStatus_IrrecoverableError
See: fluxEngine_C_v1_InstrumentDeviceStatus_IrrecoverableError

fluxEngine_C_v1_DeviceNotificationType_RecoverableError = 1¶

Recoverable error.

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

See: fluxEngine_C_v1_LightControlDeviceStatus_RecoverableError
See: fluxEngine_C_v1_InstrumentDeviceStatus_RecoverableError

fluxEngine_C_v1_DeviceNotificationType_Warning = 2¶

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

Return

0 on success, -1 on failure

Parameters

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

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.

Return

0 on success, -1 on failure

Parameters

device_group: The device group
type: The type of the notification
device: 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: The notification message. This must be freed via fluxEngine_C_v1_string_free().
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

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:

fluxEngine_C_v1_DeviceType_Instrument = 0¶

Instrument device.

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

fluxEngine_C_v1_DeviceType_LightControl = 2¶: 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

Return

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

Parameters

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

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.

Return

0 on success, -1 on failure

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: 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: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

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.

Return

0 on success, -1 on failure

Parameters

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

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.

Return

0 on success, -1 on failure

Parameters

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

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.

Return

0 on success, -1 on failure

Parameters

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

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

Get the device’s manufacturer.

Return

0 on success, -1 on failure

Parameters

device: The device
name: 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: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

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.

Return

0 on success, -1 on failure

Parameters

device: The device
name: 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: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

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.

Return

0 on success, -1 on failure

Parameters

device: The device
description: 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: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

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.

Return

0 on success, -1 on failure

Parameters

device: The device
serial_number: 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: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

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:

fluxEngine_C_v1_ParameterListType_Parameter = 0¶

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.

fluxEngine_C_v1_ParameterListType_MetaInfo = 1¶

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.

fluxEngine_C_v1_ParameterListType_Status = 2¶

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.

Return

0 on success, -1 on failure

Parameters

device: The device
type: The type of parameter list to get
parameter_info: 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: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

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.

Return

0 on success, -1 on failure

Parameters

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

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.

Return

0 on success, -1 on failure

Parameters

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

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.

Return

0 on success, -1 on failure

Parameters

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

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.

Return

0 on success, -1 on failure

Parameters

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

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.

Return

0 on success, -1 on failure

Parameters

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

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.

Return

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

Parameters

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

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.

Return

0 on success, -1 on failure

Parameters

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

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.

Return

0 on success, -1 on failure

Parameters

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

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.

Return

0 on success, -1 on failure

Parameters

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

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.

Return

0 on success, -1 on failure

Parameters

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

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.

Return

0 on success, -1 on failure

Parameters

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

enum fluxEngine_C_v1_LightControlDeviceStatus¶

Light control device status.

Values:

fluxEngine_C_v1_LightControlDeviceStatus_Invalid = -3¶

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.

fluxEngine_C_v1_LightControlDeviceStatus_IrrecoverableError = -2¶

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.

fluxEngine_C_v1_LightControlDeviceStatus_RecoverableError = -1¶

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.

fluxEngine_C_v1_LightControlDeviceStatus_Off = 0¶

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.

fluxEngine_C_v1_LightControlDeviceStatus_Parametrized = 1¶

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.

fluxEngine_C_v1_LightControlDeviceStatus_ForcedOff = 2¶

The light has been forced off.

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

fluxEngine_C_v1_LightControlDeviceStatus_ForcedRamp = 3¶

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.

Return

0 on success, -1 on failure

Parameters

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

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:

fluxEngine_C_v1_LightControlDeviceForceState_None = 0¶

The device should be parametrized.

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

fluxEngine_C_v1_LightControlDeviceForceState_Off = 1¶

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.

fluxEngine_C_v1_LightControlDeviceForceState_Ramp = 2¶

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.

Return

0 on success, -1 on failure

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: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

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.

Return

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

Parameters

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

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: fluxEngine_C_v1_expandedDataType()

Values:

fluxEngine_C_v1_BufferScalarType_Unsupported = -1¶

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.

fluxEngine_C_v1_BufferScalarType_UInt8 = 0¶: 8bit unsigned integer

fluxEngine_C_v1_BufferScalarType_UInt16 = 1¶: 16bit unsigned integer

fluxEngine_C_v1_BufferScalarType_UInt32 = 2¶: 32bit unsigned integer

fluxEngine_C_v1_BufferScalarType_UInt64 = 3¶: 64bit unsigned integer

fluxEngine_C_v1_BufferScalarType_Int8 = 4¶: 8bit signed integer

fluxEngine_C_v1_BufferScalarType_Int16 = 5¶: 16bit signed integer

fluxEngine_C_v1_BufferScalarType_Int32 = 6¶: 32bit signed integer

fluxEngine_C_v1_BufferScalarType_Int64 = 7¶: 64bit signed integer

fluxEngine_C_v1_BufferScalarType_Float32 = 10¶: 32bit IEEE 754 single-precision floating point number

fluxEngine_C_v1_BufferScalarType_Float64 = 11¶: 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.)

Return

The processing data type that the buffer type can be expanded into

Parameters

type: The buffer scalar type to expand

enum fluxEngine_C_v1_InstrumentDeviceStatus¶

Instrument device status.

Values:

fluxEngine_C_v1_InstrumentDeviceStatus_Invalid = -3¶

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.

fluxEngine_C_v1_InstrumentDeviceStatus_IrrecoverableError = -2¶

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.

fluxEngine_C_v1_InstrumentDeviceStatus_RecoverableError = -1¶

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.

fluxEngine_C_v1_InstrumentDeviceStatus_Idle = 0¶

The instrument is idle.

The instrument is idle and not returning data.

fluxEngine_C_v1_InstrumentDeviceStatus_Busy = 1¶

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

fluxEngine_C_v1_InstrumentDeviceStatus_Streaming = 2¶

The instrument is streaming data.

The instrument is streaming data to the user.

fluxEngine_C_v1_InstrumentDeviceStatus_ForcedStop = 3¶

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.

Return

0 on success, -1 on failure

Parameters

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

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.

Return

0 on success, -1 on failure

Parameters

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

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.

Return

0 on success, -1 on failure

Parameters

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

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.

Return

0 on success, -1 on failure

Parameters

device: The instrument device
dimensions: 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: The tensor order of the buffer. For cameras this will typically be 2, for spectrometers 1.
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

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.

Return

0 on success, -1 on failure

Parameters

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

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.

Return

0 on success, -1 on failure

Parameters

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

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.

Return

0 on success, -1 on failure

Parameters

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

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.

Return

0 on success, -1 on failure

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: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

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.

Return

0 on success, -1 on failure

Parameters

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

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.

Return

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

Parameters

device: The instrument device
buffer_info: 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: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

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

Return

true if an abort has been requested in the mean time, false otherwise

Parameters

context: A user-provided context that will be passed to this callback

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.

Return

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

Parameters

device: The instrument device
buffer_info: 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: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

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.

Return

0 on success, -1 on failure

Parameters

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

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.

Return

0 on success, -1 on failure

Parameters

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

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.

Return

0 on success, -1 on failure

Parameters

buffer_info: The buffer
dimensions: An array of 5 64bit integers where the dimensions of the buffer are stored; only the first order dimensions are relevant.
strides: 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: The order of the raw data in the buffer. For cameras this is 2, for spectrometers this is 1.
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

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.

Return

0 on success, -1 on failure

Parameters

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

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.

Return

0 on success, -1 on failure

Parameters

buffer_info: The buffer
data: 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: The minimal number of bytes required to create a copy of the buffer with the same stride structure in another part of memory
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

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.

Return

0 on success, -1 on failure

Parameters

buffer_info: The buffer
buffer: 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: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

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.

Return

0 on success, -1 on failure

Parameters

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

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.

Return

0 on success, -1 on failure

Parameters

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

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.

Return

0 on success, -1 on failure

Parameters

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

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.

Return

0 on success, -1 on failure

Parameters

persistent_buffer_info: The persistent buffer
dimensions: An array of 5 64bit integers where the dimensions of the buffer are stored; only the first order dimensions are relevant.
strides: 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: The order of the raw data in the buffer. For cameras this is 2, for spectrometers this is 1.
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

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.

Return

0 on success, -1 on failure

Parameters

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

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.

Return

0 on success, -1 on failure

Parameters

persistent_buffer_info: The persistent buffer
data: 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: The minimal number of bytes required to create a copy of the buffer with the same stride structure in another part of memory
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

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.

Return

0 on success, -1 on failure

Parameters

persistent_buffer_info: The persistent buffer
buffer: 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: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

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.

Return

0 on success, -1 on failure

Parameters

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

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.

Return

0 on success, -1 on failure

Parameters

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

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.

Return

0 on success, -1 on failure

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: The newly created buffer container, which must be freed via fluxEngine_C_v1_BufferContainer_free().
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_BufferContainer_get_count(fluxEngine_C_v1_BufferContainer *buffer_container, size_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.

Return

0 on success, -1 on failure

Parameters

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

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.

Return

0 on success, -1 on failure

Parameters

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

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.

Return

0 on success, -1 on failure

Parameters

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

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.

Return

0 on success, -1 on failure

Parameters

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

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.

Return

0 on success, -1 on failure

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: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

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.

Return

0 on success, -1 on failure

Parameters

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

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.

Return

0 on success, -1 on failure

Parameters

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

int fluxEngine_C_v1_BufferContainer_copy_single_data(fluxEngine_C_v1_BufferContainer *buffer_container, size_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.

Return

0 on success, -1 on failure

Parameters

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

int fluxEngine_C_v1_BufferContainer_copy_buffer(fluxEngine_C_v1_BufferContainer *buffer_container, size_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.

Return

0 on success, -1 on failure

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: The new persistent buffer
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

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

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

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

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

Return

0 on success, -1 on failure

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: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

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

Instrument Data Standardization And Processing¶

int fluxEngine_C_v1_ProcessingContext_create_instrument_preview(fluxEngine_C_v1_Device *device, fluxEngine_C_v1_ProcessingContext **context, fluxEngine_C_v1_Error **error)¶

Create a processing context for previewing instrument data.

When processing data from an instrument the raw buffer data will often not be in a form that is very useful to perform processing with. For example, PushBroom HSI cameras can have multiple different orientations for the spectrograph, making it camera-depenent how the data is to be interpreted. Furthermore some cameras may return data in a packed buffer scalar type (see fluxEngine_C_v1_BufferScalarType for further details) that may not be easily interpretable by the user.

When recording data, or using data for processing in a model, a set of preprocessing steps will be taken automatically to ensure that the data is normalized. These steps may carry some expenses though, and if the user simply wants to obtain a data to display as a preview, it might be useful.

Instrument drivers that don’t provide information about how to perform the minimally necessary normalization steps will fall back on the preprocessing steps required for data recording here, with some default settings, such as no wavelength normalization.

The normalized data of the resulting processing context can be obtained by querying the output sink with index 0. (There is no actual output sink with that index, as the processing context does not have an associated model, but the result of the preprocessing steps will be returned in this manner.)

How the data is normalized will depend on the type of instrument:

For a spectrometer this will result in a single vector of intensities. (Tensor of order 1.)
For a HSI PushBroom camera this will result in a tensor of order 3, with the first dimension always being 1 (because the y direction only has a single entry), the second dimension being the spatial dimension, and the final dimension being the spectral dimension, regardless of spectrograph orientation.
For HSI imager cameras this will result in a tensor of order 3, with the first dimension corresponding to the y dimension, the second to the x dimension, and the third to the spectral dimension, regardless of how the cube has been obtained by the camera (mosaic pattern, filter wheel, etc.).
For a monochrome polarization camera this will result in a tensor of order 3, with the first dimension corresponding to the y dimension, the second to the x dimension, and the third to the various polarization directions for that camera, regardless of the exact construction (mosaic imager, beam-split multi-camera with various polarization filters, etc.).

Note that corrections might not have been applied to the data at this point. For example, the spectral dimension of a HSI camera (be it PushBroom or imager) may not correspond to actual physical wavelengths yet. Also, any software-based post-processing, such as software binning, has not been applied to this data.

Data must be supplied to this processing context via either the fluxEngine_C_v1_ProcessingContext_set_source_data_buffer() method or the fluxEngine_C_v1_ProcessingContext_set_source_data_persistent_buffer() method.

Return

0 on success, -1 on failure

Parameters

device: The instrument device
context: The preview processing context
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

struct fluxEngine_C_v1_ProcessingContext_ReferenceMeasurement¶

Resulting Reference Measurement (Recording Processing Contexts)

This structure describes a reference measurement result in a normalized form (for HSI cameras this would be in form of a HSI cube, for example) that was obtained while creating a recording processing context. It will be stored within a fluxEngine_C_v1_ProcessingContext_HSIRecordingResult structure to return the normalized references that can be used in conjunction with the data the user records. (These could be used to later initialize an offline processing context.)

When data in referenced form (no intensities) is requested, no reference measurements will be returned while creating such a recording context.

Regardless of whether the user uses these structures, they must free them via the fluxEngine_C_v1_ProcessingContext_ReferenceMeasurement_free() function.

See: fluxEngine_C_v1_ProcessingContext_create_instrument_hsi_recording
See: fluxEngine_C_v1_ProcessingContext_create_instrument_hsi_recording_ex

Public Members

void const *data¶: A pointer to the normalized reference data.

fluxEngine_C_v1_DataType data_type¶

The scalar type of the reference data.

This will be the same scalar type as the recording result.

int order¶

The tensor order of the reference data.

This will be 3 for all current types of HSI cameras, resulting in a HSI cube in BIP storage order. (y, x, wavelengths)

For spectrometers this will be 1 (the dimension for the wavelengths).

int64_t dimensions[5]¶

The dimensions of the tensor.

Only the first order dimensions will contain valid values. The user must ignore other values in this array and must not rely on them.

int64_t strides[5]¶

The strides of the tensor.

Only the first order strides will contain valid values. The user must ignore other values in this array and must not rely on them.

void fluxEngine_C_v1_ProcessingContext_ReferenceMeasurement_free(fluxEngine_C_v1_ProcessingContext_ReferenceMeasurement *measurement)¶

Free a reference measurement.

This frees a reference measurement that was returned by either fluxEngine_C_v1_ProcessingContext_create_instrument_hsi_recording() or fluxEngine_C_v1_ProcessingContext_create_instrument_hsi_recording_ex() in their result parameter.

Parameters

measurement: The measurement to free

struct fluxEngine_C_v1_ProcessingContext_HSIRecordingResult¶

HSI Recording result.

This structure is the return value of the methods that create processing contexts for recording HSI data from a camera. It contains the resulting processing context, as well as further information describing the recording:

The wavelengths of the normalized data that is being returned.
If intensity data is requested, and references where specified during the creation of the processing context, the normalized reference data will also be returned. (Most notably a white reference cube will be present.)

The additional data that is returned in this structure must be freed in addition to the processing context, even if it is not being used.

Important: before supplying this structure to the functions that create the recording processing contexts, the structure_size parameter must be initialized with the current size of this structure. All other members of the structure will be overwritten upon a successful call to the context creation functions. The user must not access or free any data in this structure in case the context creation function fails.

Public Members

size_t structure_size¶

The size of the structure.

Must be set to sizeof(fluxEngine_C_v1_ProcessingContext_HSIRecordingResult) by the user.

fluxEngine_C_v1_ProcessingContext *context¶

The resulting processing context.

The context must be freed by the user via the fluxEngine_C_v1_ProcessingContext_destroy() function after it is no longer required.

double *wavelengths¶

The list of wavelengths of the recorded data.

This contains the wavelengths associated with the last dimension of the data being recorded. It must be freed via the fluxEngine_C_v1_wavelengths_free() function.

int wavelength_count¶

The number of wavelengths.

This will be identical to the size of the last dimension of the only output sink in the processing context.

fluxEngine_C_v1_ProcessingContext_ReferenceMeasurement *white_reference¶

Normalized white reference.

If a white reference was supplied during the creation of a recording processing context, and the user has requested intensity data, this will contain the normalized white reference that the user may save in addition to the data they will record.

The user must always free this via the fluxEngine_C_v1_ProcessingContext_ReferenceMeasurement_free() function after this structure has been returned.

fluxEngine_C_v1_ProcessingContext_ReferenceMeasurement *dark_reference¶

Normalized dark reference.

If a dark reference was supplied during the creation of a recording processing context, and the user has requested intensity data, this will contain the normalized dark reference that the user may save in addition to the data they will record.

The user must always free this via the fluxEngine_C_v1_ProcessingContext_ReferenceMeasurement_free() function after this structure has been returned.

struct fluxEngine_C_v1_ProcessingContext_InstrumentParameters¶

Instrument parameters.

This structure describes common instrument parameters that may be supplied while creating a processing context for recording instrument data or processing it via a fluxEngine/fluxRuntime model.

Currently this exists to allow the user to supply a previously measured white and dark reference measurement.

This structure allows the user to supply the references in form of fluxEngine_C_v1_BufferContainer objects. There is also a second structure, fluxEngine_C_v1_ProcessingContext_InstrumentParametersEx, that allows the user to specify the references as raw data directly.

Important: the user must initialize the structure entirely with zero bytes and thereafter set the structure_size member to the size of this structure. Only then may they set the rest of the structure members as they desire. This exists for allowing future versions of fluxEngine to expand the possible values of this structure, while maintaining both source and binary compatibility.

Public Members

size_t structure_size¶

The size of the structure.

Must be set to sizeof(fluxEngine_C_v1_ProcessingContext_InstrumentParameters) by the user.

fluxEngine_C_v1_BufferContainer *white_reference_buffer¶

The white reference buffer.

Supply NULL here to indicate that no white reference is present.

fluxEngine_C_v1_BufferContainer *dark_reference_buffer¶

The dark reference buffer.

Supply NULL here to indicate that no dark reference is present.

Note that in the absence of a white reference a dark reference is currently ignored. (This may change in later versions of fluxEngine.)

struct fluxEngine_C_v1_ProcessingContext_InstrumentParametersEx¶

Instrument parameters (explicit version)

This structure describes common instrument parameters that may be supplied while creating a processing context for recording instrument data or processing it via a fluxEngine/fluxRuntime model.

Currently this exists to allow the user to supply a previously measured white and dark reference measurement.

This structure allows the user to supply the references in form of raw data. The data must have the same buffer scalar type as buffers the instrument currently returns. The dimensions must be of the form (N, dims...), where N is the number of reference measurements, and dims... are the exact same dimensions as the instrument currently returns while providing a buffer.

Important: the user must initialize the structure entirely with zero bytes and thereafter set the structure_size member to the size of this structure. Only then may they set the rest of the structure members as they desire. This exists for allowing future versions of fluxEngine to expand the possible values of this structure, while maintaining both source and binary compatibility.

Public Members

size_t structure_size¶

The size of the structure.

Must be set to sizeof(fluxEngine_C_v1_ProcessingContext_InstrumentParametersEx) by the user.

int reference_order¶

The order of the reference tensors.

This must be exactly one more than the order of the buffer that the device returns.

If no references are set at all (both the white_reference and dark_reference fields are NULL), this may be 0 instead.

void const *white_reference¶

The white reference data.

A pointer to the start of the raw data containing the white reference.

If no white reference is provided by the user, this must be set to NULL.

int64_t white_reference_dimensions[5]¶

The dimensions of the white reference.

Only the first reference_order entries will be considered.

If no white reference is provided by the user (the white_reference field is set to NULL), the values here will be ignored completely.

int64_t white_reference_strides[5]¶

The strides of the white reference.

Only the first reference_order entries will be considered.

If no white reference is provided by the user (the white_reference field is set to NULL), the values here will be ignored completely.

void const *dark_reference¶

The dark reference data.

A pointer to the start of the raw data containing the dark reference.

If no dark reference is provided by the user, this must be set to NULL.

int64_t dark_reference_dimensions[5]¶

The dimensions of the dark reference.

Only the first reference_order entries will be considered.

If no dark reference is provided by the user (the dark_reference field is set to NULL), the values here will be ignored completely.

int64_t dark_reference_strides[5]¶

The strides of the dark reference.

Only the first reference_order entries will be considered.

If no dark reference is provided by the user (the dark_reference field is set to NULL), the values here will be ignored completely.

int fluxEngine_C_v1_ProcessingContext_create_instrument_hsi_recording(fluxEngine_C_v1_Device *device, fluxEngine_C_v1_ValueType valueType, fluxEngine_C_v1_ProcessingContext_InstrumentParameters const *instrument_parameters, double const *wavelength_grid, size_t wavelength_count, fluxEngine_C_v1_ProcessingContext_HSIRecordingResult *result, fluxEngine_C_v1_Error **error)¶

Create a processing context (HSI and spectrometer data recording)

Creates a processing context that may be used to record HSI from an instrument, this includes spectrometers.

Processing contexts of this type may be used to record data from a spectrometer or HSI camera.

The user may request normalization to a regularized wavelength grid (see the wavelength_grid and wavelength_count parameters), otherwise the instrument’s raw wavelengths will be returned. For example, a HSI camera that has a typical spectral range from 400 to 1000 nanometers might actually have wavelengths of the form 400.21, 402.35, etc. If a regularized wavelength grid is specified, all values will be interpolated before the data is returned to the user.

If a wavelength grid is provided, the wavelengths member of the result parameter will contain the user-requested wavelength grid. If no wavelength grid is provided (the parameter set to NULL) the wavelengths member of the result parameter will contain the unregularized wavelengths of the instrument device itself.

The user may optionally provide a white and dark reference to reference the data or normalize the references to be stored next to the intesnsity data. This method accepts a structure that contains pointers to fluxEngine_C_v1_BufferContainer objects that contain the actual raw reference data. There is also fluxEngine_C_v1_ProcessingContext_create_instrument_hsi_recording_ex(), which supports reference data provided by the user.

The user must specify what value type they want the data in. The following options exist:

The user requests data in intensities (using the fluxEngine_C_v1_ValueType_Intensity value type), and provides no white reference: the data will be provided in intensities and the user can only store the intensity data.

In case of instruments that can only return pre-referenced data (such as virtual devices that return reflectances, or devices that perform the referencing already in hardware) attempting to create such a context will result in an error.
The user requests data in intensities (using the fluxEngine_C_v1_ValueType_Intensity value type), but nevertheless provides a white reference: the recording data itself will still be in intensities, but a normalized white reference will be returned that may be saved next to the measurement data.

In case of instruments that can only return pre-referenced data (such as virtual devices that return reflectances, or devices that perform the referencing already in hardware) attempting to create such a context will result in an error.
The user requests data in reflectances or absorbances, but provides no white reference: if the instrument returns pre-referenced data (such as virtual devices that return reflectances, or devices that perform the referencing already in hardware) this will succeed. If the device only provides its data in intensities (most devices), but no white reference is provided, context creation will fail.
The user requests data in reflectances or absorbances, and provides a white reference measurement: the data returned by the processing context will be of the value type the user selected, and referencing will occur before the data is returned to the user.

The normalized data of the resulting processing context can be obtained by querying the output sink with index 0. (There is no actual output sink with that index, as the processing context does not have an associated model, but the result of the preprocessing steps will be returned in this manner.)

How the data is normalized will depend on the type of instrument:

For a spectrometer this will result in a single vector of intensities. (Tensor of order 1.)
For a HSI PushBroom camera this will result in a tensor of order 3, with the first dimension always being 1 (because the y direction only has a single entry), the second dimension being the spatial dimension, and the final dimension being the spectral dimension, regardless of spectrograph orientation.
For HSI imager cameras this will result in a tensor of order 3, with the first dimension corresponding to the y dimension, the second to the x dimension, and the third to the spectral dimension, regardless of how the cube has been obtained by the camera (mosaic pattern, filter wheel, etc.).

Data must be supplied to this processing context via either the fluxEngine_C_v1_ProcessingContext_set_source_data_buffer() method or the fluxEngine_C_v1_ProcessingContext_set_source_data_persistent_buffer() method.

Note that the instrument_parameters and result structures must be allocated by the user (for example on the stack) and the structure_size field must be initialized with the size of the respective structure.

Memory management: all information passed by the user to this function in the instrument_parameters and wavelength_grid parameters will only be accessed while this function is active; any required information is copied into the resulting processing context upon its creation. The use is free to release the memory associated with these parameters after the call to this method has completed.

The processing context only uses the device parameter to obtain the required information to create the context; the context is independent of the device. However, it will be associated with the fluxEngine handle of the device, and it will require that the data provided will be in the format that device currently produces. This means that reconnecting to the same device and setting the same settings allows the user to reuse the processing context. Also, if the data returned by the device is structurally the same (because it has the same buffer dimensions), but does not match the context semantically for example the user selecting a different ROI in the spectral dimension, but of the same size, the context will still process the data, even though the result will not be sensible.

Note that the user must free all allocated fields in the result structure if this function is successful, even if they choose not to use all of them. See the documentation fo the fluxEngine_C_v1_ProcessingContext_InstrumentParameters type for further details. (If the function is not successful the contents of the result parameter should not be used at all by the user.)

See

fluxEngine_C_v1_ProcessingContext_create_instrument_hsi_recording_ex()

Return

0 on success, -1 on failure

Parameters

device: The instrument device
valueType: The requested value type of the data that is to be returned.
instrument_parameters: The instrument parameters, mainly the previously measured reference data. The structure must be initialized with zeros, then the structure_size field must be set to the size of the structure, before providing this structure to this function.
wavelength_grid: Optional: a list of wavelengths to regularize the wavelengths to. Supply NULL in case the wavelengths of the instrument are to be used and the data should not normalized in this manner.
wavelength_count: The number of wavelengths stored in the wavelength_grid parameter. The value here will be ignored if that parameter is set to NULL.
result: Where to store the result in. The structure should be initialized with zeros before passing it to this function, but for the structure_size field, which must have been set by the user to the size of the structure.
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ProcessingContext_create_instrument_hsi_recording_ex(fluxEngine_C_v1_Device *device, fluxEngine_C_v1_ValueType valueType, fluxEngine_C_v1_ProcessingContext_InstrumentParametersEx const *instrument_parameters, double const *wavelength_grid, size_t wavelength_count, fluxEngine_C_v1_ProcessingContext_HSIRecordingResult *result, fluxEngine_C_v1_Error **error)¶

Create a processing context (HSI and spectrometer data recording)

Creates a processing context that may be used to record HSI from an instrument, this includes spectrometers.

Processing contexts of this type may be used to record data from a spectrometer or HSI camera.

The user may request normalization to a regularized wavelength grid (see the wavelength_grid and wavelength_count parameters), otherwise the instrument’s raw wavelengths will be returned. For example, a HSI camera that has a typical spectral range from 400 to 1000 nanometers might actually have wavelengths of the form 400.21, 402.35, etc. If a regularized wavelength grid is specified, all values will be interpolated before the data is returned to the user.

If a wavelength grid is provided, the wavelengths member of the result parameter will contain the user-requested wavelength grid. If no wavelength grid is provided (the parameter set to NULL) the wavelengths member of the result parameter will contain the unregularized wavelengths of the instrument device itself.

The user may optionally provide a white and dark reference to reference the data or normalize the references to be stored next to the intesnsity data. This method accepts a structure that the user can fill with pointers to the raw data of the measured references. There is also fluxEngine_C_v1_ProcessingContext_create_instrument_hsi_recording(), which supports reference data in form of fluxEngine_C_v1_BufferContainer objects.

The user must specify what value type they want the data in. The following options exist:

The user requests data in intensities (using the fluxEngine_C_v1_ValueType_Intensity value type), and provides no white reference: the data will be provided in intensities and the user can only store the intensity data.

In case of instruments that can only return pre-referenced data (such as virtual devices that return reflectances, or devices that perform the referencing already in hardware) attempting to create such a context will result in an error.
The user requests data in intensities (using the fluxEngine_C_v1_ValueType_Intensity value type), but nevertheless provides a white reference: the recording data itself will still be in intensities, but a normalized white reference will be returned that may be saved next to the measurement data.

In case of instruments that can only return pre-referenced data (such as virtual devices that return reflectances, or devices that perform the referencing already in hardware) attempting to create such a context will result in an error.
The user requests data in reflectances or absorbances, but provides no white reference: if the instrument returns pre-referenced data (such as virtual devices that return reflectances, or devices that perform the referencing already in hardware) this will succeed. If the device only provides its data in intensities (most devices), but no white reference is provided, context creation will fail.
The user requests data in reflectances or absorbances, and provides a white reference measurement: the data returned by the processing context will be of the value type the user selected, and referencing will occur before the data is returned to the user.

The normalized data of the resulting processing context can be obtained by querying the output sink with index 0. (There is no actual output sink with that index, as the processing context does not have an associated model, but the result of the preprocessing steps will be returned in this manner.)

How the data is normalized will depend on the type of instrument:

For a spectrometer this will result in a single vector of intensities. (Tensor of order 1.)
For a HSI PushBroom camera this will result in a tensor of order 3, with the first dimension always being 1 (because the y direction only has a single entry), the second dimension being the spatial dimension, and the final dimension being the spectral dimension, regardless of spectrograph orientation.
For HSI imager cameras this will result in a tensor of order 3, with the first dimension corresponding to the y dimension, the second to the x dimension, and the third to the spectral dimension, regardless of how the cube has been obtained by the camera (mosaic pattern, filter wheel, etc.).

Data must be supplied to this processing context via either the fluxEngine_C_v1_ProcessingContext_set_source_data_buffer() method or the fluxEngine_C_v1_ProcessingContext_set_source_data_persistent_buffer() method.

Note that the instrument_parameters and result structures must be allocated by the user (for example on the stack) and the structure_size field must be initialized with the size of the respective structure.

Memory management: all information passed by the user to this function in the instrument_parameters and wavelength_grid parameters will only be accessed while this function is active; any required information is copied into the resulting processing context upon its creation. The use is free to release the memory associated with these parameters after the call to this method has completed.

The processing context only uses the device parameter to obtain the required information to create the context; the context is independent of the device. However, it will be associated with the fluxEngine handle of the device, and it will require that the data provided will be in the format that device currently produces. This means that reconnecting to the same device and setting the same settings allows the user to reuse the processing context. Also, if the data returned by the device is structurally the same (because it has the same buffer dimensions), but does not match the context semantically for example the user selecting a different ROI in the spectral dimension, but of the same size, the context will still process the data, even though the result will not be sensible.

Note that the user must free all allocated fields in the result structure if this function is successful, even if they choose not to use all of them. See the documentation fo the fluxEngine_C_v1_ProcessingContext_InstrumentParametersEx type for further details. (If the function is not successful the contents of the result parameter should not be used at all by the user.)

See

fluxEngine_C_v1_ProcessingContext_create_instrument_hsi_recording()

Return

0 on success, -1 on failure

Parameters

device: The instrument device
valueType: The requested value type of the data that is to be returned.
instrument_parameters: The instrument parameters, mainly the previously measured reference data. The structure must be initialized with zeros, then the structure_size field must be set to the size of the structure, before providing this structure to this function.
wavelength_grid: Optional: a list of wavelengths to regularize the wavelengths to. Supply NULL in case the wavelengths of the instrument are to be used and the data should not normalized in this manner.
wavelength_count: The number of wavelengths stored in the wavelength_grid parameter. The value here will be ignored if that parameter is set to NULL.
result: Where to store the result in. The structure should be initialized with zeros before passing it to this function, but for the structure_size field, which must have been set by the user to the size of the structure.
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ProcessingContext_create_instrument_processing(fluxEngine_C_v1_Device *device, fluxEngine_C_v1_Model *model, fluxEngine_C_v1_ProcessingContext_InstrumentParameters const *instrument_parameters, fluxEngine_C_v1_ProcessingContext **context, fluxEngine_C_v1_Error **error)¶

Create a processing context (instrument device data processing)

Create a processing context that may be used to directly process data obtained from an instrument with a model.

The model must be of a compatible type to the data returned from the instrument.

The handle associated with the device and the model must be the same.

If the instrument provides data in intensities and the model requires referenced data (the common case) the user must provide a white reference, otherwise context creation will fail.

If the instrument provides data in intensities and the model requires intensity data, any white reference will be ignored.

If the instrument provides pre-referenced data (because it is a virtual instrument returning reflectances, or referencing is performed in hardware) the model must require referenced data (such as reflectances or absorbances), otherwise the context creation will fail.

For HSI cameras and spectrometers: the wavelengths will automatically be regularized onto the grid specified in the model.

This method accepts a structure that contains pointers to fluxEngine_C_v1_BufferContainer objects that contain the actual raw reference data that must be used when the user wants to specify a white reference. There is also fluxEngine_C_v1_ProcessingContext_create_instrument_processing_ex(), which supports reference data provided by the user.

See

fluxEngine_C_v1_ProcessingContext_create_instrument_processing_ex()

Return

0 on success, -1 on failure

Parameters

device: The instrument device
model: The model to process the data with
instrument_parameters: The instrument parameters, mainly the previously measured reference data. The structure must be initialized with zeros, then the structure_size field must be set to the size of the structure, before providing this structure to this function.
context: The resulting processing context.
error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

int fluxEngine_C_v1_ProcessingContext_create_instrument_processing_ex(fluxEngine_C_v1_Device *device, fluxEngine_C_v1_Model *model, fluxEngine_C_v1_ProcessingContext_InstrumentParametersEx const *instrument_parameters, fluxEngine_C_v1_ProcessingContext **context, fluxEngine_C_v1_Error **error)¶