diff --git a/docs/used/SRP_URP_ManagedDirectionalShadowPlanningPlan_完成归档_2026-04-21.md b/docs/used/SRP_URP_ManagedDirectionalShadowPlanningPlan_完成归档_2026-04-21.md new file mode 100644 index 00000000..05f63939 --- /dev/null +++ b/docs/used/SRP_URP_ManagedDirectionalShadowPlanningPlan_完成归档_2026-04-21.md @@ -0,0 +1,92 @@ +# SRP/URP Managed Directional Shadow Planning Plan + +日期：2026-04-21 + +## 背景 + +当前主方向光阴影的 planning 仍然残留一条旧的 native policy-key 接缝： + +- `UniversalRenderPipelineAsset` + 通过 `GetDirectionalShadowPlanningPolicyAssetKey()` + 返回 `BuiltinDirectionalShadowPlanning` +- `ManagedScriptableRenderPipelineAsset` + 和 `MonoManagedRenderPipelineAssetRuntime` + 通过字符串 key 把 planning 再路由回 native +- managed `ConfigureCameraRenderRequest(...)` + 实际上只是修改 planning settings， + 真正的默认规划仍然依赖后置 policy-key 分发 + +这条接缝的问题和前面收掉的 scene setup / shadow execution 一样： + +- 默认所有权不够清晰 +- managed SRP/URP 只是“提供参数”，不是明确拥有规划行为 +- native policy-key registry 形成了不必要的中间层 + +## 目标 + +本阶段把主方向光阴影 planning 改成： + +- managed `ConfigureCameraRenderRequest(...)` + 负责最终 shadow settings / suppress 决策 +- native 默认阴影规划函数 + `ApplyDefaultRenderPipelineAssetCameraRenderRequestPolicy(...)` + 直接消费 managed 最终状态 +- 移除 `BuiltinDirectionalShadowPlanning` + 和 `GetDirectionalShadowPlanningPolicyAssetKey(...)` + 整条接缝 + +也就是说： + +- C++ 继续保留默认阴影规划实现 +- 但不再通过 policy-key 回跳 +- managed 变成默认输入所有者 + +## 实施步骤 + +1. 清理 managed API + +- 删除 `RendererBackedRenderPipelineAsset` + 上的 `GetDirectionalShadowPlanningPolicyAssetKey()` +- 删除 `UniversalRenderPipelineAsset` + 对 `BuiltinDirectionalShadowPlanning` 的覆写 +- 删除 native runtime 对这个 managed 方法的解析缓存 + +2. 清理 native registry + +- 删除 `RenderPipelineFactory` + 中的 `DirectionalShadowPlanningPolicy` registry +- 删除 builtin key `BuiltinDirectionalShadowPlanning` +- 删除 `ApplyDirectionalShadowPlanningPolicyByKey(...)` + 及相关注册/反注册 API + +3. 重构 camera request 流程 + +- `ManagedScriptableRenderPipelineAsset::ConfigureCameraRenderRequest(...)` + 不再预先调用 policy-key +- `MonoManagedRenderPipelineAssetRuntime::ConfigureCameraRenderRequest(...)` + 在 managed 回调结束后： + - 若明确 suppress，则清空 directional shadow + - 否则直接用最终 `DirectionalShadowPlanningSettings` + 调用默认 native 规划函数 + +这样 `ConfigureCameraRenderRequest(...)` +就成为阴影规划的真正 managed 所有权入口。 + +## 验收标准 + +- 仓库中不再出现： + - `BuiltinDirectionalShadowPlanning` + - `GetDirectionalShadowPlanningPolicyAssetKey` + - `DirectionalShadowPlanningPolicy` registry +- `UniversalRenderPipelineAsset` + 仍然能正确配置主方向光阴影 +- `XCEditor` 编译通过 +- 旧 editor 冒烟通过，并出现新的 `SceneReady` + +## 不在本阶段处理 + +- standalone pass asset key +- `BuiltinForward` native renderer substrate +- deferred / renderer graph capability 扩展 + +这些属于后续阶段，不和这一步混在一起。 diff --git a/engine/include/XCEngine/Rendering/Pipelines/ManagedScriptableRenderPipelineAsset.h b/engine/include/XCEngine/Rendering/Pipelines/ManagedScriptableRenderPipelineAsset.h index 0ed6822a..9b756420 100644 --- a/engine/include/XCEngine/Rendering/Pipelines/ManagedScriptableRenderPipelineAsset.h +++ b/engine/include/XCEngine/Rendering/Pipelines/ManagedScriptableRenderPipelineAsset.h @@ -128,10 +128,6 @@ public: (void)rendererIndex; return GetCameraFrameStandalonePassAssetKey(stage); } - virtual std::string GetDirectionalShadowPlanningPolicyAssetKey() - const { - return {}; - } virtual bool TryGetDefaultFinalColorSettings(FinalColorSettings&) const { return false; diff --git a/engine/src/Rendering/Internal/RenderPipelineFactory.cpp b/engine/src/Rendering/Internal/RenderPipelineFactory.cpp index d9f60046..1227fd74 100644 --- a/engine/src/Rendering/Internal/RenderPipelineFactory.cpp +++ b/engine/src/Rendering/Internal/RenderPipelineFactory.cpp @@ -45,8 +45,6 @@ using PipelineRendererAssetRegistry = std::unordered_map; using CameraFrameStandalonePassRegistry = std::unordered_map; -using DirectionalShadowPlanningPolicyRegistry = - std::unordered_map; using CameraFramePlanPolicyRegistry = std::unordered_map; using DirectionalShadowExecutionPolicyRegistry = @@ -62,12 +60,6 @@ CameraFrameStandalonePassRegistry& GetCameraFrameStandalonePassRegistry() { return registry; } -DirectionalShadowPlanningPolicyRegistry& -GetDirectionalShadowPlanningPolicyRegistry() { - static DirectionalShadowPlanningPolicyRegistry registry = {}; - return registry; -} - CameraFramePlanPolicyRegistry& GetCameraFramePlanPolicyRegistry() { static CameraFramePlanPolicyRegistry registry = {}; return registry; @@ -89,11 +81,6 @@ std::unordered_set& GetBuiltinCameraFrameStandalonePassKeys() { return builtinKeys; } -std::unordered_set& GetBuiltinDirectionalShadowPlanningPolicyKeys() { - static std::unordered_set builtinKeys = {}; - return builtinKeys; -} - std::unordered_set& GetBuiltinCameraFramePlanPolicyKeys() { static std::unordered_set builtinKeys = {}; return builtinKeys; @@ -115,11 +102,6 @@ std::mutex& GetCameraFrameStandalonePassRegistryMutex() { return mutex; } -std::mutex& GetDirectionalShadowPlanningPolicyRegistryMutex() { - static std::mutex mutex; - return mutex; -} - std::mutex& GetCameraFramePlanPolicyRegistryMutex() { static std::mutex mutex; return mutex; @@ -166,29 +148,6 @@ void EnsureBuiltinCameraFrameStandalonePassRegistryInitialized() { (void)initialized; } -void EnsureBuiltinDirectionalShadowPlanningPolicyRegistryInitialized() { - static const bool initialized = []() { - DirectionalShadowPlanningPolicyRegistry& registry = - GetDirectionalShadowPlanningPolicyRegistry(); - registry.emplace( - "BuiltinDirectionalShadowPlanning", - [](CameraRenderRequest& request, - size_t renderedBaseCameraCount, - size_t renderedRequestCount, - const DirectionalShadowPlanningSettings& settings) { - ApplyDefaultRenderPipelineAssetCameraRenderRequestPolicy( - request, - renderedBaseCameraCount, - renderedRequestCount, - settings); - }); - GetBuiltinDirectionalShadowPlanningPolicyKeys().insert( - "BuiltinDirectionalShadowPlanning"); - return true; - }(); - (void)initialized; -} - void EnsureBuiltinCameraFramePlanPolicyRegistryInitialized() { static const bool initialized = []() { CameraFramePlanPolicyRegistry& registry = @@ -383,76 +342,6 @@ std::unique_ptr CreateCameraFrameStandalonePassByKey( return it->second(); } -bool RegisterDirectionalShadowPlanningPolicy( - const std::string& key, - DirectionalShadowPlanningPolicy policy) { - if (key.empty() || !policy) { - return false; - } - - EnsureBuiltinDirectionalShadowPlanningPolicyRegistryInitialized(); - - std::lock_guard lock( - GetDirectionalShadowPlanningPolicyRegistryMutex()); - DirectionalShadowPlanningPolicyRegistry& registry = - GetDirectionalShadowPlanningPolicyRegistry(); - if (registry.find(key) != registry.end()) { - return false; - } - - registry.emplace(key, std::move(policy)); - return true; -} - -bool UnregisterDirectionalShadowPlanningPolicy( - const std::string& key) { - if (key.empty()) { - return false; - } - - EnsureBuiltinDirectionalShadowPlanningPolicyRegistryInitialized(); - - std::lock_guard lock( - GetDirectionalShadowPlanningPolicyRegistryMutex()); - if (GetBuiltinDirectionalShadowPlanningPolicyKeys().find(key) != - GetBuiltinDirectionalShadowPlanningPolicyKeys().end()) { - return false; - } - - DirectionalShadowPlanningPolicyRegistry& registry = - GetDirectionalShadowPlanningPolicyRegistry(); - return registry.erase(key) != 0u; -} - -bool ApplyDirectionalShadowPlanningPolicyByKey( - const std::string& key, - CameraRenderRequest& request, - size_t renderedBaseCameraCount, - size_t renderedRequestCount, - const DirectionalShadowPlanningSettings& settings) { - if (key.empty()) { - return false; - } - - EnsureBuiltinDirectionalShadowPlanningPolicyRegistryInitialized(); - - std::lock_guard lock( - GetDirectionalShadowPlanningPolicyRegistryMutex()); - const DirectionalShadowPlanningPolicyRegistry& registry = - GetDirectionalShadowPlanningPolicyRegistry(); - const auto it = registry.find(key); - if (it == registry.end() || !it->second) { - return false; - } - - it->second( - request, - renderedBaseCameraCount, - renderedRequestCount, - settings); - return true; -} - bool RegisterCameraFramePlanPolicy( const std::string& key, CameraFramePlanPolicy policy) { diff --git a/engine/src/Rendering/Internal/RenderPipelineFactory.h b/engine/src/Rendering/Internal/RenderPipelineFactory.h index 05f43f0b..e5af377c 100644 --- a/engine/src/Rendering/Internal/RenderPipelineFactory.h +++ b/engine/src/Rendering/Internal/RenderPipelineFactory.h @@ -11,10 +11,8 @@ class NativeSceneRenderer; class RenderPipeline; class RenderPipelineAsset; class RenderPass; -struct CameraRenderRequest; struct CameraFramePlan; struct FinalColorSettings; -struct DirectionalShadowPlanningSettings; struct DirectionalShadowExecutionState; struct DirectionalShadowSurfaceAllocation; @@ -24,12 +22,6 @@ using PipelineRendererAssetFactory = std::function()>; using CameraFrameStandalonePassFactory = std::function()>; -using DirectionalShadowPlanningPolicy = - std::function; using CameraFramePlanPolicy = std::function CreateCameraFrameStandalonePassByKey( const std::string& key); -bool RegisterDirectionalShadowPlanningPolicy( - const std::string& key, - DirectionalShadowPlanningPolicy policy); -bool UnregisterDirectionalShadowPlanningPolicy( - const std::string& key); -bool ApplyDirectionalShadowPlanningPolicyByKey( - const std::string& key, - CameraRenderRequest& request, - size_t renderedBaseCameraCount, - size_t renderedRequestCount, - const DirectionalShadowPlanningSettings& settings); bool RegisterCameraFramePlanPolicy( const std::string& key, CameraFramePlanPolicy policy); diff --git a/engine/src/Rendering/Pipelines/ManagedScriptableRenderPipelineAsset.cpp b/engine/src/Rendering/Pipelines/ManagedScriptableRenderPipelineAsset.cpp index 033814c0..a816c7c9 100644 --- a/engine/src/Rendering/Pipelines/ManagedScriptableRenderPipelineAsset.cpp +++ b/engine/src/Rendering/Pipelines/ManagedScriptableRenderPipelineAsset.cpp @@ -1,8 +1,6 @@ #include "Rendering/Pipelines/ManagedScriptableRenderPipelineAsset.h" -#include "Debug/Logger.h" #include "Rendering/GraphicsSettingsState.h" -#include "Rendering/Internal/RenderPipelineFactory.h" #include @@ -10,39 +8,6 @@ namespace XCEngine { namespace Rendering { namespace Pipelines { -namespace { - -void ApplyManagedDirectionalShadowPlanningPolicyOrDefault( - const std::string& assetKey, - CameraRenderRequest& request, - size_t renderedBaseCameraCount, - size_t renderedRequestCount, - const DirectionalShadowPlanningSettings& directionalShadowSettings) { - if (assetKey.empty()) { - ApplyDefaultRenderPipelineAssetCameraRenderRequestPolicy( - request, - renderedBaseCameraCount, - renderedRequestCount, - directionalShadowSettings); - return; - } - - if (!Rendering::Internal::ApplyDirectionalShadowPlanningPolicyByKey( - assetKey, - request, - renderedBaseCameraCount, - renderedRequestCount, - directionalShadowSettings)) { - Debug::Logger::Get().Error( - Debug::LogCategory::Rendering, - Containers::String( - "ManagedScriptableRenderPipelineAsset failed to resolve directional shadow planning policy asset key: ") + - assetKey.c_str()); - } -} - -} // namespace - ManagedScriptableRenderPipelineAsset::ManagedScriptableRenderPipelineAsset( ManagedRenderPipelineAssetDescriptor descriptor) : m_descriptor(std::move(descriptor)) { @@ -127,12 +92,6 @@ void ManagedScriptableRenderPipelineAsset::ConfigureCameraRenderRequest( if (const std::shared_ptr runtime = ResolveManagedAssetRuntime(); runtime != nullptr) { - ApplyManagedDirectionalShadowPlanningPolicyOrDefault( - runtime->GetDirectionalShadowPlanningPolicyAssetKey(), - request, - renderedBaseCameraCount, - renderedRequestCount, - directionalShadowSettings); runtime->ConfigureCameraRenderRequest( request, renderedBaseCameraCount, diff --git a/engine/src/Scripting/Mono/MonoScriptRuntime.cpp b/engine/src/Scripting/Mono/MonoScriptRuntime.cpp index 891823e6..319df474 100644 --- a/engine/src/Scripting/Mono/MonoScriptRuntime.cpp +++ b/engine/src/Scripting/Mono/MonoScriptRuntime.cpp @@ -133,7 +133,6 @@ struct ManagedCameraRenderRequestContextState { size_t renderedRequestCount = 0u; Rendering::DirectionalShadowPlanningSettings directionalShadowPlanningSettings = {}; - bool directionalShadowPlanningSettingsDirty = false; bool suppressDirectionalShadow = false; }; @@ -1505,8 +1504,6 @@ public: bool UsesNativeCameraFramePlanBaseline() const override; bool UsesNativeCameraFramePlanBaseline( int32_t rendererIndex) const override; - std::string GetDirectionalShadowPlanningPolicyAssetKey() const - override; std::string GetCameraFrameStandalonePassAssetKey( Rendering::CameraFrameStage stage) const override; std::string GetCameraFrameStandalonePassAssetKey( @@ -1554,8 +1551,6 @@ private: MonoObject* assetObject) const; MonoMethod* ResolveConfigureDirectionalShadowExecutionStateMethod( MonoObject* assetObject) const; - MonoMethod* ResolveGetDirectionalShadowPlanningPolicyAssetKeyMethod( - MonoObject* assetObject) const; MonoMethod* ResolveGetCameraFrameStandalonePassAssetKeyMethod( MonoObject* assetObject) const; MonoMethod* @@ -1586,8 +1581,6 @@ private: nullptr; mutable MonoMethod* m_configureDirectionalShadowExecutionStateMethod = nullptr; - mutable MonoMethod* - m_getDirectionalShadowPlanningPolicyAssetKeyMethod = nullptr; mutable MonoMethod* m_getCameraFrameStandalonePassAssetKeyMethod = nullptr; mutable MonoMethod* @@ -2006,6 +1999,12 @@ void MonoManagedRenderPipelineAssetRuntime::ConfigureCameraRenderRequest( const Rendering::DirectionalShadowPlanningSettings& directionalShadowSettings) const { if (!EnsureManagedAsset()) { + request.directionalShadow = {}; + Rendering::ApplyDefaultRenderPipelineAssetCameraRenderRequestPolicy( + request, + renderedBaseCameraCount, + renderedRequestCount, + directionalShadowSettings); return; } @@ -2013,6 +2012,12 @@ void MonoManagedRenderPipelineAssetRuntime::ConfigureCameraRenderRequest( MonoMethod* const method = ResolveConfigureCameraRenderRequestMethod(assetObject); if (assetObject == nullptr || method == nullptr) { + request.directionalShadow = {}; + Rendering::ApplyDefaultRenderPipelineAssetCameraRenderRequestPolicy( + request, + renderedBaseCameraCount, + renderedRequestCount, + directionalShadowSettings); return; } @@ -2032,6 +2037,12 @@ void MonoManagedRenderPipelineAssetRuntime::ConfigureCameraRenderRequest( if (requestContextObject == nullptr) { UnregisterManagedCameraRenderRequestContextState( requestContextHandle); + request.directionalShadow = {}; + Rendering::ApplyDefaultRenderPipelineAssetCameraRenderRequestPolicy( + request, + renderedBaseCameraCount, + renderedRequestCount, + directionalShadowSettings); return; } @@ -2041,30 +2052,14 @@ void MonoManagedRenderPipelineAssetRuntime::ConfigureCameraRenderRequest( method, args, nullptr); - const std::string directionalShadowPlanningPolicyAssetKey = - GetDirectionalShadowPlanningPolicyAssetKey(); + request.directionalShadow = {}; if (requestContextState.suppressDirectionalShadow) { - request.directionalShadow = {}; - } else if (requestContextState.directionalShadowPlanningSettingsDirty) { - request.directionalShadow = {}; - if (directionalShadowPlanningPolicyAssetKey.empty()) { - Rendering::ApplyDefaultRenderPipelineAssetCameraRenderRequestPolicy( - request, - renderedBaseCameraCount, - renderedRequestCount, - requestContextState.directionalShadowPlanningSettings); - } else if (!Rendering::Internal::ApplyDirectionalShadowPlanningPolicyByKey( - directionalShadowPlanningPolicyAssetKey, - request, - renderedBaseCameraCount, - renderedRequestCount, - requestContextState.directionalShadowPlanningSettings)) { - Debug::Logger::Get().Error( - Debug::LogCategory::Rendering, - Containers::String( - "MonoManagedRenderPipelineAssetRuntime failed to resolve directional shadow planning policy asset key: ") + - directionalShadowPlanningPolicyAssetKey.c_str()); - } + } else { + Rendering::ApplyDefaultRenderPipelineAssetCameraRenderRequestPolicy( + request, + renderedBaseCameraCount, + renderedRequestCount, + requestContextState.directionalShadowPlanningSettings); } UnregisterManagedCameraRenderRequestContextState( requestContextHandle); @@ -2385,37 +2380,6 @@ bool MonoManagedRenderPipelineAssetRuntime::UsesNativeCameraFramePlanBaseline( usesBaseline; } -std::string MonoManagedRenderPipelineAssetRuntime:: - GetDirectionalShadowPlanningPolicyAssetKey() const { - if (!SyncManagedAssetRuntimeState()) { - return {}; - } - - MonoObject* const assetObject = GetManagedAssetObject(); - if (assetObject == nullptr) { - return {}; - } - - MonoMethod* const method = - ResolveGetDirectionalShadowPlanningPolicyAssetKeyMethod( - assetObject); - if (method == nullptr) { - return {}; - } - - MonoObject* managedKeyObject = nullptr; - if (!m_runtime->InvokeManagedMethod( - assetObject, - method, - nullptr, - &managedKeyObject)) { - return {}; - } - - return MonoStringToUtf8( - reinterpret_cast(managedKeyObject)); -} - std::string MonoManagedRenderPipelineAssetRuntime:: GetCameraFrameStandalonePassAssetKey( Rendering::CameraFrameStage stage) const { @@ -2693,7 +2657,6 @@ void MonoManagedRenderPipelineAssetRuntime::ReleaseManagedAsset() const { m_usesNativeCameraFramePlanBaselineContextualMethod = nullptr; m_configureRenderSceneSetupMethod = nullptr; m_configureDirectionalShadowExecutionStateMethod = nullptr; - m_getDirectionalShadowPlanningPolicyAssetKeyMethod = nullptr; m_getCameraFrameStandalonePassAssetKeyMethod = nullptr; m_getCameraFrameStandalonePassAssetKeyContextualMethod = nullptr; m_pipelineRendererAsset.reset(); @@ -2906,22 +2869,6 @@ MonoManagedRenderPipelineAssetRuntime:: return m_configureDirectionalShadowExecutionStateMethod; } -MonoMethod* -MonoManagedRenderPipelineAssetRuntime:: - ResolveGetDirectionalShadowPlanningPolicyAssetKeyMethod( - MonoObject* assetObject) const { - if (m_getDirectionalShadowPlanningPolicyAssetKeyMethod == - nullptr) { - m_getDirectionalShadowPlanningPolicyAssetKeyMethod = - m_runtime->ResolveManagedMethod( - assetObject, - "GetDirectionalShadowPlanningPolicyAssetKey", - 0); - } - - return m_getDirectionalShadowPlanningPolicyAssetKeyMethod; -} - MonoMethod* MonoManagedRenderPipelineAssetRuntime:: ResolveGetCameraFrameStandalonePassAssetKeyMethod( @@ -5806,7 +5753,6 @@ InternalCall_Rendering_CameraRenderRequestContext_SetDirectionalShadowPlanningSe state->directionalShadowPlanningSettings = *reinterpret_cast( settings); - state->directionalShadowPlanningSettingsDirty = true; } void InternalCall_Rendering_CameraRenderRequestContext_ClearDirectionalShadow( diff --git a/managed/XCEngine.RenderPipelines.Universal/Rendering/Universal/RendererBackedRenderPipelineAsset.cs b/managed/XCEngine.RenderPipelines.Universal/Rendering/Universal/RendererBackedRenderPipelineAsset.cs index 62d63506..586844a6 100644 --- a/managed/XCEngine.RenderPipelines.Universal/Rendering/Universal/RendererBackedRenderPipelineAsset.cs +++ b/managed/XCEngine.RenderPipelines.Universal/Rendering/Universal/RendererBackedRenderPipelineAsset.cs @@ -140,12 +140,6 @@ namespace XCEngine.Rendering.Universal stage); } - private protected virtual string - GetDirectionalShadowPlanningPolicyAssetKey() - { - return string.Empty; - } - protected override void ReleaseRuntimeResources() { ReleaseRendererDataRuntimeResources(); diff --git a/managed/XCEngine.RenderPipelines.Universal/Rendering/Universal/UniversalRenderPipelineAsset.cs b/managed/XCEngine.RenderPipelines.Universal/Rendering/Universal/UniversalRenderPipelineAsset.cs index fe903d9a..531d389e 100644 --- a/managed/XCEngine.RenderPipelines.Universal/Rendering/Universal/UniversalRenderPipelineAsset.cs +++ b/managed/XCEngine.RenderPipelines.Universal/Rendering/Universal/UniversalRenderPipelineAsset.cs @@ -23,12 +23,6 @@ namespace XCEngine.Rendering.Universal return new UniversalRenderPipeline(this); } - private protected override string - GetDirectionalShadowPlanningPolicyAssetKey() - { - return "BuiltinDirectionalShadowPlanning"; - } - protected override FinalColorSettings GetDefaultFinalColorSettings() {