docs(rendering): reconcile infinite grid docs
This commit is contained in:
@@ -6,62 +6,50 @@
|
||||
|
||||
**头文件**: `XCEngine/Rendering/Passes/BuiltinInfiniteGridPass.h`
|
||||
|
||||
**描述**: 在场景颜色目标上叠加无限地面网格的底层全屏 pass；真正使用哪份 shader 由调用方通过 `shaderPath` 注入。
|
||||
**描述**: 在场景颜色目标上叠加无限地面网格的全屏 pass；真正使用哪份 shader 由调用方通过 `shaderPath` 注入。
|
||||
|
||||
## 概述
|
||||
## 概览
|
||||
|
||||
## 2026-04-10 同步补充
|
||||
|
||||
以下内容以当前 `BuiltinInfiniteGridPass.h/.cpp` 为准：
|
||||
|
||||
- 当前实现不再把“`backendType == D3D12`”写成硬编码前置条件；只要配置 shader 在当前 backend 上存在兼容 graphics variant，就可以创建并执行。
|
||||
- `EnsureInitialized(...)` / `CreateResources(...)` 现在按 backend、目标颜色格式、深度格式和目标 `sampleCount` 重新建资源；surface 配置变化时会销毁旧的 pipeline / descriptor 再创建。
|
||||
- grid 的 viewport / scissor、视锥宽高比与投影视口尺寸都按 `surface.GetRenderArea()` 计算，不再固定覆盖整张 surface。
|
||||
- 当 `surface.IsAutoTransitionEnabled()` 为 `true` 时，pass 会把颜色附件从 `surface.GetColorStateAfter()` 切到 `RenderTarget`，并把 depth 附件从 `surface.GetDepthStateAfter()` 切到 `DepthWrite`，结束后再恢复。
|
||||
|
||||
`BuiltinInfiniteGridPass` 是当前 Scene View 里“地面参考网格”效果的实际执行者。
|
||||
|
||||
它消费一份 [InfiniteGridPassData](InfiniteGridPassData.md)，在运行时先推导
|
||||
[InfiniteGridParameters](InfiniteGridParameters.md)，再用当前配置的 shader 资源把网格直接混合到目标颜色附件上。
|
||||
`BuiltinInfiniteGridPass` 是当前 Scene View 里“地面参考网格”效果的实际执行者。它消费一份 [InfiniteGridPassData](InfiniteGridPassData.md)，先推导 [InfiniteGridParameters](InfiniteGridParameters.md)，再用当前配置的 shader 资源把网格直接混合到目标颜色附件上。
|
||||
|
||||
这个类当前不再自己决定“Scene View grid shader 到底是哪一份资源”。源码里的职责边界已经变成：
|
||||
|
||||
- `BuiltinInfiniteGridPass`
|
||||
只负责资源创建、常量写入和一次全屏三角形执行。
|
||||
- editor 调用方
|
||||
通过 [SetShaderPath](SetShaderPath.md) 或构造函数参数注入具体 shader 路径。
|
||||
只负责资源创建、常量写入和一次全屏三角形执行
|
||||
- editor / 调用方
|
||||
通过 [SetShaderPath](SetShaderPath.md) 或构造函数参数注入具体 shader 路径
|
||||
- `SceneViewportGridPass`
|
||||
负责把 [SceneViewportResourcePaths](../../../Editor/Viewport/SceneViewportResourcePaths/SceneViewportResourcePaths.md)
|
||||
生成的 editor 资源路径传进来；`SceneViewportShaderPaths` 现在只是兼容 include 层。
|
||||
负责把 editor 资源路径和 Scene View 运行时参数组织好，再调用这里执行
|
||||
|
||||
## 关键输入
|
||||
|
||||
- [InfiniteGridPassData](InfiniteGridPassData.md) 决定相机位置、朝向、FOV、裁剪面和轨道距离。
|
||||
- [BuildInfiniteGridParameters](BuildInfiniteGridParameters.md) 会把这些数据折算成 `baseScale`、`transitionBlend` 和 `fadeDistance`。
|
||||
- `RenderSurface` 需要同时提供颜色附件和深度附件；当前 pass 会开启深度测试但关闭深度写入。
|
||||
- [InfiniteGridPassData](InfiniteGridPassData.md) 决定相机位置、朝向、FOV、裁剪面和轨道距离
|
||||
- [BuildInfiniteGridParameters](BuildInfiniteGridParameters.md) 会把这些数据折算成 `baseScale`、`transitionBlend` 和 `fadeDistance`
|
||||
- `RenderSurface` 需要同时提供单个有效颜色附件、深度附件和有效 render area
|
||||
|
||||
## 当前实现流程
|
||||
|
||||
1. 先校验 `data.valid`、`RenderContext::IsValid()` 和 `backendType == D3D12`。
|
||||
2. 通过 `EnsureInitialized()` 惰性创建 pipeline layout、pipeline state 和常量描述符；这一步要求 `shaderPath` 非空且可成功加载。
|
||||
3. 从相机姿态推导网格参数，并构建 view-projection 常量。
|
||||
1. 先校验 `data.valid`、`RenderContext::IsValid()`、目标颜色附件、深度附件和 `surface.GetRenderArea()`。
|
||||
2. 通过 `EnsureInitialized(renderContext, surface)` 懒创建或重建 pipeline layout、pipeline state 和常量描述符；这一步要求 `shaderPath` 非空且可成功加载。
|
||||
3. 从相机姿态推导网格参数，并基于 `surface.GetRenderArea()` 的宽高构建 view-projection 常量。
|
||||
4. 把第一个颜色附件和深度附件绑定为渲染目标。
|
||||
5. 以全屏三角形方式发出一次 `Draw(3, 1, 0, 0)`。
|
||||
|
||||
## 当前实现边界
|
||||
|
||||
- 当前只支持 `D3D12` shader variant。
|
||||
- 在第一次创建资源之前必须先提供有效 `shaderPath`；空路径会记录错误并返回 `false`。
|
||||
- 只写入 `surface` 的第一个颜色附件。
|
||||
- 视口和裁剪矩形使用 `surface.GetWidth()` / `GetHeight()`，不是自定义 render area。
|
||||
- 网格参数完全由当前相机高度与朝向启发式推导，还没有暴露成更完整的编辑器样式配置。
|
||||
- 当前实现不再把“`backendType == D3D12`”写成硬编码前置条件；只要配置 shader 在当前 backend 上存在兼容 graphics variant，就可以创建并执行。
|
||||
- `EnsureInitialized(...)` / `CreateResources(...)` 会按 backend、目标颜色格式、深度格式和目标 `sampleCount` 重新建资源；surface 配置变化时会销毁旧的 pipeline / descriptor 再创建。
|
||||
- viewport、scissor、宽高比与投影视口尺寸都会按 `surface.GetRenderArea()` 计算，不再固定覆盖整张 surface。
|
||||
- 当 `surface.IsAutoTransitionEnabled()` 为 `true` 时，pass 会把颜色附件从 `surface.GetColorStateAfter()` 切到 `RenderTarget`，并把 depth 附件从 `surface.GetDepthStateAfter()` 切到 `DepthWrite`，结束后再恢复。
|
||||
- 当前仍只写第一个颜色附件；不是多 render target pass。
|
||||
- 网格参数仍主要由当前相机高度与朝向启发式推导，还没有暴露成更完整的编辑器样式配置对象。
|
||||
|
||||
## 公开方法与相关类型
|
||||
|
||||
| 成员 | 说明 |
|
||||
|------|------|
|
||||
| [Constructor](Constructor.md) | 创建 pass，并可选地预置 shader 路径。 |
|
||||
| [Destructor](Destructor.md) | 默认析构；不会自动代替 `Shutdown()` 释放内部 RHI 资源。 |
|
||||
| [Destructor](Destructor.md) | 默认析构；不会替代 [Shutdown](Shutdown.md) 释放内部 RHI 资源。 |
|
||||
| [SetShaderPath](SetShaderPath.md) | 更新当前要加载的 shader 路径，并清空已创建资源。 |
|
||||
| [GetShaderPath](GetShaderPath.md) | 返回当前记录的 shader 路径。 |
|
||||
| [InfiniteGridPassData](InfiniteGridPassData.md) | 输入相机数据。 |
|
||||
@@ -72,16 +60,13 @@
|
||||
|
||||
## 真实使用位置
|
||||
|
||||
- `editor/src/Viewport/Passes/SceneViewportGridPass.cpp` 用 `SceneViewportGridPassRenderer` 包装它，
|
||||
并通过 `GetSceneViewportInfiniteGridShaderPath()` 注入 editor-owned shader 路径，再把它挂进 Scene View 的 `postScenePasses`。
|
||||
- [SceneViewportRenderPlan](../../../Editor/Viewport/SceneViewportRenderPlan/SceneViewportRenderPlan.md) 决定当前帧是否需要创建这条 pass。
|
||||
- `tests/Editor/test_scene_viewport_overlay_renderer.cpp` 固定了网格参数推导规则。
|
||||
- `editor/src/Viewport/Passes/SceneViewportGridPass.cpp` 当前会包装它，并通过 `GetSceneViewportInfiniteGridShaderPath()` 注入 editor-owned shader 路径，再把它挂进 Scene View 的 `postScenePasses`
|
||||
- [SceneViewportRenderPlan](../../../Editor/Viewport/SceneViewportRenderPlan/SceneViewportRenderPlan.md) 决定当前帧是否需要创建这条 pass
|
||||
- `tests/Editor/test_scene_viewport_overlay_renderer.cpp` 覆盖了网格参数推导规则
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [Passes](../Passes.md)
|
||||
- [Constructor](Constructor.md)
|
||||
- [Destructor](Destructor.md)
|
||||
- [SetShaderPath](SetShaderPath.md)
|
||||
- [GetShaderPath](GetShaderPath.md)
|
||||
- [InfiniteGridPassData](InfiniteGridPassData.md)
|
||||
|
||||
@@ -15,33 +15,26 @@ bool Render(
|
||||
const InfiniteGridPassData& data);
|
||||
```
|
||||
|
||||
## 2026-04-10 更新
|
||||
|
||||
- 当前路径不再把 `backendType == D3D12` 作为固定失败条件；真正是否能执行，取决于当前 backend 上是否能解析到兼容的 grid shader variant。
|
||||
- `EnsureInitialized(...)` 现在显式接收 `surface`，并按 backend、render target format、depth format 与 `sampleCount` 重新建资源。
|
||||
- viewport、scissor，以及用于构建 grid 投影的宽高比，都会读取 `surface.GetRenderArea()`。
|
||||
- 当 `surface.IsAutoTransitionEnabled()` 为 `true` 时，会在进入 pass 前切换颜色 / depth 资源状态，并在结束后恢复到 `surface` 记录的 `after` 状态。
|
||||
|
||||
## 作用
|
||||
|
||||
把当前无限网格效果绘制到 `surface` 的第一个颜色附件上。
|
||||
|
||||
## 当前实现流程
|
||||
|
||||
1. 如果 `data.valid == false`、`renderContext` 无效或后端不是 `D3D12`，直接返回 `false`。
|
||||
2. 调用 `EnsureInitialized(renderContext)`；如果当前 `shaderPath` 为空，或配置路径下的 shader 无法加载，也会在这里失败。
|
||||
3. 检查颜色附件和深度附件，要求 grid pass 具备完整的颜色与深度目标。
|
||||
4. 调用 [BuildInfiniteGridParameters](BuildInfiniteGridParameters.md) 生成网格参数，并构建 view-projection 常量。
|
||||
5. 把常量写入 descriptor set。
|
||||
6. 绑定第一个颜色附件和深度附件。
|
||||
7. 以全屏三角形方式执行一次 `Draw(3, 1, 0, 0)`。
|
||||
1. 如果 `data.valid == false`、`renderContext` 无效、目标不具备单颜色附件 / 深度附件，或 `surface.GetRenderArea()` 非法，直接返回 `false`。
|
||||
2. 调用 `EnsureInitialized(renderContext, surface)`；若当前 `shaderPath` 为空，或配置路径下的 shader 无法在当前 backend 上解析到兼容 graphics variant，也会在这里失败。
|
||||
3. 调用 [BuildInfiniteGridParameters](BuildInfiniteGridParameters.md) 生成网格参数，并基于 `surface.GetRenderArea()` 的宽高构建 view-projection 常量。
|
||||
4. 把常量写入 descriptor set。
|
||||
5. 若 `surface.IsAutoTransitionEnabled()` 为 `true`，则把颜色附件从 `surface.GetColorStateAfter()` 切到 `RenderTarget`，并把深度附件从 `surface.GetDepthStateAfter()` 切到 `DepthWrite`。
|
||||
6. 绑定第一个颜色附件和深度附件，按 `surface.GetRenderArea()` 设置 viewport 与 scissor。
|
||||
7. 以全屏三角形方式执行一次 `Draw(3, 1, 0, 0)`，并在结束后按需恢复资源状态。
|
||||
|
||||
## 关键语义
|
||||
|
||||
- 这条路径不再隐式依赖 engine builtin shader；调用方必须先通过构造函数或 [SetShaderPath](SetShaderPath.md) 提供有效 shader 路径。
|
||||
- pass 本身不做资源状态切换。
|
||||
- viewport 与 scissor 总是覆盖整张 surface，不读取 `surface.GetRenderArea()`。
|
||||
- 当前只写第一个颜色附件。
|
||||
- 当前路径不再把 `backendType == D3D12` 作为固定失败条件；真正是否能执行，取决于当前 backend 上是否能解析到兼容的 grid shader variant。
|
||||
- `EnsureInitialized(...)` 现在显式接收 `surface`，并按 backend、render target format、depth format 与 `sampleCount` 重新建资源。
|
||||
- viewport、scissor 和 grid 投影用到的宽高比都会遵循 `surface.GetRenderArea()`，而不是整张 surface 的尺寸。
|
||||
- 当前仍只写第一个颜色附件。
|
||||
|
||||
## 相关文档
|
||||
|
||||
@@ -49,3 +42,4 @@ bool Render(
|
||||
- [SetShaderPath](SetShaderPath.md)
|
||||
- [InfiniteGridPassData](InfiniteGridPassData.md)
|
||||
- [BuildInfiniteGridParameters](BuildInfiniteGridParameters.md)
|
||||
- [RenderSurface](../../RenderSurface/RenderSurface.md)
|
||||
|
||||
Reference in New Issue
Block a user