PhotoRealistic RenderMan 3.6g
Release Notes

Pixar
December, 1996

1. Introduction

RenderMan Toolkit
Looks | 3.6. The significant changes and enhancements from the previous release of the RenderMan Toolkit are also described, as are the known problems and limitations in terms of the rendering feature set described in the RenderMan Interface Specification Version 3.1.

2. Major Changes Since Release 3.5

Many new features and other significant changes have been made to the RenderMan Toolkit since the previous release. This section describes the major enhancements which have been made to the renderers, libraries and associated tools in the Toolkit.

2.1. PhotoRealistic RenderMan 3.6 Major Changes

The major items that have changed since the 3.5 release of the PhotoRealistic RenderMan rendering software itself are detailed in this section.

Compressed Textures

The PhotoRealistic RenderMan 3.6 texture subsystem now supports compressed textures. The txmake program as well as RiMakeTexture, RiMakeShadow, RiMakeCubeFaceEnvironment and RiMakeLatLongEnvironment all now create texture files in which the texture data has been compressed. Compression may be turned off if desired. The amount of compression varies greatly with image content, but the file size savings are often very large. The performance penalty is relatively minor.

 

High Quality Texture Filtering

The texture runtime system has been modified to provide optional higher quality texture filtering. This includes using a higher quality filter, gaussian versus box, as well as interpolation between the resolutions of a multi-resolution texture file for smooth transitions between resolutions. The higher quality options can be selected in the Shading Language and disabled via an RiOption.

 

Shadow Bias Improvements

Improvements have been made to the shadow map sampling to allow much smaller shadow biases to be used without self shadowing. This provides a better chance of setting a bias which avoids self-shadowing and shadow separation.

The shadow bias is also now settable through the shadow() call in the Shading Language.

 

Support for Large Numbers of Textures

The texture system has been modified to allow large numbers of texture files to be in use at once. In previous versions, if the scene required more than thirty-two texture files, there was a possibility that the run-time system might close still active texture files in order to open new ones. This could result in thrashing. The only limit on the number of simultaneous textures is now system memory.

 

Support for Floating Point Textures and Images

Texture files may now be created from TIFF files containing floating point data with the txmake program as well as RiMakeTexture, RiMakeCubeFaceEnvironment and RiMakeLatLongEnvironment.

 

Unapproximated Spheres

Previously the RiSphere primitive was implemented using a set of bicubic patches to approximate a sphere very closely. Spheres are now fully implemented as a core geometric primitive. This results in lower overhead for very small spheres and higher geometric accuracy for very large spheres over the previous implementation of spheres.

 

Vertex Parameters

The parameter lists of geometric primitives can now contain extra parameters of class vertex. Previously only the geometric position P was allowed to be of class vertex and other parameters could only be of the classes varying or uniform. The values of extra vertex parameters are now available to the Shading Language to the same accuracy as P. An example use of this is to base a shader on the value of P at some standard point in time even though the current value of P is animated over time.

 

Vector and Normal Parameters

User parameters can now be declared to be of type vector, normal and hpoint. The values provided for such parameters on any RI shader and primitive calls will be transformed differently from parameters declared point as appropriate to the type. vector and normal types are now also available in the Shading Language, however the RiDeclare declaration determines the transformation used, not the Shading Language source code declarations.

 

RiNuPatch Uniform and Varying Parameters

The number of uniform and varying parameters for an RiNuPatch has been redefined. Formerly an RiNuPatch was defined to have just one uniform value and four varying values, one at each corner of the RiNuPatch. Now an RiNuPatch is defined to have a number of segments in each parameter direction with one uniform value per segment and one varying value per segment corner. This is analogous to RiPatchMatch with one uniform value per patch and one varying value per patch corner. An RiNuPatch is now defined to have (1+nu-uorder) segments in the u direction and (1+nv-vorder) segments in the v direction. (The number of segment corners is of course one more than that in each direction.) This corresponds to the RiPatchMatch model in the case where the RiNuPatch is a uniform b-spline. This results in redundant parameter values corresponding to repeated knot values, for instance when the knot vector indicates the RiNuPatch is in Bezier form, however the benefit of the flexibility far outweighs any burden due to the redundancy.

 

