Cameras

    camera "name"  
        camera_statements  
    end camera

A camera describes a view of the scene,

including the list of files to write, the lens shaders to use, volume shaders to be used as the global atmosphere or fog, global environment shaders that control what happens to rays that leave the scene, and other parameters.

Cameras are scene entities that need to be placed in the scene with an instance element. In object space mode (see options element above), the location of the camera in world space is determined by the camera instance transformation. Note that the camera instance must be attached to the root instance group of the scene. See below for information on instance groups.

Frame buffers 3.6

Cameras contain buffer statement which lists named framebuffers, image files and properties associated to them.

    framebuffer "framebuffername"
        [datatype "datatype"]
        [filename "filename"]
        [filetype "filetype"]
        [filtering <bool>]
        [colorprofile "color profile"]
        [compression "compression"]
        [quality "quality"]
        [dod <bool>]
        [dpi <int>]
        [primary <bool>]

If a filename is associated with a framebuffer, it would be written to that output file after all output shaders are applied. filtering specifies if the image filtering would be applied on the specified buffer. it corresponds to the "+" and "-" sign prepending the image type used in mental ray 3.5 and older versions. If specified, colorprofile would be applied to the image before writing it out.

The quality and compression properties can be used by the image format in order to choose compression type and factor.For the OpenEXR file forma the available compression modes are "none", "rle", "piz", "zip", and "pxr24". These mean no compression, run-length encoding, wavelet-based compression, Huffman dictionary compression, and an efficient but lossy (for floating-point data, which loses 8 of 32 bits) rounding method, respectively. The fastest ones are normally RLE or ZIP; PIZ usually achieves better compression but is much slower; if there are many very large textures a scene can render much slower. The OpenEXR manual recommends PXR24 for depth maps. mental ray 3.3 and earlier always use ZIP compression; mental ray 3.4 defaults to RLE.

The dod and dpi are passed to the image callback to allow storing them to the image file for image file formats which support them.

The primary flags marks the default color framebuffer. This flag may be set on a single framebuffer only. If the framebuffer syntax is used, the separate declaration of user framebuffers in the options block is not required.

Output Statements

Cameras contain output statements that specify output shaders and output files to write to disk, and control which frame buffers mental ray creates and maintains during rendering. More than one output file can be created, and output shaders such as filters can be listed that operate on the final rendered image, before it is written to a picture file. outputs is one or more output statements. Output statements are very similar to shader lists, like lens shader statements, but the syntax is different to allow type specifications and output file names:

    output "datatype" "shader_name" ( parameters )
    output [colorprofile "profile_name"] ["datatype"] "filetype" [options] "filename"

The first kind of 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. Interpolation is averaging for color, depth, and normal images and max'ing for label images. Interpolation 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 mental ray 3.5 and earlier versions, the order of all framebuffer declarations was significant. In mental ray 3.6, all output shaders are applied before any of the images is written out to disk.

The second kind of output statements is kept for compatibility with mental ray 3.5 and earlier versions. The framebuffer interface described above provides a more powerful mechanism. The 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 "rgb", which stands for a SGI RGBA image file, implies the data type "rgba". 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.

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"^3.1 that stores high dynamic range RGBE data is normally used for formats that understand RGBE data ( "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, like 4000x4000, compared to floating-point frame buffers which are four times as large. Note that RGBE stores no alpha. In version 3.4 of mental ray, frame buffers are stored in frame buffer files on disk to allow arbitrary frame buffer sizes and arbitrary numbers of frame buffers.

The data types "fb0" through "fb7" refer to user frame buffers 0...7. The limitation to eight frame buffers has been removed in mental ray 3.4. 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 contoursh on page contoursh for details and examples.

Multipass Rendering Statements^3.1

Multipass 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 multipass 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.

All multipass rendering functionality is controlled by a script in the camera definition, consisting of five types of 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.

pass null

Deletes all pass statements defined in the camera. This is useful for incremental changes. It is executed at parsing time, when the scene is defined.

pass

Saves the current sample rectangle to the named file. The current rectangle is initially the rendered rectangle, but it is updated every time a merge shader has run. It is executed every time a rectangle has finished rendering.

pass merge

Merges two or more sample files into the current sample rectangle buffer, and optionally writes the result to another file. If other sample files should be merged with the current rendering result, it is not necessary to first write the rendered samples to a file and then to name that file in the pass merge statement; instead, an empty filename string ( "") can be used to reference the rendered samples. If the merging function is omitted, mental ray uses a built-in default that supports depth and alpha blending of the main color frame buffer. The pass merge statement is executed every time a rectangle has finished rendering.

pass prep

Preprocesses a single pass file, and writes the result to another pass file. The function has random access to all samples in the input and output file. It is called only once before rendering begins.

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 page renderpass for more information on multipass rendering.

