.. _shadow-mapping:
Shadow mapping
==============

In Met.3D we use shadow mapping to render shadows of actors, which is important to provide spatial information about the actor's location.
Shadows are cast from the first directional :ref:`light-actor` in the scene.
Each actor in the scene can toggle, whether they receive and cast shadows or not.


Cascaded shadow maps
--------------------

Shadow mapping in Met.3D is implemented as cascaded shadow maps with 3 cascades.
The cascades split the view-frustum of the camera into 3 parts, each with their own shadow-map.
Internally, the cascades are saved in a ``GL_TEXTURE_2D_MULTISAMPLE_ARRAY`` in the ``GL_DEPTH_COMPONENT32F`` format.
Each level in the array texture corresponds to one cascade of the shadow map.
This would allow us to either increase or reduce the number of cascades Met.3D uses, but for now this is fixed at 3.



.. figure:: ./figs/cascaded_shadow_maps.svg
    :figwidth: 100%
    :align: left
    :alt: Cascading shadow maps as implemented in Met.3D


Volumetric shadows
------------------

The :ref:`raycaster-actor` can compute volumetric lighting in DVR mode.
This information is stored inside a volumetric light-map, which is a ``GL_TEXTURE_3D`` in the ``GL_RGBA8`` format.
The ``rgb`` channels store the light information, as in light color and intensity, while the ``a`` channel stores the "shadow" percentage of the main directional light.
This volumetric light-map is only rendered once, unless it requires to be updated due to changed parameters.
Once updated, it is passed to the scene view, which uses it to shade the remaining scene geometry.
In the 3-D pass, the volumetric light-map is applied after the cascaded shadow maps.
We cast a ray from the fragments world position through the volumetric light-map, to get its entry location into the volume.
The "shadow" percentage stored in the alpha channel is then projected onto the fragment using its entry location and the light direction.
If the fragment lies inside the volume no projection is necessary. 
Instead the volume is sampled directly.