float Du( float p ), Dv( float p ), Deriv( float num; float den )
color Du( color p ), Dv( color p ), Deriv( color num; float den )
point Du( point p ), Dv( point p ), Deriv( point num; float den )
vector Du( vector p ), Dv( vector p ), Deriv( vector num; float den )

These functions compute the derivatives of their arguments. The type returned depends on the type of the first argument. Du and Dv compute the derivatives in the u and v directions, respectively. Deriv computes the derivative of the first argument with respect to the second argument. This is done using the chain rule:

Deriv(num,den) = Du(num)/Du(den) + Dv(num)/Dv(den);

The actual change in a variable is equal to its derivative with respect to a surface parameter times the change in the surface parameter. Thus, assuming forward differencing:

function(u+du)-function(u) = Du( function(u) ) * du;
function(v+dv)-function(v) = Dv( function(v) ) * dv;

float erf( float x )
float erfc( float x )

The erf function returns the error function of x, which is defined to be erf(x) = (2 / sqrt(PI)) * (the integral from 0 to x of e^(-t^2) dt). The erfc function returns the complementary error function of x, that is 1.0 - erf(x).

float filterstep( float edge, s1;  [parameterlist]  )
float filterstep( float edge, s1, s2;  [parameterlist]  )

filterstep provides an analytically antialiased step function.  In its two argument form, it takes parameters identical to step, but returns a result that is filtered over the area of the surface element being shaded. If the optional s2 parameter is provided, the step function is filtered in the range between the two values.  This low-pass filtering is similar to that done for texture maps (for reference, see Texture Mapping Functions). The parameterlist provides control over the filter function, and may include the following parameters: "width" (a.k.a. "swidth"), the amount to "overfilter" in s; "filter", the name of the filter kernel to apply.  The filter may be any of the following: "box", "triangle", "catmull-rom", or "gaussian".  The default filter is "catmull-rom".

float floor( float x )
float ceil( float x )
float round( float x )

floor returns the largest integer (expressed as a float) not greater than x. ceil returns the smallest integer (expressed as a float) not smaller than x. round returns the integer closest to x.

float gridmin(varying float myVal)
float gridmax(varying float myVal)

gridmin and gridmax operate over a grid of floats and return a uniform result. These functions will find the max/min of all the values of myVal over the surface of the grid currently being shaded. The result can be varying, however the same value will be returned at all points in the varying result value.

type min(type a, b, ... )
type max( type a, b, ... )
type clamp( type a, min, max )

min takes a list of two or more arguments of identical type and returns the argument with minimum value, max returns the argument with maximum value.  clamp returns min if a is less than min, max if a is greater than max, otherwise it returns a.  The type may be any of float, point, vector, normal, or color.  The variants that operate on colors or point-like objects operate on a component-by-component basis (i.e. separately for x, y, and z).

float mix( float x, y; float alpha )
point mix( point x, y; float alpha )
vector mix( vector x, y; float alpha )
normal mix( normal z, y; float alpha )
color mix( color x, y; float alpha )
point mix( point x, y; color alpha )
vector mix( vector x, y; color alpha )
normal mix( normal z, y; color alpha )
color mix( color x, y; color alpha )

mix returns x * (1-alpha) + y * alpha, that is, it performs a linear blend between values x and y.  The types of x and y must be identical, but may be any of float, point, vector, normal or color.  The variants that operate on colors or point-like objects operate on a component-by-component basis (i.e. separately for x, y, and z); for these variants, either a float or a color alpha may be specified. If a float alpha is used each component is weighed by the same alpha, otherwise the appropriate channel on a component-by-component basis is used.

float mod( float a, b )
float abs( float x )
float sign( float x )

mod returns a value greater than 0 and less than or equal to b such that mod(a,b) = a - n*b for some integer n. abs returns the absolute value of its argument and sign returns -1 if its argument is negative, 1 if its argument is positive, and 0 if its argument is zero.

float noise( float v ),
      noise( float u, v ),
      noise( point pt ),
      noise( point pt, float t )
color noise( float v ),
      noise( float u, v ),
      noise( point pt ),
      noise( point pt, float t )
point noise( float v ),
      noise( float u, v ),
      noise( point pt ),
      noise( point pt, float t )
vector noise( float v ),
       noise( float u, v ),
       noise( point pt ),
       noise( point pt, float t )

noise returns a value that is a pseudorandom function of its arguments; its value is always between 0 and 1. The domain of this noise function can be 1D (one float), 2D (two floats), or 3D (one point), or 4D (one point and one float). These functions can return any type. The type desired is indicated by casting the function to the type desired. The following statement causes noise to return a color.

c = 2 * color noise(P);

float  cellnoise( float v ),
       cellnoise( float u, v ),
       cellnoise( point pt ),
       cellnoise( point pt, float t )
color  cellnoise( float v ),
       cellnoise( float u, v ),
       cellnoise( point pt ),
       cellnoise( point pt, float t )
point  cellnoise( float v ),
       cellnoise( float u, v ),
       cellnoise( point pt ),
       cellnoise( point pt, float t )
vector  cellnoise( float v ),
        cellnoise( float u, v ),
        cellnoise( point pt ),
        cellnoise( point pt, float t )

cellnoise returns a value that is a pseudorandom function of its arguments.  Its domain can be 1D (one float), 2D (two floats), 3D (one point), or 4D (one point and one float).  Its return value is uniformly distributed between 0 and 1, has constant value between integer lattice points, and is discontinuous at integer locations.  This is useful if you are dividing space into regions ("cells") and want a different (repeatable) random number for each region.  It is considerably cheaper than calling noise, and thus is preferable if you have been using noise simply to generate repeatable random sequences.  The type desired is indicated by casting the function to the type desired.

float knoise( filterregion fr, uniform float freqWindow,
              "keyword", value );

knoise is similar to Gabor Noise (Siggraph 2009), with many of the same properties. In particular, it is filtered and gives the user control over the frequency window, number of octaves, and amount and direction of anisotropy. Like Gabor noise it works by using a random collection of nearby points to splat values onto the lookup point. It takes a filterregion as its input, which means that it can generate 1d, 2d, and 3d noise values, filtered either over the local surface or the local volume, depending upon the underlying object.

The freqWindow parameter controls the range of frequencies that will be generated. A larger value here results in something that looks closer to white noise, while a smaller value give much more uniform frequencies and a more "structured" appearance. Useful values tend to be in the range of .5 or so to 1.2, or so.

