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.
lock2.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_CONTOUR3.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"
Copyright © 1986-2010 by mental images GmbH