Advanced Topics

Passing Lightmaps Manually

The lightmaps are rendered in camera space, using adjacent pixels to store front- and back-surface light data. Since these are adjacent horizontally, this means that lightmaps should have a width greater than their height. If 500x500 actual samples of both the front and back surface are desired, the lightmap should be 1000x500 pixels.

The lightmap must be a 32-bit texture. Floating point RGBA is strictly required because Z depth information is stored in the alpha component. As a memory saving option, the .exr format may be used, with a negligible performance penalty and 50% memory savings.

The depthmap is not user assignable and is only used for the automatic mode. Its sole purpose is a small memory/performance optimization.

Automatic Lightmap Generation

For ease of use, passing an explicit lightmap in the proper format is not required. However, since all participating shaders must know about the lightmaps used, a special kind of Phenomenon can be used in which the first two parameters of the Phenomenon must be the lightmap and depthmap pair. Anywhere the individual shaders are used within the Phenomenon, they must be linked to these first two parameters via interface connections, instead of being set to a specific value.

Only if these conditions are met, automatic lightmap creation can be used. If the conditions are not met, manual specification of the lightmap have to be used.

Here is pseudocode for a Phenomenon that meets these criteria:

declare phenomenon 
    material "my_sss_phenomenon" (
        color texture     "lightmap",                  # must be first
        color texture     "depthmap",                  # must be second
        color             "diffuse_paint",
        color             "my_special_color",
        scalar            "lightmap_size",             # for example
        ...
    )
    shader "myscattering" "misss_fast_shader" (
        "lightmap"        = interface "lightmap",      # required
        "depthmap"        = interface "depthmap",      # required
        "diffuse_illum"   ...
        ...
    )
    shader "mylightmapping"   "misss_lightmap_write" (
        "lightmap"        = interface "lightmap",      # required
        "depthmap"        = interface "depthmap",      # required
        "lightmap_group"  "A",
        "lightmap_size"   = interface "lightmap_size", # for example
        ...
    )
    ...
end declare

Failing to follow these guidelines may cause the Phenomenon to behave unpredictably and may possibly abort rendering when the shaders attempt to communicate over a parameter slot that is missing or used for another purpose.

Network Rendering

When mental ray renders lightmaps, it tries to distribute the workload to several hosts on a per-object basis. However, the misss_fast_ shaders encourage (due to memory efficiency) and in some cases require (for separate objects to scatter into each other) several objects to share the same lightmap.

Multiple hosts writing into the same lightmap is not possible in mental ray, and will create a collision, where incomplete or incorrect lightmap data can be created.

The following are some ways around the problem:

Make sure every object has its own lightmap (scatter group). This will increase memory requirements.
Redesign the model to use fewer objects so there is one object per lightmap.
Render in passes by using the component shaders (instead of the supplied Phenomena) to render the lightmaps to file on a single host. In a second pass referencing these pre-created lightmaps render the final image on an arbitrary number of hosts.
Render on a single host.

Note, when using displacement, objects might be split automatically into many sub-objects that are tessellated and lightmapped individually. This causes one object to become many, making the first two workarounds listed impossible.