float pnoise( float v, uniform float period ),
      pnoise( float u, v, uniform float uperiod, uniform float vperiod ),
      pnoise( point pt, uniform point pperiod ),
      pnoise( point pt, float t, uniform point pperiod, uniform float tperiod )
color pnoise( float v, uniform float period ),
      pnoise( float u, v, uniform float uperiod, uniform float vperiod ),
      pnoise( point pt, uniform point pperiod )
      pnoise( point pt, float t, uniform point pperiod, uniform float tperiod )
point pnoise( float v, uniform float period ),
      pnoise( float u, v, uniform float uperiod, uniform float vperiod ),
      pnoise( point pt, uniform point pperiod ),
      pnoise( point pt, float t, uniform point pperiod, uniform float tperiod )
vector pnoise( float v, uniform float period ),
       pnoise( float u, v, uniform float uperiod, uniform float vperiod ),
       pnoise( point pt, uniform point pperiod ),
       pnoise( point pt, float t, uniform point pperiod, uniform float tperiod )

pnoise returns a value similar to noise with the same arguments; however, the value returned by pnoise is periodic with period, period (or pperiod, tperiod, et cetera). That is, pnoise(v, p) == pnoise(v+p, p). The period parameters must be uniform and have an integer value (if it is a float expression), or lie on the integer lattice (if it a point expression).

float wnoise( point pt; float filterWidth; [parameterlist] )

wnoise produces one or more bands of noise constructed with wavelets, and is based on the 2005 SIGGRAPH paper by Cook and DeRose. Wavelet noise has a similar appearance to Perlin noise but can be band-limited more effectively for the sake of antialiasing. Unlike the noise function, which returns values between 0 and 1, wnoise by default returns values between -1 and 1. The distribution and range of these values may be changed using the parameters below, though output values are always centered around 0.

The filterwidth parameter is used to filter any frequencies that would otherwise alias and represents the width of the filter, usually calculated by approximating the width of a micropolygon:

float fw = max(sqrt(area(P)), (2e-6));
float fn = wnoise(P, fw);

Optional wnoise parameters are specified as name/value pairs.

float PI = 3.14159... ;
float radians( float degrees )
float degrees( float radians )
float sin( float a )
float asin( float a )
float cos( float a )
float acos( float a )
float tan( float a )
float atan( float yoverx ), atan( float y, x )

The predefined float constant PI is the value of pi. The function radians converts from degrees to radians, and, conversely, the function degrees converts from radians to degrees. sin, cos, and tan are the standard trigonometric functions of radian arguments. asin returns the arc sine in the range -PI/2 to PI/2. acos returns the arc cosine in the range 0 to PI. atan with one argument returns the arc tangent in the range -PI/2 to PI/2. atan with two arguments returns the arc tangent of y/x in the range -PI to PI.

void sincos( float a, output float sina, output float cosa )

The sincos() function performs both the standard trigonometric functions sine and cosine simultaneously.

float pow( float x, y )
float exp( float x )
float sqrt( float x )
float inversesqrt( float x )
float log( float x ), log( float x, base )

These functions compute power and inverse power functions. pow returns x ** y, exp returns pow(e,x). sqrt returns the positive square root of x, and inversesqrt returns 1/sqrt(x). log with one argument returns the natural logarithm of x (x = log(exp(x))). log with two arguments returns the logarithm in the specified base (x = log(pow(base, x), base)).

float random()
color random()
point random()

random returns a float, color, or point whose components are a random number between 0 and 1.

float randomgrid()
color randomgrid()

randomgrid returns a random uniform float or color per grid.

float spline([string basis;] float value; float f1, f2, ..., fn, fn1 )
float spline([string basis;] float value; float fvals[] )
color spline([string basis;] float value; color c1, c2, ..., cn, cn1 )
color spline([string basis;] float value; color cvals[] )
point spline([string basis;] float value; point p1, p2, ..., pn, pn1 )
point spline([string basis;] float value; point pvals[] )
vector spline([stringbasis;] float value; vector v1, v2, ..., vn, vn1 )
vector spline([string basis;] float value; vector vvals[] )

spline fits a spline to the control points given.  At least four control points must always be given.  If value equals 0, f2 (or c2, p2, v2) is returned; if value equals 1, fn (or cn, pn, vn) is returned.  The type of the result depends on the type of the arguments.

If the first argument to spline is a string, it is interpreted as the name of a cubic spline basis function.  The basis may be any one of "catmull-rom", "bezier", "bspline", "hermite", "monotonecubic" or "linear". If the optional basis name is not supplied, "catmull-rom" is assumed, resulting in the control points being interpolated by a Catmull-Rom spline. In the case of Bezier and Hermite spline bases, the number of spline knots must be 4+3n and 4+2n, respectively. In the case of monotone cubic, the first and last knot inform the incoming and outgoing tangents, and the remaining knots are interpolated through, increasing or decreasing monotonically between adjacent knots. In the case of linear spline basis, the first and last knot are unused but are nonetheless required to maintain consistency with the cubic bases.

For all spline types, an array of values may be used instead of a list of values to specify the control points of a spline. Additionally, each basis has an associated "solve" mode (e.g. "solvelinear") that is used to position the control points, e.g.:

float signal = spline ( "solvecatmull-rom", s, 0, 0, .2, .8, .1, 1 );

color result = spline ( "catmull-rom", signal, (0,0,0), (0,0,0), (1,1,0),
                       (1,1,1), (1,1,1) );

float step( float min, value )
float step( color min, value )
float smoothstep( float min, max, value )
float smoothstep( color min, max, value )

step returns 0 if value is less than min; otherwise it returns 1. smoothstep returns 0 if value is less than min, 1 if value is greater than or equal to max, and performs a smooth Hermite interpolation between 0 and 1 in the interval min to max. When using versions of these operators that work on color arguments, the operation is applied on a component-by-component basis.

float area( point P [; string measure] )

{
  return length( Du(P)*du ^ Dv(P)*dv);
}

Return the differential surface area. If measure is "shading" or isn't supplied, the areas are smoothly varying across shading grids, independent of the actual dicing rates. If measure is "dicing", the areas are the areas of micropolygons (and therefore discontinuous between shading grids with different dicing rates).

When shading a volume element, the area shadeop returns the approximate area of a circle with diameter equal to the diagonal of the voxel. This may be a poor approximation of the spot size, particularly if the voxels are highly isotropic due to depthrelativeshadingrate, and is not generally recommended for antialiasing of shaders.

normal calculatenormal( point P )

