RenderMan Artist Tools

PhotoRealistic RenderMan
Application Note #1

A Brief Introduction to the RenderMan Interface

May, 1990

This application note provides a quick introduction to the RenderMan Interface. It is intended primarily for readers who are already familiar with computer graphics and rendering. For a more thorough introduction, please consult The RenderMan Companion [1], by Steve Upstill.

The RenderMan interface is designed to be a standard interface between modeling programs and high-quality rendering programs. As such, it has provisions for the specification of 3-D scene descriptions that include: hidden surfaces, spatial filtering, dithering, motion blur, depth of field, flat and curved surfaces, objects, constructive solid geometry, and programmable shading to express lighting conditions, shadows, and surface appearances, with sophisticated control over color, texture, and reflectivity. The design of the interface emphasizes the ability to convey, compactly and efficiently, the information required to produce rendered images that resemble actual photographs.

What follows is a very general overview of the RenderMan Interface that introduces the interface routines and terminology. It concludes with a brief description of how certain concepts that are common to 3-D graphics are handled in the interface.


The RenderMan Interface was proposed by Pixar in May, 1988, as a standard interface between modelers and high-quality renderers. To date, it is the only proposed rendering interface standard that includes provisions for all the features in a scene description required to synthesize photorealistic images.

At the time of its introduction, the RenderMan Interface was defined in terms of a C language binding, a set of 96 C procedures that provides a complete rendering interface. Since then, a bytestream protocol has also been defined and incorporated into the interface specification. This protocol is known as the RenderMan Interface Bytestream (RIB), and it not only allows a scene description to be stored as an ASCII or binary coded file but also provides a means for transport over a network.

For the sake of simplicity, the interface will be presented here in its C language form. The conversion to RIB is quite straightforward, and a full description of it can be found in The RenderMan Interface, Version 3.1 [2].


The RenderMan Interface describes a scene as a sequence of geometric primitives. This sequence specifies all the objects in a scene in terms of the variety of flat and curved surfaces that RenderMan supports. To control the positioning and shading of these objects, the RenderMan Interface maintains a graphics state, which is primarily just a current setting for each of a large number of parameters associated with the rendering of an object in a scene.

The graphics state consists of options, attributes, and the interface mode. Options are the rendering parameters that affect how an entire scene will be rendered, while attributes are the parameters that can differ from object to object in a scene. The interface mode constrains and controls the context of allowed RenderMan procedure calls, and it also maintains the graphics state stack. This stack allows various parts of the graphics state to be saved and reinstated at will.

To control the graphics state, there are procedures in the interface that change the current mode, options, and attributes. These routines are classified here as mode-changing procedures, option-changing procedures, and attribute-changing procedures. The interface also includes a set of geometric primitive procedures that describe the actual geometry in a scene.

The interface starts up with default option and attribute values, which are defined in the interface specification. Calling a RenderMan option- or attribute-changing procedure sets the values of certain related options or attributes in the graphics state.

A scene is begun by calling the mode-changing routine RiWorldBegin(), and its options are set from the option values in the current graphics state. These values then become frozen, and it is forbidden to use any option-changing procedures until the scene's description is finished.

In the scene, attributes are still free to change. Each piece of the scene's geometry is described by calling a RenderMan geometric primitive procedure; a given primitive gets its attributes from the current graphics state at the time it is passed through the interface.


There are now 95 basic RenderMan routines, and they all have names of the form RiSomething(). They can be classified quite cleanly into the following categories:

  1. Geometric Primitive Procedures
  2. Mode-Changing Procedures
  3. Option-Changing Procedures
  4. Attribute-Changing Procedures
  5. Texture and Bookkeeping Procedures

There are 17 procedures in the RenderMan interface to place geometric primitives in a scene. They support polygons, bilinear and bicubic patches, non-uniform rational B-spline patches, quadric surfaces, and retained objects.

