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 *);

   typedef int    LightSampleFunc (void *data, LWItemID light, const LWDVector dir, const LWDVector color);

   typedef double LWIlluminateSampleFunc (LWItemID light, const LWDVector pos, LWDVector dir,
					  LightSampleFunc *sampler, void *data);

   typedef double  LWIlluminateNormalFunc (LWItemID light, const LWDVector pos, LWDVector dir, const LWDVector normal,
					   LWDVector color);

   typedef double  LWIlluminateSampleNormalFunc (LWItemID light, const LWDVector pos, LWDVector dir,
						 const LWDVector normal, LightSampleFunc *sampler, void *data);

   typedef double  LWRayTraceModeFunc (const LWDVector position,
                                       const LWDVector direction,
                                       LWDVector color,
                                       const double eta,
				       const int rtmode);

   typedef void    LWRayTraceDataFunc( LWRenderData, LWRayTraceData* );
   typedef void    LWRayTraceShadeFunc( LWRayTraceData* );

len = rayTrace( position, direction, color )

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.

intensity = illuminateSample( light, position, direction, sampler, mydata )Illumination function, which calls the sampler function for each of the light rays. The sampler function receives the direction, color of the sample and the specified userdata.

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.
sampler: A LightSampleFunc function callback.
mydata: The mydata argument is passed to the sampler callback and can be anything it might require.

lit = illuminate( lightID, position, direction, color ) intensity = illuminateSampleNormal( light, position, direction, normal, sampler, mydata )

These new illumination functions behave the same way as their older counterparts, only these accept a normal direction which is used by light evaluators to determine if any illumination from lights or shadow rays are to be cast for the spot.

len = rayTraceMode( position, direction, color, eta, rtmode )

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). The eta is the outgoing ray refraction index, and is only used when rtmode is RTMODE_REFRACTION. The rtmode parameter defines the outgoing ray type.

All modes except backdrop take volumetrics into account. The ray flags are (ray mode & 0xFF). The choices are:

Mode 0: RTMODE_DISTANCE
Only returns the distance to the closest surface. This mode does not recurse. It can hit fully transparent surfaces.
The ray's position, direction and flags are used. Only distance is returned.
Mode 1: RTMODE_REFLECTION
This casts a reflection ray and shades the surface that is hit. It uses ray recursion.
All parameters except eta (refraciton index) are used. Distance and color are returned.
Mode 2: RTMODE_REFRACTION
This casts a refraction ray and shades the surface that is hit. It uses ray recursion.
All parameters are used. Distance and color are returned.
Mode 3: RTMODE_DISSOLVE
This casts a dissolve ray and shades the surface that is hit. It uses ray recursion. Dissolve is a special case of a refraction ray. It will never hit the object that cast the ray.
All parameters are used. Distance and color are returned.
Mode 4: RTMODE_SHADOW
This calculates the shadow occlusion along a ray. The ray does not recurse or bend at each intersection. At each surface intersection, the opacity is calculated and combined with the ray's current opacity. The order in which the surfaces are intersected is unpredictable.
The ray's position, direction and flags are used. Color and distance are returned.
Mode 5: RTMODE_OCCLUSION
This casts an occlusion ray. The ray does not recurse or bend at each intersection. Occlusion is a special case of a shadow ray. The difference is in the way it uses the object's normal ray visibility flags instead of the object's shadow visiblity flags.
The ray's position, direction and flags are used. Color and distance are returned.
Mode 6: RTMODE_BACKDROP
This casts a backdrop ray. The ray only intersects the backdrop color. It does not recurse.
The ray's position and direction are used. Color and distance are returned. The distance is always -1.

The ray flags are (ray mode & 0xFF000000).

RTFLAG_CAMERA
The ray is cast from the camera. It may have passed through transparent surfaces but it has not been reflected or refracted.
RTFLAG_BACKSHADE
Causes shaders to be called when the back side of a surface is hit by a ray.
RTFLAG_BACKDROP
Makes the raytrace functions use the color parameter as the backdrop color instead of calculating it prior to casting the ray. This allows a plug-in to override the backdrop color.
RTFLAG_OBJECT
Restricts the rays to only intersecting the same object that cast the ray. This is useful for shaders that calculate sub-surface scattering.
RTFLAG_SAMPLEDRAY
Should be set by the plug-in when it is using multiple rays to calculate illumination. An example would be for soft relfections. This allows shaders to restrict the number of rays that they cast to calculate illumination. This can greatly speed up renderings without degrading the image quality.
RTFLAG_NOPOLYGON
Allows the rays to hit the same polygon that cast them. This is useful for shaders that cast frays from a point in front of a surface.

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.
eta: The outgoing refraction index.
rtmode: The outgoing ray type.

rayTraceData( LWRayTraceData* )

Trace a ray using the data provided in the LWRayTraceData structure.
This data is then used with rayTraceShade to shade the spot hit by the previous call to rayTraceData
Only distance, reflection and refraction rays are available for this function.

typedef struct st_LWRayTraceData
{
send

LWDVector rayStart LWDVector rayDir LWDVector backdrop LWDVector weight double eta int flags

receive

LWRayData ray double len LWDVector result

} LWRayTraceData