New or Extended RSL Functions

  gather (string category, point P, vector dir, float angle, float samples, ...)
        statement [else statement]

The gather looping construct collects information, usually color, from surfaces via ray tracing.  It is somewhat analogous to illuminance loops, which collect direct light from light sources. Rays are cast within the cone specified by P, dir and angle.  The angle, in radians, is measured from dir, the central axis of the cone; an angle of zero implies that rays should only be cast in direction dir, whereas PI/2 produces sampling over a hemispherical area.  Within this region, samples rays are stochastically distributed, so increasing the cone angle increases the blurriness; increasing the number of samples increases the quality.  When a ray intersection occurs, the optional output variables are updated with values obtained from the hit surface.  The loop statements are executed repeatedly, once for each sample pass. Code in the first statement block will be executed when a sample ray hit occurs; code in the else block will be executed when no ray intersection is found.  For example:

  uniform float samples = 16;
  vector R = reflect(I,N);
  color hitcolor = 0;

  Ci = 0;

  gather("illuminance", P, R, radians(5), samples, "surface:Ci", hitcolor) {
     Ci += hitcolor;
  } else {
     Ci += environment("skymap.env", R);
  }
  Ci = Ci / samples;

For a more detailed discussion, and a complete list of options, see the full gather description.

Optional token-value parameters:

Input parameters	Output parameters
"bias" (float) "maxdist" (float) "samplebase" (float) "distribution" "uniform" or "cosine" "label" (string) "subset (string)	"shadertype:varname" (variable) "primitive:varname" (variable) "ray:origin"  (point) "ray:direction" (vector) "ray:length" (float)

color trace( point P, vector dir )

returns the color associated with the nearest hit point determined by tracing a single ray from point P in direction dir.  Trace can now be thought of as a convenience function implemented as a one-sample gather call:

color trace(point P, vector dir)
{
    color result = 0;
    gather("illuminance", P, dir, 0, 1, "surface:Ci", result);
    return result;
}

color transmission( point Psrc, point Pdst, ... )

casts a special ray type whose purpose is to evaluate the transmission function between two arbitrary points in current space.  Transmission rays are different from trace rays because their purpose isn't to find the nearest hit but rather the ability of light to move from point to point.  Transmission is usually called in light shaders to determine whether a surface point is in shadow.  Unlike trace rays, transmission rays can terminate as soon as they encounter a completely opaque object, even if it wouldn't turn out to be the nearest object after a complete search of the database. Intersection tests are governed by the   Attribute "visibility" "transmission"  value associated with each primitive.  Optional token-value parameters are:

Input parameters

"samples" (uniform float) "samplecone" (float) "samplebase" (float) "bias" (uniform float) "label" (string) "subset" (string)

Note: It is not always appropriate to specify samples and samplecone directly in the transmission() call. In some LightSource shaders, the caller may need to apply some sort of specific fall-off or other variation to each sub-sample result which must be done per-trace, not on the averaged result of the sub-sample traces.

Built-in subsampling can be used to produce simple blurred soft shadows, similar to what would be produced by a spherical area light, where the shadow blur increases as a function of the relative distances between the light source, the occluding object, and the shadowed surface.  In this case it is important to use the correct order of Psrc and Pdst so that the cone angle has its apex at the surface position, Ps.  Here's a simple example LightSource shader:

light
transmissionpoint (
    	point from = point "shader" (0,0,0);
	float samples = 1;
	float blur = 0;)
{
     illuminate( from ) 
     {
         Cl = transmission(Ps, from, "samples", samples, "samplecone", blur);
     }
}

uniform float rayinfo( uniform string keyword, result, ... )

Provides access to state associated with the ray which resulted in the shader execution.  rayinfo fills in result with the current value associated with the query keyword.   Returns 1 or 0 to indicate whether the query succeeded or not.   For example:

uniform float d=0;
success = rayinfo("depth", d);
if (d < 3) {
    /* typical shading */
} else {
    /* we're shading for the third or deeper reflection bounce
     * so do something cheaper than usual
     */
}

Keywords:

• "speculardepth", uniform float speculardepth
  returns the specular depth of the ray which caused this shader to be invoked.
• "diffusedepth", uniform float diffusedepth
  returns the diffuse depth of the ray which caused this shader to be invoked.
• "shadowdepth", uniform float shadowdepth
  returns the "shadow depth" of the ray which caused this shader to be invoked. Shadow depth is 1 if this is a shadow ray and 0 otherwise.
• "depth", uniform float depth
  returns the current depth of the ray which caused this shader to be invoked. Depth is the sum of speculardepth, diffusedepth, and shadowdepth. Depth is 0 for camera rays (i.e. standard REYES invocation).
• "type", uniform string type
  returns the type of the ray which caused this shader to be invoked. These are built-in types, distinguished by fundamentally different handling of the ray within the renderer. Note that ray labels (next item) are used to associate user-defined names to rays. The current ray types returned are:
  • camera
  • light
  • specular
  • diffuse
  • transmission