There are 16 procedures for changing modes, which sort out into eight begin-end pairs. Three of the pairs are for basic renderer and scene control, and three others control special modes of the interface for retained object, CSG, and motion blur specification. Though most of these six pairs also affect the attribute stack, the remaining two exist solely for additional stack control. The Procedures List on the next page lists the names of these procedures, separated by category, along with a brief description of each one. (Consult The RenderMan Companion for full descriptions with arguments.)

There are 19 procedures for changing options. Each one sets a closely related set of option parameters in the graphics state, and the majority of them control either the effects that arise from the camera model or the display processing that occurs in the renderer.

There are 34 procedures for changing attributes, and each one alters a related set of attribute parameters in the graphics state. As attribute parameters pertain to operations that occur on each primitive, they tend to affect either a primitive's geometry and positioning in space or its lighting, shading and the opacity of its surfaces. Included as a geometric attribute is the current transformation, which defines the current coordinate system for all point values. Because of the special importance of this attribute, there are 8 procedures to manipulate the current transformation matrix, one to concatenate nonlinear transformations into the current transformation, and one to attach a name to a coordinate system.

Finally, there are 9 miscellaneous routines to produce texture map files from image files and perform various bookkeeping tasks.


Among the option- and attribute-changing procedures, you may notice that several are used to specify shaders. One of the most powerful features of the RenderMan Interface is its ability to apply user-defined shaders in the rendering process. Traditionally, a shader describes the intensity of light that a given point on a surface will reflect toward the camera. However, in RenderMan, the notion of a shader is much more general.

Included with the RenderMan Interface is a specification of the RenderMan Shading Language. This language has a syntax similar to C's, and it enables the user to control several key operations in the rendering process. Aside from surface shaders, which do things traditionally associated with "shading," there are seven other classes of shaders. Here is a list of the eight shader classes, along with a brief description of the rendering computation described by each one:

surfaceThe way a surface reflects and transmits light.
lightLight emitted by a light source.
atmosphereAttenuation of camera-bound light through space.
volumeAttenuation of light through a volume in space.
imagerRe-mapping of image color values before display.
displacementGeometric displacement of points on a surface.
deformationGeometric transformation of a surface.
projectionGeometric mapping from camera to screen space.

RenderMan starts up with a well-defined default shader for each of these classes, and the interface also provides a set of standard shaders that are suitable for many purposes. For beginners, the most important shader classes to consider are surface and light.


From the point of view of RenderMan Interface procedure calls, a shader is just the name of a compiled shading language file that exists in a known place. However, shaders also have parameters that can be set through the interface when the shader is brought into the graphics state. To handle this capability, certain RenderMan procedures take a list of arguments known as a parameterlist. Each parameter has a default value that is given in the shader, so it only needs to be in the parameterlist if it is to have a value other than its default. The parameterlist always begins after the last procedure-specific argument, and it consists of an optional paired list of arguments followed by the terminating token argument RI_NULL.

The paired arguments in the parameterlist each contain a token followed by a pointer to an array of values. The token is just the string for the name of the parameter, and the values in the array are the values that get assigned to the parameter. Since there are both point and color type variables defined in the Shading Language, it is possible for a parameter to have more than one floating-point value associated with it. For this reason, the rendering interface must know the type of every parameter appearing in the parameterlist. The names and types of parameters that appear in the standard shaders are already known to the interface. However, nonstandard parameters must be declared with the RiDeclare() procedure before they can be used in a parameterlist. Altering a shader's parameters affects the shader's presence in the graphics state, but it does not affect the shader itself. Therefore, every invocation of a given shader starts with the default parameter values and alters them according to the parameterlist in the call.


The 10 routines that invoke shaders are not the only RenderMan procedures that use parameterlists. RenderMan geometric primitive routines use them to define a variety of surface parameters in addition to position and shape, and RenderMan texture routines use them to specify optional texture parameters. There are also a few other routines that are designed to take extended sets of parameters using parameterlists. In total, 32 of the procedures that we have seen so far use parameterlists.


