Several proprietary extensions have been made to the Shading Language in PhotoRealistic RenderMan 3.6, in order to facilitate writing more powerful systems of shaders. There are several new or enhanced built-in functions, two new variable types for vectors, better control of specular and diffuse lighting, a generalization of distant lights for environment mapping, and a new persistent data type which provides the basis of a "blackboard"-style message passing system.

The following new built-in functions have been added to the Shading Language:

float inversesqrt( float x )

Returns 1.0 / sqrt( x ).

float random( )
point random( )

These functions did not previously work in PhotoRealistic RenderMan, even though the Shading Language compiler believed they did. Now they do.

point vtransform( string fromspace, tospace; point V )
point vtransform( string tospace; point V )
point ntransform( string fromspace, tospace; point N )
point ntransform( string tospace; point N )

Transform the direction vector V (or the normal vector N) from the coordinate system fromspace to the coordinate system tospace, just like the transform function. These functions are useful because vectors and normals transform through different transformation matrices than points, and this meant that shaders which needed to transform vectors or normals used additional calculations (like subtracting origins) to correct for the difference.

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

Transform the color C from the color respresentation fromspace to the color respresentation tospace. If fromspace is absent, it is assumed to be "rgb".

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

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

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

This new Shading Language function provides an analytically antialiased step function. In its simplest form, with two arguments, it takes parameters identical to step, but returns a result which 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 page 129 of the RenderMan Interface Specification, Texture Mapping Functions). The parameterlist provides control over the filter function, and may include the following parameters: "width" (aka "swidth"), the amount to "overfilter" is 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 cellnoise( float x )
float cellnoise( float s, float t )
float cellnoise( point pt )
float cellnoise( point pt, float t )
point cellnoise( float x )
point cellnoise( float s, float t )
point cellnoise( point pt )
point cellnoise( point pt, float t )
color cellnoise( float x )
color cellnoise( float s, float t )
color cellnoise( point pt )
color cellnoise( point pt, float t )

Returns a value which is a random function of its arguments. It's domain is 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 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. A new Applications Note describes cellnoise in more detail.

The following built-in Shading Language functions have been extended to add greater flexibility and to increase the overall efficiency of shaders which use them.

float min( float a, b, ... )
point min( point a, b, ... )
color min( color a, b, ... )
float max( float a, b, ... )
point max( point a, b, ... )
color max( color a, b, ... )
float clamp( float a, min, max )
point clamp( point a, min, max )
color clamp( color a, min, max )
float mix( float fg, bg; float value )
point mix( point fg, bg; float value )
color mix( color fg, bg; float value )

Each of these functions now accept float, point or color arguments. In the case of point and color, the results are computed element by element. The min and max functions now take two or more arguments, and returns the overall minimum/maximum value.

float spline( [string basis;] float value; float f1,f2,...,fn,fn1 )
color spline( [string basis;] float value; color f1,f2,...,fn,fn1 )
point spline( [string basis;] float value; point f1,f2,...,fn,fn1 )

A new optional first parameter basis has been added to all versions of the spline function. It specifies the cubic basis function to use to interpolate the spline. This parameter is a string which can take any of the following values: "catmull-rom", "bezier", "bspline", "hermite", or "linear". The default basis is "catmull-rom". 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.

float noise (point pt, float t)
color noise (point pt, float t)
point noise (point pt, float t)

The noise function now comes in a variety which takes a point and a float as arguments. This 4-dimensional domain may be interpreted as time-varying noise. Thus, you may now compute noise in 3-space which varies with time.

float shadow ( ..., parameterlist )

A new parameter value "bias" is now available in the shadow function. This value overrides any global shadow bias values set by the input model, for this single shadow-map lookup.

float texture ( ..., parameterlist )
color texture ( ..., parameterlist )
color environment ( ..., parameterlist )

Two new optional parameters have been added to the texture() and environment() functions "filter" selects the filter to be used when sampling the texture data. It takes uniform string value. Possible values are "box" and "gaussian". The default is "box". Use of "gaussian" should produce higher quality results. "lerp" selects whether to interpolate between adjacent resolutions of a multi-resolution texture in order to smooth the transition between resolutions. It takes a uniform float value. Possible values are 0.0 to disable the interpolation and 1.0 to enable it. The default is 0.0 to not interpolate. These can be disabled by an

2. Variable Types

The RenderMan Interface Specification Version 3.1 specifies that the Shading Language has exactly four data types: float, point, color, and string. This set has been extended to include two variants on point types: vector and normal.

