Resources Documentation RenderMan :Release Notes :PRMan Notes :

RenderMan 3.7 Release Notes

PhotoRealistic RenderMan 3.7d
Release Notes

Pixar
October, 1997

1. Introduction

RenderMan Toolkit
3.7. 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.6

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.7 Major Changes

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

Point Primitives

Point primitives are designed to be used in situations where large numbers of subpixel sized particles need to be rendered. Each point is efficiently converted into only two micropolygons and shaded more efficiently than the normal practice of using small spheres or bilinear patches. Point primitives are formally detailed in the RenderMan Interface Specification 3.2 and in Applications Note #18: Using the RtPoints Primitive.

 

Curve Primitives

The new Curve primitive implements an three dimensional curve of varying width. Curves may be specified in any basis, and the widths can similarly be specified in arbitrary spaces. Curves are more lightweight than other primitives such as cylinders, and are good for representing hair and other thin cylindrical objects. Curve primitives are formally detailed in the RenderMan Interface Specification 3.2 and in Applications Note #19: Using the RtCurves Primitive.

 

New Level Of Detail Controls

PhotoRealistic RenderMan now supports level of detail, which allows automatic shifting between detailed and simplified models based upon their size on the screen. This feature is further documented in Applications Note #21: Using Level of Detail.

 

New Procedural Primitive Support

PhotoRealistic RenderMan now can call external programs or dynamically linked libraries to generate geometry on the fly. This feature is further documented in Applications Note #23: Using Procedural Primitives in PhotoRealistic RenderMan .

 

More Flexible Motion Blur

Users are now free to specify up to six separate versions of blurring geometric primitives. PhotoRealistic RenderMan will use the beginning and end shutter times to interpolate among these six to generate beginning and ending geometric positions, and then interpolate between these to generate motion blur.

 

Improvements in サンプリング

Several artifacts resulting from poor sampling patterns have been removed or ameliorated. In particular, motion blur sampling should appear much better, even with large bucket sizes. A bug which caused artifacts at bucket edges when using the jitter hider has been removed.

 

2.2. シェーディング Language Major Changes

New features added to the シェーディング Language compiler and シェーディング Language runtime system are listed in this section.

Extensions to the シェーディング Language

Many new language features have been created in this release.
  • New Variable Types
  • Arrays in シェーディング Language
  • New and Improved Built-in Functions
  • ライティング Control -- nondiffuse and nonspecular lights
  • Broad Solar ライト
  • Message Passing Between Shaders
  • User Functions and Scoping Changes
  • Time Derivatives
  • Volume Shader Functionality

 

New Shader Compiler

The shading compiler has been entirely reimplemented with better optimizations and improved error detection. Consult the shader manual page for a description of these changes. Some changes may need to be done to preexisting shaders to get them to compile with the new shading compiler: these changes are documented in Application Note 17: Converting Shaders to use new シェーディング Language Features

 

Improved Volume Shaders

In previous releases of PhotoRealistic RenderMan, a volume shader could only determine the illumination at the point being shaded P. This restriction has been eliminated, and volume shaders may now determine the illumination of arbitary points in the scene, allowing volume shaders that do atmospheric shadows to be done in a straightforward fashion. サンプル of using the new volume shader functionality can be found in the Atmosphere and Interior Shaders application note.

 

2.3. RIB Client Library Major Changes

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

Compressed RIB streams

PhotoRealistic Renderman can now read compressed rib files, in either binary or ascii forms. The compression format is derived from the freely available libzip library, and is compatible with the popular GNU compression program gzip. The program catrib may also be used to output and convert compressed RIB streams.

 

3. Bug Fixes and Minor Changes Since Release 3.6

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.7 Bug Fixes and Minor Changes

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

Alias file format support

The Alias file format now supports files with depth and matte information. Alias files are now acceptable as input to txmake.

 

Cineon file format support

PhotoRealistic RenderMan now supports output of Kodak Cineon files.

 

Composer Z file format support

PhotoRealistic RenderMan now supports output of depth files in the (Alias/)Wavefront Composer file format.

 

GeneralPointsPolygons bug now fixed

Previous releases suffered from a bug in varying variables when assigned to PointsGeneralPolygons primitives, resulting in incorrect values being assigned to individual polygons. This bug has been removed.

 

Mailbox memory leaks

Mailboxes would occasionally improperly free memory allocated to them in version 3.6. These bugs have been removed in 3.7.

 

3.2. シェーディング Language Bug Fixes and Minor Changes

dPdtime and dtime variables added

Users can find information about how far a point to be shaded is moving by accessing the dPdtime and dtime shader variables.

 

HSY color space modifications

Conversions to the HSY color space now work properly for negative arguments.

 

break and continue fixes

Rarely noticed bugs with the flow control statements break and continue have been fixed.

 

Variable classes described

If you have been confused by the differences between variables declared as constant, varying, uniform or vertex, the new application note Applications Note #22: Class Specifiers for Primitive Variables should help.

 

3.3. Bug Fixes in 3.7d Patch Release

Long Curve Optimization

Bugs in handling Curve primitives which were long on screen have been fixed. Such Curve primitives should now render with significantly less memory and less CPU time than before.

 

Point Width Bug Fix

A bug in handling Point primitives which sometimes resulted in unpredictable width and transparency values has been fixed.

 

Procedural Primitive Bug Fix

A bug in handling "RunProgram" Procedural primitives close to the camera, which resulted in OS errors of the form "Cannot fork", has been fixed.

 

