Public Member Functions | List of all members
PSSMCameraRig Class Reference

Main class used for handling PSSM. More...

Public Member Functions

 __init__ (const PSSMCameraRig)
 __init__ (int num_splits)
 Constructs a new PSSM camera rig. More...
NodePath getCamera (int index)
 Returns the n-th camera. More...
const PTALMatrix4 getMvpArray ()
 Returns a handle to the MVP array. More...
const PTALVecBase2 getNearfarArray ()
 Returns a handle to the near and far planes array. More...
 reparentTo (NodePath parent)
 Reparents the camera rig. More...
 resetFilmSizeCache ()
 Resets the film size cache. More...
 setBorderBias (float bias)
 Sets the border bias for each split. More...
 setLogarithmicFactor (float factor)
 Sets the logarithmic factor. More...
 setPssmDistance (float distance)
 Sets the maximum pssm distance. More...
 setResolution (int resolution)
 Sets the resolution of each split. More...
 setSunDistance (float distance)
 Sets the suns distance. More...
 setUseFixedFilmSize (bool flag)
 Sets whether to use a fixed film size. More...
 setUseStableCsm (bool flag)
 Sets whether to use stable CSM snapping. More...
 update (NodePath cam_node, const LVecBase3 light_vector)
 Updates the PSSM camera rig. More...

Detailed Description

Main class used for handling PSSM.

This is the main class for supporting PSSM, it is used by the PSSM plugin to compute the position of the splits.

It supports handling a varying amount of cameras, and fitting those cameras into the main camera frustum, to render distant shadows. It also supports various optimizations for fitting the frustum, e.g. rotating the sources to get a better coverage.

It also provides methods to get arrays of data about the used cameras view-projection matrices and their near and far plane, which is required for processing the data in the shadow sampling shader.

In this class, there is often referred to "Splits" or also called "Cascades". These denote the different cameras which are used to split the frustum, and are a common term related to the PSSM algorithm.

To understand the functionality of this class, a detailed knowledge of the PSSM algorithm is helpful.

Member Function Documentation

◆ __init__() [1/2]

__init__ ( const  PSSMCameraRig)

◆ __init__() [2/2]

__init__ ( int  num_splits)

Constructs a new PSSM camera rig.

This constructs a new camera rig, with a given amount of splits. The splits can not be changed later on. Splits are also called Cascades.

An assertion will be triggered if the splits are below zero.

num_splitsAmount of PSSM splits

◆ getCamera()

NodePath getCamera ( int  index)

Returns the n-th camera.

This returns the n-th camera of the camera rig, which can be used for various stuff like showing its frustum, passing it as a shader input, and so on.

The first camera is the camera which is the camera of the first split, which is the split closest to the camera. All cameras follow in descending order until to the last camera, which is the split furthest away from the camera.

If an invalid index is passed, an assertion is thrown.

indexIndex of the camera.

◆ getMvpArray()

const PTALMatrix4 getMvpArray ( )

Returns a handle to the MVP array.

This returns a handle to the array of view-projection matrices of the different splits. This can be used for computing shadows. The array is a PTALMatrix4 and thus can be directly bound to a shader.

view-projection matrix array

◆ getNearfarArray()

const PTALVecBase2 getNearfarArray ( )

Returns a handle to the near and far planes array.

This returns a handle to the near and far plane array. Each split has an entry in the array, whereas the x component of the vecto denotes the near plane, and the y component denotes the far plane of the split.

This is required because the near and far planes of the splits change constantly. To access them in a shader, the shader needs access to the array.

Array of near and far planes

◆ reparentTo()

reparentTo ( NodePath  parent)

Reparents the camera rig.

This reparents all cameras to the given parent. Usually the parent will be ShowBase.render. The parent should be the same node where the main camera is located in, too.

If an empty parrent is passed, an assertion will get triggered.

parentParent node path

◆ resetFilmSizeCache()

resetFilmSizeCache ( )

Resets the film size cache.

