Models

Model

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.

Model_load_memory

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

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 – [out] The resulting model

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

Returns:

0 on success, -1 on failure

Model_load_file

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

Parameters:

  • handle – The fluxEngine handle for which to create the model

  • model_file_name – The name of the model to load

  • model – [out] The resulting model

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

Returns:

0 on success, -1 on failure

Model_load_file_w

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.

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.

Note

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

Parameters:

  • handle – The fluxEngine handle for which to create the model

  • model_file_name – The name of the model to load

  • model – [out] The resulting model

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

Returns:

0 on success, -1 on failure

Model_num_groups

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

Parameters:

  • model – The model to introspect

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

Returns:

The number of groups on success, -1 on failure

Model_get_group_info

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

Parameters:

  • model – The model to introspect

  • group_id – The group to obtain the information for

  • name – [out] The name of the group will be stored here. The user must free the returned string using fluxEngine_C_v1_string_free().

  • color – [out] The selected color of the group will be stored here.

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

Returns:

0 on success, -1 on failure

Model_destroy

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