The mechanism for defining a new function is very much like the ones for custom nodes and overlays, but much simpler. The function is defined via a structure which looks like this:
static RPI_ExpressionInfo exinfo = { { "cube", // function name "", // not used "Grail", // author "1.0", // version NULL, // not used NULL // not used }; InitFunction, // called on initialization ShutDown, // called on exit ApplyFunction, // define the function here const char *HelpString, // help string shown to user 1, // minimum number of arguments 1 // maximum number of arguments };This structure is defined in CPI/CPI_ExpressionProvider.h
Let's look at each of the fields in this structure:
Function Name - This is the name of the function as used by the RAYZ animator. In the example, the function is called cube, and will be referenced as cube( x ).
Author - Any text string.
Version - This is not currently used by RAYZ, but is available for the programmer.
Init - Called once, when RAYZ is started up. This can be used to build lookup tables, for example.
Shut Down - Called once, when RAYZ exits.
Function - This defines the action of the function. The syntax is:
CPI_Bool function( const CPI_Float32 args[], CPI_Uint32 numArgs, CPI_Float32 *result )where
If there is an error, for example if an argument is negative when that is not allowed by the function definition, then
cpiError("errorstring")can be called, and CPI_FALSE returned by the function.
Help String - A string used to prompt the user for correct usage of the function.
Min Args/Max Args - The minimum and maximum number of arguments allowed by the function.
A simple example is provided in expressions/Cube.C. This function returns x raised to the 3rd power.