diff --git a/docs/api/XCEngine/Rendering/Builtin/Builtin.md b/docs/api/XCEngine/Rendering/Builtin/Builtin.md new file mode 100644 index 00000000..87a9d6c9 --- /dev/null +++ b/docs/api/XCEngine/Rendering/Builtin/Builtin.md @@ -0,0 +1,40 @@ +# Builtin + +**命名空间**: `XCEngine::Rendering` + +**类型**: `submodule` + +**头文件目录**: `engine/include/XCEngine/Rendering/Builtin/` + +**描述**: builtin pass 契约与元数据辅助层，负责描述内建渲染阶段的逻辑名称、布局规则与 metadata 解析辅助。 + +## 概览 + +`Builtin` 这一层当前位于 shader/material 契约与具体 pass 执行之间。 + +它的职责不是执行渲染，而是统一描述： + +- builtin pass 的契约名 +- builtin pass 的布局语义 +- builtin metadata 的读取与标准化 +- shader `resources` 如何被解释成 builtin pass 白名单语义 + +当前公开入口包括： + +- [BuiltinPassContract](BuiltinPassContract/BuiltinPassContract.md) +- [BuiltinPassTypes](BuiltinPassTypes/BuiltinPassTypes.md) +- [BuiltinPassMetadataUtils](BuiltinPassMetadataUtils/BuiltinPassMetadataUtils.md) +- [BuiltinPassLayoutUtils](BuiltinPassLayoutUtils/BuiltinPassLayoutUtils.md) + +## 当前职责 + +- 为 builtin forward / object-id / depth-style pass 提供统一的 pass 枚举与资源语义 +- 统一 shader pass 名称和 `LightMode` tag 的匹配规则 +- 把 shader `resources` 声明转换成 descriptor-set layout 可消费的 plan +- 为管线和 pass 提供调试字符串与布局元数据刷新 helper + +## 相关文档 + +- [Rendering](../Rendering.md) +- [Materials](../Materials/Materials.md) +- [Passes](../Passes/Passes.md) diff --git a/docs/api/XCEngine/Rendering/Builtin/BuiltinPassContract/BuiltinPassContract.md b/docs/api/XCEngine/Rendering/Builtin/BuiltinPassContract/BuiltinPassContract.md new file mode 100644 index 00000000..47371eb1 --- /dev/null +++ b/docs/api/XCEngine/Rendering/Builtin/BuiltinPassContract/BuiltinPassContract.md @@ -0,0 +1,39 @@ +# BuiltinPassContract + +**命名空间**: `XCEngine::Rendering` + +**类型**: `utility header` + +**头文件**: `XCEngine/Rendering/Builtin/BuiltinPassContract.h` + +**描述**: builtin pass 资源契约的聚合入口头，当前作为兼容 include，把类型、metadata 解析与布局辅助一并暴露给调用方。 + +## 概览 + +`BuiltinPassContract.h` 当前本身不再声明独立类型或函数。 + +它的作用更接近“完整 builtin pass 契约入口”： + +- 引入 `BuiltinPassLayoutUtils.h` +- 进而间接带入 `BuiltinPassMetadataUtils.h` +- 再带入 `BuiltinPassTypes.h` + +对消费 builtin pass 资源契约的代码来说，如果不想分别 include 三层辅助头，直接引入这份聚合头即可。 + +## 当前适用场景 + +- 需要同时使用 `BuiltinMaterialPass`、`BuiltinPassResourceBindingPlan` 和 `TryBuildBuiltinPassSetLayouts(...)` +- 需要解析 shader `resources` 声明，再继续生成 descriptor-set layout +- 需要写出与 builtin forward / object-id / depth-style pass 相同的资源契约代码 + +## 当前实现边界 + +- 它只是聚合入口，不新增 ABI，也不提供独立实现。 +- 如果调用方只依赖某一小组 helper，仍然可以直接 include 更窄的头文件。 + +## 相关文档 + +- [Builtin](../Builtin.md) +- [BuiltinPassTypes](../BuiltinPassTypes/BuiltinPassTypes.md) +- [BuiltinPassMetadataUtils](../BuiltinPassMetadataUtils/BuiltinPassMetadataUtils.md) +- [BuiltinPassLayoutUtils](../BuiltinPassLayoutUtils/BuiltinPassLayoutUtils.md) diff --git a/docs/api/XCEngine/Rendering/Builtin/BuiltinPassLayoutUtils/BuiltinPassLayoutUtils.md b/docs/api/XCEngine/Rendering/Builtin/BuiltinPassLayoutUtils/BuiltinPassLayoutUtils.md new file mode 100644 index 00000000..897b326d --- /dev/null +++ b/docs/api/XCEngine/Rendering/Builtin/BuiltinPassLayoutUtils/BuiltinPassLayoutUtils.md @@ -0,0 +1,53 @@ +# BuiltinPassLayoutUtils + +**命名空间**: `XCEngine::Rendering` + +**类型**: `utility header` + +**头文件**: `XCEngine/Rendering/Builtin/BuiltinPassLayoutUtils.h` + +**描述**: builtin pass 资源布局辅助头，负责把 shader `resources` 列表解析成 `BuiltinPassResourceBindingPlan`，再进一步构建 descriptor-set layout 元数据。 + +## 当前公开能力 + +这份头文件主要提供两段式转换： + +1. `TryBuildBuiltinPassResourceBindingPlan(...)` + 把 shader `resources` 收口成 builtin 语义化 binding plan。 +2. `TryBuildBuiltinPassSetLayouts(...)` + 把 binding plan 继续落成每个 descriptor set 的布局元数据。 + +除此之外，还提供： + +- `ToBuiltinPassDescriptorType(...)` +- `ResolveBuiltinPassDescriptorHeapType(...)` +- `IsBuiltinPassShaderVisibleSet(...)` +- `CountBuiltinPassHeapDescriptors(...)` +- `RefreshBuiltinPassSetLayoutMetadata(...)` +- `RefreshBuiltinPassSetLayouts(...)` + +## 当前约束 + +- 拒绝未知 builtin 语义。 +- 拒绝语义与 shader 资源类型不兼容的组合。 +- 拒绝重复的 builtin 语义。 +- 拒绝重复的 `set/binding` 组合。 +- 拒绝在同一个 descriptor set 中混用 sampler 和非 sampler 资源。 + +## 当前调用链 + +- `BuiltinForwardPipeline` 用它为每个 resolved shader pass 生成 pipeline layout 和 descriptor sets。 +- `BuiltinObjectIdPass` 用它校验 object-id shader 的 `PerObject` 资源契约。 +- `BuiltinDepthStylePassBase` 用它为 depth-only / shadow-caster / alpha-test 变体准备共享布局。 + +## 当前实现边界 + +- 它只负责 builtin pass 白名单语义，不是通用 shader 反射层。 +- 最终“某个 pass 缺少必需语义”这类规则，仍由具体 pass 或 pipeline 在更高层决定。 + +## 相关文档 + +- [Builtin](../Builtin.md) +- [BuiltinPassTypes](../BuiltinPassTypes/BuiltinPassTypes.md) +- [BuiltinPassMetadataUtils](../BuiltinPassMetadataUtils/BuiltinPassMetadataUtils.md) +- [TryBuildBuiltinPassResourceBindingPlan](../../RenderMaterialUtility/TryBuildBuiltinPassResourceBindingPlan.md) diff --git a/docs/api/XCEngine/Rendering/Builtin/BuiltinPassMetadataUtils/BuiltinPassMetadataUtils.md b/docs/api/XCEngine/Rendering/Builtin/BuiltinPassMetadataUtils/BuiltinPassMetadataUtils.md new file mode 100644 index 00000000..aaa9fc46 --- /dev/null +++ b/docs/api/XCEngine/Rendering/Builtin/BuiltinPassMetadataUtils/BuiltinPassMetadataUtils.md @@ -0,0 +1,49 @@ +# BuiltinPassMetadataUtils + +**命名空间**: `XCEngine::Rendering` + +**类型**: `utility header` + +**头文件**: `XCEngine/Rendering/Builtin/BuiltinPassMetadataUtils.h` + +**描述**: builtin pass metadata 与 shader 资源语义解析辅助头，负责统一 pass 名称匹配、显式 metadata 判断、资源语义映射和调试描述字符串。 + +## 当前公开能力 + +这份头文件主要提供三类 helper： + +1. pass 名称标准化与匹配 +2. shader / shader pass 是否显式声明 builtin metadata 的判断 +3. shader `resources` 语义映射与描述字符串生成 + +## 关键 helper + +- `NormalizeBuiltinPassMetadataValue(...)` + 统一 trim + lower-case 规则。 +- `IsForwardPassName(...)` / `IsUnlitPassName(...)` / `IsDepthOnlyPassName(...)` / `IsShadowCasterPassName(...)` / `IsObjectIdPassName(...)` + 把历史命名和 builtin 路径名称统一映射到标准 pass 语义。 +- `MatchesBuiltinPassName(...)` + 把字符串名称和 `BuiltinMaterialPass` 枚举做一层收口匹配。 +- `ShaderPassHasExplicitBuiltinMetadata(...)` / `ShaderHasExplicitBuiltinMetadata(...)` + 判断 shader 侧是否已经显式给出 pass 名或 `LightMode` tag。 +- `ShaderPassMatchesBuiltinPass(...)` + 用当前规范判断一个 shader pass 是否属于某个 builtin pass。 +- `ResolveBuiltinPassResourceSemantic(...)` + 把 `ShaderResourceBindingDesc` 的 `semantic` 或 `name` 收口成 `BuiltinPassResourceSemantic`。 +- `DescribeShaderResourceBinding(...)` / `DescribeShaderResourceBindings(...)` + 生成带 `name / semantic / type / set / binding` 的调试描述。 +- `IsBuiltinPassResourceTypeCompatible(...)` + 校验 builtin 资源语义与 `ShaderResourceType` 是否兼容。 + +## 当前实现边界 + +- 这里只负责“解释元数据”，不负责生成 descriptor-set layout。 +- `Unknown` 语义不会在这里报错；真正的失败由后续 binding-plan 或 layout 构建阶段决定。 +- `ShaderHasExplicitBuiltinMetadata(...)` 的判断基于 shader pass 名称与 `LightMode` tag，不会解析更复杂的自定义 tag 体系。 + +## 相关文档 + +- [Builtin](../Builtin.md) +- [BuiltinPassTypes](../BuiltinPassTypes/BuiltinPassTypes.md) +- [BuiltinPassLayoutUtils](../BuiltinPassLayoutUtils/BuiltinPassLayoutUtils.md) +- [RenderMaterialResolve](../../Materials/RenderMaterialResolve/RenderMaterialResolve.md) diff --git a/docs/api/XCEngine/Rendering/Builtin/BuiltinPassTypes/BuiltinPassTypes.md b/docs/api/XCEngine/Rendering/Builtin/BuiltinPassTypes/BuiltinPassTypes.md new file mode 100644 index 00000000..f6ecf80e --- /dev/null +++ b/docs/api/XCEngine/Rendering/Builtin/BuiltinPassTypes/BuiltinPassTypes.md @@ -0,0 +1,39 @@ +# BuiltinPassTypes + +**命名空间**: `XCEngine::Rendering` + +**类型**: `utility header` + +**头文件**: `XCEngine/Rendering/Builtin/BuiltinPassTypes.h` + +**描述**: builtin pass 资源契约的基础类型头，定义 pass 枚举、资源语义、binding 位置、binding plan 和 set-layout 元数据。 + +## 头文件中的主要类型 + +- `BuiltinMaterialPass` +- `PassResourceBindingLocation` +- `BuiltinPassResourceSemantic` +- `BuiltinPassResourceBindingDesc` +- `BuiltinPassResourceBindingPlan` +- `BuiltinPassSetLayoutMetadata` + +## 当前语义 + +- `BuiltinMaterialPass` 把 builtin 渲染路径收口为 `ForwardLit`、`Unlit`、`DepthOnly`、`ShadowCaster`、`ObjectId`。 +- `PassResourceBindingLocation` 用 `(set, binding)` 描述一个 shader 资源槽位，并通过 `IsValid()` 判断是否已解析成功。 +- `BuiltinPassResourceSemantic` 把 builtin 路径当前可识别的资源语义限制在 `PerObject`、`Material`、`Lighting`、`ShadowReceiver`、`BaseColorTexture`、`ShadowMapTexture` 和两类 sampler。 +- `BuiltinPassResourceBindingPlan` 保存规范化后的 binding 列表、descriptor-set 区间、资源类型开关，以及各语义对应的快捷位置字段。 +- `BuiltinPassSetLayoutMetadata` 是更靠近 RHI 的布局结果，记录一组 descriptor bindings、heap 类型、shader 可见性和该 set 实际承载的 builtin 语义。 + +## 当前调用链 + +- [BuiltinPassMetadataUtils](../BuiltinPassMetadataUtils/BuiltinPassMetadataUtils.md) 负责把 shader pass 元数据与 `resources` 语义解析成这些类型可消费的枚举。 +- [BuiltinPassLayoutUtils](../BuiltinPassLayoutUtils/BuiltinPassLayoutUtils.md) 负责把 `BuiltinPassResourceBindingPlan` 继续落成 descriptor-set layouts。 +- `BuiltinForwardPipeline`、`BuiltinObjectIdPass` 和 `BuiltinDepthStylePassBase` 都直接消费这些契约类型。 + +## 相关文档 + +- [Builtin](../Builtin.md) +- [BuiltinPassMetadataUtils](../BuiltinPassMetadataUtils/BuiltinPassMetadataUtils.md) +- [BuiltinPassLayoutUtils](../BuiltinPassLayoutUtils/BuiltinPassLayoutUtils.md) +- [RenderMaterialUtility](../../RenderMaterialUtility/RenderMaterialUtility.md) diff --git a/docs/api/XCEngine/Rendering/Caches/Caches.md b/docs/api/XCEngine/Rendering/Caches/Caches.md new file mode 100644 index 00000000..907721fa --- /dev/null +++ b/docs/api/XCEngine/Rendering/Caches/Caches.md @@ -0,0 +1,29 @@ +# Caches + +**命名空间**: `XCEngine::Rendering` + +**类型**: `submodule` + +**头文件目录**: `engine/include/XCEngine/Rendering/Caches/` + +**描述**: Rendering 运行时缓存层，负责把 CPU 资源复用成 GPU 资源，以及为定向光阴影等阶段缓存可复用 surface。 + +## 概览 + +`Caches` 当前主要覆盖两类短生命周期但高复用的运行时对象： + +- [RenderResourceCache](RenderResourceCache/RenderResourceCache.md) +- [DirectionalShadowSurfaceCache](DirectionalShadowSurfaceCache/DirectionalShadowSurfaceCache.md) + +## 当前职责 + +- mesh / texture GPU 上传与指针级缓存 +- directional shadow depth surface 的懒创建与复用 +- 避免每帧重复创建中间纹理和 buffer + +## 相关文档 + +- [Rendering](../Rendering.md) +- [Execution](../Execution/Execution.md) +- [Passes](../Passes/Passes.md) + diff --git a/docs/api/XCEngine/Rendering/Caches/DirectionalShadowSurfaceCache/DirectionalShadowSurfaceCache.md b/docs/api/XCEngine/Rendering/Caches/DirectionalShadowSurfaceCache/DirectionalShadowSurfaceCache.md new file mode 100644 index 00000000..4a8204ec --- /dev/null +++ b/docs/api/XCEngine/Rendering/Caches/DirectionalShadowSurfaceCache/DirectionalShadowSurfaceCache.md @@ -0,0 +1,32 @@ +# DirectionalShadowSurfaceCache + +**命名空间**: `XCEngine::Rendering` + +**类型**: `class` + +**头文件**: `XCEngine/Rendering/Caches/DirectionalShadowSurfaceCache.h` + +**描述**: directional shadow 阶段的中间 surface 缓存，负责按 `DirectionalShadowRenderPlan` 懒创建并复用深度纹理、深度视图和 shader 读取视图。 + +## 概览 + +`DirectionalShadowSurfaceCache` 由 [CameraRenderer](../../Execution/CameraRenderer/CameraRenderer.md) 持有，用于 directional shadow 阶段。 + +它当前公开的核心能力只有两项： + +- `EnsureSurface(...)` +- `GetSurface()` / `GetDepthShaderView()` + +## 当前语义 + +- `EnsureSurface(...)` 会根据 `RenderContext` 与 `DirectionalShadowRenderPlan` 判断现有缓存是否还能复用。 +- `GetSurface()` 返回当前用于 shadow-caster 渲染的 `RenderSurface`。 +- `GetDepthShaderView()` 返回后续主场景采样阴影时使用的深度 SRV。 + +## 相关文档 + +- [Caches](../Caches.md) +- [CameraRenderer](../../Execution/CameraRenderer/CameraRenderer.md) +- [CameraRenderRequest](../../Planning/CameraRenderRequest/CameraRenderRequest.md) +- [RenderSurface](../../RenderSurface/RenderSurface.md) + diff --git a/docs/api/XCEngine/Rendering/Caches/RenderResourceCache/RenderResourceCache.md b/docs/api/XCEngine/Rendering/Caches/RenderResourceCache/RenderResourceCache.md new file mode 100644 index 00000000..4db87b61 --- /dev/null +++ b/docs/api/XCEngine/Rendering/Caches/RenderResourceCache/RenderResourceCache.md @@ -0,0 +1,38 @@ +# RenderResourceCache + +**命名空间**: `XCEngine::Rendering` + +**类型**: `class` + +**头文件**: `XCEngine/Rendering/Caches/RenderResourceCache.h` + +**描述**: 负责把 `Mesh` 和 `Texture` 上传成 RHI 资源，并按资源指针缓存这些 GPU 副本。 + +## 概览 + +`RenderResourceCache` 是当前 builtin pipeline 与 depth/object-id pass 共享的 GPU 资源缓存。 + +它当前定义两类缓存条目： + +- `CachedMesh` +- `CachedTexture` + +## 当前公开能力 + +- `Shutdown()` +- `GetOrCreateMesh(...)` +- `GetOrCreateTexture(...)` + +## 当前实现边界 + +- cache key 仍是 `Mesh*` / `Texture*` 裸指针。 +- 当前没有版本号或自动失效机制。 +- 当前不是线程安全对象。 + +## 相关文档 + +- [Caches](../Caches.md) +- [BuiltinForwardPipeline](../../Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md) +- [BuiltinObjectIdPass](../../Passes/BuiltinObjectIdPass/BuiltinObjectIdPass.md) +- [BuiltinDepthStylePassBase](../../Passes/BuiltinDepthStylePassBase/BuiltinDepthStylePassBase.md) + diff --git a/docs/api/XCEngine/Rendering/CameraRenderRequest/CameraRenderRequest.md b/docs/api/XCEngine/Rendering/CameraRenderRequest/CameraRenderRequest.md index f5396545..b20a23d3 100644 --- a/docs/api/XCEngine/Rendering/CameraRenderRequest/CameraRenderRequest.md +++ b/docs/api/XCEngine/Rendering/CameraRenderRequest/CameraRenderRequest.md @@ -1,10 +1,10 @@ -# CameraRenderRequest +# CameraRenderRequest **命名空间**: `XCEngine::Rendering` **类型**: `struct` -**头文件**: `XCEngine/Rendering/CameraRenderRequest.h` +**头文件**: `XCEngine/Rendering/Planning/CameraRenderRequest.h` **描述**: 把一次单相机提交所需的场景、目标表面、shadow-caster / depth-only / object-id 子请求、清屏覆盖和可选 pass 序列打包成显式请求对象。 @@ -102,3 +102,4 @@ Editor Scene View 当前会先通过 [SceneViewportRenderPlan](../../Editor/View - [RenderContext](../RenderContext/RenderContext.md) - [RenderSurface](../RenderSurface/RenderSurface.md) - [Passes](../Passes/Passes.md) + diff --git a/docs/api/XCEngine/Rendering/CameraRenderRequest/IsValid.md b/docs/api/XCEngine/Rendering/CameraRenderRequest/IsValid.md index aedb6488..ee79a16f 100644 --- a/docs/api/XCEngine/Rendering/CameraRenderRequest/IsValid.md +++ b/docs/api/XCEngine/Rendering/CameraRenderRequest/IsValid.md @@ -1,10 +1,10 @@ -# CameraRenderRequest::IsValid +# CameraRenderRequest::IsValid **命名空间**: `XCEngine::Rendering` **类型**: `method` -**头文件**: `XCEngine/Rendering/CameraRenderRequest.h` +**头文件**: `XCEngine/Rendering/Planning/CameraRenderRequest.h` ## 签名 @@ -50,3 +50,4 @@ return scene != nullptr && - [CameraRenderRequest](CameraRenderRequest.md) - [CameraRenderer::Render](../CameraRenderer/Render.md) + diff --git a/docs/api/XCEngine/Rendering/CameraRenderRequest/ObjectIdRenderRequest/ObjectIdRenderRequest.md b/docs/api/XCEngine/Rendering/CameraRenderRequest/ObjectIdRenderRequest/ObjectIdRenderRequest.md index 683dffc7..9e0377d6 100644 --- a/docs/api/XCEngine/Rendering/CameraRenderRequest/ObjectIdRenderRequest/ObjectIdRenderRequest.md +++ b/docs/api/XCEngine/Rendering/CameraRenderRequest/ObjectIdRenderRequest/ObjectIdRenderRequest.md @@ -1,10 +1,10 @@ -# ObjectIdRenderRequest +# ObjectIdRenderRequest **命名空间**: `XCEngine::Rendering` **类型**: `struct` -**头文件**: `XCEngine/Rendering/CameraRenderRequest.h` +**头文件**: `XCEngine/Rendering/Planning/CameraRenderRequest.h` **描述**: 描述一份 camera request 是否需要额外输出 object-id 纹理，以及这份输出目标是否完整可用。 @@ -35,3 +35,4 @@ - [IsRequested](IsRequested.md) - [IsValid](IsValid.md) - [CameraRenderer](../../CameraRenderer/CameraRenderer.md) + diff --git a/docs/api/XCEngine/Rendering/CameraRenderRequest/ScenePassRenderRequest/ScenePassRenderRequest.md b/docs/api/XCEngine/Rendering/CameraRenderRequest/ScenePassRenderRequest/ScenePassRenderRequest.md index 0580bc7c..938155dc 100644 --- a/docs/api/XCEngine/Rendering/CameraRenderRequest/ScenePassRenderRequest/ScenePassRenderRequest.md +++ b/docs/api/XCEngine/Rendering/CameraRenderRequest/ScenePassRenderRequest/ScenePassRenderRequest.md @@ -1,10 +1,10 @@ -# ScenePassRenderRequest +# ScenePassRenderRequest **命名空间**: `XCEngine::Rendering` **类型**: `struct` -**头文件**: `XCEngine/Rendering/CameraRenderRequest.h` +**头文件**: `XCEngine/Rendering/Planning/CameraRenderRequest.h` **描述**: 描述一份独立 scene pass 请求是否需要执行，以及这份 depth-only / shadow-caster 目标与覆盖参数是否完整可用。 @@ -38,3 +38,4 @@ - [IsRequested](IsRequested.md) - [IsValid](IsValid.md) - [CameraRenderer](../../CameraRenderer/CameraRenderer.md) + diff --git a/docs/api/XCEngine/Rendering/CameraRenderer/CameraRenderer.md b/docs/api/XCEngine/Rendering/CameraRenderer/CameraRenderer.md index 126de3a9..7cd48430 100644 --- a/docs/api/XCEngine/Rendering/CameraRenderer/CameraRenderer.md +++ b/docs/api/XCEngine/Rendering/CameraRenderer/CameraRenderer.md @@ -1,10 +1,10 @@ -# CameraRenderer +# CameraRenderer **命名空间**: `XCEngine::Rendering` **类型**: `class` -**头文件**: `XCEngine/Rendering/CameraRenderer.h` +**头文件**: `XCEngine/Rendering/Execution/CameraRenderer.h` **描述**: 单个 `CameraRenderRequest` 的执行器，负责在一次提交里串起 scene extraction、shadow/depth 预 pass、主主管线、object-id，以及注入式 pre/post/overlay pass。 @@ -106,3 +106,4 @@ - [BuiltinShadowCasterPass](../Passes/BuiltinShadowCasterPass/BuiltinShadowCasterPass.md) - [Camera Request Planning And Clear Rules](../../../_guides/Rendering/Camera-Request-Planning-And-Clear-Rules.md) - [Scene Extraction And Builtin Forward Pipeline](../../../_guides/Rendering/Scene-Extraction-And-Builtin-Forward-Pipeline.md) + diff --git a/docs/api/XCEngine/Rendering/CameraRenderer/Constructor.md b/docs/api/XCEngine/Rendering/CameraRenderer/Constructor.md index ab5f093a..d1ac0e5f 100644 --- a/docs/api/XCEngine/Rendering/CameraRenderer/Constructor.md +++ b/docs/api/XCEngine/Rendering/CameraRenderer/Constructor.md @@ -1,10 +1,10 @@ -# CameraRenderer::Constructor +# CameraRenderer::Constructor **命名空间**: `XCEngine::Rendering` **类型**: `constructor-overload group` -**头文件**: `XCEngine/Rendering/CameraRenderer.h` +**头文件**: `XCEngine/Rendering/Execution/CameraRenderer.h` ## 签名 @@ -70,3 +70,4 @@ CameraRenderer( - [SetObjectIdPass](SetObjectIdPass.md) - [SetDepthOnlyPass](SetDepthOnlyPass.md) - [SetShadowCasterPass](SetShadowCasterPass.md) + diff --git a/docs/api/XCEngine/Rendering/CameraRenderer/Destructor.md b/docs/api/XCEngine/Rendering/CameraRenderer/Destructor.md index 5f548e72..c572bcba 100644 --- a/docs/api/XCEngine/Rendering/CameraRenderer/Destructor.md +++ b/docs/api/XCEngine/Rendering/CameraRenderer/Destructor.md @@ -1,10 +1,10 @@ -# CameraRenderer::~CameraRenderer +# CameraRenderer::~CameraRenderer **命名空间**: `XCEngine::Rendering` **类型**: `destructor` -**头文件**: `XCEngine/Rendering/CameraRenderer.h` +**头文件**: `XCEngine/Rendering/Execution/CameraRenderer.h` ## 签名 @@ -44,3 +44,4 @@ - [SetObjectIdPass](SetObjectIdPass.md) - [SetDepthOnlyPass](SetDepthOnlyPass.md) - [SetShadowCasterPass](SetShadowCasterPass.md) + diff --git a/docs/api/XCEngine/Rendering/CameraRenderer/GetDepthOnlyPass.md b/docs/api/XCEngine/Rendering/CameraRenderer/GetDepthOnlyPass.md index df564694..e8daf36c 100644 --- a/docs/api/XCEngine/Rendering/CameraRenderer/GetDepthOnlyPass.md +++ b/docs/api/XCEngine/Rendering/CameraRenderer/GetDepthOnlyPass.md @@ -1,10 +1,10 @@ -# CameraRenderer::GetDepthOnlyPass +# CameraRenderer::GetDepthOnlyPass **命名空间**: `XCEngine::Rendering` **类型**: `method` -**头文件**: `XCEngine/Rendering/CameraRenderer.h` +**头文件**: `XCEngine/Rendering/Execution/CameraRenderer.h` ## 签名 @@ -30,3 +30,4 @@ RenderPass* GetDepthOnlyPass() const; - [SetDepthOnlyPass](SetDepthOnlyPass.md) - [Render](Render.md) + diff --git a/docs/api/XCEngine/Rendering/CameraRenderer/GetObjectIdPass.md b/docs/api/XCEngine/Rendering/CameraRenderer/GetObjectIdPass.md index 68af8c98..cfe93c41 100644 --- a/docs/api/XCEngine/Rendering/CameraRenderer/GetObjectIdPass.md +++ b/docs/api/XCEngine/Rendering/CameraRenderer/GetObjectIdPass.md @@ -1,10 +1,10 @@ -# CameraRenderer::GetObjectIdPass +# CameraRenderer::GetObjectIdPass **命名空间**: `XCEngine::Rendering` **类型**: `method` -**头文件**: `XCEngine/Rendering/CameraRenderer.h` +**头文件**: `XCEngine/Rendering/Execution/CameraRenderer.h` ## 签名 @@ -29,3 +29,4 @@ ObjectIdPass* GetObjectIdPass() const; - [SetObjectIdPass](SetObjectIdPass.md) - [Render](Render.md) + diff --git a/docs/api/XCEngine/Rendering/CameraRenderer/GetPipeline.md b/docs/api/XCEngine/Rendering/CameraRenderer/GetPipeline.md index 44d14f04..5628bad1 100644 --- a/docs/api/XCEngine/Rendering/CameraRenderer/GetPipeline.md +++ b/docs/api/XCEngine/Rendering/CameraRenderer/GetPipeline.md @@ -1,10 +1,10 @@ -# CameraRenderer::GetPipeline +# CameraRenderer::GetPipeline **命名空间**: `XCEngine::Rendering` **类型**: `method` -**头文件**: `XCEngine/Rendering/CameraRenderer.h` +**头文件**: `XCEngine/Rendering/Execution/CameraRenderer.h` ## 签名 @@ -35,3 +35,4 @@ RenderPipeline* GetPipeline() const; - [SetPipeline](SetPipeline.md) - [SetPipelineAsset](SetPipelineAsset.md) - [GetPipelineAsset](GetPipelineAsset.md) + diff --git a/docs/api/XCEngine/Rendering/CameraRenderer/GetPipelineAsset.md b/docs/api/XCEngine/Rendering/CameraRenderer/GetPipelineAsset.md index 8996a112..bcd9e910 100644 --- a/docs/api/XCEngine/Rendering/CameraRenderer/GetPipelineAsset.md +++ b/docs/api/XCEngine/Rendering/CameraRenderer/GetPipelineAsset.md @@ -1,10 +1,10 @@ -# CameraRenderer::GetPipelineAsset +# CameraRenderer::GetPipelineAsset **命名空间**: `XCEngine::Rendering` **类型**: `method` -**头文件**: `XCEngine/Rendering/CameraRenderer.h` +**头文件**: `XCEngine/Rendering/Execution/CameraRenderer.h` ## 签名 @@ -30,3 +30,4 @@ const RenderPipelineAsset* GetPipelineAsset() const; - [SetPipelineAsset](SetPipelineAsset.md) - [SetPipeline](SetPipeline.md) - [GetPipeline](GetPipeline.md) + diff --git a/docs/api/XCEngine/Rendering/CameraRenderer/GetShadowCasterPass.md b/docs/api/XCEngine/Rendering/CameraRenderer/GetShadowCasterPass.md index d8d5990c..5ed946e9 100644 --- a/docs/api/XCEngine/Rendering/CameraRenderer/GetShadowCasterPass.md +++ b/docs/api/XCEngine/Rendering/CameraRenderer/GetShadowCasterPass.md @@ -1,10 +1,10 @@ -# CameraRenderer::GetShadowCasterPass +# CameraRenderer::GetShadowCasterPass **命名空间**: `XCEngine::Rendering` **类型**: `method` -**头文件**: `XCEngine/Rendering/CameraRenderer.h` +**头文件**: `XCEngine/Rendering/Execution/CameraRenderer.h` ## 签名 @@ -30,3 +30,4 @@ RenderPass* GetShadowCasterPass() const; - [SetShadowCasterPass](SetShadowCasterPass.md) - [Render](Render.md) + diff --git a/docs/api/XCEngine/Rendering/CameraRenderer/Render.md b/docs/api/XCEngine/Rendering/CameraRenderer/Render.md index c88e7919..39119d12 100644 --- a/docs/api/XCEngine/Rendering/CameraRenderer/Render.md +++ b/docs/api/XCEngine/Rendering/CameraRenderer/Render.md @@ -1,10 +1,10 @@ -# CameraRenderer::Render +# CameraRenderer::Render **命名空间**: `XCEngine::Rendering` **类型**: `method` -**头文件**: `XCEngine/Rendering/CameraRenderer.h` +**头文件**: `XCEngine/Rendering/Execution/CameraRenderer.h` ## 签名 @@ -80,3 +80,4 @@ bool Render(const CameraRenderRequest& request); - [SetDepthOnlyPass](SetDepthOnlyPass.md) - [SetShadowCasterPass](SetShadowCasterPass.md) - [Passes](../Passes/Passes.md) + diff --git a/docs/api/XCEngine/Rendering/CameraRenderer/SetDepthOnlyPass.md b/docs/api/XCEngine/Rendering/CameraRenderer/SetDepthOnlyPass.md index 3bc09628..5f22f2b1 100644 --- a/docs/api/XCEngine/Rendering/CameraRenderer/SetDepthOnlyPass.md +++ b/docs/api/XCEngine/Rendering/CameraRenderer/SetDepthOnlyPass.md @@ -1,10 +1,10 @@ -# CameraRenderer::SetDepthOnlyPass +# CameraRenderer::SetDepthOnlyPass **命名空间**: `XCEngine::Rendering` **类型**: `method` -**头文件**: `XCEngine/Rendering/CameraRenderer.h` +**头文件**: `XCEngine/Rendering/Execution/CameraRenderer.h` ## 签名 @@ -33,3 +33,4 @@ void SetDepthOnlyPass(std::unique_ptr depthOnlyPass); - [GetDepthOnlyPass](GetDepthOnlyPass.md) - [Render](Render.md) - [BuiltinDepthOnlyPass](../Passes/BuiltinDepthOnlyPass/BuiltinDepthOnlyPass.md) + diff --git a/docs/api/XCEngine/Rendering/CameraRenderer/SetObjectIdPass.md b/docs/api/XCEngine/Rendering/CameraRenderer/SetObjectIdPass.md index a8822073..1ca5ddb7 100644 --- a/docs/api/XCEngine/Rendering/CameraRenderer/SetObjectIdPass.md +++ b/docs/api/XCEngine/Rendering/CameraRenderer/SetObjectIdPass.md @@ -1,10 +1,10 @@ -# CameraRenderer::SetObjectIdPass +# CameraRenderer::SetObjectIdPass **命名空间**: `XCEngine::Rendering` **类型**: `method` -**头文件**: `XCEngine/Rendering/CameraRenderer.h` +**头文件**: `XCEngine/Rendering/Execution/CameraRenderer.h` ## 签名 @@ -32,3 +32,4 @@ void SetObjectIdPass(std::unique_ptr objectIdPass); - [GetObjectIdPass](GetObjectIdPass.md) - [Render](Render.md) - [Passes](../Passes/Passes.md) + diff --git a/docs/api/XCEngine/Rendering/CameraRenderer/SetPipeline.md b/docs/api/XCEngine/Rendering/CameraRenderer/SetPipeline.md index 84b9a152..a58da904 100644 --- a/docs/api/XCEngine/Rendering/CameraRenderer/SetPipeline.md +++ b/docs/api/XCEngine/Rendering/CameraRenderer/SetPipeline.md @@ -1,10 +1,10 @@ -# CameraRenderer::SetPipeline +# CameraRenderer::SetPipeline **命名空间**: `XCEngine::Rendering` **类型**: `method` -**头文件**: `XCEngine/Rendering/CameraRenderer.h` +**头文件**: `XCEngine/Rendering/Execution/CameraRenderer.h` ## 签名 @@ -41,3 +41,4 @@ void SetPipeline(std::unique_ptr pipeline); - [SetPipelineAsset](SetPipelineAsset.md) - [GetPipeline](GetPipeline.md) - [GetPipelineAsset](GetPipelineAsset.md) + diff --git a/docs/api/XCEngine/Rendering/CameraRenderer/SetPipelineAsset.md b/docs/api/XCEngine/Rendering/CameraRenderer/SetPipelineAsset.md index 7def2c60..36e0297f 100644 --- a/docs/api/XCEngine/Rendering/CameraRenderer/SetPipelineAsset.md +++ b/docs/api/XCEngine/Rendering/CameraRenderer/SetPipelineAsset.md @@ -1,10 +1,10 @@ -# CameraRenderer::SetPipelineAsset +# CameraRenderer::SetPipelineAsset **命名空间**: `XCEngine::Rendering` **类型**: `method` -**头文件**: `XCEngine/Rendering/CameraRenderer.h` +**头文件**: `XCEngine/Rendering/Execution/CameraRenderer.h` ## 签名 @@ -33,3 +33,4 @@ void SetPipelineAsset(std::shared_ptr pipelineAsset); - [SetPipeline](SetPipeline.md) - [GetPipelineAsset](GetPipelineAsset.md) - [Constructor](Constructor.md) + diff --git a/docs/api/XCEngine/Rendering/CameraRenderer/SetShadowCasterPass.md b/docs/api/XCEngine/Rendering/CameraRenderer/SetShadowCasterPass.md index 30845fc5..234c74a4 100644 --- a/docs/api/XCEngine/Rendering/CameraRenderer/SetShadowCasterPass.md +++ b/docs/api/XCEngine/Rendering/CameraRenderer/SetShadowCasterPass.md @@ -1,10 +1,10 @@ -# CameraRenderer::SetShadowCasterPass +# CameraRenderer::SetShadowCasterPass **命名空间**: `XCEngine::Rendering` **类型**: `method` -**头文件**: `XCEngine/Rendering/CameraRenderer.h` +**头文件**: `XCEngine/Rendering/Execution/CameraRenderer.h` ## 签名 @@ -33,3 +33,4 @@ void SetShadowCasterPass(std::unique_ptr shadowCasterPass); - [GetShadowCasterPass](GetShadowCasterPass.md) - [Render](Render.md) - [BuiltinShadowCasterPass](../Passes/BuiltinShadowCasterPass/BuiltinShadowCasterPass.md) + diff --git a/docs/api/XCEngine/Rendering/Execution/CameraRenderer/CameraRenderer.md b/docs/api/XCEngine/Rendering/Execution/CameraRenderer/CameraRenderer.md new file mode 100644 index 00000000..39cc633a --- /dev/null +++ b/docs/api/XCEngine/Rendering/Execution/CameraRenderer/CameraRenderer.md @@ -0,0 +1,65 @@ +# CameraRenderer + +**命名空间**: `XCEngine::Rendering` + +**类型**: `class` + +**头文件**: `XCEngine/Rendering/Execution/CameraRenderer.h` + +**描述**: 单个 `CameraRenderRequest` 的执行器，负责在一次提交里串起 scene extraction、shadow/depth 预阶段、主管线、fullscreen 阶段，以及注入式 pre / post / overlay pass。 + +## 概览 + +`CameraRenderer` 是当前 Rendering 执行层里最核心的“单 request 执行器”。 + +它不负责决定有哪些相机会进入本次渲染；那属于 [Planning](../../Planning/Planning.md) 和 [SceneRenderer](../SceneRenderer/SceneRenderer.md) 的职责。它负责的是另一半： + +- 使用 [RenderSceneExtractor](../../Extraction/RenderSceneExtractor/RenderSceneExtractor.md) 生成 `RenderSceneData` +- 按阶段执行 `shadowCaster`、`depthOnly`、主管线、`postProcess`、`finalOutput`、`objectId` +- 消费调用方注入的 `preScenePasses`、`postScenePasses` 与 `overlayPasses` + +## 当前持有对象 + +- `m_sceneExtractor` +- `m_pipelineAsset` +- `m_pipeline` +- `m_objectIdPass` +- `m_depthOnlyPass` +- `m_shadowCasterPass` +- `m_directionalShadowSurface` +- `m_postProcessSurfaceCache` +- `m_finalOutputSurfaceCache` + +## 当前执行顺序 + +对一份有效 request，当前主顺序是： + +1. 校验 request 与 surface 前置条件 +2. 解析 shadow surface 与 `RenderSceneData` +3. 执行 `preScenePasses` +4. 执行 `shadowCaster` +5. 执行 `depthOnly` +6. 执行 `m_pipeline->Render(...)` +7. 执行 `postProcess` +8. 执行 `finalOutput` +9. 执行 `objectId` +10. 执行 `postScenePasses` +11. 执行 `overlayPasses` + +## 当前实现边界 + +- 它只执行单个 request，不负责 request 排序。 +- 它会消费 `DirectionalShadowRenderPlan`、`PostProcessRenderRequest` 与 `FinalOutputRenderRequest`，因此比旧版 `CameraRenderer` 更完整。 +- 它不自己规划 Editor 的 Scene View pass；那仍由 Editor 层先写回 request。 + +## 相关文档 + +- [Execution](../Execution.md) +- [SceneRenderer](../SceneRenderer/SceneRenderer.md) +- [CameraRenderRequest](../../Planning/CameraRenderRequest/CameraRenderRequest.md) +- [RenderSceneExtractor](../../Extraction/RenderSceneExtractor/RenderSceneExtractor.md) +- [RenderPipeline](../../RenderPipeline/RenderPipeline.md) +- [BuiltinDepthOnlyPass](../../Passes/BuiltinDepthOnlyPass/BuiltinDepthOnlyPass.md) +- [BuiltinShadowCasterPass](../../Passes/BuiltinShadowCasterPass/BuiltinShadowCasterPass.md) +- [Camera Request Planning And Clear Rules](../../../../_guides/Rendering/Camera-Request-Planning-And-Clear-Rules.md) + diff --git a/docs/api/XCEngine/Rendering/Execution/Execution.md b/docs/api/XCEngine/Rendering/Execution/Execution.md new file mode 100644 index 00000000..16f9c71e --- /dev/null +++ b/docs/api/XCEngine/Rendering/Execution/Execution.md @@ -0,0 +1,38 @@ +# Execution + +**命名空间**: `XCEngine::Rendering` + +**类型**: `submodule` + +**头文件目录**: `engine/include/XCEngine/Rendering/Execution/` + +**描述**: Rendering 执行层，负责把已经规划好的 `CameraRenderRequest` 真正跑过 scene extraction、shadow/depth 预阶段、主管线、fullscreen 阶段与注入式 pass 序列。 + +## 概览 + +`Execution` 是当前 Rendering 主链里最接近“真正执行渲染”的一层。 + +它和 [Planning](../Planning/Planning.md) 的边界很明确： + +- `Planning` 决定“有哪些 request、顺序是什么” +- `Execution` 决定“单个 request 如何被真正执行” + +当前这一层包含两个核心入口： + +- [CameraRenderer](CameraRenderer/CameraRenderer.md) +- [SceneRenderer](SceneRenderer/SceneRenderer.md) + +## 当前职责 + +- 执行单个 `CameraRenderRequest` +- 执行 request 数组 +- 在执行前调用 [Extraction](../Extraction/Extraction.md) 生成 `RenderSceneData` +- 调度 shadow-caster、depth-only、main-scene、post-process、final-output、object-id、post-scene 与 overlay 阶段 + +## 相关文档 + +- [Rendering](../Rendering.md) +- [Planning](../Planning/Planning.md) +- [FrameData](../FrameData/FrameData.md) +- [Extraction](../Extraction/Extraction.md) + diff --git a/docs/api/XCEngine/Rendering/Execution/SceneRenderer/SceneRenderer.md b/docs/api/XCEngine/Rendering/Execution/SceneRenderer/SceneRenderer.md new file mode 100644 index 00000000..9622c785 --- /dev/null +++ b/docs/api/XCEngine/Rendering/Execution/SceneRenderer/SceneRenderer.md @@ -0,0 +1,45 @@ +# SceneRenderer + +**命名空间**: `XCEngine::Rendering` + +**类型**: `class` + +**头文件**: `XCEngine/Rendering/Execution/SceneRenderer.h` + +**描述**: 场景级渲染编排入口，负责构建和排序 `CameraRenderRequest`，再把每个请求转交给 [CameraRenderer](../CameraRenderer/CameraRenderer.md) 执行。 + +## 概览 + +`SceneRenderer` 当前是执行层的外层编排器。 + +它维护两块核心运行时对象： + +- `m_requestPlanner` +- `m_cameraRenderer` + +这条拆分让 Rendering 主链明确分成两层： + +- `SceneRenderer` 负责“这次要渲染哪些 request、按什么顺序” +- `CameraRenderer` 负责“单个 request 怎样被真正执行” + +## 当前公开能力 + +- 构建 request 数组 +- 执行单个 request +- 执行 request 数组 +- 直接从 `Scene + overrideCamera + surface` 生成 request 并执行 + +## 当前实现边界 + +- 它不直接做 scene extraction。 +- 它不直接操作主管线内部细节。 +- 对手工提交的 request 数组，当前仍会再次按 stack / depth 做稳定排序。 + +## 相关文档 + +- [Execution](../Execution.md) +- [CameraRenderer](../CameraRenderer/CameraRenderer.md) +- [SceneRenderRequestPlanner](../../Planning/SceneRenderRequestPlanner/SceneRenderRequestPlanner.md) +- [SceneRenderRequestUtils](../../Planning/SceneRenderRequestUtils/SceneRenderRequestUtils.md) +- [Camera Request Planning And Clear Rules](../../../../_guides/Rendering/Camera-Request-Planning-And-Clear-Rules.md) + diff --git a/docs/api/XCEngine/Rendering/Extraction/Extraction.md b/docs/api/XCEngine/Rendering/Extraction/Extraction.md new file mode 100644 index 00000000..7b7ea224 --- /dev/null +++ b/docs/api/XCEngine/Rendering/Extraction/Extraction.md @@ -0,0 +1,33 @@ +# Extraction + +**命名空间**: `XCEngine::Rendering` + +**类型**: `submodule` + +**头文件目录**: `engine/include/XCEngine/Rendering/Extraction/` + +**描述**: Rendering 场景提取层，负责把 `Scene` 和 `CameraComponent` 压平成 `RenderSceneData`、`RenderCameraData` 与 `VisibleRenderItem`。 + +## 概览 + +`Extraction` 解决的是“场景语义如何转换成渲染语义”。 + +当前它由两个公开入口组成： + +- [RenderSceneExtractor](RenderSceneExtractor/RenderSceneExtractor.md) +- [RenderSceneUtility](RenderSceneUtility/RenderSceneUtility.md) + +## 当前职责 + +- 选择当前应使用的相机 +- 提取主方向光和 additional lights +- 遍历场景层级并收集 `VisibleRenderItem` +- 构建 `RenderCameraData` + +## 相关文档 + +- [Rendering](../Rendering.md) +- [FrameData](../FrameData/FrameData.md) +- [Execution](../Execution/Execution.md) +- [Scene Extraction And Builtin Forward Pipeline](../../../_guides/Rendering/Scene-Extraction-And-Builtin-Forward-Pipeline.md) + diff --git a/docs/api/XCEngine/Rendering/Extraction/RenderSceneExtractor/RenderSceneExtractor.md b/docs/api/XCEngine/Rendering/Extraction/RenderSceneExtractor/RenderSceneExtractor.md new file mode 100644 index 00000000..1670047b --- /dev/null +++ b/docs/api/XCEngine/Rendering/Extraction/RenderSceneExtractor/RenderSceneExtractor.md @@ -0,0 +1,40 @@ +# RenderSceneExtractor + +**命名空间**: `XCEngine::Rendering` + +**类型**: `class` + +**头文件**: `XCEngine/Rendering/Extraction/RenderSceneExtractor.h` + +**描述**: 把 `Scene` 压平成渲染侧可消费的 `RenderSceneData`，负责相机选择、环境与光照提取，以及 `visibleItems` 收集。 + +## 概览 + +`RenderSceneExtractor` 处在 `Scene` 与 `CameraRenderer` 之间。 + +它当前公开三条入口： + +- `Extract(...)` +- `ExtractForCamera(...)` +- `SelectCamera(...)` + +## 当前提取内容 + +- 当前相机 +- [RenderCameraData](../../FrameData/RenderCameraData/RenderCameraData.md) +- [RenderEnvironmentData](../../FrameData/RenderEnvironmentData/RenderEnvironmentData.md) +- `RenderLightingData` +- `visibleItems` + +## 当前实现边界 + +- 当前仍没有 frustum culling、occlusion culling 或 batching。 +- 当前光照提取仍以主方向光和 additional lights 快照为主。 + +## 相关文档 + +- [Extraction](../Extraction.md) +- [RenderSceneUtility](../RenderSceneUtility/RenderSceneUtility.md) +- [RenderSceneData](../../FrameData/RenderSceneData/RenderSceneData.md) +- [CameraRenderer](../../Execution/CameraRenderer/CameraRenderer.md) + diff --git a/docs/api/XCEngine/Rendering/Extraction/RenderSceneUtility/RenderSceneUtility.md b/docs/api/XCEngine/Rendering/Extraction/RenderSceneUtility/RenderSceneUtility.md new file mode 100644 index 00000000..d4dd1835 --- /dev/null +++ b/docs/api/XCEngine/Rendering/Extraction/RenderSceneUtility/RenderSceneUtility.md @@ -0,0 +1,34 @@ +# RenderSceneUtility + +**命名空间**: `XCEngine::Rendering` + +**类型**: `utility header` + +**头文件**: `XCEngine/Rendering/Extraction/RenderSceneUtility.h` + +**描述**: 提供把相机和场景对象翻译成 `RenderCameraData` 与 `VisibleRenderItem` 的基础 helper。 + +## 当前公开函数 + +- `BuildRenderCameraData(...)` +- `AppendRenderItemsForGameObject(...)` +- `CompareVisibleRenderItemsStable(...)` +- `CollectRenderItemsForEntityIds(...)` +- `IsUsableLight(...)` +- `IsLightVisibleForCullingMask(...)` +- `BuildRenderLightDirection(...)` +- `FindMainDirectionalLight(...)` + +## 当前语义 + +- `BuildRenderCameraData(...)` 负责构建矩阵、姿态、viewport 尺寸与默认 clear 参数。 +- `AppendRenderItemsForGameObject(...)` 会把 `GameObject` 展开成一个或多个 `VisibleRenderItem`。 +- `CollectRenderItemsForEntityIds(...)` 用于按实体 ID 收集渲染项，常见于 editor 工具链。 + +## 相关文档 + +- [Extraction](../Extraction.md) +- [RenderSceneExtractor](../RenderSceneExtractor/RenderSceneExtractor.md) +- [RenderCameraData](../../FrameData/RenderCameraData/RenderCameraData.md) +- [VisibleRenderItem](../../FrameData/VisibleRenderItem/VisibleRenderItem.md) + diff --git a/docs/api/XCEngine/Rendering/FrameData/FrameData.md b/docs/api/XCEngine/Rendering/FrameData/FrameData.md new file mode 100644 index 00000000..9a499788 --- /dev/null +++ b/docs/api/XCEngine/Rendering/FrameData/FrameData.md @@ -0,0 +1,35 @@ +# FrameData + +**命名空间**: `XCEngine::Rendering` + +**类型**: `submodule` + +**头文件目录**: `engine/include/XCEngine/Rendering/FrameData/` + +**描述**: Rendering 帧数据协议层，定义相机、环境、光照、场景和可见渲染项在提交阶段使用的中间结构。 + +## 概览 + +`FrameData` 是 `Extraction` 与 `Execution` 之间共享的数据语言。 + +当前主要包含： + +- [RenderCameraData](RenderCameraData/RenderCameraData.md) +- [RenderEnvironmentData](RenderEnvironmentData/RenderEnvironmentData.md) +- [RenderSceneData](RenderSceneData/RenderSceneData.md) +- [VisibleRenderItem](VisibleRenderItem/VisibleRenderItem.md) + +## 当前职责 + +- 承载渲染相机矩阵与清屏参数 +- 承载环境与 skybox 语义 +- 承载主方向光、阴影和 additional lights 快照 +- 承载 scene extraction 之后的 `visibleItems` + +## 相关文档 + +- [Rendering](../Rendering.md) +- [Planning](../Planning/Planning.md) +- [Extraction](../Extraction/Extraction.md) +- [Execution](../Execution/Execution.md) + diff --git a/docs/api/XCEngine/Rendering/FrameData/RenderCameraData/RenderCameraData.md b/docs/api/XCEngine/Rendering/FrameData/RenderCameraData/RenderCameraData.md new file mode 100644 index 00000000..7ce1d7c7 --- /dev/null +++ b/docs/api/XCEngine/Rendering/FrameData/RenderCameraData/RenderCameraData.md @@ -0,0 +1,49 @@ +# RenderCameraData + +**命名空间**: `XCEngine::Rendering` + +**类型**: `struct + enum` + +**头文件**: `XCEngine/Rendering/FrameData/RenderCameraData.h` + +**描述**: 承载渲染阶段实际使用的相机矩阵、视口尺寸、世界姿态和清屏参数；同头文件还定义 `RenderClearFlags` 位标志。 + +## 概览 + +`RenderCameraData` 是组件层相机到渲染层 frame data 的桥接结构。 + +当前它不仅保存： + +- `view / projection / viewProjection` +- `worldPosition / worldRight / worldUp / worldForward` +- `viewportWidth / viewportHeight` + +还保存当前提交最终会消费的： + +- `clearColor` +- `clearFlags` +- projection mode 与 clip 参数 + +## `RenderClearFlags` + +同头文件里的 `RenderClearFlags` 当前定义： + +- `None` +- `Color` +- `Depth` +- `All` + +并提供 `operator|`、`operator&` 和 `HasRenderClearFlag(...)` helper。 + +## 当前调用链 + +- [RenderSceneUtility](../../Extraction/RenderSceneUtility/RenderSceneUtility.md) 负责构建初始 `RenderCameraData` +- [RenderSceneData](../RenderSceneData/RenderSceneData.md) 持有它 +- [CameraRenderRequest](../../Planning/CameraRenderRequest/CameraRenderRequest.md) 会在执行前进一步覆盖 clear 语义 + +## 相关文档 + +- [FrameData](../FrameData.md) +- [RenderSceneUtility](../../Extraction/RenderSceneUtility/RenderSceneUtility.md) +- [RenderSceneData](../RenderSceneData/RenderSceneData.md) + diff --git a/docs/api/XCEngine/Rendering/FrameData/RenderEnvironmentData/RenderEnvironmentData.md b/docs/api/XCEngine/Rendering/FrameData/RenderEnvironmentData/RenderEnvironmentData.md new file mode 100644 index 00000000..2785e09c --- /dev/null +++ b/docs/api/XCEngine/Rendering/FrameData/RenderEnvironmentData/RenderEnvironmentData.md @@ -0,0 +1,34 @@ +# RenderEnvironmentData + +**命名空间**: `XCEngine::Rendering` + +**类型**: `structs + enum` + +**头文件**: `XCEngine/Rendering/FrameData/RenderEnvironmentData.h` + +**描述**: 描述当前渲染提交使用的环境模式与 skybox 数据，支持 procedural skybox 与 material skybox 两条路径。 + +## 头文件中的类型 + +- `RenderEnvironmentMode` +- `ProceduralSkyboxData` +- `MaterialSkyboxData` +- `RenderEnvironmentData` + +## 当前语义 + +- `RenderEnvironmentMode::None` 表示不绘制 skybox。 +- `ProceduralSkyboxData` 保存顶部、地平线与底部颜色。 +- `MaterialSkyboxData` 保存 skybox 材质指针，并通过 `IsValid()` 检查是否可用。 +- `RenderEnvironmentData` 通过 `HasProceduralSkybox()`、`HasMaterialSkybox()` 和 `HasSkybox()` 暴露统一查询入口。 + +## 当前实现边界 + +- 它只描述环境数据，不直接执行 skybox pass。 +- `MaterialSkyboxData` 目前只保存材质指针，不持有额外 GPU 资源。 + +## 相关文档 + +- [FrameData](../FrameData.md) +- [RenderSceneData](../RenderSceneData/RenderSceneData.md) + diff --git a/docs/api/XCEngine/Rendering/FrameData/RenderSceneData/RenderSceneData.md b/docs/api/XCEngine/Rendering/FrameData/RenderSceneData/RenderSceneData.md new file mode 100644 index 00000000..21e02cc4 --- /dev/null +++ b/docs/api/XCEngine/Rendering/FrameData/RenderSceneData/RenderSceneData.md @@ -0,0 +1,62 @@ +# RenderSceneData + +**命名空间**: `XCEngine::Rendering` + +**类型**: `struct + related structs + enum` + +**头文件**: `XCEngine/Rendering/FrameData/RenderSceneData.h` + +**描述**: scene extraction 之后的核心帧数据块，汇总相机、环境、光照、全局 shader keywords 与 `visibleItems`。 + +## 头文件中的主要类型 + +- `RenderDirectionalLightData` +- `RenderLightType` +- `RenderAdditionalLightData` +- `RenderDirectionalShadowData` +- `RenderLightingData` +- `RenderSceneData` + +## `RenderLightingData` + +当前光照快照包含： + +- 一盏 `mainDirectionalLight` +- 一份 `mainDirectionalShadow` +- 最多 `8` 盏 `additionalLights` + +并通过： + +- `HasMainDirectionalLight()` +- `HasMainDirectionalShadow()` +- `HasAdditionalLights()` + +暴露快速判断。 + +## `RenderSceneData` + +核心字段包括： + +- `camera` +- `cameraData` +- `environment` +- `lighting` +- `globalShaderKeywords` +- `visibleItems` + +`HasCamera()` 当前只检查 `camera != nullptr`。 + +## 当前调用链 + +- [RenderSceneExtractor](../../Extraction/RenderSceneExtractor/RenderSceneExtractor.md) 生成 `RenderSceneData` +- [CameraRenderer](../../Execution/CameraRenderer/CameraRenderer.md) 消费它 +- builtin pipeline 和各类 pass 从它的 `visibleItems` / lighting / cameraData 继续取数 + +## 相关文档 + +- [FrameData](../FrameData.md) +- [RenderCameraData](../RenderCameraData/RenderCameraData.md) +- [RenderEnvironmentData](../RenderEnvironmentData/RenderEnvironmentData.md) +- [VisibleRenderItem](../VisibleRenderItem/VisibleRenderItem.md) +- [RenderSceneExtractor](../../Extraction/RenderSceneExtractor/RenderSceneExtractor.md) + diff --git a/docs/api/XCEngine/Rendering/FrameData/VisibleRenderItem/VisibleRenderItem.md b/docs/api/XCEngine/Rendering/FrameData/VisibleRenderItem/VisibleRenderItem.md new file mode 100644 index 00000000..08809b6f --- /dev/null +++ b/docs/api/XCEngine/Rendering/FrameData/VisibleRenderItem/VisibleRenderItem.md @@ -0,0 +1,38 @@ +# VisibleRenderItem + +**命名空间**: `XCEngine::Rendering` + +**类型**: `struct` + +**头文件**: `XCEngine/Rendering/FrameData/VisibleRenderItem.h` + +**描述**: scene extraction 之后交给渲染阶段消费的一条可绘制项记录，已经带上材质槽位、section、render queue、相机距离和世界变换。 + +## 字段 + +| 字段 | 说明 | +|------|------| +| `gameObject` | 来源场景对象。 | +| `meshFilter` | 提供 mesh 引用的组件。 | +| `meshRenderer` | 提供材质与渲染状态的组件。 | +| `mesh` | 当前要绘制的 mesh。 | +| `material` | 当前解析出的材质指针，可为空。 | +| `materialIndex` | 当前材质槽位索引。 | +| `sectionIndex` | 当前 section 索引。 | +| `hasSection` | 当前项是否绑定到特定 section。 | +| `renderQueue` | 当前项的渲染队列。 | +| `cameraDistanceSq` | 到当前相机的距离平方。 | +| `localToWorld` | 当前项的世界变换。 | + +## 当前语义 + +- 同一个 `GameObject` 可能展开成多个 `VisibleRenderItem`。 +- opaque / transparent 的默认排序都会消费 `renderQueue` 与 `cameraDistanceSq`。 +- 这个结构是当前正式名称；旧文档里的 `VisibleRenderObject` 应视为兼容历史命名。 + +## 相关文档 + +- [FrameData](../FrameData.md) +- [RenderSceneData](../RenderSceneData/RenderSceneData.md) +- [RenderSceneUtility](../../Extraction/RenderSceneUtility/RenderSceneUtility.md) + diff --git a/docs/api/XCEngine/Rendering/Materials/Materials.md b/docs/api/XCEngine/Rendering/Materials/Materials.md new file mode 100644 index 00000000..f345e452 --- /dev/null +++ b/docs/api/XCEngine/Rendering/Materials/Materials.md @@ -0,0 +1,33 @@ +# Materials + +**命名空间**: `XCEngine::Rendering` + +**类型**: `submodule` + +**头文件目录**: `engine/include/XCEngine/Rendering/Materials/` + +**描述**: 渲染材质解析与状态辅助层，负责把 `Material` 运行时对象翻译成 builtin pass 可直接消费的绑定和状态语义。 + +## 概览 + +`Materials` 是 Rendering 与 `Resources::Material` 之间的桥接层。 + +它当前承接： + +- [RenderMaterialResolve](RenderMaterialResolve/RenderMaterialResolve.md) +- [RenderMaterialStateUtils](RenderMaterialStateUtils/RenderMaterialStateUtils.md) +- [RenderMaterialUtility](../RenderMaterialUtility/RenderMaterialUtility.md) + +## 当前职责 + +- shader pass / builtin pass 语义匹配 +- material render state 转换 +- builtin base-color / alpha-cutoff / skybox 材质数据解析 +- schema-driven 逐材质常量 payload 暴露 +- `VisibleRenderItem` 最终材质与 render queue 解析 + +## 相关文档 + +- [Rendering](../Rendering.md) +- [Builtin](../Builtin/Builtin.md) +- [Passes](../Passes/Passes.md) diff --git a/docs/api/XCEngine/Rendering/Materials/RenderMaterialResolve/RenderMaterialResolve.md b/docs/api/XCEngine/Rendering/Materials/RenderMaterialResolve/RenderMaterialResolve.md new file mode 100644 index 00000000..3f547b1b --- /dev/null +++ b/docs/api/XCEngine/Rendering/Materials/RenderMaterialResolve/RenderMaterialResolve.md @@ -0,0 +1,59 @@ +# RenderMaterialResolve + +**命名空间**: `XCEngine::Rendering` + +**类型**: `utility header` + +**头文件**: `XCEngine/Rendering/Materials/RenderMaterialResolve.h` + +**描述**: 渲染材质解析辅助头，负责把 `Material`、`MeshRendererComponent` 与 `VisibleRenderItem` 翻译成 builtin pass 可直接消费的材质、常量、render queue 与 skybox 语义。 + +## 头文件中的主要类型 + +- `BuiltinForwardMaterialData` +- `BuiltinSkyboxTextureMode` +- `BuiltinSkyboxMaterialData` +- `MaterialConstantLayoutView` +- `MaterialConstantPayloadView` + +## 当前公开能力 + +这份头文件当前主要承接四类解析： + +1. builtin pass 匹配 +2. base-color / alpha-cutoff / skybox 材质数据解析 +3. schema-driven 逐材质常量 payload 暴露 +4. `VisibleRenderItem` 最终材质与 render queue 解析 + +## 关键 helper + +- `FindShaderPropertyBySemantic(...)` +- `ResolveBuiltinBaseColorFactor(...)` +- `ResolveBuiltinBaseColorTexture(...)` +- `ResolveBuiltinAlphaCutoff(...)` +- `BuildBuiltinForwardMaterialData(...)` +- `ResolveSkyboxPanoramicTexture(...)` +- `ResolveSkyboxCubemapTexture(...)` +- `ResolveSkyboxTextureMode(...)` +- `ResolveSkyboxTint(...)` +- `ResolveSkyboxExposure(...)` +- `ResolveSkyboxRotationDegrees(...)` +- `BuildBuiltinSkyboxMaterialData(...)` +- `ResolveSchemaMaterialConstantPayload(...)` +- `ResolveMaterial(...)` +- `ResolveMaterialRenderQueue(...)` +- `IsTransparentRenderQueue(...)` +- `MatchesBuiltinPass(...)` + +## 当前实现边界 + +- 它只负责材质语义解析，不直接创建 descriptor set 或 pipeline state。 +- `ResolveSchemaMaterialConstantPayload(...)` 暴露的是借用视图，不负责重新打包或持有内存。 +- 没有显式 builtin metadata 的材质仍会按兼容规则回退到 `ForwardLit`。 + +## 相关文档 + +- [Materials](../Materials.md) +- [RenderMaterialStateUtils](../RenderMaterialStateUtils/RenderMaterialStateUtils.md) +- [Builtin](../../Builtin/Builtin.md) +- [RenderMaterialUtility](../../RenderMaterialUtility/RenderMaterialUtility.md) diff --git a/docs/api/XCEngine/Rendering/Materials/RenderMaterialStateUtils/RenderMaterialStateUtils.md b/docs/api/XCEngine/Rendering/Materials/RenderMaterialStateUtils/RenderMaterialStateUtils.md new file mode 100644 index 00000000..478fd7d5 --- /dev/null +++ b/docs/api/XCEngine/Rendering/Materials/RenderMaterialStateUtils/RenderMaterialStateUtils.md @@ -0,0 +1,41 @@ +# RenderMaterialStateUtils + +**命名空间**: `XCEngine::Rendering` + +**类型**: `utility header` + +**头文件**: `XCEngine/Rendering/Materials/RenderMaterialStateUtils.h` + +**描述**: 渲染材质状态转换辅助头，负责把 `MaterialRenderState` 翻译成 RHI 栅格化、混合和深度模板状态，并提供哈希辅助。 + +## 当前公开能力 + +- `ToRHICullMode(...)` +- `ToRHIComparisonFunc(...)` +- `ToRHIBlendFactor(...)` +- `ToRHIBlendOp(...)` +- `BuildRasterizerState(...)` +- `BuildBlendState(...)` +- `BuildDepthStencilState(...)` +- `ApplyMaterialRenderState(...)` +- `MaterialRenderStateHash` + +## 当前语义 + +- `BuildRasterizerState(...)` 负责填充剔除模式和通用 rasterizer 默认值。 +- `BuildBlendState(...)` 负责把材质的颜色 / alpha 混合参数映射到 `RHI::BlendDesc`。 +- `BuildDepthStencilState(...)` 负责把深度测试、深度写入和比较函数映射到 `RHI::DepthStencilStateDesc`。 +- `ApplyMaterialRenderState(...)` 用一条 helper 把三类状态同时写入 `RHI::GraphicsPipelineDesc`。 +- `MaterialRenderStateHash` 用于 pipeline-state 缓存键。 + +## 当前调用链 + +- `BuiltinForwardPipeline` 用它构建每个材质对应的 `GraphicsPipelineDesc`。 +- depth-style / object-id 之外的主场景绘制路径都依赖这层 material-state 映射。 + +## 相关文档 + +- [Materials](../Materials.md) +- [RenderMaterialResolve](../RenderMaterialResolve/RenderMaterialResolve.md) +- [BuiltinForwardPipeline](../../Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md) +- [RenderMaterialUtility](../../RenderMaterialUtility/RenderMaterialUtility.md) diff --git a/docs/api/XCEngine/Rendering/ObjectIdEncoding/ObjectIdEncoding.md b/docs/api/XCEngine/Rendering/ObjectIdEncoding/ObjectIdEncoding.md index 9d28e44e..acbf0f2b 100644 --- a/docs/api/XCEngine/Rendering/ObjectIdEncoding/ObjectIdEncoding.md +++ b/docs/api/XCEngine/Rendering/ObjectIdEncoding/ObjectIdEncoding.md @@ -2,56 +2,18 @@ **命名空间**: `XCEngine::Rendering` -**类型**: `utility header` +**类型**: `compatibility page` -**头文件**: `XCEngine/Rendering/ObjectIdEncoding.h` +**描述**: 历史名称页。当前 object-id / picking 颜色编解码 helper 的真实 owner 已迁到 [ObjectIdCodec](../Picking/ObjectIdCodec/ObjectIdCodec.md)。 -**描述**: 提供对象 ID 和颜色缓冲之间的轻量编解码 helper，供 object-id 渲染与拾取链路共享。 +## 当前状态 -## 概览 - -`ObjectIdEncoding.h` 把“对象 ID 写进颜色缓冲，再从颜色缓冲读回来”的协议固定成了三段小函数。 - -当前这套协议主要服务于： - -- [BuiltinObjectIdPass](../Passes/BuiltinObjectIdPass/BuiltinObjectIdPass.md) 把对象 ID 编码到 object-id 纹理 -- [BuiltinObjectIdOutlinePass](../Passes/BuiltinObjectIdOutlinePass/BuiltinObjectIdOutlinePass.md) 生成选中轮廓时复用同样的颜色表示 -- editor viewport 的 object picker 从像素颜色反解回 `entityId` - -## 编码规则 - -### `EncodeObjectIdToUInt32()` - -把传入的 `uint64_t objectId` 截断成低 `32` 位。 - -### `EncodeObjectIdToColor()` - -把编码后的 `uint32` 拆成四个 `8-bit` 通道，并按 `0..255 -> 0..1` 归一化为 `Vector4`： - -- `r` 对应最低 8 位 -- `g` 对应第 8-15 位 -- `b` 对应第 16-23 位 -- `a` 对应第 24-31 位 - -### `DecodeObjectIdFromColor()` - -按同样的通道顺序把 `r/g/b/a` 重新拼回 `uint32_t`。 - -## 当前实现边界 - -- 高于 `32` 位的对象身份当前会被截断，无法通过 object-id 颜色缓冲完整保真。 -- 这里的 helper 只定义字节打包协议，不处理颜色空间、纹理格式选择或 GPU 读回流程。 -- `DecodeObjectIdFromColor()` 返回 `uint32_t`，调用方如果内部仍使用 `uint64_t`，需要自己做扩展或约定。 - -## 真实使用位置 - -- `engine/src/Rendering/Passes/BuiltinObjectIdPass.cpp` 用它把对象 ID 写进 shader 常量。 -- `engine/src/Rendering/Passes/BuiltinObjectIdOutlinePass.cpp` 用它构建选中对象颜色列表。 -- `editor/src/Viewport/ViewportObjectIdPicker.h` 用它把像素颜色解码成拾取结果。 +- 旧文档里的 `ObjectIdEncoding` 只是历史叫法。 +- 当前真实头文件是 `XCEngine/Rendering/Picking/ObjectIdCodec.h`。 +- 新增文档与调用链说明应统一回到 [ObjectIdCodec](../Picking/ObjectIdCodec/ObjectIdCodec.md)。 ## 相关文档 -- [当前模块](../Rendering.md) -- [ObjectIdPass](../ObjectIdPass/ObjectIdPass.md) +- [Picking](../Picking/Picking.md) +- [ObjectIdCodec](../Picking/ObjectIdCodec/ObjectIdCodec.md) - [BuiltinObjectIdPass](../Passes/BuiltinObjectIdPass/BuiltinObjectIdPass.md) -- [BuiltinObjectIdOutlinePass](../Passes/BuiltinObjectIdOutlinePass/BuiltinObjectIdOutlinePass.md) diff --git a/docs/api/XCEngine/Rendering/ObjectIdPass/ObjectIdPass.md b/docs/api/XCEngine/Rendering/ObjectIdPass/ObjectIdPass.md index c35f6740..beecf3e4 100644 --- a/docs/api/XCEngine/Rendering/ObjectIdPass/ObjectIdPass.md +++ b/docs/api/XCEngine/Rendering/ObjectIdPass/ObjectIdPass.md @@ -2,67 +2,45 @@ **命名空间**: `XCEngine::Rendering` -**类型**: `interface` +**类型**: `concept` -**头文件**: `XCEngine/Rendering/ObjectIdPass.h` - -**描述**: 定义把 `RenderSceneData` 渲染到 object-id 目标表面的抽象接口，供 `CameraRenderer` 注入具体实现。 +**描述**: object-id 阶段的历史概念页。当前引擎不再公开独立的 `ObjectIdPass.h` 接口，而是把 object-id 输出槽位收口为可注入的 `RenderPass` 实现。 ## 概览 -`ObjectIdPass` 是 `CameraRenderer` 主链路里的一个可替换插槽。 +`ObjectIdPass` 这个名字在当前实现里仍然有语义价值，但它已经不再对应单独的 public header。 -它的职责很明确： +- `CameraRenderer::SetObjectIdPass(...)` 当前接受的是 `std::unique_ptr`。 +- 默认实现是 [BuiltinObjectIdPass](../Passes/BuiltinObjectIdPass/BuiltinObjectIdPass.md)。 +- `CameraRenderRequest::objectId` 只描述输出目标，不描述实现类型。 + +因此这里更适合作为“object-id 阶段是什么”的迁移索引，而不是独立 API 页。 + +## 当前运行时契约 + +object-id 阶段的运行时输入输出仍然很稳定： - 输入已经提取好的 `RenderSceneData` -- 输出一张 object-id 颜色目标 -- 不参与主管线本身的颜色绘制 - -当前默认实现是 [BuiltinObjectIdPass](../Passes/BuiltinObjectIdPass/BuiltinObjectIdPass.md)，但 `CameraRenderer` 允许调用方替换成别的实现，测试里也正是通过 mock pass 验证执行时序和失败回滚。 - -## 接口契约 - -### `Render()` - -调用方会把： - -- 当前帧的 `RenderContext` -- object-id 输出目标 `RenderSurface` -- 已经提取完成的 `RenderSceneData` - -一起传进来。返回 `false` 表示本次 object-id 渲染失败，`CameraRenderer::Render()` 会直接终止本次相机提交。 - -### `Shutdown()` - -默认实现为空，用于给具体 pass 释放缓存的 GPU 资源或内部状态。 - -`CameraRenderer` 会在以下时机调用它： - -- 替换 object-id pass 时 -- `CameraRenderer` 自身析构时 +- 输入 object-id 输出 `RenderSurface` +- 由一个实现 `RenderPass` 的 scene pass 负责真正提交 GPU 命令 +- 返回 `false` 时，`CameraRenderer::Render()` 会直接终止这次相机提交 ## 当前接入位置 -在 [CameraRenderer](../CameraRenderer/CameraRenderer.md) 里，object-id pass 的执行顺序是： +在 [CameraRenderer](../CameraRenderer/CameraRenderer.md) 里，object-id 阶段当前位于： 1. 执行 pre-scene pass 2. 如请求了 `shadowCaster` / `depthOnly`，先执行对应 scene pass 3. 绘制主 `RenderPipeline` -4. 如果 `request.objectId.IsRequested()`，执行 `ObjectIdPass` +4. 如果 `request.objectId.IsRequested()`，执行当前注入的 object-id `RenderPass` 5. 再执行 `postScenePasses` 6. 最后执行 `overlayPasses` -## 当前实现边界 +## 当前迁移关系 -- `ObjectIdPass` 只定义单次 object-id 绘制接口，不负责请求是否合法；这部分先由 `CameraRenderRequest` 和 `CameraRenderer` 做基础校验。 -- 接口没有显式的 `Initialize()` 阶段，具体实现通常在第一次 `Render()` 时懒初始化，或在构造期准备资源。 -- 当前引擎默认只维护一个 object-id pass 实例，由 `CameraRenderer` 持有。 - -## 真实使用位置 - -- `engine/src/Rendering/CameraRenderer.cpp` -- `engine/src/Rendering/Passes/BuiltinObjectIdPass.cpp` -- `tests/Rendering/unit/test_camera_scene_renderer.cpp` +- 如果你要看默认实现，请读 [BuiltinObjectIdPass](../Passes/BuiltinObjectIdPass/BuiltinObjectIdPass.md)。 +- 如果你要看 request 侧目标描述，请读 [ObjectIdRenderRequest](../CameraRenderRequest/ObjectIdRenderRequest/ObjectIdRenderRequest.md)。 +- 如果你要看 object-id 编码协议，请读 [ObjectIdCodec](../Picking/ObjectIdCodec/ObjectIdCodec.md) 与 [ObjectIdEncoding](../ObjectIdEncoding/ObjectIdEncoding.md)。 ## 相关文档 @@ -70,3 +48,4 @@ - [CameraRenderer](../CameraRenderer/CameraRenderer.md) - [ObjectIdRenderRequest](../CameraRenderRequest/ObjectIdRenderRequest/ObjectIdRenderRequest.md) - [BuiltinObjectIdPass](../Passes/BuiltinObjectIdPass/BuiltinObjectIdPass.md) +- [ObjectIdCodec](../Picking/ObjectIdCodec/ObjectIdCodec.md) diff --git a/docs/api/XCEngine/Rendering/Passes/BuiltinColorScalePostProcessPass/BuiltinColorScalePostProcessPass.md b/docs/api/XCEngine/Rendering/Passes/BuiltinColorScalePostProcessPass/BuiltinColorScalePostProcessPass.md new file mode 100644 index 00000000..0facb795 --- /dev/null +++ b/docs/api/XCEngine/Rendering/Passes/BuiltinColorScalePostProcessPass/BuiltinColorScalePostProcessPass.md @@ -0,0 +1,62 @@ +# BuiltinColorScalePostProcessPass + +**命名空间**: `XCEngine::Rendering::Passes` + +**类型**: `class` + +**头文件**: `XCEngine/Rendering/Passes/BuiltinColorScalePostProcessPass.h` + +**描述**: 当前内建的 fullscreen post-process pass，对 `sourceColorView` 采样后按给定 `colorScale` 乘算，并输出到目标颜色附件。 + +## 概览 + +`BuiltinColorScalePostProcessPass` 是 `CameraRenderer` fullscreen 阶段当前最简单的一条后处理实现。 + +它的输入输出模型很明确： + +- 输入来自 `RenderPassContext::sourceColorView` +- 输出写入 `RenderPassContext::surface` 的第一个颜色附件 +- 处理方式是对采样结果乘以 `colorScale` + +## 当前执行前提 + +`Execute(...)` 当前要求： + +- `renderContext` 有效 +- `sourceColorView != nullptr` +- 目标 `surface` 至少有一个有效颜色附件 +- `renderArea.width > 0 && renderArea.height > 0` + +否则直接返回 `false`。 + +## 当前实现细节 + +- 如果构造时没给 `shaderPath`，会回退到 builtin color-scale shader 路径。 +- 资源初始化会按 `(device, backend, renderTargetFormat)` 惰性重建。 +- 当前固定创建三组 descriptor set： + - constants CBV + - source color SRV + - linear clamp sampler +- 提交阶段绘制一个 fullscreen triangle，避免显式 quad 顶点缓冲。 +- 如果 `surface` 开启自动状态切换，会在 `RenderTarget` 与 `surface.GetColorStateAfter()` 之间自动迁移。 + +## 当前公开方法 + +- `GetName()` +- `Execute(...)` +- `Shutdown()` +- `SetColorScale(...)` / `GetColorScale()` +- `SetShaderPath(...)` / `GetShaderPath()` + +## 真实使用位置 + +- [CameraPostProcessPassFactory](../../Planning/CameraPostProcessPassFactory/CameraPostProcessPassFactory.md) 当前会把 `ColorScale` 声明转换成它。 +- `SceneRenderer` 把生成的 sequence 挂到 `CameraRenderRequest::postProcess`。 +- `tests/Rendering/integration/post_process_scene/` 覆盖了真实 fullscreen 链路。 + +## 相关文档 + +- [Passes](../Passes.md) +- [CameraPostProcessDesc](../../Planning/CameraPostProcessDesc/CameraPostProcessDesc.md) +- [CameraPostProcessPassFactory](../../Planning/CameraPostProcessPassFactory/CameraPostProcessPassFactory.md) +- [BuiltinFinalColorPass](../BuiltinFinalColorPass/BuiltinFinalColorPass.md) diff --git a/docs/api/XCEngine/Rendering/Passes/BuiltinFinalColorPass/BuiltinFinalColorPass.md b/docs/api/XCEngine/Rendering/Passes/BuiltinFinalColorPass/BuiltinFinalColorPass.md new file mode 100644 index 00000000..ed169b3a --- /dev/null +++ b/docs/api/XCEngine/Rendering/Passes/BuiltinFinalColorPass/BuiltinFinalColorPass.md @@ -0,0 +1,63 @@ +# BuiltinFinalColorPass + +**命名空间**: `XCEngine::Rendering::Passes` + +**类型**: `class` + +**头文件**: `XCEngine/Rendering/Passes/BuiltinFinalColorPass.h` + +**描述**: 当前内建的 final-output fullscreen pass，对中间 scene color 应用输出传递、曝光、色调映射和最终颜色缩放，再写回最终颜色目标。 + +## 概览 + +`BuiltinFinalColorPass` 是主场景绘制之后、真正写回最终颜色目标之前的最后一层颜色处理。 + +它消费的是 [FinalColorSettings](../../Planning/FinalColorSettings/FinalColorSettings.md)： + +- `outputTransferMode` +- `exposureMode` / `exposureValue` +- `toneMappingMode` +- `finalColorScale` + +## 当前执行前提 + +`Execute(...)` 当前要求： + +- `renderContext` 有效 +- `sourceColorView != nullptr` +- 目标 `surface` 至少有一个有效颜色附件 +- `renderArea` 宽高都大于 `0` + +不满足时会记录错误并返回 `false`。 + +## 当前实现细节 + +- 默认 `shaderPath` 会回退到 builtin final-color shader。 +- 内部把 `FinalColorSettings` 写入一份 fullscreen 常量： + - `colorScale` + - `params.x = exposure multiplier` + - `params.y = outputTransferMode` + - `params.z = toneMappingMode` +- `FinalColorExposureMode::Fixed` 会把 `exposureValue` 钳到非负后再参与计算。 +- 和 color-scale pass 一样，当前也使用 constants / texture / sampler 三组 descriptor set 加 fullscreen triangle。 + +## 当前公开方法 + +- `GetName()` +- `Execute(...)` +- `Shutdown()` +- `SetSettings(...)` / `GetSettings()` +- `SetShaderPath(...)` / `GetShaderPath()` + +## 真实使用位置 + +- [FinalColorPassFactory](../../Planning/FinalColorPassFactory/FinalColorPassFactory.md) 当前会在需要处理时生成这条 pass。 +- `SceneRenderer` 把生成的 sequence 挂到 `CameraRenderRequest::finalOutput`。 +- `tests/Rendering/integration/final_color_scene/` 覆盖了真实 final-color 链路。 + +## 相关文档 + +- [Passes](../Passes.md) +- [FinalColorSettings](../../Planning/FinalColorSettings/FinalColorSettings.md) +- [FinalColorPassFactory](../../Planning/FinalColorPassFactory/FinalColorPassFactory.md) +- [BuiltinColorScalePostProcessPass](../BuiltinColorScalePostProcessPass/BuiltinColorScalePostProcessPass.md) diff --git a/docs/api/XCEngine/Rendering/Passes/BuiltinObjectIdPass/BuiltinObjectIdPass.md b/docs/api/XCEngine/Rendering/Passes/BuiltinObjectIdPass/BuiltinObjectIdPass.md index 37927262..f5126033 100644 --- a/docs/api/XCEngine/Rendering/Passes/BuiltinObjectIdPass/BuiltinObjectIdPass.md +++ b/docs/api/XCEngine/Rendering/Passes/BuiltinObjectIdPass/BuiltinObjectIdPass.md @@ -32,7 +32,8 @@ - 当前 input layout 沿用 `Resources::StaticMeshVertex` 的 `POSITION / NORMAL / TEXCOORD0` 三元素布局，而不是单独定义一套 object-id 专用顶点流。 - 每个 object ID 会缓存一套独立 descriptor set，避免重复分配常量绑定。 - `RenderResourceCache` 负责把 `Mesh` 上传或复用成 GPU 资源。 -- 资源声明会优先读取 shader pass 自己的 `resources`，若为空则回退到 [BuildLegacyBuiltinObjectIdPassResourceBindings](../../RenderMaterialUtility/BuildLegacyBuiltinObjectIdPassResourceBindings.md)，再统一交给 [TryBuildBuiltinPassResourceBindingPlan](../../RenderMaterialUtility/TryBuildBuiltinPassResourceBindingPlan.md) 解析。 +- 当前 object-id shader pass 必须显式声明 `resources`；如果为空，`BuiltinObjectIdPass` 会直接报错，而不是自动生成 legacy fallback 绑定。 +- 显式资源声明随后会统一交给 [TryBuildBuiltinPassResourceBindingPlan](../../RenderMaterialUtility/TryBuildBuiltinPassResourceBindingPlan.md) 解析，并进一步要求最终 plan 只包含唯一的 `PerObject` constant-buffer 绑定。 - shader pass 解析优先匹配 builtin object-id pass tag，其次回退到 `ObjectId` / `EditorObjectId` 命名，最后才退到首个 pass。 ## 当前实现边界 diff --git a/docs/api/XCEngine/Rendering/Passes/Passes.md b/docs/api/XCEngine/Rendering/Passes/Passes.md index ebf821af..683650f0 100644 --- a/docs/api/XCEngine/Rendering/Passes/Passes.md +++ b/docs/api/XCEngine/Rendering/Passes/Passes.md @@ -4,7 +4,7 @@ **类型**: `submodule` -**描述**: 承载 builtin object-id、selection outline、infinite grid，以及 depth-only / shadow-caster 一类可复用渲染 pass 与配套样式/参数类型。 +**描述**: 承载 builtin object-id、selection outline、infinite grid、fullscreen post-process / final-color，以及 depth-only / shadow-caster 一类可复用渲染 pass 与配套样式/参数类型。 ## 概述 @@ -16,8 +16,10 @@ - [BuiltinDepthStylePassBase](BuiltinDepthStylePassBase/BuiltinDepthStylePassBase.md) 为深度风格场景重绘 pass 提供共享执行骨架。 - [BuiltinDepthOnlyPass](BuiltinDepthOnlyPass/BuiltinDepthOnlyPass.md) 是 `CameraRenderer` 默认 `depthOnly` request 的 builtin 实现。 - [BuiltinShadowCasterPass](BuiltinShadowCasterPass/BuiltinShadowCasterPass.md) 是 `CameraRenderer` 默认 `shadowCaster` request 的 builtin 实现。 +- [BuiltinColorScalePostProcessPass](BuiltinColorScalePostProcessPass/BuiltinColorScalePostProcessPass.md) 是当前 camera post-process stack 的 fullscreen 颜色缩放实现。 +- [BuiltinFinalColorPass](BuiltinFinalColorPass/BuiltinFinalColorPass.md) 是当前 final-output 阶段的 fullscreen 最终颜色处理实现。 -其中 object-id / outline / infinite-grid 更接近“主场景之外的附加结果”；depth-only / shadow-caster 则属于 `ScenePassRenderRequest` 路径，会在 `CameraRenderer` 中作为场景重绘 pass 直接执行，而不是 editor overlay 逻辑的一部分。 +其中 object-id / outline / infinite-grid 更接近“主场景之外的附加结果”；depth-only / shadow-caster 属于 `ScenePassRenderRequest` 路径；fullscreen post-process / final-color 则对应 `CameraRenderRequest::postProcess` 与 `finalOutput` 两个阶段。 当前这些 builtin pass 更多是“底层执行单元”。真正决定 Scene View 要不要画网格、要不要叠选中轮廓、这些效果要挂到 `postScenePasses` 还是 `overlayPasses` 上的逻辑，已经迁移到 editor 侧的 [SceneViewportRenderPlan](../../Editor/Viewport/SceneViewportRenderPlan/SceneViewportRenderPlan.md)；真正决定 depth-only / shadow-caster surface 与 clear 策略的，则是 [CameraRenderRequest](../CameraRenderRequest/CameraRenderRequest.md)。 @@ -40,6 +42,15 @@ 2. `CameraRenderer` 在执行主 `RenderPipeline` 前，先按顺序驱动 [BuiltinShadowCasterPass](BuiltinShadowCasterPass/BuiltinShadowCasterPass.md) 与 [BuiltinDepthOnlyPass](BuiltinDepthOnlyPass/BuiltinDepthOnlyPass.md) 的默认实例。 3. 这两类 pass 共用 [BuiltinDepthStylePassBase::Execute](BuiltinDepthStylePassBase/Execute.md) 的执行框架，因此当前都要求 `surface` 同时提供 `colorAttachments[0]` 与 `depthAttachment`，并复用 `renderArea`、clear flags 与状态迁移逻辑。 +### Fullscreen post-process / final-output + +当前 fullscreen 链路大致是： + +1. [SceneRenderer](../SceneRenderer/SceneRenderer.md) 读取相机上的声明式 post-process stack 与 final-color overrides。 +2. [CameraPostProcessPassFactory](../Planning/CameraPostProcessPassFactory/CameraPostProcessPassFactory.md) 把声明式 stack 转成 [BuiltinColorScalePostProcessPass](BuiltinColorScalePostProcessPass/BuiltinColorScalePostProcessPass.md) 序列。 +3. [FinalColorPassFactory](../Planning/FinalColorPassFactory/FinalColorPassFactory.md) 把解析后的 `ResolvedFinalColorPolicy` 转成 [BuiltinFinalColorPass](BuiltinFinalColorPass/BuiltinFinalColorPass.md) 序列。 +4. [CameraRenderer](../CameraRenderer/CameraRenderer.md) 在 `MainScene` 之后按 `PostProcess -> FinalOutput` 顺序执行 fullscreen pass 链；当序列长度大于 `1` 时，会借助中间 surface cache 在多个目标之间串接读写。 + ## 当前公开概念 | 类型 / 头文件 | 角色 | @@ -54,14 +65,17 @@ | [BuiltinDepthStylePassBase](BuiltinDepthStylePassBase/BuiltinDepthStylePassBase.md) | depth-only / shadow-caster 场景重绘共享的执行骨架。 | | [BuiltinDepthOnlyPass](BuiltinDepthOnlyPass/BuiltinDepthOnlyPass.md) | `CameraRenderer` 默认的 depth-only scene pass。 | | [BuiltinShadowCasterPass](BuiltinShadowCasterPass/BuiltinShadowCasterPass.md) | `CameraRenderer` 默认的 shadow-caster scene pass。 | +| [BuiltinColorScalePostProcessPass](BuiltinColorScalePostProcessPass/BuiltinColorScalePostProcessPass.md) | camera post-process 栈当前的 fullscreen 颜色缩放 pass。 | +| [BuiltinFinalColorPass](BuiltinFinalColorPass/BuiltinFinalColorPass.md) | final-output 阶段应用输出传递、曝光、色调映射和颜色缩放的 fullscreen pass。 | ## 测试与真实调用点 - `tests/Rendering/unit/test_camera_scene_renderer.cpp` 验证了 `CameraRenderer` 中 object-id pass 与可选 pass sequence 的接入时机。 - `engine/src/Rendering/CameraRenderer.cpp` 当前把 [BuiltinShadowCasterPass](BuiltinShadowCasterPass/BuiltinShadowCasterPass.md) 与 [BuiltinDepthOnlyPass](BuiltinDepthOnlyPass/BuiltinDepthOnlyPass.md) 作为默认 scene pass 挂进 `shadowCaster` / `depthOnly` request。 -- `tests/Rendering/unit/test_builtin_forward_pipeline.cpp` 固定了 depth-only / shadow-caster 输入布局和 legacy builtin binding plan 的兼容语义。 +- `tests/Rendering/unit/test_builtin_forward_pipeline.cpp` 固定了 depth-only / shadow-caster 资源契约与 final-color shader 的显式 fullscreen 资源声明。 - `tests/Editor/test_scene_viewport_overlay_renderer.cpp` 固定了 `BuildInfiniteGridParameters(...)` 的十进制尺度、过渡和淡出语义。 - `tests/Editor/test_viewport_render_flow_utils.cpp` 验证了 Scene View render plan 如何组装 grid / selection outline / overlay pass，以及 object-id SRV 缺失时的警告路径。 +- `tests/Rendering/integration/post_process_scene/` 和 `tests/Rendering/integration/final_color_scene/` 分别覆盖了 post-process 与 final-output 的真实 fullscreen 渲染路径。 ## 当前实现边界 @@ -79,6 +93,8 @@ - [BuiltinDepthStylePassBase](BuiltinDepthStylePassBase/BuiltinDepthStylePassBase.md) - [BuiltinDepthOnlyPass](BuiltinDepthOnlyPass/BuiltinDepthOnlyPass.md) - [BuiltinShadowCasterPass](BuiltinShadowCasterPass/BuiltinShadowCasterPass.md) +- [BuiltinColorScalePostProcessPass](BuiltinColorScalePostProcessPass/BuiltinColorScalePostProcessPass.md) +- [BuiltinFinalColorPass](BuiltinFinalColorPass/BuiltinFinalColorPass.md) - [SceneViewportRenderPlan](../../Editor/Viewport/SceneViewportRenderPlan/SceneViewportRenderPlan.md) - [CameraRenderRequest](../CameraRenderRequest/CameraRenderRequest.md) - [CameraRenderer](../CameraRenderer/CameraRenderer.md) diff --git a/docs/api/XCEngine/Rendering/Picking/ObjectIdCodec/ObjectIdCodec.md b/docs/api/XCEngine/Rendering/Picking/ObjectIdCodec/ObjectIdCodec.md new file mode 100644 index 00000000..1292a6d1 --- /dev/null +++ b/docs/api/XCEngine/Rendering/Picking/ObjectIdCodec/ObjectIdCodec.md @@ -0,0 +1,37 @@ +# ObjectIdCodec + +**命名空间**: `XCEngine::Rendering` + +**类型**: `utility header` + +**头文件**: `XCEngine/Rendering/Picking/ObjectIdCodec.h` + +**描述**: object-id 颜色编码辅助头，负责把运行时对象 ID 的低 32 位编码到 RGBA 颜色，并提供反向解码 helper。 + +## 当前公开能力 + +- `EncodedObjectId` +- `CanEncodeObjectIdWithoutLoss(...)` +- `EncodeObjectIdToEncodedId(...)` +- `EncodeObjectIdToUInt32(...)` +- `EncodeObjectIdToColor(...)` +- `DecodeEncodedObjectIdFromColor(...)` +- `DecodeObjectIdFromColor(...)` + +## 当前语义 + +- object-id render target 当前只保存运行时对象 ID 的低 32 位。 +- `CanEncodeObjectIdWithoutLoss(...)` 用于判断高 32 位是否全为 `0`。 +- `EncodeObjectIdToColor(...)` 把 `EncodedObjectId` 的四个字节映射到 `RGBA` 分量。 +- `DecodeObjectIdFromColor(...)` 则把四个 8-bit 通道重新拼回 `uint64`。 + +## 当前实现边界 + +- 这套 codec 只适用于 editor/runtime picking surface，不是持久化 ID 编码方案。 +- 如果对象 ID 超过 32 位范围，只能得到截断后的低位结果。 + +## 相关文档 + +- [Picking](../Picking.md) +- [ObjectIdEncoding](../../ObjectIdEncoding/ObjectIdEncoding.md) +- [BuiltinObjectIdPass](../../Passes/BuiltinObjectIdPass/BuiltinObjectIdPass.md) diff --git a/docs/api/XCEngine/Rendering/Picking/Picking.md b/docs/api/XCEngine/Rendering/Picking/Picking.md new file mode 100644 index 00000000..b187ceb6 --- /dev/null +++ b/docs/api/XCEngine/Rendering/Picking/Picking.md @@ -0,0 +1,32 @@ +# Picking + +**命名空间**: `XCEngine::Rendering` + +**类型**: `submodule` + +**头文件目录**: `engine/include/XCEngine/Rendering/Picking/` + +**描述**: 渲染侧 object-id / picking 协议层，负责颜色与实体 ID 之间的编码约定，以及 picker 相关的基础数据格式。 + +## 概览 + +`Picking` 当前主要承接 object-id 纹理的编码与解码约定。 + +它不负责 editor 侧的读回流程编排；那部分仍在 Editor Viewport 层。这里负责的是更底层的 codec 和数据契约。 + +当前公开入口： + +- [ObjectIdCodec](ObjectIdCodec/ObjectIdCodec.md) +- [ObjectIdEncoding](../ObjectIdEncoding/ObjectIdEncoding.md) + +## 当前职责 + +- 约定 object-id render target 的颜色编码格式 +- 暴露颜色到 runtime object id 的解码 helper +- 为 object-id pass、editor picking 和 selection outline 提供一致的数据基础 + +## 相关文档 + +- [Rendering](../Rendering.md) +- [Planning](../Planning/Planning.md) +- [Passes](../Passes/Passes.md) diff --git a/docs/api/XCEngine/Rendering/Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md b/docs/api/XCEngine/Rendering/Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md index 21712ff2..2fce04cb 100644 --- a/docs/api/XCEngine/Rendering/Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md +++ b/docs/api/XCEngine/Rendering/Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md @@ -20,15 +20,12 @@ ## 当前资源契约 -`BuiltinForwardPipeline` 会优先读取 shader pass 自己声明的 `resources`。如果该列表为空，则回退到 [BuildLegacyBuiltinForwardPassResourceBindings](../../RenderMaterialUtility/BuildLegacyBuiltinForwardPassResourceBindings.md) 返回的 legacy builtin forward 绑定： +`BuiltinForwardPipeline` 当前要求 resolved shader pass 显式声明 `resources`。 -- `set 1 binding 0` -> `PerObject` / `CBV` -- `set 2 binding 0` -> `Material` / `CBV` -- `set 3 binding 0` -> `BaseColorTexture` / `Texture2D` -- `set 4 binding 0` -> `LinearClampSampler` / `Sampler` +如果 `resources.Empty()`，实现会直接报错，而不是自动生成 legacy fallback binding plan。 随后会通过 [TryBuildBuiltinPassResourceBindingPlan](../../RenderMaterialUtility/TryBuildBuiltinPassResourceBindingPlan.md) -把显式资源声明或 legacy fallback 统一收口成 +把显式资源声明收口成 [BuiltinPassResourceBindingPlan](../../RenderMaterialUtility/BuiltinPassResourceBindingPlan.md)。 当前可识别的 forward 语义只有四个： @@ -41,7 +38,7 @@ 其中 `Material` 语义当前不是固定写死成某个历史布局。渲染时会先通过 `ResolveSchemaMaterialConstantPayload(material)` 取得 `Material::GetConstantBufferData()` 的字节视图；只有拿不到有效 payload 时， -才会回退到内部 `FallbackPerMaterialConstants { baseColorFactor }`。 +才会回退到内部 `FallbackPerMaterialConstants { baseColorFactor, alphaCutoffParams }`。 binding-plan 解析之后，布局构建阶段还会继续拒绝以下情况： @@ -51,8 +48,6 @@ binding-plan 解析之后，布局构建阶段还会继续拒绝以下情况： - 在同一个 set 中出现重复 binding。 - 缺少 `PerObject`。 -如果第一个实际绑定的 set 大于 `0`，并且 `set 0` 为空，实现还会补一个兼容用的 `set 0`，避免某些布局路径要求从 `set 0` 开始。 - ## 当前渲染流程 1. [Initialize](Initialize.md) 通过 `m_passSequence.Initialize(context)` 进入 pass 生命周期。 @@ -67,7 +62,7 @@ binding-plan 解析之后，布局构建阶段还会继续拒绝以下情况： - 材质贴图解析通过 `ResolveBuiltinBaseColorTexture(material)` 进入 builtin base-color 语义，不再依赖旧文档里的“按若干名字猜测纹理”说法。 - 逐物体常量来自 `PerObjectConstants`。 - 逐材质常量优先来自 `ResolveSchemaMaterialConstantPayload(material)` 暴露的 schema-driven payload； - 如果 view 无效，才回退到内部 `FallbackPerMaterialConstants { baseColorFactor }`。 + 如果 view 无效，才回退到内部 `FallbackPerMaterialConstants { baseColorFactor, alphaCutoffParams }`。 - 采样器和 1x1 白色 fallback 纹理在初始化后长期复用；具体 `Texture` 和 `Mesh` 的 GPU 资源则由 [RenderResourceCache](../../RenderResourceCache/RenderResourceCache.md) 按需上传。 ## 当前限制 diff --git a/docs/api/XCEngine/Rendering/Planning/CameraPostProcessDesc/CameraPostProcessDesc.md b/docs/api/XCEngine/Rendering/Planning/CameraPostProcessDesc/CameraPostProcessDesc.md new file mode 100644 index 00000000..492688fe --- /dev/null +++ b/docs/api/XCEngine/Rendering/Planning/CameraPostProcessDesc/CameraPostProcessDesc.md @@ -0,0 +1,36 @@ +# CameraPostProcessDesc + +**命名空间**: `XCEngine::Rendering` + +**类型**: `enum + structs + alias` + +**头文件**: `XCEngine/Rendering/Planning/CameraPostProcessDesc.h` + +**描述**: 相机后处理描述头，定义相机声明式 post-process 栈当前可用的 pass 类型、参数载体和 stack 别名。 + +## 头文件中的主要类型 + +- `CameraPostProcessPassType` +- `CameraColorScalePostProcessDesc` +- `CameraPostProcessPassDesc` +- `CameraPostProcessStack` + +## 当前语义 + +- `CameraPostProcessPassType` 当前只公开 `ColorScale`。 +- `CameraColorScalePostProcessDesc` 保存全屏颜色缩放向量。 +- `CameraPostProcessPassDesc::MakeColorScale(...)` 提供便捷构造入口。 +- `CameraPostProcessPassDesc::IsValid()` 负责过滤掉当前实现不认识的 pass 类型。 +- `CameraPostProcessStack` 是 `std::vector`，供 `CameraComponent` 直接持有。 + +## 当前调用链 + +- `CameraComponent` 序列化、反序列化并持有这份声明式 stack。 +- [CameraPostProcessPassFactory](../CameraPostProcessPassFactory/CameraPostProcessPassFactory.md) 把它转换成运行时 `RenderPassSequence`。 +- `SceneRenderer` 再把生成的 sequence 挂到 `CameraRenderRequest::postProcess`。 + +## 相关文档 + +- [Planning](../Planning.md) +- [CameraPostProcessPassFactory](../CameraPostProcessPassFactory/CameraPostProcessPassFactory.md) +- [BuiltinColorScalePostProcessPass](../../Passes/BuiltinColorScalePostProcessPass/BuiltinColorScalePostProcessPass.md) diff --git a/docs/api/XCEngine/Rendering/Planning/CameraPostProcessPassFactory/CameraPostProcessPassFactory.md b/docs/api/XCEngine/Rendering/Planning/CameraPostProcessPassFactory/CameraPostProcessPassFactory.md new file mode 100644 index 00000000..612c6a09 --- /dev/null +++ b/docs/api/XCEngine/Rendering/Planning/CameraPostProcessPassFactory/CameraPostProcessPassFactory.md @@ -0,0 +1,35 @@ +# CameraPostProcessPassFactory + +**命名空间**: `XCEngine::Rendering` + +**类型**: `utility header` + +**头文件**: `XCEngine/Rendering/Planning/CameraPostProcessPassFactory.h` + +**描述**: 相机后处理 pass 工厂头，负责把声明式 `CameraPostProcessStack` 转换成运行时 `RenderPassSequence`。 + +## 当前公开能力 + +```cpp +std::unique_ptr BuildCameraPostProcessPassSequence( + const CameraPostProcessStack& postProcessStack); +``` + +## 当前实现行为 + +- 如果 stack 为空，直接返回 `nullptr`。 +- 逐条遍历 `CameraPostProcessPassDesc`，跳过 `IsValid()` 为假的项。 +- 当前只识别 `CameraPostProcessPassType::ColorScale`，并创建 [BuiltinColorScalePostProcessPass](../../Passes/BuiltinColorScalePostProcessPass/BuiltinColorScalePostProcessPass.md)。 +- 如果过滤后没有任何有效 pass，同样返回 `nullptr`。 + +## 当前调用链 + +- `SceneRenderer::AttachFullscreenStageRequests(...)` 调用它构建 `CameraRenderRequest::postProcess.passes`。 +- 生成的 sequence 由 `CameraRenderer` 在 `PostProcess` 阶段按 fullscreen pass 链执行。 + +## 相关文档 + +- [Planning](../Planning.md) +- [CameraPostProcessDesc](../CameraPostProcessDesc/CameraPostProcessDesc.md) +- [BuiltinColorScalePostProcessPass](../../Passes/BuiltinColorScalePostProcessPass/BuiltinColorScalePostProcessPass.md) +- [CameraRenderRequest](../CameraRenderRequest/CameraRenderRequest.md) diff --git a/docs/api/XCEngine/Rendering/Planning/CameraRenderRequest/CameraRenderRequest.md b/docs/api/XCEngine/Rendering/Planning/CameraRenderRequest/CameraRenderRequest.md new file mode 100644 index 00000000..8ba52f36 --- /dev/null +++ b/docs/api/XCEngine/Rendering/Planning/CameraRenderRequest/CameraRenderRequest.md @@ -0,0 +1,55 @@ +# CameraRenderRequest + +**命名空间**: `XCEngine::Rendering` + +**类型**: `struct + related enums + related structs` + +**头文件**: `XCEngine/Rendering/Planning/CameraRenderRequest.h` + +**描述**: 单相机渲染提交的显式请求对象，打包主场景 surface、shadow/depth/object-id/fullscreen 子请求、clear 覆盖、frame-stage 辅助查询，以及可选 pass 序列。 + +## 概览 + +`CameraRenderRequest` 是 [Planning](../Planning.md) 与 [Execution](../../Execution/Execution.md) 之间最核心的数据契约。 + +相较旧版 request 模型，当前头文件已经把更多阶段正式纳入同一份 request： + +- `shadowCaster` +- `depthOnly` +- `postProcess` +- `finalOutput` +- `objectId` +- `preScenePasses` +- `postScenePasses` +- `overlayPasses` + +## 头文件中的主要类型 + +- `CameraFrameStage` +- `CameraFrameStageInfo` +- `ScenePassRenderRequest` +- `DirectionalShadowRenderPlan` +- `ObjectIdRenderRequest` +- `FullscreenPassRenderRequest` +- `CameraRenderRequest` + +## 当前语义 + +- `ScenePassRenderRequest` 同时服务 `DepthOnlyRenderRequest` 与 `ShadowCasterRenderRequest`。 +- `DirectionalShadowRenderPlan` 保存 directional shadow 相机与 map 配置。 +- `FullscreenPassRenderRequest` 同时服务 `PostProcessRenderRequest` 与 `FinalOutputRenderRequest`。 +- `HasFrameStage(...)`、`GetPassSequence(...)`、`GetOutputSurface(...)` 让执行层可以按统一阶段名查询 request。 + +## 当前实现边界 + +- `IsValid()` 仍只检查 `scene`、`camera` 和 `context` 是否存在，具体子请求完整性由执行层进一步验证。 +- request 本身不生成任何 pass；Editor 或更上层系统仍要先把 sequence 和 surface 写进来。 + +## 相关文档 + +- [Planning](../Planning.md) +- [SceneRenderRequestPlanner](../SceneRenderRequestPlanner/SceneRenderRequestPlanner.md) +- [SceneRenderRequestUtils](../SceneRenderRequestUtils/SceneRenderRequestUtils.md) +- [SceneRenderer](../../Execution/SceneRenderer/SceneRenderer.md) +- [CameraRenderer](../../Execution/CameraRenderer/CameraRenderer.md) + diff --git a/docs/api/XCEngine/Rendering/Planning/FinalColorPassFactory/FinalColorPassFactory.md b/docs/api/XCEngine/Rendering/Planning/FinalColorPassFactory/FinalColorPassFactory.md new file mode 100644 index 00000000..32b79ff4 --- /dev/null +++ b/docs/api/XCEngine/Rendering/Planning/FinalColorPassFactory/FinalColorPassFactory.md @@ -0,0 +1,34 @@ +# FinalColorPassFactory + +**命名空间**: `XCEngine::Rendering` + +**类型**: `utility header` + +**头文件**: `XCEngine/Rendering/Planning/FinalColorPassFactory.h` + +**描述**: final-output pass 工厂头，负责把 `ResolvedFinalColorPolicy` 转换成最终的 fullscreen `RenderPassSequence`。 + +## 当前公开能力 + +```cpp +std::unique_ptr BuildFinalColorPassSequence( + const ResolvedFinalColorPolicy& finalColorPolicy); +``` + +## 当前实现行为 + +- 如果 `finalColorPolicy.RequiresProcessing()` 为假，直接返回 `nullptr`。 +- 否则创建一个新的 `RenderPassSequence`。 +- 当前只往序列里压入一个 [BuiltinFinalColorPass](../../Passes/BuiltinFinalColorPass/BuiltinFinalColorPass.md)。 + +## 当前调用链 + +- `SceneRenderer::AttachFullscreenStageRequests(...)` 调用它构建 `CameraRenderRequest::finalOutput.passes`。 +- `CameraRenderer` 随后在 `FinalOutput` 阶段按 fullscreen pass 链执行这条 sequence。 + +## 相关文档 + +- [Planning](../Planning.md) +- [FinalColorSettings](../FinalColorSettings/FinalColorSettings.md) +- [BuiltinFinalColorPass](../../Passes/BuiltinFinalColorPass/BuiltinFinalColorPass.md) +- [CameraRenderRequest](../CameraRenderRequest/CameraRenderRequest.md) diff --git a/docs/api/XCEngine/Rendering/Planning/FinalColorSettings/FinalColorSettings.md b/docs/api/XCEngine/Rendering/Planning/FinalColorSettings/FinalColorSettings.md new file mode 100644 index 00000000..fad2bafa --- /dev/null +++ b/docs/api/XCEngine/Rendering/Planning/FinalColorSettings/FinalColorSettings.md @@ -0,0 +1,46 @@ +# FinalColorSettings + +**命名空间**: `XCEngine::Rendering` + +**类型**: `enums + structs + helpers` + +**头文件**: `XCEngine/Rendering/Planning/FinalColorSettings.h` + +**描述**: 最终颜色处理策略头，定义 final-output 阶段的输出传递、曝光、色调映射、颜色缩放，以及默认值与覆盖值的合并规则。 + +## 头文件中的主要类型 + +- `FinalColorOutputTransferMode` +- `FinalColorExposureMode` +- `FinalColorToneMappingMode` +- `FinalColorSettings` +- `FinalColorOverrideSettings` +- `ResolvedFinalColorPolicy` + +## 当前语义 + +- `FinalColorSettings` 表示 pipeline 默认策略或某一层已解析出的最终策略。 +- `RequiresProcessing()` 用来判断是否真的需要挂 final-output fullscreen pass。 +- `FinalColorOverrideSettings` 采用逐字段 `overrideXxx` 开关，允许 camera / volume 只覆盖部分配置。 +- `HasOverrides()` 用来快速判断是否存在任何覆盖项。 +- `ResolvedFinalColorPolicy` 在设置值之外额外记录是否命中了 pipeline defaults、camera overrides 和 volume overrides。 + +## 当前 helper + +- `ApplyFinalColorOverrides(...)` + 只把被 `overrideXxx` 标记的字段覆写到目标 settings。 +- `ResolveFinalColorPolicy(...)` + 先拷贝 pipeline 默认值，再依次应用 camera overrides 和 volume overrides。 + +## 当前调用链 + +- `SceneRenderer::ResolveCameraFinalColorPolicies(...)` 为每个 request 生成 `finalColorPolicy`。 +- [FinalColorPassFactory](../FinalColorPassFactory/FinalColorPassFactory.md) 根据 `RequiresProcessing()` 决定是否构建 final-output sequence。 +- [BuiltinFinalColorPass](../../Passes/BuiltinFinalColorPass/BuiltinFinalColorPass.md) 真正消费解析后的策略。 + +## 相关文档 + +- [Planning](../Planning.md) +- [FinalColorPassFactory](../FinalColorPassFactory/FinalColorPassFactory.md) +- [BuiltinFinalColorPass](../../Passes/BuiltinFinalColorPass/BuiltinFinalColorPass.md) +- [CameraRenderRequest](../CameraRenderRequest/CameraRenderRequest.md) diff --git a/docs/api/XCEngine/Rendering/Planning/Planning.md b/docs/api/XCEngine/Rendering/Planning/Planning.md new file mode 100644 index 00000000..d13125cc --- /dev/null +++ b/docs/api/XCEngine/Rendering/Planning/Planning.md @@ -0,0 +1,39 @@ +# Planning + +**命名空间**: `XCEngine::Rendering` + +**类型**: `submodule` + +**头文件目录**: `engine/include/XCEngine/Rendering/Planning/` + +**描述**: Rendering 请求规划层，负责相机收集、排序、clear 推导、render-area 解析，以及 `CameraRenderRequest` 的组装与 fullscreen 阶段配置。 + +## 概览 + +`Planning` 把“这次要渲染什么”从执行链里拆了出来。 + +当前它统一收口： + +- [CameraRenderRequest](CameraRenderRequest/CameraRenderRequest.md) +- [SceneRenderRequestPlanner](SceneRenderRequestPlanner/SceneRenderRequestPlanner.md) +- [SceneRenderRequestUtils](SceneRenderRequestUtils/SceneRenderRequestUtils.md) +- [CameraPostProcessDesc](CameraPostProcessDesc/CameraPostProcessDesc.md) +- [CameraPostProcessPassFactory](CameraPostProcessPassFactory/CameraPostProcessPassFactory.md) +- [FinalColorSettings](FinalColorSettings/FinalColorSettings.md) +- [FinalColorPassFactory](FinalColorPassFactory/FinalColorPassFactory.md) + +## 当前职责 + +- 从场景和 override camera 构建 request 数组 +- 统一 base / overlay 相机排序 +- 统一 `CameraClearMode::Auto` 推导 +- 解析 normalized viewport 到最终 render area +- 把声明式 post-process / final-color 策略转换成 fullscreen 阶段配置 +- 给执行层提供显式 request 契约 + +## 相关文档 + +- [Rendering](../Rendering.md) +- [Execution](../Execution/Execution.md) +- [FrameData](../FrameData/FrameData.md) +- [Camera Request Planning And Clear Rules](../../../_guides/Rendering/Camera-Request-Planning-And-Clear-Rules.md) diff --git a/docs/api/XCEngine/Rendering/Planning/SceneRenderRequestPlanner/SceneRenderRequestPlanner.md b/docs/api/XCEngine/Rendering/Planning/SceneRenderRequestPlanner/SceneRenderRequestPlanner.md new file mode 100644 index 00000000..4dc90e95 --- /dev/null +++ b/docs/api/XCEngine/Rendering/Planning/SceneRenderRequestPlanner/SceneRenderRequestPlanner.md @@ -0,0 +1,37 @@ +# SceneRenderRequestPlanner + +**命名空间**: `XCEngine::Rendering` + +**类型**: `class` + +**头文件**: `XCEngine/Rendering/Planning/SceneRenderRequestPlanner.h` + +**描述**: 从场景和可选 override camera 生成最终要提交给执行层的 `CameraRenderRequest` 数组。 + +## 概览 + +`SceneRenderRequestPlanner` 处在 request planning 主链的中心位置。 + +它负责： + +- 收集本次要参与渲染的相机 +- 复用 [SceneRenderRequestUtils](../SceneRenderRequestUtils/SceneRenderRequestUtils.md) 的规则组装 request +- 丢弃 render area 无效的 request + +## 当前规划规则 + +- `CollectCameras(...)` 优先接受可用的 `overrideCamera`，否则收集场景相机并做稳定排序。 +- `BuildRequests(...)` 逐个调用 `BuildCameraRenderRequest(...)`，并维护 base/request 计数以推导 `Auto` clear 行为。 + +## 当前实现边界 + +- 它只生成 request，不执行 request。 +- 它不填充 `objectId`、fullscreen 阶段或 editor 注入的 pass sequence。 + +## 相关文档 + +- [Planning](../Planning.md) +- [SceneRenderRequestUtils](../SceneRenderRequestUtils/SceneRenderRequestUtils.md) +- [CameraRenderRequest](../CameraRenderRequest/CameraRenderRequest.md) +- [SceneRenderer](../../Execution/SceneRenderer/SceneRenderer.md) + diff --git a/docs/api/XCEngine/Rendering/Planning/SceneRenderRequestUtils/SceneRenderRequestUtils.md b/docs/api/XCEngine/Rendering/Planning/SceneRenderRequestUtils/SceneRenderRequestUtils.md new file mode 100644 index 00000000..3fa83092 --- /dev/null +++ b/docs/api/XCEngine/Rendering/Planning/SceneRenderRequestUtils/SceneRenderRequestUtils.md @@ -0,0 +1,37 @@ +# SceneRenderRequestUtils + +**命名空间**: `XCEngine::Rendering::SceneRenderRequestUtils` + +**类型**: `utility header` + +**头文件**: `XCEngine/Rendering/Planning/SceneRenderRequestUtils.h` + +**描述**: request planning 规则库，统一相机可用性判断、稳定排序、clear flag 推导、render area 解析，以及基础 `CameraRenderRequest` 组装。 + +## 概览 + +`SceneRenderRequestUtils` 是 planning 层的规则收口点。 + +它当前提供的核心 helper 包括： + +- `IsUsableCamera(...)` +- `SortSceneCamerasForRendering(...)` +- `SortCameraRenderRequests(...)` +- `ResolveClearFlags(...)` +- `ResolveCameraRenderArea(...)` +- `BuildCameraRenderRequest(...)` + +## 当前规则重点 + +- 场景相机按 `stackType -> depth` 稳定排序。 +- request 按 `cameraStackOrder -> cameraDepth` 稳定排序。 +- `CameraClearMode::Auto` 不是固定值，而要结合 base/overlay 计数推导。 +- normalized viewport 会叠加到父 `RenderSurface::renderArea` 上，而不是总以整张 surface 为基准。 + +## 相关文档 + +- [Planning](../Planning.md) +- [SceneRenderRequestPlanner](../SceneRenderRequestPlanner/SceneRenderRequestPlanner.md) +- [CameraRenderRequest](../CameraRenderRequest/CameraRenderRequest.md) +- [Camera Request Planning And Clear Rules](../../../../_guides/Rendering/Camera-Request-Planning-And-Clear-Rules.md) + diff --git a/docs/api/XCEngine/Rendering/RenderCameraData/RenderCameraData.md b/docs/api/XCEngine/Rendering/RenderCameraData/RenderCameraData.md index af025b37..33cbe20c 100644 --- a/docs/api/XCEngine/Rendering/RenderCameraData/RenderCameraData.md +++ b/docs/api/XCEngine/Rendering/RenderCameraData/RenderCameraData.md @@ -1,10 +1,10 @@ -# RenderCameraData +# RenderCameraData **命名空间**: `XCEngine::Rendering` **类型**: `struct` -**头文件**: `XCEngine/Rendering/RenderCameraData.h` +**头文件**: `XCEngine/Rendering/FrameData/RenderCameraData.h` **描述**: 保存渲染阶段实际使用的相机矩阵、清屏参数和视口尺寸。 @@ -59,3 +59,4 @@ - [RenderSceneExtractor](../RenderSceneExtractor/RenderSceneExtractor.md) - [CameraRenderer](../CameraRenderer/CameraRenderer.md) - [CameraRenderRequest](../CameraRenderRequest/CameraRenderRequest.md) + diff --git a/docs/api/XCEngine/Rendering/RenderMaterialUtility/ApplyMaterialRenderState.md b/docs/api/XCEngine/Rendering/RenderMaterialUtility/ApplyMaterialRenderState.md index 0cf0e3ad..0ba5e639 100644 --- a/docs/api/XCEngine/Rendering/RenderMaterialUtility/ApplyMaterialRenderState.md +++ b/docs/api/XCEngine/Rendering/RenderMaterialUtility/ApplyMaterialRenderState.md @@ -4,7 +4,7 @@ **类型**: `function` -**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h` +**头文件**: `XCEngine/Rendering/Materials/RenderMaterialStateUtils.h` ## 签名 diff --git a/docs/api/XCEngine/Rendering/RenderMaterialUtility/BuildBlendState.md b/docs/api/XCEngine/Rendering/RenderMaterialUtility/BuildBlendState.md index ab80031f..2983c2aa 100644 --- a/docs/api/XCEngine/Rendering/RenderMaterialUtility/BuildBlendState.md +++ b/docs/api/XCEngine/Rendering/RenderMaterialUtility/BuildBlendState.md @@ -4,7 +4,7 @@ **类型**: `function` -**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h` +**头文件**: `XCEngine/Rendering/Materials/RenderMaterialStateUtils.h` ## 签名 diff --git a/docs/api/XCEngine/Rendering/RenderMaterialUtility/BuildBuiltinForwardMaterialData.md b/docs/api/XCEngine/Rendering/RenderMaterialUtility/BuildBuiltinForwardMaterialData.md index 6b5e7aac..ad58325c 100644 --- a/docs/api/XCEngine/Rendering/RenderMaterialUtility/BuildBuiltinForwardMaterialData.md +++ b/docs/api/XCEngine/Rendering/RenderMaterialUtility/BuildBuiltinForwardMaterialData.md @@ -4,7 +4,7 @@ **类型**: `function` -**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h` +**头文件**: `XCEngine/Rendering/Materials/RenderMaterialResolve.h` ## 签名 diff --git a/docs/api/XCEngine/Rendering/RenderMaterialUtility/BuildDepthStencilState.md b/docs/api/XCEngine/Rendering/RenderMaterialUtility/BuildDepthStencilState.md index fdbf231a..51f9e9d3 100644 --- a/docs/api/XCEngine/Rendering/RenderMaterialUtility/BuildDepthStencilState.md +++ b/docs/api/XCEngine/Rendering/RenderMaterialUtility/BuildDepthStencilState.md @@ -4,7 +4,7 @@ **类型**: `function` -**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h` +**头文件**: `XCEngine/Rendering/Materials/RenderMaterialStateUtils.h` ## 签名 diff --git a/docs/api/XCEngine/Rendering/RenderMaterialUtility/BuildLegacyBuiltinForwardPassResourceBindings.md b/docs/api/XCEngine/Rendering/RenderMaterialUtility/BuildLegacyBuiltinForwardPassResourceBindings.md index 6c7b9838..6a6726e4 100644 --- a/docs/api/XCEngine/Rendering/RenderMaterialUtility/BuildLegacyBuiltinForwardPassResourceBindings.md +++ b/docs/api/XCEngine/Rendering/RenderMaterialUtility/BuildLegacyBuiltinForwardPassResourceBindings.md @@ -2,45 +2,34 @@ **命名空间**: `XCEngine::Rendering` -**类型**: `function` +**类型**: `removed helper` -**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h` +**描述**: 历史上的 builtin forward fallback 绑定列表 helper。当前 public API 已移除该函数，builtin forward 路径改为要求 resolved shader pass 提供显式 `resources` 声明。 -## 签名 +## 当前状态 -```cpp -Containers::Array BuildLegacyBuiltinForwardPassResourceBindings(); -``` +- 当前 public headers 中已经不存在这个函数声明。 +- [BuiltinForwardPipeline](../Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md) 现在在 `resources.Empty()` 时会直接报错，而不是自动生成 fallback binding plan。 +- 对应的 builtin 资源契约应通过 [BuiltinPassMetadataUtils](../Builtin/BuiltinPassMetadataUtils/BuiltinPassMetadataUtils.md) 与 [BuiltinPassLayoutUtils](../Builtin/BuiltinPassLayoutUtils/BuiltinPassLayoutUtils.md) 解析显式声明。 -## 作用 +## 迁移建议 -构造 builtin forward 路径在没有显式 `resources` 声明时使用的 legacy fallback 绑定列表。 +如果你在写新的 builtin forward shader pass，应显式声明当前消费的 `resources`，至少覆盖： -## 当前实现行为 +- `PerObject` +- `Material` +- `Lighting` -当前固定返回四条绑定： +按需再补： -| `set` | `binding` | `semantic` | `type` | -|------|------|------|------| -| `1` | `0` | `PerObject` | `ConstantBuffer` | -| `2` | `0` | `Material` | `ConstantBuffer` | -| `3` | `0` | `BaseColorTexture` | `Texture2D` | -| `4` | `0` | `LinearClampSampler` | `Sampler` | - -## 当前使用位置 - -- [BuiltinForwardPipeline](../Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md) 在 shader pass 没有显式资源声明时，会先调用这条 helper。 -- 随后再交给 [TryBuildBuiltinPassResourceBindingPlan](TryBuildBuiltinPassResourceBindingPlan.md) 解析成统一 plan。 - -## 测试覆盖 - -`tests/Rendering/unit/test_builtin_forward_pipeline.cpp` 当前验证了： - -- 返回值包含四条绑定 -- 经 binding-plan 解析后，对应语义会落到 `set 1/2/3/4` +- `ShadowReceiver` +- `BaseColorTexture` +- `LinearClampSampler` +- `ShadowMapTexture` +- `ShadowMapSampler` ## 相关文档 -- [TryBuildBuiltinPassResourceBindingPlan](TryBuildBuiltinPassResourceBindingPlan.md) - [BuiltinForwardPipeline](../Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md) +- [BuiltinPassLayoutUtils](../Builtin/BuiltinPassLayoutUtils/BuiltinPassLayoutUtils.md) - [RenderMaterialUtility](RenderMaterialUtility.md) diff --git a/docs/api/XCEngine/Rendering/RenderMaterialUtility/BuildLegacyBuiltinObjectIdPassResourceBindings.md b/docs/api/XCEngine/Rendering/RenderMaterialUtility/BuildLegacyBuiltinObjectIdPassResourceBindings.md index 7aee4d74..75e5e4ca 100644 --- a/docs/api/XCEngine/Rendering/RenderMaterialUtility/BuildLegacyBuiltinObjectIdPassResourceBindings.md +++ b/docs/api/XCEngine/Rendering/RenderMaterialUtility/BuildLegacyBuiltinObjectIdPassResourceBindings.md @@ -2,43 +2,30 @@ **命名空间**: `XCEngine::Rendering` -**类型**: `function` +**类型**: `removed helper` -**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h` +**描述**: 历史上的 builtin object-id fallback 绑定列表 helper。当前 public API 已移除该函数，builtin object-id 路径改为要求 resolved shader pass 提供显式 `resources` 声明。 -## 签名 +## 当前状态 -```cpp -Containers::Array BuildLegacyBuiltinObjectIdPassResourceBindings(); -``` +- 当前 public headers 中已经不存在这个函数声明。 +- [BuiltinObjectIdPass](../Passes/BuiltinObjectIdPass/BuiltinObjectIdPass.md) 现在在 `resources.Empty()` 时会直接报错，而不是自动生成 fallback binding plan。 +- 当前 builtin object-id shader 契约要求显式提供唯一的 `PerObject` constant-buffer 绑定。 -## 作用 +## 迁移建议 -构造 builtin object-id 路径在没有显式 `resources` 声明时使用的 legacy fallback 绑定列表。 +如果你在写新的 builtin object-id shader pass，应显式声明： -## 当前实现行为 +- `PerObject` -当前固定只返回一条绑定： +并确保： -| `set` | `binding` | `semantic` | `type` | -|------|------|------|------| -| `0` | `0` | `PerObject` | `ConstantBuffer` | - -## 当前使用位置 - -- [BuiltinObjectIdPass](../Passes/BuiltinObjectIdPass/BuiltinObjectIdPass.md) 在 shader pass 没有显式资源声明时，会先回退到这份绑定列表。 -- 后续同样交给 [TryBuildBuiltinPassResourceBindingPlan](TryBuildBuiltinPassResourceBindingPlan.md) 统一解析。 - -## 测试覆盖 - -`tests/Rendering/unit/test_builtin_forward_pipeline.cpp` 当前验证了： - -- 返回值只有一条绑定 -- 解析后的 plan 只包含 `PerObject` -- `firstDescriptorSet == 0` 且 `descriptorSetCount == 1` +- 没有重复的 builtin 语义 +- 没有重复的 `set/binding` +- 不混入 object-id 路径当前不消费的纹理或 sampler 语义 ## 相关文档 -- [TryBuildBuiltinPassResourceBindingPlan](TryBuildBuiltinPassResourceBindingPlan.md) - [BuiltinObjectIdPass](../Passes/BuiltinObjectIdPass/BuiltinObjectIdPass.md) +- [BuiltinPassLayoutUtils](../Builtin/BuiltinPassLayoutUtils/BuiltinPassLayoutUtils.md) - [RenderMaterialUtility](RenderMaterialUtility.md) diff --git a/docs/api/XCEngine/Rendering/RenderMaterialUtility/BuildRasterizerState.md b/docs/api/XCEngine/Rendering/RenderMaterialUtility/BuildRasterizerState.md index 514c0203..bf4a3b32 100644 --- a/docs/api/XCEngine/Rendering/RenderMaterialUtility/BuildRasterizerState.md +++ b/docs/api/XCEngine/Rendering/RenderMaterialUtility/BuildRasterizerState.md @@ -4,7 +4,7 @@ **类型**: `function` -**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h` +**头文件**: `XCEngine/Rendering/Materials/RenderMaterialStateUtils.h` ## 签名 diff --git a/docs/api/XCEngine/Rendering/RenderMaterialUtility/BuiltinForwardMaterialData.md b/docs/api/XCEngine/Rendering/RenderMaterialUtility/BuiltinForwardMaterialData.md index cb03aee2..01ae0a97 100644 --- a/docs/api/XCEngine/Rendering/RenderMaterialUtility/BuiltinForwardMaterialData.md +++ b/docs/api/XCEngine/Rendering/RenderMaterialUtility/BuiltinForwardMaterialData.md @@ -4,7 +4,7 @@ **类型**: `struct` -**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h` +**头文件**: `XCEngine/Rendering/Materials/RenderMaterialResolve.h` **描述**: `BuiltinForwardPipeline` 在拿不到 schema-driven 材质常量 payload 时使用的兼容逐材质常量结构。 diff --git a/docs/api/XCEngine/Rendering/RenderMaterialUtility/BuiltinMaterialPass.md b/docs/api/XCEngine/Rendering/RenderMaterialUtility/BuiltinMaterialPass.md index f3ab48db..bea45652 100644 --- a/docs/api/XCEngine/Rendering/RenderMaterialUtility/BuiltinMaterialPass.md +++ b/docs/api/XCEngine/Rendering/RenderMaterialUtility/BuiltinMaterialPass.md @@ -4,7 +4,7 @@ **类型**: `enum class` -**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h` +**头文件**: `XCEngine/Rendering/Builtin/BuiltinPassTypes.h` ## 枚举值 diff --git a/docs/api/XCEngine/Rendering/RenderMaterialUtility/BuiltinPassResourceBindingDesc.md b/docs/api/XCEngine/Rendering/RenderMaterialUtility/BuiltinPassResourceBindingDesc.md index bf19616c..2be66c6d 100644 --- a/docs/api/XCEngine/Rendering/RenderMaterialUtility/BuiltinPassResourceBindingDesc.md +++ b/docs/api/XCEngine/Rendering/RenderMaterialUtility/BuiltinPassResourceBindingDesc.md @@ -4,7 +4,7 @@ **类型**: `struct` -**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h` +**头文件**: `XCEngine/Rendering/Builtin/BuiltinPassTypes.h` ## 字段 diff --git a/docs/api/XCEngine/Rendering/RenderMaterialUtility/BuiltinPassResourceBindingPlan.md b/docs/api/XCEngine/Rendering/RenderMaterialUtility/BuiltinPassResourceBindingPlan.md index a667a3e2..1d26512a 100644 --- a/docs/api/XCEngine/Rendering/RenderMaterialUtility/BuiltinPassResourceBindingPlan.md +++ b/docs/api/XCEngine/Rendering/RenderMaterialUtility/BuiltinPassResourceBindingPlan.md @@ -4,7 +4,7 @@ **类型**: `struct` -**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h` +**头文件**: `XCEngine/Rendering/Builtin/BuiltinPassTypes.h` ## 字段 diff --git a/docs/api/XCEngine/Rendering/RenderMaterialUtility/BuiltinPassResourceSemantic.md b/docs/api/XCEngine/Rendering/RenderMaterialUtility/BuiltinPassResourceSemantic.md index acce8733..f83c792f 100644 --- a/docs/api/XCEngine/Rendering/RenderMaterialUtility/BuiltinPassResourceSemantic.md +++ b/docs/api/XCEngine/Rendering/RenderMaterialUtility/BuiltinPassResourceSemantic.md @@ -4,7 +4,7 @@ **类型**: `enum class` -**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h` +**头文件**: `XCEngine/Rendering/Builtin/BuiltinPassTypes.h` ## 枚举值 diff --git a/docs/api/XCEngine/Rendering/RenderMaterialUtility/FindShaderPropertyBySemantic.md b/docs/api/XCEngine/Rendering/RenderMaterialUtility/FindShaderPropertyBySemantic.md index 119e0ff6..1f74297d 100644 --- a/docs/api/XCEngine/Rendering/RenderMaterialUtility/FindShaderPropertyBySemantic.md +++ b/docs/api/XCEngine/Rendering/RenderMaterialUtility/FindShaderPropertyBySemantic.md @@ -4,7 +4,7 @@ **类型**: `function` -**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h` +**头文件**: `XCEngine/Rendering/Materials/RenderMaterialResolve.h` ## 签名 diff --git a/docs/api/XCEngine/Rendering/RenderMaterialUtility/IsBuiltinPassResourceTypeCompatible.md b/docs/api/XCEngine/Rendering/RenderMaterialUtility/IsBuiltinPassResourceTypeCompatible.md index 8e5b24ed..e474a70b 100644 --- a/docs/api/XCEngine/Rendering/RenderMaterialUtility/IsBuiltinPassResourceTypeCompatible.md +++ b/docs/api/XCEngine/Rendering/RenderMaterialUtility/IsBuiltinPassResourceTypeCompatible.md @@ -4,7 +4,7 @@ **类型**: `function` -**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h` +**头文件**: `XCEngine/Rendering/Builtin/BuiltinPassMetadataUtils.h` ## 签名 diff --git a/docs/api/XCEngine/Rendering/RenderMaterialUtility/IsDepthOnlyPassName.md b/docs/api/XCEngine/Rendering/RenderMaterialUtility/IsDepthOnlyPassName.md index c3aa6ebb..b6f8a812 100644 --- a/docs/api/XCEngine/Rendering/RenderMaterialUtility/IsDepthOnlyPassName.md +++ b/docs/api/XCEngine/Rendering/RenderMaterialUtility/IsDepthOnlyPassName.md @@ -4,7 +4,7 @@ **类型**: `function` -**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h` +**头文件**: `XCEngine/Rendering/Builtin/BuiltinPassMetadataUtils.h` ## 签名 diff --git a/docs/api/XCEngine/Rendering/RenderMaterialUtility/IsForwardPassName.md b/docs/api/XCEngine/Rendering/RenderMaterialUtility/IsForwardPassName.md index 780ffccf..02e11a77 100644 --- a/docs/api/XCEngine/Rendering/RenderMaterialUtility/IsForwardPassName.md +++ b/docs/api/XCEngine/Rendering/RenderMaterialUtility/IsForwardPassName.md @@ -4,7 +4,7 @@ **类型**: `function` -**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h` +**头文件**: `XCEngine/Rendering/Builtin/BuiltinPassMetadataUtils.h` ## 签名 diff --git a/docs/api/XCEngine/Rendering/RenderMaterialUtility/IsObjectIdPassName.md b/docs/api/XCEngine/Rendering/RenderMaterialUtility/IsObjectIdPassName.md index f22fae9a..f74dcebb 100644 --- a/docs/api/XCEngine/Rendering/RenderMaterialUtility/IsObjectIdPassName.md +++ b/docs/api/XCEngine/Rendering/RenderMaterialUtility/IsObjectIdPassName.md @@ -4,7 +4,7 @@ **类型**: `function` -**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h` +**头文件**: `XCEngine/Rendering/Builtin/BuiltinPassMetadataUtils.h` ## 签名 diff --git a/docs/api/XCEngine/Rendering/RenderMaterialUtility/IsShadowCasterPassName.md b/docs/api/XCEngine/Rendering/RenderMaterialUtility/IsShadowCasterPassName.md index 315079d9..44267a51 100644 --- a/docs/api/XCEngine/Rendering/RenderMaterialUtility/IsShadowCasterPassName.md +++ b/docs/api/XCEngine/Rendering/RenderMaterialUtility/IsShadowCasterPassName.md @@ -4,7 +4,7 @@ **类型**: `function` -**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h` +**头文件**: `XCEngine/Rendering/Builtin/BuiltinPassMetadataUtils.h` ## 签名 diff --git a/docs/api/XCEngine/Rendering/RenderMaterialUtility/IsTransparentRenderQueue.md b/docs/api/XCEngine/Rendering/RenderMaterialUtility/IsTransparentRenderQueue.md index 0de84b84..b9a888c6 100644 --- a/docs/api/XCEngine/Rendering/RenderMaterialUtility/IsTransparentRenderQueue.md +++ b/docs/api/XCEngine/Rendering/RenderMaterialUtility/IsTransparentRenderQueue.md @@ -4,7 +4,7 @@ **类型**: `function` -**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h` +**头文件**: `XCEngine/Rendering/Materials/RenderMaterialResolve.h` ## 签名 diff --git a/docs/api/XCEngine/Rendering/RenderMaterialUtility/IsUnlitPassName.md b/docs/api/XCEngine/Rendering/RenderMaterialUtility/IsUnlitPassName.md index d66713a4..0fd8d61c 100644 --- a/docs/api/XCEngine/Rendering/RenderMaterialUtility/IsUnlitPassName.md +++ b/docs/api/XCEngine/Rendering/RenderMaterialUtility/IsUnlitPassName.md @@ -4,7 +4,7 @@ **类型**: `function` -**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h` +**头文件**: `XCEngine/Rendering/Builtin/BuiltinPassMetadataUtils.h` ## 签名 diff --git a/docs/api/XCEngine/Rendering/RenderMaterialUtility/MatchesBuiltinPass.md b/docs/api/XCEngine/Rendering/RenderMaterialUtility/MatchesBuiltinPass.md index 1983dbf4..9c9e772e 100644 --- a/docs/api/XCEngine/Rendering/RenderMaterialUtility/MatchesBuiltinPass.md +++ b/docs/api/XCEngine/Rendering/RenderMaterialUtility/MatchesBuiltinPass.md @@ -4,7 +4,7 @@ **类型**: `function` -**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h` +**头文件**: `XCEngine/Rendering/Materials/RenderMaterialResolve.h` ## 签名 diff --git a/docs/api/XCEngine/Rendering/RenderMaterialUtility/MatchesBuiltinPassName.md b/docs/api/XCEngine/Rendering/RenderMaterialUtility/MatchesBuiltinPassName.md index 3bb0218c..0f5cfe87 100644 --- a/docs/api/XCEngine/Rendering/RenderMaterialUtility/MatchesBuiltinPassName.md +++ b/docs/api/XCEngine/Rendering/RenderMaterialUtility/MatchesBuiltinPassName.md @@ -4,7 +4,7 @@ **类型**: `function` -**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h` +**头文件**: `XCEngine/Rendering/Builtin/BuiltinPassMetadataUtils.h` ## 签名 diff --git a/docs/api/XCEngine/Rendering/RenderMaterialUtility/MaterialConstantLayoutView.md b/docs/api/XCEngine/Rendering/RenderMaterialUtility/MaterialConstantLayoutView.md index a6f228f7..1a1fc6de 100644 --- a/docs/api/XCEngine/Rendering/RenderMaterialUtility/MaterialConstantLayoutView.md +++ b/docs/api/XCEngine/Rendering/RenderMaterialUtility/MaterialConstantLayoutView.md @@ -4,7 +4,7 @@ **类型**: `struct` -**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h` +**头文件**: `XCEngine/Rendering/Materials/RenderMaterialResolve.h` ## 字段 diff --git a/docs/api/XCEngine/Rendering/RenderMaterialUtility/MaterialConstantPayloadView.md b/docs/api/XCEngine/Rendering/RenderMaterialUtility/MaterialConstantPayloadView.md index b852bfc4..5c351499 100644 --- a/docs/api/XCEngine/Rendering/RenderMaterialUtility/MaterialConstantPayloadView.md +++ b/docs/api/XCEngine/Rendering/RenderMaterialUtility/MaterialConstantPayloadView.md @@ -4,7 +4,7 @@ **类型**: `struct` -**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h` +**头文件**: `XCEngine/Rendering/Materials/RenderMaterialResolve.h` **描述**: 指向 schema-driven 材质常量缓冲字节及其布局的非 owning 视图，用于把 `Material::GetConstantBufferData()` 直接写入渲染 descriptor set。 diff --git a/docs/api/XCEngine/Rendering/RenderMaterialUtility/MaterialRenderStateHash.md b/docs/api/XCEngine/Rendering/RenderMaterialUtility/MaterialRenderStateHash.md index f1031eb4..c4756927 100644 --- a/docs/api/XCEngine/Rendering/RenderMaterialUtility/MaterialRenderStateHash.md +++ b/docs/api/XCEngine/Rendering/RenderMaterialUtility/MaterialRenderStateHash.md @@ -4,7 +4,7 @@ **类型**: `functor struct` -**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h` +**头文件**: `XCEngine/Rendering/Materials/RenderMaterialStateUtils.h` ## 作用 diff --git a/docs/api/XCEngine/Rendering/RenderMaterialUtility/NormalizeBuiltinPassMetadataValue.md b/docs/api/XCEngine/Rendering/RenderMaterialUtility/NormalizeBuiltinPassMetadataValue.md index 914bbd76..d2b8f9ab 100644 --- a/docs/api/XCEngine/Rendering/RenderMaterialUtility/NormalizeBuiltinPassMetadataValue.md +++ b/docs/api/XCEngine/Rendering/RenderMaterialUtility/NormalizeBuiltinPassMetadataValue.md @@ -4,7 +4,7 @@ **类型**: `function` -**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h` +**头文件**: `XCEngine/Rendering/Builtin/BuiltinPassMetadataUtils.h` ## 签名 diff --git a/docs/api/XCEngine/Rendering/RenderMaterialUtility/PassResourceBindingLocation.md b/docs/api/XCEngine/Rendering/RenderMaterialUtility/PassResourceBindingLocation.md index 6eb2e9b8..5fb4b50c 100644 --- a/docs/api/XCEngine/Rendering/RenderMaterialUtility/PassResourceBindingLocation.md +++ b/docs/api/XCEngine/Rendering/RenderMaterialUtility/PassResourceBindingLocation.md @@ -4,7 +4,7 @@ **类型**: `struct` -**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h` +**头文件**: `XCEngine/Rendering/Builtin/BuiltinPassTypes.h` ## 字段 diff --git a/docs/api/XCEngine/Rendering/RenderMaterialUtility/RenderMaterialUtility.md b/docs/api/XCEngine/Rendering/RenderMaterialUtility/RenderMaterialUtility.md index 7830bdb7..2c66fa7b 100644 --- a/docs/api/XCEngine/Rendering/RenderMaterialUtility/RenderMaterialUtility.md +++ b/docs/api/XCEngine/Rendering/RenderMaterialUtility/RenderMaterialUtility.md @@ -2,186 +2,55 @@ **命名空间**: `XCEngine::Rendering` -**类型**: `utility header` +**类型**: `migration index` -**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h` - -**描述**: 把 `Material` 的 pass 元数据、逐材质常量契约、builtin forward 兼容语义、render queue 和 render state 解释成渲染提取与图形管线可直接使用的规则。 +**描述**: `RenderMaterialUtility.h` 的历史聚合索引页。当前公共 API 已拆分到 `Builtin` 与 `Materials` 两组头文件中，这里负责说明迁移关系。 ## 概览 -`RenderMaterialUtility.h` 不是运行时对象，而是一组内联规则函数。它当前承担五类工作： +旧的 `RenderMaterialUtility.h` 曾经把 builtin pass 契约、材质解析和 render-state 映射都堆在同一份头文件里。 -1. 解析“这次绘制真正要用哪份材质”。 -2. 判断该材质是否匹配某个 builtin pass。 -3. 暴露 shader schema 驱动的逐材质常量 payload 视图。 -4. 解析 builtin forward 兼容路径要消费的 base-color 因子与贴图。 -5. 把材质里的 `MaterialRenderState` 翻译成 `RHI::GraphicsPipelineDesc` 需要的状态结构。 +当前实现已经拆分为两层： -它位于 [RenderSceneExtractor](../RenderSceneExtractor/RenderSceneExtractor.md)、[BuiltinForwardPipeline](../Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md) 和 object-id 相关 pass 之间，是当前材质语义进入渲染链路的关键翻译层。 +- `Builtin/` + 负责 builtin pass 枚举、metadata 匹配和资源布局契约。 +- `Materials/` + 负责材质解析、skybox / base-color / alpha-cutoff helper，以及 render-state 到 RHI 的映射。 -## `BuiltinMaterialPass` +## 当前迁移关系 -当前公开的 builtin pass 枚举包括： - -| 枚举值 | 说明 | +| 历史职责 | 当前位置 | |------|------| -| `ForwardLit` | 默认前向绘制路径。 | -| `Unlit` | 非受光绘制路径。 | -| `DepthOnly` | 深度预写 / depth-only 通道。 | -| `ShadowCaster` | 阴影投射通道。 | -| `ObjectId` | object-id 输出通道。 | -| `Forward` | `ForwardLit` 的别名。 | +| builtin pass 枚举与资源语义 | [BuiltinPassTypes](../Builtin/BuiltinPassTypes/BuiltinPassTypes.md) | +| pass 名称 / `LightMode` 匹配与资源 semantic 解析 | [BuiltinPassMetadataUtils](../Builtin/BuiltinPassMetadataUtils/BuiltinPassMetadataUtils.md) | +| binding plan 与 set-layout 构建 | [BuiltinPassLayoutUtils](../Builtin/BuiltinPassLayoutUtils/BuiltinPassLayoutUtils.md) | +| 材质、skybox、base-color、alpha-cutoff、render queue 解析 | [RenderMaterialResolve](../Materials/RenderMaterialResolve/RenderMaterialResolve.md) | +| `MaterialRenderState` 到 RHI 的映射 | [RenderMaterialStateUtils](../Materials/RenderMaterialStateUtils/RenderMaterialStateUtils.md) | -## builtin pass 元数据与资源绑定契约 +## 已移除的旧 helper -当前这份头文件除了材质解析 helper，还公开了一组“shader pass 如何映射到 builtin path、资源声明如何落成 descriptor-set 计划”的契约类型： +下列 helper 不再属于当前 public API： -- [PassResourceBindingLocation](PassResourceBindingLocation.md) - 统一表示一个 `set/binding` 槽位。 -- [BuiltinPassResourceSemantic](BuiltinPassResourceSemantic.md) - 把 shader 资源语义收口成 builtin forward / object-id 当前识别的白名单枚举。 -- [BuiltinPassResourceBindingDesc](BuiltinPassResourceBindingDesc.md) - 记录单个 builtin 语义、资源类型与绑定位置。 -- [BuiltinPassResourceBindingPlan](BuiltinPassResourceBindingPlan.md) - 是 `BuiltinForwardPipeline` / `BuiltinObjectIdPass` 当前真正消费的 binding-plan 结果。 - -与这些类型配套的 helper 包括： - -- [IsForwardPassName](IsForwardPassName.md) -- [IsUnlitPassName](IsUnlitPassName.md) -- [IsDepthOnlyPassName](IsDepthOnlyPassName.md) -- [IsShadowCasterPassName](IsShadowCasterPassName.md) -- [IsObjectIdPassName](IsObjectIdPassName.md) -- [MatchesBuiltinPassName](MatchesBuiltinPassName.md) -- [ShaderPassHasExplicitBuiltinMetadata](ShaderPassHasExplicitBuiltinMetadata.md) -- [ShaderPassMatchesBuiltinPass](ShaderPassMatchesBuiltinPass.md) -- [ResolveBuiltinPassResourceSemantic](ResolveBuiltinPassResourceSemantic.md) - [BuildLegacyBuiltinForwardPassResourceBindings](BuildLegacyBuiltinForwardPassResourceBindings.md) - [BuildLegacyBuiltinObjectIdPassResourceBindings](BuildLegacyBuiltinObjectIdPassResourceBindings.md) -- [IsBuiltinPassResourceTypeCompatible](IsBuiltinPassResourceTypeCompatible.md) + +当前 builtin forward 与 builtin object-id 路径都要求 resolved shader pass 提供显式 `resources` 声明，不再从这些历史 helper 自动生成 fallback 列表。 + +## 仍可参考的成员页 + +旧目录下的很多成员页已经把 `头文件` 行改到当前实际头文件，可继续作为符号级文档使用，例如： + +- [BuiltinMaterialPass](BuiltinMaterialPass.md) +- [BuiltinPassResourceBindingPlan](BuiltinPassResourceBindingPlan.md) - [TryBuildBuiltinPassResourceBindingPlan](TryBuildBuiltinPassResourceBindingPlan.md) - -这组页面对应的是当前 builtin pipeline 的真实入口：shader pass 可以显式声明 `resources`；如果没声明，再退到 legacy fallback 绑定；最终都要先落成统一的 binding plan，后续 pass-layout / descriptor-set / pipeline-state 才能继续创建。 - -## 当前 pass 匹配策略 - -[MatchesBuiltinPass](MatchesBuiltinPass.md) 的判断顺序是： - -1. 先看材质自身的 `shaderPass` 和 `LightMode` tag。 -2. 如果材质没写显式 pass 元数据，再看材质引用 shader 里的 pass 名称和 `LightMode` tag。 -3. 如果材质和 shader 都没写显式 builtin metadata，则把它隐式视为 `ForwardLit`。 - -因此这里实际把 [MaterialLoader](../../Resources/Material/MaterialLoader/MaterialLoader.md) 解析出的： - -- `shaderPass` -- `tags.LightMode` -- `renderQueue` -- `renderState` - -全部接进了渲染路径。 - -## 逐材质常量契约 - -同一个头文件里当前公开了两类逐材质数据和一份布局视图： - -| 类型 | 说明 | -|------|------| -| [BuiltinForwardMaterialData](BuiltinForwardMaterialData.md) | builtin forward 的兼容 fallback 常量结构，当前只收口 `baseColorFactor`。 | -| [MaterialConstantLayoutView](MaterialConstantLayoutView.md) | 指向 `Material::GetConstantLayout()` 的非 owning 布局视图。 | -| [MaterialConstantPayloadView](MaterialConstantPayloadView.md) | 指向 `Material::GetConstantBufferData()` 及其布局的非 owning 视图。 | - -对应 helper 的当前职责是： - -- [ResolveBuiltinBaseColorFactor](ResolveBuiltinBaseColorFactor.md) - 解析 base color 因子，优先走 shader semantic，再回退到常见别名属性名，最后可只从 opacity/alpha 补 `w` 分量。 -- [ResolveBuiltinBaseColorTexture](ResolveBuiltinBaseColorTexture.md) - 解析 base color 贴图，优先走 shader semantic，再回退到 `_MainTex`、`baseColorTexture` 等常见别名。 -- [BuildBuiltinForwardMaterialData](BuildBuiltinForwardMaterialData.md) - 构造 builtin forward 的兼容 fallback 常量。 +- [BuildBlendState](BuildBlendState.md) +- [ResolveMaterial](ResolveMaterial.md) - [ResolveSchemaMaterialConstantPayload](ResolveSchemaMaterialConstantPayload.md) - 直接暴露当前 `Material` 已按 shader schema 生成的常量缓冲 payload 与布局视图。 - -`BuiltinForwardPipeline` 当前会优先用 [ResolveSchemaMaterialConstantPayload](ResolveSchemaMaterialConstantPayload.md) -把 `Material::GetConstantBufferData()` 写入 `Material` 语义的 constant buffer 绑定；只有拿不到有效 payload 时， -才回退到 [BuildBuiltinForwardMaterialData](BuildBuiltinForwardMaterialData.md) 生成的 -`baseColorFactor` fallback。base-color 贴图仍由 -[ResolveBuiltinBaseColorTexture](ResolveBuiltinBaseColorTexture.md) 单独解析。 - -## render state 映射 - -`BuildRasterizerState()`、`BuildBlendState()` 和 `BuildDepthStencilState()` 会把 `MaterialRenderState` 映射成 RHI 状态，再由 [ApplyMaterialRenderState](ApplyMaterialRenderState.md) 一次性写入 `GraphicsPipelineDesc`。 - -当前影响渲染结果的核心状态包括： - -- 剔除模式 -- 混合开关与颜色 / alpha 混合因子 -- 颜色写掩码 -- 深度测试 / 深度写入 / 深度比较函数 - -## 当前实现边界 - -- 它只处理 pass 归类、逐材质常量 payload 解析、builtin forward 兼容契约、render queue 和固定渲染状态，不负责 shader variant、keyword 或多 pass 编排。 -- 没有显式元数据的材质会默认进入 `ForwardLit`，这是一种“先让基础路径可用”的保守回退。 -- `MatchesBuiltinPass(nullptr, pass)` 只有在 `pass == ForwardLit` 时才返回 `true`。 -- [ResolveSchemaMaterialConstantPayload](ResolveSchemaMaterialConstantPayload.md) 只是暴露当前 - `Material::GetConstantBufferData()` 的借用视图，不负责重新打包、补齐字段或管理内存所有权。 -- [BuildBuiltinForwardMaterialData](BuildBuiltinForwardMaterialData.md) 当前仍只收口 `baseColorFactor`， - 但它已经退到 builtin forward 的兼容 fallback 路径，不再代表 `Material` 语义 constant buffer 的主路径。 - -## 公开类型 - -| 类型 | 说明 | -|------|------| -| [BuiltinMaterialPass](BuiltinMaterialPass.md) | builtin 渲染通道枚举。 | -| [PassResourceBindingLocation](PassResourceBindingLocation.md) | 一个 `set/binding` 位置。 | -| [BuiltinPassResourceSemantic](BuiltinPassResourceSemantic.md) | builtin pass 识别的资源语义白名单。 | -| [BuiltinPassResourceBindingDesc](BuiltinPassResourceBindingDesc.md) | 单个资源绑定条目的语义化描述。 | -| [BuiltinPassResourceBindingPlan](BuiltinPassResourceBindingPlan.md) | builtin pipeline 消费的绑定计划。 | -| [BuiltinForwardMaterialData](BuiltinForwardMaterialData.md) | builtin forward 的兼容 fallback 常量结构。 | -| [MaterialConstantLayoutView](MaterialConstantLayoutView.md) | schema-driven 常量布局视图。 | -| [MaterialConstantPayloadView](MaterialConstantPayloadView.md) | schema-driven 逐材质常量 payload 的借用视图。 | -| [MaterialRenderStateHash](MaterialRenderStateHash.md) | `MaterialRenderState` 的哈希 functor。 | - -## 公开函数 - -| 函数 | 说明 | -|------|------| -| [NormalizeBuiltinPassMetadataValue](NormalizeBuiltinPassMetadataValue.md) | 统一 builtin pass 元数据的归一化规则。 | -| [IsForwardPassName](IsForwardPassName.md) | 判断名称是否匹配 forward pass。 | -| [IsUnlitPassName](IsUnlitPassName.md) | 判断名称是否匹配 unlit pass。 | -| [IsDepthOnlyPassName](IsDepthOnlyPassName.md) | 判断名称是否匹配 depth-only pass。 | -| [IsShadowCasterPassName](IsShadowCasterPassName.md) | 判断名称是否匹配 shadow-caster pass。 | -| [IsObjectIdPassName](IsObjectIdPassName.md) | 判断名称是否匹配 object-id pass。 | -| [MatchesBuiltinPassName](MatchesBuiltinPassName.md) | 判断字符串是否匹配某个 builtin pass。 | -| [ShaderPassHasExplicitBuiltinMetadata](ShaderPassHasExplicitBuiltinMetadata.md) | 判断 shader pass 是否显式声明了 builtin 元数据。 | -| [ShaderPassMatchesBuiltinPass](ShaderPassMatchesBuiltinPass.md) | 判断 shader pass 是否匹配某个 builtin pass。 | -| [ResolveBuiltinPassResourceSemantic](ResolveBuiltinPassResourceSemantic.md) | 把 shader resource binding 解析成 builtin 语义。 | -| [BuildLegacyBuiltinForwardPassResourceBindings](BuildLegacyBuiltinForwardPassResourceBindings.md) | 构造 forward 路径的 legacy fallback 绑定列表。 | -| [BuildLegacyBuiltinObjectIdPassResourceBindings](BuildLegacyBuiltinObjectIdPassResourceBindings.md) | 构造 object-id 路径的 legacy fallback 绑定列表。 | -| [IsBuiltinPassResourceTypeCompatible](IsBuiltinPassResourceTypeCompatible.md) | 判断 builtin 语义和 shader 资源类型是否兼容。 | -| [TryBuildBuiltinPassResourceBindingPlan](TryBuildBuiltinPassResourceBindingPlan.md) | 把 shader 资源绑定解析成统一 binding plan。 | -| [FindShaderPropertyBySemantic](FindShaderPropertyBySemantic.md) | 按 semantic 查找 shader property。 | -| [ResolveMaterial](ResolveMaterial.md) | 解析当前可见物体最终应使用的材质。 | -| [ResolveMaterialRenderQueue](ResolveMaterialRenderQueue.md) | 读取材质 render queue，空材质时回退到 `Geometry`。 | -| [IsTransparentRenderQueue](IsTransparentRenderQueue.md) | 判断 queue 是否处于透明区间。 | -| [MatchesBuiltinPass](MatchesBuiltinPass.md) | 判断材质是否匹配某个 builtin pass。 | -| [ResolveBuiltinBaseColorFactor](ResolveBuiltinBaseColorFactor.md) | 解析 builtin forward 使用的 base color 因子。 | -| [ResolveBuiltinBaseColorTexture](ResolveBuiltinBaseColorTexture.md) | 解析 builtin forward 使用的 base color 贴图。 | -| [BuildBuiltinForwardMaterialData](BuildBuiltinForwardMaterialData.md) | 构造 builtin forward 的兼容 fallback 常量。 | -| [ResolveSchemaMaterialConstantPayload](ResolveSchemaMaterialConstantPayload.md) | 返回当前 shader schema 驱动的逐材质常量 payload 视图。 | -| [BuildRasterizerState](BuildRasterizerState.md) | 构建栅格化状态。 | -| [BuildBlendState](BuildBlendState.md) | 构建混合状态。 | -| [BuildDepthStencilState](BuildDepthStencilState.md) | 构建深度状态。 | -| [ToRHICullMode](ToRHICullMode.md) | 把材质剔除模式映射到 RHI。 | -| [ToRHIComparisonFunc](ToRHIComparisonFunc.md) | 把材质比较函数映射到 RHI。 | -| [ToRHIBlendFactor](ToRHIBlendFactor.md) | 把材质混合因子映射到 RHI。 | -| [ToRHIBlendOp](ToRHIBlendOp.md) | 把材质混合操作映射到 RHI。 | -| [ApplyMaterialRenderState](ApplyMaterialRenderState.md) | 一次性写入图形管线状态。 | ## 相关文档 -- [CameraRenderer](../CameraRenderer/CameraRenderer.md) -- [RenderSceneExtractor](../RenderSceneExtractor/RenderSceneExtractor.md) -- [VisibleRenderObject](../VisibleRenderObject/VisibleRenderObject.md) +- [Builtin](../Builtin/Builtin.md) +- [Materials](../Materials/Materials.md) +- [RenderMaterialResolve](../Materials/RenderMaterialResolve/RenderMaterialResolve.md) +- [RenderMaterialStateUtils](../Materials/RenderMaterialStateUtils/RenderMaterialStateUtils.md) - [BuiltinForwardPipeline](../Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md) diff --git a/docs/api/XCEngine/Rendering/RenderMaterialUtility/ResolveBuiltinBaseColorFactor.md b/docs/api/XCEngine/Rendering/RenderMaterialUtility/ResolveBuiltinBaseColorFactor.md index d874584a..306da2ae 100644 --- a/docs/api/XCEngine/Rendering/RenderMaterialUtility/ResolveBuiltinBaseColorFactor.md +++ b/docs/api/XCEngine/Rendering/RenderMaterialUtility/ResolveBuiltinBaseColorFactor.md @@ -4,7 +4,7 @@ **类型**: `function` -**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h` +**头文件**: `XCEngine/Rendering/Materials/RenderMaterialResolve.h` ## 签名 diff --git a/docs/api/XCEngine/Rendering/RenderMaterialUtility/ResolveBuiltinBaseColorTexture.md b/docs/api/XCEngine/Rendering/RenderMaterialUtility/ResolveBuiltinBaseColorTexture.md index e17f79ca..dc54006c 100644 --- a/docs/api/XCEngine/Rendering/RenderMaterialUtility/ResolveBuiltinBaseColorTexture.md +++ b/docs/api/XCEngine/Rendering/RenderMaterialUtility/ResolveBuiltinBaseColorTexture.md @@ -4,7 +4,7 @@ **类型**: `function` -**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h` +**头文件**: `XCEngine/Rendering/Materials/RenderMaterialResolve.h` ## 签名 diff --git a/docs/api/XCEngine/Rendering/RenderMaterialUtility/ResolveBuiltinPassResourceSemantic.md b/docs/api/XCEngine/Rendering/RenderMaterialUtility/ResolveBuiltinPassResourceSemantic.md index 78be6344..37f3cf41 100644 --- a/docs/api/XCEngine/Rendering/RenderMaterialUtility/ResolveBuiltinPassResourceSemantic.md +++ b/docs/api/XCEngine/Rendering/RenderMaterialUtility/ResolveBuiltinPassResourceSemantic.md @@ -4,7 +4,7 @@ **类型**: `function` -**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h` +**头文件**: `XCEngine/Rendering/Builtin/BuiltinPassMetadataUtils.h` ## 签名 diff --git a/docs/api/XCEngine/Rendering/RenderMaterialUtility/ResolveMaterial.md b/docs/api/XCEngine/Rendering/RenderMaterialUtility/ResolveMaterial.md index 702cbb84..f48a4929 100644 --- a/docs/api/XCEngine/Rendering/RenderMaterialUtility/ResolveMaterial.md +++ b/docs/api/XCEngine/Rendering/RenderMaterialUtility/ResolveMaterial.md @@ -4,7 +4,7 @@ **类型**: `function` -**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h` +**头文件**: `XCEngine/Rendering/Materials/RenderMaterialResolve.h` ## 签名 diff --git a/docs/api/XCEngine/Rendering/RenderMaterialUtility/ResolveMaterialRenderQueue.md b/docs/api/XCEngine/Rendering/RenderMaterialUtility/ResolveMaterialRenderQueue.md index 2faf5e47..cdf4ec36 100644 --- a/docs/api/XCEngine/Rendering/RenderMaterialUtility/ResolveMaterialRenderQueue.md +++ b/docs/api/XCEngine/Rendering/RenderMaterialUtility/ResolveMaterialRenderQueue.md @@ -4,7 +4,7 @@ **类型**: `function` -**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h` +**头文件**: `XCEngine/Rendering/Materials/RenderMaterialResolve.h` ## 签名 diff --git a/docs/api/XCEngine/Rendering/RenderMaterialUtility/ResolveSchemaMaterialConstantPayload.md b/docs/api/XCEngine/Rendering/RenderMaterialUtility/ResolveSchemaMaterialConstantPayload.md index a74c25bc..b7d304ff 100644 --- a/docs/api/XCEngine/Rendering/RenderMaterialUtility/ResolveSchemaMaterialConstantPayload.md +++ b/docs/api/XCEngine/Rendering/RenderMaterialUtility/ResolveSchemaMaterialConstantPayload.md @@ -4,7 +4,7 @@ **类型**: `function` -**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h` +**头文件**: `XCEngine/Rendering/Materials/RenderMaterialResolve.h` ## 签名 diff --git a/docs/api/XCEngine/Rendering/RenderMaterialUtility/ShaderPassHasExplicitBuiltinMetadata.md b/docs/api/XCEngine/Rendering/RenderMaterialUtility/ShaderPassHasExplicitBuiltinMetadata.md index 0713cbf5..b3e64c26 100644 --- a/docs/api/XCEngine/Rendering/RenderMaterialUtility/ShaderPassHasExplicitBuiltinMetadata.md +++ b/docs/api/XCEngine/Rendering/RenderMaterialUtility/ShaderPassHasExplicitBuiltinMetadata.md @@ -4,7 +4,7 @@ **类型**: `function` -**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h` +**头文件**: `XCEngine/Rendering/Builtin/BuiltinPassMetadataUtils.h` ## 签名 diff --git a/docs/api/XCEngine/Rendering/RenderMaterialUtility/ShaderPassMatchesBuiltinPass.md b/docs/api/XCEngine/Rendering/RenderMaterialUtility/ShaderPassMatchesBuiltinPass.md index eab9bb6c..43507144 100644 --- a/docs/api/XCEngine/Rendering/RenderMaterialUtility/ShaderPassMatchesBuiltinPass.md +++ b/docs/api/XCEngine/Rendering/RenderMaterialUtility/ShaderPassMatchesBuiltinPass.md @@ -4,7 +4,7 @@ **类型**: `function` -**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h` +**头文件**: `XCEngine/Rendering/Builtin/BuiltinPassMetadataUtils.h` ## 签名 diff --git a/docs/api/XCEngine/Rendering/RenderMaterialUtility/ToRHIBlendFactor.md b/docs/api/XCEngine/Rendering/RenderMaterialUtility/ToRHIBlendFactor.md index a632960e..f0dd1c2f 100644 --- a/docs/api/XCEngine/Rendering/RenderMaterialUtility/ToRHIBlendFactor.md +++ b/docs/api/XCEngine/Rendering/RenderMaterialUtility/ToRHIBlendFactor.md @@ -4,7 +4,7 @@ **类型**: `function` -**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h` +**头文件**: `XCEngine/Rendering/Materials/RenderMaterialStateUtils.h` ## 签名 diff --git a/docs/api/XCEngine/Rendering/RenderMaterialUtility/ToRHIBlendOp.md b/docs/api/XCEngine/Rendering/RenderMaterialUtility/ToRHIBlendOp.md index 037d0402..2709a342 100644 --- a/docs/api/XCEngine/Rendering/RenderMaterialUtility/ToRHIBlendOp.md +++ b/docs/api/XCEngine/Rendering/RenderMaterialUtility/ToRHIBlendOp.md @@ -4,7 +4,7 @@ **类型**: `function` -**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h` +**头文件**: `XCEngine/Rendering/Materials/RenderMaterialStateUtils.h` ## 签名 diff --git a/docs/api/XCEngine/Rendering/RenderMaterialUtility/ToRHIComparisonFunc.md b/docs/api/XCEngine/Rendering/RenderMaterialUtility/ToRHIComparisonFunc.md index 694316d8..12382252 100644 --- a/docs/api/XCEngine/Rendering/RenderMaterialUtility/ToRHIComparisonFunc.md +++ b/docs/api/XCEngine/Rendering/RenderMaterialUtility/ToRHIComparisonFunc.md @@ -4,7 +4,7 @@ **类型**: `function` -**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h` +**头文件**: `XCEngine/Rendering/Materials/RenderMaterialStateUtils.h` ## 签名 diff --git a/docs/api/XCEngine/Rendering/RenderMaterialUtility/ToRHICullMode.md b/docs/api/XCEngine/Rendering/RenderMaterialUtility/ToRHICullMode.md index 28aadd67..33ad07e1 100644 --- a/docs/api/XCEngine/Rendering/RenderMaterialUtility/ToRHICullMode.md +++ b/docs/api/XCEngine/Rendering/RenderMaterialUtility/ToRHICullMode.md @@ -4,7 +4,7 @@ **类型**: `function` -**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h` +**头文件**: `XCEngine/Rendering/Materials/RenderMaterialStateUtils.h` ## 签名 diff --git a/docs/api/XCEngine/Rendering/RenderMaterialUtility/TryBuildBuiltinPassResourceBindingPlan.md b/docs/api/XCEngine/Rendering/RenderMaterialUtility/TryBuildBuiltinPassResourceBindingPlan.md index 1e71adc8..82f85d0f 100644 --- a/docs/api/XCEngine/Rendering/RenderMaterialUtility/TryBuildBuiltinPassResourceBindingPlan.md +++ b/docs/api/XCEngine/Rendering/RenderMaterialUtility/TryBuildBuiltinPassResourceBindingPlan.md @@ -4,7 +4,7 @@ **类型**: `function` -**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h` +**头文件**: `XCEngine/Rendering/Builtin/BuiltinPassLayoutUtils.h` ## 签名 @@ -52,12 +52,10 @@ bool TryBuildBuiltinPassResourceBindingPlan( `tests/Rendering/unit/test_builtin_forward_pipeline.cpp` 当前验证了： - 显式 `ForwardLit` / `Unlit` shader 资源声明能正确落成 plan -- legacy forward fallback 绑定也能正确落成 plan -- legacy object-id fallback 绑定会得到只含 `PerObject` 的 plan +- 非法 builtin 语义和非法语义 / 资源类型组合会被拒绝 +- 生成的 plan 会正确计算 `firstDescriptorSet` 与 `descriptorSetCount` ## 相关文档 - [BuiltinPassResourceBindingPlan](BuiltinPassResourceBindingPlan.md) -- [BuildLegacyBuiltinForwardPassResourceBindings](BuildLegacyBuiltinForwardPassResourceBindings.md) -- [BuildLegacyBuiltinObjectIdPassResourceBindings](BuildLegacyBuiltinObjectIdPassResourceBindings.md) - [RenderMaterialUtility](RenderMaterialUtility.md) diff --git a/docs/api/XCEngine/Rendering/RenderResourceCache/RenderResourceCache.md b/docs/api/XCEngine/Rendering/RenderResourceCache/RenderResourceCache.md index 89434e8a..aedbc2c0 100644 --- a/docs/api/XCEngine/Rendering/RenderResourceCache/RenderResourceCache.md +++ b/docs/api/XCEngine/Rendering/RenderResourceCache/RenderResourceCache.md @@ -1,10 +1,10 @@ -# RenderResourceCache +# RenderResourceCache **命名空间**: `XCEngine::Rendering` **类型**: `class` -**头文件**: `XCEngine/Rendering/RenderResourceCache.h` +**头文件**: `XCEngine/Rendering/Caches/RenderResourceCache.h` **描述**: 负责把 `Mesh` 和 `Texture` 上传成 RHI 资源，并在渲染阶段按资源指针缓存这些 GPU 对象。 @@ -68,3 +68,4 @@ - [当前模块](../Rendering.md) - [BuiltinForwardPipeline](../Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md) - [RenderContext](../RenderContext/RenderContext.md) + diff --git a/docs/api/XCEngine/Rendering/RenderSceneExtractor/RenderSceneExtractor.md b/docs/api/XCEngine/Rendering/RenderSceneExtractor/RenderSceneExtractor.md index 67dd7bb5..82242032 100644 --- a/docs/api/XCEngine/Rendering/RenderSceneExtractor/RenderSceneExtractor.md +++ b/docs/api/XCEngine/Rendering/RenderSceneExtractor/RenderSceneExtractor.md @@ -1,10 +1,10 @@ -# RenderSceneExtractor +# RenderSceneExtractor **命名空间**: `XCEngine::Rendering` **类型**: `class + related structs` -**头文件**: `XCEngine/Rendering/RenderSceneExtractor.h` +**头文件**: `XCEngine/Rendering/Extraction/RenderSceneExtractor.h` **描述**: 把 `Scene` 压平成渲染侧可消费的 `RenderSceneData`，负责相机选择、主方向光提取和 `visibleItems` 收集。 @@ -84,3 +84,4 @@ - [VisibleRenderObject](../VisibleRenderObject/VisibleRenderObject.md) - [CameraRenderer](../CameraRenderer/CameraRenderer.md) - [Scene Extraction And Builtin Forward Pipeline](../../../_guides/Rendering/Scene-Extraction-And-Builtin-Forward-Pipeline.md) + diff --git a/docs/api/XCEngine/Rendering/RenderSceneUtility/RenderSceneUtility.md b/docs/api/XCEngine/Rendering/RenderSceneUtility/RenderSceneUtility.md index 66207b40..07530e08 100644 --- a/docs/api/XCEngine/Rendering/RenderSceneUtility/RenderSceneUtility.md +++ b/docs/api/XCEngine/Rendering/RenderSceneUtility/RenderSceneUtility.md @@ -1,10 +1,10 @@ -# RenderSceneUtility +# RenderSceneUtility **命名空间**: `XCEngine::Rendering` **类型**: `utility header` -**头文件**: `XCEngine/Rendering/RenderSceneUtility.h` +**头文件**: `XCEngine/Rendering/Extraction/RenderSceneUtility.h` **描述**: 提供把相机和场景对象翻译成 `RenderCameraData` 与 `VisibleRenderItem` 的基础 helper。 @@ -71,3 +71,4 @@ - [RenderSceneExtractor](../RenderSceneExtractor/RenderSceneExtractor.md) - [VisibleRenderObject](../VisibleRenderObject/VisibleRenderObject.md) - [RenderMaterialUtility](../RenderMaterialUtility/RenderMaterialUtility.md) + diff --git a/docs/api/XCEngine/Rendering/Rendering.md b/docs/api/XCEngine/Rendering/Rendering.md index 29c603e9..7b9a3886 100644 --- a/docs/api/XCEngine/Rendering/Rendering.md +++ b/docs/api/XCEngine/Rendering/Rendering.md @@ -4,18 +4,18 @@ **类型**: `module` -**描述**: 当前场景渲染主链路所在模块，覆盖 request 规划、场景提取、主管线执行、shadow-caster / depth-only / object-id 输出，以及调用方注入的 pre / post / overlay pass。 +**描述**: 当前场景渲染主链路所在模块，覆盖 request 规划、场景提取、frame data、主管线执行、资源缓存、shadow-caster / depth-only / object-id 输出，以及调用方注入的 pre / post / overlay pass。 ## 概览 当前 `Rendering` 模块已经不再是简单的“scene -> pipeline”两段式结构，而是一条更完整的提交流程： -1. [SceneRenderer](SceneRenderer/SceneRenderer.md) 规划并排序 `CameraRenderRequest`。 -2. [CameraRenderer](CameraRenderer/CameraRenderer.md) 执行单个 request。 -3. [RenderSceneExtractor](RenderSceneExtractor/RenderSceneExtractor.md) 生成 `RenderSceneData`。 +1. [Planning](Planning/Planning.md) 规划并排序 `CameraRenderRequest`。 +2. [Execution](Execution/Execution.md) 执行单个 request 或 request 数组。 +3. [Extraction](Extraction/Extraction.md) 生成 `RenderSceneData`。 4. [RenderPipelineAsset](RenderPipelineAsset/RenderPipelineAsset.md) 决定当前主管线实例如何创建。 5. [RenderPipeline](RenderPipeline/RenderPipeline.md) 执行主场景绘制。 -6. [ObjectIdPass](ObjectIdPass/ObjectIdPass.md) 和 [Passes](Passes/Passes.md) 子模块补上 shadow-caster、depth-only、object-id、grid、outline 等附加阶段。 +6. [Caches](Caches/Caches.md)、[Passes](Passes/Passes.md) 和 [Picking](Picking/Picking.md) 子模块补上资源复用、shadow-caster、depth-only、object-id 与其它附加阶段。 默认主链路当前是： @@ -24,9 +24,9 @@ 这套分层本身就是当前渲染架构最重要的设计点。 -- `SceneRenderer` / `SceneRenderRequestPlanner` 处理“这次该画什么、顺序是什么” -- `CameraRenderer` 处理“单个 request 怎样被真正执行” -- `RenderSceneExtractor` 处理“场景语义怎样压平成渲染语义” +- `Planning` 处理“这次该画什么、顺序是什么” +- `Execution` 处理“单个 request 怎样被真正执行” +- `Extraction` 处理“场景语义怎样压平成渲染语义” - `RenderPipeline` 处理“压平后的渲染数据怎样落到 GPU” 对商业级引擎来说，这种拆法的价值很直接： @@ -74,15 +74,17 @@ Scene View 里的无限网格、选中轮廓和编辑器 overlay，当前都不 ## 当前基础设施分层 -更底层的基础协议由这些页面补齐： +更底层的基础协议由这些分层补齐： -- [SceneRenderRequestPlanner](SceneRenderRequestPlanner/SceneRenderRequestPlanner.md) -- [SceneRenderRequestUtils](SceneRenderRequestUtils/SceneRenderRequestUtils.md) -- [RenderSceneUtility](RenderSceneUtility/RenderSceneUtility.md) +- [Planning](Planning/Planning.md) +- [Execution](Execution/Execution.md) +- [FrameData](FrameData/FrameData.md) +- [Extraction](Extraction/Extraction.md) +- [Caches](Caches/Caches.md) - [RenderPass](RenderPass/RenderPass.md) -- [ObjectIdEncoding](ObjectIdEncoding/ObjectIdEncoding.md) +- [Picking](Picking/Picking.md) -它们分别负责 request 规划、排序规则、scene helper、通用 pass 生命周期和 object-id 编解码约定。 +它们分别负责 request 规划、request 执行、frame data 协议、scene helper、GPU 资源缓存、通用 pass 生命周期和 object-id/picking 约定。 ## 当前实现边界 @@ -91,28 +93,23 @@ Scene View 里的无限网格、选中轮廓和编辑器 overlay，当前都不 - 多相机排序由 `SceneRenderer` 处理，`CameraRenderer` 只执行单个 request。 - 编辑器特有的 grid / outline / overlay 组装逻辑不在 `Rendering` 模块里完成，而是在 Editor 层先转成 `RenderPassSequence`。 -## 头文件索引 +## 分层索引 -- [CameraRenderRequest](CameraRenderRequest/CameraRenderRequest.md) - `CameraRenderRequest.h` -- [CameraRenderer](CameraRenderer/CameraRenderer.md) - `CameraRenderer.h` -- [ObjectIdEncoding](ObjectIdEncoding/ObjectIdEncoding.md) - `ObjectIdEncoding.h` -- [ObjectIdPass](ObjectIdPass/ObjectIdPass.md) - `ObjectIdPass.h` +- [Execution](Execution/Execution.md) - `Execution/` +- [Planning](Planning/Planning.md) - `Planning/` +- [FrameData](FrameData/FrameData.md) - `FrameData/` +- [Extraction](Extraction/Extraction.md) - `Extraction/` +- [Caches](Caches/Caches.md) - `Caches/` - [Passes](Passes/Passes.md) - `Passes/` -- [RenderCameraData](RenderCameraData/RenderCameraData.md) - `RenderCameraData.h` +- [Picking](Picking/Picking.md) - `Picking/` - [RenderContext](RenderContext/RenderContext.md) - `RenderContext.h` -- [RenderMaterialUtility](RenderMaterialUtility/RenderMaterialUtility.md) - `RenderMaterialUtility.h` - [RenderPass](RenderPass/RenderPass.md) - `RenderPass.h` - [RenderPipeline](RenderPipeline/RenderPipeline.md) - `RenderPipeline.h` - [RenderPipelineAsset](RenderPipelineAsset/RenderPipelineAsset.md) - `RenderPipelineAsset.h` -- [RenderResourceCache](RenderResourceCache/RenderResourceCache.md) - `RenderResourceCache.h` -- [RenderSceneExtractor](RenderSceneExtractor/RenderSceneExtractor.md) - `RenderSceneExtractor.h` -- [RenderSceneUtility](RenderSceneUtility/RenderSceneUtility.md) - `RenderSceneUtility.h` - [RenderSurface](RenderSurface/RenderSurface.md) - `RenderSurface.h` -- [SceneRenderRequestPlanner](SceneRenderRequestPlanner/SceneRenderRequestPlanner.md) - `SceneRenderRequestPlanner.h` -- [SceneRenderRequestUtils](SceneRenderRequestUtils/SceneRenderRequestUtils.md) - `SceneRenderRequestUtils.h` -- [SceneRenderer](SceneRenderer/SceneRenderer.md) - `SceneRenderer.h` -- [VisibleRenderObject](VisibleRenderObject/VisibleRenderObject.md) - `VisibleRenderObject.h` - [Pipelines](Pipelines/Pipelines.md) - `Pipelines/` +- [Materials](Materials/Materials.md) - `Materials/` +- [Builtin](Builtin/Builtin.md) - `Builtin/` ## 相关指南 diff --git a/docs/api/XCEngine/Rendering/SceneRenderRequestPlanner/SceneRenderRequestPlanner.md b/docs/api/XCEngine/Rendering/SceneRenderRequestPlanner/SceneRenderRequestPlanner.md index 440a5f83..52525386 100644 --- a/docs/api/XCEngine/Rendering/SceneRenderRequestPlanner/SceneRenderRequestPlanner.md +++ b/docs/api/XCEngine/Rendering/SceneRenderRequestPlanner/SceneRenderRequestPlanner.md @@ -1,10 +1,10 @@ -# SceneRenderRequestPlanner +# SceneRenderRequestPlanner **命名空间**: `XCEngine::Rendering` **类型**: `class` -**头文件**: `XCEngine/Rendering/SceneRenderRequestPlanner.h` +**头文件**: `XCEngine/Rendering/Planning/SceneRenderRequestPlanner.h` **描述**: 负责从场景和可选 override camera 生成实际要提交给 `CameraRenderer` 的相机请求列表。 @@ -82,3 +82,4 @@ - [SceneRenderRequestUtils](../SceneRenderRequestUtils/SceneRenderRequestUtils.md) - [CameraRenderRequest](../CameraRenderRequest/CameraRenderRequest.md) - [Camera Request Planning And Clear Rules](../../../_guides/Rendering/Camera-Request-Planning-And-Clear-Rules.md) + diff --git a/docs/api/XCEngine/Rendering/SceneRenderRequestUtils/SceneRenderRequestUtils.md b/docs/api/XCEngine/Rendering/SceneRenderRequestUtils/SceneRenderRequestUtils.md index b4ac94b7..cd4af241 100644 --- a/docs/api/XCEngine/Rendering/SceneRenderRequestUtils/SceneRenderRequestUtils.md +++ b/docs/api/XCEngine/Rendering/SceneRenderRequestUtils/SceneRenderRequestUtils.md @@ -1,10 +1,10 @@ -# SceneRenderRequestUtils +# SceneRenderRequestUtils **命名空间**: `XCEngine::Rendering::SceneRenderRequestUtils` **类型**: `utility header` -**头文件**: `XCEngine/Rendering/SceneRenderRequestUtils.h` +**头文件**: `XCEngine/Rendering/Planning/SceneRenderRequestUtils.h` **描述**: 提供相机可用性判断、稳定排序、clear flag 推导、render area 计算和 request 组装等内联 helper。 @@ -101,3 +101,4 @@ - [CameraRenderRequest](../CameraRenderRequest/CameraRenderRequest.md) - [SceneRenderer](../SceneRenderer/SceneRenderer.md) - [Camera Request Planning And Clear Rules](../../../_guides/Rendering/Camera-Request-Planning-And-Clear-Rules.md) + diff --git a/docs/api/XCEngine/Rendering/SceneRenderer/SceneRenderer.md b/docs/api/XCEngine/Rendering/SceneRenderer/SceneRenderer.md index 2d966030..0c5c5255 100644 --- a/docs/api/XCEngine/Rendering/SceneRenderer/SceneRenderer.md +++ b/docs/api/XCEngine/Rendering/SceneRenderer/SceneRenderer.md @@ -1,10 +1,10 @@ -# SceneRenderer +# SceneRenderer **命名空间**: `XCEngine::Rendering` **类型**: `class` -**头文件**: `XCEngine/Rendering/SceneRenderer.h` +**头文件**: `XCEngine/Rendering/Execution/SceneRenderer.h` **描述**: 场景级渲染编排入口。它负责构建和排序 `CameraRenderRequest`，再把每个请求转交给 [CameraRenderer](../CameraRenderer/CameraRenderer.md) 执行。 @@ -116,3 +116,4 @@ return Render(BuildRenderRequests(scene, overrideCamera, context, surface)); - [SceneRenderRequestUtils](../SceneRenderRequestUtils/SceneRenderRequestUtils.md) - [RenderSceneExtractor](../RenderSceneExtractor/RenderSceneExtractor.md) - [Camera Request Planning And Clear Rules](../../../_guides/Rendering/Camera-Request-Planning-And-Clear-Rules.md) + diff --git a/docs/api/XCEngine/Rendering/VisibleRenderObject/VisibleRenderObject.md b/docs/api/XCEngine/Rendering/VisibleRenderObject/VisibleRenderObject.md index 6481e83f..93ea2b75 100644 --- a/docs/api/XCEngine/Rendering/VisibleRenderObject/VisibleRenderObject.md +++ b/docs/api/XCEngine/Rendering/VisibleRenderObject/VisibleRenderObject.md @@ -1,10 +1,10 @@ -# VisibleRenderObject +# VisibleRenderObject **命名空间**: `XCEngine::Rendering` **类型**: `struct alias` -**头文件**: `XCEngine/Rendering/VisibleRenderObject.h` +**头文件**: `XCEngine/Rendering/FrameData/VisibleRenderItem.h` **描述**: `VisibleRenderObject` 当前只是 `VisibleRenderItem` 的兼容别名。它表示 scene extraction 之后交给渲染阶段消费的一条可绘制项记录。 @@ -58,3 +58,4 @@ using VisibleRenderObject = VisibleRenderItem; - [RenderSceneExtractor](../RenderSceneExtractor/RenderSceneExtractor.md) - [RenderSceneUtility](../RenderSceneUtility/RenderSceneUtility.md) - [BuiltinForwardPipeline](../Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md) +