## Built-In Functions

The shading language provides the following built-in functions:

### Mathematical Functions

The following library of math functions is provided. This library includes most of the routines normally found in the standard C math library as well as functions for interpolation and computing derivatives.

The following mathematical functions are provided:

```float PI = 3.14159... ;
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.

```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(x) 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 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.

```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(a,min,max) 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 bases (e.g., 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 (e.g., 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 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 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 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" (aka "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 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", 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 4n+3 and 4n+2, respectively.  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.

```float Du( float p ), Dv( float p ), Deriv( float num; float den )
color Du( color p ), Dv( color p ), Deriv( color num; color den )
vector Du( point p ), Dv( point p ), Deriv( point num; point den )
vector Du( vector p ), Dv( vector p ), Deriv( vector num; vector 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 random()
color random()
point random()```

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

```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 1-D (one float), 2-D (two floats), or 3-D (one point), or 4-D (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 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.

Optional wnoise parameters are specified as name/value pairs:

`"projectvector" vec (vector)`
By default, the noise is projected along the surface normal, which greatly improves filtering characteristics. You can override the vector used for projection with this parameter. This vector need not be normalized, but it must be in a stable space such as "object" or "shader." Passing a vector with value (0,0,0) disables projection.
`"frequencyrange" range (uniform string)`
Controls whether noise spectrum is "finite" and based on the point (the default), or "infinite" and always consists of visible frequencies.
`"octaves" num (uniform float)`
Controls the number of octaves of noise to calculate. By default, this value is 1.
`"lacunarity" lacunarity (uniform float)`
Specifies a multiplier for each successive frequency of noise. By default this is 2.
`"weights" weightArray (uniform float[])`
An array of floats representing weights for each frequency. Their effect will automatically be normalized. Ideally the length of the array matches the number of octaves. If the array is longer, only the relevant entries will be used. If the array is shorter or absent, the missing values will be set to 1.
`"distribution" dist (uniform string)`
Controls the manner in which values are distributed around the center. By default, this is a "flat" distribution. With a value of "gaussian", the values will have a gaussian distribution.
`"amplitude" amp (uniform float)`
Controls the amplitude of distribution about the center value. With a "flat" distribution, output values range from -amplitude to +amplitude. With a "gaussian" distribution, amplitude represents the standard deviation. In this case, a small percentage of values will exceed the bounds set by amplitude. This value defaults to 1.

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);
```
```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, etc.)  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 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 1-D (one float), 2-D (two floats), 3-D (one point), or 4-D (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

### Geometric Functions

Geometric functions provide a kernel of useful geometric operations. Most of these functions are most easily described by just giving their implementation.

```float xcomp( ptype P )
float ycomp( ptype P )
float 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 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 distance( point P1, P2 )
{
return length(P1-P2);
}```

Return the distance between two points.

`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).

`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.

```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).

```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.

```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.

`void fresnel( vector I, N; float eta, 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).

```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 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).

```normal calculatenormal( point P )
{
return Du(P) ^ Dv(P);
}```

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

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

### Color Functions

Several functions exist that operate on colors.

```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).

```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".

### Matrix and Array Functions

`float arraylength( v )`

This function returns the length of an array, which is primarily useful when the array is of indeterminate length. A value of -1 is returned if the variable v is actually a scalar.

```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.

### String Functions

