Prev |
Next
PhotoRealistic RenderMan 3.7d
Release Notes
Pixar
October, 1997
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.
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.
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 Sampling
-
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.
New features added to the Shading Language compiler and Shading Language
runtime system are listed in this section.
- Extensions to the Shading Language
-
Many new language features have been created in this release.
- New Variable Types
- Arrays in Shading Language
- New and Improved Built-in Functions
- Lighting Control -- nondiffuse and nonspecular lights
- Broad Solar Lights
- 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 Shading 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. Examples of using the new volume shader
functionality can be found in Applications Note #20: Writing Fancy Atmosphere Shaders.
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.
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.
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.
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.
- 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.
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.
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 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).
Known problems with the Shading Language are detailed in this section.
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.
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.)
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.
Usage restrictions of the current implentation are listed in this section.
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 RiShutter)
is supported.
Shading parameters (colors, shaders, etc.) can never be motion blurred.
- Unimplemented Capabilities
-
The Special Camera Projections, Deformations and
Spectral Colors 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 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.
- 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:
-
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 Shading 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 Shading 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 Shading 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.
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.
- 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;
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 Display Drivers
- 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:
- Set the enviroment variable RMANFB:
- 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:
- Set the enviroment variable RMANFB:
- 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.
Prev |
Next
Pixar Animation Studios
Copyright©
Pixar. All rights reserved.
Pixar® and RenderMan® are registered trademarks of Pixar.
All other trademarks are the properties of their respective holders. |