New call RiCoordSysTransform

The new call RiCoordSysTransform sets the current transformation matrix to that of the specified coordinate system. An example use of this would be to set the transform to "camera" in order to place geometry directly in front of the camera.

 

New RiReadArchive call.

The new RiReadArchive call causes the named RIB file to be opened and parsed by the renderer. The current RIB stream continues with the next directive after parsing the external file. It is entirely the responsibility of the user to insure that all Begin/End blocks are balanced properly.

 

New Features in the TIFF Usage

The tiff output driver can now write floating point color channels into the image files. The tiff output driver now supports a number of new image compression schemes. The tiff output driver can place optional string tags into the output TIFF file. The renderer now records the software and date of creation in TIFF string tags inside the TIFF output file.

 

Support for Alias Image Files

A new output driver, alias, has been added to write the output image in Alias image file format. The txmake program as well as RiMakeTexture, RiMakeCubeFaceEnvironment and RiMakeLatLongEnvironment calls can now create textures from images in Alias image file format.

 

Pixar Look Instance Support

The liblkm.a library introduced in release 3.5 has been expanded to support Look instances. The renderer is capable of reading the texture maps stored in the instance file in combination with the shader contained in the look master file referenced by the instance.

The libsloargs.a library can now reference the shaders embedded in Pixar Look masters or instances. Either the path of the ".vma" master file, the ".vmi" instance file or the full Look shader name of the master will cause the sloargs library to open the Pixar Look shader. The sloargs library can only access the same information from a Pixar Look shader that it can access from a regular shader file. To access more information from a Pixar Look, use the liblkm.a library.

 

2.2. Shading Language Major Changes

New features added to the Shading Language compiler and Shading Language runtime system are listed in this section.

New Noise Functionality

The Shading Language noise() function can now accept a four dimensional domain in addition to the previous one, two and three dimensional functionality.

A new Shading Language cellnoise() has been added to provide a random value associated with a particular region of the input domain. This value is locally constant but not continuous as is the standard noise() function.

 

texture(), shadow() and environment() Calls Allowed in Functions

User defined functions and atmosphere shaders were previously not allowed to use the Shading Language functions texture(), shadow() and environment(). This restriction has been removed. References to these functions in user defined functions and atmosphere shaders must explicitly provide parameters and cannot rely on the runtime system suppling values such as s and t.

 

New texture() and environment() Parameters

The Shading Language texture() and environment() functions now accept the new varying float parameters "blur", "sblur" and "tblur". Setting "blur" is equivalent to setting "sblur" and "tblur" to the same value. These specify an additional area to be added to the texture area filtered in each direction. The values are varying values expressed in units of texture coordinates. Very small values are usually desired here. A value of 1.0 would request that the entire texture file be blurred into the result. A value of 0.001 would request that one extra texture pixel be added in the case of a one-thousand by one-thousand texture file. These new additive blur values are much less prone to problems than the previously used multiplicative values, "swidth" and "twidth" values.

The texture() and environment() functions now accept a new uniform float parameter "fill" which specifies the value to be provided for channels requested which are not present in the texture file. This is most often useful for a shader which knows how to use a texture containing an alpha channel. If no alpha channel is present in the texture file, the texture system quietly provides a default value of 0.0 to requests for the alpha value resulting in a completely tranparent texture. Such a shader could provide its own "fill" value of 1.0 so that textures without an alpha channel would be opaque by default.

The texture() and environment() functions now accept two new parameters "filter" and "lerp". The "filter" parameter is of type uniform string and the possible values are "gaussian" and "box". "gaussian" will perform higher quality texture filtering at some expense in speed. "box" will perform slightly lower quality texture filtering at higher speed. The default is "box". The "lerp" parameter is of type uniform float. A "lerp" value of 1.0 will cause the texture filtering to insure that the transition is smooth between the resolution levels of a multi-resolution texture file. A "lerp" value of 0.0 disables this feature with some savings in rendering time. "lerp" is set to 0.0 by default.

 

