Function Declarations

Element type:	miSCENE_FUNCTION_DECL
Data type:	miFunction_decl
Sizes:	int decl_size
Defaults:	all nulls, type `miFUNCTION_C`

typedef enum {
        miTYPE_BOOLEAN = 0,                     /* simple types: used for */
        miTYPE_INTEGER,                         /* returns and parameters */
        miTYPE_SCALAR,
        miTYPE_STRING,
        miTYPE_COLOR,
        miTYPE_VECTOR,
        miTYPE_TRANSFORM,
        miTYPE_SHADER,                          /* complex types: used for */
        miTYPE_SCALAR_TEX,                      /* parameters only */
        miTYPE_COLOR_TEX,
        miTYPE_VECTOR_TEX,
        miTYPE_LIGHT,
        miTYPE_STRUCT,
        miTYPE_ARRAY,
        miTYPE_TEX,
        miTYPE_MATERIAL,                        /* phenomenon types */
        miTYPE_GEOMETRY,
        miTYPE_LIGHTPROFILE,
        miTYPE_DATA,                            /* free-form user data */ 
        miTYPE_SPECTRUM,                        /* light spectrum as args */
        miNTYPES
} miParam_type;

typedef struct miPhen_decl {
        int             n_subtags;              /* # of subshader/mtl tags */
        miTag           root;                   /* root attachment point */
        miTag           lens;                   /* optional lens shaders */
        miTag           output;                 /* optional output shaders */
        miTag           volume;                 /* optional volume shaders */
        miTag           environment;            /* optional environm. shaders*/
        miTag           geometry;               /* optional geometry shaders */
        miTag           contour_store;          /* opt'l contour store func */
        miTag           contour_contrast;       /* opt'l contour contrast f. */
        int             lens_seqnr;             /* opt'l sequence number */
        int             output_seqnr;           /* opt'l sequence number */
        int             volume_seqnr;           /* opt'l sequence number */
        int             environment_seqnr;      /* opt'l sequence number */
        /* Fuzzy booleans (0=dont care, 1=false, 2=true) */
        miCBoolean      scanline;               /* need scanline? */
        miCBoolean      trace;                  /* need ray tracing? */
        /* Normal Booleans (these cannot be set explicitly off): */
        miCBoolean      deriv1;                 /* need first derivatives? */
        miCBoolean      deriv2;                 /* need second derivatives? */
        miUchar         mintextures;            /* not used */
        miUchar         minbumps;               /* not used */
        miUchar         volume_level;           /* optional volume level */
        miUchar         parallel;               /* parallel output shader */
        char            shadow;                 /* 0, 1, 'l' sort, 's' segm */
        char            face;                   /* 'f'ront, 'b'ack, 'a'll */
        char            render_space;           /* 'c'amera, 'o'bject, 0 any */
        miCBoolean      cloned;                 /* delete decl when del. shd */
} miPhen_decl;

typedef struct miFunction_decl {
        miPointer       sparep[2];
        enum miFunction_type type;              /* C function or phenomenon */
        miParam_type    ret_type;               /* return type of shader */
        int             declaration_size;       /* size of declaration */
        int             result_size;            /* size of result struct */
        int             version;                /* shader version from .mi */
        miUint          apply;                  /* what can it be used for? */
        miPhen_decl     phen;                   /* if type==miFUNCTION_PHEN */
        int             spare[2];               /* not used */
        miTag           defaults;               /* default values or 0 */
        char            name[miNAMESIZE];       /* ascii name */
        char            declaration[4];         /* declaration string */
} miFunction_decl;

#define miDECL_SUBTAG(d,i) (...)

A translator must provide: name, result_size, declaration, version.

A translator may provide: type, ret_type.

Provided by mi_scene_create: parameter_size, declaration_size, parallel, apply.

lock^2.1 is a lock shared by all instances of a shader.