{
  return Du(P) ^ Dv(P);
}

Return surface normal given a point on the surface. This function is usually called after a displacement. For example:

P += displacement * N;
N = calculatenormal( P );

float depth( point P )

Return the depth of the point P in camera coordinates. The depth is normalized to lie between 0 (at the near clipping plane) and 1 (at the far clipping plane).

float distance( point P1, P2 )

{
  return length(P1-P2);
}

Return the distance between two points.

vector faceforward( vector N, I [, Nref = Ng] )

{
  return sign(-I.Nref) * N;
}

Flip N so that it faces in the direction opposite to I, from the point of view of the current surface element. The surface element's point of view is the geometric normal Ng, unless Nref is supplied, in which case it is used instead.

void fresnel( vector I, N; float eta, output float Kr, Kt
              [; output vector R, T] )

Return the reflection coefficient Kr and refraction (or transmission) coefficient Kt given an incident direction I, the surface normal N, and the relative index of refraction eta. eta is the ratio of the index of refraction in the volume containing the incident vector to that of the volume being entered. These coefficients are computed using the Fresnel formula. Optionally, this procedure also returns the reflected (R) and transmitted (T) vectors. The transmitted vector is computed using Snell's law. The angle between I and N is supposed to be larger than 90 degrees. If the angle is less than 90 degrees, fresnel will return full reflection (Kr = 1, Kt = 0).

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

gridpattern returns a one or a zero for each shading point, according to the specified pattern and context. Like other varying functions, gridpattern returns a result which may be different at each shading point on the underlying grid; however, unlike most other functions, the output is intentionally a function of the shading grid's structure. It is typically used to produce a mask using one of the built-in pattern generators, the mask is then used in a varying conditional to apply specific operations to the on subset of points. Furthermore, some patterns can be applied iteratively, in conjunction with a preserved context, and will become successively more refine in terms of the sets of points selected, until all of the points on the grid have been visited.

The available patterns are:

[1]	(1, 2) Some patterns have undefined results on non-rectangular internal grid types

The context variable is used to carry state between iterative calls to gridpattern; the meaning and usage of context depends on pattern. Usually context should be initialized to zero prior to first use. Each pattern will modify context differently and it should generally be assumed to be private data owned by gridpattern. Some patterns guarantee convergence in the sense that after a series of calls, all grid points will have been "visited" and further calls will return zero for all points.

The shading language supports several familiar conditional constructs which cause operations to occur on grid subsets; consider:

if (s < 0.5) k += 1;

The varying variable k will only be incremented at the points which satisfy the condition. Similarly, gridpattern produces a varying float mask which is 1 for some points, 0 for others. This mask might be used directly (as a float) or used in further conditional expressions.

For example, for a shader executing on a tiny 5x5 grid:

varying float patctx = 0;  /* initialize the context */
varying float f = gridpattern("concentric", patctx);

the variable f will now contain the following pattern:

1 1 1 1 1
1 0 0 0 1
1 0 0 0 1
1 0 0 0 1
1 1 1 1 1

the patctx variable allows gridpattern to track a particular context through repeated calls, so a subsequent call to:

varying float g = gridpattern("concentric", patctx);

would produce, in g:

0 0 0 0 0
0 1 1 1 0
0 1 0 1 0
0 1 1 1 0
0 0 0 0 0

and f+g would be:

1 1 1 1 1
1 1 1 1 1
1 1 0 1 1
1 1 1 1 1
1 1 1 1 1

After another iteration (in which only the center spot would be one), the pattern will have "converged," meaning that all of the gridpoints will have been visited and subsequent calls to gridpattern (with the same context variable) will return all zeros.

Another pattern type, named "binaryrefinement", tries to select a few widely spaced points for the first pass, and then more points which are less widely spaced for the second pass, etc., until all points have been visited.

The while "any" construct allows looping on gridpattern calls until a convergence occurs. In this mode a different set of gridpoints will be active during each iteration. So a typical convergence loop might look like this:

while "any" (0 != gridpattern("binaryrefinement", patctx)) {
    /* do things on this subset */
}

See the gridpattern() example for an illustration.

float length( vector V )

{
       return sqrt(V.V);
}

Return the length of a vector.

vector normalize( vector/normal V )

{
       return V/length(V);
}

Return a unit vector in the direction of V.

float ptlined( point P1, P2, Q )

Returns the minimum perpendicular distance between the point Q and the line segment that passes from the point P1 to the point P2 (not the infinite line that passes through P1 and P2).

vector reflect( vector I, N )

{
  return I - 2*(I.N)*N;
}

Return the reflection vector given an incident direction I and a normal vector N.

vector refract( vector I, N; float eta )

{
  float IdotN = I.N;
  float k = 1 - eta*eta*(1 - IdotN*IdotN);

  return k < 0 ? (0,0,0) : eta*I - (eta*IdotN + sqrt(k))*N;
}

Return the transmitted vector given an incident direction I, the normal vector N and the relative index of refraction eta. eta is the ratio of the index of refraction in the volume containing the incident vector to that of the volume being entered. This vector is computed using Snell's law. If the returned vector has zero length, then there is no transmitted light because of total internal reflection.

point rotate( point Q; float angle; point P1, P2 )

Rotate a point Q by angle radians about the axis that passes through the points P1 and P2.

point transform( string tospace; point P );
point transform( string fromspace, tospace; point P );
point transform( matrix m; point P );
point transform( string fromspace; matrix m; point P );
vector vtransform( string tospace; vector v );
vector vtransform( string fromspace, tospace; vector v );
vector vtransform( matrix m; vector v );
vector vtransform( string fromspace; matrix m; vector v );
normal ntransform( string tospace; normal  );
normal ntransform( string fromspace, tospace; normal n );
normal ntransform( matrix m; normal n );
normal ntransform( string fromspace; matrix m; normal n );

The transform function transforms the point P from the coordinate system fromspace to the coordinate system tospace.  If fromspace is absent, it is assumed to be the "current" coordinate system.  A transformation matrix may be given instead of a tospace name.  The vtransform and ntransform functions perform the equivalent coordinate system transformations on vectors and normals, respectively.

float xcomp( ptype P )
      ycomp( ptype P )
      zcomp( ptype P )
      setxcomp( ptype P; float x )
      setycomp( ptype P; float y )
      setzcomp( ptype P; float z )

These functions get [*comp] and set [set*comp] individual components of points, vectors or normals.

float readaov( uniform string name; type variable )

