State Variables by Shader Type

The following table describes which state variables are available in which types of shaders:

As an exception, a shader instance init function may use all the state variables that the shader itself may used. This does not apply to shader init functions, shader exit functions, and shader instance exit functions, all of which have only very limited access.

means that the shader may read this variable but should not modify it because it may have unknown effects on parent or child shaders.

means that the shader may read this variable but may never modify it because shader interface functions or other parts of mental ray depend on unchanged values.

means that the shader may read or write this variable; if it writes it is good practice to restore the original contents before returning to avoid surprises in parent or volume shaders. pri, in particular, must be restored. Most shaders do not need to modify most of these.

means that the shader is free to read and write, and need not restore any values. These are "scratchpad" variables for shader communication, and not used by mental ray.

means that the shader may neither read nor write this field. Its contents are undefined.

In the case of the options and camera variables, the shader may write neither the pointer nor any field of the options and camera structures. Note that during rendering (between the rendering and rendering finished messages), the camera and the options may differ from the scene file specifications because phenomenon requirements and conflict detection may make adjustments. For example, a lens shader might have requested ray tracing to be turned off even though it was turned on in the scene file. In this case, shaders called during rendering would see a trace flag that is off, and other shaders such as geometry or displacement shaders do not.

variable	G	D	P	E	Le	M	V	Lg	S	Cs	C	O	Lm	IE
version	ro	ro	ro	ro	ro	ro	ro	ro	ro	ro	ro	ro	ro	ro
camera_inst	ro	ro	ro	ro	ro	ro	ro	ro	ro	ro	ro	ro	ro	ro
camera	ro	ro	ro	ro	ro	ro	ro	ro	ro	ro	ro	ro	ro	ro
options	ro	ro	ro	ro	ro	ro	ro	ro	ro	ro	ro	ro	ro	ro
global_lock [1]	-	rw	rw	rw	rw	rw	rw	rw	rw	rw	rw	-	-	-
raster_x	-	-	-	-	ro	ro	ro	ro	ro	ro	-	-	-	-
raster_y	-	-	-	-	ro	ro	ro	ro	ro	ro	-	ro	-	-
parent	-	-	ro	ro	ro	ro	ro	ro	ro	ro	-	-	-	-
type	ro	ro	ro	ro	ro	ro	ro	ro	ro	ro	-	ro	-	-
scanline	-	-	-	-	r	r	r	r	r	r	-	-	-	-

variable	G	D	P	E	Le	M	V	Lg	S	Cs	C	O	Lm	IE
reflection_level	-	-	rw	rw	rw	rw	rw	rw	rw	rw	-	-	-	-
refraction_level	-	-	rw	rw	rw	rw	rw	rw	rw	rw	-	-	-	-
face	-	-	rw	rw	rw	rw	rw	rw	rw	r-	-	-	-	-
org	-	-	rw	rw	rw	rw	rw	rw	rw	rw	-	-	-	-
dir	-	-	rw	rw	rw	rw	rw	rw	-	rw	-	-	-	-
dist	-	-	rw	rw	rw	rw	rw	rw	rw	rw	-	ro	-	-
time	-	-	ro	ro	ro	ro	ro	ro	ro	ro	-	-	-	-
ior	x	x	x	x	x	x	x	x	x	x	x	x	-	-
ior_in	x	x	x	x	x	x	x	x	x	x	x	x	-	-
material	-	r	r	r	-	r	r	r	r	r	-	-	-	-
volume	-	-	rw	rw	rw	rw	rw	rw	rw	rw	-	-	-	-
environment	-	-	-	-	rw	rw	rw	-	-	rw	-	-	-	-
refraction_volume	-	-	rw	rw	-	rw	rw	-	-	rw	-	-	-	-
label	-	r	r	r	rw	rw	rw	rw	rw	rw	-	-	ro	-
instance	ro	ro	ro	-	ro	ro	ro	ro	ro	ro	-	-	ro	-
light_instance	-	-	-	ro	-	-	ro [2]	ro	ro	-	-	-	-	-
pri [3]	-	-	r	-	rw	rw	rw	rw	rw	rw	-	-	-	-
pri_idx	-	-	r	-	r	r	r	r	r	r	-	-	-	-

variable	G	D	P	E	Le	M	V	Lg	S	Cs	C	O	Lm	IE
bary[4]	-	-	r	-	r	r	r	r	r	r	-	-	-	-
point	-	r	r	-	rw	rw	rw	rw	rw	rw	-	-	-	-
normal	-	r	r	-	rw	rw	rw	rw	rw	rw	-	-	-	-
normal_geom	-	-	r	-	rw	rw	rw	rw	rw	rw	-	-	-	-
dot_nd	-	-	r	-	rw	rw	rw	rw	-	rw	-	-	-	-
inv_normal	-	-	r	-	r	r	r	r	-	r	-	-	-	-
shadow_tol	-	-	r	-	r	r	r	r	r	r	r	-	-	-
tex_list	-	rw	rw	-	rw	rw	rw	rw	rw	rw	-	-	-	-
bump_x_list	-	-	rw	-	rw	rw	rw	rw	rw	rw	-	-	-	-
bump_y_list	-	-	rw	-	rw	rw	rw	rw	rw	rw	-	-	-	-
motion	-	-	rw	rw	rw	rw	rw	rw	rw	rw	-	-	-	-
derivs [4]	-	-	rw	-	rw	rw	rw	rw	rw	rw	-	-	-	-
tex	x	x	x	x	x	x	x	x	x	x	x	x	-	-
shader	ro	ro	ro	ro	ro	ro	ro	ro	ro	ro	ro	ro	ro	ro
child	-	-	ro	ro	ro	ro	ro	ro	ro	ro	-	-	-	-
thread	ro	ro	ro	ro	ro	ro	ro	ro	ro	ro	ro	ro	ro	ro
count	-	-	-	-	-	-	-	rw	-	-	-	-	-	-
user	x	x	x	x	x	x	x	x	x	x	x	x	x	x
user_size	x	x	x	x	x	x	x	x	x	x	x	x	x	x

See page functype for a similar table listing available shader interface functions.

G	geometry shader
D	displacement shader
P	photon shader and photon volume shader
E	photon emitter shader
Le	lens shader
M	material shader and texture shader
V	volume shader
Lg	light shader
S	shadow shader
Cs	contour store shader
C	contour contrast shader and contour shader
Lm	lightmap shader
O	output shader
IE	shader init or exit function

	[1]	global_lock is accessed with mi_lock and mi_unlock only.
	[2]	If `state→type` is `miRAY_SHADOW`
	[3]	Set to 0 to cast rays from empty space. Do not set to other values.
	[4]	If the object contains surface derivatives