# BuiltinInfiniteGridPass

**命名空间**: `XCEngine::Rendering::Passes`

**类型**: `class`

**头文件**: `XCEngine/Rendering/Passes/BuiltinInfiniteGridPass.h`

**描述**: 在场景颜色目标上叠加无限地面网格的底层全屏 pass；真正使用哪份 shader 由调用方通过 `shaderPath` 注入。

## 概述

`BuiltinInfiniteGridPass` 是当前 Scene View 里“地面参考网格”效果的实际执行者。

它消费一份 [InfiniteGridPassData](InfiniteGridPassData.md)，在运行时先推导
[InfiniteGridParameters](InfiniteGridParameters.md)，再用当前配置的 shader 资源把网格直接混合到目标颜色附件上。

这个类当前不再自己决定“Scene View grid shader 到底是哪一份资源”。源码里的职责边界已经变成：

- `BuiltinInfiniteGridPass`
  只负责资源创建、常量写入和一次全屏三角形执行。
- editor 调用方
  通过 [SetShaderPath](SetShaderPath.md) 或构造函数参数注入具体 shader 路径。
- `SceneViewportGridPass`
  负责把 [SceneViewportResourcePaths](../../../Editor/Viewport/SceneViewportResourcePaths/SceneViewportResourcePaths.md)
  生成的 editor 资源路径传进来；`SceneViewportShaderPaths` 现在只是兼容 include 层。

## 关键输入

- [InfiniteGridPassData](InfiniteGridPassData.md) 决定相机位置、朝向、FOV、裁剪面和轨道距离。
- [BuildInfiniteGridParameters](BuildInfiniteGridParameters.md) 会把这些数据折算成 `baseScale`、`transitionBlend` 和 `fadeDistance`。
- `RenderSurface` 需要同时提供颜色附件和深度附件；当前 pass 会开启深度测试但关闭深度写入。

## 当前实现流程

1. 先校验 `data.valid`、`RenderContext::IsValid()` 和 `backendType == D3D12`。
2. 通过 `EnsureInitialized()` 惰性创建 pipeline layout、pipeline state 和常量描述符；这一步要求 `shaderPath` 非空且可成功加载。
3. 从相机姿态推导网格参数，并构建 view-projection 常量。
4. 把第一个颜色附件和深度附件绑定为渲染目标。
5. 以全屏三角形方式发出一次 `Draw(3, 1, 0, 0)`。

## 当前实现边界

- 当前只支持 `D3D12` shader variant。
- 在第一次创建资源之前必须先提供有效 `shaderPath`；空路径会记录错误并返回 `false`。
- 只写入 `surface` 的第一个颜色附件。
- 视口和裁剪矩形使用 `surface.GetWidth()` / `GetHeight()`，不是自定义 render area。
- 网格参数完全由当前相机高度与朝向启发式推导，还没有暴露成更完整的编辑器样式配置。

## 公开方法与相关类型

| 成员 | 说明 |
|------|------|
| [Constructor](Constructor.md) | 创建 pass，并可选地预置 shader 路径。 |
| [Destructor](Destructor.md) | 默认析构；不会自动代替 `Shutdown()` 释放内部 RHI 资源。 |
| [SetShaderPath](SetShaderPath.md) | 更新当前要加载的 shader 路径，并清空已创建资源。 |
| [GetShaderPath](GetShaderPath.md) | 返回当前记录的 shader 路径。 |
| [InfiniteGridPassData](InfiniteGridPassData.md) | 输入相机数据。 |
| [InfiniteGridParameters](InfiniteGridParameters.md) | 推导后的网格尺度参数。 |
| [BuildInfiniteGridParameters](BuildInfiniteGridParameters.md) | 从输入相机数据生成当前网格参数。 |
| [Render](Render.md) | 在当前颜色目标上提交网格覆盖层。 |
| [Shutdown](Shutdown.md) | 销毁内部 pipeline、descriptor 和 shader handle。 |

## 真实使用位置

- `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` 固定了网格参数推导规则。

## 相关文档

- [Passes](../Passes.md)
- [Constructor](Constructor.md)
- [Destructor](Destructor.md)
- [SetShaderPath](SetShaderPath.md)
- [GetShaderPath](GetShaderPath.md)
- [InfiniteGridPassData](InfiniteGridPassData.md)
- [InfiniteGridParameters](InfiniteGridParameters.md)
- [BuildInfiniteGridParameters](BuildInfiniteGridParameters.md)
- [SceneViewportRenderPlan](../../../Editor/Viewport/SceneViewportRenderPlan/SceneViewportRenderPlan.md)
- [SceneViewportResourcePaths](../../../Editor/Viewport/SceneViewportResourcePaths/SceneViewportResourcePaths.md)