ShadowGenerator Class Reference

Search for all occurrences

---

Detailed Description

See also:

Class ShadowType, Class ShadBufRenderer, Class RendContext, Class RenderGlobalContext, Class ShadeContext, Class Matrix3, Class Point3, Class Color.

Description:

This class is available in release 3.0 and later only.

This class is used by a Shadow Type plug-in to generate the shadows. It only exists during a render, with one per instance of the light. Methods of this class perform the shadow buffer creation and sampling.

The ShadowGenerator API allows for two methods of sampling: A generator can use either a "generic" sampling method:

float Sample(ShadeContext &sc, Point3 &norm, Color& color);

Or, if it the generator is to work with Volumetric lights, it must use the following sampling shadow-map style interface:

float Sample(ShadeContext &sc, float x, float y, float z, float xslope, float yslope);
BOOL QuickSample(int x, int y, float z);
FiltSample(int x, int y, float z, int level);
LineSample(int x1, int y1, float z1, int x2, int y2, float z2); 

To indicate that the latter interface is used, the method ShadowType::SupportStdMapInterface() must return TRUE;

#include <shadgen.h>

Inheritance diagram for ShadowGenerator:

List of all members.

Public Member Functions
virtual	~ShadowGenerator ()
virtual int	Update (TimeValue t, const RendContext &rendCntxt, RenderGlobalContext *rgc, Matrix3 &lightToWorld, float aspect, float param, float clipDist=DONT_CLIP)=0
virtual int	UpdateViewDepParams (const Matrix3 &worldToCam)=0
virtual void	FreeBuffer ()=0
virtual void	DeleteThis ()=0
virtual float	Sample (ShadeContext &sc, Point3 &norm, Color &color)
virtual float	Sample (ShadeContext &sc, float x, float y, float z, float xslope, float yslope)
virtual BOOL	QuickSample (int x, int y, float z)
virtual float	FiltSample (int x, int y, float z, int level)
virtual float	LineSample (int x1, int y1, float z1, int x2, int y2, float z2)

---

Constructor & Destructor Documentation

virtual ~ShadowGenerator

(

)

[inline, virtual]

Remarks:

Destructor.

{}

---

Member Function Documentation

virtual int Update	(	TimeValue	t,
		const RendContext &	rendCntxt,
		RenderGlobalContext *	rgc,
		Matrix3 &	lightToWorld,
		float	aspect,
		float	param,
		float	clipDist = DONT_CLIP
	)		[pure virtual]

Search for all occurrences

Remarks:

This method is called on every frame to create a new shadow buffer for that frame. For example, the objects in the scene will have moved to different position, etc., so a new shadow buffer will need to be set up. See Class ShadBufRenderer for a helper class used for generating shadow map buffers.

Parameters:

TimeValue t

The time for the update.

const RendContext& rendCntxt

The render context -- this is used for the progress bar.

RenderGlobalContext *rgc

This is used to get an instance list.

Matrix3& lightToWorld

The light to world space transformation matrix. This is not necessarily the same as that of the light.

float aspect

This is the aspect ratio for non-square buffers. The aspect gives the height/width ratio of the shadow rectangle. The shadow buffer bitmap is always the same number of pixels wide as it is high, but it can be mapped into a non-square rectangle.

float param

This is the field-of-view of the light in radians for perspective projections or the width in world coordinates for parallel projections.

float clipDist = DONTCLIP

This parameter specifies the far clipping distance for the light. This is used when the far distance attenuation is turned on, and can result in much more efficient shadow buffer creation. If you have a small scene in the middle of a large complex scene, and the small scene is lit by, for instance, a shadow-casting omni, if you don't use far attenuation the omni has to take into account the entire large scene in its shadow map. Using far attenuation will clip all this outside stuff. Also omnis free up any of their 6 shadow buffer that end up being empty, so this can save memory usage.

Returns:

Nonzero on success; otherwise zero.

virtual int UpdateViewDepParams

(

const Matrix3 &

worldToCam

)

[pure virtual]

Search for all occurrences

Remarks:

If things such as automatic cubic maps or mirror are used, the rendering is done from several different points of view. This method is called to allow the view matrix to be computed and cached so it won't have to be computed over and over again. The shadow buffer caches the matrix that does the transformation from the current view coordinates into its coordinates.

Parameters:

const Matrix3& worldToCam

This is the direction the view is looking from. Object coordinates are relative to this 'camera'. This is not always a 'camera', it is just world to whatever view is needed, for example from a mirror.

Returns:

Nonzero on success; otherwise zero.

virtual void FreeBuffer

(

)

[pure virtual]

Search for all occurrences

Remarks:

This method is used to delete the memory associated with the buffer.

virtual void DeleteThis

(

)

[pure virtual]

Search for all occurrences

Remarks:

Call this to destroy the ShadowGenerator.

virtual float Sample	(	ShadeContext &	sc,
		Point3 &	norm,
		Color &	color
	)		[inline, virtual]

Search for all occurrences

Remarks:

Generic shadow sampling function. Implement this when ShadowType::SupportStdMapInterface() returns FALSE.

This is the Sample method used for ray traced shadows, for example. It takes the color that would illuminate the surface if there were no shadows, and returns a modified value. The shade context provides the point on the surface (sc.P()) and norm is the normal to the surface.