This function fetches a named AOV and writes it to variable, if it exists. If the variable exists, 1 is returned, otherwise 0 is returned.

The variable must be a pre-declared display channel but is not required to be in the parameter list of the shader.

float writeaov( uniform string name; type variable )

This function writes the contents of variable to a named AOV. If the arbitrary output variable exists, 1 is returned, otherwise 0 is returned and no write is performed.

The variable must be a pre-declared display channel but is not required to be in the parameter list of the shader.

float readprimvar( uniform string name; type variable )

This function reads a named primitive variable and writes it to variable if it exists. There are three different return codes from readprimvar:

1 means that the value came from the primitive variable.

2 means it came from the shader parameterlist.

3 means it came from an instance's primitive variable.

Otherwise, 0 is returned and no write is performed.

The variable need not be a parameter of the current shader. The detail of the variable must be varying (unless the variable is a string) so that the renderer is free to combine grids. Doing so ensures the best performance and is analogous to making a shader parameter varying to ensure good grid combining. Reading into a string variable will defeat the grid combining optimizations.

float evalparam( uniform string name; type variable )

This function evaluates parameters of the shader. If a parameter is declared to be a reference to an RIS shading plugin node, the node and its associated pattern graph are evaluated and the resulting data are written to variable. Otherwise the literal value bound to the parameter is written to variable. The variable must be a parameter of the current shader.

The return codes follow those of the RixSCConnectionInfo return value from RixParameterList:::GetParamInfo

1 means the variable was found in the shader parameterlist,

but not connected to a pattern network.

2 means the variable was in the parameterlist and connected

to a pattern network.

Otherwise, -1 is returned and no write is performed.

This function is especially useful in RSL shaders used to perform displacement in an RIS render.

float comp( color c; float index )
      setcomp( color c; float index, value )

These functions get and set individual color components, respectively. The index values are 0-based (e.g., the green channel of an RGB triple is component 1).

See also Matrix Functions, below.

color ctransform( string tospace; color C; )
color ctransform( string fromspace, tospace; color C; )

Transform the color C from the color representation fromspace to the color representation tospace.  If fromspace is absent, it is assumed to be "rgb". Valid spaces include (but may not be limited to): "rgb", "hsv", "hsl", "xyz", "XYZ", and "YIQ".

float comp( matrix m; float row, column )
      setcomp(  matrix m; float row, column, value )

These functions get and set individual components of a matrix, respectively. Strict runtime bounds checking will be performed on row and column to ensure that they fall into the range 0...3.

float determinant( matrix m )

Returns the determinant of matrix m.

matrix translate( matrix m; vector t )
matrix rotate( matrix m; float angle; vector axis )
matrix scale( matrix m; point s )

Postconcatenate simple transformations onto the matrix m. These functions are similar to the RI functions RiTranslate, RiRotate, and RiScale, except that the rotation angle in rotate() is in radians, not in degrees as with RiRotate.

float arraylength( type array[] )
float capacity( type array[] )

Returns the length or capacity of an array. The capacity of a fixed-length array is always equal to its length, but the capacity of a resizable array might be greater than its length. See the documentation on Resizable Arrays for more information.

type pop( output type array[] )

Returns the last element of the array and decreases its length by one. The capacity is not decreased.

void push( output type array[], type value )

Increases the length of the array by one and stores the given value as the last entry.

void reserve( output type array[], uniform float length )

Increases the capacity of the array if necessary, but does not change its length. The capacity is never reduced, unless it is set to zero. Reserving storage is preferable to incrementally resizing an array, since increasing capacity generally requires copying the array contents. This is especially useful when repeatedly pushing items on an array:

reserve(A, arraylength(A)+3);
    // reallocate A before pushing.
push(A, 1);
push(A, 2);
push(A, 3);

void resize( output type array[], uniform float length )

Changes the length of a resizable array. Note that the length is always uniform. If the length is increased, the new elements are uninitialized. An error is reported if the array has a fixed length.

string concat( string a, b, ... )

Concatenates two or more strings into a single string.

string format( string pattern, ... )

Does a formatted string creation under the control of pattern.  This function is similar to the C function sprintf().  As with the Shading Language printf function, use "%f", "%p", "%c", "%m", and "%s" to indicate float, point, color, matrix, and string, respectively.

float match( string pattern, subject )

Does a string pattern match on subject.  Returns 1.0 if the pattern exists anywhere within subject, and 0.0 if the pattern does not exist within subject. pattern can be any regular expression, as described in the POSIX manual page on regex() (3X), with the following exception: the $n notation does not work, as there are no return values from this function.  Note that the pattern does not need to start in the first character of subect, unless the pattern begins with the ^ (beginning of string) character.

void printf( string pattern, ... )

Print the values of the specified variables on the standard output stream of the renderer. pattern uses "%f", "%p", "%c", "%m", and "%s" to indicate float, point, color, matrix, and string, respectively. A vector or normal may also be printed using "%p".

ambience() stmt

Lights are classified at compile-time whether they will contain ambient contributions or not, thus permitting the renderer to refrain from executing certain lights when only the ambient contribution is being computed. The criteria is simple. If the light contains "solar" or "illuminate" blocks, it is considered non-ambient and will not be forced to execute by the ambient() surface shader shadeop. If the light contains neither op, it is considered ambient and is not run by diffuse(), specular(), or illuminance().

This behavior can be overridden by using an ambience() block. Any light shader that contains an ambience() block specifies a "run-it-and-check" behavior. ambience() is a simple block structure like solar(), but has no parameters. It automatically sets L to 0, so it is not necessary (nor is it advisable) to tweak L inside the block. For example:

if (goofytest != 0) {
    illuminate(from, axis, coneangle) {
       Cl = lightcolor * atten;
    }
} else {
    ambience() {
       Cl = 0.5;
    }
}

However, it continues to be useful to set L = 0 in the case where you wish to dynamically "turn off" a non-ambient light.

color ambient()

ambient returns the total amount of ambient light incident upon the surface. An ambient light source is one in which there is no directional component, that is, a light that does not have an illuminate or a solar statement.

color caustic( point P; normal N )

caustic returns the total amount of caustic light incident upon the surface. Caustics come about through indirect specular-to-diffuse ray paths.  If a particular implementation doesn't support caustics, caustic will always return 0 (black).

color diffuse( normal N )

diffuse returns the diffuse component of the lighting model.  N is a unit-length surface normal.

Example:

{
  color C = 0;
  illuminance( P, N, PI/2 )
     C += Cl * normalize(L).N;
  return C;
}

