Functions for Shaders

mental ray makes a range of functions available to shaders that can be used to access data, cast rays, looking up images, and perform standard mathematical computations. The functions are grouped by the module that supplies them. The shader writer may also use C library functions, but it is mandatory to include <</i>stdio.h> and <</i>math.h> if printing functions such as fprintf (use mi_info or similar for console debugging messages) or math functions such as sin are used. Not including these headers may abort rendering at runtime, even though the compiler did not complain. All shaders must include the standard mental ray header file, shader.h.

Here is a summary of functions provided by mental ray. Section functype shows which functions can be used in which shaders.

Shaders can be called either explicitly, or implicitly by evaluating a shader parameter that may be assigned to the output of another shader.

    miBoolean mi_call_shader(
        miColor * const result,
        miShader_type   type,
        miState * const state,
        miTag           shader)

    miBoolean mi_call_shader_x(
        miColor * const result,
        miShader_type   type,
        miState * const state,
        miTag           shader,
        void            *arg)

These functions call the shader specified by the tag shader. The extended version passes the arg parameter as a fourth argument to the shader. The other version passes a null pointer as fourth argument to the shader. mi_call_shader_x is slightly more efficient than mi_call_shader.

The tag is normally a texture shader or light shader or some other type of shader found in the calling shader's parameter list. The caller must pass its own state and the shader type, which must be one of miSHADER_LENS, miSHADER_MATERIAL, miSHADER_LIGHT, miSHADER_SHADOW miSHADER_ENVIRONMENT miSHADER_VOLUME, and miSHADER_TEXTURE. The sequence of operations is:

1. shader is written into .
2. If the called shader is dynamically loaded and has an init shader that has not been called yet, it is called now, with state as its only argument.
3. The shader referenced by shader is called with three arguments: the result pointer, the given state, and the shader parameters retrieved from shader.
4. After the shader returns, is restored to its old value.

The return value of the shader is returned. If the shader expects a result argument of a type other than miColor, the pointer must be cast to miColor when passed to mi_call_shader. Note that the shader tag references an entire function call including shader parameters as defined in the .mi file with a texture, light, or some other statement combining shading function and shader parameters; shader is not just a simple pointer or reference to a C function.

    miBoolean mi_call_material(
        miColor         *result,
        miState         *state);

Call the material shader in . This works both for standard materials and Phenomenon materials.

    miBoolean mi_call_photon_material(
        miColor         *result,
        miState         *state);

Call the photon shader in . This works both for standard materials and Phenomenon materials. It calls the photon shader of a material Phenomenon.

    miBoolean mi_call_shadow_material(
        miColor         *result,
        miState         *state);

^3.3 Call the shadow shader in . This works both for standard materials and Phenomenon materials. It calls the shadow shader of a material Phenomenon.

    miBoolean mi_call_environment_material(
        miColor         *result,
        miState         *state);

^3.3 Call the environment shader in . This works both for standard materials and Phenomenon materials. It calls the environment shader of a material Phenomenon.

    miBoolean mi_call_volume_material(
        miColor         *result,
        miState         *state);

^3.3 Call the volume shader in . This works both for standard materials and Phenomenon materials. It calls the volume shader of a material Phenomenon.

    miBoolean mi_call_photonvol_material(
        miColor         *result,
        miState         *state);

^3.3 Call the photonvol shader in . This works both for standard materials and Phenomenon materials. It calls the photonvol shader of a material Phenomenon.

    miBoolean mi_call_contour_material(
        miContour_endpoint *result,
        void               *info_near,
        void               *info_far,
        miState            *state);

^3.4 Call the contour shader in . This works both for standard materials and Phenomenon materials. It calls the contour shader of a material Phenomenon. mi_call_contour_material may only be called in contour mode, with a contour shader as parent of a shade tree. info_near and info_far must be passed from a parent contour shader. The contour contrast shader, the contour storage shader, and the contour shader itself must use matching info_near and info_far values. The info structures must have the same size and layout.

    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)

Return the value of a shader parameter. If the shader parameter value is a constant, mi_eval returns its argument. If the parameter is assigned to another shader, call that shader and return a pointer to its return value (or the cached return value if it has been called recently). If the parameter is assigned to a Phenomenon interface, return a pointer to the value in the interface. The latter two cases let shaders operate in the contexts of shader assignments and phenomena without needing knowledge of the context, which is automatically handled. The pointer remains valid until the shader returns, which avoids the need to copy a large returned data structure such as a color or array to temporary variables. Shaders should always access their parameters with mi_eval. If parameters are accessed without mi_eval and the parameter is assigned to another shader or an interface, the shader will see garbage.

The typed variants of mi_eval are implemented as macros for the convenience of shader writers. They cast their argument to a void pointer, call mi_eval, and recast the returned pointer to the appropriate type. They all make the assumption that the shader has a local variable state of type miState * in scope. Experience has shown that the typed variants make source code look much cleaner. Note that there is only one macro mi_eval_tag that can be used for parameters of type shader, color texture, vector texture, scalar texture, light, material, and geometry. All typed variants have been designed to return the same type they accept as an argument.

Always use the correct simple type. For example, if the parameter has type color, it must be evaluated as a single color (probably using mi_eval_color). It is not possible to use four scalar evaluations to access the R, G, B, and A components separately. Also, by convention, arrays should be evaluated as a unit, evaluating two integers for the i_ index, the n_ member count, and the array itself. However, structures are not evaluated as a unit; a separate evaluation is necessary for every simple member it contains.

    void mi_flush_cache(
        miState         *state)

Prevents the cache from being used by future calls to mi_eval. If mi_eval calls another shader, the result is stored in a special cache in that other shader, which is normally flushed only when the entire shader graph returns. This means that the other shader will only ever be called once during the evaluation of a shader graph, and all mi_evals are satisfied from the cache. Notice that flushing applies to the entire sub-graph of shaders evaluated by this and future mi_evals; there is no way to flush the cache of a single shader because that would leave its sub-shaders in a funny state. The result cache is still active for shaders which call mi_flush_cache.

This is useful if the code calls a another shader more than once, such as a texture shader to sample a texture at three different locations to compute bump mapping gradients. Although the shader, if called with mi_call_shader or mi_lookup_color_texture, will get called each time, its sub-shaders inside the same Phenomenon will not if these subshaders are called as the result of mi_eval. (Remember that mi_eval results are cached.) However, if mi_flush_cache is used before the second and every subsequent shader call, the called shader's mi_eval calls will cause a fresh subshader call.