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.
|
