Functions are user-written C routines with parameters that are used as shaders during preprocessing, rendering, and postprocessing. 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 */
Before the 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.
miParameter *mi_api_parameter_append(
miParameter *list, /* list of parameters */
miParameter *parm) /* new parameter */
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 */
miParameter *child) /* str/array to attach */
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 */
char *name, /* function name */
miParameter *inparms) /* parameter list */
After the parameter list (or tree, if arrays and structures are present) has been built, the function itself can be declared. The return parameter, the function name (which must agree with the name of the C function to be executed), and the anchor of the parameter list must be passed. This call completes the declaration of a function.
The result parameter list 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 does not have a name (i.e. the name argument in the call to mi_api_parameter_decl that returned outparms was a null pointer), but if the result parameter is a structure, the structure members must be named as usual. The outparms pointer should be a null pointer if a structured user data block is being declared (see mi_api_data_begin). This function always stores the declaration type miFUNCTION_C, so 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)
After the function declaration is finished, this call finishes the declaration and returns the tag of the new database element.
Copyright © 1986-2008 by mental images GmbH