Vector and Normal Variables

Shading Language variables can now be declared to be of type vector and normal. Variables of these types behave identically to variables of type point, however, cast operators based on these types transform triples of floating point numbers into vectors using transformations appropriate to the type.

 

New shadow() Parameter

The shadow() function now accepts the new uniform float parameter "bias". Setting "bias" overrides any default shadow bias or shadow bias set in the RIB file for the given shadow() call.

 

2.3. RIB Client Library Major Changes

Significant changes made to the RIB client library are detailed in this section.

New RiReadArchive call.

The new RiReadArchive call is passed into the RIB stream as a reference to an external file containing RIB. The client library will not open or examine the referenced file in any way. Reading and parsing of the file is left up to the renderer.

3. Bug Fixes and Minor Changes Since Release 3.5

Bug fixes and other minor changes have also been made to the RenderMan Toolkit since the previous release. This section describes the minor changes which have been made to the renderers, libraries and associated tools in the Toolkit.

3.1. PhotoRealistic RenderMan 3.6 Bug Fixes and Minor Changes

Bug fixes and other minor changes that have been made to the rendering software are detailed in this section.

Light Handle value errors

Formerly, the renderer incorrectly reported an error for an RiIlluminate call that referenced a light handle whose number whose low six bits were zero. This has been fixed.

 

Incorrect Culling

Formerly, the renderer would sometimes incorrectly cull as backfacing moving geometry that during the course of motion changed from backfacing to frontfacing. This has been corrected.

 

User Parameter Values at Grid Edges

Formerly, there was the possibility of some minor arithmetic differences in the calculation of user parameter values along the edges of adjacent grids. Care has been taken to insure that the calculations of these parameters is the same along grid boundaries so that no discontinuities occur.

 

Trim Curve Problems

Certain special cases of trim curve values could formerly cause the renderer to enter an infinite loop. This problem has been corrected.

 

Dither Pattern

The random dither pattern used in the quantization of pixel values did not properly change from frame to frame. The result was that the dither pattern could be visible over time in animations. The dither pattern is now randomized based on frame number so that each frame in a sequence will get a unique dither pattern. (RiFrameBegin sets the frame number.)

 

Error Reporting Problems

Previously, under certain circumstances the renderer could overflow a buffer during error reporting, causing the renderer to die before reporting the error. This should no longer be the case.

 

X11 24-bit display

The x11 output display driver previously could only use a DirectColor visual for 24-bit color display. It has been modified to be able to use either DirectColor or TrueColor as available.

 

Textures Made from 16-bit TIFF Files

Texture creation from TIFF images using the txmake program as well as RiMakeTexture, RiMakeCubeFaceEnvironment and RiMakeLatLongEnvironment now handles sixteen bit images properly, paying attention to the sample format (signed/unsigned) and properly converting into the texture systems signed format.

 

Depth Filtering

Filtering of depth values was done improperly when the number of samples per pixel was not equal to one. This has been fixed.

3.2. Shading Language Bug Fixes and Minor Changes

Function Local Variable Initializers

Shader function local variable initializers did not work properly. This has been fixed.

 

Output Varying Parameters on Light Shaders

The new output varying shader parameters were very unreliable on light source shaders. The Shading Language function lightsource() often returned garbage values. This has been corrected.

 

mod() of Negative Integers

The Shading Language mod() function previously could return erroneous results when given a negative integer as a parameter. This has been fixed.

3.3. Bug Fixes and Minor Changes New to 3.6g

The following bugs were found in the RenderMan Toolkit 3.6d and 3.6e. These have been fixed in the RenderMan Toolkit 3.6g.

Incorrect "vertex float" variable handling

The 3.6d renderer did not correctly handle variables declared "vertex float". This has been remedied in 3.6g.

 

Incorrect "uniform string" variable handling

The 3.6d renderer did not correctly handle primitive variables declared "uniform string". This has been remedied in 3.6g.

 

