camera "name"
[frame_buffers]
[output_statements]
[pass_statements]
[camera_parameters]
end camera
A camera provides parameters to describe how to project and map a view of the scene to the final 2D image (or film). It can be used to specify optional frame buffers and output statements or pass statements for further manipulations of samples or pixels with the help of custom shaders.
A camera is always fixed at the origin, looking down the negative Z axis, with up being the positive Y axis, in its own coordinate space called camera space. A camera can be placed anywhere in world space using an instance transformation, in the same way that objects are placed anywhere in world space. (For backwards compatibility with previous mental ray versions, there is also a mode where camera space and world space are always identical.) Note, that the camera instance must be attached to the root instance group of the scene.
Cameras can contain frame_buffers which list named frame buffers and various properties associated to them, like an image file name. Such statements is basically a request for creation of a frame buffer with a specific data type in mental ray. Further optional attributes control advanced properties of the buffer, like mark it for output to an image file with certain options, which is performed by mental ray after rendering and output shading has finished.
The frame_buffers section may provide any number of the following statements:
framebuffer "name"
[ datatype "datatype" ]
[ filtering <bool> ]
[ filename "filename" ]
[ filetype "filetype" ]
[ compression "compression" ]
[ quality "quality" ]
[ colorprofile "color profile" ]
[ dod <bool> ]
[ dpi <int> ]
[ field "fieldname" ]
[ primary <bool> ]
[ user <bool> ]
[ useopacity <bool> ]
The name of a frame buffer can be
arbitrary. It is used for any further references in the scene
description. Any following framebuffer statement that
is using the same name will refer to the same frame buffer, and may
be used to incrementally change its properties.
datatypefiltering"+" or "-" prefix of the data type string
in old-style file output
statements.filenamefiletype enforces a
certain image format to be used. If specified,
colorprofile would be applied to the image before
writing it out. If multiple buffers of different data type specify
the same output file in a multi-channel format then a single file
will be written with multiple channels.compression"none",
"rle", "piz", "zip", and
"pxr24", see OpenEXR Compression for
details.quality1…100. A value of 0
selects the built-in default. This is currently only supported for
writing in the JFIF/JPEG file format.doddpifieldprimaryuseron. They will not be filled by mental ray. However,
they can be enabled for image file output like the standard
buffers. Such buffers are typically required for custom shader
solutions, like intermediate buffers for compositing operations in
output shader. A
user buffer with a unique name will always be created
and not be considered for sharing optimizations like
standard buffers.useopacityBy default, if the related attributes have not been given, a
frame buffer is of datatype "rgba" with filtering
on, is not primary nor user, and has neither
filetype nor filename set (is not written to
file).
The frame buffers maintained in mental ray are separated into standard and user buffers, controlled by the optional user attribute. Note, that standard frame buffers of the same or easily convertible data type but with different name may actually point to the same internal buffer, to optimize memory usage at the cost of a small runtime conversion overhead. Like, requesting both a floating-point and 8bit color frame buffer which are not marked as user will create a single floating-point color buffer only, and convert the pixel data to 8 bits on demand, for example if requested for file output.
Here are some examples for common cases of frame buffer usage:
framebuffer "main"
datatype "rgba"
filetype "tif"
filename "output.tif"
framebuffer "depth"
datatype "z"
Request a standard color buffer with alpha channel of 8 bits per component and the standard z-depth buffer. Both buffers will be filled by mental ray, and the color buffer will be written to an image file of format TIFF.
framebuffer "main"
datatype "rgba"
filetype "exr"
filename "output.exr"
framebuffer "depth"
datatype "z"
filetype "exr"
filename "output.exr"
Request a standard color buffer with alpha channel of 8 bits per component and the standard z-depth buffer. Both buffers will be filled by mental ray, and written as multiple channels into the same output file of format OpenEXR.
framebuffer "main"
datatype "rgba_16"
filetype "tif"
filename "output.tif"
framebuffer "second"
datatype "rgba_fp"
framebuffer "third"
datatype "rgb"
filetype "jpg"
filename "output.jpg"
quality 20
Request a standard color buffer with alpha channel in 16 bits per component, a second one with colors stored in floating-point precision, and a third 8 bit buffer without alpha channel. Write the final image as a TIFF file with 16 bit precision, and a JFIF/JPEG image file with poor quality in 8 bit precision and its native data type without alpha. mental ray may actually keep only one floating-point color frame buffer to fulfill this request.
framebuffer "main"
datatype "rgba"
filetype "tif"
filename "output.tif"
framebuffer "comp"
datatype "rgba"
filetype "tif"
filename "composit.tif"
user on
output "composit_buffers" ("main", "comp")
Request a standard color buffer and a user color buffer of matching data type. The main buffer will be rendered by mental ray. A custom output shader composit_buffers will be called after rendering, to read from the main and write to the comp color buffer. At the end, both the main and the comp buffers will be written to separate image files in TIFF format by mental ray.
Cameras contain output_statements which specify output shader calls, or, in backwards compatible mode of mental ray, define file output to write images to disk.
The following output_statements are supported:
output "shader_name" ( parameters )
This output statement calls an output shader, such as a filter, that may operate on all available frame buffers. The actual buffers to work on may be supplied as parameters, or the shader may automatically detect available frame buffers by name or type. The output shaders are called after rendering has finished but before the marked frame buffers get written to image files by mental ray. All output shaders are called in a sequence, in the exact same order as listed in the camera.
The following output statements are supported for compatibility with earlier versions of mental ray. New applications should use the named frame buffers instead.
output ["datatype"] "shader_name" ( parameters ) output [colorprofile "profile_name"] ["datatype"] "filetype" [options] "filename"
Deprecated The first output statement calls an output shader, such as a filter, that may operate on all available frame buffers. Here, the datatype may be a comma-separated list of types if the shader requires multiple frame buffers. Each type can be prefixed with a "+" or "-" to turn interpolation on or off, which is on by default for the standard color frame buffer and off by default for all others. For example, a shader that filters the standard RGBA image with a filter whose size depends on the distance of objects needs both the interpolated RGBA buffer and the interpolated depth buffer, and would have a data type "rgba,+z". In previous versions of mental ray, the order of all frame buffer declarations was significant. In mental ray , all output shaders are applied before any of the images is written out to disk.
Deprecated The second kind of output statement writes an image to a file named filename, using the file format filetype. Normally, file formats imply a data type, but the defaults can be overridden by naming an explicit datatype. For example, the file type "tif", which stands for a TIFF color image file format, implies the data type "rgba". The data type controls which type of frame buffers mental ray actually creates and maintains during rendering. The optional colorprofile may be used to transform results stored in the color frame buffer to a desired color space before they are written to the output file. This option may only be used if a render color profile had been specified in the options block. Any number of output files can be created, but just the first one can be overridden from the command line of a standalone mental ray.
Deprecated The options specify additional format related parameters. Currently, the "jpg" file format supports one option quality q, where q is an integer value between 0 and 100. Lower values force higher lossy compression resulting in lower image quality. A quality value of 0 will cause the use of the default quality 75. For Softimage "pic" file formats, the options keywords even and odd are available to set the corresponding fields in the file header.
The data type "rgbe" which stores high dynamic range data is normally used for formats that support RGBE data natively ("hdr" or "cth"), but it can also be stored in any format that accepts 8-bit RGBA. This will result in image files that cannot be displayed with standard viewers, but tools exist that can process such data. For example, the following output statement will store RGBE data in an RLA file:
output "+rgbe" "rla" "file1.rla"
Unless there is also a true floating-point buffer ("rgba_fp"), specification of the "rgbe" type will switch mental ray's color frame buffer to RGBE mode because its high dynamic range is considered a superset of regular RGB. This can significantly reduce memory usage for large frame buffers, compared to floating-point frame buffers which are four times as large. Note that RGBE stores no alpha. By default, frame buffers are stored in frame buffer files on disk to allow arbitrary frame buffer sizes and arbitrary numbers of frame buffers.
Deprecated The data types "fb0" through "fbN" refer to user frame buffers 0...N. These user frame buffers are defined in the options statement using frame buffer statements. The actual data type of fb n is the type of frame buffer n. For example, the output statements
output "+rgba" "rgb" "file1.rgb" output "fb0" "ctfp" "file2.ct"
write the standard frame buffer to the image file file1.rgb, and then write the contents of user frame buffer 0 to the image file file2.ct. This assumes that the options block contains a statement that defines user frame buffer 0, such as:
frame buffer 0 "+rgba_fp"
User frame buffers are empty unless some shader writes to them during rendering. Their purpose is to collect nonstandard image data during rendering, and to make the data available for output shading and image file writing.
A special data type "contour" can be specified that enables contour rendering. Special contour output shaders must be specified that pick up the contour information from the contour cell frame buffer and compute a color image, which it can either put into the regular color frame buffer, or composite on top of the color frame buffer. In the latter case, one rendering phase creates a color image with contours. The color frame buffer can then be written to an image file using a regular image output statement. There is also a built-in contour output shader that creates a PostScript file instead of a color image; see section contours for details and examples.
Pass rendering is a feature set that allows saving
the results of rendering not in the form of image files, but in the
form of sample lists. A sample is the result of a single primary
eye ray, including all collected frame buffer information. Oversampling
creates more than one sample per pixel, which are filtered to
compute the pixel. Since pass rendering operates on samples, it has
access to the complete set of subpixel information, and does not
suffer from pixel aliasing problems as image compositing does.
mental ray also supports merging of multiple pass file, sample by
sample, to generate the final filtered output images. Finally,
mental ray supports pass preprocessing, which is a function with
random access to a single pass file to perform operations such as
subpixel motion blur postprocessing.
The pass rendering functionality is controlled by the following pass_statements:
pass null
pass [ "types" ] write "filename"
pass merge [ "types" ]
read [ "filename ", "filename", ... ]
[ write "filename" ]
[ function ( parameters ) ]
pass prep [ "types" ]
read "filename"
write "filename"
function ( parameters )
pass delete "filename"
Pass statement lists are similar to output statement lists, which also allow storing and processing data in order.
The execution order of statements is important. Before rendering, all pass prep statements are executed in order; during rendering all pass and pass merge statements are executed in order for every finished rectangle; and after rendering all pass delete statements are executed. It is important to note that pass and pass merge statements are executed for every finished rectangle; this allows mental ray to minimize memory usage because only small sets of samples reside in memory at any one time. It also means that a pass prep statement cannot operate on the currently rendered pass because the pass prep function runs before rendering begins. In general, no two pass or pass merge statements should write to the same filename; this would result in sample data loss because of the per-rectangle interleaving.
All files are created before reading begins; hence, a pass prep statement should not read from a file written to during rendering, and the write filename should not be identical to any read filenames in any statement. In general, all filenames written to should be unique. The pass delete statement was provided to clean up temporary pass files after rendering. Pass files can become quite large, often in the hundreds of megabytes if the resolution, oversampling parameters, and the number and size of frame buffers is large. Note that only mental ray 3.2 and later compress pass files.
The types string controls which frame buffer are written to the pass file. Types apply to the write statement only. The syntax is the same as for output and frame buffer statements, such as +rgba_fp,z". The default is the set of frame buffers defined by the output statement. Note that the main RGBA frame buffer is always written as floating-point RGBA, and that a depth (Z) frame buffer is always present, regardless of the type specification.
See also page pass rendering for more information.
There is a variety of camera_parameters that can be listed in the camera. Some of them can be overridden for a standalone mental ray by specifying an appropriate command line option.
There are four camera statements that accept shader lists: output, lens, volume, and environment. As with all types of shaders, more than one shader can be listed, or more than one such statement can be given, to attach multiple shaders (or output files in the case of the output statement) to each type. In an incremental change (the incremental keyword is used before the camera keyword), each of the four first resets the list from the previous incremental change and does not add to the existing list, as multiple statements inside the same camera ... end camera block would.
The following camera_statements are supported:
Copyright © 1986-2010 by mental images GmbH