Public Types | Public Member Functions | Protected Member Functions | Protected Attributes | Static Protected Attributes
Ogre::PSSMShadowCameraSetup Class Reference

Parallel Split Shadow Map (PSSM) shadow camera setup. More...

#include <OgreShadowCameraSetupPSSM.h>

Inheritance diagram for Ogre::PSSMShadowCameraSetup:
Inheritance graph
[legend]

List of all members.

Public Types

typedef vector< Real >::type OptimalAdjustFactorList
typedef vector< Real >::type SplitPointList

Public Member Functions

 PSSMShadowCameraSetup ()
 Constructor, defaults to 3 splits.
 ~PSSMShadowCameraSetup ()
void calculateSplitPoints (uint splitCount, Real nearDist, Real farDist, Real lambda=0.95)
 Calculate a new splitting scheme.
virtual Degree getCameraLightDirectionThreshold () const
 Sets the threshold between the camera and the light direction below which the LiSPSM projection is 'flattened', since coincident light and camera projections cause problems with the perspective skew.
Real getOptimalAdjustFactor (size_t splitIndex) const
 Returns the optimal adjust factor for a given split.
Real getOptimalAdjustFactor () const
 Overridden, recommended internal use only since depends on current iteration.
virtual void getShadowCamera (const Ogre::SceneManager *sm, const Ogre::Camera *cam, const Ogre::Viewport *vp, const Ogre::Light *light, Ogre::Camera *texCam, size_t iteration) const
 Returns a LiSPSM shadow camera with PSSM splits base on iteration.
uint getSplitCount () const
 Get the number of splits.
Real getSplitPadding () const
 Get the padding factor to apply to the near & far distances when matching up splits to one another, to avoid 'cracks'.
const SplitPointListgetSplitPoints () const
 Returns the calculated split points.
bool getUseAggressiveFocusRegion () const
virtual bool getUseSimpleOptimalAdjust () const
 Gets whether or not to use a slightly simpler version of the camera near point derivation (default is true)
void operator delete (void *ptr)
void operator delete (void *ptr, void *)
void operator delete (void *ptr, const char *, int, const char *)
void operator delete[] (void *ptr)
void operator delete[] (void *ptr, const char *, int, const char *)
void * operator new (size_t sz, const char *file, int line, const char *func)
 operator new, with debug line info
void * operator new (size_t sz)
void * operator new (size_t sz, void *ptr)
 placement operator new
void * operator new[] (size_t sz, const char *file, int line, const char *func)
 array operator new, with debug line info
void * operator new[] (size_t sz)
virtual void setCameraLightDirectionThreshold (Degree angle)
 Sets the threshold between the camera and the light direction below which the LiSPSM projection is 'flattened', since coincident light and camera projections cause problems with the perspective skew.
void setOptimalAdjustFactor (size_t splitIndex, Real factor)
 Set the LiSPSM optimal adjust factor for a given split (call after configuring splits).
virtual void setOptimalAdjustFactor (Real n)
 Adjusts the parameter n to produce optimal shadows.
void setSplitPadding (Real pad)
 Set the padding factor to apply to the near & far distances when matching up splits to one another, to avoid 'cracks'.
void setSplitPoints (const SplitPointList &newSplitPoints)
 Manually configure a new splitting scheme.
void setUseAggressiveFocusRegion (bool aggressive)
 Sets whether or not to use the more aggressive approach to deciding on the focus region or not.
virtual void setUseSimpleOptimalAdjust (bool s)
 Sets whether or not to use a slightly simpler version of the camera near point derivation (default is true)

Protected Member Functions

Matrix4 buildFrustumProjection (Real left, Real right, Real bottom, Real top, Real near, Real far) const
 Builds a frustum matrix.
Matrix4 buildViewMatrix (const Vector3 &pos, const Vector3 &dir, const Vector3 &up) const
 Builds a view matrix.
void calculateB (const SceneManager &sm, const Camera &cam, const Light &light, const AxisAlignedBox &sceneBB, const AxisAlignedBox &receiverBB, PointListBody *out_bodyB) const
 Calculates the intersection bodyB.
Matrix4 calculateLiSPSM (const Matrix4 &lightSpace, const PointListBody &bodyB, const PointListBody &bodyLVS, const SceneManager &sm, const Camera &cam, const Light &light) const
 Calculates the LiSPSM projection matrix P.
