Section 3 - Relationship to the RenderMan Shading Language

The capabilities of the RenderMan Interface can be extended by using the Shading Language. The Shading Language is described in Part II of this document. This section describes the interaction between the RenderMan Interface and the Shading Language.

Special procedures, called shaders, are declared in this language. The argument list of a shader declares variables that can be passed through the RenderMan Interface to a shader. For example, in the shading language a shader called weird might be declared as follows:

     surface

     weird( float f = 1.0; point p = (0,0,0) )

     {

	          Cs = Ci * mod( length(P-p)*f - s + t, 1.0 );

     }

The shader weird is referred to by name and so are its variables.

     RtFloat	foo;

     RtPoint	bar;

     RiSurface("weird","f", (RtPointer)&foo, "p", (RtPointer)bar, RI_NULL);

passes the value of foo to the Shading Language variable f and the value bar to the variable p. Note that since all parameters are passed as arrays, the single float must be passed by reference.

In order to pass shading language variables, the RenderMan Interface must know the type of each variable defined in a shader. All predefined shaders predeclare the types of the variables that they use. Certain other variables, such as position, are also predeclared. Additional variables are declared with:

     RtToken

     RiDeclare( name, declaration )

          char	*name;

          char	*declaration;

Declare the name and type of a variable. The declaration indicates the size and semantics of values associated with the variable, or may be RI_NULL if there are no associated values. This information is used by the renderer in processing the variable argument list semantics of the RenderMan Interface. The syntax of declaration is exactly as described for variables in the Shading Language.

RiDeclare also installs name into the set of known tokens and returns a constant token which can be used to indicate that variable. This constant token will generally have the same efficient parsing properties as the `RI_' versions of the predefined tokens.

     RIB BINDING

     Declare name declaration 

RiDeclare only needs to be powerful enough to support the declarations which a user needs: declaring shader variables and his own geometric primitive variables. The RIB stream declaration facility needs to be more powerful because it must be able to handle both predefined symbols and implementation-specific predefined option and attribute values which might be impossible to declare using the limited facility described above. Therefore, the exact syntax for declaration in RIB is more general:

     [class] [type] [`[' n `]'] 

where class may be uniform, varying (as in the shading language), or vertex (position data, such as bicubic control points), and type may be one of: float, integer, string, point, and color. The optional bracket notation indicates an array of n type items, where n is a positive integer. If no array is specified, one item is assumed. If a class is not specified, the identifier is assumed to be uniform.

     EXAMPLE

          RiDeclare( "Np", "uniform point" );

          RiDeclare( "Cs", "varying color" );

          Declare "st" "varying float[2]"  

The storage modifiers varying and uniform are discussed in the section on Uniform and Varying Variables in Part II and in Section 5, Geometric Primitives. All procedure parameter tokens and shader variable name tokens named in this document are standard and are predefined by all implementations of the RenderMan Interface. In addition, a particular implementation may predeclare other variables for use with implementation-specific options, geometry, etc.

Whenever a point variable is passed through the RenderMan Interface to shaders, the points are assumed to be in the current coordinate system. This is sometimes referred to as object coordinates. Different coordinate systems are discussed in the Camera section. Normals ("N" and "Np") are also assumed to be in object coordinates.

Whenever colors are passed through the RenderMan Interface, they are expected to have a number of floats equal to the number of color samples being used by the interface. This defaults to 3, but can be changed by the user (see the section on Additional options).