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 pre-declare the types of the variables that they use. Certain other variables, such as position, are also pre-declared. Additional variables are declared with:

     RtToken
     RiDeclare(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:

        [class] [type] [ ‘[’ n ‘]’ ]

where class may be constant, 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, color, point, vector, normal, matrix, and hpoint. Most of these types are described in Section 11, Types, which describes the data types available in the Shading Language. The Shading Language does not have an integer type, but integers may be passed through the interface as arguments to options or attributes. Additionally, the hpoint is used to describe 4D homogeneous coordinates (for example, used to describe NURBS control points). Any hpoint values are converted to ordinary points by dividing by the homogeneous coordinate just before passing the value to the shader. 

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.

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 

	EXAMPLE
	   RiDeclare ( "Np", "uniform point" );
           RiDeclare ( "Cs", "varying color" );

	   Declare "st" "varying float[2]"

In addition to using RiDeclare to globally declare the type of a variable, the type and storage class of a variable may be declared “in-line.” For example:

RiSurface ( "mysurf", "uniform point center", &center, RI NULL );
RiPolygon ( 4, RI P, &points, "varying float temperature", &temps, RI NULL );

Patch "bilinear" "P" [...] "vertex point Pref" [...] "varying float[2] st" [...]

When using these in-line declarations, the storage class and data type prepend the token name. Thus, any RenderMan Interface routines or RIB directives that take user-specified data will examine the tokens, treating multi-word tokens that start with class and type names as an in-line declaration. The scope of an in-line declaration is just one data item — in other words, it does not alter the global dictionary or affect any other data transmitted through the interface. Any place where user data is used and would normally require a preceding RiDeclare, it is also legal to use an in-line declaration.

The storage modifiers vertex, varying, facevarying, uniform, and constant 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 pre-declare other variables for use with implementation-specific options, geometry, etc.

Whenever a point, vector, normal, matrix, or hpoint variable is passed through the RenderMan Interface to shaders, the values are assumed to be relative to the current coordinate system. This is sometimes referred to as object coordinates. Different coordinate systems are discussed in the Camera section.

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

No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, without the prior written permission of Pixar. The information in this publication is furnished for informational use only, is subject to change without notice and should not be construed as a commitment by Pixar. Pixar assumes no responsibility or liability for any errors or inaccuracies that may appear in this publication.