Ikaros Module Functions

This document describes the class Module. This class is used as the base class (superclass) of all IKAROS modules. All the public and protected functions of the class Module are documented below. Most of these functions can be used in derived clases (subclasses).

The member functions of the class Module have been divided into the following categories:

Functions that Should be Overridden in Derived Classes
Managing Inputs and Outputs
Getting Parameters from the IKC File
Notifying the Kernel on Errors
Setting Sizes of Outputs
Miscellaneous Functions

Abstract Functions

Every Ikaros Module should be a derived class of the class Module and should override at least the the Init and Tick functions. Modules that allocate memory should also override the destructor function. Modules where the sizes of the outputs depend in complex ways on the sizes of the inputs or other parameters should override the function SetSizes. If a module needs to allocate resources at start-up it may be necessary to override also the creator function.

The Init function should get the pointers to all input and outputs of a module as well as their sizes. The function is called when the sizes of all inputs and output have been calculated to allow a module to initialize memory for internal module data. This function will usually be overriden in derived classes. The functions GetInputSize() and GetOutputSize() are typically used to get the sizes of inputs and outputs which are used to calculate the required memory for internal structure. (Note that memory for input and output arrays are automatically created and deleted by the kernel).

The Init function should also use the Bind function to bind parameters in the IKC-file to variables in the module. Alternatively, it could use the parameter functions to get values from the IKC-file.

The Tick function does the actual work of the module and should calculate new output values based on its input. This function must be overridden in subclasses and should contain the main code for the module. The function is called once for every iteration (or tick). When the function is called, all inputs have received their new values and the function should calculate the new outputs.

If Init allocated local memory, then it is also necessary to provide a destructor function. This function should deallocate local memory and perform other clean-up tasks that may be required.

If the sizes of outputs should be dynamically calculated and the automatic function of the IKC-format is not sufficient, it is also necessary to include a SetSizes function. This function calculates the desired sizes of outputs based on the inputs that a module receives. See also below.

It is usually not necessary for the creator function to do anything. The exception is when hardraw needs to be initialized before the the sizes of inputs and outputs is calculated during start-up. The creator function can also manually add inputs and outputs to the module and may also get the values of parameters from the IKC file using the parameter functions. However, in most cases, the inputs and outputs should be added in the IKC-file for the module and parameters should be retreived in the Init() function.

How to write a module is further explained in the tutorial.

             Module();
             ˜Module();
virtual void SetSizes();
virtual void Init();
virtual void Tick();

Inputs and Outputs

Add Input and Output

The function AddInput should be called during creation of a module to add inputs to a module. The size of the input is not set explicitly in this call but is calculated later by the kernel. (The string supplied must exist throughout the execution. It is not copied.)

The function AddOutput should be called during creation of a module to add outputs to a module. The size of the output can be set explicitly in this call or can be calculated later by the kernel. If the size is not set, the constant unknown_size is used. This is the default value and need not be passed to the function.

void AddInput(char * name);
void AddOutput(char * name, int size_x=unknown_size, int size_y=1);

Note that these functions should typically not be used. Instead, it is sufficient to declare the inputs and outputs in the IKC-file for the module.

Get Input and Output

GetInputArray gets a pointer to the input array of this module with a certain name. The size of the array is given by GetInputSize(). GetOutputArray gets a pointer to the output array of this module with a certain name. The size of the array is given by GetOutputSize(). GetInputMatrix gets a pointer to the input matrix of this module with a certain name. This is the same data as that received by GetInputData but in the form of a two-dimensional matrix. The sizes of the matrix is given by GetInputSizeX() and GetInputSizeY(). GetOutputMatrix gets a pointer to the output matrix of this module with a certain name. This is the same data as that received by GetOutputData but in the form of a two-dimensional matrix. The sizes of the matrix is given by GetOutputSizeX() and GetOutputSizeY().

float *  GetInputArray(char * name);
float *  GetOutputArray(char * name);
float ** GetInputMatrix(char * name);
float ** GetOutputMatrix(char * name);

Get Sizes of Input or Output

GetInputSize gets the size of an input array (size_x * size_y if two-dimensional) GetInputSizeX gets the horizontal size of an input array. GetInputSizeY gets the vertical size of an input array (1 if one-dimensional). GetOutputSize gets the size of an output array (size_x * size_y if two-dimensional). GetOutputSizeX gets the horizontal size of an output array. GetOutputSizeY gets the vertical size of an output array (1 if one-dimensional).

int GetInputSize(char * input_name);
int GetInputSizeX(char * input_name);
int GetInputSizeY(char * input_name);
int GetOutputSize(char * name);
int GetOutputSizeX(char * name);
int GetOutputSizeY(char * name);

Check if Input or Output is Connected

