PSSMCameraRig

class PSSMCameraRig

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.

Inheritance diagram

PSSMCameraRig(std::size_t num_splits)

PSSMCameraRig(PSSMCameraRig const&) = default

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.

NodePath get_camera(std::size_t index)

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.

PTA_LMatrix4 const &get_mvp_array(void)

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.

PTA_LVecBase2 const &get_nearfar_array(void)

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.

void reparent_to(NodePath parent)

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.

void reset_film_size_cache(void)

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.

void set_border_bias(float bias)

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.

void set_logarithmic_factor(float 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.

void set_pssm_distance(float 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.

void set_resolution(std::size_t resolution)

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.

void set_sun_distance(float 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.

void set_use_fixed_film_size(bool flag)

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.

void set_use_stable_csm(bool flag)

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.

void update(NodePath cam_node, LVecBase3 const &light_vector)

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.