When rendering into a shadow map, SHADOW_MAP_FRAMEBUFFER is set to 1 in the depth shader by the ShadowMap's framebuffer. More...

Inherits G3D::ReferenceCountedObject.

Classes
class	Layer

struct	VSMSettings
	Stochastic-variance shadow map settings. More...

Public Member Functions
float	backfacePolygonOffset () const

float	bias () const
	Distance in meters to pull surfaces forward towards the light (along the -z axis) during shadow map rendering. More...

const shared_ptr< Texture > &	depthTexture () const

bool	enabled () const

const shared_ptr< Framebuffer > &	framebuffer () const
	The framebuffer used for rendering to the texture. More...

RealTime	lastUpdateTime () const
	Wall-clock time at which updateDepth() was last invoked. More...

const CoordinateFrame &	lightFrame () const
	The coordinate frame of the light source. More...

const Matrix4 &	lightMVP () const
	Model-View-Projection matrix that maps world space to the shadow map pixels; used for rendering the shadow map itself. More...

const Matrix4 &	lightProjection () const
	Projection matrix for the light, biased to avoid self-shadowing. More...

const String &	name () const
	For debugging purposes. More...

float	polygonOffset () const

const Projection &	projection () const

Projection &	projection ()

Rect2D	rect2DBounds () const

void	setBias (float f)
	Distance in meters to pull surfaces forward towards the light (along the -z axis) during shadow map rendering. Call before updateDepth. More...

void	setPolygonOffset (float s, float b=nan())
	Increase to hide self-shadowing artifacts, decrease to avoid gap between shadow and object. More...

void	setShaderArgsRead (class UniformTable &args, const String &prefix) const
	Binds these parameters: More...

virtual void	setSize (Vector2int16 desiredSize=Vector2int16(1024, 1024))
	Call with desiredSize = 0 to turn off shadow maps. More...

const Matrix4 &	unitLightMVP () const
	MVP adjusted to map to [0,0], [1,1] texture coordinates. More...

const Matrix4 &	unitLightProjection () const
	Unit projection matrix for the light, biased to avoid self-shadowing. More...

virtual void	updateDepth (class RenderDevice *renderDevice, const CoordinateFrame &lightFrame, const Matrix4 &lightProjectionMatrix, const Array< shared_ptr< Surface >> &shadowCaster, CullFace cullFace=CullFace::BACK, const Color3 &transmissionWeight=Color3::white()/3.0f, const RenderPassType passType=RenderPassType::SHADOW_MAP)
	Assumes that the caller has ensured that shadowCaster contains only shadow-casting surfaces. More...

bool	useVarianceShadowMap () const

const shared_ptr< Texture > &	vsm () const

Static Public Member Functions
static void	computeMatrices (const shared_ptr< Light > &light, AABox shadowCasterBounds, CFrame &lightFrame, Projection &projection, Matrix4 &lightProjectionMatrix, float lightProjX=20, float lightProjY=20, float lightProjNearMin=0.3f, float lightProjFarMax=500.0f, float intensityCutoff=1/255.0f)
	Computes a reference frame (as a camera) and projection matrix for the light. More...

static shared_ptr< ShadowMap >	create (const String &name="Shadow Map", Vector2int16 desiredSize=Vector2int16(1024, 1024), const VSMSettings &vsmSettings=VSMSettings())

Protected Member Functions
	ShadowMap (const String &name)

Static Protected Member Functions
template<class T , class ... ArgTypes>
static shared_ptr< T >	createShared (ArgTypes &&... args)
	Like std::make_shared, but works for protected constructors. More...

Protected Attributes
float	m_backfacePolygonOffset

Layer	m_baseLayer
	For Surface::canMove() == false surfaces, regardless of whether they actually behave correctly and don't move. More...

float	m_bias

Layer	m_dynamicLayer
	For Surface::canMove() == true surfaces. More...

CoordinateFrame	m_lightFrame

Matrix4	m_lightMVP

Matrix4	m_lightProjection
	Maps projected homogeneous coordinates to [-1, 1] More...

String	m_name

float	m_polygonOffset

Projection	m_projection

Matrix4	m_unitLightMVP
	Maps projected homogeneous coordinates to [0, 1] More...

