docs: complete rendering api reorg coverage
This commit is contained in:
40
docs/api/XCEngine/Rendering/Builtin/Builtin.md
Normal file
40
docs/api/XCEngine/Rendering/Builtin/Builtin.md
Normal file
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
29
docs/api/XCEngine/Rendering/Caches/Caches.md
Normal file
29
docs/api/XCEngine/Rendering/Caches/Caches.md
Normal file
@@ -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)
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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)
|
||||
|
||||
|
||||
@@ -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)
|
||||
|
||||
|
||||
@@ -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)
|
||||
|
||||
|
||||
@@ -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)
|
||||
|
||||
|
||||
@@ -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)
|
||||
|
||||
|
||||
@@ -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)
|
||||
|
||||
|
||||
@@ -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)
|
||||
|
||||
|
||||
@@ -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)
|
||||
|
||||
|
||||
@@ -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)
|
||||
|
||||
|
||||
@@ -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)
|
||||
|
||||
|
||||
@@ -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)
|
||||
|
||||
|
||||
@@ -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)
|
||||
|
||||
|
||||
@@ -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)
|
||||
|
||||
|
||||
@@ -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<RenderPass> depthOnlyPass);
|
||||
- [GetDepthOnlyPass](GetDepthOnlyPass.md)
|
||||
- [Render](Render.md)
|
||||
- [BuiltinDepthOnlyPass](../Passes/BuiltinDepthOnlyPass/BuiltinDepthOnlyPass.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> objectIdPass);
|
||||
- [GetObjectIdPass](GetObjectIdPass.md)
|
||||
- [Render](Render.md)
|
||||
- [Passes](../Passes/Passes.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<RenderPipeline> pipeline);
|
||||
- [SetPipelineAsset](SetPipelineAsset.md)
|
||||
- [GetPipeline](GetPipeline.md)
|
||||
- [GetPipelineAsset](GetPipelineAsset.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<const RenderPipelineAsset> pipelineAsset);
|
||||
- [SetPipeline](SetPipeline.md)
|
||||
- [GetPipelineAsset](GetPipelineAsset.md)
|
||||
- [Constructor](Constructor.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<RenderPass> shadowCasterPass);
|
||||
- [GetShadowCasterPass](GetShadowCasterPass.md)
|
||||
- [Render](Render.md)
|
||||
- [BuiltinShadowCasterPass](../Passes/BuiltinShadowCasterPass/BuiltinShadowCasterPass.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)
|
||||
|
||||
38
docs/api/XCEngine/Rendering/Execution/Execution.md
Normal file
38
docs/api/XCEngine/Rendering/Execution/Execution.md
Normal file
@@ -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)
|
||||
|
||||
@@ -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)
|
||||
|
||||
33
docs/api/XCEngine/Rendering/Extraction/Extraction.md
Normal file
33
docs/api/XCEngine/Rendering/Extraction/Extraction.md
Normal file
@@ -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)
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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)
|
||||
|
||||
35
docs/api/XCEngine/Rendering/FrameData/FrameData.md
Normal file
35
docs/api/XCEngine/Rendering/FrameData/FrameData.md
Normal file
@@ -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)
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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)
|
||||
|
||||
33
docs/api/XCEngine/Rendering/Materials/Materials.md
Normal file
33
docs/api/XCEngine/Rendering/Materials/Materials.md
Normal file
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
|
||||
@@ -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<RenderPass>`。
|
||||
- 默认实现是 [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)
|
||||
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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。
|
||||
|
||||
## 当前实现边界
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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)
|
||||
32
docs/api/XCEngine/Rendering/Picking/Picking.md
Normal file
32
docs/api/XCEngine/Rendering/Picking/Picking.md
Normal file
@@ -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)
|
||||
@@ -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) 按需上传。
|
||||
|
||||
## 当前限制
|
||||
|
||||
@@ -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<CameraPostProcessPassDesc>`，供 `CameraComponent` 直接持有。
|
||||
|
||||
## 当前调用链
|
||||
|
||||
- `CameraComponent` 序列化、反序列化并持有这份声明式 stack。
|
||||
- [CameraPostProcessPassFactory](../CameraPostProcessPassFactory/CameraPostProcessPassFactory.md) 把它转换成运行时 `RenderPassSequence`。
|
||||
- `SceneRenderer` 再把生成的 sequence 挂到 `CameraRenderRequest::postProcess`。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [Planning](../Planning.md)
|
||||
- [CameraPostProcessPassFactory](../CameraPostProcessPassFactory/CameraPostProcessPassFactory.md)
|
||||
- [BuiltinColorScalePostProcessPass](../../Passes/BuiltinColorScalePostProcessPass/BuiltinColorScalePostProcessPass.md)
|
||||
@@ -0,0 +1,35 @@
|
||||
# CameraPostProcessPassFactory
|
||||
|
||||
**命名空间**: `XCEngine::Rendering`
|
||||
|
||||
**类型**: `utility header`
|
||||
|
||||
**头文件**: `XCEngine/Rendering/Planning/CameraPostProcessPassFactory.h`
|
||||
|
||||
**描述**: 相机后处理 pass 工厂头，负责把声明式 `CameraPostProcessStack` 转换成运行时 `RenderPassSequence`。
|
||||
|
||||
## 当前公开能力
|
||||
|
||||
```cpp
|
||||
std::unique_ptr<RenderPassSequence> 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)
|
||||
@@ -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)
|
||||
|
||||
@@ -0,0 +1,34 @@
|
||||
# FinalColorPassFactory
|
||||
|
||||
**命名空间**: `XCEngine::Rendering`
|
||||
|
||||
**类型**: `utility header`
|
||||
|
||||
**头文件**: `XCEngine/Rendering/Planning/FinalColorPassFactory.h`
|
||||
|
||||
**描述**: final-output pass 工厂头，负责把 `ResolvedFinalColorPolicy` 转换成最终的 fullscreen `RenderPassSequence`。
|
||||
|
||||
## 当前公开能力
|
||||
|
||||
```cpp
|
||||
std::unique_ptr<RenderPassSequence> 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)
|
||||
@@ -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)
|
||||
39
docs/api/XCEngine/Rendering/Planning/Planning.md
Normal file
39
docs/api/XCEngine/Rendering/Planning/Planning.md
Normal file
@@ -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)
|
||||
@@ -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)
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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)
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h`
|
||||
**头文件**: `XCEngine/Rendering/Materials/RenderMaterialStateUtils.h`
|
||||
|
||||
## 签名
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h`
|
||||
**头文件**: `XCEngine/Rendering/Materials/RenderMaterialStateUtils.h`
|
||||
|
||||
## 签名
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h`
|
||||
**头文件**: `XCEngine/Rendering/Materials/RenderMaterialResolve.h`
|
||||
|
||||
## 签名
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h`
|
||||
**头文件**: `XCEngine/Rendering/Materials/RenderMaterialStateUtils.h`
|
||||
|
||||
## 签名
|
||||
|
||||
|
||||
@@ -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<Resources::ShaderResourceBindingDesc> 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)
|
||||
|
||||
@@ -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<Resources::ShaderResourceBindingDesc> 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)
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h`
|
||||
**头文件**: `XCEngine/Rendering/Materials/RenderMaterialStateUtils.h`
|
||||
|
||||
## 签名
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
**类型**: `struct`
|
||||
|
||||
**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h`
|
||||
**头文件**: `XCEngine/Rendering/Materials/RenderMaterialResolve.h`
|
||||
|
||||
**描述**: `BuiltinForwardPipeline` 在拿不到 schema-driven 材质常量 payload 时使用的兼容逐材质常量结构。
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
**类型**: `enum class`
|
||||
|
||||
**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h`
|
||||
**头文件**: `XCEngine/Rendering/Builtin/BuiltinPassTypes.h`
|
||||
|
||||
## 枚举值
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
**类型**: `struct`
|
||||
|
||||
**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h`
|
||||
**头文件**: `XCEngine/Rendering/Builtin/BuiltinPassTypes.h`
|
||||
|
||||
## 字段
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
**类型**: `struct`
|
||||
|
||||
**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h`
|
||||
**头文件**: `XCEngine/Rendering/Builtin/BuiltinPassTypes.h`
|
||||
|
||||
## 字段
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
**类型**: `enum class`
|
||||
|
||||
**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h`
|
||||
**头文件**: `XCEngine/Rendering/Builtin/BuiltinPassTypes.h`
|
||||
|
||||
## 枚举值
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h`
|
||||
**头文件**: `XCEngine/Rendering/Materials/RenderMaterialResolve.h`
|
||||
|
||||
## 签名
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h`
|
||||
**头文件**: `XCEngine/Rendering/Builtin/BuiltinPassMetadataUtils.h`
|
||||
|
||||
## 签名
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h`
|
||||
**头文件**: `XCEngine/Rendering/Builtin/BuiltinPassMetadataUtils.h`
|
||||
|
||||
## 签名
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h`
|
||||
**头文件**: `XCEngine/Rendering/Builtin/BuiltinPassMetadataUtils.h`
|
||||
|
||||
## 签名
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h`
|
||||
**头文件**: `XCEngine/Rendering/Builtin/BuiltinPassMetadataUtils.h`
|
||||
|
||||
## 签名
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h`
|
||||
**头文件**: `XCEngine/Rendering/Builtin/BuiltinPassMetadataUtils.h`
|
||||
|
||||
## 签名
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h`
|
||||
**头文件**: `XCEngine/Rendering/Materials/RenderMaterialResolve.h`
|
||||
|
||||
## 签名
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h`
|
||||
**头文件**: `XCEngine/Rendering/Builtin/BuiltinPassMetadataUtils.h`
|
||||
|
||||
## 签名
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h`
|
||||
**头文件**: `XCEngine/Rendering/Materials/RenderMaterialResolve.h`
|
||||
|
||||
## 签名
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h`
|
||||
**头文件**: `XCEngine/Rendering/Builtin/BuiltinPassMetadataUtils.h`
|
||||
|
||||
## 签名
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
**类型**: `struct`
|
||||
|
||||
**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h`
|
||||
**头文件**: `XCEngine/Rendering/Materials/RenderMaterialResolve.h`
|
||||
|
||||
## 字段
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
**类型**: `struct`
|
||||
|
||||
**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h`
|
||||
**头文件**: `XCEngine/Rendering/Materials/RenderMaterialResolve.h`
|
||||
|
||||
**描述**: 指向 schema-driven 材质常量缓冲字节及其布局的非 owning 视图，用于把 `Material::GetConstantBufferData()` 直接写入渲染 descriptor set。
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
**类型**: `functor struct`
|
||||
|
||||
**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h`
|
||||
**头文件**: `XCEngine/Rendering/Materials/RenderMaterialStateUtils.h`
|
||||
|
||||
## 作用
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h`
|
||||
**头文件**: `XCEngine/Rendering/Builtin/BuiltinPassMetadataUtils.h`
|
||||
|
||||
## 签名
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
**类型**: `struct`
|
||||
|
||||
**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h`
|
||||
**头文件**: `XCEngine/Rendering/Builtin/BuiltinPassTypes.h`
|
||||
|
||||
## 字段
|
||||
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h`
|
||||
**头文件**: `XCEngine/Rendering/Materials/RenderMaterialResolve.h`
|
||||
|
||||
## 签名
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h`
|
||||
**头文件**: `XCEngine/Rendering/Materials/RenderMaterialResolve.h`
|
||||
|
||||
## 签名
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h`
|
||||
**头文件**: `XCEngine/Rendering/Builtin/BuiltinPassMetadataUtils.h`
|
||||
|
||||
## 签名
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h`
|
||||
**头文件**: `XCEngine/Rendering/Materials/RenderMaterialResolve.h`
|
||||
|
||||
## 签名
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h`
|
||||
**头文件**: `XCEngine/Rendering/Materials/RenderMaterialResolve.h`
|
||||
|
||||
## 签名
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h`
|
||||
**头文件**: `XCEngine/Rendering/Materials/RenderMaterialResolve.h`
|
||||
|
||||
## 签名
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h`
|
||||
**头文件**: `XCEngine/Rendering/Builtin/BuiltinPassMetadataUtils.h`
|
||||
|
||||
## 签名
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h`
|
||||
**头文件**: `XCEngine/Rendering/Builtin/BuiltinPassMetadataUtils.h`
|
||||
|
||||
## 签名
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h`
|
||||
**头文件**: `XCEngine/Rendering/Materials/RenderMaterialStateUtils.h`
|
||||
|
||||
## 签名
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h`
|
||||
**头文件**: `XCEngine/Rendering/Materials/RenderMaterialStateUtils.h`
|
||||
|
||||
## 签名
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h`
|
||||
**头文件**: `XCEngine/Rendering/Materials/RenderMaterialStateUtils.h`
|
||||
|
||||
## 签名
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
**类型**: `function`
|
||||
|
||||
**头文件**: `XCEngine/Rendering/RenderMaterialUtility.h`
|
||||
**头文件**: `XCEngine/Rendering/Materials/RenderMaterialStateUtils.h`
|
||||
|
||||
## 签名
|
||||
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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)
|
||||
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user