From e0481dd6b51d1d04234e09743b9c3d6016a5ad38 Mon Sep 17 00:00:00 2001 From: ssdfasd <2156608475@qq.com> Date: Sat, 4 Apr 2026 17:03:43 +0800 Subject: [PATCH] docs: formalize scene viewport shader resource docs --- .../SceneViewportGridPassData.md | 39 +++++++++++++ .../SceneViewportPassSpecs.md | 42 ++++++++++++++ .../SceneViewportSelectionOutlineStyle.md | 33 +++++++++++ .../ToBuiltinSceneViewportGridPassData.md | 37 ++++++++++++ ...iltinSceneViewportSelectionOutlineStyle.md | 30 ++++++++++ .../BuildSceneViewportEditorResourcePath.md | 31 ++++++++++ .../GetSceneViewportCameraGizmoIconPath.md | 21 +++++++ .../GetSceneViewportInfiniteGridShaderPath.md | 27 +++++++++ .../GetSceneViewportMainLightGizmoIconPath.md | 21 +++++++ ...tSceneViewportObjectIdOutlineShaderPath.md | 27 +++++++++ .../GetSceneViewportResourceRepoRootPath.md | 25 ++++++++ .../NormalizeSceneViewportResourcePath.md | 30 ++++++++++ .../SceneViewportResourcePaths.md | 49 ++++++++++++++++ .../BuildSceneViewportShaderPath.md | 30 +++++----- .../GetSceneViewportInfiniteGridShaderPath.md | 25 ++------ ...tSceneViewportObjectIdOutlineShaderPath.md | 25 ++------ .../GetSceneViewportShaderRepoRootPath.md | 27 ++++----- .../NormalizeSceneViewportShaderPath.md | 32 +++-------- .../SceneViewportShaderPaths.md | 57 ++++++++----------- 19 files changed, 480 insertions(+), 128 deletions(-) create mode 100644 docs/api/XCEngine/Editor/Viewport/SceneViewportPassSpecs/SceneViewportGridPassData.md create mode 100644 docs/api/XCEngine/Editor/Viewport/SceneViewportPassSpecs/SceneViewportPassSpecs.md create mode 100644 docs/api/XCEngine/Editor/Viewport/SceneViewportPassSpecs/SceneViewportSelectionOutlineStyle.md create mode 100644 docs/api/XCEngine/Editor/Viewport/SceneViewportPassSpecs/ToBuiltinSceneViewportGridPassData.md create mode 100644 docs/api/XCEngine/Editor/Viewport/SceneViewportPassSpecs/ToBuiltinSceneViewportSelectionOutlineStyle.md create mode 100644 docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/BuildSceneViewportEditorResourcePath.md create mode 100644 docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/GetSceneViewportCameraGizmoIconPath.md create mode 100644 docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/GetSceneViewportInfiniteGridShaderPath.md create mode 100644 docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/GetSceneViewportMainLightGizmoIconPath.md create mode 100644 docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/GetSceneViewportObjectIdOutlineShaderPath.md create mode 100644 docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/GetSceneViewportResourceRepoRootPath.md create mode 100644 docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/NormalizeSceneViewportResourcePath.md create mode 100644 docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/SceneViewportResourcePaths.md diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportPassSpecs/SceneViewportGridPassData.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportPassSpecs/SceneViewportGridPassData.md new file mode 100644 index 00000000..1df1bbc4 --- /dev/null +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportPassSpecs/SceneViewportGridPassData.md @@ -0,0 +1,39 @@ +# SceneViewportGridPassData + +**命名空间**: `XCEngine::Editor` + +**类型**: `struct` + +**源文件**: `editor/src/Viewport/SceneViewportPassSpecs.h` + +## 描述 + +Scene View 网格 pass 的 editor 侧输入快照。 + +## 当前字段 + +- `valid` +- `cameraPosition` +- `cameraForward` +- `cameraRight` +- `cameraUp` +- `verticalFovDegrees` +- `nearClipPlane` +- `farClipPlane` +- `orbitDistance` + +## 当前语义 + +- 这组字段与 runtime `Rendering::Passes::InfiniteGridPassData` 一一对应。 +- 它本身不包含样式、shader 路径或 `RenderSurface` 信息，只描述当前 Scene View 相机姿态。 +- `orbitDistance` 也会被原样传给 runtime 结构；但当前 `BuildInfiniteGridParameters(...)` 仍不会用它参与网格参数推导。 + +## 测试覆盖 + +- `tests/Editor/test_viewport_render_flow_utils.cpp` 验证了 `BuildSceneViewportGridPassData(...)` 会把 Scene View overlay 中的相机字段正确拷贝到这里。 + +## 相关文档 + +- [SceneViewportPassSpecs](SceneViewportPassSpecs.md) +- [ToBuiltinSceneViewportGridPassData](ToBuiltinSceneViewportGridPassData.md) +- [InfiniteGridPassData](../../../Rendering/Passes/BuiltinInfiniteGridPass/InfiniteGridPassData.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportPassSpecs/SceneViewportPassSpecs.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportPassSpecs/SceneViewportPassSpecs.md new file mode 100644 index 00000000..4ec0c23f --- /dev/null +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportPassSpecs/SceneViewportPassSpecs.md @@ -0,0 +1,42 @@ +# SceneViewportPassSpecs + +**命名空间**: `XCEngine::Editor` + +**类型**: `header-helper + structs` + +**源文件**: `editor/src/Viewport/SceneViewportPassSpecs.h` + +**描述**: Scene View 渲染计划与底层 runtime pass 之间的数据适配头，负责把 editor 侧的网格与选中描边配置转换成 `BuiltinInfiniteGridPass` / `BuiltinObjectIdOutlinePass` 可直接消费的结构。 + +## 概览 + +`SceneViewportPassSpecs.h` 当前只做轻量数据桥接，不自己创建任何 `RenderPass` 或 GPU 资源。 + +它主要服务两条路径： + +- 网格路径：`SceneViewportGridPassData` -> [ToBuiltinSceneViewportGridPassData](ToBuiltinSceneViewportGridPassData.md) -> `Rendering::Passes::InfiniteGridPassData` +- 选中描边路径：`SceneViewportSelectionOutlineStyle` -> [ToBuiltinSceneViewportSelectionOutlineStyle](ToBuiltinSceneViewportSelectionOutlineStyle.md) -> `Rendering::Passes::ObjectIdOutlineStyle` + +## 公开类型与函数 + +| 成员 | 说明 | +|------|------| +| [SceneViewportGridPassData](SceneViewportGridPassData.md) | editor 侧网格 pass 输入快照。 | +| [ToBuiltinSceneViewportGridPassData](ToBuiltinSceneViewportGridPassData.md) | 把 editor 网格数据拷贝成 runtime infinite-grid 输入。 | +| [SceneViewportSelectionOutlineStyle](SceneViewportSelectionOutlineStyle.md) | editor 侧选中描边样式。 | +| [ToBuiltinSceneViewportSelectionOutlineStyle](ToBuiltinSceneViewportSelectionOutlineStyle.md) | 把 editor 描边样式拷贝成 runtime outline 样式。 | + +## 当前使用位置 + +- `ViewportHostRenderFlowUtils.h` 当前构建这两个 editor 侧结构。 +- `SceneViewportGridPass.cpp` 和 `SceneViewportSelectionOutlinePass.cpp` 会把它们进一步转换成 runtime pass 输入。 +- `tests/Editor/test_viewport_render_flow_utils.cpp` 覆盖了这两组数据的默认值和拷贝行为。 + +## 相关文档 + +- [SceneViewportGridPassData](SceneViewportGridPassData.md) +- [ToBuiltinSceneViewportGridPassData](ToBuiltinSceneViewportGridPassData.md) +- [SceneViewportSelectionOutlineStyle](SceneViewportSelectionOutlineStyle.md) +- [ToBuiltinSceneViewportSelectionOutlineStyle](ToBuiltinSceneViewportSelectionOutlineStyle.md) +- [SceneViewportGridPass](../Passes/SceneViewportGridPass/SceneViewportGridPass.md) +- [SceneViewportSelectionOutlinePass](../Passes/SceneViewportSelectionOutlinePass/SceneViewportSelectionOutlinePass.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportPassSpecs/SceneViewportSelectionOutlineStyle.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportPassSpecs/SceneViewportSelectionOutlineStyle.md new file mode 100644 index 00000000..689ce982 --- /dev/null +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportPassSpecs/SceneViewportSelectionOutlineStyle.md @@ -0,0 +1,33 @@ +# SceneViewportSelectionOutlineStyle + +**命名空间**: `XCEngine::Editor` + +**类型**: `struct` + +**源文件**: `editor/src/Viewport/SceneViewportPassSpecs.h` + +## 描述 + +Scene View 选中描边 pass 的 editor 侧样式配置。 + +## 当前字段与默认值 + +- `outlineColor = Math::Color(1.0f, 0.4f, 0.0f, 1.0f)` +- `outlineWidthPixels = 2.0f` +- `debugSelectionMask = false` + +## 当前语义 + +- 这组字段与 runtime `Rendering::Passes::ObjectIdOutlineStyle` 一一对应。 +- 默认样式就是当前 Scene View 常见的橙色、`2px` 选中描边。 +- `debugSelectionMask` 打开时，底层 outline pass 会切换到调试遮罩输出语义，而不是正常描边合成。 + +## 测试覆盖 + +- `tests/Editor/test_viewport_render_flow_utils.cpp` 验证了默认样式和 debug 样式构建结果。 + +## 相关文档 + +- [SceneViewportPassSpecs](SceneViewportPassSpecs.md) +- [ToBuiltinSceneViewportSelectionOutlineStyle](ToBuiltinSceneViewportSelectionOutlineStyle.md) +- [ObjectIdOutlineStyle](../../../Rendering/Passes/ObjectIdOutlineStyle/ObjectIdOutlineStyle.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportPassSpecs/ToBuiltinSceneViewportGridPassData.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportPassSpecs/ToBuiltinSceneViewportGridPassData.md new file mode 100644 index 00000000..8259b871 --- /dev/null +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportPassSpecs/ToBuiltinSceneViewportGridPassData.md @@ -0,0 +1,37 @@ +# ToBuiltinSceneViewportGridPassData + +把 editor 侧网格输入拷贝成 runtime infinite-grid 输入。 + +```cpp +inline Rendering::Passes::InfiniteGridPassData ToBuiltinSceneViewportGridPassData( + const SceneViewportGridPassData& data); +``` + +## 参数 + +- `data` - editor 侧网格 pass 输入。 + +## 当前语义 + +- 当前实现只是字段逐项拷贝： + - `valid` + - `cameraPosition` + - `cameraForward` + - `cameraRight` + - `cameraUp` + - `verticalFovDegrees` + - `nearClipPlane` + - `farClipPlane` + - `orbitDistance` +- 它不做坐标变换、默认值修正或单位换算。 + +## 调用方影响 + +- `SceneViewportGridPassRenderer` 最终会把转换结果交给 runtime [BuiltinInfiniteGridPass](../../../Rendering/Passes/BuiltinInfiniteGridPass/BuiltinInfiniteGridPass.md)。 +- 因为这里只做拷贝，所以如果 editor 侧输入本身无效，runtime 行为也会直接继承这一状态。 + +## 相关文档 + +- [SceneViewportPassSpecs](SceneViewportPassSpecs.md) +- [SceneViewportGridPassData](SceneViewportGridPassData.md) +- [InfiniteGridPassData](../../../Rendering/Passes/BuiltinInfiniteGridPass/InfiniteGridPassData.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportPassSpecs/ToBuiltinSceneViewportSelectionOutlineStyle.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportPassSpecs/ToBuiltinSceneViewportSelectionOutlineStyle.md new file mode 100644 index 00000000..a8dddd0b --- /dev/null +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportPassSpecs/ToBuiltinSceneViewportSelectionOutlineStyle.md @@ -0,0 +1,30 @@ +# ToBuiltinSceneViewportSelectionOutlineStyle + +把 editor 侧选中描边样式拷贝成 runtime outline 样式。 + +```cpp +inline Rendering::Passes::ObjectIdOutlineStyle ToBuiltinSceneViewportSelectionOutlineStyle( + const SceneViewportSelectionOutlineStyle& style); +``` + +## 参数 + +- `style` - editor 侧描边样式。 + +## 当前语义 + +- 当前实现只做字段逐项拷贝： + - `outlineColor` + - `outlineWidthPixels` + - `debugSelectionMask` +- 不做颜色空间转换、宽度 clamp 或额外策略判断。 + +## 调用方影响 + +- `SceneViewportSelectionOutlinePassRenderer` 会把转换结果直接交给 runtime [BuiltinObjectIdOutlinePass](../../../Rendering/Passes/BuiltinObjectIdOutlinePass/BuiltinObjectIdOutlinePass.md)。 + +## 相关文档 + +- [SceneViewportPassSpecs](SceneViewportPassSpecs.md) +- [SceneViewportSelectionOutlineStyle](SceneViewportSelectionOutlineStyle.md) +- [ObjectIdOutlineStyle](../../../Rendering/Passes/ObjectIdOutlineStyle/ObjectIdOutlineStyle.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/BuildSceneViewportEditorResourcePath.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/BuildSceneViewportEditorResourcePath.md new file mode 100644 index 00000000..57ff7f11 --- /dev/null +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/BuildSceneViewportEditorResourcePath.md @@ -0,0 +1,31 @@ +# Detail::BuildSceneViewportEditorResourcePath + +把 editor 资源相对路径拼成 repo 内绝对资源路径。 + +```cpp +inline Containers::String BuildSceneViewportEditorResourcePath(const std::filesystem::path& relativePath); +``` + +## 参数 + +- `relativePath` - `editor/resources/` 下的相对路径。 + +## 当前语义 + +- 当前实现会拼接： + +```text +{repo root}/editor/resources/{relativePath} +``` + +- 然后再调用 [NormalizeSceneViewportResourcePath](NormalizeSceneViewportResourcePath.md) 输出规范化结果。 + +## 返回值 + +- 规范化后的绝对资源路径字符串。 + +## 相关文档 + +- [SceneViewportResourcePaths](SceneViewportResourcePaths.md) +- [GetSceneViewportResourceRepoRootPath](GetSceneViewportResourceRepoRootPath.md) +- [NormalizeSceneViewportResourcePath](NormalizeSceneViewportResourcePath.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/GetSceneViewportCameraGizmoIconPath.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/GetSceneViewportCameraGizmoIconPath.md new file mode 100644 index 00000000..e491607e --- /dev/null +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/GetSceneViewportCameraGizmoIconPath.md @@ -0,0 +1,21 @@ +# GetSceneViewportCameraGizmoIconPath + +返回 Scene View camera gizmo icon 的资源路径。 + +```cpp +inline Containers::String GetSceneViewportCameraGizmoIconPath(); +``` + +## 当前语义 + +- 当前实现把 `Icons/camera_gizmo.png` 交给 [BuildSceneViewportEditorResourcePath](BuildSceneViewportEditorResourcePath.md)。 +- 返回值指向 repo 内 `editor/resources/Icons/camera_gizmo.png`。 + +## 测试覆盖 + +- `tests/Editor/test_scene_viewport_shader_paths.cpp` 验证了这里返回的是绝对路径，且目标 icon 文件存在。 + +## 相关文档 + +- [SceneViewportResourcePaths](SceneViewportResourcePaths.md) +- [BuildSceneViewportEditorResourcePath](BuildSceneViewportEditorResourcePath.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/GetSceneViewportInfiniteGridShaderPath.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/GetSceneViewportInfiniteGridShaderPath.md new file mode 100644 index 00000000..979255e1 --- /dev/null +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/GetSceneViewportInfiniteGridShaderPath.md @@ -0,0 +1,27 @@ +# GetSceneViewportInfiniteGridShaderPath + +返回 Scene View infinite-grid shader 的资源路径。 + +```cpp +inline Containers::String GetSceneViewportInfiniteGridShaderPath(); +``` + +## 当前语义 + +- 当前实现把相对路径： + +```text +shaders/scene-viewport/infinite-grid/infinite-grid.shader +``` + +交给 [BuildSceneViewportEditorResourcePath](BuildSceneViewportEditorResourcePath.md)，最终得到 repo 内 `editor/resources/` 下的绝对路径。 + +## 测试覆盖 + +- `tests/Editor/test_scene_viewport_shader_paths.cpp` 验证了这里返回的是绝对路径、目标文件存在，并且 `ShaderLoader` 能成功加载该 shader。 + +## 相关文档 + +- [SceneViewportResourcePaths](SceneViewportResourcePaths.md) +- [BuildSceneViewportEditorResourcePath](BuildSceneViewportEditorResourcePath.md) +- [BuiltinInfiniteGridPass](../../../Rendering/Passes/BuiltinInfiniteGridPass/BuiltinInfiniteGridPass.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/GetSceneViewportMainLightGizmoIconPath.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/GetSceneViewportMainLightGizmoIconPath.md new file mode 100644 index 00000000..56f21b24 --- /dev/null +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/GetSceneViewportMainLightGizmoIconPath.md @@ -0,0 +1,21 @@ +# GetSceneViewportMainLightGizmoIconPath + +返回 Scene View main-light gizmo icon 的资源路径。 + +```cpp +inline Containers::String GetSceneViewportMainLightGizmoIconPath(); +``` + +## 当前语义 + +- 当前实现把 `Icons/main_light_gizmo.png` 交给 [BuildSceneViewportEditorResourcePath](BuildSceneViewportEditorResourcePath.md)。 +- 返回值指向 repo 内 `editor/resources/Icons/main_light_gizmo.png`。 + +## 测试覆盖 + +- `tests/Editor/test_scene_viewport_shader_paths.cpp` 验证了这里返回的是绝对路径，且目标 icon 文件存在。 + +## 相关文档 + +- [SceneViewportResourcePaths](SceneViewportResourcePaths.md) +- [BuildSceneViewportEditorResourcePath](BuildSceneViewportEditorResourcePath.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/GetSceneViewportObjectIdOutlineShaderPath.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/GetSceneViewportObjectIdOutlineShaderPath.md new file mode 100644 index 00000000..bd5d3cc2 --- /dev/null +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/GetSceneViewportObjectIdOutlineShaderPath.md @@ -0,0 +1,27 @@ +# GetSceneViewportObjectIdOutlineShaderPath + +返回 Scene View object-id outline shader 的资源路径。 + +```cpp +inline Containers::String GetSceneViewportObjectIdOutlineShaderPath(); +``` + +## 当前语义 + +- 当前实现把相对路径： + +```text +shaders/scene-viewport/object-id-outline/object-id-outline.shader +``` + +交给 [BuildSceneViewportEditorResourcePath](BuildSceneViewportEditorResourcePath.md)，最终得到 repo 内 `editor/resources/` 下的绝对路径。 + +## 测试覆盖 + +- `tests/Editor/test_scene_viewport_shader_paths.cpp` 验证了这里返回的路径存在，并且 `ResourceManager` 能按该路径加载 outline shader。 + +## 相关文档 + +- [SceneViewportResourcePaths](SceneViewportResourcePaths.md) +- [BuildSceneViewportEditorResourcePath](BuildSceneViewportEditorResourcePath.md) +- [BuiltinObjectIdOutlinePass](../../../Rendering/Passes/BuiltinObjectIdOutlinePass/BuiltinObjectIdOutlinePass.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/GetSceneViewportResourceRepoRootPath.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/GetSceneViewportResourceRepoRootPath.md new file mode 100644 index 00000000..df739fea --- /dev/null +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/GetSceneViewportResourceRepoRootPath.md @@ -0,0 +1,25 @@ +# Detail::GetSceneViewportResourceRepoRootPath + +返回当前 Scene View 资源路径拼接使用的 repo root。 + +```cpp +inline std::filesystem::path GetSceneViewportResourceRepoRootPath(); +``` + +## 当前语义 + +- 如果定义了编译宏 `XCENGINE_EDITOR_REPO_ROOT`，当前实现会直接把该宏值转换成 `std::filesystem::path`。 +- 否则会以当前头文件 `__FILE__` 为起点，连续 `parent_path()` 三次回退到 repo root。 + +## 设计含义 + +- 这让编辑器既可以在已知 repo root 的构建环境下使用固定路径，也可以在本地源码树中按相对位置推导资源根目录。 + +## 返回值 + +- 推导出的 repo root 路径。 + +## 相关文档 + +- [SceneViewportResourcePaths](SceneViewportResourcePaths.md) +- [BuildSceneViewportEditorResourcePath](BuildSceneViewportEditorResourcePath.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/NormalizeSceneViewportResourcePath.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/NormalizeSceneViewportResourcePath.md new file mode 100644 index 00000000..d65d220d --- /dev/null +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/NormalizeSceneViewportResourcePath.md @@ -0,0 +1,30 @@ +# Detail::NormalizeSceneViewportResourcePath + +把 `std::filesystem::path` 规范化并转成 `Containers::String`。 + +```cpp +inline Containers::String NormalizeSceneViewportResourcePath(const std::filesystem::path& path); +``` + +## 当前语义 + +- 当前实现等价于： + +```cpp +return Containers::String(path.lexically_normal().generic_string().c_str()); +``` + +- 这意味着它会先做 `lexically_normal()`，再统一输出使用 `/` 分隔的 generic path 字符串。 + +## 参数 + +- `path` - 待规范化的文件系统路径。 + +## 返回值 + +- 规范化后的 `Containers::String` 路径。 + +## 相关文档 + +- [SceneViewportResourcePaths](SceneViewportResourcePaths.md) +- [BuildSceneViewportEditorResourcePath](BuildSceneViewportEditorResourcePath.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/SceneViewportResourcePaths.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/SceneViewportResourcePaths.md new file mode 100644 index 00000000..f4cc1a7a --- /dev/null +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/SceneViewportResourcePaths.md @@ -0,0 +1,49 @@ +# SceneViewportResourcePaths + +**命名空间**: `XCEngine::Editor` + +**类型**: `inline helper header` + +**源文件**: `editor/src/Viewport/SceneViewportResourcePaths.h` + +**描述**: 为 Scene View 相关 shader 与 icon 资源生成 repo 内绝对路径的 inline helper 头文件。 + +## 概览 + +`SceneViewportResourcePaths.h` 当前是 Scene View 资源路径解析的实际定义位置。 + +它负责： + +- 定位 editor repo root。 +- 把相对路径拼到 `editor/resources/` 下。 +- 规范化为 `Containers::String`。 +- 返回 infinite-grid shader、object-id outline shader、camera icon、main-light icon 的绝对路径。 + +`SceneViewportShaderPaths.h` 当前只是包含这个头文件的轻量兼容层。 + +## 公开 helper + +| 成员 | 说明 | +|------|------| +| [NormalizeSceneViewportResourcePath](NormalizeSceneViewportResourcePath.md) | 规范化 `std::filesystem::path` 并转成 `Containers::String`。 | +| [GetSceneViewportResourceRepoRootPath](GetSceneViewportResourceRepoRootPath.md) | 推导 repo root。 | +| [BuildSceneViewportEditorResourcePath](BuildSceneViewportEditorResourcePath.md) | 把相对路径拼到 `editor/resources/` 下。 | +| [GetSceneViewportInfiniteGridShaderPath](GetSceneViewportInfiniteGridShaderPath.md) | 返回 Scene View infinite-grid shader 路径。 | +| [GetSceneViewportObjectIdOutlineShaderPath](GetSceneViewportObjectIdOutlineShaderPath.md) | 返回 Scene View object-id outline shader 路径。 | +| [GetSceneViewportCameraGizmoIconPath](GetSceneViewportCameraGizmoIconPath.md) | 返回 camera gizmo icon 路径。 | +| [GetSceneViewportMainLightGizmoIconPath](GetSceneViewportMainLightGizmoIconPath.md) | 返回 main-light gizmo icon 路径。 | + +## 测试覆盖 + +- `tests/Editor/test_scene_viewport_shader_paths.cpp` 验证了这些 helper 返回的路径是绝对路径、文件实际存在，并能成功加载 Scene View shader 资源。 + +## 相关文档 + +- [NormalizeSceneViewportResourcePath](NormalizeSceneViewportResourcePath.md) +- [GetSceneViewportResourceRepoRootPath](GetSceneViewportResourceRepoRootPath.md) +- [BuildSceneViewportEditorResourcePath](BuildSceneViewportEditorResourcePath.md) +- [GetSceneViewportInfiniteGridShaderPath](GetSceneViewportInfiniteGridShaderPath.md) +- [GetSceneViewportObjectIdOutlineShaderPath](GetSceneViewportObjectIdOutlineShaderPath.md) +- [GetSceneViewportCameraGizmoIconPath](GetSceneViewportCameraGizmoIconPath.md) +- [GetSceneViewportMainLightGizmoIconPath](GetSceneViewportMainLightGizmoIconPath.md) +- [SceneViewportShaderPaths](../SceneViewportShaderPaths/SceneViewportShaderPaths.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportShaderPaths/BuildSceneViewportShaderPath.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportShaderPaths/BuildSceneViewportShaderPath.md index 6b550f91..bd0dda63 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportShaderPaths/BuildSceneViewportShaderPath.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportShaderPaths/BuildSceneViewportShaderPath.md @@ -1,31 +1,31 @@ # Detail::BuildSceneViewportShaderPath -把 Scene View shader 相对路径拼成 repo 内绝对资源路径字符串。 +当前已不是 `SceneViewportShaderPaths.h` 里的真实 helper；此页仅保留迁移说明。 -```cpp -inline Containers::String BuildSceneViewportShaderPath(const std::filesystem::path& relativePath); -``` +## 当前状态 -## 行为说明 +- 现行 `editor/src/Viewport/SceneViewportShaderPaths.h` 不再声明 `BuildSceneViewportShaderPath(...)`。 +- 路径构建职责已经迁移到 [Detail::BuildSceneViewportEditorResourcePath](../SceneViewportResourcePaths/BuildSceneViewportEditorResourcePath.md)。 -当前实现会拼接： +## 迁移方式 + +- 如果旧调用点想得到： ```text {repo root}/editor/resources/shaders/scene-viewport/{relativePath} ``` -然后再调用 [NormalizeSceneViewportShaderPath](NormalizeSceneViewportShaderPath.md) 输出规范化结果。 +- 当前应改为调用 `BuildSceneViewportEditorResourcePath()`，并传入完整相对路径： -## 参数 +```text +shaders/scene-viewport/{relativePath} +``` -- `relativePath` - `scene-viewport` 目录下的相对 shader 路径。 - -## 返回值 - -- `Containers::String` - 规范化后的完整资源路径。 +- 如果目标只是 infinite-grid 或 object-id outline shader，优先直接使用更高层的专用 getter。 ## 相关文档 - [SceneViewportShaderPaths](SceneViewportShaderPaths.md) -- [GetSceneViewportShaderRepoRootPath](GetSceneViewportShaderRepoRootPath.md) -- [NormalizeSceneViewportShaderPath](NormalizeSceneViewportShaderPath.md) +- [BuildSceneViewportEditorResourcePath](../SceneViewportResourcePaths/BuildSceneViewportEditorResourcePath.md) +- [GetSceneViewportInfiniteGridShaderPath](../SceneViewportResourcePaths/GetSceneViewportInfiniteGridShaderPath.md) +- [GetSceneViewportObjectIdOutlineShaderPath](../SceneViewportResourcePaths/GetSceneViewportObjectIdOutlineShaderPath.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportShaderPaths/GetSceneViewportInfiniteGridShaderPath.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportShaderPaths/GetSceneViewportInfiniteGridShaderPath.md index 0a105a6e..5fd39116 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportShaderPaths/GetSceneViewportInfiniteGridShaderPath.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportShaderPaths/GetSceneViewportInfiniteGridShaderPath.md @@ -1,31 +1,18 @@ # GetSceneViewportInfiniteGridShaderPath -返回 Scene View 无限网格 shader 的资源路径。 +通过兼容头 `SceneViewportShaderPaths.h` 可见的 Scene View infinite-grid shader 路径 helper。 ```cpp inline Containers::String GetSceneViewportInfiniteGridShaderPath(); ``` -## 行为说明 +## 当前语义 -当前实现把相对路径： - -```text -infinite-grid/infinite-grid.shader -``` - -交给 [BuildSceneViewportShaderPath](BuildSceneViewportShaderPath.md)，最终得到 repo 内 `editor/resources/shaders/scene-viewport/infinite-grid/infinite-grid.shader` 的规范化字符串路径。 - -## 当前使用位置 - -- `SceneViewportGridPassRenderer` 构造时把这个路径交给 Runtime 侧 `BuiltinInfiniteGridPass` - -## 返回值 - -- `Containers::String` - 无限网格 shader 路径。 +- 当前函数的真实声明位于 [SceneViewportResourcePaths](../SceneViewportResourcePaths/SceneViewportResourcePaths.md)，`SceneViewportShaderPaths.h` 只是通过 `#include` 把它重新暴露给旧调用点。 +- 因此路径解析、规范化和测试覆盖，都应以资源路径头的文档为准。 ## 相关文档 - [SceneViewportShaderPaths](SceneViewportShaderPaths.md) -- [BuildSceneViewportShaderPath](BuildSceneViewportShaderPath.md) -- [SceneViewportGridPass](../Passes/SceneViewportGridPass/SceneViewportGridPass.md) +- [GetSceneViewportInfiniteGridShaderPath](../SceneViewportResourcePaths/GetSceneViewportInfiniteGridShaderPath.md) +- [SceneViewportResourcePaths](../SceneViewportResourcePaths/SceneViewportResourcePaths.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportShaderPaths/GetSceneViewportObjectIdOutlineShaderPath.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportShaderPaths/GetSceneViewportObjectIdOutlineShaderPath.md index 74f90026..253711fc 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportShaderPaths/GetSceneViewportObjectIdOutlineShaderPath.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportShaderPaths/GetSceneViewportObjectIdOutlineShaderPath.md @@ -1,31 +1,18 @@ # GetSceneViewportObjectIdOutlineShaderPath -返回 Scene View object-id outline shader 的资源路径。 +通过兼容头 `SceneViewportShaderPaths.h` 可见的 Scene View object-id outline shader 路径 helper。 ```cpp inline Containers::String GetSceneViewportObjectIdOutlineShaderPath(); ``` -## 行为说明 +## 当前语义 -当前实现把相对路径： - -```text -object-id-outline/object-id-outline.shader -``` - -交给 [BuildSceneViewportShaderPath](BuildSceneViewportShaderPath.md)，最终得到 repo 内 `editor/resources/shaders/scene-viewport/object-id-outline/object-id-outline.shader` 的规范化字符串路径。 - -## 当前使用位置 - -- `SceneViewportSelectionOutlinePassRenderer` 构造时把这个路径交给 Runtime 侧 `BuiltinObjectIdOutlinePass` - -## 返回值 - -- `Containers::String` - object-id outline shader 路径。 +- 当前函数的真实声明位于 [SceneViewportResourcePaths](../SceneViewportResourcePaths/SceneViewportResourcePaths.md)，`SceneViewportShaderPaths.h` 只是通过 `#include` 把它重新暴露给旧调用点。 +- 因此路径解析、规范化和测试覆盖，都应以资源路径头的文档为准。 ## 相关文档 - [SceneViewportShaderPaths](SceneViewportShaderPaths.md) -- [BuildSceneViewportShaderPath](BuildSceneViewportShaderPath.md) -- [SceneViewportSelectionOutlinePass](../Passes/SceneViewportSelectionOutlinePass/SceneViewportSelectionOutlinePass.md) +- [GetSceneViewportObjectIdOutlineShaderPath](../SceneViewportResourcePaths/GetSceneViewportObjectIdOutlineShaderPath.md) +- [SceneViewportResourcePaths](../SceneViewportResourcePaths/SceneViewportResourcePaths.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportShaderPaths/GetSceneViewportShaderRepoRootPath.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportShaderPaths/GetSceneViewportShaderRepoRootPath.md index 87808fe4..7f51678e 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportShaderPaths/GetSceneViewportShaderRepoRootPath.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportShaderPaths/GetSceneViewportShaderRepoRootPath.md @@ -1,27 +1,20 @@ # Detail::GetSceneViewportShaderRepoRootPath -返回当前 Scene View shader 路径拼接所使用的 repo root。 +当前已不是 `SceneViewportShaderPaths.h` 里的真实 helper；此页仅保留迁移说明。 -```cpp -inline std::filesystem::path GetSceneViewportShaderRepoRootPath(); -``` +## 当前状态 -## 行为说明 +- 现行 `editor/src/Viewport/SceneViewportShaderPaths.h` 不再声明 `GetSceneViewportShaderRepoRootPath()`。 +- repo root 推导逻辑已经迁移到 [Detail::GetSceneViewportResourceRepoRootPath](../SceneViewportResourcePaths/GetSceneViewportResourceRepoRootPath.md)。 -当前实现有两条路径： +## 迁移方式 -- 如果定义了 `XCENGINE_EDITOR_REPO_ROOT` - - 直接把这个编译时宏转成 `std::filesystem::path` -- 否则 - - 以当前头文件 `__FILE__` 为起点，连续 `parent_path()` 三次回退到 repo root - -这让编辑器既可以在已知 repo root 的构建环境下直接使用固定路径，也可以在本地源码树里按相对位置回推。 - -## 返回值 - -- `std::filesystem::path` - 当前推导出的 repo root。 +- 旧调用点应改为使用 `GetSceneViewportResourceRepoRootPath()`。 +- 新 helper 仍保留原先的两条分支： + - 优先使用 `XCENGINE_EDITOR_REPO_ROOT` + - 否则基于 `__FILE__` 回退推导 repo root ## 相关文档 - [SceneViewportShaderPaths](SceneViewportShaderPaths.md) -- [BuildSceneViewportShaderPath](BuildSceneViewportShaderPath.md) +- [GetSceneViewportResourceRepoRootPath](../SceneViewportResourcePaths/GetSceneViewportResourceRepoRootPath.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportShaderPaths/NormalizeSceneViewportShaderPath.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportShaderPaths/NormalizeSceneViewportShaderPath.md index a67ee974..72f1432d 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportShaderPaths/NormalizeSceneViewportShaderPath.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportShaderPaths/NormalizeSceneViewportShaderPath.md @@ -1,34 +1,18 @@ # Detail::NormalizeSceneViewportShaderPath -把 `std::filesystem::path` 规范化并转成 `Containers::String`。 +当前已不是 `SceneViewportShaderPaths.h` 里的真实 helper；此页仅保留迁移说明。 -```cpp -inline Containers::String NormalizeSceneViewportShaderPath(const std::filesystem::path& path); -``` +## 当前状态 -## 行为说明 +- 现行 `editor/src/Viewport/SceneViewportShaderPaths.h` 不再声明 `NormalizeSceneViewportShaderPath(...)`。 +- 规范化逻辑已经迁移到 [Detail::NormalizeSceneViewportResourcePath](../SceneViewportResourcePaths/NormalizeSceneViewportResourcePath.md)。 -当前实现等价于： +## 迁移方式 -```cpp -return Containers::String(path.lexically_normal().generic_string().c_str()); -``` - -这意味着： - -- 会先做 `lexically_normal()` -- 输出统一使用 `/` 分隔的 generic path -- 返回类型是 Editor / Rendering 侧常用的 `Containers::String` - -## 参数 - -- `path` - 待规范化的文件系统路径。 - -## 返回值 - -- `Containers::String` - 规范化后的字符串路径。 +- 旧调用点应改为使用 `NormalizeSceneViewportResourcePath()`。 +- 新 helper 仍然执行 `lexically_normal().generic_string()` 并返回 `Containers::String`，只是名字从 shader 专用改成了更通用的 resource 路径语义。 ## 相关文档 - [SceneViewportShaderPaths](SceneViewportShaderPaths.md) -- [BuildSceneViewportShaderPath](BuildSceneViewportShaderPath.md) +- [NormalizeSceneViewportResourcePath](../SceneViewportResourcePaths/NormalizeSceneViewportResourcePath.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportShaderPaths/SceneViewportShaderPaths.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportShaderPaths/SceneViewportShaderPaths.md index 45819b06..4e6dcb62 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportShaderPaths/SceneViewportShaderPaths.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportShaderPaths/SceneViewportShaderPaths.md @@ -2,54 +2,43 @@ **命名空间**: `XCEngine::Editor` -**类型**: `inline helper header` +**类型**: `compatibility header` **源文件**: `editor/src/Viewport/SceneViewportShaderPaths.h` -**描述**: 为 Scene View 的 editor-owned GPU pass 生成 repo 内 shader 资源路径。 +**描述**: 当前仅作为兼容层存在的 Scene View 资源路径头文件，头文件本体只包含 `SceneViewportResourcePaths.h`，不再自己定义 helper。 ## 概览 -`SceneViewportShaderPaths.h` 是一个纯 inline helper 头文件。它不负责加载 shader，也不触碰 `AssetDatabase`；当前职责只是把 repo 根目录和 Scene View shader 相对路径拼成稳定的 `Containers::String`。 +`SceneViewportShaderPaths.h` 现在的实现只有一行： -这组 helper 当前服务于两条 editor-owned pass 路径： +```cpp +#include "SceneViewportResourcePaths.h" +``` -- [SceneViewportGridPass](../Passes/SceneViewportGridPass/SceneViewportGridPass.md) -- [SceneViewportSelectionOutlinePass](../Passes/SceneViewportSelectionOutlinePass/SceneViewportSelectionOutlinePass.md) +这意味着： -## 当前实现行为 +- 当前实际的路径 helper 定义位置已经迁移到 [SceneViewportResourcePaths](../SceneViewportResourcePaths/SceneViewportResourcePaths.md)。 +- 保留这个头文件主要是为了兼容仍然 `#include "Viewport/SceneViewportShaderPaths.h"` 的现有调用点。 +- 新代码若要理解真实声明和语义，应优先看 `SceneViewportResourcePaths.h` 对应的文档。 + +## 当前可见能力 + +- 通过包含链，调用方仍可拿到： + - [GetSceneViewportInfiniteGridShaderPath](GetSceneViewportInfiniteGridShaderPath.md) + - [GetSceneViewportObjectIdOutlineShaderPath](GetSceneViewportObjectIdOutlineShaderPath.md) +- 但这两个 helper 的真实声明已经位于 [SceneViewportResourcePaths](../SceneViewportResourcePaths/SceneViewportResourcePaths.md)。 + +## 迁移说明 + +下列旧页面保留为迁移说明，因为这些 helper 名已经不再是当前头文件里的真实声明： -- [GetSceneViewportShaderRepoRootPath](GetSceneViewportShaderRepoRootPath.md) - - 优先使用编译宏 `XCENGINE_EDITOR_REPO_ROOT` - - 否则回退到基于 `__FILE__` 的相对路径推导 - [BuildSceneViewportShaderPath](BuildSceneViewportShaderPath.md) - - 会把 repo root、`editor/resources/shaders/scene-viewport/` 和传入相对路径拼接起来 - [NormalizeSceneViewportShaderPath](NormalizeSceneViewportShaderPath.md) - - 把 `std::filesystem::path` 规范化成 `Containers::String` -- [GetSceneViewportInfiniteGridShaderPath](GetSceneViewportInfiniteGridShaderPath.md) - - 返回无限网格 shader 路径 -- [GetSceneViewportObjectIdOutlineShaderPath](GetSceneViewportObjectIdOutlineShaderPath.md) - - 返回 object-id outline shader 路径 - -## 当前使用位置 - -- `editor/src/Viewport/Passes/SceneViewportGridPass.cpp` - - `SceneViewportGridPassRenderer` 构造时调用 `GetSceneViewportInfiniteGridShaderPath()` -- `editor/src/Viewport/Passes/SceneViewportSelectionOutlinePass.cpp` - - `SceneViewportSelectionOutlinePassRenderer` 构造时调用 `GetSceneViewportObjectIdOutlineShaderPath()` - -## 当前限制 - -- 这里只负责拼路径，不验证目标文件是否存在 -- 路径策略当前写死在 repo 内 `editor/resources/shaders/scene-viewport/` -- Detail 命名空间下的 helper 也是 header 内直接暴露的 inline 实现，不是独立编译单元 +- [GetSceneViewportShaderRepoRootPath](GetSceneViewportShaderRepoRootPath.md) ## 相关文档 -- [NormalizeSceneViewportShaderPath](NormalizeSceneViewportShaderPath.md) -- [GetSceneViewportShaderRepoRootPath](GetSceneViewportShaderRepoRootPath.md) -- [BuildSceneViewportShaderPath](BuildSceneViewportShaderPath.md) +- [SceneViewportResourcePaths](../SceneViewportResourcePaths/SceneViewportResourcePaths.md) - [GetSceneViewportInfiniteGridShaderPath](GetSceneViewportInfiniteGridShaderPath.md) - [GetSceneViewportObjectIdOutlineShaderPath](GetSceneViewportObjectIdOutlineShaderPath.md) -- [SceneViewportGridPass](../Passes/SceneViewportGridPass/SceneViewportGridPass.md) -- [SceneViewportSelectionOutlinePass](../Passes/SceneViewportSelectionOutlinePass/SceneViewportSelectionOutlinePass.md)