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

typenamearguments
miBooleanmi_call_shader*result, type, *state, tag
miBooleanmi_call_shader_x*result, type, *state, tag, *arg
miBooleanmi_call_material*result, *state
miBooleanmi_call_photon_material*result, *state
miBooleanmi_call_shadow_material*result, *state
miBooleanmi_call_environment_material*result, *state
miBooleanmi_call_volume_material*result, *state
miBooleanmi_call_photonvol_material*result, *state
miBooleanmi_call_contour_material*result, *void, *void, *state
void *mi_eval*state, *param
miBoolean *mi_eval_boolean*param
miInteger *mi_eval_integer*param
miScalar *mi_eval_scalar*param
miVector *mi_eval_vector*param
miScalar *mi_eval_transform*param
miColor *mi_eval_color*param
miTag *mi_eval_tag*param
voidmi_flush_cache*state

Database Functions

typenamearguments
intmi_db_typetag
intmi_db_sizetag
void *mi_db_accesstag
voidmi_db_unpintag
voidmi_db_flushtag

Rendering Functions

typenamearguments
miBooleanmi_trace_eye*result, *state, *org, *dir
miBooleanmi_trace_reflection*result, *state, *dir
miBooleanmi_trace_refraction*result, *state, *dir
miBooleanmi_trace_transparent*result, *state
miBooleanmi_trace_environment*result, *state, *dir
miBooleanmi_trace_probe*state, *dir, *org
miBooleanmi_trace_probe_x*state, *dir, *org, flags
miBooleanmi_trace_transparent*result, *state
miBooleanmi_trace_continue*result, *state
miBooleanmi_trace_light*result, *dir, *nl, *st, i
miBooleanmi_sample_light*result, *dir, *nl, *st,i,*s
miBooleanmi_trace_shadow*result, *state
miBooleanmi_trace_shadow_seg*result, *state
miBooleanmi_continue_shadow_seg*result, *state
miBooleanmi_ray_offset*state, *offset
miBooleanmi_ray_falloff*state, *start, *stop
miBooleanmi_inclusive_lightlist*n, **lights, *state
miBooleanmi_exclusive_lightlist*n, **lights, *state
miBooleanmi_instance_lightlist*n, **lights, *state
miScalarmi_lightprofile_value*prof, phi, theta, *pos, rel
miScalarmi_lightprofile_sample*state, proftag, rel
miBooleanmi_compute_irradiance*result, *state
miBooleanmi_compute_irradiance_backside*result, *state
miBooleanmi_compute_avg_radiance*result, *state, face, irrad_options
miBooleanmi_compute_volume_irradiance*result, *state
miBooleanmi_compute_directional_irradiance*result, *state, r, g1, g2
miBooleanmi_finalgather_store*result, *state, mode
miBooleanmi_sample*sample, *i, *state, dim, *n

Photon Functions

typenamearguments
miBooleanmi_photon_light*energy, *state
miBooleanmi_photon_reflection_specular*energy, *state, *dir
miBooleanmi_photon_reflection_glossy*energy, *state, *dir
miBooleanmi_photon_reflection_diffuse*energy, *state, *dir
miBooleanmi_photon_transmission_specular*energy, *state, *dir
miBooleanmi_photon_transmission_glossy*energy, *state, *dir
miBooleanmi_photon_transmission_diffuse*energy, *state, *dir
miBooleanmi_photon_transparent*energy, *state
miBooleanmi_photon_volume_scattering*energy, *state, *dir
voidmi_store_photon*energy, *state
voidmi_store_volume_photon*energy, *state

Direction Functions

typenamearguments
voidmi_reflection_dirdir, state
voidmi_reflection_dir_specular*dir, *state
voidmi_reflection_dir_glossy*dir, *state, shiny
voidmi_reflection_dir_glossy_x*dir, *state, shiny, *sample
voidmi_reflection_dir_anisglossy*dir, *state, u, v, shiny_u, shiny_v
voidmi_reflection_dir_anisglossy_x*dir, *state, u, v, shiny_u, shiny_v, *sample
voidmi_reflection_dir_diffuse*dir, *state
voidmi_reflection_dir_diffuse_x*dir, *state, *sample
miBooleanmi_refraction_dirdir, state, ior_in, ior_out
miBooleanmi_transmission_dir_specular*dir, *state, *in, *out
miBooleanmi_transmission_dir_glossy*dir, *state, *in, *out, shiny
miBooleanmi_transmission_dir_glossy_x*dir, *state, *in, *out, shiny, *sample
miBooleanmi_transmission_dir_anisglossy*dir, *state, *in, *out, u, v, shiny_u, shiny_v
miBooleanmi_transmission_dir_anisglossy_x*dir, *state, *in, *out, u, v, shiny_u, shiny_v, *sample
voidmi_transmission_dir_diffuse*dir, *state
voidmi_transmission_dir_diffuse_x*dir, *state, *sample
voidmi_scattering_dir_diffuse*dir, *state
voidmi_scattering_dir_directional*dir, *state, directionality
miScalarmi_scattering_pathlength*state, density