void calculateLVS (const SceneManager &sm, const Camera &cam, const Light &light, const AxisAlignedBox &sceneBB, PointListBody *out_LVS) const
 Calculates the bodyLVS.
Real calculateNOpt (const Matrix4 &lightSpace, const AxisAlignedBox &bodyBABB_ls, const PointListBody &bodyLVS, const Camera &cam) const
 Calculates the distance between camera position and near clipping plane.
Real calculateNOptSimple (const PointListBody &bodyLVS, const Camera &cam) const
 Calculates a simpler version than the one above.
void calculateShadowMappingMatrix (const SceneManager &sm, const Camera &cam, const Light &light, Matrix4 *out_view, Matrix4 *out_proj, Camera *out_cam) const
 Calculates the standard shadow mapping matrix.
Vector3 calculateZ0_ls (const Matrix4 &lightSpace, const Vector3 &e, Real bodyB_zMax_ls, const Camera &cam) const
 Calculates the visible point on the near plane for the n_opt calculation.
Vector3 getLSProjViewDir (const Matrix4 &lightSpace, const Camera &cam, const PointListBody &bodyLVS) const
 Returns the projection view direction.
Vector3 getNearCameraPoint_ws (const Matrix4 &viewMatrix, const PointListBody &bodyLVS) const
 Returns a valid near-point seen by the camera.
Matrix4 transformToUnitCube (const Matrix4 &m, const PointListBody &body) const
 Transforms a given body to the unit cube (-1,-1,-1) / (+1,+1,+1) with a specific shadow matrix enabled.

Protected Attributes

ConvexBody mBodyB
Real mCosCamLightDirThreshold
 Threshold (cos angle) within which to start increasing the opt adjust as camera direction approaches light direction.
size_t mCurrentIteration
CameramLightFrustumCamera
 Temporary preallocated camera to set up a light frustum for clipping in FocusedShadowCameraSetup::calculateB.
bool mLightFrustumCameraCalculated
Real mOptAdjustFactor
 Warp factor adjustment.
Real mOptAdjustFactorTweak
 Extra calculated warp factor.
OptimalAdjustFactorList mOptimalAdjustFactors
PointListBody mPointListBodyB
PointListBody mPointListBodyLVS
uint mSplitCount
Real mSplitPadding
SplitPointList mSplitPoints
FrustummTempFrustum
 Temporary preallocated frustum to set up a projection matrix in calculateShadowMappingMatrix().
bool mUseAggressiveRegion
 Use tighter focus region?
bool mUseSimpleNOpt
 Use simple nopt derivation?

Static Protected Attributes

static const Matrix4 msLightSpaceToNormal
static const Matrix4 msNormalToLightSpace
 Transform to or from light space as defined by Wimmer et al.

Detailed Description

Parallel Split Shadow Map (PSSM) shadow camera setup.

Remarks:
A PSSM shadow system uses multiple shadow maps per light and maps each texture into a region of space, progressing away from the camera. As such it is most appropriate for directional light setups. This particular version also uses LiSPSM projection for each split to maximise the quality.
Note:
Because PSSM uses multiple shadow maps per light, you will need to increase the number of shadow textures available (via SceneManager) to match the number of shadow maps required (default is 3 per light).

Definition at line 56 of file OgreShadowCameraSetupPSSM.h.


Member Typedef Documentation

Definition at line 60 of file OgreShadowCameraSetupPSSM.h.

Definition at line 59 of file OgreShadowCameraSetupPSSM.h.


Constructor & Destructor Documentation

Constructor, defaults to 3 splits.


Member Function Documentation

Matrix4 Ogre::LiSPSMShadowCameraSetup::buildFrustumProjection ( Real  left,
Real  right,
Real  bottom,
Real  top,
Real  near,
Real  far 
) const [protected, inherited]

Builds a frustum matrix.

Remarks:
Builds a standard frustum matrix out of the distance info of the six frustum clipping planes.
Matrix4 Ogre::FocusedShadowCameraSetup::buildViewMatrix ( const Vector3 pos,
const Vector3 dir,
const Vector3 up 
) const [protected, inherited]

Builds a view matrix.

