Keywords: main

Next: 1.28 Pixel Coverage Up: 1. Functionality Previous: 1.26 Color Calculations

# 1.27 Output Shaders

mental ray can generate more than one type of image. There are up to five main frame buffers: for RGBA, depth, normal vectors, motion vectors, and labels. The depth, normal vector, motion vector, and label frame buffers store the Z coordinate, the normal vector, the motion vector, and the label of the frontmost object at each sample of the image. If multiple samples are taken for a pixel, the frame buffer value for that pixel may be either any one sample value, or a blend of all samples. The number and type of frame buffers to be rendered is controlled by `output` statements. Output statements specify what is to be done with each frame buffer. If a frame buffer is not listed by any output statement, it is not rendered (except for RGBA, which always exists). There are two types of output statements, those specifying output shaders and those specifying files to write.

There are also up to eight user-defined frame buffers that can be defined with any data type, using a frame buffer statement in the options block.

Output shaders are user-written functions that can be linked at runtime that have access to every pixel in all available frame buffers after rendering. They can be used to perform operations like post-filtering or compositing.

Files to write are specified with data type, file format and file name. If the data type is omitted a default data type is used that is assumed to be the ``best'' type for the given image format. This default type is marked ``#'' in the table below. The data type implies the frame buffer type. There are special file formats for depth, vector, and label files, in addition to a variety of standard color file formats. By listing the appropriate number and type of output statements, it is possible to write multiple files. For example, both a filtered file and the unfiltered version can be written to separate files by listing three output statements: one to write the unfiltered image, one that runs an output shader that does the filtering, and finally another one to write the filtered image. Output statements are executed in sequence.

The following file formats are supported:

format | type | compress | description
rla | rgba | RLE | 8-bit or 16-bit Utah/Wavefront color, type A
rlb | rgba | RLE | Utah/Wavefront color, type B
pic | rgba | RLE | Softimage color
Zpic | z | -- | Softimage depth map (write only)
alias | rgb | RLE | Alias color
rgb | rgba | RLE | Silicon Graphics 8-bit RGBA color
| rgb | RLE | Silicon Graphics 8-bit RGB color
| rgba_16 | RLE | Silicon Graphics 16-bit RGBA color
| rgb_16 | RLE | Silicon Graphics 16-bit RGB color
jpg | rgb | JPEG | JFIF picture
tif | rgba | RLE | 8-bit RGBA TIFF
| rgba_16 | RLE | 16-bit RGBA TIFF
| rgb | RLE | 8-bit RGB TIFF
| rgb_16 | RLE | 16-bit RGB TIFF
tifu | rgba | -- | 8-bit RGBA TIFF
| rgba_16 | -- | 16-bit RGBA TIFF
| rgba_fp | -- | floating-point RGBA TIFF3.x
| rgb | -- | 8-bit RGB TIFF
| rgb_16 | -- | 16-bit RGB TIFF
| rgb_fp | -- | floating-point RGB TIFF3.x
iff | rgb | RLE | Alias|Wavefront Maya 8-bit RGB image3.1
| rgba | RLE | Alias|Wavefront Maya 8-bit RGBA image3.1
| rgb_16 | RLE | Alias|Wavefront Maya 16-bit RGB image3.1
| rgba_16 | RLE | Alias|Wavefront Maya 16-bit RGBA image3.1
picture | rgb | RLE | Dassault Systèmes CATIA PICTURE
hdr | rgbe | -- | Radiance high dynamic range color, 8-bit RGB color3.1
ppm | rgb | -- | Portable pixmap, 8-bit P6 binary
tga | rgba | -- | Targa color
bmp | rgb | RLE | MS Windows and OS/2 color
qntpal | rgb | YUV | Abekas/Quantel, PAL (720`x`576)
qntntsc | rgb | YUV | Abekas/Quantel, NTSC (720`x`486)
ct | rgba | -- | mental images 8-bit color (3)
| rgba_16 | -- | mental images 16-bit color (6)
| rgba_fp | -- | mental images floating-point color (11)
st | a | -- | mental images 8-bit alpha (4)
| a_16 | -- | mental images 16-bit alpha (7)
| a_fp | -- | mental images floating-point alpha3.1(15)
vt | vta | -- | mental images alpha basis vectors (5)
wt | vts | -- | mental images intensity basis vectors (5)
zt | z | -- | mental images depth map (8)
nt | n | -- | mental images normal-vector map (9)
mt | m | -- | mental images motion-vector map (12)
tt | tag | -- | mental images normal-vector map (10)
bit | bit | -- | mental images mask bitmap (13)
ht | rgbe | -- | mental images high dynamic range color, 8-bit RGB color3.1 (14)
map | any | -- | mental images memory map
null | -- | -- | null, deleted on close, write only