`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, `"%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 subjectpattern 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"`.

In this section, built-in shading and lighting functions are defined.

For more information the gather, illuminance, and illuminate statements, see the Language Constructs documentation.

`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 )
{
color C = 0;
illuminance( P, N, PI/2 )
C += Cl * normalize(L).N;
return C;
}```

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

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

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.

Optional parameters are specified as name/value pairs:

• `"adaptive" adaptive` - indicates whether the hemisphere can be adaptively sampled. The default value is 1 (on).
• `"minsamples" minsamples` - specifies the (float) minimum number of samples for adaptive sampling of the hemisphere. The default value is `samples`/4 if samples is at least 64; otherwise it is `samples` (corresponding to non-adaptive sampling).
• `"coordsystem" coordsystem` - is the name of the coordinate system the object is in.
• `"distribution"` `dist` (uniform string) - specifies the distribution of samples across the sample region. Available distributions are "uniform" and "cosine".  Use "cosine" when the results are intended to simulate diffuse reflection at a surface.  Use "uniform" to ensure that all portions of the sample region are treated equally, as needed for example for a point in a volume. The default distribution is "cosine".
• `"maxdist" dist` - specifies the (float) maximum distance to consider when performing intersection calculations. The default value is 1e30.
• `"falloffmode" falloffmode` - chooses between two types of distance falloff. The default value is 0, corresponding to exponential falloff.
• `"falloff" falloff` - specifies whether indirect diffuse color (and occlusion) should fall off with distance. For falloffmode = 0: the irradiance contribution of a ray hit is multiplied by exp(-falloff*dist). For falloffmode = 1: the irradiance contribution of a ray hit is multiplied by (1 - dist/maxdist)^falloff. When falloff is 0 (the default value), the irradiance does not fall off in either mode.
• `"coneangle" coneangle` - specifies the (float) part of the hemisphere to be considered when performing intersection calculations. The default value is PI/2, corresponding to the entire hemisphere. If the coneangle is larger than the specularthreshold option (which has a default value of 10 degrees), the rays will be of type 'diffuse'; otherwise they will be of type 'specular'.
• `"samplebase" samplebase` - specifies the (float) jittering of the hemisphere ray origins. The default value is 0 (no jittering). A value of 1 corresponds to jittering over the size of a micropolygon. This can be useful to smooth out aliased indirect illumination next to edges.
• `"hitmode" hitmode` (uniform string) - specifies how the color and opacity should be computed at ray hit points. If the value is "default", the color and opacity are determined as specified by the hit object's "shade" "diffusehitmode" attribute. If the value is "primitive", the color and opacity are copied from the object's Color and Opacity attributes. If the value is "shader", the shader is evaluated to get the color and opacity. In "primitive" or "shader" mode, if the opacity is less than othreshold, a continuation ray will be fired. In "default" mode, if no attribute "shade" "diffusehitmode" is defined, the opacity will be considered 1.
• `"hitsides" hitsides` (uniform string) - specifies which side(s) of one-sided surfaces can be hit by the rays. The possible values are "front", "back", and "both". The default is "both".
• `"subset" name` - specifies the (string) name of a trace subset.  Only primitives which are members of this subset will be considered when performing intersection calculations (membership is set with Attribute "grouping" "membership"). If no subset parameter is specified, then objects with membership in the default group will be traced.
• `"environmentmap" map (uniform string)` - specifies the name of an environment map to consult when ray probes don't hit local geometry.
• `"label` - specifies the label associated with all rays spawned by this call.
• `"environmentspace"` ```name (uniform string)``` - specifies the name of a coordinate system to apply when accessing the environment map.
• `"bias" bias` (float) - specifies a float value to offset hemisphere sample origins.  If not provided the trace bias attribute is used.
• "`maxerror" error `(float) - specifies an error metric to control quality/speed tradeoff for irradiance calculations.  If set to zero, the irradiance will be computed at every shading point; no attempt at interpolation will be made. The larger "maxerror" is, the more time can be saved by interpolating nearby irradiance values. If not provided or if set to a negative value, the value of the attribute: "irradiance" "maxerror" is used. NOTE: "maxerror" is superseded by the new "maxvariation" parameter and will probably be phased out in a future release.
• `"maxpixeldist"` `dist` (float) - specifies an error metric to control quality/speed tradeoff for irradiance calculations.  If set to zero, the irradiance will be computed at every shading point; no attempt at interpolation will be made.  maxpixeldist is used in conjunction with maxerror or maxvariation and provides a screen-based metric to limit artifacts associated with interpolation. If not provided or if set to a negative value, the value of the attribute: "irradiance" "maxpixeldist" is used.
• "`maxvariation" var `(float) - specifies an error metric to control quality/speed tradeoff for irradiance calculations.  If set to zero, the irradiance will be computed at every shading point; no attempt at interpolation will be made.  The larger "maxvariation" is, the more time can be saved by interpolating nearby irradiance values.  "maxvariation" specifies how much the interpolated irradiance values are allowed to deviate from the true irradiance. For high-quality final rendering, values in the 0.01 to 0.02 range are typical; for quick preview renderings values of 0.05 or even 0.1 can be used. If "maxvariation" is not provided or is set to a negative value, "maxerror" will be used instead. NOTE: "maxvariation" is a better error metric than "maxerror" and should be used instead of it; the same quality can be obtained with fewer irradiance calculations (and therefore faster) and the control is more intuitive.
• `"seed"` `seed` `(uniform float)` - frame-dependent random directions seed. If "seed" is set to a fixed non-negative number, the ray directions from each point will be fixed from frame to frame. If "seed" is set to -1 (the default) or the frame number, the directions will change from frame to frame.
• `"pointbased"` `pointbased` `(uniform float)` - use point-based irradiance and occlusion calculation instead of ray tracing.
• `"filename"` `name` (uniform string) - the name of the point cloud file to use for point-based irradiance and occlusion.
• `"clamp"` `clamp` (uniform float) - the point-based method tends to compute too much color bleeding (due to superposition); if this parameter is 1 the over-bleeding is reduced.
• `"sortbleeding"` `sortbleeding` (uniform float) - for point-based irradiance, should the color bleeding colors be resolved front-to-back or just mixed?
• `"useopacity" useopacity` (float) - deprecated by the newer hitmode parameter and will be phased out.
• `"handle"` `name` (uniform string) - specifies the name of an irradiance cache context.  If not provided, the value of the attribute "irradiance" "handle" is used. This parameter (and the attribute) will be phased out in a future release. We strongly recommend using the bake3d() and texture3d() functions instead.
• `"filemode"` `mode` (uniform string) - specifies the irradiance cache file i/o mode associated with the irradiance cache, given by handle.  Available modes are "" (no I/O), "r" (rely exclusively on the data found in the file named by the value of handle, and "w" - store irradiance cache contents in the file named by the handle parameter). If not provided the value of the attribute: "irradiance" "filemode" is used. This parameter (and the attribute) will be phased out in a future release. We strongly recommend using the bake3d() and texture3d() functions instead.
• ```"environmentcolor" c (output color)``` - specifies the optional output variable to fill with the color resulting from environment map lookups at ray misses.  If no environment map is provided, the environment color will be black. (To get the color resulting from ray hits, just subtract the environment color from the indirectdiffuse() return value.)
• `"environmentdir"` `dir` ```(output varying vector)``` - specifies an 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.