Vector and Matrix Math Functions

typenamearguments
voidmi_vector_neg*r
voidmi_vector_add*r, *a, *b
voidmi_vector_sub*r, *a, *b
voidmi_vector_mul*r, f
voidmi_vector_div*r, f
voidmi_vector_prod*r, *a, *b
miScalarmi_vector_dot*a, *b
miScalarmi_vector_norm*a
voidmi_vector_normalize*r
voidmi_vector_min*r, *a, *b
voidmi_vector_max*r, *a, *b
miScalarmi_vector_det*a, *b, *c
miScalarmi_vector_dist*a, *b
voidmi_matrix_nullr
voidmi_matrix_identr
miBooleanmi_matrix_isidenta
voidmi_matrix_copyr, a
miBooleanmi_matrix_invertr, a
voidmi_matrix_prodr, a, b
voidmi_matrix_rot_deta
voidmi_matrix_rotatea, x, y, z
voidmi_matrix_rotate_axisa, *v, r
voidmi_matrix_solve*x, a, *b, c

Transformation Math Functions

typenamearguments
voidmi_point_transform*r, *v, m
voidmi_vector_transform*r, *v, m
voidmi_vector_transform_T*r, *v, m
voidmi_point_to_world*state, *r, *v
voidmi_point_to_camera*state, *r, *v
voidmi_point_to_object*state, *r, *v
voidmi_point_to_light*state, *r, *v
voidmi_point_to_raster*state, *r, *v
voidmi_point_from_world*state, *r, *v
voidmi_point_from_camera*state, *r, *v
voidmi_point_from_object*state, *r, *v
voidmi_point_from_light*state, *r, *v
voidmi_vector_to_world*state, *r, *v
voidmi_vector_to_camera*state, *r, *v
voidmi_vector_to_object*state, *r, *v
voidmi_vector_to_light*state, *r, *v
voidmi_vector_from_world*state, *r, *v
voidmi_vector_from_camera*state, *r, *v
voidmi_vector_from_object*state, *r, *v
voidmi_vector_from_light*state, *r, *v
voidmi_normal_to_world*state, *r, *v
voidmi_normal_to_camera*state, *r, *v
voidmi_normal_to_object*state, *r, *v
voidmi_normal_to_light*state, *r, *v
voidmi_normal_from_world*state, *r, *v
voidmi_normal_from_camera*state, *r, *v
voidmi_normal_from_object*state, *r, *v
voidmi_normal_from_light*state, *r, *v

Noise Functions

typenamearguments
miScalarmi_random
miScalarmi_srandomseed
miScalarmi_erandomseed[3]
doublemi_par_random*state
miScalarmi_splinet, n, *ctl
miScalarmi_noise_1dp
miScalarmi_noise_2du, v
miScalarmi_noise_3d*p
miScalarmi_noise_1d_gradp, *g
miScalarmi_noise_2d_gradu, v, *gu, *gv
miScalarmi_noise_3d_grad*p, *g
miScalarmi_unoise_1dp
miScalarmi_unoise_2du, v
miScalarmi_unoise_3d*p
miScalarmi_unoise_1d_gradp, *g
miScalarmi_unoise_2d_gradu, v, *gu, *gv
miScalarmi_unoise_3d_grad*p, *g

Image Functions

typenamearguments
voidmi_img_put_color*image, *color, x, y
voidmi_img_get_color*image, *color, x, y
voidmi_img_put_scalar*image, scalar, x, y
voidmi_img_get_scalar*image, *scalar, x, y
voidmi_img_put_vector*image, *vector, x, y
voidmi_img_get_vector*image, *vector, x, y
voidmi_img_put_depth*image, depth, x, y
voidmi_img_get_depth*image, *depth, x, y
voidmi_img_put_normal*image, *normal, x, y
voidmi_img_get_normal*image, *normal, x, y
voidmi_img_put_label*image, label, x, y
voidmi_img_get_label*image, *label, x, y
intmi_img_get_width*image
intmi_img_get_height*image
miImg_image*mi_img_pyramid_get_level*image, int
miBooleanmi_img_tonemap*outimage, *inimage, *paras

Color Profile Functions

typenamearguments
miUint1mi_colorprofile_renderspace_id
miUint1mi_colorprofile_internalspace_id
miUint1mi_colorprofile_ciexyz_id
miBooleanmi_colorprofile_internal_to_render*color
miBooleanmi_colorprofile_internal_to_ciexyz*color
miBooleanmi_colorprofile_render_to_internal*color
miBooleanmi_colorprofile_render_to_ciexyz*color
miBooleanmi_colorprofile_ciexyz_to_render*color
miBooleanmi_colorprofile_ciexyz_to_internal*color

