box3d/samples/gfx/shadow.h
Erin Catto f42be210a2
64-bit hashes (#126)
- ContactEvent sample
- Improved shadows
- #120 
- Triangle collision fixes
2026-08-11 18:08:34 -07:00

167 lines
7.6 KiB
C

// SPDX-FileCopyrightText: 2026 Erin Catto
// SPDX-License-Identifier: MIT
// Cascaded-shadow-map infrastructure.
//
// One depth array texture (D32F) holds all cascades, each cascade gets its
// own depth-only view used as the depth attachment for that cascade's
// shadow pass. A single comparison sampler (LESS_EQUAL with linear PCF)
// is shared by every lit shader that reads from the array.
//
// Light-space matrices and split distances are computed by FitShadows
// each frame from the camera frustum and the sun direction.
//
// Coordinate convention inside shadow space:
// - Standard Z (not reverse-Z): 0 at near, 1 at far. The shadow pass
// clears depth to 1.0, fragments closer to the light overwrite with
// smaller values, the sampler compares LESS_EQUAL to determine "this
// fragment is the closest one, so lit".
// - Right-handed orthographic projection, 0..1 clip-Z.
//
// Public surface:
// InitShadows / ShutdownShadows, lifecycle.
// SetShadowSunDir, store the direction the renderer will use when
// fitting cascades.
// FitShadows, recompute cascade matrices and split distances for a
// given camera frustum.
// BeginShadowPass / EndShadowPass, open/close the depth pass per cascade.
// GetShadowSampleView / GetShadowSampler, for lit pipelines to
// bind once and sample across all cascades.
// GetCascadeMatrix / GetCascadeFarViewZ, for lit
// shaders to transform world positions and select the right cascade.
#pragma once
#include "gfx/utility.h"
#include "sokol_gfx.h"
#include <stdbool.h>
#ifdef __cplusplus
extern "C"
{
#endif
// Must match SHADOW_CASCADE_COUNT in shaders/common/shadow_cascade.glsl,
// which the renderer static asserts against the generated uniform layout.
// Changing it needs a shader regen (BOX3D_BUILD_SHADERS=ON) to reach the
// committed headers. Four is the ceiling: per-cascade values ride in vec4
// lanes and a fifth would need a second vec4 for each of them.
//
// More cascades cannot sharpen the last one. It always has to reach the far
// split, so its texel is pinned near 2 * k * far / resolution with k set by
// the field of view. What they buy is a finer near cascade and a smaller
// step at each boundary, both at the cost of another shadow pass.
#define SHADOW_CASCADE_COUNT 4
#define SHADOW_RESOLUTION 4096
// Default cascade split range, view-space distance from the camera. Scenes
// smaller than the far end keep the default range, larger ones widen it.
//
// The near end sits nowhere near the camera near plane on purpose. It says
// where the split distribution starts, not where shadows start: the first
// cascade's bounding sphere reaches back past the eye whatever this is, so
// close content is covered either way. Starting out at working distance is
// what puts the whole volume being looked at inside the first cascade,
// rather than spending it on the metre in front of the lens and leaving two
// boundaries sitting in the middle of the scene. The cost is a first cascade
// stretched to reach that far, so it trades sharpness for uniformity.
#define SHADOW_SPLIT_NEAR 10.0f
#define SHADOW_SPLIT_FAR 50.0f
// Ceiling on that widening. The last cascade always has to reach the far
// split, so its texel size is set by this number alone and nothing else
// in the fit affects it. Letting a scene push it out coarsens the far
// cascade until its shadows read as blocks, and widens the step from the
// cascade before it. A scene that genuinely needs more reach should ask
// for it rather than have it inferred from how big its ground is.
#define SHADOW_SPLIT_FAR_MAX 80.0f
void InitShadows( void );
void ShutdownShadows( void );
// Set the world-space direction TO the sun
void SetShadowSunDir( b3Vec3 dirToSun );
// Override the view-space distance range PSSM splits over. Defaults to
// (SHADOW_SPLIT_NEAR, SHADOW_SPLIT_FAR), sufficient for the reference scenes
// but wrong for a scene watched from far off, where the near end wastes whole
// cascades on the empty space in front of the camera. Pass (0, 0) to restore
// defaults.
void SetShadowSplits( float nearViewZ, float farViewZ );
// Fit the cascade far split to a scene of this view-space depth, keeping the
// current near.
void SetShadowSplitFar( float farViewZ );
float GetShadowSplitNear( void );
float GetShadowSplitFar( void );
// Blend between the two PSSM split schemes. 0 puts every boundary at an
// equal slice of distance, 1 at an equal multiplicative step. Raising it
// tightens the near cascades at the cost of dragging every boundary toward
// the camera, so the coarse far cascade takes over sooner.
void SetShadowSplitLambda( float lambda );
float GetShadowSplitLambda( void );
// Recompute per-cascade light-space matrices and split distances for the
// camera frustum described by viewInv + proj. viewInv (the camera's world
// matrix) supplies eye + basis directly, so the slice-corner walk does no
// matrix inversion. proj supplies fovY + aspect via proj[1][1] / proj[0][0].
// Cascade slices are fit to the camera frustum and snapped to texel
// boundaries to avoid swimming edges as the camera moves.
void FitShadows( const Mat4* viewInv, const Mat4* proj );
// World-space AABB enclosing every shape that can cast into the cascades:
// each slice's bounding sphere swept toward the sun by the caster margin.
// It reaches well outside the camera frustum, which is the point. A host
// culling its draw submission to the visible volume drops casters that
// belong in the shadow map, and their shadows vanish.
//
// Derived from the camera alone, so it can be queried before FitShadows
// runs for the frame. Takes projInv because that is what the draw path
// already carries. Bounds come back in the same frame viewInv maps into,
// so a caller working against a shifted draw origin must offset them.
void GetShadowCasterBounds( const Mat4* viewInv, const Mat4* projInv, b3Vec3* loOut, b3Vec3* hiOut );
// Begin / end the depth-only render pass for a cascade. Bind this as
// the surrounding pass before issuing caster draws into the cascade.
void BeginShadowPass( int cascade );
void EndShadowPass( void );
// Light-space view-proj matrix for a cascade. Lit shaders multiply a
// world-space position by this to get shadow-space coordinates.
Mat4 GetCascadeMatrix( int cascade );
// Far view-space Z (positive value, distance from camera) for the end
// cascade. Lit shaders compare a fragment's view-space depth against
// these to pick which cascade to sample.
float GetCascadeFarViewZ( int cascade );
// One shadow texel measured in world length units for a cascade. Lit
// shaders scale the normal offset by this so every cascade biases by the
// same visual amount regardless of how much world it covers. The ratio
// against cascade 0 also shrinks the PCF kernel in the coarser cascades,
// which keeps the penumbra a constant world width instead of jumping at
// every cascade boundary.
float GetCascadeTexelWorld( int cascade );
// Residual comparison bias for a cascade, in shadow clip-Z units. The
// normal offset carries the slope term, this only has to cover depth
// quantization. Sized on the CPU because shadow clip-Z spans the whole
// orthographic range, which differs per cascade.
float GetCascadeDepthBias( int cascade );
// Bound by lit pipelines once for sampling across all cascades. The view
// is the depth array's full-array sampling view. Per-cascade selection
// happens inside the shader by passing `cascade` as the layer index.
sg_view GetShadowSampleView( void );
sg_sampler GetShadowSampler( void );
// One-texel size in shadow UV space (1 / SHADOW_RESOLUTION). Lit shaders
// use this to size PCF taps and the cascade-edge reject.
float GetShadowTexelSize( void );
#ifdef __cplusplus
} // extern "C"
#endif