Variables declared as vector and normal behave identically to variables declared as point in most situations. point, vector and normal variables can be arbitrarily assigned from one to another and can be used identically in expressions and function arguments. There is no implicit type checking or type coersion in any of these standard uses. There are exactly two differences in behavior between the three types: transformation of shader parameters provided through the RI, and casting values to these types in the Shading Language.

When a shader parameter is declared (with Declare in a RIB file or with RiDeclare in an RI program) to be a vector, any value provided for that variable in any RI call will be transformed into current space using the vtransform function described above. When a variable is declared to be a normal, any value provided for that variable in any RI call will be transformed into current space using the ntransform function. Note that the declaration of the variable in the Shading Language code does not invoke this functionality (in the current implementation). It is the declaration in the RI stream that determines this behavior.

When a triple of floating point values is assigned to a point, vector or normal variable using the type cast operator, an optional coordinate system name can be specified, such as

foo = point "object" (0, 0, 0);
bar = vector "world" (s, t, u);
baz = normalize( normal "world" (xcomp(N), 0.5, zcomp(N)) );

These operators now transform the triples of floats from the named coordinate system to the current coordinate system using the appropriate transformation routine. Variables declared as vectors and normals do not automatically call vtransform or ntransform when used as arguments or destinations of the point transform routine. This is left to the SL programmer.

Note: Prior to PRMan 3.6, the keyword vector was reserved in the Shading Language, but it was an alias for point, and did not have the new behavior described above.

3. Lighting Control

The specular and diffuse shadeops now respond to two special parameters of the light shader. Any light shader which contains the following parameter

float __nondiffuse = 1

will be ignored by diffuse (note that there are two underbars). Similarly, any light which contains the following parameter

float __nonspecular = 1

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. These variables may be either uniform or varying. These special parameters can also be accessed within illuminance statements, as described in the section on Message Passing.

The illuminance statement, as well as the specular and diffuse shadeops, now correctly ignore all ambient lights (lights where L = (0,0,0)).

4. Broad Solar Lights

The solar block is used by distantlight to specify a light which is emitted from infinity along a particular axis direction. In this use, the solar block takes two arguments, the axis vector A, and 0.0, which is the angular width of the emission cone. The RenderMan specification refers to the fact that this cone can have non-zero width, and specifically mentions the use of solar with no arguments to write an environment mapping light source using a 360 degree cone, but PhotoRealistic RenderMan has never supported this feature.

PhotoRealistic RenderMan now supports solar cones of any angular width, including the zero-argument omnidirectional case. The meaning of a non-zero width solar cone is extremely confusing to explain. Nonetheless, imagine a distant light source which is willing to emit light in any of a range of directions (not just down its axis vector), and merely needs the renderer to tell it which direction is pointed most favorably toward the specular highlight of surface. Another way of thinking of it is a large area light source, located at infinity, where each point on the area light is emitting a little spotlight.

The most obvious example is an environment-mapping light. The light wants to cast the environment texture map like a slide projector from infinity, and just needs to know which pixel on the map will reflect back into the camera. The pixel to choose is based entirely on the reflection direction R of the surface; the light itself is willing to send light in any direction as needed.

The second example is a diffuse skylight, where light is arriving on the surface from everywhere above it, and would like to be colored by all of it (radiosity-style). In this case, the solar light cone would be a hemisphere pointed down.

At this time, PhotoRealistic RenderMan will not point-sample the area light source, but it will attempt to find the most favorable direction by considering the size of the solar cone and the surface's reflection direction. The light direction vector L inside the solar block will be this direction. In the specific case of an omnidirectional light, this L will be exactly equal to -R. For narrower solar cones, it will be some vector between -R and A, such that it falls within both cones and is somewhat central to the intersection of the cones.

Here is a light source which casts an environment map onto a surface. Notice the use of the __nondiffuse flag to put the environment only in the specular component (since environment maps are really specular reflections of the worldsphere).

light envir ( string mapname = ""; float __nondiffuse = 1; ) {
	solar() {
		Cl = environment(mapname, vtransform("world", -L));
	}
}

Note: Some surface shaders use non-standard reflection directions for their specular highlights. For example, some anisotropic shaders (such as brushedmetal) have multiple specular highlights, none of them in the "normal" place. solar's guess about which direction is the most favorable direction will be wrong in these cases.

5. Message Passing

There are four new Shading Language functions which permit shaders to peek at the parameters of the other shaders that are being executed on the same piece of geometry. This permits shaders to customize their behavior based on their knowledge of what the other shaders will do with those parameter settings.

float atmosphere( string param; {float|point|color|string} var )
float displacement( string param; {float|point|color|string} var )
float lightsource( string param; {float|point|color|string} var )
float surface( string param; {float|point|color|string} var )

