Language Binding Summary

C Binding 
Bytestream Protocol
Additional Information

In this document, the RenderMan Interface is described in the ANSI C language. Other language bindings will be proposed in the future.

2.1 C Binding

All types, procedures, tokens, predefined variables and utility procedures mentioned in this document are required to be present in all C implementations that conform to this specification. The C header file which declares all of these required names, ri.h, is listed in Appendix C, Language Binding Details.

The RenderMan Interface requires the following types:

typedef short		RtBoolean;
typedef int		RtInt;
typedef float		RtFloat;
typedef char	  	*RtToken;
typedef RtFloat		RtColor[3];
typedef RtFloat		RtPoint[3];
typedef RtFloat		RtVector[3];
typedef RtFloat		RtNormal[3];
typedef RtFloat		RtHpoint[4];
typedef RtFloat		RtMatrix[4][4];
typedef RtFloat		RtBasis[4][4];
typedef RtFloat		RtBound[6];
typedef char		*RtString;
typedef void		*RtPointer;
typedef void 		RtVoid;
typedef RtFloat		(RtFilterFunc)(RtFloat, RtFloat, RtFloat, RtFloat);
typedef RtFloat		(RtErrorHandler)(RtInt, RtInt, char *);
typedef RtFloat		(RtProcSubdivFunc)(RtPointer, RtFloat);
typedef RtFloat		(RtProcFreeFunc)(RtPointer);
typedef RtFloat		(RtArchiveCallback)(RtToken, char *, ...);
typedef RtPointer	RtObjectHandle;
typedef RtPointer	RtLightHandle;
typedef RtPointer	RtContextHandle;

All procedures and values defined in the interface are prefixed with Ri (for RenderMan Interface). All types are prefixed with Rt (for RenderMan type). Boolean values are either RI_FALSE or RI_TRUE. Special floating point values RI_INFINITY and RI_EPSILON are defined. The expression -RI_INFINITY has the obvious meaning. The number of components in a color is initially three, but can be changed (See the section Additional options, p. 33). A bound is a bounding box and is specified by 6 floating point values in the order xmin, xmax, ymin, ymax, zmin, zmax. A matrix is an array of 16 numbers describing a 4 by 4 transformation matrix. All multidimensional arrays are specified in row-major order. For example, a 4 by 4 translation matrix to the location (2,3,4) is specified with

{{ 1.0, 0.0, 0.0, 0.0},
 { 0.0, 1.0, 0.0, 0.0},
 { 0.0, 0.0, 1.0, 0.0},
 { 2.0, 3.0, 4.0, 1.0} }

Tokens are strings that have a special meaning to procedures implementing the interface. These meanings are described with each procedure. The capabilities of the RenderMan Interface can be extended by defining new tokens and passing them to various procedures. The most important of these are the tokens identifying variables defined by procedures called shaders, written in the Shading Language. Variables passed through the RenderMan Interface are bound by name to shader variables. To make the standard pre-declared tokens and user-defined tokens similar, RenderMan Interface tokens are represented by strings. Associated with each of the standard predefined tokens, however, is a predefined string constant that the RenderMan Interface procedures can use for efficient parsing. The names of these string constants are derived from the token names used in this document by pre-pending an RI_ to a capitalized version of the string. For example, the predefined constant token for "rgb" is RI_RGB. The special predefined token RI_NULL is used to specify a null token.

In the C binding presented in this document, parameters are passed by value or by reference. C implementations of the RenderMan Interface are expected to make copies of any parameters whose values are to be retained across procedure invocations.

Many procedures in the RenderMan Interface have variable length parameter lists. These are indicated by the syntactical construct parameterlist in the procedure's argument list. In the C binding described, a  parameterlist is a sequence of pairs of arguments, the first being an RtToken and the second being an RtPointer, an untyped pointer to an array of either RtFloat, RtString or other values. The list is terminated by the special token RI_NULL.

In addition, each such procedure has an alternate vector interface, which passes the parameterlist as three arguments: an RtInt indicating the length of the parameter list; an array of that length that contains the RtTokens; and another array of the same length that contains the RtPointers. This alternate procedure is denoted by appending an uppercase V to the procedure name.

For example the procedure RiFoo declared as

     RiFoo( parameterlist )

could be called in the following ways:

RtColor colors;
RtPoint points;
RtFloat one_float;
RtToken tokens[3];
RtPointer values[3];
RiFoo( RI_NULL );
RiFoo((RtToken)"P", (RtPointer)points, (RtToken)"Cs", (RtPointer)colors,
            (RtToken)"Kd", (RtPointer)&one_float,  RI_NULL );
RiFoo(RI_P,  (RtPointer)points, RI_CS, (RtPointer)colors,
            RI_KD, (RtPointer)&one_float,  RI_NULL );
tokens[0] = RI_P;  values[0] = (RtPointer)points;
tokens[1] = RI_CS; values[1] = (RtPointer)colors;
tokens[2] = RI_KD; values[2] = (RtPointer)&one_float;
RiFooV( 3, tokens, values);

It is not the intent of this document to propose that other language bindings use an identical mechanism for passing parameter lists. For example, a Fortran or Pascal binding might pass parameters using four arguments: an integer indicating the length of the parameter list, an array of that length that contains the tokens, an array of the same length containing integer indices into the final array containing the real values. A Common Lisp binding would be particularly simple because it has intrinsic support for variable length argument lists.

The ANSI Standard C binding of RenderMan Interface is different from the K&R C binding presented in the document only in the normally expected ways. The semantics of the types, procedures and predefined variables are identical, and the necessary function prototype modifications are presented in a version of ri.h also listed in Appendix C, Language Binding Details.

There may be more than one rendering context. This would allow a program to, for example, output to multiple RIB files. RenderMan Interface procedure calls apply to the currently active context. At any one time, there is at most one globally active rendering context. The RenderMan Interface is not intended to be reentrant. In other words, the active context is truly global to a program process, and there cannot be multiple simultaneous threads in one process, each with a different active context. Following is an example of writing to multiple contexts, in which a sphere is written to one RIB file and a cylinder is written to a different RIB file (the semantics of the context switching routines are presented in Section 4).

RtContextHandle ctx1, ctx2;
RiBegin ("file1.rib");
ctx1 = RiGetContext ( );
RiBegin ("file2.rib");
ctx2 = RiGetContext ( );
...
RiContext (ctx1);
RiSphere (1, -1, 1, 360, RI NULL);
RiContext (ctx2);
RiCylinder (1, -1, 1, 360, RI NULL);
RiEnd ( ); /* Ends context 2 */
RiContext (ctx1);
...

There is no RIB equivalent for context switching. Additionally, other language bindings may have no need for these routines, or may provide an obvious mechanism in the language for this facility (such as class instances and methods in C++).

2.2 Bytestream Protocol

This document also describes a byte stream representation of the RenderMan Interface, known as the RenderMan Interface Bytestream, or RIB. This byte stream serves as both a network transport protocol for modeling system clients to communicate requests to a remote rendering service, and an archive file format to save requests for later submission to a renderer.

The RIB protocol provides both an ASCII and binary encoding of each request, in order to satisfy needs for both an understandable (potentially) interactive interface to a rendering server and a compact encoded format which minimizes transmission time and file storage costs. Some requests have multiple versions, for efficiency or to denote special cases of the request.

The semantics of each RIB request are identical to the corresponding C entry point, except as specifically noted in the text. In Part I of this document, each RIB request is presented in its ASCII encoding, using the following format:

RIB BINDING

     Request parameter1 parameter2... parameterN

     Explanation of the special semantics of the RIB protocol for this request. 

At the top of the description, parameter1 through parameterN are the parameters that the request requires. The notation `-' in the parameter position indicates that the request expects no parameters. Normally the parameter names suggest their purpose, e.g., x, y, or angle.

In RIB, square brackets ([ and ]) delimit arrays. Integers will be automatically promoted if supplied for parameters which require floating point values. A parameter list is simply a sequence of string-array pairs. There is no explicit termination symbol as in the C binding. Example parameter lists are:

     "P" [0 1 2 3 4 5 6 7 8 9 10 11]
     "distance" [.5] "roughness" [1.2]

The details of the lexical syntax of both the ASCII and binary encodings of the RIB protocol are presented in Appendix C, Language Binding Details.

2.3 Additional Information

Finally, the description of each RenderMan Interface request provides an example and cross-reference in the following format:

  EXAMPLE

     Request 7 22.9

  SEE ALSO

     RiOtherRequest 

Some examples are presented in C, others in RIB, and a few are presented in both bindings (for comparison). It should be obvious from the syntax which binding is which.

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.