• "label", uniform string label
  returns the value of the user-defined label assigned to the ray which caused this shader to be invoked. Labels are assigned via the "label" parameter to the gather(), transmission(), shadow(), environment(), etc. functions.
• "origin", uniform point origin
returns the origin of the ray.  For camera rays, this is equivalent to E.
• "direction", varying vector direction
returns the normalized ray direction.  For camera rays, this is equivalent to I/|I|.
• "length", varying float length
returns the length of the ray. For camera rays, this is equivalent to |I|.

color environment( string filename[channel], ... )
float environment( string filename[channel], ... )

returns the color of an environment map lookup.  This function has been extended such that when provided with the reserved filename, "raytrace", calls to trace will be substituted for standard environment map lookups.  The float version returns coverage, which is the fraction of rays which hit something; when samples=1 then the result will be either 0 or 1. When ray tracing environments, the following optional parameters are supported:

• "blur" (float) - controls the samplecone of the underlying trace call.
• "samples" (uniform float) - controls the samples of the underlying trace call.
• "bias" (uniform float) - an offset used to prevent self intersection artifacts.
• "coverage" (output varying float) - returns the alpha value of the environment map or the coverage of the underlying trace call.
• "opacity" (output varying color) - returns the opacity of the environment or the underlying trace call.
• "label" (uniform string) - applies a label to the underlying trace call.
• "subset"  (uniform string) - specifies that traced environments only consider objects that are members of the provided group name.
• "maxdist" (uniform float) - specifies that traced environments only consider objects closer than the provided distance.

color shadow( string name, ... )
float shadow( string name, ... )

returns the degree to which the current surface point is in shadow from the point of view of the current light position.  This function has been extended such that when provided with the reserved filename, "raytrace", calls to transmission will be substituted for standard shadow map lookups.  When ray tracing shadows, the following optional parameters are supported:

• "blur" (float)   - controls the ray traced shadow blurriness.   Units are radians, describing the half-angle of the sample cone.   The effect is similar to sampling a spherical light source of finite size. You should almost always increase the number of samples as the blur cone increases to reduce noise.
• "samples" (uniform float)   - causes supersampling of the underlying transmission function.
• "label" (uniform string)   - applies a label to the shadow rays, it can be queried by shaders on hit surfaces.
• "subset" (uniform string)   - shadows rays will only be tested against objects that are members of the named groups.

color caustic (point P, normal N)

returns the result of a photon map lookup at surface point P with surface normal N.  This convenience function can be expressed as:

color caustic(point P, normal N)
{
    uniform string causticmap = "";
    uniform float estimator = 50;
    color result;
    attribute("photon:causticmap", causticmap);
    attribute("photon:estimator", estimator);
    if( causticmap != "" ) {
        result = photonmap(causticmap, P, N, "lookuptype", "irradiance", "estimator", estimator);
    } else {
        result = color(0);
    }
    return result;
}

color photonmap( string filename, P, N, ... )

returns the result of a photonmap lookup at surface point P with surface normal N.  This function is the basis of PRMan's caustic effects.  Parameters include:

• "lookuptype" (uniform string)
  • "radiance" - looks up the radiance - after interacting with the surface BRDF.
  • "irradiance" - looks up the irradiance - prior to local BRDF interaction.
• "estimator" (uniform float) - specifies the number of photons to consider when estimating photon effect.

float irradiancecache(string operation, string handle, string filemode, 
                        point P, normal N, ...)

performs an irradiance cache operation on the cache given by handle. The cache can be queried or updated according to operation.  The interpretation of the return value depends on operation.  If the operation is "query"  the (varying) return value (1 or 0) indicates the  success or failure of the cache query.  This is determined by comparing values stored in the cache against the optional error metric parameters:

• "maxerror" (float)
• "maxpixeldist" (float)

Required parameters:

• string operation
  • "query"
performs a lookup of the requested quantities and returns (varying) 1 or 0 indicating success or failure of the cache query according to the optional error metrics.
  • "insert"
inserts the provided quantities into the cache, ostensibly obtained with a gather-"illuminance" statement.  Always returns (varying) 1.
• string handle
the handle to the irradiance cache.  There is no limit to the number of irradiance caches but only a single cache can be associated with a given primitive.  Usually, the handle is a file name whose usage is determined by the value of filemode.
• string filemode
controls whether the live cache is seeded from an existing cache file as well as whether to store the cache when rendering concludes.
  • "r" - seed the cache with a filename given by handle.  If this file doesn't exist, the cache will be initialized in the empty state.
  • "w" - on completion of the current rendering pass, specifies that the filename given by handle should be updated with the current cache state.
  • "rw" - seed the cache with a file given by handle.  As rendering progresses, the cache associated with handle will improve when updates are made.  On completion of the current rendering pass, the current cache state will be written to file given by handle.
  • "R" - rely purely on the irradiance data in the file specified by handle. This irradiance data will be interpolated; no new irradiance data will be computed, making rendering fast. 
  • "" - initialize the cache to the empty state, don't save the values when rendering completes.
