Frame

This table lists all state variables that remain unchanged for the duration of a frame.

type name content
int version shader interface version
miTag camera_inst tag of camera instance
miCamera * camera camera information
miOptions * options general rendering options
version
The version number of the interface and the state structure. Useful to check if the version is compatible with the shader. Version 2 stands for mental ray version 2.0 and later.
camera_inst
The camera instance is a data structure in the mental ray database that contains transformation information about the camera. Like all other tags in the state, a pointer to that data structure can be obtained by calling mi_db_access with the tag as the only argument. This function returns a void pointer to the accessed data structure. After the pointer is no longer used, the pointer must be "returned" by calling mi_db_unpin with it. Failure to do so will abort rendering.

The camera data structure pointed to by camera has the following fields. None of these may be written to from a shader.

type name content
miBoolean orthographic orthographic rendering
float focal focal length of the camera
float aperture aperture of the camera
float aspect aspect ratio y ⁄ x
miRange clip Z clipping distances
int x_resolution image width in pixels
int y_resolution image height in pixels
int window.xl left image margin
int window.yl bottom image margin
int window.xh right image margin
int window.yh top image margin
miTag volume camera volume (atmosphere)
miTag environment camera environment shader
miTag lens lens shader or lens shader list
miTag output output shader or output shader list
int frame frame number
float frame_time frame time in seconds
float frame_field 0: frame, 1: even field, 2: odd field
float x_offset x offset of image in pixels
float y_offset y offset of image in pixels
miTag userdata user data scene element, or 0
orthographic
This flag is miTRUE if the renderer is in orthographic mode, and miFALSE if it is in perspective mode.
focal
The focal length of the camera (the distance from the origin in camera space to the viewing plane that the image pixels are mapped on).
aperture
The aperture of the camera (the width of the viewing plane in camera space).
aspect
The aspect ratio (the ratio of the width and height of the viewing plane in camera space).
clip
This data structure has two members, min and max, that specify the hither and yon clipping planes in camera space for scanline rendering. Objects will be clipped if their Z coordinate in camera space is less than -max or greater than -min.
x_resolution
The x resolution of the image in pixels.
y_resolution
The y resolution of the image in pixels.
window
The window specifies the lower left and the upper right pixel of the sub-region of the image to be rendered. If xl and yl are 0 and xh and yh match or exceed the resolution minus one, the entire image is rendered. The window is clipped to the resolution. Pixels outside the window are set to black.
volume
The global volume (atmosphere) shader from the camera that is used for attenuating rays outside of objects, such as the primary ray from the camera to the first object intersection. Material shaders inherit this volume shader because the volume state variable defaults to the camera volume, but shaders may override the volume. See below.
environment
The environment (reflection map) shader of the camera. It is used to assign a color to primary eye rays that leave the scene without ever intersecting an object. Material shaders that do not define their own environment shaders for evaluation of local reflection maps inherit the camera environment shader. Reflection maps give the illusion of true raytraced reflections by looking up a texture based on the reflection direction.
lens
The list of lenses applied to the standard pinhole camera. Each lens shader in this list is called when a primary ray leaves the camera.
output
The list of output shaders and file outputs attached to the camera. File outputs are encoded in special miFunction data structures that contain a file name and various miscellaneous data instead of a shader reference.
pass
The list of pass rendering statements.
frame
The current frame number. In field mode, this is the field number, two successive frames rendered by mental ray are combined into a single output frame by an output shader. In field mode, the odd frame is the first frame and the even frame is the second.
frame_time
The current frame number, expressed as a time in seconds. The relation between frame and frame_time depends on the frame rate. Both numbers are taken verbatim from the input scene, mental ray does not change or verify either number. If the frame time is omitted in the .mi file, it is set to 0.0.
x_offset
The X offset of the rendered image. The default value is 0.0 which means that the image will be centered on the camera's axis.
y_offset
The Y offset of the rendered image. The default value is 0.0 which means that the image will be centered on the camera's axis.
userdata
User data blocks are independent named toplevel scene entities that hold structured or unstructured data of any kind. Structured data is declared much like shader parameters, while unstructured data is a raw byte stream with a fixed size. User data is useful for large amounts of shared scene data.

The options field in the state contains all rendering options specified in the scene, potentially overridden from the command line. Since the number of options is very large, and since they are rarely used in a shader, the description can be found near the end of this section, on page Options.

Copyright © 1986-2010 by mental images GmbH