Image Samples

The state variables in the next table describe an eye (primary) ray. There is one eye ray for every sample that contributes to a pixel in the output image. If a material shader that evaluates a material hit by a primary ray casts secondary reflection, refraction, transparency, light, or shadow rays, all shaders called as a consequence will inherit these variables unmodified:

type	name	content
`miScalar`	`raster_x`	X coordinate of image pixel
`miScalar`	`raster_y`	Y coordinate of image pixel
`miFunction *`	`shader`	current shader
`miLock`	`global_lock`	lock shared by all shaders
`short`	`thread`	current thread

The X coordinate of the point in raster space to be rendered. Raster space is the pixel grid of the rendered image file, with 0/0 at the lower left corner.

The Y coordinate of the point in raster space to be rendered. In output shaders executing in parallel mode because state→dist is nonzero, it contains the number of the first scanline of the scanline block to write.

This pointer points to a data structure describing the current shader. The fields usable by shaders are lock, which is a lock shared by all calls to this shader, miTag next_function for chained shaders such as lens shaders, and char parameters[] which contains the shader parameters. The latter is redundant for the current shader because the parameter pointer is also passed as the third shader argument, but it can be used to find the parameters of parent shaders. This should be used with care because the C data structure of parent shader parameter lists is not generally known. Note that mental ray 3.x no longer supports state→shader→user.p. It is necessary to use mi_query with miQ_FUNC_USERPTR to retrieve the user pointer.

This lock is shared by all shaders, regardless of their name. It can be used to lock critical sections common to all shaders. For example, it could be used to protect a nonreentrant user-defined random-number generator, or initialization of a more specific set of locks. It is pre-initialized by mental ray; do not initialize or delete it.

The current thread number. Note that mental ray may create and destroy threads at any time, and may create threads with arbitrary numbers unrelated to the value specified on the command line with -threads. The thread number should not be used to index static arrays in mental ray.

This field is valid only in light shaders. It specifies the number of times the light shader has already been called in order to oversample an area light source. It is 0 for the first call. The shader may change this value just before returning (miBoolean)2, which aborts the sample loop and changes the value that the material shader will divide by to compute the average. In particular, a light shader for a user area light might set the count to 1 so that the material shader considers each sample as a separate light. This is useful for natural light "chrome dome" illumination. The count field is also valid in multipass rendering in renderpass merge shaders, where it contains the number of passes to merge.