Function File Format

Function files are simple text files, holding comments, and definitions of variables, constants, and functions. The transformation for the modifier using the function file can be used to bring the function file in agreement with the world coordinates.

The basic building blocks of a function file are comments and statements.

Comments are enclosed in curly braces {} and may be nested.
Statements consist of a variable or function name, possibly function arguments in parens, an equal sign or colon, an expression, and a semicolon.
An expression can consist of function calls, variables, constants, and operators. The expression syntax is very similar to that of the C programming language.
White space can be used liberally between the elements of statements within expressions.
constants are defined by using a colon instead of an equal sign. The expression of a constant definition may only contain other constants.

Example:


{
    This is a comment, enclosed in curly braces.
	{Comments can be nested.}
}

        { standard expressions use +,-,*,/,^,(,) }
vname = Ny * func(A1);

        { constants are defined with a colon }
const : sqrt(PI/2);

        { user-defined functions can be used in expressions }
func(x) = 5 + A1 * sin(x/3);

        { functions may be passed and recursive }
rfunc(f,x) = if(x,f(x), f(-y) * rfunc(f, x+1));

        { constant functions may also be defined }
cfunc(x) : 10 * x / sqrt(x);

Many variables and functions are already defined by the Radiance, listed here.

A unique context is set up for each file so that the same variable may appear in different function files without conflict. The variables listed above and any others defined in rayinit.cal are available globally. If no file is needed by a given primitive because all the required variables are global, a period "." can be given inplace of the file name. It is also possible to give an expression instead of a straight variable name in a scene file, although such expressions should be kept simple as they cannot contain any white space. Also, functions (requiring parameters) must be given as names and not as expressions.

Constant expressions are used as an optimization in function files. They are replaced wherever theyoccur in an expression by their value. Constant expressions are evaluated only once, so they must not contain any variables or values that can change, such as the ray variables Px and Ny or the primitive argumentfunction arg().

All the math library functions such as sqrt() and cos() have the constant attribute, so they will be replaced by immediate values whenever they are given constant arguments. Thus, the subexpression cos(PI*sqrt(2)) is immediately replaced by its value, -.266255342, and does not cause any additional overhead in the calculation.

It is generally a good idea to define constants and variables before they are referred to in a functionfile. Although evaluation does not take place until later, the interpreter does variable scoping and constant subexpression evaluation based on what it has compiled already. For example, a variable that is defined globally in rayinit.cal, then referenced in the local context of a function file cannot subsequently be redefined in the same file because the compiler has already determined the scope of the referenced variable asglobal. To avoid such conflicts, one can state the scope of a variable explicitly by preceding the variable name with a context mark (a backquote) for a local variable, or following the name with a context mark for a global variable.

Note that Rayfront will "ignore" variables and functions that have a backquote in their name. Such variables are considered private to the function file.

Navigation:

Rayfront 1.0 User Manual