Matrix4	m_unitLightProjection
	Maps projected homogeneous coordinates to [0, 1] More...

shared_ptr< Framebuffer >	m_vsmFinalFB
	m_vsmRawFB after vertical filtering. More...

shared_ptr< Framebuffer >	m_vsmHBlurFB
	m_vsmRawFB after horizontal filtering More...

shared_ptr< Framebuffer >	m_vsmRawFB
	m_vsmSourceDynamicLayer converted to VSM format (mean + variance) before filtering More...

VSMSettings	m_vsmSettings
	Do not change after initialization. More...

Layer	m_vsmSourceBaseLayer
	For Surface::canMove() == false surfaces that want to be in the VSM. More...

Layer	m_vsmSourceDynamicLayer
	For Surface::canMove() == true surfaces that want to be in the VSM. More...

Detailed Description

When rendering into a shadow map, SHADOW_MAP_FRAMEBUFFER is set to 1 in the depth shader by the ShadowMap's framebuffer.

Constructor & Destructor Documentation

◆ ShadowMap()

G3D::ShadowMap::ShadowMap ( const String & name )

protected

Member Function Documentation

◆ backfacePolygonOffset()

float G3D::ShadowMap::backfacePolygonOffset ( ) const

inline

◆ bias()

float G3D::ShadowMap::bias ( ) const

inline

Distance in meters to pull surfaces forward towards the light (along the -z axis) during shadow map rendering.

This is typically on the scale of centimeters. During shadow map testing, surfaces are pulled three times this distance along their surface normal, so that faces in direct light are not shadowed by themselves.

◆ computeMatrices()

static void G3D::ShadowMap::computeMatrices	(	const shared_ptr< Light > &	light,
		AABox	shadowCasterBounds,
		CFrame &	lightFrame,
		Projection &	projection,
		Matrix4 &	lightProjectionMatrix,
		float	lightProjX = `20`,
		float	lightProjY = `20`,
		float	lightProjNearMin = `0.3f`,
		float	lightProjFarMax = `500.0f`,
		float	intensityCutoff = `1/255.0f`
	)

static

Computes a reference frame (as a camera) and projection matrix for the light.

Parameters

lightFrame	For a directional light, this is a finite reference frame.
projection	For a SPOT light, this is the perspective projection.
lightProjX	Scene bounds in the light's reference frame for a directional light. Not needed for a spot light
lightProjY	Scene bounds in the light's reference frame for a directional light. Not needed for a spot light
lightProjNearMin	Shadow map near plane depth in the light's reference frame for a directional light. For a spot light, a larger value will be chosen if the method determines that it can safely do so. For directional and point lights, this value is used directly.
lightProjFarMax	Shadow map far plane depth in the light's reference frame for a directional light. For a spot light, a smaller value will be chosen if the method determines that it can safely do so. For directional and point lights, this value is used directly.
intensityCutoff	Don't bother shadowing objects that cannot be brighter than this value. Set to 0 to cast shadows as far as the entire scene.

◆ create()

static shared_ptr<ShadowMap> G3D::ShadowMap::create	(	const String &	name = `"Shadow Map"`,
		Vector2int16	desiredSize = `Vector2int16(1024, 1024)`,
		const VSMSettings &	vsmSettings = `VSMSettings()`
	)

static

◆ createShared()

template<class T , class ... ArgTypes>

static shared_ptr<T> G3D::ReferenceCountedObject::createShared ( ArgTypes &&... args )

inlinestaticprotectedinherited

Like std::make_shared, but works for protected constructors.

Call as createShared<myclass>.

◆ depthTexture()

const shared_ptr<Texture>& G3D::ShadowMap::depthTexture ( ) const

inline

◆ enabled()

bool G3D::ShadowMap::enabled ( ) const

◆ framebuffer()

const shared_ptr<Framebuffer>& G3D::ShadowMap::framebuffer ( ) const

inline

The framebuffer used for rendering to the texture.

◆ lastUpdateTime()

RealTime G3D::ShadowMap::lastUpdateTime ( ) const

inline

Wall-clock time at which updateDepth() was last invoked.

Used to avoid recomputing shadow maps for static lights and objects. Calling a mutating method like setSize() resets this to zero.