• point P, normal N
describes the hemisphere for which the irradiance estimate is desired.

If the operation is "insert" an additional set of parameters are required. These will be used to guide later queries.

• "mindist" (float) - the minimum hit distance associated with a gather statement.
• "harmonicmeandist" (float) - the  harmonic mean distance is the inverse of the average of inverse ray lengths.  In Shading Language:

  float hmeandist = 0;
  gather("illuminance", P, N, PI/2, samples, "ray:length", raylength)
  {
      hmeandist += 1 / raylength;
  }
  hmeandist = samples / hmeandist;

The irradiance cache currently holds 3 quantities.  Depending on the operation (query or insert), these values will be construed as outputs or inputs.

• "irradiance" (color)
refers to the integrated incoming illumination at a point.
• "coverage" (float)
refers to the percentage of the hemisphere occupied by "hit-able" geometry.
• "environmentdir" (vector)
refers to the average un-occluded direction.  This direction can be used for environment map (HDRI) lookups but represents an approximation.  For a more precise result you may need to forego cache lookups and perform all environment lookups directly on gather "misses".

color indirectdiffuse( point P, normal N, float samples, ... )

indirectdiffuse returns diffuse illumination arising from indirect illumination. Effects such as "color bleeding" arise through the diffuse-to-diffuse indirect light transport paths are captured via the indirectdiffuse function.  Note that the indirectdiffuse function can be expressed in terms of gather and irradiancecache accesses and is provided as a convenience.  Required parameters:

• P, N, samples - controls super-sampling of the underlying indirect illumination function.  The super-sampling region is defined to be the hemisphere centered about the surface normal N at point P.

Optional parameters are specified as name/value pairs:

• "subset" name - specifies the (string) name of a trace subset.  Only members of this subset will be considered when performing intersection calculations.
• "maxdist" dist - specifies the (float) maximum distance to consider when performing intersection calculations.
• "environmentmap" (uniform string) - specifies the name of an environment map to consult when ray probes don't hit local geometry.
• "environmentspace" (uniform string) - specifies the name of a coordinate system to apply when accessing the environment map.
• "environmentdir" (output varying vector) - specifies and optional output variable to fill with the average un-occluded direction.  This direction is obtained by averaging the directions of all samples that fail to hit local geometry.
• "occlusion" (output varying float) - specifies an optional output variable to fill with the percentage of the samples that hit local geometry.

float occlusion( point P, normal N, float samples, ... )

occlusion returns the percentage of samples that hit local geometry. This convenience function hides the complexities of irradiance caching and returns, using ray tracing, an estimate of the degree to which P is occluded by local geometry to the environment illumination.  occlusion is a faster variant of indirectdiffuse because it doesn't estimate color bleeding.  

Options include:

• "subset" name (uniform string) - specifies the name of a trace subset.  Only members of this subset will be considered when performing intersection calculations.
• "maxdist" dist (float) - specifies the (float) maximum distance to consider when performing intersection calculations.
• "environmentmap" map (uniform string) - specifies the name of an environment map to consult when ray probes don't hit local geometry.
• "environmentspace" (uniform string) - specifies the name of a coordinate system to apply when accessing the environment map.
• "environmentdir" dir (output varying vector) - specifies and optional output variable to fill with the average un-occluded direction.  This direction is obtained by averaging the directions of all samples that fail to hit local geometry.
• "environmentcolor" c (output color) - specifies the optional output variable to fill with the color resulting from environment map lookups on unnoccluded samples.  If no environment map is provided, the environment color will be black.

float gridpattern( string pattern, float context, ... )

generates patterns associated with the underlying shading grid. The context variable is used to carry state from one call to the next and the meaning and usage of context depends on pattern.  Usually context should be initialized to 0 prior to first use.  Each pattern will modify context differently and generally it should be assumed that context is private data owned by gridpattern. For those renderers that support multi-point (SIMD) shader execution models, this function can be used in conjunction with the while construct to perform operations on specific patterns on the grid. Note that the use of while on varying data can be very subtle. In standard usage, SIMD runflags are cumulative through each iteration of the body. When used with gridpattern, the cumulative optimization must be defeated with the inclusion of the newly introduced run-flag mode control for the while loop construct. Now, the (varying) return value of gridpattern can be compared for equality with (uniform) 0 to generate run flags that enable execution of a statement on non-zero grid points.   Some patterns guarantee convergence in the sense that after a series of calls, all grid points will have been "visited" and additional calls will result in (varying) 0 values.  The "binaryrefinement" pattern can be used to build up an irradiance cache because of its convergence property.  Currently supported grid patterns are:

• "binaryrefinement" (convergent)
• "gridpoint" (convergent)
• "checkerboard" (non-convergent)
• "random" (non-convergent)