Note that the diffuse() shadeop responds to a special parameter of the light shader. Any light shader that contains

float __nondiffuse = 1

will be ignored by diffuse (note that there are two underbars). If the value of the parameter is 0.0, it is not ignored, so this behavior can be controlled both from the RIB file, or procedurally from inside the light shader, if desired. This parameter may be either uniform or varying, and can also be accessed within illuminance statements.

emit( color, [parameterlist] )

The arguments to describe the emissivity of the surface to the renderer. It accepts a uniform or varying color - a uniform color describes a constant luminaire, a varying color a textured luminaire (constant values are detected automatically).

By default, the emission is a single-sided cosine lobe about N. Tighter lobes may be constructed with cosine power other than 1, which adjusts the distribution to be more concentrated about the emission direction. The emission profile is stored away and used by the system to build its lighting database.

emit() runs in a context much like that of a surface shader. That is, P represents points on the emitting surface (not a surface being illuminated). The shadeop must be present in the prelighting() method of an area light source shader. The geometry to which it is attached must not be inside a procedural.

The following optional parameters are supported:

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

The gather looping construct collects information via ray tracing. It typically controls integration of a procedural reflectance model over incoming light whose source is other surfaces; that is, it collects indirect light. Direct light from light sources is collected with illuminance loops.

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, similar to while, for, or illuminance loops. In each pass, results from the current ray cast are available to the statement code, which typically accumulates values from all sample passes; a weighted average is then often computed outside the gather loop. 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:

float samples = 16;      /* often from a shader parameter */
float blur = radians(5); /* often from a shader parameter */
Ci = 0;
if (N.I < 0) { /* only trace from points facing the eye */
   vector R = reflect(normalize(I),normalize(N));
   color hitcolor = 0;
   gather("illuminance", P, R, blur, samples, "volume:Ci", hitcolor) {
      Ci += hitcolor;
   } else {
      Ci += environment("skymap.env", R);
   }
   Ci = Ci / samples;
}
Ci *= Os;
Oi = Os;

Arbitrary data associated with ray hits can be collected, see msg_spec below. Since many gathered values will be unrelated to indirect illumination, the required category string(first argument to gather) allows the renderer to distinguish certain important types of gathering. There are, currently, two special categories: illuminance and samplepattern. "illuminance" is recognized as distinguishing illuminance-gathering blocks from other information-gathering uses. In particular, during photon map creation, shader analysis will select only those gather calls categorized as "illuminance" to participate in photon scattering. "samplepattern" causes gather to generate correctly stratified and distributed rays within the sample cone described by the subsequent arguments, but gather itself will not actually shoot any rays. Instead, the gather() "else" block is executed once per sample, after filling in any requests for "ray:direction", which can be useful for shaders that want to do other types of direction-based lookups but don't want to generate their own sample distributions.

Unlike illuminance blocks, in which L and Cl are preset to each light's direction and color, there are no additional predefined variables provided by gather to its code blocks. Instead, shader writers supply their own local variables to gather, which are filled in with values from the hit surface as specified with an output msg_spec. These local variables can then be referenced within the gather code block. This general interface without reserved names prevents conflicts when gather loops are nested or called within lightsource shaders (where illuminance is illegal).

Note that there can be two code blocks associated with a gather call; the first block is executed when a ray hits something, and the optional else block executes when a ray misses everything. Output msg_spec variables have undefined values in the "miss" case, and therefore should not be referenced in the else block. Output variables from the "ray:" namespace are an exception; they are valid in both hit and miss cases. Even when a ray-hit occurs it is possible that the value requested for a particular msg_spec is not available from the hit surface; this is especially true for user-defined "message passing" shader output variables, which might not be supplied by every hit surface shader. In this case the local output variable will not be updated by gather, so it is up to the shader writer to re-initialize loop variables whose spec doesn't guarantee success.

Automatic continuation of rays occurs when the hit surface is not opaque, as determined by the output Oi from the shader(s) on the surface. Rays will continue in their original direction, collecting values from hit surfaces, until the opacity threshold is reached (see othreshold in the table below).

Optional parameters to gather take the form of token-value pairs. It supports all of the common ray tracing function parameters, as well as the following:

float hitproperty = 0;
gather(..., "attribute:user:myproperty",
       hitproperty, ...)
{
       //... use hitproperty ...
}

In situations where values are fetched using only primitive:var, attribute:var, or ray:var descriptors, some implementations may opt to skip execution of the shaders on the hit surface entirely, as an optimization. In these cases, automatic ray continuation may not occur, since shader execution is required to determine the surface opacity, Oi.

illuminance([string category], point position )
     statement
illuminance([string category], point position, vector axis, float angle )
     statement

The illuminance statement controls integration of a procedural reflectance model over the incoming light. Inside the illuminance block two additional variables are defined: Cl or light color, and L or light direction. The vector L points towards the light source, but may not be normalized (see the Light source shader state illustration, in the Shader Execution Environment document). The arguments to the illuminance statement specify a three-dimensional solid cone and, optionally, the effective number of samples or step size of the integral.

The first form (above) specifies that the integral extends over the entire sphere centered at position. The second form integrates over a cone whose apex is on the surface at position. This cone is specified by giving its centerline, and the angle between the side and the axis in radians. If angle is PI, the cone extends to cover the entire sphere and these forms are the same as the first form. If angle is PI/2, the cone subtends a hemisphere with the north pole in the direction axis. Finally, if angle is 0, the cone reduces to an infinitesimally thin ray.

The optional category string parameter selects which lights should execute during a particular illuminance loop. The illuminance category string is a simple pattern expression which is matched against each light's declared list of category "memberships". Light shaders can specify categories to which they belong by declaring a string parameter named __category (this name has two underscores), whose value is a comma-separated list of names. These categories are simply arbitrary names, chosen by the programmer to be useful among a set of cooperating shaders. The illuminance category parameter expressions are very limited. They consist of category "terms" separated by "&" or "|" (for AND and OR). The "terms" can be:

"name" - matches lights which include "name" in their category list

"-name" -matches lights which do not have "name" in their category list (including lights which have no category list)

"*" - matches every light with non-null category

"-*" - matches every light with no categories

"" - matches everything

"-" - matches nothing

omitted- if the category parameter is omitted, the illuminance loop will execute its body for every nonambient light source.

A Lambertian shading model is expressed simply using the illuminance statement:

Nn = normalize(N);
illuminance( P, Nn, PI/2 )
{
   Ln = normalize(L);
   Ci += Cs * Cl * Ln.Nn;
}