Implementations that don't support indirectdiffuse should return 0 (black).

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

`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.

Optional parameters are specified as name/value pairs:

• `"adaptive" adaptive` - indicates whether the hemisphere can be adaptively sampled. The default value is 1 (on).
• `"minsamples" minsamples` - specifies the (float) minimum number of samples for adaptive sampling of the hemisphere. The default value is `samples`/4 if samples is at least 64; otherwise it is `samples` (corresponding to non-adaptive sampling).
• `"coordsystem" coordsystem` - is the name of the coordinate system the object is in.
• `"distribution"` `dist` (uniform string) - specifies the distribution of samples across the sample region. Available distributions are "uniform" and "cosine".  Use "cosine" when the occlusion results are intended to simulate diffuse reflection at a surface.  Use "uniform" to ensure that all portions of the sample region are treated equally, as needed for example at a point in a volume. The default distribution is "cosine".
• `"maxdist" dist` ` (float)` - specifies the (float) maximum distance to consider when performing intersection calculations.
• `"falloffmode" falloffmode` - chooses between two types of distance falloff. The default value is 0, corresponding to exponential falloff.
• `"falloff" falloff` - specifies whether occlusion should fall off with distance. For falloffmode = 0: the occlusion of a ray hit is computed as exp(-falloff*dist). For falloffmode = 1: the occlusion of a ray hit is computed as (1 - dist/maxdist)^falloff. When falloff is 0 (the default value), the occlusion does not fall off in either mode.
• `"coneangle" coneangle` - specifies the (float) part of the hemisphere to be considered when performing intersection calculations. The default value is PI/2, corresponding to the entire hemisphere. If the coneangle is larger than the specularthreshold option (which has a default value of 10 degrees), the rays will be of type 'diffuse'; otherwise they will be of type 'specular'.
• `"samplebase" samplebase` - specifies the (float) jittering of the hemisphere ray origins. The default value is 0 (no jittering). A value of 1 corresponds to jittering over the size of a micropolygon. This is useful to smooth out aliased occlusion next to edges.
• `"hitmode" hitmode` (uniform string) - specifies how the opacity should be computed at ray hit points. If the value is "default", the opacity is determined as specified by the hit object's "shade" "diffusehitmode" attribute. If the value is "primitive", the opacity is copied from the object's Opacity attributes. If the value is "shader", the shader is evaluated to get the opacity. In "primitive" or "shader" mode, if the opacity is less than othreshold, a continuation ray will be fired. In "default" mode, if no attribute "shade" "diffusehitmode" is defined, the opacity will be considered 1.
• `"hitsides" hitsides` (uniform string) - specifies which side(s) of one-sided surfaces can be hit by the rays. The possible values are "front", "back", and "both". The default is "both".
• `"subset" name` ` (uniform string)` - specifies the name of a trace subset.  Only primitives which are members of this subset will be considered when performing intersection calculations (membership is set with Attribute "grouping" "membership"). If no subset parameter is specified, then objects with membership in the default group will be traced.
• `"label"` - specifies the label associated with all rays spawned by this call.
• `"environmentmap" map (uniform string)` - specifies the name of an environment map to consult when ray probes don't hit local geometry. The environment map (if present) will guide the distribution of occlusion rays: more rays will be shot in bright directions than in dark directions. This reduces the noise, particularly when high-dynamic range images are used for the environment map. When an environment map guides the occlusion rays, the meaning of occlusion changes: instead of being the fraction of the hemisphere being occluded by geometry, it is the fraction of light from the environment (in the positive hemisphere) that is being occluded.
• `"environmentspace"` ```name (uniform string)``` - specifies the name of a coordinate system to apply when accessing the environment map.
• `"brightnesswarp" warp` (uniform float) - specifies whether the environment map should be used to importance sample the hemisphere, i.e. more rays shot in directions where the environment map is bright than in directions where it is dark. (This significantly reduces the noise in the computed environmentcolor.) The meaning of the occlusion function return value changes when an environment map is used like this: instead of being the fraction of the hemisphere that is occluded by objects, it is the brightness-weighted fraction of the hemisphere that is occluded by objects. The default for brightnesswarp is 1 (on). If there is no environment map, this parameter is ignored.
• `"bias" bias` (float) - specifies a float value to offset hemisphere sample origins.  If not provided the trace bias attribute is used.
• "`maxerror" error `(float) - specifies an error metric to control quality/speed tradeoff for occlusion calculations.  If set to zero, the occlusion will be computed at every shading point; no attempt at interpolation will be made.  The larger "maxerror" is, the more time can be saved by interpolating nearby occlusion values.  If not provided or if set to a negative value, the value of the attribute: "irradiance" "maxerror" is used. NOTE: "maxerror" is superseded by the new "maxvariation" parameter and will probably be phased out in a future release.
• `"maxpixeldist"` `dist` (float) - specifies an error metric to control quality/speed tradeoff for occlusion calculations.  If set to zero, the occlusion will be computed at every shading point; no attempt at interpolation will be made.  maxpixeldist is used in conjunction with maxerror or maxvariation and provides a screen-based metric to limit artifacts associated with interpolation.  If not provided or if set to a negative value, the value of the attribute: "irradiance" "maxpixeldist" is used.
• "`maxvariation" var `(float) - specifies an error metric to control quality/speed tradeoff for occlusion calculations.  If set to zero, the occlusion will be computed at every shading point; no attempt at interpolation will be made.  The larger "maxvariation" is, the more time can be saved by interpolating nearby occlusion values.  "maxvariation" specifies how much the interpolated occlusion values are allowed to deviate from the true occlusion. For high-quality final rendering, values in the 0.01 to 0.02 range are typical; for quick preview renderings values of 0.05 or even 0.1 can be used. If "maxvariation" is not provided or is set to a negative value, "maxerror" will be used instead. NOTE: "maxvariation" is a better error metric than "maxerror" and should be used instead of it; the same quality can be obtained with fewer occlusion calculations (and therefore faster) and the control is more intuitive.
• `"seed"` `seed` `(uniform float)` - frame-dependent random directions seed. If "seed" is set to a fixed non-negative number, the ray directions from each point will be fixed from frame to frame. If "seed" is set to -1 (the default) or the frame number, the directions will change from frame to frame.
• `"pointbased"` `pointbased` `(uniform float)` - use point-based occlusion calculation instead of ray tracing.
• `"filename"` `name` (uniform string) - the name of the point cloud file to use for point-based occlusion.
• `"clamp"` `clamp` (uniform float) - the point-based method tends to compute too much occlusion (due to superposition); if this parameter is 1 the over-occlusion is reduced.
• ```"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.
• `"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.
• `"handle"` `name` (uniform string) - this parameter (and the "irradiance" "handle" attribute) will be phased out in a future release. We strongly recommend using the bake3d() and texture3d() functions instead.
• `"filemode"` `mode` (uniform string) - this parameter (and the "irradiance" "filemode" attribute) will be phased out in a future release. We strongly recommend using the bake3d() and texture3d() functions instead.
• `"useopacity" useopacity` (float) - deprecated by the newer hitmode parameter and will be phased out.

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

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

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.

`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 loops 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 phong( normal N; vector V; float size )
{
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;
}```

phong implements the Phong specular lighting model.

```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, point Pdst, ... )`

returns a color representing the ability of light to flow between Psrc and Pdst, i.e. - the transmission function.  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 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 parameters are:

• `"samples"` (varying float)
• `"minsamples"` (varying float)
• `"samplecone"` (varying float)
• `"samplebase"` (varying float)
• `"bias"` (uniform float)
• `"label"`  (uniform string) specifies an arbitrary label to be attached to the ray, can be queried by shaders on surfaces hit by the ray.
• `"subset"` (uniform string) specifies that trace should only find intersections with objects in the given group specification (i.e. a particular accelerator).
• `"hitmode" hitmode` (uniform string) - specifies how the color and opacity should be computed at ray hit points. If the value is "default", the color and opacity are determined as specified by the hit object's "shade" "transmissionhitmode" attribute. If the value is "primitive", the color and opacity are copied from the object's Color and Opacity attributes. If the value is "shader", the shader is evaluated to get the color and opacity. In "primitive" or "shader" mode, if the opacity is less than othreshold, a continuation ray will be fired. In "default" mode, if no attribute "shade" "transmissionhitmode" is defined, the opacity will be considered computed by the shader.
• `"hitsides" hitsides` (uniform string) - specifies which side(s) of one-sided surfaces can be hit by the rays. The possible values are "front", "back", and "both". The default is "both".

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 that must be done per-trace, not on the averaged result of the sub-sample traces.

Adaptive sampling will be be used if both `samples` and `minsamples` are specified (and `minsamples` is greater than 0 and smaller than `samples`): first `minsamples` transmission rays are shot, and if there is variation in the transmission values the remaining samples-minsamples rays will be shot.

The built-in sampling 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);
}
}``````

### Texture Mapping Functions

Texture maps contain data that can be mapped onto the surface of a geometric primitive. The RenderMan Interface supports several types of texture access: basic texture maps (via texture), environment maps (via environment), shadow or z-buffer maps (via shadow), and 3D textures (point clouds and brick maps via texture3d). Texture maps are accessed using two-dimensional coordinates and return floats or colors. Environment maps are accessed using a direction and return floats or colors. Shadow maps are accessed using points and return floats.  3D textures are accessed using points and directions and return arbitrary baked data.

For two-dimensional access (texture), the texture coordinates default to the texture coordinates attached to the surface, (s,t). These default texture coordinates are equal to the surface parameters, the current texture coordinates, or the texture coordinates passed with the geometric primitive. Texture coordinates can also be computed in the Shading Language. This generality allows for many different types of coordinate mappings. Images stored in various map projections can be accessed by computing the map projection given a point on a sphere. This allows basic texture maps to be used as environment maps. Images can also be mapped onto surfaces using a two step process. First the surface of the geometric primitive is mapped to the surface of a parametric primitive, such as a plane or cylinder, and then the parameters of this primitive are used as the texture coordinates. This is sometimes called a decal projection.

For three-dimensional access (environment, shadow, texture3d), the texture coordinates must always be explicitly specified.

There is no restriction on how texture map values are used in the Shading Language. For example, displacement mapping can be performed by moving a point on the surface in the direction of the normal by the amount returned by a basic texture map. Transparency mapping differs from color mapping only in which variable, either `Os` or `Cs`, the texture is assigned to. There is also, in principle, no limit on the number of texture accesses per shader or the number of texture maps per shader or per frame.

Texture maps are created in advance from image data via three types of MakeTexture procedures that are defined as part of the RenderMan Interface. These are described in Part I in the section on Texture Map Utilities. RiMakeTexture creates a texture map for access via texture. RiMakeCubeFaceEnvironment and RiMakeLatLongEnvironment create an environment map for access via environment. RiMakeShadow creates a shadow map for access via shadow. A texture file may contain several channels of information and have any horizontal or vertical resolution. This information is normally inherited from the image from which the texture is made. The s coordinate is assigned to the horizontal direction with increasing values moving right. The t coordinate is assigned to the vertical direction with increasing values moving down. These coordinates are normalized to lie in the range 0 to 1 so that changing the resolution of the texture map has no effect on the shaders that access the texture map. When a texture map is created, the wrap mode is also specified. The wrap mode controls what values are returned if the texture coordinates fall outside the unit square. Allowed wrap modes are: `periodic`, `black` and `clamp`. `periodic` causes the texture data to tile the plane, `black` causes accesses outside the unit square to return the value 0, and `clamp` causes the texture coordinates to be clamped to the closest point on the unit square and the texture value associated with that point to be returned.

The texture access functions normally pass the texture map through a low-pass filter to prevent aliasing. If one set of texture coordinates is given to the access function, the texture will be filtered over the area of the surface element being shaded (see the Shading Rate section in Part I). Four sets of texture coordinates can also be given to the access procedure, in which case the texture is filtered over the quadrilateral determined by those four points. The quality of texture antialiasing is controlled in the same way as spatial antialiasing. Parameters control how true the answer is, the effective number of samples used before filtering, and the type and width of the filter used. For this to be done properly (since texture maps are normally prefiltered), these filtering parameters are best given to the appropriate RiMake... procedure. For flexibility, however, they can also be changed at access time. Table 15.1, Texture Access Parameters gives the standard parameters to all the texture access functions; particular implementations may have additional parameters. If a parameter is encountered by an implementation that does not support its functionality, it should be ignored.

Name Type Description

"`blur`"

`varying float` Specifies an additional area to be added to the texture area filtered in both the s and t directions, expressed in units of texture coordinates.  A value of 1.0 would request that the entire texture file be blurred into the result.  A value of 0.001 would request that one extra texture pixel be added in the case of a one-thousand by one-thousand texture file.
"`sblur`" `varying float`Specifies "blur" individually in the s direction.
"`tblur`" `varying float` Specifies "blur" individually in the t direction.
"`width`"`uniform float` This value multiplies the width of the area being filtered over both the s and t directions.  A value of 0 effectively turns off texture antialiasing.  The default value is 1.0.
"`swidth``uniform float` Specifies "width" individually in the s direction.
"`twidth`"`uniform float` Specifies "width" individually in the t direction.
"`filter`"`uniform string` Specifies the name of the filter to use for filtering over an area of the texture.  The default is "box".  Individual implementations may allow additional filters.
"`fill`"`uniform float` Specifies the value to be provided for channels requested that are not present in the texture file.  This is most often useful for a shader that knows how to use a texture containing an alpha channel.  If no alpha channel is present in the texture file, the texture system quietly provides a default value of 0.0 to requests for the alpha value resulting in a completely transparent texture.  Such a shader could provide its own "fill" value of 1.0 so that textures without an alpha channel would be opaque by default.

#### Basic texture maps

Basic texture maps return either floats or colors.

```float texture( string name[channel]; [texture coordinates,] [parameterlist] )
color texture( string name[channel]; [texture coordinates,] [parameterlist] )```

where texture coordinates is one of the following:

```float s, t;
float s1,t1, s2,t2, s3,t3, s4,t4;```

Return the filtered texture value. The cast before the function determines the type returned, either a float or a color. The name is the name of the texture map created using RiMakeTexture. The channel selector is optional; if it is not present, the brackets are also omitted and channel 0 is assumed. channel selects the starting channel in the texture. The number of channels returned depends on whether the texture is interpreted as a float or a color. texture coordinates are also optional. If present they consist either of a single 2-D coordinate or four 2-D coordinates. If no texture coordinates are given, the current values of (s,t) are used. parameterlist is a list of name-value pairs that allow greater control over texture access.

Texture maps will always be available in implementations that support the Shading Language, and may also be available in the implementation-dependent predefined shaders provided by a rendering system that does not support the Shading Language.

Some examples of the use of this function are:

```c = texture( "logo" [0] );
c = color texture ( "logo" );
c = color texture ( "logo", 2*s, 4*t );```

In the first two cases, the texture coordinates are the current values of the predefined variables `(s,t)`.

#### Environment maps

```float environment( string name[channel]; texture coordinates [, parameterlist] )
color environment( string name[channel]; texture coordinates [, parameterlist] )```

where texture coordinates is one of the following:

```vector R;
vector R1, R2, R3, R4;```

Return the filtered texture value from an environment map. The cast before the function determines the type returned, either a float or a color. The name is the name of the texture map created using RiMake...Environment. The channel selector is optional; if it is not present, the brackets are also omitted and channel 0 is assumed. channel selects the starting channel in the texture. The number of channels returned depends on whether the texture is interpreted as a float or a color. This function expects either a single texture coordinate or four texture coordinates. These are points that are used to define a direction in space. The length of this vector is unimportant. parameterlist is a list of name-value pairs that allow greater control over texture access.

If a particular implementation does not support the Environment Mapping capability, environment will always return (0,0,0) (no illumination).

Shadow depth maps are z-buffer images as seen from a particular view point. Normally a shadow map is associated with a light source and represents a depth buffer rendered from the point of view of the light source. The texture coordinate of a shadow map is a point. The value returned is the fraction of points on the shaded surface that are farther from the light than the surface recorded in the depth map. A value of 1 indicates that the surface is completely in shadow and a value of 0 indicates that the surface is completely illuminated by the light source.

```float shadow( string name[channel]; texture coordinates [, parameterlist] )
color shadow( string name[channel]; texture coordinates [, parameterlist] )```

where texture coordinates is one of the following:

```point P;
point P1, P2, P3, P4;```

Return the shadow value from a shadow depth map. The name is the name of the texture map created using RiMakeShadow. The channel selector is optional; if it is not present, the brackets are also omitted and channel 0 is assumed. channel selects the starting channel in the texture. texture coordinates are points in the coordinate system in which the depth map was created. parameterlist is a list of name-value pairs that allow greater control over texture access.

Table 15.2 Shadow Map Access Parameters

Name Type Description
"`blur`" `varying float` Specifies an additional area to be added to the texture area filtered in both the s and t directions, expressed in units of texture coordinates.  A value of 1.0 would request that the entire texture file be blurred into the result.  A value of 0.001 would request that one extra texture pixel be added in the case of a one-thousand by one-thousand texture file.
"`sblur`" `varying float`Specifies "blur" individually in the s direction.
"`tblur`" `varying float` Specifies "blur" individually in the t direction.
"`width`"`uniform float` This value multiplies the width of the area being filtered over both the s and t directions.  A value of 0 effectively turns off texture antialiasing.  The default value is 1.0.
"`swidth``uniform float` Specifies "width" individually in the s direction.
"`twidth`"`uniform float` Specifies "width" individually in the t direction.
"`samples`"`uniform float` The effective sampling rate when filtering.
`"bias"``uniform float` Specifies an additional bias to add to shadow depth lookups in order to prevent incorrect self-shadowing of objects.
"`filter`"`uniform string` Specifies the name of the filter to use for filtering over an area of the texture.  The default is "box".  Individual implementations may allow additional filters.

#### 3D texture maps: Point cloud files and brick maps

Point cloud files are volumetric files containing 3D point samples of arbitrary data. Point cloud files are generated with the bake3d() function.

```float bake3d( string filename, string displaychannels, point P, normal N, ... ) ```

writes a point with associated data to the file given by filename. The return value indicates the success or failure of the write.

Required parameters:

• `string filename`
the file name to write the 3D points to. (If the optional parameter 'cachelifetime' is "frame" or "shadinggrid", this parameter is a cache name instead of a file name.)
• `string displaychannels`
a string consisting of a comma-separated list of channel names. (Each channel must be specified in the rib file with the DisplayChannel statement). (Displaymode is ignored if the optional parameter 'cachelifetime' is "frame" or "shadinggrid".)
• `point P, normal N`
describes the location and surface orientation for which the data were computed.

Optional parameters:

• `float radius`
the radius specifies the size of the area that the data point represents. If no radius is specified, one will be automatically computed from the distance to the nearest shading points.
• `float radiusscale`
• `string coordsystem`
the name of the coordinate system to store the data points in. By default, the world coordinate system is used.
• `string cachelifetime`
specifies the lifetime of the cache. "file" or "" (the default) means that the data are streamed to a file via the display system. "frame" or "shadinggrid" means that the data are written to a cache of that lifetime.
• `float interpolate`
point positions, normals, radii, and data are interpolated from four shading points when this parameter is set. This means that micropolygon midpoints are baked out instead of the exact shading points. This is great for many applications because it eliminates the double shading points along edges of shading grids. This behavior is probably only useful if the P points passed to bake3d() are the original shading point positions. This parameter is off by default (but recommended for tasks such as baking direct illumination for subsurface scattering).
• `string driver`
The name of the driver used to write the point information to disk. Depending on the implementation, there may be a choice of drivers supplied that support different on-disk representations of the baked data. Note that there is no guarantee that texture3d will support the data written by an arbitrary driver.

Data:

• `name, value`
pairs of the name and values of the data to be stored. The data can be of type float, point, vector, normal, color, or matrix.

A brick map is a tiled MIP map representation of 3D data. Brick maps can be created from point clouds using the brickmake program or via the RiMakeBrickMap and MakeBrickMap procedures that are defined as part of the RenderMan Interface. They are described in the Texture Map Utilities section. Due to the tiling and MIP map representation, brick maps are much more amenable to efficient caching than point cloud files. Brick map textures (and point cloud textures) are read with the texture3d function.

```float texture3d( string filename, point P, normal N, ... ) ```

reads texture values from the brick map (or point cloud) file given by filename. The function return value is 1 if the read was successful, and 0 if it failed.

Required parameters:

• `string filename`
the file name to read the 3D texture values from. (If the optional parameter 'cachelifetime' is "frame" or "shadinggrid", this parameter is a cache name instead of a file name.)
• `point P, normal N`
the location and surface orientation for the 3D texture lookup.

Optional parameters:

• `float filterradius`
the radius of the disk/sphere that the lookup covers. If no radius is specified, one will be automatically computed from the distance to the nearest shading points. If set to 0, the voxel data are not interpolated; instead, we just use the data values of the finest voxel that point P is in.
• `float filterscale`
a multiplier on filterradius. Default is 1.
• `float maxdepth`
max depth for lookup up in brick map. (Great for debugging, especially when used with filterradius 0.)
• `float lerp`
if lerp is set to 1: do two lookups in brick map (at two different depths) and linearly interpolate the results.
• `string coordsystem`
the name of the coordinate system to lookup the texture values in. By default, the world coordinate system is used.
• `string cachelifetime`
specifies the lifetime of the cache. "file" or "" (the default) means that the data are read from a file. "frame" or "shadinggrid" means that the data are read from a cache of that lifetime. Cachelifetime for a given cache must agree with the cache lifetime specified for that cache in bake3d().
• `float errorcode`
a return value indicating what caused the texture3d() lookup to fail. Meaning: 0 = no error (success), 1 = file does not exist, 2 = file is not a brick map file, 3 = read error while reading file header, 4 = read error while reading brick, 5 = the requested data do not exist in the brick map, 6 = lookup point P is outside the bounding box of the brick map, 10 = some other error.

If the file is a point cloud file, the filterradius, filterscale, maxdepth, and lerp parameters are ignored, and no error code is returned. (The coordsystem parameter is still used, though.)

Data:

• `name, value`
pairs of the name and values of the data to be looked up. The data can be float, point, vector, normal, color, or matrix.

#### Photon maps

Photon maps are sparse volumetric files containing photons.  Photon maps can be computed in many ways but usually contain photons that have been previously scattered (in a separate pass) through the same 3-D world in which the accesses are made.  Photons represent light that has been "forward traced" into the 3-D world and hit a surface.

```color photonmap( string filename, point P, normal N, ... )```

returns the result of a photonmap lookup at surface point P with surface normal N.  Parameters include:

• `"lookuptype"` (uniform string)
• "`irradiance`" - looks up the irradiance (prior to local BRDF interaction).
• "`radiance`" - looks up the radiance (after interacting with the surface BRDF). Not supported in PRMan release 12 and higher.
• `"estimator"` (uniform float) - specifies the number of photons to consider when estimating the photon effect.

#### Getting Information About Texture Maps

`float textureinfo( string texturename, dataname; output type variable )`

Returns data about a particular texture map, specified by the file name texturename.  The dataname specifies the piece of information that will be returned in variable.  If the dataname is known to the renderer and its type and storage class match that of variable, the named data will be written into variable and textureinfo() will return a value of 1.0.  If the data is unknown or the types do not match, variable will be unchanged and textureinfo() will return 0.0.  Note that textureinfo data is always uniform.  If variable is varying, the appropriate varying-to-uniform conversion will take places.  The standard data names supported by textureinfo() listed below.  A particular implementation may support addition textureinfo queries.

Table 15.3 Data names known to the textureinfo function

Name Type Description
"`resolution`" ```uniform float[2]``` The highest resolution of the texture map..
`"type"` ```uniform string ``` Returns the type of the texture map file: "texture", "shadow", or "environment".
"`channels`" `uniform float` Returns the number of channels in the map.
`"viewingmatrix"` `uniform matrix` Returns a matrix that transforms points from "current" space to the "camera" space from which the texture was created. *
`"projectionmatrix"` `uniform matrix` Returns a matrix that transforms points from "current" space to a 2D coordinate system where x and y range from -1 to 1. *
* only available for shadow maps or other textures that were cdreated by rendering an image, and assume a common world-space of all cameras.

### Message Passing and Information Functions

```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 )```

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.  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.

```float incident( string paramname, output type variable )
float opposite( string paramname, output type variable )```

These functions access the value of the volume shader parameter paramname that is stored in the volume shaders attached to geometric primitive 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 named variable exists and is of the correct type, the value is stored in value and the function returns 1.0; otherwise, value is unchanged and the function returns 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.

`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.