◆ lightFrame()

const CoordinateFrame& G3D::ShadowMap::lightFrame ( ) const

inline

The coordinate frame of the light source.

◆ lightMVP()

const Matrix4& G3D::ShadowMap::lightMVP ( ) const

inline

Model-View-Projection matrix that maps world space to the shadow map pixels; used for rendering the shadow map itself.

Note that this maps XY to [-1,-1],[1,1]. Most applications will use biasedLightMVP to avoid self-shadowing problems.

◆ lightProjection()

const Matrix4& G3D::ShadowMap::lightProjection ( ) const

inline

Projection matrix for the light, biased to avoid self-shadowing.

◆ name()

const String& G3D::ShadowMap::name ( ) const

inline

For debugging purposes.

◆ polygonOffset()

float G3D::ShadowMap::polygonOffset ( ) const

inline

◆ projection() [1/2]

const Projection& G3D::ShadowMap::projection ( ) const

inline

◆ projection() [2/2]

Projection& G3D::ShadowMap::projection ( )

inline

◆ rect2DBounds()

Rect2D G3D::ShadowMap::rect2DBounds ( ) const

◆ setBias()

void G3D::ShadowMap::setBias ( float f )

inline

Distance in meters to pull surfaces forward towards the light (along the -z axis) during shadow map rendering. Call before updateDepth.

See also: bias

◆ setPolygonOffset()

void G3D::ShadowMap::setPolygonOffset	(	float	s,
		float	b = `nan()`
	)

inline

Increase to hide self-shadowing artifacts, decrease to avoid gap between shadow and object.

Default = 0.0.

Parameters

b	if nan(), the backface offset is set to s, otherwise it is set to b

◆ setShaderArgsRead()

void G3D::ShadowMap::setShaderArgsRead	(	class UniformTable &	args,
		const String &	prefix
	)		const

Binds these parameters:

#expect prefix_notNull "Defined if the shadow map is bound"
uniform mat4 prefix_lightMVP;
uniform float prefix_bias;             

Plus all of the Texture::setShaderArgs values for prefix_depth

◆ setSize()

virtual void G3D::ShadowMap::setSize ( Vector2int16 desiredSize = Vector2int16(1024, 1024) )

virtual

Call with desiredSize = 0 to turn off shadow maps.

◆ unitLightMVP()

const Matrix4& G3D::ShadowMap::unitLightMVP ( ) const

inline

MVP adjusted to map to [0,0], [1,1] texture coordinates.

Equal to unitLightProjection() * Matrix4::translation(0,0,-bias()) * lightFrame().inverse().

This includes Y inversion, on the assumption that shadow maps are rendered to texture.

◆ unitLightProjection()

const Matrix4& G3D::ShadowMap::unitLightProjection ( ) const

inline

Unit projection matrix for the light, biased to avoid self-shadowing.

◆ updateDepth()

virtual void G3D::ShadowMap::updateDepth	(	class RenderDevice *	renderDevice,
		const CoordinateFrame &	lightFrame,
		const Matrix4 &	lightProjectionMatrix,
		const Array< shared_ptr< Surface >> &	shadowCaster,
		CullFace	cullFace = `CullFace::BACK`,
		const Color3 &	transmissionWeight = `Color3::white()/3.0f`,
		const RenderPassType	passType = `RenderPassType::SHADOW_MAP`
	)

virtual

Assumes that the caller has ensured that shadowCaster contains only shadow-casting surfaces.

Parameters

cullFace Use NONE or BACK. Culling FRONT faces will create light leaks with our "normal offset" scheme.

◆ useVarianceShadowMap()

bool G3D::ShadowMap::useVarianceShadowMap ( ) const

inline

◆ vsm()

const shared_ptr<Texture>& G3D::ShadowMap::vsm ( ) const

Member Data Documentation

◆ m_backfacePolygonOffset

float G3D::ShadowMap::m_backfacePolygonOffset

protected

Referenced by backfacePolygonOffset(), and setPolygonOffset().

◆ m_baseLayer

Layer G3D::ShadowMap::m_baseLayer

protected

For Surface::canMove() == false surfaces, regardless of whether they actually behave correctly and don't move.