InputConnected is true if input receives at least one connection. OutputConnected is true if output is connected to at least one module.

bool InputConnected(char * name);
bool OutputConnected(char * name);

Parameters

There are a number of functions to get parameter values from the XML element that describes a module in the IKC file. The simplest way to acces a parameter is through the Bind-function that binds a name in the IKC-file to a module parameter.

void Bind(float & v, const char * n);
void Bind(int & v, const char * n);
void Bind(bool & v, const char * n);

In addition to retreiving the parameter from the IKC-file (or its default if it is not specified), Bind also allows a parameter to be changed during runtime through the WebUI. Make sure that Bind is not used for parameters that should not be changed during execution (such as parameters that influence allocation of memory).

Alternatively, there are a number of Get-functions to access the parameters. GetValues searches for a parameter and return its value as a string or NULL if it is not found. The other parameter functions do essentially the same but also convert the value toa spcific format. GetFloatValue returns a parameter value as a float. A default value d is resykred if the parameter is not found. GetIntValue return a parameter as an int or da efault value d if not found. Also GetBoolValue returns its value as a float or as a default value d if it is not found.

char *   GetValue(char * n);
float    GetFloatValue(char * n, float d=0);
int      GetIntValue(char * n, int d=0);
bool     GetBoolValue(char * n, bool d=false);

If parameter values are given as a string from a list, the value can be converted to an integer wit the function GetIntValueFromList. This function searches through the XML for the parameter and then searches the list for the index of the value. It returns 0 if the value is not found in the list. The allowed values in the string list should be in the form "value0/value1/value2".

int      GetIntValueFromList(char * n, char * list);

For parameters that are arrays or matrices, the two functions GetArray and GetMatrix can be used. If the parameter is not found, these functions creates data structures filled with zeros instead.

float *	 GetArray(char *n, int size);
float ** GetMatrix(char *n, int sizex, int sizey);

Notification

The function Notify is used to send a message to the kernel. The two most common uses of the function is to print a message or to produce an error message. The function takes the same arguments as printf except for an initial msg variable. The result of the notification depends on the value used for the argument msg in the call. The different values are listed below:

const int    msg_fatal_error      =    1;
const int    msg_exception        =    2;
const int    msg_warning          =    3;
const int    msg_print            =    4;
const int    msg_end_of_file      =    5;
const int    msg_terminate        =    6;
const int    msg_verbose          =    7;

The values msg_fatal_error and msg_exception will print the message and terminate execution gracefully. These values are typically used in the creator and Init functions of a module to stop execution if an error occurs that prevents the module from being created or from running.

The value msg_warning write a warning message. This should be used when an error occurs that does not prevent Ikaros from running, but that may cause problems.

To print a message, msg_print is used. This is prefered to using printf:s in the code since the mesage can be streamed to a viewer while printf simply writes to the console.

A module can also use Notify with the values msg_end_of_file or msg_terminate if it wants to terminate execution as a result of a particular event.

FInally, the value msg_verbose is used to only print a message in verbose mode. Note that even if the message will not be printed the overhead of creating the string to the function may slow down execution if this call is used inside a loop.

void Notify(int msg);
void Notify(int msg, char *format, ...);

Setting Sizes

The function SetSizes() should be overridden in derived classes if the output sizes should be calculated dynamically during start-up. It is called during initialization to allow a module to calculate the sizes of output arrays as a function of the sizes of its inputs. Typically, the SetSizes() function calls GetInputSize() to get the sizes that are used to calculate the output sizes. These sizes are then set by SetOutputSize(). If any of the GetInputSize() calls receives the constant unknown_size, the function should return without setting the corresponding output size.

Note that the SetSizes() function may be called several times during start-up until all output sizes have been determined.

The function SetOutputSize sets the output size for an output of unknown size; it is an error to change the output size. The function can be used to set either a one-dimensional or two-dimensional size. The function is usually called from the SetSizes function.

Note that the following two calls have very different meanings:

SetOutputSize("OUTPUT", GetInputSizeX("INPUT"), GetInputSizeY("INPUT"));

SetOutputSize("OUTPUT", GetInputSize("INPUT"));

The first example sets the output OUT to the same two-dimensional size as the input INPUT. The second example sets the size of INPUT to be one-dimensional of the same size as INPUT when it is treated as a one-dimensional array. In most cases, it is the first alternative that should be used.

virtual void  SetSizes();
void          SetOutputSize(char * name, int size_x, int size_y=1);

The function SetSizes() may call the inherited function Module::SetSizes() to automatically calculate sizes for output not set in the function.

Miscellaneous Functions

The function GetName can be used to get the name of the module assigned during creation. Similarily, the function GetClassName retreives the name of the class of the current module. These functions are mainly used for debugging.

char * GetName();
char * GetClassName();