Correct handling of "blur", "sblur" and "tblur" texture parameters.

The RenderMan Toolkit 3.6d did not always correctly handle the new "blur" texture parameters. This has been remedied in release 3.6g.

 

Transformation of Shader Parameters of Types "vector" and "normal"

Shader parameters of type "vector" and "normal" were not transformed correctly in the RenderMan Toolkit 3.6d. This has been remedied in release 3.6g.

 

End of Frame Crash

The RenderMan Toolkit 3.6d would sometimes crash after completing a frame. This has been remedied in release 3.6g.

 

Allow Shadow Jitter to be Turned Off.

The RenderMan Toolkit 3.6d always has antialiasing noise in areas that are partially shadowed. This is usually desireable, but in some cases, such as game development, image compression can be more important than subtle anti-aliasing. A new option has been added to 3.6g to remove the shadow jitter noise from the image:
Option "shadow" "jitter" [0]
will turn off jittering of shadow samples.

 

Cellnoise

The cellnoise shading language call has been changed in release 3.6g to insure that:
cellnoise(f) == cellnoise(floor(f))

 

Polygon Accuracy

Complicated polygons that are very small in camera space could cause problems related to floating point accuracy. This has been alleviated in 3.6g.

 

Incorrect Skew Matrix

Previously, RiSkew would generate an incorrect matrix in many cases. This has been fixed in 3.6g.

 

Large Motion Blur

Motion blurs larger than a bucket often produce bucket related artifacts. In release 3.6g a new parameter to RiHider jitterperbucket can alleviate these artifacts when set to a value of zero.
Hider "hidden" "jitterperbucket" [0]

 

Zbuffer Hider Shadow Output

The zbuffer hider previously produced invalid depth values for buckets which contained no primitives. This has been fixed in 3.6g.

 

Alias Files

Support for texture creation from Alias Matte files has been added to 3.6g. Support for output of Alias Matte and Alias Depth files has been added to the alias display driver in 3.6g. The sho utility in release 3.6g now supports Alias Depth files.

 

Sloargs

The sloargs library would crash on certain shaders. This has been fixed in 3.6g.

 

X11 Display Driver

Sending 16-bit colors to the x11 display driver previously caused display of invalid data. This has been fixed in 3.6g. The x11 driver properly displays the most significant 8-bits of 16-bit colors. Setting the environment variable DSPYBACKGROUNDPIXELVALUE will cause the x11 display to preset the output window to that color. The background color is overwritten when buckets are written. The background color remains in areas where no data has been written. The background color is for screen display only and if the image is saved to a TIFF file, background areas will be black as usual.

 

Tiff Display Driver

The tiff display driver in 3.6d generated invalid data for 3-channel floating-point files. This has been fixed in release 3.6g.

 

sho

sho could potentially clobber a file it was attempting to display if an invalid framebuffer device was specified in the rendermn.ini file, or if the framebuffer could not be opened for some system dependent reason. This has been fixed in release 3.6g.

 

txcopy

A bug in the txcopy prevented use of the -ch option. This has been fixed in release 3.6g.

 

Incorrect Normals for Polygons or Bilinear Patches

Trianglular polygons or bilinear patches with a degenerate side could, under some conditions, have incorrect normals and derivatives calculated for them by the renderer. This has been fixed in 3.6g.

 

4. Known Problems and Bugs

The following problems and bugs are known to exist in the RenderMan Toolkit 3.6 as of the date of this document. These include errors in the implementation that cause requests to be ignored or handled improperly, lead to images that are incorrect, or cause any of the programs to abort. These problems and bugs have been targeted to be fixed in future releases of the software, and are noted here so that others can avoid trying to use features that do not work or reporting known problems and bugs to Pixar. If a workaround to any problem or bug is available, it is listed or a reference to a workaround is given.

4.1. PhotoRealistic RenderMan 3.6 Known Problems and Bugs

The known problems with the rendering software are detailed in this section. Generic display driver problems and problems related to Vector RenderMan are also included here.

