Types

Floats
Colors
Points, Vectors and Normals 
Transformation Matrices
Arrays
Strings 
Uniform and Varying Variables

The Shading Language is strongly typed and supports the following basic types:

Floats

Floats are used for all scalar calculations. They are also used for integer calculations.

Floating-point variables are defined as follows:

     float a, b=1;

The initialization value may be any scalar expression that contains only uniform operands.

Colors

The Shading Language implements color as an abstract data type independent of the number of samples and the color space. The major operations involving color are color addition (`+' operator) corresponding to the mixing of two light sources, and color filtering (`*' operator) corresponding to the absorption of light by a material. In each case these color operations proceed on a component by component basis.

The number of color samples used in the rendering program is set through the RenderMan Interface. Once the number of color samples has been specified, colors with the appropriate number of samples must be passed to a shader. When setting the number of samples, the user can also specify a transformation from RGB space to this n sample color space. This allows a shader to convert color constants to the specified color space.

Color component values of 0 correspond to minimum intensity, while values of 1 correspond to maximum intensity. A color constant of 0 is equivalent to black, and of 1 is equivalent to white. However, values outside that range are allowed (values less than zero decrement intensity from other sources).

Color variables may be declared with:

      color c, d=1, e=color(1,0,0);

The initialization value may be any scalar or color expression that contains only uniform operands. If a scalar expression is used, its value is promoted to a color by duplicating its value into each component.

Color constants are specified by:

      color [space] (u,v,w)

The optional specifier space indicates the color coordinate system of the 3-tuple. The default color coordinate system is "rgb." Table 11.1, Color Coordinate Systems, lists the color coordinate systems that are supported in the Shading Language.

Table 11.1 Color Coordinate Systems

Points, Vectors, and Normals

Point-like variables are (x,y,z) triples of floats that are used to store locations,direction vectors and surface normals.

A point is a position in 3D space.  A vector has a length and direction, but does not exist in a particular location.  A normal is a special type of vector that is perpendicular to a surface and thus describes the surface's orientation.

All calculations involving points. vectors and normals are assumed to take place in an implementation-dependent coordinate system, usually either the camera or world coordinate system. Procedures exists to transform points, vectors and normals from the shading coordinate system to various named coordinate systems, or to define a point, vector or normal in one of several coordinate systems and transform it to the shading coordinate system. It should be noted that point locations, direction vectors and normals do not transform in the same way as, and therefore it is important to use the correct transformation routine for each type.

A number of standard coordinate systems are known to a shader. These include: "raster", "NDC", "screen", "camera", "world", and "object". These are discussed in the section on Camera in Part I. In addition, a shader knows the coordinate systems shown in Table 11.2, Point Coordinate Systems.

Table 11.2 Point Coordinate Systems

Point variables are declared:

     point u, v=1, w=point(1,1,1);
     vector R;
     normal Nf;

The initialization value may be any scalar or point-like expression. If a scalar expression is used, the value is promoted to a point (or vecdtor or normal) by duplicating its value into each component.

Point, vector and normal constants default to be in the "current" coordinate system. Points, vectors and normals can be specified in any known coordinate system with:

     point [space] (x,y,z)
     vector [space] (x,y,z)
     point [space] (x,y,z)

where the space is a string literal containing the name of the coordinate system.  For example,

     point "world" (0,0,0)

defines a point at the position (0,0,0) in world coordinates. This point is implicitly transformed to the "current" coordinate system. Similarly, 

     vector "object" (0,0,1)

defines a vector pointing toward the +z axis in "object" space, which is implicitly transformed into the equivalent vector expressed in the "current" coordinate system.  Points, vectors and normals passed through the RenderMan Interface are interpreted to be in "shader" or "object" space, depending on whether the point variable was set using a shader command or a geometric primitive command, respectively.

Transformation Matrices

The Shading Language has a matrix type that represents the transformation matrix require to transform points and vectors from one coordinate system to another.  Matrices are represented internally by 16 floats (a 4 x 4 homogeneous transformation matrix).

A matrix can be declared:

   matrix zero = 0;
   matrix ident = 1;
   matrix m = matrix(m00, m01, m02, m03, m10, m11, m12, m13,
                     m20, m21, m22, m23, m30, m31, m32, m33);

Assigning a single floating-point number c to a matrix will result in a matrix with diagonal components all being c and other components being zero (i.e., c times the identity matrix).  Constructing a matrix with 16 floats will create the matrix whose components are those floats, in row-major order.

Similar to point-like types, a matrix may be constructed in reference to a named space.

   matrix q = matrix "shader" 1;
   matrix m = matrix "world" (m00, m01, m02, m03, m10, m11, m12, m13,
                              m20, m21, m22, m23, m30, m31, m32, m33);

The first form creates the matrix that transforms points from "current" space to "shader" space.  Transforming points by this matrix is identical to calling transform("shader", ...).  The second form prepends the current-to-world transformation matrix onto the 4 x 4 matrix with components m00 - m33.  Note that although we have used "shader" and "world" space in our examples, any named space is acceptable.

Strings

Strings are used to name external objects (texture maps, for example). String literals (or constants) are enclosed in double quotes, as in the C language, and may contain any of the shadard C "escape sequences" (such as \n for newline or \" for a quote).

Arrays

The Shading Language supports 1D arrays of all the basic data types. Local variable arrays declared in scope must be of fixed, predeclared (compile-time) lengths. Zero and negative-length arrays in any scope or context are not permitted.

As in C, the syntax for declaring a fixed size array of any data type uses square brackets, i.e. datatype[length]. length is a float constant, which is rounded down to generate an integer length. The syntax for specifying the data of a constant array uses curly braces: {value1, value2, ...}. For example:

  float a[10];
  uniform color C[4], float b[4] = {3.14, 2.17, 0, -1.0};

Arrays which are shader instance variables or function formal parameter declarations are allowed to be of indeterminate length; the length (and the value) of these arrays will be initialized either by the shader instance or from the geometry. The syntax for such declarations uses square brackets, but with no length specified: datatype[]. These variables must be initialised using curly braces as well, but without any enclosed values: {}. For example

surface myshader(uniform color C[] = {}; float b[] = {})

The length of an varying length array can be determined using the arraylength shadeop.

As in C, individual array elements may be referenced using the familiar square bracket notation. An array element index is a float expression, which is rounded down to generate an integer index. Shading Language arrays perform over/underrun checking at run-time. Unlike C, arrays can be assigned to each other as long as they are of the same type and length. Entire arrays can also be compared for equality.

Uniform and Varying Variables

A renderer implementation may choose to shade many points, or even large regions of a surface, at once.  How large such a region may be is implementation-dependent. 

Shaders contain two classes of variables: uniform variables are those whose values are constant over whatever portion of the surface begin shaded, while varying variables are those that may take on different values at different locations on the surface being shaded. For example, shaders inherit a color and a transparency from the graphics state. These values do not change from point to point on the surface and are thus uniform variables. Color and opacity can also be specified at the vertices of geometric primitives (see Section 5, Geometric Primitives). In this case they are bilinearly interpolated across the surface, and therefore are varying variables.

Local variables and arguments to shaders are declared to be either uniform or varying by specifying a storage modifier:

     varying point p;
     uniform point q;

Variables declared in the argument list of a shader are assumed to be uniform variables by default. These are sometimes referred to as instance variables. If a variable is provided only when a shader is instanced, or if it is attached to the geometric primitive as a whole, it should be declared a uniform variable. However, if a variable is to be attached to the vertices of geometric primitive, it should be declared as a varying variable in the shader argument list.

Variables declared locally in the body of a shader, as arguments to a function, or as local variables are assumed to be varying. Declaring a variable to be uniform inside a shader or function definition is never necessary, but may allow the compiler to generate more efficient code.

If a uniform value (or a constant) is assigned to a varying variable or is used in a varying expression, it will be promoted to varying by duplication. It is an error to assign a varying value to a uniform variable or to use a varying value in a uniform expression.

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.