Siren is a renderer implementing the Renderman standard for the description of 3-dimensional scenes. This document describes Siren's conformance with the Renderman standard and the renderer-specific features of Siren.
The RenderMan® Interface Procedures and RIB Protocol are: Copyright
© 1987, 1988, 1989, 1995 Pixar. All rights reserved.
RenderMan® is a registered trademark of Pixar.
Siren filenamewhere filename is the name of a RIB file. Depending on the display settings in the file, Siren will either generate an image file or render directly to the screen. For screen rendering Siren uses VESA Super VGA graphics modes. You can stop the program at any time by pressing the space bar. To save a picture after it has finished rendering, press W.
The general syntax for invoking Siren is:
Siren [options] RIBcommand(s) or RIBfile(s)Options, if present, must appear before any commands or filenames. Any RIB command may be passed as an argument by enclosing it in quotes. For example:
Siren "Shutter .1 .2" myscene.ribSiren accepts multiple commands and/or RIB files. They are parsed in order from left to right.
-dForces output to the screen. Individual images can still be sent to disk by specifying at "imageclass" in a Display call. See Display Image Class
-anim nframes (starttime endtime (fractionopen))Generates a sequence of nframes frame blocks with shutter times for animating time-varying RIB files. See Using Motion Blocks for Animation for more details.
-frames start endRestricts output to frames numbered between start and end, inclusive. This may be used with the -anim option or any RIB with frame blocks.
-res width height (pixelaspectratio)Sets the resolution of the rendered image. Equivalent to
Format width height pixelaspectratiopixelaspectratio defaults to 1 if omitted.
-crop left right top bottomRestricts rendering to a subrectangle. Equivalent to:
CropWindow left right top bottom
-file filenameSends output to the specified file.
-phong nSets the threshold for phong shading. Equivalent to:
Option "limits" "phongthreshold" nSee Shading in Siren for details.
-shadowsTurns ray-traced shadows on. Equivalent to
Option "raytrace" "shadows" "on"
-samples xsamples ysamplesSets the number of samples per pixel. Equivalent to:
PixelSamples xsamples ysamples
-mode rgb|v|rgbaSelects the channels for output. This setting will be overridden by any subsequent calls to Display.
-frate framerateSets the playback rate in frames/second for animations recorded in Flic format.
Both RGB and RGBA files are supported. If the display mode is set to "v", a single-channel grey-scale image is output, representing the V component of the HSV transform of the color.
Frames written to disk after being drawn to the screen are saved as TIFF images. 256-color screens are saved as palette color images; full-color screens are saved as RGB files.
Siren chooses a screen mode based on 2 RIB commands: the resolution specified in Format, and the ncolors display option. Siren will use the lowest resolution that satisfies the number of pixels and colors requested.
There may be problems in using modes beyond 320x200, 256 colors on some
systems. In particular, higher graphics modes may not work under
Windows NT or Windows 2000.
To record an FLI file, place a line like the following at the beginning of the file containing the animation frames:
Display "orbit.fli" "file" "rgb"Siren recognizes the ".fli" extension as an indicator to make an FLI file. Subsequent calls to Display are ignored, and the frames in the animation are saved to disk in the order of their declaration in the RIB file. FLI files are limited to 256 colors, but may be of any resolution.
An animation can also be requested by passing the -file command
line parameter a filename ending in .FLI
In addition to "rgb" and "rgba" Siren supports an output mode of "v",
which saves the "v" component of the "hsv" transform of the current color.
This is an easy way to render a grey-scale image of a color scene.
#f is replaced with the current frame number, formatted as 3 digits
with leading zeroes.
#s is replaced with the frame sequence number, which is incremented once for every frame block, regardless of frame number.
#n is replaced with a running sequence number, which is incremented once for every image file output
"imageclass" "anything"When creating a Flic animation file Siren normally ignores calls to Display after the first and sends all images to the animation file. However, some images may need to be sent to separate files for texture, environment, or shadow maps. Passing the imageclass parameter with any argument will force the next image to be sent to the specified destination, which should be a file.
The idea behind the use of "imageclass" is to classify images into certain types: e.g., "environment", "texturemap", "shadowmap", "required". In the future it may be possible to globally select the classes of images to render. At present this capability is NOT implemented.
Option "display" "colorvariance" nColorvariance sets the maximum amount a color can deviate from an existing palette entry before a new entry is allocated. It should be an integer greater than or equal to zero. Setting colorvariance to 0 will cause a new palette entry to be allocated for every new color encountered until the palette is full (no difference tolerance). Higher values will allow one palette entry to represent a neighborhood of color values. Larger values of colorvariance allow a broader range of colors to be reasonably represented on-screen, with a loss in the accuracy of the representation of any particular color. The default for colorvariance is -1, which uses a dynamically adjusted colorvariance to build the palette.
A color palette can also be loaded from a file using:
Option "display" "palette" "mycolors.pal"Siren includes a utility, GetPal, that will extract a palette from a palette-format TIFF file or a FLIC animation. The palette file format is very simple, should you wish to create your own. It's simply a sequence of up to 256 RGB values. Each color component is stored as an unsigned byte.
Attribute "divide" "u" udivisions "v" vdivisionsudivisions and vdivisions are the number of segments used to approximate the u- and v-axes of the object. Curved primitives will be rendered using udivisions x vdivisions polygons. For example,
Attribute "divide" "u" 12 "v" 6
Sphere 1 -1 1 360will result in a sphere made of 72 polygons. If either udivisions or vdivisions is 0, a default value is used. The default for udivisions is 16. The default for vdivisions depends on the type of curved primitive, summarized in the table below:
|Cone, Cylinder, Disk, Hyperboloid||1|
|Patch, PatchMesh, Parabola||udivisions|
The type of shading is determined by the phongthreshold option and the
ShadingRate and ShadingInterpolation attributes:
|> phong threshold||"constant"||Flat|
|> phong threshold||"smooth"||Gouraud|
|<= phong threshold||"constant" or "smooth"||Phong|
Option "limits" "phongthreshold" nsets the threshold for Phong shading. Objects with a shading rate less than or equal to the threshold will be Phong shaded. Setting the threshold to 0 disables Phong shading for all objects. Conversely, setting the threshold to a value greater than the shading rate of all objects will force the entire scene to be Phong shaded.
It should be emphasized that the shading type can be set for each object. Judicious use of these settings is key to achieving high-quality images with short rendering times. All shading types are compatible with motion blur, depth of field, and solid modeling.
Option "limits" "strips" nIf n>0, all geometry is dumped to a disk file, and the scene is rendered in n vertical strips. This permits much larger scenes to be rendered, at the cost of traversing the geometry file n times. If you notice gaps in your scenes, or whole objects simply fail to appear, you probably need to render in strips.
Arbitrarily large scenes can be rendered using strips subject to the following restriction: all polygons crossing a row within a strip must fit in memory at the same time. If this condition is not met, Siren will discard some polygons, in a somewhat-intelligent but error-prone manner. These "dropped" polygons may leave gaps in the image. The number of strips needed depends on the maximum horizontal density of the scene.
A stripped image is rendered from the inside out. For scenes that render slowly because of complicated shaders, it can be worthwhile to render with 3 to 5 strips even with little geometry. The center section of the image will be completed first, perhaps allowing needed changes to be identified prior to completion of the whole image.
Stripping only saves geometry to disk. Shading information and texture map caches are still kept in memory, and that memory usage limits the complexity of scenes that can be rendered.
The default number of strips is 1.
Attribute "render" "truedisplacement" 1True displacement only works for displacement shaders.
Siren renders objects as sets of polygons. A displacement shader moves the vertices of the polygons. To achieve a desirable level of smoothness in the result, you may have to increase the number of polygons used to approximate an object. For curved surfaces, you can use the divide attribute. Currently there is not a way to subdivide polygons or bilinear patches. In some cases a flat bicubic patch can be used as a substitute. For example, to displace a unit square you might use:
Basis "bezier" 3 "bezier" 3 Attribute "divide" "u" 50 "v" 50 Patch "bicubic" "Pz" [0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0]
Imager "background" "bgcolor" [r g b]The "background" shader also sets the alpha value for uncovered pixels to 1. For 256-color images, the background color is color 0 in the palette (which is also the border color for the screen.)
Shaders of type Procedure are instanced the same way as other shaders:
Procedure name parameterlistProcedural shaders may be declared anywhere in a RIB file. A procedural shader should generate a series of RIB commands using ribprintf. The ribprintf command is syntactically identical to printf, but instead of sending its output to the standard console, it writes its output to a temporary file. After the procedural shader is run, the temporary file is inserted into the RIB stream as an archive file.
Because this is a nonstandard extension to the Renderman interface, it is not recommended that procedure shaders directly refer to procedure or ribprintf. The include file "RIB.h" contains two definitions, PROC and RIBOUT, that should be used instead. This allows some compatibility with other renderers (see below).
"RIB.h" also contains declarations for many RIB calls. These can be used in a manner very similar to the C interface. In particular, the C examples in the Renderman Companion can be translated in a straightforward manner.
Some RIB calls are not defined in RIB.h and may be difficult to generate. Improvements to RIB.h are welcome.
Any RIB call can be output by a procedural shade subject to the restriction that any call output must be valid within the context in which the shader is instanced. For example, a procedure called before WorldBegin can't output geometric primitives.
With a bit more work procedural shaders can also be used with other renderers that support the Shading Language. RIB.h includes declarations to make shader procedures look like surfaces and ribprintf calls look like printf to renderers other than Siren.
Another renderer can be used to evaluate a procedure by executing the shader once and redirecting the output to a text file. The output can then be included in a RIB stream using ReadArchive.
There is a simple rib file RUNPROC.RIB provided that does just this, by rendering a 1 pixel image. You will need to edit the file and replace the surface name with the name of your procedure and any parameters. Then (for BMRT) use the following command line:
rendrib runproc.rib >mymodel.ribProcedures may be instanced within motion blocks.
MotionBegin [0 .25 .5 1] Translate 0 0 0 Translate 0 1 0 Translate 1 1 0 Translate 1 0 0 MotionEndThere is no fixed limit to the number of times that can be given. Any RIB call with floating-point parameters can be included in a motion block (including options).
All interpolation is linear. Acceleration, deceleration, and smooth motion can't be easily specified. This can be partly overcome by using a deformation shader to define a motion path that varies with time, or by using a procedure shader to arbitrarily vary parameters to any RIB call over time.
Siren blurs motion by supersampling the scene in time. To blur an object, you must set both the pathsamples and objectsamples attributes:
Attribute "time" "pathsamples" 2 "objectsamples" 4pathsamples sets the number of points used to approximate the motion path, and the minimum value to blur anything is 2. It should be set before the first motion block that affects a path.
objectsamples gives the number of instances of a given object to create along the path, and should be set prior to the call that instances the object. Objects do not have to be defined within motion blocks in order to be blurred; it suffices for them to be instanced in a motion-blurred transformation. Currently there is a limit of 16 object samples and 17 pathsamples. If the number of objectsamples is greater than or equal to the number of pathsamples, the object is positioned by treating the path as a series of straight lines connecting the path sample points. If objectsamples=pathsamples-1 the object instances will be positioned at exactly the points at which the path is sampled.
Siren will only create multiple samples if they are needed. If the Shutter open and close times are equal, no supersampling will take place. Multiple samples will only be created for objects within motion blurred transformations or with time-varying shaders.
Transformations are blurred by interpolating their arguments, not their endpoints. Rotations, for examples, interpolate correctly as motion in an arc and not in a straight line (given enough path samples.)
Lights within motion blocks can also be supersampled by setting the lightsamples custom attribute:
Attribute "time" "lightsamples" 3Motion blurred objects and lights work correctly together and with ray-traced shadows. Objectsamples also applies to the instances created for ray-traced shadows, so shadows will also blur. Given a scene with moving and static objects and moving and static lights, an object will be illuminated by the right lights, which will cast shadows from the appropriate shadowing objects.
Surface, displacement, and atmosphere shaders that vary over time will be called with the global time variable set correctly for each object sample. Motion blur can be used with any of the shading types supported by Siren: flat, Gouraud, or Phong.
Motion blur can use alot of memory and take a long time. Super-sampling an object n times actually creates n copies of it, taking n times as long to render and taking n times as much memory. Failure to use enough samples will cause objects to strobe instead of blur (which may or may not be OK depending on the effect desired.)
Animating a time-varying scene requires generating a sequence of shutter times. Siren provides a command line option to automatically generate such a sequence. The syntax is:
Siren -anim nframes starttime endttime fractionopen myfile.ribnframes is the number of frames to generate. Numbering starts with frame 0.
starttime and endtime are the starting and ending time respectively. If omitted these default to 0 and 1.
fractionopen is the fraction of the time between frames the shutter is open. This allows motion blur. A value of 0 (the default) disables motion blur. A value of .5 indicates the shutter is open half the time between frames (approximately the same as a motion picture camera). A value of 1 generates a series of contiguous time intervals.
The -anim option generates a series of FrameBegin/FrameEnd blocks and Shutter calls. Any RIB commands or files included on the command line are called once within each frame block. An example:
Siren -anim 4 0 1 .4 myanim.ribis equivalent to:
FrameBegin 0 Shutter 0 .1 ReadArchive "myanim.rib" FrameEnd FrameBegin 1 Shutter .25 .35 ReadArchive "myanim.rib" FrameEnd FrameBegin 2 Shutter .5 .6 ReadArchive "myanim.rib" FrameEnd FrameBegin 3 Shutter .75 .85 ReadArchive "myanim.rib" FrameEndThere is a also a separate utility, AFRAME, included for creating a sequence of frame blocks as a text file.
Option "render" "mindofsamples" nThis option sets the minimum number of samples to use for each object when depth of field is engaged. The number of samples used for a particular object will be the maximum of mindofsamples and the objectsamples attribute. By setting mindofsamples to a lower number and tuning objectsamples for each object, the number of samples can be greatly decreased without a loss in image quality. In particular, objects that are in focus do not need to be supersampled (set objectsamples to 1.) Samples for depth of field should be 1, 4, 8, or 16. Currently the maximum number of samples is 16, which is the default for mindofsamples.
As with motion blur, depth of field can generate lots of geometry.
Deformation shaders are run on 4 canonical points and the results are used to construct a transformation matrix that is placed on the transformation stack just like any other transformation. This means that deformations are essentially restricted to those that can be represented as a series of transformations. Two uses for this limited capability:
1. Specifying transformations in a more intuitive manner: for example, the placecam.sl shader works like the placecamera() C procedure commonly used to set up the viewing transformation for a scene.
2. Specifying motion that varies non-linearly with time using the global time variable.
Deformations are also blurred if pathsamples > 1 and the camera shutter is open for a nonzero amount of time, even if the deformation is not called within a motion block. A motion-blurred deformation shader is evaluated once for each path sample.
Option "raytrace" "shadows" ("on"|"off")
Option "limits" "phongthreshold" phongthresholdObjects with a shading rate less than or equal to the phong threshold will be shaded once per pixel sample. Objects with a shading rate greater than the phong threshold will be shaded once per polygon (if ShadingInterpolation is set to "constant") or once per vertex (if ShadingInterpolation is set to "smooth.") Setting the phong threshold to 0 will disable phong shading. Setting it to a value large than the shading rate of any object will cause all objects to be phong shaded. See Shading in Siren for more details.
Option "limits" "strips" nSets the number of vertical strips in which to render the image; if n>0, caches the scene geometry in a disk file. See Rendering Large Scenes in Strips .
Option "limits" "mindofsamples" nSets the minimum number of objectsamples for depth of field. See Depth of Field .
Option "render" "prmanspecular" 0|1When set to 0, Siren will use the standard specular function. When set to 1, Siren will use a nonstandard specular function that is very close to that used by the renderer in BMRT (Blue Moon Rendering Tools). The default is 1.
Option "runtime" "verbosity" verbControls the level of renderer progress reporting. Possible values are "silent," "normal", or "stats."
Option "display" "palette" filenameSpecifies a palette file to be loaded and used when rendering 256-color screens or making a Flic animation.
Option "display" "colorvariance" nSets the amount one color may deviate from another before a new palette entry is allocated when generating a palette for a screen image or Flic animation.
Option "display" "ncolors" nRequests a display mode with n colors when rendering to the display.
Option "display" "framerate" nSets the playback rate for a FLIC animation file in frames/second. The default is 10.
Option "searchpath" "texture" "" Option "searchpath" "archive" "" Option "searchpath" "shader" ""Sets the searchpath for texture, archive, and shader files respectively. A path is a colon separated list of directories. The & character will be replaced by the current path. For compatibility with other renderers and operating systems, forward slashes (/) should be used instead of back slashes (\) to separate directory names.
Attribute "divide" "u" udivisions "v" vdivisions
Attribute "render" "casts_shadows" ("opaque"|"none") "has_shadows" ("yes"|"no")Sets attributes for ray-traced shadows. "casts_shadows" indicates whether an object casts shadows on other objects. "has_shadows" indicates whether an object receives shadows from other objects.
Attribute "light" "shadows" ("on"|"off")Turns ray-traced shadows on and off on a per-light basis.
Attribute "render" "truedisplacement" (0|1)When set to 1, tells the renderer to actually move the points on a surface with a displacement shader. Normally only the normal vector is perturbed. See Displacement Shaders for details.
Attribute "texture" "samples" nSets the sampling rate for texture map access. Shaders that use texturemaps will have the maps filtered using n samples, unless overridden by an individual texture call. The sampling rate is bound to a shader when it is instanced. The default value is 16.
Attribute "time" "pathsamples" n "objectsamples" n "lightsamples" nSets the sampling rates for motion blur. See Motion Blur. Defaults: pathsamples=2, objectsamples=4, lightsamples=1.
MakeCubeFacedEnvironment "px" "nx" "py" "ny" "pz" "nz" "mapname" fovMakeCubeFaceEnvironment does not create a new image file; instead it saves the name of the file to use for each face. The six face files must not be deleted for the environment map to work properly.
Display "shadow.z" "file" "z"For compatibility with other renderers Siren will recognize "zfile" as a synonym for "file."
Format 640 480 1 Quantize "rgba" 255 0 255 0.5 Hider "hidden" PixelSamples 2 2 PixelFilter "gaussian" 2 2 Exposure 1 1 Display "siren.tif" "file" "rgb" Projection "orthographic" CropWindow 0 1 0 1 RelativeDetail 1 Shutter [0 0] Imager "null"
Color [1 1 1] Opacity [1 1 1] Sides 2 Orientation "outside" ShadingRate 1 ShadingInterpolation "constant" DetailRange 0 0 1e9 1e9 Basis "bezier" 3 "bezier" 3 Surface "null" Atmosphere "null" Displacement "null"
Option "raytrace" "shadows" "off" Option "limits" "phongthreshold" 100 Option "limits" "strips" 1 Option "limits" "mindofsamples" 16 Option "display" "ncolors" 256 Option "display" "colorvariance" -1 Option "display" "palette" "" Option "display" "framerate" 10 Option "render" "prmanspecular" 1 Option "runtime" "verbosity" "normal"
Attribute "divide" "u" 0 "v" 0 Attribute "light" "shadows" "on" Attribute "render" "casts_shadows" "opaque" Attribute "render" "has_shadows" "yes" Attribute "render" "truedisplacement" 0 Attribute "texture" "samples" 16 Attribute "time" "pathsamples" 2 "objectsamples" 4 "lightsamples" 1
Last Modified April 9, 2000
For questions or comments regarding this document, email: email@example.com