docs(api): finish volume and volumetric pass coverage
This commit is contained in:
@@ -19,7 +19,6 @@
|
||||
- [RenderSceneData](RenderSceneData/RenderSceneData.md)
|
||||
- [VisibleRenderItem](VisibleRenderItem/VisibleRenderItem.md)
|
||||
- [VisibleVolumeItem](VisibleVolumeItem/VisibleVolumeItem.md)
|
||||
- [VisibleVolumeItem](VisibleVolumeItem/VisibleVolumeItem.md)
|
||||
|
||||
## 当前职责
|
||||
|
||||
@@ -28,7 +27,6 @@
|
||||
- 承载主方向光、阴影和 additional lights 快照
|
||||
- 承载 scene extraction 之后的 `visibleItems`
|
||||
- 承载 scene extraction 之后的 `visibleVolumes`
|
||||
- 承载 scene extraction 之后的 `visibleVolumes`
|
||||
|
||||
## 相关文档
|
||||
|
||||
|
||||
@@ -6,38 +6,49 @@
|
||||
|
||||
**头文件**: `XCEngine/Rendering/FrameData/VisibleVolumeItem.h`
|
||||
|
||||
**描述**: scene extraction 之后交给体积渲染阶段消费的一条可见体积记录，已经带上体积组件、体积资源、材质、渲染队列、相机距离和世界变换。
|
||||
**描述**: scene extraction 之后交给体积渲染阶段消费的一条可见体积记录，已经带上组件、资源、渲染队列、相机距离和世界变换。
|
||||
|
||||
## 字段
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| `gameObject` | 来源场景对象。 |
|
||||
| `volumeRenderer` | 提供体积资源与阴影标志的组件。 |
|
||||
| `volumeField` | 当前解析出的体积资源。 |
|
||||
| `material` | 当前解析出的材质指针，可为空。 |
|
||||
| `renderQueue` | 当前体积项的渲染队列。 |
|
||||
| `cameraDistanceSq` | 到当前相机的距离平方。 |
|
||||
| `localToWorld` | 当前体积项的世界变换。 |
|
||||
| `gameObject` | 来源场景对象 |
|
||||
| `volumeRenderer` | 提供体积资源与阴影标志的组件 |
|
||||
| `volumeField` | 当前要渲染的体积资源 |
|
||||
| `material` | 当前体积对象使用的材质 |
|
||||
| `renderQueue` | 当前体积对象的渲染队列 |
|
||||
| `cameraDistanceSq` | 到当前相机的距离平方 |
|
||||
| `localToWorld` | 当前体积对象的世界变换 |
|
||||
|
||||
## 当前语义
|
||||
|
||||
- 只有对象上存在有效 [VolumeRendererComponent](../../../Components/VolumeRendererComponent/VolumeRendererComponent.md) 且体积资源可解析时，scene extraction 才会生成这条记录。
|
||||
- opaque / transparent 的排序规则同样会消费 `renderQueue` 与 `cameraDistanceSq`。
|
||||
- 这条记录与 [VisibleRenderItem](../VisibleRenderItem/VisibleRenderItem.md) 平行存在，前者服务体积链路，后者服务 mesh 链路。
|
||||
- 同一个 `GameObject` 至多展开成一条 `VisibleVolumeItem`，不像网格那样会按 section 细分。
|
||||
- `renderQueue` 与 `cameraDistanceSq` 当前会参与稳定排序：
|
||||
- opaque 队列按近到远
|
||||
- transparent 队列按远到近
|
||||
- `localToWorld` 当前直接来自 `TransformComponent::GetLocalToWorldMatrix()`，下游体积 pass 会据此构造 `model` 与 `inverseModel` 常量。
|
||||
|
||||
## 当前调用链
|
||||
## 测试与调用链
|
||||
|
||||
- `engine/src/Rendering/Extraction/RenderSceneUtility.cpp`
|
||||
- 负责构造 `VisibleVolumeItem`
|
||||
- 当前负责从 `VolumeRendererComponent` 组装本结构
|
||||
- `engine/src/Rendering/Extraction/RenderSceneExtractor.cpp`
|
||||
- 负责提取与排序 `sceneData.visibleVolumes`
|
||||
- [BuiltinVolumetricPass](../../Passes/BuiltinVolumetricPass/BuiltinVolumetricPass.md)
|
||||
- 当前消费 `visibleVolumes`
|
||||
- 当前对 `visibleVolumes` 执行稳定排序
|
||||
- `engine/src/Rendering/Passes/BuiltinVolumetricPass.cpp`
|
||||
- 当前直接消费本结构执行逐体积绘制
|
||||
- `tests/Rendering/unit/test_render_scene_extractor.cpp`
|
||||
- 覆盖可见体积提取、剔除和按 `renderQueue` 排序
|
||||
|
||||
## 当前实现边界
|
||||
|
||||
- 这是 extraction 与 execution 之间的中间结构，不负责资源生命周期。
|
||||
- 本结构不记录 GPU 资源句柄；GPU 上传由 `RenderResourceCache` 处理。
|
||||
- 当前没有额外的体积 section、LOD 或 batching 语义。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [FrameData](../FrameData.md)
|
||||
- [VisibleRenderItem](../VisibleRenderItem/VisibleRenderItem.md)
|
||||
- [RenderSceneData](../RenderSceneData/RenderSceneData.md)
|
||||
- [VolumeRendererComponent](../../../Components/VolumeRendererComponent/VolumeRendererComponent.md)
|
||||
- [BuiltinVolumetricPass](../../Passes/BuiltinVolumetricPass/BuiltinVolumetricPass.md)
|
||||
- [RenderSceneUtility](../../Extraction/RenderSceneUtility/RenderSceneUtility.md)
|
||||
|
||||
@@ -1,29 +1,18 @@
|
||||
# BuiltinVolumetricPass::BuildInputLayout
|
||||
|
||||
**命名空间**: `XCEngine::Rendering::Passes`
|
||||
|
||||
**类型**: `method`
|
||||
|
||||
**头文件**: `XCEngine/Rendering/Passes/BuiltinVolumetricPass.h`
|
||||
|
||||
## 签名
|
||||
|
||||
```cpp
|
||||
static RHI::InputLayoutDesc BuildInputLayout();
|
||||
```
|
||||
|
||||
## 作用
|
||||
返回体积绘制当前使用的顶点布局。
|
||||
|
||||
返回 `BuiltinVolumetricPass` 当前使用的顶点布局描述。
|
||||
## 当前布局
|
||||
|
||||
## 当前行为
|
||||
- `POSITION`
|
||||
- `NORMAL`
|
||||
- `TEXCOORD0`
|
||||
|
||||
- 当前布局直接基于 `Resources::StaticMeshVertex`。
|
||||
- 依次声明：
|
||||
- `POSITION`
|
||||
- `NORMAL`
|
||||
- `TEXCOORD0`
|
||||
- 说明体积 pass 当前复用静态网格顶点结构，而不是定义单独的体积代理顶点格式。
|
||||
这些元素都来自 `Resources::StaticMeshVertex`，说明体积 pass 当前沿用静态 mesh 顶点格式来绘制 cube proxy mesh。
|
||||
|
||||
## 相关文档
|
||||
|
||||
|
||||
@@ -6,66 +6,52 @@
|
||||
|
||||
**头文件**: `XCEngine/Rendering/Passes/BuiltinVolumetricPass.h`
|
||||
|
||||
**描述**: builtin 体积渲染 pass，消费 `RenderSceneData::visibleVolumes`，为每个可见体积解析 shader pass、管线状态、descriptor set 与 `VolumeField` GPU 资源后执行绘制。
|
||||
**描述**: 内建体积绘制 pass，使用 cube 代理网格、材质 shader pass 和体积资源描述符把可见体积绘制到当前颜色目标。
|
||||
|
||||
## 概览
|
||||
|
||||
`BuiltinVolumetricPass` 当前是体积渲染进入 builtin forward 链路的实际执行者。它不是独立的体积框架，而是围绕现有 scene-pass 体系补出的一条专用路径：
|
||||
`BuiltinVolumetricPass` 是当前体积渲染链路的核心执行器。
|
||||
它继承自 `RenderPass`，但和普通 mesh pass 相比有几处明显特点：
|
||||
|
||||
- 输入来自 `RenderSceneData::visibleVolumes`
|
||||
- 几何代理当前固定使用 builtin cube mesh
|
||||
- 资源绑定依赖 shader pass 的 builtin resource layout 解析
|
||||
- 当前只接受 `VolumeStorageKind::NanoVDB`
|
||||
- 几何始终来自 builtin cube mesh，而不是体积资源自带网格
|
||||
- 着色器必须声明 `PerObject` 与 `VolumeField` 资源绑定
|
||||
- descriptor set 与 pipeline state 会按 shader pass、材质和 volume SRV 动态缓存
|
||||
|
||||
## 当前执行流程
|
||||
|
||||
1. `Initialize(...)` / `EnsureInitialized(...)` 保证 device、backend 与 builtin cube mesh 就绪。
|
||||
2. `Execute(...)` 校验 `RenderContext`、颜色附件、深度附件和 render area。
|
||||
3. 遍历 `sceneData.visibleVolumes`。
|
||||
4. 每项调用 `DrawVisibleVolume(...)`：
|
||||
- 通过 `ResolveVolumeShaderPass(...)` 选择兼容的 volumetric shader pass
|
||||
- 通过 `GetOrCreatePassResourceLayout(...)` 创建或复用 pipeline layout
|
||||
- 通过 `GetOrCreatePipelineState(...)` 创建或复用 graphics pipeline
|
||||
- 通过 `RenderResourceCache` 获取 cube mesh 与 `VolumeField` 的 GPU 视图
|
||||
- 组装 `PerObjectConstants` 与 `LightingConstants`
|
||||
- 写 descriptor set 并提交 draw call
|
||||
1. [Initialize](Initialize.md) / `EnsureInitialized(...)` 加载 builtin cube mesh
|
||||
2. [Execute](Execute.md) 校验 `RenderSurface` 是否具备单颜色附件和深度附件
|
||||
3. 逐个遍历 `sceneData.visibleVolumes`
|
||||
4. 为每个体积解析兼容的 volumetric shader pass
|
||||
5. 构建或复用 pipeline layout、pipeline state 和动态 descriptor set
|
||||
6. 把体积 bounds、材质常量、主方向光常量与 volume SRV 绑定后提交 draw
|
||||
|
||||
## 关键资源约束
|
||||
## 关键内部状态
|
||||
|
||||
- 需要单一颜色附件和有效深度附件。
|
||||
- `BuiltinPassResourceBindingPlan` 里必须至少存在：
|
||||
- `PerObject`
|
||||
- `VolumeField`
|
||||
- 若 shader pass 还声明了 `Material`，则材质必须能提供有效的 schema constant payload。
|
||||
- 体积资源当前必须是 `NanoVDB`，否则该条目会被跳过。
|
||||
|
||||
## 当前缓存层
|
||||
|
||||
类内部当前维护三类缓存：
|
||||
|
||||
- `m_passResourceLayouts`
|
||||
- 以 `shader + passName` 为键缓存 pipeline layout 与 binding metadata
|
||||
- `m_pipelineStates`
|
||||
- 以 render state、shader、keyword signature、render target format 等为键缓存 pipeline state
|
||||
- `m_dynamicDescriptorSets`
|
||||
- 以 pass-layout、set、objectId、material、volumeField 为键缓存动态 descriptor set
|
||||
| 状态 | 说明 |
|
||||
|------|------|
|
||||
| `m_builtinCubeMesh` | 所有体积绘制共用的 cube proxy mesh |
|
||||
| `m_resourceCache` | 复用 mesh 与 volume GPU 资源 |
|
||||
| `m_passResourceLayouts` | 按 shader/pass 缓存资源布局 |
|
||||
| `m_pipelineStates` | 按 render state、shader、格式与 keyword 签名缓存 pipeline |
|
||||
| `m_dynamicDescriptorSets` | 按对象、材质、volume field 缓存动态描述符集 |
|
||||
|
||||
## 当前实现边界
|
||||
|
||||
- pass 本身不负责 scene extraction，也不负责决定 `visibleVolumes` 的排序策略。
|
||||
- 当前代理几何固定为 builtin cube，而不是从体数据本身生成裁剪几何。
|
||||
- 当前 lighting constants 只消费主方向光。
|
||||
- 资源清理通过 `Shutdown()` / 析构集中处理。
|
||||
- 只处理 `VisibleVolumeItem`
|
||||
- 只接受 `VolumeStorageKind::NanoVDB`
|
||||
- 当前要求 surface 为“单颜色附件 + 深度附件”模型
|
||||
- 若 shader pass 未声明 `PerObject` 或 `VolumeField` 绑定，会直接失败而不是做 legacy fallback
|
||||
|
||||
## 公开方法
|
||||
|
||||
| 方法 | 说明 |
|
||||
|------|------|
|
||||
| [BuildInputLayout](BuildInputLayout.md) | 构建当前体积 pass 使用的顶点布局。 |
|
||||
| [GetName](GetName.md) | 返回 pass 名称。 |
|
||||
| [Initialize](Initialize.md) | 预热 device/backend 相关资源。 |
|
||||
| [Execute](Execute.md) | 遍历 `visibleVolumes` 并提交绘制。 |
|
||||
| [Shutdown](Shutdown.md) | 销毁缓存的管线、descriptor 与资源状态。 |
|
||||
| [BuildInputLayout](BuildInputLayout.md) | 返回体积 pass 使用的顶点布局 |
|
||||
| [GetName](GetName.md) | 返回 pass 名称 |
|
||||
| [Initialize](Initialize.md) | 预热 builtin cube mesh 等资源 |
|
||||
| [Execute](Execute.md) | 绘制所有可见体积 |
|
||||
| [Shutdown](Shutdown.md) | 销毁缓存的 RHI 资源 |
|
||||
|
||||
## 相关文档
|
||||
|
||||
|
||||
@@ -1,31 +1,24 @@
|
||||
# BuiltinVolumetricPass::Execute
|
||||
|
||||
**命名空间**: `XCEngine::Rendering::Passes`
|
||||
|
||||
**类型**: `method`
|
||||
|
||||
**头文件**: `XCEngine/Rendering/Passes/BuiltinVolumetricPass.h`
|
||||
|
||||
## 签名
|
||||
|
||||
```cpp
|
||||
bool Execute(const RenderPassContext& context) override;
|
||||
```
|
||||
|
||||
## 作用
|
||||
把 `context.sceneData.visibleVolumes` 中的体积绘制到当前 render target。
|
||||
|
||||
遍历 `visibleVolumes`，为每个可见体积提交一次 volumetric draw。
|
||||
## 当前实现流程
|
||||
|
||||
## 当前行为
|
||||
1. 校验 `renderContext`
|
||||
2. 若 `visibleVolumes` 为空，直接返回 `true`
|
||||
3. 要求 surface 具备单颜色附件、深度附件和有效 render area
|
||||
4. 设置 viewport、scissor 和 triangle-list topology
|
||||
5. 逐个调用内部 `DrawVisibleVolume(...)`
|
||||
|
||||
- `renderContext` 无效时返回 `false`。
|
||||
- `visibleVolumes` 为空时直接返回 `true`，表示“没有工作但不算失败”。
|
||||
- 要求：
|
||||
- 单一颜色附件
|
||||
- 非空深度附件
|
||||
- 正常的 `renderArea`
|
||||
- 会设置 render target、viewport、scissor 和三角形拓扑。
|
||||
- 最终逐项调用内部 `DrawVisibleVolume(...)`。
|
||||
## 关键语义
|
||||
|
||||
- 这里不负责 scene extraction；输入必须已经是 `VisibleVolumeItem`
|
||||
- 体积绘制依赖材质 shader pass 与 volume SRV 都已可用
|
||||
- 某个体积绘制失败不会自动切换为其他 shader 或 fallback path
|
||||
|
||||
## 相关文档
|
||||
|
||||
|
||||
@@ -1,24 +1,10 @@
|
||||
# BuiltinVolumetricPass::GetName
|
||||
|
||||
**命名空间**: `XCEngine::Rendering::Passes`
|
||||
|
||||
**类型**: `method`
|
||||
|
||||
**头文件**: `XCEngine/Rendering/Passes/BuiltinVolumetricPass.h`
|
||||
|
||||
## 签名
|
||||
|
||||
```cpp
|
||||
const char* GetName() const override;
|
||||
```
|
||||
|
||||
## 作用
|
||||
|
||||
返回当前 pass 的稳定名称。
|
||||
|
||||
## 当前行为
|
||||
|
||||
- 固定返回 `"BuiltinVolumetricPass"`。
|
||||
返回固定名称 `BuiltinVolumetricPass`。
|
||||
|
||||
## 相关文档
|
||||
|
||||
|
||||
@@ -1,28 +1,18 @@
|
||||
# BuiltinVolumetricPass::Initialize
|
||||
|
||||
**命名空间**: `XCEngine::Rendering::Passes`
|
||||
|
||||
**类型**: `method`
|
||||
|
||||
**头文件**: `XCEngine/Rendering/Passes/BuiltinVolumetricPass.h`
|
||||
|
||||
## 签名
|
||||
|
||||
```cpp
|
||||
bool Initialize(const RenderContext& context) override;
|
||||
```
|
||||
|
||||
## 作用
|
||||
|
||||
预热当前 device/backend 相关资源。
|
||||
预热体积 pass 依赖的基础资源。
|
||||
|
||||
## 当前行为
|
||||
|
||||
- 直接转发到内部 `EnsureInitialized(context)`。
|
||||
- 若 device/backend 变化，旧缓存会先被 `DestroyResources()` 清掉，再重新创建。
|
||||
- 当前初始化阶段最关键的资源是 builtin cube mesh。
|
||||
- 实际入口会转到内部 `EnsureInitialized(...)`
|
||||
- 当前最关键的初始化工作是加载 builtin cube mesh
|
||||
- 若 `RenderContext` 无效或 cube mesh 加载失败，返回 `false`
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [BuiltinVolumetricPass](BuiltinVolumetricPass.md)
|
||||
- [Shutdown](Shutdown.md)
|
||||
- [Execute](Execute.md)
|
||||
|
||||
@@ -1,33 +1,19 @@
|
||||
# BuiltinVolumetricPass::Shutdown
|
||||
|
||||
**命名空间**: `XCEngine::Rendering::Passes`
|
||||
|
||||
**类型**: `method`
|
||||
|
||||
**头文件**: `XCEngine/Rendering/Passes/BuiltinVolumetricPass.h`
|
||||
|
||||
## 签名
|
||||
|
||||
```cpp
|
||||
void Shutdown() override;
|
||||
```
|
||||
|
||||
## 作用
|
||||
|
||||
销毁 `BuiltinVolumetricPass` 当前持有的缓存资源。
|
||||
销毁体积 pass 缓存的 GPU 资源与运行时状态。
|
||||
|
||||
## 当前行为
|
||||
|
||||
- 转发到 `DestroyResources()`。
|
||||
- 会清理：
|
||||
- `RenderResourceCache`
|
||||
- 所有 pipeline state
|
||||
- 所有动态 descriptor set
|
||||
- 所有 pass resource layout
|
||||
- builtin cube mesh 句柄
|
||||
- 最后把 device/backend 状态恢复到初始值。
|
||||
- 关闭 `RenderResourceCache`
|
||||
- 释放缓存的 pipeline state
|
||||
- 释放动态 descriptor set 与 pool
|
||||
- 释放按 shader pass 建立的 pipeline layout / set layout 元数据
|
||||
- 清空 builtin cube mesh 句柄
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [BuiltinVolumetricPass](BuiltinVolumetricPass.md)
|
||||
- [Initialize](Initialize.md)
|
||||
|
||||
Reference in New Issue
Block a user