type is one of miFUNCTION_C (shader), miFUNCTION_PHEN (Phenomenon), miFUNCTION_OUTFILE (output file, not a shader), or miFUNCTION_DATA (declaration of a user data block, not a shader).

ret_type is the return type of the function. For backwards compatibility, undefined return types default to miTYPE_COLOR. The type is important for subshaders in shader trees. Only "simple types" are allowed here.

name is an ASCII string identifying the shader. This name will be looked up in LINK's symbol table at runtime.

parameter_size helps the translator decide how many bytes to allocate when a new miFunction entry is allocated, see above. The parameter size does not include space needed for parameter arrays.

declaration_size is the size of the declaration array in bytes, including the trailing null byte.

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.

version is the declaration version. It can be queried by the shader using mi_query and allows the shader to ensure that the declaration and the shader agree. Also, if a shader library contains a function named shadername _version, it is scaled and its returned integer value must match the version. It is highly recommended to use this feature.

apply is a bitmap that specifies what the shader can be used for. Each bit stands for a specific type of shader:

`miAPPLY_LENS`	lens shader in a camera
`miAPPLY_MATERIAL`	material shader in a material
`miAPPLY_LIGHT`	light shader
`miAPPLY_SHADOW`	shadow shader in a material
`miAPPLY_ENVIRONMENT`	environment shader in a material or camera
`miAPPLY_VOLUME`	volume shader in a material or camera
`miAPPLY_TEXTURE`	texture shader
`miAPPLY_PHOTON`	photon shader in a material
`miAPPLY_GEOMETRY`	geometry shader
`miAPPLY_DISPLACE`	displacement shader in a material
`miAPPLY_PHOTON_EMITTER`	photon emitter shader in a light
`miAPPLY_OUTPUT`	output shader in a camera
`miAPPLY_LIGHTMAP`	light map shader in a material
`miAPPLY_PHOTONVOL`	photon volume shader
`miAPPLY_STATE`	state shader
`miAPPLY_CONTOUR`^3.4	contour shader
`miAPPLY_OTHER`	general-purpose shader, such as base shader

If the apply bitmap is zero (the default), it is not known what the shader can be used for, and all uses are legal. mental ray does not currently enforce non-applicability, this is only a hint.

phen is a substructure containing fields used if the type is miFUNCTION_PHEN. The miPhen_decl substructure is still under development. Note that phenomena keep a list of tags of shaders, materials, lights, and other sub-objects defined in the scope of the phenomenon in a tag list that follows the declaration string. Tags in this list can be accessed with the miDECL_SUBTAG macro.

defaults, if nonzero, contains the numerical default shader parameters for this shader. This is simply a tag of a miFunction whose parameters are copied to any new shader miFunction derived from this declaration. Only numerical values but not tags or arrays or array members may have defaults.

declaration describes the parameter layout required by the shader. It is a sequence of ascii characters, each describing a type or structure; the sequence is an abbreviated form of the declaration syntax in the .mi file. The declaration is a list of return and parameter declarations. Each list item begins with an optional 'a' for array, followed by the type (one of biscvtSCVlS$ for boolean, integer, scalar, color, vector, transform, scalar texture, color texture, vector texture, light, shader, and string) followed by a double-quoted name. Substructures are defined with { "name" followed by the structure name followed by the structure definition followed by } . The declaration has two parts separated by an equals sign; the first part declares the return type and the second part declares the parameters. The first part may have only one field that may not be an array and whose double-quoted name part is omitted, but it may be a structure containing named fields. One null byte terminates the entire declaration.

For example, a shader returning a color r and accepting three parameters, a scalar s, an array of structures t containing two integers i1 and i2, followed by a light array l would lead to the following declaration string:

c=s"s"a{"t"i"i1"i"i2"}al"l"

If the return type were a structure containing a color c and a boolean b, the declaration changes to:

{c"c"b"b"}=s"s"a{"t"i"i1"i"i2"}al"l"