Since the length of a parameterlist is not always known at compile-time, RenderMan also provides a varargs form for each procedure that uses a parameterlist. These routines have names of the form RiSomethingV(), and each does the same thing as its RiSomething() counterpart, taking a fixed number of pointers to variable-length argument arrays instead of a variable-length parameterlist.


Before leaving this introduction, it is worth noting how the RenderMan 3-D graphics environment works. In particular, it is important to know how RenderMan handles coordinate systems, transformations, camera positioning, and light sources. Mentioned here are the primary graphics conventions in RenderMan that are likely to differ from other 3-D environments. Consult The RenderMan Companion for more details.


The natural RenderMan coordinate system is a left-handed one in which the x axis points to the right, the y axis points up, and the z axis points into the screen. For any geometric primitive in a scene, RenderMan keeps track of several coordinate systems, including "object", "shader", "world", "camera", "screen", and "raster" spaces. In addition, any coordinate system can be named with the RiCoordinateSystem() procedure. The interface starts up in camera space.


Before RiWorldBegin() has been called, transformations are used to position the camera by defining world space (see below). After RiWorldBegin(), they set up the coordinate systems into which objects and shaders are placed. Shaders have coordinate systems associated with them in the same way that objects do. By interspersing RenderMan transformation and stack routines between geometric primitive routines, it is possible to control how object space is defined for each object in the scene. The same is true for shader space, based upon where the call that invokes each attribute shader is made.

RenderMan applies given transformations onto objects in reverse sequence. This means that the last transformation concatenated onto the current transformation before an object is defined is the first one that will be applied to the object.


In RenderMan, the camera is not specified as a separate object. Instead, transformation routines are called before RiWorldBegin() to define the mapping from world space to camera space. This process is conceptually the same as having a camera that is fixed at the origin, looking down the z axis, and transforming the world, as though it were an object, until it is in proper view.


RenderMan places point light sources into the scene as shaders. The positioning of a light source is set through parameters to the light shader associated with the light, and each light is included in the scene with a call to RiLightSource(). Since any point values passed to a light shader are interpreted as being in the current coordinate system, it is also possible to use transformations to control light source positioning.


Now that you are familiar with the RenderMan Interface, you can either go on and read The RenderMan Companion, or refer to The RenderMan Interface, Version 3.1, for more information. If you own Developer's RenderMan, you will find that the documentation contains a tutorial, with on-line examples, that is designed to accompany The RenderMan Companion. These are all excellent ways to learn more about RenderMan.

However, if you prefer to learn through hands-on experience, you may wish to consult the other RenderMan application notes. These notes provide good tips and example programs, and they are especially useful if you are using PhotoRealistic RenderMan, as they cover many implementation-specific considerations that are not covered elsewhere.


[1] Upstill, Steve, "The RenderMan Companion: A Programmer's Guide to Realistic Computer Graphics," Addison-Wesley, 1990.

[2] The RenderMan Interface Specification, V3.1, September 1989, Pixar.

RenderMan Interface Procedures

Geometric Primitive Procedures

RiPolygon() Simple, convex, planar polygon
RiGeneralPolygon() General planar polygon, holes optional
RiPointsPolygons() Many simple polygons from given points
RiPointsGeneralPolygons() Many general polygons from given point
RiPatch()Bilinear or bicubic patch
RiPatchMesh()Mesh of bilinear or bicubic patches
RiNuPatch() Non-uniform rational B-spline patch
RiSphere() Complete or partial sphere
RiCone()Complete or partial conic surface
RiCylinder()Complete or partial cylindrical surface
RiHyperboloid()Complete or partial hyperbolic surface
RiParaboloid()Complete or partial parabolic surface
RiDisk()Complete or partial disk
RiTorus()Complete or partial torus


RiProcedural()Procedural geometry specification
RiGeometry()Any other primitives not covered above
RiObjectInstance()Retained geometric object

Mode-Changing Procedures


