XCEngine/Rendering/AGENTS.md

Rendering 模块说明（在建）

1. 目的

• 本文只描述当前已落地的渲染主线和后续收口方向。
• 这里优先记录真实代码职责，不按理想状态脑补。
• 如果实现与本文冲突，以代码为准，再更新本文。

2. 当前主链

SceneRenderer
  -> SceneRenderRequestPlanner
  -> RenderPipelineHost
      -> CameraFramePlanBuilder
      -> CameraRenderer
          -> DirectionalShadowRuntime
          -> RenderSceneExtractor
          -> CameraFrameGraph
              -> RenderGraph Record / Compile / Execute

3. 当前架构判断

• 这套系统已经不是“一个 forward pipeline 直接画完整帧”。
• 当前主模型是：SRP host + renderer backend + per-camera plan + render graph execution。
• ScriptableRenderPipelineHost 是 native 侧最重要的 SRP 接缝。
• CameraRenderRequest 和 CameraFramePlan 已经承担了每相机规划职责。
• RenderSceneExtractor 负责从 Scene 生成 RenderSceneData。
• CameraFrameGraph 和 RenderGraph 已经是执行内核的一部分，不是附属实验层。

4. 和 Unity SRP / URP 的关系

• RenderPipelineAsset 对应 Unity 的 RenderPipelineAsset。
• ScriptableRenderPipelineHost 接近 Unity 的 RenderPipeline 宿主。
• managed 侧已经有 ScriptableRenderPipelineAsset -> ScriptableRendererData -> ScriptableRenderer -> ScriptableRendererFeature/Pass 这条产品层骨架。
• 因此当前问题不是“SRP 没打通”，而是“URP 风格上层还没彻底收口”。

5. 当前未收口点

• managed runtime 目前仍复用默认 native forward backend 作为共享绘制后端。
• 这意味着 BuiltinForwardPipeline 还同时带着“默认产品层”和“native 执行后端”两种身份。
• 一些本该属于 URP asset / renderer / feature 的组织策略，仍可能滑回 native backend。
• 所以现在更准确的名字是“SRP 已通、URP 主产品线未收口”。

6. 在这个模块里应怎样继续演进

• 把 camera request policy、renderer 选择、stage planning、scene setup、shadow execution config、pass/feature 排序继续上移到 managed URP。
• 把 scene extraction、renderer list 绘制、native scene feature、fullscreen primitive 执行保留在 native。
• 非通用策略不要继续直接塞进 BuiltinForwardPipeline。
• 如果新增的是“绘制能力”或“native backend contract”，可以放 C++。
• 如果新增的是“渲染组织策略”或“URP 行为差异”，优先放 managed。

7. 关键文件

• engine/src/Rendering/Execution/SceneRenderer.cpp
• engine/src/Rendering/Execution/RenderPipelineHost.cpp
• engine/src/Rendering/Execution/CameraRenderer.cpp
• engine/src/Rendering/Extraction/RenderSceneExtractor.cpp
• engine/src/Rendering/Pipelines/ScriptableRenderPipelineHost.cpp
• engine/src/Rendering/Pipelines/BuiltinForwardPipeline.cpp
• managed/XCEngine.ScriptCore/Rendering/Core/ScriptableRenderPipeline*.cs
• managed/XCEngine.RenderPipelines.Universal/Rendering/Universal/*.cs

8. 长期目标

• 形成唯一默认主线：UniversalRenderPipelineAsset -> UniversalRendererData -> UniversalRenderer -> ScriptableRendererFeature/Pass。
• ShadowCaster / DepthOnly / MainScene / PostProcess / FinalOutput 的组织权由 managed URP 持有。
• BuiltinForwardPipeline 或其后继应退回为 native scene draw backend，而不是继续充当上层产品语义。
• native 侧最终保留“执行内核”和“通用后端 contract”，managed 侧负责“渲染策略”和“产品层组织”。
• 简单说：目标不是继续堆更多 URP 外形，而是把 URP 真正收口成唯一上层组织者。