Remarks:
Builds a standard view matrix out of a given position, direction and up vector.
void Ogre::FocusedShadowCameraSetup::calculateB ( const SceneManager sm,
const Camera cam,
const Light light,
const AxisAlignedBox sceneBB,
const AxisAlignedBox receiverBB,
PointListBody out_bodyB 
) const [protected, inherited]

Calculates the intersection bodyB.

Remarks:
The intersection bodyB consists of the concatenation the cam frustum clipped by the scene bounding box followed by a convex hullification with the light's position and the clipping with the scene bounding box and the light frustum: ((V S) + l) S L (: convex intersection, +: convex hull operation). For directional lights the bodyB is assembled out of the camera frustum clipped by the scene bounding box followed by the extrusion of all available bodyB points towards the negative light direction. The rays are intersected by a maximum bounding box and added to the bodyB points to form the final intersection bodyB point list.
Parameters:
smScene manager.
camCurrently active camera.
lightCurrently active light.
sceneBBScene bounding box for clipping operations.
receiverBBBounding information for just the receivers.
out_bodyBFinal intersection bodyB point list.
Matrix4 Ogre::LiSPSMShadowCameraSetup::calculateLiSPSM ( const Matrix4 lightSpace,
const PointListBody bodyB,
const PointListBody bodyLVS,
const SceneManager sm,
const Camera cam,
const Light light 
) const [protected, inherited]

Calculates the LiSPSM projection matrix P.

Remarks:
The LiSPSM projection matrix will be built around the axis aligned bounding box of the intersection body B in light space. The distance between the near plane and the projection center is chosen in such a way (distance is set by the para- meter n) that the perspective error is the same on the near and far plane. In case P equals the identity matrix the algorithm falls back to a uniform shadow mapping matrix.
Parameters:
lightSpaceMatrix of the light space transformation
bodyBIntersection body B
bodyLVSIntersection body LVS (relevant space in front of the camera)
smScene manager
camCurrently active camera
lightCurrently active light
void Ogre::FocusedShadowCameraSetup::calculateLVS ( const SceneManager sm,
const Camera cam,
const Light light,
const AxisAlignedBox sceneBB,
PointListBody out_LVS 
) const [protected, inherited]

Calculates the bodyLVS.

Remarks:
Calculates the bodyLVS which consists of the convex intersection operation affecting the light frustum, the view frustum, and the current scene bounding box is used to find suitable positions in the viewer's frustum to build the rotation matrix L_r. This matrix is applied after the projection matrix L_p to avoid an accidental flip of the frustum orientation for views tilted with respect to the shadow map.
Parameters:
camCurrent viewer camera.
lightCurrent light.
sceneBBHolds all potential occluders / receivers as one single bounding box of the currently active scene node.
out_LVSIntersection body LVS (world coordinates).
Real Ogre::LiSPSMShadowCameraSetup::calculateNOpt ( const Matrix4 lightSpace,
const AxisAlignedBox bodyBABB_ls,
const PointListBody bodyLVS,
const Camera cam 
) const [protected, inherited]

Calculates the distance between camera position and near clipping plane.

Remarks:
n_opt determines the distance between light space origin (shadow camera position) and the near clipping plane to achieve an optimal perspective foreshortening effect. In this way the texel distribution over the shadow map is controlled.

Formula: d n_opt = --------------- sqrt(z1/z0) - 1

Parameters: d: distance between the near and the far clipping plane z0: located on the near clipping plane of the intersection body b z1: located on the far clipping plane with the same x/y values as z0

Note:
A positive value is applied as the distance between viewer and near clipping plane. In case null is returned uniform shadow mapping will be applied.
Parameters:
lightSpaceMatrix of the light space transformation
bodyBABB_lsBounding box of the transformed (light space) bodyB
bodyLVSPoint list of the bodyLVS which describes the scene space which is in front of the light and the camera
camCurrently active camera
Real Ogre::LiSPSMShadowCameraSetup::calculateNOptSimple ( const PointListBody bodyLVS,
const Camera cam 
) const [protected, inherited]

Calculates a simpler version than the one above.

void Ogre::FocusedShadowCameraSetup::calculateShadowMappingMatrix ( const SceneManager sm,
const Camera cam,
const Light light,
Matrix4 out_view,
Matrix4 out_proj,
Camera out_cam 
) const [protected, inherited]