If the surfaces in here do move (e.g., because the scene is being edited), then the shadow map will render a little more slowly due to excessive updates but will still be correct.

◆ m_bias

float G3D::ShadowMap::m_bias

protected

Referenced by bias(), and setBias().

◆ m_dynamicLayer

Layer G3D::ShadowMap::m_dynamicLayer

protected

For Surface::canMove() == true surfaces.

Referenced by depthTexture(), framebuffer(), and lastUpdateTime().

◆ m_lightFrame

CoordinateFrame G3D::ShadowMap::m_lightFrame

protected

Referenced by lightFrame().

◆ m_lightMVP

Matrix4 G3D::ShadowMap::m_lightMVP

protected

Referenced by lightMVP().

◆ m_lightProjection

Matrix4 G3D::ShadowMap::m_lightProjection

protected

Maps projected homogeneous coordinates to [-1, 1]

Referenced by lightProjection().

◆ m_name

String G3D::ShadowMap::m_name

protected

Referenced by name().

◆ m_polygonOffset

float G3D::ShadowMap::m_polygonOffset

protected

Referenced by polygonOffset(), and setPolygonOffset().

◆ m_projection

Projection G3D::ShadowMap::m_projection

protected

Referenced by projection().

◆ m_unitLightMVP

Matrix4 G3D::ShadowMap::m_unitLightMVP

protected

Maps projected homogeneous coordinates to [0, 1]

Referenced by unitLightMVP().

◆ m_unitLightProjection

Matrix4 G3D::ShadowMap::m_unitLightProjection

protected

Maps projected homogeneous coordinates to [0, 1]

Referenced by unitLightProjection().

◆ m_vsmFinalFB

shared_ptr<Framebuffer> G3D::ShadowMap::m_vsmFinalFB

protected

m_vsmRawFB after vertical filtering.

This is used for reading

◆ m_vsmHBlurFB

shared_ptr<Framebuffer> G3D::ShadowMap::m_vsmHBlurFB

protected

m_vsmRawFB after horizontal filtering

◆ m_vsmRawFB

shared_ptr<Framebuffer> G3D::ShadowMap::m_vsmRawFB

protected

m_vsmSourceDynamicLayer converted to VSM format (mean + variance) before filtering

◆ m_vsmSettings

VSMSettings G3D::ShadowMap::m_vsmSettings

protected

Do not change after initialization.

Referenced by useVarianceShadowMap().

◆ m_vsmSourceBaseLayer

Layer G3D::ShadowMap::m_vsmSourceBaseLayer

protected

For Surface::canMove() == false surfaces that want to be in the VSM.

◆ m_vsmSourceDynamicLayer

Layer G3D::ShadowMap::m_vsmSourceDynamicLayer

protected

For Surface::canMove() == true surfaces that want to be in the VSM.

Classes

Public Member Functions

Static Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ ShadowMap()

Member Function Documentation

◆ backfacePolygonOffset()

◆ bias()

◆ computeMatrices()

◆ create()

◆ createShared()

◆ depthTexture()

◆ enabled()

◆ framebuffer()

◆ lastUpdateTime()

◆ lightFrame()

◆ lightMVP()

◆ lightProjection()

◆ name()

◆ polygonOffset()

◆ projection() [1/2]

◆ projection() [2/2]

◆ rect2DBounds()

◆ setBias()

◆ setPolygonOffset()

◆ setShaderArgsRead()

◆ setSize()

◆ unitLightMVP()

◆ unitLightProjection()

◆ updateDepth()

◆ useVarianceShadowMap()

◆ vsm()

Member Data Documentation

◆ m_backfacePolygonOffset

◆ m_baseLayer

◆ m_bias

◆ m_dynamicLayer

◆ m_lightFrame

◆ m_lightMVP

◆ m_lightProjection

◆ m_name

◆ m_polygonOffset

◆ m_projection

◆ m_unitLightMVP

◆ m_unitLightProjection

◆ m_vsmFinalFB

◆ m_vsmHBlurFB

◆ m_vsmRawFB

◆ m_vsmSettings

◆ m_vsmSourceBaseLayer

◆ m_vsmSourceDynamicLayer