docs: add second-round api structure refactor plan
This commit is contained in:
@@ -42,6 +42,7 @@
|
||||
| [AssetReferenceEditorUtils](AssetReferenceEditorUtils/AssetReferenceEditorUtils.md) | 资产引用属性行 helper。 |
|
||||
| [MeshFilterComponentEditor](MeshFilterComponentEditor/MeshFilterComponentEditor.md) | MeshFilter 组件 Inspector。 |
|
||||
| [MeshRendererComponentEditor](MeshRendererComponentEditor/MeshRendererComponentEditor.md) | MeshRenderer 组件 Inspector。 |
|
||||
| [VolumeRendererComponentEditor](VolumeRendererComponentEditor/VolumeRendererComponentEditor.md) | VolumeRenderer 组件 Inspector。 |
|
||||
| [ScriptComponentEditor](ScriptComponentEditor/ScriptComponentEditor.md) | Script 组件 Inspector 与脚本字段编辑入口。 |
|
||||
| [ScriptComponentEditorUtils](ScriptComponentEditorUtils/ScriptComponentEditorUtils.md) | 脚本组件编辑器辅助规则与格式化 helper。 |
|
||||
|
||||
@@ -54,9 +55,10 @@
|
||||
- `LightComponentEditor`
|
||||
- `MeshFilterComponentEditor`
|
||||
- `MeshRendererComponentEditor`
|
||||
- `VolumeRendererComponentEditor`
|
||||
- `ScriptComponentEditor`
|
||||
|
||||
这说明当前组件编辑器系统已经不再只覆盖基础三组件，而是已经承载渲染组件和脚本组件的 Inspector 逻辑。当前 canonical 树已经把渲染组件 editor、脚本组件 editor 和它们共用的资产引用 helper 都补齐了。
|
||||
这说明当前组件编辑器系统已经不再只覆盖基础三组件，而是已经承载 mesh、volume 与脚本组件的 Inspector 逻辑。当前 canonical 树已经把这些渲染组件 editor、脚本组件 editor 和它们共用的资产引用 helper 都补齐了。
|
||||
|
||||
## ScriptComponentEditor 的特殊性
|
||||
|
||||
|
||||
@@ -0,0 +1,71 @@
|
||||
# VolumeRendererComponentEditor
|
||||
|
||||
**命名空间**: `XCEngine::Editor`
|
||||
|
||||
**类型**: `class`
|
||||
|
||||
**源文件**: `editor/src/ComponentEditors/VolumeRendererComponentEditor.h`
|
||||
|
||||
**描述**: `VolumeRendererComponent` 的 Inspector editor，负责绘制体积资源引用、材质引用以及阴影开关。
|
||||
|
||||
## 概述
|
||||
|
||||
`VolumeRendererComponentEditor` 当前是内联定义在头文件里的轻量 editor，实现方式与其他 `ComponentEditor` 一致：
|
||||
|
||||
1. 由 `ComponentEditorRegistry` 注册
|
||||
2. 在 `InspectorPanel` 渲染组件 section 时被查到
|
||||
3. 直接通过 `UI::ApplyPropertyChange(...)` 把修改包进 undo 标签
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
### 资源引用编辑
|
||||
|
||||
- `Volume Field`
|
||||
- 通过 `ComponentEditorAssetUI::DrawAssetReferenceProperty(...)` 绘制
|
||||
- 当前接受扩展名 `.nvdb`
|
||||
- 清除时调用 `VolumeRendererComponent::ClearVolumeField()`
|
||||
- 赋值时调用 `SetVolumeFieldPath(...)`
|
||||
- `Material`
|
||||
- 同样使用 `DrawAssetReferenceProperty(...)`
|
||||
- 当前接受扩展名 `.mat`
|
||||
- 清除时调用 `ClearMaterial()`
|
||||
- 赋值时调用 `SetMaterialPath(...)`
|
||||
|
||||
### 布尔属性
|
||||
|
||||
- `Cast Shadows`
|
||||
- `Receive Shadows`
|
||||
|
||||
这两个布尔值都通过 `UI::DrawPropertyBool(...)` 与 `UI::ApplyPropertyChange(...)` 包装到统一 undo 标签：
|
||||
|
||||
- `Modify Volume Renderer`
|
||||
|
||||
### 添加与移除规则
|
||||
|
||||
- `CanAddTo(...)`
|
||||
- 只有目标 `GameObject` 还没有 `VolumeRendererComponent` 时才允许添加
|
||||
- `GetAddDisabledReason(...)`
|
||||
- `nullptr` `GameObject` 返回 `"Invalid"`
|
||||
- 已存在组件返回 `"Already Added"`
|
||||
- `CanRemove(...)`
|
||||
- 当前直接复用 `CanEdit(...)`
|
||||
|
||||
## 测试与调用链
|
||||
|
||||
- `editor/src/ComponentEditors/ComponentEditorRegistry.cpp`
|
||||
- 当前把本 editor 注册进全局 registry
|
||||
- `editor/src/panels/InspectorPanel.cpp`
|
||||
- 当前通过 registry 查找并渲染本 editor
|
||||
|
||||
## 当前实现边界
|
||||
|
||||
- 当前没有独立单元测试，行为主要通过 registry 和 Inspector 实际渲染链验证。
|
||||
- 这是 editor-only UI 适配层，不保存状态；真正的数据写回都落在 `VolumeRendererComponent`。
|
||||
- 当前资源过滤只按扩展名限制，不负责进一步校验材质/体积内容是否合法。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [ComponentEditors](../ComponentEditors.md)
|
||||
- [ComponentEditorRegistry](../ComponentEditorRegistry/ComponentEditorRegistry.md)
|
||||
- [VolumeRendererComponent](../../../Components/VolumeRendererComponent/VolumeRendererComponent.md)
|
||||
- [InspectorPanel](../../panels/InspectorPanel/InspectorPanel.md)
|
||||
@@ -0,0 +1,11 @@
|
||||
# BuiltinSelectionMaskPass::BuildInputLayout
|
||||
|
||||
```cpp
|
||||
static RHI::InputLayoutDesc BuildInputLayout();
|
||||
```
|
||||
|
||||
返回 selection-mask pass 的顶点布局。当前直接复用基类 `BuildCommonInputLayout()`。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [BuiltinSelectionMaskPass](BuiltinSelectionMaskPass.md)
|
||||
@@ -0,0 +1,40 @@
|
||||
# BuiltinSelectionMaskPass
|
||||
|
||||
**命名空间**: `XCEngine::Rendering::Passes`
|
||||
|
||||
**类型**: `class`
|
||||
|
||||
**头文件**: `XCEngine/Rendering/Passes/BuiltinSelectionMaskPass.h`
|
||||
|
||||
**描述**: 选择遮罩 pass，在深度风格重绘框架上只重绘被选中对象，并把结果写入 selection mask 目标。
|
||||
|
||||
## 概览
|
||||
|
||||
`BuiltinSelectionMaskPass` 继承自 [BuiltinDepthStylePassBase](../BuiltinDepthStylePassBase/BuiltinDepthStylePassBase.md)。
|
||||
它不重新实现整套场景重绘框架，而是只增加“按选中对象过滤”的那层语义：
|
||||
|
||||
- 外部传入 `selectedObjectIds`
|
||||
- pass 内部记录到 `m_selectedObjectIds`
|
||||
- `ShouldRenderVisibleItem(...)` 只让被选中的对象通过
|
||||
|
||||
## 当前流程
|
||||
|
||||
1. [Render](Render.md) 记录选中对象 id 列表
|
||||
2. 若列表为空，直接返回 `false`
|
||||
3. 复制 `sceneData`，把 clear flags 改为纯颜色清屏且清为黑色
|
||||
4. 组装 `RenderPassContext`
|
||||
5. 调用基类 `Execute(...)`
|
||||
|
||||
## 公开方法
|
||||
|
||||
| 方法 | 说明 |
|
||||
|------|------|
|
||||
| [BuildInputLayout](BuildInputLayout.md) | 复用深度风格 pass 的通用顶点布局 |
|
||||
| [GetName](GetName.md) | 返回 `BuiltinSelectionMaskPass` |
|
||||
| [Render](Render.md) | 只重绘选中对象到 selection mask |
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [Passes](../Passes.md)
|
||||
- [BuiltinDepthStylePassBase](../BuiltinDepthStylePassBase/BuiltinDepthStylePassBase.md)
|
||||
- [BuiltinSelectionOutlinePass](../BuiltinSelectionOutlinePass/BuiltinSelectionOutlinePass.md)
|
||||
@@ -0,0 +1,11 @@
|
||||
# BuiltinSelectionMaskPass::GetName
|
||||
|
||||
```cpp
|
||||
const char* GetName() const override;
|
||||
```
|
||||
|
||||
返回固定名称 `BuiltinSelectionMaskPass`。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [BuiltinSelectionMaskPass](BuiltinSelectionMaskPass.md)
|
||||
@@ -0,0 +1,25 @@
|
||||
# BuiltinSelectionMaskPass::Render
|
||||
|
||||
```cpp
|
||||
bool Render(
|
||||
const RenderContext& context,
|
||||
const RenderSurface& surface,
|
||||
const RenderSceneData& sceneData,
|
||||
const std::vector<uint64_t>& selectedObjectIds);
|
||||
```
|
||||
|
||||
把当前选中对象重绘到 selection mask render target。
|
||||
|
||||
## 当前实现流程
|
||||
|
||||
1. 保存 `selectedObjectIds`
|
||||
2. 若选中列表为空，返回 `false`
|
||||
3. 复制输入 `sceneData`
|
||||
4. 把 `cameraData.clearFlags` 改为 `RenderClearFlags::Color`
|
||||
5. 把 clear color 固定为黑色
|
||||
6. 调用基类 `Execute(...)`
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [BuiltinSelectionMaskPass](BuiltinSelectionMaskPass.md)
|
||||
- [BuiltinSelectionOutlinePass](../BuiltinSelectionOutlinePass/BuiltinSelectionOutlinePass.md)
|
||||
@@ -0,0 +1,60 @@
|
||||
# BuiltinSelectionOutlinePass
|
||||
|
||||
**命名空间**: `XCEngine::Rendering::Passes`
|
||||
|
||||
**类型**: `class`
|
||||
|
||||
**头文件**: `XCEngine/Rendering/Passes/BuiltinSelectionOutlinePass.h`
|
||||
|
||||
**描述**: 基于 selection mask 与 depth 纹理执行的全屏轮廓 pass，用于把选中描边叠加回主颜色目标。
|
||||
|
||||
## 概览
|
||||
|
||||
`BuiltinSelectionOutlinePass` 与 `BuiltinSelectionMaskPass` 分工明确：
|
||||
|
||||
- mask pass 负责把选中对象重绘成二值 mask
|
||||
- outline pass 负责读取 mask 与 depth，执行一次全屏三角形轮廓合成
|
||||
|
||||
它不是 `RenderPass` 子类，而是一个自管理资源的独立 helper。
|
||||
|
||||
## 当前执行流程
|
||||
|
||||
1. [Render](Render.md) 校验 render context、mask view、depth view 和 surface
|
||||
2. `EnsureInitialized(...)` 按后端、render target 格式和采样数准备 pipeline 资源
|
||||
3. 写入 outline 常量
|
||||
4. 更新 selection mask / depth 的 SRV 绑定
|
||||
5. 视情况做资源状态切换
|
||||
6. 绘制一次全屏三角形并恢复资源状态
|
||||
|
||||
## 关键资源
|
||||
|
||||
| 资源 | 说明 |
|
||||
|------|------|
|
||||
| `m_pipelineLayout` / `m_pipelineState` | 全屏 outline pass 的 pipeline |
|
||||
| `m_constantPool` / `m_constantSet` | outline 常量缓冲 |
|
||||
| `m_texturePool` / `m_textureSet` | selection mask 与 depth SRV |
|
||||
| `m_shaderPath` | 当前使用的 selection-outline shader 路径 |
|
||||
|
||||
## 当前实现边界
|
||||
|
||||
- 只支持单颜色附件输出
|
||||
- 当前不写深度
|
||||
- 输出样式由 [SelectionOutlineStyle](../SelectionOutlineStyle/SelectionOutlineStyle.md) 控制
|
||||
- 输入纹理来源由 [SelectionOutlinePassInputs](../SelectionOutlinePassInputs/SelectionOutlinePassInputs.md) 描述
|
||||
|
||||
## 公开方法
|
||||
|
||||
| 方法 | 说明 |
|
||||
|------|------|
|
||||
| [Constructor](Constructor.md) | 创建 pass，可注入 shader 路径 |
|
||||
| [SetShaderPath](SetShaderPath.md) | 更新 shader 路径并清空已创建资源 |
|
||||
| [GetShaderPath](GetShaderPath.md) | 返回当前 shader 路径 |
|
||||
| [Render](Render.md) | 执行全屏描边合成 |
|
||||
| [Shutdown](Shutdown.md) | 销毁内部 RHI 资源 |
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [Passes](../Passes.md)
|
||||
- [BuiltinSelectionMaskPass](../BuiltinSelectionMaskPass/BuiltinSelectionMaskPass.md)
|
||||
- [SelectionOutlineStyle](../SelectionOutlineStyle/SelectionOutlineStyle.md)
|
||||
- [SelectionOutlinePassInputs](../SelectionOutlinePassInputs/SelectionOutlinePassInputs.md)
|
||||
@@ -0,0 +1,17 @@
|
||||
# BuiltinSelectionOutlinePass::BuiltinSelectionOutlinePass
|
||||
|
||||
```cpp
|
||||
explicit BuiltinSelectionOutlinePass(Containers::String shaderPath = Containers::String());
|
||||
```
|
||||
|
||||
创建 selection outline pass。
|
||||
|
||||
## 当前语义
|
||||
|
||||
- 若传入空路径，默认回退到内建 selection-outline shader 路径
|
||||
- 构造后会立即调用内部 `ResetState()`
|
||||
- 资源真正创建发生在第一次 `Render(...)` 或后续 `EnsureInitialized(...)`
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [BuiltinSelectionOutlinePass](BuiltinSelectionOutlinePass.md)
|
||||
@@ -0,0 +1,12 @@
|
||||
# BuiltinSelectionOutlinePass::GetShaderPath
|
||||
|
||||
```cpp
|
||||
const Containers::String& GetShaderPath() const;
|
||||
```
|
||||
|
||||
返回当前记录的 selection-outline shader 路径。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [BuiltinSelectionOutlinePass](BuiltinSelectionOutlinePass.md)
|
||||
- [SetShaderPath](SetShaderPath.md)
|
||||
@@ -0,0 +1,27 @@
|
||||
# BuiltinSelectionOutlinePass::Render
|
||||
|
||||
```cpp
|
||||
bool Render(
|
||||
const RenderContext& renderContext,
|
||||
const RenderSurface& surface,
|
||||
const SelectionOutlinePassInputs& inputs,
|
||||
const SelectionOutlineStyle& style = {});
|
||||
```
|
||||
|
||||
读取 selection mask 与 depth，并把轮廓叠加回 `surface` 的主颜色目标。
|
||||
|
||||
## 当前实现流程
|
||||
|
||||
1. 校验 render context、mask/depth 纹理与 surface
|
||||
2. `EnsureInitialized(...)`
|
||||
3. 构建 `OutlineConstants`
|
||||
4. 写入常量并更新两个 SRV
|
||||
5. 自动状态切换开启时，把目标切到 `RenderTarget`、输入切到 `PixelShaderResource`
|
||||
6. 绑定两个 descriptor set，执行一次 `Draw(3, 1, 0, 0)`
|
||||
7. 恢复资源状态
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [BuiltinSelectionOutlinePass](BuiltinSelectionOutlinePass.md)
|
||||
- [SelectionOutlinePassInputs](../SelectionOutlinePassInputs/SelectionOutlinePassInputs.md)
|
||||
- [SelectionOutlineStyle](../SelectionOutlineStyle/SelectionOutlineStyle.md)
|
||||
@@ -0,0 +1,18 @@
|
||||
# BuiltinSelectionOutlinePass::SetShaderPath
|
||||
|
||||
```cpp
|
||||
void SetShaderPath(const Containers::String& shaderPath);
|
||||
```
|
||||
|
||||
更新 selection-outline shader 路径。
|
||||
|
||||
## 当前行为
|
||||
|
||||
- 若新旧路径相同，直接返回
|
||||
- 若路径发生变化，会先销毁已创建的 pipeline / descriptor 等资源
|
||||
- 后续首次 `Render(...)` 会按新路径重新初始化
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [BuiltinSelectionOutlinePass](BuiltinSelectionOutlinePass.md)
|
||||
- [GetShaderPath](GetShaderPath.md)
|
||||
@@ -0,0 +1,18 @@
|
||||
# BuiltinSelectionOutlinePass::Shutdown
|
||||
|
||||
```cpp
|
||||
void Shutdown();
|
||||
```
|
||||
|
||||
主动销毁 selection outline pass 已创建的 RHI 资源。
|
||||
|
||||
## 当前行为
|
||||
|
||||
- 释放 pipeline state、pipeline layout
|
||||
- 释放常量与纹理 descriptor pool / set
|
||||
- 清空已加载 shader 句柄
|
||||
- 重置缓存的 render target 格式与采样数
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [BuiltinSelectionOutlinePass](BuiltinSelectionOutlinePass.md)
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
**类型**: `submodule`
|
||||
|
||||
**描述**: 承载 builtin object-id、selection outline、infinite grid、fullscreen post-process / final-color，以及 depth-only / shadow-caster 一类可复用渲染 pass 与配套参数类型。
|
||||
**描述**: 承载 builtin object-id、selection mask / outline、volumetric、infinite grid、fullscreen post-process / final-color，以及 depth-only / shadow-caster 一类可复用渲染 pass 与配套参数类型。
|
||||
|
||||
## 概览
|
||||
|
||||
@@ -12,7 +12,10 @@
|
||||
|
||||
- [BuiltinObjectIdPass](BuiltinObjectIdPass/BuiltinObjectIdPass.md) 把可见物体编码成 object-id 颜色，写到辅助渲染目标。
|
||||
- [BuiltinObjectIdOutlinePass](BuiltinObjectIdOutlinePass/BuiltinObjectIdOutlinePass.md) 读取 object-id 纹理和选中对象列表，把轮廓或调试 mask 叠加回场景颜色。
|
||||
- [BuiltinSelectionMaskPass](BuiltinSelectionMaskPass/BuiltinSelectionMaskPass.md) 重绘当前选中对象，生成 selection mask。
|
||||
- [BuiltinSelectionOutlinePass](BuiltinSelectionOutlinePass/BuiltinSelectionOutlinePass.md) 读取 selection-mask 与 depth 纹理，在主颜色目标上合成轮廓。
|
||||
- [BuiltinInfiniteGridPass](BuiltinInfiniteGridPass/BuiltinInfiniteGridPass.md) 给 Scene View 一类编辑器视口叠加无限网格。
|
||||
- [BuiltinVolumetricPass](BuiltinVolumetricPass/BuiltinVolumetricPass.md) 消费 `visibleVolumes` 与 `VolumeField` GPU 资源，执行体渲染。
|
||||
- [BuiltinColorScalePostProcessPass](BuiltinColorScalePostProcessPass/BuiltinColorScalePostProcessPass.md) 执行基于 `sourceColorView` 的全屏颜色缩放后处理。
|
||||
- [BuiltinFinalColorPass](BuiltinFinalColorPass/BuiltinFinalColorPass.md) 执行 exposure、tone mapping、output transfer 和 final color scale 的最终输出阶段。
|
||||
- [BuiltinDepthStylePassBase](BuiltinDepthStylePassBase/BuiltinDepthStylePassBase.md) 为深度风格场景重绘 pass 提供共享执行骨架。
|
||||
@@ -28,7 +31,7 @@
|
||||
1. [CameraRenderer](../CameraRenderer/CameraRenderer.md) 先执行主 `RenderPipeline`。
|
||||
2. 如果 [CameraRenderRequest](../CameraRenderRequest/CameraRenderRequest.md) 里请求了 `objectId.surface`，则额外执行 [BuiltinObjectIdPass](BuiltinObjectIdPass/BuiltinObjectIdPass.md)。
|
||||
3. editor 侧的 `SceneViewportRenderPlan` 再构建 `postScenePasses` 和 `overlayPasses`。
|
||||
4. 其中 `SceneViewportGridPass` / `SceneViewportSelectionOutlinePass` 最终分别调用 [BuiltinInfiniteGridPass](BuiltinInfiniteGridPass/BuiltinInfiniteGridPass.md) 和 [BuiltinObjectIdOutlinePass](BuiltinObjectIdOutlinePass/BuiltinObjectIdOutlinePass.md)。
|
||||
4. 其中 `SceneViewportGridPass` / `SceneViewportSelectionOutlinePass` 当前分别调用 [BuiltinInfiniteGridPass](BuiltinInfiniteGridPass/BuiltinInfiniteGridPass.md) 与“[BuiltinSelectionMaskPass](BuiltinSelectionMaskPass/BuiltinSelectionMaskPass.md) + [BuiltinSelectionOutlinePass](BuiltinSelectionOutlinePass/BuiltinSelectionOutlinePass.md)”这一组 selection outline 组合。
|
||||
|
||||
### Fullscreen post-process / final-color
|
||||
|
||||
@@ -48,13 +51,24 @@
|
||||
4. `postScenePasses`
|
||||
5. `overlayPasses`
|
||||
|
||||
### Builtin volume scene pass
|
||||
|
||||
体渲染链路和前面两类流程不同，它不是 post-process，而是 builtin scene pass：
|
||||
|
||||
1. `RenderSceneExtractor` 先把体积对象提取到 `visibleVolumes`。
|
||||
2. [BuiltinForwardPipeline](../Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md) 把 [BuiltinVolumetricPass](BuiltinVolumetricPass/BuiltinVolumetricPass.md) 放进自己的 pass sequence。
|
||||
3. `BuiltinVolumetricPass` 再按材质 shader pass、volume-field 绑定和 lighting 常量逐项绘制。
|
||||
|
||||
## 当前公开概念
|
||||
|
||||
| 类型 / 页面 | 角色 |
|
||||
|------|------|
|
||||
| [BuiltinObjectIdPass](BuiltinObjectIdPass/BuiltinObjectIdPass.md) | 生成 object-id 颜色缓冲。 |
|
||||
| [BuiltinObjectIdOutlinePass](BuiltinObjectIdOutlinePass/BuiltinObjectIdOutlinePass.md) | 在主颜色目标上合成选中轮廓。 |
|
||||
| [BuiltinSelectionMaskPass](BuiltinSelectionMaskPass/BuiltinSelectionMaskPass.md) | 为选中轮廓链路生成 selection mask。 |
|
||||
| [BuiltinSelectionOutlinePass](BuiltinSelectionOutlinePass/BuiltinSelectionOutlinePass.md) | 基于 selection-mask 与 depth 的全屏轮廓合成器。 |
|
||||
| [BuiltinInfiniteGridPass](BuiltinInfiniteGridPass/BuiltinInfiniteGridPass.md) | Scene View 网格覆盖层的底层执行 pass。 |
|
||||
| [BuiltinVolumetricPass](BuiltinVolumetricPass/BuiltinVolumetricPass.md) | builtin forward 链路中的体渲染 scene pass。 |
|
||||
| [BuiltinColorScalePostProcessPass](BuiltinColorScalePostProcessPass/BuiltinColorScalePostProcessPass.md) | 相机 post-process 栈当前的颜色缩放全屏 pass。 |
|
||||
| [BuiltinFinalColorPass](BuiltinFinalColorPass/BuiltinFinalColorPass.md) | final-color 阶段的最终合成 / 输出变换 pass。 |
|
||||
| [BuiltinDepthStylePassBase](BuiltinDepthStylePassBase/BuiltinDepthStylePassBase.md) | depth-only / shadow-caster 场景重绘共享的执行骨架。 |
|
||||
@@ -66,19 +80,27 @@
|
||||
- `tests/Rendering/unit/test_camera_scene_renderer.cpp` 验证了 `CameraRenderer` 里 object-id、post-process、final-output 与可选 pass sequence 的接入时机。
|
||||
- `engine/src/Rendering/Execution/CameraRenderer.cpp` 当前把 [BuiltinShadowCasterPass](BuiltinShadowCasterPass/BuiltinShadowCasterPass.md) 与 [BuiltinDepthOnlyPass](BuiltinDepthOnlyPass/BuiltinDepthOnlyPass.md) 作为默认 scene pass 挂进 `shadowCaster` / `depthOnly` request。
|
||||
- `engine/src/Rendering/Execution/SceneRenderer.cpp` 当前负责把 fullscreen 阶段写进 `CameraRenderRequest`。
|
||||
- `editor/src/Viewport/Passes/SceneViewportSelectionOutlinePass.h` 当前组合 [BuiltinSelectionMaskPass](BuiltinSelectionMaskPass/BuiltinSelectionMaskPass.md) 与 [BuiltinSelectionOutlinePass](BuiltinSelectionOutlinePass/BuiltinSelectionOutlinePass.md)。
|
||||
- `engine/src/Rendering/Pipelines/BuiltinForwardPipeline.cpp` 当前把 [BuiltinVolumetricPass](BuiltinVolumetricPass/BuiltinVolumetricPass.md) 挂进 builtin forward pass sequence。
|
||||
- `tests/Rendering/unit/test_builtin_forward_pipeline.cpp` 验证了 `VolumeField` 资源语义与布局元数据。
|
||||
- `tests/Editor/test_viewport_render_flow_utils.cpp` 验证了 Scene View render plan 如何组装 grid / selection outline / overlay pass。
|
||||
|
||||
## 当前实现边界
|
||||
|
||||
- 这一层目前是 builtin、轻量、偏 editor/工具链导向的 pass 集合，还不是通用 render graph。
|
||||
- object-id 相关流程依赖单独的辅助 render target / shader resource view，而不是直接从主颜色结果反推。
|
||||
- selection outline 当前已经拆成“mask 重绘 + fullscreen compositing”两层，而不是单个对象列表后处理。
|
||||
- volumetric pass 当前依赖 `visibleVolumes`、`VolumeField` 资源绑定和 builtin cube proxy，不是独立 volume framework。
|
||||
- fullscreen pass 依赖调用方准备 `sourceColorView` 和中间表面；单个 pass 本身不管理整条阶段链。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [BuiltinObjectIdPass](BuiltinObjectIdPass/BuiltinObjectIdPass.md)
|
||||
- [BuiltinObjectIdOutlinePass](BuiltinObjectIdOutlinePass/BuiltinObjectIdOutlinePass.md)
|
||||
- [BuiltinSelectionMaskPass](BuiltinSelectionMaskPass/BuiltinSelectionMaskPass.md)
|
||||
- [BuiltinSelectionOutlinePass](BuiltinSelectionOutlinePass/BuiltinSelectionOutlinePass.md)
|
||||
- [BuiltinInfiniteGridPass](BuiltinInfiniteGridPass/BuiltinInfiniteGridPass.md)
|
||||
- [BuiltinVolumetricPass](BuiltinVolumetricPass/BuiltinVolumetricPass.md)
|
||||
- [BuiltinColorScalePostProcessPass](BuiltinColorScalePostProcessPass/BuiltinColorScalePostProcessPass.md)
|
||||
- [BuiltinFinalColorPass](BuiltinFinalColorPass/BuiltinFinalColorPass.md)
|
||||
- [BuiltinDepthStylePassBase](BuiltinDepthStylePassBase/BuiltinDepthStylePassBase.md)
|
||||
|
||||
@@ -0,0 +1,28 @@
|
||||
# SelectionOutlinePassInputs
|
||||
|
||||
**命名空间**: `XCEngine::Rendering::Passes`
|
||||
|
||||
**类型**: `struct`
|
||||
|
||||
**头文件**: `XCEngine/Rendering/Passes/BuiltinSelectionOutlinePass.h`
|
||||
|
||||
**描述**: selection outline pass 的输入纹理描述，指定 selection mask、depth view 及其进入 pass 前的资源状态。
|
||||
|
||||
## 字段
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| `selectionMaskTextureView` | selection mask 纹理视图 |
|
||||
| `selectionMaskState` | selection mask 当前资源状态 |
|
||||
| `depthTextureView` | 深度纹理视图 |
|
||||
| `depthTextureState` | 深度纹理当前资源状态 |
|
||||
|
||||
## 当前作用
|
||||
|
||||
- 为 `BuiltinSelectionOutlinePass::Render(...)` 提供两个输入 SRV
|
||||
- 在 surface 开启自动状态切换时，提供“切入 pass 前”的原始状态以便恢复
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [BuiltinSelectionOutlinePass](../BuiltinSelectionOutlinePass/BuiltinSelectionOutlinePass.md)
|
||||
- [SelectionOutlineStyle](../SelectionOutlineStyle/SelectionOutlineStyle.md)
|
||||
@@ -0,0 +1,22 @@
|
||||
# SelectionOutlineStyle
|
||||
|
||||
**命名空间**: `XCEngine::Rendering::Passes`
|
||||
|
||||
**类型**: `struct`
|
||||
|
||||
**头文件**: `XCEngine/Rendering/Passes/BuiltinSelectionOutlinePass.h`
|
||||
|
||||
**描述**: selection outline pass 的样式配置，当前控制描边颜色、像素宽度和调试遮罩模式。
|
||||
|
||||
## 默认值
|
||||
|
||||
| 字段 | 默认值 | 说明 |
|
||||
|------|------|------|
|
||||
| `outlineColor` | `Math::Color(1.0f, 0.4f, 0.0f, 1.0f)` | 默认橙色描边 |
|
||||
| `outlineWidthPixels` | `2.0f` | 描边宽度，单位像素 |
|
||||
| `debugSelectionMask` | `false` | 默认输出描边而不是直接显示 mask |
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [BuiltinSelectionOutlinePass](../BuiltinSelectionOutlinePass/BuiltinSelectionOutlinePass.md)
|
||||
- [SelectionOutlinePassInputs](../SelectionOutlinePassInputs/SelectionOutlinePassInputs.md)
|
||||
@@ -25,7 +25,6 @@
|
||||
- [Shader](Shader/Shader.md)
|
||||
- [Texture](Texture/Texture.md)
|
||||
- [Volume](Volume/Volume.md)
|
||||
- [Volume](Volume/Volume.md)
|
||||
|
||||
## 头文件
|
||||
|
||||
|
||||
92
docs/plan/API文档目录结构第二轮并行任务板_2026-04-09.md
Normal file
92
docs/plan/API文档目录结构第二轮并行任务板_2026-04-09.md
Normal file
@@ -0,0 +1,92 @@
|
||||
# API 文档目录结构第二轮并行任务板（2026-04-09）
|
||||
|
||||
## 使用规则
|
||||
|
||||
- 每个任务块只允许一个会话领取。
|
||||
- 每个任务块必须同时处理：主页面、所属索引页、交叉链接。
|
||||
- 每完成一个任务块所在阶段，都要先审计，再提交推送。
|
||||
- 如果任务路径命中当前并发热点，先不要直接改。
|
||||
|
||||
## 当前并发热点
|
||||
|
||||
以下源码区域当前已有并发修改，相关文档任务默认标记为 `high-risk`：
|
||||
|
||||
- `editor/src/Viewport/**`
|
||||
- `engine/include/XCEngine/RHI/**`
|
||||
- `engine/include/XCEngine/Rendering/Passes/**`
|
||||
- `engine/include/XCEngine/Rendering/Materials/RenderMaterialResolve.h`
|
||||
- `engine/include/XCEngine/UI/Widgets/UISelectionModel.h`
|
||||
- `engine/include/XCEngine/UI/Widgets/UIDragDropInteraction.h`
|
||||
|
||||
## 任务块
|
||||
|
||||
| ID | 范围 | 目标改动 | 主要路径 | 风险 | 状态 | 领取人 |
|
||||
|----|------|----------|----------|------|------|--------|
|
||||
| `R1` | Rendering / 重复目录归位 | 把旧顶层 `CameraRenderer`、`SceneRenderer`、`CameraRenderRequest`、`SceneRenderRequestPlanner`、`SceneRenderRequestUtils`、`RenderCameraData`、`RenderResourceCache`、`RenderSceneExtractor`、`RenderSceneUtility` 合并到真实子模块位置 | `docs/api/XCEngine/Rendering/**` | `medium` | `pending` | |
|
||||
| `R2` | Rendering / 旧命名残留审计 | 处理 `ObjectIdEncoding`、`ObjectIdPass`、`RenderMaterialUtility`、`VisibleRenderObject`，判定迁移到哪里或删除 | `docs/api/XCEngine/Rendering/**` | `medium` | `pending` | |
|
||||
| `E1` | Editor / 历史失效页清理 | 移除或降级 `XCUIDemoPanel`，修正 `panels.md`、`ImGuiTransitionBackend.md` 等反向链接 | `docs/api/XCEngine/Editor/panels/**` | `low` | `pending` | |
|
||||
| `V1` | Resources / Volume | 建立 `Volume.md`、`VolumeField.md`、`VolumeFieldLoader.md`，同步 `Resources.md` | `docs/api/XCEngine/Resources/Volume/**` | `low` | `pending` | |
|
||||
| `V2` | Components / Volume | 建立 `VolumeRendererComponent.md`，同步 `Components.md` | `docs/api/XCEngine/Components/VolumeRendererComponent/**` | `low` | `pending` | |
|
||||
| `V3` | Rendering / Volume FrameData | 建立 `VisibleVolumeItem.md`，同步 `FrameData.md` | `docs/api/XCEngine/Rendering/FrameData/**` | `low` | `pending` | |
|
||||
| `V4` | Rendering / Volume & Selection Passes | 建立 `BuiltinSelectionMaskPass.md`、`BuiltinSelectionOutlinePass.md`、`BuiltinVolumetricPass.md`，同步 `Passes.md` | `docs/api/XCEngine/Rendering/Passes/**` | `high-risk` | `pending` | |
|
||||
| `U1` | UI / Widgets Helpers | 建立 `UIDragDropInteraction.md`、`UIScrollModel.md`，同步 `Widgets.md` | `docs/api/XCEngine/UI/Widgets/**` | `high-risk` | `pending` | |
|
||||
| `ED1` | Editor / ComponentEditors | 建立 `VolumeRendererComponentEditor.md`，同步 `ComponentEditors.md` | `docs/api/XCEngine/Editor/ComponentEditors/**` | `low` | `pending` | |
|
||||
| `ED2` | Editor / panels Material Authoring | 建立 `MaterialInspectorMaterialState.md`、`MaterialInspectorMaterialStateIO.md`，同步 `panels.md` | `docs/api/XCEngine/Editor/panels/**` | `low` | `pending` | |
|
||||
| `RR1` | RHI 内容回归 | 根据当前真实头文件更新 `RHI*`、`D3D12`、`OpenGL`、`Vulkan` 文档内容与结构 | `docs/api/XCEngine/RHI/**` | `high-risk` | `pending` | |
|
||||
| `RR2` | Rendering / Passes 内容回归 | 根据当前修改中的 builtin pass 头文件更新文档内容与链接 | `docs/api/XCEngine/Rendering/Passes/**` | `high-risk` | `pending` | |
|
||||
| `RR3` | Rendering / Materials 内容回归 | 把 `RenderMaterialResolve` 相关文档与当前头文件重新对齐 | `docs/api/XCEngine/Rendering/Materials/**` | `high-risk` | `pending` | |
|
||||
| `G1` | 全量审计与空目录清理 | 跑审计、清空旧重复目录、清理空目录与错链 | `docs/api/_meta/**`, `docs/api/XCEngine/**` | `medium` | `pending` | |
|
||||
|
||||
## 推荐阶段顺序
|
||||
|
||||
### 第一阶段
|
||||
|
||||
- `R1`
|
||||
- `R2`
|
||||
- `E1`
|
||||
|
||||
这一阶段的目标是先把“结构错位”和“失效历史页”清掉。
|
||||
|
||||
### 第二阶段
|
||||
|
||||
- `V1`
|
||||
- `V2`
|
||||
- `V3`
|
||||
- `ED1`
|
||||
- `ED2`
|
||||
|
||||
这一阶段优先补低冲突、可快速收口的缺页。
|
||||
|
||||
### 第三阶段
|
||||
|
||||
- `V4`
|
||||
- `U1`
|
||||
- `RR1`
|
||||
- `RR2`
|
||||
- `RR3`
|
||||
|
||||
这一阶段等源码波动收敛后再做。
|
||||
|
||||
### 第四阶段
|
||||
|
||||
- `G1`
|
||||
|
||||
## 验收口径
|
||||
|
||||
### 结构验收
|
||||
|
||||
- 每个 API 只保留一个 canonical 目录位置。
|
||||
- 文档目录层级必须与真实源码父目录一致。
|
||||
- 不再允许顶层旧路径和子模块新路径并存。
|
||||
|
||||
### 审计验收
|
||||
|
||||
- `Invalid header refs = 0`
|
||||
- `Invalid source refs = 0`
|
||||
- `Broken .md links = 0`
|
||||
- `Missing directory index pages = 0`
|
||||
|
||||
### 协作验收
|
||||
|
||||
- 每个阶段完成后立即提交推送。
|
||||
- 任务板状态同步更新，避免重复领取。
|
||||
211
docs/plan/API文档目录结构第二轮重构计划_2026-04-09.md
Normal file
211
docs/plan/API文档目录结构第二轮重构计划_2026-04-09.md
Normal file
@@ -0,0 +1,211 @@
|
||||
# API 文档目录结构第二轮重构计划
|
||||
|
||||
## 1. 背景
|
||||
|
||||
项目最近又经历了一轮较大的源码重构，`docs/api/XCEngine` 当前虽然顶层大类仍然存在，但内部已经出现了两类更严重的问题：
|
||||
|
||||
- 目录层级错位：文档页名字还对，但挂在了错误的父目录下。
|
||||
- 新旧结构并存：旧位置和新位置同时保留，导致同一 API 在文档树里出现两套入口。
|
||||
|
||||
这轮重构不再是简单补页，而是要把 `docs/api` 再次拉回到“与实际源码模块结构平行”的状态。
|
||||
|
||||
## 2. 本轮核对基准
|
||||
|
||||
本轮计划基于以下真实代码树做对照：
|
||||
|
||||
- 运行时 public headers：`engine/include/XCEngine/**`
|
||||
- 旧版编辑器 source-backed API：`editor/src/**`
|
||||
- 当前文档树：`docs/api/XCEngine/**`
|
||||
|
||||
同时参考了最新本地审计结果：
|
||||
|
||||
- `python -B docs/api/_tools/audit_api_docs.py`
|
||||
|
||||
## 3. 已确认的结构性问题
|
||||
|
||||
### 3.1 Rendering 存在成对重复目录
|
||||
|
||||
当前已确认以下目录同时出现在“旧顶层位置”和“源码对应的新子模块位置”：
|
||||
|
||||
- `docs/api/XCEngine/Rendering/CameraRenderer`
|
||||
- `docs/api/XCEngine/Rendering/Execution/CameraRenderer`
|
||||
- `docs/api/XCEngine/Rendering/SceneRenderer`
|
||||
- `docs/api/XCEngine/Rendering/Execution/SceneRenderer`
|
||||
- `docs/api/XCEngine/Rendering/CameraRenderRequest`
|
||||
- `docs/api/XCEngine/Rendering/Planning/CameraRenderRequest`
|
||||
- `docs/api/XCEngine/Rendering/SceneRenderRequestPlanner`
|
||||
- `docs/api/XCEngine/Rendering/Planning/SceneRenderRequestPlanner`
|
||||
- `docs/api/XCEngine/Rendering/SceneRenderRequestUtils`
|
||||
- `docs/api/XCEngine/Rendering/Planning/SceneRenderRequestUtils`
|
||||
- `docs/api/XCEngine/Rendering/RenderCameraData`
|
||||
- `docs/api/XCEngine/Rendering/FrameData/RenderCameraData`
|
||||
- `docs/api/XCEngine/Rendering/RenderResourceCache`
|
||||
- `docs/api/XCEngine/Rendering/Caches/RenderResourceCache`
|
||||
- `docs/api/XCEngine/Rendering/RenderSceneExtractor`
|
||||
- `docs/api/XCEngine/Rendering/Extraction/RenderSceneExtractor`
|
||||
- `docs/api/XCEngine/Rendering/RenderSceneUtility`
|
||||
- `docs/api/XCEngine/Rendering/Extraction/RenderSceneUtility`
|
||||
|
||||
这说明文档树里同时保留了“旧的平铺布局”和“新的源码子模块布局”。后续必须只保留源码对应路径，旧路径下的内容要迁移或删除，不能继续并存。
|
||||
|
||||
### 3.2 Rendering 还有一批疑似旧命名/旧抽象残留
|
||||
|
||||
当前已确认下列目录没有直接对应到当前真实头文件命名，属于优先审计对象：
|
||||
|
||||
- `docs/api/XCEngine/Rendering/ObjectIdEncoding`
|
||||
- `docs/api/XCEngine/Rendering/ObjectIdPass`
|
||||
- `docs/api/XCEngine/Rendering/RenderMaterialUtility`
|
||||
- `docs/api/XCEngine/Rendering/VisibleRenderObject`
|
||||
|
||||
这些目录大概率分别对应：
|
||||
|
||||
- 已下沉或改名后的 `Picking/ObjectIdCodec`
|
||||
- `Passes/BuiltinObjectIdPass`
|
||||
- `Materials/RenderMaterialResolve`
|
||||
- `FrameData/VisibleRenderItem`
|
||||
|
||||
但不能直接机械删除，必须先做“旧页内容是否需要迁移”的核对。
|
||||
|
||||
### 3.3 Editor 仍保留已脱离源码的历史页
|
||||
|
||||
当前已确认：
|
||||
|
||||
- `docs/api/XCEngine/Editor/panels/XCUIDemoPanel/XCUIDemoPanel.md`
|
||||
|
||||
对应源码：
|
||||
|
||||
- `editor/src/panels/XCUIDemoPanel.h`
|
||||
- `editor/src/panels/XCUIDemoPanel.cpp`
|
||||
|
||||
这两个文件都已经不存在。
|
||||
|
||||
当前仍引用该历史页的文档包括：
|
||||
|
||||
- `docs/api/XCEngine/Editor/panels/panels.md`
|
||||
- `docs/api/XCEngine/Editor/XCUIBackend/ImGuiTransitionBackend/ImGuiTransitionBackend.md`
|
||||
|
||||
`docs/api/XCEngine/UI/DrawData/DrawData.md` 里已经改成“旧链路说明”，这类描述可以保留，但不应该继续把 `XCUIDemoPanel` 作为真实 canonical API 页面入口。
|
||||
|
||||
### 3.4 审计明确缺页仍然存在
|
||||
|
||||
最新审计仍明确指出以下缺口需要补齐：
|
||||
|
||||
- `XCEngine/Components/VolumeRendererComponent.h`
|
||||
- `XCEngine/Rendering/FrameData/VisibleVolumeItem.h`
|
||||
- `XCEngine/Rendering/Passes/BuiltinSelectionMaskPass.h`
|
||||
- `XCEngine/Rendering/Passes/BuiltinSelectionOutlinePass.h`
|
||||
- `XCEngine/Rendering/Passes/BuiltinVolumetricPass.h`
|
||||
- `XCEngine/Resources/Volume/VolumeField.h`
|
||||
- `XCEngine/Resources/Volume/VolumeFieldLoader.h`
|
||||
- `XCEngine/UI/Widgets/UIDragDropInteraction.h`
|
||||
- `XCEngine/UI/Widgets/UIScrollModel.h`
|
||||
- `editor/src/ComponentEditors/VolumeRendererComponentEditor.h`
|
||||
- `editor/src/panels/MaterialInspectorMaterialState.h`
|
||||
- `editor/src/panels/MaterialInspectorMaterialStateIO.h`
|
||||
|
||||
同时还缺少：
|
||||
|
||||
- `docs/api/XCEngine/Resources/Volume/Volume.md`
|
||||
|
||||
### 3.5 当前存在并发修改热点
|
||||
|
||||
当前工作区里已有其他会话在修改以下源码区域，对应文档重构要么延后，要么单独协调：
|
||||
|
||||
- `editor/src/Viewport/**`
|
||||
- `engine/include/XCEngine/RHI/**`
|
||||
- `engine/include/XCEngine/Rendering/Passes/**`
|
||||
- `engine/include/XCEngine/Rendering/Materials/RenderMaterialResolve.h`
|
||||
- `engine/include/XCEngine/UI/Widgets/UISelectionModel.h`
|
||||
- `engine/include/XCEngine/UI/Widgets/UIDragDropInteraction.h`
|
||||
|
||||
因此本轮执行要按“低冲突优先”组织阶段，避免多个会话同时改同一批文档。
|
||||
|
||||
## 4. 本轮目标
|
||||
|
||||
### 4.1 结构目标
|
||||
|
||||
- `docs/api/XCEngine/**` 内每一个类/模块页都必须与当前真实源码路径平行。
|
||||
- 同一 API 只能保留一个 canonical 位置。
|
||||
- 旧的错位目录必须迁移或移除，不能继续保留作第二入口。
|
||||
|
||||
### 4.2 内容目标
|
||||
|
||||
- 在结构对齐完成后，再逐批做内容重构。
|
||||
- 内容必须基于当前源码与测试，而不是沿用旧说明。
|
||||
|
||||
### 4.3 协作目标
|
||||
|
||||
- 每一批任务都要能被多个会话独立领取。
|
||||
- 每一阶段结束后立即提交并推送，避免长时间悬空。
|
||||
|
||||
## 5. 分阶段执行
|
||||
|
||||
## Phase A：建立新计划与任务板
|
||||
|
||||
- 新开第二轮计划文件
|
||||
- 新开第二轮并行任务板
|
||||
- 标清“当前确定的问题”和“并发风险路径”
|
||||
|
||||
## Phase B：清理已确认的失效历史页
|
||||
|
||||
- 处理 `XCUIDemoPanel`
|
||||
- 修复所有反向链接
|
||||
- 让 `Invalid source refs` 归零
|
||||
|
||||
## Phase C：Rendering 目录结构归位
|
||||
|
||||
- 把所有错位的顶层 Rendering 目录迁移到真实子模块
|
||||
- 合并旧目录里的方法页/细页到正确的新位置
|
||||
- 删除旧顶层重复入口
|
||||
|
||||
## Phase D：补齐审计明确缺页
|
||||
|
||||
- `Resources/Volume`
|
||||
- `Components/VolumeRendererComponent`
|
||||
- `Rendering/VisibleVolumeItem`
|
||||
- `Rendering` 的体积/选择 pass
|
||||
- `UI/Widgets` 新 helper
|
||||
- `Editor` 的体积组件编辑器与材质状态页
|
||||
|
||||
## Phase E：高风险模块内容回归
|
||||
|
||||
在相关源码停止波动后，再处理：
|
||||
|
||||
- `RHI`
|
||||
- `Rendering/Passes`
|
||||
- `Rendering/Materials`
|
||||
- `Editor/Viewport`
|
||||
- `UI/Widgets`
|
||||
|
||||
## Phase F：总回归
|
||||
|
||||
- 全量跑审计
|
||||
- 清理空目录、错链、旧入口
|
||||
- 更新阶段状态并准备下一轮内容重构
|
||||
|
||||
## 6. 本轮优先级判断
|
||||
|
||||
当前最优先的不是继续写新内容，而是先把“错层级”和“重复入口”消掉。否则后面无论哪个会话补文档，都有较高概率继续写到旧路径。
|
||||
|
||||
因此第二轮的第一主战场是：
|
||||
|
||||
- `docs/api/XCEngine/Rendering`
|
||||
|
||||
第二主战场是：
|
||||
|
||||
- `docs/api/XCEngine/Editor` 中仍脱离真实源码的历史页
|
||||
|
||||
第三主战场才是：
|
||||
|
||||
- 审计明确缺页的 Volume / UI / Editor 补齐
|
||||
|
||||
## 7. 阶段收口要求
|
||||
|
||||
每完成一个阶段，必须执行：
|
||||
|
||||
1. 本地核对改动范围
|
||||
2. `python -B docs/api/_tools/audit_api_docs.py`
|
||||
3. `git commit`
|
||||
4. `git push`
|
||||
|
||||
只有在上一阶段已经提交推送后，才进入下一阶段。
|
||||
Reference in New Issue
Block a user