light "light_name"
    [ origin x y z ]
    [ direction dx dy dz ]
end light  

Lights have a large number of optional parameters that are used if global illumination, caustics or shadow maps are enabled. These techniques use a preprocessing step that analyzes how light travels through the scene. Lights that participate in this preprocessing stage must specify a number of extra parameters. For clarity, regular lights and more specialized lights are shown separately:

light "light_name"
    [ emitter shader_list ]
    [ area_light_primitive ]  
    [ origin x y z ]
    [ direction dx dy dz ]
    [ spread spread ]
    [ visible ]
    [ tag labelint ]
    [ data ["data_name"|null] ]

    [ energy r g b ]
    [ exponent exp ]
    [ caustic photons storeint [emitint] ]
    [ globillum photons storeint [emitint] ]

    [ shadowmap [on|off] ]
    [ shadowmap [detail] ]
    [ shadowmap resolution resint ]
    [ shadowmap detail samples numint ]
    [ shadowmap samples numint ]
    [ shadowmap softness size ]
    [ shadowmap file "filename" ]
    [ shadowmap camera "cameraname" ]
    [ shadowmap bias bias ]
    [ shadowmap accuracy epsilon ]
    [ shadowmap [color|alpha] ]
end light

This statement defines a light source. All light sources need a light shader, such as the mib_light_point shader in the base shader library, or another shader linked with a code or link command (see above). " shader " above stands for the quoted name of the shader. Like any other shader, a parameter list (possibly empty) enclosed in parentheses must be given. The parameters depend on the particular shader; they include the light color, attenuation, and spot light directions. The declaration of the shader determines which parameters are available in the parameters list; see section declaration for details on shader parameters.

mental ray distinguishes three kinds of light shaders: point lights, giving off light in all directions; directional lights (also called infinite lights), whose light rays are all parallel in a particular direction, and spot lights which emit light from a point along a certain direction. Point lights must define an origin but no direction. Directional lights must define a direction; starting with mental ray 3.4, they can optionally have an origin that defines a plane whose normal is aligned with the light direction, and behind which no light is emitted. Spot lights must define an origin, a direction, and a spread. The spread defines the maximum angle of the cone defined along the direction in which the spot produces illumination. The value of spread is the cosine of this maximum angle; it must be between 1 (infinitely thin) and 0 (hemisphere). Spot lights often use a directional attenuation, but this is purely a function of the shader that is independent of the spread and direction keywords in the light definition. All types of lights can be turned into area light sources.

After the definition, the light source can be instanced with an instance statement that references light_name. The instance can then be referenced in parameter lists of shaders (such as a material shader) by listing the light instance name. Material shaders normally have an array parameter accepting one or more light instances, which they loop over to accumulate the contribution by each light (unless they rely solely on the global light list). Light instances are one of the standard data types that are available for shader parameters. The light_name should be quoted to avoid clashes with predefined words, and to allow non-alphabetic characters.

A label integer can be attached to a light using the tag statement. Labels are not used by mental ray in any way, but a shader can use the mi_query function to obtain the label of a light and perform light-specific operations.

Also, user data can be attached with a data statement. The argument must be the name of a previously defined data element in the scene file. If the argument is missing, a previously existing data reference is removed.

Area Lights

Any point or spot light may be turned into an area light source by naming an area_light_primitive. Area light sources generate soft shadows because shadow-casting objects may partially obscure the light source. Six types of area light primitives are supported:

rectangle [ x0 y0 z0 x1 y1 z1 sampling ]
disc [ x y z radius sampling ]
sphere [ radius sampling ]
cylinder [ axis radius sampling ]
user sampling
object object_inst sampling

The common sampling substatement is optional:

[ u_samples v_samples [ level [low_u_samples low_v_samples] ] ]

All three area light types are centered at the origin position in the light definition. A rectangular area light is specified by two vectors that describe the lengths of the edges; a disc area light is specified by its normal vector and a radius; a sphere area light is specified only by its radius; and a cylinder area light is specified by its axis and radius. Note that the orientation of the rectangle, disc, or cylinder are independent of the direction and any directional attenuation the shader applies, although both will generally be similar. Also note that the end caps of the cylinder are not sampled.

