Pixar
March, 1997
This document describes how to use the 3.7 release of Vector RenderMan. Vector RenderMan is a wireframe renderer that accepts 3D scene descriptions created through the RenderMan Interface. It is intended to be used as a previewing tool to facilitate the creation of RenderMan scene descriptions that will subsequently be rendered with PhotoRealistic RenderMan.
Vector RenderMan is a rendering system that generates 2D wireframe images from 3D scene-description information created through the RenderMan® interface. The intent of Vector RenderMan is that it be used as a previewer for PhotoRealistic RenderMan. Since Vector RenderMan only generates wireframe images, it is considerably faster than a photorealistic renderer. Yet it complies to the geometric, camera-specification, and selected other portions of the RenderMan Interface. This, combined with its speed, makes it a useful tool for debugging and preparing RenderMan scene descriptions.
Since Vector RenderMan will normally be used in conjuction with PhotoRealistic RenderMan, this document will not attempt to describe in detail the RenderMan Interface, but rather will concentrate on its similarities and dissimilarities with PhotoRealistic RenderMan. The reader is referred to the documentation provided with PhotoRealistic RenderMan for a full discussion of the RenderMan Interface.
The user of Vector RenderMan creates a RIB stream using the RIB client library in the identical manner used for PhotoRealistic RenderMan. The same RIB stream may be sent to Vector RenderMan as may be sent to PhotoRealistic RenderMan. Vector RenderMan accepts both the binary-encoded or the ASCII versions of RIB.
The executable Vector RenderMan renderer that takes a RIB file as input is called vectrman. Though it is possible to use vectrman directly, we strongly recommend using the command script render with the -vector flag, which handles all of the niceties of streams and file concatenation required by your operating system before it invokes vectrman. This is the same command script that is used with PhotoRealistic RenderMan. To have it always invoke vectrman instead of prman, one can set the environment RIRENDER. (See section 3.1).
With one exception, Vector RenderMan uses the same display mechanisms as PhotoRealistic RenderMan. (The one exception is when it is generating PostScript® output. See section 3 for more about that.) Therefore, one may use the same display drivers, including file output, with Vector RenderMan as with PhotoRealistic RenderMan whether they were supplied with PhotoRealistic RenderMan or written by a user.
Vector RenderMan is not capable of generating a zfile which is used to generate a shadow map. One must use PhotoRealistic RenderMan for this purpose.
It is not possible for a wireframe renderer to meet the requirements of a RenderMan-compatible renderer as defined in the RenderMan Interface Specification. Therefore, Vector RenderMan, being a wireframe renderer, does not comply with the RenderMan Interface. It does, however, implement a subset of the interface as defined in the RenderMan Interface Version 3.1. This section details the capabilities and limitations of Vector RenderMan, first in terms of the required features described in the RenderMan Interface Version 3.1 specification and then in terms of optional capabilities.
Required features are those features specified in the document that must be present in a renderer to be able to qualify it as having implemented the RenderMan Interface. The following features correspond to those discussed in Section 1 of the RenderMan Interface Version 3.1 specification.
Optional capabilities are those features specified in the document that are not required to be supported in all implementations of compatible renderers. The subroutines which would normally implement the interface to these capabilities must exist, but need not do anything. The level of support of an optional capability by a specific renderer implementation can be divided into three categories: fully implemented, in which the renderer supplies the features in all of their generality; incompletely implemented, in which the renderer supports a subset of the feature, but has certain restrictions on the parameter values which can be handled correctly; and unimplemented, in which the renderer has no support for the feature. The RenderMan Interface Version 3.1 document specifies what the default action of a renderer should be if unimplemented capabilities are requested.
The following capabilities correspond to those discussed in Section 1 of the RenderMan Interface Version 3.1 specification.
As with PhotoRealistic RenderMan images, Vector RenderMan images begin with a properly configured RIB file. The PhotoRealistic RenderMan User's Manual provides a description of the preparation of RIB files.
Vector RenderMan is usually used through the render shell script using the -vector flag. The render command provides a simple front-end to both the PhotoRealistic RenderMan and the Vector RenderMan systems.
To render a model file containing RIB data, simply use
% render -vector model.rib
To permanently select the Vector RenderMan renderer, the RIRENDER can be set to (See the render(1) reference page, and Section 3.7 of the PhotoRealistic RenderMan User's Manual).
It is possible to have Vector RenderMan generate a PostScript file. This file can then be sent to a PostScript device, such as a LaserWriter®, to produce a hardcopy of the image. Vector RenderMan normally uses the same display services and display drivers as PhotoRealistic RenderMan. This means that Vector RenderMan must convert its vector output to raster data before it sends it to the display. This is not the case, however, when the postscript driver is specified in a call to RiDisplay. The PostScript driver is built into Vector RenderMan and produces a PostScript file that contains vector information instead of raster data. This allows the PostScript device that ultimately displays the image to produce its best quality lines.
By default, Vector RenderMan generates colored lines as specified in the graphics state. If no color has been specified, the default is white. Therefore, the default is white lines on a white page. To avoid this, one should either make sure non-white colors have been specified or the fullcolor option is turned off (see Section 4.1.2). Most PostScript display devices are unable to display pixels near the edges of the page, therefore the origin option to RiDisplay should be used. The following is an example of how to specify PostScript output. It will generate the PostScript file foo.ps that specifies black lines on a white background with the origin one-half inch in from the corner of the paper.
RtInt colored = 0;
RtInt o[2] = {36, 36};
RiOption( "display", "fullcolor",
(RtPointer)&colored, RI_NULL );
RiDisplay( "foo.ps", "postscript", "rgba",
"origin", (RtPointer)o, RI_NULL);
Every implementation of a rendering program has certain implementation-specific features which are accessed through the functions RiAttribute and RiOption. Table 1 summarizes the options available in Vector RenderMan.
Table 1. Implementation-specific Options and Attributes
| RIB | Defaults |
|---|---|
| Option "display" "refresh" [n] Option "display" "fullcolor" [n] | [0] [1] |
| Display name,type,mode "merge" [n] Display name,type,mode "origin" [a b] | [0] [0 0] |
| Attribute "divisions" "udivisions"
[n] Attribute "divisions" "vdivisions" [n] | [10] [10] |
These defaults can be altered by appropriate settings in the configuration file, rendermn.ini, which is shared by vectrman and prman. (See the PhotoRealistic RenderMan User's Manual and the rendermn.ini(5) reference page). In particular, the configuration file entries /vectrman/refresh, /vectrman/fullcolor, /vectrman/udivisions, and /vectrman/vdivisions are specific to Vector RenderMan.
The following sections describe the attributes and options available to control the operation of Vector RenderMan. Each section gives an example of the use of the option as it would appear in RenderMan Interface.
Options are parameters that affect the rendering of an entire image. They must be set before calling RiWorldBegin, since at that point options for a specific frame are frozen.
Vector RenderMan produces vectors immediately when a piece of geometry is defined. It is capable of buffering these vectors until some later time before calling the display services to actually display them. This option controls the number of vectors buffered before they are displayed. Be aware that a single piece of geometry will, in most cases, produce many vectors. The default, zero, implies that no vectors are displayed until RiWorldEnd is called. Calling the display services incurs a substantial performance expense. Therefore, the default should be used unless it is imperative to watch the order in which vectors are drawn.
RtInt refreshrate = 100; RiOption( "display", "refresh", (RtPointer)&refreshrate, RI_NULL );
This option controls whether or not Vector RenderMan produces colored vectors or a black and white image. The default, one, causes vectors to be displayed in the color specified in the current graphics state. If fullcolor is set to zero, Vector RenderMan will produce white lines on a black background (if PostScript output has been specified, this will produce black lines on a white background). RtInt colored = 0; RiOption( "display", "fullcolor", (RtPointer)&colored, RI_NULL );
There are two options which can be enabled through the parameter list of the display command. These options, naturally enough, influence the use of the display device.
The origin of the output window on a frame buffer device can be set using the display origin option. For example, to place the origin of the output window at the point (512,384):
RtInt o[2] = { 512, 384 };
RiDisplay( "", "framebuffer", "rgba",
"origin", (RtPointer)o, RI_NULL );
Frame buffers can be configured to merge the generated image over an existing image with the display merge option:
RtInt flag = 1; RiDisplay( "", "framebuffer", "rgba", "merge", (RtPointer)&flag, RI_NULL );
The merge option works only if the selected display driver supports it.
Attributes are flags and values that are part of the graphics state, and are therefore associated with individual primitives. The values of these attributes are pushed and popped with the graphics state.
All surfaces except for polygons are displayed as a grid of lines on the surface. This attribute controls the number of lines that are drawn in each of the surface's parametric directions. The value specified is the number of pieces into which the surface is divided.
RtInt udiv = 5, vdiv = 7; RiAttribute( "divisions", "udivisions", (RtPointer)&udiv, "vdivisions", (RtPointer)&vdiv, RI_NULL );