The following are excerpted from PRMan docs. As a result, links in them won't work.
-Saty

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:


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:


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:


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:


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:

Required parameters:

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

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


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:

Optional parameters are specified as name/value pairs:


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:


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: