User Fields

Finally, the user field allows a shader to store a pointer to an arbitrary data structure in the shader. Subsequent shaders called as a result of operations done by this shader (such as casting a reflection ray or evaluating a light or a texture) inherit the pointer and can read and write this shader's local data. Sub-shaders can also find other parent's user data by following state parent pointers, see above. With this method, extra parameters can be provided to and extra return values received from sub-shaders.

However, once the shader that has set the user pointer returns, the user pointer is lost. Its purpose is to pass information to sub-shaders down the call graph, not to pass information from one invocation of a shader to the next (for example, to the next primary ray). This implies that it is not a good idea to use mi_mem_allocate to obtain the pointer because by definition this could result in millions of allocations, which is inefficient. Long-term shader user data should be stored in the shader user pointer (obtainable with the miQ_FUNC_USERPTR mode of mi_query) instead, typically allocated in the init shader and released in the exit shader.

The user variables are initialized to 0.

type	name	content
`void *`	`user`	user data pointer
`int`	`user_size`	user data size (optional)

The shader pointer can be used to access the shader parameters, as state→parameters. This is redundant for the current shader because this pointer is also passed as the third shader argument, but it can be used to find a parent shader's parameters.