The chapter on the .mi scene description language (page declaration) explains assignment of shaders and phenomenon interface parameters to shader parameters. Assignments replace the constant value of a parameter with a link to a shader that gets called automatically when the shader asks for the value of the parameter, or a link to the phenomenon interface which is looked up, respectively.
Shader assignments simplify the development of small, simple shaders called base shaders that can be combined into larger shaders or phenomena. For example, assignments make it possible to apply a texture to any shader parameter simply by replacing the constant value of a parameter with an assignment to a texture shader. It is no longer necessary for shader writers to anticipate which parameters should be texturable, and adding additional shader parameters of type color texture to the parameter list, just in case.
For example, consider this shader assignment example from page assignex:
declare shader
color "phong" (color "ambient",
color "diffuse",
color "specular",
scalar "shiny")
version 1
end declare
declare shader
struct {color "a", color "b"}
"texture" (color texture "picture")
version 1
end declare
color texture "fluffy" "/tmp/image.rgb"
shader "map" "texture" (
"picture" "fluffy")
shader "mtlsh" "phong" (
"shiny" 50,
"ambient" 0.3 0.3 0.3,
"diffuse" = "map.a",
"specular" = "map.b")
The author of the phong shader can focus on the purpose of the shader (Phong illumination) without having to consider texturing at all. The texture is applied later as a shader assignment to the parameters of phong. This example further illustrates that shaders may have structured return values, in this case in the shader texture which returns both a and b, which can be picked up individually using the dot-member notation.
Frequently, shaders do not access all their parameters. Consider a multiplexing material shader that calls one of two material shaders depending on whether the incident ray hit the front face or the back face of the material. It would be very inefficient to evaluate both material shaders and then choose one of the two returned colors. For this reason, mental ray does not pre-evaluate all assignments before calling a shader. Instead, the shader itself must ask for the value of one of its parameters explicitly. This is done with the mi_eval function. The signature of mi_eval is
void *mi_eval (miState *state,
void *param)
miBoolean *mi_eval_boolean (miBoolean *param)
miInteger *mi_eval_integer (miInteger *param)
miScalar *mi_eval_scalar (miScalar *param)
miVector *mi_eval_vector (miVector *param)
miScalar *mi_eval_transform (miScalar *param)
miColor *mi_eval_color (miColor *param)
miTag *mi_eval_tag (miTag *param)
miSpectrum *mi_eval_spectrum (miSpectrum_para *param)
The typed variants of mi_eval are implemented as macros that perform all necessary typecasting, as a convenience for shader writers. There are three cases handled by mi_eval:
In any case, the end result is that mi_eval returns a pointer to the parameter value, no matter where it comes from. If the shader accessed its parameters directly, without using mi_eval, it would get garbage (such as 0 or NaN) if the parameter is assigned. For arrays, mi_eval must be applied to the array itself, as well as the i_ array and n_ array integers. Once the address of the array has passed through mi_eval, the array pointer is subscripted normally without applying mi_eval to each element. This is a convention; only entire arrays should be assigned to other shaders or to the phenomenon interface if present, but not individual array members.
For example, the phong shader in the example above would be implemented as:
struct phong {
miColor ambient;
miColor diffuse;
miColor specular;
miScalar shiny;
};
int phong_version(void) {return(1);}
miBoolean phong(
miColor *result, /* returned illum color */
miState *state, /* ray tracer state */
struct phong *paras) /* phong parameters */
{
miColor *diffuse; /* final diffuse param */
miColor *specular; /* final specular param */
miScalar shiny; /* phong exponent */
int n, i; /* light counter */
miTag *lights; /* global light list */
miInteger samples; /* # of samples taken */
miColor color; /* color from light */
miColor sum; /* summed sample colors */
miVector dir; /* direction to light */
miScalar dot_nl; /* normal <dot> dir*/
miScalar spec_f; /* specular factor */
*result = *mi_eval_color (¶s->ambient);
diffuse = mi_eval_color (¶s->diffuse);
specular = mi_eval_color (¶s->specular);
shiny = *mi_eval_scalar(¶s->shiny);
mi_query(miQ_NUM_GLOBAL_LIGHTS, state, 0, &n);
mi_query(miQ_GLOBAL_LIGHTS, state, 0, &lights);
for (i=0; i < n; i++) {
sum.r = sum.g = sum.b = 0;
samples = 0;
while (mi_sample_light(&color, &dir, &dot_nl,
state, lights[i],
&samples)) {
spec_f = mi_phong_specular(shiny, state,
&dir);
sum.r += color.r * (dot_nl * diffuse->r +
spec_f * specular->r);
sum.g += color.g * (dot_nl * diffuse->g +
spec_f * specular->g);
sum.b += color.b * (dot_nl * diffuse->b +
spec_f * specular->b);
}
if (samples) {
result->r += sum.r / samples;
result->g += sum.g / samples;
result->b += sum.b / samples;
}
}
result->a = 1;
return(miTRUE);
}
Note that mi_eval_color is called early to obtain pointers to parameters once. If there is a large number of lights, this saves a large number of mi_eval_color calls later. Although mi_eval et al. employ caching and fast lookups, this makes the shader faster than it were if the code were written like this:
dot_nl * mi_eval_color(¶s->diffuse)->r
in the inner loop.
Copyright © 1986-2008 by mental images GmbH