Constructive Solid Geometry (CSG)

An object, formed by CSG operations on two or more objects, that surrounds the camera position in the scene may produce incorrectly formed object geometry. This is because some of the geometry necessary to produce a correctly formed CSG object may be "clipped" from the scene before the complete CSG operation is performed. Similarly, a CSG formed object that appears too close to the camera position may also be incorrectly formed for the same reason. Avoid moving the camera through (or too near) CSG objects to ensure this problem does not occur.

 

Incorrect RiSolidBegin-End stacking

The renderer sometimes does not detect when RiSolidBegin-End is incorrectly nested with RiAttributeBegin-End. No messages will be issued but the renderer will not work correctly. The user should ensure that Begin-End pairs are matched properly to avoid problems.

 

Patch Cracks

Under certain conditions, bilinear and bicubic patches will generate noticeable cracks. This behavior has, to a large degree, been fixed in PhotoRealistic RenderMan 3.6. If cracks are still encountered, they can usually be cleaned up by setting the binary dicing attribute (see the Users Manual).

4.2. Shading Language Known Problems and Bugs

Known problems with the Shading Language are detailed in this section.

Function Local Variables

Occasionally, the Shading Language compiler will incorrectly assume that the local variables of user-defined functions are uniform, when they actually need to be varying in order to operate correctly. This can only occur if the varible is not explicitly defined to be either uniform or varying, but the usage of the variable requires varying. The effect of this can be either appear as large rectangular shading artifacts appearing on primitives, or as run-time renderer warning messages such as
S05001 shadeop error: argument -1 is wrong type in op _add at pc 27 in "foo".
The workaround for this error is to declare function variables to be varying in situations where this is known to be the desired storage class, and not let the class default.

 

4.3. RIB Client Library Known Problems and Bugs

Known problems with the RIB client library are detailed in this section.

Predefined Variables

When using the RIB client library, the predefined RtToken variables (e.g., RI_P, RI_RGB and RI_SPOTLIGHT) are not initialized until RiBegin has been called.

 

PatchMesh Variables

The RIB client library (as opposed to the PhotoRealistic RenderMan renderer itself) has a bug which can cause the library to output an incorrect number of primitive variables (other than position) on patch meshes. The RiBasis call does not stack the step-size arguments for later use by RiPatchMesh. This results in the RIB client library not being able to restore the previous step-size values when the attribute stack is popped. If the step-size changed inside the attribute block, subsequent calls to RiPatchMesh will output the wrong number of primitive variables (position, fortunately, is never done incorrectly). The problem can be worked around by always calling RiBasis before RiPatchMesh if there is any possibility that the step-size was modified inside of a preceding attribute block.

4.4. Utility Programs Known Problems and Bugs

A number of utility programs are distributed as part of the RenderMan Toolkit. This section notes known problems with these utilities.

tiff*
With the exception of tiffcopy, none of the TIFF utilities (e.g., tiffdspy, etc.) will read separate-component or tiled TIFF files. A separate-component or tiled TIFF file may be read using tiffcopy and output to a TIFF file format which the other TIFF utilities can properly read. (Pixar products such as PhotoRealistic RenderMan do not generate such separate-component or tiled TIFF images, but some programs from other vendors do.)

4.5. RenderMan Companion Examples Known Problems

The examples contained in the book The RenderMan Companion are provided in executable form as a tutorial that is part of the RenderMan Toolkit. There are several typographical and logical errors contained in these examples that are ennumerated in The RenderMan Companion errata provided as part of the documentation with the RenderMan Toolkit. This section contains other problems that have been identified with the tutorial examples.

Tutorial Chapter 17

In the Eye-Plane Splitting examples of the RenderMan Toolkit Tutorial (Section 17.2.4), both examples will print a warning message. The first example is a case where "warning messages are printed but the scene is not visibly affected."

The Binary Dicing example (Section 17.3.1) doesn't display the effect originally intended due to a change to the rendering software that repairs patch cracks in most cases. Also the resolution of the resulting image may be too large for some display drivers.

