Ogre::LiSPSMShadowCameraSetup Class Reference
[Scene]

Implements the Light Space Perspective Shadow Mapping Algorithm. More...

#include <OgreShadowCameraSetupLiSPSM.h>

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

List of all members.

Public Member Functions

 LiSPSMShadowCameraSetup (void)
 Default constructor.
virtual ~LiSPSMShadowCameraSetup (void)
 Default destructor.
virtual void getShadowCamera (const SceneManager *sm, const Camera *cam, const Viewport *vp, const Light *light, Camera *texCam, size_t iteration) const
 Returns a LiSPSM shadow camera.
virtual void setOptimalAdjustFactor (Real n)
 Adjusts the parameter n to produce optimal shadows.
virtual Real getOptimalAdjustFactor () const
 Get the parameter n used to produce optimal shadows.
virtual void setUseSimpleOptimalAdjust (bool s)
 Sets whether or not to use a slightly simpler version of the camera near point derivation (default is true).
virtual bool getUseSimpleOptimalAdjust () const
 Gets whether or not to use a slightly simpler version of the camera near point derivation (default is true).
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.
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.
void setUseAggressiveFocusRegion (bool aggressive)
 Sets whether or not to use the more aggressive approach to deciding on the focus region or not.
bool getUseAggressiveFocusRegion () const
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)
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 *)

Protected Member Functions

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.
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.
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.
Matrix4 buildFrustumProjection (Real left, Real right, Real bottom, Real top, Real near, Real far) const
 Builds a frustum matrix.
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.
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.
void calculateLVS (const SceneManager &sm, const Camera &cam, const Light &light, const AxisAlignedBox &sceneBB, PointListBody *out_LVS) const
 Calculates the bodyLVS.
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.
Matrix4 buildViewMatrix (const Vector3 &pos, const Vector3 &dir, const Vector3 &up) const
 Builds a view matrix.

Protected Attributes

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

Static Protected Attributes

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

Detailed Description

Implements the Light Space Perspective Shadow Mapping Algorithm.

Remarks:
Implements the LiSPSM algorithm for an advanced shadow map generation. LiSPSM was developed by Michael Wimmer, Daniel Scherzer and Werner Purgathofer of the TU Wien. The algorithm was presented on the Eurographics Symposium on Rendering 2004.
Note:
Shadow mapping was introduced by Williams in 1978. First a depth image is rendered from the light's view and compared in a second pass with depth values of the normal camera view. In case the depth camera's depth value is greater than the depth seen by the light the fragment lies in the shadow. The concept has a major draw back named perspective aliasing. The shadow map distri- butes the samples uniformly meaning the position of the viewer is ignored. For the viewer however the perspective projection affects near objects to be displayed bigger than further away objects. The same thing happens with the shadow map texels: Near shadows appear very coarse and far away shadows are perfectly sampled. In 2002 Stamminger et al. presented an algorithm called Perspective Shadow Maps (PSM). PSM battles the perspective aliasing by distributing 50% of the shadow map texels for objects in the range of <near clipping="" plane>=""> to <near clipping plane * 2> which inverts the problem: The shadows near the viewer are perfectly sampled, however far away shadow may contain aliasing artefacts. A near clipping plane may be a problem. But this is not the only one. In the post-perspective space the light sources are non-intuitively mapped: Directional lights may become point light and point lights may become directional lights. Also light sinks (opposite of a light source) may appear. Another problem are shadow casters located behind the viewer. In post-projective space objects behind the viewer are mapped in front of him with a flipped up-vector. LiSPSM battles the light source problem of the post-projective space by rearranging the light space before transformation in such a way that no special cases appear. This is done by converting point/spot lights into directional lights. The light space is arranged in such a way that the light direction equals the inverse UNIT_Y. In this combination the directional light will neither change its type nor its direction. Furthermore all visible objects and shadow casters affecting the user's visible area lie in front of the shadow camera: After building the intersection body that contains all these objects (body intersection building was introduced with PSM; have a look at the description for the method "calculateB" for further info) a frustum around the body's light space bounding box is created. A parameter (called 'n') automatically adjusts the shadow map sample distribution by specifying the frustum's view point - near plane which affects the perspective warp. In case the distance is small the perspecive warp will be strong. As a consequence near objects will gain quality. However there are still problems. PSM as well as LiSPSM only devote to minimize perspective aliasing. Projection aliasing is still a problem, also 'swimming artefacts' still occur. The LiSPSM quality distribution is very good but not the best available: Some sources say logarithmic shadow mapping is the non plus ultra, however others reject this thought. There is a research project on logarithmic shadow maps. The web page url is http://gamma.cs.unc.edu/logsm/. However there is no techical report available yet (Oct 23rd, 2006).
More information can be found on the webpage of the TU Wien: http://www.cg.tuwien.ac.at/research/vr/lispsm/
Original implementation by Matthias Fink <matthias.fink@web.de>, 2006.

Definition at line 98 of file OgreShadowCameraSetupLiSPSM.h.


Constructor & Destructor Documentation

Ogre::LiSPSMShadowCameraSetup::LiSPSMShadowCameraSetup ( void   ) 

Default constructor.