RiBegin()Start the interface
RiEnd()End the interface and clean up
RiFrameBegin()Begin a new frame and save options
RiFrameEnd() End the frame and restore options
RiWorldBegin()Start the scene and freeze options
RiWorldEnd()End the scene and unlock options
RiObjectBegin()Start retained object description
RiObjectEnd()End retained object description
RiSolidBegin()Start CSG solid description
RiSolidEnd()End CSG solid description
RiMotionBegin() Start motion description
RiMotionEnd()End motion description
RiAttributeBegin()Push all attributes onto stack
RiAttributeEnd() Pop all attributes from stack
RiTransformBegin()Push current transformation onto stack
RiTransformEnd()Pop current transformation from stack

Option-Changing Procedures

RiFormat()Pixel resolution of full output image
RiFrameAspectRatio()Resolution constrained to aspect ratio
RiScreenWindow()Screen-to-raster-space mapping
RiCropWindow()Portion of the full image to render
RiProjection()Camera-to-screen-space mapping shader
RiClipping()Distance to near and far clipping planes
RiDepthOfField() Parameters to simulate depth of field
RiShutter() Motion blur shutter open and close times
RiPixelVariance()Tolerance for adaptive sampling
RiPixelSamples()Effective pixel sampling rate
RiPixelFilter() Type of filter to use on samples
RiExposure()Scene-to-image exposure parameters
RiImager() Image-to-image re-mapping shader
RiQuantize()Image float-to-int mapping parameters
RiDisplay() Image filename and display parameters
RiHider()Type of hider and its parameters
RiColorSamples()Number of components in a color value
RiRelativeDetail() Relative detail level of entire scene
RiOption() Any other parameters not covered above

Attribute-Changing Procedures

RiColor()Surface color
RiOpacity()Surface opacity
RiTextureCoordinates()Surface extent in texture space
RiLightSource()Light source positions and shaders
RiAreaLightSource()Area light source extents and shaders
RiIlluminate()Active light sources
RiSurface()Surface visible intensity shader
RiAtmosphere()Atmospheric attenuation shader
RiInterior()Interior volumetric attenuation shader
RiExterior()Exterior volumetric attenuation shader
RiShadingRate()Raster area per shading computation
RiShadingInterpolation()Type of interpolation on shading values
RiMatte()Flag to render objects as matte holes
RiBound()Bounding box for geometric primitives
RiDetail()Level of detail at which to render
RiDetailRange()Range of detail assigned to geometry
RiGeometricApproximation()Tolerance of geometric approximations
RiBasis()Basis matrix for bicubic patches
RiTrimCurve()Trim curves for NURBS patches
RiOrientation()Handedness of geometric primitives
RiReverseOrientation()Handedness of geometric primitives
RiSides()Number of sides to geometric primitives
RiIdentity()Current transformation matrix
RiTransform()Current transformation matrix
RiConcatTransform()Current transformation matrix
RiPerspective()Current transformation matrix
RiTranslate()Current transformation matrix
RiRotate()Current transformation matrix
RiScale()Current transformation matrix
RiSkew()Current transformation matrix
RiDeformation()Current nonlinear transformation shaders
RiDisplacement()Surface displacement shader
RiCoordinateSystem()Name of current coordinate system
RiCoordSysTransform()Current transformation matrix
RiAttribute()Any other parameters not covered above

Other Procedures

RiMakeBump()Make bump map from image file
RiMakeCubeFaceEnvironment()Make environment map from 6 images
RiMakeLatLongEnvironment()Make environment map from one image
RiMakeShadow()Make shadow map from z file
RiMakeTexture()Make texture map from image file
RiErrorHandler()Set error handler
RiDeclare()Declare a non-standard shader parameter
RiTransformPoints()Transform points from space to space
RiArchiveRecord()Send archival comments to RIB stream

Pixar Animation Studios
(510) 752-3000 (voice)   (510) 752-3151 (fax)
Copyright © 1996- Pixar. All rights reserved.
RenderMan® is a registered trademark of Pixar.