Documentation

This page hosts the documentation of the SmartCGMS software architecture and all of its components.

The documentation is being updated to acommodate the recent improvements. Please, be patient, we are working on it...


Configuration

This page deals with support classes and functions in the SmartCGMS SDK. To see, how the SmartCGMS is configured and how to perform batch processing, please, refer to the appropriate API subpage for configuration.

The configuration part of SmartCGMS SDK offers a number of classes, that implement the configuration API interfaces, and serves as a ready-to-use solution when building chain configuration from file or memory. The top-level class is the scgms::SPersistent_Filter_Chain_Configuration, which implements the scgms::IPersistent_Filter_Chain_Configuration. This class (its implementation and storage class) encapsulates the configuration, that is used to build the chain prior the simulation.

Interface implementation

At first, let us take a brief look at the scgms::IPersistent_Filter_Chain_Configuration interface and its (hidden) implementation. The interface defines three main functions for loading the filter chain:

  • Load_From_File - this loads the configuration from file on path, which is passed as a first parameter; errors are stored in a given string container passed as a second argument
  • Load_From_Memory - this loads the configuration from a place in memory indentified by its starting address passed as a first parameter and length passed as a second one; errors are stored in a given string container passed as a third argument
  • Save_To_File - this saves the configuration to a file on path, which is passed as a first parameter; errors are stored in a given string container passed as a second argument

It is very likely, that when using the SmartCGMS SDK, you want to load the configuration by using the first method. An example how to do so follows:

refcnt::Swstr_list errors;

scgms::SPersistent_Filter_Chain_Configuration configuration{};
if (Succeeded(configuration->Load_From_File(L"my_config_file.ini", errors.get()))) {
    // everything loaded and ready
}

// this prints all errors reported by filters, which are not necessarily fatal
// if they would be fatal, the load method above returns a failure code
mErrors.for_each([](const std::wstring& err) {
    std::wcerr << "Error: " << err << std::endl;
});

It may be convenient to load a config file from memory, e.g. when embedding the file with your executable. In this case, the Load_From_Memory can be used instead of file-loading method as follows:

std::string my_config_in_memory = "...";

if (Succeeded(configuration->Load_From_Memory(my_config_in_memory.c_str(), my_config_in_memory.length(), errors.get()))) {
    // everything loaded and ready
}

Additional methods

The scgms::SPersistent_Filter_Chain_Configuration class offers additional methods for you to use:

  • Add_Link - this methods adds a single link at the end of existing filter chain with a given filter GUID; the link is then returned as an instance of scgms::SFilter_Configuration_Link (see below)
  • for_each - this allows you to call a given functor on all links of the filter chain within the given configuration instance
  • operator[] - an array access operator allows you to reference a configuration link at a given index; please note, that this is an index, not a position, and thus starts at 0. This also does not equal the filter position in config file, but is rather an equivalent of coalesced filter positions shifted to 0

Configuration link

The scgms::SFilter_Configuration_Link encapsulates a single configuration link. In other words, it contains all the parameters and their values relevant to a single filter. It is merely an implementation of a interoperable container of configuration parameters. In addition, this class (and its internal hidden parent) offers a set of methods, that allows you to access parameters inside the container:

  • Read_String - reads a string identified by given key
  • Read_File_Path - reads a string identified by given key, but converts it to a filesystem path
  • Read_Int - reads an integer identified by given key
  • Read_Int_Array - reads an array of integers identified by given key
  • Read_GUID - reads a GUID identified by given key
  • Read_Bool - reads a boolean value identified by given key
  • Read_Double - reads a double precision floating point number identified by given key
  • Read_Double_Array - reads an array of double precision floating point numbers identified by given key
  • Read_Parameters - reads a parameter set identified by given key; it could be seen as a wrapper aroung Read_Double_Array, but enhanced with parsing routines to split the set of values into lower bounds, upper bounds and actual parameter values
  • Write_Parameters - stores a parameter set with a given key identifier
Furthermore, it also defines more helper methods (some of them are members of the interface scgms::IFilter_Configuration_Link implemented by internally constructed class):
  • Clone - clones the class instance into a new instance
  • for_each - this allows you to call a given functor on all parameters of a given filter
  • Resolve_Parameter - resolves a single filter parameter link, returns it as an instance of scgms::SFilter_Parameter (see below)
  • Get_Filter_Id - retrieves the configured filter GUID (the target filter)
  • Set_Parent_Path - sets the parent path for resolving relative paths
  • Set_Variable - sets a config variable; this works similarly to retaining the system environment variables, and thus could be resolved in a config file from a $(variable_name) placeholder. An example could be found on an API subpage for configuration

A similar set of methods can be found in scgms::SFilter_Configuration class. The main difference between the former and latter is that the latter is an instance of configuration supplied as a parameter to a constructed filter, while the former exists as a configuration "template" before chain construction.