Models

Model

class Model

A runtime model.

This class wraps a runtime model that has been loaded into fluxEngine.

The default constructor does not actually create an object, the user must use one of the other constructors to actually load a model.

Public Functions

Model() = default

Default constructor.

The object created by this constructor is not a valid model.

inline Model(Handle &handle, void const *modelData, std::size_t modelDataSize)

Load a model from memory.

This constructor 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.

If an error occurs, an exception will be thrown. The following exceptions may be thrown by this constructor:

Parameters:

  • handle – The fluxEngine handle. This is required as the loaded license determines whether specific features within a model are allowed

  • modelData – The raw binary data of the model

  • modelDataSize – The raw binary size of the model, in bytes

inline Model(Handle &handle, std::vector<std::byte> const &modelData)

Load a model from memory (convenience wrapper)

If the runtime model binary data is present as a std::vector<std::byte> this convenience wrapper exists to allow the user to use that to load the model.

This wrapper is only available when compiling with a compiler that supports C++17.

See the documentation for the primary constructor for more details.

Parameters:

  • handle – The fluxEngine handle. This is required as the loaded license determines whether specific features within a model are allowed

  • modelData – The raw binary data of the model

inline Model(Handle &handle, FromFile_Tag, std::string fileName)

Load a model from disk.

This contructor allows the user to load a runtime model from a file. Example usage: 

Model model(handle, Model::FromFile, "model.fluxmdl");
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 wide string overload of this constructor 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 constructor will very likely fail.

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.

If an error occurs, an exception will be thrown. The following exceptions may be thrown by this constructor:

Parameters:

  • handle – The fluxEngine handle. This is required as the loaded license determines whether specific features within a model are allowed

  • fileName – The name of the file to load

inline Model(Handle &handle, FromFile_Tag, std::wstring fileName)

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

This contructor is identical to the other constructor that loads a file, but it takes a wide (“Unicode”) filename of Windows systems, to support opening files that can’t be encoded in the local codepage. Example usage: 

Model model(handle, Model::FromFile, L"model.fluxmdl");

Please refer to the documentation of the constructor for standard 8bit filenames 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. This is required as the loaded license determines whether specific features within a model are allowed

  • fileName – The name of the file to load, as a wide (“Unicode”) string

inline Model(Model &&other) noexcept

Move constructor.

Parameters:

other – The model to move into the newly created object

inline Model &operator=(Model &&other) noexcept

Move assginment operator.

Parameters:

other – The model to move into this object

Returns:

A reference to this

inline ~Model()

Destructor.

Destroys a model, freeing its resources.

inline int numGroups() const

Get the number of groups in a model.

If an error occurs, one of the following exceptions may be thrown:

Returns:

The number of groups

inline GroupInfo groupInfo(int groupId) const

Get the group information for a given group.

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. See the GroupInfo structure for further details.

The group id must be within 0 and one less than the number of groups in the model. For example, a model with 5 groups will have the ids 0, 1, 2, 3, and 4.

Another method, groupInfos(), will return a std::vector of all groups in the model.

If an error occurs, one of the following exceptions may be thrown:

Parameters:

groupId – The id of the group to obtain the information about

Returns:

The information about that group

inline std::vector<GroupInfo> groupInfos() const

Get the information about all groups in a model.

This helper function obtains the information about all groups in the current model and returns them as a vector. The index of that vector is the id of the group.

If an error occurs, one of the following exceptions may be thrown:

Returns:

A vector of the information of all groups in the model

inline explicit operator bool() const noexcept

Boolean conversion operator.

This allows the user to easily check if a variable of this type currently holds a valid model. For example: 

if (model) {
    // the model is valid
}

Public Static Attributes

static constexpr FromFile_Tag const FromFile = {}

Tag to differentiate constructors.

This tag allows the user to indicate they want to call a constructor that will load a file from disk.

struct GroupInfo

Group information.

This structure contains the information about a group that is stored within a given runtime model.

Public Functions

inline uint8_t colorRedComponentValue() const noexcept

Obtain the red color component value.

Obtains the red component value of the color of the group, in a range of 0 through 255.

This helper function exists to make interpreting a given color simpler.

Returns:

The red color component value

inline uint8_t colorGreenComponentValue() const noexcept

Obtain the green color component value.

Obtains the green component value of the color of the group, in a range of 0 through 255.

This helper function exists to make interpreting a given color simpler.

Returns:

The green color component value

inline uint8_t colorBlueComponentValue() const noexcept

Obtain the blue color component value.

Obtains the blue component value of the color of the group, in a range of 0 through 255.

This helper function exists to make interpreting a given color simpler.

Returns:

The blue color component value

Public Members

std::string name

The name of the group.

This is encoded as UTF-8.

uint32_t color = {0xff0000u}

The color of the group.

This is encoded in the format 0xffRRGGBB. To obtain the red, green and blue values of the color one may use the helper methods that are part of this structure.