mental ray supports a user-defined area light source. This requires a special light shader that controls the points on which it is sampled, instead of leaving the sample point location to mi_sample_light. The light shader will be called in a loop until the shader decides it has been sampled enough, or when the sample limit (u · v) is reached, and returns (miBoolean)2. User area light sources also do not apply the optimization that cancels light rays under the horizon of the illuminated point. It is not necessary (or desirable, because of self-shadowing issues) to set state→pri to null.

mental ray also supports geometric area light sources for point lights, specified by the object keyword. Its first argument must be the instance of a single-group object that defines the geometry of the area light source. All points on the surface of the object will emit light uniformly. It is generally a good idea to keep the triangle count of the object as low as possible for maximum performance. The sampling rates usually have to be set much higher for object lights.

The u_samples and v_samples are used to specify the number of samples in 2 dimensions of the light area. Quasi-Monte-Carlo sampling used by mental ray provides stratification automatically, so the sampling patterns depend only on the u_samples * v_samples product and not on the individual values. Two values are kept for compatibility reason only. As the implementation of the Quasi-Monte-Carlo sampling gives the best results for the numbers which are integer power of 2, the actual number of samples taken is the greatest power of 2 which does not exceed u_samples * v_samples.

If the optional level exists and is greater than 0, then mental ray will use low_u_samples and low_v_samples instead of u_samples and v_samples if the sum of the reflection and refraction trace level exceeds level. The defaults for the low levels are 2. The effect is that reflections and refractions of soft shadows are sampled at lower precision, which can improve performance significantly. Since shaders have control over the trace level in the state, they can influence the switching depth, which can be used to sample soft volume shadows less precisely, for example. This optimization does not apply to user-defined area light sources because here the shader is in control of sampling rates, and if it is cut off early incorrect illumination can result.

Like for u_samples and v_samples, only the product of low_u_samples and low_v_samples is relevant for the sampling pattern. In the current implementation the actual number of samples taken is the greatest power of 2 which does not exceed low_u_samples * low_v_samples.

If the rectangle, disc, sphere, or cylinder keyword is specified without any of the following arguments, then the light source reverts to a non-area light source. This is useful for incremental changes.

Physical Correctness

The second light form is for caustics and global illumination. (Caustics, global illumination, and final gathering implement the simulation of indirect illumination.) It requires specification of the light energy. The light energy is given as an RGB triple to allow colors, but the RGB values are typically much higher than the usual 0…1 range for colors. The number of photons stored from this light source in the preprocessing step is determined by store, and the number of emitted photons is determined by emit, if specified. When either limit is reached, photon emission stops. If store is 0, emit must be specified and storing is unlimited. Physical correctness demands an 1 ⁄ r2 power law for energy falloff, causing the energy received from a light source to fall off with the square of the distance to the light source. However, the exponent parameter allows modification of the power law to 1 ⁄ rexp. For any exp other than 2, physical correctness is lost, but for achieving certain looks it is often useful to use exp values between 1 and 2 to reduce the falloff, and better approximate classical local illumination non-physically correct lights.

For caustics, one can specify a caustics photons value that controls the number of caustic photons stored during caustics preprocessing. Similarly, a globillum photons value can be specified for global illumination. Typical values range from 10,000 to 100,000; larger values improve accuracy and reduce blurriness.

Light sources are by default invisible. However, area lights can be made visible by adding a visible flag to the light. Any visible flags on non-area lights are ignored since they have zero size. Light visibility cannot be inherited from the instance. It reduces performance if the number of visible lights is very large. Visible light sources ensure that the direct contribution of the light to the camera is not lost, and energy conservation is maintained in the rendered image.


Shadow maps are controlled per light source using the information about the light source type and the information provided by the shadow map keywords. Shadow maps are supported for spot lights with a cone-angle less than 90 degrees (i.e. spread > 0), for directional lights, and for point lights. A shadow map is activated for a light source by specifying the shadowmap keyword. The resolution of the shadow map which controls the quality and also the amount of memory used is specified with the shadowmap resolution keyword, which specifies the width and height of the shadowmap depth buffer in pixels. The shadowmap softness and shadowmap samples keywords determine the type of shadow produced with the shadow map; if the softness is zero a sharp shadow is generated. If softness is larger than zero, shadowmap samples different samples will be taken from the shadowmap, on a square region the size of shadowmap softness. This will make the boundaries of the shadows appear softer.

