Section 5 - Adding Custom Functions

Programmers can add their own functions to the RAYZ expression language. These functions can only take numeric values as inputs, and return a numeric result; it is not possible at this time to operate on strings. User functions can be used in any expression for any animatable parameter in RAYZ.

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
args[] is an array of arguments which the user has passed to the functions.
numArgs is the number of arguments in the args[] array
*result is the place where you put the function's return value
The function should return CPI_TRUE if the function was applied correctly.

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.


[Previous Page] [Next Page]
[Table of Contents] [Index]

Copyright © 2002 Silicon Grail Inc.
736 Seward Street, Hollywood, CA 90038