• home
• « prev
• next »
• index

• mi_call_shader
• mi_call_shader_x
• mi_call_material
• mi_call_photon_material
• mi_call_shadow_material
• mi_call_environment_material
• mi_call_volume_material
• mi_call_photonvol_material
• mi_call_contour_material
• mi_call
• mi_call_boolean
• mi_call_color
• mi_call_integer
• mi_call_scalar
• mi_call_transform
• mi_call_tag
• mi_call_vector
• mi_eval
• mi_eval_boolean
• mi_eval_color
• mi_eval_integer
• mi_eval_scalar
• mi_eval_transform
• mi_eval_tag
• mi_eval_vector
• mi_flush_cache

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 <stdio.h> and <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.

Shader Calls

Database Functions

Rendering Functions

Photon Functions

Direction Functions

Vector and Matrix Math Functions

Transformation Math Functions

Noise Functions

Image Functions

Color Profile Functions

Shading Models

Auxiliary Functions

Multipass Rendering Functions

Obsolete Auxiliary Functions

Contour Functions

Light Mapping Functions

Memory Allocation

Thread Parallelism and Locks

Messages and Errors

Shader Calls

mi_call_shader

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

mi_call_shader_x

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

Call the shader specified by the tag shader.

The extended version passes an additional arg parameter as a fourth argument to the shader. The function mi_call_shader_x is slightly more efficient than mi_call_shader.

The shadertag 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 state→shader.
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, state→shader is restored to its old value.

The return value of the shader call is returned. The result value computed by the shader is returned in the variable pointed to by the result pointer. 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 scene, or in the .mi file with a texture, light, or some other statement, combining shading function and shader parameters to form a shader instance; it is not just a simple pointer or reference to a C function.

mi_call_material

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

Call the material shader in state→material.

This works both for standard materials and Phenomenon materials.

mi_call_photon_material

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

Call the photon shader in state→material.

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

mi_call_shadow_material

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

Call the shadow shader in state→material.

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

mi_call_environment_material

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

Call the environment shader in state→material.

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

mi_call_volume_material

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

Call the volume shader in state→material.

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

mi_call_photonvol_material

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

Call the photonvol shader in state→material.

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

mi_call_contour_material

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

Call the contour shader in state→material.

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.

mi_eval
mi_eval_boolean
mi_eval_color
mi_eval_integer
mi_eval_scalar
mi_eval_vector
mi_eval_transform
mi_eval_tag

    void *mi_eval(
        miState         *state,
        void            *param)

    miBoolean *mi_eval_boolean(
        miBoolean       *param)

    miColor *mi_eval_color(
        miColor         *param)

    miInteger *mi_eval_integer(
        miInteger       *param)

    miScalar *mi_eval_scalar(
        miScalar        *param)

    miScalar *mi_eval_transform(
        miScalar        *param)

    miVector *mi_eval_vector(
        miVector        *param)

    miTag *mi_eval_tag(
        miTag           *param)

Return the value of a shader parameter.

If the shader parameter value is a constant, then mi_eval returns its argument. If the parameter is assigned to another shader, call that shader if needed and return a pointer to its return value. 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 directly and the parameter is assigned to another shader or an interface, the shader will see garbage.

The typed variants of mi_eval are convenient macros for shader writers to avoid explicit type casting. They all make the assumption that the shader has a local variable state of type miState* in scope. These typed variants make shader 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 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.

Note, for performance reasons, the return value of a shader call or a phenomenon evaluation will be stored internally in a cache. The cached value will be returned from subsequent mi_eval calls on the same parameter of a shader during the current evaluation of the shading graph. Shaders which need to enforce a complete re-computation of a connected shader graph, for example to sample a texture shader at different texture coordinates set in the state, should use the corresponding mi_call functions.

mi_call
mi_call_boolean
mi_call_color
mi_call_integer
mi_call_scalar
mi_call_vector
mi_call_transform
mi_call_tag

    void *mi_call(
        miState         *state,
        void            *param)

    miBoolean *mi_call_boolean(
        miBoolean       *param)

    miColor *mi_call_color(
        miColor         *param)

    miInteger *mi_call_integer(
        miInteger       *param)

    miScalar *mi_call_scalar(
        miScalar        *param)

    miScalar *mi_call_transform(
        miScalar        *param)

    miVector *mi_call_vector(
        miVector        *param)

    miTag *mi_call_tag(
        miTag           *param)

Return the value of a shader parameter.

These functions are equivalent to mi_eval family of functions, but do not utilize the caching mechanism. If a shader calls this function on a parameter which is connected, then all shaders in the sub-shader chain (only) will be forced to re-compute and the result value will be returned. The original shader result cache is not affected nor destroyed by these functions, meaning, that any previous or following mi_eval call on the same parameter will use the original cache. These functions are intended for multiple evaluation of same shader parameter with temporary modifications to state variables, such as normal or texture coordinates for bump mapping.

Note, this is a performance critical operation, and these functions should be used with care, only in cases where shader result caching is explicitly not wanted. They are intended to be used as replacement for the mi_flush_cache function, since they allow to write advanced shaders with a more predictable performance impact.

mi_flush_cache

    void mi_flush_cache(
        miState         *state)

Deprecated Invalidates the shader result cache from being used by future calls to mi_eval.

Future implementations should use the mi_call family of functions. since they offer a more predictable way to re-evaluate dedicated sub-shader graphs which are attached to a certain parameter.

If mi_eval calls another shader, the result value is stored in a cache, 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. Note, that flushing applies to the entire sub-graph of shaders evaluated by subsequent mi_evals; there is no way to flush the cache of individual shaders because that would leave their sub-shaders in a funny state. The result cache is still active for the shader which calls 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 different locations to compute bump mapping gradients. Even if a shader itself, if called with mi_call_shader or mi_lookup_color_texture, will get called each time again, its sub-shaders inside the same Phenomenon will not if these subshaders are called as the result of mi_eval (since those 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.

• home
• « prev
• next »
• index

Copyright © 1986-2009 by mental images GmbH