Shading Models

typenamearguments
miScalarmi_fresneln1, n2, t1, t2
miScalarmi_fresnel_reflection*state, *i, *o
miScalarmi_phong_specularspec, *state, *dir
voidmi_fresnel_specular*ns, *ks, s, *st, *dir, *in, *out
miScalarmi_blinn_specularspec, *state, *dir
miScalarmi_blong_specularspec, *state, *dir
miBooleanmi_cooktorr_specular*result, *di, *dr, *n, roughness, *ior
miScalarmi_ward_glossy*di, *dr, *n, shiny
miScalarmi_ward_anisglossy*di, *dr, *n, *u, *v, shiny_u, shiny_v
miScalarmi_schlick_scatter*di, *dr, directionality
miRay_typemi_choose_scatter_type*state, transp, *specular, *glossy, *diffuse
miRay_typemi_choose_simple_scatter_type*state, *rdiff, *rspec, *tdiff, *tspec
miIntegermi_choose_lobe*state, r

Auxiliary Functions

typenamearguments
miBooleanmi_lookup_color_texture*col, *state, tag, *v
miBooleanmi_lookup_scalar_texture*scal, *state, tag, *v
miBooleanmi_lookup_vector_texture*vec, *state, tag, *v
miBooleanmi_lookup_filter_color_texture*col, *state, tag, *paras, ST
miBooleanmi_texture_filter_projectp[3], t[3], *state, disc_r, space
miBooleanmi_texture_filter_transformST, p[3], t[3]
miScalarmi_luminance*state, color
miBooleanmi_tri_vectors*state, wh, nt, **a, **b, **c
miBooleanmi_texture_interpolate*state, space, *result
miBooleanmi_raster_unit*state, *x, *y
miBooleanmi_queryquery, *state, tag, *result, ...
miBooleanmi_shaderstate_enumerate*state, *cb, *arg
miBooleanmi_shaderstate_set*state, *key, ks, *val, vs, t
void *mi_shaderstate_get*state, *key, ks, *vs
miBooleanmi_fb_put*state, fb, *data
miBooleanmi_fb_get*state, fb, *data
miImg_image *mi_output_image_open*state, idx
voidmi_output_image_close*state, idx
miBooleanmi_geoshader_add_resultquery, *state, tag, *result, ...
miBooleanmi_geoshader_tesselate*state, *leaves, source
miBooleanmi_geoshader_tesselate_endleaves
miBooleanmi_geoshader_echo_tag*fp, tag, *eopt
char *mi_string_substitute*new, *old, size
miIntegermi_volume_num_shaders*state
miIntegermi_volume_cur_shader*state
miColor *mi_volume_tags*state
miTag *mi_volume_user_color*state
voidmi_opacity_set*state, *color
miBooleanmi_opacity_get*state, *color

Samplepass Rendering Functions

These functions are available only to pass merge (access) or pass preprocessing (get, put, flush, black) shaders.
typenamearguments
void *mi_renderpass_access*state, pass, db
miBooleanmi_renderpass_sample_get*result, sz, *state, fb, x, y
miBooleanmi_renderpass_sample_put*result, sz, *state, fb, x, y
miBooleanmi_renderpass_samplerect_flush*result, *state, x, y
miBooleanmi_renderpass_samplerect_black*result, *state, x, y

Obsolete Auxiliary Functions

These functions are obsolete; use mi_query for future implementations.
typenamearguments
voidmi_light_infotag, *org, *dir, **paras
intmi_global_lights_info**tag
voidmi_texture_infotag, *xres, *yres, **paras
void *mi_shader_info*state
intmi_instance_info*state, **paras, **p1, **p2, **p3

Contour Functions

typenamearguments
miBooleanmi_get_contour_line*p1, *p2
voidmi_add_contour_linesp1[], p2[], n

Light Mapping Functions

typenamearguments
miImg_image*mi_lightmap_edit**handle, tag
voidmi_lightmap_edit_end*handle

Memory Allocation

typenamearguments
void *mi_mem_allocatesize
void *mi_mem_test_allocatesize
void *mi_mem_reallocatemem, size
void *mi_mem_test_reallocatemem, size
voidmi_mem_releasemem
voidmi_mem_check
voidmi_mem_dumpmod
char *mi_mem_strdup*text

Thread Parallelism and Locks

type name arguments
voidmi_init_lock*lock
voidmi_delete_lock*lock
voidmi_locklock
voidmi_unlocklock
intmi_par_localvpu
intmi_par_nthreads
intmi_par_aborted

Messages and Errors

typenamearguments
voidmi_fatal*message, ...
voidmi_error*message, ...
voidmi_warning*message, ...
voidmi_info*message, ...
voidmi_progress*message, ...
voidmi_debug*message, ...
voidmi_vdebug*message, ...

Shader Calls

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

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.

Copyright © 1986, 2013 NVIDIA Corporation