These functions access the value of the parameter named param of one of the shaders attached to the geometric primitive that is currently being shaded. If the appropriate shader exists, and a parameter named param exists in that shader, and the parameter is the same type as the variable var, the value of that parameter is stored in var and the function returns 1; otherwise, var is unchanged and the function returns 0. lightsource is only available inside illuminance blocks.
Note that if the parameter named param is uniform, but the variable var is varying, the appropriate uniform-to-varying conversion will take place, however, the reverse case is considered failure.

For example, the new diffuse shadeop, which notices the special __nondiffuse light parameter, can now be written as follows:

color diffuse( point N ) {
	color C = 0;
	point Nn, Ln;
	uniform float nondif;

	Nn = normalize( N );
	illuminance( P, Nn, PI/2 ) {
#if EITHER_WAY
		nondif = 0;
		lightsource("__nondiffuse", nondif);
#else
		if (lightsource("__nondiffuse", nondif)==0)
			nondif = 0;
#endif
		if (nondif == 0) {
			Ln = normalize( L );
			C += Cl * Ln.Nn;
		}
	}
	return C;
}

Parameters to a shader typically cannot be modified by the shader. For example, the following shader

surface foo ( float bar = 1 ) {
	bar = 2;
}

will generate the following error if compiled

"foo.sl", line 2: shader "foo" - warning: "bar" readonly but modified

This can now be eliminated by the use of the new keyword output:

surface foo ( output float bar = 1 ) {
	bar = 2;
}

Shaders can set flags and send them as "messages" to other shaders, by placing them in this globally-visible "blackboard" of output parameters, where they can be received (using the parameter-reading functions above) by any other shader that is savvy to their existence.

A more powerful variation of this theme is to use output varying parameters. This way, shaders can compute arbitrary values that vary across the surface, and pass them to other shaders. For example, consider the following pair of shaders, which shade a displaced surface based on the original shape (if that information is available).

displacement wavy (float height = 1; output varying point oldP = 0;) {
	point Po = transform("object", P);
	point No = ntransform("object", N);

	oldP = Po;
	Po += height * normalize(No) * sin(2*PI*s);
	P = transform("object", "current", Po);
}

surface prepainted (float Kd = .5) {
	point Po;

	if (displacement("oldP", Po)==0)
		Po = transform("object", P);
	Ci = Kd * texture("monasmile.tx", xcomp(Po), ycomp(Po));
}

Notice that prepainted will work correctly if there is no displacement shader, and do the best it can if the displacement does not set oldP, but will have the special effect if oldP does exist.

Unlike standard varying parameters, output varying parameters do not need to be bound to the geometry in the RIB file. However, there is currently an implementation limitation (aka bug) whose effect is to make the default initialization values and the RIB overrides of those defaults not always be correct for output varying parameters. The programmer should not rely on those values, even within the shader itself. In other words, it is best for a shader to consider its output varying parameters to be write-only.

The wily programmer may ask: At what point in the shading pipeline do output parameters get set so that I can read them? (Since there is no restriction on the use of the reading functions, one might imagine that the displacement shader might try read an output of the atmosphere shader before the atmosphere has ever been run.) The answer is complicated, but the basic rules are:

• If an output uniform value is set by its default, or by an override in the RIB file, it will be valid at all times.
• As mentioned above, the default value and RIB override value of an output varying value is unreliable, and should never be used.
• Values computed and output by the shader are handled during the normal execution of the shader, and so will be available and valid if the sender is run first, and will be bogus if the receiver is run first. For reference, shaders are executed on a primitive in the following order: displacement; all of the lights; surface; atmosphere.

6. Reminder About Undocumented Functions

There are functions which have always been available in the Shading Language that are not documented in the RenderMan specification, and have therefore faded into undeserved obscurity. These functions are alive and well, and are available for use.

float ptlined( point P0, point P1, point Q )

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

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

pnoise returns a value similar to noise with the same arguments, however, the noise value returned by pnoise is periodic with period period. That is, pnoise(v, p) == pnoise(v+p,p). period must have an integer value (if it is a float expression), or lie on the integer lattice (if it is a point expression).

---

RenderMan Artist Tools Home Page
RenderMan Toolkit | ATOR | Combiner | Alfred | Looks | Textures
Pixar Home Page


---

Copyright © 1996 Pixar. All rights reserved. RenderMan® is a registered trademark of Pixar.
Pixar Animation Studios, 1001 West Cutting Blvd., Richmond, CA 94804
510-236-4000 (voice) 510-236-0388 (fax)