Calculates the standard shadow mapping matrix.

Remarks:
Provides the view and projection matrix for standard shadow mapping.
Note:
You can choose which things you want to have: view matrix and/or projection matrix and/or shadow camera. Passing a NULL value as parameter ignores the generation of this specific value.
Parameters:
smScene manager.
camCurrently active camera.
lightCurrently active light.
out_viewCalculated uniform view shadow mapping matrix (may be NULL).
out_projCalculated uniform projection shadow mapping matrix (may be NULL).
out_camCalculated uniform shadow camera (may be NULL).
void Ogre::PSSMShadowCameraSetup::calculateSplitPoints ( uint  splitCount,
Real  nearDist,
Real  farDist,
Real  lambda = 0.95 
)

Calculate a new splitting scheme.

Parameters:
splitCountThe number of splits to use
nearDistThe near plane to use for the first split
farDistThe far plane to use for the last split
lambdaFactor to use to reduce the split size
Vector3 Ogre::LiSPSMShadowCameraSetup::calculateZ0_ls ( const Matrix4 lightSpace,
const Vector3 e,
Real  bodyB_zMax_ls,
const Camera cam 
) const [protected, inherited]

Calculates the visible point on the near plane for the n_opt calculation.

Remarks:
z0 lies on the parallel plane to the near plane through e and on the near plane of the frustum C (plane z = bodyB_zMax_ls) and on the line x = e.x.
Parameters:
lightSpaceMatrix of the light space transformation
eThe LiSPSM parameter e is located near or on the near clipping plane of the LiSPSM frustum C
bodyB_zMax_lsMaximum z-value of the light space bodyB bounding box
camCurrently active camera

Sets the threshold between the camera and the light direction below which the LiSPSM projection is 'flattened', since coincident light and camera projections cause problems with the perspective skew.

Vector3 Ogre::FocusedShadowCameraSetup::getLSProjViewDir ( const Matrix4 lightSpace,
const Camera cam,
const PointListBody bodyLVS 
) const [protected, inherited]

Returns the projection view direction.

Remarks:
After the matrix L_p is applied the orientation of the light space may tilt for non-identity projections. To prevent a false shadow cast the real view direction is evaluated and applied to the light matrix L.
Parameters:
lightSpaceMatrix of the light space transformation.
camCurrent viewer camera.
bodyLVSIntersection body LVS (relevant space in front of the camera).
Vector3 Ogre::FocusedShadowCameraSetup::getNearCameraPoint_ws ( const Matrix4 viewMatrix,
const PointListBody bodyLVS 
) const [protected, inherited]

Returns a valid near-point seen by the camera.

Remarks:
Returns a point that is situated near the camera by analyzing the bodyLVS that contains all the relevant scene space in front of the light and the camera in a point list array. The view matrix is relevant because the nearest point in front of the camera should be determined.
Parameters:
viewMatrixView matrix of the current camera.
bodyLVSIntersection body LVS (relevant space in front of the camera).

Returns the optimal adjust factor for a given split.

Definition at line 117 of file OgreShadowCameraSetupPSSM.h.

Overridden, recommended internal use only since depends on current iteration.

Reimplemented from Ogre::LiSPSMShadowCameraSetup.

virtual void Ogre::PSSMShadowCameraSetup::getShadowCamera ( const Ogre::SceneManager sm,
const Ogre::Camera cam,
const Ogre::Viewport vp,
const Ogre::Light light,
Ogre::Camera texCam,
size_t  iteration 
) const [virtual]

Returns a LiSPSM shadow camera with PSSM splits base on iteration.

Reimplemented from Ogre::LiSPSMShadowCameraSetup.

Get the number of splits.

Definition at line 106 of file OgreShadowCameraSetupPSSM.h.

Get the padding factor to apply to the near & far distances when matching up splits to one another, to avoid 'cracks'.

Definition at line 104 of file OgreShadowCameraSetupPSSM.h.

Returns the calculated split points.

Definition at line 113 of file OgreShadowCameraSetupPSSM.h.

Definition at line 305 of file OgreShadowCameraSetupFocused.h.

virtual bool Ogre::LiSPSMShadowCameraSetup::getUseSimpleOptimalAdjust ( ) const [virtual, inherited]

Gets whether or not to use a slightly simpler version of the camera near point derivation (default is true)

