From 45efe2df7599e860e6a2da4dc1b92e242df05001 Mon Sep 17 00:00:00 2001 From: Ben Doherty Date: Fri, 24 Jul 2020 11:04:28 -0700 Subject: [PATCH] CSM: allow setting individual split positions (#2835) --- filament/include/filament/LightManager.h | 82 +++++++++++++++++++++++ filament/src/ShadowMapManager.cpp | 29 ++++---- filament/src/components/LightManager.cpp | 36 ++++++++++ filament/src/details/ShadowMapManager.h | 13 +++- libs/gltfio/include/gltfio/SimpleViewer.h | 5 ++ 5 files changed, 149 insertions(+), 16 deletions(-) diff --git a/filament/include/filament/LightManager.h b/filament/include/filament/LightManager.h index d762ae1c9b..0aab4dc49a 100644 --- a/filament/include/filament/LightManager.h +++ b/filament/include/filament/LightManager.h @@ -197,10 +197,41 @@ public: * A value greater than 1 turns on cascaded shadow mapping (CSM). * Only applicable to Type.SUN or Type.DIRECTIONAL lights. * + * When using shadow cascades, cascadeSplitPositions must also be set. + * + * @see ShadowCascades::cascadeSplitPositions + * * @warning This API is still experimental and subject to change. */ uint8_t shadowCascades = 1; + /** + * The split positions for shadow cascades. + * + * Cascaded shadow mapping (CSM) partitions the camera frustum into cascades. These values + * determine the planes along the camera's Z axis to split the frustum. The camera near + * plane is represented by 0.0f and the far plane represented by 1.0f. + * + * For example, if using 4 cascades, these values would set a uniform split scheme: + * { 0.25f, 0.50f, 0.75f } + * + * For N cascades, N - 1 split positions will be read from this array. + * + * Filament provides utility methods inside LightManager::ShadowCascades to help set these + * values. For example, to use a uniform split scheme: + * + * ~~~~~~~~~~~{.cpp} + * LightManager::ShadowCascades::computeUniformSplits(options.splitPositions, 4); + * ~~~~~~~~~~~ + * + * @see ShadowCascades::computeUniformSplits + * @see ShadowCascades::computeLogSplits + * @see ShadowCascades::computePracticalSplits + * + * @warning This API is still experimental and subject to change. + */ + float cascadeSplitPositions[3] = { 0.25f, 0.50f, 0.75f }; + /** Constant bias in world units (e.g. meters) by which shadows are moved away from the * light. 1mm by default. */ @@ -283,6 +314,57 @@ public: float maxShadowDistance = 0.3; }; + struct ShadowCascades { + /** + * Utility method to compute ShadowOptions::cascadeSplitPositions according to a uniform + * split scheme. + * + * @warning This API is still experimental and subject to change. + * + * @param splitPositions a float array of at least size (cascades - 1) to write the split + * positions into + * @param cascades the number of shadow cascades, at most 4 + */ + static void computeUniformSplits(float* splitPositions, uint8_t cascades); + + /** + * Utility method to compute ShadowOptions::cascadeSplitPositions according to a logarithmic + * split scheme. + * + * @warning This API is still experimental and subject to change. + * + * @param splitPositions a float array of at least size (cascades - 1) to write the split + * positions into + * @param cascades the number of shadow cascades, at most 4 + * @param near the camera near plane + * @param far the camera far plane + */ + static void computeLogSplits(float* splitPositions, uint8_t cascades, + float near, float far); + + /** + * Utility method to compute ShadowOptions::cascadeSplitPositions according to a practical + * split scheme. + * + * The practical split scheme uses uses a lambda value to interpolate between the logrithmic + * and uniform split schemes. Start with a lambda value of 0.5f and adjust for your scene. + * + * See: Zhang et al 2006, "Parallel-split shadow maps for large-scale virtual environments" + * + * @warning This API is still experimental and subject to change. + * + * @param splitPositions a float array of at least size (cascades - 1) to write the split + * positions into + * @param cascades the number of shadow cascades, at most 4 + * @param near the camera near plane + * @param far the camera far plane + * @param lambda a float in the range [0, 1] that interpolates between log and + * uniform split schemes + */ + static void computePracticalSplits(float* splitPositions, uint8_t cascades, + float near, float far, float lambda); + }; + //! Use Builder to construct a Light object instance class Builder : public BuilderBase { friend struct BuilderDetails; diff --git a/filament/src/ShadowMapManager.cpp b/filament/src/ShadowMapManager.cpp index c92b03d5f5..cdecf7404c 100644 --- a/filament/src/ShadowMapManager.cpp +++ b/filament/src/ShadowMapManager.cpp @@ -203,6 +203,9 @@ bool ShadowMapManager::updateCascadeShadowMaps(FEngine& engine, FView& view, const uint16_t textureSize = mTextureState.size; auto& lcm = engine.getLightManager(); + FLightManager::Instance directionalLight = lightData.elementAt(0); + LightManager::ShadowOptions const& options = lcm.getShadowOptions(directionalLight); + ShadowMap::CascadeParameters cascadeParams; if (mCascadeShadowMaps.size() > 0) { @@ -241,13 +244,24 @@ bool ShadowMapManager::updateCascadeShadowMaps(FEngine& engine, FView& view, vsFar = std::max(vsFar, cascadeParams.vsNearFar.y); } + const size_t cascadeCount = mCascadeShadowMaps.size(); + // We divide the camera frustum into N cascades. This gives us N + 1 split positions. // The first split position is the near plane; the last split position is the far plane. + std::array splitPercentages; + splitPercentages[0] = 0.0f; + size_t i = 1; + for (; i < cascadeCount; i++) { + splitPercentages[i] = options.cascadeSplitPositions[i - 1]; + } + splitPercentages[i] = 1.0f; + const CascadeSplits::Params p { .proj = viewingCameraInfo.cullingProjection, .near = vsNear, .far = vsFar, - .cascadeCount = mCascadeShadowMaps.size() + .cascadeCount = cascadeCount, + .splitPositions = splitPercentages }; if (p != mCascadeSplitParams) { mCascadeSplits = CascadeSplits(p); @@ -304,8 +318,6 @@ bool ShadowMapManager::updateCascadeShadowMaps(FEngine& engine, FView& view, } // screen-space contact shadows for the directional light - FLightManager::Instance directionalLight = lightData.elementAt(0); - LightManager::ShadowOptions const& options = lcm.getShadowOptions(directionalLight); screenSpaceShadowDistance = options.maxShadowDistance; directionalShadows |= std::min(uint8_t(255u), options.stepCount) << 8u; if (options.screenSpaceContactShadows) { @@ -427,17 +439,8 @@ void ShadowMapManager::destroyResources(DriverApi& driver) noexcept { } ShadowMapManager::CascadeSplits::CascadeSplits(Params p) : mSplitCount(p.cascadeCount + 1) { - auto uniformSplit = [](float near, float far, size_t cascades) { - return [near, far, cascades](size_t split) { - if (cascades == 0) { - return 0.0f; - } - return near + (far - near) * ((float) split / cascades); - }; - }; - auto uniformSplitCalculator = uniformSplit(p.near, p.far, p.cascadeCount); for (size_t s = 0; s < mSplitCount; s++) { - mSplitsWs[s] = uniformSplitCalculator(s); + mSplitsWs[s] = p.near + (p.far - p.near) * p.splitPositions[s]; mSplitsCs[s] = mat4f::project(p.proj, float3(0.0f, 0.0f, mSplitsWs[s])).z; } } diff --git a/filament/src/components/LightManager.cpp b/filament/src/components/LightManager.cpp index e9607c8809..d2f6e059da 100644 --- a/filament/src/components/LightManager.cpp +++ b/filament/src/components/LightManager.cpp @@ -370,6 +370,42 @@ void FLightManager::setShadowCaster(Instance i, bool shadowCaster) noexcept { } } +// ------------------------------------------------------------------------------------------------ +// ShadowCascades utility methods +// ------------------------------------------------------------------------------------------------ + +void LightManager::ShadowCascades::computeUniformSplits(float splitPositions[3], uint8_t cascades) { + size_t s = 0; + cascades = max(cascades, (uint8_t) 4u); + for (size_t c = 1; c < cascades; c++) { + splitPositions[s++] = (float) c / cascades; + } +} + +void LightManager::ShadowCascades::computeLogSplits(float splitPositions[3], uint8_t cascades, + float near, float far) { + size_t s = 0; + cascades = max(cascades, (uint8_t) 4u); + for (size_t c = 1; c < cascades; c++) { + splitPositions[s++] = + (near * std::powf(far / near, (float) c / cascades) - near) / (far - near); + } +} + +void LightManager::ShadowCascades::computePracticalSplits(float splitPositions[3], uint8_t cascades, + float near, float far, float lambda) { + float uniformSplits[3]; + float logSplits[3]; + cascades = max(cascades, (uint8_t) 4u); + computeUniformSplits(uniformSplits, cascades); + computeLogSplits(logSplits, cascades, near, far); + size_t s = 0; + for (size_t c = 1; c < cascades; c++) { + splitPositions[s] = lambda * logSplits[s] + (1.0f - lambda) * uniformSplits[s]; + s++; + } +} + // ------------------------------------------------------------------------------------------------ // Trampoline calling into private implementation // ------------------------------------------------------------------------------------------------ diff --git a/filament/src/details/ShadowMapManager.h b/filament/src/details/ShadowMapManager.h index a1b9706abe..44530a7154 100644 --- a/filament/src/details/ShadowMapManager.h +++ b/filament/src/details/ShadowMapManager.h @@ -126,31 +126,38 @@ private: class CascadeSplits { public: + constexpr static size_t SPLIT_COUNT = CONFIG_MAX_SHADOW_CASCADES + 1; + struct Params { math::mat4f proj = {}; float near = 0.0f; float far = 0.0f; size_t cascadeCount = 1; + std::array splitPositions = { 0.0f }; bool operator!=(const Params& rhs) const { return proj != rhs.proj || near != rhs.near || far != rhs.far || - cascadeCount != rhs.cascadeCount; + cascadeCount != rhs.cascadeCount || + splitPositions != rhs.splitPositions; } }; CascadeSplits() : CascadeSplits(Params {}) {} CascadeSplits(Params p); + // Split positions in world-space. const float* beginWs() const { return mSplitsWs; } const float* endWs() const { return mSplitsWs + mSplitCount; } + + // Split positions in clip-space. const float* beginCs() const { return mSplitsCs; } const float* endCs() const { return mSplitsCs + mSplitCount; } private: - float mSplitsWs[CONFIG_MAX_SHADOW_CASCADES + 1]; - float mSplitsCs[CONFIG_MAX_SHADOW_CASCADES + 1]; + float mSplitsWs[SPLIT_COUNT]; + float mSplitsCs[SPLIT_COUNT]; size_t mSplitCount; } mCascadeSplits; diff --git a/libs/gltfio/include/gltfio/SimpleViewer.h b/libs/gltfio/include/gltfio/SimpleViewer.h index c0cf865981..bf6bb31a83 100644 --- a/libs/gltfio/include/gltfio/SimpleViewer.h +++ b/libs/gltfio/include/gltfio/SimpleViewer.h @@ -199,6 +199,7 @@ private: bool mEnableShadows = true; int mShadowCascades = 1; bool mEnableContactShadows = false; + std::array mSplitPositions = {0.25f, 0.50f, 0.75f}; bool mEnableDithering = true; bool mEnableFxaa = true; bool mEnableMsaa = true; @@ -478,6 +479,9 @@ void SimpleViewer::updateUserInterface() { ImGui::SliderInt("Cascades", &mShadowCascades, 1, 4); ImGui::Checkbox("Debug Cascades", debug.getPropertyAddress("d.shadowmap.visualize_cascades")); ImGui::Checkbox("Enable contact shadows", &mEnableContactShadows); + ImGui::SliderFloat("Split pos 0", &mSplitPositions[0], 0.0f, 1.0f); + ImGui::SliderFloat("Split pos 1", &mSplitPositions[1], 0.0f, 1.0f); + ImGui::SliderFloat("Split pos 2", &mSplitPositions[2], 0.0f, 1.0f); ImGui::Unindent(); } @@ -518,6 +522,7 @@ void SimpleViewer::updateUserInterface() { auto options = lm.getShadowOptions(ci); options.screenSpaceContactShadows = mEnableContactShadows; options.shadowCascades = mShadowCascades; + std::copy_n(mSplitPositions.begin(), 3, options.cascadeSplitPositions); lm.setShadowOptions(ci, options); lm.setShadowCaster(ci, mEnableShadows); });