Table 15.4 Data names known to the attribute function

Name Type
"`ShadingRate`" `uniform float`
"`Sides`" `uniform float`
"`matte`" `uniform float`
"`GeometricApproximation:motionfactor`"`uniform float`
```"displacementbound:sphere" *````uniform float`
```"displacementbound:coordinatesystem" *````uniform string`
```"identifier:name" *````uniform string`
```* note that "displacementbound:sphere' does not return the value exactly as specified in the RIB file, but rather returns its length in the coordinate system returned by "displacementbound:coordinatesystem".```
`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.

Table 15.5 Data names known to the option function

Name Type Description
"`Format`" ```uniform float[3]``` The resolution (x, y) and pixel aspect ratio.
`"DeviceResolution"` ```uniform float[3] ``` The resolution (x, y) and pixel aspect ratio.  These are usually the three numbers passed to RiFormat, but may be different when RiFrameAspectRatio or RiScreenWindow are non-square.
"`FrameAspectRatio`" `uniform float` Frame aspect ratio.
`"CropWindow"` ```uniform float[4]``` Boundaries of the crop window.
`"DepthOfField"` ```uniform float[3]``` fstop, focallength, focaldistance.
`"Shutter"` ```uniform float[2]``` Shutter open and close time.
`"Hider"` `uniform string` The name of the active hider.
`"Clipping"` ```uniform float[2]``` Near and far clip depths.
`uniform float rayinfo( uniform string keyword, result, ... )`

Provides access to state associated with the ray that 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) {
} 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 that caused this shader to be invoked.
• `"diffusedepth", uniform float diffusedepth`
returns the diffuse depth of the ray that caused this shader to be invoked.
• `"shadowdepth", uniform float shadowdepth`
returns the "shadow depth" of the ray that 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 that 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 that 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`
• `march`
• `"label", uniform string label`
returns the value of the user-defined label assigned to the ray that 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|.
`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.

Table 15.6 Data names known to the rendererinfo function

Name Type Description
"`renderer`" `uniform string` The brand name of the renderer.
`"version"` ```uniform float[4] ``` Major, minor, release and patch numbers.
"`versionstring`" `uniform string` The release numbers expressed as a string.
```string shadername()