Other Camera Statements

There is a variety of camera_statements that can be listed in the camera. Some of them can be overridden by specifying an appropriate command-line option; see Appendix cmdline.

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:

focal distance | infinity

The focal distance is set to distance. The focal distance is the distance from the camera to the viewing plane. The viewing plane is the plane that the rendered scene is projected onto; its edges correspond to the edges of the rendered image. A common approach is to set the focal distance to the middle distance of the interesting objects in the scene and then set the aperture such that it is a bit larger than the horizontal extent of the objects in camera space. If infinity is used in place of the distance, an orthographic view is rendered. An orthographic view turns off perspective, all camera rays are parallel. View-dependent surface tessellation is not possible in orthogonal mode.

aperture aperture

The aperture is the width of the viewing plane. The height of the viewing plane is aperture divided by aspect. Together with the focal and aspect viewdefs, aperture defines the lens of the standard pinhole camera.

aspect aspect

This is the aspect ratio of the camera. The default is 1.33. In camera space, aperture is the width of the viewing plane and aperture divided by aspect is the height. The viewing plane is divided into pixels as specified by the resolution viewdef, so the aspect will result in nonsquare pixels if it is not equal to the X resolution divided by the Y resolution. For example, to render a PAL image at a resolution of

pixels, at an image ratio of 3:4 as defined by the PAL standard, pixels are slightly wider than tall, by a factor of

. If the aspect ratio is corrected by this number, objects will appear undistorted on a PAL video display (but not on a computer display with square pixels).

resolution x_int y_int

Specifies the width and height of the output image in pixels.

offset x y

Specifies an offset for the rendered image. The default is 0.0 for both values, which means that the image will be centered on the camera's Z axis. Positive values translate the image up and to the right. The offset is measured in pixel units.

window x_low_int y_low_int x_high_int y_high_int

Only the sub-rectangle of the image specified by the four bounds will be rendered. All pixels that fall outside the rectangle will be left black.

clip hither yon

The hither (near) and yon (far) planes are planes parallel to the viewing plane that delimit the rendered scene. This is done to keep the scanline projection transformation stable; it does not affect raytracing. Points outside the space between the hither and yon planes will not be rendered (this does not apply to the infinite-radius environment maps because they are not geometric objects). The clip statement specifies the distance of the hither and yon planes from the camera. The defaults are 0.0001 for the hither distance and 1000000.0 for the yon plane.

volume [ shader_list]

This statement specifies volume (atmosphere) shaders. The atmosphere affects all rays passing through the space outside objects by attenuating the color of the ray. It is possible to specify a volume shader for the inside of objects too, by naming a volume shader in the material statement (see above). If no shader_list is specified, the existing volume shader list is deleted; this is useful in incremental changes. If a list is given, it replaces the current list if this is the first volume statement in the camera block, or it is appended to the current list otherwise.

environment [ shader_list]

This statement specifies environment shaders. Environment shaders control the color returned by primary rays that, after leaving the camera, never strike any object in the scene. They are similar to environment shaders named in materials, which control reflection rays cast by the material shader that leave the scene without striking another object (or exceeding the trace depth). If no shader_list is specified, the existing volume shader list is deleted; this is useful for incremental changes. If a list is given, it replaces the current list if this is the first volume statement in the camera block, or it is appended to the current list otherwise.

lens [ shader_list]

Lens shaders simulate lenses by changing the camera. If no lens shader is present, the camera is a pinhole camera that casts rays from the origin in all directions that strike the viewing plane, or an orthographic camera that casts parallel rays if focal infinity is specified. A lens shader accepts the origin and direction of the camera ray, modifies them, and casts a new primary ray. Examples for lens shaders includes fish-eye lenses that exaggerate the direction vector in a nonlinear way (there is a code example in the Shader section). Multiple lenses can be specified in the camera; the n-th lens shader receives the origin and direction computed by the n-1st lens shader. If no shader_list is specified, the existing volume shader list is deleted; this is useful in incremental changes. If a list is given, it replaces the current list if this is the first volume statement in the camera block, or it is appended to the current list otherwise.

frame frame_int [ time ] [ field field_int ]

Every camera should contain the current frame number frame. The time in seconds can optionally be specified as time. Optionally, a field number field can be specified; by convention, field should be 0 when rendering frames, 1 when rendering the first (odd) field, and 2 when rendering the second (even) field. If the field modifier is missing, the field number defaults to 0. mental ray currently does not use any of these values but makes them available to shaders.

data "data_name"| null

This statement attaches user data to the camera. The argument must be the name of a previously defined data element in the scene file. If null is specified instead of a data element name, a previously existing data reference is removed.

Cameras

Frame buffers 3.6

Output Statements

Multipass Rendering Statements3.1

Other Camera Statements

Multipass Rendering Statements^3.1