Raytracing Functions

Several plug-in classes receive pointers to raytracing functions that allow them to probe the scene from any point of view.

These functions aren't valid in all contexts, since they depend on having information about the scene that may not always exist. When the Surface Editor renders its preview thumbnail, for example, it evaluates the active shaders, but in this previewing context, the rayCast and rayShade fields of the LWShaderAccess will be NULL. Always ensure that raytracing function pointers are valid before using them.

You may also need to safeguard against infinite recursion. A ray fired in the evaluation callback of a shader or (particularly) a volumetric may cause that callback to be re-entered. Shaders can use the bounce member of the LWShaderAccess to monitor the recursion level.

   typedef double LWRayTraceFunc (const LWDVector position,
                     const LWDVector direction, LWDVector color);

   typedef int    LWIlluminateFunc (LWItemID light,
                     const LWDVector position, LWDVector direction,
                     LWDVector color);

   typedef double LWRayCastFunc (const LWDVector position,
                     const LWDVector direction);

   typedef double LWRayShadeFunc (const LWDVector position,
                     const LWDVector direction,
                     struct st_LWShaderAccess *);

len = rayTrace( position, direction, color )

Trace a ray from the given location in the given direction in world coordinates. The return value is the length of the ray (or -1.0 if infinite) and the color coming from that direction. The direction argument is the outgoing direction and must be normalized (a unit vector).

position: The world coordinates of the source of the ray.
direction: A unit-length vector, the outgoing direction of the ray in world coordinates.
color: Storage for the color of the spot hit by the ray.

lit = illuminate( lightID, position, direction, color )

This function obtains the light ray (color and direction) hitting the given position from the given light at the current time step. The return value is zero if the light does not illuminate the given world coordinate position at all. The color includes effects from shadows (if any), falloff, spotlight cones and transparent objects between the light and the point.

lightID: The light, given by its LWItemID.
position: The world coordinates of the spot at which the illumination will be tested.
direction: Storage for the direction of the light ray computed by the function.
color: Storage for the color of the light ray.

Two special light IDs, LWITEM_RADIOSITY and LWITEM_CAUSTICS, allow shaders and pixel filters to account for global illumination. When using these IDs, the direction argument becomes an input rather than an output, specifying the desired sampling direction.

len = rayCast( position, direction )

This is a quicker version of the rayTrace function which only returns the distance to the nearest surface (or -1.0). It performs neither shading nor recursive raytracing.

position: The world coordinates of the source of the ray.
direction: A unit-length vector, the outgoing direction of the ray in world coordinates.

len = rayShade( position, direction, shaderAccess )

Trace a ray to the nearest surface and evaluate the basic surface parameters and any shaders on that surface. The LWShaderAccess structure passed (and owned) by the caller is filled in with the result and no more processing is done.

position: The source of the ray in world coordinates.
direction: A unit-length vector, the outgoing direction of the ray in world coordinates.
shaderAccess: A pointer to an empty ShaderAccess structure that will be filled in by the function.