Each of these file formats implies a particular default data type (the first entry in column ``Supported data types''); for example, `"jpg"` implies 8-bit RGB, and `"zt"` implies Z. The default data type may be overridden by explicitly specifying another data type, such as a 16-bit type, in the output statement, as long as it is supported and appears in the above table. mental ray will adjust its frame buffer list to compute the requested types. For example, the standard RGBA frame buffer stores 8 bits per component by default, but if any output statement references a 16-bit type, the RGBA frame buffer also switches to 16 bits.

The RGBE high dynamic range color data type3.1 can store RGB data whose components may exceed the value of 1.0, which is the normal limit for standard RGB data. There are two specialized file formats (HDR and HT) for RGBE, but mental ray will also allow storing RGBE data in any 8-bit RGBA format, such as SGI RGB. This will result in images that cannot be displayed by standard viewing programs because they would interpret the data as RGBA, but it has become common practice to use such formats to transport RGBE data to other tools that understand RGBE.

The available data types are:

type | comp | bpc | contents
`rgba` | 4 | 8 | RGBA color
`rgba_16` | 4 | 16 | RGBA color (16 bits per component)
`rgba_fp` | 4 | 32 | RGBA color (floating-point)
`rgb` | 3 | 8 | RGB color
`rgb_16` | 3 | 16 | RGB color (16 bits per component)
`rgb_fp` | 3 | 32 | RGB color (floating-point)3.x
`rgbe` | 4 | 8 | high dynamic range RGB color
`a` | 1 | 8 | Alpha channel
`a_16` | 1 | 16 | Alpha channel (16 bits per component)
`a_fp` | 1 | 32 | Alpha channel (floating-point)3.1
`s` | 1 | 8 | synonymous with `a`
`s_16` | 1 | 16 | synonymous with `a_16`
`s_fp` | 1 | 32 | synonymous with `a_fp`3.1
`z` | 1 | 32 | depth channel
`n` | 3 | 32 | normal vectors
`m` | 3 | 32 | motion vectors
`tag` | 1 | 32 | label channel
`vta` | 2 | 16 | UV vector texture
`vts` | 2 | 16 | synonymous with `vta`
`bit` | 1 | 1 | bitmask channel
`coverage` | 1 | 32 | coverage of most important object3.x

The difference between `"vta"` and `"vts"`, and between `n` and `m`, is significant only when automatic conversions are done. The file contents are identical except for the magic number in the file header.

The floating-point RGBA data type `"rgba_fp"` allows color and alpha values outside the normal range (0,...1), and no dithering is applied even if explicitly enabled. In contrast, any conversion to the 8-bit or 16-bit formats will clamp values outside this interval. Note that dithering reduces the effectivity of RLE compression.

All mental images file formats contain a header followed by simple uncompressed image data, pixel by pixel beginning in the lower left corner. Each pixel consists of one to four 8-bit, 16-bit, or 32-bit component values, in RGBA, XYZ, or UV order. The header consists of a magic number byte identifying the format, a null byte, width and height as unsigned shorts, and two unused null bytes reserved for future use. All shorts, integers, and floats are big-endian (most significant byte first).

mental ray can combine samples within a pixel in different ways. The combination of existing samples can also pad the frame buffers to ``bridge'' unsampled pixels. Interpolation of colors, depths, normals, and motion vectors means that they are averaged, while interpolation of the labels means that the maximum label is used (taking the average label is not a good idea). Interpolation of depths only takes the average of non-infinite depths, and interpolation of normals and motion vectors only takes the average of vectors different from the null vector. Interpolation is turned on by writing a ``+'' in the beginning of the output type and turned off by writing a ``-'' there. For example, to interpolate the depth samples, write ```+z`'' in the output statement:

type | meaning
`-rgba` | last color
`+rgba` | average color
`-z` | lowest depth
`+z` | average depth, excluding infinite depths
`-n` | last normal
`+n` | average normal, excluding null vectors
`-m` | last motion vector
`+m` | average motion vector, excluding null vectors
`-tag` | last label
`+tag` | maximum label

If interpolation is turned off for a frame buffer, the last sample value (color, normal, motion vector, or label) within each pixel is stored, and pixels without samples get a copy from one of the neighbor pixels. Interpolation off for depth images is an exception: rather than using the last sample depth, the min depth is used -- this can be useful for compositing. Interpolation is on by default for color frame buffers (including alpha and intensity frame buffers) and off by default for depth, normal, motion vector, and label frame buffers.

Next: 1.28 Pixel Coverage Up: 1. Functionality Previous: 1.26 Color Calculations