The softness is specified in internal space units on the shadow map projection plane. For directional lights, an orthographic projection is used, so the softness will be constant in the scene, the soft region having roughly the given softness value in size. For other lights, because of the projective projection used, apparent softness will increase with distance from the light. This means that much smaller softness values are usually required for spot lights than directional lights. If an excessively high softness value is specified, a warning will be given during rendering. Very high values tend to blur the shadow out of existence. The number of samples determines the quality of the soft shadow.

The shadowmap bias statement specifies that mental ray should not use the distance to the halfway point between the two closest shadow-casting objects (this is called the Woo trick), but the distance to the closest plus the bias value. This is useful for shadowmap merging. A bias value of zero re-enables the Woo algorithm. The bias value can also set in the options; this applies to all lights.

If shadowmap merging is enabled, mental ray will load the shadowmap file from disk, if available, and also compute the shadowmap. It then uses the closest distance to determine whether a point is in shadow. This is useful in conjunction with pass rendering, where the scene is divided into passes that are rendered separately. If the objects are sorted into passes front to back, with the frontmost rendered in the first pass, this allows front objects to cast shadowmap shadows on objects in later passes even though these objects are not present in the the later pass. The merged shadowmap is saved back to the shadowmap file. Note that shadowmap merging is not compatible with the halfway-point Woo trick, so it is necessary to specify a shadowmap bias either in each light source with shadowmaps to be merged, or globally in the options block. Merging does not work for detail shadowmaps.

The shadowmap file statement can be used to specify a shadow map file in which the shadow map will be saved the first time it is rendered, and subsequently loaded every times it is used. In the case of point lights, six different files will be saved, each for a different direction (the resolution of each file will be lower so that the total number of pixels rendered will be approximately resolution × resolution). If objects in the scene move, the old shadow map files should be deleted to prevent loading and re-using outdated shadow maps. If the filename contains the # character, it will be expanded by mental ray into a hash code number identifying the transformation of the light instance. This is useful when a light is multiply instanced, because it allows distinguishing between files representing multiple instances of the same light. However, the user must take care to remove obsolete files or they will eventually fill all available disk space.

Shadow maps are saved in the .zt file format, which is basically an 8-byte header followed by uncompressed floating-point pixel data. mental ray 3.2 and later use a format variant that works like .zt with some light space information appended. The extra information makes loading shadowmaps for lights that have moved, or scenes whose bounding box axes have changed, unambiguous. This avoids a problem of switching light axes when a shadowmap is transplanted from one scene to another.

For spot light sources, the extent of the shadow map is determined by the spread parameter. For directional light sources, the extent of the shadow map is determined by the extent of the parts of the scene that cast shadows. For example, in a scene with small objects on a large background polygon, the small objects casting shadows should have a shadow flag, while the background polygon should not. Then the extent of the shadow map will only cover the small objects that cast shadows. If the large background polygon also has the shadow flag, the extent of the shadow map will be larger, and the shadow map will lack detail at the small objects where detailed shadows are needed.

mental ray allows attaching a camera to a spot or directional light source. This is not the standard camera that defines the viewpoint from which the scene is rendered; it is simply a container for the following camera fields:

All other camera fields are ignored. A light camera does not have a camera instance; the light instance defines the necessary transform matrix. Treating a light like a camera is an useful abstraction for properly defining the light orientation. Note, however, that the spread value for spot lights must still be set and does not have a direct equivalent in the camera paradigm.

Detail Shadowmaps

The advanced detail shadowmap algorithm for calculating and storing shadowmaps is invoked by setting shadowmap detail. This algorithm is a combination of standard shadowmaps and ray traced shadows. Unlike standard shadowmaps, the detail shadowmap algorithm calls shadow shaders at intersection points if existing.

The shadowmap detail samples parameter may be used to set the number of samples per pixel taken when computing a shadowmap pixel. A value of n means that n × n samples are taken per pixel, each involving a shadow intersection including a shadow shader call at some varying subpixel coordinate inside the shadowmap pixel. If this value is not specified then the global setting in the rendering options applies.

The shadowmap accuracy parameter determines how far two depth values of a sample have to be separated in order to be considered as distinct values. Selecting this value too small will result in larger memory and compute resource requirements for detail shadowmaps. Selecting it too large will lead to visible artifacts. If not set, mental ray tries to use a reasonable default value for the accuracy.

The shadowmap color is the default choice for detail shadowmaps. This setting indicates that all color channels of the shadow shader are used for the shadowmap calculation. If shadowmap alpha is set, then only the intensity values of the color transmission coefficients are used.

Copyright © 1986, 2013 NVIDIA Corporation