Definition at line 228 of file OgreShadowCameraSetupLiSPSM.h.

template<class Alloc >
void Ogre::AllocatedObject< Alloc >::operator delete ( void *  ptr) [inherited]

Definition at line 96 of file OgreMemoryAllocatedObject.h.

template<class Alloc >
void Ogre::AllocatedObject< Alloc >::operator delete ( void *  ptr,
void *   
) [inherited]

Definition at line 102 of file OgreMemoryAllocatedObject.h.

template<class Alloc >
void Ogre::AllocatedObject< Alloc >::operator delete ( void *  ptr,
const char *  ,
int  ,
const char *   
) [inherited]

Definition at line 108 of file OgreMemoryAllocatedObject.h.

template<class Alloc >
void Ogre::AllocatedObject< Alloc >::operator delete[] ( void *  ptr) [inherited]

Definition at line 113 of file OgreMemoryAllocatedObject.h.

template<class Alloc >
void Ogre::AllocatedObject< Alloc >::operator delete[] ( void *  ptr,
const char *  ,
int  ,
const char *   
) [inherited]

Definition at line 119 of file OgreMemoryAllocatedObject.h.

template<class Alloc >
void* Ogre::AllocatedObject< Alloc >::operator new ( size_t  sz,
const char *  file,
int  line,
const char *  func 
) [inherited]

operator new, with debug line info

Definition at line 68 of file OgreMemoryAllocatedObject.h.

template<class Alloc >
void* Ogre::AllocatedObject< Alloc >::operator new ( size_t  sz) [inherited]

Definition at line 73 of file OgreMemoryAllocatedObject.h.

template<class Alloc >
void* Ogre::AllocatedObject< Alloc >::operator new ( size_t  sz,
void *  ptr 
) [inherited]

placement operator new

Definition at line 79 of file OgreMemoryAllocatedObject.h.

template<class Alloc >
void* Ogre::AllocatedObject< Alloc >::operator new[] ( size_t  sz,
const char *  file,
int  line,
const char *  func 
) [inherited]

array operator new, with debug line info

Definition at line 86 of file OgreMemoryAllocatedObject.h.

template<class Alloc >
void* Ogre::AllocatedObject< Alloc >::operator new[] ( size_t  sz) [inherited]

Definition at line 91 of file OgreMemoryAllocatedObject.h.

virtual void Ogre::LiSPSMShadowCameraSetup::setCameraLightDirectionThreshold ( Degree  angle) [virtual, inherited]

Sets the threshold between the camera and the light direction below which the LiSPSM projection is 'flattened', since coincident light and camera projections cause problems with the perspective skew.

Remarks:
For example, setting this to 20 degrees will mean that as the difference between the light and camera direction reduces from 20 degrees to 0 degrees, the perspective skew will be proportionately removed.
void Ogre::PSSMShadowCameraSetup::setOptimalAdjustFactor ( size_t  splitIndex,
Real  factor 
)

Set the LiSPSM optimal adjust factor for a given split (call after configuring splits).

virtual void Ogre::LiSPSMShadowCameraSetup::setOptimalAdjustFactor ( Real  n) [virtual, inherited]

Adjusts the parameter n to produce optimal shadows.

Remarks:
The smaller the parameter n, the stronger the perspective warping effect. The consequence of a stronger warping is that the near shadows will gain quality while the far ones will lose it. Depending on your scene and light types you may want to tweak this value - for example directional lights tend to benefit from higher values of n than other types of light, especially if you expect to see more distant shadows (say if the viewpoint is higher above the ground plane). Remember that you can supply separate ShadowCameraSetup instances configured differently per light if you wish.
Parameters:
nThe adjustment factor - default is 0.1f.

Definition at line 216 of file OgreShadowCameraSetupLiSPSM.h.

Set the padding factor to apply to the near & far distances when matching up splits to one another, to avoid 'cracks'.

Definition at line 99 of file OgreShadowCameraSetupPSSM.h.

Manually configure a new splitting scheme.

Parameters:
newSplitPointsA list which is splitCount + 1 entries long, containing the split points. The first value is the near point, the last value is the far point, and each value in between is both a far point of the previous split, and a near point for the next one.
void Ogre::FocusedShadowCameraSetup::setUseAggressiveFocusRegion ( bool  aggressive) [inherited]