5. Implementation Restrictions

Usage restrictions of the current implentation are listed in this section.

5.1 RenderMan Optional Capabilities

Optional Capabilities are those features specified in the RenderMan Interface Specification Version 3.1 that are not required to be supported in all implementations of RenderMan-compliant renderers. The subroutines which would normally implement the interface to these capabilities must exist, but need not do anything. This section lists the limitations of PhotoRealistic RenderMan 3.6 with regard to these optional capabilities.

Motion Blur

In the current implementation, only linear blur between the shutter open time and shutter close time (as specified with RiShutter) is supported. Therefore, all RiMotionBegin calls must specify the same two times as RiShutter.

Shading parameters (colors, shaders, etc.) can never be motion blurred.

 

Unimplemented Capabilities

The Level of Detail, Special Camera Projections, Deformations and Spectral Colors optional capabilities are not implemented in PhotoRealistic RenderMan 3.6. In all cases, the default actions as specified in the RenderMan Interface Specification Version 3.1 are performed.

The Bump Mapping, Volume Shading, Ray Tracing, Radiosity and Area Light Sources optional capabilities are also not implemented. In all cases, the default actions as specified in the RenderMan Interface Specification Version 3.1 are performed. (In other words, the Shading Language functions incident(), opposite(), bump(), and trace() all return 0.0).

defaultsurface

