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, 2015 NVIDIA ARC GmbH. All rights reserved.