Functions are user-written C routines with parameters that are used as shaders during preprocessing, rendering, and post-processing. Before a function can be defined (by giving its name and listing its parameter values), it must be declared so mental ray knows the complete parameter list the C function accepts, and the data type for each parameter. For a complete list of available shaders, refer to the mental ray manual.
miParameter *mi_api_parameter_decl(
miParam_type type, /* one of miTYPE_* */
char *name, /* parameter name */
int strlength) /* not used */
Declare a parameter or return type of the given type and name.
Before a function itself is declared, a complete description of
the parameters and their types must be built. This function builds
a miParameter structure for a single parameter to be
appended to the list. The parameter type, the parameter
name, and the maximum length of the string if the type is
miTYPE_STRING, must be specified. The string length
includes the trailing null byte. Note, that result parameters of
simple types have no name, thus 0 should be passed
instead for such parameters. Result structures, on the other hand,
do have members with names.
miParameter *mi_api_parameter_append(
miParameter *list, /* list of parameters to append to */
miParameter *parm) /* new parameter */
Append a declared parameter to a list of declared parameters, and return the new list.
Parameter structures created with the previous function must be concatenated to a list with this function. It appends a new parameter parm to an existing list list. The parameter pointer created with the definition of the first parameter, which is also the anchor of the parameter list that will be passed to mi_api_funcdecl_end, can be used as list argument. But it is more efficient to pass the parameter pointer returned by the previously appended parameter.
miBoolean mi_api_parameter_child(
miParameter *parm, /* struct or array to attach to */
miParameter *child) /* new child parameter */
Attach a declared parameter as a child to a struct or array parameter.
Function parameter lists are not necessarily linear lists. Parameters of type miTYPE_STRUCT and miTYPE_ARRAY require a sublist of parameters. Arrays always require a single parameter as subtree, which becomes the type of the array, while structures require a list as subtree that contains one parameter for every member of the structure. The sub-parameter or sub-parameter list child is attached to the array or structure parameter parm with this function.
miFunction_decl *mi_api_funcdecl_begin(
miParameter *outparms, /* result parameters: simple, or struct */
char *name, /* function name */
miParameter *inparms) /* input parameters: none, list, or tree */
Create a new function declaration of the given name with the given input and output parameters.
After the input an output parameter lists have been built the
function itself can be declared using this call. It requires to
pass the anchors to the parameter lists, as well as the function
name which must agree with the name of the C function to be
executed. This call completes the declaration of a function. The
input parameter list inparms may contain arrays and
structures. If the function does not have any input parameters then
inparms should be 0. The result parameter
list outparms is similar to the input parameter list,
but may only be either a simple type or a structure, not an array
or a structure containing structures or arrays. The result
parameter of a simple type does not have a name, i.e. the
name argument in the call to mi_api_parameter_decl to
create outparms was a null pointer. If the result is a
structure, the structure members must be named as usual.
Note, this function is also used to declare structured user data
blocks. In this case, the outparms pointer should be a
0 (see mi_api_data_begin). Because this
function always stores the declaration type miFUNCTION_C,
if a phenomenon or user data block is being declared, the caller
must modify the type field of the returned declaration.
Earlier versions of the API passed a miParam_type instead of a miParameter. This was changed to allow structured return types. For backward compatibility, mi_api_funcdecl_end still accepts miParam_type codes, but since the function prototype changed the compiler will generate an error unless a cast is applied.
miTag mi_api_funcdecl_end(void)
Finish the declaration of the function and return the tag of the new database element.
Copyright © 1986-2010 by mental images GmbH