State Variables by Shader Type

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

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

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.

In the table,

r

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

ro

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.

rw

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.

x

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

1 The 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 Valid only if the object contains surface derivatives.

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

Copyright © 1986-2010 by mental images GmbH