In case PSSMCameraRig::set_use_fixed_film_size is used, this resets the film size cache. This might lead to a small "jump" in the shadows, because the film size changes, however it leads to a better shadow distribution.

This is the case because when using a fixed film size, the cache will get bigger and bigger, whenever the camera moves to a grazing angle. However, when moving back to a normal angle, the film size cache still stores this big angle, and thus the splits will have a much bigger film size than actualy required. To prevent this, call this method once in a while, so an optimal distribution is ensured.

◆ setBorderBias()

setBorderBias ( float  bias)

Sets the border bias for each split.

This sets the border bias for every split. This increases each splits frustum by multiplying it by (1 + bias), and helps reducing artifacts at the borders of the splits. Artifacts can occur when the bias is too low, because then the filtering will go over the bounds of the split, producing invalid results.

If the bias is below zero, an assertion is thrown.

biasBorder bias

◆ setLogarithmicFactor()

setLogarithmicFactor ( float  factor)

Sets the logarithmic factor.

This sets the logarithmic factor, which is the core of the algorithm. PSSM splits the camera frustum based on a linear and a logarithmic factor. While a linear factor provides a good distribution, it often is not applicable for wider distances. A logarithmic distribution provides a better distribution at distance, but suffers from splitting in the near areas.

The logarithmic factor mixes the logarithmic and linear split distribution, to get the best of both. A greater factor will make the distribution more logarithmic, while a smaller factor will make it more linear.

If the factor is below zero, an ssertion is triggered.

factorThe logarithmic factor

◆ setPssmDistance()

setPssmDistance ( float  distance)

Sets the maximum pssm distance.

This sets the maximum distance in world space until which shadows are rendered. After this distance, no shadows will be rendered.

If the distance is below zero, an assertion is triggered.

distanceMaximum distance in world space

◆ setResolution()

setResolution ( int  resolution)

Sets the resolution of each split.

This sets the resolution of each split. Currently it is equal for each split. This is required when using PSSMCameraRig::set_use_stable_csm, to compute how bix a texel is.

It has to match the y-resolution of the pssm shadow map. If an invalid resolution is triggered, an assertion is thrown.

resolutionThe resolution of each split.

◆ setSunDistance()

setSunDistance ( float  distance)

Sets the suns distance.

This sets the distance the cameras will have from the cameras frustum. This prevents far objects from having no shadows, which can occur when these objects are between the cameras frustum and the sun, but not inside of the cameras frustum. Setting the sun distance high enough will move the cameras away from the camera frustum, being able to cover those distant objects too.

If the sun distance is set too high, artifacts will occur due to the reduced range of depth. If a value below zero is passed, an assertion will get triggered.

distanceThe sun distance

◆ setUseFixedFilmSize()

setUseFixedFilmSize ( bool  flag)

Sets whether to use a fixed film size.

This controls if a fixed film size should be used. This will cause the camera rig to cache the current film size, and only change it in case it gets too small. This provides less flickering when moving, because the film size will stay roughly constant. However, to prevent the cached film size getting too big, one should call PSSMCameraRig::reset_film_size once in a while, otherwise there might be a lot of wasted space.

flagWhether to use a fixed film size

◆ setUseStableCsm()

setUseStableCsm ( bool  flag)

Sets whether to use stable CSM snapping.

This option controls if stable CSM snapping should be used. When the option is enabled, all splits will snap to their texels, so that when moving, no flickering will occur. However, this only works when the splits do not change their film size, rotation and angle.

flagWhether to use stable CSM snapping

◆ update()

update ( NodePath  cam_node,
const LVecBase3  light_vector 

Updates the PSSM camera rig.

This updates the rig with an updated camera position, and a given light vector. This should be called on a per-frame basis. It will reposition all camera sources to fit the frustum based on the pssm distribution.

The light vector should be the vector from the light source, not the vector to the light source.

cam_nodeTarget camera node
light_vectorThe vector from the light to any point