This example integrates over a hemisphere centered at the point on the surface with its north pole in the direction of the normal. Since the integral extends only over the upper hemisphere, it is not necessary to use the customary max``(0,Ln.Nn)`` to exclude lights that are locally occluded by the surface element.

illuminate( point position ) stmt
illuminate( point position, vector axis, float angle ) stmt

solar( ) stmt
solar( vector axis, float angle ) stmt

The illuminate and solar statements are inverses of the illuminance statement. They control the casting of light in different directions. The vector variable L corresponding to a particular light direction is available inside this block. This vector points outward from the light source. The color variable Cl corresponds to the color in this direction and should be set. Like the illuminance statements, illuminate and solar statements cannot be nested.

The illuminate statement is used to specify light cast by local light sources. The arguments to the illuminate statement specify a three-dimensional solid cone. The first form (above) specifies that light is cast in all directions. The second form specifies that light is cast only inside the given cone. The length of L inside an illuminate statement is equal to the distance between the light source and the surface currently being shaded.

The solar statement is used to specify light cast by distant light sources. The arguments to the solar statement specify a three-dimensional cone. Light is cast from distant directions inside this cone. Since this cone specifies only directions, its apex need not be given. The first form (above) specifies that light is being cast from all points at infinity (e.g., an illumination map). The second form specifies that light is being cast from only directions inside a cone.

An example of the solar statement is the specification of a distant light source:

solar( D, 0 )
   Cl = intensity * lightcolor;

This defines a light source at infinity that sends light in the direction D. Since the angle of the cone is 0, all rays from this light are parallel.

An example of the illuminate statement is the specification of a standard point light source:

illuminate( P )
   Cl = (intensity * lightcolor) / (L.L)

This defines a light source at position P that casts light in all directions. The 1/L.L term indicates an inverse square law fall off.

color indirectdiffuse( point P; normal N; float samples;  [parameterlist]  )

indirectdiffuse returns diffuse illumination arising from indirect illumination. Effects such as "color bleeding", which arise through 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 calls but is much more efficient due to interpolation of results. Required parameters:

P, N, samples controls sampling of the underlying indirect illumination function. The sampling region is defined to be the hemisphere centered about the surface normal N at point P. (samples is ignored for point-based calculations.) Optional parameters are specified as name/value pairs.

indirectdiffuse() supports all of the common ray tracing function parameters, as well as the following:

float seed = abs(123 * Pref[0] +
                 456 * Pref[1] +
                 789 * Pref[2]);

Implementations that don't support indirectdiffuse should return black.

_lightingstart()

lightingstart is a special no-op shadeop that serves as an optimization hint for the re-rendering mode of PRMan; it marks the end of light-independent calculations (texturing and noise for example), and the beginning of light-dependent calculations (such as calls to diffuse(), illuminance(), et cetera); this allows the re-renderer to cache all shading results that occur before lighting.

The shader compiler attempts to place _lightingstart() in a reasonable part of the shaders. For complicated shaders, the result may not always be optimal and can be overridden by explicitly adding the statements to the shader sourcecode. For example:

surface
matte( float Ka=1, Kd=1 )
{
    normal Nf;

    Nf = faceforward(normalize(N),I);

    Oi = Os;
    _lightingstart();
    Ci = Os * Cs * ( Ka*ambient() + Kd*diffuse(Nf) ) ;
}

float occlusion( point P; normal N; float samples;  [parameterlist]  )

occlusion returns a measure of ambient occlusion defined as the percentage of the hemisphere that is occluded from view by the "environment".

P, N, samples controls sampling of the underlying ambient occlusion function. The sampling region is defined to be the hemisphere centered about the surface normal N at point P. (samples is ignored for point-based calculations.) Optional parameters are specified as name/value pairs.

occlusion() supports the common ray tracing function parameters (except as noted), as well as the following:

float seed = abs(123 * Pref[0] +
                 456 * Pref[1] +
                 789 * Pref[2]);

Implementations that don't support occlusion should return 0 (unoccluded).

color phong( normal N; vector V; float size )

phong implements the Phong specular lighting model.

Example:

{
  color C = 0;
  vector R = reflect( -normalize(V), normalize(N) );
  illuminance( P, N, PI/2 ) {
     vector Ln = normalize(L);
     C += Cl * pow(max(0.0,R.Ln), size);
  }
  return C;
}

The phong shadeop responds to the following special parameter of a light shader:

float __nonspecular = 1

Any light that contains this parameter will be ignored by both phong and specular. Please note that if the value of the parameter is 0.0, it is not ignored, so this behavior can be controlled both from the RIB file, or procedurally from inside the light shader, if desired. This parameter may be either uniform or varying, and can also be accessed within illuminance statements.

color specular( normal N; vector V; float roughness )

specular returns the specular component of the lighting model using an implementation-dependent specularbrdf. N is the unit-length normal to the surface. V is a unit-length vector from a point on the surface towards the viewer. For example:

{
  color C = 0;
      illuminance( P, N, PI/2 )
         C += Cl * specularbrdf(normalize(L), N, V, roughness);
      return C;
}

The specular shadeop responds to the following special parameter of a light shader:

float __nonspecular = 1

Any light that contains this parameter will be ignored by both specular and phong. Please note that if the value of the parameter is 0.0, it is not ignored, so this behavior can be controlled both from the RIB file, or procedurally from inside the light shader, if desired. This parameter may be either uniform or varying, and can also be accessed within illuminance statements.

float specularbrdf( vector L; normal N; vector V; float roughness )
color specularbrdf( vector L; normal N; vector V; float roughness )

Returns the specular attenuation of light coming from the direction L, reflecting toward direction V, with surface normal N and roughness, roughness.  All of L, V and N are assumed to be of unit length.  This is the same reflection model calculation found inside the illuminance loop of the specular() function.  This allows users to write an illuminance loop that reproduces the functionality of the specular() function, even if the renderer has an implementation-specific formula for built-in specular reflection.  Here is a sample implementation:

color specularbrdf(vector L, N, V; float roughness)
{
   vector H = normalize(L+V);
   return pow(max(0, N.H), 1/roughness);
}

color subsurface( [mode]; point P; normal N;  [parameterlist]  )

subsurface returns the subsurface scattering at point P, with surface normal N. (N is only used for point-based subsurface diffusion if the paramter "followtopology" is on.) Mode can be "pointbased" or "raytraced", with "pointbased" being the default. Other optional parameters are specified as name/value pairs.