Parameters:

ShadeContext &sc

The shade context provides the point on the surface (sc.P()).

Point3 &norm

This is the normal to the surface.

Color& color

The input color.

Returns:

It returns an attenuation, where 1.0 indicates it is not in shadow, and 0.0 indicates it is in shadow.

Default Implementation:

{ return 1.0f; }

{ return 1.0f; }

virtual float Sample	(	ShadeContext &	sc,
		float	x,
		float	y,
		float	z,
		float	xslope,
		float	yslope
	)		[inline, virtual]

Search for all occurrences

Remarks:

Implement this method when ShadowType::SupportStdMapInterface() returns TRUE. This interface allows illuminated atmospherics.

This method is called to determine how much the point (x, y, z) is in shadow. It returns an attenuation, where 1.0 indicates it is not in shadow, and 0.0 indicates it is in shadow, and potentially a small negative number. A small negative number should be returned when the sample falls outside of the buffer (this is needed in order to fix a problem occuring with Omni Lights when using shadow maps). All shadow generators that implement this function need to do this. The value itself isn't important, as long as it is negative and very small (for instance (-float(1.0e-30)).

Parameters:

ShadeContext &sc

The shade context.

float x

The x coordinate of the point to check. This point is normalized into shadow buffer space. For example if the shadow buffer was 256x256 a point at the center would be 128, 128.

float y

The y coordinate of the point to check. This point is normalized into shadow buffer space.

float z

The z coordinate of the point to check. This is the distance perpendicular to the light where 0.0 is right at the light.

float xslope

This indicates the slope of the surface relative to the shadow buffer in x.

float yslope

This indicates the slope of the surface relative to the shadow buffer in y.

Default Implementation:

{ return 1.0f; }

{ return 1.0f; }

virtual BOOL QuickSample	(	int	x,
		int	y,
		float	z
	)		[inline, virtual]

Search for all occurrences

Remarks:

Implement this method when ShadowType::SupportStdMapInterface() returns TRUE. This interface allows illuminated atmospherics.

This method determines if the given point is in a shadow. It samples a single pixel in the shadow map.

Parameters:

int x

The x coordinate of the point to check. This point is normalized into shadow buffer space. For example if the shadow buffer was 256x256 a point at the center would be 128, 128.

int y

The y coordinate of the point to check. This point is normalized into shadow buffer space.

float z

The z coordinate of the point to check. This is the distance perpendicular to the light where 0.0 is right at the light.

Returns:

TRUE if the point is in shadow; otherwise FALSE.

Default Implementation:

{ return 1; }

{ return 1; }

virtual float FiltSample	(	int	x,
		int	y,
		float	z,
		int	level
	)		[inline, virtual]

Search for all occurrences

Remarks:

Implement this method when ShadowType::SupportStdMapInterface() returns TRUE. This interface allows illuminated atmospherics.

This method is called to determine how much the point (x, y, z) is in shadow. It returns an attenuation, where 1.0 indicates it is not in shadow, and 0.0 indicates it is in shadow. The method QuickSample() above looks at a single pixel in the shadow buffer. This method looks at either 4 or 8 pixels (based on the level parameter) to compute the result. The center pixel is given the highest weighting, while the other pixels are given lesser weightings. However this method is still fairly quick, since it doesn't base the weighting on the location within the pixel. This is in contrast to the Sample() method above, where the blending of the adjacent pixels is weighted by the position within the sub-pixel.

Parameters:

int x

The x coordinate of the point to check. This point is normalized into shadow buffer space. For example if the shadow buffer was 256x256 a point at the center would be 128, 128.

int y

The y coordinate of the point to check. This point is normalized into shadow buffer space.

float z

The z coordinate of the point to check. This is the distance perpendicular to the light where 0.0 is right at the light.

int level

This may be 0 or 1. If 0, four neighboring pixels are blended in. If 1, eight neighboring pixels are blended in.

Returns:

A value in the range 0.0 to 1.0.

Default Implementation:

{ return 1.0f; }

{ return 1.0f; }

virtual float LineSample	(	int	x1,
		int	y1,
		float	z1,
		int	x2,
		int	y2,
		float	z2
	)		[inline, virtual]

Search for all occurrences

Remarks:

Implement this method when ShadowType::SupportStdMapInterface() returns TRUE. This interface allows illuminated atmospherics.

This method is called to sample the shadow map along a line segment. It uses a line between x1, y1 and x2, y2. The z values are interpolated between z1 and z2 and compared to the z value in the shadow map for that pixel.

Parameters:

int x1

The start x coordinate of the line. This point is normalized into shadow buffer space. For example if the shadow buffer was 256x256 a point at the center would be 128, 128.

int y1

The start y coordinate of the line. This point is normalized into shadow buffer space.

float z1

The start z coordinate of the line. This is the distance perpendicular to the light where 0.0 is right at the light.

int x2

The end x coordinate of the line. This point is normalized into shadow buffer space.

int y2

The end y coordinate of the line. This point is normalized into shadow buffer space.

float z2

The end z coordinate of the line. This is the distance perpendicular to the light where 0.0 is right at the light.

Returns:

A value in the range 0.0 to 1.0 which represents how much of the ray was inside the light and how much was outside the light.

Default Implementation:

{ return 1.0f; }

{ return 1.0f; }