Degenerate GeneralPolygon Bug Fix

A bug in handling extremely degenerate GeneralPolygon and PointsGeneralPolygons that could crash the renderer has been fixed.

 

4. Known Problems and Bugs

The following problems and bugs are known to exist in the RenderMan Toolkit 3.7 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.7 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 ジオメトリ (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 was, to a large degree, fixed in PhotoRealistic RenderMan 3.7. If cracks are still encountered, they can usually be cleaned up by setting the binary dicing attribute (see the Users Manual).

4.2. シェーディング Language Known Problems and Bugs

Known problems with the シェーディング Language are detailed in this section.

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. ユーティリティ 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 サンプル 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.7 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 Riシャッター) is supported.

シェーディング parameters (colors, shaders, etc.) can never be motion blurred.

 

Unimplemented Capabilities

The Special カメラ Projections, Deformations and Spectral カラーs optional capabilities are not implemented in PhotoRealistic RenderMan 3.7. In all cases, the default actions as specified in the RenderMan Interface Specification Version 3.1 are performed.

The バンプ Mapping, Volume シェーディング, 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 シェーディング 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 ジオメトリ

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. シェーディング Language Restrictions

User Defined Function Restrictions

シェーディング Language functions that are user-defined (i.e., user-supplied functions, not the standard functions provided with the シェーディング Language) are implemented with the following restrictions:

 

  • Recursive functions are not allowed.
  • Functions are expanded inline by the compiler, during compilation. If a function is changed, all shaders using it must be recompiled in order to use the new version.
  • Function parameters are passed by reference. If a function modifies a parameter, that modification will be reflected in the caller's variable.
  • Internally, the シェーディング Language compiler generates unique names for function parameters by concatenating the function and parameter names. The name thus generated is subject to a 32-character limitation. Care should be taken to ensure that the combined length of function and parameter names does not exceed this 32-character limit or a fatal error will occur in the シェーディング Language compiler.
  • Global variables are not accessible inside user-defined functions. They must be explicitly passed as parameters or declared as extern variables.
  • Multiple return statements are not supported. User-defined functions should have only a single return statement.

 

Builtin Function Restrictions

Certain restrictions apply to the implementation of the シェーディング Language builtin functions.

 

  • The area(), calculatenormal(), Deriv(), Du(), Dv(), environment(), shadow(), and texture() functions should never be used inside of a conditional block whose conditional test depends upon varying expressions (e.g., if (N.I) > 0 {...). These functions depend on comparing various values at more than one point on the surface, and can produce unexpected results when they reference those values at points that did not satisfy the conditional statement. Any results obtained in such a conditional block are (by definition) questionable.
  • The diffuse() and specular() functions do not normalize their arguments.
  • The specular() function implemented in PhotoRealistic RenderMan is not identical to the function described on page 127 of the RenderMan Interface Specification Version 3.1. The function actually implemented is similar to the Beckmann function and has somewhat more desirable behaviour in near silhouette cases.
  • The fresnel() function returns the wrong value if N.I is greater than zero. N should be faceforward()ed with I before being passed to fresnel().

 

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

Interior and Exterior 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.7 (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);
        RiシェーディングRate(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
シェーディングRate 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.7 for Silicon Graphics systems differs in a number of ways from the version for systems from other vendors.

MIPS Architecture Choices
Three versions of the RenderMan Toolkit 3.7 for Silicon Graphics systems are present in the distribution. The MIPS2 version of the Toolkit will run on all MIPS processor-based Silicon Graphics systems based on the MIPS R4000 processor chip or better (this is the entire SGI product line subsequent to the original Indigo 1), and running Irix 5.x or Irix 6.x. The MIPS3 version of the Toolkit will run on Silicon Graphics systems based on the MIPS R4400 processor chips or better, which are running Irix 6.x (this includes most Indigo 2 "green box" machines). The MIPS4 version of the Toolkit will run on MIPS processor based Silicon Graphics systems based on the MIPS R8000 and MIPS R10000 processor chips (Power Indigos through the modern O-class machines). Older MIPS processors (R2000, R3000) and Irix 4.x are no longer supported.

The MIPS3 version will run up to 20% faster than the MIPS2 version on the systems that support it. The MIPS4 version will run up to 20% faster again than the MIPS3 version on the systems that support it. If you are not sure what system type you have, use the hinv command and look at the line labeled: CPU. For the purposes of linking with the libraries in the distribution, application developers should note that the MIPS3 and MIPS4 distributions are compiled with the -n32 compiler flag.

Warning: SGI compilers for MIPS3 and MIPS4 still have some glitches. We believe that we have found workarounds for all of the compiler bugs, but it is possible that some remain. If you find situations where the MIPS3 or MIPS4 distributions create different images than the MIPS2 distribution, please contact Pixar.

 

Framebuffer ディスプレイドライバ
The default display driver for the framebuffer type is now x11 on all systems. On distributions for Silicon Graphics systems, users have two other choices.

In Release 3.5, the default for Silicon Graphics systems was the gl display driver. The gl display driver is still available on the MIPS2 distribution, but only functions correctly on machines running Irix 5.x (that is, which still have the appropriate GL shared library). If this is applicable to you, there are two ways to restore gl as the default framebuffer driver. You can:

 

  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

A new display driver of type framebuffer is included with all SGI distributions which 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.

TM & © 1986 - Pixar. All Rights Reserved.