subsurface() supports most of the common ray tracing function parameters (except as noted), plus the following:

Implementations that don't support subsurface should return black.

Additional information about usage can be found in the application notes:

• Translucency and Subsurface Scattering
• Improved Subsurface Scattering

color trace( point P; vector R )
float trace( point P; vector R )

trace returns the incident light reaching a point P from a given direction R. If a particular implementation does not support the ray tracing capability, and cannot compute the incident light arriving from an arbitrary direction, trace will return 0 (black). When the float variant of trace is called, the distance to the nearest ray hit is returned. This variant can be faster because surface shaders may not be required to determine intersection locations.  When no geometry is encountered along the ray direction, a very large distance value is returned.

color transmission( point Psrc, Pdst;  [parameterlist]  )

transmission returns a color representing the ability of light to flow between Psrc and Pdst. If a particular implementation does not support the ray tracing capability, and cannot compute the incident light arriving from an arbitrary direction, transmission will always return 1 (white). Transmission rays are different than trace rays because their purpose isn't to find the nearest hit but rather to find how much light can 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.

transmission() supports the common ray tracing function parameters (except as noted), as well as the following:

color directlighting( shader material, shader lights[],
                        ["integrationdomain", "hemisphere|sphere"],
                        ["diffuseresult", output color diffuseresult],
                        ["specularresult", output color specularresult],
                        ["irradianceresult", output color irradianceresult],
                        ["materialsamples", output __radiancesample samples[]],
                        [uniform float "arealightsamples"]
                      )

directlighting combines the diffuse and specular integrators in a single function. directlighting, like diffuse and specular, is concerned only with light that can directly impinge upon the surface, but provides advantages because certain computations can be shared.

color indirectspecular( [ shader material, "materialsamples", output
                          __radiancesample samples[]
                          | "materialsamples:direction", direction[],
                          "materialsamples:materialResponse", materialResponse[],
                          "materialsamples:materialPdf", materialPdf[],
                          "materialsamples:distance", distance[],
                          "materialsamples:radiance", radiance[]], ...
                        )

The indirectspecular function provides a means by which the specular response associated with indirect light transport paths can match the response to direct lighting. The sampling directions are either provided indirectly through a call to the generateSamples method of material, or directly in either the materialsamples __radiancesample array or individual component arrays.

It supports the same syntax as gather() for sending data to shaders at suface hits, via [send:|samplesend:]surface:varname. For samplesend:, the variable must be a varying array with the the same number of entries as the number of samples, and the data will be sent per sample.

indirectspecular() supports all of the common ray tracing function parameters, as well as the following:

public void diffuselighting(output color Ci, Oi);
public void specularlighting(output color Ci, Oi);

The material pipeline methods express the separation of view-independent and view-dependent lighting. View-independent lighting and opacity are cached in the radiosity cache in order to deliver speedups. The diffuselighting method also takes an optional Irradiance parameter, which is required for ray-traced subsurface scattering.

void randomstrat( uniform float sampleoffset, uniform float nsamples,
                    output float[] samples );
void randomstrat( uniform float sampleoffset, uniform float nsamples,
                    output triple[] samples );
void randomstrat( uniform float sampleoffset, uniform float nsamples,
                    output __radiancesample[] samples );

When invoked, randomstrat() will fill in a slice, from sampleoffset up to, but not including, sampleoffset + nsamples, of the samples array with stratified random numbers. If the array is variable length, it will automatically be resized to an appropriate capacity. With an array of floats, it generates 1D samples in [0, 1). For an array of triples, it generates 2D samples in [0, 1) x [0, 1) and zeros the third component. For an array of radiancesamples, the 2D samples will be placed in the direction field. If generating more than one sample, we stratify over the set of samples produced for each grid point. If generating only one sample, we stratify across REYES grids.

The choice and order of the parameters are intended to mirror the stdrsl_AreaSampler methods and generateSamplesAS/Env.

uniform float generateSamplesAS ( varying color weight;
                                    uniform float nSamples;
                                    varying  float exp1, exp2;
                                    varying vector Nn;
                                    varying vector Tn;
                                    varying vector Vn;  // Vn.Nn > 0
                                    output __radiancesample[] samples );

uniform float evaluateSamplesAS ( varying color weight;
                                    varying  float exp1, exp2;
                                    varying vector Nn;
                                    varying vector Tn;
                                    varying vector Vn;  // Vn.Nn > 0
                                    output __radiancesample[] samples );

These functions generate and evaluate (respectively) the specular lobe of the Ashikhmin/Shirley BRDF. generateSamplesAS may return fewer samples than asked for in order to provide better stratification of those samples.

uniform float generateSamplesEnv ( uniform string envMapName,
                                     varying point P,
                                     varying normal N,
                                     uniform float nSamples,
                                     output __radiancesample[] samples );

This function generates the contributions of environment light sources. generateSamplesEnv may return fewer samples than asked for in order to provide better stratification of those samples. Note that, currently, support is provided for latlong environment maps only.

uniform float evaluateSamplesEnv ( uniform string envMapName,
                                     varying point P,
                                     varying normal N,
                                     output __radiancesample[] samples );

This function evaluates the contributions of environment light sources. Note that, currently, support is provided for latlong environment maps only.

void accumulateMaterialResponse ( output __radiancesample samples[],
                                     [varying color layerOpacity]);

When evaluating samples, sequential calls to, e.g., evaluateSamplesAS should be followed by accumulateMaterialResponse. The optional layerOpacity parameter allows you to specify a layer compositing weight, which is used to influence the MIS computations. When no layering is required, the layerOpacity value needn't be provided; this is equivalent to setting the value to color(1).