Remarks:
Nothing done here.
virtual Ogre::LiSPSMShadowCameraSetup::~LiSPSMShadowCameraSetup ( void   )  [virtual]

Default destructor.

Remarks:
Nothing done here.

Member Function Documentation

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

Builds a frustum matrix.

Remarks:
Builds a standard frustum matrix out of the distance infos 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:
sm,: scene manager
cam,: currently active camera
light,: currently active light
sceneBB,: scene bounding box for clipping operations
receiverAABB,: bounding information for just the receivers
out_bodyB,: final 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]

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:
lightSpace,: matrix of the light space transformation
bodyB,: intersection body B
bodyLVS,: intersection body LVS (relevant space in front of the camera)
sm,: scene manager
cam,: currently active camera
light,: currently 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:
scene,: holds all potential occluders / receivers as one single bounding box of the currently active scene node
cam,: current viewer camera
light,: current light
out_LVS,: intersection body LVS (world coordinates)
Real Ogre::LiSPSMShadowCameraSetup::calculateNOpt ( const Matrix4 lightSpace,
const AxisAlignedBox bodyBABB_ls,
const PointListBody bodyLVS,
const Camera cam 
) const [protected]

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:
lightSpace,: matrix of the light space transformation
bodyBABB_ls,: bounding box of the transformed (light space) bodyB
bodyLVS,: point list of the bodyLVS which describes the scene space which is in front of the light and the camera
cam,: currently active camera
Real Ogre::LiSPSMShadowCameraSetup::calculateNOptSimple ( const PointListBody bodyLVS,
const Camera cam 
) const [protected]

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:
sm,: scene manager
cam,: currently active camera
light,: currently active light
out_view,: calculated uniform view shadow mapping matrix (may be NULL)
out_proj,: calculated uniform projection shadow mapping matrix (may be NULL)
out_cam,: calculated uniform shadow camera (may be NULL)
Vector3 Ogre::LiSPSMShadowCameraSetup::calculateZ0_ls ( const Matrix4 lightSpace,
const Vector3 e,
Real  bodyB_zMax_ls,
const Camera cam 
) const [protected]

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:
lightSpace,: matrix of the light space transformation
e,: the LiSPSM parameter e is located near or on the near clipping plane of the LiSPSM frustum C
bodyB_zMax_ls,: maximum z-value of the light space bodyB bounding box
cam,: currently active camera
virtual Degree Ogre::LiSPSMShadowCameraSetup::getCameraLightDirectionThreshold (  )  const [virtual]

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:
lightSpace,: matrix of the light space transformation
cam,: current viewer camera
bodyLVS,: intersection 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:
viewMatrix,: view matrix of the current camera
bodyLVS,: intersection body LVS (relevant space in front of the camera)
virtual Real Ogre::LiSPSMShadowCameraSetup::getOptimalAdjustFactor (  )  const [virtual]

Get the parameter n used to produce optimal shadows.

See also:
setOptimalAdjustFactor

Reimplemented in Ogre::PSSMShadowCameraSetup.

Definition at line 220 of file OgreShadowCameraSetupLiSPSM.h.

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

Returns a LiSPSM shadow camera.

Remarks:
Builds and returns a LiSPSM shadow camera. More information can be found on the webpage of the TU Wien: http://www.cg.tuwien.ac.at/research/vr/lispsm/

Reimplemented from Ogre::FocusedShadowCameraSetup.

Reimplemented in Ogre::PSSMShadowCameraSetup.

bool Ogre::FocusedShadowCameraSetup::getUseAggressiveFocusRegion (  )  const [inherited]

Definition at line 280 of file OgreShadowCameraSetupFocused.h.

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

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,
const char *  ,
int  ,
const char *   
) [inherited]

Definition at line 107 of file OgreMemoryAllocatedObject.h.

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

Definition at line 101 of file OgreMemoryAllocatedObject.h.

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

Definition at line 95 of file OgreMemoryAllocatedObject.h.

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

Definition at line 118 of file OgreMemoryAllocatedObject.h.

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

Definition at line 112 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 78 of file OgreMemoryAllocatedObject.h.

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

Definition at line 72 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 67 of file OgreMemoryAllocatedObject.h.

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

Definition at line 90 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 85 of file OgreMemoryAllocatedObject.h.

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

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.
virtual void Ogre::LiSPSMShadowCameraSetup::setOptimalAdjustFactor ( Real  n  )  [virtual]

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:
n The adjustment factor - default is 0.1f.

Definition at line 216 of file OgreShadowCameraSetupLiSPSM.h.

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:
aggressive True to use the more aggressive approach, false otherwise.

Definition at line 278 of file OgreShadowCameraSetupFocused.h.

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

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:
m,: transformation matrix applied on the point list body
body,: contains 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 144 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.

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

Definition at line 77 of file OgreShadowCameraSetupFocused.h.

Definition at line 78 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 145 of file OgreShadowCameraSetupFocused.h.

Definition at line 146 of file OgreShadowCameraSetupFocused.h.

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

Definition at line 68 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 67 of file OgreShadowCameraSetupFocused.h.

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

Definition at line 73 of file OgreShadowCameraSetupFocused.h.

Use tighter focus region?

Definition at line 81 of file OgreShadowCameraSetupFocused.h.

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 Fri May 25 23:40:18 2012