Introduction

RenderMan シェーディング Language (RSL) introduced the pipeline methods diffuselighting() and specularlighting() in PRMan 16. These methods, invoked by the renderer in much the same way as lighting() provide a mechanism by which PRMan can obtain partial shading results. By breaking apart the traditional pipeline or atomizing it, PRMan is able to leverage the richer understanding of the computation being performed, potentially caching results, thus leading to more efficient render times.

Recall that the outline flow of the methods is as follows:

     begin()
     opacity()
     displacement()
     prelighting()
     [lighting methods]
     postlighting()

Not all of the various pipeline methods (old and new) are required to be present, which further signals to the renderer the intent of the shader. This document discusses the conditions under which the various pipeline methods may be invoked, the meaning of the presence or absence of the methods, and best practices for writing them.

Adhering to the guidelines presented here enables PRMan to efficiently work with your shaders - leveraging optimizations in current releases and making future optimizations possible.

In some circumstances, PRMan only requires information provided by an early pipeline stage, and does not require the potentially more expensive results from later stages. In such cases, although preserving the ordering of the pipeline, PRMan may terminate the pipeline early - having obtained the results it needs. Subsequently, in certain cases, PRMan may require results from later pipeline stages. If earlier pipeline stages have already been executed there are cases where the renderer may simply provide the shader with values cached from the previous invocation and will skip that earlier pipeline stage, proceeding to the stage from which results are now needed. Skipping pipeline stages has some implications for the shader's ability to later rely on the state of member variables and other side effects from running the potentially skipped stage. These implications are discussed below.

RSL and opacity()

Before we further discuss the various combinations of lighting pipeline methods, an earlier stage - opacity() - bears some discussion.

The opacity() method serves three purposes: providing opacity values for camera rays, controlling compositing for surfaces and volumes; controlling opacity seen by transmission rays -- modulating shadows cast by thin, partially transparent surfaces; and, controlling the continuation of diffuse and specular rays -- providing the hold-out functionality of occupancy maps. Understanding when the method is called, and what it may contain, is key to ensuring artifact-free pictures.

ライティング Methods in RSL

RSL 2.0 introduced the lighting() method - designed to return all interaction between a shading element and the lighting in the scene. Subsequently, diffuselighting() and specularlighting() were introduced in order to allow the renderer to distinguish between view-independent and view-dependent shading. By separating these computations, the renderer is able to make optimizations resulting in more performant renders. The intended purpose of each method is given in the following.

The diffuselighting() method may be skipped if a value for its result is available in the cache. The pipeline will resume at specularlighting() with the Ci that was read from the cache. It should be noted that when caching occurs, the pipeline is run up to diffuselighting() on a different shading manifold or grid than that which will be shaded upon for later specular contributions. The shading invocations are separate and results other that Ci and Oi are not preserved. This means that values of member variables and output variables set in diffuselighing() should not be relied upon during later stages of the pipeline.

Pipeline methods may be invoked under a number of different situations with differing shading requirements:

• camera shading for REYES hider
• camera ray in raytrace hider
• specular ray
• diffuse ray

public void lighting(output color Ci,Oi) {
        string raytype = "";
        rayinfo("type",raytype);

        //... compute diffuse

        if (raytype != "diffuse") {
                //... compute specular
        }
}

Pipeline Summary

Grubby Details and Expert Settings

Presented so far has been the default out-of-box behavior for PRMan. Further to the caching scenarios presented above, there exist additional opportunities for caching, each with their own compromises. The details of these modes are subject to change and are documented here for expert use only. Due to the scene-dependent nature of the benefits of these modes, it is not clear that they should be employed by default. The setting are available via an .ini setting. We would welcome feedback on your experiences with these modes should you choose to experiment with them.

PRMan 17 now supports caching of results in the REYES hider, which can be shared between diffuse-depth 0 (specular rays). This is permitted by extending the interface for the lighting() method:

public void lighting(output color Ci, Oi, radiosity) {
    //...
}

or:

public void lighting(output color Ci, Oi, radiosity, irradiance) {
    //...
}

In both cases, the radiosity must be a view-independent diffuse entity. Irradiance must also be view-independent. An appropriate cache mode must also be used. When enabled, REYES caching may also use results cached from running diffuselighting() during a specular ray. In that case, the REYES grid is shaded with specularlighting() and the results from the cache lookup are available in Ci. This may break expectations in some shaders that assume specularlighting() is only ever invoked at the end of a ray. Note, if these optional parameters exist they must be filled with valid value. Otherwise, the respective caches will be filled with garbage values.

PRMan 17 also changed the semantics for caching on the end of specular rays. Previously, specular ray shading was divided up into a cacheable invocation of diffuselighting() and an uncached, per-ray invocation of specularlighting(). It is not clear that this is always beneficial, and in some cases the reuse rate of the cached diffuse entity was not high enough to warrant splitting the computation. This is in part due to the tradeoff between reuse via the cache and its implication that transmission rays will occur separately for the diffuse and specular lobes (see above).

The caching opportunities are outlined below:

The cache mode may be controlled by the rendermn.ini switch /prman/shade/__cachemode, or Option "shade" "int __cachemode" [i]. Possible values are:

0 - Caching disabled. No opacity, irradiance, or diffuse results are cached.

1 - Cache opacity, irradiance, and diffuse for transmission, diffuse, and subsurface rays. Transmission rays are generated when ray tracing shadows,for instance the areashadow() and transmission() shadeops. Typically, the heaviest generator of diffuse rays is the indirectdiffuse() shadeop. Subsurface is not formally a type of ray, it is a diffuse ray with the subsurface label, generated during execution of the ray-traced version of the subsurface() shadeop.

All further modes build upon mode 1. In other words, if caching is on, the renderer always caches for diffuse rays. The remaining modes are divided into two groups, caching diffuse on the end of specular rays (or not). Within each group are the four combinations of caching shading for primary grids -- those shaded for either the REYES hider or the ray traced hider.

2 - In addition to case 1, cache diffuse for REYES grids. REYES grids can't share with one another, they can only share with specular rays (e.g. indirectspecular()) and subsurface rays (cast by subsurface()). Since this mode does not cache on specular rays, it would be chosen only for a scene that makes heavy use of raytraced subsurface scattering.

3 - (default) In addition to case 1, cache diffuse for camera rays (the ray traced hider, not REYES grids). Cached shading precludes using a different time value for each ray. In the event that temporal effects are needed on camera rays, caching of diffuse on camera rays should be not be used. Because of the spatial coherence of rays generated by the raytrace hider, caching diffuse on camera rays provides a substantial speed-up.

4 - In addition to case 1, cache diffuse for REYES grids and ray-traced camera rays. Choosing this mode allows one to switch between hiders and maintain the same caching behavior.

Modes 5 through 8 are the same as modes 1 through 4 with the addition of caching for specular rays.

5 - Cache on diffuse and specular rays.

6 - Cache on diffuse rays, specular rays, and REYES grids.

7 - Cache on diffuse, specular, and camera rays. (PRMan 16 behavior).

8 - Cache on diffuse rays, specular rays, camera rays, and REYES grids. For the REYES hider, standard REYES shading will attempt to use diffuse results previously cached as the result of running diffuselighting() on the end of a specular ray. If no cache is found, one will be made and potentially used by future specular rays.

Best Practices

• Do not use depth, speculardepth or rayinfo("type",...) queries in diffuselighting().
• Do not use depth, speculardepth or rayinfo("type",...) queries in opacity(), with the exception of checking raytype == "transmission" when __computesOpacity == 2.
• Return view independent results from diffuselighting().
• If using extended REYES caching (extra outputs to lighting()), ensure their results are view-independent and match the computation in diffuselighting().