PRMan User's Manual: Display Drivers

This section describes the display drivers which may be selected for use with PhotoRealistic RenderMan via the type parameter to RiDisplay, and the geometry drivers which may be selected via the driver parameter to bake3d(). These include two framebuffer drivers (x11 and windows), nine image file formats (tiff, sgi, alias, targa, cineon, softimage, mayaiff, openexr, texture), three depth data formats (shadow, zfile, deepshad), and three geometry formats for use with bake3d() (pointcloud, rib, wavefrontobj). The user may also extend PRMan's image capabilities by writing custom display drivers.

x11

This driver draws into a new window on 24-bit DirectColor, 8-bit PseudoColor, or 1-bit monochrome displays under the X11 window system. The driver dynamically determines whether the X11 display system has a 24-bit DirectColor, or 8-bit PsuedoColor visual available and behaves appropriately for each. If neither of the above is available, the default visual is used as a 1-bit monochrome display. The size of the inside of the window is determined from the image resolution. The window can be moved, closed and reopened without affecting output.

After rendering is completed or aborted, the window remains on the screen. The window is removed only when the window is selected for focus and a “q” is typed on the keyboard. For 8- or 1-bit displays, after rendering is completed, an image-improvement process takes place and the image is redrawn. Monochrome images are dithered, and 8-bit images are redisplayed using a color map selected by the median cut color selection algorithm and dithered (see “Color Image Quantization for Frame Buffer Display,” Paul S. Heckbert, Proc. SIGGRAPH '82, pp. 297-307).

In order to view a color image properly, the colors should be adjusted for the monitor. If this isn't done, images will usually appear to be too dark. The x11 display driver does this using a technique called “gamma correction” using a “gamma” value of 2.0 to approximate the color response of most color monitors. A different gamma value can be used by setting the DSPYGAMMA environment variable; for example,

will cause the driver to use a gamma value of 2.6 instead of the default. If the image appears washed out (bright), lower the gamma value (usually not below 1.0). If the image is too dark, raise the gamma value (usually not above 3.0). A gamma value of 1.0 will display the image unaltered on a display that has the color correction handled in another fashion.

windows

This driver draws into a new framebuffer window, on Windows systems. The size of the inside of the window is determined from the image resolution. The window can be moved, closed and reopened without affecting output.

After rendering is completed or aborted, the window remains on the screen. The window is removed by the normal methods, or when a 'q' is typed on the keyboard. The image window also supports one additional command: when 's' is typed, the currently display image will be saved to disk with the filename specified in RiDisplay, if possible.

tiff

This driver produces an output file in Tagged Image File Format (TIFF). It can be used to store "r", "rgb", "rgba", "rgbz", and "rgbaz" images in 8-, 16-, or floating point 32-bit-per-component resolutions. The TIFF file created employs LZW compression; 8, 16, or 32 bits per sample; one, three, or four samples per pixel; and a planar contiguous configuration.

The tiff driver also has special configuration options to control the resolution information written into the output file as well as the compression used for output. These may be set from the RiDisplay parameter list or through the configuration file.

The TIFF compression scheme can be controlled by setting the parameter "compression", which takes a string value which should be one of "lzw", "packbits", "deflate", "pixarlog", or "none". The default value for the compression scheme may be set by adding the following line

where compression-scheme is is one of the above strings. If no compression scheme is specified, LZW compression is used.

The TIFF resolution unit can be controlled by adding the parameter "resolutionunit", which takes a string value which should be one of "inches", "centimeters", or "none". The default value for the resolution unit may be set by adding the following line

where unit is is one of the above strings. If no units are specified the default is "none".

If the TIFF resolution unit has been defined as above, the TIFF resolution values can be controlled by setting the parameter "resolution", which takes a value that is an array of two floats specifying the resolution in the x and y directions. The default value for the resolution values may be set by adding the following line

where xresolution, yresolution are floating-point numbers separated by a single comma. There should be no spaces between the comma and xresolution. If no values are specified, values of 100.0 are used, except in the case where no units are specified, in which case values of 1.0 are used.

The default image size and pixel aspect ratio are set through the configuration file as follows:

sgif

This display driver writes Silicon Graphics, Inc., image files. It supports three or four channel files (mode "rgb", or "rgba") with 8 or 16 bit per channel depth. The files produced can be read by programs using the SGI "img" library or SGI "img" utility programs like "ipaste" and "izoom".

alias

This driver produces an output file containing RGB information. In addition, the driver will interpret the alpha channel by writing a separate 8-bit Alias Matte output file, and will handle z data by writing a separate 32-bit Alias or Composer depth file. Thus, the driver can handle "z", "rgb", "rgba", or "rgbaz" images. The alias driver creates a file whose name is specified in the RiDisplay call. The Matte file, if any, will have the additional suffix .mask, and the Depth file will have the additional suffix .depth.

When writing depth data, the driver will by default write Alias depth files. This behaviour can be changed with an additional parameter, "zformat", which can be either "composer" or "alias".

targa

This driver supports Truevision, Inc. of file type 2, which is an uncompressed RGB or RGBA image (selected with RiDisplay modes "rgb" or "rgba").

The targa driver allows images to be merged over an existing TGA file. This option is selected by using the "merge" parameter to RiDisplay. If this option is selected, the existing file must have the same name as that specified with RiDisplay and it must be of the same x and y dimensions and file type.

cineon

This driver produces an output file in Kodak's Cineon image file format. It can be used to store RGB images in a 10-bit-per-channel, logarithmic encoding, as preferred by Kodak's Cineon software suite.

The cineon driver creates a file whose name is specified in the RiDisplay call. It accepts pixel data in either 8- or 16-bit-per-channel quantized integer format, or 32-bit floating-point format. These values are companded by the driver to 10-bit log, for optimal registration with film's recordable color range. Because 10-bit log can encode and store colors which are "brighter than white", use of full floating-point (unquantized) RGB output is recommended for best use of the format's capabilities. The format only supports RGB image files (mode "rgb"), and any alpha channel supplied by the renderer is ignored.

The cineon driver also has special configuration options to control the log codes which are used to compand the data which is written into the output file. These may be set from the RiDisplay parameter list or through the configuration file.

The Cineon companding equation be controlled by adding the parameter "setpoints" to the RiDisplay parameter list. The parameter takes an array of two integers, which represent the 10-bit code used to represent 1% Black, and the 10-bit code used to represent 90% White (see Kodak's Cineon documentation for explanations of these values). The default values for these setpoint codes can be set by adding the following line to the rendermn.ini configuration file:

where black and white are integer values separated by a single comma. There should be no spaces between the comma and white. If no values are specified, the standard default values of 180,685 are used.

softimage

This display device driver produces an output file in the Softimage Picture File Format. The driver supports 8-bit "rgb" or "rgba" images, with or without RLE compression.

The softimage driver has one configuration option to determine whether the output undergoes run length encoding compression. This can be controlled by setting the parameter "compression" in the RiDisplay parameter list. The parameter takes the value of "rle" or "none", to enable or disable compression, respectively. The default setting is "rle".

mayaiff

This driver produces an output file in the Maya Image File Format. The driver can generate 8-bit or 16-bit RGB along with an optional 8-bit or 16-bit Alpha channel and optional 32-bit Z data; thus, this driver supports the "rgb", "rgba", "rgbz", and "rgbaz" display modes.

shadow

This display driver which produces an output file containing depth (mode "z") information in the shadow map texture file format, which is a proprietary format peculiar to PhotoRealistic RenderMan. The shadow map texture format is accepted by the renderer for use in light shaders which produce shadows via the shadow() shadeop.

The shadow driver has two configuration options. The "minmax" parameter can be set to a value of 1 to indicate that the generated shadow should be a minmax shadow map, suitable for use in soft shadow generation. By default this option is disabled (has a value of 0). The "format" parameter can be set to a value of "tiff" or "pixar" to indicate the format of the output texture map; it defaults to the value specified for /prman/textureformat in rendermn.ini.

zfile

Zfile is a PhotoRealistic RenderMan display driver which produces an output file containing depth (mode "z") information. The zfile format is accepted by the renderer and the txmake utility program as the depth image required to make a shadow texture map.

The file format is peculiar to PhotoRealistic RenderMan. It has the following form:

deepshad

Deepshad is a PhotoRealistic RenderMan display driver which produces "deep shadow maps", which store more information per pixel than a normal shadowmap. These files are stored in a proprietary format peculiar to PhotoRealistic RenderMan. The deep shadow map texture format is accepted by the renderer for use in light shaders which produce shadows via the shadow() shadeop.

This display driver works only as a secondary display (similar to extra-output variables), which means a primary display must be used as well. For example, in RIB,

will generate a deep shadow file out.dshad (as well as a zfile out.zfile). Like depth displays, deep shadows require 'PixelFilter "box" 1 1'.

One display mode is currently available for deep shadow output: "deepopacity" indicates that the given file contains deep shadow transparency information.

The deep shadow driver accepts one configuration parameter: "volumeinterpretation". This parameter may take one of two uniform string values, "discrete" and "continuous". If set to "discrete", the display driver will faithfully emit all samples - this is useful in preserving the discontinuous nature of scenes where the depth samples are further apart. When set to "continuous" the display driver will instead interpolate through the middle of discontinuous samples; this optimizes the output but should be used only when reproducing a generally smooth depth function (such as that caused by a volume of fog, or a dense stack of hair). By default this parameter is set to "discrete".

openexr

When using this display driver for rgba or Z output, you should turn rgba and Z quantization off by using a floating point Quantize statement, ie:

This display driver also supports the output of image channels other than rgba using the Arbitrary Output Variable mechanisms.

Renderman output variable name	image channel name	type
"r"	"R"	preferred type
"g"	"G"	preferred type
"b"	"B"	preferred type
"a"	"A"	preferred type
"z"	"Z"	FLOAT
other	same as output variable name	preferred type

By default, the "preferred" channel type is the value specified for /display/openexr/type in rendermn.ini, which can be either "half" (16-bit) or "float" (32-bit). If not specified therein, it defaults to "float". The preferred type can be changed by adding an "exrpixeltype" or "type" argument to the Display command in the RIB file. For example:

The default compression method for the image's pixel data is the value specified for /display/openexr/compression in rendermn.ini, which may take the value of "rle", "zip", or "piz"; if not specified therein it defaults to "zip". You can select a different compression method by adding an "exrcompression" argument or simply the "compression" argument to the Display command. For example:

texture

This display driver produces an output file which will be accepted directly by the renderer for use in the texture() shadeop. The image will either be in TIFF format or in Pixar's mipmapped texture file format, which is a proprietary format peculiar to PhotoRealistic RenderMan. 8-, 16-, and 32- bit (floating point) image output is supported. Images rendered using this display driver must have power of two dimensions - no attempt will be made to resize the image when using this driver.

The texture driver supports several configuration options. The "pattern" parameter can be set to a value of "none", "diagonal", or "all" in order to control the mipmapping mode; the default is "diagonal". The "smode" and "tmode" parameters control the wrap modes of the texture and accept the values "black", "clamp", or "periodic"; the default is "black". The "format" parameter can be set to a value of "tiff" or "pixar" to indicate the format of the output texture map; it defaults to the value specified for /prman/textureformat in rendermn.ini.

Note that for proper 16 bit output, one must use Quantize 32767 0 32767 0, and not the usual Quantize 65535 0 65535 0. This is because PRMan's system currently expects signed, not unsigned shorts.

pointcloud

The pointcloud driver is the default geometry driver used by bake3d(); it cannot be selected as a display driver for RiDisplay. This is the only format currently supported as an input format to brickmake and RiBrickMake. Documentation on this format can be found in the appnote "Baking 3D Textures: Point Clouds and Brick Maps".

When rendering using netrender, grids that overlap bucket boundaries can get shaded more than once. If the grids have shaders that call bake3d(), baked points from those grids will be sent to the display driver multiple times. For some uses of point clouds the extra points won't matter, but for other uses (e.g. subsurface scattering) they do matter. In such cases, the duplicate grid points can be eliminated in the display driver by setting the parameter "EliminateDuplicateGrids" to 1 on a DisplayChannel line. (The default is 0.) Here is an example of the syntax:

rib

The rib driver is a geometry driver that can be used by bake3d(); it cannot be selected as a display driver for RiDisplay. The rib driver is selected by using the parameters "driver" "rib" in bake3d(). This driver creates RIB files containing PRMan grids represented as RiPoints, RiCurves, or RiPointsPolygons. Point, normal, and all other variables specified as name/value pairs to bake3d() will be emitted as geometry vector information.

wavefrontobj

The wavefrontobj driver is a geometry driver that can be used by bake3d(); it cannot be selected as a display driver for RiDisplay. This driver creates files in the Wavefront .obj format, containing PRMan grids represented as points, lines, or faces. Due to restrictions in this format, only geometric point, normal, and texture coordinates (only if s, t are in the bake3d() optional data list) will be emitted; no other information (including any optional bake3d() name/value pairs other than s, t) are supported.