Functions

Element type:	miSCENE_FUNCTION
Data type:	miFunction
Sizes:	int param_size
Defaults:	all nulls

enum miFunction_type {
        miFUNCTION_C,                           /* regular C/C++ shader */
        miFUNCTION_PHEN,                        /* phenomenon interface */
        miFUNCTION_C_REQ,                       /* C/C++ shader with reqmnts */
        miFUNCTION_OUTFILE,                     /* write an image to a file */
        miFUNCTION_DATA,                        /* user data decl, no miFunc */
        miFUNCTION_PASS_SAVE,                   /* write pass file */
        miFUNCTION_PASS_PREP,                   /* pass file preprocessor */
        miFUNCTION_PASS_MERGE,                  /* pass file merge function */
        miFUNCTION_PASS_DELETE,                 /* pass file delete */
        miFUNCTION_HARDWARE                     /* hardware rendering shader */
};

typedef struct miFunction {
        miPointer       sparep1[7];
        enum miFunction_type type;              /* C/C++, phenomenon, or file*/
        miUint          out_typemap;            /* if output, IMG_TYPE bitmap*/
        miUint          out_interpmap;          /* if output, interpolate bm */
        miTag           function_decl;          /* declaration if C or PHEN */
        miTag           next_function;          /* next function call in list*/
        miTag           parameter_indirect;     /* get params from this func */
        miTag           interfacephen;          /* parent phen, if any */
        miBoolean       spare0;                 /* not used */
        int             parameter_size;         /* size of parameter block */
        int             result_size;            /* size of result struct */
        int             ghost_offs;             /* offset to tag ghost, or 0 */
        miTag           pass_read;              /* pass: infile, infile list */
        miTag           pass_write;             /* pass: outfile or 0 */
        miSint1         pass_maxsamples;        /* pass: max samples or ~0 */
        miCBoolean      spare2[3];              /* not used */
        miCBoolean      no_expl_params;         /* candidate for indirect par*/
        miCBoolean      cloned;                 /* is this a clone */
        miCBoolean      spare3[5];              /* not used */
        miUchar         label;                  /* sequential # for bitmasks */
        char            parameters[8];          /* parameter block, then */
                                                /* miTag ghost for phenomena */
} miFunction;

A translator must provide: function_decl (using mi_scene_link), parameter_size (as mi_scene_create argument), result_size, parameters.

A translator may provide: next_function, interfacephen, ghost_offs, no_expl_params, label.

Functions are shading functions are pairs of a function identification (the shader name) and a parameter block. They are used for materials, textures, lights, transformations, and many other purposes.

Most are called during rendering; some are called during preprocessing or tessellation.

user^2.1, cached_address^2.1, cached_result^2.1, cached_ghost_ptr^2.1, gcache_timestamp^2.1, lightlist^2.1, and lock all assumed that preprocessing or shaders could write to the scene DAG, which is not the case in mental ray 3.0 so these fields were retired. The only field of interest to shaders was user, which could be used to store shader user data, typically in init shaders. New shaders must use mi_query in miQ_FUNC_USERPTR mode to access the user pointer.

type is one of the miFUNCTION_* values. Note that some types such as miFUNCTION_OUTFILE do not actually describe procedural functions; using a miFunction here allows convenient chaining of output statements or pass statements in the camera.

out_typemap is a bitmap that contains the image types needed for the function if it is either an output shader or an output file. In the future, this will also be used for pass functions.

out_interpmap is a bitmap that contains the interpolation flags for each bit in the out_typemap bitmap.

function_decl is the declaration of the function, containing both the shader name and a declaration of the parameters it requires. Declaration database elements have type miSCENE_FUNCTION_DECL; see below. miFunctions that do not have procedural functions, such as type miFUNCTION_OUTFILE, have a null tag here.

next_function references the next function in a chain. Some shader types allow chaining; for example there may be multiple lens shaders anchored in the camera that are called in sequence.

parameter_indirect contains the tag of the shader where the parameters should be picked up. It is possible to put a parameterless shadow shader and/or photon shader into a material, that will use the parameters of the material shaders. This avoids redundant parameter lists but creates interdependencies, so it is rarely used.

interfacephen is the tag of the phenomenon that contains the shader. Presently only used internally to cache the phenomenon tag for lens shaders required by a phenomenon. Should not be used by translators.

parameter_size is the size of the shader parameter area in bytes. Shader parameters are stored at the beginning of the parameters array.

result_size is the number of bytes in the result data structure. By default this is 16 (the size of miColor, which is the default return type). It must be set to match the result_size field of the declaration. In mental ray 3.0, it is important to set this field correctly for contour store shaders; this was unnecessary in mental ray 2.1.

ghost_offs is nonzero for phenomenon miFunctions and provides an offset into the parameters array where the tags begin. This value is either zero or the smallest multiple of 4 equal to or greater than parameter_size because tags are integers that must be properly aligned.

pass_read is the tag of a string (type miSCENE_STRING) for pass prep functions attached to the pass chain of the camera; or the tag of a tag list (type miSCENE_TAG) containing string tags followed by a null tag, for pass merge functions. The strings are pass file names. Non-pass functions do not use this field.

pass_write is the tag of a string (type miSCENE_STRING) for pass save, pass prep, and pass delete functions attached to the pass chain of the camera. The strings is a pass file name. Non-pass functions do not use this field.

pass_maxsamples is the max sampling density for the written pass file. The default is \ 0, which uses the rendering max sampling value from the options. This field is not currently used.

no_expl_params is set if the function has no parameters, and should pick up the parameters from parameter_indirect.

cloned is an internal flag used by mental ray to identify functions that were created during preprocessing to construct new shader chains from Phenomenon roots, for example if a Phenomenon adds a lens shader to the camera lens shader list.

label is a number in the range 0 ... 255 that helps distinguishing shaders. A new number is assigned automatically whenever a new function is created, but no attempt is made to keep the numbers unique. This helps the incremental rendering heuristics to decide whether a pixel should be re-rendered.

parameters contains one or two variable-sized data areas: the function parameters, and the optional tag ghost array. A pointer to the parameter block is passed to the shader whenever it is called. The parameters are expected to be laid out as described by the function declaration.

The tag ghost array is used for phenomenon miFunctions. It exists only if ghost_offs is nonzero. It has the same layout as the parameter array, such that there is one tag for every parameter at the same offset in the respective array. If the tag for a parameter is nonzero, the tag points to another miFunction which must be called (unless its cache is valid, in which case the previous result is re-used; see above) to provide the parameter instead of using the parameter directly. In this case the parameter in the parameter array is the offset into the result returned by the call.