The default surface shader (defaultsurface), which is loaded during RiBegin, is located using the built-in shader path and this path cannot be altered with the RiOption("searchpath","shader", ...) command. The path for default surface may be changed by using the rendermn.ini file (see the PhotoRealistic RenderMan User's Manual for more information).

 

Shadow Bias

The shadow bias parameter sets a tolerance that prevents a surface from erroneously shadowing itself. If the bias is too large, shadows might end some distance from the objects that cast the shadows; as a result, objects on a table appear to "float" above the table. If the bias is too small, dark spots and moire' patterns might appear on a surface due to erroneous self-shadowing.

The default values of the shadow bias (bias0 = 0.15, bias1 = 0.30) should be suitable for models whose diameter is between 10 and 100 units in camera space (normally the same size in world space). If your model is smaller, you might have to reduce the bias, and if your model is larger, you might have to increase it. As a rule of thumb you should start with bias equal to approximately one percent of the model diameter.

The values of the two bias parameters (bias0 and bias1) can be made the same. If the two values differ, the actual bias is set to the average of the two values.

 

Calculating Displaced Geometry

Displacement shaders are intended to be used to add detail to the surface of geometry primitives. Displacement shaders were NOT intended to be used to make radical changes in surface geometry. Unless specified otherwise, the bounding box of an object is assumed to be the bounds that the displacement shader will not exceed. When using displacement shaders, an attribute to the object primitive(s) should always be specified indicating the amount the normal bounding box should be enlarged to ensure that the bounding box completely encompasses the displaced geometry. This attribute is specified by the RiAttribute procedure (see the PhotoRealistic RenderMan User's Manual).

When a piece of geometry that has a displacement shader attached is viewed very closely, so that the displacement bounds specified by an RiAttribute call when tranformed into screen units exceeds 32 pixels, PhotoRealistic RenderMan outputs a warning message indicating that excessive displacement is being performed. This message indicates that the renderer will perform extra computation on displaced geometry in an attempt to cut back significantly on memory use. The value 32 mentioned above can be altered with the use of the RiOption("extremedisplacement", ...) call (see the PhotoRealistic RenderMan User's Manual for details).

The warning message is for informational purposes only, and the rendering should proceed to completion, although the PhotoRealistic RenderMan rendering algorithm does not have optimal performance (speed or memory utilization) when this situation occurs. If the memory usage of displaced geometry becomes excessive to the point of paging, the RiOption call can be used to set the extremedisplacement limit.

5.2. Shading Language Restrictions

User Defined Function Restrictions

Shading Language functions that are user-defined (i.e., user-supplied functions, not the standard functions provided with the Shading Language) are implemented with the following restrictions:

 

 

Builtin Function Restrictions

Certain restrictions apply to the implementation of the Shading Language builtin functions.

 

 

Distributed Shader Restrictions

The default parameters on some of the distributed shaders should be adjusted to improve their results.

 

Imager Shaders

Programmable Imager shaders are not supported in PhotoRealistic RenderMan.

 

Volume Shaders

Volume shaders are not supported in PhotoRealistic RenderMan.

5.3 Restrictions Using RIB

When using RIB to communicate data to a renderer, there are limitations on usage of certain functionality of the RenderMan Interface due to the fact that the renderer and the driving modeler are separate processes communicating through the RenderMan Interface Bytestream (RIB) data stream. Since the renderer and modeler do not share the same address space, mechanisms such as function pointer arguments do not work. Should the RIB protocol be enhanced to support renderer emulation and callbacks, these limitations will be removed. If the library version of PhotoRealistic RenderMan 3.6 (libprman.a) is linked directly to application programs, these limitations do not apply.

Pixel Filters

Only the predefined pixel filter functions work. User-defined pixel filter functions passed as function pointers to RiPixelFilter are ignored, as there is currently no mechanism for RIB to pass such information to the renderer.

 

Transformed Points

The RIB client library does not support the RiTransformPoints subroutine call, because the client does not have access to the internal state of the rendering server (e.g., the transformation stack).

 

Procedural Primitives

The RIB client library does not pass RiProcedural subroutine call information to the renderer, because there is currently no mechanism for the renderer to transmit refinement requests back to the client. Instead, the RiProcedural subroutine immediately asks for full refinement of procedural primitives by calling the refinement subroutine with an RI_INFINITY level-of-detail.

 

Errors

Error return codes received by users of the RIB client library are indicative only of the small number of parsing errors noticed by RIB.

There is currently no mechanism to transmit the actual error codes generated by the renderer back to the client.

Only the predefined error handlers work. User-defined error handlers passed as function pointers to RiErrorHandler are only used for RIB client errors, as there is currently no mechanism for RIB to pass such information to the renderer.

If the error handler RiErrorPrint is used, error messages will be printed to the renderer's standard error stream.

6. Documentation Errors

Reference Documentation

The tiff(4) reference page indicates that it can handle one-channel images. This is incorrect and will result in a program error if attempted.

 

RenderMan Companion

The target audience for The RenderMan Companion was C programmers. Hence, all of the examples in the book are listings of C programs. Few of the examples are complete and are not intended to be simply entered and run. However, all of the examples are available complete and ready to run in source code form as the Tutorial in Pixar's RenderMan Toolkit.

The C program examples in The RenderMan Companion are NOT available using the RIB binding as part of any product. In general, converting the C programs to RIB format is straightforward since the RenderMan Interface C procedures ("Ri"*) and their associated RIB bindings are the same except the RIB bindings do not begin with "Ri" (e.g., the RiDisplay C procedure corresponds to the Display RIB binding). Also, the parameters passed to the C "Ri"* procedures must accompany the RIB command as explicit values. For example, the following C code:

#include <ri.h>

RtPoint Square[4] = { {.5,.5,.5}, {.5,-.5,.5}, {-.5,-.5,.5},
  {-.5,.5,.5} };

main()
{
    RiBegin(RI_NULL);   /* Start the renderer */
        RiDisplay("RenderMan", RI_FRAMEBUFFER, "rgb", RI_NULL);
        RiFormat((RtInt) 256, (RtInt) 192, -1.0);
        RiShadingRate(1.0);
        RiWorldBegin();
            RiSurface("constant", RI_NULL);
            RiPolygon((RtInt) 4,      /* Declare the square */
                RI_P, (RtPointer) Square, RI_NULL);
        RiWorldEnd();
    RiEnd();             /* Clean up */
    return 0;
}
would be represented by the following RIB file:
#Start the renderer
##RenderMan RIB
version 3.03
Display "RenderMan" "framebuffer" "rgb"
Format 256 192 -1.0
ShadingRate 1.0
WorldBegin
Surface "constant"
#Declare the square
Polygon "P" [.5 .5 .5 .5 -.5 .5 -.5 -.5 .5 -.5 .5 .5]
WorldEnd

The RiBegin and RiEnd C procedures have no corresponding RIB binding, and hence no Begin or End RIB statements appear in the RIB file. The ##RenderMan RIB and version 3.03 RIB statements are automatically output to a RIB file by the RIB client library. All of the RIB statements that begin with # are comments that are ignored by the RIB parser.

 

RenderMan Companion Errata

There are many small errors that have been found in The RenderMan Companion. An extensive list of the known errors that appeared in the first printing of the book is contained in The RenderMan Companion Errata document.

All of the small errors identified in the errata that could be corrected without changing the pagination of the book were corrected in the second and subsequent printings of the book. A smaller RenderMan Companion Errata document has been prepared for the second printing, which lists only the the substantive errors that have not been corrected in the second printing of the book.

The following error has also been found, but has not yet been added to The RenderMan Companion Errata document:

The fractaltriangle structure definition on page 204 of The RenderMan Companion is incorrect and should be modified to be:

 

typedef struct fractaltriangle {
  FractalPoint vertices[3];
  struct fractaltriangle *children;
  int level;
} FractalTriangle;

7. Platform-Specific Notes

This section details issues specific to the various platforms.

7.1. Silicon Graphics Specific Notes.

The RenderMan Toolkit 3.6 for Silicon Graphics systems differs in a number of ways from the version for systems from other vendors.

mips1 versus mips2
Two versions of the RenderMan Toolkit 3.6 for Silicon Graphic are present in the distribution. The mips2 version of the Toolkit will run on all MIPS processor based Silicon Graphics systems, except systems based on the MIPS R2000 or MIPS R3000 processor chips. The mips1 version is provided for sites still relying on systems based on the R2000 or R3000. The mips2 version will run up to 10% faster than the mips1 version on the systems that support it. New additional software such as the it display driver (see next item) and the new RenderMan Artist's Tools products such as ATOR, Alfred and Combiner are only available for the mips2 version. If you are not sure what system type you have, use the hinv command and look at the line labeled: CPU.

 

Default Display is "x11"
The default display driver for the framebuffer type is now x11 on all systems. In release 3.5, the default for Silicon Graphics systems was the gl as the default framebuffer driver are:

 

  1. Set the enviroment variable RMANFB:

     

      % setenv RMANFB gl

     

  2. Define the default /displaytype/framebuffer in the rendermn.ini file to be as follows:

     

      /displaytype/framebuffer gl

 

New Display Driver "it"
A new display driver of type framebuffer is included in the mips2 version that displays the image with the ability to zoom in and out as well as scroll through a subwindow of the image. The driver is named it. Two ways to set up the it driver as the default framebuffer driver are:

 

  1. Set the enviroment variable RMANFB:

     

      % setenv RMANFB it

     

  2. Define the default /displaytype/framebuffer in the rendermn.ini file to be as follows:

     

      /displaytype/framebuffer it

 

Gamma Correction
When using the x11 display driver (the default) on systems other than Silicon Graphics, the display driver assumes that the system is not providing gamma correction for the display, so it adjusts the image using a gamma value of 2.0. Since SGI systems provide control of the gamma correction of the display using the gamma command, the default behaviour of the x11 display driver is to not perform gamma correction. As usual, this behaviour can be overridden using the DSPYGAMMA environment variable.

This differing behaviour is usually only noticeable in a mixed environment. When displaying an image from an SGI to a non-SGI using the x11 display driver with the DISPLAY environment set, the image will usually appear too dark. Conversely, when displaying an image from a non-SGI to an SGI using the x11 display driver with the DISPLAY environment set, the image will appear too bright. This is because the display driver gamma correction behaviour is set according to the system on which the driver is running, not the system on whose screen the X window system is displaying the image. This behaviour can of course be compensated for by setting the DSPYGAMMA environment variable appropriately.


 

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