Output Shaders

Output shaders are user-written functions to operate on frame buffers. They have access to every pixel in all available frame buffers after rendering, and can be used to perform operations like post-filtering or compositing.

Output Files

Writing frame buffers of a certain data type to files on disk is enabled by specifying a file format and output file name.

In framebuffer statements, adding the file properties to a buffer marks it to be written to the file. For multi-channel formats, the same file name may be given to several buffers to write them as multiple channels to the same file.

Deprecated In file output statements, if the data type is omitted and more than a single target data type is supported by a format, then a default data type is chosen that is assumed to be the "best" type for the given image format. This default type is underlined in the table below.

mental ray supports a variety of standard color file formats, as well as special file formats for depth, vector, and label files. By listing the appropriate number and type of framebuffer statements (or 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 multiple framebuffer statements (or output statements) : one to write the unfiltered image, one that runs an output shader that does the filtering into a secondary buffer, and finally another one to write the filtered image from that buffer. Output statements are executed in sequence.

The following file formats are natively supported for image output.

format type(s) compress description
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
png rgb RLE Portable Network Graphics 8-bit RGB color
rgba RLE Portable Network Graphics 8-bit RGBA color
exr a * OpenEXR 8-bit scalar
rgb * OpenEXR 8-bit RGB color
rgba * OpenEXR 8-bit RGBA color
a_h * OpenEXR 16-bit scalar
rgb_h * OpenEXR 16-bit RGB color
rgba_h * OpenEXR 16-bit RGBA color
a_fp * OpenEXR 32-bit scalar
rgb_fp * OpenEXR 32-bit RGB color
rgba_fp * OpenEXR 32-bit RGBA color
z * OpenEXR depth map
n * OpenEXR normal-vector map
m * OpenEXR motion-vector map
tif rgba RLE 8-bit RGBA TIFF
rgba_16 RLE 16-bit RGBA TIFF
rgba_fp RLE floating-point RGBA TIFF
rgb RLE 8-bit RGB TIFF
rgb_16 RLE 16-bit RGB TIFF
rgb_fp RLE floating-point RGB TIFF
tifu rgba - 8-bit RGBA TIFF
rgba_16 - 16-bit RGBA TIFF
rgba_fp - floating-point RGBA TIFF
rgb - 8-bit RGB TIFF
rgb_16 - 16-bit RGB TIFF
rgb_fp - floating-point RGB TIFF
iff rgb RLE Autodesk Maya 8-bit RGB image
rgba RLE Autodesk Maya 8-bit RGBA image
rgb_16 RLE Autodesk Maya 16-bit RGB image
rgba_16 RLE Autodesk Maya 16-bit RGBA image
rgba_fp RLE Autodesk Maya float RGBA image
a RLE Autodesk Maya 8-bit alpha
a_16 RLE Autodesk Maya 16-bit alpha
a_fp RLE Autodesk Maya floating-point alpha
z RLE Autodesk Maya depth map
rla rgba RLE 8-bit or 16-bit Utah/Wavefront color, type A
rlb rgba RLE Utah/Wavefront color, type B
picture rgb RLE Dassault Systèmes CATIA PICTURE
hdr rgbe - Radiance high dynamic range color, 8-bit RGB color
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 × 576)
qntntsc rgb YUV Abekas/Quantel, NTSC (720 × 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 alpha (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 label map (10)
bit bit - mental images mask bitmap (13)
cth rgbe - mental images HDR color, 8-bit RGB color (14)
map any - mental images memory map
null - - null, deleted on close, write only

The supported compression algorithms include :

RLE
a simple lossless run-length encoding, which achieves best compression ratios on images with larger areas of constant color without noise like drawings and graphical paint. This method is implemented slightly differently by various formats, like separate encoding per color component to increase the compression rate in IFF. The compression ratio may reach 2:1 for appropriate input.
JPEG3
a lossy perception-based compression technique with adjustable degree of compression. It is well suited for final storage and distribution of photographic and photorealistic images with smooth variations of color. It is not well suited for further edits like in a compositing pipeline. The compression ratio can easily reach 10:1 for appropriate input.
ZIP
a lossless Huffman dictionary encoding, which tend to give slightly better compression ratios than RLE for photographic imagery at the expense of runtime performance. The compression ratio is about 2:1 for appropriate input.
PIZ
a lossless compression based on wavelets coupled with Huffman encoding. This technique improves compression ratios especially for photographic imagery with film grain to about 3:1.

The OpenEXR 1 implementation in mental ray supports the compression modes: RLE, PIZ, ZIP, and, optionally, PXR24 2, a lossy compression method if the data is stored in full floating-point precision but lossless otherwise. The fastest algorithms are normally RLE and ZIP; PIZ usually achieves better compression but is much slower. The OpenEXR manual recommends PXR24 for depth maps. Note, that mental ray defaults to RLE, previous versions were using ZIP compression by default.


Each of the file formats implies a particular default data type (the entry underlined in column "supported data types"), like "jpg" implies the 8-bit RGB color type, and "zt" implies Z depth data. The data type may be overridden by explicitly specifying another data type, such as a 16-bit type, in the framebuffer statement (or output statement), as long as it is supported and appears in the above table.

The null file format is useful to create a stub file during rendering, that can be used to attach the imf_disp viewer, without leaving the file on disk when rendering finishes.

All mental ray native file formats, like ct or st, are following a simple layout. They contain a header followed by the image data, where

header
consists of a magic number byte identifying the format (as listed in table above), a null byte, width and height as unsigned shorts, as well as a version number as unsigned short ; and
image data
are simply uncompressed values written pixel by pixel (with increasing horizontal x coordinate) and line by line (with increasing vertical y coordinate), beginning in the lower left corner (x = y = 0). The pixel data consists of one to four 8-bit, 16-bit, or 32-bit component values, in RGBA, XYZ, or UV order. All shorts, integers, and floats are big-endian (most significant byte first).

The supported data types are:

type comp bpc contents
rgba 4 8 RGBA color
rgba_16 4 16 RGBA color (16 bits per component)
rgba_h 4 16 RGBA color (half floating-point)
rgba_fp 4 32 RGBA color (floating-point)
rgb 3 8 RGB color
rgb_16 3 16 RGB color (16 bits per component)
rgb_h 3 16 RGB color (half floating-point)
rgb_fp 3 32 RGB color (floating-point)
rgbe 4 8 high dynamic range RGB color
a 1 8 Alpha channel
a_16 1 16 Alpha channel (16 bits per component)
a_h 1 16 Alpha channel (half floating-point)
a_fp 1 32 Alpha channel (floating-point)
s 1 8 synonymous with a
s_16 1 16 synonymous with a_16
s_h 1 16 synonymous with a_h
s_fp 1 32 synonymous with a_fp
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 object

The half-float data types rgb_h, rgba_h, and a_h inform mental ray to store floating-point color values only with half-float precision in the frame buffer, thus reducing memory requirements at the cost of small details. Note, that only the OpenEXR image file format supports to store half-float data natively. The other file formats can be used as well but may fall back to store only the low dynamic range of the data, which means values outside the [0…1] range will be clamped.

The RGBE color data type can store high dynamic range color values with RGB components which exceed the value of 1.0, the normal upper limit for standard RGB data. There are two specialized file formats HDR and CTH for RGBE, but mental ray will also allow storing RGBE data in any other 8-bit RGBA format, such as TIFF. This will result in images that can not 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.

All the floating-point data types, like "rgba_fp" or a_fp, permit to store color and alpha values outside the normal range [0…1], often referred to as high dynamic range values. 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 tends to reduce the effectivity of RLE compression.

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.

mental ray can combine samples within a pixel in different ways, called filtering or interpolation. 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.

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 neighboring 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.

Interpolation is controlled with the framebuffer filtering property.

Deprecated In backwards compatible output statements, it 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

1 The distribution of OpenEXR requires the following copyright notice:

Copyright (c) 2002, Industrial Light & Magic, a division of Lucas Digital Ltd. LLC

All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

2 The distribution of the PXR24 compressor requires the following copyright notice:

Copyright (c) 2004, Pixar Animation Studios

All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

3 The JPEG software is based in part on the work of the Independent JPEG Group.

Copyright © 1986, 2012 NVIDIA Corporation