Sets whether or not to use the more aggressive approach to deciding on the focus region or not.

Note:
There are 2 approaches that can be used to define the focus region, the more aggressive way introduced by Wimmer et al, or the original way as described in Stamminger et al. Wimmer et al's way tends to come up with a tighter focus region but in rare cases (mostly highly glancing angles) can cause some shadow casters to be clipped incorrectly. By default the more aggressive approach is used since it leads to significantly better results in most cases, but if you experience clipping issues, you can use the less aggressive version.
Parameters:
aggressiveTrue to use the more aggressive approach, false otherwise.

Definition at line 303 of file OgreShadowCameraSetupFocused.h.

virtual void Ogre::LiSPSMShadowCameraSetup::setUseSimpleOptimalAdjust ( bool  s) [virtual, inherited]

Sets whether or not to use a slightly simpler version of the camera near point derivation (default is true)

Definition at line 224 of file OgreShadowCameraSetupLiSPSM.h.

Matrix4 Ogre::FocusedShadowCameraSetup::transformToUnitCube ( const Matrix4 m,
const PointListBody body 
) const [protected, inherited]

Transforms a given body to the unit cube (-1,-1,-1) / (+1,+1,+1) with a specific shadow matrix enabled.

Remarks:
Transforms a given point list body object with the matrix m and then maps its extends to a (-1,-1,-1) / (+1,+1,+1) unit cube.
Parameters:
mTransformation matrix applied on the point list body.
bodyContains the points of the extends of all valid scene elements which are mapped to the unit cube.

Member Data Documentation

ConvexBody Ogre::FocusedShadowCameraSetup::mBodyB [mutable, protected, inherited]

Definition at line 145 of file OgreShadowCameraSetupFocused.h.

Threshold (cos angle) within which to start increasing the opt adjust as camera direction approaches light direction.

Definition at line 108 of file OgreShadowCameraSetupLiSPSM.h.

Definition at line 68 of file OgreShadowCameraSetupPSSM.h.

Temporary preallocated camera to set up a light frustum for clipping in FocusedShadowCameraSetup::calculateB.

Definition at line 78 of file OgreShadowCameraSetupFocused.h.

Definition at line 79 of file OgreShadowCameraSetupFocused.h.

Warp factor adjustment.

Definition at line 102 of file OgreShadowCameraSetupLiSPSM.h.

Extra calculated warp factor.

Definition at line 106 of file OgreShadowCameraSetupLiSPSM.h.

Definition at line 65 of file OgreShadowCameraSetupPSSM.h.

Definition at line 146 of file OgreShadowCameraSetupFocused.h.

Definition at line 147 of file OgreShadowCameraSetupFocused.h.

const Matrix4 Ogre::FocusedShadowCameraSetup::msLightSpaceToNormal [static, protected, inherited]

Definition at line 69 of file OgreShadowCameraSetupFocused.h.

const Matrix4 Ogre::FocusedShadowCameraSetup::msNormalToLightSpace [static, protected, inherited]

Transform to or from light space as defined by Wimmer et al.

Remarks:
Point and spot lights need to be converted to directional lights to enable a 1:1 light mapping. Otherwise a directional light may become a point light or a point sink (opposite of a light source) or point/spot lights may become directional lights or light sinks. The light direction is always -y.

Definition at line 68 of file OgreShadowCameraSetupFocused.h.

Definition at line 63 of file OgreShadowCameraSetupPSSM.h.

Definition at line 66 of file OgreShadowCameraSetupPSSM.h.

Definition at line 64 of file OgreShadowCameraSetupPSSM.h.

Temporary preallocated frustum to set up a projection matrix in calculateShadowMappingMatrix().

Definition at line 74 of file OgreShadowCameraSetupFocused.h.

Use tighter focus region?

Definition at line 82 of file OgreShadowCameraSetupFocused.h.

bool Ogre::LiSPSMShadowCameraSetup::mUseSimpleNOpt [protected, inherited]

Use simple nopt derivation?

Definition at line 104 of file OgreShadowCameraSetupLiSPSM.h.


The documentation for this class was generated from the following file:

Copyright © 2012 Torus Knot Software Ltd
Creative Commons License
This work is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.
Last modified Mon Jul 27 2020 13:41:31