# OSL trace() : how is the “shade ” parameter used?

In its description of the trace() function , The OSL language specification refers to:

...the optional "shade" parameter indicating whether or not the shader ought to execute on the traced ray ... .

What does this mean? It can't mean I recursively apply the calling shader to the point hit by trace(), can it? That point will have been / may be shaded by something else, at some other time. Are there any examples of the use of this parameter?

As described in the OSL specification, the main purpose of the trace() function call is to be used within a shader to 'probe out' the surrounding geometry. When used in this way there is no need for the shader to perform the additional work of determining the shading of that 'hit' point - only whether there is something along that ray (and what/where it is). The default of the 'shade' parameter is 0 - ie, only determine whether geometry is 'hit', don't consider it's surface or shading. ie,

Optional parameters include:
"mindist"  float     Minimum hit distance (default: zero)
"maxdist"  float     Maximum hit distance (default: infinite)
"traceset" string    An optional named set of objects to ray trace (if preceded by a ‘-’ character, it means to exclude that set).


From what I gather, setting 'shade' to 1 indicates that the additional work of actually shading the hit point on the surface (eg, calculate the normal, interpolation, etc.) also takes place (taking additional processing time).

So, in summary, it's an efficiency flag - leaving as 0 provides a quick and dirty trace whereas setting to non-zero acivates the 'full' trace, including hit surface properties.

EDIT : For a related question (see https://blender.stackexchange.com/a/106832/29586) I have been trying to trace through the source code for the trace() function.

The trail seems to lead to the trace() function with the comment /* todo: options.shader support, maybe options.traceset */ which seems to confirm that the 'traceset' option is not implemented and the same function does not have any other reference to the 'shade' parameter - it would appear that the 'shader' mentioned in the comment is a typo (should be 'shade') and the 'shade' option is not implemented.

• I'll have to try it ... but what I don't understand is, if 'the shader' to be executed is this shader, but at the hitpoint, that's a recursion, and would have to be bottomed out somehow .. (by a threshold value, condition, or message). Even if the hitpoint executes its own assigned shaders, from its own material, it seems to me that would still be calling a shader twice on the same point? Once by us, and again during the renderer's normal progress? – Robin Betts Apr 20 '18 at 16:01
• I see what you mean - and re-reading the OSL spec does seem to indicate potential recursive shading - so if it was the same shader it could potentially get trapped indefinitely unless your code sets some kind of bounce limit. – Rich Sedman Apr 20 '18 at 16:20
• @RobinBetts see my edit - I've pretty much convinced myself that the 'shade' option isn't implemented (as is with the 'traceset' option). – Rich Sedman Apr 20 '18 at 22:21
• Phew.. that's almost a relief. A lot of trial and error avoided. – Robin Betts Apr 21 '18 at 6:09