void normalizeMaterialResponse ( output __radiancesample samples[],
                                    uniform float nsamplesPerComponent[],
                                    [varying color layerOpacities[])

Similarly, when generating samples each component should contribute samples to the result. Now, while there may be multiple calls to, e.g., generateSamplesAS, there must be a single call to normalizeMaterialResponse. We assume that each component may contribute a unique number of samples; this is represented in the nsamplesPerComponent array. The length of this array is equal to the number of components that contribute to the samples. Finally, as above, layerOpacities is an optional parameter which, if not provided, is equivalent to array of 1 and with a length equal to the length of nsamplesPerComponent.

shader getlight( string handlename )
shader getshader( string handlename )

Returns the light or co-shader with the specified handle, or null if not found. For example, a co-shader can be declared in RIB by specifying the shader name, a handle name, and any desired parameter values:

Shader "basic" "baselayer" "float Ks" [.5]
Shader "rust" "rustlayer" "float Ks" [0]

The surface method of the baselayer shader could then be called as follows:

shader baselayer = getshader("baselayer");
if (baselayer != null)
    baselayer->surface(Ci, Oi);

shader[] getlights( ... )
shader[] getshaders( ... )

Returns a variable-length array of the light shaders or the co-shaders that are active in the current attribute scope. If the parameter list is empty, all the active lights or co-shaders are returned. Otherwise the parameters must be name/value pairs that specify a subset of the results. Currently the only supported parameter is "category". For example, diffuse illumination can be implemented as follows:

shader lights[] = getlights("category", "diffuse");
uniform float i, n = arraylength(lights);
for (i = 0; i < n; i += 1) {
    vector L;
    color Cl;
    lights[i]->light(L, Cl);
    C += Cl * max(0,Nn . normalize(-L));
}

float getvar( shader shader; string name; [ output type variable ] )

Copies the value of the specified variable from the given shader into the output parameter, returning 1.0 if successful. Otherwise the output parameter is unchanged and getvar returns 0.0, which indicates that

• the given shader was null (e.g. an earlier call to getshader() failed); or
• the specified variable was not a parameter or public member variable of the given shader; or
• the type or detail of the specified variable did not match that of the output parameter.

For example:

shader baselayer = getshader("baselayer");
float baseKd = 0;
getvar(baselayer, "Kd", baseKd);

The output parameter can be omitted, in which case getvar simply checks whether the specified variable exists. For convenience, the "arrow operator" can also be used instead of getvar:

float baseKd = baselayer->Kd;

When this syntax is used, a warning is reported if the specified variable does not exist or does not have the expected type, in which case the arrow operator returns zero(s) (or the empty string, etc.)

float hasmethod( shader shader; string methodname )

Returns 1.0 if the given shader defines a method with the specified name; otherwise it returns 0.0. Method calls employ the usual arrow operator syntax; for example:

if ( hasmethod(surface, "GetBRDF") )
    surface->GetBRDF( ... );

shader surface;
shader light;

These global variables provide access to the current surface shader and the current light. The current light can be used only within an illuminance loop.

float atmosphere( string paramname; output type variable )
float displacement( string paramname; output type variable )
float lightsource( string paramname; output type variable )
float surface( string paramname; output type variable )
float incident( string paramname; output type variable )
float opposite( string paramname; output type variable )

These functions access the value of the parameter named paramname of one of the shaders attached to the geometric primitive that is currently being shaded. incident accesses values from the volume shader that describes the volume that contains the incident ray, I.  opposite accesses values from the volume shader that describes the volume on the other side of the surface.  If the appropriate shader exists, and a parameter name paramname exists in that shader, and the parameter is the same type as variable, then the value of that parameter is stored in variable and the function returns 1.0; otherwise, variable is unchanged and the function returns 0.0.

Note that if the data corresponding to paramname is uniform, but the variable variable is varying, the appropriate uniform-to-varying conversion will take place. However, the reverse case is considered failure.

The lightsource function is only available inside illuminance blocks and refers to the light being examined by the current iteration.

It should be noted that, as of PRMan 14, these functions have been deprecated in favor of techniques available in RSL 2.0.

float attribute( string name, output type variable )

Returns data that is part of the primitive's attribute state, either from individual RenderMan Interface calls that set attributes or from the RiAttribute call.  The name specifies the piece of RenderMan Interface attribute state that will be returned in variable.  If the data name is known to the renderer and its type and storage class match that of variable, the named data will be written into variable and attribute() will return a value of 1.0.  If the data is unknown or the types do not match, variable will be unchanged and attribute() will return 0.0.

Note that if the data corresponding to paramname is uniform, but the variable variable is varying, the appropriate uniform-to-varying conversion will take place. However, the reverse case is considered failure.

The standard data names supported by attribute are listed below.  A particular implementation may support additional attribute queries.

The pieces of attribute state that can be retrieved via the attribute() function are:

float option( string name; output type variable )

Returns data that is part of the renderer's global option state, either from individual RenderMan Interface calls that set options or from the RiOption call. The name parameter specifies the piece of RenderMan Interface option state that will be returned in variable.  If name is known to the renderer and its type and storage class match that of variable, the named data will be written into variable and option() will return a value of 1.0.  If the data is unknown or the types do not match, variable will be unchanged and option() will return 0.0. Note that option data is always uniform.  If variable is varying, the appropriate uniform-to-varying conversion will take place.

The standard data names supported by option are listed below.  A particular implementation may support additional option queries.

The pieces of option state that can be retrieved via the option() function are:

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

Provides access to state associated with the ray that caused the current shader to execute. rayinfo fills in result with the current value associated with the query keyword(s). 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
     */
}

float rendererinfo( string name; output type variable )

Returns data about the renderer itself.  The name parameter specifies the piece of information that will be returned in variable.  If name is known to the renderer and its type and storage class match that of variable, the named data will be written into variable and rendererinfo() will return a value of 1.0.  If the data is unknown or the types do not match, variable will be unchanged and rendererinfo() will return 0.0.  Note that renderer data is always uniform. If variable is varying, the appropriate uniform-to-varying conversion will take place.

uniform float shaderinfo( uniform string keyword, result )

Provides access to state associated with the currently executing shader. shaderinfo 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 string s;
success = shaderinfo("pipelinestage", s);
if (s == "lighting") {
    /* specialize for lighting */
} else {
    /* don't */
}

string shadername()
string shadername( string shadertype )

If no parameter is passed, returns the name of the shader that is currently running.  If the shadertype is supplied, this function returns the name of the shader of the specified type that is bound to the geometric primitive that is being shaded.  Acceptable values of shadertype are "surface", "displacement", "atmosphere", "lightsource", "interior", "exterior".  If the surface being shaded does not have a shader bound to it that matches the type, this function will return the empty string ("").

void rbug( point | vector | normal dbgP )
void rbug( point | vector | normal dbgP, color dbgC )
void rbug( point | vector | normal dbgP, color dbgC, normal dbgN )

void rbug( point dbgP0, point dbgP1 )
void rbug( point dbgP0, point dbgP1, color dbgC )
void rbug( point dbgP0, point dbgP1, color dbgC, normal dbgN )

Spawns a debug window that will graphically plot the point dbgP or the line segment from dbgP0 to dbgP1. If a color dbgC is provided, that color will be used instead of white. If a dbgN is provided that will be plotted at the point dbgP as well.