RenderPipeline. More...

#include "pssmCameraRig.h"

Public Types
enum	CoordinateOrigin { UpperLeft = 0, UpperRight, LowerLeft, LowerRight }

Public Member Functions
	PSSMCameraRig (size_t num_splits)
	Constructs a new PSSM camera rig. More...

	~PSSMCameraRig ()
	Destructs the camera rig. More...

NodePath	get_camera (size_t index)
	Returns the n-th camera. More...

const PTA_LMatrix4 &	get_mvp_array ()
	Returns a handle to the MVP array. More...

const PTA_LVecBase2 &	get_nearfar_array ()
	Returns a handle to the near and far planes array. More...

void	reparent_to (NodePath parent)
	Reparents the camera rig. More...

void	reset_film_size_cache ()
	Resets the film size cache. More...

void	set_border_bias (float bias)
	Sets the border bias for each split. More...

void	set_logarithmic_factor (float factor)
	Sets the logarithmic factor. More...

void	set_pssm_distance (float distance)
	RenderPipeline. More...

void	set_resolution (size_t resolution)
	Sets the resolution of each split. More...

void	set_sun_distance (float distance)
	Sets the suns distance. More...

void	set_use_fixed_film_size (bool flag)
	Sets whether to use a fixed film size. More...

void	set_use_stable_csm (bool flag)
	Sets whether to use stable CSM snapping. More...

void	update (NodePath cam_node, const LVecBase3 &light_vector)
	Updates the PSSM camera rig. More...

Detailed Description

RenderPipeline.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 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.

Definition at line 59 of file pssmCameraRig.h.

Constructor & Destructor Documentation

◆ PSSMCameraRig()

PSSMCameraRig::PSSMCameraRig ( size_t 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.

Parameters

num_splits Amount of PSSM splits

Definition at line 48 of file pssmCameraRig.cxx.

◆ ~PSSMCameraRig()

PSSMCameraRig::~PSSMCameraRig ( )

Destructs the camera rig.

This destructs the camera rig, cleaning up all used resources.

Definition at line 67 of file pssmCameraRig.cxx.

Member Function Documentation

◆ get_camera()

NodePath PSSMCameraRig::get_camera ( size_t index )

inline

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.

Parameters

index Index of the camera.

Returns: [description]

Definition at line 178 of file pssmCameraRig.I.

◆ get_mvp_array()

const PTA_LMatrix4 & PSSMCameraRig::get_mvp_array ( )

inline

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.

Returns: view-projection matrix array

Definition at line 225 of file pssmCameraRig.I.

◆ get_nearfar_array()

const PTA_LVecBase2 & PSSMCameraRig::get_nearfar_array ( )

inline

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.

Returns: Array of near and far planes

Definition at line 241 of file pssmCameraRig.I.

◆ reparent_to()

void PSSMCameraRig::reparent_to ( 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.

Parameters

parent Parent node path

Definition at line 105 of file pssmCameraRig.cxx.

◆ reset_film_size_cache()

void PSSMCameraRig::reset_film_size_cache ( )

inline

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.

Definition at line 156 of file pssmCameraRig.I.

◆ set_border_bias()

void PSSMCameraRig::set_border_bias ( float bias )

inline

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.

Parameters

bias	Border bias

Definition at line 138 of file pssmCameraRig.I.

◆ set_logarithmic_factor()

void PSSMCameraRig::set_logarithmic_factor ( float factor )

inline

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.

Parameters

factor The logarithmic factor

Definition at line 77 of file pssmCameraRig.I.

◆ set_pssm_distance()

void PSSMCameraRig::set_pssm_distance ( float distance )

inline

RenderPipeline.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 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.

Parameters

distance Maximum distance in world space

Definition at line 37 of file pssmCameraRig.I.

◆ set_resolution()

void PSSMCameraRig::set_resolution ( size_t resolution )

inline

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.

Parameters

resolution The resolution of each split.

Definition at line 108 of file pssmCameraRig.I.

◆ set_sun_distance()

void PSSMCameraRig::set_sun_distance ( float distance )

inline

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.

Parameters

distance The sun distance

Definition at line 56 of file pssmCameraRig.I.

◆ set_use_fixed_film_size()

void PSSMCameraRig::set_use_fixed_film_size ( bool flag )

inline

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.

Parameters

flag	Whether to use a fixed film size

Definition at line 93 of file pssmCameraRig.I.

◆ set_use_stable_csm()

void PSSMCameraRig::set_use_stable_csm ( bool flag )

inline

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.

Parameters

flag	Whether to use stable CSM snapping

Definition at line 122 of file pssmCameraRig.I.

◆ update()

void PSSMCameraRig::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.

Parameters

cam_node	Target camera node
light_vector	The vector from the light to any point

Definition at line 364 of file pssmCameraRig.cxx.

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

contrib/src/rplight/pssmCameraRig.h
contrib/src/rplight/pssmCameraRig.cxx
contrib/src/rplight/pssmCameraRig.I

Public Types

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ PSSMCameraRig()

◆ ~PSSMCameraRig()

Member Function Documentation

◆ get_camera()

◆ get_mvp_array()

◆ get_nearfar_array()

◆ reparent_to()

◆ reset_film_size_cache()

◆ set_border_bias()

◆ set_logarithmic_factor()

◆ set_pssm_distance()

◆ set_resolution()

◆ set_sun_distance()

◆ set_use_fixed_film_size()

◆ set_use_stable_csm()

◆ update()