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.