Materials

material "material_name"
    [ opaque ]
    shader_list
    [ displace [shader_list] ]
    [ shadow [shader_list] ]
    [ volume [shader_list] ]
    [ environment [shader_list] ]
    [ contour [shader_list] ]
    [ photon [shader_list] ]
    [ photonvol [shader_list] ]
    [ lightmap [shader_list] ]
    [ bsdf [shader_list] ] 
end material

Materials determine the look of geometric objects. They are referenced by material_name in the geometry definition in object statements (see below). Lights and textures cannot be referenced by objects; they are referenced by the material which uses them to compute the color of a point on the object's surface. All built-in material shaders accept textures and light instances as shader parameters.

When a primary ray cast from the camera hits an object, that object's material shader (the first shader_list) is called. The material shader may be omitted in fully transparent objects. Such objects are useful as hull objects for volume effects such as visible light cones. Such objects will generally specify shadowmap off as well.

The material shader then calculates a color (and certain other optional values such as labels, Z depths, and normal vectors that can be written to special output files). This color may then be modified by the optional volume shader if present. The resulting color is stored in the output frame buffer, which is written to the output picture file when rendering has finished. In order to calculate the color, the material shader may cast secondary reflection, refraction, or transparency rays, which in turn may hit objects and cause other (or the same; multiple objects may share a material) material shaders to be called. The material shader bases the decision whether to cast secondary rays on its parameters, which are part of the scene description and may contain parameters such as the material's diffuse color or its reflectivity and transparency, light instances, and textures. The parameters depend entirely on the material shader. In this sense, material shaders are "primary" shaders that get help from "secondary" texture and light shaders.

It is possible to specify a shader type such as shadow without following it with a shader_list. This is useful if an incremental change is done to the material. The incremental change leaves the contents of the material undisturbed except where explicitly rewritten, so the shadow shader list remains intact. It can be replaced by specifying a new one, but it can only be deleted with a shadow keyword not followed by any shaders. In an incremental change, the first statement (say, volume) first resets the old volume list; every subsequent volume statement in the same material block adds to the list.

The material_name should be quoted to avoid conflicts with reserved names and non-alphabetic characters. The opaque flag, if present, informs mental ray that this material is not transparent (i.e., it does not cast refraction or transparency rays and always sets its alpha result value to 1); this allows certain optimizations that improve rendering speed. The material shader and its parameters are the only mandatory part of a material.

There are several optional functions that can be listed in a material. The displacement shader is a function returning a scalar that displaces the object's surface in the direction of its normal, or in arbitrary directions. Displacement shaders can be applied to both free-form surface objects and polygonal objects.

The shadow shader is called when a shadow calculation is done, and the shadow ray from the light source towards the point in shadow intersects with this material. The shadow shader then changes the color of the ray, which is initially the (possibly attenuated) color of the light to another color, typically a darker or tinted color if the material is colored glass. It returns black if the material is totally opaque, which is also the default if no shadow shader is present. Shadow shaders are usually reduced versions of the material shaders; they evaluate transparencies and colors but cast no secondary rays. Shadow shaders are only required for transparent objects. If global illumination is enabled, no shadow shaders should be used because global illumination provides a more powerful way to compute light transmission, and using two "competing" methods at the same time for the same object may produce incorrect results.

It is possible to use the material shader as a shadow shader; material shaders can find out whether they are called as material or shadow shaders and do only the required subset in the latter case. This is done by naming the material shader after the shadow keyword, and giving no parameters (i.e., giving ()). mental ray will notice the absence of parameters and pass the material parameters instead. If the shadow shader has no parameters of its own, it is not defined whether it receives a pointer to the material shader parameters, or a pointer to a copy of the material shader parameters.

A volume shader affects rays traveling inside an object. Volume shaders are conceptually similar to fog or atmosphere shaders of other rendering programs. When a ray (either from the eye or from a light source) hits this material, the volume shader, if present, is called to change the color returned by the ray based on the distance the ray has traveled, and atmospheric or material parameters. A volume shader can also be named in the camera (see above); that shader is used for rays traveling outside objects. It is the material shader's responsibility to determine inside and outside of objects.

The environment shader is called when a reflection or refraction ray cast by the material shader leaves the scene entirely without striking another object. For example, the environment shader may map a texture on a sphere with an infinite radius surrounding the scene. (This is another example for an application of a texture; a texture name must be used as a parameter for the environment shader for this to work.) The camera statement also allows naming an environment shader; that shader is used when the ray leaves the scene without ever striking any object (or exceeding the trace depth).

If a contour shader is given, it is called when contours are enabled with an appropriate output statement in the camera element, and certain contour store and contour contrast shaders are specified in the options element. For more information on contour rendering see section contour.

If caustics or global illumination computation is enabled, the photon shader is called during a preprocessing stage (before rendering) to determine the light distribution in the scene. Like shadow shaders, photon shaders without parameter lists are called with the material shader parameter lists.

A volume photon shader affects photons traveling inside an object. When a photon hits this material, the volume photon shader, if present, is called to trace the photon through the volume. Volume photon shaders are to volume shaders what photon shaders are to material shaders.

The lightmap shader, if present, is called for the object that the material is attached to, and is expected to create a light map other information collection about the object that can be saved to disk or used during rendering. In its most common form, the shader creates a texture that contains the illumination of the object; hence the term "light map".

The BRDF shader attached to the bsdf slot specifies a common shading model to be used for illumination effects where the corresponding shader is not available, including the main material shader.

Materials can be replaced with phenomena. In all places where the name of a material may be given, the name of a shader that references a phenomenon declaration of type material is legal. Given the following scene fragment:

declare phenomenon
     material "phen_mtl" (color "param")
     material "mtl" opaque
          "shader" ("diffuse" = interface "param")
     end material
     root material "mtl"
end declare

shader "mtl_sh" "phen_mtl" ("param" 1.0 0.7 0.3)

the name mtl_sh can be used like a material_name, for example in polygon or free-form surface definitions in objects. For more information on material phenomena, see section phenomenon.

Note that there are three ways to use materials in a scene:

Every polygon and surface in an object specifies a material. They can be omitted but default to the previous polygon or surface in the object, but this is only a syntactical simplification. Effectively, every polygon and surface brings its own material, and no material inheritance takes place.
If the object is marked tagged, polygons and surfaces do not specify materials but integer labels. In this case the inherited material in the instance is used. That material can use mi_query to obtain the label and modify its behavior based on the label.
As a variation of the previous method, the instance may specify not a single material but a list of materials. In this case, mental ray will use the n-th material in the list if the label of the intersected primitive is n (or the first material if the label is greater than or equal to the number of materials in the list).

See section instance for more details on material lists and material inheritance.