diff --git a/AGENT.md b/AGENT.md index 55fcf007..ff5a0a9b 100644 --- a/AGENT.md +++ b/AGENT.md @@ -4,142 +4,150 @@ 如果 README、旧文档和当前文件树 / `CMakeLists.txt` / 测试 target 冲突，以当前 checkout 为准，并在本次工作里顺手修正文档。 -## 1. 先建立的事实 +## 1. 开工顺序 -- 顶层 `CMakeLists.txt` 当前纳入 `engine/`、`editor/`、`managed/`、`mvs/RenderDoc/` 和 `tests/`。 -- `engine/` 构建静态库 `XCEngine`；`editor/` 构建 `XCEditor`，但输出文件名仍是 `editor/bin//XCEngine.exe`。 -- editor 默认把仓库内的 `project/` 识别为工程根目录，也支持 `--project ` 覆盖。 -- 当前工程不再只是 `Assets/` 目录：已经真实使用 `Assets/ + .meta + Library/` 的工程布局。 -- Mono 运行时与 editor 脚本类发现都从 `/Library/ScriptAssemblies/` 加载程序集。 -- `engine/CMakeLists.txt` 当前对 Vulkan 是硬依赖；`editor/` 和 `tests/` 首次配置会拉取 `ImGui` 和 `googletest`。 - -## 2. 优先阅读顺序 - -进入仓库后，优先看这些文档和入口文件： +进入仓库后，优先按下面顺序建立上下文： 1. [AGENT.md](AGENT.md) 2. [README.md](README.md) -3. [docs/plan/end/RHI模块设计与实现/RHI模块总览.md](docs/plan/end/RHI模块设计与实现/RHI模块总览.md) -4. [docs/plan/Shader与Material系统下一阶段计划.md](docs/plan/Shader与Material系统下一阶段计划.md) -5. [docs/plan/SceneViewport_Overlay_Gizmo_Rework_Plan.md](docs/plan/SceneViewport_Overlay_Gizmo_Rework_Plan.md) -6. [tests/TEST_SPEC.md](tests/TEST_SPEC.md) +3. 相关模块的 `CMakeLists.txt` +4. 对应模块最近的测试目录与聚合 target +5. 对应设计文档 -额外规则： +当前最常用的设计入口： -- 如果任务落在某个模块里，先读该模块的 `CMakeLists.txt` 和最近的测试目录。 -- `tests/TEST_SPEC.md` 仍然适合作为 GT 图规则和 RHI 边界说明，但 target 名称与目录变化时，始终以当前 `tests/CMakeLists.txt` 和子模块 `CMakeLists.txt` 为准。 +- [docs/plan/end/RHI模块设计与实现/RHI模块总览.md](docs/plan/end/RHI模块设计与实现/RHI模块总览.md) +- [docs/plan/Library启动预热与运行时异步加载混合重构计划_2026-04-04.md](docs/plan/Library启动预热与运行时异步加载混合重构计划_2026-04-04.md) +- [docs/plan/Library启动预热与运行时异步加载混合重构计划_进度更新_2026-04-04.md](docs/plan/Library启动预热与运行时异步加载混合重构计划_进度更新_2026-04-04.md) +- [docs/plan/Editor架构说明.md](docs/plan/Editor架构说明.md) +- [docs/plan/Renderer下一阶段_Unity风格Shader体系正式化计划_2026-04-06.md](docs/plan/Renderer下一阶段_Unity风格Shader体系正式化计划_2026-04-06.md) +- [docs/plan/XCUI完整架构设计与执行计划.md](docs/plan/XCUI完整架构设计与执行计划.md) +- [docs/plan/XCUI_Phase_Status_2026-04-05.md](docs/plan/XCUI_Phase_Status_2026-04-05.md) +- [docs/plan/C#脚本模块下一阶段计划.md](docs/plan/C%23脚本模块下一阶段计划.md) +- [tests/TEST_SPEC.md](tests/TEST_SPEC.md) +- [tests/UI/TEST_SPEC.md](tests/UI/TEST_SPEC.md) -## 3. 当前工程状态 +已归档但当前仍常用的背景文档： -### 3.1 Engine 与工程布局 +- [Library资产导入与缓存系统收口计划（归档）](docs/used/Library资产导入与缓存系统收口计划_完成归档_2026-04-03.md) +- [Shader与Material系统下一阶段计划（归档）](docs/used/Shader与Material系统下一阶段计划_完成归档_2026-04-04.md) +- [SceneViewport Overlay / Gizmo 重构计划（归档）](docs/used/SceneViewport_Overlay_Gizmo_Rework_Plan_完成归档_2026-04-04.md) +- [Unity式 SceneView Gizmo 正式化方案（归档）](docs/used/Unity式SceneView_Gizmo系统完整审查与正式化重构方案_完成归档_2026-04-06.md) -当前仓库已经不在“先把底层 sample 跑起来”的阶段，而是已经形成： +如果任务落在 API 文档： -- `RHI` -- `Rendering` -- `Editor viewport` -- `AssetDatabase / Library` -- `Mono scripting` +1. 先检查 `docs/plan/` 下有没有日期更晚的 API 相关计划或归档；当前活跃任务池是 [docs/plan/API文档实时同步任务池_2026-04-03.md](docs/plan/API文档实时同步任务池_2026-04-03.md)。这份任务池目前已经推进到第三轮 `T01-T20` 全部完成，结构审计保持全绿，但开始新一轮前仍要先确认是否又追加了新任务块。 +2. 再看 [docs/api-skill.md](docs/api-skill.md)。 +3. 再看 `docs/api/_meta/rebuild-status.md`。 +4. 一次只认领一个任务块，先改状态为 `DOING`，只写自己任务块允许的范围。 -这几条主线之间的真实对接。 +## 2. 当前工程事实 -`Core/Asset/AssetDatabase` 现在是当前工程的重要基线，不是预研代码。它已经负责： +- 顶层 `CMakeLists.txt` 当前纳入 `engine/`、`editor/`、`new_editor/`、`managed/`、`mvs/RenderDoc/` 和 `tests/`。 +- `engine/` 构建静态库 `XCEngine`；`editor/` 构建 `XCEditor`，但输出文件名仍是 `editor/bin//XCEngine.exe`。 +- `new_editor/` 当前构建 `XCUIEditorLib`、`XCUIEditorHost`；启用 `XCENGINE_BUILD_XCUI_EDITOR_APP` 时会输出 `new_editor/bin//XCUIEditor.exe`。 +- editor 默认把仓库内的 `project/` 识别为工程根目录，也支持 `--project ` 覆盖。 +- 当前工程真实使用 `Assets/ + .meta + Library/` 的项目布局；`project/Library/` 是当前 workflow 的一部分，不是可随手忽略的垃圾目录。 +- Mono 运行时与 editor 的脚本类发现都从 `/Library/ScriptAssemblies/` 加载程序集。 +- 当前根目录里没有 `native` 占位项；更新目录树或迁移旧文档时，不要继续传播这条过期事实。 +- 当前工作机是 Windows 文件系统；文档里统一写 `tests/Editor/`、`tests/Core/`、`tests/Scripting/` 等真实目录名，不要制造大小写噪音。 +- `engine/CMakeLists.txt` 当前对 Vulkan 是硬依赖；`editor/` 和 `tests/` 首次配置会拉取 `ImGui` 与 `googletest`。 -- 扫描 `Assets/` -- 为资源生成 `.meta` -- 维护 `Library/SourceAssetDB/assets.db` -- 维护 `Library/ArtifactDB/artifacts.db` -- 维护哈希化 `Library/Artifacts/` +## 3. 子系统现状 -因此： +### 3.1 Core / Asset / Resources -- `project/Library/` 虽然可重建，但在当前 workflow 里不是可以随手忽略的“垃圾目录”。 -- 涉及资源导入、meta、artifact、脚本程序集发现时，不要擅自删除 `project/Library/` 或 `.meta` 文件来“清环境”。 +- `Core/Asset/AssetDatabase`、`AssetImportService`、`ProjectAssetIndex`、`ResourceManager` 已形成正式导入与运行时加载链路。 +- 当前真实职责包括： + - 扫描 `Assets/` + - 为资源生成 `.meta` + - 维护 `Library/SourceAssetDB/assets.db` + - 维护 `Library/ArtifactDB/artifacts.db` + - 写入 `Library/Artifacts/` +- 最新活跃设计文档已经把下一阶段目标收口到“启动阶段前置恢复索引 / 缓存状态，运行时按需异步加载 payload”。 +- `BootstrapProject()` / `BootstrapProjectAssets()` 已正式接入启动链路；接下来重点是指标固化、UI 状态拆分和剩余同步兜底点审计。 +- 当前还不要把 `AssetImportService`、`ProjectAssetIndex`、`ResourceManager` 的职责重新揉回一团；先看 [docs/plan/Library启动预热与运行时异步加载混合重构计划_2026-04-04.md](docs/plan/Library启动预热与运行时异步加载混合重构计划_2026-04-04.md)。 +- 材质 artifact 当前是 schema v2： + - `kMaterialArtifactSchemaVersion = 2` + - magic `XCMAT02` + - texture binding 序列化三元组是 `binding name + encoded AssetRef + optional path` +- `Material` 当前同时维护 loaded handle、稳定 `AssetRef` 与 path 元数据；`GetTexture()` 首次访问时可触发懒加载，`GetTextureBindingLoadedTexture()` 不触发加载。 ### 3.2 Rendering -当前 `engine/include/XCEngine/Rendering/` 与 `engine/src/Rendering/` 已经形成正式主链： - -- `SceneRenderer` -- `CameraRenderer` -- `RenderPipeline` -- `RenderSceneExtractor` -- `RenderResourceCache` -- `SceneRenderRequestPlanner` -- `RenderSurface` - -当前已经落地并应被视为正式能力的内容包括： - -- 内建 forward 主几何渲染 -- `ObjectId` 渲染与 editor picking -- `BuiltinInfiniteGridPass` -- `BuiltinObjectIdOutlinePass` -- `CameraRenderRequest::overlayPasses` - -当前 Renderer 的下一阶段主线不是 render graph，而是： - -- shader asset contract -- material GPU binding -- builtin pass contract -- renderer-owned feature contract - -对应设计文档是 [docs/plan/Shader与Material系统下一阶段计划.md](docs/plan/Shader与Material系统下一阶段计划.md)。 +- 当前正式主链是 `SceneRenderer -> CameraRenderer -> RenderPipeline`。 +- 现有正式能力包括： + - forward 主几何渲染 + - `ObjectId` 渲染与 editor picking + - `BuiltinInfiniteGridPass` + - `BuiltinObjectIdOutlinePass` + - `CameraRenderRequest::postScenePasses` + - `CameraRenderRequest::overlayPasses` +- 当前主线不是 render graph，而是 shader / material contract、builtin pass contract 和 renderer-owned feature contract。 ### 3.3 Editor -当前 editor 的事实： +- editor 仍然是 `D3D12` 宿主应用。 +- Scene/Game viewport 已通过引擎 `Rendering + RHI` 输出离屏纹理，再由 editor 宿主接入 ImGui。 +- 当前 Scene View 主链已经显式拆成： + - `SceneViewportChrome` + - `SceneViewportInteractionFrame` + - `SceneViewportNavigation` + - `SceneViewportTransformGizmoCoordinator` + - `ViewportHostService` +- `editor/src/Viewport/` 当前稳定存在的关键入口包括： + - `SceneViewportCameraController` + - `SceneViewportChrome` + - `SceneViewportEditorModes` + - `SceneViewportHudOverlay` + - `SceneViewportInteractionActions` + - `SceneViewportInteractionFrame` + - `SceneViewportInteractionResolver` + - `SceneViewportMoveGizmo` + - `SceneViewportNavigation` + - `SceneViewportOverlayBuilder` + - `SceneViewportOverlayFrameCache` + - `SceneViewportOverlayProviders` + - `SceneViewportOverlaySpriteResources` + - `SceneViewportPassSpecs` + - `SceneViewportPicker` + - `SceneViewportResourcePaths` + - `SceneViewportRotateGizmo` + - `SceneViewportScaleGizmo` + - `SceneViewportShaderPaths` + - `SceneViewportTransformGizmoCoordinator` + - `SceneViewportTransformGizmoFrameBuilder` + - `ViewportHostRenderFlowUtils` + - `ViewportHostRenderTargets` + - `ViewportHostSurfaceUtils` + - `ViewportObjectIdPicker` +- `SceneViewportShaderPaths.h` 当前主要是兼容 include；路径真实 owner 已转到 `SceneViewportResourcePaths.h`。 +- `tests/Editor/` 已有 `test_scene_viewport_chrome.cpp`、`test_scene_viewport_interaction_frame.cpp`、`test_scene_viewport_navigation.cpp` 与 `test_scene_viewport_transform_gizmo_coordinator.cpp`，不要再按“这些 helper 还没落地”理解当前 editor。 -- 它仍然是 `D3D12` 宿主应用。 -- Scene/Game viewport 已经通过引擎 `Rendering + RHI` 输出离屏纹理。 -- `ViewportHostService` 是 editor 与 renderer 的关键接线层。 -- object-id picking、selection outline、scene icon / gizmo overlay 已经进入正规化收口阶段。 +### 3.4 XCUI / New Editor -当前 `editor/src/Viewport/` 已经存在： +- `new_editor/` 是当前 `XCUI` editor sandbox 主线；旧 `editor/` 的整体替换仍处于延后状态，不要把 `XCUI` 计划误读成“已经整体替换现有 editor”。 +- 当前宿主分层是： + - `XCUIEditorLib` + - `XCUIEditorHost` + - `XCUIEditorApp`（可选应用壳） +- 共享 UI core、runtime screen host 与 widget 基础能力主要沉淀在 `engine/include/XCEngine/UI/` 与 `engine/src/UI/`；`new_editor/` 负责 XCUI editor 壳、宿主与 widget sandbox。 +- XCUI / new_editor 的测试规范以 [tests/UI/TEST_SPEC.md](tests/UI/TEST_SPEC.md) 为准；根目录虽然有 `tests/NewEditor/`，但当前具体测试实现主要放在 `tests/UI/` 下。 -- `SceneViewportOverlayBuilder` -- `SceneViewportEditorOverlayPass` -- `SceneViewportPicker` -- `SceneViewportMoveGizmo` -- `SceneViewportRotateGizmo` -- `SceneViewportScaleGizmo` +### 3.5 Scripting -这意味着： +- 当前脚本链路由三部分组成： + - `managed/XCEngine.ScriptCore/` + - `managed/GameScripts/` + - `project/Assets/**/*.cs` +- 构建结果分两类： + - `xcengine_managed_assemblies` 生成引擎示例程序集 + - `xcengine_project_managed_assemblies` 生成项目脚本程序集，并复制到 `project/Library/ScriptAssemblies/` +- `project/Library/ScriptAssemblies/` 里的当前快照可能落后于目标态；判断“成功构建后应有哪些程序集”时，以 `managed/CMakeLists.txt`、`editor/src/Scripting/EditorScriptAssemblyBuilder.cpp` 与对应测试为准，而不是只看工作树里此刻存着什么。 +- `ScriptEngine` 当前已具备脚本类发现、字段元数据读取、默认值读取、stored override 管理和运行时 managed field 同步。 +- Inspector 侧已经存在 `ScriptComponentEditor`；脚本相关改动通常同时影响 `engine/src/Scripting/`、`managed/`、`project/Assets/Scripts/`、`editor/src/ComponentEditors/` 与 `tests/Scripting/` / `tests/Editor/`。 -- editor 是宿主，不是第二套 renderer。 -- 新的世界空间 overlay，不应继续堆回 `SceneViewPanel.cpp` 的 ImGui world overlay 路径。 -- 优先沿 `overlayPasses -> overlay builder -> canonical frame data -> overlay pass` 方向扩展。 - -### 3.4 Scripting - -当前脚本链路由三部分组成： - -- `managed/XCEngine.ScriptCore/` -- `managed/GameScripts/` -- `project/Assets/**/*.cs` - -构建结果分两类： - -- `xcengine_managed_assemblies` 生成引擎示例程序集 -- `xcengine_project_managed_assemblies` 生成项目脚本程序集，并复制到 `project/Library/ScriptAssemblies/` - -`ScriptEngine` 当前已经具备： - -- 脚本类发现 -- 字段元数据读取 -- 默认值读取 -- stored override 管理 -- 运行时 managed field 同步 - -Inspector 侧已经存在 `ScriptComponentEditor`，因此脚本相关改动通常同时影响： - -- `engine/src/Scripting/` -- `managed/` -- `project/Assets/Scripts/` -- `editor/src/ComponentEditors/` -- `tests/Scripting/` -- `tests/Editor/test_script_component_editor_utils.cpp` - -### 3.5 Tests +### 3.6 Tests 当前测试主目录包括： @@ -147,14 +155,17 @@ Inspector 侧已经存在 `ScriptComponentEditor`，因此脚本相关改动通 - `tests/Core/` - `tests/Debug/` - `tests/Editor/` +- `tests/Fixtures/` - `tests/Input/` - `tests/Memory/` +- `tests/NewEditor/` - `tests/Rendering/` - `tests/Resources/` - `tests/RHI/` - `tests/Scene/` - `tests/Scripting/` - `tests/Threading/` +- `tests/UI/` 需要特别记住的聚合 target： @@ -162,6 +173,9 @@ Inspector 侧已经存在 `ScriptComponentEditor`，因此脚本相关改动通 - `rendering_all_tests` - `rendering_phase_regression` - `editor_tests` +- `core_ui_tests` +- `editor_ui_tests` +- `runtime_ui_tests` - `scripting_tests` ## 4. 不可忽视的硬约束 @@ -175,7 +189,18 @@ Inspector 侧已经存在 `ScriptComponentEditor`，因此脚本相关改动通 不要沿用“计划中但未落地”的旧说法。 -### 4.2 RHI 抽象层与后端层必须分层 +### 4.2 不要随手清空 `project/Library/` 或删 `.meta` + +`project/Library/` 虽然可重建，但它在当前 workflow 里承载： + +- `SourceAssetDB` +- `ArtifactDB` +- `Artifacts` +- `ScriptAssemblies` + +涉及资源导入、artifact、脚本程序集发现时，不要把删库重建当作默认修复手段。 + +### 4.3 RHI 抽象层与后端层必须分层 `tests/RHI/unit/` 与 `tests/RHI/integration/` 只能依赖公共 RHI 抽象。 @@ -187,7 +212,7 @@ Inspector 侧已经存在 `ScriptComponentEditor`，因此脚本相关改动通 如果必须这么做，优先修 RHI，而不是污染测试边界。 -### 4.3 Editor 是宿主，不是第二套渲染器 +### 4.4 Editor 是宿主，不是第二套渲染器 如果 viewport、outline、picking 或 gizmo 有问题，优先判断： @@ -195,28 +220,25 @@ Inspector 侧已经存在 `ScriptComponentEditor`，因此脚本相关改动通 - 是 `RenderSurface` / RHI 输出问题 - 还是 editor 宿主接线问题 -不要因为 editor 当前是 D3D12 host，就把问题草率地塞回 editor 私有渲染逻辑。 +不要因为 editor 当前是 D3D12 host，就把问题草率塞回 editor 私有渲染逻辑。 -### 4.4 不要再扩写 ImGui world overlay +### 4.5 不要再把新逻辑堆回旧的 ImGui world overlay -当前 viewport overlay / gizmo 已有明确收口方向。新功能若仍然继续堆在： +新的世界空间 overlay / gizmo 逻辑如果仍然直接堆在： - `SceneViewPanel.cpp` -- `SceneViewportOverlayRenderer.cpp` 的 ImGui world draw 路径 +- panel 层临时拼的 immediate draw / ad-hoc overlay 路径 -通常就是逆着当前架构方向在走。 - -优先入口是： +通常就是逆着当前架构方向在走。优先入口是： - `CameraRenderRequest::overlayPasses` - `SceneViewportOverlayBuilder` - `SceneViewportEditorOverlayPass` +- `SceneViewportTransformGizmoCoordinator` -### 4.5 backpack 导入行为必须统一 +### 4.6 `backpack` 导入行为必须统一 -这是仓库里已经踩过的真实坑。 - -`backpack` 相关资源在以下路径中的导入行为必须保持一致： +这是仓库里已经踩过的真实坑。`backpack` 相关资源在以下路径中的导入行为必须保持一致： - editor - runtime @@ -225,7 +247,7 @@ Inspector 侧已经存在 `ScriptComponentEditor`，因此脚本相关改动通 不要只在局部路径里额外加 `MeshImportFlags::FlipUVs` 之类的补丁。 -### 4.6 `mvs/` 不是长期主线模块 +### 4.7 `mvs/` 不是长期主线模块 `mvs/` 里有样例、研究和工具，但当前正式引擎逻辑的长期落点应优先是： @@ -236,6 +258,20 @@ Inspector 侧已经存在 `ScriptComponentEditor`，因此脚本相关改动通 不要把正式渲染逻辑重新堆回 sample 子树长期存活。 +### 4.8 API 文档任务必须看最新计划并复跑审计 + +只要任务涉及 `docs/api/`： + +1. 先检查 `docs/plan/` 下有没有更新日期更晚的 API 计划或归档。 +2. 以最新任务池和 [docs/api-skill.md](docs/api-skill.md) 为执行规范。 +3. 改完必须重新执行： + +```powershell +python -B docs/api/_tools/audit_api_docs.py +``` + +如果审计没回绿，不算完成。 + ## 5. 推荐构建与验证入口 ### 5.1 配置 @@ -268,7 +304,7 @@ cmake --build build --config Debug --target scripting_tests - 改 `engine/RHI`：先跑 `rhi_abstraction_tests` 或 `rhi_backend_tests`，再决定是否扩展到 `rhi_all_tests` - 改 `engine/Rendering`：先跑 `rendering_unit_tests` 和最相关的 `rendering_integration_*`，必要时再跑 `rendering_phase_regression` -- 改 `editor/Viewport` 或 Inspector：先跑 `editor_tests` +- 改 `editor/Viewport`、`editor/UI` 或 Inspector：先跑 `editor_tests` - 改 `engine/Scripting`、`managed/`、`project/Assets/Scripts/`：先构建 `xcengine_project_managed_assemblies`，再跑 `scripting_tests` - 改资源导入、`.meta`、artifact 相关逻辑：优先跑 `tests/Resources/` 里的对应 target @@ -282,10 +318,12 @@ ctest --test-dir build -C Debug --output-on-failure - RHI 抽象与后端：`engine/include/XCEngine/RHI/`、`engine/src/RHI/`、`tests/RHI/` - Rendering 主链与 pass：`engine/include/XCEngine/Rendering/`、`engine/src/Rendering/`、`tests/Rendering/` -- Editor viewport / gizmo / picking：`editor/src/Viewport/`、`editor/src/panels/SceneViewPanel.cpp`、`tests/Editor/` - 资源导入与工程布局：`engine/include/XCEngine/Core/Asset/`、`engine/src/Core/Asset/`、`editor/src/Managers/ProjectManager.cpp`、`project/Assets/`、`project/Library/` +- Material / shader / artifact：`engine/include/XCEngine/Resources/Material/`、`engine/src/Resources/Material/`、`engine/include/XCEngine/Core/Asset/ArtifactFormats.h`、`tests/Resources/Material/` +- Editor viewport / gizmo / picking：`editor/src/Viewport/`、`editor/src/panels/SceneViewPanel.cpp`、`tests/Editor/` +- Editor actions / project routing：`editor/src/Actions/`、`editor/src/Commands/`、`editor/src/Core/`、`editor/src/Managers/`、`tests/Editor/test_action_routing.cpp` - 脚本运行时与程序集：`engine/include/XCEngine/Scripting/`、`engine/src/Scripting/`、`managed/`、`project/Assets/Scripts/`、`tests/Scripting/` -- 默认工程与项目描述：`project/Project.xcproject`、`editor/src/Core/ProjectRootResolver.h`、`editor/src/Utils/ProjectFileUtils.h` +- API 文档：`docs/api/XCEngine/`、`docs/api/_guides/`、`docs/api/_tools/audit_api_docs.py`、`docs/plan/API文档实时同步任务池_2026-04-03.md` ## 7. 适合当前仓库的工作方式 @@ -295,4 +333,4 @@ ctest --test-dir build -C Debug --output-on-failure 4. 目录、target、入口、文档名改了，就同步更新 README / AGENT / 相关说明。 5. 如果任务会有意重建 `project/Library/`、脚本程序集或 `.meta`，在结果里明确说明哪些文件是有意生成的。 -这份文档的作用是给 agent 一个“当前真实工程长什么样”的基线。它本身也必须随着工程演进一起维护，不能再落回旧状态说明。 +这份文档的作用，是给 agent 一条“当前真实工程长什么样”的基线。它本身也必须随着工程演进一起维护，不能再落回旧状态说明。 diff --git a/README.md b/README.md index aeed9f89..a898777d 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,27 @@ # XCEngine -XCEngine 是一个 Windows 优先、编辑器优先的模块化 C++ 游戏引擎工作区。当前主线已经形成 `RHI -> Rendering -> Editor Viewport -> AssetDatabase/Library -> Mono Scripting` 的可运行闭环，不再只是示例代码集合。 +XCEngine 是一个 Windows 优先、编辑器优先的模块化 C++ 游戏引擎工作区。当前主线已经形成 `RHI -> Rendering -> Editor Viewport -> AssetDatabase/Library -> Mono Scripting` 的可运行闭环，不再只是若干独立 sample 的集合。 -这份 README 面向引擎用户：关注怎么进入项目、怎么构建、当前仓库各目录分别负责什么。面向构建本引擎的 coding agent，请看 [AGENT.md](AGENT.md)。 +这份 README 面向引擎用户：重点回答项目是什么、当前能做什么、怎么构建、怎么启动，以及当前仓库各目录分别承担什么职责。面向参与引擎实现和文档维护的 coding agent，请看 [AGENT.md](AGENT.md)。 ## 项目定位 -- `engine/` 提供静态库 `XCEngine`，包含 `RHI`、`Rendering`、`Resources`、`Scene`、`Scripting` 等核心模块。 -- `editor/` 提供桌面编辑器 `XCEditor`，输出文件名为 `XCEngine.exe`，默认打开仓库内的 `project/`。 -- `project/` 是当前随仓库维护的示例工程，已经采用 `Assets/ + .meta + Library/` 的工程布局。 +- `engine/` 构建静态库 `XCEngine`，包含 `RHI`、`Rendering`、`Resources`、`Scene`、`Scripting` 等核心模块。 +- `editor/` 构建桌面编辑器 `XCEditor`，输出文件名仍为 `XCEngine.exe`，默认打开仓库内的 `project/`。 +- `new_editor/` 维护基于 `XCUI` 的新宿主与 UI sandbox，当前与旧 `editor/` 并行演进，应用输出名为 `XCUIEditor.exe`。 +- `project/` 是随仓库维护的示例工程，已经采用 `Assets/ + .meta + Library/` 的工程布局。 - `managed/` 负责 `XCEngine.ScriptCore.dll`、示例 `GameScripts.dll` 以及项目脚本程序集构建。 -- `tests/` 已覆盖 Engine、RHI、Rendering、Editor、Scripting 等主要模块。 +- `tests/` 覆盖 Engine、RHI、Rendering、Editor、Scripting、XCUI 等主线模块。 + +## 当前能力概览 + +- `RHI` 当前维护 `D3D12 / OpenGL / Vulkan` 三后端。 +- `Rendering` 已形成 `SceneRenderer -> CameraRenderer -> RenderPipeline` 主链，支持 `ObjectId`、`InfiniteGrid`、`Outline`、`overlayPasses` 等能力。 +- `Core/Asset` 已经不是简单加载器，当前真实维护 `Assets/.meta/Library` 风格的 `AssetDatabase`、artifact 缓存和项目资源索引。 +- `Library` 当前已经采用“启动阶段恢复索引与缓存状态 + 运行时按需异步恢复 payload”的混合工作流，`BootstrapProject()` 已接入正式启动链路。 +- `Material` 与材质 artifact 已经进入稳定格式阶段，当前 `.xcmat` 使用 schema v2。 +- 编辑器 Scene/Game viewport 已通过引擎 `Rendering + RHI` 链路渲染到离屏纹理，再接入 ImGui。 +- `ScriptComponent` 已打通脚本类发现、字段元数据读取、字段编辑和运行时字段同步。 ## 环境要求 @@ -60,7 +71,7 @@ cmake --build build --config Debug --target xcengine_project_managed_assemblies - `XCEngine` 是引擎静态库。 - `XCEditor` 是编辑器 target，输出文件名仍为 `editor/bin//XCEngine.exe`。 -- `xcengine_managed_assemblies` 生成 `managed/` 示例托管程序集。 +- `xcengine_managed_assemblies` 生成 `managed/` 下的示例托管程序集。 - `xcengine_project_managed_assemblies` 会扫描 `project/Assets/**/*.cs`，并把结果输出到 `project/Library/ScriptAssemblies/`。 ### 3. 启动编辑器 @@ -75,7 +86,7 @@ cmake --build build --config Debug --target xcengine_project_managed_assemblies .\editor\bin\Debug\XCEngine.exe --project D:\Path\To\MyProject ``` -如果 Inspector 里看不到 C# 脚本类，先确认 `project/Library/ScriptAssemblies/` 中已经生成： +如果 Inspector 里看不到 C# 脚本类，先确认 `project/Library/ScriptAssemblies/` 中已经生成下面这 3 个程序集。当前工作树如果暂时缺少 `XCEngine.ScriptCore.dll`，通常说明项目脚本程序集还没有按最新状态完成重建： - `XCEngine.ScriptCore.dll` - `GameScripts.dll` @@ -102,311 +113,413 @@ cmake --build build --config Debug --target scripting_tests ### Engine -- `RHI` 正式维护 `D3D12 / OpenGL / Vulkan` 三后端。 -- `Rendering` 已形成 `SceneRenderer -> CameraRenderer -> RenderPipeline` 主链，包含 `ObjectId`、`InfiniteGrid`、`Outline`、`overlayPasses` 等能力。 -- `Resources` 与 `Core/Asset` 已不只是简单加载器，当前已经具备 `Assets/.meta/Library` 风格的 `AssetDatabase` 与 artifact 缓存。 +- `RHI` 已经不是单后端实验代码，而是 `D3D12 / OpenGL / Vulkan` 三后端并行维护。 +- `Rendering` 当前正式主线是 `SceneRenderer -> CameraRenderer -> RenderPipeline`，而不是 sample 私有渲染分支。 +- `Resources` 与 `Core/Asset` 已形成项目资源导入、artifact 缓存和运行时加载的统一链路。 ### Editor -- 当前 editor 是 `D3D12` 宿主应用，但 Scene/Game viewport 已通过引擎 `Rendering + RHI` 链路渲染到离屏纹理，再接入 ImGui。 -- `Viewport` 相关代码已经进入 overlay/gizmo 正规化阶段，`SceneViewportOverlayBuilder`、`SceneViewportEditorOverlayPass`、`ObjectId` picking 都已落地。 -- Inspector 已支持 `ScriptComponent` 的脚本类选择、字段元数据读取、字段重置与基础编辑。 +- 当前 editor 是 `D3D12` 宿主应用，但 Scene/Game viewport 渲染本身走引擎 `Rendering + RHI`。 +- `Viewport` 子系统当前已经拆成更清晰的链路：`SceneViewportChrome -> SceneViewportInteractionFrame -> SceneViewportNavigation -> SceneViewportTransformGizmoCoordinator -> ViewportHostService`。 +- `tests/Editor/` 已覆盖 `SceneViewportChrome`、`SceneViewportInteractionFrame`、`SceneViewportNavigation`、`SceneViewportTransformGizmoCoordinator` 等新 helper。 ### Project & Scripting -- 示例工程位于 `project/`，当前工程文件是 `Project.xcproject`，启动场景为 `Assets/Scenes/Main.xc`。 -- `project/Assets/` 现已包含 `.meta` 文件，`project/Library/` 则维护 `SourceAssetDB`、`ArtifactDB`、`Artifacts` 与 `ScriptAssemblies`。 -- `managed/` 会生成引擎脚本 API 与示例脚本程序集，项目资产下的 `.cs` 文件也会被单独编译为项目脚本程序集。 +- 示例工程位于 `project/`，工程文件是 `Project.xcproject`，启动场景为 `Assets/Scenes/Main.xc`。 +- `project/Library/` 虽然是生成目录，但在当前 workflow 里承担 `SourceAssetDB`、`ArtifactDB`、`Artifacts`、`ScriptAssemblies` 等关键角色。 +- `managed/` 会生成引擎脚本 API 与示例脚本程序集，项目资产下的 `.cs` 文件也会单独编译为项目脚本程序集。 ### Tests -- `tests/` 已覆盖 `Core`、`Memory`、`Threading`、`Scene`、`Resources`、`RHI`、`Rendering`、`Editor`、`Scripting` 等模块。 -- `tests/Rendering/` 当前已包含 `backpack_scene`、`backpack_lit_scene`、`camera_stack_scene`、`offscreen_scene` 等集成场景。 -- `tests/RHI/` 同时维护抽象层测试与后端专用测试，`D3D12 / OpenGL / Vulkan` 都有独立子树。 +- `tests/` 已覆盖 `Core`、`Memory`、`Threading`、`Scene`、`Resources`、`RHI`、`Rendering`、`Editor`、`Scripting` 等主线模块。 +- `tests/Rendering/` 当前维护一组集成场景测试。 +- `tests/RHI/` 同时维护抽象层测试与后端专用测试。 ## 完整目录结构 -以下目录树以当前工程入口为准，保留了当前 workflow 已经实际使用的生成目录；省略 `.git/`、`build/_deps/` 与临时文件。 +以下目录树按当前工作树整理，保留了当前 workflow 已经真实使用的生成目录与关键子树；省略 `.git/`、`build/_deps/` 与部分重复资源文件。像 `project/.xceditor/thumbs/`、`project/Library/Artifacts/` 这类会随本地导入状态变化的内容，用结构模式表示。 ```text XCEngine/ -├── .gitattributes -├── .gitignore -├── AGENT.md -├── CMakeLists.txt -├── README.md -├── build/ # 本地 CMake 构建输出 -├── docs/ -│ ├── api/ -│ │ ├── XCEngine/ -│ │ ├── _guides/ -│ │ ├── _meta/ -│ │ ├── _tools/ -│ │ └── main.md -│ ├── issues/ -│ ├── plan/ -│ │ ├── end/ -│ │ │ ├── RHI模块设计与实现/ -│ │ │ │ ├── RHIFence.md -│ │ │ │ └── RHI模块总览.md -│ │ │ └── 编辑器与运行时分层架构设计.md -│ │ ├── 开题报告和任务书/ -│ │ ├── 旧版题目/ -│ │ ├── API文档并行更新任务池_2026-04-02.md -│ │ ├── C#脚本模块的设计与实现.md -│ │ ├── Editor架构说明.md -│ │ ├── SceneViewport_Overlay_Gizmo_Rework_Plan.md -│ │ ├── Shader与Material系统下一阶段计划.md -│ │ ├── Unity SRP API参考文档.md -│ │ ├── Unity式Library资产导入与缓存系统重构方案.md -│ │ ├── Unity式Tick系统与PlayMode运行时方案.md -│ │ ├── Unity式Tick系统与PlayMode运行时方案-阶段进展.md -│ │ └── Unity绝区零开发文档还原版.md -│ ├── used/ -│ ├── api-skill.md -│ ├── blueprint-skill.md -│ └── blueprint.md -├── editor/ -│ ├── CMakeLists.txt -│ ├── README.md -│ ├── resources/ -│ │ └── Icons/ -│ ├── src/ -│ │ ├── Actions/ -│ │ ├── Commands/ -│ │ ├── ComponentEditors/ -│ │ ├── Core/ -│ │ ├── Layers/ -│ │ ├── Layout/ -│ │ ├── Managers/ -│ │ ├── panels/ -│ │ ├── Platform/ -│ │ ├── UI/ -│ │ ├── Utils/ -│ │ ├── Viewport/ -│ │ │ ├── Passes/ -│ │ │ ├── SceneViewportOverlayBuilder.cpp -│ │ │ ├── SceneViewportOverlayBuilder.h -│ │ │ ├── SceneViewportOverlayRenderer.cpp -│ │ │ ├── SceneViewportOverlayRenderer.h -│ │ │ ├── SceneViewportPicker.cpp -│ │ │ ├── SceneViewportPicker.h -│ │ │ ├── SceneViewportMoveGizmo.cpp -│ │ │ ├── SceneViewportMoveGizmo.h -│ │ │ ├── SceneViewportRotateGizmo.cpp -│ │ │ ├── SceneViewportRotateGizmo.h -│ │ │ ├── SceneViewportScaleGizmo.cpp -│ │ │ ├── SceneViewportScaleGizmo.h -│ │ │ ├── ViewportHostRenderFlowUtils.h -│ │ │ └── ViewportHostService.h -│ │ ├── Application.cpp -│ │ ├── Application.h -│ │ ├── EditorApp.rc -│ │ ├── Theme.cpp -│ │ ├── Theme.h -│ │ └── main.cpp -│ └── bin/ # 编辑器输出目录，输出名为 XCEngine.exe -├── engine/ -│ ├── CMakeLists.txt -│ ├── include/ -│ │ └── XCEngine/ -│ │ ├── Audio/ -│ │ ├── Components/ -│ │ ├── Core/ -│ │ │ ├── Asset/ -│ │ │ ├── Containers/ -│ │ │ ├── IO/ -│ │ │ └── Math/ -│ │ ├── Debug/ -│ │ ├── Input/ -│ │ ├── Memory/ -│ │ ├── Platform/ -│ │ │ └── Windows/ -│ │ ├── Rendering/ -│ │ │ ├── Passes/ -│ │ │ ├── Pipelines/ -│ │ │ ├── CameraRenderer.h -│ │ │ ├── CameraRenderRequest.h -│ │ │ ├── ObjectIdEncoding.h -│ │ │ ├── ObjectIdPass.h -│ │ │ ├── RenderCameraData.h -│ │ │ ├── RenderContext.h -│ │ │ ├── RenderMaterialUtility.h -│ │ │ ├── RenderPass.h -│ │ │ ├── RenderPipeline.h -│ │ │ ├── RenderPipelineAsset.h -│ │ │ ├── RenderResourceCache.h -│ │ │ ├── RenderSceneExtractor.h -│ │ │ ├── RenderSceneUtility.h -│ │ │ ├── RenderSurface.h -│ │ │ ├── SceneRenderRequestPlanner.h -│ │ │ ├── SceneRenderRequestUtils.h -│ │ │ ├── SceneRenderer.h -│ │ │ └── VisibleRenderObject.h -│ │ ├── Resources/ -│ │ │ ├── AudioClip/ -│ │ │ ├── Material/ -│ │ │ ├── Mesh/ -│ │ │ ├── Shader/ -│ │ │ └── Texture/ -│ │ ├── RHI/ -│ │ │ ├── D3D12/ -│ │ │ ├── OpenGL/ -│ │ │ └── Vulkan/ -│ │ ├── Scene/ -│ │ ├── Scripting/ -│ │ │ └── Mono/ -│ │ └── Threading/ -│ ├── src/ -│ │ ├── Audio/ -│ │ ├── Components/ -│ │ ├── Core/ -│ │ │ ├── Asset/ -│ │ │ ├── Containers/ -│ │ │ ├── IO/ -│ │ │ └── Math/ -│ │ ├── Debug/ -│ │ ├── Input/ -│ │ ├── Memory/ -│ │ ├── Platform/ -│ │ │ └── Windows/ -│ │ ├── Rendering/ -│ │ │ ├── Passes/ -│ │ │ └── Pipelines/ -│ │ ├── Resources/ -│ │ │ ├── AudioClip/ -│ │ │ ├── Material/ -│ │ │ ├── Mesh/ -│ │ │ ├── Shader/ -│ │ │ └── Texture/ -│ │ ├── RHI/ -│ │ │ ├── D3D12/ -│ │ │ ├── OpenGL/ -│ │ │ └── Vulkan/ -│ │ ├── Scene/ -│ │ ├── Scripting/ -│ │ │ └── Mono/ -│ │ └── Threading/ -│ ├── third_party/ -│ │ ├── assimp/ -│ │ ├── GLAD/ -│ │ ├── kissfft/ -│ │ ├── renderdoc/ -│ │ └── stb/ -│ └── tools/ -│ └── renderdoc_parser/ -├── managed/ -│ ├── CMakeLists.txt -│ ├── GameScripts/ -│ └── XCEngine.ScriptCore/ -├── mvs/ -│ ├── 3DGS-Unity/ -│ ├── D3D12/ -│ ├── Music fluctuations/ -│ ├── OpenGL/ -│ ├── RenderDoc/ -│ ├── Res/ -│ ├── ui/ # 早期 ImGui + D3D12 UI 原型，非当前正式 editor -│ └── VolumeRenderer/ -├── project/ -│ ├── .xceditor/ -│ │ ├── imgui_layout.ini -│ │ └── thumbs/ -│ ├── Assets/ -│ │ ├── Materials/ -│ │ ├── Models/ -│ │ │ └── backpack/ -│ │ ├── New Folder/ -│ │ ├── New Folder 1/ -│ │ ├── Scenes/ -│ │ │ ├── Backpack.xc -│ │ │ └── Main.xc -│ │ └── Scripts/ -│ │ ├── ProjectScriptProbe.cs -│ │ └── Textures/ -│ ├── Library/ -│ │ ├── ArtifactDB/ -│ │ ├── Artifacts/ -│ │ ├── ScriptAssemblies/ -│ │ │ ├── GameScripts.dll -│ │ │ ├── mscorlib.dll -│ │ │ └── XCEngine.ScriptCore.dll -│ │ └── SourceAssetDB/ -│ ├── Assets.meta -│ └── Project.xcproject -├── scripts/ -│ └── Run-RendererPhaseRegression.ps1 -├── tests/ -│ ├── CMakeLists.txt -│ ├── TEST_SPEC.md -│ ├── Components/ -│ ├── Core/ -│ │ ├── Asset/ -│ │ ├── Containers/ -│ │ ├── IO/ -│ │ └── Math/ -│ ├── Debug/ -│ ├── Editor/ -│ ├── Fixtures/ -│ ├── Input/ -│ ├── Memory/ -│ ├── Rendering/ -│ │ ├── integration/ -│ │ │ ├── backpack_lit_scene/ -│ │ │ ├── backpack_scene/ -│ │ │ ├── camera_stack_scene/ -│ │ │ ├── cull_material_scene/ -│ │ │ ├── depth_sort_scene/ -│ │ │ ├── material_state_scene/ -│ │ │ ├── offscreen_scene/ -│ │ │ ├── textured_quad_scene/ -│ │ │ └── transparent_material_scene/ -│ │ └── unit/ -│ ├── Resources/ -│ │ ├── AudioClip/ -│ │ ├── Material/ -│ │ ├── Mesh/ -│ │ ├── Shader/ -│ │ └── Texture/ -│ ├── RHI/ -│ │ ├── D3D12/ -│ │ │ ├── integration/ -│ │ │ └── unit/ -│ │ ├── integration/ -│ │ │ ├── backpack/ -│ │ │ ├── fixtures/ -│ │ │ ├── minimal/ -│ │ │ ├── quad/ -│ │ │ ├── sphere/ -│ │ │ └── triangle/ -│ │ ├── OpenGL/ -│ │ │ ├── integration/ -│ │ │ └── unit/ -│ │ ├── unit/ -│ │ └── Vulkan/ -│ │ ├── integration/ -│ │ └── unit/ -│ ├── Scene/ -│ ├── Scripting/ -│ └── Threading/ -├── 参考/ -│ ├── Fermion/ -│ ├── TransformGizmo/ -│ ├── unity editor/ -│ ├── unity-editor-icons/ -│ ├── unity-icons/ -│ └── UnityRuntimeSceneGizmo-master/ -└── .vscode/ +|- .gitattributes +|- .gitignore +|- AGENT.md +|- CMakeLists.txt +|- README.md +|- build/ # 本地 CMake 构建输出 +|- docs/ +| |- api/ +| | |- XCEngine/ +| | |- _guides/ +| | |- _meta/ +| | |- _tools/ +| | `- main.md +| |- issues/ +| | `- Editor模块_Console面板错误绑定fallback sink导致运行时日志不显示4.3.md +| |- plan/ +| | |- end/ +| | | |- RHI模块设计与实现/ +| | | | |- RHIFence.md +| | | | `- RHI模块总览.md +| | | `- 编辑器与运行时分层架构设计.md +| | |- 开题报告和任务书/ +| | |- 旧版题目/ +| | |- API文档实时同步任务池_2026-04-03.md +| | |- C#脚本模块下一阶段计划.md +| | |- Editor架构说明.md +| | |- Library启动预热与运行时异步加载混合重构计划_2026-04-04.md +| | |- Library启动预热与运行时异步加载混合重构计划_进度更新_2026-04-04.md +| | |- Renderer下一阶段_Unity风格Shader体系正式化计划_2026-04-06.md +| | |- Unity SRP API参考文档.md +| | |- XCUI_Phase_Status_2026-04-05.md +| | |- XCUI完整架构设计与执行计划.md +| | `- Unity绝区零开发文档还原版.md +| |- used/ # 历史材料、归档计划与截图 +| | |- API文档实时同步任务池_2026-04-03_第一轮归档.md +| | |- API文档实时同步任务池_2026-04-03_第二轮归档.md +| | |- C#脚本模块的设计与实现_阶段一归档_2026-04-03.md +| | |- Library资产导入与缓存系统收口计划_完成归档_2026-04-03.md +| | |- Renderer结构收口与代码正式化计划_完成归档_2026-04-05.md +| | |- SceneViewport_Overlay_Gizmo_Rework_Plan_完成归档_2026-04-04.md +| | |- Shader与Material系统下一阶段计划_完成归档_2026-04-04.md +| | |- Unity式SceneView_Gizmo系统完整审查与正式化重构方案_完成归档_2026-04-06.md +| | |- Unity式Tick系统与PlayMode运行时方案-阶段进展.md +| | `- Unity式Tick系统与PlayMode运行时方案.md +| |- api-skill.md +| |- blueprint-skill.md +| `- blueprint.md +|- editor/ +| |- CMakeLists.txt +| |- README.md +| |- bin/ # 编辑器输出目录，产物名为 XCEngine.exe +| |- resources/ +| | `- Icons/ +| `- src/ +| |- Actions/ +| |- Commands/ +| |- ComponentEditors/ +| |- Core/ +| |- Layers/ +| |- Layout/ +| |- Managers/ +| |- panels/ +| | |- ConsolePanel.cpp +| | |- ConsolePanel.h +| | |- GameViewPanel.cpp +| | |- GameViewPanel.h +| | |- HierarchyPanel.cpp +| | |- HierarchyPanel.h +| | |- InspectorPanel.cpp +| | |- InspectorPanel.h +| | |- MenuBar.cpp +| | |- MenuBar.h +| | |- Panel.cpp +| | |- Panel.h +| | |- PanelCollection.h +| | |- ProjectPanel.cpp +| | |- ProjectPanel.h +| | |- SceneViewPanel.cpp +| | |- SceneViewPanel.h +| | `- ViewportPanelContent.h +| |- Platform/ +| |- Scripting/ +| |- UI/ +| |- Utils/ +| |- Viewport/ +| | |- Passes/ +| | | |- SceneViewportEditorOverlayPass.cpp +| | | |- SceneViewportEditorOverlayPass.h +| | | |- SceneViewportGridPass.cpp +| | | |- SceneViewportGridPass.h +| | | |- SceneViewportSelectionOutlinePass.cpp +| | | `- SceneViewportSelectionOutlinePass.h +| | |- IViewportHostService.h +| | |- SceneViewportCameraController.h +| | |- SceneViewportChrome.cpp +| | |- SceneViewportChrome.h +| | |- SceneViewportEditorModes.h +| | |- SceneViewportEditorOverlayData.h +| | |- SceneViewportHudOverlay.cpp +| | |- SceneViewportHudOverlay.h +| | |- SceneViewportInteractionActions.cpp +| | |- SceneViewportInteractionActions.h +| | |- SceneViewportInteractionFrame.h +| | |- SceneViewportInteractionResolver.cpp +| | |- SceneViewportInteractionResolver.h +| | |- SceneViewportMath.h +| | |- SceneViewportMoveGizmo.cpp +| | |- SceneViewportMoveGizmo.h +| | |- SceneViewportNavigation.h +| | |- SceneViewportOrientationGizmo.cpp +| | |- SceneViewportOrientationGizmo.h +| | |- SceneViewportOverlayBuilder.cpp +| | |- SceneViewportOverlayBuilder.h +| | |- SceneViewportOverlayFrameCache.cpp +| | |- SceneViewportOverlayFrameCache.h +| | |- SceneViewportOverlayHandleBuilder.h +| | |- SceneViewportOverlayHitTester.h +| | |- SceneViewportOverlayProviders.cpp +| | |- SceneViewportOverlayProviders.h +| | |- SceneViewportOverlaySpriteResources.cpp +| | |- SceneViewportOverlaySpriteResources.h +| | |- SceneViewportPassSpecs.h +| | |- SceneViewportPicker.cpp +| | |- SceneViewportPicker.h +| | |- SceneViewportRenderPlan.h +| | |- SceneViewportResourcePaths.h +| | |- SceneViewportRotateGizmo.cpp +| | |- SceneViewportRotateGizmo.h +| | |- SceneViewportScaleGizmo.cpp +| | |- SceneViewportScaleGizmo.h +| | |- SceneViewportShaderPaths.h +| | |- SceneViewportTransformGizmoCoordinator.cpp +| | |- SceneViewportTransformGizmoCoordinator.h +| | |- SceneViewportTransformGizmoFrameBuilder.h +| | |- ViewportHostRenderFlowUtils.h +| | |- ViewportHostRenderTargets.h +| | |- ViewportHostService.h +| | |- ViewportHostSurfaceUtils.h +| | `- ViewportObjectIdPicker.h +| |- Application.cpp +| |- Application.h +| |- EditorApp.rc +| |- EditorResources.h +| |- Theme.cpp +| |- Theme.h +| `- main.cpp +|- engine/ +| |- CMakeLists.txt +| |- include/ +| | `- XCEngine/ +| | |- Audio/ +| | |- Components/ +| | |- Core/ +| | | |- Asset/ +| | | |- Containers/ +| | | |- IO/ +| | | `- Math/ +| | |- Debug/ +| | |- Input/ +| | |- Memory/ +| | |- Platform/ +| | | `- Windows/ +| | |- Rendering/ +| | | |- Passes/ +| | | |- Pipelines/ +| | | |- CameraRenderer.h +| | | |- CameraRenderRequest.h +| | | |- ObjectIdPass.h +| | | |- RenderPipeline.h +| | | |- RenderSurface.h +| | | `- SceneRenderer.h +| | |- Resources/ +| | | |- AudioClip/ +| | | |- Material/ +| | | |- Mesh/ +| | | |- Shader/ +| | | `- Texture/ +| | |- RHI/ +| | | |- D3D12/ +| | | |- OpenGL/ +| | | `- Vulkan/ +| | |- Scene/ +| | |- Scripting/ +| | | `- Mono/ +| | `- Threading/ +| |- src/ # 与 include/XCEngine 中的主模块一一对应 +| |- third_party/ +| | |- assimp/ +| | |- GLAD/ +| | |- kissfft/ +| | |- renderdoc/ +| | `- stb/ +| `- tools/ +| `- renderdoc_parser/ +|- managed/ +| |- CMakeLists.txt +| |- GameScripts/ +| `- XCEngine.ScriptCore/ +|- mvs/ +| |- 3DGS-Unity/ +| |- D3D12/ +| |- Music fluctuations/ +| |- OpenGL/ +| |- RenderDoc/ +| |- Res/ +| |- ui/ # 早期 ImGui + D3D12 UI 原型 +| `- VolumeRenderer/ +|- new_editor/ +| |- app/ +| | |- Host/ +| | |- Application.cpp +| | |- Application.h +| | `- main.cpp +| |- bin/ # XCUIEditor.exe 输出目录 +| |- include/ +| | `- XCEditor/ +| | |- Core/ +| | `- Widgets/ +| |- src/ +| | |- Core/ +| | |- Platform/ +| | `- Widgets/ +| |- ui/ +| `- CMakeLists.txt +|- project/ +| |- .xceditor/ +| | |- imgui_layout.ini +| | `- thumbs/ +| |- Assets/ +| | |- Materials/ +| | |- Materials.meta +| | |- Models/ +| | |- Models.meta +| | |- New Folder.meta +| | |- New Folder 1.meta +| | |- New Material.mat +| | |- New Material.mat.meta +| | |- Scenes/ +| | | |- Backpack.xc +| | | |- Backpack.xc.meta +| | | |- Main.xc +| | | |- Main.xc.meta +| | | |- NewFolder.meta +| | | `- NewFolder/ +| | |- Scenes.meta +| | |- Scripts/ +| | | |- ProjectScriptProbe.cs +| | | |- ProjectScriptProbe.cs.meta +| | | |- Textures/ +| | | |- Textures.meta +| | | |- TickLogProbe.cs +| | | `- TickLogProbe.cs.meta +| | `- Scripts.meta +| |- Library/ +| | |- ArtifactDB/ +| | | `- artifacts.db +| | |- Artifacts/ +| | | `- // +| | |- ScriptAssemblies/ +| | | |- GameScripts.dll +| | | `- mscorlib.dll +| | `- SourceAssetDB/ +| | `- assets.db +| |- Assets.meta +| `- Project.xcproject +|- scripts/ +| `- Run-RendererPhaseRegression.ps1 +|- tests/ +| |- CMakeLists.txt +| |- TEST_SPEC.md +| |- Components/ +| |- Core/ +| | |- Asset/ +| | |- Containers/ +| | |- IO/ +| | `- Math/ +| |- Debug/ +| |- Editor/ +| | |- CMakeLists.txt +| | |- test_action_routing.cpp +| | |- test_application_asset_cache_stub.cpp +| | |- test_builtin_icon_layout_utils.cpp +| | |- test_editor_console_sink.cpp +| | |- test_editor_script_assembly_builder.cpp +| | |- test_editor_script_assembly_builder_utils.cpp +| | |- test_play_session_controller.cpp +| | |- test_play_session_controller_scripting.cpp +| | |- test_scene_viewport_camera_controller.cpp +| | |- test_scene_viewport_chrome.cpp +| | |- test_scene_viewport_interaction_actions.cpp +| | |- test_scene_viewport_interaction_frame.cpp +| | |- test_scene_viewport_interaction_resolver.cpp +| | |- test_scene_viewport_move_gizmo.cpp +| | |- test_scene_viewport_navigation.cpp +| | |- test_scene_viewport_overlay_providers.cpp +| | |- test_scene_viewport_overlay_renderer.cpp +| | |- test_scene_viewport_picker.cpp +| | |- test_scene_viewport_rotate_gizmo.cpp +| | |- test_scene_viewport_scale_gizmo.cpp +| | |- test_scene_viewport_shader_paths.cpp +| | |- test_scene_viewport_transform_gizmo_coordinator.cpp +| | |- test_script_component_editor_utils.cpp +| | |- test_viewport_host_surface_utils.cpp +| | |- test_viewport_object_id_picker.cpp +| | |- test_viewport_render_flow_utils.cpp +| | `- test_viewport_render_targets.cpp +| |- Fixtures/ +| | `- Resources/ +| |- Input/ +| |- Memory/ +| |- NewEditor/ # 当前为空的预留测试根目录 +| |- Rendering/ +| | |- integration/ +| | | |- backpack_lit_scene/ +| | | |- backpack_scene/ +| | | |- camera_stack_scene/ +| | | |- cull_material_scene/ +| | | |- depth_sort_scene/ +| | | |- material_state_scene/ +| | | |- offscreen_scene/ +| | | |- textured_quad_scene/ +| | | `- transparent_material_scene/ +| | `- unit/ +| |- Resources/ +| | |- AudioClip/ +| | |- Material/ +| | |- Mesh/ +| | |- Shader/ +| | `- Texture/ +| |- RHI/ +| | |- D3D12/ +| | | |- integration/ +| | | `- unit/ +| | |- integration/ +| | | |- backpack/ +| | | |- fixtures/ +| | | |- minimal/ +| | | |- quad/ +| | | |- sphere/ +| | | `- triangle/ +| | |- OpenGL/ +| | | |- integration/ +| | | `- unit/ +| | |- unit/ +| | `- Vulkan/ +| | |- integration/ +| | `- unit/ +| |- Scene/ +| |- Scripting/ +| |- Threading/ +| `- UI/ +| |- Core/ +| |- Editor/ +| |- Runtime/ +| `- TEST_SPEC.md +|- 参考/ +| |- Fermion/ +| |- TransformGizmo/ +| |- unity editor/ +| |- unity-editor-icons/ +| |- unity-icons/ +| `- UnityRuntimeSceneGizmo-master/ +`- .vscode/ ``` ## 关键文档入口 -- 协作基线与 coding agent 入口：[AGENT.md](AGENT.md) +- 编辑器模块说明：[editor/README.md](editor/README.md) +- 面向引擎实现者和 coding agent 的协作基线：[AGENT.md](AGENT.md) +- API 文档入口：[docs/api/main.md](docs/api/main.md) +- 架构蓝图：[docs/blueprint.md](docs/blueprint.md) - RHI 基线设计：[docs/plan/end/RHI模块设计与实现/RHI模块总览.md](docs/plan/end/RHI模块设计与实现/RHI模块总览.md) -- 当前 Shader / Material 主线：[docs/plan/Shader与Material系统下一阶段计划.md](docs/plan/Shader与Material系统下一阶段计划.md) -- Scene viewport overlay 重构：[docs/plan/SceneViewport_Overlay_Gizmo_Rework_Plan.md](docs/plan/SceneViewport_Overlay_Gizmo_Rework_Plan.md) +- Library 启动与运行时加载主线：[docs/plan/Library启动预热与运行时异步加载混合重构计划_2026-04-04.md](docs/plan/Library启动预热与运行时异步加载混合重构计划_2026-04-04.md) +- Editor 当前架构：[docs/plan/Editor架构说明.md](docs/plan/Editor架构说明.md) +- 当前 Shader / Material 主线：[docs/plan/Renderer下一阶段_Unity风格Shader体系正式化计划_2026-04-06.md](docs/plan/Renderer下一阶段_Unity风格Shader体系正式化计划_2026-04-06.md) +- XCUI 总体蓝图：[docs/plan/XCUI完整架构设计与执行计划.md](docs/plan/XCUI完整架构设计与执行计划.md) +- XCUI 阶段状态：[docs/plan/XCUI_Phase_Status_2026-04-05.md](docs/plan/XCUI_Phase_Status_2026-04-05.md) - 测试规范：[tests/TEST_SPEC.md](tests/TEST_SPEC.md) -## 许可证 +## 许可说明 当前仓库根目录未看到独立的顶层许可证文件。涉及第三方库时，请分别遵循其所在目录中的许可证或随附说明。 diff --git a/docs/api-skill.md b/docs/api-skill.md index 5d64ebf2..604b2265 100644 --- a/docs/api-skill.md +++ b/docs/api-skill.md @@ -2,199 +2,217 @@ ## 目标 -本规范用于维护 `XCEngine` 的唯一正式 API 文档树，并约束后续所有模块级重构的工作方式。 +这份规范面向维护 `XCEngine` API 文档的 coding agent。它的目标不是“批量生成一套看起来完整的文档”，而是持续把当前源码、测试和真实调用链路同步到唯一的 canonical API 文档树里。 -硬性要求： +当前仓库已经进入“增量同步”阶段。重点不再是补骨架，而是： -1. `docs/api/XCEngine/**` 必须与 `engine/include/XCEngine/**` 保持平行。 -2. canonical API 文档只保留一套；迁移完成后必须删除旧目录与旧入口。 -3. 默认情况下，每个 public header 对应一个独立文档目录，每个类型页都使用 `{TypeName}/{TypeName}.md`。 -4. 方法页优先使用源码中的原始函数名；不要改成 kebab-case、全小写或其它再命名形式。 -5. API 文档必须以源码、实现、测试和真实调用点为依据，禁止只根据名字猜测行为。 -6. 对于只承担聚合包含职责的 umbrella header，可以并入模块页说明，不强制再建一个同名类型目录。 +- 跟住最新 public header 和 Editor source header 的真实变化 +- 清理过期 API 页面和过期叙述 +- 保持 overview / guide / method page 的口径一致 -## Canonical 目录结构 +## 当前范围 -```text -docs/api/ -├── main.md -├── XCEngine/ -│ ├── XCEngine.md -│ ├── Debug/ -│ │ ├── Debug.md -│ │ ├── Logger/ -│ │ │ ├── Logger.md -│ │ │ ├── Get.md -│ │ │ ├── Initialize.md -│ │ │ └── Log.md -│ │ └── RenderDocCapture/ -│ │ ├── RenderDocCapture.md -│ │ └── BeginCapture.md -│ └── ... -├── _guides/ -│ └── Debug/ -└── _meta/ +API 文档的正式范围包含两部分： + +1. 引擎 public API + - 对齐 `engine/include/XCEngine/**` +2. Editor source-backed API + - 对齐 `editor/src/**` + - canonical 文档入口仍放在 `docs/api/XCEngine/Editor/**` + +辅助目录也属于工作流的一部分： + +- `docs/api/_guides/**` + - 教程、架构说明、工作流说明 +- `docs/api/_meta/**` + - 审计结果、阶段性状态 +- `docs/api/_tools/**` + - 审计、生成、修链脚本 +- `docs/plan/API文档实时同步任务池_2026-04-03.md` + - 当前多任务并行同步池 +- `README.md` / `editor/README.md` / `AGENT.md` + - 这些不是 canonical API 页，但一旦它们引用 API 模块结构、测试目录或 Editor helper 分层，就属于必须同步的活跃协作文档 + +## 硬约束 + +1. `docs/api/XCEngine/**` 是唯一 canonical API 树。 +2. 文档必须以“当前 header + 当前实现 + 当前测试 + 当前真实调用点”为依据，不能按旧文档或命名猜行为。 +3. 删除的 API 页面要一起删除，相关交叉链接也必须一起清理。 +4. 方法页优先使用源码中的原始函数名；不要擅自改成 kebab-case 或小写别名。 +5. 不要把“设计意图”写成“当前实现行为”。 +6. 不要为已经删除的 API 保留默认兼容入口页，除非任务明确要求。 +7. `rebuild-status.md` 以审计脚本输出为准；并发场景下，stdout 比旧文件内容更可信。 +8. 只收口活跃文档；`docs/plan/used/**`、`docs/used/**` 等归档材料默认保留历史写法，不要为了“顺手统一”去重写归档。 +9. Windows 工作树里的路径大小写按真实目录名写，例如 `tests/Editor/`、`tests/Core/`、`tests/Scripting/`，不要继续传播 `tests/editor/`、`tests/core/` 之类的历史噪音。 + +## 工作流 + +### 1. 开工前先看两份文件 + +- 任务池： + - `docs/plan/API文档实时同步任务池_2026-04-03.md` +- 最新审计： + - `docs/api/_meta/rebuild-status.md` + +如果任务池和工作树不一致，以当前源码和重新执行审计后的结果为准。 + +如果 `docs/plan/` 下出现日期更晚的 API 相关计划或归档文件，优先读取更新日期更晚的文件，再判断当前任务池是否已经转入 `docs/plan/used/`。 + +如果工作内容会改到 `README.md`、`editor/README.md` 或 `AGENT.md`： + +- 先对照真实工作树、`Get-ChildItem` 输出和当前测试目录 +- 再改目录树与模块说明 +- 不要沿用旧摘要、旧计划里的目录快照 + +### 2. 认领规则 + +- 一次只认领一个任务块。 +- 先把任务状态改成 `DOING`，再写认领人。 +- 只修改该任务块的写入范围。 +- 如果发现新的失配，但不属于当前任务块，向任务池追加新任务，不顺手扩写。 + +### 3. 写文档前的取证 + +至少完成下面四步： + +1. 读对应 header +2. 读对应 `.cpp` 或内联实现 +3. 搜测试和真实调用点 +4. 确认生命周期、线程语义、失败路径、所有权、平台限制 + +如果是 Editor source-backed API，至少额外确认两类锚点： + +1. `tests/Editor/` 下是否已有对应单测 +2. `SceneViewPanel.cpp`、`ViewportHostService.*` 或其他真实上层调用链是否已经切到新 helper + +落文前至少能回答这些问题： + +- 这个类型或函数解决什么问题，边界在哪里？ +- 调用前需要什么前置条件？ +- 失败时返回什么，或者会不会静默 no-op？ +- 谁拥有对象，谁负责释放资源？ +- 当前实现是完整能力、轻量封装、stub，还是占位入口？ + +### 4. 改完后的收口 + +必须重新执行： + +```powershell +python -B docs/api/_tools/audit_api_docs.py ``` -说明： +至少关注这些指标： -- `docs/api/XCEngine/**` 是唯一 canonical API 树。 -- `docs/api/_guides/**` 用于概念、教程、设计理念和工作流说明，不是第二套 API 树。 -- `README.md` 不用于 canonical 模块索引页；模块索引页统一使用 `{DirName}.md`。 +- `Invalid header refs` +- `Invalid source refs` +- `Broken .md links` +- `Old template pages` +- `Flat header pages` +- `Stale editor doc tokens` +- `Stale editor canonical pages` -## 强制命名规则 +如果审计没回绿，不算完成。 -### 1. 目录索引页 +## Canonical 目录规则 -- 根索引页：`docs/api/XCEngine/XCEngine.md` -- 模块索引页：`docs/api/XCEngine/{ModuleName}/{ModuleName}.md` -- 子模块索引页：`docs/api/XCEngine/{ModuleName}/{SubmoduleName}/{SubmoduleName}.md` +### 1. 模块总览页 + +- 根入口： + - `docs/api/main.md` +- API 根页： + - `docs/api/XCEngine/XCEngine.md` +- 模块页： + - `docs/api/XCEngine/{ModuleName}/{ModuleName}.md` +- 子模块页： + - `docs/api/XCEngine/{ModuleName}/{SubmoduleName}/{SubmoduleName}.md` 示例： -- `docs/api/XCEngine/Debug/Debug.md` - `docs/api/XCEngine/Core/Core.md` -- `docs/api/XCEngine/RHI/D3D12/D3D12.md` +- `docs/api/XCEngine/Core/Asset/Asset.md` +- `docs/api/XCEngine/Rendering/Passes/Passes.md` +- `docs/api/XCEngine/Editor/Viewport/Viewport.md` -### 2. 类型目录 +### 2. Header / source-backed 目录 -- 每个 public header 对应一个独立文件夹。 -- 文件夹名必须与 header stem 或主要类型名一致。 -- 保留源码中的大小写，不做风格改写。 -- 如果 header 只是模块聚合入口，不声明独立类型，可以直接并入模块页，不单独建文件夹。 +当前不是“每个类型再套一层目录”，而是： + +- 每个 public header 或 Editor source header 对应一个文档目录 +- 该目录内放主类型页、辅助类型页和方法页 示例： -- `docs/api/XCEngine/Debug/Logger/` -- `docs/api/XCEngine/Core/Asset/ResourceManager/` -- `docs/api/XCEngine/RHI/D3D12/D3D12Device/` +```text +docs/api/XCEngine/Core/Asset/ResourceManager/ +├── ResourceManager.md +├── Load.md +├── LoadAsync.md +├── RefreshProjectAssets.md +├── RebuildProjectAssetCache.md +└── GetProjectLibraryRoot.md +``` -### 3. 类型总览页 +多类型 / helper 同头文件示例： -- 固定为 `{TypeName}/{TypeName}.md` -- 不允许把类型总览页直接平铺在模块目录中 +```text +docs/api/XCEngine/Editor/Viewport/SceneViewportRenderPlan/ +├── SceneViewportRenderPlan.md +├── SceneViewportRenderPlanBuildResult.md +├── BuildSceneViewportRenderPlan.md +└── ApplySceneViewportRenderPlan.md +``` -### 4. 方法详情页 +### 3. umbrella header 例外 -- 方法页放在所属类型目录内。 -- 文件名优先使用原函数名。 -- 重载共享同一页，在页内按签名分节说明。 +如果一个 header 只是聚合入口，通常不单独建同名类型页，直接并入模块页： -示例： +- 文件主要由 `#include` 组成 +- 不声明独立 class / struct / enum / function family +- 单独建页只会制造重复入口 -- `Get.md` -- `Initialize.md` -- `SetCaptureFilePath.md` -- `LoadSceneAsync.md` +## 命名规则 -### 5. 特殊命名 +### 1. 主页面 -- 构造函数：`Constructor.md` -- 析构函数：`Destructor.md` -- 运算符使用可读的 PascalCase 名称 +- 主类型页通常用主类型名： + - `ResourceManager.md` + - `BuiltinInfiniteGridPass.md` +- helper 类型页直接用真实类型名： + - `ImportedAsset.md` + - `LookupSnapshot.md` -建议映射： +### 2. 方法页 -- `operator=` -> `OperatorAssign.md` -- `operator+=` -> `OperatorPlusAssign.md` -- `operator[]` -> `OperatorSubscript.md` -- `operator()` -> `OperatorCall.md` +- 用真实函数名： + - `Initialize.md` + - `TryResolveAssetPath.md` + - `BuildInfiniteGridParameters.md` -## 写作前的取证流程 +重载共享同一页，在页内按签名分节说明。 -在编写任何 API 页之前，必须完成下面的最小取证： +### 3. 特殊命名 -1. 阅读对应 public header。 -2. 阅读对应 `.cpp` 或内联实现。 -3. 搜索测试、示例和真实调用点。 -4. 确认生命周期、线程语义、所有权、失败路径和平台限制。 - -至少回答以下问题后才能落文： - -- 这个类型解决什么问题，边界在哪里？ -- 调用前需要什么前置条件？ -- 调用失败时返回什么，或者会静默失败？ -- 谁拥有对象，谁负责释放资源？ -- 多线程下哪些调用安全，哪些只能在初始化阶段使用？ -- 当前实现是不是完整的？有没有空实现、占位实现或只做轻量封装？ - -禁止行为： - -- 只根据 `Get`、`Create`、`Set` 之类的前缀写模板句。 -- 把“设计意图”当成“当前实现行为”来写。 -- 把测试里假设成立的场景，误写成通用保证。 - -## umbrella header 例外规则 - -以下情况通常应视为模块聚合头，而不是单独类型页： - -- 头文件主要由一组 `#include` 组成。 -- 不声明独立类、结构体、枚举或函数族。 -- 名称与模块目录同名，单独建页会造成 `Debug/Debug.md` 这类重复入口。 - -处理方式： - -- 在模块页中增加“聚合头文件”或“包含入口”小节。 -- 使用 `**头文件**: \`...\`` 保留头文件覆盖记录。 -- 不再额外创建 `{HeaderStem}/{HeaderStem}.md`。 - -## 契约分层规则 - -文档必须明确区分下面三层信息： - -### 1. 接口契约 - -来自 public header，属于使用者可以依赖的 API 形状。 - -例如： - -- 函数签名 -- 参数和返回值 -- 可见的数据结构 -- 明确暴露的枚举值和宏 - -### 2. 当前实现行为 - -来自 `.cpp`、内联实现、测试和调用点，描述当前版本的真实行为。 - -例如： - -- 是否自动初始化 -- 是否加锁 -- 是否会写日志、刷新文件、拉起窗口焦点 -- 是否只是 no-op 或 stub - -这一层必须使用明确表述，例如： - -- “当前实现中……” -- “按 `engine/src/...` 的实现……” -- “当前版本会……” - -### 3. 合理推断 - -只在确实有必要时使用，而且必须标明是推断。 - -例如： - -- “从 API 形状看，设计上显然是为后续 Chrome Trace 导出预留扩展点。” - -如果不能证明，就不要写。 +- 构造函数： + - `Constructor.md` +- 析构函数： + - `Destructor.md` +- 运算符： + - `operator=` -> `OperatorAssign.md` + - `operator[]` -> `OperatorSubscript.md` + - `operator()` -> `OperatorCall.md` ## 页面职责 -### 1. 模块页 / 子模块页 +### 1. 模块页 -负责： +必须说明： -- 说明模块职责、边界和典型使用场景 -- 列出子目录与 public headers -- 给出与相邻模块的关系 -- 链接相关 guide 页 +- 模块职责 +- 与相邻模块的边界 +- 典型使用链路 +- 关键入口页 -不负责： - -- 展开所有方法细节 -- 重复 header 全量声明 +不要在模块页里平铺所有方法细节。 ### 2. 类型页 @@ -202,212 +220,122 @@ docs/api/ - 命名空间 - 类型分类 -- 头文件 +- `头文件` 或 `源文件` - 角色概述 - 生命周期 - 线程语义 - 所有权 / 资源管理方式 - 当前实现限制 -- 与相关方法页、guide 页的跳转 +- 相关方法与相关 guide -如果类型是枚举或结构体，还应补充： - -- 字段或枚举值说明 -- 值之间的语义关系 -- 典型使用方式 +如果是 `struct` / `enum`，还要写清字段或枚举值的实际语义。 ### 3. 方法页 -必须包含： +必须写清： - 准确签名 - 调用目的 - 前置条件 -- 参数说明 -- 返回值说明 +- 当前实现行为 +- 返回值 - 副作用 -- 线程语义 - 失败路径或 no-op 条件 -- 最小可信示例 +- 线程语义 +- 真实调用点或测试锚点 -方法页不能只写“获取对象”“设置状态”这种空描述。 +不能只写“获取对象”“设置状态”这种空描述。 -## 内容深度要求 +## 写法规则 -### 1. 解释“是什么” +### 1. 区分三层信息 -说明类型或方法的职责，而不是简单复述名字。 +文档里要明确区分： -### 2. 解释“怎么用” +- 接口契约 + - 来自 header，可被调用方依赖 +- 当前实现行为 + - 来自 `.cpp`、测试和调用链 +- 合理推断 + - 只有必要时才写，并明确标注是推断 -给出最小可运行或最小可信的使用顺序，让用户知道放在初始化、运行时还是销毁阶段。 +推荐措辞： -### 3. 解释“为什么这样设计” +- “当前实现中……” +- “按 `engine/src/...` 的实现……” +- “测试 `tests/...` 当前验证了……” -结合引擎架构解释： +### 2. 优先写真实链路 -- 为什么做成 singleton、service、interface、sink、builder、handle -- 这样做的收益是什么 -- 有哪些代价或约束 +如果一个 API 真正只是更大链路中的一环，要把链路写出来。 -### 4. 解释“当前实现做到哪一步” +示例： -商业级 API 文档不能假装所有接口都同样成熟。 +- `ResourceManager` + - 不只写“负责资源加载” + - 要写清 `AssetImportService -> ProjectAssetIndex -> loader` 的真实路径 +- `SceneViewportRenderPlan` + - 不只写“构建后处理 plan” + - 要写清它如何给 Scene View 组装 `postScenePasses` / `overlayPasses` -对于未完成能力，必须明确说明： +### 3. 明确不成熟部分 -- 当前是占位接口 -- 当前只有基础实现 -- 当前只覆盖某个平台 / 某条后端路径 +对未完成能力要直接写明： -## 教程与概念页规范 +- 当前是 stub +- 当前只支持某个平台 +- 当前只覆盖某条 backend 路径 +- 当前仍要求调用方手动轮询或手动 shutdown -当某个模块仅靠 API 页不足以让用户理解时，应增加 `_guides` 页。 +不要把不成熟接口包装成成熟系统。 + +## Guide / Overview 规则 + +`_guides` 不是第二套 API 参考，而是解释： + +- 为什么这样组织模块 +- 推荐从哪里开始读 +- 典型工作流是什么 +- 与 Unity / Unreal 等常见心智模型的关系 适合写 guide 的内容： -- 前置知识 -- 架构设计理念 -- 推荐工作流 -- 和 Unity / Unreal / RenderDoc 等常见工具的概念对照 -- 最佳实践与反模式 +- 架构图景 +- 推荐使用顺序 +- 设计权衡 +- 常见误区 -guide 页不是第二套 API 参考，它们负责回答： +不适合： -- 为什么要这样组织模块 -- 用户第一次接触时该从哪里开始 -- 这套 API 与常见引擎的对应关系是什么 +- 重复抄一遍类型页和方法页 +- 延续已经过期的旧工作流 -guide 页应尽量包含： +## 常见失误 -- 问题背景 -- 设计目标 -- 推荐流程 -- 优点与代价 -- 与现有 API 页的链接 +- 按名字猜 API 行为，不看实现和测试 +- 保留已经删除的 API 页面或链接 +- overview 还在传播旧心智，但类型页已经改新了 +- 把 helper / wrapper 当成独立大系统来写 +- 把 Editor source-backed API 当成 public header 处理，漏掉 `源文件` 语义 +- 审计没跑或没回绿就宣布完成 +- README / AGENT / editor README 的目录树还停留在旧快照，和当前工作树脱节 +- Windows 上真实已有新测试，但类型页还在写“没有独立单元测试” -## Unity 风格的解释性要求 +## 推荐命令 -当模块涉及常见引擎概念时，可以增加 Unity 对照，但必须克制且准确。 - -推荐写法： - -- “可以把 `Logger` 理解为比 Unity Console 更底层的日志分发中心。” -- “当前 `Profiler` 只覆盖轻量 CPU 埋点，不等同于 Unity Profiler 的完整时间线分析。” -- “`RenderDocCapture` 更接近引擎内置的 RenderDoc 工作流桥接，而不是 Unity Frame Debugger 的替代品。” - -禁止写法： - -- “和 Unity 完全一样” -- “等价于某商业引擎的完整系统” - -## 页面模板 - -### 1. 模块页模板 - -```markdown -# {DirName} - -**命名空间**: `{Namespace}` - -**类型**: `module` / `submodule` / `module-root` - -**描述**: {一句话说明当前目录职责} - -## 概述 - -{解释职责边界、典型场景和相邻模块关系} - -## 设计要点 - -- {要点 1} -- {要点 2} - -## 头文件 - -- [TypeA](TypeA/TypeA.md) - `TypeA.h` -- [TypeB](TypeB/TypeB.md) - `TypeB.h` - -## 相关指南 - -- [GuideA](../../_guides/.../GuideA.md) +```powershell +rg --files docs/api/XCEngine +rg --files tests/Editor +rg -n "SymbolName" engine/include engine/src editor/src tests docs/api +python -B docs/api/_tools/audit_api_docs.py ``` -### 2. 类型页模板 +## 一个最小完成定义 -```markdown -# {TypeName} +一次 API 文档任务只有同时满足下面条件才算完成： -**命名空间**: `{Namespace}` - -**类型**: `class` / `class (abstract)` / `class (singleton)` / `struct` / `enum class` - -**头文件**: `XCEngine/.../{Header}.h` - -**描述**: {一句话说明} - -## 概述 - -{说明角色、状态、边界、典型使用方式} - -## 生命周期 - -- {初始化与销毁方式} - -## 线程语义 - -- {线程安全说明} - -## 公开成员 - -| 成员 | 说明 | -|------|------| -| [Initialize](Initialize.md) | {说明} | -| [Shutdown](Shutdown.md) | {说明} | -``` - -### 3. 方法页模板 - -```markdown -# {TypeName}::{MethodName} - -{一句话说明方法职责} - -```cpp -{完整签名} -``` - -## 行为说明 - -{说明前置条件、后置状态、副作用和当前实现细节} - -## 参数 - -- `param` - {描述} - -## 返回值 - -- `{Type}` - {描述} - -## 线程语义 - -- {线程安全、只建议初始化阶段调用、或必须同线程配对等} - -## 示例 - -```cpp -{最小可信示例} -``` -``` - -## 验收清单 - -- `docs/api/XCEngine/**` 与 `engine/include/XCEngine/**` 目录平行 -- canonical 树下没有模块级 `README.md` -- 每个 public header 都有对应类型目录 -- 每个类型总览页都位于 `{TypeName}/{TypeName}.md` -- 方法页使用原函数名或规范化运算符名 -- 所有链接都指向真实存在的 `.md` 页面 -- 文档中明确区分接口契约、当前实现和合理推断 -- 重要模块拥有必要的 guide 页 -- 重要限制、stub、平台条件和线程语义都已写清 +- 对应源码、测试、调用链已经核对 +- 文档页内容已经改到当前实现 +- 过期页面和交叉链接已经清理 +- 任务池记录已最小更新 +- 审计脚本重新执行且结果全绿 diff --git a/docs/api/XCEngine/Audio/AudioMixer/AddEffect.md b/docs/api/XCEngine/Audio/AudioMixer/AddEffect.md index d66f8685..5959ee29 100644 --- a/docs/api/XCEngine/Audio/AudioMixer/AddEffect.md +++ b/docs/api/XCEngine/Audio/AudioMixer/AddEffect.md @@ -1,31 +1,26 @@ # AudioMixer::AddEffect -添加元素或建立关联。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/AudioMixer.h` + +## 签名 ```cpp void AddEffect(IAudioEffect* effect); ``` -该方法声明于 `XCEngine/Audio/AudioMixer.h`，当前页面用于固定 `AudioMixer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `effect` - 参数语义详见头文件声明。 +更新 `m_effects`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::AudioMixer object; - // 根据上下文补齐参数后调用 AudioMixer::AddEffect(...)。 - (void)object; -} -``` +- 会更新 `m_effects`。 +- 当前实现会调用 `push_back`。 ## 相关文档 -- [返回类总览](AudioMixer.md) -- [返回模块目录](../Audio.md) +- [AudioMixer](AudioMixer.md) diff --git a/docs/api/XCEngine/Audio/AudioMixer/ClearEffects.md b/docs/api/XCEngine/Audio/AudioMixer/ClearEffects.md index ce94279e..e37485c0 100644 --- a/docs/api/XCEngine/Audio/AudioMixer/ClearEffects.md +++ b/docs/api/XCEngine/Audio/AudioMixer/ClearEffects.md @@ -1,30 +1,26 @@ # AudioMixer::ClearEffects -清空内部数据。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/AudioMixer.h` + +## 签名 ```cpp void ClearEffects(); ``` -该方法声明于 `XCEngine/Audio/AudioMixer.h`，当前页面用于固定 `AudioMixer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_effects`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::AudioMixer object; - // 根据上下文补齐参数后调用 AudioMixer::ClearEffects(...)。 - (void)object; -} -``` +- 会更新 `m_effects`。 +- 当前实现会调用 `clear`。 ## 相关文档 -- [返回类总览](AudioMixer.md) -- [返回模块目录](../Audio.md) +- [AudioMixer](AudioMixer.md) diff --git a/docs/api/XCEngine/Audio/AudioMixer/Constructor.md b/docs/api/XCEngine/Audio/AudioMixer/Constructor.md index 1778ef76..a1b45f35 100644 --- a/docs/api/XCEngine/Audio/AudioMixer/Constructor.md +++ b/docs/api/XCEngine/Audio/AudioMixer/Constructor.md @@ -1,28 +1,25 @@ # AudioMixer::AudioMixer() -构造对象。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/AudioMixer.h` + +## 签名 ```cpp AudioMixer(); ``` -该方法声明于 `XCEngine/Audio/AudioMixer.h`，当前页面用于固定 `AudioMixer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行该公开方法对应的当前实现。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::AudioMixer object; -} -``` +- 执行该公开方法对应的当前实现。 ## 相关文档 -- [返回类总览](AudioMixer.md) -- [返回模块目录](../Audio.md) +- [AudioMixer](AudioMixer.md) diff --git a/docs/api/XCEngine/Audio/AudioMixer/Destructor.md b/docs/api/XCEngine/Audio/AudioMixer/Destructor.md index 64bb8edd..88b06c84 100644 --- a/docs/api/XCEngine/Audio/AudioMixer/Destructor.md +++ b/docs/api/XCEngine/Audio/AudioMixer/Destructor.md @@ -1,29 +1,25 @@ # AudioMixer::~AudioMixer() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/AudioMixer.h` + +## 签名 ```cpp ~AudioMixer(); ``` -该方法声明于 `XCEngine/Audio/AudioMixer.h`，当前页面用于固定 `AudioMixer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +当前实现为空。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::AudioMixer object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 当前函数体为空。 ## 相关文档 -- [返回类总览](AudioMixer.md) -- [返回模块目录](../Audio.md) +- [AudioMixer](AudioMixer.md) diff --git a/docs/api/XCEngine/Audio/AudioMixer/Get3DParams.md b/docs/api/XCEngine/Audio/AudioMixer/Get3DParams.md index 090626d7..0851eb24 100644 --- a/docs/api/XCEngine/Audio/AudioMixer/Get3DParams.md +++ b/docs/api/XCEngine/Audio/AudioMixer/Get3DParams.md @@ -1,30 +1,26 @@ # AudioMixer::Get3DParams -获取相关状态或对象。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/AudioMixer.h` + +## 签名 ```cpp const Audio3DParams& Get3DParams() const; ``` -该方法声明于 `XCEngine/Audio/AudioMixer.h`，当前页面用于固定 `AudioMixer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_3DParams`。 -**返回：** `const Audio3DParams&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::AudioMixer object; - // 根据上下文补齐参数后调用 AudioMixer::Get3DParams(...)。 - (void)object; -} -``` +- 返回 `m_3DParams`。 ## 相关文档 -- [返回类总览](AudioMixer.md) -- [返回模块目录](../Audio.md) +- [AudioMixer](AudioMixer.md) +- [Set3DParams](Set3DParams.md) diff --git a/docs/api/XCEngine/Audio/AudioMixer/GetChannelVolume.md b/docs/api/XCEngine/Audio/AudioMixer/GetChannelVolume.md index 088f045d..d2bc02dd 100644 --- a/docs/api/XCEngine/Audio/AudioMixer/GetChannelVolume.md +++ b/docs/api/XCEngine/Audio/AudioMixer/GetChannelVolume.md @@ -1,31 +1,28 @@ # AudioMixer::GetChannelVolume -获取相关状态或对象。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/AudioMixer.h` + +## 签名 ```cpp float GetChannelVolume(AudioChannel channel) const; ``` -该方法声明于 `XCEngine/Audio/AudioMixer.h`，当前页面用于固定 `AudioMixer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `channel` - 参数语义详见头文件声明。 +更新 `m_channelVolumes`。 -**返回：** `float` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::AudioMixer object; - // 根据上下文补齐参数后调用 AudioMixer::GetChannelVolume(...)。 - (void)object; -} -``` +- 会更新 `m_channelVolumes`。 +- 当前实现会调用 `find`、`end`。 +- 包含条件分支，并可能提前返回。 ## 相关文档 -- [返回类总览](AudioMixer.md) -- [返回模块目录](../Audio.md) +- [AudioMixer](AudioMixer.md) +- [SetChannelVolume](SetChannelVolume.md) diff --git a/docs/api/XCEngine/Audio/AudioMixer/GetOutputMixer.md b/docs/api/XCEngine/Audio/AudioMixer/GetOutputMixer.md index 1400dc05..721ec0ad 100644 --- a/docs/api/XCEngine/Audio/AudioMixer/GetOutputMixer.md +++ b/docs/api/XCEngine/Audio/AudioMixer/GetOutputMixer.md @@ -1,30 +1,26 @@ # AudioMixer::GetOutputMixer -获取相关状态或对象。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/AudioMixer.h` + +## 签名 ```cpp AudioMixer* GetOutputMixer() const; ``` -该方法声明于 `XCEngine/Audio/AudioMixer.h`，当前页面用于固定 `AudioMixer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_outputMixer` 当前值。 -**返回：** `AudioMixer*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::AudioMixer object; - // 根据上下文补齐参数后调用 AudioMixer::GetOutputMixer(...)。 - (void)object; -} -``` +- 返回 `m_outputMixer` 当前值。 ## 相关文档 -- [返回类总览](AudioMixer.md) -- [返回模块目录](../Audio.md) +- [AudioMixer](AudioMixer.md) +- [SetOutputMixer](SetOutputMixer.md) diff --git a/docs/api/XCEngine/Audio/AudioMixer/GetVolume.md b/docs/api/XCEngine/Audio/AudioMixer/GetVolume.md index 6ecc92b4..69685cdb 100644 --- a/docs/api/XCEngine/Audio/AudioMixer/GetVolume.md +++ b/docs/api/XCEngine/Audio/AudioMixer/GetVolume.md @@ -1,30 +1,26 @@ # AudioMixer::GetVolume -获取相关状态或对象。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/AudioMixer.h` + +## 签名 ```cpp float GetVolume() const; ``` -该方法声明于 `XCEngine/Audio/AudioMixer.h`，当前页面用于固定 `AudioMixer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_volume` 当前值。 -**返回：** `float` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::AudioMixer object; - // 根据上下文补齐参数后调用 AudioMixer::GetVolume(...)。 - (void)object; -} -``` +- 返回 `m_volume` 当前值。 ## 相关文档 -- [返回类总览](AudioMixer.md) -- [返回模块目录](../Audio.md) +- [AudioMixer](AudioMixer.md) +- [SetVolume](SetVolume.md) diff --git a/docs/api/XCEngine/Audio/AudioMixer/IsMute.md b/docs/api/XCEngine/Audio/AudioMixer/IsMute.md index 16773b74..588348c6 100644 --- a/docs/api/XCEngine/Audio/AudioMixer/IsMute.md +++ b/docs/api/XCEngine/Audio/AudioMixer/IsMute.md @@ -1,30 +1,25 @@ # AudioMixer::IsMute -查询当前状态。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/AudioMixer.h` + +## 签名 ```cpp bool IsMute() const; ``` -该方法声明于 `XCEngine/Audio/AudioMixer.h`，当前页面用于固定 `AudioMixer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_mute` 当前值。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::AudioMixer object; - // 根据上下文补齐参数后调用 AudioMixer::IsMute(...)。 - (void)object; -} -``` +- 返回 `m_mute` 当前值。 ## 相关文档 -- [返回类总览](AudioMixer.md) -- [返回模块目录](../Audio.md) +- [AudioMixer](AudioMixer.md) diff --git a/docs/api/XCEngine/Audio/AudioMixer/ProcessAudio.md b/docs/api/XCEngine/Audio/AudioMixer/ProcessAudio.md index bd08df4c..a2e454d8 100644 --- a/docs/api/XCEngine/Audio/AudioMixer/ProcessAudio.md +++ b/docs/api/XCEngine/Audio/AudioMixer/ProcessAudio.md @@ -1,33 +1,25 @@ # AudioMixer::ProcessAudio -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/AudioMixer.h` + +## 签名 ```cpp void ProcessAudio(float* buffer, uint32 sampleCount, uint32 channels); ``` -该方法声明于 `XCEngine/Audio/AudioMixer.h`，当前页面用于固定 `AudioMixer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `buffer` - 参数语义详见头文件声明。 -- `sampleCount` - 参数语义详见头文件声明。 -- `channels` - 参数语义详见头文件声明。 +执行该公开方法对应的当前实现。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::AudioMixer object; - // 根据上下文补齐参数后调用 AudioMixer::ProcessAudio(...)。 - (void)object; -} -``` +- 执行该公开方法对应的当前实现。 ## 相关文档 -- [返回类总览](AudioMixer.md) -- [返回模块目录](../Audio.md) +- [AudioMixer](AudioMixer.md) diff --git a/docs/api/XCEngine/Audio/AudioMixer/RemoveEffect.md b/docs/api/XCEngine/Audio/AudioMixer/RemoveEffect.md index 7c8191d9..f1c6faa1 100644 --- a/docs/api/XCEngine/Audio/AudioMixer/RemoveEffect.md +++ b/docs/api/XCEngine/Audio/AudioMixer/RemoveEffect.md @@ -1,31 +1,26 @@ # AudioMixer::RemoveEffect -移除元素或解除关联。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/AudioMixer.h` + +## 签名 ```cpp void RemoveEffect(IAudioEffect* effect); ``` -该方法声明于 `XCEngine/Audio/AudioMixer.h`，当前页面用于固定 `AudioMixer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `effect` - 参数语义详见头文件声明。 +更新 `m_effects`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::AudioMixer object; - // 根据上下文补齐参数后调用 AudioMixer::RemoveEffect(...)。 - (void)object; -} -``` +- 会更新 `m_effects`。 +- 当前实现会调用 `find`、`begin`、`end`、`erase`。 ## 相关文档 -- [返回类总览](AudioMixer.md) -- [返回模块目录](../Audio.md) +- [AudioMixer](AudioMixer.md) diff --git a/docs/api/XCEngine/Audio/AudioMixer/Set3DParams.md b/docs/api/XCEngine/Audio/AudioMixer/Set3DParams.md index 94ba3fa7..dd4ebbd4 100644 --- a/docs/api/XCEngine/Audio/AudioMixer/Set3DParams.md +++ b/docs/api/XCEngine/Audio/AudioMixer/Set3DParams.md @@ -1,31 +1,26 @@ # AudioMixer::Set3DParams -设置相关状态或配置。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/AudioMixer.h` + +## 签名 ```cpp void Set3DParams(const Audio3DParams& params); ``` -该方法声明于 `XCEngine/Audio/AudioMixer.h`，当前页面用于固定 `AudioMixer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `params` - 参数语义详见头文件声明。 +执行该公开方法对应的当前实现。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::AudioMixer object; - // 根据上下文补齐参数后调用 AudioMixer::Set3DParams(...)。 - (void)object; -} -``` +- 执行该公开方法对应的当前实现。 ## 相关文档 -- [返回类总览](AudioMixer.md) -- [返回模块目录](../Audio.md) +- [AudioMixer](AudioMixer.md) +- [Get3DParams](Get3DParams.md) diff --git a/docs/api/XCEngine/Audio/AudioMixer/SetChannelVolume.md b/docs/api/XCEngine/Audio/AudioMixer/SetChannelVolume.md index 28d8591e..dc1e0e14 100644 --- a/docs/api/XCEngine/Audio/AudioMixer/SetChannelVolume.md +++ b/docs/api/XCEngine/Audio/AudioMixer/SetChannelVolume.md @@ -1,32 +1,27 @@ # AudioMixer::SetChannelVolume -设置相关状态或配置。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/AudioMixer.h` + +## 签名 ```cpp void SetChannelVolume(AudioChannel channel, float volume); ``` -该方法声明于 `XCEngine/Audio/AudioMixer.h`，当前页面用于固定 `AudioMixer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `channel` - 参数语义详见头文件声明。 -- `volume` - 参数语义详见头文件声明。 +更新 `m_channelVolumes`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::AudioMixer object; - // 根据上下文补齐参数后调用 AudioMixer::SetChannelVolume(...)。 - (void)object; -} -``` +- 会更新 `m_channelVolumes`。 +- 当前实现会调用 `find`、`end`、`max`、`min`。 ## 相关文档 -- [返回类总览](AudioMixer.md) -- [返回模块目录](../Audio.md) +- [AudioMixer](AudioMixer.md) +- [GetChannelVolume](GetChannelVolume.md) diff --git a/docs/api/XCEngine/Audio/AudioMixer/SetMute.md b/docs/api/XCEngine/Audio/AudioMixer/SetMute.md index 0f18e8b8..ee75bdc2 100644 --- a/docs/api/XCEngine/Audio/AudioMixer/SetMute.md +++ b/docs/api/XCEngine/Audio/AudioMixer/SetMute.md @@ -1,31 +1,25 @@ # AudioMixer::SetMute -设置相关状态或配置。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/AudioMixer.h` + +## 签名 ```cpp void SetMute(bool mute); ``` -该方法声明于 `XCEngine/Audio/AudioMixer.h`，当前页面用于固定 `AudioMixer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `mute` - 参数语义详见头文件声明。 +更新 `m_mute`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::AudioMixer object; - // 根据上下文补齐参数后调用 AudioMixer::SetMute(...)。 - (void)object; -} -``` +- 会更新 `m_mute`。 ## 相关文档 -- [返回类总览](AudioMixer.md) -- [返回模块目录](../Audio.md) +- [AudioMixer](AudioMixer.md) diff --git a/docs/api/XCEngine/Audio/AudioMixer/SetOutputMixer.md b/docs/api/XCEngine/Audio/AudioMixer/SetOutputMixer.md index f216edf5..16366747 100644 --- a/docs/api/XCEngine/Audio/AudioMixer/SetOutputMixer.md +++ b/docs/api/XCEngine/Audio/AudioMixer/SetOutputMixer.md @@ -1,31 +1,26 @@ # AudioMixer::SetOutputMixer -设置相关状态或配置。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/AudioMixer.h` + +## 签名 ```cpp void SetOutputMixer(AudioMixer* mixer); ``` -该方法声明于 `XCEngine/Audio/AudioMixer.h`，当前页面用于固定 `AudioMixer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `mixer` - 参数语义详见头文件声明。 +更新 `m_outputMixer`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::AudioMixer object; - // 根据上下文补齐参数后调用 AudioMixer::SetOutputMixer(...)。 - (void)object; -} -``` +- 会更新 `m_outputMixer`。 ## 相关文档 -- [返回类总览](AudioMixer.md) -- [返回模块目录](../Audio.md) +- [AudioMixer](AudioMixer.md) +- [GetOutputMixer](GetOutputMixer.md) diff --git a/docs/api/XCEngine/Audio/AudioMixer/SetVolume.md b/docs/api/XCEngine/Audio/AudioMixer/SetVolume.md index ac716d0b..f003c542 100644 --- a/docs/api/XCEngine/Audio/AudioMixer/SetVolume.md +++ b/docs/api/XCEngine/Audio/AudioMixer/SetVolume.md @@ -1,31 +1,27 @@ # AudioMixer::SetVolume -设置相关状态或配置。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/AudioMixer.h` + +## 签名 ```cpp void SetVolume(float volume); ``` -该方法声明于 `XCEngine/Audio/AudioMixer.h`，当前页面用于固定 `AudioMixer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `volume` - 参数语义详见头文件声明。 +更新 `m_volume`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::AudioMixer object; - // 根据上下文补齐参数后调用 AudioMixer::SetVolume(...)。 - (void)object; -} -``` +- 会更新 `m_volume`。 +- 当前实现会调用 `max`、`min`。 ## 相关文档 -- [返回类总览](AudioMixer.md) -- [返回模块目录](../Audio.md) +- [AudioMixer](AudioMixer.md) +- [GetVolume](GetVolume.md) diff --git a/docs/api/XCEngine/Audio/AudioSystem/Get.md b/docs/api/XCEngine/Audio/AudioSystem/Get.md index 441a07d7..531bd76a 100644 --- a/docs/api/XCEngine/Audio/AudioSystem/Get.md +++ b/docs/api/XCEngine/Audio/AudioSystem/Get.md @@ -1,29 +1,25 @@ # AudioSystem::Get -获取相关状态或对象。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/AudioSystem.h` + +## 签名 ```cpp static AudioSystem& Get(); ``` -该方法声明于 `XCEngine/Audio/AudioSystem.h`，当前页面用于固定 `AudioSystem` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `instance`。 -**返回：** `AudioSystem&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - auto& instance = XCEngine::Audio::AudioSystem::Get(); - (void)instance; -} -``` +- 返回 `instance`。 ## 相关文档 -- [返回类总览](AudioSystem.md) -- [返回模块目录](../Audio.md) +- [AudioSystem](AudioSystem.md) diff --git a/docs/api/XCEngine/Audio/AudioSystem/GetAvailableDevices.md b/docs/api/XCEngine/Audio/AudioSystem/GetAvailableDevices.md index 2fbe5fdb..55f07ebc 100644 --- a/docs/api/XCEngine/Audio/AudioSystem/GetAvailableDevices.md +++ b/docs/api/XCEngine/Audio/AudioSystem/GetAvailableDevices.md @@ -1,31 +1,25 @@ # AudioSystem::GetAvailableDevices -获取相关状态或对象。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/AudioSystem.h` + +## 签名 ```cpp void GetAvailableDevices(std::vector& devices); ``` -该方法声明于 `XCEngine/Audio/AudioSystem.h`，当前页面用于固定 `AudioSystem` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `devices` - 参数语义详见头文件声明。 +执行 `GetAvailableDevices` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::AudioSystem object; - // 根据上下文补齐参数后调用 AudioSystem::GetAvailableDevices(...)。 - (void)object; -} -``` +- 当前实现会调用 `GetAvailableDevices`。 ## 相关文档 -- [返回类总览](AudioSystem.md) -- [返回模块目录](../Audio.md) +- [AudioSystem](AudioSystem.md) diff --git a/docs/api/XCEngine/Audio/AudioSystem/GetBackend.md b/docs/api/XCEngine/Audio/AudioSystem/GetBackend.md index 4459a81d..32685776 100644 --- a/docs/api/XCEngine/Audio/AudioSystem/GetBackend.md +++ b/docs/api/XCEngine/Audio/AudioSystem/GetBackend.md @@ -1,30 +1,27 @@ # AudioSystem::GetBackend -获取相关状态或对象。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/AudioSystem.h` + +## 签名 ```cpp IAudioBackend* GetBackend() const; ``` -该方法声明于 `XCEngine/Audio/AudioSystem.h`，当前页面用于固定 `AudioSystem` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_backend`。 -**返回：** `IAudioBackend*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::AudioSystem object; - // 根据上下文补齐参数后调用 AudioSystem::GetBackend(...)。 - (void)object; -} -``` +- 会更新 `m_backend`。 +- 当前实现会调用 `get`。 ## 相关文档 -- [返回类总览](AudioSystem.md) -- [返回模块目录](../Audio.md) +- [AudioSystem](AudioSystem.md) +- [SetBackend](SetBackend.md) diff --git a/docs/api/XCEngine/Audio/AudioSystem/GetCurrentDevice.md b/docs/api/XCEngine/Audio/AudioSystem/GetCurrentDevice.md index 3bc80b76..8ecfa992 100644 --- a/docs/api/XCEngine/Audio/AudioSystem/GetCurrentDevice.md +++ b/docs/api/XCEngine/Audio/AudioSystem/GetCurrentDevice.md @@ -1,30 +1,26 @@ # AudioSystem::GetCurrentDevice -获取相关状态或对象。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/AudioSystem.h` + +## 签名 ```cpp std::string GetCurrentDevice() const; ``` -该方法声明于 `XCEngine/Audio/AudioSystem.h`，当前页面用于固定 `AudioSystem` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `GetDeviceName` 协同流程。 -**返回：** `std::string` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::AudioSystem object; - // 根据上下文补齐参数后调用 AudioSystem::GetCurrentDevice(...)。 - (void)object; -} -``` +- 当前实现会调用 `GetDeviceName`。 +- 包含条件分支，并可能提前返回。 ## 相关文档 -- [返回类总览](AudioSystem.md) -- [返回模块目录](../Audio.md) +- [AudioSystem](AudioSystem.md) diff --git a/docs/api/XCEngine/Audio/AudioSystem/GetListenerPosition.md b/docs/api/XCEngine/Audio/AudioSystem/GetListenerPosition.md index b4675eef..3388a9cc 100644 --- a/docs/api/XCEngine/Audio/AudioSystem/GetListenerPosition.md +++ b/docs/api/XCEngine/Audio/AudioSystem/GetListenerPosition.md @@ -1,30 +1,25 @@ # AudioSystem::GetListenerPosition -获取相关状态或对象。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/AudioSystem.h` + +## 签名 ```cpp const Math::Vector3& GetListenerPosition() const; ``` -该方法声明于 `XCEngine/Audio/AudioSystem.h`，当前页面用于固定 `AudioSystem` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_listenerPosition` 当前值。 -**返回：** `const Math::Vector3&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::AudioSystem object; - // 根据上下文补齐参数后调用 AudioSystem::GetListenerPosition(...)。 - (void)object; -} -``` +- 返回 `m_listenerPosition` 当前值。 ## 相关文档 -- [返回类总览](AudioSystem.md) -- [返回模块目录](../Audio.md) +- [AudioSystem](AudioSystem.md) diff --git a/docs/api/XCEngine/Audio/AudioSystem/GetListenerRotation.md b/docs/api/XCEngine/Audio/AudioSystem/GetListenerRotation.md index 1a24bc65..89876620 100644 --- a/docs/api/XCEngine/Audio/AudioSystem/GetListenerRotation.md +++ b/docs/api/XCEngine/Audio/AudioSystem/GetListenerRotation.md @@ -1,30 +1,25 @@ # AudioSystem::GetListenerRotation -获取相关状态或对象。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/AudioSystem.h` + +## 签名 ```cpp const Math::Quaternion& GetListenerRotation() const; ``` -该方法声明于 `XCEngine/Audio/AudioSystem.h`，当前页面用于固定 `AudioSystem` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_listenerRotation` 当前值。 -**返回：** `const Math::Quaternion&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::AudioSystem object; - // 根据上下文补齐参数后调用 AudioSystem::GetListenerRotation(...)。 - (void)object; -} -``` +- 返回 `m_listenerRotation` 当前值。 ## 相关文档 -- [返回类总览](AudioSystem.md) -- [返回模块目录](../Audio.md) +- [AudioSystem](AudioSystem.md) diff --git a/docs/api/XCEngine/Audio/AudioSystem/GetListenerVelocity.md b/docs/api/XCEngine/Audio/AudioSystem/GetListenerVelocity.md index b87db94b..82cb87f7 100644 --- a/docs/api/XCEngine/Audio/AudioSystem/GetListenerVelocity.md +++ b/docs/api/XCEngine/Audio/AudioSystem/GetListenerVelocity.md @@ -1,30 +1,26 @@ # AudioSystem::GetListenerVelocity -获取相关状态或对象。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/AudioSystem.h` + +## 签名 ```cpp const Math::Vector3& GetListenerVelocity() const; ``` -该方法声明于 `XCEngine/Audio/AudioSystem.h`，当前页面用于固定 `AudioSystem` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_listenerVelocity` 当前值。 -**返回：** `const Math::Vector3&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::AudioSystem object; - // 根据上下文补齐参数后调用 AudioSystem::GetListenerVelocity(...)。 - (void)object; -} -``` +- 返回 `m_listenerVelocity` 当前值。 ## 相关文档 -- [返回类总览](AudioSystem.md) -- [返回模块目录](../Audio.md) +- [AudioSystem](AudioSystem.md) +- [SetListenerVelocity](SetListenerVelocity.md) diff --git a/docs/api/XCEngine/Audio/AudioSystem/GetMasterVolume.md b/docs/api/XCEngine/Audio/AudioSystem/GetMasterVolume.md index ed86cb6e..29468bbb 100644 --- a/docs/api/XCEngine/Audio/AudioSystem/GetMasterVolume.md +++ b/docs/api/XCEngine/Audio/AudioSystem/GetMasterVolume.md @@ -1,30 +1,27 @@ # AudioSystem::GetMasterVolume -获取相关状态或对象。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/AudioSystem.h` + +## 签名 ```cpp float GetMasterVolume() const; ``` -该方法声明于 `XCEngine/Audio/AudioSystem.h`，当前页面用于固定 `AudioSystem` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `GetMasterVolume` 协同流程。 -**返回：** `float` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::AudioSystem object; - // 根据上下文补齐参数后调用 AudioSystem::GetMasterVolume(...)。 - (void)object; -} -``` +- 当前实现会调用 `GetMasterVolume`。 +- 包含条件分支，并可能提前返回。 ## 相关文档 -- [返回类总览](AudioSystem.md) -- [返回模块目录](../Audio.md) +- [AudioSystem](AudioSystem.md) +- [SetMasterVolume](SetMasterVolume.md) diff --git a/docs/api/XCEngine/Audio/AudioSystem/GetStats.md b/docs/api/XCEngine/Audio/AudioSystem/GetStats.md index ec8d7bda..61b8f772 100644 --- a/docs/api/XCEngine/Audio/AudioSystem/GetStats.md +++ b/docs/api/XCEngine/Audio/AudioSystem/GetStats.md @@ -1,30 +1,25 @@ # AudioSystem::GetStats -获取相关状态或对象。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/AudioSystem.h` + +## 签名 ```cpp const Stats& GetStats() const; ``` -该方法声明于 `XCEngine/Audio/AudioSystem.h`，当前页面用于固定 `AudioSystem` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_stats` 当前值。 -**返回：** `const Stats&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::AudioSystem object; - // 根据上下文补齐参数后调用 AudioSystem::GetStats(...)。 - (void)object; -} -``` +- 返回 `m_stats` 当前值。 ## 相关文档 -- [返回类总览](AudioSystem.md) -- [返回模块目录](../Audio.md) +- [AudioSystem](AudioSystem.md) diff --git a/docs/api/XCEngine/Audio/AudioSystem/Initialize.md b/docs/api/XCEngine/Audio/AudioSystem/Initialize.md index 034a499c..cfe31027 100644 --- a/docs/api/XCEngine/Audio/AudioSystem/Initialize.md +++ b/docs/api/XCEngine/Audio/AudioSystem/Initialize.md @@ -1,31 +1,26 @@ # AudioSystem::Initialize -初始化内部状态。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/AudioSystem.h` + +## 签名 ```cpp void Initialize(const AudioConfig& config); ``` -该方法声明于 `XCEngine/Audio/AudioSystem.h`，当前页面用于固定 `AudioSystem` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `config` - 参数语义详见头文件声明。 +更新 `m_backend`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::AudioSystem object; - // 根据上下文补齐参数后调用 AudioSystem::Initialize(...)。 - (void)object; -} -``` +- 会更新 `m_backend`。 +- 当前实现会调用 `Shutdown`、`Initialize`、`Start`、`reset`。 ## 相关文档 -- [返回类总览](AudioSystem.md) -- [返回模块目录](../Audio.md) +- [AudioSystem](AudioSystem.md) diff --git a/docs/api/XCEngine/Audio/AudioSystem/IsMuted.md b/docs/api/XCEngine/Audio/AudioSystem/IsMuted.md index 02ddd391..d322fee7 100644 --- a/docs/api/XCEngine/Audio/AudioSystem/IsMuted.md +++ b/docs/api/XCEngine/Audio/AudioSystem/IsMuted.md @@ -1,30 +1,26 @@ # AudioSystem::IsMuted -查询当前状态。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/AudioSystem.h` + +## 签名 ```cpp bool IsMuted() const; ``` -该方法声明于 `XCEngine/Audio/AudioSystem.h`，当前页面用于固定 `AudioSystem` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `IsMuted` 协同流程。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::AudioSystem object; - // 根据上下文补齐参数后调用 AudioSystem::IsMuted(...)。 - (void)object; -} -``` +- 当前实现会调用 `IsMuted`。 +- 包含条件分支，并可能提前返回。 ## 相关文档 -- [返回类总览](AudioSystem.md) -- [返回模块目录](../Audio.md) +- [AudioSystem](AudioSystem.md) diff --git a/docs/api/XCEngine/Audio/AudioSystem/ProcessAudio.md b/docs/api/XCEngine/Audio/AudioSystem/ProcessAudio.md index e52cdc59..5c0c9b34 100644 --- a/docs/api/XCEngine/Audio/AudioSystem/ProcessAudio.md +++ b/docs/api/XCEngine/Audio/AudioSystem/ProcessAudio.md @@ -1,33 +1,25 @@ # AudioSystem::ProcessAudio -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/AudioSystem.h` + +## 签名 ```cpp void ProcessAudio(float* buffer, uint32 sampleCount, uint32 channels); ``` -该方法声明于 `XCEngine/Audio/AudioSystem.h`，当前页面用于固定 `AudioSystem` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `buffer` - 参数语义详见头文件声明。 -- `sampleCount` - 参数语义详见头文件声明。 -- `channels` - 参数语义详见头文件声明。 +执行 `ProcessAudio` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::AudioSystem object; - // 根据上下文补齐参数后调用 AudioSystem::ProcessAudio(...)。 - (void)object; -} -``` +- 当前实现会调用 `ProcessAudio`。 ## 相关文档 -- [返回类总览](AudioSystem.md) -- [返回模块目录](../Audio.md) +- [AudioSystem](AudioSystem.md) diff --git a/docs/api/XCEngine/Audio/AudioSystem/RegisterSource.md b/docs/api/XCEngine/Audio/AudioSystem/RegisterSource.md index 7a038527..b90684ca 100644 --- a/docs/api/XCEngine/Audio/AudioSystem/RegisterSource.md +++ b/docs/api/XCEngine/Audio/AudioSystem/RegisterSource.md @@ -1,31 +1,26 @@ # AudioSystem::RegisterSource -注册对象、回调或映射。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/AudioSystem.h` + +## 签名 ```cpp void RegisterSource(Components::AudioSourceComponent* source); ``` -该方法声明于 `XCEngine/Audio/AudioSystem.h`，当前页面用于固定 `AudioSystem` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `source` - 参数语义详见头文件声明。 +更新 `m_activeSources`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::AudioSystem object; - // 根据上下文补齐参数后调用 AudioSystem::RegisterSource(...)。 - (void)object; -} -``` +- 会更新 `m_activeSources`。 +- 当前实现会调用 `push_back`。 ## 相关文档 -- [返回类总览](AudioSystem.md) -- [返回模块目录](../Audio.md) +- [AudioSystem](AudioSystem.md) diff --git a/docs/api/XCEngine/Audio/AudioSystem/SetBackend.md b/docs/api/XCEngine/Audio/AudioSystem/SetBackend.md index 444cdc20..a2174dcc 100644 --- a/docs/api/XCEngine/Audio/AudioSystem/SetBackend.md +++ b/docs/api/XCEngine/Audio/AudioSystem/SetBackend.md @@ -1,31 +1,27 @@ # AudioSystem::SetBackend -设置相关状态或配置。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/AudioSystem.h` + +## 签名 ```cpp void SetBackend(std::unique_ptr backend); ``` -该方法声明于 `XCEngine/Audio/AudioSystem.h`，当前页面用于固定 `AudioSystem` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `backend` - 参数语义详见头文件声明。 +更新 `m_backend`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::AudioSystem object; - // 根据上下文补齐参数后调用 AudioSystem::SetBackend(...)。 - (void)object; -} -``` +- 会更新 `m_backend`。 +- 当前实现会调用 `move`。 ## 相关文档 -- [返回类总览](AudioSystem.md) -- [返回模块目录](../Audio.md) +- [AudioSystem](AudioSystem.md) +- [GetBackend](GetBackend.md) diff --git a/docs/api/XCEngine/Audio/AudioSystem/SetDevice.md b/docs/api/XCEngine/Audio/AudioSystem/SetDevice.md index 89639fc1..28ea52c0 100644 --- a/docs/api/XCEngine/Audio/AudioSystem/SetDevice.md +++ b/docs/api/XCEngine/Audio/AudioSystem/SetDevice.md @@ -1,31 +1,25 @@ # AudioSystem::SetDevice -设置相关状态或配置。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/AudioSystem.h` + +## 签名 ```cpp void SetDevice(const std::string& deviceName); ``` -该方法声明于 `XCEngine/Audio/AudioSystem.h`，当前页面用于固定 `AudioSystem` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `deviceName` - 参数语义详见头文件声明。 +执行 `SetDevice` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::AudioSystem object; - // 根据上下文补齐参数后调用 AudioSystem::SetDevice(...)。 - (void)object; -} -``` +- 当前实现会调用 `SetDevice`。 ## 相关文档 -- [返回类总览](AudioSystem.md) -- [返回模块目录](../Audio.md) +- [AudioSystem](AudioSystem.md) diff --git a/docs/api/XCEngine/Audio/AudioSystem/SetListenerTransform.md b/docs/api/XCEngine/Audio/AudioSystem/SetListenerTransform.md index 2d85c242..14fca4c0 100644 --- a/docs/api/XCEngine/Audio/AudioSystem/SetListenerTransform.md +++ b/docs/api/XCEngine/Audio/AudioSystem/SetListenerTransform.md @@ -1,32 +1,25 @@ # AudioSystem::SetListenerTransform -设置相关状态或配置。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/AudioSystem.h` + +## 签名 ```cpp void SetListenerTransform(const Math::Vector3& position, const Math::Quaternion& rotation); ``` -该方法声明于 `XCEngine/Audio/AudioSystem.h`，当前页面用于固定 `AudioSystem` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `position` - 参数语义详见头文件声明。 -- `rotation` - 参数语义详见头文件声明。 +执行该公开方法对应的当前实现。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::AudioSystem object; - // 根据上下文补齐参数后调用 AudioSystem::SetListenerTransform(...)。 - (void)object; -} -``` +- 会更新 `m_listenerPosition`、`m_listenerRotation`。 ## 相关文档 -- [返回类总览](AudioSystem.md) -- [返回模块目录](../Audio.md) +- [AudioSystem](AudioSystem.md) diff --git a/docs/api/XCEngine/Audio/AudioSystem/SetListenerVelocity.md b/docs/api/XCEngine/Audio/AudioSystem/SetListenerVelocity.md index dba94b3f..6943bf2d 100644 --- a/docs/api/XCEngine/Audio/AudioSystem/SetListenerVelocity.md +++ b/docs/api/XCEngine/Audio/AudioSystem/SetListenerVelocity.md @@ -1,31 +1,26 @@ # AudioSystem::SetListenerVelocity -设置相关状态或配置。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/AudioSystem.h` + +## 签名 ```cpp void SetListenerVelocity(const Math::Vector3& velocity); ``` -该方法声明于 `XCEngine/Audio/AudioSystem.h`，当前页面用于固定 `AudioSystem` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `velocity` - 参数语义详见头文件声明。 +更新 `m_listenerVelocity`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::AudioSystem object; - // 根据上下文补齐参数后调用 AudioSystem::SetListenerVelocity(...)。 - (void)object; -} -``` +- 会更新 `m_listenerVelocity`。 ## 相关文档 -- [返回类总览](AudioSystem.md) -- [返回模块目录](../Audio.md) +- [AudioSystem](AudioSystem.md) +- [GetListenerVelocity](GetListenerVelocity.md) diff --git a/docs/api/XCEngine/Audio/AudioSystem/SetMasterVolume.md b/docs/api/XCEngine/Audio/AudioSystem/SetMasterVolume.md index f4313fb5..ff9ad7ae 100644 --- a/docs/api/XCEngine/Audio/AudioSystem/SetMasterVolume.md +++ b/docs/api/XCEngine/Audio/AudioSystem/SetMasterVolume.md @@ -1,31 +1,26 @@ # AudioSystem::SetMasterVolume -设置相关状态或配置。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/AudioSystem.h` + +## 签名 ```cpp void SetMasterVolume(float volume); ``` -该方法声明于 `XCEngine/Audio/AudioSystem.h`，当前页面用于固定 `AudioSystem` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `volume` - 参数语义详见头文件声明。 +执行 `SetMasterVolume` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::AudioSystem object; - // 根据上下文补齐参数后调用 AudioSystem::SetMasterVolume(...)。 - (void)object; -} -``` +- 当前实现会调用 `SetMasterVolume`。 ## 相关文档 -- [返回类总览](AudioSystem.md) -- [返回模块目录](../Audio.md) +- [AudioSystem](AudioSystem.md) +- [GetMasterVolume](GetMasterVolume.md) diff --git a/docs/api/XCEngine/Audio/AudioSystem/SetMuted.md b/docs/api/XCEngine/Audio/AudioSystem/SetMuted.md index 46befc70..13eccd38 100644 --- a/docs/api/XCEngine/Audio/AudioSystem/SetMuted.md +++ b/docs/api/XCEngine/Audio/AudioSystem/SetMuted.md @@ -1,31 +1,25 @@ # AudioSystem::SetMuted -设置相关状态或配置。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/AudioSystem.h` + +## 签名 ```cpp void SetMuted(bool muted); ``` -该方法声明于 `XCEngine/Audio/AudioSystem.h`，当前页面用于固定 `AudioSystem` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `muted` - 参数语义详见头文件声明。 +执行 `SetMuted` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::AudioSystem object; - // 根据上下文补齐参数后调用 AudioSystem::SetMuted(...)。 - (void)object; -} -``` +- 当前实现会调用 `SetMuted`。 ## 相关文档 -- [返回类总览](AudioSystem.md) -- [返回模块目录](../Audio.md) +- [AudioSystem](AudioSystem.md) diff --git a/docs/api/XCEngine/Audio/AudioSystem/Shutdown.md b/docs/api/XCEngine/Audio/AudioSystem/Shutdown.md index 9bc983b6..2be61302 100644 --- a/docs/api/XCEngine/Audio/AudioSystem/Shutdown.md +++ b/docs/api/XCEngine/Audio/AudioSystem/Shutdown.md @@ -1,30 +1,25 @@ # AudioSystem::Shutdown -关闭并清理内部状态。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/AudioSystem.h` + +## 签名 ```cpp void Shutdown(); ``` -该方法声明于 `XCEngine/Audio/AudioSystem.h`，当前页面用于固定 `AudioSystem` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `Stop`、`Shutdown`、`reset` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::AudioSystem object; - // 根据上下文补齐参数后调用 AudioSystem::Shutdown(...)。 - (void)object; -} -``` +- 当前实现会调用 `Stop`、`Shutdown`、`reset`、`clear`。 ## 相关文档 -- [返回类总览](AudioSystem.md) -- [返回模块目录](../Audio.md) +- [AudioSystem](AudioSystem.md) diff --git a/docs/api/XCEngine/Audio/AudioSystem/UnregisterSource.md b/docs/api/XCEngine/Audio/AudioSystem/UnregisterSource.md index e405cfb8..bdcebdf3 100644 --- a/docs/api/XCEngine/Audio/AudioSystem/UnregisterSource.md +++ b/docs/api/XCEngine/Audio/AudioSystem/UnregisterSource.md @@ -1,31 +1,26 @@ # AudioSystem::UnregisterSource -取消注册对象、回调或映射。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/AudioSystem.h` + +## 签名 ```cpp void UnregisterSource(Components::AudioSourceComponent* source); ``` -该方法声明于 `XCEngine/Audio/AudioSystem.h`，当前页面用于固定 `AudioSystem` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `source` - 参数语义详见头文件声明。 +更新 `m_activeSources`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::AudioSystem object; - // 根据上下文补齐参数后调用 AudioSystem::UnregisterSource(...)。 - (void)object; -} -``` +- 会更新 `m_activeSources`。 +- 当前实现会调用 `find`、`begin`、`end`、`erase`。 ## 相关文档 -- [返回类总览](AudioSystem.md) -- [返回模块目录](../Audio.md) +- [AudioSystem](AudioSystem.md) diff --git a/docs/api/XCEngine/Audio/AudioSystem/Update.md b/docs/api/XCEngine/Audio/AudioSystem/Update.md index d9cce1a2..7d11c183 100644 --- a/docs/api/XCEngine/Audio/AudioSystem/Update.md +++ b/docs/api/XCEngine/Audio/AudioSystem/Update.md @@ -1,31 +1,26 @@ # AudioSystem::Update -更新运行时状态。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/AudioSystem.h` + +## 签名 ```cpp void Update(float deltaTime); ``` -该方法声明于 `XCEngine/Audio/AudioSystem.h`，当前页面用于固定 `AudioSystem` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `deltaTime` - 参数语义详见头文件声明。 +更新 `m_deltaTime`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::AudioSystem object; - // 根据上下文补齐参数后调用 AudioSystem::Update(...)。 - (void)object; -} -``` +- 会更新 `m_deltaTime`。 +- 当前实现会调用 `IsRunning`、`GetConfig`、`mixBuffer`、`IsEnabled`、`IsPlaying`。 ## 相关文档 -- [返回类总览](AudioSystem.md) -- [返回模块目录](../Audio.md) +- [AudioSystem](AudioSystem.md) diff --git a/docs/api/XCEngine/Audio/Equalizer/Constructor.md b/docs/api/XCEngine/Audio/Equalizer/Constructor.md index bc38d862..2042c4e7 100644 --- a/docs/api/XCEngine/Audio/Equalizer/Constructor.md +++ b/docs/api/XCEngine/Audio/Equalizer/Constructor.md @@ -1,28 +1,25 @@ # Equalizer::Equalizer() -构造对象。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/Equalizer.h` + +## 签名 ```cpp Equalizer(); ``` -该方法声明于 `XCEngine/Audio/Equalizer.h`，当前页面用于固定 `Equalizer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +构造 `Equalizer` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::Equalizer object; -} -``` +- 具体定义位于 `engine/src/Audio/Equalizer.cpp`。 ## 相关文档 -- [返回类总览](Equalizer.md) -- [返回模块目录](../Audio.md) +- [Equalizer](Equalizer.md) diff --git a/docs/api/XCEngine/Audio/Equalizer/Destructor.md b/docs/api/XCEngine/Audio/Equalizer/Destructor.md index 8340fe7d..3d94bbaa 100644 --- a/docs/api/XCEngine/Audio/Equalizer/Destructor.md +++ b/docs/api/XCEngine/Audio/Equalizer/Destructor.md @@ -1,29 +1,25 @@ # Equalizer::~Equalizer() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/Equalizer.h` + +## 签名 ```cpp ~Equalizer() override; ``` -该方法声明于 `XCEngine/Audio/Equalizer.h`，当前页面用于固定 `Equalizer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +当前实现为空。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::Equalizer object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 当前函数体为空。 ## 相关文档 -- [返回类总览](Equalizer.md) -- [返回模块目录](../Audio.md) +- [Equalizer](Equalizer.md) diff --git a/docs/api/XCEngine/Audio/Equalizer/GetBandCount.md b/docs/api/XCEngine/Audio/Equalizer/GetBandCount.md index 7397d19d..32473fe3 100644 --- a/docs/api/XCEngine/Audio/Equalizer/GetBandCount.md +++ b/docs/api/XCEngine/Audio/Equalizer/GetBandCount.md @@ -1,30 +1,26 @@ # Equalizer::GetBandCount -获取相关状态或对象。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/Equalizer.h` + +## 签名 ```cpp uint32 GetBandCount() const; ``` -该方法声明于 `XCEngine/Audio/Equalizer.h`，当前页面用于固定 `Equalizer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_bandCount` 当前值。 -**返回：** `uint32` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::Equalizer object; - // 根据上下文补齐参数后调用 Equalizer::GetBandCount(...)。 - (void)object; -} -``` +- 返回 `m_bandCount` 当前值。 ## 相关文档 -- [返回类总览](Equalizer.md) -- [返回模块目录](../Audio.md) +- [Equalizer](Equalizer.md) +- [SetBandCount](SetBandCount.md) diff --git a/docs/api/XCEngine/Audio/Equalizer/GetBandFrequency.md b/docs/api/XCEngine/Audio/Equalizer/GetBandFrequency.md index 9c24c7e6..79cc6e9d 100644 --- a/docs/api/XCEngine/Audio/Equalizer/GetBandFrequency.md +++ b/docs/api/XCEngine/Audio/Equalizer/GetBandFrequency.md @@ -1,31 +1,26 @@ # Equalizer::GetBandFrequency -获取相关状态或对象。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/Equalizer.h` + +## 签名 ```cpp float GetBandFrequency(uint32 band) const; ``` -该方法声明于 `XCEngine/Audio/Equalizer.h`，当前页面用于固定 `Equalizer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `band` - 参数语义详见头文件声明。 +执行该公开方法对应的当前实现。 -**返回：** `float` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::Equalizer object; - // 根据上下文补齐参数后调用 Equalizer::GetBandFrequency(...)。 - (void)object; -} -``` +- 包含条件分支，并可能提前返回。 ## 相关文档 -- [返回类总览](Equalizer.md) -- [返回模块目录](../Audio.md) +- [Equalizer](Equalizer.md) +- [SetBandFrequency](SetBandFrequency.md) diff --git a/docs/api/XCEngine/Audio/Equalizer/GetBandGain.md b/docs/api/XCEngine/Audio/Equalizer/GetBandGain.md index 37136cb1..20c03687 100644 --- a/docs/api/XCEngine/Audio/Equalizer/GetBandGain.md +++ b/docs/api/XCEngine/Audio/Equalizer/GetBandGain.md @@ -1,31 +1,26 @@ # Equalizer::GetBandGain -获取相关状态或对象。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/Equalizer.h` + +## 签名 ```cpp float GetBandGain(uint32 band) const; ``` -该方法声明于 `XCEngine/Audio/Equalizer.h`，当前页面用于固定 `Equalizer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `band` - 参数语义详见头文件声明。 +执行该公开方法对应的当前实现。 -**返回：** `float` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::Equalizer object; - // 根据上下文补齐参数后调用 Equalizer::GetBandGain(...)。 - (void)object; -} -``` +- 包含条件分支，并可能提前返回。 ## 相关文档 -- [返回类总览](Equalizer.md) -- [返回模块目录](../Audio.md) +- [Equalizer](Equalizer.md) +- [SetBandGain](SetBandGain.md) diff --git a/docs/api/XCEngine/Audio/Equalizer/GetBandQ.md b/docs/api/XCEngine/Audio/Equalizer/GetBandQ.md index f2690d7d..f0b4e71f 100644 --- a/docs/api/XCEngine/Audio/Equalizer/GetBandQ.md +++ b/docs/api/XCEngine/Audio/Equalizer/GetBandQ.md @@ -1,31 +1,26 @@ # Equalizer::GetBandQ -获取相关状态或对象。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/Equalizer.h` + +## 签名 ```cpp float GetBandQ(uint32 band) const; ``` -该方法声明于 `XCEngine/Audio/Equalizer.h`，当前页面用于固定 `Equalizer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `band` - 参数语义详见头文件声明。 +执行该公开方法对应的当前实现。 -**返回：** `float` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::Equalizer object; - // 根据上下文补齐参数后调用 Equalizer::GetBandQ(...)。 - (void)object; -} -``` +- 包含条件分支，并可能提前返回。 ## 相关文档 -- [返回类总览](Equalizer.md) -- [返回模块目录](../Audio.md) +- [Equalizer](Equalizer.md) +- [SetBandQ](SetBandQ.md) diff --git a/docs/api/XCEngine/Audio/Equalizer/GetWetMix.md b/docs/api/XCEngine/Audio/Equalizer/GetWetMix.md index 9795613d..6e276849 100644 --- a/docs/api/XCEngine/Audio/Equalizer/GetWetMix.md +++ b/docs/api/XCEngine/Audio/Equalizer/GetWetMix.md @@ -1,30 +1,26 @@ # Equalizer::GetWetMix -获取相关状态或对象。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/Equalizer.h` + +## 签名 ```cpp float GetWetMix() const override; ``` -该方法声明于 `XCEngine/Audio/Equalizer.h`，当前页面用于固定 `Equalizer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_wetMix` 当前值。 -**返回：** `float` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::Equalizer object; - // 根据上下文补齐参数后调用 Equalizer::GetWetMix(...)。 - (void)object; -} -``` +- 返回 `m_wetMix` 当前值。 ## 相关文档 -- [返回类总览](Equalizer.md) -- [返回模块目录](../Audio.md) +- [Equalizer](Equalizer.md) +- [SetWetMix](SetWetMix.md) diff --git a/docs/api/XCEngine/Audio/Equalizer/IsEnabled.md b/docs/api/XCEngine/Audio/Equalizer/IsEnabled.md index db7bf901..ef0d13bf 100644 --- a/docs/api/XCEngine/Audio/Equalizer/IsEnabled.md +++ b/docs/api/XCEngine/Audio/Equalizer/IsEnabled.md @@ -1,30 +1,25 @@ # Equalizer::IsEnabled -查询当前状态。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/Equalizer.h` + +## 签名 ```cpp bool IsEnabled() const override; ``` -该方法声明于 `XCEngine/Audio/Equalizer.h`，当前页面用于固定 `Equalizer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_enabled` 当前值。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::Equalizer object; - // 根据上下文补齐参数后调用 Equalizer::IsEnabled(...)。 - (void)object; -} -``` +- 返回 `m_enabled` 当前值。 ## 相关文档 -- [返回类总览](Equalizer.md) -- [返回模块目录](../Audio.md) +- [Equalizer](Equalizer.md) diff --git a/docs/api/XCEngine/Audio/Equalizer/ProcessAudio.md b/docs/api/XCEngine/Audio/Equalizer/ProcessAudio.md index 22be17f0..07e19e8a 100644 --- a/docs/api/XCEngine/Audio/Equalizer/ProcessAudio.md +++ b/docs/api/XCEngine/Audio/Equalizer/ProcessAudio.md @@ -1,33 +1,25 @@ # Equalizer::ProcessAudio -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/Equalizer.h` + +## 签名 ```cpp void ProcessAudio(float* buffer, uint32 sampleCount, uint32 channels) override; ``` -该方法声明于 `XCEngine/Audio/Equalizer.h`，当前页面用于固定 `Equalizer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `buffer` - 参数语义详见头文件声明。 -- `sampleCount` - 参数语义详见头文件声明。 -- `channels` - 参数语义详见头文件声明。 +执行该公开方法对应的当前实现。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::Equalizer object; - // 根据上下文补齐参数后调用 Equalizer::ProcessAudio(...)。 - (void)object; -} -``` +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](Equalizer.md) -- [返回模块目录](../Audio.md) +- [Equalizer](Equalizer.md) diff --git a/docs/api/XCEngine/Audio/Equalizer/SetBandCount.md b/docs/api/XCEngine/Audio/Equalizer/SetBandCount.md index 17ae33ed..514578e1 100644 --- a/docs/api/XCEngine/Audio/Equalizer/SetBandCount.md +++ b/docs/api/XCEngine/Audio/Equalizer/SetBandCount.md @@ -1,31 +1,27 @@ # Equalizer::SetBandCount -设置相关状态或配置。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/Equalizer.h` + +## 签名 ```cpp void SetBandCount(uint32 count); ``` -该方法声明于 `XCEngine/Audio/Equalizer.h`，当前页面用于固定 `Equalizer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `count` - 参数语义详见头文件声明。 +更新 `m_bandCount`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::Equalizer object; - // 根据上下文补齐参数后调用 Equalizer::SetBandCount(...)。 - (void)object; -} -``` +- 会更新 `m_bandCount`。 +- 当前实现会调用 `resize`。 ## 相关文档 -- [返回类总览](Equalizer.md) -- [返回模块目录](../Audio.md) +- [Equalizer](Equalizer.md) +- [GetBandCount](GetBandCount.md) diff --git a/docs/api/XCEngine/Audio/Equalizer/SetBandFrequency.md b/docs/api/XCEngine/Audio/Equalizer/SetBandFrequency.md index a74c0c07..2bf90fa5 100644 --- a/docs/api/XCEngine/Audio/Equalizer/SetBandFrequency.md +++ b/docs/api/XCEngine/Audio/Equalizer/SetBandFrequency.md @@ -1,32 +1,26 @@ # Equalizer::SetBandFrequency -设置相关状态或配置。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/Equalizer.h` + +## 签名 ```cpp void SetBandFrequency(uint32 band, float frequency); ``` -该方法声明于 `XCEngine/Audio/Equalizer.h`，当前页面用于固定 `Equalizer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `band` - 参数语义详见头文件声明。 -- `frequency` - 参数语义详见头文件声明。 +执行 `max`、`min`、`ComputeCoefficients` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::Equalizer object; - // 根据上下文补齐参数后调用 Equalizer::SetBandFrequency(...)。 - (void)object; -} -``` +- 当前实现会调用 `max`、`min`、`ComputeCoefficients`。 ## 相关文档 -- [返回类总览](Equalizer.md) -- [返回模块目录](../Audio.md) +- [Equalizer](Equalizer.md) +- [GetBandFrequency](GetBandFrequency.md) diff --git a/docs/api/XCEngine/Audio/Equalizer/SetBandGain.md b/docs/api/XCEngine/Audio/Equalizer/SetBandGain.md index f4f3c81e..18ac1149 100644 --- a/docs/api/XCEngine/Audio/Equalizer/SetBandGain.md +++ b/docs/api/XCEngine/Audio/Equalizer/SetBandGain.md @@ -1,32 +1,26 @@ # Equalizer::SetBandGain -设置相关状态或配置。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/Equalizer.h` + +## 签名 ```cpp void SetBandGain(uint32 band, float gainDb); ``` -该方法声明于 `XCEngine/Audio/Equalizer.h`，当前页面用于固定 `Equalizer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `band` - 参数语义详见头文件声明。 -- `gainDb` - 参数语义详见头文件声明。 +执行 `max`、`min`、`ComputeCoefficients` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::Equalizer object; - // 根据上下文补齐参数后调用 Equalizer::SetBandGain(...)。 - (void)object; -} -``` +- 当前实现会调用 `max`、`min`、`ComputeCoefficients`。 ## 相关文档 -- [返回类总览](Equalizer.md) -- [返回模块目录](../Audio.md) +- [Equalizer](Equalizer.md) +- [GetBandGain](GetBandGain.md) diff --git a/docs/api/XCEngine/Audio/Equalizer/SetBandQ.md b/docs/api/XCEngine/Audio/Equalizer/SetBandQ.md index 681d4b8d..357f36d1 100644 --- a/docs/api/XCEngine/Audio/Equalizer/SetBandQ.md +++ b/docs/api/XCEngine/Audio/Equalizer/SetBandQ.md @@ -1,32 +1,26 @@ # Equalizer::SetBandQ -设置相关状态或配置。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/Equalizer.h` + +## 签名 ```cpp void SetBandQ(uint32 band, float q); ``` -该方法声明于 `XCEngine/Audio/Equalizer.h`，当前页面用于固定 `Equalizer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `band` - 参数语义详见头文件声明。 -- `q` - 参数语义详见头文件声明。 +执行 `max`、`min`、`ComputeCoefficients` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::Equalizer object; - // 根据上下文补齐参数后调用 Equalizer::SetBandQ(...)。 - (void)object; -} -``` +- 当前实现会调用 `max`、`min`、`ComputeCoefficients`。 ## 相关文档 -- [返回类总览](Equalizer.md) -- [返回模块目录](../Audio.md) +- [Equalizer](Equalizer.md) +- [GetBandQ](GetBandQ.md) diff --git a/docs/api/XCEngine/Audio/Equalizer/SetEnabled.md b/docs/api/XCEngine/Audio/Equalizer/SetEnabled.md index 4c311095..68ffe21c 100644 --- a/docs/api/XCEngine/Audio/Equalizer/SetEnabled.md +++ b/docs/api/XCEngine/Audio/Equalizer/SetEnabled.md @@ -1,31 +1,25 @@ # Equalizer::SetEnabled -设置相关状态或配置。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/Equalizer.h` + +## 签名 ```cpp void SetEnabled(bool enabled) override; ``` -该方法声明于 `XCEngine/Audio/Equalizer.h`，当前页面用于固定 `Equalizer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `enabled` - 参数语义详见头文件声明。 +更新 `m_enabled`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::Equalizer object; - // 根据上下文补齐参数后调用 Equalizer::SetEnabled(...)。 - (void)object; -} -``` +- 会更新 `m_enabled`。 ## 相关文档 -- [返回类总览](Equalizer.md) -- [返回模块目录](../Audio.md) +- [Equalizer](Equalizer.md) diff --git a/docs/api/XCEngine/Audio/Equalizer/SetWetMix.md b/docs/api/XCEngine/Audio/Equalizer/SetWetMix.md index 8c2aa48f..56719575 100644 --- a/docs/api/XCEngine/Audio/Equalizer/SetWetMix.md +++ b/docs/api/XCEngine/Audio/Equalizer/SetWetMix.md @@ -1,31 +1,27 @@ # Equalizer::SetWetMix -设置相关状态或配置。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/Equalizer.h` + +## 签名 ```cpp void SetWetMix(float wetMix) override; ``` -该方法声明于 `XCEngine/Audio/Equalizer.h`，当前页面用于固定 `Equalizer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `wetMix` - 参数语义详见头文件声明。 +更新 `m_wetMix`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::Equalizer object; - // 根据上下文补齐参数后调用 Equalizer::SetWetMix(...)。 - (void)object; -} -``` +- 会更新 `m_wetMix`。 +- 当前实现会调用 `max`、`min`。 ## 相关文档 -- [返回类总览](Equalizer.md) -- [返回模块目录](../Audio.md) +- [Equalizer](Equalizer.md) +- [GetWetMix](GetWetMix.md) diff --git a/docs/api/XCEngine/Audio/FFTFilter/Constructor.md b/docs/api/XCEngine/Audio/FFTFilter/Constructor.md index 120e0b84..2064cf3e 100644 --- a/docs/api/XCEngine/Audio/FFTFilter/Constructor.md +++ b/docs/api/XCEngine/Audio/FFTFilter/Constructor.md @@ -1,41 +1,26 @@ # FFTFilter::FFTFilter() -构造对象。 +**命名空间**: `XCEngine::Audio` -该方法在 `XCEngine/Audio/FFTFilter.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。 +**类型**: `method` -## 重载 1: 声明 +**头文件**: `XCEngine/Audio/FFTFilter.h` + +## 签名 ```cpp FFTFilter(); -``` - -**参数：** 无。 - -**返回：** `void` - 无返回值。 - -## 重载 2: 声明 - -```cpp explicit FFTFilter(uint32 fftSize); ``` -**参数：** -- `fftSize` - 参数语义详见头文件声明。 +## 作用 -**返回：** `void` - 无返回值。 +构造 `FFTFilter` 实例。 -**示例：** +## 当前实现 -```cpp -#include - -void Example() { - XCEngine::Audio::FFTFilter object; -} -``` +- 具体定义位于 `engine/src/Audio/FFTFilter.cpp`。 ## 相关文档 -- [返回类总览](FFTFilter.md) -- [返回模块目录](../Audio.md) +- [FFTFilter](FFTFilter.md) diff --git a/docs/api/XCEngine/Audio/FFTFilter/Destructor.md b/docs/api/XCEngine/Audio/FFTFilter/Destructor.md index 100abd9f..03494ab2 100644 --- a/docs/api/XCEngine/Audio/FFTFilter/Destructor.md +++ b/docs/api/XCEngine/Audio/FFTFilter/Destructor.md @@ -1,29 +1,27 @@ # FFTFilter::~FFTFilter() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/FFTFilter.h` + +## 签名 ```cpp ~FFTFilter() override; ``` -该方法声明于 `XCEngine/Audio/FFTFilter.h`，当前页面用于固定 `FFTFilter` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `kiss_fft_free`、`kiss_fftr_free` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::FFTFilter object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 会更新 `m_fftConfig`、`m_fftrConfig`。 +- 当前实现会调用 `kiss_fft_free`、`kiss_fftr_free`。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](FFTFilter.md) -- [返回模块目录](../Audio.md) +- [FFTFilter](FFTFilter.md) diff --git a/docs/api/XCEngine/Audio/FFTFilter/GetFFTSize.md b/docs/api/XCEngine/Audio/FFTFilter/GetFFTSize.md index 2a1d2b08..ed6fbe62 100644 --- a/docs/api/XCEngine/Audio/FFTFilter/GetFFTSize.md +++ b/docs/api/XCEngine/Audio/FFTFilter/GetFFTSize.md @@ -1,30 +1,26 @@ # FFTFilter::GetFFTSize -获取相关状态或对象。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/FFTFilter.h` + +## 签名 ```cpp uint32 GetFFTSize() const; ``` -该方法声明于 `XCEngine/Audio/FFTFilter.h`，当前页面用于固定 `FFTFilter` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_fftSize` 当前值。 -**返回：** `uint32` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::FFTFilter object; - // 根据上下文补齐参数后调用 FFTFilter::GetFFTSize(...)。 - (void)object; -} -``` +- 返回 `m_fftSize` 当前值。 ## 相关文档 -- [返回类总览](FFTFilter.md) -- [返回模块目录](../Audio.md) +- [FFTFilter](FFTFilter.md) +- [SetFFTSize](SetFFTSize.md) diff --git a/docs/api/XCEngine/Audio/FFTFilter/GetSmoothingFactor.md b/docs/api/XCEngine/Audio/FFTFilter/GetSmoothingFactor.md index e9813c99..02393054 100644 --- a/docs/api/XCEngine/Audio/FFTFilter/GetSmoothingFactor.md +++ b/docs/api/XCEngine/Audio/FFTFilter/GetSmoothingFactor.md @@ -1,30 +1,26 @@ # FFTFilter::GetSmoothingFactor -获取相关状态或对象。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/FFTFilter.h` + +## 签名 ```cpp float GetSmoothingFactor() const; ``` -该方法声明于 `XCEngine/Audio/FFTFilter.h`，当前页面用于固定 `FFTFilter` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_smoothingFactor` 当前值。 -**返回：** `float` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::FFTFilter object; - // 根据上下文补齐参数后调用 FFTFilter::GetSmoothingFactor(...)。 - (void)object; -} -``` +- 返回 `m_smoothingFactor` 当前值。 ## 相关文档 -- [返回类总览](FFTFilter.md) -- [返回模块目录](../Audio.md) +- [FFTFilter](FFTFilter.md) +- [SetSmoothingFactor](SetSmoothingFactor.md) diff --git a/docs/api/XCEngine/Audio/FFTFilter/GetSpectrumData.md b/docs/api/XCEngine/Audio/FFTFilter/GetSpectrumData.md index c5aad642..bf0ae384 100644 --- a/docs/api/XCEngine/Audio/FFTFilter/GetSpectrumData.md +++ b/docs/api/XCEngine/Audio/FFTFilter/GetSpectrumData.md @@ -1,30 +1,26 @@ # FFTFilter::GetSpectrumData -获取相关状态或对象。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/FFTFilter.h` + +## 签名 ```cpp const float* GetSpectrumData() const; ``` -该方法声明于 `XCEngine/Audio/FFTFilter.h`，当前页面用于固定 `FFTFilter` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_spectrumData`。 -**返回：** `const float*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::FFTFilter object; - // 根据上下文补齐参数后调用 FFTFilter::GetSpectrumData(...)。 - (void)object; -} -``` +- 会更新 `m_spectrumData`。 +- 当前实现会调用 `data`。 ## 相关文档 -- [返回类总览](FFTFilter.md) -- [返回模块目录](../Audio.md) +- [FFTFilter](FFTFilter.md) diff --git a/docs/api/XCEngine/Audio/FFTFilter/GetSpectrumSize.md b/docs/api/XCEngine/Audio/FFTFilter/GetSpectrumSize.md index a9b5c37b..d63f22b4 100644 --- a/docs/api/XCEngine/Audio/FFTFilter/GetSpectrumSize.md +++ b/docs/api/XCEngine/Audio/FFTFilter/GetSpectrumSize.md @@ -1,30 +1,26 @@ # FFTFilter::GetSpectrumSize -获取相关状态或对象。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/FFTFilter.h` + +## 签名 ```cpp size_t GetSpectrumSize() const; ``` -该方法声明于 `XCEngine/Audio/FFTFilter.h`，当前页面用于固定 `FFTFilter` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_spectrumData`。 -**返回：** `size_t` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::FFTFilter object; - // 根据上下文补齐参数后调用 FFTFilter::GetSpectrumSize(...)。 - (void)object; -} -``` +- 会更新 `m_spectrumData`。 +- 当前实现会调用 `size`。 ## 相关文档 -- [返回类总览](FFTFilter.md) -- [返回模块目录](../Audio.md) +- [FFTFilter](FFTFilter.md) diff --git a/docs/api/XCEngine/Audio/FFTFilter/ProcessAudio.md b/docs/api/XCEngine/Audio/FFTFilter/ProcessAudio.md index 683aa41b..54e5e813 100644 --- a/docs/api/XCEngine/Audio/FFTFilter/ProcessAudio.md +++ b/docs/api/XCEngine/Audio/FFTFilter/ProcessAudio.md @@ -1,33 +1,26 @@ # FFTFilter::ProcessAudio -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/FFTFilter.h` + +## 签名 ```cpp void ProcessAudio(float* buffer, uint32 sampleCount, uint32 channels) override; ``` -该方法声明于 `XCEngine/Audio/FFTFilter.h`，当前页面用于固定 `FFTFilter` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `buffer` - 参数语义详见头文件声明。 -- `sampleCount` - 参数语义详见头文件声明。 -- `channels` - 参数语义详见头文件声明。 +执行 `size`、`resize` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::FFTFilter object; - // 根据上下文补齐参数后调用 FFTFilter::ProcessAudio(...)。 - (void)object; -} -``` +- 当前实现会调用 `size`、`resize`、`monoBuffer`、`ComputeFFT`。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](FFTFilter.md) -- [返回模块目录](../Audio.md) +- [FFTFilter](FFTFilter.md) diff --git a/docs/api/XCEngine/Audio/FFTFilter/SetFFTSize.md b/docs/api/XCEngine/Audio/FFTFilter/SetFFTSize.md index 443217b1..d4979abc 100644 --- a/docs/api/XCEngine/Audio/FFTFilter/SetFFTSize.md +++ b/docs/api/XCEngine/Audio/FFTFilter/SetFFTSize.md @@ -1,31 +1,27 @@ # FFTFilter::SetFFTSize -设置相关状态或配置。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/FFTFilter.h` + +## 签名 ```cpp void SetFFTSize(uint32 size); ``` -该方法声明于 `XCEngine/Audio/FFTFilter.h`，当前页面用于固定 `FFTFilter` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `size` - 参数语义详见头文件声明。 +更新 `m_fftSize`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::FFTFilter object; - // 根据上下文补齐参数后调用 FFTFilter::SetFFTSize(...)。 - (void)object; -} -``` +- 会更新 `m_fftSize`。 +- 当前实现会调用 `resize`、`InitializeFFT`。 ## 相关文档 -- [返回类总览](FFTFilter.md) -- [返回模块目录](../Audio.md) +- [FFTFilter](FFTFilter.md) +- [GetFFTSize](GetFFTSize.md) diff --git a/docs/api/XCEngine/Audio/FFTFilter/SetSmoothingFactor.md b/docs/api/XCEngine/Audio/FFTFilter/SetSmoothingFactor.md index dcf69866..f9448d45 100644 --- a/docs/api/XCEngine/Audio/FFTFilter/SetSmoothingFactor.md +++ b/docs/api/XCEngine/Audio/FFTFilter/SetSmoothingFactor.md @@ -1,31 +1,27 @@ # FFTFilter::SetSmoothingFactor -设置相关状态或配置。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/FFTFilter.h` + +## 签名 ```cpp void SetSmoothingFactor(float factor); ``` -该方法声明于 `XCEngine/Audio/FFTFilter.h`，当前页面用于固定 `FFTFilter` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `factor` - 参数语义详见头文件声明。 +更新 `m_smoothingFactor`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::FFTFilter object; - // 根据上下文补齐参数后调用 FFTFilter::SetSmoothingFactor(...)。 - (void)object; -} -``` +- 会更新 `m_smoothingFactor`。 +- 当前实现会调用 `max`、`min`。 ## 相关文档 -- [返回类总览](FFTFilter.md) -- [返回模块目录](../Audio.md) +- [FFTFilter](FFTFilter.md) +- [GetSmoothingFactor](GetSmoothingFactor.md) diff --git a/docs/api/XCEngine/Audio/HRTF/Constructor.md b/docs/api/XCEngine/Audio/HRTF/Constructor.md index 7dcb47af..130cc582 100644 --- a/docs/api/XCEngine/Audio/HRTF/Constructor.md +++ b/docs/api/XCEngine/Audio/HRTF/Constructor.md @@ -1,28 +1,25 @@ # HRTF::HRTF() -构造对象。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/HRTF.h` + +## 签名 ```cpp HRTF(); ``` -该方法声明于 `XCEngine/Audio/HRTF.h`，当前页面用于固定 `HRTF` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +构造 `HRTF` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::HRTF object; -} -``` +- 具体定义位于 `engine/src/Audio/HRTF.cpp`。 ## 相关文档 -- [返回类总览](HRTF.md) -- [返回模块目录](../Audio.md) +- [HRTF](HRTF.md) diff --git a/docs/api/XCEngine/Audio/HRTF/Destructor.md b/docs/api/XCEngine/Audio/HRTF/Destructor.md index a11e7bee..05538a44 100644 --- a/docs/api/XCEngine/Audio/HRTF/Destructor.md +++ b/docs/api/XCEngine/Audio/HRTF/Destructor.md @@ -1,29 +1,25 @@ # HRTF::~HRTF() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/HRTF.h` + +## 签名 ```cpp ~HRTF(); ``` -该方法声明于 `XCEngine/Audio/HRTF.h`，当前页面用于固定 `HRTF` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +当前实现为空。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::HRTF object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 当前函数体为空。 ## 相关文档 -- [返回类总览](HRTF.md) -- [返回模块目录](../Audio.md) +- [HRTF](HRTF.md) diff --git a/docs/api/XCEngine/Audio/HRTF/GetCrossFeed.md b/docs/api/XCEngine/Audio/HRTF/GetCrossFeed.md index a4da6788..acdce315 100644 --- a/docs/api/XCEngine/Audio/HRTF/GetCrossFeed.md +++ b/docs/api/XCEngine/Audio/HRTF/GetCrossFeed.md @@ -1,30 +1,26 @@ # HRTF::GetCrossFeed -获取相关状态或对象。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/HRTF.h` + +## 签名 ```cpp float GetCrossFeed() const; ``` -该方法声明于 `XCEngine/Audio/HRTF.h`，当前页面用于固定 `HRTF` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_crossFeed` 当前值。 -**返回：** `float` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::HRTF object; - // 根据上下文补齐参数后调用 HRTF::GetCrossFeed(...)。 - (void)object; -} -``` +- 返回 `m_crossFeed` 当前值。 ## 相关文档 -- [返回类总览](HRTF.md) -- [返回模块目录](../Audio.md) +- [HRTF](HRTF.md) +- [SetCrossFeed](SetCrossFeed.md) diff --git a/docs/api/XCEngine/Audio/HRTF/GetQualityLevel.md b/docs/api/XCEngine/Audio/HRTF/GetQualityLevel.md index 4ee2d9fb..37fbdb55 100644 --- a/docs/api/XCEngine/Audio/HRTF/GetQualityLevel.md +++ b/docs/api/XCEngine/Audio/HRTF/GetQualityLevel.md @@ -1,30 +1,26 @@ # HRTF::GetQualityLevel -获取相关状态或对象。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/HRTF.h` + +## 签名 ```cpp uint32 GetQualityLevel() const; ``` -该方法声明于 `XCEngine/Audio/HRTF.h`，当前页面用于固定 `HRTF` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_qualityLevel` 当前值。 -**返回：** `uint32` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::HRTF object; - // 根据上下文补齐参数后调用 HRTF::GetQualityLevel(...)。 - (void)object; -} -``` +- 返回 `m_qualityLevel` 当前值。 ## 相关文档 -- [返回类总览](HRTF.md) -- [返回模块目录](../Audio.md) +- [HRTF](HRTF.md) +- [SetQualityLevel](SetQualityLevel.md) diff --git a/docs/api/XCEngine/Audio/HRTF/GetSpeedOfSound.md b/docs/api/XCEngine/Audio/HRTF/GetSpeedOfSound.md index 48cd7510..328bbf9c 100644 --- a/docs/api/XCEngine/Audio/HRTF/GetSpeedOfSound.md +++ b/docs/api/XCEngine/Audio/HRTF/GetSpeedOfSound.md @@ -1,30 +1,26 @@ # HRTF::GetSpeedOfSound -获取相关状态或对象。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/HRTF.h` + +## 签名 ```cpp float GetSpeedOfSound() const; ``` -该方法声明于 `XCEngine/Audio/HRTF.h`，当前页面用于固定 `HRTF` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_speedOfSound` 当前值。 -**返回：** `float` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::HRTF object; - // 根据上下文补齐参数后调用 HRTF::GetSpeedOfSound(...)。 - (void)object; -} -``` +- 返回 `m_speedOfSound` 当前值。 ## 相关文档 -- [返回类总览](HRTF.md) -- [返回模块目录](../Audio.md) +- [HRTF](HRTF.md) +- [SetSpeedOfSound](SetSpeedOfSound.md) diff --git a/docs/api/XCEngine/Audio/HRTF/IsDopplerShiftEnabled.md b/docs/api/XCEngine/Audio/HRTF/IsDopplerShiftEnabled.md index 7a5a9534..f0adeb7e 100644 --- a/docs/api/XCEngine/Audio/HRTF/IsDopplerShiftEnabled.md +++ b/docs/api/XCEngine/Audio/HRTF/IsDopplerShiftEnabled.md @@ -1,30 +1,25 @@ # HRTF::IsDopplerShiftEnabled -查询当前状态。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/HRTF.h` + +## 签名 ```cpp bool IsDopplerShiftEnabled() const; ``` -该方法声明于 `XCEngine/Audio/HRTF.h`，当前页面用于固定 `HRTF` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_dopplerEnabled` 当前值。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::HRTF object; - // 根据上下文补齐参数后调用 HRTF::IsDopplerShiftEnabled(...)。 - (void)object; -} -``` +- 返回 `m_dopplerEnabled` 当前值。 ## 相关文档 -- [返回类总览](HRTF.md) -- [返回模块目录](../Audio.md) +- [HRTF](HRTF.md) diff --git a/docs/api/XCEngine/Audio/HRTF/IsEnabled.md b/docs/api/XCEngine/Audio/HRTF/IsEnabled.md index b8ff02f1..5786f74c 100644 --- a/docs/api/XCEngine/Audio/HRTF/IsEnabled.md +++ b/docs/api/XCEngine/Audio/HRTF/IsEnabled.md @@ -1,30 +1,25 @@ # HRTF::IsEnabled -查询当前状态。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/HRTF.h` + +## 签名 ```cpp bool IsEnabled() const; ``` -该方法声明于 `XCEngine/Audio/HRTF.h`，当前页面用于固定 `HRTF` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_enabled` 当前值。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::HRTF object; - // 根据上下文补齐参数后调用 HRTF::IsEnabled(...)。 - (void)object; -} -``` +- 返回 `m_enabled` 当前值。 ## 相关文档 -- [返回类总览](HRTF.md) -- [返回模块目录](../Audio.md) +- [HRTF](HRTF.md) diff --git a/docs/api/XCEngine/Audio/HRTF/IsHRTFEnabled.md b/docs/api/XCEngine/Audio/HRTF/IsHRTFEnabled.md index d7873f79..dd44f8e3 100644 --- a/docs/api/XCEngine/Audio/HRTF/IsHRTFEnabled.md +++ b/docs/api/XCEngine/Audio/HRTF/IsHRTFEnabled.md @@ -1,30 +1,25 @@ # HRTF::IsHRTFEnabled -查询当前状态。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/HRTF.h` + +## 签名 ```cpp bool IsHRTFEnabled() const; ``` -该方法声明于 `XCEngine/Audio/HRTF.h`，当前页面用于固定 `HRTF` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_hrtfEnabled` 当前值。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::HRTF object; - // 根据上下文补齐参数后调用 HRTF::IsHRTFEnabled(...)。 - (void)object; -} -``` +- 返回 `m_hrtfEnabled` 当前值。 ## 相关文档 -- [返回类总览](HRTF.md) -- [返回模块目录](../Audio.md) +- [HRTF](HRTF.md) diff --git a/docs/api/XCEngine/Audio/HRTF/ProcessAudio.md b/docs/api/XCEngine/Audio/HRTF/ProcessAudio.md index eee2bebe..434b9a2f 100644 --- a/docs/api/XCEngine/Audio/HRTF/ProcessAudio.md +++ b/docs/api/XCEngine/Audio/HRTF/ProcessAudio.md @@ -1,36 +1,26 @@ # HRTF::ProcessAudio -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/HRTF.h` + +## 签名 ```cpp void ProcessAudio(float* buffer, uint32 sampleCount, uint32 channels, const Math::Vector3& sourcePosition, const Math::Vector3& listenerPosition, const Math::Quaternion& listenerRotation); ``` -该方法声明于 `XCEngine/Audio/HRTF.h`，当前页面用于固定 `HRTF` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `buffer` - 参数语义详见头文件声明。 -- `sampleCount` - 参数语义详见头文件声明。 -- `channels` - 参数语义详见头文件声明。 -- `sourcePosition` - 参数语义详见头文件声明。 -- `listenerPosition` - 参数语义详见头文件声明。 -- `listenerRotation` - 参数语义详见头文件声明。 +执行 `ComputeDirection`、`ComputeITD`、`ComputeILD` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::HRTF object; - // 根据上下文补齐参数后调用 HRTF::ProcessAudio(...)。 - (void)object; -} -``` +- 当前实现会调用 `ComputeDirection`、`ComputeITD`、`ComputeILD`、`ApplyHRTF`、`ApplySimplePanning`。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](HRTF.md) -- [返回模块目录](../Audio.md) +- [HRTF](HRTF.md) diff --git a/docs/api/XCEngine/Audio/HRTF/SetCrossFeed.md b/docs/api/XCEngine/Audio/HRTF/SetCrossFeed.md index 646c0da5..e5904700 100644 --- a/docs/api/XCEngine/Audio/HRTF/SetCrossFeed.md +++ b/docs/api/XCEngine/Audio/HRTF/SetCrossFeed.md @@ -1,31 +1,27 @@ # HRTF::SetCrossFeed -设置相关状态或配置。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/HRTF.h` + +## 签名 ```cpp void SetCrossFeed(float crossFeed); ``` -该方法声明于 `XCEngine/Audio/HRTF.h`，当前页面用于固定 `HRTF` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `crossFeed` - 参数语义详见头文件声明。 +更新 `m_crossFeed`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::HRTF object; - // 根据上下文补齐参数后调用 HRTF::SetCrossFeed(...)。 - (void)object; -} -``` +- 会更新 `m_crossFeed`。 +- 当前实现会调用 `max`、`min`。 ## 相关文档 -- [返回类总览](HRTF.md) -- [返回模块目录](../Audio.md) +- [HRTF](HRTF.md) +- [GetCrossFeed](GetCrossFeed.md) diff --git a/docs/api/XCEngine/Audio/HRTF/SetDopplerShiftEnabled.md b/docs/api/XCEngine/Audio/HRTF/SetDopplerShiftEnabled.md index 545f8104..b48d80f3 100644 --- a/docs/api/XCEngine/Audio/HRTF/SetDopplerShiftEnabled.md +++ b/docs/api/XCEngine/Audio/HRTF/SetDopplerShiftEnabled.md @@ -1,31 +1,25 @@ # HRTF::SetDopplerShiftEnabled -设置相关状态或配置。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/HRTF.h` + +## 签名 ```cpp void SetDopplerShiftEnabled(bool enabled); ``` -该方法声明于 `XCEngine/Audio/HRTF.h`，当前页面用于固定 `HRTF` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `enabled` - 参数语义详见头文件声明。 +更新 `m_dopplerEnabled`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::HRTF object; - // 根据上下文补齐参数后调用 HRTF::SetDopplerShiftEnabled(...)。 - (void)object; -} -``` +- 会更新 `m_dopplerEnabled`。 ## 相关文档 -- [返回类总览](HRTF.md) -- [返回模块目录](../Audio.md) +- [HRTF](HRTF.md) diff --git a/docs/api/XCEngine/Audio/HRTF/SetEnabled.md b/docs/api/XCEngine/Audio/HRTF/SetEnabled.md index d924b7ee..75a8b6dd 100644 --- a/docs/api/XCEngine/Audio/HRTF/SetEnabled.md +++ b/docs/api/XCEngine/Audio/HRTF/SetEnabled.md @@ -1,31 +1,25 @@ # HRTF::SetEnabled -设置相关状态或配置。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/HRTF.h` + +## 签名 ```cpp void SetEnabled(bool enabled); ``` -该方法声明于 `XCEngine/Audio/HRTF.h`，当前页面用于固定 `HRTF` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `enabled` - 参数语义详见头文件声明。 +更新 `m_enabled`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::HRTF object; - // 根据上下文补齐参数后调用 HRTF::SetEnabled(...)。 - (void)object; -} -``` +- 会更新 `m_enabled`。 ## 相关文档 -- [返回类总览](HRTF.md) -- [返回模块目录](../Audio.md) +- [HRTF](HRTF.md) diff --git a/docs/api/XCEngine/Audio/HRTF/SetHRTFEnabled.md b/docs/api/XCEngine/Audio/HRTF/SetHRTFEnabled.md index 872ff33d..093c6b04 100644 --- a/docs/api/XCEngine/Audio/HRTF/SetHRTFEnabled.md +++ b/docs/api/XCEngine/Audio/HRTF/SetHRTFEnabled.md @@ -1,31 +1,25 @@ # HRTF::SetHRTFEnabled -设置相关状态或配置。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/HRTF.h` + +## 签名 ```cpp void SetHRTFEnabled(bool enabled); ``` -该方法声明于 `XCEngine/Audio/HRTF.h`，当前页面用于固定 `HRTF` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `enabled` - 参数语义详见头文件声明。 +更新 `m_hrtfEnabled`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::HRTF object; - // 根据上下文补齐参数后调用 HRTF::SetHRTFEnabled(...)。 - (void)object; -} -``` +- 会更新 `m_hrtfEnabled`。 ## 相关文档 -- [返回类总览](HRTF.md) -- [返回模块目录](../Audio.md) +- [HRTF](HRTF.md) diff --git a/docs/api/XCEngine/Audio/HRTF/SetQualityLevel.md b/docs/api/XCEngine/Audio/HRTF/SetQualityLevel.md index dbe54a8e..b7ebd6f3 100644 --- a/docs/api/XCEngine/Audio/HRTF/SetQualityLevel.md +++ b/docs/api/XCEngine/Audio/HRTF/SetQualityLevel.md @@ -1,31 +1,27 @@ # HRTF::SetQualityLevel -设置相关状态或配置。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/HRTF.h` + +## 签名 ```cpp void SetQualityLevel(uint32 level); ``` -该方法声明于 `XCEngine/Audio/HRTF.h`，当前页面用于固定 `HRTF` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `level` - 参数语义详见头文件声明。 +更新 `m_qualityLevel`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::HRTF object; - // 根据上下文补齐参数后调用 HRTF::SetQualityLevel(...)。 - (void)object; -} -``` +- 会更新 `m_qualityLevel`。 +- 当前实现会调用 `max`、`min`。 ## 相关文档 -- [返回类总览](HRTF.md) -- [返回模块目录](../Audio.md) +- [HRTF](HRTF.md) +- [GetQualityLevel](GetQualityLevel.md) diff --git a/docs/api/XCEngine/Audio/HRTF/SetSpeedOfSound.md b/docs/api/XCEngine/Audio/HRTF/SetSpeedOfSound.md index 237a53e4..ce226a9c 100644 --- a/docs/api/XCEngine/Audio/HRTF/SetSpeedOfSound.md +++ b/docs/api/XCEngine/Audio/HRTF/SetSpeedOfSound.md @@ -1,31 +1,27 @@ # HRTF::SetSpeedOfSound -设置相关状态或配置。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/HRTF.h` + +## 签名 ```cpp void SetSpeedOfSound(float speed); ``` -该方法声明于 `XCEngine/Audio/HRTF.h`，当前页面用于固定 `HRTF` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `speed` - 参数语义详见头文件声明。 +更新 `m_speedOfSound`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::HRTF object; - // 根据上下文补齐参数后调用 HRTF::SetSpeedOfSound(...)。 - (void)object; -} -``` +- 会更新 `m_speedOfSound`。 +- 当前实现会调用 `max`。 ## 相关文档 -- [返回类总览](HRTF.md) -- [返回模块目录](../Audio.md) +- [HRTF](HRTF.md) +- [GetSpeedOfSound](GetSpeedOfSound.md) diff --git a/docs/api/XCEngine/Audio/IAudioBackend/Destructor.md b/docs/api/XCEngine/Audio/IAudioBackend/Destructor.md index a9508980..2b1d2471 100644 --- a/docs/api/XCEngine/Audio/IAudioBackend/Destructor.md +++ b/docs/api/XCEngine/Audio/IAudioBackend/Destructor.md @@ -1,29 +1,25 @@ # IAudioBackend::~IAudioBackend() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/IAudioBackend.h` + +## 签名 ```cpp virtual ~IAudioBackend() = default; ``` -该方法声明于 `XCEngine/Audio/IAudioBackend.h`，当前页面用于固定 `IAudioBackend` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +销毁 `IAudioBackend` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::IAudioBackend object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 当前为默认析构实现。 ## 相关文档 -- [返回类总览](IAudioBackend.md) -- [返回模块目录](../Audio.md) +- [IAudioBackend](IAudioBackend.md) diff --git a/docs/api/XCEngine/Audio/IAudioBackend/GetAvailableDevices.md b/docs/api/XCEngine/Audio/IAudioBackend/GetAvailableDevices.md index 4ab712e8..7ab6b32c 100644 --- a/docs/api/XCEngine/Audio/IAudioBackend/GetAvailableDevices.md +++ b/docs/api/XCEngine/Audio/IAudioBackend/GetAvailableDevices.md @@ -1,31 +1,25 @@ # IAudioBackend::GetAvailableDevices -获取相关状态或对象。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/IAudioBackend.h` + +## 签名 ```cpp virtual void GetAvailableDevices(std::vector& devices) = 0; ``` -该方法声明于 `XCEngine/Audio/IAudioBackend.h`，当前页面用于固定 `IAudioBackend` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `devices` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::IAudioBackend object; - // 根据上下文补齐参数后调用 IAudioBackend::GetAvailableDevices(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](IAudioBackend.md) -- [返回模块目录](../Audio.md) +- [IAudioBackend](IAudioBackend.md) diff --git a/docs/api/XCEngine/Audio/IAudioBackend/GetConfig.md b/docs/api/XCEngine/Audio/IAudioBackend/GetConfig.md index b1531dd2..8bebc3be 100644 --- a/docs/api/XCEngine/Audio/IAudioBackend/GetConfig.md +++ b/docs/api/XCEngine/Audio/IAudioBackend/GetConfig.md @@ -1,30 +1,25 @@ # IAudioBackend::GetConfig -获取相关状态或对象。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/IAudioBackend.h` + +## 签名 ```cpp virtual AudioConfig GetConfig() const = 0; ``` -该方法声明于 `XCEngine/Audio/IAudioBackend.h`，当前页面用于固定 `IAudioBackend` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `AudioConfig` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::IAudioBackend object; - // 根据上下文补齐参数后调用 IAudioBackend::GetConfig(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](IAudioBackend.md) -- [返回模块目录](../Audio.md) +- [IAudioBackend](IAudioBackend.md) diff --git a/docs/api/XCEngine/Audio/IAudioBackend/GetDeviceName.md b/docs/api/XCEngine/Audio/IAudioBackend/GetDeviceName.md index e0b6508b..46ab6712 100644 --- a/docs/api/XCEngine/Audio/IAudioBackend/GetDeviceName.md +++ b/docs/api/XCEngine/Audio/IAudioBackend/GetDeviceName.md @@ -1,30 +1,25 @@ # IAudioBackend::GetDeviceName -获取相关状态或对象。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/IAudioBackend.h` + +## 签名 ```cpp virtual std::string GetDeviceName() const = 0; ``` -该方法声明于 `XCEngine/Audio/IAudioBackend.h`，当前页面用于固定 `IAudioBackend` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `std::string` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::IAudioBackend object; - // 根据上下文补齐参数后调用 IAudioBackend::GetDeviceName(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](IAudioBackend.md) -- [返回模块目录](../Audio.md) +- [IAudioBackend](IAudioBackend.md) diff --git a/docs/api/XCEngine/Audio/IAudioBackend/GetMasterVolume.md b/docs/api/XCEngine/Audio/IAudioBackend/GetMasterVolume.md index dcd8aab7..691872f1 100644 --- a/docs/api/XCEngine/Audio/IAudioBackend/GetMasterVolume.md +++ b/docs/api/XCEngine/Audio/IAudioBackend/GetMasterVolume.md @@ -1,30 +1,26 @@ # IAudioBackend::GetMasterVolume -获取相关状态或对象。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/IAudioBackend.h` + +## 签名 ```cpp virtual float GetMasterVolume() const = 0; ``` -该方法声明于 `XCEngine/Audio/IAudioBackend.h`，当前页面用于固定 `IAudioBackend` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `float` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::IAudioBackend object; - // 根据上下文补齐参数后调用 IAudioBackend::GetMasterVolume(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](IAudioBackend.md) -- [返回模块目录](../Audio.md) +- [IAudioBackend](IAudioBackend.md) +- [SetMasterVolume](SetMasterVolume.md) diff --git a/docs/api/XCEngine/Audio/IAudioBackend/Initialize.md b/docs/api/XCEngine/Audio/IAudioBackend/Initialize.md index d478da5a..3cfbf634 100644 --- a/docs/api/XCEngine/Audio/IAudioBackend/Initialize.md +++ b/docs/api/XCEngine/Audio/IAudioBackend/Initialize.md @@ -1,31 +1,25 @@ # IAudioBackend::Initialize -初始化内部状态。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/IAudioBackend.h` + +## 签名 ```cpp virtual bool Initialize(const AudioConfig& config) = 0; ``` -该方法声明于 `XCEngine/Audio/IAudioBackend.h`，当前页面用于固定 `IAudioBackend` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `config` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::IAudioBackend object; - // 根据上下文补齐参数后调用 IAudioBackend::Initialize(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](IAudioBackend.md) -- [返回模块目录](../Audio.md) +- [IAudioBackend](IAudioBackend.md) diff --git a/docs/api/XCEngine/Audio/IAudioBackend/IsMuted.md b/docs/api/XCEngine/Audio/IAudioBackend/IsMuted.md index 29faf0ec..5ff6a27d 100644 --- a/docs/api/XCEngine/Audio/IAudioBackend/IsMuted.md +++ b/docs/api/XCEngine/Audio/IAudioBackend/IsMuted.md @@ -1,30 +1,25 @@ # IAudioBackend::IsMuted -查询当前状态。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/IAudioBackend.h` + +## 签名 ```cpp virtual bool IsMuted() const = 0; ``` -该方法声明于 `XCEngine/Audio/IAudioBackend.h`，当前页面用于固定 `IAudioBackend` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::IAudioBackend object; - // 根据上下文补齐参数后调用 IAudioBackend::IsMuted(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](IAudioBackend.md) -- [返回模块目录](../Audio.md) +- [IAudioBackend](IAudioBackend.md) diff --git a/docs/api/XCEngine/Audio/IAudioBackend/IsRunning.md b/docs/api/XCEngine/Audio/IAudioBackend/IsRunning.md index cfb9b15e..293017dc 100644 --- a/docs/api/XCEngine/Audio/IAudioBackend/IsRunning.md +++ b/docs/api/XCEngine/Audio/IAudioBackend/IsRunning.md @@ -1,30 +1,25 @@ # IAudioBackend::IsRunning -查询当前状态。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/IAudioBackend.h` + +## 签名 ```cpp virtual bool IsRunning() const = 0; ``` -该方法声明于 `XCEngine/Audio/IAudioBackend.h`，当前页面用于固定 `IAudioBackend` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::IAudioBackend object; - // 根据上下文补齐参数后调用 IAudioBackend::IsRunning(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](IAudioBackend.md) -- [返回模块目录](../Audio.md) +- [IAudioBackend](IAudioBackend.md) diff --git a/docs/api/XCEngine/Audio/IAudioBackend/ProcessAudio.md b/docs/api/XCEngine/Audio/IAudioBackend/ProcessAudio.md index 87f903fb..4454e6ff 100644 --- a/docs/api/XCEngine/Audio/IAudioBackend/ProcessAudio.md +++ b/docs/api/XCEngine/Audio/IAudioBackend/ProcessAudio.md @@ -1,34 +1,25 @@ # IAudioBackend::ProcessAudio -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/IAudioBackend.h` + +## 签名 ```cpp virtual void ProcessAudio(float* buffer, uint32 bufferSize, uint32 channels, uint32 sampleRate) = 0; ``` -该方法声明于 `XCEngine/Audio/IAudioBackend.h`，当前页面用于固定 `IAudioBackend` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `buffer` - 参数语义详见头文件声明。 -- `bufferSize` - 参数语义详见头文件声明。 -- `channels` - 参数语义详见头文件声明。 -- `sampleRate` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::IAudioBackend object; - // 根据上下文补齐参数后调用 IAudioBackend::ProcessAudio(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](IAudioBackend.md) -- [返回模块目录](../Audio.md) +- [IAudioBackend](IAudioBackend.md) diff --git a/docs/api/XCEngine/Audio/IAudioBackend/Resume.md b/docs/api/XCEngine/Audio/IAudioBackend/Resume.md index 12df546b..9be1d156 100644 --- a/docs/api/XCEngine/Audio/IAudioBackend/Resume.md +++ b/docs/api/XCEngine/Audio/IAudioBackend/Resume.md @@ -1,30 +1,25 @@ # IAudioBackend::Resume -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/IAudioBackend.h` + +## 签名 ```cpp virtual void Resume() = 0; ``` -该方法声明于 `XCEngine/Audio/IAudioBackend.h`，当前页面用于固定 `IAudioBackend` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::IAudioBackend object; - // 根据上下文补齐参数后调用 IAudioBackend::Resume(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](IAudioBackend.md) -- [返回模块目录](../Audio.md) +- [IAudioBackend](IAudioBackend.md) diff --git a/docs/api/XCEngine/Audio/IAudioBackend/SetDevice.md b/docs/api/XCEngine/Audio/IAudioBackend/SetDevice.md index d66f26b5..c739be80 100644 --- a/docs/api/XCEngine/Audio/IAudioBackend/SetDevice.md +++ b/docs/api/XCEngine/Audio/IAudioBackend/SetDevice.md @@ -1,31 +1,25 @@ # IAudioBackend::SetDevice -设置相关状态或配置。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/IAudioBackend.h` + +## 签名 ```cpp virtual bool SetDevice(const std::string& deviceName) = 0; ``` -该方法声明于 `XCEngine/Audio/IAudioBackend.h`，当前页面用于固定 `IAudioBackend` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `deviceName` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::IAudioBackend object; - // 根据上下文补齐参数后调用 IAudioBackend::SetDevice(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](IAudioBackend.md) -- [返回模块目录](../Audio.md) +- [IAudioBackend](IAudioBackend.md) diff --git a/docs/api/XCEngine/Audio/IAudioBackend/SetMasterVolume.md b/docs/api/XCEngine/Audio/IAudioBackend/SetMasterVolume.md index c634dc1c..acf47ba0 100644 --- a/docs/api/XCEngine/Audio/IAudioBackend/SetMasterVolume.md +++ b/docs/api/XCEngine/Audio/IAudioBackend/SetMasterVolume.md @@ -1,31 +1,26 @@ # IAudioBackend::SetMasterVolume -设置相关状态或配置。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/IAudioBackend.h` + +## 签名 ```cpp virtual void SetMasterVolume(float volume) = 0; ``` -该方法声明于 `XCEngine/Audio/IAudioBackend.h`，当前页面用于固定 `IAudioBackend` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `volume` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::IAudioBackend object; - // 根据上下文补齐参数后调用 IAudioBackend::SetMasterVolume(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](IAudioBackend.md) -- [返回模块目录](../Audio.md) +- [IAudioBackend](IAudioBackend.md) +- [GetMasterVolume](GetMasterVolume.md) diff --git a/docs/api/XCEngine/Audio/IAudioBackend/SetMuted.md b/docs/api/XCEngine/Audio/IAudioBackend/SetMuted.md index 371b2704..826a008c 100644 --- a/docs/api/XCEngine/Audio/IAudioBackend/SetMuted.md +++ b/docs/api/XCEngine/Audio/IAudioBackend/SetMuted.md @@ -1,31 +1,25 @@ # IAudioBackend::SetMuted -设置相关状态或配置。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/IAudioBackend.h` + +## 签名 ```cpp virtual void SetMuted(bool muted) = 0; ``` -该方法声明于 `XCEngine/Audio/IAudioBackend.h`，当前页面用于固定 `IAudioBackend` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `muted` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::IAudioBackend object; - // 根据上下文补齐参数后调用 IAudioBackend::SetMuted(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](IAudioBackend.md) -- [返回模块目录](../Audio.md) +- [IAudioBackend](IAudioBackend.md) diff --git a/docs/api/XCEngine/Audio/IAudioBackend/Shutdown.md b/docs/api/XCEngine/Audio/IAudioBackend/Shutdown.md index 09350e8c..d4e6202d 100644 --- a/docs/api/XCEngine/Audio/IAudioBackend/Shutdown.md +++ b/docs/api/XCEngine/Audio/IAudioBackend/Shutdown.md @@ -1,30 +1,25 @@ # IAudioBackend::Shutdown -关闭并清理内部状态。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/IAudioBackend.h` + +## 签名 ```cpp virtual void Shutdown() = 0; ``` -该方法声明于 `XCEngine/Audio/IAudioBackend.h`，当前页面用于固定 `IAudioBackend` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::IAudioBackend object; - // 根据上下文补齐参数后调用 IAudioBackend::Shutdown(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](IAudioBackend.md) -- [返回模块目录](../Audio.md) +- [IAudioBackend](IAudioBackend.md) diff --git a/docs/api/XCEngine/Audio/IAudioBackend/Start.md b/docs/api/XCEngine/Audio/IAudioBackend/Start.md index d35b2057..be194b4b 100644 --- a/docs/api/XCEngine/Audio/IAudioBackend/Start.md +++ b/docs/api/XCEngine/Audio/IAudioBackend/Start.md @@ -1,30 +1,25 @@ # IAudioBackend::Start -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/IAudioBackend.h` + +## 签名 ```cpp virtual void Start() = 0; ``` -该方法声明于 `XCEngine/Audio/IAudioBackend.h`，当前页面用于固定 `IAudioBackend` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::IAudioBackend object; - // 根据上下文补齐参数后调用 IAudioBackend::Start(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](IAudioBackend.md) -- [返回模块目录](../Audio.md) +- [IAudioBackend](IAudioBackend.md) diff --git a/docs/api/XCEngine/Audio/IAudioBackend/Stop.md b/docs/api/XCEngine/Audio/IAudioBackend/Stop.md index 5db349fa..ac1ef83b 100644 --- a/docs/api/XCEngine/Audio/IAudioBackend/Stop.md +++ b/docs/api/XCEngine/Audio/IAudioBackend/Stop.md @@ -1,30 +1,25 @@ # IAudioBackend::Stop -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/IAudioBackend.h` + +## 签名 ```cpp virtual void Stop() = 0; ``` -该方法声明于 `XCEngine/Audio/IAudioBackend.h`，当前页面用于固定 `IAudioBackend` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::IAudioBackend object; - // 根据上下文补齐参数后调用 IAudioBackend::Stop(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](IAudioBackend.md) -- [返回模块目录](../Audio.md) +- [IAudioBackend](IAudioBackend.md) diff --git a/docs/api/XCEngine/Audio/IAudioBackend/Suspend.md b/docs/api/XCEngine/Audio/IAudioBackend/Suspend.md index 749fccd7..8727e44b 100644 --- a/docs/api/XCEngine/Audio/IAudioBackend/Suspend.md +++ b/docs/api/XCEngine/Audio/IAudioBackend/Suspend.md @@ -1,30 +1,25 @@ # IAudioBackend::Suspend -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/IAudioBackend.h` + +## 签名 ```cpp virtual void Suspend() = 0; ``` -该方法声明于 `XCEngine/Audio/IAudioBackend.h`，当前页面用于固定 `IAudioBackend` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::IAudioBackend object; - // 根据上下文补齐参数后调用 IAudioBackend::Suspend(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](IAudioBackend.md) -- [返回模块目录](../Audio.md) +- [IAudioBackend](IAudioBackend.md) diff --git a/docs/api/XCEngine/Audio/IAudioEffect/Destructor.md b/docs/api/XCEngine/Audio/IAudioEffect/Destructor.md index 3ab55bfe..87e9cee3 100644 --- a/docs/api/XCEngine/Audio/IAudioEffect/Destructor.md +++ b/docs/api/XCEngine/Audio/IAudioEffect/Destructor.md @@ -1,29 +1,25 @@ # IAudioEffect::~IAudioEffect() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/IAudioEffect.h` + +## 签名 ```cpp virtual ~IAudioEffect() = default; ``` -该方法声明于 `XCEngine/Audio/IAudioEffect.h`，当前页面用于固定 `IAudioEffect` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +销毁 `IAudioEffect` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::IAudioEffect object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 当前为默认析构实现。 ## 相关文档 -- [返回类总览](IAudioEffect.md) -- [返回模块目录](../Audio.md) +- [IAudioEffect](IAudioEffect.md) diff --git a/docs/api/XCEngine/Audio/IAudioEffect/GetWetMix.md b/docs/api/XCEngine/Audio/IAudioEffect/GetWetMix.md index 4b1e6a7d..40cce049 100644 --- a/docs/api/XCEngine/Audio/IAudioEffect/GetWetMix.md +++ b/docs/api/XCEngine/Audio/IAudioEffect/GetWetMix.md @@ -1,30 +1,26 @@ # IAudioEffect::GetWetMix -获取相关状态或对象。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/IAudioEffect.h` + +## 签名 ```cpp virtual float GetWetMix() const; ``` -该方法声明于 `XCEngine/Audio/IAudioEffect.h`，当前页面用于固定 `IAudioEffect` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_wetMix` 当前值。 -**返回：** `float` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::IAudioEffect object; - // 根据上下文补齐参数后调用 IAudioEffect::GetWetMix(...)。 - (void)object; -} -``` +- 返回 `m_wetMix` 当前值。 ## 相关文档 -- [返回类总览](IAudioEffect.md) -- [返回模块目录](../Audio.md) +- [IAudioEffect](IAudioEffect.md) +- [SetWetMix](SetWetMix.md) diff --git a/docs/api/XCEngine/Audio/IAudioEffect/IsEnabled.md b/docs/api/XCEngine/Audio/IAudioEffect/IsEnabled.md index 30fea140..9dfbb8a9 100644 --- a/docs/api/XCEngine/Audio/IAudioEffect/IsEnabled.md +++ b/docs/api/XCEngine/Audio/IAudioEffect/IsEnabled.md @@ -1,30 +1,25 @@ # IAudioEffect::IsEnabled -查询当前状态。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/IAudioEffect.h` + +## 签名 ```cpp virtual bool IsEnabled() const; ``` -该方法声明于 `XCEngine/Audio/IAudioEffect.h`，当前页面用于固定 `IAudioEffect` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_enabled` 当前值。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::IAudioEffect object; - // 根据上下文补齐参数后调用 IAudioEffect::IsEnabled(...)。 - (void)object; -} -``` +- 返回 `m_enabled` 当前值。 ## 相关文档 -- [返回类总览](IAudioEffect.md) -- [返回模块目录](../Audio.md) +- [IAudioEffect](IAudioEffect.md) diff --git a/docs/api/XCEngine/Audio/IAudioEffect/ProcessAudio.md b/docs/api/XCEngine/Audio/IAudioEffect/ProcessAudio.md index 4da17c28..ec00b2e4 100644 --- a/docs/api/XCEngine/Audio/IAudioEffect/ProcessAudio.md +++ b/docs/api/XCEngine/Audio/IAudioEffect/ProcessAudio.md @@ -1,33 +1,25 @@ # IAudioEffect::ProcessAudio -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/IAudioEffect.h` + +## 签名 ```cpp virtual void ProcessAudio(float* buffer, uint32 sampleCount, uint32 channels) = 0; ``` -该方法声明于 `XCEngine/Audio/IAudioEffect.h`，当前页面用于固定 `IAudioEffect` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `buffer` - 参数语义详见头文件声明。 -- `sampleCount` - 参数语义详见头文件声明。 -- `channels` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::IAudioEffect object; - // 根据上下文补齐参数后调用 IAudioEffect::ProcessAudio(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](IAudioEffect.md) -- [返回模块目录](../Audio.md) +- [IAudioEffect](IAudioEffect.md) diff --git a/docs/api/XCEngine/Audio/IAudioEffect/SetEnabled.md b/docs/api/XCEngine/Audio/IAudioEffect/SetEnabled.md index 58715330..43a079b0 100644 --- a/docs/api/XCEngine/Audio/IAudioEffect/SetEnabled.md +++ b/docs/api/XCEngine/Audio/IAudioEffect/SetEnabled.md @@ -1,31 +1,25 @@ # IAudioEffect::SetEnabled -设置相关状态或配置。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/IAudioEffect.h` + +## 签名 ```cpp virtual void SetEnabled(bool enabled); ``` -该方法声明于 `XCEngine/Audio/IAudioEffect.h`，当前页面用于固定 `IAudioEffect` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `enabled` - 参数语义详见头文件声明。 +更新 `m_enabled`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::IAudioEffect object; - // 根据上下文补齐参数后调用 IAudioEffect::SetEnabled(...)。 - (void)object; -} -``` +- 会更新 `m_enabled`。 ## 相关文档 -- [返回类总览](IAudioEffect.md) -- [返回模块目录](../Audio.md) +- [IAudioEffect](IAudioEffect.md) diff --git a/docs/api/XCEngine/Audio/IAudioEffect/SetWetMix.md b/docs/api/XCEngine/Audio/IAudioEffect/SetWetMix.md index 8b6f6759..f4d61bc1 100644 --- a/docs/api/XCEngine/Audio/IAudioEffect/SetWetMix.md +++ b/docs/api/XCEngine/Audio/IAudioEffect/SetWetMix.md @@ -1,31 +1,26 @@ # IAudioEffect::SetWetMix -设置相关状态或配置。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/IAudioEffect.h` + +## 签名 ```cpp virtual void SetWetMix(float wetMix); ``` -该方法声明于 `XCEngine/Audio/IAudioEffect.h`，当前页面用于固定 `IAudioEffect` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `wetMix` - 参数语义详见头文件声明。 +更新 `m_wetMix`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::IAudioEffect object; - // 根据上下文补齐参数后调用 IAudioEffect::SetWetMix(...)。 - (void)object; -} -``` +- 会更新 `m_wetMix`。 ## 相关文档 -- [返回类总览](IAudioEffect.md) -- [返回模块目录](../Audio.md) +- [IAudioEffect](IAudioEffect.md) +- [GetWetMix](GetWetMix.md) diff --git a/docs/api/XCEngine/Audio/Reverbation/Constructor.md b/docs/api/XCEngine/Audio/Reverbation/Constructor.md index 873417f3..8d0462f1 100644 --- a/docs/api/XCEngine/Audio/Reverbation/Constructor.md +++ b/docs/api/XCEngine/Audio/Reverbation/Constructor.md @@ -1,28 +1,25 @@ # Reverbation::Reverbation() -构造对象。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/Reverbation.h` + +## 签名 ```cpp Reverbation(); ``` -该方法声明于 `XCEngine/Audio/Reverbation.h`，当前页面用于固定 `Reverbation` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +构造 `Reverbation` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::Reverbation object; -} -``` +- 具体定义位于 `engine/src/Audio/Reverbation.cpp`。 ## 相关文档 -- [返回类总览](Reverbation.md) -- [返回模块目录](../Audio.md) +- [Reverbation](Reverbation.md) diff --git a/docs/api/XCEngine/Audio/Reverbation/Destructor.md b/docs/api/XCEngine/Audio/Reverbation/Destructor.md index 64a705d4..367e3a9b 100644 --- a/docs/api/XCEngine/Audio/Reverbation/Destructor.md +++ b/docs/api/XCEngine/Audio/Reverbation/Destructor.md @@ -1,29 +1,25 @@ # Reverbation::~Reverbation() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/Reverbation.h` + +## 签名 ```cpp ~Reverbation() override; ``` -该方法声明于 `XCEngine/Audio/Reverbation.h`，当前页面用于固定 `Reverbation` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +当前实现为空。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::Reverbation object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 当前函数体为空。 ## 相关文档 -- [返回类总览](Reverbation.md) -- [返回模块目录](../Audio.md) +- [Reverbation](Reverbation.md) diff --git a/docs/api/XCEngine/Audio/Reverbation/GetDamping.md b/docs/api/XCEngine/Audio/Reverbation/GetDamping.md index 8223497a..69cd306f 100644 --- a/docs/api/XCEngine/Audio/Reverbation/GetDamping.md +++ b/docs/api/XCEngine/Audio/Reverbation/GetDamping.md @@ -1,30 +1,26 @@ # Reverbation::GetDamping -获取相关状态或对象。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/Reverbation.h` + +## 签名 ```cpp float GetDamping() const; ``` -该方法声明于 `XCEngine/Audio/Reverbation.h`，当前页面用于固定 `Reverbation` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_damping` 当前值。 -**返回：** `float` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::Reverbation object; - // 根据上下文补齐参数后调用 Reverbation::GetDamping(...)。 - (void)object; -} -``` +- 返回 `m_damping` 当前值。 ## 相关文档 -- [返回类总览](Reverbation.md) -- [返回模块目录](../Audio.md) +- [Reverbation](Reverbation.md) +- [SetDamping](SetDamping.md) diff --git a/docs/api/XCEngine/Audio/Reverbation/GetDryMix.md b/docs/api/XCEngine/Audio/Reverbation/GetDryMix.md index 809b585e..5f0e34bc 100644 --- a/docs/api/XCEngine/Audio/Reverbation/GetDryMix.md +++ b/docs/api/XCEngine/Audio/Reverbation/GetDryMix.md @@ -1,30 +1,26 @@ # Reverbation::GetDryMix -获取相关状态或对象。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/Reverbation.h` + +## 签名 ```cpp float GetDryMix() const; ``` -该方法声明于 `XCEngine/Audio/Reverbation.h`，当前页面用于固定 `Reverbation` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_dryMix` 当前值。 -**返回：** `float` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::Reverbation object; - // 根据上下文补齐参数后调用 Reverbation::GetDryMix(...)。 - (void)object; -} -``` +- 返回 `m_dryMix` 当前值。 ## 相关文档 -- [返回类总览](Reverbation.md) -- [返回模块目录](../Audio.md) +- [Reverbation](Reverbation.md) +- [SetDryMix](SetDryMix.md) diff --git a/docs/api/XCEngine/Audio/Reverbation/GetRoomSize.md b/docs/api/XCEngine/Audio/Reverbation/GetRoomSize.md index 822f902e..15a7f929 100644 --- a/docs/api/XCEngine/Audio/Reverbation/GetRoomSize.md +++ b/docs/api/XCEngine/Audio/Reverbation/GetRoomSize.md @@ -1,30 +1,26 @@ # Reverbation::GetRoomSize -获取相关状态或对象。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/Reverbation.h` + +## 签名 ```cpp float GetRoomSize() const; ``` -该方法声明于 `XCEngine/Audio/Reverbation.h`，当前页面用于固定 `Reverbation` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_roomSize` 当前值。 -**返回：** `float` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::Reverbation object; - // 根据上下文补齐参数后调用 Reverbation::GetRoomSize(...)。 - (void)object; -} -``` +- 返回 `m_roomSize` 当前值。 ## 相关文档 -- [返回类总览](Reverbation.md) -- [返回模块目录](../Audio.md) +- [Reverbation](Reverbation.md) +- [SetRoomSize](SetRoomSize.md) diff --git a/docs/api/XCEngine/Audio/Reverbation/GetWetMix.md b/docs/api/XCEngine/Audio/Reverbation/GetWetMix.md index 98ca33e0..68528f22 100644 --- a/docs/api/XCEngine/Audio/Reverbation/GetWetMix.md +++ b/docs/api/XCEngine/Audio/Reverbation/GetWetMix.md @@ -1,30 +1,26 @@ # Reverbation::GetWetMix -获取相关状态或对象。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/Reverbation.h` + +## 签名 ```cpp float GetWetMix() const override; ``` -该方法声明于 `XCEngine/Audio/Reverbation.h`，当前页面用于固定 `Reverbation` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_wetMix` 当前值。 -**返回：** `float` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::Reverbation object; - // 根据上下文补齐参数后调用 Reverbation::GetWetMix(...)。 - (void)object; -} -``` +- 返回 `m_wetMix` 当前值。 ## 相关文档 -- [返回类总览](Reverbation.md) -- [返回模块目录](../Audio.md) +- [Reverbation](Reverbation.md) +- [SetWetMix](SetWetMix.md) diff --git a/docs/api/XCEngine/Audio/Reverbation/GetWidth.md b/docs/api/XCEngine/Audio/Reverbation/GetWidth.md index e2e6fac7..52fec240 100644 --- a/docs/api/XCEngine/Audio/Reverbation/GetWidth.md +++ b/docs/api/XCEngine/Audio/Reverbation/GetWidth.md @@ -1,30 +1,26 @@ # Reverbation::GetWidth -获取相关状态或对象。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/Reverbation.h` + +## 签名 ```cpp float GetWidth() const; ``` -该方法声明于 `XCEngine/Audio/Reverbation.h`，当前页面用于固定 `Reverbation` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_width` 当前值。 -**返回：** `float` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::Reverbation object; - // 根据上下文补齐参数后调用 Reverbation::GetWidth(...)。 - (void)object; -} -``` +- 返回 `m_width` 当前值。 ## 相关文档 -- [返回类总览](Reverbation.md) -- [返回模块目录](../Audio.md) +- [Reverbation](Reverbation.md) +- [SetWidth](SetWidth.md) diff --git a/docs/api/XCEngine/Audio/Reverbation/IsFreeze.md b/docs/api/XCEngine/Audio/Reverbation/IsFreeze.md index e3e78a1f..b48e1e98 100644 --- a/docs/api/XCEngine/Audio/Reverbation/IsFreeze.md +++ b/docs/api/XCEngine/Audio/Reverbation/IsFreeze.md @@ -1,30 +1,25 @@ # Reverbation::IsFreeze -查询当前状态。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/Reverbation.h` + +## 签名 ```cpp bool IsFreeze() const; ``` -该方法声明于 `XCEngine/Audio/Reverbation.h`，当前页面用于固定 `Reverbation` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_freeze` 当前值。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::Reverbation object; - // 根据上下文补齐参数后调用 Reverbation::IsFreeze(...)。 - (void)object; -} -``` +- 返回 `m_freeze` 当前值。 ## 相关文档 -- [返回类总览](Reverbation.md) -- [返回模块目录](../Audio.md) +- [Reverbation](Reverbation.md) diff --git a/docs/api/XCEngine/Audio/Reverbation/ProcessAudio.md b/docs/api/XCEngine/Audio/Reverbation/ProcessAudio.md index 6bc281bf..32e8f0f6 100644 --- a/docs/api/XCEngine/Audio/Reverbation/ProcessAudio.md +++ b/docs/api/XCEngine/Audio/Reverbation/ProcessAudio.md @@ -1,33 +1,25 @@ # Reverbation::ProcessAudio -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/Reverbation.h` + +## 签名 ```cpp void ProcessAudio(float* buffer, uint32 sampleCount, uint32 channels) override; ``` -该方法声明于 `XCEngine/Audio/Reverbation.h`，当前页面用于固定 `Reverbation` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `buffer` - 参数语义详见头文件声明。 -- `sampleCount` - 参数语义详见头文件声明。 -- `channels` - 参数语义详见头文件声明。 +执行该公开方法对应的当前实现。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::Reverbation object; - // 根据上下文补齐参数后调用 Reverbation::ProcessAudio(...)。 - (void)object; -} -``` +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](Reverbation.md) -- [返回模块目录](../Audio.md) +- [Reverbation](Reverbation.md) diff --git a/docs/api/XCEngine/Audio/Reverbation/SetDamping.md b/docs/api/XCEngine/Audio/Reverbation/SetDamping.md index d24b4d06..7ff2feab 100644 --- a/docs/api/XCEngine/Audio/Reverbation/SetDamping.md +++ b/docs/api/XCEngine/Audio/Reverbation/SetDamping.md @@ -1,31 +1,27 @@ # Reverbation::SetDamping -设置相关状态或配置。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/Reverbation.h` + +## 签名 ```cpp void SetDamping(float damping); ``` -该方法声明于 `XCEngine/Audio/Reverbation.h`，当前页面用于固定 `Reverbation` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `damping` - 参数语义详见头文件声明。 +更新 `m_damping`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::Reverbation object; - // 根据上下文补齐参数后调用 Reverbation::SetDamping(...)。 - (void)object; -} -``` +- 会更新 `m_damping`。 +- 当前实现会调用 `max`、`min`。 ## 相关文档 -- [返回类总览](Reverbation.md) -- [返回模块目录](../Audio.md) +- [Reverbation](Reverbation.md) +- [GetDamping](GetDamping.md) diff --git a/docs/api/XCEngine/Audio/Reverbation/SetDryMix.md b/docs/api/XCEngine/Audio/Reverbation/SetDryMix.md index bd526654..0cf5e1e3 100644 --- a/docs/api/XCEngine/Audio/Reverbation/SetDryMix.md +++ b/docs/api/XCEngine/Audio/Reverbation/SetDryMix.md @@ -1,31 +1,27 @@ # Reverbation::SetDryMix -设置相关状态或配置。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/Reverbation.h` + +## 签名 ```cpp void SetDryMix(float dryMix); ``` -该方法声明于 `XCEngine/Audio/Reverbation.h`，当前页面用于固定 `Reverbation` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `dryMix` - 参数语义详见头文件声明。 +更新 `m_dryMix`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::Reverbation object; - // 根据上下文补齐参数后调用 Reverbation::SetDryMix(...)。 - (void)object; -} -``` +- 会更新 `m_dryMix`。 +- 当前实现会调用 `max`、`min`。 ## 相关文档 -- [返回类总览](Reverbation.md) -- [返回模块目录](../Audio.md) +- [Reverbation](Reverbation.md) +- [GetDryMix](GetDryMix.md) diff --git a/docs/api/XCEngine/Audio/Reverbation/SetFreeze.md b/docs/api/XCEngine/Audio/Reverbation/SetFreeze.md index ac746edf..fb7a0555 100644 --- a/docs/api/XCEngine/Audio/Reverbation/SetFreeze.md +++ b/docs/api/XCEngine/Audio/Reverbation/SetFreeze.md @@ -1,31 +1,25 @@ # Reverbation::SetFreeze -设置相关状态或配置。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/Reverbation.h` + +## 签名 ```cpp void SetFreeze(bool freeze); ``` -该方法声明于 `XCEngine/Audio/Reverbation.h`，当前页面用于固定 `Reverbation` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `freeze` - 参数语义详见头文件声明。 +更新 `m_freeze`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::Reverbation object; - // 根据上下文补齐参数后调用 Reverbation::SetFreeze(...)。 - (void)object; -} -``` +- 会更新 `m_freeze`。 ## 相关文档 -- [返回类总览](Reverbation.md) -- [返回模块目录](../Audio.md) +- [Reverbation](Reverbation.md) diff --git a/docs/api/XCEngine/Audio/Reverbation/SetRoomSize.md b/docs/api/XCEngine/Audio/Reverbation/SetRoomSize.md index 28aa6b77..aae0f27b 100644 --- a/docs/api/XCEngine/Audio/Reverbation/SetRoomSize.md +++ b/docs/api/XCEngine/Audio/Reverbation/SetRoomSize.md @@ -1,31 +1,27 @@ # Reverbation::SetRoomSize -设置相关状态或配置。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/Reverbation.h` + +## 签名 ```cpp void SetRoomSize(float size); ``` -该方法声明于 `XCEngine/Audio/Reverbation.h`，当前页面用于固定 `Reverbation` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `size` - 参数语义详见头文件声明。 +更新 `m_roomSize`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::Reverbation object; - // 根据上下文补齐参数后调用 Reverbation::SetRoomSize(...)。 - (void)object; -} -``` +- 会更新 `m_roomSize`。 +- 当前实现会调用 `max`、`min`。 ## 相关文档 -- [返回类总览](Reverbation.md) -- [返回模块目录](../Audio.md) +- [Reverbation](Reverbation.md) +- [GetRoomSize](GetRoomSize.md) diff --git a/docs/api/XCEngine/Audio/Reverbation/SetWetMix.md b/docs/api/XCEngine/Audio/Reverbation/SetWetMix.md index ffc57d90..d9179a27 100644 --- a/docs/api/XCEngine/Audio/Reverbation/SetWetMix.md +++ b/docs/api/XCEngine/Audio/Reverbation/SetWetMix.md @@ -1,31 +1,27 @@ # Reverbation::SetWetMix -设置相关状态或配置。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/Reverbation.h` + +## 签名 ```cpp void SetWetMix(float wetMix) override; ``` -该方法声明于 `XCEngine/Audio/Reverbation.h`，当前页面用于固定 `Reverbation` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `wetMix` - 参数语义详见头文件声明。 +更新 `m_wetMix`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::Reverbation object; - // 根据上下文补齐参数后调用 Reverbation::SetWetMix(...)。 - (void)object; -} -``` +- 会更新 `m_wetMix`。 +- 当前实现会调用 `max`、`min`。 ## 相关文档 -- [返回类总览](Reverbation.md) -- [返回模块目录](../Audio.md) +- [Reverbation](Reverbation.md) +- [GetWetMix](GetWetMix.md) diff --git a/docs/api/XCEngine/Audio/Reverbation/SetWidth.md b/docs/api/XCEngine/Audio/Reverbation/SetWidth.md index a74f877e..cb5eae8c 100644 --- a/docs/api/XCEngine/Audio/Reverbation/SetWidth.md +++ b/docs/api/XCEngine/Audio/Reverbation/SetWidth.md @@ -1,31 +1,27 @@ # Reverbation::SetWidth -设置相关状态或配置。 +**命名空间**: `XCEngine::Audio` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/Reverbation.h` + +## 签名 ```cpp void SetWidth(float width); ``` -该方法声明于 `XCEngine/Audio/Reverbation.h`，当前页面用于固定 `Reverbation` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `width` - 参数语义详见头文件声明。 +更新 `m_width`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::Reverbation object; - // 根据上下文补齐参数后调用 Reverbation::SetWidth(...)。 - (void)object; -} -``` +- 会更新 `m_width`。 +- 当前实现会调用 `max`、`min`。 ## 相关文档 -- [返回类总览](Reverbation.md) -- [返回模块目录](../Audio.md) +- [Reverbation](Reverbation.md) +- [GetWidth](GetWidth.md) diff --git a/docs/api/XCEngine/Audio/WindowsAudioBackend/Constructor.md b/docs/api/XCEngine/Audio/WindowsAudioBackend/Constructor.md index d4903adb..ac8c20e8 100644 --- a/docs/api/XCEngine/Audio/WindowsAudioBackend/Constructor.md +++ b/docs/api/XCEngine/Audio/WindowsAudioBackend/Constructor.md @@ -1,28 +1,25 @@ # WASAPIBackend::WASAPIBackend() -构造对象。 +**命名空间**: `XCEngine::Audio::WASAPI` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/WindowsAudioBackend.h` + +## 签名 ```cpp WASAPIBackend(); ``` -该方法声明于 `XCEngine/Audio/WindowsAudioBackend.h`，当前页面用于固定 `WASAPIBackend` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +构造 `WASAPIBackend` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::WASAPI::WASAPIBackend object; -} -``` +- 具体定义位于 `engine/src/Audio/WindowsAudioBackend.cpp`。 ## 相关文档 -- [返回类总览](WindowsAudioBackend.md) -- [返回模块目录](../Audio.md) +- [WASAPIBackend](WindowsAudioBackend.md) diff --git a/docs/api/XCEngine/Audio/WindowsAudioBackend/Destructor.md b/docs/api/XCEngine/Audio/WindowsAudioBackend/Destructor.md index e45b2c34..0fa8b5c3 100644 --- a/docs/api/XCEngine/Audio/WindowsAudioBackend/Destructor.md +++ b/docs/api/XCEngine/Audio/WindowsAudioBackend/Destructor.md @@ -1,29 +1,25 @@ # WASAPIBackend::~WASAPIBackend() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::Audio::WASAPI` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/WindowsAudioBackend.h` + +## 签名 ```cpp ~WASAPIBackend() override; ``` -该方法声明于 `XCEngine/Audio/WindowsAudioBackend.h`，当前页面用于固定 `WASAPIBackend` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `Shutdown(...)` 相关流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::WASAPI::WASAPIBackend object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 当前实现会调用 `Shutdown`。 ## 相关文档 -- [返回类总览](WindowsAudioBackend.md) -- [返回模块目录](../Audio.md) +- [WASAPIBackend](WindowsAudioBackend.md) diff --git a/docs/api/XCEngine/Audio/WindowsAudioBackend/GetAvailableDevices.md b/docs/api/XCEngine/Audio/WindowsAudioBackend/GetAvailableDevices.md index 42966523..c18a71a6 100644 --- a/docs/api/XCEngine/Audio/WindowsAudioBackend/GetAvailableDevices.md +++ b/docs/api/XCEngine/Audio/WindowsAudioBackend/GetAvailableDevices.md @@ -1,31 +1,25 @@ # WASAPIBackend::GetAvailableDevices -获取相关状态或对象。 +**命名空间**: `XCEngine::Audio::WASAPI` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/WindowsAudioBackend.h` + +## 签名 ```cpp void GetAvailableDevices(std::vector& devices) override; ``` -该方法声明于 `XCEngine/Audio/WindowsAudioBackend.h`，当前页面用于固定 `WASAPIBackend` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `devices` - 参数语义详见头文件声明。 +执行 `clear`、`push_back` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::WASAPI::WASAPIBackend object; - // 根据上下文补齐参数后调用 WASAPIBackend::GetAvailableDevices(...)。 - (void)object; -} -``` +- 当前实现会调用 `clear`、`push_back`。 ## 相关文档 -- [返回类总览](WindowsAudioBackend.md) -- [返回模块目录](../Audio.md) +- [WASAPIBackend](WindowsAudioBackend.md) diff --git a/docs/api/XCEngine/Audio/WindowsAudioBackend/GetConfig.md b/docs/api/XCEngine/Audio/WindowsAudioBackend/GetConfig.md index eb75440e..c55c6fe2 100644 --- a/docs/api/XCEngine/Audio/WindowsAudioBackend/GetConfig.md +++ b/docs/api/XCEngine/Audio/WindowsAudioBackend/GetConfig.md @@ -1,30 +1,25 @@ # WASAPIBackend::GetConfig -获取相关状态或对象。 +**命名空间**: `XCEngine::Audio::WASAPI` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/WindowsAudioBackend.h` + +## 签名 ```cpp AudioConfig GetConfig() const override; ``` -该方法声明于 `XCEngine/Audio/WindowsAudioBackend.h`，当前页面用于固定 `WASAPIBackend` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_config` 当前值。 -**返回：** `AudioConfig` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::WASAPI::WASAPIBackend object; - // 根据上下文补齐参数后调用 WASAPIBackend::GetConfig(...)。 - (void)object; -} -``` +- 返回 `m_config` 当前值。 ## 相关文档 -- [返回类总览](WindowsAudioBackend.md) -- [返回模块目录](../Audio.md) +- [WASAPIBackend](WindowsAudioBackend.md) diff --git a/docs/api/XCEngine/Audio/WindowsAudioBackend/GetDeviceName.md b/docs/api/XCEngine/Audio/WindowsAudioBackend/GetDeviceName.md index 4e30b818..578c4144 100644 --- a/docs/api/XCEngine/Audio/WindowsAudioBackend/GetDeviceName.md +++ b/docs/api/XCEngine/Audio/WindowsAudioBackend/GetDeviceName.md @@ -1,30 +1,25 @@ # WASAPIBackend::GetDeviceName -获取相关状态或对象。 +**命名空间**: `XCEngine::Audio::WASAPI` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/WindowsAudioBackend.h` + +## 签名 ```cpp std::string GetDeviceName() const override; ``` -该方法声明于 `XCEngine/Audio/WindowsAudioBackend.h`，当前页面用于固定 `WASAPIBackend` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_deviceName` 当前值。 -**返回：** `std::string` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::WASAPI::WASAPIBackend object; - // 根据上下文补齐参数后调用 WASAPIBackend::GetDeviceName(...)。 - (void)object; -} -``` +- 返回 `m_deviceName` 当前值。 ## 相关文档 -- [返回类总览](WindowsAudioBackend.md) -- [返回模块目录](../Audio.md) +- [WASAPIBackend](WindowsAudioBackend.md) diff --git a/docs/api/XCEngine/Audio/WindowsAudioBackend/GetMasterVolume.md b/docs/api/XCEngine/Audio/WindowsAudioBackend/GetMasterVolume.md index e4d54a81..bb6bec91 100644 --- a/docs/api/XCEngine/Audio/WindowsAudioBackend/GetMasterVolume.md +++ b/docs/api/XCEngine/Audio/WindowsAudioBackend/GetMasterVolume.md @@ -1,30 +1,27 @@ # WASAPIBackend::GetMasterVolume -获取相关状态或对象。 +**命名空间**: `XCEngine::Audio::WASAPI` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/WindowsAudioBackend.h` + +## 签名 ```cpp float GetMasterVolume() const override; ``` -该方法声明于 `XCEngine/Audio/WindowsAudioBackend.h`，当前页面用于固定 `WASAPIBackend` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_masterVolume`。 -**返回：** `float` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::WASAPI::WASAPIBackend object; - // 根据上下文补齐参数后调用 WASAPIBackend::GetMasterVolume(...)。 - (void)object; -} -``` +- 会更新 `m_masterVolume`。 +- 当前实现会调用 `load`。 ## 相关文档 -- [返回类总览](WindowsAudioBackend.md) -- [返回模块目录](../Audio.md) +- [WASAPIBackend](WindowsAudioBackend.md) +- [SetMasterVolume](SetMasterVolume.md) diff --git a/docs/api/XCEngine/Audio/WindowsAudioBackend/Initialize.md b/docs/api/XCEngine/Audio/WindowsAudioBackend/Initialize.md index 893a14a6..53768706 100644 --- a/docs/api/XCEngine/Audio/WindowsAudioBackend/Initialize.md +++ b/docs/api/XCEngine/Audio/WindowsAudioBackend/Initialize.md @@ -1,31 +1,27 @@ # WASAPIBackend::Initialize -初始化内部状态。 +**命名空间**: `XCEngine::Audio::WASAPI` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/WindowsAudioBackend.h` + +## 签名 ```cpp bool Initialize(const AudioConfig& config) override; ``` -该方法声明于 `XCEngine/Audio/WindowsAudioBackend.h`，当前页面用于固定 `WASAPIBackend` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `config` - 参数语义详见头文件声明。 +更新 `m_config`。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::WASAPI::WASAPIBackend object; - // 根据上下文补齐参数后调用 WASAPIBackend::Initialize(...)。 - (void)object; -} -``` +- 会更新 `m_config`。 +- 当前实现会调用 `InitDevice`、`InitBuffer`、`waveOutClose`。 +- 包含条件分支，并可能提前返回。 ## 相关文档 -- [返回类总览](WindowsAudioBackend.md) -- [返回模块目录](../Audio.md) +- [WASAPIBackend](WindowsAudioBackend.md) diff --git a/docs/api/XCEngine/Audio/WindowsAudioBackend/IsMuted.md b/docs/api/XCEngine/Audio/WindowsAudioBackend/IsMuted.md index 40abffde..dc75f19d 100644 --- a/docs/api/XCEngine/Audio/WindowsAudioBackend/IsMuted.md +++ b/docs/api/XCEngine/Audio/WindowsAudioBackend/IsMuted.md @@ -1,30 +1,26 @@ # WASAPIBackend::IsMuted -查询当前状态。 +**命名空间**: `XCEngine::Audio::WASAPI` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/WindowsAudioBackend.h` + +## 签名 ```cpp bool IsMuted() const override; ``` -该方法声明于 `XCEngine/Audio/WindowsAudioBackend.h`，当前页面用于固定 `WASAPIBackend` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_muted`。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::WASAPI::WASAPIBackend object; - // 根据上下文补齐参数后调用 WASAPIBackend::IsMuted(...)。 - (void)object; -} -``` +- 会更新 `m_muted`。 +- 当前实现会调用 `load`。 ## 相关文档 -- [返回类总览](WindowsAudioBackend.md) -- [返回模块目录](../Audio.md) +- [WASAPIBackend](WindowsAudioBackend.md) diff --git a/docs/api/XCEngine/Audio/WindowsAudioBackend/IsRunning.md b/docs/api/XCEngine/Audio/WindowsAudioBackend/IsRunning.md index 9f7cca30..47f184a5 100644 --- a/docs/api/XCEngine/Audio/WindowsAudioBackend/IsRunning.md +++ b/docs/api/XCEngine/Audio/WindowsAudioBackend/IsRunning.md @@ -1,30 +1,26 @@ # WASAPIBackend::IsRunning -查询当前状态。 +**命名空间**: `XCEngine::Audio::WASAPI` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/WindowsAudioBackend.h` + +## 签名 ```cpp bool IsRunning() const override; ``` -该方法声明于 `XCEngine/Audio/WindowsAudioBackend.h`，当前页面用于固定 `WASAPIBackend` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_isRunning`。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::WASAPI::WASAPIBackend object; - // 根据上下文补齐参数后调用 WASAPIBackend::IsRunning(...)。 - (void)object; -} -``` +- 会更新 `m_isRunning`。 +- 当前实现会调用 `load`。 ## 相关文档 -- [返回类总览](WindowsAudioBackend.md) -- [返回模块目录](../Audio.md) +- [WASAPIBackend](WindowsAudioBackend.md) diff --git a/docs/api/XCEngine/Audio/WindowsAudioBackend/ProcessAudio.md b/docs/api/XCEngine/Audio/WindowsAudioBackend/ProcessAudio.md index 5d8f28d8..7304ddac 100644 --- a/docs/api/XCEngine/Audio/WindowsAudioBackend/ProcessAudio.md +++ b/docs/api/XCEngine/Audio/WindowsAudioBackend/ProcessAudio.md @@ -1,34 +1,27 @@ # WASAPIBackend::ProcessAudio -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Audio::WASAPI` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/WindowsAudioBackend.h` + +## 签名 ```cpp void ProcessAudio(float* buffer, uint32 bufferSize, uint32 channels, uint32 sampleRate) override; ``` -该方法声明于 `XCEngine/Audio/WindowsAudioBackend.h`，当前页面用于固定 `WASAPIBackend` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `buffer` - 参数语义详见头文件声明。 -- `bufferSize` - 参数语义详见头文件声明。 -- `channels` - 参数语义详见头文件声明。 -- `sampleRate` - 参数语义详见头文件声明。 +更新 `m_dataReady`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::WASAPI::WASAPIBackend object; - // 根据上下文补齐参数后调用 WASAPIBackend::ProcessAudio(...)。 - (void)object; -} -``` +- 会更新 `m_dataReady`。 +- 当前实现会调用 `load`、`data`、`size`。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](WindowsAudioBackend.md) -- [返回模块目录](../Audio.md) +- [WASAPIBackend](WindowsAudioBackend.md) diff --git a/docs/api/XCEngine/Audio/WindowsAudioBackend/Resume.md b/docs/api/XCEngine/Audio/WindowsAudioBackend/Resume.md index 2fcd1179..05de5db4 100644 --- a/docs/api/XCEngine/Audio/WindowsAudioBackend/Resume.md +++ b/docs/api/XCEngine/Audio/WindowsAudioBackend/Resume.md @@ -1,30 +1,26 @@ # WASAPIBackend::Resume -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Audio::WASAPI` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/WindowsAudioBackend.h` + +## 签名 ```cpp void Resume() override; ``` -该方法声明于 `XCEngine/Audio/WindowsAudioBackend.h`，当前页面用于固定 `WASAPIBackend` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `waveOutRestart(...)` 相关流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::WASAPI::WASAPIBackend object; - // 根据上下文补齐参数后调用 WASAPIBackend::Resume(...)。 - (void)object; -} -``` +- 当前实现会调用 `waveOutRestart`。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](WindowsAudioBackend.md) -- [返回模块目录](../Audio.md) +- [WASAPIBackend](WindowsAudioBackend.md) diff --git a/docs/api/XCEngine/Audio/WindowsAudioBackend/SetDevice.md b/docs/api/XCEngine/Audio/WindowsAudioBackend/SetDevice.md index 6f6afed2..16298084 100644 --- a/docs/api/XCEngine/Audio/WindowsAudioBackend/SetDevice.md +++ b/docs/api/XCEngine/Audio/WindowsAudioBackend/SetDevice.md @@ -1,31 +1,27 @@ # WASAPIBackend::SetDevice -设置相关状态或配置。 +**命名空间**: `XCEngine::Audio::WASAPI` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/WindowsAudioBackend.h` + +## 签名 ```cpp bool SetDevice(const std::string& deviceName) override; ``` -该方法声明于 `XCEngine/Audio/WindowsAudioBackend.h`，当前页面用于固定 `WASAPIBackend` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `deviceName` - 参数语义详见头文件声明。 +更新 `m_deviceName`。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::WASAPI::WASAPIBackend object; - // 根据上下文补齐参数后调用 WASAPIBackend::SetDevice(...)。 - (void)object; -} -``` +- 会更新 `m_deviceName`。 +- 当前实现会调用 `waveOutGetNumDevs`、`waveOutGetDevCaps`。 +- 包含条件分支，并可能提前返回。 ## 相关文档 -- [返回类总览](WindowsAudioBackend.md) -- [返回模块目录](../Audio.md) +- [WASAPIBackend](WindowsAudioBackend.md) diff --git a/docs/api/XCEngine/Audio/WindowsAudioBackend/SetMasterVolume.md b/docs/api/XCEngine/Audio/WindowsAudioBackend/SetMasterVolume.md index 89d4a227..1f629e43 100644 --- a/docs/api/XCEngine/Audio/WindowsAudioBackend/SetMasterVolume.md +++ b/docs/api/XCEngine/Audio/WindowsAudioBackend/SetMasterVolume.md @@ -1,31 +1,27 @@ # WASAPIBackend::SetMasterVolume -设置相关状态或配置。 +**命名空间**: `XCEngine::Audio::WASAPI` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/WindowsAudioBackend.h` + +## 签名 ```cpp void SetMasterVolume(float volume) override; ``` -该方法声明于 `XCEngine/Audio/WindowsAudioBackend.h`，当前页面用于固定 `WASAPIBackend` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `volume` - 参数语义详见头文件声明。 +更新 `m_masterVolume`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::WASAPI::WASAPIBackend object; - // 根据上下文补齐参数后调用 WASAPIBackend::SetMasterVolume(...)。 - (void)object; -} -``` +- 会更新 `m_masterVolume`。 +- 当前实现会调用 `store`、`max`、`min`。 ## 相关文档 -- [返回类总览](WindowsAudioBackend.md) -- [返回模块目录](../Audio.md) +- [WASAPIBackend](WindowsAudioBackend.md) +- [GetMasterVolume](GetMasterVolume.md) diff --git a/docs/api/XCEngine/Audio/WindowsAudioBackend/SetMuted.md b/docs/api/XCEngine/Audio/WindowsAudioBackend/SetMuted.md index c48209e9..7320f826 100644 --- a/docs/api/XCEngine/Audio/WindowsAudioBackend/SetMuted.md +++ b/docs/api/XCEngine/Audio/WindowsAudioBackend/SetMuted.md @@ -1,31 +1,26 @@ # WASAPIBackend::SetMuted -设置相关状态或配置。 +**命名空间**: `XCEngine::Audio::WASAPI` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/WindowsAudioBackend.h` + +## 签名 ```cpp void SetMuted(bool muted) override; ``` -该方法声明于 `XCEngine/Audio/WindowsAudioBackend.h`，当前页面用于固定 `WASAPIBackend` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `muted` - 参数语义详见头文件声明。 +更新 `m_muted`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::WASAPI::WASAPIBackend object; - // 根据上下文补齐参数后调用 WASAPIBackend::SetMuted(...)。 - (void)object; -} -``` +- 会更新 `m_muted`。 +- 当前实现会调用 `store`。 ## 相关文档 -- [返回类总览](WindowsAudioBackend.md) -- [返回模块目录](../Audio.md) +- [WASAPIBackend](WindowsAudioBackend.md) diff --git a/docs/api/XCEngine/Audio/WindowsAudioBackend/Shutdown.md b/docs/api/XCEngine/Audio/WindowsAudioBackend/Shutdown.md index e40ce5f3..6ee0d0ee 100644 --- a/docs/api/XCEngine/Audio/WindowsAudioBackend/Shutdown.md +++ b/docs/api/XCEngine/Audio/WindowsAudioBackend/Shutdown.md @@ -1,30 +1,27 @@ # WASAPIBackend::Shutdown -关闭并清理内部状态。 +**命名空间**: `XCEngine::Audio::WASAPI` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/WindowsAudioBackend.h` + +## 签名 ```cpp void Shutdown() override; ``` -该方法声明于 `XCEngine/Audio/WindowsAudioBackend.h`，当前页面用于固定 `WASAPIBackend` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_hWaveOut`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::WASAPI::WASAPIBackend object; - // 根据上下文补齐参数后调用 WASAPIBackend::Shutdown(...)。 - (void)object; -} -``` +- 会更新 `m_hWaveOut`。 +- 当前实现会调用 `load`、`Stop`、`waveOutUnprepareHeader`、`waveOutClose`。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](WindowsAudioBackend.md) -- [返回模块目录](../Audio.md) +- [WASAPIBackend](WindowsAudioBackend.md) diff --git a/docs/api/XCEngine/Audio/WindowsAudioBackend/Start.md b/docs/api/XCEngine/Audio/WindowsAudioBackend/Start.md index 37a91daf..0772880d 100644 --- a/docs/api/XCEngine/Audio/WindowsAudioBackend/Start.md +++ b/docs/api/XCEngine/Audio/WindowsAudioBackend/Start.md @@ -1,30 +1,26 @@ # WASAPIBackend::Start -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Audio::WASAPI` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/WindowsAudioBackend.h` + +## 签名 ```cpp void Start() override; ``` -该方法声明于 `XCEngine/Audio/WindowsAudioBackend.h`，当前页面用于固定 `WASAPIBackend` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `load`、`thread` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::WASAPI::WASAPIBackend object; - // 根据上下文补齐参数后调用 WASAPIBackend::Start(...)。 - (void)object; -} -``` +- 会更新 `m_isRunning`、`m_audioThread`。 +- 当前实现会调用 `load`、`thread`。 ## 相关文档 -- [返回类总览](WindowsAudioBackend.md) -- [返回模块目录](../Audio.md) +- [WASAPIBackend](WindowsAudioBackend.md) diff --git a/docs/api/XCEngine/Audio/WindowsAudioBackend/Stop.md b/docs/api/XCEngine/Audio/WindowsAudioBackend/Stop.md index 9ad31275..e55d160b 100644 --- a/docs/api/XCEngine/Audio/WindowsAudioBackend/Stop.md +++ b/docs/api/XCEngine/Audio/WindowsAudioBackend/Stop.md @@ -1,30 +1,26 @@ # WASAPIBackend::Stop -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Audio::WASAPI` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/WindowsAudioBackend.h` + +## 签名 ```cpp void Stop() override; ``` -该方法声明于 `XCEngine/Audio/WindowsAudioBackend.h`，当前页面用于固定 `WASAPIBackend` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_isRunning`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::WASAPI::WASAPIBackend object; - // 根据上下文补齐参数后调用 WASAPIBackend::Stop(...)。 - (void)object; -} -``` +- 会更新 `m_isRunning`。 +- 当前实现会调用 `joinable`、`join`。 ## 相关文档 -- [返回类总览](WindowsAudioBackend.md) -- [返回模块目录](../Audio.md) +- [WASAPIBackend](WindowsAudioBackend.md) diff --git a/docs/api/XCEngine/Audio/WindowsAudioBackend/Suspend.md b/docs/api/XCEngine/Audio/WindowsAudioBackend/Suspend.md index e47a2a07..e116321e 100644 --- a/docs/api/XCEngine/Audio/WindowsAudioBackend/Suspend.md +++ b/docs/api/XCEngine/Audio/WindowsAudioBackend/Suspend.md @@ -1,30 +1,26 @@ # WASAPIBackend::Suspend -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Audio::WASAPI` + +**类型**: `method` + +**头文件**: `XCEngine/Audio/WindowsAudioBackend.h` + +## 签名 ```cpp void Suspend() override; ``` -该方法声明于 `XCEngine/Audio/WindowsAudioBackend.h`，当前页面用于固定 `WASAPIBackend` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `waveOutReset(...)` 相关流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Audio::WASAPI::WASAPIBackend object; - // 根据上下文补齐参数后调用 WASAPIBackend::Suspend(...)。 - (void)object; -} -``` +- 当前实现会调用 `waveOutReset`。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](WindowsAudioBackend.md) -- [返回模块目录](../Audio.md) +- [WASAPIBackend](WindowsAudioBackend.md) diff --git a/docs/api/XCEngine/Components/AudioListenerComponent/Constructor.md b/docs/api/XCEngine/Components/AudioListenerComponent/Constructor.md index dda9afb2..232483e8 100644 --- a/docs/api/XCEngine/Components/AudioListenerComponent/Constructor.md +++ b/docs/api/XCEngine/Components/AudioListenerComponent/Constructor.md @@ -1,28 +1,25 @@ # AudioListenerComponent::AudioListenerComponent() -构造对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioListenerComponent.h` + +## 签名 ```cpp AudioListenerComponent(); ``` -该方法声明于 `XCEngine/Components/AudioListenerComponent.h`，当前页面用于固定 `AudioListenerComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +当前实现为空。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioListenerComponent object; -} -``` +- 当前函数体为空。 ## 相关文档 -- [返回类总览](AudioListenerComponent.md) -- [返回模块目录](../Components.md) +- [AudioListenerComponent](AudioListenerComponent.md) diff --git a/docs/api/XCEngine/Components/AudioListenerComponent/Destructor.md b/docs/api/XCEngine/Components/AudioListenerComponent/Destructor.md index bfbd3905..8bc18f71 100644 --- a/docs/api/XCEngine/Components/AudioListenerComponent/Destructor.md +++ b/docs/api/XCEngine/Components/AudioListenerComponent/Destructor.md @@ -1,29 +1,25 @@ # AudioListenerComponent::~AudioListenerComponent() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioListenerComponent.h` + +## 签名 ```cpp ~AudioListenerComponent() override; ``` -该方法声明于 `XCEngine/Components/AudioListenerComponent.h`，当前页面用于固定 `AudioListenerComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +当前实现为空。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioListenerComponent object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 当前函数体为空。 ## 相关文档 -- [返回类总览](AudioListenerComponent.md) -- [返回模块目录](../Components.md) +- [AudioListenerComponent](AudioListenerComponent.md) diff --git a/docs/api/XCEngine/Components/AudioListenerComponent/GetDopplerLevel.md b/docs/api/XCEngine/Components/AudioListenerComponent/GetDopplerLevel.md index 46edcc07..6b70f35e 100644 --- a/docs/api/XCEngine/Components/AudioListenerComponent/GetDopplerLevel.md +++ b/docs/api/XCEngine/Components/AudioListenerComponent/GetDopplerLevel.md @@ -1,30 +1,26 @@ # AudioListenerComponent::GetDopplerLevel -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioListenerComponent.h` + +## 签名 ```cpp float GetDopplerLevel() const; ``` -该方法声明于 `XCEngine/Components/AudioListenerComponent.h`，当前页面用于固定 `AudioListenerComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_dopplerLevel` 当前值。 -**返回：** `float` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioListenerComponent object; - // 根据上下文补齐参数后调用 AudioListenerComponent::GetDopplerLevel(...)。 - (void)object; -} -``` +- 返回 `m_dopplerLevel` 当前值。 ## 相关文档 -- [返回类总览](AudioListenerComponent.md) -- [返回模块目录](../Components.md) +- [AudioListenerComponent](AudioListenerComponent.md) +- [SetDopplerLevel](SetDopplerLevel.md) diff --git a/docs/api/XCEngine/Components/AudioListenerComponent/GetEnergy.md b/docs/api/XCEngine/Components/AudioListenerComponent/GetEnergy.md index 94f612ea..e507a846 100644 --- a/docs/api/XCEngine/Components/AudioListenerComponent/GetEnergy.md +++ b/docs/api/XCEngine/Components/AudioListenerComponent/GetEnergy.md @@ -1,30 +1,25 @@ # AudioListenerComponent::GetEnergy -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioListenerComponent.h` + +## 签名 ```cpp float GetEnergy() const; ``` -该方法声明于 `XCEngine/Components/AudioListenerComponent.h`，当前页面用于固定 `AudioListenerComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_energy` 当前值。 -**返回：** `float` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioListenerComponent object; - // 根据上下文补齐参数后调用 AudioListenerComponent::GetEnergy(...)。 - (void)object; -} -``` +- 返回 `m_energy` 当前值。 ## 相关文档 -- [返回类总览](AudioListenerComponent.md) -- [返回模块目录](../Components.md) +- [AudioListenerComponent](AudioListenerComponent.md) diff --git a/docs/api/XCEngine/Components/AudioListenerComponent/GetFrequencyData.md b/docs/api/XCEngine/Components/AudioListenerComponent/GetFrequencyData.md index 631a0b9d..8e5426e9 100644 --- a/docs/api/XCEngine/Components/AudioListenerComponent/GetFrequencyData.md +++ b/docs/api/XCEngine/Components/AudioListenerComponent/GetFrequencyData.md @@ -1,30 +1,26 @@ # AudioListenerComponent::GetFrequencyData -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioListenerComponent.h` + +## 签名 ```cpp const float* GetFrequencyData() const; ``` -该方法声明于 `XCEngine/Components/AudioListenerComponent.h`，当前页面用于固定 `AudioListenerComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_frequencyData`。 -**返回：** `const float*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioListenerComponent object; - // 根据上下文补齐参数后调用 AudioListenerComponent::GetFrequencyData(...)。 - (void)object; -} -``` +- 会更新 `m_frequencyData`。 +- 当前实现会调用 `data`。 ## 相关文档 -- [返回类总览](AudioListenerComponent.md) -- [返回模块目录](../Components.md) +- [AudioListenerComponent](AudioListenerComponent.md) diff --git a/docs/api/XCEngine/Components/AudioListenerComponent/GetFrequencyDataSize.md b/docs/api/XCEngine/Components/AudioListenerComponent/GetFrequencyDataSize.md index 62dc555a..f3a1637c 100644 --- a/docs/api/XCEngine/Components/AudioListenerComponent/GetFrequencyDataSize.md +++ b/docs/api/XCEngine/Components/AudioListenerComponent/GetFrequencyDataSize.md @@ -1,30 +1,26 @@ # AudioListenerComponent::GetFrequencyDataSize -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioListenerComponent.h` + +## 签名 ```cpp size_t GetFrequencyDataSize() const; ``` -该方法声明于 `XCEngine/Components/AudioListenerComponent.h`，当前页面用于固定 `AudioListenerComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_frequencyData`。 -**返回：** `size_t` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioListenerComponent object; - // 根据上下文补齐参数后调用 AudioListenerComponent::GetFrequencyDataSize(...)。 - (void)object; -} -``` +- 会更新 `m_frequencyData`。 +- 当前实现会调用 `size`。 ## 相关文档 -- [返回类总览](AudioListenerComponent.md) -- [返回模块目录](../Components.md) +- [AudioListenerComponent](AudioListenerComponent.md) diff --git a/docs/api/XCEngine/Components/AudioListenerComponent/GetMasterVolume.md b/docs/api/XCEngine/Components/AudioListenerComponent/GetMasterVolume.md index 46a7ee58..76554c0d 100644 --- a/docs/api/XCEngine/Components/AudioListenerComponent/GetMasterVolume.md +++ b/docs/api/XCEngine/Components/AudioListenerComponent/GetMasterVolume.md @@ -1,30 +1,26 @@ # AudioListenerComponent::GetMasterVolume -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioListenerComponent.h` + +## 签名 ```cpp float GetMasterVolume() const; ``` -该方法声明于 `XCEngine/Components/AudioListenerComponent.h`，当前页面用于固定 `AudioListenerComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_masterVolume` 当前值。 -**返回：** `float` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioListenerComponent object; - // 根据上下文补齐参数后调用 AudioListenerComponent::GetMasterVolume(...)。 - (void)object; -} -``` +- 返回 `m_masterVolume` 当前值。 ## 相关文档 -- [返回类总览](AudioListenerComponent.md) -- [返回模块目录](../Components.md) +- [AudioListenerComponent](AudioListenerComponent.md) +- [SetMasterVolume](SetMasterVolume.md) diff --git a/docs/api/XCEngine/Components/AudioListenerComponent/GetName.md b/docs/api/XCEngine/Components/AudioListenerComponent/GetName.md index e34d45b1..b0415bd0 100644 --- a/docs/api/XCEngine/Components/AudioListenerComponent/GetName.md +++ b/docs/api/XCEngine/Components/AudioListenerComponent/GetName.md @@ -1,30 +1,25 @@ # AudioListenerComponent::GetName -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioListenerComponent.h` + +## 签名 ```cpp std::string GetName() const override; ``` -该方法声明于 `XCEngine/Components/AudioListenerComponent.h`，当前页面用于固定 `AudioListenerComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `"AudioListener"`。 -**返回：** `std::string` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioListenerComponent object; - // 根据上下文补齐参数后调用 AudioListenerComponent::GetName(...)。 - (void)object; -} -``` +- 返回 `"AudioListener"`。 ## 相关文档 -- [返回类总览](AudioListenerComponent.md) -- [返回模块目录](../Components.md) +- [AudioListenerComponent](AudioListenerComponent.md) diff --git a/docs/api/XCEngine/Components/AudioListenerComponent/GetReverb.md b/docs/api/XCEngine/Components/AudioListenerComponent/GetReverb.md index 1a159f4e..6e187b62 100644 --- a/docs/api/XCEngine/Components/AudioListenerComponent/GetReverb.md +++ b/docs/api/XCEngine/Components/AudioListenerComponent/GetReverb.md @@ -1,30 +1,26 @@ # AudioListenerComponent::GetReverb -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioListenerComponent.h` + +## 签名 ```cpp Audio::AudioMixer* GetReverb() const; ``` -该方法声明于 `XCEngine/Components/AudioListenerComponent.h`，当前页面用于固定 `AudioListenerComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_reverb` 当前值。 -**返回：** `Audio::AudioMixer*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioListenerComponent object; - // 根据上下文补齐参数后调用 AudioListenerComponent::GetReverb(...)。 - (void)object; -} -``` +- 返回 `m_reverb` 当前值。 ## 相关文档 -- [返回类总览](AudioListenerComponent.md) -- [返回模块目录](../Components.md) +- [AudioListenerComponent](AudioListenerComponent.md) +- [SetReverb](SetReverb.md) diff --git a/docs/api/XCEngine/Components/AudioListenerComponent/GetReverbLevel.md b/docs/api/XCEngine/Components/AudioListenerComponent/GetReverbLevel.md index 271962b2..d0720395 100644 --- a/docs/api/XCEngine/Components/AudioListenerComponent/GetReverbLevel.md +++ b/docs/api/XCEngine/Components/AudioListenerComponent/GetReverbLevel.md @@ -1,30 +1,26 @@ # AudioListenerComponent::GetReverbLevel -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioListenerComponent.h` + +## 签名 ```cpp float GetReverbLevel() const; ``` -该方法声明于 `XCEngine/Components/AudioListenerComponent.h`，当前页面用于固定 `AudioListenerComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_reverbLevel` 当前值。 -**返回：** `float` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioListenerComponent object; - // 根据上下文补齐参数后调用 AudioListenerComponent::GetReverbLevel(...)。 - (void)object; -} -``` +- 返回 `m_reverbLevel` 当前值。 ## 相关文档 -- [返回类总览](AudioListenerComponent.md) -- [返回模块目录](../Components.md) +- [AudioListenerComponent](AudioListenerComponent.md) +- [SetReverbLevel](SetReverbLevel.md) diff --git a/docs/api/XCEngine/Components/AudioListenerComponent/GetSpeedOfSound.md b/docs/api/XCEngine/Components/AudioListenerComponent/GetSpeedOfSound.md index a851dd5c..13a5435e 100644 --- a/docs/api/XCEngine/Components/AudioListenerComponent/GetSpeedOfSound.md +++ b/docs/api/XCEngine/Components/AudioListenerComponent/GetSpeedOfSound.md @@ -1,30 +1,26 @@ # AudioListenerComponent::GetSpeedOfSound -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioListenerComponent.h` + +## 签名 ```cpp float GetSpeedOfSound() const; ``` -该方法声明于 `XCEngine/Components/AudioListenerComponent.h`，当前页面用于固定 `AudioListenerComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_speedOfSound` 当前值。 -**返回：** `float` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioListenerComponent object; - // 根据上下文补齐参数后调用 AudioListenerComponent::GetSpeedOfSound(...)。 - (void)object; -} -``` +- 返回 `m_speedOfSound` 当前值。 ## 相关文档 -- [返回类总览](AudioListenerComponent.md) -- [返回模块目录](../Components.md) +- [AudioListenerComponent](AudioListenerComponent.md) +- [SetSpeedOfSound](SetSpeedOfSound.md) diff --git a/docs/api/XCEngine/Components/AudioListenerComponent/IsMute.md b/docs/api/XCEngine/Components/AudioListenerComponent/IsMute.md index 43f9071a..7ce4a9b9 100644 --- a/docs/api/XCEngine/Components/AudioListenerComponent/IsMute.md +++ b/docs/api/XCEngine/Components/AudioListenerComponent/IsMute.md @@ -1,30 +1,25 @@ # AudioListenerComponent::IsMute -查询当前状态。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioListenerComponent.h` + +## 签名 ```cpp bool IsMute() const; ``` -该方法声明于 `XCEngine/Components/AudioListenerComponent.h`，当前页面用于固定 `AudioListenerComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_mute` 当前值。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioListenerComponent object; - // 根据上下文补齐参数后调用 AudioListenerComponent::IsMute(...)。 - (void)object; -} -``` +- 返回 `m_mute` 当前值。 ## 相关文档 -- [返回类总览](AudioListenerComponent.md) -- [返回模块目录](../Components.md) +- [AudioListenerComponent](AudioListenerComponent.md) diff --git a/docs/api/XCEngine/Components/AudioListenerComponent/SetDopplerLevel.md b/docs/api/XCEngine/Components/AudioListenerComponent/SetDopplerLevel.md index 933a39d5..d7c4eb92 100644 --- a/docs/api/XCEngine/Components/AudioListenerComponent/SetDopplerLevel.md +++ b/docs/api/XCEngine/Components/AudioListenerComponent/SetDopplerLevel.md @@ -1,31 +1,27 @@ # AudioListenerComponent::SetDopplerLevel -设置相关状态或配置。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioListenerComponent.h` + +## 签名 ```cpp void SetDopplerLevel(float level); ``` -该方法声明于 `XCEngine/Components/AudioListenerComponent.h`，当前页面用于固定 `AudioListenerComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `level` - 参数语义详见头文件声明。 +更新 `m_dopplerLevel`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioListenerComponent object; - // 根据上下文补齐参数后调用 AudioListenerComponent::SetDopplerLevel(...)。 - (void)object; -} -``` +- 会更新 `m_dopplerLevel`。 +- 当前实现会调用 `max`、`min`。 ## 相关文档 -- [返回类总览](AudioListenerComponent.md) -- [返回模块目录](../Components.md) +- [AudioListenerComponent](AudioListenerComponent.md) +- [GetDopplerLevel](GetDopplerLevel.md) diff --git a/docs/api/XCEngine/Components/AudioListenerComponent/SetMasterVolume.md b/docs/api/XCEngine/Components/AudioListenerComponent/SetMasterVolume.md index db856417..2c6e5eaa 100644 --- a/docs/api/XCEngine/Components/AudioListenerComponent/SetMasterVolume.md +++ b/docs/api/XCEngine/Components/AudioListenerComponent/SetMasterVolume.md @@ -1,31 +1,27 @@ # AudioListenerComponent::SetMasterVolume -设置相关状态或配置。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioListenerComponent.h` + +## 签名 ```cpp void SetMasterVolume(float volume); ``` -该方法声明于 `XCEngine/Components/AudioListenerComponent.h`，当前页面用于固定 `AudioListenerComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `volume` - 参数语义详见头文件声明。 +更新 `m_masterVolume`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioListenerComponent object; - // 根据上下文补齐参数后调用 AudioListenerComponent::SetMasterVolume(...)。 - (void)object; -} -``` +- 会更新 `m_masterVolume`。 +- 当前实现会调用 `max`、`min`、`SetMasterVolume`。 ## 相关文档 -- [返回类总览](AudioListenerComponent.md) -- [返回模块目录](../Components.md) +- [AudioListenerComponent](AudioListenerComponent.md) +- [GetMasterVolume](GetMasterVolume.md) diff --git a/docs/api/XCEngine/Components/AudioListenerComponent/SetMute.md b/docs/api/XCEngine/Components/AudioListenerComponent/SetMute.md index d831104e..202714db 100644 --- a/docs/api/XCEngine/Components/AudioListenerComponent/SetMute.md +++ b/docs/api/XCEngine/Components/AudioListenerComponent/SetMute.md @@ -1,31 +1,26 @@ # AudioListenerComponent::SetMute -设置相关状态或配置。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioListenerComponent.h` + +## 签名 ```cpp void SetMute(bool mute); ``` -该方法声明于 `XCEngine/Components/AudioListenerComponent.h`，当前页面用于固定 `AudioListenerComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `mute` - 参数语义详见头文件声明。 +更新 `m_mute`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioListenerComponent object; - // 根据上下文补齐参数后调用 AudioListenerComponent::SetMute(...)。 - (void)object; -} -``` +- 会更新 `m_mute`。 +- 当前实现会调用 `SetMuted`。 ## 相关文档 -- [返回类总览](AudioListenerComponent.md) -- [返回模块目录](../Components.md) +- [AudioListenerComponent](AudioListenerComponent.md) diff --git a/docs/api/XCEngine/Components/AudioListenerComponent/SetReverb.md b/docs/api/XCEngine/Components/AudioListenerComponent/SetReverb.md index b6664260..5498c15a 100644 --- a/docs/api/XCEngine/Components/AudioListenerComponent/SetReverb.md +++ b/docs/api/XCEngine/Components/AudioListenerComponent/SetReverb.md @@ -1,31 +1,26 @@ # AudioListenerComponent::SetReverb -设置相关状态或配置。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioListenerComponent.h` + +## 签名 ```cpp void SetReverb(Audio::AudioMixer* reverb); ``` -该方法声明于 `XCEngine/Components/AudioListenerComponent.h`，当前页面用于固定 `AudioListenerComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `reverb` - 参数语义详见头文件声明。 +更新 `m_reverb`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioListenerComponent object; - // 根据上下文补齐参数后调用 AudioListenerComponent::SetReverb(...)。 - (void)object; -} -``` +- 会更新 `m_reverb`。 ## 相关文档 -- [返回类总览](AudioListenerComponent.md) -- [返回模块目录](../Components.md) +- [AudioListenerComponent](AudioListenerComponent.md) +- [GetReverb](GetReverb.md) diff --git a/docs/api/XCEngine/Components/AudioListenerComponent/SetReverbLevel.md b/docs/api/XCEngine/Components/AudioListenerComponent/SetReverbLevel.md index df573dc7..893c919a 100644 --- a/docs/api/XCEngine/Components/AudioListenerComponent/SetReverbLevel.md +++ b/docs/api/XCEngine/Components/AudioListenerComponent/SetReverbLevel.md @@ -1,31 +1,27 @@ # AudioListenerComponent::SetReverbLevel -设置相关状态或配置。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioListenerComponent.h` + +## 签名 ```cpp void SetReverbLevel(float level); ``` -该方法声明于 `XCEngine/Components/AudioListenerComponent.h`，当前页面用于固定 `AudioListenerComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `level` - 参数语义详见头文件声明。 +更新 `m_reverbLevel`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioListenerComponent object; - // 根据上下文补齐参数后调用 AudioListenerComponent::SetReverbLevel(...)。 - (void)object; -} -``` +- 会更新 `m_reverbLevel`。 +- 当前实现会调用 `max`、`min`。 ## 相关文档 -- [返回类总览](AudioListenerComponent.md) -- [返回模块目录](../Components.md) +- [AudioListenerComponent](AudioListenerComponent.md) +- [GetReverbLevel](GetReverbLevel.md) diff --git a/docs/api/XCEngine/Components/AudioListenerComponent/SetSpeedOfSound.md b/docs/api/XCEngine/Components/AudioListenerComponent/SetSpeedOfSound.md index ea294e4c..e123889a 100644 --- a/docs/api/XCEngine/Components/AudioListenerComponent/SetSpeedOfSound.md +++ b/docs/api/XCEngine/Components/AudioListenerComponent/SetSpeedOfSound.md @@ -1,31 +1,27 @@ # AudioListenerComponent::SetSpeedOfSound -设置相关状态或配置。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioListenerComponent.h` + +## 签名 ```cpp void SetSpeedOfSound(float metersPerSecond); ``` -该方法声明于 `XCEngine/Components/AudioListenerComponent.h`，当前页面用于固定 `AudioListenerComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `metersPerSecond` - 参数语义详见头文件声明。 +更新 `m_speedOfSound`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioListenerComponent object; - // 根据上下文补齐参数后调用 AudioListenerComponent::SetSpeedOfSound(...)。 - (void)object; -} -``` +- 会更新 `m_speedOfSound`。 +- 当前实现会调用 `max`。 ## 相关文档 -- [返回类总览](AudioListenerComponent.md) -- [返回模块目录](../Components.md) +- [AudioListenerComponent](AudioListenerComponent.md) +- [GetSpeedOfSound](GetSpeedOfSound.md) diff --git a/docs/api/XCEngine/Components/AudioListenerComponent/Update.md b/docs/api/XCEngine/Components/AudioListenerComponent/Update.md index c082610a..44c38aa6 100644 --- a/docs/api/XCEngine/Components/AudioListenerComponent/Update.md +++ b/docs/api/XCEngine/Components/AudioListenerComponent/Update.md @@ -1,31 +1,25 @@ # AudioListenerComponent::Update -更新运行时状态。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioListenerComponent.h` + +## 签名 ```cpp void Update(float deltaTime) override; ``` -该方法声明于 `XCEngine/Components/AudioListenerComponent.h`，当前页面用于固定 `AudioListenerComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `deltaTime` - 参数语义详见头文件声明。 +执行 `transform`、`GetPosition` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioListenerComponent object; - // 根据上下文补齐参数后调用 AudioListenerComponent::Update(...)。 - (void)object; -} -``` +- 当前实现会调用 `transform`、`GetPosition`、`GetRotation`、`SetListenerTransform`。 ## 相关文档 -- [返回类总览](AudioListenerComponent.md) -- [返回模块目录](../Components.md) +- [AudioListenerComponent](AudioListenerComponent.md) diff --git a/docs/api/XCEngine/Components/AudioSourceComponent/Constructor.md b/docs/api/XCEngine/Components/AudioSourceComponent/Constructor.md index 3405ca2e..1e044297 100644 --- a/docs/api/XCEngine/Components/AudioSourceComponent/Constructor.md +++ b/docs/api/XCEngine/Components/AudioSourceComponent/Constructor.md @@ -1,28 +1,25 @@ # AudioSourceComponent::AudioSourceComponent() -构造对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioSourceComponent.h` + +## 签名 ```cpp AudioSourceComponent(); ``` -该方法声明于 `XCEngine/Components/AudioSourceComponent.h`，当前页面用于固定 `AudioSourceComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +构造 `AudioSourceComponent` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioSourceComponent object; -} -``` +- 具体定义位于 `engine/src/Components/AudioSourceComponent.cpp`。 ## 相关文档 -- [返回类总览](AudioSourceComponent.md) -- [返回模块目录](../Components.md) +- [AudioSourceComponent](AudioSourceComponent.md) diff --git a/docs/api/XCEngine/Components/AudioSourceComponent/Destructor.md b/docs/api/XCEngine/Components/AudioSourceComponent/Destructor.md index f67339a4..ef856ef1 100644 --- a/docs/api/XCEngine/Components/AudioSourceComponent/Destructor.md +++ b/docs/api/XCEngine/Components/AudioSourceComponent/Destructor.md @@ -1,29 +1,26 @@ # AudioSourceComponent::~AudioSourceComponent() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioSourceComponent.h` + +## 签名 ```cpp ~AudioSourceComponent() override; ``` -该方法声明于 `XCEngine/Components/AudioSourceComponent.h`，当前页面用于固定 `AudioSourceComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_playState`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioSourceComponent object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 会更新 `m_playState`。 +- 当前实现会调用 `UnregisterSource`。 ## 相关文档 -- [返回类总览](AudioSourceComponent.md) -- [返回模块目录](../Components.md) +- [AudioSourceComponent](AudioSourceComponent.md) diff --git a/docs/api/XCEngine/Components/AudioSourceComponent/Get3DParams.md b/docs/api/XCEngine/Components/AudioSourceComponent/Get3DParams.md index 10278e81..94d9a9c6 100644 --- a/docs/api/XCEngine/Components/AudioSourceComponent/Get3DParams.md +++ b/docs/api/XCEngine/Components/AudioSourceComponent/Get3DParams.md @@ -1,30 +1,26 @@ # AudioSourceComponent::Get3DParams -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioSourceComponent.h` + +## 签名 ```cpp const Audio::Audio3DParams& Get3DParams() const; ``` -该方法声明于 `XCEngine/Components/AudioSourceComponent.h`，当前页面用于固定 `AudioSourceComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_3DParams`。 -**返回：** `const Audio::Audio3DParams&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioSourceComponent object; - // 根据上下文补齐参数后调用 AudioSourceComponent::Get3DParams(...)。 - (void)object; -} -``` +- 返回 `m_3DParams`。 ## 相关文档 -- [返回类总览](AudioSourceComponent.md) -- [返回模块目录](../Components.md) +- [AudioSourceComponent](AudioSourceComponent.md) +- [Set3DParams](Set3DParams.md) diff --git a/docs/api/XCEngine/Components/AudioSourceComponent/GetClip.md b/docs/api/XCEngine/Components/AudioSourceComponent/GetClip.md index 529a3c2e..1ac72e42 100644 --- a/docs/api/XCEngine/Components/AudioSourceComponent/GetClip.md +++ b/docs/api/XCEngine/Components/AudioSourceComponent/GetClip.md @@ -1,30 +1,26 @@ # AudioSourceComponent::GetClip -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioSourceComponent.h` + +## 签名 ```cpp Resources::AudioClip* GetClip() const; ``` -该方法声明于 `XCEngine/Components/AudioSourceComponent.h`，当前页面用于固定 `AudioSourceComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_clip` 当前值。 -**返回：** `Resources::AudioClip*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioSourceComponent object; - // 根据上下文补齐参数后调用 AudioSourceComponent::GetClip(...)。 - (void)object; -} -``` +- 返回 `m_clip` 当前值。 ## 相关文档 -- [返回类总览](AudioSourceComponent.md) -- [返回模块目录](../Components.md) +- [AudioSourceComponent](AudioSourceComponent.md) +- [SetClip](SetClip.md) diff --git a/docs/api/XCEngine/Components/AudioSourceComponent/GetDopplerLevel.md b/docs/api/XCEngine/Components/AudioSourceComponent/GetDopplerLevel.md index 008e0bb5..9cc7e420 100644 --- a/docs/api/XCEngine/Components/AudioSourceComponent/GetDopplerLevel.md +++ b/docs/api/XCEngine/Components/AudioSourceComponent/GetDopplerLevel.md @@ -1,30 +1,26 @@ # AudioSourceComponent::GetDopplerLevel -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioSourceComponent.h` + +## 签名 ```cpp float GetDopplerLevel() const; ``` -该方法声明于 `XCEngine/Components/AudioSourceComponent.h`，当前页面用于固定 `AudioSourceComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_3DParams.dopplerLevel`。 -**返回：** `float` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioSourceComponent object; - // 根据上下文补齐参数后调用 AudioSourceComponent::GetDopplerLevel(...)。 - (void)object; -} -``` +- 返回 `m_3DParams.dopplerLevel`。 ## 相关文档 -- [返回类总览](AudioSourceComponent.md) -- [返回模块目录](../Components.md) +- [AudioSourceComponent](AudioSourceComponent.md) +- [SetDopplerLevel](SetDopplerLevel.md) diff --git a/docs/api/XCEngine/Components/AudioSourceComponent/GetDuration.md b/docs/api/XCEngine/Components/AudioSourceComponent/GetDuration.md index 5ee01a58..aa1878ea 100644 --- a/docs/api/XCEngine/Components/AudioSourceComponent/GetDuration.md +++ b/docs/api/XCEngine/Components/AudioSourceComponent/GetDuration.md @@ -1,30 +1,26 @@ # AudioSourceComponent::GetDuration -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioSourceComponent.h` + +## 签名 ```cpp float GetDuration() const; ``` -该方法声明于 `XCEngine/Components/AudioSourceComponent.h`，当前页面用于固定 `AudioSourceComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `IsValid`、`GetDuration` 协同流程。 -**返回：** `float` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioSourceComponent object; - // 根据上下文补齐参数后调用 AudioSourceComponent::GetDuration(...)。 - (void)object; -} -``` +- 当前实现会调用 `IsValid`、`GetDuration`。 +- 包含条件分支，并可能提前返回。 ## 相关文档 -- [返回类总览](AudioSourceComponent.md) -- [返回模块目录](../Components.md) +- [AudioSourceComponent](AudioSourceComponent.md) diff --git a/docs/api/XCEngine/Components/AudioSourceComponent/GetEnergy.md b/docs/api/XCEngine/Components/AudioSourceComponent/GetEnergy.md index bc9cb4a5..8e823e4c 100644 --- a/docs/api/XCEngine/Components/AudioSourceComponent/GetEnergy.md +++ b/docs/api/XCEngine/Components/AudioSourceComponent/GetEnergy.md @@ -1,30 +1,25 @@ # AudioSourceComponent::GetEnergy -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioSourceComponent.h` + +## 签名 ```cpp float GetEnergy() const; ``` -该方法声明于 `XCEngine/Components/AudioSourceComponent.h`，当前页面用于固定 `AudioSourceComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_energy` 当前值。 -**返回：** `float` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioSourceComponent object; - // 根据上下文补齐参数后调用 AudioSourceComponent::GetEnergy(...)。 - (void)object; -} -``` +- 返回 `m_energy` 当前值。 ## 相关文档 -- [返回类总览](AudioSourceComponent.md) -- [返回模块目录](../Components.md) +- [AudioSourceComponent](AudioSourceComponent.md) diff --git a/docs/api/XCEngine/Components/AudioSourceComponent/GetName.md b/docs/api/XCEngine/Components/AudioSourceComponent/GetName.md index 61f44cb0..9f98a5d0 100644 --- a/docs/api/XCEngine/Components/AudioSourceComponent/GetName.md +++ b/docs/api/XCEngine/Components/AudioSourceComponent/GetName.md @@ -1,30 +1,25 @@ # AudioSourceComponent::GetName -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioSourceComponent.h` + +## 签名 ```cpp std::string GetName() const override; ``` -该方法声明于 `XCEngine/Components/AudioSourceComponent.h`，当前页面用于固定 `AudioSourceComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `"AudioSource"`。 -**返回：** `std::string` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioSourceComponent object; - // 根据上下文补齐参数后调用 AudioSourceComponent::GetName(...)。 - (void)object; -} -``` +- 返回 `"AudioSource"`。 ## 相关文档 -- [返回类总览](AudioSourceComponent.md) -- [返回模块目录](../Components.md) +- [AudioSourceComponent](AudioSourceComponent.md) diff --git a/docs/api/XCEngine/Components/AudioSourceComponent/GetOutputMixer.md b/docs/api/XCEngine/Components/AudioSourceComponent/GetOutputMixer.md index ebc28e25..d5ea5418 100644 --- a/docs/api/XCEngine/Components/AudioSourceComponent/GetOutputMixer.md +++ b/docs/api/XCEngine/Components/AudioSourceComponent/GetOutputMixer.md @@ -1,30 +1,26 @@ # AudioSourceComponent::GetOutputMixer -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioSourceComponent.h` + +## 签名 ```cpp Audio::AudioMixer* GetOutputMixer() const; ``` -该方法声明于 `XCEngine/Components/AudioSourceComponent.h`，当前页面用于固定 `AudioSourceComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_outputMixer` 当前值。 -**返回：** `Audio::AudioMixer*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioSourceComponent object; - // 根据上下文补齐参数后调用 AudioSourceComponent::GetOutputMixer(...)。 - (void)object; -} -``` +- 返回 `m_outputMixer` 当前值。 ## 相关文档 -- [返回类总览](AudioSourceComponent.md) -- [返回模块目录](../Components.md) +- [AudioSourceComponent](AudioSourceComponent.md) +- [SetOutputMixer](SetOutputMixer.md) diff --git a/docs/api/XCEngine/Components/AudioSourceComponent/GetPan.md b/docs/api/XCEngine/Components/AudioSourceComponent/GetPan.md index 9b8e7369..9d592a20 100644 --- a/docs/api/XCEngine/Components/AudioSourceComponent/GetPan.md +++ b/docs/api/XCEngine/Components/AudioSourceComponent/GetPan.md @@ -1,30 +1,26 @@ # AudioSourceComponent::GetPan -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioSourceComponent.h` + +## 签名 ```cpp float GetPan() const; ``` -该方法声明于 `XCEngine/Components/AudioSourceComponent.h`，当前页面用于固定 `AudioSourceComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_pan` 当前值。 -**返回：** `float` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioSourceComponent object; - // 根据上下文补齐参数后调用 AudioSourceComponent::GetPan(...)。 - (void)object; -} -``` +- 返回 `m_pan` 当前值。 ## 相关文档 -- [返回类总览](AudioSourceComponent.md) -- [返回模块目录](../Components.md) +- [AudioSourceComponent](AudioSourceComponent.md) +- [SetPan](SetPan.md) diff --git a/docs/api/XCEngine/Components/AudioSourceComponent/GetPitch.md b/docs/api/XCEngine/Components/AudioSourceComponent/GetPitch.md index 2d864f42..cca0d178 100644 --- a/docs/api/XCEngine/Components/AudioSourceComponent/GetPitch.md +++ b/docs/api/XCEngine/Components/AudioSourceComponent/GetPitch.md @@ -1,30 +1,26 @@ # AudioSourceComponent::GetPitch -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioSourceComponent.h` + +## 签名 ```cpp float GetPitch() const; ``` -该方法声明于 `XCEngine/Components/AudioSourceComponent.h`，当前页面用于固定 `AudioSourceComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_pitch` 当前值。 -**返回：** `float` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioSourceComponent object; - // 根据上下文补齐参数后调用 AudioSourceComponent::GetPitch(...)。 - (void)object; -} -``` +- 返回 `m_pitch` 当前值。 ## 相关文档 -- [返回类总览](AudioSourceComponent.md) -- [返回模块目录](../Components.md) +- [AudioSourceComponent](AudioSourceComponent.md) +- [SetPitch](SetPitch.md) diff --git a/docs/api/XCEngine/Components/AudioSourceComponent/GetReverbZoneMix.md b/docs/api/XCEngine/Components/AudioSourceComponent/GetReverbZoneMix.md index 67d55d9b..d6b3c8b9 100644 --- a/docs/api/XCEngine/Components/AudioSourceComponent/GetReverbZoneMix.md +++ b/docs/api/XCEngine/Components/AudioSourceComponent/GetReverbZoneMix.md @@ -1,30 +1,26 @@ # AudioSourceComponent::GetReverbZoneMix -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioSourceComponent.h` + +## 签名 ```cpp float GetReverbZoneMix() const; ``` -该方法声明于 `XCEngine/Components/AudioSourceComponent.h`，当前页面用于固定 `AudioSourceComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_3DParams.reverbZoneMix`。 -**返回：** `float` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioSourceComponent object; - // 根据上下文补齐参数后调用 AudioSourceComponent::GetReverbZoneMix(...)。 - (void)object; -} -``` +- 返回 `m_3DParams.reverbZoneMix`。 ## 相关文档 -- [返回类总览](AudioSourceComponent.md) -- [返回模块目录](../Components.md) +- [AudioSourceComponent](AudioSourceComponent.md) +- [SetReverbZoneMix](SetReverbZoneMix.md) diff --git a/docs/api/XCEngine/Components/AudioSourceComponent/GetSpread.md b/docs/api/XCEngine/Components/AudioSourceComponent/GetSpread.md index 1457ab1d..64cf44f5 100644 --- a/docs/api/XCEngine/Components/AudioSourceComponent/GetSpread.md +++ b/docs/api/XCEngine/Components/AudioSourceComponent/GetSpread.md @@ -1,30 +1,26 @@ # AudioSourceComponent::GetSpread -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioSourceComponent.h` + +## 签名 ```cpp float GetSpread() const; ``` -该方法声明于 `XCEngine/Components/AudioSourceComponent.h`，当前页面用于固定 `AudioSourceComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_3DParams.spread`。 -**返回：** `float` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioSourceComponent object; - // 根据上下文补齐参数后调用 AudioSourceComponent::GetSpread(...)。 - (void)object; -} -``` +- 返回 `m_3DParams.spread`。 ## 相关文档 -- [返回类总览](AudioSourceComponent.md) -- [返回模块目录](../Components.md) +- [AudioSourceComponent](AudioSourceComponent.md) +- [SetSpread](SetSpread.md) diff --git a/docs/api/XCEngine/Components/AudioSourceComponent/GetTime.md b/docs/api/XCEngine/Components/AudioSourceComponent/GetTime.md index 356cfde3..897cf87a 100644 --- a/docs/api/XCEngine/Components/AudioSourceComponent/GetTime.md +++ b/docs/api/XCEngine/Components/AudioSourceComponent/GetTime.md @@ -1,30 +1,26 @@ # AudioSourceComponent::GetTime -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioSourceComponent.h` + +## 签名 ```cpp float GetTime() const; ``` -该方法声明于 `XCEngine/Components/AudioSourceComponent.h`，当前页面用于固定 `AudioSourceComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `static_cast(m_lastingTime)`。 -**返回：** `float` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioSourceComponent object; - // 根据上下文补齐参数后调用 AudioSourceComponent::GetTime(...)。 - (void)object; -} -``` +- 返回 `static_cast(m_lastingTime)`。 ## 相关文档 -- [返回类总览](AudioSourceComponent.md) -- [返回模块目录](../Components.md) +- [AudioSourceComponent](AudioSourceComponent.md) +- [SetTime](SetTime.md) diff --git a/docs/api/XCEngine/Components/AudioSourceComponent/GetVolume.md b/docs/api/XCEngine/Components/AudioSourceComponent/GetVolume.md index 90f3b170..b9b37719 100644 --- a/docs/api/XCEngine/Components/AudioSourceComponent/GetVolume.md +++ b/docs/api/XCEngine/Components/AudioSourceComponent/GetVolume.md @@ -1,30 +1,26 @@ # AudioSourceComponent::GetVolume -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioSourceComponent.h` + +## 签名 ```cpp float GetVolume() const; ``` -该方法声明于 `XCEngine/Components/AudioSourceComponent.h`，当前页面用于固定 `AudioSourceComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_volume` 当前值。 -**返回：** `float` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioSourceComponent object; - // 根据上下文补齐参数后调用 AudioSourceComponent::GetVolume(...)。 - (void)object; -} -``` +- 返回 `m_volume` 当前值。 ## 相关文档 -- [返回类总览](AudioSourceComponent.md) -- [返回模块目录](../Components.md) +- [AudioSourceComponent](AudioSourceComponent.md) +- [SetVolume](SetVolume.md) diff --git a/docs/api/XCEngine/Components/AudioSourceComponent/IsEnergyDetecting.md b/docs/api/XCEngine/Components/AudioSourceComponent/IsEnergyDetecting.md index b00bb9f9..31832352 100644 --- a/docs/api/XCEngine/Components/AudioSourceComponent/IsEnergyDetecting.md +++ b/docs/api/XCEngine/Components/AudioSourceComponent/IsEnergyDetecting.md @@ -1,30 +1,25 @@ # AudioSourceComponent::IsEnergyDetecting -查询当前状态。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioSourceComponent.h` + +## 签名 ```cpp bool IsEnergyDetecting() const; ``` -该方法声明于 `XCEngine/Components/AudioSourceComponent.h`，当前页面用于固定 `AudioSourceComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_isEnergyDetecting` 当前值。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioSourceComponent object; - // 根据上下文补齐参数后调用 AudioSourceComponent::IsEnergyDetecting(...)。 - (void)object; -} -``` +- 返回 `m_isEnergyDetecting` 当前值。 ## 相关文档 -- [返回类总览](AudioSourceComponent.md) -- [返回模块目录](../Components.md) +- [AudioSourceComponent](AudioSourceComponent.md) diff --git a/docs/api/XCEngine/Components/AudioSourceComponent/IsLooping.md b/docs/api/XCEngine/Components/AudioSourceComponent/IsLooping.md index acc385a1..bcef9642 100644 --- a/docs/api/XCEngine/Components/AudioSourceComponent/IsLooping.md +++ b/docs/api/XCEngine/Components/AudioSourceComponent/IsLooping.md @@ -1,30 +1,25 @@ # AudioSourceComponent::IsLooping -查询当前状态。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioSourceComponent.h` + +## 签名 ```cpp bool IsLooping() const; ``` -该方法声明于 `XCEngine/Components/AudioSourceComponent.h`，当前页面用于固定 `AudioSourceComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_isLooping` 当前值。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioSourceComponent object; - // 根据上下文补齐参数后调用 AudioSourceComponent::IsLooping(...)。 - (void)object; -} -``` +- 返回 `m_isLooping` 当前值。 ## 相关文档 -- [返回类总览](AudioSourceComponent.md) -- [返回模块目录](../Components.md) +- [AudioSourceComponent](AudioSourceComponent.md) diff --git a/docs/api/XCEngine/Components/AudioSourceComponent/IsPaused.md b/docs/api/XCEngine/Components/AudioSourceComponent/IsPaused.md index 1bf7c7f7..d975f37d 100644 --- a/docs/api/XCEngine/Components/AudioSourceComponent/IsPaused.md +++ b/docs/api/XCEngine/Components/AudioSourceComponent/IsPaused.md @@ -1,30 +1,25 @@ # AudioSourceComponent::IsPaused -查询当前状态。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioSourceComponent.h` + +## 签名 ```cpp bool IsPaused() const; ``` -该方法声明于 `XCEngine/Components/AudioSourceComponent.h`，当前页面用于固定 `AudioSourceComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_playState`。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioSourceComponent object; - // 根据上下文补齐参数后调用 AudioSourceComponent::IsPaused(...)。 - (void)object; -} -``` +- 会更新 `m_playState`。 ## 相关文档 -- [返回类总览](AudioSourceComponent.md) -- [返回模块目录](../Components.md) +- [AudioSourceComponent](AudioSourceComponent.md) diff --git a/docs/api/XCEngine/Components/AudioSourceComponent/IsPlaying.md b/docs/api/XCEngine/Components/AudioSourceComponent/IsPlaying.md index 881afed2..33176286 100644 --- a/docs/api/XCEngine/Components/AudioSourceComponent/IsPlaying.md +++ b/docs/api/XCEngine/Components/AudioSourceComponent/IsPlaying.md @@ -1,30 +1,25 @@ # AudioSourceComponent::IsPlaying -查询当前状态。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioSourceComponent.h` + +## 签名 ```cpp bool IsPlaying() const; ``` -该方法声明于 `XCEngine/Components/AudioSourceComponent.h`，当前页面用于固定 `AudioSourceComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_playState`。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioSourceComponent object; - // 根据上下文补齐参数后调用 AudioSourceComponent::IsPlaying(...)。 - (void)object; -} -``` +- 会更新 `m_playState`。 ## 相关文档 -- [返回类总览](AudioSourceComponent.md) -- [返回模块目录](../Components.md) +- [AudioSourceComponent](AudioSourceComponent.md) diff --git a/docs/api/XCEngine/Components/AudioSourceComponent/IsSpatialize.md b/docs/api/XCEngine/Components/AudioSourceComponent/IsSpatialize.md index a12d7ce6..a286b587 100644 --- a/docs/api/XCEngine/Components/AudioSourceComponent/IsSpatialize.md +++ b/docs/api/XCEngine/Components/AudioSourceComponent/IsSpatialize.md @@ -1,30 +1,25 @@ # AudioSourceComponent::IsSpatialize -查询当前状态。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioSourceComponent.h` + +## 签名 ```cpp bool IsSpatialize() const; ``` -该方法声明于 `XCEngine/Components/AudioSourceComponent.h`，当前页面用于固定 `AudioSourceComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_spatialize` 当前值。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioSourceComponent object; - // 根据上下文补齐参数后调用 AudioSourceComponent::IsSpatialize(...)。 - (void)object; -} -``` +- 返回 `m_spatialize` 当前值。 ## 相关文档 -- [返回类总览](AudioSourceComponent.md) -- [返回模块目录](../Components.md) +- [AudioSourceComponent](AudioSourceComponent.md) diff --git a/docs/api/XCEngine/Components/AudioSourceComponent/OnDestroy.md b/docs/api/XCEngine/Components/AudioSourceComponent/OnDestroy.md index 0b76f5ee..75211022 100644 --- a/docs/api/XCEngine/Components/AudioSourceComponent/OnDestroy.md +++ b/docs/api/XCEngine/Components/AudioSourceComponent/OnDestroy.md @@ -1,30 +1,25 @@ # AudioSourceComponent::OnDestroy -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioSourceComponent.h` + +## 签名 ```cpp void OnDestroy() override; ``` -该方法声明于 `XCEngine/Components/AudioSourceComponent.h`，当前页面用于固定 `AudioSourceComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `Stop(...)` 相关流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioSourceComponent object; - // 根据上下文补齐参数后调用 AudioSourceComponent::OnDestroy(...)。 - (void)object; -} -``` +- 当前实现会调用 `Stop`。 ## 相关文档 -- [返回类总览](AudioSourceComponent.md) -- [返回模块目录](../Components.md) +- [AudioSourceComponent](AudioSourceComponent.md) diff --git a/docs/api/XCEngine/Components/AudioSourceComponent/OnDisable.md b/docs/api/XCEngine/Components/AudioSourceComponent/OnDisable.md index 69bdce32..d4c33701 100644 --- a/docs/api/XCEngine/Components/AudioSourceComponent/OnDisable.md +++ b/docs/api/XCEngine/Components/AudioSourceComponent/OnDisable.md @@ -1,30 +1,26 @@ # AudioSourceComponent::OnDisable -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioSourceComponent.h` + +## 签名 ```cpp void OnDisable() override; ``` -该方法声明于 `XCEngine/Components/AudioSourceComponent.h`，当前页面用于固定 `AudioSourceComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_playState`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioSourceComponent object; - // 根据上下文补齐参数后调用 AudioSourceComponent::OnDisable(...)。 - (void)object; -} -``` +- 会更新 `m_playState`。 +- 当前实现会调用 `UnregisterSource`。 ## 相关文档 -- [返回类总览](AudioSourceComponent.md) -- [返回模块目录](../Components.md) +- [AudioSourceComponent](AudioSourceComponent.md) diff --git a/docs/api/XCEngine/Components/AudioSourceComponent/OnEnable.md b/docs/api/XCEngine/Components/AudioSourceComponent/OnEnable.md index 7550ec5e..b7d24feb 100644 --- a/docs/api/XCEngine/Components/AudioSourceComponent/OnEnable.md +++ b/docs/api/XCEngine/Components/AudioSourceComponent/OnEnable.md @@ -1,30 +1,26 @@ # AudioSourceComponent::OnEnable -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioSourceComponent.h` + +## 签名 ```cpp void OnEnable() override; ``` -该方法声明于 `XCEngine/Components/AudioSourceComponent.h`，当前页面用于固定 `AudioSourceComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_playState`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioSourceComponent object; - // 根据上下文补齐参数后调用 AudioSourceComponent::OnEnable(...)。 - (void)object; -} -``` +- 会更新 `m_playState`。 +- 当前实现会调用 `RegisterSource`。 ## 相关文档 -- [返回类总览](AudioSourceComponent.md) -- [返回模块目录](../Components.md) +- [AudioSourceComponent](AudioSourceComponent.md) diff --git a/docs/api/XCEngine/Components/AudioSourceComponent/Pause.md b/docs/api/XCEngine/Components/AudioSourceComponent/Pause.md index b4a64e91..eab48fd5 100644 --- a/docs/api/XCEngine/Components/AudioSourceComponent/Pause.md +++ b/docs/api/XCEngine/Components/AudioSourceComponent/Pause.md @@ -1,30 +1,26 @@ # AudioSourceComponent::Pause -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioSourceComponent.h` + +## 签名 ```cpp void Pause(); ``` -该方法声明于 `XCEngine/Components/AudioSourceComponent.h`，当前页面用于固定 `AudioSourceComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_playState`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioSourceComponent object; - // 根据上下文补齐参数后调用 AudioSourceComponent::Pause(...)。 - (void)object; -} -``` +- 会更新 `m_playState`。 +- 当前实现会调用 `UnregisterSource`。 ## 相关文档 -- [返回类总览](AudioSourceComponent.md) -- [返回模块目录](../Components.md) +- [AudioSourceComponent](AudioSourceComponent.md) diff --git a/docs/api/XCEngine/Components/AudioSourceComponent/Play.md b/docs/api/XCEngine/Components/AudioSourceComponent/Play.md index 82d4bd67..9fcda90c 100644 --- a/docs/api/XCEngine/Components/AudioSourceComponent/Play.md +++ b/docs/api/XCEngine/Components/AudioSourceComponent/Play.md @@ -1,30 +1,26 @@ # AudioSourceComponent::Play -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioSourceComponent.h` + +## 签名 ```cpp void Play(); ``` -该方法声明于 `XCEngine/Components/AudioSourceComponent.h`，当前页面用于固定 `AudioSourceComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `IsValid`、`RegisterSource` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioSourceComponent object; - // 根据上下文补齐参数后调用 AudioSourceComponent::Play(...)。 - (void)object; -} -``` +- 会更新 `m_playState`、`m_samplePosition`、`m_lastingTime`。 +- 当前实现会调用 `IsValid`、`RegisterSource`。 ## 相关文档 -- [返回类总览](AudioSourceComponent.md) -- [返回模块目录](../Components.md) +- [AudioSourceComponent](AudioSourceComponent.md) diff --git a/docs/api/XCEngine/Components/AudioSourceComponent/ProcessAudio.md b/docs/api/XCEngine/Components/AudioSourceComponent/ProcessAudio.md index fa164816..b5de06d0 100644 --- a/docs/api/XCEngine/Components/AudioSourceComponent/ProcessAudio.md +++ b/docs/api/XCEngine/Components/AudioSourceComponent/ProcessAudio.md @@ -1,35 +1,26 @@ # AudioSourceComponent::ProcessAudio -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioSourceComponent.h` + +## 签名 ```cpp void ProcessAudio(float* buffer, Audio::uint32 sampleCount, Audio::uint32 channels, const Math::Vector3& listenerPosition, const Math::Quaternion& listenerRotation); ``` -该方法声明于 `XCEngine/Components/AudioSourceComponent.h`，当前页面用于固定 `AudioSourceComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `buffer` - 参数语义详见头文件声明。 -- `sampleCount` - 参数语义详见头文件声明。 -- `channels` - 参数语义详见头文件声明。 -- `listenerPosition` - 参数语义详见头文件声明。 -- `listenerRotation` - 参数语义详见头文件声明。 +更新 `m_samplePosition`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioSourceComponent object; - // 根据上下文补齐参数后调用 AudioSourceComponent::ProcessAudio(...)。 - (void)object; -} -``` +- 会更新 `m_samplePosition`。 +- 当前实现会调用 `empty`、`Apply3DAttenuation`、`GetChannels`、`size`、`Stop`。 ## 相关文档 -- [返回类总览](AudioSourceComponent.md) -- [返回模块目录](../Components.md) +- [AudioSourceComponent](AudioSourceComponent.md) diff --git a/docs/api/XCEngine/Components/AudioSourceComponent/Set3DParams.md b/docs/api/XCEngine/Components/AudioSourceComponent/Set3DParams.md index e912c2ba..617fa249 100644 --- a/docs/api/XCEngine/Components/AudioSourceComponent/Set3DParams.md +++ b/docs/api/XCEngine/Components/AudioSourceComponent/Set3DParams.md @@ -1,31 +1,26 @@ # AudioSourceComponent::Set3DParams -设置相关状态或配置。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioSourceComponent.h` + +## 签名 ```cpp void Set3DParams(const Audio::Audio3DParams& params); ``` -该方法声明于 `XCEngine/Components/AudioSourceComponent.h`，当前页面用于固定 `AudioSourceComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `params` - 参数语义详见头文件声明。 +执行该公开方法对应的当前实现。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioSourceComponent object; - // 根据上下文补齐参数后调用 AudioSourceComponent::Set3DParams(...)。 - (void)object; -} -``` +- 执行该公开方法对应的当前实现。 ## 相关文档 -- [返回类总览](AudioSourceComponent.md) -- [返回模块目录](../Components.md) +- [AudioSourceComponent](AudioSourceComponent.md) +- [Get3DParams](Get3DParams.md) diff --git a/docs/api/XCEngine/Components/AudioSourceComponent/SetClip.md b/docs/api/XCEngine/Components/AudioSourceComponent/SetClip.md index 59355308..f5b97468 100644 --- a/docs/api/XCEngine/Components/AudioSourceComponent/SetClip.md +++ b/docs/api/XCEngine/Components/AudioSourceComponent/SetClip.md @@ -1,31 +1,27 @@ # AudioSourceComponent::SetClip -设置相关状态或配置。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioSourceComponent.h` + +## 签名 ```cpp void SetClip(Resources::AudioClip* clip); ``` -该方法声明于 `XCEngine/Components/AudioSourceComponent.h`，当前页面用于固定 `AudioSourceComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `clip` - 参数语义详见头文件声明。 +执行 `IsValid`、`DecodeAudioData` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioSourceComponent object; - // 根据上下文补齐参数后调用 AudioSourceComponent::SetClip(...)。 - (void)object; -} -``` +- 会更新 `m_clip`、`m_isDecoded`。 +- 当前实现会调用 `IsValid`、`DecodeAudioData`。 ## 相关文档 -- [返回类总览](AudioSourceComponent.md) -- [返回模块目录](../Components.md) +- [AudioSourceComponent](AudioSourceComponent.md) +- [GetClip](GetClip.md) diff --git a/docs/api/XCEngine/Components/AudioSourceComponent/SetDopplerLevel.md b/docs/api/XCEngine/Components/AudioSourceComponent/SetDopplerLevel.md index 6e2436fc..5347bda5 100644 --- a/docs/api/XCEngine/Components/AudioSourceComponent/SetDopplerLevel.md +++ b/docs/api/XCEngine/Components/AudioSourceComponent/SetDopplerLevel.md @@ -1,31 +1,26 @@ # AudioSourceComponent::SetDopplerLevel -设置相关状态或配置。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioSourceComponent.h` + +## 签名 ```cpp void SetDopplerLevel(float level); ``` -该方法声明于 `XCEngine/Components/AudioSourceComponent.h`，当前页面用于固定 `AudioSourceComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `level` - 参数语义详见头文件声明。 +执行该公开方法对应的当前实现。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioSourceComponent object; - // 根据上下文补齐参数后调用 AudioSourceComponent::SetDopplerLevel(...)。 - (void)object; -} -``` +- 执行该公开方法对应的当前实现。 ## 相关文档 -- [返回类总览](AudioSourceComponent.md) -- [返回模块目录](../Components.md) +- [AudioSourceComponent](AudioSourceComponent.md) +- [GetDopplerLevel](GetDopplerLevel.md) diff --git a/docs/api/XCEngine/Components/AudioSourceComponent/SetLooping.md b/docs/api/XCEngine/Components/AudioSourceComponent/SetLooping.md index 8ed1265b..72532924 100644 --- a/docs/api/XCEngine/Components/AudioSourceComponent/SetLooping.md +++ b/docs/api/XCEngine/Components/AudioSourceComponent/SetLooping.md @@ -1,31 +1,25 @@ # AudioSourceComponent::SetLooping -设置相关状态或配置。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioSourceComponent.h` + +## 签名 ```cpp void SetLooping(bool loop); ``` -该方法声明于 `XCEngine/Components/AudioSourceComponent.h`，当前页面用于固定 `AudioSourceComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `loop` - 参数语义详见头文件声明。 +更新 `m_isLooping`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioSourceComponent object; - // 根据上下文补齐参数后调用 AudioSourceComponent::SetLooping(...)。 - (void)object; -} -``` +- 会更新 `m_isLooping`。 ## 相关文档 -- [返回类总览](AudioSourceComponent.md) -- [返回模块目录](../Components.md) +- [AudioSourceComponent](AudioSourceComponent.md) diff --git a/docs/api/XCEngine/Components/AudioSourceComponent/SetOutputMixer.md b/docs/api/XCEngine/Components/AudioSourceComponent/SetOutputMixer.md index 8323ba5e..83ce7c88 100644 --- a/docs/api/XCEngine/Components/AudioSourceComponent/SetOutputMixer.md +++ b/docs/api/XCEngine/Components/AudioSourceComponent/SetOutputMixer.md @@ -1,31 +1,26 @@ # AudioSourceComponent::SetOutputMixer -设置相关状态或配置。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioSourceComponent.h` + +## 签名 ```cpp void SetOutputMixer(Audio::AudioMixer* mixer); ``` -该方法声明于 `XCEngine/Components/AudioSourceComponent.h`，当前页面用于固定 `AudioSourceComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `mixer` - 参数语义详见头文件声明。 +更新 `m_outputMixer`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioSourceComponent object; - // 根据上下文补齐参数后调用 AudioSourceComponent::SetOutputMixer(...)。 - (void)object; -} -``` +- 会更新 `m_outputMixer`。 ## 相关文档 -- [返回类总览](AudioSourceComponent.md) -- [返回模块目录](../Components.md) +- [AudioSourceComponent](AudioSourceComponent.md) +- [GetOutputMixer](GetOutputMixer.md) diff --git a/docs/api/XCEngine/Components/AudioSourceComponent/SetPan.md b/docs/api/XCEngine/Components/AudioSourceComponent/SetPan.md index 04ea5503..619b2efe 100644 --- a/docs/api/XCEngine/Components/AudioSourceComponent/SetPan.md +++ b/docs/api/XCEngine/Components/AudioSourceComponent/SetPan.md @@ -1,31 +1,27 @@ # AudioSourceComponent::SetPan -设置相关状态或配置。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioSourceComponent.h` + +## 签名 ```cpp void SetPan(float pan); ``` -该方法声明于 `XCEngine/Components/AudioSourceComponent.h`，当前页面用于固定 `AudioSourceComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `pan` - 参数语义详见头文件声明。 +更新 `m_pan`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioSourceComponent object; - // 根据上下文补齐参数后调用 AudioSourceComponent::SetPan(...)。 - (void)object; -} -``` +- 会更新 `m_pan`。 +- 当前实现会调用 `max`、`min`。 ## 相关文档 -- [返回类总览](AudioSourceComponent.md) -- [返回模块目录](../Components.md) +- [AudioSourceComponent](AudioSourceComponent.md) +- [GetPan](GetPan.md) diff --git a/docs/api/XCEngine/Components/AudioSourceComponent/SetPitch.md b/docs/api/XCEngine/Components/AudioSourceComponent/SetPitch.md index acb0aaf6..e2c06fcb 100644 --- a/docs/api/XCEngine/Components/AudioSourceComponent/SetPitch.md +++ b/docs/api/XCEngine/Components/AudioSourceComponent/SetPitch.md @@ -1,31 +1,27 @@ # AudioSourceComponent::SetPitch -设置相关状态或配置。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioSourceComponent.h` + +## 签名 ```cpp void SetPitch(float pitch); ``` -该方法声明于 `XCEngine/Components/AudioSourceComponent.h`，当前页面用于固定 `AudioSourceComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `pitch` - 参数语义详见头文件声明。 +更新 `m_pitch`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioSourceComponent object; - // 根据上下文补齐参数后调用 AudioSourceComponent::SetPitch(...)。 - (void)object; -} -``` +- 会更新 `m_pitch`。 +- 当前实现会调用 `max`、`min`。 ## 相关文档 -- [返回类总览](AudioSourceComponent.md) -- [返回模块目录](../Components.md) +- [AudioSourceComponent](AudioSourceComponent.md) +- [GetPitch](GetPitch.md) diff --git a/docs/api/XCEngine/Components/AudioSourceComponent/SetReverbZoneMix.md b/docs/api/XCEngine/Components/AudioSourceComponent/SetReverbZoneMix.md index 27295bb5..38908d36 100644 --- a/docs/api/XCEngine/Components/AudioSourceComponent/SetReverbZoneMix.md +++ b/docs/api/XCEngine/Components/AudioSourceComponent/SetReverbZoneMix.md @@ -1,31 +1,26 @@ # AudioSourceComponent::SetReverbZoneMix -设置相关状态或配置。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioSourceComponent.h` + +## 签名 ```cpp void SetReverbZoneMix(float mix); ``` -该方法声明于 `XCEngine/Components/AudioSourceComponent.h`，当前页面用于固定 `AudioSourceComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `mix` - 参数语义详见头文件声明。 +执行 `max`、`min` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioSourceComponent object; - // 根据上下文补齐参数后调用 AudioSourceComponent::SetReverbZoneMix(...)。 - (void)object; -} -``` +- 当前实现会调用 `max`、`min`。 ## 相关文档 -- [返回类总览](AudioSourceComponent.md) -- [返回模块目录](../Components.md) +- [AudioSourceComponent](AudioSourceComponent.md) +- [GetReverbZoneMix](GetReverbZoneMix.md) diff --git a/docs/api/XCEngine/Components/AudioSourceComponent/SetSpatialize.md b/docs/api/XCEngine/Components/AudioSourceComponent/SetSpatialize.md index c7dafb08..ae9b97ee 100644 --- a/docs/api/XCEngine/Components/AudioSourceComponent/SetSpatialize.md +++ b/docs/api/XCEngine/Components/AudioSourceComponent/SetSpatialize.md @@ -1,31 +1,25 @@ # AudioSourceComponent::SetSpatialize -设置相关状态或配置。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioSourceComponent.h` + +## 签名 ```cpp void SetSpatialize(bool spatialize); ``` -该方法声明于 `XCEngine/Components/AudioSourceComponent.h`，当前页面用于固定 `AudioSourceComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `spatialize` - 参数语义详见头文件声明。 +更新 `m_spatialize`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioSourceComponent object; - // 根据上下文补齐参数后调用 AudioSourceComponent::SetSpatialize(...)。 - (void)object; -} -``` +- 会更新 `m_spatialize`。 ## 相关文档 -- [返回类总览](AudioSourceComponent.md) -- [返回模块目录](../Components.md) +- [AudioSourceComponent](AudioSourceComponent.md) diff --git a/docs/api/XCEngine/Components/AudioSourceComponent/SetSpread.md b/docs/api/XCEngine/Components/AudioSourceComponent/SetSpread.md index d5a0fb3a..63f8ab35 100644 --- a/docs/api/XCEngine/Components/AudioSourceComponent/SetSpread.md +++ b/docs/api/XCEngine/Components/AudioSourceComponent/SetSpread.md @@ -1,31 +1,26 @@ # AudioSourceComponent::SetSpread -设置相关状态或配置。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioSourceComponent.h` + +## 签名 ```cpp void SetSpread(float spread); ``` -该方法声明于 `XCEngine/Components/AudioSourceComponent.h`，当前页面用于固定 `AudioSourceComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `spread` - 参数语义详见头文件声明。 +执行 `max`、`min` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioSourceComponent object; - // 根据上下文补齐参数后调用 AudioSourceComponent::SetSpread(...)。 - (void)object; -} -``` +- 当前实现会调用 `max`、`min`。 ## 相关文档 -- [返回类总览](AudioSourceComponent.md) -- [返回模块目录](../Components.md) +- [AudioSourceComponent](AudioSourceComponent.md) +- [GetSpread](GetSpread.md) diff --git a/docs/api/XCEngine/Components/AudioSourceComponent/SetTime.md b/docs/api/XCEngine/Components/AudioSourceComponent/SetTime.md index f50d3e08..25efecd0 100644 --- a/docs/api/XCEngine/Components/AudioSourceComponent/SetTime.md +++ b/docs/api/XCEngine/Components/AudioSourceComponent/SetTime.md @@ -1,31 +1,27 @@ # AudioSourceComponent::SetTime -设置相关状态或配置。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioSourceComponent.h` + +## 签名 ```cpp void SetTime(float seconds); ``` -该方法声明于 `XCEngine/Components/AudioSourceComponent.h`，当前页面用于固定 `AudioSourceComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `seconds` - 参数语义详见头文件声明。 +执行 `IsValid`、`GetSampleRate`、`GetChannels` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioSourceComponent object; - // 根据上下文补齐参数后调用 AudioSourceComponent::SetTime(...)。 - (void)object; -} -``` +- 会更新 `m_samplePosition`、`m_lastingTime`。 +- 当前实现会调用 `IsValid`、`GetSampleRate`、`GetChannels`。 ## 相关文档 -- [返回类总览](AudioSourceComponent.md) -- [返回模块目录](../Components.md) +- [AudioSourceComponent](AudioSourceComponent.md) +- [GetTime](GetTime.md) diff --git a/docs/api/XCEngine/Components/AudioSourceComponent/SetVolume.md b/docs/api/XCEngine/Components/AudioSourceComponent/SetVolume.md index 9402dba8..21f0d638 100644 --- a/docs/api/XCEngine/Components/AudioSourceComponent/SetVolume.md +++ b/docs/api/XCEngine/Components/AudioSourceComponent/SetVolume.md @@ -1,31 +1,27 @@ # AudioSourceComponent::SetVolume -设置相关状态或配置。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioSourceComponent.h` + +## 签名 ```cpp void SetVolume(float volume); ``` -该方法声明于 `XCEngine/Components/AudioSourceComponent.h`，当前页面用于固定 `AudioSourceComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `volume` - 参数语义详见头文件声明。 +更新 `m_volume`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioSourceComponent object; - // 根据上下文补齐参数后调用 AudioSourceComponent::SetVolume(...)。 - (void)object; -} -``` +- 会更新 `m_volume`。 +- 当前实现会调用 `max`、`min`。 ## 相关文档 -- [返回类总览](AudioSourceComponent.md) -- [返回模块目录](../Components.md) +- [AudioSourceComponent](AudioSourceComponent.md) +- [GetVolume](GetVolume.md) diff --git a/docs/api/XCEngine/Components/AudioSourceComponent/StartEnergyDetect.md b/docs/api/XCEngine/Components/AudioSourceComponent/StartEnergyDetect.md index 014b0e24..cb2cee7e 100644 --- a/docs/api/XCEngine/Components/AudioSourceComponent/StartEnergyDetect.md +++ b/docs/api/XCEngine/Components/AudioSourceComponent/StartEnergyDetect.md @@ -1,30 +1,26 @@ # AudioSourceComponent::StartEnergyDetect -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioSourceComponent.h` + +## 签名 ```cpp void StartEnergyDetect(); ``` -该方法声明于 `XCEngine/Components/AudioSourceComponent.h`，当前页面用于固定 `AudioSourceComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_isEnergyDetecting`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioSourceComponent object; - // 根据上下文补齐参数后调用 AudioSourceComponent::StartEnergyDetect(...)。 - (void)object; -} -``` +- 会更新 `m_isEnergyDetecting`。 +- 当前实现会调用 `clear`。 ## 相关文档 -- [返回类总览](AudioSourceComponent.md) -- [返回模块目录](../Components.md) +- [AudioSourceComponent](AudioSourceComponent.md) diff --git a/docs/api/XCEngine/Components/AudioSourceComponent/Stop.md b/docs/api/XCEngine/Components/AudioSourceComponent/Stop.md index 636535e2..e633f5d7 100644 --- a/docs/api/XCEngine/Components/AudioSourceComponent/Stop.md +++ b/docs/api/XCEngine/Components/AudioSourceComponent/Stop.md @@ -1,31 +1,26 @@ # AudioSourceComponent::Stop -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioSourceComponent.h` + +## 签名 ```cpp void Stop(Audio::StopMode mode = Audio::StopMode::Immediate); ``` -该方法声明于 `XCEngine/Components/AudioSourceComponent.h`，当前页面用于固定 `AudioSourceComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `mode` - 参数语义详见头文件声明。 +执行 `UnregisterSource` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioSourceComponent object; - // 根据上下文补齐参数后调用 AudioSourceComponent::Stop(...)。 - (void)object; -} -``` +- 会更新 `m_playState`、`m_samplePosition`。 +- 当前实现会调用 `UnregisterSource`。 ## 相关文档 -- [返回类总览](AudioSourceComponent.md) -- [返回模块目录](../Components.md) +- [AudioSourceComponent](AudioSourceComponent.md) diff --git a/docs/api/XCEngine/Components/AudioSourceComponent/StopEnergyDetect.md b/docs/api/XCEngine/Components/AudioSourceComponent/StopEnergyDetect.md index e9beafa8..1b65dd3a 100644 --- a/docs/api/XCEngine/Components/AudioSourceComponent/StopEnergyDetect.md +++ b/docs/api/XCEngine/Components/AudioSourceComponent/StopEnergyDetect.md @@ -1,30 +1,25 @@ # AudioSourceComponent::StopEnergyDetect -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioSourceComponent.h` + +## 签名 ```cpp void StopEnergyDetect(); ``` -该方法声明于 `XCEngine/Components/AudioSourceComponent.h`，当前页面用于固定 `AudioSourceComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_isEnergyDetecting`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioSourceComponent object; - // 根据上下文补齐参数后调用 AudioSourceComponent::StopEnergyDetect(...)。 - (void)object; -} -``` +- 会更新 `m_isEnergyDetecting`。 ## 相关文档 -- [返回类总览](AudioSourceComponent.md) -- [返回模块目录](../Components.md) +- [AudioSourceComponent](AudioSourceComponent.md) diff --git a/docs/api/XCEngine/Components/AudioSourceComponent/Update.md b/docs/api/XCEngine/Components/AudioSourceComponent/Update.md index 81404e0a..6dd22580 100644 --- a/docs/api/XCEngine/Components/AudioSourceComponent/Update.md +++ b/docs/api/XCEngine/Components/AudioSourceComponent/Update.md @@ -1,31 +1,26 @@ # AudioSourceComponent::Update -更新运行时状态。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/AudioSourceComponent.h` + +## 签名 ```cpp void Update(float deltaTime) override; ``` -该方法声明于 `XCEngine/Components/AudioSourceComponent.h`，当前页面用于固定 `AudioSourceComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `deltaTime` - 参数语义详见头文件声明。 +执行 `GetChannels`、`GetSampleRate`、`GetAudioData` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::AudioSourceComponent object; - // 根据上下文补齐参数后调用 AudioSourceComponent::Update(...)。 - (void)object; -} -``` +- 会更新 `m_lastingTime`、`m_samplePosition`。 +- 当前实现会调用 `GetChannels`、`GetSampleRate`、`GetAudioData`、`GetBitsPerSample`、`Stop`。 ## 相关文档 -- [返回类总览](AudioSourceComponent.md) -- [返回模块目录](../Components.md) +- [AudioSourceComponent](AudioSourceComponent.md) diff --git a/docs/api/XCEngine/Components/CameraComponent/Deserialize.md b/docs/api/XCEngine/Components/CameraComponent/Deserialize.md index 3b19ec2d..43e12c42 100644 --- a/docs/api/XCEngine/Components/CameraComponent/Deserialize.md +++ b/docs/api/XCEngine/Components/CameraComponent/Deserialize.md @@ -1,31 +1,26 @@ # CameraComponent::Deserialize -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/CameraComponent.h` + +## 签名 ```cpp void Deserialize(std::istream& is) override; ``` -该方法声明于 `XCEngine/Components/CameraComponent.h`，当前页面用于固定 `CameraComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `is` - 参数语义详见头文件声明。 +执行 `getline`、`empty`、`find` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::CameraComponent object; - // 根据上下文补齐参数后调用 CameraComponent::Deserialize(...)。 - (void)object; -} -``` +- 会更新 `m_projectionType`、`m_depth`、`m_primary`、`m_clearMode`。 +- 当前实现会调用 `getline`、`empty`、`find`、`substr`。 ## 相关文档 -- [返回类总览](CameraComponent.md) -- [返回模块目录](../Components.md) +- [CameraComponent](CameraComponent.md) diff --git a/docs/api/XCEngine/Components/CameraComponent/GetClearColor.md b/docs/api/XCEngine/Components/CameraComponent/GetClearColor.md index e7d41a06..28720634 100644 --- a/docs/api/XCEngine/Components/CameraComponent/GetClearColor.md +++ b/docs/api/XCEngine/Components/CameraComponent/GetClearColor.md @@ -1,30 +1,26 @@ # CameraComponent::GetClearColor -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/CameraComponent.h` + +## 签名 ```cpp const Math::Color& GetClearColor() const; ``` -该方法声明于 `XCEngine/Components/CameraComponent.h`，当前页面用于固定 `CameraComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_clearColor` 当前值。 -**返回：** `const Math::Color&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::CameraComponent object; - // 根据上下文补齐参数后调用 CameraComponent::GetClearColor(...)。 - (void)object; -} -``` +- 返回 `m_clearColor` 当前值。 ## 相关文档 -- [返回类总览](CameraComponent.md) -- [返回模块目录](../Components.md) +- [CameraComponent](CameraComponent.md) +- [SetClearColor](SetClearColor.md) diff --git a/docs/api/XCEngine/Components/CameraComponent/GetDepth.md b/docs/api/XCEngine/Components/CameraComponent/GetDepth.md index f54bcf94..ed318d3f 100644 --- a/docs/api/XCEngine/Components/CameraComponent/GetDepth.md +++ b/docs/api/XCEngine/Components/CameraComponent/GetDepth.md @@ -1,30 +1,26 @@ # CameraComponent::GetDepth -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/CameraComponent.h` + +## 签名 ```cpp float GetDepth() const; ``` -该方法声明于 `XCEngine/Components/CameraComponent.h`，当前页面用于固定 `CameraComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_depth` 当前值。 -**返回：** `float` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::CameraComponent object; - // 根据上下文补齐参数后调用 CameraComponent::GetDepth(...)。 - (void)object; -} -``` +- 返回 `m_depth` 当前值。 ## 相关文档 -- [返回类总览](CameraComponent.md) -- [返回模块目录](../Components.md) +- [CameraComponent](CameraComponent.md) +- [SetDepth](SetDepth.md) diff --git a/docs/api/XCEngine/Components/CameraComponent/GetFarClipPlane.md b/docs/api/XCEngine/Components/CameraComponent/GetFarClipPlane.md index 72f1d19c..3df41ad4 100644 --- a/docs/api/XCEngine/Components/CameraComponent/GetFarClipPlane.md +++ b/docs/api/XCEngine/Components/CameraComponent/GetFarClipPlane.md @@ -1,30 +1,26 @@ # CameraComponent::GetFarClipPlane -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/CameraComponent.h` + +## 签名 ```cpp float GetFarClipPlane() const; ``` -该方法声明于 `XCEngine/Components/CameraComponent.h`，当前页面用于固定 `CameraComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_farClipPlane` 当前值。 -**返回：** `float` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::CameraComponent object; - // 根据上下文补齐参数后调用 CameraComponent::GetFarClipPlane(...)。 - (void)object; -} -``` +- 返回 `m_farClipPlane` 当前值。 ## 相关文档 -- [返回类总览](CameraComponent.md) -- [返回模块目录](../Components.md) +- [CameraComponent](CameraComponent.md) +- [SetFarClipPlane](SetFarClipPlane.md) diff --git a/docs/api/XCEngine/Components/CameraComponent/GetFieldOfView.md b/docs/api/XCEngine/Components/CameraComponent/GetFieldOfView.md index 8fbea413..a91850a3 100644 --- a/docs/api/XCEngine/Components/CameraComponent/GetFieldOfView.md +++ b/docs/api/XCEngine/Components/CameraComponent/GetFieldOfView.md @@ -1,30 +1,26 @@ # CameraComponent::GetFieldOfView -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/CameraComponent.h` + +## 签名 ```cpp float GetFieldOfView() const; ``` -该方法声明于 `XCEngine/Components/CameraComponent.h`，当前页面用于固定 `CameraComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_fieldOfView` 当前值。 -**返回：** `float` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::CameraComponent object; - // 根据上下文补齐参数后调用 CameraComponent::GetFieldOfView(...)。 - (void)object; -} -``` +- 返回 `m_fieldOfView` 当前值。 ## 相关文档 -- [返回类总览](CameraComponent.md) -- [返回模块目录](../Components.md) +- [CameraComponent](CameraComponent.md) +- [SetFieldOfView](SetFieldOfView.md) diff --git a/docs/api/XCEngine/Components/CameraComponent/GetName.md b/docs/api/XCEngine/Components/CameraComponent/GetName.md index 9817c9d0..bb703195 100644 --- a/docs/api/XCEngine/Components/CameraComponent/GetName.md +++ b/docs/api/XCEngine/Components/CameraComponent/GetName.md @@ -1,30 +1,25 @@ # CameraComponent::GetName -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/CameraComponent.h` + +## 签名 ```cpp std::string GetName() const override; ``` -该方法声明于 `XCEngine/Components/CameraComponent.h`，当前页面用于固定 `CameraComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `"Camera"`。 -**返回：** `std::string` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::CameraComponent object; - // 根据上下文补齐参数后调用 CameraComponent::GetName(...)。 - (void)object; -} -``` +- 返回 `"Camera"`。 ## 相关文档 -- [返回类总览](CameraComponent.md) -- [返回模块目录](../Components.md) +- [CameraComponent](CameraComponent.md) diff --git a/docs/api/XCEngine/Components/CameraComponent/GetNearClipPlane.md b/docs/api/XCEngine/Components/CameraComponent/GetNearClipPlane.md index 34e90f18..3cf7a790 100644 --- a/docs/api/XCEngine/Components/CameraComponent/GetNearClipPlane.md +++ b/docs/api/XCEngine/Components/CameraComponent/GetNearClipPlane.md @@ -1,30 +1,26 @@ # CameraComponent::GetNearClipPlane -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/CameraComponent.h` + +## 签名 ```cpp float GetNearClipPlane() const; ``` -该方法声明于 `XCEngine/Components/CameraComponent.h`，当前页面用于固定 `CameraComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_nearClipPlane` 当前值。 -**返回：** `float` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::CameraComponent object; - // 根据上下文补齐参数后调用 CameraComponent::GetNearClipPlane(...)。 - (void)object; -} -``` +- 返回 `m_nearClipPlane` 当前值。 ## 相关文档 -- [返回类总览](CameraComponent.md) -- [返回模块目录](../Components.md) +- [CameraComponent](CameraComponent.md) +- [SetNearClipPlane](SetNearClipPlane.md) diff --git a/docs/api/XCEngine/Components/CameraComponent/GetOrthographicSize.md b/docs/api/XCEngine/Components/CameraComponent/GetOrthographicSize.md index ee80ed1f..8a7d1ef3 100644 --- a/docs/api/XCEngine/Components/CameraComponent/GetOrthographicSize.md +++ b/docs/api/XCEngine/Components/CameraComponent/GetOrthographicSize.md @@ -1,30 +1,26 @@ # CameraComponent::GetOrthographicSize -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/CameraComponent.h` + +## 签名 ```cpp float GetOrthographicSize() const; ``` -该方法声明于 `XCEngine/Components/CameraComponent.h`，当前页面用于固定 `CameraComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_orthographicSize` 当前值。 -**返回：** `float` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::CameraComponent object; - // 根据上下文补齐参数后调用 CameraComponent::GetOrthographicSize(...)。 - (void)object; -} -``` +- 返回 `m_orthographicSize` 当前值。 ## 相关文档 -- [返回类总览](CameraComponent.md) -- [返回模块目录](../Components.md) +- [CameraComponent](CameraComponent.md) +- [SetOrthographicSize](SetOrthographicSize.md) diff --git a/docs/api/XCEngine/Components/CameraComponent/GetProjectionType.md b/docs/api/XCEngine/Components/CameraComponent/GetProjectionType.md index 919e59e0..8d3bca99 100644 --- a/docs/api/XCEngine/Components/CameraComponent/GetProjectionType.md +++ b/docs/api/XCEngine/Components/CameraComponent/GetProjectionType.md @@ -1,30 +1,26 @@ # CameraComponent::GetProjectionType -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/CameraComponent.h` + +## 签名 ```cpp CameraProjectionType GetProjectionType() const; ``` -该方法声明于 `XCEngine/Components/CameraComponent.h`，当前页面用于固定 `CameraComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_projectionType` 当前值。 -**返回：** `CameraProjectionType` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::CameraComponent object; - // 根据上下文补齐参数后调用 CameraComponent::GetProjectionType(...)。 - (void)object; -} -``` +- 返回 `m_projectionType` 当前值。 ## 相关文档 -- [返回类总览](CameraComponent.md) -- [返回模块目录](../Components.md) +- [CameraComponent](CameraComponent.md) +- [SetProjectionType](SetProjectionType.md) diff --git a/docs/api/XCEngine/Components/CameraComponent/IsPrimary.md b/docs/api/XCEngine/Components/CameraComponent/IsPrimary.md index 2671e3df..bbc608a4 100644 --- a/docs/api/XCEngine/Components/CameraComponent/IsPrimary.md +++ b/docs/api/XCEngine/Components/CameraComponent/IsPrimary.md @@ -1,30 +1,25 @@ # CameraComponent::IsPrimary -查询当前状态。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/CameraComponent.h` + +## 签名 ```cpp bool IsPrimary() const; ``` -该方法声明于 `XCEngine/Components/CameraComponent.h`，当前页面用于固定 `CameraComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_primary` 当前值。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::CameraComponent object; - // 根据上下文补齐参数后调用 CameraComponent::IsPrimary(...)。 - (void)object; -} -``` +- 返回 `m_primary` 当前值。 ## 相关文档 -- [返回类总览](CameraComponent.md) -- [返回模块目录](../Components.md) +- [CameraComponent](CameraComponent.md) diff --git a/docs/api/XCEngine/Components/CameraComponent/Serialize.md b/docs/api/XCEngine/Components/CameraComponent/Serialize.md index 37c5d842..25b076b5 100644 --- a/docs/api/XCEngine/Components/CameraComponent/Serialize.md +++ b/docs/api/XCEngine/Components/CameraComponent/Serialize.md @@ -1,31 +1,25 @@ # CameraComponent::Serialize -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/CameraComponent.h` + +## 签名 ```cpp void Serialize(std::ostream& os) const override; ``` -该方法声明于 `XCEngine/Components/CameraComponent.h`，当前页面用于固定 `CameraComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `os` - 参数语义详见头文件声明。 +执行 `Serialize` 对应的公开操作。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::CameraComponent object; - // 根据上下文补齐参数后调用 CameraComponent::Serialize(...)。 - (void)object; -} -``` +- 具体定义位于 `engine/src/Components/CameraComponent.cpp`。 ## 相关文档 -- [返回类总览](CameraComponent.md) -- [返回模块目录](../Components.md) +- [CameraComponent](CameraComponent.md) diff --git a/docs/api/XCEngine/Components/CameraComponent/SetClearColor.md b/docs/api/XCEngine/Components/CameraComponent/SetClearColor.md index 39b1fdc9..71ab6f56 100644 --- a/docs/api/XCEngine/Components/CameraComponent/SetClearColor.md +++ b/docs/api/XCEngine/Components/CameraComponent/SetClearColor.md @@ -1,31 +1,26 @@ # CameraComponent::SetClearColor -设置相关状态或配置。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/CameraComponent.h` + +## 签名 ```cpp void SetClearColor(const Math::Color& value); ``` -该方法声明于 `XCEngine/Components/CameraComponent.h`，当前页面用于固定 `CameraComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `value` - 参数语义详见头文件声明。 +更新 `m_clearColor`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::CameraComponent object; - // 根据上下文补齐参数后调用 CameraComponent::SetClearColor(...)。 - (void)object; -} -``` +- 会更新 `m_clearColor`。 ## 相关文档 -- [返回类总览](CameraComponent.md) -- [返回模块目录](../Components.md) +- [CameraComponent](CameraComponent.md) +- [GetClearColor](GetClearColor.md) diff --git a/docs/api/XCEngine/Components/CameraComponent/SetDepth.md b/docs/api/XCEngine/Components/CameraComponent/SetDepth.md index 6fd837f6..6e390670 100644 --- a/docs/api/XCEngine/Components/CameraComponent/SetDepth.md +++ b/docs/api/XCEngine/Components/CameraComponent/SetDepth.md @@ -1,31 +1,26 @@ # CameraComponent::SetDepth -设置相关状态或配置。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/CameraComponent.h` + +## 签名 ```cpp void SetDepth(float value); ``` -该方法声明于 `XCEngine/Components/CameraComponent.h`，当前页面用于固定 `CameraComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `value` - 参数语义详见头文件声明。 +更新 `m_depth`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::CameraComponent object; - // 根据上下文补齐参数后调用 CameraComponent::SetDepth(...)。 - (void)object; -} -``` +- 会更新 `m_depth`。 ## 相关文档 -- [返回类总览](CameraComponent.md) -- [返回模块目录](../Components.md) +- [CameraComponent](CameraComponent.md) +- [GetDepth](GetDepth.md) diff --git a/docs/api/XCEngine/Components/CameraComponent/SetFarClipPlane.md b/docs/api/XCEngine/Components/CameraComponent/SetFarClipPlane.md index d4b52bc9..114a6c59 100644 --- a/docs/api/XCEngine/Components/CameraComponent/SetFarClipPlane.md +++ b/docs/api/XCEngine/Components/CameraComponent/SetFarClipPlane.md @@ -1,31 +1,27 @@ # CameraComponent::SetFarClipPlane -设置相关状态或配置。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/CameraComponent.h` + +## 签名 ```cpp void SetFarClipPlane(float value); ``` -该方法声明于 `XCEngine/Components/CameraComponent.h`，当前页面用于固定 `CameraComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `value` - 参数语义详见头文件声明。 +更新 `m_farClipPlane`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::CameraComponent object; - // 根据上下文补齐参数后调用 CameraComponent::SetFarClipPlane(...)。 - (void)object; -} -``` +- 会更新 `m_farClipPlane`。 +- 当前实现会调用 `max`。 ## 相关文档 -- [返回类总览](CameraComponent.md) -- [返回模块目录](../Components.md) +- [CameraComponent](CameraComponent.md) +- [GetFarClipPlane](GetFarClipPlane.md) diff --git a/docs/api/XCEngine/Components/CameraComponent/SetFieldOfView.md b/docs/api/XCEngine/Components/CameraComponent/SetFieldOfView.md index a836fcad..c680feac 100644 --- a/docs/api/XCEngine/Components/CameraComponent/SetFieldOfView.md +++ b/docs/api/XCEngine/Components/CameraComponent/SetFieldOfView.md @@ -1,31 +1,27 @@ # CameraComponent::SetFieldOfView -设置相关状态或配置。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/CameraComponent.h` + +## 签名 ```cpp void SetFieldOfView(float value); ``` -该方法声明于 `XCEngine/Components/CameraComponent.h`，当前页面用于固定 `CameraComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `value` - 参数语义详见头文件声明。 +更新 `m_fieldOfView`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::CameraComponent object; - // 根据上下文补齐参数后调用 CameraComponent::SetFieldOfView(...)。 - (void)object; -} -``` +- 会更新 `m_fieldOfView`。 +- 当前实现会调用 `clamp`。 ## 相关文档 -- [返回类总览](CameraComponent.md) -- [返回模块目录](../Components.md) +- [CameraComponent](CameraComponent.md) +- [GetFieldOfView](GetFieldOfView.md) diff --git a/docs/api/XCEngine/Components/CameraComponent/SetNearClipPlane.md b/docs/api/XCEngine/Components/CameraComponent/SetNearClipPlane.md index 27244e15..01be0422 100644 --- a/docs/api/XCEngine/Components/CameraComponent/SetNearClipPlane.md +++ b/docs/api/XCEngine/Components/CameraComponent/SetNearClipPlane.md @@ -1,31 +1,27 @@ # CameraComponent::SetNearClipPlane -设置相关状态或配置。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/CameraComponent.h` + +## 签名 ```cpp void SetNearClipPlane(float value); ``` -该方法声明于 `XCEngine/Components/CameraComponent.h`，当前页面用于固定 `CameraComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `value` - 参数语义详见头文件声明。 +执行 `max(...)` 相关流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::CameraComponent object; - // 根据上下文补齐参数后调用 CameraComponent::SetNearClipPlane(...)。 - (void)object; -} -``` +- 会更新 `m_nearClipPlane`、`m_farClipPlane`。 +- 当前实现会调用 `max`。 ## 相关文档 -- [返回类总览](CameraComponent.md) -- [返回模块目录](../Components.md) +- [CameraComponent](CameraComponent.md) +- [GetNearClipPlane](GetNearClipPlane.md) diff --git a/docs/api/XCEngine/Components/CameraComponent/SetOrthographicSize.md b/docs/api/XCEngine/Components/CameraComponent/SetOrthographicSize.md index 59aecf9e..8724619c 100644 --- a/docs/api/XCEngine/Components/CameraComponent/SetOrthographicSize.md +++ b/docs/api/XCEngine/Components/CameraComponent/SetOrthographicSize.md @@ -1,31 +1,27 @@ # CameraComponent::SetOrthographicSize -设置相关状态或配置。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/CameraComponent.h` + +## 签名 ```cpp void SetOrthographicSize(float value); ``` -该方法声明于 `XCEngine/Components/CameraComponent.h`，当前页面用于固定 `CameraComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `value` - 参数语义详见头文件声明。 +更新 `m_orthographicSize`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::CameraComponent object; - // 根据上下文补齐参数后调用 CameraComponent::SetOrthographicSize(...)。 - (void)object; -} -``` +- 会更新 `m_orthographicSize`。 +- 当前实现会调用 `max`。 ## 相关文档 -- [返回类总览](CameraComponent.md) -- [返回模块目录](../Components.md) +- [CameraComponent](CameraComponent.md) +- [GetOrthographicSize](GetOrthographicSize.md) diff --git a/docs/api/XCEngine/Components/CameraComponent/SetPrimary.md b/docs/api/XCEngine/Components/CameraComponent/SetPrimary.md index 135e188e..62d54859 100644 --- a/docs/api/XCEngine/Components/CameraComponent/SetPrimary.md +++ b/docs/api/XCEngine/Components/CameraComponent/SetPrimary.md @@ -1,31 +1,25 @@ # CameraComponent::SetPrimary -设置相关状态或配置。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/CameraComponent.h` + +## 签名 ```cpp void SetPrimary(bool value); ``` -该方法声明于 `XCEngine/Components/CameraComponent.h`，当前页面用于固定 `CameraComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `value` - 参数语义详见头文件声明。 +更新 `m_primary`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::CameraComponent object; - // 根据上下文补齐参数后调用 CameraComponent::SetPrimary(...)。 - (void)object; -} -``` +- 会更新 `m_primary`。 ## 相关文档 -- [返回类总览](CameraComponent.md) -- [返回模块目录](../Components.md) +- [CameraComponent](CameraComponent.md) diff --git a/docs/api/XCEngine/Components/CameraComponent/SetProjectionType.md b/docs/api/XCEngine/Components/CameraComponent/SetProjectionType.md index f4bde4ab..170a27ec 100644 --- a/docs/api/XCEngine/Components/CameraComponent/SetProjectionType.md +++ b/docs/api/XCEngine/Components/CameraComponent/SetProjectionType.md @@ -1,31 +1,26 @@ # CameraComponent::SetProjectionType -设置相关状态或配置。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/CameraComponent.h` + +## 签名 ```cpp void SetProjectionType(CameraProjectionType type); ``` -该方法声明于 `XCEngine/Components/CameraComponent.h`，当前页面用于固定 `CameraComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `type` - 参数语义详见头文件声明。 +更新 `m_projectionType`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::CameraComponent object; - // 根据上下文补齐参数后调用 CameraComponent::SetProjectionType(...)。 - (void)object; -} -``` +- 会更新 `m_projectionType`。 ## 相关文档 -- [返回类总览](CameraComponent.md) -- [返回模块目录](../Components.md) +- [CameraComponent](CameraComponent.md) +- [GetProjectionType](GetProjectionType.md) diff --git a/docs/api/XCEngine/Components/Component/Awake.md b/docs/api/XCEngine/Components/Component/Awake.md index 24328632..f7e26e99 100644 --- a/docs/api/XCEngine/Components/Component/Awake.md +++ b/docs/api/XCEngine/Components/Component/Awake.md @@ -1,30 +1,25 @@ # Component::Awake -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/Component.h` + +## 签名 ```cpp virtual void Awake(); ``` -该方法声明于 `XCEngine/Components/Component.h`，当前页面用于固定 `Component` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +当前实现为空。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::Component object; - // 根据上下文补齐参数后调用 Component::Awake(...)。 - (void)object; -} -``` +- 当前函数体为空。 ## 相关文档 -- [返回类总览](Component.md) -- [返回模块目录](../Components.md) +- [Component](Component.md) diff --git a/docs/api/XCEngine/Components/Component/Deserialize.md b/docs/api/XCEngine/Components/Component/Deserialize.md index 8b53cfc0..7a7a0400 100644 --- a/docs/api/XCEngine/Components/Component/Deserialize.md +++ b/docs/api/XCEngine/Components/Component/Deserialize.md @@ -1,31 +1,25 @@ # Component::Deserialize -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/Component.h` + +## 签名 ```cpp virtual void Deserialize(std::istream& is); ``` -该方法声明于 `XCEngine/Components/Component.h`，当前页面用于固定 `Component` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `is` - 参数语义详见头文件声明。 +当前实现为空。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::Component object; - // 根据上下文补齐参数后调用 Component::Deserialize(...)。 - (void)object; -} -``` +- 当前函数体为空。 ## 相关文档 -- [返回类总览](Component.md) -- [返回模块目录](../Components.md) +- [Component](Component.md) diff --git a/docs/api/XCEngine/Components/Component/Destructor.md b/docs/api/XCEngine/Components/Component/Destructor.md index c6b91952..85b31cef 100644 --- a/docs/api/XCEngine/Components/Component/Destructor.md +++ b/docs/api/XCEngine/Components/Component/Destructor.md @@ -1,29 +1,25 @@ # Component::~Component() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/Component.h` + +## 签名 ```cpp virtual ~Component() = default; ``` -该方法声明于 `XCEngine/Components/Component.h`，当前页面用于固定 `Component` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +销毁 `Component` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::Component object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 当前为默认析构实现。 ## 相关文档 -- [返回类总览](Component.md) -- [返回模块目录](../Components.md) +- [Component](Component.md) diff --git a/docs/api/XCEngine/Components/Component/FixedUpdate.md b/docs/api/XCEngine/Components/Component/FixedUpdate.md index 15acd69e..1d61a404 100644 --- a/docs/api/XCEngine/Components/Component/FixedUpdate.md +++ b/docs/api/XCEngine/Components/Component/FixedUpdate.md @@ -1,30 +1,25 @@ # Component::FixedUpdate -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/Component.h` + +## 签名 ```cpp virtual void FixedUpdate(); ``` -该方法声明于 `XCEngine/Components/Component.h`，当前页面用于固定 `Component` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +当前实现为空。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::Component object; - // 根据上下文补齐参数后调用 Component::FixedUpdate(...)。 - (void)object; -} -``` +- 当前函数体为空。 ## 相关文档 -- [返回类总览](Component.md) -- [返回模块目录](../Components.md) +- [Component](Component.md) diff --git a/docs/api/XCEngine/Components/Component/GetGameObject.md b/docs/api/XCEngine/Components/Component/GetGameObject.md index e2fba288..870d414d 100644 --- a/docs/api/XCEngine/Components/Component/GetGameObject.md +++ b/docs/api/XCEngine/Components/Component/GetGameObject.md @@ -1,30 +1,25 @@ # Component::GetGameObject -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/Component.h` + +## 签名 ```cpp GameObject* GetGameObject() const; ``` -该方法声明于 `XCEngine/Components/Component.h`，当前页面用于固定 `Component` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_gameObject` 当前值。 -**返回：** `GameObject*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::Component object; - // 根据上下文补齐参数后调用 Component::GetGameObject(...)。 - (void)object; -} -``` +- 返回 `m_gameObject` 当前值。 ## 相关文档 -- [返回类总览](Component.md) -- [返回模块目录](../Components.md) +- [Component](Component.md) diff --git a/docs/api/XCEngine/Components/Component/GetName.md b/docs/api/XCEngine/Components/Component/GetName.md index fa1e8d69..61139b28 100644 --- a/docs/api/XCEngine/Components/Component/GetName.md +++ b/docs/api/XCEngine/Components/Component/GetName.md @@ -1,30 +1,25 @@ # Component::GetName -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/Component.h` + +## 签名 ```cpp virtual std::string GetName() const = 0; ``` -该方法声明于 `XCEngine/Components/Component.h`，当前页面用于固定 `Component` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `std::string` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::Component object; - // 根据上下文补齐参数后调用 Component::GetName(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](Component.md) -- [返回模块目录](../Components.md) +- [Component](Component.md) diff --git a/docs/api/XCEngine/Components/Component/GetScene.md b/docs/api/XCEngine/Components/Component/GetScene.md index d7521e64..df0e53af 100644 --- a/docs/api/XCEngine/Components/Component/GetScene.md +++ b/docs/api/XCEngine/Components/Component/GetScene.md @@ -1,30 +1,26 @@ # Component::GetScene -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/Component.h` + +## 签名 ```cpp Scene* GetScene() const; ``` -该方法声明于 `XCEngine/Components/Component.h`，当前页面用于固定 `Component` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_gameObject ? m_gameObject->GetScene() : nullptr`。 -**返回：** `Scene*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::Component object; - // 根据上下文补齐参数后调用 Component::GetScene(...)。 - (void)object; -} -``` +- 当前实现会调用 `GetScene`。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](Component.md) -- [返回模块目录](../Components.md) +- [Component](Component.md) diff --git a/docs/api/XCEngine/Components/Component/IsEnabled.md b/docs/api/XCEngine/Components/Component/IsEnabled.md index e691c3b5..cfaa124d 100644 --- a/docs/api/XCEngine/Components/Component/IsEnabled.md +++ b/docs/api/XCEngine/Components/Component/IsEnabled.md @@ -1,30 +1,25 @@ # Component::IsEnabled -查询当前状态。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/Component.h` + +## 签名 ```cpp bool IsEnabled() const; ``` -该方法声明于 `XCEngine/Components/Component.h`，当前页面用于固定 `Component` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_enabled` 当前值。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::Component object; - // 根据上下文补齐参数后调用 Component::IsEnabled(...)。 - (void)object; -} -``` +- 返回 `m_enabled` 当前值。 ## 相关文档 -- [返回类总览](Component.md) -- [返回模块目录](../Components.md) +- [Component](Component.md) diff --git a/docs/api/XCEngine/Components/Component/LateUpdate.md b/docs/api/XCEngine/Components/Component/LateUpdate.md index 2402ca09..3729cd72 100644 --- a/docs/api/XCEngine/Components/Component/LateUpdate.md +++ b/docs/api/XCEngine/Components/Component/LateUpdate.md @@ -1,31 +1,25 @@ # Component::LateUpdate -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/Component.h` + +## 签名 ```cpp virtual void LateUpdate(float deltaTime); ``` -该方法声明于 `XCEngine/Components/Component.h`，当前页面用于固定 `Component` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `deltaTime` - 参数语义详见头文件声明。 +当前实现为空。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::Component object; - // 根据上下文补齐参数后调用 Component::LateUpdate(...)。 - (void)object; -} -``` +- 当前函数体为空。 ## 相关文档 -- [返回类总览](Component.md) -- [返回模块目录](../Components.md) +- [Component](Component.md) diff --git a/docs/api/XCEngine/Components/Component/OnDestroy.md b/docs/api/XCEngine/Components/Component/OnDestroy.md index 4b5333d7..a1f329b9 100644 --- a/docs/api/XCEngine/Components/Component/OnDestroy.md +++ b/docs/api/XCEngine/Components/Component/OnDestroy.md @@ -1,30 +1,25 @@ # Component::OnDestroy -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/Component.h` + +## 签名 ```cpp virtual void OnDestroy(); ``` -该方法声明于 `XCEngine/Components/Component.h`，当前页面用于固定 `Component` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +当前实现为空。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::Component object; - // 根据上下文补齐参数后调用 Component::OnDestroy(...)。 - (void)object; -} -``` +- 当前函数体为空。 ## 相关文档 -- [返回类总览](Component.md) -- [返回模块目录](../Components.md) +- [Component](Component.md) diff --git a/docs/api/XCEngine/Components/Component/OnDisable.md b/docs/api/XCEngine/Components/Component/OnDisable.md index 6a1e8301..4f772c2f 100644 --- a/docs/api/XCEngine/Components/Component/OnDisable.md +++ b/docs/api/XCEngine/Components/Component/OnDisable.md @@ -1,30 +1,25 @@ # Component::OnDisable -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/Component.h` + +## 签名 ```cpp virtual void OnDisable(); ``` -该方法声明于 `XCEngine/Components/Component.h`，当前页面用于固定 `Component` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +当前实现为空。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::Component object; - // 根据上下文补齐参数后调用 Component::OnDisable(...)。 - (void)object; -} -``` +- 当前函数体为空。 ## 相关文档 -- [返回类总览](Component.md) -- [返回模块目录](../Components.md) +- [Component](Component.md) diff --git a/docs/api/XCEngine/Components/Component/OnEnable.md b/docs/api/XCEngine/Components/Component/OnEnable.md index f5765c9b..18261be3 100644 --- a/docs/api/XCEngine/Components/Component/OnEnable.md +++ b/docs/api/XCEngine/Components/Component/OnEnable.md @@ -1,30 +1,25 @@ # Component::OnEnable -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/Component.h` + +## 签名 ```cpp virtual void OnEnable(); ``` -该方法声明于 `XCEngine/Components/Component.h`，当前页面用于固定 `Component` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +当前实现为空。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::Component object; - // 根据上下文补齐参数后调用 Component::OnEnable(...)。 - (void)object; -} -``` +- 当前函数体为空。 ## 相关文档 -- [返回类总览](Component.md) -- [返回模块目录](../Components.md) +- [Component](Component.md) diff --git a/docs/api/XCEngine/Components/Component/Serialize.md b/docs/api/XCEngine/Components/Component/Serialize.md index c1fc78bc..9ca04600 100644 --- a/docs/api/XCEngine/Components/Component/Serialize.md +++ b/docs/api/XCEngine/Components/Component/Serialize.md @@ -1,31 +1,25 @@ # Component::Serialize -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/Component.h` + +## 签名 ```cpp virtual void Serialize(std::ostream& os) const; ``` -该方法声明于 `XCEngine/Components/Component.h`，当前页面用于固定 `Component` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `os` - 参数语义详见头文件声明。 +执行 `Serialize` 对应的公开操作。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::Component object; - // 根据上下文补齐参数后调用 Component::Serialize(...)。 - (void)object; -} -``` +- 具体定义位于 `engine/src/Components/Component.cpp`。 ## 相关文档 -- [返回类总览](Component.md) -- [返回模块目录](../Components.md) +- [Component](Component.md) diff --git a/docs/api/XCEngine/Components/Component/SetEnabled.md b/docs/api/XCEngine/Components/Component/SetEnabled.md index a4c031e5..a8465697 100644 --- a/docs/api/XCEngine/Components/Component/SetEnabled.md +++ b/docs/api/XCEngine/Components/Component/SetEnabled.md @@ -1,31 +1,26 @@ # Component::SetEnabled -设置相关状态或配置。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/Component.h` + +## 签名 ```cpp void SetEnabled(bool enabled); ``` -该方法声明于 `XCEngine/Components/Component.h`，当前页面用于固定 `Component` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `enabled` - 参数语义详见头文件声明。 +更新 `m_enabled`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::Component object; - // 根据上下文补齐参数后调用 Component::SetEnabled(...)。 - (void)object; -} -``` +- 会更新 `m_enabled`。 +- 当前实现会调用 `IsActiveInHierarchy`、`OnEnable`、`OnDisable`。 ## 相关文档 -- [返回类总览](Component.md) -- [返回模块目录](../Components.md) +- [Component](Component.md) diff --git a/docs/api/XCEngine/Components/Component/Start.md b/docs/api/XCEngine/Components/Component/Start.md index 0552db2e..253c3749 100644 --- a/docs/api/XCEngine/Components/Component/Start.md +++ b/docs/api/XCEngine/Components/Component/Start.md @@ -1,30 +1,25 @@ # Component::Start -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/Component.h` + +## 签名 ```cpp virtual void Start(); ``` -该方法声明于 `XCEngine/Components/Component.h`，当前页面用于固定 `Component` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +当前实现为空。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::Component object; - // 根据上下文补齐参数后调用 Component::Start(...)。 - (void)object; -} -``` +- 当前函数体为空。 ## 相关文档 -- [返回类总览](Component.md) -- [返回模块目录](../Components.md) +- [Component](Component.md) diff --git a/docs/api/XCEngine/Components/Component/Update.md b/docs/api/XCEngine/Components/Component/Update.md index 56525d95..0ad1e02d 100644 --- a/docs/api/XCEngine/Components/Component/Update.md +++ b/docs/api/XCEngine/Components/Component/Update.md @@ -1,31 +1,25 @@ # Component::Update -更新运行时状态。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/Component.h` + +## 签名 ```cpp virtual void Update(float deltaTime); ``` -该方法声明于 `XCEngine/Components/Component.h`，当前页面用于固定 `Component` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `deltaTime` - 参数语义详见头文件声明。 +当前实现为空。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::Component object; - // 根据上下文补齐参数后调用 Component::Update(...)。 - (void)object; -} -``` +- 当前函数体为空。 ## 相关文档 -- [返回类总览](Component.md) -- [返回模块目录](../Components.md) +- [Component](Component.md) diff --git a/docs/api/XCEngine/Components/Component/transform.md b/docs/api/XCEngine/Components/Component/transform.md index 2320adb8..e9850888 100644 --- a/docs/api/XCEngine/Components/Component/transform.md +++ b/docs/api/XCEngine/Components/Component/transform.md @@ -1,30 +1,25 @@ # Component::transform -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/Component.h` + +## 签名 ```cpp TransformComponent& transform() const; ``` -该方法声明于 `XCEngine/Components/Component.h`，当前页面用于固定 `Component` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `transform` 对应的公开操作。 -**返回：** `TransformComponent&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::Component object; - // 根据上下文补齐参数后调用 Component::transform(...)。 - (void)object; -} -``` +- 具体定义位于 `engine/src/Components/Component.cpp`。 ## 相关文档 -- [返回类总览](Component.md) -- [返回模块目录](../Components.md) +- [Component](Component.md) diff --git a/docs/api/XCEngine/Components/ComponentFactoryRegistry/CreateComponent.md b/docs/api/XCEngine/Components/ComponentFactoryRegistry/CreateComponent.md index 9e595a76..5c338ba0 100644 --- a/docs/api/XCEngine/Components/ComponentFactoryRegistry/CreateComponent.md +++ b/docs/api/XCEngine/Components/ComponentFactoryRegistry/CreateComponent.md @@ -1,32 +1,25 @@ # ComponentFactoryRegistry::CreateComponent -创建新对象或资源。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/ComponentFactoryRegistry.h` + +## 签名 ```cpp Component* CreateComponent(GameObject* gameObject, const std::string& typeName) const; ``` -该方法声明于 `XCEngine/Components/ComponentFactoryRegistry.h`，当前页面用于固定 `ComponentFactoryRegistry` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `gameObject` - 参数语义详见头文件声明。 -- `typeName` - 参数语义详见头文件声明。 +执行 `CreateComponent` 创建流程。 -**返回：** `Component*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::ComponentFactoryRegistry object; - // 根据上下文补齐参数后调用 ComponentFactoryRegistry::CreateComponent(...)。 - (void)object; -} -``` +- 具体定义位于 `engine/src/Components/ComponentFactoryRegistry.cpp`。 ## 相关文档 -- [返回类总览](ComponentFactoryRegistry.md) -- [返回模块目录](../Components.md) +- [ComponentFactoryRegistry](ComponentFactoryRegistry.md) diff --git a/docs/api/XCEngine/Components/ComponentFactoryRegistry/Get.md b/docs/api/XCEngine/Components/ComponentFactoryRegistry/Get.md index 0653594e..80b029d0 100644 --- a/docs/api/XCEngine/Components/ComponentFactoryRegistry/Get.md +++ b/docs/api/XCEngine/Components/ComponentFactoryRegistry/Get.md @@ -1,29 +1,25 @@ # ComponentFactoryRegistry::Get -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/ComponentFactoryRegistry.h` + +## 签名 ```cpp static ComponentFactoryRegistry& Get(); ``` -该方法声明于 `XCEngine/Components/ComponentFactoryRegistry.h`，当前页面用于固定 `ComponentFactoryRegistry` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `registry`。 -**返回：** `ComponentFactoryRegistry&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - auto& instance = XCEngine::Components::ComponentFactoryRegistry::Get(); - (void)instance; -} -``` +- 返回 `registry`。 ## 相关文档 -- [返回类总览](ComponentFactoryRegistry.md) -- [返回模块目录](../Components.md) +- [ComponentFactoryRegistry](ComponentFactoryRegistry.md) diff --git a/docs/api/XCEngine/Components/ComponentFactoryRegistry/GetRegisteredTypes.md b/docs/api/XCEngine/Components/ComponentFactoryRegistry/GetRegisteredTypes.md index 824edfd1..24d36f86 100644 --- a/docs/api/XCEngine/Components/ComponentFactoryRegistry/GetRegisteredTypes.md +++ b/docs/api/XCEngine/Components/ComponentFactoryRegistry/GetRegisteredTypes.md @@ -1,30 +1,25 @@ # ComponentFactoryRegistry::GetRegisteredTypes -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/ComponentFactoryRegistry.h` + +## 签名 ```cpp const std::vector& GetRegisteredTypes() const; ``` -该方法声明于 `XCEngine/Components/ComponentFactoryRegistry.h`，当前页面用于固定 `ComponentFactoryRegistry` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_registrationOrder` 当前值。 -**返回：** `const std::vector&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::ComponentFactoryRegistry object; - // 根据上下文补齐参数后调用 ComponentFactoryRegistry::GetRegisteredTypes(...)。 - (void)object; -} -``` +- 返回 `m_registrationOrder` 当前值。 ## 相关文档 -- [返回类总览](ComponentFactoryRegistry.md) -- [返回模块目录](../Components.md) +- [ComponentFactoryRegistry](ComponentFactoryRegistry.md) diff --git a/docs/api/XCEngine/Components/ComponentFactoryRegistry/IsRegistered.md b/docs/api/XCEngine/Components/ComponentFactoryRegistry/IsRegistered.md index a3a2011f..2b476fb1 100644 --- a/docs/api/XCEngine/Components/ComponentFactoryRegistry/IsRegistered.md +++ b/docs/api/XCEngine/Components/ComponentFactoryRegistry/IsRegistered.md @@ -1,31 +1,26 @@ # ComponentFactoryRegistry::IsRegistered -查询当前状态。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/ComponentFactoryRegistry.h` + +## 签名 ```cpp bool IsRegistered(const std::string& typeName) const; ``` -该方法声明于 `XCEngine/Components/ComponentFactoryRegistry.h`，当前页面用于固定 `ComponentFactoryRegistry` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `typeName` - 参数语义详见头文件声明。 +更新 `m_factories`。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::ComponentFactoryRegistry object; - // 根据上下文补齐参数后调用 ComponentFactoryRegistry::IsRegistered(...)。 - (void)object; -} -``` +- 会更新 `m_factories`。 +- 当前实现会调用 `find`、`end`。 ## 相关文档 -- [返回类总览](ComponentFactoryRegistry.md) -- [返回模块目录](../Components.md) +- [ComponentFactoryRegistry](ComponentFactoryRegistry.md) diff --git a/docs/api/XCEngine/Components/ComponentFactoryRegistry/RegisterFactory.md b/docs/api/XCEngine/Components/ComponentFactoryRegistry/RegisterFactory.md index c923f0b5..9aab82ca 100644 --- a/docs/api/XCEngine/Components/ComponentFactoryRegistry/RegisterFactory.md +++ b/docs/api/XCEngine/Components/ComponentFactoryRegistry/RegisterFactory.md @@ -1,32 +1,25 @@ # ComponentFactoryRegistry::RegisterFactory -注册对象、回调或映射。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/ComponentFactoryRegistry.h` + +## 签名 ```cpp void RegisterFactory(const std::string& typeName, CreateComponentFn createFn); ``` -该方法声明于 `XCEngine/Components/ComponentFactoryRegistry.h`，当前页面用于固定 `ComponentFactoryRegistry` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `typeName` - 参数语义详见头文件声明。 -- `createFn` - 参数语义详见头文件声明。 +执行 `empty`、`insert_or_assign`、`push_back` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::ComponentFactoryRegistry object; - // 根据上下文补齐参数后调用 ComponentFactoryRegistry::RegisterFactory(...)。 - (void)object; -} -``` +- 当前实现会调用 `empty`、`insert_or_assign`、`push_back`。 ## 相关文档 -- [返回类总览](ComponentFactoryRegistry.md) -- [返回模块目录](../Components.md) +- [ComponentFactoryRegistry](ComponentFactoryRegistry.md) diff --git a/docs/api/XCEngine/Components/Components.md b/docs/api/XCEngine/Components/Components.md index 950c2716..2e6af239 100644 --- a/docs/api/XCEngine/Components/Components.md +++ b/docs/api/XCEngine/Components/Components.md @@ -23,6 +23,7 @@ - 生命周期由 `GameObject` 和 `Scene` 驱动，运行时直接 `AddComponent()` 并不会自动补发 `Awake`、`Start` 或 `OnEnable`。 - 序列化职责分层：`GameObject::Serialize()` 只写对象基础字段和 `Transform`，完整场景保存由 `Scene::SerializeToString()` 负责组件和父子关系。 - `ComponentFactoryRegistry` 只负责把序列化文本里的组件类型名还原为内建组件实例，`Transform` 不走这条路径。 +- 渲染组件链路当前是显式拆分的：`MeshFilterComponent` 负责 mesh 的运行时路径缓存、项目 `AssetRef` 与句柄绑定，`MeshRendererComponent` 负责材质槽的运行时路径缓存、项目 `AssetRef`、句柄以及渲染附加状态；对项目资产来说，正式持久化协议都优先是 `AssetRef`，而不是普通项目路径。 ## 适用场景 @@ -36,6 +37,8 @@ - 静态查找接口 `GameObject::Find()`、`FindObjectsOfType()`、`FindGameObjectsWithTag()` 只会看到已注册到全局表的对象；普通 `GameObject` 直接构造后并不会自动注册。 - `FindGameObjectsWithTag()` 当前按对象名称比较，不是真正的 tag 系统。 - 某些组件已经具备基础运行时行为，但序列化覆盖并不完整，例如音频组件当前没有自定义 `Serialize()`/`Deserialize()`。 +- `MeshFilterComponent` 在 deferred scene load 模式下会先按 `AssetRef` 恢复身份，并在可解析时补出路径缓存；真正的 mesh 句柄通常要到首次访问时才异步兑现，因此“组件存在”不等于“这一帧已经有可绘制网格”。 +- `MeshRendererComponent` 也会先恢复槽位的 `AssetRef` 与必要的路径缓存；普通项目路径不会作为长期持久化协议单独存活，只有 virtual scheme 路径才会稳定保留在 `materialPaths` 中。 - 一些 API 名义上接近 Unity 对应物，但当前实现能力更轻量，不能直接按“完整 Unity 行为”等同理解。 ## 头文件 @@ -47,7 +50,7 @@ - [ComponentFactoryRegistry](ComponentFactoryRegistry/ComponentFactoryRegistry.md) - `ComponentFactoryRegistry.h`，场景反序列化时的组件工厂注册表。 - [GameObject](GameObject/GameObject.md) - `GameObject.h`，对象身份、层级和生命周期分发中心。 - [LightComponent](LightComponent/LightComponent.md) - `LightComponent.h`，基础灯光参数。 -- [MeshFilterComponent](MeshFilterComponent/MeshFilterComponent.md) - `MeshFilterComponent.h`，网格资源引用。 +- [MeshFilterComponent](MeshFilterComponent/MeshFilterComponent.md) - `MeshFilterComponent.h`，mesh 资源绑定、序列化路径和资产引用恢复。 - [MeshRendererComponent](MeshRendererComponent/MeshRendererComponent.md) - `MeshRendererComponent.h`，材质槽和渲染附加参数。 - [TransformComponent](TransformComponent/TransformComponent.md) - `TransformComponent.h`，局部/世界变换与层级矩阵。 @@ -55,7 +58,8 @@ 1. 先读 [GameObject-Component Lifecycle And Serialization](../../_guides/Components/GameObject-Component-Lifecycle-And-Serialization.md)，建立整体心智模型。 2. 再读 [GameObject](GameObject/GameObject.md) 和 [TransformComponent](TransformComponent/TransformComponent.md)，理解对象树和变换树的关系。 -3. 最后按功能阅读具体组件页，例如 [CameraComponent](CameraComponent/CameraComponent.md)、[MeshRendererComponent](MeshRendererComponent/MeshRendererComponent.md)、[AudioSourceComponent](AudioSourceComponent/AudioSourceComponent.md)。 +3. 如果关注渲染资源绑定，再读 [MeshFilterComponent](MeshFilterComponent/MeshFilterComponent.md) 和 [MeshRendererComponent](MeshRendererComponent/MeshRendererComponent.md)，理解几何、材质和渲染提取之间的分工。 +4. 最后按功能阅读其余组件页，例如 [CameraComponent](CameraComponent/CameraComponent.md)、[AudioSourceComponent](AudioSourceComponent/AudioSourceComponent.md)。 ## 相关文档 diff --git a/docs/api/XCEngine/Components/GameObject/GameObject.md b/docs/api/XCEngine/Components/GameObject/GameObject.md index c4c41399..c6b475aa 100644 --- a/docs/api/XCEngine/Components/GameObject/GameObject.md +++ b/docs/api/XCEngine/Components/GameObject/GameObject.md @@ -189,7 +189,7 @@ Mono 运行时当前已经把这些元数据直接暴露给 C#： - `Component.Layer` / `Component.layer` - `CompareTag(...)` -这些接口不是副本，而是直接读写同一份原生字段。`tests/scripting/test_mono_script_runtime.cpp` 中的 `GameObjectTagAndLayerApiExposeUnityStylePropertiesAndCompareTag` 明确验证了： +这些接口不是副本，而是直接读写同一份原生字段。`tests/Scripting/test_mono_script_runtime.cpp` 中的 `GameObjectTagAndLayerApiExposeUnityStylePropertiesAndCompareTag` 明确验证了： - 托管脚本能读到原生已有的 tag / layer - 托管脚本写回 `"Player"` 和 `31` 后，原生对象会立即更新 diff --git a/docs/api/XCEngine/Components/LightComponent/Deserialize.md b/docs/api/XCEngine/Components/LightComponent/Deserialize.md index 4dd7ff5a..77858f8f 100644 --- a/docs/api/XCEngine/Components/LightComponent/Deserialize.md +++ b/docs/api/XCEngine/Components/LightComponent/Deserialize.md @@ -1,31 +1,26 @@ # LightComponent::Deserialize -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/LightComponent.h` + +## 签名 ```cpp void Deserialize(std::istream& is) override; ``` -该方法声明于 `XCEngine/Components/LightComponent.h`，当前页面用于固定 `LightComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `is` - 参数语义详见头文件声明。 +执行 `getline`、`empty`、`find` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::LightComponent object; - // 根据上下文补齐参数后调用 LightComponent::Deserialize(...)。 - (void)object; -} -``` +- 会更新 `m_lightType`、`m_castsShadows`。 +- 当前实现会调用 `getline`、`empty`、`find`、`substr`。 ## 相关文档 -- [返回类总览](LightComponent.md) -- [返回模块目录](../Components.md) +- [LightComponent](LightComponent.md) diff --git a/docs/api/XCEngine/Components/LightComponent/GetCastsShadows.md b/docs/api/XCEngine/Components/LightComponent/GetCastsShadows.md index bd74b986..65ad4184 100644 --- a/docs/api/XCEngine/Components/LightComponent/GetCastsShadows.md +++ b/docs/api/XCEngine/Components/LightComponent/GetCastsShadows.md @@ -1,30 +1,26 @@ # LightComponent::GetCastsShadows -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/LightComponent.h` + +## 签名 ```cpp bool GetCastsShadows() const; ``` -该方法声明于 `XCEngine/Components/LightComponent.h`，当前页面用于固定 `LightComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_castsShadows` 当前值。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::LightComponent object; - // 根据上下文补齐参数后调用 LightComponent::GetCastsShadows(...)。 - (void)object; -} -``` +- 返回 `m_castsShadows` 当前值。 ## 相关文档 -- [返回类总览](LightComponent.md) -- [返回模块目录](../Components.md) +- [LightComponent](LightComponent.md) +- [SetCastsShadows](SetCastsShadows.md) diff --git a/docs/api/XCEngine/Components/LightComponent/GetColor.md b/docs/api/XCEngine/Components/LightComponent/GetColor.md index 5803e391..f789d30f 100644 --- a/docs/api/XCEngine/Components/LightComponent/GetColor.md +++ b/docs/api/XCEngine/Components/LightComponent/GetColor.md @@ -1,30 +1,26 @@ # LightComponent::GetColor -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/LightComponent.h` + +## 签名 ```cpp const Math::Color& GetColor() const; ``` -该方法声明于 `XCEngine/Components/LightComponent.h`，当前页面用于固定 `LightComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_color` 当前值。 -**返回：** `const Math::Color&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::LightComponent object; - // 根据上下文补齐参数后调用 LightComponent::GetColor(...)。 - (void)object; -} -``` +- 返回 `m_color` 当前值。 ## 相关文档 -- [返回类总览](LightComponent.md) -- [返回模块目录](../Components.md) +- [LightComponent](LightComponent.md) +- [SetColor](SetColor.md) diff --git a/docs/api/XCEngine/Components/LightComponent/GetIntensity.md b/docs/api/XCEngine/Components/LightComponent/GetIntensity.md index 4d7ae9d8..3a268303 100644 --- a/docs/api/XCEngine/Components/LightComponent/GetIntensity.md +++ b/docs/api/XCEngine/Components/LightComponent/GetIntensity.md @@ -1,30 +1,26 @@ # LightComponent::GetIntensity -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/LightComponent.h` + +## 签名 ```cpp float GetIntensity() const; ``` -该方法声明于 `XCEngine/Components/LightComponent.h`，当前页面用于固定 `LightComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_intensity` 当前值。 -**返回：** `float` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::LightComponent object; - // 根据上下文补齐参数后调用 LightComponent::GetIntensity(...)。 - (void)object; -} -``` +- 返回 `m_intensity` 当前值。 ## 相关文档 -- [返回类总览](LightComponent.md) -- [返回模块目录](../Components.md) +- [LightComponent](LightComponent.md) +- [SetIntensity](SetIntensity.md) diff --git a/docs/api/XCEngine/Components/LightComponent/GetLightType.md b/docs/api/XCEngine/Components/LightComponent/GetLightType.md index 5923abe5..c6b917be 100644 --- a/docs/api/XCEngine/Components/LightComponent/GetLightType.md +++ b/docs/api/XCEngine/Components/LightComponent/GetLightType.md @@ -1,30 +1,26 @@ # LightComponent::GetLightType -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/LightComponent.h` + +## 签名 ```cpp LightType GetLightType() const; ``` -该方法声明于 `XCEngine/Components/LightComponent.h`，当前页面用于固定 `LightComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_lightType` 当前值。 -**返回：** `LightType` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::LightComponent object; - // 根据上下文补齐参数后调用 LightComponent::GetLightType(...)。 - (void)object; -} -``` +- 返回 `m_lightType` 当前值。 ## 相关文档 -- [返回类总览](LightComponent.md) -- [返回模块目录](../Components.md) +- [LightComponent](LightComponent.md) +- [SetLightType](SetLightType.md) diff --git a/docs/api/XCEngine/Components/LightComponent/GetName.md b/docs/api/XCEngine/Components/LightComponent/GetName.md index c7f5d459..f80626fb 100644 --- a/docs/api/XCEngine/Components/LightComponent/GetName.md +++ b/docs/api/XCEngine/Components/LightComponent/GetName.md @@ -1,30 +1,25 @@ # LightComponent::GetName -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/LightComponent.h` + +## 签名 ```cpp std::string GetName() const override; ``` -该方法声明于 `XCEngine/Components/LightComponent.h`，当前页面用于固定 `LightComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `"Light"`。 -**返回：** `std::string` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::LightComponent object; - // 根据上下文补齐参数后调用 LightComponent::GetName(...)。 - (void)object; -} -``` +- 返回 `"Light"`。 ## 相关文档 -- [返回类总览](LightComponent.md) -- [返回模块目录](../Components.md) +- [LightComponent](LightComponent.md) diff --git a/docs/api/XCEngine/Components/LightComponent/GetRange.md b/docs/api/XCEngine/Components/LightComponent/GetRange.md index 31f95e62..6ff9c1aa 100644 --- a/docs/api/XCEngine/Components/LightComponent/GetRange.md +++ b/docs/api/XCEngine/Components/LightComponent/GetRange.md @@ -1,30 +1,26 @@ # LightComponent::GetRange -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/LightComponent.h` + +## 签名 ```cpp float GetRange() const; ``` -该方法声明于 `XCEngine/Components/LightComponent.h`，当前页面用于固定 `LightComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_range` 当前值。 -**返回：** `float` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::LightComponent object; - // 根据上下文补齐参数后调用 LightComponent::GetRange(...)。 - (void)object; -} -``` +- 返回 `m_range` 当前值。 ## 相关文档 -- [返回类总览](LightComponent.md) -- [返回模块目录](../Components.md) +- [LightComponent](LightComponent.md) +- [SetRange](SetRange.md) diff --git a/docs/api/XCEngine/Components/LightComponent/GetSpotAngle.md b/docs/api/XCEngine/Components/LightComponent/GetSpotAngle.md index d167274b..7577a89a 100644 --- a/docs/api/XCEngine/Components/LightComponent/GetSpotAngle.md +++ b/docs/api/XCEngine/Components/LightComponent/GetSpotAngle.md @@ -1,30 +1,26 @@ # LightComponent::GetSpotAngle -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/LightComponent.h` + +## 签名 ```cpp float GetSpotAngle() const; ``` -该方法声明于 `XCEngine/Components/LightComponent.h`，当前页面用于固定 `LightComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_spotAngle` 当前值。 -**返回：** `float` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::LightComponent object; - // 根据上下文补齐参数后调用 LightComponent::GetSpotAngle(...)。 - (void)object; -} -``` +- 返回 `m_spotAngle` 当前值。 ## 相关文档 -- [返回类总览](LightComponent.md) -- [返回模块目录](../Components.md) +- [LightComponent](LightComponent.md) +- [SetSpotAngle](SetSpotAngle.md) diff --git a/docs/api/XCEngine/Components/LightComponent/Serialize.md b/docs/api/XCEngine/Components/LightComponent/Serialize.md index c5f6771f..55db0bad 100644 --- a/docs/api/XCEngine/Components/LightComponent/Serialize.md +++ b/docs/api/XCEngine/Components/LightComponent/Serialize.md @@ -1,31 +1,25 @@ # LightComponent::Serialize -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/LightComponent.h` + +## 签名 ```cpp void Serialize(std::ostream& os) const override; ``` -该方法声明于 `XCEngine/Components/LightComponent.h`，当前页面用于固定 `LightComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `os` - 参数语义详见头文件声明。 +执行 `Serialize` 对应的公开操作。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::LightComponent object; - // 根据上下文补齐参数后调用 LightComponent::Serialize(...)。 - (void)object; -} -``` +- 具体定义位于 `engine/src/Components/LightComponent.cpp`。 ## 相关文档 -- [返回类总览](LightComponent.md) -- [返回模块目录](../Components.md) +- [LightComponent](LightComponent.md) diff --git a/docs/api/XCEngine/Components/LightComponent/SetCastsShadows.md b/docs/api/XCEngine/Components/LightComponent/SetCastsShadows.md index 66b54bb0..98bbe2a4 100644 --- a/docs/api/XCEngine/Components/LightComponent/SetCastsShadows.md +++ b/docs/api/XCEngine/Components/LightComponent/SetCastsShadows.md @@ -1,31 +1,26 @@ # LightComponent::SetCastsShadows -设置相关状态或配置。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/LightComponent.h` + +## 签名 ```cpp void SetCastsShadows(bool value); ``` -该方法声明于 `XCEngine/Components/LightComponent.h`，当前页面用于固定 `LightComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `value` - 参数语义详见头文件声明。 +更新 `m_castsShadows`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::LightComponent object; - // 根据上下文补齐参数后调用 LightComponent::SetCastsShadows(...)。 - (void)object; -} -``` +- 会更新 `m_castsShadows`。 ## 相关文档 -- [返回类总览](LightComponent.md) -- [返回模块目录](../Components.md) +- [LightComponent](LightComponent.md) +- [GetCastsShadows](GetCastsShadows.md) diff --git a/docs/api/XCEngine/Components/LightComponent/SetColor.md b/docs/api/XCEngine/Components/LightComponent/SetColor.md index de967d90..be70fee0 100644 --- a/docs/api/XCEngine/Components/LightComponent/SetColor.md +++ b/docs/api/XCEngine/Components/LightComponent/SetColor.md @@ -1,31 +1,26 @@ # LightComponent::SetColor -设置相关状态或配置。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/LightComponent.h` + +## 签名 ```cpp void SetColor(const Math::Color& value); ``` -该方法声明于 `XCEngine/Components/LightComponent.h`，当前页面用于固定 `LightComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `value` - 参数语义详见头文件声明。 +更新 `m_color`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::LightComponent object; - // 根据上下文补齐参数后调用 LightComponent::SetColor(...)。 - (void)object; -} -``` +- 会更新 `m_color`。 ## 相关文档 -- [返回类总览](LightComponent.md) -- [返回模块目录](../Components.md) +- [LightComponent](LightComponent.md) +- [GetColor](GetColor.md) diff --git a/docs/api/XCEngine/Components/LightComponent/SetIntensity.md b/docs/api/XCEngine/Components/LightComponent/SetIntensity.md index 148c2c28..84fd20c9 100644 --- a/docs/api/XCEngine/Components/LightComponent/SetIntensity.md +++ b/docs/api/XCEngine/Components/LightComponent/SetIntensity.md @@ -1,31 +1,27 @@ # LightComponent::SetIntensity -设置相关状态或配置。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/LightComponent.h` + +## 签名 ```cpp void SetIntensity(float value); ``` -该方法声明于 `XCEngine/Components/LightComponent.h`，当前页面用于固定 `LightComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `value` - 参数语义详见头文件声明。 +更新 `m_intensity`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::LightComponent object; - // 根据上下文补齐参数后调用 LightComponent::SetIntensity(...)。 - (void)object; -} -``` +- 会更新 `m_intensity`。 +- 当前实现会调用 `max`。 ## 相关文档 -- [返回类总览](LightComponent.md) -- [返回模块目录](../Components.md) +- [LightComponent](LightComponent.md) +- [GetIntensity](GetIntensity.md) diff --git a/docs/api/XCEngine/Components/LightComponent/SetLightType.md b/docs/api/XCEngine/Components/LightComponent/SetLightType.md index 725f9009..048b70a0 100644 --- a/docs/api/XCEngine/Components/LightComponent/SetLightType.md +++ b/docs/api/XCEngine/Components/LightComponent/SetLightType.md @@ -1,31 +1,26 @@ # LightComponent::SetLightType -设置相关状态或配置。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/LightComponent.h` + +## 签名 ```cpp void SetLightType(LightType value); ``` -该方法声明于 `XCEngine/Components/LightComponent.h`，当前页面用于固定 `LightComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `value` - 参数语义详见头文件声明。 +更新 `m_lightType`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::LightComponent object; - // 根据上下文补齐参数后调用 LightComponent::SetLightType(...)。 - (void)object; -} -``` +- 会更新 `m_lightType`。 ## 相关文档 -- [返回类总览](LightComponent.md) -- [返回模块目录](../Components.md) +- [LightComponent](LightComponent.md) +- [GetLightType](GetLightType.md) diff --git a/docs/api/XCEngine/Components/LightComponent/SetRange.md b/docs/api/XCEngine/Components/LightComponent/SetRange.md index b1a1d683..86e30055 100644 --- a/docs/api/XCEngine/Components/LightComponent/SetRange.md +++ b/docs/api/XCEngine/Components/LightComponent/SetRange.md @@ -1,31 +1,27 @@ # LightComponent::SetRange -设置相关状态或配置。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/LightComponent.h` + +## 签名 ```cpp void SetRange(float value); ``` -该方法声明于 `XCEngine/Components/LightComponent.h`，当前页面用于固定 `LightComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `value` - 参数语义详见头文件声明。 +更新 `m_range`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::LightComponent object; - // 根据上下文补齐参数后调用 LightComponent::SetRange(...)。 - (void)object; -} -``` +- 会更新 `m_range`。 +- 当前实现会调用 `max`。 ## 相关文档 -- [返回类总览](LightComponent.md) -- [返回模块目录](../Components.md) +- [LightComponent](LightComponent.md) +- [GetRange](GetRange.md) diff --git a/docs/api/XCEngine/Components/LightComponent/SetSpotAngle.md b/docs/api/XCEngine/Components/LightComponent/SetSpotAngle.md index 875fcdf2..8dea5092 100644 --- a/docs/api/XCEngine/Components/LightComponent/SetSpotAngle.md +++ b/docs/api/XCEngine/Components/LightComponent/SetSpotAngle.md @@ -1,31 +1,27 @@ # LightComponent::SetSpotAngle -设置相关状态或配置。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/LightComponent.h` + +## 签名 ```cpp void SetSpotAngle(float value); ``` -该方法声明于 `XCEngine/Components/LightComponent.h`，当前页面用于固定 `LightComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `value` - 参数语义详见头文件声明。 +更新 `m_spotAngle`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::LightComponent object; - // 根据上下文补齐参数后调用 LightComponent::SetSpotAngle(...)。 - (void)object; -} -``` +- 会更新 `m_spotAngle`。 +- 当前实现会调用 `clamp`。 ## 相关文档 -- [返回类总览](LightComponent.md) -- [返回模块目录](../Components.md) +- [LightComponent](LightComponent.md) +- [GetSpotAngle](GetSpotAngle.md) diff --git a/docs/api/XCEngine/Components/TransformComponent/Constructor.md b/docs/api/XCEngine/Components/TransformComponent/Constructor.md index 12862c0e..05967bef 100644 --- a/docs/api/XCEngine/Components/TransformComponent/Constructor.md +++ b/docs/api/XCEngine/Components/TransformComponent/Constructor.md @@ -1,28 +1,25 @@ # TransformComponent::TransformComponent() -构造对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/TransformComponent.h` + +## 签名 ```cpp TransformComponent(); ``` -该方法声明于 `XCEngine/Components/TransformComponent.h`，当前页面用于固定 `TransformComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +构造 `TransformComponent` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::TransformComponent object; -} -``` +- 当前为默认构造实现。 ## 相关文档 -- [返回类总览](TransformComponent.md) -- [返回模块目录](../Components.md) +- [TransformComponent](TransformComponent.md) diff --git a/docs/api/XCEngine/Components/TransformComponent/Deserialize.md b/docs/api/XCEngine/Components/TransformComponent/Deserialize.md index 6c00d189..e4b47e0a 100644 --- a/docs/api/XCEngine/Components/TransformComponent/Deserialize.md +++ b/docs/api/XCEngine/Components/TransformComponent/Deserialize.md @@ -1,31 +1,26 @@ # TransformComponent::Deserialize -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/TransformComponent.h` + +## 签名 ```cpp void Deserialize(std::istream& is) override; ``` -该方法声明于 `XCEngine/Components/TransformComponent.h`，当前页面用于固定 `TransformComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `is` - 参数语义详见头文件声明。 +执行 `getline`、`empty`、`find` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::TransformComponent object; - // 根据上下文补齐参数后调用 TransformComponent::Deserialize(...)。 - (void)object; -} -``` +- 会更新 `m_localPosition`、`m_localRotation`、`m_localScale`。 +- 当前实现会调用 `getline`、`empty`、`find`、`substr`。 ## 相关文档 -- [返回类总览](TransformComponent.md) -- [返回模块目录](../Components.md) +- [TransformComponent](TransformComponent.md) diff --git a/docs/api/XCEngine/Components/TransformComponent/Destructor.md b/docs/api/XCEngine/Components/TransformComponent/Destructor.md index 4f38ca55..25ef4b16 100644 --- a/docs/api/XCEngine/Components/TransformComponent/Destructor.md +++ b/docs/api/XCEngine/Components/TransformComponent/Destructor.md @@ -1,29 +1,25 @@ # TransformComponent::~TransformComponent() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/TransformComponent.h` + +## 签名 ```cpp ~TransformComponent() override = default; ``` -该方法声明于 `XCEngine/Components/TransformComponent.h`，当前页面用于固定 `TransformComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +销毁 `TransformComponent` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::TransformComponent object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 具体定义位于 `engine/src/Components/TransformComponent.cpp`。 ## 相关文档 -- [返回类总览](TransformComponent.md) -- [返回模块目录](../Components.md) +- [TransformComponent](TransformComponent.md) diff --git a/docs/api/XCEngine/Components/TransformComponent/DetachChildren.md b/docs/api/XCEngine/Components/TransformComponent/DetachChildren.md index 2e71143d..a1b0f76c 100644 --- a/docs/api/XCEngine/Components/TransformComponent/DetachChildren.md +++ b/docs/api/XCEngine/Components/TransformComponent/DetachChildren.md @@ -1,30 +1,27 @@ # TransformComponent::DetachChildren -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/TransformComponent.h` + +## 签名 ```cpp void DetachChildren(); ``` -该方法声明于 `XCEngine/Components/TransformComponent.h`，当前页面用于固定 `TransformComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_parent`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::TransformComponent object; - // 根据上下文补齐参数后调用 TransformComponent::DetachChildren(...)。 - (void)object; -} -``` +- 会更新 `m_parent`。 +- 当前实现会调用 `clear`。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](TransformComponent.md) -- [返回模块目录](../Components.md) +- [TransformComponent](TransformComponent.md) diff --git a/docs/api/XCEngine/Components/TransformComponent/Find.md b/docs/api/XCEngine/Components/TransformComponent/Find.md index deb2cacd..29f5c265 100644 --- a/docs/api/XCEngine/Components/TransformComponent/Find.md +++ b/docs/api/XCEngine/Components/TransformComponent/Find.md @@ -1,31 +1,25 @@ # TransformComponent::Find -查找并返回匹配对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/TransformComponent.h` + +## 签名 ```cpp TransformComponent* Find(const std::string& name) const; ``` -该方法声明于 `XCEngine/Components/TransformComponent.h`，当前页面用于固定 `TransformComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `name` - 参数语义详见头文件声明。 +执行 `Find` 对应的公开操作。 -**返回：** `TransformComponent*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::TransformComponent object; - // 根据上下文补齐参数后调用 TransformComponent::Find(...)。 - (void)object; -} -``` +- 具体定义位于 `engine/src/Components/TransformComponent.cpp`。 ## 相关文档 -- [返回类总览](TransformComponent.md) -- [返回模块目录](../Components.md) +- [TransformComponent](TransformComponent.md) diff --git a/docs/api/XCEngine/Components/TransformComponent/GetChild.md b/docs/api/XCEngine/Components/TransformComponent/GetChild.md index cc3d5f0c..4ad1e37f 100644 --- a/docs/api/XCEngine/Components/TransformComponent/GetChild.md +++ b/docs/api/XCEngine/Components/TransformComponent/GetChild.md @@ -1,31 +1,28 @@ # TransformComponent::GetChild -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/TransformComponent.h` + +## 签名 ```cpp TransformComponent* GetChild(size_t index) const; ``` -该方法声明于 `XCEngine/Components/TransformComponent.h`，当前页面用于固定 `TransformComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `index` - 参数语义详见头文件声明。 +更新 `m_children`。 -**返回：** `TransformComponent*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::TransformComponent object; - // 根据上下文补齐参数后调用 TransformComponent::GetChild(...)。 - (void)object; -} -``` +- 会更新 `m_children`。 +- 当前实现会调用 `size`。 +- 包含条件分支，并可能提前返回。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](TransformComponent.md) -- [返回模块目录](../Components.md) +- [TransformComponent](TransformComponent.md) diff --git a/docs/api/XCEngine/Components/TransformComponent/GetChildCount.md b/docs/api/XCEngine/Components/TransformComponent/GetChildCount.md index 09d345b8..3aee8855 100644 --- a/docs/api/XCEngine/Components/TransformComponent/GetChildCount.md +++ b/docs/api/XCEngine/Components/TransformComponent/GetChildCount.md @@ -1,30 +1,26 @@ # TransformComponent::GetChildCount -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/TransformComponent.h` + +## 签名 ```cpp size_t GetChildCount() const; ``` -该方法声明于 `XCEngine/Components/TransformComponent.h`，当前页面用于固定 `TransformComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_children`。 -**返回：** `size_t` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::TransformComponent object; - // 根据上下文补齐参数后调用 TransformComponent::GetChildCount(...)。 - (void)object; -} -``` +- 会更新 `m_children`。 +- 当前实现会调用 `size`。 ## 相关文档 -- [返回类总览](TransformComponent.md) -- [返回模块目录](../Components.md) +- [TransformComponent](TransformComponent.md) diff --git a/docs/api/XCEngine/Components/TransformComponent/GetForward.md b/docs/api/XCEngine/Components/TransformComponent/GetForward.md index fac6b7c0..f4a43c19 100644 --- a/docs/api/XCEngine/Components/TransformComponent/GetForward.md +++ b/docs/api/XCEngine/Components/TransformComponent/GetForward.md @@ -1,30 +1,25 @@ # TransformComponent::GetForward -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/TransformComponent.h` + +## 签名 ```cpp Math::Vector3 GetForward() const; ``` -该方法声明于 `XCEngine/Components/TransformComponent.h`，当前页面用于固定 `TransformComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `GetRotation() * Math::Vector3::Forward()` 的结果。 -**返回：** `Math::Vector3` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::TransformComponent object; - // 根据上下文补齐参数后调用 TransformComponent::GetForward(...)。 - (void)object; -} -``` +- 当前实现会调用 `GetRotation`、`Forward`。 ## 相关文档 -- [返回类总览](TransformComponent.md) -- [返回模块目录](../Components.md) +- [TransformComponent](TransformComponent.md) diff --git a/docs/api/XCEngine/Components/TransformComponent/GetLocalEulerAngles.md b/docs/api/XCEngine/Components/TransformComponent/GetLocalEulerAngles.md index 7aa2eaa0..e686fd50 100644 --- a/docs/api/XCEngine/Components/TransformComponent/GetLocalEulerAngles.md +++ b/docs/api/XCEngine/Components/TransformComponent/GetLocalEulerAngles.md @@ -1,30 +1,27 @@ # TransformComponent::GetLocalEulerAngles -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/TransformComponent.h` + +## 签名 ```cpp Math::Vector3 GetLocalEulerAngles() const; ``` -该方法声明于 `XCEngine/Components/TransformComponent.h`，当前页面用于固定 `TransformComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_localRotation`。 -**返回：** `Math::Vector3` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::TransformComponent object; - // 根据上下文补齐参数后调用 TransformComponent::GetLocalEulerAngles(...)。 - (void)object; -} -``` +- 会更新 `m_localRotation`。 +- 当前实现会调用 `ToEulerAngles`。 ## 相关文档 -- [返回类总览](TransformComponent.md) -- [返回模块目录](../Components.md) +- [TransformComponent](TransformComponent.md) +- [SetLocalEulerAngles](SetLocalEulerAngles.md) diff --git a/docs/api/XCEngine/Components/TransformComponent/GetLocalPosition.md b/docs/api/XCEngine/Components/TransformComponent/GetLocalPosition.md index e0ef9af6..2691b272 100644 --- a/docs/api/XCEngine/Components/TransformComponent/GetLocalPosition.md +++ b/docs/api/XCEngine/Components/TransformComponent/GetLocalPosition.md @@ -1,30 +1,26 @@ # TransformComponent::GetLocalPosition -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/TransformComponent.h` + +## 签名 ```cpp const Math::Vector3& GetLocalPosition() const; ``` -该方法声明于 `XCEngine/Components/TransformComponent.h`，当前页面用于固定 `TransformComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_localPosition` 当前值。 -**返回：** `const Math::Vector3&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::TransformComponent object; - // 根据上下文补齐参数后调用 TransformComponent::GetLocalPosition(...)。 - (void)object; -} -``` +- 返回 `m_localPosition` 当前值。 ## 相关文档 -- [返回类总览](TransformComponent.md) -- [返回模块目录](../Components.md) +- [TransformComponent](TransformComponent.md) +- [SetLocalPosition](SetLocalPosition.md) diff --git a/docs/api/XCEngine/Components/TransformComponent/GetLocalRotation.md b/docs/api/XCEngine/Components/TransformComponent/GetLocalRotation.md index 64a0f1a9..0a8ebc45 100644 --- a/docs/api/XCEngine/Components/TransformComponent/GetLocalRotation.md +++ b/docs/api/XCEngine/Components/TransformComponent/GetLocalRotation.md @@ -1,30 +1,26 @@ # TransformComponent::GetLocalRotation -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/TransformComponent.h` + +## 签名 ```cpp const Math::Quaternion& GetLocalRotation() const; ``` -该方法声明于 `XCEngine/Components/TransformComponent.h`，当前页面用于固定 `TransformComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_localRotation` 当前值。 -**返回：** `const Math::Quaternion&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::TransformComponent object; - // 根据上下文补齐参数后调用 TransformComponent::GetLocalRotation(...)。 - (void)object; -} -``` +- 返回 `m_localRotation` 当前值。 ## 相关文档 -- [返回类总览](TransformComponent.md) -- [返回模块目录](../Components.md) +- [TransformComponent](TransformComponent.md) +- [SetLocalRotation](SetLocalRotation.md) diff --git a/docs/api/XCEngine/Components/TransformComponent/GetLocalScale.md b/docs/api/XCEngine/Components/TransformComponent/GetLocalScale.md index 9f34764e..1a5d2786 100644 --- a/docs/api/XCEngine/Components/TransformComponent/GetLocalScale.md +++ b/docs/api/XCEngine/Components/TransformComponent/GetLocalScale.md @@ -1,30 +1,26 @@ # TransformComponent::GetLocalScale -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/TransformComponent.h` + +## 签名 ```cpp const Math::Vector3& GetLocalScale() const; ``` -该方法声明于 `XCEngine/Components/TransformComponent.h`，当前页面用于固定 `TransformComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_localScale` 当前值。 -**返回：** `const Math::Vector3&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::TransformComponent object; - // 根据上下文补齐参数后调用 TransformComponent::GetLocalScale(...)。 - (void)object; -} -``` +- 返回 `m_localScale` 当前值。 ## 相关文档 -- [返回类总览](TransformComponent.md) -- [返回模块目录](../Components.md) +- [TransformComponent](TransformComponent.md) +- [SetLocalScale](SetLocalScale.md) diff --git a/docs/api/XCEngine/Components/TransformComponent/GetLocalToWorldMatrix.md b/docs/api/XCEngine/Components/TransformComponent/GetLocalToWorldMatrix.md index 07e74fd6..b6bc82c8 100644 --- a/docs/api/XCEngine/Components/TransformComponent/GetLocalToWorldMatrix.md +++ b/docs/api/XCEngine/Components/TransformComponent/GetLocalToWorldMatrix.md @@ -1,30 +1,25 @@ # TransformComponent::GetLocalToWorldMatrix -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/TransformComponent.h` + +## 签名 ```cpp const Math::Matrix4x4& GetLocalToWorldMatrix() const; ``` -该方法声明于 `XCEngine/Components/TransformComponent.h`，当前页面用于固定 `TransformComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `UpdateWorldTransform(...)` 相关流程。 -**返回：** `const Math::Matrix4x4&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::TransformComponent object; - // 根据上下文补齐参数后调用 TransformComponent::GetLocalToWorldMatrix(...)。 - (void)object; -} -``` +- 当前实现会调用 `UpdateWorldTransform`。 ## 相关文档 -- [返回类总览](TransformComponent.md) -- [返回模块目录](../Components.md) +- [TransformComponent](TransformComponent.md) diff --git a/docs/api/XCEngine/Components/TransformComponent/GetName.md b/docs/api/XCEngine/Components/TransformComponent/GetName.md index 609a8ce9..b4acb8a4 100644 --- a/docs/api/XCEngine/Components/TransformComponent/GetName.md +++ b/docs/api/XCEngine/Components/TransformComponent/GetName.md @@ -1,30 +1,25 @@ # TransformComponent::GetName -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/TransformComponent.h` + +## 签名 ```cpp std::string GetName() const override; ``` -该方法声明于 `XCEngine/Components/TransformComponent.h`，当前页面用于固定 `TransformComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `"Transform"`。 -**返回：** `std::string` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::TransformComponent object; - // 根据上下文补齐参数后调用 TransformComponent::GetName(...)。 - (void)object; -} -``` +- 返回 `"Transform"`。 ## 相关文档 -- [返回类总览](TransformComponent.md) -- [返回模块目录](../Components.md) +- [TransformComponent](TransformComponent.md) diff --git a/docs/api/XCEngine/Components/TransformComponent/GetParent.md b/docs/api/XCEngine/Components/TransformComponent/GetParent.md index 54c806ce..f43fcf98 100644 --- a/docs/api/XCEngine/Components/TransformComponent/GetParent.md +++ b/docs/api/XCEngine/Components/TransformComponent/GetParent.md @@ -1,30 +1,26 @@ # TransformComponent::GetParent -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/TransformComponent.h` + +## 签名 ```cpp TransformComponent* GetParent() const; ``` -该方法声明于 `XCEngine/Components/TransformComponent.h`，当前页面用于固定 `TransformComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_parent` 当前值。 -**返回：** `TransformComponent*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::TransformComponent object; - // 根据上下文补齐参数后调用 TransformComponent::GetParent(...)。 - (void)object; -} -``` +- 返回 `m_parent` 当前值。 ## 相关文档 -- [返回类总览](TransformComponent.md) -- [返回模块目录](../Components.md) +- [TransformComponent](TransformComponent.md) +- [SetParent](SetParent.md) diff --git a/docs/api/XCEngine/Components/TransformComponent/GetPosition.md b/docs/api/XCEngine/Components/TransformComponent/GetPosition.md index 24f8da1f..001c1794 100644 --- a/docs/api/XCEngine/Components/TransformComponent/GetPosition.md +++ b/docs/api/XCEngine/Components/TransformComponent/GetPosition.md @@ -1,30 +1,26 @@ # TransformComponent::GetPosition -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/TransformComponent.h` + +## 签名 ```cpp Math::Vector3 GetPosition() const; ``` -该方法声明于 `XCEngine/Components/TransformComponent.h`，当前页面用于固定 `TransformComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `UpdateWorldTransform(...)` 相关流程。 -**返回：** `Math::Vector3` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::TransformComponent object; - // 根据上下文补齐参数后调用 TransformComponent::GetPosition(...)。 - (void)object; -} -``` +- 当前实现会调用 `UpdateWorldTransform`。 ## 相关文档 -- [返回类总览](TransformComponent.md) -- [返回模块目录](../Components.md) +- [TransformComponent](TransformComponent.md) +- [SetPosition](SetPosition.md) diff --git a/docs/api/XCEngine/Components/TransformComponent/GetRight.md b/docs/api/XCEngine/Components/TransformComponent/GetRight.md index 81567c79..f2d4fdce 100644 --- a/docs/api/XCEngine/Components/TransformComponent/GetRight.md +++ b/docs/api/XCEngine/Components/TransformComponent/GetRight.md @@ -1,30 +1,25 @@ # TransformComponent::GetRight -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/TransformComponent.h` + +## 签名 ```cpp Math::Vector3 GetRight() const; ``` -该方法声明于 `XCEngine/Components/TransformComponent.h`，当前页面用于固定 `TransformComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `GetRotation() * Math::Vector3::Right()` 的结果。 -**返回：** `Math::Vector3` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::TransformComponent object; - // 根据上下文补齐参数后调用 TransformComponent::GetRight(...)。 - (void)object; -} -``` +- 当前实现会调用 `GetRotation`、`Right`。 ## 相关文档 -- [返回类总览](TransformComponent.md) -- [返回模块目录](../Components.md) +- [TransformComponent](TransformComponent.md) diff --git a/docs/api/XCEngine/Components/TransformComponent/GetRotation.md b/docs/api/XCEngine/Components/TransformComponent/GetRotation.md index 55c196eb..53ab465e 100644 --- a/docs/api/XCEngine/Components/TransformComponent/GetRotation.md +++ b/docs/api/XCEngine/Components/TransformComponent/GetRotation.md @@ -1,30 +1,26 @@ # TransformComponent::GetRotation -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/TransformComponent.h` + +## 签名 ```cpp Math::Quaternion GetRotation() const; ``` -该方法声明于 `XCEngine/Components/TransformComponent.h`，当前页面用于固定 `TransformComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `UpdateWorldTransform(...)` 相关流程。 -**返回：** `Math::Quaternion` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::TransformComponent object; - // 根据上下文补齐参数后调用 TransformComponent::GetRotation(...)。 - (void)object; -} -``` +- 当前实现会调用 `UpdateWorldTransform`。 ## 相关文档 -- [返回类总览](TransformComponent.md) -- [返回模块目录](../Components.md) +- [TransformComponent](TransformComponent.md) +- [SetRotation](SetRotation.md) diff --git a/docs/api/XCEngine/Components/TransformComponent/GetScale.md b/docs/api/XCEngine/Components/TransformComponent/GetScale.md index 1c846d86..02e5f374 100644 --- a/docs/api/XCEngine/Components/TransformComponent/GetScale.md +++ b/docs/api/XCEngine/Components/TransformComponent/GetScale.md @@ -1,30 +1,26 @@ # TransformComponent::GetScale -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/TransformComponent.h` + +## 签名 ```cpp Math::Vector3 GetScale() const; ``` -该方法声明于 `XCEngine/Components/TransformComponent.h`，当前页面用于固定 `TransformComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `UpdateWorldTransform(...)` 相关流程。 -**返回：** `Math::Vector3` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::TransformComponent object; - // 根据上下文补齐参数后调用 TransformComponent::GetScale(...)。 - (void)object; -} -``` +- 当前实现会调用 `UpdateWorldTransform`。 ## 相关文档 -- [返回类总览](TransformComponent.md) -- [返回模块目录](../Components.md) +- [TransformComponent](TransformComponent.md) +- [SetScale](SetScale.md) diff --git a/docs/api/XCEngine/Components/TransformComponent/GetSiblingIndex.md b/docs/api/XCEngine/Components/TransformComponent/GetSiblingIndex.md index 9b4a28a7..ce9df1ca 100644 --- a/docs/api/XCEngine/Components/TransformComponent/GetSiblingIndex.md +++ b/docs/api/XCEngine/Components/TransformComponent/GetSiblingIndex.md @@ -1,30 +1,26 @@ # TransformComponent::GetSiblingIndex -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/TransformComponent.h` + +## 签名 ```cpp int GetSiblingIndex() const; ``` -该方法声明于 `XCEngine/Components/TransformComponent.h`，当前页面用于固定 `TransformComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_siblingIndex` 当前值。 -**返回：** `int` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::TransformComponent object; - // 根据上下文补齐参数后调用 TransformComponent::GetSiblingIndex(...)。 - (void)object; -} -``` +- 返回 `m_siblingIndex` 当前值。 ## 相关文档 -- [返回类总览](TransformComponent.md) -- [返回模块目录](../Components.md) +- [TransformComponent](TransformComponent.md) +- [SetSiblingIndex](SetSiblingIndex.md) diff --git a/docs/api/XCEngine/Components/TransformComponent/GetUp.md b/docs/api/XCEngine/Components/TransformComponent/GetUp.md index 107a194d..5abdb814 100644 --- a/docs/api/XCEngine/Components/TransformComponent/GetUp.md +++ b/docs/api/XCEngine/Components/TransformComponent/GetUp.md @@ -1,30 +1,25 @@ # TransformComponent::GetUp -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/TransformComponent.h` + +## 签名 ```cpp Math::Vector3 GetUp() const; ``` -该方法声明于 `XCEngine/Components/TransformComponent.h`，当前页面用于固定 `TransformComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `GetRotation() * Math::Vector3::Up()` 的结果。 -**返回：** `Math::Vector3` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::TransformComponent object; - // 根据上下文补齐参数后调用 TransformComponent::GetUp(...)。 - (void)object; -} -``` +- 当前实现会调用 `GetRotation`、`Up`。 ## 相关文档 -- [返回类总览](TransformComponent.md) -- [返回模块目录](../Components.md) +- [TransformComponent](TransformComponent.md) diff --git a/docs/api/XCEngine/Components/TransformComponent/GetWorldToLocalMatrix.md b/docs/api/XCEngine/Components/TransformComponent/GetWorldToLocalMatrix.md index 5c76b011..603d66dc 100644 --- a/docs/api/XCEngine/Components/TransformComponent/GetWorldToLocalMatrix.md +++ b/docs/api/XCEngine/Components/TransformComponent/GetWorldToLocalMatrix.md @@ -1,30 +1,25 @@ # TransformComponent::GetWorldToLocalMatrix -获取相关状态或对象。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/TransformComponent.h` + +## 签名 ```cpp Math::Matrix4x4 GetWorldToLocalMatrix() const; ``` -该方法声明于 `XCEngine/Components/TransformComponent.h`，当前页面用于固定 `TransformComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `GetLocalToWorldMatrix().Inverse()` 的结果。 -**返回：** `Math::Matrix4x4` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::TransformComponent object; - // 根据上下文补齐参数后调用 TransformComponent::GetWorldToLocalMatrix(...)。 - (void)object; -} -``` +- 当前实现会调用 `GetLocalToWorldMatrix`、`Inverse`。 ## 相关文档 -- [返回类总览](TransformComponent.md) -- [返回模块目录](../Components.md) +- [TransformComponent](TransformComponent.md) diff --git a/docs/api/XCEngine/Components/TransformComponent/InverseTransformDirection.md b/docs/api/XCEngine/Components/TransformComponent/InverseTransformDirection.md index d25c7344..9121d332 100644 --- a/docs/api/XCEngine/Components/TransformComponent/InverseTransformDirection.md +++ b/docs/api/XCEngine/Components/TransformComponent/InverseTransformDirection.md @@ -1,31 +1,25 @@ # TransformComponent::InverseTransformDirection -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/TransformComponent.h` + +## 签名 ```cpp Math::Vector3 InverseTransformDirection(const Math::Vector3& direction) const; ``` -该方法声明于 `XCEngine/Components/TransformComponent.h`，当前页面用于固定 `TransformComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `direction` - 参数语义详见头文件声明。 +执行 `InverseTransformDirection` 对应的公开操作。 -**返回：** `Math::Vector3` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::TransformComponent object; - // 根据上下文补齐参数后调用 TransformComponent::InverseTransformDirection(...)。 - (void)object; -} -``` +- 具体定义位于 `engine/src/Components/TransformComponent.cpp`。 ## 相关文档 -- [返回类总览](TransformComponent.md) -- [返回模块目录](../Components.md) +- [TransformComponent](TransformComponent.md) diff --git a/docs/api/XCEngine/Components/TransformComponent/InverseTransformPoint.md b/docs/api/XCEngine/Components/TransformComponent/InverseTransformPoint.md index 7171fd34..876d5079 100644 --- a/docs/api/XCEngine/Components/TransformComponent/InverseTransformPoint.md +++ b/docs/api/XCEngine/Components/TransformComponent/InverseTransformPoint.md @@ -1,31 +1,25 @@ # TransformComponent::InverseTransformPoint -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/TransformComponent.h` + +## 签名 ```cpp Math::Vector3 InverseTransformPoint(const Math::Vector3& point) const; ``` -该方法声明于 `XCEngine/Components/TransformComponent.h`，当前页面用于固定 `TransformComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `point` - 参数语义详见头文件声明。 +执行 `InverseTransformPoint` 对应的公开操作。 -**返回：** `Math::Vector3` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::TransformComponent object; - // 根据上下文补齐参数后调用 TransformComponent::InverseTransformPoint(...)。 - (void)object; -} -``` +- 具体定义位于 `engine/src/Components/TransformComponent.cpp`。 ## 相关文档 -- [返回类总览](TransformComponent.md) -- [返回模块目录](../Components.md) +- [TransformComponent](TransformComponent.md) diff --git a/docs/api/XCEngine/Components/TransformComponent/LookAt.md b/docs/api/XCEngine/Components/TransformComponent/LookAt.md index 9c748d6a..34cffed0 100644 --- a/docs/api/XCEngine/Components/TransformComponent/LookAt.md +++ b/docs/api/XCEngine/Components/TransformComponent/LookAt.md @@ -1,45 +1,27 @@ # TransformComponent::LookAt -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Components` -该方法在 `XCEngine/Components/TransformComponent.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。 +**类型**: `method` -## 重载 1: 声明 +**头文件**: `XCEngine/Components/TransformComponent.h` + +## 签名 ```cpp void LookAt(const Math::Vector3& target); -``` - -**参数：** -- `target` - 参数语义详见头文件声明。 - -**返回：** `void` - 无返回值。 - -## 重载 2: 声明 - -```cpp void LookAt(const Math::Vector3& target, const Math::Vector3& up); ``` -**参数：** -- `target` - 参数语义详见头文件声明。 -- `up` - 参数语义详见头文件声明。 +## 作用 -**返回：** `void` - 无返回值。 +执行 `LookAt`、`Up` 协同流程。 -**示例：** +## 当前实现 -```cpp -#include - -void Example() { - XCEngine::Components::TransformComponent object; - // 根据上下文补齐参数后调用 TransformComponent::LookAt(...)。 - (void)object; -} -``` +- 当前实现会调用 `LookAt`、`Up`。 +- 当前实现会调用 `Normalize`、`GetPosition`、`Magnitude`、`SetRotation`、`LookRotation`。 ## 相关文档 -- [返回类总览](TransformComponent.md) -- [返回模块目录](../Components.md) +- [TransformComponent](TransformComponent.md) diff --git a/docs/api/XCEngine/Components/TransformComponent/NotifyHierarchyChanged.md b/docs/api/XCEngine/Components/TransformComponent/NotifyHierarchyChanged.md index 1534b43b..0a17d254 100644 --- a/docs/api/XCEngine/Components/TransformComponent/NotifyHierarchyChanged.md +++ b/docs/api/XCEngine/Components/TransformComponent/NotifyHierarchyChanged.md @@ -1,30 +1,25 @@ # TransformComponent::NotifyHierarchyChanged -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/TransformComponent.h` + +## 签名 ```cpp void NotifyHierarchyChanged(); ``` -该方法声明于 `XCEngine/Components/TransformComponent.h`，当前页面用于固定 `TransformComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `SetDirty(...)` 相关流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::TransformComponent object; - // 根据上下文补齐参数后调用 TransformComponent::NotifyHierarchyChanged(...)。 - (void)object; -} -``` +- 当前实现会调用 `SetDirty`。 ## 相关文档 -- [返回类总览](TransformComponent.md) -- [返回模块目录](../Components.md) +- [TransformComponent](TransformComponent.md) diff --git a/docs/api/XCEngine/Components/TransformComponent/Rotate.md b/docs/api/XCEngine/Components/TransformComponent/Rotate.md index ee43075a..257f3926 100644 --- a/docs/api/XCEngine/Components/TransformComponent/Rotate.md +++ b/docs/api/XCEngine/Components/TransformComponent/Rotate.md @@ -1,47 +1,27 @@ # TransformComponent::Rotate -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Components` -该方法在 `XCEngine/Components/TransformComponent.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。 +**类型**: `method` -## 重载 1: 声明 +**头文件**: `XCEngine/Components/TransformComponent.h` + +## 签名 ```cpp void Rotate(const Math::Vector3& eulers, Space relativeTo = Space::Self); -``` - -**参数：** -- `eulers` - 参数语义详见头文件声明。 -- `relativeTo` - 参数语义详见头文件声明。 - -**返回：** `void` - 无返回值。 - -## 重载 2: 声明 - -```cpp void Rotate(const Math::Vector3& axis, float angle, Space relativeTo = Space::Self); ``` -**参数：** -- `axis` - 参数语义详见头文件声明。 -- `angle` - 参数语义详见头文件声明。 -- `relativeTo` - 参数语义详见头文件声明。 +## 作用 -**返回：** `void` - 无返回值。 +执行 `FromEulerAngles`、`SetRotation`、`GetRotation` 协同流程。 -**示例：** +## 当前实现 -```cpp -#include - -void Example() { - XCEngine::Components::TransformComponent object; - // 根据上下文补齐参数后调用 TransformComponent::Rotate(...)。 - (void)object; -} -``` +- 当前实现会调用 `FromEulerAngles`、`SetRotation`、`GetRotation`。 +- 当前实现会调用 `FromAxisAngle`、`SetRotation`、`GetRotation`。 ## 相关文档 -- [返回类总览](TransformComponent.md) -- [返回模块目录](../Components.md) +- [TransformComponent](TransformComponent.md) diff --git a/docs/api/XCEngine/Components/TransformComponent/Serialize.md b/docs/api/XCEngine/Components/TransformComponent/Serialize.md index 4680f41c..2683c0f7 100644 --- a/docs/api/XCEngine/Components/TransformComponent/Serialize.md +++ b/docs/api/XCEngine/Components/TransformComponent/Serialize.md @@ -1,31 +1,25 @@ # TransformComponent::Serialize -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/TransformComponent.h` + +## 签名 ```cpp void Serialize(std::ostream& os) const override; ``` -该方法声明于 `XCEngine/Components/TransformComponent.h`，当前页面用于固定 `TransformComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `os` - 参数语义详见头文件声明。 +执行 `Serialize` 对应的公开操作。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::TransformComponent object; - // 根据上下文补齐参数后调用 TransformComponent::Serialize(...)。 - (void)object; -} -``` +- 具体定义位于 `engine/src/Components/TransformComponent.cpp`。 ## 相关文档 -- [返回类总览](TransformComponent.md) -- [返回模块目录](../Components.md) +- [TransformComponent](TransformComponent.md) diff --git a/docs/api/XCEngine/Components/TransformComponent/SetAsFirstSibling.md b/docs/api/XCEngine/Components/TransformComponent/SetAsFirstSibling.md index ae60a66c..39faf622 100644 --- a/docs/api/XCEngine/Components/TransformComponent/SetAsFirstSibling.md +++ b/docs/api/XCEngine/Components/TransformComponent/SetAsFirstSibling.md @@ -1,30 +1,25 @@ # TransformComponent::SetAsFirstSibling -设置相关状态或配置。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/TransformComponent.h` + +## 签名 ```cpp void SetAsFirstSibling(); ``` -该方法声明于 `XCEngine/Components/TransformComponent.h`，当前页面用于固定 `TransformComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `SetSiblingIndex` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::TransformComponent object; - // 根据上下文补齐参数后调用 TransformComponent::SetAsFirstSibling(...)。 - (void)object; -} -``` +- 当前实现会调用 `SetSiblingIndex`。 ## 相关文档 -- [返回类总览](TransformComponent.md) -- [返回模块目录](../Components.md) +- [TransformComponent](TransformComponent.md) diff --git a/docs/api/XCEngine/Components/TransformComponent/SetAsLastSibling.md b/docs/api/XCEngine/Components/TransformComponent/SetAsLastSibling.md index 5164f601..0cb5c335 100644 --- a/docs/api/XCEngine/Components/TransformComponent/SetAsLastSibling.md +++ b/docs/api/XCEngine/Components/TransformComponent/SetAsLastSibling.md @@ -1,30 +1,26 @@ # TransformComponent::SetAsLastSibling -设置相关状态或配置。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/TransformComponent.h` + +## 签名 ```cpp void SetAsLastSibling(); ``` -该方法声明于 `XCEngine/Components/TransformComponent.h`，当前页面用于固定 `TransformComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_siblingIndex`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::TransformComponent object; - // 根据上下文补齐参数后调用 TransformComponent::SetAsLastSibling(...)。 - (void)object; -} -``` +- 会更新 `m_siblingIndex`。 +- 当前实现会调用 `GetChildCount`。 ## 相关文档 -- [返回类总览](TransformComponent.md) -- [返回模块目录](../Components.md) +- [TransformComponent](TransformComponent.md) diff --git a/docs/api/XCEngine/Components/TransformComponent/SetDirty.md b/docs/api/XCEngine/Components/TransformComponent/SetDirty.md index 8d7d722b..c85e40e9 100644 --- a/docs/api/XCEngine/Components/TransformComponent/SetDirty.md +++ b/docs/api/XCEngine/Components/TransformComponent/SetDirty.md @@ -1,30 +1,26 @@ # TransformComponent::SetDirty -设置相关状态或配置。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/TransformComponent.h` + +## 签名 ```cpp void SetDirty(); ``` -该方法声明于 `XCEngine/Components/TransformComponent.h`，当前页面用于固定 `TransformComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_dirty`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::TransformComponent object; - // 根据上下文补齐参数后调用 TransformComponent::SetDirty(...)。 - (void)object; -} -``` +- 会更新 `m_dirty`。 +- 当前实现会调用 `SetDirty`。 ## 相关文档 -- [返回类总览](TransformComponent.md) -- [返回模块目录](../Components.md) +- [TransformComponent](TransformComponent.md) diff --git a/docs/api/XCEngine/Components/TransformComponent/SetLocalEulerAngles.md b/docs/api/XCEngine/Components/TransformComponent/SetLocalEulerAngles.md index 25f871d9..dbccb36b 100644 --- a/docs/api/XCEngine/Components/TransformComponent/SetLocalEulerAngles.md +++ b/docs/api/XCEngine/Components/TransformComponent/SetLocalEulerAngles.md @@ -1,31 +1,27 @@ # TransformComponent::SetLocalEulerAngles -设置相关状态或配置。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/TransformComponent.h` + +## 签名 ```cpp void SetLocalEulerAngles(const Math::Vector3& eulers); ``` -该方法声明于 `XCEngine/Components/TransformComponent.h`，当前页面用于固定 `TransformComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `eulers` - 参数语义详见头文件声明。 +更新 `m_localRotation`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::TransformComponent object; - // 根据上下文补齐参数后调用 TransformComponent::SetLocalEulerAngles(...)。 - (void)object; -} -``` +- 会更新 `m_localRotation`。 +- 当前实现会调用 `FromEulerAngles`、`SetDirty`。 ## 相关文档 -- [返回类总览](TransformComponent.md) -- [返回模块目录](../Components.md) +- [TransformComponent](TransformComponent.md) +- [GetLocalEulerAngles](GetLocalEulerAngles.md) diff --git a/docs/api/XCEngine/Components/TransformComponent/SetLocalPosition.md b/docs/api/XCEngine/Components/TransformComponent/SetLocalPosition.md index 20da498d..90ac1ea0 100644 --- a/docs/api/XCEngine/Components/TransformComponent/SetLocalPosition.md +++ b/docs/api/XCEngine/Components/TransformComponent/SetLocalPosition.md @@ -1,31 +1,27 @@ # TransformComponent::SetLocalPosition -设置相关状态或配置。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/TransformComponent.h` + +## 签名 ```cpp void SetLocalPosition(const Math::Vector3& position); ``` -该方法声明于 `XCEngine/Components/TransformComponent.h`，当前页面用于固定 `TransformComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `position` - 参数语义详见头文件声明。 +更新 `m_localPosition`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::TransformComponent object; - // 根据上下文补齐参数后调用 TransformComponent::SetLocalPosition(...)。 - (void)object; -} -``` +- 会更新 `m_localPosition`。 +- 当前实现会调用 `SetDirty`。 ## 相关文档 -- [返回类总览](TransformComponent.md) -- [返回模块目录](../Components.md) +- [TransformComponent](TransformComponent.md) +- [GetLocalPosition](GetLocalPosition.md) diff --git a/docs/api/XCEngine/Components/TransformComponent/SetLocalRotation.md b/docs/api/XCEngine/Components/TransformComponent/SetLocalRotation.md index 7e415b05..36034cd3 100644 --- a/docs/api/XCEngine/Components/TransformComponent/SetLocalRotation.md +++ b/docs/api/XCEngine/Components/TransformComponent/SetLocalRotation.md @@ -1,31 +1,27 @@ # TransformComponent::SetLocalRotation -设置相关状态或配置。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/TransformComponent.h` + +## 签名 ```cpp void SetLocalRotation(const Math::Quaternion& rotation); ``` -该方法声明于 `XCEngine/Components/TransformComponent.h`，当前页面用于固定 `TransformComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `rotation` - 参数语义详见头文件声明。 +更新 `m_localRotation`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::TransformComponent object; - // 根据上下文补齐参数后调用 TransformComponent::SetLocalRotation(...)。 - (void)object; -} -``` +- 会更新 `m_localRotation`。 +- 当前实现会调用 `SetDirty`。 ## 相关文档 -- [返回类总览](TransformComponent.md) -- [返回模块目录](../Components.md) +- [TransformComponent](TransformComponent.md) +- [GetLocalRotation](GetLocalRotation.md) diff --git a/docs/api/XCEngine/Components/TransformComponent/SetLocalScale.md b/docs/api/XCEngine/Components/TransformComponent/SetLocalScale.md index 5fcdcdf2..217aa914 100644 --- a/docs/api/XCEngine/Components/TransformComponent/SetLocalScale.md +++ b/docs/api/XCEngine/Components/TransformComponent/SetLocalScale.md @@ -1,31 +1,27 @@ # TransformComponent::SetLocalScale -设置相关状态或配置。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/TransformComponent.h` + +## 签名 ```cpp void SetLocalScale(const Math::Vector3& scale); ``` -该方法声明于 `XCEngine/Components/TransformComponent.h`，当前页面用于固定 `TransformComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `scale` - 参数语义详见头文件声明。 +更新 `m_localScale`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::TransformComponent object; - // 根据上下文补齐参数后调用 TransformComponent::SetLocalScale(...)。 - (void)object; -} -``` +- 会更新 `m_localScale`。 +- 当前实现会调用 `SetDirty`。 ## 相关文档 -- [返回类总览](TransformComponent.md) -- [返回模块目录](../Components.md) +- [TransformComponent](TransformComponent.md) +- [GetLocalScale](GetLocalScale.md) diff --git a/docs/api/XCEngine/Components/TransformComponent/SetParent.md b/docs/api/XCEngine/Components/TransformComponent/SetParent.md index 2fe2208c..6a30937a 100644 --- a/docs/api/XCEngine/Components/TransformComponent/SetParent.md +++ b/docs/api/XCEngine/Components/TransformComponent/SetParent.md @@ -1,32 +1,27 @@ # TransformComponent::SetParent -设置相关状态或配置。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/TransformComponent.h` + +## 签名 ```cpp void SetParent(TransformComponent* parent, bool worldPositionStays = true); ``` -该方法声明于 `XCEngine/Components/TransformComponent.h`，当前页面用于固定 `TransformComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `parent` - 参数语义详见头文件声明。 -- `worldPositionStays` - 参数语义详见头文件声明。 +执行 `GetPosition`、`GetRotation`、`GetScale` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::TransformComponent object; - // 根据上下文补齐参数后调用 TransformComponent::SetParent(...)。 - (void)object; -} -``` +- 会更新 `m_parent`、`m_localRotation`。 +- 当前实现会调用 `GetPosition`、`GetRotation`、`GetScale`、`erase`、`remove`。 ## 相关文档 -- [返回类总览](TransformComponent.md) -- [返回模块目录](../Components.md) +- [TransformComponent](TransformComponent.md) +- [GetParent](GetParent.md) diff --git a/docs/api/XCEngine/Components/TransformComponent/SetPosition.md b/docs/api/XCEngine/Components/TransformComponent/SetPosition.md index 0820a2e7..4f7c5c6e 100644 --- a/docs/api/XCEngine/Components/TransformComponent/SetPosition.md +++ b/docs/api/XCEngine/Components/TransformComponent/SetPosition.md @@ -1,31 +1,27 @@ # TransformComponent::SetPosition -设置相关状态或配置。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/TransformComponent.h` + +## 签名 ```cpp void SetPosition(const Math::Vector3& position); ``` -该方法声明于 `XCEngine/Components/TransformComponent.h`，当前页面用于固定 `TransformComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `position` - 参数语义详见头文件声明。 +更新 `m_localPosition`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::TransformComponent object; - // 根据上下文补齐参数后调用 TransformComponent::SetPosition(...)。 - (void)object; -} -``` +- 会更新 `m_localPosition`。 +- 当前实现会调用 `GetWorldToLocalMatrix`、`MultiplyPoint`、`SetDirty`。 ## 相关文档 -- [返回类总览](TransformComponent.md) -- [返回模块目录](../Components.md) +- [TransformComponent](TransformComponent.md) +- [GetPosition](GetPosition.md) diff --git a/docs/api/XCEngine/Components/TransformComponent/SetRotation.md b/docs/api/XCEngine/Components/TransformComponent/SetRotation.md index 0f3e919e..c43ef940 100644 --- a/docs/api/XCEngine/Components/TransformComponent/SetRotation.md +++ b/docs/api/XCEngine/Components/TransformComponent/SetRotation.md @@ -1,31 +1,27 @@ # TransformComponent::SetRotation -设置相关状态或配置。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/TransformComponent.h` + +## 签名 ```cpp void SetRotation(const Math::Quaternion& rotation); ``` -该方法声明于 `XCEngine/Components/TransformComponent.h`，当前页面用于固定 `TransformComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `rotation` - 参数语义详见头文件声明。 +更新 `m_localRotation`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::TransformComponent object; - // 根据上下文补齐参数后调用 TransformComponent::SetRotation(...)。 - (void)object; -} -``` +- 会更新 `m_localRotation`。 +- 当前实现会调用 `GetRotation`、`Inverse`、`SetDirty`。 ## 相关文档 -- [返回类总览](TransformComponent.md) -- [返回模块目录](../Components.md) +- [TransformComponent](TransformComponent.md) +- [GetRotation](GetRotation.md) diff --git a/docs/api/XCEngine/Components/TransformComponent/SetScale.md b/docs/api/XCEngine/Components/TransformComponent/SetScale.md index 45974231..25128c9a 100644 --- a/docs/api/XCEngine/Components/TransformComponent/SetScale.md +++ b/docs/api/XCEngine/Components/TransformComponent/SetScale.md @@ -1,31 +1,27 @@ # TransformComponent::SetScale -设置相关状态或配置。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/TransformComponent.h` + +## 签名 ```cpp void SetScale(const Math::Vector3& scale); ``` -该方法声明于 `XCEngine/Components/TransformComponent.h`，当前页面用于固定 `TransformComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `scale` - 参数语义详见头文件声明。 +更新 `m_localScale`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::TransformComponent object; - // 根据上下文补齐参数后调用 TransformComponent::SetScale(...)。 - (void)object; -} -``` +- 会更新 `m_localScale`。 +- 当前实现会调用 `GetScale`、`Vector3`、`SetDirty`。 ## 相关文档 -- [返回类总览](TransformComponent.md) -- [返回模块目录](../Components.md) +- [TransformComponent](TransformComponent.md) +- [GetScale](GetScale.md) diff --git a/docs/api/XCEngine/Components/TransformComponent/SetSiblingIndex.md b/docs/api/XCEngine/Components/TransformComponent/SetSiblingIndex.md index 562d8b38..778fe5da 100644 --- a/docs/api/XCEngine/Components/TransformComponent/SetSiblingIndex.md +++ b/docs/api/XCEngine/Components/TransformComponent/SetSiblingIndex.md @@ -1,31 +1,26 @@ # TransformComponent::SetSiblingIndex -设置相关状态或配置。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/TransformComponent.h` + +## 签名 ```cpp void SetSiblingIndex(int index); ``` -该方法声明于 `XCEngine/Components/TransformComponent.h`，当前页面用于固定 `TransformComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `index` - 参数语义详见头文件声明。 +更新 `m_siblingIndex`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::TransformComponent object; - // 根据上下文补齐参数后调用 TransformComponent::SetSiblingIndex(...)。 - (void)object; -} -``` +- 会更新 `m_siblingIndex`。 ## 相关文档 -- [返回类总览](TransformComponent.md) -- [返回模块目录](../Components.md) +- [TransformComponent](TransformComponent.md) +- [GetSiblingIndex](GetSiblingIndex.md) diff --git a/docs/api/XCEngine/Components/TransformComponent/TransformDirection.md b/docs/api/XCEngine/Components/TransformComponent/TransformDirection.md index 9f5619c3..f563e406 100644 --- a/docs/api/XCEngine/Components/TransformComponent/TransformDirection.md +++ b/docs/api/XCEngine/Components/TransformComponent/TransformDirection.md @@ -1,31 +1,25 @@ # TransformComponent::TransformDirection -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/TransformComponent.h` + +## 签名 ```cpp Math::Vector3 TransformDirection(const Math::Vector3& direction) const; ``` -该方法声明于 `XCEngine/Components/TransformComponent.h`，当前页面用于固定 `TransformComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `direction` - 参数语义详见头文件声明。 +执行 `TransformDirection` 对应的公开操作。 -**返回：** `Math::Vector3` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::TransformComponent object; - // 根据上下文补齐参数后调用 TransformComponent::TransformDirection(...)。 - (void)object; -} -``` +- 具体定义位于 `engine/src/Components/TransformComponent.cpp`。 ## 相关文档 -- [返回类总览](TransformComponent.md) -- [返回模块目录](../Components.md) +- [TransformComponent](TransformComponent.md) diff --git a/docs/api/XCEngine/Components/TransformComponent/TransformPoint.md b/docs/api/XCEngine/Components/TransformComponent/TransformPoint.md index 3f348430..fd212f06 100644 --- a/docs/api/XCEngine/Components/TransformComponent/TransformPoint.md +++ b/docs/api/XCEngine/Components/TransformComponent/TransformPoint.md @@ -1,31 +1,25 @@ # TransformComponent::TransformPoint -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/TransformComponent.h` + +## 签名 ```cpp Math::Vector3 TransformPoint(const Math::Vector3& point) const; ``` -该方法声明于 `XCEngine/Components/TransformComponent.h`，当前页面用于固定 `TransformComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `point` - 参数语义详见头文件声明。 +执行 `TransformPoint` 对应的公开操作。 -**返回：** `Math::Vector3` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::TransformComponent object; - // 根据上下文补齐参数后调用 TransformComponent::TransformPoint(...)。 - (void)object; -} -``` +- 具体定义位于 `engine/src/Components/TransformComponent.cpp`。 ## 相关文档 -- [返回类总览](TransformComponent.md) -- [返回模块目录](../Components.md) +- [TransformComponent](TransformComponent.md) diff --git a/docs/api/XCEngine/Components/TransformComponent/Translate.md b/docs/api/XCEngine/Components/TransformComponent/Translate.md index 4385f692..dcc76abe 100644 --- a/docs/api/XCEngine/Components/TransformComponent/Translate.md +++ b/docs/api/XCEngine/Components/TransformComponent/Translate.md @@ -1,32 +1,25 @@ # TransformComponent::Translate -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/TransformComponent.h` + +## 签名 ```cpp void Translate(const Math::Vector3& translation, Space relativeTo = Space::Self); ``` -该方法声明于 `XCEngine/Components/TransformComponent.h`，当前页面用于固定 `TransformComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `translation` - 参数语义详见头文件声明。 -- `relativeTo` - 参数语义详见头文件声明。 +执行 `SetPosition`、`GetPosition`、`TransformDirection` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::TransformComponent object; - // 根据上下文补齐参数后调用 TransformComponent::Translate(...)。 - (void)object; -} -``` +- 当前实现会调用 `SetPosition`、`GetPosition`、`TransformDirection`。 ## 相关文档 -- [返回类总览](TransformComponent.md) -- [返回模块目录](../Components.md) +- [TransformComponent](TransformComponent.md) diff --git a/docs/api/XCEngine/Components/TransformComponent/UpdateWorldTransform.md b/docs/api/XCEngine/Components/TransformComponent/UpdateWorldTransform.md index dde87117..47de36bc 100644 --- a/docs/api/XCEngine/Components/TransformComponent/UpdateWorldTransform.md +++ b/docs/api/XCEngine/Components/TransformComponent/UpdateWorldTransform.md @@ -1,30 +1,25 @@ # TransformComponent::UpdateWorldTransform -更新运行时状态。 +**命名空间**: `XCEngine::Components` + +**类型**: `method` + +**头文件**: `XCEngine/Components/TransformComponent.h` + +## 签名 ```cpp void UpdateWorldTransform() const; ``` -该方法声明于 `XCEngine/Components/TransformComponent.h`，当前页面用于固定 `TransformComponent` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行一次 `UpdateWorldTransform` 更新。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Components::TransformComponent object; - // 根据上下文补齐参数后调用 TransformComponent::UpdateWorldTransform(...)。 - (void)object; -} -``` +- 具体定义位于 `engine/src/Components/TransformComponent.cpp`。 ## 相关文档 -- [返回类总览](TransformComponent.md) -- [返回模块目录](../Components.md) +- [TransformComponent](TransformComponent.md) diff --git a/docs/api/XCEngine/Core/Asset/ArtifactFormats/ArtifactFormats.md b/docs/api/XCEngine/Core/Asset/ArtifactFormats/ArtifactFormats.md index b550b338..b7f475f3 100644 --- a/docs/api/XCEngine/Core/Asset/ArtifactFormats/ArtifactFormats.md +++ b/docs/api/XCEngine/Core/Asset/ArtifactFormats/ArtifactFormats.md @@ -27,9 +27,10 @@ ## 当前 schema 常量 - `kTextureArtifactSchemaVersion = 1` -- `kMaterialArtifactSchemaVersion = 2` +- `kMaterialArtifactSchemaVersion = 4` - `kMeshArtifactSchemaVersion = 2` -- `kShaderArtifactSchemaVersion = 1` +- `kShaderArtifactSchemaVersion = 4` +- `kUIDocumentArtifactSchemaVersion = 2` ## Texture artifact: `.xctex` @@ -57,8 +58,8 @@ - 文件头: `MaterialArtifactFileHeader` - 主头结构: `MaterialArtifactHeader` - 属性结构: `MaterialPropertyArtifact` -- schema: `2` -- magic: `XCMAT02` +- schema: `4` +- magic: `XCMAT04` ### 当前正文布局 @@ -71,8 +72,9 @@ 5. shader pass 字符串 6. `MaterialArtifactHeader` 7. `tagCount` 对 tag 名/值字符串 -8. `propertyCount` 个属性名字符串 + `MaterialPropertyArtifact` -9. `textureBindingCount` 组 texture binding 三元组： +8. `keywordCount` 个 keyword 字符串 +9. `propertyCount` 个属性名字符串 + `MaterialPropertyArtifact` +10. `textureBindingCount` 组 texture binding 三元组： - binding name - 编码后的 `AssetRef` 字符串 - 可选 texture path 字符串 @@ -84,6 +86,8 @@ - `renderQueue` - `renderState` - `tagCount` +- `hasRenderStateOverride` +- `keywordCount` - `propertyCount` - `textureBindingCount` @@ -96,7 +100,16 @@ 当前 writer 只把非 texture 属性写进 property 段；texture / cubemap 绑定统一走 texture binding 段。 -### texture binding v2 语义 +### render-state override 语义 + +`MaterialArtifactHeader::hasRenderStateOverride` 当前显式区分两种情况： + +- 材质真的声明了 `renderState` +- 材质只是保留了一份默认 `MaterialRenderState` 缓存 + +回读侧 `MaterialLoader` 当前会据此恢复 `HasRenderStateOverride()`。 + +### texture binding 语义 texture binding 当前不再只保存 path。 @@ -124,7 +137,7 @@ path 的求值优先级当前是： - 有效 `AssetRef` 优先走 `Material::SetTextureAssetRef(...)` - 否则退到 `Material::SetTexturePath(...)` -这意味着 `.xcmat` v2 可以只靠 `AssetRef` 恢复稳定引用，path 只作为可选辅助信息存在。 +这意味着当前 `.xcmat` 版本可以只靠 `AssetRef` 恢复稳定引用，path 只作为可选辅助信息存在。 ## Mesh artifact: `.xcmesh` @@ -162,9 +175,75 @@ path 的求值优先级当前是： - 属性结构: `ShaderPropertyArtifact` - 资源结构: `ShaderResourceArtifact` - variant 头结构: `ShaderVariantArtifactHeader` -- magic: `XCSHD01` +- schema: `4` +- magic: `XCSHD04` -当前 `ArtifactFormats.h` 已经把 shader artifact 的头结构一起纳入契约。 +### 当前正文布局 + +`.xcshader` 当前采用“文件头 + 名称/路径字符串 + 逻辑 shader 头 + property 段 + pass 段”的顺序写出： + +1. `ShaderArtifactFileHeader` +2. shader 名称字符串 +3. source shader 路径字符串 +4. fallback 字符串 +5. `ShaderArtifactHeader` +6. `propertyCount` 组 property 数据： + - property 名称字符串 + - display name 字符串 + - default value 字符串 + - semantic 字符串 + - `ShaderPropertyArtifact` +7. `passCount` 组 pass 数据： + - pass 名称字符串 + - `ShaderPassArtifactHeaderV4` + - `tagCount` 对 tag 名/值字符串 + - `resourceCount` 组资源绑定： + - resource 名称字符串 + - semantic 字符串 + - `ShaderResourceArtifact` + - `keywordDeclarationCount` 组 keyword 声明： + - `ShaderKeywordDeclarationArtifactHeader` + - `optionCount` 个 option 字符串 + - `variantCount` 组 stage variant： + - `ShaderVariantArtifactHeader` + - entry point 字符串 + - profile 字符串 + - source code 字符串 + - `keywordCount` 个 required keyword 字符串 + - 可选 `compiledBinary` payload（长度由 `compiledBinarySize` 指定） + +### 各头结构当前记录 + +- `ShaderArtifactHeader` + - `propertyCount` + - `passCount` +- `ShaderPassArtifactHeader` + - `tagCount` + - `resourceCount` + - `keywordDeclarationCount` + - `variantCount` +- `ShaderPassArtifactHeaderV4` + - `tagCount` + - `resourceCount` + - `keywordDeclarationCount` + - `variantCount` + - `hasFixedFunctionState` + - `fixedFunctionState` +- `ShaderPropertyArtifact` + - `propertyType` +- `ShaderResourceArtifact` + - `resourceType` + - `set` + - `binding` +- `ShaderVariantArtifactHeader` + - `stage` + - `language` + - `backend` + - `keywordCount` + - `compiledBinarySize` +- `ShaderKeywordDeclarationArtifactHeader` + - `declarationType` + - `optionCount` ## 导入与消费链路 @@ -173,7 +252,7 @@ path 的求值优先级当前是： - `AssetDatabase::ImportTextureAsset()` 产出 `main.xctex` - `AssetDatabase::ImportMaterialAsset()` 产出 `main.xcmat` - `AssetDatabase::ImportModelAsset()` 产出 `main.xcmesh` -- `AssetDatabase::ImportShaderAsset()` 产出 shader artifact +- `AssetDatabase::ImportShaderAsset()` 产出 `main.xcshader` 模型导入还会在同一个 artifact 目录里附带生成： @@ -185,6 +264,7 @@ path 的求值优先级当前是： - `TextureLoader` 回读 `.xctex` - `MaterialLoader` 回读 `.xcmat` - `MeshLoader` 回读 `.xcmesh` +- `ShaderLoader` 回读 `.xcshader` `ResourceManager::LoadResource()` 在项目模式下会先经 `AssetImportService::EnsureArtifact()` 准备 `ImportedAsset`，再把 `runtimeLoadPath` 交给具体 loader。 diff --git a/docs/api/XCEngine/Core/Asset/Asset.md b/docs/api/XCEngine/Core/Asset/Asset.md index 9fe42315..b99f01f1 100644 --- a/docs/api/XCEngine/Core/Asset/Asset.md +++ b/docs/api/XCEngine/Core/Asset/Asset.md @@ -37,7 +37,7 @@ Assets/... source files - `ProjectAssetIndex::TryGetAssetRef()` 当前会优先查本地 snapshot，cache miss 时再回退到 `AssetImportService`；必要时会先 `Refresh()` 数据库再整体重建 snapshot。 - `ProjectAssetIndex::TryResolveAssetPath()` 当前同样优先查 snapshot，但 miss 时只回退到 `AssetImportService::TryGetPrimaryAssetPath()`，不会主动刷新整份 snapshot。 - `engine/src/Resources/Material/MaterialLoader.cpp` 现在已经把材质纹理路径解析、`.xcmat` 中的 texture `AssetRef` 回读，以及首次访问时的懒加载纳入真实行为范围，因此 `AssetDatabase` 的材质依赖快照不再只是预留设计。 -- `.xcmat` 当前已经是 material artifact v2：texture binding 会同时写出编码后的 `AssetRef` 和可选路径字符串，后续由 `MaterialLoader` 与 `Material` 协作懒解析成真正贴图句柄。 +- `.xcmat` 当前已经是 material artifact v4：texture binding 会同时写出编码后的 `AssetRef` 和可选路径字符串，并额外保存 `hasRenderStateOverride` 与 keywords，后续由 `MaterialLoader` 与 `Material` 协作懒解析成真正贴图句柄。 ## 设计要点 diff --git a/docs/api/XCEngine/Core/Asset/AssetDatabase/AssetDatabase.md b/docs/api/XCEngine/Core/Asset/AssetDatabase/AssetDatabase.md index 497b6a0f..905199b3 100644 --- a/docs/api/XCEngine/Core/Asset/AssetDatabase/AssetDatabase.md +++ b/docs/api/XCEngine/Core/Asset/AssetDatabase/AssetDatabase.md @@ -6,87 +6,87 @@ **头文件**: `XCEngine/Core/Asset/AssetDatabase.h` -**描述**: 管理项目 `Assets` 目录里的 source asset、`.meta` sidecar、source/artifact 快照以及 artifact 导入结果的项目资产数据库。 +**描述**: 管理项目 `Assets` 目录里的 source asset、`.meta` sidecar、source/artifact 快照，以及 artifact 导入结果的项目资产数据库。 ## 概览 `AssetDatabase` 处理的是“项目资产”和“artifact 索引”，而不是已经加载进内存的运行时资源实例。 -它当前的真实职责是: +它当前的真实职责是： -1. 扫描项目根目录下的 `Assets` -2. 为每个 source asset 或文件夹确保存在 `.meta` sidecar，并维持稳定 GUID -3. 保存 source 侧快照和 artifact 侧快照 -4. 在需要时把 source asset 导入到 `Library/Artifacts///...` -5. 为 [AssetImportService](../AssetImportService/AssetImportService.md) 和 [ProjectAssetIndex](../ProjectAssetIndex/ProjectAssetIndex.md) 提供 GUID / 路径查询与 lookup snapshot +1. 扫描项目 `Assets` +2. 为每个 source asset 或文件夹维护稳定 `.meta` 与 GUID +3. 维护 source 快照和 artifact 快照 +4. 在按需导入或显式重导时，把 source asset 导入到 `Library/Artifacts///...` +5. 向上游提供路径解析、GUID 查询、可导入类型探测、显式重导与 lookup snapshot 导出能力 -当前它并不直接暴露给 `ResourceManager` 调用点，而是经 `AssetImportService` 包装后再进入运行时路径。 +当前它并不直接暴露给 `ResourceManager`；运行时与编辑器通常都通过 [AssetImportService](../AssetImportService/AssetImportService.md) 间接访问。 ## 生命周期 - [Initialize](Initialize.md) 设置项目根、`Assets` 根和 `Library` 根，确保目录结构存在，然后加载 source/artifact 数据库并扫描当前资产树。 - [Refresh](Refresh.md) - 重新扫描 `Assets` 并更新 source 记录，不会批量重导 artifact。 + 重新扫描 `Assets`、维护 source 快照并清理孤儿 artifact；当前返回 [MaintenanceStats](MaintenanceStats.md)。 - [Shutdown](Shutdown.md) - 把 source/artifact 两份数据库写回磁盘，然后清空内存状态。 + 写回 source/artifact 数据库，然后清空内存状态。 -当前 `AssetDatabase` 自身没有内部锁。线程同步由外层 [AssetImportService](../AssetImportService/AssetImportService.md) 的 `recursive_mutex` 提供。 +`AssetDatabase` 自身没有内部锁。线程同步当前由外层 [AssetImportService](../AssetImportService/AssetImportService.md) 的 `recursive_mutex` 提供。 ## 持久化布局 ### Source 侧 - 每个 source asset 或文件夹都对应一个 `.meta` sidecar -- `.meta` 当前记录: +- `.meta` 当前记录： - `guid` - `folderAsset` - `importer` - `importerVersion` -- `Library/SourceAssetDB/assets.db` 保存 `SourceAssetRecord` 快照 +- `Library/SourceAssetDB/assets.db` 保存 [SourceAssetRecord](SourceAssetRecord.md) 快照 `assets.db` 当前是制表符分隔的文本快照，而不是二进制数据库。 ### Artifact 侧 -- `Library/ArtifactDB/artifacts.db` 保存 `ArtifactRecord` 快照 -- artifact 目录按 `artifactKey` 前两位分片: +- `Library/ArtifactDB/artifacts.db` 保存 [ArtifactRecord](ArtifactRecord.md) 快照 +- artifact 目录按 `artifactKey` 前两位分片： - `Library/Artifacts/<2-char-shard>//...` -- 主 artifact 文件当前约定为: +- 主 artifact 文件当前约定： - 纹理: `main.xctex` - 材质: `main.xcmat` - 模型: `main.xcmesh` - Shader: `main.xcshader` -模型 artifact 还会在同一目录下产出内嵌材质和纹理 artifact，例如 `material_0.xcmat`、`texture_0.xctex`。 - -`artifacts.db` 当前同样是文本快照，依赖记录以附加字段顺序存储。 +模型 artifact 还会在同一目录下写出内嵌材质和贴图 artifact，例如 `material_0.xcmat`、`texture_0.xctex`。 ## 查询与快照链路 ### 路径解析 -- [ResolvePath](ResolvePath.md) 只把项目内 `Assets/...` 或可相对当前项目根还原为 `Assets/...` 的绝对路径视为正式项目资产路径 -- 带 `://` 的虚拟路径会直接失败，不进入项目资产数据库 -- 其他普通相对路径虽然可以被展开为绝对路径，但 `relativePath` 会保持为空，因此不会被认作正式项目资产 +- [ResolvePath](ResolvePath.md) 只把项目内 `Assets/...`，或能还原成 `Assets/...` 的绝对路径视为正式项目资产路径。 +- 带 `://` 的虚拟路径会直接失败，不进入项目资产数据库。 +- 普通相对路径虽然可以被展开成绝对路径，但如果无法得到 `Assets/...` 相对路径，就不会被当作正式项目资产。 -### GUID 与 `AssetRef` +### GUID、类型探测与 `AssetRef` - [TryGetAssetGuid](TryGetAssetGuid.md) - 通过规范化、大小写无关的 `Assets/...` 路径 key 查 GUID + 通过规范化、大小写无关的 `Assets/...` path key 查询 GUID。 +- [TryGetImportableResourceType](TryGetImportableResourceType.md) + 返回当前 importer 的 primary `ResourceType`；目录、项目外路径和 `Unknown` importer 都直接失败。 - [TryGetAssetRef](TryGetAssetRef.md) - 只是把 GUID 包装成主资产 `AssetRef`，并原样写入调用方给定的 `ResourceType` + 只是把 GUID 包装成主资产 `AssetRef`，并原样写入调用方指定的 `ResourceType`。 - [TryGetPrimaryAssetPath](TryGetPrimaryAssetPath.md) - 做 GUID 到主 source 路径的反查 + 做 GUID 到主 source 路径的反查。 ### Lookup snapshot -[BuildLookupSnapshot](BuildLookupSnapshot.md) 会从当前 source 快照导出两张查找表: +[BuildLookupSnapshot](BuildLookupSnapshot.md) 会从当前 source 快照导出两张表： - `pathKey -> AssetGUID` - `AssetGUID -> relativePath` -它不做扫描，也不触发导入。当前真实链路是: +它不扫描磁盘，也不触发导入。当前真实链路是： ```text AssetDatabase::BuildLookupSnapshot @@ -97,22 +97,22 @@ AssetDatabase::BuildLookupSnapshot ## 导入与重导链路 -### 当前导入器映射 +### 当前 importer 映射 -| importer | 扩展名/来源 | 主资源类型 | 当前 artifact | +| importer | 扩展名/来源 | 主资源类型 | 当前主 artifact | |------|------|------|------| | `TextureImporter` | `.png` `.jpg` `.jpeg` `.bmp` `.tga` `.gif` `.hdr` | `Texture` | `main.xctex` | | `MaterialImporter` | `.mat` `.material` `.json` | `Material` | `main.xcmat` | -| `ModelImporter` | `.obj` `.fbx` `.gltf` `.glb` `.dae` `.stl` | `Mesh` | `main.xcmesh` + 内嵌材质/纹理 artifact | +| `ModelImporter` | `.obj` `.fbx` `.gltf` `.glb` `.dae` `.stl` | `Mesh` | `main.xcmesh` + 内嵌材质/贴图 artifact | | `ShaderImporter` | `.shader` `.hlsl` `.glsl` `.vert` `.frag` `.geom` `.comp` | `Shader` | `main.xcshader` | -| `FolderImporter` | 文件夹 | `Unknown` | 无 artifact | -| `DefaultImporter` | 其他扩展名 | `Unknown` | 无 artifact | +| `FolderImporter` | 文件夹 | `Unknown` | 无 | +| `DefaultImporter` | 其他扩展名 | `Unknown` | 无 | -`SourceAssetRecord::importerVersion` 当前统一取头文件里的 `kCurrentImporterVersion`。按 `engine/include/XCEngine/Core/Asset/AssetDatabase.h` 的当前定义，这个值是 `5`。 +[SourceAssetRecord](SourceAssetRecord.md) 的 `importerVersion` 当前统一取头文件里的 `kCurrentImporterVersion`，现在是 `5`。 -### 重导入判定 +### 重导判定 -`ShouldReimport()` 当前会在以下任一条件满足时要求重导入: +`ShouldReimport()` 当前会在以下任一条件满足时要求重导： - 没有现存 `ArtifactRecord` - `artifactKey` 或 `mainArtifactPath` 为空 @@ -123,70 +123,29 @@ AssetDatabase::BuildLookupSnapshot - source 文件大小或写时间变化 - 任一依赖文件快照不再匹配 -因此当前 artifact key 并不是唯一判定条件；真正的重导入 gate 是一组 source / meta / dependency snapshot。 +因此当前 artifact key 不是唯一 gate，真正的重导判定是一组 source / meta / dependency snapshot 联合判断。 -### `EnsureArtifact()` +### 公开导入入口 -[EnsureArtifact](EnsureArtifact.md) 是当前最关键的入口。它会: +- [EnsureArtifact](EnsureArtifact.md) + 按需保证单个 source asset 的主 artifact 可用；只有命中 `ShouldReimport()` 时才真正重建。 +- [ReimportAsset](ReimportAsset.md) + 强制重导单个 source asset，并返回最新主 artifact 的 [ResolvedAsset](ResolvedAsset.md)。 +- [ReimportAllAssets](ReimportAllAssets.md) + 强制重导当前 source 快照里的全部可导入记录；单个条目失败不会中断整轮循环。 -1. 解析请求路径并确认它落在项目 `Assets` 下 -2. 检查 source 文件是否存在 -3. 调用 `EnsureMetaForPath()`，确保 source 记录、GUID、`.meta` 和 importerVersion 有效 -4. 根据 importer 推导主资源类型，并检查是否与 `requestedType` 一致 -5. 查找已有 `ArtifactRecord` -6. 若 `ShouldReimport()` 要求重建，则同步调用对应 importer: - - 纹理 -> `ImportTextureAsset()` - - 材质 -> `ImportMaterialAsset()` - - 模型 -> `ImportModelAsset()` - - Shader -> `ImportShaderAsset()` -7. 成功后更新 `m_artifactsByGuid`，并把 `lastKnownArtifactKey` 回写到两份 source 记录索引 -8. 调用 `SaveArtifactDB()` 和 `SaveSourceAssetDB()` 持久化结果 -9. 把 source 绝对路径、相对路径、GUID、artifact 绝对目录和主 artifact 绝对路径写入 `ResolvedAsset` +### `Refresh()` 与显式重导的区别 -### 材质 artifact 写入 - -`ImportMaterialAsset()` 当前不是简单把 source 文件原样拷进 `Library`。 - -它的真实路径是: - -1. 用 `MaterialLoader` 先把 source 材质解析成运行时 `Material` -2. 通过 `CollectMaterialDependencies()` 收集 shader 和 texture binding 依赖快照 -3. 基于 source/meta/dependencies 生成新的 `artifactKey` -4. 调用 `WriteMaterialArtifactFile(...)` 写出 `main.xcmat` - -当前写出的 `.xcmat` 已经是 v2: - -- magic `XCMAT02` -- schema version `2` -- texture binding 段同时保存编码 `AssetRef` 与可选 path - -这让 artifact 可以同时保留: - -- 稳定的项目资产身份 -- 当前可用的定位 path - -### 依赖快照 - -`ArtifactDependencyRecord` 当前已经进入真实行为范围，不再只是预留结构。 - -- 材质导入会通过 `CollectMaterialDependencies()` 收集: - - shader path - - 每个 texture binding 的 path -- 模型导入会通过 `CollectModelDependencies()` 收集: - - `obj -> mtl` 声明依赖 - - `mtl -> texture` 声明依赖 - - 导入后 mesh 暴露出的纹理路径 -- Shader 导入会通过 `CollectShaderDependencies()` 收集 shader manifest 和 `ShaderLoader::CollectSourceDependencies()` 解析出的源码依赖 -- `AreDependenciesCurrent()` 会同时比较文件是否存在、大小、写时间和内容哈希 - -这意味着贴图、`.mtl`、shader manifest、shader 源文件或其他已记录依赖变化时，当前都会触发新的 artifact 重建。 +- [Refresh](Refresh.md) 是“扫描 + 清理”入口，返回 [MaintenanceStats](MaintenanceStats.md)，但当前不主动重建 artifact。 +- [ReimportAsset](ReimportAsset.md) 和 [ReimportAllAssets](ReimportAllAssets.md) 才是显式重导入口，它们会真正调用 importer 重写 artifact。 ## 公开数据结构 +- [MaintenanceStats](MaintenanceStats.md) - 一次维护操作的汇总统计 - [ArtifactDependencyRecord](ArtifactDependencyRecord.md) - 单个依赖文件的快照记录 - [SourceAssetRecord](SourceAssetRecord.md) - source 资产记录 - [ArtifactRecord](ArtifactRecord.md) - artifact 数据库记录 -- [ResolvedAsset](ResolvedAsset.md) - `EnsureArtifact()` 返回给调用方的解析结果 +- [ResolvedAsset](ResolvedAsset.md) - `EnsureArtifact()` 与 `ReimportAsset()` 返回给调用方的解析结果 ## 公开方法 @@ -194,11 +153,14 @@ AssetDatabase::BuildLookupSnapshot |------|------| | [Initialize](Initialize.md) | 初始化项目根与数据库状态。 | | [Shutdown](Shutdown.md) | 写回数据库并清理内存状态。 | -| [Refresh](Refresh.md) | 重新扫描 `Assets`。 | +| [Refresh](Refresh.md) | 重新扫描 `Assets` 并返回维护统计。 | | [ResolvePath](ResolvePath.md) | 解析请求路径到绝对/相对项目路径。 | -| [TryGetAssetGuid](TryGetAssetGuid.md) | 通过路径查 GUID。 | +| [TryGetAssetGuid](TryGetAssetGuid.md) | 通过路径查询 GUID。 | +| [TryGetImportableResourceType](TryGetImportableResourceType.md) | 探测当前 importer 的主资源类型。 | | [TryGetAssetRef](TryGetAssetRef.md) | 通过路径组装主资产 `AssetRef`。 | -| [EnsureArtifact](EnsureArtifact.md) | 确保 source asset 对应的 artifact 可用。 | +| [ReimportAsset](ReimportAsset.md) | 强制重导单个 project asset。 | +| [ReimportAllAssets](ReimportAllAssets.md) | 强制重导当前快照里的全部可导入资产。 | +| [EnsureArtifact](EnsureArtifact.md) | 确保 source asset 对应的主 artifact 可用。 | | [TryGetPrimaryAssetPath](TryGetPrimaryAssetPath.md) | 通过 GUID 反查主 source 路径。 | | [BuildLookupSnapshot](BuildLookupSnapshot.md) | 导出 path/GUID lookup snapshot。 | | [GetProjectRoot](GetProjectRoot.md) | 获取项目根目录。 | @@ -207,19 +169,21 @@ AssetDatabase::BuildLookupSnapshot ## 真实使用位置 -- [AssetImportService](../AssetImportService/AssetImportService.md) 当前持有 `AssetDatabase`，并负责所有外部访问的加锁与项目根切换 -- [ProjectAssetIndex](../ProjectAssetIndex/ProjectAssetIndex.md) 通过 `BuildLookupSnapshot()` 构建热路径 snapshot -- `ResourceManager::LoadResource()` 通过 `AssetImportService::EnsureArtifact()` 准备 artifact，再交给具体 loader -- `tests/core/Asset/test_resource_manager.cpp` 覆盖了新建项目资产后 `TryGetAssetRef()` cache miss 刷新 snapshot、随后 `TryResolveAssetPath()` 成功的真实链路 -- `tests/Resources/Texture/test_texture_loader.cpp`、`tests/Resources/Material/test_material_loader.cpp`、`tests/Resources/Mesh/test_mesh_loader.cpp` 覆盖了 artifact 生成、复用和依赖变化触发重导的主路径 +- [AssetImportService](../AssetImportService/AssetImportService.md) 当前持有 `AssetDatabase`，并负责所有外部访问的加锁与项目根切换。 +- `AssetImportService` 的显式工具入口当前会： + - 先 `Refresh()`，再调用 [ReimportAsset](ReimportAsset.md) + - 先 `Refresh()`，再调用 [ReimportAllAssets](ReimportAllAssets.md) + - 在持锁且项目根有效时转发 [TryGetImportableResourceType](TryGetImportableResourceType.md) +- [ProjectAssetIndex](../ProjectAssetIndex/ProjectAssetIndex.md) 通过 [BuildLookupSnapshot](BuildLookupSnapshot.md) 构建热路径 snapshot。 +- `ResourceManager::LoadResource()` 通过 `AssetImportService::EnsureArtifact()` 准备 artifact，再把结果交给具体 loader。 ## 当前实现边界 -- 当前只处理项目 `Assets` 下的资产，`builtin://` 等虚拟路径不会进入这里 -- `.meta` 只存导入器名称和版本，不存 importer 细节设置 -- `FolderImporter` / `DefaultImporter` 不会产出 artifact -- 当前没有文件监听器，也没有后台导入任务；artifact 通常在首次加载或显式调用时同步生成 -- `TryGetAssetRef()` 只保证“路径有 GUID”，不保证请求的 `ResourceType` 与实际 importer 一致；真正的类型匹配要到 `EnsureArtifact()` 阶段才检查 +- 当前只处理项目 `Assets` 下的资产，`builtin://` 等虚拟路径不会进入这里。 +- `.meta` 只保存 importer 名称和版本，不保存更细的 importer 设置。 +- `FolderImporter` / `DefaultImporter` 不会产出 artifact。 +- 当前没有文件监听器，也没有后台导入队列；artifact 通常在首次加载、显式重导或按需导入时同步生成。 +- [TryGetAssetRef](TryGetAssetRef.md) 只保证“路径有 GUID”，不保证请求的 `ResourceType` 与真实 importer 一致；真正的类型匹配要到 [EnsureArtifact](EnsureArtifact.md) 阶段才检查。 ## 相关文档 diff --git a/docs/api/XCEngine/Core/Asset/AssetDatabase/EnsureArtifact.md b/docs/api/XCEngine/Core/Asset/AssetDatabase/EnsureArtifact.md index 95662e6a..8003310c 100644 --- a/docs/api/XCEngine/Core/Asset/AssetDatabase/EnsureArtifact.md +++ b/docs/api/XCEngine/Core/Asset/AssetDatabase/EnsureArtifact.md @@ -17,39 +17,39 @@ bool EnsureArtifact( ## 作用 -确保指定 project asset 的主 artifact 已经存在且与当前 source / `.meta` / dependency snapshot 一致，并把可直接加载的 artifact 路径回传给调用方。 +确保指定 project asset 的主 artifact 已经存在并与当前 source / `.meta` / dependency snapshot 一致，再把可直接加载的 artifact 结果写入 [ResolvedAsset](ResolvedAsset.md)。 ## 当前实现流程 -1. 把 `outAsset` 重置为默认值 -2. 调用 [ResolvePath](ResolvePath.md) 解析请求路径；若无法得到 `Assets/...` 相对路径则失败 -3. 检查 source 文件是否存在 -4. 调用内部 `EnsureMetaForPath()`，确保 source 记录、GUID、`.meta` 和 `importerVersion` 有效 -5. 根据 importer 推导主资源类型，并检查是否与 `requestedType` 一致 -6. 查找已有 `ArtifactRecord` -7. 若 `ShouldReimport()` 判定需要重建，则同步调用对应 importer: - - 纹理 -> `ImportTextureAsset()` - - 材质 -> `ImportMaterialAsset()` - - 模型 -> `ImportModelAsset()` - - Shader -> `ImportShaderAsset()` -8. 成功重建后，更新 `m_artifactsByGuid`，并把 `lastKnownArtifactKey` 回写到两份 source 记录索引 -9. 调用 `SaveArtifactDB()` 和 `SaveSourceAssetDB()` 持久化结果 -10. 把 source 绝对路径、相对路径、GUID、artifact 绝对目录和主 artifact 绝对路径写入 `outAsset` +1. 先把 `outAsset` 置空。 +2. 调用 [ResolvePath](ResolvePath.md)；若拿不到非空 `Assets/...` 相对路径则失败。 +3. 检查 source 路径当前是否存在。 +4. 调用内部 `EnsureMetaForPath(...)`，确保 source 记录、GUID、`.meta` 和 `importerVersion` 有效。 +5. 根据 importer 推导主资源类型，并要求它与 `requestedType` 一致。 +6. 查找现有 `ArtifactRecord`。 +7. 若 `ShouldReimport(...)` 判定需要重建，则同步调用对应 importer 重建 artifact，并回写： + - `m_artifactsByGuid` + - `m_sourcesByGuid[].lastKnownArtifactKey` + - `m_sourcesByPathKey[].lastKnownArtifactKey` +8. 若这次真的发生了重建，当前实现还会额外调用一次 `CleanupOrphanedArtifacts()`。 +9. 最后通过 `PopulateResolvedAssetResult(...)` 把 source / artifact 路径、GUID、类型和 `mainLocalID` 写进 `outAsset`。 ## 返回值 - `true` - 表示 source 存在、类型匹配，且主 artifact 已可直接使用 + 表示 source 存在、类型匹配，而且主 artifact 已可直接使用。 - `false` - 表示路径不合法、source 不存在、类型不匹配、导入失败，或当前 importer 不支持产出 artifact + 表示路径无效、source 不存在、类型不匹配、导入失败，或当前 importer 不支持产出 artifact。 ## 关键语义 -- 当前成功路径里会把 `exists` 和 `artifactReady` 一起置为 `true` -- `artifactKey` 由 GUID、importer、版本、source/meta 哈希、文件大小、写时间和依赖快照共同决定 -- `ShouldReimport()` 不只比较 `artifactKey`；它还会检查主 artifact 文件是否仍然存在，以及依赖快照是否仍匹配 -- 材质、模型和 Shader 导入的依赖快照都已经进入真实行为范围，因此贴图、`.mtl`、shader manifest 或 shader 源文件变化时都会触发新的 artifact -- 返回给调用方的 `artifactDirectory` 与 `artifactMainPath` 都是绝对路径，适合直接交给 loader 或文件系统操作 +- 当前成功路径里会把 `exists` 和 `artifactReady` 一起置为 `true`。 +- `ResolvedAsset::imported` 只表示“这次调用是否真的触发了导入”： + - 命中 `ShouldReimport(...)` 并成功重建时为 `true` + - 直接复用现有 artifact 时为 `false` +- `artifactKey` 由 GUID、importer、版本、source/meta 哈希、文件大小、写时间和依赖快照共同决定。 +- `ShouldReimport()` 不只比较 `artifactKey`；它还会检查主 artifact 文件是否仍然存在，以及依赖快照是否仍然匹配。 +- 返回给调用方的 `artifactDirectory` 与 `artifactMainPath` 都是绝对路径，适合直接交给 loader 或文件系统操作。 ## 相关文档 @@ -58,3 +58,4 @@ bool EnsureArtifact( - [ArtifactRecord](ArtifactRecord.md) - [ArtifactDependencyRecord](ArtifactDependencyRecord.md) - [ResolvePath](ResolvePath.md) +- [ReimportAsset](ReimportAsset.md) diff --git a/docs/api/XCEngine/Core/Asset/AssetDatabase/MaintenanceStats.md b/docs/api/XCEngine/Core/Asset/AssetDatabase/MaintenanceStats.md new file mode 100644 index 00000000..e8f5504c --- /dev/null +++ b/docs/api/XCEngine/Core/Asset/AssetDatabase/MaintenanceStats.md @@ -0,0 +1,41 @@ +# AssetDatabase::MaintenanceStats + +**命名空间**: `XCEngine::Resources` + +**类型**: `struct` + +**头文件**: `XCEngine/Core/Asset/AssetDatabase.h` + +**描述**: 记录一次资产维护操作的汇总结果，用来描述“这次扫描或重导到底处理了多少资产、清掉了多少孤儿 artifact”。 + +## 字段 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `importedAssetCount` | `Core::uint32` | 本次操作里成功重建的 source asset 数量。 | +| `removedArtifactCount` | `Core::uint32` | 本次操作里从 `Library/Artifacts` 清掉的孤儿 artifact 目录或条目数量。 | + +## 当前实现语义 + +- 它不是长期缓存，而是一次维护操作的返回快照。 +- [Refresh](Refresh.md) 当前只做扫描、索引清理和孤儿 artifact 清理，不做显式重导，因此： + - `importedAssetCount` 当前通常为 `0` + - `removedArtifactCount` 反映这次扫描顺手清掉了多少失配 artifact +- [ReimportAsset](ReimportAsset.md) 成功时当前会写出： + - `importedAssetCount = 1` + - `removedArtifactCount = CleanupOrphanedArtifacts()` 的结果 +- [ReimportAllAssets](ReimportAllAssets.md) 会把每个成功重导的条目累加到 `importedAssetCount`，最后再统一统计一次 `removedArtifactCount`。 + +## 设计提示 + +把统计结构放在 `AssetDatabase` 层，而不是只放在上层服务里，有两个直接好处： + +- 底层扫描和导入逻辑可以把真实维护结果原样暴露出来，上层不需要自己猜测“到底做了多少事”。 +- `AssetImportService`、`ResourceManager` 或编辑器工具都可以在不重复统计的前提下，构造自己的导入状态 UI 或日志。 + +## 相关文档 + +- [AssetDatabase](AssetDatabase.md) +- [Refresh](Refresh.md) +- [ReimportAsset](ReimportAsset.md) +- [ReimportAllAssets](ReimportAllAssets.md) diff --git a/docs/api/XCEngine/Core/Asset/AssetDatabase/Refresh.md b/docs/api/XCEngine/Core/Asset/AssetDatabase/Refresh.md index d3f9b651..b8f7209f 100644 --- a/docs/api/XCEngine/Core/Asset/AssetDatabase/Refresh.md +++ b/docs/api/XCEngine/Core/Asset/AssetDatabase/Refresh.md @@ -9,26 +9,46 @@ ## 签名 ```cpp -void Refresh(); +MaintenanceStats Refresh(); ``` ## 作用 -重新扫描项目 `Assets` 目录，更新 source 资产索引与 `.meta`。 +重新扫描当前项目的 `Assets` 树，更新 source 快照、清理失效记录，并返回这次维护操作的汇总统计。 ## 当前实现行为 -- 当前实现只是调用 `ScanAssets()`。 -- 会补齐缺失 `.meta`、更新 source 文件快照、移除已经不存在的 source 记录。 -- 若发现 source 记录被删除，会同步从 artifact 索引中移除对应记录。 +- 公开入口当前只是直接转发到内部 `ScanAssets()`。 +- `ScanAssets()` 会做四件事： + 1. 递归扫描 `Assets` + 2. 调用 `EnsureMetaForPath(...)` 维护 `.meta`、GUID、importer 和 source 快照 + 3. 调用 `RemoveMissingRecords(...)` 移除已经不存在的 source 记录及其 artifact 索引 + 4. 调用 `CleanupOrphanedArtifacts()` 删除 `Library/Artifacts` 下不再被当前索引引用的孤儿目录 +- 扫描结束后会写回： + - `Library/SourceAssetDB/assets.db` + - `Library/ArtifactDB/artifacts.db` -## 当前限制 +## 返回值 -- 不会主动为所有资产重建 artifact。 -- 也不会自动通知编辑器 UI 或运行时缓存刷新；这些动作仍需外层系统自己串起来。 +- 返回 [MaintenanceStats](MaintenanceStats.md)。 +- 按当前实现： + - `importedAssetCount` 通常为 `0`，因为 `Refresh()` 本身不做显式重导 + - `removedArtifactCount` 表示这次扫描额外清掉了多少孤儿 artifact 条目 + +## 关键语义 + +- 它会刷新 source 快照，但不会像 [ReimportAllAssets](ReimportAllAssets.md) 那样强制重建所有 artifact。 +- 它也不会像 [EnsureArtifact](EnsureArtifact.md) 那样按需保证某个具体 artifact 就绪。 +- 对已经从项目中删除的 source asset，当前实现会同时删掉内存中的 source/artifact 索引记录；随后 `CleanupOrphanedArtifacts()` 再把磁盘上的孤儿 artifact 目录清掉。 + +## 当前实现边界 + +- 这是“扫描 + 清理”入口，不是批量导入入口。 +- 它不会主动刷新上层缓存；`ProjectAssetIndex`、`ResourceManager` 或编辑器 UI 仍要由外层显式跟进。 ## 相关文档 - [AssetDatabase](AssetDatabase.md) -- [Initialize](Initialize.md) -- [BuildLookupSnapshot](BuildLookupSnapshot.md) +- [MaintenanceStats](MaintenanceStats.md) +- [ReimportAsset](ReimportAsset.md) +- [ReimportAllAssets](ReimportAllAssets.md) diff --git a/docs/api/XCEngine/Core/Asset/AssetDatabase/ReimportAllAssets.md b/docs/api/XCEngine/Core/Asset/AssetDatabase/ReimportAllAssets.md new file mode 100644 index 00000000..ce118ee1 --- /dev/null +++ b/docs/api/XCEngine/Core/Asset/AssetDatabase/ReimportAllAssets.md @@ -0,0 +1,75 @@ +# AssetDatabase::ReimportAllAssets + +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/AssetDatabase.h` + +## 签名 + +```cpp +bool ReimportAllAssets(MaintenanceStats* outStats = nullptr); +``` + +## 作用 + +对当前 source snapshot 里的全部可导入 project asset 执行一次显式全量重导。 + +## 当前实现流程 + +1. 如果传入了 `outStats`，先清零。 +2. 遍历 `m_sourcesByGuid`，过滤掉以下记录： + - `isFolder == true` + - importer 的主资源类型为 `ResourceType::Unknown` + - source 路径当前不存在 + - source 路径当前变成目录 +3. 把剩余 `SourceAssetRecord` 收集到 `importableRecords`。 +4. 按 `relativePath` 字典序排序，保证导入顺序稳定。 +5. 逐项调用内部 `ImportAsset(record, rebuiltRecord)` 强制重建 artifact。 +6. 对每个成功条目更新： + - `m_artifactsByGuid[record.guid]` + - `m_sourcesByGuid[record.guid].lastKnownArtifactKey` + - `m_sourcesByPathKey[pathKey].lastKnownArtifactKey` + - `localStats.importedAssetCount` +7. 全量循环结束后统一写回 `ArtifactDB` 和 `SourceAssetDB`。 +8. 最后调用一次 `CleanupOrphanedArtifacts()`，把结果写进 `localStats.removedArtifactCount`。 +9. 返回总体成功位 `allSucceeded`。 + +## 返回值 + +- `true` + 表示本次批量重导中所有可导入条目都成功了。 +- `false` + 表示至少有一个条目重导失败；失败不会中断整轮循环。 + +## 关键语义 + +- 这是“对当前快照做全量显式重导”，不是实时扫描磁盘的目录遍历器。 +- 单个条目导入失败不会中断全量循环；实现只会把 `allSucceeded` 置为 `false`，然后继续处理后续条目。 +- `outStats->importedAssetCount` 只统计成功重建的条目数。 +- `outStats->removedArtifactCount` 统计的是批量重导结束后清理掉的孤儿 artifact 条目数。 +- 文件夹记录与 `DefaultImporter` 这类主资源类型为 `Unknown` 的记录会被跳过，不算失败。 + +## 当前实现边界 + +- 本方法本身不会先做 [Refresh](Refresh.md)；当前典型调用方 [AssetImportService](../AssetImportService/AssetImportService.md) 会先刷新 source snapshot。 +- 它只会重导当前 `m_sourcesByGuid` 里已经存在的 source 记录；如果新文件尚未进入快照，本方法自身不会主动发现它。 + +## 当前调用链 + +- [AssetImportService](../AssetImportService/AssetImportService.md) + 当前会先 `m_assetDatabase.Refresh()`，再调用这里。 +- `tests/Core/Asset/test_resource_manager.cpp` + 里的 `AssetImportService_Test.ClearLibraryAndReimportAllAssetsManageArtifactsExplicitly` + 通过 service 包装层验证了： + - `ClearLibraryCache()` 后 `Artifacts` 目录可以被清空 + - 再次 `ReimportAllAssets()` 后 artifact 会被重新批量生成 + +## 相关文档 + +- [AssetDatabase](AssetDatabase.md) +- [MaintenanceStats](MaintenanceStats.md) +- [Refresh](Refresh.md) +- [ReimportAsset](ReimportAsset.md) +- [EnsureArtifact](EnsureArtifact.md) diff --git a/docs/api/XCEngine/Core/Asset/AssetDatabase/ReimportAsset.md b/docs/api/XCEngine/Core/Asset/AssetDatabase/ReimportAsset.md new file mode 100644 index 00000000..3606b002 --- /dev/null +++ b/docs/api/XCEngine/Core/Asset/AssetDatabase/ReimportAsset.md @@ -0,0 +1,78 @@ +# AssetDatabase::ReimportAsset + +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/AssetDatabase.h` + +## 签名 + +```cpp +bool ReimportAsset( + const Containers::String& requestPath, + ResolvedAsset& outAsset, + MaintenanceStats* outStats = nullptr); +``` + +## 作用 + +强制重导单个 project asset，不经过 `ShouldReimport()` 的按需判断，并把最新主 artifact 的解析结果写入 [ResolvedAsset](ResolvedAsset.md)。 + +## 当前实现流程 + +1. 先把 `outAsset` 置空；如果传入了 `outStats`，也先清零。 +2. 调用 [ResolvePath](ResolvePath.md)，要求能得到非空的 `Assets/...` 相对路径。 +3. 要求源路径当前存在，且必须是文件而不是目录。 +4. 调用内部 `EnsureMetaForPath(...)`，确保 `.meta`、GUID、importer 和 `SourceAssetRecord` 有效。 +5. 用 `GetPrimaryResourceTypeForImporter(sourceRecord.importerName)` 求主资源类型。 +6. 如果主资源类型是 `ResourceType::Unknown`，直接失败。 +7. 直接调用内部 `ImportAsset(sourceRecord, rebuiltRecord)` 强制重建 artifact。 +8. 成功后更新： + - `m_artifactsByGuid[sourceRecord.guid]` + - `m_sourcesByGuid[sourceRecord.guid].lastKnownArtifactKey` + - `m_sourcesByPathKey[pathKey].lastKnownArtifactKey` +9. 写回 `ArtifactDB` 和 `SourceAssetDB`。 +10. 统计并写出： + - `importedAssetCount = 1` + - `removedArtifactCount = CleanupOrphanedArtifacts()` 的结果 +11. 调用内部 `PopulateResolvedAssetResult(..., true, outAsset)`，因此返回结果里的 `imported` 当前一定为 `true`。 + +## 返回值 + +- `true` + 表示该 source asset 已被成功强制重导，`outAsset` 现在指向最新主 artifact。 +- `false` + 表示路径无效、源文件不存在、主资源类型未知，或实际导入失败；失败时 `outAsset` 与 `outStats` 都保持零值。 + +## 关键语义 + +- 这是显式重导入口，不走 [EnsureArtifact](EnsureArtifact.md) 的 `ShouldReimport()` 分支。 +- 只要前置条件成立，它就会尝试真正重建，而不是“如果旧 artifact 还能用就复用”。 +- 返回的 [ResolvedAsset](ResolvedAsset.md) 代表最新主 artifact，其中： + - `absolutePath` / `relativePath` 仍指向 source asset + - `artifactDirectory` / `artifactMainPath` 指向最新生成的 artifact 绝对路径 + - `imported` 为 `true` +- 对模型这类会附带写出材质/贴图 artifact 的资源，本方法会一起生成附属产物，但返回值仍只暴露主 artifact。 + +## 当前实现边界 + +- 只接受项目 `Assets/...` 内、存在且非目录的 source asset。 +- 不会自行先做 [Refresh](Refresh.md)；当前典型调用方 [AssetImportService](../AssetImportService/AssetImportService.md) 会先刷新 source snapshot，再转发到这里。 +- 不适用于 `FolderImporter` / `DefaultImporter` 这类主资源类型为 `Unknown` 的 source 记录。 + +## 当前调用链 + +- [AssetImportService](../AssetImportService/AssetImportService.md) + 的 `ReimportAsset(...)` 当前会先 `Refresh()`，再调用这里。 +- `tests/Core/Asset/test_resource_manager.cpp` + 里的 `ResourceManager_Test.ReimportProjectAssetBuildsArtifactForSelectedPath` + 通过 `ResourceManager -> AssetImportService -> AssetDatabase` 这条链验证了单路径重导会生成 artifact。 + +## 相关文档 + +- [AssetDatabase](AssetDatabase.md) +- [MaintenanceStats](MaintenanceStats.md) +- [ResolvedAsset](ResolvedAsset.md) +- [EnsureArtifact](EnsureArtifact.md) +- [ReimportAllAssets](ReimportAllAssets.md) diff --git a/docs/api/XCEngine/Core/Asset/AssetDatabase/ResolvedAsset.md b/docs/api/XCEngine/Core/Asset/AssetDatabase/ResolvedAsset.md index 6a8cb2ef..81485c7f 100644 --- a/docs/api/XCEngine/Core/Asset/AssetDatabase/ResolvedAsset.md +++ b/docs/api/XCEngine/Core/Asset/AssetDatabase/ResolvedAsset.md @@ -6,29 +6,41 @@ **头文件**: `XCEngine/Core/Asset/AssetDatabase.h` -**描述**: `EnsureArtifact()` 返回给调用方的解析结果，汇总 source 路径、GUID 和可直接加载的 artifact 主文件信息。 +**描述**: [EnsureArtifact](EnsureArtifact.md) 与 [ReimportAsset](ReimportAsset.md) 返回给调用方的解析结果，汇总 source 路径、GUID、主 artifact 位置，以及这次调用是否真的触发了导入。 ## 字段 | 字段 | 类型 | 说明 | |------|------|------| -| `exists` | `bool` | 当前 source asset 与 artifact 均成功解析时为 `true`。 | -| `artifactReady` | `bool` | 当前 artifact 已可用时为 `true`。 | +| `exists` | `bool` | 当前 source asset 与主 artifact 都已成功解析时为 `true`。 | +| `artifactReady` | `bool` | 当前主 artifact 已可直接使用时为 `true`。 | +| `imported` | `bool` | 这次调用是否真的触发了导入或重导。 | | `absolutePath` | `Containers::String` | source asset 的绝对路径。 | | `relativePath` | `Containers::String` | source asset 的项目相对路径，通常是 `Assets/...`。 | | `assetGuid` | `AssetGUID` | source asset GUID。 | -| `resourceType` | `ResourceType` | artifact 的主资源类型。 | +| `resourceType` | `ResourceType` | 主 artifact 的资源类型。 | | `artifactMainPath` | `Containers::String` | 主 artifact 文件的绝对路径。 | | `artifactDirectory` | `Containers::String` | artifact 目录的绝对路径。 | -| `mainLocalID` | `LocalID` | 主资产 local ID。 | +| `mainLocalID` | `LocalID` | 主资源 local ID。 | ## 当前实现语义 - 当前实现里，`exists` 和 `artifactReady` 只会在完全成功时一起置为 `true`。 -- 失败时整个结构会保持默认值，因此它还不能表达“source 已存在但 artifact 尚未生成”的中间态。 -- `artifactMainPath` 与 `artifactDirectory` 都已经被展开为绝对路径，适合直接交给 loader 或文件系统调用。 +- 失败时整个结构体会保持零值，因此它目前不表达“source 已存在但 artifact 尚未就绪”的中间态。 +- `artifactMainPath` 与 `artifactDirectory` 都已经被展开成绝对路径，适合直接交给 loader 或文件系统调用。 +- 对模型这类会产出附属材质 / 贴图 artifact 的 source asset，这个结构体仍只暴露主 artifact 信息。 + +## `imported` 的真实含义 + +- [EnsureArtifact](EnsureArtifact.md) + 当前只有在 `ShouldReimport(...)` 命中并且实际完成重建时，才会把 `imported` 设为 `true`。 +- 如果 `EnsureArtifact()` 直接复用了现有 artifact，`imported` 会保持 `false`。 +- [ReimportAsset](ReimportAsset.md) + 当前总是走显式重导路径，因此成功返回时 `imported` 为 `true`。 ## 相关文档 - [AssetDatabase](AssetDatabase.md) - [EnsureArtifact](EnsureArtifact.md) +- [ReimportAsset](ReimportAsset.md) +- [MaintenanceStats](MaintenanceStats.md) diff --git a/docs/api/XCEngine/Core/Asset/AssetDatabase/TryGetImportableResourceType.md b/docs/api/XCEngine/Core/Asset/AssetDatabase/TryGetImportableResourceType.md new file mode 100644 index 00000000..b046d2b1 --- /dev/null +++ b/docs/api/XCEngine/Core/Asset/AssetDatabase/TryGetImportableResourceType.md @@ -0,0 +1,52 @@ +# AssetDatabase::TryGetImportableResourceType + +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/AssetDatabase.h` + +## 签名 + +```cpp +bool TryGetImportableResourceType( + const Containers::String& requestPath, + ResourceType& outType) const; +``` + +## 作用 + +判断指定 project asset 路径当前是否可导入，并返回该 importer 的主资源类型。 + +## 当前实现行为 + +1. 先把 `outType` 重置为 `ResourceType::Unknown` +2. 调用 [ResolvePath](ResolvePath.md) 解析 `requestPath` +3. 若无法得到非空 `Assets/...` 相对路径，则直接失败 +4. 检查解析后的绝对路径是否存在，且必须是文件而不是目录 +5. 调用内部： + - `GetImporterNameForPath(relativePath, false)` + - `GetPrimaryResourceTypeForImporter(importerName)` +6. 只有当主资源类型不是 `ResourceType::Unknown` 时才返回 `true` + +## 关键语义 + +- 它只返回当前 importer 的 primary `ResourceType`，不会描述模型内嵌材质、内嵌贴图之类次级 artifact。 +- 目录路径会直接失败，即使该目录最终会走 `FolderImporter`。 +- `builtin://` 之类虚拟路径、项目外绝对路径、以及不能还原成 `Assets/...` 的普通相对路径，当前都不会被认作可导入项目资产。 +- 失败时 `outType` 会保持 `ResourceType::Unknown`。 + +## 当前调用链 + +- [AssetImportService](../AssetImportService/AssetImportService.md) + 当前会在持锁且项目根有效时，直接转发到这个方法。 +- `tests/Core/Asset/test_resource_manager.cpp` + 里的 `AssetImportService_Test.ClearLibraryAndReimportAllAssetsManageArtifactsExplicitly` + 当前通过 service 包装层验证了 `Assets/runtime.material` 会返回 `ResourceType::Material`。 + +## 相关文档 + +- [AssetDatabase](AssetDatabase.md) +- [ResolvePath](ResolvePath.md) +- [ReimportAsset](ReimportAsset.md) +- [ReimportAllAssets](ReimportAllAssets.md) diff --git a/docs/api/XCEngine/Core/Asset/AssetImportService/AssetImportService.md b/docs/api/XCEngine/Core/Asset/AssetImportService/AssetImportService.md index bec0342f..1ad03edc 100644 --- a/docs/api/XCEngine/Core/Asset/AssetImportService/AssetImportService.md +++ b/docs/api/XCEngine/Core/Asset/AssetImportService/AssetImportService.md @@ -6,135 +6,191 @@ **头文件**: `XCEngine/Core/Asset/AssetImportService.h` -**描述**: 以线程安全服务层的形式封装 `AssetDatabase`，向 `ResourceManager` 和 `ProjectAssetIndex` 暴露项目资产导入、`AssetRef` 查询、`Library` 根目录查询以及 lookup snapshot 导出能力。 +**描述**: 以线程安全服务层包装 [AssetDatabase](../AssetDatabase/AssetDatabase.md)，向运行时与编辑器暴露项目资产导入、Library 维护工具、lookup snapshot 导出与导入状态快照。 ## 概览 -`AssetImportService` 是当前 `Core/Asset` 分层里的“受控数据库入口”： +`AssetImportService` 是当前 `Core/Asset` 分层里推荐的对外入口。它并不自己实现 importer 或持久化格式，而是把这些职责组织起来： -- [AssetDatabase](../AssetDatabase/AssetDatabase.md) 负责真实的扫描、`.meta`、artifact 与导入逻辑 -- `AssetImportService` 用一把 `std::recursive_mutex` 串行化这些数据库入口，并把结果整理成更适合运行时消费的服务 API -- [ProjectAssetIndex](../ProjectAssetIndex/ProjectAssetIndex.md) 再基于它导出的 [LookupSnapshot](LookupSnapshot.md) 构建热路径查询缓存 +1. 持有当前活动项目根，并负责在项目切换时重建底层 [AssetDatabase](../AssetDatabase/AssetDatabase.md)。 +2. 用一把 `std::recursive_mutex` 串行化所有数据库访问，保证 `ResourceManager`、`ProjectAssetIndex` 和编辑器工具都通过同一个受控入口访问项目资产层。 +3. 向上层提供显式工具命令： + - [Refresh](Refresh.md) + - [ClearLibraryCache](ClearLibraryCache.md) + - [RebuildLibraryCache](RebuildLibraryCache.md) + - [ReimportAllAssets](ReimportAllAssets.md) + - [ReimportAsset](ReimportAsset.md) +4. 把底层 [ResolvedAsset](../AssetDatabase/ResolvedAsset.md) 转换成更适合运行时消费的 [ImportedAsset](ImportedAsset.md)。 +5. 维护最近一次导入/清理操作的 [ImportStatusSnapshot](ImportStatusSnapshot.md)，供测试、编辑器提示和后续工具链读取。 -## 公开类型 +## 设计理念 -### `LookupSnapshot` +这套分层和 Unity 一类商业级游戏引擎的思路接近： -[LookupSnapshot](LookupSnapshot.md) 是一个值对象，里面保存两张表： +- `Assets` 里保存作者源文件和 `.meta` 身份。 +- `Library` 里保存可再生的导入缓存与 artifact。 +- 运行时与编辑器工具不直接依赖 `Library` 的具体磁盘布局，而是走一层稳定的服务 API。 -- `path key -> AssetGUID` -- `AssetGUID -> relative path` +这样拆开的好处是： -它的用途不是长期持有数据库状态，而是给 `ProjectAssetIndex::RefreshFrom()` 做一次性整体拉取。 - -### `ImportedAsset` - -[ImportedAsset](ImportedAsset.md) 是 [EnsureArtifact](EnsureArtifact.md) 的输出对象。它把 `AssetDatabase::ResolvedAsset` 转成更适合运行时装配的结果： - -- 保留 source 绝对路径、`Assets/...` 相对路径和 `AssetGUID` -- 保留 `artifactDirectory` 与 `mainLocalID` -- 暴露 `runtimeLoadPath`，供 `ResourceManager::LoadResource()` 决定真正交给 loader 的路径 - -按 `ConvertResolvedAsset()` 的字段转换规则，`runtimeLoadPath` 会在 `artifactReady=true` 时取主 artifact 绝对路径，否则退回 source 绝对路径；但按当前 `AssetDatabase::EnsureArtifact()` 的实现，`AssetImportService::EnsureArtifact()` 只有在主 artifact 已经可用时才会成功返回，因此当前成功路径里的 `runtimeLoadPath` 实际上总是指向 `Library/Artifacts/.../main.*`。 +- `.meta` 里的 `AssetGUID` 负责“稳定身份”，`Library` 负责“可再生缓存”，两者职责清楚。 +- 项目根切换、数据库关闭重建、状态记录、日志输出都集中在一个 choke point，避免这些横切逻辑分散到 `ResourceManager` 或编辑器面板里。 +- 将来如果要做后台导入队列、导入进度 UI、批处理命令或更细的审计日志，可以先沿用这层服务接口，而不必让上层直接碰 `AssetDatabase` 的内部细节。 ## 生命周期 ### `Initialize()` -当前实现是空函数。它更像一个生命周期锚点，给未来后台导入队列或统计能力预留挂接位置。 - -### `Shutdown()` - -`Shutdown()` 会在锁内执行： - -- `m_assetDatabase.Shutdown()` -- 清空 `m_projectRoot` - -这会彻底断开当前项目的资产数据库状态，而不只是清理临时缓存。 +当前实现是空钩子。它主要是一个生命周期锚点，给未来的后台任务系统或状态订阅留位置。 ### `SetProjectRoot()` / `GetProjectRoot()` / `GetLibraryRoot()` -- `SetProjectRoot()` 是最关键的状态切换入口 -- 如果新旧项目根相同，直接返回 -- 如果旧项目根非空，先关闭旧的 `AssetDatabase` -- 写入新的 `m_projectRoot` 后，若新项目根非空则重新初始化 `AssetDatabase` -- [GetLibraryRoot](GetLibraryRoot.md) 返回当前项目 `Library` 根目录的绝对路径，供测试和更高层缓存重建入口使用 +- `SetProjectRoot()` 是最关键的状态切换入口。 +- 如果新旧项目根相同，直接返回。 +- 如果旧项目根非空，会先关闭旧的 `AssetDatabase`。 +- 写入新的项目根后，会重置导入状态；若新项目根非空，则立即重新初始化底层数据库。 +- `GetLibraryRoot()` 返回当前项目 `Library` 根目录的绝对路径。 -因此它当前是单项目绑定服务，不支持同时托管多个项目根。 +这意味着当前 `AssetImportService` 是“单活动项目根”模型，不支持在一个实例里同时托管多个项目。 -## 当前公开能力 +### `Shutdown()` + +`Shutdown()` 会： + +- 关闭底层 `AssetDatabase` +- 清空 `m_projectRoot` +- 重置最近一次导入状态 + +因此它不仅仅是“清理临时缓存”，而是彻底断开当前项目资产数据库上下文。 + +## 导入工具与状态模型 ### `Refresh()` -在项目根有效时转发到 `AssetDatabase::Refresh()`，用于重新扫描 source 资产并刷新数据库状态。 +[Refresh](Refresh.md) 负责 source 快照维护与孤儿 artifact 清理。它不是显式重导入命令。 + +当前实现里： + +- 它会转发到底层 `AssetDatabase::Refresh()`。 +- 它只在 `removedArtifactCount > 0` 时写入新的 [ImportStatusSnapshot](ImportStatusSnapshot.md)。 +- 如果只是普通扫描、source DB 更新或无事发生，最近一次状态会保持不变。 + +### `ClearLibraryCache()` + +[ClearLibraryCache](ClearLibraryCache.md) 会显式删除整个 `Library` 目录，然后立刻重新初始化数据库根结构。它本身不会自动批量重导入全部资产。 + +这和商业编辑器里“清缓存但不立刻全量重建”的工具命令一致，适合把“清空缓存”和“重新导入”拆成两步。 ### `RebuildLibraryCache()` -[RebuildLibraryCache](RebuildLibraryCache.md) 是更重的入口： +[RebuildLibraryCache](RebuildLibraryCache.md) 的真实实现就是： -1. 记录当前 `projectRoot` 和 `libraryRoot` -2. `m_assetDatabase.Shutdown()` -3. 删除整个 `Library` 目录 -4. 用原项目根重新 `Initialize()` +```text +ClearLibraryCache() +-> ReimportAllAssets() +``` -测试 `AssetImportService_Test.RebuildLibraryCacheKeepsStableAssetRefs` 说明它会清空缓存产物，但不会破坏现有 `.meta` 驱动的 `AssetGUID` 稳定性。 +它没有自己的独立状态模型；成功时最终留下的最近一次状态，来自第二步 [ReimportAllAssets](ReimportAllAssets.md)。 + +### `ReimportAllAssets()` / `ReimportAsset()` + +这两个是显式重导入命令： + +- 调用前都会先执行一次底层 `Refresh()`，先让 source 快照收敛到当前磁盘状态。 +- 然后再进入强制重导流程。 +- 返回或记录到状态里的 `importedAssetCount` / `removedArtifactCount` 来自显式重导步骤本身，不包含前置 `Refresh()` 那次扫描的统计。 + +这类接口适合编辑器菜单命令、诊断工具、CI 验证或用户手动执行的“重建导入结果”动作。 + +### `GetLastImportStatus()` + +[GetLastImportStatus](GetLastImportStatus.md) 返回最近一次写入的 [ImportStatusSnapshot](ImportStatusSnapshot.md)。 + +需要注意两个当前实现细节： + +- 切换项目根或调用 `Shutdown()` 后，状态会被重置回“无值”。 +- 虽然内部会先写一份 `inProgress=true` 的开始状态，但由于所有公开操作都在同一把互斥锁里同步执行，外部调用者通常只能在操作完成后读到最终状态。 ### `EnsureArtifact()` -[EnsureArtifact](EnsureArtifact.md) 会在项目根有效时转发到底层数据库，并把结果转换成 [ImportedAsset](ImportedAsset.md)。 +[EnsureArtifact](EnsureArtifact.md) 是运行时最常走的入口。它会确保请求资产的主 artifact 可直接加载，并把结果转成 [ImportedAsset](ImportedAsset.md)。 -当前成功路径里： +它和显式重导入的关键差异是： -- `artifactReady` 为 `true` -- `runtimeLoadPath` 指向主 artifact 的绝对路径 -- `absolutePath` / `relativePath` / `assetGuid` 仍保留 source 资产身份 +- 如果命中了现有 artifact 缓存，返回 `true`，但不会写入新的成功状态。 +- 只有这次调用真的触发了导入，才会写出 `operation = "Import Asset"` 的成功状态。 +- 如果导入失败，会写出失败状态。 -`ResourceManager::LoadResource()` 用它决定真正交给 loader 的加载路径。 +这使得“按需导入”可以服务运行时热路径，同时又不会把每次缓存命中都当作一次新的工具操作。 -### `TryGetAssetRef()` / `TryGetPrimaryAssetPath()` +## 公开类型 -- `TryGetAssetRef()` 按请求路径解析主资产 `AssetRef` -- `TryGetPrimaryAssetPath()` 通过 `AssetGUID` 反查主相对路径 +- [ImportStatusSnapshot](ImportStatusSnapshot.md) + 最近一次导入/清理操作的状态快照。 +- [LookupSnapshot](LookupSnapshot.md) + 导出的 path/GUID 双向查询表，供 [ProjectAssetIndex](../ProjectAssetIndex/ProjectAssetIndex.md) 一次性刷新本地缓存。 +- [ImportedAsset](ImportedAsset.md) + [EnsureArtifact](EnsureArtifact.md) 与 [ReimportAsset](ReimportAsset.md) 返回给上层的轻量结果对象。 -它们都只负责数据库查询本身；高频缓存和 cache miss 刷新策略由 `ProjectAssetIndex` 负责。 +## 典型调用链 -### `BuildLookupSnapshot()` +### 编辑器显式清理并重建 Library -[BuildLookupSnapshot](BuildLookupSnapshot.md) 会先清空传入的 [LookupSnapshot](LookupSnapshot.md)，再导出当前双向查询表。这是 `ProjectAssetIndex` 刷新本地 snapshot 的唯一上游入口。 +```text +ClearLibraryCache() +-> ReimportAllAssets() +``` -## 与 `ResourceManager` 的关系 +如果你要做“重新生成整个项目导入缓存”的工具按钮，应优先使用 [RebuildLibraryCache](RebuildLibraryCache.md)，而不是手工拼底层数据库调用。 -`ResourceManager` 不再直接把 `AssetDatabase` 当成自己的内部实现细节，而是通过 `AssetImportService` 访问项目资产层： +### 运行时按需加载项目资产 -- `SetResourceRoot()` 用它切换项目根 -- `LoadResource()` 用它确保 artifact 就绪 -- [RefreshProjectAssets](../ResourceManager/RefreshProjectAssets.md) 用它刷新数据库，再同步重建 `ProjectAssetIndex` -- [RebuildProjectAssetCache](../ResourceManager/RebuildProjectAssetCache.md) 用它重建整个 `Library` 缓存 +```text +ResourceManager::LoadResource() +-> AssetImportService::EnsureArtifact() +-> loader 读取 ImportedAsset.runtimeLoadPath +``` -这让“数据库导入能力”和“运行时资源加载器”之间多了一层清晰职责边界。 +这里体现的是“源资产管理”和“运行时加载器”分层：加载器不需要知道 `.meta`、`assets.db` 或 artifact key 的细节。 + +### 构建查询快照 + +```text +ProjectAssetIndex::RefreshFrom() +-> AssetImportService::BuildLookupSnapshot() +``` + +`ProjectAssetIndex` 通过整份快照替换本地查表，而不是长期持有 `AssetDatabase`。 + +## 公开方法 + +| 方法 | 说明 | +|------|------| +| [Initialize](Initialize.md) | 生命周期钩子，当前为空实现。 | +| [Shutdown](Shutdown.md) | 关闭当前项目数据库并重置状态。 | +| [SetProjectRoot](SetProjectRoot.md) | 切换活动项目根。 | +| [GetProjectRoot](GetProjectRoot.md) | 获取当前项目根。 | +| [GetLibraryRoot](GetLibraryRoot.md) | 获取当前项目 `Library` 根目录。 | +| [Refresh](Refresh.md) | 扫描 source 快照并清理孤儿 artifact。 | +| [ClearLibraryCache](ClearLibraryCache.md) | 删除整个 `Library` 目录并重建数据库根结构。 | +| [RebuildLibraryCache](RebuildLibraryCache.md) | 清空 `Library` 后批量重导全部项目资产。 | +| [ReimportAllAssets](ReimportAllAssets.md) | 强制重导当前快照里的全部可导入资产。 | +| [ReimportAsset](ReimportAsset.md) | 强制重导指定项目资产。 | +| [GetLastImportStatus](GetLastImportStatus.md) | 读取最近一次导入状态快照。 | +| [TryGetImportableResourceType](TryGetImportableResourceType.md) | 探测请求路径当前 importer 的主资源类型。 | +| [EnsureArtifact](EnsureArtifact.md) | 按需确保主 artifact 可直接加载。 | +| [TryGetAssetRef](TryGetAssetRef.md) | 按路径查询主资产 `AssetRef`。 | +| [TryGetPrimaryAssetPath](TryGetPrimaryAssetPath.md) | 通过 `AssetGUID` 反查主相对路径。 | +| [BuildLookupSnapshot](BuildLookupSnapshot.md) | 导出 path/GUID lookup snapshot。 | ## 当前实现边界 -- `Initialize()` 仍是空实现，没有后台导入线程或事件订阅 -- 没有项目根时，所有数据库相关入口都会直接失败或返回空结果 -- 线程模型当前很直接: 一把 `recursive_mutex` 串行化所有服务入口 -- `LookupSnapshot` 是整份重建，不是增量同步 - -## 相关方法 - -- [Initialize](Initialize.md) -- [Shutdown](Shutdown.md) -- [SetProjectRoot](SetProjectRoot.md) -- [GetProjectRoot](GetProjectRoot.md) -- [GetLibraryRoot](GetLibraryRoot.md) -- [Refresh](Refresh.md) -- [RebuildLibraryCache](RebuildLibraryCache.md) -- [EnsureArtifact](EnsureArtifact.md) -- [TryGetAssetRef](TryGetAssetRef.md) -- [TryGetPrimaryAssetPath](TryGetPrimaryAssetPath.md) -- [BuildLookupSnapshot](BuildLookupSnapshot.md) -- [LookupSnapshot](LookupSnapshot.md) -- [ImportedAsset](ImportedAsset.md) +- 当前只有一个活动项目根，没有多项目并行上下文。 +- 所有公开方法都走同一把 `recursive_mutex`，当前模型是同步串行，不是后台导入队列。 +- [ImportStatusSnapshot](ImportStatusSnapshot.md) 只保存“最近一次状态”，不是历史日志列表。 +- [TryGetImportableResourceType](TryGetImportableResourceType.md) 只能回答“当前 importer 的 primary `ResourceType` 是什么”，不能保证后续真正导入一定成功。 +- [ReimportAllAssets](ReimportAllAssets.md) 与 [ReimportAsset](ReimportAsset.md) 在显式重导前会先做一次底层 `Refresh()`；但最终状态里的统计值只记录显式重导步骤本身。 +- 当前公开成功路径里，[EnsureArtifact](EnsureArtifact.md) 与 [ReimportAsset](ReimportAsset.md) 返回的 [ImportedAsset](ImportedAsset.md) 都可直接交给加载器消费；其中 `runtimeLoadPath` 现实上通常指向 `Library/Artifacts/.../main.*`。 ## 相关文档 diff --git a/docs/api/XCEngine/Core/Asset/AssetImportService/ClearLibraryCache.md b/docs/api/XCEngine/Core/Asset/AssetImportService/ClearLibraryCache.md new file mode 100644 index 00000000..3a692b33 --- /dev/null +++ b/docs/api/XCEngine/Core/Asset/AssetImportService/ClearLibraryCache.md @@ -0,0 +1,70 @@ +# AssetImportService::ClearLibraryCache + +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/AssetImportService.h` + +## 签名 + +```cpp +bool ClearLibraryCache(); +``` + +## 作用 + +删除当前项目的整个 `Library` 目录，然后重新初始化底层资产数据库。 + +这是显式的缓存清理命令。它不会自动批量重导所有项目资产。 + +## 当前实现流程 + +1. 在 `std::recursive_mutex` 保护下执行。 +2. 如果当前没有活动项目根： + - 写入失败的 [ImportStatusSnapshot](ImportStatusSnapshot.md) + - 返回 `false` +3. 如果项目根有效： + - 写入开始状态：`operation = "Clear Library"` + - 记录当前 `projectRoot` 与 `libraryRoot` + - 调用 `m_assetDatabase.Shutdown()` + - 调用 `std::filesystem::remove_all(libraryRoot, ec)` + - 无论 `remove_all` 是否报告错误，都会再用原项目根重新 `Initialize()` + - 根据 `ec` 写入完成状态并返回成功位 + +## 返回值 + +- `true` + - 表示 `remove_all()` 没有报告错误。 +- `false` + - 表示当前没有活动项目根，或者删除 `Library` 目录时出现了错误。 + +需要注意，返回值并不表示“删除了多少文件”，也不表示“是否随后发生了全量重导”。这一步只负责清缓存并重建数据库根结构。 + +## 调用后的系统状态 + +成功后，当前实现会重新建好 `Library` 根结构和数据库文件，但 `Artifacts` 目录通常是空的，直到后续发生： + +- [ReimportAllAssets](ReimportAllAssets.md) +- [ReimportAsset](ReimportAsset.md) +- [EnsureArtifact](EnsureArtifact.md) + +这正是把“清缓存”和“导入内容”分开的设计目标。 + +## 设计意义 + +在商业级编辑器里，“清空 Library”通常是诊断工具，而不是日常热路径操作。 + +把它单独做成一个命令有几个好处： + +- 可以验证 importer 是否能从纯净缓存重新生成产物。 +- 可以单独排查损坏的 artifact 或过时的中间文件。 +- 可以和 [RebuildLibraryCache](RebuildLibraryCache.md) 组合，也可以只做清理不立刻重导。 + +## 相关文档 + +- [AssetImportService](AssetImportService.md) +- [RebuildLibraryCache](RebuildLibraryCache.md) +- [ReimportAllAssets](ReimportAllAssets.md) +- [GetLastImportStatus](GetLastImportStatus.md) +- [ImportStatusSnapshot](ImportStatusSnapshot.md) diff --git a/docs/api/XCEngine/Core/Asset/AssetImportService/EnsureArtifact.md b/docs/api/XCEngine/Core/Asset/AssetImportService/EnsureArtifact.md index dcd0b158..abe17af3 100644 --- a/docs/api/XCEngine/Core/Asset/AssetImportService/EnsureArtifact.md +++ b/docs/api/XCEngine/Core/Asset/AssetImportService/EnsureArtifact.md @@ -17,28 +17,85 @@ bool EnsureArtifact( ## 作用 -确保指定项目资产请求已经具备可供运行时加载的主 artifact，并把数据库层结果转换成服务层返回对象。 +确保指定项目资产的主 artifact 已经存在且可直接加载，并把结果转换成服务层可消费的 [ImportedAsset](ImportedAsset.md)。 -## 当前实现行为 +这是运行时最常用的项目资产入口。`ResourceManager::LoadResource()` 会基于它决定最终要交给 loader 的路径。 -- 在 `std::recursive_mutex` 保护下执行 -- 如果当前没有项目根，直接返回 `false` -- 否则先调用 `AssetDatabase::EnsureArtifact()`，再把得到的 `ResolvedAsset` 转成 [ImportedAsset](ImportedAsset.md) -- 字段转换时，`ConvertResolvedAsset()` 会把 `runtimeLoadPath` 设为: - - `artifactMainPath`，当 `artifactReady=true` - - `absolutePath`，当 `artifactReady=false` +## 当前实现流程 -但按当前实现，`AssetDatabase::EnsureArtifact()` 只有在主 artifact 已可直接使用时才会返回成功，因此这条服务 API 的当前成功路径里，`runtimeLoadPath` 实际总是主 artifact 的绝对路径。 +1. 在 `std::recursive_mutex` 保护下执行。 +2. 如果当前没有活动项目根，直接返回 `false`。 +3. 调用底层 [AssetDatabase::EnsureArtifact](../AssetDatabase/EnsureArtifact.md)。 +4. 如果底层失败： + - 写入失败的 [ImportStatusSnapshot](ImportStatusSnapshot.md) + - `operation = "Import Asset"` + - `targetPath = requestPath` + - 返回 `false` +5. 如果底层成功： + - 把 [ResolvedAsset](../AssetDatabase/ResolvedAsset.md) 转成 [ImportedAsset](ImportedAsset.md) + - 如果这次确实发生了导入，则写入成功状态 + - 返回 `true` -## 当前语义 +## `outAsset` 的有效性 -- 这一层不再把 `AssetDatabase::ResolvedAsset` 直接暴露给上游 -- `ResourceManager::LoadResource()` 用它决定后续应该让 loader 读取 source 文件还是读取 `Library/Artifacts/.../main.*` -- 以当前代码路径来看，只要本方法返回 `true`，调用方就可以把 `runtimeLoadPath` 当作可直接交给 loader 的最终路径 +当前实现不会在方法入口主动清空 `outAsset`。也就是说： + +- 返回 `true` 时，`outAsset` 有效。 +- 返回 `false` 时，调用方不能假设 `outAsset` 已被清零；如果调用前它里头有旧内容，失败后旧内容可能仍然存在。 + +这和底层 [AssetDatabase::EnsureArtifact](../AssetDatabase/EnsureArtifact.md) 的内部临时对象语义不同。服务层这里更像“成功才回填结果”。 + +## 导入状态语义 + +### 失败路径 + +只要底层导入失败，当前实现就会写出失败状态： + +- `operation = "Import Asset"` +- `success = false` +- `targetPath = requestPath` +- `message = "Failed to build asset artifact: ..."` + +### 成功路径 + +成功并不总是写状态。 + +- 如果 `resolvedAsset.imported == true` + - 说明这次真的生成了 artifact。 + - 服务会写出成功状态，并把 `importedAssetCount` 记为 `1`。 +- 如果 `resolvedAsset.imported == false` + - 说明只是复用了现有 artifact。 + - 方法仍然返回 `true`，但不会覆盖最近一次状态。 + +因此，[GetLastImportStatus](GetLastImportStatus.md) 更适合观察“显式导入事件”或“导入失败”，而不是把每次缓存命中都当作一次新事件。 + +## `ImportedAsset` 的关键含义 + +- `outAsset.imported` + - 表示这次调用是否真的触发了导入。 +- `outAsset.runtimeLoadPath` + - 当前成功路径里通常会指向 `Library/Artifacts/.../main.*`。 +- `outAsset.assetGuid` / `outAsset.mainLocalID` + - 让运行时和资产索引继续使用稳定的资产身份，而不是直接绑定 artifact key。 + +## 设计含义 + +这类“按需确保 artifact 可用”的接口，是商业引擎里很常见的运行时桥接模式： + +- 编辑器与工具命令用显式 `Reimport*`。 +- 运行时加载用 `EnsureArtifact()`。 + +这样做的好处是： + +- 运行时只在真正需要时才触发导入。 +- 已经可用的 artifact 可以直接复用。 +- 上层 API 仍然保持简单，只接收路径和期望类型。 ## 相关文档 - [AssetImportService](AssetImportService.md) - [ImportedAsset](ImportedAsset.md) +- [GetLastImportStatus](GetLastImportStatus.md) +- [ImportStatusSnapshot](ImportStatusSnapshot.md) - [AssetDatabase::EnsureArtifact](../AssetDatabase/EnsureArtifact.md) - [ResourceManager](../ResourceManager/ResourceManager.md) diff --git a/docs/api/XCEngine/Core/Asset/AssetImportService/GetLastImportStatus.md b/docs/api/XCEngine/Core/Asset/AssetImportService/GetLastImportStatus.md new file mode 100644 index 00000000..5f551aa8 --- /dev/null +++ b/docs/api/XCEngine/Core/Asset/AssetImportService/GetLastImportStatus.md @@ -0,0 +1,73 @@ +# AssetImportService::GetLastImportStatus + +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/AssetImportService.h` + +## 签名 + +```cpp +ImportStatusSnapshot GetLastImportStatus() const; +``` + +## 作用 + +返回最近一次写入的 [ImportStatusSnapshot](ImportStatusSnapshot.md)。 + +它是当前服务层面向测试、编辑器提示和工具脚本暴露的唯一状态查询入口。 + +## 当前实现行为 + +- 在 `std::recursive_mutex` 保护下返回 `m_lastImportStatus` 的一个值拷贝。 +- 不会触发磁盘扫描、导入或快照刷新。 +- 不会返回历史列表，只返回“最近一次状态”。 + +## 什么时候会是“无值” + +当以下任一情况发生后，最近状态会被重置为空： + +- 刚初始化但还没有写过状态 +- 调用了 [SetProjectRoot](SetProjectRoot.md) 并切换或重置了项目根 +- 调用了 [Shutdown](Shutdown.md) + +在这些场景下，返回值上的 `HasValue()` 会是 `false`。 + +## 当前可观测语义 + +虽然内部有“开始状态”和“完成状态”两个写入点，但当前实现的所有公开操作都是在同一把互斥锁里同步执行，而 `GetLastImportStatus()` 自己也要拿这把锁。 + +因此，对外部调用者来说，最常见、最可靠的读取时机是： + +```text +执行工具命令 +-> 命令返回 +-> 立即读取 GetLastImportStatus() +``` + +此时读到的通常是最终完成状态，而不是中间的 `inProgress=true` 状态。 + +## 哪些调用会更新它 + +当前源码里，以下路径会写入状态： + +- [ClearLibraryCache](ClearLibraryCache.md) +- [ReimportAllAssets](ReimportAllAssets.md) +- [ReimportAsset](ReimportAsset.md) +- [Refresh](Refresh.md) + 仅当清理了孤儿 artifact +- [EnsureArtifact](EnsureArtifact.md) + 失败时会写失败状态，成功时仅在“本次真的发生导入”时写成功状态 + +这意味着“普通查询”“no-op refresh”“artifact 缓存命中”都可能让最近状态保持原值。 + +## 相关文档 + +- [AssetImportService](AssetImportService.md) +- [ImportStatusSnapshot](ImportStatusSnapshot.md) +- [Refresh](Refresh.md) +- [ClearLibraryCache](ClearLibraryCache.md) +- [ReimportAllAssets](ReimportAllAssets.md) +- [ReimportAsset](ReimportAsset.md) +- [EnsureArtifact](EnsureArtifact.md) diff --git a/docs/api/XCEngine/Core/Asset/AssetImportService/ImportStatusSnapshot.md b/docs/api/XCEngine/Core/Asset/AssetImportService/ImportStatusSnapshot.md new file mode 100644 index 00000000..6b0c2813 --- /dev/null +++ b/docs/api/XCEngine/Core/Asset/AssetImportService/ImportStatusSnapshot.md @@ -0,0 +1,97 @@ +# AssetImportService::ImportStatusSnapshot + +**命名空间**: `XCEngine::Resources` + +**类型**: `struct` + +**头文件**: `XCEngine/Core/Asset/AssetImportService.h` + +## 概览 + +`ImportStatusSnapshot` 保存 `AssetImportService` 最近一次导入、清理或维护操作的状态快照。 + +它不是历史日志，也不是事件流，而是一个“最后状态槽位”。当前服务层所有状态可观测性都收口在这个结构上。 + +## 当前字段 + +- `revision` + - 状态写入序号。 + - `0` 表示当前还没有有效状态。 +- `inProgress` + - 该快照是否表示“操作进行中”。 +- `success` + - 当前快照表示的操作是否成功。 +- `operation` + - 操作名称。 + - 当前源码里会出现的值包括： + - `"Refresh"` + - `"Clear Library"` + - `"Reimport All Assets"` + - `"Reimport Asset"` + - `"Import Asset"` +- `targetPath` + - 当前操作绑定的目标路径或根路径。 +- `message` + - 面向日志与调试的简短说明。 +- `importedAssetCount` + - 这次操作里显式导入成功的资产数量。 +- `removedArtifactCount` + - 这次操作里移除的孤儿 artifact 数量。 + +## `HasValue()` + +```cpp +bool HasValue() const; +``` + +当前实现很直接： + +- `revision != 0` 时返回 `true` +- `revision == 0` 时返回 `false` + +切换项目根或调用 `Shutdown()` 时，服务会把状态重置为空，因此 `HasValue()` 会重新回到 `false`。 + +## 当前写入规则 + +### 显式工具命令 + +以下命令会先写开始状态，再写完成状态： + +- [ClearLibraryCache](ClearLibraryCache.md) +- [ReimportAllAssets](ReimportAllAssets.md) +- [ReimportAsset](ReimportAsset.md) + +每写一次状态，`revision` 都会递增一次。也就是说，`revision` 代表的是“状态槽位被写了多少次”，而不是“一共执行了多少次高层命令”。 + +### 维护与按需导入 + +- [Refresh](Refresh.md) + - 仅在 `removedArtifactCount > 0` 时写一条完成状态 +- [EnsureArtifact](EnsureArtifact.md) + - 失败时写失败状态 + - 成功时仅在“本次真的发生导入”时写成功状态 + - 纯缓存命中不会覆盖最近状态 + +## 为什么 `inProgress` 现在不常见 + +虽然实现里确实有 `BeginImportStatusLocked(...)`，会产生 `inProgress=true` 的开始状态，但当前所有公开操作都在同一把 `std::recursive_mutex` 中同步执行，而 [GetLastImportStatus](GetLastImportStatus.md) 也需要拿这把锁。 + +因此在当前实现下，外部调用者通常只能在命令返回后读到最终状态。`inProgress` 更像是为未来的异步导入或更细的状态观察能力预留的字段。 + +## 设计意义 + +把状态模型显式做成结构体，有几个现实价值： + +- 测试可以稳定断言操作名、成功位和统计值。 +- 编辑器工具可以把最近一次导入结果展示在状态栏、日志窗或工具提示里。 +- 后续如果要做后台任务系统，可以在不破坏 API 形状的前提下扩展更多状态来源。 + +## 相关文档 + +- [AssetImportService](AssetImportService.md) +- [GetLastImportStatus](GetLastImportStatus.md) +- [ClearLibraryCache](ClearLibraryCache.md) +- [ReimportAllAssets](ReimportAllAssets.md) +- [ReimportAsset](ReimportAsset.md) +- [Refresh](Refresh.md) +- [EnsureArtifact](EnsureArtifact.md) diff --git a/docs/api/XCEngine/Core/Asset/AssetImportService/ImportedAsset.md b/docs/api/XCEngine/Core/Asset/AssetImportService/ImportedAsset.md index 3d9f4c7c..3f0fe66a 100644 --- a/docs/api/XCEngine/Core/Asset/AssetImportService/ImportedAsset.md +++ b/docs/api/XCEngine/Core/Asset/AssetImportService/ImportedAsset.md @@ -8,42 +8,72 @@ ## 概览 -`ImportedAsset` 是 `AssetImportService::EnsureArtifact()` 向上层返回的轻量结果对象。它把 `AssetDatabase::ResolvedAsset` 转成更适合运行时消费的形态。 +`ImportedAsset` 是 [EnsureArtifact](EnsureArtifact.md) 和 [ReimportAsset](ReimportAsset.md) 返回给上层的轻量结果对象。它不是持久化数据库记录，而是由 `AssetImportService::ConvertResolvedAsset()` 从底层 [AssetDatabase::ResolvedAsset](../AssetDatabase/ResolvedAsset.md) 转出来的服务层快照。 + +这样做的目的，是让 `ResourceManager`、编辑器工具和测试直接拿到“可消费结果”，而不必了解底层 source/artifact 数据库的内部结构。 ## 当前字段 - `exists` - - source 资产是否存在 + - source asset 是否存在。 - `artifactReady` - - 对应主 artifact 是否已经就绪 + - 当前是否已经有可直接使用的主 artifact。 +- `imported` + - 这次调用是否真的触发了导入。 + - 对 [EnsureArtifact](EnsureArtifact.md) 而言，这个字段用来区分“缓存命中复用”和“本次真的发生了导入”。 + - 对 [ReimportAsset](ReimportAsset.md) 而言，当前成功路径里它会是 `true`。 - `absolutePath` - - source 资产绝对路径 + - source asset 的绝对路径。 - `relativePath` - - 项目内相对路径，通常是 `Assets/...` + - 项目内相对路径，通常是 `Assets/...`。 - `assetGuid` - - source 资产的稳定身份 + - source asset 的稳定身份，来自 `.meta`。 - `resourceType` - - 当前导入得到的主资源类型 + - 当前 importer 推导出来的主资源类型。 - `runtimeLoadPath` - - 运行时实际应交给 loader 的路径 - - `ConvertResolvedAsset()` 会在 `artifactReady=true` 时写入主 artifact 绝对路径 - - 否则回退到 `absolutePath` + - 上层真正应交给 loader 的路径。 + - 当前转换规则是：`artifactReady=true` 时使用主 artifact 绝对路径，否则退回 source 绝对路径。 - `artifactDirectory` - - 当前 artifact 目录的绝对路径 + - 当前 artifact 目录的绝对路径。 - `mainLocalID` - - 当前主资产的 local ID，默认值是 `kMainAssetLocalID` + - 主资产的 local ID，默认是 `kMainAssetLocalID`。 -## 当前实现语义 +## 字段语义 -- 它不是持久化格式，也不是数据库记录本身；只是服务层返回给运行时装配链路的结果快照 -- `ResourceManager::LoadResource()` 主要依赖它决定: - - 是否把请求路径切换成 artifact 主文件路径 - - 是否把 `assetGuid -> relativePath` 关系回填给 `ProjectAssetIndex` -- 虽然结构体字段允许表达“source 已知但 artifact 尚未就绪”的形态，但按当前 `AssetImportService::EnsureArtifact()` 的公开成功路径，调用方实际拿到的结果总是 `artifactReady=true` +### `imported` 不等于“是否成功” + +最容易误解的字段是 `imported`。它表示的是“这次调用是否真的做了导入工作”，不是“这次调用有没有成功”。 + +- `true` + - 说明这次调用确实重新生成了 artifact。 +- `false` + - 说明这次调用可能只是复用了已有 artifact。 + - 这在 [EnsureArtifact](EnsureArtifact.md) 的缓存命中路径里是正常且常见的。 + +因此，不要把 `imported=false` 误读成失败。 + +### `runtimeLoadPath` 是给运行时加载器的 + +`absolutePath` 描述的是 source asset 的作者路径，`runtimeLoadPath` 描述的是运行时真正要读的路径。 + +这两者分开的意义在于： + +- 资产身份、回溯和编辑器显示依然锚定 source 路径。 +- 运行时读取优先走导入产物，而不是每次重新解析作者格式。 + +这正是商业引擎常见的“作者资源”和“运行时产物”分层。 + +## 当前成功路径 + +- [EnsureArtifact](EnsureArtifact.md) 成功时，当前实现要求主 artifact 已经可直接使用，所以 `artifactReady` 会是 `true`。 +- [ReimportAsset](ReimportAsset.md) 成功时，当前实现会强制重建 artifact，因此 `imported` 也会是 `true`。 +- 虽然 `runtimeLoadPath` 的转换规则保留了“fallback 到 source 路径”的通用形态，但当前这两个公开成功路径里，它现实上通常都指向 `Library/Artifacts/.../main.*`。 ## 相关文档 - [AssetImportService](AssetImportService.md) - [EnsureArtifact](EnsureArtifact.md) +- [ReimportAsset](ReimportAsset.md) +- [ImportStatusSnapshot](ImportStatusSnapshot.md) - [AssetDatabase::ResolvedAsset](../AssetDatabase/ResolvedAsset.md) - [ResourceManager](../ResourceManager/ResourceManager.md) diff --git a/docs/api/XCEngine/Core/Asset/AssetImportService/RebuildLibraryCache.md b/docs/api/XCEngine/Core/Asset/AssetImportService/RebuildLibraryCache.md index e0c64bd4..106992bb 100644 --- a/docs/api/XCEngine/Core/Asset/AssetImportService/RebuildLibraryCache.md +++ b/docs/api/XCEngine/Core/Asset/AssetImportService/RebuildLibraryCache.md @@ -14,28 +14,57 @@ bool RebuildLibraryCache(); ## 作用 -删除当前项目的 `Library` 目录，并重新初始化 `AssetDatabase`。 +清空当前项目 `Library`，然后批量重导全部可导入项目资产。 + +它是一个组合命令，适合“把项目导入缓存完全重建一遍”的编辑器工具场景。 ## 当前实现行为 -- 在 `std::recursive_mutex` 保护下执行 -- 如果当前没有项目根，直接返回 `false` -- 否则会: - 1. 记录当前 `projectRoot` 和 `libraryRoot` - 2. `m_assetDatabase.Shutdown()` - 3. 调用 `std::filesystem::remove_all(libraryRoot, ec)` - 4. 用原来的 `projectRoot` 重新 `Initialize()` -- 返回值表示 `remove_all` 是否没有报告错误，而不是“实际删除了多少文件” +当前实现没有单独的“Rebuild Library”底层流程，而是直接串联两个现有命令： -## 当前语义 +```text +ClearLibraryCache() +-> ReimportAllAssets() +``` -- 这是导入缓存层的重建入口，比普通的 [Refresh](Refresh.md) 更重 -- 它不会改动 `.meta` 里的 `AssetGUID`，因此已生成 `AssetRef` 的稳定性仍由 source 资产身份保证 -- `tests/core/Asset/test_resource_manager.cpp` 中的 `AssetImportService_Test.RebuildLibraryCacheKeepsStableAssetRefs` 专门覆盖了这条语义 +因此它的返回值语义也非常直接： + +- `ClearLibraryCache()` 失败，立刻返回 `false` +- `ClearLibraryCache()` 成功后，再返回 `ReimportAllAssets()` 的结果 + +## 和单独调用两步命令的关系 + +`RebuildLibraryCache()` 的真正价值，不在于它做了新的事情，而在于它把“清缓存”和“全量重导”收口成了一个稳定的高级命令。 + +这对编辑器和自动化脚本有两个好处： + +- 调用方不必自己理解正确顺序。 +- 后续如果实现要调整，仍然可以把变化收敛在这个组合入口里。 + +## 导入状态语义 + +需要注意，`RebuildLibraryCache()` 当前不会写出一个新的复合状态名。它最终留下的最近一次状态取决于最后完成的那一步： + +- 如果 `ClearLibraryCache()` 失败 + - 最近状态来自 [ClearLibraryCache](ClearLibraryCache.md) +- 如果清理成功并进入批量重导 + - 最终最近状态来自 [ReimportAllAssets](ReimportAllAssets.md) + +这意味着调用方如果在成功后读取 [GetLastImportStatus](GetLastImportStatus.md)，看到的 `operation` 会是 `"Reimport All Assets"`，而不是 `"Rebuild Library"`。 + +## 为什么这样设计 + +这和 Unity 一类引擎里“Library 可删、可重建”的理念一致： + +- `Library` 是缓存，不是资产身份真相。 +- 真正稳定的身份来自 source 目录和 `.meta` 里的 `AssetGUID`。 + +测试 `AssetImportService_Test.RebuildLibraryCacheKeepsStableAssetRefs` 也正是在验证这一点：即使整份 `Library` 被重建，只要 `.meta` 还在，已有 `AssetRef` 的 GUID / local ID 语义就不应被破坏。 ## 相关文档 - [AssetImportService](AssetImportService.md) -- [GetLibraryRoot](GetLibraryRoot.md) -- [Refresh](Refresh.md) +- [ClearLibraryCache](ClearLibraryCache.md) +- [ReimportAllAssets](ReimportAllAssets.md) +- [GetLastImportStatus](GetLastImportStatus.md) - [ResourceManager::RebuildProjectAssetCache](../ResourceManager/RebuildProjectAssetCache.md) diff --git a/docs/api/XCEngine/Core/Asset/AssetImportService/Refresh.md b/docs/api/XCEngine/Core/Asset/AssetImportService/Refresh.md index ff92e9e5..225f585d 100644 --- a/docs/api/XCEngine/Core/Asset/AssetImportService/Refresh.md +++ b/docs/api/XCEngine/Core/Asset/AssetImportService/Refresh.md @@ -14,15 +14,43 @@ void Refresh(); ## 作用 -刷新当前项目根对应的资产数据库。 +刷新当前项目的 source asset 快照，并在需要时清理已经失去 source 归属的孤儿 artifact。 + +这一步对应的是“扫描与维护”，不是“显式重导入”。如果你想强制重建 artifact，应使用 [ReimportAsset](ReimportAsset.md) 或 [ReimportAllAssets](ReimportAllAssets.md)。 ## 当前实现行为 -- 在 `std::recursive_mutex` 保护下执行。 -- 只有 `m_projectRoot` 非空时才会调用 `AssetDatabase::Refresh()`。 -- 空项目根下调用会被安全忽略。 +1. 在 `std::recursive_mutex` 保护下执行。 +2. 如果当前没有活动项目根，直接返回，不写状态，也不报错。 +3. 如果项目根有效，则调用 [AssetDatabase::Refresh](../AssetDatabase/Refresh.md)。 +4. 只有当底层返回的 `removedArtifactCount > 0` 时，才会写入新的 [ImportStatusSnapshot](ImportStatusSnapshot.md)： + - `operation = "Refresh"` + - `targetPath = projectRoot` + - `success = true` + - `removedArtifactCount = stats.removedArtifactCount` + +换句话说，`Refresh()` 当前可能真的修改了 source/artifact 数据库，但只在“清理掉了孤儿 artifact”时才刷新对外可见的导入状态。 + +## 为什么这样设计 + +这和商业级引擎里常见的 `Refresh` / `Reimport` 分层一致： + +- `Refresh` 负责把磁盘真实状态重新同步回数据库。 +- `Reimport` 负责显式重建可再生的导入产物。 + +这样做的好处是，编辑器可以把“目录扫描”和“强制重建”拆成两类命令。前者更轻、更适合作为常规维护；后者更重、更适合用户明确触发。 + +## 使用建议 + +- 项目切换后、批量工具命令前，可以先调用 `Refresh()`，让 source 快照和孤儿清理先收敛到最新磁盘状态。 +- 如果你需要判断这次 `Refresh()` 是否真的清理了产物，可以在调用后读取 [GetLastImportStatus](GetLastImportStatus.md)，但要记住：只有在 `removedArtifactCount > 0` 时它才会更新。 +- 不要把 `Refresh()` 当成“全量重建 Library”的替代品。 ## 相关文档 - [AssetImportService](AssetImportService.md) -- [BuildLookupSnapshot](BuildLookupSnapshot.md) +- [GetLastImportStatus](GetLastImportStatus.md) +- [ImportStatusSnapshot](ImportStatusSnapshot.md) +- [AssetDatabase::Refresh](../AssetDatabase/Refresh.md) +- [ReimportAsset](ReimportAsset.md) +- [ReimportAllAssets](ReimportAllAssets.md) diff --git a/docs/api/XCEngine/Core/Asset/AssetImportService/ReimportAllAssets.md b/docs/api/XCEngine/Core/Asset/AssetImportService/ReimportAllAssets.md new file mode 100644 index 00000000..32af180b --- /dev/null +++ b/docs/api/XCEngine/Core/Asset/AssetImportService/ReimportAllAssets.md @@ -0,0 +1,92 @@ +# AssetImportService::ReimportAllAssets + +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/AssetImportService.h` + +## 签名 + +```cpp +bool ReimportAllAssets(); +``` + +## 作用 + +强制重导当前项目快照中的全部可导入 source asset，并把统计结果写入最近一次导入状态。 + +这是编辑器和工具层的显式批处理命令，不是运行时热路径 API。 + +## 当前实现流程 + +1. 在 `std::recursive_mutex` 保护下执行。 +2. 如果当前没有活动项目根： + - 写入失败状态：`operation = "Reimport All Assets"` + - 返回 `false` +3. 如果项目根有效： + - 先写入开始状态 + - 先调用底层 `m_assetDatabase.Refresh()` + - 再调用 `m_assetDatabase.ReimportAllAssets(&stats)` + - 按最终结果写入完成状态并返回成功位 + +## 底层真实边界 + +底层 [AssetDatabase::ReimportAllAssets](../AssetDatabase/ReimportAllAssets.md) 当前会： + +- 只遍历当前 source 快照里的可导入记录 +- 跳过目录 +- 跳过 `Unknown` primary type +- 跳过已经缺失或变成目录的文件 +- 按 `relativePath` 排序后逐个重导 +- 单个条目失败不会中断整个批次 +- 最终返回“本批次是否全部成功”的总成功位 + +因此，这个服务层方法也继承了相同的总体语义：它是“批量尽可能完成”，而不是“遇错立刻停”。 + +## 导入状态语义 + +完成后写出的 [ImportStatusSnapshot](ImportStatusSnapshot.md) 当前具有这些关键特征： + +- `operation = "Reimport All Assets"` +- `targetPath = projectRoot` +- `importedAssetCount` + - 来自显式重导步骤中实际成功导入的条目数 +- `removedArtifactCount` + - 来自显式重导结束后的孤儿清理统计 + +需要特别注意的是：方法开头那次前置 `Refresh()` 也可能清理 source 快照或移除孤儿 artifact，但那次扫描的统计不会合并进最终状态。当前状态统计只记录显式重导步骤本身。 + +## 为什么先 `Refresh()` + +先做一次 `Refresh()` 的目的，是让批量重导建立在“当前磁盘真实状态”之上，而不是建立在过时的 source 快照之上。 + +这样做的好处是： + +- 新增/删除文件先被 source DB 感知 +- 失效 source record 先被剔除 +- 批量重导针对的是最新项目视图 + +这和商业编辑器的“先同步资产数据库，再执行重导命令”是一致的。 + +## 测试锚点 + +`tests/Core/Asset/test_resource_manager.cpp` 里的以下测试直接约束了当前行为： + +- `AssetImportService_Test.ClearLibraryAndReimportAllAssetsManageArtifactsExplicitly` +- `AssetImportService_Test.ImportStatusTracksExplicitOperationsAndRefreshCleanup` + +从这些测试可以明确看出： + +- `ClearLibraryCache()` 后 `Artifacts` 可以为空 +- 再次 `ReimportAllAssets()` 后 artifact 会被重新批量生成 +- `GetLastImportStatus()` 会记录 `"Reimport All Assets"` 以及 `importedAssetCount` + +## 相关文档 + +- [AssetImportService](AssetImportService.md) +- [ReimportAsset](ReimportAsset.md) +- [ClearLibraryCache](ClearLibraryCache.md) +- [GetLastImportStatus](GetLastImportStatus.md) +- [ImportStatusSnapshot](ImportStatusSnapshot.md) +- [AssetDatabase::ReimportAllAssets](../AssetDatabase/ReimportAllAssets.md) diff --git a/docs/api/XCEngine/Core/Asset/AssetImportService/ReimportAsset.md b/docs/api/XCEngine/Core/Asset/AssetImportService/ReimportAsset.md new file mode 100644 index 00000000..45ac6966 --- /dev/null +++ b/docs/api/XCEngine/Core/Asset/AssetImportService/ReimportAsset.md @@ -0,0 +1,91 @@ +# AssetImportService::ReimportAsset + +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/AssetImportService.h` + +## 签名 + +```cpp +bool ReimportAsset( + const Containers::String& requestPath, + ImportedAsset& outAsset); +``` + +## 作用 + +强制重导指定项目资产，并把结果以 [ImportedAsset](ImportedAsset.md) 的形式返回给调用方。 + +这适合编辑器里的“重导当前选中资产”“修复单个 artifact”或自动化校验脚本。 + +## 当前实现流程 + +1. 在 `std::recursive_mutex` 保护下执行。 +2. 如果当前没有活动项目根： + - 写入失败状态：`operation = "Reimport Asset"` + - 返回 `false` +3. 如果项目根有效： + - 先写开始状态 + - 先执行 `m_assetDatabase.Refresh()` + - 再调用底层 `m_assetDatabase.ReimportAsset(requestPath, resolvedAsset, &stats)` +4. 底层成功后： + - 把 `resolvedAsset` 转成 [ImportedAsset](ImportedAsset.md) + - 写入成功状态 + - 返回 `true` +5. 底层失败时： + - 写入失败状态 + - 返回 `false` + +## 对 `requestPath` 的真实要求 + +这个方法最终受到底层 [AssetDatabase::ReimportAsset](../AssetDatabase/ReimportAsset.md) 的边界约束。当前成功路径要求： + +- 请求必须能解析到项目内 `Assets/...` +- 目标必须存在 +- 目标必须是文件而不是目录 +- 当前 importer 的 primary `ResourceType` 不能是 `Unknown` + +因此它不是“任意路径的文件重建命令”，而是“单个可导入 project asset 的重导命令”。 + +## `outAsset` 的有效性 + +当前实现只有在底层重导成功后，才会给 `outAsset` 赋值。 + +这意味着： + +- 返回 `true` 时，`outAsset` 有效，且当前成功路径里 `outAsset.imported == true` +- 返回 `false` 时，调用方不能假设 `outAsset` 已被清空 + +如果你在失败后继续读取 `outAsset`，读到的可能是调用前残留的旧值。 + +## 导入状态语义 + +完成后写出的 [ImportStatusSnapshot](ImportStatusSnapshot.md) 当前具有这些特点： + +- `operation = "Reimport Asset"` +- `targetPath = requestPath` +- 成功时 `importedAssetCount = 1` +- `removedArtifactCount` 来自底层显式重导结束后的孤儿清理 + +和 [ReimportAllAssets](ReimportAllAssets.md) 一样，前置 `Refresh()` 产生的维护统计不会合并进最终状态。 + +## 为什么这是显式工具命令 + +和 [EnsureArtifact](EnsureArtifact.md) 相比，`ReimportAsset()` 的定位更接近编辑器工具而不是运行时保障： + +- 它不等待“是否有必要重导”的判断，而是直接强制重建 +- 它会始终把成功结果当作一次新的导入事件记录下来 +- 它更适合用户明确触发的诊断/修复动作 + +这种把“按需保证可用”和“显式强制重建”拆开的设计，在商业引擎文档体系里是很常见的做法。 + +## 相关文档 + +- [AssetImportService](AssetImportService.md) +- [ImportedAsset](ImportedAsset.md) +- [ReimportAllAssets](ReimportAllAssets.md) +- [GetLastImportStatus](GetLastImportStatus.md) +- [ImportStatusSnapshot](ImportStatusSnapshot.md) +- [AssetDatabase::ReimportAsset](../AssetDatabase/ReimportAsset.md) diff --git a/docs/api/XCEngine/Core/Asset/AssetImportService/TryGetImportableResourceType.md b/docs/api/XCEngine/Core/Asset/AssetImportService/TryGetImportableResourceType.md new file mode 100644 index 00000000..3817f8f4 --- /dev/null +++ b/docs/api/XCEngine/Core/Asset/AssetImportService/TryGetImportableResourceType.md @@ -0,0 +1,74 @@ +# AssetImportService::TryGetImportableResourceType + +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/AssetImportService.h` + +## 签名 + +```cpp +bool TryGetImportableResourceType( + const Containers::String& requestPath, + ResourceType& outType) const; +``` + +## 作用 + +探测指定请求路径在当前 importer 规则下对应的 primary `ResourceType`。 + +它的定位是“轻量类型探测”，不是“真正执行导入”。 + +## 当前实现行为 + +1. 在 `std::recursive_mutex` 保护下执行。 +2. 如果当前没有活动项目根： + - 把 `outType` 设为 `ResourceType::Unknown` + - 返回 `false` +3. 如果项目根有效： + - 直接转发到底层 [AssetDatabase::TryGetImportableResourceType](../AssetDatabase/TryGetImportableResourceType.md) + +## 底层真实边界 + +当前底层成功路径要求： + +- 请求路径必须能归一化到项目内的 `Assets/...` +- 目标必须存在 +- 目标必须是文件而不是目录 +- 当前 importer 的 primary `ResourceType` 不能是 `Unknown` + +因此以下情形都会失败： + +- 项目外路径 +- 目录路径 +- 不存在的路径 +- 当前由 `DefaultImporter` / `FolderImporter` 处理、主类型为 `Unknown` 的资源 + +## 为什么要单独提供这个接口 + +它非常适合做编辑器侧的“前置判断”： + +- 这个路径能不能参与重导？ +- 当前它大概会被当作什么资源类型处理？ +- 是否应该显示“Reimport”或“打开导入设置”这类工具按钮？ + +把这类轻量探测从真正的导入流程里拆出来，可以让 UI 与工具脚本先做无副作用的判断，再决定是否进入更重的命令。 + +## 当前实现边界 + +- 它只回答“主资源类型是什么”，不保证真正导入一定成功。 +- 文件内容损坏、依赖缺失、写 artifact 失败这类问题，只有真正导入时才能暴露。 + +## 测试锚点 + +`tests/Core/Asset/test_resource_manager.cpp` 里的 +`AssetImportService_Test.ClearLibraryAndReimportAllAssetsManageArtifactsExplicitly` +直接验证了当前 `Assets/runtime.material -> ResourceType::Material` 的行为。 + +## 相关文档 + +- [AssetImportService](AssetImportService.md) +- [ReimportAsset](ReimportAsset.md) +- [ReimportAllAssets](ReimportAllAssets.md) +- [AssetDatabase::TryGetImportableResourceType](../AssetDatabase/TryGetImportableResourceType.md) diff --git a/docs/api/XCEngine/Core/Asset/AsyncLoader/AsyncLoader.md b/docs/api/XCEngine/Core/Asset/AsyncLoader/AsyncLoader.md index b6805dac..b1edcb94 100644 --- a/docs/api/XCEngine/Core/Asset/AsyncLoader/AsyncLoader.md +++ b/docs/api/XCEngine/Core/Asset/AsyncLoader/AsyncLoader.md @@ -6,25 +6,24 @@ **头文件**: `XCEngine/Core/Asset/AsyncLoader.h` -**描述**: 为资源异步加载预留的请求队列与回调分发接口，但当前实现仍明显未完成。 +**描述**: 资源系统当前实际可用的后台加载器。它维护待处理队列、工作线程和完成队列，但回调分发仍需要主线程显式调用 `Update()` 驱动。 ## 角色概述 -`AsyncLoader` 的 API 形状表达得很清楚：它想成为资源系统里的后台加载服务，负责接收 `LoadRequest`、在工作线程里执行 loader，然后把结果回送给主线程或调用方。 +`AsyncLoader` 处在当前资源系统的“后台执行层”： -这也是商业引擎资源系统非常常见的一层设计，因为真正的资源加载通常要考虑： +- `ResourceManager::LoadAsync()` 把请求转给它 +- 工作线程调用 `ResourceManager::LoadResource()` 做真实加载 +- 完成结果先进入 `m_completedQueue` +- 调用方线程再通过 [Update](Update.md) 把结果分发成回调 -- 后台 I/O -- 导入配置复制 -- 回调线程切换 -- 进度统计 -- 取消与批量清理 +这意味着它已经不是纯架构草图，但也还不是“提交后完全自驱”的成熟异步系统。 -但当前版本还只搭好了外形，没有把执行链真正闭环。 +## 请求与完成模型 -## 当前结构 +### `LoadRequest` -`LoadRequest` 当前包含： +每个请求当前包含： - `path` - `type` @@ -32,83 +31,131 @@ - `settings` - `requestId` -`requestId` 通过原子自增静态计数器生成。 +`requestId` 由 `LoadRequest::GenerateRequestId()` 用原子自增计数器生成。 -`AsyncLoader` 自身同时提供两种使用方式： +### 执行链路 -- `AsyncLoader::Get()` 返回全局单例 -- [ResourceManager](../ResourceManager/ResourceManager.md) 在 `Initialize()` 中再拥有一个自己的 `AsyncLoader` 实例 +当前真实链路是： -这说明当前架构上已经出现“双入口”现象。真实运行时主要走的是 `ResourceManager` 持有的那一份，而不是 `AsyncLoader::Get()` 单例。 +```text +Submit(...) +-> SubmitInternal(...) +-> m_pendingQueue +-> WorkerThread() +-> ResourceManager::LoadResource(...) +-> QueueCompleted(...) +-> Update() +-> callback(result) +``` + +要特别注意两点： + +1. 后台线程只负责把结果放进完成队列，不直接触发用户回调。 +2. 同一路径/类型的去重不在 `AsyncLoader` 自身完成，而是依赖 `ResourceManager::LoadResource()` 的 in-flight 去重逻辑。 + +## 生命周期 + +### 初始化 + +[Initialize](Initialize.md) 当前会： + +- 用 `m_running.exchange(true)` 防止重复启动 +- 把 `workerThreadCount == 0` 纠正为 `1` +- 创建对应数量的工作线程 + +因此现在的 `workerThreadCount` 已经是实际生效参数，不再是旧文档里说的“被忽略”。 + +### 关闭 + +[Shutdown](Shutdown.md) 当前会： + +- 停止接收新请求 +- 清空仍在 pending 队列中的请求 +- 唤醒并等待所有工作线程退出 +- 清空完成队列 +- 重置计数器 + +这一步会丢弃“尚未通过 `Update()` 分发出去”的结果，不会补发取消回调。 ## 当前行为 -### 初始化与关闭 - -- `Initialize(workerThreadCount)` 当前直接忽略参数，不创建线程。 -- `Shutdown()` 当前只是调用 `CancelAll()`。 - -也就是说，初始化并不会启动任何真正的后台执行环境。 - ### 提交请求 -`Submit()` 当前流程是： +[Submit](Submit.md) 当前的关键语义是： -1. 组装 `LoadRequest` -2. 通过 `FindLoader(type)` 查找 loader -3. 如果没有 loader，立即通过回调返回失败结果 -4. 如果有 loader，只把请求推入 `m_pendingQueue` -5. 递增 `m_pendingCount` 与 `m_totalRequested` +- 没有对应 loader 时，立即通过回调返回失败结果 +- `AsyncLoader` 未初始化时，立即通过回调返回 `"Async loader is not initialized"` +- 成功入队后： + - `m_pendingCount++` + - `m_totalRequested++` + - 唤醒一个工作线程 -关键点在第 4 步之后就结束了。当前没有工作线程，也没有任何地方会真正从 `m_pendingQueue` 取出请求并调用 `loader->Load()`。 +### 工作线程 -### 更新与完成回调 +每个工作线程都会循环： -`Update()` 当前只会处理 `m_completedQueue`。但现在的 `QueueCompleted()` 是空实现，所以成功加载请求根本不会进入完成队列。 +1. 等待 `m_pendingCondition` +2. 从 `m_pendingQueue` 取出一个请求 +3. 调用 `ResourceManager::LoadResource(path, type, settings)` +4. 捕获异常并转换成失败 `LoadResult` +5. 把结果放入 `m_completedQueue` -这意味着： +因此“真实加载”已经发生在后台线程，而不是像旧文档描述的那样永远卡在 pending 队列里。 -- “无 loader”的失败回调会立即触发 -- “有 loader”的请求会一直留在 pending 队列里 -- `IsLoading()` 可能长期保持 true -- `GetProgress()` 也不会自然推进到你期待的完成状态 +### 完成分发 -## 导入配置与生命周期边界 +[Update](Update.md) 是当前异步加载闭环的最后一步。它会： -`LoadRequest` 保存的是 `ImportSettings*` 裸指针。当前版本里： +- 取走整份 `m_completedQueue` +- 对每个完成项： + - `m_pendingCount--` + - `m_completedCount++` + - 调用请求回调 -- `Submit()` 不会克隆 settings -- 队列里只是保留原始指针 -- 由于真正后台执行逻辑还没做完，这个问题暂时没有完全暴露 +所以： -但从接口契约上讲，这已经说明未来如果异步路径做实，调用方就不能假设 settings 会被安全复制。当前文档必须把这个生命周期边界讲清楚。 +- `callback` 默认运行在调用 `Update()` 的线程上 +- 如果主线程不调用 `Update()`，后台完成的加载不会自动通知上层 -## 设计取向 +## 进度与状态语义 -把异步加载单独做成服务是对的。它让资源系统可以朝商业引擎常见的“主线程驱动资源引用，后台线程完成 I/O 与解码”的方向演进。 +- [IsLoading](IsLoading.md) 等价于 `m_pendingCount > 0` +- [GetPendingCount](GetPendingCount.md) 返回的不是单纯队列长度，而是“尚未经 `Update()` 分发完成”的请求数 +- [GetProgress](GetProgress.md) 使用： -但当前版本更准确的描述应该是： +```text +(m_totalRequested - m_pendingCount) / m_totalRequested +``` -- 它是异步加载架构草图 -- 不是已经可投产的后台加载器 +这意味着进度推进点在 `Update()`，而不是工作线程刚完成加载的瞬间。 -如果你需要稳定的当前行为，应该优先走 [ResourceManager::Load](../ResourceManager/Load.md) 的同步路径。 +## 取消语义 -## 线程语义 +- [CancelAll](CancelAll.md) 只会移除仍留在 `m_pendingQueue` 里的请求 +- [Cancel](Cancel.md) 只会尝试按 `requestId` 删除尚未被工作线程取走的请求 -- `m_pendingQueue` 和 `m_completedQueue` 各自有独立 mutex 保护。 -- `m_pendingCount` / `m_completedCount` 使用原子计数。 -- 但没有真实工作线程，也没有完整的跨线程回调时序保证。 +当前都**不会**： -## 当前实现限制 +- 中断已经在执行中的 `LoadResource()` +- 清掉已进入 `m_completedQueue` 但尚未分发的结果 +- 为取消请求补发失败或取消回调 -- `Initialize()` 忽略 `workerThreadCount`。 -- 没有后台线程处理 `m_pendingQueue`。 -- `QueueCompleted()` 是空实现。 -- `Update()` 只能消费完成队列，但当前没有成功请求会进入完成队列。 -- `Cancel(requestId)` 是 stub。 -- `AsyncLoader::Get()` 与 `ResourceManager` 自持实例并存，架构入口不统一。 -- `ImportSettings*` 当前按裸指针跨请求传递，没有复制或所有权说明。 +## 双入口现实 + +`AsyncLoader` 现在仍同时存在两种入口： + +- [Get](Get.md) 返回静态单例 +- `ResourceManager` 在 `EnsureInitialized()` 里自持一份 `m_asyncLoader` + +当前主运行时路径主要使用的是 `ResourceManager` 持有的实例，而不是 `AsyncLoader::Get()` 单例。 + +## 当前实现边界 + +- 回调分发仍是手动轮询模型，必须显式调用 `Update()`。 +- `ImportSettings*` 仍按裸指针跨线程传递，没有复制或所有权封装。 +- 取消只覆盖“尚未开始执行”的请求，不支持中断正在加载的资源。 +- `Shutdown()` 会丢弃未分发完成的结果，不会补回调。 +- 单例入口与 `ResourceManager` 自持实例并存，架构入口仍不完全统一。 ## 相关方法 diff --git a/docs/api/XCEngine/Core/Asset/AsyncLoader/Cancel.md b/docs/api/XCEngine/Core/Asset/AsyncLoader/Cancel.md index ec7f0891..1f965351 100644 --- a/docs/api/XCEngine/Core/Asset/AsyncLoader/Cancel.md +++ b/docs/api/XCEngine/Core/Asset/AsyncLoader/Cancel.md @@ -1,31 +1,38 @@ # AsyncLoader::Cancel -判断当前条件下是否可执行。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/AsyncLoader.h` + +## 签名 ```cpp void Cancel(Core::uint64 requestId); ``` -该方法声明于 `XCEngine/Core/Asset/AsyncLoader.h`，当前页面用于固定 `AsyncLoader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `requestId` - 参数语义详见头文件声明。 +按请求 id 取消一个尚未开始执行的异步加载请求。 -**返回：** `void` - 无返回值。 +## 当前实现行为 -**示例：** +当前实现会： -```cpp -#include +1. 锁住 `m_queueMutex` +2. 线性遍历 `m_pendingQueue` +3. 找到 `requestId` 匹配项后将其擦除 +4. 若 `m_pendingCount > 0`，执行一次 `m_pendingCount--` -void Example() { - XCEngine::Resources::AsyncLoader object; - // 根据上下文补齐参数后调用 AsyncLoader::Cancel(...)。 - (void)object; -} -``` +## 当前语义 + +- 它只会尝试删除“还在 pending 队列里”的请求。 +- 如果请求已经被工作线程取走、已经完成或根本不存在，这个方法什么都不会做。 +- 当前不会触发取消回调，也不会中断正在运行的加载。 ## 相关文档 -- [返回类总览](AsyncLoader.md) -- [返回模块目录](../Asset.md) +- [AsyncLoader](AsyncLoader.md) +- [CancelAll](CancelAll.md) +- [Submit](Submit.md) diff --git a/docs/api/XCEngine/Core/Asset/AsyncLoader/CancelAll.md b/docs/api/XCEngine/Core/Asset/AsyncLoader/CancelAll.md index 149def89..652d0cee 100644 --- a/docs/api/XCEngine/Core/Asset/AsyncLoader/CancelAll.md +++ b/docs/api/XCEngine/Core/Asset/AsyncLoader/CancelAll.md @@ -1,30 +1,39 @@ # AsyncLoader::CancelAll -判断当前条件下是否可执行。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/AsyncLoader.h` + +## 签名 ```cpp void CancelAll(); ``` -该方法声明于 `XCEngine/Core/Asset/AsyncLoader.h`，当前页面用于固定 `AsyncLoader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +移除所有尚未开始执行的异步请求。 -**返回：** `void` - 无返回值。 +## 当前实现行为 -**示例：** +当前实现会： -```cpp -#include +1. 锁住 `m_queueMutex` +2. 统计 `m_pendingQueue.size()` +3. 清空 `m_pendingQueue` +4. 相应减少 `m_pendingCount` -void Example() { - XCEngine::Resources::AsyncLoader object; - // 根据上下文补齐参数后调用 AsyncLoader::CancelAll(...)。 - (void)object; -} -``` +## 当前语义 + +- 它只作用于还在 pending 队列里的请求。 +- 已经被工作线程取走的请求不会受影响。 +- 已进入 `m_completedQueue` 但还没分发的结果也不会受影响。 +- 当前不会为这些被移除的请求补发取消回调。 ## 相关文档 -- [返回类总览](AsyncLoader.md) -- [返回模块目录](../Asset.md) +- [AsyncLoader](AsyncLoader.md) +- [Cancel](Cancel.md) +- [Shutdown](Shutdown.md) diff --git a/docs/api/XCEngine/Core/Asset/AsyncLoader/Constructor.md b/docs/api/XCEngine/Core/Asset/AsyncLoader/Constructor.md index 7b32716f..3aab071f 100644 --- a/docs/api/XCEngine/Core/Asset/AsyncLoader/Constructor.md +++ b/docs/api/XCEngine/Core/Asset/AsyncLoader/Constructor.md @@ -1,28 +1,32 @@ -# AsyncLoader::AsyncLoader() +# AsyncLoader::AsyncLoader -构造对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `constructor` + +**头文件**: `XCEngine/Core/Asset/AsyncLoader.h` + +## 签名 ```cpp AsyncLoader() = default; ``` -该方法声明于 `XCEngine/Core/Asset/AsyncLoader.h`，当前页面用于固定 `AsyncLoader` 类目录下的方法级 canonical 路径。 +## 当前实现行为 -**参数：** 无。 +默认构造不会创建工作线程，也不会触发任何 loader 注册。 -**返回：** `void` - 无返回值。 +对象初始状态的关键点是： -**示例：** +- `m_running = false` +- `m_pendingCount = 0` +- `m_completedCount = 0` +- `m_totalRequested = 0` +- `m_workerThreads` 为空 -```cpp -#include - -void Example() { - XCEngine::Resources::AsyncLoader object; -} -``` +只有在调用 [Initialize](Initialize.md) 之后，它才会变成真正工作的异步加载器。 ## 相关文档 -- [返回类总览](AsyncLoader.md) -- [返回模块目录](../Asset.md) +- [AsyncLoader](AsyncLoader.md) +- [Initialize](Initialize.md) diff --git a/docs/api/XCEngine/Core/Asset/AsyncLoader/Destructor.md b/docs/api/XCEngine/Core/Asset/AsyncLoader/Destructor.md index 9021fff8..ccc33c76 100644 --- a/docs/api/XCEngine/Core/Asset/AsyncLoader/Destructor.md +++ b/docs/api/XCEngine/Core/Asset/AsyncLoader/Destructor.md @@ -1,29 +1,28 @@ -# AsyncLoader::~AsyncLoader() +# AsyncLoader::~AsyncLoader -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::Resources` + +**类型**: `destructor` + +**头文件**: `XCEngine/Core/Asset/AsyncLoader.h` + +## 签名 ```cpp ~AsyncLoader() = default; ``` -该方法声明于 `XCEngine/Core/Asset/AsyncLoader.h`，当前页面用于固定 `AsyncLoader` 类目录下的方法级 canonical 路径。 +## 当前实现行为 -**参数：** 无。 +析构函数本身没有额外逻辑，不会自动调用 [Shutdown](Shutdown.md)。 -**返回：** `void` - 无返回值。 +## 当前语义 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::AsyncLoader object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 如果对象已经启动过工作线程，调用方应先显式 `Shutdown()`。 +- 当前主路径里，这个责任通常由 `ResourceManager::Shutdown()` 承担。 ## 相关文档 -- [返回类总览](AsyncLoader.md) -- [返回模块目录](../Asset.md) +- [AsyncLoader](AsyncLoader.md) +- [Shutdown](Shutdown.md) +- [ResourceManager](../ResourceManager/ResourceManager.md) diff --git a/docs/api/XCEngine/Core/Asset/AsyncLoader/Get.md b/docs/api/XCEngine/Core/Asset/AsyncLoader/Get.md index 2d399fb4..dd4cc758 100644 --- a/docs/api/XCEngine/Core/Asset/AsyncLoader/Get.md +++ b/docs/api/XCEngine/Core/Asset/AsyncLoader/Get.md @@ -1,29 +1,40 @@ # AsyncLoader::Get -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `static method` + +**头文件**: `XCEngine/Core/Asset/AsyncLoader.h` + +## 签名 ```cpp static AsyncLoader& Get(); ``` -该方法声明于 `XCEngine/Core/Asset/AsyncLoader.h`，当前页面用于固定 `AsyncLoader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回一个进程内静态 `AsyncLoader` 单例。 -**返回：** `AsyncLoader&` - 返回值语义详见头文件声明。 +## 当前实现行为 -**示例：** +当前实现是标准静态局部对象： ```cpp -#include - -void Example() { - auto& instance = XCEngine::Resources::AsyncLoader::Get(); - (void)instance; -} +static AsyncLoader instance; +return instance; ``` +它本身不会自动初始化工作线程；拿到实例后仍需显式调用 [Initialize](Initialize.md)。 + +## 当前语义 + +- 单例入口当前存在，但主资源加载路径通常不直接依赖它。 +- `ResourceManager` 在自身初始化时会创建并持有一份独立的 `AsyncLoader` 实例。 +- 因此这里更像“备用或独立使用入口”，不是当前运行时最常走的那条路径。 + ## 相关文档 -- [返回类总览](AsyncLoader.md) -- [返回模块目录](../Asset.md) +- [AsyncLoader](AsyncLoader.md) +- [Initialize](Initialize.md) +- [ResourceManager](../ResourceManager/ResourceManager.md) diff --git a/docs/api/XCEngine/Core/Asset/AsyncLoader/GetPendingCount.md b/docs/api/XCEngine/Core/Asset/AsyncLoader/GetPendingCount.md index dc90163f..34e52226 100644 --- a/docs/api/XCEngine/Core/Asset/AsyncLoader/GetPendingCount.md +++ b/docs/api/XCEngine/Core/Asset/AsyncLoader/GetPendingCount.md @@ -1,30 +1,41 @@ # AsyncLoader::GetPendingCount -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/AsyncLoader.h` + +## 签名 ```cpp Core::uint32 GetPendingCount() const; ``` -该方法声明于 `XCEngine/Core/Asset/AsyncLoader.h`，当前页面用于固定 `AsyncLoader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回当前尚未完成分发的异步请求数。 -**返回：** `Core::uint32` - 返回值语义详见头文件声明。 +## 当前实现行为 -**示例：** +当前实现直接返回原子计数器 `m_pendingCount`。 -```cpp -#include +## 当前语义 -void Example() { - XCEngine::Resources::AsyncLoader object; - // 根据上下文补齐参数后调用 AsyncLoader::GetPendingCount(...)。 - (void)object; -} -``` +它不是“待处理队列长度”，而是更接近： + +- 已提交 +- 还没被 [Update](Update.md) 扣减并分发完成 + +的请求数量。 + +因此： + +- 一个请求即使已经完成后台加载，只要回调还没经 `Update()` 分发出去，它仍可能计入这里。 +- `CancelAll()` / `Cancel(requestId)` 删除未开始执行的请求后，这个数字会同步下降。 ## 相关文档 -- [返回类总览](AsyncLoader.md) -- [返回模块目录](../Asset.md) +- [AsyncLoader](AsyncLoader.md) +- [IsLoading](IsLoading.md) +- [GetProgress](GetProgress.md) diff --git a/docs/api/XCEngine/Core/Asset/AsyncLoader/GetProgress.md b/docs/api/XCEngine/Core/Asset/AsyncLoader/GetProgress.md index a3200f74..3c41295a 100644 --- a/docs/api/XCEngine/Core/Asset/AsyncLoader/GetProgress.md +++ b/docs/api/XCEngine/Core/Asset/AsyncLoader/GetProgress.md @@ -1,30 +1,46 @@ # AsyncLoader::GetProgress -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/AsyncLoader.h` + +## 签名 ```cpp float GetProgress() const; ``` -该方法声明于 `XCEngine/Core/Asset/AsyncLoader.h`，当前页面用于固定 `AsyncLoader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +按当前计数器估算异步加载进度。 -**返回：** `float` - 返回值语义详见头文件声明。 +## 当前实现行为 -**示例：** +当前公式是： ```cpp -#include - -void Example() { - XCEngine::Resources::AsyncLoader object; - // 根据上下文补齐参数后调用 AsyncLoader::GetProgress(...)。 - (void)object; +if (m_totalRequested == 0) { + return 1.0f; } + +return float(m_totalRequested - m_pendingCount) / float(m_totalRequested); ``` +## 当前语义 + +- 在没有提交任何请求前，返回 `1.0f`。 +- 它统计的是“已提交请求里，有多少已经从 pending 状态完成分发”。 +- 因为 `m_pendingCount` 只会在 [Update](Update.md) 中递减，所以这个进度通常也是在 `Update()` 被调用后才前进。 + +## 当前边界 + +- 取消未开始的请求会降低 `m_pendingCount`，因此进度可能直接跳升。 +- 它不是字节级、阶段级或资源权重级进度，只是请求数层面的粗略比例。 + ## 相关文档 -- [返回类总览](AsyncLoader.md) -- [返回模块目录](../Asset.md) +- [AsyncLoader](AsyncLoader.md) +- [GetPendingCount](GetPendingCount.md) +- [Update](Update.md) diff --git a/docs/api/XCEngine/Core/Asset/AsyncLoader/Initialize.md b/docs/api/XCEngine/Core/Asset/AsyncLoader/Initialize.md index 5a2af6de..55145325 100644 --- a/docs/api/XCEngine/Core/Asset/AsyncLoader/Initialize.md +++ b/docs/api/XCEngine/Core/Asset/AsyncLoader/Initialize.md @@ -1,31 +1,38 @@ # AsyncLoader::Initialize -初始化内部状态。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/AsyncLoader.h` + +## 签名 ```cpp void Initialize(Core::uint32 workerThreadCount = 2); ``` -该方法声明于 `XCEngine/Core/Asset/AsyncLoader.h`，当前页面用于固定 `AsyncLoader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `workerThreadCount` - 参数语义详见头文件声明。 +启动 `AsyncLoader` 的后台工作线程。 -**返回：** `void` - 无返回值。 +## 当前实现行为 -**示例：** +当前流程是： -```cpp -#include +1. 用 `m_running.exchange(true)` 防止重复初始化。 +2. 如果 `workerThreadCount == 0`，自动纠正为 `1`。 +3. 预留线程容器容量。 +4. 创建指定数量的工作线程，并让每个线程执行 `WorkerThread()`。 -void Example() { - XCEngine::Resources::AsyncLoader object; - // 根据上下文补齐参数后调用 AsyncLoader::Initialize(...)。 - (void)object; -} -``` +## 当前语义 + +- 现在的 `workerThreadCount` 是真实生效参数，不再是旧文档描述的“被忽略”。 +- 对同一个对象重复调用时，第二次及后续调用会直接返回，不会重复起线程。 +- 它不会重置旧统计值；真正的清理与归零由 [Shutdown](Shutdown.md) 负责。 ## 相关文档 -- [返回类总览](AsyncLoader.md) -- [返回模块目录](../Asset.md) +- [AsyncLoader](AsyncLoader.md) +- [Shutdown](Shutdown.md) +- [Update](Update.md) diff --git a/docs/api/XCEngine/Core/Asset/AsyncLoader/IsLoading.md b/docs/api/XCEngine/Core/Asset/AsyncLoader/IsLoading.md index afbaf70b..104354d6 100644 --- a/docs/api/XCEngine/Core/Asset/AsyncLoader/IsLoading.md +++ b/docs/api/XCEngine/Core/Asset/AsyncLoader/IsLoading.md @@ -1,30 +1,43 @@ # AsyncLoader::IsLoading -查询当前状态。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/AsyncLoader.h` + +## 签名 ```cpp bool IsLoading() const; ``` -该方法声明于 `XCEngine/Core/Asset/AsyncLoader.h`，当前页面用于固定 `AsyncLoader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +判断当前是否还有尚未通过 `Update()` 分发完成的异步请求。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现行为 -**示例：** +当前实现直接返回： ```cpp -#include - -void Example() { - XCEngine::Resources::AsyncLoader object; - // 根据上下文补齐参数后调用 AsyncLoader::IsLoading(...)。 - (void)object; -} +m_pendingCount > 0 ``` +## 当前语义 + +这里的“loading”不是单纯指： + +- 还在 `m_pendingQueue` 里排队 + +而是更宽的集合： + +- 还在等待工作线程处理 +- 正在工作线程里执行 +- 已经完成，但还没被 [Update](Update.md) 取出并分发回调 + ## 相关文档 -- [返回类总览](AsyncLoader.md) -- [返回模块目录](../Asset.md) +- [AsyncLoader](AsyncLoader.md) +- [GetPendingCount](GetPendingCount.md) +- [Update](Update.md) diff --git a/docs/api/XCEngine/Core/Asset/AsyncLoader/Shutdown.md b/docs/api/XCEngine/Core/Asset/AsyncLoader/Shutdown.md index a6bd00b9..933e8719 100644 --- a/docs/api/XCEngine/Core/Asset/AsyncLoader/Shutdown.md +++ b/docs/api/XCEngine/Core/Asset/AsyncLoader/Shutdown.md @@ -1,30 +1,43 @@ # AsyncLoader::Shutdown -关闭并清理内部状态。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/AsyncLoader.h` + +## 签名 ```cpp void Shutdown(); ``` -该方法声明于 `XCEngine/Core/Asset/AsyncLoader.h`，当前页面用于固定 `AsyncLoader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +停止后台加载器，等待工作线程退出，并清理队列与统计状态。 -**返回：** `void` - 无返回值。 +## 当前实现行为 -**示例：** +当前实现分四步： -```cpp -#include +1. 锁住 `m_queueMutex`，把： + - `m_running = false` + - `m_pendingQueue.clear()` + - `m_pendingCount = 0` +2. `notify_all()` 唤醒所有工作线程。 +3. `join()` 所有工作线程并清空 `m_workerThreads`。 +4. 清空 `m_completedQueue`，并把： + - `m_completedCount = 0` + - `m_totalRequested = 0` -void Example() { - XCEngine::Resources::AsyncLoader object; - // 根据上下文补齐参数后调用 AsyncLoader::Shutdown(...)。 - (void)object; -} -``` +## 当前语义 + +- 仍在 pending 队列中的请求会被直接丢弃。 +- 已经在工作线程里开始执行的请求不会被强行中断；线程会跑完当前加载后再退出。 +- 但这些“关闭过程中完成”的结果随后也会被从 `m_completedQueue` 清掉，因此不会再通过 [Update](Update.md) 分发回调。 ## 相关文档 -- [返回类总览](AsyncLoader.md) -- [返回模块目录](../Asset.md) +- [AsyncLoader](AsyncLoader.md) +- [Initialize](Initialize.md) +- [CancelAll](CancelAll.md) diff --git a/docs/api/XCEngine/Core/Asset/AsyncLoader/Submit.md b/docs/api/XCEngine/Core/Asset/AsyncLoader/Submit.md index b6c56a85..b8fbfb59 100644 --- a/docs/api/XCEngine/Core/Asset/AsyncLoader/Submit.md +++ b/docs/api/XCEngine/Core/Asset/AsyncLoader/Submit.md @@ -1,49 +1,65 @@ # AsyncLoader::Submit -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Resources` -该方法在 `XCEngine/Core/Asset/AsyncLoader.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。 +**类型**: `method` -## 重载 1: 声明 +**头文件**: `XCEngine/Core/Asset/AsyncLoader.h` + +## 签名 ```cpp -void Submit(const Containers::String& path, ResourceType type, std::function callback); +void Submit( + const Containers::String& path, + ResourceType type, + std::function callback); + +void Submit( + const Containers::String& path, + ResourceType type, + ImportSettings* settings, + std::function callback); ``` -**参数：** -- `path` - 参数语义详见头文件声明。 -- `type` - 参数语义详见头文件声明。 -- `callback` - 参数语义详见头文件声明。 +## 作用 -**返回：** `void` - 无返回值。 +向后台加载器提交一个资源加载请求。 -## 重载 2: 声明 +## 当前实现行为 -```cpp -void Submit(const Containers::String& path, ResourceType type, ImportSettings* settings, std::function callback); -``` +无 `settings` 的重载只是把 `nullptr` 转发给带 `settings` 的版本。 -**参数：** -- `path` - 参数语义详见头文件声明。 -- `type` - 参数语义详见头文件声明。 -- `settings` - 参数语义详见头文件声明。 -- `callback` - 参数语义详见头文件声明。 +真正的入队逻辑发生在 `SubmitInternal()`： -**返回：** `void` - 无返回值。 +1. 先通过 `FindLoader(type)` 查找 loader。 +2. 若没有 loader： + - 不入队 + - 直接同步执行回调 + - 返回失败 `LoadResult("No loader for type: ...")` +3. 若 `AsyncLoader` 尚未初始化： + - 不入队 + - 直接同步执行回调 + - 返回失败 `LoadResult("Async loader is not initialized")` +4. 否则把请求压入 `m_pendingQueue`，并： + - `m_pendingCount++` + - `m_totalRequested++` +5. `notify_one()` 唤醒一个工作线程。 -**示例：** +## 参数语义 -```cpp -#include +- `path` - 交给后续 `ResourceManager::LoadResource()` 的资源路径。 +- `type` - 用来选择对应 `IResourceLoader`。 +- `settings` - 原样跨线程传递的 `ImportSettings*`，当前不会复制。 +- `callback` - 在后续 [Update](Update.md) 中分发的完成回调；但如果前置检查失败，也可能在 `Submit()` 调用点同步执行。 -void Example() { - XCEngine::Resources::AsyncLoader object; - // 根据上下文补齐参数后调用 AsyncLoader::Submit(...)。 - (void)object; -} -``` +## 当前边界 + +- `settings` 仍是裸指针，生命周期需要调用方自己保证。 +- 没有 loader 或未初始化时，回调会同步触发；因此它并不是“永远异步返回”。 +- 同一路径的请求不会在这里去重，真正的去重发生在 `ResourceManager::LoadResource()`。 ## 相关文档 -- [返回类总览](AsyncLoader.md) -- [返回模块目录](../Asset.md) +- [AsyncLoader](AsyncLoader.md) +- [Update](Update.md) +- [Cancel](Cancel.md) diff --git a/docs/api/XCEngine/Core/Asset/AsyncLoader/Update.md b/docs/api/XCEngine/Core/Asset/AsyncLoader/Update.md index 680e824c..8deaa12c 100644 --- a/docs/api/XCEngine/Core/Asset/AsyncLoader/Update.md +++ b/docs/api/XCEngine/Core/Asset/AsyncLoader/Update.md @@ -1,30 +1,41 @@ # AsyncLoader::Update -更新运行时状态。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/AsyncLoader.h` + +## 签名 ```cpp void Update(); ``` -该方法声明于 `XCEngine/Core/Asset/AsyncLoader.h`，当前页面用于固定 `AsyncLoader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +分发已经完成的后台加载结果。 -**返回：** `void` - 无返回值。 +## 当前实现行为 -**示例：** +当前实现会： -```cpp -#include +1. 锁住 `m_completedMutex` +2. 把整份 `m_completedQueue` 交换到局部变量 +3. 逐项处理完成结果： + - 若 `m_pendingCount > 0`，执行 `m_pendingCount--` + - `m_completedCount++` + - 调用该请求的 `callback` -void Example() { - XCEngine::Resources::AsyncLoader object; - // 根据上下文补齐参数后调用 AsyncLoader::Update(...)。 - (void)object; -} -``` +## 当前语义 + +- 回调运行在线程调用 `Update()` 的线程上。 +- 这通常意味着：后台线程完成加载后，主线程还需要定期 `Update()`，异步结果才会真正进入上层逻辑。 +- `GetProgress()` 和 `IsLoading()` 的状态推进点也是这里，而不是工作线程完成加载的瞬间。 ## 相关文档 -- [返回类总览](AsyncLoader.md) -- [返回模块目录](../Asset.md) +- [AsyncLoader](AsyncLoader.md) +- [Submit](Submit.md) +- [GetProgress](GetProgress.md) +- [IsLoading](IsLoading.md) diff --git a/docs/api/XCEngine/Core/Asset/IResource/Destructor.md b/docs/api/XCEngine/Core/Asset/IResource/Destructor.md index 38a66e18..4f590225 100644 --- a/docs/api/XCEngine/Core/Asset/IResource/Destructor.md +++ b/docs/api/XCEngine/Core/Asset/IResource/Destructor.md @@ -1,29 +1,25 @@ # IResource::~IResource() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/IResource.h` + +## 签名 ```cpp virtual ~IResource() = default; ``` -该方法声明于 `XCEngine/Core/Asset/IResource.h`，当前页面用于固定 `IResource` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +销毁 `IResource` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::IResource object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 当前为默认析构实现。 ## 相关文档 -- [返回类总览](IResource.md) -- [返回模块目录](../Asset.md) +- [IResource](IResource.md) diff --git a/docs/api/XCEngine/Core/Asset/IResource/GetGUID.md b/docs/api/XCEngine/Core/Asset/IResource/GetGUID.md index 8ba83e13..a56c92da 100644 --- a/docs/api/XCEngine/Core/Asset/IResource/GetGUID.md +++ b/docs/api/XCEngine/Core/Asset/IResource/GetGUID.md @@ -1,30 +1,25 @@ # IResource::GetGUID -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/IResource.h` + +## 签名 ```cpp virtual ResourceGUID GetGUID() const = 0; ``` -该方法声明于 `XCEngine/Core/Asset/IResource.h`，当前页面用于固定 `IResource` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `ResourceGUID` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::IResource object; - // 根据上下文补齐参数后调用 IResource::GetGUID(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](IResource.md) -- [返回模块目录](../Asset.md) +- [IResource](IResource.md) diff --git a/docs/api/XCEngine/Core/Asset/IResource/GetMemorySize.md b/docs/api/XCEngine/Core/Asset/IResource/GetMemorySize.md index 7c48ead4..5986ecb0 100644 --- a/docs/api/XCEngine/Core/Asset/IResource/GetMemorySize.md +++ b/docs/api/XCEngine/Core/Asset/IResource/GetMemorySize.md @@ -1,30 +1,25 @@ # IResource::GetMemorySize -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/IResource.h` + +## 签名 ```cpp virtual size_t GetMemorySize() const = 0; ``` -该方法声明于 `XCEngine/Core/Asset/IResource.h`，当前页面用于固定 `IResource` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `size_t` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::IResource object; - // 根据上下文补齐参数后调用 IResource::GetMemorySize(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](IResource.md) -- [返回模块目录](../Asset.md) +- [IResource](IResource.md) diff --git a/docs/api/XCEngine/Core/Asset/IResource/GetName.md b/docs/api/XCEngine/Core/Asset/IResource/GetName.md index fd21dbb4..f6e52a9c 100644 --- a/docs/api/XCEngine/Core/Asset/IResource/GetName.md +++ b/docs/api/XCEngine/Core/Asset/IResource/GetName.md @@ -1,30 +1,25 @@ # IResource::GetName -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/IResource.h` + +## 签名 ```cpp virtual const Containers::String& GetName() const = 0; ``` -该方法声明于 `XCEngine/Core/Asset/IResource.h`，当前页面用于固定 `IResource` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `const Containers::String&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::IResource object; - // 根据上下文补齐参数后调用 IResource::GetName(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](IResource.md) -- [返回模块目录](../Asset.md) +- [IResource](IResource.md) diff --git a/docs/api/XCEngine/Core/Asset/IResource/GetPath.md b/docs/api/XCEngine/Core/Asset/IResource/GetPath.md index 926ed162..6bb83cf2 100644 --- a/docs/api/XCEngine/Core/Asset/IResource/GetPath.md +++ b/docs/api/XCEngine/Core/Asset/IResource/GetPath.md @@ -1,30 +1,25 @@ # IResource::GetPath -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/IResource.h` + +## 签名 ```cpp virtual const Containers::String& GetPath() const = 0; ``` -该方法声明于 `XCEngine/Core/Asset/IResource.h`，当前页面用于固定 `IResource` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `const Containers::String&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::IResource object; - // 根据上下文补齐参数后调用 IResource::GetPath(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](IResource.md) -- [返回模块目录](../Asset.md) +- [IResource](IResource.md) diff --git a/docs/api/XCEngine/Core/Asset/IResource/GetType.md b/docs/api/XCEngine/Core/Asset/IResource/GetType.md index 2eb7e7d4..b32b5c55 100644 --- a/docs/api/XCEngine/Core/Asset/IResource/GetType.md +++ b/docs/api/XCEngine/Core/Asset/IResource/GetType.md @@ -1,30 +1,25 @@ # IResource::GetType -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/IResource.h` + +## 签名 ```cpp virtual ResourceType GetType() const = 0; ``` -该方法声明于 `XCEngine/Core/Asset/IResource.h`，当前页面用于固定 `IResource` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `ResourceType` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::IResource object; - // 根据上下文补齐参数后调用 IResource::GetType(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](IResource.md) -- [返回模块目录](../Asset.md) +- [IResource](IResource.md) diff --git a/docs/api/XCEngine/Core/Asset/IResource/Initialize.md b/docs/api/XCEngine/Core/Asset/IResource/Initialize.md index 668b05dc..486fb893 100644 --- a/docs/api/XCEngine/Core/Asset/IResource/Initialize.md +++ b/docs/api/XCEngine/Core/Asset/IResource/Initialize.md @@ -1,31 +1,25 @@ # IResource::Initialize -初始化内部状态。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/IResource.h` + +## 签名 ```cpp void Initialize(const ConstructParams& params); ``` -该方法声明于 `XCEngine/Core/Asset/IResource.h`，当前页面用于固定 `IResource` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `params` - 参数语义详见头文件声明。 +执行该公开方法对应的当前实现。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::IResource object; - // 根据上下文补齐参数后调用 IResource::Initialize(...)。 - (void)object; -} -``` +- 会更新 `m_name`、`m_path`、`m_guid`、`m_memorySize`。 ## 相关文档 -- [返回类总览](IResource.md) -- [返回模块目录](../Asset.md) +- [IResource](IResource.md) diff --git a/docs/api/XCEngine/Core/Asset/IResource/IsValid.md b/docs/api/XCEngine/Core/Asset/IResource/IsValid.md index 0ae42685..ac6b05b0 100644 --- a/docs/api/XCEngine/Core/Asset/IResource/IsValid.md +++ b/docs/api/XCEngine/Core/Asset/IResource/IsValid.md @@ -1,30 +1,25 @@ # IResource::IsValid -查询当前状态。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/IResource.h` + +## 签名 ```cpp virtual bool IsValid() const = 0; ``` -该方法声明于 `XCEngine/Core/Asset/IResource.h`，当前页面用于固定 `IResource` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::IResource object; - // 根据上下文补齐参数后调用 IResource::IsValid(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](IResource.md) -- [返回模块目录](../Asset.md) +- [IResource](IResource.md) diff --git a/docs/api/XCEngine/Core/Asset/IResource/Release.md b/docs/api/XCEngine/Core/Asset/IResource/Release.md index 06caf96c..06ec642b 100644 --- a/docs/api/XCEngine/Core/Asset/IResource/Release.md +++ b/docs/api/XCEngine/Core/Asset/IResource/Release.md @@ -1,30 +1,25 @@ # IResource::Release -释放引用或底层资源。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/IResource.h` + +## 签名 ```cpp virtual void Release() = 0; ``` -该方法声明于 `XCEngine/Core/Asset/IResource.h`，当前页面用于固定 `IResource` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::IResource object; - // 根据上下文补齐参数后调用 IResource::Release(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](IResource.md) -- [返回模块目录](../Asset.md) +- [IResource](IResource.md) diff --git a/docs/api/XCEngine/Core/Asset/IResource/SetInvalid.md b/docs/api/XCEngine/Core/Asset/IResource/SetInvalid.md index 5b1dc797..94e520d7 100644 --- a/docs/api/XCEngine/Core/Asset/IResource/SetInvalid.md +++ b/docs/api/XCEngine/Core/Asset/IResource/SetInvalid.md @@ -1,30 +1,25 @@ # IResource::SetInvalid -设置相关状态或配置。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/IResource.h` + +## 签名 ```cpp void SetInvalid(); ``` -该方法声明于 `XCEngine/Core/Asset/IResource.h`，当前页面用于固定 `IResource` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_isValid`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::IResource object; - // 根据上下文补齐参数后调用 IResource::SetInvalid(...)。 - (void)object; -} -``` +- 会更新 `m_isValid`。 ## 相关文档 -- [返回类总览](IResource.md) -- [返回模块目录](../Asset.md) +- [IResource](IResource.md) diff --git a/docs/api/XCEngine/Core/Asset/ImportSettings/Clone.md b/docs/api/XCEngine/Core/Asset/ImportSettings/Clone.md index dae9b913..baf1c10c 100644 --- a/docs/api/XCEngine/Core/Asset/ImportSettings/Clone.md +++ b/docs/api/XCEngine/Core/Asset/ImportSettings/Clone.md @@ -1,30 +1,25 @@ # ImportSettings::Clone -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/ImportSettings.h` + +## 签名 ```cpp virtual Core::UniqueRef Clone() const = 0; ``` -该方法声明于 `XCEngine/Core/Asset/ImportSettings.h`，当前页面用于固定 `ImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `Core::UniqueRef` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::ImportSettings object; - // 根据上下文补齐参数后调用 ImportSettings::Clone(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](ImportSettings.md) -- [返回模块目录](../Asset.md) +- [ImportSettings](ImportSettings.md) diff --git a/docs/api/XCEngine/Core/Asset/ImportSettings/Destructor.md b/docs/api/XCEngine/Core/Asset/ImportSettings/Destructor.md index 58060879..3072889f 100644 --- a/docs/api/XCEngine/Core/Asset/ImportSettings/Destructor.md +++ b/docs/api/XCEngine/Core/Asset/ImportSettings/Destructor.md @@ -1,29 +1,25 @@ # ImportSettings::~ImportSettings() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/ImportSettings.h` + +## 签名 ```cpp virtual ~ImportSettings() = default; ``` -该方法声明于 `XCEngine/Core/Asset/ImportSettings.h`，当前页面用于固定 `ImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +销毁 `ImportSettings` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::ImportSettings object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 当前为默认析构实现。 ## 相关文档 -- [返回类总览](ImportSettings.md) -- [返回模块目录](../Asset.md) +- [ImportSettings](ImportSettings.md) diff --git a/docs/api/XCEngine/Core/Asset/ImportSettings/LoadFromJSON.md b/docs/api/XCEngine/Core/Asset/ImportSettings/LoadFromJSON.md index deadcce5..db456539 100644 --- a/docs/api/XCEngine/Core/Asset/ImportSettings/LoadFromJSON.md +++ b/docs/api/XCEngine/Core/Asset/ImportSettings/LoadFromJSON.md @@ -1,31 +1,25 @@ # ImportSettings::LoadFromJSON -加载资源或数据。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/ImportSettings.h` + +## 签名 ```cpp virtual bool LoadFromJSON(const Containers::String& json); ``` -该方法声明于 `XCEngine/Core/Asset/ImportSettings.h`，当前页面用于固定 `ImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `json` - 参数语义详见头文件声明。 +固定返回 `false`。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::ImportSettings object; - // 根据上下文补齐参数后调用 ImportSettings::LoadFromJSON(...)。 - (void)object; -} -``` +- 固定返回 `false`。 ## 相关文档 -- [返回类总览](ImportSettings.md) -- [返回模块目录](../Asset.md) +- [ImportSettings](ImportSettings.md) diff --git a/docs/api/XCEngine/Core/Asset/ImportSettings/SaveToJSON.md b/docs/api/XCEngine/Core/Asset/ImportSettings/SaveToJSON.md index 85ed8793..5081294b 100644 --- a/docs/api/XCEngine/Core/Asset/ImportSettings/SaveToJSON.md +++ b/docs/api/XCEngine/Core/Asset/ImportSettings/SaveToJSON.md @@ -1,30 +1,25 @@ # ImportSettings::SaveToJSON -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/ImportSettings.h` + +## 签名 ```cpp virtual Containers::String SaveToJSON() const; ``` -该方法声明于 `XCEngine/Core/Asset/ImportSettings.h`，当前页面用于固定 `ImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `SaveToJSON` 对应的公开操作。 -**返回：** `Containers::String` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::ImportSettings object; - // 根据上下文补齐参数后调用 ImportSettings::SaveToJSON(...)。 - (void)object; -} -``` +- 执行 `SaveToJSON` 对应的公开操作。 ## 相关文档 -- [返回类总览](ImportSettings.md) -- [返回模块目录](../Asset.md) +- [ImportSettings](ImportSettings.md) diff --git a/docs/api/XCEngine/Core/Asset/ResourceCache/Add.md b/docs/api/XCEngine/Core/Asset/ResourceCache/Add.md index f9002c28..41b118f0 100644 --- a/docs/api/XCEngine/Core/Asset/ResourceCache/Add.md +++ b/docs/api/XCEngine/Core/Asset/ResourceCache/Add.md @@ -1,32 +1,43 @@ # ResourceCache::Add -添加元素或建立关联。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/ResourceCache.h` + +## 签名 ```cpp void Add(ResourceGUID guid, IResource* resource); ``` -该方法声明于 `XCEngine/Core/Asset/ResourceCache.h`，当前页面用于固定 `ResourceCache` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `guid` - 参数语义详见头文件声明。 -- `resource` - 参数语义详见头文件声明。 +向缓存中插入一个新的资源条目。 -**返回：** `void` - 无返回值。 +## 当前实现行为 -**示例：** +- 方法开始时会锁住 `m_mutex`。 +- 如果 `m_cache` 已包含该 `guid`，会直接返回，不更新旧条目。 +- 否则会构造 `CacheEntry(resource, resource->GetMemorySize())`，并： + - 以参数 `guid` 作为 map key 插入 `m_cache` + - 把同一个 `guid` 追加到 `m_lruOrder` + - 把条目内存大小累加到 `m_memoryUsage` -```cpp -#include +## 参数语义 -void Example() { - XCEngine::Resources::ResourceCache object; - // 根据上下文补齐参数后调用 ResourceCache::Add(...)。 - (void)object; -} -``` +- `guid` - 作为缓存键使用，同时写入 `m_lruOrder`。 +- `resource` - 被缓存的裸 `IResource*`。 + +## 当前边界 + +- 当前不检查 `resource == nullptr`。 +- 当前不验证参数 `guid` 是否与 `resource->GetGUID()` 一致；如果调用方传错，两者可能出现偏离。 +- 当前不会在 `Add()` 内部自动执行预算检查或淘汰；超预算处理要靠外部显式调用 [OnMemoryPressure](OnMemoryPressure.md)。 ## 相关文档 -- [返回类总览](ResourceCache.md) -- [返回模块目录](../Asset.md) +- [ResourceCache](ResourceCache.md) +- [Find](Find.md) +- [OnMemoryPressure](OnMemoryPressure.md) diff --git a/docs/api/XCEngine/Core/Asset/ResourceCache/Clear.md b/docs/api/XCEngine/Core/Asset/ResourceCache/Clear.md index a1167a05..658b02c4 100644 --- a/docs/api/XCEngine/Core/Asset/ResourceCache/Clear.md +++ b/docs/api/XCEngine/Core/Asset/ResourceCache/Clear.md @@ -1,30 +1,35 @@ # ResourceCache::Clear -清空内部数据。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/ResourceCache.h` + +## 签名 ```cpp void Clear(); ``` -该方法声明于 `XCEngine/Core/Asset/ResourceCache.h`，当前页面用于固定 `ResourceCache` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +直接清空缓存记录和统计值。 -**返回：** `void` - 无返回值。 +## 当前实现行为 -**示例：** +- 方法会锁住 `m_mutex`。 +- 当前会直接执行： + - `m_cache.Clear()` + - `m_lruOrder.Clear()` + - `m_memoryUsage = 0` -```cpp -#include +## 当前边界 -void Example() { - XCEngine::Resources::ResourceCache object; - // 根据上下文补齐参数后调用 ResourceCache::Clear(...)。 - (void)object; -} -``` +- 它不会调用 `resource->Release()`。 +- 如果外部系统仍保留这些资源对象指针，`Clear()` 不会替它们做任何生命周期收尾。 ## 相关文档 -- [返回类总览](ResourceCache.md) -- [返回模块目录](../Asset.md) +- [ResourceCache](ResourceCache.md) +- [Flush](Flush.md) diff --git a/docs/api/XCEngine/Core/Asset/ResourceCache/Constructor.md b/docs/api/XCEngine/Core/Asset/ResourceCache/Constructor.md index 3aa2b7d3..4929649b 100644 --- a/docs/api/XCEngine/Core/Asset/ResourceCache/Constructor.md +++ b/docs/api/XCEngine/Core/Asset/ResourceCache/Constructor.md @@ -1,28 +1,30 @@ -# ResourceCache::ResourceCache() +# ResourceCache::ResourceCache -构造对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/ResourceCache.h` + +## 签名 ```cpp ResourceCache(); ``` -该方法声明于 `XCEngine/Core/Asset/ResourceCache.h`，当前页面用于固定 `ResourceCache` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +构造一个空的资源缓存对象。 -**返回：** `void` - 无返回值。 +## 当前实现行为 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::ResourceCache object; -} -``` +- 构造函数在 `.cpp` 中是 `= default`。 +- `m_cache` 和 `m_lruOrder` 初始为空。 +- `m_memoryUsage` 初始为 `0`。 +- `m_memoryBudget` 通过成员默认值初始化为 `512 * 1024 * 1024` 字节。 +- 不会自动接入 [ResourceManager](../ResourceManager/ResourceManager.md)，也不会主动触发任何资源释放或预热。 ## 相关文档 -- [返回类总览](ResourceCache.md) -- [返回模块目录](../Asset.md) +- [ResourceCache](ResourceCache.md) +- [Destructor](Destructor.md) diff --git a/docs/api/XCEngine/Core/Asset/ResourceCache/Destructor.md b/docs/api/XCEngine/Core/Asset/ResourceCache/Destructor.md index 44d39373..60bb4d4f 100644 --- a/docs/api/XCEngine/Core/Asset/ResourceCache/Destructor.md +++ b/docs/api/XCEngine/Core/Asset/ResourceCache/Destructor.md @@ -1,29 +1,31 @@ -# ResourceCache::~ResourceCache() +# ResourceCache::~ResourceCache -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/ResourceCache.h` + +## 签名 ```cpp ~ResourceCache(); ``` -该方法声明于 `XCEngine/Core/Asset/ResourceCache.h`，当前页面用于固定 `ResourceCache` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +销毁缓存对象本身。 -**返回：** `void` - 无返回值。 +## 当前实现行为 -**示例：** +- 析构函数在 `.cpp` 中同样是 `= default`。 +- 它不会自动调用 [Flush](Flush.md) 或 [Clear](Clear.md)。 +- 如果缓存里仍保存着 `IResource*`，析构本身不会逐项执行 `resource->Release()`。 -```cpp -#include - -void Example() { - XCEngine::Resources::ResourceCache object; - // 对象离开作用域时会自动触发析构。 -} -``` +这意味着 `ResourceCache` 目前不是“析构即托管清理”的安全容器，它更像一层需要外部生命周期约束的策略对象。 ## 相关文档 -- [返回类总览](ResourceCache.md) -- [返回模块目录](../Asset.md) +- [ResourceCache](ResourceCache.md) +- [Flush](Flush.md) +- [Clear](Clear.md) diff --git a/docs/api/XCEngine/Core/Asset/ResourceCache/Find.md b/docs/api/XCEngine/Core/Asset/ResourceCache/Find.md index 8faba05b..25a53975 100644 --- a/docs/api/XCEngine/Core/Asset/ResourceCache/Find.md +++ b/docs/api/XCEngine/Core/Asset/ResourceCache/Find.md @@ -1,31 +1,39 @@ # ResourceCache::Find -查找并返回匹配对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/ResourceCache.h` + +## 签名 ```cpp IResource* Find(ResourceGUID guid) const; ``` -该方法声明于 `XCEngine/Core/Asset/ResourceCache.h`，当前页面用于固定 `ResourceCache` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `guid` - 参数语义详见头文件声明。 +按 GUID 查找当前缓存里的资源指针。 -**返回：** `IResource*` - 返回值语义详见头文件声明。 +## 当前实现行为 -**示例：** +- 方法会锁住 `m_mutex`。 +- 若 `m_cache.Find(guid)` 命中，则返回该条目的 `resource`。 +- 若未命中，则返回 `nullptr`。 -```cpp -#include +## 返回值 -void Example() { - XCEngine::Resources::ResourceCache object; - // 根据上下文补齐参数后调用 ResourceCache::Find(...)。 - (void)object; -} -``` +- 命中时返回缓存中的裸 `IResource*`。 +- 未命中时返回 `nullptr`。 + +## 当前边界 + +- 当前不会自动调用 [Touch](Touch.md)，查找不会改变热度统计或淘汰顺序。 +- 返回的是非拥有型裸指针，生命周期仍由外部系统约束。 ## 相关文档 -- [返回类总览](ResourceCache.md) -- [返回模块目录](../Asset.md) +- [ResourceCache](ResourceCache.md) +- [Touch](Touch.md) +- [GetLRUList](GetLRUList.md) diff --git a/docs/api/XCEngine/Core/Asset/ResourceCache/Flush.md b/docs/api/XCEngine/Core/Asset/ResourceCache/Flush.md index 67b15e7b..1263317b 100644 --- a/docs/api/XCEngine/Core/Asset/ResourceCache/Flush.md +++ b/docs/api/XCEngine/Core/Asset/ResourceCache/Flush.md @@ -1,30 +1,36 @@ # ResourceCache::Flush -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/ResourceCache.h` + +## 签名 ```cpp void Flush(); ``` -该方法声明于 `XCEngine/Core/Asset/ResourceCache.h`，当前页面用于固定 `ResourceCache` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +清空当前缓存状态。 -**返回：** `void` - 无返回值。 +## 当前实现行为 -**示例：** +- 方法会锁住 `m_mutex`。 +- 源码里保留了“逐项释放资源”的注释，但实际迭代逻辑没有实现。 +- 当前真正执行的是： + - `m_cache.Clear()` + - `m_lruOrder.Clear()` + - `m_memoryUsage = 0` -```cpp -#include +## 当前边界 -void Example() { - XCEngine::Resources::ResourceCache object; - // 根据上下文补齐参数后调用 ResourceCache::Flush(...)。 - (void)object; -} -``` +- 当前不会逐项调用 `resource->Release()`。 +- 因此它和 [Clear](Clear.md) 在实际效果上几乎等价，只是 `Flush()` 多了一段尚未落地的注释意图。 ## 相关文档 -- [返回类总览](ResourceCache.md) -- [返回模块目录](../Asset.md) +- [ResourceCache](ResourceCache.md) +- [Clear](Clear.md) diff --git a/docs/api/XCEngine/Core/Asset/ResourceCache/GetLRUList.md b/docs/api/XCEngine/Core/Asset/ResourceCache/GetLRUList.md index 365710b3..3677cc14 100644 --- a/docs/api/XCEngine/Core/Asset/ResourceCache/GetLRUList.md +++ b/docs/api/XCEngine/Core/Asset/ResourceCache/GetLRUList.md @@ -1,31 +1,38 @@ # ResourceCache::GetLRUList -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/ResourceCache.h` + +## 签名 ```cpp Containers::Array GetLRUList(size_t count) const; ``` -该方法声明于 `XCEngine/Core/Asset/ResourceCache.h`，当前页面用于固定 `ResourceCache` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `count` - 参数语义详见头文件声明。 +返回当前内部顺序数组中的前若干个 GUID。 -**返回：** `Containers::Array` - 返回值语义详见头文件声明。 +## 当前实现行为 -**示例：** +- 方法会锁住 `m_mutex`。 +- 先计算 `n = min(count, m_lruOrder.Size())`。 +- 然后按 `m_lruOrder[0]` 到 `m_lruOrder[n - 1]` 的顺序复制到新数组并返回。 -```cpp -#include +## 返回值 -void Example() { - XCEngine::Resources::ResourceCache object; - // 根据上下文补齐参数后调用 ResourceCache::GetLRUList(...)。 - (void)object; -} -``` +- 一份新的 `Containers::Array` 拷贝。 + +## 当前边界 + +- 这个列表不是根据 `lastAccessTime` 现场排序出来的结果，只是当前内部数组的前缀视图。 +- 因为 [Touch](Touch.md) 不会重排顺序，而 [OnMemoryPressure](OnMemoryPressure.md) 是从数组尾部淘汰，所以这里的“LRU”命名在当前实现里带有明显历史遗留色彩。 ## 相关文档 -- [返回类总览](ResourceCache.md) -- [返回模块目录](../Asset.md) +- [ResourceCache](ResourceCache.md) +- [Touch](Touch.md) +- [OnMemoryPressure](OnMemoryPressure.md) diff --git a/docs/api/XCEngine/Core/Asset/ResourceCache/GetMemoryBudget.md b/docs/api/XCEngine/Core/Asset/ResourceCache/GetMemoryBudget.md index 1bd60878..532edfec 100644 --- a/docs/api/XCEngine/Core/Asset/ResourceCache/GetMemoryBudget.md +++ b/docs/api/XCEngine/Core/Asset/ResourceCache/GetMemoryBudget.md @@ -1,30 +1,35 @@ # ResourceCache::GetMemoryBudget -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/ResourceCache.h` + +## 签名 ```cpp size_t GetMemoryBudget() const; ``` -该方法声明于 `XCEngine/Core/Asset/ResourceCache.h`，当前页面用于固定 `ResourceCache` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +读取当前缓存预算。 -**返回：** `size_t` - 返回值语义详见头文件声明。 +## 当前实现行为 -**示例：** +- 这是头文件里的内联访问器，直接返回 `m_memoryBudget`。 +- 当前访问器本身不加锁。 -```cpp -#include +## 返回值 -void Example() { - XCEngine::Resources::ResourceCache object; - // 根据上下文补齐参数后调用 ResourceCache::GetMemoryBudget(...)。 - (void)object; -} -``` +- 当前预算值，单位是字节。 + +## 当前边界 + +- 如果与 [SetMemoryBudget](SetMemoryBudget.md) 并发交错，调用方需要自己保证同步。 ## 相关文档 -- [返回类总览](ResourceCache.md) -- [返回模块目录](../Asset.md) +- [ResourceCache](ResourceCache.md) +- [SetMemoryBudget](SetMemoryBudget.md) diff --git a/docs/api/XCEngine/Core/Asset/ResourceCache/GetMemoryUsage.md b/docs/api/XCEngine/Core/Asset/ResourceCache/GetMemoryUsage.md index 4664e538..f0fc8caa 100644 --- a/docs/api/XCEngine/Core/Asset/ResourceCache/GetMemoryUsage.md +++ b/docs/api/XCEngine/Core/Asset/ResourceCache/GetMemoryUsage.md @@ -1,30 +1,37 @@ # ResourceCache::GetMemoryUsage -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/ResourceCache.h` + +## 签名 ```cpp size_t GetMemoryUsage() const; ``` -该方法声明于 `XCEngine/Core/Asset/ResourceCache.h`，当前页面用于固定 `ResourceCache` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +读取当前记录的缓存内存占用。 -**返回：** `size_t` - 返回值语义详见头文件声明。 +## 当前实现行为 -**示例：** +- 这是头文件中的内联访问器，直接返回 `m_memoryUsage`。 +- 当前访问器本身不加锁。 -```cpp -#include +## 返回值 -void Example() { - XCEngine::Resources::ResourceCache object; - // 根据上下文补齐参数后调用 ResourceCache::GetMemoryUsage(...)。 - (void)object; -} -``` +- 当前缓存条目累计的 `memorySize` 总和。 + +## 当前边界 + +- 这个统计值依赖 [Add](Add.md)、[Remove](Remove.md)、[OnMemoryPressure](OnMemoryPressure.md)、[Flush](Flush.md)、[Clear](Clear.md) 的维护。 +- 当前值不保证和 [ResourceManager](../ResourceManager/ResourceManager.md) 的 `m_memoryUsage` 始终严格一致。 ## 相关文档 -- [返回类总览](ResourceCache.md) -- [返回模块目录](../Asset.md) +- [ResourceCache](ResourceCache.md) +- [GetSize](GetSize.md) +- [OnMemoryPressure](OnMemoryPressure.md) diff --git a/docs/api/XCEngine/Core/Asset/ResourceCache/GetSize.md b/docs/api/XCEngine/Core/Asset/ResourceCache/GetSize.md index 685850b0..0a33172e 100644 --- a/docs/api/XCEngine/Core/Asset/ResourceCache/GetSize.md +++ b/docs/api/XCEngine/Core/Asset/ResourceCache/GetSize.md @@ -1,30 +1,35 @@ # ResourceCache::GetSize -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/ResourceCache.h` + +## 签名 ```cpp size_t GetSize() const; ``` -该方法声明于 `XCEngine/Core/Asset/ResourceCache.h`，当前页面用于固定 `ResourceCache` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回当前缓存条目数量。 -**返回：** `size_t` - 返回值语义详见头文件声明。 +## 当前实现行为 -**示例：** +- 这是头文件中的内联访问器，直接返回 `m_cache.Size()`。 +- 当前访问器本身不加锁。 -```cpp -#include +## 返回值 -void Example() { - XCEngine::Resources::ResourceCache object; - // 根据上下文补齐参数后调用 ResourceCache::GetSize(...)。 - (void)object; -} -``` +- 当前 `m_cache` 中的条目数。 + +## 当前边界 + +- 它读取的是 map 条目数量，不代表 `m_lruOrder` 中一定没有历史残留；两者的一致性依赖其它方法正确维护。 ## 相关文档 -- [返回类总览](ResourceCache.md) -- [返回模块目录](../Asset.md) +- [ResourceCache](ResourceCache.md) +- [GetMemoryUsage](GetMemoryUsage.md) diff --git a/docs/api/XCEngine/Core/Asset/ResourceCache/OnMemoryPressure.md b/docs/api/XCEngine/Core/Asset/ResourceCache/OnMemoryPressure.md index b80d5229..b655c4d5 100644 --- a/docs/api/XCEngine/Core/Asset/ResourceCache/OnMemoryPressure.md +++ b/docs/api/XCEngine/Core/Asset/ResourceCache/OnMemoryPressure.md @@ -1,31 +1,56 @@ # ResourceCache::OnMemoryPressure -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/ResourceCache.h` + +## 签名 ```cpp void OnMemoryPressure(size_t requiredBytes); ``` -该方法声明于 `XCEngine/Core/Asset/ResourceCache.h`，当前页面用于固定 `ResourceCache` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `requiredBytes` - 参数语义详见头文件声明。 +在调用方预计还需要额外内存时，尝试执行缓存淘汰。 -**返回：** `void` - 无返回值。 +## 当前实现行为 -**示例：** +- 方法会锁住 `m_mutex`。 +- 如果 `m_memoryUsage + requiredBytes <= m_memoryBudget`，直接返回。 +- 否则会计算： ```cpp -#include - -void Example() { - XCEngine::Resources::ResourceCache object; - // 根据上下文补齐参数后调用 ResourceCache::OnMemoryPressure(...)。 - (void)object; -} +size_t targetRelease = (m_memoryUsage + requiredBytes) - m_memoryBudget; ``` +- 然后调用内部 `Evict(targetRelease)`。 + +## 内部淘汰策略 + +`Evict()` 当前的实际行为是： + +- 从 `m_lruOrder` 尾部反复弹出 GUID +- 命中条目后： + - 从 `m_memoryUsage` 扣减其 `memorySize` + - 调用 `it->resource->Release()` + - 从 `m_cache` 擦除该条目 +- 直到累计释放字节数达到目标或 `m_lruOrder` 为空 + +## 参数 + +- `requiredBytes` - 调用方希望额外腾出的字节数。 + +## 当前边界 + +- 当前淘汰顺序并不是真实 LRU，因为 [Touch](Touch.md) 不会重排 `m_lruOrder`。 +- 它不会检查资源当前是否仍被 [ResourceHandle](../ResourceHandle/ResourceHandle.md) 持有。 +- 如果 `m_lruOrder` 里能释放的资源不足，函数返回后总占用仍可能高于预算。 + ## 相关文档 -- [返回类总览](ResourceCache.md) -- [返回模块目录](../Asset.md) +- [ResourceCache](ResourceCache.md) +- [Touch](Touch.md) +- [GetLRUList](GetLRUList.md) diff --git a/docs/api/XCEngine/Core/Asset/ResourceCache/OnZeroRefCount.md b/docs/api/XCEngine/Core/Asset/ResourceCache/OnZeroRefCount.md index da214875..02c11b76 100644 --- a/docs/api/XCEngine/Core/Asset/ResourceCache/OnZeroRefCount.md +++ b/docs/api/XCEngine/Core/Asset/ResourceCache/OnZeroRefCount.md @@ -1,31 +1,33 @@ # ResourceCache::OnZeroRefCount -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/ResourceCache.h` + +## 签名 ```cpp void OnZeroRefCount(ResourceGUID guid); ``` -该方法声明于 `XCEngine/Core/Asset/ResourceCache.h`，当前页面用于固定 `ResourceCache` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `guid` - 参数语义详见头文件声明。 +为“引用数归零时的缓存策略”预留入口。 -**返回：** `void` - 无返回值。 +## 当前实现行为 -**示例：** +- 当前函数体为空。 +- 传入的 `guid` 没有被使用。 -```cpp -#include +## 当前边界 -void Example() { - XCEngine::Resources::ResourceCache object; - // 根据上下文补齐参数后调用 ResourceCache::OnZeroRefCount(...)。 - (void)object; -} -``` +- [ResourceManager::Release](../ResourceManager/Release.md) 在引用计数归零时会调用这里，但目前不会触发任何卸载、降级或回收到缓存尾部的动作。 +- 因此“最后一个句柄释放后自动进入可淘汰状态”目前并不是现状保证。 ## 相关文档 -- [返回类总览](ResourceCache.md) -- [返回模块目录](../Asset.md) +- [ResourceCache](ResourceCache.md) +- [ResourceManager](../ResourceManager/ResourceManager.md) +- [ResourceHandle](../ResourceHandle/ResourceHandle.md) diff --git a/docs/api/XCEngine/Core/Asset/ResourceCache/Remove.md b/docs/api/XCEngine/Core/Asset/ResourceCache/Remove.md index 64c5cdb2..2c960f1b 100644 --- a/docs/api/XCEngine/Core/Asset/ResourceCache/Remove.md +++ b/docs/api/XCEngine/Core/Asset/ResourceCache/Remove.md @@ -1,31 +1,41 @@ # ResourceCache::Remove -移除元素或解除关联。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/ResourceCache.h` + +## 签名 ```cpp void Remove(ResourceGUID guid); ``` -该方法声明于 `XCEngine/Core/Asset/ResourceCache.h`，当前页面用于固定 `ResourceCache` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `guid` - 参数语义详见头文件声明。 +按 GUID 从缓存中移除一个条目。 -**返回：** `void` - 无返回值。 +## 当前实现行为 -**示例：** +- 方法会先锁住 `m_mutex`。 +- 找到条目后会： + - 从 `m_memoryUsage` 中减去该条目的 `memorySize` + - 从 `m_cache` 擦除该键 + - 重新构建一个新的 `m_lruOrder`，把目标 `guid` 过滤掉 +- 如果条目不存在，则什么也不做。 -```cpp -#include +## 参数 -void Example() { - XCEngine::Resources::ResourceCache object; - // 根据上下文补齐参数后调用 ResourceCache::Remove(...)。 - (void)object; -} -``` +- `guid` - 要移除的缓存键。 + +## 当前边界 + +- 当前只移除缓存记录，不会调用 `resource->Release()`。 +- `m_lruOrder` 的更新方式是整表重建，复杂度较高，但实现直接。 ## 相关文档 -- [返回类总览](ResourceCache.md) -- [返回模块目录](../Asset.md) +- [ResourceCache](ResourceCache.md) +- [Add](Add.md) +- [Flush](Flush.md) diff --git a/docs/api/XCEngine/Core/Asset/ResourceCache/ResourceCache.md b/docs/api/XCEngine/Core/Asset/ResourceCache/ResourceCache.md index 0f5dc845..002571d7 100644 --- a/docs/api/XCEngine/Core/Asset/ResourceCache/ResourceCache.md +++ b/docs/api/XCEngine/Core/Asset/ResourceCache/ResourceCache.md @@ -36,6 +36,7 @@ ### 添加与查找 - `Add(guid, resource)` 在键不存在时插入条目，记录内存大小，并把 GUID 追加到 `m_lruOrder`。 +- `Add()` 当前不检查 `resource == nullptr`，也不校验参数 `guid` 与 `resource->GetGUID()` 是否一致。 - `Find(guid)` 只做查找，不会自动调用 `Touch()`。 - `Remove(guid)` 会删除缓存项，并通过重建数组的方式从 `m_lruOrder` 中移除该 GUID。 @@ -58,6 +59,11 @@ 这说明当前版本的淘汰行为更像“按数组尾部顺序删”，不是成熟的最近最少使用缓存。 +### 清理语义 + +- `Flush()` 和 `Clear()` 当前都会直接清空容器并把 `m_memoryUsage` 置零。 +- `Flush()` 虽然保留了“逐项释放资源”的注释，但实际没有执行这一步。 + ## 设计取向 把缓存做成独立对象是合理的。它让资源管理器有机会只负责“谁被加载了”，而把“什么时候因为内存压力淘汰”下沉给缓存层。对商业引擎来说，这样的分层有两个好处： @@ -70,6 +76,8 @@ ## 线程语义 - `Add()`、`Remove()`、`Find()`、`Touch()`、`OnMemoryPressure()`、`Flush()`、`Clear()`、`GetLRUList()` 当前都使用 `m_mutex`。 +- `SetMemoryBudget()` 也会使用 `m_mutex`。 +- `GetSize()`、`GetMemoryUsage()`、`GetMemoryBudget()` 是头文件内联 getter，当前本身不加锁。 - 头文件里还有一个 `m_cacheMutex`，但当前 `.cpp` 实现并没有实际使用它。 - 资源对象本身的线程安全不由 `ResourceCache` 保证。 diff --git a/docs/api/XCEngine/Core/Asset/ResourceCache/SetMemoryBudget.md b/docs/api/XCEngine/Core/Asset/ResourceCache/SetMemoryBudget.md index c9abd8f0..af532fce 100644 --- a/docs/api/XCEngine/Core/Asset/ResourceCache/SetMemoryBudget.md +++ b/docs/api/XCEngine/Core/Asset/ResourceCache/SetMemoryBudget.md @@ -1,31 +1,37 @@ # ResourceCache::SetMemoryBudget -设置相关状态或配置。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/ResourceCache.h` + +## 签名 ```cpp void SetMemoryBudget(size_t bytes); ``` -该方法声明于 `XCEngine/Core/Asset/ResourceCache.h`，当前页面用于固定 `ResourceCache` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `bytes` - 参数语义详见头文件声明。 +设置缓存预算上限。 -**返回：** `void` - 无返回值。 +## 当前实现行为 -**示例：** +- 方法会锁住 `m_mutex`。 +- 当前只做一件事：把 `m_memoryBudget` 赋值为 `bytes`。 -```cpp -#include +## 参数 -void Example() { - XCEngine::Resources::ResourceCache object; - // 根据上下文补齐参数后调用 ResourceCache::SetMemoryBudget(...)。 - (void)object; -} -``` +- `bytes` - 新的预算值，单位是字节。 + +## 当前边界 + +- 设置新预算后不会立即执行淘汰。 +- 如果新预算低于当前已占用内存，缓存仍会保持现状，直到后续显式调用 [OnMemoryPressure](OnMemoryPressure.md)。 ## 相关文档 -- [返回类总览](ResourceCache.md) -- [返回模块目录](../Asset.md) +- [ResourceCache](ResourceCache.md) +- [GetMemoryBudget](GetMemoryBudget.md) +- [OnMemoryPressure](OnMemoryPressure.md) diff --git a/docs/api/XCEngine/Core/Asset/ResourceCache/Touch.md b/docs/api/XCEngine/Core/Asset/ResourceCache/Touch.md index 39ea0835..891bc2e7 100644 --- a/docs/api/XCEngine/Core/Asset/ResourceCache/Touch.md +++ b/docs/api/XCEngine/Core/Asset/ResourceCache/Touch.md @@ -1,31 +1,36 @@ # ResourceCache::Touch -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/ResourceCache.h` + +## 签名 ```cpp void Touch(ResourceGUID guid); ``` -该方法声明于 `XCEngine/Core/Asset/ResourceCache.h`，当前页面用于固定 `ResourceCache` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `guid` - 参数语义详见头文件声明。 +更新某个缓存条目的访问统计。 -**返回：** `void` - 无返回值。 +## 当前实现行为 -**示例：** +- 方法会锁住 `m_mutex`。 +- 命中条目时会： + - 把 `lastAccessTime` 更新为 `CacheEntry::GetCurrentTick()` + - 把 `accessCount` 加一 +- 未命中时直接返回。 -```cpp -#include +## 当前边界 -void Example() { - XCEngine::Resources::ResourceCache object; - // 根据上下文补齐参数后调用 ResourceCache::Touch(...)。 - (void)object; -} -``` +- 它不会重排 `m_lruOrder`。 +- 因此它虽然更新了“最近访问时间”，但不会真正改变 [OnMemoryPressure](OnMemoryPressure.md) 后续的淘汰顺序。 ## 相关文档 -- [返回类总览](ResourceCache.md) -- [返回模块目录](../Asset.md) +- [ResourceCache](ResourceCache.md) +- [Find](Find.md) +- [GetLRUList](GetLRUList.md) diff --git a/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/AddDependency.md b/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/AddDependency.md index d0b03ebb..d79a2f7a 100644 --- a/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/AddDependency.md +++ b/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/AddDependency.md @@ -1,32 +1,42 @@ # ResourceDependencyGraph::AddDependency -添加元素或建立关联。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/ResourceDependencyGraph.h` + +## 签名 ```cpp void AddDependency(ResourceGUID owner, ResourceGUID dependency); ``` -该方法声明于 `XCEngine/Core/Asset/ResourceDependencyGraph.h`，当前页面用于固定 `ResourceDependencyGraph` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `owner` - 参数语义详见头文件声明。 -- `dependency` - 参数语义详见头文件声明。 +建立一条 `owner -> dependency` 依赖边。 -**返回：** `void` - 无返回值。 +## 当前实现行为 -**示例：** +- 先分别查找 `owner` 和 `dependency` 两个节点。 +- 任何一方不存在时直接返回。 +- 若依赖边尚不存在，则： + - 把 `dependency` 追加到 `ownerNode->dependencies` + - 把 `owner` 追加到 `depNode->dependents` -```cpp -#include +## 参数 -void Example() { - XCEngine::Resources::ResourceDependencyGraph object; - // 根据上下文补齐参数后调用 ResourceDependencyGraph::AddDependency(...)。 - (void)object; -} -``` +- `owner` - 依赖别人资源的节点。 +- `dependency` - 被依赖的节点。 + +## 当前边界 + +- 当前不会自动创建缺失节点。 +- 当前只防止 `owner.dependencies` 中出现重复边。 +- 当前也不阻止 `owner == dependency` 的自依赖。 ## 相关文档 -- [返回类总览](ResourceDependencyGraph.md) -- [返回模块目录](../Asset.md) +- [ResourceDependencyGraph](ResourceDependencyGraph.md) +- [RemoveDependency](RemoveDependency.md) +- [GetDependencies](GetDependencies.md) diff --git a/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/AddNode.md b/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/AddNode.md index 9ea1da3a..7244989c 100644 --- a/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/AddNode.md +++ b/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/AddNode.md @@ -1,32 +1,37 @@ # ResourceDependencyGraph::AddNode -添加元素或建立关联。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/ResourceDependencyGraph.h` + +## 签名 ```cpp void AddNode(ResourceGUID guid, ResourceType type); ``` -该方法声明于 `XCEngine/Core/Asset/ResourceDependencyGraph.h`，当前页面用于固定 `ResourceDependencyGraph` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `guid` - 参数语义详见头文件声明。 -- `type` - 参数语义详见头文件声明。 +向依赖图中注册一个新的资源节点。 -**返回：** `void` - 无返回值。 +## 当前实现行为 -**示例：** +- 如果 `m_nodes` 已包含该 `guid`，会直接返回。 +- 否则会创建一个新的 `DependencyNode`，并写入： + - `guid` + - `type` + - `refCount = 0` +- `dependencies` 和 `dependents` 初始为空。 -```cpp -#include +## 参数 -void Example() { - XCEngine::Resources::ResourceDependencyGraph object; - // 根据上下文补齐参数后调用 ResourceDependencyGraph::AddNode(...)。 - (void)object; -} -``` +- `guid` - 节点标识。 +- `type` - 资源类型。 ## 相关文档 -- [返回类总览](ResourceDependencyGraph.md) -- [返回模块目录](../Asset.md) +- [ResourceDependencyGraph](ResourceDependencyGraph.md) +- [HasNode](HasNode.md) +- [RemoveNode](RemoveNode.md) diff --git a/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/Clear.md b/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/Clear.md index dde5a3d7..2c53aa8e 100644 --- a/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/Clear.md +++ b/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/Clear.md @@ -1,30 +1,31 @@ # ResourceDependencyGraph::Clear -清空内部数据。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/ResourceDependencyGraph.h` + +## 签名 ```cpp void Clear(); ``` -该方法声明于 `XCEngine/Core/Asset/ResourceDependencyGraph.h`，当前页面用于固定 `ResourceDependencyGraph` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +清空整张依赖图。 -**返回：** `void` - 无返回值。 +## 当前实现行为 -**示例：** +- 当前实现直接调用 `m_nodes.Clear()`。 -```cpp -#include +## 当前边界 -void Example() { - XCEngine::Resources::ResourceDependencyGraph object; - // 根据上下文补齐参数后调用 ResourceDependencyGraph::Clear(...)。 - (void)object; -} -``` +- 会一次性丢弃所有节点、依赖关系和图内引用计数。 +- 不会向外部资源系统同步卸载。 ## 相关文档 -- [返回类总览](ResourceDependencyGraph.md) -- [返回模块目录](../Asset.md) +- [ResourceDependencyGraph](ResourceDependencyGraph.md) +- [RemoveNode](RemoveNode.md) diff --git a/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/Constructor.md b/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/Constructor.md index 4405efa3..e6b5f5ae 100644 --- a/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/Constructor.md +++ b/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/Constructor.md @@ -1,28 +1,28 @@ -# ResourceDependencyGraph::ResourceDependencyGraph() +# ResourceDependencyGraph::ResourceDependencyGraph -构造对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/ResourceDependencyGraph.h` + +## 签名 ```cpp ResourceDependencyGraph(); ``` -该方法声明于 `XCEngine/Core/Asset/ResourceDependencyGraph.h`，当前页面用于固定 `ResourceDependencyGraph` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +构造一个空的资源依赖图。 -**返回：** `void` - 无返回值。 +## 当前实现行为 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::ResourceDependencyGraph object; -} -``` +- 构造函数在 `.cpp` 中是 `= default`。 +- `m_nodes` 初始为空。 +- 不会自动从 [ResourceManager](../ResourceManager/ResourceManager.md) 或任何资产数据库中导入现有依赖关系。 ## 相关文档 -- [返回类总览](ResourceDependencyGraph.md) -- [返回模块目录](../Asset.md) +- [ResourceDependencyGraph](ResourceDependencyGraph.md) +- [Destructor](Destructor.md) diff --git a/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/DecrementRefCount.md b/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/DecrementRefCount.md index f9e4fee7..8cd2bf67 100644 --- a/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/DecrementRefCount.md +++ b/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/DecrementRefCount.md @@ -1,31 +1,29 @@ # ResourceDependencyGraph::DecrementRefCount -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/ResourceDependencyGraph.h` + +## 签名 ```cpp void DecrementRefCount(ResourceGUID guid); ``` -该方法声明于 `XCEngine/Core/Asset/ResourceDependencyGraph.h`，当前页面用于固定 `ResourceDependencyGraph` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `guid` - 参数语义详见头文件声明。 +减少图节点自己的引用计数。 -**返回：** `void` - 无返回值。 +## 当前实现行为 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::ResourceDependencyGraph object; - // 根据上下文补齐参数后调用 ResourceDependencyGraph::DecrementRefCount(...)。 - (void)object; -} -``` +- 仅当节点存在且 `refCount > 0` 时才会递减。 +- 不会把计数减成负数。 +- 不会在归零时自动卸载节点。 ## 相关文档 -- [返回类总览](ResourceDependencyGraph.md) -- [返回模块目录](../Asset.md) +- [ResourceDependencyGraph](ResourceDependencyGraph.md) +- [IncrementRefCount](IncrementRefCount.md) +- [Unload](Unload.md) diff --git a/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/Destructor.md b/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/Destructor.md index 346a03e5..13ebef8f 100644 --- a/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/Destructor.md +++ b/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/Destructor.md @@ -1,29 +1,27 @@ -# ResourceDependencyGraph::~ResourceDependencyGraph() +# ResourceDependencyGraph::~ResourceDependencyGraph -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/ResourceDependencyGraph.h` + +## 签名 ```cpp ~ResourceDependencyGraph(); ``` -该方法声明于 `XCEngine/Core/Asset/ResourceDependencyGraph.h`，当前页面用于固定 `ResourceDependencyGraph` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +销毁依赖图对象本身。 -**返回：** `void` - 无返回值。 +## 当前实现行为 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::ResourceDependencyGraph object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 析构函数也是 `= default`。 +- 不会主动清理外部资源对象，也不会向 [ResourceManager](../ResourceManager/ResourceManager.md) 发送卸载通知。 ## 相关文档 -- [返回类总览](ResourceDependencyGraph.md) -- [返回模块目录](../Asset.md) +- [ResourceDependencyGraph](ResourceDependencyGraph.md) +- [Clear](Clear.md) diff --git a/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/GetAllDependencies.md b/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/GetAllDependencies.md index cb11d6b4..269f4268 100644 --- a/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/GetAllDependencies.md +++ b/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/GetAllDependencies.md @@ -1,31 +1,39 @@ # ResourceDependencyGraph::GetAllDependencies -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/ResourceDependencyGraph.h` + +## 签名 ```cpp Containers::Array GetAllDependencies(ResourceGUID guid) const; ``` -该方法声明于 `XCEngine/Core/Asset/ResourceDependencyGraph.h`，当前页面用于固定 `ResourceDependencyGraph` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `guid` - 参数语义详见头文件声明。 +收集某个节点的全部可达依赖。 -**返回：** `Containers::Array` - 返回值语义详见头文件声明。 +## 当前实现行为 -**示例：** +- 当前使用一个显式 `stack` 做深度遍历式搜索。 +- 起点 `guid` 会先压栈，但不会写入返回结果。 +- 每弹出一个节点时，会通过线性扫描 `result` 判断是否已访问过。 +- 对命中的节点，会把它的直接依赖继续压栈。 -```cpp -#include +## 返回值 -void Example() { - XCEngine::Resources::ResourceDependencyGraph object; - // 根据上下文补齐参数后调用 ResourceDependencyGraph::GetAllDependencies(...)。 - (void)object; -} -``` +- 一份去重后的间接/直接依赖 GUID 集合。 + +## 当前边界 + +- 返回顺序取决于当前数组压栈顺序，不是稳定拓扑序。 +- 当前没有专门的环保护逻辑；如果图结构本身异常，结果只保证“按现实现尽量遍历”。 ## 相关文档 -- [返回类总览](ResourceDependencyGraph.md) -- [返回模块目录](../Asset.md) +- [ResourceDependencyGraph](ResourceDependencyGraph.md) +- [GetDependencies](GetDependencies.md) +- [TopologicalSort](TopologicalSort.md) diff --git a/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/GetDependencies.md b/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/GetDependencies.md index c51234b3..80002f45 100644 --- a/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/GetDependencies.md +++ b/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/GetDependencies.md @@ -1,31 +1,32 @@ # ResourceDependencyGraph::GetDependencies -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/ResourceDependencyGraph.h` + +## 签名 ```cpp Containers::Array GetDependencies(ResourceGUID guid) const; ``` -该方法声明于 `XCEngine/Core/Asset/ResourceDependencyGraph.h`，当前页面用于固定 `ResourceDependencyGraph` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `guid` - 参数语义详见头文件声明。 +读取某个节点的直接依赖列表。 -**返回：** `Containers::Array` - 返回值语义详见头文件声明。 +## 当前实现行为 -**示例：** +- 如果节点存在，返回 `node->dependencies` 的一份拷贝。 +- 如果节点不存在，返回空数组。 -```cpp -#include +## 返回值 -void Example() { - XCEngine::Resources::ResourceDependencyGraph object; - // 根据上下文补齐参数后调用 ResourceDependencyGraph::GetDependencies(...)。 - (void)object; -} -``` +- 直接依赖 GUID 列表，不包含间接依赖。 ## 相关文档 -- [返回类总览](ResourceDependencyGraph.md) -- [返回模块目录](../Asset.md) +- [ResourceDependencyGraph](ResourceDependencyGraph.md) +- [GetAllDependencies](GetAllDependencies.md) +- [GetDependents](GetDependents.md) diff --git a/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/GetDependents.md b/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/GetDependents.md index 5e102a14..364de563 100644 --- a/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/GetDependents.md +++ b/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/GetDependents.md @@ -1,31 +1,32 @@ # ResourceDependencyGraph::GetDependents -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/ResourceDependencyGraph.h` + +## 签名 ```cpp Containers::Array GetDependents(ResourceGUID guid) const; ``` -该方法声明于 `XCEngine/Core/Asset/ResourceDependencyGraph.h`，当前页面用于固定 `ResourceDependencyGraph` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `guid` - 参数语义详见头文件声明。 +读取直接依赖当前节点的上游节点列表。 -**返回：** `Containers::Array` - 返回值语义详见头文件声明。 +## 当前实现行为 -**示例：** +- 如果节点存在，返回 `node->dependents` 的一份拷贝。 +- 如果节点不存在，返回空数组。 -```cpp -#include +## 返回值 -void Example() { - XCEngine::Resources::ResourceDependencyGraph object; - // 根据上下文补齐参数后调用 ResourceDependencyGraph::GetDependents(...)。 - (void)object; -} -``` +- 直接 dependent GUID 列表。 ## 相关文档 -- [返回类总览](ResourceDependencyGraph.md) -- [返回模块目录](../Asset.md) +- [ResourceDependencyGraph](ResourceDependencyGraph.md) +- [GetDependencies](GetDependencies.md) +- [Unload](Unload.md) diff --git a/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/GetRefCount.md b/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/GetRefCount.md index eace1c9f..933faf1f 100644 --- a/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/GetRefCount.md +++ b/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/GetRefCount.md @@ -1,31 +1,28 @@ # ResourceDependencyGraph::GetRefCount -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/ResourceDependencyGraph.h` + +## 签名 ```cpp Core::uint32 GetRefCount(ResourceGUID guid) const; ``` -该方法声明于 `XCEngine/Core/Asset/ResourceDependencyGraph.h`，当前页面用于固定 `ResourceDependencyGraph` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `guid` - 参数语义详见头文件声明。 +读取图节点当前记录的引用计数。 -**返回：** `Core::uint32` - 返回值语义详见头文件声明。 +## 当前实现行为 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::ResourceDependencyGraph object; - // 根据上下文补齐参数后调用 ResourceDependencyGraph::GetRefCount(...)。 - (void)object; -} -``` +- 如果节点存在，返回 `node->refCount`。 +- 否则返回 `0`。 ## 相关文档 -- [返回类总览](ResourceDependencyGraph.md) -- [返回模块目录](../Asset.md) +- [ResourceDependencyGraph](ResourceDependencyGraph.md) +- [IncrementRefCount](IncrementRefCount.md) +- [DecrementRefCount](DecrementRefCount.md) diff --git a/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/HasCircularDependency.md b/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/HasCircularDependency.md index 7195cb8a..4fced893 100644 --- a/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/HasCircularDependency.md +++ b/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/HasCircularDependency.md @@ -1,32 +1,42 @@ # ResourceDependencyGraph::HasCircularDependency -判断是否具备指定状态或能力。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/ResourceDependencyGraph.h` + +## 签名 ```cpp bool HasCircularDependency(ResourceGUID guid, Containers::Array& outCycle) const; ``` -该方法声明于 `XCEngine/Core/Asset/ResourceDependencyGraph.h`，当前页面用于固定 `ResourceDependencyGraph` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `guid` - 参数语义详见头文件声明。 -- `outCycle` - 参数语义详见头文件声明。 +尝试检测从指定节点出发是否能观察到循环依赖。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现行为 -**示例：** +- 当前实现使用一个显式栈和一个只增不减的 `path` 数组。 +- 每次弹出节点时，如果它已经出现在 `path` 中，就认为发现了环： + - `outCycle = path` + - 再把当前节点追加到 `outCycle` + - 返回 `true` +- 若遍历结束未发现重复节点，则返回 `false`。 -```cpp -#include +## 参数 -void Example() { - XCEngine::Resources::ResourceDependencyGraph object; - // 根据上下文补齐参数后调用 ResourceDependencyGraph::HasCircularDependency(...)。 - (void)object; -} -``` +- `guid` - 起始节点。 +- `outCycle` - 检测到环时写出的路径快照。 + +## 当前边界 + +- 当前算法可能把“共享子依赖”误判成环。 +- 无环时不会主动清空 `outCycle`。 +- 私有辅助函数 `HasCircularDependencyInternal()` 目前并未实际参与这条路径。 ## 相关文档 -- [返回类总览](ResourceDependencyGraph.md) -- [返回模块目录](../Asset.md) +- [ResourceDependencyGraph](ResourceDependencyGraph.md) +- [TopologicalSort](TopologicalSort.md) diff --git a/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/HasNode.md b/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/HasNode.md index 16b86f9f..3ee15da2 100644 --- a/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/HasNode.md +++ b/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/HasNode.md @@ -1,31 +1,30 @@ # ResourceDependencyGraph::HasNode -判断是否具备指定状态或能力。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/ResourceDependencyGraph.h` + +## 签名 ```cpp bool HasNode(ResourceGUID guid) const; ``` -该方法声明于 `XCEngine/Core/Asset/ResourceDependencyGraph.h`，当前页面用于固定 `ResourceDependencyGraph` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `guid` - 参数语义详见头文件声明。 +判断图中是否存在指定 GUID 的节点。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现行为 -**示例：** +- 当前实现直接返回 `m_nodes.Find(guid) != nullptr`。 -```cpp -#include +## 返回值 -void Example() { - XCEngine::Resources::ResourceDependencyGraph object; - // 根据上下文补齐参数后调用 ResourceDependencyGraph::HasNode(...)。 - (void)object; -} -``` +- 节点存在时返回 `true`，否则返回 `false`。 ## 相关文档 -- [返回类总览](ResourceDependencyGraph.md) -- [返回模块目录](../Asset.md) +- [ResourceDependencyGraph](ResourceDependencyGraph.md) +- [AddNode](AddNode.md) diff --git a/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/IncrementRefCount.md b/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/IncrementRefCount.md index 42e14405..9072b7e0 100644 --- a/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/IncrementRefCount.md +++ b/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/IncrementRefCount.md @@ -1,31 +1,28 @@ # ResourceDependencyGraph::IncrementRefCount -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/ResourceDependencyGraph.h` + +## 签名 ```cpp void IncrementRefCount(ResourceGUID guid); ``` -该方法声明于 `XCEngine/Core/Asset/ResourceDependencyGraph.h`，当前页面用于固定 `ResourceDependencyGraph` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `guid` - 参数语义详见头文件声明。 +增加图节点自己的引用计数。 -**返回：** `void` - 无返回值。 +## 当前实现行为 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::ResourceDependencyGraph object; - // 根据上下文补齐参数后调用 ResourceDependencyGraph::IncrementRefCount(...)。 - (void)object; -} -``` +- 仅当节点存在时，执行 `node->refCount++`。 +- 不会递归传播到依赖节点，也不会通知 [ResourceManager](../ResourceManager/ResourceManager.md)。 ## 相关文档 -- [返回类总览](ResourceDependencyGraph.md) -- [返回模块目录](../Asset.md) +- [ResourceDependencyGraph](ResourceDependencyGraph.md) +- [DecrementRefCount](DecrementRefCount.md) +- [GetRefCount](GetRefCount.md) diff --git a/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/RemoveDependency.md b/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/RemoveDependency.md index 20d3f193..101f5b53 100644 --- a/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/RemoveDependency.md +++ b/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/RemoveDependency.md @@ -1,32 +1,37 @@ # ResourceDependencyGraph::RemoveDependency -移除元素或解除关联。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/ResourceDependencyGraph.h` + +## 签名 ```cpp void RemoveDependency(ResourceGUID owner, ResourceGUID dependency); ``` -该方法声明于 `XCEngine/Core/Asset/ResourceDependencyGraph.h`，当前页面用于固定 `ResourceDependencyGraph` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `owner` - 参数语义详见头文件声明。 -- `dependency` - 参数语义详见头文件声明。 +删除一条 `owner -> dependency` 依赖边。 -**返回：** `void` - 无返回值。 +## 当前实现行为 -**示例：** +- 只有在两个节点都存在时才继续执行。 +- 会分别在： + - `ownerNode->dependencies` + - `depNode->dependents` + 里查找目标 GUID。 +- 删除方式都是“尾元素覆盖 + `PopBack()`”。 -```cpp -#include +## 当前边界 -void Example() { - XCEngine::Resources::ResourceDependencyGraph object; - // 根据上下文补齐参数后调用 ResourceDependencyGraph::RemoveDependency(...)。 - (void)object; -} -``` +- 不存在的边会被静默忽略。 +- 当前只删除找到的第一处匹配项。 ## 相关文档 -- [返回类总览](ResourceDependencyGraph.md) -- [返回模块目录](../Asset.md) +- [ResourceDependencyGraph](ResourceDependencyGraph.md) +- [AddDependency](AddDependency.md) +- [GetDependents](GetDependents.md) diff --git a/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/RemoveNode.md b/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/RemoveNode.md index a4d323b7..6bb05aa0 100644 --- a/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/RemoveNode.md +++ b/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/RemoveNode.md @@ -1,31 +1,32 @@ # ResourceDependencyGraph::RemoveNode -移除元素或解除关联。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/ResourceDependencyGraph.h` + +## 签名 ```cpp void RemoveNode(ResourceGUID guid); ``` -该方法声明于 `XCEngine/Core/Asset/ResourceDependencyGraph.h`，当前页面用于固定 `ResourceDependencyGraph` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `guid` - 参数语义详见头文件声明。 +从图中删除一个节点。 -**返回：** `void` - 无返回值。 +## 当前实现行为 -**示例：** +- 当前实现只有一行：`m_nodes.Erase(guid);` -```cpp -#include +## 当前边界 -void Example() { - XCEngine::Resources::ResourceDependencyGraph object; - // 根据上下文补齐参数后调用 ResourceDependencyGraph::RemoveNode(...)。 - (void)object; -} -``` +- 它不会同步清理其他节点 `dependencies` / `dependents` 里的残留 GUID。 +- 因此这更像“裸删节点”，不是完整的图一致性维护操作。 ## 相关文档 -- [返回类总览](ResourceDependencyGraph.md) -- [返回模块目录](../Asset.md) +- [ResourceDependencyGraph](ResourceDependencyGraph.md) +- [AddNode](AddNode.md) +- [Clear](Clear.md) diff --git a/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/TopologicalSort.md b/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/TopologicalSort.md index 6b8e3550..62455c75 100644 --- a/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/TopologicalSort.md +++ b/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/TopologicalSort.md @@ -1,30 +1,34 @@ # ResourceDependencyGraph::TopologicalSort -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/ResourceDependencyGraph.h` + +## 签名 ```cpp Containers::Array TopologicalSort() const; ``` -该方法声明于 `XCEngine/Core/Asset/ResourceDependencyGraph.h`，当前页面用于固定 `ResourceDependencyGraph` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +为依赖图提供拓扑排序入口。 -**返回：** `Containers::Array` - 返回值语义详见头文件声明。 +## 当前实现行为 -**示例：** +- 当前函数体只创建一个空 `Containers::Array result`，然后直接返回。 -```cpp -#include +## 返回值 -void Example() { - XCEngine::Resources::ResourceDependencyGraph object; - // 根据上下文补齐参数后调用 ResourceDependencyGraph::TopologicalSort(...)。 - (void)object; -} -``` +- 始终返回空数组。 + +## 当前边界 + +- 这是未完成实现，当前不能用于生成实际的加载顺序或卸载顺序。 ## 相关文档 -- [返回类总览](ResourceDependencyGraph.md) -- [返回模块目录](../Asset.md) +- [ResourceDependencyGraph](ResourceDependencyGraph.md) +- [GetAllDependencies](GetAllDependencies.md) diff --git a/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/Unload.md b/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/Unload.md index 04ba80e3..a93bfa3e 100644 --- a/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/Unload.md +++ b/docs/api/XCEngine/Core/Asset/ResourceDependencyGraph/Unload.md @@ -1,31 +1,41 @@ # ResourceDependencyGraph::Unload -卸载资源或释放缓存。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/ResourceDependencyGraph.h` + +## 签名 ```cpp bool Unload(ResourceGUID guid); ``` -该方法声明于 `XCEngine/Core/Asset/ResourceDependencyGraph.h`，当前页面用于固定 `ResourceDependencyGraph` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `guid` - 参数语义详见头文件声明。 +判断一个节点当前是否允许被卸载。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现行为 -**示例：** +- 若节点不存在，返回 `false`。 +- 若节点自身 `refCount > 0`，返回 `false`。 +- 否则遍历该节点的直接 `dependents`： + - 只要发现某个 dependent 节点存在且 `refCount > 0`，就返回 `false` +- 上述检查都通过时返回 `true`。 -```cpp -#include +## 返回值 -void Example() { - XCEngine::Resources::ResourceDependencyGraph object; - // 根据上下文补齐参数后调用 ResourceDependencyGraph::Unload(...)。 - (void)object; -} -``` +- `true` 表示“按当前简化规则可以卸载”。 +- `false` 表示“不允许卸载”或节点不存在。 + +## 当前边界 + +- 它不会真正删除节点，也不会释放资源对象。 +- 当前只检查直接 dependents，不做更深层递归分析。 ## 相关文档 -- [返回类总览](ResourceDependencyGraph.md) -- [返回模块目录](../Asset.md) +- [ResourceDependencyGraph](ResourceDependencyGraph.md) +- [GetDependents](GetDependents.md) +- [DecrementRefCount](DecrementRefCount.md) diff --git a/docs/api/XCEngine/Core/Asset/ResourceHandle/Constructor.md b/docs/api/XCEngine/Core/Asset/ResourceHandle/Constructor.md index 97d98dfe..a4f0ce2e 100644 --- a/docs/api/XCEngine/Core/Asset/ResourceHandle/Constructor.md +++ b/docs/api/XCEngine/Core/Asset/ResourceHandle/Constructor.md @@ -1,63 +1,58 @@ -# ResourceHandle::ResourceHandle() +# ResourceHandle::ResourceHandle -构造对象。 +**命名空间**: `XCEngine::Resources` -该方法在 `XCEngine/Core/Asset/ResourceHandle.h` 中提供了 4 个重载，当前页面统一汇总这些公开声明。 +**类型**: `method` -## 重载 1: 声明 +**头文件**: `XCEngine/Core/Asset/ResourceHandle.h` + +## 签名 ```cpp ResourceHandle() = default; +explicit ResourceHandle(T* resource); +ResourceHandle(const ResourceHandle& other); +ResourceHandle(ResourceHandle&& other) noexcept; ``` -**参数：** 无。 +## 作用 -**返回：** `void` - 无返回值。 +创建一个类型化资源句柄。 -## 重载 2: 声明 +## 当前实现行为 + +### 默认构造 + +- 得到一个空句柄，`m_resource == nullptr`。 + +### 指针构造 + +- 保存传入的 `resource` 指针。 +- 如果指针非空，会立刻调用： ```cpp -explicit ResourceHandle(T* resource) : m_resource(resource); +ResourceManager::Get().AddRef(m_resource->GetGUID()); ``` -**参数：** -- `resource` - 参数语义详见头文件声明。 +### 拷贝构造 -**返回：** `void` - 无返回值。 +- 复制 `other.m_resource`。 +- 如果指针非空，会再次调用一次 `AddRef()`。 -## 重载 3: 声明 +### 移动构造 -```cpp -ResourceHandle(const ResourceHandle& other) : m_resource(other.m_resource); -``` +- 直接窃取 `other.m_resource`。 +- 把 `other.m_resource` 置为 `nullptr`。 +- 不增加引用计数。 -**参数：** -- `other` - 参数语义详见头文件声明。 +## 当前边界 -**返回：** `void` - 无返回值。 - -## 重载 4: 声明 - -```cpp -ResourceHandle(ResourceHandle&& other) noexcept : m_resource(other.m_resource); -``` - -**参数：** -- `other` - 参数语义详见头文件声明。 - -**返回：** `void` - 无返回值。 - -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::ResourceHandle object; -} -``` +- 这是模板类构造，`T` 必须继承 `IResource`。 +- 指针构造不会验证该资源是否已经登记在 [ResourceManager](../ResourceManager/ResourceManager.md) 缓存中。 +- 因此它既能包装由管理器加载出的资源，也能包装外部直接 new 出来的裸资源指针。 ## 相关文档 -- [返回类总览](ResourceHandle.md) -- [返回模块目录](../Asset.md) +- [ResourceHandle](ResourceHandle.md) +- [OperatorAssign](OperatorAssign.md) +- [Destructor](Destructor.md) diff --git a/docs/api/XCEngine/Core/Asset/ResourceHandle/Destructor.md b/docs/api/XCEngine/Core/Asset/ResourceHandle/Destructor.md index c8e091ba..02fdeb6b 100644 --- a/docs/api/XCEngine/Core/Asset/ResourceHandle/Destructor.md +++ b/docs/api/XCEngine/Core/Asset/ResourceHandle/Destructor.md @@ -1,29 +1,34 @@ -# ResourceHandle::~ResourceHandle() +# ResourceHandle::~ResourceHandle -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/ResourceHandle.h` + +## 签名 ```cpp ~ResourceHandle(); ``` -该方法声明于 `XCEngine/Core/Asset/ResourceHandle.h`，当前页面用于固定 `ResourceHandle` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +在句柄离开作用域时释放它持有的引用计数通知。 -**返回：** `void` - 无返回值。 +## 当前实现行为 -**示例：** +- 析构函数实现只有一行：`Reset();` +- 因此如果当前持有非空资源，会： + - 调用 `ResourceManager::Get().Release(m_resource->GetGUID())` + - 把 `m_resource` 设为 `nullptr` -```cpp -#include +## 当前边界 -void Example() { - XCEngine::Resources::ResourceHandle object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 析构本身不会直接 `delete` 资源对象。 +- 是否真的触发资源回收，取决于 [ResourceManager](../ResourceManager/ResourceManager.md) 和 [ResourceCache](../ResourceCache/ResourceCache.md) 后续链路；当前这条链路仍未完全闭环。 ## 相关文档 -- [返回类总览](ResourceHandle.md) -- [返回模块目录](../Asset.md) +- [ResourceHandle](ResourceHandle.md) +- [Reset](Reset.md) diff --git a/docs/api/XCEngine/Core/Asset/ResourceHandle/Get.md b/docs/api/XCEngine/Core/Asset/ResourceHandle/Get.md index 6c555986..279a1596 100644 --- a/docs/api/XCEngine/Core/Asset/ResourceHandle/Get.md +++ b/docs/api/XCEngine/Core/Asset/ResourceHandle/Get.md @@ -1,29 +1,33 @@ # ResourceHandle::Get -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/ResourceHandle.h` + +## 签名 ```cpp T* Get() const; ``` -该方法声明于 `XCEngine/Core/Asset/ResourceHandle.h`，当前页面用于固定 `ResourceHandle` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回句柄内部保存的裸资源指针。 -**返回：** `T*` - 返回值语义详见头文件声明。 +## 当前实现行为 -**示例：** +- 这是头文件中的内联访问器，直接返回 `m_resource`。 +- 不做空值检查，也不触发 `AddRef()` / `Release()`。 -```cpp -#include +## 返回值 -void Example() { - auto& instance = XCEngine::Resources::ResourceHandle::Get(); - (void)instance; -} -``` +- 当前持有的 `T*`。 +- 如果句柄为空，则返回 `nullptr`。 ## 相关文档 -- [返回类总览](ResourceHandle.md) -- [返回模块目录](../Asset.md) +- [ResourceHandle](ResourceHandle.md) +- [OperatorArrow](OperatorArrow.md) +- [IsValid](IsValid.md) diff --git a/docs/api/XCEngine/Core/Asset/ResourceHandle/GetGUID.md b/docs/api/XCEngine/Core/Asset/ResourceHandle/GetGUID.md index 979bf902..6fb8e383 100644 --- a/docs/api/XCEngine/Core/Asset/ResourceHandle/GetGUID.md +++ b/docs/api/XCEngine/Core/Asset/ResourceHandle/GetGUID.md @@ -1,30 +1,32 @@ # ResourceHandle::GetGUID -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/ResourceHandle.h` + +## 签名 ```cpp ResourceGUID GetGUID() const; ``` -该方法声明于 `XCEngine/Core/Asset/ResourceHandle.h`，当前页面用于固定 `ResourceHandle` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +读取当前资源的 GUID。 -**返回：** `ResourceGUID` - 返回值语义详见头文件声明。 +## 当前实现行为 -**示例：** +- 若 `m_resource` 非空，返回 `m_resource->GetGUID()`。 +- 若句柄为空，返回 `ResourceGUID(0)`。 -```cpp -#include +## 返回值 -void Example() { - XCEngine::Resources::ResourceHandle object; - // 根据上下文补齐参数后调用 ResourceHandle::GetGUID(...)。 - (void)object; -} -``` +- 当前资源 GUID，或空句柄哨兵值 `0`。 ## 相关文档 -- [返回类总览](ResourceHandle.md) -- [返回模块目录](../Asset.md) +- [ResourceHandle](ResourceHandle.md) +- [GetResourceType](GetResourceType.md) +- [IsValid](IsValid.md) diff --git a/docs/api/XCEngine/Core/Asset/ResourceHandle/GetResourceType.md b/docs/api/XCEngine/Core/Asset/ResourceHandle/GetResourceType.md index 97cf6398..722d6579 100644 --- a/docs/api/XCEngine/Core/Asset/ResourceHandle/GetResourceType.md +++ b/docs/api/XCEngine/Core/Asset/ResourceHandle/GetResourceType.md @@ -1,30 +1,31 @@ # ResourceHandle::GetResourceType -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/ResourceHandle.h` + +## 签名 ```cpp ResourceType GetResourceType() const; ``` -该方法声明于 `XCEngine/Core/Asset/ResourceHandle.h`，当前页面用于固定 `ResourceHandle` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +读取当前资源类型。 -**返回：** `ResourceType` - 返回值语义详见头文件声明。 +## 当前实现行为 -**示例：** +- 若 `m_resource` 非空，返回 `m_resource->GetType()`。 +- 若句柄为空，返回 `ResourceType::Unknown`。 -```cpp -#include +## 返回值 -void Example() { - XCEngine::Resources::ResourceHandle object; - // 根据上下文补齐参数后调用 ResourceHandle::GetResourceType(...)。 - (void)object; -} -``` +- 当前资源类型，或空句柄哨兵值 `Unknown`。 ## 相关文档 -- [返回类总览](ResourceHandle.md) -- [返回模块目录](../Asset.md) +- [ResourceHandle](ResourceHandle.md) +- [GetGUID](GetGUID.md) diff --git a/docs/api/XCEngine/Core/Asset/ResourceHandle/IsValid.md b/docs/api/XCEngine/Core/Asset/ResourceHandle/IsValid.md index 3bbf8e9f..f44dbe55 100644 --- a/docs/api/XCEngine/Core/Asset/ResourceHandle/IsValid.md +++ b/docs/api/XCEngine/Core/Asset/ResourceHandle/IsValid.md @@ -1,30 +1,40 @@ # ResourceHandle::IsValid -查询当前状态。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/ResourceHandle.h` + +## 签名 ```cpp bool IsValid() const; ``` -该方法声明于 `XCEngine/Core/Asset/ResourceHandle.h`，当前页面用于固定 `ResourceHandle` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +判断句柄当前是否指向一个逻辑上有效的资源。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现行为 -**示例：** +实现等价于： ```cpp -#include - -void Example() { - XCEngine::Resources::ResourceHandle object; - // 根据上下文补齐参数后调用 ResourceHandle::IsValid(...)。 - (void)object; -} +return m_resource != nullptr && m_resource->IsValid(); ``` +## 返回值 + +- 只有在内部指针非空且底层资源 `IsValid()` 返回 `true` 时才返回 `true`。 + +## 当前边界 + +- 它不会验证该资源是否仍登记在 [ResourceManager](../ResourceManager/ResourceManager.md) 缓存里。 +- 它也不会检查资源是否已被别的系统回收成悬空指针。 + ## 相关文档 -- [返回类总览](ResourceHandle.md) -- [返回模块目录](../Asset.md) +- [ResourceHandle](ResourceHandle.md) +- [bool](bool.md) +- [Get](Get.md) diff --git a/docs/api/XCEngine/Core/Asset/ResourceHandle/OperatorArrow.md b/docs/api/XCEngine/Core/Asset/ResourceHandle/OperatorArrow.md index bb518f22..c9adcd1d 100644 --- a/docs/api/XCEngine/Core/Asset/ResourceHandle/OperatorArrow.md +++ b/docs/api/XCEngine/Core/Asset/ResourceHandle/OperatorArrow.md @@ -1,30 +1,33 @@ # ResourceHandle::operator-> -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/ResourceHandle.h` + +## 签名 ```cpp T* operator->() const; ``` -该方法声明于 `XCEngine/Core/Asset/ResourceHandle.h`，当前页面用于固定 `ResourceHandle` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +提供 `handle->Member` 语法。 -**返回：** `T*` - 返回值语义详见头文件声明。 +## 当前实现行为 -**示例：** +- 这是头文件中的内联访问器，直接返回 `m_resource`。 +- 当前没有断言、异常或空指针保护。 -```cpp -#include +## 当前边界 -void Example() { - XCEngine::Resources::ResourceHandle object; - // 根据上下文补齐参数后调用 ResourceHandle::operator->(...)。 - (void)object; -} -``` +- 调用方必须先自己保证句柄非空且资源仍有效。 +- 如果句柄为空，继续用 `->` 解引用就是未定义行为。 ## 相关文档 -- [返回类总览](ResourceHandle.md) -- [返回模块目录](../Asset.md) +- [ResourceHandle](ResourceHandle.md) +- [Get](Get.md) +- [IsValid](IsValid.md) diff --git a/docs/api/XCEngine/Core/Asset/ResourceHandle/OperatorAssign.md b/docs/api/XCEngine/Core/Asset/ResourceHandle/OperatorAssign.md index 7653bef8..89928046 100644 --- a/docs/api/XCEngine/Core/Asset/ResourceHandle/OperatorAssign.md +++ b/docs/api/XCEngine/Core/Asset/ResourceHandle/OperatorAssign.md @@ -1,44 +1,51 @@ # ResourceHandle::operator= -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Resources` -该方法在 `XCEngine/Core/Asset/ResourceHandle.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。 +**类型**: `method` -## 重载 1: 声明 +**头文件**: `XCEngine/Core/Asset/ResourceHandle.h` + +## 签名 ```cpp ResourceHandle& operator=(const ResourceHandle& other); -``` - -**参数：** -- `other` - 参数语义详见头文件声明。 - -**返回：** `ResourceHandle&` - 返回值语义详见头文件声明。 - -## 重载 2: 声明 - -```cpp ResourceHandle& operator=(ResourceHandle&& other) noexcept; ``` -**参数：** -- `other` - 参数语义详见头文件声明。 +## 作用 -**返回：** `ResourceHandle&` - 返回值语义详见头文件声明。 +把当前句柄改为持有另一个句柄的资源，或接管另一个句柄的资源。 -**示例：** +## 当前实现行为 -```cpp -#include +### 拷贝赋值 -void Example() { - XCEngine::Resources::ResourceHandle object; - // 根据上下文补齐参数后调用 ResourceHandle::operator=(...)。 - (void)object; -} -``` +- 先检查 `this != &other`。 +- 若不是自赋值： + - 先调用 [Reset](Reset.md) 释放当前句柄 + - 再把 `m_resource` 设为 `other.m_resource` + - 若新指针非空，再调用一次 `ResourceManager::Get().AddRef(...)` + +### 移动赋值 + +- 同样先检查 `this != &other`。 +- 若不是自赋值： + - 先 `Reset()` + - 再窃取 `other.m_resource` + - 把 `other.m_resource` 置空 +- 不增加引用计数。 + +## 返回值 + +- 返回 `*this`。 + +## 当前边界 + +- 拷贝赋值和移动赋值都可能触发 `ResourceManager` 侧副作用，不是纯本地指针覆盖。 ## 相关文档 -- [返回类总览](ResourceHandle.md) -- [返回模块目录](../Asset.md) +- [ResourceHandle](ResourceHandle.md) +- [Constructor](Constructor.md) +- [Reset](Reset.md) diff --git a/docs/api/XCEngine/Core/Asset/ResourceHandle/OperatorMultiply.md b/docs/api/XCEngine/Core/Asset/ResourceHandle/OperatorMultiply.md index 02472428..df6ee760 100644 --- a/docs/api/XCEngine/Core/Asset/ResourceHandle/OperatorMultiply.md +++ b/docs/api/XCEngine/Core/Asset/ResourceHandle/OperatorMultiply.md @@ -1,30 +1,33 @@ # ResourceHandle::operator* -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/ResourceHandle.h` + +## 签名 ```cpp T& operator*() const; ``` -该方法声明于 `XCEngine/Core/Asset/ResourceHandle.h`，当前页面用于固定 `ResourceHandle` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +提供 `*handle` 解引用语法。 -**返回：** `T&` - 返回值语义详见头文件声明。 +## 当前实现行为 -**示例：** +- 这是头文件中的内联访问器，直接返回 `*m_resource`。 +- 当前没有任何空值保护。 -```cpp -#include +## 当前边界 -void Example() { - XCEngine::Resources::ResourceHandle object; - // 根据上下文补齐参数后调用 ResourceHandle::operator*(...)。 - (void)object; -} -``` +- 如果句柄为空，`operator*()` 会直接解引用空指针。 +- 即使句柄非空，资源对象本身的有效性和线程安全也仍由外部保证。 ## 相关文档 -- [返回类总览](ResourceHandle.md) -- [返回模块目录](../Asset.md) +- [ResourceHandle](ResourceHandle.md) +- [OperatorArrow](OperatorArrow.md) +- [IsValid](IsValid.md) diff --git a/docs/api/XCEngine/Core/Asset/ResourceHandle/Reset.md b/docs/api/XCEngine/Core/Asset/ResourceHandle/Reset.md index 6c9cb532..87ab1091 100644 --- a/docs/api/XCEngine/Core/Asset/ResourceHandle/Reset.md +++ b/docs/api/XCEngine/Core/Asset/ResourceHandle/Reset.md @@ -1,30 +1,39 @@ # ResourceHandle::Reset -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/ResourceHandle.h` + +## 签名 ```cpp void Reset(); ``` -该方法声明于 `XCEngine/Core/Asset/ResourceHandle.h`，当前页面用于固定 `ResourceHandle` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +释放当前句柄持有的资源引用并把句柄清空。 -**返回：** `void` - 无返回值。 +## 当前实现行为 -**示例：** +- 如果 `m_resource` 非空，会先调用： ```cpp -#include - -void Example() { - XCEngine::Resources::ResourceHandle object; - // 根据上下文补齐参数后调用 ResourceHandle::Reset(...)。 - (void)object; -} +ResourceManager::Get().Release(m_resource->GetGUID()); ``` +- 然后把 `m_resource = nullptr`。 +- 如果句柄本来就是空的，则什么也不做。 + +## 当前边界 + +- `Reset()` 不会直接释放资源对象内存。 +- 它只是向 [ResourceManager](../ResourceManager/ResourceManager.md) 通知“这个句柄不再持有该 GUID”。 + ## 相关文档 -- [返回类总览](ResourceHandle.md) -- [返回模块目录](../Asset.md) +- [ResourceHandle](ResourceHandle.md) +- [Destructor](Destructor.md) +- [OperatorAssign](OperatorAssign.md) diff --git a/docs/api/XCEngine/Core/Asset/ResourceHandle/Swap.md b/docs/api/XCEngine/Core/Asset/ResourceHandle/Swap.md index 97a25510..86879d9e 100644 --- a/docs/api/XCEngine/Core/Asset/ResourceHandle/Swap.md +++ b/docs/api/XCEngine/Core/Asset/ResourceHandle/Swap.md @@ -1,31 +1,35 @@ # ResourceHandle::Swap -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/ResourceHandle.h` + +## 签名 ```cpp void Swap(ResourceHandle& other); ``` -该方法声明于 `XCEngine/Core/Asset/ResourceHandle.h`，当前页面用于固定 `ResourceHandle` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `other` - 参数语义详见头文件声明。 +交换两个句柄内部保存的资源指针。 -**返回：** `void` - 无返回值。 +## 当前实现行为 -**示例：** +- 实现直接调用 `std::swap(m_resource, other.m_resource)`。 +- 交换过程中不会触发 `AddRef()` 或 `Release()`。 -```cpp -#include +## 参数 -void Example() { - XCEngine::Resources::ResourceHandle object; - // 根据上下文补齐参数后调用 ResourceHandle::Swap(...)。 - (void)object; -} -``` +- `other` - 另一个同类型句柄。 + +## 当前边界 + +- 它只交换当前两个句柄的本地指针状态，不会改变 [ResourceManager](../ResourceManager/ResourceManager.md) 中的总引用计数。 ## 相关文档 -- [返回类总览](ResourceHandle.md) -- [返回模块目录](../Asset.md) +- [ResourceHandle](ResourceHandle.md) +- [OperatorAssign](OperatorAssign.md) diff --git a/docs/api/XCEngine/Core/Asset/ResourceHandle/bool.md b/docs/api/XCEngine/Core/Asset/ResourceHandle/bool.md index 05936868..40cea2f1 100644 --- a/docs/api/XCEngine/Core/Asset/ResourceHandle/bool.md +++ b/docs/api/XCEngine/Core/Asset/ResourceHandle/bool.md @@ -1,30 +1,31 @@ -# ResourceHandle::bool +# ResourceHandle::operator bool -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/ResourceHandle.h` + +## 签名 ```cpp explicit operator bool() const; ``` -该方法声明于 `XCEngine/Core/Asset/ResourceHandle.h`，当前页面用于固定 `ResourceHandle` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +让句柄可以直接用于 `if (handle)` 这类布尔上下文。 -**返回：** `operator` - 返回值语义详见头文件声明。 +## 当前实现行为 -**示例：** +- 实现直接返回 [IsValid](IsValid.md) 的结果。 +- 没有额外语义，也不会触发资源管理副作用。 -```cpp -#include +## 返回值 -void Example() { - XCEngine::Resources::ResourceHandle object; - // 根据上下文补齐参数后调用 ResourceHandle::bool(...)。 - (void)object; -} -``` +- 与 `IsValid()` 完全一致。 ## 相关文档 -- [返回类总览](ResourceHandle.md) -- [返回模块目录](../Asset.md) +- [ResourceHandle](ResourceHandle.md) +- [IsValid](IsValid.md) diff --git a/docs/api/XCEngine/Core/Asset/ResourceManager/CanReimportProjectAsset.md b/docs/api/XCEngine/Core/Asset/ResourceManager/CanReimportProjectAsset.md new file mode 100644 index 00000000..fb6513c2 --- /dev/null +++ b/docs/api/XCEngine/Core/Asset/ResourceManager/CanReimportProjectAsset.md @@ -0,0 +1,65 @@ +# ResourceManager::CanReimportProjectAsset + +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/ResourceManager.h` + +## 签名 + +```cpp +bool CanReimportProjectAsset(const Containers::String& path) const; +``` + +## 作用 + +判断指定路径当前是否属于“可通过项目资产工具链重导”的项目资产。 + +它是一个无副作用的前置判断接口。 + +## 当前实现行为 + +1. 如果 `m_resourceRoot` 为空，直接返回 `false`。 +2. 如果 `path` 为空，直接返回 `false`。 +3. 否则调用： + +```cpp +ResourceType importType = ResourceType::Unknown; +return m_assetImportService.TryGetImportableResourceType(path, importType); +``` + +需要注意，当前实现会丢弃探测得到的具体 `importType`，只保留“能不能导”的布尔结论。 + +## 真实语义边界 + +它当前回答的是： + +- 这条路径在当前项目上下文里，是否能被识别成一个可导入的 project asset + +它并不回答： + +- 导入后一定会不会成功 +- 具体使用哪个 importer 的所有细节 +- 是否需要立即重导 + +因此它最适合用在 UI / 工具入口上，先决定是否启用“Reimport”命令。 + +## 设计意义 + +把“是否可重导”单独做成一个轻量探测接口，有两个现实好处： + +- 编辑器不必为了点亮/禁用一个按钮，就真的触发一次导入。 +- 调用方不必了解 `AssetImportService::TryGetImportableResourceType()` 和 `Unknown` primary type 的细节。 + +## 测试锚点 + +`tests/Core/Asset/test_resource_manager.cpp` 里的 +`ResourceManager_Test.ReimportProjectAssetBuildsArtifactForSelectedPath` +先调用了 `CanReimportProjectAsset("Assets/runtime.material")`，验证当前路径在项目上下文里可被识别为可导入资产。 + +## 相关文档 + +- [ResourceManager](ResourceManager.md) +- [ReimportProjectAsset](ReimportProjectAsset.md) +- [AssetImportService::TryGetImportableResourceType](../AssetImportService/TryGetImportableResourceType.md) diff --git a/docs/api/XCEngine/Core/Asset/ResourceManager/ClearProjectLibraryCache.md b/docs/api/XCEngine/Core/Asset/ResourceManager/ClearProjectLibraryCache.md new file mode 100644 index 00000000..707bc6d6 --- /dev/null +++ b/docs/api/XCEngine/Core/Asset/ResourceManager/ClearProjectLibraryCache.md @@ -0,0 +1,68 @@ +# ResourceManager::ClearProjectLibraryCache + +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/ResourceManager.h` + +## 签名 + +```cpp +bool ClearProjectLibraryCache(); +``` + +## 作用 + +清空当前项目 `Library` 缓存，并同步刷新运行时缓存和项目资产查询 snapshot。 + +## 当前实现流程 + +当前顺序固定为： + +```text +if (m_resourceRoot.Empty()) return false +UnloadAll() +-> m_assetImportService.ClearLibraryCache() +-> m_projectAssetIndex.RefreshFrom(m_assetImportService) +``` + +## 关键语义 + +### 它比 `AssetImportService::ClearLibraryCache()` 更高一层 + +底层服务只负责清理 `Library` 并重建数据库根结构，而 `ResourceManager` 这一层还额外负责： + +- 清空当前运行时资源缓存 +- 刷新 `ProjectAssetIndex` + +这就是为什么它不能被理解成“只是转发底层清缓存”。 + +### 它不会自动全量重导 + +当前实现只负责清空 `Library`，不会继续调用 [RebuildProjectAssetCache](RebuildProjectAssetCache.md) 或批量重导全部资产。 + +因此清理成功后，`Artifacts` 目录可能暂时为空，直到后续发生： + +- [ReimportProjectAsset](ReimportProjectAsset.md) +- [RebuildProjectAssetCache](RebuildProjectAssetCache.md) +- 运行时按需加载触发的 artifact 生成 + +### 失败不会回滚 `UnloadAll()` + +如果底层清理失败，当前实现也不会恢复此前已卸载的资源对象。 + +## 返回值 + +- `true` + - 当前项目根有效，且底层清理成功。 +- `false` + - 当前没有项目根，或底层清理失败。 + +## 相关文档 + +- [ResourceManager](ResourceManager.md) +- [RebuildProjectAssetCache](RebuildProjectAssetCache.md) +- [GetProjectLibraryRoot](GetProjectLibraryRoot.md) +- [GetProjectAssetImportStatus](GetProjectAssetImportStatus.md) +- [AssetImportService::ClearLibraryCache](../AssetImportService/ClearLibraryCache.md) diff --git a/docs/api/XCEngine/Core/Asset/ResourceManager/GetProjectAssetImportStatus.md b/docs/api/XCEngine/Core/Asset/ResourceManager/GetProjectAssetImportStatus.md new file mode 100644 index 00000000..a2245476 --- /dev/null +++ b/docs/api/XCEngine/Core/Asset/ResourceManager/GetProjectAssetImportStatus.md @@ -0,0 +1,59 @@ +# ResourceManager::GetProjectAssetImportStatus + +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/ResourceManager.h` + +## 签名 + +```cpp +AssetImportService::ImportStatusSnapshot GetProjectAssetImportStatus() const; +``` + +## 作用 + +返回最近一次项目资产导入/清理操作的状态快照。 + +这是 `ResourceManager` 层暴露给上层工具和测试的项目资产状态观察入口。 + +## 当前实现行为 + +- 当前只是直接转发到底层： + +```cpp +return m_assetImportService.GetLastImportStatus(); +``` + +- 不会主动刷新项目资产。 +- 不会构建历史记录。 +- 返回的是一个按值拷贝的 [ImportStatusSnapshot](../AssetImportService/ImportStatusSnapshot.md)。 + +## 为什么这个入口有意义 + +虽然它只是转发，但它让只依赖 `ResourceManager` 的上层代码也能获取项目资产工具链状态，例如： + +- 最近一次 `ReimportProjectAsset()` 是否成功 +- `RefreshProjectAssets()` 是否清理了孤儿 artifact +- `RebuildProjectAssetCache()` 最后留下的到底是哪一步状态 + +这可以避免上层同时持有 `ResourceManager` 和 `AssetImportService` 两个入口对象。 + +## 当前状态来源 + +实际写入状态的是底层 [AssetImportService](../AssetImportService/AssetImportService.md)。因此这里观测到的语义完全继承它的当前规则，例如： + +- `Refresh()` 只有在清理了孤儿 artifact 时才会更新状态 +- `EnsureArtifact()` 成功时只有在“本次真的发生导入”时才会更新状态 +- `RebuildLibraryCache()` 成功后最终留下的状态通常是 `"Reimport All Assets"` + +## 相关文档 + +- [ResourceManager](ResourceManager.md) +- [RefreshProjectAssets](RefreshProjectAssets.md) +- [ReimportProjectAsset](ReimportProjectAsset.md) +- [ClearProjectLibraryCache](ClearProjectLibraryCache.md) +- [RebuildProjectAssetCache](RebuildProjectAssetCache.md) +- [AssetImportService::GetLastImportStatus](../AssetImportService/GetLastImportStatus.md) +- [AssetImportService::ImportStatusSnapshot](../AssetImportService/ImportStatusSnapshot.md) diff --git a/docs/api/XCEngine/Core/Asset/ResourceManager/GetProjectLibraryRoot.md b/docs/api/XCEngine/Core/Asset/ResourceManager/GetProjectLibraryRoot.md index 30ee9234..63b725e3 100644 --- a/docs/api/XCEngine/Core/Asset/ResourceManager/GetProjectLibraryRoot.md +++ b/docs/api/XCEngine/Core/Asset/ResourceManager/GetProjectLibraryRoot.md @@ -14,21 +14,26 @@ Containers::String GetProjectLibraryRoot() const; ## 作用 -返回当前项目 `Library` 目录的根路径。 +返回当前项目 `Library` 根目录的绝对路径。 ## 当前实现行为 -- 直接转发到 `m_assetImportService.GetLibraryRoot()`。 -- 返回值是一个按值复制出来的 `Containers::String`，不是内部成员引用。 +- 当前只是直接转发到底层 `m_assetImportService.GetLibraryRoot()`。 +- 返回值是按值返回的 `Containers::String`，不是内部成员引用。 - 如果当前没有绑定项目根，通常会返回空字符串。 -## 主要用途 +## 为什么这个入口仍然有价值 -- 用于测试或工具层定位当前项目的 `Library` 目录。 -- 在执行 [RebuildProjectAssetCache](RebuildProjectAssetCache.md) 前后，可以用它确认实际操作的缓存目录。 +虽然它只是一个转发接口，但在 `ResourceManager` 这一层保留它是合理的，因为很多上层工具只持有 `ResourceManager`，并不知道内部还有 `AssetImportService`。 + +典型用途包括： + +- 在执行 [ClearProjectLibraryCache](ClearProjectLibraryCache.md) 或 [RebuildProjectAssetCache](RebuildProjectAssetCache.md) 前后定位实际操作的 `Library` 目录。 +- 在测试里验证 artifact 是否生成、清理或重建。 ## 相关文档 - [ResourceManager](ResourceManager.md) +- [ClearProjectLibraryCache](ClearProjectLibraryCache.md) - [RebuildProjectAssetCache](RebuildProjectAssetCache.md) - [AssetImportService::GetLibraryRoot](../AssetImportService/GetLibraryRoot.md) diff --git a/docs/api/XCEngine/Core/Asset/ResourceManager/RebuildProjectAssetCache.md b/docs/api/XCEngine/Core/Asset/ResourceManager/RebuildProjectAssetCache.md index 2b710a50..82a2a432 100644 --- a/docs/api/XCEngine/Core/Asset/ResourceManager/RebuildProjectAssetCache.md +++ b/docs/api/XCEngine/Core/Asset/ResourceManager/RebuildProjectAssetCache.md @@ -14,26 +14,65 @@ bool RebuildProjectAssetCache(); ## 作用 -清空当前运行时资源缓存，重建项目 `Library` 缓存目录，并刷新项目资产索引状态。 +清空当前运行时资源缓存，重建项目 `Library` 缓存，并刷新 `ProjectAssetIndex`。 -## 当前实现行为 +这是 `ResourceManager` 层最高级别的项目资产重建命令。 -- 如果 `m_resourceRoot` 为空，直接返回 `false` -- 否则固定按下面的顺序执行: - 1. `UnloadAll()` - 2. `m_assetImportService.RebuildLibraryCache()` - 3. `m_projectAssetIndex.RefreshFrom(m_assetImportService)` -- 返回值直接透传 `AssetImportService::RebuildLibraryCache()` 的结果 +## 当前实现流程 -## 当前语义 +当前顺序固定为： -- 这是“清空并重建当前项目 Library 缓存”的高层入口，不是普通的 snapshot 刷新 -- 它会丢掉当前 `ResourceManager` 中已经加载的运行时资源对象，因此比 [RefreshProjectAssets](RefreshProjectAssets.md) 更重 -- `tests/core/Asset/test_resource_manager.cpp` 里的 `ResourceManager_Test.RebuildProjectAssetCacheRefreshesLookupState` 验证了重建后 `AssetRef` 查询仍能恢复，并能重新命中新建的 Library 产物 +```text +UnloadAll() +-> m_assetImportService.RebuildLibraryCache() +-> m_projectAssetIndex.RefreshFrom(m_assetImportService) +``` + +并且只有在 `m_resourceRoot` 非空时才会执行；否则直接返回 `false`。 + +## 返回值 + +- `true` + - 当前项目根有效，且底层 [AssetImportService::RebuildLibraryCache](../AssetImportService/RebuildLibraryCache.md) 成功。 +- `false` + - 当前没有项目根，或底层重建失败。 + +需要注意，当前失败不会回滚前面已经发生的 [UnloadAll](UnloadAll.md)。也就是说，方法失败后，运行时缓存仍然可能已经被清空。 + +## 和其他项目资产工具命令的区别 + +- 和 [RefreshProjectAssets](RefreshProjectAssets.md) 相比： + - 它不仅刷新 snapshot，还会重建整个 `Library` + - 它会先卸载全部已加载资源 +- 和 [ClearProjectLibraryCache](ClearProjectLibraryCache.md) 相比： + - 它不仅清空 `Library`，还会继续做全量重导 +- 和 [ReimportProjectAsset](ReimportProjectAsset.md) 相比： + - 它针对的是整个项目，而不是单个路径 + +## 导入状态语义 + +成功或失败后，可以通过 [GetProjectAssetImportStatus](GetProjectAssetImportStatus.md) 读取最近状态。 + +但要注意，底层 `AssetImportService::RebuildLibraryCache()` 当前本身是： + +```text +ClearLibraryCache() +-> ReimportAllAssets() +``` + +因此在成功场景下，最终留下的最近状态通常会是 `"Reimport All Assets"`，而不是 `"Rebuild Project Asset Cache"`。 + +## 测试锚点 + +`tests/Core/Asset/test_resource_manager.cpp` 里的 +`ResourceManager_Test.RebuildProjectAssetCacheRefreshesLookupState` +直接约束了当前行为：即使整份 `Library` 被重建，项目资产查询状态也应被重新恢复。 ## 相关文档 - [ResourceManager](ResourceManager.md) - [RefreshProjectAssets](RefreshProjectAssets.md) +- [ClearProjectLibraryCache](ClearProjectLibraryCache.md) - [GetProjectLibraryRoot](GetProjectLibraryRoot.md) +- [GetProjectAssetImportStatus](GetProjectAssetImportStatus.md) - [AssetImportService::RebuildLibraryCache](../AssetImportService/RebuildLibraryCache.md) diff --git a/docs/api/XCEngine/Core/Asset/ResourceManager/RefreshProjectAssets.md b/docs/api/XCEngine/Core/Asset/ResourceManager/RefreshProjectAssets.md index bf1681b7..e7b72897 100644 --- a/docs/api/XCEngine/Core/Asset/ResourceManager/RefreshProjectAssets.md +++ b/docs/api/XCEngine/Core/Asset/ResourceManager/RefreshProjectAssets.md @@ -14,25 +14,52 @@ void RefreshProjectAssets(); ## 作用 -显式刷新当前项目的资产数据库，并重建 `ProjectAssetIndex` 的本地 snapshot。 +刷新当前项目的资产数据库视图，并重建 `ProjectAssetIndex` 的本地 snapshot。 + +它是“项目资产查询链”的轻量同步入口，不负责卸载已加载资源，也不负责强制重导 artifact。 ## 当前实现行为 -- 只有在 `m_resourceRoot` 非空时才执行实际刷新。 -- 固定按下面的顺序执行： - - `m_assetImportService.Refresh()` - - `m_projectAssetIndex.RefreshFrom(m_assetImportService)` -- 它不会直接重载已经在运行时缓存里的资源对象；只负责更新项目资产查询链路。 +- 只有当 `m_resourceRoot` 非空时才会执行实际刷新。 +- 当前固定顺序是： + +```text +m_assetImportService.Refresh() +-> m_projectAssetIndex.RefreshFrom(m_assetImportService) +``` + +- 如果当前没有项目根，直接返回。 + +## 和重导类命令的区别 + +这个方法最容易被误读成“刷新并重建项目缓存”，但当前它做的事情更轻： + +- 不会调用 [UnloadAll](UnloadAll.md) +- 不会调用 [ReimportProjectAsset](ReimportProjectAsset.md) +- 不会调用 [ClearProjectLibraryCache](ClearProjectLibraryCache.md) +- 不会调用 [RebuildProjectAssetCache](RebuildProjectAssetCache.md) + +它更像是“让 snapshot 跟上最新磁盘状态”的维护命令。 + +## 导入状态语义 + +如果你在调用后读取 [GetProjectAssetImportStatus](GetProjectAssetImportStatus.md)，要注意底层 [AssetImportService::Refresh](../AssetImportService/Refresh.md) 当前只会在“清理了孤儿 artifact”时更新最近状态。 + +因此： + +- `RefreshProjectAssets()` 执行了，不代表最近状态一定变化 +- 最近状态没变化，也不代表这次刷新没有同步 source 快照 ## 适用场景 -- 项目里新增、删除或改写了 `Assets/...` 源文件后，需要让 `AssetRef` 查询和路径反查看到最新状态。 -- `TryGetAssetRef()` 的 cache miss 自动恢复不够时，可以显式调用这条入口做一次整体刷新。 +- 项目里新增、删除或改写了 `Assets/...` 文件后，希望 `AssetRef` 查询和路径反查尽快看到最新状态。 +- 需要在不清空运行时缓存的前提下，把 `ProjectAssetIndex` 和资产数据库重新对齐。 ## 相关文档 - [ResourceManager](ResourceManager.md) -- [SetResourceRoot](SetResourceRoot.md) -- [TryGetAssetRef](TryGetAssetRef.md) +- [GetProjectAssetImportStatus](GetProjectAssetImportStatus.md) +- [CanReimportProjectAsset](CanReimportProjectAsset.md) +- [RebuildProjectAssetCache](RebuildProjectAssetCache.md) - [AssetImportService::Refresh](../AssetImportService/Refresh.md) - [ProjectAssetIndex::RefreshFrom](../ProjectAssetIndex/RefreshFrom.md) diff --git a/docs/api/XCEngine/Core/Asset/ResourceManager/ReimportProjectAsset.md b/docs/api/XCEngine/Core/Asset/ResourceManager/ReimportProjectAsset.md new file mode 100644 index 00000000..b2edb7a3 --- /dev/null +++ b/docs/api/XCEngine/Core/Asset/ResourceManager/ReimportProjectAsset.md @@ -0,0 +1,97 @@ +# ResourceManager::ReimportProjectAsset + +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Asset/ResourceManager.h` + +## 签名 + +```cpp +bool ReimportProjectAsset(const Containers::String& path); +``` + +## 作用 + +重导指定项目资产，同时同步运行时缓存和项目资产查询 snapshot。 + +这是 `ResourceManager` 层面对“单资产重导”给出的完整工具命令，而不是简单的底层转发。 + +## 当前实现流程 + +当前顺序固定为： + +```text +if (m_resourceRoot.Empty() || path.Empty()) return false +UnloadAll() +-> m_assetImportService.ReimportAsset(path, importedAsset) +-> m_projectAssetIndex.RefreshFrom(m_assetImportService) +-> RememberResolvedPath(...) on success +``` + +具体成功路径要求： + +- 当前已绑定项目根 +- `path` 非空 +- 底层 [AssetImportService::ReimportAsset](../AssetImportService/ReimportAsset.md) 重导成功 + +## 关键副作用 + +### 它会先清空整个运行时缓存 + +即使你只重导一个资产，当前实现也会先执行 [UnloadAll](UnloadAll.md)。 + +这意味着它的设计目标不是“尽量保留现有内存对象”，而是“先把运行时状态清干净，再同步项目资产真相”。 + +### 它总会刷新 `ProjectAssetIndex` + +无论底层重导成功还是失败，当前实现都会执行： + +```cpp +m_projectAssetIndex.RefreshFrom(m_assetImportService); +``` + +这样做的好处是，项目资产查询 snapshot 不会停留在重导前的旧状态。 + +### 成功时会补记路径 + +如果底层返回的 `importedAsset` 里： + +- `assetGuid` 有效 +- `relativePath` 非空 + +当前实现会额外调用 `RememberResolvedPath(...)`，把成功重导出的路径关系立即记回本地 snapshot。 + +## 返回值 + +- `true` + - 单资产重导成功。 +- `false` + - 没有项目根、路径为空，或底层重导失败。 + +需要注意：返回 `false` 并不意味着运行时缓存被保留。因为 [UnloadAll](UnloadAll.md) 已经先发生了。 + +## 为什么它存在于 `ResourceManager` + +如果只暴露底层 `AssetImportService::ReimportAsset()`，上层调用者还得自己记得： + +- 先清理运行时缓存 +- 再重导 +- 再刷新 `ProjectAssetIndex` + +把这些顺序收口在一个高层 API 里，能避免编辑器工具和自动化脚本各自拼一套不同流程。 + +## 测试锚点 + +`tests/Core/Asset/test_resource_manager.cpp` 里的 +`ResourceManager_Test.ReimportProjectAssetBuildsArtifactForSelectedPath` +直接验证了当前语义：对选定路径执行重导后，会在项目 `Library` 中生成 artifact。 + +## 相关文档 + +- [ResourceManager](ResourceManager.md) +- [CanReimportProjectAsset](CanReimportProjectAsset.md) +- [ClearProjectLibraryCache](ClearProjectLibraryCache.md) +- [GetProjectAssetImportStatus](GetProjectAssetImportStatus.md) +- [AssetImportService::ReimportAsset](../AssetImportService/ReimportAsset.md) diff --git a/docs/api/XCEngine/Core/Asset/ResourceManager/ResourceManager.md b/docs/api/XCEngine/Core/Asset/ResourceManager/ResourceManager.md index 4c5fedfd..eb15b7db 100644 --- a/docs/api/XCEngine/Core/Asset/ResourceManager/ResourceManager.md +++ b/docs/api/XCEngine/Core/Asset/ResourceManager/ResourceManager.md @@ -6,18 +6,78 @@ **头文件**: `XCEngine/Core/Asset/ResourceManager.h` -**描述**: 运行时资源系统的中心入口，负责 loader 注册、项目资产服务桥接、同步/异步加载、句柄引用计数、in-flight 去重以及部分缓存管理。 +**描述**: 运行时资源系统的中心入口，负责 loader 注册、同步/异步加载、资源缓存与引用计数，同时桥接项目资产导入服务、查询快照和 Library 维护工具。 -## 角色概述 +## 概览 -`ResourceManager` 是当前资源模块里最接近“运行时入口”的类。它当前串起四层职责： +`ResourceManager` 是当前资源模块里最接近“运行时门面”的类。它把几类原本容易分散的职责收口到一个统一入口： -- loader 注册与查找 -- 项目资产服务桥接 -- 运行时加载与缓存 -- 句柄引用计数与异步入口 +1. loader 注册与资源类型分发。 +2. 同步/异步加载、in-flight 去重与运行时缓存。 +3. `ResourceHandle` 引用计数与部分缓存回收协作。 +4. 项目资产工具入口： + - [RefreshProjectAssets](RefreshProjectAssets.md) + - [CanReimportProjectAsset](CanReimportProjectAsset.md) + - [ReimportProjectAsset](ReimportProjectAsset.md) + - [ClearProjectLibraryCache](ClearProjectLibraryCache.md) + - [RebuildProjectAssetCache](RebuildProjectAssetCache.md) +5. 项目资产查询桥接： + - [TryGetAssetRef](TryGetAssetRef.md) + - [TryResolveAssetPath](TryResolveAssetPath.md) + - [GetProjectLibraryRoot](GetProjectLibraryRoot.md) + - [GetProjectAssetImportStatus](GetProjectAssetImportStatus.md) -其中项目资产桥接链路不是“直接调用 `AssetDatabase`”，而是： +## 设计理念 + +这层门面的意义，不只是“少传几个对象”。更重要的是它把运行时缓存、项目资产导入和查询快照的协同顺序固定下来。 + +如果上层自己分别操作： + +- `AssetImportService` +- `ProjectAssetIndex` +- 运行时缓存 + +就很容易在“重导了资产，但旧资源对象还在内存里”或“Library 清空了，但 lookup snapshot 没刷新”的半更新状态里出问题。 + +因此 `ResourceManager` 当前把这类高层命令做成完整流程，而不是裸转发。这和商业级引擎文档常见的做法一致：用户看到的是“重导项目资产”“清理 Library”“获取导入状态”这些完整工具入口，而不是一串需要自行拼接的底层步骤。 + +## 生命周期 + +### `Get()` / `Initialize()` + +- [Get](Get.md) 返回单例。 +- [Initialize](Initialize.md) 当前会进入内部 `EnsureInitialized()`。 +- `EnsureInitialized()` 只在首次调用时完成以下工作： + - 创建并初始化 `AsyncLoader` + - 注册 builtin `MaterialLoader`、`MeshLoader`、`ShaderLoader`、`TextureLoader` + - 初始化 [AssetImportService](../AssetImportService/AssetImportService.md) + +这意味着“资源系统已初始化”和“当前已绑定项目根”是两个不同概念：前者只保证加载器和服务对象就绪，后者要看 [SetResourceRoot](SetResourceRoot.md) 是否已绑定项目。 + +### `SetResourceRoot()` / `Shutdown()` + +- [SetResourceRoot](SetResourceRoot.md) 是进入/退出项目资产模式的总开关。 +- 绑定项目根时，它会： + - 初始化 `ResourceFileSystem` + - 让 `AssetImportService` 切换到新项目根 + - 立刻刷新 [ProjectAssetIndex](../ProjectAssetIndex/ProjectAssetIndex.md) +- 清空项目根时，它会： + - 清空 `AssetImportService` 的项目上下文 + - 关闭 `ResourceFileSystem` + - 重置 `ProjectAssetIndex` + +[Shutdown](Shutdown.md) 则会进一步： + +- [UnloadAll](UnloadAll.md) +- 关闭异步加载器 +- 关闭项目资产服务 +- 关闭 `ResourceFileSystem` +- 重置 `ProjectAssetIndex` +- 清空 in-flight 去重状态 + +## 项目资产工具链 + +这一组 API 是本轮最容易和“普通运行时加载”混淆的区域。它们都建立在下面这套分层上： ```text ResourceManager @@ -26,192 +86,152 @@ ResourceManager -> AssetDatabase ``` -这条分层决定了： - -- `SetResourceRoot()` 负责绑定项目根并初始化 snapshot -- `LoadResource()` 负责在真正加载前确保 artifact 就绪 -- `TryGetAssetRef()` / `TryResolveAssetPath()` 先走 snapshot，再视情况回退到服务层 - -## 生命周期 - -### `Initialize()` - -`Initialize()` 当前只转发到内部 `EnsureInitialized()`。 - -`EnsureInitialized()` 会： - -1. 创建 `AsyncLoader` 并调用 `Initialize(2)` -2. 注册 builtin `MaterialLoader`、`MeshLoader`、`ShaderLoader`、`TextureLoader` -3. 初始化 `AssetImportService` -4. 持有初始化后的 `AsyncLoader` - -因此当前自动注册的 builtin loader 一共四类，而项目资产链路真正是否生效仍取决于后续 `SetResourceRoot()` 是否绑定项目根。 - -### `Shutdown()` - -`Shutdown()` 会： - -- `UnloadAll()` -- 关闭并释放 `m_asyncLoader` -- `m_assetImportService.Shutdown()` -- `ResourceFileSystem::Get().Shutdown()` -- `m_projectAssetIndex.ResetProjectRoot()` -- 清空 `m_inFlightLoads` - -这不仅卸载运行时资源，也会彻底断开项目资产服务和本地 snapshot。 - -## 项目资产链路 - -### `SetResourceRoot(rootPath)` - -这不是一个单纯的路径前缀 setter。 - -当 `rootPath` 非空时，它会： - -- 写入 `m_resourceRoot` -- 初始化 `ResourceFileSystem` -- `m_assetImportService.SetProjectRoot(rootPath)` -- `m_projectAssetIndex.RefreshFrom(m_assetImportService)` - -当 `rootPath` 为空时，它会： - -- 清空 `AssetImportService` 的项目根 -- 关闭 `ResourceFileSystem` -- 重置 `ProjectAssetIndex` - -所以它实际上是“进入 / 退出项目资产模式”的总开关。 - ### `RefreshProjectAssets()` -这是显式重建项目资产 snapshot 的轻量入口： +[RefreshProjectAssets](RefreshProjectAssets.md) 是轻量维护入口： ```text -ResourceManager::RefreshProjectAssets --> AssetImportService::Refresh --> ProjectAssetIndex::RefreshFrom +AssetImportService::Refresh() +-> ProjectAssetIndex::RefreshFrom() ``` -它只在 `m_resourceRoot` 非空时生效，也不会直接重载已经在缓存里的运行时对象。 +它不会卸载当前已加载资源，也不会强制重建所有 artifact。适合在磁盘上的 `Assets/...` 变动后，让查询快照重新和当前项目状态对齐。 + +### `CanReimportProjectAsset()` + +[CanReimportProjectAsset](CanReimportProjectAsset.md) 是无副作用的前置探测： + +- 要求当前已经绑定项目根 +- 要求路径非空 +- 通过 [AssetImportService::TryGetImportableResourceType](../AssetImportService/TryGetImportableResourceType.md) 判断当前路径是否属于“可导入项目资产” + +它非常适合编辑器侧决定是否显示“Reimport”按钮，而不是直接拿来执行真正导入。 + +### `ReimportProjectAsset()` + +[ReimportProjectAsset](ReimportProjectAsset.md) 是高层“重导单个项目资产”命令。当前顺序固定为： + +```text +UnloadAll() +-> AssetImportService::ReimportAsset(path, importedAsset) +-> ProjectAssetIndex::RefreshFrom() +-> RememberResolvedPath(...) on success +``` + +最关键的现实语义是： + +- 它会先清掉整个运行时缓存，不只是目标资产。 +- 无论单资产重导成功与否，都会刷新 `ProjectAssetIndex`。 +- 成功时还会把 `assetGuid -> relativePath` 再记回本地快照。 + +这说明它不是“轻量刷新某个内存对象”，而是“先清理运行时态，再同步重导指定项目资产”的工具入口。 + +### `ClearProjectLibraryCache()` + +[ClearProjectLibraryCache](ClearProjectLibraryCache.md) 的真实顺序是： + +```text +UnloadAll() +-> AssetImportService::ClearLibraryCache() +-> ProjectAssetIndex::RefreshFrom() +``` + +它会清掉当前运行时资源对象和整个项目 `Library` 缓存，但不会自动全量重导资产。 ### `RebuildProjectAssetCache()` -这是更重的项目缓存重建入口： +[RebuildProjectAssetCache](RebuildProjectAssetCache.md) 是更重的组合命令： ```text -ResourceManager::RebuildProjectAssetCache --> UnloadAll --> AssetImportService::RebuildLibraryCache --> ProjectAssetIndex::RefreshFrom +UnloadAll() +-> AssetImportService::RebuildLibraryCache() +-> ProjectAssetIndex::RefreshFrom() ``` -它会清掉当前运行时资源缓存并重建整个 `Library` 目录。`tests/core/Asset/test_resource_manager.cpp` 里的 `ResourceManager_Test.RebuildProjectAssetCacheRefreshesLookupState` 已经覆盖了这条链路。 +测试 `ResourceManager_Test.RebuildProjectAssetCacheRefreshesLookupState` 直接约束了它的当前行为：重建 Library 后，项目资产查询状态仍应恢复可用。 -### `GetProjectLibraryRoot()` +### `GetProjectLibraryRoot()` / `GetProjectAssetImportStatus()` -直接返回当前项目 `Library` 根目录，底层转发到 `AssetImportService::GetLibraryRoot()`。这条入口主要用于测试和调试工具。 +- [GetProjectLibraryRoot](GetProjectLibraryRoot.md) 直接暴露当前项目 `Library` 根目录。 +- [GetProjectAssetImportStatus](GetProjectAssetImportStatus.md) 直接暴露最近一次项目资产导入状态。 + +这两个接口的意义在于：上层如果只持有 `ResourceManager`，仍然可以观察项目资产工具链的当前状态，而不必越层去拿 `AssetImportService`。 + +## 项目资产查询链 ### `TryGetAssetRef()` -当前直接委托给 `ProjectAssetIndex::TryGetAssetRef(...)`。真实行为是： +[TryGetAssetRef](TryGetAssetRef.md) 当前会优先命中 `ProjectAssetIndex` 本地 snapshot；miss 时才回退到 `AssetImportService`，必要时还会触发一次： -1. 先查本地 `path -> guid` snapshot -2. miss 时回退到 `AssetImportService::TryGetAssetRef(...)` -3. 如果仍失败，而且路径像项目资产路径，则触发一次： - - `importService.Refresh()` - - `ProjectAssetIndex::RefreshFrom(importService)` - - 再重试 -4. 成功后再通过 `TryGetPrimaryAssetPath()` 回填本地 snapshot +```text +Refresh() +-> RefreshFrom() +-> retry +``` -这就是当前 cache miss 刷新路径的真实位置。 +这就是当前“路径 -> `AssetRef`”发现链路的真实位置。 ### `TryResolveAssetPath()` -当前委托给 `ProjectAssetIndex::TryResolveAssetPath(...)`。行为和上面不完全对称： - -1. 先查本地 `guid -> path` snapshot -2. miss 时回退到 `AssetImportService::TryGetPrimaryAssetPath(...)` -3. 成功后记回 snapshot - -它不会像 `TryGetAssetRef()` 那样主动刷新整份 snapshot，而是只做一次数据库回退查询。 +[TryResolveAssetPath](TryResolveAssetPath.md) 也优先走 `ProjectAssetIndex` snapshot，但它的 fallback 比 `TryGetAssetRef()` 更轻：当前不会主动整份刷新 snapshot，而是只回退到 `AssetImportService::TryGetPrimaryAssetPath()` 做一次数据库查询。 ## 当前加载模型 ### 同步加载 -路径版模板 [Load](Load.md) 最终都会走内部 `LoadResource(path, type, settings)`。当前主流程是： +所有路径版 [Load](Load.md) 最终都会进入内部 `LoadResource(path, type, settings)`。当前关键流程是： -1. `EnsureInitialized()` -2. 用原始请求路径生成 `ResourceGUID` -3. 先查运行时缓存 -4. 做 in-flight 去重；相同 `guid + type` 的并发请求会共享一次真实加载 -5. 找到对应 `IResourceLoader` -6. 如果 `m_resourceRoot` 非空，尝试 `m_assetImportService.EnsureArtifact(path, type, resolvedAsset)` -7. 若 `artifactReady=true`： - - `m_projectAssetIndex.RememberResolvedPath(resolvedAsset.assetGuid, resolvedAsset.relativePath)` - - 把真正传给 loader 的 `loadPath` 切到 `resolvedAsset.runtimeLoadPath` -8. 调用 `loader->Load(loadPath, settings)` -9. 成功后把 `resource->m_path` 设回原始请求路径 -10. 写入缓存，并把 `guid -> 原始请求路径` 记入 `m_guidToPath` +1. 确保系统初始化。 +2. 用原始请求路径生成 `ResourceGUID`。 +3. 先查运行时缓存。 +4. 对相同 `guid + type` 做 in-flight 去重。 +5. 找到对应 `IResourceLoader`。 +6. 如果当前绑定了项目根，则尝试 `AssetImportService::EnsureArtifact(path, type, importedAsset)`。 +7. 如果拿到了可用 artifact： + - `ProjectAssetIndex::RememberResolvedPath(importedAsset.assetGuid, importedAsset.relativePath)` + - 把真正传给 loader 的 `loadPath` 切换到 `importedAsset.runtimeLoadPath` +8. 调用 `loader->Load(loadPath, settings)`。 +9. 成功后把资源对象对外暴露的 `m_path` 设回原始请求路径，并写入缓存与 `guid -> requestPath` 映射。 -这里有三个关键结论： +这条链路体现了一个很重要的设计点： -- 项目资产路径真正被 loader 读取的通常已经是 `Library/Artifacts/.../main.*` -- 资源对象对外暴露的 `m_path` 仍是原始请求路径 -- `Load(const AssetRef&)` 只是先用 `TryResolveAssetPath()` 还原成源路径，再复用这条普通路径加载链路 +- 运行时实际读取的通常是 `Library/Artifacts/.../main.*` +- 但资源对象对外暴露的身份路径仍然是用户请求的 source 路径 + +这和商业引擎常见的“作者路径稳定、运行时读取 artifact”模型是一致的。 ### 异步加载 -`LoadAsync()` 只把请求转发给 `AsyncLoader::Submit(...)`。 +[LoadAsync](LoadAsync.md) 当前把请求转发给 `AsyncLoader::Submit(...)`。后台线程会实际调用同一套 `LoadResource()` 逻辑，而完成回调要等 [UpdateAsyncLoads](UpdateAsyncLoads.md) 被主线程拉取分发。 -当前版本里： - -- `AsyncLoader` 会启动真实工作线程 -- 后台线程实际调用 `LoadResource()` -- 结果先进入完成队列 -- 只有调用 `UpdateAsyncLoads()` 时，回调才会分发到当前线程 - -因此它已经是可运行的异步加载路径，但仍更接近“后台加载 + 主线程轮询分发”模型，而不是全自动流式资源系统。 +因此它已经是可运行的异步路径，但仍然是“后台执行 + 主线程轮询分发”的模型，不是全自动事件流式系统。 ## 延迟场景加载开关 -`ScopedDeferredSceneLoad` 是 `BeginDeferredSceneLoad()` / `EndDeferredSceneLoad()` 的 RAII 包装器： - -- 构造时递增 `m_deferredSceneLoadDepth` -- 析构时在非空管理器上递减 -- [IsDeferredSceneLoadEnabled](IsDeferredSceneLoadEnabled.md) 通过原子计数判断是否开启 - -这条能力当前只表达“是否处于延迟场景加载区间”，不直接替代真正的异步恢复调度器。 - -## 引用计数与缓存现状 - -[ResourceHandle](../ResourceHandle/ResourceHandle.md) 的构造、拷贝、析构都会调用 `AddRef()` / `Release()`，因此 `ResourceManager` 记录的是“句柄引用数”。 - -当前实现仍有几个现实限制： - -- `Release()` 在引用数归零时只会调用 `m_cache.OnZeroRefCount(guid)`，这条行为链还没有完全打通成真实自动卸载 -- `ReloadResource()` 仍基本是 stub -- `UnloadUnused()` 仍是空实现 -- `m_resourceCache` / `m_memoryUsage` 和 `ResourceCache m_cache` 的状态并不总是严格同步 - -所以当前版本里，“自动卸载”“自动重载”和“缓存统计完全一致”都还不是成熟保证。 +[ScopedDeferredSceneLoad](ScopedDeferredSceneLoad.md) 是 [BeginDeferredSceneLoad](BeginDeferredSceneLoad.md) / [EndDeferredSceneLoad](EndDeferredSceneLoad.md) 的 RAII 包装。当前它只表达“是否处于延迟场景加载区间”，由 [IsDeferredSceneLoadEnabled](IsDeferredSceneLoadEnabled.md) 通过原子计数判断。 ## 测试锚点 -`tests/core/Asset/test_resource_manager.cpp` 当前直接覆盖了几条关键语义： +`tests/Core/Asset/test_resource_manager.cpp` 当前直接约束了几条关键语义： - `ConcurrentAsyncLoadsCoalesceSameMeshPath` - - 验证相同 `guid + type` 的并发请求会共享一次实际加载 + - 相同 `guid + type` 的并发请求会共享一次真实加载。 - `AssetLookupFallbackRefreshesSnapshotForNewProjectAsset` - - 验证 `TryGetAssetRef()` 会在 cache miss 时刷新 snapshot 再重试 + - `TryGetAssetRef()` 在 cache miss 时会尝试刷新项目资产 snapshot。 - `ResourceManager_Test.RebuildProjectAssetCacheRefreshesLookupState` - - 验证重建 `Library` 缓存后，查询状态仍能恢复 + - 重建 Library 后，项目资产查询状态仍能恢复。 +- `ResourceManager_Test.ReimportProjectAssetBuildsArtifactForSelectedPath` + - 显式重导单个项目资产后，会生成对应 artifact。 ## 当前实现限制 -- 自动注册的 builtin loader 只有 `Material`、`Mesh`、`Shader`、`Texture` -- `UnloadUnused()` 是空实现 -- `LoadAsync()` / `LoadGroup()` 仍要求主线程稳定调用 `UpdateAsyncLoads()` -- 项目资产 snapshot 的自动刷新只发生在少数显式入口，不是文件监听驱动的全局自动同步系统 +- 当前自动注册的 builtin loader 只有 `Material`、`Mesh`、`Shader`、`Texture`。 +- [UnloadUnused](UnloadUnused.md) 仍是空实现。 +- `Release()`、`ResourceCache` 与真实自动卸载策略还没有完全打通。 +- `ReloadResource()` 仍基本是 stub。 +- 项目资产工具入口都要求 `m_resourceRoot` 非空，否则直接失败。 +- [ReimportProjectAsset](ReimportProjectAsset.md)、[ClearProjectLibraryCache](ClearProjectLibraryCache.md)、[RebuildProjectAssetCache](RebuildProjectAssetCache.md) 都会先 [UnloadAll](UnloadAll.md)，当前没有更细粒度的运行时失效策略。 +- [GetProjectAssetImportStatus](GetProjectAssetImportStatus.md) 暴露的是“最近一次状态”，不是历史列表。 ## 相关方法 @@ -245,8 +265,12 @@ ResourceManager::RebuildProjectAssetCache - [GetResourcePaths](GetResourcePaths.md) - [UnloadGroup](UnloadGroup.md) - [RefreshProjectAssets](RefreshProjectAssets.md) +- [CanReimportProjectAsset](CanReimportProjectAsset.md) +- [ReimportProjectAsset](ReimportProjectAsset.md) +- [ClearProjectLibraryCache](ClearProjectLibraryCache.md) - [RebuildProjectAssetCache](RebuildProjectAssetCache.md) - [GetProjectLibraryRoot](GetProjectLibraryRoot.md) +- [GetProjectAssetImportStatus](GetProjectAssetImportStatus.md) - [TryGetAssetRef](TryGetAssetRef.md) - [TryResolveAssetPath](TryResolveAssetPath.md) - [ScopedDeferredSceneLoad](ScopedDeferredSceneLoad.md) diff --git a/docs/api/XCEngine/Core/Containers/Array/Back.md b/docs/api/XCEngine/Core/Containers/Array/Back.md index 1ea907bd..f8b6399f 100644 --- a/docs/api/XCEngine/Core/Containers/Array/Back.md +++ b/docs/api/XCEngine/Core/Containers/Array/Back.md @@ -1,42 +1,26 @@ # Array::Back -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Containers` -该方法在 `XCEngine/Core/Containers/Array.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。 +**类型**: `method` -## 重载 1: 声明 +**头文件**: `XCEngine/Core/Containers/Array.h` + +## 签名 ```cpp T& Back(); -``` - -**参数：** 无。 - -**返回：** `T&` - 返回值语义详见头文件声明。 - -## 重载 2: 声明 - -```cpp const T& Back() const; ``` -**参数：** 无。 +## 作用 -**返回：** `const T&` - 返回值语义详见头文件声明。 +返回 `m_data[m_size - 1]`。 -**示例：** +## 当前实现 -```cpp -#include - -void Example() { - XCEngine::Containers::Array object; - // 根据上下文补齐参数后调用 Array::Back(...)。 - (void)object; -} -``` +- 返回 `m_data[m_size - 1]`。 ## 相关文档 -- [返回类总览](Array.md) -- [返回模块目录](../Containers.md) +- [Array](Array.md) diff --git a/docs/api/XCEngine/Core/Containers/Array/Capacity.md b/docs/api/XCEngine/Core/Containers/Array/Capacity.md index 84d47bde..1dce5874 100644 --- a/docs/api/XCEngine/Core/Containers/Array/Capacity.md +++ b/docs/api/XCEngine/Core/Containers/Array/Capacity.md @@ -1,30 +1,25 @@ # Array::Capacity -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Containers` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Containers/Array.h` + +## 签名 ```cpp size_t Capacity() const; ``` -该方法声明于 `XCEngine/Core/Containers/Array.h`，当前页面用于固定 `Array` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `Capacity` 对应的公开操作。 -**返回：** `size_t` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Containers::Array object; - // 根据上下文补齐参数后调用 Array::Capacity(...)。 - (void)object; -} -``` +- 执行 `Capacity` 对应的公开操作。 ## 相关文档 -- [返回类总览](Array.md) -- [返回模块目录](../Containers.md) +- [Array](Array.md) diff --git a/docs/api/XCEngine/Core/Containers/Array/Clear.md b/docs/api/XCEngine/Core/Containers/Array/Clear.md index bb223168..94d6c0f3 100644 --- a/docs/api/XCEngine/Core/Containers/Array/Clear.md +++ b/docs/api/XCEngine/Core/Containers/Array/Clear.md @@ -1,30 +1,25 @@ # Array::Clear -清空内部数据。 +**命名空间**: `XCEngine::Containers` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Containers/Array.h` + +## 签名 ```cpp void Clear(); ``` -该方法声明于 `XCEngine/Core/Containers/Array.h`，当前页面用于固定 `Array` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `Clear` 对应的公开操作。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Containers::Array object; - // 根据上下文补齐参数后调用 Array::Clear(...)。 - (void)object; -} -``` +- 执行 `Clear` 对应的公开操作。 ## 相关文档 -- [返回类总览](Array.md) -- [返回模块目录](../Containers.md) +- [Array](Array.md) diff --git a/docs/api/XCEngine/Core/Containers/Array/Constructor.md b/docs/api/XCEngine/Core/Containers/Array/Constructor.md index ba847c06..17ab542b 100644 --- a/docs/api/XCEngine/Core/Containers/Array/Constructor.md +++ b/docs/api/XCEngine/Core/Containers/Array/Constructor.md @@ -1,86 +1,31 @@ # Array::Array() -构造对象。 +**命名空间**: `XCEngine::Containers` -该方法在 `XCEngine/Core/Containers/Array.h` 中提供了 6 个重载，当前页面统一汇总这些公开声明。 +**类型**: `method` -## 重载 1: 声明 +**头文件**: `XCEngine/Core/Containers/Array.h` + +## 签名 ```cpp Array() = default; -``` - -**参数：** 无。 - -**返回：** `void` - 无返回值。 - -## 重载 2: 声明 - -```cpp explicit Array(size_t capacity); -``` - -**参数：** -- `capacity` - 参数语义详见头文件声明。 - -**返回：** `void` - 无返回值。 - -## 重载 3: 声明 - -```cpp Array(size_t count, const T& value); -``` - -**参数：** -- `count` - 参数语义详见头文件声明。 -- `value` - 参数语义详见头文件声明。 - -**返回：** `void` - 无返回值。 - -## 重载 4: 声明 - -```cpp Array(std::initializer_list init); -``` - -**参数：** -- `init` - 参数语义详见头文件声明。 - -**返回：** `void` - 无返回值。 - -## 重载 5: 声明 - -```cpp Array(const Array& other); -``` - -**参数：** -- `other` - 参数语义详见头文件声明。 - -**返回：** `void` - 无返回值。 - -## 重载 6: 声明 - -```cpp Array(Array&& other) noexcept; ``` -**参数：** -- `other` - 参数语义详见头文件声明。 +## 作用 -**返回：** `void` - 无返回值。 +构造 `Array` 实例。 -**示例：** +## 当前实现 -```cpp -#include - -void Example() { - XCEngine::Containers::Array object; -} -``` +- 当前为默认构造实现。 +- 当前实现会调用 `DestructRange`。 ## 相关文档 -- [返回类总览](Array.md) -- [返回模块目录](../Containers.md) +- [Array](Array.md) diff --git a/docs/api/XCEngine/Core/Containers/Array/Data.md b/docs/api/XCEngine/Core/Containers/Array/Data.md index 0225e352..b2740399 100644 --- a/docs/api/XCEngine/Core/Containers/Array/Data.md +++ b/docs/api/XCEngine/Core/Containers/Array/Data.md @@ -1,42 +1,26 @@ # Array::Data -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Containers` -该方法在 `XCEngine/Core/Containers/Array.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。 +**类型**: `method` -## 重载 1: 声明 +**头文件**: `XCEngine/Core/Containers/Array.h` + +## 签名 ```cpp T* Data(); -``` - -**参数：** 无。 - -**返回：** `T*` - 返回值语义详见头文件声明。 - -## 重载 2: 声明 - -```cpp const T* Data() const; ``` -**参数：** 无。 +## 作用 -**返回：** `const T*` - 返回值语义详见头文件声明。 +返回 `m_data` 当前值。 -**示例：** +## 当前实现 -```cpp -#include - -void Example() { - XCEngine::Containers::Array object; - // 根据上下文补齐参数后调用 Array::Data(...)。 - (void)object; -} -``` +- 返回 `m_data` 当前值。 ## 相关文档 -- [返回类总览](Array.md) -- [返回模块目录](../Containers.md) +- [Array](Array.md) diff --git a/docs/api/XCEngine/Core/Containers/Array/Destructor.md b/docs/api/XCEngine/Core/Containers/Array/Destructor.md index 94d6083d..5056cedb 100644 --- a/docs/api/XCEngine/Core/Containers/Array/Destructor.md +++ b/docs/api/XCEngine/Core/Containers/Array/Destructor.md @@ -1,29 +1,25 @@ # Array::~Array() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::Containers` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Containers/Array.h` + +## 签名 ```cpp ~Array(); ``` -该方法声明于 `XCEngine/Core/Containers/Array.h`，当前页面用于固定 `Array` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +销毁 `Array` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Containers::Array object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 销毁 `Array` 实例。 ## 相关文档 -- [返回类总览](Array.md) -- [返回模块目录](../Containers.md) +- [Array](Array.md) diff --git a/docs/api/XCEngine/Core/Containers/Array/EmplaceBack.md b/docs/api/XCEngine/Core/Containers/Array/EmplaceBack.md index 9f2455da..052a90c5 100644 --- a/docs/api/XCEngine/Core/Containers/Array/EmplaceBack.md +++ b/docs/api/XCEngine/Core/Containers/Array/EmplaceBack.md @@ -1,31 +1,25 @@ # Array::EmplaceBack -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Containers` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Containers/Array.h` + +## 签名 ```cpp template T& EmplaceBack(Args&&... args); ``` -该方法声明于 `XCEngine/Core/Containers/Array.h`，当前页面用于固定 `Array` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `args` - 参数语义详见头文件声明。 +执行 `EmplaceBack` 对应的公开操作。 -**返回：** `template T&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Containers::Array object; - // 根据上下文补齐参数后调用 Array::EmplaceBack(...)。 - (void)object; -} -``` +- 执行 `EmplaceBack` 对应的公开操作。 ## 相关文档 -- [返回类总览](Array.md) -- [返回模块目录](../Containers.md) +- [Array](Array.md) diff --git a/docs/api/XCEngine/Core/Containers/Array/Empty.md b/docs/api/XCEngine/Core/Containers/Array/Empty.md index 6ae5ce50..e94b7786 100644 --- a/docs/api/XCEngine/Core/Containers/Array/Empty.md +++ b/docs/api/XCEngine/Core/Containers/Array/Empty.md @@ -1,30 +1,25 @@ # Array::Empty -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Containers` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Containers/Array.h` + +## 签名 ```cpp bool Empty() const; ``` -该方法声明于 `XCEngine/Core/Containers/Array.h`，当前页面用于固定 `Array` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `Empty` 对应的公开操作。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Containers::Array object; - // 根据上下文补齐参数后调用 Array::Empty(...)。 - (void)object; -} -``` +- 执行 `Empty` 对应的公开操作。 ## 相关文档 -- [返回类总览](Array.md) -- [返回模块目录](../Containers.md) +- [Array](Array.md) diff --git a/docs/api/XCEngine/Core/Containers/Array/Front.md b/docs/api/XCEngine/Core/Containers/Array/Front.md index a3419ee3..0541cf48 100644 --- a/docs/api/XCEngine/Core/Containers/Array/Front.md +++ b/docs/api/XCEngine/Core/Containers/Array/Front.md @@ -1,42 +1,26 @@ # Array::Front -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Containers` -该方法在 `XCEngine/Core/Containers/Array.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。 +**类型**: `method` -## 重载 1: 声明 +**头文件**: `XCEngine/Core/Containers/Array.h` + +## 签名 ```cpp T& Front(); -``` - -**参数：** 无。 - -**返回：** `T&` - 返回值语义详见头文件声明。 - -## 重载 2: 声明 - -```cpp const T& Front() const; ``` -**参数：** 无。 +## 作用 -**返回：** `const T&` - 返回值语义详见头文件声明。 +返回 `m_data[0]`。 -**示例：** +## 当前实现 -```cpp -#include - -void Example() { - XCEngine::Containers::Array object; - // 根据上下文补齐参数后调用 Array::Front(...)。 - (void)object; -} -``` +- 返回 `m_data[0]`。 ## 相关文档 -- [返回类总览](Array.md) -- [返回模块目录](../Containers.md) +- [Array](Array.md) diff --git a/docs/api/XCEngine/Core/Containers/Array/OperatorAssign.md b/docs/api/XCEngine/Core/Containers/Array/OperatorAssign.md index 8ede5db4..d2a62df7 100644 --- a/docs/api/XCEngine/Core/Containers/Array/OperatorAssign.md +++ b/docs/api/XCEngine/Core/Containers/Array/OperatorAssign.md @@ -1,44 +1,26 @@ # Array::operator= -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Containers` -该方法在 `XCEngine/Core/Containers/Array.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。 +**类型**: `method` -## 重载 1: 声明 +**头文件**: `XCEngine/Core/Containers/Array.h` + +## 签名 ```cpp Array& operator=(const Array& other); -``` - -**参数：** -- `other` - 参数语义详见头文件声明。 - -**返回：** `Array&` - 返回值语义详见头文件声明。 - -## 重载 2: 声明 - -```cpp Array& operator=(Array&& other) noexcept; ``` -**参数：** -- `other` - 参数语义详见头文件声明。 +## 作用 -**返回：** `Array&` - 返回值语义详见头文件声明。 +执行 `operator=` 对应的公开操作。 -**示例：** +## 当前实现 -```cpp -#include - -void Example() { - XCEngine::Containers::Array object; - // 根据上下文补齐参数后调用 Array::operator=(...)。 - (void)object; -} -``` +- 执行 `operator=` 对应的公开操作。 ## 相关文档 -- [返回类总览](Array.md) -- [返回模块目录](../Containers.md) +- [Array](Array.md) diff --git a/docs/api/XCEngine/Core/Containers/Array/OperatorSubscript.md b/docs/api/XCEngine/Core/Containers/Array/OperatorSubscript.md index 97aae2ef..48bfc049 100644 --- a/docs/api/XCEngine/Core/Containers/Array/OperatorSubscript.md +++ b/docs/api/XCEngine/Core/Containers/Array/OperatorSubscript.md @@ -1,44 +1,26 @@ # Array::operator[] -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Containers` -该方法在 `XCEngine/Core/Containers/Array.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。 +**类型**: `method` -## 重载 1: 声明 +**头文件**: `XCEngine/Core/Containers/Array.h` + +## 签名 ```cpp T& operator[](size_t index); -``` - -**参数：** -- `index` - 参数语义详见头文件声明。 - -**返回：** `T&` - 返回值语义详见头文件声明。 - -## 重载 2: 声明 - -```cpp const T& operator[](size_t index) const; ``` -**参数：** -- `index` - 参数语义详见头文件声明。 +## 作用 -**返回：** `const T&` - 返回值语义详见头文件声明。 +执行 `operator[]` 对应的公开操作。 -**示例：** +## 当前实现 -```cpp -#include - -void Example() { - XCEngine::Containers::Array object; - // 根据上下文补齐参数后调用 Array::operator[](...)。 - (void)object; -} -``` +- 执行 `operator[]` 对应的公开操作。 ## 相关文档 -- [返回类总览](Array.md) -- [返回模块目录](../Containers.md) +- [Array](Array.md) diff --git a/docs/api/XCEngine/Core/Containers/Array/PopBack.md b/docs/api/XCEngine/Core/Containers/Array/PopBack.md index bea7c133..76cfc060 100644 --- a/docs/api/XCEngine/Core/Containers/Array/PopBack.md +++ b/docs/api/XCEngine/Core/Containers/Array/PopBack.md @@ -1,30 +1,25 @@ # Array::PopBack -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Containers` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Containers/Array.h` + +## 签名 ```cpp void PopBack(); ``` -该方法声明于 `XCEngine/Core/Containers/Array.h`，当前页面用于固定 `Array` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `PopBack` 对应的公开操作。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Containers::Array object; - // 根据上下文补齐参数后调用 Array::PopBack(...)。 - (void)object; -} -``` +- 执行 `PopBack` 对应的公开操作。 ## 相关文档 -- [返回类总览](Array.md) -- [返回模块目录](../Containers.md) +- [Array](Array.md) diff --git a/docs/api/XCEngine/Core/Containers/Array/PushBack.md b/docs/api/XCEngine/Core/Containers/Array/PushBack.md index 7ee81759..bce3baa3 100644 --- a/docs/api/XCEngine/Core/Containers/Array/PushBack.md +++ b/docs/api/XCEngine/Core/Containers/Array/PushBack.md @@ -1,44 +1,26 @@ # Array::PushBack -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Containers` -该方法在 `XCEngine/Core/Containers/Array.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。 +**类型**: `method` -## 重载 1: 声明 +**头文件**: `XCEngine/Core/Containers/Array.h` + +## 签名 ```cpp void PushBack(const T& value); -``` - -**参数：** -- `value` - 参数语义详见头文件声明。 - -**返回：** `void` - 无返回值。 - -## 重载 2: 声明 - -```cpp void PushBack(T&& value); ``` -**参数：** -- `value` - 参数语义详见头文件声明。 +## 作用 -**返回：** `void` - 无返回值。 +执行 `PushBack` 对应的公开操作。 -**示例：** +## 当前实现 -```cpp -#include - -void Example() { - XCEngine::Containers::Array object; - // 根据上下文补齐参数后调用 Array::PushBack(...)。 - (void)object; -} -``` +- 执行 `PushBack` 对应的公开操作。 ## 相关文档 -- [返回类总览](Array.md) -- [返回模块目录](../Containers.md) +- [Array](Array.md) diff --git a/docs/api/XCEngine/Core/Containers/Array/Reserve.md b/docs/api/XCEngine/Core/Containers/Array/Reserve.md index 076ef14a..bde11cde 100644 --- a/docs/api/XCEngine/Core/Containers/Array/Reserve.md +++ b/docs/api/XCEngine/Core/Containers/Array/Reserve.md @@ -1,31 +1,25 @@ # Array::Reserve -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Containers` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Containers/Array.h` + +## 签名 ```cpp void Reserve(size_t capacity); ``` -该方法声明于 `XCEngine/Core/Containers/Array.h`，当前页面用于固定 `Array` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `capacity` - 参数语义详见头文件声明。 +执行 `Reserve` 对应的公开操作。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Containers::Array object; - // 根据上下文补齐参数后调用 Array::Reserve(...)。 - (void)object; -} -``` +- 执行 `Reserve` 对应的公开操作。 ## 相关文档 -- [返回类总览](Array.md) -- [返回模块目录](../Containers.md) +- [Array](Array.md) diff --git a/docs/api/XCEngine/Core/Containers/Array/Resize.md b/docs/api/XCEngine/Core/Containers/Array/Resize.md index ca88fe10..810e2c78 100644 --- a/docs/api/XCEngine/Core/Containers/Array/Resize.md +++ b/docs/api/XCEngine/Core/Containers/Array/Resize.md @@ -1,45 +1,26 @@ # Array::Resize -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Containers` -该方法在 `XCEngine/Core/Containers/Array.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。 +**类型**: `method` -## 重载 1: 声明 +**头文件**: `XCEngine/Core/Containers/Array.h` + +## 签名 ```cpp void Resize(size_t newSize); -``` - -**参数：** -- `newSize` - 参数语义详见头文件声明。 - -**返回：** `void` - 无返回值。 - -## 重载 2: 声明 - -```cpp void Resize(size_t newSize, const T& value); ``` -**参数：** -- `newSize` - 参数语义详见头文件声明。 -- `value` - 参数语义详见头文件声明。 +## 作用 -**返回：** `void` - 无返回值。 +执行 `Resize` 对应的公开操作。 -**示例：** +## 当前实现 -```cpp -#include - -void Example() { - XCEngine::Containers::Array object; - // 根据上下文补齐参数后调用 Array::Resize(...)。 - (void)object; -} -``` +- 执行 `Resize` 对应的公开操作。 ## 相关文档 -- [返回类总览](Array.md) -- [返回模块目录](../Containers.md) +- [Array](Array.md) diff --git a/docs/api/XCEngine/Core/Containers/Array/SetAllocator.md b/docs/api/XCEngine/Core/Containers/Array/SetAllocator.md index 745b5a8f..c7919342 100644 --- a/docs/api/XCEngine/Core/Containers/Array/SetAllocator.md +++ b/docs/api/XCEngine/Core/Containers/Array/SetAllocator.md @@ -1,31 +1,25 @@ # Array::SetAllocator -设置相关状态或配置。 +**命名空间**: `XCEngine::Containers` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Containers/Array.h` + +## 签名 ```cpp void SetAllocator(Memory::IAllocator* allocator); ``` -该方法声明于 `XCEngine/Core/Containers/Array.h`，当前页面用于固定 `Array` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `allocator` - 参数语义详见头文件声明。 +更新 `m_allocator`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Containers::Array object; - // 根据上下文补齐参数后调用 Array::SetAllocator(...)。 - (void)object; -} -``` +- 会更新 `m_allocator`。 ## 相关文档 -- [返回类总览](Array.md) -- [返回模块目录](../Containers.md) +- [Array](Array.md) diff --git a/docs/api/XCEngine/Core/Containers/Array/Size.md b/docs/api/XCEngine/Core/Containers/Array/Size.md index 7f3b9764..85c8e6a3 100644 --- a/docs/api/XCEngine/Core/Containers/Array/Size.md +++ b/docs/api/XCEngine/Core/Containers/Array/Size.md @@ -1,30 +1,25 @@ # Array::Size -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Containers` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Containers/Array.h` + +## 签名 ```cpp size_t Size() const; ``` -该方法声明于 `XCEngine/Core/Containers/Array.h`，当前页面用于固定 `Array` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `Size` 对应的公开操作。 -**返回：** `size_t` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Containers::Array object; - // 根据上下文补齐参数后调用 Array::Size(...)。 - (void)object; -} -``` +- 执行 `Size` 对应的公开操作。 ## 相关文档 -- [返回类总览](Array.md) -- [返回模块目录](../Containers.md) +- [Array](Array.md) diff --git a/docs/api/XCEngine/Core/Containers/Array/begin.md b/docs/api/XCEngine/Core/Containers/Array/begin.md index b8a31964..b8e6fa45 100644 --- a/docs/api/XCEngine/Core/Containers/Array/begin.md +++ b/docs/api/XCEngine/Core/Containers/Array/begin.md @@ -1,42 +1,26 @@ # Array::begin -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Containers` -该方法在 `XCEngine/Core/Containers/Array.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。 +**类型**: `method` -## 重载 1: 声明 +**头文件**: `XCEngine/Core/Containers/Array.h` + +## 签名 ```cpp Iterator begin(); -``` - -**参数：** 无。 - -**返回：** `Iterator` - 返回值语义详见头文件声明。 - -## 重载 2: 声明 - -```cpp ConstIterator begin() const; ``` -**参数：** 无。 +## 作用 -**返回：** `ConstIterator` - 返回值语义详见头文件声明。 +返回 `m_data` 当前值。 -**示例：** +## 当前实现 -```cpp -#include - -void Example() { - XCEngine::Containers::Array object; - // 根据上下文补齐参数后调用 Array::begin(...)。 - (void)object; -} -``` +- 返回 `m_data` 当前值。 ## 相关文档 -- [返回类总览](Array.md) -- [返回模块目录](../Containers.md) +- [Array](Array.md) diff --git a/docs/api/XCEngine/Core/Containers/Array/end.md b/docs/api/XCEngine/Core/Containers/Array/end.md index ec3fb093..2aecfa31 100644 --- a/docs/api/XCEngine/Core/Containers/Array/end.md +++ b/docs/api/XCEngine/Core/Containers/Array/end.md @@ -1,42 +1,26 @@ # Array::end -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Containers` -该方法在 `XCEngine/Core/Containers/Array.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。 +**类型**: `method` -## 重载 1: 声明 +**头文件**: `XCEngine/Core/Containers/Array.h` + +## 签名 ```cpp Iterator end(); -``` - -**参数：** 无。 - -**返回：** `Iterator` - 返回值语义详见头文件声明。 - -## 重载 2: 声明 - -```cpp ConstIterator end() const; ``` -**参数：** 无。 +## 作用 -**返回：** `ConstIterator` - 返回值语义详见头文件声明。 +返回 `m_data + m_size`。 -**示例：** +## 当前实现 -```cpp -#include - -void Example() { - XCEngine::Containers::Array object; - // 根据上下文补齐参数后调用 Array::end(...)。 - (void)object; -} -``` +- 返回 `m_data + m_size`。 ## 相关文档 -- [返回类总览](Array.md) -- [返回模块目录](../Containers.md) +- [Array](Array.md) diff --git a/docs/api/XCEngine/Core/Containers/HashMap/Clear.md b/docs/api/XCEngine/Core/Containers/HashMap/Clear.md index 4b62c62f..7bf5cc8f 100644 --- a/docs/api/XCEngine/Core/Containers/HashMap/Clear.md +++ b/docs/api/XCEngine/Core/Containers/HashMap/Clear.md @@ -1,30 +1,25 @@ # HashMap::Clear -清空内部数据。 +**命名空间**: `XCEngine::Containers` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Containers/HashMap.h` + +## 签名 ```cpp void Clear(); ``` -该方法声明于 `XCEngine/Core/Containers/HashMap.h`，当前页面用于固定 `HashMap` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `Clear` 对应的公开操作。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Containers::HashMap object; - // 根据上下文补齐参数后调用 HashMap::Clear(...)。 - (void)object; -} -``` +- 执行 `Clear` 对应的公开操作。 ## 相关文档 -- [返回类总览](HashMap.md) -- [返回模块目录](../Containers.md) +- [HashMap](HashMap.md) diff --git a/docs/api/XCEngine/Core/Containers/HashMap/Constructor.md b/docs/api/XCEngine/Core/Containers/HashMap/Constructor.md index 7a1d45da..e59efa85 100644 --- a/docs/api/XCEngine/Core/Containers/HashMap/Constructor.md +++ b/docs/api/XCEngine/Core/Containers/HashMap/Constructor.md @@ -1,64 +1,30 @@ # HashMap::HashMap() -构造对象。 +**命名空间**: `XCEngine::Containers` -该方法在 `XCEngine/Core/Containers/HashMap.h` 中提供了 4 个重载，当前页面统一汇总这些公开声明。 +**类型**: `method` -## 重载 1: 声明 +**头文件**: `XCEngine/Core/Containers/HashMap.h` + +## 签名 ```cpp HashMap(); -``` - -**参数：** 无。 - -**返回：** `void` - 无返回值。 - -## 重载 2: 声明 - -```cpp explicit HashMap(size_t bucketCount, Memory::IAllocator* allocator = nullptr); -``` - -**参数：** -- `bucketCount` - 参数语义详见头文件声明。 -- `allocator` - 参数语义详见头文件声明。 - -**返回：** `void` - 无返回值。 - -## 重载 3: 声明 - -```cpp HashMap(const HashMap& other); -``` - -**参数：** -- `other` - 参数语义详见头文件声明。 - -**返回：** `void` - 无返回值。 - -## 重载 4: 声明 - -```cpp HashMap(HashMap&& other) noexcept; ``` -**参数：** -- `other` - 参数语义详见头文件声明。 +## 作用 -**返回：** `void` - 无返回值。 +更新 `m_buckets`。 -**示例：** +## 当前实现 -```cpp -#include - -void Example() { - XCEngine::Containers::HashMap object; -} -``` +- 会更新 `m_buckets`。 +- 当前实现会调用 `Resize`。 +- 当前实现会调用 `Clear`。 ## 相关文档 -- [返回类总览](HashMap.md) -- [返回模块目录](../Containers.md) +- [HashMap](HashMap.md) diff --git a/docs/api/XCEngine/Core/Containers/HashMap/Contains.md b/docs/api/XCEngine/Core/Containers/HashMap/Contains.md index 7cc2efcf..c592b507 100644 --- a/docs/api/XCEngine/Core/Containers/HashMap/Contains.md +++ b/docs/api/XCEngine/Core/Containers/HashMap/Contains.md @@ -1,31 +1,25 @@ # HashMap::Contains -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Containers` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Containers/HashMap.h` + +## 签名 ```cpp bool Contains(const Key& key) const; ``` -该方法声明于 `XCEngine/Core/Containers/HashMap.h`，当前页面用于固定 `HashMap` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `key` - 参数语义详见头文件声明。 +执行 `Contains` 对应的公开操作。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Containers::HashMap object; - // 根据上下文补齐参数后调用 HashMap::Contains(...)。 - (void)object; -} -``` +- 执行 `Contains` 对应的公开操作。 ## 相关文档 -- [返回类总览](HashMap.md) -- [返回模块目录](../Containers.md) +- [HashMap](HashMap.md) diff --git a/docs/api/XCEngine/Core/Containers/HashMap/Destructor.md b/docs/api/XCEngine/Core/Containers/HashMap/Destructor.md index 818842e5..9d7954ac 100644 --- a/docs/api/XCEngine/Core/Containers/HashMap/Destructor.md +++ b/docs/api/XCEngine/Core/Containers/HashMap/Destructor.md @@ -1,29 +1,25 @@ # HashMap::~HashMap() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::Containers` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Containers/HashMap.h` + +## 签名 ```cpp ~HashMap(); ``` -该方法声明于 `XCEngine/Core/Containers/HashMap.h`，当前页面用于固定 `HashMap` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +销毁 `HashMap` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Containers::HashMap object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 销毁 `HashMap` 实例。 ## 相关文档 -- [返回类总览](HashMap.md) -- [返回模块目录](../Containers.md) +- [HashMap](HashMap.md) diff --git a/docs/api/XCEngine/Core/Containers/HashMap/Empty.md b/docs/api/XCEngine/Core/Containers/HashMap/Empty.md index a7781b5f..921b3dab 100644 --- a/docs/api/XCEngine/Core/Containers/HashMap/Empty.md +++ b/docs/api/XCEngine/Core/Containers/HashMap/Empty.md @@ -1,30 +1,25 @@ # HashMap::Empty -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Containers` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Containers/HashMap.h` + +## 签名 ```cpp bool Empty() const; ``` -该方法声明于 `XCEngine/Core/Containers/HashMap.h`，当前页面用于固定 `HashMap` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `Empty` 对应的公开操作。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Containers::HashMap object; - // 根据上下文补齐参数后调用 HashMap::Empty(...)。 - (void)object; -} -``` +- 执行 `Empty` 对应的公开操作。 ## 相关文档 -- [返回类总览](HashMap.md) -- [返回模块目录](../Containers.md) +- [HashMap](HashMap.md) diff --git a/docs/api/XCEngine/Core/Containers/HashMap/Erase.md b/docs/api/XCEngine/Core/Containers/HashMap/Erase.md index 3dbd44a1..2acc7a45 100644 --- a/docs/api/XCEngine/Core/Containers/HashMap/Erase.md +++ b/docs/api/XCEngine/Core/Containers/HashMap/Erase.md @@ -1,31 +1,25 @@ # HashMap::Erase -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Containers` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Containers/HashMap.h` + +## 签名 ```cpp bool Erase(const Key& key); ``` -该方法声明于 `XCEngine/Core/Containers/HashMap.h`，当前页面用于固定 `HashMap` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `key` - 参数语义详见头文件声明。 +执行 `Erase` 对应的公开操作。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Containers::HashMap object; - // 根据上下文补齐参数后调用 HashMap::Erase(...)。 - (void)object; -} -``` +- 执行 `Erase` 对应的公开操作。 ## 相关文档 -- [返回类总览](HashMap.md) -- [返回模块目录](../Containers.md) +- [HashMap](HashMap.md) diff --git a/docs/api/XCEngine/Core/Containers/HashMap/Find.md b/docs/api/XCEngine/Core/Containers/HashMap/Find.md index 758541c4..48b79ed5 100644 --- a/docs/api/XCEngine/Core/Containers/HashMap/Find.md +++ b/docs/api/XCEngine/Core/Containers/HashMap/Find.md @@ -1,44 +1,26 @@ # HashMap::Find -查找并返回匹配对象。 +**命名空间**: `XCEngine::Containers` -该方法在 `XCEngine/Core/Containers/HashMap.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。 +**类型**: `method` -## 重载 1: 声明 +**头文件**: `XCEngine/Core/Containers/HashMap.h` + +## 签名 ```cpp Value* Find(const Key& key); -``` - -**参数：** -- `key` - 参数语义详见头文件声明。 - -**返回：** `Value*` - 返回值语义详见头文件声明。 - -## 重载 2: 声明 - -```cpp const Value* Find(const Key& key) const; ``` -**参数：** -- `key` - 参数语义详见头文件声明。 +## 作用 -**返回：** `const Value*` - 返回值语义详见头文件声明。 +执行 `Find` 对应的公开操作。 -**示例：** +## 当前实现 -```cpp -#include - -void Example() { - XCEngine::Containers::HashMap object; - // 根据上下文补齐参数后调用 HashMap::Find(...)。 - (void)object; -} -``` +- 执行 `Find` 对应的公开操作。 ## 相关文档 -- [返回类总览](HashMap.md) -- [返回模块目录](../Containers.md) +- [HashMap](HashMap.md) diff --git a/docs/api/XCEngine/Core/Containers/HashMap/Insert.md b/docs/api/XCEngine/Core/Containers/HashMap/Insert.md index c90b168a..9e253bfc 100644 --- a/docs/api/XCEngine/Core/Containers/HashMap/Insert.md +++ b/docs/api/XCEngine/Core/Containers/HashMap/Insert.md @@ -1,57 +1,27 @@ # HashMap::Insert -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Containers` -该方法在 `XCEngine/Core/Containers/HashMap.h` 中提供了 3 个重载，当前页面统一汇总这些公开声明。 +**类型**: `method` -## 重载 1: 声明 +**头文件**: `XCEngine/Core/Containers/HashMap.h` + +## 签名 ```cpp bool Insert(const Key& key, const Value& value); -``` - -**参数：** -- `key` - 参数语义详见头文件声明。 -- `value` - 参数语义详见头文件声明。 - -**返回：** `bool` - 返回值语义详见头文件声明。 - -## 重载 2: 声明 - -```cpp bool Insert(const Key& key, Value&& value); -``` - -**参数：** -- `key` - 参数语义详见头文件声明。 -- `value` - 参数语义详见头文件声明。 - -**返回：** `bool` - 返回值语义详见头文件声明。 - -## 重载 3: 声明 - -```cpp bool Insert(Pair&& pair); ``` -**参数：** -- `pair` - 参数语义详见头文件声明。 +## 作用 -**返回：** `bool` - 返回值语义详见头文件声明。 +执行 `Insert` 对应的公开操作。 -**示例：** +## 当前实现 -```cpp -#include - -void Example() { - XCEngine::Containers::HashMap object; - // 根据上下文补齐参数后调用 HashMap::Insert(...)。 - (void)object; -} -``` +- 执行 `Insert` 对应的公开操作。 ## 相关文档 -- [返回类总览](HashMap.md) -- [返回模块目录](../Containers.md) +- [HashMap](HashMap.md) diff --git a/docs/api/XCEngine/Core/Containers/HashMap/OperatorAssign.md b/docs/api/XCEngine/Core/Containers/HashMap/OperatorAssign.md index a35791d3..0b3d483b 100644 --- a/docs/api/XCEngine/Core/Containers/HashMap/OperatorAssign.md +++ b/docs/api/XCEngine/Core/Containers/HashMap/OperatorAssign.md @@ -1,44 +1,26 @@ # HashMap::operator= -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Containers` -该方法在 `XCEngine/Core/Containers/HashMap.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。 +**类型**: `method` -## 重载 1: 声明 +**头文件**: `XCEngine/Core/Containers/HashMap.h` + +## 签名 ```cpp HashMap& operator=(const HashMap& other); -``` - -**参数：** -- `other` - 参数语义详见头文件声明。 - -**返回：** `HashMap&` - 返回值语义详见头文件声明。 - -## 重载 2: 声明 - -```cpp HashMap& operator=(HashMap&& other) noexcept; ``` -**参数：** -- `other` - 参数语义详见头文件声明。 +## 作用 -**返回：** `HashMap&` - 返回值语义详见头文件声明。 +执行 `operator=` 对应的公开操作。 -**示例：** +## 当前实现 -```cpp -#include - -void Example() { - XCEngine::Containers::HashMap object; - // 根据上下文补齐参数后调用 HashMap::operator=(...)。 - (void)object; -} -``` +- 执行 `operator=` 对应的公开操作。 ## 相关文档 -- [返回类总览](HashMap.md) -- [返回模块目录](../Containers.md) +- [HashMap](HashMap.md) diff --git a/docs/api/XCEngine/Core/Containers/HashMap/OperatorSubscript.md b/docs/api/XCEngine/Core/Containers/HashMap/OperatorSubscript.md index 10d6ad70..58f610d2 100644 --- a/docs/api/XCEngine/Core/Containers/HashMap/OperatorSubscript.md +++ b/docs/api/XCEngine/Core/Containers/HashMap/OperatorSubscript.md @@ -1,31 +1,25 @@ # HashMap::operator[] -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Containers` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Containers/HashMap.h` + +## 签名 ```cpp Value& operator[](const Key& key); ``` -该方法声明于 `XCEngine/Core/Containers/HashMap.h`，当前页面用于固定 `HashMap` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `key` - 参数语义详见头文件声明。 +执行 `operator[]` 对应的公开操作。 -**返回：** `Value&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Containers::HashMap object; - // 根据上下文补齐参数后调用 HashMap::operator[](...)。 - (void)object; -} -``` +- 执行 `operator[]` 对应的公开操作。 ## 相关文档 -- [返回类总览](HashMap.md) -- [返回模块目录](../Containers.md) +- [HashMap](HashMap.md) diff --git a/docs/api/XCEngine/Core/Containers/HashMap/SetAllocator.md b/docs/api/XCEngine/Core/Containers/HashMap/SetAllocator.md index d0c34b00..e5796883 100644 --- a/docs/api/XCEngine/Core/Containers/HashMap/SetAllocator.md +++ b/docs/api/XCEngine/Core/Containers/HashMap/SetAllocator.md @@ -1,31 +1,25 @@ # HashMap::SetAllocator -设置相关状态或配置。 +**命名空间**: `XCEngine::Containers` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Containers/HashMap.h` + +## 签名 ```cpp void SetAllocator(Memory::IAllocator* allocator); ``` -该方法声明于 `XCEngine/Core/Containers/HashMap.h`，当前页面用于固定 `HashMap` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `allocator` - 参数语义详见头文件声明。 +更新 `m_allocator`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Containers::HashMap object; - // 根据上下文补齐参数后调用 HashMap::SetAllocator(...)。 - (void)object; -} -``` +- 会更新 `m_allocator`。 ## 相关文档 -- [返回类总览](HashMap.md) -- [返回模块目录](../Containers.md) +- [HashMap](HashMap.md) diff --git a/docs/api/XCEngine/Core/Containers/HashMap/Size.md b/docs/api/XCEngine/Core/Containers/HashMap/Size.md index 918f41ef..52ac7c62 100644 --- a/docs/api/XCEngine/Core/Containers/HashMap/Size.md +++ b/docs/api/XCEngine/Core/Containers/HashMap/Size.md @@ -1,30 +1,25 @@ # HashMap::Size -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Containers` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Containers/HashMap.h` + +## 签名 ```cpp size_t Size() const; ``` -该方法声明于 `XCEngine/Core/Containers/HashMap.h`，当前页面用于固定 `HashMap` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `Size` 对应的公开操作。 -**返回：** `size_t` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Containers::HashMap object; - // 根据上下文补齐参数后调用 HashMap::Size(...)。 - (void)object; -} -``` +- 执行 `Size` 对应的公开操作。 ## 相关文档 -- [返回类总览](HashMap.md) -- [返回模块目录](../Containers.md) +- [HashMap](HashMap.md) diff --git a/docs/api/XCEngine/Core/Containers/HashMap/begin.md b/docs/api/XCEngine/Core/Containers/HashMap/begin.md index eff408b6..fab7d02e 100644 --- a/docs/api/XCEngine/Core/Containers/HashMap/begin.md +++ b/docs/api/XCEngine/Core/Containers/HashMap/begin.md @@ -1,42 +1,26 @@ # HashMap::begin -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Containers` -该方法在 `XCEngine/Core/Containers/HashMap.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。 +**类型**: `method` -## 重载 1: 声明 +**头文件**: `XCEngine/Core/Containers/HashMap.h` + +## 签名 ```cpp Iterator begin(); -``` - -**参数：** 无。 - -**返回：** `Iterator` - 返回值语义详见头文件声明。 - -## 重载 2: 声明 - -```cpp ConstIterator begin() const; ``` -**参数：** 无。 +## 作用 -**返回：** `ConstIterator` - 返回值语义详见头文件声明。 +返回 `m_buckets[0].pairs.begin()` 的结果。 -**示例：** +## 当前实现 -```cpp -#include - -void Example() { - XCEngine::Containers::HashMap object; - // 根据上下文补齐参数后调用 HashMap::begin(...)。 - (void)object; -} -``` +- 当前实现会调用 `begin`。 ## 相关文档 -- [返回类总览](HashMap.md) -- [返回模块目录](../Containers.md) +- [HashMap](HashMap.md) diff --git a/docs/api/XCEngine/Core/Containers/HashMap/end.md b/docs/api/XCEngine/Core/Containers/HashMap/end.md index 802b687e..e56bbc3b 100644 --- a/docs/api/XCEngine/Core/Containers/HashMap/end.md +++ b/docs/api/XCEngine/Core/Containers/HashMap/end.md @@ -1,42 +1,29 @@ # HashMap::end -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Containers` -该方法在 `XCEngine/Core/Containers/HashMap.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。 +**类型**: `method` -## 重载 1: 声明 +**头文件**: `XCEngine/Core/Containers/HashMap.h` + +## 签名 ```cpp Iterator end(); -``` - -**参数：** 无。 - -**返回：** `Iterator` - 返回值语义详见头文件声明。 - -## 重载 2: 声明 - -```cpp ConstIterator end() const; ``` -**参数：** 无。 +## 作用 -**返回：** `ConstIterator` - 返回值语义详见头文件声明。 +执行 `end`、`Iterator` 协同流程。 -**示例：** +## 当前实现 -```cpp -#include - -void Example() { - XCEngine::Containers::HashMap object; - // 根据上下文补齐参数后调用 HashMap::end(...)。 - (void)object; -} -``` +- 当前实现会调用 `end`、`Iterator`。 +- 包含条件分支，并可能提前返回。 +- 包含 `nullptr` 相关分支。 +- 当前实现会调用 `end`、`ConstIterator`。 ## 相关文档 -- [返回类总览](HashMap.md) -- [返回模块目录](../Containers.md) +- [HashMap](HashMap.md) diff --git a/docs/api/XCEngine/Core/Containers/String/CStr.md b/docs/api/XCEngine/Core/Containers/String/CStr.md index a4effcac..8b1d11c9 100644 --- a/docs/api/XCEngine/Core/Containers/String/CStr.md +++ b/docs/api/XCEngine/Core/Containers/String/CStr.md @@ -1,30 +1,25 @@ # String::CStr -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Containers` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Containers/String.h` + +## 签名 ```cpp const char* CStr() const; ``` -该方法声明于 `XCEngine/Core/Containers/String.h`，当前页面用于固定 `String` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `CStr` 对应的公开操作。 -**返回：** `const char*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Containers::String object; - // 根据上下文补齐参数后调用 String::CStr(...)。 - (void)object; -} -``` +- 具体定义位于 `engine/src/Core/Containers/String.cpp`。 ## 相关文档 -- [返回类总览](String.md) -- [返回模块目录](../Containers.md) +- [String](String.md) diff --git a/docs/api/XCEngine/Core/Containers/String/Capacity.md b/docs/api/XCEngine/Core/Containers/String/Capacity.md index dcd9123b..dad22260 100644 --- a/docs/api/XCEngine/Core/Containers/String/Capacity.md +++ b/docs/api/XCEngine/Core/Containers/String/Capacity.md @@ -1,30 +1,25 @@ # String::Capacity -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Containers` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Containers/String.h` + +## 签名 ```cpp SizeType Capacity() const; ``` -该方法声明于 `XCEngine/Core/Containers/String.h`，当前页面用于固定 `String` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `Capacity` 对应的公开操作。 -**返回：** `SizeType` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Containers::String object; - // 根据上下文补齐参数后调用 String::Capacity(...)。 - (void)object; -} -``` +- 具体定义位于 `engine/src/Core/Containers/String.cpp`。 ## 相关文档 -- [返回类总览](String.md) -- [返回模块目录](../Containers.md) +- [String](String.md) diff --git a/docs/api/XCEngine/Core/Containers/String/Clear.md b/docs/api/XCEngine/Core/Containers/String/Clear.md index 51ad34c2..5162255f 100644 --- a/docs/api/XCEngine/Core/Containers/String/Clear.md +++ b/docs/api/XCEngine/Core/Containers/String/Clear.md @@ -1,30 +1,25 @@ # String::Clear -清空内部数据。 +**命名空间**: `XCEngine::Containers` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Containers/String.h` + +## 签名 ```cpp void Clear(); ``` -该方法声明于 `XCEngine/Core/Containers/String.h`，当前页面用于固定 `String` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_length`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Containers::String object; - // 根据上下文补齐参数后调用 String::Clear(...)。 - (void)object; -} -``` +- 会更新 `m_length`。 ## 相关文档 -- [返回类总览](String.md) -- [返回模块目录](../Containers.md) +- [String](String.md) diff --git a/docs/api/XCEngine/Core/Containers/String/Constructor.md b/docs/api/XCEngine/Core/Containers/String/Constructor.md index e3949a5c..f9eb2514 100644 --- a/docs/api/XCEngine/Core/Containers/String/Constructor.md +++ b/docs/api/XCEngine/Core/Containers/String/Constructor.md @@ -1,75 +1,33 @@ # String::String() -构造对象。 +**命名空间**: `XCEngine::Containers` -该方法在 `XCEngine/Core/Containers/String.h` 中提供了 5 个重载，当前页面统一汇总这些公开声明。 +**类型**: `method` -## 重载 1: 声明 +**头文件**: `XCEngine/Core/Containers/String.h` + +## 签名 ```cpp String(); -``` - -**参数：** 无。 - -**返回：** `void` - 无返回值。 - -## 重载 2: 声明 - -```cpp String(const char* str); -``` - -**参数：** -- `str` - 参数语义详见头文件声明。 - -**返回：** `void` - 无返回值。 - -## 重载 3: 声明 - -```cpp String(const char* str, SizeType len); -``` - -**参数：** -- `str` - 参数语义详见头文件声明。 -- `len` - 参数语义详见头文件声明。 - -**返回：** `void` - 无返回值。 - -## 重载 4: 声明 - -```cpp String(const String& other); -``` - -**参数：** -- `other` - 参数语义详见头文件声明。 - -**返回：** `void` - 无返回值。 - -## 重载 5: 声明 - -```cpp String(String&& other) noexcept; ``` -**参数：** -- `other` - 参数语义详见头文件声明。 +## 作用 -**返回：** `void` - 无返回值。 +执行 `strlen`、`memcpy` 协同流程。 -**示例：** +## 当前实现 -```cpp -#include - -void Example() { - XCEngine::Containers::String object; -} -``` +- 会更新 `m_length`、`m_capacity`、`m_data`。 +- 当前实现会调用 `strlen`、`memcpy`。 +- 当前实现会调用 `memcpy`。 +- 会更新 `m_data`、`m_length`、`m_capacity`。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](String.md) -- [返回模块目录](../Containers.md) +- [String](String.md) diff --git a/docs/api/XCEngine/Core/Containers/String/Destructor.md b/docs/api/XCEngine/Core/Containers/String/Destructor.md index 4e8e9651..ceea20ee 100644 --- a/docs/api/XCEngine/Core/Containers/String/Destructor.md +++ b/docs/api/XCEngine/Core/Containers/String/Destructor.md @@ -1,29 +1,25 @@ # String::~String() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::Containers` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Containers/String.h` + +## 签名 ```cpp ~String(); ``` -该方法声明于 `XCEngine/Core/Containers/String.h`，当前页面用于固定 `String` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `Deallocate(...)` 相关流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Containers::String object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 当前实现会调用 `Deallocate`。 ## 相关文档 -- [返回类总览](String.md) -- [返回模块目录](../Containers.md) +- [String](String.md) diff --git a/docs/api/XCEngine/Core/Containers/String/Empty.md b/docs/api/XCEngine/Core/Containers/String/Empty.md index 12a2576b..43a4958e 100644 --- a/docs/api/XCEngine/Core/Containers/String/Empty.md +++ b/docs/api/XCEngine/Core/Containers/String/Empty.md @@ -1,30 +1,25 @@ # String::Empty -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Containers` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Containers/String.h` + +## 签名 ```cpp bool Empty() const; ``` -该方法声明于 `XCEngine/Core/Containers/String.h`，当前页面用于固定 `String` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `Empty` 对应的公开操作。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Containers::String object; - // 根据上下文补齐参数后调用 String::Empty(...)。 - (void)object; -} -``` +- 具体定义位于 `engine/src/Core/Containers/String.cpp`。 ## 相关文档 -- [返回类总览](String.md) -- [返回模块目录](../Containers.md) +- [String](String.md) diff --git a/docs/api/XCEngine/Core/Containers/String/EndsWith.md b/docs/api/XCEngine/Core/Containers/String/EndsWith.md index d018978e..b3578860 100644 --- a/docs/api/XCEngine/Core/Containers/String/EndsWith.md +++ b/docs/api/XCEngine/Core/Containers/String/EndsWith.md @@ -1,44 +1,26 @@ # String::EndsWith -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Containers` -该方法在 `XCEngine/Core/Containers/String.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。 +**类型**: `method` -## 重载 1: 声明 +**头文件**: `XCEngine/Core/Containers/String.h` + +## 签名 ```cpp bool EndsWith(const String& suffix) const; -``` - -**参数：** -- `suffix` - 参数语义详见头文件声明。 - -**返回：** `bool` - 返回值语义详见头文件声明。 - -## 重载 2: 声明 - -```cpp bool EndsWith(const char* suffix) const; ``` -**参数：** -- `suffix` - 参数语义详见头文件声明。 +## 作用 -**返回：** `bool` - 返回值语义详见头文件声明。 +执行 `EndsWith` 对应的公开操作。 -**示例：** +## 当前实现 -```cpp -#include - -void Example() { - XCEngine::Containers::String object; - // 根据上下文补齐参数后调用 String::EndsWith(...)。 - (void)object; -} -``` +- 具体定义位于 `engine/src/Core/Containers/String.cpp`。 ## 相关文档 -- [返回类总览](String.md) -- [返回模块目录](../Containers.md) +- [String](String.md) diff --git a/docs/api/XCEngine/Core/Containers/String/Find.md b/docs/api/XCEngine/Core/Containers/String/Find.md index c2278d0f..a4e5f5e8 100644 --- a/docs/api/XCEngine/Core/Containers/String/Find.md +++ b/docs/api/XCEngine/Core/Containers/String/Find.md @@ -1,32 +1,25 @@ # String::Find -查找并返回匹配对象。 +**命名空间**: `XCEngine::Containers` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Containers/String.h` + +## 签名 ```cpp SizeType Find(const char* str, SizeType pos = 0) const; ``` -该方法声明于 `XCEngine/Core/Containers/String.h`，当前页面用于固定 `String` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `str` - 参数语义详见头文件声明。 -- `pos` - 参数语义详见头文件声明。 +执行 `Find` 对应的公开操作。 -**返回：** `SizeType` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Containers::String object; - // 根据上下文补齐参数后调用 String::Find(...)。 - (void)object; -} -``` +- 具体定义位于 `engine/src/Core/Containers/String.cpp`。 ## 相关文档 -- [返回类总览](String.md) -- [返回模块目录](../Containers.md) +- [String](String.md) diff --git a/docs/api/XCEngine/Core/Containers/String/Length.md b/docs/api/XCEngine/Core/Containers/String/Length.md index cfd531fa..2e27cb61 100644 --- a/docs/api/XCEngine/Core/Containers/String/Length.md +++ b/docs/api/XCEngine/Core/Containers/String/Length.md @@ -1,30 +1,25 @@ # String::Length -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Containers` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Containers/String.h` + +## 签名 ```cpp SizeType Length() const; ``` -该方法声明于 `XCEngine/Core/Containers/String.h`，当前页面用于固定 `String` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `Length` 对应的公开操作。 -**返回：** `SizeType` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Containers::String object; - // 根据上下文补齐参数后调用 String::Length(...)。 - (void)object; -} -``` +- 具体定义位于 `engine/src/Core/Containers/String.cpp`。 ## 相关文档 -- [返回类总览](String.md) -- [返回模块目录](../Containers.md) +- [String](String.md) diff --git a/docs/api/XCEngine/Core/Containers/String/OperatorAssign.md b/docs/api/XCEngine/Core/Containers/String/OperatorAssign.md index 60286cea..da6c8c51 100644 --- a/docs/api/XCEngine/Core/Containers/String/OperatorAssign.md +++ b/docs/api/XCEngine/Core/Containers/String/OperatorAssign.md @@ -1,55 +1,30 @@ # String::operator= -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Containers` -该方法在 `XCEngine/Core/Containers/String.h` 中提供了 3 个重载，当前页面统一汇总这些公开声明。 +**类型**: `method` -## 重载 1: 声明 +**头文件**: `XCEngine/Core/Containers/String.h` + +## 签名 ```cpp String& operator=(const String& other); -``` - -**参数：** -- `other` - 参数语义详见头文件声明。 - -**返回：** `String&` - 返回值语义详见头文件声明。 - -## 重载 2: 声明 - -```cpp String& operator=(String&& other) noexcept; -``` - -**参数：** -- `other` - 参数语义详见头文件声明。 - -**返回：** `String&` - 返回值语义详见头文件声明。 - -## 重载 3: 声明 - -```cpp String& operator=(const char* str); ``` -**参数：** -- `str` - 参数语义详见头文件声明。 +## 作用 -**返回：** `String&` - 返回值语义详见头文件声明。 +更新 `m_length`。 -**示例：** +## 当前实现 -```cpp -#include - -void Example() { - XCEngine::Containers::String object; - // 根据上下文补齐参数后调用 String::operator=(...)。 - (void)object; -} -``` +- 会更新 `m_length`。 +- 当前实现会调用 `Deallocate`、`Allocate`、`memcpy`。 +- 包含条件分支，并可能提前返回。 +- 当前实现会调用 `strlen`、`Deallocate`、`Allocate`、`memcpy`、`Clear`。 ## 相关文档 -- [返回类总览](String.md) -- [返回模块目录](../Containers.md) +- [String](String.md) diff --git a/docs/api/XCEngine/Core/Containers/String/OperatorPlusAssign.md b/docs/api/XCEngine/Core/Containers/String/OperatorPlusAssign.md index 851cf194..0a7fbf5c 100644 --- a/docs/api/XCEngine/Core/Containers/String/OperatorPlusAssign.md +++ b/docs/api/XCEngine/Core/Containers/String/OperatorPlusAssign.md @@ -1,55 +1,30 @@ # String::operator+= -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Containers` -该方法在 `XCEngine/Core/Containers/String.h` 中提供了 3 个重载，当前页面统一汇总这些公开声明。 +**类型**: `method` -## 重载 1: 声明 +**头文件**: `XCEngine/Core/Containers/String.h` + +## 签名 ```cpp String& operator+=(const String& other); -``` - -**参数：** -- `other` - 参数语义详见头文件声明。 - -**返回：** `String&` - 返回值语义详见头文件声明。 - -## 重载 2: 声明 - -```cpp String& operator+=(const char* str); -``` - -**参数：** -- `str` - 参数语义详见头文件声明。 - -**返回：** `String&` - 返回值语义详见头文件声明。 - -## 重载 3: 声明 - -```cpp String& operator+=(char c); ``` -**参数：** -- `c` - 参数语义详见头文件声明。 +## 作用 -**返回：** `String&` - 返回值语义详见头文件声明。 +执行 `memcpy` 协同流程。 -**示例：** +## 当前实现 -```cpp -#include - -void Example() { - XCEngine::Containers::String object; - // 根据上下文补齐参数后调用 String::operator+=(...)。 - (void)object; -} -``` +- 会更新 `m_data`、`m_capacity`、`m_length`。 +- 当前实现会调用 `memcpy`。 +- 包含条件分支，并可能提前返回。 +- 当前实现会调用 `strlen`、`memcpy`。 ## 相关文档 -- [返回类总览](String.md) -- [返回模块目录](../Containers.md) +- [String](String.md) diff --git a/docs/api/XCEngine/Core/Containers/String/OperatorSubscript.md b/docs/api/XCEngine/Core/Containers/String/OperatorSubscript.md index 5c2fa132..8328740d 100644 --- a/docs/api/XCEngine/Core/Containers/String/OperatorSubscript.md +++ b/docs/api/XCEngine/Core/Containers/String/OperatorSubscript.md @@ -1,44 +1,26 @@ # String::operator[] -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Containers` -该方法在 `XCEngine/Core/Containers/String.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。 +**类型**: `method` -## 重载 1: 声明 +**头文件**: `XCEngine/Core/Containers/String.h` + +## 签名 ```cpp char& operator[](SizeType index); -``` - -**参数：** -- `index` - 参数语义详见头文件声明。 - -**返回：** `char&` - 返回值语义详见头文件声明。 - -## 重载 2: 声明 - -```cpp const char& operator[](SizeType index) const; ``` -**参数：** -- `index` - 参数语义详见头文件声明。 +## 作用 -**返回：** `const char&` - 返回值语义详见头文件声明。 +返回 `m_data[index]`。 -**示例：** +## 当前实现 -```cpp -#include - -void Example() { - XCEngine::Containers::String object; - // 根据上下文补齐参数后调用 String::operator[](...)。 - (void)object; -} -``` +- 返回 `m_data[index]`。 ## 相关文档 -- [返回类总览](String.md) -- [返回模块目录](../Containers.md) +- [String](String.md) diff --git a/docs/api/XCEngine/Core/Containers/String/Reserve.md b/docs/api/XCEngine/Core/Containers/String/Reserve.md index 5144b9dd..44b430b8 100644 --- a/docs/api/XCEngine/Core/Containers/String/Reserve.md +++ b/docs/api/XCEngine/Core/Containers/String/Reserve.md @@ -1,31 +1,26 @@ # String::Reserve -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Containers` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Containers/String.h` + +## 签名 ```cpp void Reserve(SizeType capacity); ``` -该方法声明于 `XCEngine/Core/Containers/String.h`，当前页面用于固定 `String` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `capacity` - 参数语义详见头文件声明。 +执行 `memcpy(...)` 相关流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Containers::String object; - // 根据上下文补齐参数后调用 String::Reserve(...)。 - (void)object; -} -``` +- 会更新 `m_data`、`m_capacity`。 +- 当前实现会调用 `memcpy`。 ## 相关文档 -- [返回类总览](String.md) -- [返回模块目录](../Containers.md) +- [String](String.md) diff --git a/docs/api/XCEngine/Core/Containers/String/Resize.md b/docs/api/XCEngine/Core/Containers/String/Resize.md index f1297c11..5eba9252 100644 --- a/docs/api/XCEngine/Core/Containers/String/Resize.md +++ b/docs/api/XCEngine/Core/Containers/String/Resize.md @@ -1,45 +1,28 @@ # String::Resize -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Containers` -该方法在 `XCEngine/Core/Containers/String.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。 +**类型**: `method` -## 重载 1: 声明 +**头文件**: `XCEngine/Core/Containers/String.h` + +## 签名 ```cpp void Resize(SizeType newSize); -``` - -**参数：** -- `newSize` - 参数语义详见头文件声明。 - -**返回：** `void` - 无返回值。 - -## 重载 2: 声明 - -```cpp void Resize(SizeType newSize, char fillChar); ``` -**参数：** -- `newSize` - 参数语义详见头文件声明。 -- `fillChar` - 参数语义详见头文件声明。 +## 作用 -**返回：** `void` - 无返回值。 +执行 `Resize(...)` 相关流程。 -**示例：** +## 当前实现 -```cpp -#include - -void Example() { - XCEngine::Containers::String object; - // 根据上下文补齐参数后调用 String::Resize(...)。 - (void)object; -} -``` +- 当前实现会调用 `Resize`。 +- 会更新 `m_length`。 +- 当前实现会调用 `Reserve`。 ## 相关文档 -- [返回类总览](String.md) -- [返回模块目录](../Containers.md) +- [String](String.md) diff --git a/docs/api/XCEngine/Core/Containers/String/StartsWith.md b/docs/api/XCEngine/Core/Containers/String/StartsWith.md index 547e50fe..ed7d6426 100644 --- a/docs/api/XCEngine/Core/Containers/String/StartsWith.md +++ b/docs/api/XCEngine/Core/Containers/String/StartsWith.md @@ -1,44 +1,26 @@ # String::StartsWith -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Containers` -该方法在 `XCEngine/Core/Containers/String.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。 +**类型**: `method` -## 重载 1: 声明 +**头文件**: `XCEngine/Core/Containers/String.h` + +## 签名 ```cpp bool StartsWith(const String& prefix) const; -``` - -**参数：** -- `prefix` - 参数语义详见头文件声明。 - -**返回：** `bool` - 返回值语义详见头文件声明。 - -## 重载 2: 声明 - -```cpp bool StartsWith(const char* prefix) const; ``` -**参数：** -- `prefix` - 参数语义详见头文件声明。 +## 作用 -**返回：** `bool` - 返回值语义详见头文件声明。 +执行 `StartsWith` 对应的公开操作。 -**示例：** +## 当前实现 -```cpp -#include - -void Example() { - XCEngine::Containers::String object; - // 根据上下文补齐参数后调用 String::StartsWith(...)。 - (void)object; -} -``` +- 具体定义位于 `engine/src/Core/Containers/String.cpp`。 ## 相关文档 -- [返回类总览](String.md) -- [返回模块目录](../Containers.md) +- [String](String.md) diff --git a/docs/api/XCEngine/Core/Containers/String/Substring.md b/docs/api/XCEngine/Core/Containers/String/Substring.md index 2ec74835..e195a849 100644 --- a/docs/api/XCEngine/Core/Containers/String/Substring.md +++ b/docs/api/XCEngine/Core/Containers/String/Substring.md @@ -1,32 +1,25 @@ # String::Substring -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Containers` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Containers/String.h` + +## 签名 ```cpp String Substring(SizeType pos, SizeType len = npos) const; ``` -该方法声明于 `XCEngine/Core/Containers/String.h`，当前页面用于固定 `String` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `pos` - 参数语义详见头文件声明。 -- `len` - 参数语义详见头文件声明。 +执行 `Substring` 对应的公开操作。 -**返回：** `String` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Containers::String object; - // 根据上下文补齐参数后调用 String::Substring(...)。 - (void)object; -} -``` +- 具体定义位于 `engine/src/Core/Containers/String.cpp`。 ## 相关文档 -- [返回类总览](String.md) -- [返回模块目录](../Containers.md) +- [String](String.md) diff --git a/docs/api/XCEngine/Core/Containers/String/ToLower.md b/docs/api/XCEngine/Core/Containers/String/ToLower.md index cb6b87e6..8c943378 100644 --- a/docs/api/XCEngine/Core/Containers/String/ToLower.md +++ b/docs/api/XCEngine/Core/Containers/String/ToLower.md @@ -1,30 +1,25 @@ # String::ToLower -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Containers` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Containers/String.h` + +## 签名 ```cpp String ToLower() const; ``` -该方法声明于 `XCEngine/Core/Containers/String.h`，当前页面用于固定 `String` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `ToLower` 对应的公开操作。 -**返回：** `String` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Containers::String object; - // 根据上下文补齐参数后调用 String::ToLower(...)。 - (void)object; -} -``` +- 具体定义位于 `engine/src/Core/Containers/String.cpp`。 ## 相关文档 -- [返回类总览](String.md) -- [返回模块目录](../Containers.md) +- [String](String.md) diff --git a/docs/api/XCEngine/Core/Containers/String/ToUpper.md b/docs/api/XCEngine/Core/Containers/String/ToUpper.md index 2047002c..cc1ddbfe 100644 --- a/docs/api/XCEngine/Core/Containers/String/ToUpper.md +++ b/docs/api/XCEngine/Core/Containers/String/ToUpper.md @@ -1,30 +1,25 @@ # String::ToUpper -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Containers` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Containers/String.h` + +## 签名 ```cpp String ToUpper() const; ``` -该方法声明于 `XCEngine/Core/Containers/String.h`，当前页面用于固定 `String` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `ToUpper` 对应的公开操作。 -**返回：** `String` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Containers::String object; - // 根据上下文补齐参数后调用 String::ToUpper(...)。 - (void)object; -} -``` +- 具体定义位于 `engine/src/Core/Containers/String.cpp`。 ## 相关文档 -- [返回类总览](String.md) -- [返回模块目录](../Containers.md) +- [String](String.md) diff --git a/docs/api/XCEngine/Core/Containers/String/Trim.md b/docs/api/XCEngine/Core/Containers/String/Trim.md index 303806e4..306a3bfa 100644 --- a/docs/api/XCEngine/Core/Containers/String/Trim.md +++ b/docs/api/XCEngine/Core/Containers/String/Trim.md @@ -1,30 +1,25 @@ # String::Trim -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Containers` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Containers/String.h` + +## 签名 ```cpp String Trim() const; ``` -该方法声明于 `XCEngine/Core/Containers/String.h`，当前页面用于固定 `String` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `Trim` 对应的公开操作。 -**返回：** `String` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Containers::String object; - // 根据上下文补齐参数后调用 String::Trim(...)。 - (void)object; -} -``` +- 具体定义位于 `engine/src/Core/Containers/String.cpp`。 ## 相关文档 -- [返回类总览](String.md) -- [返回模块目录](../Containers.md) +- [String](String.md) diff --git a/docs/api/XCEngine/Core/Event/Clear.md b/docs/api/XCEngine/Core/Event/Clear.md index 954bb250..eab22c56 100644 --- a/docs/api/XCEngine/Core/Event/Clear.md +++ b/docs/api/XCEngine/Core/Event/Clear.md @@ -1,30 +1,26 @@ # Event::Clear -清空内部数据。 +**命名空间**: `XCEngine::Core` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Event.h` + +## 签名 ```cpp void Clear(); ``` -该方法声明于 `XCEngine/Core/Event.h`，当前页面用于固定 `Event` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_listeners`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Core::Event object; - // 根据上下文补齐参数后调用 Event::Clear(...)。 - (void)object; -} -``` +- 会更新 `m_listeners`。 +- 当前实现会调用 `lock`、`clear`。 ## 相关文档 -- [返回类总览](Event.md) -- [返回模块目录](../Core.md) +- [Event](Event.md) diff --git a/docs/api/XCEngine/Core/Event/Event.md b/docs/api/XCEngine/Core/Event/Event.md index f2615abe..bbdbc5ef 100644 --- a/docs/api/XCEngine/Core/Event/Event.md +++ b/docs/api/XCEngine/Core/Event/Event.md @@ -35,7 +35,7 @@ - 监听器以 `(uint64_t id, Callback)` 形式保存在 `m_listeners` 中 - ID 由 `m_nextId` 递增生成 -- `tests/core/test_core.cpp` 已验证不同订阅返回的 ID 不同 +- `tests/Core/test_core.cpp` 已验证不同订阅返回的 ID 不同 ### 2. `Unsubscribe()` 是延迟取消订阅 @@ -87,7 +87,7 @@ ## 测试覆盖 -`tests/core/test_core.cpp` 已覆盖： +`tests/Core/test_core.cpp` 已覆盖： - 订阅与回调调用 - 带参数事件 diff --git a/docs/api/XCEngine/Core/Event/Invoke.md b/docs/api/XCEngine/Core/Event/Invoke.md index fb5fd55d..54d6a467 100644 --- a/docs/api/XCEngine/Core/Event/Invoke.md +++ b/docs/api/XCEngine/Core/Event/Invoke.md @@ -1,31 +1,26 @@ # Event::Invoke -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Core` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Event.h` + +## 签名 ```cpp void Invoke(Args... args); ``` -该方法声明于 `XCEngine/Core/Event.h`，当前页面用于固定 `Event` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `args` - 参数语义详见头文件声明。 +执行 `lock`、`empty`、`erase` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Core::Event object; - // 根据上下文补齐参数后调用 Event::Invoke(...)。 - (void)object; -} -``` +- 当前实现会调用 `lock`、`empty`、`erase`、`remove_if`、`begin`。 +- 包含条件分支，并可能提前返回。 ## 相关文档 -- [返回类总览](Event.md) -- [返回模块目录](../Core.md) +- [Event](Event.md) diff --git a/docs/api/XCEngine/Core/Event/ProcessUnsubscribes.md b/docs/api/XCEngine/Core/Event/ProcessUnsubscribes.md index b9de9dd9..050c8523 100644 --- a/docs/api/XCEngine/Core/Event/ProcessUnsubscribes.md +++ b/docs/api/XCEngine/Core/Event/ProcessUnsubscribes.md @@ -1,30 +1,26 @@ # Event::ProcessUnsubscribes -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Core` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Event.h` + +## 签名 ```cpp void ProcessUnsubscribes(); ``` -该方法声明于 `XCEngine/Core/Event.h`，当前页面用于固定 `Event` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `pair.first == id`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Core::Event object; - // 根据上下文补齐参数后调用 Event::ProcessUnsubscribes(...)。 - (void)object; -} -``` +- 会更新 `m_listeners`、`m_pendingUnsubscribes`。 +- 当前实现会调用 `lock`、`erase`、`remove_if`、`begin`、`end`。 ## 相关文档 -- [返回类总览](Event.md) -- [返回模块目录](../Core.md) +- [Event](Event.md) diff --git a/docs/api/XCEngine/Core/Event/Subscribe.md b/docs/api/XCEngine/Core/Event/Subscribe.md index 03f3bff3..a2359581 100644 --- a/docs/api/XCEngine/Core/Event/Subscribe.md +++ b/docs/api/XCEngine/Core/Event/Subscribe.md @@ -1,31 +1,26 @@ # Event::Subscribe -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Core` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Event.h` + +## 签名 ```cpp uint64_t Subscribe(Callback callback); ``` -该方法声明于 `XCEngine/Core/Event.h`，当前页面用于固定 `Event` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `callback` - 参数语义详见头文件声明。 +更新 `m_listeners`。 -**返回：** `uint64_t` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Core::Event object; - // 根据上下文补齐参数后调用 Event::Subscribe(...)。 - (void)object; -} -``` +- 会更新 `m_listeners`。 +- 当前实现会调用 `lock`、`emplace_back`、`move`。 ## 相关文档 -- [返回类总览](Event.md) -- [返回模块目录](../Core.md) +- [Event](Event.md) diff --git a/docs/api/XCEngine/Core/Event/Unsubscribe.md b/docs/api/XCEngine/Core/Event/Unsubscribe.md index a715aa85..5ab8217a 100644 --- a/docs/api/XCEngine/Core/Event/Unsubscribe.md +++ b/docs/api/XCEngine/Core/Event/Unsubscribe.md @@ -1,31 +1,26 @@ # Event::Unsubscribe -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Core` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Event.h` + +## 签名 ```cpp void Unsubscribe(uint64_t id); ``` -该方法声明于 `XCEngine/Core/Event.h`，当前页面用于固定 `Event` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `id` - 参数语义详见头文件声明。 +更新 `m_pendingUnsubscribes`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Core::Event object; - // 根据上下文补齐参数后调用 Event::Unsubscribe(...)。 - (void)object; -} -``` +- 会更新 `m_pendingUnsubscribes`。 +- 当前实现会调用 `lock`、`push_back`。 ## 相关文档 -- [返回类总览](Event.md) -- [返回模块目录](../Core.md) +- [Event](Event.md) diff --git a/docs/api/XCEngine/Core/Event/begin.md b/docs/api/XCEngine/Core/Event/begin.md index 67586a41..df307114 100644 --- a/docs/api/XCEngine/Core/Event/begin.md +++ b/docs/api/XCEngine/Core/Event/begin.md @@ -1,30 +1,26 @@ # Event::begin -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Core` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Event.h` + +## 签名 ```cpp Iterator begin(); ``` -该方法声明于 `XCEngine/Core/Event.h`，当前页面用于固定 `Event` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_listeners`。 -**返回：** `Iterator` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Core::Event object; - // 根据上下文补齐参数后调用 Event::begin(...)。 - (void)object; -} -``` +- 会更新 `m_listeners`。 +- 当前实现会调用 `begin`。 ## 相关文档 -- [返回类总览](Event.md) -- [返回模块目录](../Core.md) +- [Event](Event.md) diff --git a/docs/api/XCEngine/Core/Event/end.md b/docs/api/XCEngine/Core/Event/end.md index c7cd4a9d..a474ab64 100644 --- a/docs/api/XCEngine/Core/Event/end.md +++ b/docs/api/XCEngine/Core/Event/end.md @@ -1,30 +1,26 @@ # Event::end -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Core` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Event.h` + +## 签名 ```cpp Iterator end(); ``` -该方法声明于 `XCEngine/Core/Event.h`，当前页面用于固定 `Event` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_listeners`。 -**返回：** `Iterator` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Core::Event object; - // 根据上下文补齐参数后调用 Event::end(...)。 - (void)object; -} -``` +- 会更新 `m_listeners`。 +- 当前实现会调用 `end`。 ## 相关文档 -- [返回类总览](Event.md) -- [返回模块目录](../Core.md) +- [Event](Event.md) diff --git a/docs/api/XCEngine/Core/FileWriter/Close.md b/docs/api/XCEngine/Core/FileWriter/Close.md index d7581567..5d679bba 100644 --- a/docs/api/XCEngine/Core/FileWriter/Close.md +++ b/docs/api/XCEngine/Core/FileWriter/Close.md @@ -1,30 +1,27 @@ # FileWriter::Close -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Core` + +**类型**: `method` + +**头文件**: `XCEngine/Core/FileWriter.h` + +## 签名 ```cpp void Close(); ``` -该方法声明于 `XCEngine/Core/FileWriter.h`，当前页面用于固定 `FileWriter` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_file`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Core::FileWriter object; - // 根据上下文补齐参数后调用 FileWriter::Close(...)。 - (void)object; -} -``` +- 会更新 `m_file`。 +- 当前实现会调用 `fclose`。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](FileWriter.md) -- [返回模块目录](../Core.md) +- [FileWriter](FileWriter.md) diff --git a/docs/api/XCEngine/Core/FileWriter/Constructor.md b/docs/api/XCEngine/Core/FileWriter/Constructor.md index c710ff2e..28970965 100644 --- a/docs/api/XCEngine/Core/FileWriter/Constructor.md +++ b/docs/api/XCEngine/Core/FileWriter/Constructor.md @@ -1,42 +1,27 @@ # FileWriter::FileWriter() -构造对象。 +**命名空间**: `XCEngine::Core` -该方法在 `XCEngine/Core/FileWriter.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。 +**类型**: `method` -## 重载 1: 声明 +**头文件**: `XCEngine/Core/FileWriter.h` + +## 签名 ```cpp FileWriter(); -``` - -**参数：** 无。 - -**返回：** `void` - 无返回值。 - -## 重载 2: 声明 - -```cpp FileWriter(const char* filePath, bool append = false); ``` -**参数：** -- `filePath` - 参数语义详见头文件声明。 -- `append` - 参数语义详见头文件声明。 +## 作用 -**返回：** `void` - 无返回值。 +构造 `FileWriter` 实例。 -**示例：** +## 当前实现 -```cpp -#include - -void Example() { - XCEngine::Core::FileWriter object; -} -``` +- 当前为默认构造实现。 +- 当前实现会调用 `Open`。 ## 相关文档 -- [返回类总览](FileWriter.md) -- [返回模块目录](../Core.md) +- [FileWriter](FileWriter.md) diff --git a/docs/api/XCEngine/Core/FileWriter/Destructor.md b/docs/api/XCEngine/Core/FileWriter/Destructor.md index 85ed9103..58d3e911 100644 --- a/docs/api/XCEngine/Core/FileWriter/Destructor.md +++ b/docs/api/XCEngine/Core/FileWriter/Destructor.md @@ -1,29 +1,25 @@ # FileWriter::~FileWriter() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::Core` + +**类型**: `method` + +**头文件**: `XCEngine/Core/FileWriter.h` + +## 签名 ```cpp ~FileWriter(); ``` -该方法声明于 `XCEngine/Core/FileWriter.h`，当前页面用于固定 `FileWriter` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `Close(...)` 相关流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Core::FileWriter object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 当前实现会调用 `Close`。 ## 相关文档 -- [返回类总览](FileWriter.md) -- [返回模块目录](../Core.md) +- [FileWriter](FileWriter.md) diff --git a/docs/api/XCEngine/Core/FileWriter/Flush.md b/docs/api/XCEngine/Core/FileWriter/Flush.md index 3d981b90..b23f0804 100644 --- a/docs/api/XCEngine/Core/FileWriter/Flush.md +++ b/docs/api/XCEngine/Core/FileWriter/Flush.md @@ -1,30 +1,26 @@ # FileWriter::Flush -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Core` + +**类型**: `method` + +**头文件**: `XCEngine/Core/FileWriter.h` + +## 签名 ```cpp bool Flush(); ``` -该方法声明于 `XCEngine/Core/FileWriter.h`，当前页面用于固定 `FileWriter` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `fflush(...)` 相关流程。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Core::FileWriter object; - // 根据上下文补齐参数后调用 FileWriter::Flush(...)。 - (void)object; -} -``` +- 当前实现会调用 `fflush`。 +- 包含条件分支，并可能提前返回。 ## 相关文档 -- [返回类总览](FileWriter.md) -- [返回模块目录](../Core.md) +- [FileWriter](FileWriter.md) diff --git a/docs/api/XCEngine/Core/FileWriter/IsOpen.md b/docs/api/XCEngine/Core/FileWriter/IsOpen.md index f4c48e9f..48b1335b 100644 --- a/docs/api/XCEngine/Core/FileWriter/IsOpen.md +++ b/docs/api/XCEngine/Core/FileWriter/IsOpen.md @@ -1,30 +1,25 @@ # FileWriter::IsOpen -查询当前状态。 +**命名空间**: `XCEngine::Core` + +**类型**: `method` + +**头文件**: `XCEngine/Core/FileWriter.h` + +## 签名 ```cpp bool IsOpen() const; ``` -该方法声明于 `XCEngine/Core/FileWriter.h`，当前页面用于固定 `FileWriter` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_file != nullptr`。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Core::FileWriter object; - // 根据上下文补齐参数后调用 FileWriter::IsOpen(...)。 - (void)object; -} -``` +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](FileWriter.md) -- [返回模块目录](../Core.md) +- [FileWriter](FileWriter.md) diff --git a/docs/api/XCEngine/Core/FileWriter/Open.md b/docs/api/XCEngine/Core/FileWriter/Open.md index 85361073..c0c804e0 100644 --- a/docs/api/XCEngine/Core/FileWriter/Open.md +++ b/docs/api/XCEngine/Core/FileWriter/Open.md @@ -1,32 +1,27 @@ # FileWriter::Open -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Core` + +**类型**: `method` + +**头文件**: `XCEngine/Core/FileWriter.h` + +## 签名 ```cpp bool Open(const char* filePath, bool append = false); ``` -该方法声明于 `XCEngine/Core/FileWriter.h`，当前页面用于固定 `FileWriter` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `filePath` - 参数语义详见头文件声明。 -- `append` - 参数语义详见头文件声明。 +更新 `m_file`。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Core::FileWriter object; - // 根据上下文补齐参数后调用 FileWriter::Open(...)。 - (void)object; -} -``` +- 会更新 `m_file`。 +- 当前实现会调用 `Close`、`fopen`。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](FileWriter.md) -- [返回模块目录](../Core.md) +- [FileWriter](FileWriter.md) diff --git a/docs/api/XCEngine/Core/FileWriter/Write.md b/docs/api/XCEngine/Core/FileWriter/Write.md index f6035ec1..9f210b98 100644 --- a/docs/api/XCEngine/Core/FileWriter/Write.md +++ b/docs/api/XCEngine/Core/FileWriter/Write.md @@ -1,45 +1,28 @@ # FileWriter::Write -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Core` -该方法在 `XCEngine/Core/FileWriter.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。 +**类型**: `method` -## 重载 1: 声明 +**头文件**: `XCEngine/Core/FileWriter.h` + +## 签名 ```cpp bool Write(const char* data, size_t length); -``` - -**参数：** -- `data` - 参数语义详见头文件声明。 -- `length` - 参数语义详见头文件声明。 - -**返回：** `bool` - 返回值语义详见头文件声明。 - -## 重载 2: 声明 - -```cpp bool Write(const Containers::String& str); ``` -**参数：** -- `str` - 参数语义详见头文件声明。 +## 作用 -**返回：** `bool` - 返回值语义详见头文件声明。 +执行 `fwrite(...)` 相关流程。 -**示例：** +## 当前实现 -```cpp -#include - -void Example() { - XCEngine::Core::FileWriter object; - // 根据上下文补齐参数后调用 FileWriter::Write(...)。 - (void)object; -} -``` +- 当前实现会调用 `fwrite`。 +- 包含条件分支，并可能提前返回。 +- 当前实现会调用 `Write`、`CStr`、`Length`。 ## 相关文档 -- [返回类总览](FileWriter.md) -- [返回模块目录](../Core.md) +- [FileWriter](FileWriter.md) diff --git a/docs/api/XCEngine/Core/IO/FileArchive/Close.md b/docs/api/XCEngine/Core/IO/FileArchive/Close.md index 4274a3c0..6bd185e0 100644 --- a/docs/api/XCEngine/Core/IO/FileArchive/Close.md +++ b/docs/api/XCEngine/Core/IO/FileArchive/Close.md @@ -1,30 +1,25 @@ # FileArchive::Close -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/IO/FileArchive.h` + +## 签名 ```cpp void Close() override; ``` -该方法声明于 `XCEngine/Core/IO/FileArchive.h`，当前页面用于固定 `FileArchive` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行该公开方法对应的当前实现。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::FileArchive object; - // 根据上下文补齐参数后调用 FileArchive::Close(...)。 - (void)object; -} -``` +- 会更新 `m_archivePath`、`m_isValid`。 ## 相关文档 -- [返回类总览](FileArchive.md) -- [返回模块目录](../IO.md) +- [FileArchive](FileArchive.md) diff --git a/docs/api/XCEngine/Core/IO/FileArchive/Constructor.md b/docs/api/XCEngine/Core/IO/FileArchive/Constructor.md index c94d3356..f63d0e3e 100644 --- a/docs/api/XCEngine/Core/IO/FileArchive/Constructor.md +++ b/docs/api/XCEngine/Core/IO/FileArchive/Constructor.md @@ -1,28 +1,25 @@ # FileArchive::FileArchive() -构造对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/IO/FileArchive.h` + +## 签名 ```cpp FileArchive(); ``` -该方法声明于 `XCEngine/Core/IO/FileArchive.h`，当前页面用于固定 `FileArchive` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +构造 `FileArchive` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::FileArchive object; -} -``` +- 当前为默认构造实现。 ## 相关文档 -- [返回类总览](FileArchive.md) -- [返回模块目录](../IO.md) +- [FileArchive](FileArchive.md) diff --git a/docs/api/XCEngine/Core/IO/FileArchive/Destructor.md b/docs/api/XCEngine/Core/IO/FileArchive/Destructor.md index 2b703546..02ba37cf 100644 --- a/docs/api/XCEngine/Core/IO/FileArchive/Destructor.md +++ b/docs/api/XCEngine/Core/IO/FileArchive/Destructor.md @@ -1,29 +1,25 @@ # FileArchive::~FileArchive() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/IO/FileArchive.h` + +## 签名 ```cpp virtual ~FileArchive() override; ``` -该方法声明于 `XCEngine/Core/IO/FileArchive.h`，当前页面用于固定 `FileArchive` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `Close(...)` 相关流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::FileArchive object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 当前实现会调用 `Close`。 ## 相关文档 -- [返回类总览](FileArchive.md) -- [返回模块目录](../IO.md) +- [FileArchive](FileArchive.md) diff --git a/docs/api/XCEngine/Core/IO/FileArchive/Enumerate.md b/docs/api/XCEngine/Core/IO/FileArchive/Enumerate.md index f67a01ed..a8041914 100644 --- a/docs/api/XCEngine/Core/IO/FileArchive/Enumerate.md +++ b/docs/api/XCEngine/Core/IO/FileArchive/Enumerate.md @@ -1,32 +1,25 @@ # FileArchive::Enumerate -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/IO/FileArchive.h` + +## 签名 ```cpp void Enumerate(const Containers::String& pattern, Containers::Array& outFiles) const override; ``` -该方法声明于 `XCEngine/Core/IO/FileArchive.h`，当前页面用于固定 `FileArchive` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `pattern` - 参数语义详见头文件声明。 -- `outFiles` - 参数语义详见头文件声明。 +执行 `Enumerate` 对应的公开操作。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::FileArchive object; - // 根据上下文补齐参数后调用 FileArchive::Enumerate(...)。 - (void)object; -} -``` +- 具体定义位于 `engine/src/Core/IO/FileArchive.cpp`。 ## 相关文档 -- [返回类总览](FileArchive.md) -- [返回模块目录](../IO.md) +- [FileArchive](FileArchive.md) diff --git a/docs/api/XCEngine/Core/IO/FileArchive/Exists.md b/docs/api/XCEngine/Core/IO/FileArchive/Exists.md index 8fe93a77..ed6eaf2d 100644 --- a/docs/api/XCEngine/Core/IO/FileArchive/Exists.md +++ b/docs/api/XCEngine/Core/IO/FileArchive/Exists.md @@ -1,31 +1,25 @@ # FileArchive::Exists -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/IO/FileArchive.h` + +## 签名 ```cpp bool Exists(const Containers::String& fileName) const override; ``` -该方法声明于 `XCEngine/Core/IO/FileArchive.h`，当前页面用于固定 `FileArchive` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `fileName` - 参数语义详见头文件声明。 +执行 `Exists` 对应的公开操作。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::FileArchive object; - // 根据上下文补齐参数后调用 FileArchive::Exists(...)。 - (void)object; -} -``` +- 具体定义位于 `engine/src/Core/IO/FileArchive.cpp`。 ## 相关文档 -- [返回类总览](FileArchive.md) -- [返回模块目录](../IO.md) +- [FileArchive](FileArchive.md) diff --git a/docs/api/XCEngine/Core/IO/FileArchive/GetPath.md b/docs/api/XCEngine/Core/IO/FileArchive/GetPath.md index 23484b20..bcb9b865 100644 --- a/docs/api/XCEngine/Core/IO/FileArchive/GetPath.md +++ b/docs/api/XCEngine/Core/IO/FileArchive/GetPath.md @@ -1,30 +1,25 @@ # FileArchive::GetPath -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/IO/FileArchive.h` + +## 签名 ```cpp const Containers::String& GetPath() const; ``` -该方法声明于 `XCEngine/Core/IO/FileArchive.h`，当前页面用于固定 `FileArchive` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_archivePath` 当前值。 -**返回：** `const Containers::String&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::FileArchive object; - // 根据上下文补齐参数后调用 FileArchive::GetPath(...)。 - (void)object; -} -``` +- 返回 `m_archivePath` 当前值。 ## 相关文档 -- [返回类总览](FileArchive.md) -- [返回模块目录](../IO.md) +- [FileArchive](FileArchive.md) diff --git a/docs/api/XCEngine/Core/IO/FileArchive/GetSize.md b/docs/api/XCEngine/Core/IO/FileArchive/GetSize.md index 18c52d9d..5748128c 100644 --- a/docs/api/XCEngine/Core/IO/FileArchive/GetSize.md +++ b/docs/api/XCEngine/Core/IO/FileArchive/GetSize.md @@ -1,31 +1,26 @@ # FileArchive::GetSize -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/IO/FileArchive.h` + +## 签名 ```cpp size_t GetSize(const Containers::String& fileName) const override; ``` -该方法声明于 `XCEngine/Core/IO/FileArchive.h`，当前页面用于固定 `FileArchive` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `fileName` - 参数语义详见头文件声明。 +执行 `EndsWith`、`fopen` 协同流程。 -**返回：** `size_t` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::FileArchive object; - // 根据上下文补齐参数后调用 FileArchive::GetSize(...)。 - (void)object; -} -``` +- 当前实现会调用 `EndsWith`、`fopen`、`CStr`、`fseek`。 +- 包含条件分支，并可能提前返回。 ## 相关文档 -- [返回类总览](FileArchive.md) -- [返回模块目录](../IO.md) +- [FileArchive](FileArchive.md) diff --git a/docs/api/XCEngine/Core/IO/FileArchive/IsValid.md b/docs/api/XCEngine/Core/IO/FileArchive/IsValid.md index a16071ca..3f3dc20f 100644 --- a/docs/api/XCEngine/Core/IO/FileArchive/IsValid.md +++ b/docs/api/XCEngine/Core/IO/FileArchive/IsValid.md @@ -1,30 +1,25 @@ # FileArchive::IsValid -查询当前状态。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/IO/FileArchive.h` + +## 签名 ```cpp bool IsValid() const override; ``` -该方法声明于 `XCEngine/Core/IO/FileArchive.h`，当前页面用于固定 `FileArchive` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_isValid` 当前值。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::FileArchive object; - // 根据上下文补齐参数后调用 FileArchive::IsValid(...)。 - (void)object; -} -``` +- 返回 `m_isValid` 当前值。 ## 相关文档 -- [返回类总览](FileArchive.md) -- [返回模块目录](../IO.md) +- [FileArchive](FileArchive.md) diff --git a/docs/api/XCEngine/Core/IO/FileArchive/Open.md b/docs/api/XCEngine/Core/IO/FileArchive/Open.md index bf9ea807..0d331531 100644 --- a/docs/api/XCEngine/Core/IO/FileArchive/Open.md +++ b/docs/api/XCEngine/Core/IO/FileArchive/Open.md @@ -1,31 +1,25 @@ # FileArchive::Open -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/IO/FileArchive.h` + +## 签名 ```cpp bool Open(const Containers::String& path) override; ``` -该方法声明于 `XCEngine/Core/IO/FileArchive.h`，当前页面用于固定 `FileArchive` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `path` - 参数语义详见头文件声明。 +固定返回 `true`。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::FileArchive object; - // 根据上下文补齐参数后调用 FileArchive::Open(...)。 - (void)object; -} -``` +- 会更新 `m_archivePath`、`m_isValid`。 ## 相关文档 -- [返回类总览](FileArchive.md) -- [返回模块目录](../IO.md) +- [FileArchive](FileArchive.md) diff --git a/docs/api/XCEngine/Core/IO/FileArchive/Read.md b/docs/api/XCEngine/Core/IO/FileArchive/Read.md index 30be8e61..6665d901 100644 --- a/docs/api/XCEngine/Core/IO/FileArchive/Read.md +++ b/docs/api/XCEngine/Core/IO/FileArchive/Read.md @@ -1,34 +1,25 @@ # FileArchive::Read -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/IO/FileArchive.h` + +## 签名 ```cpp bool Read(const Containers::String& fileName, void* buffer, size_t size, size_t offset) const override; ``` -该方法声明于 `XCEngine/Core/IO/FileArchive.h`，当前页面用于固定 `FileArchive` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `fileName` - 参数语义详见头文件声明。 -- `buffer` - 参数语义详见头文件声明。 -- `size` - 参数语义详见头文件声明。 -- `offset` - 参数语义详见头文件声明。 +执行 `Read` 对应的公开操作。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::FileArchive object; - // 根据上下文补齐参数后调用 FileArchive::Read(...)。 - (void)object; -} -``` +- 具体定义位于 `engine/src/Core/IO/FileArchive.cpp`。 ## 相关文档 -- [返回类总览](FileArchive.md) -- [返回模块目录](../IO.md) +- [FileArchive](FileArchive.md) diff --git a/docs/api/XCEngine/Core/IO/IResourceLoader/CanLoad.md b/docs/api/XCEngine/Core/IO/IResourceLoader/CanLoad.md index c3b36d68..e734e253 100644 --- a/docs/api/XCEngine/Core/IO/IResourceLoader/CanLoad.md +++ b/docs/api/XCEngine/Core/IO/IResourceLoader/CanLoad.md @@ -1,31 +1,25 @@ # IResourceLoader::CanLoad -判断当前条件下是否可执行。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/IO/IResourceLoader.h` + +## 签名 ```cpp virtual bool CanLoad(const Containers::String& path) const = 0; ``` -该方法声明于 `XCEngine/Core/IO/IResourceLoader.h`，当前页面用于固定 `IResourceLoader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `path` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::IResourceLoader object; - // 根据上下文补齐参数后调用 IResourceLoader::CanLoad(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](IResourceLoader.md) -- [返回模块目录](../IO.md) +- [IResourceLoader](IResourceLoader.md) diff --git a/docs/api/XCEngine/Core/IO/IResourceLoader/Destructor.md b/docs/api/XCEngine/Core/IO/IResourceLoader/Destructor.md index b6b8c4e3..526d8472 100644 --- a/docs/api/XCEngine/Core/IO/IResourceLoader/Destructor.md +++ b/docs/api/XCEngine/Core/IO/IResourceLoader/Destructor.md @@ -1,29 +1,25 @@ # IResourceLoader::~IResourceLoader() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/IO/IResourceLoader.h` + +## 签名 ```cpp virtual ~IResourceLoader() = default; ``` -该方法声明于 `XCEngine/Core/IO/IResourceLoader.h`，当前页面用于固定 `IResourceLoader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +销毁 `IResourceLoader` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::IResourceLoader object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 当前为默认析构实现。 ## 相关文档 -- [返回类总览](IResourceLoader.md) -- [返回模块目录](../IO.md) +- [IResourceLoader](IResourceLoader.md) diff --git a/docs/api/XCEngine/Core/IO/IResourceLoader/GetDefaultSettings.md b/docs/api/XCEngine/Core/IO/IResourceLoader/GetDefaultSettings.md index d44e6c79..889a32b7 100644 --- a/docs/api/XCEngine/Core/IO/IResourceLoader/GetDefaultSettings.md +++ b/docs/api/XCEngine/Core/IO/IResourceLoader/GetDefaultSettings.md @@ -1,30 +1,25 @@ # IResourceLoader::GetDefaultSettings -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/IO/IResourceLoader.h` + +## 签名 ```cpp virtual ImportSettings* GetDefaultSettings() const = 0; ``` -该方法声明于 `XCEngine/Core/IO/IResourceLoader.h`，当前页面用于固定 `IResourceLoader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `ImportSettings*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::IResourceLoader object; - // 根据上下文补齐参数后调用 IResourceLoader::GetDefaultSettings(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](IResourceLoader.md) -- [返回模块目录](../IO.md) +- [IResourceLoader](IResourceLoader.md) diff --git a/docs/api/XCEngine/Core/IO/IResourceLoader/GetResourceType.md b/docs/api/XCEngine/Core/IO/IResourceLoader/GetResourceType.md index 6dc6fa36..06fb427b 100644 --- a/docs/api/XCEngine/Core/IO/IResourceLoader/GetResourceType.md +++ b/docs/api/XCEngine/Core/IO/IResourceLoader/GetResourceType.md @@ -1,30 +1,25 @@ # IResourceLoader::GetResourceType -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/IO/IResourceLoader.h` + +## 签名 ```cpp virtual ResourceType GetResourceType() const = 0; ``` -该方法声明于 `XCEngine/Core/IO/IResourceLoader.h`，当前页面用于固定 `IResourceLoader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `ResourceType` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::IResourceLoader object; - // 根据上下文补齐参数后调用 IResourceLoader::GetResourceType(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](IResourceLoader.md) -- [返回模块目录](../IO.md) +- [IResourceLoader](IResourceLoader.md) diff --git a/docs/api/XCEngine/Core/IO/IResourceLoader/GetSupportedExtensions.md b/docs/api/XCEngine/Core/IO/IResourceLoader/GetSupportedExtensions.md index a8ce51a8..220b9922 100644 --- a/docs/api/XCEngine/Core/IO/IResourceLoader/GetSupportedExtensions.md +++ b/docs/api/XCEngine/Core/IO/IResourceLoader/GetSupportedExtensions.md @@ -1,30 +1,25 @@ # IResourceLoader::GetSupportedExtensions -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/IO/IResourceLoader.h` + +## 签名 ```cpp virtual Containers::Array GetSupportedExtensions() const = 0; ``` -该方法声明于 `XCEngine/Core/IO/IResourceLoader.h`，当前页面用于固定 `IResourceLoader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `Containers::Array` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::IResourceLoader object; - // 根据上下文补齐参数后调用 IResourceLoader::GetSupportedExtensions(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](IResourceLoader.md) -- [返回模块目录](../IO.md) +- [IResourceLoader](IResourceLoader.md) diff --git a/docs/api/XCEngine/Core/IO/IResourceLoader/Load.md b/docs/api/XCEngine/Core/IO/IResourceLoader/Load.md index f55cb659..b5dc08f6 100644 --- a/docs/api/XCEngine/Core/IO/IResourceLoader/Load.md +++ b/docs/api/XCEngine/Core/IO/IResourceLoader/Load.md @@ -1,32 +1,25 @@ # IResourceLoader::Load -加载资源或数据。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/IO/IResourceLoader.h` + +## 签名 ```cpp virtual LoadResult Load(const Containers::String& path, const ImportSettings* settings = nullptr) = 0; ``` -该方法声明于 `XCEngine/Core/IO/IResourceLoader.h`，当前页面用于固定 `IResourceLoader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `path` - 参数语义详见头文件声明。 -- `settings` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `LoadResult` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::IResourceLoader object; - // 根据上下文补齐参数后调用 IResourceLoader::Load(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](IResourceLoader.md) -- [返回模块目录](../IO.md) +- [IResourceLoader](IResourceLoader.md) diff --git a/docs/api/XCEngine/Core/IO/IResourceLoader/LoadAsync.md b/docs/api/XCEngine/Core/IO/IResourceLoader/LoadAsync.md index c4d2a853..5aef1bb1 100644 --- a/docs/api/XCEngine/Core/IO/IResourceLoader/LoadAsync.md +++ b/docs/api/XCEngine/Core/IO/IResourceLoader/LoadAsync.md @@ -1,33 +1,25 @@ # IResourceLoader::LoadAsync -加载资源或数据。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/IO/IResourceLoader.h` + +## 签名 ```cpp virtual void LoadAsync(const Containers::String& path, const ImportSettings* settings, std::function callback); ``` -该方法声明于 `XCEngine/Core/IO/IResourceLoader.h`，当前页面用于固定 `IResourceLoader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `path` - 参数语义详见头文件声明。 -- `settings` - 参数语义详见头文件声明。 -- `callback` - 参数语义详见头文件声明。 +执行 `Load`、`callback` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::IResourceLoader object; - // 根据上下文补齐参数后调用 IResourceLoader::LoadAsync(...)。 - (void)object; -} -``` +- 当前实现会调用 `Load`、`callback`。 ## 相关文档 -- [返回类总览](IResourceLoader.md) -- [返回模块目录](../IO.md) +- [IResourceLoader](IResourceLoader.md) diff --git a/docs/api/XCEngine/Core/IO/ResourceFileSystem/AddArchive.md b/docs/api/XCEngine/Core/IO/ResourceFileSystem/AddArchive.md index 071f193e..fba21f98 100644 --- a/docs/api/XCEngine/Core/IO/ResourceFileSystem/AddArchive.md +++ b/docs/api/XCEngine/Core/IO/ResourceFileSystem/AddArchive.md @@ -1,31 +1,26 @@ # ResourceFileSystem::AddArchive -添加元素或建立关联。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/IO/ResourceFileSystem.h` + +## 签名 ```cpp bool AddArchive(const Containers::String& archivePath); ``` -该方法声明于 `XCEngine/Core/IO/ResourceFileSystem.h`，当前页面用于固定 `ResourceFileSystem` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `archivePath` - 参数语义详见头文件声明。 +更新 `m_directories`。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::ResourceFileSystem object; - // 根据上下文补齐参数后调用 ResourceFileSystem::AddArchive(...)。 - (void)object; -} -``` +- 会更新 `m_directories`。 +- 当前实现会调用 `lock`、`PushBack`。 ## 相关文档 -- [返回类总览](ResourceFileSystem.md) -- [返回模块目录](../IO.md) +- [ResourceFileSystem](ResourceFileSystem.md) diff --git a/docs/api/XCEngine/Core/IO/ResourceFileSystem/AddDirectory.md b/docs/api/XCEngine/Core/IO/ResourceFileSystem/AddDirectory.md index 71285583..0cd3a16e 100644 --- a/docs/api/XCEngine/Core/IO/ResourceFileSystem/AddDirectory.md +++ b/docs/api/XCEngine/Core/IO/ResourceFileSystem/AddDirectory.md @@ -1,31 +1,26 @@ # ResourceFileSystem::AddDirectory -添加元素或建立关联。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/IO/ResourceFileSystem.h` + +## 签名 ```cpp bool AddDirectory(const Containers::String& directoryPath); ``` -该方法声明于 `XCEngine/Core/IO/ResourceFileSystem.h`，当前页面用于固定 `ResourceFileSystem` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `directoryPath` - 参数语义详见头文件声明。 +更新 `m_directories`。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::ResourceFileSystem object; - // 根据上下文补齐参数后调用 ResourceFileSystem::AddDirectory(...)。 - (void)object; -} -``` +- 会更新 `m_directories`。 +- 当前实现会调用 `lock`、`PushBack`。 ## 相关文档 -- [返回类总览](ResourceFileSystem.md) -- [返回模块目录](../IO.md) +- [ResourceFileSystem](ResourceFileSystem.md) diff --git a/docs/api/XCEngine/Core/IO/ResourceFileSystem/Constructor.md b/docs/api/XCEngine/Core/IO/ResourceFileSystem/Constructor.md index e53005ff..7ec9329b 100644 --- a/docs/api/XCEngine/Core/IO/ResourceFileSystem/Constructor.md +++ b/docs/api/XCEngine/Core/IO/ResourceFileSystem/Constructor.md @@ -1,28 +1,25 @@ # ResourceFileSystem::ResourceFileSystem() -构造对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/IO/ResourceFileSystem.h` + +## 签名 ```cpp ResourceFileSystem(); ``` -该方法声明于 `XCEngine/Core/IO/ResourceFileSystem.h`，当前页面用于固定 `ResourceFileSystem` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +构造 `ResourceFileSystem` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::ResourceFileSystem object; -} -``` +- 当前为默认构造实现。 ## 相关文档 -- [返回类总览](ResourceFileSystem.md) -- [返回模块目录](../IO.md) +- [ResourceFileSystem](ResourceFileSystem.md) diff --git a/docs/api/XCEngine/Core/IO/ResourceFileSystem/Destructor.md b/docs/api/XCEngine/Core/IO/ResourceFileSystem/Destructor.md index a8261d10..1097ce1b 100644 --- a/docs/api/XCEngine/Core/IO/ResourceFileSystem/Destructor.md +++ b/docs/api/XCEngine/Core/IO/ResourceFileSystem/Destructor.md @@ -1,29 +1,25 @@ # ResourceFileSystem::~ResourceFileSystem() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/IO/ResourceFileSystem.h` + +## 签名 ```cpp ~ResourceFileSystem(); ``` -该方法声明于 `XCEngine/Core/IO/ResourceFileSystem.h`，当前页面用于固定 `ResourceFileSystem` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `Shutdown(...)` 相关流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::ResourceFileSystem object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 当前实现会调用 `Shutdown`。 ## 相关文档 -- [返回类总览](ResourceFileSystem.md) -- [返回模块目录](../IO.md) +- [ResourceFileSystem](ResourceFileSystem.md) diff --git a/docs/api/XCEngine/Core/IO/ResourceFileSystem/EnumerateResources.md b/docs/api/XCEngine/Core/IO/ResourceFileSystem/EnumerateResources.md index f5c72cc5..7fba398e 100644 --- a/docs/api/XCEngine/Core/IO/ResourceFileSystem/EnumerateResources.md +++ b/docs/api/XCEngine/Core/IO/ResourceFileSystem/EnumerateResources.md @@ -1,32 +1,25 @@ # ResourceFileSystem::EnumerateResources -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/IO/ResourceFileSystem.h` + +## 签名 ```cpp void EnumerateResources(const Containers::String& pattern, Containers::Array& outResources) const; ``` -该方法声明于 `XCEngine/Core/IO/ResourceFileSystem.h`，当前页面用于固定 `ResourceFileSystem` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `pattern` - 参数语义详见头文件声明。 -- `outResources` - 参数语义详见头文件声明。 +执行 `EnumerateResources` 对应的公开操作。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::ResourceFileSystem object; - // 根据上下文补齐参数后调用 ResourceFileSystem::EnumerateResources(...)。 - (void)object; -} -``` +- 具体定义位于 `engine/src/Core/IO/ResourceFileSystem.cpp`。 ## 相关文档 -- [返回类总览](ResourceFileSystem.md) -- [返回模块目录](../IO.md) +- [ResourceFileSystem](ResourceFileSystem.md) diff --git a/docs/api/XCEngine/Core/IO/ResourceFileSystem/Exists.md b/docs/api/XCEngine/Core/IO/ResourceFileSystem/Exists.md index 82d741bf..20aa2f31 100644 --- a/docs/api/XCEngine/Core/IO/ResourceFileSystem/Exists.md +++ b/docs/api/XCEngine/Core/IO/ResourceFileSystem/Exists.md @@ -1,31 +1,25 @@ # ResourceFileSystem::Exists -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/IO/ResourceFileSystem.h` + +## 签名 ```cpp bool Exists(const Containers::String& relativePath) const; ``` -该方法声明于 `XCEngine/Core/IO/ResourceFileSystem.h`，当前页面用于固定 `ResourceFileSystem` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `relativePath` - 参数语义详见头文件声明。 +执行 `Exists` 对应的公开操作。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::ResourceFileSystem object; - // 根据上下文补齐参数后调用 ResourceFileSystem::Exists(...)。 - (void)object; -} -``` +- 具体定义位于 `engine/src/Core/IO/ResourceFileSystem.cpp`。 ## 相关文档 -- [返回类总览](ResourceFileSystem.md) -- [返回模块目录](../IO.md) +- [ResourceFileSystem](ResourceFileSystem.md) diff --git a/docs/api/XCEngine/Core/IO/ResourceFileSystem/FindResource.md b/docs/api/XCEngine/Core/IO/ResourceFileSystem/FindResource.md index 797aceb7..3140db51 100644 --- a/docs/api/XCEngine/Core/IO/ResourceFileSystem/FindResource.md +++ b/docs/api/XCEngine/Core/IO/ResourceFileSystem/FindResource.md @@ -1,32 +1,25 @@ # ResourceFileSystem::FindResource -查找并返回匹配对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/IO/ResourceFileSystem.h` + +## 签名 ```cpp bool FindResource(const Containers::String& relativePath, Containers::String& outAbsolutePath) const; ``` -该方法声明于 `XCEngine/Core/IO/ResourceFileSystem.h`，当前页面用于固定 `ResourceFileSystem` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `relativePath` - 参数语义详见头文件声明。 -- `outAbsolutePath` - 参数语义详见头文件声明。 +执行 `FindResource` 对应的公开操作。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::ResourceFileSystem object; - // 根据上下文补齐参数后调用 ResourceFileSystem::FindResource(...)。 - (void)object; -} -``` +- 具体定义位于 `engine/src/Core/IO/ResourceFileSystem.cpp`。 ## 相关文档 -- [返回类总览](ResourceFileSystem.md) -- [返回模块目录](../IO.md) +- [ResourceFileSystem](ResourceFileSystem.md) diff --git a/docs/api/XCEngine/Core/IO/ResourceFileSystem/Get.md b/docs/api/XCEngine/Core/IO/ResourceFileSystem/Get.md index 68f0b8c6..6ecf6f11 100644 --- a/docs/api/XCEngine/Core/IO/ResourceFileSystem/Get.md +++ b/docs/api/XCEngine/Core/IO/ResourceFileSystem/Get.md @@ -1,29 +1,25 @@ # ResourceFileSystem::Get -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/IO/ResourceFileSystem.h` + +## 签名 ```cpp static ResourceFileSystem& Get(); ``` -该方法声明于 `XCEngine/Core/IO/ResourceFileSystem.h`，当前页面用于固定 `ResourceFileSystem` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `instance`。 -**返回：** `ResourceFileSystem&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - auto& instance = XCEngine::Resources::ResourceFileSystem::Get(); - (void)instance; -} -``` +- 返回 `instance`。 ## 相关文档 -- [返回类总览](ResourceFileSystem.md) -- [返回模块目录](../IO.md) +- [ResourceFileSystem](ResourceFileSystem.md) diff --git a/docs/api/XCEngine/Core/IO/ResourceFileSystem/GetResourceInfo.md b/docs/api/XCEngine/Core/IO/ResourceFileSystem/GetResourceInfo.md index 21df6174..ccf043a1 100644 --- a/docs/api/XCEngine/Core/IO/ResourceFileSystem/GetResourceInfo.md +++ b/docs/api/XCEngine/Core/IO/ResourceFileSystem/GetResourceInfo.md @@ -1,32 +1,28 @@ # ResourceFileSystem::GetResourceInfo -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/IO/ResourceFileSystem.h` + +## 签名 ```cpp bool GetResourceInfo(const Containers::String& relativePath, ResourceInfo& outInfo) const; ``` -该方法声明于 `XCEngine/Core/IO/ResourceFileSystem.h`，当前页面用于固定 `ResourceFileSystem` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `relativePath` - 参数语义详见头文件声明。 -- `outInfo` - 参数语义详见头文件声明。 +更新 `m_infoCache`。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::ResourceFileSystem object; - // 根据上下文补齐参数后调用 ResourceFileSystem::GetResourceInfo(...)。 - (void)object; -} -``` +- 会更新 `m_infoCache`。 +- 当前实现会调用 `lock`、`Find`、`FindResource`、`Insert`。 +- 包含条件分支，并可能提前返回。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](ResourceFileSystem.md) -- [返回模块目录](../IO.md) +- [ResourceFileSystem](ResourceFileSystem.md) diff --git a/docs/api/XCEngine/Core/IO/ResourceFileSystem/Initialize.md b/docs/api/XCEngine/Core/IO/ResourceFileSystem/Initialize.md index 6eedaaab..a65f9c35 100644 --- a/docs/api/XCEngine/Core/IO/ResourceFileSystem/Initialize.md +++ b/docs/api/XCEngine/Core/IO/ResourceFileSystem/Initialize.md @@ -1,31 +1,26 @@ # ResourceFileSystem::Initialize -初始化内部状态。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/IO/ResourceFileSystem.h` + +## 签名 ```cpp void Initialize(const Containers::String& rootPath); ``` -该方法声明于 `XCEngine/Core/IO/ResourceFileSystem.h`，当前页面用于固定 `ResourceFileSystem` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `rootPath` - 参数语义详见头文件声明。 +更新 `m_rootPath`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::ResourceFileSystem object; - // 根据上下文补齐参数后调用 ResourceFileSystem::Initialize(...)。 - (void)object; -} -``` +- 会更新 `m_rootPath`。 +- 当前实现会调用 `lock`。 ## 相关文档 -- [返回类总览](ResourceFileSystem.md) -- [返回模块目录](../IO.md) +- [ResourceFileSystem](ResourceFileSystem.md) diff --git a/docs/api/XCEngine/Core/IO/ResourceFileSystem/ReadResource.md b/docs/api/XCEngine/Core/IO/ResourceFileSystem/ReadResource.md index 48deebfa..cb09b41f 100644 --- a/docs/api/XCEngine/Core/IO/ResourceFileSystem/ReadResource.md +++ b/docs/api/XCEngine/Core/IO/ResourceFileSystem/ReadResource.md @@ -1,31 +1,25 @@ # ResourceFileSystem::ReadResource -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/IO/ResourceFileSystem.h` + +## 签名 ```cpp Containers::Array ReadResource(const Containers::String& relativePath) const; ``` -该方法声明于 `XCEngine/Core/IO/ResourceFileSystem.h`，当前页面用于固定 `ResourceFileSystem` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `relativePath` - 参数语义详见头文件声明。 +执行 `ReadResource` 对应的公开操作。 -**返回：** `Containers::Array` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::ResourceFileSystem object; - // 根据上下文补齐参数后调用 ResourceFileSystem::ReadResource(...)。 - (void)object; -} -``` +- 具体定义位于 `engine/src/Core/IO/ResourceFileSystem.cpp`。 ## 相关文档 -- [返回类总览](ResourceFileSystem.md) -- [返回模块目录](../IO.md) +- [ResourceFileSystem](ResourceFileSystem.md) diff --git a/docs/api/XCEngine/Core/IO/ResourceFileSystem/RemoveArchive.md b/docs/api/XCEngine/Core/IO/ResourceFileSystem/RemoveArchive.md index 550b5353..24d863bc 100644 --- a/docs/api/XCEngine/Core/IO/ResourceFileSystem/RemoveArchive.md +++ b/docs/api/XCEngine/Core/IO/ResourceFileSystem/RemoveArchive.md @@ -1,31 +1,26 @@ # ResourceFileSystem::RemoveArchive -移除元素或解除关联。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/IO/ResourceFileSystem.h` + +## 签名 ```cpp void RemoveArchive(const Containers::String& archivePath); ``` -该方法声明于 `XCEngine/Core/IO/ResourceFileSystem.h`，当前页面用于固定 `ResourceFileSystem` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `archivePath` - 参数语义详见头文件声明。 +更新 `m_directories`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::ResourceFileSystem object; - // 根据上下文补齐参数后调用 ResourceFileSystem::RemoveArchive(...)。 - (void)object; -} -``` +- 会更新 `m_directories`。 +- 当前实现会调用 `lock`、`PushBack`、`move`。 ## 相关文档 -- [返回类总览](ResourceFileSystem.md) -- [返回模块目录](../IO.md) +- [ResourceFileSystem](ResourceFileSystem.md) diff --git a/docs/api/XCEngine/Core/IO/ResourceFileSystem/Shutdown.md b/docs/api/XCEngine/Core/IO/ResourceFileSystem/Shutdown.md index 27e315ba..99e9d9da 100644 --- a/docs/api/XCEngine/Core/IO/ResourceFileSystem/Shutdown.md +++ b/docs/api/XCEngine/Core/IO/ResourceFileSystem/Shutdown.md @@ -1,30 +1,26 @@ # ResourceFileSystem::Shutdown -关闭并清理内部状态。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/IO/ResourceFileSystem.h` + +## 签名 ```cpp void Shutdown(); ``` -该方法声明于 `XCEngine/Core/IO/ResourceFileSystem.h`，当前页面用于固定 `ResourceFileSystem` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `lock`、`Clear` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::ResourceFileSystem object; - // 根据上下文补齐参数后调用 ResourceFileSystem::Shutdown(...)。 - (void)object; -} -``` +- 会更新 `m_rootPath`、`m_archives`、`m_directories`、`m_infoCache`。 +- 当前实现会调用 `lock`、`Clear`。 ## 相关文档 -- [返回类总览](ResourceFileSystem.md) -- [返回模块目录](../IO.md) +- [ResourceFileSystem](ResourceFileSystem.md) diff --git a/docs/api/XCEngine/Core/IO/ResourcePackage/Close.md b/docs/api/XCEngine/Core/IO/ResourcePackage/Close.md index 87bb4535..bce7414a 100644 --- a/docs/api/XCEngine/Core/IO/ResourcePackage/Close.md +++ b/docs/api/XCEngine/Core/IO/ResourcePackage/Close.md @@ -1,30 +1,26 @@ # ResourcePackage::Close -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/IO/ResourcePackage.h` + +## 签名 ```cpp void Close(); ``` -该方法声明于 `XCEngine/Core/IO/ResourcePackage.h`，当前页面用于固定 `ResourcePackage` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `Clear` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::ResourcePackage object; - // 根据上下文补齐参数后调用 ResourcePackage::Close(...)。 - (void)object; -} -``` +- 会更新 `m_isValid`、`m_packagePath`、`m_dataOffset`、`m_entries`。 +- 当前实现会调用 `Clear`。 ## 相关文档 -- [返回类总览](ResourcePackage.md) -- [返回模块目录](../IO.md) +- [ResourcePackage](ResourcePackage.md) diff --git a/docs/api/XCEngine/Core/IO/ResourcePackage/Constructor.md b/docs/api/XCEngine/Core/IO/ResourcePackage/Constructor.md index 9daa21f7..e00e2731 100644 --- a/docs/api/XCEngine/Core/IO/ResourcePackage/Constructor.md +++ b/docs/api/XCEngine/Core/IO/ResourcePackage/Constructor.md @@ -1,28 +1,25 @@ # ResourcePackage::ResourcePackage() -构造对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/IO/ResourcePackage.h` + +## 签名 ```cpp ResourcePackage(); ``` -该方法声明于 `XCEngine/Core/IO/ResourcePackage.h`，当前页面用于固定 `ResourcePackage` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +构造 `ResourcePackage` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::ResourcePackage object; -} -``` +- 当前为默认构造实现。 ## 相关文档 -- [返回类总览](ResourcePackage.md) -- [返回模块目录](../IO.md) +- [ResourcePackage](ResourcePackage.md) diff --git a/docs/api/XCEngine/Core/IO/ResourcePackage/Destructor.md b/docs/api/XCEngine/Core/IO/ResourcePackage/Destructor.md index 1552bdc9..cf42eb6e 100644 --- a/docs/api/XCEngine/Core/IO/ResourcePackage/Destructor.md +++ b/docs/api/XCEngine/Core/IO/ResourcePackage/Destructor.md @@ -1,29 +1,25 @@ # ResourcePackage::~ResourcePackage() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/IO/ResourcePackage.h` + +## 签名 ```cpp ~ResourcePackage(); ``` -该方法声明于 `XCEngine/Core/IO/ResourcePackage.h`，当前页面用于固定 `ResourcePackage` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `Close(...)` 相关流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::ResourcePackage object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 当前实现会调用 `Close`。 ## 相关文档 -- [返回类总览](ResourcePackage.md) -- [返回模块目录](../IO.md) +- [ResourcePackage](ResourcePackage.md) diff --git a/docs/api/XCEngine/Core/IO/ResourcePackage/Enumerate.md b/docs/api/XCEngine/Core/IO/ResourcePackage/Enumerate.md index 08d6a707..f1ceca9d 100644 --- a/docs/api/XCEngine/Core/IO/ResourcePackage/Enumerate.md +++ b/docs/api/XCEngine/Core/IO/ResourcePackage/Enumerate.md @@ -1,32 +1,25 @@ # ResourcePackage::Enumerate -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/IO/ResourcePackage.h` + +## 签名 ```cpp void Enumerate(const Containers::String& pattern, Containers::Array& outFiles) const; ``` -该方法声明于 `XCEngine/Core/IO/ResourcePackage.h`，当前页面用于固定 `ResourcePackage` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `pattern` - 参数语义详见头文件声明。 -- `outFiles` - 参数语义详见头文件声明。 +执行 `Enumerate` 对应的公开操作。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::ResourcePackage object; - // 根据上下文补齐参数后调用 ResourcePackage::Enumerate(...)。 - (void)object; -} -``` +- 具体定义位于 `engine/src/Core/IO/ResourcePackage.cpp`。 ## 相关文档 -- [返回类总览](ResourcePackage.md) -- [返回模块目录](../IO.md) +- [ResourcePackage](ResourcePackage.md) diff --git a/docs/api/XCEngine/Core/IO/ResourcePackage/Exists.md b/docs/api/XCEngine/Core/IO/ResourcePackage/Exists.md index 732277e4..3a99b69c 100644 --- a/docs/api/XCEngine/Core/IO/ResourcePackage/Exists.md +++ b/docs/api/XCEngine/Core/IO/ResourcePackage/Exists.md @@ -1,31 +1,25 @@ # ResourcePackage::Exists -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/IO/ResourcePackage.h` + +## 签名 ```cpp bool Exists(const Containers::String& relativePath) const; ``` -该方法声明于 `XCEngine/Core/IO/ResourcePackage.h`，当前页面用于固定 `ResourcePackage` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `relativePath` - 参数语义详见头文件声明。 +执行 `Exists` 对应的公开操作。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::ResourcePackage object; - // 根据上下文补齐参数后调用 ResourcePackage::Exists(...)。 - (void)object; -} -``` +- 具体定义位于 `engine/src/Core/IO/ResourcePackage.cpp`。 ## 相关文档 -- [返回类总览](ResourcePackage.md) -- [返回模块目录](../IO.md) +- [ResourcePackage](ResourcePackage.md) diff --git a/docs/api/XCEngine/Core/IO/ResourcePackage/GetInfo.md b/docs/api/XCEngine/Core/IO/ResourcePackage/GetInfo.md index f8e1cc67..2b3ecd7d 100644 --- a/docs/api/XCEngine/Core/IO/ResourcePackage/GetInfo.md +++ b/docs/api/XCEngine/Core/IO/ResourcePackage/GetInfo.md @@ -1,30 +1,25 @@ # ResourcePackage::GetInfo -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/IO/ResourcePackage.h` + +## 签名 ```cpp const PackageInfo& GetInfo() const; ``` -该方法声明于 `XCEngine/Core/IO/ResourcePackage.h`，当前页面用于固定 `ResourcePackage` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_info` 当前值。 -**返回：** `const PackageInfo&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::ResourcePackage object; - // 根据上下文补齐参数后调用 ResourcePackage::GetInfo(...)。 - (void)object; -} -``` +- 返回 `m_info` 当前值。 ## 相关文档 -- [返回类总览](ResourcePackage.md) -- [返回模块目录](../IO.md) +- [ResourcePackage](ResourcePackage.md) diff --git a/docs/api/XCEngine/Core/IO/ResourcePackage/GetSize.md b/docs/api/XCEngine/Core/IO/ResourcePackage/GetSize.md index 039af192..97661949 100644 --- a/docs/api/XCEngine/Core/IO/ResourcePackage/GetSize.md +++ b/docs/api/XCEngine/Core/IO/ResourcePackage/GetSize.md @@ -1,31 +1,25 @@ # ResourcePackage::GetSize -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/IO/ResourcePackage.h` + +## 签名 ```cpp size_t GetSize(const Containers::String& relativePath) const; ``` -该方法声明于 `XCEngine/Core/IO/ResourcePackage.h`，当前页面用于固定 `ResourcePackage` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `relativePath` - 参数语义详见头文件声明。 +执行该公开方法对应的当前实现。 -**返回：** `size_t` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::ResourcePackage object; - // 根据上下文补齐参数后调用 ResourcePackage::GetSize(...)。 - (void)object; -} -``` +- 包含条件分支，并可能提前返回。 ## 相关文档 -- [返回类总览](ResourcePackage.md) -- [返回模块目录](../IO.md) +- [ResourcePackage](ResourcePackage.md) diff --git a/docs/api/XCEngine/Core/IO/ResourcePackage/IsValid.md b/docs/api/XCEngine/Core/IO/ResourcePackage/IsValid.md index 355d09d5..0ee7e1e3 100644 --- a/docs/api/XCEngine/Core/IO/ResourcePackage/IsValid.md +++ b/docs/api/XCEngine/Core/IO/ResourcePackage/IsValid.md @@ -1,30 +1,25 @@ # ResourcePackage::IsValid -查询当前状态。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/IO/ResourcePackage.h` + +## 签名 ```cpp bool IsValid() const; ``` -该方法声明于 `XCEngine/Core/IO/ResourcePackage.h`，当前页面用于固定 `ResourcePackage` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_isValid` 当前值。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::ResourcePackage object; - // 根据上下文补齐参数后调用 ResourcePackage::IsValid(...)。 - (void)object; -} -``` +- 返回 `m_isValid` 当前值。 ## 相关文档 -- [返回类总览](ResourcePackage.md) -- [返回模块目录](../IO.md) +- [ResourcePackage](ResourcePackage.md) diff --git a/docs/api/XCEngine/Core/IO/ResourcePackage/Open.md b/docs/api/XCEngine/Core/IO/ResourcePackage/Open.md index 7193d9ed..40b9f0cf 100644 --- a/docs/api/XCEngine/Core/IO/ResourcePackage/Open.md +++ b/docs/api/XCEngine/Core/IO/ResourcePackage/Open.md @@ -1,31 +1,27 @@ # ResourcePackage::Open -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/IO/ResourcePackage.h` + +## 签名 ```cpp bool Open(const Containers::String& packagePath); ``` -该方法声明于 `XCEngine/Core/IO/ResourcePackage.h`，当前页面用于固定 `ResourcePackage` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `packagePath` - 参数语义详见头文件声明。 +执行 `fopen`、`CStr`、`ReadHeader` 协同流程。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::ResourcePackage object; - // 根据上下文补齐参数后调用 ResourcePackage::Open(...)。 - (void)object; -} -``` +- 会更新 `m_packagePath`、`m_isValid`。 +- 当前实现会调用 `fopen`、`CStr`、`ReadHeader`、`ReadManifest`、`fclose`。 +- 包含条件分支，并可能提前返回。 ## 相关文档 -- [返回类总览](ResourcePackage.md) -- [返回模块目录](../IO.md) +- [ResourcePackage](ResourcePackage.md) diff --git a/docs/api/XCEngine/Core/IO/ResourcePackage/Read.md b/docs/api/XCEngine/Core/IO/ResourcePackage/Read.md index aec79315..147e238d 100644 --- a/docs/api/XCEngine/Core/IO/ResourcePackage/Read.md +++ b/docs/api/XCEngine/Core/IO/ResourcePackage/Read.md @@ -1,31 +1,25 @@ # ResourcePackage::Read -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/IO/ResourcePackage.h` + +## 签名 ```cpp Containers::Array Read(const Containers::String& relativePath) const; ``` -该方法声明于 `XCEngine/Core/IO/ResourcePackage.h`，当前页面用于固定 `ResourcePackage` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `relativePath` - 参数语义详见头文件声明。 +执行 `Read` 对应的公开操作。 -**返回：** `Containers::Array` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::ResourcePackage object; - // 根据上下文补齐参数后调用 ResourcePackage::Read(...)。 - (void)object; -} -``` +- 具体定义位于 `engine/src/Core/IO/ResourcePackage.cpp`。 ## 相关文档 -- [返回类总览](ResourcePackage.md) -- [返回模块目录](../IO.md) +- [ResourcePackage](ResourcePackage.md) diff --git a/docs/api/XCEngine/Core/IO/ResourcePath/Constructor.md b/docs/api/XCEngine/Core/IO/ResourcePath/Constructor.md index 7a7260f9..5c817703 100644 --- a/docs/api/XCEngine/Core/IO/ResourcePath/Constructor.md +++ b/docs/api/XCEngine/Core/IO/ResourcePath/Constructor.md @@ -1,52 +1,27 @@ # ResourcePath::ResourcePath() -构造对象。 +**命名空间**: `XCEngine::Resources` -该方法在 `XCEngine/Core/IO/ResourcePath.h` 中提供了 3 个重载，当前页面统一汇总这些公开声明。 +**类型**: `method` -## 重载 1: 声明 +**头文件**: `XCEngine/Core/IO/ResourcePath.h` + +## 签名 ```cpp ResourcePath() = default; -``` - -**参数：** 无。 - -**返回：** `void` - 无返回值。 - -## 重载 2: 声明 - -```cpp ResourcePath(const char* path); -``` - -**参数：** -- `path` - 参数语义详见头文件声明。 - -**返回：** `void` - 无返回值。 - -## 重载 3: 声明 - -```cpp ResourcePath(const Containers::String& path); ``` -**参数：** -- `path` - 参数语义详见头文件声明。 +## 作用 -**返回：** `void` - 无返回值。 +构造 `ResourcePath` 实例。 -**示例：** +## 当前实现 -```cpp -#include - -void Example() { - XCEngine::Resources::ResourcePath object; -} -``` +- 当前为默认构造实现。 ## 相关文档 -- [返回类总览](ResourcePath.md) -- [返回模块目录](../IO.md) +- [ResourcePath](ResourcePath.md) diff --git a/docs/api/XCEngine/Core/IO/ResourcePath/GetDirectory.md b/docs/api/XCEngine/Core/IO/ResourcePath/GetDirectory.md index fabef6b7..4829ef8a 100644 --- a/docs/api/XCEngine/Core/IO/ResourcePath/GetDirectory.md +++ b/docs/api/XCEngine/Core/IO/ResourcePath/GetDirectory.md @@ -1,30 +1,27 @@ # ResourcePath::GetDirectory -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/IO/ResourcePath.h` + +## 签名 ```cpp Containers::String GetDirectory() const; ``` -该方法声明于 `XCEngine/Core/IO/ResourcePath.h`，当前页面用于固定 `ResourcePath` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_path`。 -**返回：** `Containers::String` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::ResourcePath object; - // 根据上下文补齐参数后调用 ResourcePath::GetDirectory(...)。 - (void)object; -} -``` +- 会更新 `m_path`。 +- 当前实现会调用 `Empty`、`String`、`FindLastOf`、`max`。 +- 包含条件分支，并可能提前返回。 ## 相关文档 -- [返回类总览](ResourcePath.md) -- [返回模块目录](../IO.md) +- [ResourcePath](ResourcePath.md) diff --git a/docs/api/XCEngine/Core/IO/ResourcePath/GetExtension.md b/docs/api/XCEngine/Core/IO/ResourcePath/GetExtension.md index 380d49f6..8e094d11 100644 --- a/docs/api/XCEngine/Core/IO/ResourcePath/GetExtension.md +++ b/docs/api/XCEngine/Core/IO/ResourcePath/GetExtension.md @@ -1,30 +1,27 @@ # ResourcePath::GetExtension -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/IO/ResourcePath.h` + +## 签名 ```cpp Containers::String GetExtension() const; ``` -该方法声明于 `XCEngine/Core/IO/ResourcePath.h`，当前页面用于固定 `ResourcePath` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_path`。 -**返回：** `Containers::String` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::ResourcePath object; - // 根据上下文补齐参数后调用 ResourcePath::GetExtension(...)。 - (void)object; -} -``` +- 会更新 `m_path`。 +- 当前实现会调用 `Empty`、`String`、`FindLastOf`、`Substring`。 +- 包含条件分支，并可能提前返回。 ## 相关文档 -- [返回类总览](ResourcePath.md) -- [返回模块目录](../IO.md) +- [ResourcePath](ResourcePath.md) diff --git a/docs/api/XCEngine/Core/IO/ResourcePath/GetFileName.md b/docs/api/XCEngine/Core/IO/ResourcePath/GetFileName.md index 213d32aa..acf0778e 100644 --- a/docs/api/XCEngine/Core/IO/ResourcePath/GetFileName.md +++ b/docs/api/XCEngine/Core/IO/ResourcePath/GetFileName.md @@ -1,30 +1,27 @@ # ResourcePath::GetFileName -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/IO/ResourcePath.h` + +## 签名 ```cpp Containers::String GetFileName() const; ``` -该方法声明于 `XCEngine/Core/IO/ResourcePath.h`，当前页面用于固定 `ResourcePath` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_path`。 -**返回：** `Containers::String` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::ResourcePath object; - // 根据上下文补齐参数后调用 ResourcePath::GetFileName(...)。 - (void)object; -} -``` +- 会更新 `m_path`。 +- 当前实现会调用 `Empty`、`String`、`FindLastOf`、`max`。 +- 包含条件分支，并可能提前返回。 ## 相关文档 -- [返回类总览](ResourcePath.md) -- [返回模块目录](../IO.md) +- [ResourcePath](ResourcePath.md) diff --git a/docs/api/XCEngine/Core/IO/ResourcePath/GetFullPath.md b/docs/api/XCEngine/Core/IO/ResourcePath/GetFullPath.md index 7424cc1c..c077fc9e 100644 --- a/docs/api/XCEngine/Core/IO/ResourcePath/GetFullPath.md +++ b/docs/api/XCEngine/Core/IO/ResourcePath/GetFullPath.md @@ -1,30 +1,25 @@ # ResourcePath::GetFullPath -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/IO/ResourcePath.h` + +## 签名 ```cpp Containers::String GetFullPath() const; ``` -该方法声明于 `XCEngine/Core/IO/ResourcePath.h`，当前页面用于固定 `ResourcePath` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_path` 当前值。 -**返回：** `Containers::String` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::ResourcePath object; - // 根据上下文补齐参数后调用 ResourcePath::GetFullPath(...)。 - (void)object; -} -``` +- 返回 `m_path` 当前值。 ## 相关文档 -- [返回类总览](ResourcePath.md) -- [返回模块目录](../IO.md) +- [ResourcePath](ResourcePath.md) diff --git a/docs/api/XCEngine/Core/IO/ResourcePath/GetPath.md b/docs/api/XCEngine/Core/IO/ResourcePath/GetPath.md index c3478b60..4615b04c 100644 --- a/docs/api/XCEngine/Core/IO/ResourcePath/GetPath.md +++ b/docs/api/XCEngine/Core/IO/ResourcePath/GetPath.md @@ -1,30 +1,26 @@ # ResourcePath::GetPath -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/IO/ResourcePath.h` + +## 签名 ```cpp const Containers::String& GetPath() const; ``` -该方法声明于 `XCEngine/Core/IO/ResourcePath.h`，当前页面用于固定 `ResourcePath` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_path` 当前值。 -**返回：** `const Containers::String&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::ResourcePath object; - // 根据上下文补齐参数后调用 ResourcePath::GetPath(...)。 - (void)object; -} -``` +- 返回 `m_path` 当前值。 ## 相关文档 -- [返回类总览](ResourcePath.md) -- [返回模块目录](../IO.md) +- [ResourcePath](ResourcePath.md) +- [SetPath](SetPath.md) diff --git a/docs/api/XCEngine/Core/IO/ResourcePath/GetRelativePath.md b/docs/api/XCEngine/Core/IO/ResourcePath/GetRelativePath.md index 8ed94faf..f7a48425 100644 --- a/docs/api/XCEngine/Core/IO/ResourcePath/GetRelativePath.md +++ b/docs/api/XCEngine/Core/IO/ResourcePath/GetRelativePath.md @@ -1,30 +1,25 @@ # ResourcePath::GetRelativePath -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/IO/ResourcePath.h` + +## 签名 ```cpp Containers::String GetRelativePath() const; ``` -该方法声明于 `XCEngine/Core/IO/ResourcePath.h`，当前页面用于固定 `ResourcePath` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_path` 当前值。 -**返回：** `Containers::String` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::ResourcePath object; - // 根据上下文补齐参数后调用 ResourcePath::GetRelativePath(...)。 - (void)object; -} -``` +- 返回 `m_path` 当前值。 ## 相关文档 -- [返回类总览](ResourcePath.md) -- [返回模块目录](../IO.md) +- [ResourcePath](ResourcePath.md) diff --git a/docs/api/XCEngine/Core/IO/ResourcePath/GetStem.md b/docs/api/XCEngine/Core/IO/ResourcePath/GetStem.md index f02422be..0417811e 100644 --- a/docs/api/XCEngine/Core/IO/ResourcePath/GetStem.md +++ b/docs/api/XCEngine/Core/IO/ResourcePath/GetStem.md @@ -1,30 +1,27 @@ # ResourcePath::GetStem -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/IO/ResourcePath.h` + +## 签名 ```cpp Containers::String GetStem() const; ``` -该方法声明于 `XCEngine/Core/IO/ResourcePath.h`，当前页面用于固定 `ResourcePath` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_path`。 -**返回：** `Containers::String` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::ResourcePath object; - // 根据上下文补齐参数后调用 ResourcePath::GetStem(...)。 - (void)object; -} -``` +- 会更新 `m_path`。 +- 当前实现会调用 `Empty`、`String`、`FindLastOf`、`max`。 +- 包含条件分支，并可能提前返回。 ## 相关文档 -- [返回类总览](ResourcePath.md) -- [返回模块目录](../IO.md) +- [ResourcePath](ResourcePath.md) diff --git a/docs/api/XCEngine/Core/IO/ResourcePath/HasAnyExtension.md b/docs/api/XCEngine/Core/IO/ResourcePath/HasAnyExtension.md index cf4cc647..9029dd09 100644 --- a/docs/api/XCEngine/Core/IO/ResourcePath/HasAnyExtension.md +++ b/docs/api/XCEngine/Core/IO/ResourcePath/HasAnyExtension.md @@ -1,32 +1,27 @@ # ResourcePath::HasAnyExtension -判断是否具备指定状态或能力。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/IO/ResourcePath.h` + +## 签名 ```cpp bool HasAnyExtension(const char* const* extensions, Core::uint32 count) const; ``` -该方法声明于 `XCEngine/Core/IO/ResourcePath.h`，当前页面用于固定 `ResourcePath` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `extensions` - 参数语义详见头文件声明。 -- `count` - 参数语义详见头文件声明。 +更新 `m_path`。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::ResourcePath object; - // 根据上下文补齐参数后调用 ResourcePath::HasAnyExtension(...)。 - (void)object; -} -``` +- 会更新 `m_path`。 +- 当前实现会调用 `Empty`、`HasExtension`。 +- 包含条件分支，并可能提前返回。 ## 相关文档 -- [返回类总览](ResourcePath.md) -- [返回模块目录](../IO.md) +- [ResourcePath](ResourcePath.md) diff --git a/docs/api/XCEngine/Core/IO/ResourcePath/HasExtension.md b/docs/api/XCEngine/Core/IO/ResourcePath/HasExtension.md index 58ad5990..b152ed79 100644 --- a/docs/api/XCEngine/Core/IO/ResourcePath/HasExtension.md +++ b/docs/api/XCEngine/Core/IO/ResourcePath/HasExtension.md @@ -1,31 +1,27 @@ # ResourcePath::HasExtension -判断是否具备指定状态或能力。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/IO/ResourcePath.h` + +## 签名 ```cpp bool HasExtension(const char* ext) const; ``` -该方法声明于 `XCEngine/Core/IO/ResourcePath.h`，当前页面用于固定 `ResourcePath` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `ext` - 参数语义详见头文件声明。 +更新 `m_path`。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::ResourcePath object; - // 根据上下文补齐参数后调用 ResourcePath::HasExtension(...)。 - (void)object; -} -``` +- 会更新 `m_path`。 +- 当前实现会调用 `Empty`、`GetExtension`。 +- 包含条件分支，并可能提前返回。 ## 相关文档 -- [返回类总览](ResourcePath.md) -- [返回模块目录](../IO.md) +- [ResourcePath](ResourcePath.md) diff --git a/docs/api/XCEngine/Core/IO/ResourcePath/IsValid.md b/docs/api/XCEngine/Core/IO/ResourcePath/IsValid.md index af980b33..b07816e0 100644 --- a/docs/api/XCEngine/Core/IO/ResourcePath/IsValid.md +++ b/docs/api/XCEngine/Core/IO/ResourcePath/IsValid.md @@ -1,30 +1,26 @@ # ResourcePath::IsValid -查询当前状态。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/IO/ResourcePath.h` + +## 签名 ```cpp bool IsValid() const; ``` -该方法声明于 `XCEngine/Core/IO/ResourcePath.h`，当前页面用于固定 `ResourcePath` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_path`。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::ResourcePath object; - // 根据上下文补齐参数后调用 ResourcePath::IsValid(...)。 - (void)object; -} -``` +- 会更新 `m_path`。 +- 当前实现会调用 `Empty`。 ## 相关文档 -- [返回类总览](ResourcePath.md) -- [返回模块目录](../IO.md) +- [ResourcePath](ResourcePath.md) diff --git a/docs/api/XCEngine/Core/IO/ResourcePath/SetPath.md b/docs/api/XCEngine/Core/IO/ResourcePath/SetPath.md index cdb02b15..586d4563 100644 --- a/docs/api/XCEngine/Core/IO/ResourcePath/SetPath.md +++ b/docs/api/XCEngine/Core/IO/ResourcePath/SetPath.md @@ -1,31 +1,26 @@ # ResourcePath::SetPath -设置相关状态或配置。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/IO/ResourcePath.h` + +## 签名 ```cpp void SetPath(const Containers::String& path); ``` -该方法声明于 `XCEngine/Core/IO/ResourcePath.h`，当前页面用于固定 `ResourcePath` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `path` - 参数语义详见头文件声明。 +更新 `m_path`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::ResourcePath object; - // 根据上下文补齐参数后调用 ResourcePath::SetPath(...)。 - (void)object; -} -``` +- 会更新 `m_path`。 ## 相关文档 -- [返回类总览](ResourcePath.md) -- [返回模块目录](../IO.md) +- [ResourcePath](ResourcePath.md) +- [GetPath](GetPath.md) diff --git a/docs/api/XCEngine/Core/IO/ResourcePath/ToGUID.md b/docs/api/XCEngine/Core/IO/ResourcePath/ToGUID.md index 87270ba3..a11a3c2a 100644 --- a/docs/api/XCEngine/Core/IO/ResourcePath/ToGUID.md +++ b/docs/api/XCEngine/Core/IO/ResourcePath/ToGUID.md @@ -1,30 +1,25 @@ # ResourcePath::ToGUID -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Core/IO/ResourcePath.h` + +## 签名 ```cpp ResourceGUID ToGUID() const; ``` -该方法声明于 `XCEngine/Core/IO/ResourcePath.h`，当前页面用于固定 `ResourcePath` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `ToGUID` 对应的公开操作。 -**返回：** `ResourceGUID` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::ResourcePath object; - // 根据上下文补齐参数后调用 ResourcePath::ToGUID(...)。 - (void)object; -} -``` +- 具体定义位于 `engine/src/Core/IO/ResourcePath.cpp`。 ## 相关文档 -- [返回类总览](ResourcePath.md) -- [返回模块目录](../IO.md) +- [ResourcePath](ResourcePath.md) diff --git a/docs/api/XCEngine/Core/Layer/Constructor.md b/docs/api/XCEngine/Core/Layer/Constructor.md index 7a1d300d..e8a899d3 100644 --- a/docs/api/XCEngine/Core/Layer/Constructor.md +++ b/docs/api/XCEngine/Core/Layer/Constructor.md @@ -1,29 +1,25 @@ # Layer::Layer() -构造对象。 +**命名空间**: `XCEngine::Core` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Layer.h` + +## 签名 ```cpp Layer(const std::string& name = "Layer") : m_name(name); ``` -该方法声明于 `XCEngine/Core/Layer.h`，当前页面用于固定 `Layer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `name` - 参数语义详见头文件声明。 +构造 `Layer` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Core::Layer object; -} -``` +- 当前为默认构造实现。 ## 相关文档 -- [返回类总览](Layer.md) -- [返回模块目录](../Core.md) +- [Layer](Layer.md) diff --git a/docs/api/XCEngine/Core/Layer/Destructor.md b/docs/api/XCEngine/Core/Layer/Destructor.md index 0e3a75e7..e8fa8111 100644 --- a/docs/api/XCEngine/Core/Layer/Destructor.md +++ b/docs/api/XCEngine/Core/Layer/Destructor.md @@ -1,29 +1,25 @@ # Layer::~Layer() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::Core` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Layer.h` + +## 签名 ```cpp virtual ~Layer() = default; ``` -该方法声明于 `XCEngine/Core/Layer.h`，当前页面用于固定 `Layer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +销毁 `Layer` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Core::Layer object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 当前为默认析构实现。 ## 相关文档 -- [返回类总览](Layer.md) -- [返回模块目录](../Core.md) +- [Layer](Layer.md) diff --git a/docs/api/XCEngine/Core/Layer/getName.md b/docs/api/XCEngine/Core/Layer/getName.md index ef40e040..3d348623 100644 --- a/docs/api/XCEngine/Core/Layer/getName.md +++ b/docs/api/XCEngine/Core/Layer/getName.md @@ -1,30 +1,25 @@ # Layer::getName -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Core` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Layer.h` + +## 签名 ```cpp const std::string& getName() const; ``` -该方法声明于 `XCEngine/Core/Layer.h`，当前页面用于固定 `Layer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `getName` 对应的公开操作。 -**返回：** `const std::string&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Core::Layer object; - // 根据上下文补齐参数后调用 Layer::getName(...)。 - (void)object; -} -``` +- 执行 `getName` 对应的公开操作。 ## 相关文档 -- [返回类总览](Layer.md) -- [返回模块目录](../Core.md) +- [Layer](Layer.md) diff --git a/docs/api/XCEngine/Core/Layer/onAttach.md b/docs/api/XCEngine/Core/Layer/onAttach.md index 28f30cce..baf1778e 100644 --- a/docs/api/XCEngine/Core/Layer/onAttach.md +++ b/docs/api/XCEngine/Core/Layer/onAttach.md @@ -1,30 +1,25 @@ # Layer::onAttach -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Core` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Layer.h` + +## 签名 ```cpp virtual void onAttach(); ``` -该方法声明于 `XCEngine/Core/Layer.h`，当前页面用于固定 `Layer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +当前实现为空。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Core::Layer object; - // 根据上下文补齐参数后调用 Layer::onAttach(...)。 - (void)object; -} -``` +- 当前函数体为空。 ## 相关文档 -- [返回类总览](Layer.md) -- [返回模块目录](../Core.md) +- [Layer](Layer.md) diff --git a/docs/api/XCEngine/Core/Layer/onDetach.md b/docs/api/XCEngine/Core/Layer/onDetach.md index 93dfb6f8..86d8969f 100644 --- a/docs/api/XCEngine/Core/Layer/onDetach.md +++ b/docs/api/XCEngine/Core/Layer/onDetach.md @@ -1,30 +1,25 @@ # Layer::onDetach -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Core` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Layer.h` + +## 签名 ```cpp virtual void onDetach(); ``` -该方法声明于 `XCEngine/Core/Layer.h`，当前页面用于固定 `Layer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +当前实现为空。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Core::Layer object; - // 根据上下文补齐参数后调用 Layer::onDetach(...)。 - (void)object; -} -``` +- 当前函数体为空。 ## 相关文档 -- [返回类总览](Layer.md) -- [返回模块目录](../Core.md) +- [Layer](Layer.md) diff --git a/docs/api/XCEngine/Core/Layer/onEvent.md b/docs/api/XCEngine/Core/Layer/onEvent.md index f8d74d60..9c62894a 100644 --- a/docs/api/XCEngine/Core/Layer/onEvent.md +++ b/docs/api/XCEngine/Core/Layer/onEvent.md @@ -1,31 +1,25 @@ # Layer::onEvent -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Core` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Layer.h` + +## 签名 ```cpp virtual void onEvent(void* event); ``` -该方法声明于 `XCEngine/Core/Layer.h`，当前页面用于固定 `Layer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `event` - 参数语义详见头文件声明。 +当前实现为空。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Core::Layer object; - // 根据上下文补齐参数后调用 Layer::onEvent(...)。 - (void)object; -} -``` +- 当前函数体为空。 ## 相关文档 -- [返回类总览](Layer.md) -- [返回模块目录](../Core.md) +- [Layer](Layer.md) diff --git a/docs/api/XCEngine/Core/Layer/onImGuiRender.md b/docs/api/XCEngine/Core/Layer/onImGuiRender.md index 15f80880..4ba904e0 100644 --- a/docs/api/XCEngine/Core/Layer/onImGuiRender.md +++ b/docs/api/XCEngine/Core/Layer/onImGuiRender.md @@ -1,30 +1,25 @@ # Layer::onImGuiRender -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Core` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Layer.h` + +## 签名 ```cpp virtual void onImGuiRender(); ``` -该方法声明于 `XCEngine/Core/Layer.h`，当前页面用于固定 `Layer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +当前实现为空。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Core::Layer object; - // 根据上下文补齐参数后调用 Layer::onImGuiRender(...)。 - (void)object; -} -``` +- 当前函数体为空。 ## 相关文档 -- [返回类总览](Layer.md) -- [返回模块目录](../Core.md) +- [Layer](Layer.md) diff --git a/docs/api/XCEngine/Core/Layer/onUpdate.md b/docs/api/XCEngine/Core/Layer/onUpdate.md index 5a701dde..413f9a5d 100644 --- a/docs/api/XCEngine/Core/Layer/onUpdate.md +++ b/docs/api/XCEngine/Core/Layer/onUpdate.md @@ -1,31 +1,25 @@ # Layer::onUpdate -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Core` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Layer.h` + +## 签名 ```cpp virtual void onUpdate(float dt); ``` -该方法声明于 `XCEngine/Core/Layer.h`，当前页面用于固定 `Layer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `dt` - 参数语义详见头文件声明。 +当前实现为空。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Core::Layer object; - // 根据上下文补齐参数后调用 Layer::onUpdate(...)。 - (void)object; -} -``` +- 当前函数体为空。 ## 相关文档 -- [返回类总览](Layer.md) -- [返回模块目录](../Core.md) +- [Layer](Layer.md) diff --git a/docs/api/XCEngine/Core/LayerStack/Constructor.md b/docs/api/XCEngine/Core/LayerStack/Constructor.md index 85912a8e..09f254ac 100644 --- a/docs/api/XCEngine/Core/LayerStack/Constructor.md +++ b/docs/api/XCEngine/Core/LayerStack/Constructor.md @@ -1,28 +1,25 @@ # LayerStack::LayerStack() -构造对象。 +**命名空间**: `XCEngine::Core` + +**类型**: `method` + +**头文件**: `XCEngine/Core/LayerStack.h` + +## 签名 ```cpp LayerStack() = default; ``` -该方法声明于 `XCEngine/Core/LayerStack.h`，当前页面用于固定 `LayerStack` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +构造 `LayerStack` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Core::LayerStack object; -} -``` +- 当前为默认构造实现。 ## 相关文档 -- [返回类总览](LayerStack.md) -- [返回模块目录](../Core.md) +- [LayerStack](LayerStack.md) diff --git a/docs/api/XCEngine/Core/LayerStack/Destructor.md b/docs/api/XCEngine/Core/LayerStack/Destructor.md index d76268d3..cea280c3 100644 --- a/docs/api/XCEngine/Core/LayerStack/Destructor.md +++ b/docs/api/XCEngine/Core/LayerStack/Destructor.md @@ -1,29 +1,25 @@ # LayerStack::~LayerStack() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::Core` + +**类型**: `method` + +**头文件**: `XCEngine/Core/LayerStack.h` + +## 签名 ```cpp ~LayerStack() = default; ``` -该方法声明于 `XCEngine/Core/LayerStack.h`，当前页面用于固定 `LayerStack` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +销毁 `LayerStack` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Core::LayerStack object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 当前为默认析构实现。 ## 相关文档 -- [返回类总览](LayerStack.md) -- [返回模块目录](../Core.md) +- [LayerStack](LayerStack.md) diff --git a/docs/api/XCEngine/Core/LayerStack/begin.md b/docs/api/XCEngine/Core/LayerStack/begin.md index 51c4ef98..d861118f 100644 --- a/docs/api/XCEngine/Core/LayerStack/begin.md +++ b/docs/api/XCEngine/Core/LayerStack/begin.md @@ -1,30 +1,26 @@ # LayerStack::begin -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Core` + +**类型**: `method` + +**头文件**: `XCEngine/Core/LayerStack.h` + +## 签名 ```cpp std::vector>::iterator begin(); ``` -该方法声明于 `XCEngine/Core/LayerStack.h`，当前页面用于固定 `LayerStack` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_layers`。 -**返回：** `std::vector>::iterator` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Core::LayerStack object; - // 根据上下文补齐参数后调用 LayerStack::begin(...)。 - (void)object; -} -``` +- 会更新 `m_layers`。 +- 当前实现会调用 `begin`。 ## 相关文档 -- [返回类总览](LayerStack.md) -- [返回模块目录](../Core.md) +- [LayerStack](LayerStack.md) diff --git a/docs/api/XCEngine/Core/LayerStack/cbegin.md b/docs/api/XCEngine/Core/LayerStack/cbegin.md index 3e3556f5..caa24dcb 100644 --- a/docs/api/XCEngine/Core/LayerStack/cbegin.md +++ b/docs/api/XCEngine/Core/LayerStack/cbegin.md @@ -1,30 +1,25 @@ # LayerStack::cbegin -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Core` + +**类型**: `method` + +**头文件**: `XCEngine/Core/LayerStack.h` + +## 签名 ```cpp std::vector>::const_iterator cbegin() const; ``` -该方法声明于 `XCEngine/Core/LayerStack.h`，当前页面用于固定 `LayerStack` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `cbegin` 对应的公开操作。 -**返回：** `std::vector>::const_iterator` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Core::LayerStack object; - // 根据上下文补齐参数后调用 LayerStack::cbegin(...)。 - (void)object; -} -``` +- 执行 `cbegin` 对应的公开操作。 ## 相关文档 -- [返回类总览](LayerStack.md) -- [返回模块目录](../Core.md) +- [LayerStack](LayerStack.md) diff --git a/docs/api/XCEngine/Core/LayerStack/cend.md b/docs/api/XCEngine/Core/LayerStack/cend.md index 38a26187..629475dc 100644 --- a/docs/api/XCEngine/Core/LayerStack/cend.md +++ b/docs/api/XCEngine/Core/LayerStack/cend.md @@ -1,30 +1,25 @@ # LayerStack::cend -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Core` + +**类型**: `method` + +**头文件**: `XCEngine/Core/LayerStack.h` + +## 签名 ```cpp std::vector>::const_iterator cend() const; ``` -该方法声明于 `XCEngine/Core/LayerStack.h`，当前页面用于固定 `LayerStack` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `cend` 对应的公开操作。 -**返回：** `std::vector>::const_iterator` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Core::LayerStack object; - // 根据上下文补齐参数后调用 LayerStack::cend(...)。 - (void)object; -} -``` +- 执行 `cend` 对应的公开操作。 ## 相关文档 -- [返回类总览](LayerStack.md) -- [返回模块目录](../Core.md) +- [LayerStack](LayerStack.md) diff --git a/docs/api/XCEngine/Core/LayerStack/crbegin.md b/docs/api/XCEngine/Core/LayerStack/crbegin.md index 6abfb5e9..558ec316 100644 --- a/docs/api/XCEngine/Core/LayerStack/crbegin.md +++ b/docs/api/XCEngine/Core/LayerStack/crbegin.md @@ -1,30 +1,25 @@ # LayerStack::crbegin -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Core` + +**类型**: `method` + +**头文件**: `XCEngine/Core/LayerStack.h` + +## 签名 ```cpp std::vector>::const_reverse_iterator crbegin() const; ``` -该方法声明于 `XCEngine/Core/LayerStack.h`，当前页面用于固定 `LayerStack` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `crbegin` 对应的公开操作。 -**返回：** `std::vector>::const_reverse_iterator` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Core::LayerStack object; - // 根据上下文补齐参数后调用 LayerStack::crbegin(...)。 - (void)object; -} -``` +- 执行 `crbegin` 对应的公开操作。 ## 相关文档 -- [返回类总览](LayerStack.md) -- [返回模块目录](../Core.md) +- [LayerStack](LayerStack.md) diff --git a/docs/api/XCEngine/Core/LayerStack/crend.md b/docs/api/XCEngine/Core/LayerStack/crend.md index 461dca7b..247f867c 100644 --- a/docs/api/XCEngine/Core/LayerStack/crend.md +++ b/docs/api/XCEngine/Core/LayerStack/crend.md @@ -1,30 +1,25 @@ # LayerStack::crend -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Core` + +**类型**: `method` + +**头文件**: `XCEngine/Core/LayerStack.h` + +## 签名 ```cpp std::vector>::const_reverse_iterator crend() const; ``` -该方法声明于 `XCEngine/Core/LayerStack.h`，当前页面用于固定 `LayerStack` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `crend` 对应的公开操作。 -**返回：** `std::vector>::const_reverse_iterator` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Core::LayerStack object; - // 根据上下文补齐参数后调用 LayerStack::crend(...)。 - (void)object; -} -``` +- 执行 `crend` 对应的公开操作。 ## 相关文档 -- [返回类总览](LayerStack.md) -- [返回模块目录](../Core.md) +- [LayerStack](LayerStack.md) diff --git a/docs/api/XCEngine/Core/LayerStack/end.md b/docs/api/XCEngine/Core/LayerStack/end.md index 97facc8a..1d0e9ece 100644 --- a/docs/api/XCEngine/Core/LayerStack/end.md +++ b/docs/api/XCEngine/Core/LayerStack/end.md @@ -1,30 +1,26 @@ # LayerStack::end -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Core` + +**类型**: `method` + +**头文件**: `XCEngine/Core/LayerStack.h` + +## 签名 ```cpp std::vector>::iterator end(); ``` -该方法声明于 `XCEngine/Core/LayerStack.h`，当前页面用于固定 `LayerStack` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_layers`。 -**返回：** `std::vector>::iterator` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Core::LayerStack object; - // 根据上下文补齐参数后调用 LayerStack::end(...)。 - (void)object; -} -``` +- 会更新 `m_layers`。 +- 当前实现会调用 `end`。 ## 相关文档 -- [返回类总览](LayerStack.md) -- [返回模块目录](../Core.md) +- [LayerStack](LayerStack.md) diff --git a/docs/api/XCEngine/Core/LayerStack/onAttach.md b/docs/api/XCEngine/Core/LayerStack/onAttach.md index 7c6c0df3..43126f4e 100644 --- a/docs/api/XCEngine/Core/LayerStack/onAttach.md +++ b/docs/api/XCEngine/Core/LayerStack/onAttach.md @@ -1,30 +1,25 @@ # LayerStack::onAttach -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Core` + +**类型**: `method` + +**头文件**: `XCEngine/Core/LayerStack.h` + +## 签名 ```cpp void onAttach(); ``` -该方法声明于 `XCEngine/Core/LayerStack.h`，当前页面用于固定 `LayerStack` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `onAttach` 对应的公开操作。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Core::LayerStack object; - // 根据上下文补齐参数后调用 LayerStack::onAttach(...)。 - (void)object; -} -``` +- 执行 `onAttach` 对应的公开操作。 ## 相关文档 -- [返回类总览](LayerStack.md) -- [返回模块目录](../Core.md) +- [LayerStack](LayerStack.md) diff --git a/docs/api/XCEngine/Core/LayerStack/onDetach.md b/docs/api/XCEngine/Core/LayerStack/onDetach.md index af59412e..9a55dbed 100644 --- a/docs/api/XCEngine/Core/LayerStack/onDetach.md +++ b/docs/api/XCEngine/Core/LayerStack/onDetach.md @@ -1,30 +1,25 @@ # LayerStack::onDetach -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Core` + +**类型**: `method` + +**头文件**: `XCEngine/Core/LayerStack.h` + +## 签名 ```cpp void onDetach(); ``` -该方法声明于 `XCEngine/Core/LayerStack.h`，当前页面用于固定 `LayerStack` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `onDetach` 对应的公开操作。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Core::LayerStack object; - // 根据上下文补齐参数后调用 LayerStack::onDetach(...)。 - (void)object; -} -``` +- 执行 `onDetach` 对应的公开操作。 ## 相关文档 -- [返回类总览](LayerStack.md) -- [返回模块目录](../Core.md) +- [LayerStack](LayerStack.md) diff --git a/docs/api/XCEngine/Core/LayerStack/onEvent.md b/docs/api/XCEngine/Core/LayerStack/onEvent.md index 4b9ae257..d65573c1 100644 --- a/docs/api/XCEngine/Core/LayerStack/onEvent.md +++ b/docs/api/XCEngine/Core/LayerStack/onEvent.md @@ -1,31 +1,25 @@ # LayerStack::onEvent -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Core` + +**类型**: `method` + +**头文件**: `XCEngine/Core/LayerStack.h` + +## 签名 ```cpp void onEvent(void* event); ``` -该方法声明于 `XCEngine/Core/LayerStack.h`，当前页面用于固定 `LayerStack` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `event` - 参数语义详见头文件声明。 +执行 `onEvent` 对应的公开操作。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Core::LayerStack object; - // 根据上下文补齐参数后调用 LayerStack::onEvent(...)。 - (void)object; -} -``` +- 执行 `onEvent` 对应的公开操作。 ## 相关文档 -- [返回类总览](LayerStack.md) -- [返回模块目录](../Core.md) +- [LayerStack](LayerStack.md) diff --git a/docs/api/XCEngine/Core/LayerStack/onImGuiRender.md b/docs/api/XCEngine/Core/LayerStack/onImGuiRender.md index da8d0721..d70f79ed 100644 --- a/docs/api/XCEngine/Core/LayerStack/onImGuiRender.md +++ b/docs/api/XCEngine/Core/LayerStack/onImGuiRender.md @@ -1,30 +1,25 @@ # LayerStack::onImGuiRender -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Core` + +**类型**: `method` + +**头文件**: `XCEngine/Core/LayerStack.h` + +## 签名 ```cpp void onImGuiRender(); ``` -该方法声明于 `XCEngine/Core/LayerStack.h`，当前页面用于固定 `LayerStack` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `onImGuiRender` 对应的公开操作。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Core::LayerStack object; - // 根据上下文补齐参数后调用 LayerStack::onImGuiRender(...)。 - (void)object; -} -``` +- 执行 `onImGuiRender` 对应的公开操作。 ## 相关文档 -- [返回类总览](LayerStack.md) -- [返回模块目录](../Core.md) +- [LayerStack](LayerStack.md) diff --git a/docs/api/XCEngine/Core/LayerStack/onUpdate.md b/docs/api/XCEngine/Core/LayerStack/onUpdate.md index 4fc54364..73f83e6d 100644 --- a/docs/api/XCEngine/Core/LayerStack/onUpdate.md +++ b/docs/api/XCEngine/Core/LayerStack/onUpdate.md @@ -1,31 +1,25 @@ # LayerStack::onUpdate -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Core` + +**类型**: `method` + +**头文件**: `XCEngine/Core/LayerStack.h` + +## 签名 ```cpp void onUpdate(float dt); ``` -该方法声明于 `XCEngine/Core/LayerStack.h`，当前页面用于固定 `LayerStack` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `dt` - 参数语义详见头文件声明。 +执行 `onUpdate` 对应的公开操作。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Core::LayerStack object; - // 根据上下文补齐参数后调用 LayerStack::onUpdate(...)。 - (void)object; -} -``` +- 执行 `onUpdate` 对应的公开操作。 ## 相关文档 -- [返回类总览](LayerStack.md) -- [返回模块目录](../Core.md) +- [LayerStack](LayerStack.md) diff --git a/docs/api/XCEngine/Core/LayerStack/popLayer.md b/docs/api/XCEngine/Core/LayerStack/popLayer.md index 7878c1a1..fc982aca 100644 --- a/docs/api/XCEngine/Core/LayerStack/popLayer.md +++ b/docs/api/XCEngine/Core/LayerStack/popLayer.md @@ -1,31 +1,25 @@ # LayerStack::popLayer -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Core` + +**类型**: `method` + +**头文件**: `XCEngine/Core/LayerStack.h` + +## 签名 ```cpp void popLayer(Layer* layer); ``` -该方法声明于 `XCEngine/Core/LayerStack.h`，当前页面用于固定 `LayerStack` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `layer` - 参数语义详见头文件声明。 +执行 `popLayer` 对应的公开操作。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Core::LayerStack object; - // 根据上下文补齐参数后调用 LayerStack::popLayer(...)。 - (void)object; -} -``` +- 执行 `popLayer` 对应的公开操作。 ## 相关文档 -- [返回类总览](LayerStack.md) -- [返回模块目录](../Core.md) +- [LayerStack](LayerStack.md) diff --git a/docs/api/XCEngine/Core/LayerStack/popOverlay.md b/docs/api/XCEngine/Core/LayerStack/popOverlay.md index 3250faef..d7361ea3 100644 --- a/docs/api/XCEngine/Core/LayerStack/popOverlay.md +++ b/docs/api/XCEngine/Core/LayerStack/popOverlay.md @@ -1,31 +1,25 @@ # LayerStack::popOverlay -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Core` + +**类型**: `method` + +**头文件**: `XCEngine/Core/LayerStack.h` + +## 签名 ```cpp void popOverlay(Layer* overlay); ``` -该方法声明于 `XCEngine/Core/LayerStack.h`，当前页面用于固定 `LayerStack` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `overlay` - 参数语义详见头文件声明。 +执行 `popOverlay` 对应的公开操作。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Core::LayerStack object; - // 根据上下文补齐参数后调用 LayerStack::popOverlay(...)。 - (void)object; -} -``` +- 执行 `popOverlay` 对应的公开操作。 ## 相关文档 -- [返回类总览](LayerStack.md) -- [返回模块目录](../Core.md) +- [LayerStack](LayerStack.md) diff --git a/docs/api/XCEngine/Core/LayerStack/pushLayer.md b/docs/api/XCEngine/Core/LayerStack/pushLayer.md index 388af659..ff9a9565 100644 --- a/docs/api/XCEngine/Core/LayerStack/pushLayer.md +++ b/docs/api/XCEngine/Core/LayerStack/pushLayer.md @@ -1,31 +1,25 @@ # LayerStack::pushLayer -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Core` + +**类型**: `method` + +**头文件**: `XCEngine/Core/LayerStack.h` + +## 签名 ```cpp void pushLayer(std::unique_ptr layer); ``` -该方法声明于 `XCEngine/Core/LayerStack.h`，当前页面用于固定 `LayerStack` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `layer` - 参数语义详见头文件声明。 +执行 `pushLayer` 对应的公开操作。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Core::LayerStack object; - // 根据上下文补齐参数后调用 LayerStack::pushLayer(...)。 - (void)object; -} -``` +- 执行 `pushLayer` 对应的公开操作。 ## 相关文档 -- [返回类总览](LayerStack.md) -- [返回模块目录](../Core.md) +- [LayerStack](LayerStack.md) diff --git a/docs/api/XCEngine/Core/LayerStack/pushOverlay.md b/docs/api/XCEngine/Core/LayerStack/pushOverlay.md index 8d0b8bc8..80696efe 100644 --- a/docs/api/XCEngine/Core/LayerStack/pushOverlay.md +++ b/docs/api/XCEngine/Core/LayerStack/pushOverlay.md @@ -1,31 +1,25 @@ # LayerStack::pushOverlay -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Core` + +**类型**: `method` + +**头文件**: `XCEngine/Core/LayerStack.h` + +## 签名 ```cpp void pushOverlay(std::unique_ptr overlay); ``` -该方法声明于 `XCEngine/Core/LayerStack.h`，当前页面用于固定 `LayerStack` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `overlay` - 参数语义详见头文件声明。 +执行 `pushOverlay` 对应的公开操作。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Core::LayerStack object; - // 根据上下文补齐参数后调用 LayerStack::pushOverlay(...)。 - (void)object; -} -``` +- 执行 `pushOverlay` 对应的公开操作。 ## 相关文档 -- [返回类总览](LayerStack.md) -- [返回模块目录](../Core.md) +- [LayerStack](LayerStack.md) diff --git a/docs/api/XCEngine/Core/LayerStack/rbegin.md b/docs/api/XCEngine/Core/LayerStack/rbegin.md index 4922d73e..8a309b63 100644 --- a/docs/api/XCEngine/Core/LayerStack/rbegin.md +++ b/docs/api/XCEngine/Core/LayerStack/rbegin.md @@ -1,30 +1,26 @@ # LayerStack::rbegin -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Core` + +**类型**: `method` + +**头文件**: `XCEngine/Core/LayerStack.h` + +## 签名 ```cpp std::vector>::reverse_iterator rbegin(); ``` -该方法声明于 `XCEngine/Core/LayerStack.h`，当前页面用于固定 `LayerStack` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_layers`。 -**返回：** `std::vector>::reverse_iterator` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Core::LayerStack object; - // 根据上下文补齐参数后调用 LayerStack::rbegin(...)。 - (void)object; -} -``` +- 会更新 `m_layers`。 +- 当前实现会调用 `rbegin`。 ## 相关文档 -- [返回类总览](LayerStack.md) -- [返回模块目录](../Core.md) +- [LayerStack](LayerStack.md) diff --git a/docs/api/XCEngine/Core/LayerStack/rend.md b/docs/api/XCEngine/Core/LayerStack/rend.md index b3e53616..db2c412e 100644 --- a/docs/api/XCEngine/Core/LayerStack/rend.md +++ b/docs/api/XCEngine/Core/LayerStack/rend.md @@ -1,30 +1,26 @@ # LayerStack::rend -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Core` + +**类型**: `method` + +**头文件**: `XCEngine/Core/LayerStack.h` + +## 签名 ```cpp std::vector>::reverse_iterator rend(); ``` -该方法声明于 `XCEngine/Core/LayerStack.h`，当前页面用于固定 `LayerStack` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_layers`。 -**返回：** `std::vector>::reverse_iterator` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Core::LayerStack object; - // 根据上下文补齐参数后调用 LayerStack::rend(...)。 - (void)object; -} -``` +- 会更新 `m_layers`。 +- 当前实现会调用 `rend`。 ## 相关文档 -- [返回类总览](LayerStack.md) -- [返回模块目录](../Core.md) +- [LayerStack](LayerStack.md) diff --git a/docs/api/XCEngine/Core/Math/Bounds/Bounds.md b/docs/api/XCEngine/Core/Math/Bounds/Bounds.md index 43cf9b2a..6537557c 100644 --- a/docs/api/XCEngine/Core/Math/Bounds/Bounds.md +++ b/docs/api/XCEngine/Core/Math/Bounds/Bounds.md @@ -32,7 +32,7 @@ - `GetClosestPoint(point)` 会把点 clamp 到包围盒内部。 - `GetVolume()` 返回完整尺寸乘积，而不是 `extents` 乘积。 -按 `tests/math/test_geometry.cpp`，当前 `Bounds` 的默认构造、参数构造、最值、包含、相交、包裹、扩张、体积和最近点都有测试覆盖。 +按 `tests/Core/Math/test_geometry.cpp`，当前 `Bounds` 的默认构造、参数构造、最值、包含、相交、包裹、扩张、体积和最近点都有测试覆盖。 ## 生命周期 diff --git a/docs/api/XCEngine/Core/Math/Frustum/Contains.md b/docs/api/XCEngine/Core/Math/Frustum/Contains.md index b93dd607..0da1a7e6 100644 --- a/docs/api/XCEngine/Core/Math/Frustum/Contains.md +++ b/docs/api/XCEngine/Core/Math/Frustum/Contains.md @@ -1,55 +1,27 @@ # Frustum::Contains -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Math` -该方法在 `XCEngine/Core/Math/Frustum.h` 中提供了 3 个重载，当前页面统一汇总这些公开声明。 +**类型**: `method` -## 重载 1: 声明 +**头文件**: `XCEngine/Core/Math/Frustum.h` + +## 签名 ```cpp bool Contains(const Vector3& point) const; -``` - -**参数：** -- `point` - 参数语义详见头文件声明。 - -**返回：** `bool` - 返回值语义详见头文件声明。 - -## 重载 2: 声明 - -```cpp bool Contains(const Sphere& sphere) const; -``` - -**参数：** -- `sphere` - 参数语义详见头文件声明。 - -**返回：** `bool` - 返回值语义详见头文件声明。 - -## 重载 3: 声明 - -```cpp bool Contains(const Bounds& bounds) const; ``` -**参数：** -- `bounds` - 参数语义详见头文件声明。 +## 作用 -**返回：** `bool` - 返回值语义详见头文件声明。 +执行 `Contains` 对应的公开操作。 -**示例：** +## 当前实现 -```cpp -#include - -void Example() { - XCEngine::Math::Frustum object; - // 根据上下文补齐参数后调用 Frustum::Contains(...)。 - (void)object; -} -``` +- 执行 `Contains` 对应的公开操作。 ## 相关文档 -- [返回类总览](Frustum.md) -- [返回模块目录](../Math.md) +- [Frustum](Frustum.md) diff --git a/docs/api/XCEngine/Core/Math/Frustum/Frustum.md b/docs/api/XCEngine/Core/Math/Frustum/Frustum.md index 544c9fc6..e8e6f069 100644 --- a/docs/api/XCEngine/Core/Math/Frustum/Frustum.md +++ b/docs/api/XCEngine/Core/Math/Frustum/Frustum.md @@ -27,7 +27,7 @@ - `Contains(bounds)` 会检查 8 个角点是否对某个平面全部落在负侧；只要不存在这种“整盒都在某平面外侧”的情况，就返回 `true`。 - `Intersects(bounds)` 也基本是同一思路；当前实现里 `allPositive` 变量没有实质作用。 -按 `tests/math/test_geometry.cpp`，当前有对点、球体和 `Bounds` 的基础测试，但测试构造都非常轻量，通常只手动设置一个 near plane。 +按 `tests/Core/Math/test_geometry.cpp`，当前有对点、球体和 `Bounds` 的基础测试，但测试构造都非常轻量，通常只手动设置一个 near plane。 ## 生命周期 diff --git a/docs/api/XCEngine/Core/Math/Frustum/Intersects.md b/docs/api/XCEngine/Core/Math/Frustum/Intersects.md index 7b62ba0c..96a1b217 100644 --- a/docs/api/XCEngine/Core/Math/Frustum/Intersects.md +++ b/docs/api/XCEngine/Core/Math/Frustum/Intersects.md @@ -1,44 +1,26 @@ # Frustum::Intersects -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Math` -该方法在 `XCEngine/Core/Math/Frustum.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。 +**类型**: `method` -## 重载 1: 声明 +**头文件**: `XCEngine/Core/Math/Frustum.h` + +## 签名 ```cpp bool Intersects(const Bounds& bounds) const; -``` - -**参数：** -- `bounds` - 参数语义详见头文件声明。 - -**返回：** `bool` - 返回值语义详见头文件声明。 - -## 重载 2: 声明 - -```cpp bool Intersects(const Sphere& sphere) const; ``` -**参数：** -- `sphere` - 参数语义详见头文件声明。 +## 作用 -**返回：** `bool` - 返回值语义详见头文件声明。 +执行 `Intersects` 对应的公开操作。 -**示例：** +## 当前实现 -```cpp -#include - -void Example() { - XCEngine::Math::Frustum object; - // 根据上下文补齐参数后调用 Frustum::Intersects(...)。 - (void)object; -} -``` +- 执行 `Intersects` 对应的公开操作。 ## 相关文档 -- [返回类总览](Frustum.md) -- [返回模块目录](../Math.md) +- [Frustum](Frustum.md) diff --git a/docs/api/XCEngine/Core/Math/Matrix3/Constructor.md b/docs/api/XCEngine/Core/Math/Matrix3/Constructor.md index 2063cdfa..8d3efaba 100644 --- a/docs/api/XCEngine/Core/Math/Matrix3/Constructor.md +++ b/docs/api/XCEngine/Core/Math/Matrix3/Constructor.md @@ -1,28 +1,25 @@ # Matrix3x3::Matrix3x3() -构造对象。 +**命名空间**: `XCEngine::Math` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Math/Matrix3.h` + +## 签名 ```cpp Matrix3x3(); ``` -该方法声明于 `XCEngine/Core/Math/Matrix3.h`，当前页面用于固定 `Matrix3x3` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行该公开方法对应的当前实现。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Math::Matrix3x3 object; -} -``` +- 执行该公开方法对应的当前实现。 ## 相关文档 -- [返回类总览](Matrix3.md) -- [返回模块目录](../Math.md) +- [Matrix3x3](Matrix3.md) diff --git a/docs/api/XCEngine/Core/Math/Matrix3/Determinant.md b/docs/api/XCEngine/Core/Math/Matrix3/Determinant.md index 3a370d65..a4b1023a 100644 --- a/docs/api/XCEngine/Core/Math/Matrix3/Determinant.md +++ b/docs/api/XCEngine/Core/Math/Matrix3/Determinant.md @@ -1,30 +1,25 @@ # Matrix3x3::Determinant -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Math` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Math/Matrix3.h` + +## 签名 ```cpp float Determinant() const; ``` -该方法声明于 `XCEngine/Core/Math/Matrix3.h`，当前页面用于固定 `Matrix3x3` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `Determinant` 对应的公开操作。 -**返回：** `float` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Math::Matrix3x3 object; - // 根据上下文补齐参数后调用 Matrix3x3::Determinant(...)。 - (void)object; -} -``` +- 执行 `Determinant` 对应的公开操作。 ## 相关文档 -- [返回类总览](Matrix3.md) -- [返回模块目录](../Math.md) +- [Matrix3x3](Matrix3.md) diff --git a/docs/api/XCEngine/Core/Math/Matrix3/Identity.md b/docs/api/XCEngine/Core/Math/Matrix3/Identity.md index 147ed2a4..abd44beb 100644 --- a/docs/api/XCEngine/Core/Math/Matrix3/Identity.md +++ b/docs/api/XCEngine/Core/Math/Matrix3/Identity.md @@ -1,30 +1,25 @@ # Matrix3x3::Identity -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Math` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Math/Matrix3.h` + +## 签名 ```cpp static Matrix3x3 Identity(); ``` -该方法声明于 `XCEngine/Core/Math/Matrix3.h`，当前页面用于固定 `Matrix3x3` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `result`。 -**返回：** `Matrix3x3` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Math::Matrix3x3 object; - // 根据上下文补齐参数后调用 Matrix3x3::Identity(...)。 - (void)object; -} -``` +- 返回 `result`。 ## 相关文档 -- [返回类总览](Matrix3.md) -- [返回模块目录](../Math.md) +- [Matrix3x3](Matrix3.md) diff --git a/docs/api/XCEngine/Core/Math/Matrix3/Inverse.md b/docs/api/XCEngine/Core/Math/Matrix3/Inverse.md index c06360e2..23564775 100644 --- a/docs/api/XCEngine/Core/Math/Matrix3/Inverse.md +++ b/docs/api/XCEngine/Core/Math/Matrix3/Inverse.md @@ -1,30 +1,25 @@ # Matrix3x3::Inverse -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Math` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Math/Matrix3.h` + +## 签名 ```cpp Matrix3x3 Inverse() const; ``` -该方法声明于 `XCEngine/Core/Math/Matrix3.h`，当前页面用于固定 `Matrix3x3` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `Inverse` 对应的公开操作。 -**返回：** `Matrix3x3` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Math::Matrix3x3 object; - // 根据上下文补齐参数后调用 Matrix3x3::Inverse(...)。 - (void)object; -} -``` +- 执行 `Inverse` 对应的公开操作。 ## 相关文档 -- [返回类总览](Matrix3.md) -- [返回模块目录](../Math.md) +- [Matrix3x3](Matrix3.md) diff --git a/docs/api/XCEngine/Core/Math/Matrix3/OperatorMultiply.md b/docs/api/XCEngine/Core/Math/Matrix3/OperatorMultiply.md index 7ec18bb1..93adf72c 100644 --- a/docs/api/XCEngine/Core/Math/Matrix3/OperatorMultiply.md +++ b/docs/api/XCEngine/Core/Math/Matrix3/OperatorMultiply.md @@ -1,44 +1,26 @@ # Matrix3x3::operator* -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Math` -该方法在 `XCEngine/Core/Math/Matrix3.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。 +**类型**: `method` -## 重载 1: 声明 +**头文件**: `XCEngine/Core/Math/Matrix3.h` + +## 签名 ```cpp Matrix3x3 operator*(const Matrix3x3& other) const; -``` - -**参数：** -- `other` - 参数语义详见头文件声明。 - -**返回：** `Matrix3x3` - 返回值语义详见头文件声明。 - -## 重载 2: 声明 - -```cpp Vector3 operator*(const Vector3& v) const; ``` -**参数：** -- `v` - 参数语义详见头文件声明。 +## 作用 -**返回：** `Vector3` - 返回值语义详见头文件声明。 +执行 `operator*` 对应的公开操作。 -**示例：** +## 当前实现 -```cpp -#include - -void Example() { - XCEngine::Math::Matrix3x3 object; - // 根据上下文补齐参数后调用 Matrix3x3::operator*(...)。 - (void)object; -} -``` +- 执行 `operator*` 对应的公开操作。 ## 相关文档 -- [返回类总览](Matrix3.md) -- [返回模块目录](../Math.md) +- [Matrix3x3](Matrix3.md) diff --git a/docs/api/XCEngine/Core/Math/Matrix3/OperatorSubscript.md b/docs/api/XCEngine/Core/Math/Matrix3/OperatorSubscript.md index 1bed8a7b..f948609d 100644 --- a/docs/api/XCEngine/Core/Math/Matrix3/OperatorSubscript.md +++ b/docs/api/XCEngine/Core/Math/Matrix3/OperatorSubscript.md @@ -1,44 +1,26 @@ # Matrix3x3::operator[] -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Math` -该方法在 `XCEngine/Core/Math/Matrix3.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。 +**类型**: `method` -## 重载 1: 声明 +**头文件**: `XCEngine/Core/Math/Matrix3.h` + +## 签名 ```cpp float* operator[](int row); -``` - -**参数：** -- `row` - 参数语义详见头文件声明。 - -**返回：** `float*` - 返回值语义详见头文件声明。 - -## 重载 2: 声明 - -```cpp const float* operator[](int row) const; ``` -**参数：** -- `row` - 参数语义详见头文件声明。 +## 作用 -**返回：** `const float*` - 返回值语义详见头文件声明。 +返回 `m[row]`。 -**示例：** +## 当前实现 -```cpp -#include - -void Example() { - XCEngine::Math::Matrix3x3 object; - // 根据上下文补齐参数后调用 Matrix3x3::operator[](...)。 - (void)object; -} -``` +- 返回 `m[row]`。 ## 相关文档 -- [返回类总览](Matrix3.md) -- [返回模块目录](../Math.md) +- [Matrix3x3](Matrix3.md) diff --git a/docs/api/XCEngine/Core/Math/Matrix3/RotationX.md b/docs/api/XCEngine/Core/Math/Matrix3/RotationX.md index 26a93da2..c9b3d500 100644 --- a/docs/api/XCEngine/Core/Math/Matrix3/RotationX.md +++ b/docs/api/XCEngine/Core/Math/Matrix3/RotationX.md @@ -1,31 +1,25 @@ # Matrix3x3::RotationX -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Math` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Math/Matrix3.h` + +## 签名 ```cpp static Matrix3x3 RotationX(float radians); ``` -该方法声明于 `XCEngine/Core/Math/Matrix3.h`，当前页面用于固定 `Matrix3x3` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `radians` - 参数语义详见头文件声明。 +执行 `RotationX` 对应的公开操作。 -**返回：** `Matrix3x3` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Math::Matrix3x3 object; - // 根据上下文补齐参数后调用 Matrix3x3::RotationX(...)。 - (void)object; -} -``` +- 执行 `RotationX` 对应的公开操作。 ## 相关文档 -- [返回类总览](Matrix3.md) -- [返回模块目录](../Math.md) +- [Matrix3x3](Matrix3.md) diff --git a/docs/api/XCEngine/Core/Math/Matrix3/RotationY.md b/docs/api/XCEngine/Core/Math/Matrix3/RotationY.md index 3c43ed0e..665187cc 100644 --- a/docs/api/XCEngine/Core/Math/Matrix3/RotationY.md +++ b/docs/api/XCEngine/Core/Math/Matrix3/RotationY.md @@ -1,31 +1,25 @@ # Matrix3x3::RotationY -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Math` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Math/Matrix3.h` + +## 签名 ```cpp static Matrix3x3 RotationY(float radians); ``` -该方法声明于 `XCEngine/Core/Math/Matrix3.h`，当前页面用于固定 `Matrix3x3` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `radians` - 参数语义详见头文件声明。 +执行 `RotationY` 对应的公开操作。 -**返回：** `Matrix3x3` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Math::Matrix3x3 object; - // 根据上下文补齐参数后调用 Matrix3x3::RotationY(...)。 - (void)object; -} -``` +- 执行 `RotationY` 对应的公开操作。 ## 相关文档 -- [返回类总览](Matrix3.md) -- [返回模块目录](../Math.md) +- [Matrix3x3](Matrix3.md) diff --git a/docs/api/XCEngine/Core/Math/Matrix3/RotationZ.md b/docs/api/XCEngine/Core/Math/Matrix3/RotationZ.md index 80a70411..d1f85221 100644 --- a/docs/api/XCEngine/Core/Math/Matrix3/RotationZ.md +++ b/docs/api/XCEngine/Core/Math/Matrix3/RotationZ.md @@ -1,31 +1,25 @@ # Matrix3x3::RotationZ -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Math` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Math/Matrix3.h` + +## 签名 ```cpp static Matrix3x3 RotationZ(float radians); ``` -该方法声明于 `XCEngine/Core/Math/Matrix3.h`，当前页面用于固定 `Matrix3x3` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `radians` - 参数语义详见头文件声明。 +执行 `RotationZ` 对应的公开操作。 -**返回：** `Matrix3x3` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Math::Matrix3x3 object; - // 根据上下文补齐参数后调用 Matrix3x3::RotationZ(...)。 - (void)object; -} -``` +- 执行 `RotationZ` 对应的公开操作。 ## 相关文档 -- [返回类总览](Matrix3.md) -- [返回模块目录](../Math.md) +- [Matrix3x3](Matrix3.md) diff --git a/docs/api/XCEngine/Core/Math/Matrix3/Scale.md b/docs/api/XCEngine/Core/Math/Matrix3/Scale.md index 9278502a..f2919f00 100644 --- a/docs/api/XCEngine/Core/Math/Matrix3/Scale.md +++ b/docs/api/XCEngine/Core/Math/Matrix3/Scale.md @@ -1,31 +1,25 @@ # Matrix3x3::Scale -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Math` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Math/Matrix3.h` + +## 签名 ```cpp static Matrix3x3 Scale(const Vector3& scale); ``` -该方法声明于 `XCEngine/Core/Math/Matrix3.h`，当前页面用于固定 `Matrix3x3` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `scale` - 参数语义详见头文件声明。 +执行 `Scale` 对应的公开操作。 -**返回：** `Matrix3x3` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Math::Matrix3x3 object; - // 根据上下文补齐参数后调用 Matrix3x3::Scale(...)。 - (void)object; -} -``` +- 执行 `Scale` 对应的公开操作。 ## 相关文档 -- [返回类总览](Matrix3.md) -- [返回模块目录](../Math.md) +- [Matrix3x3](Matrix3.md) diff --git a/docs/api/XCEngine/Core/Math/Matrix3/Transpose.md b/docs/api/XCEngine/Core/Math/Matrix3/Transpose.md index a1b5d5c7..d453b42b 100644 --- a/docs/api/XCEngine/Core/Math/Matrix3/Transpose.md +++ b/docs/api/XCEngine/Core/Math/Matrix3/Transpose.md @@ -1,30 +1,25 @@ # Matrix3x3::Transpose -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Math` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Math/Matrix3.h` + +## 签名 ```cpp Matrix3x3 Transpose() const; ``` -该方法声明于 `XCEngine/Core/Math/Matrix3.h`，当前页面用于固定 `Matrix3x3` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `Transpose` 对应的公开操作。 -**返回：** `Matrix3x3` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Math::Matrix3x3 object; - // 根据上下文补齐参数后调用 Matrix3x3::Transpose(...)。 - (void)object; -} -``` +- 执行 `Transpose` 对应的公开操作。 ## 相关文档 -- [返回类总览](Matrix3.md) -- [返回模块目录](../Math.md) +- [Matrix3x3](Matrix3.md) diff --git a/docs/api/XCEngine/Core/Math/Matrix3/Zero.md b/docs/api/XCEngine/Core/Math/Matrix3/Zero.md index 1b06cea0..c7b0db2a 100644 --- a/docs/api/XCEngine/Core/Math/Matrix3/Zero.md +++ b/docs/api/XCEngine/Core/Math/Matrix3/Zero.md @@ -1,30 +1,25 @@ # Matrix3x3::Zero -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Math` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Math/Matrix3.h` + +## 签名 ```cpp static Matrix3x3 Zero(); ``` -该方法声明于 `XCEngine/Core/Math/Matrix3.h`，当前页面用于固定 `Matrix3x3` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `Matrix3x3(...)` 相关流程。 -**返回：** `Matrix3x3` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Math::Matrix3x3 object; - // 根据上下文补齐参数后调用 Matrix3x3::Zero(...)。 - (void)object; -} -``` +- 当前实现会调用 `Matrix3x3`。 ## 相关文档 -- [返回类总览](Matrix3.md) -- [返回模块目录](../Math.md) +- [Matrix3x3](Matrix3.md) diff --git a/docs/api/XCEngine/Core/Math/Matrix4/Constructor.md b/docs/api/XCEngine/Core/Math/Matrix4/Constructor.md index 6341dede..7ab5b0eb 100644 --- a/docs/api/XCEngine/Core/Math/Matrix4/Constructor.md +++ b/docs/api/XCEngine/Core/Math/Matrix4/Constructor.md @@ -1,28 +1,25 @@ # Matrix4x4::Matrix4x4() -构造对象。 +**命名空间**: `XCEngine::Math` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Math/Matrix4.h` + +## 签名 ```cpp Matrix4x4(); ``` -该方法声明于 `XCEngine/Core/Math/Matrix4.h`，当前页面用于固定 `Matrix4x4` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行该公开方法对应的当前实现。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Math::Matrix4x4 object; -} -``` +- 执行该公开方法对应的当前实现。 ## 相关文档 -- [返回类总览](Matrix4.md) -- [返回模块目录](../Math.md) +- [Matrix4x4](Matrix4.md) diff --git a/docs/api/XCEngine/Core/Math/Matrix4/Decompose.md b/docs/api/XCEngine/Core/Math/Matrix4/Decompose.md index 369aef8a..30274501 100644 --- a/docs/api/XCEngine/Core/Math/Matrix4/Decompose.md +++ b/docs/api/XCEngine/Core/Math/Matrix4/Decompose.md @@ -1,33 +1,25 @@ # Matrix4x4::Decompose -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Math` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Math/Matrix4.h` + +## 签名 ```cpp void Decompose(Vector3& translation, Quaternion& rotation, Vector3& scale) const; ``` -该方法声明于 `XCEngine/Core/Math/Matrix4.h`，当前页面用于固定 `Matrix4x4` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `translation` - 参数语义详见头文件声明。 -- `rotation` - 参数语义详见头文件声明。 -- `scale` - 参数语义详见头文件声明。 +执行 `Decompose` 对应的公开操作。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Math::Matrix4x4 object; - // 根据上下文补齐参数后调用 Matrix4x4::Decompose(...)。 - (void)object; -} -``` +- 执行 `Decompose` 对应的公开操作。 ## 相关文档 -- [返回类总览](Matrix4.md) -- [返回模块目录](../Math.md) +- [Matrix4x4](Matrix4.md) diff --git a/docs/api/XCEngine/Core/Math/Matrix4/Determinant.md b/docs/api/XCEngine/Core/Math/Matrix4/Determinant.md index 6c11ecf3..2eb296ed 100644 --- a/docs/api/XCEngine/Core/Math/Matrix4/Determinant.md +++ b/docs/api/XCEngine/Core/Math/Matrix4/Determinant.md @@ -1,30 +1,25 @@ # Matrix4x4::Determinant -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Math` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Math/Matrix4.h` + +## 签名 ```cpp float Determinant() const; ``` -该方法声明于 `XCEngine/Core/Math/Matrix4.h`，当前页面用于固定 `Matrix4x4` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `Determinant` 对应的公开操作。 -**返回：** `float` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Math::Matrix4x4 object; - // 根据上下文补齐参数后调用 Matrix4x4::Determinant(...)。 - (void)object; -} -``` +- 执行 `Determinant` 对应的公开操作。 ## 相关文档 -- [返回类总览](Matrix4.md) -- [返回模块目录](../Math.md) +- [Matrix4x4](Matrix4.md) diff --git a/docs/api/XCEngine/Core/Math/Matrix4/GetRotation.md b/docs/api/XCEngine/Core/Math/Matrix4/GetRotation.md index a5176a0a..f4d5ba35 100644 --- a/docs/api/XCEngine/Core/Math/Matrix4/GetRotation.md +++ b/docs/api/XCEngine/Core/Math/Matrix4/GetRotation.md @@ -1,30 +1,25 @@ # Matrix4x4::GetRotation -获取相关状态或对象。 +**命名空间**: `XCEngine::Math` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Math/Matrix4.h` + +## 签名 ```cpp Quaternion GetRotation() const; ``` -该方法声明于 `XCEngine/Core/Math/Matrix4.h`，当前页面用于固定 `Matrix4x4` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `Rotation` 相关结果。 -**返回：** `Quaternion` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Math::Matrix4x4 object; - // 根据上下文补齐参数后调用 Matrix4x4::GetRotation(...)。 - (void)object; -} -``` +- 返回 `Rotation` 相关结果。 ## 相关文档 -- [返回类总览](Matrix4.md) -- [返回模块目录](../Math.md) +- [Matrix4x4](Matrix4.md) diff --git a/docs/api/XCEngine/Core/Math/Matrix4/GetScale.md b/docs/api/XCEngine/Core/Math/Matrix4/GetScale.md index 92ee5e64..57f44d1c 100644 --- a/docs/api/XCEngine/Core/Math/Matrix4/GetScale.md +++ b/docs/api/XCEngine/Core/Math/Matrix4/GetScale.md @@ -1,30 +1,25 @@ # Matrix4x4::GetScale -获取相关状态或对象。 +**命名空间**: `XCEngine::Math` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Math/Matrix4.h` + +## 签名 ```cpp Vector3 GetScale() const; ``` -该方法声明于 `XCEngine/Core/Math/Matrix4.h`，当前页面用于固定 `Matrix4x4` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `Scale` 相关结果。 -**返回：** `Vector3` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Math::Matrix4x4 object; - // 根据上下文补齐参数后调用 Matrix4x4::GetScale(...)。 - (void)object; -} -``` +- 返回 `Scale` 相关结果。 ## 相关文档 -- [返回类总览](Matrix4.md) -- [返回模块目录](../Math.md) +- [Matrix4x4](Matrix4.md) diff --git a/docs/api/XCEngine/Core/Math/Matrix4/GetTranslation.md b/docs/api/XCEngine/Core/Math/Matrix4/GetTranslation.md index 086124d3..82b3055b 100644 --- a/docs/api/XCEngine/Core/Math/Matrix4/GetTranslation.md +++ b/docs/api/XCEngine/Core/Math/Matrix4/GetTranslation.md @@ -1,30 +1,25 @@ # Matrix4x4::GetTranslation -获取相关状态或对象。 +**命名空间**: `XCEngine::Math` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Math/Matrix4.h` + +## 签名 ```cpp Vector3 GetTranslation() const; ``` -该方法声明于 `XCEngine/Core/Math/Matrix4.h`，当前页面用于固定 `Matrix4x4` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `Translation` 相关结果。 -**返回：** `Vector3` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Math::Matrix4x4 object; - // 根据上下文补齐参数后调用 Matrix4x4::GetTranslation(...)。 - (void)object; -} -``` +- 返回 `Translation` 相关结果。 ## 相关文档 -- [返回类总览](Matrix4.md) -- [返回模块目录](../Math.md) +- [Matrix4x4](Matrix4.md) diff --git a/docs/api/XCEngine/Core/Math/Matrix4/Identity.md b/docs/api/XCEngine/Core/Math/Matrix4/Identity.md index b3da4d1e..9b3a449e 100644 --- a/docs/api/XCEngine/Core/Math/Matrix4/Identity.md +++ b/docs/api/XCEngine/Core/Math/Matrix4/Identity.md @@ -1,30 +1,25 @@ # Matrix4x4::Identity -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Math` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Math/Matrix4.h` + +## 签名 ```cpp static Matrix4x4 Identity(); ``` -该方法声明于 `XCEngine/Core/Math/Matrix4.h`，当前页面用于固定 `Matrix4x4` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `result`。 -**返回：** `Matrix4x4` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Math::Matrix4x4 object; - // 根据上下文补齐参数后调用 Matrix4x4::Identity(...)。 - (void)object; -} -``` +- 返回 `result`。 ## 相关文档 -- [返回类总览](Matrix4.md) -- [返回模块目录](../Math.md) +- [Matrix4x4](Matrix4.md) diff --git a/docs/api/XCEngine/Core/Math/Matrix4/Inverse.md b/docs/api/XCEngine/Core/Math/Matrix4/Inverse.md index 53f66180..37730ae4 100644 --- a/docs/api/XCEngine/Core/Math/Matrix4/Inverse.md +++ b/docs/api/XCEngine/Core/Math/Matrix4/Inverse.md @@ -1,30 +1,25 @@ # Matrix4x4::Inverse -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Math` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Math/Matrix4.h` + +## 签名 ```cpp Matrix4x4 Inverse() const; ``` -该方法声明于 `XCEngine/Core/Math/Matrix4.h`，当前页面用于固定 `Matrix4x4` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `Inverse` 对应的公开操作。 -**返回：** `Matrix4x4` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Math::Matrix4x4 object; - // 根据上下文补齐参数后调用 Matrix4x4::Inverse(...)。 - (void)object; -} -``` +- 执行 `Inverse` 对应的公开操作。 ## 相关文档 -- [返回类总览](Matrix4.md) -- [返回模块目录](../Math.md) +- [Matrix4x4](Matrix4.md) diff --git a/docs/api/XCEngine/Core/Math/Matrix4/LookAt.md b/docs/api/XCEngine/Core/Math/Matrix4/LookAt.md index 53f4e46e..2ef0f7a1 100644 --- a/docs/api/XCEngine/Core/Math/Matrix4/LookAt.md +++ b/docs/api/XCEngine/Core/Math/Matrix4/LookAt.md @@ -1,33 +1,25 @@ # Matrix4x4::LookAt -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Math` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Math/Matrix4.h` + +## 签名 ```cpp static Matrix4x4 LookAt(const Vector3& eye, const Vector3& target, const Vector3& up); ``` -该方法声明于 `XCEngine/Core/Math/Matrix4.h`，当前页面用于固定 `Matrix4x4` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `eye` - 参数语义详见头文件声明。 -- `target` - 参数语义详见头文件声明。 -- `up` - 参数语义详见头文件声明。 +执行 `LookAt` 对应的公开操作。 -**返回：** `Matrix4x4` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Math::Matrix4x4 object; - // 根据上下文补齐参数后调用 Matrix4x4::LookAt(...)。 - (void)object; -} -``` +- 执行 `LookAt` 对应的公开操作。 ## 相关文档 -- [返回类总览](Matrix4.md) -- [返回模块目录](../Math.md) +- [Matrix4x4](Matrix4.md) diff --git a/docs/api/XCEngine/Core/Math/Matrix4/Matrix4.md b/docs/api/XCEngine/Core/Math/Matrix4/Matrix4.md index 772d3c18..57085c25 100644 --- a/docs/api/XCEngine/Core/Math/Matrix4/Matrix4.md +++ b/docs/api/XCEngine/Core/Math/Matrix4/Matrix4.md @@ -31,7 +31,7 @@ - `MultiplyPoint()` 会把输入当作 `w = 1` 的点参与计算。 - `MultiplyVector()` 会把输入当作 `w = 0` 的方向向量参与计算，因此不受平移影响。 -按当前源码和 `tests/math/test_matrix.cpp`，下面几项行为是有测试支撑的： +按当前源码和 `tests/Core/Math/test_matrix.cpp`，下面几项行为是有测试支撑的： - 基础平移、缩放、绕轴旋转 - `TRS()` 组合 diff --git a/docs/api/XCEngine/Core/Math/Matrix4/MultiplyPoint.md b/docs/api/XCEngine/Core/Math/Matrix4/MultiplyPoint.md index 42de3f19..9d0da4c2 100644 --- a/docs/api/XCEngine/Core/Math/Matrix4/MultiplyPoint.md +++ b/docs/api/XCEngine/Core/Math/Matrix4/MultiplyPoint.md @@ -1,31 +1,25 @@ # Matrix4x4::MultiplyPoint -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Math` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Math/Matrix4.h` + +## 签名 ```cpp Vector3 MultiplyPoint(const Vector3& v) const; ``` -该方法声明于 `XCEngine/Core/Math/Matrix4.h`，当前页面用于固定 `Matrix4x4` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `v` - 参数语义详见头文件声明。 +执行 `MultiplyPoint` 对应的公开操作。 -**返回：** `Vector3` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Math::Matrix4x4 object; - // 根据上下文补齐参数后调用 Matrix4x4::MultiplyPoint(...)。 - (void)object; -} -``` +- 执行 `MultiplyPoint` 对应的公开操作。 ## 相关文档 -- [返回类总览](Matrix4.md) -- [返回模块目录](../Math.md) +- [Matrix4x4](Matrix4.md) diff --git a/docs/api/XCEngine/Core/Math/Matrix4/MultiplyVector.md b/docs/api/XCEngine/Core/Math/Matrix4/MultiplyVector.md index 8ee595cf..0dc6f55c 100644 --- a/docs/api/XCEngine/Core/Math/Matrix4/MultiplyVector.md +++ b/docs/api/XCEngine/Core/Math/Matrix4/MultiplyVector.md @@ -1,31 +1,25 @@ # Matrix4x4::MultiplyVector -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Math` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Math/Matrix4.h` + +## 签名 ```cpp Vector3 MultiplyVector(const Vector3& v) const; ``` -该方法声明于 `XCEngine/Core/Math/Matrix4.h`，当前页面用于固定 `Matrix4x4` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `v` - 参数语义详见头文件声明。 +执行 `MultiplyVector` 对应的公开操作。 -**返回：** `Vector3` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Math::Matrix4x4 object; - // 根据上下文补齐参数后调用 Matrix4x4::MultiplyVector(...)。 - (void)object; -} -``` +- 执行 `MultiplyVector` 对应的公开操作。 ## 相关文档 -- [返回类总览](Matrix4.md) -- [返回模块目录](../Math.md) +- [Matrix4x4](Matrix4.md) diff --git a/docs/api/XCEngine/Core/Math/Matrix4/OperatorMultiply.md b/docs/api/XCEngine/Core/Math/Matrix4/OperatorMultiply.md index 82b38053..d5ccad6c 100644 --- a/docs/api/XCEngine/Core/Math/Matrix4/OperatorMultiply.md +++ b/docs/api/XCEngine/Core/Math/Matrix4/OperatorMultiply.md @@ -1,44 +1,26 @@ # Matrix4x4::operator* -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Math` -该方法在 `XCEngine/Core/Math/Matrix4.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。 +**类型**: `method` -## 重载 1: 声明 +**头文件**: `XCEngine/Core/Math/Matrix4.h` + +## 签名 ```cpp Matrix4x4 operator*(const Matrix4x4& other) const; -``` - -**参数：** -- `other` - 参数语义详见头文件声明。 - -**返回：** `Matrix4x4` - 返回值语义详见头文件声明。 - -## 重载 2: 声明 - -```cpp Vector4 operator*(const Vector4& v) const; ``` -**参数：** -- `v` - 参数语义详见头文件声明。 +## 作用 -**返回：** `Vector4` - 返回值语义详见头文件声明。 +执行 `operator*` 对应的公开操作。 -**示例：** +## 当前实现 -```cpp -#include - -void Example() { - XCEngine::Math::Matrix4x4 object; - // 根据上下文补齐参数后调用 Matrix4x4::operator*(...)。 - (void)object; -} -``` +- 执行 `operator*` 对应的公开操作。 ## 相关文档 -- [返回类总览](Matrix4.md) -- [返回模块目录](../Math.md) +- [Matrix4x4](Matrix4.md) diff --git a/docs/api/XCEngine/Core/Math/Matrix4/OperatorSubscript.md b/docs/api/XCEngine/Core/Math/Matrix4/OperatorSubscript.md index cbf65d8c..1f9ab937 100644 --- a/docs/api/XCEngine/Core/Math/Matrix4/OperatorSubscript.md +++ b/docs/api/XCEngine/Core/Math/Matrix4/OperatorSubscript.md @@ -1,44 +1,26 @@ # Matrix4x4::operator[] -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Math` -该方法在 `XCEngine/Core/Math/Matrix4.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。 +**类型**: `method` -## 重载 1: 声明 +**头文件**: `XCEngine/Core/Math/Matrix4.h` + +## 签名 ```cpp float* operator[](int row); -``` - -**参数：** -- `row` - 参数语义详见头文件声明。 - -**返回：** `float*` - 返回值语义详见头文件声明。 - -## 重载 2: 声明 - -```cpp const float* operator[](int row) const; ``` -**参数：** -- `row` - 参数语义详见头文件声明。 +## 作用 -**返回：** `const float*` - 返回值语义详见头文件声明。 +返回 `m[row]`。 -**示例：** +## 当前实现 -```cpp -#include - -void Example() { - XCEngine::Math::Matrix4x4 object; - // 根据上下文补齐参数后调用 Matrix4x4::operator[](...)。 - (void)object; -} -``` +- 返回 `m[row]`。 ## 相关文档 -- [返回类总览](Matrix4.md) -- [返回模块目录](../Math.md) +- [Matrix4x4](Matrix4.md) diff --git a/docs/api/XCEngine/Core/Math/Matrix4/Orthographic.md b/docs/api/XCEngine/Core/Math/Matrix4/Orthographic.md index b709af90..d7c066bc 100644 --- a/docs/api/XCEngine/Core/Math/Matrix4/Orthographic.md +++ b/docs/api/XCEngine/Core/Math/Matrix4/Orthographic.md @@ -1,36 +1,25 @@ # Matrix4x4::Orthographic -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Math` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Math/Matrix4.h` + +## 签名 ```cpp static Matrix4x4 Orthographic(float left, float right, float bottom, float top, float near, float far); ``` -该方法声明于 `XCEngine/Core/Math/Matrix4.h`，当前页面用于固定 `Matrix4x4` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `left` - 参数语义详见头文件声明。 -- `right` - 参数语义详见头文件声明。 -- `bottom` - 参数语义详见头文件声明。 -- `top` - 参数语义详见头文件声明。 -- `near` - 参数语义详见头文件声明。 -- `far` - 参数语义详见头文件声明。 +执行 `Orthographic` 对应的公开操作。 -**返回：** `Matrix4x4` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Math::Matrix4x4 object; - // 根据上下文补齐参数后调用 Matrix4x4::Orthographic(...)。 - (void)object; -} -``` +- 执行 `Orthographic` 对应的公开操作。 ## 相关文档 -- [返回类总览](Matrix4.md) -- [返回模块目录](../Math.md) +- [Matrix4x4](Matrix4.md) diff --git a/docs/api/XCEngine/Core/Math/Matrix4/Perspective.md b/docs/api/XCEngine/Core/Math/Matrix4/Perspective.md index a55f8c2c..2c4de0e0 100644 --- a/docs/api/XCEngine/Core/Math/Matrix4/Perspective.md +++ b/docs/api/XCEngine/Core/Math/Matrix4/Perspective.md @@ -1,34 +1,25 @@ # Matrix4x4::Perspective -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Math` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Math/Matrix4.h` + +## 签名 ```cpp static Matrix4x4 Perspective(float fov, float aspect, float near, float far); ``` -该方法声明于 `XCEngine/Core/Math/Matrix4.h`，当前页面用于固定 `Matrix4x4` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `fov` - 参数语义详见头文件声明。 -- `aspect` - 参数语义详见头文件声明。 -- `near` - 参数语义详见头文件声明。 -- `far` - 参数语义详见头文件声明。 +执行 `Perspective` 对应的公开操作。 -**返回：** `Matrix4x4` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Math::Matrix4x4 object; - // 根据上下文补齐参数后调用 Matrix4x4::Perspective(...)。 - (void)object; -} -``` +- 执行 `Perspective` 对应的公开操作。 ## 相关文档 -- [返回类总览](Matrix4.md) -- [返回模块目录](../Math.md) +- [Matrix4x4](Matrix4.md) diff --git a/docs/api/XCEngine/Core/Math/Matrix4/Rotation.md b/docs/api/XCEngine/Core/Math/Matrix4/Rotation.md index 49e9a8f3..ec04db1a 100644 --- a/docs/api/XCEngine/Core/Math/Matrix4/Rotation.md +++ b/docs/api/XCEngine/Core/Math/Matrix4/Rotation.md @@ -1,31 +1,25 @@ # Matrix4x4::Rotation -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Math` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Math/Matrix4.h` + +## 签名 ```cpp static Matrix4x4 Rotation(const Quaternion& q); ``` -该方法声明于 `XCEngine/Core/Math/Matrix4.h`，当前页面用于固定 `Matrix4x4` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `q` - 参数语义详见头文件声明。 +执行 `Rotation` 对应的公开操作。 -**返回：** `Matrix4x4` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Math::Matrix4x4 object; - // 根据上下文补齐参数后调用 Matrix4x4::Rotation(...)。 - (void)object; -} -``` +- 执行 `Rotation` 对应的公开操作。 ## 相关文档 -- [返回类总览](Matrix4.md) -- [返回模块目录](../Math.md) +- [Matrix4x4](Matrix4.md) diff --git a/docs/api/XCEngine/Core/Math/Matrix4/RotationX.md b/docs/api/XCEngine/Core/Math/Matrix4/RotationX.md index 8d3458d9..506b3a37 100644 --- a/docs/api/XCEngine/Core/Math/Matrix4/RotationX.md +++ b/docs/api/XCEngine/Core/Math/Matrix4/RotationX.md @@ -1,31 +1,25 @@ # Matrix4x4::RotationX -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Math` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Math/Matrix4.h` + +## 签名 ```cpp static Matrix4x4 RotationX(float radians); ``` -该方法声明于 `XCEngine/Core/Math/Matrix4.h`，当前页面用于固定 `Matrix4x4` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `radians` - 参数语义详见头文件声明。 +执行 `RotationX` 对应的公开操作。 -**返回：** `Matrix4x4` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Math::Matrix4x4 object; - // 根据上下文补齐参数后调用 Matrix4x4::RotationX(...)。 - (void)object; -} -``` +- 执行 `RotationX` 对应的公开操作。 ## 相关文档 -- [返回类总览](Matrix4.md) -- [返回模块目录](../Math.md) +- [Matrix4x4](Matrix4.md) diff --git a/docs/api/XCEngine/Core/Math/Matrix4/RotationY.md b/docs/api/XCEngine/Core/Math/Matrix4/RotationY.md index 79301cef..80f88b67 100644 --- a/docs/api/XCEngine/Core/Math/Matrix4/RotationY.md +++ b/docs/api/XCEngine/Core/Math/Matrix4/RotationY.md @@ -1,31 +1,25 @@ # Matrix4x4::RotationY -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Math` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Math/Matrix4.h` + +## 签名 ```cpp static Matrix4x4 RotationY(float radians); ``` -该方法声明于 `XCEngine/Core/Math/Matrix4.h`，当前页面用于固定 `Matrix4x4` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `radians` - 参数语义详见头文件声明。 +执行 `RotationY` 对应的公开操作。 -**返回：** `Matrix4x4` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Math::Matrix4x4 object; - // 根据上下文补齐参数后调用 Matrix4x4::RotationY(...)。 - (void)object; -} -``` +- 执行 `RotationY` 对应的公开操作。 ## 相关文档 -- [返回类总览](Matrix4.md) -- [返回模块目录](../Math.md) +- [Matrix4x4](Matrix4.md) diff --git a/docs/api/XCEngine/Core/Math/Matrix4/RotationZ.md b/docs/api/XCEngine/Core/Math/Matrix4/RotationZ.md index a610af33..34bd09eb 100644 --- a/docs/api/XCEngine/Core/Math/Matrix4/RotationZ.md +++ b/docs/api/XCEngine/Core/Math/Matrix4/RotationZ.md @@ -1,31 +1,25 @@ # Matrix4x4::RotationZ -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Math` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Math/Matrix4.h` + +## 签名 ```cpp static Matrix4x4 RotationZ(float radians); ``` -该方法声明于 `XCEngine/Core/Math/Matrix4.h`，当前页面用于固定 `Matrix4x4` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `radians` - 参数语义详见头文件声明。 +执行 `RotationZ` 对应的公开操作。 -**返回：** `Matrix4x4` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Math::Matrix4x4 object; - // 根据上下文补齐参数后调用 Matrix4x4::RotationZ(...)。 - (void)object; -} -``` +- 执行 `RotationZ` 对应的公开操作。 ## 相关文档 -- [返回类总览](Matrix4.md) -- [返回模块目录](../Math.md) +- [Matrix4x4](Matrix4.md) diff --git a/docs/api/XCEngine/Core/Math/Matrix4/Scale.md b/docs/api/XCEngine/Core/Math/Matrix4/Scale.md index 2f5b1fd1..d21746aa 100644 --- a/docs/api/XCEngine/Core/Math/Matrix4/Scale.md +++ b/docs/api/XCEngine/Core/Math/Matrix4/Scale.md @@ -1,31 +1,25 @@ # Matrix4x4::Scale -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Math` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Math/Matrix4.h` + +## 签名 ```cpp static Matrix4x4 Scale(const Vector3& v); ``` -该方法声明于 `XCEngine/Core/Math/Matrix4.h`，当前页面用于固定 `Matrix4x4` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `v` - 参数语义详见头文件声明。 +执行 `Scale` 对应的公开操作。 -**返回：** `Matrix4x4` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Math::Matrix4x4 object; - // 根据上下文补齐参数后调用 Matrix4x4::Scale(...)。 - (void)object; -} -``` +- 执行 `Scale` 对应的公开操作。 ## 相关文档 -- [返回类总览](Matrix4.md) -- [返回模块目录](../Math.md) +- [Matrix4x4](Matrix4.md) diff --git a/docs/api/XCEngine/Core/Math/Matrix4/TRS.md b/docs/api/XCEngine/Core/Math/Matrix4/TRS.md index 6a114c20..8aeb5911 100644 --- a/docs/api/XCEngine/Core/Math/Matrix4/TRS.md +++ b/docs/api/XCEngine/Core/Math/Matrix4/TRS.md @@ -1,33 +1,25 @@ # Matrix4x4::TRS -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Math` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Math/Matrix4.h` + +## 签名 ```cpp static Matrix4x4 TRS(const Vector3& translation, const Quaternion& rotation, const Vector3& scale); ``` -该方法声明于 `XCEngine/Core/Math/Matrix4.h`，当前页面用于固定 `Matrix4x4` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `translation` - 参数语义详见头文件声明。 -- `rotation` - 参数语义详见头文件声明。 -- `scale` - 参数语义详见头文件声明。 +执行 `TRS` 对应的公开操作。 -**返回：** `Matrix4x4` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Math::Matrix4x4 object; - // 根据上下文补齐参数后调用 Matrix4x4::TRS(...)。 - (void)object; -} -``` +- 执行 `TRS` 对应的公开操作。 ## 相关文档 -- [返回类总览](Matrix4.md) -- [返回模块目录](../Math.md) +- [Matrix4x4](Matrix4.md) diff --git a/docs/api/XCEngine/Core/Math/Matrix4/Translation.md b/docs/api/XCEngine/Core/Math/Matrix4/Translation.md index ac7eece5..ab363727 100644 --- a/docs/api/XCEngine/Core/Math/Matrix4/Translation.md +++ b/docs/api/XCEngine/Core/Math/Matrix4/Translation.md @@ -1,31 +1,25 @@ # Matrix4x4::Translation -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Math` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Math/Matrix4.h` + +## 签名 ```cpp static Matrix4x4 Translation(const Vector3& v); ``` -该方法声明于 `XCEngine/Core/Math/Matrix4.h`，当前页面用于固定 `Matrix4x4` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `v` - 参数语义详见头文件声明。 +执行 `Translation` 对应的公开操作。 -**返回：** `Matrix4x4` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Math::Matrix4x4 object; - // 根据上下文补齐参数后调用 Matrix4x4::Translation(...)。 - (void)object; -} -``` +- 执行 `Translation` 对应的公开操作。 ## 相关文档 -- [返回类总览](Matrix4.md) -- [返回模块目录](../Math.md) +- [Matrix4x4](Matrix4.md) diff --git a/docs/api/XCEngine/Core/Math/Matrix4/Transpose.md b/docs/api/XCEngine/Core/Math/Matrix4/Transpose.md index 05b5251e..23bcfaf9 100644 --- a/docs/api/XCEngine/Core/Math/Matrix4/Transpose.md +++ b/docs/api/XCEngine/Core/Math/Matrix4/Transpose.md @@ -1,30 +1,25 @@ # Matrix4x4::Transpose -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Math` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Math/Matrix4.h` + +## 签名 ```cpp Matrix4x4 Transpose() const; ``` -该方法声明于 `XCEngine/Core/Math/Matrix4.h`，当前页面用于固定 `Matrix4x4` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `Transpose` 对应的公开操作。 -**返回：** `Matrix4x4` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Math::Matrix4x4 object; - // 根据上下文补齐参数后调用 Matrix4x4::Transpose(...)。 - (void)object; -} -``` +- 执行 `Transpose` 对应的公开操作。 ## 相关文档 -- [返回类总览](Matrix4.md) -- [返回模块目录](../Math.md) +- [Matrix4x4](Matrix4.md) diff --git a/docs/api/XCEngine/Core/Math/Matrix4/Zero.md b/docs/api/XCEngine/Core/Math/Matrix4/Zero.md index 8500a69b..ddb76cbc 100644 --- a/docs/api/XCEngine/Core/Math/Matrix4/Zero.md +++ b/docs/api/XCEngine/Core/Math/Matrix4/Zero.md @@ -1,30 +1,25 @@ # Matrix4x4::Zero -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Math` + +**类型**: `method` + +**头文件**: `XCEngine/Core/Math/Matrix4.h` + +## 签名 ```cpp static Matrix4x4 Zero(); ``` -该方法声明于 `XCEngine/Core/Math/Matrix4.h`，当前页面用于固定 `Matrix4x4` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `Matrix4x4(...)` 相关流程。 -**返回：** `Matrix4x4` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Math::Matrix4x4 object; - // 根据上下文补齐参数后调用 Matrix4x4::Zero(...)。 - (void)object; -} -``` +- 当前实现会调用 `Matrix4x4`。 ## 相关文档 -- [返回类总览](Matrix4.md) -- [返回模块目录](../Math.md) +- [Matrix4x4](Matrix4.md) diff --git a/docs/api/XCEngine/Core/Math/Plane/Plane.md b/docs/api/XCEngine/Core/Math/Plane/Plane.md index 17f2d828..08bf7391 100644 --- a/docs/api/XCEngine/Core/Math/Plane/Plane.md +++ b/docs/api/XCEngine/Core/Math/Plane/Plane.md @@ -27,7 +27,7 @@ - `GetSide()` 以距离是否大于 `0.0f` 判断点位于平面哪一侧。 - `Intersects(const Sphere&)` 以 `abs(distanceToCenter) <= radius` 判断球体是否与平面相交。 -按 `tests/math/test_geometry.cpp`，以下路径有测试覆盖： +按 `tests/Core/Math/test_geometry.cpp`，以下路径有测试覆盖： - 默认构造 - 参数构造 diff --git a/docs/api/XCEngine/Core/Math/Quaternion/Quaternion.md b/docs/api/XCEngine/Core/Math/Quaternion/Quaternion.md index df63afd0..a5bc2807 100644 --- a/docs/api/XCEngine/Core/Math/Quaternion/Quaternion.md +++ b/docs/api/XCEngine/Core/Math/Quaternion/Quaternion.md @@ -25,7 +25,7 @@ - 默认构造结果是单位四元数 `(0, 0, 0, 1)`。 - `Identity()` 明确返回单位四元数。 - `FromEulerAngles()` 和 `ToEulerAngles()` 都使用弧度制。 -- `tests/math/test_quaternion.cpp` 验证了 `FromEulerAngles(x, y, z)` 与 `ToEulerAngles()` 在单轴场景下保持 `x/y/z` 轴顺序一致。 +- `tests/Core/Math/test_quaternion.cpp` 验证了 `FromEulerAngles(x, y, z)` 与 `ToEulerAngles()` 在单轴场景下保持 `x/y/z` 轴顺序一致。 - `FromRotationMatrix()` 会在返回前做一次 `Normalized()`，因此输出总会被归一化。 - `Slerp()` 会先把 `t` clamp 到 `[0, 1]`。 - `LookRotation()` 对 `Up / Down / Right / Left` 这几条精确方向做了硬编码快捷分支，而不是完全统一走一般路径。 diff --git a/docs/api/XCEngine/Core/Math/Ray/Ray.md b/docs/api/XCEngine/Core/Math/Ray/Ray.md index e6248427..ed508910 100644 --- a/docs/api/XCEngine/Core/Math/Ray/Ray.md +++ b/docs/api/XCEngine/Core/Math/Ray/Ray.md @@ -27,7 +27,7 @@ - `Intersects(const Plane&, float& t)` 在分母接近 `0` 时视为平行不相交；只接受 `t >= 0` 的命中。 - `Intersects(const Box&, float& t)` 使用 slab 风格的轴向区间裁剪。 -按 `tests/math/test_geometry.cpp`，当前有测试覆盖： +按 `tests/Core/Math/test_geometry.cpp`，当前有测试覆盖： - 默认构造 / 参数构造 - `GetPoint()` diff --git a/docs/api/XCEngine/Core/Math/Sphere/Sphere.md b/docs/api/XCEngine/Core/Math/Sphere/Sphere.md index eabd8a0f..c9d57da9 100644 --- a/docs/api/XCEngine/Core/Math/Sphere/Sphere.md +++ b/docs/api/XCEngine/Core/Math/Sphere/Sphere.md @@ -24,7 +24,7 @@ - `Contains(point)` 通过比较平方距离与 `radius * radius` 判断点是否在球内或球面上。 - `Intersects(other)` 通过比较球心平方距离和半径和的平方判断两球是否相交。 -按 `tests/math/test_geometry.cpp`，默认构造、参数构造、包含判定和球球相交都已有测试覆盖。 +按 `tests/Core/Math/test_geometry.cpp`，默认构造、参数构造、包含判定和球球相交都已有测试覆盖。 ## 生命周期 diff --git a/docs/api/XCEngine/Core/RefCounted/AddRef.md b/docs/api/XCEngine/Core/RefCounted/AddRef.md index 511cfba3..f0088c09 100644 --- a/docs/api/XCEngine/Core/RefCounted/AddRef.md +++ b/docs/api/XCEngine/Core/RefCounted/AddRef.md @@ -1,30 +1,25 @@ # RefCounted::AddRef -添加元素或建立关联。 +**命名空间**: `XCEngine::Core` + +**类型**: `method` + +**头文件**: `XCEngine/Core/RefCounted.h` + +## 签名 ```cpp void AddRef(); ``` -该方法声明于 `XCEngine/Core/RefCounted.h`，当前页面用于固定 `RefCounted` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行该公开方法对应的当前实现。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Core::RefCounted object; - // 根据上下文补齐参数后调用 RefCounted::AddRef(...)。 - (void)object; -} -``` +- 执行该公开方法对应的当前实现。 ## 相关文档 -- [返回类总览](RefCounted.md) -- [返回模块目录](../Core.md) +- [RefCounted](RefCounted.md) diff --git a/docs/api/XCEngine/Core/RefCounted/Constructor.md b/docs/api/XCEngine/Core/RefCounted/Constructor.md index de42be2f..f6f3a8cb 100644 --- a/docs/api/XCEngine/Core/RefCounted/Constructor.md +++ b/docs/api/XCEngine/Core/RefCounted/Constructor.md @@ -1,28 +1,25 @@ # RefCounted::RefCounted() -构造对象。 +**命名空间**: `XCEngine::Core` + +**类型**: `method` + +**头文件**: `XCEngine/Core/RefCounted.h` + +## 签名 ```cpp RefCounted() : m_refCount(1); ``` -该方法声明于 `XCEngine/Core/RefCounted.h`，当前页面用于固定 `RefCounted` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +构造 `RefCounted` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Core::RefCounted object; -} -``` +- 当前为默认构造实现。 ## 相关文档 -- [返回类总览](RefCounted.md) -- [返回模块目录](../Core.md) +- [RefCounted](RefCounted.md) diff --git a/docs/api/XCEngine/Core/RefCounted/Destructor.md b/docs/api/XCEngine/Core/RefCounted/Destructor.md index 50155ae1..9f869c96 100644 --- a/docs/api/XCEngine/Core/RefCounted/Destructor.md +++ b/docs/api/XCEngine/Core/RefCounted/Destructor.md @@ -1,29 +1,25 @@ # RefCounted::~RefCounted() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::Core` + +**类型**: `method` + +**头文件**: `XCEngine/Core/RefCounted.h` + +## 签名 ```cpp virtual ~RefCounted() = default; ``` -该方法声明于 `XCEngine/Core/RefCounted.h`，当前页面用于固定 `RefCounted` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +销毁 `RefCounted` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Core::RefCounted object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 当前为默认析构实现。 ## 相关文档 -- [返回类总览](RefCounted.md) -- [返回模块目录](../Core.md) +- [RefCounted](RefCounted.md) diff --git a/docs/api/XCEngine/Core/RefCounted/GetRefCount.md b/docs/api/XCEngine/Core/RefCounted/GetRefCount.md index 29c51951..5c97632f 100644 --- a/docs/api/XCEngine/Core/RefCounted/GetRefCount.md +++ b/docs/api/XCEngine/Core/RefCounted/GetRefCount.md @@ -1,30 +1,26 @@ # RefCounted::GetRefCount -获取相关状态或对象。 +**命名空间**: `XCEngine::Core` + +**类型**: `method` + +**头文件**: `XCEngine/Core/RefCounted.h` + +## 签名 ```cpp uint32_t GetRefCount() const; ``` -该方法声明于 `XCEngine/Core/RefCounted.h`，当前页面用于固定 `RefCounted` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_refCount`。 -**返回：** `uint32_t` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Core::RefCounted object; - // 根据上下文补齐参数后调用 RefCounted::GetRefCount(...)。 - (void)object; -} -``` +- 会更新 `m_refCount`。 +- 当前实现会调用 `load`。 ## 相关文档 -- [返回类总览](RefCounted.md) -- [返回模块目录](../Core.md) +- [RefCounted](RefCounted.md) diff --git a/docs/api/XCEngine/Core/RefCounted/RefCounted.md b/docs/api/XCEngine/Core/RefCounted/RefCounted.md index 47538f62..97f4f64c 100644 --- a/docs/api/XCEngine/Core/RefCounted/RefCounted.md +++ b/docs/api/XCEngine/Core/RefCounted/RefCounted.md @@ -22,7 +22,7 @@ ### 1. 初始引用计数是 1 -构造函数会把 `m_refCount` 初始化为 `1`。`tests/core/test_core.cpp` 已验证这一点。 +构造函数会把 `m_refCount` 初始化为 `1`。`tests/Core/test_core.cpp` 已验证这一点。 这意味着默认语义是： @@ -75,7 +75,7 @@ if (--m_refCount == 0) { ## 测试覆盖 -`tests/core/test_core.cpp` 已覆盖： +`tests/Core/test_core.cpp` 已覆盖： - 初始引用计数 - `AddRef()` diff --git a/docs/api/XCEngine/Core/RefCounted/Release.md b/docs/api/XCEngine/Core/RefCounted/Release.md index a5aafbcc..503ebf0c 100644 --- a/docs/api/XCEngine/Core/RefCounted/Release.md +++ b/docs/api/XCEngine/Core/RefCounted/Release.md @@ -1,30 +1,25 @@ # RefCounted::Release -释放引用或底层资源。 +**命名空间**: `XCEngine::Core` + +**类型**: `method` + +**头文件**: `XCEngine/Core/RefCounted.h` + +## 签名 ```cpp void Release(); ``` -该方法声明于 `XCEngine/Core/RefCounted.h`，当前页面用于固定 `RefCounted` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_refCount`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Core::RefCounted object; - // 根据上下文补齐参数后调用 RefCounted::Release(...)。 - (void)object; -} -``` +- 会更新 `m_refCount`。 ## 相关文档 -- [返回类总览](RefCounted.md) -- [返回模块目录](../Core.md) +- [RefCounted](RefCounted.md) diff --git a/docs/api/XCEngine/Core/SmartPtr/SmartPtr.md b/docs/api/XCEngine/Core/SmartPtr/SmartPtr.md index 67198575..7e87321c 100644 --- a/docs/api/XCEngine/Core/SmartPtr/SmartPtr.md +++ b/docs/api/XCEngine/Core/SmartPtr/SmartPtr.md @@ -37,7 +37,7 @@ - `MakeRef()` -> `std::make_shared` - `MakeUnique()` -> `std::make_unique` -`tests/core/test_core.cpp` 已覆盖： +`tests/Core/test_core.cpp` 已覆盖： - 默认构造 - 拷贝共享 diff --git a/docs/api/XCEngine/Editor/Actions/ConsoleActionRouter/ConsoleActionRouter.md b/docs/api/XCEngine/Editor/Actions/ConsoleActionRouter/ConsoleActionRouter.md index 00712e38..f336d739 100644 --- a/docs/api/XCEngine/Editor/Actions/ConsoleActionRouter/ConsoleActionRouter.md +++ b/docs/api/XCEngine/Editor/Actions/ConsoleActionRouter/ConsoleActionRouter.md @@ -6,39 +6,51 @@ **源文件**: `editor/src/Actions/ConsoleActionRouter.h` -**描述**: 为 Console 面板提供工具栏动作和日志列表绘制逻辑。 +**描述**: 为 Console 面板提供一组轻量 toolbar/action helper；当前保留基础控制台动作绑定，但已不再承载完整 Console 面板渲染主路径。 ## 概述 -`ConsoleActionRouter` 目前主要负责两件事： +`ConsoleActionRouter` 当前主要提供两类内联 helper： - `DrawConsoleToolbarActions` 绘制清空按钮和 Info / Warn / Error 过滤切换 - `DrawConsoleLogRows` 读取 `EditorConsoleSink` 中的日志，并按过滤条件输出到面板 -`ConsolePanel.cpp` 只负责搭窗口和滚动区域，真正的交互逻辑由这层统一承接。这样 Console 面板本身会保持很薄，不会把过滤策略、日志格式化和按钮语义都堆在一个类里。 +但需要注意，`ConsolePanel.cpp` 当前已经演化出比这组 helper 更完整的控制台工作流： + +- play mode 事件订阅 +- search + collapse 聚合 +- 键盘选择与复制 +- splitter 和详情区 +- error pause 扫描 + +也就是说，这个 header 现在更像“保留的轻量动作 helper”，而不是 Console 面板的唯一 presenter 层。 ## 当前实现 - 数据源固定为 [`EditorConsoleSink`](../../Core/EditorConsoleSink/EditorConsoleSink.md) - 过滤状态由 [`ConsoleFilterState`](../../UI/ConsoleFilterState/ConsoleFilterState.md) 持有 -- 每条日志通过 [`BuildConsoleLogText`](../../UI/ConsoleLogFormatter/ConsoleLogFormatter.md) 生成展示字符串 -- 点击日志行时会把完整字符串复制到剪贴板 +- `DrawConsoleToolbarActions(...)` 当前会绘制： + - `Clear` + - `Collapse` + - `Clear on Play` + - `Error Pause` + - log / warning / error filter +- `DrawConsoleLogRows(...)` 当前会遍历 sink 的日志副本，按过滤状态输出基础文本行 ## 设计说明 -这层拆分的价值在于把“日志存储”和“日志呈现”分开： +这层拆分的价值仍然在于把“日志存储”和“基础动作 helper”从面板类里分离出来： - `EditorConsoleSink` 关注线程安全和日志缓存 -- `ConsoleActionRouter` 关注工具栏与列表交互 +- `ConsoleActionRouter` 关注一小组可复用的工具栏与列表 helper - `UI` 辅助函数负责外观和文本格式 -这种分层比直接在 `ConsolePanel::Render` 中处理全部逻辑更容易维护，也更接近商业级编辑器里常见的 presenter / controller 风格。 +但按当前版本，完整的 Console 面板交互已经不再只依赖这里；文档和调用方都不应把它误解成现行主渲染入口。 ## 当前限制 -- 当前过滤粒度只有三档：信息、警告、错误 -- 没有搜索、分类树、时间戳列或堆栈追踪展开 -- `GetLogs()` 会复制整个日志数组，日志量继续增大后可能需要增量视图或虚拟列表 +- 这里只覆盖较基础的 helper，当前并不表达 `ConsolePanel` 全部行为。 +- `DrawConsoleLogRows(...)` 仍基于简单遍历日志副本的方式，不包含当前 `ConsolePanel` 里的搜索、折叠聚合、详情区和 source opening 流程。 ## 相关文档 diff --git a/docs/api/XCEngine/Editor/Actions/EditorActions/EditorActions.md b/docs/api/XCEngine/Editor/Actions/EditorActions/EditorActions.md index 26cae114..970ba234 100644 --- a/docs/api/XCEngine/Editor/Actions/EditorActions/EditorActions.md +++ b/docs/api/XCEngine/Editor/Actions/EditorActions/EditorActions.md @@ -6,54 +6,185 @@ **源文件**: `editor/src/Actions/EditorActions.h` -**描述**: 定义编辑器中可复用的动作描述，包括菜单标题、快捷键、启用状态和选中项解析辅助函数。 +**描述**: 定义 editor 中可复用的动作描述，集中维护标签、快捷键、选中态、启用态，以及从 `IEditorContext` 解析当前选择对象的轻量 helper。 ## 概述 -`EditorActions.h` 并不直接执行命令，它负责生产 [`ActionBinding`](../ActionBinding/ActionBinding.md)。 +`EditorActions.h` 不直接修改项目或场景数据；它负责生成 [`ActionBinding`](../ActionBinding/ActionBinding.md)，让菜单栏、工具栏、上下文菜单和快捷键路由共享同一套动作描述。 -当前文件中的动作工厂可以分成几类： +这是一种典型的商业编辑器写法： -- 场景级动作：`MakeNewSceneAction`、`MakeOpenSceneAction`、`MakeSaveSceneAction` -- 编辑级动作：`MakeUndoAction`、`MakeRedoAction`、`MakeCopyEntityAction`、`MakePasteEntityAction` -- 层级面板动作：`MakeCreateChildEntityAction`、`MakeDetachEntityAction` -- 项目面板动作：`MakeNavigateBackAction`、`MakeOpenAssetAction`、`MakeCreateFolderAction` -- Inspector / Console 动作：`MakeAddComponentButtonAction`、`MakeRemoveComponentAction`、`MakeClearConsoleAction` +- 动作文案只有一个权威来源 +- 默认快捷键只有一个权威来源 +- enabled / selected 语义可以在多个入口之间保持一致 -此外它还提供： +因此这里真正文档化的对象不是“命令逻辑”，而是“UI 如何描述这些命令”。 -- `GetSelectedGameObject` -- `GetSelectedAssetItem` +## 当前动作分组 -用于把当前上下文解析为后续路由与命令层需要的对象。 +### 项目与场景文档动作 -## 当前实现 +当前头文件直接提供了这组菜单级动作工厂： -- 动作标签、快捷键文本和 `ImGuiKey` 触发条件都集中写在这里 -- `Undo` / `Redo` 标签会根据 `IUndoManager` 动态显示历史项名称 -- `Paste`、`Delete`、`Duplicate` 等动作会根据当前选择动态启用或禁用 -- 资源选择解析依赖 `IProjectManager::GetSelectedIndex()` 和 `GetCurrentItems()` +- `MakeNewProjectAction` +- `MakeOpenProjectAction` +- `MakeSaveProjectAction` +- `MakeRebuildScriptsAction` +- `MakeNewSceneAction` +- `MakeOpenSceneAction` +- `MakeSaveSceneAction` +- `MakeSaveSceneAsAction` +- `MakeExitAction` + +其中： + +- `New Scene` 默认是 `Ctrl+N` +- `Open Scene` 默认是 `Ctrl+O` +- `Save Scene` 默认是 `Ctrl+S` +- `Save Scene As...` 默认是 `Ctrl+Shift+S` +- `New Project...`、`Open Project...`、`Save Project` 和 `Rebuild Script Assemblies` 当前没有默认全局快捷键 + +这反映了当前主菜单设计：项目级动作以菜单点击为主，场景级动作同时暴露快捷键。 + +### 编辑与层级动作 + +- `MakeUndoAction` +- `MakeRedoAction` +- `MakeCutAction` +- `MakeCopyEntityAction` +- `MakePasteEntityAction` +- `MakeDuplicateEntityAction` +- `MakeDeleteEntityAction` +- `MakeRenameEntityAction` +- `MakeCreateChildEntityAction` +- `MakeDetachEntityAction` + +这组动作主要服务 [HierarchyActionRouter](../HierarchyActionRouter/HierarchyActionRouter.md) 和 [EditActionRouter](../EditActionRouter/EditActionRouter.md)。 + +其中比较值得注意的是： + +- `Undo` / `Redo` 的 label 会拼接当前撤销栈标签 +- `Copy` / `Duplicate` / `Delete` / `Rename` 是否可用取决于当前是否存在选中实体 +- `Detach from Parent` 还要求当前对象确实存在父对象 + +### 创建实体动作 + +头文件里还集中定义了创建菜单所需的若干静态动作： + +- `MakeCreateEmptyEntityAction` +- `MakeCreateCameraEntityAction` +- `MakeCreateLightEntityAction` +- `MakeCreateCubeEntityAction` +- `MakeCreateSphereEntityAction` +- `MakeCreateCapsuleEntityAction` +- `MakeCreateCylinderEntityAction` +- `MakeCreatePlaneEntityAction` +- `MakeCreateQuadEntityAction` + +这些工厂本身只提供 label，不直接负责实体创建命令。 + +### 运行时与宿主动作 + +- `MakeTogglePlayModeAction` +- `MakeStartPlayModeAction` +- `MakeStopPlayModeAction` +- `MakeTogglePauseModeAction` +- `MakeStepPlayModeAction` +- `MakeResetLayoutAction` +- `MakeAboutAction` + +这组动作把 `EditorRuntimeMode` 映射为最终 UI 状态： + +- 编辑态下显示 `Play` +- 运行态下显示 `Stop` +- 暂停按钮会在 `Pause` / `Resume` 之间切换 +- `Step` 只有在 `Paused` 时才有意义 + +### Project Browser 动作 + +- `MakeNavigateBackAction` +- `MakeOpenAssetAction` +- `MakeDeleteAssetAction` +- `MakeCreateFolderAction` +- `MakeConfirmCreateAction` +- `MakeCancelAction` + +这些动作主要被 [ProjectPanel](../../panels/ProjectPanel/ProjectPanel.md) 与 [ProjectActionRouter](../ProjectActionRouter/ProjectActionRouter.md) 复用。 + +默认快捷键包括： + +- `Navigate Back` -> `Alt+Left` +- `Open` -> `Enter` +- `Delete` -> `Delete` + +要注意一个当前边界：`Create Material`、`Copy Path`、`Show in Explore` 这类右键菜单项仍然局部定义在 `ProjectPanel.cpp`，还没有统一纳入 `EditorActions.h`。 + +### Inspector / Console 动作 + +- `MakeAddComponentButtonAction` +- `MakeAddComponentMenuAction` +- `MakeRemoveComponentAction` +- `MakeClearConsoleAction` +- `MakeConsoleInfoFilterAction` +- `MakeConsoleWarningFilterAction` +- `MakeConsoleErrorFilterAction` + +这里的重点是统一 section 按钮、筛选按钮和菜单项的启用态与选中态，而不是提供复杂业务逻辑。 + +## 当前实现特征 + +### 动态 label 与 enabled + +当前并不是所有动作都写死为静态字符串。 + +几个典型例子： + +- `MakeUndoAction(context)` / `MakeRedoAction(context)` + - 从 `IUndoManager` 读取历史标签 + - 同时结合 runtime mode 决定是否允许撤销/重做 +- `MakeTogglePlayModeAction(mode, enabled)` + - 同一工厂会根据 mode 输出 `Play` 或 `Stop` +- `MakeTogglePauseModeAction(mode, enabled)` + - 同一工厂会根据 mode 输出 `Pause` 或 `Resume` +- `MakeOpenAssetAction(enabled)` + - 由调用方先决定当前资源是否可打开 + +因此 `EditorActions` 更像“动作描述工厂”，而不是常量表。 + +### 选择解析 helper + +文件尾部保留了两个非常实用的 helper： + +- `GetSelectedGameObject(context)` +- `GetSelectedAssetItem(context)` + +它们的价值在于，把“如何从 `IEditorContext` 当前状态还原出目标对象”收口到一处，避免每个 router 都重复手写同样的样板代码。 ## 设计说明 -把动作描述统一集中，是商业编辑器里常见的稳定做法。 -原因很直接： +把动作描述和动作执行拆开，有几个现实收益： -- 菜单栏、工具栏、右键菜单、快捷键需要共享同一组语义 -- “名称、快捷键、是否可用” 应该只有一个权威来源 -- 如果动作定义分散在各个面板里，最终会出现文本不一致、快捷键冲突和启用逻辑漂移 +- UI 层不会到处散落重复 label +- 快捷键冲突更容易集中审查 +- router 可以专注于“何时触发”，commands 可以专注于“触发后做什么” -所以 `EditorActions` 更像编辑器的“动作字典”，而 `ActionRouter` 是“动作分发器”，`Commands` 则是“真正执行业务变更的地方”。 +因此当前分层更适合这样理解： + +- `EditorActions`：动作字典 +- `*ActionRouter`：交互入口与路由 +- `Commands` / `Managers`：真实修改逻辑 ## 当前限制 -- 动作仍然以手写 inline 工厂为主，尚未发展成可注册、可枚举的统一 action registry -- 没有本地化层，标签文本直接写死为英文 -- 资源动作当前只覆盖文件夹导航和场景资源打开 +- 仍然是手写 inline 工厂，不是可注册的统一 action registry。 +- 没有本地化层，label 直接写在代码中。 +- Project 右键菜单仍有一部分局部动作未纳入统一 action factory。 ## 相关文档 - [Actions](../Actions.md) - [ActionBinding](../ActionBinding/ActionBinding.md) -- [EditActionRouter](../EditActionRouter/EditActionRouter.md) - [MainMenuActionRouter](../MainMenuActionRouter/MainMenuActionRouter.md) +- [ProjectActionRouter](../ProjectActionRouter/ProjectActionRouter.md) +- [ProjectCommands](../../Commands/ProjectCommands/ProjectCommands.md) +- [ProjectPanel](../../panels/ProjectPanel/ProjectPanel.md) diff --git a/docs/api/XCEngine/Editor/Actions/HierarchyActionRouter/HierarchyActionRouter.md b/docs/api/XCEngine/Editor/Actions/HierarchyActionRouter/HierarchyActionRouter.md index 58f4bbc9..c32cbd87 100644 --- a/docs/api/XCEngine/Editor/Actions/HierarchyActionRouter/HierarchyActionRouter.md +++ b/docs/api/XCEngine/Editor/Actions/HierarchyActionRouter/HierarchyActionRouter.md @@ -6,46 +6,161 @@ **源文件**: `editor/src/Actions/HierarchyActionRouter.h` -**描述**: 封装 Hierarchy 面板中的选中、重命名、拖拽重挂接、排序和上下文菜单动作。 +**描述**: Hierarchy 面板的交互路由助手，负责把层级树中的点击、重命名、拖放、上下文菜单和创建动作转成统一的 editor command / event 流。 ## 概述 -`HierarchyActionRouter` 是当前实体层级树交互的主要承载者。它把 `HierarchyPanel.cpp` 中最容易膨胀的逻辑拆成了几类可复用动作： +`HierarchyActionRouter` 不是独立的运行时对象，而是一组 `inline` helper。 +它的意义在于把 Hierarchy 这种“高交互密度、低业务独立性”的逻辑，从面板渲染代码中拆出来。 -- 选择与背景点击清空选择 -- 实体重命名请求与提交 -- 拖拽实体到其他父节点或根节点 -- 创建 / 删除 / 复制 / 粘贴 / 重复实体 -- 排序选项弹窗 +当前它负责的事情主要有： -## 当前实现 +- 实体选择与背景点击清空选择。 +- 发布重命名请求，并提交最终名称。 +- 处理实体拖拽重挂接。 +- 绘制背景菜单、实体菜单和排序选项弹窗。 +- 调用 [EntityCommands](../../Commands/EntityCommands/EntityCommands.md) 创建、复制、粘贴、删除、重复和重挂接实体。 -- 拖拽载荷类型固定为字符串 `"ENTITY_PTR"` -- `HandleHierarchySelectionClick` 只实现了单选和 Ctrl 增选 -- `CommitEntityRename` 会先验证实体存在且名字非空，再调用 [`RenameEntity`](../../Commands/EntityCommands/EntityCommands.md) -- 拖拽重挂接时会调用 `Commands::CanReparentEntity` 和 `ReparentEntityPreserveWorldTransform` -- 背景右键菜单可以直接创建空物体、Camera、Light，以及命名为 `Cube` / `Sphere` / `Plane` 的空实体 +这类拆法很符合商业编辑器的做法。Hierarchy 面板应该主要关心“树怎么画”，而不是“菜单项怎么执行”。 + +## 前置知识 + +当前 Hierarchy 相关调用链大致是： + +`HierarchyPanel` 采样 ImGui 交互 -> `HierarchyActionRouter` 做输入解释与路由 -> [EntityCommands](../../Commands/EntityCommands/EntityCommands.md) 修改场景 / 撤销栈 -> [SelectionManager](../../Core/ISelectionManager/ISelectionManager.md) 与 [EventBus](../../Core/EventBus/EventBus.md) 推进后续 UI 同步。 + +这条链路里： + +- 面板负责显示。 +- router 负责交互语义。 +- command 层负责真正修改场景。 + +这就是典型的“展示层 / 交互层 / 命令层”分离。 + +## 主要职责 + +| 职责 | 代表入口 | 说明 | +|------|------|------| +| 选择路由 | `HandleHierarchySelectionClick` | 单击实体时更新当前选择。 | +| 重命名请求 | `RequestEntityRename` / `CommitEntityRename` | 通过事件请求进入重命名，再调用命令层提交名称。 | +| 背景交互 | `HandleHierarchyBackgroundPrimaryClick` / `DrawHierarchyBackgroundInteraction` | 清空选择、接收拖放到根节点。 | +| 右键菜单 | `RequestHierarchyBackgroundContextPopup` / `DrawHierarchyContextActions` | 组装创建、删除、复制、粘贴等菜单项。 | +| 创建实体 | `DrawHierarchyCreateActions` | 调用命令层创建空对象、相机、灯光和内置 primitive。 | +| 拖拽重挂接 | `BeginHierarchyEntityDrag` / `AcceptHierarchyEntityDrop` | 在实体之间或根节点上完成重挂接。 | +| 排序菜单 | `DrawHierarchySortOptionsPopup` | 绘制排序选项 popup。 | + +## 当前实现行为 + +### 选择与重命名 + +- `HandleHierarchySelectionClick` 当前支持两种模式： + - 普通点击: `SetSelectedEntity(entityId)` + - additive 点击: 仅在未选中时 `AddToSelection(entityId)` +- 当前 additive 语义更接近“增量加入”，不是完整的 Ctrl-toggle 逻辑。 + +重命名分两步： + +1. `RequestEntityRename(context, gameObject)` 发布 `EntityRenameRequestedEvent`。 +2. `CommitEntityRename(context, entityId, newName)` 校验实体存在且名称非空，再调用 [EntityCommands](../../Commands/EntityCommands/EntityCommands.md)。 + +这种拆法的意义在于： +Hierarchy 行内编辑、菜单栏 Rename、快捷键 Rename 都可以走同一条“先请求、后提交”的链路。 + +### 背景交互与 action route + +`HandleHierarchyBackgroundPrimaryClick` 和 `DrawHierarchyBackgroundInteraction` 会在以下条件下清空选择： + +- 鼠标在窗口内。 +- 当前没有悬停在具体 item 上。 +- 当前不处于 rename 编辑状态。 + +`DrawHierarchyBackgroundInteraction` 还会创建一个不可见交互面，并允许把实体直接拖回根节点。这一点很像 Unity 的 Hierarchy 根级拖放体验。 + +### 拖拽载荷与重挂接 + +当前拖拽载荷类型固定为： + +- `"ENTITY_PTR"` + +`BeginHierarchyEntityDrag` 会把 `GameObject*` 直接写入 ImGui drag payload。 +`AcceptHierarchyEntityDrop` / `AcceptHierarchyEntityDropToRoot` 在 drop 时读取这个指针，并调用： + +- `Commands::CanReparentEntity(...)` +- `Commands::ReparentEntityPreserveWorldTransform(...)` + +所以当前 router 的重挂接语义不是“只改 parent 指针”，而是“尽量保持世界空间位置、旋转和缩放不跳变”。 + +### 上下文菜单与创建动作 + +`DrawHierarchyContextActions(...)` 当前统一拼装了： + +- Detach +- Rename +- Delete +- Copy +- Paste +- Duplicate +- Create 子菜单 + +其中 `DrawHierarchyCreateActions(...)` 已经不只是创建“命名好的空物体”。 +按当前 [EntityCommands](../../Commands/EntityCommands/EntityCommands.md) 实现： + +- `CreateCameraEntity` 会附加 `CameraComponent` +- `CreateLightEntity` 会附加 `LightComponent` +- `CreatePrimitiveEntity` 会附加 `MeshFilterComponent` 与 `MeshRendererComponent` +- primitive 还会绑定内置 mesh 路径和默认 primitive material + +这点和旧文档结论不同，当前实现已经更接近商业引擎里“Create 3D Object” 的真实行为。 + +### Popup 诊断日志 + +文件中还有一组 `TraceHierarchyPopup(...)` 调试日志 helper。 +它们会在背景右键菜单、实体右键菜单和 `Create` 子菜单的打开 / 关闭过程中写日志，便于定位 ImGui popup 状态错乱问题。 ## 设计说明 -这类层级树交互通常非常碎，如果全写在面板类里，后续一加多选、拖放规则或菜单项就会迅速失控。 -把交互逻辑集中在 router 里有三个好处： +Hierarchy 交互往往是编辑器里最容易失控的一块，因为它同时牵涉： -- 面板类仍然只负责树结构遍历和 UI 布局 -- 所有入口都能复用同一套实体命令 -- 可以明确把“层级树交互规则”与“SceneManager 真正修改场景”的职责隔开 +- 选择 +- 多级树展开 +- 内联重命名 +- 拖放 +- 上下文菜单 +- 创建 / 删除 / 复制 / 粘贴 -这和 Unity Hierarchy 的设计也比较接近：Hierarchy 面板只是入口，真正的数据修改要落到场景编辑命令层。 +如果这些逻辑全部堆在 `HierarchyPanel.cpp`，后续一加多选、过滤、排序或者 prefab 支持，文件会很快失去可维护性。 + +当前拆成 router 的好处很实际： + +- `HierarchyPanel` 仍然能保持“绘树”为主。 +- 菜单、拖放、重命名可以复用同一套命令层。 +- 快捷键、菜单栏、右键菜单都能共用行为定义。 + +这就是商业编辑器常见的“thin panel, rich routing, centralized commands” 模式。 + +## 测试与验证 + +当前与该文件直接相关的行为，至少有以下测试锚点： + +- `HierarchyRouteExecutesCopyPasteDuplicateDeleteAndRename` +- `HierarchyRouterRenameHelpersPublishAndCommit` +- `HierarchyItemContextRequestSelectsEntityAndStoresPopupTarget` +- `ReparentPreserveWorldTransformKeepsWorldPose` + +这些测试位于 `tests/Editor/test_action_routing.cpp`，覆盖了 rename 请求、上下文目标记录、复制粘贴和保持世界变换的重挂接语义。 ## 当前限制 -- 暂不支持多实体批量拖拽 -- 只有 `Ctrl` 增选，没有框选、Shift 范围选中等高级交互 -- `Cube` / `Sphere` / `Plane` 当前只是命名约定，不会自动附加网格或渲染组件 +- 暂不支持多实体拖拽、范围选择或框选。 +- additive 选择不是完整 Ctrl-toggle / Shift-range 模型。 +- 拖拽 payload 使用原始 `GameObject*`，应视为单进程、单帧 UI 交互协议，而不是可持久化数据格式。 +- popup 诊断日志当前直接写常规日志通道，调试时有帮助，但正式产品里可能需要更细粒度的 trace 控制。 ## 相关文档 -- [Actions](../Actions.md) - [HierarchyPanel](../../panels/HierarchyPanel/HierarchyPanel.md) - [EntityCommands](../../Commands/EntityCommands/EntityCommands.md) - [EditorEvents](../../Core/EditorEvents/EditorEvents.md) +- [EventBus](../../Core/EventBus/EventBus.md) +- [EditorActionRoute](../../Core/EditorActionRoute/EditorActionRoute.md) +- [Widgets](../../UI/Widgets/Widgets.md) diff --git a/docs/api/XCEngine/Editor/Actions/MainMenuActionRouter/MainMenuActionRouter.md b/docs/api/XCEngine/Editor/Actions/MainMenuActionRouter/MainMenuActionRouter.md index 2f235d77..a15b435e 100644 --- a/docs/api/XCEngine/Editor/Actions/MainMenuActionRouter/MainMenuActionRouter.md +++ b/docs/api/XCEngine/Editor/Actions/MainMenuActionRouter/MainMenuActionRouter.md @@ -6,47 +6,173 @@ **源文件**: `editor/src/Actions/MainMenuActionRouter.h` -**描述**: 实现主菜单栏的文件、编辑、视图、帮助菜单，以及相应的全局快捷键和弹窗入口。 +**描述**: 主菜单栏动作路由层，负责把 File / Edit / Run / Scripts / View / Help 菜单项与全局快捷键翻译成 `Commands` 调用或 `EventBus` 请求事件。 ## 概述 -`MainMenuActionRouter` 是 `MenuBar` 面板背后的实际逻辑层。当前它负责： +`MainMenuActionRouter` 当前是 [MenuBar](../../panels/MenuBar/MenuBar.md) 的顶层工作流入口，而不只是几个 `ImGui::MenuItem` 的薄封装。 -- 新建、打开、保存场景 -- 撤销与重做 -- 请求退出编辑器 -- 请求重置 Dock 布局 -- 打开 About 弹窗 -- 在菜单栏右侧绘制当前场景状态 +按当前源码，它把三类链路汇到一起： -## 当前实现 +- 项目 / 场景文档命令 +- Play mode 请求事件 +- 布局与 About 这类宿主级 UI 事件 -- `ExecuteNewScene` / `ExecuteOpenScene` / `ExecuteSaveScene` 最终调用 [`SceneCommands`](../../Commands/SceneCommands/SceneCommands.md) -- `RequestEditorExit` 发布 `EditorExitRequestedEvent` -- `RequestDockLayoutReset` 发布 `DockLayoutResetRequestedEvent` -- `RequestAboutPopup` 通过 [`DeferredPopupState`](../../UI/PopupState/PopupState.md) 延迟打开 About 对话框 -- `HandleMenuBarShortcuts` 目前使用 `GlobalShortcutContext()` +这页最需要和旧文档区分的一点是： -`MenuBar.cpp` 的 `Render()` 顺序也比较清晰：先处理快捷键，再绘制菜单栏，最后绘制弹窗覆盖层。 +- 当前菜单里已经没有旧的场景资源迁移入口 +- 项目维护相关的真实菜单项现在只有 `Save Project` 与 `Scripts -> Rebuild Script Assemblies` -## 设计说明 +## 当前菜单结构 -把主菜单作为单独 router，而不是直接在 `MenuBar::Render` 里写一大串 `ImGui::MenuItem`，有两个明显收益： +### File -- 菜单项逻辑可以和命令层、事件总线清晰对接 -- 快捷键和菜单点击能共享同一套执行入口 +`DrawFileMenuActions(context)` 当前按顺序绘制： -这正是商业编辑器常见的菜单层设计方式。菜单不是业务逻辑本体，它只是统一入口。 +- `New Project...` +- `Open Project...` +- `Save Project` +- `New Scene` +- `Open Scene` +- `Save Scene` +- `Save Scene As...` +- `Exit` + +对应执行链路分别是： + +- `ExecuteNewProject()` -> `Commands::NewProjectWithDialog(context)` +- `ExecuteOpenProject()` -> `Commands::OpenProjectWithDialog(context)` +- `ExecuteSaveProject()` -> `Commands::SaveProject(context)` +- `ExecuteNewScene()` -> `Commands::NewScene(context)` +- `ExecuteOpenScene()` -> `Commands::OpenSceneWithDialog(context)` +- `ExecuteSaveScene()` -> `Commands::SaveCurrentScene(context)` +- `ExecuteSaveSceneAs()` -> `Commands::SaveSceneAsWithDialog(context)` +- `RequestEditorExit()` -> `EditorExitRequestedEvent` + +这里要注意两个实现语义： + +- `MainMenuActionRouter` 自己不处理保存结果弹窗；它只负责转接到 `Commands` +- `Save Project` 与场景保存一样，都受 `IsEditorDocumentEditingAllowed(...)` 约束 + +### Edit + +`Edit` 菜单继续委托给 [EditActionRouter](../EditActionRouter/EditActionRouter.md)，因此复制、粘贴、删除和重命名等上下文编辑行为不在这里重复定义。 + +### Run + +`DrawRunMenuActions(context)` 当前提供： + +- `Play` / `Stop` +- `Pause` / `Resume` +- `Step` + +这些入口不直接推进运行时，而是分别走： + +- `RequestTogglePlayMode()` -> `PlayModeStartRequestedEvent` / `PlayModeStopRequestedEvent` +- `RequestTogglePauseMode()` -> `PlayModePauseRequestedEvent` / `PlayModeResumeRequestedEvent` +- `RequestStepPlayMode()` -> `PlayModeStepRequestedEvent` + +因此 Run 菜单本质上是 [EventBus](../../Core/EventBus/EventBus.md) 的请求端。 + +### Scripts + +`DrawScriptsMenuActions(context)` 当前只有一个入口： + +- `Rebuild Script Assemblies` + +完整链路是： + +```text +MainMenuActionRouter +-> ExecuteRebuildScriptAssemblies(context) +-> Commands::RebuildScriptAssemblies(context) +-> Application::Get().RebuildScriptingAssemblies() +-> 成功时 ProjectManager.RefreshCurrentFolder() +``` + +菜单启用状态由 `Commands::CanRebuildScriptAssemblies(context)` 控制，而不是菜单层自己猜测。 + +菜单层当前不会消费 `RebuildScriptAssemblies(...)` 的布尔返回值。成功或失败的反馈主要依赖下游日志、脚本状态页和后续 UI 状态。 + +### View / Help + +- `View -> Reset Layout` 发布 `DockLayoutResetRequestedEvent` +- `Help -> About` 通过 [`DeferredPopupState`](../../UI/PopupState/DeferredPopupState.md) 请求打开 About 对话框 + +## 快捷键与可用性 + +`HandleMenuBarShortcuts(context)` 当前只处理： + +- Play / Pause / Step +- New / Open / Save Scene +- Undo / Redo +- `EditActionRouter` 定义的编辑快捷键 + +项目级菜单项当前都还是“菜单点击入口”，没有绑定全局快捷键，包括： + +- `New Project...` +- `Open Project...` +- `Save Project` +- `Rebuild Script Assemblies` + +菜单启用状态则基于四组条件： + +- `canEditDocuments` +- `canPause` +- `canStep` +- 下游 `ProjectCommands` 返回的 guard，如 `CanRebuildScriptAssemblies(...)` + +其中项目维护相关项有一个共同前提：当前 runtime mode 必须允许文档编辑。换句话说，在 `Play` / `Paused` 期间，`Save Project` 和 `Rebuild Script Assemblies` 这类会改动项目内容的入口都会被禁用。 + +## 和下游项目工作流的关系 + +当前和项目工作流相关的主链路可以概括成： + +```text +MenuBar +-> MainMenuActionRouter +-> ProjectCommands +-> Application / IProjectManager +-> ProjectManager / SceneManager / ProjectPanel +``` + +其中： + +- “保存项目”最终落到 [`ProjectCommands::SaveProject`](../../Commands/ProjectCommands/ProjectCommands.md)。 +- “重建脚本程序集”最终落到 [`Application::RebuildScriptingAssemblies`](../../Application/RebuildScriptingAssemblies.md)。 +- `ProjectPanel` 本身不暴露这两个入口，但会在下游 `RefreshCurrentFolder()` 之后同步自己的 `Assets` 视图。 + +这里再补一个容易误解的点： + +- `Rebuild Script Assemblies` 产物主要在 `/Library/ScriptAssemblies` +- 而 `ProjectPanel` 只投影 `/Assets` + +所以脚本重建成功后，菜单链路虽然会触发一次 `RefreshCurrentFolder()`，但它不保证 Project 面板一定出现肉眼可见的树变化。 + +## 测试锚点 + +`tests/Editor/test_action_routing.cpp` 当前直接或间接覆盖了这组路由的关键行为： + +- `MainMenuRouterRequestsExitResetAndAboutPopup` +- `MainMenuRouterRequestsPlayPauseResumeAndStepEvents` +- `ProjectCommandsReportWhenScriptAssembliesCanBeRebuilt` + +前两项验证菜单层事件路由，最后一项验证 `Scripts` 菜单下游命令的可用性。 ## 当前限制 -- 文件菜单当前只覆盖场景级工作流，没有项目级导入、构建或设置入口 -- About 弹窗内容仍然是开发中状态说明，不是正式产品级信息页 -- 全局快捷键冲突处理比较简单，尚未提供用户可配置热键系统 +- 主菜单动作仍以内联 helper 形式定义在头文件中，不是可注册的命令表。 +- 项目级菜单项当前没有默认快捷键。 +- `MainMenuActionRouter` 自己不展示保存结果或脚本重建结果摘要；返回值在这一层不会被消费，反馈更多依赖下游日志与状态页。 +- 文件菜单还没有 recent projects、project settings、build profiles 等更完整的项目入口。 ## 相关文档 - [Actions](../Actions.md) +- [EditorActions](../EditorActions/EditorActions.md) +- [EditActionRouter](../EditActionRouter/EditActionRouter.md) - [MenuBar](../../panels/MenuBar/MenuBar.md) +- [ProjectCommands](../../Commands/ProjectCommands/ProjectCommands.md) - [SceneCommands](../../Commands/SceneCommands/SceneCommands.md) +- [EventBus](../../Core/EventBus/EventBus.md) - [PopupState](../../UI/PopupState/PopupState.md) diff --git a/docs/api/XCEngine/Editor/Actions/ProjectActionRouter/ProjectActionRouter.md b/docs/api/XCEngine/Editor/Actions/ProjectActionRouter/ProjectActionRouter.md index 88a1663e..e6e4a500 100644 --- a/docs/api/XCEngine/Editor/Actions/ProjectActionRouter/ProjectActionRouter.md +++ b/docs/api/XCEngine/Editor/Actions/ProjectActionRouter/ProjectActionRouter.md @@ -6,43 +6,134 @@ **源文件**: `editor/src/Actions/ProjectActionRouter.h` -**描述**: 封装 Project 面板中的资源选择、导航、拖放、上下文菜单和创建文件夹弹窗流程。 +**描述**: Project 面板交互路由 helper，负责资源拖拽载荷、资源打开、返回上级导航、背景清选和项目项右键菜单目标建立。 ## 概述 -`ProjectActionRouter` 让 `ProjectPanel.cpp` 可以专注于资源网格布局，而把交互行为集中管理。当前覆盖的能力包括： +`ProjectActionRouter` 当前不是一个“大而全的项目面板行为中心”，而是一组比较薄的交互 helper。 -- 资源项选中与右键上下文菜单 -- 文件夹打开与返回上级导航 -- 资源拖放到目录 -- 空白区域上下文菜单 -- “Create Folder” 弹窗与提交 +它的职责边界和 [ProjectPanel](../../panels/ProjectPanel/ProjectPanel.md) / [ProjectCommands](../../Commands/ProjectCommands/ProjectCommands.md) 的分工很明确： -## 当前实现 +- `ProjectPanel` 负责目录树、面包屑、资源网格和上下文菜单的具体布局 +- `ProjectActionRouter` 负责把少量通用交互翻译成稳定动作 +- `ProjectCommands` 负责真正修改项目内容 -- 资源拖拽载荷类型固定为 `"ASSET_ITEM"` -- 打开资源时只支持两类：文件夹与 `type == "Scene"` 的资源 -- 删除资源调用 [`DeleteAsset`](../../Commands/ProjectCommands/ProjectCommands.md) -- 移动资源调用 `MoveAssetToFolder` -- 创建目录弹窗依赖 [`TextInputPopupState`](../../UI/PopupState/PopupState.md) +因此当前这页不应再描述成“承载创建文件夹弹窗、重命名、复制粘贴等完整资源 workflow”。那些语义如今主要已经在面板层和命令层展开了。 -`FindProjectItemIndex` 还额外做了 `fullPath` 匹配，这说明当前实现允许在某些刷新路径下通过值语义重新定位资源项，而不是完全依赖共享指针地址。 +## 当前覆盖的能力 + +按 `editor/src/Actions/ProjectActionRouter.h` 当前实现，这组 helper 主要覆盖： + +- 资源拖拽 payload 协议 +- 判断某个资源是否正处于拖拽中 +- 打开资源 +- 工具栏返回上级导航 +- Project 背景左键清选 +- Project 空白区右键菜单请求 +- Project 资源项右键菜单目标记录 + +## 关键 helper + +### 拖拽载荷 + +当前项目资源拖拽协议固定为： + +- `ProjectAssetPayloadType() -> "ASSET_ITEM"` + +拖拽数据本身不是 `AssetItemPtr`，而是： + +- `item->fullPath.c_str()` + +也就是说，当前 Project 拖拽协议使用的是“资源全路径字符串载荷”，而不是对象指针。 + +这和 Hierarchy 里的实体拖拽不同，也更适合项目资源这种需要跨刷新定位的对象。 + +相关 helper 包括： + +- `GetDraggedProjectAssetPath()` +- `IsProjectAssetBeingDragged(item)` +- `BeginProjectAssetDrag(item, iconKind)` + +### 打开资源 + +`OpenProjectAsset(...)` 当前只是一个薄封装： + +1. 先调用 `Commands::CanOpenAsset(item)` +2. 合法时再调用 `Commands::OpenAsset(context, item)` + +因此“什么资源可以打开”的判定权并不在 action router，而在命令层。 + +### 返回上级 + +`DrawProjectNavigateBackAction(...)` 当前负责： + +- 基于 `projectManager.CanNavigateBack()` 计算按钮是否启用 +- 点击后调用 `projectManager.NavigateBack()` + +这是 Project 工具栏里少量直接在 action 层完成的导航动作之一。 + +### 背景清选 + +`HandleProjectBackgroundPrimaryClick(...)` 的当前语义是： + +- 只有窗口悬停 +- 左键点击 +- 当前没有悬停任意 item +- 当前不处于 rename 状态 + +时，才调用： + +- `projectManager.ClearSelection()` + +这让 ProjectPanel 可以在“空白处点一下取消选中”和“行内重命名期间不要误清选”之间保持一致行为。 + +### 右键菜单目标 + +当前 router 提供了两组与上下文菜单相关的 helper： + +- `RequestProjectEmptyContextPopup(...)` +- `HandleProjectItemContextRequest(...)` + +前者只负责在空白区域右键时请求 popup；后者则会： + +1. 先把该项设为当前选中资源 +2. 再把它写入 [`TargetedPopupState`](../../UI/PopupState/TargetedPopupState.md) + +这样项目项右键菜单在打开时，选择状态和 popup target 是同步的。 + +## 当前没有负责什么 + +为了避免和旧文档混淆，需要明确当前这组 helper **不** 负责： + +- 资源重命名提交 +- 创建文件夹 / 创建材质 +- 删除资源 +- 移动资源到目录 +- 复制路径 + +这些行为如今分别在： + +- [ProjectPanel](../../panels/ProjectPanel/ProjectPanel.md) +- [ProjectCommands](../../Commands/ProjectCommands/ProjectCommands.md) + +中完成。 ## 设计说明 -Project 面板本质上是一个资产浏览器。 -把这些动作单独放在 router 层，有助于把以下两类变化隔开： +当前 `ProjectActionRouter` 的设计取向是合理的，因为它只保留那些真正适合抽成共享交互协议的部分： -- 视觉变化：列表改网格、加图标、加搜索、加分栏 -- 交互语义变化：打开、删除、移动、创建目录 +- 拖拽 payload +- 打开资源入口 +- 背景清选 +- 右键菜单目标建立 -这样后续即使 Project 面板彻底重画 UI，动作语义仍然可以稳定保留。 +而把更强业务语义留给 ProjectPanel 和命令层。这比把所有资源 workflow 都堆进一个 router header 更容易维护。 ## 当前限制 -- 当前资源系统没有更细的资源类型分发，场景之外的资源多数只能展示，不能打开 -- 资源重命名、复制、粘贴尚未实现 -- 没有回收站、删除确认和批量操作 +- 当前动作层本身不提供资源复制 / 粘贴协议。 +- `iconKind` 参数在 `BeginProjectAssetDrag(...)` 里当前没有实际参与绘制，拖拽预览被关闭。 +- 这组 helper 仍然假设调用点位于 Project 面板即时模式 UI 主循环中。 ## 相关文档 diff --git a/docs/api/XCEngine/Editor/Commands/Commands.md b/docs/api/XCEngine/Editor/Commands/Commands.md index 4e877785..044cc5ee 100644 --- a/docs/api/XCEngine/Editor/Commands/Commands.md +++ b/docs/api/XCEngine/Editor/Commands/Commands.md @@ -24,7 +24,7 @@ 从当前代码看，`Commands` 的职责边界已经比较清楚： - `SceneCommands` 负责场景文件生命周期 -- `ProjectCommands` 负责资产浏览器中的资源动作 +- `ProjectCommands` 负责资源动作、项目描述保存和项目文档级 helper - `EntityCommands` 负责场景树结构编辑 - `ComponentCommands` 负责 Inspector 中的组件增删 diff --git a/docs/api/XCEngine/Editor/Commands/EntityCommands/EntityCommands.md b/docs/api/XCEngine/Editor/Commands/EntityCommands/EntityCommands.md index a248f8e3..9f66f67d 100644 --- a/docs/api/XCEngine/Editor/Commands/EntityCommands/EntityCommands.md +++ b/docs/api/XCEngine/Editor/Commands/EntityCommands/EntityCommands.md @@ -6,49 +6,194 @@ **源文件**: `editor/src/Commands/EntityCommands.h` -**描述**: 封装实体创建、重命名、删除、复制粘贴、重复和父子重挂接等场景编辑命令。 +**描述**: 场景实体编辑命令集合，封装实体创建、重命名、删除、复制、粘贴、重复、重挂接和从父节点分离等标准编辑动作。 ## 概述 -`EntityCommands` 是当前 Scene 编辑工作流里最重要的一层命令辅助。 -Hierarchy 面板、Edit 菜单和快捷键触发的实体级操作，最终大多落到这里。 +`EntityCommands` 是当前 editor 场景编辑链路里的核心命令层之一。 +Hierarchy、Edit 菜单、快捷键和其他交互路由，不应该直接调用 `SceneManager` 做数据修改，而应该把“用户想做什么”翻译成稳定的命令语义。 -当前覆盖： +当前这组 helper 覆盖的核心操作包括： -- 创建空实体、Camera、Light -- 重命名与删除实体 -- 复制、粘贴、重复实体 -- 重挂接父节点并尽量保持世界变换 -- 从父节点分离实体 +- 创建空实体、相机、灯光和内置 primitive。 +- 重命名与删除实体。 +- 复制、粘贴、重复实体。 +- 改变父子关系，并在可能时保持世界空间变换。 +- 将实体从父节点分离到根层级。 -## 当前实现 +## 前置知识 -- 结构性修改统一通过 [`UndoUtils::ExecuteSceneCommand`](../../Utils/UndoUtils/UndoUtils.md) 包装 -- 创建实体后会自动把新实体设置为当前选中对象 -- `CreateCameraEntity` 与 `CreateLightEntity` 会附加对应组件 -- `CanReparentEntity` 会阻止把对象挂到自己的子孙节点下 -- `ReparentEntityPreserveWorldTransform` 会缓存当前位置、旋转和缩放，再执行 `MoveEntity` +理解这组 API，最重要的是分清两层： + +- [ISceneManager](../../Core/ISceneManager/ISceneManager.md) 负责真正的数据结构修改。 +- `EntityCommands` 负责把这些修改包装成编辑器可复用的“命令语义”。 + +这么做的原因很直接： + +- 统一接入 [UndoUtils](../../Utils/UndoUtils/UndoUtils.md)。 +- 统一处理“创建后选中”“粘贴后选中”这类编辑器行为。 +- 让 Hierarchy、菜单栏、快捷键共享同一套实现。 + +## 主要接口 + +| 成员 | 说明 | +|------|------| +| `CreateEntity(...)` | 通用模板创建入口，允许传入自定义 setup 回调。 | +| `CreateEmptyEntity(...)` | 创建空实体。 | +| `CreateCameraEntity(...)` | 创建实体并附加 `CameraComponent`。 | +| `CreateLightEntity(...)` | 创建实体并附加 `LightComponent`。 | +| `CreatePrimitiveEntity(...)` | 创建实体并附加 primitive 所需组件与资源引用。 | +| `RenameEntity(...)` | 重命名实体。 | +| `DeleteEntity(...)` | 删除实体。 | +| `CopyEntity(...)` | 把实体复制到 scene clipboard。 | +| `PasteEntity(...)` | 从 clipboard 粘贴实体，可指定父节点。 | +| `DuplicateEntity(...)` | 复制当前实体并插入场景。 | +| `CanReparentEntity(...)` | 判断目标父节点是否合法。 | +| `ReparentEntityPreserveWorldTransform(...)` | 重挂接到新父节点，并尽量保持世界变换。 | +| `DetachEntity(...)` | 从父节点分离到根节点。 | + +## 当前实现行为 + +### 命令包装与撤销 + +大多数会改动场景结构的操作，都会走： + +- `UndoUtils::ExecuteSceneCommand(context, commandLabel, ...)` + +这包括： + +- 创建 +- 重命名 +- 删除 +- 粘贴 +- 重复 +- 重挂接 + +这意味着 `EntityCommands` 的职责不只是帮你少写几行代码，而是确保场景级编辑动作可以用统一方式进入撤销系统。 + +一个重要例外是 `CopyEntity(...)`： + +- 它只写 scene clipboard，不改场景结构。 +- 因此当前没有包进 undo command。 + +### 创建语义 + +`CreateEntity(...)` 是所有创建 helper 的底层模板。 + +它会： + +1. 通过 `SceneManager::CreateEntity(...)` 创建实体。 +2. 执行可选的 `setup(created, sceneManager)` 回调。 +3. 把新实体设为当前选择。 + +这使得更高层的创建 helper 可以只关注“创建后要附加什么”。 + +### Camera / Light / Primitive + +当前具体 helper 的行为是： + +- `CreateCameraEntity(...)` + - 创建实体 + - 附加 `CameraComponent` +- `CreateLightEntity(...)` + - 创建实体 + - 附加 `LightComponent` +- `CreatePrimitiveEntity(...)` + - 创建实体 + - 确保存在 `MeshFilterComponent` + - 把 mesh 路径设为内置 primitive mesh + - 确保存在 `MeshRendererComponent` + - 给第 `0` 个材质槽绑定默认 primitive material + +这意味着当前 primitive 创建已经具备“立刻可见”的基础语义，而不是旧版本那种只生成命名空对象。 + +## 重命名、删除、复制、粘贴、重复 + +### 重命名与删除 + +- `RenameEntity(...)` 会先检查新名称非空且实体存在。 +- `DeleteEntity(...)` 会先检查实体是否存在。 + +这里要注意一点： + +- 这两个 helper 不自己维护 UI 选择状态。 +- 删除后选择如何清理，依赖更高层路由与 manager 的整体行为。 + +因此文档里不应把“删除后自动取消选择”错误归因到 `EntityCommands` 自身。 + +### 复制、粘贴、重复 + +- `CopyEntity(...)` 只是把实体写入 scene clipboard。 +- `PasteEntity(...)` 可以指定 `parentId`，成功后会把新实体设为选中对象。 +- `DuplicateEntity(...)` 依赖 `SceneManager::DuplicateEntity(...)`，成功后同样会把复制出的实体设为选中对象。 + +复制 / 粘贴 / 重复的深拷贝细节，当前并不在本文件里实现，而是委托给 [ISceneManager](../../Core/ISceneManager/ISceneManager.md)。 + +## 重挂接与保持世界变换 + +`CanReparentEntity(...)` 负责做最核心的合法性校验： + +- `source` 不能为空。 +- 不能把对象挂到自己的后代节点下。 + +`ReparentEntityPreserveWorldTransform(...)` 的实现重点在于： + +1. 读取当前父节点 id。 +2. 若目标父节点未变化，直接返回 `false`。 +3. 若对象没有 transform，直接 `MoveEntity(...)`。 +4. 若对象有 transform，则先缓存世界空间位置、旋转和缩放。 +5. 执行 `MoveEntity(...)`。 +6. 再把缓存下来的世界变换写回 transform。 + +这样做的设计目标非常明确： +用户在 Hierarchy 里换 parent 时，默认期望对象的世界空间姿态不要突然跳变。 + +`DetachEntity(...)` 本质上只是调用： + +- `ReparentEntityPreserveWorldTransform(context, entity, 0, ...)` + +也就是把对象挂回根节点。 ## 设计说明 -把实体编辑动作做成独立命令层，是编辑器架构里非常关键的一步。 -如果直接在 Hierarchy 面板里 `CreateEntity`、`DeleteEntity`、`MoveEntity`，会很快遇到三个问题： +把实体修改动作收敛到命令层，是编辑器工程质量的分水岭之一。 -- 撤销历史无法统一 -- 菜单栏、快捷键、右键菜单会重复同一逻辑 -- 结构修改和 UI 交互代码缠在一起 +如果直接在面板或 router 中散落调用： -`EntityCommands` 把“编辑行为语义”稳定下来，面板和 router 只需要负责调用它。 +- `CreateEntity` +- `DeleteEntity` +- `MoveEntity` +- `RenameEntity` + +会立刻遇到三个问题： + +- 撤销历史接不上。 +- 菜单栏、右键菜单、快捷键会复制同样的逻辑。 +- “UI 如何触发”与“场景如何修改”混在一起，后续难以扩展。 + +`EntityCommands` 的价值就在于把“商业编辑器里的标准实体操作”稳定成一层可复用协议。 + +## 测试与验证 + +当前至少有以下测试为这些命令提供行为锚点： + +- `HierarchyRouteExecutesCopyPasteDuplicateDeleteAndRename` +- `ReparentPreserveWorldTransformKeepsWorldPose` +- `HierarchyRouterRenameHelpersPublishAndCommit` +- `PlayModeAllowsRuntimeSceneUndoRedoButKeepsSceneDocumentCommandsBlocked` + +这些测试表明当前命令层不仅在 Edit 模式使用，也参与 Play 模式下的运行时场景编辑与 undo/redo。 ## 当前限制 -- `CreateCubeEntity` / `CreateSphereEntity` / `CreatePlaneEntity` 在当前路由中实际上还是创建命名后的空实体，不会自动生成渲染组件 -- 粘贴和重复的深拷贝语义完全依赖 `ISceneManager` 当前实现 -- 多实体批量命令尚未覆盖 +- 仍然是单实体命令集，没有批量操作协议。 +- 粘贴与重复的深拷贝语义完全依赖 [ISceneManager](../../Core/ISceneManager/ISceneManager.md) 当前实现。 +- “保持世界变换”当前只覆盖 transform 的位置、旋转、缩放，不涵盖其他可能依赖父层级的自定义状态。 +- 是否允许在某个 editor runtime mode 下执行，通常由更高层调用点决定，不是每个 helper 自己都做模式拦截。 ## 相关文档 -- [Commands](../Commands.md) - [HierarchyActionRouter](../../Actions/HierarchyActionRouter/HierarchyActionRouter.md) -- [SceneManager](../../Managers/SceneManager/SceneManager.md) +- [HierarchyPanel](../../panels/HierarchyPanel/HierarchyPanel.md) +- [ISceneManager](../../Core/ISceneManager/ISceneManager.md) - [UndoUtils](../../Utils/UndoUtils/UndoUtils.md) diff --git a/docs/api/XCEngine/Editor/Commands/ProjectCommands/ProjectCommands.md b/docs/api/XCEngine/Editor/Commands/ProjectCommands/ProjectCommands.md index 3483d2ea..5b1429db 100644 --- a/docs/api/XCEngine/Editor/Commands/ProjectCommands/ProjectCommands.md +++ b/docs/api/XCEngine/Editor/Commands/ProjectCommands/ProjectCommands.md @@ -6,44 +6,224 @@ **源文件**: `editor/src/Commands/ProjectCommands.h` -**描述**: 封装 Project 面板中与资源打开、目录创建、删除和移动相关的高层操作。 +**描述**: Project 工作流命令集合，封装项目切换与保存、资源浏览与文件操作，以及脚本程序集重建等高层动作。 ## 概述 -`ProjectCommands` 当前是一个很轻量的命令头，但它已经把 Project 面板最基础的资源管理语义集中起来： +`ProjectCommands` 当前已经不只是“打开资源 + 建目录 + 删除/移动”的薄命令头。 -- `CanOpenAsset` -- `OpenAsset` -- `CreateFolder` -- `DeleteAsset` -- `MoveAssetToFolder` +按 `ProjectCommands.h` 的真实实现，它覆盖四组链路： -这让资源浏览面板不必直接操作底层 manager 细节。 +- 资源浏览与编辑命令 +- 项目文档保存命令 +- 脚本程序集重建 +- 项目切换与项目目录初始化 -## 当前实现 +和 [ProjectPanel](../../panels/ProjectPanel/ProjectPanel.md) 的关系也很清楚： -- 资源能否打开，当前只看两种情况：目录，或 `item->type == "Scene"` -- 打开目录时调用 `IProjectManager::NavigateToFolder` -- 打开场景资源时转发到 [`LoadScene`](../SceneCommands/SceneCommands.md) -- 创建目录和删除资源只做最小参数校验，然后委托给 `IProjectManager` -- 资源拖入目录时会比较源路径与目标路径，避免把资源移动到自己身上 +- Panel 负责 UI 与交互采样 +- Commands 负责 guard、规则和 manager / application 调用 + +## 资源命令 + +### 打开资源 + +`CanOpenAsset(item)` 当前只在两种情况下返回 `true`： + +- `item->isFolder` +- `item->type == "Scene"` + +`OpenAsset(context, item)` 则进一步区分： + +- 文件夹: `context.GetProjectManager().NavigateToFolder(item)` +- 场景资源: 转发到 [`LoadScene`](../SceneCommands/SceneCommands.md) + +因此当前“打开资源”仍然是收敛语义，不会在这里直接承载脚本、材质或图片编辑器分发。 + +### 创建文件夹 + +`CreateFolder(projectManager, name)` 当前只做最基本校验： + +- 名称不能为空 + +真正的唯一命名、落盘和刷新由 [`IProjectManager::CreateFolder`](../../Core/IProjectManager/IProjectManager.md) 负责。 + +### 创建材质 + +`CreateMaterial(projectManager, name)` 当前会： + +1. 读取当前目录与根目录。 +2. 验证当前目录位于项目根目录内。 +3. 自动补 `.mat` 扩展名。 +4. 为重名文件追加数字后缀。 +5. 直接写出默认材质 JSON。 +6. `RefreshCurrentFolder()`。 +7. 定位新建条目并设为当前选中项。 + +因此 `ProjectPanel` 右键菜单里的 `Create -> Material` 已经是落地命令，不再只是 UI 预留位。 + +### 删除 / 移动 / 重命名 + +这三类命令当前都只是把高层工作流规则收口后，再委托给 `IProjectManager`： + +- `DeleteAsset(...)` -> `projectManager.DeleteItem(...)` +- `MoveAssetToFolder(...)` -> `projectManager.MoveItem(...)` +- `RenameAsset(...)` -> `projectManager.RenameItem(...)` + +其中 `CanMoveAssetToFolder(...)` 额外承担了较完整的安全校验，包括： + +- 源与目标都必须位于项目根目录内 +- 不能移动项目根目录本身 +- 不能把目录移动到自己的子目录 +- 不能覆盖同名目标 + +## 项目保存命令 + +### `EnsureProjectStructure(projectPath)` + +当前会确保以下目录存在： + +- `Assets/Scenes` +- `.xceditor` + +### `BuildProjectDescriptor(context)` + +当前会结合： + +- `context.GetProjectPath()` +- `context.GetSceneManager().GetCurrentScenePath()` + +构建项目描述；当没有有效当前场景时，回退到： + +- `Assets/Scenes/Main.xc` + +### `SaveProject(context)` + +这是当前项目保存链路的总入口，主要流程是： + +1. 检查当前 runtime mode 是否允许文档编辑。 +2. `EnsureProjectStructure(context.GetProjectPath())`。 +3. 通过 `SaveDirtySceneWithFallback(...)` 保存当前场景，必要时回退到 `Assets/Scenes/Main.xc`。 +4. `context.GetProjectManager().RefreshCurrentFolder()`。 +5. `Application::Get().SaveProjectState()`。 +6. `SaveProjectDescriptor(context)`。 + +这说明 `ProjectCommands` 当前已经超出“Project 面板本地命令”的范畴，开始承担项目文档生命周期本身。 + +还要注意这个顺序的真实含义： + +- `RefreshCurrentFolder()` 只会同步 `Assets` 浏览树 +- `SaveProjectState()` 和项目描述文件会落在 `Assets` 之外的项目级位置 + +因此“保存项目”成功并不等于 `ProjectPanel` 一定出现明显可见变化；面板刷新更多是在保证项目资源视图和磁盘状态保持一致。 + +## 脚本程序集重建 + +### `CanRebuildScriptAssemblies(context)` + +当前 guard 很明确： + +- 文档编辑必须允许 +- 项目路径不能为空 + +### `RebuildScriptAssemblies(context)` + +这是 `Scripts -> Rebuild Script Assemblies` 菜单项的命令层入口。 + +当前流程是： + +1. 先走 `CanRebuildScriptAssemblies(context)`。 +2. 调用 [`Application::RebuildScriptingAssemblies`](../../Application/RebuildScriptingAssemblies.md)。 +3. 若重建成功，执行 `context.GetProjectManager().RefreshCurrentFolder()`。 +4. 把布尔结果直接返回给调用方。 + +因此它的职责边界是： + +- `ProjectCommands` 负责 guard 和后置刷新。 +- `Application` 负责真正的程序集构建。 + +这里有两个很实际的调用语义： + +- 返回 `false` 既可能是 guard 不通过，也可能是下游脚本构建失败。 +- 即使返回 `true`，`RefreshCurrentFolder()` 也不代表 `ProjectPanel` 一定会出现新条目，因为脚本程序集产物主要位于 `/Library/ScriptAssemblies`，不在 `Assets` 投影视图内。 + +## 项目切换与目录选择 + +### `SwitchProject(context, projectPath)` + +当前项目切换主流程是： + +1. 要求允许文档编辑。 +2. 要求目标路径非空。 +3. 通过 `SceneEditorUtils::ConfirmSceneSwitch(context)` 处理场景切换确认。 +4. `EnsureProjectStructure(projectPath)`。 +5. `Application::Get().SwitchProject(projectPath)`。 +6. 写回 `context.SetProjectPath(projectPath)`。 +7. `context.GetProjectManager().Initialize(projectPath)`。 +8. `context.GetSceneManager().LoadStartupScene(projectPath)`。 +9. 清空选择与 undo 历史。 +10. `RefreshCurrentFolder()`。 +11. 若成功加载启动场景，则 `SaveProjectDescriptor(context)`。 + +这说明 `ProjectCommands` 现在也是 Project 生命周期切换的统一入口，而不是只服务 `ProjectPanel`。 + +这里的重置动作也很关键： + +- `ClearSelection()` 保证旧项目里的资源 / 实体选择不会泄漏到新项目上下文 +- `ClearHistory()` 保证旧项目的撤销栈不会跨项目复用 + +### `NewProjectWithDialog(context)` / `OpenProjectWithDialog(context)` + +这两个 helper 都通过 `FileDialogUtils::PickFolderDialog(...)` 选择目录，然后回到 `SwitchProject(...)`。 + +也就是说： + +- 对话框归它们负责 +- 真正的切换规则仍收口在 `SwitchProject(...)` ## 设计说明 -现在这层看起来很薄，但它依然有存在价值。 -原因在于 Project 面板的 UI 以后很可能持续变化，而“什么资源能打开、什么动作合法、如何调用 manager”这些规则应该集中在一个稳定位置。 +当前 `ProjectCommands` 的设计方向很清楚： -这也是商业编辑器常见的演进路径：先用轻量命令层收口，等资源类型和导入系统成熟后，再逐渐扩展成完整 asset workflow。 +- 把资源管理规则集中化 +- 把项目文档保存链路集中化 +- 把项目维护类动作从菜单 / 面板层抽离出来 +- 让 `ProjectPanel` 只消费命令，而不自己拼文件系统规则 + +当前最值得明确的一点是：旧文档里提到的项目级批量场景迁移入口已经不在这个头文件里，当前保留下来的项目维护动作只有： + +- 保存项目 +- 重建脚本程序集 +- 切换项目 / 新建项目 / 打开项目 + +这才是当前源码里的真实分层。 + +## 测试锚点 + +`tests/Editor/test_action_routing.cpp` 当前直接覆盖或锚定了这组命令的关键行为： + +- `ProjectCommandsReportWhenScriptAssembliesCanBeRebuilt` +- `ProjectCommandsCreateFolderMoveAssetAndOpenFolderHelper` +- `ProjectCommandsCreateFolderUsesUniqueDefaultName` +- `ProjectCommandsRenameAssetUpdatesSelectionAndPreservesFileExtension` +- `ProjectCommandsRejectInvalidMoveTargets` +- `ProjectCommandsRejectMovingFolderIntoItsDescendant` ## 当前限制 -- 只能打开文件夹和场景资源 -- 没有资源重命名、复制粘贴、导入和重新导入 -- 删除和移动操作没有事务、确认框或冲突解决策略 +- 资源打开仍然只覆盖文件夹和场景。 +- 创建材质当前写的是内置默认 JSON 骨架，没有更复杂模板选择。 +- 删除、移动、重命名仍然没有事务预览或冲突解决 UI。 +- 资源复制 / 粘贴 / 重新导入仍未形成命令层协议。 +- 脚本重建当前只返回布尔值，不负责弹窗反馈或进度 UI；主菜单层也不会消费这个返回值。 ## 相关文档 - [Commands](../Commands.md) +- [MainMenuActionRouter](../../Actions/MainMenuActionRouter/MainMenuActionRouter.md) +- [ProjectPanel](../../panels/ProjectPanel/ProjectPanel.md) - [ProjectActionRouter](../../Actions/ProjectActionRouter/ProjectActionRouter.md) +- [IProjectManager](../../Core/IProjectManager/IProjectManager.md) - [ProjectManager](../../Managers/ProjectManager/ProjectManager.md) - [SceneCommands](../SceneCommands/SceneCommands.md) +- [Application](../../Application/Application.md) diff --git a/docs/api/XCEngine/Editor/ComponentEditors/AssetReferenceEditorUtils/AssetReferenceEditorUtils.md b/docs/api/XCEngine/Editor/ComponentEditors/AssetReferenceEditorUtils/AssetReferenceEditorUtils.md new file mode 100644 index 00000000..fef50d21 --- /dev/null +++ b/docs/api/XCEngine/Editor/ComponentEditors/AssetReferenceEditorUtils/AssetReferenceEditorUtils.md @@ -0,0 +1,57 @@ +# AssetReferenceEditorUtils + +**命名空间**: `XCEngine::Editor::ComponentEditorAssetUI` + +**类型**: `header-helper` + +**源文件**: `editor/src/ComponentEditors/AssetReferenceEditorUtils.h` + +**描述**: 为组件编辑器提供统一的“资产引用属性行”封装，把 Inspector 属性行布局和 `ReferencePicker` 资产选择控件拼成一个小 helper。 + +## 概述 + +`AssetReferenceEditorUtils.h` 的目标很简单：让具体组件编辑器不用重复写同一套“标签 + 引用选择器 + 清空按钮 + 扩展名过滤”组合。 + +当前它主要服务于： + +- [MeshFilterComponentEditor](../MeshFilterComponentEditor/MeshFilterComponentEditor.md) +- [MeshRendererComponentEditor](../MeshRendererComponentEditor/MeshRendererComponentEditor.md) + +## 公开结构 + +### `AssetReferenceInteraction` + +当前只回传两件事： + +- `assignedPath` +- `clearRequested` + +组件编辑器再根据这两个结果自行决定是否写入 undo 记录和组件字段。 + +## `DrawAssetReferenceProperty()` + +这个 helper 当前会： + +1. 组装 `ReferencePickerOptions` +2. 强制使用 assets-only picker +3. 应用调用方给定的扩展名过滤 +4. 在 `UI::DrawPropertyRow()` 里嵌入 picker 控件 +5. 返回资产路径变更和清空请求 + +当前特意把 `showSceneTab` 关闭，因为这条 helper 的语义就是“组件资产引用”，不消费场景对象选择结果。 + +## 设计说明 + +这类 helper 的价值不在于逻辑复杂，而在于把常见 Inspector 模式沉淀下来： + +- 统一交互 +- 统一文案 +- 统一布局 +- 降低具体组件编辑器的模板代码 + +## 相关文档 + +- [ComponentEditors](../ComponentEditors.md) +- [MeshFilterComponentEditor](../MeshFilterComponentEditor/MeshFilterComponentEditor.md) +- [MeshRendererComponentEditor](../MeshRendererComponentEditor/MeshRendererComponentEditor.md) +- [ReferencePicker](../../UI/ReferencePicker/ReferencePicker.md) diff --git a/docs/api/XCEngine/Editor/ComponentEditors/ComponentEditorRegistry/ComponentEditorRegistry.md b/docs/api/XCEngine/Editor/ComponentEditors/ComponentEditorRegistry/ComponentEditorRegistry.md index 41e25a2f..dfae439c 100644 --- a/docs/api/XCEngine/Editor/ComponentEditors/ComponentEditorRegistry/ComponentEditorRegistry.md +++ b/docs/api/XCEngine/Editor/ComponentEditors/ComponentEditorRegistry/ComponentEditorRegistry.md @@ -6,50 +6,72 @@ **源文件**: `editor/src/ComponentEditors/ComponentEditorRegistry.h` -**描述**: 持有并注册所有组件编辑器实例，按组件类型名为 Inspector 提供统一查询入口。 +**描述**: 组件编辑器注册中心，负责持有全部 `IComponentEditor` 实例，并为 Inspector 与 Add Component 菜单提供按组件类型查询的统一入口。 ## 概述 -`ComponentEditorRegistry` 是当前 Inspector 组件编辑器系统的注册中心。它负责： +`ComponentEditorRegistry` 是当前 Inspector 组件编辑器系统的路由中心。它本身不绘制 UI，也不修改场景数据；它负责： -- 拥有 `IComponentEditor` 实例 -- 按组件实例查找 editor -- 按组件类型名查找 editor -- 暴露所有已注册 editor，供 Inspector 侧遍历和构建“添加组件”入口 +- 拥有 editor 对象的生命周期。 +- 维护“组件类型名 -> editor”的快速查询映射。 +- 为 Inspector 和 Add Component 菜单暴露统一入口。 -## 当前注册列表 +可以把它理解成编辑器组件 Inspector 体系的服务定位器。 -按 `editor/src/ComponentEditors/ComponentEditorRegistry.cpp`，构造函数当前会注册： +## 公开成员 -1. `TransformComponentEditor` -2. `CameraComponentEditor` -3. `LightComponentEditor` -4. `MeshFilterComponentEditor` -5. `MeshRendererComponentEditor` -6. [ScriptComponentEditor](../ScriptComponentEditor/ScriptComponentEditor.md) +| 成员 | 说明 | +|------|------| +| `Get()` | 返回 registry 单例。 | +| `RegisterEditor(...)` | 注册一个 editor 并建立类型名索引。 | +| `FindEditor(component)` | 根据组件实例找到对应 editor。 | +| `FindEditorByTypeName(...)` | 根据组件类型名找到 editor。 | +| `GetEditors()` | 返回当前已注册 editor 列表。 | -这说明脚本组件编辑器已经是 registry 里的正式一员，而不是 Inspector 特判分支。 +## 当前实现行为 -## 数据结构 +按 `ComponentEditorRegistry.cpp` 的实现： -- `m_editors`：`std::vector>`，负责真正拥有 editor 对象 -- `m_editorsByType`：按 `GetComponentTypeName()` 建立的快速索引 +- `Get()` 使用函数内静态对象实现单例。 +- 构造函数当前会自动注册： + - `TransformComponentEditor` + - `CameraComponentEditor` + - `LightComponentEditor` + - `MeshFilterComponentEditor` + - `MeshRendererComponentEditor` + - [ScriptComponentEditor](../ScriptComponentEditor/ScriptComponentEditor.md) +- `RegisterEditor(...)` 会把 `unique_ptr` 存入 `m_editors`，并把裸指针缓存到 `m_editorsByType`。 +- `FindEditor(component)` 默认通过 `component->GetName()` 走类型名查询。 -`RegisterEditor()` 当前会先把裸指针写入 `m_editorsByType`，再把 `unique_ptr` 推入 `m_editors`。 +## 与 Inspector 的关系 -## 当前实现边界 +当前 registry 至少被两条主路径直接使用： -- 注册列表写死在构造函数里，不是插件式发现机制。 -- 如果后注册 editor 与已有类型名重复，`m_editorsByType` 会被覆盖，但 `m_editors` 里仍会保留多个对象。 -- `FindEditor(component)` 依赖组件的 `GetName()` 返回值与 editor 的 `GetComponentTypeName()` 完整对齐。 +- `InspectorPanel::RenderComponent(...)` + - 查 editor + - 读取显示名 + - 调用 `Render(...)` +- `InspectorActionRouter::DrawInspectorAddComponentMenu(...)` + - 枚举 `GetEditors()` + - 根据 `ShowInAddComponentMenu()` 与 `CanAddTo()` 构建 Add Component 菜单 + +这意味着 registry 不只是“显示用查表”，它也参与组件添加工作流。 ## 与 ScriptComponentEditor 的关系 -`ScriptComponentEditor` 通过这里注册后，InspectorPanel 就能像处理普通组件一样处理脚本组件： +脚本组件 Inspector 不是 `InspectorPanel` 里的特殊分支，而是通过 registry 正常注册的一种 editor。这一点很重要，因为它说明即便是“依赖脚本运行时元数据”的复杂 Inspector，也仍然遵循与其他组件一致的接入模型。 -- 按 `ScriptComponent` 类型查找到 editor -- 调用其 `Render()` 获取脚本类选择器和脚本字段 UI -- 继续复用统一的撤销与 Inspector 布局体系 +## 所有权与生命周期 + +- `m_editors` 持有全部 editor 的所有权。 +- `m_editorsByType` 只保存指向 `m_editors` 内对象的非拥有指针。 +- registry 生命周期绑定到 `Get()` 的静态对象生命周期。 + +## 当前限制 + +- 当前是手工注册，不是反射或插件发现。 +- 若重复注册同一 `GetComponentTypeName()`，`m_editorsByType` 会被覆盖，但 `m_editors` 中旧实例仍会保留。 +- 线程安全没有显式保证，应视为 Editor 主线程设施。 ## 相关文档 diff --git a/docs/api/XCEngine/Editor/ComponentEditors/ComponentEditors.md b/docs/api/XCEngine/Editor/ComponentEditors/ComponentEditors.md index 101432c2..16b41761 100644 --- a/docs/api/XCEngine/Editor/ComponentEditors/ComponentEditors.md +++ b/docs/api/XCEngine/Editor/ComponentEditors/ComponentEditors.md @@ -4,47 +4,86 @@ **类型**: `submodule` -**描述**: Inspector 组件编辑器层，负责把运行时组件映射成可撤销、可交互的专用编辑 UI。 +**源目录**: `editor/src/ComponentEditors/` + +**描述**: Inspector 组件编辑器子模块，负责把运行时组件映射为编辑器侧的专用检查器 UI、添加/移除策略和交互式修改入口。 ## 概述 -当前组件编辑器系统走的是典型的“按组件类型注册专用 editor”路线： +`ComponentEditors` 是当前 Inspector 扩展体系里最重要的一层。它的职责不是保存组件数据，而是决定“某个组件在编辑器里应该如何被看见和编辑”。 -- [IComponentEditor](IComponentEditor/IComponentEditor.md) 定义统一契约 -- [ComponentEditorRegistry](ComponentEditorRegistry/ComponentEditorRegistry.md) 负责注册、拥有和查找 editor -- 各个具体 editor 只处理自己的组件 UI 与交互规则 +按当前实现，这条链路很清晰： -这比把所有组件字段塞进一个通用 Inspector 渲染器更容易扩展，也更方便为特殊组件接入脚本元数据、引用选择器和撤销逻辑。 +1. `InspectorPanel` 遍历选中对象上的组件。 +2. [ComponentEditorRegistry](ComponentEditorRegistry/ComponentEditorRegistry.md) 负责查找匹配的 editor。 +3. 每个具体 editor 只处理自己负责的组件类型。 +4. 若 editor 报告发生修改，`InspectorPanel` 会标记场景 dirty。 -## 当前已记录的 editor +这和商业编辑器常见的 custom inspector / details customization 设计非常接近。这样做的直接收益是，复杂组件不会把 `InspectorPanel` 本身变成一个巨大的 `switch`。 -- [TransformComponentEditor](TransformComponentEditor/TransformComponentEditor.md) -- [CameraComponentEditor](CameraComponentEditor/CameraComponentEditor.md) -- [LightComponentEditor](LightComponentEditor/LightComponentEditor.md) -- [ScriptComponentEditor](ScriptComponentEditor/ScriptComponentEditor.md) +## 当前调用链 -## 当前注册但尚未单独补页的 editor +按 `InspectorPanel.cpp` 和 `InspectorActionRouter.h` 的实现： -按 `ComponentEditorRegistry.cpp` 当前实现，registry 还会注册： +- `ComponentEditorRegistry::Get().FindEditor(component)` 决定当前组件由谁绘制。 +- editor 的 `GetDisplayName()` 决定 Inspector 组件节标题。 +- editor 的 `Render(...)` 负责真正的字段 UI。 +- Add Component 菜单通过 `ComponentEditorRegistry::Get().GetEditors()` 遍历所有可显示 editor。 +## 已建立的 canonical 页面 + +| 页面 | 说明 | +|------|------| +| [IComponentEditor](IComponentEditor/IComponentEditor.md) | 组件编辑器统一契约。 | +| [ComponentEditorRegistry](ComponentEditorRegistry/ComponentEditorRegistry.md) | editor 注册中心与查询入口。 | +| [TransformComponentEditor](TransformComponentEditor/TransformComponentEditor.md) | Transform 组件 Inspector。 | +| [CameraComponentEditor](CameraComponentEditor/CameraComponentEditor.md) | Camera 组件 Inspector。 | +| [LightComponentEditor](LightComponentEditor/LightComponentEditor.md) | Light 组件 Inspector。 | +| [AssetReferenceEditorUtils](AssetReferenceEditorUtils/AssetReferenceEditorUtils.md) | 资产引用属性行 helper。 | +| [MeshFilterComponentEditor](MeshFilterComponentEditor/MeshFilterComponentEditor.md) | MeshFilter 组件 Inspector。 | +| [MeshRendererComponentEditor](MeshRendererComponentEditor/MeshRendererComponentEditor.md) | MeshRenderer 组件 Inspector。 | +| [ScriptComponentEditor](ScriptComponentEditor/ScriptComponentEditor.md) | Script 组件 Inspector 与脚本字段编辑入口。 | +| [ScriptComponentEditorUtils](ScriptComponentEditorUtils/ScriptComponentEditorUtils.md) | 脚本组件编辑器辅助规则与格式化 helper。 | + +## 当前源码对齐情况 + +按 `ComponentEditorRegistry.cpp` 当前实现，registry 实际注册的 editor 包括： + +- `TransformComponentEditor` +- `CameraComponentEditor` +- `LightComponentEditor` - `MeshFilterComponentEditor` - `MeshRendererComponentEditor` +- `ScriptComponentEditor` -## ScriptComponentEditor 在这层里的位置 +这说明当前组件编辑器系统已经不再只覆盖基础三组件，而是已经承载渲染组件和脚本组件的 Inspector 逻辑。当前 canonical 树已经把渲染组件 editor、脚本组件 editor 和它们共用的资产引用 helper 都补齐了。 -[ScriptComponentEditor](ScriptComponentEditor/ScriptComponentEditor.md) 是这套系统里最依赖运行时元数据的一个 editor。它不是直接读取 `ScriptComponent` 自身的字段列表，而是通过 `ScriptEngine::TryGetScriptFieldModel()` 获取： +## ScriptComponentEditor 的特殊性 -- 当前脚本类是否已分配 / 可用 / 缺失 -- 字段元数据 -- 默认值、stored override 和 live managed value 的合成结果 -- stored-only / type mismatch 一类问题状态 +[ScriptComponentEditor](ScriptComponentEditor/ScriptComponentEditor.md) 是这个子模块里最依赖运行时元数据的一页。它不是直接读取 `ScriptComponent` 的本地成员列表，而是通过 [ScriptEngine](../../Scripting/ScriptEngine/ScriptEngine.md) 查询： -因此它也是 `ComponentEditors` 子模块和 `Scripting` 子模块的主要交汇点。 +- 当前脚本类是否已分配、可用或缺失。 +- 脚本字段元数据。 +- 默认值、stored override 与 live managed value 的合成结果。 +- `StoredOnly`、`TypeMismatch` 一类问题状态。 + +因此它也是当前 `ComponentEditors` 和 `Scripting` 子模块之间最重要的交汇点之一。 + +## 设计说明 + +把组件编辑 UI 拆成独立 editor 类型，有几个非常现实的好处： + +- 不同组件可以拥有完全不同的 Inspector 交互形态。 +- Add / Remove 规则可以跟组件类型一起定义。 +- 像脚本组件这种依赖运行时元数据的复杂面板，不会污染整个 Inspector 主循环。 + +## 当前限制 + +- `ComponentEditorRegistry` 仍然是构造函数里手工注册，不是插件式发现机制。 ## 相关文档 -- [ComponentEditorRegistry](ComponentEditorRegistry/ComponentEditorRegistry.md) -- [ScriptComponentEditor](ScriptComponentEditor/ScriptComponentEditor.md) -- [ScriptComponentEditorUtils](ScriptComponentEditorUtils/ScriptComponentEditorUtils.md) +- [Editor](../Editor.md) - [InspectorPanel](../panels/InspectorPanel/InspectorPanel.md) - [Components](../../Components/Components.md) +- [Scripting](../../Scripting/Scripting.md) diff --git a/docs/api/XCEngine/Editor/ComponentEditors/MeshFilterComponentEditor/MeshFilterComponentEditor.md b/docs/api/XCEngine/Editor/ComponentEditors/MeshFilterComponentEditor/MeshFilterComponentEditor.md new file mode 100644 index 00000000..9993e788 --- /dev/null +++ b/docs/api/XCEngine/Editor/ComponentEditors/MeshFilterComponentEditor/MeshFilterComponentEditor.md @@ -0,0 +1,43 @@ +# MeshFilterComponentEditor + +**命名空间**: `XCEngine::Editor` + +**类型**: `class` + +**源文件**: `editor/src/ComponentEditors/MeshFilterComponentEditor.h` + +**描述**: `MeshFilterComponent` 的专用 Inspector 编辑器，负责 mesh 资产路径选择、清空与撤销集成。 + +## 概述 + +`MeshFilterComponentEditor` 是当前渲染组件 Inspector 链路里的第一环。它不直接管理 mesh 资源加载，而是负责把用户在 Inspector 里选中的模型资产路径写回 [MeshFilterComponent](../../../Components/MeshFilterComponent/MeshFilterComponent.md)。 + +## 当前 Render 流程 + +`Render(...)` 当前行为很直接： + +1. 把输入组件 `dynamic_cast` 成 `MeshFilterComponent` +2. 调用 [AssetReferenceEditorUtils](../AssetReferenceEditorUtils/AssetReferenceEditorUtils.md) 绘制 `Mesh` 资产引用行 +3. 仅接受模型扩展名： + - `.fbx` + - `.obj` + - `.gltf` + - `.glb` +4. 若用户请求清空，则通过 undo 包装调用 `meshFilter->ClearMesh()` +5. 若用户指定了新路径，则通过 undo 包装调用 `meshFilter->SetMeshPath(...)` + +## Add / Remove 规则 + +- `CanAddTo()` 只允许一个对象拥有一个 `MeshFilterComponent` +- 若对象上已存在 `MeshFilterComponent`，`GetAddDisabledReason()` 返回 `Already Added` +- `CanRemove()` 当前直接复用 `CanEdit(component)` + +## 设计取向 + +这个 editor 明显走的是“只编辑路径，不直接编辑运行时句柄”的路线。这样做是合理的，因为资源解析、artifact 导入和句柄维护本来就属于运行时资源系统，而不是 Inspector UI。 + +## 相关文档 + +- [ComponentEditors](../ComponentEditors.md) +- [AssetReferenceEditorUtils](../AssetReferenceEditorUtils/AssetReferenceEditorUtils.md) +- [MeshFilterComponent](../../../Components/MeshFilterComponent/MeshFilterComponent.md) diff --git a/docs/api/XCEngine/Editor/ComponentEditors/MeshRendererComponentEditor/MeshRendererComponentEditor.md b/docs/api/XCEngine/Editor/ComponentEditors/MeshRendererComponentEditor/MeshRendererComponentEditor.md new file mode 100644 index 00000000..bcb9100b --- /dev/null +++ b/docs/api/XCEngine/Editor/ComponentEditors/MeshRendererComponentEditor/MeshRendererComponentEditor.md @@ -0,0 +1,57 @@ +# MeshRendererComponentEditor + +**命名空间**: `XCEngine::Editor` + +**类型**: `class` + +**源文件**: `editor/src/ComponentEditors/MeshRendererComponentEditor.h` + +**描述**: `MeshRendererComponent` 的专用 Inspector 编辑器，负责可见材质槽位推导和材质资产路径编辑。 + +## 概述 + +`MeshRendererComponentEditor` 负责把 [MeshRendererComponent](../../../Components/MeshRendererComponent/MeshRendererComponent.md) 的材质绑定变成 Inspector 里的多槽位材质选择器。 + +和 `MeshFilterComponentEditor` 相比，它多做了一步：会根据当前 mesh 和 section 信息推导“应该显示多少个材质槽位”。 + +## 当前 Render 流程 + +`Render(...)` 当前会： + +1. 把输入组件转换成 `MeshRendererComponent` +2. 计算可见材质槽位数 `GetVisibleMaterialSlotCount(...)` +3. 对每个槽位绘制一个 `Material N` 资产引用行 +4. 仅接受 `.mat` 资产 +5. 清空时调用 `SetMaterialPath(slotIndex, std::string())` +6. 赋值时调用 `SetMaterialPath(slotIndex, assignedPath)` +7. 所有修改都通过 undo 标签 `Modify Mesh Renderer` 包装 + +## 材质槽位推导规则 + +当前 `GetVisibleMaterialSlotCount(...)` 会取以下信息的最大值： + +- `MeshRendererComponent::GetMaterialCount()` +- 若对象上有 `MeshFilterComponent` 且 mesh 有效： + - `mesh->GetMaterials().Size()` + - 所有 section 的 `materialID + 1` + +另外，最小槽位数始终至少为 `1`。 + +这保证了 Inspector 能同时覆盖： + +- 组件自己已经保存的材质路径 +- mesh 导入时声明的材质数组 +- section 显式索引到的更高材质槽位 + +## Add / Remove 规则 + +- `CanAddTo()` 只允许一个对象拥有一个 `MeshRendererComponent` +- 若对象上已存在该组件，`GetAddDisabledReason()` 返回 `Already Added` +- `CanRemove()` 当前直接复用 `CanEdit(component)` + +## 相关文档 + +- [ComponentEditors](../ComponentEditors.md) +- [AssetReferenceEditorUtils](../AssetReferenceEditorUtils/AssetReferenceEditorUtils.md) +- [MeshRendererComponent](../../../Components/MeshRendererComponent/MeshRendererComponent.md) +- [MeshFilterComponent](../../../Components/MeshFilterComponent/MeshFilterComponent.md) diff --git a/docs/api/XCEngine/Editor/ComponentEditors/ScriptComponentEditor/ScriptComponentEditor.md b/docs/api/XCEngine/Editor/ComponentEditors/ScriptComponentEditor/ScriptComponentEditor.md index 98de11b1..fca2303b 100644 --- a/docs/api/XCEngine/Editor/ComponentEditors/ScriptComponentEditor/ScriptComponentEditor.md +++ b/docs/api/XCEngine/Editor/ComponentEditors/ScriptComponentEditor/ScriptComponentEditor.md @@ -6,51 +6,76 @@ **源文件**: `editor/src/ComponentEditors/ScriptComponentEditor.h` -**描述**: `ScriptComponent` 的专用 Inspector 编辑器，负责脚本类选择、脚本字段绘制、override 写回和运行时不可用提示。 +**描述**: `ScriptComponent` 的专用 Inspector 编辑器，负责脚本类选择、脚本字段绘制、override 写回与脚本运行时不可用状态提示。 ## 概述 -`ScriptComponentEditor` 是当前 Inspector 里最动态的一类组件编辑器。它实现了 [IComponentEditor](../IComponentEditor/IComponentEditor.md)，但和普通“直接编辑组件成员”的 editor 不同，它要先经过 [ScriptEngine](../../../Scripting/ScriptEngine/ScriptEngine.md) 查询脚本字段模型，再决定能显示什么、能编辑什么。 +`ScriptComponentEditor` 是当前 `ComponentEditors` 子模块里最动态的一类 editor。和普通“直接编辑组件成员”的 editor 不同，它必须先通过 [ScriptEngine](../../../Scripting/ScriptEngine/ScriptEngine.md) 查询脚本字段模型，再决定： -当前 `Render()` 的主流程是： +- 当前脚本类是否已分配。 +- 当前脚本类是否还能从已加载程序集里解析出来。 +- 每个字段是默认值、stored override，还是 live managed value。 +- 哪些字段已经变成 `StoredOnly` 或 `TypeMismatch`。 -1. 把传入组件 `dynamic_cast` 成 [ScriptComponent](../../../Scripting/ScriptComponent/ScriptComponent.md) -2. 绘制脚本类选择器 -3. 调用 `ScriptEngine::TryGetScriptFieldModel()` 获取当前脚本类状态和字段快照 -4. 根据类状态显示 hint、缺失信息或字段列表 -5. 对每个字段决定走可编辑控件还是只读显示 -6. 必要时提供 `Reset` 按钮清除 stored override +因此它更像脚本序列化系统的 Inspector 前端，而不是简单的属性表单。 + +## 当前 Render 流程 + +按 `ScriptComponentEditor.h` 当前实现，`Render(...)` 大致遵循下面的顺序： + +1. 将传入组件 `dynamic_cast` 成 [ScriptComponent](../../../Scripting/ScriptComponent/ScriptComponent.md)。 +2. 绘制脚本类下拉选择器。 +3. 调用 `ScriptEngine::TryGetScriptFieldModel(...)` 获取 [ScriptFieldModel](../../../Scripting/ScriptField/ScriptField.md)。 +4. 根据 `classStatus` 显示未分配、缺失或空字段列表提示。 +5. 遍历 `model.fields`，对每个字段决定走可编辑控件还是只读显示。 +6. 若字段存在 override 或当前值来自 managed runtime，则显示 `Reset` 按钮。 ## 脚本类选择器 -脚本类下拉框的数据来自 `ScriptEngine::TryGetAvailableScriptClasses()`。 +脚本类下拉框的数据来自 `ScriptEngine::TryGetAvailableScriptClasses(...)`。 -- 已分配脚本类且能在当前 runtime 中找到时，显示规范化类名 -- 已分配但当前加载的脚本程序集里找不到时，显示 `"(Missing)"` -- 未分配时显示 `None` +当前行为是： -如果当前没有加载到脚本程序集，editor 还会读取 `Application::Get().GetScriptRuntimeStatus()`，并按状态决定是否显示： +- 未分配脚本类时显示 `None`。 +- 若当前脚本类仍存在于已加载程序集里，显示格式化类名。 +- 若组件已记录脚本类，但当前运行时解析不到，会显示 `"(Missing)"` 后缀。 -- `Rebuild Scripts` -- `Reload Scripts` +当当前没有成功加载脚本程序集时，editor 还会读取 `Application::Get().GetScriptRuntimeStatus()`，并按状态显示： -这意味着脚本组件编辑器不仅是字段编辑 UI，也是脚本运行时状态的主要反馈入口之一。 +- 提示文本 +- `Rebuild Scripts` 按钮 +- `Reload Scripts` 按钮 -## 字段元数据来源 +这说明 `ScriptComponentEditor` 不只是字段编辑 UI，也是脚本运行时状态反馈入口之一。 -字段列表不是直接从 `ScriptComponent` 本地成员生成的，而是来自 `ScriptEngine::TryGetScriptFieldModel()` 合成的 `ScriptFieldModel`： +## 字段模型与元数据来源 -- 脚本类元数据来自 `IScriptRuntime::TryGetClassFieldMetadata()` -- 默认值来自运行时侧的类默认值采集 -- live managed value 优先来自 `TryGetManagedFieldValue()` -- 如果没有 live instance，则回退到 `ScriptComponent::GetFieldStorage()` 中的 stored override -- 如果 storage 里存在脚本类已不再声明的字段，会以 `StoredOnly` 形式补到模型里 +字段列表不是直接从 `ScriptComponent` 本地成员生成，而是来自 `ScriptEngine::TryGetScriptFieldModel(...)` 合成的 `ScriptFieldModel`。 -这也是 editor 能区分“可编辑字段”“只剩 stored override 的遗留字段”“类型不匹配字段”的原因。 +按 `ScriptEngine.cpp` 当前实现，字段模型会综合： + +- 脚本类元数据: + - `IScriptRuntime::TryGetClassFieldMetadata(...)` +- 运行时可获得的字段默认值 +- 当前 live managed value +- `ScriptComponent::GetFieldStorage()` 里的 stored override + +由此可以得到几种很关键的状态： + +- `declaredInClass = true` + - 字段仍由当前脚本类声明 +- `valueSource = DefaultValue / StoredValue / ManagedValue` + - 当前 Inspector 展示值的来源 +- `issue = StoredOnly` + - 存储里还有旧字段，但脚本类已经不再声明它 +- `issue = TypeMismatch` + - stored override 类型与当前脚本字段类型不一致 + +`tests/Scripting/test_script_engine.cpp` 与 `tests/Scripting/test_mono_script_runtime.cpp` 当前都覆盖了这些模型组合与状态值。 ## 当前支持的字段类型 -按 `RenderScriptFieldEditor()` 当前实现，editor 支持这些字段控件： +按 `RenderScriptFieldEditor()` 当前实现，editor 当前支持： - `Float` - `Double` @@ -65,41 +90,59 @@ 其中： -- `String` 使用内部 `StringFieldEditState` 做编辑缓存，避免外部同步打断输入 -- `GameObject` 通过 `UI::DrawReferencePickerControl()` 和场景对象 UUID / ID 映射完成引用选择 +- `String` 使用内部 `StringFieldEditState` 缓存输入框文本，避免外部同步打断当前编辑。 +- `GameObject` 通过 `UI::DrawReferencePickerControl(...)` 与场景对象 UUID / 运行时 ID 映射完成引用选择。 -## 可编辑性与 reset 规则 +## 写回与 Reset 语义 -当前规则由 [ScriptComponentEditorUtils](../ScriptComponentEditorUtils/ScriptComponentEditorUtils.md) 决定： +当前写回路径统一走： -- `classStatus == Available` 且字段确实由当前类声明时，字段可编辑 -- 类缺失或未分配时，stored-only 字段也允许继续编辑 / 保留 -- 当字段存在 stored value，或当前值来自 managed runtime 时，显示 `Reset` +- `ScriptEngine::ApplyScriptFieldWrites(...)` +- `ScriptEngine::ClearScriptFieldOverrides(...)` -写回路径则统一走： +并在 Inspector 层配合 `IUndoManager` 启动交互式撤销记录。当前使用的撤销标签包括： -- `ScriptEngine::ApplyScriptFieldWrites()` -- `ScriptEngine::ClearScriptFieldOverrides()` +- `Modify Script Component` +- `Modify Script Field` +- `Clear Script Field Override` -并在 Inspector 层接入 `IUndoManager::BeginInteractiveChange(...)`。 +`Reset` 的真实语义不是简单“清空显示值”，而是： -## 当前实现边界 +- 若字段存在 stored override，则移除存储值。 +- 若运行时当前有 live instance，则把 managed field 重置到默认值。 -- 当前不支持多对象联合编辑。 -- `StringFieldEditState` 以 `scriptComponentUUID + fieldName` 为键缓存，没有额外清理失效键的机制。 -- 对不支持的字段类型会退回只读文本显示，而不是显示通用编辑器。 -- `CanAddTo()` 当前对任意非空 `GameObject` 都返回 `true`，没有做“每对象只能有一个 ScriptComponent”之类的额外限制。 +这一点在 `tests/Scripting/test_script_engine.cpp` 的 field clear 相关测试里已有明确覆盖。 + +## 与 ScriptComponent 和 ScriptEngine 的关系 + +- [ScriptComponent](../../../Scripting/ScriptComponent/ScriptComponent.md) + - 保存脚本类标识和字段存储。 +- [ScriptEngine](../../../Scripting/ScriptEngine/ScriptEngine.md) + - 负责查询可用脚本类、生成字段模型、执行字段写回和清除 override。 +- `ScriptComponentEditor` + - 只负责 Inspector 展示和交互编排，不自己维护脚本字段语义。 + +这种分层是合理的：脚本运行时和字段模型属于 `Scripting` 模块，Inspector 负责把它们变成可操作 UI。 ## 测试与真实调用点 -- `ComponentEditorRegistry` 当前会自动注册这个 editor。 -- `tests/Editor/test_script_component_editor_utils.cpp` 覆盖了它依赖的显示名、字段可编辑性、issue 文本和 runtime 状态提示规则。 -- Inspector 真实字段模型和写回语义依赖 `ScriptEngine.cpp` 当前实现。 +- `ComponentEditorRegistry.cpp` 当前会自动注册 `ScriptComponentEditor`。 +- `InspectorPanel.cpp` 通过 registry 调用它的 `Render(...)`。 +- `tests/Editor/test_script_component_editor_utils.cpp` 覆盖了它依赖的显示规则与 issue 文本逻辑。 +- `tests/Scripting/test_script_engine.cpp` 与 `tests/Scripting/test_mono_script_runtime.cpp` 覆盖了字段模型、批量写入和 clear override 的真实语义。 + +## 当前限制 + +- 当前不支持多对象联合编辑。 +- `StringFieldEditState` 以 `scriptComponentUUID + fieldName` 为键缓存，当前没有专门的失效回收策略。 +- 对不支持的字段类型会退回到只读文本显示。 +- `CanAddTo()` 当前对任意非空 `GameObject` 都返回 `true`，没有额外的“每对象只能有一个脚本组件”限制。 ## 相关文档 - [ComponentEditors](../ComponentEditors.md) - [ComponentEditorRegistry](../ComponentEditorRegistry/ComponentEditorRegistry.md) - [ScriptComponentEditorUtils](../ScriptComponentEditorUtils/ScriptComponentEditorUtils.md) -- [ScriptEngine](../../../Scripting/ScriptEngine/ScriptEngine.md) - [ScriptComponent](../../../Scripting/ScriptComponent/ScriptComponent.md) +- [ScriptEngine](../../../Scripting/ScriptEngine/ScriptEngine.md) +- [ScriptField](../../../Scripting/ScriptField/ScriptField.md) diff --git a/docs/api/XCEngine/Editor/ComponentEditors/ScriptComponentEditorUtils/ScriptComponentEditorUtils.md b/docs/api/XCEngine/Editor/ComponentEditors/ScriptComponentEditorUtils/ScriptComponentEditorUtils.md index bf9ad4d7..5b0f67c9 100644 --- a/docs/api/XCEngine/Editor/ComponentEditors/ScriptComponentEditorUtils/ScriptComponentEditorUtils.md +++ b/docs/api/XCEngine/Editor/ComponentEditors/ScriptComponentEditorUtils/ScriptComponentEditorUtils.md @@ -6,78 +6,104 @@ **源文件**: `editor/src/ComponentEditors/ScriptComponentEditorUtils.h` -**描述**: 为 `ScriptComponentEditor` 提供显示名格式化、场景对象 UUID 查找、字段可编辑性判断和脚本运行时状态提示的内联辅助函数集合。 +**描述**: 为 `ScriptComponentEditor` 提供脚本类显示名格式化、场景对象 UUID 查询、字段可编辑性判断与脚本运行时状态提示规则。 ## 概述 -`ScriptComponentEditorUtils.h` 不是一个运行时对象，而是一组专门为 [ScriptComponentEditor](../ScriptComponentEditor/ScriptComponentEditor.md) 服务的 helper。它把那些“不是 UI 控件本身，但决定 UI 怎么显示”的规则集中到了一个地方，避免这些判断散落在 editor 主流程里。 +`ScriptComponentEditorUtils.h` 不是运行时对象，而是一组专门服务于 [ScriptComponentEditor](../ScriptComponentEditor/ScriptComponentEditor.md) 的规则函数。它把那些“不直接绘制控件，但决定 Inspector 如何显示”的判断集中起来，避免这些策略散落在 editor 主流程里。 -## 当前承担的工作 +## 主要职责 -### 脚本类显示名 +| 函数 | 作用 | +|------|------| +| `BuildScriptClassDisplayName(...)` | 生成脚本类下拉框里的可读标签。 | +| `FindGameObjectIdByUuidRecursive(...)` | 递归在场景树里查找目标 UUID 对应的对象 ID。 | +| `FindGameObjectIdByUuid(...)` | 从根对象列表入口执行 UUID 查找。 | +| `CanEditScriptField(...)` | 判断某个字段在当前类状态下是否允许编辑。 | +| `CanClearScriptFieldOverride(...)` | 判断是否应显示 `Reset`。 | +| `BuildScriptFieldIssueText(...)` | 把 `StoredOnly` / `TypeMismatch` 转成用户提示。 | +| `BuildScriptRuntimeUnavailableHint(...)` | 生成脚本运行时不可用提示文本。 | +| `CanReloadScriptRuntime(...)` | 判断是否应启用 `Reload Scripts`。 | +| `CanRebuildScriptAssemblies(...)` | 判断是否应启用 `Rebuild Scripts`。 | -- `BuildScriptClassDisplayName(descriptor)` -- `BuildScriptClassDisplayName(component)` +## 脚本类显示名规则 + +`BuildScriptClassDisplayName(...)` 当前的约定是： + +- 若程序集名为空，或程序集名为 `GameScripts`，只显示完整类名。 +- 否则显示 `FullName (AssemblyName)`。 + +这个规则很实用，因为主项目脚本程序集是最常见路径，保持简洁更利于阅读；而工具程序集或扩展程序集仍能通过后缀区分来源。 + +`tests/Editor/test_script_component_editor_utils.cpp` 已覆盖这一格式化行为。 + +## UUID 到场景对象 ID 的桥接 + +脚本字段里的 `GameObjectReference` 保存的是 UUID，但 Inspector 引用选择器使用的是当前场景对象的运行时 ID。`FindGameObjectIdByUuidRecursive(...)` / `FindGameObjectIdByUuid(...)` 的作用，就是在这两套标识之间做桥接。 + +这也是 `GameObject` 类型脚本字段能在 Inspector 中正常显示与回选的关键。 + +## 字段编辑性与问题提示 + +`CanEditScriptField(...)` 当前规则很关键： + +- 当 `classStatus == Available` 时，只有 `declaredInClass == true` 的字段允许编辑。 +- 当脚本类缺失或未分配时，stored-only 字段仍允许继续查看和编辑。 + +`CanClearScriptFieldOverride(...)` 当前只要满足任一条件就返回 `true`： + +- 字段存在 stored value +- 字段当前值来自 `ManagedValue` + +`BuildScriptFieldIssueText(...)` 当前主要覆盖两种问题： + +- `StoredOnly` + - `Stored override is not declared by the selected script.` +- `TypeMismatch` + - `Stored override type is X, but the script field expects Y.` + +这些规则决定了 `ScriptComponentEditor` 是绘制可编辑控件、只读文本，还是提示用户当前字段已经偏离脚本声明。 + +## 脚本运行时不可用提示 + +这组 helper 还负责把 `EditorScriptRuntimeStatus` 转成 Inspector 上可直接显示的提示文本与按钮启用条件。 当前规则是： -- 如果程序集名为空，或程序集名为 `GameScripts`，只显示完整类名 -- 否则显示 `FullName (AssemblyName)` +- `statusMessage` 非空时，优先直接显示运行时给出的完整状态文案。 +- 若后端未启用，显示当前构建不包含 Mono scripting 支持。 +- 若程序集目录已知但没有加载到程序集，显示目录级提示。 -这让项目主脚本程序集保持简洁显示，而工具程序集仍能区分来源。 +`CanReloadScriptRuntime(...)` 与 `CanRebuildScriptAssemblies(...)` 当前都要求： -### 场景对象 UUID 到 Inspector 可选目标的映射 +- `backendEnabled = true` +- `assemblyDirectory` 非空 -- `FindGameObjectIdByUuidRecursive(...)` -- `FindGameObjectIdByUuid(...)` +## 设计说明 -`GameObjectReference` 在脚本字段里存的是 UUID，但 Inspector 引用选择器用的是当前 scene object 的运行时 ID。这组函数负责在场景树里做桥接查找。 +把这些规则收拢到 utils 层有明显收益： -### 字段可编辑性与问题提示 - -- `CanEditScriptField(...)` -- `CanClearScriptFieldOverride(...)` -- `BuildScriptFieldIssueText(...)` - -当前规则里最关键的一点是： - -- 当脚本类状态是 `Available` 时，只有 `declaredInClass == true` 的字段可编辑 -- 当类缺失或未分配时，遗留 stored 字段仍可继续显示和编辑 - -issue 文本当前主要覆盖： - -- `StoredOnly` -- `TypeMismatch` - -### 脚本运行时不可用提示 - -- `BuildScriptRuntimeUnavailableHint(...)` -- `CanReloadScriptRuntime(...)` -- `CanRebuildScriptAssemblies(...)` - -这些函数把 `EditorScriptRuntimeStatus` 转成 Inspector 上可直接显示的 hint 与按钮启用条件。 - -## 为什么这层有价值 - -`ScriptComponentEditor` 同时依赖： - -- 脚本运行时状态 -- 场景对象层级 -- 脚本字段问题状态 - -把这些判断抽到 utils 后，editor 主类就更聚焦于“如何渲染 UI”和“什么时候写回 ScriptEngine”，而不是维护大量显示策略分支。 +- `ScriptComponentEditor` 主类可以聚焦在 UI 与写回时机。 +- 字段问题文本、显示名格式和按钮启用逻辑都能统一维护。 +- 这些规则更容易被单元测试直接覆盖。 ## 测试覆盖 `tests/Editor/test_script_component_editor_utils.cpp` 当前验证了： -- 脚本类显示名格式化 -- 场景层级里的 UUID 查找 -- 字段可编辑性、可清除性和 issue 文本 -- runtime unavailable hint 与 reload / rebuild 可用性 +- 脚本类显示名格式化。 +- 层级场景中的 UUID 查找。 +- 字段可编辑性、可清除性和 issue 文本。 +- 运行时 unavailable hint 与 rebuild / reload 可用性判断。 + +## 当前限制 + +- UUID 查找基于当前场景根对象递归遍历，不是索引化查询。 +- 这些 helper 只封装当前 `ScriptComponentEditor` 所需规则，不是通用脚本 Inspector 框架。 ## 相关文档 - [ScriptComponentEditor](../ScriptComponentEditor/ScriptComponentEditor.md) -- [ScriptEngine](../../../Scripting/ScriptEngine/ScriptEngine.md) - [ScriptComponent](../../../Scripting/ScriptComponent/ScriptComponent.md) +- [ScriptEngine](../../../Scripting/ScriptEngine/ScriptEngine.md) +- [ScriptField](../../../Scripting/ScriptField/ScriptField.md) diff --git a/docs/api/XCEngine/Editor/Core/EditorRuntimeMode/EditorRuntimeMode.md b/docs/api/XCEngine/Editor/Core/EditorRuntimeMode/EditorRuntimeMode.md index 585e2b39..e71e8a09 100644 --- a/docs/api/XCEngine/Editor/Core/EditorRuntimeMode/EditorRuntimeMode.md +++ b/docs/api/XCEngine/Editor/Core/EditorRuntimeMode/EditorRuntimeMode.md @@ -60,8 +60,8 @@ - `editor/src/Actions/EditorActions.h` - `editor/src/Actions/MainMenuActionRouter.h` - `editor/src/panels/MenuBar.cpp` -- `tests/editor/test_action_routing.cpp` -- `tests/editor/test_play_session_controller.cpp` +- `tests/Editor/test_action_routing.cpp` +- `tests/Editor/test_play_session_controller.cpp` ## 相关文档 diff --git a/docs/api/XCEngine/Editor/Core/PlaySessionController/PlaySessionController.md b/docs/api/XCEngine/Editor/Core/PlaySessionController/PlaySessionController.md index 1811124c..2077d12b 100644 --- a/docs/api/XCEngine/Editor/Core/PlaySessionController/PlaySessionController.md +++ b/docs/api/XCEngine/Editor/Core/PlaySessionController/PlaySessionController.md @@ -104,7 +104,7 @@ 这些事件都不会驱动运行时 `InputManager` -这是 `tests/editor/test_play_session_controller.cpp` 明确覆盖的当前规则。 +这是 `tests/Editor/test_play_session_controller.cpp` 明确覆盖的当前规则。 通过这道门槛后，`Update()` 才会按顺序执行： @@ -200,9 +200,9 @@ input.hovered || input.focused 当前已有两组直接测试： -- `tests/editor/test_play_session_controller.cpp` +- `tests/Editor/test_play_session_controller.cpp` - 覆盖快照恢复、事件总线路由、暂停/恢复/步进，以及“非 Play mode 不驱动 InputManager”和“Play mode 下输入被桥接并在空事件后释放” -- `tests/editor/test_play_session_controller_scripting.cpp` +- `tests/Editor/test_play_session_controller_scripting.cpp` - 覆盖 play mode 下脚本生命周期、fixed delta 传递、managed 输入桥接和停止后恢复编辑态场景 ## 当前实现边界 diff --git a/docs/api/XCEngine/Editor/Editor.md b/docs/api/XCEngine/Editor/Editor.md index b163c079..85cb4d8d 100644 --- a/docs/api/XCEngine/Editor/Editor.md +++ b/docs/api/XCEngine/Editor/Editor.md @@ -4,7 +4,7 @@ **类型**: `app-module` -**描述**: XCEngine 独立编辑器应用层 API 文档入口，对应 `editor/src/**` 的模块结构，覆盖应用启动、上下文、面板、布局、命令、动作路由与 UI 基础设施。 +**描述**: XCEngine 独立编辑器应用层 API 文档入口，对应 `editor/src/**` 的模块结构，覆盖应用启动、上下文、面板、布局、命令、动作路由、视口基础设施、脚本工具链、UI 基础设施与 XCUI 过渡后端。 ## 概述 @@ -24,6 +24,12 @@ 承载 Scene / Game / Hierarchy / Inspector / Console / Project 等主要工作面板。 6. [UI](UI/UI.md) 承载 Dear ImGui 上层的主题 token、chrome、树视图、属性布局和通用 widget。 +7. [XCUIBackend](XCUIBackend/XCUIBackend.md) + 承载 XCUI draw data 到当前 ImGui 宿主的过渡桥接层。 +8. [Viewport](Viewport/Viewport.md) + 承载 Scene / Game 视口宿主、对象 picking、overlay 与 gizmo 交互基础设施。 +9. [Scripting](Scripting/Scripting.md) + 承载编辑器侧脚本程序集重建与脚本运行时状态反馈。 ## 架构定位 @@ -52,8 +58,6 @@ - `editor/src/UI/UI.h` 这是 UI 子模块的 umbrella header，文档并入 [UI](UI/UI.md)。 -- `editor/src/EditorResources.h` - 当前只定义了 `IDI_APP_ICON 101`，用于 `EditorApp.rc` 的资源 id 绑定，更适合作为 Editor 应用资源入口说明，而不是独立类型页。 - `editor/src/EditorApp.rc`、`editor/src/main.cpp` 属于应用启动与资源清单支撑文件，不是面向上层复用的编辑器 API。 @@ -72,14 +76,18 @@ - [Commands](Commands/Commands.md) - 面向场景与项目操作的命令封装。 - [ComponentEditors](ComponentEditors/ComponentEditors.md) - 组件编辑器注册与实现。 - [Core](Core/Core.md) - 上下文、事件、撤销、选择与基础接口。 +- [EditorResources](EditorResources/EditorResources.md) - Windows 资源脚本使用的资源 id。 - [Layers](Layers/Layers.md) - 编辑器 layer 封装。 - [Layout](Layout/Layout.md) - Dock 布局控制。 - [Managers](Managers/Managers.md) - 项目和场景管理实现。 - [panels](panels/panels.md) - 主要工作面板。 - [Platform](Platform/Platform.md) - Win32 宿主与 D3D12 窗口渲染路径。 +- [Scripting](Scripting/Scripting.md) - Editor 侧脚本程序集构建与状态反馈。 - [Theme](Theme/Theme.md) - 顶层主题入口。 - [UI](UI/UI.md) - Editor UI 基础设施。 +- [XCUIBackend](XCUIBackend/XCUIBackend.md) - XCUI 到 ImGui 的过渡后端。 - [Utils](Utils/Utils.md) - 场景编辑与撤销相关辅助函数。 +- [Viewport](Viewport/Viewport.md) - Scene / Game 视口宿主、overlay 与 gizmo 基础设施。 ## 相关文档 diff --git a/docs/api/XCEngine/Editor/EditorResources/EditorResources.md b/docs/api/XCEngine/Editor/EditorResources/EditorResources.md new file mode 100644 index 00000000..108dc668 --- /dev/null +++ b/docs/api/XCEngine/Editor/EditorResources/EditorResources.md @@ -0,0 +1,29 @@ +# EditorResources + +**命名空间**: `XCEngine::Editor` + +**类型**: `resource-header` + +**源文件**: `editor/src/EditorResources.h` + +**描述**: 定义编辑器 Windows 资源脚本使用的资源 id 常量。 + +## 概述 + +`EditorResources.h` 当前非常小，但它确实承担了 `EditorApp.rc` 和应用图标资源之间的绑定角色。 + +## 当前定义 + +- `IDI_APP_ICON = 101` + +这个资源 id 当前用于编辑器主程序图标。 + +## 当前实现边界 + +- 当前只是一个轻量资源头文件，不承载可复用的运行时逻辑。 +- 资源脚本本身仍在 `editor/src/EditorApp.rc`。 + +## 相关文档 + +- [Editor](../Editor.md) +- [Application](../Application/Application.md) diff --git a/docs/api/XCEngine/Editor/Layout/DockLayoutController/DockLayoutController.md b/docs/api/XCEngine/Editor/Layout/DockLayoutController/DockLayoutController.md index 08e29c42..fd06e3c4 100644 --- a/docs/api/XCEngine/Editor/Layout/DockLayoutController/DockLayoutController.md +++ b/docs/api/XCEngine/Editor/Layout/DockLayoutController/DockLayoutController.md @@ -20,9 +20,12 @@ ## 当前实现说明 -- `Attach(IEditorContext&)` 会订阅布局重置事件。 +- `Attach(IEditorContext&)` 只有在 context 发生变化时才会重新订阅 `DockLayoutResetRequestedEvent`。 - `Detach()` 会取消订阅并把 `m_layoutDirty` 重新标记为 `true`。 -- `RenderDockspace()` 每帧都会绘制全窗口 dock host，并在 `m_layoutDirty` 为真时重建默认布局。 +- `RequestReset()` 不会立刻改布局，而是把重建请求延后到下一次 `RenderDockspace()`。 +- `RenderDockspace()` 当前以 `MainViewport->WorkPos / WorkSize` 作为宿主区域，先配置 dock host window，再在 `DockHostStyleScope` 里提交 `ImGui::DockSpace(...)`。 +- `RenderDockspace()` 会在创建 dockspace 前后都调用 `ConfigureDockTabBarChrome(...)`，确保 tab bar 样式与 node 配置保持一致。 +- `m_layoutDirty` 为真时会重建默认布局，并在本帧结束前清掉 `m_layoutDirty` 与 `m_forceRebuild`。 - 默认布局当前是： - 左边 `Hierarchy` - 中间 `Scene` / `Game` @@ -40,6 +43,7 @@ - 当前默认布局是硬编码的。 - 当前只依赖 ImGui DockBuilder，没有更高层布局配置文件系统。 +- `m_forceRebuild` 当前只是和 reset 请求一起被置位/清零，并没有独立改变 build 分支；真实生效条件仍然是 `m_layoutDirty`。 ## 相关文档 diff --git a/docs/api/XCEngine/Editor/Platform/D3D12WindowRenderer/D3D12WindowRenderer.md b/docs/api/XCEngine/Editor/Platform/D3D12WindowRenderer/D3D12WindowRenderer.md index c655f6b0..6995811a 100644 --- a/docs/api/XCEngine/Editor/Platform/D3D12WindowRenderer/D3D12WindowRenderer.md +++ b/docs/api/XCEngine/Editor/Platform/D3D12WindowRenderer/D3D12WindowRenderer.md @@ -14,30 +14,48 @@ 它当前自己管理： -- `ID3D12Device` -- `ID3D12CommandQueue` -- `ID3D12CommandAllocator` -- `ID3D12GraphicsCommandList` -- `IDXGISwapChain3` -- RTV / SRV descriptor heap -- back buffer render targets -- fence +- `RHIDevice` +- `RHICommandQueue` +- `RHICommandList` +- `RHISwapChain` +- shader-visible SRV descriptor heap +- back buffer render target views + +## 公开 API + +### 生命周期 + +- [Initialize / Shutdown](Initialize-And-Shutdown.md) + +### 帧切换 + +- [Resize / BeginFrame](Resize-And-BeginFrame.md) + +### 渲染与上下文 + +- [Render / GetRenderContext](Render-And-RenderContext.md) + +### 设备与交换链访问 + +- [Device And SwapChain Accessors](Device-And-SwapChain-Accessors.md) ## 当前实现说明 - `Initialize(hwnd, width, height)` 会创建设备与渲染目标。 -- `Render(imguiBackend, clearColor)` 会完成 back buffer 状态切换、清屏、ImGui draw data 提交、present 和 fence signal。 +- `Render(imguiBackend, clearColor)` 会完成 back buffer 状态切换、清屏、ImGui draw data 提交和 present。 - `Resize()` 会重建 back buffer RTV。 - `GetDevice()` / `GetSrvHeap()` 为 ImGui backend 提供初始化依赖。 +- `beforeUiRender` 回调允许上层先用同一份 `RenderContext` 完成 viewport 等非 ImGui 渲染。 ## 当前实现边界 -- 当前完全是编辑器宿主级 D3D12 代码，不走引擎自己的 RHI 抽象。 -- 当前资源释放与错误处理都比较直接，没有更高层的资源状态对象。 -- `SetEventOnCompletion()` 当前传的是 `nullptr` 事件句柄，这个等待路径仍然很原始。 +- 当前是编辑器宿主级窗口渲染器，但底层资源仍然通过引擎 RHI 抽象对象创建与访问。 +- 当前资源释放与错误处理都比较直接，没有更高层的窗口 renderer 状态对象。 +- 当前实现固定面向 D3D12，不是可替换的多后端窗口壳层。 ## 相关文档 - [Platform](../Platform.md) - [Application](../../Application/Application.md) - [Win32EditorHost](../Win32EditorHost/Win32EditorHost.md) +- [ImGuiBackendBridge](../../UI/ImGuiBackendBridge/ImGuiBackendBridge.md) diff --git a/docs/api/XCEngine/Editor/Platform/D3D12WindowRenderer/Device-And-SwapChain-Accessors.md b/docs/api/XCEngine/Editor/Platform/D3D12WindowRenderer/Device-And-SwapChain-Accessors.md new file mode 100644 index 00000000..7e5e7899 --- /dev/null +++ b/docs/api/XCEngine/Editor/Platform/D3D12WindowRenderer/Device-And-SwapChain-Accessors.md @@ -0,0 +1,51 @@ +# D3D12WindowRenderer Device And SwapChain Accessors + +**命名空间**: `XCEngine::Editor::Platform` + +**类型**: `method group` + +**源文件**: `editor/src/Platform/D3D12WindowRenderer.h` + +## 签名 + +```cpp +ID3D12Device* GetDevice() const; +ID3D12DescriptorHeap* GetSrvHeap() const; +ID3D12CommandQueue* GetCommandQueue() const; +UINT GetSrvDescriptorSize() const; +UINT GetSrvDescriptorCount() const; +RHI::RHIDevice* GetRHIDevice() const; +RHI::RHISwapChain* GetSwapChain() const; +``` + +## 作用 + +暴露 ImGui backend 和更高层编辑器系统初始化所需的设备、heap、队列与 swap chain 访问入口。 + +## 当前实现行为 + +- `GetDevice()` + - 返回当前底层 `ID3D12Device*` +- `GetSrvHeap()` + - 返回 ImGui 可见的 shader-visible descriptor heap +- `GetCommandQueue()` + - 返回底层 `ID3D12CommandQueue*` +- `GetSrvDescriptorSize()` + - 返回 SRV heap 单个 descriptor 的步长 +- `GetSrvDescriptorCount()` + - 固定返回 `kSrvDescriptorCount`，当前值为 `64` +- `GetRHIDevice()` + - 返回 RHI 抽象层设备对象 +- `GetSwapChain()` + - 返回 RHI 抽象层 swap chain 对象 + +## 当前使用位置 + +- `Application` 会把 `GetDevice()`、`GetCommandQueue()`、`GetSrvHeap()` 和 descriptor 参数传给 [ImGuiBackendBridge](../../UI/ImGuiBackendBridge/ImGuiBackendBridge.md) +- `ViewportHostService` 会通过 `GetRHIDevice()` 获取视口 render target 创建所需设备 + +## 相关文档 + +- [D3D12WindowRenderer](D3D12WindowRenderer.md) +- [Initialize / Shutdown](Initialize-And-Shutdown.md) +- [ImGuiBackendBridge](../../UI/ImGuiBackendBridge/ImGuiBackendBridge.md) diff --git a/docs/api/XCEngine/Editor/Platform/D3D12WindowRenderer/Initialize-And-Shutdown.md b/docs/api/XCEngine/Editor/Platform/D3D12WindowRenderer/Initialize-And-Shutdown.md new file mode 100644 index 00000000..6c2a0a00 --- /dev/null +++ b/docs/api/XCEngine/Editor/Platform/D3D12WindowRenderer/Initialize-And-Shutdown.md @@ -0,0 +1,59 @@ +# D3D12WindowRenderer::Initialize / Shutdown + +**命名空间**: `XCEngine::Editor::Platform` + +**类型**: `methods` + +**源文件**: `editor/src/Platform/D3D12WindowRenderer.h` + +## 签名 + +```cpp +bool Initialize(HWND hwnd, int width, int height); +void Shutdown(); +``` + +## 作用 + +初始化或释放编辑器主窗口使用的 D3D12 设备、交换链、命令队列、命令列表、SRV heap 和 back buffer 视图。 + +## 当前实现行为 + +### `Initialize(...)` + +- 会先调用 `Shutdown()`，确保旧状态完全释放。 +- 当前只有在以下条件满足时才继续： + - `hwnd` 非空 + - `width > 0` + - `height > 0` +- 然后依次创建并校验： + - `RHIDevice`，类型固定为 `D3D12` + - `Direct` command queue + - `Direct` command list + - swap chain，buffer count 固定为 `3` + - shader-visible SRV descriptor pool，descriptor count 固定为 `64` +- `commandList` 初始化后会先 `Close()` 一次。 +- 成功创建 SRV heap 后，会调用 `RecreateBackBufferViews()` 为所有 swap chain back buffer 创建 RTV。 +- 任一阶段失败都会调用 `Shutdown()` 回滚，并返回 `false`。 + +### `Shutdown()` + +- 会先调用 `WaitForGpuIdle()`，再释放 back buffer views。 +- 然后按顺序释放： + - `m_srvPool` + - `m_swapChain` + - `m_commandList` + - `m_commandQueue` + - `m_device` +- 最后清空窗口句柄、尺寸和 SRV descriptor size。 + +## 当前实现边界 + +- 当前对象自己持有 RHI 抽象层对象，而不是直接持有裸 `ID3D12CommandAllocator` 或 `IDXGISwapChain3` 成员。 +- 它是编辑器宿主窗口级渲染器，不是引擎通用 renderer。 + +## 相关文档 + +- [D3D12WindowRenderer](D3D12WindowRenderer.md) +- [Resize / BeginFrame](Resize-And-BeginFrame.md) +- [Render And RenderContext](Render-And-RenderContext.md) diff --git a/docs/api/XCEngine/Editor/Platform/D3D12WindowRenderer/Render-And-RenderContext.md b/docs/api/XCEngine/Editor/Platform/D3D12WindowRenderer/Render-And-RenderContext.md new file mode 100644 index 00000000..c082f1a9 --- /dev/null +++ b/docs/api/XCEngine/Editor/Platform/D3D12WindowRenderer/Render-And-RenderContext.md @@ -0,0 +1,65 @@ +# D3D12WindowRenderer::Render / GetRenderContext + +**命名空间**: `XCEngine::Editor::Platform` + +**类型**: `method group` + +**源文件**: `editor/src/Platform/D3D12WindowRenderer.h` + +## 签名 + +```cpp +void Render( + UI::ImGuiBackendBridge& imguiBackend, + const float clearColor[4], + const std::function& beforeUiRender = {}); + +Rendering::RenderContext GetRenderContext() const; +``` + +## 作用 + +把一帧编辑器 UI 提交到交换链 back buffer，并为上层提供当前窗口渲染上下文。 + +## 当前实现行为 + +### `Render(...)` + +- 只有在 swap chain、command queue、command list 和 SRV heap 都有效时才继续。 +- 若传入了 `beforeUiRender`，会先以 `GetRenderContext()` 结果调用它。 +- 然后根据当前 back buffer index： + - 取出对应 `RHIResourceView` + - 从 `Present` 过渡到 `RenderTarget` + - 绑定 render target + - 清屏 +- 随后把 ImGui 使用的 SRV heap 绑定到命令列表，并调用: + +```cpp +imguiBackend.RenderDrawData(d3d12CommandList->GetCommandList()); +``` + +- 最后： + - back buffer 从 `RenderTarget` 过渡回 `Present` + - `m_commandList->Close()` + - `m_commandQueue->ExecuteCommandLists(...)` + - `m_swapChain->Present(1, 0)` + +### `GetRenderContext()` + +- 当前返回一个轻量 `Rendering::RenderContext` +- 其中会填入： + - `device` + - `commandList` + - `commandQueue` + - `backendType = D3D12` + +## 设计含义 + +- `beforeUiRender` 是当前窗口 renderer 与更高层 Scene / Viewport 渲染逻辑的接缝点。 +- 它让 `Application` 能在真正提交 ImGui 之前，把 Scene / Game 视口内容先画进各自 render target。 + +## 相关文档 + +- [D3D12WindowRenderer](D3D12WindowRenderer.md) +- [Resize / BeginFrame](Resize-And-BeginFrame.md) +- [ImGuiBackendBridge](../../UI/ImGuiBackendBridge/ImGuiBackendBridge.md) diff --git a/docs/api/XCEngine/Editor/Platform/D3D12WindowRenderer/Resize-And-BeginFrame.md b/docs/api/XCEngine/Editor/Platform/D3D12WindowRenderer/Resize-And-BeginFrame.md new file mode 100644 index 00000000..5183a18c --- /dev/null +++ b/docs/api/XCEngine/Editor/Platform/D3D12WindowRenderer/Resize-And-BeginFrame.md @@ -0,0 +1,52 @@ +# D3D12WindowRenderer::Resize / BeginFrame + +**命名空间**: `XCEngine::Editor::Platform` + +**类型**: `methods` + +**源文件**: `editor/src/Platform/D3D12WindowRenderer.h` + +## 签名 + +```cpp +void Resize(int width, int height); +bool BeginFrame(); +``` + +## 作用 + +处理窗口尺寸变化下的 back buffer 重建，并准备一帧新的 UI 渲染提交。 + +## 当前实现行为 + +### `Resize(width, height)` + +- 当宽高非法或当前没有 swap chain 时直接返回。 +- 否则会： + - `WaitForGpuIdle()` + - `ReleaseBackBufferViews()` + - `m_swapChain->Resize(...)` + - 更新缓存尺寸 + - `RecreateBackBufferViews()` + +### `BeginFrame()` + +- 会确认以下对象均有效： + - swap chain + - D3D12 command queue + - D3D12 command list + - SRV heap +- 当前实现会先调用 `d3d12Queue->WaitForPreviousFrame()`。 +- 之后执行 `m_commandList->Reset()`，为本帧记录命令做准备。 +- 成功时返回 `true`。 + +## 设计含义 + +- `BeginFrame()` 当前承担了“上一帧 retire 完成后再允许 CPU 侧资源重建”的保护作用。 +- 这对 viewport panel 在 ImGui 构建期间可能重建 render target 的场景尤其重要。 + +## 相关文档 + +- [D3D12WindowRenderer](D3D12WindowRenderer.md) +- [Initialize / Shutdown](Initialize-And-Shutdown.md) +- [Render And RenderContext](Render-And-RenderContext.md) diff --git a/docs/api/XCEngine/Editor/Platform/D3D12WindowRendererImGuiInterop/D3D12WindowRendererImGuiInterop.md b/docs/api/XCEngine/Editor/Platform/D3D12WindowRendererImGuiInterop/D3D12WindowRendererImGuiInterop.md new file mode 100644 index 00000000..2a29fe04 --- /dev/null +++ b/docs/api/XCEngine/Editor/Platform/D3D12WindowRendererImGuiInterop/D3D12WindowRendererImGuiInterop.md @@ -0,0 +1,50 @@ +# D3D12WindowRendererImGuiInterop + +**命名空间**: `XCEngine::Editor::Platform` + +**类型**: `inline helper` + +**源文件**: `editor/src/Platform/D3D12WindowRendererImGuiInterop.h` + +**描述**: 把 `D3D12WindowRenderer`、`ImGuiBackendBridge` 与可选的前后置渲染回调收束到同一条 present helper 里的平台层桥接函数。 + +## 公开入口 + +| 声明 | 说明 | +|------|------| +| `RenderImGuiFrame(windowRenderer, imguiBackend, clearColor, beforeUiRender, afterUiRender)` | 用 swapchain backbuffer 清屏、执行可选 3D/overlay 回调、提交 ImGui draw data，并完成 present。 | + +## 当前行为 + +- 这条 helper 会先检查： + - `RenderContext` 是否有效 + - command list / queue 是否存在 + - swapchain、当前 render surface、SRV heap 是否存在 + - 当前 color attachment 是否存在 +- 前置条件不满足时直接返回，不抛异常。 +- 真正执行时的顺序是： + 1. backbuffer 从 `Present` 切到 `RenderTarget` + 2. 绑定 render target 并清屏 + 3. 调用 `beforeUiRender`，让上层先用同一条 command list 渲染 viewport 等内容 + 4. 重新绑定 swapchain backbuffer + 5. 绑定 SRV heap 并调用 `imguiBackend.RenderDrawData(...)` + 6. 可选调用 `afterUiRender` + 7. backbuffer 切回 `Present` + 8. `Close -> ExecuteCommandLists -> Present` + +## 当前调用链 + +- `editor/src/Application.cpp` 当前直接通过这条 helper 驱动主窗口一帧的最终提交。 +- `beforeUiRender` 回调当前承接 `ViewportHostService.RenderRequestedViewports(...)` 一类非 ImGui 渲染。 +- `tests/Editor/test_window_renderer_api.cpp` 当前至少静态验证了这条 helper 的签名和 `GetCurrentRenderSurface()` 访问器契约。 + +## 当前边界 + +- 这是 Windows / D3D12 / ImGui 绑定很紧的 inline helper，不是通用 render loop 抽象。 +- `beforeUiRender` 被假定会把 swapchain color attachment 保持在 `RenderTarget` 状态；helper 只负责在之后重新绑定 backbuffer，不会替调用方补状态修复。 + +## 相关文档 + +- [Platform](../Platform.md) +- [D3D12WindowRenderer](../D3D12WindowRenderer/D3D12WindowRenderer.md) +- [ImGuiBackendBridge](../../UI/ImGuiBackendBridge/ImGuiBackendBridge.md) diff --git a/docs/api/XCEngine/Editor/Platform/Platform.md b/docs/api/XCEngine/Editor/Platform/Platform.md index 44c725f0..54b0f924 100644 --- a/docs/api/XCEngine/Editor/Platform/Platform.md +++ b/docs/api/XCEngine/Editor/Platform/Platform.md @@ -17,6 +17,7 @@ - [Win32EditorHost](Win32EditorHost/Win32EditorHost.md) - [D3D12WindowRenderer](D3D12WindowRenderer/D3D12WindowRenderer.md) +- [D3D12WindowRendererImGuiInterop](D3D12WindowRendererImGuiInterop/D3D12WindowRendererImGuiInterop.md) - [Win32Utf8](Win32Utf8/Win32Utf8.md) - [WindowsProcessDiagnostics](WindowsProcessDiagnostics/WindowsProcessDiagnostics.md) diff --git a/docs/api/XCEngine/Editor/Platform/Win32EditorHost/EditorWndProc.md b/docs/api/XCEngine/Editor/Platform/Win32EditorHost/EditorWndProc.md new file mode 100644 index 00000000..936e0285 --- /dev/null +++ b/docs/api/XCEngine/Editor/Platform/Win32EditorHost/EditorWndProc.md @@ -0,0 +1,54 @@ +# EditorWndProc + +**命名空间**: `XCEngine::Editor::Platform` + +**类型**: `function` + +**源文件**: `editor/src/Platform/Win32EditorHost.h` + +## 签名 + +```cpp +LRESULT WINAPI EditorWndProc(HWND hWnd, UINT msg, WPARAM wParam, LPARAM lParam); +``` + +## 作用 + +作为编辑器主窗口的 Win32 窗口过程，把平台消息桥接到 ImGui backend 和 `Application`。 + +## 当前实现行为 + +- 会先调用: + +```cpp +UI::ImGuiBackendBridge::HandleWindowMessage(hWnd, msg, wParam, lParam) +``` + +- 如果 ImGui backend 已消费该消息，当前直接返回 `true`。 + +### 已处理的关键消息 + +- `WM_SIZE` + - 当窗口未最小化时，调用 `Application::OnResize(width, height)` + - 若当前 render 已就绪，会立即再调用一次 `Application::Render()` +- `WM_PAINT` + - 当 render 已就绪时，执行 `BeginPaint -> Application::Render -> EndPaint` +- `WM_ERASEBKGND` + - 返回 `1`，避免默认背景擦除闪烁 +- `WM_SYSCOMMAND` + - 对 `SC_KEYMENU` 返回 `0`，屏蔽 Alt 菜单激活 +- `WM_DESTROY` + - 调用 `PostQuitMessage(0)` + +- 其余消息会回退到 `DefWindowProcW(...)` + +## 设计含义 + +- 当前宿主窗口过程本身很薄，只负责把平台事件尽快转发到 ImGui 和 `Application`。 +- 编辑器业务逻辑并不直接塞进 Win32 `WndProc`。 + +## 相关文档 + +- [Win32EditorHost](Win32EditorHost.md) +- [RunEditor](RunEditor.md) +- [ImGuiBackendBridge](../../UI/ImGuiBackendBridge/ImGuiBackendBridge.md) diff --git a/docs/api/XCEngine/Editor/Platform/Win32EditorHost/RunEditor.md b/docs/api/XCEngine/Editor/Platform/Win32EditorHost/RunEditor.md new file mode 100644 index 00000000..c8807741 --- /dev/null +++ b/docs/api/XCEngine/Editor/Platform/Win32EditorHost/RunEditor.md @@ -0,0 +1,60 @@ +# RunEditor + +**命名空间**: `XCEngine::Editor::Platform` + +**类型**: `function` + +**源文件**: `editor/src/Platform/Win32EditorHost.h` + +## 签名 + +```cpp +int RunEditor(HINSTANCE hInstance, int nCmdShow); +``` + +## 作用 + +启动当前 Win32 编辑器宿主，完成窗口类注册、窗口创建、`Application` 初始化和消息循环驱动。 + +## 当前实现行为 + +### 启动阶段 + +- 先调用 `ImGuiBackendBridge::EnableDpiAwareness()` +- 注册窗口类 `WNDCLASSEXW` +- 当前窗口类名固定为 `XCVolumeRendererUI2` +- 之后创建标题为 `XCEngine Editor` 的主窗口 +- 若图标资源存在，还会分别设置大图标和小图标 +- 然后执行: + - `ShowWindow(hwnd, nCmdShow)` + - `UpdateWindow(hwnd)` + +### Application 初始化 + +- 调用 `Application::Get().Initialize(hwnd)` +- 初始化失败时，会销毁窗口并注销窗口类，然后返回 `1` + +### 主消息循环 + +- 循环直到收到 `WM_QUIT` +- 若 `PeekMessageW(...)` 取到了消息，则走正常的: + - `TranslateMessage` + - `DispatchMessageW` +- 若消息队列为空，则主动调用 `Application::Get().Render()` + +### 退出阶段 + +- 循环结束后调用 `Application::Get().Shutdown()` +- 注销窗口类 +- 最终返回 `msg.wParam` + +## 设计含义 + +- 当前是典型的“消息驱动 + idle render” Win32 editor host。 +- `RunEditor()` 本身不承载 editor 业务状态，它只是宿主启动和主循环壳层。 + +## 相关文档 + +- [Win32EditorHost](Win32EditorHost.md) +- [EditorWndProc](EditorWndProc.md) +- [Application](../../Application/Application.md) diff --git a/docs/api/XCEngine/Editor/Platform/Win32EditorHost/Win32EditorHost.md b/docs/api/XCEngine/Editor/Platform/Win32EditorHost/Win32EditorHost.md index e341ad24..55e9e97b 100644 --- a/docs/api/XCEngine/Editor/Platform/Win32EditorHost/Win32EditorHost.md +++ b/docs/api/XCEngine/Editor/Platform/Win32EditorHost/Win32EditorHost.md @@ -12,15 +12,15 @@ `Win32EditorHost.h` 当前不是传统意义上的 class，而是一组 inline 平台宿主入口： -- `EditorWndProc` -- `RunEditor(HINSTANCE, int)` +- [EditorWndProc](EditorWndProc.md) +- [RunEditor(HINSTANCE, int)](RunEditor.md) ## 当前实现说明 -- `EditorWndProc` 会先把消息交给 `ImGuiBackendBridge::HandleWindowMessage()`。 +- [EditorWndProc](EditorWndProc.md) 会先把消息交给 `ImGuiBackendBridge::HandleWindowMessage()`。 - `WM_SIZE` 会转发到 `Application::OnResize()`。 - `WM_DESTROY` 会发出 `PostQuitMessage(0)`。 -- `RunEditor()` 负责注册窗口类、创建窗口、调用 `Application::Initialize()`，并在消息循环空闲时执行 `Application::Render()`。 +- [RunEditor](RunEditor.md) 负责注册窗口类、创建窗口、调用 `Application::Initialize()`，并在消息循环空闲时执行 `Application::Render()`。 ## 当前实现边界 diff --git a/docs/api/XCEngine/Editor/Scripting/EditorScriptAssemblyBuilder/EditorScriptAssemblyBuilder.md b/docs/api/XCEngine/Editor/Scripting/EditorScriptAssemblyBuilder/EditorScriptAssemblyBuilder.md index 96f96122..fc4e410f 100644 --- a/docs/api/XCEngine/Editor/Scripting/EditorScriptAssemblyBuilder/EditorScriptAssemblyBuilder.md +++ b/docs/api/XCEngine/Editor/Scripting/EditorScriptAssemblyBuilder/EditorScriptAssemblyBuilder.md @@ -53,7 +53,7 @@ ## 真实使用位置 - `Application.cpp` 会在重建脚本程序集时调用它。 -- `tests/editor/test_editor_script_assembly_builder.cpp` 当前覆盖了两类关键语义： +- `tests/Editor/test_editor_script_assembly_builder.cpp` 当前覆盖了两类关键语义： - 成功路径：`XCEngine.ScriptCore.dll`、`GameScripts.dll` 与项目本地 `mscorlib.dll` 都会落到 `Library/ScriptAssemblies` - 锁语义：如果活动 Mono runtime 仍持有已加载的 `GameScripts.dll`，直接重建会失败；释放 runtime 后再重建则可以成功并看到新增脚本类型 diff --git a/docs/api/XCEngine/Editor/Scripting/EditorScriptAssemblyBuilderUtils/EditorScriptAssemblyBuilderUtils.md b/docs/api/XCEngine/Editor/Scripting/EditorScriptAssemblyBuilderUtils/EditorScriptAssemblyBuilderUtils.md index 60e38017..01627240 100644 --- a/docs/api/XCEngine/Editor/Scripting/EditorScriptAssemblyBuilderUtils/EditorScriptAssemblyBuilderUtils.md +++ b/docs/api/XCEngine/Editor/Scripting/EditorScriptAssemblyBuilderUtils/EditorScriptAssemblyBuilderUtils.md @@ -30,7 +30,7 @@ ## 测试覆盖 -`tests/editor/test_editor_script_assembly_builder_utils.cpp` 当前已覆盖： +`tests/Editor/test_editor_script_assembly_builder_utils.cpp` 当前已覆盖： - `.cs` 文件递归收集与排序 - SDK 版本解析 diff --git a/docs/api/XCEngine/Editor/UI/AboutEditorDialog/AboutEditorDialog.md b/docs/api/XCEngine/Editor/UI/AboutEditorDialog/AboutEditorDialog.md index 955135ff..ff573e42 100644 --- a/docs/api/XCEngine/Editor/UI/AboutEditorDialog/AboutEditorDialog.md +++ b/docs/api/XCEngine/Editor/UI/AboutEditorDialog/AboutEditorDialog.md @@ -11,7 +11,7 @@ ## 概述 `DrawEditorAboutDialog` 是一个很轻量的 UI helper，用来响应主菜单 Help -> About 的弹窗请求。 -它依赖 [`DeferredPopupState`](../PopupState/PopupState.md) 控制打开时机，并在弹窗中显示： +它依赖 [`DeferredPopupState`](../PopupState/DeferredPopupState.md) 控制打开时机，并在弹窗中显示： - 编辑器名称 - 简短说明文字 diff --git a/docs/api/XCEngine/Editor/UI/BuiltInIconLayoutUtils/BuiltInIconLayoutUtils.md b/docs/api/XCEngine/Editor/UI/BuiltInIconLayoutUtils/BuiltInIconLayoutUtils.md new file mode 100644 index 00000000..fb729a2a --- /dev/null +++ b/docs/api/XCEngine/Editor/UI/BuiltInIconLayoutUtils/BuiltInIconLayoutUtils.md @@ -0,0 +1,41 @@ +# BuiltInIconLayoutUtils + +**命名空间**: `XCEngine::Editor::UI` + +**类型**: `utility-header` + +**源文件**: `editor/src/UI/BuiltInIconLayoutUtils.h` + +**描述**: 提供内置图标纹理在给定矩形内按比例缩放的布局辅助。 + +## 概述 + +`BuiltInIconLayoutUtils.h` 当前只有一个函数，但它正好承担了 `BuiltInIcons` 绘制里的核心布局职责：在可用区域内按原始宽高比缩放图标。 + +## 当前公开函数 + +- `ComputeFittedIconSize(...)` + +## 当前语义 + +输入： + +- 原始纹理宽高 +- 目标矩形 `min` +- 目标矩形 `max` + +输出： + +- 一个保持宽高比、并完全落在目标矩形内的 `ImVec2` + +如果输入尺寸无效或可用区域为零，则返回 `(0, 0)`。 + +## 测试与使用位置 + +- `BuiltInIcons.cpp` 当前会用它决定图标实际绘制尺寸。 +- `tests/Editor/test_builtin_icon_layout_utils.cpp` 当前覆盖了非法尺寸和宽高比保持行为。 + +## 相关文档 + +- [当前模块](../UI.md) +- [BuiltInIcons](../BuiltInIcons/BuiltInIcons.md) diff --git a/docs/api/XCEngine/Editor/UI/BuiltInIcons/AssetIconKind.md b/docs/api/XCEngine/Editor/UI/BuiltInIcons/AssetIconKind.md new file mode 100644 index 00000000..c5cfa85b --- /dev/null +++ b/docs/api/XCEngine/Editor/UI/BuiltInIcons/AssetIconKind.md @@ -0,0 +1,42 @@ +# AssetIconKind + +**命名空间**: `XCEngine::Editor::UI` + +**类型**: `enum class` + +**源文件**: `editor/src/UI/BuiltInIcons.h` + +## 定义 + +```cpp +enum class AssetIconKind { + Folder, + File, + GameObject, + Scene +}; +``` + +## 作用 + +定义当前编辑器内置图标系统可识别的资源/对象类别。 + +## 枚举值 + +| 值 | 说明 | +|------|------| +| `Folder` | 目录或资源树文件夹节点。 | +| `File` | 普通文件资源。 | +| `GameObject` | 场景层级中的 `GameObject`。 | +| `Scene` | 场景资源文件。 | + +## 当前实现行为 + +- [DrawAssetIcon](DrawAssetIcon.md) 会根据该枚举选择贴图或程序化 fallback。 +- 当前只有 `Folder`、`GameObject`、`Scene` 三类尝试加载 PNG。 +- `File` 当前始终使用程序化 file-style fallback。 + +## 相关文档 + +- [BuiltInIcons](BuiltInIcons.md) +- [DrawAssetIcon](DrawAssetIcon.md) diff --git a/docs/api/XCEngine/Editor/UI/BuiltInIcons/BuiltInIcons.md b/docs/api/XCEngine/Editor/UI/BuiltInIcons/BuiltInIcons.md index f760d29b..efa9f79e 100644 --- a/docs/api/XCEngine/Editor/UI/BuiltInIcons/BuiltInIcons.md +++ b/docs/api/XCEngine/Editor/UI/BuiltInIcons/BuiltInIcons.md @@ -6,7 +6,7 @@ **源文件**: `editor/src/UI/BuiltInIcons.h` -**描述**: 为编辑器的资源树、资源网格和层级树提供内置图标枚举、初始化入口与统一绘制函数。 +**描述**: 为编辑器的资源树、资源网格和层级树提供内置图标枚举、初始化入口、统一图标绘制，以及轻量纹理预览缓存。 ## 概述 @@ -18,16 +18,28 @@ - `ProjectPanel` 通过 `Folder` / `File` 图标绘制左侧目录树和右侧资源卡片。 - `ProjectActionRouter` 在拖拽预览等交互里复用同一套图标语义。 +同时它现在还承担了一个额外职责： + +- 为资源卡片提供异步缩略图预览入口 `DrawTextureAssetPreview(...)` + 这和商业级编辑器常见的做法一致：业务面板不直接持有纹理资源，不自己决定某一类对象该显示什么图标，而是把“对象类别 -> 图标表现”的决定集中到一层共享 helper 中。这样做的好处是统一、可替换，而且不会让每个面板都自己重复写上传纹理、绘制 fallback 图形、适配尺寸的逻辑。 ## 公开 API | 成员 | 说明 | |------|------| -| `enum class AssetIconKind { Folder, File, GameObject }` | 定义当前编辑器可识别的内置图标类别。 | -| `InitializeBuiltInIcons(ImGuiBackendBridge&, ID3D12Device*, ID3D12CommandQueue*)` | 初始化图标系统，上传贴图并分配 ImGui 可见的 SRV 描述符。 | -| `ShutdownBuiltInIcons()` | 释放内置图标占用的 GPU 资源与描述符。 | -| `DrawAssetIcon(ImDrawList*, const ImVec2& min, const ImVec2& max, AssetIconKind)` | 在给定矩形内绘制指定类别的图标。 | +| [AssetIconKind](AssetIconKind.md) | 定义当前编辑器可识别的内置图标类别。 | +| [InitializeBuiltInIcons](InitializeBuiltInIcons.md) | 初始化图标系统，上传内置图标并启动预览工作线程。 | +| [ShutdownBuiltInIcons](ShutdownBuiltInIcons.md) | 释放内置图标与预览缓存占用的 GPU / 后台资源。 | +| [DrawAssetIcon](DrawAssetIcon.md) | 在给定矩形内绘制指定类别的内置图标。 | +| [DrawTextureAssetPreview](DrawTextureAssetPreview.md) | 读取或异步准备资源缩略图，并在可用时直接绘制。 | + +## 生命周期与公开入口 + +- [InitializeBuiltInIcons](InitializeBuiltInIcons.md) +- [ShutdownBuiltInIcons](ShutdownBuiltInIcons.md) +- [DrawAssetIcon](DrawAssetIcon.md) +- [DrawTextureAssetPreview](DrawTextureAssetPreview.md) ## 生命周期 @@ -40,11 +52,19 @@ 按 `editor/src/UI/BuiltInIcons.cpp` 的实现，当前版本有几个值得明确写进文档的事实： -- 只有 `Folder` 和 `GameObject` 两类图标会尝试从磁盘加载 PNG。 -- 图标路径不是从项目目录查找，而是从可执行文件目录推导到 `../../resources/Icons/folder_icon.png` 与 `../../resources/Icons/gameobject_icon.png`。 -- 贴图上传路径目前只支持 D3D12，上传时会创建默认堆纹理、上传堆 buffer、一次性命令列表，并在结束后主动等待命令队列空闲。 +- `Folder`、`GameObject` 和 `Scene` 三类图标都会尝试从磁盘加载 PNG。 +- 图标路径不是从项目目录查找，而是从可执行文件目录推导到： + - `../../resources/Icons/folder_icon.png` + - `../../resources/Icons/gameobject_icon.png` + - `../../resources/Icons/scene_icon.png` +- 图标上传路径目前只支持 D3D12，上传时会创建默认堆纹理、上传堆 buffer 和一次性命令列表；提交后通过 fence 跟踪完成状态，并把挂起 upload 保存在 `pendingIconUploads` 中。 - `File` 图标当前不是贴图资源，而是运行时用 `ImDrawList` 直接画出的简化文件形状。 -- 如果 `Folder` / `GameObject` 的 PNG 加载失败，系统不会抛出错误或写日志；它会静默退回到程序化绘制的 fallback 图标。 +- 如果 `Folder` / `GameObject` / `Scene` 的 PNG 加载失败，系统不会抛出错误或写日志；它会静默退回到程序化绘制的 fallback 图标。 +- `DrawTextureAssetPreview(...)` 当前带有： + - 进程内预览缓存 + - 后台解码 worker + - `.xceditor/thumbs/*.thumb` 磁盘缩略图缓存 + - 每帧预览加载预算与缓存裁剪 这意味着它更接近“编辑器内部视觉资源辅助层”，而不是一个对外稳定暴露的通用图标资源系统。 @@ -67,7 +87,7 @@ ## 线程语义 - 这套 API 应被视为仅限编辑器 UI / 渲染线程使用。 -- 初始化和销毁会触发 GPU 资源分配、命令提交与队列等待，不适合在任意后台线程上调用。 +- 初始化会触发 GPU 资源分配与命令提交；销毁阶段在后端对象齐全时还会显式等待队列空闲，因此都不适合在任意后台线程上调用。 - `DrawAssetIcon(...)` 依赖当前帧的 `ImDrawList` 和 ImGui 绘制上下文，也只能在 ImGui 绘制阶段调用。 ## 典型用法 @@ -94,12 +114,17 @@ UI::ShutdownBuiltInIcons(); ## 当前限制 - 当前只支持 D3D12 上传路径，没有 OpenGL / Vulkan / 软件后备实现。 -- 图标种类固定为 `Folder`、`File`、`GameObject` 三类。 +- 内置图标种类固定为 `Folder`、`File`、`GameObject`、`Scene` 四类。 - 没有热重载、主题切换或 DPI 变体资源管理。 - 加载失败时以静默 fallback 为主，没有诊断级错误反馈。 ## 相关文档 +- [AssetIconKind](AssetIconKind.md) +- [InitializeBuiltInIcons](InitializeBuiltInIcons.md) +- [ShutdownBuiltInIcons](ShutdownBuiltInIcons.md) +- [DrawAssetIcon](DrawAssetIcon.md) +- [DrawTextureAssetPreview](DrawTextureAssetPreview.md) - [UI](../UI.md) - [StyleTokens](../StyleTokens/StyleTokens.md) - [Application](../../Application/Application.md) diff --git a/docs/api/XCEngine/Editor/UI/BuiltInIcons/DrawAssetIcon.md b/docs/api/XCEngine/Editor/UI/BuiltInIcons/DrawAssetIcon.md new file mode 100644 index 00000000..0b238317 --- /dev/null +++ b/docs/api/XCEngine/Editor/UI/BuiltInIcons/DrawAssetIcon.md @@ -0,0 +1,42 @@ +# DrawAssetIcon + +**命名空间**: `XCEngine::Editor::UI` + +**类型**: `function` + +**源文件**: `editor/src/UI/BuiltInIcons.h` + +## 签名 + +```cpp +void DrawAssetIcon(ImDrawList* drawList, const ImVec2& min, const ImVec2& max, AssetIconKind kind); +``` + +## 作用 + +在指定矩形里绘制一个统一风格的编辑器内置图标。 + +## 当前实现行为 + +调用时会先 `MaintainIconRuntimeState()`，然后按 [AssetIconKind](AssetIconKind.md) 分支： + +- `Folder` + - 纹理有效时画 `folder` 贴图 + - 否则画 folder fallback +- `GameObject` + - 纹理有效时画 `gameObject` 贴图 + - 否则回退到 file-style fallback +- `Scene` + - 纹理有效时画 `scene` 贴图 + - 否则回退到 file-style fallback +- 其余情况 + - 画 file fallback + +因此 `File` 当前没有独立 PNG，而是直接走程序化图形。 + +## 相关文档 + +- [BuiltInIcons](BuiltInIcons.md) +- [AssetIconKind](AssetIconKind.md) +- [InitializeBuiltInIcons](InitializeBuiltInIcons.md) +- [DrawTextureAssetPreview](DrawTextureAssetPreview.md) diff --git a/docs/api/XCEngine/Editor/UI/BuiltInIcons/DrawTextureAssetPreview.md b/docs/api/XCEngine/Editor/UI/BuiltInIcons/DrawTextureAssetPreview.md new file mode 100644 index 00000000..6daacf44 --- /dev/null +++ b/docs/api/XCEngine/Editor/UI/BuiltInIcons/DrawTextureAssetPreview.md @@ -0,0 +1,64 @@ +# DrawTextureAssetPreview + +**命名空间**: `XCEngine::Editor::UI` + +**类型**: `function` + +**源文件**: `editor/src/UI/BuiltInIcons.h` + +## 签名 + +```cpp +bool DrawTextureAssetPreview( + ImDrawList* drawList, + const ImVec2& min, + const ImVec2& max, + const std::string& filePath, + const std::string& projectPath = {}); +``` + +## 作用 + +在纹理预览已经可用时直接绘制资源缩略图；若当前帧还没有可用贴图，则返回 `false` 让调用方自行回退到普通图标。 + +## 当前实现行为 + +当前函数会先调用： + +```cpp +GetOrCreateAssetPreview(filePath, projectPath) +``` + +随后按下面条件判断是否真正可画： + +- preview 不存在: 返回 `false` +- `preview->texture` 还没准备好: 返回 `false` +- `preview->hasStaleTexture == true`: 返回 `false` +- 否则直接 `DrawTextureIcon(...)` + +绘制成功后还会执行一次 `PruneAssetPreviewCache()`，把缓存维持在预算范围内。 + +## 当前预览管线 + +这个入口背后不只是一次同步文件读取。当前实际包含： + +- 路径归一化 key +- 进程内 `assetPreviews` 缓存 +- 后台解码 worker +- `.xceditor/thumbs/*.thumb` 缩略图磁盘缓存 +- 预览尺寸上限和每帧加载预算 + +所以它更接近“轻量预览系统的同步消费端”，而不是简单 `LoadTexture(filePath)`。 + +## 返回值语义 + +- `true` + - 当前帧已经拿到有效纹理，并且已完成绘制 +- `false` + - 当前帧没有可用预览，调用方应回退到 `DrawAssetIcon(...)` 或其他默认表现 + +## 相关文档 + +- [BuiltInIcons](BuiltInIcons.md) +- [DrawAssetIcon](DrawAssetIcon.md) +- [ShutdownBuiltInIcons](ShutdownBuiltInIcons.md) diff --git a/docs/api/XCEngine/Editor/UI/BuiltInIcons/InitializeBuiltInIcons.md b/docs/api/XCEngine/Editor/UI/BuiltInIcons/InitializeBuiltInIcons.md new file mode 100644 index 00000000..1c370ece --- /dev/null +++ b/docs/api/XCEngine/Editor/UI/BuiltInIcons/InitializeBuiltInIcons.md @@ -0,0 +1,47 @@ +# InitializeBuiltInIcons + +**命名空间**: `XCEngine::Editor::UI` + +**类型**: `function` + +**源文件**: `editor/src/UI/BuiltInIcons.h` + +## 签名 + +```cpp +void InitializeBuiltInIcons( + ImGuiBackendBridge& backend, + ID3D12Device* device, + ID3D12CommandQueue* commandQueue); +``` + +## 作用 + +初始化内置图标系统，记录后端对象，启动预览 worker，并按需加载 `Folder / GameObject / Scene` 三类内置 PNG。 + +## 当前实现行为 + +当前函数会按下面顺序执行： + +1. 先调用 `ShutdownBuiltInIcons()` +2. 保存 `backend / device / commandQueue` +3. 启动预览解码 worker 线程 +4. 尝试加载： + - `folder_icon.png` + - `gameobject_icon.png` + - `scene_icon.png` +5. 对每个成功加载的图标，把待提交的 GPU upload 放进 `pendingIconUploads` + +这些 upload 在函数返回时不保证已经执行完毕。当前实现只是把上传命令提交到队列，并用 fence 跟踪完成状态；后续帧会通过运行时维护流程回收已完成的挂起 upload。 + +## 当前语义 + +- 这是一个“重初始化”入口，不是假设只能调用一次 +- 初始化失败不会抛异常；单个图标加载失败时，后续绘制会自动回退到程序化 fallback +- 内置 PNG 的 GPU 上传是异步完成的；真正的队列空闲等待发生在 `ShutdownBuiltInIcons()` 阶段，而不是每次初始化上传时 + +## 相关文档 + +- [BuiltInIcons](BuiltInIcons.md) +- [ShutdownBuiltInIcons](ShutdownBuiltInIcons.md) +- [DrawAssetIcon](DrawAssetIcon.md) diff --git a/docs/api/XCEngine/Editor/UI/BuiltInIcons/ShutdownBuiltInIcons.md b/docs/api/XCEngine/Editor/UI/BuiltInIcons/ShutdownBuiltInIcons.md new file mode 100644 index 00000000..0866fa84 --- /dev/null +++ b/docs/api/XCEngine/Editor/UI/BuiltInIcons/ShutdownBuiltInIcons.md @@ -0,0 +1,39 @@ +# ShutdownBuiltInIcons + +**命名空间**: `XCEngine::Editor::UI` + +**类型**: `function` + +**源文件**: `editor/src/UI/BuiltInIcons.h` + +## 签名 + +```cpp +void ShutdownBuiltInIcons(); +``` + +## 作用 + +停止预览后台工作、清空预览缓存，并释放内置图标相关的 GPU 资源状态。 + +## 当前实现行为 + +当前会： + +1. 若后端对象齐全，先 `WaitForQueueIdle(...)` +2. 停止预览 worker +3. 清空 asset preview cache +4. 清空 `pendingIconUploads` +5. 重置 `folder / gameObject / scene` 三张内置纹理 +6. 清空 `backend / device / commandQueue` +7. 重置维护预算和帧计数状态 + +## 设计含义 + +这个 API 管的不只是三张内置图标，还包括整套资源预览运行时状态。因此它更像 `BuiltInIcons` 子系统的统一 shutdown，而不是单纯释放几张纹理。 + +## 相关文档 + +- [BuiltInIcons](BuiltInIcons.md) +- [InitializeBuiltInIcons](InitializeBuiltInIcons.md) +- [DrawTextureAssetPreview](DrawTextureAssetPreview.md) diff --git a/docs/api/XCEngine/Editor/UI/ColorPicker/ColorPicker.md b/docs/api/XCEngine/Editor/UI/ColorPicker/ColorPicker.md new file mode 100644 index 00000000..c5461d23 --- /dev/null +++ b/docs/api/XCEngine/Editor/UI/ColorPicker/ColorPicker.md @@ -0,0 +1,50 @@ +# ColorPicker + +**命名空间**: `XCEngine::Editor::UI` + +**类型**: `utility-header` + +**源文件**: `editor/src/UI/ColorPicker.h` + +**描述**: 提供 Unity 风格的弹出式颜色选择控件，支持 HSV 选择、RGBA 通道编辑和十六进制输入。 + +## 概述 + +`ColorPicker.h` 当前不是一个单独 widget class，而是一整套 header-only 颜色编辑 helper。 + +对外真正暴露的主入口是： + +- `DrawUnityColor3(...)` +- `DrawUnityColor4(...)` + +## 当前交互形态 + +调用后会渲染一个颜色预览按钮。点击后弹出自定义 popup，当前包含： + +- 色相环 +- 明度/饱和度方块 +- `R/G/B/A` 通道滑条和输入框 +- 十六进制输入框 +- 颜色预览区域 + +内部状态通过 `ImGuiID -> ColorPickerState` 映射缓存，包括： + +- 当前 RGBA +- HSV 派生值 +- hex buffer +- 拖拽状态 + +## 当前使用位置 + +`ScalarControls.h` 当前把颜色字段编辑统一转发到这里，因此 Inspector 里的颜色属性最终都会走这套控件。 + +## 当前实现边界 + +- 当前是强定制的 Editor 私有 UI，不是直接包装 ImGui 原生 color picker。 +- popup 尺寸、配色和布局常量多数写死在 header 内部。 +- 内部状态缓存依赖当前 ImGui id 语义，不适合脱离即时模式上下文长期持有。 + +## 相关文档 + +- [当前模块](../UI.md) +- [ScalarControls](../ScalarControls/ScalarControls.md) diff --git a/docs/api/XCEngine/Editor/UI/ConsoleFilterState/ConsoleFilterState.md b/docs/api/XCEngine/Editor/UI/ConsoleFilterState/ConsoleFilterState.md index e0b8775f..5cf94571 100644 --- a/docs/api/XCEngine/Editor/UI/ConsoleFilterState/ConsoleFilterState.md +++ b/docs/api/XCEngine/Editor/UI/ConsoleFilterState/ConsoleFilterState.md @@ -6,33 +6,67 @@ **源文件**: `editor/src/UI/ConsoleFilterState.h` -**描述**: 保存 Console 面板的日志等级过滤开关。 +**描述**: 保存 `ConsolePanel` 的本地过滤与行为开关，包括等级过滤、折叠、进入 play 时清空以及错误暂停。 ## 概述 -`ConsoleFilterState` 是一个很小的状态对象，负责决定哪些日志等级会在 Console 面板中显示。 +`ConsoleFilterState` 是一个纯头文件、纯本地状态对象。 +它不负责保存日志，也不负责渲染 UI；它的职责只是把 Console 当前有哪些过滤和附加行为开关表达清楚，供 [ConsolePanel](../../panels/ConsolePanel/ConsolePanel.md) 直接读写。 -当前内部维护三组布尔值： +## 当前状态项 -- `m_showInfo` -- `m_showWarning` -- `m_showError` +当前实现里，它维护的不是旧文档里提到的“三档等级过滤”而已，而是六个布尔开关： + +| 状态 | 说明 | +|------|------| +| `ShowLog` | 是否显示 `Verbose / Debug / Info` 三类日志。 | +| `ShowWarning` | 是否显示 `Warning`。 | +| `ShowError` | 是否显示 `Error / Fatal`。 | +| `Collapse` | 是否把重复日志按 key 折叠聚合。 | +| `ClearOnPlay` | 进入 play mode 时是否立刻清空控制台。 | +| `ErrorPause` | play mode 下遇到新增错误时是否请求暂停。 | + +## 公开访问模式 + +这些访问器大多返回 `bool&`，例如： + +- `ShowLog()` +- `ShowWarning()` +- `ShowError()` +- `Collapse()` +- `ClearOnPlay()` +- `ErrorPause()` + +这样 `ConsolePanel` 工具栏就可以直接把按钮状态绑定到这些引用上，而不需要再写一层 setter。 ## 当前实现 -- `ShowInfo()` / `ShowWarning()` / `ShowError()` 返回可写引用，便于直接绑定工具栏切换按钮 +- `ShowInfo()` 当前只是 `ShowLog()` 的别名 +- `ShowInfo() const` 当前只是 `ShowLog() const` 的别名 - `Allows()` 的等级映射如下： - - `Verbose` / `Debug` / `Info` 归到 Info + - `Verbose` / `Debug` / `Info` 归到 Log - `Warning` 归到 Warning - `Error` / `Fatal` 归到 Error -## 设计说明 +## 别名兼容语义 -这种“三档过滤”很像商业编辑器控制台的第一层筛选：先把低成本的等级过滤做好，再考虑更重的搜索、分类和标签系统。 -对于当前阶段的编辑器，这已经能显著提升日志可读性。 +`ShowInfo()` 仍然存在，说明这份状态对象经历过“Info 命名”到“Log 命名”的收口。 +按当前实现，它不再代表独立第四档，而只是对 `ShowLog()` 的兼容别名。 + +## 在当前 Console 流程里的角色 + +- `ConsolePanel::Render()` 用它决定日志列表是否显示某条记录。 +- `Collapse` 影响控制台是逐条显示还是按 key 聚合。 +- `ClearOnPlay` 和 `ErrorPause` 会参与 play mode 事件处理，而不是单纯 UI 装饰项。 + +## 当前实现边界 + +- 状态只保存在 `ConsolePanel` 实例内，不会跨窗口共享。 +- 当前没有项目级持久化，不会自动写回用户配置。 +- `Allows()` 只处理等级过滤，不处理文本搜索、source dropdown 或 category 过滤。 ## 相关文档 - [UI](../UI.md) -- [ConsoleActionRouter](../../Actions/ConsoleActionRouter/ConsoleActionRouter.md) - [ConsolePanel](../../panels/ConsolePanel/ConsolePanel.md) +- [EditorConsoleSink](../../Core/EditorConsoleSink/EditorConsoleSink.md) diff --git a/docs/api/XCEngine/Editor/UI/ContextMenu/ContextMenu.md b/docs/api/XCEngine/Editor/UI/ContextMenu/ContextMenu.md new file mode 100644 index 00000000..5c2789cc --- /dev/null +++ b/docs/api/XCEngine/Editor/UI/ContextMenu/ContextMenu.md @@ -0,0 +1,49 @@ +# ContextMenu + +**命名空间**: `XCEngine::Editor::UI` + +**类型**: `utility-header` + +**源文件**: `editor/src/UI/ContextMenu.h` + +**描述**: 为 Editor 统一封装上下文菜单 popup 的样式压栈、开启/结束入口和子菜单绘制辅助。 + +## 概述 + +`ContextMenu.h` 把 Dear ImGui 原始 popup API 收束成了 Editor 统一风格的上下文菜单入口。 + +## 当前公开入口 + +- `BeginContextMenu(...)` +- `BeginContextMenuForLastItem(...)` +- `BeginContextMenuForWindow(...)` +- `EndContextMenu()` +- `DrawContextSubmenu(...)` + +## 当前行为 + +- 进入菜单前会统一压入 popup chrome 和 context menu layout style。 +- 结束菜单时会对应弹出这些样式。 +- `DrawContextSubmenu(...)` 会在打开子菜单时再压入 popup content chrome。 + +当前还有一条很具体的产品行为： + +- 当子菜单 label 为 `Create` 时，会通过 `Debug::Logger` 追踪其打开/关闭状态。 + +## 当前使用位置 + +- `HierarchyActionRouter.h` +- `ProjectPanel.cpp` +- `ConsolePanel.cpp` +- `InspectorPanel.cpp` + +## 当前实现边界 + +- 这里统一的是 Editor 菜单风格，不是通用 menu framework。 +- 依赖当前 `StyleTokens` 和 `Core.h` 里定义的 popup chrome helper。 + +## 相关文档 + +- [当前模块](../UI.md) +- [MenuCommand](../MenuCommand/MenuCommand.md) +- [Widgets](../Widgets/Widgets.md) diff --git a/docs/api/XCEngine/Editor/UI/ImGuiBackendBridge/Frame-Rendering.md b/docs/api/XCEngine/Editor/UI/ImGuiBackendBridge/Frame-Rendering.md new file mode 100644 index 00000000..9b70ae8e --- /dev/null +++ b/docs/api/XCEngine/Editor/UI/ImGuiBackendBridge/Frame-Rendering.md @@ -0,0 +1,49 @@ +# ImGuiBackendBridge Frame Rendering + +**命名空间**: `XCEngine::Editor::UI` + +**类型**: `method group` + +**源文件**: `editor/src/UI/ImGuiBackendBridge.h` + +## 签名 + +```cpp +void BeginFrame() const; +void RenderDrawData(ID3D12GraphicsCommandList* commandList) const; +``` + +## 作用 + +驱动 ImGui backend 的逐帧准备和 D3D12 draw data 提交。 + +## 当前实现行为 + +### `BeginFrame()` + +- 依次调用: + - `ImGui_ImplDX12_NewFrame()` + - `ImGui_ImplWin32_NewFrame()` + - `ImGui::NewFrame()` +- 这说明它负责的是 backend 和 ImGui immediate frame 的起点。 + +### `RenderDrawData(commandList)` + +- 直接调用: + +```cpp +ImGui_ImplDX12_RenderDrawData(ImGui::GetDrawData(), commandList); +``` + +- 当前不做额外状态包装，调用方需要保证 command list 和 descriptor heap 已处在可渲染状态。 + +## 当前使用位置 + +- `Application` 每帧会先调用 `m_imguiBackend.BeginFrame()` +- `D3D12WindowRenderer` 在最终回写到交换链前会调用 `RenderDrawData(...)` + +## 相关文档 + +- [ImGuiBackendBridge](ImGuiBackendBridge.md) +- [Initialize / Shutdown](Initialize-And-Shutdown.md) +- [D3D12WindowRenderer](../../Platform/D3D12WindowRenderer/D3D12WindowRenderer.md) diff --git a/docs/api/XCEngine/Editor/UI/ImGuiBackendBridge/ImGuiBackendBridge.md b/docs/api/XCEngine/Editor/UI/ImGuiBackendBridge/ImGuiBackendBridge.md index 395af467..33017e9d 100644 --- a/docs/api/XCEngine/Editor/UI/ImGuiBackendBridge/ImGuiBackendBridge.md +++ b/docs/api/XCEngine/Editor/UI/ImGuiBackendBridge/ImGuiBackendBridge.md @@ -21,12 +21,35 @@ - 把 `ImGui::GetDrawData()` 提交到 D3D12 command list - 处理 Win32 消息转发 +## 公开 API + +### 平台与窗口桥接 + +- [Platform And Window Bridge](Platform-And-Window-Bridge.md) + +### 后端生命周期 + +- [Initialize / Shutdown](Initialize-And-Shutdown.md) + +### 逐帧渲染 + +- [Frame Rendering](Frame-Rendering.md) + +### 纹理描述符与显示纹理 + +- [Texture Descriptors And UploadedTexture](Texture-Descriptors-And-UploadedTexture.md) + +### RGBA 纹理上传 + +- [Texture Upload Flow](Texture-Upload-Flow.md) + ## 当前实现 - `Initialize()` 需要 `HWND`、`ID3D12Device*` 和 SRV heap - 默认 frame count 为 `3` - 默认 back buffer format 为 `DXGI_FORMAT_R8G8B8A8_UNORM` - `HandleWindowMessage()` 是静态 helper，直接转发给 `ImGui_ImplWin32_WndProcHandler` +- `UploadRgbaTexture(...)` 会返回 `UploadedTexture + PendingTextureUpload` 两段式结果，供调用方管理上传完成前的中间资源 ## 设计说明 @@ -46,6 +69,11 @@ ## 相关文档 - [UI](../UI.md) +- [Platform And Window Bridge](Platform-And-Window-Bridge.md) +- [Initialize / Shutdown](Initialize-And-Shutdown.md) +- [Frame Rendering](Frame-Rendering.md) +- [Texture Descriptors And UploadedTexture](Texture-Descriptors-And-UploadedTexture.md) +- [Texture Upload Flow](Texture-Upload-Flow.md) - [ImGuiSession](../ImGuiSession/ImGuiSession.md) - [Application](../../Application/Application.md) - [D3D12WindowRenderer](../../Platform/D3D12WindowRenderer/D3D12WindowRenderer.md) diff --git a/docs/api/XCEngine/Editor/UI/ImGuiBackendBridge/Initialize-And-Shutdown.md b/docs/api/XCEngine/Editor/UI/ImGuiBackendBridge/Initialize-And-Shutdown.md new file mode 100644 index 00000000..7aab72ce --- /dev/null +++ b/docs/api/XCEngine/Editor/UI/ImGuiBackendBridge/Initialize-And-Shutdown.md @@ -0,0 +1,62 @@ +# ImGuiBackendBridge::Initialize / Shutdown + +**命名空间**: `XCEngine::Editor::UI` + +**类型**: `methods` + +**源文件**: `editor/src/UI/ImGuiBackendBridge.h` + +## 签名 + +```cpp +void Initialize( + HWND hwnd, + ID3D12Device* device, + ID3D12CommandQueue* commandQueue, + ID3D12DescriptorHeap* srvHeap, + UINT srvDescriptorSize, + UINT srvDescriptorCount, + int frameCount = 3, + DXGI_FORMAT backBufferFormat = DXGI_FORMAT_R8G8B8A8_UNORM); +void Shutdown(); +``` + +## 作用 + +初始化或释放 Dear ImGui 的 Win32 + D3D12 backend 绑定状态，并接管一段 SRV descriptor heap 用于 ImGui 纹理显示。 + +## 当前实现行为 + +### `Initialize(...)` + +- 会缓存: + - `m_srvHeap` + - `m_srvDescriptorSize` + - `m_srvCpuStart` + - `m_srvGpuStart` +- 然后按 `srvDescriptorCount` 初始化 `m_srvUsage`，用于跟踪该 heap 片段的 descriptor 使用情况。 +- 先调用 `ImGui_ImplWin32_Init(hwnd)`。 +- 再构造 `ImGui_ImplDX12_InitInfo` 并调用 `ImGui_ImplDX12_Init(...)`。 +- 当前把自定义的 SRV 分配和释放回调挂进了: + - `SrvDescriptorAllocFn` + - `SrvDescriptorFreeFn` +- 成功后把 `m_initialized` 设为 `true`。 + +### `Shutdown()` + +- 如果当前尚未初始化，直接返回。 +- 否则依次调用: + - `ImGui_ImplDX12_Shutdown()` + - `ImGui_ImplWin32_Shutdown()` +- 然后清空 descriptor 使用表与相关 heap 指针、重置 upload fence，并把 `m_initialized` 设回 `false`。 + +## 当前实现边界 + +- 该类型不负责 ImGui context 生命周期；那部分由 [ImGuiSession](../ImGuiSession/ImGuiSession.md) 管理。 +- 当前后端明确绑定 Win32 + D3D12。 + +## 相关文档 + +- [ImGuiBackendBridge](ImGuiBackendBridge.md) +- [Platform And Window Bridge](Platform-And-Window-Bridge.md) +- [Frame Rendering](Frame-Rendering.md) diff --git a/docs/api/XCEngine/Editor/UI/ImGuiBackendBridge/Platform-And-Window-Bridge.md b/docs/api/XCEngine/Editor/UI/ImGuiBackendBridge/Platform-And-Window-Bridge.md new file mode 100644 index 00000000..9c5dce3b --- /dev/null +++ b/docs/api/XCEngine/Editor/UI/ImGuiBackendBridge/Platform-And-Window-Bridge.md @@ -0,0 +1,43 @@ +# ImGuiBackendBridge Platform And Window Bridge + +**命名空间**: `XCEngine::Editor::UI` + +**类型**: `static method group` + +**源文件**: `editor/src/UI/ImGuiBackendBridge.h` + +## 签名 + +```cpp +static void EnableDpiAwareness(); +static float GetDpiScaleForHwnd(HWND hwnd); +static bool HandleWindowMessage(HWND hwnd, UINT msg, WPARAM wParam, LPARAM lParam); +``` + +## 作用 + +提供 ImGui Win32 backend 的平台辅助入口，包括 DPI 初始化、窗口 DPI 查询和 Win32 消息桥接。 + +## 当前实现行为 + +### `EnableDpiAwareness()` + +- 直接调用 `ImGui_ImplWin32_EnableDpiAwareness()`。 +- 当前用于 Editor 进程初始化早期，保证 Win32 窗口 DPI 行为与 ImGui backend 对齐。 + +### `GetDpiScaleForHwnd(hwnd)` + +- 当 `hwnd` 有效时，转发到 `ImGui_ImplWin32_GetDpiScaleForHwnd(hwnd)`。 +- `hwnd == nullptr` 时返回 `1.0f`。 + +### `HandleWindowMessage(...)` + +- 直接把 Win32 消息转发给 `ImGui_ImplWin32_WndProcHandler(...)`。 +- 返回值表示该消息是否已被 ImGui backend 消费。 +- 当前 `Win32EditorHost` 会优先调用它，再决定是否继续走宿主窗口逻辑。 + +## 相关文档 + +- [ImGuiBackendBridge](ImGuiBackendBridge.md) +- [Initialize / Shutdown](Initialize-And-Shutdown.md) +- [Win32EditorHost](../../Platform/Win32EditorHost/Win32EditorHost.md) diff --git a/docs/api/XCEngine/Editor/UI/ImGuiBackendBridge/Texture-Descriptors-And-UploadedTexture.md b/docs/api/XCEngine/Editor/UI/ImGuiBackendBridge/Texture-Descriptors-And-UploadedTexture.md new file mode 100644 index 00000000..d5d9efe4 --- /dev/null +++ b/docs/api/XCEngine/Editor/UI/ImGuiBackendBridge/Texture-Descriptors-And-UploadedTexture.md @@ -0,0 +1,92 @@ +# ImGuiBackendBridge Texture Descriptors And UploadedTexture + +**命名空间**: `XCEngine::Editor::UI` + +**类型**: `method and type group` + +**源文件**: `editor/src/UI/ImGuiBackendBridge.h` + +## 公开类型 + +### `UploadedTexture` + +表示一个已经拥有 ImGui `ImTextureID` 和 D3D12 SRV 的上传纹理句柄。 + +关键字段包括： + +- `textureId` +- `cpuHandle` +- `gpuHandle` +- `texture` +- `width / height` + +`IsValid()` 当前要求： + +- `textureId` 非空 +- `texture` 非空 +- 尺寸大于 `0` + +## 签名 + +```cpp +void AllocateTextureDescriptor( + D3D12_CPU_DESCRIPTOR_HANDLE* outCpuHandle, + D3D12_GPU_DESCRIPTOR_HANDLE* outGpuHandle); +bool CreateTextureDescriptor( + ::XCEngine::RHI::RHIDevice* device, + ::XCEngine::RHI::RHITexture* texture, + D3D12_CPU_DESCRIPTOR_HANDLE* outCpuHandle, + D3D12_GPU_DESCRIPTOR_HANDLE* outGpuHandle, + ImTextureID* outTextureId); +void FreeTextureDescriptor( + D3D12_CPU_DESCRIPTOR_HANDLE cpuHandle, + D3D12_GPU_DESCRIPTOR_HANDLE gpuHandle); +void ResetUploadedTexture(UploadedTexture* texture); +``` + +## 作用 + +管理 ImGui 可显示纹理所需的 SRV descriptor，并提供把现有 `RHITexture` 包装成 `ImTextureID` 的桥接能力。 + +## 当前实现行为 + +### `AllocateTextureDescriptor(...)` + +- 通过内部 descriptor 使用表扫描第一个空闲槽位。 +- 成功时会返回对应的 CPU/GPU handle。 +- 当前 descriptor heap 耗尽时会触发 `IM_ASSERT`。 + +### `CreateTextureDescriptor(...)` + +- 要求传入的是 `D3D12Device` 与 `D3D12Texture` 的实际实现对象。 +- 当 dynamic cast 失败或底层资源为空时返回 `false`。 +- 成功时会: + - 先分配 descriptor + - 再以固定 `DXGI_FORMAT_R8G8B8A8_UNORM` 和 `MipLevels = 1` 创建 SRV + - 最终把 `gpuHandle.ptr` 转成 `ImTextureID` + +### `FreeTextureDescriptor(...)` + +- 当前只负责把 descriptor 槽位标记回空闲。 +- 不会主动销毁调用方持有的纹理资源。 + +### `ResetUploadedTexture(...)` + +- 允许传入空指针。 +- 若 `UploadedTexture` 持有有效 CPU handle，会先释放 descriptor。 +- 然后清空: + - `texture` + - `textureId` + - `cpuHandle / gpuHandle` + - `width / height` + +## 当前使用位置 + +- `ViewportHostRenderTargets` 会通过它给 Scene / Game 视口颜色纹理创建 ImGui 可显示描述符。 +- `BuiltInIcons` 会复用 `UploadedTexture` 保存已上传图标与预览纹理。 + +## 相关文档 + +- [ImGuiBackendBridge](ImGuiBackendBridge.md) +- [Texture Upload Flow](Texture-Upload-Flow.md) +- [BuiltInIcons](../BuiltInIcons/BuiltInIcons.md) diff --git a/docs/api/XCEngine/Editor/UI/ImGuiBackendBridge/Texture-Upload-Flow.md b/docs/api/XCEngine/Editor/UI/ImGuiBackendBridge/Texture-Upload-Flow.md new file mode 100644 index 00000000..2f03e53a --- /dev/null +++ b/docs/api/XCEngine/Editor/UI/ImGuiBackendBridge/Texture-Upload-Flow.md @@ -0,0 +1,97 @@ +# ImGuiBackendBridge Texture Upload Flow + +**命名空间**: `XCEngine::Editor::UI` + +**类型**: `method and type group` + +**源文件**: `editor/src/UI/ImGuiBackendBridge.h` + +## 公开类型 + +### `PendingTextureUpload` + +表示一次尚未完成 GPU 执行的纹理上传事务。当前会保存： + +- `uploadResource` +- `commandAllocator` +- `commandList` +- `fenceValue` + +这些资源会一直保留到 fence 完成为止，避免上传阶段的中间资源提前释放。 + +## 签名 + +```cpp +bool UploadRgbaTexture( + ID3D12Device* device, + ID3D12CommandQueue* commandQueue, + const std::uint8_t* rgbaPixels, + int width, + int height, + UploadedTexture* outTexture, + std::unique_ptr* outPendingUpload); +bool IsTextureUploadComplete(const PendingTextureUpload& upload) const; +void RemoveCompletedTextureUploads( + std::vector>* uploads) const; +bool WaitForQueueIdle(ID3D12Device* device, ID3D12CommandQueue* commandQueue) const; +``` + +## 作用 + +把一块 CPU 侧 RGBA 像素数据上传成 D3D12 纹理并暴露给 ImGui，同时提供上传完成查询和队列空闲等待 helper。 + +## 当前实现行为 + +### `UploadRgbaTexture(...)` + +- 会先校验设备、队列、像素指针、尺寸和输出参数。 +- 然后创建: + - 一个默认堆 `TEXTURE2D` + - 一个上传堆 `BUFFER` +- 使用 `GetCopyableFootprints(...)` 计算 upload buffer 布局，并逐行把 `rgbaPixels` 复制到映射内存。 +- 随后创建一次性 command allocator 和 command list，记录: + - `CopyTextureRegion(...)` + - `COPY_DEST -> PIXEL_SHADER_RESOURCE` 资源状态过渡 +- 之后会: + - 确保 upload fence 存在 + - 分配 ImGui texture descriptor + - 为新纹理创建 SRV + - 执行命令列表 + - 对队列 signal fence +- 成功时返回两部分结果: + - `UploadedTexture` + - `PendingTextureUpload` + +### `IsTextureUploadComplete(...)` + +- 通过比较 `m_uploadFence->GetCompletedValue()` 与 `upload.fenceValue` 判断上传是否已完成。 + +### `RemoveCompletedTextureUploads(...)` + +- 会就地删除 fence 已完成的 `PendingTextureUpload` 项。 +- 当前要求调用方自己持有并定期清理该数组。 + +### `WaitForQueueIdle(...)` + +- 每次调用都会临时创建一个 fence 和 Win32 event。 +- 给队列发送一次 `Signal(...)`，然后同步等待它完成。 +- 适合在资源销毁或 shutdown 前做保守同步。 + +## 当前使用位置 + +- `BuiltInIcons` 使用 `UploadRgbaTexture(...)` 上传内置图标与纹理预览。 +- `BuiltInIcons` 也会定期调用: + - `IsTextureUploadComplete(...)` + - `RemoveCompletedTextureUploads(...)` + - `WaitForQueueIdle(...)` + +## 当前实现边界 + +- 当前上传路径固定假设输入格式为 RGBA8。 +- 当前只处理 2D 纹理，SRV 视图同样固定为单 mip 2D 纹理。 + +## 相关文档 + +- [ImGuiBackendBridge](ImGuiBackendBridge.md) +- [Texture Descriptors And UploadedTexture](Texture-Descriptors-And-UploadedTexture.md) +- [BuiltInIcons](../BuiltInIcons/BuiltInIcons.md) diff --git a/docs/api/XCEngine/Editor/UI/ImGuiSession/ImGuiSession.md b/docs/api/XCEngine/Editor/UI/ImGuiSession/ImGuiSession.md index 16ef93c3..88716837 100644 --- a/docs/api/XCEngine/Editor/UI/ImGuiSession/ImGuiSession.md +++ b/docs/api/XCEngine/Editor/UI/ImGuiSession/ImGuiSession.md @@ -16,19 +16,34 @@ - 创建/销毁 ImGui context - 把布局 ini 文件放到 `/.xceditor/imgui_layout.ini` -- 配置默认字体并应用基础主题 +- 配置默认字体、DPI 缩放和基础主题 + +## 当前公开方法 + +| 方法 | 说明 | +|------|------| +| `Initialize(projectPath, mainDpiScale)` | 创建 ImGui context，并绑定项目级 ini、主题和字体。 | +| `Shutdown()` | 先保存布局，再销毁当前 ImGui context。 | +| `SaveSettings()` | 把当前布局写回磁盘。 | +| `GetIniPath()` | 返回当前项目绑定的 ini 路径。 | +| `SetProjectPath(projectPath)` | 切换到新的项目级 ini 文件，并返回磁盘上是否已有 docking 布局。 | ## 当前实现说明 -- `Initialize(projectPath)` 会开启 `ImGuiConfigFlags_DockingEnable`。 -- 字体优先尝试加载 `C:/Windows/Fonts/msyh.ttc`，失败时回退到 ImGui 默认字体。 +- `Initialize(projectPath, mainDpiScale)` 会创建 context，并开启 `ImGuiConfigFlags_DockingEnable`、`ConfigDpiScaleFonts` 和 `ConfigDpiScaleViewports`。 +- ini 文件当前固定落在 `/.xceditor/imgui_layout.ini`。 +- 主题配置会先应用 `BaseTheme`，再把 DPI 缩放钳到 `1.0f` 到 `4.0f`。 +- 字体当前优先加载 `C:/Windows/Fonts/segoeui.ttf`，成功时再 merge `C:/Windows/Fonts/msyh.ttc` 作为中文 fallback；如果主字体失败，则退化为单独加载 `msyh.ttc`，最后才回退到 ImGui 默认字体。 - `Shutdown()` 会先保存设置，再销毁当前 context。 - `SaveSettings()` 只在 context 存在且 ini 路径非空时生效。 +- `SetProjectPath(projectPath)` 会先保存当前布局，再切换 ini 路径、重新加载磁盘设置，并返回该 ini 文件里是否已经存在 `[Docking][Data]`。 +- `GetIniPath()` 暴露的是当前会话实际绑定的 ini 文件路径。 ## 当前实现边界 - 当前字体路径写死为 Windows 字体目录。 - 当前 ini 文件位置策略是项目局部目录，而不是全局用户目录。 +- `SetProjectPath(...)` 的返回值只表示磁盘上是否检测到了保存过的 docking 数据，不代表布局内容一定可用。 - 当前主要负责会话和基础样式，不处理平台/渲染后端桥接。 ## 相关文档 diff --git a/docs/api/XCEngine/Editor/UI/MenuCommand/MenuCommand.md b/docs/api/XCEngine/Editor/UI/MenuCommand/MenuCommand.md new file mode 100644 index 00000000..00dc5723 --- /dev/null +++ b/docs/api/XCEngine/Editor/UI/MenuCommand/MenuCommand.md @@ -0,0 +1,52 @@ +# MenuCommand + +**命名空间**: `XCEngine::Editor::UI` + +**类型**: `struct` + +**源文件**: `editor/src/UI/MenuCommand.h` + +**描述**: 定义 Editor 菜单项的轻量数据模型，支持普通 action 和 separator 两种项类型。 + +## 概述 + +`MenuCommand` 自身不负责绘制或执行，它只是把菜单项所需的最小数据整理成统一结构。 + +## 当前公开内容 + +### `MenuCommandKind` + +- `Action` +- `Separator` + +### `MenuCommand` + +字段包括： + +- `kind` +- `label` +- `shortcut` +- `selected` +- `enabled` + +并提供两个便捷构造函数： + +- `MenuCommand::Action(...)` +- `MenuCommand::Separator()` + +## 当前使用位置 + +- `ActionBinding.h` 会把 action 绑定转换成 `MenuCommand` +- `Widgets.h` 负责把 `MenuCommand` 真正绘制成菜单项 +- `HierarchyActionRouter.h` 当前直接声明 `MenuCommand` 数组做排序菜单 + +## 当前实现边界 + +- 这里只是数据对象，不内置回调。 +- 菜单执行逻辑仍由 `Widgets::DrawMenuCommand(...)` 外部提供。 + +## 相关文档 + +- [当前模块](../UI.md) +- [Widgets](../Widgets/Widgets.md) +- [ActionBinding](../../Actions/ActionBinding/ActionBinding.md) diff --git a/docs/api/XCEngine/Editor/UI/ReferencePicker/ReferencePicker.md b/docs/api/XCEngine/Editor/UI/ReferencePicker/ReferencePicker.md new file mode 100644 index 00000000..97dac5e4 --- /dev/null +++ b/docs/api/XCEngine/Editor/UI/ReferencePicker/ReferencePicker.md @@ -0,0 +1,72 @@ +# ReferencePicker + +**命名空间**: `XCEngine::Editor::UI` + +**类型**: `utility-header` + +**源文件**: `editor/src/UI/ReferencePicker.h` + +**描述**: 提供统一的资产 / 场景对象引用选择控件，支持搜索、拖拽资产、双 tab 浏览和清空当前引用。 + +## 概述 + +`ReferencePicker` 是当前 Inspector 和脚本字段编辑里最重要的“引用类型 UI”之一。 + +它解决的是：在不直接暴露原始路径文本框的前提下，让用户选择： + +- 项目资产 +- 当前场景中的对象 + +## 当前公开内容 + +### 类型 + +- `ReferencePickerTab` +- `ReferencePickerOptions` +- `ReferencePickerInteraction` + +### 主入口 + +- `DrawReferencePickerControl(...)` + +## 当前行为 + +调用后会先画出一个只读引用字段，随后支持： + +- 点击打开 popup +- 接收 `ASSET_ITEM` 拖放 payload +- 显示 Assets / Scene 双 tab +- 搜索过滤 +- 清空当前引用 + +资产候选当前来自 `ProjectManager` 的项目树；场景候选当前来自 `SceneManager` 的根节点递归遍历。 + +返回值会表达三种结果： + +- `assignedAssetPath` +- `assignedSceneObjectId` +- `clearRequested` + +## 当前依赖关系 + +- 资产路径会通过 `ProjectFileUtils::MakeProjectRelativePath(...)` 归一化到项目相对路径。 +- 搜索逻辑复用 [SearchText](../SearchText/SearchText.md)。 +- 图标绘制复用 `BuiltInIcons`。 + +## 当前使用位置 + +- `InspectorPanel.cpp` +- `ScriptComponentEditor.h` +- `AssetReferenceEditorUtils.h` + +## 当前实现边界 + +- 当前 scene 选择范围只覆盖当前已加载场景层级。 +- 状态缓存通过 `ImGuiID` 持有，不是独立可序列化对象。 +- 这套控件同时支持资产和场景对象，但具体调用方可以通过选项关闭任一 tab。 + +## 相关文档 + +- [当前模块](../UI.md) +- [SearchText](../SearchText/SearchText.md) +- [AssetReferenceEditorUtils](../../ComponentEditors/AssetReferenceEditorUtils/AssetReferenceEditorUtils.md) diff --git a/docs/api/XCEngine/Editor/UI/SearchText/SearchText.md b/docs/api/XCEngine/Editor/UI/SearchText/SearchText.md new file mode 100644 index 00000000..086acdc9 --- /dev/null +++ b/docs/api/XCEngine/Editor/UI/SearchText/SearchText.md @@ -0,0 +1,52 @@ +# SearchText + +**命名空间**: `XCEngine::Editor::UI` + +**类型**: `utility-header` + +**源文件**: `editor/src/UI/SearchText.h` + +**描述**: 提供简单的大小写无关搜索文本归一化与查询对象 `SearchQuery`。 + +## 概述 + +`SearchText.h` 很小，但它是当前多个 Editor 面板共享的搜索基础。 + +## 当前公开内容 + +- `NormalizeSearchText(std::string_view)` +- `SearchQuery` + +### `SearchQuery` + +当前提供： + +- 默认构造 +- `SearchQuery(std::string_view)` +- `Empty()` +- `Text()` +- `Matches(...)` +- `MatchesNormalized(...)` + +## 当前语义 + +- 归一化规则当前就是转小写。 +- `Matches(...)` 会先对输入文本归一化，再做子串查找。 +- `MatchesNormalized(...)` 则假定调用方已经给出了归一化文本，避免重复处理。 + +## 当前使用位置 + +- `ConsolePanel.cpp` +- `HierarchyPanel.cpp` +- `ProjectPanel.cpp` +- [ReferencePicker](../ReferencePicker/ReferencePicker.md) + +## 当前实现边界 + +- 当前没有分词、模糊匹配、拼音匹配或 ranking。 +- 这是轻量 substring search helper，不是全文检索层。 + +## 相关文档 + +- [当前模块](../UI.md) +- [ReferencePicker](../ReferencePicker/ReferencePicker.md) diff --git a/docs/api/XCEngine/Editor/UI/UI.md b/docs/api/XCEngine/Editor/UI/UI.md index f9cef513..ddc7cffa 100644 --- a/docs/api/XCEngine/Editor/UI/UI.md +++ b/docs/api/XCEngine/Editor/UI/UI.md @@ -45,7 +45,7 @@ 管理层级树 / 目录树的共享节点表现与图标前缀。 - `PropertyLayout + ScalarControls + VectorControls + PropertyGrid` 管理 Inspector 的属性布局、标量控件、向量控件和高层属性编辑入口。 -- `Widgets + PopupState + SceneStatusWidget + AboutEditorDialog` +- `Widgets + PopupState + SceneStatusWidget + AboutEditorDialog + ReferencePicker` 提供更接近编辑器业务语义的通用 widget。 这次重构里，`TreeView`、`PropertyLayout`、`BuiltInIcons` 和 `DockTabBarChrome` 是最明显的新基础设施，它们共同把原先分散在具体面板中的 UI 技巧沉淀成了复用层。 @@ -74,20 +74,26 @@ - [AboutEditorDialog](AboutEditorDialog/AboutEditorDialog.md) - `AboutEditorDialog.h`，关于对话框相关 UI。 - [BaseTheme](BaseTheme/BaseTheme.md) - `BaseTheme.h`，编辑器基础主题安装。 +- [BuiltInIconLayoutUtils](BuiltInIconLayoutUtils/BuiltInIconLayoutUtils.md) - `BuiltInIconLayoutUtils.h`，图标按比例缩放布局 helper。 - [BuiltInIcons](BuiltInIcons/BuiltInIcons.md) - `BuiltInIcons.h`，内置资源/对象图标系统。 +- [ColorPicker](ColorPicker/ColorPicker.md) - `ColorPicker.h`，Unity 风格颜色弹窗控件。 - [ConsoleFilterState](ConsoleFilterState/ConsoleFilterState.md) - `ConsoleFilterState.h`，Console 过滤状态。 - [ConsoleLogFormatter](ConsoleLogFormatter/ConsoleLogFormatter.md) - `ConsoleLogFormatter.h`，Console 日志格式化。 +- [ContextMenu](ContextMenu/ContextMenu.md) - `ContextMenu.h`，统一上下文菜单 chrome 与 popup helper。 - [Core](Core/Core.md) - `Core.h`，底层 ImGui helper 与 popup chrome 包装。 - [DividerChrome](DividerChrome/DividerChrome.md) - `DividerChrome.h`，统一分隔线绘制。 - [DockHostStyle](DockHostStyle/DockHostStyle.md) - `DockHostStyle.h`，dock host 风格压栈。 - [DockTabBarChrome](DockTabBarChrome/DockTabBarChrome.md) - `DockTabBarChrome.h`，自定义 dock 标签栏。 - [ImGuiBackendBridge](ImGuiBackendBridge/ImGuiBackendBridge.md) - `ImGuiBackendBridge.h`，ImGui 与 D3D12 之间的桥接层。 - [ImGuiSession](ImGuiSession/ImGuiSession.md) - `ImGuiSession.h`，ImGui 会话生命周期。 +- [MenuCommand](MenuCommand/MenuCommand.md) - `MenuCommand.h`，菜单项轻量数据模型。 - [PanelChrome](PanelChrome/PanelChrome.md) - `PanelChrome.h`，面板窗口 / 工具栏 / 内容区 RAII 外壳。 - [PopupState](PopupState/PopupState.md) - `PopupState.h`，延迟弹窗与目标型弹窗状态。 - [PropertyGrid](PropertyGrid/PropertyGrid.md) - `PropertyGrid.h`，Inspector 级属性编辑入口。 - [PropertyLayout](PropertyLayout/PropertyLayout.md) - `PropertyLayout.h`，属性行几何布局层。 +- [ReferencePicker](ReferencePicker/ReferencePicker.md) - `ReferencePicker.h`，资产 / 场景对象引用选择控件。 - [ScalarControls](ScalarControls/ScalarControls.md) - `ScalarControls.h`，标量属性控件。 +- [SearchText](SearchText/SearchText.md) - `SearchText.h`，大小写无关搜索 helper。 - [SceneStatusWidget](SceneStatusWidget/SceneStatusWidget.md) - `SceneStatusWidget.h`，场景状态部件。 - [SplitterChrome](SplitterChrome/SplitterChrome.md) - `SplitterChrome.h`，分隔条交互与绘制。 - [StyleTokens](StyleTokens/StyleTokens.md) - `StyleTokens.h`，Editor UI 设计 token 中心。 diff --git a/docs/api/XCEngine/Editor/UI/Widgets/Widgets.md b/docs/api/XCEngine/Editor/UI/Widgets/Widgets.md index 0c7f7ab9..8dc59adb 100644 --- a/docs/api/XCEngine/Editor/UI/Widgets/Widgets.md +++ b/docs/api/XCEngine/Editor/UI/Widgets/Widgets.md @@ -6,47 +6,198 @@ **源文件**: `editor/src/UI/Widgets.h` -**描述**: 提供更接近编辑器业务语义的中高层 widget，如菜单命令、层级树节点、资产格子、组件区块和对话框按钮行。 +**描述**: 面向编辑器业务语义的高层 ImGui helper 集合，覆盖菜单、搜索框、行内重命名、面包屑、资产卡片、Inspector section、弹窗和日志行等可复用交互单元。 ## 概述 -如果说 [`Core`](../Core/Core.md) 是底层 UI 包装，那么 `Widgets.h` 就是更贴近编辑器业务的通用组件库。 -当前文件涵盖的内容很多，主要可以分成几类： +`Widgets.h` 不是底层绘图原语集合，而是“已经带编辑器语义”的复用控件层。 -- 菜单与命令：`MenuCommand`、`DrawMenuScope`、`DrawMenuCommands` -- 工具栏：搜索框、标签、切换按钮、面包屑 -- Hierarchy / Project：`DrawHierarchyNode`、`DrawAssetTile`、`DrawAssetIcon` -- Inspector：`BeginComponentSection` -- 对话框与 tooltip：`DrawDialogActionRow`、`BeginTitledPopup`、`BeginTitledTooltip` -- Console：`DrawConsoleLogRow` +它的定位介于： + +- `Core.h`、`StyleTokens.h` 这类基础 UI 封装 +- 具体面板文件里的业务流程 + +之间。 + +当前多个关键面板都直接依赖它： + +- `ProjectPanel` +- `HierarchyPanel` +- `InspectorPanel` +- `ConsolePanel` + +所以这份 header 的核心价值，不是减少几行 ImGui 代码，而是统一整个 editor 的交互语言。 + +## 当前覆盖的 widget 类别 + +| 类别 | 代表 API | 主要使用场景 | +|------|------|------| +| 菜单与子菜单 | `DrawMenuScope`、`DrawMenuCommand`、`DrawMenuCommands`、`DrawPopupSubmenuScope` | MenuBar、Hierarchy / Project 上下文菜单 | +| 工具栏与搜索 | `ToolbarSearchField`、`DrawToolbarLabel`、`ToolbarToggleButton` | Project / Console / 顶部工具栏 | +| 行内编辑 | `DrawInlineRenameField`、`DrawInlineRenameFieldAt` | Project 资源网格重命名、Hierarchy 行内重命名 | +| 路径导航 | `DrawToolbarBreadcrumbs`、`DrawBreadcrumbSegment` | Project 面包屑 | +| 资产浏览 | `ComputeAssetTileSize`、`DrawAssetTile`、`AssetTileOptions` | Project 浏览区 | +| Inspector section | `BeginComponentSection`、`EndComponentSection`、`InspectorActionButton` | Inspector 组件区块、材质资源区块 | +| 弹窗与对话框 | `BeginTitledPopup`、`DrawDialogActionRow` | 选择器、确认弹窗 | +| 提示与日志 | `BeginTitledTooltip`、`DrawConsoleLogRow`、`DrawEmptyState`、`DrawHintText` | Console、空状态、悬浮提示 | + +## 为什么这一层很重要 + +即时模式 UI 最容易出现的问题，不是“没法画出来”，而是： + +- 同一种交互在不同面板里长得不一样 +- 每个面板都自己实现一份重命名输入框 +- 上下文菜单、面包屑、资产卡片的行为逐渐漂移 + +`Widgets.h` 当前就是专门用来压住这类分叉的。 + +它把“编辑器里反复出现的交互模式”抽成统一 helper，使面板层可以更专注于： + +- 当前数据来自哪里 +- 当前用户动作应该触发什么命令 + +而不是反复造相同的 UI 小轮子。 + +## 结果结构而不是直接副作用 + +当前文件一个很重要的风格，是尽量用结果结构返回交互状态，而不是在 helper 内部直接改业务对象。 + +例如： + +- `AssetTileResult` +- `InlineRenameFieldResult` +- `ComponentSectionResult` + +这种做法对 ImGui 风格 editor 很关键，因为调用方通常需要： + +- 先绘制 +- 再统一在循环外处理选择、打开、导航、提交重命名 + +`ProjectPanel` 当前就是典型例子。它先批量收集 `clicked` / `openRequested`，再在循环末统一处理 selection 和 open 行为，避免在遍历过程中破坏当前容器或导航状态。 + +## 关键 helper 行为 + +### 搜索框 + +`ToolbarSearchField(...)` 当前除了调用 `InputTextWithHint(...)`，还会： + +- 应用统一的工具栏输入框样式 +- 按 `trailingWidth` 自动计算可用宽度 +- 在输入框左侧手动画搜索图标 + +这意味着 Project 等工具栏的搜索控件已经有统一视觉和布局语义，而不是普通裸 `InputText`。 + +### 行内重命名 + +`DrawInlineRenameField(...)` 和 `DrawInlineRenameFieldAt(...)` 当前返回： + +- `submitted` +- `cancelRequested` +- `deactivated` +- `active` + +这几个状态组合非常实用，因为编辑器行内重命名通常既要响应： + +- Enter 提交 +- Escape 取消 +- 失焦提交或结束 + +又要允许调用方控制焦点请求和屏幕定位。 + +### 面包屑 + +`DrawToolbarBreadcrumbs(...)` 当前把 root label、路径段数量、名称回调和导航回调解耦开来。 + +它的行为是： + +- 当前段不可点击 +- 非当前段点击后回调 `navigateToSegment(index)` +- 相邻段之间统一插入 `>` 分隔符 + +`ProjectPanel` 正是靠它把 `Assets -> ... -> CurrentFolder` 渲染成稳定的导航条。 + +### 资产卡片 + +`DrawAssetTile(...)` 是当前 Project Browser 最核心的共享 widget 之一。 + +它会统一处理： + +- 空闲边框与填充 +- 选中态高亮 +- 拖拽中的 dim overlay +- 图标居中布局 +- 标签区域裁剪 +- 单击和双击判断 + +并返回： + +- `clicked` +- `openRequested` +- `hovered` +- `labelMin / labelMax` + +其中 `labelMin / labelMax` 会被 `ProjectPanel` 继续拿去覆盖行内重命名输入框位置。 + +### Inspector section + +`BeginComponentSection(...)` 当前做的不只是画一个标题行。它还负责： + +- 用 ImGui state storage 按 `id` 保存展开状态 +- 绘制 disclosure arrow +- 统一 header 背景、边框和文字布局 +- 返回内容缩进量 + +这让 `InspectorPanel` 和材质资源 inspector 可以在完全共享的 section 语义上继续叠加各自内容。 + +### Popup 子菜单 + +`DrawPopupSubmenuScope(...)` 是当前比较有“编辑器修 bug 痕迹”的 helper。 + +它除了处理 popup 子菜单的 hover-open / click-open / auto-close 之外，还会对标签为 `Create` 的子菜单写调试日志，用来定位 Hierarchy 创建子菜单 popup 状态错乱问题。 + +这说明 `Widgets.h` 不只是“视觉控件库”，也承担了一部分复杂交互协议的收口工作。 + +## 真实调用方式 + +当前几个典型使用点是： + +- `ProjectPanel` + - `ToolbarSearchField(...)` + - `DrawToolbarBreadcrumbs(...)` + - `DrawAssetTile(...)` + - `DrawInlineRenameFieldAt(...)` +- `InspectorPanel` + - `BeginComponentSection(...)` + - `InspectorActionButton(...)` + - `DrawHintText(...)` + - `DrawEmptyState(...)` +- `HierarchyActionRouter` + - `DrawMenuCommands(...)` + - `DrawPopupSubmenuScope(...)` +- `ConsolePanel` + - `DrawConsoleLogRow(...)` ## 设计说明 -这类文件在商业编辑器里通常非常关键，因为它决定了“多个面板是否共享同一种交互语言”。 -比如： +当前 `Widgets.h` 的设计取向很明确： -- Hierarchy 节点的点击、展开和双击 -- Project 资源网格的卡片样式 -- Inspector 组件区块的标题和右键菜单 +- 保持 header-only，降低调用成本 +- 通过小结果结构承载交互状态 +- 让多个面板共享一致的 UI 语义 -如果这些都散落在各个面板里，最终 UI 行为会越来越不一致。 - -## 当前实现特征 - -- `MenuCommand` 把菜单项和分隔线统一成一个小数据结构 -- `AssetTileResult`、`HierarchyNodeResult` 等结果结构让调用方更容易写流程判断 -- 组件区块与工具栏、搜索框都已经形成可复用构件 +这是一种很典型的 Dear ImGui 编辑器写法。它未必“面向通用 GUI 框架”，但对当前项目这种单体 editor 非常高效。 ## 当前限制 -- 仍然是 header inline helpers，而不是独立 widget 类库 -- 某些 widget 仍然高度耦合当前编辑器视觉风格 -- 还没有更高级的虚拟列表、树过滤高亮或多列资源浏览控件 +- 仍然是 inline helper 集合，不是独立 widget framework。 +- 某些 helper 明显服务于当前视觉风格和业务模型，通用性有限。 +- 目前没有虚拟列表、树过滤高亮、多列资产表等更重型控件。 +- `Create` 子菜单相关 trace 直接写日志通道，后续若日志层细化，可能需要单独的 debug 开关。 ## 相关文档 - [UI](../UI.md) - [Core](../Core/Core.md) -- [StyleTokens](../StyleTokens/StyleTokens.md) -- [HierarchyPanel](../../panels/HierarchyPanel/HierarchyPanel.md) - [ProjectPanel](../../panels/ProjectPanel/ProjectPanel.md) +- [InspectorPanel](../../panels/InspectorPanel/InspectorPanel.md) +- [HierarchyActionRouter](../../Actions/HierarchyActionRouter/HierarchyActionRouter.md) diff --git a/docs/api/XCEngine/Editor/Utils/FileDialogUtils/FileDialogUtils.md b/docs/api/XCEngine/Editor/Utils/FileDialogUtils/FileDialogUtils.md new file mode 100644 index 00000000..47035bf3 --- /dev/null +++ b/docs/api/XCEngine/Editor/Utils/FileDialogUtils/FileDialogUtils.md @@ -0,0 +1,52 @@ +# FileDialogUtils + +**命名空间**: `XCEngine::Editor::FileDialogUtils` + +**类型**: `utility-header` + +**源文件**: `editor/src/Utils/FileDialogUtils.h` + +**描述**: 提供 Editor 常用的打开文件、保存文件和选择目录对话框封装。 + +## 概述 + +`FileDialogUtils` 是当前编辑器里对 Win32 / COM 文件对话框的一层轻量包装。 + +它的目标很直接：让上层命令和面板可以直接拿到 UTF-8 字符串路径，而不必重复处理宽字符、owner window 和 COM 初始化这些细节。 + +## 当前公开函数 + +- `GetDialogOwnerWindow()` +- `OpenFileDialog(...)` +- `SaveFileDialog(...)` +- `PickFolderDialog(...)` + +## 当前行为 + +### `OpenFileDialog(...)` + +- 基于 `GetOpenFileNameW` +- 支持初始目录、初始路径和自定义 flags +- 失败或取消时返回空字符串 + +### `SaveFileDialog(...)` + +- 基于 `GetSaveFileNameW` +- 支持默认扩展名和建议保存路径 + +### `PickFolderDialog(...)` + +- 基于 `IFileDialog` +- 使用 `FOS_PICKFOLDERS` +- 内部处理 `CoInitializeEx` / `CoUninitialize` + +## 当前实现边界 + +- 当前是明确的 Windows-only 工具层。 +- 返回值只有最终路径字符串，不保留更细粒度的错误原因。 +- 对话框 owner 依赖当前活动窗口或前台窗口。 + +## 相关文档 + +- [当前模块](../Utils.md) +- [ProjectCommands](../../Commands/ProjectCommands/ProjectCommands.md) diff --git a/docs/api/XCEngine/Editor/Utils/ProjectFileUtils/ProjectFileUtils.md b/docs/api/XCEngine/Editor/Utils/ProjectFileUtils/ProjectFileUtils.md new file mode 100644 index 00000000..e7991d76 --- /dev/null +++ b/docs/api/XCEngine/Editor/Utils/ProjectFileUtils/ProjectFileUtils.md @@ -0,0 +1,65 @@ +# ProjectFileUtils + +**命名空间**: `XCEngine::Editor::ProjectFileUtils` + +**类型**: `utility-header` + +**源文件**: `editor/src/Utils/ProjectFileUtils.h` + +**描述**: 提供 `Project.xcproject` 的读写、项目名推导以及项目相对路径解析辅助。 + +## 概述 + +`ProjectFileUtils` 把当前 Editor 项目描述文件的最小协议封装成了一组 header-only helper。 + +这层处理的是很朴素但很常用的几件事： + +- 项目描述文件路径在哪里 +- 项目名默认取什么 +- `Project.xcproject` 如何保存和读取 +- 全路径和项目相对路径如何互转 + +## 当前公开内容 + +### `ProjectDescriptor` + +- `name` +- `startupScene` + +### 主要 helper + +- `GetProjectFilePath(...)` +- `GetProjectName(...)` +- `Trim(...)` +- `SaveProjectDescriptor(...)` +- `LoadProjectDescriptor(...)` +- `MakeProjectRelativePath(...)` +- `ResolveProjectPath(...)` + +## 当前文件格式 + +当前 `Project.xcproject` 仍然是简单的 key-value 文本： + +- `version=1` +- `name=...` +- `startup_scene=...` + +它不是 JSON，也不是事务式数据库。 + +## 当前使用位置 + +- `ProjectCommands.h` 用它生成并保存项目描述。 +- `SceneManager.cpp` 用它读取 startup scene。 +- `ProjectPanel.cpp`、`InspectorPanel.cpp` 和 `ReferencePicker.h` 用它把绝对路径折回项目相对路径。 + +## 当前实现边界 + +- 当前协议字段很少，只够支撑项目名和启动场景。 +- 路径解析主要围绕当前本地文件系统工作流，不带更复杂的虚拟文件系统抽象。 +- `LoadProjectDescriptor(...)` 对未知字段会忽略，不做严格模式校验。 + +## 相关文档 + +- [当前模块](../Utils.md) +- [ProjectRootResolver](../../Core/ProjectRootResolver/ProjectRootResolver.md) +- [ProjectManager](../../Managers/ProjectManager/ProjectManager.md) diff --git a/docs/api/XCEngine/Editor/Utils/Utils.md b/docs/api/XCEngine/Editor/Utils/Utils.md index be173b4e..c45bdcc0 100644 --- a/docs/api/XCEngine/Editor/Utils/Utils.md +++ b/docs/api/XCEngine/Editor/Utils/Utils.md @@ -4,21 +4,32 @@ **类型**: `submodule` -**描述**: 编辑器辅助函数层，当前主要围绕场景切换确认、文件对话框和撤销相关辅助展开。 +**描述**: 编辑器辅助函数层，当前围绕项目描述文件、文件对话框、场景切换确认和撤销相关辅助展开。 ## 概述 当前 `Utils` 目录包括： +- `FileDialogUtils.h` +- `ProjectFileUtils.h` - `SceneEditorUtils.h` - `UndoUtils.h` 这些工具函数本身不构成一个很强的对象模型，但它们支撑了： +- 项目描述文件读写与项目相对路径转换 +- 打开/保存文件与选择目录对话框 - 场景打开/保存对话框 - 场景切换确认 - 撤销与交互式修改配合 +## 当前页面 + +- [FileDialogUtils](FileDialogUtils/FileDialogUtils.md) +- [ProjectFileUtils](ProjectFileUtils/ProjectFileUtils.md) +- [SceneEditorUtils](SceneEditorUtils/SceneEditorUtils.md) +- [UndoUtils](UndoUtils/UndoUtils.md) + ## 相关文档 - [Editor 模块](../Editor.md) diff --git a/docs/api/XCEngine/Editor/Viewport/IViewportHostService/IViewportHostService.md b/docs/api/XCEngine/Editor/Viewport/IViewportHostService/IViewportHostService.md index 0f4bb9e2..c81b0d1b 100644 --- a/docs/api/XCEngine/Editor/Viewport/IViewportHostService/IViewportHostService.md +++ b/docs/api/XCEngine/Editor/Viewport/IViewportHostService/IViewportHostService.md @@ -27,7 +27,7 @@ | `EditorViewportKind` | 区分 `Scene` 与 `Game` 两类视口。 | | `EditorViewportFrame` | 面板拿到的视口帧结果，包含 `ImTextureID`、请求尺寸、实际渲染尺寸和状态文案。 | | `SceneViewportInput` | Scene View 每帧输入快照，包含 hover/focus、鼠标增量、滚轮、飞行移动和 focus-selection 请求。 | -| `SceneViewportOverlayData` | 面板侧绘制 gizmo / orientation gizmo 所需的相机姿态数据。 | +| [SceneViewportOverlayData](SceneViewportOverlayData.md) | 面板侧绘制 gizmo / orientation gizmo 所需的相机姿态数据。 | | `SceneViewportOrientationAxis` | 右上角朝向 gizmo 点击后的目标轴语义。 | ## 接口契约 diff --git a/docs/api/XCEngine/Editor/Viewport/IViewportHostService/SceneViewportOverlayData.md b/docs/api/XCEngine/Editor/Viewport/IViewportHostService/SceneViewportOverlayData.md new file mode 100644 index 00000000..c38ed0f4 --- /dev/null +++ b/docs/api/XCEngine/Editor/Viewport/IViewportHostService/SceneViewportOverlayData.md @@ -0,0 +1,46 @@ +# SceneViewportOverlayData + +**命名空间**: `XCEngine::Editor` + +**类型**: `struct` + +**源文件**: `editor/src/Viewport/IViewportHostService.h` + +## 描述 + +Scene View 前端几何计算使用的相机 overlay 数据快照。 + +## 当前字段 + +| 字段 | 类型 | 语义 | +|------|------|------| +| `valid` | `bool` | 当前相机 overlay 是否可用。 | +| `cameraPosition` | `Math::Vector3` | 相机世界位置。 | +| `cameraForward` | `Math::Vector3` | 相机前向。 | +| `cameraRight` | `Math::Vector3` | 相机右向。 | +| `cameraUp` | `Math::Vector3` | 相机上向。 | +| `verticalFovDegrees` | `float` | 当前垂直视场角。 | +| `nearClipPlane` | `float` | 近裁剪面。 | +| `farClipPlane` | `float` | 远裁剪面。 | +| `orbitDistance` | `float` | Scene View 相机控制器当前 orbit 距离。 | + +## 当前语义 + +- 这份结构不是最终的 `SceneViewportOverlayFrameData`，而是前端投影、gizmo 数学和 HUD 需要的相机输入。 +- `valid == false` 时，调用方应把这份数据视为“当前没有可用于 Scene View overlay 计算的私有相机”。 +- `ViewportHostService::GetSceneViewOverlayData()` 当前会从隐藏编辑器相机提取这些字段。 + +## 当前使用位置 + +- `SceneViewportMath/**` 用它构建 view / projection、做世界点投影和轴向拖拽几何。 +- `SceneViewportHudOverlay/**` 与 `SceneViewportOrientationGizmo/**` 用它驱动右上角 HUD / orientation gizmo。 +- `SceneViewportOverlayFrameCache/**` 会把它作为缓存失效判定的一部分。 +- `ViewportHostRenderFlowUtils::BuildSceneViewportGridPassData(...)` 当前直接从这里拷贝 grid pass 需要的相机字段。 + +## 相关文档 + +- [IViewportHostService](IViewportHostService.md) +- [SceneView Overlay Contracts](SceneView-Overlay-Contracts.md) +- [SceneViewportMath](../SceneViewportMath/SceneViewportMath.md) +- [SceneViewportHudOverlay](../SceneViewportHudOverlay/SceneViewportHudOverlay.md) +- [SceneViewportOverlayFrameCache](../SceneViewportOverlayFrameCache/SceneViewportOverlayFrameCache.md) diff --git a/docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportEditorOverlayPass/Render.md b/docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportEditorOverlayPass/Render.md index 8d07e12f..697c11e2 100644 --- a/docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportEditorOverlayPass/Render.md +++ b/docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportEditorOverlayPass/Render.md @@ -52,10 +52,9 @@ sprite 还会按 `sortDepth` 做 back-to-front 排序，以保证透明图标混 - `EnsureScreenTriangleBufferCapacity(...)` - `EnsureSpriteBufferCapacity(...)` -只要当前帧存在 sprite，还会调用 `EnsureIconTexturesLoaded()`，按需加载： +只要当前帧存在 sprite，还会调用 `EnsureIconTexturesLoaded()`。 -- `camera_gizmo.png` -- `main_light_gizmo.png` +这个 helper 现在只是转发到 [SceneViewportOverlaySpriteResourceCache::EnsureResources](../../SceneViewportOverlaySpriteResources/EnsureResources.md)，由它按需加载 camera / light 两类 overlay sprite 资源，并为每种 sprite 准备可直接绑定的 `RHIDescriptorSet`。 ### 4. 上传常量与切换 render target @@ -96,3 +95,4 @@ sprite 还会按 `sortDepth` 做 back-to-front 排序，以保证透明图标混 - [Shutdown](Shutdown.md) - [CreateSceneViewportEditorOverlayPass](CreateSceneViewportEditorOverlayPass.md) - [SceneViewportEditorOverlayData](../../SceneViewportEditorOverlayData/SceneViewportEditorOverlayData.md) +- [SceneViewportOverlaySpriteResources](../../SceneViewportOverlaySpriteResources/SceneViewportOverlaySpriteResources.md) diff --git a/docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportEditorOverlayPass/SceneViewportEditorOverlayPass.md b/docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportEditorOverlayPass/SceneViewportEditorOverlayPass.md index d3a94388..e1927089 100644 --- a/docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportEditorOverlayPass/SceneViewportEditorOverlayPass.md +++ b/docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportEditorOverlayPass/SceneViewportEditorOverlayPass.md @@ -22,7 +22,7 @@ - [Render](Render.md) 把当前帧 `worldLines / screenTriangles / worldSprites` 转成 GPU draw call。 - [Shutdown](Shutdown.md) - 释放 pipeline、descriptor、buffer 与内置 icon 纹理。 + 释放 pipeline、descriptor、buffer，以及由 `SceneViewportOverlaySpriteResourceCache` 持有的 icon 纹理资源。 - [CreateSceneViewportEditorOverlayPass](CreateSceneViewportEditorOverlayPass.md) 生成一帧使用的 `RenderPass` 包装对象。 @@ -39,9 +39,9 @@ - line vertex buffer - screen-triangle vertex buffer - sprite vertex buffer -- 内置 sprite 纹理当前只有： - - `resources/Icons/camera_gizmo.png` - - `resources/Icons/main_light_gizmo.png` +- world sprite 采样资源当前由 [SceneViewportOverlaySpriteResourceCache](../../SceneViewportOverlaySpriteResources/SceneViewportOverlaySpriteResourceCache.md) 统一管理： + - `Camera` -> `editor/resources/Icons/camera_gizmo.png` + - `Light` -> `editor/resources/Icons/main_light_gizmo.png` ## 数据来源 @@ -73,5 +73,6 @@ - [CreateSceneViewportEditorOverlayPass](CreateSceneViewportEditorOverlayPass.md) - [SceneViewportEditorOverlayData](../../SceneViewportEditorOverlayData/SceneViewportEditorOverlayData.md) +- [SceneViewportOverlaySpriteResources](../../SceneViewportOverlaySpriteResources/SceneViewportOverlaySpriteResources.md) - [SceneViewportHudOverlay](../../SceneViewportHudOverlay/SceneViewportHudOverlay.md) - [ViewportHostService](../../ViewportHostService/ViewportHostService.md) diff --git a/docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportEditorOverlayPass/Shutdown.md b/docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportEditorOverlayPass/Shutdown.md index 4f2b7a62..6d1f9113 100644 --- a/docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportEditorOverlayPass/Shutdown.md +++ b/docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportEditorOverlayPass/Shutdown.md @@ -27,7 +27,7 @@ DestroyResources(); 而 `DestroyResources()` 会按资源类型依次释放： - line / screen-triangle / sprite 三类 vertex buffer 及 view -- camera / light 两张 overlay sprite 纹理、SRV 和 descriptor set +- `SceneViewportOverlaySpriteResourceCache` 持有的 camera / light 两张 overlay sprite 纹理、SRV 和 descriptor set - depth-tested / always-on-top 两套 line、screen-triangle、sprite pipeline state - sampler / constant / texture descriptor pool 与 descriptor set - pipeline layout @@ -54,3 +54,4 @@ DestroyResources(); - [SceneViewportEditorOverlayPass](SceneViewportEditorOverlayPass.md) - [Render](Render.md) - [CreateSceneViewportEditorOverlayPass](CreateSceneViewportEditorOverlayPass.md) +- [SceneViewportOverlaySpriteResources](../../SceneViewportOverlaySpriteResources/SceneViewportOverlaySpriteResources.md) diff --git a/docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportGridPass/CreateSceneViewportGridPass.md b/docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportGridPass/CreateSceneViewportGridPass.md index 0b7c431d..30c9d4b9 100644 --- a/docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportGridPass/CreateSceneViewportGridPass.md +++ b/docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportGridPass/CreateSceneViewportGridPass.md @@ -11,12 +11,12 @@ ```cpp std::unique_ptr CreateSceneViewportGridPass( SceneViewportGridPassRenderer& renderer, - const Rendering::Passes::InfiniteGridPassData& data); + const SceneViewportGridPassData& data); ``` ## 作用 -创建一个本帧使用的 Scene View 网格 `RenderPass`，把 `InfiniteGridPassData` 绑定到给定 renderer。 +创建一个本帧使用的 Scene View 网格 `RenderPass`，把 `SceneViewportGridPassData` 绑定到给定 renderer。 ## 当前实现行为 @@ -39,7 +39,7 @@ std::unique_ptr CreateSceneViewportGridPass( 典型调用点是 [ViewportHostService](../../ViewportHostService/ViewportHostService.md)： -1. 先通过 `BuildSceneViewportGridPassData(...)` 组装 `InfiniteGridPassData` +1. 先通过 `BuildSceneViewportGridPassData(...)` 组装 `SceneViewportGridPassData` 2. 再经由 [SceneViewportRenderPlan](../../SceneViewportRenderPlan/SceneViewportRenderPlan.md) 的 `SceneViewportGridPassFactory` 3. 最终把结果挂进 `plan.postScenePasses` @@ -48,4 +48,5 @@ std::unique_ptr CreateSceneViewportGridPass( - [SceneViewportGridPass](SceneViewportGridPass.md) - [Render](Render.md) - [Shutdown](Shutdown.md) +- [SceneViewportGridPassData](../../SceneViewportPassSpecs/SceneViewportGridPassData.md) - [SceneViewportRenderPlan](../../SceneViewportRenderPlan/SceneViewportRenderPlan.md) diff --git a/docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportGridPass/Render.md b/docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportGridPass/Render.md index 7fbe28e0..6c095b58 100644 --- a/docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportGridPass/Render.md +++ b/docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportGridPass/Render.md @@ -12,24 +12,28 @@ bool Render( const Rendering::RenderContext& renderContext, const Rendering::RenderSurface& surface, - const Rendering::Passes::InfiniteGridPassData& data); + const SceneViewportGridPassData& data); ``` ## 作用 -执行 Scene View 无限网格绘制，把一份 `InfiniteGridPassData` 转交给底层 `BuiltinInfiniteGridPass`。 +执行 Scene View 无限网格绘制，把一份 `SceneViewportGridPassData` 转交给底层 `BuiltinInfiniteGridPass`。 ## 当前实现行为 当前实现本身没有额外逻辑，函数体就是： ```cpp -return m_gridPass.Render(renderContext, surface, data); +return m_gridPass.Render( + renderContext, + surface, + ToBuiltinSceneViewportGridPassData(data)); ``` 因此它的语义边界非常明确： - Editor 层不在这里修改网格参数 +- Editor 层会在这里完成“editor wrapper -> runtime builtin 输入”的最后一次转换 - Editor 层不在这里补充 render target 或 clear 行为 - 真正的初始化、shader 选择、绘制和失败条件都由 [BuiltinInfiniteGridPass](../../../../Rendering/Passes/BuiltinInfiniteGridPass/BuiltinInfiniteGridPass.md) 决定 @@ -43,4 +47,6 @@ return m_gridPass.Render(renderContext, surface, data); - [SceneViewportGridPass](SceneViewportGridPass.md) - [Shutdown](Shutdown.md) - [CreateSceneViewportGridPass](CreateSceneViewportGridPass.md) +- [SceneViewportGridPassData](../../SceneViewportPassSpecs/SceneViewportGridPassData.md) +- [ToBuiltinSceneViewportGridPassData](../../SceneViewportPassSpecs/ToBuiltinSceneViewportGridPassData.md) - [BuiltinInfiniteGridPass](../../../../Rendering/Passes/BuiltinInfiniteGridPass/BuiltinInfiniteGridPass.md) diff --git a/docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportGridPass/SceneViewportGridPass.md b/docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportGridPass/SceneViewportGridPass.md index 2014840b..e18010bb 100644 --- a/docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportGridPass/SceneViewportGridPass.md +++ b/docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportGridPass/SceneViewportGridPass.md @@ -14,24 +14,24 @@ - `SceneViewportGridPassRenderer` - `CreateSceneViewportGridPass(...)` -这样 `ViewportHostService` 在组装 [SceneViewportRenderPlan](../../SceneViewportRenderPlan/SceneViewportRenderPlan.md) 时，可以直接把 Scene View 相机姿态推导出的 `InfiniteGridPassData` 变成一个标准 `RenderPass`。 +这样 `ViewportHostService` 在组装 [SceneViewportRenderPlan](../../SceneViewportRenderPlan/SceneViewportRenderPlan.md) 时，可以直接把 Scene View 相机姿态推导出的 `SceneViewportGridPassData` 变成一个标准 `RenderPass`。 ## 当前实现行为 按 `SceneViewportGridPass.cpp` 的当前实现： - `SceneViewportGridPassRenderer` 内部只持有一个 `BuiltinInfiniteGridPass m_gridPass` -- [Render](Render.md) 只是把 `renderContext`、`surface` 和 `InfiniteGridPassData` 原样转发给 `m_gridPass.Render(...)` +- [Render](Render.md) 会把 `SceneViewportGridPassData` 先转换成 runtime `InfiniteGridPassData`，再转发给 `m_gridPass.Render(...)` - [Shutdown](Shutdown.md) 只是转发到 `m_gridPass.Shutdown()` - [CreateSceneViewportGridPass](CreateSceneViewportGridPass.md) 会创建一个内部 `SceneViewportGridPass` 对象： - 持有对 `renderer` 的引用 - - 按值保存本帧的 `InfiniteGridPassData` + - 按值保存本帧的 `SceneViewportGridPassData` - `GetName()` 固定返回 `"SceneViewportGrid"` ## 当前使用位置 - [SceneViewportRenderPlan](../../SceneViewportRenderPlan/SceneViewportRenderPlan.md) 里的 `SceneViewportGridPassFactory` 负责把 `BuildSceneViewportGridPassData(...)` 的结果转成 `RenderPass` -- [ViewportHostService](../../ViewportHostService/ViewportHostService.md) 当前把这个 factory 绑定到 `CreateSceneViewportGridPass(m_sceneViewportGridRenderer, data)` +- [SceneViewportRenderPassBundle](../../SceneViewportRenderPassBundle/SceneViewportRenderPassBundle.md) 当前把这个 factory 绑定到 `CreateSceneViewportGridPass(m_gridRenderer, data)`，再由 [ViewportHostService](../../ViewportHostService/ViewportHostService.md) 通过 bundle 调用 - `tests/Editor/test_viewport_render_flow_utils.cpp` 的 `BuildSceneViewportRenderPlanCollectsPostSceneAndOverlayPasses` 覆盖了 grid factory 被调用的路径 ## 设计含义 @@ -53,5 +53,8 @@ - [Render](Render.md) - [Shutdown](Shutdown.md) - [CreateSceneViewportGridPass](CreateSceneViewportGridPass.md) +- [SceneViewportGridPassData](../../SceneViewportPassSpecs/SceneViewportGridPassData.md) +- [ToBuiltinSceneViewportGridPassData](../../SceneViewportPassSpecs/ToBuiltinSceneViewportGridPassData.md) - [SceneViewportRenderPlan](../../SceneViewportRenderPlan/SceneViewportRenderPlan.md) +- [SceneViewportRenderPassBundle](../../SceneViewportRenderPassBundle/SceneViewportRenderPassBundle.md) - [BuiltinInfiniteGridPass](../../../../Rendering/Passes/BuiltinInfiniteGridPass/BuiltinInfiniteGridPass.md) diff --git a/docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportSelectionOutlinePass/CreateSceneViewportSelectionOutlinePass.md b/docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportSelectionOutlinePass/CreateSceneViewportSelectionOutlinePass.md index 09bd050e..a67c7521 100644 --- a/docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportSelectionOutlinePass/CreateSceneViewportSelectionOutlinePass.md +++ b/docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportSelectionOutlinePass/CreateSceneViewportSelectionOutlinePass.md @@ -13,7 +13,7 @@ std::unique_ptr CreateSceneViewportSelectionOutlinePass( SceneViewportSelectionOutlinePassRenderer& renderer, RHI::RHIResourceView* objectIdTextureView, const std::vector& selectedObjectIds, - const Rendering::Passes::ObjectIdOutlineStyle& style); + const SceneViewportSelectionOutlineStyle& style); ``` ## 作用 @@ -52,4 +52,4 @@ std::unique_ptr CreateSceneViewportSelectionOutlinePass( - [Render](Render.md) - [Shutdown](Shutdown.md) - [SceneViewportRenderPlan](../../SceneViewportRenderPlan/SceneViewportRenderPlan.md) -- [ObjectIdOutlineStyle](../../../../Rendering/Passes/ObjectIdOutlineStyle/ObjectIdOutlineStyle.md) +- [SceneViewportSelectionOutlineStyle](../../SceneViewportPassSpecs/SceneViewportSelectionOutlineStyle.md) diff --git a/docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportSelectionOutlinePass/Render.md b/docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportSelectionOutlinePass/Render.md index 076c848b..f5692610 100644 --- a/docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportSelectionOutlinePass/Render.md +++ b/docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportSelectionOutlinePass/Render.md @@ -14,12 +14,12 @@ bool Render( const Rendering::RenderSurface& surface, RHI::RHIResourceView* objectIdTextureView, const std::vector& selectedObjectIds, - const Rendering::Passes::ObjectIdOutlineStyle& style); + const SceneViewportSelectionOutlineStyle& style); ``` ## 作用 -执行 Scene View 的选中轮廓绘制，把 object-id 纹理、选中对象列表和轮廓样式转交给底层 outline pass。 +执行 Scene View 的选中轮廓绘制，把 object-id 纹理、选中对象列表和 editor 侧轮廓样式转交给底层 outline pass。 ## 当前实现行为 @@ -31,12 +31,12 @@ return m_outlinePass.Render( surface, objectIdTextureView, selectedObjectIds, - style); + ToBuiltinSceneViewportSelectionOutlineStyle(style)); ``` 因此： -- Editor 层不会在这里重新编码 object-id 或调整 outline 样式 +- Editor 层不会在这里重新编码 object-id，但会在最后一步把 editor wrapper 样式转换成 runtime outline 样式 - 资源初始化、shader 选择、绘制与失败条件都由 [BuiltinObjectIdOutlinePass](../../../../Rendering/Passes/BuiltinObjectIdOutlinePass/BuiltinObjectIdOutlinePass.md) 决定 ## 返回值语义 @@ -49,4 +49,6 @@ return m_outlinePass.Render( - [SceneViewportSelectionOutlinePass](SceneViewportSelectionOutlinePass.md) - [Shutdown](Shutdown.md) - [CreateSceneViewportSelectionOutlinePass](CreateSceneViewportSelectionOutlinePass.md) +- [SceneViewportSelectionOutlineStyle](../../SceneViewportPassSpecs/SceneViewportSelectionOutlineStyle.md) +- [ToBuiltinSceneViewportSelectionOutlineStyle](../../SceneViewportPassSpecs/ToBuiltinSceneViewportSelectionOutlineStyle.md) - [BuiltinObjectIdOutlinePass](../../../../Rendering/Passes/BuiltinObjectIdOutlinePass/BuiltinObjectIdOutlinePass.md) diff --git a/docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportSelectionOutlinePass/SceneViewportSelectionOutlinePass.md b/docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportSelectionOutlinePass/SceneViewportSelectionOutlinePass.md index 533d3b9e..c52a22bc 100644 --- a/docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportSelectionOutlinePass/SceneViewportSelectionOutlinePass.md +++ b/docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportSelectionOutlinePass/SceneViewportSelectionOutlinePass.md @@ -18,7 +18,7 @@ - `objectIdTextureView` - `selectedObjectIds` -- `ObjectIdOutlineStyle` +- `SceneViewportSelectionOutlineStyle` 组装成一个标准 `RenderPass`，随后插到 Scene View 的主场景绘制之后执行。 @@ -27,7 +27,7 @@ 按 `SceneViewportSelectionOutlinePass.cpp` 的当前实现： - renderer 内部只持有一个 `BuiltinObjectIdOutlinePass m_outlinePass` -- [Render](Render.md) 原样转发 `renderContext`、`surface`、`objectIdTextureView`、`selectedObjectIds` 与 `style` +- [Render](Render.md) 会把 `SceneViewportSelectionOutlineStyle` 转成 runtime `ObjectIdOutlineStyle` 后，再转发给 `BuiltinObjectIdOutlinePass` - [Shutdown](Shutdown.md) 只调用 `m_outlinePass.Shutdown()` - [CreateSceneViewportSelectionOutlinePass](CreateSceneViewportSelectionOutlinePass.md) 会创建内部 `SceneViewportSelectionOutlinePass`： - 持有对 `renderer` 的引用 @@ -38,7 +38,7 @@ ## 当前使用位置 - [SceneViewportRenderPlan](../../SceneViewportRenderPlan/SceneViewportRenderPlan.md) 的 `SceneViewportSelectionOutlinePassFactory` 会在“有选中对象且 `objectIdShaderView` 可用”时创建这个 pass -- [ViewportHostService](../../ViewportHostService/ViewportHostService.md) 当前把该 factory 绑定到 `CreateSceneViewportSelectionOutlinePass(m_sceneViewportSelectionOutlineRenderer, ...)` +- [SceneViewportRenderPassBundle](../../SceneViewportRenderPassBundle/SceneViewportRenderPassBundle.md) 当前把该 factory 绑定到 `CreateSceneViewportSelectionOutlinePass(m_selectionOutlineRenderer, ...)`，再由 [ViewportHostService](../../ViewportHostService/ViewportHostService.md) 通过 bundle 调用 - `tests/Editor/test_viewport_render_flow_utils.cpp` 覆盖了： - 选中对象存在时 factory 被调用 - `outlineWidthPixels == 2.0f` @@ -64,5 +64,7 @@ - [Shutdown](Shutdown.md) - [CreateSceneViewportSelectionOutlinePass](CreateSceneViewportSelectionOutlinePass.md) - [SceneViewportRenderPlan](../../SceneViewportRenderPlan/SceneViewportRenderPlan.md) +- [SceneViewportRenderPassBundle](../../SceneViewportRenderPassBundle/SceneViewportRenderPassBundle.md) - [BuiltinObjectIdOutlinePass](../../../../Rendering/Passes/BuiltinObjectIdOutlinePass/BuiltinObjectIdOutlinePass.md) -- [ObjectIdOutlineStyle](../../../../Rendering/Passes/ObjectIdOutlineStyle/ObjectIdOutlineStyle.md) +- [SceneViewportSelectionOutlineStyle](../../SceneViewportPassSpecs/SceneViewportSelectionOutlineStyle.md) +- [ToBuiltinSceneViewportSelectionOutlineStyle](../../SceneViewportPassSpecs/ToBuiltinSceneViewportSelectionOutlineStyle.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportChrome/SceneViewportToolCommand.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportChrome/SceneViewportToolCommand.md index 2100da1a..df5d0d83 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportChrome/SceneViewportToolCommand.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportChrome/SceneViewportToolCommand.md @@ -10,7 +10,7 @@ | 字段 | 类型 | 说明 | |------|------|------| -| `targetTool` | `SceneViewportToolMode` | 最终要切换到的工具。默认值是 `Move`。 | +| `targetTool` | `SceneViewportToolMode` | 最终要切换到的工具；默认值是 `Move`。 | | `triggered` | `bool` | 当前帧是否真的形成工具切换命令。 | | `cancelMoveGizmo` | `bool` | 执行前是否需要取消 move gizmo 拖拽。 | | `cancelRotateGizmo` | `bool` | 执行前是否需要取消 rotate gizmo 拖拽。 | @@ -19,7 +19,24 @@ ## 当前语义 - `HasAction()` 当前只返回 `triggered`。 -- 这是轻量命令对象，真正的取消拖拽与工具切换由 [ExecuteSceneViewportToolCommand](ExecuteSceneViewportToolCommand.md) 完成。 +- 这是轻量命令对象；真正的取消拖拽与工具切换由 [ExecuteSceneViewportToolCommand](ExecuteSceneViewportToolCommand.md) 完成。 +- 它通常由 [BuildSceneViewportToolCommand](BuildSceneViewportToolCommand.md) 把两路输入合并出来： + - 工具栏 overlay 点击 + - 键盘 shortcut 动作 + +## 合并规则 + +- overlay 点击会被解释为一次完整工具切换，并默认要求取消三个 gizmo 的当前拖拽。 +- 如果同一帧 shortcut 也触发，shortcut 会覆盖 `targetTool`。 +- 但三类 `cancel*` 标志会保留 overlay 与 shortcut 两侧的并集。 + +## 测试覆盖 + +`tests/Editor/test_scene_viewport_chrome.cpp` 当前验证了： + +- overlay 点击可独立形成完整工具切换。 +- 没有 overlay 点击时可以只使用 shortcut。 +- shortcut 可以覆盖 overlay 的目标工具，同时保留 cancel 标志并集。 ## 相关文档 diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportChrome/SceneViewportToolOverlayResult.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportChrome/SceneViewportToolOverlayResult.md index 44769935..461a264d 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportChrome/SceneViewportToolOverlayResult.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportChrome/SceneViewportToolOverlayResult.md @@ -10,14 +10,30 @@ | 字段 | 类型 | 说明 | |------|------|------| -| `hovered` | `bool` | 鼠标当前是否落在任意工具按钮上。 | -| `clicked` | `bool` | 本帧是否发生工具按钮点击。 | -| `clickedTool` | `SceneViewportToolMode` | 若发生点击，对应被选中的目标工具。默认值是 `Move`。 | +| `hovered` | `bool` | 鼠标当前是否悬停在任意工具按钮上。 | +| `clicked` | `bool` | 本帧是否有工具按钮被点击。 | +| `clickedTool` | `SceneViewportToolMode` | 若 `clicked == true`，表示被点击按钮对应的目标工具；默认值是 `Move`。 | ## 当前语义 -- `SceneViewPanel::Render()` 当前会把 `toolOverlay.hovered` 从 viewport 内容悬停判定里扣掉，避免点工具按钮时误走 Scene View 内容交互。 -- `clickedTool` 只在 `clicked == true` 时有实际语义。 +- 这是 [RenderSceneViewportToolOverlay](RenderSceneViewportToolOverlay.md) 的逐帧结果快照，本身不执行工具切换。 +- 当前 `SceneViewPanel::Render()` 会把 `toolOverlay.hovered` 从 viewport 内容 hover 中扣掉，避免鼠标停在工具栏按钮上时误触发 Scene View 内容交互。 +- `clickedTool` 只有在 `clicked == true` 时才有实际意义；未点击时它只是默认初始化值。 +- 下游的 [BuildSceneViewportToolCommand](BuildSceneViewportToolCommand.md) 会把 overlay 点击解释为一次完整的工具切换，并默认要求取消三个 gizmo 的当前拖拽。 +- 如果同一帧同时还有快捷键动作，下游命令构建会让快捷键覆盖 `clickedTool`，但保留 overlay 与 shortcut 两侧的 cancel 标志并集。 + +## 调用边界 + +- `RenderSceneViewportToolOverlay(...)` 在没有 viewport 区域或没有可用 `ImDrawList` 时会返回默认结果，此时三个字段都保持默认值。 +- 因为工具栏使用的是本帧点击边沿，所以这个结构不适合跨帧持久化。 + +## 测试覆盖 + +`tests/Editor/test_scene_viewport_chrome.cpp` 当前验证了： + +- overlay 点击会被解释为完整工具切换。 +- 没有 overlay 点击时可以只使用快捷键动作。 +- shortcut 可以覆盖 overlay 的目标工具，同时保留两边 cancel 标志的并集。 ## 相关文档 diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportEditorModes/SceneViewportPivotMode.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportEditorModes/SceneViewportPivotMode.md index 12d21959..285c1315 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportEditorModes/SceneViewportPivotMode.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportEditorModes/SceneViewportPivotMode.md @@ -10,16 +10,22 @@ | 值 | 含义 | |------|------| -| `Pivot` | 使用 primary selection 的 pivot 语义。 | -| `Center` | 请求使用 selection center 语义。当前 gizmo frame builder 会基于选中对象中心点聚合 pivot。 | +| `Pivot` | 使用主选对象的 pivot 语义。 | +| `Center` | 请求使用 selection center 语义。 | ## 当前语义 -- `SceneViewPanel` 默认把成员 `m_pivotMode` 初始化为 `Pivot`。 -- `SceneViewportInteractionFrame` 当前把 `Center` 翻译为 `useCenterPivot = true`，再交给 gizmo frame builder 处理。 -- `tests/Editor/test_scene_viewport_interaction_frame.cpp` 当前验证了 `Center` 会把 `SceneViewportToolState::useCenterPivot` 置为 `true`。 +- `SceneViewPanel` 默认把 `m_pivotMode` 初始化为 `Pivot`。 +- `SceneViewportChrome` 会把它作为 toolbar 上的二值切换状态，并显示 `Pivot / Center` 标签。 +- [BuildSceneViewportToolState](../SceneViewportInteractionFrame/BuildSceneViewportToolState.md) 会把 `Center` 翻译成 `useCenterPivot = true`，再交给 gizmo frame builder 处理。 +- 最终 center-pivot 的实际世界位置由 [BuildSceneViewportSelectionGizmoState](../SceneViewportTransformGizmoFrameBuilder/BuildSceneViewportSelectionGizmoState.md) 决定。 + +## 测试覆盖 + +`tests/Editor/test_scene_viewport_interaction_frame.cpp` 当前验证了 `Center` 会把 `SceneViewportToolState::useCenterPivot` 置为 `true`。 ## 相关文档 - [SceneViewportEditorModes](SceneViewportEditorModes.md) +- [SceneViewportInteractionFrame](../SceneViewportInteractionFrame/SceneViewportInteractionFrame.md) - [SceneView Interaction And Gizmo Model](../../../../_guides/Editor/SceneView-Interaction-And-Gizmo-Model.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportEditorModes/SceneViewportToolMode.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportEditorModes/SceneViewportToolMode.md index 6a043258..281a249e 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportEditorModes/SceneViewportToolMode.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportEditorModes/SceneViewportToolMode.md @@ -11,20 +11,27 @@ | 值 | 含义 | |------|------| | `ViewMove` | 视图移动工具。当前 `SceneViewportNavigation` 会允许左键进入 pan drag，且交互解析阶段会禁用 gizmo hit-test。 | -| `Move` | 仅显示 move gizmo。 | -| `Rotate` | 仅显示 rotate gizmo。 | -| `Scale` | 仅显示 scale gizmo。 | +| `Move` | 只显示 move gizmo。 | +| `Rotate` | 只显示 rotate gizmo。 | +| `Scale` | 只显示 scale gizmo。 | | `Transform` | 组合工具。当前 `SceneViewportInteractionFrame` 会同时显示 move / rotate / scale gizmo，并把 scale gizmo 置于 `uniformOnly` 语义。 | ## 当前语义 -- `SceneViewPanel` 默认把成员 `m_toolMode` 初始化为 `Move`。 -- `tests/Editor/test_scene_viewport_interaction_frame.cpp` 当前验证了： - - `Move` 会打开 move gizmo，关闭 rotate / scale gizmo。 - - `Transform` 会同时打开三类 gizmo，并把 `usingTransformTool` 置为 `true`。 +- `SceneViewPanel` 默认把 `m_toolMode` 初始化为 `Move`。 +- `SceneViewportNavigation` 的快捷键解析会把 `Q / W / E / R` 映射到 `ViewMove / Move / Rotate / Scale`。 +- `SceneViewportChrome` 会把它同时用作 toolbar 激活态、按钮 tooltip 和点击命令目标。 +- `SceneViewportInteractionFrame` 会进一步把它翻译成 `usingViewMoveTool`、`usingTransformTool` 以及各类 gizmo 显示开关。 + +## 测试覆盖 + +- `tests/Editor/test_scene_viewport_navigation.cpp` 验证了快捷键到 tool mode 的映射。 +- `tests/Editor/test_scene_viewport_interaction_frame.cpp` 验证了 `Move` 与 `Transform` 会生成不同的 gizmo 可见性组合。 +- `tests/Editor/test_scene_viewport_chrome.cpp` 验证了 toolbar 点击和快捷键命令会正确更新当前 tool mode。 ## 相关文档 - [SceneViewportEditorModes](SceneViewportEditorModes.md) - [SceneViewportNavigation](../SceneViewportNavigation/SceneViewportNavigation.md) +- [SceneViewportInteractionFrame](../SceneViewportInteractionFrame/SceneViewportInteractionFrame.md) - [SceneViewPanel](../../panels/SceneViewPanel/SceneViewPanel.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportEditorModes/SceneViewportTransformSpaceMode.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportEditorModes/SceneViewportTransformSpaceMode.md index fce5aaee..a6eef9b7 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportEditorModes/SceneViewportTransformSpaceMode.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportEditorModes/SceneViewportTransformSpaceMode.md @@ -11,15 +11,21 @@ | 值 | 含义 | |------|------| | `Global` | 使用世界空间轴向。 | -| `Local` | 使用当前 primary selection 的稳定世界旋转作为 gizmo 轴向。 | +| `Local` | 使用当前主选对象的稳定世界旋转作为 gizmo 轴向。 | ## 当前语义 -- `SceneViewPanel` 默认把成员 `m_transformSpaceMode` 初始化为 `Global`。 -- `SceneViewportInteractionFrame` 当前把 `Local` 翻译为 `localSpace = true`，再交给各 gizmo context builder。 -- `tests/Editor/test_scene_viewport_interaction_frame.cpp` 当前验证了 `Local` 会同步进入 `SceneViewportToolState::localSpace` 与 `gizmoFrameOptions.localSpace`。 +- `SceneViewPanel` 默认把 `m_transformSpaceMode` 初始化为 `Global`。 +- `SceneViewportChrome` 当前把它作为 toolbar 上的二值切换状态，并显示 `Global / Local` 标签。 +- [BuildSceneViewportToolState](../SceneViewportInteractionFrame/BuildSceneViewportToolState.md) 会把 `Local` 翻译成 `localSpace = true`，再同步给 gizmo context / frame builder。 +- rotate / scale / move gizmo 是否真的采用局部轴向，最终仍由各自 context 构建和实现逻辑决定。 + +## 测试覆盖 + +`tests/Editor/test_scene_viewport_interaction_frame.cpp` 当前验证了 `Local` 会同步进入 `SceneViewportToolState::localSpace` 和 `gizmoFrameOptions.localSpace`。 ## 相关文档 - [SceneViewportEditorModes](SceneViewportEditorModes.md) +- [SceneViewportInteractionFrame](../SceneViewportInteractionFrame/SceneViewportInteractionFrame.md) - [SceneView Interaction And Gizmo Model](../../../../_guides/Editor/SceneView-Interaction-And-Gizmo-Model.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportEditorOverlayData/SceneViewportEditorOverlayData.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportEditorOverlayData/SceneViewportEditorOverlayData.md index 5a8a8cf6..47e8da89 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportEditorOverlayData/SceneViewportEditorOverlayData.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportEditorOverlayData/SceneViewportEditorOverlayData.md @@ -37,7 +37,8 @@ ## 当前实现行为 - `worldLines` 使用世界空间起点/终点，真正投影与渲染在后续 pass 里完成。 -- `worldSprites` 使用世界坐标、像素尺寸和 `textureKind`，而不是直接持有 `ImTextureID`。 +- `worldSprites` 使用世界坐标、像素尺寸和 `textureKind`，而不是直接持有 `ImTextureID` 或具体文件路径。 +- `textureKind` 只表达逻辑图标种类；真正的资源路径、RGBA 像素与 descriptor set 解析由 [SceneViewportOverlaySpriteResources](../SceneViewportOverlaySpriteResources/SceneViewportOverlaySpriteResources.md) 负责。 - `screenTriangles` 当前主要承载 transform gizmo 的屏幕空间几何。 - `handleRecords` 当前统一覆盖 scene icon 与 transform gizmo 的命中记录。 - `SceneViewportOverlayFrameData::HasOverlayPrimitives()` 会同时检查 `worldLines`、`worldSprites` 与 `screenTriangles`。 @@ -67,4 +68,5 @@ - [SceneViewportOverlayBuilder](../SceneViewportOverlayBuilder/SceneViewportOverlayBuilder.md) - [SceneViewportOverlayHitTester](../SceneViewportOverlayHitTester/SceneViewportOverlayHitTester.md) - [SceneViewportEditorOverlayPass](../Passes/SceneViewportEditorOverlayPass/SceneViewportEditorOverlayPass.md) +- [SceneViewportOverlaySpriteResources](../SceneViewportOverlaySpriteResources/SceneViewportOverlaySpriteResources.md) - [SceneViewportHudOverlay](../SceneViewportHudOverlay/SceneViewportHudOverlay.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportHudOverlay/BuildSceneViewportHudOverlayData.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportHudOverlay/BuildSceneViewportHudOverlayData.md index 9dc44e46..23100378 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportHudOverlay/BuildSceneViewportHudOverlayData.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportHudOverlay/BuildSceneViewportHudOverlayData.md @@ -11,28 +11,52 @@ ```cpp inline SceneViewportHudOverlayData BuildSceneViewportHudOverlayData( const SceneViewportOverlayData& sceneOverlay, - bool showOrientationGizmo = true); + bool showOrientationGizmo = true, + const SceneViewportOverlayFrameData* overlayFrameData = nullptr, + bool showSceneIcons = true); ``` ## 作用 -把一份 `SceneViewportOverlayData` 封装成 HUD overlay 输入。 +把 `SceneViewportOverlayData` 和可选的 overlay frame data 封装成一份 HUD overlay 输入。 -## 当前行为 +## 当前实现行为 -- 直接把 `sceneOverlay` 拷入结果 -- 把 `showOrientationGizmo` 写入结果 +当前实现是纯内联数据封装： -## 关键语义 +- `sceneOverlay` +- `showOrientationGizmo` +- `overlayFrameData` +- `showSceneIcons` -- 这是一个头文件内联 helper，不做额外计算 -- `SceneViewPanel` 当前用它统一组装 hover 判定和最终绘制所需的 HUD 数据 +都会被原样写入结果。 -## 测试覆盖 +它不做额外校验，也不在这里判断最终是否可见；那部分交给 [HasVisibleElements](HasVisibleElements.md)。 -`tests/Editor/test_scene_viewport_overlay_renderer.cpp` 的 `BuildSceneViewportHudOverlayDataTracksVisibilityIntent` 当前验证了默认可见和显式隐藏两条路径。 +## 当前语义 + +- 默认调用会打开 orientation gizmo +- 默认不绑定 `overlayFrameData` +- 如果传入 `overlayFrameData` 且 `showSceneIcons == true`，那么即便 `showOrientationGizmo == false`，HUD 仍可能因为 scene icon 而可见 + +## 测试锚点 + +- `BuildSceneViewportHudOverlayDataTracksVisibilityIntent` +- `BuildSceneViewportHudOverlayDataCanExposeSceneIconsWithoutOrientationGizmo` + +## 设计说明 + +把 HUD 输入组装成一个单独 helper，而不是到处直接写结构体字面量，有助于让： + +- interaction frame +- presentation +- 测试 + +都围绕同一种 HUD 数据构造方式工作。 ## 相关文档 - [SceneViewportHudOverlay](SceneViewportHudOverlay.md) - [SceneViewportHudOverlayData](SceneViewportHudOverlayData.md) +- [HasVisibleElements](HasVisibleElements.md) +- [RefreshAndDrawSceneViewportPresentation](../SceneViewportInteractionFrame/RefreshAndDrawSceneViewportPresentation.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportHudOverlay/DrawSceneViewportHudOverlay.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportHudOverlay/DrawSceneViewportHudOverlay.md index 6a7166ca..f3abb9a4 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportHudOverlay/DrawSceneViewportHudOverlay.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportHudOverlay/DrawSceneViewportHudOverlay.md @@ -22,16 +22,66 @@ void DrawSceneViewportHudOverlay( ## 当前实现行为 -- 当 `drawList == nullptr`、`overlay.HasVisibleElements() == false` 或 viewport 矩形无效时，直接返回 -- 否则先裁剪到当前 viewport 区域 -- 当前只会在 `showOrientationGizmo` 为真时调用 `DrawSceneViewportOrientationGizmo(...)` +### 1. 早退门禁 -## 关键语义 +当前会在以下情况直接返回： -- 它当前不画 transform gizmo，也不画 scene icon -- 这是一条纯前端 HUD 绘制链，不会把内容送进 GPU world overlay pass +- `drawList == nullptr` +- `overlay.HasVisibleElements() == false` +- 视口矩形无效 + +### 2. 设置裁剪区域 + +当前会先： + +```cpp +drawList->PushClipRect(viewportMin, viewportMax, true); +``` + +然后在结束时 `PopClipRect()`。 + +### 3. 绘制 scene icon + +若 `overlay.showSceneIcons == true` 且 `overlayFrameData` 中存在 sprite，当前会： + +- 把 `worldSprites` 收集成指针数组 +- 按 `sortDepth` 从大到小排序 +- 用 `ProjectSceneViewportWorldPoint(...)` 投影到屏幕 +- 调用 `DrawSceneViewportSpriteIcon(...)` + +当前 sprite 贴图类型只支持： + +- `Camera` +- `Light` + +### 4. 绘制 orientation gizmo + +若 `overlay.showOrientationGizmo == true`，当前会继续调用： + +- `DrawSceneViewportOrientationGizmo(...)` + +## 当前绘制顺序 + +当前绘制顺序是： + +1. scene icon +2. orientation gizmo + +这意味着 orientation gizmo 会覆盖在 icon 之上。 + +## 设计说明 + +HUD overlay 的绘制路径故意保持非常轻： + +- 不走 GPU world overlay pass +- 不重新构建几何 +- 只消费一份轻量 HUD 数据 + +这让它非常适合承载 orientation gizmo 和固定 screen-space icon 这类前端元素。 ## 相关文档 - [SceneViewportHudOverlay](SceneViewportHudOverlay.md) +- [SceneViewportHudOverlayData](SceneViewportHudOverlayData.md) - [SceneViewportOrientationGizmo](../SceneViewportOrientationGizmo/SceneViewportOrientationGizmo.md) +- [ProjectSceneViewportWorldPoint](../SceneViewportMath/ProjectSceneViewportWorldPoint.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportHudOverlay/HasHit.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportHudOverlay/HasHit.md new file mode 100644 index 00000000..5444a090 --- /dev/null +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportHudOverlay/HasHit.md @@ -0,0 +1,37 @@ +# SceneViewportHudOverlayHitResult::HasHit + +**命名空间**: `XCEngine::Editor` + +**类型**: `method` + +**源文件**: `editor/src/Viewport/SceneViewportHudOverlay.h` + +## 签名 + +```cpp +bool HasHit() const; +``` + +## 作用 + +判断当前 HUD 命中结果是否代表一次有效命中。 + +## 当前实现行为 + +当前实现只有一个判断： + +```cpp +return kind != SceneViewportHudOverlayHitKind::None; +``` + +也就是说，当前 HUD hit 结果是否有效，完全由 `kind` 决定。 + +## 设计说明 + +把这个判断挂到结果结构上，可以让上层交互代码直接按“有没有命中”来分流，而不必反复关心具体枚举值。 + +## 相关文档 + +- [SceneViewportHudOverlayHitResult](SceneViewportHudOverlayHitResult.md) +- [SceneViewportHudOverlayHitKind](SceneViewportHudOverlayHitKind.md) +- [HitTestSceneViewportHudOverlay](HitTestSceneViewportHudOverlay.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportHudOverlay/HasVisibleElements.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportHudOverlay/HasVisibleElements.md new file mode 100644 index 00000000..55810535 --- /dev/null +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportHudOverlay/HasVisibleElements.md @@ -0,0 +1,46 @@ +# SceneViewportHudOverlayData::HasVisibleElements + +**命名空间**: `XCEngine::Editor` + +**类型**: `method` + +**源文件**: `editor/src/Viewport/SceneViewportHudOverlay.h` + +## 签名 + +```cpp +bool HasVisibleElements() const; +``` + +## 作用 + +判断当前 HUD overlay 数据是否真的包含可见元素。 + +## 当前实现行为 + +当前只有在以下条件成立时才返回 `true`： + +- `sceneOverlay.valid == true` +- 并且满足以下二者之一： + - `showOrientationGizmo == true` + - `showSceneIcons == true && overlayFrameData != nullptr && !overlayFrameData->worldSprites.empty()` + +## 当前语义 + +这意味着： + +- 只要 orientation gizmo 打开，HUD 就会被视为可见 +- 即便关闭 orientation gizmo，只要 scene icon 开启且有 sprite 数据，HUD 仍然可见 +- 如果二者都不满足，绘制与 hit-test 都会早退 + +## 测试锚点 + +- `BuildSceneViewportHudOverlayDataTracksVisibilityIntent` +- `BuildSceneViewportHudOverlayDataCanExposeSceneIconsWithoutOrientationGizmo` + +## 相关文档 + +- [SceneViewportHudOverlayData](SceneViewportHudOverlayData.md) +- [BuildSceneViewportHudOverlayData](BuildSceneViewportHudOverlayData.md) +- [DrawSceneViewportHudOverlay](DrawSceneViewportHudOverlay.md) +- [HitTestSceneViewportHudOverlay](HitTestSceneViewportHudOverlay.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportHudOverlay/HitTestSceneViewportHudOverlay.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportHudOverlay/HitTestSceneViewportHudOverlay.md index b5881174..30aa6e89 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportHudOverlay/HitTestSceneViewportHudOverlay.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportHudOverlay/HitTestSceneViewportHudOverlay.md @@ -22,18 +22,47 @@ SceneViewportHudOverlayHitResult HitTestSceneViewportHudOverlay( ## 当前实现行为 -- 当 HUD 不可见或 viewport 矩形无效时，返回空结果 -- 当前只会对 orientation gizmo 做命中测试 -- 命中成功时，返回: - - `kind = SceneViewportHudOverlayHitKind::OrientationAxis` - - `orientationAxis = 命中的具体轴` +### 1. 早退门禁 -## 测试覆盖 +当前会在以下情况直接返回空结果： -`tests/Editor/test_scene_viewport_overlay_renderer.cpp` 的 `HitTestSceneViewportHudOverlaySkipsInvalidOrHiddenOverlay` 当前验证了无效和显式隐藏时会返回空结果。 +- `overlay.HasVisibleElements() == false` +- 视口矩形无效 + +### 2. 仅命中 orientation gizmo + +当前如果 `overlay.showOrientationGizmo == true`，会调用： + +- `HitTestSceneViewportOrientationGizmo(...)` + +若命中某个轴，则返回： + +- `kind = SceneViewportHudOverlayHitKind::OrientationAxis` +- `orientationAxis = 命中的具体轴` + +## 当前边界 + +- scene icon 当前不参与 HUD hit-test +- 该函数只产生命中结果，不直接执行任何交互副作用 + +真正的“命中后做什么”，当前交给： + +- [SceneViewportInteractionResolver](../SceneViewportInteractionResolver/SceneViewportInteractionResolver.md) + +## 测试锚点 + +`HitTestSceneViewportHudOverlaySkipsInvalidOrHiddenOverlay` 验证了： + +- HUD overlay 无效时会返回空结果 +- HUD 被显式隐藏时也会返回空结果 + +## 设计说明 + +当前 HUD hit-test 只聚焦 orientation gizmo，是一个很明确的产品边界：这部分是 Scene View HUD 中最重要、最稳定的交互元素，而 scene icon 目前仍只承担显示职责。 ## 相关文档 - [SceneViewportHudOverlay](SceneViewportHudOverlay.md) +- [SceneViewportHudOverlayHitKind](SceneViewportHudOverlayHitKind.md) - [SceneViewportHudOverlayHitResult](SceneViewportHudOverlayHitResult.md) - [SceneViewportInteractionResolver](../SceneViewportInteractionResolver/SceneViewportInteractionResolver.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportHudOverlay/SceneViewportHudOverlay.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportHudOverlay/SceneViewportHudOverlay.md index 4c29c9f6..6f1e4b17 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportHudOverlay/SceneViewportHudOverlay.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportHudOverlay/SceneViewportHudOverlay.md @@ -6,68 +6,92 @@ **源文件**: `editor/src/Viewport/SceneViewportHudOverlay.h` -**描述**: 定义 Scene View 前端 HUD overlay 的轻量数据结构、orientation gizmo 绘制入口以及对应的鼠标命中结果。 +**描述**: 定义 Scene View 前端 HUD overlay 的轻量数据结构、绘制入口以及命中结果，负责 orientation gizmo 与 scene icon 的前端可视化层。 ## 概览 -`SceneViewportHudOverlay` 解决的是 Scene View 里“固定贴在 ImGui 前端的一层 HUD 交互”。 +`SceneViewportHudOverlay` 处理的是贴在 Scene View 前端的 HUD 层，而不是 GPU 世界 overlay pass。 -和 [SceneViewportEditorOverlayPass](../Passes/SceneViewportEditorOverlayPass/SceneViewportEditorOverlayPass.md) 的 GPU 世界 overlay 不同，这里处理的是: +它和 [SceneViewportEditorOverlayPass](../Passes/SceneViewportEditorOverlayPass/SceneViewportEditorOverlayPass.md) 的差别很重要： -- orientation gizmo 的可见性开关 -- orientation gizmo 的 ImGui draw-list 绘制 -- orientation gizmo 的鼠标命中 +- Editor overlay pass + - 偏世界空间 / GPU 叠加 +- HUD overlay + - 偏 `ImGui` 前端 / 屏幕空间 UI -当前这层 HUD 不再承担 move / rotate / scale gizmo、scene icon 或 scene line 的主绘制链路；这些内容已经分别进入 editor overlay handle 命中链和 GPU overlay pass。 +当前 HUD overlay 主要承担两件事： -## 公开类型与函数 +- orientation gizmo 的显示与命中 +- scene icon sprite 的前端绘制 + +## 当前公开成员 | 成员 | 说明 | |------|------| -| `SceneViewportHudOverlayHitKind` | 当前 HUD 命中种类枚举。 | -| [SceneViewportHudOverlayHitResult](SceneViewportHudOverlayHitResult.md) | HUD 命中结果；当前主要承载 orientation axis。 | -| [SceneViewportHudOverlayData](SceneViewportHudOverlayData.md) | 一帧 HUD overlay 的输入数据。 | -| [BuildSceneViewportHudOverlayData](BuildSceneViewportHudOverlayData.md) | 从 `SceneViewportOverlayData` 组装 HUD 数据。 | -| [DrawSceneViewportHudOverlay](DrawSceneViewportHudOverlay.md) | 把 HUD 绘制到 `ImDrawList`。 | -| [HitTestSceneViewportHudOverlay](HitTestSceneViewportHudOverlay.md) | 把鼠标位置解析成 HUD 命中结果。 | +| [SceneViewportHudOverlayHitKind](SceneViewportHudOverlayHitKind.md) | HUD 命中类型枚举。 | +| [SceneViewportHudOverlayHitResult](SceneViewportHudOverlayHitResult.md) | HUD 命中结果。 | +| [SceneViewportHudOverlayData](SceneViewportHudOverlayData.md) | 一帧 HUD overlay 输入数据。 | +| [BuildSceneViewportHudOverlayData](BuildSceneViewportHudOverlayData.md) | 组装 HUD 输入数据。 | +| [DrawSceneViewportHudOverlay](DrawSceneViewportHudOverlay.md) | 在 `ImDrawList` 上绘制 HUD。 | +| [HitTestSceneViewportHudOverlay](HitTestSceneViewportHudOverlay.md) | 解析鼠标对 HUD 的命中。 | ## 当前实现行为 -按 `SceneViewportHudOverlay.cpp` 的实现: +按 `SceneViewportHudOverlay.cpp` 当前实现： -- HUD 只在 viewport 矩形有效时工作 +- HUD 只有在视口矩形有效时才工作 - 绘制时会先 `PushClipRect(viewportMin, viewportMax, true)` -- 当前唯一的可见 HUD 元素是 orientation gizmo -- 命中测试当前也只会返回 `OrientationAxis` +- 当前绘制层包含两类元素： + - 可选的 scene icon sprite + - 可选的 orientation gizmo +- scene icon 会按 `sortDepth` 从大到小排序后绘制 +- 当前命中测试仍只覆盖 orientation gizmo -## 当前在 `SceneViewPanel` 中的使用方式 +## 为什么 scene icon 只绘制不命中 -`SceneViewPanel` 当前会在两条链路里使用它: +当前 HUD 层里的 scene icon 主要承担“识别与定位”的视觉作用，而不是交互主入口。 -- 交互判定阶段: - - 先 `BuildSceneViewportHudOverlayData(overlay)` - - 再交给 [SceneViewportInteractionResolver](../SceneViewportInteractionResolver/SceneViewportInteractionResolver.md) 参与命中合并 -- 最终绘制阶段: - - 调用 [DrawSceneViewportHudOverlay](DrawSceneViewportHudOverlay.md) - - 只补一层 ImGui HUD / orientation gizmo +真正的 Scene View 点击主链目前还是： -## 与测试的对应关系 +- object-id picking +- overlay handle hit-test +- HUD orientation gizmo hit-test + +scene icon 如果以后要加入可点击语义，可以在不改 HUD 绘制总体结构的前提下单独扩展 hit-test。 + +## 与交互链的关系 + +当前它主要挂在两条链路里： + +### 交互解析阶段 + +- `SceneViewportInteractionFrameState::hudOverlay` +- [SceneViewportInteractionResolver](../SceneViewportInteractionResolver/SceneViewportInteractionResolver.md) + +### presentation 阶段 + +- [RefreshAndDrawSceneViewportPresentation](../SceneViewportInteractionFrame/RefreshAndDrawSceneViewportPresentation.md) + +这说明 HUD overlay 不只是“画一下”，它还是 Scene View 交互命中链的一部分。 + +## 测试锚点 `tests/Editor/test_scene_viewport_overlay_renderer.cpp` 当前验证了： -- [BuildSceneViewportHudOverlayData](BuildSceneViewportHudOverlayData.md) 会正确追踪显示 / 隐藏意图。 -- [HitTestSceneViewportHudOverlay](HitTestSceneViewportHudOverlay.md) 会在 overlay 无效或 HUD 被隐藏时直接跳过命中。 -- 与 HUD 共用的 [ProjectSceneViewportWorldPoint](../SceneViewportMath/ProjectSceneViewportWorldPoint.md) 投影规则能把场景中心稳定映射到视口中心。 +- `BuildSceneViewportHudOverlayData(...)` 会正确追踪显示/隐藏意图 +- 即便关闭 orientation gizmo，只要存在 scene icon sprite，HUD 仍然可见 +- `HitTestSceneViewportHudOverlay(...)` 会在 overlay 无效或 HUD 隐藏时直接返回空结果 ## 当前限制 -- 当前 HUD 只有 orientation gizmo，没有 transform gizmo 或 scene icon -- 命中结果只表达“点中了哪个朝向轴”，不直接执行相机对齐 -- 真正的相机对齐仍由 `ViewportHostService::AlignSceneViewToOrientationAxis(...)` 在更上层调用链中完成 +- HUD hit-test 目前只覆盖 orientation gizmo +- scene icon 目前只参与绘制，不参与 HUD hit-test +- 真正的相机对齐动作仍由更上层调用链负责执行 ## 相关文档 - [SceneViewportOrientationGizmo](../SceneViewportOrientationGizmo/SceneViewportOrientationGizmo.md) - [SceneViewportInteractionResolver](../SceneViewportInteractionResolver/SceneViewportInteractionResolver.md) - [SceneViewportEditorOverlayPass](../Passes/SceneViewportEditorOverlayPass/SceneViewportEditorOverlayPass.md) +- [SceneViewportEditorOverlayData](../SceneViewportEditorOverlayData/SceneViewportEditorOverlayData.md) - [SceneViewPanel](../../panels/SceneViewPanel/SceneViewPanel.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportHudOverlay/SceneViewportHudOverlayData.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportHudOverlay/SceneViewportHudOverlayData.md index e1ece511..dab4791d 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportHudOverlay/SceneViewportHudOverlayData.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportHudOverlay/SceneViewportHudOverlayData.md @@ -6,20 +6,47 @@ **源文件**: `editor/src/Viewport/SceneViewportHudOverlay.h` -## 字段 +## 定义 -| 字段 | 类型 | 说明 | -|------|------|------| -| `sceneOverlay` | `SceneViewportOverlayData` | orientation gizmo 绘制所需的相机/投影输入。 | -| `showOrientationGizmo` | `bool` | 当前是否允许绘制和命中 orientation gizmo。 | +```cpp +struct SceneViewportHudOverlayData { + SceneViewportOverlayData sceneOverlay = {}; + bool showOrientationGizmo = true; + bool showSceneIcons = true; + const SceneViewportOverlayFrameData* overlayFrameData = nullptr; -## 当前语义 + bool HasVisibleElements() const; +}; +``` -- [HasVisibleElements](SceneViewportHudOverlay.md) 当前等价于: - - `sceneOverlay.valid && showOrientationGizmo` -- 因此这份数据既承载“相机姿态是否有效”，也承载“HUD 是否应该显示” +## 作用 + +描述一帧 Scene View HUD overlay 所需的全部输入。 + +## 字段语义 + +| 字段 | 说明 | +|------|------| +| `sceneOverlay` | HUD 数学和 orientation gizmo 绘制所需的相机姿态数据。 | +| `showOrientationGizmo` | 是否允许显示与命中 orientation gizmo。 | +| `showSceneIcons` | 是否允许绘制 scene icon。 | +| `overlayFrameData` | scene icon sprite 的非拥有来源；可为空。 | + +## 当前可见性语义 + +当前 [HasVisibleElements](HasVisibleElements.md) 会把“这一帧 HUD 到底是否可见”收口到统一规则里。 + +这意味着该结构不仅描述输入，还隐含了 HUD 是否值得绘制/命中的门禁条件。 + +## 生命周期语义 + +`overlayFrameData` 是非拥有指针，只适合在当前帧立即消费。 + +这很合理，因为 Scene View overlay frame 本来就由更上层缓存系统维护，HUD 这里只需要借用。 ## 相关文档 - [SceneViewportHudOverlay](SceneViewportHudOverlay.md) - [BuildSceneViewportHudOverlayData](BuildSceneViewportHudOverlayData.md) +- [HasVisibleElements](HasVisibleElements.md) +- [SceneViewportHudOverlayHitResult](SceneViewportHudOverlayHitResult.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportHudOverlay/SceneViewportHudOverlayHitKind.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportHudOverlay/SceneViewportHudOverlayHitKind.md new file mode 100644 index 00000000..5f85c755 --- /dev/null +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportHudOverlay/SceneViewportHudOverlayHitKind.md @@ -0,0 +1,42 @@ +# SceneViewportHudOverlayHitKind + +**命名空间**: `XCEngine::Editor` + +**类型**: `enum class` + +**源文件**: `editor/src/Viewport/SceneViewportHudOverlay.h` + +## 定义 + +```cpp +enum class SceneViewportHudOverlayHitKind : uint8_t { + None = 0, + OrientationAxis +}; +``` + +## 作用 + +表示 Scene View HUD overlay 当前命中的元素类别。 + +## 当前枚举语义 + +| 枚举值 | 含义 | +|------|------| +| `None` | 当前没有命中任何 HUD 元素。 | +| `OrientationAxis` | 命中了 orientation gizmo 的某个轴。 | + +## 当前实现边界 + +目前 HUD hit-test 只支持 orientation gizmo，因此这个枚举当前只有一个真正的“命中”类别。 + +这也反映了当前产品边界： + +- scene icon 会参与绘制 +- 但 scene icon 目前不参与 HUD hit-test + +## 相关文档 + +- [SceneViewportHudOverlay](SceneViewportHudOverlay.md) +- [SceneViewportHudOverlayHitResult](SceneViewportHudOverlayHitResult.md) +- [HitTestSceneViewportHudOverlay](HitTestSceneViewportHudOverlay.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportHudOverlay/SceneViewportHudOverlayHitResult.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportHudOverlay/SceneViewportHudOverlayHitResult.md index 24c8e30c..810bf173 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportHudOverlay/SceneViewportHudOverlayHitResult.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportHudOverlay/SceneViewportHudOverlayHitResult.md @@ -6,19 +6,48 @@ **源文件**: `editor/src/Viewport/SceneViewportHudOverlay.h` -## 字段 +## 定义 -| 字段 | 类型 | 说明 | +```cpp +struct SceneViewportHudOverlayHitResult { + SceneViewportHudOverlayHitKind kind = SceneViewportHudOverlayHitKind::None; + SceneViewportOrientationAxis orientationAxis = SceneViewportOrientationAxis::None; + + bool HasHit() const; +}; +``` + +## 作用 + +表示一次 HUD overlay 命中测试的结果。 + +## 字段语义 + +| 字段 | 默认值 | 说明 | |------|------|------| -| `kind` | `SceneViewportHudOverlayHitKind` | 当前命中种类；默认是 `None`。 | -| `orientationAxis` | `SceneViewportOrientationAxis` | 当命中 orientation gizmo 时记录具体轴向。 | +| `kind` | `None` | 当前命中种类。 | +| `orientationAxis` | `SceneViewportOrientationAxis::None` | 命中 orientation gizmo 时记录具体轴向。 | -## 当前语义 +## 当前实现语义 -- `HasHit()` 当前只检查 `kind != None` -- 当前实现里，唯一有效的命中种类是 `OrientationAxis` +当前 HUD hit-test 只支持 orientation gizmo，因此： + +- `kind == OrientationAxis` 时，`orientationAxis` 才有业务意义 +- `kind == None` 时，`orientationAxis` 的默认值只是占位 + +## 便利方法 + +| 方法 | 说明 | +|------|------| +| [HasHit](HasHit.md) | 判断当前是否存在有效命中。 | + +## 调用链位置 + +当前 [HitTestSceneViewportHudOverlay](HitTestSceneViewportHudOverlay.md) 会生成它，然后由 [SceneViewportInteractionResolver](../SceneViewportInteractionResolver/SceneViewportInteractionResolver.md) 继续把它并入最终交互结果。 ## 相关文档 - [SceneViewportHudOverlay](SceneViewportHudOverlay.md) +- [SceneViewportHudOverlayHitKind](SceneViewportHudOverlayHitKind.md) - [HitTestSceneViewportHudOverlay](HitTestSceneViewportHudOverlay.md) +- [HasHit](HasHit.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportInteractionFrame/BuildSceneViewportFrameGeometry.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportInteractionFrame/BuildSceneViewportFrameGeometry.md index 6adedd23..bedad60b 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportInteractionFrame/BuildSceneViewportFrameGeometry.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportInteractionFrame/BuildSceneViewportFrameGeometry.md @@ -1,6 +1,7 @@ # BuildSceneViewportFrameGeometry -根据 viewport 矩形和绝对鼠标位置构建当前帧几何输入。 +根据 viewport 几何和绝对鼠标位置，构建当前帧的局部几何输入。 + ```cpp SceneViewportFrameGeometry BuildSceneViewportFrameGeometry( const ImVec2& viewportSize, @@ -10,19 +11,23 @@ SceneViewportFrameGeometry BuildSceneViewportFrameGeometry( ## 参数 -- `viewportSize` - 当前 viewport 的可用尺寸。 -- `viewportMin` - 当前 viewport 左上角的绝对屏幕坐标。 -- `absoluteMousePosition` - 当前鼠标的绝对屏幕坐标。 +- `viewportSize`：当前 viewport 的可用尺寸。 +- `viewportMin`：当前 viewport 左上角的绝对屏幕坐标。 +- `absoluteMousePosition`：当前鼠标的绝对屏幕坐标。 ## 当前语义 -- `viewportSize` 会直接转成 `Math::Vector2`。 +- `viewportSize` 会直接转成 `Math::Vector2` 写入 `SceneViewportFrameGeometry::viewportSize`。 - `localMousePosition` 通过 `absoluteMousePosition - viewportMin` 计算。 -- 这里不做裁剪或悬停判断；即使鼠标已经跑出 viewport 外，本地坐标也会照常计算。 +- 这里不做 clamp、hover 判断或命中测试；即使鼠标已经跑出 viewport 外，局部坐标也会照常计算。 + +## 调用位置 + +当前 `SceneViewPanel::Render()` 会在 gizmo refresh、interaction resolve 和 presentation 尾段之前先构造这份几何快照，并在同一帧内复用。 ## 测试覆盖 -`tests/Editor/test_scene_viewport_interaction_frame.cpp` 当前验证了本地鼠标坐标的偏移计算。 +`tests/Editor/test_scene_viewport_interaction_frame.cpp` 当前验证了 viewport 尺寸和局部鼠标偏移的计算结果。 ## 相关文档 diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportInteractionFrame/BuildSceneViewportInteractionFrameState.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportInteractionFrame/BuildSceneViewportInteractionFrameState.md index 71d74299..bf547f6c 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportInteractionFrame/BuildSceneViewportInteractionFrameState.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportInteractionFrame/BuildSceneViewportInteractionFrameState.md @@ -1,6 +1,7 @@ # BuildSceneViewportInteractionFrameState 组装当前 Scene View 单帧交互状态。 + ```cpp SceneViewportInteractionFrameState BuildSceneViewportInteractionFrameState( IEditorContext& context, @@ -16,37 +17,40 @@ SceneViewportInteractionFrameState BuildSceneViewportInteractionFrameState( ## 参数 -- `context` - 当前 editor 上下文。 -- `viewportHostService` - 当前 Scene View overlay 和 gizmo 数据来源。 -- `hasInteractiveViewport` - 当前是否真的有可交互 viewport。 -- `geometry` - 当前帧视口尺寸和本地鼠标几何。 -- `gizmoFrameOptions` - 当前 gizmo frame 刷新配置。 -- `moveGizmo` / `rotateGizmo` / `scaleGizmo` - 三类 gizmo 实例。 -- `emptyOverlayFrameData` - 非交互 viewport 时使用的空 overlay frame。 +- `context`：当前 editor 上下文，会转发给 gizmo refresh 路径。 +- `viewportHostService`：当前 Scene View overlay 与 editor overlay frame data 的来源，同时也是 gizmo overlay submission 的写入目标。 +- `hasInteractiveViewport`：这帧是否真的存在可交互 viewport 区域。 +- `geometry`：当前帧的 viewport 尺寸和局部鼠标坐标。 +- `gizmoFrameOptions`：当前工具模式翻译后的 gizmo 刷新配置。 +- `moveGizmo / rotateGizmo / scaleGizmo`：三个实际参与刷新的 gizmo 实例。 +- `emptyOverlayFrameData`：非交互 viewport 时回退使用的空 overlay frame 数据。 ## 当前语义 -- 如果 `hasInteractiveViewport == false`： - - 会调用 `CancelSceneViewportTransformGizmoFrame(...)` - - `overlayFrameData` 回退到 `emptyOverlayFrameData` - - 返回的 `overlay`、`activeGizmoKind` 和 `gizmoActive` 都保持空状态 -- 如果存在交互视口： - - 从 `viewportHostService` 读取当前 `SceneViewOverlayData` - - 调用 `RefreshAndSubmitSceneViewportTransformGizmoFrame(...)` - - 记录最新的 frame state、overlay submission 和 HUD overlay - - `overlayFrameData` 改为 host service 当前返回的 editor overlay frame data +- 返回值里的 `overlayFrameData` 始终是非拥有指针，不会拷贝底层 overlay frame 数据。 +- `hasInteractiveViewport == false` 时： + - 会调用 `CancelSceneViewportTransformGizmoFrame(...)`，让当前帧不再保留旧的 gizmo 拖拽状态。 + - `overlayFrameData` 指向 `emptyOverlayFrameData`。 + - `overlay`、`activeGizmoKind`、`gizmoActive` 都保持默认空值。 + - `hudOverlay` 由空 `overlay` 计算得到。 +- `hasInteractiveViewport == true` 时： + - 先从 `viewportHostService.GetSceneViewOverlayData()` 读取当前 Scene View overlay。 + - 再调用 `RefreshAndSubmitSceneViewportTransformGizmoFrame(...)`，同步得到新的 `gizmoFrameState` 和 `overlaySubmission`。 + - `overlayFrameData` 改为指向 `viewportHostService.GetSceneViewEditorOverlayFrameData(context)` 返回对象。 + - `activeGizmoKind` 与 `gizmoActive` 来自这次 gizmo overlay submission，而不是单独再做一次查询。 + - `hudOverlay` 始终根据本次读取到的 `overlay` 重新构建。 -## 真实使用位置 +## 调用位置 -- `SceneViewPanel::Render()` 当前会在解析 hover interaction 之前调用这里，先把 overlay、HUD 和 gizmo frame 刷新到一致状态。 +当前 `SceneViewPanel::Render()` 会在 interaction resolve 之前调用这里，先把 overlay、gizmo frame 和 HUD 相关数据收口成一个可复用的帧快照。 ## 测试覆盖 -`tests/Editor/test_scene_viewport_interaction_frame.cpp` 当前覆盖了交互/非交互两条主要路径。 +`tests/Editor/test_scene_viewport_interaction_frame.cpp` 当前覆盖了交互 / 非交互两条主要路径，并验证了 host overlay 与 submission 的转发结果。 ## 相关文档 - [SceneViewportInteractionFrame](SceneViewportInteractionFrame.md) - [SceneViewportInteractionFrameState](SceneViewportInteractionFrameState.md) - [BuildSceneViewportInteractionResolveRequest](BuildSceneViewportInteractionResolveRequest.md) -- [SceneViewportInteractionResolver](../SceneViewportInteractionResolver/SceneViewportInteractionResolver.md) +- [RefreshAndSubmitSceneViewportTransformGizmoFrame](../SceneViewportTransformGizmoCoordinator/RefreshAndSubmitSceneViewportTransformGizmoFrame.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportInteractionFrame/BuildSceneViewportInteractionResolveRequest.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportInteractionFrame/BuildSceneViewportInteractionResolveRequest.md index c0026110..e9a90d2b 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportInteractionFrame/BuildSceneViewportInteractionResolveRequest.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportInteractionFrame/BuildSceneViewportInteractionResolveRequest.md @@ -1,6 +1,7 @@ # BuildSceneViewportInteractionResolveRequest -把当前帧状态和视口几何打包成 interaction resolver 输入。 +把当前帧状态和视口几何打包成 `SceneViewportInteractionResolver` 的输入请求。 + ```cpp SceneViewportInteractionResolveRequest BuildSceneViewportInteractionResolveRequest( const SceneViewportInteractionFrameState& frameState, @@ -12,14 +13,19 @@ SceneViewportInteractionResolveRequest BuildSceneViewportInteractionResolveReque ## 当前语义 -- 它不会重新做命中测试，只负责组装请求对象。 -- `overlayFrameData` 和 `hudOverlay` 都直接引用 `frameState` 里的现成结果。 +- 这个 helper 只负责组装请求对象，不会重新做命中测试。 +- `overlayFrameData` 和 `hudOverlay` 都直接引用 `frameState` 里已经准备好的现成结果，不会深拷贝底层数据。 - `viewportSize` 和 `localMousePosition` 直接复用 `geometry`。 -- `viewportMin / viewportMax / absoluteMousePosition` 则为 HUD hit-test 提供绝对坐标输入。 +- `viewportMin / viewportMax / absoluteMousePosition` 以 ImGui 绝对坐标形式透传，供 HUD hit-test 和屏幕空间判断使用。 + +## 生命周期边界 + +- 因为返回值里包含对 `frameState.overlayFrameData` 和 `frameState.hudOverlay` 的非拥有引用，所以它应当只在当前帧、且在 `frameState` 仍然有效时立即消费。 +- 这个 helper 不校验 viewport 矩形是否合法，也不对鼠标坐标做 clamp；调用前的交互门禁由 [CanResolveSceneViewportInteraction](../SceneViewportNavigation/CanResolveSceneViewportInteraction.md) 负责。 ## 测试覆盖 -`tests/Editor/test_scene_viewport_interaction_frame.cpp` 当前验证了 request 字段复制是否正确。 +`tests/Editor/test_scene_viewport_interaction_frame.cpp` 当前验证了 request 字段复制与指针转发是否正确。 ## 相关文档 diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportInteractionFrame/RefreshAndDrawSceneViewportPresentation.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportInteractionFrame/RefreshAndDrawSceneViewportPresentation.md index 6578e42b..cc956185 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportInteractionFrame/RefreshAndDrawSceneViewportPresentation.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportInteractionFrame/RefreshAndDrawSceneViewportPresentation.md @@ -1,6 +1,7 @@ # RefreshAndDrawSceneViewportPresentation 刷新 Scene View 帧尾段的 transform gizmo presentation，并绘制 HUD overlay。 + ```cpp void RefreshAndDrawSceneViewportPresentation( const SceneViewportPresentationRequest& request); @@ -8,23 +9,33 @@ void RefreshAndDrawSceneViewportPresentation( ## 当前语义 -- 如果 `request.IsValid() == false` 或 `request.hasInteractiveViewport == false`，直接返回。 -- 否则会先从 `request.viewportHostService` 读取当前 `SceneViewportOverlayData`。 -- 然后调用 `RefreshAndSubmitSceneViewportTransformGizmoFrame(...)`，把最新 overlay、viewport geometry 和 gizmo frame options 再次提交给 transform gizmo coordinator。 -- 最后调用 `DrawSceneViewportHudOverlay(...)`，把同一份 overlay 转成 HUD overlay 并画到 `request.drawList` 上。 +- 这是 `SceneViewPanel` 在提交 `SceneViewportInput` 之后执行的尾段 helper。 +- `request.IsValid() == false` 或 `request.hasInteractiveViewport == false` 时会直接返回。 +- 进入主路径后，函数会： + - 从 `request.viewportHostService` 再读一次当前 `SceneViewportOverlayData` + - 用 `request.geometry` 和 `request.gizmoFrameOptions` 再跑一次 `RefreshAndSubmitSceneViewportTransformGizmoFrame(...)` + - 用 `request.overlayFrameData` 构造 HUD 数据并调用 `DrawSceneViewportHudOverlay(...)` -## 关键边界 +## 当前 HUD 行为 -- 这是 `SceneViewPanel` 在提交 `SceneViewportInput` 之后的最终 presentation helper，用来让 gizmo overlay 跟上最新相机状态。 -- 它不重新做 interaction resolve，也不处理 gizmo begin / update / end 生命周期命令。 -- `drawList` 允许为空；当前实现仍会刷新 gizmo frame，只是 HUD overlay 绘制阶段会直接 no-op。 +- 这里传给 `BuildSceneViewportHudOverlayData(...)` 的是： + - 最新 `overlay` + - `showOrientationGizmo = true` + - `request.overlayFrameData` +- 也就是说，presentation 尾段当前既能绘制 orientation gizmo，也能在存在 `overlayFrameData` 时绘制 scene icon。 + +## 边界说明 + +- 它不会重新做 interaction resolve。 +- 它不会替代 [ExecuteSceneViewportTransformGizmoLifecycleCommand](../SceneViewportTransformGizmoCoordinator/ExecuteSceneViewportTransformGizmoLifecycleCommand.md)；gizmo begin / update / end 仍由 `SceneViewPanel` 明确推进。 +- 因为这里会再次刷新 gizmo overlay，所以它更接近“presentation 收尾”而不是“交互前置准备”。 ## 测试覆盖 -`tests/Editor/test_scene_viewport_interaction_frame.cpp` 当前覆盖了： +`tests/Editor/test_scene_viewport_interaction_frame.cpp` 当前验证了： -- 非交互 viewport 时不会提交 gizmo overlay -- 交互 viewport 且 `drawList == nullptr` 时仍会刷新 gizmo frame +- 非交互 viewport 时不会提交 gizmo overlay。 +- 交互 viewport 且 `drawList == nullptr` 时，仍会刷新并提交 gizmo frame。 ## 相关文档 diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportInteractionFrame/SceneViewportFrameGeometry.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportInteractionFrame/SceneViewportFrameGeometry.md index 9c71f4e3..bd9a340d 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportInteractionFrame/SceneViewportFrameGeometry.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportInteractionFrame/SceneViewportFrameGeometry.md @@ -6,20 +6,28 @@ **源文件**: `editor/src/Viewport/SceneViewportInteractionFrame.h` -**描述**: 描述当前 Scene View 单帧交互使用的局部几何输入。 +**说明**: 描述当前 Scene View 单帧交互使用的局部几何输入。 ## 字段 -| 字段 | 说明 | -|------|------| -| `viewportSize` | 当前 viewport 的本地尺寸。 | -| `localMousePosition` | 鼠标相对于 viewport 左上角的本地坐标。 | +| 字段 | 类型 | 说明 | +|------|------|------| +| `viewportSize` | `Math::Vector2` | 当前 viewport 的本地尺寸。 | +| `localMousePosition` | `Math::Vector2` | 鼠标相对 viewport 左上角的局部坐标。 | ## 当前语义 - 这是 [BuildSceneViewportFrameGeometry](BuildSceneViewportFrameGeometry.md) 的输出结构。 - 它把 ImGui 的绝对屏幕坐标输入翻译成后续 gizmo refresh、interaction resolve 和 HUD hit-test 都能直接消费的局部几何数据。 -- `SceneViewPanel` 会把它同时传给 gizmo frame 刷新流程和 interaction resolve request 组装流程。 +- 它本身不携带 hovered / focused 等 UI 状态，只关注几何快照。 + +## 调用位置 + +当前 `SceneViewPanel::Render()` 会把同一份 `SceneViewportFrameGeometry` 同时传给： + +- `BuildSceneViewportInteractionFrameState(...)` +- `BuildSceneViewportInteractionResolveRequest(...)` +- `RefreshAndDrawSceneViewportPresentation(...)` ## 相关文档 diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportInteractionFrame/SceneViewportInteractionFrame.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportInteractionFrame/SceneViewportInteractionFrame.md index cdd32384..d12d11db 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportInteractionFrame/SceneViewportInteractionFrame.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportInteractionFrame/SceneViewportInteractionFrame.md @@ -2,50 +2,42 @@ **命名空间**: `XCEngine::Editor` -**类型**: `structs + free functions` +**类型**: `header-only helpers + structs` **源文件**: `editor/src/Viewport/SceneViewportInteractionFrame.h` -**描述**: 把 Scene View 单帧交互与 presentation 尾段所需的工具模式、视口几何、overlay 数据、焦点决策和 gizmo/HUD presentation 收口成可复用 helper。 +**说明**: 把 Scene View 每帧里和工具状态、视口几何、overlay/gizmo 刷新、interaction resolve 输入以及 presentation 尾段相关的重复装配逻辑收口到一组轻量 helper 中。 ## 概览 -`SceneViewportInteractionFrame.h` 位于 `SceneViewPanel` 与 gizmo / overlay / interaction-resolver 之间。它解决的不是“如何命中交互”，而是“这一帧 Scene View 交互前后，需要复用哪些装配与收口步骤”。 +当前 `SceneViewPanel::Render()` 会按下面顺序消费这组 helper： -当前它主要负责五件事： +1. 用 [BuildSceneViewportToolState](BuildSceneViewportToolState.md) 把 `toolMode / pivotMode / transformSpaceMode` 翻译成 gizmo 可见性和 frame options。 +2. 用 [BuildSceneViewportFrameGeometry](BuildSceneViewportFrameGeometry.md) 把 ImGui 的 viewport 尺寸与绝对鼠标坐标转成局部坐标。 +3. 用 [BuildSceneViewportInteractionFrameState](BuildSceneViewportInteractionFrameState.md) 拉取 host overlay、刷新 gizmo frame，并准备 HUD 与后续 resolve 所需状态。 +4. 用 [BuildSceneViewportInteractionResolveRequest](BuildSceneViewportInteractionResolveRequest.md) 给 interaction resolver 组装输入。 +5. 用 [ShouldFocusSceneViewportAfterInteraction](ShouldFocusSceneViewportAfterInteraction.md) 决定这帧是否把焦点重新交给 Scene View。 +6. 在 `IViewportHostService::UpdateSceneViewInput(...)` 之后，再用 [RefreshAndDrawSceneViewportPresentation](RefreshAndDrawSceneViewportPresentation.md) 刷新一次 presentation 并绘制 HUD。 -1. 根据工具模式生成当前帧的 gizmo 开关和 frame options。 -2. 把 ImGui 视口矩形和鼠标位置整理成统一的局部几何输入。 -3. 从 `IViewportHostService` 拉取 overlay 与 gizmo frame 更新结果，并组装成可供后续 interaction resolve 使用的 frame state。 -4. 把 tool command、interaction action 与 navigation begin 标志折叠成统一的 Scene View focus 决策。 -5. 在本帧尾段刷新最新 gizmo presentation，并绘制 HUD overlay。 +## 当前语义 -## 公开结构与函数 - -| 成员 | 说明 | -|------|------| -| [SceneViewportToolState](SceneViewportToolState.md) | 当前工具模式翻译后的 gizmo 与 pivot/space 状态。 | -| [BuildSceneViewportToolState](BuildSceneViewportToolState.md) | 从 tool/pivot/space 三组枚举构建工具状态。 | -| [SceneViewportFrameGeometry](SceneViewportFrameGeometry.md) | 当前视口尺寸和本地鼠标坐标。 | -| [BuildSceneViewportFrameGeometry](BuildSceneViewportFrameGeometry.md) | 从 ImGui 输入构建 frame geometry。 | -| [SceneViewportInteractionFrameState](SceneViewportInteractionFrameState.md) | 当前帧 overlay、gizmo 更新结果和 HUD 数据。 | -| [BuildSceneViewportInteractionFrameState](BuildSceneViewportInteractionFrameState.md) | 组装单帧交互状态。 | -| [BuildSceneViewportInteractionResolveRequest](BuildSceneViewportInteractionResolveRequest.md) | 把 frame state 与视口几何打包成 resolver 输入。 | -| [ShouldFocusSceneViewportAfterInteraction](ShouldFocusSceneViewportAfterInteraction.md) | 折叠工具切换、点击动作与导航起始事件，决定是否聚焦 Scene View。 | -| [SceneViewportPresentationRequest](SceneViewportPresentationRequest.md) | 描述单帧尾段 gizmo/HUD presentation 所需的输入。 | -| [RefreshAndDrawSceneViewportPresentation](RefreshAndDrawSceneViewportPresentation.md) | 刷新最终 gizmo frame 并绘制 HUD overlay。 | +- 这组 helper 不拥有 `IEditorContext`、`IViewportHostService`、三个 gizmo，也不缓存跨帧状态。 +- [SceneViewportInteractionFrameState](SceneViewportInteractionFrameState.md) 里的 `overlayFrameData` 是非拥有指针： + - 非交互 viewport 时指向调用方传入的 `emptyOverlayFrameData` + - 交互 viewport 时指向 `viewportHostService.GetSceneViewEditorOverlayFrameData(context)` 返回对象 +- `hasInteractiveViewport == false` 时，会立即走“空帧”路径，并取消当前 gizmo frame。 +- [RefreshAndDrawSceneViewportPresentation](RefreshAndDrawSceneViewportPresentation.md) 只负责 presentation 尾段，不做 interaction resolve，也不推进 gizmo begin / update / end 生命周期命令。 ## 测试覆盖 `tests/Editor/test_scene_viewport_interaction_frame.cpp` 当前验证了： -- 工具模式到 gizmo 显示状态的映射。 -- 视口尺寸与本地鼠标坐标的构造。 -- 非交互视口时如何回退到空 overlay frame。 -- 交互视口时如何消费 `IViewportHostService` 的 overlay 与 gizmo submission。 -- interaction resolve request 是否正确复制 frame-state 与几何输入。 -- focus helper 是否正确收口 tool command、click action 与 navigation begin 条件。 -- presentation helper 是否会跳过非交互视口，并在 `drawList == nullptr` 时仍刷新 gizmo frame。 +- 工具模式到 gizmo frame options 的映射。 +- viewport 尺寸与局部鼠标坐标的构造。 +- 交互 / 非交互 viewport 两条 frame-state 路径。 +- resolve request 是否按原样转发 frame-state 与几何快照。 +- focus helper 是否统一收口工具切换、点击动作和导航起始。 +- presentation helper 是否跳过非交互 viewport，以及在 `drawList == nullptr` 时仍刷新 gizmo frame。 ## 相关文档 @@ -54,4 +46,5 @@ - [SceneViewportChrome](../SceneViewportChrome/SceneViewportChrome.md) - [SceneViewportInteractionResolver](../SceneViewportInteractionResolver/SceneViewportInteractionResolver.md) - [SceneViewportHudOverlay](../SceneViewportHudOverlay/SceneViewportHudOverlay.md) +- [SceneViewportTransformGizmoCoordinator](../SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoCoordinator.md) - [SceneViewPanel](../../panels/SceneViewPanel/SceneViewPanel.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportInteractionFrame/SceneViewportInteractionFrameState.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportInteractionFrame/SceneViewportInteractionFrameState.md index 0f68f242..54401fce 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportInteractionFrame/SceneViewportInteractionFrameState.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportInteractionFrame/SceneViewportInteractionFrameState.md @@ -6,28 +6,33 @@ **源文件**: `editor/src/Viewport/SceneViewportInteractionFrame.h` -**描述**: 描述 Scene View 当前帧已经准备好的 overlay、gizmo 和 HUD 状态包。 +**说明**: 描述 Scene View 当前帧已经准备好的 overlay、gizmo 和 HUD 状态包，供 interaction resolve、gizmo 生命周期推进和 presentation 收尾复用。 ## 关键字段 -- `hasInteractiveViewport`：这一帧是否存在可交互 viewport。 -- `overlay`：当前 scene view overlay 数据。 -- `gizmoFrameUpdate` / `gizmoFrameState`：当前帧 transform gizmo 刷新结果与生命周期状态。 -- `overlayFrameData`：当前帧 editor overlay primitive 数据来源。 -- `activeGizmoKind`：当前处于激活态的 gizmo 类型。 -- `gizmoActive`：当前是否已有 gizmo 占用交互。 -- `hudOverlay`：HUD overlay 数据。 +- `hasInteractiveViewport`：这帧是否存在可交互 viewport。 +- `overlay`：当前帧读取到的 `SceneViewportOverlayData`。 +- `gizmoFrameUpdate`：本次 gizmo refresh 的完整输出，包含 `frameState` 和 `overlaySubmission`。 +- `gizmoFrameState`：`gizmoFrameUpdate.frameState` 的便捷副本，便于直接传给 gizmo 生命周期执行函数。 +- `overlayFrameData`：editor overlay primitive 数据源的非拥有指针。 +- `activeGizmoKind`：当前处于 active 状态的 gizmo 类型。 +- `gizmoActive`：`activeGizmoKind != None` 的便捷布尔位。 +- `hudOverlay`：由 `overlay` 派生出的 HUD overlay 数据。 ## 当前语义 - 这是 [BuildSceneViewportInteractionFrameState](BuildSceneViewportInteractionFrameState.md) 的输出结构。 -- 它是 `SceneViewPanel` 在“准备阶段”和“interaction resolve 阶段”之间传递的单帧状态包。 -- 后续的 [BuildSceneViewportInteractionResolveRequest](BuildSceneViewportInteractionResolveRequest.md) 会把其中的 overlay、HUD 和局部几何数据重新打包成 resolver 输入。 +- 它是 `SceneViewPanel` 在 interaction resolve 之前准备好的单帧状态包，本身不跨帧持久化。 +- `overlayFrameData` 是非拥有指针： + - 非交互 viewport 时指向调用方提供的空 frame data + - 交互 viewport 时指向 `IViewportHostService` 当前返回的 overlay frame data +- `activeGizmoKind` 和 `gizmoActive` 直接来自本帧 gizmo overlay submission，调用方可以用它们做交互门禁，而不需要再次查询三个 gizmo。 +- 后续的 [BuildSceneViewportInteractionResolveRequest](BuildSceneViewportInteractionResolveRequest.md) 会复用这里的 `overlayFrameData`、`hudOverlay` 和局部几何，重新打包成 resolver 输入。 -## 当前实现边界 +## 边界说明 -- 它不直接保存最终 hover 命中结果；那是 interaction resolver 的职责。 -- 它也不直接驱动相机导航；导航状态由 [SceneViewportNavigation](../SceneViewportNavigation/SceneViewportNavigation.md) 维护。 +- 它不保存最终 hover / click 命中结果；那属于 interaction resolver 的输出。 +- 它也不维护导航拖拽状态；导航状态由 [SceneViewportNavigation](../SceneViewportNavigation/SceneViewportNavigation.md) 单独维护。 ## 相关文档 diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportInteractionFrame/SceneViewportPresentationRequest.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportInteractionFrame/SceneViewportPresentationRequest.md index f85e328f..ea58537a 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportInteractionFrame/SceneViewportPresentationRequest.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportInteractionFrame/SceneViewportPresentationRequest.md @@ -6,7 +6,7 @@ **源文件**: `editor/src/Viewport/SceneViewportInteractionFrame.h` -**描述**: 描述 Scene View 单帧尾段 gizmo/HUD presentation 所需的输入集合。 +**说明**: 描述 Scene View 单帧尾段 gizmo / HUD presentation 所需的输入集合。 ## 字段 @@ -14,23 +14,31 @@ |------|------|------| | `context` | `IEditorContext*` | 当前 editor 上下文。 | | `viewportHostService` | `IViewportHostService*` | Scene View overlay 与 gizmo 提交宿主。 | +| `overlayFrameData` | `const SceneViewportOverlayFrameData*` | HUD scene icon 的非拥有数据源；允许为空。 | | `hasInteractiveViewport` | `bool` | 当前帧是否存在可交互 viewport。 | -| `geometry` | `SceneViewportFrameGeometry` | 当前 viewport 尺寸与本地鼠标坐标。 | +| `geometry` | `SceneViewportFrameGeometry` | 当前 viewport 尺寸与局部鼠标坐标。 | | `gizmoFrameOptions` | `SceneViewportTransformGizmoFrameOptions` | 当前 gizmo 刷新配置。 | -| `moveGizmo` / `rotateGizmo` / `scaleGizmo` | gizmo 指针 | 三类 gizmo 实例。 | +| `moveGizmo / rotateGizmo / scaleGizmo` | gizmo 指针 | 三类 gizmo 实例。 | | `drawList` | `ImDrawList*` | HUD overlay 的目标绘制列表。 | -| `viewportMin` / `viewportMax` | `ImVec2` | HUD overlay 的 viewport 绝对矩形。 | +| `viewportMin / viewportMax` | `ImVec2` | HUD overlay 使用的 viewport 绝对矩形。 | ## 当前语义 - 这是 [RefreshAndDrawSceneViewportPresentation](RefreshAndDrawSceneViewportPresentation.md) 的输入结构。 - `IsValid()` 当前要求 `context`、`viewportHostService`、`moveGizmo`、`rotateGizmo` 和 `scaleGizmo` 全部非空。 -- `drawList` 不属于 `IsValid()` 的必需条件；当前实现允许 `drawList == nullptr`，此时 gizmo frame 仍会刷新，HUD 绘制则会在 `DrawSceneViewportHudOverlay(...)` 内部直接返回。 -- `hasInteractiveViewport == false` 时，这份请求依然可以是“有效”的，但 presentation helper 会整体 no-op。 +- `overlayFrameData` 和 `drawList` 都不是 `IsValid()` 的必需条件： + - `overlayFrameData == nullptr` 时，HUD 不会绘制 scene icon + - `drawList == nullptr` 时，gizmo frame 仍会刷新，但 HUD 绘制阶段会 no-op +- `hasInteractiveViewport == false` 时，这份 request 依然可以是“有效”的，但 presentation helper 会整体直接返回。 + +## 生命周期边界 + +- 这里的指针字段都是非拥有引用，只适合在当前帧立即消费。 +- `overlayFrameData` 当前只参与 HUD 绘制，不参与 gizmo refresh。 ## 相关文档 - [SceneViewportInteractionFrame](SceneViewportInteractionFrame.md) - [RefreshAndDrawSceneViewportPresentation](RefreshAndDrawSceneViewportPresentation.md) - [BuildSceneViewportFrameGeometry](BuildSceneViewportFrameGeometry.md) -- [BuildSceneViewportToolState](BuildSceneViewportToolState.md) +- [BuildSceneViewportHudOverlayData](../SceneViewportHudOverlay/BuildSceneViewportHudOverlayData.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportInteractionFrame/SceneViewportToolState.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportInteractionFrame/SceneViewportToolState.md index 3bfb884d..18f7c5c8 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportInteractionFrame/SceneViewportToolState.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportInteractionFrame/SceneViewportToolState.md @@ -6,30 +6,35 @@ **源文件**: `editor/src/Viewport/SceneViewportInteractionFrame.h` -**描述**: 描述当前 Scene View 工具模式翻译后的 gizmo、pivot 和坐标空间状态。 +**说明**: 描述当前 Scene View 工具模式翻译后的 gizmo 可见性、pivot/space 选项，以及下游 gizmo frame 刷新所需聚合配置。 ## 关键字段 - `usingViewMoveTool`：当前是否处于 `ViewMove` 导航工具。 -- `usingTransformTool`：当前是否处于联合 `Transform` 工具。 -- `showingMoveGizmo` / `showingRotateGizmo` / `showingScaleGizmo`：当前帧三类 gizmo 是否应被显示与刷新。 +- `usingTransformTool`：当前是否处于聚合的 `Transform` 工具。 +- `showingMoveGizmo / showingRotateGizmo / showingScaleGizmo`：当前帧三类 gizmo 是否应该被刷新并可见。 - `useCenterPivot`：当前是否使用中心 pivot，而不是对象 pivot。 - `localSpace`：当前是否使用局部坐标空间。 -- `gizmoFrameOptions`：进一步传给 transform gizmo frame builder / coordinator 的聚合选项。 +- `gizmoFrameOptions`：把以上布尔位继续折叠成给 transform gizmo coordinator 使用的 frame options。 ## 当前语义 -- 这是 [BuildSceneViewportToolState](BuildSceneViewportToolState.md) 的输出结构。 -- `SceneViewPanel` 会先根据工具栏、快捷键、pivot 开关和 global/local 开关生成这份结构，再把其中的 `gizmoFrameOptions` 交给 gizmo frame 刷新流程。 -- `Transform` 模式并不是第四套独立 gizmo，而是同时打开 move / rotate / scale 三类 gizmo 的聚合模式。 +- 这是 [BuildSceneViewportToolState](BuildSceneViewportToolState.md) 的输出结构，不自己做任何推导。 +- `SceneViewportToolMode::Transform` 不是第四套独立 gizmo；当前实现会同时打开 move / rotate / scale 三类 gizmo。 +- `gizmoFrameOptions` 和前面的布尔字段在构造时保持同步，下游应优先把它当作 gizmo refresh 的权威输入。 +- 这里不包含 hover、selection、active-drag 或 overlay 数据；它只回答“这一帧应该以什么工具配置刷新 gizmo”。 -## 当前实现边界 +## 调用位置 -- 这里不保存拖拽生命周期状态，也不描述当前 hover/selection 命中结果。 -- 它只负责“这一帧应该以什么工具配置刷新 gizmo”，真正的交互命中和生命周期控制仍在后续步骤完成。 +当前 `SceneViewPanel::Render()` 会在处理快捷键和工具栏切换之后立即构造这份状态，并把其中的 `gizmoFrameOptions` 传给 interaction-frame 和 presentation 两条 gizmo 刷新路径。 + +## 测试覆盖 + +`tests/Editor/test_scene_viewport_interaction_frame.cpp` 当前验证了 `Move` 与 `Transform` 两类模式下的 gizmo 显示位、pivot 和 local-space 映射。 ## 相关文档 - [SceneViewportInteractionFrame](SceneViewportInteractionFrame.md) - [BuildSceneViewportToolState](BuildSceneViewportToolState.md) +- [SceneViewportTransformGizmoFrameOptions](../SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoFrameOptions.md) - [SceneViewportEditorModes](../SceneViewportEditorModes/SceneViewportEditorModes.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportInteractionFrame/ShouldFocusSceneViewportAfterInteraction.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportInteractionFrame/ShouldFocusSceneViewportAfterInteraction.md index e58b7cac..6ad5828d 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportInteractionFrame/ShouldFocusSceneViewportAfterInteraction.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportInteractionFrame/ShouldFocusSceneViewportAfterInteraction.md @@ -1,6 +1,7 @@ # ShouldFocusSceneViewportAfterInteraction 把工具切换、点击动作和导航起始事件折叠成 Scene View 聚焦决策。 + ```cpp bool ShouldFocusSceneViewportAfterInteraction( bool toolCommandTriggered, @@ -13,11 +14,13 @@ bool ShouldFocusSceneViewportAfterInteraction( - 只要 `toolCommandTriggered == true`，就返回 `true`。 - 只要 `interactionActions.HasClickAction() == true`，就返回 `true`。 - 只要 `navigationUpdate.beginLookDrag` 或 `navigationUpdate.beginPanDrag` 为真，就返回 `true`。 -- 它不关心 hover-only 状态，也不直接调用 `ImGui::SetWindowFocus()`；真正的聚焦动作仍由 `SceneViewPanel::Render()` 执行。 +- 以上条件是“或”关系；任一成立都会要求 Scene View 获取焦点。 -## 真实使用位置 +## 设计边界 -- `SceneViewPanel::Render()` 当前会在更新导航状态之后调用这里，再决定是否执行 `ImGui::SetWindowFocus()`。 +- 它不关心 hover-only 状态。 +- 它也不直接调用 `ImGui::SetWindowFocus()`；真正的聚焦动作仍由 `SceneViewPanel::Render()` 执行。 +- 这个 helper 只负责把来自 tool command、interaction action 和 navigation update 的多路边沿信号统一收口。 ## 测试覆盖 diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportMath/BuildSceneViewportViewMatrix.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportMath/BuildSceneViewportViewMatrix.md index b2c585ea..8f6e0f30 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportMath/BuildSceneViewportViewMatrix.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportMath/BuildSceneViewportViewMatrix.md @@ -18,11 +18,25 @@ Math::Matrix4x4 BuildSceneViewportViewMatrix(const SceneViewportOverlayData& ove ## 当前实现行为 -- 会把 `cameraRight / cameraUp / cameraForward` 全部归一化。 -- 矩阵前三行分别使用右、上、前方向和相机位置的点积偏移组装。 -- 当前实现不额外检查 `overlay.valid`，默认由调用方保证输入有效。 +- 会先把 `cameraRight / cameraUp / cameraForward` 全部归一化。 +- 然后用这三条基向量和 `cameraPosition` 的点积偏移组装出 view matrix 的前三行。 +- 当前实现不额外检查 `overlay.valid`；默认由调用方保证输入语义有效。 + +## 当前语义 + +- 该矩阵遵循当前 editor 相机的 transform 约定。 +- 从测试看，它应当与 `cameraObject.GetTransform()->GetWorldToLocalMatrix()` 保持一致。 +- 对位于相机前方的世界点，当前矩阵会把它变换到正向 view-space 深度。 + +## 测试覆盖 + +`tests/Editor/test_scene_viewport_overlay_renderer.cpp` 当前验证了： + +- 位于相机前方的世界点会保持正向 view-space 深度。 +- 返回矩阵与 Scene View 相机 transform 的 `WorldToLocalMatrix` 约定一致。 ## 相关文档 - [SceneViewportMath](SceneViewportMath.md) +- [BuildSceneViewportProjectionMatrix](BuildSceneViewportProjectionMatrix.md) - [BuildSceneViewportViewProjectionMatrix](BuildSceneViewportViewProjectionMatrix.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportMoveGizmo/CancelDrag.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportMoveGizmo/CancelDrag.md index 007379be..dc9be904 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportMoveGizmo/CancelDrag.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportMoveGizmo/CancelDrag.md @@ -19,8 +19,20 @@ void CancelDrag(IUndoManager* undoManager = nullptr); ## 当前实现行为 - 如果传入了 `undoManager` 且当前有 pending interactive change，会调用 `CancelInteractiveChange()` 回滚。 -- 同样会清空全部拖拽状态。 -- 额外会把 `hoveredAxis` 和 `hoveredPlane` 一并清空，避免取消后继续显示旧命中。 +- 无论是否真的发生撤销，都会清空： + - 拖拽模式 + - active axis / plane + - active entity id + - 拖拽平面与起始 hit 缓存 + - 拖拽对象与起始位置数组 +- 还会额外把 `hoveredAxis` 和 `hoveredPlane` 一并清空，避免取消后继续显示旧 hover。 +- 最后调用 `RefreshHandleState()` 去掉 active / hovered 视觉状态。 + +## 与 `EndDrag` 的区别 + +- `EndDrag(...)` 会尝试 `FinalizeInteractiveChange()` 提交结果。 +- `CancelDrag(...)` 会在可用时 `CancelInteractiveChange()` 回滚结果。 +- 并且 `CancelDrag(...)` 比 `EndDrag(...)` 多做了一步：清空当前 hover。 ## 相关文档 diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportMoveGizmo/EndDrag.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportMoveGizmo/EndDrag.md index 09ebbb2c..c5401554 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportMoveGizmo/EndDrag.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportMoveGizmo/EndDrag.md @@ -19,10 +19,28 @@ void EndDrag(IUndoManager& undoManager); ## 当前实现行为 - 当前没有活动拖拽时直接返回。 -- 若 `undoManager` 还持有 pending interactive change，会调用 `FinalizeInteractiveChange()` 提交位移结果。 -- 之后清空拖拽模式、活动轴/平面、活动实体 id、拖拽平面相关缓存以及对象起始位置数组。 +- 若 `undoManager` 仍持有 pending interactive change，会调用 `FinalizeInteractiveChange()` 提交本次位移结果。 +- 随后清空： + - 拖拽模式 + - active axis / plane + - active entity id + - 轴向 / 平面方向缓存 + - 拖拽起始 pivot / hit / 标量缓存 + - 拖拽对象与起始位置数组 - 最后调用 `RefreshHandleState()` 去掉 active 标记。 +## 当前语义 + +- 它不会清空当前 hover；释放拖拽后的 hover 状态会由后续 `Update(...)` 或外部 hover 注入继续决定。 +- 拖拽提交与视觉状态清理在同一个入口完成，因此外层通常只需要在鼠标释放时调用一次这里。 + +## 测试关联 + +`tests/Editor/test_scene_viewport_move_gizmo.cpp` 当前通过完整 drag 路径验证了： + +- 拖拽结束后位移结果被保留。 +- undo 历史中会留下可撤销步骤。 + ## 相关文档 - [SceneViewportMoveGizmo](SceneViewportMoveGizmo.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportMoveGizmo/SetHoveredHandle.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportMoveGizmo/SetHoveredHandle.md index ac1e7ba7..d9b1b813 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportMoveGizmo/SetHoveredHandle.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportMoveGizmo/SetHoveredHandle.md @@ -19,9 +19,14 @@ void SetHoveredHandle(SceneViewportGizmoAxis axis, SceneViewportGizmoPlane plane ## 当前实现行为 - 当前存在活动拖拽时不会覆盖内部状态。 -- 若传入了有效轴，会强制清空平面 hover。 -- 若轴为 `None`，则保留传入的平面 hover。 -- 写入后会通过 `RefreshHandleState()` 同步显示状态。 +- 如果传入了有效 axis，会强制清空 plane hover。 +- 只有当 axis 为 `None` 时，才会保留传入的 plane hover。 +- 写入后会调用 `RefreshHandleState()` 同步 draw data 中的 hovered 样式。 + +## 当前语义 + +- 这给了外层 interaction resolver 一个“命中结果反灌”入口，不必完全依赖 gizmo 自己的内部 hit-test。 +- move gizmo 的 hover 模型始终是“轴优先于平面”；同一时刻不会同时保留 axis 和 plane 两种 hover。 ## 相关文档 diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportNavigation/BuildSceneViewportCaptureFlags.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportNavigation/BuildSceneViewportCaptureFlags.md index 8728cad6..d04309a0 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportNavigation/BuildSceneViewportCaptureFlags.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportNavigation/BuildSceneViewportCaptureFlags.md @@ -1,35 +1,34 @@ # BuildSceneViewportCaptureFlags -**命名空间**: `XCEngine::Editor` - -**类型**: `function` - -**源文件**: `editor/src/Viewport/SceneViewportNavigation.h` - -## 签名 +根据导航状态和 gizmo 活动状态，生成下一帧 ImGui 输入捕获标志。 ```cpp SceneViewportCaptureFlags BuildSceneViewportCaptureFlags( const SceneViewportCaptureRequest& request); ``` -## 作用 - -根据导航状态和 gizmo 活动状态，生成下一帧 ImGui 输入捕获标志。 - -## 当前实现行为 +## 当前行为 - `captureMouse` 在以下任一条件满足时为 `true`： - - `state.lookDragging` - - `state.panDragging` - - `moveGizmoActive` - - `rotateGizmoActive` - - `scaleGizmoActive` -- `captureKeyboard` 当前只在 `state.lookDragging` 时为 `true` + - `request.state.lookDragging` + - `request.state.panDragging` + - `request.moveGizmoActive` + - `request.rotateGizmoActive` + - `request.scaleGizmoActive` +- `captureKeyboard` 当前只在 `request.state.lookDragging` 时为 `true`。 -`tests/Editor/test_scene_viewport_navigation.cpp` 当前验证了 look drag 与 gizmo active 两类典型输入。 +## 设计边界 + +- 这个函数不关心 viewport hover、focus 或文本输入状态；它只根据“当前有没有主动占用交互”的状态做判断。 +- 当前 `SceneViewPanel` 会把返回值直接映射到 `ImGui::SetNextFrameWantCaptureMouse(true)` 和 `ImGui::SetNextFrameWantCaptureKeyboard(true)`。 +- 也就是说，它描述的是“下一帧是否要让 ImGui 把输入留给 Scene View 流程”，而不是“这一帧有没有收到输入事件”。 + +## 测试覆盖 + +`tests/Editor/test_scene_viewport_navigation.cpp` 当前验证了 look drag 和 gizmo active 两类典型输入下的 capture 行为。 ## 相关文档 - [SceneViewportNavigation](SceneViewportNavigation.md) - [SceneViewportCaptureRequest](SceneViewportCaptureRequest.md) +- [SceneViewportCaptureFlags](SceneViewportCaptureFlags.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportNavigation/BuildSceneViewportInput.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportNavigation/BuildSceneViewportInput.md index e0789640..f14f6e86 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportNavigation/BuildSceneViewportInput.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportNavigation/BuildSceneViewportInput.md @@ -1,36 +1,42 @@ # BuildSceneViewportInput -**命名空间**: `XCEngine::Editor` - -**类型**: `function` - -**源文件**: `editor/src/Viewport/SceneViewportNavigation.h` - -## 签名 +把面板层输入快照翻译成 `IViewportHostService::UpdateSceneViewInput(...)` 需要的 `SceneViewportInput`。 ```cpp -SceneViewportInput BuildSceneViewportInput(const SceneViewportInputBuildRequest& request); +SceneViewportInput BuildSceneViewportInput( + const SceneViewportInputBuildRequest& request); ``` -## 作用 +## 当前行为 -把 ImGui 层输入快照翻译成 `IViewportHostService::UpdateSceneViewInput(...)` 需要的 `SceneViewportInput`。 +- `viewportSize` 和 `deltaTime` 会直接透传。 +- `focused` 满足以下任一条件就会为 `true`： + - `request.viewportFocused` + - `request.state.lookDragging` + - `request.state.panDragging` +- `mouseWheel` 只有在 `request.viewportHovered && !request.state.lookDragging` 时才透传；否则清零。 +- `flySpeedDelta` 只有在 `request.viewportHovered && request.state.lookDragging` 时才透传；否则清零。 +- `looking` 取自 `request.state.lookDragging`，`panning` 取自 `request.state.panDragging`，`orbiting` 当前固定为 `false`。 +- `focusSelectionRequested` 需要同时满足： + - 计算后的 `input.focused == true` + - `request.wantTextInput == false` + - `request.focusSelectionKeyPressed == true` +- 飞行移动轴 `moveForward / moveRight / moveUp` 只会在 `lookDragging && !wantTextInput` 时写入。 +- `mouseDelta` 只会在 look drag 或 pan drag 活跃时透传。 -## 当前实现行为 +## 设计边界 -- `viewportSize` 和 `deltaTime` 直接透传。 -- `focused` 只要满足以下任一条件就会置为 `true`： - - `viewportFocused` - - `state.lookDragging` - - `state.panDragging` -- `mouseWheel` 只有在 `viewportHovered && !state.lookDragging` 时才透传；否则清零。 -- `flySpeedDelta` 只有在 `viewportHovered && state.lookDragging` 时才透传；否则清零。 -- `looking` 取自 `state.lookDragging`，`panning` 取自 `state.panDragging`，`orbiting` 当前固定为 `false`。 -- `focusSelectionRequested` 需要 `focused == true`、`wantTextInput == false` 且 `focusSelectionKeyPressed == true`。 -- 只有在 `state.lookDragging && !wantTextInput` 时，`moveForward / moveRight / moveUp` 等飞行移动轴才会写入。 -- 只有在 look 或 pan drag 活跃时，`mouseDelta` 才会透传。 +- 这个函数不读取 ImGui，也不绑定具体快捷键；所有按键语义都由调用方先翻译成 `SceneViewportInputBuildRequest`。 +- 当前 `SceneViewPanel` 会把 `Shift` 映射到 `fastMove`，把 `F` 映射到 `focusSelectionKeyPressed`，再调用这里。 +- 即便 viewport 没有显式焦点，只要导航拖拽还在进行，返回的 `SceneViewportInput` 仍会保持 `focused == true`。 -`tests/Editor/test_scene_viewport_navigation.cpp` 当前验证了滚轮、飞行速度调节、焦点请求、移动轴和鼠标位移的映射。 +## 测试覆盖 + +`tests/Editor/test_scene_viewport_navigation.cpp` 当前验证了： + +- 普通 hover 时滚轮进入 `mouseWheel`。 +- look drag 期间滚轮改写为 `flySpeedDelta`。 +- `fastMove`、`focusSelectionRequested`、飞行移动轴和 `mouseDelta` 的映射。 ## 相关文档 diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportNavigation/CanResolveSceneViewportInteraction.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportNavigation/CanResolveSceneViewportInteraction.md index 10e2f266..556f98ad 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportNavigation/CanResolveSceneViewportInteraction.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportNavigation/CanResolveSceneViewportInteraction.md @@ -1,6 +1,7 @@ # CanResolveSceneViewportInteraction 判断当前帧是否允许进入 Scene View 的 overlay / HUD 交互命中解析。 + ```cpp bool CanResolveSceneViewportInteraction( bool hasInteractiveViewport, @@ -23,12 +24,14 @@ bool CanResolveSceneViewportInteraction( ## 设计说明 -- 这意味着当前实现会在 view-move 导航、任意导航拖拽和 gizmo active 期间屏蔽新的 hover / click 解析。 -- 它相当于 `SceneViewPanel` 在调用 [ResolveSceneViewportInteraction](../SceneViewportInteractionResolver/ResolveSceneViewportInteraction.md) 前的一层统一守卫。 +- 它是 `SceneViewPanel` 在调用 [ResolveSceneViewportInteraction](../SceneViewportInteractionResolver/ResolveSceneViewportInteraction.md) 之前的一层统一门禁。 +- 这意味着当前实现会在 view-move 导航、任意导航拖拽以及 gizmo active 期间，屏蔽新的 hover / click 命中解析。 +- 这里的 `viewportHovered` 来自调用方；在当前 `SceneViewPanel` 中，它已经扣除了工具栏 overlay 的悬停区域。 +- 这个函数本身不做 hit-test，也不判断鼠标到底命中了哪一个 overlay handle。 ## 测试覆盖 -`tests/Editor/test_scene_viewport_navigation.cpp` 当前覆盖了 hover、导航和 gizmo active 对返回值的影响。 +`tests/Editor/test_scene_viewport_navigation.cpp` 当前覆盖了 hover、导航状态、ViewMove 模式和 gizmo active 对返回值的影响。 ## 相关文档 diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportNavigation/SceneViewportCaptureFlags.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportNavigation/SceneViewportCaptureFlags.md index 18ad9a3b..9fd04dc5 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportNavigation/SceneViewportCaptureFlags.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportNavigation/SceneViewportCaptureFlags.md @@ -6,20 +6,27 @@ **源文件**: `editor/src/Viewport/SceneViewportNavigation.h` -**描述**: 描述当前帧是否需要让 Scene View 请求捕获鼠标和键盘输入。 +**说明**: 描述当前帧是否需要让 Scene View 请求捕获鼠标和键盘输入。 ## 字段 | 字段 | 类型 | 说明 | |------|------|------| -| `captureMouse` | `bool` | 是否应让 ImGui 在下一帧继续捕获鼠标。 | -| `captureKeyboard` | `bool` | 是否应让 ImGui 在下一帧继续捕获键盘。 | +| `captureMouse` | `bool` | 是否应让 ImGui 在下一帧继续把鼠标输入留给 Scene View。 | +| `captureKeyboard` | `bool` | 是否应让 ImGui 在下一帧继续把键盘输入留给 Scene View。 | ## 当前语义 -- `captureMouse` 的范围更宽：只要处于 look drag、pan drag，或任意 gizmo 还在 active，就会被置为 `true`。 +- 这是 [BuildSceneViewportCaptureFlags](BuildSceneViewportCaptureFlags.md) 的输出结构。 +- `captureMouse` 的范围更宽：只要处于 look drag、pan drag，或任意 gizmo 仍然 active，就会被置为 `true`。 - `captureKeyboard` 更保守：当前只在 look drag 期间捕获键盘。 -- `SceneViewPanel` 当前会把它翻译成 `ImGui::SetNextFrameWantCaptureMouse/Keyboard(...)`。 + +## 调用位置 + +当前 `SceneViewPanel::Render()` 会把它翻译成： + +- `ImGui::SetNextFrameWantCaptureMouse(true)` +- `ImGui::SetNextFrameWantCaptureKeyboard(true)` ## 相关文档 diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportNavigation/SceneViewportCaptureRequest.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportNavigation/SceneViewportCaptureRequest.md index 1948ad9b..21b1391a 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportNavigation/SceneViewportCaptureRequest.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportNavigation/SceneViewportCaptureRequest.md @@ -11,16 +11,22 @@ | 字段 | 类型 | 说明 | |------|------|------| | `state` | `SceneViewportNavigationState` | 当前导航状态。 | -| `moveGizmoActive` | `bool` | move gizmo 是否正在拖拽。 | -| `rotateGizmoActive` | `bool` | rotate gizmo 是否正在拖拽。 | -| `scaleGizmoActive` | `bool` | scale gizmo 是否正在拖拽。 | +| `moveGizmoActive` | `bool` | move gizmo 是否正在占用交互。 | +| `rotateGizmoActive` | `bool` | rotate gizmo 是否正在占用交互。 | +| `scaleGizmoActive` | `bool` | scale gizmo 是否正在占用交互。 | -## 当前用法 +## 当前语义 -- `SceneViewPanel::Render()` 当前在 gizmo lifecycle 更新后构造它。 -- [BuildSceneViewportCaptureFlags](BuildSceneViewportCaptureFlags.md) 根据它决定是否调用 `ImGui::SetNextFrameWantCaptureMouse/Keyboard(true)`。 +- 这是 [BuildSceneViewportCaptureFlags](BuildSceneViewportCaptureFlags.md) 的最小输入快照。 +- 它只关心“当前有没有主动占用输入”的状态，不包含 hover、focus、文本输入或鼠标位置等信息。 +- 三个 `*GizmoActive` 字段通常来自各 gizmo 的 `IsActive()`。 + +## 调用位置 + +当前 `SceneViewPanel::Render()` 会在 gizmo 生命周期更新之后构造它，再据此生成下一帧的 ImGui capture 标志。 ## 相关文档 - [SceneViewportNavigation](SceneViewportNavigation.md) - [SceneViewportCaptureFlags](SceneViewportCaptureFlags.md) +- [BuildSceneViewportCaptureFlags](BuildSceneViewportCaptureFlags.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportNavigation/SceneViewportNavigation.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportNavigation/SceneViewportNavigation.md index b69e7b28..1a8bb29f 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportNavigation/SceneViewportNavigation.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportNavigation/SceneViewportNavigation.md @@ -2,57 +2,64 @@ **命名空间**: `XCEngine::Editor` -**类型**: `header-helper + structs` +**类型**: `header-only helpers + structs` **源文件**: `editor/src/Viewport/SceneViewportNavigation.h` -**描述**: Scene View 的 header-only 导航与输入组装层，负责工具快捷键、look/pan drag 状态机、ImGui capture 标志以及 `SceneViewportInput` 构造。 +**说明**: Scene View 的导航、输入转译和 ImGui capture 规则都在这里收口。它不直接读 ImGui 全局状态，而是消费调用方整理好的布尔快照。 -## 概述 +## 概览 -`SceneViewportNavigation.h` 解决的是 `SceneViewPanel` 中那部分与渲染无关、但每帧都要稳定重复执行的输入规则： +这组 helper 主要解决四件事： -- 工具快捷键何时可用 -- 右键 look drag / 中键或 view-move 左键 pan drag 如何开始和结束 -- 当前是否应该拦截鼠标与键盘 -- 如何把 ImGui 输入快照翻译成 `IViewportHostService::UpdateSceneViewInput(...)` 需要的 `SceneViewportInput` +1. 工具快捷键何时允许触发，以及触发后要切到哪个 `SceneViewportToolMode`。 +2. `look drag`、`pan drag` 的开始、互斥和结束规则。 +3. 当前帧是否需要请求 ImGui 捕获鼠标或键盘。 +4. 如何把面板层输入快照翻译成 `IViewportHostService::UpdateSceneViewInput(...)` 所需的 `SceneViewportInput`。 -当前 `SceneViewPanel::Render()` 会直接消费这些 helper，而不是自己手拼多个拖拽布尔位。 +当前 `SceneViewPanel::Render()` 会在调用这里之前先把具体按键映射成布尔值。例如： -## 公开类型与函数 +- `Q / W / E / R` 被映射成工具切换请求。 +- `W / A / S / D / E / Q`、`Shift`、`F` 被映射成飞行移动、加速和 focus-selection 请求。 -| 成员 | 说明 | -|------|------| -| [SceneViewportToolShortcutRequest](SceneViewportToolShortcutRequest.md) | 工具快捷键输入快照。 | -| [SceneViewportToolShortcutAction](SceneViewportToolShortcutAction.md) | 快捷键解析结果。 | -| [CanUseSceneViewportToolShortcut](CanUseSceneViewportToolShortcut.md) | 判断当前是否允许切换工具。 | -| [BuildSceneViewportToolShortcutAction](BuildSceneViewportToolShortcutAction.md) | 把快捷键输入翻译成目标工具和取消策略。 | -| [SceneViewportNavigationState](SceneViewportNavigationState.md) | 持久化的导航拖拽状态。 | -| [SceneViewportNavigationRequest](SceneViewportNavigationRequest.md) | 导航状态机输入。 | -| [SceneViewportNavigationUpdate](SceneViewportNavigationUpdate.md) | 导航状态机输出。 | -| [ShouldBeginSceneViewportNavigationDrag](ShouldBeginSceneViewportNavigationDrag.md) | 判断某类导航拖拽是否可开始。 | -| [IsSceneViewportPanDragButtonDown](IsSceneViewportPanDragButtonDown.md) | 判断当前 pan drag 绑定的鼠标键是否仍按下。 | -| [UpdateSceneViewportNavigationState](UpdateSceneViewportNavigationState.md) | 更新 look / pan drag 状态机。 | -| [SceneViewportCaptureRequest](SceneViewportCaptureRequest.md) | ImGui capture 计算输入。 | -| [SceneViewportCaptureFlags](SceneViewportCaptureFlags.md) | 是否捕获鼠标 / 键盘。 | -| [BuildSceneViewportCaptureFlags](BuildSceneViewportCaptureFlags.md) | 计算 capture 标志。 | -| [CanResolveSceneViewportInteraction](CanResolveSceneViewportInteraction.md) | 判断当前帧是否允许进行 Scene View 交互命中解析。 | -| [SceneViewportInputBuildRequest](SceneViewportInputBuildRequest.md) | 组装 `SceneViewportInput` 所需的输入快照。 | -| [BuildSceneViewportInput](BuildSceneViewportInput.md) | 构造交给宿主服务的 `SceneViewportInput`。 | +也就是说，这个头文件本身不绑定具体快捷键，只处理已经解码完成的输入语义。 -## 测试锚点 +## 当前语义 -`tests/Editor/test_scene_viewport_navigation.cpp` 当前覆盖了： +- 工具快捷键只有在不输入文本、也不处于 look / pan drag 中时才允许触发。 +- 左键 pan drag 只允许在 `usingViewMoveTool == true` 时开始。 +- 右键点击尝试开始 look drag，中键点击尝试开始 pan drag。 +- look drag 和 pan drag 是互斥状态；任一新拖拽开始时，另一种拖拽状态会被清掉。 +- pan drag 会记住是左键还是中键启动，并在绑定按键释放后结束，同时把 `panDragButton` 重置回 `ImGuiMouseButton_Middle`。 +- capture 规则是： + - 只要 look / pan drag 活跃，或任意 transform gizmo 处于 active 状态，就捕获鼠标。 + - 只有 look drag 活跃时才捕获键盘。 +- interaction resolve 只有在 viewport 可交互、鼠标真正在 viewport 内容区、当前不处于 ViewMove、没有导航拖拽、也没有 active gizmo 时才允许执行。 -- 快捷键在文本输入或导航拖拽期间的屏蔽逻辑 -- `Q/W/E/R` 映射与 gizmo cancel 标志 -- look drag / pan drag 的开始与结束 -- capture 标志的生成 -- `SceneViewportInput` 的滚轮、焦点、移动轴与鼠标位移映射 -- 交互解析门禁条件 +## 与 `SceneViewportInput` 的关系 + +[BuildSceneViewportInput](BuildSceneViewportInput.md) 会继续把导航状态翻译成给 viewport host service 的输入包： + +- `focused` 由 `viewportFocused`、`lookDragging`、`panDragging` 三者之一决定。 +- 鼠标滚轮在普通 hover 时进入 `mouseWheel`，在 look drag 期间改为 `flySpeedDelta`。 +- 飞行移动轴只在 `lookDragging && !wantTextInput` 时写入。 +- `mouseDelta` 只在 look / pan drag 活跃时透传。 +- `orbiting` 当前固定为 `false`。 + +## 测试覆盖 + +`tests/Editor/test_scene_viewport_navigation.cpp` 当前验证了： + +- 快捷键在文本输入或导航拖拽期间会被屏蔽。 +- 工具快捷键会产出正确的目标工具和 gizmo cancel 标志。 +- look drag / pan drag 的开始与释放收尾逻辑。 +- capture 标志的生成。 +- `SceneViewportInput` 中滚轮、焦点、飞行速度、移动轴和鼠标位移的映射。 +- interaction resolve 的准入条件。 ## 相关文档 - [Viewport](../Viewport.md) - [SceneViewportEditorModes](../SceneViewportEditorModes/SceneViewportEditorModes.md) +- [IViewportHostService](../IViewportHostService/IViewportHostService.md) - [SceneViewPanel](../../panels/SceneViewPanel/SceneViewPanel.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportNavigation/SceneViewportNavigationState.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportNavigation/SceneViewportNavigationState.md index 04a17cef..a454126b 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportNavigation/SceneViewportNavigationState.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportNavigation/SceneViewportNavigationState.md @@ -12,15 +12,25 @@ |------|------|------| | `lookDragging` | `bool` | 当前是否处于右键 look drag。 | | `panDragging` | `bool` | 当前是否处于 pan drag。 | -| `panDragButton` | `int` | 当前 pan drag 绑定的鼠标键。默认值是 `ImGuiMouseButton_Middle`。 | +| `panDragButton` | `int` | 当前 pan drag 绑定的鼠标键；默认值是 `ImGuiMouseButton_Middle`。 | ## 当前语义 -- `SceneViewPanel` 把它作为成员 `m_navigationState` 持久化保存。 -- 当前实现保证 look drag 与 pan drag 互斥。 -- `panDragButton` 只在 pan drag 开始时切到左键或中键；结束时会重置回中键默认值。 +- `SceneViewPanel` 把它作为成员 `m_navigationState` 跨帧保存。 +- 当前实现保证 look drag 与 pan drag 互斥；状态转换由 [UpdateSceneViewportNavigationState](UpdateSceneViewportNavigationState.md) 统一完成。 +- `panDragButton` 只有在 `panDragging == true` 时才有实际业务意义。 +- pan drag 结束后，`panDragButton` 会被重置回 `ImGuiMouseButton_Middle`，因此默认值同时承担“当前没有绑定中的 pan 拖拽按键”这一哨兵含义。 + +## 使用方式 + +- 这份状态会被用于： + - 导航状态机的下一帧输入 + - [BuildSceneViewportCaptureFlags](BuildSceneViewportCaptureFlags.md) 生成 ImGui capture 标志 + - [BuildSceneViewportInput](BuildSceneViewportInput.md) 生成给 viewport host service 的导航输入 + - [CanResolveSceneViewportInteraction](CanResolveSceneViewportInteraction.md) 作为交互门禁的一部分 ## 相关文档 - [SceneViewportNavigation](SceneViewportNavigation.md) - [UpdateSceneViewportNavigationState](UpdateSceneViewportNavigationState.md) +- [BuildSceneViewportInput](BuildSceneViewportInput.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportNavigation/SceneViewportNavigationUpdate.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportNavigation/SceneViewportNavigationUpdate.md index 4ca749cf..c8c04f97 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportNavigation/SceneViewportNavigationUpdate.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportNavigation/SceneViewportNavigationUpdate.md @@ -10,16 +10,26 @@ | 字段 | 类型 | 说明 | |------|------|------| -| `state` | `SceneViewportNavigationState` | 更新后的导航状态。 | -| `beginLookDrag` | `bool` | 当前帧是否开始 look drag。 | -| `beginPanDrag` | `bool` | 当前帧是否开始 pan drag。 | +| `state` | `SceneViewportNavigationState` | 更新后的可持久化导航状态。 | +| `beginLookDrag` | `bool` | 当前帧是否刚开始 look drag。 | +| `beginPanDrag` | `bool` | 当前帧是否刚开始 pan drag。 | | `beginLeftPanDrag` | `bool` | 当前帧是否以左键开始 pan drag。 | | `beginMiddlePanDrag` | `bool` | 当前帧是否以中键开始 pan drag。 | ## 当前语义 -- `beginPanDrag` 是 `beginLeftPanDrag || beginMiddlePanDrag` 的合成位。 -- `SceneViewPanel::Render()` 当前会把这些 begin 标志连同 tool command 与 interaction action 一起交给 `ShouldFocusSceneViewportAfterInteraction(...)`，再决定是否调用 `ImGui::SetWindowFocus()`。 +- `beginPanDrag` 是 `beginLeftPanDrag || beginMiddlePanDrag` 的聚合位。 +- `state` 已经包含本帧的开始或结束转换结果，调用方通常会立即把它回写成下一帧的 `m_navigationState`。 +- 四个 `begin*` 字段都是“只在本帧为真”的边沿事件，不应该跨帧持久化。 + +## 当前使用位置 + +当前 `SceneViewPanel::Render()` 会把这些 begin 标志与工具切换命令、interaction actions 一起交给 [ShouldFocusSceneViewportAfterInteraction](../SceneViewportInteractionFrame/ShouldFocusSceneViewportAfterInteraction.md)，再决定是否调用 `ImGui::SetWindowFocus()`。 + +## 设计边界 + +- 这个结构只描述导航状态机的输出，不包含 ImGui capture 结果，也不直接表示 viewport 输入包。 +- 如果当前帧既没有新拖拽开始，也有旧拖拽结束，`state` 仍然会正确反映收尾结果，而 begin 标志保持 `false`。 ## 相关文档 diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportNavigation/SceneViewportToolShortcutAction.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportNavigation/SceneViewportToolShortcutAction.md index 63d5f79f..da3081ef 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportNavigation/SceneViewportToolShortcutAction.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportNavigation/SceneViewportToolShortcutAction.md @@ -10,7 +10,7 @@ | 字段 | 类型 | 说明 | |------|------|------| -| `targetTool` | `SceneViewportToolMode` | 快捷键命中的目标工具。默认值是 `Move`。 | +| `targetTool` | `SceneViewportToolMode` | 快捷键命中的目标工具；默认值是 `Move`。 | | `triggered` | `bool` | 当前帧是否真的形成了工具切换动作。 | | `cancelMoveGizmo` | `bool` | 切换时是否应取消 move gizmo 正在进行的拖拽。 | | `cancelRotateGizmo` | `bool` | 切换时是否应取消 rotate gizmo 正在进行的拖拽。 | @@ -18,14 +18,23 @@ ## 当前语义 -- `HasAction()` 只检查 `triggered`。 -- 当前实现里： - - `ViewMove` 会取消三类 gizmo drag。 - - `Move` 会取消 rotate / scale drag。 - - `Rotate` 会取消 move / scale drag。 - - `Scale` 会取消 move / rotate drag。 +- `HasAction()` 只检查 `triggered`；当 `triggered == false` 时，`targetTool` 的默认值没有业务意义。 +- 当前实现里的 cancel 规则是： + - `ViewMove`：取消 move / rotate / scale 三类 gizmo drag + - `Move`：取消 rotate / scale drag + - `Rotate`：取消 move / scale drag + - `Scale`：取消 move / rotate drag +- 这个结构只表示“快捷键侧”的工具切换结果；真正的最终命令还会在 [BuildSceneViewportToolCommand](../SceneViewportChrome/BuildSceneViewportToolCommand.md) 中与工具栏 overlay 点击结果合并。 + +## 测试覆盖 + +`tests/Editor/test_scene_viewport_navigation.cpp` 当前验证了： + +- 文本输入或导航拖拽期间不会产生动作。 +- `ViewMove`、`Rotate` 等目标工具会生成正确的 cancel 标志组合。 ## 相关文档 - [SceneViewportNavigation](SceneViewportNavigation.md) - [BuildSceneViewportToolShortcutAction](BuildSceneViewportToolShortcutAction.md) +- [BuildSceneViewportToolCommand](../SceneViewportChrome/BuildSceneViewportToolCommand.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportNavigation/UpdateSceneViewportNavigationState.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportNavigation/UpdateSceneViewportNavigationState.md index 08705152..00609fbc 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportNavigation/UpdateSceneViewportNavigationState.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportNavigation/UpdateSceneViewportNavigationState.md @@ -1,36 +1,46 @@ # UpdateSceneViewportNavigationState -**命名空间**: `XCEngine::Editor` - -**类型**: `function` - -**源文件**: `editor/src/Viewport/SceneViewportNavigation.h` - -## 签名 +更新 Scene View 的 look drag / pan drag 状态机。 ```cpp SceneViewportNavigationUpdate UpdateSceneViewportNavigationState( const SceneViewportNavigationRequest& request); ``` -## 作用 +## 当前行为 -更新 Scene View 的 look drag / pan drag 状态机。 +- 左键 pan drag 只有在 `request.usingViewMoveTool == true` 时才允许开始。 +- 右键点击满足条件时会触发 `beginLookDrag`。 +- 中键点击满足条件时会触发 `beginMiddlePanDrag`。 +- 左键 view-move pan 或中键 pan 任一触发后，`beginPanDrag` 都会变成 `true`。 +- look drag 开始时会把 `state.lookDragging` 置为 `true`，并强制清掉 `state.panDragging`。 +- pan drag 开始时会把 `state.panDragging` 置为 `true`，并强制清掉 `state.lookDragging`，同时记录当前绑定的 `panDragButton`。 +- look drag 期间只要右键释放，就会结束 look drag。 +- pan drag 期间只要绑定的拖拽按键释放，就会结束 pan drag，并把 `panDragButton` 重置回 `ImGuiMouseButton_Middle`。 -## 当前实现行为 +## 前置条件 -- 左键 pan drag 只有在 `usingViewMoveTool == true` 时才允许开始。 -- 右键点击会尝试开始 look drag。 -- 中键点击会尝试开始 pan drag。 -- 一旦开始 look drag，会强制清掉 `panDragging`。 -- 一旦开始 pan drag，会强制清掉 `lookDragging`，并把 `panDragButton` 记成左键或中键。 -- 如果 `lookDragging == true` 但右键已松开，会结束 look drag。 -- 如果 `panDragging == true` 且当前绑定鼠标键已松开，会结束 pan drag，并把 `panDragButton` 重置为 `ImGuiMouseButton_Middle`。 +每一种拖拽开始都依赖 [ShouldBeginSceneViewportNavigationDrag](ShouldBeginSceneViewportNavigationDrag.md) 的统一门禁： -`tests/Editor/test_scene_viewport_navigation.cpp` 当前验证了 look drag / pan drag 的开始与释放收尾逻辑。 +- viewport 必须可交互。 +- 鼠标必须在 viewport 内容区。 +- 当前拖拽尚未开始。 +- 另一种拖拽不能同时活跃。 +- 当前不能有 active gizmo。 +- 必须收到对应按键的本帧点击事件。 + +## 返回值说明 + +- `SceneViewportNavigationUpdate.state` 是可持久化回下一帧的导航状态。 +- `beginLookDrag / beginPanDrag / beginLeftPanDrag / beginMiddlePanDrag` 都是“只在本帧为真”的边沿标志，适合拿来做焦点切换或输入路由决策。 + +## 测试覆盖 + +`tests/Editor/test_scene_viewport_navigation.cpp` 当前验证了 look / pan drag 的开始条件、结束条件以及 `panDragButton` 的重置行为。 ## 相关文档 - [SceneViewportNavigation](SceneViewportNavigation.md) +- [SceneViewportNavigationRequest](SceneViewportNavigationRequest.md) - [SceneViewportNavigationState](SceneViewportNavigationState.md) - [SceneViewportNavigationUpdate](SceneViewportNavigationUpdate.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayBuilder/Build.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayBuilder/Build.md index b7920f58..ed3b75ac 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayBuilder/Build.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayBuilder/Build.md @@ -20,35 +20,35 @@ SceneViewportOverlayFrameData Build( ## 作用 -基于当前 builder 持有的 provider registry，构建一帧 Scene View editor overlay 数据。 +基于当前 builder 持有的 provider registry，构建一帧统一的 Scene View editor overlay 数据。 ## 当前实现行为 -### 1. 先初始化返回值 +### 1. 先准备返回值 -函数一开始会创建： +函数一开始就会创建： ```cpp SceneViewportOverlayFrameData frameData = {}; frameData.overlay = overlay; ``` -因此即使后续走早退路径，返回值里也会保留传入的 `overlay` 快照。 +因此即使后续走早退路径，返回值里也会保留这份 `overlay` 快照。 -### 2. 无效输入时直接返回空 frame +### 2. 检查最小前置条件 -当前会在以下任一条件成立时直接返回： +当前会在以下任一条件成立时直接返回空 frame： - `overlay.valid == false` -- `viewportWidth == 0` -- `viewportHeight == 0` +- `viewportWidth == 0u` +- `viewportHeight == 0u` - `context.GetSceneManager().GetScene() == nullptr` -这里不会抛异常，也不会尝试构建部分 overlay。 +这里不会尝试做部分构建，也不会抛异常。 -### 3. 组装 build context 并交给 provider registry +### 3. 组装 build context -当前实现会构造一份： +当前会构造： ```cpp SceneViewportOverlayBuildContext{ @@ -62,31 +62,54 @@ SceneViewportOverlayBuildContext{ } ``` -然后调用： +### 4. 分发给 provider registry + +随后直接调用： ```cpp m_providerRegistry.AppendOverlay(buildContext, frameData); ``` -这意味着： +这说明： -- `Build(...)` 自己不直接生成 camera / light / gizmo 图元 -- 具体追加哪些 `worldSprites`、`worldLines`、`screenTriangles`、`handleRecords` 由当前 registry 中的 provider 决定 +- `Build(...)` 自己不直接生成 camera/light/gizmo primitive +- 具体追加哪些 sprite、line、triangle、handle record 由 registry 中的 provider 决定 - 输出顺序当前跟随 provider 的注册顺序 ## 默认 builder 的输出来源 -默认构造的 builder 当前使用 [BuildDefaultSceneViewportOverlayProviderRegistry](../SceneViewportOverlayProviders/BuildDefaultSceneViewportOverlayProviderRegistry.md)，所以默认 `Build(...)` 的 editor overlay 主要来自： +默认构造的 builder 当前使用 [BuildDefaultSceneViewportOverlayProviderRegistry](../SceneViewportOverlayProviders/BuildDefaultSceneViewportOverlayProviderRegistry.md)，所以默认 `Build(...)` 的 overlay 主要来自： - [CreateSceneViewportCameraOverlayProvider](../SceneViewportOverlayProviders/CreateSceneViewportCameraOverlayProvider.md) - [CreateSceneViewportLightOverlayProvider](../SceneViewportOverlayProviders/CreateSceneViewportLightOverlayProvider.md) - [CreateSceneViewportTransformGizmoOverlayProvider](../SceneViewportOverlayProviders/CreateSceneViewportTransformGizmoOverlayProvider.md) -## 当前实现边界 +## 与缓存系统的边界 -- 该方法不缓存构建结果；每次调用都会重新走一遍 registry 分发。 -- 该方法只构建数据，不负责 Scene View overlay pass 或 ImGui HUD 绘制。 -- 若调用方传入自定义 registry，返回内容会随自定义 provider 集合变化。 +`Build(...)` 每次调用都会重新执行 provider 分发，它本身不做缓存判断。 + +“本帧到底该不该重建 overlay”这件事当前交给： + +- [SceneViewportOverlayFrameCache](../SceneViewportOverlayFrameCache/SceneViewportOverlayFrameCache.md) + +来判断。 + +## 测试锚点 + +- `OverlayBuilderUsesDefaultRegistryToAggregateCameraAndLightProviders` +- `OverlayBuilderAppendsFormalTransformGizmoProviderOutput` + +## 设计说明 + +builder 的关键价值是把 Scene View overlay 构建入口标准化，而不是把所有 overlay 逻辑集中到一个函数里。 + +这意味着： + +- provider 可以单独测试 +- registry 可以单独验证顺序语义 +- builder 只负责把输入组装好并发出去 + +这种分层比“在一个 Build 函数里手写所有 overlay 细节”更适合长期扩展。 ## 相关文档 @@ -95,3 +118,4 @@ m_providerRegistry.AppendOverlay(buildContext, frameData); - [GetProviderRegistry](GetProviderRegistry.md) - [SceneViewportOverlayBuildContext](../SceneViewportOverlayProviders/SceneViewportOverlayBuildContext.md) - [SceneViewportOverlayProviderRegistry](../SceneViewportOverlayProviders/SceneViewportOverlayProviderRegistry.md) +- [SceneViewportOverlayFrameCache](../SceneViewportOverlayFrameCache/SceneViewportOverlayFrameCache.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayBuilder/Constructor.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayBuilder/Constructor.md index 7c1014c2..9fab4bb9 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayBuilder/Constructor.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayBuilder/Constructor.md @@ -15,7 +15,7 @@ explicit SceneViewportOverlayBuilder(SceneViewportOverlayProviderRegistry provid ## 作用 -创建一个持有 provider registry 的 Scene View 世界 overlay builder。 +创建一个持有 overlay provider registry 的 Scene View overlay builder。 ## 当前实现行为 @@ -33,9 +33,9 @@ SceneViewportOverlayBuilder::SceneViewportOverlayBuilder() 1. camera overlay provider 2. light overlay provider -3. transform-gizmo overlay provider +3. transform gizmo overlay provider -### 传入自定义 registry +### 自定义 registry 构造 第二个重载当前等价于： @@ -50,15 +50,20 @@ SceneViewportOverlayBuilder::SceneViewportOverlayBuilder( - builder 会按值接管调用方提供的 registry - registry 内部 provider 的所有权也会一起转移 -- 后续 [Build](Build.md) 只会使用这份 registry +- 后续 `Build(...)` 只会使用这份 registry -## 当前实现边界 +## 设计说明 -- 构造阶段不访问 scene、selection 或 GPU 资源。 -- 实际 overlay 内容仍取决于后续 `Build(...)` 时传入的 context 与 gizmo state。 +默认构造路径提供的是“商业引擎式编辑器 Scene View 的标准组合”，而自定义 registry 构造则提供扩展点。 + +这种双路径设计很实用： + +- 绝大多数场景直接用默认行为 +- 测试、实验功能或特殊编辑模式可以注入自定义 provider 集合 ## 相关文档 - [SceneViewportOverlayBuilder](SceneViewportOverlayBuilder.md) - [Build](Build.md) - [BuildDefaultSceneViewportOverlayProviderRegistry](../SceneViewportOverlayProviders/BuildDefaultSceneViewportOverlayProviderRegistry.md) +- [SceneViewportOverlayProviderRegistry](../SceneViewportOverlayProviders/SceneViewportOverlayProviderRegistry.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayBuilder/GetProviderRegistry.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayBuilder/GetProviderRegistry.md index 48d38161..8f9b8b72 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayBuilder/GetProviderRegistry.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayBuilder/GetProviderRegistry.md @@ -27,21 +27,20 @@ return m_providerRegistry; 因此： -- `const` 重载适合读取当前 registry 配置 -- 可变重载允许调用方继续向 registry 注册或调整 provider +- `const` 重载适合检查当前 registry 配置 +- 可变重载允许调用方继续注册或调整 provider -对可变重载返回值的修改，会影响后续 [Build](Build.md) 使用的 provider 集合。 +## 生命周期语义 -## 所有权与生命周期 +- 返回的是对内部成员的引用，不是拷贝 +- registry 的所有权仍属于 `SceneViewportOverlayBuilder` +- 对可变重载返回值所做的修改，会影响后续 `Build(...)` 的输出 -- 返回的是对内部成员的引用，不是拷贝。 -- registry 及其内部 provider 的所有权仍然属于 `SceneViewportOverlayBuilder`。 -- 只要 builder 存活，这个引用就保持有效；builder 销毁后引用随之失效。 +## 设计说明 -## 当前实现边界 +builder 没有把 registry 完全封死，这是一个有意保留的扩展点。 -- 该方法本身不触发 overlay 重建。 -- 该方法不做空值检查；builder 始终持有一份 registry 成员。 +它允许上层在不重写 builder 逻辑的前提下，替换 provider 组合或追加新的 provider，从而扩展 Scene View overlay 语义。 ## 相关文档 diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayBuilder/SceneViewportOverlayBuilder.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayBuilder/SceneViewportOverlayBuilder.md index 384c8c85..80587086 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayBuilder/SceneViewportOverlayBuilder.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayBuilder/SceneViewportOverlayBuilder.md @@ -6,71 +6,89 @@ **源文件**: `editor/src/Viewport/SceneViewportOverlayBuilder.h` -**描述**: 持有一个 [SceneViewportOverlayProviderRegistry](../SceneViewportOverlayProviders/SceneViewportOverlayProviderRegistry.md)，把 Scene View editor overlay 的 build context 分发给各个 provider，并汇总成一帧 [SceneViewportOverlayFrameData](../SceneViewportEditorOverlayData/SceneViewportEditorOverlayData.md)。 +**描述**: 持有一份 `SceneViewportOverlayProviderRegistry`，把一帧 Scene View 构建输入分发给 provider 体系，并汇总成统一的 `SceneViewportOverlayFrameData`。 ## 概览 -`SceneViewportOverlayBuilder` 当前已经不是“无状态 helper + static Build(...)”。 +`SceneViewportOverlayBuilder` 是 Scene View editor overlay 数据链里的“聚合器”。 -按 `SceneViewportOverlayBuilder.h/.cpp` 的当前实现，它内部直接持有： +它不直接知道相机 icon、灯光 helper 或 transform gizmo 应该怎么画；这些细节已经被拆到了 [SceneViewportOverlayProviders](../SceneViewportOverlayProviders/SceneViewportOverlayProviders.md) 中。 -```cpp -SceneViewportOverlayProviderRegistry m_providerRegistry = {}; -``` +它的职责更明确： -而 [Build](Build.md) 做的事情也不再是自己硬编码相机 / 灯光 / gizmo overlay 细节，而是： +1. 持有 provider registry +2. 在一帧构建时准备好统一的 build context +3. 让 registry 按顺序把各 provider 的输出汇总到一份 `SceneViewportOverlayFrameData` -1. 检查 `overlay`、视口尺寸和当前 scene 是否有效。 -2. 组装一份 [SceneViewportOverlayBuildContext](../SceneViewportOverlayProviders/SceneViewportOverlayBuildContext.md)。 -3. 调用 `m_providerRegistry.AppendOverlay(...)`，把 provider 输出追加进同一份 `SceneViewportOverlayFrameData`。 +这让 Scene View overlay 体系具备了很强的可扩展性。新增 overlay 类型时，通常不需要改 builder 主流程，只需要增加 provider 并放进 registry。 -因此，“这一帧 Scene View 里会出现哪些 scene icon、world line、screen triangle、handle record”，当前取决于 builder 持有的 provider registry，而不是这个类本身写死的图元集合。 +## `ViewportHostService` 调用链中的位置 + +按当前实现，`ViewportHostService::EnsureSceneViewEditorOverlayFrameData(...)` 会： + +1. 解析当前 Scene View 视口尺寸 +2. 读取 `SceneViewportOverlayData` +3. 构建内容签名并决定是否需要重建缓存 +4. 在需要时调用 `m_sceneViewportOverlayBuilder.Build(...)` +5. 把结果写进 `SceneViewportOverlayFrameCache` + +因此 builder 本身不负责缓存，只负责“真的要重建时，如何构建这一帧 overlay 数据”。 ## 默认 registry 语义 -[Constructor](Constructor.md) 的默认路径当前会调用 [BuildDefaultSceneViewportOverlayProviderRegistry](../SceneViewportOverlayProviders/BuildDefaultSceneViewportOverlayProviderRegistry.md)，因此默认 builder 会聚合： +默认构造路径会调用 [BuildDefaultSceneViewportOverlayProviderRegistry](../SceneViewportOverlayProviders/BuildDefaultSceneViewportOverlayProviderRegistry.md)，因此默认 builder 当前会聚合： - camera overlay provider - light overlay provider - transform gizmo overlay provider +这三者组合后，默认输出能覆盖： + +- `worldSprites` +- `worldLines` +- `screenTriangles` +- `handleRecords` + ## 生命周期与所有权 - builder 按值持有 `SceneViewportOverlayProviderRegistry` -- registry 再按 `std::unique_ptr` 持有各个 provider -- builder 本身不持有 GPU 资源，也不缓存 frame data -- Scene View overlay 的缓存当前由 [ViewportHostService](../ViewportHostService/ViewportHostService.md) 负责，而不是由 builder 负责 +- registry 再按 `std::unique_ptr` 持有 provider +- builder 自身不持有 GPU 资源 +- builder 不缓存 `SceneViewportOverlayFrameData` -这意味着它更像“provider 聚合器”，而不是“Scene View overlay 缓存器”。 +这说明它更接近“overlay 数据聚合器”，而不是“overlay renderer”或“overlay cache”。 ## 当前公开成员 | 成员 | 说明 | |------|------| | [Constructor](Constructor.md) | 创建默认 builder，或接管一份自定义 provider registry。 | -| [Build](Build.md) | 基于当前 registry 构建一帧 editor overlay 数据。 | +| [Build](Build.md) | 基于当前 provider registry 构建一帧 overlay 数据。 | | [GetProviderRegistry](GetProviderRegistry.md) | 访问 builder 当前持有的 provider registry。 | -## 与测试的对应关系 +## 测试锚点 -`tests/Editor/test_scene_viewport_overlay_providers.cpp` 当前覆盖了： +`tests/Editor/test_scene_viewport_overlay_providers.cpp` 当前直接覆盖了两类关键行为： -- registry 会按注册顺序追加 provider 输出。 -- 默认 builder 会聚合 camera / light provider 的输出。 -- 传入 `SceneViewportTransformGizmoOverlayState` 时，builder 会把 gizmo provider 产出的 `screenTriangles / handleRecords` 一并带上。 +- 默认 builder 会聚合 camera / light provider 的输出 +- 传入 `SceneViewportTransformGizmoOverlayState` 时，builder 会把 gizmo provider 的输出一起带进 frame data -## 当前实现边界 +## 设计说明 -- builder 只负责组装 `SceneViewportOverlayBuildContext` 并分发给 provider，不负责 GPU pass 或 ImGui HUD 绘制。 -- provider 的执行顺序当前就是 registry 的注册顺序。 -- 默认 registry 当前会注册 camera / light / transform gizmo 三类 provider；更多 overlay 需要通过 provider 扩展进入这条链路。 +这类 builder 在商业引擎编辑器里很常见。它的价值不在于“多了一层类”，而在于让 Scene View overlay 体系有一个稳定的组合边界： + +- provider 负责单项语义 +- registry 负责顺序与汇总 +- builder 负责一帧构建入口 + +这样相机/灯光/gizmo 三类 overlay 可以独立演进，又不会把 `ViewportHostService` 继续膨胀成“什么都懂的大类”。 ## 相关文档 -- [Constructor](Constructor.md) - [Build](Build.md) +- [Constructor](Constructor.md) - [GetProviderRegistry](GetProviderRegistry.md) - [SceneViewportOverlayProviders](../SceneViewportOverlayProviders/SceneViewportOverlayProviders.md) -- [SceneViewportOverlayProviderRegistry](../SceneViewportOverlayProviders/SceneViewportOverlayProviderRegistry.md) -- [SceneViewportOverlayBuildContext](../SceneViewportOverlayProviders/SceneViewportOverlayBuildContext.md) +- [SceneViewportOverlayFrameCache](../SceneViewportOverlayFrameCache/SceneViewportOverlayFrameCache.md) +- [SceneViewportEditorOverlayData](../SceneViewportEditorOverlayData/SceneViewportEditorOverlayData.md) - [ViewportHostService](../ViewportHostService/ViewportHostService.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayFrameCache/AreEqualSceneViewportOverlayData.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayFrameCache/AreEqualSceneViewportOverlayData.md new file mode 100644 index 00000000..56b4aee6 --- /dev/null +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayFrameCache/AreEqualSceneViewportOverlayData.md @@ -0,0 +1,49 @@ +# AreEqualSceneViewportOverlayData + +**命名空间**: `XCEngine::Editor` + +**类型**: `function` + +**源文件**: `editor/src/Viewport/SceneViewportOverlayFrameCache.h` + +## 签名 + +```cpp +bool AreEqualSceneViewportOverlayData( + const SceneViewportOverlayData& lhs, + const SceneViewportOverlayData& rhs); +``` + +## 作用 + +以 epsilon 容差比较两份 Scene View 相机 overlay 数据是否等价。 + +## 当前实现行为 + +- 当前使用固定容差 `1e-4f`。 +- 会比较： + - `valid` + - `cameraPosition` + - `cameraForward` + - `cameraRight` + - `cameraUp` + - `verticalFovDegrees` + - `nearClipPlane` + - `farClipPlane` + - `orbitDistance` + +## 设计含义 + +Scene View overlay frame 是否需要重建，不能简单依赖逐位相等。 + +当前这层 helper 的作用是避免因为微小浮点抖动而让 overlay frame 缓存失效，但仍然会在相机姿态出现可见变化时触发重建。 + +## 测试锚点 + +- `OverlayDataComparisonUsesEpsilonTolerance` + +## 相关文档 + +- [SceneViewportOverlayFrameCache](SceneViewportOverlayFrameCache.md) +- [ShouldRebuildSceneViewportOverlayFrameCache](ShouldRebuildSceneViewportOverlayFrameCache.md) +- [SceneView Overlay Contracts](../IViewportHostService/SceneView-Overlay-Contracts.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayFrameCache/BuildSceneViewportOverlayContentSignature.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayFrameCache/BuildSceneViewportOverlayContentSignature.md new file mode 100644 index 00000000..06d14f46 --- /dev/null +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayFrameCache/BuildSceneViewportOverlayContentSignature.md @@ -0,0 +1,63 @@ +# BuildSceneViewportOverlayContentSignature + +**命名空间**: `XCEngine::Editor` + +**类型**: `function` + +**源文件**: `editor/src/Viewport/SceneViewportOverlayFrameCache.h` + +## 签名 + +```cpp +uint64_t BuildSceneViewportOverlayContentSignature( + const Components::Scene* scene, + const std::vector& selectedObjectIds); +``` + +## 作用 + +为 Scene View overlay frame 的“场景内容是否变化”生成一个稳定签名。 + +## 当前实现行为 + +当前实现使用一套 FNV 风格的 `uint64_t` 哈希流程，依次折叠： + +1. 选中对象数量与每个 `selectedObjectIds` +2. 场景中每个 `CameraComponent` + - 组件种类标记 + - `GameObject` id + - 组件是否启用 + - 对象是否在层级中激活 + - 若相机和对象都有效且有 `TransformComponent` + - 位置 / 旋转 / 缩放 + - 投影类型 + - `fieldOfView` + - `orthographicSize` + - `nearClipPlane / farClipPlane` + - `viewportRect` +3. 场景中每个 `LightComponent` + - 组件种类标记 + - `GameObject` id + - 组件是否启用 + - 对象是否在层级中激活 + - 若灯光和对象都有效且有 `TransformComponent` + - 位置 / 旋转 / 缩放 + - `lightType` + +`scene == nullptr` 时，当前签名只会反映选中列表。 + +## 当前边界 + +- 这里不直接哈希 `SceneViewportOverlayFrameData` 的最终 primitive 集合。 +- 当前签名只覆盖 overlay builder 默认依赖的上游输入之一：场景里的相机、灯光以及选中集。 +- transform gizmo overlay 的逐帧变化不走这里，而是由 `transformGizmoOverlayDirty` 单独触发缓存重建。 + +## 测试锚点 + +- `ContentSignatureTracksSceneCameraAndLightState` + +## 相关文档 + +- [SceneViewportOverlayFrameCache](SceneViewportOverlayFrameCache.md) +- [ShouldRebuildSceneViewportOverlayFrameCache](ShouldRebuildSceneViewportOverlayFrameCache.md) +- [SceneViewportOverlayBuilder](../SceneViewportOverlayBuilder/SceneViewportOverlayBuilder.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayFrameCache/ResetSceneViewportOverlayFrameCacheState.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayFrameCache/ResetSceneViewportOverlayFrameCacheState.md new file mode 100644 index 00000000..ac307265 --- /dev/null +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayFrameCache/ResetSceneViewportOverlayFrameCacheState.md @@ -0,0 +1,39 @@ +# ResetSceneViewportOverlayFrameCacheState + +**命名空间**: `XCEngine::Editor` + +**类型**: `function` + +**源文件**: `editor/src/Viewport/SceneViewportOverlayFrameCache.h` + +## 签名 + +```cpp +void ResetSceneViewportOverlayFrameCacheState( + SceneViewportOverlayFrameCacheState& cacheState); +``` + +## 作用 + +清空 Scene View overlay frame 缓存状态。 + +## 当前实现行为 + +- 当前实现直接执行 `cacheState = {};` +- 因此会同时清空： + - `frameData` + - `scene` + - `selectedObjectIds` + - `viewportWidth / viewportHeight` + - `contentSignature` + - `cached` + +## 当前使用位置 + +- `ViewportHostService::EnsureSceneViewEditorOverlayFrameData(...)` 在 Scene View 私有相机不可用时会重置这份缓存。 +- `ViewportHostService` 的其它失败路径也可以通过这里显式丢弃上一份 overlay frame。 + +## 相关文档 + +- [SceneViewportOverlayFrameCache](SceneViewportOverlayFrameCache.md) +- [SceneViewportOverlayFrameCacheState](SceneViewportOverlayFrameCacheState.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayFrameCache/ResolveSceneViewportOverlayFrameViewportSize.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayFrameCache/ResolveSceneViewportOverlayFrameViewportSize.md new file mode 100644 index 00000000..97e82271 --- /dev/null +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayFrameCache/ResolveSceneViewportOverlayFrameViewportSize.md @@ -0,0 +1,46 @@ +# ResolveSceneViewportOverlayFrameViewportSize + +**命名空间**: `XCEngine::Editor` + +**类型**: `function` + +**源文件**: `editor/src/Viewport/SceneViewportOverlayFrameCache.h` + +## 签名 + +```cpp +void ResolveSceneViewportOverlayFrameViewportSize( + uint32_t requestedWidth, + uint32_t requestedHeight, + uint32_t renderWidth, + uint32_t renderHeight, + uint32_t& outWidth, + uint32_t& outHeight); +``` + +## 作用 + +解析 Scene View overlay frame 构建阶段应使用的视口尺寸。 + +## 当前实现行为 + +- `requestedWidth > 0` 时，`outWidth = requestedWidth`；否则回退到 `renderWidth` +- `requestedHeight > 0` 时，`outHeight = requestedHeight`；否则回退到 `renderHeight` + +## 设计含义 + +Scene View overlay 的数学构建需要稳定的“逻辑视口尺寸”，但宿主服务同时又可能复用已有 render target。 + +把这层规则收口成 helper 之后： + +- `ViewportHostService` 不需要在多处重复判断 requested size 和实际 render target size +- 测试可以直接锁定 fallback 规则，而不必通过完整 viewport 渲染路径间接验证 + +## 测试锚点 + +- `ResolveViewportSizePrefersRequestedDimensions` + +## 相关文档 + +- [SceneViewportOverlayFrameCache](SceneViewportOverlayFrameCache.md) +- [ViewportHostService Scene View Overlay Frame Data](../ViewportHostService/SceneView-Overlay-Frame-Data.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayFrameCache/SceneViewportOverlayFrameCache.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayFrameCache/SceneViewportOverlayFrameCache.md new file mode 100644 index 00000000..f69e906f --- /dev/null +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayFrameCache/SceneViewportOverlayFrameCache.md @@ -0,0 +1,67 @@ +# SceneViewportOverlayFrameCache + +**命名空间**: `XCEngine::Editor` + +**类型**: `struct + free functions` + +**源文件**: `editor/src/Viewport/SceneViewportOverlayFrameCache.h` + +**描述**: 为 Scene View canonical overlay frame 提供缓存状态、内容签名、重建判定和缓存写回 helper。 + +## 概览 + +`SceneViewportOverlayFrameCache.h` 解决的是一个很具体的问题： + +- `SceneViewportOverlayBuilder` 能构建一份完整 `SceneViewportOverlayFrameData` +- 但 `ViewportHostService` 不能在每次 hit-test 或渲染前都盲目重建这份 frame data + +当前这组 helper 把宿主服务真正依赖的缓存规则收拢成单独一层： + +- 用 [SceneViewportOverlayFrameCacheState](SceneViewportOverlayFrameCacheState.md) 保存上一份 frame data 和对应元数据 +- 用 [ResolveSceneViewportOverlayFrameViewportSize](ResolveSceneViewportOverlayFrameViewportSize.md) 统一 Scene View overlay 构建时使用的视口尺寸 +- 用 [BuildSceneViewportOverlayContentSignature](BuildSceneViewportOverlayContentSignature.md) 折叠场景相机、灯光和选中列表的内容签名 +- 用 [ShouldRebuildSceneViewportOverlayFrameCache](ShouldRebuildSceneViewportOverlayFrameCache.md) 判断这一帧是否必须重建 +- 用 [UpdateSceneViewportOverlayFrameCacheState](UpdateSceneViewportOverlayFrameCacheState.md) 把最新 frame data 写回缓存 + +它当前主要服务于 `ViewportHostService::EnsureSceneViewEditorOverlayFrameData(...)`。 + +## 公开成员 + +| 成员 | 说明 | +|------|------| +| [SceneViewportOverlayFrameCacheState](SceneViewportOverlayFrameCacheState.md) | Scene View overlay frame 的缓存状态。 | +| [ResetSceneViewportOverlayFrameCacheState](ResetSceneViewportOverlayFrameCacheState.md) | 清空缓存状态。 | +| [ResolveSceneViewportOverlayFrameViewportSize](ResolveSceneViewportOverlayFrameViewportSize.md) | 解析 overlay frame 构建尺寸。 | +| [AreEqualSceneViewportOverlayData](AreEqualSceneViewportOverlayData.md) | 以 epsilon 容差比较两份相机 overlay 数据。 | +| [BuildSceneViewportOverlayContentSignature](BuildSceneViewportOverlayContentSignature.md) | 为场景相机、灯光和选中列表生成稳定内容签名。 | +| [ShouldRebuildSceneViewportOverlayFrameCache](ShouldRebuildSceneViewportOverlayFrameCache.md) | 根据缓存状态、场景、视口、选中集和 dirty 标记判断是否需要重建。 | +| [UpdateSceneViewportOverlayFrameCacheState](UpdateSceneViewportOverlayFrameCacheState.md) | 写回最新 frame data 和缓存元数据。 | + +## 当前调用链 + +按 `ViewportHostService.h` 的当前实现，Scene View overlay frame 缓存路径大致是： + +1. `ResolveSceneViewportOverlayFrameViewportSize(...)` +2. `BuildSceneViewportOverlayContentSignature(...)` +3. `ShouldRebuildSceneViewportOverlayFrameCache(...)` +4. 仅在需要时调用 `m_sceneViewportOverlayBuilder.Build(...)` +5. `UpdateSceneViewportOverlayFrameCacheState(...)` + +这意味着当前 `GetSceneViewEditorOverlayFrameData(...)` 已经不是“每次调用都重建”，而是明确走缓存判定。 + +## 测试覆盖 + +`tests/Editor/test_scene_viewport_overlay_frame_cache.cpp` 当前直接覆盖了： + +- 视口尺寸解析 +- 相机 overlay 数据的 epsilon 比较 +- 缓存重建判定 +- 场景内容签名对相机 / 灯光状态变化的跟踪 + +## 相关文档 + +- [Viewport](../Viewport.md) +- [ViewportHostService](../ViewportHostService/ViewportHostService.md) +- [ViewportHostService Scene View Overlay Frame Data](../ViewportHostService/SceneView-Overlay-Frame-Data.md) +- [SceneViewportOverlayBuilder](../SceneViewportOverlayBuilder/SceneViewportOverlayBuilder.md) +- [SceneViewportEditorOverlayData](../SceneViewportEditorOverlayData/SceneViewportEditorOverlayData.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayFrameCache/SceneViewportOverlayFrameCacheState.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayFrameCache/SceneViewportOverlayFrameCacheState.md new file mode 100644 index 00000000..fada5486 --- /dev/null +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayFrameCache/SceneViewportOverlayFrameCacheState.md @@ -0,0 +1,42 @@ +# SceneViewportOverlayFrameCacheState + +**命名空间**: `XCEngine::Editor` + +**类型**: `struct` + +**源文件**: `editor/src/Viewport/SceneViewportOverlayFrameCache.h` + +## 描述 + +保存 Scene View canonical overlay frame 的上一帧缓存结果及其重建元数据。 + +## 当前字段 + +| 字段 | 类型 | 语义 | +|------|------|------| +| `frameData` | `SceneViewportOverlayFrameData` | 当前缓存的 overlay frame。 | +| `scene` | `const Components::Scene*` | 生成这份缓存时对应的活动场景指针。 | +| `selectedObjectIds` | `std::vector` | 生成缓存时的选中对象 id 列表。 | +| `viewportWidth` | `uint32_t` | 构建这份 frame data 时使用的宽度。 | +| `viewportHeight` | `uint32_t` | 构建这份 frame data 时使用的高度。 | +| `contentSignature` | `uint64_t` | 折叠后的场景内容签名。 | +| `cached` | `bool` | 当前缓存是否有效。 | + +## 当前语义 + +- `scene` 是非拥有指针，只用于判定“是否还是同一活动场景”。 +- `selectedObjectIds` 按值缓存，因此选中集变化可以直接触发重建。 +- `frameData.overlay` 还会被 [ShouldRebuildSceneViewportOverlayFrameCache](ShouldRebuildSceneViewportOverlayFrameCache.md) 拿来和最新 `SceneViewportOverlayData` 做 epsilon 比较。 +- `cached == false` 时，当前状态应视为“没有可复用的 overlay frame”。 + +## 当前使用位置 + +- `ViewportHostService` 用它作为成员 `m_sceneViewEditorOverlayFrameCache`，统一保存 Scene View overlay frame 的缓存状态。 +- [ResetSceneViewportOverlayFrameCacheState](ResetSceneViewportOverlayFrameCacheState.md) 与 [UpdateSceneViewportOverlayFrameCacheState](UpdateSceneViewportOverlayFrameCacheState.md) 当前分别负责清空和写回这份状态。 + +## 相关文档 + +- [SceneViewportOverlayFrameCache](SceneViewportOverlayFrameCache.md) +- [ResetSceneViewportOverlayFrameCacheState](ResetSceneViewportOverlayFrameCacheState.md) +- [ShouldRebuildSceneViewportOverlayFrameCache](ShouldRebuildSceneViewportOverlayFrameCache.md) +- [UpdateSceneViewportOverlayFrameCacheState](UpdateSceneViewportOverlayFrameCacheState.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayFrameCache/ShouldRebuildSceneViewportOverlayFrameCache.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayFrameCache/ShouldRebuildSceneViewportOverlayFrameCache.md new file mode 100644 index 00000000..c32c1212 --- /dev/null +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayFrameCache/ShouldRebuildSceneViewportOverlayFrameCache.md @@ -0,0 +1,60 @@ +# ShouldRebuildSceneViewportOverlayFrameCache + +**命名空间**: `XCEngine::Editor` + +**类型**: `function` + +**源文件**: `editor/src/Viewport/SceneViewportOverlayFrameCache.h` + +## 签名 + +```cpp +bool ShouldRebuildSceneViewportOverlayFrameCache( + const SceneViewportOverlayFrameCacheState& cacheState, + const Components::Scene* scene, + const SceneViewportOverlayData& overlay, + uint32_t viewportWidth, + uint32_t viewportHeight, + const std::vector& selectedObjectIds, + uint64_t contentSignature, + bool transformGizmoOverlayDirty); +``` + +## 作用 + +判断 Scene View canonical overlay frame 是否必须重建。 + +## 当前实现行为 + +当前返回 `true` 的条件包括： + +- `transformGizmoOverlayDirty == true` +- `cacheState.cached == false` +- `cacheState.scene != scene` +- `cacheState.viewportWidth != viewportWidth` +- `cacheState.viewportHeight != viewportHeight` +- `cacheState.selectedObjectIds != selectedObjectIds` +- `cacheState.contentSignature != contentSignature` +- [AreEqualSceneViewportOverlayData](AreEqualSceneViewportOverlayData.md) 返回 `false` + +也就是说，这里把“逐帧 gizmo dirty”、“场景 / 选中集 / 视口元数据变化”和“相机 overlay 数学变化”统一折叠成一个布尔决策。 + +## 设计含义 + +这层 helper 的价值不只是减少 `ViewportHostService` 里的条件判断，而是把缓存失效规则做成一份可测试契约。 + +当前策略明确区分了两类变化来源： + +- 通过 `contentSignature` 跟踪的场景内容变化 +- 通过 `transformGizmoOverlayDirty` 跟踪的逐帧 gizmo overlay 变化 + +## 测试锚点 + +- `RebuildDecisionTracksCacheMetadataAndDirtyState` + +## 相关文档 + +- [SceneViewportOverlayFrameCache](SceneViewportOverlayFrameCache.md) +- [SceneViewportOverlayFrameCacheState](SceneViewportOverlayFrameCacheState.md) +- [AreEqualSceneViewportOverlayData](AreEqualSceneViewportOverlayData.md) +- [UpdateSceneViewportOverlayFrameCacheState](UpdateSceneViewportOverlayFrameCacheState.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayFrameCache/UpdateSceneViewportOverlayFrameCacheState.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayFrameCache/UpdateSceneViewportOverlayFrameCacheState.md new file mode 100644 index 00000000..e63df968 --- /dev/null +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayFrameCache/UpdateSceneViewportOverlayFrameCacheState.md @@ -0,0 +1,48 @@ +# UpdateSceneViewportOverlayFrameCacheState + +**命名空间**: `XCEngine::Editor` + +**类型**: `function` + +**源文件**: `editor/src/Viewport/SceneViewportOverlayFrameCache.h` + +## 签名 + +```cpp +void UpdateSceneViewportOverlayFrameCacheState( + SceneViewportOverlayFrameCacheState& cacheState, + const Components::Scene* scene, + uint32_t viewportWidth, + uint32_t viewportHeight, + const std::vector& selectedObjectIds, + uint64_t contentSignature, + const SceneViewportOverlayFrameData& frameData); +``` + +## 作用 + +把最新生成的 Scene View overlay frame 及其元数据写回缓存状态。 + +## 当前实现行为 + +当前会按值写回： + +- `frameData` +- `scene` +- `selectedObjectIds` +- `viewportWidth` +- `viewportHeight` +- `contentSignature` + +最后把 `cached = true`。 + +## 当前语义 + +- 这一步不做增量 merge，而是把“这一帧最新的 canonical frame”整体替换进缓存。 +- 写回完成后，`GetSceneViewEditorOverlayFrameData(...)` 就会直接返回 `cacheState.frameData`，直到下一次 [ShouldRebuildSceneViewportOverlayFrameCache](ShouldRebuildSceneViewportOverlayFrameCache.md) 判定为真。 + +## 相关文档 + +- [SceneViewportOverlayFrameCache](SceneViewportOverlayFrameCache.md) +- [SceneViewportOverlayFrameCacheState](SceneViewportOverlayFrameCacheState.md) +- [ShouldRebuildSceneViewportOverlayFrameCache](ShouldRebuildSceneViewportOverlayFrameCache.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayHitTester/HitTestSceneViewportOverlayHandles.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayHitTester/HitTestSceneViewportOverlayHandles.md new file mode 100644 index 00000000..2538563e --- /dev/null +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayHitTester/HitTestSceneViewportOverlayHandles.md @@ -0,0 +1,89 @@ +# HitTestSceneViewportOverlayHandles + +**命名空间**: `XCEngine::Editor` + +**类型**: `function` + +**源文件**: `editor/src/Viewport/SceneViewportOverlayHitTester.h` + +## 签名 + +```cpp +SceneViewportOverlayHandleHitResult HitTestSceneViewportOverlayHandles( + const SceneViewportOverlayFrameData& frameData, + const Math::Vector2& viewportSize, + const Math::Vector2& viewportMousePosition); +``` + +## 作用 + +对当前 overlay frame 的 `handleRecords` 做命中测试，并返回最佳 handle 命中结果。 + +## 当前实现行为 + +### 1. 遍历全部 handle record + +当前会遍历： + +```cpp +frameData.handleRecords +``` + +对每条记录尝试构建命中度量。 + +### 2. 按 shape 计算命中 + +内部当前支持四种 handle shape： + +- `WorldRect` + - 先用 `ProjectSceneViewportWorldPoint(...)` 投影到屏幕，再做矩形包含测试 +- `ScreenSegment` + - 用 `DistanceToSegmentSquared(...)` 和 `hitThicknessPixels` 做距离判定 +- `ScreenRect` + - 直接做屏幕矩形包含测试 +- `ScreenQuad` + - 用逐边叉积判断点是否落在四边形内 + +### 3. 统一仲裁最佳结果 + +当前最佳结果的选择顺序是： + +1. `priority` 更高者优先 +2. 同优先级下，`depth` 更近者优先 +3. 深度差在 `kMetricEpsilon = 0.001f` 内时，`distanceSq` 更小者优先 + +最终返回的结果会保留： + +- `kind` +- `handleId` +- `entityId` +- `priority` +- `distanceSq` +- `depth` + +## 为什么是这个仲裁顺序 + +这套规则体现的是一种很典型的编辑器命中策略： + +- 先尊重显式优先级 +- 再尊重视觉上更靠前的几何 +- 最后再用鼠标离中心更近的候选打破平局 + +这样比单纯按距离最近做命中更稳，因为 Scene View 里很多 handle 在屏幕上本来就会相互叠压。 + +## 当前使用位置 + +当前主要由 [SceneViewportInteractionResolver](../SceneViewportInteractionResolver/SceneViewportInteractionResolver.md) 调用，随后再与 HUD 命中结果统一仲裁。 + +## 设计说明 + +这个函数是 Scene View overlay 命中链的“几何裁判”，但不是最终交互裁判。 + +它负责把复杂 shape 规则统一折叠成一个最佳 overlay 命中候选，交给 resolver 继续做更高层的交互决策。 + +## 相关文档 + +- [SceneViewportOverlayHitTester](SceneViewportOverlayHitTester.md) +- [SceneViewportInteractionResolver](../SceneViewportInteractionResolver/SceneViewportInteractionResolver.md) +- [SceneViewportEditorOverlayData](../SceneViewportEditorOverlayData/SceneViewportEditorOverlayData.md) +- [SceneViewportMath](../SceneViewportMath/SceneViewportMath.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayHitTester/SceneViewportOverlayHitTester.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayHitTester/SceneViewportOverlayHitTester.md index 02986964..6dc2bd5a 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayHitTester/SceneViewportOverlayHitTester.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayHitTester/SceneViewportOverlayHitTester.md @@ -6,71 +6,65 @@ **源文件**: `editor/src/Viewport/SceneViewportOverlayHitTester.h` -**描述**: 基于 overlay `handleRecords` 对 Scene View 鼠标位置做命中测试，并返回当前最佳命中结果。 +**描述**: 基于 `SceneViewportOverlayFrameData::handleRecords` 对鼠标位置做命中测试，并返回当前最佳 overlay handle 命中结果。 ## 概览 -`SceneViewportOverlayHitTester` 解决的是“从 canonical overlay frame 里找出鼠标当前最可能命中的 handle”。 +`SceneViewportOverlayHitTester` 解决的是“在当前这一帧已经生成好的 overlay handle 数据里，鼠标最可能命中了哪一个 handle”。 -它不重新计算 gizmo 几何，而是直接消费 [SceneViewportOverlayHandleBuilder](../SceneViewportOverlayHandleBuilder/SceneViewportOverlayHandleBuilder.md) 产出的 `handleRecords`。 +它不重新计算 gizmo 几何，也不重新构建 overlay frame。 +它只消费 [SceneViewportEditorOverlayData](../SceneViewportEditorOverlayData/SceneViewportEditorOverlayData.md) 里的： + +- `handleRecords` +- `overlay` + +然后按统一规则返回最佳命中结果。 ## 当前公开入口 -- `HitTestSceneViewportOverlayHandles(...)` +| 函数 | 说明 | +|------|------| +| [HitTestSceneViewportOverlayHandles](HitTestSceneViewportOverlayHandles.md) | 对当前 overlay handle 集合做命中测试并返回最佳结果。 | -## 当前判定规则 +## 当前支持的 handle shape -当前支持的 handle shape 包括： +当前命中逻辑支持： - `WorldRect` - `ScreenSegment` - `ScreenRect` - `ScreenQuad` -命中成功后，最佳结果的选择顺序是： +不同 shape 的判定方式不同，但最后都会统一折叠成： -1. `priority` 更高者优先 -2. 同优先级下 `depth` 更近者优先 -3. 深度近似相同时 `distanceSq` 更小者优先 +- `distanceSq` +- `depth` +- `priority` -## 当前实现特征 +供最终最佳结果仲裁使用。 -- `WorldRect` 会先投影到屏幕再判断。 -- `ScreenSegment` 使用线段距离平方与 `hitThicknessPixels`。 -- `ScreenQuad` 使用逐边叉积判断点是否落在四边形内。 -- 输出的 `SceneViewportOverlayHandleHitResult` 会保留： - - `kind` - - `handleId` - - `entityId` - - `priority` - - `distanceSq` - - `depth` +## 在交互链中的位置 -## 当前使用位置 - -当前主调用方不再是 `SceneViewPanel` 直接调用，而是： +当前主调用方不是面板直接调用，而是： - [SceneViewportInteractionResolver](../SceneViewportInteractionResolver/SceneViewportInteractionResolver.md) - 的 request 重载内部先调用它 -- 随后再和 HUD 命中做统一仲裁 -因此面板当前只需构造 `SceneViewportInteractionResolveRequest`，不再自己手工串联命中函数。 +它会先调用 overlay hit tester，再和 HUD 命中结果做统一仲裁。 -## 与测试的对应关系 +因此这个模块的定位是“overlay 命中候选生成器”，而不是最终交互决策器。 -`tests/Editor/test_scene_viewport_interaction_resolver.cpp` 当前覆盖了： +## 设计说明 -- request 重载会实际走 `HitTestSceneViewportOverlayHandles(...)` 路径。 -- 由它产出的 overlay handle 候选会继续参与和 HUD 命中的统一仲裁。 +把 overlay handle 命中单独收成一个 header helper，有两个现实收益： -## 当前实现边界 +- gizmo/overlay 生成和命中判定可以独立演进 +- resolver 只需要关注“候选结果之间怎么仲裁”，不用重新理解各种几何形状的命中规则 -- 这里只处理当前帧 overlay 几何，不持有历史状态。 -- 它只解析世界 overlay / gizmo handle，不处理 HUD orientation gizmo。 -- HUD 命中由 [SceneViewportHudOverlay](../SceneViewportHudOverlay/SceneViewportHudOverlay.md) 负责，统一排序由 resolver 完成。 +这也是很典型的编辑器交互分层：先产生命中候选，再统一裁决。 ## 相关文档 -- [SceneViewportOverlayHandleBuilder](../SceneViewportOverlayHandleBuilder/SceneViewportOverlayHandleBuilder.md) +- [HitTestSceneViewportOverlayHandles](HitTestSceneViewportOverlayHandles.md) - [SceneViewportInteractionResolver](../SceneViewportInteractionResolver/SceneViewportInteractionResolver.md) -- [SceneViewPanel](../../panels/SceneViewPanel/SceneViewPanel.md) +- [SceneViewportOverlayHandleBuilder](../SceneViewportOverlayHandleBuilder/SceneViewportOverlayHandleBuilder.md) +- [SceneViewportEditorOverlayData](../SceneViewportEditorOverlayData/SceneViewportEditorOverlayData.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/AddProvider.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/AddProvider.md new file mode 100644 index 00000000..01344811 --- /dev/null +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/AddProvider.md @@ -0,0 +1,43 @@ +# SceneViewportOverlayProviderRegistry::AddProvider + +**命名空间**: `XCEngine::Editor` + +**类型**: `method` + +**源文件**: `editor/src/Viewport/SceneViewportOverlayProviders.h` + +## 签名 + +```cpp +void AddProvider(std::unique_ptr provider); +``` + +## 作用 + +向 registry 末尾追加一个 overlay provider，并接管其所有权。 + +## 当前实现行为 + +当前实现规则很简单： + +- `provider == nullptr` 时直接返回 +- 非空时执行 `m_providers.emplace_back(std::move(provider))` + +也就是说： + +- 空 provider 不会报错，也不会留下占位项 +- 注册顺序就是容器追加顺序 + +## 顺序语义 + +由于 [AppendOverlay](AppendOverlay.md) 会按 `m_providers` 的顺序遍历，这个方法决定的注册顺序会直接影响不同 provider 输出追加到 `frameData` 的先后顺序。 + +## 测试锚点 + +`AppendsProvidersInRegistrationOrder` 通过自定义 `MarkerOverlayProvider` 验证了注册顺序会反映到最终输出顺序。 + +## 相关文档 + +- [SceneViewportOverlayProviderRegistry](SceneViewportOverlayProviderRegistry.md) +- [AppendOverlay](AppendOverlay.md) +- [ISceneViewportOverlayProvider](ISceneViewportOverlayProvider.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/AppendOverlay.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/AppendOverlay.md new file mode 100644 index 00000000..995c2f4c --- /dev/null +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/AppendOverlay.md @@ -0,0 +1,55 @@ +# SceneViewportOverlayProviderRegistry::AppendOverlay + +**命名空间**: `XCEngine::Editor` + +**类型**: `method` + +**源文件**: `editor/src/Viewport/SceneViewportOverlayProviders.h` + +## 签名 + +```cpp +void AppendOverlay( + const SceneViewportOverlayBuildContext& context, + SceneViewportOverlayFrameData& frameData) const; +``` + +## 作用 + +按注册顺序调用所有 provider，把它们负责的 overlay primitive 统一追加到同一份 `SceneViewportOverlayFrameData` 中。 + +## 当前实现行为 + +当前逻辑分两步： + +1. 若 `context.IsValid()` 为假，直接返回 +2. 否则遍历 `m_providers` + - 对每个非空 provider 调用 `provider->AppendOverlay(context, frameData)` + +它不会： + +- 重置 `frameData` +- 自己创建上下文 +- 重新排序 provider + +## 为什么顺序重要 + +registry 追加的是同一份 `frameData`，因此 provider 的注册顺序会决定： + +- `worldLines` +- `worldSprites` +- `screenTriangles` +- `handleRecords` + +被追加进去的相对顺序。虽然这不一定总是直接等于最终渲染顺序，但它会影响后续消费这些数组的模块观察到的数据布局。 + +## 测试锚点 + +`AppendsProvidersInRegistrationOrder` 当前直接覆盖了这一点：两个 marker provider 按注册顺序向 `worldLines` 追加输出。 + +## 相关文档 + +- [SceneViewportOverlayProviderRegistry](SceneViewportOverlayProviderRegistry.md) +- [SceneViewportOverlayBuildContext](SceneViewportOverlayBuildContext.md) +- [ISceneViewportOverlayProvider](ISceneViewportOverlayProvider.md) +- [AddProvider](AddProvider.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/BuildDefaultSceneViewportOverlayProviderRegistry.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/BuildDefaultSceneViewportOverlayProviderRegistry.md index b0a47181..4059ba88 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/BuildDefaultSceneViewportOverlayProviderRegistry.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/BuildDefaultSceneViewportOverlayProviderRegistry.md @@ -20,26 +20,37 @@ SceneViewportOverlayProviderRegistry BuildDefaultSceneViewportOverlayProviderReg 当前实现会： -1. 构造一个空的 `SceneViewportOverlayProviderRegistry` -2. 先注册 [CreateSceneViewportCameraOverlayProvider](CreateSceneViewportCameraOverlayProvider.md) -3. 再注册 [CreateSceneViewportLightOverlayProvider](CreateSceneViewportLightOverlayProvider.md) -4. 最后注册 [CreateSceneViewportTransformGizmoOverlayProvider](CreateSceneViewportTransformGizmoOverlayProvider.md) +1. 创建空的 `SceneViewportOverlayProviderRegistry` +2. 注册 [CreateSceneViewportCameraOverlayProvider](CreateSceneViewportCameraOverlayProvider.md) +3. 注册 [CreateSceneViewportLightOverlayProvider](CreateSceneViewportLightOverlayProvider.md) +4. 注册 [CreateSceneViewportTransformGizmoOverlayProvider](CreateSceneViewportTransformGizmoOverlayProvider.md) 5. 返回 registry -## 当前语义边界 +当前默认顺序因此是： -- 当前默认 registry 包含相机 provider、灯光 provider 与 transform gizmo provider 三项。 -- 注册顺序是契约的一部分，因为 registry 追加输出时会保留顺序。 +1. camera +2. light +3. transform gizmo + +## 为什么这个顺序值得文档化 + +因为 registry 会按注册顺序执行 provider，而默认 builder 直接使用这份 registry。 + +这意味着“默认 Scene View overlay 是如何组合出来的”，在源码上就是一条稳定的顺序契约，而不是模糊约定。 ## 当前调用链 -[SceneViewportOverlayBuilder](../SceneViewportOverlayBuilder/SceneViewportOverlayBuilder.md) -的默认构造路径当前就使用这条函数来准备 provider registry。 +[SceneViewportOverlayBuilder](../SceneViewportOverlayBuilder/SceneViewportOverlayBuilder.md) 的默认构造函数当前就调用本函数准备 registry。 + +## 测试关联 + +虽然当前测试没有直接逐项断言这三个 factory 的注册顺序，但默认 builder 的聚合测试已经间接依赖这份默认 registry 组合。 ## 相关文档 +- [SceneViewportOverlayProviders](SceneViewportOverlayProviders.md) - [SceneViewportOverlayProviderRegistry](SceneViewportOverlayProviderRegistry.md) - [CreateSceneViewportCameraOverlayProvider](CreateSceneViewportCameraOverlayProvider.md) - [CreateSceneViewportLightOverlayProvider](CreateSceneViewportLightOverlayProvider.md) - [CreateSceneViewportTransformGizmoOverlayProvider](CreateSceneViewportTransformGizmoOverlayProvider.md) -- [SceneViewportOverlayProviders](SceneViewportOverlayProviders.md) +- [SceneViewportOverlayBuilder](../SceneViewportOverlayBuilder/SceneViewportOverlayBuilder.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/CreateSceneViewportCameraOverlayProvider.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/CreateSceneViewportCameraOverlayProvider.md index b94e4dff..b467b8a2 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/CreateSceneViewportCameraOverlayProvider.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/CreateSceneViewportCameraOverlayProvider.md @@ -18,25 +18,57 @@ std::unique_ptr CreateSceneViewportCameraOverlayP ## 当前实现行为 -当前返回一个内部 `SceneViewportCameraOverlayProvider` 实例。 -它在有效上下文下会做两类事： +当前返回内部 `SceneViewportCameraOverlayProvider` 实例。 -- 遍历场景里已启用相机，为其追加相机图标 sprite -- 对当前选中的已启用相机，追加视锥线框辅助几何 +按 `SceneViewportOverlayProviders.cpp` 当前实现，它在有效上下文下会做两类事： -## 当前语义边界 +### 1. 为所有可见相机追加 scene icon -- provider 只处理“相机相关 overlay”，不会生成灯光辅助内容。 -- 只有对象处于激活层级且带有效 `Transform` 时，当前实现才会继续构建对应 overlay。 +它会遍历场景中的 `CameraComponent`，过滤掉： + +- `camera == nullptr` +- `!camera->IsEnabled()` +- `GameObject` 不可用于构建 overlay + +随后调用 `AppendSceneIconOverlay(...)`，用固定图标尺寸： + +```cpp +Math::Vector2(90.0f, 90.0f) +``` + +追加 camera sprite。 + +### 2. 为当前选中的相机追加 frustum 辅助线框 + +它会再次遍历 `selectedObjectIds`，对其中： + +- 可找到的对象 +- 有效且启用的 `CameraComponent` + +调用 `AppendCameraFrustumOverlay(...)`。 + +这说明 frustum helper 不是“所有相机都画”，而是“只对当前被选中的相机画”。 ## 测试锚点 -`tests/Editor/test_scene_viewport_overlay_providers.cpp` -中的 `CameraProviderBuildsSceneIconAndSelectedFrustum` -当前覆盖了它的主要输出路径。 +`CameraProviderBuildsSceneIconAndSelectedFrustum` 验证了： + +- 会追加 `Camera` 类型 sprite +- 会追加一个 handle record +- 会生成 12 条 world line 作为 frustum 线框 + +## 设计说明 + +Scene View 相机 overlay 采用“所有相机都有图标、选中相机才有详细辅助几何”的策略，是一种很合理的编辑器设计平衡： + +- 平时能看见场景里有哪些相机 +- 选中时才提供更强的诊断和编辑辅助 + +这样既不会把视图塞得太满，也不会牺牲可读性。 ## 相关文档 +- [SceneViewportOverlayProviders](SceneViewportOverlayProviders.md) - [ISceneViewportOverlayProvider](ISceneViewportOverlayProvider.md) -- [CreateSceneViewportLightOverlayProvider](CreateSceneViewportLightOverlayProvider.md) - [BuildDefaultSceneViewportOverlayProviderRegistry](BuildDefaultSceneViewportOverlayProviderRegistry.md) +- [SceneViewportEditorOverlayData](../SceneViewportEditorOverlayData/SceneViewportEditorOverlayData.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/CreateSceneViewportLightOverlayProvider.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/CreateSceneViewportLightOverlayProvider.md index 63a0dd46..87a75c03 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/CreateSceneViewportLightOverlayProvider.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/CreateSceneViewportLightOverlayProvider.md @@ -18,25 +18,58 @@ std::unique_ptr CreateSceneViewportLightOverlayPr ## 当前实现行为 -当前返回一个内部 `SceneViewportLightOverlayProvider` 实例。 -它在有效上下文下会做两类事： +当前返回内部 `SceneViewportLightOverlayProvider` 实例。 -- 遍历场景里已启用灯光，为其追加灯光图标 sprite -- 对当前选中的已启用方向光，追加方向环与射线辅助几何 +按当前实现，它在有效上下文下会做两类事： -## 当前语义边界 +### 1. 为所有可见灯光追加 scene icon -- provider 只处理“灯光相关 overlay”。 -- 额外辅助几何当前只覆盖 `Directional` 光源；点光和聚光不会生成同级别 helper。 +它会遍历场景中的 `LightComponent`，过滤掉： + +- `light == nullptr` +- `!light->IsEnabled()` +- `GameObject` 不可用于构建 overlay + +随后调用 `AppendSceneIconOverlay(...)`，以固定图标尺寸： + +```cpp +Math::Vector2(100.0f, 100.0f) +``` + +追加 light sprite。 + +### 2. 仅为当前选中的方向光追加辅助几何 + +它会遍历 `selectedObjectIds`，只对满足以下条件的对象追加额外 helper： + +- 对象存在且可用于 overlay +- 挂有启用的 `LightComponent` +- `light->GetLightType() == Directional` + +随后调用 `AppendDirectionalLightOverlay(...)`。 + +这意味着点光和聚光当前不会生成同级别的选中辅助几何。 ## 测试锚点 -`tests/Editor/test_scene_viewport_overlay_providers.cpp` -中的 `LightProviderBuildsSceneIconAndSelectedDirectionalHelper` -当前覆盖了它的主要输出路径。 +`LightProviderBuildsSceneIconAndSelectedDirectionalHelper` 验证了： + +- 会追加 `Light` 类型 sprite +- 会追加一个 handle record +- 会生成大于 0 的 world line 作为方向光 helper + +## 设计说明 + +当前把“所有灯光都有 icon”和“只有选中的方向光才有详细 helper”拆开，是一个很典型的编辑器视觉策略： + +- icon 用于存在性与定位 +- 详细 helper 用于当前编辑焦点 + +这能减少视图噪音，同时保留需要时的诊断信息。 ## 相关文档 +- [SceneViewportOverlayProviders](SceneViewportOverlayProviders.md) - [ISceneViewportOverlayProvider](ISceneViewportOverlayProvider.md) -- [CreateSceneViewportCameraOverlayProvider](CreateSceneViewportCameraOverlayProvider.md) - [BuildDefaultSceneViewportOverlayProviderRegistry](BuildDefaultSceneViewportOverlayProviderRegistry.md) +- [SceneViewportEditorOverlayData](../SceneViewportEditorOverlayData/SceneViewportEditorOverlayData.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/CreateSceneViewportTransformGizmoOverlayProvider.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/CreateSceneViewportTransformGizmoOverlayProvider.md index 00762484..ee8275e8 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/CreateSceneViewportTransformGizmoOverlayProvider.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/CreateSceneViewportTransformGizmoOverlayProvider.md @@ -18,22 +18,51 @@ std::unique_ptr CreateSceneViewportTransformGizmo ## 当前实现行为 -当前返回一个内部 `SceneViewportTransformGizmoOverlayProvider` 实例。 -它在有效上下文下会做两类事： +当前返回内部 `SceneViewportTransformGizmoOverlayProvider` 实例。 -- 检查 `context.transformGizmoOverlayState` 是否存在且至少有一类 gizmo 可见 -- 把这份 gizmo state 重新转回 `SceneViewportTransformGizmoHandleBuildInputs`，并向 `frameData` 追加： - - `screenTriangles` - - `handleRecords` +它在执行时会先检查： -## 当前语义边界 +- `context.IsValid()` +- `context.transformGizmoOverlayState != nullptr` +- `context.transformGizmoOverlayState->HasAnyVisibleGizmo()` -- provider 本身不参与 gizmo 数学刷新，也不负责拖拽生命周期。 -- 它只消费已经准备好的 draw data 快照，把它写回统一的 editor overlay frame data。 +只有这三者都满足时才继续。 + +随后当前实现会： + +1. 调用 `BuildSceneViewportTransformGizmoHandleBuildInputs(...)` +2. 调用 `AppendTransformGizmoScreenTriangles(frameData, inputs)` +3. 调用 `AppendTransformGizmoHandleRecords(frameData, inputs)` + +也就是说它不会生成： + +- `worldLines` +- `worldSprites` + +它只负责把 gizmo 正式 draw data 转成： + +- `screenTriangles` +- `handleRecords` + +## 测试锚点 + +`TransformGizmoProviderBuildsOverlayFromFormalState` 验证了： + +- 会追加 `MoveAxis` 类型 handle record +- `entityId` 会被正确保留 +- 会生成 `screenTriangles` +- 不会生成 world line 或 sprite + +## 设计说明 + +transform gizmo provider 的职责非常纯粹：它不做 gizmo 数学刷新，不处理拖拽生命周期，也不自己决定当前 gizmo 应该是什么状态。 + +它只是消费已经准备好的 formal gizmo overlay state，把它投影成统一的 overlay frame 数据。这种设计让 gizmo 交互系统和 overlay 聚合系统保持了很清晰的分工。 ## 相关文档 +- [SceneViewportOverlayProviders](SceneViewportOverlayProviders.md) - [ISceneViewportOverlayProvider](ISceneViewportOverlayProvider.md) - [BuildDefaultSceneViewportOverlayProviderRegistry](BuildDefaultSceneViewportOverlayProviderRegistry.md) -- [SceneViewportOverlayBuilder](../SceneViewportOverlayBuilder/SceneViewportOverlayBuilder.md) - [SceneViewportOverlayHandleBuilder](../SceneViewportOverlayHandleBuilder/SceneViewportOverlayHandleBuilder.md) +- [SceneViewportTransformGizmoCoordinator](../SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoCoordinator.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/GetProvider.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/GetProvider.md new file mode 100644 index 00000000..3f519b6a --- /dev/null +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/GetProvider.md @@ -0,0 +1,47 @@ +# SceneViewportOverlayProviderRegistry::GetProvider + +**命名空间**: `XCEngine::Editor` + +**类型**: `method` + +**源文件**: `editor/src/Viewport/SceneViewportOverlayProviders.h` + +## 签名 + +```cpp +const ISceneViewportOverlayProvider* GetProvider(size_t index) const; +``` + +## 作用 + +按索引读取 registry 中已注册 provider 的观察指针。 + +## 当前实现行为 + +当前实现是一个边界检查包装： + +```cpp +return index < m_providers.size() ? m_providers[index].get() : nullptr; +``` + +这意味着： + +- 索引合法时返回非拥有型观察指针 +- 越界时返回 `nullptr` + +## 生命周期语义 + +返回值的所有权仍属于 registry。 + +只要 registry 还持有对应 provider，返回指针就有效；如果 registry 被销毁或该 provider 被替换，观察指针也随之失效。 + +## 测试锚点 + +`AppendsProvidersInRegistrationOrder` 当前至少验证了前两个合法索引会返回非空指针。 + +## 相关文档 + +- [SceneViewportOverlayProviderRegistry](SceneViewportOverlayProviderRegistry.md) +- [GetProviderCount](GetProviderCount.md) +- [AddProvider](AddProvider.md) +- [ISceneViewportOverlayProvider](ISceneViewportOverlayProvider.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/GetProviderCount.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/GetProviderCount.md new file mode 100644 index 00000000..0a785d87 --- /dev/null +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/GetProviderCount.md @@ -0,0 +1,33 @@ +# SceneViewportOverlayProviderRegistry::GetProviderCount + +**命名空间**: `XCEngine::Editor` + +**类型**: `method` + +**源文件**: `editor/src/Viewport/SceneViewportOverlayProviders.h` + +## 签名 + +```cpp +size_t GetProviderCount() const; +``` + +## 作用 + +返回当前 registry 中已注册 provider 的数量。 + +## 当前实现行为 + +当前实现直接返回： + +```cpp +m_providers.size() +``` + +因此它反映的是当前真实持有的 provider 数量，不包含空占位，也不做额外过滤。 + +## 相关文档 + +- [SceneViewportOverlayProviderRegistry](SceneViewportOverlayProviderRegistry.md) +- [AddProvider](AddProvider.md) +- [GetProvider](GetProvider.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/ISceneViewportOverlayProvider.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/ISceneViewportOverlayProvider.md index c573773e..b2639e9a 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/ISceneViewportOverlayProvider.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/ISceneViewportOverlayProvider.md @@ -6,36 +6,54 @@ **源文件**: `editor/src/Viewport/SceneViewportOverlayProviders.h` -**描述**: 单个 Scene View 世界 overlay provider 的抽象接口。 +**描述**: 单个 Scene View overlay provider 的抽象接口，负责把某一类 overlay primitive 追加到统一的 frame data 中。 -## 概述 +## 概览 -`ISceneViewportOverlayProvider` 定义了一类很明确的职责： +`ISceneViewportOverlayProvider` 定义了一类很窄但很稳定的职责： -- 给自己起一个稳定名字 -- 在给定构建上下文下，把本 provider 负责的 overlay 基元追加进 `SceneViewportOverlayFrameData` +- 给自己提供一个可读名称 +- 在给定构建上下文下，把本 provider 负责的 overlay 内容追加进 `SceneViewportOverlayFrameData` -按当前实现，内建 provider 只有两种： +它不负责： -- 相机 provider -- 灯光 provider +- provider 的注册顺序 +- overlay frame 的缓存 +- GPU 渲染 -它们都在 `SceneViewportOverlayProviders.cpp` 里以内部类实现，再通过工厂函数暴露。 +这意味着 provider 只需要专注于“内容生成语义”。 -## 当前接口语义 +## 当前接口 -- `GetName()` 返回 provider 名字，当前主要用于调试 / 诊断。 -- `AppendOverlay(...)` 接收只读构建上下文和可写 `frameData`，把本 provider 负责的图标或线段追加进去。 -- provider 可以选择在上下文无效、对象未启用或当前没有匹配对象时直接 no-op。 +| 方法 | 说明 | +|------|------| +| `GetName()` | 返回 provider 名称，当前主要用于调试与诊断。 | +| `AppendOverlay(...)` | 把本 provider 负责的 primitive 追加进 `frameData`。 | -## 当前实现边界 +## 当前内建实现 -- 这个接口本身不管理注册顺序；顺序由 [SceneViewportOverlayProviderRegistry](SceneViewportOverlayProviderRegistry.md) 决定。 -- 它也不负责渲染；只是生成 overlay 数据。 +当前在 `SceneViewportOverlayProviders.cpp` 内部实现了三种 provider： + +- `SceneViewportCameraOverlayProvider` +- `SceneViewportLightOverlayProvider` +- `SceneViewportTransformGizmoOverlayProvider` + +它们都通过工厂函数对外暴露，而不是直接把具体类写进头文件。 + +## 设计说明 + +把 provider 暴露成接口而不是具象类，有两个现实收益： + +- 默认实现可以藏在 `.cpp` 内，不污染公开 API 面 +- 测试可以轻松注入自定义 provider + +`test_scene_viewport_overlay_providers.cpp` 里的 `MarkerOverlayProvider` 就是这种设计的直接受益者。 ## 相关文档 +- [SceneViewportOverlayProviders](SceneViewportOverlayProviders.md) - [SceneViewportOverlayBuildContext](SceneViewportOverlayBuildContext.md) - [SceneViewportOverlayProviderRegistry](SceneViewportOverlayProviderRegistry.md) - [CreateSceneViewportCameraOverlayProvider](CreateSceneViewportCameraOverlayProvider.md) - [CreateSceneViewportLightOverlayProvider](CreateSceneViewportLightOverlayProvider.md) +- [CreateSceneViewportTransformGizmoOverlayProvider](CreateSceneViewportTransformGizmoOverlayProvider.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/IsValid.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/IsValid.md new file mode 100644 index 00000000..a9789553 --- /dev/null +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/IsValid.md @@ -0,0 +1,48 @@ +# SceneViewportOverlayBuildContext::IsValid + +**命名空间**: `XCEngine::Editor` + +**类型**: `method` + +**源文件**: `editor/src/Viewport/SceneViewportOverlayProviders.h` + +## 签名 + +```cpp +bool IsValid() const; +``` + +## 作用 + +判断当前 `SceneViewportOverlayBuildContext` 是否满足 overlay provider 执行的最小前置条件。 + +## 当前实现行为 + +当前只有在以下条件同时满足时才返回 `true`： + +- `editorContext != nullptr` +- `scene != nullptr` +- `overlay != nullptr` +- `overlay->valid == true` +- `viewportWidth > 0u` +- `viewportHeight > 0u` +- `selectedObjectIds != nullptr` + +`transformGizmoOverlayState` 不参与该判定。 + +## 设计说明 + +这意味着 `IsValid()` 表达的是“provider 体系是否可以开始工作”的通用前置条件，而不是“每一种 provider 都已经拿到了自己所有需要的可选数据”。 + +例如： + +- transform gizmo provider 仍然需要额外检查 `transformGizmoOverlayState` +- 但 camera/light provider 并不依赖该字段 + +这种设计能让不同 provider 共享一条统一早退路径，同时保留各自的附加判断。 + +## 相关文档 + +- [SceneViewportOverlayBuildContext](SceneViewportOverlayBuildContext.md) +- [ISceneViewportOverlayProvider](ISceneViewportOverlayProvider.md) +- [AppendOverlay](AppendOverlay.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/SceneViewportOverlayBuildContext.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/SceneViewportOverlayBuildContext.md index 77780058..52a131f9 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/SceneViewportOverlayBuildContext.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/SceneViewportOverlayBuildContext.md @@ -6,34 +6,38 @@ **源文件**: `editor/src/Viewport/SceneViewportOverlayProviders.h` -**描述**: 一帧 Scene View editor overlay 构建所需的借用输入集合。 +**描述**: 一帧 Scene View overlay 构建所需的借用输入集合，供所有 provider 共享。 -## 概述 +## 概览 -`SceneViewportOverlayBuildContext` 不拥有任何资源。 -它只是把 provider 构建阶段真正需要的几个只读入口打包到一起： +`SceneViewportOverlayBuildContext` 不拥有资源，也不缓存任何结果。 -- 当前 editor 上下文 +它只是把 provider 构建阶段真正需要的输入打包到一起： + +- editor 上下文 - 当前场景 -- 当前 Scene View 相机 overlay 数据 +- 当前 Scene View overlay 相机数据 - 当前视口尺寸 -- 当前选中对象 ID 列表 +- 当前选中对象列表 - 当前帧 transform gizmo overlay state +这样 provider 不需要分别从多个地方再去取这些状态。 + ## 字段 | 字段 | 说明 | |------|------| -| `editorContext` | 当前 `IEditorContext`，供 provider 读取 editor 级状态。 | +| `editorContext` | 当前 `IEditorContext`。 | | `scene` | 当前场景，只读查询入口。 | -| `overlay` | 当前 Scene View 相机投影与朝向数据。 | -| `viewportWidth` / `viewportHeight` | 当前视口像素尺寸。 | +| `overlay` | 当前 Scene View 相机姿态与投影输入。 | +| `viewportWidth` | 当前视口宽度。 | +| `viewportHeight` | 当前视口高度。 | | `selectedObjectIds` | 当前选中对象 ID 列表。 | -| `transformGizmoOverlayState` | 当前帧 transform gizmo draw data 快照；可为空。 | +| `transformGizmoOverlayState` | 当前帧 gizmo overlay state；可为空。 | -## `IsValid()` 语义 +## 当前有效性规则 -当前 `IsValid()` 只有在下面条件同时满足时才返回 `true`： +当前 [IsValid](IsValid.md) 只有在以下条件同时满足时才返回 `true`： - `editorContext != nullptr` - `scene != nullptr` @@ -43,15 +47,20 @@ - `viewportHeight > 0` - `selectedObjectIds != nullptr` -`transformGizmoOverlayState` 不参与 `IsValid()` 判定；只有需要 gizmo 几何的 provider 才会额外检查它。 +`transformGizmoOverlayState` 是可选输入，不参与通用有效性判定。 -## 当前语义边界 +## 设计说明 -- 它只是一组借用指针 / 标量，不负责生命周期管理。 -- provider 当前普遍把“`context.IsValid()` 为假时直接 no-op”当作统一的失败路径。 +把所有 provider 公共需要的输入收进一个 context，而不是让每个 provider 自己去抓 editor/service 状态，是很成熟的 API 设计： + +- provider 更容易测试 +- provider 更不容易偷偷依赖隐藏全局状态 +- builder 更容易统一控制“这一帧允许 provider 看见什么” ## 相关文档 +- [SceneViewportOverlayProviders](SceneViewportOverlayProviders.md) +- [IsValid](IsValid.md) - [ISceneViewportOverlayProvider](ISceneViewportOverlayProvider.md) - [SceneViewportOverlayProviderRegistry](SceneViewportOverlayProviderRegistry.md) -- [SceneViewportOverlayProviders](SceneViewportOverlayProviders.md) +- [SceneViewportOverlayBuilder](../SceneViewportOverlayBuilder/SceneViewportOverlayBuilder.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/SceneViewportOverlayProviderRegistry.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/SceneViewportOverlayProviderRegistry.md index 5b33522a..bdc5b92e 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/SceneViewportOverlayProviderRegistry.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/SceneViewportOverlayProviderRegistry.md @@ -6,49 +6,63 @@ **源文件**: `editor/src/Viewport/SceneViewportOverlayProviders.h` -**描述**: 维护一组 `ISceneViewportOverlayProvider`，并按注册顺序把它们的输出追加到同一帧 overlay 数据中。 +**描述**: 按所有权持有一组 `ISceneViewportOverlayProvider`，并按注册顺序把它们的输出追加到同一帧 overlay 数据中。 -## 概述 +## 概览 `SceneViewportOverlayProviderRegistry` 是 provider 体系的聚合层。 + 它内部持有： ```cpp -std::vector> m_providers; +std::vector> m_providers = {}; ``` -因此 provider 所有权当前完全由 registry 接管。 +这意味着： -## 当前公开行为 +- provider 生命周期由 registry 管理 +- provider 调用顺序由注册顺序决定 +- builder 只需要和 registry 打交道，而不必知道每个 provider 的具体类型 -### `AddProvider(...)` +## 当前公开成员 -- 传入空指针时直接 no-op -- 非空时把 provider 追加到 `m_providers` 末尾 +| 方法 | 说明 | +|------|------| +| [AddProvider](AddProvider.md) | 追加 provider 并接管所有权。 | +| [GetProviderCount](GetProviderCount.md) | 返回当前 provider 数量。 | +| [GetProvider](GetProvider.md) | 按索引读取观察指针。 | +| [AppendOverlay](AppendOverlay.md) | 按顺序把所有 provider 输出追加进同一份 frame data。 | -### `GetProviderCount()` - -- 返回当前注册 provider 数量 - -### `GetProvider(index)` - -- 索引合法时返回对应 provider 观察指针 -- 越界时返回 `nullptr` - -### `AppendOverlay(...)` - -- 若 `context.IsValid()` 为假，直接 no-op -- 否则按注册顺序遍历所有非空 provider -- 对每个 provider 调用 `provider->AppendOverlay(context, frameData)` - -## 顺序语义 +## 当前顺序语义 当前 registry 明确保留注册顺序。 -`tests/Editor/test_scene_viewport_overlay_providers.cpp` -里的 `AppendsProvidersInRegistrationOrder` 就在验证这一点。 + +`AppendOverlay(...)` 不会重排，也不会分组，只会按 `m_providers` 从前到后执行。 + +这点很重要，因为 Scene View overlay 的很多输出都进入同一份数组。如果顺序不稳定，命中测试、调试和输出对比都会更难判断。 + +## 测试锚点 + +`AppendsProvidersInRegistrationOrder` 当前直接验证了： + +- provider 会按注册顺序执行 +- 输出会按该顺序追加到 `frameData` + +## 设计说明 + +registry 的价值不只是“装一个 vector”。它把 overlay provider 的三个关键语义放到了一个稳定 API 里： + +- 所有权 +- 顺序 +- 汇总入口 + +这让 provider 体系从一堆零散 helper，升级成一个真正可扩展的子系统。 ## 相关文档 -- [ISceneViewportOverlayProvider](ISceneViewportOverlayProvider.md) -- [BuildDefaultSceneViewportOverlayProviderRegistry](BuildDefaultSceneViewportOverlayProviderRegistry.md) - [SceneViewportOverlayProviders](SceneViewportOverlayProviders.md) +- [ISceneViewportOverlayProvider](ISceneViewportOverlayProvider.md) +- [SceneViewportOverlayBuildContext](SceneViewportOverlayBuildContext.md) +- [AddProvider](AddProvider.md) +- [AppendOverlay](AppendOverlay.md) +- [BuildDefaultSceneViewportOverlayProviderRegistry](BuildDefaultSceneViewportOverlayProviderRegistry.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/SceneViewportOverlayProviders.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/SceneViewportOverlayProviders.md index 63e3aaa8..214c2167 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/SceneViewportOverlayProviders.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/SceneViewportOverlayProviders.md @@ -6,61 +6,91 @@ **源文件**: `editor/src/Viewport/SceneViewportOverlayProviders.h` -**描述**: 定义 Scene View editor overlay provider 的构建上下文、provider 接口、注册表以及默认相机 / 灯光 / transform gizmo provider 工厂。 +**描述**: 定义 Scene View overlay provider 体系的构建上下文、抽象接口、注册表和默认 provider 工厂，用于把不同 overlay 语义拆成可组合的 provider。 -## 概述 +## 概览 -这个头文件把 Scene View editor overlay 的“语义生成”进一步拆成了 provider 体系： +`SceneViewportOverlayProviders` 这组声明把 Scene View editor overlay 的“内容生成”拆成了 provider 体系。 -- [SceneViewportOverlayBuildContext](SceneViewportOverlayBuildContext.md) - 提供一帧 overlay 构建所需的只读输入 -- [ISceneViewportOverlayProvider](ISceneViewportOverlayProvider.md) - 定义单个 overlay provider 的统一接口 -- [SceneViewportOverlayProviderRegistry](SceneViewportOverlayProviderRegistry.md) - 负责按注册顺序汇总多个 provider -- 默认工厂函数 - 返回相机 provider、灯光 provider、transform gizmo provider，以及三者组合成的默认 registry +当前这套体系的核心思想是：不同 overlay 类型不直接写死在 `ViewportHostService` 或 `SceneViewportOverlayBuilder` 里，而是各自实现为 provider，然后由 registry 统一调度。 -按当前实现，[SceneViewportOverlayBuilder](../SceneViewportOverlayBuilder/SceneViewportOverlayBuilder.md) -默认持有的就是 [BuildDefaultSceneViewportOverlayProviderRegistry](BuildDefaultSceneViewportOverlayProviderRegistry.md) -构造出来的 registry。 +这非常适合编辑器场景，因为 Scene View overlay 天生是一个会不断扩展的系统： -## 当前默认 provider 语义 +- 相机 icon +- 灯光 icon 与辅助几何 +- transform gizmo +- 未来还可能有更多 editor-only 可视化 -- 相机 provider 会给已启用相机生成场景图标。 -- 当相机对象被选中时，还会生成相机视锥辅助线框。 -- 灯光 provider 会给已启用灯光生成场景图标。 -- 当方向光对象被选中时，还会生成方向环与射线辅助几何。 -- transform gizmo provider 会把当前 `SceneViewportTransformGizmoOverlayState` 里的 draw data 转成 `screenTriangles` 与 `handleRecords`。 +provider 体系让这些能力可以并行演进，而不会把主流程继续写成巨大的 if/else。 -## 公开类型 +## 当前组成 | 成员 | 说明 | |------|------| | [SceneViewportOverlayBuildContext](SceneViewportOverlayBuildContext.md) | 一帧 overlay 构建所需的只读上下文。 | | [ISceneViewportOverlayProvider](ISceneViewportOverlayProvider.md) | 单个 overlay provider 的抽象接口。 | | [SceneViewportOverlayProviderRegistry](SceneViewportOverlayProviderRegistry.md) | provider 聚合与顺序分发容器。 | - -## 公开函数 - -| 函数 | 说明 | -|------|------| | [CreateSceneViewportCameraOverlayProvider](CreateSceneViewportCameraOverlayProvider.md) | 创建内建相机 overlay provider。 | | [CreateSceneViewportLightOverlayProvider](CreateSceneViewportLightOverlayProvider.md) | 创建内建灯光 overlay provider。 | | [CreateSceneViewportTransformGizmoOverlayProvider](CreateSceneViewportTransformGizmoOverlayProvider.md) | 创建内建 transform gizmo overlay provider。 | -| [BuildDefaultSceneViewportOverlayProviderRegistry](BuildDefaultSceneViewportOverlayProviderRegistry.md) | 构建默认 registry，当前按“相机后灯光后 transform gizmo”顺序注册。 | +| [BuildDefaultSceneViewportOverlayProviderRegistry](BuildDefaultSceneViewportOverlayProviderRegistry.md) | 构建默认 registry。 | + +## 默认 provider 语义 + +按 `SceneViewportOverlayProviders.cpp` 当前实现： + +- 相机 provider + - 为已启用相机生成 scene icon sprite + - 对当前选中的已启用相机追加 frustum 辅助线框 +- 灯光 provider + - 为已启用灯光生成 scene icon sprite + - 对当前选中的已启用方向光追加方向环与射线辅助几何 +- transform gizmo provider + - 把正式的 gizmo overlay state 转成 `screenTriangles` 与 `handleRecords` + +## 为什么 registry 顺序是契约的一部分 + +registry 当前会按注册顺序调用 provider，这并不是偶然实现细节。 + +因为所有 provider 都在往同一份 `SceneViewportOverlayFrameData` 追加内容，所以顺序会影响： + +- `worldLines` +- `worldSprites` +- `screenTriangles` +- `handleRecords` + +当前测试 `AppendsProvidersInRegistrationOrder` 也明确把这一点当作可观察行为来验证。 + +## 与 builder 的关系 + +[SceneViewportOverlayBuilder](../SceneViewportOverlayBuilder/SceneViewportOverlayBuilder.md) 默认持有的，就是 [BuildDefaultSceneViewportOverlayProviderRegistry](BuildDefaultSceneViewportOverlayProviderRegistry.md) 返回的 registry。 + +因此 provider 体系是 overlay builder 的“内容来源层”，而不是平行替代物。 ## 测试锚点 `tests/Editor/test_scene_viewport_overlay_providers.cpp` 当前覆盖了： -- registry 按注册顺序追加 provider 输出 -- 相机 provider 的图标与选中视锥生成 -- 灯光 provider 的图标与选中方向光辅助几何生成 -- transform gizmo provider 的 `screenTriangles / handleRecords` 追加 +- registry 顺序追加 +- camera provider 的 icon 与 frustum 输出 +- light provider 的 icon 与方向光 helper 输出 +- transform gizmo provider 的 `screenTriangles / handleRecords` +- 默认 overlay builder 对这些 provider 的聚合行为 + +## 设计说明 + +这套 provider 体系的真正收益不是“更抽象”，而是： + +- 新 overlay 类型更容易加入 +- 单项 overlay 行为可以单独测试 +- builder / cache / host service 的职责边界更清晰 + +这正是商业级编辑器 API 设计里非常值得坚持的方向。 ## 相关文档 - [SceneViewportOverlayBuilder](../SceneViewportOverlayBuilder/SceneViewportOverlayBuilder.md) - [SceneViewportEditorOverlayData](../SceneViewportEditorOverlayData/SceneViewportEditorOverlayData.md) -- [SceneViewportHudOverlay](../SceneViewportHudOverlay/SceneViewportHudOverlay.md) +- [SceneViewportOverlayBuildContext](SceneViewportOverlayBuildContext.md) +- [SceneViewportOverlayProviderRegistry](SceneViewportOverlayProviderRegistry.md) +- [BuildDefaultSceneViewportOverlayProviderRegistry](BuildDefaultSceneViewportOverlayProviderRegistry.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlaySpriteResources/Destructor.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlaySpriteResources/Destructor.md new file mode 100644 index 00000000..19698da6 --- /dev/null +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlaySpriteResources/Destructor.md @@ -0,0 +1,28 @@ +# SceneViewportOverlaySpriteResourceCache::~SceneViewportOverlaySpriteResourceCache + +**命名空间**: `XCEngine::Editor` + +**类型**: `method` + +**源文件**: `editor/src/Viewport/SceneViewportOverlaySpriteResources.h` + +## 签名 + +```cpp +~SceneViewportOverlaySpriteResourceCache() = default; +``` + +## 当前语义 + +- 当前析构函数是默认生成的，不会额外插入显式的 RHI 清理逻辑。 +- 也就是说，真正释放缓存纹理、SRV 与 descriptor set 的入口仍然是 [Shutdown](Shutdown.md)。 +- 当前调用链里，`SceneViewportEditorOverlayPassRenderer::DestroyResources()` 会先调用 `m_overlaySpriteResources.Shutdown()`，再销毁外围 renderer 资源。 + +## 设计含义 + +这个类把“析构对象本身”和“显式释放底层 GPU 资源”分开处理，和 editor 里其他长期缓存型 renderer helper 的模式一致。 + +## 相关文档 + +- [SceneViewportOverlaySpriteResourceCache](SceneViewportOverlaySpriteResourceCache.md) +- [Shutdown](Shutdown.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlaySpriteResources/EnsureResources.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlaySpriteResources/EnsureResources.md new file mode 100644 index 00000000..633f8374 --- /dev/null +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlaySpriteResources/EnsureResources.md @@ -0,0 +1,59 @@ +# SceneViewportOverlaySpriteResourceCache::EnsureResources + +**命名空间**: `XCEngine::Editor` + +**类型**: `method` + +**源文件**: `editor/src/Viewport/SceneViewportOverlaySpriteResources.h` + +## 签名 + +```cpp +bool EnsureResources( + RHI::RHIDevice* device, + RHI::RHIDescriptorPool* texturePool); +``` + +## 参数 + +- `device` - 当前 Scene View overlay pass 使用的 RHI 设备。 +- `texturePool` - 用于分配 sprite SRV descriptor set 的 descriptor pool。 + +## 当前实现行为 + +### 1. 先校验输入 + +- `device == nullptr` 或 `texturePool == nullptr` 时直接返回 `false`。 + +### 2. 如有上下文切换则先清缓存 + +- 只要 `m_device` 或 `m_texturePool` 已存在且与这次输入不同，就会先调用 [Shutdown](Shutdown.md)。 + +### 3. 按稳定顺序逐项懒加载 + +对每个 texture kind： + +- 若当前条目已经同时拥有 `texture / shaderView / textureSet`，直接跳过。 +- 否则先调用 [LoadSceneViewportOverlaySpritePixels](LoadSceneViewportOverlaySpritePixels.md) 读取 RGBA 像素。 +- 再创建： + - `R8G8B8A8_UNorm` 的 `Texture2D` + - 对应 `ShaderResourceView` + - 一个 binding `0`、类型为 `SRV` 的 descriptor set +- 最后把 SRV 写入 `textureSet->Update(0, entry.shaderView)`。 + +### 4. 失败时只清当前条目 + +- 任何一步失败都会先销毁当前正在构建的 `ResourceEntry`，然后返回 `false`。 +- 已经成功构建的其他条目不会在这里被整体回滚。 + +## 返回值 + +- `true` 表示当前已知的 overlay sprite 资源都已可用。 +- `false` 表示输入无效或某个资源加载 / 创建失败。 + +## 相关文档 + +- [SceneViewportOverlaySpriteResourceCache](SceneViewportOverlaySpriteResourceCache.md) +- [Shutdown](Shutdown.md) +- [LoadSceneViewportOverlaySpritePixels](LoadSceneViewportOverlaySpritePixels.md) +- [GetTextureSet](GetTextureSet.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlaySpriteResources/GetSceneViewportOverlaySpriteAssetSpec.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlaySpriteResources/GetSceneViewportOverlaySpriteAssetSpec.md new file mode 100644 index 00000000..fbc80485 --- /dev/null +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlaySpriteResources/GetSceneViewportOverlaySpriteAssetSpec.md @@ -0,0 +1,37 @@ +# GetSceneViewportOverlaySpriteAssetSpec + +**命名空间**: `XCEngine::Editor` + +**类型**: `inline function` + +**源文件**: `editor/src/Viewport/SceneViewportOverlaySpriteResources.h` + +## 签名 + +```cpp +inline SceneViewportOverlaySpriteAssetSpec GetSceneViewportOverlaySpriteAssetSpec( + SceneViewportOverlaySpriteTextureKind textureKind); +``` + +## 参数 + +- `textureKind` - 要解析的逻辑 sprite 种类。 + +## 当前语义 + +- 返回值里的 `kind` 会原样保留输入枚举。 +- `Camera` 当前解析为 [GetSceneViewportCameraGizmoIconPath](../SceneViewportResourcePaths/GetSceneViewportCameraGizmoIconPath.md)。 +- `Light` 当前解析为 [GetSceneViewportMainLightGizmoIconPath](../SceneViewportResourcePaths/GetSceneViewportMainLightGizmoIconPath.md)。 +- 默认分支不会抛错，而是保留空的 `resourcePath`；后续 + [LoadSceneViewportOverlaySpritePixels](LoadSceneViewportOverlaySpritePixels.md) + 会把这种情况视为失败路径。 + +## 返回值 + +- 包含逻辑 kind 与实际绝对资源路径的快照。 + +## 相关文档 + +- [SceneViewportOverlaySpriteResources](SceneViewportOverlaySpriteResources.md) +- [SceneViewportOverlaySpriteAssetSpec](SceneViewportOverlaySpriteAssetSpec.md) +- [LoadSceneViewportOverlaySpritePixels](LoadSceneViewportOverlaySpritePixels.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlaySpriteResources/GetSceneViewportOverlaySpriteResourceIndex.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlaySpriteResources/GetSceneViewportOverlaySpriteResourceIndex.md new file mode 100644 index 00000000..a567e16e --- /dev/null +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlaySpriteResources/GetSceneViewportOverlaySpriteResourceIndex.md @@ -0,0 +1,38 @@ +# GetSceneViewportOverlaySpriteResourceIndex + +**命名空间**: `XCEngine::Editor` + +**类型**: `inline function` + +**源文件**: `editor/src/Viewport/SceneViewportOverlaySpriteResources.h` + +## 签名 + +```cpp +inline size_t GetSceneViewportOverlaySpriteResourceIndex( + SceneViewportOverlaySpriteTextureKind textureKind); +``` + +## 参数 + +- `textureKind` - 逻辑 sprite 种类。 + +## 当前语义 + +- `Camera` 返回 `0`。 +- `Light` 返回 `1`。 +- 其他未识别枚举值当前也回退到 `0`，从而保持数组访问安全并默认落回首个资源位。 + +这个函数当前被 +[SceneViewportOverlaySpriteResourceCache](SceneViewportOverlaySpriteResourceCache.md) +与 `SceneViewportEditorOverlayPassRenderer` 的 sprite batch 访问共同使用。 + +## 返回值 + +- `textureKind` 对应的稳定资源下标。 + +## 相关文档 + +- [SceneViewportOverlaySpriteResources](SceneViewportOverlaySpriteResources.md) +- [GetSceneViewportOverlaySpriteTextureKindByIndex](GetSceneViewportOverlaySpriteTextureKindByIndex.md) +- [kSceneViewportOverlaySpriteTextureKinds](kSceneViewportOverlaySpriteTextureKinds.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlaySpriteResources/GetSceneViewportOverlaySpriteTextureKindByIndex.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlaySpriteResources/GetSceneViewportOverlaySpriteTextureKindByIndex.md new file mode 100644 index 00000000..fbbb5559 --- /dev/null +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlaySpriteResources/GetSceneViewportOverlaySpriteTextureKindByIndex.md @@ -0,0 +1,38 @@ +# GetSceneViewportOverlaySpriteTextureKindByIndex + +**命名空间**: `XCEngine::Editor` + +**类型**: `inline function` + +**源文件**: `editor/src/Viewport/SceneViewportOverlaySpriteResources.h` + +## 签名 + +```cpp +inline SceneViewportOverlaySpriteTextureKind GetSceneViewportOverlaySpriteTextureKindByIndex( + size_t textureIndex); +``` + +## 参数 + +- `textureIndex` - overlay sprite 资源数组下标。 + +## 当前语义 + +- `0` 返回 `SceneViewportOverlaySpriteTextureKind::Camera`。 +- `1` 返回 `SceneViewportOverlaySpriteTextureKind::Light`。 +- 越界下标当前回退到首个 kind，也就是 `Camera`。 + +这个回退策略与 +[GetSceneViewportOverlaySpriteResourceIndex](GetSceneViewportOverlaySpriteResourceIndex.md) +的“未知值落回首项”保持对称，便于 cache 与 render pass 复用固定大小数组。 + +## 返回值 + +- 给定下标当前对应的逻辑 sprite 种类。 + +## 相关文档 + +- [SceneViewportOverlaySpriteResources](SceneViewportOverlaySpriteResources.md) +- [GetSceneViewportOverlaySpriteResourceIndex](GetSceneViewportOverlaySpriteResourceIndex.md) +- [kSceneViewportOverlaySpriteTextureKinds](kSceneViewportOverlaySpriteTextureKinds.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlaySpriteResources/GetTextureSet.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlaySpriteResources/GetTextureSet.md new file mode 100644 index 00000000..52b05d4a --- /dev/null +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlaySpriteResources/GetTextureSet.md @@ -0,0 +1,36 @@ +# SceneViewportOverlaySpriteResourceCache::GetTextureSet + +**命名空间**: `XCEngine::Editor` + +**类型**: `method` + +**源文件**: `editor/src/Viewport/SceneViewportOverlaySpriteResources.h` + +## 签名 + +```cpp +RHI::RHIDescriptorSet* GetTextureSet( + SceneViewportOverlaySpriteTextureKind textureKind) const; +``` + +## 参数 + +- `textureKind` - 要查询的逻辑 sprite 种类。 + +## 当前语义 + +- 当前通过 [GetSceneViewportOverlaySpriteResourceIndex](GetSceneViewportOverlaySpriteResourceIndex.md) + 计算数组下标，再返回该条目的 `textureSet`。 +- 这个函数本身不做懒加载；调用方需要先保证已经成功执行过 + [EnsureResources](EnsureResources.md)。 +- 若资源尚未构建完成，返回值可能是 `nullptr`。 + +## 返回值 + +- 指向指定 kind 当前 descriptor set 的非 owning 指针。 + +## 相关文档 + +- [SceneViewportOverlaySpriteResourceCache](SceneViewportOverlaySpriteResourceCache.md) +- [EnsureResources](EnsureResources.md) +- [GetSceneViewportOverlaySpriteResourceIndex](GetSceneViewportOverlaySpriteResourceIndex.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlaySpriteResources/IsValid.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlaySpriteResources/IsValid.md new file mode 100644 index 00000000..ba3f63b2 --- /dev/null +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlaySpriteResources/IsValid.md @@ -0,0 +1,38 @@ +# SceneViewportOverlaySpritePixels::IsValid + +**命名空间**: `XCEngine::Editor` + +**类型**: `method` + +**源文件**: `editor/src/Viewport/SceneViewportOverlaySpriteResources.h` + +## 签名 + +```cpp +bool IsValid() const; +``` + +## 作用 + +校验当前像素载荷是否满足一个合法 `R8G8B8A8` 贴图的基本条件。 + +## 当前语义 + +- 只有当 `width`、`height` 都大于 `0` 时才可能返回 `true`。 +- 期望字节数按 `width * height * 4` 计算。 +- 若期望字节数溢出 `size_t` 上限，立即返回 `false`。 +- 只有 `rgbaPixels.size()` 与期望字节数完全一致时才返回 `true`。 + +当前 +[LoadSceneViewportOverlaySpritePixels](LoadSceneViewportOverlaySpritePixels.md) +在解码成功后会再走一遍这层校验，避免把尺寸与字节数组不一致的载荷继续上传到 GPU。 + +## 返回值 + +- `true` 表示当前像素载荷可视为一张合法的 4 通道图像。 +- `false` 表示尺寸或字节数不一致。 + +## 相关文档 + +- [SceneViewportOverlaySpritePixels](SceneViewportOverlaySpritePixels.md) +- [LoadSceneViewportOverlaySpritePixels](LoadSceneViewportOverlaySpritePixels.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlaySpriteResources/LoadSceneViewportOverlaySpritePixels.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlaySpriteResources/LoadSceneViewportOverlaySpritePixels.md new file mode 100644 index 00000000..4d3ee9b0 --- /dev/null +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlaySpriteResources/LoadSceneViewportOverlaySpritePixels.md @@ -0,0 +1,54 @@ +# LoadSceneViewportOverlaySpritePixels + +**命名空间**: `XCEngine::Editor` + +**类型**: `function` + +**源文件**: `editor/src/Viewport/SceneViewportOverlaySpriteResources.h` + +## 签名 + +```cpp +bool LoadSceneViewportOverlaySpritePixels( + SceneViewportOverlaySpriteTextureKind textureKind, + SceneViewportOverlaySpritePixels& outPixels); +``` + +## 参数 + +- `textureKind` - 要加载的逻辑 sprite 种类。 +- `outPixels` - 成功时写入解码后的 RGBA 像素载荷，失败时会被重置为空。 + +## 当前实现行为 + +### 1. 先解析资源路径 + +- 先调用 [GetSceneViewportOverlaySpriteAssetSpec](GetSceneViewportOverlaySpriteAssetSpec.md)。 +- 如果得到的 `resourcePath` 为空，直接把 `outPixels` 清空并返回 `false`。 + +### 2. 再读取并解码图像 + +- `.cpp` 当前会先通过内部 `ReadFileBytes(...)` 读入整个文件。 +- 然后使用 `stbi_load_from_memory(..., STBI_rgb_alpha)` 强制解码为 4 通道像素。 +- 解码成功后把结果写入 `outPixels.rgbaPixels / width / height`。 + +### 3. 最后做一致性校验 + +- 返回前还会调用 [IsValid](IsValid.md)。 +- 只有路径解析、文件读取、图像解码和像素校验全部成功时才返回 `true`。 + +## 返回值 + +- `true` 表示已成功拿到合法的 RGBA 像素载荷。 +- `false` 表示路径为空、文件读取失败、图像解码失败，或像素尺寸校验失败。 + +## 测试覆盖 + +- `tests/Editor/test_scene_viewport_overlay_sprite_resources.cpp` 验证了当前 `Camera` / `Light` 两类资源都能成功加载像素并通过有效性检查。 + +## 相关文档 + +- [SceneViewportOverlaySpriteResources](SceneViewportOverlaySpriteResources.md) +- [SceneViewportOverlaySpriteAssetSpec](SceneViewportOverlaySpriteAssetSpec.md) +- [SceneViewportOverlaySpritePixels](SceneViewportOverlaySpritePixels.md) +- [SceneViewportOverlaySpriteResourceCache](SceneViewportOverlaySpriteResourceCache.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlaySpriteResources/SceneViewportOverlaySpriteAssetSpec.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlaySpriteResources/SceneViewportOverlaySpriteAssetSpec.md new file mode 100644 index 00000000..ecd7823f --- /dev/null +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlaySpriteResources/SceneViewportOverlaySpriteAssetSpec.md @@ -0,0 +1,31 @@ +# SceneViewportOverlaySpriteAssetSpec + +**命名空间**: `XCEngine::Editor` + +**类型**: `struct` + +**源文件**: `editor/src/Viewport/SceneViewportOverlaySpriteResources.h` + +## 描述 + +描述单个 Scene View overlay sprite 资源的逻辑种类与实际资源路径。 + +## 当前字段 + +- `kind` +- `resourcePath` + +## 当前语义 + +- `kind` 表示逻辑 sprite 种类，例如 `Camera` 或 `Light`。 +- `resourcePath` 是通过 [SceneViewportResourcePaths](../SceneViewportResourcePaths/SceneViewportResourcePaths.md) + 解析出来的 repo 内绝对路径，而不是相对路径或 `ImTextureID`。 +- 对于当前未识别的 kind， + [GetSceneViewportOverlaySpriteAssetSpec](GetSceneViewportOverlaySpriteAssetSpec.md) + 会保留空路径，后续加载函数会直接失败返回。 + +## 相关文档 + +- [SceneViewportOverlaySpriteResources](SceneViewportOverlaySpriteResources.md) +- [GetSceneViewportOverlaySpriteAssetSpec](GetSceneViewportOverlaySpriteAssetSpec.md) +- [SceneViewportResourcePaths](../SceneViewportResourcePaths/SceneViewportResourcePaths.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlaySpriteResources/SceneViewportOverlaySpritePixels.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlaySpriteResources/SceneViewportOverlaySpritePixels.md new file mode 100644 index 00000000..5bea7fd5 --- /dev/null +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlaySpriteResources/SceneViewportOverlaySpritePixels.md @@ -0,0 +1,40 @@ +# SceneViewportOverlaySpritePixels + +**命名空间**: `XCEngine::Editor` + +**类型**: `struct` + +**源文件**: `editor/src/Viewport/SceneViewportOverlaySpriteResources.h` + +## 描述 + +承载单张 overlay sprite 图标解码后的 RGBA 像素与尺寸信息。 + +## 当前字段 + +- `rgbaPixels` +- `width` +- `height` + +## 当前语义 + +- `rgbaPixels` 当前保存 4 通道 `R8G8B8A8` 像素数据。 +- `width` 与 `height` 由 `stbi_load_from_memory(..., STBI_rgb_alpha)` 解码结果写入。 +- 这个结构体本身不持有 GPU 资源；它只是 + [LoadSceneViewportOverlaySpritePixels](LoadSceneViewportOverlaySpritePixels.md) + 与 [SceneViewportOverlaySpriteResourceCache](SceneViewportOverlaySpriteResourceCache.md) + 之间的 CPU 侧载荷。 + +## 校验方法 + +- [IsValid](IsValid.md) 会检查： + - `width > 0` + - `height > 0` + - `width * height * 4` 没有溢出 + - `rgbaPixels.size()` 恰好等于预期字节数 + +## 相关文档 + +- [SceneViewportOverlaySpriteResources](SceneViewportOverlaySpriteResources.md) +- [IsValid](IsValid.md) +- [LoadSceneViewportOverlaySpritePixels](LoadSceneViewportOverlaySpritePixels.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlaySpriteResources/SceneViewportOverlaySpriteResourceCache.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlaySpriteResources/SceneViewportOverlaySpriteResourceCache.md new file mode 100644 index 00000000..39d9a287 --- /dev/null +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlaySpriteResources/SceneViewportOverlaySpriteResourceCache.md @@ -0,0 +1,44 @@ +# SceneViewportOverlaySpriteResourceCache + +**命名空间**: `XCEngine::Editor` + +**类型**: `class` + +**源文件**: `editor/src/Viewport/SceneViewportOverlaySpriteResources.h` + +**描述**: 懒加载并缓存 Scene View overlay sprite 的 `RHITexture / SRV / descriptor set`。 + +## 概述 + +`SceneViewportOverlaySpriteResourceCache` 负责把 +[LoadSceneViewportOverlaySpritePixels](LoadSceneViewportOverlaySpritePixels.md) +得到的 CPU 像素载荷上传为 GPU 资源，并按照 +[kSceneViewportOverlaySpriteTextureKinds](kSceneViewportOverlaySpriteTextureKinds.md) +的稳定顺序缓存起来。 + +它当前由 `SceneViewportEditorOverlayPassRenderer` 持有，用来支撑 world sprite 的绘制阶段： + +- `EnsureResources(...)` 懒加载全部已知 icon 纹理 +- [GetTextureSet](GetTextureSet.md) 返回指定 kind 的 SRV descriptor set +- [Shutdown](Shutdown.md) 释放缓存的 GPU 资源 + +## 公开方法 + +| 成员 | 说明 | +|------|------| +| [Destructor](Destructor.md) | 默认析构；真正的 GPU 资源释放依赖显式 `Shutdown()`。 | +| [Shutdown](Shutdown.md) | 释放缓存的纹理、SRV 与 descriptor set。 | +| [EnsureResources](EnsureResources.md) | 按需创建并缓存所有已知 overlay sprite 资源。 | +| [GetTextureSet](GetTextureSet.md) | 返回指定 kind 当前对应的纹理 descriptor set。 | + +## 当前实现边界 + +- 当前只缓存 `Camera` 与 `Light` 两类图标。 +- 只接受外部传入的 `RHIDevice*` 与 `RHIDescriptorPool*`，自身不拥有设备。 +- 若设备或纹理 descriptor pool 发生切换，会先显式调用 [Shutdown](Shutdown.md) 再重建。 + +## 相关文档 + +- [SceneViewportOverlaySpriteResources](SceneViewportOverlaySpriteResources.md) +- [LoadSceneViewportOverlaySpritePixels](LoadSceneViewportOverlaySpritePixels.md) +- [SceneViewportEditorOverlayPass](../Passes/SceneViewportEditorOverlayPass/SceneViewportEditorOverlayPass.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlaySpriteResources/SceneViewportOverlaySpriteResources.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlaySpriteResources/SceneViewportOverlaySpriteResources.md new file mode 100644 index 00000000..32e2154e --- /dev/null +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlaySpriteResources/SceneViewportOverlaySpriteResources.md @@ -0,0 +1,50 @@ +# SceneViewportOverlaySpriteResources + +**命名空间**: `XCEngine::Editor` + +**类型**: `inline helper header + resource cache` + +**源文件**: `editor/src/Viewport/SceneViewportOverlaySpriteResources.h` + +**描述**: 为 Scene View overlay sprite 提供 texture-kind 映射、editor 资源路径解析、RGBA 像素解码与 GPU descriptor 缓存。 + +## 概述 + +`SceneViewportOverlaySpriteResources.h` 不是 overlay builder，也不是 render pass。它只负责把 +`SceneViewportOverlaySpriteTextureKind` 这层逻辑标识映射到真正可消费的资源： + +- 稳定的 kind -> index 顺序 +- `editor/resources/Icons/...` 绝对路径 +- 解码后的 RGBA 像素缓冲 +- 供 `SceneViewportEditorOverlayPassRenderer` 复用的 `RHITexture / SRV / descriptor set` + +当前 `SceneViewportEditorOverlayPassRenderer::EnsureIconTexturesLoaded()` 已经通过 +[SceneViewportOverlaySpriteResourceCache](SceneViewportOverlaySpriteResourceCache.md) +统一管理 camera / light 两类 Scene View icon 资源，而不是在 pass 内部零散维护文件路径和纹理生命周期。 + +## 公开常量、类型与函数 + +| 成员 | 说明 | +|------|------| +| [kSceneViewportOverlaySpriteTextureKinds](kSceneViewportOverlaySpriteTextureKinds.md) | 当前支持的 overlay sprite texture kind 稳定顺序。 | +| [kSceneViewportOverlaySpriteResourceCount](kSceneViewportOverlaySpriteResourceCount.md) | 当前 overlay sprite 资源总数。 | +| [GetSceneViewportOverlaySpriteResourceIndex](GetSceneViewportOverlaySpriteResourceIndex.md) | 把 `textureKind` 映射到稳定数组下标。 | +| [GetSceneViewportOverlaySpriteTextureKindByIndex](GetSceneViewportOverlaySpriteTextureKindByIndex.md) | 反向把数组下标映射回 `textureKind`。 | +| [SceneViewportOverlaySpriteAssetSpec](SceneViewportOverlaySpriteAssetSpec.md) | 单个 overlay sprite 资源的逻辑 kind + 绝对路径快照。 | +| [GetSceneViewportOverlaySpriteAssetSpec](GetSceneViewportOverlaySpriteAssetSpec.md) | 解析指定 kind 当前应该使用的 editor 资源路径。 | +| [SceneViewportOverlaySpritePixels](SceneViewportOverlaySpritePixels.md) | 解码后的 RGBA 像素载荷。 | +| [IsValid](IsValid.md) | 校验像素载荷是否满足 `width * height * 4`。 | +| [LoadSceneViewportOverlaySpritePixels](LoadSceneViewportOverlaySpritePixels.md) | 从 editor 资源文件加载并解码 RGBA 像素。 | +| [SceneViewportOverlaySpriteResourceCache](SceneViewportOverlaySpriteResourceCache.md) | 懒加载并缓存 overlay sprite 的 GPU 资源与 descriptor set。 | + +## 测试覆盖 + +- `tests/Editor/test_scene_viewport_overlay_sprite_resources.cpp` 覆盖了稳定 kind 顺序、asset spec 路径解析，以及像素加载与有效性校验。 +- `SceneViewportOverlaySpriteResourceCache` 当前没有独立的 RHI 单元测试；它的生命周期约束主要由 [SceneViewportEditorOverlayPass](../Passes/SceneViewportEditorOverlayPass/SceneViewportEditorOverlayPass.md) 调用链消费。 + +## 相关文档 + +- [Viewport](../Viewport.md) +- [SceneViewportEditorOverlayData](../SceneViewportEditorOverlayData/SceneViewportEditorOverlayData.md) +- [SceneViewportResourcePaths](../SceneViewportResourcePaths/SceneViewportResourcePaths.md) +- [SceneViewportEditorOverlayPass](../Passes/SceneViewportEditorOverlayPass/SceneViewportEditorOverlayPass.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlaySpriteResources/Shutdown.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlaySpriteResources/Shutdown.md new file mode 100644 index 00000000..c067f9e1 --- /dev/null +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlaySpriteResources/Shutdown.md @@ -0,0 +1,40 @@ +# SceneViewportOverlaySpriteResourceCache::Shutdown + +**命名空间**: `XCEngine::Editor` + +**类型**: `method` + +**源文件**: `editor/src/Viewport/SceneViewportOverlaySpriteResources.h` + +## 签名 + +```cpp +void Shutdown(); +``` + +## 作用 + +释放当前 cache 持有的全部 overlay sprite GPU 资源，并把内部状态复位。 + +## 当前实现行为 + +- 逐个遍历内部 `m_resources` 数组。 +- 对每个条目调用内部 `DestroyResourceEntry(...)`，依次释放： + - `RHIDescriptorSet` + - `RHIResourceView` + - `RHITexture` +- 遍历完成后，把： + - `m_device` + - `m_texturePool` + 统一清空为 `nullptr`。 + +## 当前语义 + +- `Shutdown()` 可以重复调用；空条目会被安全跳过。 +- 当 [EnsureResources](EnsureResources.md) 发现设备或纹理 descriptor pool 发生切换时，也会先调用这里清空旧缓存。 + +## 相关文档 + +- [SceneViewportOverlaySpriteResourceCache](SceneViewportOverlaySpriteResourceCache.md) +- [EnsureResources](EnsureResources.md) +- [SceneViewportEditorOverlayPassRenderer::Shutdown](../Passes/SceneViewportEditorOverlayPass/Shutdown.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlaySpriteResources/kSceneViewportOverlaySpriteResourceCount.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlaySpriteResources/kSceneViewportOverlaySpriteResourceCount.md new file mode 100644 index 00000000..d35e3dd4 --- /dev/null +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlaySpriteResources/kSceneViewportOverlaySpriteResourceCount.md @@ -0,0 +1,26 @@ +# kSceneViewportOverlaySpriteResourceCount + +**命名空间**: `XCEngine::Editor` + +**类型**: `inline constexpr constant` + +**源文件**: `editor/src/Viewport/SceneViewportOverlaySpriteResources.h` + +## 声明 + +```cpp +inline constexpr size_t kSceneViewportOverlaySpriteResourceCount = + kSceneViewportOverlaySpriteTextureKinds.size(); +``` + +## 当前语义 + +- 当前值由 [kSceneViewportOverlaySpriteTextureKinds](kSceneViewportOverlaySpriteTextureKinds.md) 推导，而不是手写重复常量。 +- 目前固定为 `2`，对应 `Camera` 与 `Light` 两类 Scene View overlay sprite。 +- `SceneViewportOverlaySpriteResourceCache` 的 `std::array`、overlay pass 的 batch 数组以及相关测试都依赖这个值。 + +## 相关文档 + +- [SceneViewportOverlaySpriteResources](SceneViewportOverlaySpriteResources.md) +- [kSceneViewportOverlaySpriteTextureKinds](kSceneViewportOverlaySpriteTextureKinds.md) +- [SceneViewportOverlaySpriteResourceCache](SceneViewportOverlaySpriteResourceCache.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlaySpriteResources/kSceneViewportOverlaySpriteTextureKinds.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlaySpriteResources/kSceneViewportOverlaySpriteTextureKinds.md new file mode 100644 index 00000000..adf72193 --- /dev/null +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportOverlaySpriteResources/kSceneViewportOverlaySpriteTextureKinds.md @@ -0,0 +1,31 @@ +# kSceneViewportOverlaySpriteTextureKinds + +**命名空间**: `XCEngine::Editor` + +**类型**: `inline constexpr constant` + +**源文件**: `editor/src/Viewport/SceneViewportOverlaySpriteResources.h` + +## 声明 + +```cpp +inline constexpr std::array kSceneViewportOverlaySpriteTextureKinds = { + SceneViewportOverlaySpriteTextureKind::Camera, + SceneViewportOverlaySpriteTextureKind::Light +}; +``` + +## 当前语义 + +- 当前固定顺序为 `Camera`、`Light`。 +- 这个顺序既决定了 [kSceneViewportOverlaySpriteResourceCount](kSceneViewportOverlaySpriteResourceCount.md)，也决定了 + [GetSceneViewportOverlaySpriteTextureKindByIndex](GetSceneViewportOverlaySpriteTextureKindByIndex.md) + 与 `SceneViewportEditorOverlayPassRenderer` sprite batch 数组的稳定下标。 +- `tests/Editor/test_scene_viewport_overlay_sprite_resources.cpp` 明确锁定了这个顺序，避免文档与实现再度漂移。 + +## 相关文档 + +- [SceneViewportOverlaySpriteResources](SceneViewportOverlaySpriteResources.md) +- [kSceneViewportOverlaySpriteResourceCount](kSceneViewportOverlaySpriteResourceCount.md) +- [GetSceneViewportOverlaySpriteResourceIndex](GetSceneViewportOverlaySpriteResourceIndex.md) +- [GetSceneViewportOverlaySpriteTextureKindByIndex](GetSceneViewportOverlaySpriteTextureKindByIndex.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportPassSpecs/SceneViewportGridPassData.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportPassSpecs/SceneViewportGridPassData.md index 1df1bbc4..fb6f7547 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportPassSpecs/SceneViewportGridPassData.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportPassSpecs/SceneViewportGridPassData.md @@ -6,34 +6,74 @@ **源文件**: `editor/src/Viewport/SceneViewportPassSpecs.h` -## 描述 +## 定义 -Scene View 网格 pass 的 editor 侧输入快照。 +```cpp +struct SceneViewportGridPassData { + bool valid = false; + Math::Vector3 cameraPosition = Math::Vector3::Zero(); + Math::Vector3 cameraForward = Math::Vector3::Forward(); + Math::Vector3 cameraRight = Math::Vector3::Right(); + Math::Vector3 cameraUp = Math::Vector3::Up(); + float verticalFovDegrees = 60.0f; + float nearClipPlane = 0.03f; + float farClipPlane = 2000.0f; + float orbitDistance = 6.0f; +}; +``` -## 当前字段 +## 作用 -- `valid` -- `cameraPosition` -- `cameraForward` -- `cameraRight` -- `cameraUp` -- `verticalFovDegrees` -- `nearClipPlane` -- `farClipPlane` -- `orbitDistance` +表达 Scene View 无限网格 pass 所需的 Editor 侧相机快照。 -## 当前语义 +这不是一个通用相机结构，也不是 `RenderSurface` 描述；它只保留无限网格真正需要的那组观察参数。 -- 这组字段与 runtime `Rendering::Passes::InfiniteGridPassData` 一一对应。 -- 它本身不包含样式、shader 路径或 `RenderSurface` 信息，只描述当前 Scene View 相机姿态。 -- `orbitDistance` 也会被原样传给 runtime 结构；但当前 `BuildInfiniteGridParameters(...)` 仍不会用它参与网格参数推导。 +## 字段语义 -## 测试覆盖 +| 字段 | 默认值 | 说明 | +|------|------|------| +| `valid` | `false` | 当前这份网格输入是否可用。 | +| `cameraPosition` | `Vector3::Zero()` | Scene View 相机位置。 | +| `cameraForward` | `Vector3::Forward()` | Scene View 相机前向。 | +| `cameraRight` | `Vector3::Right()` | Scene View 相机右向。 | +| `cameraUp` | `Vector3::Up()` | Scene View 相机上向。 | +| `verticalFovDegrees` | `60.0f` | 垂直 FOV。 | +| `nearClipPlane` | `0.03f` | 近裁面。 | +| `farClipPlane` | `2000.0f` | 远裁面。 | +| `orbitDistance` | `6.0f` | Scene View 相机轨道距离。 | -- `tests/Editor/test_viewport_render_flow_utils.cpp` 验证了 `BuildSceneViewportGridPassData(...)` 会把 Scene View overlay 中的相机字段正确拷贝到这里。 +## 当前实现语义 + +- 这组字段当前与 runtime [InfiniteGridPassData](../../../Rendering/Passes/BuiltinInfiniteGridPass/InfiniteGridPassData.md) 一一对应。 +- 它不包含 shader 路径、颜色风格、`RenderSurface`、命令列表等执行层信息。 +- `orbitDistance` 会被原样传给 runtime 结构；但当前 runtime 网格参数推导并不会因为这个字段存在就自动改变更高层行为。 + +## 真实构建位置 + +[BuildSceneViewportGridPassData](../ViewportHostRenderFlowUtils/BuildSceneViewportGridPassData.md) 会从 `SceneViewportOverlayData` 直接拷贝这些字段，生成当前 Editor 侧网格规格。 + +随后： + +- `SceneViewportRenderPlan` 把它交给 grid pass factory +- `SceneViewportGridPass.cpp` 再把它转换成 runtime `InfiniteGridPassData` + +## 测试锚点 + +`BuildSceneViewportGridPassDataCopiesSceneCameraState` 验证了： + +- `valid` 会被保留 +- 位置与 FOV 等相机字段会被原样复制 + +## 设计说明 + +把无限网格需要的输入明确限制在这一小组字段上，有助于保证 Scene View 网格行为稳定、可解释，而且不会被其他 Editor 状态偶然耦合进去。 + +这也是商业引擎里常见的做法：给某个专用 pass 一份最小充分输入，而不是把整个“编辑器上下文”直接塞过去。 ## 相关文档 - [SceneViewportPassSpecs](SceneViewportPassSpecs.md) - [ToBuiltinSceneViewportGridPassData](ToBuiltinSceneViewportGridPassData.md) +- [BuildSceneViewportGridPassData](../ViewportHostRenderFlowUtils/BuildSceneViewportGridPassData.md) +- [SceneViewportGridPass](../Passes/SceneViewportGridPass/SceneViewportGridPass.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 index 4ec0c23f..fcd09c1b 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportPassSpecs/SceneViewportPassSpecs.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportPassSpecs/SceneViewportPassSpecs.md @@ -6,37 +6,104 @@ **源文件**: `editor/src/Viewport/SceneViewportPassSpecs.h` -**描述**: Scene View 渲染计划与底层 runtime pass 之间的数据适配头，负责把 editor 侧的网格与选中描边配置转换成 `BuiltinInfiniteGridPass` / `BuiltinObjectIdOutlinePass` 可直接消费的结构。 +**描述**: 定义 Scene View 网格与选中描边的 Editor 侧规格结构，并提供到 runtime 内建 pass 规格的轻量转换 helper。 ## 概览 -`SceneViewportPassSpecs.h` 当前只做轻量数据桥接，不自己创建任何 `RenderPass` 或 GPU 资源。 +`SceneViewportPassSpecs.h` 是 Scene View 渲染链里一个很小、但分层意义很强的桥接头。 -它主要服务两条路径： +它解决的问题不是“怎么渲染网格或描边”，而是“Editor 这边应该用什么稳定结构表达这些需求，再怎样把它们交给 runtime pass”。 -- 网格路径：`SceneViewportGridPassData` -> [ToBuiltinSceneViewportGridPassData](ToBuiltinSceneViewportGridPassData.md) -> `Rendering::Passes::InfiniteGridPassData` -- 选中描边路径：`SceneViewportSelectionOutlineStyle` -> [ToBuiltinSceneViewportSelectionOutlineStyle](ToBuiltinSceneViewportSelectionOutlineStyle.md) -> `Rendering::Passes::ObjectIdOutlineStyle` +当前它包含两条桥接链： + +- 网格链 + - `SceneViewportGridPassData` + - [ToBuiltinSceneViewportGridPassData](ToBuiltinSceneViewportGridPassData.md) + - `Rendering::Passes::InfiniteGridPassData` +- 选中描边链 + - `SceneViewportSelectionOutlineStyle` + - [ToBuiltinSceneViewportSelectionOutlineStyle](ToBuiltinSceneViewportSelectionOutlineStyle.md) + - `Rendering::Passes::ObjectIdOutlineStyle` + +这层桥接的价值在于：Scene View 上层逻辑不需要直接依赖 runtime pass 的所有细节，runtime pass 也不需要理解 `ViewportHostService` 或 `SceneViewportRenderPlan` 的状态组织方式。 + +## 为什么需要单独一层 Editor 规格 + +如果 Scene View 直接把 runtime `InfiniteGridPassData` / `ObjectIdOutlineStyle` 暴露到更上层，会有两个现实问题： + +- Editor 工作流会被 runtime pass 契约反向绑死 +- 后续如果 Editor 想改默认值、增加说明性字段或替换底层实现，扩展点会很差 + +当前单独保留 Editor 侧规格，意味着： + +- `ViewportHostRenderFlowUtils` 可以先按 Editor 语义构建数据 +- `SceneViewportGridPass` / `SceneViewportSelectionOutlinePass` 再把它们转换给 runtime pass + +这和商业引擎里常见的“编辑器状态结构”和“渲染后端提交结构”分层是一致的。 ## 公开类型与函数 | 成员 | 说明 | |------|------| -| [SceneViewportGridPassData](SceneViewportGridPassData.md) | editor 侧网格 pass 输入快照。 | -| [ToBuiltinSceneViewportGridPassData](ToBuiltinSceneViewportGridPassData.md) | 把 editor 网格数据拷贝成 runtime infinite-grid 输入。 | -| [SceneViewportSelectionOutlineStyle](SceneViewportSelectionOutlineStyle.md) | editor 侧选中描边样式。 | -| [ToBuiltinSceneViewportSelectionOutlineStyle](ToBuiltinSceneViewportSelectionOutlineStyle.md) | 把 editor 描边样式拷贝成 runtime outline 样式。 | +| [SceneViewportGridPassData](SceneViewportGridPassData.md) | Scene View 无限网格的 Editor 侧输入快照。 | +| [ToBuiltinSceneViewportGridPassData](ToBuiltinSceneViewportGridPassData.md) | 把 Editor 网格规格拷贝成 runtime `InfiniteGridPassData`。 | +| [SceneViewportSelectionOutlineStyle](SceneViewportSelectionOutlineStyle.md) | Scene View 选中描边的 Editor 侧样式配置。 | +| [ToBuiltinSceneViewportSelectionOutlineStyle](ToBuiltinSceneViewportSelectionOutlineStyle.md) | 把 Editor 描边样式拷贝成 runtime `ObjectIdOutlineStyle`。 | ## 当前使用位置 -- `ViewportHostRenderFlowUtils.h` 当前构建这两个 editor 侧结构。 -- `SceneViewportGridPass.cpp` 和 `SceneViewportSelectionOutlinePass.cpp` 会把它们进一步转换成 runtime pass 输入。 -- `tests/Editor/test_viewport_render_flow_utils.cpp` 覆盖了这两组数据的默认值和拷贝行为。 +按当前源码： + +- `ViewportHostRenderFlowUtils.h` + - [BuildSceneViewportGridPassData](../ViewportHostRenderFlowUtils/BuildSceneViewportGridPassData.md) 构建 `SceneViewportGridPassData` + - [BuildSceneViewportSelectionOutlineStyle](../ViewportHostRenderFlowUtils/BuildSceneViewportSelectionOutlineStyle.md) 构建 `SceneViewportSelectionOutlineStyle` +- `SceneViewportRenderPlan.h` + - 用这两个 Editor 规格作为 factory 的参数类型 +- `Passes/SceneViewportGridPass.cpp` + - 调用 [ToBuiltinSceneViewportGridPassData](ToBuiltinSceneViewportGridPassData.md) +- `Passes/SceneViewportSelectionOutlinePass.cpp` + - 调用 [ToBuiltinSceneViewportSelectionOutlineStyle](ToBuiltinSceneViewportSelectionOutlineStyle.md) + +## 当前实现特征 + +当前这四个声明都很克制： + +- 结构体只保存必要字段 +- 转换函数只做字段拷贝 +- 不做额外推导、clamp、颜色空间修正或策略判断 + +这说明这层桥接的目标就是“稳定传递语义”，而不是在中途偷偷改变含义。 + +## 测试与调用链锚点 + +- `tests/Editor/test_viewport_render_flow_utils.cpp` + - `BuildSceneViewportGridPassDataCopiesSceneCameraState` + - `BuildSceneViewportSelectionOutlineStyleAppliesSceneDefaults` +- `editor/src/Viewport/Passes/SceneViewportGridPass.cpp` +- `editor/src/Viewport/Passes/SceneViewportSelectionOutlinePass.cpp` + +## 设计说明 + +这层桥接的设计重点在于“Editor 默认值归 Editor 管，runtime 执行格式归 runtime 管”。 + +例如： + +- 网格是否有效、相机姿态是什么，由 Editor 侧决定 +- 具体 grid shader 如何利用这些字段，由 runtime `BuiltinInfiniteGridPass` 决定 + +同样地： + +- Scene View 默认橙色 `2px` 描边，是 Editor 视觉语言 +- runtime outline pass 只消费统一格式，不关心这个默认值最初来自哪个面板或 helper + +这样分层后，Scene View 的文档、测试和实现都会更稳。 ## 相关文档 -- [SceneViewportGridPassData](SceneViewportGridPassData.md) -- [ToBuiltinSceneViewportGridPassData](ToBuiltinSceneViewportGridPassData.md) -- [SceneViewportSelectionOutlineStyle](SceneViewportSelectionOutlineStyle.md) -- [ToBuiltinSceneViewportSelectionOutlineStyle](ToBuiltinSceneViewportSelectionOutlineStyle.md) +- [Viewport](../Viewport.md) +- [ViewportHostRenderFlowUtils](../ViewportHostRenderFlowUtils/ViewportHostRenderFlowUtils.md) +- [SceneViewportRenderPlan](../SceneViewportRenderPlan/SceneViewportRenderPlan.md) - [SceneViewportGridPass](../Passes/SceneViewportGridPass/SceneViewportGridPass.md) - [SceneViewportSelectionOutlinePass](../Passes/SceneViewportSelectionOutlinePass/SceneViewportSelectionOutlinePass.md) +- [InfiniteGridPassData](../../../Rendering/Passes/BuiltinInfiniteGridPass/InfiniteGridPassData.md) +- [ObjectIdOutlineStyle](../../../Rendering/Passes/ObjectIdOutlineStyle/ObjectIdOutlineStyle.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportPassSpecs/SceneViewportSelectionOutlineStyle.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportPassSpecs/SceneViewportSelectionOutlineStyle.md index 689ce982..081e6cc3 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportPassSpecs/SceneViewportSelectionOutlineStyle.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportPassSpecs/SceneViewportSelectionOutlineStyle.md @@ -6,28 +6,64 @@ **源文件**: `editor/src/Viewport/SceneViewportPassSpecs.h` -## 描述 +## 定义 -Scene View 选中描边 pass 的 editor 侧样式配置。 +```cpp +struct SceneViewportSelectionOutlineStyle { + Math::Color outlineColor = Math::Color(1.0f, 0.4f, 0.0f, 1.0f); + float outlineWidthPixels = 2.0f; + bool debugSelectionMask = false; +}; +``` -## 当前字段与默认值 +## 作用 -- `outlineColor = Math::Color(1.0f, 0.4f, 0.0f, 1.0f)` -- `outlineWidthPixels = 2.0f` -- `debugSelectionMask = false` +表达 Scene View 选中描边 pass 的 Editor 侧样式规范。 -## 当前语义 +它的重点不是对象选择逻辑，而是“当 Scene View 确定要画选中轮廓时，应该使用怎样的视觉样式”。 -- 这组字段与 runtime `Rendering::Passes::ObjectIdOutlineStyle` 一一对应。 -- 默认样式就是当前 Scene View 常见的橙色、`2px` 选中描边。 -- `debugSelectionMask` 打开时，底层 outline pass 会切换到调试遮罩输出语义，而不是正常描边合成。 +## 字段与默认值 -## 测试覆盖 +| 字段 | 默认值 | 说明 | +|------|------|------| +| `outlineColor` | `(1.0, 0.4, 0.0, 1.0)` | 当前默认橙色描边。 | +| `outlineWidthPixels` | `2.0f` | 当前默认描边宽度。 | +| `debugSelectionMask` | `false` | 是否切到调试遮罩语义。 | -- `tests/Editor/test_viewport_render_flow_utils.cpp` 验证了默认样式和 debug 样式构建结果。 +## 当前实现语义 + +- 这组字段当前与 runtime [ObjectIdOutlineStyle](../../../Rendering/Passes/ObjectIdOutlineStyle/ObjectIdOutlineStyle.md) 一一对应。 +- 默认值就是当前 Scene View 的标准视觉语言：橙色、`2px`。 +- `debugSelectionMask == true` 时，底层 outline pass 会切换到调试遮罩输出思路，而不是普通的轮廓合成。 + +## 真实构建位置 + +[BuildSceneViewportSelectionOutlineStyle](../ViewportHostRenderFlowUtils/BuildSceneViewportSelectionOutlineStyle.md) 是当前默认样式的构建入口。 + +随后： + +- `SceneViewportRenderPlan` 把这份样式交给 selection outline factory +- `SceneViewportSelectionOutlinePass.cpp` 再把它转换成 runtime `ObjectIdOutlineStyle` + +## 测试锚点 + +`BuildSceneViewportSelectionOutlineStyleAppliesSceneDefaults` 验证了： + +- 默认颜色是橙色 +- 默认宽度是 `2.0` +- debug mask 标志会被正确透传 + +## 设计说明 + +把 Scene View 的选中描边样式保留成一份独立 Editor 结构，而不是直接裸传 runtime `ObjectIdOutlineStyle`，有两个重要意义： + +- Editor 视觉规范有自己稳定的表述层 +- 底层 pass 替换或扩展时，上层 API 不会立刻被绑死到 runtime 类型命名上 ## 相关文档 - [SceneViewportPassSpecs](SceneViewportPassSpecs.md) - [ToBuiltinSceneViewportSelectionOutlineStyle](ToBuiltinSceneViewportSelectionOutlineStyle.md) +- [BuildSceneViewportSelectionOutlineStyle](../ViewportHostRenderFlowUtils/BuildSceneViewportSelectionOutlineStyle.md) +- [SceneViewportSelectionOutlinePass](../Passes/SceneViewportSelectionOutlinePass/SceneViewportSelectionOutlinePass.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 index 8259b871..3ccdafd3 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportPassSpecs/ToBuiltinSceneViewportGridPassData.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportPassSpecs/ToBuiltinSceneViewportGridPassData.md @@ -1,37 +1,66 @@ # ToBuiltinSceneViewportGridPassData -把 editor 侧网格输入拷贝成 runtime infinite-grid 输入。 +**命名空间**: `XCEngine::Editor` + +**类型**: `function` + +**源文件**: `editor/src/Viewport/SceneViewportPassSpecs.h` + +## 签名 ```cpp -inline Rendering::Passes::InfiniteGridPassData ToBuiltinSceneViewportGridPassData( +Rendering::Passes::InfiniteGridPassData ToBuiltinSceneViewportGridPassData( const SceneViewportGridPassData& data); ``` -## 参数 +## 作用 -- `data` - editor 侧网格 pass 输入。 +把 Editor 侧的 [SceneViewportGridPassData](SceneViewportGridPassData.md) 转换成 runtime `BuiltinInfiniteGridPass` 可直接消费的 `InfiniteGridPassData`。 -## 当前语义 +## 当前实现行为 -- 当前实现只是字段逐项拷贝： - - `valid` - - `cameraPosition` - - `cameraForward` - - `cameraRight` - - `cameraUp` - - `verticalFovDegrees` - - `nearClipPlane` - - `farClipPlane` - - `orbitDistance` -- 它不做坐标变换、默认值修正或单位换算。 +当前实现只做字段逐项拷贝： -## 调用方影响 +- `valid` +- `cameraPosition` +- `cameraForward` +- `cameraRight` +- `cameraUp` +- `verticalFovDegrees` +- `nearClipPlane` +- `farClipPlane` +- `orbitDistance` -- `SceneViewportGridPassRenderer` 最终会把转换结果交给 runtime [BuiltinInfiniteGridPass](../../../Rendering/Passes/BuiltinInfiniteGridPass/BuiltinInfiniteGridPass.md)。 -- 因为这里只做拷贝，所以如果 editor 侧输入本身无效，runtime 行为也会直接继承这一状态。 +它不做： + +- 坐标变换 +- 单位换算 +- 默认值修正 +- 视锥裁剪规则推导 + +## 真实使用位置 + +`editor/src/Viewport/Passes/SceneViewportGridPass.cpp` 中，当前实现会在真正调用 runtime `BuiltinInfiniteGridPass::Render(...)` 之前，把 Editor 侧网格规格转换成 runtime 规格。 + +这意味着： + +- Editor 层负责决定“Scene View 想要什么网格语义” +- runtime pass 负责决定“拿到这些字段后如何真正绘制网格” + +## 设计说明 + +这里只做纯拷贝，而不是在中间层做更多逻辑判断，是一个很稳的设计选择。 + +因为一旦桥接层开始偷偷修正输入，就会让问题定位变得困难： + +- 上层以为自己传的是 A +- runtime 看到的却是被桥接层改过的 B + +当前这层保持透明转换，文档和测试都更容易对齐源码真实行为。 ## 相关文档 - [SceneViewportPassSpecs](SceneViewportPassSpecs.md) - [SceneViewportGridPassData](SceneViewportGridPassData.md) +- [SceneViewportGridPass](../Passes/SceneViewportGridPass/SceneViewportGridPass.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 index a8dddd0b..448a8ea5 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportPassSpecs/ToBuiltinSceneViewportSelectionOutlineStyle.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportPassSpecs/ToBuiltinSceneViewportSelectionOutlineStyle.md @@ -1,30 +1,56 @@ # ToBuiltinSceneViewportSelectionOutlineStyle -把 editor 侧选中描边样式拷贝成 runtime outline 样式。 +**命名空间**: `XCEngine::Editor` + +**类型**: `function` + +**源文件**: `editor/src/Viewport/SceneViewportPassSpecs.h` + +## 签名 ```cpp -inline Rendering::Passes::ObjectIdOutlineStyle ToBuiltinSceneViewportSelectionOutlineStyle( +Rendering::Passes::ObjectIdOutlineStyle ToBuiltinSceneViewportSelectionOutlineStyle( const SceneViewportSelectionOutlineStyle& style); ``` -## 参数 +## 作用 -- `style` - editor 侧描边样式。 +把 Editor 侧 [SceneViewportSelectionOutlineStyle](SceneViewportSelectionOutlineStyle.md) 转换成 runtime `BuiltinObjectIdOutlinePass` 可直接消费的 `ObjectIdOutlineStyle`。 -## 当前语义 +## 当前实现行为 -- 当前实现只做字段逐项拷贝： - - `outlineColor` - - `outlineWidthPixels` - - `debugSelectionMask` -- 不做颜色空间转换、宽度 clamp 或额外策略判断。 +当前实现只做字段逐项拷贝： -## 调用方影响 +- `outlineColor` +- `outlineWidthPixels` +- `debugSelectionMask` -- `SceneViewportSelectionOutlinePassRenderer` 会把转换结果直接交给 runtime [BuiltinObjectIdOutlinePass](../../../Rendering/Passes/BuiltinObjectIdOutlinePass/BuiltinObjectIdOutlinePass.md)。 +它不做： + +- 颜色空间转换 +- 线宽 clamp +- 样式主题替换 +- object-id 可用性检查 + +这些更高层决策都不属于桥接层职责。 + +## 真实使用位置 + +`editor/src/Viewport/Passes/SceneViewportSelectionOutlinePass.cpp` 当前会在真正调用 runtime outline pass 前，先通过本函数把 Editor 样式转换成 runtime 样式。 + +## 设计说明 + +这类样式桥接函数最重要的原则是“忠实传递，而不是中途策略化”。 + +当前保持纯拷贝意味着： + +- 样式默认值的来源仍然清楚地在 Editor 层 +- runtime pass 只面对统一格式 +- 调试时不会出现“文档写的是一种样式，运行时却被桥接层悄悄改成另一种”的问题 ## 相关文档 - [SceneViewportPassSpecs](SceneViewportPassSpecs.md) - [SceneViewportSelectionOutlineStyle](SceneViewportSelectionOutlineStyle.md) +- [SceneViewportSelectionOutlinePass](../Passes/SceneViewportSelectionOutlinePass/SceneViewportSelectionOutlinePass.md) - [ObjectIdOutlineStyle](../../../Rendering/Passes/ObjectIdOutlineStyle/ObjectIdOutlineStyle.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportPicker/BuildSceneViewportRay.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportPicker/BuildSceneViewportRay.md index 57eaed05..d0932b21 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportPicker/BuildSceneViewportRay.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportPicker/BuildSceneViewportRay.md @@ -22,25 +22,71 @@ bool BuildSceneViewportRay( ## 当前实现行为 -- 若 `overlay.valid` 为假，或视口尺寸/位置非法，则返回 `false`。 -- 会把 `viewportPosition` 归一化成 NDC 坐标，然后结合： - - `cameraForward` - - `cameraRight` - - `cameraUp` - - `verticalFovDegrees` - 计算世界射线方向。 -- 若最终方向长度退化到 `EPSILON` 以内，也会返回 `false`。 -- 成功时输出： - - `origin = overlay.cameraPosition` - - `direction = 归一化后的世界方向` +### 1. 输入合法性检查 + +当前会在以下情况直接返回 `false`： + +- `overlay.valid == false` +- 视口尺寸或点击位置非法 + +### 2. 把点击位置映射到 NDC + +当前会计算： + +- `aspect = viewportSize.x / viewportSize.y` +- `tanHalfFov = tan(verticalFovDegrees * 0.5)` +- `ndcX` +- `ndcY` + +其中： + +- `ndcX = (viewportPosition.x / viewportSize.x) * 2 - 1` +- `ndcY = 1 - (viewportPosition.y / viewportSize.y) * 2` + +### 3. 用相机基向量构造世界方向 + +当前世界方向来自三项线性组合： + +- `cameraForward` +- `cameraRight * (ndcX * aspect * tanHalfFov)` +- `cameraUp * (ndcY * tanHalfFov)` + +最后会做归一化。 + +### 4. 输出射线 + +若最终方向退化到 `EPSILON` 以内，则返回 `false`。 + +成功时： + +- `origin = overlay.cameraPosition` +- `direction = 归一化后的世界方向` ## 当前使用位置 +当前至少被以下路径复用： + - `SceneViewportMoveGizmo.cpp` - `SceneViewportRotateGizmo.cpp` - [PickSceneViewportEntity](PickSceneViewportEntity.md) +这说明它不仅服务 CPU picker，也服务 Scene View gizmo 交互数学。 + +## 测试锚点 + +`BuildSceneViewportRayPointsThroughViewportCenter` 验证了： + +- 当点击视口中心时，构造出的射线方向会穿过当前相机前向 + +## 设计说明 + +这个 helper 的价值在于把“屏幕坐标 -> 世界射线”的规则固定下来，让 CPU picking 和 gizmo 交互共用同一套几何入口。 + +这样做能减少“点击命中”和“拖拽射线”在边界上出现不一致。 + ## 相关文档 - [SceneViewportPicker](SceneViewportPicker.md) - [PickSceneViewportEntity](PickSceneViewportEntity.md) +- [SceneViewportMath](../SceneViewportMath/SceneViewportMath.md) +- [Scene View Overlay Contracts](../IViewportHostService/SceneView-Overlay-Contracts.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportPicker/PickSceneViewportEntity.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportPicker/PickSceneViewportEntity.md index 2972b627..678fba37 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportPicker/PickSceneViewportEntity.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportPicker/PickSceneViewportEntity.md @@ -20,36 +20,80 @@ SceneViewportPickResult PickSceneViewportEntity(const SceneViewportPickRequest& ### 1. 构造世界射线 -- 若 `request.scene == nullptr`，直接返回未命中结果。 -- 否则先调用 [BuildSceneViewportRay](BuildSceneViewportRay.md)；如果射线构造失败，也直接返回未命中。 +当前会先做两步早退检查： -### 2. 递归遍历场景 +- `request.scene == nullptr` 时直接返回默认未命中结果 +- `BuildSceneViewportRay(...)` 失败时也直接返回默认未命中结果 -- 从 `scene->GetRootGameObjects()` 出发递归遍历整棵层级树。 -- 仅当对象： - - `IsActiveInHierarchy() == true` - - 具有 `MeshFilterComponent` - - 具有 `MeshRendererComponent` - - 且二者都启用 - 时才进入网格求交。 +### 2. 从根对象递归遍历场景 -### 3. 局部空间求交 +当前从： -- 会把世界射线变换到对象局部空间。 -- 先对 mesh bounds 做一次包围盒测试。 -- 之后按 mesh 形态分别遍历： - - indexed sections - - non-indexed sections -- 求交成功后把局部命中点重新变回世界坐标，并用平方距离更新最近命中结果。 +```cpp +request.scene->GetRootGameObjects() +``` -## 当前实现边界 +出发，递归遍历整棵层级树。 -- 当前只基于渲染网格三角形命中，不考虑更粗的 editor proxy 或 collider-only 选择。 -- Scene View 的主点击选择路径当前仍是 object-id picking，不是这个 CPU picker。 +### 3. 只对可渲染网格对象求交 + +对象只有满足以下条件才会进入网格求交： + +- `IsActiveInHierarchy() == true` +- 挂有 `MeshFilterComponent` +- 挂有 `MeshRendererComponent` +- 两个组件都启用 +- 变换和网格资源可用 + +### 4. 世界射线转局部空间 + +当前会把世界射线变换到对象局部空间，再进行求交。 + +这是支持旋转和缩放对象正确拾取的关键，因为三角形数据本来就在局部空间里。 + +### 5. 先做 bounds 测试，再做三角形测试 + +当前实现会先做本地 bounds 相交，再按 mesh 形态分别遍历： + +- indexed sections +- non-indexed sections + +以减少不必要的三角形测试。 + +### 6. 只保留最近命中 + +命中成功后会： + +- 把局部命中点变回世界空间 +- 计算到射线原点的 `distanceSq` +- 只在更近时覆盖当前最佳结果 + +## 测试锚点 + +- `PickSceneViewportEntityReturnsNearestHit` +- `PickSceneViewportEntityHandlesRotatedAndScaledObjects` +- `PickSceneViewportEntityReturnsNoHitForEmptySpace` + +这些测试分别确认了： + +- 会返回最近命中 +- 旋转缩放后的对象仍能正确命中 +- 空白区域不会误报命中 + +## 设计说明 + +当前实现明确偏向“编辑器几何精确性”，而不是“高吞吐实时 picking”： + +- 它尊重对象变换 +- 它做到三角形级别命中 +- 但代价是纯 CPU 遍历在大场景里不如 object-id picking 合适 + +因此它现在更适合作为工具链和辅助路径，而不是主选择路径。 ## 相关文档 - [SceneViewportPicker](SceneViewportPicker.md) - [SceneViewportPickRequest](SceneViewportPickRequest.md) - [SceneViewportPickResult](SceneViewportPickResult.md) +- [BuildSceneViewportRay](BuildSceneViewportRay.md) - [ViewportObjectIdPicker](../ViewportObjectIdPicker/ViewportObjectIdPicker.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportPicker/SceneViewportPickRequest.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportPicker/SceneViewportPickRequest.md index 902dcce2..caf852c2 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportPicker/SceneViewportPickRequest.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportPicker/SceneViewportPickRequest.md @@ -21,21 +21,27 @@ struct SceneViewportPickRequest { 封装一次 Scene View CPU 射线拾取所需的全部输入。 -## 字段说明 +## 字段语义 | 字段 | 说明 | |------|------| | `scene` | 被遍历的场景指针。 | | `overlay` | 当前 Scene View 相机姿态、FOV 和有效性数据。 | -| `viewportSize` | 视口像素尺寸。 | -| `viewportPosition` | 视口内鼠标位置或点击位置。 | +| `viewportSize` | 当前视口像素尺寸。 | +| `viewportPosition` | 视口内点击或鼠标位置。 | -## 当前使用方式 +## 当前实现语义 -- [PickSceneViewportEntity](PickSceneViewportEntity.md) 会读取该结构体，先用其中的 `overlay + viewportSize + viewportPosition` 构造世界射线。 -- 若 `scene == nullptr`，pick 会直接返回未命中结果。 +- `scene == nullptr` 时，pick 会立即返回未命中结果 +- `overlay` 是按值存储的，这意味着请求本身保留了一份相机快照，而不是借用外部指针 +- `viewportSize` 与 `viewportPosition` 共同决定世界射线方向 + +## 设计说明 + +把 scene、overlay 和鼠标位置收成一份 request，而不是把多个散参数直接传给 `PickSceneViewportEntity(...)`，更适合未来继续扩展 picker 语义，也更方便测试直接构造输入。 ## 相关文档 - [SceneViewportPicker](SceneViewportPicker.md) - [PickSceneViewportEntity](PickSceneViewportEntity.md) +- [SceneViewportPickResult](SceneViewportPickResult.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportPicker/SceneViewportPickResult.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportPicker/SceneViewportPickResult.md index 2d1bf64f..e5d97e69 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportPicker/SceneViewportPickResult.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportPicker/SceneViewportPickResult.md @@ -21,21 +21,27 @@ struct SceneViewportPickResult { 表示一次 Scene View CPU pick 的最近命中结果。 -## 字段说明 +## 字段语义 -| 字段 | 说明 | -|------|------| -| `entityId` | 最近命中的实体 ID；未命中时为 `0`。 | -| `worldPosition` | 命中的世界坐标。 | -| `distanceSq` | 命中点到射线原点的平方距离，用于比较最近命中。 | -| `hit` | 是否存在有效命中。 | +| 字段 | 默认值 | 说明 | +|------|------|------| +| `entityId` | `0` | 最近命中的实体 ID；未命中时为 `0`。 | +| `worldPosition` | `Vector3::Zero()` | 命中点的世界坐标。 | +| `distanceSq` | `Math::FLOAT_MAX` | 命中点到射线原点的平方距离。 | +| `hit` | `false` | 是否存在有效命中。 | -## 当前实现行为 +## 当前实现语义 -- `PickSceneViewportEntity(...)` 会在遍历中不断比较 `distanceSq`，只保留最近命中。 -- 若没有命中任何三角形，则保持默认值返回。 +`PickSceneViewportEntity(...)` 在递归遍历过程中会不断比较 `distanceSq`，只保留最近命中的对象。 + +因此这个结果结构表达的是“最佳命中”，而不是“全部命中列表”。 + +## 设计说明 + +当前 picker 的职责是给编辑器交互提供单一、可立即消费的最佳命中结果，而不是做通用射线查询系统。这个结果结构也相应地保持极简。 ## 相关文档 - [SceneViewportPicker](SceneViewportPicker.md) +- [SceneViewportPickRequest](SceneViewportPickRequest.md) - [PickSceneViewportEntity](PickSceneViewportEntity.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportPicker/SceneViewportPicker.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportPicker/SceneViewportPicker.md index 0842c8bb..4c1c6190 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportPicker/SceneViewportPicker.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportPicker/SceneViewportPicker.md @@ -6,79 +6,91 @@ **源文件**: `editor/src/Viewport/SceneViewportPicker.h` -**描述**: 提供 Scene View 的 CPU 射线拾取辅助函数，可从视口坐标生成世界射线并对场景网格执行三角形求交。 +**描述**: 提供 Scene View 的 CPU 射线拾取辅助函数，可从 overlay 相机数据和视口位置构建世界射线，并对场景网格执行最近命中查询。 -## 概述 +## 概览 -`SceneViewportPicker` 代表的是传统编辑器里另一条常见的选取路径: CPU ray cast。 +`SceneViewportPicker` 代表的是编辑器里一条更传统的 CPU picking 路线。 当前它能做两件事： -- [BuildSceneViewportRay](BuildSceneViewportRay.md): 由相机姿态、FOV、视口尺寸和点击位置生成一条世界射线。 -- [PickSceneViewportEntity](PickSceneViewportEntity.md): 遍历场景根对象，对 `MeshFilterComponent` 持有的网格做三角形求交，返回最近命中对象。 +- [BuildSceneViewportRay](BuildSceneViewportRay.md) + - 从 `SceneViewportOverlayData`、视口尺寸和鼠标位置构建世界射线 +- [PickSceneViewportEntity](PickSceneViewportEntity.md) + - 用这条射线递归遍历场景网格，返回最近命中的实体 -## 公开类型 +这和当前 Scene View 左键主选取路径并不相同。现在主路径已经收敛到 object-id 读回，而 CPU picker 更多承担： + +- gizmo 数学与拖拽射线的基础工具 +- 保留的 CPU 几何拾取能力 +- 一些不依赖渲染结果的编辑器辅助场景 + +## 当前公开类型 | 类型 | 说明 | |------|------| -| [SceneViewportPickRequest](SceneViewportPickRequest.md) | 一次 CPU pick 所需的 scene、overlay 和视口坐标输入。 | +| [SceneViewportPickRequest](SceneViewportPickRequest.md) | 一次 CPU pick 所需的 scene、overlay 和视口输入。 | | [SceneViewportPickResult](SceneViewportPickResult.md) | pick 输出，包含命中实体、世界命中点和距离。 | -## 公开函数 +## 当前公开函数 | 函数 | 说明 | |------|------| | [BuildSceneViewportRay](BuildSceneViewportRay.md) | 从 Scene View overlay 相机参数构造世界射线。 | | [PickSceneViewportEntity](PickSceneViewportEntity.md) | 对场景网格做 CPU 射线求交并返回最近命中。 | -## 当前实现行为 +## 当前实现链路 -按 `SceneViewportPicker.cpp` 的实现： +按 `SceneViewportPicker.cpp` 当前实现： -- 会先把世界射线变换到对象局部空间。 -- 会先过一次本地包围盒相交，再进入三角形测试。 -- 同时支持 indexed mesh 和 non-indexed mesh 的 section 遍历。 -- 返回值里会带最近命中的 `entityId`、命中世界位置和 `distanceSq`。 +1. 先通过 `BuildSceneViewportRay(...)` 从 Scene View 相机姿态构造世界射线 +2. 从 `scene->GetRootGameObjects()` 出发递归遍历整棵层级树 +3. 只对活跃、可渲染且有网格的对象做进一步检测 +4. 把世界射线变换到对象局部空间 +5. 先做 bounds 测试，再做三角形求交 +6. 命中后把局部命中点变回世界空间，并只保留最近命中 ## 当前在编辑器里的使用状态 -这是很关键的一点： +这是一个很重要的现实边界： -- 当前 `SceneViewPanel` 左键选取主路径不是它。 -- 当前主路径是 [ViewportHostService](../ViewportHostService/ViewportHostService.md) 里的 object-id 读回 `PickSceneViewEntity(...)`。 -- 但 [BuildSceneViewportRay](BuildSceneViewportRay.md) 不是“完全闲置”的 helper；`SceneViewportMoveGizmo` 和 `SceneViewportRotateGizmo` 当前仍直接复用它来建立拖拽/命中射线。 +- Scene View 左键主选择路径当前是 [ViewportObjectIdPicker](../ViewportObjectIdPicker/ViewportObjectIdPicker.md) +- 但 [BuildSceneViewportRay](BuildSceneViewportRay.md) 仍然被： + - `SceneViewportMoveGizmo.cpp` + - `SceneViewportRotateGizmo.cpp` + 复用来建立交互射线 -也就是说，这个 picker 目前更像一个保留的独立 helper，而不是 Scene View 点击选择的主实现。 +因此 `SceneViewportPicker` 现在更像“CPU picking / ray helper 工具模块”，而不是 Scene View 鼠标点选的唯一实现。 -## 设计说明 +## 为什么仍然值得保留 CPU picker -保留 CPU picker 仍然有价值，因为它适合： +即使 object-id picking 已经是主路径，CPU picker 仍然有明确价值： -- 没有 object-id 缓冲时的回退方案。 -- 做更精细的编辑器工具命中测试。 -- 离线几何查询或非渲染式拾取。 +- 不依赖 object-id buffer +- 适合更精细的工具命中逻辑 +- 可用于调试、离线查询或某些不经过主渲染链的编辑器功能 -但从当前产品方向看，Scene View 已经明显在向“渲染结果驱动的 object-id picking”收拢。 +商业引擎里也常见这种双路径并存：一条偏渲染结果驱动，一条偏几何工具驱动。 -## 与测试的对应关系 +## 测试锚点 -`tests/Editor/test_scene_viewport_picker.cpp` 当前验证了： +`tests/Editor/test_scene_viewport_picker.cpp` 当前覆盖了： -- `BuildSceneViewportRay(...)` 会让视口中心点穿过相机 forward。 -- `PickSceneViewportEntity(...)` 会返回最近命中的对象，而不是更远的命中。 -- 旋转和缩放后的网格仍能通过局部空间求交正确选中。 -- 空白区域点击会返回未命中结果。 +- `BuildSceneViewportRay(...)` 会让视口中心点穿过相机 `forward` +- `PickSceneViewportEntity(...)` 会返回最近命中的对象 +- 旋转和缩放后的对象仍能被正确选中 +- 空白区域点击会返回未命中结果 ## 当前限制 -- `PickSceneViewportEntity(...)` 当前不是 Scene View 左键选取的主路径。 -- 纯 CPU 三角形遍历在大场景下不如 object-id 路径稳定。 -- 当前只检查带 `MeshFilterComponent + MeshRendererComponent` 且二者都启用的对象。 +- 当前不是 Scene View 主点击选择路径 +- 当前只对带 `MeshFilterComponent + MeshRendererComponent` 且两者启用的对象做 CPU picking +- 纯 CPU 三角形遍历在大场景下不如 object-id 路径稳定 ## 相关文档 - [Viewport](../Viewport.md) - [ViewportObjectIdPicker](../ViewportObjectIdPicker/ViewportObjectIdPicker.md) -- [SceneViewPanel](../../panels/SceneViewPanel/SceneViewPanel.md) - [SceneViewportMoveGizmo](../SceneViewportMoveGizmo/SceneViewportMoveGizmo.md) - [SceneViewportRotateGizmo](../SceneViewportRotateGizmo/SceneViewportRotateGizmo.md) +- [SceneViewportMath](../SceneViewportMath/SceneViewportMath.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportRenderPassBundle/BuildRenderPlan.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportRenderPassBundle/BuildRenderPlan.md new file mode 100644 index 00000000..5fb7a505 --- /dev/null +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportRenderPassBundle/BuildRenderPlan.md @@ -0,0 +1,60 @@ +# SceneViewportRenderPassBundle::BuildRenderPlan + +**命名空间**: `XCEngine::Editor` + +**类型**: `method` + +**源文件**: `editor/src/Viewport/SceneViewportRenderPassBundle.h` + +## 签名 + +```cpp +SceneViewportRenderPlanBuildResult BuildRenderPlan( + const ViewportRenderTargets& targets, + const SceneViewportOverlayData& overlay, + const std::vector& selectedObjectIds, + const SceneViewportOverlayFrameData& editorOverlayFrameData, + bool debugSelectionMask = false); +``` + +## 作用 + +使用 bundle 内部持有的 pass renderer，为当前 Scene View 构建一份可执行的 `SceneViewportRenderPlanBuildResult`。 + +## 当前行为 + +当前实现本质上是对 [BuildSceneViewportRenderPlan](../SceneViewportRenderPlan/BuildSceneViewportRenderPlan.md) 的一次封装调用。 + +它会把内部 renderer 适配成三个 factory： + +- grid factory：`CreateSceneViewportGridPass(m_gridRenderer, data)` +- selection outline factory： + `CreateSceneViewportSelectionOutlinePass(m_selectionOutlineRenderer, objectIdTextureView, selectionIds, style)` +- overlay factory：`CreateSceneViewportEditorOverlayPass(m_overlayRenderer, frameData)` + +然后把这些 factory 连同以下输入一起交给 `BuildSceneViewportRenderPlan(...)`： + +- `targets` +- `overlay` +- `selectedObjectIds` +- `editorOverlayFrameData` +- `debugSelectionMask` + +## 设计边界 + +- 这里不重新定义 Scene View pass 规划规则；是否要加 grid / outline / overlay 仍以 `SceneViewportRenderPlan` 那一层的逻辑为准。 +- 这个方法的价值在于把“renderer 所有权”和“plan 所需 factory”绑到一起，避免 `ViewportHostService` 自己散落持有三套 renderer 并重复装配 lambda。 + +## 测试覆盖 + +`tests/Editor/test_scene_viewport_render_pass_bundle.cpp` 当前覆盖了两条关键路径： + +- `BuildRenderPlanCreatesGridOutlineAndOverlayPasses` +- `BuildRenderPlanReportsMissingObjectIdShaderView` + +## 相关文档 + +- [SceneViewportRenderPassBundle](SceneViewportRenderPassBundle.md) +- [SceneViewportRenderPlan](../SceneViewportRenderPlan/SceneViewportRenderPlan.md) +- [BuildSceneViewportRenderPlan](../SceneViewportRenderPlan/BuildSceneViewportRenderPlan.md) +- [ViewportHostRenderTargets](../ViewportHostRenderTargets/ViewportHostRenderTargets.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportRenderPassBundle/SceneViewportRenderPassBundle.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportRenderPassBundle/SceneViewportRenderPassBundle.md new file mode 100644 index 00000000..529a4596 --- /dev/null +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportRenderPassBundle/SceneViewportRenderPassBundle.md @@ -0,0 +1,64 @@ +# SceneViewportRenderPassBundle + +**命名空间**: `XCEngine::Editor` + +**类型**: `class` + +**源文件**: `editor/src/Viewport/SceneViewportRenderPassBundle.h` + +**说明**: 持有 Scene View 的 grid / selection outline / editor overlay 三类 pass renderer，并把它们封装成一个可直接生成 `SceneViewportRenderPlan` 的 bundle。 + +## 概览 + +`SceneViewportRenderPassBundle` 是 `SceneViewportRenderPlan` 之上的一层轻量封装。 + +如果说 [BuildSceneViewportRenderPlan](../SceneViewportRenderPlan/BuildSceneViewportRenderPlan.md) 只负责“根据输入状态决定应该规划哪些 pass”，那么这个 bundle 负责的是另一半： + +- 持有实际 pass renderer 的生命周期。 +- 为 render plan 提供具体的 pass factory。 +- 把这三类 renderer 的 shutdown 入口收口到一起。 + +当前它内部持有： + +- `SceneViewportGridPassRenderer` +- `SceneViewportSelectionOutlinePassRenderer` +- `SceneViewportEditorOverlayPassRenderer` + +## 当前公开方法 + +| 方法 | 说明 | +|------|------| +| [Shutdown](Shutdown.md) | 统一关闭内部三个 pass renderer。 | +| [BuildRenderPlan](BuildRenderPlan.md) | 用内部 renderer 生成一份 Scene View render plan build result。 | + +## 当前语义 + +- 这个类不直接执行渲染；它只返回 [SceneViewportRenderPlanBuildResult](../SceneViewportRenderPlan/SceneViewportRenderPlanBuildResult.md)。 +- 它也不负责把 render plan 回写进 request 或处理失败回退；这些仍由 `ViewportHostService` 和 `ViewportHostRenderFlowUtils` 负责。 +- 当前测试直接覆盖了它的主路径，因此它已经是 Scene View pass 规划链路中的稳定入口。 + +## 调用位置 + +当前 `ViewportHostService` 持有成员： + +```cpp +SceneViewportRenderPassBundle m_sceneViewportRenderPassBundle; +``` + +也就是说，它已经承担了 Scene View 附加 pass renderer 的宿主职责。 + +## 测试覆盖 + +`tests/Editor/test_scene_viewport_render_pass_bundle.cpp` 当前验证了： + +- object-id SRV 可用时会创建 grid、selection outline 和 overlay 三类 pass。 +- object-id SRV 不可用时会返回 warning，并跳过 selection outline pass。 + +## 相关文档 + +- [SceneViewportRenderPlan](../SceneViewportRenderPlan/SceneViewportRenderPlan.md) +- [BuildSceneViewportRenderPlan](../SceneViewportRenderPlan/BuildSceneViewportRenderPlan.md) +- [ViewportHostRenderFlowUtils](../ViewportHostRenderFlowUtils/ViewportHostRenderFlowUtils.md) +- [SceneViewportGridPass](../Passes/SceneViewportGridPass/SceneViewportGridPass.md) +- [SceneViewportSelectionOutlinePass](../Passes/SceneViewportSelectionOutlinePass/SceneViewportSelectionOutlinePass.md) +- [SceneViewportEditorOverlayPass](../Passes/SceneViewportEditorOverlayPass/SceneViewportEditorOverlayPass.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportRenderPassBundle/Shutdown.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportRenderPassBundle/Shutdown.md new file mode 100644 index 00000000..8122464b --- /dev/null +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportRenderPassBundle/Shutdown.md @@ -0,0 +1,43 @@ +# SceneViewportRenderPassBundle::Shutdown + +**命名空间**: `XCEngine::Editor` + +**类型**: `method` + +**源文件**: `editor/src/Viewport/SceneViewportRenderPassBundle.h` + +## 签名 + +```cpp +void Shutdown(); +``` + +## 作用 + +关闭 `SceneViewportRenderPassBundle` 内部持有的三个 Scene View pass renderer。 + +## 当前行为 + +当前实现按下面顺序调用： + +1. `m_overlayRenderer.Shutdown()` +2. `m_selectionOutlineRenderer.Shutdown()` +3. `m_gridRenderer.Shutdown()` + +## 当前语义 + +- 这个方法只负责 bundle 内部 renderer 的资源释放。 +- 它不会重建 render plan，也不会触发任何新的 Scene View 渲染。 +- 因为 renderer 的所有权已经集中在 bundle 内，所以 shutdown 逻辑也由 bundle 统一收口，而不是重新分散回上层 service。 + +## 调用位置 + +当前 `ViewportHostService` 把 Scene View 附加 pass renderer 的生命周期托管给 bundle，因此这里是这层资源回收的自然入口。 + +## 相关文档 + +- [SceneViewportRenderPassBundle](SceneViewportRenderPassBundle.md) +- [BuildRenderPlan](BuildRenderPlan.md) +- [SceneViewportGridPass](../Passes/SceneViewportGridPass/SceneViewportGridPass.md) +- [SceneViewportSelectionOutlinePass](../Passes/SceneViewportSelectionOutlinePass/SceneViewportSelectionOutlinePass.md) +- [SceneViewportEditorOverlayPass](../Passes/SceneViewportEditorOverlayPass/SceneViewportEditorOverlayPass.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportRenderPlan/BuildSceneViewportRenderPlan.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportRenderPlan/BuildSceneViewportRenderPlan.md index ee566078..1ce82a6e 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportRenderPlan/BuildSceneViewportRenderPlan.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportRenderPlan/BuildSceneViewportRenderPlan.md @@ -24,6 +24,8 @@ SceneViewportRenderPlanBuildResult BuildSceneViewportRenderPlan( 根据当前 Scene View 的相机 overlay 状态、选中对象、render target 可用性以及当前帧 editor overlay 数据，构建一份可直接应用到 `CameraRenderRequest` 的 render plan。 +当前源码里，这个 free function 的直接调用者已经不是 `ViewportHostService` 本体，而是 [SceneViewportRenderPassBundle::BuildRenderPlan](../SceneViewportRenderPassBundle/BuildRenderPlan.md)。bundle 负责补上三类 pass renderer 的 factory，再把规划逻辑委托给这里。 + ## 输入分别承担什么职责 | 参数 | 作用 | @@ -127,6 +129,7 @@ SceneViewportRenderPlanBuildResult BuildSceneViewportRenderPlan( ## 相关文档 - [SceneViewportRenderPlan](SceneViewportRenderPlan.md) +- [SceneViewportRenderPassBundle](../SceneViewportRenderPassBundle/SceneViewportRenderPassBundle.md) - [SceneViewportRenderPlanBuildResult](SceneViewportRenderPlanBuildResult.md) - [SceneViewportGridPassFactory](SceneViewportGridPassFactory.md) - [SceneViewportSelectionOutlinePassFactory](SceneViewportSelectionOutlinePassFactory.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportRenderPlan/SceneViewportGridPassFactory.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportRenderPlan/SceneViewportGridPassFactory.md index 299dc663..f80dde1f 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportRenderPlan/SceneViewportGridPassFactory.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportRenderPlan/SceneViewportGridPassFactory.md @@ -10,7 +10,7 @@ ```cpp using SceneViewportGridPassFactory = - std::function(const Rendering::Passes::InfiniteGridPassData&)>; + std::function(const SceneViewportGridPassData&)>; ``` ## 作用 @@ -19,17 +19,17 @@ using SceneViewportGridPassFactory = ## 当前语义 -- 输入是一份已由 [BuildSceneViewportGridPassData](../ViewportHostRenderFlowUtils/BuildSceneViewportGridPassData.md) 组装好的 `InfiniteGridPassData` +- 输入是一份已由 [BuildSceneViewportGridPassData](../ViewportHostRenderFlowUtils/BuildSceneViewportGridPassData.md) 组装好的 `SceneViewportGridPassData` - 输出是要追加到 `SceneViewportRenderPlan::postScenePasses` 的 `RenderPass` - 返回 `nullptr` 时，本帧不会追加 grid pass ## 真实使用位置 -`ViewportHostService::BuildSceneViewportRenderState(...)` 会把它绑定到： +当前源码里，[SceneViewportRenderPassBundle::BuildRenderPlan](../SceneViewportRenderPassBundle/BuildRenderPlan.md) 会把它绑定到： -- `CreateSceneViewportGridPass(m_sceneViewportGridRenderer, data)` +- `CreateSceneViewportGridPass(m_gridRenderer, data)` -而 [BuildSceneViewportRenderPlan](BuildSceneViewportRenderPlan.md) 只负责决定是否调用它，并在返回非空时把 pass 收进 plan。 +而 [BuildSceneViewportRenderPlan](BuildSceneViewportRenderPlan.md) 只负责决定是否调用它，并在返回非空时把 pass 收进 plan；`ViewportHostService` 则通过 bundle 间接参与这一层。 ## 设计说明 @@ -38,6 +38,8 @@ using SceneViewportGridPassFactory = ## 相关文档 - [SceneViewportRenderPlan](SceneViewportRenderPlan.md) +- [SceneViewportRenderPassBundle](../SceneViewportRenderPassBundle/SceneViewportRenderPassBundle.md) - [BuildSceneViewportRenderPlan](BuildSceneViewportRenderPlan.md) - [BuildSceneViewportGridPassData](../ViewportHostRenderFlowUtils/BuildSceneViewportGridPassData.md) +- [SceneViewportGridPassData](../SceneViewportPassSpecs/SceneViewportGridPassData.md) - [SceneViewportGridPass](../Passes/SceneViewportGridPass/SceneViewportGridPass.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportRenderPlan/SceneViewportRenderPlan.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportRenderPlan/SceneViewportRenderPlan.md index 92e6384e..aaf2c8df 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportRenderPlan/SceneViewportRenderPlan.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportRenderPlan/SceneViewportRenderPlan.md @@ -24,15 +24,16 @@ 这类逻辑如果直接写死在 `ViewportHostService::RenderSceneViewportEntry(...)` 里，会让 service 变成“又要懂主流程，又要懂每种 pass 细节”的大杂糅。当前拆成 render plan 之后，调用链会更清晰： 1. `ViewportHostService` 负责总调度 -2. `SceneViewportRenderPlan` 负责“本帧额外挂什么” -3. [ViewportHostRenderFlowUtils](../ViewportHostRenderFlowUtils/ViewportHostRenderFlowUtils.md) 负责失败回退、基础 request 接线和成功收尾 +2. [SceneViewportRenderPassBundle](../SceneViewportRenderPassBundle/SceneViewportRenderPassBundle.md) 负责持有 pass renderer 生命周期，并把它们适配成 render-plan factory +3. `SceneViewportRenderPlan` 负责“本帧额外挂什么” +4. [ViewportHostRenderFlowUtils](../ViewportHostRenderFlowUtils/ViewportHostRenderFlowUtils.md) 负责失败回退、基础 request 接线和成功收尾 ## 公开类型与函数 | 成员 | 说明 | |------|------| -| [SceneViewportGridPassFactory](SceneViewportGridPassFactory.md) | 根据 `InfiniteGridPassData` 生成 grid `RenderPass` 的工厂回调。 | -| [SceneViewportSelectionOutlinePassFactory](SceneViewportSelectionOutlinePassFactory.md) | 根据 object-id SRV、选中对象和样式生成 selection outline `RenderPass` 的工厂回调。 | +| [SceneViewportGridPassFactory](SceneViewportGridPassFactory.md) | 根据 `SceneViewportGridPassData` 生成 grid `RenderPass` 的工厂回调。 | +| [SceneViewportSelectionOutlinePassFactory](SceneViewportSelectionOutlinePassFactory.md) | 根据 object-id SRV、选中对象和 `SceneViewportSelectionOutlineStyle` 生成 selection outline `RenderPass` 的工厂回调。 | | [SceneViewportOverlayPassFactory](SceneViewportOverlayPassFactory.md) | 根据合成后的 overlay frame data 生成 editor overlay `RenderPass` 的工厂回调。 | | [SceneViewportRenderPlanBuildResult](SceneViewportRenderPlanBuildResult.md) | 返回 render plan 与可选 warning 文案。 | | [HasPostScenePasses](HasPostScenePasses.md) | 判断当前计划是否包含 post-scene pass。 | @@ -73,14 +74,15 @@ 在 `ViewportHostService::RenderSceneViewportEntry(...)` 中，当前真实顺序大致是： 1. `BuildSceneViewportRenderState(...)` -2. `BuildSceneViewportRenderPlan(...)` -3. 若 `warningStatusText != nullptr`，用 `SetViewportStatusIfEmpty(...)` 尝试保留 warning -4. `SceneRenderer::BuildRenderRequests(...)` -5. `ApplySceneViewportRenderPlan(...)` -6. `SceneRenderer::Render(requests)` -7. 成功后 `MarkSceneViewportRenderSuccess(...)` +2. `m_sceneViewportRenderPassBundle.BuildRenderPlan(...)` +3. bundle 内部调用 `BuildSceneViewportRenderPlan(...)` +4. 若 `warningStatusText != nullptr`，用 `SetViewportStatusIfEmpty(...)` 尝试保留 warning +5. `SceneRenderer::BuildRenderRequests(...)` +6. `ApplySceneViewportRenderPlan(...)` +7. `SceneRenderer::Render(requests)` +8. 成功后 `MarkSceneViewportRenderSuccess(...)` -这条链很重要，因为它说明 render plan 既不是最上层入口，也不是最终执行器，而是 Scene View 专属附加内容的中间规划层。 +这条链很重要，因为它说明 render plan 既不是最上层入口，也不是最终执行器，而是 `ViewportHostService -> SceneViewportRenderPassBundle -> SceneViewportRenderPlan` 这条 Scene View 附加渲染链里的规划核心。 ## 为什么只有 Scene View 需要它 @@ -123,6 +125,7 @@ Scene View 则完全不同： - [Viewport](../Viewport.md) - [ViewportHostService](../ViewportHostService/ViewportHostService.md) +- [SceneViewportRenderPassBundle](../SceneViewportRenderPassBundle/SceneViewportRenderPassBundle.md) - [ViewportHostRenderFlowUtils](../ViewportHostRenderFlowUtils/ViewportHostRenderFlowUtils.md) - [ApplySceneViewportRenderRequestSetup](../ViewportHostRenderFlowUtils/ApplySceneViewportRenderRequestSetup.md) - [BuildSceneViewportGridPassData](../ViewportHostRenderFlowUtils/BuildSceneViewportGridPassData.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportRenderPlan/SceneViewportSelectionOutlinePassFactory.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportRenderPlan/SceneViewportSelectionOutlinePassFactory.md index 1346d6b8..665e7ac8 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportRenderPlan/SceneViewportSelectionOutlinePassFactory.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportRenderPlan/SceneViewportSelectionOutlinePassFactory.md @@ -12,7 +12,7 @@ using SceneViewportSelectionOutlinePassFactory = std::function( RHI::RHIResourceView*, const std::vector&, - const Rendering::Passes::ObjectIdOutlineStyle&)>; + const SceneViewportSelectionOutlineStyle&)>; ``` ## 作用 @@ -54,5 +54,5 @@ selection outline 是典型的“编辑器强需求，但依赖额外 GPU 资源 - [SceneViewportRenderPlan](SceneViewportRenderPlan.md) - [BuildSceneViewportRenderPlan](BuildSceneViewportRenderPlan.md) - [BuildSceneViewportSelectionOutlineStyle](../ViewportHostRenderFlowUtils/BuildSceneViewportSelectionOutlineStyle.md) -- [ObjectIdOutlineStyle](../../../Rendering/Passes/ObjectIdOutlineStyle/ObjectIdOutlineStyle.md) +- [SceneViewportSelectionOutlineStyle](../SceneViewportPassSpecs/SceneViewportSelectionOutlineStyle.md) - [SceneViewportSelectionOutlinePass](../Passes/SceneViewportSelectionOutlinePass/SceneViewportSelectionOutlinePass.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/BuildSceneViewportEditorResourcePath.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/BuildSceneViewportEditorResourcePath.md index 57ff7f11..0be9d2a8 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/BuildSceneViewportEditorResourcePath.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/BuildSceneViewportEditorResourcePath.md @@ -1,31 +1,49 @@ # Detail::BuildSceneViewportEditorResourcePath -把 editor 资源相对路径拼成 repo 内绝对资源路径。 +**命名空间**: `XCEngine::Editor::Detail` + +**类型**: `function` + +**源文件**: `editor/src/Viewport/SceneViewportResourcePaths.h` + +## 签名 ```cpp -inline Containers::String BuildSceneViewportEditorResourcePath(const std::filesystem::path& relativePath); +Containers::String BuildSceneViewportEditorResourcePath(const std::filesystem::path& relativePath); ``` -## 参数 +## 作用 -- `relativePath` - `editor/resources/` 下的相对路径。 +把一个相对于 `editor/resources/` 的路径，拼成 Scene View 编辑器资源的绝对路径字符串。 -## 当前语义 +## 当前实现行为 -- 当前实现会拼接： +当前实现会拼接： ```text {repo root}/editor/resources/{relativePath} ``` -- 然后再调用 [NormalizeSceneViewportResourcePath](NormalizeSceneViewportResourcePath.md) 输出规范化结果。 +随后再调用 [NormalizeSceneViewportResourcePath](NormalizeSceneViewportResourcePath.md) 输出规范化结果。 -## 返回值 +## 为什么它是中心 helper -- 规范化后的绝对资源路径字符串。 +本头文件里所有公开的 shader/icon 路径入口，最终都依赖这个函数。 + +这意味着： + +- repo root 逻辑只写一遍 +- 规范化逻辑只写一遍 +- 各个资源 helper 只需要关心自己的相对路径常量 + +## 设计说明 + +这种“先确定根，再挂相对路径”的组织方式，比让每个 helper 都复制一整段路径拼接代码更稳，也更接近商业引擎里编辑器内建资源表的写法。 ## 相关文档 - [SceneViewportResourcePaths](SceneViewportResourcePaths.md) - [GetSceneViewportResourceRepoRootPath](GetSceneViewportResourceRepoRootPath.md) - [NormalizeSceneViewportResourcePath](NormalizeSceneViewportResourcePath.md) +- [GetSceneViewportInfiniteGridShaderPath](GetSceneViewportInfiniteGridShaderPath.md) +- [GetSceneViewportObjectIdOutlineShaderPath](GetSceneViewportObjectIdOutlineShaderPath.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/GetSceneViewportCameraGizmoIconPath.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/GetSceneViewportCameraGizmoIconPath.md index e491607e..59ed60c3 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/GetSceneViewportCameraGizmoIconPath.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/GetSceneViewportCameraGizmoIconPath.md @@ -1,21 +1,53 @@ # GetSceneViewportCameraGizmoIconPath -返回 Scene View camera gizmo icon 的资源路径。 +**命名空间**: `XCEngine::Editor` + +**类型**: `function` + +**源文件**: `editor/src/Viewport/SceneViewportResourcePaths.h` + +## 签名 ```cpp -inline Containers::String GetSceneViewportCameraGizmoIconPath(); +Containers::String GetSceneViewportCameraGizmoIconPath(); ``` -## 当前语义 +## 作用 -- 当前实现把 `Icons/camera_gizmo.png` 交给 [BuildSceneViewportEditorResourcePath](BuildSceneViewportEditorResourcePath.md)。 -- 返回值指向 repo 内 `editor/resources/Icons/camera_gizmo.png`。 +返回 Scene View camera gizmo icon 的绝对资源路径。 -## 测试覆盖 +## 当前实现行为 -- `tests/Editor/test_scene_viewport_shader_paths.cpp` 验证了这里返回的是绝对路径，且目标 icon 文件存在。 +当前实现把相对路径： + +```text +Icons/camera_gizmo.png +``` + +交给 [BuildSceneViewportEditorResourcePath](BuildSceneViewportEditorResourcePath.md)，最终定位到： + +```text +{repo root}/editor/resources/Icons/camera_gizmo.png +``` + +## 真实使用位置 + +`editor/src/Viewport/SceneViewportOverlaySpriteResources.h` 当前会使用这个路径，为相机 overlay sprite 资源填充 `resourcePath`。 + +## 测试锚点 + +`ResolvePathsUnderEditorResources` 验证了： + +- 返回值是绝对路径 +- 目标 icon 文件存在 +- 路径字符串位于 `editor/resources/Icons` + +## 设计说明 + +Scene View icon 虽然不是 shader，但同样属于 Editor 私有资源。把它们和 shader 路径放在同一组 helper 中，能让 overlay 系统和 pass 系统共享同一套资源定位规则。 ## 相关文档 - [SceneViewportResourcePaths](SceneViewportResourcePaths.md) - [BuildSceneViewportEditorResourcePath](BuildSceneViewportEditorResourcePath.md) +- [SceneViewportEditorOverlayData](../SceneViewportEditorOverlayData/SceneViewportEditorOverlayData.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/GetSceneViewportInfiniteGridShaderPath.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/GetSceneViewportInfiniteGridShaderPath.md index 979255e1..451089ff 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/GetSceneViewportInfiniteGridShaderPath.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/GetSceneViewportInfiniteGridShaderPath.md @@ -1,27 +1,53 @@ # GetSceneViewportInfiniteGridShaderPath -返回 Scene View infinite-grid shader 的资源路径。 +**命名空间**: `XCEngine::Editor` + +**类型**: `function` + +**源文件**: `editor/src/Viewport/SceneViewportResourcePaths.h` + +## 签名 ```cpp -inline Containers::String GetSceneViewportInfiniteGridShaderPath(); +Containers::String GetSceneViewportInfiniteGridShaderPath(); ``` -## 当前语义 +## 作用 -- 当前实现把相对路径： +返回 Scene View 无限网格 shader 的绝对资源路径。 + +## 当前实现行为 + +当前实现把相对路径： ```text shaders/scene-viewport/infinite-grid/infinite-grid.shader ``` -交给 [BuildSceneViewportEditorResourcePath](BuildSceneViewportEditorResourcePath.md)，最终得到 repo 内 `editor/resources/` 下的绝对路径。 +交给 [BuildSceneViewportEditorResourcePath](BuildSceneViewportEditorResourcePath.md)，最终定位到： -## 测试覆盖 +```text +{repo root}/editor/resources/shaders/scene-viewport/infinite-grid/infinite-grid.shader +``` -- `tests/Editor/test_scene_viewport_shader_paths.cpp` 验证了这里返回的是绝对路径、目标文件存在，并且 `ShaderLoader` 能成功加载该 shader。 +## 真实使用位置 + +`editor/src/Viewport/Passes/SceneViewportGridPass.cpp` 当前会用这个路径初始化底层 grid pass 使用的 shader。 + +## 测试锚点 + +- `ResolvePathsUnderEditorResources` + - 验证返回值是绝对路径，且文件存在 +- `ShaderLoaderLoadsSceneViewportInfiniteGridShader` + - 验证 `ShaderLoader` 能按该路径加载 shader，并找到 `InfiniteGrid` pass + +## 设计说明 + +把 infinite-grid shader 路径收敛成固定 helper，有助于保证 Scene View 网格功能不会被调用点自己的字符串拼接方式影响。这比在 pass 构造函数里写裸路径更可维护。 ## 相关文档 - [SceneViewportResourcePaths](SceneViewportResourcePaths.md) - [BuildSceneViewportEditorResourcePath](BuildSceneViewportEditorResourcePath.md) +- [SceneViewportGridPass](../Passes/SceneViewportGridPass/SceneViewportGridPass.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 index 56f21b24..c33a51cb 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/GetSceneViewportMainLightGizmoIconPath.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/GetSceneViewportMainLightGizmoIconPath.md @@ -1,21 +1,53 @@ # GetSceneViewportMainLightGizmoIconPath -返回 Scene View main-light gizmo icon 的资源路径。 +**命名空间**: `XCEngine::Editor` + +**类型**: `function` + +**源文件**: `editor/src/Viewport/SceneViewportResourcePaths.h` + +## 签名 ```cpp -inline Containers::String GetSceneViewportMainLightGizmoIconPath(); +Containers::String GetSceneViewportMainLightGizmoIconPath(); ``` -## 当前语义 +## 作用 -- 当前实现把 `Icons/main_light_gizmo.png` 交给 [BuildSceneViewportEditorResourcePath](BuildSceneViewportEditorResourcePath.md)。 -- 返回值指向 repo 内 `editor/resources/Icons/main_light_gizmo.png`。 +返回 Scene View 主灯光 gizmo icon 的绝对资源路径。 -## 测试覆盖 +## 当前实现行为 -- `tests/Editor/test_scene_viewport_shader_paths.cpp` 验证了这里返回的是绝对路径，且目标 icon 文件存在。 +当前实现把相对路径： + +```text +Icons/main_light_gizmo.png +``` + +交给 [BuildSceneViewportEditorResourcePath](BuildSceneViewportEditorResourcePath.md)，最终定位到： + +```text +{repo root}/editor/resources/Icons/main_light_gizmo.png +``` + +## 真实使用位置 + +`editor/src/Viewport/SceneViewportOverlaySpriteResources.h` 当前会使用这个路径，为主灯光 overlay sprite 资源填充 `resourcePath`。 + +## 测试锚点 + +`ResolvePathsUnderEditorResources` 验证了： + +- 返回值是绝对路径 +- 目标 icon 文件存在 +- 路径字符串位于 `editor/resources/Icons` + +## 设计说明 + +主灯光图标和相机图标一样，都属于 Scene View overlay 的基础视觉资源。用统一 helper 暴露这些路径，可以让 icon 资源与 shader 资源共享同一套 repo root 与路径规范化规则。 ## 相关文档 - [SceneViewportResourcePaths](SceneViewportResourcePaths.md) - [BuildSceneViewportEditorResourcePath](BuildSceneViewportEditorResourcePath.md) +- [SceneViewportEditorOverlayData](../SceneViewportEditorOverlayData/SceneViewportEditorOverlayData.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/GetSceneViewportObjectIdOutlineShaderPath.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/GetSceneViewportObjectIdOutlineShaderPath.md index bd5d3cc2..e163043c 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/GetSceneViewportObjectIdOutlineShaderPath.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/GetSceneViewportObjectIdOutlineShaderPath.md @@ -1,27 +1,53 @@ # GetSceneViewportObjectIdOutlineShaderPath -返回 Scene View object-id outline shader 的资源路径。 +**命名空间**: `XCEngine::Editor` + +**类型**: `function` + +**源文件**: `editor/src/Viewport/SceneViewportResourcePaths.h` + +## 签名 ```cpp -inline Containers::String GetSceneViewportObjectIdOutlineShaderPath(); +Containers::String GetSceneViewportObjectIdOutlineShaderPath(); ``` -## 当前语义 +## 作用 -- 当前实现把相对路径： +返回 Scene View object-id outline shader 的绝对资源路径。 + +## 当前实现行为 + +当前实现把相对路径： ```text shaders/scene-viewport/object-id-outline/object-id-outline.shader ``` -交给 [BuildSceneViewportEditorResourcePath](BuildSceneViewportEditorResourcePath.md)，最终得到 repo 内 `editor/resources/` 下的绝对路径。 +交给 [BuildSceneViewportEditorResourcePath](BuildSceneViewportEditorResourcePath.md)，最终定位到： -## 测试覆盖 +```text +{repo root}/editor/resources/shaders/scene-viewport/object-id-outline/object-id-outline.shader +``` -- `tests/Editor/test_scene_viewport_shader_paths.cpp` 验证了这里返回的路径存在，并且 `ResourceManager` 能按该路径加载 outline shader。 +## 真实使用位置 + +`editor/src/Viewport/Passes/SceneViewportSelectionOutlinePass.cpp` 当前会用这个路径初始化底层 outline shader。 + +## 测试锚点 + +- `ResolvePathsUnderEditorResources` + - 验证返回值是绝对路径，且文件存在 +- `ResourceManagerLoadsSceneViewportOutlineShaderByResolvedPath` + - 验证 `ResourceManager` 能直接按该路径加载 outline shader + +## 设计说明 + +选中轮廓是 Scene View 的关键编辑反馈之一。把它的 shader 路径固定成单一 helper，能避免 outline pass 与 editor 资源布局发生隐蔽耦合错误。 ## 相关文档 - [SceneViewportResourcePaths](SceneViewportResourcePaths.md) - [BuildSceneViewportEditorResourcePath](BuildSceneViewportEditorResourcePath.md) +- [SceneViewportSelectionOutlinePass](../Passes/SceneViewportSelectionOutlinePass/SceneViewportSelectionOutlinePass.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 index df739fea..a39a9b98 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/GetSceneViewportResourceRepoRootPath.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/GetSceneViewportResourceRepoRootPath.md @@ -1,25 +1,55 @@ # Detail::GetSceneViewportResourceRepoRootPath -返回当前 Scene View 资源路径拼接使用的 repo root。 +**命名空间**: `XCEngine::Editor::Detail` + +**类型**: `function` + +**源文件**: `editor/src/Viewport/SceneViewportResourcePaths.h` + +## 签名 ```cpp -inline std::filesystem::path GetSceneViewportResourceRepoRootPath(); +std::filesystem::path GetSceneViewportResourceRepoRootPath(); ``` -## 当前语义 +## 作用 -- 如果定义了编译宏 `XCENGINE_EDITOR_REPO_ROOT`，当前实现会直接把该宏值转换成 `std::filesystem::path`。 -- 否则会以当前头文件 `__FILE__` 为起点，连续 `parent_path()` 三次回退到 repo root。 +返回当前 Scene View 编辑器资源路径拼接所依赖的 repo root。 -## 设计含义 +## 当前实现行为 -- 这让编辑器既可以在已知 repo root 的构建环境下使用固定路径，也可以在本地源码树中按相对位置推导资源根目录。 +当前有两条分支： -## 返回值 +1. 如果定义了编译宏 `XCENGINE_EDITOR_REPO_ROOT` + - 直接把该宏值包装成 `std::filesystem::path` +2. 否则 + - 以当前头文件 `__FILE__` 为起点 + - 连续 `parent_path()` 三次回退 -- 推导出的 repo root 路径。 +也就是当前默认 fallback 会从： + +```text +editor/src/Viewport/SceneViewportResourcePaths.h +``` + +回退到 repo 根目录。 + +## 设计说明 + +这是一种很实用的编辑器部署策略： + +- 在明确知道 repo 根的构建环境里，用宏提供固定值 +- 在本地源码树或开发环境里，用相对布局自动推导 + +这样既不强迫所有环境都依赖同一工作目录，也不要求每个调用者自己传入根目录。 + +## 当前边界 + +- 它只负责路径根的推导，不校验该目录下是否真的存在 `editor/resources/`。 +- 真正的“资源文件是否存在”由测试和 loader 层负责验证。 ## 相关文档 - [SceneViewportResourcePaths](SceneViewportResourcePaths.md) - [BuildSceneViewportEditorResourcePath](BuildSceneViewportEditorResourcePath.md) +- [NormalizeSceneViewportResourcePath](NormalizeSceneViewportResourcePath.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/NormalizeSceneViewportResourcePath.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/NormalizeSceneViewportResourcePath.md index d65d220d..a271c716 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/NormalizeSceneViewportResourcePath.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/NormalizeSceneViewportResourcePath.md @@ -1,30 +1,49 @@ # Detail::NormalizeSceneViewportResourcePath -把 `std::filesystem::path` 规范化并转成 `Containers::String`。 +**命名空间**: `XCEngine::Editor::Detail` + +**类型**: `function` + +**源文件**: `editor/src/Viewport/SceneViewportResourcePaths.h` + +## 签名 ```cpp -inline Containers::String NormalizeSceneViewportResourcePath(const std::filesystem::path& path); +Containers::String NormalizeSceneViewportResourcePath(const std::filesystem::path& path); ``` -## 当前语义 +## 作用 -- 当前实现等价于： +把 `std::filesystem::path` 规范化为稳定的、使用 `/` 分隔的 `Containers::String`。 + +## 当前实现行为 + +当前实现等价于： ```cpp return Containers::String(path.lexically_normal().generic_string().c_str()); ``` -- 这意味着它会先做 `lexically_normal()`，再统一输出使用 `/` 分隔的 generic path 字符串。 +这意味着它会： -## 参数 +1. 先执行 `lexically_normal()` +2. 再执行 `generic_string()` +3. 最后转成 `Containers::String` -- `path` - 待规范化的文件系统路径。 +## 为什么这一步重要 -## 返回值 +Scene View 资源路径会被： -- 规范化后的 `Containers::String` 路径。 +- shader loader +- resource manager +- editor sprite/icon 资源系统 + +共同消费。如果不同调用点拿到的路径字符串分隔符风格不一致，调试和比较都会变得很麻烦。 + +这里统一做规范化，就是为了让上层看到的始终是稳定格式。 ## 相关文档 - [SceneViewportResourcePaths](SceneViewportResourcePaths.md) - [BuildSceneViewportEditorResourcePath](BuildSceneViewportEditorResourcePath.md) +- [GetSceneViewportResourceRepoRootPath](GetSceneViewportResourceRepoRootPath.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/SceneViewportResourcePaths.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/SceneViewportResourcePaths.md index f4cc1a7a..9b37b70c 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/SceneViewportResourcePaths.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportResourcePaths/SceneViewportResourcePaths.md @@ -6,44 +6,89 @@ **源文件**: `editor/src/Viewport/SceneViewportResourcePaths.h` -**描述**: 为 Scene View 相关 shader 与 icon 资源生成 repo 内绝对路径的 inline helper 头文件。 +**描述**: 统一解析 Scene View 所需 shader 与 icon 资源的 repo 内绝对路径，并把它们规范化为稳定的 `Containers::String`。 ## 概览 -`SceneViewportResourcePaths.h` 当前是 Scene View 资源路径解析的实际定义位置。 +`SceneViewportResourcePaths.h` 是 Scene View 资源定位的真实定义位置。 -它负责： +它做的事情很具体，但对编辑器可靠性很关键： -- 定位 editor repo root。 -- 把相对路径拼到 `editor/resources/` 下。 -- 规范化为 `Containers::String`。 -- 返回 infinite-grid shader、object-id outline shader、camera icon、main-light icon 的绝对路径。 +- 推导当前 editor 资源根目录 +- 统一把相对资源路径挂到 `editor/resources/` +- 规范化输出路径格式 +- 为 grid shader、object-id outline shader、camera icon、main-light icon 提供固定入口 -`SceneViewportShaderPaths.h` 当前只是包含这个头文件的轻量兼容层。 +当前 [SceneViewportShaderPaths](../SceneViewportShaderPaths/SceneViewportShaderPaths.md) 只是一个兼容层，真正的实现已经统一收口到这里。 + +## 为什么 Scene View 要有自己的资源路径 helper + +商业引擎编辑器通常都会把“编辑器私有资源”与“项目资源”分开管理。 + +Scene View 的无限网格、选中描边 shader、相机与灯光 gizmo icon 都属于编辑器私有资源，而不是用户项目里的 `Assets/` 内容。因此它们不应该靠面板或 pass 随手拼字符串，更不应该让每个调用点自己猜 repo 结构。 + +统一收口到这组 helper 后有几个直接好处： + +- 资源路径规则只有一个来源 +- 测试可以直接验证这些入口返回的路径是否真实可用 +- 更容易兼容不同构建环境下的 repo root 解析方式 ## 公开 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 路径。 | +| [NormalizeSceneViewportResourcePath](NormalizeSceneViewportResourcePath.md) | 规范化文件系统路径并转成 `Containers::String`。 | +| [GetSceneViewportResourceRepoRootPath](GetSceneViewportResourceRepoRootPath.md) | 推导当前 Scene View 资源路径使用的 repo root。 | +| [BuildSceneViewportEditorResourcePath](BuildSceneViewportEditorResourcePath.md) | 把相对路径拼到 `editor/resources/` 下并规范化输出。 | +| [GetSceneViewportInfiniteGridShaderPath](GetSceneViewportInfiniteGridShaderPath.md) | 返回 infinite-grid shader 的绝对路径。 | +| [GetSceneViewportObjectIdOutlineShaderPath](GetSceneViewportObjectIdOutlineShaderPath.md) | 返回 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 资源。 +按当前源码： + +- `Passes/SceneViewportGridPass.cpp` + - 使用 [GetSceneViewportInfiniteGridShaderPath](GetSceneViewportInfiniteGridShaderPath.md) +- `Passes/SceneViewportSelectionOutlinePass.cpp` + - 使用 [GetSceneViewportObjectIdOutlineShaderPath](GetSceneViewportObjectIdOutlineShaderPath.md) +- `editor/src/Viewport/SceneViewportOverlaySpriteResources.h` + - 使用 [GetSceneViewportCameraGizmoIconPath](GetSceneViewportCameraGizmoIconPath.md) + - 使用 [GetSceneViewportMainLightGizmoIconPath](GetSceneViewportMainLightGizmoIconPath.md) +- `SceneViewportShaderPaths.h` + - 当前只包含本头文件，作为旧命名兼容层 + +## 测试锚点 + +`tests/Editor/test_scene_viewport_shader_paths.cpp` 当前覆盖了三类关键行为： + +- `ResolvePathsUnderEditorResources` + - 验证这些 helper 返回的是绝对路径，且文件实际存在 +- `ShaderLoaderLoadsSceneViewportInfiniteGridShader` + - 验证 infinite-grid shader 能被 `ShaderLoader` 成功加载 +- `ResourceManagerLoadsSceneViewportOutlineShaderByResolvedPath` + - 验证 `ResourceManager` 能按解析后的 outline shader 路径直接加载资源 + +## 设计说明 + +### 为什么返回绝对路径而不是相对路径 + +因为 Scene View 这些资源不是项目资源，而是 editor 自带资源。它们的消费位置分散在 pass renderer、sprite 资源与 shader loader 之间，如果继续使用相对路径，调用方就必须假设当前工作目录和部署布局，这在编辑器里通常很脆弱。 + +### 为什么先做路径规范化 + +当前实现把路径统一输出为 `generic_string()`，也就是使用 `/` 分隔的规范化字符串。这能减少跨平台与工具链差异带来的路径比较、日志输出和 loader 解析问题。 + +## 当前边界 + +- 这里只有资源路径解析，不负责资源缓存或资源热更新。 +- 它也不负责检查 shader 或 icon 内容的语义是否正确，只保证定位规则稳定。 ## 相关文档 -- [NormalizeSceneViewportResourcePath](NormalizeSceneViewportResourcePath.md) -- [GetSceneViewportResourceRepoRootPath](GetSceneViewportResourceRepoRootPath.md) -- [BuildSceneViewportEditorResourcePath](BuildSceneViewportEditorResourcePath.md) -- [GetSceneViewportInfiniteGridShaderPath](GetSceneViewportInfiniteGridShaderPath.md) -- [GetSceneViewportObjectIdOutlineShaderPath](GetSceneViewportObjectIdOutlineShaderPath.md) -- [GetSceneViewportCameraGizmoIconPath](GetSceneViewportCameraGizmoIconPath.md) -- [GetSceneViewportMainLightGizmoIconPath](GetSceneViewportMainLightGizmoIconPath.md) +- [Viewport](../Viewport.md) - [SceneViewportShaderPaths](../SceneViewportShaderPaths/SceneViewportShaderPaths.md) +- [SceneViewportGridPass](../Passes/SceneViewportGridPass/SceneViewportGridPass.md) +- [SceneViewportSelectionOutlinePass](../Passes/SceneViewportSelectionOutlinePass/SceneViewportSelectionOutlinePass.md) +- [Scene View Render Plan And Failure Flow](../../../../_guides/Editor/Scene-Viewport-Render-Plan-And-Failure-Flow.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportRotateGizmo/EndDrag.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportRotateGizmo/EndDrag.md index 551cfed5..d088abcd 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportRotateGizmo/EndDrag.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportRotateGizmo/EndDrag.md @@ -18,10 +18,30 @@ void EndDrag(IUndoManager& undoManager); ## 当前实现行为 -- 若当前没有活动轴，直接返回。 +- 若当前没有 active axis，直接返回。 - 当 `undoManager` 仍持有 pending interactive change 时，会调用 `FinalizeInteractiveChange()` 提交本次旋转。 -- 随后清空活动轴、活动实体、拖拽平面、起始角、共享 pivot 标志和所有缓存对象姿态。 -- 会保留当前 hover 刷新逻辑，并通过 `RefreshHandleState()` 去掉 active 标记。 +- 随后清空： + - active axis + - active entity id + - screen-space / local-space / shared-pivot 标志 + - active world axis + - 起始环角与累计角度 + - 起始 pivot + - 拖拽对象、起始位置和起始旋转数组 +- 最后通过 `RefreshHandleState()` 去掉 active 样式。 + +## 当前语义 + +- 它不会清空 hover axis；释放后的 hover 会继续由后续 `Update(...)` 或外部命中注入决定。 +- 角度填充和其他拖拽反馈会在状态清空后随下一次 `BuildDrawData(...)` 一起消失。 + +## 测试关联 + +`tests/Editor/test_scene_viewport_rotate_gizmo.cpp` 当前通过多条 drag 路径验证了： + +- 旋转结果会被提交到对象 transform。 +- undo 历史可用。 +- 角度填充会在释放后消失。 ## 相关文档 diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportRotateGizmo/EvaluateHit.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportRotateGizmo/EvaluateHit.md index c4474544..44ed0e4c 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportRotateGizmo/EvaluateHit.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportRotateGizmo/EvaluateHit.md @@ -14,15 +14,28 @@ SceneViewportRotateGizmoHitResult EvaluateHit(const Math::Vector2& mousePosition ## 作用 -提供旋转环命中检测，并返回当前最近命中的轴。 +对旋转环做命中检测，并返回当前最近的命中轴。 ## 当前实现行为 -- 如果当前 draw data 不可见，直接返回空命中。 +- 当 draw data 不可见时直接返回空命中。 - 会遍历每个可见 handle 的所有离散线段。 - 对普通 `X / Y / Z` 环，只考虑 `frontFacing = true` 的可见线段。 - `View` 环不受前后向裁剪限制。 -- 使用固定像素阈值比较鼠标到线段的距离平方，并返回最近命中的轴。 +- 使用固定像素阈值比较鼠标到线段的距离平方，并保留最近命中轴。 + +## 当前语义 + +- rotate gizmo 的命中模型是“最近可见线段优先”，而不是按整圈或扇区做粗命中。 +- 因为普通世界轴环会过滤 back-facing segment，所以从相机背侧绕过去的半圈默认不能直接命中。 +- `View` 环是例外，它始终允许整圈参与命中。 + +## 测试关联 + +`tests/Editor/test_scene_viewport_rotate_gizmo.cpp` 当前通过可见 segment 采样验证了： + +- `X` 轴可见环可以被稳定 hover。 +- `View` 环同样可见且可命中。 ## 相关文档 diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportRotateGizmo/SceneViewportRotateGizmoHitResult.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportRotateGizmo/SceneViewportRotateGizmoHitResult.md index eb3d35cb..4bde3631 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportRotateGizmo/SceneViewportRotateGizmoHitResult.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportRotateGizmo/SceneViewportRotateGizmoHitResult.md @@ -6,23 +6,21 @@ **源文件**: `editor/src/Viewport/SceneViewportRotateGizmo.h` -## 作用 +## 字段 -表示一次旋转 gizmo hit-test 的结果。 +| 字段 | 类型 | 说明 | +|------|------|------| +| `axis` | `SceneViewportRotateGizmoAxis` | 命中的旋转环。 | +| `distanceSq` | `float` | 鼠标到最近命中线段的距离平方。 | -## 字段说明 +## 当前语义 -| 字段 | 说明 | -|------|------| -| `axis` | 命中的旋转环。 | -| `distanceSq` | 命中点到鼠标的平方距离。 | - -## 当前实现行为 - -- 内联 `HasHit()` 只要 `axis != SceneViewportRotateGizmoAxis::None` 就返回 `true`。 -- 当前命中结果统一按最近旋转环表达，不再区分单独的平面或中心 handle 类型。 +- `HasHit()` 只要 `axis != SceneViewportRotateGizmoAxis::None` 就返回 `true`。 +- 这个结果统一用“最近旋转环”表达，不再区分单独的平面或中心 handle 类型。 +- 当没有命中时，`distanceSq` 会保持默认的 `Math::FLOAT_MAX`。 ## 相关文档 - [SceneViewportRotateGizmo](SceneViewportRotateGizmo.md) - [SceneViewportRotateGizmoAxis](SceneViewportRotateGizmoAxis.md) +- [EvaluateHit](EvaluateHit.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportRotateGizmo/SetHoveredHandle.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportRotateGizmo/SetHoveredHandle.md index bf852ab5..a44bdd19 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportRotateGizmo/SetHoveredHandle.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportRotateGizmo/SetHoveredHandle.md @@ -20,7 +20,11 @@ void SetHoveredHandle(SceneViewportRotateGizmoAxis axis); - 仅在当前没有活动拖拽时生效。 - 直接写入 `m_hoveredAxis`，然后调用 `RefreshHandleState()` 同步显示状态。 -- 这个入口通常用于外层统一命中仲裁后，把结果灌回 gizmo，而不是依赖它自己内部 hit test。 + +## 当前语义 + +- 这个入口通常用于外层统一命中后，把结果灌回 gizmo，而不是完全依赖它自己的内部 hit-test。 +- active drag 期间禁止外部覆盖 hover，可避免拖拽中途被其他命中结果抢走高亮。 ## 相关文档 diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportScaleGizmo/CancelDrag.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportScaleGizmo/CancelDrag.md index dd06328d..ac9ea2a4 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportScaleGizmo/CancelDrag.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportScaleGizmo/CancelDrag.md @@ -19,8 +19,21 @@ void CancelDrag(IUndoManager* undoManager = nullptr); ## 当前实现行为 - 如果传入了 `undoManager` 且当前存在 pending interactive change，会调用 `CancelInteractiveChange()` 回滚本次事务。 -- 同样会清空活动状态。 -- 与 [EndDrag](EndDrag.md) 相比，还会额外把 `hoveredHandle` 一并清空。 +- 随后会清空： + - `hoveredHandle` + - `activeHandle` + - active entity id + - 起始局部缩放 + - 当前视觉缩放反馈 + - 起始鼠标位置 + - 活动屏幕方向 +- 最后调用 `RefreshHandleState()` 清掉视觉状态。 + +## 与 `EndDrag` 的区别 + +- `EndDrag(...)` 会提交 interactive change。 +- `CancelDrag(...)` 会在可用时回滚 interactive change。 +- 并且 `CancelDrag(...)` 会额外把 hover 一并清空。 ## 相关文档 diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportScaleGizmo/EndDrag.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportScaleGizmo/EndDrag.md index f4728992..d4380a19 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportScaleGizmo/EndDrag.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportScaleGizmo/EndDrag.md @@ -20,7 +20,27 @@ void EndDrag(IUndoManager& undoManager); - 当前没有活动 handle 时直接返回。 - 如果 `undoManager` 仍有 pending interactive change，会调用 `FinalizeInteractiveChange()` 提交缩放结果。 -- 随后清空活动 handle、活动实体 id、起始局部缩放、起始鼠标位置、屏幕方向和视觉缩放缓存。 +- 随后清空： + - active handle + - active entity id + - 起始局部缩放 + - 当前视觉缩放反馈 + - 起始鼠标位置 + - 活动屏幕方向 +- 最后调用 `RefreshHandleState()` 去掉 active 样式。 + +## 当前语义 + +- 它不会清空 hover handle；释放后的 hover 会继续由下一次 `Update(...)` 或外部注入结果决定。 +- 视觉拉伸反馈 `m_dragCurrentVisualScale` 会在这里重置，因此轴长度或中心缩放反馈会在释放后恢复正常。 + +## 测试关联 + +`tests/Editor/test_scene_viewport_scale_gizmo.cpp` 当前通过完整 drag 路径验证了： + +- 轴向缩放只改变目标本地轴向。 +- 视觉拉伸反馈会在释放后回到正常长度。 +- 均匀缩放会生成可撤销步骤。 ## 相关文档 diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportScaleGizmo/SceneViewportScaleGizmoHitResult.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportScaleGizmo/SceneViewportScaleGizmoHitResult.md index 9f86e40a..bb906c1a 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportScaleGizmo/SceneViewportScaleGizmoHitResult.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportScaleGizmo/SceneViewportScaleGizmoHitResult.md @@ -6,23 +6,21 @@ **源文件**: `editor/src/Viewport/SceneViewportScaleGizmo.h` -## 作用 +## 字段 -表示一次缩放 gizmo hit-test 的结果。 +| 字段 | 类型 | 说明 | +|------|------|------| +| `handle` | `SceneViewportScaleGizmoHandle` | 命中的缩放 handle。 | +| `distanceSq` | `float` | 命中点到鼠标的距离平方。 | -## 字段说明 +## 当前语义 -| 字段 | 说明 | -|------|------| -| `handle` | 命中的缩放 handle。 | -| `distanceSq` | 命中点到鼠标的平方距离。 | - -## 当前实现行为 - -- 内联 `HasHit()` 只要 `handle != None` 就返回 `true`。 -- 当前命中模型不区分轴向和平面，而是统一收敛到单个 `SceneViewportScaleGizmoHandle`。 +- `HasHit()` 只要 `handle != SceneViewportScaleGizmoHandle::None` 就返回 `true`。 +- scale gizmo 的命中模型不区分轴线段和中心方块这两种来源；最终都统一折叠到单个 `SceneViewportScaleGizmoHandle`。 +- 当没有命中时，`distanceSq` 会保持默认的 `Math::FLOAT_MAX`。 ## 相关文档 - [SceneViewportScaleGizmo](SceneViewportScaleGizmo.md) - [SceneViewportScaleGizmoHandle](SceneViewportScaleGizmoHandle.md) +- [EvaluateHit](EvaluateHit.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportScaleGizmo/SetHoveredHandle.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportScaleGizmo/SetHoveredHandle.md index 0033239a..339da6c3 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportScaleGizmo/SetHoveredHandle.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportScaleGizmo/SetHoveredHandle.md @@ -21,6 +21,11 @@ void SetHoveredHandle(SceneViewportScaleGizmoHandle handle); - 当前存在活动 handle 时不会覆盖内部 hover 状态。 - 当前没有拖拽时，会直接写入 `m_hoveredHandle` 并刷新 draw data 状态。 +## 当前语义 + +- 这个入口与 move / rotate gizmo 的同类接口一致，主要用于让统一交互解析层把命中结果反灌回 gizmo。 +- active drag 期间禁止外部覆盖 hover，可避免拖拽中途失去当前 handle 的高亮。 + ## 相关文档 - [SceneViewportScaleGizmo](SceneViewportScaleGizmo.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportShaderPaths/BuildSceneViewportShaderPath.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportShaderPaths/BuildSceneViewportShaderPath.md index bd0dda63..c1b6d445 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportShaderPaths/BuildSceneViewportShaderPath.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportShaderPaths/BuildSceneViewportShaderPath.md @@ -1,31 +1,57 @@ # Detail::BuildSceneViewportShaderPath -当前已不是 `SceneViewportShaderPaths.h` 里的真实 helper；此页仅保留迁移说明。 +**命名空间**: `XCEngine::Editor::Detail` + +**类型**: `migration note` ## 当前状态 -- 现行 `editor/src/Viewport/SceneViewportShaderPaths.h` 不再声明 `BuildSceneViewportShaderPath(...)`。 -- 路径构建职责已经迁移到 [Detail::BuildSceneViewportEditorResourcePath](../SceneViewportResourcePaths/BuildSceneViewportEditorResourcePath.md)。 +这已经不是 `SceneViewportShaderPaths.h` 里的真实 helper；此页只保留迁移说明。 -## 迁移方式 +当前： -- 如果旧调用点想得到： +- `editor/src/Viewport/SceneViewportShaderPaths.h` 不再声明 `BuildSceneViewportShaderPath(...)` +- 真实路径拼接职责已经迁移到 [Detail::BuildSceneViewportEditorResourcePath](../SceneViewportResourcePaths/BuildSceneViewportEditorResourcePath.md) + +## 旧语义与新语义的关系 + +如果旧调用点原本想表达的是： ```text {repo root}/editor/resources/shaders/scene-viewport/{relativePath} ``` -- 当前应改为调用 `BuildSceneViewportEditorResourcePath()`，并传入完整相对路径： +当前更推荐的做法是： + +1. 直接调用 `BuildSceneViewportEditorResourcePath()` +2. 传入完整相对路径，例如： ```text shaders/scene-viewport/{relativePath} ``` -- 如果目标只是 infinite-grid 或 object-id outline shader，优先直接使用更高层的专用 getter。 +如果目标本来就是固定资源： + +- infinite-grid shader +- object-id outline shader + +那么最好直接使用更高层的专用 getter，而不是手工拼路径。 + +## 为什么不再保留旧 helper + +旧命名把“shader 路径”当作中心，但当前 Scene View 资源系统已经不仅包含 shader，还包含 icon 等其他 editor 资源。 + +因此继续保留 `BuildSceneViewportShaderPath(...)` 作为 canonical helper 会把语义限制得过窄，不利于后续统一资源定位规则。 + +## 迁移目标 + +- 旧 helper: `BuildSceneViewportShaderPath(...)` +- 新 canonical helper: [BuildSceneViewportEditorResourcePath](../SceneViewportResourcePaths/BuildSceneViewportEditorResourcePath.md) ## 相关文档 - [SceneViewportShaderPaths](SceneViewportShaderPaths.md) +- [SceneViewportResourcePaths](../SceneViewportResourcePaths/SceneViewportResourcePaths.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 5fd39116..a5e48c75 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportShaderPaths/GetSceneViewportInfiniteGridShaderPath.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportShaderPaths/GetSceneViewportInfiniteGridShaderPath.md @@ -1,18 +1,55 @@ # GetSceneViewportInfiniteGridShaderPath -通过兼容头 `SceneViewportShaderPaths.h` 可见的 Scene View infinite-grid shader 路径 helper。 +**命名空间**: `XCEngine::Editor` + +**类型**: `compatibility-visible function` + +## 签名 ```cpp inline Containers::String GetSceneViewportInfiniteGridShaderPath(); ``` +## 作用 + +通过兼容头 `SceneViewportShaderPaths.h` 暴露 Scene View infinite-grid shader 路径 helper。 + ## 当前语义 -- 当前函数的真实声明位于 [SceneViewportResourcePaths](../SceneViewportResourcePaths/SceneViewportResourcePaths.md)，`SceneViewportShaderPaths.h` 只是通过 `#include` 把它重新暴露给旧调用点。 -- 因此路径解析、规范化和测试覆盖，都应以资源路径头的文档为准。 +当前函数的真实声明与完整实现位于： + +- [SceneViewportResourcePaths](../SceneViewportResourcePaths/SceneViewportResourcePaths.md) +- [GetSceneViewportInfiniteGridShaderPath](../SceneViewportResourcePaths/GetSceneViewportInfiniteGridShaderPath.md) + +`SceneViewportShaderPaths.h` 只是通过 `#include` 让旧 include 路径继续可见。 + +因此： + +- 路径如何拼接 +- repo root 如何推导 +- 测试如何验证该路径 + +都应该以 `ResourcePaths` 模块文档为准。 + +## 当前调用点 + +当前至少有这些位置仍然通过兼容头间接使用该函数： + +- `editor/src/Viewport/Passes/SceneViewportGridPass.cpp` +- `tests/Editor/test_scene_viewport_shader_paths.cpp` + +## 设计说明 + +保留这个兼容可见入口的目的，不是鼓励新代码继续依赖 `ShaderPaths`，而是让旧 include surface 在重构期保持稳定。 + +新代码若要表达真实 owner，应优先直接包含： + +```cpp +#include "Viewport/SceneViewportResourcePaths.h" +``` ## 相关文档 - [SceneViewportShaderPaths](SceneViewportShaderPaths.md) -- [GetSceneViewportInfiniteGridShaderPath](../SceneViewportResourcePaths/GetSceneViewportInfiniteGridShaderPath.md) - [SceneViewportResourcePaths](../SceneViewportResourcePaths/SceneViewportResourcePaths.md) +- [GetSceneViewportInfiniteGridShaderPath](../SceneViewportResourcePaths/GetSceneViewportInfiniteGridShaderPath.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportShaderPaths/GetSceneViewportObjectIdOutlineShaderPath.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportShaderPaths/GetSceneViewportObjectIdOutlineShaderPath.md index 253711fc..e5856d82 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportShaderPaths/GetSceneViewportObjectIdOutlineShaderPath.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportShaderPaths/GetSceneViewportObjectIdOutlineShaderPath.md @@ -1,18 +1,46 @@ # GetSceneViewportObjectIdOutlineShaderPath -通过兼容头 `SceneViewportShaderPaths.h` 可见的 Scene View object-id outline shader 路径 helper。 +**命名空间**: `XCEngine::Editor` + +**类型**: `compatibility-visible function` + +## 签名 ```cpp inline Containers::String GetSceneViewportObjectIdOutlineShaderPath(); ``` +## 作用 + +通过兼容头 `SceneViewportShaderPaths.h` 暴露 Scene View object-id outline shader 路径 helper。 + ## 当前语义 -- 当前函数的真实声明位于 [SceneViewportResourcePaths](../SceneViewportResourcePaths/SceneViewportResourcePaths.md)，`SceneViewportShaderPaths.h` 只是通过 `#include` 把它重新暴露给旧调用点。 -- 因此路径解析、规范化和测试覆盖，都应以资源路径头的文档为准。 +当前函数的真实声明与完整实现位于： + +- [SceneViewportResourcePaths](../SceneViewportResourcePaths/SceneViewportResourcePaths.md) +- [GetSceneViewportObjectIdOutlineShaderPath](../SceneViewportResourcePaths/GetSceneViewportObjectIdOutlineShaderPath.md) + +`SceneViewportShaderPaths.h` 自己不再声明该函数，只是保持旧 include 路径兼容。 + +## 当前调用点 + +当前至少有这些位置仍然通过兼容头间接使用该函数： + +- `editor/src/Viewport/Passes/SceneViewportSelectionOutlinePass.cpp` +- `tests/Editor/test_scene_viewport_shader_paths.cpp` + +## 设计说明 + +对于这类兼容可见函数，最重要的是区分： + +- “我还能从旧头里看到它” +- “这个头仍然是它的真实 owner” + +当前只有前者成立。新文档与新代码都应把 `SceneViewportResourcePaths` 视为 canonical owner。 ## 相关文档 - [SceneViewportShaderPaths](SceneViewportShaderPaths.md) -- [GetSceneViewportObjectIdOutlineShaderPath](../SceneViewportResourcePaths/GetSceneViewportObjectIdOutlineShaderPath.md) - [SceneViewportResourcePaths](../SceneViewportResourcePaths/SceneViewportResourcePaths.md) +- [GetSceneViewportObjectIdOutlineShaderPath](../SceneViewportResourcePaths/GetSceneViewportObjectIdOutlineShaderPath.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportShaderPaths/GetSceneViewportShaderRepoRootPath.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportShaderPaths/GetSceneViewportShaderRepoRootPath.md index 7f51678e..73db2ce0 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportShaderPaths/GetSceneViewportShaderRepoRootPath.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportShaderPaths/GetSceneViewportShaderRepoRootPath.md @@ -1,20 +1,40 @@ # Detail::GetSceneViewportShaderRepoRootPath -当前已不是 `SceneViewportShaderPaths.h` 里的真实 helper；此页仅保留迁移说明。 +**命名空间**: `XCEngine::Editor::Detail` + +**类型**: `migration note` ## 当前状态 -- 现行 `editor/src/Viewport/SceneViewportShaderPaths.h` 不再声明 `GetSceneViewportShaderRepoRootPath()`。 -- repo root 推导逻辑已经迁移到 [Detail::GetSceneViewportResourceRepoRootPath](../SceneViewportResourcePaths/GetSceneViewportResourceRepoRootPath.md)。 +这已经不是 `SceneViewportShaderPaths.h` 里的真实 helper；此页只保留迁移说明。 -## 迁移方式 +当前： -- 旧调用点应改为使用 `GetSceneViewportResourceRepoRootPath()`。 -- 新 helper 仍保留原先的两条分支： - - 优先使用 `XCENGINE_EDITOR_REPO_ROOT` - - 否则基于 `__FILE__` 回退推导 repo root +- `editor/src/Viewport/SceneViewportShaderPaths.h` 不再声明 `GetSceneViewportShaderRepoRootPath()` +- repo root 推导逻辑已经迁移到 [Detail::GetSceneViewportResourceRepoRootPath](../SceneViewportResourcePaths/GetSceneViewportResourceRepoRootPath.md) + +## 为什么会迁移 + +旧名字强调“shader repo root”，但当前 Scene View 资源定位已经覆盖： + +- shader +- icon +- 其他 editor 私有资源 + +因此更准确的 canonical 概念是“resource repo root”。 + +## 迁移目标 + +- 旧 helper: `GetSceneViewportShaderRepoRootPath()` +- 新 canonical helper: [GetSceneViewportResourceRepoRootPath](../SceneViewportResourcePaths/GetSceneViewportResourceRepoRootPath.md) + +新 helper 仍保留原先两条核心分支： + +- 优先使用 `XCENGINE_EDITOR_REPO_ROOT` +- 否则基于 `__FILE__` 进行 fallback 推导 ## 相关文档 - [SceneViewportShaderPaths](SceneViewportShaderPaths.md) +- [SceneViewportResourcePaths](../SceneViewportResourcePaths/SceneViewportResourcePaths.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 72f1432d..519f3345 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportShaderPaths/NormalizeSceneViewportShaderPath.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportShaderPaths/NormalizeSceneViewportShaderPath.md @@ -1,18 +1,35 @@ # Detail::NormalizeSceneViewportShaderPath -当前已不是 `SceneViewportShaderPaths.h` 里的真实 helper；此页仅保留迁移说明。 +**命名空间**: `XCEngine::Editor::Detail` + +**类型**: `migration note` ## 当前状态 -- 现行 `editor/src/Viewport/SceneViewportShaderPaths.h` 不再声明 `NormalizeSceneViewportShaderPath(...)`。 -- 规范化逻辑已经迁移到 [Detail::NormalizeSceneViewportResourcePath](../SceneViewportResourcePaths/NormalizeSceneViewportResourcePath.md)。 +这已经不是 `SceneViewportShaderPaths.h` 里的真实 helper；此页只保留迁移说明。 -## 迁移方式 +当前： -- 旧调用点应改为使用 `NormalizeSceneViewportResourcePath()`。 -- 新 helper 仍然执行 `lexically_normal().generic_string()` 并返回 `Containers::String`，只是名字从 shader 专用改成了更通用的 resource 路径语义。 +- `editor/src/Viewport/SceneViewportShaderPaths.h` 不再声明 `NormalizeSceneViewportShaderPath(...)` +- 路径规范化逻辑已经迁移到 [Detail::NormalizeSceneViewportResourcePath](../SceneViewportResourcePaths/NormalizeSceneViewportResourcePath.md) + +## 旧语义与新语义 + +迁移后语义没有本质变化，仍然是： + +- 对路径做 `lexically_normal()` +- 输出 `/` 分隔的 `generic_string()` +- 返回 `Containers::String` + +变化点只在于命名更准确：它现在服务的不只是 shader path，而是 Scene View editor resource path。 + +## 迁移目标 + +- 旧 helper: `NormalizeSceneViewportShaderPath(...)` +- 新 canonical helper: [NormalizeSceneViewportResourcePath](../SceneViewportResourcePaths/NormalizeSceneViewportResourcePath.md) ## 相关文档 - [SceneViewportShaderPaths](SceneViewportShaderPaths.md) +- [SceneViewportResourcePaths](../SceneViewportResourcePaths/SceneViewportResourcePaths.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 4e6dcb62..5a500fbe 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportShaderPaths/SceneViewportShaderPaths.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportShaderPaths/SceneViewportShaderPaths.md @@ -6,39 +6,84 @@ **源文件**: `editor/src/Viewport/SceneViewportShaderPaths.h` -**描述**: 当前仅作为兼容层存在的 Scene View 资源路径头文件，头文件本体只包含 `SceneViewportResourcePaths.h`，不再自己定义 helper。 +**描述**: 作为兼容层保留的 Scene View shader-path include 入口；当前头文件本体只包含 `SceneViewportResourcePaths.h`，真实路径 helper 已迁移到资源路径模块。 ## 概览 -`SceneViewportShaderPaths.h` 现在的实现只有一行： +`SceneViewportShaderPaths.h` 当前实现只有一行： ```cpp #include "SceneViewportResourcePaths.h" ``` -这意味着： +这说明它的职责已经非常明确： -- 当前实际的路径 helper 定义位置已经迁移到 [SceneViewportResourcePaths](../SceneViewportResourcePaths/SceneViewportResourcePaths.md)。 -- 保留这个头文件主要是为了兼容仍然 `#include "Viewport/SceneViewportShaderPaths.h"` 的现有调用点。 -- 新代码若要理解真实声明和语义，应优先看 `SceneViewportResourcePaths.h` 对应的文档。 +- 不再自己声明任何路径 helper +- 只负责让旧 include 路径继续可用 +- 把真实实现统一收口到 [SceneViewportResourcePaths](../SceneViewportResourcePaths/SceneViewportResourcePaths.md) -## 当前可见能力 +这种设计在大型工程重构里非常常见，也很合理。因为“名字更准确”和“让旧调用点瞬间全部爆炸”不是一回事。当前保留这个薄兼容头，正是在做一次低风险迁移： -- 通过包含链，调用方仍可拿到： - - [GetSceneViewportInfiniteGridShaderPath](GetSceneViewportInfiniteGridShaderPath.md) - - [GetSceneViewportObjectIdOutlineShaderPath](GetSceneViewportObjectIdOutlineShaderPath.md) -- 但这两个 helper 的真实声明已经位于 [SceneViewportResourcePaths](../SceneViewportResourcePaths/SceneViewportResourcePaths.md)。 +- 旧代码还能继续编译 +- 新文档和新调用点可以统一指向更准确的 `ResourcePaths` + +## 为什么从 `ShaderPaths` 迁到 `ResourcePaths` + +旧命名里的 `ShaderPaths` 已经不能准确表达当前职责了，因为这组 helper 现在不仅定位 shader，还定位： + +- camera gizmo icon +- main-light gizmo icon + +所以新的 canonical 名称是 `SceneViewportResourcePaths`。这更符合真实语义，也更符合商业引擎里常见的“编辑器私有资源路径”命名方式。 + +## 当前仍依赖此兼容头的调用点 + +按当前源码与测试： + +- `editor/src/Viewport/Passes/SceneViewportGridPass.cpp` +- `editor/src/Viewport/Passes/SceneViewportSelectionOutlinePass.cpp` +- `tests/Editor/test_scene_viewport_shader_paths.cpp` + +这些位置仍然 `#include "Viewport/SceneViewportShaderPaths.h"`，但它们实际拿到的声明已经来自 `SceneViewportResourcePaths.h`。 + +## 当前通过兼容头可见的 helper + +虽然本头文件自己不声明 helper，但通过包含链，调用方仍能直接使用： + +- [GetSceneViewportInfiniteGridShaderPath](GetSceneViewportInfiniteGridShaderPath.md) +- [GetSceneViewportObjectIdOutlineShaderPath](GetSceneViewportObjectIdOutlineShaderPath.md) + +它们的真实定义与完整语义应以 [SceneViewportResourcePaths](../SceneViewportResourcePaths/SceneViewportResourcePaths.md) 为准。 ## 迁移说明 -下列旧页面保留为迁移说明，因为这些 helper 名已经不再是当前头文件里的真实声明： +以下旧命名页面只作为迁移说明保留，因为这些 helper 已不再是当前头文件里的真实声明： - [BuildSceneViewportShaderPath](BuildSceneViewportShaderPath.md) - [NormalizeSceneViewportShaderPath](NormalizeSceneViewportShaderPath.md) - [GetSceneViewportShaderRepoRootPath](GetSceneViewportShaderRepoRootPath.md) +它们现在对应的新 canonical helper 分别是： + +- `BuildSceneViewportEditorResourcePath(...)` +- `NormalizeSceneViewportResourcePath(...)` +- `GetSceneViewportResourceRepoRootPath()` + +## 设计说明 + +这种“保留薄兼容头，迁移真实 owner”的做法，比直接删除旧头更稳，原因很现实： + +- include 路径 churn 会波及很多文件 +- 文档、测试和源码可以分阶段迁移 +- 旧命名仍能明确指向新 canonical owner + +这是一种很典型的商业工程重构策略：先稳定 ABI / include surface，再慢慢收紧内部语义。 + ## 相关文档 - [SceneViewportResourcePaths](../SceneViewportResourcePaths/SceneViewportResourcePaths.md) - [GetSceneViewportInfiniteGridShaderPath](GetSceneViewportInfiniteGridShaderPath.md) - [GetSceneViewportObjectIdOutlineShaderPath](GetSceneViewportObjectIdOutlineShaderPath.md) +- [BuildSceneViewportShaderPath](BuildSceneViewportShaderPath.md) +- [NormalizeSceneViewportShaderPath](NormalizeSceneViewportShaderPath.md) +- [GetSceneViewportShaderRepoRootPath](GetSceneViewportShaderRepoRootPath.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/BuildBeginSceneViewportTransformGizmoLifecycleCommand.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/BuildBeginSceneViewportTransformGizmoLifecycleCommand.md index 4ba4b8b3..a6bced0e 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/BuildBeginSceneViewportTransformGizmoLifecycleCommand.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/BuildBeginSceneViewportTransformGizmoLifecycleCommand.md @@ -15,15 +15,24 @@ SceneViewportTransformGizmoLifecycleCommand BuildBeginSceneViewportTransformGizm ## 作用 -根据点击动作生成 gizmo 拖拽 begin 命令。 +根据交互动作生成 gizmo 拖拽的 `Begin` 生命周期命令。 -## 当前实现行为 +## 当前行为 -- 若 `actions.beginTransformGizmo == false`，返回空命令。 -- 否则返回： - - `stage = Begin` +- 当 `actions.beginTransformGizmo == false` 时，返回默认空命令。 +- 当 `actions.beginTransformGizmo == true` 时： + - `stage = SceneViewportTransformGizmoLifecycleStage::Begin` - `gizmoKind = actions.hoveredGizmoKind` +## 设计边界 + +- 它不检查 `hoveredGizmoKind` 是否为 `None`；如果调用方传入不一致的 `actions`，后续是否真正执行工作要由命令自身的 `HasWork()` 和执行阶段一起决定。 +- 它只负责 begin 边沿，不处理拖拽中的 update / end。 + +## 测试覆盖 + +`tests/Editor/test_scene_viewport_transform_gizmo_coordinator.cpp` 当前验证了 begin 命令会正确使用 `hoveredGizmoKind`。 + ## 相关文档 - [SceneViewportTransformGizmoLifecycleCommand](SceneViewportTransformGizmoLifecycleCommand.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/BuildFrameSceneViewportTransformGizmoLifecycleCommand.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/BuildFrameSceneViewportTransformGizmoLifecycleCommand.md index 3f05a104..147c9164 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/BuildFrameSceneViewportTransformGizmoLifecycleCommand.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/BuildFrameSceneViewportTransformGizmoLifecycleCommand.md @@ -16,21 +16,27 @@ SceneViewportTransformGizmoLifecycleCommand BuildFrameSceneViewportTransformGizm ## 作用 -根据当前 active gizmo 和鼠标按键状态生成本帧的 update / end 生命周期命令。 +根据当前 active gizmo 和左键状态，生成本帧的 `Update` 或 `End` 生命周期命令。 -## 当前实现行为 +## 当前行为 -- 若 `activeGizmoKind == None`，返回空命令。 +- `activeGizmoKind == SceneViewportActiveGizmoKind::None` 时返回空命令。 - 否则： - `leftMouseDown == true` 时生成 `Update` - `leftMouseDown == false` 时生成 `End` -- 返回命令中的 `gizmoKind` 直接取 `activeGizmoKind`。 +- 返回命令里的 `gizmoKind` 会直接取 `activeGizmoKind`。 + +## 设计说明 + +- 当前实现把“左键仍按下”视为拖拽继续，把“左键松开”视为拖拽结束。 +- 它不重新查询 gizmo 对象本身，也不处理 begin 边沿；begin 路径由 [BuildBeginSceneViewportTransformGizmoLifecycleCommand](BuildBeginSceneViewportTransformGizmoLifecycleCommand.md) 单独负责。 ## 测试覆盖 -`tests/Editor/test_scene_viewport_transform_gizmo_coordinator.cpp` 当前验证了 update / end 两种映射。 +`tests/Editor/test_scene_viewport_transform_gizmo_coordinator.cpp` 当前验证了 `Update` 与 `End` 两种映射。 ## 相关文档 - [SceneViewportTransformGizmoCoordinator](SceneViewportTransformGizmoCoordinator.md) - [SceneViewportTransformGizmoLifecycleCommand](SceneViewportTransformGizmoLifecycleCommand.md) +- [ExecuteSceneViewportTransformGizmoLifecycleCommand](ExecuteSceneViewportTransformGizmoLifecycleCommand.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/BuildSceneViewportTransformGizmoRefreshRequest.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/BuildSceneViewportTransformGizmoRefreshRequest.md index 811f5cbb..68b58757 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/BuildSceneViewportTransformGizmoRefreshRequest.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/BuildSceneViewportTransformGizmoRefreshRequest.md @@ -21,17 +21,23 @@ SceneViewportTransformGizmoRefreshRequest BuildSceneViewportTransformGizmoRefres 把当前帧 gizmo 刷新输入收口成 coordinator 可消费的 request。 -## 当前实现行为 +## 当前行为 - `context` 会以指针形式写入 `request.context`。 -- `overlay`、`viewportSize`、`mousePosition` 与 `options` 会被值拷贝到返回结构。 -- 该函数本身不做额外校验；请求是否有效由 `request.IsValid()` 判断。 +- `overlay`、`viewportSize`、`mousePosition` 和 `options` 都会以值拷贝方式写入返回结构。 +- 这个函数本身不做额外校验；请求是否有效由 `request.IsValid()` 判断。 + +## 设计边界 + +- 它不负责从 `SceneViewPanel`、`IViewportHostService` 或工具状态里拉取数据，只负责把已经准备好的输入打包。 +- 因为 `context` 存的是裸指针，所以返回值不适合脱离当前调用链长期保存。 ## 测试覆盖 -`tests/Editor/test_scene_viewport_transform_gizmo_coordinator.cpp` 当前验证了 context 指针、overlay、viewportSize、mousePosition 和 options 都会被正确拷贝。 +`tests/Editor/test_scene_viewport_transform_gizmo_coordinator.cpp` 当前验证了 `context` 指针、overlay、viewport 尺寸、鼠标位置和 options 都会被正确复制。 ## 相关文档 - [SceneViewportTransformGizmoRefreshRequest](SceneViewportTransformGizmoRefreshRequest.md) - [RefreshSceneViewportTransformGizmoFrame](RefreshSceneViewportTransformGizmoFrame.md) +- [BuildSceneViewportInteractionFrameState](../SceneViewportInteractionFrame/BuildSceneViewportInteractionFrameState.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/CancelSceneViewportTransformGizmoFrame.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/CancelSceneViewportTransformGizmoFrame.md index 28345d88..8971bf5f 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/CancelSceneViewportTransformGizmoFrame.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/CancelSceneViewportTransformGizmoFrame.md @@ -18,18 +18,21 @@ void CancelSceneViewportTransformGizmoFrame( ## 作用 -提供 coordinator 层的统一“取消当前 gizmo 拖拽”入口。 +提供 coordinator 层统一的“取消当前 gizmo 拖拽”入口。 -## 当前实现行为 +## 当前行为 -- 当前只是转调 [CancelSceneViewportTransformGizmoDrags](../SceneViewportTransformGizmoFrameBuilder/CancelSceneViewportTransformGizmoDrags.md)。 -- 不额外构建 frame state，也不生成 overlay submission。 +- 当前实现只是转调 [CancelSceneViewportTransformGizmoDrags](../SceneViewportTransformGizmoFrameBuilder/CancelSceneViewportTransformGizmoDrags.md)。 +- 它会把 `context` 和三个 gizmo 原样转发给底层取消逻辑。 +- 它不会额外构建 frame state，也不会生成或提交新的 overlay submission。 -## 测试覆盖 +## 调用位置 -`tests/Editor/test_scene_viewport_transform_gizmo_coordinator.cpp` 当前会调用该入口，验证 coordinator 层可统一触发取消流程。 +- `BuildSceneViewportInteractionFrameState(...)` 在 `hasInteractiveViewport == false` 时会调用这里，防止不可交互帧继续保留旧的 gizmo 拖拽状态。 +- 测试也会通过这层入口验证 coordinator 能统一触发取消路径。 ## 相关文档 - [SceneViewportTransformGizmoCoordinator](SceneViewportTransformGizmoCoordinator.md) - [CancelSceneViewportTransformGizmoDrags](../SceneViewportTransformGizmoFrameBuilder/CancelSceneViewportTransformGizmoDrags.md) +- [BuildSceneViewportInteractionFrameState](../SceneViewportInteractionFrame/BuildSceneViewportInteractionFrameState.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/RefreshSceneViewportTransformGizmoFrame.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/RefreshSceneViewportTransformGizmoFrame.md index 6dd209b2..4319e00f 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/RefreshSceneViewportTransformGizmoFrame.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/RefreshSceneViewportTransformGizmoFrame.md @@ -18,13 +18,18 @@ SceneViewportTransformGizmoFrameUpdate RefreshSceneViewportTransformGizmoFrame( ## 作用 -刷新一帧 transform gizmo，并同时生成可提交给宿主服务的 overlay submission。 +刷新一帧 transform gizmo，并同时生成可供后续提交给 viewport host service 的 overlay submission。 -## 当前实现行为 +## 当前行为 - 如果 `request.IsValid()` 为 `false`，当前直接返回默认构造的 `SceneViewportTransformGizmoFrameUpdate`。 -- 否则先调用 [RefreshSceneViewportTransformGizmos](../SceneViewportTransformGizmoFrameBuilder/RefreshSceneViewportTransformGizmos.md) 得到 `frameState`。 -- 然后调用 [BuildSceneViewportTransformGizmoOverlaySubmission](BuildSceneViewportTransformGizmoOverlaySubmission.md) 生成 `overlaySubmission`。 +- 否则会先调用 [RefreshSceneViewportTransformGizmos](../SceneViewportTransformGizmoFrameBuilder/RefreshSceneViewportTransformGizmos.md)，得到新的 `frameState`。 +- 然后再调用 [BuildSceneViewportTransformGizmoOverlaySubmission](BuildSceneViewportTransformGizmoOverlaySubmission.md)，基于 `frameState` 和三个 gizmo 当前状态生成 `overlaySubmission`。 + +## 边界说明 + +- 它会刷新 gizmo 自身状态，但不会把结果写回 `IViewportHostService`；提交步骤由 [RefreshAndSubmitSceneViewportTransformGizmoFrame](RefreshAndSubmitSceneViewportTransformGizmoFrame.md) 或 [SubmitSceneViewportTransformGizmoOverlaySubmission](SubmitSceneViewportTransformGizmoOverlaySubmission.md) 负责。 +- 这意味着调用方可以先拿到 `SceneViewportTransformGizmoFrameUpdate` 做进一步判断，再决定是否提交 overlay state。 ## 相关文档 diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoCoordinator.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoCoordinator.md index b94509f7..a99a2c9a 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoCoordinator.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoCoordinator.md @@ -6,49 +6,45 @@ **源文件**: `editor/src/Viewport/SceneViewportTransformGizmoCoordinator.h` -**描述**: 负责把 gizmo frame state 收口成可提交的 overlay state，并把 Scene View 中的 gizmo begin / update / end 推进收口成统一生命周期命令。 +**说明**: 把 Scene View 中 transform gizmo 的“每帧刷新、overlay 提交、begin/update/end 生命周期命令生成与分发”收口到同一个协作层。 ## 概览 -这层 helper 位于 `SceneViewPanel` 与 `ViewportHostService` / 各 gizmo 对象之间。 -它当前解决两件事： +这一层位于 `SceneViewPanel`、`IViewportHostService` 和三个具体 gizmo 对象之间，主要负责两类工作： -- overlay 提交：把本帧 gizmo 状态转成 `SceneViewportTransformGizmoOverlaySubmission` -- 生命周期推进：把 begin / update / end 统一成 `SceneViewportTransformGizmoLifecycleCommand` +1. 每帧根据 overlay、viewport 几何、选择状态和工具显示开关，刷新 move / rotate / scale gizmo，并把结果折叠成可提交的 overlay state。 +2. 把 interaction resolver 给出的“本帧开始拖拽”与“当前激活 gizmo 继续更新/结束”信号，翻译成统一的生命周期命令，再分发到具体 gizmo。 -## 公开类型与函数 +## 当前语义 -| 成员 | 说明 | -|------|------| -| [SceneViewportTransformGizmoFrameOptions](SceneViewportTransformGizmoFrameOptions.md) | 每帧 gizmo 刷新所需的布尔配置。 | -| [SceneViewportTransformGizmoRefreshRequest](SceneViewportTransformGizmoRefreshRequest.md) | 一次 gizmo frame 刷新的完整输入包。 | -| [SceneViewportTransformGizmoOverlaySubmission](SceneViewportTransformGizmoOverlaySubmission.md) | 提交给宿主服务的 overlay submission。 | -| [SceneViewportTransformGizmoLifecycleStage](SceneViewportTransformGizmoLifecycleStage.md) | gizmo 生命周期阶段枚举。 | -| [SceneViewportTransformGizmoLifecycleCommand](SceneViewportTransformGizmoLifecycleCommand.md) | begin / update / end 命令包。 | -| [SceneViewportTransformGizmoFrameUpdate](SceneViewportTransformGizmoFrameUpdate.md) | 一次 gizmo frame 刷新的完整输出。 | -| [BuildSceneViewportTransformGizmoFrameOptions](BuildSceneViewportTransformGizmoFrameOptions.md) | 构建每帧 gizmo 布尔配置。 | -| [BuildSceneViewportTransformGizmoRefreshRequest](BuildSceneViewportTransformGizmoRefreshRequest.md) | 构建 gizmo frame 刷新请求。 | -| [CancelSceneViewportTransformGizmoFrame](CancelSceneViewportTransformGizmoFrame.md) | 取消当前帧正在进行的 gizmo 拖拽。 | -| [RefreshSceneViewportTransformGizmoFrame](RefreshSceneViewportTransformGizmoFrame.md) | 刷新 gizmo frame 并生成 overlay submission。 | -| [RefreshAndSubmitSceneViewportTransformGizmoFrame](RefreshAndSubmitSceneViewportTransformGizmoFrame.md) | 刷新 gizmo frame 并直接提交到 viewport host service。 | -| [BuildSceneViewportTransformGizmoOverlaySubmission](BuildSceneViewportTransformGizmoOverlaySubmission.md) | 从 frame state 和 gizmo 对象生成 overlay submission。 | -| [SubmitSceneViewportTransformGizmoOverlaySubmission](SubmitSceneViewportTransformGizmoOverlaySubmission.md) | 把 overlay submission 写回 viewport host service。 | -| [BuildBeginSceneViewportTransformGizmoLifecycleCommand](BuildBeginSceneViewportTransformGizmoLifecycleCommand.md) | 根据交互 action 生成 begin 命令。 | -| [BuildFrameSceneViewportTransformGizmoLifecycleCommand](BuildFrameSceneViewportTransformGizmoLifecycleCommand.md) | 根据 active gizmo 和鼠标状态生成 update / end 命令。 | -| [ExecuteSceneViewportTransformGizmoLifecycleCommand](ExecuteSceneViewportTransformGizmoLifecycleCommand.md) | 把生命周期命令分发到 move / rotate / scale gizmo。 | +- [SceneViewportTransformGizmoFrameOptions](SceneViewportTransformGizmoFrameOptions.md) 和 [SceneViewportTransformGizmoRefreshRequest](SceneViewportTransformGizmoRefreshRequest.md) 都是纯值对象，不拥有外部资源。 +- `SceneViewportTransformGizmoRefreshRequest::IsValid()` 目前只检查 `context != nullptr`。 +- [RefreshSceneViewportTransformGizmoFrame](RefreshSceneViewportTransformGizmoFrame.md) 在请求无效时返回默认空 `SceneViewportTransformGizmoFrameUpdate`，不会尝试刷新 gizmo。 +- [RefreshAndSubmitSceneViewportTransformGizmoFrame](RefreshAndSubmitSceneViewportTransformGizmoFrame.md) 会先刷新，再把 `overlaySubmission.overlayState` 直接写回 `viewportHostService`。 +- [BuildSceneViewportTransformGizmoOverlaySubmission](BuildSceneViewportTransformGizmoOverlaySubmission.md) 的 `activeGizmoKind` 来自三个 gizmo 的当前活跃状态，不是单靠 frame-state 推导。 +- [CancelSceneViewportTransformGizmoFrame](CancelSceneViewportTransformGizmoFrame.md) 只负责取消三个 gizmo 的当前拖拽，不做额外刷新。 + +## 生命周期命令 + +- [BuildBeginSceneViewportTransformGizmoLifecycleCommand](BuildBeginSceneViewportTransformGizmoLifecycleCommand.md) 只有在 `actions.beginTransformGizmo == true` 时才产生 `Begin` 命令，目标 gizmo 取自 `actions.hoveredGizmoKind`。 +- [BuildFrameSceneViewportTransformGizmoLifecycleCommand](BuildFrameSceneViewportTransformGizmoLifecycleCommand.md) 只有在存在 active gizmo 时才返回命令： + - `leftMouseDown == true` 时产出 `Update` + - `leftMouseDown == false` 时产出 `End` +- [ExecuteSceneViewportTransformGizmoLifecycleCommand](ExecuteSceneViewportTransformGizmoLifecycleCommand.md) 会根据 `gizmoKind` 分发到 move / rotate / scale gizmo，并调用各自的 `TryBeginDrag`、`UpdateDrag` 或 `EndDrag`。 ## 测试覆盖 -`tests/Editor/test_scene_viewport_transform_gizmo_coordinator.cpp` 当前覆盖了： +`tests/Editor/test_scene_viewport_transform_gizmo_coordinator.cpp` 当前验证了： -- frame options / refresh request 构造 -- refresh + submit 包装调用 -- begin / update / end 命令生成 -- overlay submission 构造 -- overlay submission 提交到 `IViewportHostService` +- begin / update / end 生命周期命令的生成。 +- frame options 和 refresh request 的字段转发。 +- overlay submission 的构造与提交。 +- `RefreshAndSubmitSceneViewportTransformGizmoFrame(...)` 是否把 frame-state 和 overlay submission 一起跑通。 ## 相关文档 - [Viewport](../Viewport.md) +- [SceneViewportInteractionActions](../SceneViewportInteractionActions/SceneViewportInteractionActions.md) - [SceneViewportOverlayHandleBuilder](../SceneViewportOverlayHandleBuilder/SceneViewportOverlayHandleBuilder.md) +- [SceneViewportTransformGizmoFrameBuilder](../SceneViewportTransformGizmoFrameBuilder/SceneViewportTransformGizmoFrameBuilder.md) - [SceneViewPanel](../../panels/SceneViewPanel/SceneViewPanel.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoFrameOptions.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoFrameOptions.md index 938e2265..8801d4f8 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoFrameOptions.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoFrameOptions.md @@ -12,7 +12,7 @@ |------|------|------| | `useCenterPivot` | `bool` | 是否使用中心 pivot。 | | `localSpace` | `bool` | 是否使用局部坐标空间。 | -| `usingTransformTool` | `bool` | 是否处于联合 `Transform` 工具模式。 | +| `usingTransformTool` | `bool` | 是否处于聚合的 `Transform` 工具模式。 | | `showingMoveGizmo` | `bool` | 本帧是否显示 move gizmo。 | | `showingRotateGizmo` | `bool` | 本帧是否显示 rotate gizmo。 | | `showingScaleGizmo` | `bool` | 本帧是否显示 scale gizmo。 | @@ -20,8 +20,19 @@ ## 当前语义 - 这是传给 gizmo frame refresh 的轻量布尔配置。 -- 它把工具模式、pivot 模式和空间模式压平成 gizmo 刷新层真正消费的参数。 -- [BuildSceneViewportToolState](../SceneViewportInteractionFrame/BuildSceneViewportToolState.md) 当前会构建并下发这份配置。 +- 它把工具模式、pivot 模式和空间模式压平成 gizmo refresh 流程真正消费的参数。 +- `usingTransformTool` 与三个 `showing*Gizmo` 位不是同一概念： + - `usingTransformTool` 表示当前是否选择了聚合工具 + - `showing*Gizmo` 表示对应 gizmo 这一帧是否应该可见并参与刷新 + +## 来源 + +- 当前 [BuildSceneViewportToolState](../SceneViewportInteractionFrame/BuildSceneViewportToolState.md) 会先生成高层工具状态。 +- 然后 [BuildSceneViewportTransformGizmoFrameOptions](BuildSceneViewportTransformGizmoFrameOptions.md) 把这些高层布尔位折叠成这里的 options。 + +## 测试覆盖 + +`tests/Editor/test_scene_viewport_transform_gizmo_coordinator.cpp` 当前验证了各字段会被原样复制进返回对象。 ## 相关文档 diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoFrameUpdate.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoFrameUpdate.md index 1776b62e..af2bda88 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoFrameUpdate.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoFrameUpdate.md @@ -10,16 +10,28 @@ | 字段 | 类型 | 说明 | |------|------|------| -| `frameState` | `SceneViewportTransformGizmoFrameState` | 本帧 gizmo 刷新结果。 | -| `overlaySubmission` | `SceneViewportTransformGizmoOverlaySubmission` | 可继续提交给宿主服务的 overlay submission。 | +| `frameState` | `SceneViewportTransformGizmoFrameState` | 本帧 gizmo refresh 的原始输出。 | +| `overlaySubmission` | `SceneViewportTransformGizmoOverlaySubmission` | 基于本帧结果构造出的 overlay submission。 | ## 当前语义 -- 这是 `RefreshSceneViewportTransformGizmoFrame(...)` 与 `RefreshAndSubmitSceneViewportTransformGizmoFrame(...)` 的统一返回结构。 -- 它同时保留 frame builder 的原始输出和 overlay 提交层的收口结果。 +- 这是 [RefreshSceneViewportTransformGizmoFrame](RefreshSceneViewportTransformGizmoFrame.md) 和 [RefreshAndSubmitSceneViewportTransformGizmoFrame](RefreshAndSubmitSceneViewportTransformGizmoFrame.md) 的统一返回结构。 +- 它同时保留了两层结果： + - frame-builder 级别的 `frameState` + - host-service 提交级别的 `overlaySubmission` +- 调用方既可以消费 `frameState` 去推进 gizmo 生命周期，也可以直接拿 `overlaySubmission` 做 host overlay 提交或交互门禁。 + +## 调用位置 + +当前 `BuildSceneViewportInteractionFrameState(...)` 会从这里拆出： + +- `gizmoFrameState` +- `activeGizmoKind` +- `gizmoActive` ## 相关文档 - [RefreshSceneViewportTransformGizmoFrame](RefreshSceneViewportTransformGizmoFrame.md) - [RefreshAndSubmitSceneViewportTransformGizmoFrame](RefreshAndSubmitSceneViewportTransformGizmoFrame.md) - [SceneViewportTransformGizmoFrameState](../SceneViewportTransformGizmoFrameBuilder/SceneViewportTransformGizmoFrameState.md) +- [SceneViewportTransformGizmoOverlaySubmission](SceneViewportTransformGizmoOverlaySubmission.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoLifecycleCommand.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoLifecycleCommand.md index 52622767..81cc67be 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoLifecycleCommand.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoLifecycleCommand.md @@ -15,8 +15,14 @@ ## 当前语义 -- `HasWork()` 当前要求 `stage != None` 且 `gizmoKind != None`。 -- 这是一份轻量命令对象，真正的 begin / update / end 分发由 `ExecuteSceneViewportTransformGizmoLifecycleCommand(...)` 完成。 +- `HasWork()` 要求 `stage != None` 且 `gizmoKind != None`。 +- 这是一个轻量命令对象，只描述“做什么”，不携带 gizmo context。 +- 真正的上下文读取和 `TryBeginDrag / UpdateDrag / EndDrag` 分发由 [ExecuteSceneViewportTransformGizmoLifecycleCommand](ExecuteSceneViewportTransformGizmoLifecycleCommand.md) 完成；执行时会再从 `SceneViewportTransformGizmoFrameState` 里拿对应 gizmo 的 context。 + +## 来源 + +- [BuildBeginSceneViewportTransformGizmoLifecycleCommand](BuildBeginSceneViewportTransformGizmoLifecycleCommand.md) 负责产生 `Begin` 命令。 +- [BuildFrameSceneViewportTransformGizmoLifecycleCommand](BuildFrameSceneViewportTransformGizmoLifecycleCommand.md) 负责产生 `Update` 或 `End` 命令。 ## 相关文档 diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoLifecycleStage.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoLifecycleStage.md index 1ca49e03..8ecc40a4 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoLifecycleStage.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoLifecycleStage.md @@ -10,12 +10,20 @@ | 值 | 含义 | |------|------| -| `None` | 无工作。 | -| `Begin` | 开始拖拽。 | -| `Update` | 持续更新拖拽。 | -| `End` | 结束拖拽。 | +| `None` | 当前帧没有 gizmo 生命周期工作。 | +| `Begin` | 尝试开始一次 gizmo 拖拽。 | +| `Update` | 继续更新正在进行的 gizmo 拖拽。 | +| `End` | 结束当前 gizmo 拖拽。 | + +## 当前语义 + +- 这是 [SceneViewportTransformGizmoLifecycleCommand](SceneViewportTransformGizmoLifecycleCommand.md) 的阶段字段。 +- `Begin` 通常来自 [BuildBeginSceneViewportTransformGizmoLifecycleCommand](BuildBeginSceneViewportTransformGizmoLifecycleCommand.md)。 +- `Update / End` 通常来自 [BuildFrameSceneViewportTransformGizmoLifecycleCommand](BuildFrameSceneViewportTransformGizmoLifecycleCommand.md)。 +- 具体执行时，阶段会被 [ExecuteSceneViewportTransformGizmoLifecycleCommand](ExecuteSceneViewportTransformGizmoLifecycleCommand.md) 分发到对应 gizmo 的 `TryBeginDrag`、`UpdateDrag` 或 `EndDrag`。 ## 相关文档 - [SceneViewportTransformGizmoCoordinator](SceneViewportTransformGizmoCoordinator.md) - [SceneViewportTransformGizmoLifecycleCommand](SceneViewportTransformGizmoLifecycleCommand.md) +- [ExecuteSceneViewportTransformGizmoLifecycleCommand](ExecuteSceneViewportTransformGizmoLifecycleCommand.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoOverlaySubmission.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoOverlaySubmission.md index 5eae35a0..f226db06 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoOverlaySubmission.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoOverlaySubmission.md @@ -10,15 +10,24 @@ | 字段 | 类型 | 说明 | |------|------|------| -| `overlayState` | `SceneViewportTransformGizmoOverlayState` | 本帧 gizmo overlay state。 | -| `activeGizmoKind` | `SceneViewportActiveGizmoKind` | 当前 active gizmo 类型。 | +| `overlayState` | `SceneViewportTransformGizmoOverlayState` | 本帧要提交给 viewport host service 的 gizmo overlay state。 | +| `activeGizmoKind` | `SceneViewportActiveGizmoKind` | 当前处于 active 状态的 gizmo 类型。 | ## 当前语义 -- `GizmoActive()` 当前仅检查 `activeGizmoKind != None`。 -- 该结构把“本帧要提交给宿主服务的 overlay 数据”和“当前是否已有 gizmo 处于 active 状态”打包在一起。 +- `GizmoActive()` 只是 `activeGizmoKind != SceneViewportActiveGizmoKind::None` 的便捷判断。 +- 这个结构把两件事打包在一起： + - “本帧要渲染 / 命中的 gizmo overlay 数据” + - “当前是否已经有 gizmo 占用交互” +- `activeGizmoKind` 由 [BuildSceneViewportTransformGizmoOverlaySubmission](BuildSceneViewportTransformGizmoOverlaySubmission.md) 从三个 gizmo 的当前活跃状态推导出来，不是简单从 `overlayState` 反推。 + +## 调用位置 + +- `BuildSceneViewportInteractionFrameState(...)` 会用它填充 `activeGizmoKind` 和 `gizmoActive`。 +- `RefreshAndSubmitSceneViewportTransformGizmoFrame(...)` 会把其中的 `overlayState` 提交给 `IViewportHostService`。 ## 相关文档 - [SceneViewportTransformGizmoCoordinator](SceneViewportTransformGizmoCoordinator.md) - [BuildSceneViewportTransformGizmoOverlaySubmission](BuildSceneViewportTransformGizmoOverlaySubmission.md) +- [SubmitSceneViewportTransformGizmoOverlaySubmission](SubmitSceneViewportTransformGizmoOverlaySubmission.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoRefreshRequest.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoRefreshRequest.md index 8c245f72..480e5944 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoRefreshRequest.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoRefreshRequest.md @@ -12,15 +12,20 @@ |------|------|------| | `context` | `IEditorContext*` | 当前 editor context。 | | `overlay` | `SceneViewportOverlayData` | 当前帧 Scene View overlay 基础数据。 | -| `viewportSize` | `Math::Vector2` | 当前视口尺寸。 | -| `mousePosition` | `Math::Vector2` | 当前鼠标位置。 | +| `viewportSize` | `Math::Vector2` | 当前 viewport 尺寸。 | +| `mousePosition` | `Math::Vector2` | 当前局部鼠标位置。 | | `options` | `SceneViewportTransformGizmoFrameOptions` | 本帧 gizmo 刷新配置。 | ## 当前语义 - 这是 coordinator 刷新一帧 gizmo 所需的完整输入包。 -- `IsValid()` 当前只要求 `context != nullptr`。 -- 其余字段即使为默认值，也允许下游继续刷新，只是会得到默认 / 空 gizmo frame state。 +- `IsValid()` 当前只检查 `context != nullptr`。 +- `overlay`、`viewportSize`、`mousePosition` 和 `options` 都是值语义字段；构造后不会再回指调用方。 + +## 设计边界 + +- 即使除了 `context` 以外的字段都是默认值，它仍然被视为“有效请求”；这时下游得到的是默认/空的 gizmo frame 结果，而不是请求级别的错误。 +- 这个结构不自己做坐标转换、工具模式推导或 host-service 查询；这些工作都应当在构造前完成。 ## 相关文档 diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/SubmitSceneViewportTransformGizmoOverlaySubmission.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/SubmitSceneViewportTransformGizmoOverlaySubmission.md index f9083955..527e4fc4 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/SubmitSceneViewportTransformGizmoOverlaySubmission.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/SubmitSceneViewportTransformGizmoOverlaySubmission.md @@ -16,19 +16,28 @@ void SubmitSceneViewportTransformGizmoOverlaySubmission( ## 作用 -把构造好的 overlay submission 写入宿主服务。 +把已经构造好的 gizmo overlay submission 写入 viewport host service。 -## 当前实现行为 +## 当前行为 -当前实现非常薄，只做一件事： +当前实现只做一件事： ```cpp viewportHostService.SetSceneViewTransformGizmoOverlayState(submission.overlayState); ``` -它不会自行触发 frame data 重建；真正的重建发生在宿主服务下一次 `GetSceneViewEditorOverlayFrameData(...)` 时。 +## 边界说明 + +- 提交时只会使用 `submission.overlayState`。 +- `submission.activeGizmoKind` 不会被写入 `viewportHostService`，它只供调用方本地做交互门禁或生命周期判断。 +- 它不会自行重建 frame state，也不会触发新的 gizmo refresh。 + +## 测试覆盖 + +`tests/Editor/test_scene_viewport_transform_gizmo_coordinator.cpp` 当前验证了提交后的 host service 能收到与 submission 一致的 overlay state。 ## 相关文档 - [BuildSceneViewportTransformGizmoOverlaySubmission](BuildSceneViewportTransformGizmoOverlaySubmission.md) +- [SceneViewportTransformGizmoOverlaySubmission](SceneViewportTransformGizmoOverlaySubmission.md) - [IViewportHostService Scene View Overlay Contracts](../IViewportHostService/SceneView-Overlay-Contracts.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/BuildSceneViewportSelectionGizmoState.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/BuildSceneViewportSelectionGizmoState.md index 8ea4f68c..f911c5ef 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/BuildSceneViewportSelectionGizmoState.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/BuildSceneViewportSelectionGizmoState.md @@ -20,17 +20,24 @@ SceneViewportSelectionGizmoState BuildSceneViewportSelectionGizmoState( ## 当前实现行为 -- 从 `SelectionManager` 读取主选中实体与全选列表。 +- 从 `SelectionManager` 读取主选中实体和全选列表。 - 通过 `SceneManager::GetEntity(...)` 过滤掉空实体 id 或无法解析的对象。 - 如果 `primaryObject` 缺失但 `selectedObjects` 非空，当前会回退为最后一个可解析对象。 - 如果有 `primaryObject` 但 `selectedObjects` 为空，当前会把它补进多选列表。 -- 若存在主对象，会计算并写入 `primaryWorldRotation`。 -- 若没有任何选中对象，直接返回默认状态。 +- 如果存在主对象，会计算并写入 `primaryWorldRotation`。 +- 如果没有任何选中对象，直接返回默认状态。 - `useCenterPivot == true` 时，会对所有选中对象的“中心世界位置”求平均。 -- `useCenterPivot == false` 时，pivot 取主对象 transform 位置。 +- `useCenterPivot == false` 时，pivot 取主对象 transform 世界位置。 + +## 当前语义 + +- `primaryWorldRotation` 始终来自主对象，而不是多选平均旋转。 +- center-pivot 路径依赖 [GetGameObjectCenterWorldPosition](GetGameObjectCenterWorldPosition.md)，因此在存在 mesh bounds 的对象上会优先使用几何中心。 +- pivot 模式只影响 `pivotWorldPosition`，不会改变 `selectedObjects` 或 `primaryObject` 的选取规则。 ## 相关文档 - [SceneViewportSelectionGizmoState](SceneViewportSelectionGizmoState.md) - [GetGameObjectCenterWorldPosition](GetGameObjectCenterWorldPosition.md) +- [GetGameObjectPivotWorldPosition](GetGameObjectPivotWorldPosition.md) - [ComputeStableWorldRotation](ComputeStableWorldRotation.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/GetActiveSceneViewportGizmoKind.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/GetActiveSceneViewportGizmoKind.md index 2ab68c3e..6d491f9c 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/GetActiveSceneViewportGizmoKind.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/GetActiveSceneViewportGizmoKind.md @@ -17,17 +17,25 @@ SceneViewportActiveGizmoKind GetActiveSceneViewportGizmoKind( ## 作用 -从三个 gizmo 当前 `IsActive()` 状态推导出本帧的 active gizmo 大类。 +从三个 gizmo 当前 `IsActive()` 状态推导出本帧的 active gizmo 类型。 ## 当前实现行为 - 按固定优先级检查： - - `moveGizmo.IsActive()` - - `rotateGizmo.IsActive()` - - `scaleGizmo.IsActive()` + 1. `moveGizmo.IsActive()` + 2. `rotateGizmo.IsActive()` + 3. `scaleGizmo.IsActive()` - 三者都不 active 时返回 `SceneViewportActiveGizmoKind::None`。 - 如果出现多个 gizmo 同时 active 的异常情况，当前会按上面的检查顺序返回第一个命中的类型。 +## 当前语义 + +- 它是 frame-builder 和 coordinator 之间共享的“当前谁占用交互”推导函数。 +- 下游会据此： + - 屏蔽其他 gizmo 的 hover 更新 + - 生成 lifecycle command + - 标记 `gizmoActive` + ## 相关文档 - [SceneViewportActiveGizmoKind](SceneViewportActiveGizmoKind.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/GetGameObjectCenterWorldPosition.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/GetGameObjectCenterWorldPosition.md index 4827f324..af4f4a2e 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/GetGameObjectCenterWorldPosition.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/GetGameObjectCenterWorldPosition.md @@ -19,8 +19,16 @@ Math::Vector3 GetGameObjectCenterWorldPosition(const Components::GameObject* gam ## 当前实现行为 - `gameObject == nullptr` 或缺少 transform 时返回 `Math::Vector3::Zero()`。 -- 若对象存在有效 `MeshFilterComponent`，且 mesh 非空并 `IsValid()`，则返回 `mesh->GetBounds().center` 经 transform 后的世界位置。 -- 否则回退到对象 transform 位置。 +- 如果对象存在有效 `MeshFilterComponent`，且 mesh 非空并且 `IsValid()`，则返回： + - `mesh->GetBounds().center` + - 再通过对象 transform 做 `TransformPoint(...)` +- 否则回退到对象 transform 世界位置。 + +## 当前语义 + +- 它优先使用 mesh bounds center，而不是单纯的 transform origin。 +- 因此 center-pivot 模式在有 mesh 的对象上更接近“几何中心平均”，而不是“节点原点平均”。 +- [BuildSceneViewportSelectionGizmoState](BuildSceneViewportSelectionGizmoState.md) 会在多选且 `useCenterPivot == true` 时，对所有选中对象的这个结果求平均。 ## 相关文档 diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/GetGameObjectPivotWorldPosition.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/GetGameObjectPivotWorldPosition.md index 3d0d81e9..6e9bc994 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/GetGameObjectPivotWorldPosition.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/GetGameObjectPivotWorldPosition.md @@ -21,6 +21,11 @@ Math::Vector3 GetGameObjectPivotWorldPosition(const Components::GameObject* game - `gameObject == nullptr` 或缺少 transform 时返回 `Math::Vector3::Zero()`。 - 其余情况下直接返回 `gameObject->GetTransform()->GetPosition()`。 +## 当前语义 + +- 这里读取的是 transform 位置，不会尝试估算 mesh bounds center。 +- 它是 [BuildSceneViewportSelectionGizmoState](BuildSceneViewportSelectionGizmoState.md) 在 `useCenterPivot == false` 路径下的最终 pivot 来源。 + ## 相关文档 - [BuildSceneViewportSelectionGizmoState](BuildSceneViewportSelectionGizmoState.md) diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/SceneViewportActiveGizmoKind.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/SceneViewportActiveGizmoKind.md index a814f70b..abb10b00 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/SceneViewportActiveGizmoKind.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/SceneViewportActiveGizmoKind.md @@ -11,15 +11,16 @@ | 值 | 说明 | |----|------| | `None` | 当前没有 gizmo 处于 active 拖拽态。 | -| `Move` | 当前由 move gizmo 持有拖拽。 | -| `Rotate` | 当前由 rotate gizmo 持有拖拽。 | -| `Scale` | 当前由 scale gizmo 持有拖拽。 | +| `Move` | 当前由 move gizmo 持有交互。 | +| `Rotate` | 当前由 rotate gizmo 持有交互。 | +| `Scale` | 当前由 scale gizmo 持有交互。 | ## 当前语义 -- 这是 Scene View transform gizmo 系统内部用来表达“谁正在持有交互”的统一枚举。 -- [RefreshSceneViewportTransformGizmos](RefreshSceneViewportTransformGizmos.md) 会用它屏蔽非活动 gizmo 的 hover 竞争。 -- [SceneViewportTransformGizmoCoordinator](../SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoCoordinator.md) 也会用它驱动 begin / update / end 生命周期命令。 +- 这是 Scene View transform gizmo 系统内部用来表达“谁正在占用交互”的统一枚举。 +- [RefreshSceneViewportTransformGizmos](RefreshSceneViewportTransformGizmos.md) 会用它屏蔽非 active gizmo 的 hover 竞争。 +- [SceneViewportTransformGizmoCoordinator](../SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoCoordinator.md) 会继续用它驱动 begin / update / end 生命周期命令。 +- [SceneViewportInteractionActions](../SceneViewportInteractionActions/SceneViewportInteractionActions.md) 也会把交互命中的 gizmo 类型映射到这里。 ## 相关文档 diff --git a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/SceneViewportSelectionGizmoState.md b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/SceneViewportSelectionGizmoState.md index 4d52be4c..e80bfa9d 100644 --- a/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/SceneViewportSelectionGizmoState.md +++ b/docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoFrameBuilder/SceneViewportSelectionGizmoState.md @@ -13,15 +13,23 @@ | `primaryObject` | `Components::GameObject*` | 当前主选中对象。 | | `selectedObjects` | `std::vector` | 当前可解析的选中对象集合。 | | `pivotWorldPosition` | `Math::Vector3` | 本帧 gizmo 应使用的世界 pivot。 | -| `primaryWorldRotation` | `Math::Quaternion` | 主对象稳定世界旋转。 | +| `primaryWorldRotation` | `Math::Quaternion` | 主对象的稳定世界旋转。 | ## 当前语义 - 这是 [BuildSceneViewportSelectionGizmoState](BuildSceneViewportSelectionGizmoState.md) 的输出结构。 -- 当前实现会尽量保持 `primaryObject` 与 `selectedObjects` 自洽： +- 当前实现会尽量保持 `primaryObject` 和 `selectedObjects` 自洽： - 有多选但主对象缺失时，会回退到最后一个可解析对象。 - 只有主对象时，会把它补进 `selectedObjects`。 -- `pivotWorldPosition` 会按当前是否使用 center pivot 决定来源。 +- `pivotWorldPosition` 的来源取决于当前 pivot 模式： + - center-pivot 时使用选中对象中心平均 + - pivot 模式时使用主对象 transform 位置 +- `primaryWorldRotation` 始终来自主对象，不会做多选平均旋转。 + +## 设计边界 + +- 这个结构只是一帧快照，不拥有其中任何 `GameObject*`。 +- 它不表示当前谁在 active drag；active gizmo 信息属于 [SceneViewportTransformGizmoFrameState](SceneViewportTransformGizmoFrameState.md)。 ## 相关文档 diff --git a/docs/api/XCEngine/Editor/Viewport/Viewport.md b/docs/api/XCEngine/Editor/Viewport/Viewport.md index 8a70c92f..f99b252a 100644 --- a/docs/api/XCEngine/Editor/Viewport/Viewport.md +++ b/docs/api/XCEngine/Editor/Viewport/Viewport.md @@ -6,7 +6,7 @@ **源目录**: `editor/src/Viewport/` -**描述**: 编辑器视口基础设施模块，负责 Scene / Game 视口请求、Scene View 相机与 picking、overlay 数据装配，以及 transform gizmo 的命中与渲染辅助链路。 +**描述**: 编辑器视口基础设施模块，负责 Scene / Game 视口请求、Scene View 相机与 picking、overlay 数据装配、editor pass 规划，以及 transform gizmo 的命中与渲染辅助链路。 ## 概览 @@ -45,10 +45,26 @@ 负责 Scene View 顶部 toolbar、左侧工具按钮 overlay，以及工具切换命令折叠与执行。 - [SceneViewportEditorOverlayData](SceneViewportEditorOverlayData/SceneViewportEditorOverlayData.md) 定义 world line、sprite、screen triangle 与 handle record 组成的 canonical overlay 帧协议。 +- [SceneViewportOverlayFrameCache](SceneViewportOverlayFrameCache/SceneViewportOverlayFrameCache.md) + 统一 Scene View editor overlay frame 的缓存状态、内容签名与重建判定规则。 +- [SceneViewportResourcePaths](SceneViewportResourcePaths/SceneViewportResourcePaths.md) + 统一解析 Scene View grid shader、outline shader 与 editor icon 的资源绝对路径。 +- [SceneViewportShaderPaths](SceneViewportShaderPaths/SceneViewportShaderPaths.md) + 当前只保留为兼容 include 层，真实资源路径 owner 已收口到 `SceneViewportResourcePaths`。 +- [SceneViewportOverlaySpriteResources](SceneViewportOverlaySpriteResources/SceneViewportOverlaySpriteResources.md) + 把 `SceneViewportOverlaySpriteTextureKind` 解析为 editor icon 资源路径、RGBA 像素和可复用的纹理 descriptor set 缓存。 +- [SceneViewportPassSpecs](SceneViewportPassSpecs/SceneViewportPassSpecs.md) + 定义 Scene View 网格与选中描边的 Editor 侧规格结构，并提供到 runtime pass 规格的轻量转换。 - [SceneViewportOverlayProviders](SceneViewportOverlayProviders/SceneViewportOverlayProviders.md) 定义相机 / 灯光 / transform gizmo overlay provider 接口、registry 与默认工厂。 - [SceneViewportOverlayBuilder](SceneViewportOverlayBuilder/SceneViewportOverlayBuilder.md) 按 provider registry 聚合一帧 Scene View editor overlay 数据。 +- [SceneViewportRenderPlan](SceneViewportRenderPlan/SceneViewportRenderPlan.md) + 规划 Scene View 本帧要追加的 post-scene pass、overlay pass 与 clear-color override。 +- [SceneViewportRenderPassBundle](SceneViewportRenderPassBundle/SceneViewportRenderPassBundle.md) + 持有 grid / outline / overlay 三类 pass renderer，并为宿主服务提供可直接调用的 render-plan 构建入口。 +- [ViewportHostRenderFlowUtils](ViewportHostRenderFlowUtils/ViewportHostRenderFlowUtils.md) + 收口失败回退、Scene View request 基础接线和渲染成功后的状态回写规则。 - [SceneViewportOverlayHitTester](SceneViewportOverlayHitTester/SceneViewportOverlayHitTester.md) 基于 overlay `handleRecords` 对鼠标位置做命中测试，并给 resolver 提供候选结果。 - [SceneViewportMoveGizmo](SceneViewportMoveGizmo/SceneViewportMoveGizmo.md) @@ -88,8 +104,16 @@ - [SceneViewportHudOverlay](SceneViewportHudOverlay/SceneViewportHudOverlay.md) - [SceneViewportOrientationGizmo](SceneViewportOrientationGizmo/SceneViewportOrientationGizmo.md) - [SceneViewportEditorOverlayData](SceneViewportEditorOverlayData/SceneViewportEditorOverlayData.md) +- [SceneViewportOverlayFrameCache](SceneViewportOverlayFrameCache/SceneViewportOverlayFrameCache.md) +- [SceneViewportResourcePaths](SceneViewportResourcePaths/SceneViewportResourcePaths.md) +- [SceneViewportShaderPaths](SceneViewportShaderPaths/SceneViewportShaderPaths.md) +- [SceneViewportOverlaySpriteResources](SceneViewportOverlaySpriteResources/SceneViewportOverlaySpriteResources.md) +- [SceneViewportPassSpecs](SceneViewportPassSpecs/SceneViewportPassSpecs.md) - [SceneViewportOverlayProviders](SceneViewportOverlayProviders/SceneViewportOverlayProviders.md) - [SceneViewportOverlayBuilder](SceneViewportOverlayBuilder/SceneViewportOverlayBuilder.md) +- [SceneViewportRenderPlan](SceneViewportRenderPlan/SceneViewportRenderPlan.md) +- [SceneViewportRenderPassBundle](SceneViewportRenderPassBundle/SceneViewportRenderPassBundle.md) +- [ViewportHostRenderFlowUtils](ViewportHostRenderFlowUtils/ViewportHostRenderFlowUtils.md) - [SceneViewportOverlayHitTester](SceneViewportOverlayHitTester/SceneViewportOverlayHitTester.md) - [SceneViewportMoveGizmo](SceneViewportMoveGizmo/SceneViewportMoveGizmo.md) - [SceneViewportRotateGizmo](SceneViewportRotateGizmo/SceneViewportRotateGizmo.md) diff --git a/docs/api/XCEngine/Editor/Viewport/ViewportHostRenderFlowUtils/BuildSceneViewportGridPassData.md b/docs/api/XCEngine/Editor/Viewport/ViewportHostRenderFlowUtils/BuildSceneViewportGridPassData.md index 02d83016..0d338c4d 100644 --- a/docs/api/XCEngine/Editor/Viewport/ViewportHostRenderFlowUtils/BuildSceneViewportGridPassData.md +++ b/docs/api/XCEngine/Editor/Viewport/ViewportHostRenderFlowUtils/BuildSceneViewportGridPassData.md @@ -9,17 +9,17 @@ ## 签名 ```cpp -Rendering::Passes::InfiniteGridPassData BuildSceneViewportGridPassData( +SceneViewportGridPassData BuildSceneViewportGridPassData( const SceneViewportOverlayData& overlay); ``` ## 作用 -从当前 Scene View overlay 数据构造 grid pass 所需的 `InfiniteGridPassData`。 +从当前 Scene View overlay 数据构造 grid pass 所需的 editor 侧 `SceneViewportGridPassData`。 ## 当前实现行为 -- 当前只做字段拷贝，不创建真正的 pass 对象。 +- 当前只做字段拷贝，不创建真正的 pass 对象，也不直接生成 runtime `InfiniteGridPassData`。 - 会复制： - `valid` - `cameraPosition` @@ -38,5 +38,7 @@ Rendering::Passes::InfiniteGridPassData BuildSceneViewportGridPassData( ## 相关文档 - [SceneViewportEditorOverlayData](../SceneViewportEditorOverlayData/SceneViewportEditorOverlayData.md) +- [SceneViewportGridPassData](../SceneViewportPassSpecs/SceneViewportGridPassData.md) +- [ToBuiltinSceneViewportGridPassData](../SceneViewportPassSpecs/ToBuiltinSceneViewportGridPassData.md) - [SceneViewportGridPassFactory](../SceneViewportRenderPlan/SceneViewportGridPassFactory.md) - [CreateSceneViewportGridPass](../Passes/SceneViewportGridPass/CreateSceneViewportGridPass.md) diff --git a/docs/api/XCEngine/Editor/Viewport/ViewportHostRenderFlowUtils/BuildSceneViewportSelectionOutlineStyle.md b/docs/api/XCEngine/Editor/Viewport/ViewportHostRenderFlowUtils/BuildSceneViewportSelectionOutlineStyle.md index 07881ded..ae31eebc 100644 --- a/docs/api/XCEngine/Editor/Viewport/ViewportHostRenderFlowUtils/BuildSceneViewportSelectionOutlineStyle.md +++ b/docs/api/XCEngine/Editor/Viewport/ViewportHostRenderFlowUtils/BuildSceneViewportSelectionOutlineStyle.md @@ -9,13 +9,13 @@ ## 签名 ```cpp -Rendering::Passes::ObjectIdOutlineStyle BuildSceneViewportSelectionOutlineStyle( +SceneViewportSelectionOutlineStyle BuildSceneViewportSelectionOutlineStyle( bool debugSelectionMask = false); ``` ## 作用 -生成 Scene View 选中轮廓 pass 的默认样式配置。 +生成 Scene View 选中轮廓 pass 的 editor 侧默认样式配置。 ## 当前实现行为 @@ -37,7 +37,7 @@ Rendering::Passes::ObjectIdOutlineStyle BuildSceneViewportSelectionOutlineStyle( ## 真实使用位置 -[BuildSceneViewportRenderPlan](../SceneViewportRenderPlan/BuildSceneViewportRenderPlan.md) 在为当前选中对象创建 selection outline pass 之前，会调用本函数构造 `ObjectIdOutlineStyle`。 +[BuildSceneViewportRenderPlan](../SceneViewportRenderPlan/BuildSceneViewportRenderPlan.md) 在为当前选中对象创建 selection outline pass 之前，会调用本函数构造 `SceneViewportSelectionOutlineStyle`；真正转成 runtime `ObjectIdOutlineStyle` 的动作发生在 [ToBuiltinSceneViewportSelectionOutlineStyle](../SceneViewportPassSpecs/ToBuiltinSceneViewportSelectionOutlineStyle.md)。 ## 设计说明 @@ -52,5 +52,6 @@ Rendering::Passes::ObjectIdOutlineStyle BuildSceneViewportSelectionOutlineStyle( - [SceneViewportRenderPlan](../SceneViewportRenderPlan/SceneViewportRenderPlan.md) - [BuildSceneViewportRenderPlan](../SceneViewportRenderPlan/BuildSceneViewportRenderPlan.md) -- [ObjectIdOutlineStyle](../../../Rendering/Passes/ObjectIdOutlineStyle/ObjectIdOutlineStyle.md) +- [SceneViewportSelectionOutlineStyle](../SceneViewportPassSpecs/SceneViewportSelectionOutlineStyle.md) +- [ToBuiltinSceneViewportSelectionOutlineStyle](../SceneViewportPassSpecs/ToBuiltinSceneViewportSelectionOutlineStyle.md) - [SceneViewportSelectionOutlinePass](../Passes/SceneViewportSelectionOutlinePass/SceneViewportSelectionOutlinePass.md) diff --git a/docs/api/XCEngine/Editor/Viewport/ViewportHostRenderFlowUtils/ViewportHostRenderFlowUtils.md b/docs/api/XCEngine/Editor/Viewport/ViewportHostRenderFlowUtils/ViewportHostRenderFlowUtils.md index 5b163d38..6eae90e8 100644 --- a/docs/api/XCEngine/Editor/Viewport/ViewportHostRenderFlowUtils/ViewportHostRenderFlowUtils.md +++ b/docs/api/XCEngine/Editor/Viewport/ViewportHostRenderFlowUtils/ViewportHostRenderFlowUtils.md @@ -65,8 +65,8 @@ | [BuildViewportRenderTargetUnavailablePolicy](BuildViewportRenderTargetUnavailablePolicy.md) | 构建“render target 不可用”策略。 | | [BuildSceneViewportRenderFailurePolicy](BuildSceneViewportRenderFailurePolicy.md) | 把 Scene View 失败分类转成回退策略。 | | [BuildGameViewportRenderFailurePolicy](BuildGameViewportRenderFailurePolicy.md) | 把 Game View 失败分类转成回退策略。 | -| [BuildSceneViewportGridPassData](BuildSceneViewportGridPassData.md) | 把 Scene View overlay 相机状态转换为 `InfiniteGridPassData`。 | -| [BuildSceneViewportSelectionOutlineStyle](BuildSceneViewportSelectionOutlineStyle.md) | 生成 Scene View 选中轮廓默认样式。 | +| [BuildSceneViewportGridPassData](BuildSceneViewportGridPassData.md) | 把 Scene View overlay 相机状态转换为 `SceneViewportGridPassData`。 | +| [BuildSceneViewportSelectionOutlineStyle](BuildSceneViewportSelectionOutlineStyle.md) | 生成 Scene View 选中轮廓的 editor 样式。 | | [ApplySceneViewportRenderRequestSetup](ApplySceneViewportRenderRequestSetup.md) | 为 Scene View 基础 request 接线。 | | [MarkSceneViewportRenderSuccess](MarkSceneViewportRenderSuccess.md) | Scene View 成功后的状态回写。 | | [MarkGameViewportRenderSuccess](MarkGameViewportRenderSuccess.md) | Game View 成功后的状态回写。 | diff --git a/docs/api/XCEngine/Editor/Viewport/ViewportHostService/Initialize-And-Shutdown.md b/docs/api/XCEngine/Editor/Viewport/ViewportHostService/Initialize-And-Shutdown.md index af399b02..360d716a 100644 --- a/docs/api/XCEngine/Editor/Viewport/ViewportHostService/Initialize-And-Shutdown.md +++ b/docs/api/XCEngine/Editor/Viewport/ViewportHostService/Initialize-And-Shutdown.md @@ -29,14 +29,12 @@ void Shutdown(); ### `Shutdown()` - 逐个销毁 `Scene / Game` 两个 `ViewportEntry` 的 render target。 -- 依次调用： - - `m_sceneViewportSelectionOutlineRenderer.Shutdown()` - - `m_sceneViewportGridRenderer.Shutdown()` - - `m_sceneViewportEditorOverlayRenderer.Shutdown()` - 释放 Scene View 的 selection outline、grid 和 overlay 三类 pass renderer 资源。 +- 调用 `m_sceneViewportRenderPassBundle.Shutdown()`，统一回收 Scene View 的 selection outline、grid 和 overlay 三类 pass renderer 资源。 - 清空 Scene View 私有相机状态、overlay frame data 缓存与最近一次渲染上下文。 - 置空 `m_device`、`m_backend`，并释放 `m_sceneRenderer`。 +这里真正的 renderer 关闭顺序由 [SceneViewportRenderPassBundle::Shutdown](../SceneViewportRenderPassBundle/Shutdown.md) 决定；`ViewportHostService` 不再直接散落持有三套 pass renderer 字段。 + ## 当前实现边界 - `Initialize(...)` 本身不会立即创建 render target 或 Scene View 相机。 @@ -45,5 +43,6 @@ void Shutdown(); ## 相关文档 - [ViewportHostService](ViewportHostService.md) +- [SceneViewportRenderPassBundle](../SceneViewportRenderPassBundle/SceneViewportRenderPassBundle.md) - [BeginFrame / RequestViewport](BeginFrame-And-RequestViewport.md) - [RenderRequestedViewports](RenderRequestedViewports.md) diff --git a/docs/api/XCEngine/Editor/Viewport/ViewportHostService/RenderRequestedViewports.md b/docs/api/XCEngine/Editor/Viewport/ViewportHostService/RenderRequestedViewports.md index 14b6fe50..49dfe2ca 100644 --- a/docs/api/XCEngine/Editor/Viewport/ViewportHostService/RenderRequestedViewports.md +++ b/docs/api/XCEngine/Editor/Viewport/ViewportHostService/RenderRequestedViewports.md @@ -41,7 +41,7 @@ Scene View 当前不是简单地把场景直接交给 renderer，而是先做一 2. 获取 `SceneViewportOverlayData`。 3. 读取当前选中对象 id 列表。 4. 读取 `GetSceneViewEditorOverlayFrameData(...)`。 -5. 调用 [BuildSceneViewportRenderPlan](../SceneViewportRenderPlan/BuildSceneViewportRenderPlan.md)，为 request 组装： +5. 调用 [SceneViewportRenderPassBundle::BuildRenderPlan](../SceneViewportRenderPassBundle/BuildRenderPlan.md)，由 bundle 复用 [BuildSceneViewportRenderPlan](../SceneViewportRenderPlan/BuildSceneViewportRenderPlan.md) 为 request 组装： - grid pass - selection outline pass - editor overlay pass @@ -81,6 +81,7 @@ Game View 更接近运行时流程： ## 相关文档 - [ViewportHostService](ViewportHostService.md) +- [SceneViewportRenderPassBundle](../SceneViewportRenderPassBundle/SceneViewportRenderPassBundle.md) - [SceneViewportRenderPlan](../SceneViewportRenderPlan/SceneViewportRenderPlan.md) - [ViewportHostRenderFlowUtils](../ViewportHostRenderFlowUtils/ViewportHostRenderFlowUtils.md) - [SceneViewportEditorOverlayPass](../Passes/SceneViewportEditorOverlayPass/SceneViewportEditorOverlayPass.md) diff --git a/docs/api/XCEngine/Editor/Viewport/ViewportHostService/SceneView-Overlay-Frame-Data.md b/docs/api/XCEngine/Editor/Viewport/ViewportHostService/SceneView-Overlay-Frame-Data.md index 1bfd3e01..2be40c2f 100644 --- a/docs/api/XCEngine/Editor/Viewport/ViewportHostService/SceneView-Overlay-Frame-Data.md +++ b/docs/api/XCEngine/Editor/Viewport/ViewportHostService/SceneView-Overlay-Frame-Data.md @@ -20,7 +20,7 @@ void SetSceneViewTransformGizmoOverlayState( 管理 `ViewportHostService` 当前维护的三块 Scene View overlay 数据： -- 前端几何计算用的相机 overlay +- 前端几何计算使用的相机 overlay - 一份可缓存的 editor overlay frame data - 当前帧 transform gizmo 的 overlay state @@ -48,16 +48,9 @@ void SetSceneViewTransformGizmoOverlayState( 当前会先走 `EnsureSceneViewEditorOverlayFrameData(context)`，内部流程大致是： 1. 确保 Scene View 私有相机存在。 -2. 从当前 `ViewportEntry` 解析 Scene 视口尺寸。 -3. 读取活动场景、相机 overlay、选中对象列表和内容签名。 -4. 只要以下任一条件成立，就重建缓存： - - `m_sceneViewTransformGizmoOverlayDirty == true` - - 还没有缓存 - - 场景指针变化 - - 视口尺寸变化 - - 选中对象列表变化 - - 内容签名变化 - - 相机 overlay 数据变化 +2. 通过 [ResolveSceneViewportOverlayFrameViewportSize](../SceneViewportOverlayFrameCache/ResolveSceneViewportOverlayFrameViewportSize.md) 解析 Scene 视口尺寸。 +3. 读取活动场景、相机 overlay、选中对象列表，并通过 [BuildSceneViewportOverlayContentSignature](../SceneViewportOverlayFrameCache/BuildSceneViewportOverlayContentSignature.md) 生成内容签名。 +4. 通过 [ShouldRebuildSceneViewportOverlayFrameCache](../SceneViewportOverlayFrameCache/ShouldRebuildSceneViewportOverlayFrameCache.md) 统一判断是否需要重建缓存。 5. 真正重建时，调用： ```cpp @@ -70,6 +63,8 @@ m_sceneViewportOverlayBuilder.Build( &m_sceneViewTransformGizmoOverlayState); ``` +6. 重建完成后，再通过 [UpdateSceneViewportOverlayFrameCacheState](../SceneViewportOverlayFrameCache/UpdateSceneViewportOverlayFrameCacheState.md) 回写缓存。 + 因此当前返回的不是“纯世界 overlay”，而是一份已经把默认 world overlay provider 输出和当前帧 gizmo state 合成到一起的 frame data。 ## `BeginFrame()` 的影响 @@ -79,7 +74,7 @@ m_sceneViewportOverlayBuilder.Build( - 清空 `m_sceneViewTransformGizmoOverlayState` - 把 `m_sceneViewTransformGizmoOverlayDirty` 重新置为 `true` -这意味着 transform gizmo overlay 是逐帧输入。`SceneViewPanel` 需要在每一帧重新提交当前 gizmo state。 +这意味着 transform gizmo overlay 是逐帧输入，`SceneViewPanel` 需要在每一帧重新提交当前 gizmo state。 ## 设计含义 @@ -89,11 +84,12 @@ m_sceneViewportOverlayBuilder.Build( - 宿主服务按需重建一份合成 frame data - 这份 frame data 同时服务 hit-test 与最终 `SceneViewportEditorOverlayPass` -这样做减少了双通道协议漂移，也让 `SceneViewPanel` 不需要自己维护 overlay 缓存对象。 +`SceneViewportOverlayFrameCache` 这组 helper 进一步把“尺寸解析 / 内容签名 / 命中判定 / 缓存回写”从 `ViewportHostService` 本体里拆了出来，减少了宿主类内部的规则散落。 ## 相关文档 - [ViewportHostService](ViewportHostService.md) +- [SceneViewportOverlayFrameCache](../SceneViewportOverlayFrameCache/SceneViewportOverlayFrameCache.md) - [SceneViewportOverlayBuilder](../SceneViewportOverlayBuilder/SceneViewportOverlayBuilder.md) - [SceneViewportOverlayProviders](../SceneViewportOverlayProviders/SceneViewportOverlayProviders.md) - [RenderRequestedViewports](RenderRequestedViewports.md) diff --git a/docs/api/XCEngine/Editor/Viewport/ViewportHostService/ViewportHostService.md b/docs/api/XCEngine/Editor/Viewport/ViewportHostService/ViewportHostService.md index 34fb42a2..9d285f07 100644 --- a/docs/api/XCEngine/Editor/Viewport/ViewportHostService/ViewportHostService.md +++ b/docs/api/XCEngine/Editor/Viewport/ViewportHostService/ViewportHostService.md @@ -6,7 +6,7 @@ **源文件**: `editor/src/Viewport/ViewportHostService.h` -**描述**: `IViewportHostService` 的当前实现，负责 Scene / Game 视口资源、隐藏编辑器相机、Scene View overlay frame data、object-id picking 和编辑器专属 render pass 注入。 +**描述**: `IViewportHostService` 的当前实现，负责 Scene / Game 视口资源、隐藏编辑器相机、Scene View overlay frame data、object-id picking，以及通过 render-pass bundle 注入编辑器专属 Scene View pass。 ## 概述 @@ -37,19 +37,16 @@ - `SceneViewportOverlayBuilder` - 成员 `m_sceneViewportOverlayBuilder` - 默认持有相机 + 灯光 provider registry -- `m_sceneViewEditorOverlayFrameData` - - 当前缓存的一份 Scene View overlay frame data +- `SceneViewportOverlayFrameCacheState` + - 成员 `m_sceneViewEditorOverlayFrameCache` + - 当前缓存的一份 Scene View overlay frame data 及其缓存元数据 - `m_sceneViewTransformGizmoOverlayState` - 当前帧 transform gizmo overlay state -- 一组 overlay cache key - - 场景指针 - - 选中对象 id 列表 - - 视口尺寸 - - 内容签名 - - dirty 标记 -- `SceneViewportGridPassRenderer` -- `SceneViewportSelectionOutlinePassRenderer` -- `SceneViewportEditorOverlayPassRenderer` +- `m_sceneViewTransformGizmoOverlayDirty` + - 标记当前帧 gizmo overlay 是否强制触发缓存重建 +- `SceneViewportRenderPassBundle` + - 成员 `m_sceneViewportRenderPassBundle` + - 统一持有 grid / selection outline / editor overlay 三类 pass renderer 生命周期，并提供 `BuildRenderPlan(...)` - `SceneRenderer` - 最近一次 Scene View 渲染上下文 @@ -83,11 +80,9 @@ 1. `RequestViewport(Scene, size)` 标记本帧需要 Scene 视口，并尽量复用或重建 render target。 2. `SceneViewPanel` 根据当前 selection、工具模式和鼠标状态刷新 gizmo，并先经由 coordinator 提交 gizmo overlay submission。 3. 命中测试前，面板通过 `GetSceneViewEditorOverlayFrameData(...)` 取到一份已经合成好 scene icon、相机/灯光辅助几何和 gizmo handle 的 frame data。 -4. `RenderRequestedViewports(...)` 中为 Scene entry 构建 `SceneViewportRenderPlan`： - - object-id surface - - [SceneViewportGridPass](../Passes/SceneViewportGridPass/SceneViewportGridPass.md) - - [SceneViewportSelectionOutlinePass](../Passes/SceneViewportSelectionOutlinePass/SceneViewportSelectionOutlinePass.md) - - [SceneViewportEditorOverlayPass](../Passes/SceneViewportEditorOverlayPass/SceneViewportEditorOverlayPass.md) +4. `RenderRequestedViewports(...)` 中通过 [SceneViewportRenderPassBundle](../SceneViewportRenderPassBundle/SceneViewportRenderPassBundle.md) 为 Scene entry 构建 `SceneViewportRenderPlan`： + - 内部持有 [SceneViewportGridPass](../Passes/SceneViewportGridPass/SceneViewportGridPass.md)、[SceneViewportSelectionOutlinePass](../Passes/SceneViewportSelectionOutlinePass/SceneViewportSelectionOutlinePass.md)、[SceneViewportEditorOverlayPass](../Passes/SceneViewportEditorOverlayPass/SceneViewportEditorOverlayPass.md) 对应 renderer + - 再经由 [BuildSceneViewportRenderPlan](../SceneViewportRenderPlan/BuildSceneViewportRenderPlan.md) 规划 object-id surface、post-scene pass、overlay pass 与 clear-color override 5. `ApplySceneViewportRenderPlan(...)` 把 render plan 回写到 `CameraRenderRequest`。 6. `SceneRenderer` 提交请求。 7. 渲染成功后回写颜色/object-id 资源状态，并在存在异步加载时更新 `Loading scene assets... (N)` 状态文案。 @@ -141,6 +136,7 @@ ### 合成后的 editor overlay frame data - `GetSceneViewEditorOverlayFrameData(...)` 会按需重建并缓存一份合成 frame data。 +- 具体缓存规则当前由 [SceneViewportOverlayFrameCache](../SceneViewportOverlayFrameCache/SceneViewportOverlayFrameCache.md) 收口，而不是散落在宿主服务里手写多组比较逻辑。 - 真正构建时走： ```cpp @@ -148,7 +144,7 @@ m_sceneViewportOverlayBuilder.Build(..., &m_sceneViewTransformGizmoOverlayState) ``` - 也就是说，默认 world overlay provider 的输出和当前帧 gizmo state 会在这一层被合成到同一份 frame data 里。 -- 这份缓存只有在场景、视口尺寸、selection、内容签名、相机 overlay 或 gizmo dirty 状态变化时才会重建。 +- 这份缓存只有在 [ShouldRebuildSceneViewportOverlayFrameCache](../SceneViewportOverlayFrameCache/ShouldRebuildSceneViewportOverlayFrameCache.md) 返回 `true` 时才会重建。 ## 与 `SceneViewPanel` 的配合关系 @@ -199,7 +195,7 @@ Game View 更接近运行时逻辑： ## 生命周期与线程语义 - 需要先 `Initialize(...)`，再参与每帧 `BeginFrame()` / `RequestViewport(...)` / `RenderRequestedViewports(...)` 流程。 -- `Shutdown()` 会销毁所有 render target、overlay renderer 资源和 Scene View 相机状态。 +- `Shutdown()` 会销毁所有 render target，调用 `m_sceneViewportRenderPassBundle.Shutdown()` 回收 Scene View pass renderer 资源，并清空 Scene View 相机与 overlay 缓存状态。 - 当前应视为主线程 / UI 线程与渲染线程协同下的 Editor 服务对象，但接口本身没有声明线程安全。 ## 当前限制 @@ -212,8 +208,10 @@ Game View 更接近运行时逻辑： - [IViewportHostService](../IViewportHostService/IViewportHostService.md) - [ViewportHostRenderFlowUtils](../ViewportHostRenderFlowUtils/ViewportHostRenderFlowUtils.md) +- [SceneViewportRenderPassBundle](../SceneViewportRenderPassBundle/SceneViewportRenderPassBundle.md) - [SceneViewportRenderPlan](../SceneViewportRenderPlan/SceneViewportRenderPlan.md) - [SceneViewportCameraController](../SceneViewportCameraController/SceneViewportCameraController.md) +- [SceneViewportOverlayFrameCache](../SceneViewportOverlayFrameCache/SceneViewportOverlayFrameCache.md) - [SceneViewportOverlayBuilder](../SceneViewportOverlayBuilder/SceneViewportOverlayBuilder.md) - [SceneViewportOverlayProviders](../SceneViewportOverlayProviders/SceneViewportOverlayProviders.md) - [SceneViewportOverlayHandleBuilder](../SceneViewportOverlayHandleBuilder/SceneViewportOverlayHandleBuilder.md) diff --git a/docs/api/XCEngine/Editor/Viewport/ViewportHostSurfaceUtils/ClampViewportPixelCoordinate.md b/docs/api/XCEngine/Editor/Viewport/ViewportHostSurfaceUtils/ClampViewportPixelCoordinate.md index 94811d84..0ae64f09 100644 --- a/docs/api/XCEngine/Editor/Viewport/ViewportHostSurfaceUtils/ClampViewportPixelCoordinate.md +++ b/docs/api/XCEngine/Editor/Viewport/ViewportHostSurfaceUtils/ClampViewportPixelCoordinate.md @@ -14,13 +14,29 @@ uint32_t ClampViewportPixelCoordinate(float value, uint32_t extent); ## 作用 -把浮点视口坐标稳定映射到纹理像素范围。 +把浮点 viewport 坐标稳定映射到纹理像素范围。 ## 当前实现行为 -- 若 `extent == 0`，直接返回 `0`。 -- 否则会先把输入钳制到 `[0, extent - 1]`，再对结果取 `floor`。 -- 这样可以避免 GPU 像素读回越界。 +- 当 `extent == 0` 时直接返回 `0`。 +- 否则会先把输入钳制到 `[0, extent - 1]`。 +- 再对钳制结果执行 `floor`，最后转成 `uint32_t`。 + +## 当前语义 + +- 这是一个“先 clamp、再离散化”的像素索引 helper。 +- 它避免了 GPU 像素读回时越界，也避免了把 `0.99f` 这种接近像素边界的值提前进位到下一个像素。 +- 因为用的是 `floor`，所以它始终向较小像素索引落点。 + +## 测试覆盖 + +`tests/Editor/test_viewport_host_surface_utils.cpp` 当前验证了： + +- 负坐标会被钳到 `0` +- 小于 `1` 的正值会落到 `0` +- 普通浮点值会先 floor 再转换 +- 超出 extent 的值会被钳到 `extent - 1` +- `extent == 0` 时返回 `0` ## 相关文档 diff --git a/docs/api/XCEngine/Editor/Viewport/ViewportHostSurfaceUtils/ViewportRequiresObjectIdResources.md b/docs/api/XCEngine/Editor/Viewport/ViewportHostSurfaceUtils/ViewportRequiresObjectIdResources.md index 15db125a..1359dfcf 100644 --- a/docs/api/XCEngine/Editor/Viewport/ViewportHostSurfaceUtils/ViewportRequiresObjectIdResources.md +++ b/docs/api/XCEngine/Editor/Viewport/ViewportHostSurfaceUtils/ViewportRequiresObjectIdResources.md @@ -14,14 +14,30 @@ bool ViewportRequiresObjectIdResources(EditorViewportKind kind); ## 作用 -判断给定视口类型是否要求 object-id 相关资源。 +判断给定 viewport 类型是否要求 object-id 相关资源。 ## 当前实现行为 - 当前只有 `EditorViewportKind::Scene` 返回 `true`。 -- 其余视口类型都不要求 object-id 纹理、RTV 或 SRV。 +- 其余 viewport 类型都不要求 object-id 纹理、RTV 或 SRV。 + +## 当前语义 + +- 这是 `ViewportHostSurfaceUtils` 里决定资源需求差异的最小分流点。 +- 下游的 [CanReuseViewportResources](CanReuseViewportResources.md) 会据此决定是否必须检查 object-id 资源是否齐备。 +- 当前实现反映的是： + - Scene View 需要 picking / object-id 相关能力 + - Game View 不需要这套编辑器专用资源 + +## 测试覆盖 + +`tests/Editor/test_viewport_host_surface_utils.cpp` 当前验证了： + +- `Game` 返回 `false` +- `Scene` 返回 `true` ## 相关文档 - [ViewportHostSurfaceUtils](ViewportHostSurfaceUtils.md) - [CanReuseViewportResources](CanReuseViewportResources.md) +- [ViewportObjectIdPicker](../ViewportObjectIdPicker/ViewportObjectIdPicker.md) diff --git a/docs/api/XCEngine/Editor/XCUIBackend/ImGuiTransitionBackend/ImGuiTransitionBackend.md b/docs/api/XCEngine/Editor/XCUIBackend/ImGuiTransitionBackend/ImGuiTransitionBackend.md new file mode 100644 index 00000000..023831ce --- /dev/null +++ b/docs/api/XCEngine/Editor/XCUIBackend/ImGuiTransitionBackend/ImGuiTransitionBackend.md @@ -0,0 +1,49 @@ +# ImGuiTransitionBackend + +**命名空间**: `XCEngine::Editor::XCUIBackend` + +**类型**: `class` + +**源文件**: `editor/src/XCUIBackend/ImGuiTransitionBackend.h` + +**描述**: 把 `UIDrawList` / `UIDrawData` 过渡性地刷到 Dear ImGui `ImDrawList` 的桥接器。 + +## 概览 + +`ImGuiTransitionBackend` 解决的是“XCUI 已经有 draw command，但 editor 主窗口仍由 ImGui 承载”这个过渡问题。 + +它当前做三件事： + +- 在 `BeginFrame()` 清空上一帧待刷数据 +- 用 `Submit(...)` 收集 `UIDrawList` 或 `UIDrawData` +- 在 `EndFrame(...)` 把命令翻译成 `ImDrawList` 调用 + +## 当前行为 + +- `BeginFrame()` 会同时重置： + - `m_pendingDrawLists` + - `m_pendingCommandCount` + - `m_lastFlushedDrawListCount` + - `m_lastFlushedCommandCount` +- `Submit(const UIDrawData&)` 当前只是遍历内部 draw list 后逐个转发到 `Submit(const UIDrawList&)`。 +- `EndFrame(...)` 默认落到 `ImGui::GetWindowDrawList()`；如果目标 draw list 为空，会清空 pending state 并返回 `false`。 +- flush 时会维护 `clipDepth`；即便调用方忘了显式补足 `PopClipRect`，函数也会在尾部补弹所有未闭合 clip。 +- `Text` 命令在 `fontSize <= 0` 时回退到 `ImGui::GetFontSize()`。 +- `Image` 命令当前要求 `UITextureHandle::IsValid()` 为真；并且固定使用整张纹理，不消费 `UIDrawCommand.uvMin / uvMax`。 + +## 当前调用链 + +- `XCUIDemoPanel::Render()` 当前每帧都会 `BeginFrame() -> Submit(drawData) -> EndFrame(ImGui::GetWindowDrawList())`。 +- `tests/Editor/test_xcui_imgui_transition_backend.cpp` 当前直接验证了 pending state 重置和 flush 后 `ImDrawList` 顶点 / 命令缓冲被写入。 + +## 当前实现边界 + +- 这是过渡后端，不是最终 XCUI renderer。 +- 当前只覆盖 `FilledRect / RectOutline / Text / Image / PushClipRect / PopClipRect` 六类命令。 +- 所有待刷 draw list 目前都先暂存在 `std::vector` 里，没有增量流式提交。 + +## 相关文档 + +- [XCUIBackend](../XCUIBackend.md) +- [DrawData](../../../UI/DrawData/DrawData.md) +- [XCUIDemoPanel](../../panels/XCUIDemoPanel/XCUIDemoPanel.md) diff --git a/docs/api/XCEngine/Editor/XCUIBackend/XCUIBackend.md b/docs/api/XCEngine/Editor/XCUIBackend/XCUIBackend.md new file mode 100644 index 00000000..079e3b21 --- /dev/null +++ b/docs/api/XCEngine/Editor/XCUIBackend/XCUIBackend.md @@ -0,0 +1,25 @@ +# XCUIBackend + +**命名空间**: `XCEngine::Editor::XCUIBackend` + +**类型**: `submodule` + +**源文件目录**: `editor/src/XCUIBackend/` + +**描述**: Editor 侧 XCUI 过渡后端，当前主要承接“XCUI draw data 已生成，但最终仍要落到 Dear ImGui / 现有宿主”的桥接层。 + +## 当前范围 + +- [ImGuiTransitionBackend](ImGuiTransitionBackend/ImGuiTransitionBackend.md) +- [XCUIDemoRuntime](XCUIDemoRuntime/XCUIDemoRuntime.md) + +## 当前定位 + +- `ImGuiTransitionBackend` 已经接上真实测试和 demo 面板，是当前过渡期可运行的桥接器。 +- `XCUIDemoRuntime` 目前只有头文件声明，还没有 `.cpp` 和真实调用链，更像后续 demo runtime 的占位入口。 + +## 相关文档 + +- [Editor](../Editor.md) +- [UI](../../UI/UI.md) +- [panels](../panels/panels.md) diff --git a/docs/api/XCEngine/Editor/XCUIBackend/XCUIDemoRuntime/XCUIDemoRuntime.md b/docs/api/XCEngine/Editor/XCUIBackend/XCUIDemoRuntime/XCUIDemoRuntime.md new file mode 100644 index 00000000..4def2c98 --- /dev/null +++ b/docs/api/XCEngine/Editor/XCUIBackend/XCUIDemoRuntime/XCUIDemoRuntime.md @@ -0,0 +1,42 @@ +# XCUIDemoRuntime + +**命名空间**: `XCEngine::Editor::XCUIBackend` + +**类型**: `struct family + class declaration` + +**源文件**: `editor/src/XCUIBackend/XCUIDemoRuntime.h` + +**描述**: XCUI demo runtime 的头文件声明，当前公开输入状态、帧统计、帧结果和一个 move-only 的 PIMPL 运行时类。 + +## 公开声明 + +| 声明 | 类型 | 说明 | +|------|------|------| +| `XCUIDemoInputState` | `struct` | demo 帧输入，当前覆盖 canvas、指针、焦点与快捷键状态。 | +| `XCUIDemoFrameStats` | `struct` | 文档就绪、依赖数、元素数、dirty root 数、draw command 数等统计。 | +| `XCUIDemoFrameResult` | `struct` | `UIDrawData + XCUIDemoFrameStats`。 | +| `XCUIDemoRuntime` | `class` | move-only PIMPL 声明，公开 `ReloadDocuments()`、`Update()`、`GetFrameResult()`、`TryGetElementRect()`。 | + +## 当前状态 + +- 当前工作树里只有 `editor/src/XCUIBackend/XCUIDemoRuntime.h`，没有对应 `.cpp`。 +- 代码搜索也没有发现 `XCUIDemoRuntime` 的真实实例化或调用链。 +- 因此这里公开的构造、析构、移动赋值、`ReloadDocuments()`、`Update()` 和 `TryGetElementRect()` 目前都只是接口声明，不应被文档误写成已完成实现。 + +## 当前语义边界 + +- 从头文件能确认的事实只有： + - 它采用 `RuntimeState` PIMPL + - 它是 move-only，禁止拷贝 + - 它打算围绕“输入 -> 帧结果 -> 元素矩形查询”组织 demo runtime +- 但当前无法从源码确认： + - 文档加载策略 + - 实际 draw data 生成过程 + - 焦点 / hover / command 跟踪逻辑 + - 失败返回路径 + +## 相关文档 + +- [XCUIBackend](../XCUIBackend.md) +- [DrawData](../../../UI/DrawData/DrawData.md) +- [Types](../../../UI/Types/Types.md) diff --git a/docs/api/XCEngine/Editor/panels/ConsolePanel/ConsolePanel.md b/docs/api/XCEngine/Editor/panels/ConsolePanel/ConsolePanel.md index e7f691d3..5b7e2bf2 100644 --- a/docs/api/XCEngine/Editor/panels/ConsolePanel/ConsolePanel.md +++ b/docs/api/XCEngine/Editor/panels/ConsolePanel/ConsolePanel.md @@ -6,28 +6,107 @@ **源文件**: `editor/src/panels/ConsolePanel.h` -**描述**: 控制台面板，负责根据过滤状态显示编辑器日志，并绘制日志工具栏。 +**描述**: 编辑器控制台面板，负责显示 `EditorConsoleSink` 中的日志记录、维护过滤与搜索状态，并组织工具栏、日志列表、详情区与 play mode 错误暂停逻辑。 ## 概述 -`ConsolePanel` 当前围绕两块逻辑展开： +`ConsolePanel` 当前已经不是一个“只调两个 helper 就结束”的薄面板。它实际串起了四层内容： -- 一个 `UI::ConsoleFilterState` -- 一个 `EditorConsoleSink` 日志源 +1. 日志数据源： + 来自 [EditorConsoleSink](../../Core/EditorConsoleSink/EditorConsoleSink.md) 的记录数组与 revision。 +2. 本地视图状态： + 由 [ConsoleFilterState](../../UI/ConsoleFilterState/ConsoleFilterState.md)、搜索缓冲、选中 serial、详情区高度和 play mode 标志组成。 +3. 面板编排： + 负责工具栏、日志列表、splitter、详情区和上下文菜单的布局。 +4. 编辑器协作： + 通过 `EventBus` 订阅 play mode 事件，并在需要时发出 `PlayModePauseRequestedEvent`。 -## 当前实现说明 +因此它更像“Console 工作流容器”，而不只是一个简单的 ImGui 窗口包装器。 -- 构造时面板名为 `"Console"`。 -- `Render()` 里会先绘制工具栏，再绘制日志滚动区域。 -- 日志行实际绘制和工具栏动作主要委托给 `Actions` 层。 +## 生命周期 + +- [Constructor](Constructor.md) 会把面板标题固定为 `"Console"`。 +- [OnAttach](OnAttach.md) 会初始化详情区高度、记录当前 revision，并向 `EventBus` 订阅 play mode 四类事件。 +- [OnDetach](OnDetach.md) 会注销这些事件订阅。 +- [Render](Render.md) 会构建完整控制台 UI，并在渲染尾部调用 `Actions::ObserveInactiveActionRoute(...)`。 + +## 当前 Render 流程 + +按当前 `ConsolePanel.cpp` 的真实行为，`Render()` 大致遵循下面的顺序： + +1. 进入 `UI::PanelWindowScope`，处理面板可见性。 +2. 获取 [EditorConsoleSink](../../Core/EditorConsoleSink/EditorConsoleSink.md)；若 sink 不可用，则直接显示 empty state。 +3. 读取日志记录与 revision，并在启用 `Error Pause` 时扫描新增 error/fatal 日志。 +4. 用 `ConsoleFilterState + SearchQuery` 生成可见行集合，并维护当前选中项。 +5. 绘制工具栏： + - `Clear` + - `Collapse` + - `Error Pause` + - source dropdown + - 搜索框 + - severity toggle counters +6. 绘制日志列表区，支持： + - 选择 + - 双击打开源码 + - 右键菜单 + - Ctrl+C 复制 + - 上下方向键切换 +7. 绘制 splitter 与详情区，展示完整消息、source location、thread、timestamp 和 occurrence count。 +8. 调用 `ObserveInactiveActionRoute(...)`，保证该面板在未设置显式 action route 时仍能参与统一动作观察。 + +## 过滤、搜索与折叠 + +`ConsolePanel` 的本地过滤状态当前包括： + +- `ShowLog / ShowWarning / ShowError` +- `Collapse` +- `ClearOnPlay` +- `ErrorPause` +- 文本搜索缓冲 `m_searchBuffer` + +其中： + +- 非折叠模式下，每条 `EditorConsoleRecord` 都会对应一行。 +- 折叠模式下，面板会按“等级 + 分类 + 消息 + 文件 + 行号 + 函数”构造 key，把重复日志聚合为单行，并累计 `count`。 +- 搜索匹配不仅检查日志消息，也会把文件路径和函数名纳入 haystack。 + +## Play Mode 事件与 Error Pause + +`OnAttach()` 当前会订阅： + +- `PlayModeStartedEvent` +- `PlayModeStoppedEvent` +- `PlayModePausedEvent` +- `PlayModeResumedEvent` + +相关行为是： + +- `ClearOnPlay` 打开时，进入 play mode 会立即清空 sink、重置选择状态。 +- `ErrorPause` 打开且当前未暂停时，`Render()` 会扫描自上次 play mode 边界之后新增的 `Error/Fatal` 日志，并发布 `PlayModePauseRequestedEvent`。 +- `m_lastErrorPauseScanSerial` 用来避免重复对旧错误记录再次触发暂停。 ## 当前实现边界 -- 当前控制台面板自身很薄，大部分行为来自 action router 和 `EditorConsoleSink`。 -- 当前过滤状态存在面板实例内，不是全局日志视图配置对象。 +- 当前过滤和搜索状态完全保存在面板实例内，不是跨窗口共享配置。 +- source dropdown 当前仍是占位 UI： + - `Editor` 选项固定选中 + - `Player` 选项禁用 +- 主要渲染逻辑现在直接写在 `ConsolePanel.cpp` 中；[ConsoleActionRouter](../../Actions/ConsoleActionRouter/ConsoleActionRouter.md) 仍存在，但已不是控制台主渲染路径的唯一承载点。 +- 该面板依赖 [EditorConsoleSink](../../Core/EditorConsoleSink/EditorConsoleSink.md) 的内存日志快照，不是无限日志历史浏览器。 + +## 公开方法 + +| 方法 | 说明 | +|------|------| +| [Constructor](Constructor.md) | 创建名为 `"Console"` 的面板。 | +| [OnAttach](OnAttach.md) | 绑定上下文后的初始化与事件订阅。 | +| [OnDetach](OnDetach.md) | 注销 play mode 事件订阅。 | +| [Render](Render.md) | 绘制完整控制台 UI。 | ## 相关文档 - [panels](../panels.md) -- [Actions](../../Actions/Actions.md) +- [EditorConsoleSink](../../Core/EditorConsoleSink/EditorConsoleSink.md) +- [ConsoleFilterState](../../UI/ConsoleFilterState/ConsoleFilterState.md) +- [ConsoleActionRouter](../../Actions/ConsoleActionRouter/ConsoleActionRouter.md) - [UI](../../UI/UI.md) diff --git a/docs/api/XCEngine/Editor/panels/ConsolePanel/Constructor.md b/docs/api/XCEngine/Editor/panels/ConsolePanel/Constructor.md new file mode 100644 index 00000000..6d785888 --- /dev/null +++ b/docs/api/XCEngine/Editor/panels/ConsolePanel/Constructor.md @@ -0,0 +1,30 @@ +# ConsolePanel::Constructor + +**命名空间**: `XCEngine::Editor` + +**类型**: `method` + +**源文件**: `editor/src/panels/ConsolePanel.h` + +## 签名 + +```cpp +ConsolePanel(); +``` + +## 作用 + +构造 Console 面板实例。 + +## 当前实现行为 + +- 通过基类 `Panel("Console")` 把面板标题固定为 `"Console"`。 +- 其余状态主要依赖类成员默认初始化： + - `m_searchBuffer` 为空字符串 + - `m_selectedSerial`、revision 和各类 handler id 为 `0` + - play mode 标志默认关闭 + +## 相关文档 + +- [ConsolePanel](ConsolePanel.md) +- [OnAttach](OnAttach.md) diff --git a/docs/api/XCEngine/Editor/panels/ConsolePanel/OnAttach.md b/docs/api/XCEngine/Editor/panels/ConsolePanel/OnAttach.md new file mode 100644 index 00000000..c4109386 --- /dev/null +++ b/docs/api/XCEngine/Editor/panels/ConsolePanel/OnAttach.md @@ -0,0 +1,34 @@ +# ConsolePanel::OnAttach + +**命名空间**: `XCEngine::Editor` + +**类型**: `method` + +**源文件**: `editor/src/panels/ConsolePanel.h` + +## 签名 + +```cpp +void OnAttach() override; +``` + +## 作用 + +在面板拿到有效 `IEditorContext` 后初始化本地状态并订阅 play mode 事件。 + +## 当前实现行为 + +- 若 `m_context` 为空，直接返回。 +- 首次 attach 时会把 `m_detailsHeight` 初始化到 `UI::ConsoleDetailsDefaultHeight()`。 +- 读取 [EditorConsoleSink](../../Core/EditorConsoleSink/EditorConsoleSink.md) 当前 revision 和最新 serial，建立初始观察基线。 +- 仅当对应 handler id 仍为 `0` 时，才向 `EventBus` 订阅四类 play mode 事件，避免重复订阅： + - Started + - Stopped + - Paused + - Resumed + +## 相关文档 + +- [ConsolePanel](ConsolePanel.md) +- [OnDetach](OnDetach.md) +- [Render](Render.md) diff --git a/docs/api/XCEngine/Editor/panels/ConsolePanel/OnDetach.md b/docs/api/XCEngine/Editor/panels/ConsolePanel/OnDetach.md new file mode 100644 index 00000000..f24c1cbb --- /dev/null +++ b/docs/api/XCEngine/Editor/panels/ConsolePanel/OnDetach.md @@ -0,0 +1,28 @@ +# ConsolePanel::OnDetach + +**命名空间**: `XCEngine::Editor` + +**类型**: `method` + +**源文件**: `editor/src/panels/ConsolePanel.h` + +## 签名 + +```cpp +void OnDetach() override; +``` + +## 作用 + +在面板脱离上下文时注销 play mode 事件订阅。 + +## 当前实现行为 + +- 若 `m_context` 为空，直接返回。 +- 对四类 play mode 事件的 handler id 分别做判零检查。 +- 非零时调用 `EventBus::Unsubscribe<...>(handlerId)`，然后把对应 id 复位为 `0`。 + +## 相关文档 + +- [ConsolePanel](ConsolePanel.md) +- [OnAttach](OnAttach.md) diff --git a/docs/api/XCEngine/Editor/panels/ConsolePanel/Render.md b/docs/api/XCEngine/Editor/panels/ConsolePanel/Render.md new file mode 100644 index 00000000..d7ad16c1 --- /dev/null +++ b/docs/api/XCEngine/Editor/panels/ConsolePanel/Render.md @@ -0,0 +1,69 @@ +# ConsolePanel::Render + +**命名空间**: `XCEngine::Editor` + +**类型**: `method` + +**源文件**: `editor/src/panels/ConsolePanel.h` + +## 签名 + +```cpp +void Render() override; +``` + +## 作用 + +绘制控制台面板的完整 UI，并在运行时按需触发 error pause。 + +## 当前实现行为 + +### 1. 获取数据源与 revision + +- 使用 `UI::PanelWindowScope` 打开窗口。 +- 从 [EditorConsoleSink](../../Core/EditorConsoleSink/EditorConsoleSink.md) 读取当前日志记录和 revision。 +- sink 不可用时会直接显示 `"Console unavailable"` 的 empty state。 + +### 2. 扫描 error pause + +- 当处于 play mode、`ErrorPause` 打开且当前未暂停时，会扫描 `m_lastErrorPauseScanSerial` 之后新增的 `Error/Fatal` 日志。 +- 若发现新增错误，则通过 `EventBus` 发布 `PlayModePauseRequestedEvent`。 + +### 3. 构建可见行 + +- 用 [ConsoleFilterState](../../UI/ConsoleFilterState/ConsoleFilterState.md) 和 `SearchQuery` 过滤日志。 +- 非折叠模式下每条记录一行。 +- 折叠模式下会对重复日志聚合计数。 +- 同时维护当前选中项和键盘导航状态。 + +### 4. 绘制工具栏 + +当前工具栏包括： + +- `Clear` +- `Collapse` +- `Error Pause` +- source dropdown +- 搜索框 +- log / warning / error 数量按钮 + +### 5. 绘制列表与详情 + +- 上半区是带滚动和上下文菜单的日志列表。 +- 下半区是详情视图，显示完整消息、source location、thread、timestamp 和 occurrence count。 +- 双击列表项会尝试打开源码位置；失败时回退到复制完整内容。 + +### 6. 动作观察 + +- 渲染结束前会调用 `Actions::ObserveInactiveActionRoute(*m_context)`。 + +## 当前实现边界 + +- 目前 source dropdown 仍未真正接入 `Player` 日志源。 +- 大量交互 helper 仍直接实现在 `ConsolePanel.cpp` 内部匿名命名空间里。 + +## 相关文档 + +- [ConsolePanel](ConsolePanel.md) +- [ConsoleActionRouter](../../Actions/ConsoleActionRouter/ConsoleActionRouter.md) +- [EditorConsoleSink](../../Core/EditorConsoleSink/EditorConsoleSink.md) diff --git a/docs/api/XCEngine/Editor/panels/HierarchyPanel/Constructor.md b/docs/api/XCEngine/Editor/panels/HierarchyPanel/Constructor.md new file mode 100644 index 00000000..6de2947e --- /dev/null +++ b/docs/api/XCEngine/Editor/panels/HierarchyPanel/Constructor.md @@ -0,0 +1,30 @@ +# HierarchyPanel::Constructor + +**命名空间**: `XCEngine::Editor` + +**类型**: `method` + +**源文件**: `editor/src/panels/HierarchyPanel.h` + +## 签名 + +```cpp +HierarchyPanel(); +``` + +## 作用 + +构造 Hierarchy 面板实例。 + +## 当前实现行为 + +- 通过基类 `Panel("Hierarchy")` 把面板标题固定为 `"Hierarchy"`。 +- 其余 UI 状态依赖成员默认初始化： + - `m_renameState`、`m_treeState`、popup state 为空初始态 + - 事件 handler id 为 `0` + - `m_searchBuffer` 为空字符串 + +## 相关文档 + +- [HierarchyPanel](HierarchyPanel.md) +- [OnAttach](OnAttach.md) diff --git a/docs/api/XCEngine/Editor/panels/HierarchyPanel/HierarchyPanel.md b/docs/api/XCEngine/Editor/panels/HierarchyPanel/HierarchyPanel.md index 59da4945..136266ef 100644 --- a/docs/api/XCEngine/Editor/panels/HierarchyPanel/HierarchyPanel.md +++ b/docs/api/XCEngine/Editor/panels/HierarchyPanel/HierarchyPanel.md @@ -15,6 +15,7 @@ 按当前实现，这个面板主要负责： - 订阅选择变化与外部重命名请求事件。 +- 在工具栏中维护名称搜索输入。 - 读取 `ISceneManager` 提供的根实体列表。 - 基于 `UI::TreeView` 递归绘制场景对象树。 - 维护内联重命名状态。 @@ -22,6 +23,13 @@ 这和商业引擎编辑器的分层很一致：Hierarchy 面板负责“看见和触发”，而不是直接“改数据和执行业务命令”。 +## 生命周期 + +- [Constructor](Constructor.md) 会把面板标题固定为 `"Hierarchy"`。 +- [OnAttach](OnAttach.md) 会向 `EventBus` 订阅选择变化和重命名请求。 +- [OnDetach](OnDetach.md) 会取消这些订阅并清零 handler id。 +- [Render](Render.md) 会绘制工具栏、搜索框、实体树以及背景/实体上下文交互。 + ## 当前实现行为 按 `editor/src/panels/HierarchyPanel.cpp` 的实现： @@ -34,8 +42,10 @@ - 应用 `HierarchyInspectorPanelBackgroundColor()`。 - 通过 `PanelWindowScope` / `PanelContentScope` 建立标准面板外壳。 - 调用 `Actions::ObserveFocusedActionRoute(...)` 将当前焦点路由标记为 `Hierarchy`。 + - 在工具栏右侧绘制 `"Search"` 输入框，并用 `UI::SearchQuery` 构造过滤条件。 - 向 `ISceneManager` 读取根实体并逐个递归渲染。 - 在树绘制完成后处理背景点击、背景右键菜单、实体右键菜单和根级 drop target。 + - 搜索命中为空时绘制 `"No matching entities"` empty state。 ## 节点绘制模型 @@ -47,16 +57,25 @@ - `persistenceKey` 使用 `gameObject->GetUUID()` 转成字符串，保证展开状态在同一面板实例中稳定。 - `style` 使用 `UI::HierarchyTreeStyle()`。 - `prefix` 使用 `UI::NavigationTreePrefixWidth()` 和 `UI::DrawAssetIcon(..., AssetIconKind::GameObject)` 绘制对象图标。 +- 搜索启用时不写入持久化 key，而是让有子节点的对象默认展开，方便显示命中的后代节点。 这意味着当前 Hierarchy 的视觉和交互行为已经被统一纳入 Editor UI 基础设施，而不是面板自己手工维护整套树渲染细节。 +## 搜索与可见性 + +当前 `HierarchyPanel` 已经支持名称搜索，但它属于轻量过滤而不是完整查询系统： + +- 工具栏搜索框写入 `m_searchBuffer`。 +- `RenderEntity(...)` 会调用匿名 helper `HierarchyNodeMatchesSearch(...)`。 +- 匹配规则不仅检查当前实体名，也会递归检查后代；只要子树中存在命中，该祖先节点就会保留显示。 +- 搜索进行中时，节点展开状态不依赖常规 `m_treeState` 持久化键，而是让有子节点的对象默认展开。 + ## 交互行为 当前节点交互通过 `TreeNodeCallbacks` 接入： - 单击左键：调用 `Actions::HandleHierarchySelectionClick(...)`，支持结合 `Ctrl` 执行多选。 - 右键：调用 `Actions::HandleHierarchyItemContextRequest(...)` 打开目标实体上下文菜单。 -- 双击：调用 `BeginRename(...)` 进入内联重命名。 - 节点额外渲染阶段：调用 `Actions::BeginHierarchyEntityDrag(...)` 和 `Actions::AcceptHierarchyEntityDrop(...)` 接入拖放。 因此 `HierarchyPanel` 自己不直接执行“重排父子关系”之类操作，它只负责在正确的节点生命周期里提供 drop source / target 入口。 @@ -68,11 +87,10 @@ 当前行为是： - 外部若派发 `EntityRenameRequestedEvent`，面板会在 `OnRenameRequested(...)` 中找到实体并进入重命名。 -- 若用户双击树节点，也会进入重命名。 - 编辑过程中： - `Enter` 提交。 - `Escape` 取消。 - - 输入框失焦且用户左键点击其他位置时提交。 + - 输入框失活时提交。 - `CommitRename()` 最终通过 `Actions::CommitEntityRename(...)` 把改名请求发往动作层。 这类实现很像商业编辑器中的“inline rename controller”：面板持有输入框状态，但真正的实体改名仍然走统一命令路径。 @@ -95,11 +113,21 @@ ## 当前限制 -- 当前没有搜索、过滤、排序或大场景虚拟化能力。 +- 当前只有名称搜索，不支持按组件、Tag、Layer 或类型做更复杂过滤。 +- 当前没有排序或大场景虚拟化能力。 - 展开状态只保存在 `UI::TreeViewState` 的内存态中，不会自动写入布局文件。 - 重命名输入框是替换式绘制，不是“树节点原位嵌入子控件”的更复杂实现。 - 目前只为每个节点提供统一的 `GameObject` 图标前缀，没有按组件类型做更细粒度图标区分。 +## 公开方法 + +| 方法 | 说明 | +|------|------| +| [Constructor](Constructor.md) | 创建名为 `"Hierarchy"` 的面板。 | +| [OnAttach](OnAttach.md) | 订阅选择变化和重命名请求。 | +| [OnDetach](OnDetach.md) | 注销事件订阅。 | +| [Render](Render.md) | 绘制搜索栏、层级树和上下文交互。 | + ## 相关文档 - [panels](../panels.md) diff --git a/docs/api/XCEngine/Editor/panels/HierarchyPanel/OnAttach.md b/docs/api/XCEngine/Editor/panels/HierarchyPanel/OnAttach.md new file mode 100644 index 00000000..6da6d924 --- /dev/null +++ b/docs/api/XCEngine/Editor/panels/HierarchyPanel/OnAttach.md @@ -0,0 +1,32 @@ +# HierarchyPanel::OnAttach + +**命名空间**: `XCEngine::Editor` + +**类型**: `method` + +**源文件**: `editor/src/panels/HierarchyPanel.h` + +## 签名 + +```cpp +void OnAttach() override; +``` + +## 作用 + +在面板拥有有效 `IEditorContext` 后订阅层级树相关 editor 事件。 + +## 当前实现行为 + +- 若 `m_context` 为空，直接返回。 +- 若 `m_selectionHandlerId` 或 `m_renameRequestHandlerId` 已非 `0`，说明已经 attach 过，本次不会重复订阅。 +- 当前会向 `EventBus` 订阅两类事件： + - `SelectionChangedEvent` + - `EntityRenameRequestedEvent` +- 两个订阅最终分别回调到 `OnSelectionChanged(...)` 与 `OnRenameRequested(...)`。 + +## 相关文档 + +- [HierarchyPanel](HierarchyPanel.md) +- [OnDetach](OnDetach.md) +- [Render](Render.md) diff --git a/docs/api/XCEngine/Editor/panels/HierarchyPanel/OnDetach.md b/docs/api/XCEngine/Editor/panels/HierarchyPanel/OnDetach.md new file mode 100644 index 00000000..4e135474 --- /dev/null +++ b/docs/api/XCEngine/Editor/panels/HierarchyPanel/OnDetach.md @@ -0,0 +1,29 @@ +# HierarchyPanel::OnDetach + +**命名空间**: `XCEngine::Editor` + +**类型**: `method` + +**源文件**: `editor/src/panels/HierarchyPanel.h` + +## 签名 + +```cpp +void OnDetach() override; +``` + +## 作用 + +在面板脱离上下文时取消事件订阅。 + +## 当前实现行为 + +- 若 `m_context` 为空，直接返回。 +- 若 `m_selectionHandlerId` 非 `0`，则从 `EventBus` 注销 `SelectionChangedEvent` 订阅并清零。 +- 若 `m_renameRequestHandlerId` 非 `0`，则从 `EventBus` 注销 `EntityRenameRequestedEvent` 订阅并清零。 +- 该函数不重置树展开状态、搜索内容或 rename buffer；这些仍属于面板实例内存状态。 + +## 相关文档 + +- [HierarchyPanel](HierarchyPanel.md) +- [OnAttach](OnAttach.md) diff --git a/docs/api/XCEngine/Editor/panels/HierarchyPanel/Render.md b/docs/api/XCEngine/Editor/panels/HierarchyPanel/Render.md new file mode 100644 index 00000000..f0308c71 --- /dev/null +++ b/docs/api/XCEngine/Editor/panels/HierarchyPanel/Render.md @@ -0,0 +1,57 @@ +# HierarchyPanel::Render + +**命名空间**: `XCEngine::Editor` + +**类型**: `method` + +**源文件**: `editor/src/panels/HierarchyPanel.h` + +## 签名 + +```cpp +void Render() override; +``` + +## 作用 + +绘制层级面板的完整 UI，包括搜索栏、实体树、空状态和上下文交互。 + +## 当前实现行为 + +### 1. 建立面板外壳 + +- 先压入 `HierarchyInspectorPanelBackgroundColor()` 到 `ImGuiCol_WindowBg` 和 `ImGuiCol_ChildBg`。 +- 进入 `UI::PanelWindowScope`；若窗口当前关闭，则提前返回。 +- 调用 `Actions::ObserveFocusedActionRoute(*m_context, EditorActionRoute::Hierarchy)` 标记焦点路由。 + +### 2. 绘制工具栏搜索 + +- 用 `UI::PanelToolbarScope` 创建顶部工具栏。 +- 当前工具栏布局主要保留一个右侧固定宽度搜索框： + - widget id 为 `"##HierarchySearch"` + - 占位文本为 `"Search"` +- 搜索内容写入 `m_searchBuffer`。 + +### 3. 绘制实体树 + +- 用 `UI::PanelContentScope` 打开主体内容区。 +- 从 `ISceneManager` 读取根实体数组。 +- 以 `m_searchBuffer` 构造 `UI::SearchQuery`，然后逐个调用 `RenderEntity(...)` 递归绘制。 +- 若搜索非空但没有任何可见实体，则显示 `"No matching entities"` empty state。 + +### 4. 处理背景与菜单 + +- 调用 `Actions::DrawHierarchyBackgroundInteraction(*m_context, m_renameState)` 处理背景点击和根级 drop target。 +- 调用 `Actions::DrawHierarchyEntityContextPopup(*m_context, m_itemContextMenu)` 处理实体右键菜单。 +- 若背景 surface 打开上下文菜单，则通过 `Actions::DrawHierarchyContextActions(*m_context, nullptr, true)` 绘制背景菜单项。 + +## 当前实现边界 + +- `Render()` 只负责视图状态与交互编排，不直接修改场景数据。 +- 实体选择、重命名提交、拖放重挂接和上下文菜单动作主要仍由 [HierarchyActionRouter](../../Actions/HierarchyActionRouter/HierarchyActionRouter.md) 负责。 + +## 相关文档 + +- [HierarchyPanel](HierarchyPanel.md) +- [HierarchyActionRouter](../../Actions/HierarchyActionRouter/HierarchyActionRouter.md) +- [TreeView](../../UI/TreeView/TreeView.md) diff --git a/docs/api/XCEngine/Editor/panels/InspectorPanel/Constructor.md b/docs/api/XCEngine/Editor/panels/InspectorPanel/Constructor.md new file mode 100644 index 00000000..0eb4e992 --- /dev/null +++ b/docs/api/XCEngine/Editor/panels/InspectorPanel/Constructor.md @@ -0,0 +1,45 @@ +# InspectorPanel::InspectorPanel + +**命名空间**: `XCEngine::Editor` + +**类型**: `constructor` + +**源文件**: `editor/src/panels/InspectorPanel.h` + +## 签名 + +```cpp +InspectorPanel(); +``` + +## 作用 + +创建标题固定为 `"Inspector"` 的检查器面板。 + +## 当前实现行为 + +当前构造函数非常薄： + +```cpp +InspectorPanel::InspectorPanel() : Panel("Inspector") {} +``` + +它只负责： + +- 通过基类 `Panel` 设置窗口标题 + +其余状态都由成员默认值完成初始化，例如： + +- `m_subjectMode = None` +- `m_lastExplicitRoute = None` +- `m_selectedEntityId = 0` +- `m_selectedAssetItem` +- `m_selectedMaterial` +- `m_materialAssetState` +- `m_addComponentPopup` + +## 相关文档 + +- [InspectorPanel](InspectorPanel.md) +- [OnAttach](OnAttach.md) +- [Render](Render.md) diff --git a/docs/api/XCEngine/Editor/panels/InspectorPanel/InspectorPanel.md b/docs/api/XCEngine/Editor/panels/InspectorPanel/InspectorPanel.md index 34c35b86..e32d628b 100644 --- a/docs/api/XCEngine/Editor/panels/InspectorPanel/InspectorPanel.md +++ b/docs/api/XCEngine/Editor/panels/InspectorPanel/InspectorPanel.md @@ -6,36 +6,275 @@ **源文件**: `editor/src/panels/InspectorPanel.h` -**描述**: 检查器面板，负责显示当前选中对象的组件列表，并通过 `ComponentEditorRegistry` 渲染对应组件编辑 UI。 +**描述**: 检查器面板，负责在 `GameObject`、材质资源、未支持资源和空状态之间切换，并把当前 subject 渲染成组件编辑器 UI 或资源属性 UI。 ## 概述 -`InspectorPanel` 是组件编辑系统的主要承载面板。 +旧版本的描述很容易把 `InspectorPanel` 写成“只显示当前实体组件列表”的面板，但这已经不准确。 -它当前的工作流是： +按当前实现，它是一个带 subject 解析逻辑的通用检查器。它会综合： -1. 订阅选择变化。 -2. 根据当前选中实体拿到 `GameObject`。 -3. 遍历其组件。 -4. 通过 `ComponentEditorRegistry` 找到对应的 `IComponentEditor`。 -5. 渲染每个组件 section。 +- 当前 `SelectionManager` 主选中实体 +- `EditorActionRoute` +- `ProjectManager` 当前选中资源 -## 当前实现说明 +来决定本帧到底应该检查什么。 -- 没有选中对象时会显示 empty state。 -- 若选中对象已失效，也会显示 empty state。 -- `RenderGameObject()` 里会绘制 Add Component 按钮和弹窗。 -- 若某个组件没有已注册 editor，会显示提示文本。 -- 组件 editor 返回 `true` 时，当前会标记场景为 dirty。 +因此它当前至少承担了两类职责： -## 当前实现边界 +- Scene 对象检查器 +- 资源检查器前端 -- 当前 Inspector 完全依赖组件 editor 注册表，不是基于反射自动生成 UI。 -- 组件 section 的移除、添加和交互式编辑配合主要通过 `Actions` 层完成。 +## 生命周期与公开入口 + +- [Constructor](Constructor.md) + 创建标题固定为 `"Inspector"` 的检查器面板实例。 +- [OnAttach](OnAttach.md) + 绑定上下文后订阅 `SelectionChangedEvent`，建立当前 scene selection 基线。 +- [OnDetach](OnDetach.md) + 注销选择变化事件订阅，避免悬挂 handler。 +- [Render](Render.md) + 解析当前 subject，并在 `GameObject / MaterialAsset / UnsupportedAsset / None` 之间切换渲染路径。 + +## Subject 模式 + +`InspectorPanel` 当前通过 `SubjectMode` 明确区分四种模式。 + +| 模式 | 触发条件 | 当前行为 | +|------|------|------| +| `None` | 没有有效检查目标 | 显示 empty state | +| `GameObject` | route 偏向 `Hierarchy`，且有有效实体 | 渲染组件列表与 `Add Component` | +| `MaterialAsset` | route 偏向 `Project`，且选中资源类型为 `Material` | 渲染材质资源属性编辑 UI | +| `UnsupportedAsset` | route 偏向 `Project`，但当前资源没有专用 inspector | 显示资源名、资源类型和 fallback 提示 | + +这也是它和旧版 Unity 风格“永远盯住当前实体”的 Inspector 最大区别。 + +## 生命周期 + +### [OnAttach()](OnAttach.md) + +挂接时会： + +- 订阅 `SelectionChangedEvent` +- 记录当前主选中实体 id + +这样即使 Inspector 本身不是选择发起方，也能在后续帧里同步 scene selection。 + +### [OnDetach()](OnDetach.md) + +卸载时会： + +- 从 [EventBus](../../Core/EventBus/EventBus.md) 取消 `SelectionChangedEvent` 订阅 + +### `OnSelectionChanged(...)` + +收到选择变化后，当前逻辑不是自己直接重建全部 UI，而是： + +1. 调用 `Actions::HandleInspectorSelectionChanged(...)` +2. 更新 `m_selectedEntityId` +3. 若存在 `primarySelection`，把最近一次显式 route 记为 `Hierarchy` + +这意味着 Inspector 的选择同步和弹窗状态管理，已经和 `Actions` 层形成协作，而不是孤立面板逻辑。 + +## Subject 决策流程 + +`SyncSubject()` 是当前文件最重要的入口之一。 + +它的决策顺序大致是： + +1. 读取 `m_context->GetActiveActionRoute()` +2. 若 route 不是 `None`，更新 `m_lastExplicitRoute` +3. 若最近显式 route 是 `Project` + - 读取 `ProjectManager::GetSelectedItem()` + - 若 `type == "Material"`，进入 `MaterialAsset` + - 若有选中资源但没有专用 inspector，进入 `UnsupportedAsset` + - 若没有选中资源，进入 `None` +4. 否则若 route 偏向 `Hierarchy` 或仍有有效选中实体 + - 从 `SceneManager` 取 `GameObject` + - 成功则进入 `GameObject` +5. 其余情况进入 `None` + +这套规则解释了一个很重要的实际体验： + +- 当前 Inspector 在 Project 和 Hierarchy 之间是“焦点敏感”的。 +- Project 资源检查优先级可以盖过 scene entity 检查。 + +## GameObject 模式 + +### 主流程 + +`RenderGameObject(...)` 当前会： + +1. 建立 `PanelContentScope` +2. 拉取 `gameObject->GetComponents()` +3. 逐个调用 `RenderComponent(...)` +4. 在底部绘制 `Add Component` 按钮和弹窗 +5. 调用 `FinalizeInspectorInteractiveChangeIfIdle(...)` +6. 在本帧末执行 deferred context action + +### 组件绘制 + +`RenderComponent(...)` 的路径是： + +1. 用 `ComponentEditorRegistry::Get().FindEditor(component)` 查找专用 editor +2. 取 display name +3. 用 `UI::BeginComponentSection(...)` 绘制 section header +4. 为该 section 挂接组件上下文菜单 +5. 若 section 展开且当前没有 deferred action + - 调用具体 `IComponentEditor::Render(...)` + - 返回 `true` 时标记场景 dirty +6. 收尾 `UI::EndComponentSection(...)` + +当前这一支已经明确是“注册表驱动的专用 inspector”，而不是“把所有组件字段用反射自动铺成表单”。 + +### 脚本组件 + +当前 `ScriptComponent` 已经通过 [ScriptComponentEditor](../../ComponentEditors/ScriptComponentEditor/ScriptComponentEditor.md) 接入这里。 + +因此 GameObject 模式下的 Inspector 已经支持： + +- 脚本类选择 +- 脚本字段展示 +- 字段 override 重置 +- 运行时缺失时的错误提示与脚本重建入口 + +把它继续描述为“还没有脚本组件 inspector”是不准确的。 + +### Deferred action + +组件右键菜单相关操作不会在遍历组件列表时立刻改场景，而是写入 `m_deferredContextAction`，在本帧组件渲染结束后再执行。 + +这么做的原因很实际： + +- 即时模式 UI 遍历期间避免直接破坏当前组件列表 +- 降低删除组件、重排组件或打开弹窗时的迭代风险 + +## Material 资源模式 + +这是当前文件里相对较新的能力，也是旧文档最容易过时的部分。 + +### 进入条件 + +只有当： + +- 最近显式 route 是 `Project` +- `ProjectManager::GetSelectedItem()` 存在 +- `item->type == "Material"` + +时，Inspector 才会进入 `MaterialAsset` 模式。 + +### 资源加载 + +`InspectMaterialAsset(...)` 和 `ReloadMaterialAsset()` 会： + +1. 把磁盘全路径转换成项目相对路径 +2. 使用 `ResourceManager::Load()` 加载资源 +3. 从已加载 `Material` 里提取当前状态，填充 `MaterialAssetState` + +缓存的内容包括： + +- `shaderPath` +- `shaderPass` +- `renderQueue` +- `renderState` +- `tags` +- 错误消息 + +### 编辑内容 + +当前可编辑的 section 包括： + +- `Material` + - Shader 资源引用 + - Pass 名 + - Render Queue 预设或自定义值 +- `Render State` + - Cull + - Depth Test / Write + - Depth Func + - Blend 相关因子与操作 + - Color Write Mask +- `Tags` + - 增删 tag + - 编辑键值对 + +Shader 资源选择还会通过 inspector 侧资源引用选择器限制扩展名集合。 + +### 保存语义 + +这一支当前不是“先改内存，最后统一 Apply”模型，而是边改边保存： + +1. 任意字段变化后把 `m_materialAssetState.dirty = true` +2. 立即调用 `SaveMaterialAsset()` +3. 覆盖写回磁盘材质文件 +4. 若资源句柄有效，则把修改同步应用到已加载 `Material` 实例 + +这意味着当前材质资源检查器更接近直接编辑器，而不是带 staging 的事务型 inspector。 + +### 错误与退化行为 + +若材质文件为空、无效或当前资源不可用： + +- Inspector 不会直接崩溃 +- 会记录错误消息 +- 仍尽量显示默认值或 fallback 提示 + +## Unsupported 资源模式 + +若当前 route 是 `Project`，但选中的资源没有专用 inspector： + +- Inspector 会显示资源名 +- 显示 `item->type` +- 提示 “This asset type does not have a dedicated inspector yet.” + +这说明当前资源检查器体系并不是空白，而是明确采用了“逐种资源补专用 inspector”的扩展方式。 + +## 空状态与模式切换 + +`SetSubjectMode(...)` 有两个值得文档明确写出的语义： + +- 若从 `MaterialAsset` 切走，且材质状态仍为 dirty，会先自动保存 +- 若切到非材质模式，会清空材质缓存和资源句柄 + +因此当前 Inspector 在模式切换上已经具有最基本的一致性保证，而不是简单地每帧盲目重建所有缓存。 + +## 设计说明 + +当前 `InspectorPanel` 的设计取向可以概括成三点： + +- 用 `EditorActionRoute` 决定“现在是谁拥有检查焦点” +- 用 `ComponentEditorRegistry` 解决 scene component 的专用编辑 UI +- 用专门的 subject 分支逐步接入资源 inspector + +这种结构比“只有 GameObject inspector”更复杂，但也更接近当前 editor 已经具备的真实能力。 + +## 测试与验证锚点 + +和当前 Inspector 直接相关的行为锚点主要分布在： + +- `tests/Editor/test_script_component_editor_utils.cpp` +- `tests/Scripting/test_script_engine.cpp` +- `tests/Scripting/test_mono_script_runtime.cpp` + +这些测试并不直接覆盖整个 `InspectorPanel` UI，但覆盖了它依赖的脚本字段模型、运行时缺失提示和字段状态解释逻辑。 + +## 当前限制 + +- 当前专用资源 inspector 只覆盖 `Material`。 +- 当前没有多对象联合检查和 mixed-value 语义。 +- `EditorActionRoute` 只有 `Hierarchy` 和 `Project` 两条显式来源，焦点模型仍然偏轻量。 +- 材质编辑当前是立即写回模式，没有 `Apply/Revert` staging。 +- Unsupported 资源目前只有 fallback 提示，没有通用元数据面板。 ## 相关文档 +- [Constructor](Constructor.md) +- [OnAttach](OnAttach.md) +- [OnDetach](OnDetach.md) +- [Render](Render.md) - [panels](../panels.md) -- [IComponentEditor](../../ComponentEditors/IComponentEditor/IComponentEditor.md) +- [ComponentEditors](../../ComponentEditors/ComponentEditors.md) - [ComponentEditorRegistry](../../ComponentEditors/ComponentEditorRegistry/ComponentEditorRegistry.md) -- [SceneManager](../../Managers/SceneManager/SceneManager.md) +- [ScriptComponentEditor](../../ComponentEditors/ScriptComponentEditor/ScriptComponentEditor.md) +- [ProjectPanel](../ProjectPanel/ProjectPanel.md) +- [EventBus](../../Core/EventBus/EventBus.md) diff --git a/docs/api/XCEngine/Editor/panels/InspectorPanel/OnAttach.md b/docs/api/XCEngine/Editor/panels/InspectorPanel/OnAttach.md new file mode 100644 index 00000000..c8f2eb0d --- /dev/null +++ b/docs/api/XCEngine/Editor/panels/InspectorPanel/OnAttach.md @@ -0,0 +1,41 @@ +# InspectorPanel::OnAttach + +**命名空间**: `XCEngine::Editor` + +**类型**: `method` + +**源文件**: `editor/src/panels/InspectorPanel.h` + +## 签名 + +```cpp +void OnAttach() override; +``` + +## 作用 + +在面板拿到有效 `IEditorContext` 后，订阅选择变化事件并同步当前主选中实体。 + +## 当前实现行为 + +当前 `OnAttach()` 会： + +1. 若 `m_context == nullptr`，直接返回 +2. 把 `m_selectedEntityId` 初始化为 `SelectionManager::GetSelectedEntity()` +3. 仅当 `m_selectionHandlerId == 0` 时，向 `EventBus` 订阅 `SelectionChangedEvent` + +收到事件后，真正的选择同步逻辑会落到 `OnSelectionChanged(...)`，而不是在订阅 lambda 里直接重建所有 UI。 + +## 设计含义 + +这让 Inspector 即使不是选择动作的发起方，也能在后续帧里跟随： + +- Hierarchy 选择变化 +- 其他动作路由引发的主选中切换 + +## 相关文档 + +- [InspectorPanel](InspectorPanel.md) +- [OnDetach](OnDetach.md) +- [Render](Render.md) +- [EventBus](../../Core/EventBus/EventBus.md) diff --git a/docs/api/XCEngine/Editor/panels/InspectorPanel/OnDetach.md b/docs/api/XCEngine/Editor/panels/InspectorPanel/OnDetach.md new file mode 100644 index 00000000..7425b652 --- /dev/null +++ b/docs/api/XCEngine/Editor/panels/InspectorPanel/OnDetach.md @@ -0,0 +1,35 @@ +# InspectorPanel::OnDetach + +**命名空间**: `XCEngine::Editor` + +**类型**: `method` + +**源文件**: `editor/src/panels/InspectorPanel.h` + +## 签名 + +```cpp +void OnDetach() override; +``` + +## 作用 + +注销 Inspector 挂接期间注册的选择变化事件订阅。 + +## 当前实现行为 + +当前实现会： + +- 检查 `m_context` 和 `m_selectionHandlerId` +- 若二者都有效，则通过 `EventBus::Unsubscribe(...)` 取消订阅 +- 最后把 `m_selectionHandlerId` 复位为 `0` + +## 设计含义 + +这一步很关键，因为 `InspectorPanel` 的 subject 解析强依赖外部选择变化。如果不在 detach 时显式解除订阅，就会留下悬挂 handler。 + +## 相关文档 + +- [InspectorPanel](InspectorPanel.md) +- [OnAttach](OnAttach.md) +- [EventBus](../../Core/EventBus/EventBus.md) diff --git a/docs/api/XCEngine/Editor/panels/InspectorPanel/Render.md b/docs/api/XCEngine/Editor/panels/InspectorPanel/Render.md new file mode 100644 index 00000000..705e94c6 --- /dev/null +++ b/docs/api/XCEngine/Editor/panels/InspectorPanel/Render.md @@ -0,0 +1,85 @@ +# InspectorPanel::Render + +**命名空间**: `XCEngine::Editor` + +**类型**: `method` + +**源文件**: `editor/src/panels/InspectorPanel.h` + +## 签名 + +```cpp +void Render() override; +``` + +## 作用 + +解析当前 Inspector subject，并按不同模式渲染： + +- `GameObject` +- `MaterialAsset` +- `UnsupportedAsset` +- `None` + +## 当前实现行为 + +### 1. 同步 subject + +当前 `Render()` 一开始会先调用： + +```cpp +SyncSubject(); +``` + +这一步会结合： + +- `EditorActionRoute` +- scene selection +- Project 当前选中资源 + +决定本帧 Inspector 应该检查什么。 + +### 2. 打开面板窗口 + +然后会进入 `UI::PanelWindowScope`。若窗口当前未打开，直接返回，不继续执行后续 subject 渲染。 + +### 3. 按模式分发 + +当前主体逻辑是按 `m_subjectMode` 分发： + +- `GameObject` + - 调用 `RenderGameObject(...)` +- `MaterialAsset` + - 调用 `RenderMaterialAsset()` +- `UnsupportedAsset` + - 调用 `RenderUnsupportedAsset()` +- `None` + - 调用 `RenderEmptyState(...)` + +这说明 Inspector 当前不是单一路径组件列表，而是一个真正的 subject router。 + +### 4. Material 模式切换保护 + +`Render()` 自己虽然不直接写磁盘，但它依赖 `SetSubjectMode(...)` 保证一个重要语义： + +- 从 `MaterialAsset` 切走前，若当前材质状态仍为 dirty，会先尝试保存 + +因此当前 Inspector 模式切换已经具备基本的一致性保护，而不是简单清空状态。 + +## 设计含义 + +`Render()` 的核心职责不是“画一堆控件”，而是“根据当前 editor 焦点和 subject 决定该画哪一套 inspector”。这也是它能同时承载： + +- Scene component inspector +- Material asset inspector +- Unsupported asset fallback + +的原因。 + +## 相关文档 + +- [InspectorPanel](InspectorPanel.md) +- [OnAttach](OnAttach.md) +- [OnDetach](OnDetach.md) +- [ProjectPanel](../ProjectPanel/ProjectPanel.md) +- [ComponentEditors](../../ComponentEditors/ComponentEditors.md) diff --git a/docs/api/XCEngine/Editor/panels/SceneViewPanel/Render.md b/docs/api/XCEngine/Editor/panels/SceneViewPanel/Render.md index c72b8e26..12e6fec0 100644 --- a/docs/api/XCEngine/Editor/panels/SceneViewPanel/Render.md +++ b/docs/api/XCEngine/Editor/panels/SceneViewPanel/Render.md @@ -14,103 +14,46 @@ void Render() override; ## 作用 -绘制并驱动完整的 Scene View：工具栏、工具切换、视口交互、对象选择、相机导航、transform gizmo 拖拽，以及 gizmo overlay state 提交与 HUD 绘制。 +渲染 Scene View 面板，并在同一帧内完成： + +- Scene viewport 内容请求 +- toolbar / tool overlay 更新 +- Scene View hover / click 解析 +- transform gizmo 生命周期推进 +- editor camera 导航输入提交 +- HUD / gizmo presentation 刷新 ## 当前实现行为 -### 1. 工具栏与视口表面 +按 `editor/src/panels/SceneViewPanel.cpp` 的当前实现，这个方法会依次执行： -当前会先： +1. 先渲染顶部 toolbar，并更新 `pivotMode / transformSpaceMode`。 +2. 再通过 `RenderViewportPanelContent(...)` 请求 Scene 视口纹理与交互表面。 +3. 若存在 `IViewportHostService`，则渲染左侧工具按钮 overlay，并把按钮点击与快捷键折叠成 `SceneViewportToolCommand`。 +4. 通过 `ExecuteSceneViewportToolCommand(...)` 切换 `m_toolMode`，必要时先取消当前 gizmo 拖拽。 +5. 基于 `m_toolMode / m_pivotMode / m_transformSpaceMode` 构造 `SceneViewportToolState`，并把 viewport 尺寸与鼠标位置组装成 `SceneViewportFrameGeometry`。 +6. 调用 `BuildSceneViewportInteractionFrameState(...)`，刷新 gizmo frame、提交 gizmo overlay state，并取回当前 canonical `SceneViewportOverlayFrameData`。 +7. 在允许交互解析时，调用 `ResolveSceneViewportInteraction(...)` 获取 hovered interaction，再把结果折叠成 `SceneViewportInteractionActions`。 +8. 用 `ApplySceneViewportHoveredHandleState(...)` 更新 move / rotate / scale gizmo 的 hovered state。 +9. 通过 `UpdateSceneViewportNavigationState(...)` 更新 look / pan 状态，再调用 `ShouldFocusSceneViewportAfterInteraction(...)` 决定本帧是否需要 `ImGui::SetWindowFocus()`。 +10. 先执行 `BuildBeginSceneViewportTransformGizmoLifecycleCommand(...)` 产出的 begin 命令，再分发交互动作。 +11. 再执行 `BuildFrameSceneViewportTransformGizmoLifecycleCommand(...)` 产出的 frame 命令，推进 gizmo update / end。 +12. 构造 `SceneViewportCaptureFlags`，必要时请求 ImGui 在下一帧捕获鼠标或键盘。 +13. 构造 `SceneViewportInput`，并提交给 `IViewportHostService::UpdateSceneViewInput(...)` 以驱动 editor camera。 +14. 最后通过 `RefreshAndDrawSceneViewportPresentation(...)` 对齐最新 gizmo frame，并绘制 HUD overlay。 +15. 面板尾部调用 `Actions::ObserveInactiveActionRoute(*m_context)`，维持动作路由状态。 -- 绘制顶部 `Pivot / Center`、`Global / Local` toolbar -- 调用 `RenderViewportPanelContent(...)` 申请 `Scene` 视口纹理 -- 绘制左侧工具条，并处理 `Q/W/E/R` 快捷键 +## 当前边界 -如果工具切换发生，还会先取消当前活动 gizmo 的拖拽状态，避免旧工具继续持有输入。 - -### 2. 首次刷新 gizmo 上下文 - -当视口可交互时，会先读取： - -- `viewportHostService->GetSceneViewOverlayData()` - -然后调用 `RefreshSceneViewportTransformGizmos(...)`，按当前： - -- selection -- pivot mode -- transform space -- tool mode -- 鼠标位置 - -生成 move / rotate / scale 三套 gizmo context。 - -### 3. 命中仲裁 - -当前命中流程不是直接点击某个控件，而是先： - -1. 用 `BuildSceneViewportTransformGizmoHandleBuildInputs(...)` 组装本帧 gizmo 输入 -2. 用 `BuildSceneViewportTransformGizmoOverlayState(...)` 构造当前帧 gizmo state -3. 先调用 `SetSceneViewTransformGizmoOverlayState(...)` -4. 再从 `GetSceneViewEditorOverlayFrameData(...)` 拿到“editor overlay + gizmo handle”合成帧数据 -5. 用 `ResolveSceneViewportInteraction(...)` 做 overlay / orientation gizmo 的统一命中仲裁 - -这一步最终会决定当前左键点击到底落到： - -- transform gizmo -- orientation gizmo -- scene icon -- object-id picking 回退路径 - -### 4. 选择、拖拽与导航 - -命中结果解析完成后，当前实现会： - -- 命中 gizmo 时调用 `TryBeginDrag(...)` -- 命中 orientation gizmo 时调用 `AlignSceneViewToOrientationAxis(...)` -- 命中 scene icon 时直接改选中对象 -- 都没命中时调用 `PickSceneViewEntity(...)` - -导航侧则会维护： - -- 右键 look -- 中键或 `ViewMove` 左键 pan -- `WASDQE` 飞行 -- `F` focus selection - -并把这些状态整理成 `SceneViewportInput` 回传给 `UpdateSceneViewInput(...)`。 - -### 5. 提交最终 gizmo state 并绘制 HUD - -当视口图像存在时，当前实现会再次刷新一次 gizmo 上下文，然后： - -1. 重新用 `BuildSceneViewportTransformGizmoHandleBuildInputs(...)` 组装最新 gizmo 输入 -2. 再次调用 `SetSceneViewTransformGizmoOverlayState(...)` -3. 最后调用 `DrawSceneViewportHudOverlay(...)` 绘制前端 HUD / orientation gizmo - -这里的关键点是：第二次写回 gizmo state 后，真正的 Scene View render path 还没跑。后续 `ViewportHostService::RenderRequestedViewports(...)` 会感知 overlay cache 已变脏，并按最新 gizmo state 重建 overlay frame data，再交给 `SceneViewportEditorOverlayPass`。 - -也就是说，transform gizmo 的最终出图已经不再走独立的 transient overlay API，而是走“提交 gizmo state -> 宿主服务重建合成 frame data -> overlay pass 渲染”的主路径。 - -### 6. 动作观察 - -渲染末尾会调用： - -```cpp -Actions::ObserveInactiveActionRoute(*m_context); -``` - -保证该面板即使没有显式激活 action route，也能继续参与统一动作观察。 - -## 当前实现边界 - -- orbit 输入当前仍固定为 `false` -- `Transform` 组合工具下的 scale 仍是 `uniformOnly` -- `Render()` 仍然承担大量交互编排职责，因此它更像 Scene View 壳层主流程，而不是单纯 UI 绘制函数 +- 该方法不直接构建底层 `screenTriangles / handleRecords`；这部分已下沉到 `SceneViewportOverlayHandleBuilder` 与 provider 链。 +- 该方法不直接持有 render target，也不直接执行 Scene / Game 视口渲染。 +- 该方法负责 orchestration，不负责定义 gizmo 几何或 overlay provider 契约本身。 ## 相关文档 - [SceneViewPanel](SceneViewPanel.md) -- [Constructor](Constructor.md) -- [ViewportPanelContent](../ViewportPanelContent/ViewportPanelContent.md) -- [IViewportHostService](../../Viewport/IViewportHostService/IViewportHostService.md) -- [SceneView Interaction And Gizmo Model](../../../../_guides/Editor/SceneView-Interaction-And-Gizmo-Model.md) +- [SceneViewportChrome](../../Viewport/SceneViewportChrome/SceneViewportChrome.md) +- [SceneViewportInteractionFrame](../../Viewport/SceneViewportInteractionFrame/SceneViewportInteractionFrame.md) +- [SceneViewportNavigation](../../Viewport/SceneViewportNavigation/SceneViewportNavigation.md) +- [SceneViewportTransformGizmoCoordinator](../../Viewport/SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoCoordinator.md) +- [SceneViewportInteractionActions](../../Viewport/SceneViewportInteractionActions/SceneViewportInteractionActions.md) diff --git a/docs/api/XCEngine/Editor/panels/SceneViewPanel/SceneViewPanel.md b/docs/api/XCEngine/Editor/panels/SceneViewPanel/SceneViewPanel.md index ca0e568e..3e32ab42 100644 --- a/docs/api/XCEngine/Editor/panels/SceneViewPanel/SceneViewPanel.md +++ b/docs/api/XCEngine/Editor/panels/SceneViewPanel/SceneViewPanel.md @@ -6,246 +6,62 @@ **源文件**: `editor/src/panels/SceneViewPanel.h` -**描述**: 编辑器 Scene View 面板，负责场景视口 UI、工具栏与工具叠层、对象选择、相机导航，以及 transform gizmo 的交互编排与 overlay 接线。 +**描述**: Scene 视口面板。它持有 Scene View 当前的工具模式、pivot 模式、空间模式、导航状态和三类 transform gizmo，并把 UI chrome、交互解析、导航输入与 viewport 宿主服务串成一条完整的编辑器视口链路。 ## 概述 -`SceneViewPanel` 是当前 Editor 里最像商业级场景视图壳层的面板之一。按 `SceneViewPanel.cpp` 的真实实现，它把以下链路编排到同一帧里： - -- 顶部 `Pivot / Center` 与 `Global / Local` 切换。 -- 左侧 `ViewMove / Move / Rotate / Scale / Transform` 工具条。 -- Scene 视口纹理申请与交互表面建立。 -- scene icon、orientation gizmo、transform gizmo 与空白区域 picking 的命中仲裁。 -- look / pan / fly / focus-selection 输入回传。 -- transform gizmo 的绘制、命中、拖拽和撤销事务。 - -`SceneViewPanel` 自己不持有 render target，也不直接做 object-id 读回或 `SceneRenderer` 调用；这些都通过 [IViewportHostService](../../Viewport/IViewportHostService/IViewportHostService.md) 完成。它的职责更准确地说是交互编排层。 - -## 生命周期与公开入口 - -- [Constructor](Constructor.md) - 创建标题固定为 `"Scene"` 的面板实例，并保留 Scene View 运行期私有状态。 -- [Render](Render.md) - 执行完整的 Scene View 工具栏、命中仲裁、导航输入、gizmo 拖拽与 overlay 提交流程。 - -## 当前帧执行链路 - -`Render()` 当前不是简单的 ImGui 绘制，而是按下面的顺序组织 Scene View： - -1. 绘制顶部 Scene toolbar。 -2. 调用 [ViewportPanelContent](../ViewportPanelContent/ViewportPanelContent.md) 请求 `Scene` 视口纹理并建立交互表面。 -3. 绘制左侧工具条，并处理 `Q/W/E/R` 快捷键与工具切换。 -4. 若视口可交互，先读取宿主服务的 `SceneViewportOverlayData`，刷新 move / rotate / scale gizmo 上下文。 -5. 通过 `BuildSceneViewportTransformGizmoHandleBuildInputs(...)` 和 `BuildSceneViewportTransformGizmoOverlayState(...)` 组装当前帧 gizmo state，并先调用 `SetSceneViewTransformGizmoOverlayState(...)` 写回宿主服务。 -6. 调用 `GetSceneViewEditorOverlayFrameData(...)` 取回一份已经合成好 scene icon、相机/灯光辅助几何和 gizmo handle 的 frame data。 -7. 对这份 frame data 执行 [SceneViewportOverlayHitTester](../../Viewport/SceneViewportOverlayHitTester/SceneViewportOverlayHitTester.md) 命中测试，并再和 orientation gizmo 命中做统一仲裁。 -8. 处理点击、拖拽和导航，然后把 `SceneViewportInput` 回传给宿主服务。 -9. 视口图像存在时，再次刷新 gizmo，使其对齐本帧更新后的相机与输入状态，并再次调用 `SetSceneViewTransformGizmoOverlayState(...)`，让后续 render path 消费最新 gizmo state。 -10. 最后绘制前端 HUD / orientation overlay。 - -这里有个实现细节很重要：gizmo 当前会在一帧里刷新两次。 - -- 第一次用于交互命中。 -- 第二次用于最终 Scene View render path。 - -这样做的目的，是让导航输入和 gizmo 命中使用同一套几何语义，同时保证最终画出来的 overlay 和本帧相机状态保持一致。 - -## 顶部工具栏语义 - -当前顶部 Scene toolbar 只有两个切换，但它们都会直接改变 gizmo 的数学语义。 - -### Pivot / Center - -`m_pivotMode` 当前有两种值： - -- `Pivot` -- `Center` - -它会改变 `BuildSceneViewportSelectionGizmoState(...)` 的 pivot 计算： - -- `Pivot` - - 使用 primary selected object 的 transform 世界位置。 -- `Center` - - 对所有选中对象求中心点平均值。 - -这里的“中心点”当前按源码有两级回退： - -- 若对象有有效 `MeshFilterComponent + Mesh`，使用 `mesh->GetBounds().center` 经过对象 transform 变换后的世界位置。 -- 否则回退到对象 transform 世界位置。 - -因此 `Center` 更接近视觉中心，而 `Pivot` 更接近主对象原点。 - -### Global / Local - -`m_transformSpaceMode` 当前有两种值： - -- `Global` -- `Local` - -它直接影响 gizmo context 中的 `axisOrientation`： - -- `Global` - - 使用单位旋转，gizmo 轴始终对齐世界轴。 -- `Local` - - 使用 primary selected object 的稳定世界旋转。 - -这里的稳定世界旋转不是直接取单一字段，而是沿父链把 local rotation 连乘得到，再归一化，因此它反映的是当前层级下的真实世界朝向。 - -## primary object 规则 - -gizmo 使用的 primary object 规则是： - -- 优先取 `SelectionManager::GetSelectedEntity()`。 -- 再读取 `GetSelectedEntities()` 构造 `selectedObjects`。 -- 若 primary entity 为空，但多选列表非空，则回退到 `selectedObjects.back()`。 -- 若只有 primary，没有多选列表，则把 primary 补回 `selectedObjects`。 - -这意味着多选时仍然会有一个主对象，它决定： - -- `Pivot` 模式的 pivot 原点。 -- `Local` 模式的轴向旋转来源。 - -## 命中仲裁与点击顺序 - -当前 Scene View 不是“点到什么就直接处理什么”，而是先把不同来源的命中结果统一抽象成 `SceneViewportInteractionCandidate`，再比较优先级、距离和深度。 - -### 命中前置条件 - -只有在以下条件同时满足时，面板才会解析视口交互： - -- 视口纹理存在且尺寸有效。 -- 鼠标位于 viewport 内容区。 -- 当前不是 `ViewMove` 工具。 -- 当前不在 look / pan 拖拽中。 -- 左侧工具条没有悬停。 -- 没有 gizmo 正在活动拖拽。 - -### 当前优先级 - -按当前源码中的 priority 常量，交互优先级从高到低是： - -- scale uniform: `333` -- scale axis cap: `332` -- scale axis line: `331` -- move axis: `322` -- move plane: `321` -- rotate axis: `311` -- orientation gizmo: `200` -- scene icon: `100` -- 空白区域 object-id picking: 兜底路径 - -这带来几个当前行为： - -- transform gizmo 总会压过 orientation gizmo 和 scene icon。 -- orientation gizmo 会压过 scene icon。 -- 只有没有 overlay handle 命中时，才会退回到普通 object-id picking。 - -### 点击结果 - -左键点击当前有四种分支： - -- 命中 transform gizmo - - 调用对应 gizmo 的 `TryBeginDrag(...)` -- 命中 orientation gizmo - - `AlignSceneViewToOrientationAxis(...)` -- 命中 scene icon - - 直接 `SetSelectedEntity(entityId)` -- 都没命中 - - 调用 `PickSceneViewEntity(...)` 走 object-id picking，没选中则清空选择 - -scene icon 这一支不依赖 object-id 纹理，而是直接消费 overlay frame data 里的 handle record，因此图标点击优先走 overlay 选择，不和场景几何 picking 混在一起。 - -## gizmo 更新、拖拽与撤销 - -`SceneViewPanel` 自己不实现 move / rotate / scale 数学，但负责决定哪一套 gizmo 现在拥有输入权。 - -当前面板会做这些事情： - -- 根据 selection、pivot mode、transform space 和鼠标位置构造 gizmo context。 -- 当某一套 gizmo 处于活动状态时，把其他 gizmo 的 `mousePosition` 置成 `(-1, -1)`，防止 hover 状态串扰。 -- 工具切换、视口失效、selection 变更到其他对象时，主动 `CancelDrag(...)`。 -- 鼠标按住左键时持续 `UpdateDrag(...)`，释放时 `EndDrag(...)`。 - -撤销事务本身仍由 gizmo 类发起，但面板负责保证事务只被当前活动 gizmo 使用。 - -## 相机导航与 Focus Selection - -导航模型当前和成熟 Scene View 很接近： - -- 右键按住：look -- 右键 look 期间：`WASDQE` 飞行移动 -- `Shift`：快速移动 -- 中键拖拽：pan -- `ViewMove` 工具下左键拖拽：pan -- 滚轮 - - 普通悬停时：缩放 - - 右键 look 时：调整飞行速度 -- `F`：发送 `focusSelectionRequested` - -真正的 focus 行为由 [ViewportHostService](../../Viewport/ViewportHostService/ViewportHostService.md) 执行： - -- 有 primary selection 时聚焦该对象的 transform position。 -- 否则聚焦所有根对象位置的平均值。 -- 场景为空时聚焦原点。 - -当前 [SceneViewportCameraController](../../Viewport/SceneViewportCameraController/SceneViewportCameraController.md) 虽然支持 orbit 输入，但 `SceneViewPanel` 仍把 `orbiting` 固定为 `false`，所以完整 orbit 手势还没有在面板层接线。 - -## overlay 接线模型 - -`SceneViewPanel` 当前和宿主服务之间的 overlay 接线可以概括成两步： - -### 命中前 - -- 面板先构造当前帧 `SceneViewportTransformGizmoOverlayState` -- 再调用 `SetSceneViewTransformGizmoOverlayState(...)` -- 然后通过 `GetSceneViewEditorOverlayFrameData(...)` 拿到合成 frame data 做 hit-test - -### 渲染前 - -- 导航和拖拽处理结束后，面板再次刷新 gizmo state -- 再次调用 `SetSceneViewTransformGizmoOverlayState(...)` -- 后续 `ViewportHostService::RenderRequestedViewports(...)` 会因为 state 重新变脏而重建 overlay frame data，并把它交给 [SceneViewportEditorOverlayPass](../../Viewport/Passes/SceneViewportEditorOverlayPass/SceneViewportEditorOverlayPass.md) - -这意味着当前 transform gizmo overlay 是“面板生成、宿主缓存并渲染、逐帧失效”的状态输入，而不是面板自己持有的一份 GPU pass 数据。 - -与之对应，`DrawSceneViewportHudOverlay(...)` 现在只补一层 ImGui HUD / orientation gizmo，不再承担 transform gizmo 主绘制。 - -## 设计说明 - -`SceneViewPanel` 当前的结构体现出一个比较成熟的编辑器设计取向： - -- 面板负责交互编排和 UI 状态。 -- 宿主服务负责视口资源、渲染与 picking。 -- gizmo 类负责具体变换数学。 -- overlay 构建与渲染进一步拆成数据层、命中层、GPU pass 层和 ImGui 层。 - -这种分层的好处是 Scene View 能持续长大，而不会迅速坍缩成一个几千行、什么都管的大面板类。 - -## 生命周期与线程语义 - -- 该面板依赖有效 `IEditorContext` 和 `IViewportHostService`。 -- 所有交互与绘制都应视为 Editor 主线程 / ImGui 帧内行为。 -- `m_moveGizmo`、`m_rotateGizmo`、`m_scaleGizmo`、导航拖拽标记、工具模式、pivot mode 和 transform space mode 都属于面板实例私有状态。 - -## 当前限制 - -- 选择主路径仍依赖有效 object-id 帧；只有 scene icon 点击走 overlay 直选。 -- orbit 手势能力仍未从控制器完整接到面板。 -- `Transform` 模式下的 scale 只暴露 `uniformOnly` 行为。 -- scale gizmo 当前仍偏单对象语义，多对象缩放没有和 move / rotate 一样展开。 +`SceneViewPanel` 是当前 Scene View 的编排层，不直接持有 render target，也不直接构建底层 overlay pass。 + +它当前主要把下面这些 helper 串起来： + +- [ViewportPanelContent](../ViewportPanelContent/ViewportPanelContent.md) + 请求 Scene viewport 纹理，并提供 hovered / focused / clicked 等面板表面状态。 +- [SceneViewportChrome](../../Viewport/SceneViewportChrome/SceneViewportChrome.md) + 处理顶部 toolbar、左侧工具按钮 overlay、工具快捷键折叠，以及工具切换前的 gizmo 取消逻辑。 +- [SceneViewportEditorModes](../../Viewport/SceneViewportEditorModes/SceneViewportEditorModes.md) + 提供 `tool / pivot / transform-space` 三组模式枚举。 +- [SceneViewportInteractionFrame](../../Viewport/SceneViewportInteractionFrame/SceneViewportInteractionFrame.md) + 把面板状态翻译成 `SceneViewportToolState`、`SceneViewportFrameGeometry`、`SceneViewportInteractionFrameState`、focus 决策与 presentation request。 +- [SceneViewportNavigation](../../Viewport/SceneViewportNavigation/SceneViewportNavigation.md) + 管理 look/pan 拖拽状态、工具快捷键、capture flags，以及 `SceneViewportInput` 组装。 +- [SceneViewportTransformGizmoCoordinator](../../Viewport/SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoCoordinator.md) + 刷新并提交 gizmo overlay state，并驱动 begin / frame / end 生命周期命令。 +- [SceneViewportInteractionResolver](../../Viewport/SceneViewportInteractionResolver/SceneViewportInteractionResolver.md) + 统一 HUD 命中、overlay handle 命中和 scene pick 入口。 +- [SceneViewportInteractionActions](../../Viewport/SceneViewportInteractionActions/SceneViewportInteractionActions.md) + 把命中结果折叠成 hover / click action，并分发 orientation 对齐与 scene picking。 +- [IViewportHostService](../../Viewport/IViewportHostService/IViewportHostService.md) + 提供 Scene / Game 视口宿主服务、Scene View overlay 查询以及 editor camera 输入桥接。 + +## 公开类型与方法 + +| 成员 | 说明 | +|------|------| +| [SceneViewportToolMode](../../Viewport/SceneViewportEditorModes/SceneViewportToolMode.md) | Scene View 当前工具模式。 | +| [SceneViewportPivotMode](../../Viewport/SceneViewportEditorModes/SceneViewportPivotMode.md) | `Pivot / Center` 两种 pivot 模式。 | +| [SceneViewportTransformSpaceMode](../../Viewport/SceneViewportEditorModes/SceneViewportTransformSpaceMode.md) | `Global / Local` 两种变换空间模式。 | +| [SceneViewPanel()](Constructor.md) | 构造面板实例。 | +| [Render](Render.md) | 渲染面板，并推进一整帧 Scene View 交互链。 | + +## 当前成员语义 + +- `m_toolMode` 默认是 `SceneViewportToolMode::Move`，当前由 `SceneViewportChrome` 负责切换。 +- `m_pivotMode` 默认是 `SceneViewportPivotMode::Pivot`，`m_transformSpaceMode` 默认是 `SceneViewportTransformSpaceMode::Global`。 +- `m_navigationState` 记录 look drag、pan drag，以及当前 pan drag 使用的鼠标按键。 +- `m_moveGizmo / m_rotateGizmo / m_scaleGizmo` 作为面板长生命周期成员跨帧保存交互状态，而不是每帧临时构造。 + +## 当前边界 + +- `SceneViewPanel` 负责“交互编排”，不是 Scene / Game 视口的底层宿主。 +- object-id picking、overlay frame data 缓存、render target 生命周期和 editor camera 状态都在 `ViewportHostService` 一侧。 +- 它只服务于 Scene View，不参与 Game View 的运行时输入桥接。 ## 相关文档 -- [Constructor](Constructor.md) - [Render](Render.md) -- [panels](../panels.md) - [Viewport](../../Viewport/Viewport.md) - [ViewportPanelContent](../ViewportPanelContent/ViewportPanelContent.md) -- [IViewportHostService](../../Viewport/IViewportHostService/IViewportHostService.md) -- [ViewportHostService](../../Viewport/ViewportHostService/ViewportHostService.md) -- [SceneViewportOverlayHandleBuilder](../../Viewport/SceneViewportOverlayHandleBuilder/SceneViewportOverlayHandleBuilder.md) -- [SceneViewportOverlayHitTester](../../Viewport/SceneViewportOverlayHitTester/SceneViewportOverlayHitTester.md) -- [SceneViewportMoveGizmo](../../Viewport/SceneViewportMoveGizmo/SceneViewportMoveGizmo.md) -- [SceneViewportRotateGizmo](../../Viewport/SceneViewportRotateGizmo/SceneViewportRotateGizmo.md) -- [SceneViewportScaleGizmo](../../Viewport/SceneViewportScaleGizmo/SceneViewportScaleGizmo.md) -- [SceneView Interaction And Gizmo Model](../../../../_guides/Editor/SceneView-Interaction-And-Gizmo-Model.md) +- [SceneViewportChrome](../../Viewport/SceneViewportChrome/SceneViewportChrome.md) +- [SceneViewportInteractionFrame](../../Viewport/SceneViewportInteractionFrame/SceneViewportInteractionFrame.md) +- [SceneViewportNavigation](../../Viewport/SceneViewportNavigation/SceneViewportNavigation.md) +- [SceneViewportTransformGizmoCoordinator](../../Viewport/SceneViewportTransformGizmoCoordinator/SceneViewportTransformGizmoCoordinator.md) diff --git a/docs/api/XCEngine/Editor/panels/ViewportPanelContent/ViewportPanelContent.md b/docs/api/XCEngine/Editor/panels/ViewportPanelContent/ViewportPanelContent.md new file mode 100644 index 00000000..b5217dbb --- /dev/null +++ b/docs/api/XCEngine/Editor/panels/ViewportPanelContent/ViewportPanelContent.md @@ -0,0 +1,70 @@ +# ViewportPanelContent + +**命名空间**: `XCEngine::Editor` + +**类型**: `header-helper + result struct` + +**源文件**: `editor/src/panels/ViewportPanelContent.h` + +**描述**: SceneViewPanel 与 GameViewPanel 共享的视口面板内容 helper，负责申请视口纹理、绘制图像、建立交互表面并回传 hover / click / focus 状态。 + +## 概述 + +`ViewportPanelContent.h` 是一个很有价值的“共享面板骨架”抽象。它把 Scene 与 Game 两种视口面板都要做的底层步骤统一起来： + +- 读取可用内容区域。 +- 向 `IViewportHostService` 请求视口。 +- 在窗口里显示视口纹理。 +- 建立 `InvisibleButton` 交互表面。 +- 返回 hover / click / focus 等即时 UI 状态。 + +这样各个视口面板就能把精力放在自己的上层交互逻辑上，而不是重复写一套图像显示和输入表面代码。 + +## 公开类型与函数 + +| 成员 | 说明 | +|------|------| +| `ViewportPanelContentResult` | 返回视口帧、尺寸、item rect 与鼠标交互状态。 | +| `ToUISize(...)` | 把 `ImVec2` 转成 `UISize`，供视口申请使用。 | +| `ToImGuiTextureId(...)` | 把 `UITextureHandle` 转成 `ImGui` 可绘制的纹理句柄。 | +| `DrawViewportStatusMessage(...)` | 在视口中央绘制状态文案。 | +| `GetViewportInteractionSurfaceId(...)` | 为 Scene / Game 生成不同的 invisible button ID。 | +| `RenderViewportInteractionSurface(...)` | 建立交互表面并回填 hover / click 信息。 | +| `RenderViewportPanelContent(...)` | 统一完成视口申请、图像绘制与状态收集。 | + +## 当前实现行为 + +按 `ViewportPanelContent.h` 的实现： + +- 若内容区域过小，会直接 `Dummy(...)` 并返回空结果。 +- `focused` 当前按 `ImGuiFocusedFlags_RootAndChildWindows` 采样，而不是只看当前 leaf window。 +- 若 `viewportHostService` 不存在，仍会建立交互表面，并显示 `Viewport host is unavailable`。 +- 请求到有效 `frame` 后，会用 `ImDrawList::AddImage(...)` 绘制整块视口图像。 +- 若没有纹理也没有明确状态文案，则显示默认提示 `Viewport is initializing`。 +- 交互表面会先 `SetNextItemAllowOverlap()`，再通过 `ImGuiHoveredFlags_AllowWhenOverlappedByItem` 采样 hover/click，从而允许后续 toolbar 叠在视口上方而不丢掉同帧点击边缘。 +- `DrawViewportStatusMessage(...)` 使用当前 item rect 居中绘制提示文字，所以它依赖前面已经建立了可测量的视口交互区域。 + +## 设计说明 + +这是非常典型的商业编辑器 UI 基础设施设计：把“视口承载外壳”抽成一层共用 helper。它的收益包括： + +- Scene / Game 面板行为更一致。 +- 焦点、hover、点击判定不容易各写各的。 +- 后续调整视口显示方式时，只需要改一个共享头。 + +## 生命周期与线程语义 + +- 这是纯 ImGui 帧内 helper，只能在面板 `Render()` 期间使用。 +- `ViewportPanelContentResult` 是逐帧临时结果，不应跨帧缓存使用。 + +## 当前限制 + +- 这里只负责“承载视口”，不负责 gizmo、快捷键、选择和导航逻辑。 +- 交互表面当前基于 `InvisibleButton`，没有更复杂的拖拽层级系统。 +- 状态文字和纹理绘制都直接依赖当前窗口 draw list，不做离屏缓存或异步显示协调。 + +## 相关文档 + +- [SceneViewPanel](../SceneViewPanel/SceneViewPanel.md) +- [Viewport](../../Viewport/Viewport.md) +- [IViewportHostService](../../Viewport/IViewportHostService/IViewportHostService.md) diff --git a/docs/api/XCEngine/Editor/panels/XCUIDemoPanel/XCUIDemoPanel.md b/docs/api/XCEngine/Editor/panels/XCUIDemoPanel/XCUIDemoPanel.md new file mode 100644 index 00000000..45ee3018 --- /dev/null +++ b/docs/api/XCEngine/Editor/panels/XCUIDemoPanel/XCUIDemoPanel.md @@ -0,0 +1,50 @@ +# XCUIDemoPanel + +**命名空间**: `XCEngine::Editor` + +**类型**: `class` + +**源文件**: `editor/src/panels/XCUIDemoPanel.h` + +**描述**: 一个编辑器工作区面板，用固定 demo draw list 演示“XCUI draw command -> ImGuiTransitionBackend -> ImDrawList”的过渡渲染链。 + +## 概览 + +`XCUIDemoPanel` 当前不是完整 XCUI runtime 的宿主，而是一个很轻的过渡演示面板。 + +按 `XCUIDemoPanel.cpp` 的当前实现，它每帧会： + +1. 打开普通 `PanelWindowScope` +2. 创建一个内容区 canvas +3. 直接构造一份 `UIDrawData` +4. 交给 `ImGuiTransitionBackend` 刷到当前 ImGui 窗口 draw list + +## 当前行为 + +- 构造函数把面板标题固定成 `"XCUI Demo"`。 +- `Render()` 会在内容区尺寸太小时直接 `Dummy(...)` 后返回，不生成 draw data。 +- 内部 `BuildXCUIDemoDrawList(...)` 当前写死了： + - 背景卡片 + - 文本标题 + - primitive set / backend flow 说明 + - 底部 footer 文案 +- 当前 demo 数据完全由 `XCUIDemoPanel.cpp` 内部拼装，不依赖 `XCUIDemoRuntime`。 + +## 当前调用链 + +- `editor/src/Core/EditorWorkspace.h` 当前会在工作区初始化时 `m_panels.Emplace()`。 +- `Render()` 最终通过成员 `m_backend` 调用： + - `BeginFrame()` + - `Submit(drawData)` + - `EndFrame(ImGui::GetWindowDrawList())` + +## 当前边界 + +- 这是展示过渡后端的 demo panel，不是正式 editor XCUI shell。 +- 当前没有独立单测；它的关键桥接行为主要由 `tests/Editor/test_xcui_imgui_transition_backend.cpp` 间接覆盖。 + +## 相关文档 + +- [panels](../panels.md) +- [ImGuiTransitionBackend](../../XCUIBackend/ImGuiTransitionBackend/ImGuiTransitionBackend.md) +- [DrawData](../../../UI/DrawData/DrawData.md) diff --git a/docs/api/XCEngine/Editor/panels/panels.md b/docs/api/XCEngine/Editor/panels/panels.md index fc630ae8..751d6085 100644 --- a/docs/api/XCEngine/Editor/panels/panels.md +++ b/docs/api/XCEngine/Editor/panels/panels.md @@ -4,13 +4,24 @@ **类型**: `submodule` -**描述**: 编辑器面板基础设施与具体面板集合，当前以 `Panel` 基类和 `PanelCollection` 容器为核心。 +**描述**: 编辑器工作面板子模块，覆盖通用 `Panel` 生命周期、面板集合调度以及 Hierarchy、Project、Inspector、Scene/Game View、Console、MenuBar 等主要工作窗口。 ## 概述 -`editor/src/panels` 目录当前包含菜单栏、Hierarchy、SceneView、GameView、Inspector、Console、Project 等具体面板。 +`editor/src/panels` 是当前 Editor 工作区的直接承载层。 -当前这组文档当前覆盖了： +这些类型共同决定： + +- 用户能看到哪些窗口 +- 每个窗口如何接收 `IEditorContext` +- 哪些窗口只是展示层，哪些窗口还会参与动作路由 +- Scene / Game 视口内容如何嵌入到普通面板生命周期里 + +按当前实现，这一层已经不是简单的“几个松散 ImGui 窗口”，而是统一挂在 `PanelCollection` 和 `EditorLayer` 之下的工作区系统。 + +## 当前面板集合 + +活跃文档当前覆盖： - [Panel](Panel/Panel.md) - [PanelCollection](PanelCollection/PanelCollection.md) @@ -21,17 +32,96 @@ - [ConsolePanel](ConsolePanel/ConsolePanel.md) - [SceneViewPanel](SceneViewPanel/SceneViewPanel.md) - [GameViewPanel](GameViewPanel/GameViewPanel.md) +- [ViewportPanelContent](ViewportPanelContent/ViewportPanelContent.md) +- [XCUIDemoPanel](XCUIDemoPanel/XCUIDemoPanel.md) + +## 分层关系 + +当前面板层可以粗分成三类。 + +### 工作区容器 + +- `Panel` +- `PanelCollection` + +它们负责统一生命周期和上下文注入，不承担具体编辑业务。 + +### 资源 / 场景编辑面板 + +- `HierarchyPanel` +- `ProjectPanel` +- `InspectorPanel` +- `ConsolePanel` + +这些面板主要负责采样用户交互、组织内容区和上下文菜单，再把动作导向 `Actions` / `Commands`。 + +### 视口面板 + +- `SceneViewPanel` +- `GameViewPanel` +- `ViewportPanelContent` + +这几页则更多承担“把视口请求嵌入面板”的职责，真正的渲染仍由 `ViewportHostService` 管理。 + +### XCUI 过渡演示面板 + +- `XCUIDemoPanel` + +它当前不是正式 XCUI shell，而是把 `UIDrawData` 通过 `ImGuiTransitionBackend` 刷到 ImGui 的演示入口。 + +## 当前实现特点 + +### 上下文统一注入 + +当前每个面板都通过 `IEditorContext*` 获取： + +- 选择状态 +- 场景状态 +- 项目状态 +- undo +- active action route + +所以面板层没有自己 new 一套 manager，而是共享同一个 editor context。 + +### 薄面板趋势 + +这轮源码和文档对齐后，几个关键面板的职责边界已经比较清晰： + +- `HierarchyPanel` 主要负责树渲染，交互语义下沉到 `HierarchyActionRouter` +- `ProjectPanel` 主要负责目录树 / 面包屑 / 网格布局，编辑动作下沉到 `ProjectCommands` +- `InspectorPanel` 主要负责 subject 决策与 section 组织，具体字段 UI 下沉到 `ComponentEditors` + +这说明当前 panel 层已经明显走向“薄面板 + 富命令/路由层”的结构。 + +### 视口面板不是 renderer + +`SceneViewPanel` 和 `GameViewPanel` 不再应被理解成“自己持有独立渲染逻辑”的窗口。 + +更准确的描述是： + +- 它们是普通面板 +- 通过 `ViewportPanelContent` 和 `ViewportHostService` 请求并展示视口结果 ## 设计说明 -当前面板系统的思路很直接： +当前 panel 子模块的作用，是把编辑器工作区稳定成一组可组合窗口，而不是把所有逻辑都塞进 `EditorLayer`。 -- 每个面板继承 `Panel` -- 生命周期由 `PanelCollection` 统一调度 -- 上下文通过 `IEditorContext*` 注入到每个面板 +这样做的收益很直接： + +- 工作区增删窗口成本更低 +- 不同窗口可以共享统一 chrome 和布局协议 +- 动作路由和命令层可以围绕窗口上下文形成清晰边界 + +## 当前限制 + +- 当前工作区仍然围绕单主窗口 editor 组织。 +- panel 层没有独立多文档系统。 +- 某些窗口间协作仍依赖显式 route 和共享上下文，没有更复杂的 pane-level focus manager。 ## 相关文档 -- [Editor 模块](../Editor.md) -- [EditorWorkspace](../Core/EditorWorkspace/EditorWorkspace.md) -- [Layers](../Layers/Layers.md) +- [Editor](../Editor.md) +- [Layout](../Layout/Layout.md) +- [UI](../UI/UI.md) +- [Actions](../Actions/Actions.md) +- [Commands](../Commands/Commands.md) diff --git a/docs/api/XCEngine/Input/Input.md b/docs/api/XCEngine/Input/Input.md index 55daa9f4..63f64231 100644 --- a/docs/api/XCEngine/Input/Input.md +++ b/docs/api/XCEngine/Input/Input.md @@ -10,15 +10,34 @@ `XCEngine::Input` 解决的是“如何把平台消息变成引擎可查询输入状态”这个问题。当前模块的核心由两层组成： -- `InputManager` 负责保存当前帧输入状态、提供轮询查询接口，并同步分发输入事件。 +- `InputManager` 负责保存键盘、鼠标的按住态、本帧按下边沿、本帧释放边沿、鼠标位移和滚轮状态，并同步广播输入事件。 - `InputModule` 负责定义平台桥接接口，把操作系统窗口消息翻译成 `InputManager::Process*` 调用。 当前版本的成熟度是分层的： - 键盘与鼠标的基础轮询和事件分发已经可用，并且有单元测试覆盖。 -- Windows 路径已经有实际桥接实现 `WindowsInputModule`。 +- Windows 路径已经有实际桥接实现 [WindowsInputModule](../Platform/Windows/WindowsInputModule/WindowsInputModule.md)。 - 触摸与摇杆相关 API 仍然偏预留位，当前 `InputManager` 自身并不会产生这些输入。 +## 当前帧语义 + +当前输入模块明确区分三类状态： + +- 按住态 + - `IsKeyDown()`、`IsMouseButtonDown()`、`GetAxis()`、`GetAxisRaw()`、`GetButton()`、`IsAnyKeyDown()` +- 抬起态 + - `IsKeyUp()`、`IsMouseButtonUp()` + - 这类查询只是“当前没有按住”，不是“本帧刚释放” +- 边沿态 + - 按下边沿: `IsKeyPressed()`、`IsMouseButtonClicked()`、`GetButtonDown()`、`IsAnyKeyPressed()` + - 释放边沿: `IsKeyReleased()`、`IsMouseButtonReleased()`、`GetButtonUp()` + +这里最容易误解的点有两个： + +- `IsKeyUp()` / `IsMouseButtonUp()` 与 `IsKeyReleased()` / `IsMouseButtonReleased()` 不是一回事。 +- `GetAxisRaw()` 当前和 `GetAxis()` 使用同一套实现，都会根据持续按住状态返回 `-1 / 0 / 1`；它现在不是“只在本帧按下才非零”的边沿接口。 +- 键盘按下边沿查询当前不会过滤 `repeat`。如果平台在后续帧继续发送重复 `KeyDown`，`IsKeyPressed()`、`GetButtonDown()`、`IsAnyKeyPressed()` 仍可能再次成立。 + ## 设计要点 - 同时保留轮询接口和事件接口，方便游戏逻辑与 UI 系统按各自习惯接入。 @@ -28,9 +47,12 @@ ## 当前实现限制 -- `GetAxisRaw` 当前按“本帧按下边沿”计算，而不是按“持续按住”计算，这一点和很多引擎的 `GetAxisRaw` 直觉不同。 -- `ClearAxes` 会同时清空轴和按钮映射，名字比实际行为更窄。 +- `GetAxisRaw()` 当前与 `GetAxis()` 完全一致，都不做平滑、重力或灵敏度处理。 +- 默认注册的 `Mouse X` / `Mouse Y` 轴虽然存在，但仍绑定到 `KeyCode::None`，所以当前查询结果始终为 `0.0f`。 +- 键盘按下边沿语义是“本帧收到 `ProcessKeyDown()` 消息”，不是“严格意义上的首次物理按下”。 +- `ClearAxes()` 会同时清空轴和按钮映射，名字比实际行为更窄。 - `InputTypes::KeyCode` 的底层数值当前存在重复项，而 `InputManager` 又直接把这些值当作数组下标。 +- `InputManager::Shutdown()` 不会清空事件监听器；如果跨生命周期复用单例，需要调用方自己管理订阅。 - `InputManager` 暴露了触摸接口，但当前代码路径没有填充触摸状态。 ## 头文件 @@ -43,7 +65,7 @@ ## 相关指南 -- [Input Flow And Frame Semantics](../../_guides/Input/Input-Flow-and-Frame-Semantics.md) - 解释事件、轮询、帧边界和平台桥接如何配合工作。 +- [Input Flow And Frame Semantics](../../_guides/Input/Input-Flow-and-Frame-Semantics.md) - 解释事件、轮询、边沿状态、帧边界和平台桥接如何配合工作。 ## 相关实现 diff --git a/docs/api/XCEngine/Input/InputManager/GetAxisRaw.md b/docs/api/XCEngine/Input/InputManager/GetAxisRaw.md index 4808103a..8b7d5f45 100644 --- a/docs/api/XCEngine/Input/InputManager/GetAxisRaw.md +++ b/docs/api/XCEngine/Input/InputManager/GetAxisRaw.md @@ -8,12 +8,20 @@ float GetAxisRaw(const Containers::String& axisName) const; ## 行为说明 -当前实现与 [GetAxis](GetAxis.md) 最大的区别在于，它检查的是 `IsKeyPressed()`，而不是 `IsKeyDown()`。这意味着： +按当前 `InputManager.cpp` 的实现，这个方法和 [GetAxis](GetAxis.md) 使用完全相同的计算逻辑： -- 只有在按键“刚按下的那一帧”才会返回 `1.0f` 或 `-1.0f` -- 按住不放跨帧后，结果会回到 `0.0f` +- 如果找不到该轴，返回 `0.0f` +- 正方向键按住时加 `1.0f` +- 负方向键按住时减 `1.0f` +- 正负方向同时按住时互相抵消为 `0.0f` -这和很多引擎里“raw axis 仍然表示持续按住的未平滑值”的直觉不同，因此需要特别小心。 +因此当前 `GetAxisRaw()` 并不是边沿接口，而是“未平滑的持续按住值”。 + +也就是说，当前实现里： + +- `GetAxisRaw()` 与 `GetAxis()` 没有行为差异 +- 两者都不会读取 `InputAxis::GetValue()` +- 两者都不做平滑、重力或灵敏度处理 ## 参数 @@ -21,7 +29,7 @@ float GetAxisRaw(const Containers::String& axisName) const; ## 返回值 -- `float` - 当前帧的原始边沿值。 +- `float` - 当前轴值，通常为 `-1.0f`、`0.0f` 或 `1.0f`。 ## 示例 @@ -33,3 +41,4 @@ float raw = XCEngine::Input::InputManager::Get().GetAxisRaw("Horizontal"); - [返回类型总览](InputManager.md) - [GetAxis](GetAxis.md) +- [RegisterAxis](RegisterAxis.md) diff --git a/docs/api/XCEngine/Input/InputManager/GetButtonDown.md b/docs/api/XCEngine/Input/InputManager/GetButtonDown.md index 44168b3c..789e011d 100644 --- a/docs/api/XCEngine/Input/InputManager/GetButtonDown.md +++ b/docs/api/XCEngine/Input/InputManager/GetButtonDown.md @@ -8,9 +8,17 @@ bool GetButtonDown(const Containers::String& buttonName) const; ## 行为说明 -当前实现把逻辑按钮当作 `KeyCode` 别名处理，因此这个方法等价于对映射后的键调用 `IsKeyPressed()`。 +当前实现把逻辑按钮当作 `KeyCode` 别名处理，这个方法的工作流程是： -如果按钮名未注册，返回 `false`。 +1. 在 `m_buttons` 中查找 `buttonName` +2. 如果未注册，返回 `false` +3. 如果找到，则对映射后的键调用 [IsKeyPressed](IsKeyPressed.md) + +这意味着它继承了 `IsKeyPressed()` 的全部语义： + +- 返回的是“本帧按下边沿”，不是持续按住态 +- 依赖 [Update](Update.md) 的帧边界 +- 当前不会过滤平台重复按键消息；如果映射键在后续帧收到 repeat keydown，本方法也可能再次返回 `true` ## 参数 @@ -33,3 +41,4 @@ if (XCEngine::Input::InputManager::Get().GetButtonDown("Fire1")) { - [返回类型总览](InputManager.md) - [GetButton](GetButton.md) - [GetButtonUp](GetButtonUp.md) +- [IsKeyPressed](IsKeyPressed.md) diff --git a/docs/api/XCEngine/Input/InputManager/GetButtonUp.md b/docs/api/XCEngine/Input/InputManager/GetButtonUp.md index 208430e7..480fb35e 100644 --- a/docs/api/XCEngine/Input/InputManager/GetButtonUp.md +++ b/docs/api/XCEngine/Input/InputManager/GetButtonUp.md @@ -1,6 +1,6 @@ # InputManager::GetButtonUp -查询一个具名逻辑按钮当前是否处于抬起状态。 +查询一个具名逻辑按钮是否在本帧刚被释放。 ```cpp bool GetButtonUp(const Containers::String& buttonName) const; @@ -8,9 +8,13 @@ bool GetButtonUp(const Containers::String& buttonName) const; ## 行为说明 -如果按钮名已注册，当前实现会对映射后的键调用 `IsKeyUp()`。如果按钮名未注册，当前实现直接返回 `true`。 +当前逻辑按钮只是“名字到 `KeyCode`”的映射。按当前实现，这个方法会： -这个“未注册也算 Up”是当前行为，不一定符合所有上层代码的直觉。 +1. 查找 `buttonName` +2. 如果找到，则对映射后的键调用 [IsKeyReleased](IsKeyReleased.md) +3. 如果没找到，则返回 `false` + +这意味着它表达的是“释放边沿”，不是“当前没有按住”。如果你要判断逻辑按钮当前是否处于未按下状态，应先查映射，再结合 [GetButton](GetButton.md) 或物理键的 `IsKeyUp()` 语义处理。 ## 参数 @@ -18,7 +22,7 @@ bool GetButtonUp(const Containers::String& buttonName) const; ## 返回值 -- `bool` - 当前是否处于抬起状态；未注册按钮也会返回 `true`。 +- `bool` - 该按钮是否在本帧刚被释放；未注册按钮返回 `false`。 ## 示例 @@ -30,3 +34,5 @@ bool released = XCEngine::Input::InputManager::Get().GetButtonUp("Jump"); - [返回类型总览](InputManager.md) - [GetButton](GetButton.md) +- [GetButtonDown](GetButtonDown.md) +- [IsKeyReleased](IsKeyReleased.md) diff --git a/docs/api/XCEngine/Input/InputManager/InputManager.md b/docs/api/XCEngine/Input/InputManager/InputManager.md index e5e06218..c775c8e4 100644 --- a/docs/api/XCEngine/Input/InputManager/InputManager.md +++ b/docs/api/XCEngine/Input/InputManager/InputManager.md @@ -10,42 +10,75 @@ ## 概述 -`InputManager` 是 XCEngine 当前输入系统的核心入口。平台层通过 `ProcessKeyDown`、`ProcessMouseMove` 等方法把原始输入送进来；游戏代码、编辑器和测试代码则通过 `IsKeyDown`、`GetAxis`、`OnKeyEvent` 等 API 查询或订阅这些状态。 +`InputManager` 是 XCEngine 当前输入系统的核心入口。平台层通过 `ProcessKeyDown`、`ProcessMouseMove` 等方法把原始输入送进来；游戏代码、编辑器和测试代码则通过 `IsKeyDown`、`GetAxis`、`GetButtonDown`、`OnKeyEvent` 等 API 查询或订阅这些状态。 它同时承担两种角色： -- 轮询中心：保存“当前是否按下”“本帧是否刚按下”“本帧鼠标位移”等状态。 -- 事件中心：把输入变化同步广播给订阅者。 +- 轮询中心 + - 保存“当前是否按住”“本帧是否刚按下”“本帧是否刚释放”“本帧鼠标位移 / 滚轮”等状态 +- 事件中心 + - 把输入变化同步广播给订阅者 + +## 当前帧状态模型 + +当前实现内部至少维护四组和键鼠查询直接相关的状态： + +| 状态层 | 键盘 | 鼠标 | 作用 | +|------|------|------|------| +| 按住态 | `m_keyDown` | `m_mouseButtonDown` | 回答 `IsKeyDown()` / `IsMouseButtonDown()` / `GetAxis()` / `GetButton()` / `IsAnyKeyDown()` | +| 按下边沿 | `m_keyDownThisFrame` | `m_mouseButtonDownThisFrame` | 回答 `IsKeyPressed()` / `IsMouseButtonClicked()` / `GetButtonDown()` / `IsAnyKeyPressed()` | +| 上一帧按下边沿 | `m_keyDownLastFrame` | `m_mouseButtonDownLastFrame` | 帮助判断“这一帧是否第一次按下” | +| 释放边沿 | `m_keyUpThisFrame` | `m_mouseButtonUpThisFrame` | 回答 `IsKeyReleased()` / `IsMouseButtonReleased()` / `GetButtonUp()` | + +这里要特别区分两组很容易混淆的接口： + +- `IsKeyUp()` / `IsMouseButtonUp()` + - 只是“当前没有按住” + - 等价于 `!IsKeyDown()` / `!IsMouseButtonDown()` +- `IsKeyReleased()` / `IsMouseButtonReleased()` + - 是“本帧刚释放” + - 依赖 `ProcessKeyUp()` / `ProcessMouseButton(..., false, ...)` 写入的释放边沿缓存 ## 生命周期 - [Get](Get.md) 返回进程级单例。 - [Initialize](Initialize.md) 分配内部状态数组、保存窗口句柄并注册默认轴/按钮。 -- [Shutdown](Shutdown.md) 清空状态和映射，但当前不会清空事件监听器。 +- [Shutdown](Shutdown.md) 会清空状态和映射，但当前不会清空事件监听器。 - [Update](Update.md) 用于推进帧边界并清理瞬时状态。 ## 默认映射 -当前 `Initialize` 会注册以下默认逻辑项： +当前 `Initialize()` 会注册以下默认逻辑项： - 轴：`Horizontal` (`D` / `A`)、`Vertical` (`W` / `S`) -- 轴：`Mouse X`、`Mouse Y`，但两者当前都绑定为 `KeyCode::None`，因此 `GetAxis` 结果始终为 `0` +- 轴：`Mouse X`、`Mouse Y` + - 但两者当前都绑定为 `KeyCode::None` + - 因此 `GetAxis()` / `GetAxisRaw()` 结果始终为 `0.0f` - 按钮：`Jump` (`Space`)、`Fire1` (`LeftCtrl`)、`Fire2` (`LeftAlt`)、`Fire3` (`LeftShift`) +## 当前实现行为 + +- [GetAxis](GetAxis.md) 和 [GetAxisRaw](GetAxisRaw.md) 当前使用同一套实现，都会根据持续按住状态返回 `-1.0f / 0.0f / 1.0f`。 +- 逻辑按钮当前只是“名字到 `KeyCode`”的映射；`GetButtonDown()` / `GetButtonUp()` 仍然分别转发到键盘的按下边沿 / 释放边沿查询。 +- [IsAnyKeyDown](IsAnyKeyDown.md) 和 [IsAnyKeyPressed](IsAnyKeyPressed.md) 会同时统计键盘和鼠标按键，不只是键盘。 +- [ProcessKeyDown](ProcessKeyDown.md) 不会因为 `repeat == true` 而跳过按下缓存写入，所以 `IsKeyPressed()` / `GetButtonDown()` / `IsAnyKeyPressed()` 反映的是“这一帧是否收到按下消息”，不保证只对应首次物理按下。 +- `m_buttonDownThisFrame` / `m_buttonDownLastFrame` 当前只在 [Update](Update.md) 中维护，还没有成为逻辑按钮查询的主来源。 + ## 线程语义 - 当前实现没有锁，也不是为多线程输入注入设计的。 -- `Process*`、`Update`、注册映射和查询最好都在主线程或同一逻辑线程完成。 +- `Process*`、`Update()`、注册映射和查询最好都在主线程或同一逻辑线程完成。 - 事件回调同步执行在调用 `Process*` 的线程上。 ## 当前实现限制 - `platformWindowHandle` 会被保存，但 `InputManager` 当前并不直接使用它。 - `KeyCode` 数值存在重复项，而 `InputManager` 用原始枚举值索引固定数组，因此部分按键状态会别名冲突。 -- `GetAxisRaw` 当前按“按下这一帧”计算，而不是按“持续按住”计算。 -- `GetButtonUp` 对未注册按钮返回 `true`。 -- `ClearAxes` 会同时清空 `m_axes` 和 `m_buttons`。 +- `GetAxisRaw()` 当前和 `GetAxis()` 没有行为差异。 +- 键盘按下边沿接口不屏蔽平台重复按键消息。 +- `ClearAxes()` 会同时清空 `m_axes` 和 `m_buttons`。 - 触摸接口已暴露，但当前实现没有任何公开路径去填充 `m_touches`。 +- `Shutdown()` 不会清空事件监听器；如果单例跨生命周期反复初始化，需要调用方自己解除订阅。 ## 公开方法 @@ -58,19 +91,23 @@ | [IsKeyDown](IsKeyDown.md) | 查询键是否处于按下状态。 | | [IsKeyUp](IsKeyUp.md) | 查询键是否处于抬起状态。 | | [IsKeyPressed](IsKeyPressed.md) | 查询键是否在本帧刚被按下。 | +| [IsKeyReleased](IsKeyReleased.md) | 查询键是否在本帧刚被释放。 | | [GetMousePosition](GetMousePosition.md) | 读取当前鼠标位置。 | | [GetMouseDelta](GetMouseDelta.md) | 读取本帧鼠标位移。 | | [GetMouseScrollDelta](GetMouseScrollDelta.md) | 读取本帧滚轮增量。 | | [IsMouseButtonDown](IsMouseButtonDown.md) | 查询鼠标按键是否按下。 | | [IsMouseButtonUp](IsMouseButtonUp.md) | 查询鼠标按键是否抬起。 | | [IsMouseButtonClicked](IsMouseButtonClicked.md) | 查询鼠标按键是否在本帧刚被按下。 | +| [IsMouseButtonReleased](IsMouseButtonReleased.md) | 查询鼠标按键是否在本帧刚被释放。 | | [GetTouchCount](GetTouchCount.md) | 读取触点数量。 | | [GetTouch](GetTouch.md) | 读取指定触点状态。 | | [GetAxis](GetAxis.md) | 读取具名逻辑轴。 | | [GetAxisRaw](GetAxisRaw.md) | 读取具名逻辑轴的当前原始值。 | | [GetButton](GetButton.md) | 查询具名按钮当前是否按下。 | | [GetButtonDown](GetButtonDown.md) | 查询具名按钮是否在本帧刚按下。 | -| [GetButtonUp](GetButtonUp.md) | 查询具名按钮是否处于抬起状态。 | +| [GetButtonUp](GetButtonUp.md) | 查询具名按钮是否在本帧刚释放。 | +| [IsAnyKeyDown](IsAnyKeyDown.md) | 查询是否存在任意键盘键或鼠标键处于按住状态。 | +| [IsAnyKeyPressed](IsAnyKeyPressed.md) | 查询是否存在任意键盘键或鼠标键在本帧刚被按下。 | | [RegisterAxis](RegisterAxis.md) | 注册或覆盖一个具名轴。 | | [RegisterButton](RegisterButton.md) | 注册或覆盖一个具名按钮。 | | [ClearAxes](ClearAxes.md) | 清空轴和按钮映射。 | @@ -86,6 +123,11 @@ | [ProcessMouseWheel](ProcessMouseWheel.md) | 注入鼠标滚轮事件。 | | [ProcessTextInput](ProcessTextInput.md) | 注入文本输入事件。 | +## 真实行为依据 + +- `engine/src/Input/InputManager.cpp` +- `tests/Input/test_input_manager.cpp` + ## 相关文档 - [当前模块](../Input.md) diff --git a/docs/api/XCEngine/Input/InputManager/IsAnyKeyDown.md b/docs/api/XCEngine/Input/InputManager/IsAnyKeyDown.md new file mode 100644 index 00000000..e15c7c15 --- /dev/null +++ b/docs/api/XCEngine/Input/InputManager/IsAnyKeyDown.md @@ -0,0 +1,37 @@ +# InputManager::IsAnyKeyDown + +查询是否存在任意键盘键或鼠标按键当前处于按住状态。 + +```cpp +bool IsAnyKeyDown() const; +``` + +## 行为说明 + +当前实现会： + +- 如果未初始化，返回 `false` +- 先扫描 `m_keyDown` +- 再扫描 `m_mouseButtonDown` +- 任一数组里存在 `true` 就返回 `true` + +这意味着当前 “any key” 的统计范围并不只限于键盘，鼠标按键也会让它成立。 + +## 返回值 + +- `bool` - 当前是否存在任意键盘键或鼠标按键处于按住状态。 + +## 示例 + +```cpp +if (XCEngine::Input::InputManager::Get().IsAnyKeyDown()) { + // ... +} +``` + +## 相关文档 + +- [返回类型总览](InputManager.md) +- [IsAnyKeyPressed](IsAnyKeyPressed.md) +- [IsKeyDown](IsKeyDown.md) +- [IsMouseButtonDown](IsMouseButtonDown.md) diff --git a/docs/api/XCEngine/Input/InputManager/IsAnyKeyPressed.md b/docs/api/XCEngine/Input/InputManager/IsAnyKeyPressed.md new file mode 100644 index 00000000..752f5118 --- /dev/null +++ b/docs/api/XCEngine/Input/InputManager/IsAnyKeyPressed.md @@ -0,0 +1,43 @@ +# InputManager::IsAnyKeyPressed + +查询是否存在任意键盘键或鼠标按键在本帧刚被按下。 + +```cpp +bool IsAnyKeyPressed() const; +``` + +## 行为说明 + +当前实现会： + +- 如果未初始化，返回 `false` +- 先扫描 `m_keyDownThisFrame` +- 再扫描 `m_mouseButtonDownThisFrame` +- 任一数组里存在 `true` 就返回 `true` + +因此它表达的是“按下边沿”，而且同样会把鼠标按键算进 any-key 统计。 + +还要注意两点： + +- 它不是“任意输入设备”。当前只统计键盘和鼠标按钮，不包含触摸、滚轮或文本输入。 +- 键盘侧当前不会过滤 `repeat`。如果平台在后续帧继续发送重复 `KeyDown`，只要 `m_keyDownThisFrame` 被再次写入，它仍会返回 `true`。 + +## 返回值 + +- `bool` - 当前帧是否存在任意键盘键或鼠标按键刚被按下。 + +## 示例 + +```cpp +if (XCEngine::Input::InputManager::Get().IsAnyKeyPressed()) { + // ... +} +``` + +## 相关文档 + +- [返回类型总览](InputManager.md) +- [IsAnyKeyDown](IsAnyKeyDown.md) +- [IsKeyPressed](IsKeyPressed.md) +- [IsMouseButtonClicked](IsMouseButtonClicked.md) +- [ProcessKeyDown](ProcessKeyDown.md) diff --git a/docs/api/XCEngine/Input/InputManager/IsKeyPressed.md b/docs/api/XCEngine/Input/InputManager/IsKeyPressed.md index bf11a32a..864416f2 100644 --- a/docs/api/XCEngine/Input/InputManager/IsKeyPressed.md +++ b/docs/api/XCEngine/Input/InputManager/IsKeyPressed.md @@ -14,7 +14,19 @@ bool IsKeyPressed(KeyCode key) const; m_keyDownThisFrame[index] && !m_keyDownLastFrame[index] ``` -所以它表示的是“从上一帧到当前帧的按下边沿”。要得到正确结果，必须保证 [Update](Update.md) 每帧只在固定边界调用一次。 +因此它表达的是“当前帧出现了按下消息，而且上一帧没有同一个按下标记”。 + +这有两个直接含义： + +- 它是帧级边沿接口，不是持续按住态；按住请使用 [IsKeyDown](IsKeyDown.md) +- 它依赖 [Update](Update.md) 推进帧边界；如果 `Update()` 调用时机不稳定，边沿判断就会失真 + +还要特别注意当前实现不会过滤 `repeat`： + +- [ProcessKeyDown](ProcessKeyDown.md) 无论 `repeat` 是 `true` 还是 `false`，都会把 `m_keyDownThisFrame[index]` 设为 `true` +- 因此平台如果在后续帧继续发送重复 `KeyDown`，`IsKeyPressed()` 仍可能再次返回 `true` + +所以它更准确的定义是“这一帧收到按键按下消息”，而不是“严格意义上的首次物理按下”。 ## 参数 @@ -37,3 +49,5 @@ if (XCEngine::Input::InputManager::Get().IsKeyPressed(XCEngine::Input::KeyCode:: - [返回类型总览](InputManager.md) - [Update](Update.md) - [IsKeyDown](IsKeyDown.md) +- [ProcessKeyDown](ProcessKeyDown.md) +- [IsKeyReleased](IsKeyReleased.md) diff --git a/docs/api/XCEngine/Input/InputManager/IsKeyReleased.md b/docs/api/XCEngine/Input/InputManager/IsKeyReleased.md new file mode 100644 index 00000000..d813afab --- /dev/null +++ b/docs/api/XCEngine/Input/InputManager/IsKeyReleased.md @@ -0,0 +1,41 @@ +# InputManager::IsKeyReleased + +查询一个键是否在本帧刚被释放。 + +```cpp +bool IsKeyReleased(KeyCode key) const; +``` + +## 行为说明 + +当前实现会： + +- 如果未初始化，返回 `false` +- 把 `KeyCode` 强转成数组下标 +- 如果下标越界，返回 `false` +- 否则返回 `m_keyUpThisFrame[index]` + +这个标志位由 [ProcessKeyUp](ProcessKeyUp.md) 写入，并会在 [Update](Update.md) 时被清空，因此它表达的是“释放边沿”，不是“当前没有按住”。 + +## 参数 + +- `key` - 要查询的键。 + +## 返回值 + +- `bool` - 当前帧是否刚被释放。 + +## 示例 + +```cpp +if (XCEngine::Input::InputManager::Get().IsKeyReleased(XCEngine::Input::KeyCode::Space)) { + // ... +} +``` + +## 相关文档 + +- [返回类型总览](InputManager.md) +- [ProcessKeyUp](ProcessKeyUp.md) +- [Update](Update.md) +- [IsKeyUp](IsKeyUp.md) diff --git a/docs/api/XCEngine/Input/InputManager/IsKeyUp.md b/docs/api/XCEngine/Input/InputManager/IsKeyUp.md index d16783d3..e42e3edd 100644 --- a/docs/api/XCEngine/Input/InputManager/IsKeyUp.md +++ b/docs/api/XCEngine/Input/InputManager/IsKeyUp.md @@ -8,12 +8,20 @@ bool IsKeyUp(KeyCode key) const; ## 行为说明 -当前实现有一个很宽松的定义： +当前实现直接把它定义成“不是 Down”： - 如果管理器未初始化，返回 `true` - 否则返回 `!IsKeyDown(key)` +- 如果 `KeyCode` 超出内部数组范围，`IsKeyDown()` 会返回 `false`，因此这里也会表现为 `true` -因此对于未初始化或未识别的键，它都会被视为 “Up”。 +因此对于未初始化、越界或当前未按住的键，它都会被视为 “Up”。 + +这和 [IsKeyReleased](IsKeyReleased.md) 要区分开： + +- `IsKeyUp()` 回答的是“现在有没有按住” +- `IsKeyReleased()` 回答的是“这一帧是否刚释放” + +如果你要做“松开键就触发一次”这类逻辑，应优先使用释放边沿接口，而不是用 `IsKeyUp()` 轮询。 ## 参数 @@ -23,7 +31,16 @@ bool IsKeyUp(KeyCode key) const; - `bool` - 当前是否抬起。 +## 示例 + +```cpp +if (XCEngine::Input::InputManager::Get().IsKeyUp(XCEngine::Input::KeyCode::Space)) { + // Space 当前没有被按住 +} +``` + ## 相关文档 - [返回类型总览](InputManager.md) - [IsKeyDown](IsKeyDown.md) +- [IsKeyReleased](IsKeyReleased.md) diff --git a/docs/api/XCEngine/Input/InputManager/IsMouseButtonClicked.md b/docs/api/XCEngine/Input/InputManager/IsMouseButtonClicked.md index bdae76cc..0a26ac89 100644 --- a/docs/api/XCEngine/Input/InputManager/IsMouseButtonClicked.md +++ b/docs/api/XCEngine/Input/InputManager/IsMouseButtonClicked.md @@ -14,7 +14,15 @@ bool IsMouseButtonClicked(MouseButton button) const; m_mouseButtonDownThisFrame[index] && !m_mouseButtonDownLastFrame[index] ``` -它表示的是“本帧按下边沿”，而不是完整的点击手势。 +因此它表示的是“当前帧按下边沿”，而不是完整的点击手势。 + +这里的 `Clicked` 更接近很多引擎里的 `MouseButtonDown` 语义，而不是“按下再抬起组成的一次 click 手势”。如果你需要完整点击判定，通常还要结合： + +- [IsMouseButtonReleased](IsMouseButtonReleased.md) +- 鼠标位置 / 拖拽阈值 +- UI 命中测试或自己的手势状态机 + +和键盘不同，鼠标这条路径没有 `repeat` 参数，因此它不会因为平台自动重复而被重复触发。 ## 参数 @@ -29,3 +37,5 @@ m_mouseButtonDownThisFrame[index] && !m_mouseButtonDownLastFrame[index] - [返回类型总览](InputManager.md) - [IsMouseButtonDown](IsMouseButtonDown.md) - [Update](Update.md) +- [IsMouseButtonReleased](IsMouseButtonReleased.md) +- [ProcessMouseButton](ProcessMouseButton.md) diff --git a/docs/api/XCEngine/Input/InputManager/IsMouseButtonReleased.md b/docs/api/XCEngine/Input/InputManager/IsMouseButtonReleased.md new file mode 100644 index 00000000..ac877ec0 --- /dev/null +++ b/docs/api/XCEngine/Input/InputManager/IsMouseButtonReleased.md @@ -0,0 +1,40 @@ +# InputManager::IsMouseButtonReleased + +查询鼠标按键是否在本帧刚被释放。 + +```cpp +bool IsMouseButtonReleased(MouseButton button) const; +``` + +## 行为说明 + +当前实现会： + +- 如果未初始化，返回 `false` +- 把 `MouseButton` 强转成数组下标 +- 如果下标越界，返回 `false` +- 否则返回 `m_mouseButtonUpThisFrame[index]` + +这个标志位由 [ProcessMouseButton](ProcessMouseButton.md) 在 `pressed == false` 时写入，并会在 [Update](Update.md) 时被清空。 + +## 参数 + +- `button` - 要查询的鼠标按键。 + +## 返回值 + +- `bool` - 当前帧是否刚被释放。 + +## 示例 + +```cpp +bool released = + XCEngine::Input::InputManager::Get().IsMouseButtonReleased(XCEngine::Input::MouseButton::Left); +``` + +## 相关文档 + +- [返回类型总览](InputManager.md) +- [ProcessMouseButton](ProcessMouseButton.md) +- [Update](Update.md) +- [IsMouseButtonUp](IsMouseButtonUp.md) diff --git a/docs/api/XCEngine/Input/InputManager/IsMouseButtonUp.md b/docs/api/XCEngine/Input/InputManager/IsMouseButtonUp.md index 3c0c5975..dc128aaa 100644 --- a/docs/api/XCEngine/Input/InputManager/IsMouseButtonUp.md +++ b/docs/api/XCEngine/Input/InputManager/IsMouseButtonUp.md @@ -8,7 +8,13 @@ bool IsMouseButtonUp(MouseButton button) const; ## 行为说明 -如果未初始化，当前实现返回 `true`；否则返回 `!IsMouseButtonDown(button)`。这和键盘的 `IsKeyUp` 语义一致。 +当前实现和键盘侧的 [IsKeyUp](IsKeyUp.md) 一样，表达的是“当前没有按住”： + +- 如果未初始化，返回 `true` +- 否则返回 `!IsMouseButtonDown(button)` +- 如果按钮值越界，`IsMouseButtonDown()` 会返回 `false`，因此这里同样会表现为 `true` + +它不是鼠标“释放边沿”接口。要判断左键是否在这一帧刚刚松开，应使用 [IsMouseButtonReleased](IsMouseButtonReleased.md)。 ## 参数 @@ -18,7 +24,16 @@ bool IsMouseButtonUp(MouseButton button) const; - `bool` - 当前是否抬起。 +## 示例 + +```cpp +if (XCEngine::Input::InputManager::Get().IsMouseButtonUp(XCEngine::Input::MouseButton::Left)) { + // 左键当前没有处于按住状态 +} +``` + ## 相关文档 - [返回类型总览](InputManager.md) - [IsMouseButtonDown](IsMouseButtonDown.md) +- [IsMouseButtonReleased](IsMouseButtonReleased.md) diff --git a/docs/api/XCEngine/Input/InputManager/ProcessKeyDown.md b/docs/api/XCEngine/Input/InputManager/ProcessKeyDown.md index d6a9cba3..4bce2906 100644 --- a/docs/api/XCEngine/Input/InputManager/ProcessKeyDown.md +++ b/docs/api/XCEngine/Input/InputManager/ProcessKeyDown.md @@ -17,6 +17,14 @@ void ProcessKeyDown(KeyCode key, bool repeat, bool alt, bool ctrl, bool shift, b - 如果 `repeat` 为 `true`，事件类型设为 `Repeat`，否则为 `Down` - 同步触发 `m_onKeyEvent` +这里有一个很重要的当前实现细节：`repeat` 只会影响事件类型，不会阻止本帧按下缓存被写入。也就是说，只要平台层再次调用 `ProcessKeyDown()`： + +- [IsKeyPressed](IsKeyPressed.md) 可能在该帧再次返回 `true` +- [GetButtonDown](GetButtonDown.md) 可能再次返回 `true` +- [IsAnyKeyPressed](IsAnyKeyPressed.md) 也可能再次成立 + +如果你需要“严格只响应首次物理按下”，需要结合 `repeat` 自己做过滤，或者在更上层维护去抖逻辑。 + ## 参数 - `key` - 键值。 @@ -35,3 +43,5 @@ void ProcessKeyDown(KeyCode key, bool repeat, bool alt, bool ctrl, bool shift, b - [返回类型总览](InputManager.md) - [OnKeyEvent](OnKeyEvent.md) - [ProcessKeyUp](ProcessKeyUp.md) +- [IsKeyPressed](IsKeyPressed.md) +- [GetButtonDown](GetButtonDown.md) diff --git a/docs/api/XCEngine/Input/InputManager/ProcessKeyUp.md b/docs/api/XCEngine/Input/InputManager/ProcessKeyUp.md index e78fcf6e..6e5cbde8 100644 --- a/docs/api/XCEngine/Input/InputManager/ProcessKeyUp.md +++ b/docs/api/XCEngine/Input/InputManager/ProcessKeyUp.md @@ -12,10 +12,11 @@ void ProcessKeyUp(KeyCode key, bool alt, bool ctrl, bool shift, bool meta); - 如果未初始化或键索引越界，直接返回 - 把 `m_keyDown[index]` 设为 `false` +- 把 `m_keyUpThisFrame[index]` 设为 `true` - 构造 `KeyEvent`，类型固定为 `KeyEvent::Up` - 同步触发 `m_onKeyEvent` -当前没有单独的 “key up this frame” 标志位；抬起后，`IsKeyUp` 会立即通过 `!IsKeyDown(key)` 成立。 +因此这条路径既会让 [IsKeyUp](IsKeyUp.md) 立刻成立，也会为 [IsKeyReleased](IsKeyReleased.md) 写入本帧释放边沿。 ## 参数 @@ -33,4 +34,5 @@ void ProcessKeyUp(KeyCode key, bool alt, bool ctrl, bool shift, bool meta); - [返回类型总览](InputManager.md) - [ProcessKeyDown](ProcessKeyDown.md) +- [IsKeyReleased](IsKeyReleased.md) - [OnKeyEvent](OnKeyEvent.md) diff --git a/docs/api/XCEngine/Input/InputManager/ProcessMouseButton.md b/docs/api/XCEngine/Input/InputManager/ProcessMouseButton.md index 8c8087b5..4e0bbf91 100644 --- a/docs/api/XCEngine/Input/InputManager/ProcessMouseButton.md +++ b/docs/api/XCEngine/Input/InputManager/ProcessMouseButton.md @@ -12,11 +12,16 @@ void ProcessMouseButton(MouseButton button, bool pressed, int x, int y); - 如果未初始化或按钮索引越界，直接返回 - 把 `m_mouseButtonDown[index]` 更新为 `pressed` -- 只有在 `pressed == true` 时，才把 `m_mouseButtonDownThisFrame[index]` 设为 `true` +- 如果 `pressed == true`，把 `m_mouseButtonDownThisFrame[index]` 设为 `true` +- 如果 `pressed == false`，把 `m_mouseButtonUpThisFrame[index]` 设为 `true` - 构造 `MouseButtonEvent` - 同步触发 `m_onMouseButton` -这意味着当前实现只显式记录“按下边沿”，没有单独的 “mouse up this frame” 缓存。 +因此这条注入路径会同时驱动三类查询： + +- 按住态: [IsMouseButtonDown](IsMouseButtonDown.md) +- 按下边沿: [IsMouseButtonClicked](IsMouseButtonClicked.md) +- 释放边沿: [IsMouseButtonReleased](IsMouseButtonReleased.md) ## 参数 @@ -34,3 +39,4 @@ void ProcessMouseButton(MouseButton button, bool pressed, int x, int y); - [返回类型总览](InputManager.md) - [OnMouseButton](OnMouseButton.md) - [IsMouseButtonClicked](IsMouseButtonClicked.md) +- [IsMouseButtonReleased](IsMouseButtonReleased.md) diff --git a/docs/api/XCEngine/Input/InputManager/Shutdown.md b/docs/api/XCEngine/Input/InputManager/Shutdown.md index f0572a72..023a0c62 100644 --- a/docs/api/XCEngine/Input/InputManager/Shutdown.md +++ b/docs/api/XCEngine/Input/InputManager/Shutdown.md @@ -8,7 +8,16 @@ void Shutdown(); ## 行为说明 -当前实现只有在已初始化时才会执行关闭逻辑。它会清空： +当前实现会先无条件重置几项瞬时缓存： + +- `m_mousePosition = Vector2::Zero()` +- `m_mouseDelta = Vector2::Zero()` +- `m_mouseScrollDelta = 0.0f` +- `m_touches.clear()` + +如果管理器此前没有初始化，函数会在这里直接返回。 + +如果管理器已经初始化，则还会继续清空： - 键盘状态数组 - 鼠标按键状态数组 @@ -21,8 +30,6 @@ void Shutdown(); 当前不会清空： - 事件监听器 -- `m_touches` -- 鼠标位置缓存 ## 返回值 diff --git a/docs/api/XCEngine/Input/InputManager/Update.md b/docs/api/XCEngine/Input/InputManager/Update.md index 988a53cf..b8c5f599 100644 --- a/docs/api/XCEngine/Input/InputManager/Update.md +++ b/docs/api/XCEngine/Input/InputManager/Update.md @@ -12,8 +12,10 @@ void Update(float deltaTime); - 把 `m_keyDownThisFrame` 复制到 `m_keyDownLastFrame` - 清空并重建 `m_keyDownThisFrame` +- 清空并重建 `m_keyUpThisFrame` - 把 `m_mouseButtonDownThisFrame` 复制到 `m_mouseButtonDownLastFrame` - 清空并重建 `m_mouseButtonDownThisFrame` +- 清空并重建 `m_mouseButtonUpThisFrame` - 把 `m_buttonDownThisFrame` 复制到 `m_buttonDownLastFrame` - 清空并重建 `m_buttonDownThisFrame` - 把 `m_mouseDelta` 重置为零向量 @@ -33,4 +35,6 @@ void Update(float deltaTime); - [返回类型总览](InputManager.md) - [IsKeyPressed](IsKeyPressed.md) +- [IsKeyReleased](IsKeyReleased.md) - [IsMouseButtonClicked](IsMouseButtonClicked.md) +- [IsMouseButtonReleased](IsMouseButtonReleased.md) diff --git a/docs/api/XCEngine/Platform/GameTime/GameTime.md b/docs/api/XCEngine/Platform/GameTime/GameTime.md index fbc0b1da..657574b6 100644 --- a/docs/api/XCEngine/Platform/GameTime/GameTime.md +++ b/docs/api/XCEngine/Platform/GameTime/GameTime.md @@ -6,27 +6,38 @@ **头文件**: `XCEngine/Platform/GameTime.h` -**描述**: 定义 `XCEngine/Platform` 子目录中的 `GameTime` public API。 +**描述**: 帧时间快照结构，保存单帧时间、累计时间和帧计数，并提供 FPS / SPF 便捷查询。 ## 概述 -`GameTime.h` 是 `XCEngine/Platform` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。 +`GameTime` 是一个轻量值类型，用来把时钟采样结果传给主循环、游戏逻辑或渲染流程。它不自己推进时间，只保存某一帧已经算好的三个核心量： + +- `deltaTime`：这一帧相对上一帧经过的秒数 +- `totalTime`：从计时起点累计到当前的总秒数 +- `frameCount`：已经推进的帧数 ## 声明概览 | 声明 | 类型 | 说明 | |------|------|------| -| `GameTime` | `struct` | 头文件中的公开声明。 | +| `GameTime` | `struct` | 帧时间采样结果。 | ## 结构体成员 -| 成员 | 类型 | 描述 | 默认值 | -|------|------|------|--------| -| `deltaTime` | `float` | 结构体公开字段。 | - | -| `totalTime` | `float` | 结构体公开字段。 | - | -| `frameCount` | `Core::uint64_t` | 结构体公开字段。 | - | +| 成员 | 类型 | 描述 | +|------|------|------| +| `deltaTime` | `float` | 当前帧的秒级时间增量。 | +| `totalTime` | `float` | 从初始化起累计的总时间。 | +| `frameCount` | `Core::uint64_t` | 已推进的帧计数。 | + +## 内联方法 + +| 方法 | 说明 | +|------|------| +| `GetFPS() const` | 按 `1.0f / deltaTime` 计算当前帧率；当 `deltaTime <= 0` 时返回 `0.0f`。 | +| `GetSPF() const` | 直接返回 `deltaTime`。 | ## 相关文档 -- [当前目录](../Platform.md) - 返回 `Platform` 平行目录 -- [API 总索引](../../../main.md) - 返回顶层索引 +- [Platform](../Platform.md) +- [IClock](../IClock/IClock.md) diff --git a/docs/api/XCEngine/Platform/IClock/Destructor.md b/docs/api/XCEngine/Platform/IClock/Destructor.md index 494b4e3c..40aeea87 100644 --- a/docs/api/XCEngine/Platform/IClock/Destructor.md +++ b/docs/api/XCEngine/Platform/IClock/Destructor.md @@ -1,29 +1,26 @@ # IClock::~IClock() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IClock.h` + +## 签名 ```cpp virtual ~IClock() = default; ``` -该方法声明于 `XCEngine/Platform/IClock.h`，当前页面用于固定 `IClock` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +为 `IClock` 提供虚析构，保证调用方可以通过基类指针安全销毁具体平台时钟实现。 -**返回：** `void` - 无返回值。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IClock object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 当前析构函数是 `= default`。 +- 真正需要释放的资源由具体派生类自行管理。 ## 相关文档 -- [返回类总览](IClock.md) -- [返回模块目录](../Platform.md) +- [IClock](IClock.md) diff --git a/docs/api/XCEngine/Platform/IClock/GetAbsoluteTime.md b/docs/api/XCEngine/Platform/IClock/GetAbsoluteTime.md index 1267ed2c..31c8ed99 100644 --- a/docs/api/XCEngine/Platform/IClock/GetAbsoluteTime.md +++ b/docs/api/XCEngine/Platform/IClock/GetAbsoluteTime.md @@ -1,30 +1,29 @@ # IClock::GetAbsoluteTime -获取相关状态或对象。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IClock.h` + +## 签名 ```cpp virtual double GetAbsoluteTime() const = 0; ``` -该方法声明于 `XCEngine/Platform/IClock.h`，当前页面用于固定 `IClock` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回底层时钟当前的绝对时间读数。 -**返回：** `double` - 返回值语义详见头文件声明。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IClock object; - // 根据上下文补齐参数后调用 IClock::GetAbsoluteTime(...)。 - (void)object; -} -``` +- 这是只读查询，不会推进时钟状态。 +- 返回类型是 `double`，适合保存较长运行时间下的高精度读数。 +- 具体时间起点由平台实现决定；如果调用方只关心“程序启动后过了多久”，通常更应该看 [GetTimeSinceInit](GetTimeSinceInit.md)。 ## 相关文档 -- [返回类总览](IClock.md) -- [返回模块目录](../Platform.md) +- [IClock](IClock.md) +- [GetTimeSinceInit](GetTimeSinceInit.md) +- [GetDeltaTime](GetDeltaTime.md) diff --git a/docs/api/XCEngine/Platform/IClock/GetDeltaTime.md b/docs/api/XCEngine/Platform/IClock/GetDeltaTime.md index c356ec2f..ec310ce1 100644 --- a/docs/api/XCEngine/Platform/IClock/GetDeltaTime.md +++ b/docs/api/XCEngine/Platform/IClock/GetDeltaTime.md @@ -1,30 +1,29 @@ # IClock::GetDeltaTime -获取相关状态或对象。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IClock.h` + +## 签名 ```cpp virtual float GetDeltaTime() const = 0; ``` -该方法声明于 `XCEngine/Platform/IClock.h`，当前页面用于固定 `IClock` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回最近一次 [Update](Update.md) 采样得到的时间增量。 -**返回：** `float` - 返回值语义详见头文件声明。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IClock object; - // 根据上下文补齐参数后调用 IClock::GetDeltaTime(...)。 - (void)object; -} -``` +- 返回类型是 `float`，适合作为每帧更新逻辑里的 `deltaTime` 使用。 +- 该值如何定义取决于平台实现，但通常表达“上一帧和这一帧之间经过的秒数”。 +- 调用该方法本身不会刷新内部状态；要得到新的采样结果，需要先调用 [Update](Update.md)。 ## 相关文档 -- [返回类总览](IClock.md) -- [返回模块目录](../Platform.md) +- [IClock](IClock.md) +- [Update](Update.md) +- [GetTimeSinceInit](GetTimeSinceInit.md) diff --git a/docs/api/XCEngine/Platform/IClock/GetTimeSinceInit.md b/docs/api/XCEngine/Platform/IClock/GetTimeSinceInit.md index 85454d17..ddc85de6 100644 --- a/docs/api/XCEngine/Platform/IClock/GetTimeSinceInit.md +++ b/docs/api/XCEngine/Platform/IClock/GetTimeSinceInit.md @@ -1,30 +1,29 @@ # IClock::GetTimeSinceInit -获取相关状态或对象。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IClock.h` + +## 签名 ```cpp virtual double GetTimeSinceInit() const = 0; ``` -该方法声明于 `XCEngine/Platform/IClock.h`，当前页面用于固定 `IClock` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回自该时钟实现初始化以来的累计时间。 -**返回：** `double` - 返回值语义详见头文件声明。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IClock object; - // 根据上下文补齐参数后调用 IClock::GetTimeSinceInit(...)。 - (void)object; -} -``` +- 这是只读查询，不会推进时钟状态。 +- 返回值通常比绝对时间更适合驱动运行时逻辑，因为它的起点是时钟自身初始化时刻。 +- 若调用方需要“上一帧到这一帧经过了多久”，应看 [GetDeltaTime](GetDeltaTime.md)。 ## 相关文档 -- [返回类总览](IClock.md) -- [返回模块目录](../Platform.md) +- [IClock](IClock.md) +- [GetAbsoluteTime](GetAbsoluteTime.md) +- [GetDeltaTime](GetDeltaTime.md) diff --git a/docs/api/XCEngine/Platform/IClock/IClock.md b/docs/api/XCEngine/Platform/IClock/IClock.md index 5378ebd4..ead160cd 100644 --- a/docs/api/XCEngine/Platform/IClock/IClock.md +++ b/docs/api/XCEngine/Platform/IClock/IClock.md @@ -6,29 +6,36 @@ **头文件**: `XCEngine/Platform/IClock.h` -**描述**: 定义 `XCEngine/Platform` 子目录中的 `IClock` public API。 +**描述**: 平台时钟抽象，提供绝对时间、相对启动时间、上一帧增量时间和显式更新时间采样入口。 ## 概述 -`IClock.h` 是 `XCEngine/Platform` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。 +`IClock` 是平台层的时间读取接口。它约定了一套最小但够用的时钟能力： + +- `GetAbsoluteTime()` 读取底层时钟当前值 +- `GetTimeSinceInit()` 读取自时钟初始化以来的累计时间 +- `GetDeltaTime()` 读取最近一次 `Update()` 采样得到的帧增量 +- `Update()` 推进内部采样状态 + +调用方通常不会自己实现它，而是通过 [IPlatform::CreateClock](../IPlatform/CreateClock.md) 获取具体平台实现。 ## 声明概览 | 声明 | 类型 | 说明 | |------|------|------| -| `IClock` | `class` | 头文件中的公开声明。 | +| `IClock` | `class` | 平台时钟接口。 | ## 公共方法 | 方法 | 描述 | |------|------| -| [~IClock()](Destructor.md) | 销毁对象并释放相关资源。 | -| [GetAbsoluteTime](GetAbsoluteTime.md) | 获取相关状态或对象。 | -| [GetTimeSinceInit](GetTimeSinceInit.md) | 获取相关状态或对象。 | -| [GetDeltaTime](GetDeltaTime.md) | 获取相关状态或对象。 | -| [Update](Update.md) | 更新运行时状态。 | +| [~IClock()](Destructor.md) | 通过基类指针安全销毁具体平台时钟实现。 | +| [GetAbsoluteTime](GetAbsoluteTime.md) | 返回底层时钟当前的绝对时间读数。 | +| [GetTimeSinceInit](GetTimeSinceInit.md) | 返回自时钟初始化以来的累计时间。 | +| [GetDeltaTime](GetDeltaTime.md) | 返回最近一次 `Update()` 记录的时间增量。 | +| [Update](Update.md) | 采样当前时钟并刷新 `deltaTime` 一类派生状态。 | ## 相关文档 -- [当前目录](../Platform.md) - 返回 `Platform` 平行目录 -- [API 总索引](../../../main.md) - 返回顶层索引 +- [Platform](../Platform.md) +- [IPlatform::CreateClock](../IPlatform/CreateClock.md) diff --git a/docs/api/XCEngine/Platform/IClock/Update.md b/docs/api/XCEngine/Platform/IClock/Update.md index 24d26023..e38374b2 100644 --- a/docs/api/XCEngine/Platform/IClock/Update.md +++ b/docs/api/XCEngine/Platform/IClock/Update.md @@ -1,30 +1,28 @@ # IClock::Update -更新运行时状态。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IClock.h` + +## 签名 ```cpp virtual void Update() = 0; ``` -该方法声明于 `XCEngine/Platform/IClock.h`，当前页面用于固定 `IClock` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +采样当前底层时钟，并刷新该实现内部维护的增量时间状态。 -**返回：** `void` - 无返回值。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IClock object; - // 根据上下文补齐参数后调用 IClock::Update(...)。 - (void)object; -} -``` +- 这是 `IClock` 唯一的显式推进入口。 +- 调用后，`GetDeltaTime()` 一类查询通常才会反映新一帧的时间增量。 +- 该接口不规定谁来驱动更新频率；通常由引擎主循环或平台主循环在每帧调用。 ## 相关文档 -- [返回类总览](IClock.md) -- [返回模块目录](../Platform.md) +- [IClock](IClock.md) +- [GetDeltaTime](GetDeltaTime.md) diff --git a/docs/api/XCEngine/Platform/IDisplayEnumerator/Destructor.md b/docs/api/XCEngine/Platform/IDisplayEnumerator/Destructor.md index 33246d75..7baa7621 100644 --- a/docs/api/XCEngine/Platform/IDisplayEnumerator/Destructor.md +++ b/docs/api/XCEngine/Platform/IDisplayEnumerator/Destructor.md @@ -1,29 +1,26 @@ # IDisplayEnumerator::~IDisplayEnumerator() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IDisplayEnumerator.h` + +## 签名 ```cpp virtual ~IDisplayEnumerator() = default; ``` -该方法声明于 `XCEngine/Platform/IDisplayEnumerator.h`，当前页面用于固定 `IDisplayEnumerator` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +允许调用方通过基类指针安全销毁具体显示器枚举器实现。 -**返回：** `void` - 无返回值。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IDisplayEnumerator object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 析构函数本身没有额外逻辑。 +- 真实清理由具体派生类承担。 ## 相关文档 -- [返回类总览](IDisplayEnumerator.md) -- [返回模块目录](../Platform.md) +- [IDisplayEnumerator](IDisplayEnumerator.md) diff --git a/docs/api/XCEngine/Platform/IDisplayEnumerator/GetDPIForDisplay.md b/docs/api/XCEngine/Platform/IDisplayEnumerator/GetDPIForDisplay.md index 50e0b919..1690cc97 100644 --- a/docs/api/XCEngine/Platform/IDisplayEnumerator/GetDPIForDisplay.md +++ b/docs/api/XCEngine/Platform/IDisplayEnumerator/GetDPIForDisplay.md @@ -1,31 +1,29 @@ # IDisplayEnumerator::GetDPIForDisplay -获取相关状态或对象。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IDisplayEnumerator.h` + +## 签名 ```cpp virtual float GetDPIForDisplay(Core::uint32_t index) const = 0; ``` -该方法声明于 `XCEngine/Platform/IDisplayEnumerator.h`，当前页面用于固定 `IDisplayEnumerator` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `index` - 参数语义详见头文件声明。 +返回指定显示器的 DPI。 -**返回：** `float` - 返回值语义详见头文件声明。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IDisplayEnumerator object; - // 根据上下文补齐参数后调用 IDisplayEnumerator::GetDPIForDisplay(...)。 - (void)object; -} -``` +- `index` 是显示器索引，通常对应 [GetDisplayInfo](GetDisplayInfo.md) 的同一块屏幕。 +- 返回值用于把平台像素密度换算成 UI 或渲染缩放。 +- 索引无效时的处理方式由具体平台实现决定。 ## 相关文档 -- [返回类总览](IDisplayEnumerator.md) -- [返回模块目录](../Platform.md) +- [IDisplayEnumerator](IDisplayEnumerator.md) +- [GetDisplayInfo](GetDisplayInfo.md) +- [GetPrimaryDisplay](GetPrimaryDisplay.md) diff --git a/docs/api/XCEngine/Platform/IDisplayEnumerator/GetDisplayCount.md b/docs/api/XCEngine/Platform/IDisplayEnumerator/GetDisplayCount.md index dc2e3576..0654b72e 100644 --- a/docs/api/XCEngine/Platform/IDisplayEnumerator/GetDisplayCount.md +++ b/docs/api/XCEngine/Platform/IDisplayEnumerator/GetDisplayCount.md @@ -1,30 +1,28 @@ # IDisplayEnumerator::GetDisplayCount -获取相关状态或对象。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IDisplayEnumerator.h` + +## 签名 ```cpp virtual Core::uint32_t GetDisplayCount() const = 0; ``` -该方法声明于 `XCEngine/Platform/IDisplayEnumerator.h`，当前页面用于固定 `IDisplayEnumerator` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回当前平台实现可以枚举到的显示器数量。 -**返回：** `Core::uint32_t` - 返回值语义详见头文件声明。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IDisplayEnumerator object; - // 根据上下文补齐参数后调用 IDisplayEnumerator::GetDisplayCount(...)。 - (void)object; -} -``` +- 这是只读查询，不修改枚举器状态。 +- 返回值通常决定 [GetDisplayInfo](GetDisplayInfo.md) 可接受的索引范围。 ## 相关文档 -- [返回类总览](IDisplayEnumerator.md) -- [返回模块目录](../Platform.md) +- [IDisplayEnumerator](IDisplayEnumerator.md) +- [GetDisplayInfo](GetDisplayInfo.md) +- [GetPrimaryDisplay](GetPrimaryDisplay.md) diff --git a/docs/api/XCEngine/Platform/IDisplayEnumerator/GetDisplayInfo.md b/docs/api/XCEngine/Platform/IDisplayEnumerator/GetDisplayInfo.md index cb5cadcb..16191d8c 100644 --- a/docs/api/XCEngine/Platform/IDisplayEnumerator/GetDisplayInfo.md +++ b/docs/api/XCEngine/Platform/IDisplayEnumerator/GetDisplayInfo.md @@ -1,31 +1,29 @@ # IDisplayEnumerator::GetDisplayInfo -获取相关状态或对象。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IDisplayEnumerator.h` + +## 签名 ```cpp virtual DisplayInfo GetDisplayInfo(Core::uint32_t index) const = 0; ``` -该方法声明于 `XCEngine/Platform/IDisplayEnumerator.h`，当前页面用于固定 `IDisplayEnumerator` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `index` - 参数语义详见头文件声明。 +返回指定索引显示器的快照信息。 -**返回：** `DisplayInfo` - 返回值语义详见头文件声明。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IDisplayEnumerator object; - // 根据上下文补齐参数后调用 IDisplayEnumerator::GetDisplayInfo(...)。 - (void)object; -} -``` +- `index` 是显示器索引，通常应小于 [GetDisplayCount](GetDisplayCount.md) 的返回值。 +- 返回的 `DisplayInfo` 包含名称、分辨率、刷新率、主屏标记和支持分辨率列表。 +- 越界时的行为由具体平台实现决定。 ## 相关文档 -- [返回类总览](IDisplayEnumerator.md) -- [返回模块目录](../Platform.md) +- [IDisplayEnumerator](IDisplayEnumerator.md) +- [GetDisplayCount](GetDisplayCount.md) +- [GetDPIForDisplay](GetDPIForDisplay.md) diff --git a/docs/api/XCEngine/Platform/IDisplayEnumerator/GetPrimaryDisplay.md b/docs/api/XCEngine/Platform/IDisplayEnumerator/GetPrimaryDisplay.md index 6b3b18db..c52b0cbb 100644 --- a/docs/api/XCEngine/Platform/IDisplayEnumerator/GetPrimaryDisplay.md +++ b/docs/api/XCEngine/Platform/IDisplayEnumerator/GetPrimaryDisplay.md @@ -1,30 +1,28 @@ # IDisplayEnumerator::GetPrimaryDisplay -获取相关状态或对象。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IDisplayEnumerator.h` + +## 签名 ```cpp virtual DisplayInfo GetPrimaryDisplay() const = 0; ``` -该方法声明于 `XCEngine/Platform/IDisplayEnumerator.h`，当前页面用于固定 `IDisplayEnumerator` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回主显示器的 `DisplayInfo` 快照。 -**返回：** `DisplayInfo` - 返回值语义详见头文件声明。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IDisplayEnumerator object; - // 根据上下文补齐参数后调用 IDisplayEnumerator::GetPrimaryDisplay(...)。 - (void)object; -} -``` +- 返回值通常等价于“`isPrimary == true` 的那块显示器”。 +- 调用方不需要自己遍历所有显示器去找主屏。 ## 相关文档 -- [返回类总览](IDisplayEnumerator.md) -- [返回模块目录](../Platform.md) +- [IDisplayEnumerator](IDisplayEnumerator.md) +- [GetDisplayInfo](GetDisplayInfo.md) +- [GetDisplayCount](GetDisplayCount.md) diff --git a/docs/api/XCEngine/Platform/IDisplayEnumerator/IDisplayEnumerator.md b/docs/api/XCEngine/Platform/IDisplayEnumerator/IDisplayEnumerator.md index 63fac10a..38ffe8f9 100644 --- a/docs/api/XCEngine/Platform/IDisplayEnumerator/IDisplayEnumerator.md +++ b/docs/api/XCEngine/Platform/IDisplayEnumerator/IDisplayEnumerator.md @@ -6,30 +6,48 @@ **头文件**: `XCEngine/Platform/IDisplayEnumerator.h` -**描述**: 定义 `XCEngine/Platform` 子目录中的 `IDisplayEnumerator` public API。 +**描述**: 显示器枚举接口，配套 `DisplayInfo` 结构体，用于查询显示器数量、显示参数、主显示器和 DPI。 ## 概述 -`IDisplayEnumerator.h` 是 `XCEngine/Platform` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。 +这个头文件同时定义了： + +- `DisplayInfo` + - 一块显示器的快照信息 +- `IDisplayEnumerator` + - 查询显示器列表和 DPI 的抽象接口 + +调用方通常通过 [IPlatform::CreateDisplayEnumerator](../IPlatform/CreateDisplayEnumerator.md) 获取具体实现，再用它枚举显示器或读取主显示器信息。 ## 声明概览 | 声明 | 类型 | 说明 | |------|------|------| -| `DisplayInfo` | `struct` | 头文件中的公开声明。 | -| `IDisplayEnumerator` | `class` | 头文件中的公开声明。 | +| `DisplayInfo` | `struct` | 单块显示器的基础信息快照。 | +| `IDisplayEnumerator` | `class` | 显示器枚举抽象接口。 | + +## `DisplayInfo` 成员 + +| 成员 | 类型 | 说明 | +|------|------|------| +| `name` | `Containers::String` | 显示器名称。 | +| `width` | `Core::uint32_t` | 当前宽度。 | +| `height` | `Core::uint32_t` | 当前高度。 | +| `refreshRate` | `Core::uint32_t` | 当前刷新率。 | +| `isPrimary` | `bool` | 是否为主显示器。 | +| `supportedResolutions` | `std::vector>` | 支持的分辨率列表。 | ## 公共方法 | 方法 | 描述 | |------|------| -| [~IDisplayEnumerator()](Destructor.md) | 销毁对象并释放相关资源。 | -| [GetDisplayCount](GetDisplayCount.md) | 获取相关状态或对象。 | -| [GetDisplayInfo](GetDisplayInfo.md) | 获取相关状态或对象。 | -| [GetPrimaryDisplay](GetPrimaryDisplay.md) | 获取相关状态或对象。 | -| [GetDPIForDisplay](GetDPIForDisplay.md) | 获取相关状态或对象。 | +| [~IDisplayEnumerator()](Destructor.md) | 通过基类指针安全销毁具体枚举器实现。 | +| [GetDisplayCount](GetDisplayCount.md) | 返回当前可见显示器数量。 | +| [GetDisplayInfo](GetDisplayInfo.md) | 返回指定索引显示器的 `DisplayInfo`。 | +| [GetPrimaryDisplay](GetPrimaryDisplay.md) | 返回主显示器信息。 | +| [GetDPIForDisplay](GetDPIForDisplay.md) | 返回指定显示器的 DPI。 | ## 相关文档 -- [当前目录](../Platform.md) - 返回 `Platform` 平行目录 -- [API 总索引](../../../main.md) - 返回顶层索引 +- [Platform](../Platform.md) +- [IPlatform](../IPlatform/IPlatform.md) diff --git a/docs/api/XCEngine/Platform/IDynamicLibrary/Destructor.md b/docs/api/XCEngine/Platform/IDynamicLibrary/Destructor.md index e34f0ff8..640cb7a9 100644 --- a/docs/api/XCEngine/Platform/IDynamicLibrary/Destructor.md +++ b/docs/api/XCEngine/Platform/IDynamicLibrary/Destructor.md @@ -1,29 +1,27 @@ # IDynamicLibrary::~IDynamicLibrary() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IDynamicLibrary.h` + +## 签名 ```cpp virtual ~IDynamicLibrary() = default; ``` -该方法声明于 `XCEngine/Platform/IDynamicLibrary.h`，当前页面用于固定 `IDynamicLibrary` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +允许调用方通过基类指针安全销毁动态库实现对象。 -**返回：** `void` - 无返回值。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IDynamicLibrary object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 析构函数本身没有额外逻辑。 +- 是否在析构前要求显式 [Unload](Unload.md)，取决于具体实现策略。 ## 相关文档 -- [返回类总览](IDynamicLibrary.md) -- [返回模块目录](../Platform.md) +- [IDynamicLibrary](IDynamicLibrary.md) +- [Unload](Unload.md) diff --git a/docs/api/XCEngine/Platform/IDynamicLibrary/GetPath.md b/docs/api/XCEngine/Platform/IDynamicLibrary/GetPath.md index 46795dc0..4a19a807 100644 --- a/docs/api/XCEngine/Platform/IDynamicLibrary/GetPath.md +++ b/docs/api/XCEngine/Platform/IDynamicLibrary/GetPath.md @@ -1,30 +1,28 @@ # IDynamicLibrary::GetPath -获取相关状态或对象。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IDynamicLibrary.h` + +## 签名 ```cpp virtual const char* GetPath() const = 0; ``` -该方法声明于 `XCEngine/Platform/IDynamicLibrary.h`，当前页面用于固定 `IDynamicLibrary` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回当前动态库对象关联的路径字符串。 -**返回：** `const char*` - 返回值语义详见头文件声明。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IDynamicLibrary object; - // 根据上下文补齐参数后调用 IDynamicLibrary::GetPath(...)。 - (void)object; -} -``` +- 返回值通常对应最近一次 [Load](Load.md) 使用的路径，或对象内部记录的当前库路径。 +- 字符串内存由具体实现持有，调用方不应自行释放。 ## 相关文档 -- [返回类总览](IDynamicLibrary.md) -- [返回模块目录](../Platform.md) +- [IDynamicLibrary](IDynamicLibrary.md) +- [Load](Load.md) +- [IsLoaded](IsLoaded.md) diff --git a/docs/api/XCEngine/Platform/IDynamicLibrary/GetSymbol.md b/docs/api/XCEngine/Platform/IDynamicLibrary/GetSymbol.md index 38e6dd6f..15e5230d 100644 --- a/docs/api/XCEngine/Platform/IDynamicLibrary/GetSymbol.md +++ b/docs/api/XCEngine/Platform/IDynamicLibrary/GetSymbol.md @@ -1,44 +1,35 @@ # IDynamicLibrary::GetSymbol -获取相关状态或对象。 +**命名空间**: `XCEngine::Platform` -该方法在 `XCEngine/Platform/IDynamicLibrary.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。 +**类型**: `method` -## 重载 1: 声明 +**头文件**: `XCEngine/Platform/IDynamicLibrary.h` + +## 重载 1 ```cpp virtual void* GetSymbol(const char* symbolName) = 0; ``` -**参数：** -- `symbolName` - 参数语义详见头文件声明。 +按导出符号名查询原始地址。 -**返回：** `void*` - 返回值语义详见头文件声明。 - -## 重载 2: 声明 +## 重载 2 ```cpp template T GetSymbol(const char* symbolName); ``` -**参数：** -- `symbolName` - 参数语义详见头文件声明。 +在重载 1 的基础上做 `reinterpret_cast`，方便直接取函数指针或特定符号类型。 -**返回：** `template T` - 返回值语义详见头文件声明。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IDynamicLibrary object; - // 根据上下文补齐参数后调用 IDynamicLibrary::GetSymbol(...)。 - (void)object; -} -``` +- `symbolName` 是要查询的导出符号名。 +- 调用前通常要求动态库已经成功 [Load](Load.md)。 +- 查询失败时返回值如何表示由具体实现决定；模板重载只负责类型转换，不额外做校验。 ## 相关文档 -- [返回类总览](IDynamicLibrary.md) -- [返回模块目录](../Platform.md) +- [IDynamicLibrary](IDynamicLibrary.md) +- [Load](Load.md) +- [IsLoaded](IsLoaded.md) diff --git a/docs/api/XCEngine/Platform/IDynamicLibrary/IDynamicLibrary.md b/docs/api/XCEngine/Platform/IDynamicLibrary/IDynamicLibrary.md index 7312e06b..90b7505d 100644 --- a/docs/api/XCEngine/Platform/IDynamicLibrary/IDynamicLibrary.md +++ b/docs/api/XCEngine/Platform/IDynamicLibrary/IDynamicLibrary.md @@ -6,30 +6,37 @@ **头文件**: `XCEngine/Platform/IDynamicLibrary.h` -**描述**: 定义 `XCEngine/Platform` 子目录中的 `IDynamicLibrary` public API。 +**描述**: 动态库接口，负责装载 / 卸载共享库、查询加载状态，并按符号名提取函数地址。 ## 概述 -`IDynamicLibrary.h` 是 `XCEngine/Platform` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。 +`IDynamicLibrary` 表达的是一份已加载或待加载的共享库对象。它覆盖的能力很集中： + +- `Load(...)` / `Unload()` +- `IsLoaded()` +- `GetSymbol(...)` +- `GetPath()` + +它既支持用 `void*` 原样取符号，也提供模板形式的 `GetSymbol(...)` 便捷转换。 ## 声明概览 | 声明 | 类型 | 说明 | |------|------|------| -| `IDynamicLibrary` | `class` | 头文件中的公开声明。 | +| `IDynamicLibrary` | `class` | 动态库抽象接口。 | ## 公共方法 | 方法 | 描述 | |------|------| -| [~IDynamicLibrary()](Destructor.md) | 销毁对象并释放相关资源。 | -| [Load](Load.md) | 加载资源或数据。 | -| [Unload](Unload.md) | 卸载资源或释放缓存。 | -| [IsLoaded](IsLoaded.md) | 查询当前状态。 | -| [GetSymbol](GetSymbol.md) | 获取相关状态或对象。 | -| [GetPath](GetPath.md) | 获取相关状态或对象。 | +| [~IDynamicLibrary()](Destructor.md) | 通过基类指针安全销毁具体动态库实现。 | +| [Load](Load.md) | 从给定路径加载动态库。 | +| [Unload](Unload.md) | 卸载当前动态库。 | +| [IsLoaded](IsLoaded.md) | 查询动态库当前是否已加载。 | +| [GetSymbol](GetSymbol.md) | 按符号名查询导出地址。 | +| [GetPath](GetPath.md) | 返回当前动态库路径。 | ## 相关文档 -- [当前目录](../Platform.md) - 返回 `Platform` 平行目录 -- [API 总索引](../../../main.md) - 返回顶层索引 +- [Platform](../Platform.md) +- [IPlatform](../IPlatform/IPlatform.md) diff --git a/docs/api/XCEngine/Platform/IDynamicLibrary/IsLoaded.md b/docs/api/XCEngine/Platform/IDynamicLibrary/IsLoaded.md index c7eef613..3597a61f 100644 --- a/docs/api/XCEngine/Platform/IDynamicLibrary/IsLoaded.md +++ b/docs/api/XCEngine/Platform/IDynamicLibrary/IsLoaded.md @@ -1,30 +1,28 @@ # IDynamicLibrary::IsLoaded -查询当前状态。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IDynamicLibrary.h` + +## 签名 ```cpp virtual bool IsLoaded() const = 0; ``` -该方法声明于 `XCEngine/Platform/IDynamicLibrary.h`，当前页面用于固定 `IDynamicLibrary` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +查询动态库对象当前是否已经成功装载底层共享库。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IDynamicLibrary object; - // 根据上下文补齐参数后调用 IDynamicLibrary::IsLoaded(...)。 - (void)object; -} -``` +- 这是只读状态查询。 +- 调用方通常用它决定是否可以继续 [GetSymbol](GetSymbol.md) 或是否需要重新 [Load](Load.md)。 ## 相关文档 -- [返回类总览](IDynamicLibrary.md) -- [返回模块目录](../Platform.md) +- [IDynamicLibrary](IDynamicLibrary.md) +- [Load](Load.md) +- [GetSymbol](GetSymbol.md) diff --git a/docs/api/XCEngine/Platform/IDynamicLibrary/Load.md b/docs/api/XCEngine/Platform/IDynamicLibrary/Load.md index f5fa9c22..a725d167 100644 --- a/docs/api/XCEngine/Platform/IDynamicLibrary/Load.md +++ b/docs/api/XCEngine/Platform/IDynamicLibrary/Load.md @@ -1,31 +1,28 @@ # IDynamicLibrary::Load -加载资源或数据。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IDynamicLibrary.h` + +## 签名 ```cpp virtual bool Load(const char* path) = 0; ``` -该方法声明于 `XCEngine/Platform/IDynamicLibrary.h`，当前页面用于固定 `IDynamicLibrary` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `path` - 参数语义详见头文件声明。 +按路径加载一份动态库。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IDynamicLibrary object; - // 根据上下文补齐参数后调用 IDynamicLibrary::Load(...)。 - (void)object; -} -``` +- `path` 是目标动态库文件路径。 +- 返回值表示加载是否成功。 ## 相关文档 -- [返回类总览](IDynamicLibrary.md) -- [返回模块目录](../Platform.md) +- [IDynamicLibrary](IDynamicLibrary.md) +- [Unload](Unload.md) +- [GetSymbol](GetSymbol.md) diff --git a/docs/api/XCEngine/Platform/IDynamicLibrary/Unload.md b/docs/api/XCEngine/Platform/IDynamicLibrary/Unload.md index 9cfb65d5..8ed943d9 100644 --- a/docs/api/XCEngine/Platform/IDynamicLibrary/Unload.md +++ b/docs/api/XCEngine/Platform/IDynamicLibrary/Unload.md @@ -1,30 +1,28 @@ # IDynamicLibrary::Unload -卸载资源或释放缓存。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IDynamicLibrary.h` + +## 签名 ```cpp virtual void Unload() = 0; ``` -该方法声明于 `XCEngine/Platform/IDynamicLibrary.h`，当前页面用于固定 `IDynamicLibrary` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +卸载当前已经装载的动态库。 -**返回：** `void` - 无返回值。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IDynamicLibrary object; - // 根据上下文补齐参数后调用 IDynamicLibrary::Unload(...)。 - (void)object; -} -``` +- 具体清理顺序和是否允许重复调用，由实现决定。 +- 卸载后 [IsLoaded](IsLoaded.md) 通常会返回 `false`。 ## 相关文档 -- [返回类总览](IDynamicLibrary.md) -- [返回模块目录](../Platform.md) +- [IDynamicLibrary](IDynamicLibrary.md) +- [Load](Load.md) +- [IsLoaded](IsLoaded.md) diff --git a/docs/api/XCEngine/Platform/IFileSystem/CombinePaths.md b/docs/api/XCEngine/Platform/IFileSystem/CombinePaths.md index 36c7af24..d68a5237 100644 --- a/docs/api/XCEngine/Platform/IFileSystem/CombinePaths.md +++ b/docs/api/XCEngine/Platform/IFileSystem/CombinePaths.md @@ -1,32 +1,27 @@ # IFileSystem::CombinePaths -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IFileSystem.h` + +## 签名 ```cpp virtual Containers::String CombinePaths(const Containers::String& base, const Containers::String& relative) const = 0; ``` -该方法声明于 `XCEngine/Platform/IFileSystem.h`，当前页面用于固定 `IFileSystem` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `base` - 参数语义详见头文件声明。 -- `relative` - 参数语义详见头文件声明。 +按当前平台的路径规则把 `base` 和 `relative` 拼成一个路径字符串。 -**返回：** `Containers::String` - 返回值语义详见头文件声明。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IFileSystem object; - // 根据上下文补齐参数后调用 IFileSystem::CombinePaths(...)。 - (void)object; -} -``` +- `base` 是基路径，`relative` 是待拼接的相对部分。 +- 返回值是新的 `Containers::String`，不修改原始输入。 ## 相关文档 -- [返回类总览](IFileSystem.md) -- [返回模块目录](../Platform.md) +- [IFileSystem](IFileSystem.md) +- [NormalizePath](NormalizePath.md) diff --git a/docs/api/XCEngine/Platform/IFileSystem/CreateDirectory.md b/docs/api/XCEngine/Platform/IFileSystem/CreateDirectory.md index 04495eaf..a0614b73 100644 --- a/docs/api/XCEngine/Platform/IFileSystem/CreateDirectory.md +++ b/docs/api/XCEngine/Platform/IFileSystem/CreateDirectory.md @@ -1,31 +1,28 @@ # IFileSystem::CreateDirectory -创建新对象或资源。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IFileSystem.h` + +## 签名 ```cpp virtual bool CreateDirectory(const char* path) = 0; ``` -该方法声明于 `XCEngine/Platform/IFileSystem.h`，当前页面用于固定 `IFileSystem` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `path` - 参数语义详见头文件声明。 +创建 `path` 指向的目录。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IFileSystem object; - // 根据上下文补齐参数后调用 IFileSystem::CreateDirectory(...)。 - (void)object; -} -``` +- `path` 是待创建目录路径。 +- 返回值表示创建是否成功。 ## 相关文档 -- [返回类总览](IFileSystem.md) -- [返回模块目录](../Platform.md) +- [IFileSystem](IFileSystem.md) +- [DirectoryExists](DirectoryExists.md) +- [DeleteFile](DeleteFile.md) diff --git a/docs/api/XCEngine/Platform/IFileSystem/DeleteFile.md b/docs/api/XCEngine/Platform/IFileSystem/DeleteFile.md index 98fc415a..32e9ca27 100644 --- a/docs/api/XCEngine/Platform/IFileSystem/DeleteFile.md +++ b/docs/api/XCEngine/Platform/IFileSystem/DeleteFile.md @@ -1,31 +1,28 @@ # IFileSystem::DeleteFile -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IFileSystem.h` + +## 签名 ```cpp virtual bool DeleteFile(const char* path) = 0; ``` -该方法声明于 `XCEngine/Platform/IFileSystem.h`，当前页面用于固定 `IFileSystem` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `path` - 参数语义详见头文件声明。 +删除 `path` 指向的文件。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IFileSystem object; - // 根据上下文补齐参数后调用 IFileSystem::DeleteFile(...)。 - (void)object; -} -``` +- `path` 是要删除的目标文件路径。 +- 返回值表示删除是否成功。 ## 相关文档 -- [返回类总览](IFileSystem.md) -- [返回模块目录](../Platform.md) +- [IFileSystem](IFileSystem.md) +- [FileExists](FileExists.md) +- [CreateDirectory](CreateDirectory.md) diff --git a/docs/api/XCEngine/Platform/IFileSystem/Destructor.md b/docs/api/XCEngine/Platform/IFileSystem/Destructor.md index 4a6058af..4a4316ee 100644 --- a/docs/api/XCEngine/Platform/IFileSystem/Destructor.md +++ b/docs/api/XCEngine/Platform/IFileSystem/Destructor.md @@ -1,29 +1,26 @@ # IFileSystem::~IFileSystem() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IFileSystem.h` + +## 签名 ```cpp virtual ~IFileSystem() = default; ``` -该方法声明于 `XCEngine/Platform/IFileSystem.h`，当前页面用于固定 `IFileSystem` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +允许调用方通过基类指针安全销毁具体文件系统实现。 -**返回：** `void` - 无返回值。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IFileSystem object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 析构函数本身没有额外逻辑。 +- 真实资源释放由派生类完成。 ## 相关文档 -- [返回类总览](IFileSystem.md) -- [返回模块目录](../Platform.md) +- [IFileSystem](IFileSystem.md) diff --git a/docs/api/XCEngine/Platform/IFileSystem/DirectoryExists.md b/docs/api/XCEngine/Platform/IFileSystem/DirectoryExists.md index c4a5cc42..1455ac24 100644 --- a/docs/api/XCEngine/Platform/IFileSystem/DirectoryExists.md +++ b/docs/api/XCEngine/Platform/IFileSystem/DirectoryExists.md @@ -1,31 +1,28 @@ # IFileSystem::DirectoryExists -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IFileSystem.h` + +## 签名 ```cpp virtual bool DirectoryExists(const char* path) const = 0; ``` -该方法声明于 `XCEngine/Platform/IFileSystem.h`，当前页面用于固定 `IFileSystem` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `path` - 参数语义详见头文件声明。 +查询 `path` 是否指向一个已存在的目录。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IFileSystem object; - // 根据上下文补齐参数后调用 IFileSystem::DirectoryExists(...)。 - (void)object; -} -``` +- 这是只读存在性检查。 +- 返回 `true` 表示目录存在，`false` 表示不存在或无法按目录访问。 ## 相关文档 -- [返回类总览](IFileSystem.md) -- [返回模块目录](../Platform.md) +- [IFileSystem](IFileSystem.md) +- [FileExists](FileExists.md) +- [CreateDirectory](CreateDirectory.md) diff --git a/docs/api/XCEngine/Platform/IFileSystem/FileExists.md b/docs/api/XCEngine/Platform/IFileSystem/FileExists.md index 7e4d62a8..7ddd931a 100644 --- a/docs/api/XCEngine/Platform/IFileSystem/FileExists.md +++ b/docs/api/XCEngine/Platform/IFileSystem/FileExists.md @@ -1,31 +1,28 @@ # IFileSystem::FileExists -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IFileSystem.h` + +## 签名 ```cpp virtual bool FileExists(const char* path) const = 0; ``` -该方法声明于 `XCEngine/Platform/IFileSystem.h`，当前页面用于固定 `IFileSystem` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `path` - 参数语义详见头文件声明。 +查询 `path` 是否指向一个已存在的文件。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IFileSystem object; - // 根据上下文补齐参数后调用 IFileSystem::FileExists(...)。 - (void)object; -} -``` +- 这是只读存在性检查。 +- 返回 `true` 表示文件存在，`false` 表示不存在或无法按文件访问。 ## 相关文档 -- [返回类总览](IFileSystem.md) -- [返回模块目录](../Platform.md) +- [IFileSystem](IFileSystem.md) +- [DirectoryExists](DirectoryExists.md) +- [GetFileSize](GetFileSize.md) diff --git a/docs/api/XCEngine/Platform/IFileSystem/GetExecutablePath.md b/docs/api/XCEngine/Platform/IFileSystem/GetExecutablePath.md index d46de2da..81ff2520 100644 --- a/docs/api/XCEngine/Platform/IFileSystem/GetExecutablePath.md +++ b/docs/api/XCEngine/Platform/IFileSystem/GetExecutablePath.md @@ -1,30 +1,28 @@ # IFileSystem::GetExecutablePath -获取相关状态或对象。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IFileSystem.h` + +## 签名 ```cpp virtual Containers::String GetExecutablePath() const = 0; ``` -该方法声明于 `XCEngine/Platform/IFileSystem.h`，当前页面用于固定 `IFileSystem` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回当前可执行文件的完整路径。 -**返回：** `Containers::String` - 返回值语义详见头文件声明。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IFileSystem object; - // 根据上下文补齐参数后调用 IFileSystem::GetExecutablePath(...)。 - (void)object; -} -``` +- 返回值是新的 `Containers::String`，由调用方按值接收。 +- 这是只读查询，不改变工作目录。 ## 相关文档 -- [返回类总览](IFileSystem.md) -- [返回模块目录](../Platform.md) +- [IFileSystem](IFileSystem.md) +- [GetWorkingDirectory](GetWorkingDirectory.md) +- [GetUserDirectory](GetUserDirectory.md) diff --git a/docs/api/XCEngine/Platform/IFileSystem/GetFileSize.md b/docs/api/XCEngine/Platform/IFileSystem/GetFileSize.md index d470f67d..21a398ba 100644 --- a/docs/api/XCEngine/Platform/IFileSystem/GetFileSize.md +++ b/docs/api/XCEngine/Platform/IFileSystem/GetFileSize.md @@ -1,31 +1,28 @@ # IFileSystem::GetFileSize -获取相关状态或对象。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IFileSystem.h` + +## 签名 ```cpp virtual int64_t GetFileSize(const char* path) const = 0; ``` -该方法声明于 `XCEngine/Platform/IFileSystem.h`，当前页面用于固定 `IFileSystem` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `path` - 参数语义详见头文件声明。 +返回指定文件的字节大小。 -**返回：** `int64_t` - 返回值语义详见头文件声明。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IFileSystem object; - // 根据上下文补齐参数后调用 IFileSystem::GetFileSize(...)。 - (void)object; -} -``` +- `path` 是目标文件路径。 +- 这是只读查询；失败时如何编码返回值由具体实现决定。 ## 相关文档 -- [返回类总览](IFileSystem.md) -- [返回模块目录](../Platform.md) +- [IFileSystem](IFileSystem.md) +- [FileExists](FileExists.md) +- [ReadFile](ReadFile.md) diff --git a/docs/api/XCEngine/Platform/IFileSystem/GetTempDirectory.md b/docs/api/XCEngine/Platform/IFileSystem/GetTempDirectory.md index e6ac97c8..91c5c761 100644 --- a/docs/api/XCEngine/Platform/IFileSystem/GetTempDirectory.md +++ b/docs/api/XCEngine/Platform/IFileSystem/GetTempDirectory.md @@ -1,30 +1,28 @@ # IFileSystem::GetTempDirectory -获取相关状态或对象。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IFileSystem.h` + +## 签名 ```cpp virtual Containers::String GetTempDirectory() const = 0; ``` -该方法声明于 `XCEngine/Platform/IFileSystem.h`，当前页面用于固定 `IFileSystem` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回平台临时目录路径。 -**返回：** `Containers::String` - 返回值语义详见头文件声明。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IFileSystem object; - // 根据上下文补齐参数后调用 IFileSystem::GetTempDirectory(...)。 - (void)object; -} -``` +- 返回值适合放临时文件、缓存或一次性中间产物。 +- 具体目录位置由平台实现决定。 ## 相关文档 -- [返回类总览](IFileSystem.md) -- [返回模块目录](../Platform.md) +- [IFileSystem](IFileSystem.md) +- [GetUserDirectory](GetUserDirectory.md) +- [GetWorkingDirectory](GetWorkingDirectory.md) diff --git a/docs/api/XCEngine/Platform/IFileSystem/GetUserDirectory.md b/docs/api/XCEngine/Platform/IFileSystem/GetUserDirectory.md index eb84776b..dee27464 100644 --- a/docs/api/XCEngine/Platform/IFileSystem/GetUserDirectory.md +++ b/docs/api/XCEngine/Platform/IFileSystem/GetUserDirectory.md @@ -1,30 +1,28 @@ # IFileSystem::GetUserDirectory -获取相关状态或对象。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IFileSystem.h` + +## 签名 ```cpp virtual Containers::String GetUserDirectory() const = 0; ``` -该方法声明于 `XCEngine/Platform/IFileSystem.h`，当前页面用于固定 `IFileSystem` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回当前用户目录路径。 -**返回：** `Containers::String` - 返回值语义详见头文件声明。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IFileSystem object; - // 根据上下文补齐参数后调用 IFileSystem::GetUserDirectory(...)。 - (void)object; -} -``` +- 具体是家目录、用户配置目录还是平台约定目录，由实现决定。 +- 返回值是新的 `Containers::String`。 ## 相关文档 -- [返回类总览](IFileSystem.md) -- [返回模块目录](../Platform.md) +- [IFileSystem](IFileSystem.md) +- [GetTempDirectory](GetTempDirectory.md) +- [GetWorkingDirectory](GetWorkingDirectory.md) diff --git a/docs/api/XCEngine/Platform/IFileSystem/GetWorkingDirectory.md b/docs/api/XCEngine/Platform/IFileSystem/GetWorkingDirectory.md index 1fea72f9..43fab8b4 100644 --- a/docs/api/XCEngine/Platform/IFileSystem/GetWorkingDirectory.md +++ b/docs/api/XCEngine/Platform/IFileSystem/GetWorkingDirectory.md @@ -1,30 +1,28 @@ # IFileSystem::GetWorkingDirectory -获取相关状态或对象。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IFileSystem.h` + +## 签名 ```cpp virtual Containers::String GetWorkingDirectory() const = 0; ``` -该方法声明于 `XCEngine/Platform/IFileSystem.h`，当前页面用于固定 `IFileSystem` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回当前进程的工作目录。 -**返回：** `Containers::String` - 返回值语义详见头文件声明。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IFileSystem object; - // 根据上下文补齐参数后调用 IFileSystem::GetWorkingDirectory(...)。 - (void)object; -} -``` +- 这是只读查询。 +- 返回值可能影响相对路径解析的起点，但该方法本身不改变解析行为。 ## 相关文档 -- [返回类总览](IFileSystem.md) -- [返回模块目录](../Platform.md) +- [IFileSystem](IFileSystem.md) +- [GetExecutablePath](GetExecutablePath.md) +- [CombinePaths](CombinePaths.md) diff --git a/docs/api/XCEngine/Platform/IFileSystem/IFileSystem.md b/docs/api/XCEngine/Platform/IFileSystem/IFileSystem.md index fcadad44..84dbda1e 100644 --- a/docs/api/XCEngine/Platform/IFileSystem/IFileSystem.md +++ b/docs/api/XCEngine/Platform/IFileSystem/IFileSystem.md @@ -6,38 +6,45 @@ **头文件**: `XCEngine/Platform/IFileSystem.h` -**描述**: 定义 `XCEngine/Platform` 子目录中的 `IFileSystem` public API。 +**描述**: 平台文件系统接口，提供存在性检查、文件读写、目录操作、常用路径查询和路径拼接/规范化能力。 ## 概述 -`IFileSystem.h` 是 `XCEngine/Platform` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。 +`IFileSystem` 把平台相关的文件访问能力抽象成统一接口。当前头文件里的能力主要分四组： + +- 文件 / 目录存在性与大小查询 +- 删除文件、创建目录、读写文件 +- 可执行目录、工作目录、用户目录和临时目录查询 +- 路径规范化与路径拼接 + +调用方通常通过 [IPlatform::CreateFileSystem](../IPlatform/CreateFileSystem.md) 获取具体实现。 ## 声明概览 | 声明 | 类型 | 说明 | |------|------|------| -| `IFileSystem` | `class` | 头文件中的公开声明。 | +| `IFileSystem` | `class` | 平台文件系统抽象接口。 | ## 公共方法 | 方法 | 描述 | |------|------| -| [~IFileSystem()](Destructor.md) | 销毁对象并释放相关资源。 | -| [FileExists](FileExists.md) | 公开方法，详见头文件声明。 | -| [DirectoryExists](DirectoryExists.md) | 公开方法，详见头文件声明。 | -| [GetFileSize](GetFileSize.md) | 获取相关状态或对象。 | -| [DeleteFile](DeleteFile.md) | 公开方法，详见头文件声明。 | -| [CreateDirectory](CreateDirectory.md) | 创建新对象或资源。 | -| [ReadFile](ReadFile.md) | 公开方法，详见头文件声明。 | -| [WriteFile](WriteFile.md) | 公开方法，详见头文件声明。 | -| [GetExecutablePath](GetExecutablePath.md) | 获取相关状态或对象。 | -| [GetWorkingDirectory](GetWorkingDirectory.md) | 获取相关状态或对象。 | -| [GetUserDirectory](GetUserDirectory.md) | 获取相关状态或对象。 | -| [GetTempDirectory](GetTempDirectory.md) | 获取相关状态或对象。 | -| [NormalizePath](NormalizePath.md) | 公开方法，详见头文件声明。 | -| [CombinePaths](CombinePaths.md) | 公开方法，详见头文件声明。 | +| [~IFileSystem()](Destructor.md) | 通过基类指针安全销毁具体文件系统实现。 | +| [FileExists](FileExists.md) | 查询指定文件是否存在。 | +| [DirectoryExists](DirectoryExists.md) | 查询指定目录是否存在。 | +| [GetFileSize](GetFileSize.md) | 返回指定文件大小。 | +| [DeleteFile](DeleteFile.md) | 删除指定文件。 | +| [CreateDirectory](CreateDirectory.md) | 创建目录。 | +| [ReadFile](ReadFile.md) | 读取整个文件内容。 | +| [WriteFile](WriteFile.md) | 把一段内存写入文件。 | +| [GetExecutablePath](GetExecutablePath.md) | 返回当前可执行文件路径。 | +| [GetWorkingDirectory](GetWorkingDirectory.md) | 返回当前工作目录。 | +| [GetUserDirectory](GetUserDirectory.md) | 返回用户目录。 | +| [GetTempDirectory](GetTempDirectory.md) | 返回临时目录。 | +| [NormalizePath](NormalizePath.md) | 规范化路径表示。 | +| [CombinePaths](CombinePaths.md) | 按平台规则拼接路径。 | ## 相关文档 -- [当前目录](../Platform.md) - 返回 `Platform` 平行目录 -- [API 总索引](../../../main.md) - 返回顶层索引 +- [Platform](../Platform.md) +- [IPlatform](../IPlatform/IPlatform.md) diff --git a/docs/api/XCEngine/Platform/IFileSystem/NormalizePath.md b/docs/api/XCEngine/Platform/IFileSystem/NormalizePath.md index 029e43e5..e60a53a0 100644 --- a/docs/api/XCEngine/Platform/IFileSystem/NormalizePath.md +++ b/docs/api/XCEngine/Platform/IFileSystem/NormalizePath.md @@ -1,31 +1,27 @@ # IFileSystem::NormalizePath -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IFileSystem.h` + +## 签名 ```cpp virtual Containers::String NormalizePath(const Containers::String& path) const = 0; ``` -该方法声明于 `XCEngine/Platform/IFileSystem.h`，当前页面用于固定 `IFileSystem` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `path` - 参数语义详见头文件声明。 +把输入路径按当前平台规则规范化成统一表示。 -**返回：** `Containers::String` - 返回值语义详见头文件声明。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IFileSystem object; - // 根据上下文补齐参数后调用 IFileSystem::NormalizePath(...)。 - (void)object; -} -``` +- 规范化可能包含分隔符整理、冗余片段清理或大小写策略调整，具体由实现决定。 +- 返回值是新的 `Containers::String`。 ## 相关文档 -- [返回类总览](IFileSystem.md) -- [返回模块目录](../Platform.md) +- [IFileSystem](IFileSystem.md) +- [CombinePaths](CombinePaths.md) diff --git a/docs/api/XCEngine/Platform/IFileSystem/ReadFile.md b/docs/api/XCEngine/Platform/IFileSystem/ReadFile.md index 1e58771f..89d1379e 100644 --- a/docs/api/XCEngine/Platform/IFileSystem/ReadFile.md +++ b/docs/api/XCEngine/Platform/IFileSystem/ReadFile.md @@ -1,32 +1,29 @@ # IFileSystem::ReadFile -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IFileSystem.h` + +## 签名 ```cpp virtual std::unique_ptr ReadFile(const char* path, size_t* outSize) const = 0; ``` -该方法声明于 `XCEngine/Platform/IFileSystem.h`，当前页面用于固定 `IFileSystem` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `path` - 参数语义详见头文件声明。 -- `outSize` - 参数语义详见头文件声明。 +读取整个文件内容，并把字节缓冲区所有权交给调用方。 -**返回：** `std::unique_ptr` - 返回值语义详见头文件声明。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IFileSystem object; - // 根据上下文补齐参数后调用 IFileSystem::ReadFile(...)。 - (void)object; -} -``` +- `path` 是目标文件路径。 +- `outSize` 用于返回读取到的字节数。 +- 返回值是 `std::unique_ptr`，其内存所有权属于调用方。 ## 相关文档 -- [返回类总览](IFileSystem.md) -- [返回模块目录](../Platform.md) +- [IFileSystem](IFileSystem.md) +- [WriteFile](WriteFile.md) +- [GetFileSize](GetFileSize.md) diff --git a/docs/api/XCEngine/Platform/IFileSystem/WriteFile.md b/docs/api/XCEngine/Platform/IFileSystem/WriteFile.md index 7c70ef37..0baac90a 100644 --- a/docs/api/XCEngine/Platform/IFileSystem/WriteFile.md +++ b/docs/api/XCEngine/Platform/IFileSystem/WriteFile.md @@ -1,33 +1,29 @@ # IFileSystem::WriteFile -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IFileSystem.h` + +## 签名 ```cpp virtual bool WriteFile(const char* path, const void* data, size_t size) = 0; ``` -该方法声明于 `XCEngine/Platform/IFileSystem.h`，当前页面用于固定 `IFileSystem` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `path` - 参数语义详见头文件声明。 -- `data` - 参数语义详见头文件声明。 -- `size` - 参数语义详见头文件声明。 +把 `data` 指向的 `size` 字节内容写入 `path`。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IFileSystem object; - // 根据上下文补齐参数后调用 IFileSystem::WriteFile(...)。 - (void)object; -} -``` +- `path` 是目标文件路径。 +- `data` / `size` 描述待写入的内存块。 +- 返回值表示写入是否成功。 ## 相关文档 -- [返回类总览](IFileSystem.md) -- [返回模块目录](../Platform.md) +- [IFileSystem](IFileSystem.md) +- [ReadFile](ReadFile.md) +- [DeleteFile](DeleteFile.md) diff --git a/docs/api/XCEngine/Platform/IPlatform/CreateClock.md b/docs/api/XCEngine/Platform/IPlatform/CreateClock.md index a4d2064e..fcb5bd46 100644 --- a/docs/api/XCEngine/Platform/IPlatform/CreateClock.md +++ b/docs/api/XCEngine/Platform/IPlatform/CreateClock.md @@ -1,30 +1,27 @@ # IPlatform::CreateClock -创建新对象或资源。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IPlatform.h` + +## 签名 ```cpp virtual std::unique_ptr CreateClock() = 0; ``` -该方法声明于 `XCEngine/Platform/IPlatform.h`，当前页面用于固定 `IPlatform` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +创建一个平台时钟实现对象。 -**返回：** `std::unique_ptr` - 返回值语义详见头文件声明。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IPlatform object; - // 根据上下文补齐参数后调用 IPlatform::CreateClock(...)。 - (void)object; -} -``` +- 返回值是带独占所有权的 `std::unique_ptr`。 +- 具体计时精度和底层时间源由平台实现决定。 ## 相关文档 -- [返回类总览](IPlatform.md) -- [返回模块目录](../Platform.md) +- [IPlatform](IPlatform.md) +- [IClock](../IClock/IClock.md) diff --git a/docs/api/XCEngine/Platform/IPlatform/CreateDisplayEnumerator.md b/docs/api/XCEngine/Platform/IPlatform/CreateDisplayEnumerator.md index 1bb14374..d4e5ad72 100644 --- a/docs/api/XCEngine/Platform/IPlatform/CreateDisplayEnumerator.md +++ b/docs/api/XCEngine/Platform/IPlatform/CreateDisplayEnumerator.md @@ -1,30 +1,27 @@ # IPlatform::CreateDisplayEnumerator -创建新对象或资源。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IPlatform.h` + +## 签名 ```cpp virtual std::unique_ptr CreateDisplayEnumerator() = 0; ``` -该方法声明于 `XCEngine/Platform/IPlatform.h`，当前页面用于固定 `IPlatform` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +创建一个显示器枚举器实现对象。 -**返回：** `std::unique_ptr` - 返回值语义详见头文件声明。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IPlatform object; - // 根据上下文补齐参数后调用 IPlatform::CreateDisplayEnumerator(...)。 - (void)object; -} -``` +- 返回值是带独占所有权的 `std::unique_ptr`。 +- 调用方随后可用它查询显示器列表、主显示器和 DPI。 ## 相关文档 -- [返回类总览](IPlatform.md) -- [返回模块目录](../Platform.md) +- [IPlatform](IPlatform.md) +- [IDisplayEnumerator](../IDisplayEnumerator/IDisplayEnumerator.md) diff --git a/docs/api/XCEngine/Platform/IPlatform/CreateFileSystem.md b/docs/api/XCEngine/Platform/IPlatform/CreateFileSystem.md index a083e31e..396f19ce 100644 --- a/docs/api/XCEngine/Platform/IPlatform/CreateFileSystem.md +++ b/docs/api/XCEngine/Platform/IPlatform/CreateFileSystem.md @@ -1,30 +1,27 @@ # IPlatform::CreateFileSystem -创建新对象或资源。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IPlatform.h` + +## 签名 ```cpp virtual std::unique_ptr CreateFileSystem() = 0; ``` -该方法声明于 `XCEngine/Platform/IPlatform.h`，当前页面用于固定 `IPlatform` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +创建一个平台文件系统实现对象。 -**返回：** `std::unique_ptr` - 返回值语义详见头文件声明。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IPlatform object; - // 根据上下文补齐参数后调用 IPlatform::CreateFileSystem(...)。 - (void)object; -} -``` +- 返回值是带独占所有权的 `std::unique_ptr`。 +- 调用方随后可用它访问路径、文件和目录相关能力。 ## 相关文档 -- [返回类总览](IPlatform.md) -- [返回模块目录](../Platform.md) +- [IPlatform](IPlatform.md) +- [IFileSystem](../IFileSystem/IFileSystem.md) diff --git a/docs/api/XCEngine/Platform/IPlatform/CreateWindow.md b/docs/api/XCEngine/Platform/IPlatform/CreateWindow.md index 88d783a8..2a873ba2 100644 --- a/docs/api/XCEngine/Platform/IPlatform/CreateWindow.md +++ b/docs/api/XCEngine/Platform/IPlatform/CreateWindow.md @@ -1,31 +1,28 @@ # IPlatform::CreateWindow -创建新对象或资源。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IPlatform.h` + +## 签名 ```cpp virtual std::unique_ptr CreateWindow(const WindowDesc& desc) = 0; ``` -该方法声明于 `XCEngine/Platform/IPlatform.h`，当前页面用于固定 `IPlatform` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `desc` - 参数语义详见头文件声明。 +按 `WindowDesc` 创建一个平台窗口实现对象。 -**返回：** `std::unique_ptr` - 返回值语义详见头文件声明。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IPlatform object; - // 根据上下文补齐参数后调用 IPlatform::CreateWindow(...)。 - (void)object; -} -``` +- `desc` 提供标题、尺寸和全屏初始参数。 +- 返回值是带独占所有权的 `std::unique_ptr`。 ## 相关文档 -- [返回类总览](IPlatform.md) -- [返回模块目录](../Platform.md) +- [IPlatform](IPlatform.md) +- [IWindow](../IWindow/IWindow.md) +- [PlatformTypes](../PlatformTypes/PlatformTypes.md) diff --git a/docs/api/XCEngine/Platform/IPlatform/Destructor.md b/docs/api/XCEngine/Platform/IPlatform/Destructor.md index 3e77532c..c63ac88b 100644 --- a/docs/api/XCEngine/Platform/IPlatform/Destructor.md +++ b/docs/api/XCEngine/Platform/IPlatform/Destructor.md @@ -1,29 +1,26 @@ # IPlatform::~IPlatform() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IPlatform.h` + +## 签名 ```cpp virtual ~IPlatform() = default; ``` -该方法声明于 `XCEngine/Platform/IPlatform.h`，当前页面用于固定 `IPlatform` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +允许通过基类指针安全销毁具体平台实现。 -**返回：** `void` - 无返回值。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IPlatform object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 析构函数本身没有额外逻辑。 +- 真实平台级资源释放由派生类承担。 ## 相关文档 -- [返回类总览](IPlatform.md) -- [返回模块目录](../Platform.md) +- [IPlatform](IPlatform.md) diff --git a/docs/api/XCEngine/Platform/IPlatform/Get.md b/docs/api/XCEngine/Platform/IPlatform/Get.md index 6f76e280..23e25b10 100644 --- a/docs/api/XCEngine/Platform/IPlatform/Get.md +++ b/docs/api/XCEngine/Platform/IPlatform/Get.md @@ -1,29 +1,28 @@ # IPlatform::Get -获取相关状态或对象。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IPlatform.h` + +## 签名 ```cpp static IPlatform& Get(); ``` -该方法声明于 `XCEngine/Platform/IPlatform.h`，当前页面用于固定 `IPlatform` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回当前激活的平台单例。 -**返回：** `IPlatform&` - 返回值语义详见头文件声明。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - auto& instance = XCEngine::Platform::IPlatform::Get(); - (void)instance; -} -``` +- 这是静态访问入口，不要求调用方自己持有平台对象。 +- 平台实例的创建、注册和生命周期不由这个接口页定义，而由平台启动流程决定。 ## 相关文档 -- [返回类总览](IPlatform.md) -- [返回模块目录](../Platform.md) +- [IPlatform](IPlatform.md) +- [CreateWindow](CreateWindow.md) +- [PumpPlatformMessages](PumpPlatformMessages.md) diff --git a/docs/api/XCEngine/Platform/IPlatform/GetName.md b/docs/api/XCEngine/Platform/IPlatform/GetName.md index 03262b24..57e6fcf9 100644 --- a/docs/api/XCEngine/Platform/IPlatform/GetName.md +++ b/docs/api/XCEngine/Platform/IPlatform/GetName.md @@ -1,30 +1,27 @@ # IPlatform::GetName -获取相关状态或对象。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IPlatform.h` + +## 签名 ```cpp virtual const char* GetName() const = 0; ``` -该方法声明于 `XCEngine/Platform/IPlatform.h`，当前页面用于固定 `IPlatform` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回平台实现的人类可读名称。 -**返回：** `const char*` - 返回值语义详见头文件声明。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IPlatform object; - // 根据上下文补齐参数后调用 IPlatform::GetName(...)。 - (void)object; -} -``` +- 返回值通常用于日志、调试输出或平台识别展示。 +- 字符串内存由具体平台实现持有。 ## 相关文档 -- [返回类总览](IPlatform.md) -- [返回模块目录](../Platform.md) +- [IPlatform](IPlatform.md) +- [GetType](GetType.md) diff --git a/docs/api/XCEngine/Platform/IPlatform/GetType.md b/docs/api/XCEngine/Platform/IPlatform/GetType.md index 95064d09..8212eec7 100644 --- a/docs/api/XCEngine/Platform/IPlatform/GetType.md +++ b/docs/api/XCEngine/Platform/IPlatform/GetType.md @@ -1,30 +1,28 @@ # IPlatform::GetType -获取相关状态或对象。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IPlatform.h` + +## 签名 ```cpp virtual PlatformType GetType() const = 0; ``` -该方法声明于 `XCEngine/Platform/IPlatform.h`，当前页面用于固定 `IPlatform` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回平台类型枚举。 -**返回：** `PlatformType` - 返回值语义详见头文件声明。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IPlatform object; - // 根据上下文补齐参数后调用 IPlatform::GetType(...)。 - (void)object; -} -``` +- 结果用于做平台分支判断，而不是展示给用户。 +- 这是只读查询。 ## 相关文档 -- [返回类总览](IPlatform.md) -- [返回模块目录](../Platform.md) +- [IPlatform](IPlatform.md) +- [GetName](GetName.md) +- [PlatformTypes](../PlatformTypes/PlatformTypes.md) diff --git a/docs/api/XCEngine/Platform/IPlatform/IPlatform.md b/docs/api/XCEngine/Platform/IPlatform/IPlatform.md index 7603cc9d..1cb7f146 100644 --- a/docs/api/XCEngine/Platform/IPlatform/IPlatform.md +++ b/docs/api/XCEngine/Platform/IPlatform/IPlatform.md @@ -6,34 +6,48 @@ **头文件**: `XCEngine/Platform/IPlatform.h` -**描述**: 定义 `XCEngine/Platform` 子目录中的 `IPlatform` public API。 +**描述**: 平台服务总入口，负责创建窗口、文件系统、时钟、动态库和显示器枚举器，并驱动平台消息泵。 ## 概述 -`IPlatform.h` 是 `XCEngine/Platform` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。 +`IPlatform` 把平台相关能力集中在一个统一入口上。它本身不直接实现具体功能，而是提供两类能力： + +- 平台身份查询 + - `GetName()` + - `GetType()` +- 平台对象工厂 + - `CreateWindow(...)` + - `CreateFileSystem()` + - `CreateClock()` + - `LoadDynamicLibrary(...)` + - `CreateDisplayEnumerator()` + +同时，`PumpPlatformMessages()` 负责让主循环显式处理平台消息，`Get()` 则暴露当前激活的平台单例。 ## 声明概览 | 声明 | 类型 | 说明 | |------|------|------| -| `IPlatform` | `class` | 头文件中的公开声明。 | +| `IPlatform` | `class` | 平台抽象总入口。 | ## 公共方法 | 方法 | 描述 | |------|------| -| [~IPlatform()](Destructor.md) | 销毁对象并释放相关资源。 | -| [GetName](GetName.md) | 获取相关状态或对象。 | -| [GetType](GetType.md) | 获取相关状态或对象。 | -| [CreateWindow](CreateWindow.md) | 创建新对象或资源。 | -| [CreateFileSystem](CreateFileSystem.md) | 创建新对象或资源。 | -| [CreateClock](CreateClock.md) | 创建新对象或资源。 | -| [LoadDynamicLibrary](LoadDynamicLibrary.md) | 加载资源或数据。 | -| [CreateDisplayEnumerator](CreateDisplayEnumerator.md) | 创建新对象或资源。 | -| [PumpPlatformMessages](PumpPlatformMessages.md) | 公开方法，详见头文件声明。 | -| [Get](Get.md) | 获取相关状态或对象。 | +| [~IPlatform()](Destructor.md) | 通过基类指针安全销毁具体平台实现。 | +| [GetName](GetName.md) | 返回平台名称字符串。 | +| [GetType](GetType.md) | 返回平台类型枚举。 | +| [CreateWindow](CreateWindow.md) | 创建一个平台窗口实现。 | +| [CreateFileSystem](CreateFileSystem.md) | 创建一个平台文件系统实现。 | +| [CreateClock](CreateClock.md) | 创建一个平台时钟实现。 | +| [LoadDynamicLibrary](LoadDynamicLibrary.md) | 加载并返回一个动态库对象。 | +| [CreateDisplayEnumerator](CreateDisplayEnumerator.md) | 创建一个显示器枚举器实现。 | +| [PumpPlatformMessages](PumpPlatformMessages.md) | 处理平台主消息循环。 | +| [Get](Get.md) | 返回当前激活的平台单例。 | ## 相关文档 -- [当前目录](../Platform.md) - 返回 `Platform` 平行目录 -- [API 总索引](../../../main.md) - 返回顶层索引 +- [Platform](../Platform.md) +- [IWindow](../IWindow/IWindow.md) +- [IFileSystem](../IFileSystem/IFileSystem.md) +- [IClock](../IClock/IClock.md) diff --git a/docs/api/XCEngine/Platform/IPlatform/LoadDynamicLibrary.md b/docs/api/XCEngine/Platform/IPlatform/LoadDynamicLibrary.md index bc2e0fde..e4596e4f 100644 --- a/docs/api/XCEngine/Platform/IPlatform/LoadDynamicLibrary.md +++ b/docs/api/XCEngine/Platform/IPlatform/LoadDynamicLibrary.md @@ -1,31 +1,27 @@ # IPlatform::LoadDynamicLibrary -加载资源或数据。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IPlatform.h` + +## 签名 ```cpp virtual std::unique_ptr LoadDynamicLibrary(const char* path) = 0; ``` -该方法声明于 `XCEngine/Platform/IPlatform.h`，当前页面用于固定 `IPlatform` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `path` - 参数语义详见头文件声明。 +按路径加载一份动态库，并返回对应的动态库对象。 -**返回：** `std::unique_ptr` - 返回值语义详见头文件声明。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IPlatform object; - // 根据上下文补齐参数后调用 IPlatform::LoadDynamicLibrary(...)。 - (void)object; -} -``` +- `path` 是目标动态库文件路径。 +- 返回值是带独占所有权的 `std::unique_ptr`。 ## 相关文档 -- [返回类总览](IPlatform.md) -- [返回模块目录](../Platform.md) +- [IPlatform](IPlatform.md) +- [IDynamicLibrary](../IDynamicLibrary/IDynamicLibrary.md) diff --git a/docs/api/XCEngine/Platform/IPlatform/PumpPlatformMessages.md b/docs/api/XCEngine/Platform/IPlatform/PumpPlatformMessages.md index 55ba22b7..5414eccb 100644 --- a/docs/api/XCEngine/Platform/IPlatform/PumpPlatformMessages.md +++ b/docs/api/XCEngine/Platform/IPlatform/PumpPlatformMessages.md @@ -1,30 +1,28 @@ # IPlatform::PumpPlatformMessages -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IPlatform.h` + +## 签名 ```cpp virtual void PumpPlatformMessages() = 0; ``` -该方法声明于 `XCEngine/Platform/IPlatform.h`，当前页面用于固定 `IPlatform` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +处理平台层挂起的主消息队列。 -**返回：** `void` - 无返回值。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IPlatform object; - // 根据上下文补齐参数后调用 IPlatform::PumpPlatformMessages(...)。 - (void)object; -} -``` +- 主循环通常需要周期性调用它，避免窗口、输入或平台回调饿死。 +- 具体会泵哪些消息，以及是否转发到窗口对象，由平台实现决定。 ## 相关文档 -- [返回类总览](IPlatform.md) -- [返回模块目录](../Platform.md) +- [IPlatform](IPlatform.md) +- [Get](Get.md) +- [CreateWindow](CreateWindow.md) diff --git a/docs/api/XCEngine/Platform/IWindow/Create.md b/docs/api/XCEngine/Platform/IWindow/Create.md index dd882292..703040f9 100644 --- a/docs/api/XCEngine/Platform/IWindow/Create.md +++ b/docs/api/XCEngine/Platform/IWindow/Create.md @@ -1,31 +1,28 @@ # IWindow::Create -创建新对象或资源。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IWindow.h` + +## 签名 ```cpp virtual bool Create(const WindowDesc& desc) = 0; ``` -该方法声明于 `XCEngine/Platform/IWindow.h`，当前页面用于固定 `IWindow` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `desc` - 参数语义详见头文件声明。 +按 `WindowDesc` 创建底层平台窗口。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IWindow object; - // 根据上下文补齐参数后调用 IWindow::Create(...)。 - (void)object; -} -``` +- `desc` 提供标题、尺寸和全屏初始参数。 +- 返回值表示创建是否成功。 ## 相关文档 -- [返回类总览](IWindow.md) -- [返回模块目录](../Platform.md) +- [IWindow](IWindow.md) +- [Destroy](Destroy.md) +- [PlatformTypes](../PlatformTypes/PlatformTypes.md) diff --git a/docs/api/XCEngine/Platform/IWindow/Destroy.md b/docs/api/XCEngine/Platform/IWindow/Destroy.md index f40610f7..13caec84 100644 --- a/docs/api/XCEngine/Platform/IWindow/Destroy.md +++ b/docs/api/XCEngine/Platform/IWindow/Destroy.md @@ -1,30 +1,28 @@ # IWindow::Destroy -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IWindow.h` + +## 签名 ```cpp virtual void Destroy() = 0; ``` -该方法声明于 `XCEngine/Platform/IWindow.h`，当前页面用于固定 `IWindow` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +释放窗口对象持有的原生窗口资源。 -**返回：** `void` - 无返回值。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IWindow object; - // 根据上下文补齐参数后调用 IWindow::Destroy(...)。 - (void)object; -} -``` +- 这是纯虚接口，具体销毁范围和顺序由平台实现决定。 +- 调用后窗口通常不再有效；如果需要再次使用，应重新 [Create](Create.md)。 ## 相关文档 -- [返回类总览](IWindow.md) -- [返回模块目录](../Platform.md) +- [IWindow](IWindow.md) +- [Create](Create.md) +- [IsValid](IsValid.md) diff --git a/docs/api/XCEngine/Platform/IWindow/Destructor.md b/docs/api/XCEngine/Platform/IWindow/Destructor.md index 53312697..641f999f 100644 --- a/docs/api/XCEngine/Platform/IWindow/Destructor.md +++ b/docs/api/XCEngine/Platform/IWindow/Destructor.md @@ -1,29 +1,27 @@ # IWindow::~IWindow() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IWindow.h` + +## 签名 ```cpp virtual ~IWindow() = default; ``` -该方法声明于 `XCEngine/Platform/IWindow.h`，当前页面用于固定 `IWindow` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +允许通过基类指针安全销毁具体窗口实现。 -**返回：** `void` - 无返回值。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IWindow object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 析构函数本身没有额外逻辑。 +- 真实窗口资源清理由派生类完成。 ## 相关文档 -- [返回类总览](IWindow.md) -- [返回模块目录](../Platform.md) +- [IWindow](IWindow.md) +- [Destroy](Destroy.md) diff --git a/docs/api/XCEngine/Platform/IWindow/GetHeight.md b/docs/api/XCEngine/Platform/IWindow/GetHeight.md index 2158284a..d22d5496 100644 --- a/docs/api/XCEngine/Platform/IWindow/GetHeight.md +++ b/docs/api/XCEngine/Platform/IWindow/GetHeight.md @@ -1,30 +1,28 @@ # IWindow::GetHeight -获取相关状态或对象。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IWindow.h` + +## 签名 ```cpp virtual Core::uint32_t GetHeight() const = 0; ``` -该方法声明于 `XCEngine/Platform/IWindow.h`，当前页面用于固定 `IWindow` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回当前窗口客户区高度。 -**返回：** `Core::uint32_t` - 返回值语义详见头文件声明。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IWindow object; - // 根据上下文补齐参数后调用 IWindow::GetHeight(...)。 - (void)object; -} -``` +- 这是只读查询。 +- 返回值来源于具体平台实现维护的当前窗口状态。 ## 相关文档 -- [返回类总览](IWindow.md) -- [返回模块目录](../Platform.md) +- [IWindow](IWindow.md) +- [GetWidth](GetWidth.md) +- [SetResizeCallback](SetResizeCallback.md) diff --git a/docs/api/XCEngine/Platform/IWindow/GetNativeHandle.md b/docs/api/XCEngine/Platform/IWindow/GetNativeHandle.md index 651a8a82..bb35c7d6 100644 --- a/docs/api/XCEngine/Platform/IWindow/GetNativeHandle.md +++ b/docs/api/XCEngine/Platform/IWindow/GetNativeHandle.md @@ -1,30 +1,27 @@ # IWindow::GetNativeHandle -获取相关状态或对象。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IWindow.h` + +## 签名 ```cpp virtual WindowHandle GetNativeHandle() const = 0; ``` -该方法声明于 `XCEngine/Platform/IWindow.h`，当前页面用于固定 `IWindow` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回底层平台窗口句柄。 -**返回：** `WindowHandle` - 返回值语义详见头文件声明。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IWindow object; - // 根据上下文补齐参数后调用 IWindow::GetNativeHandle(...)。 - (void)object; -} -``` +- 句柄的具体类型由 `WindowHandle` 决定，当前别名是 `void*`。 +- 该句柄通常用于和原生窗口系统或图形后端做对接。 ## 相关文档 -- [返回类总览](IWindow.md) -- [返回模块目录](../Platform.md) +- [IWindow](IWindow.md) +- [PlatformTypes](../PlatformTypes/PlatformTypes.md) diff --git a/docs/api/XCEngine/Platform/IWindow/GetWidth.md b/docs/api/XCEngine/Platform/IWindow/GetWidth.md index 40dd3d62..67a9e59a 100644 --- a/docs/api/XCEngine/Platform/IWindow/GetWidth.md +++ b/docs/api/XCEngine/Platform/IWindow/GetWidth.md @@ -1,30 +1,28 @@ # IWindow::GetWidth -获取相关状态或对象。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IWindow.h` + +## 签名 ```cpp virtual Core::uint32_t GetWidth() const = 0; ``` -该方法声明于 `XCEngine/Platform/IWindow.h`，当前页面用于固定 `IWindow` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回当前窗口客户区宽度。 -**返回：** `Core::uint32_t` - 返回值语义详见头文件声明。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IWindow object; - // 根据上下文补齐参数后调用 IWindow::GetWidth(...)。 - (void)object; -} -``` +- 这是只读查询。 +- 返回值来源于具体平台实现维护的当前窗口状态。 ## 相关文档 -- [返回类总览](IWindow.md) -- [返回模块目录](../Platform.md) +- [IWindow](IWindow.md) +- [GetHeight](GetHeight.md) +- [SetResizeCallback](SetResizeCallback.md) diff --git a/docs/api/XCEngine/Platform/IWindow/IWindow.md b/docs/api/XCEngine/Platform/IWindow/IWindow.md index ce7c0a93..76804059 100644 --- a/docs/api/XCEngine/Platform/IWindow/IWindow.md +++ b/docs/api/XCEngine/Platform/IWindow/IWindow.md @@ -6,44 +6,55 @@ **头文件**: `XCEngine/Platform/IWindow.h` -**描述**: 定义 `XCEngine/Platform` 子目录中的 `IWindow` public API。 +**描述**: 平台窗口接口，覆盖窗口生命周期、原生句柄访问、消息处理、标题/全屏/VSync 状态和关闭/尺寸回调。 ## 概述 -`IWindow.h` 是 `XCEngine/Platform` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。 +`IWindow` 描述的是“平台窗口最小公共能力”。它不关心渲染后端，也不负责输入系统本身，只约定窗口对象需要提供哪些基础操作： + +- 创建、销毁和有效性查询 +- 原生句柄访问 +- 平台事件泵 +- 标题、全屏、最小化 / 最大化 / 恢复 +- VSync 开关 +- 尺寸与关闭状态查询 +- 关闭和尺寸变化回调 + +具体平台实现通常由 [IPlatform](../IPlatform/IPlatform.md) 创建。 ## 声明概览 | 声明 | 类型 | 说明 | |------|------|------| -| `IWindow` | `class` | 头文件中的公开声明。 | +| `IWindow` | `class` | 平台窗口抽象接口。 | ## 公共方法 | 方法 | 描述 | |------|------| -| [~IWindow()](Destructor.md) | 销毁对象并释放相关资源。 | -| [Create](Create.md) | 创建新对象或资源。 | -| [Destroy](Destroy.md) | 公开方法，详见头文件声明。 | -| [IsValid](IsValid.md) | 查询当前状态。 | -| [GetNativeHandle](GetNativeHandle.md) | 获取相关状态或对象。 | -| [PumpEvents](PumpEvents.md) | 公开方法，详见头文件声明。 | -| [SetTitle](SetTitle.md) | 设置相关状态或配置。 | -| [SetFullscreen](SetFullscreen.md) | 设置相关状态或配置。 | -| [IsFullscreen](IsFullscreen.md) | 查询当前状态。 | -| [Minimize](Minimize.md) | 公开方法，详见头文件声明。 | -| [Maximize](Maximize.md) | 公开方法，详见头文件声明。 | -| [Restore](Restore.md) | 公开方法，详见头文件声明。 | -| [SetVSync](SetVSync.md) | 设置相关状态或配置。 | -| [IsVSync](IsVSync.md) | 查询当前状态。 | -| [GetWidth](GetWidth.md) | 获取相关状态或对象。 | -| [GetHeight](GetHeight.md) | 获取相关状态或对象。 | -| [ShouldClose](ShouldClose.md) | 公开方法，详见头文件声明。 | -| [SetShouldClose](SetShouldClose.md) | 设置相关状态或配置。 | -| [SetCloseCallback](SetCloseCallback.md) | 设置相关状态或配置。 | -| [SetResizeCallback](SetResizeCallback.md) | 设置相关状态或配置。 | +| [~IWindow()](Destructor.md) | 通过基类指针安全销毁具体窗口实现。 | +| [Create](Create.md) | 按 `WindowDesc` 创建窗口。 | +| [Destroy](Destroy.md) | 销毁窗口及其平台资源。 | +| [IsValid](IsValid.md) | 查询窗口是否已成功创建且仍有效。 | +| [GetNativeHandle](GetNativeHandle.md) | 返回平台相关的原生窗口句柄。 | +| [PumpEvents](PumpEvents.md) | 处理挂起的窗口事件。 | +| [SetTitle](SetTitle.md) | 修改窗口标题。 | +| [SetFullscreen](SetFullscreen.md) | 切换全屏状态。 | +| [IsFullscreen](IsFullscreen.md) | 查询当前是否处于全屏。 | +| [Minimize](Minimize.md) | 最小化窗口。 | +| [Maximize](Maximize.md) | 最大化窗口。 | +| [Restore](Restore.md) | 从最小化或最大化恢复窗口。 | +| [SetVSync](SetVSync.md) | 设置窗口呈现相关的 VSync 开关。 | +| [IsVSync](IsVSync.md) | 查询 VSync 是否开启。 | +| [GetWidth](GetWidth.md) | 返回当前窗口宽度。 | +| [GetHeight](GetHeight.md) | 返回当前窗口高度。 | +| [ShouldClose](ShouldClose.md) | 查询窗口是否收到关闭请求。 | +| [SetShouldClose](SetShouldClose.md) | 主动标记窗口应关闭。 | +| [SetCloseCallback](SetCloseCallback.md) | 设置关闭事件回调。 | +| [SetResizeCallback](SetResizeCallback.md) | 设置尺寸变化回调。 | ## 相关文档 -- [当前目录](../Platform.md) - 返回 `Platform` 平行目录 -- [API 总索引](../../../main.md) - 返回顶层索引 +- [Platform](../Platform.md) +- [IPlatform](../IPlatform/IPlatform.md) +- [PlatformTypes](../PlatformTypes/PlatformTypes.md) diff --git a/docs/api/XCEngine/Platform/IWindow/IsFullscreen.md b/docs/api/XCEngine/Platform/IWindow/IsFullscreen.md index 9ada3279..b604589e 100644 --- a/docs/api/XCEngine/Platform/IWindow/IsFullscreen.md +++ b/docs/api/XCEngine/Platform/IWindow/IsFullscreen.md @@ -1,30 +1,27 @@ # IWindow::IsFullscreen -查询当前状态。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IWindow.h` + +## 签名 ```cpp virtual bool IsFullscreen() const = 0; ``` -该方法声明于 `XCEngine/Platform/IWindow.h`，当前页面用于固定 `IWindow` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +查询窗口当前是否处于全屏状态。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IWindow object; - // 根据上下文补齐参数后调用 IWindow::IsFullscreen(...)。 - (void)object; -} -``` +- 这是只读状态查询。 +- 具体状态来源由平台实现维护。 ## 相关文档 -- [返回类总览](IWindow.md) -- [返回模块目录](../Platform.md) +- [IWindow](IWindow.md) +- [SetFullscreen](SetFullscreen.md) diff --git a/docs/api/XCEngine/Platform/IWindow/IsVSync.md b/docs/api/XCEngine/Platform/IWindow/IsVSync.md index 07ba4d05..9781f125 100644 --- a/docs/api/XCEngine/Platform/IWindow/IsVSync.md +++ b/docs/api/XCEngine/Platform/IWindow/IsVSync.md @@ -1,30 +1,27 @@ # IWindow::IsVSync -查询当前状态。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IWindow.h` + +## 签名 ```cpp virtual bool IsVSync() const = 0; ``` -该方法声明于 `XCEngine/Platform/IWindow.h`，当前页面用于固定 `IWindow` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +查询窗口当前是否启用了 VSync。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IWindow object; - // 根据上下文补齐参数后调用 IWindow::IsVSync(...)。 - (void)object; -} -``` +- 这是只读状态查询。 +- VSync 的真实实现可能在交换链或呈现层，但状态入口暴露在窗口接口上。 ## 相关文档 -- [返回类总览](IWindow.md) -- [返回模块目录](../Platform.md) +- [IWindow](IWindow.md) +- [SetVSync](SetVSync.md) diff --git a/docs/api/XCEngine/Platform/IWindow/IsValid.md b/docs/api/XCEngine/Platform/IWindow/IsValid.md index aba83f1b..213192d9 100644 --- a/docs/api/XCEngine/Platform/IWindow/IsValid.md +++ b/docs/api/XCEngine/Platform/IWindow/IsValid.md @@ -1,30 +1,28 @@ # IWindow::IsValid -查询当前状态。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IWindow.h` + +## 签名 ```cpp virtual bool IsValid() const = 0; ``` -该方法声明于 `XCEngine/Platform/IWindow.h`，当前页面用于固定 `IWindow` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +查询窗口对象当前是否已经成功创建并处于可用状态。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IWindow object; - // 根据上下文补齐参数后调用 IWindow::IsValid(...)。 - (void)object; -} -``` +- 这是只读状态查询。 +- 具体判定标准由平台实现决定。 ## 相关文档 -- [返回类总览](IWindow.md) -- [返回模块目录](../Platform.md) +- [IWindow](IWindow.md) +- [Create](Create.md) +- [Destroy](Destroy.md) diff --git a/docs/api/XCEngine/Platform/IWindow/Maximize.md b/docs/api/XCEngine/Platform/IWindow/Maximize.md index d28db1b2..e7ba5864 100644 --- a/docs/api/XCEngine/Platform/IWindow/Maximize.md +++ b/docs/api/XCEngine/Platform/IWindow/Maximize.md @@ -1,30 +1,28 @@ # IWindow::Maximize -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IWindow.h` + +## 签名 ```cpp virtual void Maximize() = 0; ``` -该方法声明于 `XCEngine/Platform/IWindow.h`，当前页面用于固定 `IWindow` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +请求平台实现把窗口切到最大化状态。 -**返回：** `void` - 无返回值。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IWindow object; - // 根据上下文补齐参数后调用 IWindow::Maximize(...)。 - (void)object; -} -``` +- 是否立即生效以及是否触发尺寸回调，由具体平台实现决定。 +- 该调用本身不要求切换全屏。 ## 相关文档 -- [返回类总览](IWindow.md) -- [返回模块目录](../Platform.md) +- [IWindow](IWindow.md) +- [Minimize](Minimize.md) +- [Restore](Restore.md) diff --git a/docs/api/XCEngine/Platform/IWindow/Minimize.md b/docs/api/XCEngine/Platform/IWindow/Minimize.md index ddbcc17d..88a2e149 100644 --- a/docs/api/XCEngine/Platform/IWindow/Minimize.md +++ b/docs/api/XCEngine/Platform/IWindow/Minimize.md @@ -1,30 +1,28 @@ # IWindow::Minimize -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IWindow.h` + +## 签名 ```cpp virtual void Minimize() = 0; ``` -该方法声明于 `XCEngine/Platform/IWindow.h`，当前页面用于固定 `IWindow` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +请求平台实现把窗口最小化。 -**返回：** `void` - 无返回值。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IWindow object; - // 根据上下文补齐参数后调用 IWindow::Minimize(...)。 - (void)object; -} -``` +- 是否立即生效由具体平台实现决定。 +- 最小化后的恢复通常由 [Restore](Restore.md) 或用户的窗口操作触发。 ## 相关文档 -- [返回类总览](IWindow.md) -- [返回模块目录](../Platform.md) +- [IWindow](IWindow.md) +- [Maximize](Maximize.md) +- [Restore](Restore.md) diff --git a/docs/api/XCEngine/Platform/IWindow/PumpEvents.md b/docs/api/XCEngine/Platform/IWindow/PumpEvents.md index e4a6f488..f4c104ff 100644 --- a/docs/api/XCEngine/Platform/IWindow/PumpEvents.md +++ b/docs/api/XCEngine/Platform/IWindow/PumpEvents.md @@ -1,30 +1,28 @@ # IWindow::PumpEvents -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IWindow.h` + +## 签名 ```cpp virtual void PumpEvents() = 0; ``` -该方法声明于 `XCEngine/Platform/IWindow.h`，当前页面用于固定 `IWindow` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +处理窗口挂起的原生事件。 -**返回：** `void` - 无返回值。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IWindow object; - // 根据上下文补齐参数后调用 IWindow::PumpEvents(...)。 - (void)object; -} -``` +- 主循环通常需要周期性调用它，才能让关闭标记、尺寸变化和输入桥接及时更新。 +- 具体处理哪些消息以及是否触发回调，由平台实现决定。 ## 相关文档 -- [返回类总览](IWindow.md) -- [返回模块目录](../Platform.md) +- [IWindow](IWindow.md) +- [ShouldClose](ShouldClose.md) +- [SetResizeCallback](SetResizeCallback.md) diff --git a/docs/api/XCEngine/Platform/IWindow/Restore.md b/docs/api/XCEngine/Platform/IWindow/Restore.md index 9cf93e55..07d0329f 100644 --- a/docs/api/XCEngine/Platform/IWindow/Restore.md +++ b/docs/api/XCEngine/Platform/IWindow/Restore.md @@ -1,30 +1,28 @@ # IWindow::Restore -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IWindow.h` + +## 签名 ```cpp virtual void Restore() = 0; ``` -该方法声明于 `XCEngine/Platform/IWindow.h`，当前页面用于固定 `IWindow` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +把窗口从最小化或最大化状态恢复到普通窗口状态。 -**返回：** `void` - 无返回值。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IWindow object; - // 根据上下文补齐参数后调用 IWindow::Restore(...)。 - (void)object; -} -``` +- 该调用不等同于退出全屏；全屏切换由 [SetFullscreen](SetFullscreen.md) 负责。 +- 实际恢复行为由平台实现决定。 ## 相关文档 -- [返回类总览](IWindow.md) -- [返回模块目录](../Platform.md) +- [IWindow](IWindow.md) +- [Minimize](Minimize.md) +- [Maximize](Maximize.md) diff --git a/docs/api/XCEngine/Platform/IWindow/SetCloseCallback.md b/docs/api/XCEngine/Platform/IWindow/SetCloseCallback.md index 9291045e..514e6a34 100644 --- a/docs/api/XCEngine/Platform/IWindow/SetCloseCallback.md +++ b/docs/api/XCEngine/Platform/IWindow/SetCloseCallback.md @@ -1,31 +1,27 @@ # IWindow::SetCloseCallback -设置相关状态或配置。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IWindow.h` + +## 签名 ```cpp virtual void SetCloseCallback(CloseCallback callback) = 0; ``` -该方法声明于 `XCEngine/Platform/IWindow.h`，当前页面用于固定 `IWindow` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `callback` - 参数语义详见头文件声明。 +注册窗口关闭事件回调。 -**返回：** `void` - 无返回值。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IWindow object; - // 根据上下文补齐参数后调用 IWindow::SetCloseCallback(...)。 - (void)object; -} -``` +- `callback` 是一个 `std::function`。 +- 何时触发、是否允许覆盖旧回调，由平台实现决定。 ## 相关文档 -- [返回类总览](IWindow.md) -- [返回模块目录](../Platform.md) +- [IWindow](IWindow.md) +- [ShouldClose](ShouldClose.md) diff --git a/docs/api/XCEngine/Platform/IWindow/SetFullscreen.md b/docs/api/XCEngine/Platform/IWindow/SetFullscreen.md index 186f5846..b0837272 100644 --- a/docs/api/XCEngine/Platform/IWindow/SetFullscreen.md +++ b/docs/api/XCEngine/Platform/IWindow/SetFullscreen.md @@ -1,31 +1,27 @@ # IWindow::SetFullscreen -设置相关状态或配置。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IWindow.h` + +## 签名 ```cpp virtual void SetFullscreen(bool fullscreen) = 0; ``` -该方法声明于 `XCEngine/Platform/IWindow.h`，当前页面用于固定 `IWindow` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `fullscreen` - 参数语义详见头文件声明。 +切换窗口是否处于全屏状态。 -**返回：** `void` - 无返回值。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IWindow object; - // 根据上下文补齐参数后调用 IWindow::SetFullscreen(...)。 - (void)object; -} -``` +- `fullscreen == true` 表示请求进入全屏，`false` 表示退出全屏。 +- 具体切换方式和副作用由平台实现决定。 ## 相关文档 -- [返回类总览](IWindow.md) -- [返回模块目录](../Platform.md) +- [IWindow](IWindow.md) +- [IsFullscreen](IsFullscreen.md) diff --git a/docs/api/XCEngine/Platform/IWindow/SetResizeCallback.md b/docs/api/XCEngine/Platform/IWindow/SetResizeCallback.md index 09b5e754..8c4f7348 100644 --- a/docs/api/XCEngine/Platform/IWindow/SetResizeCallback.md +++ b/docs/api/XCEngine/Platform/IWindow/SetResizeCallback.md @@ -1,31 +1,28 @@ # IWindow::SetResizeCallback -设置相关状态或配置。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IWindow.h` + +## 签名 ```cpp virtual void SetResizeCallback(ResizeCallback callback) = 0; ``` -该方法声明于 `XCEngine/Platform/IWindow.h`，当前页面用于固定 `IWindow` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `callback` - 参数语义详见头文件声明。 +注册窗口尺寸变化回调。 -**返回：** `void` - 无返回值。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IWindow object; - // 根据上下文补齐参数后调用 IWindow::SetResizeCallback(...)。 - (void)object; -} -``` +- `callback` 是一个 `std::function`。 +- 回调通常接收新的宽高，但具体触发时机由平台实现决定。 ## 相关文档 -- [返回类总览](IWindow.md) -- [返回模块目录](../Platform.md) +- [IWindow](IWindow.md) +- [GetWidth](GetWidth.md) +- [GetHeight](GetHeight.md) diff --git a/docs/api/XCEngine/Platform/IWindow/SetShouldClose.md b/docs/api/XCEngine/Platform/IWindow/SetShouldClose.md index bffa0a37..026cb6fb 100644 --- a/docs/api/XCEngine/Platform/IWindow/SetShouldClose.md +++ b/docs/api/XCEngine/Platform/IWindow/SetShouldClose.md @@ -1,31 +1,27 @@ # IWindow::SetShouldClose -设置相关状态或配置。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IWindow.h` + +## 签名 ```cpp virtual void SetShouldClose(bool shouldClose) = 0; ``` -该方法声明于 `XCEngine/Platform/IWindow.h`，当前页面用于固定 `IWindow` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `shouldClose` - 参数语义详见头文件声明。 +主动设置窗口的关闭标记。 -**返回：** `void` - 无返回值。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IWindow object; - // 根据上下文补齐参数后调用 IWindow::SetShouldClose(...)。 - (void)object; -} -``` +- `shouldClose == true` 常用于请求主循环尽快退出。 +- 该标记后续可通过 [ShouldClose](ShouldClose.md) 读取。 ## 相关文档 -- [返回类总览](IWindow.md) -- [返回模块目录](../Platform.md) +- [IWindow](IWindow.md) +- [ShouldClose](ShouldClose.md) diff --git a/docs/api/XCEngine/Platform/IWindow/SetTitle.md b/docs/api/XCEngine/Platform/IWindow/SetTitle.md index 89b585d3..02cc295b 100644 --- a/docs/api/XCEngine/Platform/IWindow/SetTitle.md +++ b/docs/api/XCEngine/Platform/IWindow/SetTitle.md @@ -1,31 +1,27 @@ # IWindow::SetTitle -设置相关状态或配置。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IWindow.h` + +## 签名 ```cpp virtual void SetTitle(const Containers::String& title) = 0; ``` -该方法声明于 `XCEngine/Platform/IWindow.h`，当前页面用于固定 `IWindow` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `title` - 参数语义详见头文件声明。 +修改窗口标题。 -**返回：** `void` - 无返回值。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IWindow object; - // 根据上下文补齐参数后调用 IWindow::SetTitle(...)。 - (void)object; -} -``` +- `title` 是新的标题字符串。 +- 标题如何同步到原生窗口系统由平台实现决定。 ## 相关文档 -- [返回类总览](IWindow.md) -- [返回模块目录](../Platform.md) +- [IWindow](IWindow.md) +- [Create](Create.md) diff --git a/docs/api/XCEngine/Platform/IWindow/SetVSync.md b/docs/api/XCEngine/Platform/IWindow/SetVSync.md index 8edbb331..1475333a 100644 --- a/docs/api/XCEngine/Platform/IWindow/SetVSync.md +++ b/docs/api/XCEngine/Platform/IWindow/SetVSync.md @@ -1,31 +1,27 @@ # IWindow::SetVSync -设置相关状态或配置。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IWindow.h` + +## 签名 ```cpp virtual void SetVSync(bool enabled) = 0; ``` -该方法声明于 `XCEngine/Platform/IWindow.h`，当前页面用于固定 `IWindow` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `enabled` - 参数语义详见头文件声明。 +切换窗口呈现路径上的 VSync 开关。 -**返回：** `void` - 无返回值。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IWindow object; - // 根据上下文补齐参数后调用 IWindow::SetVSync(...)。 - (void)object; -} -``` +- `enabled == true` 表示请求开启 VSync，`false` 表示关闭。 +- 具体由窗口直接处理还是转交交换链，由平台实现决定。 ## 相关文档 -- [返回类总览](IWindow.md) -- [返回模块目录](../Platform.md) +- [IWindow](IWindow.md) +- [IsVSync](IsVSync.md) diff --git a/docs/api/XCEngine/Platform/IWindow/ShouldClose.md b/docs/api/XCEngine/Platform/IWindow/ShouldClose.md index 95fbdbb7..7f450096 100644 --- a/docs/api/XCEngine/Platform/IWindow/ShouldClose.md +++ b/docs/api/XCEngine/Platform/IWindow/ShouldClose.md @@ -1,30 +1,28 @@ # IWindow::ShouldClose -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/IWindow.h` + +## 签名 ```cpp virtual bool ShouldClose() const = 0; ``` -该方法声明于 `XCEngine/Platform/IWindow.h`，当前页面用于固定 `IWindow` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +查询窗口是否已经收到关闭请求。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::IWindow object; - // 根据上下文补齐参数后调用 IWindow::ShouldClose(...)。 - (void)object; -} -``` +- 关闭请求可能来自平台消息，也可能来自 [SetShouldClose](SetShouldClose.md) 的主动设置。 +- 这是主循环常用的退出判定接口。 ## 相关文档 -- [返回类总览](IWindow.md) -- [返回模块目录](../Platform.md) +- [IWindow](IWindow.md) +- [PumpEvents](PumpEvents.md) +- [SetShouldClose](SetShouldClose.md) diff --git a/docs/api/XCEngine/Platform/PlatformTypes/PlatformTypes.md b/docs/api/XCEngine/Platform/PlatformTypes/PlatformTypes.md index 6056a7ab..45dfe795 100644 --- a/docs/api/XCEngine/Platform/PlatformTypes/PlatformTypes.md +++ b/docs/api/XCEngine/Platform/PlatformTypes/PlatformTypes.md @@ -2,34 +2,56 @@ **命名空间**: `XCEngine::Platform` -**类型**: `struct` +**类型**: `header summary` **头文件**: `XCEngine/Platform/PlatformTypes.h` -**描述**: 定义 `XCEngine/Platform` 子目录中的 `PlatformTypes` public API。 +**描述**: 平台层共用基础类型，覆盖窗口句柄、窗口创建描述以及二维点 / 矩形结构。 ## 概述 -`PlatformTypes.h` 是 `XCEngine/Platform` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。 +`PlatformTypes.h` 放的是平台接口之间共享的轻量 POD / alias，而不是某一个独立系统。当前头文件主要提供三类基础数据： + +- `WindowHandle`：平台窗口句柄别名 +- `WindowDesc`：创建窗口时传入的标题、尺寸和全屏标记 +- `Point` / `Rect`：平台层和窗口代码会复用的二维几何结构 ## 声明概览 | 声明 | 类型 | 说明 | |------|------|------| -| `WindowDesc` | `struct` | 头文件中的公开声明。 | -| `Point` | `struct` | 头文件中的公开声明。 | -| `Rect` | `struct` | 头文件中的公开声明。 | +| `WindowHandle` | `using` | 平台窗口句柄别名，当前定义为 `void*`。 | +| `WindowDesc` | `struct` | 窗口创建参数。 | +| `Point` | `struct` | 二维整数点。 | +| `Rect` | `struct` | 二维整数矩形。 | -## 结构体成员 +## `WindowDesc` 成员 | 成员 | 类型 | 描述 | 默认值 | |------|------|------|--------| -| `title` | `Containers::String` | 结构体公开字段。 | - | -| `width` | `Core::uint32` | 结构体公开字段。 | - | -| `height` | `Core::uint32` | 结构体公开字段。 | - | -| `fullscreen` | `bool` | 结构体公开字段。 | - | +| `title` | `Containers::String` | 初始窗口标题。 | `"XCEngine"` | +| `width` | `Core::uint32` | 初始窗口宽度。 | `1280` | +| `height` | `Core::uint32` | 初始窗口高度。 | `720` | +| `fullscreen` | `bool` | 是否以全屏模式创建。 | `false` | + +## `Point` 成员 + +| 成员 | 类型 | 描述 | +|------|------|------| +| `x` | `Core::int32` | 横坐标。 | +| `y` | `Core::int32` | 纵坐标。 | + +## `Rect` 成员 + +| 成员 | 类型 | 描述 | +|------|------|------| +| `x` | `Core::int32` | 左上角横坐标。 | +| `y` | `Core::int32` | 左上角纵坐标。 | +| `width` | `Core::int32` | 矩形宽度。 | +| `height` | `Core::int32` | 矩形高度。 | ## 相关文档 -- [当前目录](../Platform.md) - 返回 `Platform` 平行目录 -- [API 总索引](../../../main.md) - 返回顶层索引 +- [Platform](../Platform.md) +- [IWindow](../IWindow/IWindow.md) +- [Window](../Window/Window.md) diff --git a/docs/api/XCEngine/Platform/Window/Create.md b/docs/api/XCEngine/Platform/Window/Create.md index a8e5d495..a6887083 100644 --- a/docs/api/XCEngine/Platform/Window/Create.md +++ b/docs/api/XCEngine/Platform/Window/Create.md @@ -1,31 +1,28 @@ # Window::Create -创建新对象或资源。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/Window.h` + +## 签名 ```cpp virtual bool Create(const WindowDesc& desc) = 0; ``` -该方法声明于 `XCEngine/Platform/Window.h`，当前页面用于固定 `Window` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `desc` - 参数语义详见头文件声明。 +按 `WindowDesc` 创建具体平台窗口。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::Window object; - // 根据上下文补齐参数后调用 Window::Create(...)。 - (void)object; -} -``` +- `desc` 提供标题、尺寸和全屏初始参数。 +- 返回值表示创建是否成功。 ## 相关文档 -- [返回类总览](Window.md) -- [返回模块目录](../Platform.md) +- [Window](Window.md) +- [Destroy](Destroy.md) +- [PlatformTypes](../PlatformTypes/PlatformTypes.md) diff --git a/docs/api/XCEngine/Platform/Window/Destroy.md b/docs/api/XCEngine/Platform/Window/Destroy.md index 9d8f8c5a..e067adba 100644 --- a/docs/api/XCEngine/Platform/Window/Destroy.md +++ b/docs/api/XCEngine/Platform/Window/Destroy.md @@ -1,30 +1,27 @@ # Window::Destroy -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/Window.h` + +## 签名 ```cpp virtual void Destroy() = 0; ``` -该方法声明于 `XCEngine/Platform/Window.h`，当前页面用于固定 `Window` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +释放派生类持有的原生窗口资源。 -**返回：** `void` - 无返回值。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::Window object; - // 根据上下文补齐参数后调用 Window::Destroy(...)。 - (void)object; -} -``` +- `Window` 自身不实现销毁逻辑，具体行为由派生类决定。 +- 调用后对象通常回到未创建状态。 ## 相关文档 -- [返回类总览](Window.md) -- [返回模块目录](../Platform.md) +- [Window](Window.md) +- [Create](Create.md) diff --git a/docs/api/XCEngine/Platform/Window/Destructor.md b/docs/api/XCEngine/Platform/Window/Destructor.md index d1edd308..6ef211a5 100644 --- a/docs/api/XCEngine/Platform/Window/Destructor.md +++ b/docs/api/XCEngine/Platform/Window/Destructor.md @@ -1,29 +1,27 @@ # Window::~Window() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/Window.h` + +## 签名 ```cpp virtual ~Window() = default; ``` -该方法声明于 `XCEngine/Platform/Window.h`，当前页面用于固定 `Window` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +允许通过基类指针安全销毁具体 `Window` 派生类。 -**返回：** `void` - 无返回值。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::Window object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 析构函数本身没有额外逻辑。 +- 原生窗口资源释放由派生类负责。 ## 相关文档 -- [返回类总览](Window.md) -- [返回模块目录](../Platform.md) +- [Window](Window.md) +- [Destroy](Destroy.md) diff --git a/docs/api/XCEngine/Platform/Window/GetHandle.md b/docs/api/XCEngine/Platform/Window/GetHandle.md index a7c7e850..aa276990 100644 --- a/docs/api/XCEngine/Platform/Window/GetHandle.md +++ b/docs/api/XCEngine/Platform/Window/GetHandle.md @@ -1,30 +1,27 @@ # Window::GetHandle -获取相关状态或对象。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/Window.h` + +## 签名 ```cpp virtual WindowHandle GetHandle() const = 0; ``` -该方法声明于 `XCEngine/Platform/Window.h`，当前页面用于固定 `Window` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回引擎层定义的 `WindowHandle`。 -**返回：** `WindowHandle` - 返回值语义详见头文件声明。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::Window object; - // 根据上下文补齐参数后调用 Window::GetHandle(...)。 - (void)object; -} -``` +- `WindowHandle` 当前是 `void*` 别名，但调用方应按抽象句柄使用。 +- 具体句柄来源由派生类决定。 ## 相关文档 -- [返回类总览](Window.md) -- [返回模块目录](../Platform.md) +- [Window](Window.md) +- [GetNativeHandle](GetNativeHandle.md) diff --git a/docs/api/XCEngine/Platform/Window/GetInputModule.md b/docs/api/XCEngine/Platform/Window/GetInputModule.md index c8e17f03..7a6b50fe 100644 --- a/docs/api/XCEngine/Platform/Window/GetInputModule.md +++ b/docs/api/XCEngine/Platform/Window/GetInputModule.md @@ -1,30 +1,27 @@ # Window::GetInputModule -获取相关状态或对象。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/Window.h` + +## 签名 ```cpp Input::InputModule* GetInputModule() const; ``` -该方法声明于 `XCEngine/Platform/Window.h`，当前页面用于固定 `Window` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回当前挂接到窗口上的输入模块指针。 -**返回：** `Input::InputModule*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::Window object; - // 根据上下文补齐参数后调用 Window::GetInputModule(...)。 - (void)object; -} -``` +- `Window` 直接返回成员 `m_inputModule`。 +- 该指针是非拥有型引用，生命周期由外部系统管理。 ## 相关文档 -- [返回类总览](Window.md) -- [返回模块目录](../Platform.md) +- [Window](Window.md) +- [SetInputModule](SetInputModule.md) diff --git a/docs/api/XCEngine/Platform/Window/GetNativeHandle.md b/docs/api/XCEngine/Platform/Window/GetNativeHandle.md index c6e44888..cf9c79fd 100644 --- a/docs/api/XCEngine/Platform/Window/GetNativeHandle.md +++ b/docs/api/XCEngine/Platform/Window/GetNativeHandle.md @@ -1,30 +1,27 @@ # Window::GetNativeHandle -获取相关状态或对象。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/Window.h` + +## 签名 ```cpp virtual void* GetNativeHandle() = 0; ``` -该方法声明于 `XCEngine/Platform/Window.h`，当前页面用于固定 `Window` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回底层平台窗口的原生句柄。 -**返回：** `void*` - 返回值语义详见头文件声明。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::Window object; - // 根据上下文补齐参数后调用 Window::GetNativeHandle(...)。 - (void)object; -} -``` +- 返回值通常是 `HWND` 之类的平台对象地址，但接口层统一暴露为 `void*`。 +- 句柄解释方式由具体平台实现决定。 ## 相关文档 -- [返回类总览](Window.md) -- [返回模块目录](../Platform.md) +- [Window](Window.md) +- [GetHandle](GetHandle.md) diff --git a/docs/api/XCEngine/Platform/Window/IsFullscreen.md b/docs/api/XCEngine/Platform/Window/IsFullscreen.md index 81e3d371..23b308e3 100644 --- a/docs/api/XCEngine/Platform/Window/IsFullscreen.md +++ b/docs/api/XCEngine/Platform/Window/IsFullscreen.md @@ -1,30 +1,27 @@ # Window::IsFullscreen -查询当前状态。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/Window.h` + +## 签名 ```cpp virtual bool IsFullscreen() const = 0; ``` -该方法声明于 `XCEngine/Platform/Window.h`，当前页面用于固定 `Window` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +查询窗口当前是否处于全屏状态。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::Window object; - // 根据上下文补齐参数后调用 Window::IsFullscreen(...)。 - (void)object; -} -``` +- 这是只读状态查询。 +- 具体状态由派生类维护。 ## 相关文档 -- [返回类总览](Window.md) -- [返回模块目录](../Platform.md) +- [Window](Window.md) +- [SetFullscreen](SetFullscreen.md) diff --git a/docs/api/XCEngine/Platform/Window/Maximize.md b/docs/api/XCEngine/Platform/Window/Maximize.md index 1496f9e9..825f9c62 100644 --- a/docs/api/XCEngine/Platform/Window/Maximize.md +++ b/docs/api/XCEngine/Platform/Window/Maximize.md @@ -1,30 +1,27 @@ # Window::Maximize -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/Window.h` + +## 签名 ```cpp virtual void Maximize() = 0; ``` -该方法声明于 `XCEngine/Platform/Window.h`，当前页面用于固定 `Window` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +请求派生类把窗口切到最大化状态。 -**返回：** `void` - 无返回值。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::Window object; - // 根据上下文补齐参数后调用 Window::Maximize(...)。 - (void)object; -} -``` +- 具体最大化行为由平台实现负责。 ## 相关文档 -- [返回类总览](Window.md) -- [返回模块目录](../Platform.md) +- [Window](Window.md) +- [Minimize](Minimize.md) +- [Restore](Restore.md) diff --git a/docs/api/XCEngine/Platform/Window/Minimize.md b/docs/api/XCEngine/Platform/Window/Minimize.md index 8921a884..605c1bc3 100644 --- a/docs/api/XCEngine/Platform/Window/Minimize.md +++ b/docs/api/XCEngine/Platform/Window/Minimize.md @@ -1,30 +1,27 @@ # Window::Minimize -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/Window.h` + +## 签名 ```cpp virtual void Minimize() = 0; ``` -该方法声明于 `XCEngine/Platform/Window.h`，当前页面用于固定 `Window` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +请求派生类把窗口最小化。 -**返回：** `void` - 无返回值。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::Window object; - // 根据上下文补齐参数后调用 Window::Minimize(...)。 - (void)object; -} -``` +- 具体最小化行为由平台实现负责。 ## 相关文档 -- [返回类总览](Window.md) -- [返回模块目录](../Platform.md) +- [Window](Window.md) +- [Maximize](Maximize.md) +- [Restore](Restore.md) diff --git a/docs/api/XCEngine/Platform/Window/PumpEvents.md b/docs/api/XCEngine/Platform/Window/PumpEvents.md index 140050dd..fd9c8b03 100644 --- a/docs/api/XCEngine/Platform/Window/PumpEvents.md +++ b/docs/api/XCEngine/Platform/Window/PumpEvents.md @@ -1,30 +1,27 @@ # Window::PumpEvents -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/Window.h` + +## 签名 ```cpp virtual void PumpEvents() = 0; ``` -该方法声明于 `XCEngine/Platform/Window.h`，当前页面用于固定 `Window` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +处理挂起的窗口消息。 -**返回：** `void` - 无返回值。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::Window object; - // 根据上下文补齐参数后调用 Window::PumpEvents(...)。 - (void)object; -} -``` +- 派生类通常会在这里推进平台消息泵，并可选择转发到当前绑定的输入模块。 ## 相关文档 -- [返回类总览](Window.md) -- [返回模块目录](../Platform.md) +- [Window](Window.md) +- [ShouldClose](ShouldClose.md) +- [GetInputModule](GetInputModule.md) diff --git a/docs/api/XCEngine/Platform/Window/Restore.md b/docs/api/XCEngine/Platform/Window/Restore.md index fd5bc310..d5186b48 100644 --- a/docs/api/XCEngine/Platform/Window/Restore.md +++ b/docs/api/XCEngine/Platform/Window/Restore.md @@ -1,30 +1,27 @@ # Window::Restore -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/Window.h` + +## 签名 ```cpp virtual void Restore() = 0; ``` -该方法声明于 `XCEngine/Platform/Window.h`，当前页面用于固定 `Window` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +把窗口从最小化或最大化状态恢复回来。 -**返回：** `void` - 无返回值。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::Window object; - // 根据上下文补齐参数后调用 Window::Restore(...)。 - (void)object; -} -``` +- 具体恢复细节由平台实现决定。 ## 相关文档 -- [返回类总览](Window.md) -- [返回模块目录](../Platform.md) +- [Window](Window.md) +- [Minimize](Minimize.md) +- [Maximize](Maximize.md) diff --git a/docs/api/XCEngine/Platform/Window/SetFullscreen.md b/docs/api/XCEngine/Platform/Window/SetFullscreen.md index b99b5a79..f33e4f83 100644 --- a/docs/api/XCEngine/Platform/Window/SetFullscreen.md +++ b/docs/api/XCEngine/Platform/Window/SetFullscreen.md @@ -1,31 +1,27 @@ # Window::SetFullscreen -设置相关状态或配置。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/Window.h` + +## 签名 ```cpp virtual void SetFullscreen(bool fullscreen) = 0; ``` -该方法声明于 `XCEngine/Platform/Window.h`，当前页面用于固定 `Window` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `fullscreen` - 参数语义详见头文件声明。 +切换窗口是否处于全屏状态。 -**返回：** `void` - 无返回值。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::Window object; - // 根据上下文补齐参数后调用 Window::SetFullscreen(...)。 - (void)object; -} -``` +- `fullscreen == true` 表示请求进入全屏，`false` 表示退出全屏。 +- 具体切换方式由派生类实现。 ## 相关文档 -- [返回类总览](Window.md) -- [返回模块目录](../Platform.md) +- [Window](Window.md) +- [IsFullscreen](IsFullscreen.md) diff --git a/docs/api/XCEngine/Platform/Window/SetInputModule.md b/docs/api/XCEngine/Platform/Window/SetInputModule.md index e3b51451..3d2c6558 100644 --- a/docs/api/XCEngine/Platform/Window/SetInputModule.md +++ b/docs/api/XCEngine/Platform/Window/SetInputModule.md @@ -1,31 +1,27 @@ # Window::SetInputModule -设置相关状态或配置。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/Window.h` + +## 签名 ```cpp void SetInputModule(Input::InputModule* module); ``` -该方法声明于 `XCEngine/Platform/Window.h`，当前页面用于固定 `Window` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `module` - 参数语义详见头文件声明。 +把一个输入模块指针挂接到窗口对象上。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::Window object; - // 根据上下文补齐参数后调用 Window::SetInputModule(...)。 - (void)object; -} -``` +- `Window.cpp` 里这个方法只做一件事：`m_inputModule = module;` +- 该指针是非拥有型引用，`Window` 不负责释放它。 ## 相关文档 -- [返回类总览](Window.md) -- [返回模块目录](../Platform.md) +- [Window](Window.md) +- [GetInputModule](GetInputModule.md) diff --git a/docs/api/XCEngine/Platform/Window/SetTitle.md b/docs/api/XCEngine/Platform/Window/SetTitle.md index 41714fc2..a9e534e6 100644 --- a/docs/api/XCEngine/Platform/Window/SetTitle.md +++ b/docs/api/XCEngine/Platform/Window/SetTitle.md @@ -1,31 +1,27 @@ # Window::SetTitle -设置相关状态或配置。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/Window.h` + +## 签名 ```cpp virtual void SetTitle(const Containers::String& title) = 0; ``` -该方法声明于 `XCEngine/Platform/Window.h`，当前页面用于固定 `Window` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `title` - 参数语义详见头文件声明。 +修改窗口标题。 -**返回：** `void` - 无返回值。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::Window object; - // 根据上下文补齐参数后调用 Window::SetTitle(...)。 - (void)object; -} -``` +- `title` 是新的标题字符串。 +- 标题如何同步到原生窗口由派生类决定。 ## 相关文档 -- [返回类总览](Window.md) -- [返回模块目录](../Platform.md) +- [Window](Window.md) +- [Create](Create.md) diff --git a/docs/api/XCEngine/Platform/Window/ShouldClose.md b/docs/api/XCEngine/Platform/Window/ShouldClose.md index 06c86df8..3e316d51 100644 --- a/docs/api/XCEngine/Platform/Window/ShouldClose.md +++ b/docs/api/XCEngine/Platform/Window/ShouldClose.md @@ -1,30 +1,26 @@ # Window::ShouldClose -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/Window.h` + +## 签名 ```cpp virtual bool ShouldClose() const = 0; ``` -该方法声明于 `XCEngine/Platform/Window.h`，当前页面用于固定 `Window` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +查询窗口是否已经被标记为应关闭。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前契约 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::Window object; - // 根据上下文补齐参数后调用 Window::ShouldClose(...)。 - (void)object; -} -``` +- 关闭标记通常由派生类在平台消息处理过程中维护。 ## 相关文档 -- [返回类总览](Window.md) -- [返回模块目录](../Platform.md) +- [Window](Window.md) +- [PumpEvents](PumpEvents.md) diff --git a/docs/api/XCEngine/Platform/Window/Window.md b/docs/api/XCEngine/Platform/Window/Window.md index 8da0f1fb..48d97203 100644 --- a/docs/api/XCEngine/Platform/Window/Window.md +++ b/docs/api/XCEngine/Platform/Window/Window.md @@ -6,39 +6,47 @@ **头文件**: `XCEngine/Platform/Window.h` -**描述**: 定义 `XCEngine/Platform` 子目录中的 `Window` public API。 +**描述**: 旧平台层窗口抽象基类，定义窗口生命周期、状态切换、句柄访问和输入模块挂接能力。 ## 概述 -`Window.h` 是 `XCEngine/Platform` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。 +`Window` 是 `Platform` 模块里较早的一套窗口抽象。它负责约定平台窗口至少要提供哪些操作： + +- 创建、销毁和事件泵 +- 标题与全屏状态切换 +- 最小化、最大化、恢复 +- 关闭标记查询 +- 引擎层句柄和原生句柄访问 + +和 `IWindow` 不同，`Window` 还内置了一个 `Input::InputModule*` 成员，用来把窗口和输入模块挂接起来。当前 `Window.cpp` 只实现了 [SetInputModule](SetInputModule.md) 这一层指针保存，其余行为都由派生类完成。 ## 声明概览 | 声明 | 类型 | 说明 | |------|------|------| -| `Window` | `class` | 头文件中的公开声明。 | +| `Window` | `class` | 带输入模块挂接能力的抽象窗口基类。 | ## 公共方法 | 方法 | 描述 | |------|------| -| [~Window()](Destructor.md) | 销毁对象并释放相关资源。 | -| [Create](Create.md) | 创建新对象或资源。 | -| [Destroy](Destroy.md) | 公开方法，详见头文件声明。 | -| [GetHandle](GetHandle.md) | 获取相关状态或对象。 | -| [PumpEvents](PumpEvents.md) | 公开方法，详见头文件声明。 | -| [SetTitle](SetTitle.md) | 设置相关状态或配置。 | -| [SetFullscreen](SetFullscreen.md) | 设置相关状态或配置。 | -| [IsFullscreen](IsFullscreen.md) | 查询当前状态。 | -| [Minimize](Minimize.md) | 公开方法，详见头文件声明。 | -| [Maximize](Maximize.md) | 公开方法，详见头文件声明。 | -| [Restore](Restore.md) | 公开方法，详见头文件声明。 | -| [ShouldClose](ShouldClose.md) | 公开方法，详见头文件声明。 | -| [GetNativeHandle](GetNativeHandle.md) | 获取相关状态或对象。 | -| [SetInputModule](SetInputModule.md) | 设置相关状态或配置。 | -| [GetInputModule](GetInputModule.md) | 获取相关状态或对象。 | +| [~Window()](Destructor.md) | 通过基类指针销毁具体窗口实现。 | +| [Create](Create.md) | 按 `WindowDesc` 创建平台窗口。 | +| [Destroy](Destroy.md) | 释放平台窗口资源。 | +| [GetHandle](GetHandle.md) | 返回引擎层 `WindowHandle`。 | +| [PumpEvents](PumpEvents.md) | 处理窗口事件，并允许派生类转发到输入模块。 | +| [SetTitle](SetTitle.md) | 修改窗口标题。 | +| [SetFullscreen](SetFullscreen.md) | 切换窗口全屏状态。 | +| [IsFullscreen](IsFullscreen.md) | 查询当前是否处于全屏。 | +| [Minimize](Minimize.md) | 最小化窗口。 | +| [Maximize](Maximize.md) | 最大化窗口。 | +| [Restore](Restore.md) | 把窗口恢复到普通状态。 | +| [ShouldClose](ShouldClose.md) | 查询窗口是否收到关闭请求。 | +| [GetNativeHandle](GetNativeHandle.md) | 返回底层平台窗口句柄。 | +| [SetInputModule](SetInputModule.md) | 绑定一个非拥有型输入模块指针。 | +| [GetInputModule](GetInputModule.md) | 取回当前绑定的输入模块指针。 | ## 相关文档 -- [当前目录](../Platform.md) - 返回 `Platform` 平行目录 -- [API 总索引](../../../main.md) - 返回顶层索引 +- [Platform](../Platform.md) +- [WindowsWindow](../Windows/WindowsWindow/WindowsWindow.md) diff --git a/docs/api/XCEngine/Platform/Windows/WindowsInputModule/Constructor.md b/docs/api/XCEngine/Platform/Windows/WindowsInputModule/Constructor.md index bdc5c25b..7dd230d4 100644 --- a/docs/api/XCEngine/Platform/Windows/WindowsInputModule/Constructor.md +++ b/docs/api/XCEngine/Platform/Windows/WindowsInputModule/Constructor.md @@ -1,28 +1,26 @@ # WindowsInputModule::WindowsInputModule() -构造对象。 +**命名空间**: `XCEngine::Input::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/Windows/WindowsInputModule.h` + +## 签名 ```cpp WindowsInputModule(); ``` -该方法声明于 `XCEngine/Platform/Windows/WindowsInputModule.h`，当前页面用于固定 `WindowsInputModule` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +构造一个尚未绑定窗口句柄的 Win32 输入模块。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Input::Platform::WindowsInputModule object; -} -``` +- 构造函数把 `m_hwnd` 初始化为 `nullptr`，并把 `m_isInitialized` 设为 `false`。 ## 相关文档 -- [返回类总览](WindowsInputModule.md) -- [返回模块目录](../Windows.md) +- [WindowsInputModule](WindowsInputModule.md) +- [Initialize](Initialize.md) diff --git a/docs/api/XCEngine/Platform/Windows/WindowsInputModule/Destructor.md b/docs/api/XCEngine/Platform/Windows/WindowsInputModule/Destructor.md index 3106247e..847bf184 100644 --- a/docs/api/XCEngine/Platform/Windows/WindowsInputModule/Destructor.md +++ b/docs/api/XCEngine/Platform/Windows/WindowsInputModule/Destructor.md @@ -1,29 +1,26 @@ # WindowsInputModule::~WindowsInputModule() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::Input::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/Windows/WindowsInputModule.h` + +## 签名 ```cpp virtual ~WindowsInputModule(); ``` -该方法声明于 `XCEngine/Platform/Windows/WindowsInputModule.h`，当前页面用于固定 `WindowsInputModule` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +在析构时退出已初始化状态并清空句柄引用。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Input::Platform::WindowsInputModule object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 析构函数内部直接调用 [Shutdown](Shutdown.md)。 ## 相关文档 -- [返回类总览](WindowsInputModule.md) -- [返回模块目录](../Windows.md) +- [WindowsInputModule](WindowsInputModule.md) +- [Shutdown](Shutdown.md) diff --git a/docs/api/XCEngine/Platform/Windows/WindowsInputModule/HandleMessage.md b/docs/api/XCEngine/Platform/Windows/WindowsInputModule/HandleMessage.md index 94d6edea..6484bd38 100644 --- a/docs/api/XCEngine/Platform/Windows/WindowsInputModule/HandleMessage.md +++ b/docs/api/XCEngine/Platform/Windows/WindowsInputModule/HandleMessage.md @@ -1,34 +1,30 @@ # WindowsInputModule::HandleMessage -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Input::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/Windows/WindowsInputModule.h` + +## 签名 ```cpp void HandleMessage(size_t hwnd, unsigned int msg, size_t wParam, size_t lParam) override; ``` -该方法声明于 `XCEngine/Platform/Windows/WindowsInputModule.h`，当前页面用于固定 `WindowsInputModule` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `hwnd` - 参数语义详见头文件声明。 -- `msg` - 参数语义详见头文件声明。 -- `wParam` - 参数语义详见头文件声明。 -- `lParam` - 参数语义详见头文件声明。 +把一条 Win32 窗口消息翻译成引擎输入事件。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Input::Platform::WindowsInputModule object; - // 根据上下文补齐参数后调用 WindowsInputModule::HandleMessage(...)。 - (void)object; -} -``` +- 如果模块尚未初始化，会直接返回。 +- `msg` 会被分发到键盘、字符输入、鼠标移动、鼠标按键和滚轮等处理函数。 +- 这些辅助函数最终都转成 `InputManager::Get()` 上的 `ProcessKeyDown`、`ProcessMouseMove`、`ProcessMouseButton`、`ProcessMouseWheel`、`ProcessTextInput` 等调用。 +- `hwnd` 参数当前未参与分支决策，真正用到的是消息类型和 `wParam` / `lParam`。 ## 相关文档 -- [返回类总览](WindowsInputModule.md) -- [返回模块目录](../Windows.md) +- [WindowsInputModule](WindowsInputModule.md) +- [PumpEvents](PumpEvents.md) +- [WindowsWindow::PumpEvents](../WindowsWindow/PumpEvents.md) diff --git a/docs/api/XCEngine/Platform/Windows/WindowsInputModule/Initialize.md b/docs/api/XCEngine/Platform/Windows/WindowsInputModule/Initialize.md index 563b8d05..ab17cff8 100644 --- a/docs/api/XCEngine/Platform/Windows/WindowsInputModule/Initialize.md +++ b/docs/api/XCEngine/Platform/Windows/WindowsInputModule/Initialize.md @@ -1,31 +1,28 @@ # WindowsInputModule::Initialize -初始化内部状态。 +**命名空间**: `XCEngine::Input::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/Windows/WindowsInputModule.h` + +## 签名 ```cpp void Initialize(void* windowHandle) override; ``` -该方法声明于 `XCEngine/Platform/Windows/WindowsInputModule.h`，当前页面用于固定 `WindowsInputModule` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `windowHandle` - 参数语义详见头文件声明。 +绑定 Win32 窗口句柄，并让输入模块进入可处理消息状态。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Input::Platform::WindowsInputModule object; - // 根据上下文补齐参数后调用 WindowsInputModule::Initialize(...)。 - (void)object; -} -``` +- 如果已经初始化过，会直接返回。 +- 否则把 `windowHandle` 转成 `HWND` 保存到 `m_hwnd`，把 `m_isInitialized` 设为 `true`，并把 `m_lastMousePosition` 重置为零向量。 ## 相关文档 -- [返回类总览](WindowsInputModule.md) -- [返回模块目录](../Windows.md) +- [WindowsInputModule](WindowsInputModule.md) +- [Shutdown](Shutdown.md) +- [HandleMessage](HandleMessage.md) diff --git a/docs/api/XCEngine/Platform/Windows/WindowsInputModule/PumpEvents.md b/docs/api/XCEngine/Platform/Windows/WindowsInputModule/PumpEvents.md index 77879c10..5e54b62c 100644 --- a/docs/api/XCEngine/Platform/Windows/WindowsInputModule/PumpEvents.md +++ b/docs/api/XCEngine/Platform/Windows/WindowsInputModule/PumpEvents.md @@ -1,30 +1,27 @@ # WindowsInputModule::PumpEvents -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Input::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/Windows/WindowsInputModule.h` + +## 签名 ```cpp void PumpEvents() override; ``` -该方法声明于 `XCEngine/Platform/Windows/WindowsInputModule.h`，当前页面用于固定 `WindowsInputModule` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +为 `InputModule` 接口保留一个逐帧泵事件入口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Input::Platform::WindowsInputModule object; - // 根据上下文补齐参数后调用 WindowsInputModule::PumpEvents(...)。 - (void)object; -} -``` +- 当前 `.cpp` 中这个方法是空实现。 +- Win32 输入事件的真正处理入口是 [HandleMessage](HandleMessage.md)，而不是这里。 ## 相关文档 -- [返回类总览](WindowsInputModule.md) -- [返回模块目录](../Windows.md) +- [WindowsInputModule](WindowsInputModule.md) +- [HandleMessage](HandleMessage.md) diff --git a/docs/api/XCEngine/Platform/Windows/WindowsInputModule/Shutdown.md b/docs/api/XCEngine/Platform/Windows/WindowsInputModule/Shutdown.md index d2cd7707..6247e76f 100644 --- a/docs/api/XCEngine/Platform/Windows/WindowsInputModule/Shutdown.md +++ b/docs/api/XCEngine/Platform/Windows/WindowsInputModule/Shutdown.md @@ -1,30 +1,27 @@ # WindowsInputModule::Shutdown -关闭并清理内部状态。 +**命名空间**: `XCEngine::Input::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/Windows/WindowsInputModule.h` + +## 签名 ```cpp void Shutdown() override; ``` -该方法声明于 `XCEngine/Platform/Windows/WindowsInputModule.h`，当前页面用于固定 `WindowsInputModule` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +退出输入模块的已初始化状态，并断开窗口句柄引用。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Input::Platform::WindowsInputModule object; - // 根据上下文补齐参数后调用 WindowsInputModule::Shutdown(...)。 - (void)object; -} -``` +- 如果模块尚未初始化，会直接返回。 +- 否则把 `m_hwnd` 清空，并把 `m_isInitialized` 设为 `false`。 ## 相关文档 -- [返回类总览](WindowsInputModule.md) -- [返回模块目录](../Windows.md) +- [WindowsInputModule](WindowsInputModule.md) +- [Initialize](Initialize.md) diff --git a/docs/api/XCEngine/Platform/Windows/WindowsInputModule/WindowsInputModule.md b/docs/api/XCEngine/Platform/Windows/WindowsInputModule/WindowsInputModule.md index 6c4fda4c..9e7030e9 100644 --- a/docs/api/XCEngine/Platform/Windows/WindowsInputModule/WindowsInputModule.md +++ b/docs/api/XCEngine/Platform/Windows/WindowsInputModule/WindowsInputModule.md @@ -6,30 +6,37 @@ **头文件**: `XCEngine/Platform/Windows/WindowsInputModule.h` -**描述**: 定义 `XCEngine/Platform/Windows` 子目录中的 `WindowsInputModule` public API。 +**描述**: `InputModule` 的 Win32 实现，把窗口消息翻译成 `InputManager` 的键盘、鼠标和文本输入事件。 ## 概述 -`WindowsInputModule.h` 是 `XCEngine/Platform/Windows` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。 +`WindowsInputModule` 本身不拥有消息循环；它依赖窗口层把 Win32 消息喂给 [HandleMessage](HandleMessage.md)。按 `engine/src/Platform/Windows/WindowsInputModule.cpp` 的当前实现： + +- [Initialize](Initialize.md) 只保存 `HWND`、重置鼠标位置并标记已初始化 +- [PumpEvents](PumpEvents.md) 当前是空实现 +- [HandleMessage](HandleMessage.md) 负责把 `WM_KEYDOWN`、`WM_MOUSEMOVE`、`WM_MOUSEWHEEL`、`WM_CHAR` 等消息转换成 `InputManager::Get()` 的调用 + +它是一个纯桥接层，真正的输入状态存储和按帧语义都在 `InputManager` 里。 ## 声明概览 | 声明 | 类型 | 说明 | |------|------|------| -| `WindowsInputModule` | `class` | 继承自 `InputModule` 的公开声明。 | +| `WindowsInputModule` | `class` | `InputModule` 的 Win32 消息适配器。 | ## 公共方法 | 方法 | 描述 | |------|------| -| [WindowsInputModule()](Constructor.md) | 构造对象。 | -| [~WindowsInputModule()](Destructor.md) | 销毁对象并释放相关资源。 | -| [Initialize](Initialize.md) | 初始化内部状态。 | -| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 | -| [PumpEvents](PumpEvents.md) | 公开方法，详见头文件声明。 | -| [HandleMessage](HandleMessage.md) | 公开方法，详见头文件声明。 | +| [WindowsInputModule()](Constructor.md) | 初始化空句柄和未初始化状态。 | +| [~WindowsInputModule()](Destructor.md) | 析构时调用 [Shutdown](Shutdown.md)。 | +| [Initialize](Initialize.md) | 绑定窗口句柄并进入可处理消息状态。 | +| [Shutdown](Shutdown.md) | 清空窗口句柄并退出已初始化状态。 | +| [PumpEvents](PumpEvents.md) | 当前为空实现，消息处理实际发生在 [HandleMessage](HandleMessage.md)。 | +| [HandleMessage](HandleMessage.md) | 把 Win32 键盘 / 鼠标 / 字符消息翻译成 `InputManager` 调用。 | ## 相关文档 -- [当前目录](../Windows.md) - 返回 `Windows` 平行目录 -- [API 总索引](../../../../main.md) - 返回顶层索引 +- [Windows](../Windows.md) +- [WindowsWindow](../WindowsWindow/WindowsWindow.md) +- [InputManager](../../../Input/InputManager/InputManager.md) diff --git a/docs/api/XCEngine/Platform/Windows/WindowsWindow/Constructor.md b/docs/api/XCEngine/Platform/Windows/WindowsWindow/Constructor.md index 0db0eda8..ace67e49 100644 --- a/docs/api/XCEngine/Platform/Windows/WindowsWindow/Constructor.md +++ b/docs/api/XCEngine/Platform/Windows/WindowsWindow/Constructor.md @@ -1,28 +1,26 @@ # WindowsWindow::WindowsWindow() -构造对象。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/Windows/WindowsWindow.h` + +## 签名 ```cpp WindowsWindow(); ``` -该方法声明于 `XCEngine/Platform/Windows/WindowsWindow.h`，当前页面用于固定 `WindowsWindow` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +构造一个尚未创建原生窗口的 `WindowsWindow` 对象。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::WindowsWindow object; -} -``` +- 构造函数把 `m_hwnd`、`m_hInstance`、`m_fullscreen`、`m_shouldClose` 和 `m_minimized` 初始化为空或 `false`。 ## 相关文档 -- [返回类总览](WindowsWindow.md) -- [返回模块目录](../Windows.md) +- [WindowsWindow](WindowsWindow.md) +- [Create](Create.md) diff --git a/docs/api/XCEngine/Platform/Windows/WindowsWindow/Create.md b/docs/api/XCEngine/Platform/Windows/WindowsWindow/Create.md index 63bc3ec4..b8cbfab0 100644 --- a/docs/api/XCEngine/Platform/Windows/WindowsWindow/Create.md +++ b/docs/api/XCEngine/Platform/Windows/WindowsWindow/Create.md @@ -1,31 +1,30 @@ # WindowsWindow::Create -创建新对象或资源。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/Windows/WindowsWindow.h` + +## 签名 ```cpp bool Create(const WindowDesc& desc) override; ``` -该方法声明于 `XCEngine/Platform/Windows/WindowsWindow.h`，当前页面用于固定 `WindowsWindow` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `desc` - 参数语义详见头文件声明。 +创建并显示一个 Win32 主窗口。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::WindowsWindow object; - // 根据上下文补齐参数后调用 WindowsWindow::Create(...)。 - (void)object; -} -``` +- 先取 `HINSTANCE`，注册 `XCEngineWindowClass`，再按 `desc.width` / `desc.height` 计算窗口矩形。 +- 通过 `CreateWindowExA` 创建 `HWND`；失败时返回 `false`。 +- 如果 `desc.fullscreen` 为真，会在创建后立即调用 [SetFullscreen](SetFullscreen.md)。 +- 成功时调用 `ShowWindow` 和 `UpdateWindow`，然后返回 `true`。 ## 相关文档 -- [返回类总览](WindowsWindow.md) -- [返回模块目录](../Windows.md) +- [WindowsWindow](WindowsWindow.md) +- [Destroy](Destroy.md) +- [SetFullscreen](SetFullscreen.md) diff --git a/docs/api/XCEngine/Platform/Windows/WindowsWindow/Destroy.md b/docs/api/XCEngine/Platform/Windows/WindowsWindow/Destroy.md index 734b4800..cfcff830 100644 --- a/docs/api/XCEngine/Platform/Windows/WindowsWindow/Destroy.md +++ b/docs/api/XCEngine/Platform/Windows/WindowsWindow/Destroy.md @@ -1,30 +1,28 @@ # WindowsWindow::Destroy -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/Windows/WindowsWindow.h` + +## 签名 ```cpp void Destroy() override; ``` -该方法声明于 `XCEngine/Platform/Windows/WindowsWindow.h`，当前页面用于固定 `WindowsWindow` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +销毁当前 `HWND`，并注销 `XCEngineWindowClass`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::WindowsWindow object; - // 根据上下文补齐参数后调用 WindowsWindow::Destroy(...)。 - (void)object; -} -``` +- 若 `m_hwnd` 非空，会先调用 `DestroyWindow(m_hwnd)`，再把句柄清空。 +- 随后调用 `UnregisterClassA` 注销窗口类，并把 `m_hInstance` 置空。 ## 相关文档 -- [返回类总览](WindowsWindow.md) -- [返回模块目录](../Windows.md) +- [WindowsWindow](WindowsWindow.md) +- [Create](Create.md) +- [Destructor](Destructor.md) diff --git a/docs/api/XCEngine/Platform/Windows/WindowsWindow/Destructor.md b/docs/api/XCEngine/Platform/Windows/WindowsWindow/Destructor.md index 3ab4e162..df9a8ceb 100644 --- a/docs/api/XCEngine/Platform/Windows/WindowsWindow/Destructor.md +++ b/docs/api/XCEngine/Platform/Windows/WindowsWindow/Destructor.md @@ -1,29 +1,26 @@ # WindowsWindow::~WindowsWindow() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/Windows/WindowsWindow.h` + +## 签名 ```cpp virtual ~WindowsWindow(); ``` -该方法声明于 `XCEngine/Platform/Windows/WindowsWindow.h`，当前页面用于固定 `WindowsWindow` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +在对象析构时清理 Win32 窗口资源。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::WindowsWindow object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 析构函数内部直接调用 [Destroy](Destroy.md)。 ## 相关文档 -- [返回类总览](WindowsWindow.md) -- [返回模块目录](../Windows.md) +- [WindowsWindow](WindowsWindow.md) +- [Destroy](Destroy.md) diff --git a/docs/api/XCEngine/Platform/Windows/WindowsWindow/GetHandle.md b/docs/api/XCEngine/Platform/Windows/WindowsWindow/GetHandle.md index 31751efa..cd651ec9 100644 --- a/docs/api/XCEngine/Platform/Windows/WindowsWindow/GetHandle.md +++ b/docs/api/XCEngine/Platform/Windows/WindowsWindow/GetHandle.md @@ -1,30 +1,27 @@ # WindowsWindow::GetHandle -获取相关状态或对象。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/Windows/WindowsWindow.h` + +## 签名 ```cpp WindowHandle GetHandle() const override; ``` -该方法声明于 `XCEngine/Platform/Windows/WindowsWindow.h`，当前页面用于固定 `WindowsWindow` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +把当前 `HWND` 作为 `WindowHandle` 返回。 -**返回：** `WindowHandle` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::WindowsWindow object; - // 根据上下文补齐参数后调用 WindowsWindow::GetHandle(...)。 - (void)object; -} -``` +- 该方法直接返回成员 `m_hwnd`。 +- 在当前实现里，这个值和 [GetNativeHandle](GetNativeHandle.md) 指向同一个 Win32 句柄。 ## 相关文档 -- [返回类总览](WindowsWindow.md) -- [返回模块目录](../Windows.md) +- [WindowsWindow](WindowsWindow.md) +- [GetNativeHandle](GetNativeHandle.md) diff --git a/docs/api/XCEngine/Platform/Windows/WindowsWindow/GetNativeHandle.md b/docs/api/XCEngine/Platform/Windows/WindowsWindow/GetNativeHandle.md index 6cc47c02..3c3869ca 100644 --- a/docs/api/XCEngine/Platform/Windows/WindowsWindow/GetNativeHandle.md +++ b/docs/api/XCEngine/Platform/Windows/WindowsWindow/GetNativeHandle.md @@ -1,30 +1,27 @@ # WindowsWindow::GetNativeHandle -获取相关状态或对象。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/Windows/WindowsWindow.h` + +## 签名 ```cpp void* GetNativeHandle() override; ``` -该方法声明于 `XCEngine/Platform/Windows/WindowsWindow.h`，当前页面用于固定 `WindowsWindow` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回原始 Win32 `HWND`。 -**返回：** `void*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::WindowsWindow object; - // 根据上下文补齐参数后调用 WindowsWindow::GetNativeHandle(...)。 - (void)object; -} -``` +- 该方法直接把 `m_hwnd` 作为 `void*` 返回。 +- 调用方如果要按 Win32 API 使用，需要自行转回 `HWND`。 ## 相关文档 -- [返回类总览](WindowsWindow.md) -- [返回模块目录](../Windows.md) +- [WindowsWindow](WindowsWindow.md) +- [GetHandle](GetHandle.md) diff --git a/docs/api/XCEngine/Platform/Windows/WindowsWindow/IsFullscreen.md b/docs/api/XCEngine/Platform/Windows/WindowsWindow/IsFullscreen.md index 3de6e3e5..62c125dc 100644 --- a/docs/api/XCEngine/Platform/Windows/WindowsWindow/IsFullscreen.md +++ b/docs/api/XCEngine/Platform/Windows/WindowsWindow/IsFullscreen.md @@ -1,30 +1,26 @@ # WindowsWindow::IsFullscreen -查询当前状态。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/Windows/WindowsWindow.h` + +## 签名 ```cpp bool IsFullscreen() const override; ``` -该方法声明于 `XCEngine/Platform/Windows/WindowsWindow.h`，当前页面用于固定 `WindowsWindow` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +查询窗口当前是否处于 Win32 全屏状态。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::WindowsWindow object; - // 根据上下文补齐参数后调用 WindowsWindow::IsFullscreen(...)。 - (void)object; -} -``` +- 该方法直接返回成员 `m_fullscreen`。 ## 相关文档 -- [返回类总览](WindowsWindow.md) -- [返回模块目录](../Windows.md) +- [WindowsWindow](WindowsWindow.md) +- [SetFullscreen](SetFullscreen.md) diff --git a/docs/api/XCEngine/Platform/Windows/WindowsWindow/Maximize.md b/docs/api/XCEngine/Platform/Windows/WindowsWindow/Maximize.md index 21c0d426..98be289e 100644 --- a/docs/api/XCEngine/Platform/Windows/WindowsWindow/Maximize.md +++ b/docs/api/XCEngine/Platform/Windows/WindowsWindow/Maximize.md @@ -1,30 +1,27 @@ # WindowsWindow::Maximize -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/Windows/WindowsWindow.h` + +## 签名 ```cpp void Maximize() override; ``` -该方法声明于 `XCEngine/Platform/Windows/WindowsWindow.h`，当前页面用于固定 `WindowsWindow` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +把窗口切到 Win32 最大化状态。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::WindowsWindow object; - // 根据上下文补齐参数后调用 WindowsWindow::Maximize(...)。 - (void)object; -} -``` +- 当 `m_hwnd` 非空时调用 `ShowWindow(m_hwnd, SW_MAXIMIZE)`。 ## 相关文档 -- [返回类总览](WindowsWindow.md) -- [返回模块目录](../Windows.md) +- [WindowsWindow](WindowsWindow.md) +- [Minimize](Minimize.md) +- [Restore](Restore.md) diff --git a/docs/api/XCEngine/Platform/Windows/WindowsWindow/Minimize.md b/docs/api/XCEngine/Platform/Windows/WindowsWindow/Minimize.md index b47335e7..a6c2412e 100644 --- a/docs/api/XCEngine/Platform/Windows/WindowsWindow/Minimize.md +++ b/docs/api/XCEngine/Platform/Windows/WindowsWindow/Minimize.md @@ -1,30 +1,28 @@ # WindowsWindow::Minimize -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/Windows/WindowsWindow.h` + +## 签名 ```cpp void Minimize() override; ``` -该方法声明于 `XCEngine/Platform/Windows/WindowsWindow.h`，当前页面用于固定 `WindowsWindow` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +把窗口切到 Win32 最小化状态。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::WindowsWindow object; - // 根据上下文补齐参数后调用 WindowsWindow::Minimize(...)。 - (void)object; -} -``` +- 当 `m_hwnd` 非空时调用 `ShowWindow(m_hwnd, SW_MINIMIZE)`。 +- 同时把 `m_minimized` 设为 `true`。 ## 相关文档 -- [返回类总览](WindowsWindow.md) -- [返回模块目录](../Windows.md) +- [WindowsWindow](WindowsWindow.md) +- [Maximize](Maximize.md) +- [Restore](Restore.md) diff --git a/docs/api/XCEngine/Platform/Windows/WindowsWindow/PumpEvents.md b/docs/api/XCEngine/Platform/Windows/WindowsWindow/PumpEvents.md index e72c4d53..a91cefe8 100644 --- a/docs/api/XCEngine/Platform/Windows/WindowsWindow/PumpEvents.md +++ b/docs/api/XCEngine/Platform/Windows/WindowsWindow/PumpEvents.md @@ -1,30 +1,29 @@ # WindowsWindow::PumpEvents -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/Windows/WindowsWindow.h` + +## 签名 ```cpp void PumpEvents() override; ``` -该方法声明于 `XCEngine/Platform/Windows/WindowsWindow.h`，当前页面用于固定 `WindowsWindow` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +处理当前线程上的 Win32 消息，并推进绑定的输入模块。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::WindowsWindow object; - // 根据上下文补齐参数后调用 WindowsWindow::PumpEvents(...)。 - (void)object; -} -``` +- 通过 `PeekMessage` 循环取出所有挂起消息，并依次 `TranslateMessage` / `DispatchMessage`。 +- 如果遇到 `WM_QUIT`，会把 `m_shouldClose` 设为 `true`。 +- 消息循环结束后，若 `m_inputModule` 非空，还会额外调用一次 `m_inputModule->PumpEvents()`。 ## 相关文档 -- [返回类总览](WindowsWindow.md) -- [返回模块目录](../Windows.md) +- [WindowsWindow](WindowsWindow.md) +- [ShouldClose](ShouldClose.md) +- [SetMessageCallback](SetMessageCallback.md) diff --git a/docs/api/XCEngine/Platform/Windows/WindowsWindow/Restore.md b/docs/api/XCEngine/Platform/Windows/WindowsWindow/Restore.md index ab828ea2..2035021a 100644 --- a/docs/api/XCEngine/Platform/Windows/WindowsWindow/Restore.md +++ b/docs/api/XCEngine/Platform/Windows/WindowsWindow/Restore.md @@ -1,30 +1,28 @@ # WindowsWindow::Restore -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/Windows/WindowsWindow.h` + +## 签名 ```cpp void Restore() override; ``` -该方法声明于 `XCEngine/Platform/Windows/WindowsWindow.h`，当前页面用于固定 `WindowsWindow` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +把窗口从最小化或最大化状态恢复到普通窗口状态。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::WindowsWindow object; - // 根据上下文补齐参数后调用 WindowsWindow::Restore(...)。 - (void)object; -} -``` +- 当 `m_hwnd` 非空时调用 `ShowWindow(m_hwnd, SW_RESTORE)`。 +- 同时把 `m_minimized` 设为 `false`。 ## 相关文档 -- [返回类总览](WindowsWindow.md) -- [返回模块目录](../Windows.md) +- [WindowsWindow](WindowsWindow.md) +- [Minimize](Minimize.md) +- [Maximize](Maximize.md) diff --git a/docs/api/XCEngine/Platform/Windows/WindowsWindow/SetFullscreen.md b/docs/api/XCEngine/Platform/Windows/WindowsWindow/SetFullscreen.md index 9abbc57c..d49bf1b6 100644 --- a/docs/api/XCEngine/Platform/Windows/WindowsWindow/SetFullscreen.md +++ b/docs/api/XCEngine/Platform/Windows/WindowsWindow/SetFullscreen.md @@ -1,31 +1,29 @@ # WindowsWindow::SetFullscreen -设置相关状态或配置。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/Windows/WindowsWindow.h` + +## 签名 ```cpp void SetFullscreen(bool fullscreen) override; ``` -该方法声明于 `XCEngine/Platform/Windows/WindowsWindow.h`，当前页面用于固定 `WindowsWindow` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `fullscreen` - 参数语义详见头文件声明。 +通过调整 Win32 窗口样式和位置切换全屏。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::WindowsWindow object; - // 根据上下文补齐参数后调用 WindowsWindow::SetFullscreen(...)。 - (void)object; -} -``` +- 如果 `m_hwnd` 为空，会直接返回。 +- 进入全屏时会缓存旧窗口矩形，查询当前显示器范围，然后把样式改成 `WS_POPUP | WS_SYSMENU` 并铺满显示器。 +- 退出全屏时会恢复 `WS_OVERLAPPEDWINDOW`，并使用缓存的旧窗口矩形恢复位置与尺寸。 +- 最后同步更新 `m_fullscreen`。 ## 相关文档 -- [返回类总览](WindowsWindow.md) -- [返回模块目录](../Windows.md) +- [WindowsWindow](WindowsWindow.md) +- [IsFullscreen](IsFullscreen.md) diff --git a/docs/api/XCEngine/Platform/Windows/WindowsWindow/SetMessageCallback.md b/docs/api/XCEngine/Platform/Windows/WindowsWindow/SetMessageCallback.md index b9d3bcc6..8706455d 100644 --- a/docs/api/XCEngine/Platform/Windows/WindowsWindow/SetMessageCallback.md +++ b/docs/api/XCEngine/Platform/Windows/WindowsWindow/SetMessageCallback.md @@ -1,31 +1,27 @@ # WindowsWindow::SetMessageCallback -设置相关状态或配置。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/Windows/WindowsWindow.h` + +## 签名 ```cpp void SetMessageCallback(std::function callback); ``` -该方法声明于 `XCEngine/Platform/Windows/WindowsWindow.h`，当前页面用于固定 `WindowsWindow` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `callback` - 参数语义详见头文件声明。 +注册一个额外的 Win32 消息回调。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::WindowsWindow object; - // 根据上下文补齐参数后调用 WindowsWindow::SetMessageCallback(...)。 - (void)object; -} -``` +- 方法只是把传入回调保存到成员 `m_messageCallback`。 +- `WndProc` 在处理自有分支前，会先调用这个回调。 ## 相关文档 -- [返回类总览](WindowsWindow.md) -- [返回模块目录](../Windows.md) +- [WindowsWindow](WindowsWindow.md) +- [PumpEvents](PumpEvents.md) diff --git a/docs/api/XCEngine/Platform/Windows/WindowsWindow/SetTitle.md b/docs/api/XCEngine/Platform/Windows/WindowsWindow/SetTitle.md index 63dd9a93..dc5eca5f 100644 --- a/docs/api/XCEngine/Platform/Windows/WindowsWindow/SetTitle.md +++ b/docs/api/XCEngine/Platform/Windows/WindowsWindow/SetTitle.md @@ -1,31 +1,26 @@ # WindowsWindow::SetTitle -设置相关状态或配置。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/Windows/WindowsWindow.h` + +## 签名 ```cpp void SetTitle(const Containers::String& title) override; ``` -该方法声明于 `XCEngine/Platform/Windows/WindowsWindow.h`，当前页面用于固定 `WindowsWindow` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `title` - 参数语义详见头文件声明。 +修改 Win32 窗口标题。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::WindowsWindow object; - // 根据上下文补齐参数后调用 WindowsWindow::SetTitle(...)。 - (void)object; -} -``` +- 当 `m_hwnd` 非空时调用 `SetWindowTextA(m_hwnd, title.CStr())`。 ## 相关文档 -- [返回类总览](WindowsWindow.md) -- [返回模块目录](../Windows.md) +- [WindowsWindow](WindowsWindow.md) +- [Create](Create.md) diff --git a/docs/api/XCEngine/Platform/Windows/WindowsWindow/ShouldClose.md b/docs/api/XCEngine/Platform/Windows/WindowsWindow/ShouldClose.md index d6cbc49e..58deda08 100644 --- a/docs/api/XCEngine/Platform/Windows/WindowsWindow/ShouldClose.md +++ b/docs/api/XCEngine/Platform/Windows/WindowsWindow/ShouldClose.md @@ -1,30 +1,27 @@ # WindowsWindow::ShouldClose -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Platform` + +**类型**: `method` + +**头文件**: `XCEngine/Platform/Windows/WindowsWindow.h` + +## 签名 ```cpp bool ShouldClose() const override; ``` -该方法声明于 `XCEngine/Platform/Windows/WindowsWindow.h`，当前页面用于固定 `WindowsWindow` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回窗口是否已经被标记为应关闭。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Platform::WindowsWindow object; - // 根据上下文补齐参数后调用 WindowsWindow::ShouldClose(...)。 - (void)object; -} -``` +- 该方法直接返回成员 `m_shouldClose`。 +- 这个标记会在 `WM_CLOSE` 和 `WM_QUIT` 路径上被置为 `true`。 ## 相关文档 -- [返回类总览](WindowsWindow.md) -- [返回模块目录](../Windows.md) +- [WindowsWindow](WindowsWindow.md) +- [PumpEvents](PumpEvents.md) diff --git a/docs/api/XCEngine/Platform/Windows/WindowsWindow/WindowsWindow.md b/docs/api/XCEngine/Platform/Windows/WindowsWindow/WindowsWindow.md index 0c166d65..83605c0d 100644 --- a/docs/api/XCEngine/Platform/Windows/WindowsWindow/WindowsWindow.md +++ b/docs/api/XCEngine/Platform/Windows/WindowsWindow/WindowsWindow.md @@ -6,39 +6,47 @@ **头文件**: `XCEngine/Platform/Windows/WindowsWindow.h` -**描述**: 定义 `XCEngine/Platform/Windows` 子目录中的 `WindowsWindow` public API。 +**描述**: `Window` 的 Win32 实现，负责创建 `HWND`、泵消息、维护关闭 / 全屏状态，并把消息分发给输入模块和自定义回调。 ## 概述 -`WindowsWindow.h` 是 `XCEngine/Platform/Windows` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。 +`WindowsWindow` 是当前仓库里 `Window` 抽象的具体 Win32 落地。按 `engine/src/Platform/Windows/WindowsWindow.cpp` 的实现，它主要做四件事： + +- 注册 `XCEngineWindowClass` 并创建主窗口 `HWND` +- 用 `PeekMessage` / `DispatchMessage` 推进 Win32 消息循环 +- 在 `WM_CLOSE`、`WM_DESTROY`、`WM_SIZE` 中维护关闭和最小化状态 +- 把消息同时转发给 `m_messageCallback` 和已绑定的 `InputModule` + +全屏切换通过修改窗口样式和缓存旧窗口矩形实现；`Destroy()` 会销毁窗口并注销窗口类。 ## 声明概览 | 声明 | 类型 | 说明 | |------|------|------| -| `WindowsWindow` | `class` | 继承自 `Window` 的公开声明。 | +| `WindowsWindow` | `class` | `Window` 的 Win32 具体实现。 | ## 公共方法 | 方法 | 描述 | |------|------| -| [WindowsWindow()](Constructor.md) | 构造对象。 | -| [~WindowsWindow()](Destructor.md) | 销毁对象并释放相关资源。 | -| [Create](Create.md) | 创建新对象或资源。 | -| [Destroy](Destroy.md) | 公开方法，详见头文件声明。 | -| [GetHandle](GetHandle.md) | 获取相关状态或对象。 | -| [PumpEvents](PumpEvents.md) | 公开方法，详见头文件声明。 | -| [SetTitle](SetTitle.md) | 设置相关状态或配置。 | -| [SetFullscreen](SetFullscreen.md) | 设置相关状态或配置。 | -| [IsFullscreen](IsFullscreen.md) | 查询当前状态。 | -| [Minimize](Minimize.md) | 公开方法，详见头文件声明。 | -| [Maximize](Maximize.md) | 公开方法，详见头文件声明。 | -| [Restore](Restore.md) | 公开方法，详见头文件声明。 | -| [ShouldClose](ShouldClose.md) | 公开方法，详见头文件声明。 | -| [GetNativeHandle](GetNativeHandle.md) | 获取相关状态或对象。 | -| [SetMessageCallback](SetMessageCallback.md) | 设置相关状态或配置。 | +| [WindowsWindow()](Constructor.md) | 初始化空窗口状态。 | +| [~WindowsWindow()](Destructor.md) | 析构时调用 [Destroy](Destroy.md)。 | +| [Create](Create.md) | 创建 `HWND` 并显示窗口。 | +| [Destroy](Destroy.md) | 销毁 `HWND` 并注销窗口类。 | +| [GetHandle](GetHandle.md) | 返回当前 `HWND` 作为 `WindowHandle`。 | +| [PumpEvents](PumpEvents.md) | 处理 Win32 消息并推进输入模块事件。 | +| [SetTitle](SetTitle.md) | 修改 Win32 窗口标题。 | +| [SetFullscreen](SetFullscreen.md) | 通过窗口样式切换 Win32 全屏。 | +| [IsFullscreen](IsFullscreen.md) | 查询 `m_fullscreen` 标记。 | +| [Minimize](Minimize.md) | 调用 `ShowWindow(..., SW_MINIMIZE)`。 | +| [Maximize](Maximize.md) | 调用 `ShowWindow(..., SW_MAXIMIZE)`。 | +| [Restore](Restore.md) | 调用 `ShowWindow(..., SW_RESTORE)` 并清理最小化标记。 | +| [ShouldClose](ShouldClose.md) | 返回 `WM_CLOSE` / `WM_QUIT` 维护的关闭标记。 | +| [GetNativeHandle](GetNativeHandle.md) | 返回原始 `HWND`。 | +| [SetMessageCallback](SetMessageCallback.md) | 绑定额外的 Win32 消息回调。 | ## 相关文档 -- [当前目录](../Windows.md) - 返回 `Windows` 平行目录 -- [API 总索引](../../../../main.md) - 返回顶层索引 +- [Windows](../Windows.md) +- [Window](../../Window/Window.md) +- [WindowsInputModule](../WindowsInputModule/WindowsInputModule.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/AliasBarrier.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/AliasBarrier.md index 8f0c5370..be4b3774 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/AliasBarrier.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/AliasBarrier.md @@ -1,32 +1,25 @@ # D3D12CommandList::AliasBarrier -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp void AliasBarrier(ID3D12Resource* beforeResource = nullptr, ID3D12Resource* afterResource = nullptr); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `beforeResource` - 参数语义详见头文件声明。 -- `afterResource` - 参数语义详见头文件声明。 +执行 `AliasBarrierInternal(...)` 相关流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::AliasBarrier(...)。 - (void)object; -} -``` +- 当前实现会调用 `AliasBarrierInternal`。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/AliasBarrierInternal.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/AliasBarrierInternal.md index 3c316590..f97ea9bc 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/AliasBarrierInternal.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/AliasBarrierInternal.md @@ -1,32 +1,25 @@ # D3D12CommandList::AliasBarrierInternal -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp void AliasBarrierInternal(ID3D12Resource* beforeResource, ID3D12Resource* afterResource); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `beforeResource` - 参数语义详见头文件声明。 -- `afterResource` - 参数语义详见头文件声明。 +执行 `ResourceBarrier` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::AliasBarrierInternal(...)。 - (void)object; -} -``` +- 当前实现会调用 `ResourceBarrier`。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/BeginQuery.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/BeginQuery.md index f5d69252..a2c5aad5 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/BeginQuery.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/BeginQuery.md @@ -1,33 +1,25 @@ # D3D12CommandList::BeginQuery -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp void BeginQuery(ID3D12QueryHeap* queryHeap, QueryType type, uint32_t index); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `queryHeap` - 参数语义详见头文件声明。 -- `type` - 参数语义详见头文件声明。 -- `index` - 参数语义详见头文件声明。 +执行 `BeginQuery`、`ToD3D12` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::BeginQuery(...)。 - (void)object; -} -``` +- 当前实现会调用 `BeginQuery`、`ToD3D12`。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/ClearDepthStencil.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/ClearDepthStencil.md index dda64670..6cb5de26 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/ClearDepthStencil.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/ClearDepthStencil.md @@ -1,33 +1,26 @@ # D3D12CommandList::ClearDepthStencil -清空内部数据。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp -void ClearDepthStencil(RHIResourceView* depthStencil, float depth, uint8_t stencil) override; +void ClearDepthStencil( RHIResourceView* depthStencil, float depth, uint8_t stencil, uint32_t rectCount = 0, const Rect* rects = nullptr) override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `depthStencil` - 参数语义详见头文件声明。 -- `depth` - 参数语义详见头文件声明。 -- `stencil` - 参数语义详见头文件声明。 +执行 `IsValid`、`reserve`、`push_back` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::ClearDepthStencil(...)。 - (void)object; -} -``` +- 当前实现会调用 `IsValid`、`reserve`、`push_back`、`data`、`ClearDepthStencilView`。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/ClearDepthStencilView.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/ClearDepthStencilView.md index 45e3a718..8cb4c58e 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/ClearDepthStencilView.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/ClearDepthStencilView.md @@ -1,54 +1,26 @@ # D3D12CommandList::ClearDepthStencilView -清空内部数据。 +**命名空间**: `XCEngine::RHI` -该方法在 `XCEngine/RHI/D3D12/D3D12CommandList.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。 +**类型**: `method` -## 重载 1: 声明 +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp void ClearDepthStencilView(ID3D12Resource* depthStencil, uint32_t clearFlags, float depth = 1.0f, uint8_t stencil = 0, uint32_t rectCount = 0, const D3D12_RECT* rects = nullptr); -``` - -**参数：** -- `depthStencil` - 参数语义详见头文件声明。 -- `clearFlags` - 参数语义详见头文件声明。 -- `depth` - 参数语义详见头文件声明。 -- `stencil` - 参数语义详见头文件声明。 -- `rectCount` - 参数语义详见头文件声明。 -- `rects` - 参数语义详见头文件声明。 - -**返回：** `void` - 无返回值。 - -## 重载 2: 声明 - -```cpp void ClearDepthStencilView(D3D12_CPU_DESCRIPTOR_HANDLE depthStencilHandle, uint32_t clearFlags, float depth = 1.0f, uint8_t stencil = 0, uint32_t rectCount = 0, const D3D12_RECT* rects = nullptr); ``` -**参数：** -- `depthStencilHandle` - 参数语义详见头文件声明。 -- `clearFlags` - 参数语义详见头文件声明。 -- `depth` - 参数语义详见头文件声明。 -- `stencil` - 参数语义详见头文件声明。 -- `rectCount` - 参数语义详见头文件声明。 -- `rects` - 参数语义详见头文件声明。 +## 作用 -**返回：** `void` - 无返回值。 +执行 `ClearDepthStencilView` 协同流程。 -**示例：** +## 当前实现 -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::ClearDepthStencilView(...)。 - (void)object; -} -``` +- 当前实现会调用 `ClearDepthStencilView`。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/ClearRenderTarget.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/ClearRenderTarget.md index beb1ed9a..1957ca5b 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/ClearRenderTarget.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/ClearRenderTarget.md @@ -1,32 +1,26 @@ # D3D12CommandList::ClearRenderTarget -清空内部数据。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp -void ClearRenderTarget(RHIResourceView* renderTarget, const float color[4]) override; +void ClearRenderTarget( RHIResourceView* renderTarget, const float color[4], uint32_t rectCount = 0, const Rect* rects = nullptr) override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `renderTarget` - 参数语义详见头文件声明。 -- `param` - 参数语义详见头文件声明。 +执行 `IsValid`、`reserve`、`push_back` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::ClearRenderTarget(...)。 - (void)object; -} -``` +- 当前实现会调用 `IsValid`、`reserve`、`push_back`、`data`、`ClearRenderTargetView`。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/ClearRenderTargetView.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/ClearRenderTargetView.md index 9fab3586..19e503fc 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/ClearRenderTargetView.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/ClearRenderTargetView.md @@ -1,50 +1,26 @@ # D3D12CommandList::ClearRenderTargetView -清空内部数据。 +**命名空间**: `XCEngine::RHI` -该方法在 `XCEngine/RHI/D3D12/D3D12CommandList.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。 +**类型**: `method` -## 重载 1: 声明 +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp void ClearRenderTargetView(ID3D12Resource* renderTarget, const float color[4], uint32_t rectCount = 0, const D3D12_RECT* rects = nullptr); -``` - -**参数：** -- `renderTarget` - 参数语义详见头文件声明。 -- `param` - 参数语义详见头文件声明。 -- `rectCount` - 参数语义详见头文件声明。 -- `rects` - 参数语义详见头文件声明。 - -**返回：** `void` - 无返回值。 - -## 重载 2: 声明 - -```cpp void ClearRenderTargetView(D3D12_CPU_DESCRIPTOR_HANDLE renderTargetHandle, const float color[4], uint32_t rectCount = 0, const D3D12_RECT* rects = nullptr); ``` -**参数：** -- `renderTargetHandle` - 参数语义详见头文件声明。 -- `param` - 参数语义详见头文件声明。 -- `rectCount` - 参数语义详见头文件声明。 -- `rects` - 参数语义详见头文件声明。 +## 作用 -**返回：** `void` - 无返回值。 +执行 `ClearRenderTargetView` 协同流程。 -**示例：** +## 当前实现 -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::ClearRenderTargetView(...)。 - (void)object; -} -``` +- 当前实现会调用 `ClearRenderTargetView`。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/ClearUnorderedAccessView.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/ClearUnorderedAccessView.md index 5cbb4103..522bb29c 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/ClearUnorderedAccessView.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/ClearUnorderedAccessView.md @@ -1,36 +1,25 @@ # D3D12CommandList::ClearUnorderedAccessView -清空内部数据。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp void ClearUnorderedAccessView(D3D12_GPU_DESCRIPTOR_HANDLE viewHandle, D3D12_CPU_DESCRIPTOR_HANDLE resourceHandle, ID3D12Resource* unorderedAccess, const float values[4], uint32_t rectCount = 0, const D3D12_RECT* rects = nullptr); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `viewHandle` - 参数语义详见头文件声明。 -- `resourceHandle` - 参数语义详见头文件声明。 -- `unorderedAccess` - 参数语义详见头文件声明。 -- `param` - 参数语义详见头文件声明。 -- `rectCount` - 参数语义详见头文件声明。 -- `rects` - 参数语义详见头文件声明。 +执行 `ClearUnorderedAccessViewFloat` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::ClearUnorderedAccessView(...)。 - (void)object; -} -``` +- 当前实现会调用 `ClearUnorderedAccessViewFloat`。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/Close.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/Close.md index 932bef61..e822ba87 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/Close.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/Close.md @@ -1,30 +1,25 @@ # D3D12CommandList::Close -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp void Close() override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `Close` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::Close(...)。 - (void)object; -} -``` +- 当前实现会调用 `Close`。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/Constructor.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/Constructor.md index 2fc594c8..a1f4ca99 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/Constructor.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/Constructor.md @@ -1,28 +1,25 @@ # D3D12CommandList::D3D12CommandList() -构造对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp D3D12CommandList(); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +构造 `D3D12CommandList` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; -} -``` +- 具体定义位于 `engine/src/RHI/D3D12/D3D12CommandList.cpp`。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/CopyBuffer.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/CopyBuffer.md index e8b589fe..05b18450 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/CopyBuffer.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/CopyBuffer.md @@ -1,35 +1,26 @@ # D3D12CommandList::CopyBuffer -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp void CopyBuffer(ID3D12Resource* dst, uint64_t dstOffset, ID3D12Resource* src, uint64_t srcOffset, uint64_t size); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `dst` - 参数语义详见头文件声明。 -- `dstOffset` - 参数语义详见头文件声明。 -- `src` - 参数语义详见头文件声明。 -- `srcOffset` - 参数语义详见头文件声明。 -- `size` - 参数语义详见头文件声明。 +执行 `CopyTextureRegion` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::CopyBuffer(...)。 - (void)object; -} -``` +- 当前实现会调用 `CopyTextureRegion`。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/CopyResourceInternal.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/CopyResourceInternal.md index 9c18e069..7bc8c0c0 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/CopyResourceInternal.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/CopyResourceInternal.md @@ -1,32 +1,25 @@ # D3D12CommandList::CopyResourceInternal -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp void CopyResourceInternal(ID3D12Resource* dst, ID3D12Resource* src); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `dst` - 参数语义详见头文件声明。 -- `src` - 参数语义详见头文件声明。 +执行 `CopyResource` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::CopyResourceInternal(...)。 - (void)object; -} -``` +- 当前实现会调用 `CopyResource`。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/CopyTexture.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/CopyTexture.md index f476a191..c5c52d6e 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/CopyTexture.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/CopyTexture.md @@ -1,34 +1,26 @@ # D3D12CommandList::CopyTexture -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp void CopyTexture(ID3D12Resource* dst, const D3D12_TEXTURE_COPY_LOCATION& dstLocation, ID3D12Resource* src, const D3D12_TEXTURE_COPY_LOCATION& srcLocation); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `dst` - 参数语义详见头文件声明。 -- `dstLocation` - 参数语义详见头文件声明。 -- `src` - 参数语义详见头文件声明。 -- `srcLocation` - 参数语义详见头文件声明。 +执行 `CopyTextureRegion` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::CopyTexture(...)。 - (void)object; -} -``` +- 当前实现会调用 `CopyTextureRegion`。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/Destructor.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/Destructor.md index 2d6a7a5b..93bb957a 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/Destructor.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/Destructor.md @@ -1,29 +1,25 @@ # D3D12CommandList::~D3D12CommandList() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp ~D3D12CommandList() override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `Shutdown(...)` 相关流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 当前实现会调用 `Shutdown`。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/DispatchIndirect.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/DispatchIndirect.md index ac68a486..a46a56b5 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/DispatchIndirect.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/DispatchIndirect.md @@ -1,32 +1,25 @@ # D3D12CommandList::DispatchIndirect -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp void DispatchIndirect(ID3D12Resource* argBuffer, uint64_t alignedByteOffset); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `argBuffer` - 参数语义详见头文件声明。 -- `alignedByteOffset` - 参数语义详见头文件声明。 +执行 `DispatchIndirectInternal(...)` 相关流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::DispatchIndirect(...)。 - (void)object; -} -``` +- 当前实现会调用 `DispatchIndirectInternal`。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/DispatchIndirectInternal.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/DispatchIndirectInternal.md index 507550b8..de71b3f0 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/DispatchIndirectInternal.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/DispatchIndirectInternal.md @@ -1,32 +1,26 @@ # D3D12CommandList::DispatchIndirectInternal -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp void DispatchIndirectInternal(ID3D12Resource* argBuffer, uint64_t alignedByteOffset); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `argBuffer` - 参数语义详见头文件声明。 -- `alignedByteOffset` - 参数语义详见头文件声明。 +执行 `ExecuteIndirect` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::DispatchIndirectInternal(...)。 - (void)object; -} -``` +- 当前实现会调用 `ExecuteIndirect`。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/DrawIndexedInstancedIndirect.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/DrawIndexedInstancedIndirect.md index 5cc5a04a..de935742 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/DrawIndexedInstancedIndirect.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/DrawIndexedInstancedIndirect.md @@ -1,32 +1,25 @@ # D3D12CommandList::DrawIndexedInstancedIndirect -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp void DrawIndexedInstancedIndirect(ID3D12Resource* argBuffer, uint64_t alignedByteOffset); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `argBuffer` - 参数语义详见头文件声明。 -- `alignedByteOffset` - 参数语义详见头文件声明。 +执行 `DrawIndexedInstancedIndirectInternal(...)` 相关流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::DrawIndexedInstancedIndirect(...)。 - (void)object; -} -``` +- 当前实现会调用 `DrawIndexedInstancedIndirectInternal`。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/DrawIndexedInstancedIndirectInternal.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/DrawIndexedInstancedIndirectInternal.md index e7af3090..3522eda7 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/DrawIndexedInstancedIndirectInternal.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/DrawIndexedInstancedIndirectInternal.md @@ -1,32 +1,26 @@ # D3D12CommandList::DrawIndexedInstancedIndirectInternal -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp void DrawIndexedInstancedIndirectInternal(ID3D12Resource* argBuffer, uint64_t alignedByteOffset); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `argBuffer` - 参数语义详见头文件声明。 -- `alignedByteOffset` - 参数语义详见头文件声明。 +执行 `ExecuteIndirect` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::DrawIndexedInstancedIndirectInternal(...)。 - (void)object; -} -``` +- 当前实现会调用 `ExecuteIndirect`。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/DrawInstancedIndirect.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/DrawInstancedIndirect.md index 9a39683b..d1ba92c1 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/DrawInstancedIndirect.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/DrawInstancedIndirect.md @@ -1,32 +1,25 @@ # D3D12CommandList::DrawInstancedIndirect -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp void DrawInstancedIndirect(ID3D12Resource* argBuffer, uint64_t alignedByteOffset); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `argBuffer` - 参数语义详见头文件声明。 -- `alignedByteOffset` - 参数语义详见头文件声明。 +执行 `DrawInstancedIndirectInternal(...)` 相关流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::DrawInstancedIndirect(...)。 - (void)object; -} -``` +- 当前实现会调用 `DrawInstancedIndirectInternal`。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/DrawInstancedIndirectInternal.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/DrawInstancedIndirectInternal.md index 43bfe23b..f4c48283 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/DrawInstancedIndirectInternal.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/DrawInstancedIndirectInternal.md @@ -1,32 +1,26 @@ # D3D12CommandList::DrawInstancedIndirectInternal -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp void DrawInstancedIndirectInternal(ID3D12Resource* argBuffer, uint64_t alignedByteOffset); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `argBuffer` - 参数语义详见头文件声明。 -- `alignedByteOffset` - 参数语义详见头文件声明。 +执行 `ExecuteIndirect` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::DrawInstancedIndirectInternal(...)。 - (void)object; -} -``` +- 当前实现会调用 `ExecuteIndirect`。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/EndQuery.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/EndQuery.md index 0497c8a0..2962dd0e 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/EndQuery.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/EndQuery.md @@ -1,33 +1,25 @@ # D3D12CommandList::EndQuery -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp void EndQuery(ID3D12QueryHeap* queryHeap, QueryType type, uint32_t index); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `queryHeap` - 参数语义详见头文件声明。 -- `type` - 参数语义详见头文件声明。 -- `index` - 参数语义详见头文件声明。 +执行 `EndQuery`、`ToD3D12` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::EndQuery(...)。 - (void)object; -} -``` +- 当前实现会调用 `EndQuery`、`ToD3D12`。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/EndRenderPass.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/EndRenderPass.md index a081ca22..09bc827e 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/EndRenderPass.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/EndRenderPass.md @@ -1,30 +1,25 @@ # D3D12CommandList::EndRenderPass -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp void EndRenderPass() override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +当前实现为空。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::EndRenderPass(...)。 - (void)object; -} -``` +- 当前函数体为空。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/ExecuteBundle.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/ExecuteBundle.md index d90292a7..f43e1de2 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/ExecuteBundle.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/ExecuteBundle.md @@ -1,31 +1,25 @@ # D3D12CommandList::ExecuteBundle -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp void ExecuteBundle(ID3D12GraphicsCommandList* bundle); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `bundle` - 参数语义详见头文件声明。 +执行 `ExecuteBundle` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::ExecuteBundle(...)。 - (void)object; -} -``` +- 当前实现会调用 `ExecuteBundle`。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/GetCommandList.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/GetCommandList.md index d40372fe..9cd86d82 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/GetCommandList.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/GetCommandList.md @@ -1,30 +1,25 @@ # D3D12CommandList::GetCommandList -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp ID3D12GraphicsCommandList* GetCommandList() const; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_commandList`。 -**返回：** `ID3D12GraphicsCommandList*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::GetCommandList(...)。 - (void)object; -} -``` +- 会更新 `m_commandList`。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/GetNativeHandle.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/GetNativeHandle.md index 9f9e64f0..e32c2190 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/GetNativeHandle.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/GetNativeHandle.md @@ -1,30 +1,25 @@ # D3D12CommandList::GetNativeHandle -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp void* GetNativeHandle() override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `GetCommandList(...)` 相关流程。 -**返回：** `void*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::GetNativeHandle(...)。 - (void)object; -} -``` +- 当前实现会调用 `GetCommandList`。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/GetResourceState.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/GetResourceState.md index 68969c1c..e5d5a4f7 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/GetResourceState.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/GetResourceState.md @@ -1,31 +1,27 @@ # D3D12CommandList::GetResourceState -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp ResourceStates GetResourceState(ID3D12Resource* resource) const; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `resource` - 参数语义详见头文件声明。 +更新 `m_resourceStateMap`。 -**返回：** `ResourceStates` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::GetResourceState(...)。 - (void)object; -} -``` +- 会更新 `m_resourceStateMap`。 +- 当前实现会调用 `find`、`end`。 +- 包含条件分支，并可能提前返回。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/Initialize.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/Initialize.md index f550c3e2..fc41b557 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/Initialize.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/Initialize.md @@ -1,33 +1,28 @@ # D3D12CommandList::Initialize -初始化内部状态。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp bool Initialize(ID3D12Device* device, CommandQueueType type = CommandQueueType::Direct, ID3D12CommandAllocator* allocator = nullptr); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `device` - 参数语义详见头文件声明。 -- `type` - 参数语义详见头文件声明。 -- `allocator` - 参数语义详见头文件声明。 +执行 `ToD3D12`、`sprintf`、`OutputDebugStringA` 协同流程。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::Initialize(...)。 - (void)object; -} -``` +- 会更新 `m_commandAllocator`、`m_device`、`m_type`。 +- 当前实现会调用 `ToD3D12`、`sprintf`、`OutputDebugStringA`、`CreateCommandList`、`IID_PPV_ARGS`。 +- 包含条件分支，并可能提前返回。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/Reset.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/Reset.md index 21c55444..60801df5 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/Reset.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/Reset.md @@ -1,30 +1,27 @@ # D3D12CommandList::Reset -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp void Reset() override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `Reset`、`clear` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::Reset(...)。 - (void)object; -} -``` +- 会更新 `m_currentTopology`、`m_currentPipelineState`、`m_currentRootSignature`、`m_currentPipelineLayout`。 +- 当前实现会调用 `Reset`、`clear`。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/ResolveQueryData.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/ResolveQueryData.md index 4edbde73..239cd577 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/ResolveQueryData.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/ResolveQueryData.md @@ -1,36 +1,25 @@ # D3D12CommandList::ResolveQueryData -解析并返回目标结果。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp void ResolveQueryData(ID3D12QueryHeap* queryHeap, QueryType type, uint32_t startIndex, uint32_t count, ID3D12Resource* resultBuffer, uint64_t resultOffset); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `queryHeap` - 参数语义详见头文件声明。 -- `type` - 参数语义详见头文件声明。 -- `startIndex` - 参数语义详见头文件声明。 -- `count` - 参数语义详见头文件声明。 -- `resultBuffer` - 参数语义详见头文件声明。 -- `resultOffset` - 参数语义详见头文件声明。 +执行 `ResolveQueryData`、`ToD3D12` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::ResolveQueryData(...)。 - (void)object; -} -``` +- 当前实现会调用 `ResolveQueryData`、`ToD3D12`。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetBlendFactor.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetBlendFactor.md index e0870e05..715ee26d 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetBlendFactor.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetBlendFactor.md @@ -1,31 +1,25 @@ # D3D12CommandList::SetBlendFactor -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp void SetBlendFactor(const float blendFactor[4]); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `param` - 参数语义详见头文件声明。 +执行 `OMSetBlendFactor` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::SetBlendFactor(...)。 - (void)object; -} -``` +- 当前实现会调用 `OMSetBlendFactor`。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetComputeDescriptorTable.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetComputeDescriptorTable.md index dc238d65..0e932528 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetComputeDescriptorTable.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetComputeDescriptorTable.md @@ -1,32 +1,25 @@ # D3D12CommandList::SetComputeDescriptorTable -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp void SetComputeDescriptorTable(uint32_t rootParameterIndex, D3D12_GPU_DESCRIPTOR_HANDLE baseHandle); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `rootParameterIndex` - 参数语义详见头文件声明。 -- `baseHandle` - 参数语义详见头文件声明。 +执行 `SetComputeRootDescriptorTable` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::SetComputeDescriptorTable(...)。 - (void)object; -} -``` +- 当前实现会调用 `SetComputeRootDescriptorTable`。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetDepthBias.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetDepthBias.md index 255cfb51..e90e2c58 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetDepthBias.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetDepthBias.md @@ -1,33 +1,25 @@ # D3D12CommandList::SetDepthBias -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp void SetDepthBias(float depthBias, float slopeScaledDepthBias, float depthBiasClamp); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `depthBias` - 参数语义详见头文件声明。 -- `slopeScaledDepthBias` - 参数语义详见头文件声明。 -- `depthBiasClamp` - 参数语义详见头文件声明。 +当前实现为空。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::SetDepthBias(...)。 - (void)object; -} -``` +- 当前函数体为空。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetDescriptorHeap.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetDescriptorHeap.md index 84a3599d..935a3ef9 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetDescriptorHeap.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetDescriptorHeap.md @@ -1,31 +1,26 @@ # D3D12CommandList::SetDescriptorHeap -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp void SetDescriptorHeap(ID3D12DescriptorHeap* heap); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `heap` - 参数语义详见头文件声明。 +更新 `m_currentDescriptorHeap`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::SetDescriptorHeap(...)。 - (void)object; -} -``` +- 会更新 `m_currentDescriptorHeap`。 +- 当前实现会调用 `SetDescriptorHeaps`。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetDescriptorHeaps.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetDescriptorHeaps.md index 140bc5ea..4156d86e 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetDescriptorHeaps.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetDescriptorHeaps.md @@ -1,32 +1,25 @@ # D3D12CommandList::SetDescriptorHeaps -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp void SetDescriptorHeaps(uint32_t count, ID3D12DescriptorHeap** heaps); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `count` - 参数语义详见头文件声明。 -- `heaps` - 参数语义详见头文件声明。 +执行 `SetDescriptorHeaps` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::SetDescriptorHeaps(...)。 - (void)object; -} -``` +- 当前实现会调用 `SetDescriptorHeaps`。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetGraphicsDescriptorTable.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetGraphicsDescriptorTable.md index c3bc3a1f..0cbc1833 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetGraphicsDescriptorTable.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetGraphicsDescriptorTable.md @@ -1,32 +1,25 @@ # D3D12CommandList::SetGraphicsDescriptorTable -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp void SetGraphicsDescriptorTable(uint32_t rootParameterIndex, D3D12_GPU_DESCRIPTOR_HANDLE baseHandle); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `rootParameterIndex` - 参数语义详见头文件声明。 -- `baseHandle` - 参数语义详见头文件声明。 +执行 `SetGraphicsRootDescriptorTable` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::SetGraphicsDescriptorTable(...)。 - (void)object; -} -``` +- 当前实现会调用 `SetGraphicsRootDescriptorTable`。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetGraphicsRoot32BitConstants.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetGraphicsRoot32BitConstants.md index 0bb4b80f..47058463 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetGraphicsRoot32BitConstants.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetGraphicsRoot32BitConstants.md @@ -1,34 +1,25 @@ # D3D12CommandList::SetGraphicsRoot32BitConstants -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp void SetGraphicsRoot32BitConstants(uint32_t rootParameterIndex, uint32_t num32BitValuesToSet, const void* pSrcData, uint32_t destOffsetIn32BitValues); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `rootParameterIndex` - 参数语义详见头文件声明。 -- `num32BitValuesToSet` - 参数语义详见头文件声明。 -- `pSrcData` - 参数语义详见头文件声明。 -- `destOffsetIn32BitValues` - 参数语义详见头文件声明。 +执行 `SetGraphicsRoot32BitConstants` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::SetGraphicsRoot32BitConstants(...)。 - (void)object; -} -``` +- 当前实现会调用 `SetGraphicsRoot32BitConstants`。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetGraphicsRootConstantBufferView.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetGraphicsRootConstantBufferView.md index 84b7fa6e..969e7010 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetGraphicsRootConstantBufferView.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetGraphicsRootConstantBufferView.md @@ -1,32 +1,25 @@ # D3D12CommandList::SetGraphicsRootConstantBufferView -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp void SetGraphicsRootConstantBufferView(uint32_t rootParameterIndex, D3D12_GPU_VIRTUAL_ADDRESS bufferLocation); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `rootParameterIndex` - 参数语义详见头文件声明。 -- `bufferLocation` - 参数语义详见头文件声明。 +执行 `SetGraphicsRootConstantBufferView` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::SetGraphicsRootConstantBufferView(...)。 - (void)object; -} -``` +- 当前实现会调用 `SetGraphicsRootConstantBufferView`。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetGraphicsRootDescriptorTable.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetGraphicsRootDescriptorTable.md index cd7f7324..60e91310 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetGraphicsRootDescriptorTable.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetGraphicsRootDescriptorTable.md @@ -1,32 +1,25 @@ # D3D12CommandList::SetGraphicsRootDescriptorTable -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp void SetGraphicsRootDescriptorTable(uint32_t rootParameterIndex, D3D12_GPU_DESCRIPTOR_HANDLE baseDescriptor); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `rootParameterIndex` - 参数语义详见头文件声明。 -- `baseDescriptor` - 参数语义详见头文件声明。 +执行 `SetGraphicsRootDescriptorTable` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::SetGraphicsRootDescriptorTable(...)。 - (void)object; -} -``` +- 当前实现会调用 `SetGraphicsRootDescriptorTable`。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetGraphicsRootShaderResourceView.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetGraphicsRootShaderResourceView.md index 260bb42c..ede3143b 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetGraphicsRootShaderResourceView.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetGraphicsRootShaderResourceView.md @@ -1,32 +1,25 @@ # D3D12CommandList::SetGraphicsRootShaderResourceView -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp void SetGraphicsRootShaderResourceView(uint32_t rootParameterIndex, D3D12_GPU_VIRTUAL_ADDRESS shaderResource); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `rootParameterIndex` - 参数语义详见头文件声明。 -- `shaderResource` - 参数语义详见头文件声明。 +执行 `SetGraphicsRootShaderResourceView` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::SetGraphicsRootShaderResourceView(...)。 - (void)object; -} -``` +- 当前实现会调用 `SetGraphicsRootShaderResourceView`。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetIndexBufferInternal.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetIndexBufferInternal.md index afe38bf0..d2fba0fd 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetIndexBufferInternal.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetIndexBufferInternal.md @@ -1,33 +1,25 @@ # D3D12CommandList::SetIndexBufferInternal -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp void SetIndexBufferInternal(ID3D12Resource* buffer, uint64_t offset, Format indexFormat); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `buffer` - 参数语义详见头文件声明。 -- `offset` - 参数语义详见头文件声明。 -- `indexFormat` - 参数语义详见头文件声明。 +执行 `GetGPUVirtualAddress`、`GetDesc`、`ToD3D12` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::SetIndexBufferInternal(...)。 - (void)object; -} -``` +- 当前实现会调用 `GetGPUVirtualAddress`、`GetDesc`、`ToD3D12`、`IASetIndexBuffer`。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetPipelineLayout.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetPipelineLayout.md index d3754374..bafc5558 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetPipelineLayout.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetPipelineLayout.md @@ -1,31 +1,26 @@ # D3D12CommandList::SetPipelineLayout -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp void SetPipelineLayout(D3D12PipelineLayout* layout); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `layout` - 参数语义详见头文件声明。 +更新 `m_currentPipelineLayout`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::SetPipelineLayout(...)。 - (void)object; -} -``` +- 会更新 `m_currentPipelineLayout`。 +- 当前实现会调用 `SetRootSignature`、`GetRootSignature`。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetPipelineStateInternal.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetPipelineStateInternal.md index 6ccd5d81..89a91371 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetPipelineStateInternal.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetPipelineStateInternal.md @@ -1,31 +1,27 @@ # D3D12CommandList::SetPipelineStateInternal -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp void SetPipelineStateInternal(ID3D12PipelineState* pso); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `pso` - 参数语义详见头文件声明。 +更新 `m_currentPipelineState`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::SetPipelineStateInternal(...)。 - (void)object; -} -``` +- 会更新 `m_currentPipelineState`。 +- 当前实现会调用 `SetPipelineState`、`SetGraphicsRootSignature`。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetPrimitiveTopology.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetPrimitiveTopology.md index 929ea7d3..c7887465 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetPrimitiveTopology.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetPrimitiveTopology.md @@ -1,31 +1,26 @@ # D3D12CommandList::SetPrimitiveTopology -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp void SetPrimitiveTopology(PrimitiveTopology topology); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `topology` - 参数语义详见头文件声明。 +更新 `m_currentTopology`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::SetPrimitiveTopology(...)。 - (void)object; -} -``` +- 会更新 `m_currentTopology`。 +- 当前实现会调用 `IASetPrimitiveTopology`、`ToD3D12Topology`。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetRenderTargetsHandle.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetRenderTargetsHandle.md index b7a6e35a..a6e4b7b6 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetRenderTargetsHandle.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetRenderTargetsHandle.md @@ -1,33 +1,26 @@ # D3D12CommandList::SetRenderTargetsHandle -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp void SetRenderTargetsHandle(uint32_t count, const D3D12_CPU_DESCRIPTOR_HANDLE* renderTargetHandles, const D3D12_CPU_DESCRIPTOR_HANDLE* depthStencilHandle = nullptr); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `count` - 参数语义详见头文件声明。 -- `renderTargetHandles` - 参数语义详见头文件声明。 -- `depthStencilHandle` - 参数语义详见头文件声明。 +执行 `OMSetRenderTargets`、`clear`、`push_back` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::SetRenderTargetsHandle(...)。 - (void)object; -} -``` +- 会更新 `m_boundDepthStencil`、`m_depthStencilBound`。 +- 当前实现会调用 `OMSetRenderTargets`、`clear`、`push_back`。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetRenderTargetsInternal.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetRenderTargetsInternal.md index 9192c780..af457d82 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetRenderTargetsInternal.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetRenderTargetsInternal.md @@ -1,33 +1,26 @@ # D3D12CommandList::SetRenderTargetsInternal -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp void SetRenderTargetsInternal(uint32_t count, ID3D12Resource** renderTargets, ID3D12Resource* depthStencil = nullptr); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `count` - 参数语义详见头文件声明。 -- `renderTargets` - 参数语义详见头文件声明。 -- `depthStencil` - 参数语义详见头文件声明。 +执行 `rtvHandles`、`OMSetRenderTargets`、`data` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::SetRenderTargetsInternal(...)。 - (void)object; -} -``` +- 当前实现会调用 `rtvHandles`、`OMSetRenderTargets`、`data`。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetRootSignature.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetRootSignature.md index c6646863..a93bfe1f 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetRootSignature.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetRootSignature.md @@ -1,31 +1,26 @@ # D3D12CommandList::SetRootSignature -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp void SetRootSignature(ID3D12RootSignature* signature); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `signature` - 参数语义详见头文件声明。 +更新 `m_currentRootSignature`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::SetRootSignature(...)。 - (void)object; -} -``` +- 会更新 `m_currentRootSignature`。 +- 当前实现会调用 `SetGraphicsRootSignature`。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetScissorRect.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetScissorRect.md index 3fe4afec..a89c0312 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetScissorRect.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetScissorRect.md @@ -1,31 +1,25 @@ # D3D12CommandList::SetScissorRect -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp void SetScissorRect(const Rect& rect) override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `rect` - 参数语义详见头文件声明。 +执行 `RSSetScissorRects` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::SetScissorRect(...)。 - (void)object; -} -``` +- 当前实现会调用 `RSSetScissorRects`。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetScissorRects.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetScissorRects.md index c582f4dc..ae8004a0 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetScissorRects.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetScissorRects.md @@ -1,32 +1,25 @@ # D3D12CommandList::SetScissorRects -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp void SetScissorRects(uint32_t count, const Rect* rects) override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `count` - 参数语义详见头文件声明。 -- `rects` - 参数语义详见头文件声明。 +执行 `d3d12Rects`、`RSSetScissorRects`、`data` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::SetScissorRects(...)。 - (void)object; -} -``` +- 当前实现会调用 `d3d12Rects`、`RSSetScissorRects`、`data`。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetShader.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetShader.md index 1e1d227f..ca124eb3 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetShader.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetShader.md @@ -1,31 +1,25 @@ # D3D12CommandList::SetShader -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp void SetShader(RHIShader* shader) override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `shader` - 参数语义详见头文件声明。 +更新 `m_currentShader`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::SetShader(...)。 - (void)object; -} -``` +- 会更新 `m_currentShader`。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetStencilRef.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetStencilRef.md index b6300d19..b17c9f0a 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetStencilRef.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetStencilRef.md @@ -1,31 +1,25 @@ # D3D12CommandList::SetStencilRef -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp void SetStencilRef(uint8_t stencilRef) override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `stencilRef` - 参数语义详见头文件声明。 +执行 `OMSetStencilRef` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::SetStencilRef(...)。 - (void)object; -} -``` +- 当前实现会调用 `OMSetStencilRef`。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetVertexBuffer.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetVertexBuffer.md index 5d819098..80680b40 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetVertexBuffer.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetVertexBuffer.md @@ -1,34 +1,25 @@ # D3D12CommandList::SetVertexBuffer -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp void SetVertexBuffer(uint32_t slot, ID3D12Resource* resource, uint64_t offset, uint32_t stride); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `slot` - 参数语义详见头文件声明。 -- `resource` - 参数语义详见头文件声明。 -- `offset` - 参数语义详见头文件声明。 -- `stride` - 参数语义详见头文件声明。 +执行 `GetGPUVirtualAddress`、`GetDesc`、`SetVertexBuffersInternal` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::SetVertexBuffer(...)。 - (void)object; -} -``` +- 当前实现会调用 `GetGPUVirtualAddress`、`GetDesc`、`SetVertexBuffersInternal`。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetVertexBuffersInternal.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetVertexBuffersInternal.md index d64da34d..0540abe5 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetVertexBuffersInternal.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetVertexBuffersInternal.md @@ -1,33 +1,25 @@ # D3D12CommandList::SetVertexBuffersInternal -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp void SetVertexBuffersInternal(uint32_t startSlot, uint32_t count, const D3D12_VERTEX_BUFFER_VIEW* views); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `startSlot` - 参数语义详见头文件声明。 -- `count` - 参数语义详见头文件声明。 -- `views` - 参数语义详见头文件声明。 +执行 `IASetVertexBuffers` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::SetVertexBuffersInternal(...)。 - (void)object; -} -``` +- 当前实现会调用 `IASetVertexBuffers`。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetViewport.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetViewport.md index 4157c76f..cfbde059 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetViewport.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetViewport.md @@ -1,31 +1,25 @@ # D3D12CommandList::SetViewport -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp void SetViewport(const Viewport& viewport) override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `viewport` - 参数语义详见头文件声明。 +执行 `RSSetViewports` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::SetViewport(...)。 - (void)object; -} -``` +- 当前实现会调用 `RSSetViewports`。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetViewports.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetViewports.md index a720548c..82a9c0c4 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetViewports.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/SetViewports.md @@ -1,32 +1,25 @@ # D3D12CommandList::SetViewports -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp void SetViewports(uint32_t count, const Viewport* viewports) override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `count` - 参数语义详见头文件声明。 -- `viewports` - 参数语义详见头文件声明。 +执行 `d3d12Viewports`、`RSSetViewports`、`data` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::SetViewports(...)。 - (void)object; -} -``` +- 当前实现会调用 `d3d12Viewports`、`RSSetViewports`、`data`。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/Shutdown.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/Shutdown.md index 3e276452..4a72fdd1 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/Shutdown.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/Shutdown.md @@ -1,30 +1,27 @@ # D3D12CommandList::Shutdown -关闭并清理内部状态。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp void Shutdown() override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `Reset`、`clear` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::Shutdown(...)。 - (void)object; -} -``` +- 会更新 `m_currentShader`、`m_commandList`、`m_rtvHeap`。 +- 当前实现会调用 `Reset`、`clear`。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/TrackResource.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/TrackResource.md index 59fca6dd..4997832e 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/TrackResource.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/TrackResource.md @@ -1,31 +1,25 @@ # D3D12CommandList::TrackResource -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp void TrackResource(ID3D12Resource* resource); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `resource` - 参数语义详见头文件声明。 +执行 `push_back`、`find`、`end` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::TrackResource(...)。 - (void)object; -} -``` +- 当前实现会调用 `push_back`、`find`、`end`。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/TransitionBarrierInternal.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/TransitionBarrierInternal.md index 90bffe55..5618dadf 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/TransitionBarrierInternal.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/TransitionBarrierInternal.md @@ -1,34 +1,25 @@ # D3D12CommandList::TransitionBarrierInternal -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp void TransitionBarrierInternal(ID3D12Resource* resource, ResourceStates stateBefore, ResourceStates stateAfter, uint32_t subresource = D3D12_RESOURCE_BARRIER_ALL_SUBRESOURCES); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `resource` - 参数语义详见头文件声明。 -- `stateBefore` - 参数语义详见头文件声明。 -- `stateAfter` - 参数语义详见头文件声明。 -- `subresource` - 参数语义详见头文件声明。 +执行 `ToD3D12`、`ResourceBarrier` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::TransitionBarrierInternal(...)。 - (void)object; -} -``` +- 当前实现会调用 `ToD3D12`、`ResourceBarrier`。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/UAVBarrier.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/UAVBarrier.md index 5d5a8f2b..7097eb2f 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/UAVBarrier.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/UAVBarrier.md @@ -1,31 +1,25 @@ # D3D12CommandList::UAVBarrier -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp void UAVBarrier(ID3D12Resource* resource = nullptr); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `resource` - 参数语义详见头文件声明。 +执行 `UAVBarrierInternal(...)` 相关流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::UAVBarrier(...)。 - (void)object; -} -``` +- 当前实现会调用 `UAVBarrierInternal`。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/UAVBarrierInternal.md b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/UAVBarrierInternal.md index 510bf9f0..e9c113bf 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/UAVBarrierInternal.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/UAVBarrierInternal.md @@ -1,31 +1,25 @@ # D3D12CommandList::UAVBarrierInternal -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12CommandList.h` + +## 签名 ```cpp void UAVBarrierInternal(ID3D12Resource* resource); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12CommandList.h`，当前页面用于固定 `D3D12CommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `resource` - 参数语义详见头文件声明。 +执行 `ResourceBarrier` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12CommandList object; - // 根据上下文补齐参数后调用 D3D12CommandList::UAVBarrierInternal(...)。 - (void)object; -} -``` +- 当前实现会调用 `ResourceBarrier`。 ## 相关文档 -- [返回类总览](D3D12CommandList.md) -- [返回模块目录](../D3D12.md) +- [D3D12CommandList](D3D12CommandList.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Common/D3D12Common.md b/docs/api/XCEngine/RHI/D3D12/D3D12Common/D3D12Common.md index b14f7e1f..3824aa00 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12Common/D3D12Common.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12Common/D3D12Common.md @@ -6,11 +6,19 @@ **头文件**: `XCEngine/RHI/D3D12/D3D12Common.h` -**描述**: 定义 `XCEngine/RHI/D3D12` 子目录中的 `D3D12Common` public API。 +**描述**: D3D12 常用便捷函数集合，覆盖 descriptor 大小查询、barrier 构造、格式能力检查和若干原生描述结构创建。 ## 概述 -`D3D12Common.h` 是 `XCEngine/RHI/D3D12` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。 +`D3D12Common.h` 提供的是一组 D3D12 后端到处会用到的“小工具函数”，不是一个需要单独实例化的类型。当前头文件里的 helper 主要分成几类： + +- descriptor heap 步长查询 +- transition / UAV / aliasing barrier 构造 +- DXGI format 能力检查 +- clear value、viewport、scissor rect、buffer view 构造 +- CPU / GPU descriptor handle 偏移计算 + +这些函数的目的，是把 D3D12 原生 API 里重复、易错的样板代码压缩成统一入口。 ## 相关文档 diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/Constructor.md b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/Constructor.md index a7a69d32..092bd88b 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/Constructor.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/Constructor.md @@ -1,28 +1,25 @@ # D3D12DescriptorSet::D3D12DescriptorSet() -构造对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12DescriptorSet.h` + +## 签名 ```cpp D3D12DescriptorSet(); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12DescriptorSet.h`，当前页面用于固定 `D3D12DescriptorSet` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +构造 `D3D12DescriptorSet` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12DescriptorSet object; -} -``` +- 具体定义位于 `engine/src/RHI/D3D12/D3D12DescriptorSet.cpp`。 ## 相关文档 -- [返回类总览](D3D12DescriptorSet.md) -- [返回模块目录](../D3D12.md) +- [D3D12DescriptorSet](D3D12DescriptorSet.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/Destructor.md b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/Destructor.md index 0e47329f..3e556275 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/Destructor.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/Destructor.md @@ -1,29 +1,25 @@ # D3D12DescriptorSet::~D3D12DescriptorSet() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12DescriptorSet.h` + +## 签名 ```cpp ~D3D12DescriptorSet() override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12DescriptorSet.h`，当前页面用于固定 `D3D12DescriptorSet` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `Shutdown(...)` 相关流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12DescriptorSet object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 当前实现会调用 `Shutdown`。 ## 相关文档 -- [返回类总览](D3D12DescriptorSet.md) -- [返回模块目录](../D3D12.md) +- [D3D12DescriptorSet](D3D12DescriptorSet.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/GetBindingCount.md b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/GetBindingCount.md index 0ccbca1b..d0e2f8a6 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/GetBindingCount.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/GetBindingCount.md @@ -1,30 +1,25 @@ # D3D12DescriptorSet::GetBindingCount -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12DescriptorSet.h` + +## 签名 ```cpp uint32_t GetBindingCount() const override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12DescriptorSet.h`，当前页面用于固定 `D3D12DescriptorSet` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_bindingCount` 当前值。 -**返回：** `uint32_t` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12DescriptorSet object; - // 根据上下文补齐参数后调用 D3D12DescriptorSet::GetBindingCount(...)。 - (void)object; -} -``` +- 返回 `m_bindingCount` 当前值。 ## 相关文档 -- [返回类总览](D3D12DescriptorSet.md) -- [返回模块目录](../D3D12.md) +- [D3D12DescriptorSet](D3D12DescriptorSet.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/GetBindings.md b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/GetBindings.md index dc157213..434ee064 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/GetBindings.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/GetBindings.md @@ -1,30 +1,27 @@ # D3D12DescriptorSet::GetBindings -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12DescriptorSet.h` + +## 签名 ```cpp const DescriptorSetLayoutBinding* GetBindings() const override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12DescriptorSet.h`，当前页面用于固定 `D3D12DescriptorSet` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_bindings`。 -**返回：** `const DescriptorSetLayoutBinding*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12DescriptorSet object; - // 根据上下文补齐参数后调用 D3D12DescriptorSet::GetBindings(...)。 - (void)object; -} -``` +- 会更新 `m_bindings`。 +- 当前实现会调用 `empty`、`data`。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](D3D12DescriptorSet.md) -- [返回模块目录](../D3D12.md) +- [D3D12DescriptorSet](D3D12DescriptorSet.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/GetConstantBufferData.md b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/GetConstantBufferData.md index 4d4270eb..3df8f148 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/GetConstantBufferData.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/GetConstantBufferData.md @@ -1,30 +1,27 @@ # D3D12DescriptorSet::GetConstantBufferData -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12DescriptorSet.h` + +## 签名 ```cpp void* GetConstantBufferData() override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12DescriptorSet.h`，当前页面用于固定 `D3D12DescriptorSet` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `FindFirstBindingRecordOfType`、`empty`、`data` 协同流程。 -**返回：** `void*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12DescriptorSet object; - // 根据上下文补齐参数后调用 D3D12DescriptorSet::GetConstantBufferData(...)。 - (void)object; -} -``` +- 当前实现会调用 `FindFirstBindingRecordOfType`、`empty`、`data`。 +- 包含条件分支，并可能提前返回。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](D3D12DescriptorSet.md) -- [返回模块目录](../D3D12.md) +- [D3D12DescriptorSet](D3D12DescriptorSet.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/GetConstantBufferGPUAddress.md b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/GetConstantBufferGPUAddress.md index 2e02bc18..1ed74657 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/GetConstantBufferGPUAddress.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/GetConstantBufferGPUAddress.md @@ -1,31 +1,27 @@ # D3D12DescriptorSet::GetConstantBufferGPUAddress -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12DescriptorSet.h` + +## 签名 ```cpp D3D12_GPU_VIRTUAL_ADDRESS GetConstantBufferGPUAddress(uint32_t binding) const; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12DescriptorSet.h`，当前页面用于固定 `D3D12DescriptorSet` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `binding` - 参数语义详见头文件声明。 +执行 `FindBindingRecord`、`GetGPUVirtualAddress` 协同流程。 -**返回：** `D3D12_GPU_VIRTUAL_ADDRESS` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12DescriptorSet object; - // 根据上下文补齐参数后调用 D3D12DescriptorSet::GetConstantBufferGPUAddress(...)。 - (void)object; -} -``` +- 当前实现会调用 `FindBindingRecord`、`GetGPUVirtualAddress`。 +- 包含条件分支，并可能提前返回。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](D3D12DescriptorSet.md) -- [返回模块目录](../D3D12.md) +- [D3D12DescriptorSet](D3D12DescriptorSet.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/GetConstantBufferSize.md b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/GetConstantBufferSize.md index d9f953a2..77b5dbff 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/GetConstantBufferSize.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/GetConstantBufferSize.md @@ -1,30 +1,26 @@ # D3D12DescriptorSet::GetConstantBufferSize -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12DescriptorSet.h` + +## 签名 ```cpp size_t GetConstantBufferSize() const override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12DescriptorSet.h`，当前页面用于固定 `D3D12DescriptorSet` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `bindingRecord != nullptr ? bindingRecord->constantBufferData.size() : 0`。 -**返回：** `size_t` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12DescriptorSet object; - // 根据上下文补齐参数后调用 D3D12DescriptorSet::GetConstantBufferSize(...)。 - (void)object; -} -``` +- 当前实现会调用 `FindFirstBindingRecordOfType`、`size`。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](D3D12DescriptorSet.md) -- [返回模块目录](../D3D12.md) +- [D3D12DescriptorSet](D3D12DescriptorSet.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/GetCount.md b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/GetCount.md index 04315e56..45f36639 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/GetCount.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/GetCount.md @@ -1,30 +1,25 @@ # D3D12DescriptorSet::GetCount -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12DescriptorSet.h` + +## 签名 ```cpp uint32_t GetCount() const; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12DescriptorSet.h`，当前页面用于固定 `D3D12DescriptorSet` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_count` 当前值。 -**返回：** `uint32_t` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12DescriptorSet object; - // 根据上下文补齐参数后调用 D3D12DescriptorSet::GetCount(...)。 - (void)object; -} -``` +- 返回 `m_count` 当前值。 ## 相关文档 -- [返回类总览](D3D12DescriptorSet.md) -- [返回模块目录](../D3D12.md) +- [D3D12DescriptorSet](D3D12DescriptorSet.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/GetDescriptorIndexForBinding.md b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/GetDescriptorIndexForBinding.md index c5dc54e4..3a4be9e1 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/GetDescriptorIndexForBinding.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/GetDescriptorIndexForBinding.md @@ -1,31 +1,28 @@ # D3D12DescriptorSet::GetDescriptorIndexForBinding -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12DescriptorSet.h` + +## 签名 ```cpp uint32_t GetDescriptorIndexForBinding(uint32_t binding) const; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12DescriptorSet.h`，当前页面用于固定 `D3D12DescriptorSet` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `binding` - 参数语义详见头文件声明。 +更新 `m_heap`。 -**返回：** `uint32_t` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12DescriptorSet object; - // 根据上下文补齐参数后调用 D3D12DescriptorSet::GetDescriptorIndexForBinding(...)。 - (void)object; -} -``` +- 会更新 `m_heap`。 +- 当前实现会调用 `FindBindingRecord`、`UsesDescriptorHeap`、`GetType`。 +- 包含条件分支，并可能提前返回。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](D3D12DescriptorSet.md) -- [返回模块目录](../D3D12.md) +- [D3D12DescriptorSet](D3D12DescriptorSet.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/GetFirstBindingOfType.md b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/GetFirstBindingOfType.md index e1573be8..e9954ab7 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/GetFirstBindingOfType.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/GetFirstBindingOfType.md @@ -1,31 +1,25 @@ # D3D12DescriptorSet::GetFirstBindingOfType -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12DescriptorSet.h` + +## 签名 ```cpp uint32_t GetFirstBindingOfType(DescriptorType type) const; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12DescriptorSet.h`，当前页面用于固定 `D3D12DescriptorSet` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `type` - 参数语义详见头文件声明。 +执行该公开方法对应的当前实现。 -**返回：** `uint32_t` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12DescriptorSet object; - // 根据上下文补齐参数后调用 D3D12DescriptorSet::GetFirstBindingOfType(...)。 - (void)object; -} -``` +- 包含条件分支，并可能提前返回。 ## 相关文档 -- [返回类总览](D3D12DescriptorSet.md) -- [返回模块目录](../D3D12.md) +- [D3D12DescriptorSet](D3D12DescriptorSet.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/GetGPUHandle.md b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/GetGPUHandle.md index f682d462..b5618259 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/GetGPUHandle.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/GetGPUHandle.md @@ -1,31 +1,28 @@ # D3D12DescriptorSet::GetGPUHandle -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12DescriptorSet.h` + +## 签名 ```cpp D3D12_GPU_DESCRIPTOR_HANDLE GetGPUHandle(uint32_t index = 0) const; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12DescriptorSet.h`，当前页面用于固定 `D3D12DescriptorSet` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `index` - 参数语义详见头文件声明。 +更新 `m_heap`。 -**返回：** `D3D12_GPU_DESCRIPTOR_HANDLE` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12DescriptorSet object; - // 根据上下文补齐参数后调用 D3D12DescriptorSet::GetGPUHandle(...)。 - (void)object; -} -``` +- 会更新 `m_heap`。 +- 当前实现会调用 `GetGPUDescriptorHandle`。 +- 包含条件分支，并可能提前返回。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](D3D12DescriptorSet.md) -- [返回模块目录](../D3D12.md) +- [D3D12DescriptorSet](D3D12DescriptorSet.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/GetGPUHandleForBinding.md b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/GetGPUHandleForBinding.md index be70eaef..2d61e31a 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/GetGPUHandleForBinding.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/GetGPUHandleForBinding.md @@ -1,31 +1,26 @@ # D3D12DescriptorSet::GetGPUHandleForBinding -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12DescriptorSet.h` + +## 签名 ```cpp D3D12_GPU_DESCRIPTOR_HANDLE GetGPUHandleForBinding(uint32_t binding) const; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12DescriptorSet.h`，当前页面用于固定 `D3D12DescriptorSet` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `binding` - 参数语义详见头文件声明。 +执行 `GetDescriptorIndexForBinding`、`GetGPUHandle` 协同流程。 -**返回：** `D3D12_GPU_DESCRIPTOR_HANDLE` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12DescriptorSet object; - // 根据上下文补齐参数后调用 D3D12DescriptorSet::GetGPUHandleForBinding(...)。 - (void)object; -} -``` +- 当前实现会调用 `GetDescriptorIndexForBinding`、`GetGPUHandle`。 +- 包含条件分支，并可能提前返回。 ## 相关文档 -- [返回类总览](D3D12DescriptorSet.md) -- [返回模块目录](../D3D12.md) +- [D3D12DescriptorSet](D3D12DescriptorSet.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/GetHeap.md b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/GetHeap.md index cafe9386..5b97fb27 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/GetHeap.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/GetHeap.md @@ -1,30 +1,25 @@ # D3D12DescriptorSet::GetHeap -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12DescriptorSet.h` + +## 签名 ```cpp D3D12DescriptorHeap* GetHeap() const; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12DescriptorSet.h`，当前页面用于固定 `D3D12DescriptorSet` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_heap` 当前值。 -**返回：** `D3D12DescriptorHeap*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12DescriptorSet object; - // 根据上下文补齐参数后调用 D3D12DescriptorSet::GetHeap(...)。 - (void)object; -} -``` +- 返回 `m_heap` 当前值。 ## 相关文档 -- [返回类总览](D3D12DescriptorSet.md) -- [返回模块目录](../D3D12.md) +- [D3D12DescriptorSet](D3D12DescriptorSet.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/GetOffset.md b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/GetOffset.md index 0a790888..2cbf1514 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/GetOffset.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/GetOffset.md @@ -1,30 +1,25 @@ # D3D12DescriptorSet::GetOffset -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12DescriptorSet.h` + +## 签名 ```cpp uint32_t GetOffset() const; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12DescriptorSet.h`，当前页面用于固定 `D3D12DescriptorSet` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_offset` 当前值。 -**返回：** `uint32_t` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12DescriptorSet object; - // 根据上下文补齐参数后调用 D3D12DescriptorSet::GetOffset(...)。 - (void)object; -} -``` +- 返回 `m_offset` 当前值。 ## 相关文档 -- [返回类总览](D3D12DescriptorSet.md) -- [返回模块目录](../D3D12.md) +- [D3D12DescriptorSet](D3D12DescriptorSet.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/HasBindingType.md b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/HasBindingType.md index d11d5d62..26003136 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/HasBindingType.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/HasBindingType.md @@ -1,31 +1,25 @@ # D3D12DescriptorSet::HasBindingType -判断是否具备指定状态或能力。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12DescriptorSet.h` + +## 签名 ```cpp bool HasBindingType(DescriptorType type) const; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12DescriptorSet.h`，当前页面用于固定 `D3D12DescriptorSet` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `type` - 参数语义详见头文件声明。 +执行该公开方法对应的当前实现。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12DescriptorSet object; - // 根据上下文补齐参数后调用 D3D12DescriptorSet::HasBindingType(...)。 - (void)object; -} -``` +- 包含条件分支，并可能提前返回。 ## 相关文档 -- [返回类总览](D3D12DescriptorSet.md) -- [返回模块目录](../D3D12.md) +- [D3D12DescriptorSet](D3D12DescriptorSet.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/IsConstantDirty.md b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/IsConstantDirty.md index 321f44e5..7e38040d 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/IsConstantDirty.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/IsConstantDirty.md @@ -1,30 +1,25 @@ # D3D12DescriptorSet::IsConstantDirty -查询当前状态。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12DescriptorSet.h` + +## 签名 ```cpp bool IsConstantDirty() const override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12DescriptorSet.h`，当前页面用于固定 `D3D12DescriptorSet` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行该公开方法对应的当前实现。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12DescriptorSet object; - // 根据上下文补齐参数后调用 D3D12DescriptorSet::IsConstantDirty(...)。 - (void)object; -} -``` +- 包含条件分支，并可能提前返回。 ## 相关文档 -- [返回类总览](D3D12DescriptorSet.md) -- [返回模块目录](../D3D12.md) +- [D3D12DescriptorSet](D3D12DescriptorSet.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/MarkConstantClean.md b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/MarkConstantClean.md index 9f603d8f..a4b7025f 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/MarkConstantClean.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/MarkConstantClean.md @@ -1,30 +1,25 @@ # D3D12DescriptorSet::MarkConstantClean -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12DescriptorSet.h` + +## 签名 ```cpp void MarkConstantClean() override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12DescriptorSet.h`，当前页面用于固定 `D3D12DescriptorSet` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行该公开方法对应的当前实现。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12DescriptorSet object; - // 根据上下文补齐参数后调用 D3D12DescriptorSet::MarkConstantClean(...)。 - (void)object; -} -``` +- 执行该公开方法对应的当前实现。 ## 相关文档 -- [返回类总览](D3D12DescriptorSet.md) -- [返回模块目录](../D3D12.md) +- [D3D12DescriptorSet](D3D12DescriptorSet.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/Shutdown.md b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/Shutdown.md index c1251f9a..459cca6a 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/Shutdown.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12DescriptorSet/Shutdown.md @@ -1,30 +1,27 @@ # D3D12DescriptorSet::Shutdown -关闭并清理内部状态。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12DescriptorSet.h` + +## 签名 ```cpp void Shutdown() override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12DescriptorSet.h`，当前页面用于固定 `D3D12DescriptorSet` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `clear` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12DescriptorSet object; - // 根据上下文补齐参数后调用 D3D12DescriptorSet::Shutdown(...)。 - (void)object; -} -``` +- 会更新 `m_heap`、`m_offset`、`m_count`、`m_bindingCount`。 +- 当前实现会调用 `clear`。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](D3D12DescriptorSet.md) -- [返回模块目录](../D3D12.md) +- [D3D12DescriptorSet](D3D12DescriptorSet.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Device/CheckFeatureSupport.md b/docs/api/XCEngine/RHI/D3D12/D3D12Device/CheckFeatureSupport.md index 1f40ac9d..f0a313b7 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12Device/CheckFeatureSupport.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12Device/CheckFeatureSupport.md @@ -1,33 +1,25 @@ # D3D12Device::CheckFeatureSupport -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12Device.h` + +## 签名 ```cpp bool CheckFeatureSupport(D3D12_FEATURE feature, void* featureSupportData, uint32_t featureSupportDataSize); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12Device.h`，当前页面用于固定 `D3D12Device` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `feature` - 参数语义详见头文件声明。 -- `featureSupportData` - 参数语义详见头文件声明。 -- `featureSupportDataSize` - 参数语义详见头文件声明。 +返回 `SUCCEEDED(m_device->CheckFeatureSupport(feature, featureSupportData, featureSupportDataSize))`。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12Device object; - // 根据上下文补齐参数后调用 D3D12Device::CheckFeatureSupport(...)。 - (void)object; -} -``` +- 当前实现会调用 `SUCCEEDED`、`CheckFeatureSupport`。 ## 相关文档 -- [返回类总览](D3D12Device.md) -- [返回模块目录](../D3D12.md) +- [D3D12Device](D3D12Device.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Device/Constructor.md b/docs/api/XCEngine/RHI/D3D12/D3D12Device/Constructor.md index a59ce09b..bbbb315c 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12Device/Constructor.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12Device/Constructor.md @@ -1,28 +1,25 @@ # D3D12Device::D3D12Device() -构造对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12Device.h` + +## 签名 ```cpp D3D12Device(); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12Device.h`，当前页面用于固定 `D3D12Device` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +构造 `D3D12Device` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12Device object; -} -``` +- 具体定义位于 `engine/src/RHI/D3D12/D3D12Device.cpp`。 ## 相关文档 -- [返回类总览](D3D12Device.md) -- [返回模块目录](../D3D12.md) +- [D3D12Device](D3D12Device.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateBuffer.md b/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateBuffer.md index 8e37b94e..a619c03a 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateBuffer.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateBuffer.md @@ -1,31 +1,28 @@ # D3D12Device::CreateBuffer -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12Device.h` + +## 签名 ```cpp RHIBuffer* CreateBuffer(const BufferDesc& desc) override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12Device.h`，当前页面用于固定 `D3D12Device` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `desc` - 参数语义详见头文件声明。 +更新 `m_device`。 -**返回：** `RHIBuffer*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12Device object; - // 根据上下文补齐参数后调用 D3D12Device::CreateBuffer(...)。 - (void)object; -} -``` +- 会更新 `m_device`。 +- 当前实现会调用 `D3D12Buffer`、`Initialize`、`SetStride`、`SetBufferType`。 +- 包含条件分支，并可能提前返回。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](D3D12Device.md) -- [返回模块目录](../D3D12.md) +- [D3D12Device](D3D12Device.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateCommandAllocator.md b/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateCommandAllocator.md index 7024727e..4ee08214 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateCommandAllocator.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateCommandAllocator.md @@ -1,31 +1,25 @@ # D3D12Device::CreateCommandAllocator -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12Device.h` + +## 签名 ```cpp D3D12CommandAllocator* CreateCommandAllocator(const CommandAllocatorDesc& desc); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12Device.h`，当前页面用于固定 `D3D12Device` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `desc` - 参数语义详见头文件声明。 +执行 `CreateCommandAllocator` 创建流程。 -**返回：** `D3D12CommandAllocator*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12Device object; - // 根据上下文补齐参数后调用 D3D12Device::CreateCommandAllocator(...)。 - (void)object; -} -``` +- 具体定义位于 `engine/src/RHI/D3D12/D3D12Device.cpp`。 ## 相关文档 -- [返回类总览](D3D12Device.md) -- [返回模块目录](../D3D12.md) +- [D3D12Device](D3D12Device.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateCommandListImpl.md b/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateCommandListImpl.md index e0654f80..29028d6a 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateCommandListImpl.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateCommandListImpl.md @@ -1,31 +1,25 @@ # D3D12Device::CreateCommandListImpl -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12Device.h` + +## 签名 ```cpp D3D12CommandList* CreateCommandListImpl(const CommandListDesc& desc); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12Device.h`，当前页面用于固定 `D3D12Device` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `desc` - 参数语义详见头文件声明。 +固定返回 `nullptr`。 -**返回：** `D3D12CommandList*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12Device object; - // 根据上下文补齐参数后调用 D3D12Device::CreateCommandListImpl(...)。 - (void)object; -} -``` +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](D3D12Device.md) -- [返回模块目录](../D3D12.md) +- [D3D12Device](D3D12Device.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateCommandQueueImpl.md b/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateCommandQueueImpl.md index 24087e14..d6966e4f 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateCommandQueueImpl.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateCommandQueueImpl.md @@ -1,31 +1,25 @@ # D3D12Device::CreateCommandQueueImpl -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12Device.h` + +## 签名 ```cpp D3D12CommandQueue* CreateCommandQueueImpl(const CommandQueueDesc& desc); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12Device.h`，当前页面用于固定 `D3D12Device` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `desc` - 参数语义详见头文件声明。 +固定返回 `nullptr`。 -**返回：** `D3D12CommandQueue*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12Device object; - // 根据上下文补齐参数后调用 D3D12Device::CreateCommandQueueImpl(...)。 - (void)object; -} -``` +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](D3D12Device.md) -- [返回模块目录](../D3D12.md) +- [D3D12Device](D3D12Device.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateDepthStencilView.md b/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateDepthStencilView.md index 137a08cb..96d0804c 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateDepthStencilView.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateDepthStencilView.md @@ -1,32 +1,28 @@ # D3D12Device::CreateDepthStencilView -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12Device.h` + +## 签名 ```cpp RHIResourceView* CreateDepthStencilView(RHITexture* texture, const ResourceViewDesc& desc) override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12Device.h`，当前页面用于固定 `D3D12Device` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `texture` - 参数语义详见头文件声明。 -- `desc` - 参数语义详见头文件声明。 +更新 `m_device`。 -**返回：** `RHIResourceView*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12Device object; - // 根据上下文补齐参数后调用 D3D12Device::CreateDepthStencilView(...)。 - (void)object; -} -``` +- 会更新 `m_device`。 +- 当前实现会调用 `D3D12ResourceView`、`GetResource`、`ToD3D12`、`Initialize`、`InitializeAsDepthStencil`。 +- 包含条件分支，并可能提前返回。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](D3D12Device.md) -- [返回模块目录](../D3D12.md) +- [D3D12Device](D3D12Device.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateDescriptorHeap.md b/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateDescriptorHeap.md index 6a04f479..8049d364 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateDescriptorHeap.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateDescriptorHeap.md @@ -1,31 +1,28 @@ # D3D12Device::CreateDescriptorHeap -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12Device.h` + +## 签名 ```cpp D3D12DescriptorHeap* CreateDescriptorHeap(const DescriptorHeapDesc& desc); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12Device.h`，当前页面用于固定 `D3D12Device` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `desc` - 参数语义详见头文件声明。 +更新 `m_device`。 -**返回：** `D3D12DescriptorHeap*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12Device object; - // 根据上下文补齐参数后调用 D3D12Device::CreateDescriptorHeap(...)。 - (void)object; -} -``` +- 会更新 `m_device`。 +- 当前实现会调用 `D3D12DescriptorHeap`、`Initialize`。 +- 包含条件分支，并可能提前返回。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](D3D12Device.md) -- [返回模块目录](../D3D12.md) +- [D3D12Device](D3D12Device.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateDescriptorPool.md b/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateDescriptorPool.md index ba4db0af..e72fbfef 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateDescriptorPool.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateDescriptorPool.md @@ -1,31 +1,28 @@ # D3D12Device::CreateDescriptorPool -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12Device.h` + +## 签名 ```cpp RHIDescriptorPool* CreateDescriptorPool(const DescriptorPoolDesc& desc) override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12Device.h`，当前页面用于固定 `D3D12Device` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `desc` - 参数语义详见头文件声明。 +更新 `m_device`。 -**返回：** `RHIDescriptorPool*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12Device object; - // 根据上下文补齐参数后调用 D3D12Device::CreateDescriptorPool(...)。 - (void)object; -} -``` +- 会更新 `m_device`。 +- 当前实现会调用 `D3D12DescriptorHeap`、`Initialize`。 +- 包含条件分支，并可能提前返回。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](D3D12Device.md) -- [返回模块目录](../D3D12.md) +- [D3D12Device](D3D12Device.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateDescriptorSet.md b/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateDescriptorSet.md index 6b2f38df..01ee1caf 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateDescriptorSet.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateDescriptorSet.md @@ -1,32 +1,27 @@ # D3D12Device::CreateDescriptorSet -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12Device.h` + +## 签名 ```cpp RHIDescriptorSet* CreateDescriptorSet(RHIDescriptorPool* pool, const DescriptorSetLayoutDesc& layout) override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12Device.h`，当前页面用于固定 `D3D12Device` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `pool` - 参数语义详见头文件声明。 -- `layout` - 参数语义详见头文件声明。 +执行 `AllocateSet` 协同流程。 -**返回：** `RHIDescriptorSet*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12Device object; - // 根据上下文补齐参数后调用 D3D12Device::CreateDescriptorSet(...)。 - (void)object; -} -``` +- 当前实现会调用 `AllocateSet`。 +- 包含条件分支，并可能提前返回。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](D3D12Device.md) -- [返回模块目录](../D3D12.md) +- [D3D12Device](D3D12Device.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateFence.md b/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateFence.md index fbbb2b6a..80641a20 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateFence.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateFence.md @@ -1,31 +1,28 @@ # D3D12Device::CreateFence -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12Device.h` + +## 签名 ```cpp RHIFence* CreateFence(const FenceDesc& desc) override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12Device.h`，当前页面用于固定 `D3D12Device` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `desc` - 参数语义详见头文件声明。 +更新 `m_device`。 -**返回：** `RHIFence*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12Device object; - // 根据上下文补齐参数后调用 D3D12Device::CreateFence(...)。 - (void)object; -} -``` +- 会更新 `m_device`。 +- 当前实现会调用 `D3D12Fence`、`Initialize`。 +- 包含条件分支，并可能提前返回。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](D3D12Device.md) -- [返回模块目录](../D3D12.md) +- [D3D12Device](D3D12Device.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateFramebuffer.md b/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateFramebuffer.md index fc460616..a6aadbe9 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateFramebuffer.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateFramebuffer.md @@ -1,36 +1,27 @@ # D3D12Device::CreateFramebuffer -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12Device.h` + +## 签名 ```cpp RHIFramebuffer* CreateFramebuffer( class RHIRenderPass* renderPass, uint32_t width, uint32_t height, uint32_t colorAttachmentCount, RHIResourceView** colorAttachments, RHIResourceView* depthStencilAttachment) override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12Device.h`，当前页面用于固定 `D3D12Device` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `renderPass` - 参数语义详见头文件声明。 -- `width` - 参数语义详见头文件声明。 -- `height` - 参数语义详见头文件声明。 -- `colorAttachmentCount` - 参数语义详见头文件声明。 -- `colorAttachments` - 参数语义详见头文件声明。 -- `depthStencilAttachment` - 参数语义详见头文件声明。 +执行 `D3D12Framebuffer`、`Initialize` 协同流程。 -**返回：** `RHIFramebuffer*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12Device object; - // 根据上下文补齐参数后调用 D3D12Device::CreateFramebuffer(...)。 - (void)object; -} -``` +- 当前实现会调用 `D3D12Framebuffer`、`Initialize`。 +- 包含条件分支，并可能提前返回。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](D3D12Device.md) -- [返回模块目录](../D3D12.md) +- [D3D12Device](D3D12Device.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateIndexBufferView.md b/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateIndexBufferView.md index a02f8e68..497d8aeb 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateIndexBufferView.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateIndexBufferView.md @@ -1,32 +1,27 @@ # D3D12Device::CreateIndexBufferView -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12Device.h` + +## 签名 ```cpp RHIResourceView* CreateIndexBufferView(RHIBuffer* buffer, const ResourceViewDesc& desc) override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12Device.h`，当前页面用于固定 `D3D12Device` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `buffer` - 参数语义详见头文件声明。 -- `desc` - 参数语义详见头文件声明。 +执行 `D3D12ResourceView`、`InitializeAsIndexBuffer`、`IsValid` 协同流程。 -**返回：** `RHIResourceView*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12Device object; - // 根据上下文补齐参数后调用 D3D12Device::CreateIndexBufferView(...)。 - (void)object; -} -``` +- 当前实现会调用 `D3D12ResourceView`、`InitializeAsIndexBuffer`、`IsValid`。 +- 包含条件分支，并可能提前返回。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](D3D12Device.md) -- [返回模块目录](../D3D12.md) +- [D3D12Device](D3D12Device.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreatePipelineLayout.md b/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreatePipelineLayout.md index 04ad989c..55c19332 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreatePipelineLayout.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreatePipelineLayout.md @@ -1,31 +1,27 @@ # D3D12Device::CreatePipelineLayout -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12Device.h` + +## 签名 ```cpp RHIPipelineLayout* CreatePipelineLayout(const RHIPipelineLayoutDesc& desc) override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12Device.h`，当前页面用于固定 `D3D12Device` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `desc` - 参数语义详见头文件声明。 +执行 `D3D12PipelineLayout`、`InitializeWithDevice` 协同流程。 -**返回：** `RHIPipelineLayout*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12Device object; - // 根据上下文补齐参数后调用 D3D12Device::CreatePipelineLayout(...)。 - (void)object; -} -``` +- 当前实现会调用 `D3D12PipelineLayout`、`InitializeWithDevice`。 +- 包含条件分支，并可能提前返回。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](D3D12Device.md) -- [返回模块目录](../D3D12.md) +- [D3D12Device](D3D12Device.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreatePipelineState.md b/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreatePipelineState.md index 84391ef8..d2bcb348 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreatePipelineState.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreatePipelineState.md @@ -1,31 +1,28 @@ # D3D12Device::CreatePipelineState -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12Device.h` + +## 签名 ```cpp RHIPipelineState* CreatePipelineState(const GraphicsPipelineDesc& desc) override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12Device.h`，当前页面用于固定 `D3D12Device` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `desc` - 参数语义详见头文件声明。 +更新 `m_device`。 -**返回：** `RHIPipelineState*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12Device object; - // 根据上下文补齐参数后调用 D3D12Device::CreatePipelineState(...)。 - (void)object; -} -``` +- 会更新 `m_device`。 +- 当前实现会调用 `D3D12PipelineState`、`SetInputLayout`、`SetRasterizerState`、`SetBlendState`、`SetDepthStencilState`。 +- 包含条件分支，并可能提前返回。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](D3D12Device.md) -- [返回模块目录](../D3D12.md) +- [D3D12Device](D3D12Device.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateQueryHeap.md b/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateQueryHeap.md index 00594177..fa728fc0 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateQueryHeap.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateQueryHeap.md @@ -1,31 +1,28 @@ # D3D12Device::CreateQueryHeap -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12Device.h` + +## 签名 ```cpp D3D12QueryHeap* CreateQueryHeap(const QueryHeapDesc& desc); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12Device.h`，当前页面用于固定 `D3D12Device` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `desc` - 参数语义详见头文件声明。 +更新 `m_device`。 -**返回：** `D3D12QueryHeap*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12Device object; - // 根据上下文补齐参数后调用 D3D12Device::CreateQueryHeap(...)。 - (void)object; -} -``` +- 会更新 `m_device`。 +- 当前实现会调用 `D3D12QueryHeap`、`Initialize`。 +- 包含条件分支，并可能提前返回。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](D3D12Device.md) -- [返回模块目录](../D3D12.md) +- [D3D12Device](D3D12Device.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateRenderPass.md b/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateRenderPass.md index 18c047e7..46cbe672 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateRenderPass.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateRenderPass.md @@ -1,33 +1,27 @@ # D3D12Device::CreateRenderPass -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12Device.h` + +## 签名 ```cpp RHIRenderPass* CreateRenderPass( uint32_t colorAttachmentCount, const AttachmentDesc* colorAttachments, const AttachmentDesc* depthStencilAttachment) override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12Device.h`，当前页面用于固定 `D3D12Device` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `colorAttachmentCount` - 参数语义详见头文件声明。 -- `colorAttachments` - 参数语义详见头文件声明。 -- `depthStencilAttachment` - 参数语义详见头文件声明。 +执行 `D3D12RenderPass`、`Initialize` 协同流程。 -**返回：** `RHIRenderPass*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12Device object; - // 根据上下文补齐参数后调用 D3D12Device::CreateRenderPass(...)。 - (void)object; -} -``` +- 当前实现会调用 `D3D12RenderPass`、`Initialize`。 +- 包含条件分支，并可能提前返回。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](D3D12Device.md) -- [返回模块目录](../D3D12.md) +- [D3D12Device](D3D12Device.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateRenderTargetView.md b/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateRenderTargetView.md index 3aec5a83..638bbb23 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateRenderTargetView.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateRenderTargetView.md @@ -1,32 +1,28 @@ # D3D12Device::CreateRenderTargetView -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12Device.h` + +## 签名 ```cpp RHIResourceView* CreateRenderTargetView(RHITexture* texture, const ResourceViewDesc& desc) override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12Device.h`，当前页面用于固定 `D3D12Device` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `texture` - 参数语义详见头文件声明。 -- `desc` - 参数语义详见头文件声明。 +更新 `m_device`。 -**返回：** `RHIResourceView*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12Device object; - // 根据上下文补齐参数后调用 D3D12Device::CreateRenderTargetView(...)。 - (void)object; -} -``` +- 会更新 `m_device`。 +- 当前实现会调用 `D3D12ResourceView`、`GetResource`、`GetFormat`、`GetTextureType`、`ToD3D12`。 +- 包含条件分支，并可能提前返回。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](D3D12Device.md) -- [返回模块目录](../D3D12.md) +- [D3D12Device](D3D12Device.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateRootSignature.md b/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateRootSignature.md index 7797c53e..0d3c9b29 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateRootSignature.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateRootSignature.md @@ -1,31 +1,28 @@ # D3D12Device::CreateRootSignature -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12Device.h` + +## 签名 ```cpp D3D12RootSignature* CreateRootSignature(const RootSignatureDesc& desc); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12Device.h`，当前页面用于固定 `D3D12Device` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `desc` - 参数语义详见头文件声明。 +更新 `m_device`。 -**返回：** `D3D12RootSignature*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12Device object; - // 根据上下文补齐参数后调用 D3D12Device::CreateRootSignature(...)。 - (void)object; -} -``` +- 会更新 `m_device`。 +- 当前实现会调用 `D3D12RootSignature`、`Initialize`。 +- 包含条件分支，并可能提前返回。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](D3D12Device.md) -- [返回模块目录](../D3D12.md) +- [D3D12Device](D3D12Device.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateSampler.md b/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateSampler.md index 6e82db85..246b4300 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateSampler.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateSampler.md @@ -1,31 +1,28 @@ # D3D12Device::CreateSampler -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12Device.h` + +## 签名 ```cpp RHISampler* CreateSampler(const SamplerDesc& desc) override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12Device.h`，当前页面用于固定 `D3D12Device` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `desc` - 参数语义详见头文件声明。 +更新 `m_device`。 -**返回：** `RHISampler*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12Device object; - // 根据上下文补齐参数后调用 D3D12Device::CreateSampler(...)。 - (void)object; -} -``` +- 会更新 `m_device`。 +- 当前实现会调用 `D3D12Sampler`、`ToD3D12`。 +- 包含条件分支，并可能提前返回。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](D3D12Device.md) -- [返回模块目录](../D3D12.md) +- [D3D12Device](D3D12Device.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateShader.md b/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateShader.md index e1c3c795..4c4c3d4b 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateShader.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateShader.md @@ -1,31 +1,27 @@ # D3D12Device::CreateShader -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12Device.h` + +## 签名 ```cpp RHIShader* CreateShader(const ShaderCompileDesc& desc) override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12Device.h`，当前页面用于固定 `D3D12Device` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `desc` - 参数语义详见头文件声明。 +执行 `D3D12Shader`、`NarrowAscii` 协同流程。 -**返回：** `RHIShader*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12Device object; - // 根据上下文补齐参数后调用 D3D12Device::CreateShader(...)。 - (void)object; -} -``` +- 当前实现会调用 `D3D12Shader`、`NarrowAscii`、`empty`、`c_str`。 +- 包含条件分支，并可能提前返回。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](D3D12Device.md) -- [返回模块目录](../D3D12.md) +- [D3D12Device](D3D12Device.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateShaderResourceView.md b/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateShaderResourceView.md index d5aea442..f8d900c0 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateShaderResourceView.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateShaderResourceView.md @@ -1,32 +1,28 @@ # D3D12Device::CreateShaderResourceView -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12Device.h` + +## 签名 ```cpp RHIResourceView* CreateShaderResourceView(RHITexture* texture, const ResourceViewDesc& desc) override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12Device.h`，当前页面用于固定 `D3D12Device` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `texture` - 参数语义详见头文件声明。 -- `desc` - 参数语义详见头文件声明。 +更新 `m_device`。 -**返回：** `RHIResourceView*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12Device object; - // 根据上下文补齐参数后调用 D3D12Device::CreateShaderResourceView(...)。 - (void)object; -} -``` +- 会更新 `m_device`。 +- 当前实现会调用 `D3D12ResourceView`、`GetResource`、`ToD3D12`、`Initialize`、`InitializeAsShaderResource`。 +- 包含条件分支，并可能提前返回。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](D3D12Device.md) -- [返回模块目录](../D3D12.md) +- [D3D12Device](D3D12Device.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateSwapChain.md b/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateSwapChain.md index 33716a0c..c0b9c2d0 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateSwapChain.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateSwapChain.md @@ -1,32 +1,28 @@ # D3D12Device::CreateSwapChain -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12Device.h` + +## 签名 ```cpp RHISwapChain* CreateSwapChain(const SwapChainDesc& desc, RHICommandQueue* presentQueue) override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12Device.h`，当前页面用于固定 `D3D12Device` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `desc` - 参数语义详见头文件声明。 -- `presentQueue` - 参数语义详见头文件声明。 +更新 `m_factory`。 -**返回：** `RHISwapChain*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12Device object; - // 根据上下文补齐参数后调用 D3D12Device::CreateSwapChain(...)。 - (void)object; -} -``` +- 会更新 `m_factory`。 +- 当前实现会调用 `GetNativeHandle`、`D3D12SwapChain`、`Initialize`。 +- 包含条件分支，并可能提前返回。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](D3D12Device.md) -- [返回模块目录](../D3D12.md) +- [D3D12Device](D3D12Device.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateUnorderedAccessView.md b/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateUnorderedAccessView.md index e3cc00b3..550b83e2 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateUnorderedAccessView.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateUnorderedAccessView.md @@ -1,32 +1,28 @@ # D3D12Device::CreateUnorderedAccessView -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12Device.h` + +## 签名 ```cpp RHIResourceView* CreateUnorderedAccessView(RHITexture* texture, const ResourceViewDesc& desc) override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12Device.h`，当前页面用于固定 `D3D12Device` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `texture` - 参数语义详见头文件声明。 -- `desc` - 参数语义详见头文件声明。 +更新 `m_device`。 -**返回：** `RHIResourceView*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12Device object; - // 根据上下文补齐参数后调用 D3D12Device::CreateUnorderedAccessView(...)。 - (void)object; -} -``` +- 会更新 `m_device`。 +- 当前实现会调用 `D3D12ResourceView`、`GetResource`、`Initialize`、`InitializeAsUnorderedAccess`、`get`。 +- 包含条件分支，并可能提前返回。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](D3D12Device.md) -- [返回模块目录](../D3D12.md) +- [D3D12Device](D3D12Device.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateVertexBufferView.md b/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateVertexBufferView.md index 18058418..c317f1ef 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateVertexBufferView.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12Device/CreateVertexBufferView.md @@ -1,32 +1,27 @@ # D3D12Device::CreateVertexBufferView -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12Device.h` + +## 签名 ```cpp RHIResourceView* CreateVertexBufferView(RHIBuffer* buffer, const ResourceViewDesc& desc) override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12Device.h`，当前页面用于固定 `D3D12Device` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `buffer` - 参数语义详见头文件声明。 -- `desc` - 参数语义详见头文件声明。 +执行 `D3D12ResourceView`、`InitializeAsVertexBuffer`、`IsValid` 协同流程。 -**返回：** `RHIResourceView*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12Device object; - // 根据上下文补齐参数后调用 D3D12Device::CreateVertexBufferView(...)。 - (void)object; -} -``` +- 当前实现会调用 `D3D12ResourceView`、`InitializeAsVertexBuffer`、`IsValid`。 +- 包含条件分支，并可能提前返回。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](D3D12Device.md) -- [返回模块目录](../D3D12.md) +- [D3D12Device](D3D12Device.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Device/Destructor.md b/docs/api/XCEngine/RHI/D3D12/D3D12Device/Destructor.md index 4beee559..5ab58273 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12Device/Destructor.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12Device/Destructor.md @@ -1,29 +1,25 @@ # D3D12Device::~D3D12Device() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12Device.h` + +## 签名 ```cpp ~D3D12Device() override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12Device.h`，当前页面用于固定 `D3D12Device` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `Shutdown(...)` 相关流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12Device object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 当前实现会调用 `Shutdown`。 ## 相关文档 -- [返回类总览](D3D12Device.md) -- [返回模块目录](../D3D12.md) +- [D3D12Device](D3D12Device.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Device/EnumerateAdapters.md b/docs/api/XCEngine/RHI/D3D12/D3D12Device/EnumerateAdapters.md index 945ac45e..15c9ba0b 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12Device/EnumerateAdapters.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12Device/EnumerateAdapters.md @@ -1,30 +1,26 @@ # D3D12Device::EnumerateAdapters -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12Device.h` + +## 签名 ```cpp std::vector EnumerateAdapters(); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12Device.h`，当前页面用于固定 `D3D12Device` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `EnumAdapters1`、`GetDesc1`、`push_back` 协同流程。 -**返回：** `std::vector` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12Device object; - // 根据上下文补齐参数后调用 D3D12Device::EnumerateAdapters(...)。 - (void)object; -} -``` +- 当前实现会调用 `EnumAdapters1`、`GetDesc1`、`push_back`。 +- 包含条件分支，并可能提前返回。 ## 相关文档 -- [返回类总览](D3D12Device.md) -- [返回模块目录](../D3D12.md) +- [D3D12Device](D3D12Device.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Device/GetAdapterInfo.md b/docs/api/XCEngine/RHI/D3D12/D3D12Device/GetAdapterInfo.md index 4f916c77..35312003 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12Device/GetAdapterInfo.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12Device/GetAdapterInfo.md @@ -1,30 +1,25 @@ # D3D12Device::GetAdapterInfo -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12Device.h` + +## 签名 ```cpp const AdapterInfo& GetAdapterInfo() const; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12Device.h`，当前页面用于固定 `D3D12Device` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_adapterInfo` 当前值。 -**返回：** `const AdapterInfo&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12Device object; - // 根据上下文补齐参数后调用 D3D12Device::GetAdapterInfo(...)。 - (void)object; -} -``` +- 返回 `m_adapterInfo` 当前值。 ## 相关文档 -- [返回类总览](D3D12Device.md) -- [返回模块目录](../D3D12.md) +- [D3D12Device](D3D12Device.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Device/GetCapabilities.md b/docs/api/XCEngine/RHI/D3D12/D3D12Device/GetCapabilities.md index a618ca39..8b4511e6 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12Device/GetCapabilities.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12Device/GetCapabilities.md @@ -1,30 +1,25 @@ # D3D12Device::GetCapabilities -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12Device.h` + +## 签名 ```cpp const RHICapabilities& GetCapabilities() const override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12Device.h`，当前页面用于固定 `D3D12Device` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_capabilities` 当前值。 -**返回：** `const RHICapabilities&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12Device object; - // 根据上下文补齐参数后调用 D3D12Device::GetCapabilities(...)。 - (void)object; -} -``` +- 返回 `m_capabilities` 当前值。 ## 相关文档 -- [返回类总览](D3D12Device.md) -- [返回模块目录](../D3D12.md) +- [D3D12Device](D3D12Device.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Device/GetDescriptorHandleIncrementSize.md b/docs/api/XCEngine/RHI/D3D12/D3D12Device/GetDescriptorHandleIncrementSize.md index af495738..c2064207 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12Device/GetDescriptorHandleIncrementSize.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12Device/GetDescriptorHandleIncrementSize.md @@ -1,31 +1,25 @@ # D3D12Device::GetDescriptorHandleIncrementSize -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12Device.h` + +## 签名 ```cpp UINT GetDescriptorHandleIncrementSize(DescriptorHeapType type) const; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12Device.h`，当前页面用于固定 `D3D12Device` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `type` - 参数语义详见头文件声明。 +返回 `m_device->GetDescriptorHandleIncrementSize(ToD3D12(type))`。 -**返回：** `UINT` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12Device object; - // 根据上下文补齐参数后调用 D3D12Device::GetDescriptorHandleIncrementSize(...)。 - (void)object; -} -``` +- 当前实现会调用 `GetDescriptorHandleIncrementSize`、`ToD3D12`。 ## 相关文档 -- [返回类总览](D3D12Device.md) -- [返回模块目录](../D3D12.md) +- [D3D12Device](D3D12Device.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Device/GetDevice.md b/docs/api/XCEngine/RHI/D3D12/D3D12Device/GetDevice.md index 248ddd3e..ad731e63 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12Device/GetDevice.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12Device/GetDevice.md @@ -1,30 +1,25 @@ # D3D12Device::GetDevice -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12Device.h` + +## 签名 ```cpp ID3D12Device* GetDevice() const; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12Device.h`，当前页面用于固定 `D3D12Device` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_device`。 -**返回：** `ID3D12Device*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12Device object; - // 根据上下文补齐参数后调用 D3D12Device::GetDevice(...)。 - (void)object; -} -``` +- 会更新 `m_device`。 ## 相关文档 -- [返回类总览](D3D12Device.md) -- [返回模块目录](../D3D12.md) +- [D3D12Device](D3D12Device.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Device/GetDeviceInfo.md b/docs/api/XCEngine/RHI/D3D12/D3D12Device/GetDeviceInfo.md index 9e151fec..54a81cc4 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12Device/GetDeviceInfo.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12Device/GetDeviceInfo.md @@ -1,30 +1,25 @@ # D3D12Device::GetDeviceInfo -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12Device.h` + +## 签名 ```cpp const RHIDeviceInfo& GetDeviceInfo() const override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12Device.h`，当前页面用于固定 `D3D12Device` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_deviceInfo` 当前值。 -**返回：** `const RHIDeviceInfo&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12Device object; - // 根据上下文补齐参数后调用 D3D12Device::GetDeviceInfo(...)。 - (void)object; -} -``` +- 返回 `m_deviceInfo` 当前值。 ## 相关文档 -- [返回类总览](D3D12Device.md) -- [返回模块目录](../D3D12.md) +- [D3D12Device](D3D12Device.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Device/GetFactory.md b/docs/api/XCEngine/RHI/D3D12/D3D12Device/GetFactory.md index 232d0091..d8032a0b 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12Device/GetFactory.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12Device/GetFactory.md @@ -1,30 +1,25 @@ # D3D12Device::GetFactory -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12Device.h` + +## 签名 ```cpp IDXGIFactory4* GetFactory() const; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12Device.h`，当前页面用于固定 `D3D12Device` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_factory`。 -**返回：** `IDXGIFactory4*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12Device object; - // 根据上下文补齐参数后调用 D3D12Device::GetFactory(...)。 - (void)object; -} -``` +- 会更新 `m_factory`。 ## 相关文档 -- [返回类总览](D3D12Device.md) -- [返回模块目录](../D3D12.md) +- [D3D12Device](D3D12Device.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Device/GetNativeDevice.md b/docs/api/XCEngine/RHI/D3D12/D3D12Device/GetNativeDevice.md index 7647a32d..1df9bb11 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12Device/GetNativeDevice.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12Device/GetNativeDevice.md @@ -1,30 +1,25 @@ # D3D12Device::GetNativeDevice -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12Device.h` + +## 签名 ```cpp void* GetNativeDevice() override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12Device.h`，当前页面用于固定 `D3D12Device` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_device`。 -**返回：** `void*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12Device object; - // 根据上下文补齐参数后调用 D3D12Device::GetNativeDevice(...)。 - (void)object; -} -``` +- 会更新 `m_device`。 ## 相关文档 -- [返回类总览](D3D12Device.md) -- [返回模块目录](../D3D12.md) +- [D3D12Device](D3D12Device.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Device/GetNativeHandle.md b/docs/api/XCEngine/RHI/D3D12/D3D12Device/GetNativeHandle.md index e70fc01d..ed677a27 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12Device/GetNativeHandle.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12Device/GetNativeHandle.md @@ -1,30 +1,25 @@ # D3D12Device::GetNativeHandle -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12Device.h` + +## 签名 ```cpp void* GetNativeHandle() const; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12Device.h`，当前页面用于固定 `D3D12Device` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_device`。 -**返回：** `void*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12Device object; - // 根据上下文补齐参数后调用 D3D12Device::GetNativeHandle(...)。 - (void)object; -} -``` +- 会更新 `m_device`。 ## 相关文档 -- [返回类总览](D3D12Device.md) -- [返回模块目录](../D3D12.md) +- [D3D12Device](D3D12Device.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Device/IsDeviceRemoved.md b/docs/api/XCEngine/RHI/D3D12/D3D12Device/IsDeviceRemoved.md index db990b4c..bba6d768 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12Device/IsDeviceRemoved.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12Device/IsDeviceRemoved.md @@ -1,30 +1,25 @@ # D3D12Device::IsDeviceRemoved -查询当前状态。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12Device.h` + +## 签名 ```cpp bool IsDeviceRemoved() const; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12Device.h`，当前页面用于固定 `D3D12Device` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_isDeviceRemoved` 当前值。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12Device object; - // 根据上下文补齐参数后调用 D3D12Device::IsDeviceRemoved(...)。 - (void)object; -} -``` +- 返回 `m_isDeviceRemoved` 当前值。 ## 相关文档 -- [返回类总览](D3D12Device.md) -- [返回模块目录](../D3D12.md) +- [D3D12Device](D3D12Device.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Device/SetDeviceRemoved.md b/docs/api/XCEngine/RHI/D3D12/D3D12Device/SetDeviceRemoved.md index f55a046b..1cb15214 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12Device/SetDeviceRemoved.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12Device/SetDeviceRemoved.md @@ -1,30 +1,25 @@ # D3D12Device::SetDeviceRemoved -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12Device.h` + +## 签名 ```cpp void SetDeviceRemoved(); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12Device.h`，当前页面用于固定 `D3D12Device` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_isDeviceRemoved`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12Device object; - // 根据上下文补齐参数后调用 D3D12Device::SetDeviceRemoved(...)。 - (void)object; -} -``` +- 会更新 `m_isDeviceRemoved`。 ## 相关文档 -- [返回类总览](D3D12Device.md) -- [返回模块目录](../D3D12.md) +- [D3D12Device](D3D12Device.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Device/Shutdown.md b/docs/api/XCEngine/RHI/D3D12/D3D12Device/Shutdown.md index 4d4cb08b..034cbd0c 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12Device/Shutdown.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12Device/Shutdown.md @@ -1,30 +1,26 @@ # D3D12Device::Shutdown -关闭并清理内部状态。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12Device.h` + +## 签名 ```cpp void Shutdown() override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12Device.h`，当前页面用于固定 `D3D12Device` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `Reset` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12Device object; - // 根据上下文补齐参数后调用 D3D12Device::Shutdown(...)。 - (void)object; -} -``` +- 会更新 `m_initialized`、`m_device`、`m_factory`、`m_adapter`。 +- 当前实现会调用 `Reset`。 ## 相关文档 -- [返回类总览](D3D12Device.md) -- [返回模块目录](../D3D12.md) +- [D3D12Device](D3D12Device.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Enums/D3D12Enums.md b/docs/api/XCEngine/RHI/D3D12/D3D12Enums/D3D12Enums.md index a801cadc..0080b298 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12Enums/D3D12Enums.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12Enums/D3D12Enums.md @@ -6,11 +6,18 @@ **头文件**: `XCEngine/RHI/D3D12/D3D12Enums.h` -**描述**: 定义 `XCEngine/RHI/D3D12` 子目录中的 `D3D12Enums` public API。 +**描述**: D3D12 枚举映射头，提供引擎 RHI 枚举与 D3D12 / DXGI 原生枚举之间的双向转换函数。 ## 概述 -`D3D12Enums.h` 是 `XCEngine/RHI/D3D12` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。 +`D3D12Enums.h` 的职责很直接：把引擎自己的 RHI 枚举翻译成 D3D12 / DXGI 能识别的原生值，必要时再做反向转换。当前头文件覆盖的映射包括： + +- rasterizer、blend、depth / stencil、sampler、shader visibility +- 纹理 / buffer format 与 `DXGI_FORMAT` +- resource state、heap type、primitive topology、descriptor heap type、query type +- root parameter type、texture dimension、command list type + +它是 D3D12 后端把平台无关 RHI 配置落到原生 API 的基础桥接层。 ## 相关文档 diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/Bind.md b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/Bind.md index 168f00f4..78dd0d63 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/Bind.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/Bind.md @@ -1,30 +1,25 @@ # D3D12PipelineState::Bind -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12PipelineState.h` + +## 签名 ```cpp void Bind() override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12PipelineState.h`，当前页面用于固定 `D3D12PipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +当前实现为空。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12PipelineState object; - // 根据上下文补齐参数后调用 D3D12PipelineState::Bind(...)。 - (void)object; -} -``` +- 当前函数体为空。 ## 相关文档 -- [返回类总览](D3D12PipelineState.md) -- [返回模块目录](../D3D12.md) +- [D3D12PipelineState](D3D12PipelineState.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/Constructor.md b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/Constructor.md index 22ab843e..87c3f80b 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/Constructor.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/Constructor.md @@ -1,41 +1,26 @@ # D3D12PipelineState::D3D12PipelineState() -构造对象。 +**命名空间**: `XCEngine::RHI` -该方法在 `XCEngine/RHI/D3D12/D3D12PipelineState.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。 +**类型**: `method` -## 重载 1: 声明 +**头文件**: `XCEngine/RHI/D3D12/D3D12PipelineState.h` + +## 签名 ```cpp D3D12PipelineState() = default; -``` - -**参数：** 无。 - -**返回：** `void` - 无返回值。 - -## 重载 2: 声明 - -```cpp D3D12PipelineState(ID3D12Device* device); ``` -**参数：** -- `device` - 参数语义详见头文件声明。 +## 作用 -**返回：** `void` - 无返回值。 +构造 `D3D12PipelineState` 实例。 -**示例：** +## 当前实现 -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12PipelineState object; -} -``` +- 当前为默认构造实现。 ## 相关文档 -- [返回类总览](D3D12PipelineState.md) -- [返回模块目录](../D3D12.md) +- [D3D12PipelineState](D3D12PipelineState.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/CreateInputElement.md b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/CreateInputElement.md index 57290b13..5631ef11 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/CreateInputElement.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/CreateInputElement.md @@ -1,51 +1,27 @@ # D3D12PipelineState::CreateInputElement -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` -该方法在 `XCEngine/RHI/D3D12/D3D12PipelineState.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。 +**类型**: `method` -## 重载 1: 声明 +**头文件**: `XCEngine/RHI/D3D12/D3D12PipelineState.h` + +## 签名 ```cpp static D3D12_INPUT_ELEMENT_DESC CreateInputElement( const char* semanticName, uint32_t semanticIndex, Format format, uint32_t inputSlot, uint32_t alignedByteOffset); -``` - -**参数：** -- `semanticName` - 参数语义详见头文件声明。 -- `semanticIndex` - 参数语义详见头文件声明。 -- `format` - 参数语义详见头文件声明。 -- `inputSlot` - 参数语义详见头文件声明。 -- `alignedByteOffset` - 参数语义详见头文件声明。 - -**返回：** `D3D12_INPUT_ELEMENT_DESC` - 返回值语义详见头文件声明。 - -## 重载 2: 声明 - -```cpp static D3D12_INPUT_ELEMENT_DESC CreateInputElement( const char* semanticName, uint32_t semanticIndex, Format format, uint32_t inputSlot); ``` -**参数：** -- `semanticName` - 参数语义详见头文件声明。 -- `semanticIndex` - 参数语义详见头文件声明。 -- `format` - 参数语义详见头文件声明。 -- `inputSlot` - 参数语义详见头文件声明。 +## 作用 -**返回：** `D3D12_INPUT_ELEMENT_DESC` - 返回值语义详见头文件声明。 +执行 `ToD3D12(...)` 相关流程。 -**示例：** +## 当前实现 -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12PipelineState object; - // 根据上下文补齐参数后调用 D3D12PipelineState::CreateInputElement(...)。 - (void)object; -} -``` +- 当前实现会调用 `ToD3D12`。 +- 当前实现会调用 `CreateInputElement`。 ## 相关文档 -- [返回类总览](D3D12PipelineState.md) -- [返回模块目录](../D3D12.md) +- [D3D12PipelineState](D3D12PipelineState.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/D3D12PipelineState.md b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/D3D12PipelineState.md index e126f1c7..b75be98d 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/D3D12PipelineState.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/D3D12PipelineState.md @@ -6,54 +6,59 @@ **头文件**: `XCEngine/RHI/D3D12/D3D12PipelineState.h` -**描述**: 定义 `XCEngine/RHI/D3D12` 子目录中的 `D3D12PipelineState` public API。 +**描述**: D3D12 pipeline state 封装，保存 Unity SRP 风格的管线配置，并在需要时生成 graphics / compute PSO。 ## 概述 -`D3D12PipelineState.h` 是 `XCEngine/RHI/D3D12` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。 +`D3D12PipelineState` 是 D3D12 后端的 PSO 包装类。它不是单纯的原生句柄壳，而是先缓存一整套与引擎 RHI 对齐的状态描述，再在 `EnsureValid()` 或初始化阶段把这些配置固化成 D3D12 graphics / compute pipeline state object。头文件里当前可见的职责包括： + +- 存储 rasterizer、blend、depth-stencil、input layout、render target format 等状态 +- 接收 graphics / compute shader bytecode +- 管理 root signature 和最终 `ID3D12PipelineState` +- 为命令列表绑定前提供 hash、类型和有效性查询 ## 声明概览 | 声明 | 类型 | 说明 | |------|------|------| -| `D3D12PipelineState` | `class` | 继承自 `RHIPipelineState` 的公开声明。 | +| `D3D12PipelineState` | `class` | D3D12 后端的 graphics / compute PSO 封装。 | ## 公共方法 | 方法 | 描述 | |------|------| -| [D3D12PipelineState()](Constructor.md) | 构造对象。 | -| [~D3D12PipelineState()](Destructor.md) | 销毁对象并释放相关资源。 | -| [Initialize](Initialize.md) | 初始化内部状态。 | -| [SetInputLayout](SetInputLayout.md) | 设置相关状态或配置。 | -| [SetRasterizerState](SetRasterizerState.md) | 设置相关状态或配置。 | -| [SetBlendState](SetBlendState.md) | 设置相关状态或配置。 | -| [SetDepthStencilState](SetDepthStencilState.md) | 设置相关状态或配置。 | -| [SetTopology](SetTopology.md) | 设置相关状态或配置。 | -| [SetRenderTargetFormats](SetRenderTargetFormats.md) | 设置相关状态或配置。 | -| [SetSampleCount](SetSampleCount.md) | 设置相关状态或配置。 | -| [SetComputeShader](SetComputeShader.md) | 设置相关状态或配置。 | -| [SetRootSignature](SetRootSignature.md) | 设置相关状态或配置。 | -| [GetRasterizerState](GetRasterizerState.md) | 获取相关状态或对象。 | -| [GetBlendState](GetBlendState.md) | 获取相关状态或对象。 | -| [GetDepthStencilState](GetDepthStencilState.md) | 获取相关状态或对象。 | -| [GetInputLayout](GetInputLayout.md) | 获取相关状态或对象。 | -| [GetHash](GetHash.md) | 获取相关状态或对象。 | -| [GetComputeShader](GetComputeShader.md) | 获取相关状态或对象。 | -| [HasComputeShader](HasComputeShader.md) | 判断是否具备指定状态或能力。 | -| [IsValid](IsValid.md) | 查询当前状态。 | -| [EnsureValid](EnsureValid.md) | 公开方法，详见头文件声明。 | -| [SetShaderBytecodes](SetShaderBytecodes.md) | 设置相关状态或配置。 | -| [SetComputeShaderBytecodes](SetComputeShaderBytecodes.md) | 设置相关状态或配置。 | -| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 | -| [GetPipelineState](GetPipelineState.md) | 获取相关状态或对象。 | -| [GetComputePipelineState](GetComputePipelineState.md) | 获取相关状态或对象。 | -| [GetRootSignature](GetRootSignature.md) | 获取相关状态或对象。 | -| [GetNativeHandle](GetNativeHandle.md) | 获取相关状态或对象。 | -| [GetType](GetType.md) | 获取相关状态或对象。 | -| [Bind](Bind.md) | 公开方法，详见头文件声明。 | -| [Unbind](Unbind.md) | 公开方法，详见头文件声明。 | -| [CreateInputElement](CreateInputElement.md) | 创建新对象或资源。 | +| [D3D12PipelineState()](Constructor.md) | 构造 `D3D12PipelineState` 实例。 | +| [~D3D12PipelineState()](Destructor.md) | 执行 `Shutdown(...)` 相关流程。 | +| [Initialize](Initialize.md) | 执行 `clear`、`push_back`、`EnsureValid` 协同流程。 | +| [SetInputLayout](SetInputLayout.md) | 更新 `m_inputLayoutDesc`。 | +| [SetRasterizerState](SetRasterizerState.md) | 写入 `m_rasterizerDesc`。 | +| [SetBlendState](SetBlendState.md) | 写入 `m_blendDesc`。 | +| [SetDepthStencilState](SetDepthStencilState.md) | 写入 `m_depthStencilDesc`。 | +| [SetTopology](SetTopology.md) | 写入 `m_topologyType`。 | +| [SetRenderTargetFormats](SetRenderTargetFormats.md) | 执行该公开方法对应的当前实现。 | +| [SetSampleCount](SetSampleCount.md) | 写入 `m_sampleCount`。 | +| [SetComputeShader](SetComputeShader.md) | 执行 `Reset`、`IsValid` 协同流程。 | +| [SetRootSignature](SetRootSignature.md) | 写入 `m_rootSignature`。 | +| [GetRasterizerState](GetRasterizerState.md) | 返回 `m_rasterizerDesc` 当前值。 | +| [GetBlendState](GetBlendState.md) | 返回 `m_blendDesc` 当前值。 | +| [GetDepthStencilState](GetDepthStencilState.md) | 返回 `m_depthStencilDesc` 当前值。 | +| [GetInputLayout](GetInputLayout.md) | 返回 `m_inputLayoutDesc` 当前值。 | +| [GetHash](GetHash.md) | 返回 `hash`。 | +| [GetComputeShader](GetComputeShader.md) | 返回 `m_computeShader` 当前值。 | +| [HasComputeShader](HasComputeShader.md) | 返回 `m_csBytecode.pShaderBytecode != nullptr && m_csBytecode.BytecodeLength > 0`。 | +| [IsValid](IsValid.md) | 返回 `m_finalized` 当前值。 | +| [EnsureValid](EnsureValid.md) | 执行 `HasComputeShader`、`CreateD3D12ComputePSO`、`CreateD3D12PSO` 协同流程。 | +| [SetShaderBytecodes](SetShaderBytecodes.md) | 执行该公开方法对应的当前实现。 | +| [SetComputeShaderBytecodes](SetComputeShaderBytecodes.md) | 写入 `m_csBytecode`。 | +| [Shutdown](Shutdown.md) | 执行 `Reset` 协同流程。 | +| [GetPipelineState](GetPipelineState.md) | 返回 `m_pipelineState.Get()` 的结果。 | +| [GetComputePipelineState](GetComputePipelineState.md) | 返回 `m_computePipelineState.Get()` 的结果。 | +| [GetRootSignature](GetRootSignature.md) | 返回 `m_rootSignature.Get()` 的结果。 | +| [GetNativeHandle](GetNativeHandle.md) | 返回 `m_pipelineState.Get()` 的结果。 | +| [GetType](GetType.md) | 返回 `HasComputeShader() ? PipelineType::Compute : PipelineType::Graphics`。 | +| [Bind](Bind.md) | 当前实现为空。 | +| [Unbind](Unbind.md) | 当前实现为空。 | +| [CreateInputElement](CreateInputElement.md) | 执行 `ToD3D12(...)` 相关流程。 | ## 相关文档 diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/Destructor.md b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/Destructor.md index 85f57547..665da8cd 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/Destructor.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/Destructor.md @@ -1,29 +1,25 @@ # D3D12PipelineState::~D3D12PipelineState() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12PipelineState.h` + +## 签名 ```cpp ~D3D12PipelineState() override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12PipelineState.h`，当前页面用于固定 `D3D12PipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `Shutdown(...)` 相关流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12PipelineState object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 当前实现会调用 `Shutdown`。 ## 相关文档 -- [返回类总览](D3D12PipelineState.md) -- [返回模块目录](../D3D12.md) +- [D3D12PipelineState](D3D12PipelineState.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/EnsureValid.md b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/EnsureValid.md index ddf11ff3..78455252 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/EnsureValid.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/EnsureValid.md @@ -1,30 +1,25 @@ # D3D12PipelineState::EnsureValid -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12PipelineState.h` + +## 签名 ```cpp void EnsureValid() override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12PipelineState.h`，当前页面用于固定 `D3D12PipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `HasComputeShader`、`CreateD3D12ComputePSO`、`CreateD3D12PSO` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12PipelineState object; - // 根据上下文补齐参数后调用 D3D12PipelineState::EnsureValid(...)。 - (void)object; -} -``` +- 当前实现会调用 `HasComputeShader`、`CreateD3D12ComputePSO`、`CreateD3D12PSO`。 ## 相关文档 -- [返回类总览](D3D12PipelineState.md) -- [返回模块目录](../D3D12.md) +- [D3D12PipelineState](D3D12PipelineState.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/GetBlendState.md b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/GetBlendState.md index 39514e99..dc7fa39e 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/GetBlendState.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/GetBlendState.md @@ -1,30 +1,26 @@ # D3D12PipelineState::GetBlendState -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12PipelineState.h` + +## 签名 ```cpp const BlendDesc& GetBlendState() const override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12PipelineState.h`，当前页面用于固定 `D3D12PipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_blendDesc` 当前值。 -**返回：** `const BlendDesc&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12PipelineState object; - // 根据上下文补齐参数后调用 D3D12PipelineState::GetBlendState(...)。 - (void)object; -} -``` +- 返回 `m_blendDesc` 当前值。 ## 相关文档 -- [返回类总览](D3D12PipelineState.md) -- [返回模块目录](../D3D12.md) +- [D3D12PipelineState](D3D12PipelineState.md) +- [SetBlendState](SetBlendState.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/GetComputePipelineState.md b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/GetComputePipelineState.md index bdf634fe..7c68edd0 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/GetComputePipelineState.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/GetComputePipelineState.md @@ -1,30 +1,25 @@ # D3D12PipelineState::GetComputePipelineState -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12PipelineState.h` + +## 签名 ```cpp ID3D12PipelineState* GetComputePipelineState() const; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12PipelineState.h`，当前页面用于固定 `D3D12PipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_computePipelineState`。 -**返回：** `ID3D12PipelineState*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12PipelineState object; - // 根据上下文补齐参数后调用 D3D12PipelineState::GetComputePipelineState(...)。 - (void)object; -} -``` +- 会更新 `m_computePipelineState`。 ## 相关文档 -- [返回类总览](D3D12PipelineState.md) -- [返回模块目录](../D3D12.md) +- [D3D12PipelineState](D3D12PipelineState.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/GetComputeShader.md b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/GetComputeShader.md index 973afe37..ef801a95 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/GetComputeShader.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/GetComputeShader.md @@ -1,30 +1,26 @@ # D3D12PipelineState::GetComputeShader -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12PipelineState.h` + +## 签名 ```cpp RHIShader* GetComputeShader() const override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12PipelineState.h`，当前页面用于固定 `D3D12PipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_computeShader` 当前值。 -**返回：** `RHIShader*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12PipelineState object; - // 根据上下文补齐参数后调用 D3D12PipelineState::GetComputeShader(...)。 - (void)object; -} -``` +- 返回 `m_computeShader` 当前值。 ## 相关文档 -- [返回类总览](D3D12PipelineState.md) -- [返回模块目录](../D3D12.md) +- [D3D12PipelineState](D3D12PipelineState.md) +- [SetComputeShader](SetComputeShader.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/GetDepthStencilState.md b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/GetDepthStencilState.md index f4f4c021..8b7191b6 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/GetDepthStencilState.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/GetDepthStencilState.md @@ -1,30 +1,26 @@ # D3D12PipelineState::GetDepthStencilState -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12PipelineState.h` + +## 签名 ```cpp const DepthStencilStateDesc& GetDepthStencilState() const override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12PipelineState.h`，当前页面用于固定 `D3D12PipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_depthStencilDesc` 当前值。 -**返回：** `const DepthStencilStateDesc&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12PipelineState object; - // 根据上下文补齐参数后调用 D3D12PipelineState::GetDepthStencilState(...)。 - (void)object; -} -``` +- 返回 `m_depthStencilDesc` 当前值。 ## 相关文档 -- [返回类总览](D3D12PipelineState.md) -- [返回模块目录](../D3D12.md) +- [D3D12PipelineState](D3D12PipelineState.md) +- [SetDepthStencilState](SetDepthStencilState.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/GetHash.md b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/GetHash.md index 8930b54d..b4a63898 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/GetHash.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/GetHash.md @@ -1,30 +1,25 @@ # D3D12PipelineState::GetHash -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12PipelineState.h` + +## 签名 ```cpp PipelineStateHash GetHash() const override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12PipelineState.h`，当前页面用于固定 `D3D12PipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `hash`。 -**返回：** `PipelineStateHash` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12PipelineState object; - // 根据上下文补齐参数后调用 D3D12PipelineState::GetHash(...)。 - (void)object; -} -``` +- 返回 `hash`。 ## 相关文档 -- [返回类总览](D3D12PipelineState.md) -- [返回模块目录](../D3D12.md) +- [D3D12PipelineState](D3D12PipelineState.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/GetInputLayout.md b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/GetInputLayout.md index 928e5eb3..0c6462a4 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/GetInputLayout.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/GetInputLayout.md @@ -1,30 +1,26 @@ # D3D12PipelineState::GetInputLayout -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12PipelineState.h` + +## 签名 ```cpp const InputLayoutDesc& GetInputLayout() const override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12PipelineState.h`，当前页面用于固定 `D3D12PipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_inputLayoutDesc` 当前值。 -**返回：** `const InputLayoutDesc&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12PipelineState object; - // 根据上下文补齐参数后调用 D3D12PipelineState::GetInputLayout(...)。 - (void)object; -} -``` +- 返回 `m_inputLayoutDesc` 当前值。 ## 相关文档 -- [返回类总览](D3D12PipelineState.md) -- [返回模块目录](../D3D12.md) +- [D3D12PipelineState](D3D12PipelineState.md) +- [SetInputLayout](SetInputLayout.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/GetNativeHandle.md b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/GetNativeHandle.md index a9288d4d..f2882e36 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/GetNativeHandle.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/GetNativeHandle.md @@ -1,30 +1,25 @@ # D3D12PipelineState::GetNativeHandle -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12PipelineState.h` + +## 签名 ```cpp void* GetNativeHandle() override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12PipelineState.h`，当前页面用于固定 `D3D12PipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_pipelineState`。 -**返回：** `void*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12PipelineState object; - // 根据上下文补齐参数后调用 D3D12PipelineState::GetNativeHandle(...)。 - (void)object; -} -``` +- 会更新 `m_pipelineState`。 ## 相关文档 -- [返回类总览](D3D12PipelineState.md) -- [返回模块目录](../D3D12.md) +- [D3D12PipelineState](D3D12PipelineState.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/GetPipelineState.md b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/GetPipelineState.md index f69b1205..458d034e 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/GetPipelineState.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/GetPipelineState.md @@ -1,30 +1,25 @@ # D3D12PipelineState::GetPipelineState -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12PipelineState.h` + +## 签名 ```cpp ID3D12PipelineState* GetPipelineState() const; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12PipelineState.h`，当前页面用于固定 `D3D12PipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_pipelineState`。 -**返回：** `ID3D12PipelineState*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12PipelineState object; - // 根据上下文补齐参数后调用 D3D12PipelineState::GetPipelineState(...)。 - (void)object; -} -``` +- 会更新 `m_pipelineState`。 ## 相关文档 -- [返回类总览](D3D12PipelineState.md) -- [返回模块目录](../D3D12.md) +- [D3D12PipelineState](D3D12PipelineState.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/GetRasterizerState.md b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/GetRasterizerState.md index 8c37f372..2d207261 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/GetRasterizerState.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/GetRasterizerState.md @@ -1,30 +1,26 @@ # D3D12PipelineState::GetRasterizerState -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12PipelineState.h` + +## 签名 ```cpp const RasterizerDesc& GetRasterizerState() const override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12PipelineState.h`，当前页面用于固定 `D3D12PipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_rasterizerDesc` 当前值。 -**返回：** `const RasterizerDesc&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12PipelineState object; - // 根据上下文补齐参数后调用 D3D12PipelineState::GetRasterizerState(...)。 - (void)object; -} -``` +- 返回 `m_rasterizerDesc` 当前值。 ## 相关文档 -- [返回类总览](D3D12PipelineState.md) -- [返回模块目录](../D3D12.md) +- [D3D12PipelineState](D3D12PipelineState.md) +- [SetRasterizerState](SetRasterizerState.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/GetRootSignature.md b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/GetRootSignature.md index d50de5a7..25dd70d3 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/GetRootSignature.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/GetRootSignature.md @@ -1,30 +1,26 @@ # D3D12PipelineState::GetRootSignature -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12PipelineState.h` + +## 签名 ```cpp ID3D12RootSignature* GetRootSignature() const; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12PipelineState.h`，当前页面用于固定 `D3D12PipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_rootSignature`。 -**返回：** `ID3D12RootSignature*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12PipelineState object; - // 根据上下文补齐参数后调用 D3D12PipelineState::GetRootSignature(...)。 - (void)object; -} -``` +- 会更新 `m_rootSignature`。 ## 相关文档 -- [返回类总览](D3D12PipelineState.md) -- [返回模块目录](../D3D12.md) +- [D3D12PipelineState](D3D12PipelineState.md) +- [SetRootSignature](SetRootSignature.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/GetType.md b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/GetType.md index 00bb2e33..cb688622 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/GetType.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/GetType.md @@ -1,30 +1,25 @@ # D3D12PipelineState::GetType -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12PipelineState.h` + +## 签名 ```cpp PipelineType GetType() const override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12PipelineState.h`，当前页面用于固定 `D3D12PipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `HasComputeShader(...)` 相关流程。 -**返回：** `PipelineType` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12PipelineState object; - // 根据上下文补齐参数后调用 D3D12PipelineState::GetType(...)。 - (void)object; -} -``` +- 当前实现会调用 `HasComputeShader`。 ## 相关文档 -- [返回类总览](D3D12PipelineState.md) -- [返回模块目录](../D3D12.md) +- [D3D12PipelineState](D3D12PipelineState.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/HasComputeShader.md b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/HasComputeShader.md index 4fcf58f7..0c4b4690 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/HasComputeShader.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/HasComputeShader.md @@ -1,30 +1,25 @@ # D3D12PipelineState::HasComputeShader -判断是否具备指定状态或能力。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12PipelineState.h` + +## 签名 ```cpp bool HasComputeShader() const override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12PipelineState.h`，当前页面用于固定 `D3D12PipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_csBytecode.pShaderBytecode != nullptr && m_csBytecode.BytecodeLength > 0`。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12PipelineState object; - // 根据上下文补齐参数后调用 D3D12PipelineState::HasComputeShader(...)。 - (void)object; -} -``` +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](D3D12PipelineState.md) -- [返回模块目录](../D3D12.md) +- [D3D12PipelineState](D3D12PipelineState.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/Initialize.md b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/Initialize.md index 3429d1b7..14eca779 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/Initialize.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/Initialize.md @@ -1,32 +1,26 @@ # D3D12PipelineState::Initialize -初始化内部状态。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12PipelineState.h` + +## 签名 ```cpp bool Initialize(ID3D12Device* device, const D3D12_GRAPHICS_PIPELINE_STATE_DESC& desc); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12PipelineState.h`，当前页面用于固定 `D3D12PipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `device` - 参数语义详见头文件声明。 -- `desc` - 参数语义详见头文件声明。 +返回 `m_finalized` 当前值。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12PipelineState object; - // 根据上下文补齐参数后调用 D3D12PipelineState::Initialize(...)。 - (void)object; -} -``` +- 会更新 `m_device`、`m_rootSignature`、`m_topologyType`、`m_renderTargetCount`。 +- 当前实现会调用 `clear`、`push_back`、`EnsureValid`。 ## 相关文档 -- [返回类总览](D3D12PipelineState.md) -- [返回模块目录](../D3D12.md) +- [D3D12PipelineState](D3D12PipelineState.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/IsValid.md b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/IsValid.md index 432897a5..4fd5f3f5 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/IsValid.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/IsValid.md @@ -1,30 +1,25 @@ # D3D12PipelineState::IsValid -查询当前状态。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12PipelineState.h` + +## 签名 ```cpp bool IsValid() const override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12PipelineState.h`，当前页面用于固定 `D3D12PipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_finalized` 当前值。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12PipelineState object; - // 根据上下文补齐参数后调用 D3D12PipelineState::IsValid(...)。 - (void)object; -} -``` +- 返回 `m_finalized` 当前值。 ## 相关文档 -- [返回类总览](D3D12PipelineState.md) -- [返回模块目录](../D3D12.md) +- [D3D12PipelineState](D3D12PipelineState.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/SetBlendState.md b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/SetBlendState.md index cb272cf3..84acb92a 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/SetBlendState.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/SetBlendState.md @@ -1,31 +1,26 @@ # D3D12PipelineState::SetBlendState -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12PipelineState.h` + +## 签名 ```cpp void SetBlendState(const BlendDesc& state) override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12PipelineState.h`，当前页面用于固定 `D3D12PipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `state` - 参数语义详见头文件声明。 +更新 `m_blendDesc`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12PipelineState object; - // 根据上下文补齐参数后调用 D3D12PipelineState::SetBlendState(...)。 - (void)object; -} -``` +- 会更新 `m_blendDesc`。 ## 相关文档 -- [返回类总览](D3D12PipelineState.md) -- [返回模块目录](../D3D12.md) +- [D3D12PipelineState](D3D12PipelineState.md) +- [GetBlendState](GetBlendState.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/SetComputeShader.md b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/SetComputeShader.md index 4726892c..0cfbf4b5 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/SetComputeShader.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/SetComputeShader.md @@ -1,31 +1,28 @@ # D3D12PipelineState::SetComputeShader -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12PipelineState.h` + +## 签名 ```cpp void SetComputeShader(RHIShader* shader) override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12PipelineState.h`，当前页面用于固定 `D3D12PipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `shader` - 参数语义详见头文件声明。 +执行 `Reset`、`IsValid` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12PipelineState object; - // 根据上下文补齐参数后调用 D3D12PipelineState::SetComputeShader(...)。 - (void)object; -} -``` +- 会更新 `m_computeShader`、`m_csBytecode`、`m_finalized`、`m_computePipelineState`。 +- 当前实现会调用 `Reset`、`IsValid`、`GetType`、`GetD3D12Bytecode`。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](D3D12PipelineState.md) -- [返回模块目录](../D3D12.md) +- [D3D12PipelineState](D3D12PipelineState.md) +- [GetComputeShader](GetComputeShader.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/SetComputeShaderBytecodes.md b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/SetComputeShaderBytecodes.md index 3ca0f5a7..04ced25a 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/SetComputeShaderBytecodes.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/SetComputeShaderBytecodes.md @@ -1,31 +1,25 @@ # D3D12PipelineState::SetComputeShaderBytecodes -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12PipelineState.h` + +## 签名 ```cpp void SetComputeShaderBytecodes(const D3D12_SHADER_BYTECODE& cs); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12PipelineState.h`，当前页面用于固定 `D3D12PipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `cs` - 参数语义详见头文件声明。 +更新 `m_csBytecode`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12PipelineState object; - // 根据上下文补齐参数后调用 D3D12PipelineState::SetComputeShaderBytecodes(...)。 - (void)object; -} -``` +- 会更新 `m_csBytecode`。 ## 相关文档 -- [返回类总览](D3D12PipelineState.md) -- [返回模块目录](../D3D12.md) +- [D3D12PipelineState](D3D12PipelineState.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/SetDepthStencilState.md b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/SetDepthStencilState.md index f6c2cccf..9aedd3cc 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/SetDepthStencilState.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/SetDepthStencilState.md @@ -1,31 +1,26 @@ # D3D12PipelineState::SetDepthStencilState -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12PipelineState.h` + +## 签名 ```cpp void SetDepthStencilState(const DepthStencilStateDesc& state) override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12PipelineState.h`，当前页面用于固定 `D3D12PipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `state` - 参数语义详见头文件声明。 +更新 `m_depthStencilDesc`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12PipelineState object; - // 根据上下文补齐参数后调用 D3D12PipelineState::SetDepthStencilState(...)。 - (void)object; -} -``` +- 会更新 `m_depthStencilDesc`。 ## 相关文档 -- [返回类总览](D3D12PipelineState.md) -- [返回模块目录](../D3D12.md) +- [D3D12PipelineState](D3D12PipelineState.md) +- [GetDepthStencilState](GetDepthStencilState.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/SetInputLayout.md b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/SetInputLayout.md index bfd9e605..c5d30fc7 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/SetInputLayout.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/SetInputLayout.md @@ -1,31 +1,27 @@ # D3D12PipelineState::SetInputLayout -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12PipelineState.h` + +## 签名 ```cpp void SetInputLayout(const InputLayoutDesc& layout) override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12PipelineState.h`，当前页面用于固定 `D3D12PipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `layout` - 参数语义详见头文件声明。 +更新 `m_inputLayoutDesc`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12PipelineState object; - // 根据上下文补齐参数后调用 D3D12PipelineState::SetInputLayout(...)。 - (void)object; -} -``` +- 会更新 `m_inputLayoutDesc`。 +- 当前实现会调用 `clear`、`c_str`、`ToD3D12`、`push_back`。 ## 相关文档 -- [返回类总览](D3D12PipelineState.md) -- [返回模块目录](../D3D12.md) +- [D3D12PipelineState](D3D12PipelineState.md) +- [GetInputLayout](GetInputLayout.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/SetRasterizerState.md b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/SetRasterizerState.md index d7cf4437..07e2b469 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/SetRasterizerState.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/SetRasterizerState.md @@ -1,31 +1,26 @@ # D3D12PipelineState::SetRasterizerState -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12PipelineState.h` + +## 签名 ```cpp void SetRasterizerState(const RasterizerDesc& state) override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12PipelineState.h`，当前页面用于固定 `D3D12PipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `state` - 参数语义详见头文件声明。 +更新 `m_rasterizerDesc`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12PipelineState object; - // 根据上下文补齐参数后调用 D3D12PipelineState::SetRasterizerState(...)。 - (void)object; -} -``` +- 会更新 `m_rasterizerDesc`。 ## 相关文档 -- [返回类总览](D3D12PipelineState.md) -- [返回模块目录](../D3D12.md) +- [D3D12PipelineState](D3D12PipelineState.md) +- [GetRasterizerState](GetRasterizerState.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/SetRenderTargetFormats.md b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/SetRenderTargetFormats.md index 6a4a7587..03a68382 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/SetRenderTargetFormats.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/SetRenderTargetFormats.md @@ -1,33 +1,25 @@ # D3D12PipelineState::SetRenderTargetFormats -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12PipelineState.h` + +## 签名 ```cpp void SetRenderTargetFormats(uint32_t count, const uint32_t* formats, uint32_t depthFormat) override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12PipelineState.h`，当前页面用于固定 `D3D12PipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `count` - 参数语义详见头文件声明。 -- `formats` - 参数语义详见头文件声明。 -- `depthFormat` - 参数语义详见头文件声明。 +执行该公开方法对应的当前实现。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12PipelineState object; - // 根据上下文补齐参数后调用 D3D12PipelineState::SetRenderTargetFormats(...)。 - (void)object; -} -``` +- 会更新 `m_renderTargetCount`、`m_depthStencilFormat`。 ## 相关文档 -- [返回类总览](D3D12PipelineState.md) -- [返回模块目录](../D3D12.md) +- [D3D12PipelineState](D3D12PipelineState.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/SetRootSignature.md b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/SetRootSignature.md index f6861c50..dd2c3ec3 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/SetRootSignature.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/SetRootSignature.md @@ -1,31 +1,26 @@ # D3D12PipelineState::SetRootSignature -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12PipelineState.h` + +## 签名 ```cpp void SetRootSignature(ID3D12RootSignature* rootSignature); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12PipelineState.h`，当前页面用于固定 `D3D12PipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `rootSignature` - 参数语义详见头文件声明。 +更新 `m_rootSignature`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12PipelineState object; - // 根据上下文补齐参数后调用 D3D12PipelineState::SetRootSignature(...)。 - (void)object; -} -``` +- 会更新 `m_rootSignature`。 ## 相关文档 -- [返回类总览](D3D12PipelineState.md) -- [返回模块目录](../D3D12.md) +- [D3D12PipelineState](D3D12PipelineState.md) +- [GetRootSignature](GetRootSignature.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/SetSampleCount.md b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/SetSampleCount.md index 7c5fd872..af48c9ff 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/SetSampleCount.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/SetSampleCount.md @@ -1,31 +1,25 @@ # D3D12PipelineState::SetSampleCount -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12PipelineState.h` + +## 签名 ```cpp void SetSampleCount(uint32_t count) override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12PipelineState.h`，当前页面用于固定 `D3D12PipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `count` - 参数语义详见头文件声明。 +更新 `m_sampleCount`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12PipelineState object; - // 根据上下文补齐参数后调用 D3D12PipelineState::SetSampleCount(...)。 - (void)object; -} -``` +- 会更新 `m_sampleCount`。 ## 相关文档 -- [返回类总览](D3D12PipelineState.md) -- [返回模块目录](../D3D12.md) +- [D3D12PipelineState](D3D12PipelineState.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/SetShaderBytecodes.md b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/SetShaderBytecodes.md index c2caf2bf..4fa9e676 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/SetShaderBytecodes.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/SetShaderBytecodes.md @@ -1,30 +1,25 @@ # D3D12PipelineState::SetShaderBytecodes -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12PipelineState.h` + +## 签名 ```cpp void SetShaderBytecodes(const D3D12_SHADER_BYTECODE& vs, const D3D12_SHADER_BYTECODE& ps, const D3D12_SHADER_BYTECODE& gs =; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12PipelineState.h`，当前页面用于固定 `D3D12PipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行该公开方法对应的当前实现。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12PipelineState object; - // 根据上下文补齐参数后调用 D3D12PipelineState::SetShaderBytecodes(...)。 - (void)object; -} -``` +- 会更新 `m_vsBytecode`、`m_psBytecode`、`m_gsBytecode`。 ## 相关文档 -- [返回类总览](D3D12PipelineState.md) -- [返回模块目录](../D3D12.md) +- [D3D12PipelineState](D3D12PipelineState.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/SetTopology.md b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/SetTopology.md index 1f5a7d1a..2e1d03a4 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/SetTopology.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/SetTopology.md @@ -1,31 +1,25 @@ # D3D12PipelineState::SetTopology -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12PipelineState.h` + +## 签名 ```cpp void SetTopology(uint32_t topologyType) override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12PipelineState.h`，当前页面用于固定 `D3D12PipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `topologyType` - 参数语义详见头文件声明。 +更新 `m_topologyType`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12PipelineState object; - // 根据上下文补齐参数后调用 D3D12PipelineState::SetTopology(...)。 - (void)object; -} -``` +- 会更新 `m_topologyType`。 ## 相关文档 -- [返回类总览](D3D12PipelineState.md) -- [返回模块目录](../D3D12.md) +- [D3D12PipelineState](D3D12PipelineState.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/Shutdown.md b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/Shutdown.md index 9f4435c0..bec80ca4 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/Shutdown.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/Shutdown.md @@ -1,30 +1,27 @@ # D3D12PipelineState::Shutdown -关闭并清理内部状态。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12PipelineState.h` + +## 签名 ```cpp void Shutdown() override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12PipelineState.h`，当前页面用于固定 `D3D12PipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `Reset` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12PipelineState object; - // 根据上下文补齐参数后调用 D3D12PipelineState::Shutdown(...)。 - (void)object; -} -``` +- 会更新 `m_vsBytecode`、`m_psBytecode`、`m_gsBytecode`、`m_csBytecode`。 +- 当前实现会调用 `Reset`。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](D3D12PipelineState.md) -- [返回模块目录](../D3D12.md) +- [D3D12PipelineState](D3D12PipelineState.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/Unbind.md b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/Unbind.md index b2013746..d32e776e 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/Unbind.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12PipelineState/Unbind.md @@ -1,30 +1,25 @@ # D3D12PipelineState::Unbind -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12PipelineState.h` + +## 签名 ```cpp void Unbind() override; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12PipelineState.h`，当前页面用于固定 `D3D12PipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +当前实现为空。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12PipelineState object; - // 根据上下文补齐参数后调用 D3D12PipelineState::Unbind(...)。 - (void)object; -} -``` +- 当前函数体为空。 ## 相关文档 -- [返回类总览](D3D12PipelineState.md) -- [返回模块目录](../D3D12.md) +- [D3D12PipelineState](D3D12PipelineState.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/Constructor.md b/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/Constructor.md index f218195e..fb75cbb2 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/Constructor.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/Constructor.md @@ -1,28 +1,25 @@ # D3D12RootSignature::D3D12RootSignature() -构造对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12RootSignature.h` + +## 签名 ```cpp D3D12RootSignature(); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12RootSignature.h`，当前页面用于固定 `D3D12RootSignature` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +当前实现为空。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12RootSignature object; -} -``` +- 当前函数体为空。 ## 相关文档 -- [返回类总览](D3D12RootSignature.md) -- [返回模块目录](../D3D12.md) +- [D3D12RootSignature](D3D12RootSignature.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/Create32BitConstants.md b/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/Create32BitConstants.md index dbf44f87..fe7ca2fa 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/Create32BitConstants.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/Create32BitConstants.md @@ -1,34 +1,25 @@ # D3D12RootSignature::Create32BitConstants -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12RootSignature.h` + +## 签名 ```cpp static D3D12_ROOT_PARAMETER Create32BitConstants(uint32_t shaderRegister, uint32_t num32BitValues, ShaderVisibility visibility = ShaderVisibility::All, uint32_t registerSpace = 0); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12RootSignature.h`，当前页面用于固定 `D3D12RootSignature` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `shaderRegister` - 参数语义详见头文件声明。 -- `num32BitValues` - 参数语义详见头文件声明。 -- `visibility` - 参数语义详见头文件声明。 -- `registerSpace` - 参数语义详见头文件声明。 +执行 `ToD3D12(...)` 相关流程。 -**返回：** `D3D12_ROOT_PARAMETER` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12RootSignature object; - // 根据上下文补齐参数后调用 D3D12RootSignature::Create32BitConstants(...)。 - (void)object; -} -``` +- 当前实现会调用 `ToD3D12`。 ## 相关文档 -- [返回类总览](D3D12RootSignature.md) -- [返回模块目录](../D3D12.md) +- [D3D12RootSignature](D3D12RootSignature.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/CreateCBV.md b/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/CreateCBV.md index ce66c504..6e4bf501 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/CreateCBV.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/CreateCBV.md @@ -1,33 +1,25 @@ # D3D12RootSignature::CreateCBV -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12RootSignature.h` + +## 签名 ```cpp static D3D12_ROOT_PARAMETER CreateCBV(uint32_t shaderRegister, ShaderVisibility visibility = ShaderVisibility::All, uint32_t registerSpace = 0); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12RootSignature.h`，当前页面用于固定 `D3D12RootSignature` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `shaderRegister` - 参数语义详见头文件声明。 -- `visibility` - 参数语义详见头文件声明。 -- `registerSpace` - 参数语义详见头文件声明。 +执行 `ToD3D12(...)` 相关流程。 -**返回：** `D3D12_ROOT_PARAMETER` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12RootSignature object; - // 根据上下文补齐参数后调用 D3D12RootSignature::CreateCBV(...)。 - (void)object; -} -``` +- 当前实现会调用 `ToD3D12`。 ## 相关文档 -- [返回类总览](D3D12RootSignature.md) -- [返回模块目录](../D3D12.md) +- [D3D12RootSignature](D3D12RootSignature.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/CreateDesc.md b/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/CreateDesc.md index 40af1bc9..6912d1f9 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/CreateDesc.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/CreateDesc.md @@ -1,35 +1,25 @@ # D3D12RootSignature::CreateDesc -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12RootSignature.h` + +## 签名 ```cpp static D3D12_ROOT_SIGNATURE_DESC CreateDesc( D3D12_ROOT_PARAMETER* parameters, uint32_t parameterCount, D3D12_STATIC_SAMPLER_DESC* samplers = nullptr, uint32_t samplerCount = 0, D3D12_ROOT_SIGNATURE_FLAGS flags = D3D12_ROOT_SIGNATURE_FLAG_ALLOW_INPUT_ASSEMBLER_INPUT_LAYOUT); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12RootSignature.h`，当前页面用于固定 `D3D12RootSignature` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `parameters` - 参数语义详见头文件声明。 -- `parameterCount` - 参数语义详见头文件声明。 -- `samplers` - 参数语义详见头文件声明。 -- `samplerCount` - 参数语义详见头文件声明。 -- `flags` - 参数语义详见头文件声明。 +返回 `desc`。 -**返回：** `D3D12_ROOT_SIGNATURE_DESC` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12RootSignature object; - // 根据上下文补齐参数后调用 D3D12RootSignature::CreateDesc(...)。 - (void)object; -} -``` +- 返回 `desc`。 ## 相关文档 -- [返回类总览](D3D12RootSignature.md) -- [返回模块目录](../D3D12.md) +- [D3D12RootSignature](D3D12RootSignature.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/CreateDescriptorRange.md b/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/CreateDescriptorRange.md index 2038efec..a99b0293 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/CreateDescriptorRange.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/CreateDescriptorRange.md @@ -1,34 +1,25 @@ # D3D12RootSignature::CreateDescriptorRange -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12RootSignature.h` + +## 签名 ```cpp static D3D12_DESCRIPTOR_RANGE CreateDescriptorRange(D3D12_DESCRIPTOR_RANGE_TYPE type, uint32_t baseShaderRegister, uint32_t numDescriptors, uint32_t registerSpace = 0); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12RootSignature.h`，当前页面用于固定 `D3D12RootSignature` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `type` - 参数语义详见头文件声明。 -- `baseShaderRegister` - 参数语义详见头文件声明。 -- `numDescriptors` - 参数语义详见头文件声明。 -- `registerSpace` - 参数语义详见头文件声明。 +返回 `range`。 -**返回：** `D3D12_DESCRIPTOR_RANGE` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12RootSignature object; - // 根据上下文补齐参数后调用 D3D12RootSignature::CreateDescriptorRange(...)。 - (void)object; -} -``` +- 返回 `range`。 ## 相关文档 -- [返回类总览](D3D12RootSignature.md) -- [返回模块目录](../D3D12.md) +- [D3D12RootSignature](D3D12RootSignature.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/CreateDescriptorTable.md b/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/CreateDescriptorTable.md index 5a3402cd..3691e263 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/CreateDescriptorTable.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/CreateDescriptorTable.md @@ -1,33 +1,25 @@ # D3D12RootSignature::CreateDescriptorTable -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12RootSignature.h` + +## 签名 ```cpp static D3D12_ROOT_PARAMETER CreateDescriptorTable(uint32_t numRanges, const D3D12_DESCRIPTOR_RANGE* ranges, ShaderVisibility visibility = ShaderVisibility::All); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12RootSignature.h`，当前页面用于固定 `D3D12RootSignature` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `numRanges` - 参数语义详见头文件声明。 -- `ranges` - 参数语义详见头文件声明。 -- `visibility` - 参数语义详见头文件声明。 +执行 `ToD3D12(...)` 相关流程。 -**返回：** `D3D12_ROOT_PARAMETER` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12RootSignature object; - // 根据上下文补齐参数后调用 D3D12RootSignature::CreateDescriptorTable(...)。 - (void)object; -} -``` +- 当前实现会调用 `ToD3D12`。 ## 相关文档 -- [返回类总览](D3D12RootSignature.md) -- [返回模块目录](../D3D12.md) +- [D3D12RootSignature](D3D12RootSignature.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/CreateSRV.md b/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/CreateSRV.md index 6992f235..29c91afa 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/CreateSRV.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/CreateSRV.md @@ -1,33 +1,25 @@ # D3D12RootSignature::CreateSRV -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12RootSignature.h` + +## 签名 ```cpp static D3D12_ROOT_PARAMETER CreateSRV(uint32_t shaderRegister, ShaderVisibility visibility = ShaderVisibility::All, uint32_t registerSpace = 0); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12RootSignature.h`，当前页面用于固定 `D3D12RootSignature` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `shaderRegister` - 参数语义详见头文件声明。 -- `visibility` - 参数语义详见头文件声明。 -- `registerSpace` - 参数语义详见头文件声明。 +执行 `ToD3D12(...)` 相关流程。 -**返回：** `D3D12_ROOT_PARAMETER` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12RootSignature object; - // 根据上下文补齐参数后调用 D3D12RootSignature::CreateSRV(...)。 - (void)object; -} -``` +- 当前实现会调用 `ToD3D12`。 ## 相关文档 -- [返回类总览](D3D12RootSignature.md) -- [返回模块目录](../D3D12.md) +- [D3D12RootSignature](D3D12RootSignature.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/CreateSamplerDesc.md b/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/CreateSamplerDesc.md index eaab7bca..c4b626eb 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/CreateSamplerDesc.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/CreateSamplerDesc.md @@ -1,33 +1,25 @@ # D3D12RootSignature::CreateSamplerDesc -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12RootSignature.h` + +## 签名 ```cpp static D3D12_SAMPLER_DESC CreateSamplerDesc(FilterMode filter, TextureAddressMode address, float maxLOD = D3D12_FLOAT32_MAX); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12RootSignature.h`，当前页面用于固定 `D3D12RootSignature` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `filter` - 参数语义详见头文件声明。 -- `address` - 参数语义详见头文件声明。 -- `maxLOD` - 参数语义详见头文件声明。 +返回 `desc`。 -**返回：** `D3D12_SAMPLER_DESC` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12RootSignature object; - // 根据上下文补齐参数后调用 D3D12RootSignature::CreateSamplerDesc(...)。 - (void)object; -} -``` +- 当前实现会调用 `ToD3D12`。 ## 相关文档 -- [返回类总览](D3D12RootSignature.md) -- [返回模块目录](../D3D12.md) +- [D3D12RootSignature](D3D12RootSignature.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/CreateStaticSampler.md b/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/CreateStaticSampler.md index b3903eca..5d6e8175 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/CreateStaticSampler.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/CreateStaticSampler.md @@ -1,33 +1,25 @@ # D3D12RootSignature::CreateStaticSampler -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12RootSignature.h` + +## 签名 ```cpp static D3D12_STATIC_SAMPLER_DESC CreateStaticSampler(uint32_t shaderRegister, const D3D12_SAMPLER_DESC& desc, ShaderVisibility visibility = ShaderVisibility::Pixel); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12RootSignature.h`，当前页面用于固定 `D3D12RootSignature` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `shaderRegister` - 参数语义详见头文件声明。 -- `desc` - 参数语义详见头文件声明。 -- `visibility` - 参数语义详见头文件声明。 +执行 `ToD3D12(...)` 相关流程。 -**返回：** `D3D12_STATIC_SAMPLER_DESC` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12RootSignature object; - // 根据上下文补齐参数后调用 D3D12RootSignature::CreateStaticSampler(...)。 - (void)object; -} -``` +- 当前实现会调用 `ToD3D12`。 ## 相关文档 -- [返回类总览](D3D12RootSignature.md) -- [返回模块目录](../D3D12.md) +- [D3D12RootSignature](D3D12RootSignature.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/CreateUAV.md b/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/CreateUAV.md index 02c0118a..31b0ba78 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/CreateUAV.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/CreateUAV.md @@ -1,33 +1,25 @@ # D3D12RootSignature::CreateUAV -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12RootSignature.h` + +## 签名 ```cpp static D3D12_ROOT_PARAMETER CreateUAV(uint32_t shaderRegister, ShaderVisibility visibility = ShaderVisibility::All, uint32_t registerSpace = 0); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12RootSignature.h`，当前页面用于固定 `D3D12RootSignature` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `shaderRegister` - 参数语义详见头文件声明。 -- `visibility` - 参数语义详见头文件声明。 -- `registerSpace` - 参数语义详见头文件声明。 +执行 `ToD3D12(...)` 相关流程。 -**返回：** `D3D12_ROOT_PARAMETER` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12RootSignature object; - // 根据上下文补齐参数后调用 D3D12RootSignature::CreateUAV(...)。 - (void)object; -} -``` +- 当前实现会调用 `ToD3D12`。 ## 相关文档 -- [返回类总览](D3D12RootSignature.md) -- [返回模块目录](../D3D12.md) +- [D3D12RootSignature](D3D12RootSignature.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/D3D12RootSignature.md b/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/D3D12RootSignature.md index 1e094736..77bdd29c 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/D3D12RootSignature.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/D3D12RootSignature.md @@ -6,38 +6,44 @@ **头文件**: `XCEngine/RHI/D3D12/D3D12RootSignature.h` -**描述**: 定义 `XCEngine/RHI/D3D12` 子目录中的 `D3D12RootSignature` public API。 +**描述**: D3D12 root signature 封装，负责管理 `ID3D12RootSignature` 生命周期，并提供 root parameter / sampler / range 构造 helper。 ## 概述 -`D3D12RootSignature.h` 是 `XCEngine/RHI/D3D12` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。 +`D3D12RootSignature` 是对 `ID3D12RootSignature` 的薄封装。按头文件和实现约定，它既负责保存 / 释放实际 root signature 对象，也提供一批静态 helper，用来拼装： + +- root parameter 描述 +- descriptor table +- static sampler +- descriptor range +- 整体 `D3D12_ROOT_SIGNATURE_DESC` ## 声明概览 | 声明 | 类型 | 说明 | |------|------|------| -| `D3D12RootSignature` | `class` | 头文件中的公开声明。 | +| `D3D12RootSignature` | `class` | `ID3D12RootSignature` 生命周期与描述构造封装。 | ## 公共方法 | 方法 | 描述 | |------|------| -| [D3D12RootSignature()](Constructor.md) | 构造对象。 | -| [~D3D12RootSignature()](Destructor.md) | 销毁对象并释放相关资源。 | -| [Initialize](Initialize.md) | 初始化内部状态。 | -| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 | -| [GetRootSignature](GetRootSignature.md) | 获取相关状态或对象。 | -| [GetNativeHandle](GetNativeHandle.md) | 获取相关状态或对象。 | -| [GetParameterCount](GetParameterCount.md) | 获取相关状态或对象。 | -| [CreateDesc](CreateDesc.md) | 创建新对象或资源。 | -| [CreateCBV](CreateCBV.md) | 创建新对象或资源。 | -| [CreateSRV](CreateSRV.md) | 创建新对象或资源。 | -| [CreateUAV](CreateUAV.md) | 创建新对象或资源。 | -| [Create32BitConstants](Create32BitConstants.md) | 创建新对象或资源。 | -| [CreateDescriptorTable](CreateDescriptorTable.md) | 创建新对象或资源。 | -| [CreateStaticSampler](CreateStaticSampler.md) | 创建新对象或资源。 | -| [CreateSamplerDesc](CreateSamplerDesc.md) | 创建新对象或资源。 | -| [CreateDescriptorRange](CreateDescriptorRange.md) | 创建新对象或资源。 | +| [D3D12RootSignature()](Constructor.md) | 当前实现为空。 | +| [~D3D12RootSignature()](Destructor.md) | 执行 `Shutdown(...)` 相关流程。 | +| [Initialize](Initialize.md) | 更新 `m_parameterCount`。 | +| [Shutdown](Shutdown.md) | 更新 `m_rootSignature`。 | +| [GetRootSignature](GetRootSignature.md) | 更新 `m_rootSignature`。 | +| [GetNativeHandle](GetNativeHandle.md) | 更新 `m_rootSignature`。 | +| [GetParameterCount](GetParameterCount.md) | 返回 `m_parameterCount` 当前值。 | +| [CreateDesc](CreateDesc.md) | 返回 `desc`。 | +| [CreateCBV](CreateCBV.md) | 执行 `ToD3D12(...)` 相关流程。 | +| [CreateSRV](CreateSRV.md) | 执行 `ToD3D12(...)` 相关流程。 | +| [CreateUAV](CreateUAV.md) | 执行 `ToD3D12(...)` 相关流程。 | +| [Create32BitConstants](Create32BitConstants.md) | 执行 `ToD3D12(...)` 相关流程。 | +| [CreateDescriptorTable](CreateDescriptorTable.md) | 执行 `ToD3D12(...)` 相关流程。 | +| [CreateStaticSampler](CreateStaticSampler.md) | 执行 `ToD3D12(...)` 相关流程。 | +| [CreateSamplerDesc](CreateSamplerDesc.md) | 返回 `desc`。 | +| [CreateDescriptorRange](CreateDescriptorRange.md) | 返回 `range`。 | ## 相关文档 diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/Destructor.md b/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/Destructor.md index c1e1daa2..8b667283 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/Destructor.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/Destructor.md @@ -1,29 +1,25 @@ # D3D12RootSignature::~D3D12RootSignature() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12RootSignature.h` + +## 签名 ```cpp ~D3D12RootSignature(); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12RootSignature.h`，当前页面用于固定 `D3D12RootSignature` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `Shutdown(...)` 相关流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12RootSignature object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 当前实现会调用 `Shutdown`。 ## 相关文档 -- [返回类总览](D3D12RootSignature.md) -- [返回模块目录](../D3D12.md) +- [D3D12RootSignature](D3D12RootSignature.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/GetNativeHandle.md b/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/GetNativeHandle.md index 64ffe654..9f5acd7a 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/GetNativeHandle.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/GetNativeHandle.md @@ -1,30 +1,25 @@ # D3D12RootSignature::GetNativeHandle -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12RootSignature.h` + +## 签名 ```cpp void* GetNativeHandle() const; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12RootSignature.h`，当前页面用于固定 `D3D12RootSignature` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_rootSignature`。 -**返回：** `void*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12RootSignature object; - // 根据上下文补齐参数后调用 D3D12RootSignature::GetNativeHandle(...)。 - (void)object; -} -``` +- 会更新 `m_rootSignature`。 ## 相关文档 -- [返回类总览](D3D12RootSignature.md) -- [返回模块目录](../D3D12.md) +- [D3D12RootSignature](D3D12RootSignature.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/GetParameterCount.md b/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/GetParameterCount.md index 5943d487..038eaf85 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/GetParameterCount.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/GetParameterCount.md @@ -1,30 +1,25 @@ # D3D12RootSignature::GetParameterCount -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12RootSignature.h` + +## 签名 ```cpp uint32_t GetParameterCount() const; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12RootSignature.h`，当前页面用于固定 `D3D12RootSignature` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_parameterCount` 当前值。 -**返回：** `uint32_t` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12RootSignature object; - // 根据上下文补齐参数后调用 D3D12RootSignature::GetParameterCount(...)。 - (void)object; -} -``` +- 返回 `m_parameterCount` 当前值。 ## 相关文档 -- [返回类总览](D3D12RootSignature.md) -- [返回模块目录](../D3D12.md) +- [D3D12RootSignature](D3D12RootSignature.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/GetRootSignature.md b/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/GetRootSignature.md index e644e77e..d4758d91 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/GetRootSignature.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/GetRootSignature.md @@ -1,30 +1,25 @@ # D3D12RootSignature::GetRootSignature -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12RootSignature.h` + +## 签名 ```cpp ID3D12RootSignature* GetRootSignature() const; ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12RootSignature.h`，当前页面用于固定 `D3D12RootSignature` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_rootSignature`。 -**返回：** `ID3D12RootSignature*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12RootSignature object; - // 根据上下文补齐参数后调用 D3D12RootSignature::GetRootSignature(...)。 - (void)object; -} -``` +- 会更新 `m_rootSignature`。 ## 相关文档 -- [返回类总览](D3D12RootSignature.md) -- [返回模块目录](../D3D12.md) +- [D3D12RootSignature](D3D12RootSignature.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/Initialize.md b/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/Initialize.md index c8962e00..276f5b84 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/Initialize.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/Initialize.md @@ -1,32 +1,28 @@ # D3D12RootSignature::Initialize -初始化内部状态。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12RootSignature.h` + +## 签名 ```cpp bool Initialize(ID3D12Device* device, const D3D12_ROOT_SIGNATURE_DESC& desc); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12RootSignature.h`，当前页面用于固定 `D3D12RootSignature` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `device` - 参数语义详见头文件声明。 -- `desc` - 参数语义详见头文件声明。 +更新 `m_parameterCount`。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12RootSignature object; - // 根据上下文补齐参数后调用 D3D12RootSignature::Initialize(...)。 - (void)object; -} -``` +- 会更新 `m_parameterCount`。 +- 当前实现会调用 `D3D12SerializeRootSignature`、`FAILED`、`Release`、`CreateRootSignature`、`GetBufferPointer`。 +- 包含条件分支，并可能提前返回。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](D3D12RootSignature.md) -- [返回模块目录](../D3D12.md) +- [D3D12RootSignature](D3D12RootSignature.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/Shutdown.md b/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/Shutdown.md index ccd73d4c..661fe8ba 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/Shutdown.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12RootSignature/Shutdown.md @@ -1,30 +1,26 @@ # D3D12RootSignature::Shutdown -关闭并清理内部状态。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/D3D12/D3D12RootSignature.h` + +## 签名 ```cpp void Shutdown(); ``` -该方法声明于 `XCEngine/RHI/D3D12/D3D12RootSignature.h`，当前页面用于固定 `D3D12RootSignature` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_rootSignature`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::D3D12RootSignature object; - // 根据上下文补齐参数后调用 D3D12RootSignature::Shutdown(...)。 - (void)object; -} -``` +- 会更新 `m_rootSignature`。 +- 当前实现会调用 `Reset`。 ## 相关文档 -- [返回类总览](D3D12RootSignature.md) -- [返回模块目录](../D3D12.md) +- [D3D12RootSignature](D3D12RootSignature.md) diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Types/D3D12Types.md b/docs/api/XCEngine/RHI/D3D12/D3D12Types/D3D12Types.md index 35b5ca59..7eeb5a28 100644 --- a/docs/api/XCEngine/RHI/D3D12/D3D12Types/D3D12Types.md +++ b/docs/api/XCEngine/RHI/D3D12/D3D12Types/D3D12Types.md @@ -6,11 +6,18 @@ **头文件**: `XCEngine/RHI/D3D12/D3D12Types.h` -**描述**: 定义 `XCEngine/RHI/D3D12` 子目录中的 `D3D12Types` public API。 +**描述**: D3D12 类型转换辅助头，提供把通用 RHI 描述转换成原生 D3D12 结构体的内联函数。 ## 概述 -`D3D12Types.h` 是 `XCEngine/RHI/D3D12` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。 +`D3D12Types.h` 不是独立系统，而是一组轻量转换 helper。当前头文件主要负责把引擎通用 RHI 数据结构转换成 D3D12 原生描述，例如： + +- `Viewport` / `Rect` 到 `D3D12_VIEWPORT` / `D3D12_RECT` +- `ClearValue` 到颜色或深度模板 `D3D12_CLEAR_VALUE` +- `TextureDesc` / `BufferDesc` 到 `D3D12_RESOURCE_DESC` +- `DescriptorHeapDesc` / `CommandQueueDesc` 到对应的 D3D12 描述结构 + +这些函数都是 `inline`，主要被 D3D12 后端在创建资源和命令对象时复用。 ## 相关文档 diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/Clear.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/Clear.md index 6faa7886..09f0a2a2 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/Clear.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/Clear.md @@ -1,35 +1,25 @@ # OpenGLCommandList::Clear -清空内部数据。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLCommandList.h` + +## 签名 ```cpp void Clear(float r, float g, float b, float a, uint32_t buffers) override; ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandList.h`，当前页面用于固定 `OpenGLCommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `r` - 参数语义详见头文件声明。 -- `g` - 参数语义详见头文件声明。 -- `b` - 参数语义详见头文件声明。 -- `a` - 参数语义详见头文件声明。 -- `buffers` - 参数语义详见头文件声明。 +执行 `glClearColor`、`glClear`、`ToOpenGLClearBuffer` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::Clear(...)。 - (void)object; -} -``` +- 当前实现会调用 `glClearColor`、`glClear`、`ToOpenGLClearBuffer`。 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLCommandList](OpenGLCommandList.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/ClearColor.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/ClearColor.md index d03b6deb..208d035e 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/ClearColor.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/ClearColor.md @@ -1,34 +1,25 @@ # OpenGLCommandList::ClearColor -清空内部数据。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLCommandList.h` + +## 签名 ```cpp void ClearColor(float r, float g, float b, float a); ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandList.h`，当前页面用于固定 `OpenGLCommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `r` - 参数语义详见头文件声明。 -- `g` - 参数语义详见头文件声明。 -- `b` - 参数语义详见头文件声明。 -- `a` - 参数语义详见头文件声明。 +执行 `glClearColor`、`glClear` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::ClearColor(...)。 - (void)object; -} -``` +- 当前实现会调用 `glClearColor`、`glClear`。 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLCommandList](OpenGLCommandList.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/ClearDepth.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/ClearDepth.md index b8c749cb..cee04caa 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/ClearDepth.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/ClearDepth.md @@ -1,31 +1,25 @@ # OpenGLCommandList::ClearDepth -清空内部数据。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLCommandList.h` + +## 签名 ```cpp void ClearDepth(float depth); ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandList.h`，当前页面用于固定 `OpenGLCommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `depth` - 参数语义详见头文件声明。 +执行 `glClearDepth`、`glClear` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::ClearDepth(...)。 - (void)object; -} -``` +- 当前实现会调用 `glClearDepth`、`glClear`。 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLCommandList](OpenGLCommandList.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/ClearDepthStencil.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/ClearDepthStencil.md index ff2b4cbd..d56460ab 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/ClearDepthStencil.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/ClearDepthStencil.md @@ -1,47 +1,28 @@ # OpenGLCommandList::ClearDepthStencil -清空内部数据。 +**命名空间**: `XCEngine::RHI` -该方法在 `XCEngine/RHI/OpenGL/OpenGLCommandList.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。 +**类型**: `method` -## 重载 1: 声明 +**头文件**: `XCEngine/RHI/OpenGL/OpenGLCommandList.h` + +## 签名 ```cpp void ClearDepthStencil(float depth, int stencil); +void ClearDepthStencil( RHIResourceView* depthStencil, float depth, uint8_t stencil, uint32_t rectCount = 0, const Rect* rects = nullptr) override; ``` -**参数：** -- `depth` - 参数语义详见头文件声明。 -- `stencil` - 参数语义详见头文件声明。 +## 作用 -**返回：** `void` - 无返回值。 +执行 `glClearDepth`、`glClearStencil`、`glClear` 协同流程。 -## 重载 2: 声明 +## 当前实现 -```cpp -void ClearDepthStencil(RHIResourceView* depthStencil, float depth, uint8_t stencil) override; -``` - -**参数：** -- `depthStencil` - 参数语义详见头文件声明。 -- `depth` - 参数语义详见头文件声明。 -- `stencil` - 参数语义详见头文件声明。 - -**返回：** `void` - 无返回值。 - -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::ClearDepthStencil(...)。 - (void)object; -} -``` +- 当前实现会调用 `glClearDepth`、`glClearStencil`、`glClear`。 +- 当前实现会调用 `IsValid`、`glIsEnabled`、`glGetIntegerv`、`glGetBooleanv`。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLCommandList](OpenGLCommandList.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/ClearRenderTarget.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/ClearRenderTarget.md index d960736f..7a42dcbd 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/ClearRenderTarget.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/ClearRenderTarget.md @@ -1,32 +1,26 @@ # OpenGLCommandList::ClearRenderTarget -清空内部数据。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLCommandList.h` + +## 签名 ```cpp -void ClearRenderTarget(RHIResourceView* renderTarget, const float color[4]) override; +void ClearRenderTarget( RHIResourceView* renderTarget, const float color[4], uint32_t rectCount = 0, const Rect* rects = nullptr) override; ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandList.h`，当前页面用于固定 `OpenGLCommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `renderTarget` - 参数语义详见头文件声明。 -- `param` - 参数语义详见头文件声明。 +执行 `IsValid`、`glIsEnabled`、`glGetIntegerv` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::ClearRenderTarget(...)。 - (void)object; -} -``` +- 当前实现会调用 `IsValid`、`glIsEnabled`、`glGetIntegerv`、`glGetBooleanv`。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLCommandList](OpenGLCommandList.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/ClearStencil.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/ClearStencil.md index 2c45ceb8..66e96ad1 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/ClearStencil.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/ClearStencil.md @@ -1,31 +1,25 @@ # OpenGLCommandList::ClearStencil -清空内部数据。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLCommandList.h` + +## 签名 ```cpp void ClearStencil(int stencil); ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandList.h`，当前页面用于固定 `OpenGLCommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `stencil` - 参数语义详见头文件声明。 +执行 `glClearStencil`、`glClear` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::ClearStencil(...)。 - (void)object; -} -``` +- 当前实现会调用 `glClearStencil`、`glClear`。 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLCommandList](OpenGLCommandList.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/Constructor.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/Constructor.md index 5a51736e..5b44b4ea 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/Constructor.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/Constructor.md @@ -1,28 +1,25 @@ # OpenGLCommandList::OpenGLCommandList() -构造对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLCommandList.h` + +## 签名 ```cpp OpenGLCommandList(); ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandList.h`，当前页面用于固定 `OpenGLCommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +构造 `OpenGLCommandList` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLCommandList object; -} -``` +- 具体定义位于 `engine/src/RHI/OpenGL/OpenGLCommandList.cpp`。 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLCommandList](OpenGLCommandList.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/Destructor.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/Destructor.md index 6a41143a..cf4d6edd 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/Destructor.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/Destructor.md @@ -1,29 +1,25 @@ # OpenGLCommandList::~OpenGLCommandList() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLCommandList.h` + +## 签名 ```cpp ~OpenGLCommandList() override; ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandList.h`，当前页面用于固定 `OpenGLCommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +当前实现为空。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 当前函数体为空。 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLCommandList](OpenGLCommandList.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/GetQueryObjectiv.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/GetQueryObjectiv.md index f19bc0b5..ffb98280 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/GetQueryObjectiv.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/GetQueryObjectiv.md @@ -1,33 +1,25 @@ # OpenGLCommandList::GetQueryObjectiv -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLCommandList.h` + +## 签名 ```cpp void GetQueryObjectiv(unsigned int id, unsigned int pname, int* params); ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandList.h`，当前页面用于固定 `OpenGLCommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `id` - 参数语义详见头文件声明。 -- `pname` - 参数语义详见头文件声明。 -- `params` - 参数语义详见头文件声明。 +执行 `glGetQueryObjectiv(...)` 相关流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::GetQueryObjectiv(...)。 - (void)object; -} -``` +- 当前实现会调用 `glGetQueryObjectiv`。 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLCommandList](OpenGLCommandList.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/GetQueryObjectuiv.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/GetQueryObjectuiv.md index feec2dc3..5cc3f76a 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/GetQueryObjectuiv.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/GetQueryObjectuiv.md @@ -1,33 +1,25 @@ # OpenGLCommandList::GetQueryObjectuiv -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLCommandList.h` + +## 签名 ```cpp void GetQueryObjectuiv(unsigned int id, unsigned int pname, unsigned int* params); ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandList.h`，当前页面用于固定 `OpenGLCommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `id` - 参数语义详见头文件声明。 -- `pname` - 参数语义详见头文件声明。 -- `params` - 参数语义详见头文件声明。 +执行 `glGetQueryObjectuiv(...)` 相关流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::GetQueryObjectuiv(...)。 - (void)object; -} -``` +- 当前实现会调用 `glGetQueryObjectuiv`。 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLCommandList](OpenGLCommandList.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetBlendColor.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetBlendColor.md index 3780e67e..419b24a5 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetBlendColor.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetBlendColor.md @@ -1,34 +1,25 @@ # OpenGLCommandList::SetBlendColor -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLCommandList.h` + +## 签名 ```cpp void SetBlendColor(float r, float g, float b, float a); ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandList.h`，当前页面用于固定 `OpenGLCommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `r` - 参数语义详见头文件声明。 -- `g` - 参数语义详见头文件声明。 -- `b` - 参数语义详见头文件声明。 -- `a` - 参数语义详见头文件声明。 +执行 `glBlendColor(...)` 相关流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::SetBlendColor(...)。 - (void)object; -} -``` +- 当前实现会调用 `glBlendColor`。 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLCommandList](OpenGLCommandList.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetBlendEquation.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetBlendEquation.md index 13bbde76..aed3b29c 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetBlendEquation.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetBlendEquation.md @@ -1,31 +1,25 @@ # OpenGLCommandList::SetBlendEquation -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLCommandList.h` + +## 签名 ```cpp void SetBlendEquation(unsigned int mode); ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandList.h`，当前页面用于固定 `OpenGLCommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `mode` - 参数语义详见头文件声明。 +执行 `glBlendEquation(...)` 相关流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::SetBlendEquation(...)。 - (void)object; -} -``` +- 当前实现会调用 `glBlendEquation`。 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLCommandList](OpenGLCommandList.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetBlendFactor.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetBlendFactor.md index 186433a5..370cc6f5 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetBlendFactor.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetBlendFactor.md @@ -1,31 +1,25 @@ # OpenGLCommandList::SetBlendFactor -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLCommandList.h` + +## 签名 ```cpp void SetBlendFactor(const float factor[4]) override; ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandList.h`，当前页面用于固定 `OpenGLCommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `param` - 参数语义详见头文件声明。 +执行 `glBlendColor(...)` 相关流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::SetBlendFactor(...)。 - (void)object; -} -``` +- 当前实现会调用 `glBlendColor`。 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLCommandList](OpenGLCommandList.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetBlendFunc.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetBlendFunc.md index 5165b972..dc6911f1 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetBlendFunc.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetBlendFunc.md @@ -1,32 +1,25 @@ # OpenGLCommandList::SetBlendFunc -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLCommandList.h` + +## 签名 ```cpp void SetBlendFunc(unsigned int src, unsigned int dst); ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandList.h`，当前页面用于固定 `OpenGLCommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `src` - 参数语义详见头文件声明。 -- `dst` - 参数语义详见头文件声明。 +执行 `glBlendFunc(...)` 相关流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::SetBlendFunc(...)。 - (void)object; -} -``` +- 当前实现会调用 `glBlendFunc`。 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLCommandList](OpenGLCommandList.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetBlendFuncSeparate.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetBlendFuncSeparate.md index f39be590..9b352282 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetBlendFuncSeparate.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetBlendFuncSeparate.md @@ -1,34 +1,25 @@ # OpenGLCommandList::SetBlendFuncSeparate -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLCommandList.h` + +## 签名 ```cpp void SetBlendFuncSeparate(unsigned int srcRGB, unsigned int dstRGB, unsigned int srcAlpha, unsigned int dstAlpha); ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandList.h`，当前页面用于固定 `OpenGLCommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `srcRGB` - 参数语义详见头文件声明。 -- `dstRGB` - 参数语义详见头文件声明。 -- `srcAlpha` - 参数语义详见头文件声明。 -- `dstAlpha` - 参数语义详见头文件声明。 +执行 `glBlendFuncSeparate(...)` 相关流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::SetBlendFuncSeparate(...)。 - (void)object; -} -``` +- 当前实现会调用 `glBlendFuncSeparate`。 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLCommandList](OpenGLCommandList.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetCullFace.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetCullFace.md index 69ed3040..42a98c3d 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetCullFace.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetCullFace.md @@ -1,31 +1,25 @@ # OpenGLCommandList::SetCullFace -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLCommandList.h` + +## 签名 ```cpp void SetCullFace(unsigned int face); ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandList.h`，当前页面用于固定 `OpenGLCommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `face` - 参数语义详见头文件声明。 +执行 `glCullFace(...)` 相关流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::SetCullFace(...)。 - (void)object; -} -``` +- 当前实现会调用 `glCullFace`。 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLCommandList](OpenGLCommandList.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetDepthFunc.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetDepthFunc.md index 19bab3e0..e030dafd 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetDepthFunc.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetDepthFunc.md @@ -1,31 +1,25 @@ # OpenGLCommandList::SetDepthFunc -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLCommandList.h` + +## 签名 ```cpp void SetDepthFunc(unsigned int func); ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandList.h`，当前页面用于固定 `OpenGLCommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `func` - 参数语义详见头文件声明。 +执行 `glDepthFunc(...)` 相关流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::SetDepthFunc(...)。 - (void)object; -} -``` +- 当前实现会调用 `glDepthFunc`。 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLCommandList](OpenGLCommandList.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetFrontFace.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetFrontFace.md index c72085aa..f7c04ba0 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetFrontFace.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetFrontFace.md @@ -1,31 +1,25 @@ # OpenGLCommandList::SetFrontFace -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLCommandList.h` + +## 签名 ```cpp void SetFrontFace(unsigned int face); ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandList.h`，当前页面用于固定 `OpenGLCommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `face` - 参数语义详见头文件声明。 +执行 `glFrontFace(...)` 相关流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::SetFrontFace(...)。 - (void)object; -} -``` +- 当前实现会调用 `glFrontFace`。 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLCommandList](OpenGLCommandList.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetPipelineState.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetPipelineState.md index 0c427aec..7844b904 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetPipelineState.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetPipelineState.md @@ -1,31 +1,27 @@ # OpenGLCommandList::SetPipelineState -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLCommandList.h` + +## 签名 ```cpp void SetPipelineState(RHIPipelineState* pipelineState) override; ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandList.h`，当前页面用于固定 `OpenGLCommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `pipelineState` - 参数语义详见头文件声明。 +更新 `m_currentPipelineState`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::SetPipelineState(...)。 - (void)object; -} -``` +- 会更新 `m_currentPipelineState`。 +- 当前实现会调用 `Bind`。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLCommandList](OpenGLCommandList.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetPolygonMode.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetPolygonMode.md index 3c639971..5c0401e1 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetPolygonMode.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetPolygonMode.md @@ -1,31 +1,25 @@ # OpenGLCommandList::SetPolygonMode -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLCommandList.h` + +## 签名 ```cpp void SetPolygonMode(unsigned int mode); ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandList.h`，当前页面用于固定 `OpenGLCommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `mode` - 参数语义详见头文件声明。 +执行 `glPolygonMode(...)` 相关流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::SetPolygonMode(...)。 - (void)object; -} -``` +- 当前实现会调用 `glPolygonMode`。 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLCommandList](OpenGLCommandList.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetPolygonOffset.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetPolygonOffset.md index 7818a951..d260a793 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetPolygonOffset.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetPolygonOffset.md @@ -1,32 +1,25 @@ # OpenGLCommandList::SetPolygonOffset -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLCommandList.h` + +## 签名 ```cpp void SetPolygonOffset(float factor, float units); ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandList.h`，当前页面用于固定 `OpenGLCommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `factor` - 参数语义详见头文件声明。 -- `units` - 参数语义详见头文件声明。 +执行 `glPolygonOffset(...)` 相关流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::SetPolygonOffset(...)。 - (void)object; -} -``` +- 当前实现会调用 `glPolygonOffset`。 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLCommandList](OpenGLCommandList.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetPrimitiveTopology.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetPrimitiveTopology.md index fcb8ad65..3faa66e6 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetPrimitiveTopology.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetPrimitiveTopology.md @@ -1,31 +1,26 @@ # OpenGLCommandList::SetPrimitiveTopology -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLCommandList.h` + +## 签名 ```cpp void SetPrimitiveTopology(PrimitiveTopology topology) override; ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandList.h`，当前页面用于固定 `OpenGLCommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `topology` - 参数语义详见头文件声明。 +更新 `m_primitiveType`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::SetPrimitiveTopology(...)。 - (void)object; -} -``` +- 会更新 `m_primitiveType`。 +- 当前实现会调用 `ToOpenGL`。 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLCommandList](OpenGLCommandList.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetPrimitiveType.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetPrimitiveType.md index d40647b5..82fee697 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetPrimitiveType.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetPrimitiveType.md @@ -1,31 +1,26 @@ # OpenGLCommandList::SetPrimitiveType -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLCommandList.h` + +## 签名 ```cpp void SetPrimitiveType(PrimitiveType type); ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandList.h`，当前页面用于固定 `OpenGLCommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `type` - 参数语义详见头文件声明。 +更新 `m_primitiveType`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::SetPrimitiveType(...)。 - (void)object; -} -``` +- 会更新 `m_primitiveType`。 +- 当前实现会调用 `ToOpenGL`。 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLCommandList](OpenGLCommandList.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetScissor.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetScissor.md index 743d3f0f..de1013f8 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetScissor.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetScissor.md @@ -1,34 +1,25 @@ # OpenGLCommandList::SetScissor -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLCommandList.h` + +## 签名 ```cpp void SetScissor(int x, int y, int width, int height); ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandList.h`，当前页面用于固定 `OpenGLCommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `x` - 参数语义详见头文件声明。 -- `y` - 参数语义详见头文件声明。 -- `width` - 参数语义详见头文件声明。 -- `height` - 参数语义详见头文件声明。 +执行 `glScissor(...)` 相关流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::SetScissor(...)。 - (void)object; -} -``` +- 当前实现会调用 `glScissor`。 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLCommandList](OpenGLCommandList.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetScissorRect.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetScissorRect.md index 5b913556..ca66b245 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetScissorRect.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetScissorRect.md @@ -1,31 +1,25 @@ # OpenGLCommandList::SetScissorRect -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLCommandList.h` + +## 签名 ```cpp void SetScissorRect(const Rect& rect) override; ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandList.h`，当前页面用于固定 `OpenGLCommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `rect` - 参数语义详见头文件声明。 +执行 `glScissor(...)` 相关流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::SetScissorRect(...)。 - (void)object; -} -``` +- 当前实现会调用 `glScissor`。 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLCommandList](OpenGLCommandList.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetScissorRects.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetScissorRects.md index 04a49c31..b8fe5d4c 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetScissorRects.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetScissorRects.md @@ -1,46 +1,27 @@ # OpenGLCommandList::SetScissorRects -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` -该方法在 `XCEngine/RHI/OpenGL/OpenGLCommandList.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。 +**类型**: `method` -## 重载 1: 声明 +**头文件**: `XCEngine/RHI/OpenGL/OpenGLCommandList.h` + +## 签名 ```cpp void SetScissorRects(unsigned int count, const int* rects); -``` - -**参数：** -- `count` - 参数语义详见头文件声明。 -- `rects` - 参数语义详见头文件声明。 - -**返回：** `void` - 无返回值。 - -## 重载 2: 声明 - -```cpp void SetScissorRects(uint32_t count, const Rect* rects) override; ``` -**参数：** -- `count` - 参数语义详见头文件声明。 -- `rects` - 参数语义详见头文件声明。 +## 作用 -**返回：** `void` - 无返回值。 +执行 `glScissorIndexed(...)` 相关流程。 -**示例：** +## 当前实现 -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::SetScissorRects(...)。 - (void)object; -} -``` +- 当前实现会调用 `glScissorIndexed`。 +- 当前实现会调用 `scissorGL`、`glScissorArrayv`、`data`。 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLCommandList](OpenGLCommandList.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetShader.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetShader.md index 3ab42d9d..be13b646 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetShader.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetShader.md @@ -1,31 +1,26 @@ # OpenGLCommandList::SetShader -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLCommandList.h` + +## 签名 ```cpp void SetShader(RHIShader* shader) override; ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandList.h`，当前页面用于固定 `OpenGLCommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `shader` - 参数语义详见头文件声明。 +更新 `m_currentShader`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::SetShader(...)。 - (void)object; -} -``` +- 会更新 `m_currentShader`。 +- 当前实现会调用 `UseShader`、`GetID`。 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLCommandList](OpenGLCommandList.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetStencilFunc.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetStencilFunc.md index f4ff45e8..6dcbbde3 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetStencilFunc.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetStencilFunc.md @@ -1,33 +1,25 @@ # OpenGLCommandList::SetStencilFunc -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLCommandList.h` + +## 签名 ```cpp void SetStencilFunc(unsigned int func, int ref, unsigned int mask); ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandList.h`，当前页面用于固定 `OpenGLCommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `func` - 参数语义详见头文件声明。 -- `ref` - 参数语义详见头文件声明。 -- `mask` - 参数语义详见头文件声明。 +执行 `glStencilFunc(...)` 相关流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::SetStencilFunc(...)。 - (void)object; -} -``` +- 当前实现会调用 `glStencilFunc`。 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLCommandList](OpenGLCommandList.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetStencilOp.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetStencilOp.md index fd209037..a398ede8 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetStencilOp.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetStencilOp.md @@ -1,33 +1,25 @@ # OpenGLCommandList::SetStencilOp -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLCommandList.h` + +## 签名 ```cpp void SetStencilOp(unsigned int fail, unsigned int zfail, unsigned int zpass); ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandList.h`，当前页面用于固定 `OpenGLCommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `fail` - 参数语义详见头文件声明。 -- `zfail` - 参数语义详见头文件声明。 -- `zpass` - 参数语义详见头文件声明。 +执行 `glStencilOp(...)` 相关流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::SetStencilOp(...)。 - (void)object; -} -``` +- 当前实现会调用 `glStencilOp`。 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLCommandList](OpenGLCommandList.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetStencilRef.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetStencilRef.md index 6e477a67..ab472891 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetStencilRef.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetStencilRef.md @@ -1,31 +1,25 @@ # OpenGLCommandList::SetStencilRef -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLCommandList.h` + +## 签名 ```cpp void SetStencilRef(uint8_t ref) override; ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandList.h`，当前页面用于固定 `OpenGLCommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `ref` - 参数语义详见头文件声明。 +执行 `glStencilFunc(...)` 相关流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::SetStencilRef(...)。 - (void)object; -} -``` +- 当前实现会调用 `glStencilFunc`。 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLCommandList](OpenGLCommandList.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniform1f.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniform1f.md index 7b61377e..0c130e2d 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniform1f.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniform1f.md @@ -1,32 +1,25 @@ # OpenGLCommandList::SetUniform1f -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLCommandList.h` + +## 签名 ```cpp void SetUniform1f(int location, float v); ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandList.h`，当前页面用于固定 `OpenGLCommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `location` - 参数语义详见头文件声明。 -- `v` - 参数语义详见头文件声明。 +执行 `glUniform1f(...)` 相关流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::SetUniform1f(...)。 - (void)object; -} -``` +- 当前实现会调用 `glUniform1f`。 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLCommandList](OpenGLCommandList.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniform1fv.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniform1fv.md index 5e76d5d8..bf111baa 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniform1fv.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniform1fv.md @@ -1,33 +1,25 @@ # OpenGLCommandList::SetUniform1fv -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLCommandList.h` + +## 签名 ```cpp void SetUniform1fv(int location, int count, const float* v); ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandList.h`，当前页面用于固定 `OpenGLCommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `location` - 参数语义详见头文件声明。 -- `count` - 参数语义详见头文件声明。 -- `v` - 参数语义详见头文件声明。 +执行 `glUniform1fv(...)` 相关流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::SetUniform1fv(...)。 - (void)object; -} -``` +- 当前实现会调用 `glUniform1fv`。 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLCommandList](OpenGLCommandList.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniform1i.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniform1i.md index 36057344..61776f95 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniform1i.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniform1i.md @@ -1,32 +1,25 @@ # OpenGLCommandList::SetUniform1i -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLCommandList.h` + +## 签名 ```cpp void SetUniform1i(int location, int v); ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandList.h`，当前页面用于固定 `OpenGLCommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `location` - 参数语义详见头文件声明。 -- `v` - 参数语义详见头文件声明。 +执行 `glUniform1i(...)` 相关流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::SetUniform1i(...)。 - (void)object; -} -``` +- 当前实现会调用 `glUniform1i`。 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLCommandList](OpenGLCommandList.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniform2f.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniform2f.md index 5b1d2603..e0683438 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniform2f.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniform2f.md @@ -1,33 +1,25 @@ # OpenGLCommandList::SetUniform2f -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLCommandList.h` + +## 签名 ```cpp void SetUniform2f(int location, float x, float y); ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandList.h`，当前页面用于固定 `OpenGLCommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `location` - 参数语义详见头文件声明。 -- `x` - 参数语义详见头文件声明。 -- `y` - 参数语义详见头文件声明。 +执行 `glUniform2f(...)` 相关流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::SetUniform2f(...)。 - (void)object; -} -``` +- 当前实现会调用 `glUniform2f`。 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLCommandList](OpenGLCommandList.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniform2fv.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniform2fv.md index 96b85af5..acf2a7fb 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniform2fv.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniform2fv.md @@ -1,33 +1,25 @@ # OpenGLCommandList::SetUniform2fv -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLCommandList.h` + +## 签名 ```cpp void SetUniform2fv(int location, int count, const float* v); ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandList.h`，当前页面用于固定 `OpenGLCommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `location` - 参数语义详见头文件声明。 -- `count` - 参数语义详见头文件声明。 -- `v` - 参数语义详见头文件声明。 +执行 `glUniform2fv(...)` 相关流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::SetUniform2fv(...)。 - (void)object; -} -``` +- 当前实现会调用 `glUniform2fv`。 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLCommandList](OpenGLCommandList.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniform3f.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniform3f.md index 2cf95968..a20874ca 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniform3f.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniform3f.md @@ -1,34 +1,25 @@ # OpenGLCommandList::SetUniform3f -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLCommandList.h` + +## 签名 ```cpp void SetUniform3f(int location, float x, float y, float z); ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandList.h`，当前页面用于固定 `OpenGLCommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `location` - 参数语义详见头文件声明。 -- `x` - 参数语义详见头文件声明。 -- `y` - 参数语义详见头文件声明。 -- `z` - 参数语义详见头文件声明。 +执行 `glUniform3f(...)` 相关流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::SetUniform3f(...)。 - (void)object; -} -``` +- 当前实现会调用 `glUniform3f`。 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLCommandList](OpenGLCommandList.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniform3fv.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniform3fv.md index 74dbb8c9..0cc7688e 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniform3fv.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniform3fv.md @@ -1,33 +1,25 @@ # OpenGLCommandList::SetUniform3fv -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLCommandList.h` + +## 签名 ```cpp void SetUniform3fv(int location, int count, const float* v); ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandList.h`，当前页面用于固定 `OpenGLCommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `location` - 参数语义详见头文件声明。 -- `count` - 参数语义详见头文件声明。 -- `v` - 参数语义详见头文件声明。 +执行 `glUniform3fv(...)` 相关流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::SetUniform3fv(...)。 - (void)object; -} -``` +- 当前实现会调用 `glUniform3fv`。 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLCommandList](OpenGLCommandList.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniform4f.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniform4f.md index 3a41274c..d5c9ee36 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniform4f.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniform4f.md @@ -1,35 +1,25 @@ # OpenGLCommandList::SetUniform4f -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLCommandList.h` + +## 签名 ```cpp void SetUniform4f(int location, float x, float y, float z, float w); ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandList.h`，当前页面用于固定 `OpenGLCommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `location` - 参数语义详见头文件声明。 -- `x` - 参数语义详见头文件声明。 -- `y` - 参数语义详见头文件声明。 -- `z` - 参数语义详见头文件声明。 -- `w` - 参数语义详见头文件声明。 +执行 `glUniform4f(...)` 相关流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::SetUniform4f(...)。 - (void)object; -} -``` +- 当前实现会调用 `glUniform4f`。 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLCommandList](OpenGLCommandList.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniform4fv.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniform4fv.md index 83d31e90..ea15ca83 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniform4fv.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniform4fv.md @@ -1,33 +1,25 @@ # OpenGLCommandList::SetUniform4fv -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLCommandList.h` + +## 签名 ```cpp void SetUniform4fv(int location, int count, const float* v); ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandList.h`，当前页面用于固定 `OpenGLCommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `location` - 参数语义详见头文件声明。 -- `count` - 参数语义详见头文件声明。 -- `v` - 参数语义详见头文件声明。 +执行 `glUniform4fv(...)` 相关流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::SetUniform4fv(...)。 - (void)object; -} -``` +- 当前实现会调用 `glUniform4fv`。 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLCommandList](OpenGLCommandList.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniformFloat.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniformFloat.md index e91dcced..425e72e9 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniformFloat.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniformFloat.md @@ -1,32 +1,25 @@ # OpenGLCommandList::SetUniformFloat -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLCommandList.h` + +## 签名 ```cpp void SetUniformFloat(const char* name, float value); ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandList.h`，当前页面用于固定 `OpenGLCommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `name` - 参数语义详见头文件声明。 -- `value` - 参数语义详见头文件声明。 +执行 `glUniform1f`、`glGetUniformLocation`、`GetID` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::SetUniformFloat(...)。 - (void)object; -} -``` +- 当前实现会调用 `glUniform1f`、`glGetUniformLocation`、`GetID`。 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLCommandList](OpenGLCommandList.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniformInt.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniformInt.md index 1f760740..13d50a2d 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniformInt.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniformInt.md @@ -1,32 +1,25 @@ # OpenGLCommandList::SetUniformInt -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLCommandList.h` + +## 签名 ```cpp void SetUniformInt(const char* name, int value); ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandList.h`，当前页面用于固定 `OpenGLCommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `name` - 参数语义详见头文件声明。 -- `value` - 参数语义详见头文件声明。 +执行 `glUniform1i`、`glGetUniformLocation`、`GetID` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::SetUniformInt(...)。 - (void)object; -} -``` +- 当前实现会调用 `glUniform1i`、`glGetUniformLocation`、`GetID`。 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLCommandList](OpenGLCommandList.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniformMat4.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniformMat4.md index 8b350b3b..b432511a 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniformMat4.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniformMat4.md @@ -1,32 +1,25 @@ # OpenGLCommandList::SetUniformMat4 -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLCommandList.h` + +## 签名 ```cpp void SetUniformMat4(const char* name, const float* value); ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandList.h`，当前页面用于固定 `OpenGLCommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `name` - 参数语义详见头文件声明。 -- `value` - 参数语义详见头文件声明。 +执行 `glUniformMatrix4fv`、`glGetUniformLocation`、`GetID` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::SetUniformMat4(...)。 - (void)object; -} -``` +- 当前实现会调用 `glUniformMatrix4fv`、`glGetUniformLocation`、`GetID`。 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLCommandList](OpenGLCommandList.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniformMatrix4fv.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniformMatrix4fv.md index 9997a5fa..1c961ec1 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniformMatrix4fv.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniformMatrix4fv.md @@ -1,34 +1,25 @@ # OpenGLCommandList::SetUniformMatrix4fv -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLCommandList.h` + +## 签名 ```cpp void SetUniformMatrix4fv(int location, int count, bool transpose, const float* v); ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandList.h`，当前页面用于固定 `OpenGLCommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `location` - 参数语义详见头文件声明。 -- `count` - 参数语义详见头文件声明。 -- `transpose` - 参数语义详见头文件声明。 -- `v` - 参数语义详见头文件声明。 +执行 `glUniformMatrix4fv(...)` 相关流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::SetUniformMatrix4fv(...)。 - (void)object; -} -``` +- 当前实现会调用 `glUniformMatrix4fv`。 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLCommandList](OpenGLCommandList.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniformVec3.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniformVec3.md index cf09b8b5..08caa47e 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniformVec3.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniformVec3.md @@ -1,34 +1,25 @@ # OpenGLCommandList::SetUniformVec3 -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLCommandList.h` + +## 签名 ```cpp void SetUniformVec3(const char* name, float x, float y, float z); ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandList.h`，当前页面用于固定 `OpenGLCommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `name` - 参数语义详见头文件声明。 -- `x` - 参数语义详见头文件声明。 -- `y` - 参数语义详见头文件声明。 -- `z` - 参数语义详见头文件声明。 +执行 `glUniform3f`、`glGetUniformLocation`、`GetID` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::SetUniformVec3(...)。 - (void)object; -} -``` +- 当前实现会调用 `glUniform3f`、`glGetUniformLocation`、`GetID`。 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLCommandList](OpenGLCommandList.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniformVec4.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniformVec4.md index c2b5230b..2ce8cfc8 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniformVec4.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetUniformVec4.md @@ -1,35 +1,25 @@ # OpenGLCommandList::SetUniformVec4 -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLCommandList.h` + +## 签名 ```cpp void SetUniformVec4(const char* name, float x, float y, float z, float w); ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandList.h`，当前页面用于固定 `OpenGLCommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `name` - 参数语义详见头文件声明。 -- `x` - 参数语义详见头文件声明。 -- `y` - 参数语义详见头文件声明。 -- `z` - 参数语义详见头文件声明。 -- `w` - 参数语义详见头文件声明。 +执行 `glUniform4f`、`glGetUniformLocation`、`GetID` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::SetUniformVec4(...)。 - (void)object; -} -``` +- 当前实现会调用 `glUniform4f`、`glGetUniformLocation`、`GetID`。 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLCommandList](OpenGLCommandList.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetVertexBuffer.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetVertexBuffer.md index 6f896377..b1a5baef 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetVertexBuffer.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetVertexBuffer.md @@ -1,33 +1,25 @@ # OpenGLCommandList::SetVertexBuffer -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLCommandList.h` + +## 签名 ```cpp void SetVertexBuffer(unsigned int buffer, size_t offset, size_t stride); ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandList.h`，当前页面用于固定 `OpenGLCommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `buffer` - 参数语义详见头文件声明。 -- `offset` - 参数语义详见头文件声明。 -- `stride` - 参数语义详见头文件声明。 +执行 `glBindBuffer`、`glVertexAttribPointer`、`glEnableVertexAttribArray` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::SetVertexBuffer(...)。 - (void)object; -} -``` +- 当前实现会调用 `glBindBuffer`、`glVertexAttribPointer`、`glEnableVertexAttribArray`。 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLCommandList](OpenGLCommandList.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetViewport.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetViewport.md index 57a6b48f..38f52bc9 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetViewport.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetViewport.md @@ -1,63 +1,28 @@ # OpenGLCommandList::SetViewport -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` -该方法在 `XCEngine/RHI/OpenGL/OpenGLCommandList.h` 中提供了 3 个重载，当前页面统一汇总这些公开声明。 +**类型**: `method` -## 重载 1: 声明 +**头文件**: `XCEngine/RHI/OpenGL/OpenGLCommandList.h` + +## 签名 ```cpp void SetViewport(int x, int y, int width, int height); -``` - -**参数：** -- `x` - 参数语义详见头文件声明。 -- `y` - 参数语义详见头文件声明。 -- `width` - 参数语义详见头文件声明。 -- `height` - 参数语义详见头文件声明。 - -**返回：** `void` - 无返回值。 - -## 重载 2: 声明 - -```cpp void SetViewport(float x, float y, float width, float height, float minDepth, float maxDepth); -``` - -**参数：** -- `x` - 参数语义详见头文件声明。 -- `y` - 参数语义详见头文件声明。 -- `width` - 参数语义详见头文件声明。 -- `height` - 参数语义详见头文件声明。 -- `minDepth` - 参数语义详见头文件声明。 -- `maxDepth` - 参数语义详见头文件声明。 - -**返回：** `void` - 无返回值。 - -## 重载 3: 声明 - -```cpp void SetViewport(const Viewport& viewport) override; ``` -**参数：** -- `viewport` - 参数语义详见头文件声明。 +## 作用 -**返回：** `void` - 无返回值。 +执行 `glViewport(...)` 相关流程。 -**示例：** +## 当前实现 -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::SetViewport(...)。 - (void)object; -} -``` +- 当前实现会调用 `glViewport`。 +- 当前实现会调用 `glViewportIndexedf`、`glDepthRange`。 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLCommandList](OpenGLCommandList.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetViewports.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetViewports.md index 7e7244ee..754dc2df 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetViewports.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/SetViewports.md @@ -1,46 +1,27 @@ # OpenGLCommandList::SetViewports -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` -该方法在 `XCEngine/RHI/OpenGL/OpenGLCommandList.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。 +**类型**: `method` -## 重载 1: 声明 +**头文件**: `XCEngine/RHI/OpenGL/OpenGLCommandList.h` + +## 签名 ```cpp void SetViewports(unsigned int count, const float* viewports); -``` - -**参数：** -- `count` - 参数语义详见头文件声明。 -- `viewports` - 参数语义详见头文件声明。 - -**返回：** `void` - 无返回值。 - -## 重载 2: 声明 - -```cpp void SetViewports(uint32_t count, const Viewport* viewports) override; ``` -**参数：** -- `count` - 参数语义详见头文件声明。 -- `viewports` - 参数语义详见头文件声明。 +## 作用 -**返回：** `void` - 无返回值。 +执行 `glViewportIndexedf`、`glDepthRangeIndexed` 协同流程。 -**示例：** +## 当前实现 -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::SetViewports(...)。 - (void)object; -} -``` +- 当前实现会调用 `glViewportIndexedf`、`glDepthRangeIndexed`。 +- 当前实现会调用 `viewportsGL`、`glViewportArrayv`、`data`。 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLCommandList](OpenGLCommandList.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/Shutdown.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/Shutdown.md index bcc47c60..9b7035b6 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/Shutdown.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLCommandList/Shutdown.md @@ -1,30 +1,27 @@ # OpenGLCommandList::Shutdown -关闭并清理内部状态。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLCommandList.h` + +## 签名 ```cpp void Shutdown() override; ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLCommandList.h`，当前页面用于固定 `OpenGLCommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `ReleaseComposedFramebuffer`、`DisableConfiguredVertexAttributes`、`glDeleteVertexArrays` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLCommandList object; - // 根据上下文补齐参数后调用 OpenGLCommandList::Shutdown(...)。 - (void)object; -} -``` +- 会更新 `m_internalVAO`、`m_currentPipelineState`、`m_currentShader`、`m_currentRenderTargetWidth`。 +- 当前实现会调用 `ReleaseComposedFramebuffer`、`DisableConfiguredVertexAttributes`、`glDeleteVertexArrays`。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](OpenGLCommandList.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLCommandList](OpenGLCommandList.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/Constructor.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/Constructor.md index dceadf7e..af132f5a 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/Constructor.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/Constructor.md @@ -1,28 +1,25 @@ # OpenGLDevice::OpenGLDevice() -构造对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLDevice.h` + +## 签名 ```cpp OpenGLDevice(); ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDevice.h`，当前页面用于固定 `OpenGLDevice` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +构造 `OpenGLDevice` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLDevice object; -} -``` +- 具体定义位于 `engine/src/RHI/OpenGL/OpenGLDevice.cpp`。 ## 相关文档 -- [返回类总览](OpenGLDevice.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLDevice](OpenGLDevice.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateBuffer.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateBuffer.md index e7f291eb..d31e1992 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateBuffer.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateBuffer.md @@ -1,31 +1,26 @@ # OpenGLDevice::CreateBuffer -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLDevice.h` + +## 签名 ```cpp RHIBuffer* CreateBuffer(const BufferDesc& desc) override; ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDevice.h`，当前页面用于固定 `OpenGLDevice` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `desc` - 参数语义详见头文件声明。 +返回 `buffer`。 -**返回：** `RHIBuffer*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLDevice object; - // 根据上下文补齐参数后调用 OpenGLDevice::CreateBuffer(...)。 - (void)object; -} -``` +- 当前实现会调用 `OpenGLBuffer`、`Initialize`、`SetStride`。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](OpenGLDevice.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLDevice](OpenGLDevice.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateCommandList.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateCommandList.md index 60bf9161..1f450ae4 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateCommandList.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateCommandList.md @@ -1,31 +1,25 @@ # OpenGLDevice::CreateCommandList -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLDevice.h` + +## 签名 ```cpp RHICommandList* CreateCommandList(const CommandListDesc& desc) override; ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDevice.h`，当前页面用于固定 `OpenGLDevice` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `desc` - 参数语义详见头文件声明。 +执行 `OpenGLCommandList(...)` 相关流程。 -**返回：** `RHICommandList*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLDevice object; - // 根据上下文补齐参数后调用 OpenGLDevice::CreateCommandList(...)。 - (void)object; -} -``` +- 当前实现会调用 `OpenGLCommandList`。 ## 相关文档 -- [返回类总览](OpenGLDevice.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLDevice](OpenGLDevice.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateCommandQueue.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateCommandQueue.md index 8bf1118f..ccc4de57 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateCommandQueue.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateCommandQueue.md @@ -1,31 +1,25 @@ # OpenGLDevice::CreateCommandQueue -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLDevice.h` + +## 签名 ```cpp RHICommandQueue* CreateCommandQueue(const CommandQueueDesc& desc) override; ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDevice.h`，当前页面用于固定 `OpenGLDevice` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `desc` - 参数语义详见头文件声明。 +执行 `OpenGLCommandQueue(...)` 相关流程。 -**返回：** `RHICommandQueue*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLDevice object; - // 根据上下文补齐参数后调用 OpenGLDevice::CreateCommandQueue(...)。 - (void)object; -} -``` +- 当前实现会调用 `OpenGLCommandQueue`。 ## 相关文档 -- [返回类总览](OpenGLDevice.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLDevice](OpenGLDevice.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateDepthStencilView.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateDepthStencilView.md index 61bda328..8ac6d5f8 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateDepthStencilView.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateDepthStencilView.md @@ -1,32 +1,27 @@ # OpenGLDevice::CreateDepthStencilView -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLDevice.h` + +## 签名 ```cpp RHIResourceView* CreateDepthStencilView(RHITexture* texture, const ResourceViewDesc& desc) override; ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDevice.h`，当前页面用于固定 `OpenGLDevice` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `texture` - 参数语义详见头文件声明。 -- `desc` - 参数语义详见头文件声明。 +执行 `GetWidth`、`GetHeight`、`GetID` 协同流程。 -**返回：** `RHIResourceView*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLDevice object; - // 根据上下文补齐参数后调用 OpenGLDevice::CreateDepthStencilView(...)。 - (void)object; -} -``` +- 当前实现会调用 `GetWidth`、`GetHeight`、`GetID`、`ResolveFramebufferTextureTarget`、`GetOpenGLType`。 +- 包含条件分支，并可能提前返回。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](OpenGLDevice.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLDevice](OpenGLDevice.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateDescriptorPool.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateDescriptorPool.md index 9edaa98c..2ad7803b 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateDescriptorPool.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateDescriptorPool.md @@ -1,31 +1,28 @@ # OpenGLDevice::CreateDescriptorPool -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLDevice.h` + +## 签名 ```cpp RHIDescriptorPool* CreateDescriptorPool(const DescriptorPoolDesc& desc) override; ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDevice.h`，当前页面用于固定 `OpenGLDevice` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `desc` - 参数语义详见头文件声明。 +更新 `m_textureUnitAllocator`。 -**返回：** `RHIDescriptorPool*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLDevice object; - // 根据上下文补齐参数后调用 OpenGLDevice::CreateDescriptorPool(...)。 - (void)object; -} -``` +- 会更新 `m_textureUnitAllocator`。 +- 当前实现会调用 `OpenGLDescriptorPool`、`Initialize`、`SetTextureUnitAllocator`、`get`。 +- 包含条件分支，并可能提前返回。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](OpenGLDevice.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLDevice](OpenGLDevice.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateDescriptorSet.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateDescriptorSet.md index 619c6ea6..c2401738 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateDescriptorSet.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateDescriptorSet.md @@ -1,32 +1,27 @@ # OpenGLDevice::CreateDescriptorSet -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLDevice.h` + +## 签名 ```cpp RHIDescriptorSet* CreateDescriptorSet(RHIDescriptorPool* pool, const DescriptorSetLayoutDesc& layout) override; ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDevice.h`，当前页面用于固定 `OpenGLDevice` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `pool` - 参数语义详见头文件声明。 -- `layout` - 参数语义详见头文件声明。 +执行 `AllocateSet` 协同流程。 -**返回：** `RHIDescriptorSet*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLDevice object; - // 根据上下文补齐参数后调用 OpenGLDevice::CreateDescriptorSet(...)。 - (void)object; -} -``` +- 当前实现会调用 `AllocateSet`。 +- 包含条件分支，并可能提前返回。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](OpenGLDevice.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLDevice](OpenGLDevice.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateFence.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateFence.md index 36ad9713..6a166902 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateFence.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateFence.md @@ -1,31 +1,25 @@ # OpenGLDevice::CreateFence -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLDevice.h` + +## 签名 ```cpp RHIFence* CreateFence(const FenceDesc& desc) override; ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDevice.h`，当前页面用于固定 `OpenGLDevice` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `desc` - 参数语义详见头文件声明。 +返回 `fence`。 -**返回：** `RHIFence*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLDevice object; - // 根据上下文补齐参数后调用 OpenGLDevice::CreateFence(...)。 - (void)object; -} -``` +- 当前实现会调用 `OpenGLFence`、`Initialize`。 ## 相关文档 -- [返回类总览](OpenGLDevice.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLDevice](OpenGLDevice.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateFramebuffer.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateFramebuffer.md index ea69dd55..6bf4534e 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateFramebuffer.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateFramebuffer.md @@ -1,36 +1,27 @@ # OpenGLDevice::CreateFramebuffer -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLDevice.h` + +## 签名 ```cpp RHIFramebuffer* CreateFramebuffer( class RHIRenderPass* renderPass, uint32_t width, uint32_t height, uint32_t colorAttachmentCount, RHIResourceView** colorAttachments, RHIResourceView* depthStencilAttachment) override; ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDevice.h`，当前页面用于固定 `OpenGLDevice` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `renderPass` - 参数语义详见头文件声明。 -- `width` - 参数语义详见头文件声明。 -- `height` - 参数语义详见头文件声明。 -- `colorAttachmentCount` - 参数语义详见头文件声明。 -- `colorAttachments` - 参数语义详见头文件声明。 -- `depthStencilAttachment` - 参数语义详见头文件声明。 +执行 `OpenGLFramebuffer`、`Initialize` 协同流程。 -**返回：** `RHIFramebuffer*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLDevice object; - // 根据上下文补齐参数后调用 OpenGLDevice::CreateFramebuffer(...)。 - (void)object; -} -``` +- 当前实现会调用 `OpenGLFramebuffer`、`Initialize`。 +- 包含条件分支，并可能提前返回。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](OpenGLDevice.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLDevice](OpenGLDevice.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateIndexBufferView.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateIndexBufferView.md index 57c2c7a9..f8408fc0 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateIndexBufferView.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateIndexBufferView.md @@ -1,32 +1,27 @@ # OpenGLDevice::CreateIndexBufferView -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLDevice.h` + +## 签名 ```cpp RHIResourceView* CreateIndexBufferView(RHIBuffer* buffer, const ResourceViewDesc& desc) override; ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDevice.h`，当前页面用于固定 `OpenGLDevice` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `buffer` - 参数语义详见头文件声明。 -- `desc` - 参数语义详见头文件声明。 +执行 `OpenGLResourceView`、`InitializeAsIndexBuffer` 协同流程。 -**返回：** `RHIResourceView*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLDevice object; - // 根据上下文补齐参数后调用 OpenGLDevice::CreateIndexBufferView(...)。 - (void)object; -} -``` +- 当前实现会调用 `OpenGLResourceView`、`InitializeAsIndexBuffer`。 +- 包含条件分支，并可能提前返回。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](OpenGLDevice.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLDevice](OpenGLDevice.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreatePipelineLayout.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreatePipelineLayout.md index cff4b994..5014da0f 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreatePipelineLayout.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreatePipelineLayout.md @@ -1,31 +1,27 @@ # OpenGLDevice::CreatePipelineLayout -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLDevice.h` + +## 签名 ```cpp RHIPipelineLayout* CreatePipelineLayout(const RHIPipelineLayoutDesc& desc) override; ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDevice.h`，当前页面用于固定 `OpenGLDevice` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `desc` - 参数语义详见头文件声明。 +执行 `OpenGLPipelineLayout`、`Initialize` 协同流程。 -**返回：** `RHIPipelineLayout*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLDevice object; - // 根据上下文补齐参数后调用 OpenGLDevice::CreatePipelineLayout(...)。 - (void)object; -} -``` +- 当前实现会调用 `OpenGLPipelineLayout`、`Initialize`。 +- 包含条件分支，并可能提前返回。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](OpenGLDevice.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLDevice](OpenGLDevice.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateRenderPass.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateRenderPass.md index 765d98d1..bea926af 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateRenderPass.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateRenderPass.md @@ -1,33 +1,27 @@ # OpenGLDevice::CreateRenderPass -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLDevice.h` + +## 签名 ```cpp RHIRenderPass* CreateRenderPass( uint32_t colorAttachmentCount, const AttachmentDesc* colorAttachments, const AttachmentDesc* depthStencilAttachment) override; ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDevice.h`，当前页面用于固定 `OpenGLDevice` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `colorAttachmentCount` - 参数语义详见头文件声明。 -- `colorAttachments` - 参数语义详见头文件声明。 -- `depthStencilAttachment` - 参数语义详见头文件声明。 +执行 `OpenGLRenderPass`、`Initialize` 协同流程。 -**返回：** `RHIRenderPass*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLDevice object; - // 根据上下文补齐参数后调用 OpenGLDevice::CreateRenderPass(...)。 - (void)object; -} -``` +- 当前实现会调用 `OpenGLRenderPass`、`Initialize`。 +- 包含条件分支，并可能提前返回。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](OpenGLDevice.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLDevice](OpenGLDevice.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateRenderTargetView.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateRenderTargetView.md index 21297d9d..08259e39 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateRenderTargetView.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateRenderTargetView.md @@ -1,32 +1,27 @@ # OpenGLDevice::CreateRenderTargetView -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLDevice.h` + +## 签名 ```cpp RHIResourceView* CreateRenderTargetView(RHITexture* texture, const ResourceViewDesc& desc) override; ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDevice.h`，当前页面用于固定 `OpenGLDevice` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `texture` - 参数语义详见头文件声明。 -- `desc` - 参数语义详见头文件声明。 +执行 `GetWidth`、`GetHeight`、`GetID` 协同流程。 -**返回：** `RHIResourceView*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLDevice object; - // 根据上下文补齐参数后调用 OpenGLDevice::CreateRenderTargetView(...)。 - (void)object; -} -``` +- 当前实现会调用 `GetWidth`、`GetHeight`、`GetID`、`ResolveFramebufferTextureTarget`、`GetOpenGLType`。 +- 包含条件分支，并可能提前返回。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](OpenGLDevice.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLDevice](OpenGLDevice.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateSampler.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateSampler.md index 4d5f050b..03d675b5 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateSampler.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateSampler.md @@ -1,31 +1,27 @@ # OpenGLDevice::CreateSampler -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLDevice.h` + +## 签名 ```cpp RHISampler* CreateSampler(const SamplerDesc& desc) override; ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDevice.h`，当前页面用于固定 `OpenGLDevice` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `desc` - 参数语义详见头文件声明。 +执行 `OpenGLSampler`、`ToOpenGLSamplerDesc`、`Initialize` 协同流程。 -**返回：** `RHISampler*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLDevice object; - // 根据上下文补齐参数后调用 OpenGLDevice::CreateSampler(...)。 - (void)object; -} -``` +- 当前实现会调用 `OpenGLSampler`、`ToOpenGLSamplerDesc`、`Initialize`。 +- 包含条件分支，并可能提前返回。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](OpenGLDevice.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLDevice](OpenGLDevice.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateShaderResourceView.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateShaderResourceView.md index 24eb81d6..14df5096 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateShaderResourceView.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateShaderResourceView.md @@ -1,32 +1,28 @@ # OpenGLDevice::CreateShaderResourceView -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLDevice.h` + +## 签名 ```cpp RHIResourceView* CreateShaderResourceView(RHITexture* texture, const ResourceViewDesc& desc) override; ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDevice.h`，当前页面用于固定 `OpenGLDevice` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `texture` - 参数语义详见头文件声明。 -- `desc` - 参数语义详见头文件声明。 +更新 `m_textureUnitAllocator`。 -**返回：** `RHIResourceView*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLDevice object; - // 根据上下文补齐参数后调用 OpenGLDevice::CreateShaderResourceView(...)。 - (void)object; -} -``` +- 会更新 `m_textureUnitAllocator`。 +- 当前实现会调用 `OpenGLResourceView`、`InitializeAsShaderResource`、`get`。 +- 包含条件分支，并可能提前返回。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](OpenGLDevice.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLDevice](OpenGLDevice.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateSwapChain.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateSwapChain.md index 698cba33..4a08d5c4 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateSwapChain.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateSwapChain.md @@ -1,32 +1,27 @@ # OpenGLDevice::CreateSwapChain -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLDevice.h` + +## 签名 ```cpp RHISwapChain* CreateSwapChain(const SwapChainDesc& desc, RHICommandQueue* presentQueue) override; ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDevice.h`，当前页面用于固定 `OpenGLDevice` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `desc` - 参数语义详见头文件声明。 -- `presentQueue` - 参数语义详见头文件声明。 +执行 `OpenGLSwapChain`、`InitializeWithExistingWindow`、`Initialize` 协同流程。 -**返回：** `RHISwapChain*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLDevice object; - // 根据上下文补齐参数后调用 OpenGLDevice::CreateSwapChain(...)。 - (void)object; -} -``` +- 当前实现会调用 `OpenGLSwapChain`、`InitializeWithExistingWindow`、`Initialize`。 +- 包含条件分支，并可能提前返回。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](OpenGLDevice.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLDevice](OpenGLDevice.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateUnorderedAccessView.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateUnorderedAccessView.md index d9263e53..a41733c4 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateUnorderedAccessView.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateUnorderedAccessView.md @@ -1,32 +1,28 @@ # OpenGLDevice::CreateUnorderedAccessView -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLDevice.h` + +## 签名 ```cpp RHIResourceView* CreateUnorderedAccessView(RHITexture* texture, const ResourceViewDesc& desc) override; ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDevice.h`，当前页面用于固定 `OpenGLDevice` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `texture` - 参数语义详见头文件声明。 -- `desc` - 参数语义详见头文件声明。 +更新 `m_textureUnitAllocator`。 -**返回：** `RHIResourceView*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLDevice object; - // 根据上下文补齐参数后调用 OpenGLDevice::CreateUnorderedAccessView(...)。 - (void)object; -} -``` +- 会更新 `m_textureUnitAllocator`。 +- 当前实现会调用 `OpenGLResourceView`、`InitializeAsUnorderedAccess`、`get`。 +- 包含条件分支，并可能提前返回。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](OpenGLDevice.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLDevice](OpenGLDevice.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateVertexBufferView.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateVertexBufferView.md index 9e21408b..1154a8de 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateVertexBufferView.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/CreateVertexBufferView.md @@ -1,32 +1,27 @@ # OpenGLDevice::CreateVertexBufferView -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLDevice.h` + +## 签名 ```cpp RHIResourceView* CreateVertexBufferView(RHIBuffer* buffer, const ResourceViewDesc& desc) override; ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDevice.h`，当前页面用于固定 `OpenGLDevice` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `buffer` - 参数语义详见头文件声明。 -- `desc` - 参数语义详见头文件声明。 +执行 `OpenGLResourceView`、`InitializeAsVertexBuffer` 协同流程。 -**返回：** `RHIResourceView*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLDevice object; - // 根据上下文补齐参数后调用 OpenGLDevice::CreateVertexBufferView(...)。 - (void)object; -} -``` +- 当前实现会调用 `OpenGLResourceView`、`InitializeAsVertexBuffer`。 +- 包含条件分支，并可能提前返回。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](OpenGLDevice.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLDevice](OpenGLDevice.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/Destructor.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/Destructor.md index 9a32388c..d6299d67 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/Destructor.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/Destructor.md @@ -1,29 +1,25 @@ # OpenGLDevice::~OpenGLDevice() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLDevice.h` + +## 签名 ```cpp ~OpenGLDevice() override; ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDevice.h`，当前页面用于固定 `OpenGLDevice` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `Shutdown(...)` 相关流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLDevice object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 当前实现会调用 `Shutdown`。 ## 相关文档 -- [返回类总览](OpenGLDevice.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLDevice](OpenGLDevice.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/GetCapabilities.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/GetCapabilities.md index 0c6eb094..5e62e1c6 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/GetCapabilities.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/GetCapabilities.md @@ -1,30 +1,25 @@ # OpenGLDevice::GetCapabilities -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLDevice.h` + +## 签名 ```cpp const RHICapabilities& GetCapabilities() const override; ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDevice.h`，当前页面用于固定 `OpenGLDevice` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_capabilities` 当前值。 -**返回：** `const RHICapabilities&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLDevice object; - // 根据上下文补齐参数后调用 OpenGLDevice::GetCapabilities(...)。 - (void)object; -} -``` +- 返回 `m_capabilities` 当前值。 ## 相关文档 -- [返回类总览](OpenGLDevice.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLDevice](OpenGLDevice.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/GetDeviceInfo.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/GetDeviceInfo.md index ee3b9f62..bb249cbe 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/GetDeviceInfo.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/GetDeviceInfo.md @@ -1,30 +1,25 @@ # OpenGLDevice::GetDeviceInfo -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLDevice.h` + +## 签名 ```cpp const RHIDeviceInfo& GetDeviceInfo() const override; ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDevice.h`，当前页面用于固定 `OpenGLDevice` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_deviceInfo` 当前值。 -**返回：** `const RHIDeviceInfo&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLDevice object; - // 根据上下文补齐参数后调用 OpenGLDevice::GetDeviceInfo(...)。 - (void)object; -} -``` +- 返回 `m_deviceInfo` 当前值。 ## 相关文档 -- [返回类总览](OpenGLDevice.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLDevice](OpenGLDevice.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/GetDeviceInfoImpl.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/GetDeviceInfoImpl.md index 75a57457..6446c6bd 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/GetDeviceInfoImpl.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/GetDeviceInfoImpl.md @@ -1,30 +1,25 @@ # OpenGLDevice::GetDeviceInfoImpl -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLDevice.h` + +## 签名 ```cpp const RHIDeviceInfo& GetDeviceInfoImpl() const; ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDevice.h`，当前页面用于固定 `OpenGLDevice` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_deviceInfo` 当前值。 -**返回：** `const RHIDeviceInfo&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLDevice object; - // 根据上下文补齐参数后调用 OpenGLDevice::GetDeviceInfoImpl(...)。 - (void)object; -} -``` +- 返回 `m_deviceInfo` 当前值。 ## 相关文档 -- [返回类总览](OpenGLDevice.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLDevice](OpenGLDevice.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/GetNativeContext.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/GetNativeContext.md index e432e408..d8d926b7 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/GetNativeContext.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/GetNativeContext.md @@ -1,30 +1,25 @@ # OpenGLDevice::GetNativeContext -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLDevice.h` + +## 签名 ```cpp void* GetNativeContext() const; ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDevice.h`，当前页面用于固定 `OpenGLDevice` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_hglrc` 当前值。 -**返回：** `void*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLDevice object; - // 根据上下文补齐参数后调用 OpenGLDevice::GetNativeContext(...)。 - (void)object; -} -``` +- 返回 `m_hglrc` 当前值。 ## 相关文档 -- [返回类总览](OpenGLDevice.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLDevice](OpenGLDevice.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/GetNativeDevice.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/GetNativeDevice.md index 990bfc6f..4e350a36 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/GetNativeDevice.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/GetNativeDevice.md @@ -1,30 +1,25 @@ # OpenGLDevice::GetNativeDevice -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLDevice.h` + +## 签名 ```cpp void* GetNativeDevice() override; ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDevice.h`，当前页面用于固定 `OpenGLDevice` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_hglrc` 当前值。 -**返回：** `void*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLDevice object; - // 根据上下文补齐参数后调用 OpenGLDevice::GetNativeDevice(...)。 - (void)object; -} -``` +- 返回 `m_hglrc` 当前值。 ## 相关文档 -- [返回类总览](OpenGLDevice.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLDevice](OpenGLDevice.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/GetNativeHandle.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/GetNativeHandle.md index 2f1a39e0..963107cd 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/GetNativeHandle.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/GetNativeHandle.md @@ -1,30 +1,25 @@ # OpenGLDevice::GetNativeHandle -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLDevice.h` + +## 签名 ```cpp void* GetNativeHandle() const; ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDevice.h`，当前页面用于固定 `OpenGLDevice` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_hglrc` 当前值。 -**返回：** `void*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLDevice object; - // 根据上下文补齐参数后调用 OpenGLDevice::GetNativeHandle(...)。 - (void)object; -} -``` +- 返回 `m_hglrc` 当前值。 ## 相关文档 -- [返回类总览](OpenGLDevice.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLDevice](OpenGLDevice.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/Shutdown.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/Shutdown.md index f9d8db53..5c03dfef 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/Shutdown.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLDevice/Shutdown.md @@ -1,30 +1,27 @@ # OpenGLDevice::Shutdown -关闭并清理内部状态。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLDevice.h` + +## 签名 ```cpp void Shutdown() override; ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLDevice.h`，当前页面用于固定 `OpenGLDevice` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `wglMakeCurrent`、`wglDeleteContext`、`ReleaseDC` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLDevice object; - // 根据上下文补齐参数后调用 OpenGLDevice::Shutdown(...)。 - (void)object; -} -``` +- 会更新 `m_hglrc`、`m_hdc`、`m_hwnd`、`m_initialized`。 +- 当前实现会调用 `wglMakeCurrent`、`wglDeleteContext`、`ReleaseDC`、`DestroyOwnedWindow`、`Shutdown`。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](OpenGLDevice.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLDevice](OpenGLDevice.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/GetBlendState.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/GetBlendState.md index 73a91b8d..0e262ede 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/GetBlendState.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/GetBlendState.md @@ -1,30 +1,26 @@ # OpenGLPipelineState::GetBlendState -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLPipelineState.h` + +## 签名 ```cpp const BlendDesc& GetBlendState() const override; ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLPipelineState.h`，当前页面用于固定 `OpenGLPipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_blendDesc` 当前值。 -**返回：** `const BlendDesc&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLPipelineState object; - // 根据上下文补齐参数后调用 OpenGLPipelineState::GetBlendState(...)。 - (void)object; -} -``` +- 返回 `m_blendDesc` 当前值。 ## 相关文档 -- [返回类总览](OpenGLPipelineState.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLPipelineState](OpenGLPipelineState.md) +- [SetBlendState](SetBlendState.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/GetDepthStencilState.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/GetDepthStencilState.md index c5ef5559..adf3c237 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/GetDepthStencilState.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/GetDepthStencilState.md @@ -1,30 +1,26 @@ # OpenGLPipelineState::GetDepthStencilState -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLPipelineState.h` + +## 签名 ```cpp const DepthStencilStateDesc& GetDepthStencilState() const override; ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLPipelineState.h`，当前页面用于固定 `OpenGLPipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_depthStencilDesc` 当前值。 -**返回：** `const DepthStencilStateDesc&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLPipelineState object; - // 根据上下文补齐参数后调用 OpenGLPipelineState::GetDepthStencilState(...)。 - (void)object; -} -``` +- 返回 `m_depthStencilDesc` 当前值。 ## 相关文档 -- [返回类总览](OpenGLPipelineState.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLPipelineState](OpenGLPipelineState.md) +- [SetDepthStencilState](SetDepthStencilState.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/GetInputLayout.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/GetInputLayout.md index 7b9acb46..d9f42ff3 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/GetInputLayout.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/GetInputLayout.md @@ -1,30 +1,26 @@ # OpenGLPipelineState::GetInputLayout -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLPipelineState.h` + +## 签名 ```cpp const InputLayoutDesc& GetInputLayout() const override; ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLPipelineState.h`，当前页面用于固定 `OpenGLPipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_inputLayoutDesc` 当前值。 -**返回：** `const InputLayoutDesc&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLPipelineState object; - // 根据上下文补齐参数后调用 OpenGLPipelineState::GetInputLayout(...)。 - (void)object; -} -``` +- 返回 `m_inputLayoutDesc` 当前值。 ## 相关文档 -- [返回类总览](OpenGLPipelineState.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLPipelineState](OpenGLPipelineState.md) +- [SetInputLayout](SetInputLayout.md) diff --git a/docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/GetRasterizerState.md b/docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/GetRasterizerState.md index c920c6f8..a37d3335 100644 --- a/docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/GetRasterizerState.md +++ b/docs/api/XCEngine/RHI/OpenGL/OpenGLPipelineState/GetRasterizerState.md @@ -1,30 +1,26 @@ # OpenGLPipelineState::GetRasterizerState -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/OpenGL/OpenGLPipelineState.h` + +## 签名 ```cpp const RasterizerDesc& GetRasterizerState() const override; ``` -该方法声明于 `XCEngine/RHI/OpenGL/OpenGLPipelineState.h`，当前页面用于固定 `OpenGLPipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_rasterizerDesc` 当前值。 -**返回：** `const RasterizerDesc&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::OpenGLPipelineState object; - // 根据上下文补齐参数后调用 OpenGLPipelineState::GetRasterizerState(...)。 - (void)object; -} -``` +- 返回 `m_rasterizerDesc` 当前值。 ## 相关文档 -- [返回类总览](OpenGLPipelineState.md) -- [返回模块目录](../OpenGL.md) +- [OpenGLPipelineState](OpenGLPipelineState.md) +- [SetRasterizerState](SetRasterizerState.md) diff --git a/docs/api/XCEngine/RHI/RHIBuffer/Destructor.md b/docs/api/XCEngine/RHI/RHIBuffer/Destructor.md index fd56ea2d..96044ab5 100644 --- a/docs/api/XCEngine/RHI/RHIBuffer/Destructor.md +++ b/docs/api/XCEngine/RHI/RHIBuffer/Destructor.md @@ -1,29 +1,25 @@ # RHIBuffer::~RHIBuffer() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIBuffer.h` + +## 签名 ```cpp virtual ~RHIBuffer() = default; ``` -该方法声明于 `XCEngine/RHI/RHIBuffer.h`，当前页面用于固定 `RHIBuffer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +销毁 `RHIBuffer` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIBuffer object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 当前为默认析构实现。 ## 相关文档 -- [返回类总览](RHIBuffer.md) -- [返回模块目录](../RHI.md) +- [RHIBuffer](RHIBuffer.md) diff --git a/docs/api/XCEngine/RHI/RHIBuffer/GetBufferType.md b/docs/api/XCEngine/RHI/RHIBuffer/GetBufferType.md index 344665f9..fb90c3b2 100644 --- a/docs/api/XCEngine/RHI/RHIBuffer/GetBufferType.md +++ b/docs/api/XCEngine/RHI/RHIBuffer/GetBufferType.md @@ -1,30 +1,26 @@ # RHIBuffer::GetBufferType -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIBuffer.h` + +## 签名 ```cpp virtual BufferType GetBufferType() const = 0; ``` -该方法声明于 `XCEngine/RHI/RHIBuffer.h`，当前页面用于固定 `RHIBuffer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `BufferType` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIBuffer object; - // 根据上下文补齐参数后调用 RHIBuffer::GetBufferType(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIBuffer.md) -- [返回模块目录](../RHI.md) +- [RHIBuffer](RHIBuffer.md) +- [SetBufferType](SetBufferType.md) diff --git a/docs/api/XCEngine/RHI/RHIBuffer/GetName.md b/docs/api/XCEngine/RHI/RHIBuffer/GetName.md index ccc3942d..fcd68629 100644 --- a/docs/api/XCEngine/RHI/RHIBuffer/GetName.md +++ b/docs/api/XCEngine/RHI/RHIBuffer/GetName.md @@ -1,30 +1,26 @@ # RHIBuffer::GetName -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIBuffer.h` + +## 签名 ```cpp virtual const std::string& GetName() const = 0; ``` -该方法声明于 `XCEngine/RHI/RHIBuffer.h`，当前页面用于固定 `RHIBuffer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `const std::string&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIBuffer object; - // 根据上下文补齐参数后调用 RHIBuffer::GetName(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIBuffer.md) -- [返回模块目录](../RHI.md) +- [RHIBuffer](RHIBuffer.md) +- [SetName](SetName.md) diff --git a/docs/api/XCEngine/RHI/RHIBuffer/GetNativeHandle.md b/docs/api/XCEngine/RHI/RHIBuffer/GetNativeHandle.md index 6e9095e5..dd6d7e55 100644 --- a/docs/api/XCEngine/RHI/RHIBuffer/GetNativeHandle.md +++ b/docs/api/XCEngine/RHI/RHIBuffer/GetNativeHandle.md @@ -1,30 +1,25 @@ # RHIBuffer::GetNativeHandle -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIBuffer.h` + +## 签名 ```cpp virtual void* GetNativeHandle() = 0; ``` -该方法声明于 `XCEngine/RHI/RHIBuffer.h`，当前页面用于固定 `RHIBuffer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `void*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIBuffer object; - // 根据上下文补齐参数后调用 RHIBuffer::GetNativeHandle(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIBuffer.md) -- [返回模块目录](../RHI.md) +- [RHIBuffer](RHIBuffer.md) diff --git a/docs/api/XCEngine/RHI/RHIBuffer/GetSize.md b/docs/api/XCEngine/RHI/RHIBuffer/GetSize.md index 404d85ba..f04d56cb 100644 --- a/docs/api/XCEngine/RHI/RHIBuffer/GetSize.md +++ b/docs/api/XCEngine/RHI/RHIBuffer/GetSize.md @@ -1,30 +1,25 @@ # RHIBuffer::GetSize -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIBuffer.h` + +## 签名 ```cpp virtual uint64_t GetSize() const = 0; ``` -该方法声明于 `XCEngine/RHI/RHIBuffer.h`，当前页面用于固定 `RHIBuffer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `uint64_t` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIBuffer object; - // 根据上下文补齐参数后调用 RHIBuffer::GetSize(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIBuffer.md) -- [返回模块目录](../RHI.md) +- [RHIBuffer](RHIBuffer.md) diff --git a/docs/api/XCEngine/RHI/RHIBuffer/GetState.md b/docs/api/XCEngine/RHI/RHIBuffer/GetState.md index 95e3a9ca..86b5d01d 100644 --- a/docs/api/XCEngine/RHI/RHIBuffer/GetState.md +++ b/docs/api/XCEngine/RHI/RHIBuffer/GetState.md @@ -1,30 +1,26 @@ # RHIBuffer::GetState -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIBuffer.h` + +## 签名 ```cpp virtual ResourceStates GetState() const = 0; ``` -该方法声明于 `XCEngine/RHI/RHIBuffer.h`，当前页面用于固定 `RHIBuffer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `ResourceStates` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIBuffer object; - // 根据上下文补齐参数后调用 RHIBuffer::GetState(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIBuffer.md) -- [返回模块目录](../RHI.md) +- [RHIBuffer](RHIBuffer.md) +- [SetState](SetState.md) diff --git a/docs/api/XCEngine/RHI/RHIBuffer/GetStride.md b/docs/api/XCEngine/RHI/RHIBuffer/GetStride.md index 70d9047d..6be9bbd8 100644 --- a/docs/api/XCEngine/RHI/RHIBuffer/GetStride.md +++ b/docs/api/XCEngine/RHI/RHIBuffer/GetStride.md @@ -1,30 +1,26 @@ # RHIBuffer::GetStride -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIBuffer.h` + +## 签名 ```cpp virtual uint32_t GetStride() const = 0; ``` -该方法声明于 `XCEngine/RHI/RHIBuffer.h`，当前页面用于固定 `RHIBuffer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `uint32_t` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIBuffer object; - // 根据上下文补齐参数后调用 RHIBuffer::GetStride(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIBuffer.md) -- [返回模块目录](../RHI.md) +- [RHIBuffer](RHIBuffer.md) +- [SetStride](SetStride.md) diff --git a/docs/api/XCEngine/RHI/RHIBuffer/Map.md b/docs/api/XCEngine/RHI/RHIBuffer/Map.md index ddc7e6b4..c04da6fb 100644 --- a/docs/api/XCEngine/RHI/RHIBuffer/Map.md +++ b/docs/api/XCEngine/RHI/RHIBuffer/Map.md @@ -1,30 +1,25 @@ # RHIBuffer::Map -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIBuffer.h` + +## 签名 ```cpp virtual void* Map() = 0; ``` -该方法声明于 `XCEngine/RHI/RHIBuffer.h`，当前页面用于固定 `RHIBuffer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `void*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIBuffer object; - // 根据上下文补齐参数后调用 RHIBuffer::Map(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIBuffer.md) -- [返回模块目录](../RHI.md) +- [RHIBuffer](RHIBuffer.md) diff --git a/docs/api/XCEngine/RHI/RHIBuffer/SetBufferType.md b/docs/api/XCEngine/RHI/RHIBuffer/SetBufferType.md index fc2dbf65..afdf062e 100644 --- a/docs/api/XCEngine/RHI/RHIBuffer/SetBufferType.md +++ b/docs/api/XCEngine/RHI/RHIBuffer/SetBufferType.md @@ -1,31 +1,26 @@ # RHIBuffer::SetBufferType -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIBuffer.h` + +## 签名 ```cpp virtual void SetBufferType(BufferType type) = 0; ``` -该方法声明于 `XCEngine/RHI/RHIBuffer.h`，当前页面用于固定 `RHIBuffer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `type` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIBuffer object; - // 根据上下文补齐参数后调用 RHIBuffer::SetBufferType(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIBuffer.md) -- [返回模块目录](../RHI.md) +- [RHIBuffer](RHIBuffer.md) +- [GetBufferType](GetBufferType.md) diff --git a/docs/api/XCEngine/RHI/RHIBuffer/SetData.md b/docs/api/XCEngine/RHI/RHIBuffer/SetData.md index 5ec0417a..deb122d0 100644 --- a/docs/api/XCEngine/RHI/RHIBuffer/SetData.md +++ b/docs/api/XCEngine/RHI/RHIBuffer/SetData.md @@ -1,33 +1,25 @@ # RHIBuffer::SetData -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIBuffer.h` + +## 签名 ```cpp virtual void SetData(const void* data, size_t size, size_t offset = 0) = 0; ``` -该方法声明于 `XCEngine/RHI/RHIBuffer.h`，当前页面用于固定 `RHIBuffer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `data` - 参数语义详见头文件声明。 -- `size` - 参数语义详见头文件声明。 -- `offset` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIBuffer object; - // 根据上下文补齐参数后调用 RHIBuffer::SetData(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIBuffer.md) -- [返回模块目录](../RHI.md) +- [RHIBuffer](RHIBuffer.md) diff --git a/docs/api/XCEngine/RHI/RHIBuffer/SetName.md b/docs/api/XCEngine/RHI/RHIBuffer/SetName.md index c34e4c8a..e76340ce 100644 --- a/docs/api/XCEngine/RHI/RHIBuffer/SetName.md +++ b/docs/api/XCEngine/RHI/RHIBuffer/SetName.md @@ -1,31 +1,26 @@ # RHIBuffer::SetName -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIBuffer.h` + +## 签名 ```cpp virtual void SetName(const std::string& name) = 0; ``` -该方法声明于 `XCEngine/RHI/RHIBuffer.h`，当前页面用于固定 `RHIBuffer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `name` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIBuffer object; - // 根据上下文补齐参数后调用 RHIBuffer::SetName(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIBuffer.md) -- [返回模块目录](../RHI.md) +- [RHIBuffer](RHIBuffer.md) +- [GetName](GetName.md) diff --git a/docs/api/XCEngine/RHI/RHIBuffer/SetState.md b/docs/api/XCEngine/RHI/RHIBuffer/SetState.md index 65f8eb39..842daa79 100644 --- a/docs/api/XCEngine/RHI/RHIBuffer/SetState.md +++ b/docs/api/XCEngine/RHI/RHIBuffer/SetState.md @@ -1,31 +1,26 @@ # RHIBuffer::SetState -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIBuffer.h` + +## 签名 ```cpp virtual void SetState(ResourceStates state) = 0; ``` -该方法声明于 `XCEngine/RHI/RHIBuffer.h`，当前页面用于固定 `RHIBuffer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `state` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIBuffer object; - // 根据上下文补齐参数后调用 RHIBuffer::SetState(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIBuffer.md) -- [返回模块目录](../RHI.md) +- [RHIBuffer](RHIBuffer.md) +- [GetState](GetState.md) diff --git a/docs/api/XCEngine/RHI/RHIBuffer/SetStride.md b/docs/api/XCEngine/RHI/RHIBuffer/SetStride.md index 89036785..684ad388 100644 --- a/docs/api/XCEngine/RHI/RHIBuffer/SetStride.md +++ b/docs/api/XCEngine/RHI/RHIBuffer/SetStride.md @@ -1,31 +1,26 @@ # RHIBuffer::SetStride -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIBuffer.h` + +## 签名 ```cpp virtual void SetStride(uint32_t stride) = 0; ``` -该方法声明于 `XCEngine/RHI/RHIBuffer.h`，当前页面用于固定 `RHIBuffer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `stride` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIBuffer object; - // 根据上下文补齐参数后调用 RHIBuffer::SetStride(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIBuffer.md) -- [返回模块目录](../RHI.md) +- [RHIBuffer](RHIBuffer.md) +- [GetStride](GetStride.md) diff --git a/docs/api/XCEngine/RHI/RHIBuffer/Shutdown.md b/docs/api/XCEngine/RHI/RHIBuffer/Shutdown.md index 43ac3c5f..e6d2cd92 100644 --- a/docs/api/XCEngine/RHI/RHIBuffer/Shutdown.md +++ b/docs/api/XCEngine/RHI/RHIBuffer/Shutdown.md @@ -1,30 +1,25 @@ # RHIBuffer::Shutdown -关闭并清理内部状态。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIBuffer.h` + +## 签名 ```cpp virtual void Shutdown() = 0; ``` -该方法声明于 `XCEngine/RHI/RHIBuffer.h`，当前页面用于固定 `RHIBuffer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIBuffer object; - // 根据上下文补齐参数后调用 RHIBuffer::Shutdown(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIBuffer.md) -- [返回模块目录](../RHI.md) +- [RHIBuffer](RHIBuffer.md) diff --git a/docs/api/XCEngine/RHI/RHIBuffer/Unmap.md b/docs/api/XCEngine/RHI/RHIBuffer/Unmap.md index a5a0bfc8..b9ba0721 100644 --- a/docs/api/XCEngine/RHI/RHIBuffer/Unmap.md +++ b/docs/api/XCEngine/RHI/RHIBuffer/Unmap.md @@ -1,30 +1,25 @@ # RHIBuffer::Unmap -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIBuffer.h` + +## 签名 ```cpp virtual void Unmap() = 0; ``` -该方法声明于 `XCEngine/RHI/RHIBuffer.h`，当前页面用于固定 `RHIBuffer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIBuffer object; - // 根据上下文补齐参数后调用 RHIBuffer::Unmap(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIBuffer.md) -- [返回模块目录](../RHI.md) +- [RHIBuffer](RHIBuffer.md) diff --git a/docs/api/XCEngine/RHI/RHICommandList/BeginRenderPass.md b/docs/api/XCEngine/RHI/RHICommandList/BeginRenderPass.md index 4550df52..c9211af1 100644 --- a/docs/api/XCEngine/RHI/RHICommandList/BeginRenderPass.md +++ b/docs/api/XCEngine/RHI/RHICommandList/BeginRenderPass.md @@ -1,35 +1,25 @@ # RHICommandList::BeginRenderPass -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHICommandList.h` + +## 签名 ```cpp virtual void BeginRenderPass(class RHIRenderPass* renderPass, class RHIFramebuffer* framebuffer, const Rect& renderArea, uint32_t clearValueCount, const ClearValue* clearValues) = 0; ``` -该方法声明于 `XCEngine/RHI/RHICommandList.h`，当前页面用于固定 `RHICommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `renderPass` - 参数语义详见头文件声明。 -- `framebuffer` - 参数语义详见头文件声明。 -- `renderArea` - 参数语义详见头文件声明。 -- `clearValueCount` - 参数语义详见头文件声明。 -- `clearValues` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHICommandList object; - // 根据上下文补齐参数后调用 RHICommandList::BeginRenderPass(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHICommandList.md) -- [返回模块目录](../RHI.md) +- [RHICommandList](RHICommandList.md) diff --git a/docs/api/XCEngine/RHI/RHICommandList/Clear.md b/docs/api/XCEngine/RHI/RHICommandList/Clear.md index c3c5a317..6bd3774f 100644 --- a/docs/api/XCEngine/RHI/RHICommandList/Clear.md +++ b/docs/api/XCEngine/RHI/RHICommandList/Clear.md @@ -1,35 +1,25 @@ # RHICommandList::Clear -清空内部数据。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHICommandList.h` + +## 签名 ```cpp virtual void Clear(float r, float g, float b, float a, uint32_t buffers) = 0; ``` -该方法声明于 `XCEngine/RHI/RHICommandList.h`，当前页面用于固定 `RHICommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `r` - 参数语义详见头文件声明。 -- `g` - 参数语义详见头文件声明。 -- `b` - 参数语义详见头文件声明。 -- `a` - 参数语义详见头文件声明。 -- `buffers` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHICommandList object; - // 根据上下文补齐参数后调用 RHICommandList::Clear(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHICommandList.md) -- [返回模块目录](../RHI.md) +- [RHICommandList](RHICommandList.md) diff --git a/docs/api/XCEngine/RHI/RHICommandList/ClearDepthStencil.md b/docs/api/XCEngine/RHI/RHICommandList/ClearDepthStencil.md index 05ed2c13..dca5b446 100644 --- a/docs/api/XCEngine/RHI/RHICommandList/ClearDepthStencil.md +++ b/docs/api/XCEngine/RHI/RHICommandList/ClearDepthStencil.md @@ -1,33 +1,25 @@ # RHICommandList::ClearDepthStencil -清空内部数据。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHICommandList.h` + +## 签名 ```cpp -virtual void ClearDepthStencil(RHIResourceView* depthStencil, float depth, uint8_t stencil) = 0; +virtual void ClearDepthStencil( RHIResourceView* depthStencil, float depth, uint8_t stencil, uint32_t rectCount = 0, const Rect* rects = nullptr) = 0; ``` -该方法声明于 `XCEngine/RHI/RHICommandList.h`，当前页面用于固定 `RHICommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `depthStencil` - 参数语义详见头文件声明。 -- `depth` - 参数语义详见头文件声明。 -- `stencil` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHICommandList object; - // 根据上下文补齐参数后调用 RHICommandList::ClearDepthStencil(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHICommandList.md) -- [返回模块目录](../RHI.md) +- [RHICommandList](RHICommandList.md) diff --git a/docs/api/XCEngine/RHI/RHICommandList/ClearRenderTarget.md b/docs/api/XCEngine/RHI/RHICommandList/ClearRenderTarget.md index e102e3ef..7c650508 100644 --- a/docs/api/XCEngine/RHI/RHICommandList/ClearRenderTarget.md +++ b/docs/api/XCEngine/RHI/RHICommandList/ClearRenderTarget.md @@ -1,32 +1,25 @@ # RHICommandList::ClearRenderTarget -清空内部数据。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHICommandList.h` + +## 签名 ```cpp -virtual void ClearRenderTarget(RHIResourceView* renderTarget, const float color[4]) = 0; +virtual void ClearRenderTarget( RHIResourceView* renderTarget, const float color[4], uint32_t rectCount = 0, const Rect* rects = nullptr) = 0; ``` -该方法声明于 `XCEngine/RHI/RHICommandList.h`，当前页面用于固定 `RHICommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `renderTarget` - 参数语义详见头文件声明。 -- `param` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHICommandList object; - // 根据上下文补齐参数后调用 RHICommandList::ClearRenderTarget(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHICommandList.md) -- [返回模块目录](../RHI.md) +- [RHICommandList](RHICommandList.md) diff --git a/docs/api/XCEngine/RHI/RHICommandList/Close.md b/docs/api/XCEngine/RHI/RHICommandList/Close.md index 056ff911..70fba01b 100644 --- a/docs/api/XCEngine/RHI/RHICommandList/Close.md +++ b/docs/api/XCEngine/RHI/RHICommandList/Close.md @@ -1,30 +1,25 @@ # RHICommandList::Close -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHICommandList.h` + +## 签名 ```cpp virtual void Close() = 0; ``` -该方法声明于 `XCEngine/RHI/RHICommandList.h`，当前页面用于固定 `RHICommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHICommandList object; - // 根据上下文补齐参数后调用 RHICommandList::Close(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHICommandList.md) -- [返回模块目录](../RHI.md) +- [RHICommandList](RHICommandList.md) diff --git a/docs/api/XCEngine/RHI/RHICommandList/CopyResource.md b/docs/api/XCEngine/RHI/RHICommandList/CopyResource.md index 382f151d..767a51c6 100644 --- a/docs/api/XCEngine/RHI/RHICommandList/CopyResource.md +++ b/docs/api/XCEngine/RHI/RHICommandList/CopyResource.md @@ -1,32 +1,25 @@ # RHICommandList::CopyResource -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHICommandList.h` + +## 签名 ```cpp virtual void CopyResource(RHIResourceView* dst, RHIResourceView* src) = 0; ``` -该方法声明于 `XCEngine/RHI/RHICommandList.h`，当前页面用于固定 `RHICommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `dst` - 参数语义详见头文件声明。 -- `src` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHICommandList object; - // 根据上下文补齐参数后调用 RHICommandList::CopyResource(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHICommandList.md) -- [返回模块目录](../RHI.md) +- [RHICommandList](RHICommandList.md) diff --git a/docs/api/XCEngine/RHI/RHICommandList/Destructor.md b/docs/api/XCEngine/RHI/RHICommandList/Destructor.md index 150b4ac1..667698a4 100644 --- a/docs/api/XCEngine/RHI/RHICommandList/Destructor.md +++ b/docs/api/XCEngine/RHI/RHICommandList/Destructor.md @@ -1,29 +1,25 @@ # RHICommandList::~RHICommandList() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHICommandList.h` + +## 签名 ```cpp virtual ~RHICommandList() = default; ``` -该方法声明于 `XCEngine/RHI/RHICommandList.h`，当前页面用于固定 `RHICommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +销毁 `RHICommandList` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHICommandList object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 当前为默认析构实现。 ## 相关文档 -- [返回类总览](RHICommandList.md) -- [返回模块目录](../RHI.md) +- [RHICommandList](RHICommandList.md) diff --git a/docs/api/XCEngine/RHI/RHICommandList/Dispatch.md b/docs/api/XCEngine/RHI/RHICommandList/Dispatch.md index 866de0e3..8c763935 100644 --- a/docs/api/XCEngine/RHI/RHICommandList/Dispatch.md +++ b/docs/api/XCEngine/RHI/RHICommandList/Dispatch.md @@ -1,33 +1,25 @@ # RHICommandList::Dispatch -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHICommandList.h` + +## 签名 ```cpp virtual void Dispatch(uint32_t x, uint32_t y, uint32_t z) = 0; ``` -该方法声明于 `XCEngine/RHI/RHICommandList.h`，当前页面用于固定 `RHICommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `x` - 参数语义详见头文件声明。 -- `y` - 参数语义详见头文件声明。 -- `z` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHICommandList object; - // 根据上下文补齐参数后调用 RHICommandList::Dispatch(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHICommandList.md) -- [返回模块目录](../RHI.md) +- [RHICommandList](RHICommandList.md) diff --git a/docs/api/XCEngine/RHI/RHICommandList/Draw.md b/docs/api/XCEngine/RHI/RHICommandList/Draw.md index 8254df0b..77c062c9 100644 --- a/docs/api/XCEngine/RHI/RHICommandList/Draw.md +++ b/docs/api/XCEngine/RHI/RHICommandList/Draw.md @@ -1,34 +1,25 @@ # RHICommandList::Draw -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHICommandList.h` + +## 签名 ```cpp virtual void Draw(uint32_t vertexCount, uint32_t instanceCount = 1, uint32_t startVertex = 0, uint32_t startInstance = 0) = 0; ``` -该方法声明于 `XCEngine/RHI/RHICommandList.h`，当前页面用于固定 `RHICommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `vertexCount` - 参数语义详见头文件声明。 -- `instanceCount` - 参数语义详见头文件声明。 -- `startVertex` - 参数语义详见头文件声明。 -- `startInstance` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHICommandList object; - // 根据上下文补齐参数后调用 RHICommandList::Draw(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHICommandList.md) -- [返回模块目录](../RHI.md) +- [RHICommandList](RHICommandList.md) diff --git a/docs/api/XCEngine/RHI/RHICommandList/DrawIndexed.md b/docs/api/XCEngine/RHI/RHICommandList/DrawIndexed.md index 0b3011cb..dac3e151 100644 --- a/docs/api/XCEngine/RHI/RHICommandList/DrawIndexed.md +++ b/docs/api/XCEngine/RHI/RHICommandList/DrawIndexed.md @@ -1,35 +1,25 @@ # RHICommandList::DrawIndexed -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHICommandList.h` + +## 签名 ```cpp virtual void DrawIndexed(uint32_t indexCount, uint32_t instanceCount = 1, uint32_t startIndex = 0, int32_t baseVertex = 0, uint32_t startInstance = 0) = 0; ``` -该方法声明于 `XCEngine/RHI/RHICommandList.h`，当前页面用于固定 `RHICommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `indexCount` - 参数语义详见头文件声明。 -- `instanceCount` - 参数语义详见头文件声明。 -- `startIndex` - 参数语义详见头文件声明。 -- `baseVertex` - 参数语义详见头文件声明。 -- `startInstance` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHICommandList object; - // 根据上下文补齐参数后调用 RHICommandList::DrawIndexed(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHICommandList.md) -- [返回模块目录](../RHI.md) +- [RHICommandList](RHICommandList.md) diff --git a/docs/api/XCEngine/RHI/RHICommandList/EndRenderPass.md b/docs/api/XCEngine/RHI/RHICommandList/EndRenderPass.md index fee52bbe..095dbb5d 100644 --- a/docs/api/XCEngine/RHI/RHICommandList/EndRenderPass.md +++ b/docs/api/XCEngine/RHI/RHICommandList/EndRenderPass.md @@ -1,30 +1,25 @@ # RHICommandList::EndRenderPass -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHICommandList.h` + +## 签名 ```cpp virtual void EndRenderPass() = 0; ``` -该方法声明于 `XCEngine/RHI/RHICommandList.h`，当前页面用于固定 `RHICommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHICommandList object; - // 根据上下文补齐参数后调用 RHICommandList::EndRenderPass(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHICommandList.md) -- [返回模块目录](../RHI.md) +- [RHICommandList](RHICommandList.md) diff --git a/docs/api/XCEngine/RHI/RHICommandList/GetNativeHandle.md b/docs/api/XCEngine/RHI/RHICommandList/GetNativeHandle.md index f0631f5a..fe19bb49 100644 --- a/docs/api/XCEngine/RHI/RHICommandList/GetNativeHandle.md +++ b/docs/api/XCEngine/RHI/RHICommandList/GetNativeHandle.md @@ -1,30 +1,25 @@ # RHICommandList::GetNativeHandle -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHICommandList.h` + +## 签名 ```cpp virtual void* GetNativeHandle(); ``` -该方法声明于 `XCEngine/RHI/RHICommandList.h`，当前页面用于固定 `RHICommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +固定返回 `nullptr`。 -**返回：** `void*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHICommandList object; - // 根据上下文补齐参数后调用 RHICommandList::GetNativeHandle(...)。 - (void)object; -} -``` +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](RHICommandList.md) -- [返回模块目录](../RHI.md) +- [RHICommandList](RHICommandList.md) diff --git a/docs/api/XCEngine/RHI/RHICommandList/Reset.md b/docs/api/XCEngine/RHI/RHICommandList/Reset.md index d60587c1..15c28686 100644 --- a/docs/api/XCEngine/RHI/RHICommandList/Reset.md +++ b/docs/api/XCEngine/RHI/RHICommandList/Reset.md @@ -1,30 +1,25 @@ # RHICommandList::Reset -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHICommandList.h` + +## 签名 ```cpp virtual void Reset() = 0; ``` -该方法声明于 `XCEngine/RHI/RHICommandList.h`，当前页面用于固定 `RHICommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHICommandList object; - // 根据上下文补齐参数后调用 RHICommandList::Reset(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHICommandList.md) -- [返回模块目录](../RHI.md) +- [RHICommandList](RHICommandList.md) diff --git a/docs/api/XCEngine/RHI/RHICommandList/SetBlendFactor.md b/docs/api/XCEngine/RHI/RHICommandList/SetBlendFactor.md index a6de943f..8286926f 100644 --- a/docs/api/XCEngine/RHI/RHICommandList/SetBlendFactor.md +++ b/docs/api/XCEngine/RHI/RHICommandList/SetBlendFactor.md @@ -1,31 +1,25 @@ # RHICommandList::SetBlendFactor -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHICommandList.h` + +## 签名 ```cpp virtual void SetBlendFactor(const float factor[4]) = 0; ``` -该方法声明于 `XCEngine/RHI/RHICommandList.h`，当前页面用于固定 `RHICommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `param` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHICommandList object; - // 根据上下文补齐参数后调用 RHICommandList::SetBlendFactor(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHICommandList.md) -- [返回模块目录](../RHI.md) +- [RHICommandList](RHICommandList.md) diff --git a/docs/api/XCEngine/RHI/RHICommandList/SetComputeDescriptorSets.md b/docs/api/XCEngine/RHI/RHICommandList/SetComputeDescriptorSets.md index 2a9451e3..158b917c 100644 --- a/docs/api/XCEngine/RHI/RHICommandList/SetComputeDescriptorSets.md +++ b/docs/api/XCEngine/RHI/RHICommandList/SetComputeDescriptorSets.md @@ -1,34 +1,25 @@ # RHICommandList::SetComputeDescriptorSets -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHICommandList.h` + +## 签名 ```cpp virtual void SetComputeDescriptorSets( uint32_t firstSet, uint32_t count, RHIDescriptorSet** descriptorSets, RHIPipelineLayout* pipelineLayout) = 0; ``` -该方法声明于 `XCEngine/RHI/RHICommandList.h`，当前页面用于固定 `RHICommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `firstSet` - 参数语义详见头文件声明。 -- `count` - 参数语义详见头文件声明。 -- `descriptorSets` - 参数语义详见头文件声明。 -- `pipelineLayout` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHICommandList object; - // 根据上下文补齐参数后调用 RHICommandList::SetComputeDescriptorSets(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHICommandList.md) -- [返回模块目录](../RHI.md) +- [RHICommandList](RHICommandList.md) diff --git a/docs/api/XCEngine/RHI/RHICommandList/SetGraphicsDescriptorSets.md b/docs/api/XCEngine/RHI/RHICommandList/SetGraphicsDescriptorSets.md index bba7d310..eaf5320a 100644 --- a/docs/api/XCEngine/RHI/RHICommandList/SetGraphicsDescriptorSets.md +++ b/docs/api/XCEngine/RHI/RHICommandList/SetGraphicsDescriptorSets.md @@ -1,34 +1,25 @@ # RHICommandList::SetGraphicsDescriptorSets -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHICommandList.h` + +## 签名 ```cpp virtual void SetGraphicsDescriptorSets( uint32_t firstSet, uint32_t count, RHIDescriptorSet** descriptorSets, RHIPipelineLayout* pipelineLayout) = 0; ``` -该方法声明于 `XCEngine/RHI/RHICommandList.h`，当前页面用于固定 `RHICommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `firstSet` - 参数语义详见头文件声明。 -- `count` - 参数语义详见头文件声明。 -- `descriptorSets` - 参数语义详见头文件声明。 -- `pipelineLayout` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHICommandList object; - // 根据上下文补齐参数后调用 RHICommandList::SetGraphicsDescriptorSets(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHICommandList.md) -- [返回模块目录](../RHI.md) +- [RHICommandList](RHICommandList.md) diff --git a/docs/api/XCEngine/RHI/RHICommandList/SetIndexBuffer.md b/docs/api/XCEngine/RHI/RHICommandList/SetIndexBuffer.md index 41b62755..d4dcdc55 100644 --- a/docs/api/XCEngine/RHI/RHICommandList/SetIndexBuffer.md +++ b/docs/api/XCEngine/RHI/RHICommandList/SetIndexBuffer.md @@ -1,32 +1,25 @@ # RHICommandList::SetIndexBuffer -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHICommandList.h` + +## 签名 ```cpp virtual void SetIndexBuffer(RHIResourceView* buffer, uint64_t offset) = 0; ``` -该方法声明于 `XCEngine/RHI/RHICommandList.h`，当前页面用于固定 `RHICommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `buffer` - 参数语义详见头文件声明。 -- `offset` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHICommandList object; - // 根据上下文补齐参数后调用 RHICommandList::SetIndexBuffer(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHICommandList.md) -- [返回模块目录](../RHI.md) +- [RHICommandList](RHICommandList.md) diff --git a/docs/api/XCEngine/RHI/RHICommandList/SetPipelineState.md b/docs/api/XCEngine/RHI/RHICommandList/SetPipelineState.md index 6af537d0..f53683d6 100644 --- a/docs/api/XCEngine/RHI/RHICommandList/SetPipelineState.md +++ b/docs/api/XCEngine/RHI/RHICommandList/SetPipelineState.md @@ -1,31 +1,25 @@ # RHICommandList::SetPipelineState -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHICommandList.h` + +## 签名 ```cpp virtual void SetPipelineState(RHIPipelineState* pso) = 0; ``` -该方法声明于 `XCEngine/RHI/RHICommandList.h`，当前页面用于固定 `RHICommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `pso` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHICommandList object; - // 根据上下文补齐参数后调用 RHICommandList::SetPipelineState(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHICommandList.md) -- [返回模块目录](../RHI.md) +- [RHICommandList](RHICommandList.md) diff --git a/docs/api/XCEngine/RHI/RHICommandList/SetPrimitiveTopology.md b/docs/api/XCEngine/RHI/RHICommandList/SetPrimitiveTopology.md index 599e65ba..e68277fc 100644 --- a/docs/api/XCEngine/RHI/RHICommandList/SetPrimitiveTopology.md +++ b/docs/api/XCEngine/RHI/RHICommandList/SetPrimitiveTopology.md @@ -1,31 +1,25 @@ # RHICommandList::SetPrimitiveTopology -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHICommandList.h` + +## 签名 ```cpp virtual void SetPrimitiveTopology(PrimitiveTopology topology) = 0; ``` -该方法声明于 `XCEngine/RHI/RHICommandList.h`，当前页面用于固定 `RHICommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `topology` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHICommandList object; - // 根据上下文补齐参数后调用 RHICommandList::SetPrimitiveTopology(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHICommandList.md) -- [返回模块目录](../RHI.md) +- [RHICommandList](RHICommandList.md) diff --git a/docs/api/XCEngine/RHI/RHICommandList/SetRenderTargets.md b/docs/api/XCEngine/RHI/RHICommandList/SetRenderTargets.md index 7a576915..211cf85a 100644 --- a/docs/api/XCEngine/RHI/RHICommandList/SetRenderTargets.md +++ b/docs/api/XCEngine/RHI/RHICommandList/SetRenderTargets.md @@ -1,33 +1,25 @@ # RHICommandList::SetRenderTargets -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHICommandList.h` + +## 签名 ```cpp virtual void SetRenderTargets(uint32_t count, RHIResourceView** renderTargets, RHIResourceView* depthStencil = nullptr) = 0; ``` -该方法声明于 `XCEngine/RHI/RHICommandList.h`，当前页面用于固定 `RHICommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `count` - 参数语义详见头文件声明。 -- `renderTargets` - 参数语义详见头文件声明。 -- `depthStencil` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHICommandList object; - // 根据上下文补齐参数后调用 RHICommandList::SetRenderTargets(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHICommandList.md) -- [返回模块目录](../RHI.md) +- [RHICommandList](RHICommandList.md) diff --git a/docs/api/XCEngine/RHI/RHICommandList/SetScissorRect.md b/docs/api/XCEngine/RHI/RHICommandList/SetScissorRect.md index 8b47e494..a63b8a19 100644 --- a/docs/api/XCEngine/RHI/RHICommandList/SetScissorRect.md +++ b/docs/api/XCEngine/RHI/RHICommandList/SetScissorRect.md @@ -1,31 +1,25 @@ # RHICommandList::SetScissorRect -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHICommandList.h` + +## 签名 ```cpp virtual void SetScissorRect(const Rect& rect) = 0; ``` -该方法声明于 `XCEngine/RHI/RHICommandList.h`，当前页面用于固定 `RHICommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `rect` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHICommandList object; - // 根据上下文补齐参数后调用 RHICommandList::SetScissorRect(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHICommandList.md) -- [返回模块目录](../RHI.md) +- [RHICommandList](RHICommandList.md) diff --git a/docs/api/XCEngine/RHI/RHICommandList/SetScissorRects.md b/docs/api/XCEngine/RHI/RHICommandList/SetScissorRects.md index b7297e34..2507ee49 100644 --- a/docs/api/XCEngine/RHI/RHICommandList/SetScissorRects.md +++ b/docs/api/XCEngine/RHI/RHICommandList/SetScissorRects.md @@ -1,32 +1,25 @@ # RHICommandList::SetScissorRects -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHICommandList.h` + +## 签名 ```cpp virtual void SetScissorRects(uint32_t count, const Rect* rects) = 0; ``` -该方法声明于 `XCEngine/RHI/RHICommandList.h`，当前页面用于固定 `RHICommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `count` - 参数语义详见头文件声明。 -- `rects` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHICommandList object; - // 根据上下文补齐参数后调用 RHICommandList::SetScissorRects(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHICommandList.md) -- [返回模块目录](../RHI.md) +- [RHICommandList](RHICommandList.md) diff --git a/docs/api/XCEngine/RHI/RHICommandList/SetShader.md b/docs/api/XCEngine/RHI/RHICommandList/SetShader.md index b8555478..cdf382f0 100644 --- a/docs/api/XCEngine/RHI/RHICommandList/SetShader.md +++ b/docs/api/XCEngine/RHI/RHICommandList/SetShader.md @@ -1,31 +1,25 @@ # RHICommandList::SetShader -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHICommandList.h` + +## 签名 ```cpp virtual void SetShader(RHIShader* shader) = 0; ``` -该方法声明于 `XCEngine/RHI/RHICommandList.h`，当前页面用于固定 `RHICommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `shader` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHICommandList object; - // 根据上下文补齐参数后调用 RHICommandList::SetShader(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHICommandList.md) -- [返回模块目录](../RHI.md) +- [RHICommandList](RHICommandList.md) diff --git a/docs/api/XCEngine/RHI/RHICommandList/SetStencilRef.md b/docs/api/XCEngine/RHI/RHICommandList/SetStencilRef.md index ce2fb0db..1fc62a06 100644 --- a/docs/api/XCEngine/RHI/RHICommandList/SetStencilRef.md +++ b/docs/api/XCEngine/RHI/RHICommandList/SetStencilRef.md @@ -1,31 +1,25 @@ # RHICommandList::SetStencilRef -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHICommandList.h` + +## 签名 ```cpp virtual void SetStencilRef(uint8_t ref) = 0; ``` -该方法声明于 `XCEngine/RHI/RHICommandList.h`，当前页面用于固定 `RHICommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `ref` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHICommandList object; - // 根据上下文补齐参数后调用 RHICommandList::SetStencilRef(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHICommandList.md) -- [返回模块目录](../RHI.md) +- [RHICommandList](RHICommandList.md) diff --git a/docs/api/XCEngine/RHI/RHICommandList/SetVertexBuffers.md b/docs/api/XCEngine/RHI/RHICommandList/SetVertexBuffers.md index ec652eb1..cc56afaa 100644 --- a/docs/api/XCEngine/RHI/RHICommandList/SetVertexBuffers.md +++ b/docs/api/XCEngine/RHI/RHICommandList/SetVertexBuffers.md @@ -1,35 +1,25 @@ # RHICommandList::SetVertexBuffers -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHICommandList.h` + +## 签名 ```cpp virtual void SetVertexBuffers(uint32_t startSlot, uint32_t count, RHIResourceView** buffers, const uint64_t* offsets, const uint32_t* strides) = 0; ``` -该方法声明于 `XCEngine/RHI/RHICommandList.h`，当前页面用于固定 `RHICommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `startSlot` - 参数语义详见头文件声明。 -- `count` - 参数语义详见头文件声明。 -- `buffers` - 参数语义详见头文件声明。 -- `offsets` - 参数语义详见头文件声明。 -- `strides` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHICommandList object; - // 根据上下文补齐参数后调用 RHICommandList::SetVertexBuffers(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHICommandList.md) -- [返回模块目录](../RHI.md) +- [RHICommandList](RHICommandList.md) diff --git a/docs/api/XCEngine/RHI/RHICommandList/SetViewport.md b/docs/api/XCEngine/RHI/RHICommandList/SetViewport.md index ab25e3bf..2fa27e06 100644 --- a/docs/api/XCEngine/RHI/RHICommandList/SetViewport.md +++ b/docs/api/XCEngine/RHI/RHICommandList/SetViewport.md @@ -1,31 +1,25 @@ # RHICommandList::SetViewport -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHICommandList.h` + +## 签名 ```cpp virtual void SetViewport(const Viewport& viewport) = 0; ``` -该方法声明于 `XCEngine/RHI/RHICommandList.h`，当前页面用于固定 `RHICommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `viewport` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHICommandList object; - // 根据上下文补齐参数后调用 RHICommandList::SetViewport(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHICommandList.md) -- [返回模块目录](../RHI.md) +- [RHICommandList](RHICommandList.md) diff --git a/docs/api/XCEngine/RHI/RHICommandList/SetViewports.md b/docs/api/XCEngine/RHI/RHICommandList/SetViewports.md index dffeed40..f5045992 100644 --- a/docs/api/XCEngine/RHI/RHICommandList/SetViewports.md +++ b/docs/api/XCEngine/RHI/RHICommandList/SetViewports.md @@ -1,32 +1,25 @@ # RHICommandList::SetViewports -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHICommandList.h` + +## 签名 ```cpp virtual void SetViewports(uint32_t count, const Viewport* viewports) = 0; ``` -该方法声明于 `XCEngine/RHI/RHICommandList.h`，当前页面用于固定 `RHICommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `count` - 参数语义详见头文件声明。 -- `viewports` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHICommandList object; - // 根据上下文补齐参数后调用 RHICommandList::SetViewports(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHICommandList.md) -- [返回模块目录](../RHI.md) +- [RHICommandList](RHICommandList.md) diff --git a/docs/api/XCEngine/RHI/RHICommandList/Shutdown.md b/docs/api/XCEngine/RHI/RHICommandList/Shutdown.md index 922e7ec9..7de7bdbb 100644 --- a/docs/api/XCEngine/RHI/RHICommandList/Shutdown.md +++ b/docs/api/XCEngine/RHI/RHICommandList/Shutdown.md @@ -1,30 +1,25 @@ # RHICommandList::Shutdown -关闭并清理内部状态。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHICommandList.h` + +## 签名 ```cpp virtual void Shutdown() = 0; ``` -该方法声明于 `XCEngine/RHI/RHICommandList.h`，当前页面用于固定 `RHICommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHICommandList object; - // 根据上下文补齐参数后调用 RHICommandList::Shutdown(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHICommandList.md) -- [返回模块目录](../RHI.md) +- [RHICommandList](RHICommandList.md) diff --git a/docs/api/XCEngine/RHI/RHICommandList/TransitionBarrier.md b/docs/api/XCEngine/RHI/RHICommandList/TransitionBarrier.md index 2ee860f8..9a4ea1a4 100644 --- a/docs/api/XCEngine/RHI/RHICommandList/TransitionBarrier.md +++ b/docs/api/XCEngine/RHI/RHICommandList/TransitionBarrier.md @@ -1,33 +1,25 @@ # RHICommandList::TransitionBarrier -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHICommandList.h` + +## 签名 ```cpp virtual void TransitionBarrier(RHIResourceView* resource, ResourceStates stateBefore, ResourceStates stateAfter) = 0; ``` -该方法声明于 `XCEngine/RHI/RHICommandList.h`，当前页面用于固定 `RHICommandList` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `resource` - 参数语义详见头文件声明。 -- `stateBefore` - 参数语义详见头文件声明。 -- `stateAfter` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHICommandList object; - // 根据上下文补齐参数后调用 RHICommandList::TransitionBarrier(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHICommandList.md) -- [返回模块目录](../RHI.md) +- [RHICommandList](RHICommandList.md) diff --git a/docs/api/XCEngine/RHI/RHICommandQueue/Destructor.md b/docs/api/XCEngine/RHI/RHICommandQueue/Destructor.md index c21c5495..a1fa10d6 100644 --- a/docs/api/XCEngine/RHI/RHICommandQueue/Destructor.md +++ b/docs/api/XCEngine/RHI/RHICommandQueue/Destructor.md @@ -1,29 +1,25 @@ # RHICommandQueue::~RHICommandQueue() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHICommandQueue.h` + +## 签名 ```cpp virtual ~RHICommandQueue() = default; ``` -该方法声明于 `XCEngine/RHI/RHICommandQueue.h`，当前页面用于固定 `RHICommandQueue` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +销毁 `RHICommandQueue` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHICommandQueue object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 当前为默认析构实现。 ## 相关文档 -- [返回类总览](RHICommandQueue.md) -- [返回模块目录](../RHI.md) +- [RHICommandQueue](RHICommandQueue.md) diff --git a/docs/api/XCEngine/RHI/RHICommandQueue/ExecuteCommandLists.md b/docs/api/XCEngine/RHI/RHICommandQueue/ExecuteCommandLists.md index 0858c90e..05956f63 100644 --- a/docs/api/XCEngine/RHI/RHICommandQueue/ExecuteCommandLists.md +++ b/docs/api/XCEngine/RHI/RHICommandQueue/ExecuteCommandLists.md @@ -1,32 +1,25 @@ # RHICommandQueue::ExecuteCommandLists -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHICommandQueue.h` + +## 签名 ```cpp virtual void ExecuteCommandLists(uint32_t count, void** lists) = 0; ``` -该方法声明于 `XCEngine/RHI/RHICommandQueue.h`，当前页面用于固定 `RHICommandQueue` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `count` - 参数语义详见头文件声明。 -- `lists` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHICommandQueue object; - // 根据上下文补齐参数后调用 RHICommandQueue::ExecuteCommandLists(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHICommandQueue.md) -- [返回模块目录](../RHI.md) +- [RHICommandQueue](RHICommandQueue.md) diff --git a/docs/api/XCEngine/RHI/RHICommandQueue/GetCompletedValue.md b/docs/api/XCEngine/RHI/RHICommandQueue/GetCompletedValue.md index 51d6dd07..de245980 100644 --- a/docs/api/XCEngine/RHI/RHICommandQueue/GetCompletedValue.md +++ b/docs/api/XCEngine/RHI/RHICommandQueue/GetCompletedValue.md @@ -1,30 +1,25 @@ # RHICommandQueue::GetCompletedValue -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHICommandQueue.h` + +## 签名 ```cpp virtual uint64_t GetCompletedValue() = 0; ``` -该方法声明于 `XCEngine/RHI/RHICommandQueue.h`，当前页面用于固定 `RHICommandQueue` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `uint64_t` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHICommandQueue object; - // 根据上下文补齐参数后调用 RHICommandQueue::GetCompletedValue(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHICommandQueue.md) -- [返回模块目录](../RHI.md) +- [RHICommandQueue](RHICommandQueue.md) diff --git a/docs/api/XCEngine/RHI/RHICommandQueue/GetCurrentFrame.md b/docs/api/XCEngine/RHI/RHICommandQueue/GetCurrentFrame.md index d7ae4633..153f470a 100644 --- a/docs/api/XCEngine/RHI/RHICommandQueue/GetCurrentFrame.md +++ b/docs/api/XCEngine/RHI/RHICommandQueue/GetCurrentFrame.md @@ -1,30 +1,25 @@ # RHICommandQueue::GetCurrentFrame -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHICommandQueue.h` + +## 签名 ```cpp virtual uint64_t GetCurrentFrame() const = 0; ``` -该方法声明于 `XCEngine/RHI/RHICommandQueue.h`，当前页面用于固定 `RHICommandQueue` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `uint64_t` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHICommandQueue object; - // 根据上下文补齐参数后调用 RHICommandQueue::GetCurrentFrame(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHICommandQueue.md) -- [返回模块目录](../RHI.md) +- [RHICommandQueue](RHICommandQueue.md) diff --git a/docs/api/XCEngine/RHI/RHICommandQueue/GetNativeHandle.md b/docs/api/XCEngine/RHI/RHICommandQueue/GetNativeHandle.md index aa2d48d9..ec00ddea 100644 --- a/docs/api/XCEngine/RHI/RHICommandQueue/GetNativeHandle.md +++ b/docs/api/XCEngine/RHI/RHICommandQueue/GetNativeHandle.md @@ -1,30 +1,25 @@ # RHICommandQueue::GetNativeHandle -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHICommandQueue.h` + +## 签名 ```cpp virtual void* GetNativeHandle() = 0; ``` -该方法声明于 `XCEngine/RHI/RHICommandQueue.h`，当前页面用于固定 `RHICommandQueue` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `void*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHICommandQueue object; - // 根据上下文补齐参数后调用 RHICommandQueue::GetNativeHandle(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHICommandQueue.md) -- [返回模块目录](../RHI.md) +- [RHICommandQueue](RHICommandQueue.md) diff --git a/docs/api/XCEngine/RHI/RHICommandQueue/GetTimestampFrequency.md b/docs/api/XCEngine/RHI/RHICommandQueue/GetTimestampFrequency.md index 0973bff4..15e9912e 100644 --- a/docs/api/XCEngine/RHI/RHICommandQueue/GetTimestampFrequency.md +++ b/docs/api/XCEngine/RHI/RHICommandQueue/GetTimestampFrequency.md @@ -1,30 +1,25 @@ # RHICommandQueue::GetTimestampFrequency -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHICommandQueue.h` + +## 签名 ```cpp virtual uint64_t GetTimestampFrequency() const = 0; ``` -该方法声明于 `XCEngine/RHI/RHICommandQueue.h`，当前页面用于固定 `RHICommandQueue` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `uint64_t` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHICommandQueue object; - // 根据上下文补齐参数后调用 RHICommandQueue::GetTimestampFrequency(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHICommandQueue.md) -- [返回模块目录](../RHI.md) +- [RHICommandQueue](RHICommandQueue.md) diff --git a/docs/api/XCEngine/RHI/RHICommandQueue/GetType.md b/docs/api/XCEngine/RHI/RHICommandQueue/GetType.md index 1ab88e98..df3252ac 100644 --- a/docs/api/XCEngine/RHI/RHICommandQueue/GetType.md +++ b/docs/api/XCEngine/RHI/RHICommandQueue/GetType.md @@ -1,30 +1,25 @@ # RHICommandQueue::GetType -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHICommandQueue.h` + +## 签名 ```cpp virtual CommandQueueType GetType() const = 0; ``` -该方法声明于 `XCEngine/RHI/RHICommandQueue.h`，当前页面用于固定 `RHICommandQueue` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `CommandQueueType` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHICommandQueue object; - // 根据上下文补齐参数后调用 RHICommandQueue::GetType(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHICommandQueue.md) -- [返回模块目录](../RHI.md) +- [RHICommandQueue](RHICommandQueue.md) diff --git a/docs/api/XCEngine/RHI/RHICommandQueue/Shutdown.md b/docs/api/XCEngine/RHI/RHICommandQueue/Shutdown.md index 41bf5a8c..fdbdec04 100644 --- a/docs/api/XCEngine/RHI/RHICommandQueue/Shutdown.md +++ b/docs/api/XCEngine/RHI/RHICommandQueue/Shutdown.md @@ -1,30 +1,25 @@ # RHICommandQueue::Shutdown -关闭并清理内部状态。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHICommandQueue.h` + +## 签名 ```cpp virtual void Shutdown() = 0; ``` -该方法声明于 `XCEngine/RHI/RHICommandQueue.h`，当前页面用于固定 `RHICommandQueue` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHICommandQueue object; - // 根据上下文补齐参数后调用 RHICommandQueue::Shutdown(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHICommandQueue.md) -- [返回模块目录](../RHI.md) +- [RHICommandQueue](RHICommandQueue.md) diff --git a/docs/api/XCEngine/RHI/RHICommandQueue/Signal.md b/docs/api/XCEngine/RHI/RHICommandQueue/Signal.md index 950967f6..66ed3ef2 100644 --- a/docs/api/XCEngine/RHI/RHICommandQueue/Signal.md +++ b/docs/api/XCEngine/RHI/RHICommandQueue/Signal.md @@ -1,32 +1,25 @@ # RHICommandQueue::Signal -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHICommandQueue.h` + +## 签名 ```cpp virtual void Signal(RHIFence* fence, uint64_t value) = 0; ``` -该方法声明于 `XCEngine/RHI/RHICommandQueue.h`，当前页面用于固定 `RHICommandQueue` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `fence` - 参数语义详见头文件声明。 -- `value` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHICommandQueue object; - // 根据上下文补齐参数后调用 RHICommandQueue::Signal(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHICommandQueue.md) -- [返回模块目录](../RHI.md) +- [RHICommandQueue](RHICommandQueue.md) diff --git a/docs/api/XCEngine/RHI/RHICommandQueue/Wait.md b/docs/api/XCEngine/RHI/RHICommandQueue/Wait.md index 677a4d2d..09a070e2 100644 --- a/docs/api/XCEngine/RHI/RHICommandQueue/Wait.md +++ b/docs/api/XCEngine/RHI/RHICommandQueue/Wait.md @@ -1,32 +1,25 @@ # RHICommandQueue::Wait -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHICommandQueue.h` + +## 签名 ```cpp virtual void Wait(RHIFence* fence, uint64_t value) = 0; ``` -该方法声明于 `XCEngine/RHI/RHICommandQueue.h`，当前页面用于固定 `RHICommandQueue` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `fence` - 参数语义详见头文件声明。 -- `value` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHICommandQueue object; - // 根据上下文补齐参数后调用 RHICommandQueue::Wait(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHICommandQueue.md) -- [返回模块目录](../RHI.md) +- [RHICommandQueue](RHICommandQueue.md) diff --git a/docs/api/XCEngine/RHI/RHICommandQueue/WaitForIdle.md b/docs/api/XCEngine/RHI/RHICommandQueue/WaitForIdle.md index db4a1100..866982cc 100644 --- a/docs/api/XCEngine/RHI/RHICommandQueue/WaitForIdle.md +++ b/docs/api/XCEngine/RHI/RHICommandQueue/WaitForIdle.md @@ -1,30 +1,25 @@ # RHICommandQueue::WaitForIdle -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHICommandQueue.h` + +## 签名 ```cpp virtual void WaitForIdle() = 0; ``` -该方法声明于 `XCEngine/RHI/RHICommandQueue.h`，当前页面用于固定 `RHICommandQueue` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHICommandQueue object; - // 根据上下文补齐参数后调用 RHICommandQueue::WaitForIdle(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHICommandQueue.md) -- [返回模块目录](../RHI.md) +- [RHICommandQueue](RHICommandQueue.md) diff --git a/docs/api/XCEngine/RHI/RHICommandQueue/WaitForPreviousFrame.md b/docs/api/XCEngine/RHI/RHICommandQueue/WaitForPreviousFrame.md index aae24953..f8c68d6d 100644 --- a/docs/api/XCEngine/RHI/RHICommandQueue/WaitForPreviousFrame.md +++ b/docs/api/XCEngine/RHI/RHICommandQueue/WaitForPreviousFrame.md @@ -1,30 +1,25 @@ # RHICommandQueue::WaitForPreviousFrame -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHICommandQueue.h` + +## 签名 ```cpp virtual void WaitForPreviousFrame() = 0; ``` -该方法声明于 `XCEngine/RHI/RHICommandQueue.h`，当前页面用于固定 `RHICommandQueue` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHICommandQueue object; - // 根据上下文补齐参数后调用 RHICommandQueue::WaitForPreviousFrame(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHICommandQueue.md) -- [返回模块目录](../RHI.md) +- [RHICommandQueue](RHICommandQueue.md) diff --git a/docs/api/XCEngine/RHI/RHIDescriptorPool/AllocateSet.md b/docs/api/XCEngine/RHI/RHIDescriptorPool/AllocateSet.md index dbb966e2..527f6be4 100644 --- a/docs/api/XCEngine/RHI/RHIDescriptorPool/AllocateSet.md +++ b/docs/api/XCEngine/RHI/RHIDescriptorPool/AllocateSet.md @@ -1,31 +1,25 @@ # RHIDescriptorPool::AllocateSet -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIDescriptorPool.h` + +## 签名 ```cpp virtual RHIDescriptorSet* AllocateSet(const DescriptorSetLayoutDesc& layout) = 0; ``` -该方法声明于 `XCEngine/RHI/RHIDescriptorPool.h`，当前页面用于固定 `RHIDescriptorPool` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `layout` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `RHIDescriptorSet*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIDescriptorPool object; - // 根据上下文补齐参数后调用 RHIDescriptorPool::AllocateSet(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIDescriptorPool.md) -- [返回模块目录](../RHI.md) +- [RHIDescriptorPool](RHIDescriptorPool.md) diff --git a/docs/api/XCEngine/RHI/RHIDescriptorPool/Destructor.md b/docs/api/XCEngine/RHI/RHIDescriptorPool/Destructor.md index 0f49dbae..bda83fa0 100644 --- a/docs/api/XCEngine/RHI/RHIDescriptorPool/Destructor.md +++ b/docs/api/XCEngine/RHI/RHIDescriptorPool/Destructor.md @@ -1,29 +1,25 @@ # RHIDescriptorPool::~RHIDescriptorPool() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIDescriptorPool.h` + +## 签名 ```cpp virtual ~RHIDescriptorPool() = default; ``` -该方法声明于 `XCEngine/RHI/RHIDescriptorPool.h`，当前页面用于固定 `RHIDescriptorPool` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +销毁 `RHIDescriptorPool` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIDescriptorPool object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 当前为默认析构实现。 ## 相关文档 -- [返回类总览](RHIDescriptorPool.md) -- [返回模块目录](../RHI.md) +- [RHIDescriptorPool](RHIDescriptorPool.md) diff --git a/docs/api/XCEngine/RHI/RHIDescriptorPool/FreeSet.md b/docs/api/XCEngine/RHI/RHIDescriptorPool/FreeSet.md index de7e4981..f9a026c4 100644 --- a/docs/api/XCEngine/RHI/RHIDescriptorPool/FreeSet.md +++ b/docs/api/XCEngine/RHI/RHIDescriptorPool/FreeSet.md @@ -1,31 +1,25 @@ # RHIDescriptorPool::FreeSet -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIDescriptorPool.h` + +## 签名 ```cpp virtual void FreeSet(RHIDescriptorSet* set) = 0; ``` -该方法声明于 `XCEngine/RHI/RHIDescriptorPool.h`，当前页面用于固定 `RHIDescriptorPool` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `set` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIDescriptorPool object; - // 根据上下文补齐参数后调用 RHIDescriptorPool::FreeSet(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIDescriptorPool.md) -- [返回模块目录](../RHI.md) +- [RHIDescriptorPool](RHIDescriptorPool.md) diff --git a/docs/api/XCEngine/RHI/RHIDescriptorPool/GetDescriptorCount.md b/docs/api/XCEngine/RHI/RHIDescriptorPool/GetDescriptorCount.md index 646d6341..4163baae 100644 --- a/docs/api/XCEngine/RHI/RHIDescriptorPool/GetDescriptorCount.md +++ b/docs/api/XCEngine/RHI/RHIDescriptorPool/GetDescriptorCount.md @@ -1,30 +1,25 @@ # RHIDescriptorPool::GetDescriptorCount -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIDescriptorPool.h` + +## 签名 ```cpp virtual uint32_t GetDescriptorCount() const = 0; ``` -该方法声明于 `XCEngine/RHI/RHIDescriptorPool.h`，当前页面用于固定 `RHIDescriptorPool` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `uint32_t` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIDescriptorPool object; - // 根据上下文补齐参数后调用 RHIDescriptorPool::GetDescriptorCount(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIDescriptorPool.md) -- [返回模块目录](../RHI.md) +- [RHIDescriptorPool](RHIDescriptorPool.md) diff --git a/docs/api/XCEngine/RHI/RHIDescriptorPool/GetNativeHandle.md b/docs/api/XCEngine/RHI/RHIDescriptorPool/GetNativeHandle.md index 7e7a995d..e3fc7226 100644 --- a/docs/api/XCEngine/RHI/RHIDescriptorPool/GetNativeHandle.md +++ b/docs/api/XCEngine/RHI/RHIDescriptorPool/GetNativeHandle.md @@ -1,30 +1,25 @@ # RHIDescriptorPool::GetNativeHandle -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIDescriptorPool.h` + +## 签名 ```cpp virtual void* GetNativeHandle() = 0; ``` -该方法声明于 `XCEngine/RHI/RHIDescriptorPool.h`，当前页面用于固定 `RHIDescriptorPool` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `void*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIDescriptorPool object; - // 根据上下文补齐参数后调用 RHIDescriptorPool::GetNativeHandle(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIDescriptorPool.md) -- [返回模块目录](../RHI.md) +- [RHIDescriptorPool](RHIDescriptorPool.md) diff --git a/docs/api/XCEngine/RHI/RHIDescriptorPool/GetType.md b/docs/api/XCEngine/RHI/RHIDescriptorPool/GetType.md index 9b080c1d..1c2704f7 100644 --- a/docs/api/XCEngine/RHI/RHIDescriptorPool/GetType.md +++ b/docs/api/XCEngine/RHI/RHIDescriptorPool/GetType.md @@ -1,30 +1,25 @@ # RHIDescriptorPool::GetType -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIDescriptorPool.h` + +## 签名 ```cpp virtual DescriptorHeapType GetType() const = 0; ``` -该方法声明于 `XCEngine/RHI/RHIDescriptorPool.h`，当前页面用于固定 `RHIDescriptorPool` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `DescriptorHeapType` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIDescriptorPool object; - // 根据上下文补齐参数后调用 RHIDescriptorPool::GetType(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIDescriptorPool.md) -- [返回模块目录](../RHI.md) +- [RHIDescriptorPool](RHIDescriptorPool.md) diff --git a/docs/api/XCEngine/RHI/RHIDescriptorPool/Initialize.md b/docs/api/XCEngine/RHI/RHIDescriptorPool/Initialize.md index a73d6f2e..7e4b5aed 100644 --- a/docs/api/XCEngine/RHI/RHIDescriptorPool/Initialize.md +++ b/docs/api/XCEngine/RHI/RHIDescriptorPool/Initialize.md @@ -1,31 +1,25 @@ # RHIDescriptorPool::Initialize -初始化内部状态。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIDescriptorPool.h` + +## 签名 ```cpp virtual bool Initialize(const DescriptorPoolDesc& desc) = 0; ``` -该方法声明于 `XCEngine/RHI/RHIDescriptorPool.h`，当前页面用于固定 `RHIDescriptorPool` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `desc` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIDescriptorPool object; - // 根据上下文补齐参数后调用 RHIDescriptorPool::Initialize(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIDescriptorPool.md) -- [返回模块目录](../RHI.md) +- [RHIDescriptorPool](RHIDescriptorPool.md) diff --git a/docs/api/XCEngine/RHI/RHIDescriptorPool/Shutdown.md b/docs/api/XCEngine/RHI/RHIDescriptorPool/Shutdown.md index 39820374..dc176e67 100644 --- a/docs/api/XCEngine/RHI/RHIDescriptorPool/Shutdown.md +++ b/docs/api/XCEngine/RHI/RHIDescriptorPool/Shutdown.md @@ -1,30 +1,25 @@ # RHIDescriptorPool::Shutdown -关闭并清理内部状态。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIDescriptorPool.h` + +## 签名 ```cpp virtual void Shutdown() = 0; ``` -该方法声明于 `XCEngine/RHI/RHIDescriptorPool.h`，当前页面用于固定 `RHIDescriptorPool` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIDescriptorPool object; - // 根据上下文补齐参数后调用 RHIDescriptorPool::Shutdown(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIDescriptorPool.md) -- [返回模块目录](../RHI.md) +- [RHIDescriptorPool](RHIDescriptorPool.md) diff --git a/docs/api/XCEngine/RHI/RHIDescriptorSet/Bind.md b/docs/api/XCEngine/RHI/RHIDescriptorSet/Bind.md index e3180768..a8712e46 100644 --- a/docs/api/XCEngine/RHI/RHIDescriptorSet/Bind.md +++ b/docs/api/XCEngine/RHI/RHIDescriptorSet/Bind.md @@ -1,30 +1,25 @@ # RHIDescriptorSet::Bind -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIDescriptorSet.h` + +## 签名 ```cpp virtual void Bind() = 0; ``` -该方法声明于 `XCEngine/RHI/RHIDescriptorSet.h`，当前页面用于固定 `RHIDescriptorSet` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIDescriptorSet object; - // 根据上下文补齐参数后调用 RHIDescriptorSet::Bind(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIDescriptorSet.md) -- [返回模块目录](../RHI.md) +- [RHIDescriptorSet](RHIDescriptorSet.md) diff --git a/docs/api/XCEngine/RHI/RHIDescriptorSet/Destructor.md b/docs/api/XCEngine/RHI/RHIDescriptorSet/Destructor.md index eee7db26..1c48d0a9 100644 --- a/docs/api/XCEngine/RHI/RHIDescriptorSet/Destructor.md +++ b/docs/api/XCEngine/RHI/RHIDescriptorSet/Destructor.md @@ -1,29 +1,25 @@ # RHIDescriptorSet::~RHIDescriptorSet() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIDescriptorSet.h` + +## 签名 ```cpp virtual ~RHIDescriptorSet() = default; ``` -该方法声明于 `XCEngine/RHI/RHIDescriptorSet.h`，当前页面用于固定 `RHIDescriptorSet` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +销毁 `RHIDescriptorSet` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIDescriptorSet object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 当前为默认析构实现。 ## 相关文档 -- [返回类总览](RHIDescriptorSet.md) -- [返回模块目录](../RHI.md) +- [RHIDescriptorSet](RHIDescriptorSet.md) diff --git a/docs/api/XCEngine/RHI/RHIDescriptorSet/GetBindingCount.md b/docs/api/XCEngine/RHI/RHIDescriptorSet/GetBindingCount.md index d7bf945d..f80a60e8 100644 --- a/docs/api/XCEngine/RHI/RHIDescriptorSet/GetBindingCount.md +++ b/docs/api/XCEngine/RHI/RHIDescriptorSet/GetBindingCount.md @@ -1,30 +1,25 @@ # RHIDescriptorSet::GetBindingCount -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIDescriptorSet.h` + +## 签名 ```cpp virtual uint32_t GetBindingCount() const = 0; ``` -该方法声明于 `XCEngine/RHI/RHIDescriptorSet.h`，当前页面用于固定 `RHIDescriptorSet` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `uint32_t` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIDescriptorSet object; - // 根据上下文补齐参数后调用 RHIDescriptorSet::GetBindingCount(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIDescriptorSet.md) -- [返回模块目录](../RHI.md) +- [RHIDescriptorSet](RHIDescriptorSet.md) diff --git a/docs/api/XCEngine/RHI/RHIDescriptorSet/GetBindings.md b/docs/api/XCEngine/RHI/RHIDescriptorSet/GetBindings.md index cfd8298d..6fc59287 100644 --- a/docs/api/XCEngine/RHI/RHIDescriptorSet/GetBindings.md +++ b/docs/api/XCEngine/RHI/RHIDescriptorSet/GetBindings.md @@ -1,30 +1,25 @@ # RHIDescriptorSet::GetBindings -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIDescriptorSet.h` + +## 签名 ```cpp virtual const DescriptorSetLayoutBinding* GetBindings() const = 0; ``` -该方法声明于 `XCEngine/RHI/RHIDescriptorSet.h`，当前页面用于固定 `RHIDescriptorSet` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `const DescriptorSetLayoutBinding*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIDescriptorSet object; - // 根据上下文补齐参数后调用 RHIDescriptorSet::GetBindings(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIDescriptorSet.md) -- [返回模块目录](../RHI.md) +- [RHIDescriptorSet](RHIDescriptorSet.md) diff --git a/docs/api/XCEngine/RHI/RHIDescriptorSet/GetConstantBufferData.md b/docs/api/XCEngine/RHI/RHIDescriptorSet/GetConstantBufferData.md index 9dc4b14a..d582b33c 100644 --- a/docs/api/XCEngine/RHI/RHIDescriptorSet/GetConstantBufferData.md +++ b/docs/api/XCEngine/RHI/RHIDescriptorSet/GetConstantBufferData.md @@ -1,30 +1,25 @@ # RHIDescriptorSet::GetConstantBufferData -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIDescriptorSet.h` + +## 签名 ```cpp virtual void* GetConstantBufferData() = 0; ``` -该方法声明于 `XCEngine/RHI/RHIDescriptorSet.h`，当前页面用于固定 `RHIDescriptorSet` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `void*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIDescriptorSet object; - // 根据上下文补齐参数后调用 RHIDescriptorSet::GetConstantBufferData(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIDescriptorSet.md) -- [返回模块目录](../RHI.md) +- [RHIDescriptorSet](RHIDescriptorSet.md) diff --git a/docs/api/XCEngine/RHI/RHIDescriptorSet/GetConstantBufferSize.md b/docs/api/XCEngine/RHI/RHIDescriptorSet/GetConstantBufferSize.md index 388bd180..61077b13 100644 --- a/docs/api/XCEngine/RHI/RHIDescriptorSet/GetConstantBufferSize.md +++ b/docs/api/XCEngine/RHI/RHIDescriptorSet/GetConstantBufferSize.md @@ -1,30 +1,25 @@ # RHIDescriptorSet::GetConstantBufferSize -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIDescriptorSet.h` + +## 签名 ```cpp virtual size_t GetConstantBufferSize() const = 0; ``` -该方法声明于 `XCEngine/RHI/RHIDescriptorSet.h`，当前页面用于固定 `RHIDescriptorSet` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `size_t` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIDescriptorSet object; - // 根据上下文补齐参数后调用 RHIDescriptorSet::GetConstantBufferSize(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIDescriptorSet.md) -- [返回模块目录](../RHI.md) +- [RHIDescriptorSet](RHIDescriptorSet.md) diff --git a/docs/api/XCEngine/RHI/RHIDescriptorSet/IsConstantDirty.md b/docs/api/XCEngine/RHI/RHIDescriptorSet/IsConstantDirty.md index 3b26a488..228f5b9d 100644 --- a/docs/api/XCEngine/RHI/RHIDescriptorSet/IsConstantDirty.md +++ b/docs/api/XCEngine/RHI/RHIDescriptorSet/IsConstantDirty.md @@ -1,30 +1,25 @@ # RHIDescriptorSet::IsConstantDirty -查询当前状态。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIDescriptorSet.h` + +## 签名 ```cpp virtual bool IsConstantDirty() const = 0; ``` -该方法声明于 `XCEngine/RHI/RHIDescriptorSet.h`，当前页面用于固定 `RHIDescriptorSet` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIDescriptorSet object; - // 根据上下文补齐参数后调用 RHIDescriptorSet::IsConstantDirty(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIDescriptorSet.md) -- [返回模块目录](../RHI.md) +- [RHIDescriptorSet](RHIDescriptorSet.md) diff --git a/docs/api/XCEngine/RHI/RHIDescriptorSet/MarkConstantClean.md b/docs/api/XCEngine/RHI/RHIDescriptorSet/MarkConstantClean.md index cea06681..00dd8a35 100644 --- a/docs/api/XCEngine/RHI/RHIDescriptorSet/MarkConstantClean.md +++ b/docs/api/XCEngine/RHI/RHIDescriptorSet/MarkConstantClean.md @@ -1,30 +1,25 @@ # RHIDescriptorSet::MarkConstantClean -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIDescriptorSet.h` + +## 签名 ```cpp virtual void MarkConstantClean() = 0; ``` -该方法声明于 `XCEngine/RHI/RHIDescriptorSet.h`，当前页面用于固定 `RHIDescriptorSet` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIDescriptorSet object; - // 根据上下文补齐参数后调用 RHIDescriptorSet::MarkConstantClean(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIDescriptorSet.md) -- [返回模块目录](../RHI.md) +- [RHIDescriptorSet](RHIDescriptorSet.md) diff --git a/docs/api/XCEngine/RHI/RHIDescriptorSet/Shutdown.md b/docs/api/XCEngine/RHI/RHIDescriptorSet/Shutdown.md index f688e479..c2119158 100644 --- a/docs/api/XCEngine/RHI/RHIDescriptorSet/Shutdown.md +++ b/docs/api/XCEngine/RHI/RHIDescriptorSet/Shutdown.md @@ -1,30 +1,25 @@ # RHIDescriptorSet::Shutdown -关闭并清理内部状态。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIDescriptorSet.h` + +## 签名 ```cpp virtual void Shutdown() = 0; ``` -该方法声明于 `XCEngine/RHI/RHIDescriptorSet.h`，当前页面用于固定 `RHIDescriptorSet` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIDescriptorSet object; - // 根据上下文补齐参数后调用 RHIDescriptorSet::Shutdown(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIDescriptorSet.md) -- [返回模块目录](../RHI.md) +- [RHIDescriptorSet](RHIDescriptorSet.md) diff --git a/docs/api/XCEngine/RHI/RHIDescriptorSet/Unbind.md b/docs/api/XCEngine/RHI/RHIDescriptorSet/Unbind.md index 390ee120..16f85330 100644 --- a/docs/api/XCEngine/RHI/RHIDescriptorSet/Unbind.md +++ b/docs/api/XCEngine/RHI/RHIDescriptorSet/Unbind.md @@ -1,30 +1,25 @@ # RHIDescriptorSet::Unbind -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIDescriptorSet.h` + +## 签名 ```cpp virtual void Unbind() = 0; ``` -该方法声明于 `XCEngine/RHI/RHIDescriptorSet.h`，当前页面用于固定 `RHIDescriptorSet` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIDescriptorSet object; - // 根据上下文补齐参数后调用 RHIDescriptorSet::Unbind(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIDescriptorSet.md) -- [返回模块目录](../RHI.md) +- [RHIDescriptorSet](RHIDescriptorSet.md) diff --git a/docs/api/XCEngine/RHI/RHIDescriptorSet/Update.md b/docs/api/XCEngine/RHI/RHIDescriptorSet/Update.md index cb48cf65..41710636 100644 --- a/docs/api/XCEngine/RHI/RHIDescriptorSet/Update.md +++ b/docs/api/XCEngine/RHI/RHIDescriptorSet/Update.md @@ -1,32 +1,25 @@ # RHIDescriptorSet::Update -更新运行时状态。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIDescriptorSet.h` + +## 签名 ```cpp virtual void Update(uint32_t offset, RHIResourceView* view) = 0; ``` -该方法声明于 `XCEngine/RHI/RHIDescriptorSet.h`，当前页面用于固定 `RHIDescriptorSet` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `offset` - 参数语义详见头文件声明。 -- `view` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIDescriptorSet object; - // 根据上下文补齐参数后调用 RHIDescriptorSet::Update(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIDescriptorSet.md) -- [返回模块目录](../RHI.md) +- [RHIDescriptorSet](RHIDescriptorSet.md) diff --git a/docs/api/XCEngine/RHI/RHIDescriptorSet/UpdateSampler.md b/docs/api/XCEngine/RHI/RHIDescriptorSet/UpdateSampler.md index a69786b2..95e1a707 100644 --- a/docs/api/XCEngine/RHI/RHIDescriptorSet/UpdateSampler.md +++ b/docs/api/XCEngine/RHI/RHIDescriptorSet/UpdateSampler.md @@ -1,32 +1,25 @@ # RHIDescriptorSet::UpdateSampler -更新运行时状态。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIDescriptorSet.h` + +## 签名 ```cpp virtual void UpdateSampler(uint32_t offset, RHISampler* sampler) = 0; ``` -该方法声明于 `XCEngine/RHI/RHIDescriptorSet.h`，当前页面用于固定 `RHIDescriptorSet` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `offset` - 参数语义详见头文件声明。 -- `sampler` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIDescriptorSet object; - // 根据上下文补齐参数后调用 RHIDescriptorSet::UpdateSampler(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIDescriptorSet.md) -- [返回模块目录](../RHI.md) +- [RHIDescriptorSet](RHIDescriptorSet.md) diff --git a/docs/api/XCEngine/RHI/RHIDescriptorSet/WriteConstant.md b/docs/api/XCEngine/RHI/RHIDescriptorSet/WriteConstant.md index 3bcdd512..d5cbd62f 100644 --- a/docs/api/XCEngine/RHI/RHIDescriptorSet/WriteConstant.md +++ b/docs/api/XCEngine/RHI/RHIDescriptorSet/WriteConstant.md @@ -1,34 +1,25 @@ # RHIDescriptorSet::WriteConstant -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIDescriptorSet.h` + +## 签名 ```cpp virtual void WriteConstant(uint32_t binding, const void* data, size_t size, size_t offset = 0) = 0; ``` -该方法声明于 `XCEngine/RHI/RHIDescriptorSet.h`，当前页面用于固定 `RHIDescriptorSet` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `binding` - 参数语义详见头文件声明。 -- `data` - 参数语义详见头文件声明。 -- `size` - 参数语义详见头文件声明。 -- `offset` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIDescriptorSet object; - // 根据上下文补齐参数后调用 RHIDescriptorSet::WriteConstant(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIDescriptorSet.md) -- [返回模块目录](../RHI.md) +- [RHIDescriptorSet](RHIDescriptorSet.md) diff --git a/docs/api/XCEngine/RHI/RHIDevice/CreateBuffer.md b/docs/api/XCEngine/RHI/RHIDevice/CreateBuffer.md index c0f625ad..38e8b82e 100644 --- a/docs/api/XCEngine/RHI/RHIDevice/CreateBuffer.md +++ b/docs/api/XCEngine/RHI/RHIDevice/CreateBuffer.md @@ -1,31 +1,25 @@ # RHIDevice::CreateBuffer -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIDevice.h` + +## 签名 ```cpp virtual RHIBuffer* CreateBuffer(const BufferDesc& desc) = 0; ``` -该方法声明于 `XCEngine/RHI/RHIDevice.h`，当前页面用于固定 `RHIDevice` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `desc` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `RHIBuffer*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIDevice object; - // 根据上下文补齐参数后调用 RHIDevice::CreateBuffer(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIDevice.md) -- [返回模块目录](../RHI.md) +- [RHIDevice](RHIDevice.md) diff --git a/docs/api/XCEngine/RHI/RHIDevice/CreateCommandList.md b/docs/api/XCEngine/RHI/RHIDevice/CreateCommandList.md index d5eb8add..77664dd6 100644 --- a/docs/api/XCEngine/RHI/RHIDevice/CreateCommandList.md +++ b/docs/api/XCEngine/RHI/RHIDevice/CreateCommandList.md @@ -1,31 +1,25 @@ # RHIDevice::CreateCommandList -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIDevice.h` + +## 签名 ```cpp virtual RHICommandList* CreateCommandList(const CommandListDesc& desc) = 0; ``` -该方法声明于 `XCEngine/RHI/RHIDevice.h`，当前页面用于固定 `RHIDevice` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `desc` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `RHICommandList*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIDevice object; - // 根据上下文补齐参数后调用 RHIDevice::CreateCommandList(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIDevice.md) -- [返回模块目录](../RHI.md) +- [RHIDevice](RHIDevice.md) diff --git a/docs/api/XCEngine/RHI/RHIDevice/CreateCommandQueue.md b/docs/api/XCEngine/RHI/RHIDevice/CreateCommandQueue.md index 0f9a4814..7ca96142 100644 --- a/docs/api/XCEngine/RHI/RHIDevice/CreateCommandQueue.md +++ b/docs/api/XCEngine/RHI/RHIDevice/CreateCommandQueue.md @@ -1,31 +1,25 @@ # RHIDevice::CreateCommandQueue -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIDevice.h` + +## 签名 ```cpp virtual RHICommandQueue* CreateCommandQueue(const CommandQueueDesc& desc) = 0; ``` -该方法声明于 `XCEngine/RHI/RHIDevice.h`，当前页面用于固定 `RHIDevice` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `desc` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `RHICommandQueue*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIDevice object; - // 根据上下文补齐参数后调用 RHIDevice::CreateCommandQueue(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIDevice.md) -- [返回模块目录](../RHI.md) +- [RHIDevice](RHIDevice.md) diff --git a/docs/api/XCEngine/RHI/RHIDevice/CreateDepthStencilView.md b/docs/api/XCEngine/RHI/RHIDevice/CreateDepthStencilView.md index 57f03e5c..757e1500 100644 --- a/docs/api/XCEngine/RHI/RHIDevice/CreateDepthStencilView.md +++ b/docs/api/XCEngine/RHI/RHIDevice/CreateDepthStencilView.md @@ -1,32 +1,25 @@ # RHIDevice::CreateDepthStencilView -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIDevice.h` + +## 签名 ```cpp virtual RHIResourceView* CreateDepthStencilView(RHITexture* texture, const ResourceViewDesc& desc) = 0; ``` -该方法声明于 `XCEngine/RHI/RHIDevice.h`，当前页面用于固定 `RHIDevice` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `texture` - 参数语义详见头文件声明。 -- `desc` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `RHIResourceView*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIDevice object; - // 根据上下文补齐参数后调用 RHIDevice::CreateDepthStencilView(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIDevice.md) -- [返回模块目录](../RHI.md) +- [RHIDevice](RHIDevice.md) diff --git a/docs/api/XCEngine/RHI/RHIDevice/CreateDescriptorPool.md b/docs/api/XCEngine/RHI/RHIDevice/CreateDescriptorPool.md index 771b8efe..b6a7dc7f 100644 --- a/docs/api/XCEngine/RHI/RHIDevice/CreateDescriptorPool.md +++ b/docs/api/XCEngine/RHI/RHIDevice/CreateDescriptorPool.md @@ -1,31 +1,25 @@ # RHIDevice::CreateDescriptorPool -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIDevice.h` + +## 签名 ```cpp virtual RHIDescriptorPool* CreateDescriptorPool(const DescriptorPoolDesc& desc) = 0; ``` -该方法声明于 `XCEngine/RHI/RHIDevice.h`，当前页面用于固定 `RHIDevice` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `desc` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `RHIDescriptorPool*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIDevice object; - // 根据上下文补齐参数后调用 RHIDevice::CreateDescriptorPool(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIDevice.md) -- [返回模块目录](../RHI.md) +- [RHIDevice](RHIDevice.md) diff --git a/docs/api/XCEngine/RHI/RHIDevice/CreateDescriptorSet.md b/docs/api/XCEngine/RHI/RHIDevice/CreateDescriptorSet.md index d1c23bb0..9729db68 100644 --- a/docs/api/XCEngine/RHI/RHIDevice/CreateDescriptorSet.md +++ b/docs/api/XCEngine/RHI/RHIDevice/CreateDescriptorSet.md @@ -1,32 +1,25 @@ # RHIDevice::CreateDescriptorSet -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIDevice.h` + +## 签名 ```cpp virtual RHIDescriptorSet* CreateDescriptorSet(RHIDescriptorPool* pool, const DescriptorSetLayoutDesc& layout) = 0; ``` -该方法声明于 `XCEngine/RHI/RHIDevice.h`，当前页面用于固定 `RHIDevice` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `pool` - 参数语义详见头文件声明。 -- `layout` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `RHIDescriptorSet*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIDevice object; - // 根据上下文补齐参数后调用 RHIDevice::CreateDescriptorSet(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIDevice.md) -- [返回模块目录](../RHI.md) +- [RHIDevice](RHIDevice.md) diff --git a/docs/api/XCEngine/RHI/RHIDevice/CreateFence.md b/docs/api/XCEngine/RHI/RHIDevice/CreateFence.md index 9bfed941..fe34a3fa 100644 --- a/docs/api/XCEngine/RHI/RHIDevice/CreateFence.md +++ b/docs/api/XCEngine/RHI/RHIDevice/CreateFence.md @@ -1,31 +1,25 @@ # RHIDevice::CreateFence -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIDevice.h` + +## 签名 ```cpp virtual RHIFence* CreateFence(const FenceDesc& desc) = 0; ``` -该方法声明于 `XCEngine/RHI/RHIDevice.h`，当前页面用于固定 `RHIDevice` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `desc` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `RHIFence*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIDevice object; - // 根据上下文补齐参数后调用 RHIDevice::CreateFence(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIDevice.md) -- [返回模块目录](../RHI.md) +- [RHIDevice](RHIDevice.md) diff --git a/docs/api/XCEngine/RHI/RHIDevice/CreateFramebuffer.md b/docs/api/XCEngine/RHI/RHIDevice/CreateFramebuffer.md index ae80c032..a6baecf2 100644 --- a/docs/api/XCEngine/RHI/RHIDevice/CreateFramebuffer.md +++ b/docs/api/XCEngine/RHI/RHIDevice/CreateFramebuffer.md @@ -1,36 +1,25 @@ # RHIDevice::CreateFramebuffer -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIDevice.h` + +## 签名 ```cpp virtual RHIFramebuffer* CreateFramebuffer( class RHIRenderPass* renderPass, uint32_t width, uint32_t height, uint32_t colorAttachmentCount, RHIResourceView** colorAttachments, RHIResourceView* depthStencilAttachment) = 0; ``` -该方法声明于 `XCEngine/RHI/RHIDevice.h`，当前页面用于固定 `RHIDevice` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `renderPass` - 参数语义详见头文件声明。 -- `width` - 参数语义详见头文件声明。 -- `height` - 参数语义详见头文件声明。 -- `colorAttachmentCount` - 参数语义详见头文件声明。 -- `colorAttachments` - 参数语义详见头文件声明。 -- `depthStencilAttachment` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `RHIFramebuffer*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIDevice object; - // 根据上下文补齐参数后调用 RHIDevice::CreateFramebuffer(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIDevice.md) -- [返回模块目录](../RHI.md) +- [RHIDevice](RHIDevice.md) diff --git a/docs/api/XCEngine/RHI/RHIDevice/CreateIndexBufferView.md b/docs/api/XCEngine/RHI/RHIDevice/CreateIndexBufferView.md index 622eabae..c3b1d35c 100644 --- a/docs/api/XCEngine/RHI/RHIDevice/CreateIndexBufferView.md +++ b/docs/api/XCEngine/RHI/RHIDevice/CreateIndexBufferView.md @@ -1,32 +1,25 @@ # RHIDevice::CreateIndexBufferView -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIDevice.h` + +## 签名 ```cpp virtual RHIResourceView* CreateIndexBufferView(RHIBuffer* buffer, const ResourceViewDesc& desc) = 0; ``` -该方法声明于 `XCEngine/RHI/RHIDevice.h`，当前页面用于固定 `RHIDevice` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `buffer` - 参数语义详见头文件声明。 -- `desc` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `RHIResourceView*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIDevice object; - // 根据上下文补齐参数后调用 RHIDevice::CreateIndexBufferView(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIDevice.md) -- [返回模块目录](../RHI.md) +- [RHIDevice](RHIDevice.md) diff --git a/docs/api/XCEngine/RHI/RHIDevice/CreatePipelineLayout.md b/docs/api/XCEngine/RHI/RHIDevice/CreatePipelineLayout.md index 7f250f3b..d466819f 100644 --- a/docs/api/XCEngine/RHI/RHIDevice/CreatePipelineLayout.md +++ b/docs/api/XCEngine/RHI/RHIDevice/CreatePipelineLayout.md @@ -1,31 +1,25 @@ # RHIDevice::CreatePipelineLayout -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIDevice.h` + +## 签名 ```cpp virtual RHIPipelineLayout* CreatePipelineLayout(const RHIPipelineLayoutDesc& desc) = 0; ``` -该方法声明于 `XCEngine/RHI/RHIDevice.h`，当前页面用于固定 `RHIDevice` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `desc` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `RHIPipelineLayout*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIDevice object; - // 根据上下文补齐参数后调用 RHIDevice::CreatePipelineLayout(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIDevice.md) -- [返回模块目录](../RHI.md) +- [RHIDevice](RHIDevice.md) diff --git a/docs/api/XCEngine/RHI/RHIDevice/CreatePipelineState.md b/docs/api/XCEngine/RHI/RHIDevice/CreatePipelineState.md index aaefd644..bd95fff4 100644 --- a/docs/api/XCEngine/RHI/RHIDevice/CreatePipelineState.md +++ b/docs/api/XCEngine/RHI/RHIDevice/CreatePipelineState.md @@ -1,31 +1,25 @@ # RHIDevice::CreatePipelineState -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIDevice.h` + +## 签名 ```cpp virtual RHIPipelineState* CreatePipelineState(const GraphicsPipelineDesc& desc) = 0; ``` -该方法声明于 `XCEngine/RHI/RHIDevice.h`，当前页面用于固定 `RHIDevice` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `desc` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `RHIPipelineState*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIDevice object; - // 根据上下文补齐参数后调用 RHIDevice::CreatePipelineState(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIDevice.md) -- [返回模块目录](../RHI.md) +- [RHIDevice](RHIDevice.md) diff --git a/docs/api/XCEngine/RHI/RHIDevice/CreateRenderPass.md b/docs/api/XCEngine/RHI/RHIDevice/CreateRenderPass.md index 3ea8dc12..422fc9ac 100644 --- a/docs/api/XCEngine/RHI/RHIDevice/CreateRenderPass.md +++ b/docs/api/XCEngine/RHI/RHIDevice/CreateRenderPass.md @@ -1,33 +1,25 @@ # RHIDevice::CreateRenderPass -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIDevice.h` + +## 签名 ```cpp virtual RHIRenderPass* CreateRenderPass( uint32_t colorAttachmentCount, const AttachmentDesc* colorAttachments, const AttachmentDesc* depthStencilAttachment) = 0; ``` -该方法声明于 `XCEngine/RHI/RHIDevice.h`，当前页面用于固定 `RHIDevice` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `colorAttachmentCount` - 参数语义详见头文件声明。 -- `colorAttachments` - 参数语义详见头文件声明。 -- `depthStencilAttachment` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `RHIRenderPass*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIDevice object; - // 根据上下文补齐参数后调用 RHIDevice::CreateRenderPass(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIDevice.md) -- [返回模块目录](../RHI.md) +- [RHIDevice](RHIDevice.md) diff --git a/docs/api/XCEngine/RHI/RHIDevice/CreateRenderTargetView.md b/docs/api/XCEngine/RHI/RHIDevice/CreateRenderTargetView.md index 029c5413..d5785eb2 100644 --- a/docs/api/XCEngine/RHI/RHIDevice/CreateRenderTargetView.md +++ b/docs/api/XCEngine/RHI/RHIDevice/CreateRenderTargetView.md @@ -1,32 +1,25 @@ # RHIDevice::CreateRenderTargetView -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIDevice.h` + +## 签名 ```cpp virtual RHIResourceView* CreateRenderTargetView(RHITexture* texture, const ResourceViewDesc& desc) = 0; ``` -该方法声明于 `XCEngine/RHI/RHIDevice.h`，当前页面用于固定 `RHIDevice` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `texture` - 参数语义详见头文件声明。 -- `desc` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `RHIResourceView*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIDevice object; - // 根据上下文补齐参数后调用 RHIDevice::CreateRenderTargetView(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIDevice.md) -- [返回模块目录](../RHI.md) +- [RHIDevice](RHIDevice.md) diff --git a/docs/api/XCEngine/RHI/RHIDevice/CreateSampler.md b/docs/api/XCEngine/RHI/RHIDevice/CreateSampler.md index ba0ba722..6751134b 100644 --- a/docs/api/XCEngine/RHI/RHIDevice/CreateSampler.md +++ b/docs/api/XCEngine/RHI/RHIDevice/CreateSampler.md @@ -1,31 +1,25 @@ # RHIDevice::CreateSampler -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIDevice.h` + +## 签名 ```cpp virtual RHISampler* CreateSampler(const SamplerDesc& desc) = 0; ``` -该方法声明于 `XCEngine/RHI/RHIDevice.h`，当前页面用于固定 `RHIDevice` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `desc` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `RHISampler*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIDevice object; - // 根据上下文补齐参数后调用 RHIDevice::CreateSampler(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIDevice.md) -- [返回模块目录](../RHI.md) +- [RHIDevice](RHIDevice.md) diff --git a/docs/api/XCEngine/RHI/RHIDevice/CreateShader.md b/docs/api/XCEngine/RHI/RHIDevice/CreateShader.md index 5e0fab5c..c3ca7d36 100644 --- a/docs/api/XCEngine/RHI/RHIDevice/CreateShader.md +++ b/docs/api/XCEngine/RHI/RHIDevice/CreateShader.md @@ -1,31 +1,25 @@ # RHIDevice::CreateShader -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIDevice.h` + +## 签名 ```cpp virtual RHIShader* CreateShader(const ShaderCompileDesc& desc) = 0; ``` -该方法声明于 `XCEngine/RHI/RHIDevice.h`，当前页面用于固定 `RHIDevice` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `desc` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `RHIShader*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIDevice object; - // 根据上下文补齐参数后调用 RHIDevice::CreateShader(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIDevice.md) -- [返回模块目录](../RHI.md) +- [RHIDevice](RHIDevice.md) diff --git a/docs/api/XCEngine/RHI/RHIDevice/CreateShaderResourceView.md b/docs/api/XCEngine/RHI/RHIDevice/CreateShaderResourceView.md index 920a3d7a..184f04ab 100644 --- a/docs/api/XCEngine/RHI/RHIDevice/CreateShaderResourceView.md +++ b/docs/api/XCEngine/RHI/RHIDevice/CreateShaderResourceView.md @@ -1,32 +1,25 @@ # RHIDevice::CreateShaderResourceView -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIDevice.h` + +## 签名 ```cpp virtual RHIResourceView* CreateShaderResourceView(RHITexture* texture, const ResourceViewDesc& desc) = 0; ``` -该方法声明于 `XCEngine/RHI/RHIDevice.h`，当前页面用于固定 `RHIDevice` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `texture` - 参数语义详见头文件声明。 -- `desc` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `RHIResourceView*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIDevice object; - // 根据上下文补齐参数后调用 RHIDevice::CreateShaderResourceView(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIDevice.md) -- [返回模块目录](../RHI.md) +- [RHIDevice](RHIDevice.md) diff --git a/docs/api/XCEngine/RHI/RHIDevice/CreateSwapChain.md b/docs/api/XCEngine/RHI/RHIDevice/CreateSwapChain.md index a787bb93..f1ec879d 100644 --- a/docs/api/XCEngine/RHI/RHIDevice/CreateSwapChain.md +++ b/docs/api/XCEngine/RHI/RHIDevice/CreateSwapChain.md @@ -1,32 +1,25 @@ # RHIDevice::CreateSwapChain -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIDevice.h` + +## 签名 ```cpp virtual RHISwapChain* CreateSwapChain(const SwapChainDesc& desc, RHICommandQueue* presentQueue) = 0; ``` -该方法声明于 `XCEngine/RHI/RHIDevice.h`，当前页面用于固定 `RHIDevice` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `desc` - 参数语义详见头文件声明。 -- `presentQueue` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `RHISwapChain*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIDevice object; - // 根据上下文补齐参数后调用 RHIDevice::CreateSwapChain(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIDevice.md) -- [返回模块目录](../RHI.md) +- [RHIDevice](RHIDevice.md) diff --git a/docs/api/XCEngine/RHI/RHIDevice/CreateTexture.md b/docs/api/XCEngine/RHI/RHIDevice/CreateTexture.md index 4ee1526c..a4b84d13 100644 --- a/docs/api/XCEngine/RHI/RHIDevice/CreateTexture.md +++ b/docs/api/XCEngine/RHI/RHIDevice/CreateTexture.md @@ -1,47 +1,26 @@ # RHIDevice::CreateTexture -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` -该方法在 `XCEngine/RHI/RHIDevice.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。 +**类型**: `method` -## 重载 1: 声明 +**头文件**: `XCEngine/RHI/RHIDevice.h` + +## 签名 ```cpp virtual RHITexture* CreateTexture(const TextureDesc& desc) = 0; -``` - -**参数：** -- `desc` - 参数语义详见头文件声明。 - -**返回：** `RHITexture*` - 返回值语义详见头文件声明。 - -## 重载 2: 声明 - -```cpp virtual RHITexture* CreateTexture(const TextureDesc& desc, const void* initialData, size_t initialDataSize, uint32_t rowPitch = 0) = 0; ``` -**参数：** -- `desc` - 参数语义详见头文件声明。 -- `initialData` - 参数语义详见头文件声明。 -- `initialDataSize` - 参数语义详见头文件声明。 -- `rowPitch` - 参数语义详见头文件声明。 +## 作用 -**返回：** `RHITexture*` - 返回值语义详见头文件声明。 +纯虚接口。 -**示例：** +## 当前实现 -```cpp -#include - -void Example() { - XCEngine::RHI::RHIDevice object; - // 根据上下文补齐参数后调用 RHIDevice::CreateTexture(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIDevice.md) -- [返回模块目录](../RHI.md) +- [RHIDevice](RHIDevice.md) diff --git a/docs/api/XCEngine/RHI/RHIDevice/CreateUnorderedAccessView.md b/docs/api/XCEngine/RHI/RHIDevice/CreateUnorderedAccessView.md index f4afd5c8..b57bd6fa 100644 --- a/docs/api/XCEngine/RHI/RHIDevice/CreateUnorderedAccessView.md +++ b/docs/api/XCEngine/RHI/RHIDevice/CreateUnorderedAccessView.md @@ -1,32 +1,25 @@ # RHIDevice::CreateUnorderedAccessView -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIDevice.h` + +## 签名 ```cpp virtual RHIResourceView* CreateUnorderedAccessView(RHITexture* texture, const ResourceViewDesc& desc) = 0; ``` -该方法声明于 `XCEngine/RHI/RHIDevice.h`，当前页面用于固定 `RHIDevice` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `texture` - 参数语义详见头文件声明。 -- `desc` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `RHIResourceView*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIDevice object; - // 根据上下文补齐参数后调用 RHIDevice::CreateUnorderedAccessView(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIDevice.md) -- [返回模块目录](../RHI.md) +- [RHIDevice](RHIDevice.md) diff --git a/docs/api/XCEngine/RHI/RHIDevice/CreateVertexBufferView.md b/docs/api/XCEngine/RHI/RHIDevice/CreateVertexBufferView.md index 229eb770..b2e67e4d 100644 --- a/docs/api/XCEngine/RHI/RHIDevice/CreateVertexBufferView.md +++ b/docs/api/XCEngine/RHI/RHIDevice/CreateVertexBufferView.md @@ -1,32 +1,25 @@ # RHIDevice::CreateVertexBufferView -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIDevice.h` + +## 签名 ```cpp virtual RHIResourceView* CreateVertexBufferView(RHIBuffer* buffer, const ResourceViewDesc& desc) = 0; ``` -该方法声明于 `XCEngine/RHI/RHIDevice.h`，当前页面用于固定 `RHIDevice` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `buffer` - 参数语义详见头文件声明。 -- `desc` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `RHIResourceView*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIDevice object; - // 根据上下文补齐参数后调用 RHIDevice::CreateVertexBufferView(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIDevice.md) -- [返回模块目录](../RHI.md) +- [RHIDevice](RHIDevice.md) diff --git a/docs/api/XCEngine/RHI/RHIDevice/Destructor.md b/docs/api/XCEngine/RHI/RHIDevice/Destructor.md index a669d5ed..182cbfc3 100644 --- a/docs/api/XCEngine/RHI/RHIDevice/Destructor.md +++ b/docs/api/XCEngine/RHI/RHIDevice/Destructor.md @@ -1,29 +1,25 @@ # RHIDevice::~RHIDevice() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIDevice.h` + +## 签名 ```cpp virtual ~RHIDevice() = default; ``` -该方法声明于 `XCEngine/RHI/RHIDevice.h`，当前页面用于固定 `RHIDevice` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +销毁 `RHIDevice` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIDevice object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 当前为默认析构实现。 ## 相关文档 -- [返回类总览](RHIDevice.md) -- [返回模块目录](../RHI.md) +- [RHIDevice](RHIDevice.md) diff --git a/docs/api/XCEngine/RHI/RHIDevice/GetCapabilities.md b/docs/api/XCEngine/RHI/RHIDevice/GetCapabilities.md index 2355fb85..cddc6454 100644 --- a/docs/api/XCEngine/RHI/RHIDevice/GetCapabilities.md +++ b/docs/api/XCEngine/RHI/RHIDevice/GetCapabilities.md @@ -1,30 +1,25 @@ # RHIDevice::GetCapabilities -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIDevice.h` + +## 签名 ```cpp virtual const RHICapabilities& GetCapabilities() const = 0; ``` -该方法声明于 `XCEngine/RHI/RHIDevice.h`，当前页面用于固定 `RHIDevice` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `const RHICapabilities&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIDevice object; - // 根据上下文补齐参数后调用 RHIDevice::GetCapabilities(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIDevice.md) -- [返回模块目录](../RHI.md) +- [RHIDevice](RHIDevice.md) diff --git a/docs/api/XCEngine/RHI/RHIDevice/GetDeviceInfo.md b/docs/api/XCEngine/RHI/RHIDevice/GetDeviceInfo.md index 53807d4f..dd08600e 100644 --- a/docs/api/XCEngine/RHI/RHIDevice/GetDeviceInfo.md +++ b/docs/api/XCEngine/RHI/RHIDevice/GetDeviceInfo.md @@ -1,30 +1,25 @@ # RHIDevice::GetDeviceInfo -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIDevice.h` + +## 签名 ```cpp virtual const RHIDeviceInfo& GetDeviceInfo() const = 0; ``` -该方法声明于 `XCEngine/RHI/RHIDevice.h`，当前页面用于固定 `RHIDevice` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `const RHIDeviceInfo&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIDevice object; - // 根据上下文补齐参数后调用 RHIDevice::GetDeviceInfo(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIDevice.md) -- [返回模块目录](../RHI.md) +- [RHIDevice](RHIDevice.md) diff --git a/docs/api/XCEngine/RHI/RHIDevice/GetNativeDevice.md b/docs/api/XCEngine/RHI/RHIDevice/GetNativeDevice.md index 1681b5e9..3b44b34e 100644 --- a/docs/api/XCEngine/RHI/RHIDevice/GetNativeDevice.md +++ b/docs/api/XCEngine/RHI/RHIDevice/GetNativeDevice.md @@ -1,30 +1,25 @@ # RHIDevice::GetNativeDevice -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIDevice.h` + +## 签名 ```cpp virtual void* GetNativeDevice() = 0; ``` -该方法声明于 `XCEngine/RHI/RHIDevice.h`，当前页面用于固定 `RHIDevice` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `void*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIDevice object; - // 根据上下文补齐参数后调用 RHIDevice::GetNativeDevice(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIDevice.md) -- [返回模块目录](../RHI.md) +- [RHIDevice](RHIDevice.md) diff --git a/docs/api/XCEngine/RHI/RHIDevice/Initialize.md b/docs/api/XCEngine/RHI/RHIDevice/Initialize.md index 07e93034..a9be9e65 100644 --- a/docs/api/XCEngine/RHI/RHIDevice/Initialize.md +++ b/docs/api/XCEngine/RHI/RHIDevice/Initialize.md @@ -1,31 +1,25 @@ # RHIDevice::Initialize -初始化内部状态。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIDevice.h` + +## 签名 ```cpp virtual bool Initialize(const RHIDeviceDesc& desc) = 0; ``` -该方法声明于 `XCEngine/RHI/RHIDevice.h`，当前页面用于固定 `RHIDevice` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `desc` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIDevice object; - // 根据上下文补齐参数后调用 RHIDevice::Initialize(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIDevice.md) -- [返回模块目录](../RHI.md) +- [RHIDevice](RHIDevice.md) diff --git a/docs/api/XCEngine/RHI/RHIDevice/Shutdown.md b/docs/api/XCEngine/RHI/RHIDevice/Shutdown.md index 4a7a5440..0b084d16 100644 --- a/docs/api/XCEngine/RHI/RHIDevice/Shutdown.md +++ b/docs/api/XCEngine/RHI/RHIDevice/Shutdown.md @@ -1,30 +1,25 @@ # RHIDevice::Shutdown -关闭并清理内部状态。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIDevice.h` + +## 签名 ```cpp virtual void Shutdown() = 0; ``` -该方法声明于 `XCEngine/RHI/RHIDevice.h`，当前页面用于固定 `RHIDevice` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIDevice object; - // 根据上下文补齐参数后调用 RHIDevice::Shutdown(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIDevice.md) -- [返回模块目录](../RHI.md) +- [RHIDevice](RHIDevice.md) diff --git a/docs/api/XCEngine/RHI/RHIFactory/CreateRHIDevice.md b/docs/api/XCEngine/RHI/RHIFactory/CreateRHIDevice.md index 13905f9e..ea115678 100644 --- a/docs/api/XCEngine/RHI/RHIFactory/CreateRHIDevice.md +++ b/docs/api/XCEngine/RHI/RHIFactory/CreateRHIDevice.md @@ -1,44 +1,28 @@ # RHIFactory::CreateRHIDevice -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` -该方法在 `XCEngine/RHI/RHIFactory.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。 +**类型**: `method` -## 重载 1: 声明 +**头文件**: `XCEngine/RHI/RHIFactory.h` + +## 签名 ```cpp static RHIDevice* CreateRHIDevice(RHIType type); -``` - -**参数：** -- `type` - 参数语义详见头文件声明。 - -**返回：** `RHIDevice*` - 返回值语义详见头文件声明。 - -## 重载 2: 声明 - -```cpp static RHIDevice* CreateRHIDevice(const std::string& typeName); ``` -**参数：** -- `typeName` - 参数语义详见头文件声明。 +## 作用 -**返回：** `RHIDevice*` - 返回值语义详见头文件声明。 +执行 `D3D12Device`、`OpenGLDevice`、`VulkanDevice` 协同流程。 -**示例：** +## 当前实现 -```cpp -#include - -void Example() { - XCEngine::RHI::RHIFactory object; - // 根据上下文补齐参数后调用 RHIFactory::CreateRHIDevice(...)。 - (void)object; -} -``` +- 当前实现会调用 `D3D12Device`、`OpenGLDevice`、`VulkanDevice`。 +- 包含条件分支，并可能提前返回。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](RHIFactory.md) -- [返回模块目录](../RHI.md) +- [RHIFactory](RHIFactory.md) diff --git a/docs/api/XCEngine/RHI/RHIFence/Destructor.md b/docs/api/XCEngine/RHI/RHIFence/Destructor.md index 1cabd6c7..610c740c 100644 --- a/docs/api/XCEngine/RHI/RHIFence/Destructor.md +++ b/docs/api/XCEngine/RHI/RHIFence/Destructor.md @@ -1,29 +1,25 @@ # RHIFence::~RHIFence() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIFence.h` + +## 签名 ```cpp virtual ~RHIFence() = default; ``` -该方法声明于 `XCEngine/RHI/RHIFence.h`，当前页面用于固定 `RHIFence` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +销毁 `RHIFence` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIFence object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 当前为默认析构实现。 ## 相关文档 -- [返回类总览](RHIFence.md) -- [返回模块目录](../RHI.md) +- [RHIFence](RHIFence.md) diff --git a/docs/api/XCEngine/RHI/RHIFence/GetCompletedValue.md b/docs/api/XCEngine/RHI/RHIFence/GetCompletedValue.md index fe077d25..17ef2397 100644 --- a/docs/api/XCEngine/RHI/RHIFence/GetCompletedValue.md +++ b/docs/api/XCEngine/RHI/RHIFence/GetCompletedValue.md @@ -1,30 +1,25 @@ # RHIFence::GetCompletedValue -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIFence.h` + +## 签名 ```cpp virtual uint64_t GetCompletedValue() const = 0; ``` -该方法声明于 `XCEngine/RHI/RHIFence.h`，当前页面用于固定 `RHIFence` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `uint64_t` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIFence object; - // 根据上下文补齐参数后调用 RHIFence::GetCompletedValue(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIFence.md) -- [返回模块目录](../RHI.md) +- [RHIFence](RHIFence.md) diff --git a/docs/api/XCEngine/RHI/RHIFence/GetNativeHandle.md b/docs/api/XCEngine/RHI/RHIFence/GetNativeHandle.md index 6ffb4949..7a0950be 100644 --- a/docs/api/XCEngine/RHI/RHIFence/GetNativeHandle.md +++ b/docs/api/XCEngine/RHI/RHIFence/GetNativeHandle.md @@ -1,30 +1,25 @@ # RHIFence::GetNativeHandle -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIFence.h` + +## 签名 ```cpp virtual void* GetNativeHandle() = 0; ``` -该方法声明于 `XCEngine/RHI/RHIFence.h`，当前页面用于固定 `RHIFence` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `void*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIFence object; - // 根据上下文补齐参数后调用 RHIFence::GetNativeHandle(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIFence.md) -- [返回模块目录](../RHI.md) +- [RHIFence](RHIFence.md) diff --git a/docs/api/XCEngine/RHI/RHIFence/Shutdown.md b/docs/api/XCEngine/RHI/RHIFence/Shutdown.md index 1b497f63..4d745701 100644 --- a/docs/api/XCEngine/RHI/RHIFence/Shutdown.md +++ b/docs/api/XCEngine/RHI/RHIFence/Shutdown.md @@ -1,30 +1,25 @@ # RHIFence::Shutdown -关闭并清理内部状态。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIFence.h` + +## 签名 ```cpp virtual void Shutdown() = 0; ``` -该方法声明于 `XCEngine/RHI/RHIFence.h`，当前页面用于固定 `RHIFence` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIFence object; - // 根据上下文补齐参数后调用 RHIFence::Shutdown(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIFence.md) -- [返回模块目录](../RHI.md) +- [RHIFence](RHIFence.md) diff --git a/docs/api/XCEngine/RHI/RHIFence/Signal.md b/docs/api/XCEngine/RHI/RHIFence/Signal.md index e1120699..8272fa73 100644 --- a/docs/api/XCEngine/RHI/RHIFence/Signal.md +++ b/docs/api/XCEngine/RHI/RHIFence/Signal.md @@ -1,43 +1,26 @@ # RHIFence::Signal -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` -该方法在 `XCEngine/RHI/RHIFence.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。 +**类型**: `method` -## 重载 1: 声明 +**头文件**: `XCEngine/RHI/RHIFence.h` + +## 签名 ```cpp virtual void Signal() = 0; -``` - -**参数：** 无。 - -**返回：** `void` - 无返回值。 - -## 重载 2: 声明 - -```cpp virtual void Signal(uint64_t value) = 0; ``` -**参数：** -- `value` - 参数语义详见头文件声明。 +## 作用 -**返回：** `void` - 无返回值。 +纯虚接口。 -**示例：** +## 当前实现 -```cpp -#include - -void Example() { - XCEngine::RHI::RHIFence object; - // 根据上下文补齐参数后调用 RHIFence::Signal(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIFence.md) -- [返回模块目录](../RHI.md) +- [RHIFence](RHIFence.md) diff --git a/docs/api/XCEngine/RHI/RHIFence/Wait.md b/docs/api/XCEngine/RHI/RHIFence/Wait.md index 344e7629..bab8a573 100644 --- a/docs/api/XCEngine/RHI/RHIFence/Wait.md +++ b/docs/api/XCEngine/RHI/RHIFence/Wait.md @@ -1,31 +1,25 @@ # RHIFence::Wait -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIFence.h` + +## 签名 ```cpp virtual void Wait(uint64_t value) = 0; ``` -该方法声明于 `XCEngine/RHI/RHIFence.h`，当前页面用于固定 `RHIFence` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `value` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIFence object; - // 根据上下文补齐参数后调用 RHIFence::Wait(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIFence.md) -- [返回模块目录](../RHI.md) +- [RHIFence](RHIFence.md) diff --git a/docs/api/XCEngine/RHI/RHIFramebuffer/Destructor.md b/docs/api/XCEngine/RHI/RHIFramebuffer/Destructor.md index 177310cf..394059a1 100644 --- a/docs/api/XCEngine/RHI/RHIFramebuffer/Destructor.md +++ b/docs/api/XCEngine/RHI/RHIFramebuffer/Destructor.md @@ -1,29 +1,25 @@ # RHIFramebuffer::~RHIFramebuffer() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIFramebuffer.h` + +## 签名 ```cpp virtual ~RHIFramebuffer() = default; ``` -该方法声明于 `XCEngine/RHI/RHIFramebuffer.h`，当前页面用于固定 `RHIFramebuffer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +销毁 `RHIFramebuffer` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIFramebuffer object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 当前为默认析构实现。 ## 相关文档 -- [返回类总览](RHIFramebuffer.md) -- [返回模块目录](../RHI.md) +- [RHIFramebuffer](RHIFramebuffer.md) diff --git a/docs/api/XCEngine/RHI/RHIFramebuffer/GetHeight.md b/docs/api/XCEngine/RHI/RHIFramebuffer/GetHeight.md index bcd44401..ae401d1c 100644 --- a/docs/api/XCEngine/RHI/RHIFramebuffer/GetHeight.md +++ b/docs/api/XCEngine/RHI/RHIFramebuffer/GetHeight.md @@ -1,30 +1,25 @@ # RHIFramebuffer::GetHeight -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIFramebuffer.h` + +## 签名 ```cpp virtual uint32_t GetHeight() const = 0; ``` -该方法声明于 `XCEngine/RHI/RHIFramebuffer.h`，当前页面用于固定 `RHIFramebuffer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `uint32_t` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIFramebuffer object; - // 根据上下文补齐参数后调用 RHIFramebuffer::GetHeight(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIFramebuffer.md) -- [返回模块目录](../RHI.md) +- [RHIFramebuffer](RHIFramebuffer.md) diff --git a/docs/api/XCEngine/RHI/RHIFramebuffer/GetNativeHandle.md b/docs/api/XCEngine/RHI/RHIFramebuffer/GetNativeHandle.md index 18d0a575..9bbeb524 100644 --- a/docs/api/XCEngine/RHI/RHIFramebuffer/GetNativeHandle.md +++ b/docs/api/XCEngine/RHI/RHIFramebuffer/GetNativeHandle.md @@ -1,30 +1,25 @@ # RHIFramebuffer::GetNativeHandle -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIFramebuffer.h` + +## 签名 ```cpp virtual void* GetNativeHandle() = 0; ``` -该方法声明于 `XCEngine/RHI/RHIFramebuffer.h`，当前页面用于固定 `RHIFramebuffer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `void*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIFramebuffer object; - // 根据上下文补齐参数后调用 RHIFramebuffer::GetNativeHandle(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIFramebuffer.md) -- [返回模块目录](../RHI.md) +- [RHIFramebuffer](RHIFramebuffer.md) diff --git a/docs/api/XCEngine/RHI/RHIFramebuffer/GetWidth.md b/docs/api/XCEngine/RHI/RHIFramebuffer/GetWidth.md index e362f2b0..a90d1b82 100644 --- a/docs/api/XCEngine/RHI/RHIFramebuffer/GetWidth.md +++ b/docs/api/XCEngine/RHI/RHIFramebuffer/GetWidth.md @@ -1,30 +1,25 @@ # RHIFramebuffer::GetWidth -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIFramebuffer.h` + +## 签名 ```cpp virtual uint32_t GetWidth() const = 0; ``` -该方法声明于 `XCEngine/RHI/RHIFramebuffer.h`，当前页面用于固定 `RHIFramebuffer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `uint32_t` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIFramebuffer object; - // 根据上下文补齐参数后调用 RHIFramebuffer::GetWidth(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIFramebuffer.md) -- [返回模块目录](../RHI.md) +- [RHIFramebuffer](RHIFramebuffer.md) diff --git a/docs/api/XCEngine/RHI/RHIFramebuffer/Initialize.md b/docs/api/XCEngine/RHI/RHIFramebuffer/Initialize.md index 0103d092..e3aa1dd7 100644 --- a/docs/api/XCEngine/RHI/RHIFramebuffer/Initialize.md +++ b/docs/api/XCEngine/RHI/RHIFramebuffer/Initialize.md @@ -1,36 +1,25 @@ # RHIFramebuffer::Initialize -初始化内部状态。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIFramebuffer.h` + +## 签名 ```cpp virtual bool Initialize(class RHIRenderPass* renderPass, uint32_t width, uint32_t height, uint32_t colorAttachmentCount, RHIResourceView** colorAttachments, RHIResourceView* depthStencilAttachment) = 0; ``` -该方法声明于 `XCEngine/RHI/RHIFramebuffer.h`，当前页面用于固定 `RHIFramebuffer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `renderPass` - 参数语义详见头文件声明。 -- `width` - 参数语义详见头文件声明。 -- `height` - 参数语义详见头文件声明。 -- `colorAttachmentCount` - 参数语义详见头文件声明。 -- `colorAttachments` - 参数语义详见头文件声明。 -- `depthStencilAttachment` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIFramebuffer object; - // 根据上下文补齐参数后调用 RHIFramebuffer::Initialize(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIFramebuffer.md) -- [返回模块目录](../RHI.md) +- [RHIFramebuffer](RHIFramebuffer.md) diff --git a/docs/api/XCEngine/RHI/RHIFramebuffer/IsValid.md b/docs/api/XCEngine/RHI/RHIFramebuffer/IsValid.md index 3bd623d6..a6a0ef69 100644 --- a/docs/api/XCEngine/RHI/RHIFramebuffer/IsValid.md +++ b/docs/api/XCEngine/RHI/RHIFramebuffer/IsValid.md @@ -1,30 +1,25 @@ # RHIFramebuffer::IsValid -查询当前状态。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIFramebuffer.h` + +## 签名 ```cpp virtual bool IsValid() const = 0; ``` -该方法声明于 `XCEngine/RHI/RHIFramebuffer.h`，当前页面用于固定 `RHIFramebuffer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIFramebuffer object; - // 根据上下文补齐参数后调用 RHIFramebuffer::IsValid(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIFramebuffer.md) -- [返回模块目录](../RHI.md) +- [RHIFramebuffer](RHIFramebuffer.md) diff --git a/docs/api/XCEngine/RHI/RHIFramebuffer/Shutdown.md b/docs/api/XCEngine/RHI/RHIFramebuffer/Shutdown.md index a2db2388..9883e9df 100644 --- a/docs/api/XCEngine/RHI/RHIFramebuffer/Shutdown.md +++ b/docs/api/XCEngine/RHI/RHIFramebuffer/Shutdown.md @@ -1,30 +1,25 @@ # RHIFramebuffer::Shutdown -关闭并清理内部状态。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIFramebuffer.h` + +## 签名 ```cpp virtual void Shutdown() = 0; ``` -该方法声明于 `XCEngine/RHI/RHIFramebuffer.h`，当前页面用于固定 `RHIFramebuffer` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIFramebuffer object; - // 根据上下文补齐参数后调用 RHIFramebuffer::Shutdown(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIFramebuffer.md) -- [返回模块目录](../RHI.md) +- [RHIFramebuffer](RHIFramebuffer.md) diff --git a/docs/api/XCEngine/RHI/RHIPipelineLayout/Destructor.md b/docs/api/XCEngine/RHI/RHIPipelineLayout/Destructor.md index 2b05183f..2b836eee 100644 --- a/docs/api/XCEngine/RHI/RHIPipelineLayout/Destructor.md +++ b/docs/api/XCEngine/RHI/RHIPipelineLayout/Destructor.md @@ -1,29 +1,25 @@ # RHIPipelineLayout::~RHIPipelineLayout() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIPipelineLayout.h` + +## 签名 ```cpp virtual ~RHIPipelineLayout() = default; ``` -该方法声明于 `XCEngine/RHI/RHIPipelineLayout.h`，当前页面用于固定 `RHIPipelineLayout` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +销毁 `RHIPipelineLayout` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIPipelineLayout object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 当前为默认析构实现。 ## 相关文档 -- [返回类总览](RHIPipelineLayout.md) -- [返回模块目录](../RHI.md) +- [RHIPipelineLayout](RHIPipelineLayout.md) diff --git a/docs/api/XCEngine/RHI/RHIPipelineLayout/GetNativeHandle.md b/docs/api/XCEngine/RHI/RHIPipelineLayout/GetNativeHandle.md index ed0bb3de..74727b1d 100644 --- a/docs/api/XCEngine/RHI/RHIPipelineLayout/GetNativeHandle.md +++ b/docs/api/XCEngine/RHI/RHIPipelineLayout/GetNativeHandle.md @@ -1,30 +1,25 @@ # RHIPipelineLayout::GetNativeHandle -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIPipelineLayout.h` + +## 签名 ```cpp virtual void* GetNativeHandle() = 0; ``` -该方法声明于 `XCEngine/RHI/RHIPipelineLayout.h`，当前页面用于固定 `RHIPipelineLayout` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `void*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIPipelineLayout object; - // 根据上下文补齐参数后调用 RHIPipelineLayout::GetNativeHandle(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIPipelineLayout.md) -- [返回模块目录](../RHI.md) +- [RHIPipelineLayout](RHIPipelineLayout.md) diff --git a/docs/api/XCEngine/RHI/RHIPipelineLayout/Initialize.md b/docs/api/XCEngine/RHI/RHIPipelineLayout/Initialize.md index 478694fd..c08074a1 100644 --- a/docs/api/XCEngine/RHI/RHIPipelineLayout/Initialize.md +++ b/docs/api/XCEngine/RHI/RHIPipelineLayout/Initialize.md @@ -1,31 +1,25 @@ # RHIPipelineLayout::Initialize -初始化内部状态。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIPipelineLayout.h` + +## 签名 ```cpp virtual bool Initialize(const RHIPipelineLayoutDesc& desc) = 0; ``` -该方法声明于 `XCEngine/RHI/RHIPipelineLayout.h`，当前页面用于固定 `RHIPipelineLayout` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `desc` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIPipelineLayout object; - // 根据上下文补齐参数后调用 RHIPipelineLayout::Initialize(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIPipelineLayout.md) -- [返回模块目录](../RHI.md) +- [RHIPipelineLayout](RHIPipelineLayout.md) diff --git a/docs/api/XCEngine/RHI/RHIPipelineLayout/Shutdown.md b/docs/api/XCEngine/RHI/RHIPipelineLayout/Shutdown.md index 7a32ac9f..085279cc 100644 --- a/docs/api/XCEngine/RHI/RHIPipelineLayout/Shutdown.md +++ b/docs/api/XCEngine/RHI/RHIPipelineLayout/Shutdown.md @@ -1,30 +1,25 @@ # RHIPipelineLayout::Shutdown -关闭并清理内部状态。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIPipelineLayout.h` + +## 签名 ```cpp virtual void Shutdown() = 0; ``` -该方法声明于 `XCEngine/RHI/RHIPipelineLayout.h`，当前页面用于固定 `RHIPipelineLayout` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIPipelineLayout object; - // 根据上下文补齐参数后调用 RHIPipelineLayout::Shutdown(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIPipelineLayout.md) -- [返回模块目录](../RHI.md) +- [RHIPipelineLayout](RHIPipelineLayout.md) diff --git a/docs/api/XCEngine/RHI/RHIPipelineState/Bind.md b/docs/api/XCEngine/RHI/RHIPipelineState/Bind.md index 5a9ab491..d875a760 100644 --- a/docs/api/XCEngine/RHI/RHIPipelineState/Bind.md +++ b/docs/api/XCEngine/RHI/RHIPipelineState/Bind.md @@ -1,30 +1,25 @@ # RHIPipelineState::Bind -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIPipelineState.h` + +## 签名 ```cpp virtual void Bind() = 0; ``` -该方法声明于 `XCEngine/RHI/RHIPipelineState.h`，当前页面用于固定 `RHIPipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIPipelineState object; - // 根据上下文补齐参数后调用 RHIPipelineState::Bind(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIPipelineState.md) -- [返回模块目录](../RHI.md) +- [RHIPipelineState](RHIPipelineState.md) diff --git a/docs/api/XCEngine/RHI/RHIPipelineState/Destructor.md b/docs/api/XCEngine/RHI/RHIPipelineState/Destructor.md index 14715537..44afd124 100644 --- a/docs/api/XCEngine/RHI/RHIPipelineState/Destructor.md +++ b/docs/api/XCEngine/RHI/RHIPipelineState/Destructor.md @@ -1,29 +1,25 @@ # RHIPipelineState::~RHIPipelineState() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIPipelineState.h` + +## 签名 ```cpp virtual ~RHIPipelineState() = default; ``` -该方法声明于 `XCEngine/RHI/RHIPipelineState.h`，当前页面用于固定 `RHIPipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +销毁 `RHIPipelineState` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIPipelineState object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 当前为默认析构实现。 ## 相关文档 -- [返回类总览](RHIPipelineState.md) -- [返回模块目录](../RHI.md) +- [RHIPipelineState](RHIPipelineState.md) diff --git a/docs/api/XCEngine/RHI/RHIPipelineState/EnsureValid.md b/docs/api/XCEngine/RHI/RHIPipelineState/EnsureValid.md index f7091fbe..837a12da 100644 --- a/docs/api/XCEngine/RHI/RHIPipelineState/EnsureValid.md +++ b/docs/api/XCEngine/RHI/RHIPipelineState/EnsureValid.md @@ -1,30 +1,25 @@ # RHIPipelineState::EnsureValid -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIPipelineState.h` + +## 签名 ```cpp virtual void EnsureValid() = 0; ``` -该方法声明于 `XCEngine/RHI/RHIPipelineState.h`，当前页面用于固定 `RHIPipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIPipelineState object; - // 根据上下文补齐参数后调用 RHIPipelineState::EnsureValid(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIPipelineState.md) -- [返回模块目录](../RHI.md) +- [RHIPipelineState](RHIPipelineState.md) diff --git a/docs/api/XCEngine/RHI/RHIPipelineState/GetBlendState.md b/docs/api/XCEngine/RHI/RHIPipelineState/GetBlendState.md index 8fc8de98..d2643650 100644 --- a/docs/api/XCEngine/RHI/RHIPipelineState/GetBlendState.md +++ b/docs/api/XCEngine/RHI/RHIPipelineState/GetBlendState.md @@ -1,30 +1,26 @@ # RHIPipelineState::GetBlendState -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIPipelineState.h` + +## 签名 ```cpp virtual const BlendDesc& GetBlendState() const = 0; ``` -该方法声明于 `XCEngine/RHI/RHIPipelineState.h`，当前页面用于固定 `RHIPipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `const BlendDesc&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIPipelineState object; - // 根据上下文补齐参数后调用 RHIPipelineState::GetBlendState(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIPipelineState.md) -- [返回模块目录](../RHI.md) +- [RHIPipelineState](RHIPipelineState.md) +- [SetBlendState](SetBlendState.md) diff --git a/docs/api/XCEngine/RHI/RHIPipelineState/GetComputeShader.md b/docs/api/XCEngine/RHI/RHIPipelineState/GetComputeShader.md index 8ed9025e..370faf90 100644 --- a/docs/api/XCEngine/RHI/RHIPipelineState/GetComputeShader.md +++ b/docs/api/XCEngine/RHI/RHIPipelineState/GetComputeShader.md @@ -1,30 +1,26 @@ # RHIPipelineState::GetComputeShader -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIPipelineState.h` + +## 签名 ```cpp virtual RHIShader* GetComputeShader() const = 0; ``` -该方法声明于 `XCEngine/RHI/RHIPipelineState.h`，当前页面用于固定 `RHIPipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `RHIShader*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIPipelineState object; - // 根据上下文补齐参数后调用 RHIPipelineState::GetComputeShader(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIPipelineState.md) -- [返回模块目录](../RHI.md) +- [RHIPipelineState](RHIPipelineState.md) +- [SetComputeShader](SetComputeShader.md) diff --git a/docs/api/XCEngine/RHI/RHIPipelineState/GetDepthStencilState.md b/docs/api/XCEngine/RHI/RHIPipelineState/GetDepthStencilState.md index bffb5934..fc8c74f4 100644 --- a/docs/api/XCEngine/RHI/RHIPipelineState/GetDepthStencilState.md +++ b/docs/api/XCEngine/RHI/RHIPipelineState/GetDepthStencilState.md @@ -1,30 +1,26 @@ # RHIPipelineState::GetDepthStencilState -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIPipelineState.h` + +## 签名 ```cpp virtual const DepthStencilStateDesc& GetDepthStencilState() const = 0; ``` -该方法声明于 `XCEngine/RHI/RHIPipelineState.h`，当前页面用于固定 `RHIPipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `const DepthStencilStateDesc&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIPipelineState object; - // 根据上下文补齐参数后调用 RHIPipelineState::GetDepthStencilState(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIPipelineState.md) -- [返回模块目录](../RHI.md) +- [RHIPipelineState](RHIPipelineState.md) +- [SetDepthStencilState](SetDepthStencilState.md) diff --git a/docs/api/XCEngine/RHI/RHIPipelineState/GetHash.md b/docs/api/XCEngine/RHI/RHIPipelineState/GetHash.md index 2cbfc9a5..d48058fe 100644 --- a/docs/api/XCEngine/RHI/RHIPipelineState/GetHash.md +++ b/docs/api/XCEngine/RHI/RHIPipelineState/GetHash.md @@ -1,30 +1,25 @@ # RHIPipelineState::GetHash -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIPipelineState.h` + +## 签名 ```cpp virtual PipelineStateHash GetHash() const = 0; ``` -该方法声明于 `XCEngine/RHI/RHIPipelineState.h`，当前页面用于固定 `RHIPipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `PipelineStateHash` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIPipelineState object; - // 根据上下文补齐参数后调用 RHIPipelineState::GetHash(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIPipelineState.md) -- [返回模块目录](../RHI.md) +- [RHIPipelineState](RHIPipelineState.md) diff --git a/docs/api/XCEngine/RHI/RHIPipelineState/GetInputLayout.md b/docs/api/XCEngine/RHI/RHIPipelineState/GetInputLayout.md index b409ec56..78630f8f 100644 --- a/docs/api/XCEngine/RHI/RHIPipelineState/GetInputLayout.md +++ b/docs/api/XCEngine/RHI/RHIPipelineState/GetInputLayout.md @@ -1,30 +1,26 @@ # RHIPipelineState::GetInputLayout -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIPipelineState.h` + +## 签名 ```cpp virtual const InputLayoutDesc& GetInputLayout() const = 0; ``` -该方法声明于 `XCEngine/RHI/RHIPipelineState.h`，当前页面用于固定 `RHIPipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `const InputLayoutDesc&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIPipelineState object; - // 根据上下文补齐参数后调用 RHIPipelineState::GetInputLayout(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIPipelineState.md) -- [返回模块目录](../RHI.md) +- [RHIPipelineState](RHIPipelineState.md) +- [SetInputLayout](SetInputLayout.md) diff --git a/docs/api/XCEngine/RHI/RHIPipelineState/GetNativeHandle.md b/docs/api/XCEngine/RHI/RHIPipelineState/GetNativeHandle.md index 20b62a90..759d764c 100644 --- a/docs/api/XCEngine/RHI/RHIPipelineState/GetNativeHandle.md +++ b/docs/api/XCEngine/RHI/RHIPipelineState/GetNativeHandle.md @@ -1,30 +1,25 @@ # RHIPipelineState::GetNativeHandle -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIPipelineState.h` + +## 签名 ```cpp virtual void* GetNativeHandle() = 0; ``` -该方法声明于 `XCEngine/RHI/RHIPipelineState.h`，当前页面用于固定 `RHIPipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `void*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIPipelineState object; - // 根据上下文补齐参数后调用 RHIPipelineState::GetNativeHandle(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIPipelineState.md) -- [返回模块目录](../RHI.md) +- [RHIPipelineState](RHIPipelineState.md) diff --git a/docs/api/XCEngine/RHI/RHIPipelineState/GetRasterizerState.md b/docs/api/XCEngine/RHI/RHIPipelineState/GetRasterizerState.md index f91c49f2..8c6b27ae 100644 --- a/docs/api/XCEngine/RHI/RHIPipelineState/GetRasterizerState.md +++ b/docs/api/XCEngine/RHI/RHIPipelineState/GetRasterizerState.md @@ -1,30 +1,26 @@ # RHIPipelineState::GetRasterizerState -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIPipelineState.h` + +## 签名 ```cpp virtual const RasterizerDesc& GetRasterizerState() const = 0; ``` -该方法声明于 `XCEngine/RHI/RHIPipelineState.h`，当前页面用于固定 `RHIPipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `const RasterizerDesc&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIPipelineState object; - // 根据上下文补齐参数后调用 RHIPipelineState::GetRasterizerState(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIPipelineState.md) -- [返回模块目录](../RHI.md) +- [RHIPipelineState](RHIPipelineState.md) +- [SetRasterizerState](SetRasterizerState.md) diff --git a/docs/api/XCEngine/RHI/RHIPipelineState/GetType.md b/docs/api/XCEngine/RHI/RHIPipelineState/GetType.md index 58eb1ad7..81661419 100644 --- a/docs/api/XCEngine/RHI/RHIPipelineState/GetType.md +++ b/docs/api/XCEngine/RHI/RHIPipelineState/GetType.md @@ -1,30 +1,25 @@ # RHIPipelineState::GetType -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIPipelineState.h` + +## 签名 ```cpp virtual PipelineType GetType() const = 0; ``` -该方法声明于 `XCEngine/RHI/RHIPipelineState.h`，当前页面用于固定 `RHIPipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `PipelineType` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIPipelineState object; - // 根据上下文补齐参数后调用 RHIPipelineState::GetType(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIPipelineState.md) -- [返回模块目录](../RHI.md) +- [RHIPipelineState](RHIPipelineState.md) diff --git a/docs/api/XCEngine/RHI/RHIPipelineState/HasComputeShader.md b/docs/api/XCEngine/RHI/RHIPipelineState/HasComputeShader.md index afa0546c..afd7b1fc 100644 --- a/docs/api/XCEngine/RHI/RHIPipelineState/HasComputeShader.md +++ b/docs/api/XCEngine/RHI/RHIPipelineState/HasComputeShader.md @@ -1,30 +1,25 @@ # RHIPipelineState::HasComputeShader -判断是否具备指定状态或能力。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIPipelineState.h` + +## 签名 ```cpp virtual bool HasComputeShader() const = 0; ``` -该方法声明于 `XCEngine/RHI/RHIPipelineState.h`，当前页面用于固定 `RHIPipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIPipelineState object; - // 根据上下文补齐参数后调用 RHIPipelineState::HasComputeShader(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIPipelineState.md) -- [返回模块目录](../RHI.md) +- [RHIPipelineState](RHIPipelineState.md) diff --git a/docs/api/XCEngine/RHI/RHIPipelineState/IsValid.md b/docs/api/XCEngine/RHI/RHIPipelineState/IsValid.md index 9e4ca5e0..18a1e089 100644 --- a/docs/api/XCEngine/RHI/RHIPipelineState/IsValid.md +++ b/docs/api/XCEngine/RHI/RHIPipelineState/IsValid.md @@ -1,30 +1,25 @@ # RHIPipelineState::IsValid -查询当前状态。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIPipelineState.h` + +## 签名 ```cpp virtual bool IsValid() const = 0; ``` -该方法声明于 `XCEngine/RHI/RHIPipelineState.h`，当前页面用于固定 `RHIPipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIPipelineState object; - // 根据上下文补齐参数后调用 RHIPipelineState::IsValid(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIPipelineState.md) -- [返回模块目录](../RHI.md) +- [RHIPipelineState](RHIPipelineState.md) diff --git a/docs/api/XCEngine/RHI/RHIPipelineState/SetBlendState.md b/docs/api/XCEngine/RHI/RHIPipelineState/SetBlendState.md index 6d072543..5f9ea71f 100644 --- a/docs/api/XCEngine/RHI/RHIPipelineState/SetBlendState.md +++ b/docs/api/XCEngine/RHI/RHIPipelineState/SetBlendState.md @@ -1,31 +1,26 @@ # RHIPipelineState::SetBlendState -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIPipelineState.h` + +## 签名 ```cpp virtual void SetBlendState(const BlendDesc& state) = 0; ``` -该方法声明于 `XCEngine/RHI/RHIPipelineState.h`，当前页面用于固定 `RHIPipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `state` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIPipelineState object; - // 根据上下文补齐参数后调用 RHIPipelineState::SetBlendState(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIPipelineState.md) -- [返回模块目录](../RHI.md) +- [RHIPipelineState](RHIPipelineState.md) +- [GetBlendState](GetBlendState.md) diff --git a/docs/api/XCEngine/RHI/RHIPipelineState/SetComputeShader.md b/docs/api/XCEngine/RHI/RHIPipelineState/SetComputeShader.md index ee43fd5a..8adfc8a2 100644 --- a/docs/api/XCEngine/RHI/RHIPipelineState/SetComputeShader.md +++ b/docs/api/XCEngine/RHI/RHIPipelineState/SetComputeShader.md @@ -1,31 +1,26 @@ # RHIPipelineState::SetComputeShader -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIPipelineState.h` + +## 签名 ```cpp virtual void SetComputeShader(RHIShader* shader) = 0; ``` -该方法声明于 `XCEngine/RHI/RHIPipelineState.h`，当前页面用于固定 `RHIPipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `shader` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIPipelineState object; - // 根据上下文补齐参数后调用 RHIPipelineState::SetComputeShader(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIPipelineState.md) -- [返回模块目录](../RHI.md) +- [RHIPipelineState](RHIPipelineState.md) +- [GetComputeShader](GetComputeShader.md) diff --git a/docs/api/XCEngine/RHI/RHIPipelineState/SetDepthStencilState.md b/docs/api/XCEngine/RHI/RHIPipelineState/SetDepthStencilState.md index 9646889e..5eeedc95 100644 --- a/docs/api/XCEngine/RHI/RHIPipelineState/SetDepthStencilState.md +++ b/docs/api/XCEngine/RHI/RHIPipelineState/SetDepthStencilState.md @@ -1,31 +1,26 @@ # RHIPipelineState::SetDepthStencilState -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIPipelineState.h` + +## 签名 ```cpp virtual void SetDepthStencilState(const DepthStencilStateDesc& state) = 0; ``` -该方法声明于 `XCEngine/RHI/RHIPipelineState.h`，当前页面用于固定 `RHIPipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `state` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIPipelineState object; - // 根据上下文补齐参数后调用 RHIPipelineState::SetDepthStencilState(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIPipelineState.md) -- [返回模块目录](../RHI.md) +- [RHIPipelineState](RHIPipelineState.md) +- [GetDepthStencilState](GetDepthStencilState.md) diff --git a/docs/api/XCEngine/RHI/RHIPipelineState/SetInputLayout.md b/docs/api/XCEngine/RHI/RHIPipelineState/SetInputLayout.md index ccf12fd5..8d8395d5 100644 --- a/docs/api/XCEngine/RHI/RHIPipelineState/SetInputLayout.md +++ b/docs/api/XCEngine/RHI/RHIPipelineState/SetInputLayout.md @@ -1,31 +1,26 @@ # RHIPipelineState::SetInputLayout -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIPipelineState.h` + +## 签名 ```cpp virtual void SetInputLayout(const InputLayoutDesc& layout) = 0; ``` -该方法声明于 `XCEngine/RHI/RHIPipelineState.h`，当前页面用于固定 `RHIPipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `layout` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIPipelineState object; - // 根据上下文补齐参数后调用 RHIPipelineState::SetInputLayout(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIPipelineState.md) -- [返回模块目录](../RHI.md) +- [RHIPipelineState](RHIPipelineState.md) +- [GetInputLayout](GetInputLayout.md) diff --git a/docs/api/XCEngine/RHI/RHIPipelineState/SetRasterizerState.md b/docs/api/XCEngine/RHI/RHIPipelineState/SetRasterizerState.md index 9483e4ad..74757a85 100644 --- a/docs/api/XCEngine/RHI/RHIPipelineState/SetRasterizerState.md +++ b/docs/api/XCEngine/RHI/RHIPipelineState/SetRasterizerState.md @@ -1,31 +1,26 @@ # RHIPipelineState::SetRasterizerState -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIPipelineState.h` + +## 签名 ```cpp virtual void SetRasterizerState(const RasterizerDesc& state) = 0; ``` -该方法声明于 `XCEngine/RHI/RHIPipelineState.h`，当前页面用于固定 `RHIPipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `state` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIPipelineState object; - // 根据上下文补齐参数后调用 RHIPipelineState::SetRasterizerState(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIPipelineState.md) -- [返回模块目录](../RHI.md) +- [RHIPipelineState](RHIPipelineState.md) +- [GetRasterizerState](GetRasterizerState.md) diff --git a/docs/api/XCEngine/RHI/RHIPipelineState/SetRenderTargetFormats.md b/docs/api/XCEngine/RHI/RHIPipelineState/SetRenderTargetFormats.md index 4b18ae9a..de5de161 100644 --- a/docs/api/XCEngine/RHI/RHIPipelineState/SetRenderTargetFormats.md +++ b/docs/api/XCEngine/RHI/RHIPipelineState/SetRenderTargetFormats.md @@ -1,33 +1,25 @@ # RHIPipelineState::SetRenderTargetFormats -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIPipelineState.h` + +## 签名 ```cpp virtual void SetRenderTargetFormats(uint32_t count, const uint32_t* formats, uint32_t depthFormat) = 0; ``` -该方法声明于 `XCEngine/RHI/RHIPipelineState.h`，当前页面用于固定 `RHIPipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `count` - 参数语义详见头文件声明。 -- `formats` - 参数语义详见头文件声明。 -- `depthFormat` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIPipelineState object; - // 根据上下文补齐参数后调用 RHIPipelineState::SetRenderTargetFormats(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIPipelineState.md) -- [返回模块目录](../RHI.md) +- [RHIPipelineState](RHIPipelineState.md) diff --git a/docs/api/XCEngine/RHI/RHIPipelineState/SetSampleCount.md b/docs/api/XCEngine/RHI/RHIPipelineState/SetSampleCount.md index 7657920e..96efd0d4 100644 --- a/docs/api/XCEngine/RHI/RHIPipelineState/SetSampleCount.md +++ b/docs/api/XCEngine/RHI/RHIPipelineState/SetSampleCount.md @@ -1,31 +1,25 @@ # RHIPipelineState::SetSampleCount -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIPipelineState.h` + +## 签名 ```cpp virtual void SetSampleCount(uint32_t count) = 0; ``` -该方法声明于 `XCEngine/RHI/RHIPipelineState.h`，当前页面用于固定 `RHIPipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `count` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIPipelineState object; - // 根据上下文补齐参数后调用 RHIPipelineState::SetSampleCount(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIPipelineState.md) -- [返回模块目录](../RHI.md) +- [RHIPipelineState](RHIPipelineState.md) diff --git a/docs/api/XCEngine/RHI/RHIPipelineState/SetTopology.md b/docs/api/XCEngine/RHI/RHIPipelineState/SetTopology.md index 8e9998c2..35a67db0 100644 --- a/docs/api/XCEngine/RHI/RHIPipelineState/SetTopology.md +++ b/docs/api/XCEngine/RHI/RHIPipelineState/SetTopology.md @@ -1,31 +1,25 @@ # RHIPipelineState::SetTopology -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIPipelineState.h` + +## 签名 ```cpp virtual void SetTopology(uint32_t topologyType) = 0; ``` -该方法声明于 `XCEngine/RHI/RHIPipelineState.h`，当前页面用于固定 `RHIPipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `topologyType` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIPipelineState object; - // 根据上下文补齐参数后调用 RHIPipelineState::SetTopology(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIPipelineState.md) -- [返回模块目录](../RHI.md) +- [RHIPipelineState](RHIPipelineState.md) diff --git a/docs/api/XCEngine/RHI/RHIPipelineState/Shutdown.md b/docs/api/XCEngine/RHI/RHIPipelineState/Shutdown.md index 5f912c34..bb02be28 100644 --- a/docs/api/XCEngine/RHI/RHIPipelineState/Shutdown.md +++ b/docs/api/XCEngine/RHI/RHIPipelineState/Shutdown.md @@ -1,30 +1,25 @@ # RHIPipelineState::Shutdown -关闭并清理内部状态。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIPipelineState.h` + +## 签名 ```cpp virtual void Shutdown() = 0; ``` -该方法声明于 `XCEngine/RHI/RHIPipelineState.h`，当前页面用于固定 `RHIPipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIPipelineState object; - // 根据上下文补齐参数后调用 RHIPipelineState::Shutdown(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIPipelineState.md) -- [返回模块目录](../RHI.md) +- [RHIPipelineState](RHIPipelineState.md) diff --git a/docs/api/XCEngine/RHI/RHIPipelineState/Unbind.md b/docs/api/XCEngine/RHI/RHIPipelineState/Unbind.md index 96b84ea9..828d87d1 100644 --- a/docs/api/XCEngine/RHI/RHIPipelineState/Unbind.md +++ b/docs/api/XCEngine/RHI/RHIPipelineState/Unbind.md @@ -1,30 +1,25 @@ # RHIPipelineState::Unbind -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIPipelineState.h` + +## 签名 ```cpp virtual void Unbind() = 0; ``` -该方法声明于 `XCEngine/RHI/RHIPipelineState.h`，当前页面用于固定 `RHIPipelineState` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIPipelineState object; - // 根据上下文补齐参数后调用 RHIPipelineState::Unbind(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIPipelineState.md) -- [返回模块目录](../RHI.md) +- [RHIPipelineState](RHIPipelineState.md) diff --git a/docs/api/XCEngine/RHI/RHIRenderPass/Destructor.md b/docs/api/XCEngine/RHI/RHIRenderPass/Destructor.md index 983339cc..1471f9f2 100644 --- a/docs/api/XCEngine/RHI/RHIRenderPass/Destructor.md +++ b/docs/api/XCEngine/RHI/RHIRenderPass/Destructor.md @@ -1,29 +1,25 @@ # RHIRenderPass::~RHIRenderPass() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIRenderPass.h` + +## 签名 ```cpp virtual ~RHIRenderPass() = default; ``` -该方法声明于 `XCEngine/RHI/RHIRenderPass.h`，当前页面用于固定 `RHIRenderPass` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +销毁 `RHIRenderPass` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIRenderPass object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 当前为默认析构实现。 ## 相关文档 -- [返回类总览](RHIRenderPass.md) -- [返回模块目录](../RHI.md) +- [RHIRenderPass](RHIRenderPass.md) diff --git a/docs/api/XCEngine/RHI/RHIRenderPass/GetColorAttachmentCount.md b/docs/api/XCEngine/RHI/RHIRenderPass/GetColorAttachmentCount.md index d7df58b7..8706dbe1 100644 --- a/docs/api/XCEngine/RHI/RHIRenderPass/GetColorAttachmentCount.md +++ b/docs/api/XCEngine/RHI/RHIRenderPass/GetColorAttachmentCount.md @@ -1,30 +1,25 @@ # RHIRenderPass::GetColorAttachmentCount -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIRenderPass.h` + +## 签名 ```cpp virtual uint32_t GetColorAttachmentCount() const = 0; ``` -该方法声明于 `XCEngine/RHI/RHIRenderPass.h`，当前页面用于固定 `RHIRenderPass` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `uint32_t` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIRenderPass object; - // 根据上下文补齐参数后调用 RHIRenderPass::GetColorAttachmentCount(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIRenderPass.md) -- [返回模块目录](../RHI.md) +- [RHIRenderPass](RHIRenderPass.md) diff --git a/docs/api/XCEngine/RHI/RHIRenderPass/GetColorAttachments.md b/docs/api/XCEngine/RHI/RHIRenderPass/GetColorAttachments.md index afb086f9..44cfec9e 100644 --- a/docs/api/XCEngine/RHI/RHIRenderPass/GetColorAttachments.md +++ b/docs/api/XCEngine/RHI/RHIRenderPass/GetColorAttachments.md @@ -1,30 +1,25 @@ # RHIRenderPass::GetColorAttachments -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIRenderPass.h` + +## 签名 ```cpp virtual const AttachmentDesc* GetColorAttachments() const = 0; ``` -该方法声明于 `XCEngine/RHI/RHIRenderPass.h`，当前页面用于固定 `RHIRenderPass` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `const AttachmentDesc*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIRenderPass object; - // 根据上下文补齐参数后调用 RHIRenderPass::GetColorAttachments(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIRenderPass.md) -- [返回模块目录](../RHI.md) +- [RHIRenderPass](RHIRenderPass.md) diff --git a/docs/api/XCEngine/RHI/RHIRenderPass/GetDepthStencilAttachment.md b/docs/api/XCEngine/RHI/RHIRenderPass/GetDepthStencilAttachment.md index 2926f209..39d0a51e 100644 --- a/docs/api/XCEngine/RHI/RHIRenderPass/GetDepthStencilAttachment.md +++ b/docs/api/XCEngine/RHI/RHIRenderPass/GetDepthStencilAttachment.md @@ -1,30 +1,25 @@ # RHIRenderPass::GetDepthStencilAttachment -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIRenderPass.h` + +## 签名 ```cpp virtual const AttachmentDesc* GetDepthStencilAttachment() const = 0; ``` -该方法声明于 `XCEngine/RHI/RHIRenderPass.h`，当前页面用于固定 `RHIRenderPass` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `const AttachmentDesc*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIRenderPass object; - // 根据上下文补齐参数后调用 RHIRenderPass::GetDepthStencilAttachment(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIRenderPass.md) -- [返回模块目录](../RHI.md) +- [RHIRenderPass](RHIRenderPass.md) diff --git a/docs/api/XCEngine/RHI/RHIRenderPass/GetNativeHandle.md b/docs/api/XCEngine/RHI/RHIRenderPass/GetNativeHandle.md index 204f8605..09736d53 100644 --- a/docs/api/XCEngine/RHI/RHIRenderPass/GetNativeHandle.md +++ b/docs/api/XCEngine/RHI/RHIRenderPass/GetNativeHandle.md @@ -1,30 +1,25 @@ # RHIRenderPass::GetNativeHandle -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIRenderPass.h` + +## 签名 ```cpp virtual void* GetNativeHandle() = 0; ``` -该方法声明于 `XCEngine/RHI/RHIRenderPass.h`，当前页面用于固定 `RHIRenderPass` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `void*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIRenderPass object; - // 根据上下文补齐参数后调用 RHIRenderPass::GetNativeHandle(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIRenderPass.md) -- [返回模块目录](../RHI.md) +- [RHIRenderPass](RHIRenderPass.md) diff --git a/docs/api/XCEngine/RHI/RHIRenderPass/Initialize.md b/docs/api/XCEngine/RHI/RHIRenderPass/Initialize.md index 7f3bfe21..d0e42f7f 100644 --- a/docs/api/XCEngine/RHI/RHIRenderPass/Initialize.md +++ b/docs/api/XCEngine/RHI/RHIRenderPass/Initialize.md @@ -1,33 +1,25 @@ # RHIRenderPass::Initialize -初始化内部状态。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIRenderPass.h` + +## 签名 ```cpp virtual bool Initialize(uint32_t colorAttachmentCount, const AttachmentDesc* colorAttachments, const AttachmentDesc* depthStencilAttachment) = 0; ``` -该方法声明于 `XCEngine/RHI/RHIRenderPass.h`，当前页面用于固定 `RHIRenderPass` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `colorAttachmentCount` - 参数语义详见头文件声明。 -- `colorAttachments` - 参数语义详见头文件声明。 -- `depthStencilAttachment` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIRenderPass object; - // 根据上下文补齐参数后调用 RHIRenderPass::Initialize(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIRenderPass.md) -- [返回模块目录](../RHI.md) +- [RHIRenderPass](RHIRenderPass.md) diff --git a/docs/api/XCEngine/RHI/RHIRenderPass/Shutdown.md b/docs/api/XCEngine/RHI/RHIRenderPass/Shutdown.md index 6be0a864..b981df1b 100644 --- a/docs/api/XCEngine/RHI/RHIRenderPass/Shutdown.md +++ b/docs/api/XCEngine/RHI/RHIRenderPass/Shutdown.md @@ -1,30 +1,25 @@ # RHIRenderPass::Shutdown -关闭并清理内部状态。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIRenderPass.h` + +## 签名 ```cpp virtual void Shutdown() = 0; ``` -该方法声明于 `XCEngine/RHI/RHIRenderPass.h`，当前页面用于固定 `RHIRenderPass` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIRenderPass object; - // 根据上下文补齐参数后调用 RHIRenderPass::Shutdown(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIRenderPass.md) -- [返回模块目录](../RHI.md) +- [RHIRenderPass](RHIRenderPass.md) diff --git a/docs/api/XCEngine/RHI/RHIResource/Destructor.md b/docs/api/XCEngine/RHI/RHIResource/Destructor.md index e1115b1e..0dae9774 100644 --- a/docs/api/XCEngine/RHI/RHIResource/Destructor.md +++ b/docs/api/XCEngine/RHI/RHIResource/Destructor.md @@ -1,29 +1,25 @@ # RHIResource::~RHIResource() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIResource.h` + +## 签名 ```cpp virtual ~RHIResource() = default; ``` -该方法声明于 `XCEngine/RHI/RHIResource.h`，当前页面用于固定 `RHIResource` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +销毁 `RHIResource` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIResource object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 当前为默认析构实现。 ## 相关文档 -- [返回类总览](RHIResource.md) -- [返回模块目录](../RHI.md) +- [RHIResource](RHIResource.md) diff --git a/docs/api/XCEngine/RHI/RHIResource/GetNativeHandle.md b/docs/api/XCEngine/RHI/RHIResource/GetNativeHandle.md index 77c4b004..7920d2a2 100644 --- a/docs/api/XCEngine/RHI/RHIResource/GetNativeHandle.md +++ b/docs/api/XCEngine/RHI/RHIResource/GetNativeHandle.md @@ -1,30 +1,25 @@ # RHIResource::GetNativeHandle -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIResource.h` + +## 签名 ```cpp virtual void* GetNativeHandle() = 0; ``` -该方法声明于 `XCEngine/RHI/RHIResource.h`，当前页面用于固定 `RHIResource` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `void*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIResource object; - // 根据上下文补齐参数后调用 RHIResource::GetNativeHandle(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIResource.md) -- [返回模块目录](../RHI.md) +- [RHIResource](RHIResource.md) diff --git a/docs/api/XCEngine/RHI/RHIResource/GetState.md b/docs/api/XCEngine/RHI/RHIResource/GetState.md index be17d6ec..0359dd79 100644 --- a/docs/api/XCEngine/RHI/RHIResource/GetState.md +++ b/docs/api/XCEngine/RHI/RHIResource/GetState.md @@ -1,30 +1,26 @@ # RHIResource::GetState -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIResource.h` + +## 签名 ```cpp virtual ResourceStates GetState() const = 0; ``` -该方法声明于 `XCEngine/RHI/RHIResource.h`，当前页面用于固定 `RHIResource` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `ResourceStates` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIResource object; - // 根据上下文补齐参数后调用 RHIResource::GetState(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIResource.md) -- [返回模块目录](../RHI.md) +- [RHIResource](RHIResource.md) +- [SetState](SetState.md) diff --git a/docs/api/XCEngine/RHI/RHIResource/SetState.md b/docs/api/XCEngine/RHI/RHIResource/SetState.md index 8c5a4f77..b3eb7227 100644 --- a/docs/api/XCEngine/RHI/RHIResource/SetState.md +++ b/docs/api/XCEngine/RHI/RHIResource/SetState.md @@ -1,31 +1,26 @@ # RHIResource::SetState -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIResource.h` + +## 签名 ```cpp virtual void SetState(ResourceStates state) = 0; ``` -该方法声明于 `XCEngine/RHI/RHIResource.h`，当前页面用于固定 `RHIResource` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `state` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIResource object; - // 根据上下文补齐参数后调用 RHIResource::SetState(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIResource.md) -- [返回模块目录](../RHI.md) +- [RHIResource](RHIResource.md) +- [GetState](GetState.md) diff --git a/docs/api/XCEngine/RHI/RHIResourceView/Destructor.md b/docs/api/XCEngine/RHI/RHIResourceView/Destructor.md index 528328b8..f7b86048 100644 --- a/docs/api/XCEngine/RHI/RHIResourceView/Destructor.md +++ b/docs/api/XCEngine/RHI/RHIResourceView/Destructor.md @@ -1,29 +1,25 @@ # RHIResourceView::~RHIResourceView() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIResourceView.h` + +## 签名 ```cpp virtual ~RHIResourceView() = default; ``` -该方法声明于 `XCEngine/RHI/RHIResourceView.h`，当前页面用于固定 `RHIResourceView` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +销毁 `RHIResourceView` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIResourceView object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 当前为默认析构实现。 ## 相关文档 -- [返回类总览](RHIResourceView.md) -- [返回模块目录](../RHI.md) +- [RHIResourceView](RHIResourceView.md) diff --git a/docs/api/XCEngine/RHI/RHIResourceView/GetDimension.md b/docs/api/XCEngine/RHI/RHIResourceView/GetDimension.md index 3c3765f3..6725490f 100644 --- a/docs/api/XCEngine/RHI/RHIResourceView/GetDimension.md +++ b/docs/api/XCEngine/RHI/RHIResourceView/GetDimension.md @@ -1,30 +1,25 @@ # RHIResourceView::GetDimension -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIResourceView.h` + +## 签名 ```cpp virtual ResourceViewDimension GetDimension() const = 0; ``` -该方法声明于 `XCEngine/RHI/RHIResourceView.h`，当前页面用于固定 `RHIResourceView` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `ResourceViewDimension` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIResourceView object; - // 根据上下文补齐参数后调用 RHIResourceView::GetDimension(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIResourceView.md) -- [返回模块目录](../RHI.md) +- [RHIResourceView](RHIResourceView.md) diff --git a/docs/api/XCEngine/RHI/RHIResourceView/GetFormat.md b/docs/api/XCEngine/RHI/RHIResourceView/GetFormat.md index 4215bf42..55f83624 100644 --- a/docs/api/XCEngine/RHI/RHIResourceView/GetFormat.md +++ b/docs/api/XCEngine/RHI/RHIResourceView/GetFormat.md @@ -1,30 +1,25 @@ # RHIResourceView::GetFormat -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIResourceView.h` + +## 签名 ```cpp virtual Format GetFormat() const = 0; ``` -该方法声明于 `XCEngine/RHI/RHIResourceView.h`，当前页面用于固定 `RHIResourceView` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `Format` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIResourceView object; - // 根据上下文补齐参数后调用 RHIResourceView::GetFormat(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIResourceView.md) -- [返回模块目录](../RHI.md) +- [RHIResourceView](RHIResourceView.md) diff --git a/docs/api/XCEngine/RHI/RHIResourceView/GetNativeHandle.md b/docs/api/XCEngine/RHI/RHIResourceView/GetNativeHandle.md index edf0550d..3a02f858 100644 --- a/docs/api/XCEngine/RHI/RHIResourceView/GetNativeHandle.md +++ b/docs/api/XCEngine/RHI/RHIResourceView/GetNativeHandle.md @@ -1,30 +1,25 @@ # RHIResourceView::GetNativeHandle -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIResourceView.h` + +## 签名 ```cpp virtual void* GetNativeHandle() = 0; ``` -该方法声明于 `XCEngine/RHI/RHIResourceView.h`，当前页面用于固定 `RHIResourceView` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `void*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIResourceView object; - // 根据上下文补齐参数后调用 RHIResourceView::GetNativeHandle(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIResourceView.md) -- [返回模块目录](../RHI.md) +- [RHIResourceView](RHIResourceView.md) diff --git a/docs/api/XCEngine/RHI/RHIResourceView/GetViewType.md b/docs/api/XCEngine/RHI/RHIResourceView/GetViewType.md index 70291b11..f204c1c2 100644 --- a/docs/api/XCEngine/RHI/RHIResourceView/GetViewType.md +++ b/docs/api/XCEngine/RHI/RHIResourceView/GetViewType.md @@ -1,30 +1,25 @@ # RHIResourceView::GetViewType -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIResourceView.h` + +## 签名 ```cpp virtual ResourceViewType GetViewType() const = 0; ``` -该方法声明于 `XCEngine/RHI/RHIResourceView.h`，当前页面用于固定 `RHIResourceView` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `ResourceViewType` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIResourceView object; - // 根据上下文补齐参数后调用 RHIResourceView::GetViewType(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIResourceView.md) -- [返回模块目录](../RHI.md) +- [RHIResourceView](RHIResourceView.md) diff --git a/docs/api/XCEngine/RHI/RHIResourceView/IsValid.md b/docs/api/XCEngine/RHI/RHIResourceView/IsValid.md index 8b4d69a5..731bc6bd 100644 --- a/docs/api/XCEngine/RHI/RHIResourceView/IsValid.md +++ b/docs/api/XCEngine/RHI/RHIResourceView/IsValid.md @@ -1,30 +1,25 @@ # RHIResourceView::IsValid -查询当前状态。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIResourceView.h` + +## 签名 ```cpp virtual bool IsValid() const = 0; ``` -该方法声明于 `XCEngine/RHI/RHIResourceView.h`，当前页面用于固定 `RHIResourceView` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIResourceView object; - // 根据上下文补齐参数后调用 RHIResourceView::IsValid(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIResourceView.md) -- [返回模块目录](../RHI.md) +- [RHIResourceView](RHIResourceView.md) diff --git a/docs/api/XCEngine/RHI/RHIResourceView/Shutdown.md b/docs/api/XCEngine/RHI/RHIResourceView/Shutdown.md index 127d19ff..897bf814 100644 --- a/docs/api/XCEngine/RHI/RHIResourceView/Shutdown.md +++ b/docs/api/XCEngine/RHI/RHIResourceView/Shutdown.md @@ -1,30 +1,25 @@ # RHIResourceView::Shutdown -关闭并清理内部状态。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIResourceView.h` + +## 签名 ```cpp virtual void Shutdown() = 0; ``` -该方法声明于 `XCEngine/RHI/RHIResourceView.h`，当前页面用于固定 `RHIResourceView` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIResourceView object; - // 根据上下文补齐参数后调用 RHIResourceView::Shutdown(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIResourceView.md) -- [返回模块目录](../RHI.md) +- [RHIResourceView](RHIResourceView.md) diff --git a/docs/api/XCEngine/RHI/RHISampler/Bind.md b/docs/api/XCEngine/RHI/RHISampler/Bind.md index 09930903..5b91d6e7 100644 --- a/docs/api/XCEngine/RHI/RHISampler/Bind.md +++ b/docs/api/XCEngine/RHI/RHISampler/Bind.md @@ -1,31 +1,25 @@ # RHISampler::Bind -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHISampler.h` + +## 签名 ```cpp virtual void Bind(unsigned int unit) = 0; ``` -该方法声明于 `XCEngine/RHI/RHISampler.h`，当前页面用于固定 `RHISampler` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `unit` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHISampler object; - // 根据上下文补齐参数后调用 RHISampler::Bind(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHISampler.md) -- [返回模块目录](../RHI.md) +- [RHISampler](RHISampler.md) diff --git a/docs/api/XCEngine/RHI/RHISampler/Destructor.md b/docs/api/XCEngine/RHI/RHISampler/Destructor.md index 3a13046f..e01219d7 100644 --- a/docs/api/XCEngine/RHI/RHISampler/Destructor.md +++ b/docs/api/XCEngine/RHI/RHISampler/Destructor.md @@ -1,29 +1,25 @@ # RHISampler::~RHISampler() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHISampler.h` + +## 签名 ```cpp virtual ~RHISampler() = default; ``` -该方法声明于 `XCEngine/RHI/RHISampler.h`，当前页面用于固定 `RHISampler` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +销毁 `RHISampler` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHISampler object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 当前为默认析构实现。 ## 相关文档 -- [返回类总览](RHISampler.md) -- [返回模块目录](../RHI.md) +- [RHISampler](RHISampler.md) diff --git a/docs/api/XCEngine/RHI/RHISampler/GetID.md b/docs/api/XCEngine/RHI/RHISampler/GetID.md index 5eb4171c..7563ab62 100644 --- a/docs/api/XCEngine/RHI/RHISampler/GetID.md +++ b/docs/api/XCEngine/RHI/RHISampler/GetID.md @@ -1,30 +1,25 @@ # RHISampler::GetID -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHISampler.h` + +## 签名 ```cpp virtual unsigned int GetID() = 0; ``` -该方法声明于 `XCEngine/RHI/RHISampler.h`，当前页面用于固定 `RHISampler` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `unsigned int` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHISampler object; - // 根据上下文补齐参数后调用 RHISampler::GetID(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHISampler.md) -- [返回模块目录](../RHI.md) +- [RHISampler](RHISampler.md) diff --git a/docs/api/XCEngine/RHI/RHISampler/GetNativeHandle.md b/docs/api/XCEngine/RHI/RHISampler/GetNativeHandle.md index 74925120..37779663 100644 --- a/docs/api/XCEngine/RHI/RHISampler/GetNativeHandle.md +++ b/docs/api/XCEngine/RHI/RHISampler/GetNativeHandle.md @@ -1,30 +1,25 @@ # RHISampler::GetNativeHandle -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHISampler.h` + +## 签名 ```cpp virtual void* GetNativeHandle() = 0; ``` -该方法声明于 `XCEngine/RHI/RHISampler.h`，当前页面用于固定 `RHISampler` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `void*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHISampler object; - // 根据上下文补齐参数后调用 RHISampler::GetNativeHandle(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHISampler.md) -- [返回模块目录](../RHI.md) +- [RHISampler](RHISampler.md) diff --git a/docs/api/XCEngine/RHI/RHISampler/Shutdown.md b/docs/api/XCEngine/RHI/RHISampler/Shutdown.md index 9b50e8e4..9293c9de 100644 --- a/docs/api/XCEngine/RHI/RHISampler/Shutdown.md +++ b/docs/api/XCEngine/RHI/RHISampler/Shutdown.md @@ -1,30 +1,25 @@ # RHISampler::Shutdown -关闭并清理内部状态。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHISampler.h` + +## 签名 ```cpp virtual void Shutdown() = 0; ``` -该方法声明于 `XCEngine/RHI/RHISampler.h`，当前页面用于固定 `RHISampler` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHISampler object; - // 根据上下文补齐参数后调用 RHISampler::Shutdown(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHISampler.md) -- [返回模块目录](../RHI.md) +- [RHISampler](RHISampler.md) diff --git a/docs/api/XCEngine/RHI/RHISampler/Unbind.md b/docs/api/XCEngine/RHI/RHISampler/Unbind.md index 05a4fe7b..e024d653 100644 --- a/docs/api/XCEngine/RHI/RHISampler/Unbind.md +++ b/docs/api/XCEngine/RHI/RHISampler/Unbind.md @@ -1,31 +1,25 @@ # RHISampler::Unbind -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHISampler.h` + +## 签名 ```cpp virtual void Unbind(unsigned int unit) = 0; ``` -该方法声明于 `XCEngine/RHI/RHISampler.h`，当前页面用于固定 `RHISampler` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `unit` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHISampler object; - // 根据上下文补齐参数后调用 RHISampler::Unbind(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHISampler.md) -- [返回模块目录](../RHI.md) +- [RHISampler](RHISampler.md) diff --git a/docs/api/XCEngine/RHI/RHIScreenshot/Capture.md b/docs/api/XCEngine/RHI/RHIScreenshot/Capture.md index 7977cd7f..ecaa8403 100644 --- a/docs/api/XCEngine/RHI/RHIScreenshot/Capture.md +++ b/docs/api/XCEngine/RHI/RHIScreenshot/Capture.md @@ -1,33 +1,25 @@ # RHIScreenshot::Capture -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIScreenshot.h` + +## 签名 ```cpp virtual bool Capture(RHIDevice* device, RHISwapChain* swapChain, const char* filename) = 0; ``` -该方法声明于 `XCEngine/RHI/RHIScreenshot.h`，当前页面用于固定 `RHIScreenshot` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `device` - 参数语义详见头文件声明。 -- `swapChain` - 参数语义详见头文件声明。 -- `filename` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIScreenshot object; - // 根据上下文补齐参数后调用 RHIScreenshot::Capture(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIScreenshot.md) -- [返回模块目录](../RHI.md) +- [RHIScreenshot](RHIScreenshot.md) diff --git a/docs/api/XCEngine/RHI/RHIScreenshot/Create.md b/docs/api/XCEngine/RHI/RHIScreenshot/Create.md index 636010e8..4e4c7b15 100644 --- a/docs/api/XCEngine/RHI/RHIScreenshot/Create.md +++ b/docs/api/XCEngine/RHI/RHIScreenshot/Create.md @@ -1,31 +1,27 @@ # RHIScreenshot::Create -创建新对象或资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIScreenshot.h` + +## 签名 ```cpp static RHIScreenshot* Create(RHIType type); ``` -该方法声明于 `XCEngine/RHI/RHIScreenshot.h`，当前页面用于固定 `RHIScreenshot` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `type` - 参数语义详见头文件声明。 +执行 `D3D12Screenshot`、`OpenGLScreenshot`、`VulkanScreenshot` 协同流程。 -**返回：** `RHIScreenshot*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIScreenshot object; - // 根据上下文补齐参数后调用 RHIScreenshot::Create(...)。 - (void)object; -} -``` +- 当前实现会调用 `D3D12Screenshot`、`OpenGLScreenshot`、`VulkanScreenshot`。 +- 包含条件分支，并可能提前返回。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](RHIScreenshot.md) -- [返回模块目录](../RHI.md) +- [RHIScreenshot](RHIScreenshot.md) diff --git a/docs/api/XCEngine/RHI/RHIScreenshot/Destructor.md b/docs/api/XCEngine/RHI/RHIScreenshot/Destructor.md index 62ea78ba..82ce6b8b 100644 --- a/docs/api/XCEngine/RHI/RHIScreenshot/Destructor.md +++ b/docs/api/XCEngine/RHI/RHIScreenshot/Destructor.md @@ -1,29 +1,25 @@ # RHIScreenshot::~RHIScreenshot() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIScreenshot.h` + +## 签名 ```cpp virtual ~RHIScreenshot() = default; ``` -该方法声明于 `XCEngine/RHI/RHIScreenshot.h`，当前页面用于固定 `RHIScreenshot` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +销毁 `RHIScreenshot` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIScreenshot object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 当前为默认析构实现。 ## 相关文档 -- [返回类总览](RHIScreenshot.md) -- [返回模块目录](../RHI.md) +- [RHIScreenshot](RHIScreenshot.md) diff --git a/docs/api/XCEngine/RHI/RHIScreenshot/Shutdown.md b/docs/api/XCEngine/RHI/RHIScreenshot/Shutdown.md index 3cdc7d81..04f099eb 100644 --- a/docs/api/XCEngine/RHI/RHIScreenshot/Shutdown.md +++ b/docs/api/XCEngine/RHI/RHIScreenshot/Shutdown.md @@ -1,30 +1,25 @@ # RHIScreenshot::Shutdown -关闭并清理内部状态。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIScreenshot.h` + +## 签名 ```cpp virtual void Shutdown() = 0; ``` -该方法声明于 `XCEngine/RHI/RHIScreenshot.h`，当前页面用于固定 `RHIScreenshot` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIScreenshot object; - // 根据上下文补齐参数后调用 RHIScreenshot::Shutdown(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIScreenshot.md) -- [返回模块目录](../RHI.md) +- [RHIScreenshot](RHIScreenshot.md) diff --git a/docs/api/XCEngine/RHI/RHIShader/Compile.md b/docs/api/XCEngine/RHI/RHIShader/Compile.md index 362f704f..9f3a8775 100644 --- a/docs/api/XCEngine/RHI/RHIShader/Compile.md +++ b/docs/api/XCEngine/RHI/RHIShader/Compile.md @@ -1,34 +1,25 @@ # RHIShader::Compile -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIShader.h` + +## 签名 ```cpp virtual bool Compile(const void* sourceData, size_t sourceSize, const char* entryPoint, const char* target) = 0; ``` -该方法声明于 `XCEngine/RHI/RHIShader.h`，当前页面用于固定 `RHIShader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `sourceData` - 参数语义详见头文件声明。 -- `sourceSize` - 参数语义详见头文件声明。 -- `entryPoint` - 参数语义详见头文件声明。 -- `target` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIShader object; - // 根据上下文补齐参数后调用 RHIShader::Compile(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIShader.md) -- [返回模块目录](../RHI.md) +- [RHIShader](RHIShader.md) diff --git a/docs/api/XCEngine/RHI/RHIShader/CompileFromFile.md b/docs/api/XCEngine/RHI/RHIShader/CompileFromFile.md index fe31d3d9..5a9b36aa 100644 --- a/docs/api/XCEngine/RHI/RHIShader/CompileFromFile.md +++ b/docs/api/XCEngine/RHI/RHIShader/CompileFromFile.md @@ -1,33 +1,25 @@ # RHIShader::CompileFromFile -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIShader.h` + +## 签名 ```cpp virtual bool CompileFromFile(const wchar_t* filePath, const char* entryPoint, const char* target) = 0; ``` -该方法声明于 `XCEngine/RHI/RHIShader.h`，当前页面用于固定 `RHIShader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `filePath` - 参数语义详见头文件声明。 -- `entryPoint` - 参数语义详见头文件声明。 -- `target` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIShader object; - // 根据上下文补齐参数后调用 RHIShader::CompileFromFile(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIShader.md) -- [返回模块目录](../RHI.md) +- [RHIShader](RHIShader.md) diff --git a/docs/api/XCEngine/RHI/RHIShader/Destructor.md b/docs/api/XCEngine/RHI/RHIShader/Destructor.md index 878e3fbd..45a71459 100644 --- a/docs/api/XCEngine/RHI/RHIShader/Destructor.md +++ b/docs/api/XCEngine/RHI/RHIShader/Destructor.md @@ -1,29 +1,25 @@ # RHIShader::~RHIShader() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIShader.h` + +## 签名 ```cpp virtual ~RHIShader() = default; ``` -该方法声明于 `XCEngine/RHI/RHIShader.h`，当前页面用于固定 `RHIShader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +销毁 `RHIShader` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIShader object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 当前为默认析构实现。 ## 相关文档 -- [返回类总览](RHIShader.md) -- [返回模块目录](../RHI.md) +- [RHIShader](RHIShader.md) diff --git a/docs/api/XCEngine/RHI/RHIShader/GetNativeHandle.md b/docs/api/XCEngine/RHI/RHIShader/GetNativeHandle.md index 2cfcf345..eb1cf414 100644 --- a/docs/api/XCEngine/RHI/RHIShader/GetNativeHandle.md +++ b/docs/api/XCEngine/RHI/RHIShader/GetNativeHandle.md @@ -1,30 +1,25 @@ # RHIShader::GetNativeHandle -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIShader.h` + +## 签名 ```cpp virtual void* GetNativeHandle() = 0; ``` -该方法声明于 `XCEngine/RHI/RHIShader.h`，当前页面用于固定 `RHIShader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `void*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIShader object; - // 根据上下文补齐参数后调用 RHIShader::GetNativeHandle(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIShader.md) -- [返回模块目录](../RHI.md) +- [RHIShader](RHIShader.md) diff --git a/docs/api/XCEngine/RHI/RHIShader/GetType.md b/docs/api/XCEngine/RHI/RHIShader/GetType.md index 1a54bae5..153067bb 100644 --- a/docs/api/XCEngine/RHI/RHIShader/GetType.md +++ b/docs/api/XCEngine/RHI/RHIShader/GetType.md @@ -1,30 +1,25 @@ # RHIShader::GetType -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIShader.h` + +## 签名 ```cpp virtual ShaderType GetType() const = 0; ``` -该方法声明于 `XCEngine/RHI/RHIShader.h`，当前页面用于固定 `RHIShader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `ShaderType` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIShader object; - // 根据上下文补齐参数后调用 RHIShader::GetType(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIShader.md) -- [返回模块目录](../RHI.md) +- [RHIShader](RHIShader.md) diff --git a/docs/api/XCEngine/RHI/RHIShader/GetUniformInfo.md b/docs/api/XCEngine/RHI/RHIShader/GetUniformInfo.md index c021d07d..7ecf83ac 100644 --- a/docs/api/XCEngine/RHI/RHIShader/GetUniformInfo.md +++ b/docs/api/XCEngine/RHI/RHIShader/GetUniformInfo.md @@ -1,31 +1,25 @@ # RHIShader::GetUniformInfo -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIShader.h` + +## 签名 ```cpp virtual const UniformInfo* GetUniformInfo(const char* name) const = 0; ``` -该方法声明于 `XCEngine/RHI/RHIShader.h`，当前页面用于固定 `RHIShader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `name` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `const UniformInfo*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIShader object; - // 根据上下文补齐参数后调用 RHIShader::GetUniformInfo(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIShader.md) -- [返回模块目录](../RHI.md) +- [RHIShader](RHIShader.md) diff --git a/docs/api/XCEngine/RHI/RHIShader/GetUniformInfos.md b/docs/api/XCEngine/RHI/RHIShader/GetUniformInfos.md index f3293180..4ced7456 100644 --- a/docs/api/XCEngine/RHI/RHIShader/GetUniformInfos.md +++ b/docs/api/XCEngine/RHI/RHIShader/GetUniformInfos.md @@ -1,30 +1,25 @@ # RHIShader::GetUniformInfos -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIShader.h` + +## 签名 ```cpp virtual const std::vector& GetUniformInfos() const = 0; ``` -该方法声明于 `XCEngine/RHI/RHIShader.h`，当前页面用于固定 `RHIShader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `const std::vector&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIShader object; - // 根据上下文补齐参数后调用 RHIShader::GetUniformInfos(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIShader.md) -- [返回模块目录](../RHI.md) +- [RHIShader](RHIShader.md) diff --git a/docs/api/XCEngine/RHI/RHIShader/IsValid.md b/docs/api/XCEngine/RHI/RHIShader/IsValid.md index 78edb4d0..b9d56aa1 100644 --- a/docs/api/XCEngine/RHI/RHIShader/IsValid.md +++ b/docs/api/XCEngine/RHI/RHIShader/IsValid.md @@ -1,30 +1,25 @@ # RHIShader::IsValid -查询当前状态。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIShader.h` + +## 签名 ```cpp virtual bool IsValid() const = 0; ``` -该方法声明于 `XCEngine/RHI/RHIShader.h`，当前页面用于固定 `RHIShader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIShader object; - // 根据上下文补齐参数后调用 RHIShader::IsValid(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIShader.md) -- [返回模块目录](../RHI.md) +- [RHIShader](RHIShader.md) diff --git a/docs/api/XCEngine/RHI/RHIShader/Shutdown.md b/docs/api/XCEngine/RHI/RHIShader/Shutdown.md index 9709bc2c..8d7a411a 100644 --- a/docs/api/XCEngine/RHI/RHIShader/Shutdown.md +++ b/docs/api/XCEngine/RHI/RHIShader/Shutdown.md @@ -1,30 +1,25 @@ # RHIShader::Shutdown -关闭并清理内部状态。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHIShader.h` + +## 签名 ```cpp virtual void Shutdown() = 0; ``` -该方法声明于 `XCEngine/RHI/RHIShader.h`，当前页面用于固定 `RHIShader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHIShader object; - // 根据上下文补齐参数后调用 RHIShader::Shutdown(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHIShader.md) -- [返回模块目录](../RHI.md) +- [RHIShader](RHIShader.md) diff --git a/docs/api/XCEngine/RHI/RHISwapChain/Destructor.md b/docs/api/XCEngine/RHI/RHISwapChain/Destructor.md index f4f1bdfa..463fcf62 100644 --- a/docs/api/XCEngine/RHI/RHISwapChain/Destructor.md +++ b/docs/api/XCEngine/RHI/RHISwapChain/Destructor.md @@ -1,29 +1,25 @@ # RHISwapChain::~RHISwapChain() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHISwapChain.h` + +## 签名 ```cpp virtual ~RHISwapChain() = default; ``` -该方法声明于 `XCEngine/RHI/RHISwapChain.h`，当前页面用于固定 `RHISwapChain` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +销毁 `RHISwapChain` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHISwapChain object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 当前为默认析构实现。 ## 相关文档 -- [返回类总览](RHISwapChain.md) -- [返回模块目录](../RHI.md) +- [RHISwapChain](RHISwapChain.md) diff --git a/docs/api/XCEngine/RHI/RHISwapChain/GetCurrentBackBuffer.md b/docs/api/XCEngine/RHI/RHISwapChain/GetCurrentBackBuffer.md index e50faec7..271c777d 100644 --- a/docs/api/XCEngine/RHI/RHISwapChain/GetCurrentBackBuffer.md +++ b/docs/api/XCEngine/RHI/RHISwapChain/GetCurrentBackBuffer.md @@ -1,30 +1,25 @@ # RHISwapChain::GetCurrentBackBuffer -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHISwapChain.h` + +## 签名 ```cpp virtual RHITexture* GetCurrentBackBuffer() = 0; ``` -该方法声明于 `XCEngine/RHI/RHISwapChain.h`，当前页面用于固定 `RHISwapChain` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `RHITexture*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHISwapChain object; - // 根据上下文补齐参数后调用 RHISwapChain::GetCurrentBackBuffer(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHISwapChain.md) -- [返回模块目录](../RHI.md) +- [RHISwapChain](RHISwapChain.md) diff --git a/docs/api/XCEngine/RHI/RHISwapChain/GetCurrentBackBufferIndex.md b/docs/api/XCEngine/RHI/RHISwapChain/GetCurrentBackBufferIndex.md index a7fdd0cd..1bff49bf 100644 --- a/docs/api/XCEngine/RHI/RHISwapChain/GetCurrentBackBufferIndex.md +++ b/docs/api/XCEngine/RHI/RHISwapChain/GetCurrentBackBufferIndex.md @@ -1,30 +1,25 @@ # RHISwapChain::GetCurrentBackBufferIndex -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHISwapChain.h` + +## 签名 ```cpp virtual uint32_t GetCurrentBackBufferIndex() const = 0; ``` -该方法声明于 `XCEngine/RHI/RHISwapChain.h`，当前页面用于固定 `RHISwapChain` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `uint32_t` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHISwapChain object; - // 根据上下文补齐参数后调用 RHISwapChain::GetCurrentBackBufferIndex(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHISwapChain.md) -- [返回模块目录](../RHI.md) +- [RHISwapChain](RHISwapChain.md) diff --git a/docs/api/XCEngine/RHI/RHISwapChain/GetNativeHandle.md b/docs/api/XCEngine/RHI/RHISwapChain/GetNativeHandle.md index 531da207..043cb222 100644 --- a/docs/api/XCEngine/RHI/RHISwapChain/GetNativeHandle.md +++ b/docs/api/XCEngine/RHI/RHISwapChain/GetNativeHandle.md @@ -1,30 +1,25 @@ # RHISwapChain::GetNativeHandle -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHISwapChain.h` + +## 签名 ```cpp virtual void* GetNativeHandle() = 0; ``` -该方法声明于 `XCEngine/RHI/RHISwapChain.h`，当前页面用于固定 `RHISwapChain` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `void*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHISwapChain object; - // 根据上下文补齐参数后调用 RHISwapChain::GetNativeHandle(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHISwapChain.md) -- [返回模块目录](../RHI.md) +- [RHISwapChain](RHISwapChain.md) diff --git a/docs/api/XCEngine/RHI/RHISwapChain/Present.md b/docs/api/XCEngine/RHI/RHISwapChain/Present.md index efb71be0..8022b422 100644 --- a/docs/api/XCEngine/RHI/RHISwapChain/Present.md +++ b/docs/api/XCEngine/RHI/RHISwapChain/Present.md @@ -1,32 +1,25 @@ # RHISwapChain::Present -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHISwapChain.h` + +## 签名 ```cpp virtual void Present(uint32_t syncInterval = 1, uint32_t flags = 0) = 0; ``` -该方法声明于 `XCEngine/RHI/RHISwapChain.h`，当前页面用于固定 `RHISwapChain` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `syncInterval` - 参数语义详见头文件声明。 -- `flags` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHISwapChain object; - // 根据上下文补齐参数后调用 RHISwapChain::Present(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHISwapChain.md) -- [返回模块目录](../RHI.md) +- [RHISwapChain](RHISwapChain.md) diff --git a/docs/api/XCEngine/RHI/RHISwapChain/Resize.md b/docs/api/XCEngine/RHI/RHISwapChain/Resize.md index c9242040..8e04324e 100644 --- a/docs/api/XCEngine/RHI/RHISwapChain/Resize.md +++ b/docs/api/XCEngine/RHI/RHISwapChain/Resize.md @@ -1,32 +1,25 @@ # RHISwapChain::Resize -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHISwapChain.h` + +## 签名 ```cpp virtual void Resize(uint32_t width, uint32_t height) = 0; ``` -该方法声明于 `XCEngine/RHI/RHISwapChain.h`，当前页面用于固定 `RHISwapChain` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `width` - 参数语义详见头文件声明。 -- `height` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHISwapChain object; - // 根据上下文补齐参数后调用 RHISwapChain::Resize(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHISwapChain.md) -- [返回模块目录](../RHI.md) +- [RHISwapChain](RHISwapChain.md) diff --git a/docs/api/XCEngine/RHI/RHISwapChain/Shutdown.md b/docs/api/XCEngine/RHI/RHISwapChain/Shutdown.md index 6909ae93..2d09bb87 100644 --- a/docs/api/XCEngine/RHI/RHISwapChain/Shutdown.md +++ b/docs/api/XCEngine/RHI/RHISwapChain/Shutdown.md @@ -1,30 +1,25 @@ # RHISwapChain::Shutdown -关闭并清理内部状态。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHISwapChain.h` + +## 签名 ```cpp virtual void Shutdown() = 0; ``` -该方法声明于 `XCEngine/RHI/RHISwapChain.h`，当前页面用于固定 `RHISwapChain` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHISwapChain object; - // 根据上下文补齐参数后调用 RHISwapChain::Shutdown(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHISwapChain.md) -- [返回模块目录](../RHI.md) +- [RHISwapChain](RHISwapChain.md) diff --git a/docs/api/XCEngine/RHI/RHITexture/Destructor.md b/docs/api/XCEngine/RHI/RHITexture/Destructor.md index a561fd6b..87fdc4fb 100644 --- a/docs/api/XCEngine/RHI/RHITexture/Destructor.md +++ b/docs/api/XCEngine/RHI/RHITexture/Destructor.md @@ -1,29 +1,25 @@ # RHITexture::~RHITexture() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHITexture.h` + +## 签名 ```cpp virtual ~RHITexture() = default; ``` -该方法声明于 `XCEngine/RHI/RHITexture.h`，当前页面用于固定 `RHITexture` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +销毁 `RHITexture` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHITexture object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 当前为默认析构实现。 ## 相关文档 -- [返回类总览](RHITexture.md) -- [返回模块目录](../RHI.md) +- [RHITexture](RHITexture.md) diff --git a/docs/api/XCEngine/RHI/RHITexture/GetDepth.md b/docs/api/XCEngine/RHI/RHITexture/GetDepth.md index 2373d0d4..a3f2d2ed 100644 --- a/docs/api/XCEngine/RHI/RHITexture/GetDepth.md +++ b/docs/api/XCEngine/RHI/RHITexture/GetDepth.md @@ -1,30 +1,25 @@ # RHITexture::GetDepth -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHITexture.h` + +## 签名 ```cpp virtual uint32_t GetDepth() const = 0; ``` -该方法声明于 `XCEngine/RHI/RHITexture.h`，当前页面用于固定 `RHITexture` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `uint32_t` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHITexture object; - // 根据上下文补齐参数后调用 RHITexture::GetDepth(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHITexture.md) -- [返回模块目录](../RHI.md) +- [RHITexture](RHITexture.md) diff --git a/docs/api/XCEngine/RHI/RHITexture/GetFormat.md b/docs/api/XCEngine/RHI/RHITexture/GetFormat.md index 01df21ef..4222daad 100644 --- a/docs/api/XCEngine/RHI/RHITexture/GetFormat.md +++ b/docs/api/XCEngine/RHI/RHITexture/GetFormat.md @@ -1,30 +1,25 @@ # RHITexture::GetFormat -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHITexture.h` + +## 签名 ```cpp virtual Format GetFormat() const = 0; ``` -该方法声明于 `XCEngine/RHI/RHITexture.h`，当前页面用于固定 `RHITexture` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `Format` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHITexture object; - // 根据上下文补齐参数后调用 RHITexture::GetFormat(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHITexture.md) -- [返回模块目录](../RHI.md) +- [RHITexture](RHITexture.md) diff --git a/docs/api/XCEngine/RHI/RHITexture/GetHeight.md b/docs/api/XCEngine/RHI/RHITexture/GetHeight.md index 7b21be36..7da2f61b 100644 --- a/docs/api/XCEngine/RHI/RHITexture/GetHeight.md +++ b/docs/api/XCEngine/RHI/RHITexture/GetHeight.md @@ -1,30 +1,25 @@ # RHITexture::GetHeight -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHITexture.h` + +## 签名 ```cpp virtual uint32_t GetHeight() const = 0; ``` -该方法声明于 `XCEngine/RHI/RHITexture.h`，当前页面用于固定 `RHITexture` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `uint32_t` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHITexture object; - // 根据上下文补齐参数后调用 RHITexture::GetHeight(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHITexture.md) -- [返回模块目录](../RHI.md) +- [RHITexture](RHITexture.md) diff --git a/docs/api/XCEngine/RHI/RHITexture/GetMipLevels.md b/docs/api/XCEngine/RHI/RHITexture/GetMipLevels.md index 7910290f..ff4eef69 100644 --- a/docs/api/XCEngine/RHI/RHITexture/GetMipLevels.md +++ b/docs/api/XCEngine/RHI/RHITexture/GetMipLevels.md @@ -1,30 +1,25 @@ # RHITexture::GetMipLevels -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHITexture.h` + +## 签名 ```cpp virtual uint32_t GetMipLevels() const = 0; ``` -该方法声明于 `XCEngine/RHI/RHITexture.h`，当前页面用于固定 `RHITexture` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `uint32_t` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHITexture object; - // 根据上下文补齐参数后调用 RHITexture::GetMipLevels(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHITexture.md) -- [返回模块目录](../RHI.md) +- [RHITexture](RHITexture.md) diff --git a/docs/api/XCEngine/RHI/RHITexture/GetName.md b/docs/api/XCEngine/RHI/RHITexture/GetName.md index b7fbec6e..d143eee9 100644 --- a/docs/api/XCEngine/RHI/RHITexture/GetName.md +++ b/docs/api/XCEngine/RHI/RHITexture/GetName.md @@ -1,30 +1,26 @@ # RHITexture::GetName -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHITexture.h` + +## 签名 ```cpp virtual const std::string& GetName() const = 0; ``` -该方法声明于 `XCEngine/RHI/RHITexture.h`，当前页面用于固定 `RHITexture` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `const std::string&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHITexture object; - // 根据上下文补齐参数后调用 RHITexture::GetName(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHITexture.md) -- [返回模块目录](../RHI.md) +- [RHITexture](RHITexture.md) +- [SetName](SetName.md) diff --git a/docs/api/XCEngine/RHI/RHITexture/GetNativeHandle.md b/docs/api/XCEngine/RHI/RHITexture/GetNativeHandle.md index 25cad766..374f7871 100644 --- a/docs/api/XCEngine/RHI/RHITexture/GetNativeHandle.md +++ b/docs/api/XCEngine/RHI/RHITexture/GetNativeHandle.md @@ -1,30 +1,25 @@ # RHITexture::GetNativeHandle -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHITexture.h` + +## 签名 ```cpp virtual void* GetNativeHandle() = 0; ``` -该方法声明于 `XCEngine/RHI/RHITexture.h`，当前页面用于固定 `RHITexture` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `void*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHITexture object; - // 根据上下文补齐参数后调用 RHITexture::GetNativeHandle(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHITexture.md) -- [返回模块目录](../RHI.md) +- [RHITexture](RHITexture.md) diff --git a/docs/api/XCEngine/RHI/RHITexture/GetState.md b/docs/api/XCEngine/RHI/RHITexture/GetState.md index 16a2bcff..05a5d28b 100644 --- a/docs/api/XCEngine/RHI/RHITexture/GetState.md +++ b/docs/api/XCEngine/RHI/RHITexture/GetState.md @@ -1,30 +1,26 @@ # RHITexture::GetState -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHITexture.h` + +## 签名 ```cpp virtual ResourceStates GetState() const = 0; ``` -该方法声明于 `XCEngine/RHI/RHITexture.h`，当前页面用于固定 `RHITexture` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `ResourceStates` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHITexture object; - // 根据上下文补齐参数后调用 RHITexture::GetState(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHITexture.md) -- [返回模块目录](../RHI.md) +- [RHITexture](RHITexture.md) +- [SetState](SetState.md) diff --git a/docs/api/XCEngine/RHI/RHITexture/GetTextureType.md b/docs/api/XCEngine/RHI/RHITexture/GetTextureType.md index d13874d3..87cc463a 100644 --- a/docs/api/XCEngine/RHI/RHITexture/GetTextureType.md +++ b/docs/api/XCEngine/RHI/RHITexture/GetTextureType.md @@ -1,30 +1,25 @@ # RHITexture::GetTextureType -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHITexture.h` + +## 签名 ```cpp virtual TextureType GetTextureType() const = 0; ``` -该方法声明于 `XCEngine/RHI/RHITexture.h`，当前页面用于固定 `RHITexture` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `TextureType` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHITexture object; - // 根据上下文补齐参数后调用 RHITexture::GetTextureType(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHITexture.md) -- [返回模块目录](../RHI.md) +- [RHITexture](RHITexture.md) diff --git a/docs/api/XCEngine/RHI/RHITexture/GetWidth.md b/docs/api/XCEngine/RHI/RHITexture/GetWidth.md index 9f6ec5e6..048950e5 100644 --- a/docs/api/XCEngine/RHI/RHITexture/GetWidth.md +++ b/docs/api/XCEngine/RHI/RHITexture/GetWidth.md @@ -1,30 +1,25 @@ # RHITexture::GetWidth -获取相关状态或对象。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHITexture.h` + +## 签名 ```cpp virtual uint32_t GetWidth() const = 0; ``` -该方法声明于 `XCEngine/RHI/RHITexture.h`，当前页面用于固定 `RHITexture` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `uint32_t` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHITexture object; - // 根据上下文补齐参数后调用 RHITexture::GetWidth(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHITexture.md) -- [返回模块目录](../RHI.md) +- [RHITexture](RHITexture.md) diff --git a/docs/api/XCEngine/RHI/RHITexture/SetName.md b/docs/api/XCEngine/RHI/RHITexture/SetName.md index db1f22b8..bb66ff26 100644 --- a/docs/api/XCEngine/RHI/RHITexture/SetName.md +++ b/docs/api/XCEngine/RHI/RHITexture/SetName.md @@ -1,31 +1,26 @@ # RHITexture::SetName -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHITexture.h` + +## 签名 ```cpp virtual void SetName(const std::string& name) = 0; ``` -该方法声明于 `XCEngine/RHI/RHITexture.h`，当前页面用于固定 `RHITexture` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `name` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHITexture object; - // 根据上下文补齐参数后调用 RHITexture::SetName(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHITexture.md) -- [返回模块目录](../RHI.md) +- [RHITexture](RHITexture.md) +- [GetName](GetName.md) diff --git a/docs/api/XCEngine/RHI/RHITexture/SetState.md b/docs/api/XCEngine/RHI/RHITexture/SetState.md index b0a54842..540c8a20 100644 --- a/docs/api/XCEngine/RHI/RHITexture/SetState.md +++ b/docs/api/XCEngine/RHI/RHITexture/SetState.md @@ -1,31 +1,26 @@ # RHITexture::SetState -设置相关状态或配置。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHITexture.h` + +## 签名 ```cpp virtual void SetState(ResourceStates state) = 0; ``` -该方法声明于 `XCEngine/RHI/RHITexture.h`，当前页面用于固定 `RHITexture` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `state` - 参数语义详见头文件声明。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHITexture object; - // 根据上下文补齐参数后调用 RHITexture::SetState(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHITexture.md) -- [返回模块目录](../RHI.md) +- [RHITexture](RHITexture.md) +- [GetState](GetState.md) diff --git a/docs/api/XCEngine/RHI/RHITexture/Shutdown.md b/docs/api/XCEngine/RHI/RHITexture/Shutdown.md index 05b39413..c3e34069 100644 --- a/docs/api/XCEngine/RHI/RHITexture/Shutdown.md +++ b/docs/api/XCEngine/RHI/RHITexture/Shutdown.md @@ -1,30 +1,25 @@ # RHITexture::Shutdown -关闭并清理内部状态。 +**命名空间**: `XCEngine::RHI` + +**类型**: `method` + +**头文件**: `XCEngine/RHI/RHITexture.h` + +## 签名 ```cpp virtual void Shutdown() = 0; ``` -该方法声明于 `XCEngine/RHI/RHITexture.h`，当前页面用于固定 `RHITexture` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +纯虚接口。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::RHI::RHITexture object; - // 根据上下文补齐参数后调用 RHITexture::Shutdown(...)。 - (void)object; -} -``` +- 该声明是纯虚接口，基类不提供实现。 ## 相关文档 -- [返回类总览](RHITexture.md) -- [返回模块目录](../RHI.md) +- [RHITexture](RHITexture.md) diff --git a/docs/api/XCEngine/RHI/ShaderCompiler/ShaderCompiler.md b/docs/api/XCEngine/RHI/ShaderCompiler/ShaderCompiler.md new file mode 100644 index 00000000..a1c656f1 --- /dev/null +++ b/docs/api/XCEngine/RHI/ShaderCompiler/ShaderCompiler.md @@ -0,0 +1,18 @@ +# ShaderCompiler + +**命名空间**: `XCEngine::RHI` + +**类型**: `submodule` + +**头文件目录**: `engine/include/XCEngine/RHI/ShaderCompiler/` + +**描述**: RHI shader compiler 子模块，当前公开 SPIR-V shader compiler 相关接口。 + +## 当前范围 + +- [SpirvShaderCompiler](SpirvShaderCompiler/SpirvShaderCompiler.md) + +## 相关文档 + +- [RHI](../RHI.md) +- [Rendering](../../Rendering/Rendering.md) diff --git a/docs/api/XCEngine/RHI/ShaderCompiler/SpirvShaderCompiler/SpirvShaderCompiler.md b/docs/api/XCEngine/RHI/ShaderCompiler/SpirvShaderCompiler/SpirvShaderCompiler.md new file mode 100644 index 00000000..d9bccb31 --- /dev/null +++ b/docs/api/XCEngine/RHI/ShaderCompiler/SpirvShaderCompiler/SpirvShaderCompiler.md @@ -0,0 +1,52 @@ +# SpirvShaderCompiler + +**命名空间**: `XCEngine::RHI` + +**类型**: `enum + struct + free functions` + +**头文件**: `XCEngine/RHI/ShaderCompiler/SpirvShaderCompiler.h` + +**描述**: SPIR-V 编译与 OpenGL GLSL 转译入口，负责把 `ShaderCompileDesc` 输入统一变成 `CompiledSpirvShader`，并在需要时继续转成 GLSL 430 文本。 + +## 声明概览 + +| 声明 | 类型 | 说明 | +|------|------|------| +| `SpirvTargetEnvironment` | `enum class` | 目标 SPIR-V 环境，当前公开 `Vulkan` 与 `OpenGL`。 | +| `CompiledSpirvShader` | `struct` | 持有编译后的 `spirvWords`、解析出的 `ShaderType` 与 `entryPoint`。 | +| `CompileSpirvShader(...)` | `free function` | 读取源码或现成 SPIR-V，输出 `CompiledSpirvShader`。 | +| `TranspileSpirvToOpenGLGLSL(...)` | `free function` | 把 `CompiledSpirvShader` 再转成 OpenGL GLSL 文本。 | + +## 当前行为 + +- `CompileSpirvShader(...)` 支持三类输入： + - 现成 SPIR-V 二进制 + - HLSL 源码 + - GLSL 源码 +- 当 `desc.entryPoint` 为空时，函数会先把结果入口点设成 `main`；若输入本身就是 SPIR-V 且 metadata 可解析，再回填成 SPIR-V 里真实声明的入口点。 +- 当输入已经是 SPIR-V 时，函数只做 payload 长度、magic header 和 metadata 校验，不会再次调用外部编译器。 +- 当输入是 HLSL / GLSL 时，当前实现会： + - 把 `desc.macros` 注入临时源码 + - 调 `glslangValidator.exe` + - 读取临时 `.spv` + - 再从 SPIR-V metadata 回填 shader stage / entry point +- `TranspileSpirvToOpenGLGLSL(...)` 当前依赖 `spirv-cross.exe`，固定输出 `--version 430` 的 GLSL 文本。 + +## 当前调用链 + +- `engine/src/RHI/Vulkan/VulkanShaderCompiler.cpp` 直接调用 `CompileSpirvShader(..., SpirvTargetEnvironment::Vulkan, ...)`。 +- `engine/src/RHI/OpenGL/OpenGLDevice.cpp` 当前先编出 Vulkan 目标 SPIR-V，再调用 `TranspileSpirvToOpenGLGLSL(...)`。 +- 这意味着 `SpirvTargetEnvironment::OpenGL` 虽然已公开，但当前工作树里的真实运行时调用方还没有直接走这条编译目标分支。 + +## 当前边界 + +- 这套接口是外部工具前端，不是内嵌编译器；缺少 `glslangValidator.exe` 或 `spirv-cross.exe` 时会直接失败并返回错误文本。 +- 编译过程当前依赖临时文件和 Windows 进程创建。 +- `CompileSpirvShader(...)` 要求至少提供 `desc.source` 或 `desc.fileName` 之一；两者都为空会立即失败。 +- 目前没有找到针对这两个公开函数的独立单测；它们主要通过 Vulkan / OpenGL 设备编译路径间接被消费。 + +## 相关文档 + +- [ShaderCompiler](../ShaderCompiler.md) +- [RHI](../../RHI.md) +- [Rendering](../../../Rendering/Rendering.md) diff --git a/docs/api/XCEngine/Rendering/Builtin/Builtin.md b/docs/api/XCEngine/Rendering/Builtin/Builtin.md index 87a9d6c9..f1ce131c 100644 --- a/docs/api/XCEngine/Rendering/Builtin/Builtin.md +++ b/docs/api/XCEngine/Rendering/Builtin/Builtin.md @@ -6,32 +6,26 @@ **头文件目录**: `engine/include/XCEngine/Rendering/Builtin/` -**描述**: builtin pass 契约与元数据辅助层，负责描述内建渲染阶段的逻辑名称、布局规则与 metadata 解析辅助。 +**描述**: builtin pass 契约与元数据辅助层，负责描述内建渲染阶段的逻辑名称、资源语义、布局规则和统一 include 入口。 ## 概览 `Builtin` 这一层当前位于 shader/material 契约与具体 pass 执行之间。 - 它的职责不是执行渲染，而是统一描述： - builtin pass 的契约名 - builtin pass 的布局语义 - builtin metadata 的读取与标准化 -- shader `resources` 如何被解释成 builtin pass 白名单语义 +- builtin pass contract 的统一 include 入口 -当前公开入口包括： +## 当前公开入口 - [BuiltinPassContract](BuiltinPassContract/BuiltinPassContract.md) -- [BuiltinPassTypes](BuiltinPassTypes/BuiltinPassTypes.md) -- [BuiltinPassMetadataUtils](BuiltinPassMetadataUtils/BuiltinPassMetadataUtils.md) -- [BuiltinPassLayoutUtils](BuiltinPassLayoutUtils/BuiltinPassLayoutUtils.md) - -## 当前职责 - -- 为 builtin forward / object-id / depth-style pass 提供统一的 pass 枚举与资源语义 -- 统一 shader pass 名称和 `LightMode` tag 的匹配规则 -- 把 shader `resources` 声明转换成 descriptor-set layout 可消费的 plan -- 为管线和 pass 提供调试字符串与布局元数据刷新 helper +- [BuiltinMaterialPass](../RenderMaterialUtility/BuiltinMaterialPass.md) +- [BuiltinPassResourceSemantic](../RenderMaterialUtility/BuiltinPassResourceSemantic.md) +- [BuiltinPassResourceBindingPlan](../RenderMaterialUtility/BuiltinPassResourceBindingPlan.md) +- [NormalizeBuiltinPassMetadataValue](../RenderMaterialUtility/NormalizeBuiltinPassMetadataValue.md) +- [TryBuildBuiltinPassResourceBindingPlan](../RenderMaterialUtility/TryBuildBuiltinPassResourceBindingPlan.md) ## 相关文档 diff --git a/docs/api/XCEngine/Rendering/Builtin/BuiltinPassContract/BuiltinPassContract.md b/docs/api/XCEngine/Rendering/Builtin/BuiltinPassContract/BuiltinPassContract.md index 47371eb1..4ad548af 100644 --- a/docs/api/XCEngine/Rendering/Builtin/BuiltinPassContract/BuiltinPassContract.md +++ b/docs/api/XCEngine/Rendering/Builtin/BuiltinPassContract/BuiltinPassContract.md @@ -2,38 +2,35 @@ **命名空间**: `XCEngine::Rendering` -**类型**: `utility header` +**类型**: `umbrella header` **头文件**: `XCEngine/Rendering/Builtin/BuiltinPassContract.h` -**描述**: builtin pass 资源契约的聚合入口头，当前作为兼容 include，把类型、metadata 解析与布局辅助一并暴露给调用方。 +**描述**: builtin pass 契约相关头文件的统一 include 入口；当前直接转发到 `BuiltinPassLayoutUtils.h`，供 builtin pipeline 和各类 builtin pass 复用。 ## 概览 -`BuiltinPassContract.h` 当前本身不再声明独立类型或函数。 +`BuiltinPassContract.h` 本身不声明新的类型或函数，它的作用是提供一个稳定入口，把 builtin pass contract 所需的布局辅助一并引入。 -它的作用更接近“完整 builtin pass 契约入口”： +当前实际承载的能力包括： -- 引入 `BuiltinPassLayoutUtils.h` -- 进而间接带入 `BuiltinPassMetadataUtils.h` -- 再带入 `BuiltinPassTypes.h` +- builtin pass 资源 binding-plan 构建 +- descriptor-set layout 元数据生成 +- builtin pass 资源语义与 RHI 描述符布局之间的转换 -对消费 builtin pass 资源契约的代码来说，如果不想分别 include 三层辅助头，直接引入这份聚合头即可。 +## 何时使用 -## 当前适用场景 +- 需要一次性引入 builtin pass contract 辅助能力时。 +- 需要避免在调用方显式区分 `BuiltinPassLayoutUtils.h` 与其依赖层级时。 +- 作为 builtin pass / pipeline 相关源码的稳定 include 路径时。 -- 需要同时使用 `BuiltinMaterialPass`、`BuiltinPassResourceBindingPlan` 和 `TryBuildBuiltinPassSetLayouts(...)` -- 需要解析 shader `resources` 声明，再继续生成 descriptor-set layout -- 需要写出与 builtin forward / object-id / depth-style pass 相同的资源契约代码 +## 当前边界 -## 当前实现边界 - -- 它只是聚合入口，不新增 ABI，也不提供独立实现。 -- 如果调用方只依赖某一小组 helper，仍然可以直接 include 更窄的头文件。 +- 这个头文件只是聚合入口，不额外引入新的行为。 +- 具体公开项仍以 [TryBuildBuiltinPassResourceBindingPlan](../../RenderMaterialUtility/TryBuildBuiltinPassResourceBindingPlan.md) 等页面为准。 ## 相关文档 - [Builtin](../Builtin.md) -- [BuiltinPassTypes](../BuiltinPassTypes/BuiltinPassTypes.md) -- [BuiltinPassMetadataUtils](../BuiltinPassMetadataUtils/BuiltinPassMetadataUtils.md) -- [BuiltinPassLayoutUtils](../BuiltinPassLayoutUtils/BuiltinPassLayoutUtils.md) +- [TryBuildBuiltinPassResourceBindingPlan](../../RenderMaterialUtility/TryBuildBuiltinPassResourceBindingPlan.md) +- [BuiltinPassResourceBindingPlan](../../RenderMaterialUtility/BuiltinPassResourceBindingPlan.md) diff --git a/docs/api/XCEngine/Rendering/Execution/SceneRenderer/SceneRenderer.md b/docs/api/XCEngine/Rendering/Execution/SceneRenderer/SceneRenderer.md index 9622c785..62c537a1 100644 --- a/docs/api/XCEngine/Rendering/Execution/SceneRenderer/SceneRenderer.md +++ b/docs/api/XCEngine/Rendering/Execution/SceneRenderer/SceneRenderer.md @@ -6,20 +6,27 @@ **头文件**: `XCEngine/Rendering/Execution/SceneRenderer.h` -**描述**: 场景级渲染编排入口，负责构建和排序 `CameraRenderRequest`，再把每个请求转交给 [CameraRenderer](../CameraRenderer/CameraRenderer.md) 执行。 +**描述**: 场景级渲染编排入口，负责构建并补全 `CameraRenderRequest`，包括 final-color policy、fullscreen post-process/final-output 子请求，再把请求转交给 [CameraRenderer](../CameraRenderer/CameraRenderer.md) 执行。 ## 概览 `SceneRenderer` 当前是执行层的外层编排器。 -它维护两块核心运行时对象： +它维护两块公开可见的核心运行时对象： - `m_requestPlanner` - `m_cameraRenderer` +除此之外，它还维护每帧按 request 数量扩展的 owned fullscreen-stage 状态： + +- `m_ownedPostProcessSequences` +- `m_ownedFinalOutputSequences` +- `m_ownedFullscreenStageSurfaces` + 这条拆分让 Rendering 主链明确分成两层： - `SceneRenderer` 负责“这次要渲染哪些 request、按什么顺序” +- `SceneRenderer` 还负责把每个 request 进一步补成“主场景颜色 -> post-process -> final-output”的完整链 - `CameraRenderer` 负责“单个 request 怎样被真正执行” ## 当前公开能力 @@ -28,11 +35,15 @@ - 执行单个 request - 执行 request 数组 - 直接从 `Scene + overrideCamera + surface` 生成 request 并执行 +- 为每个 request 解析 final-color policy +- 按相机 post-process / final-color 需求挂接 fullscreen-stage 子请求 ## 当前实现边界 - 它不直接做 scene extraction。 - 它不直接操作主管线内部细节。 +- `BuildRenderRequests(...)` 当前会先让 `SceneRenderRequestPlanner` 生成基础 request，再调用 `ResolveCameraFinalColorPolicies(...)` 和 `AttachFullscreenStageRequests(...)` 做后处理补全。 +- fullscreen-stage 只会在 request 同时具备 `camera`、有效 `device` 和有效颜色目标时挂接。 - 对手工提交的 request 数组，当前仍会再次按 stack / depth 做稳定排序。 ## 相关文档 @@ -42,4 +53,3 @@ - [SceneRenderRequestPlanner](../../Planning/SceneRenderRequestPlanner/SceneRenderRequestPlanner.md) - [SceneRenderRequestUtils](../../Planning/SceneRenderRequestUtils/SceneRenderRequestUtils.md) - [Camera Request Planning And Clear Rules](../../../../_guides/Rendering/Camera-Request-Planning-And-Clear-Rules.md) - diff --git a/docs/api/XCEngine/Rendering/Materials/RenderMaterialResolve/RenderMaterialResolve.md b/docs/api/XCEngine/Rendering/Materials/RenderMaterialResolve/RenderMaterialResolve.md index 3f547b1b..878ac661 100644 --- a/docs/api/XCEngine/Rendering/Materials/RenderMaterialResolve/RenderMaterialResolve.md +++ b/docs/api/XCEngine/Rendering/Materials/RenderMaterialResolve/RenderMaterialResolve.md @@ -32,6 +32,8 @@ - `ResolveBuiltinBaseColorTexture(...)` - `ResolveBuiltinAlphaCutoff(...)` - `BuildBuiltinForwardMaterialData(...)` +- `IsCubemapSkyboxTextureType(...)` +- `IsPanoramicSkyboxTextureType(...)` - `ResolveSkyboxPanoramicTexture(...)` - `ResolveSkyboxCubemapTexture(...)` - `ResolveSkyboxTextureMode(...)` @@ -41,15 +43,23 @@ - `BuildBuiltinSkyboxMaterialData(...)` - `ResolveSchemaMaterialConstantPayload(...)` - `ResolveMaterial(...)` +- `TryResolveRenderQueueTagValue(...)` +- `TryResolveShaderPassRenderQueue(...)` - `ResolveMaterialRenderQueue(...)` - `IsTransparentRenderQueue(...)` +- `HasLegacyMaterialBuiltinPassHints(...)` +- `LegacyMaterialBuiltinPassHintsMatch(...)` +- `CanUseLegacyMaterialPassFallback(...)` - `MatchesBuiltinPass(...)` ## 当前实现边界 - 它只负责材质语义解析，不直接创建 descriptor set 或 pipeline state。 -- `ResolveSchemaMaterialConstantPayload(...)` 暴露的是借用视图，不负责重新打包或持有内存。 -- 没有显式 builtin metadata 的材质仍会按兼容规则回退到 `ForwardLit`。 +- `ResolveSchemaMaterialConstantPayload(...)` 暴露的是借用视图，不负责重新打包或持有内存；只有常量布局和常量 buffer 都非空时才会返回有效 payload。 +- `MaterialConstantPayloadView::IsValid()` 还要求 `layout.size == size`，因此文档使用时应把它视为“布局与字节载荷配对成功”的结果，而不只是 data 指针非空。 +- `ResolveMaterialRenderQueue(...)` 当前优先尊重材质自身 `renderQueue` 覆盖；只有它仍等于默认 `Geometry` 队列时，才会继续读取显式 `shaderPass` 或 shader pass `Queue` tag。 +- `ResolveSkyboxTextureMode(...)` 先尝试 panoramic，再尝试 cubemap；如果两者都能解析到，当前会优先返回 `Panoramic`。 +- `MatchesBuiltinPass(...)` 会先看 shader 是否已经声明显式 builtin metadata；只有缺少这层 metadata 时，才会回退到 `Material::GetShaderPass()` / `LightMode` 这套兼容提示，并最终把完全无提示的材质视作 `ForwardLit`。 ## 相关文档 diff --git a/docs/api/XCEngine/Rendering/ObjectIdEncoding/ObjectIdEncoding.md b/docs/api/XCEngine/Rendering/ObjectIdEncoding/ObjectIdEncoding.md index acbf0f2b..ccc54644 100644 --- a/docs/api/XCEngine/Rendering/ObjectIdEncoding/ObjectIdEncoding.md +++ b/docs/api/XCEngine/Rendering/ObjectIdEncoding/ObjectIdEncoding.md @@ -2,18 +2,48 @@ **命名空间**: `XCEngine::Rendering` -**类型**: `compatibility page` +**类型**: `compatibility note` -**描述**: 历史名称页。当前 object-id / picking 颜色编解码 helper 的真实 owner 已迁到 [ObjectIdCodec](../Picking/ObjectIdCodec/ObjectIdCodec.md)。 +**头文件**: `XCEngine/Rendering/Picking/ObjectIdCodec.h` -## 当前状态 +**描述**: 历史文档里的 `ObjectIdEncoding` 现已收口到 `Picking/ObjectIdCodec.h`；当前公开 API 提供 object-id 与 RGBA 颜色之间的稳定编码约定。 -- 旧文档里的 `ObjectIdEncoding` 只是历史叫法。 -- 当前真实头文件是 `XCEngine/Rendering/Picking/ObjectIdCodec.h`。 -- 新增文档与调用链说明应统一回到 [ObjectIdCodec](../Picking/ObjectIdCodec/ObjectIdCodec.md)。 +## 当前公开项 + +`ObjectIdCodec.h` 当前公开： + +- `EncodedObjectId` +- `CanEncodeObjectIdWithoutLoss(...)` +- `EncodeObjectIdToEncodedId(...)` +- `EncodeObjectIdToUInt32(...)` +- `EncodeObjectIdToColor(...)` +- `DecodeEncodedObjectIdFromColor(...)` +- `DecodeObjectIdFromColor(...)` + +## 当前语义 + +- object-id 渲染目标只保留运行时对象 ID 的低 `32` 位。 +- `CanEncodeObjectIdWithoutLoss(...)` 用来判断高 `32` 位是否全为 `0`。 +- RGBA 编码顺序固定为： + - `r` 对应最低 `8` 位 + - `g` 对应 `8-15` 位 + - `b` 对应 `16-23` 位 + - `a` 对应 `24-31` 位 + +## 使用位置 + +- [BuiltinObjectIdPass](../Passes/BuiltinObjectIdPass/BuiltinObjectIdPass.md) +- [BuiltinObjectIdOutlinePass](../Passes/BuiltinObjectIdOutlinePass/BuiltinObjectIdOutlinePass.md) +- [ObjectIdCodec](../Picking/ObjectIdCodec/ObjectIdCodec.md) + +## 迁移说明 + +- 旧名称 `ObjectIdEncoding` 只保留为兼容文档入口。 +- 需要查看当前权威说明时，优先使用 [ObjectIdCodec](../Picking/ObjectIdCodec/ObjectIdCodec.md)。 ## 相关文档 +- [Rendering](../Rendering.md) - [Picking](../Picking/Picking.md) - [ObjectIdCodec](../Picking/ObjectIdCodec/ObjectIdCodec.md) - [BuiltinObjectIdPass](../Passes/BuiltinObjectIdPass/BuiltinObjectIdPass.md) diff --git a/docs/api/XCEngine/Rendering/ObjectIdPass/ObjectIdPass.md b/docs/api/XCEngine/Rendering/ObjectIdPass/ObjectIdPass.md index beecf3e4..1e126aed 100644 --- a/docs/api/XCEngine/Rendering/ObjectIdPass/ObjectIdPass.md +++ b/docs/api/XCEngine/Rendering/ObjectIdPass/ObjectIdPass.md @@ -2,49 +2,43 @@ **命名空间**: `XCEngine::Rendering` -**类型**: `concept` +**类型**: `compatibility note` -**描述**: object-id 阶段的历史概念页。当前引擎不再公开独立的 `ObjectIdPass.h` 接口，而是把 object-id 输出槽位收口为可注入的 `RenderPass` 实现。 +**描述**: 历史上的 `ObjectIdPass.h` 抽象接口已经移除；当前 object-id 渲染插槽改为由 `CameraRenderer` 持有的通用 `RenderPass` 实例，默认实现是 `Passes::BuiltinObjectIdPass`。 -## 概览 +## 当前实现 -`ObjectIdPass` 这个名字在当前实现里仍然有语义价值，但它已经不再对应单独的 public header。 +当前公开 API 不再提供单独的 `ObjectIdPass` 基类： -- `CameraRenderer::SetObjectIdPass(...)` 当前接受的是 `std::unique_ptr`。 -- 默认实现是 [BuiltinObjectIdPass](../Passes/BuiltinObjectIdPass/BuiltinObjectIdPass.md)。 -- `CameraRenderRequest::objectId` 只描述输出目标，不描述实现类型。 +- [CameraRenderer::SetObjectIdPass](../CameraRenderer/SetObjectIdPass.md) 接收 `std::unique_ptr`。 +- [CameraRenderer::GetObjectIdPass](../CameraRenderer/GetObjectIdPass.md) 返回当前 object-id 插槽里的 `RenderPass*`。 +- 默认注入的实现是 [BuiltinObjectIdPass](../Passes/BuiltinObjectIdPass/BuiltinObjectIdPass.md)。 -因此这里更适合作为“object-id 阶段是什么”的迁移索引，而不是独立 API 页。 +因此，“object-id pass” 现在描述的是执行阶段里的一个职责槽位，而不是一个独立的公开头文件类型。 -## 当前运行时契约 +## 执行时机 -object-id 阶段的运行时输入输出仍然很稳定： +按 `engine/src/Rendering/Execution/CameraRenderer.cpp` 的当前实现，object-id 阶段位于： -- 输入已经提取好的 `RenderSceneData` -- 输入 object-id 输出 `RenderSurface` -- 由一个实现 `RenderPass` 的 scene pass 负责真正提交 GPU 命令 -- 返回 `false` 时，`CameraRenderer::Render()` 会直接终止这次相机提交 +1. `preScenePasses` +2. `shadowCaster` +3. `depthOnly` +4. 主 `RenderPipeline` +5. object-id pass +6. `postScenePasses` +7. `overlayPasses` -## 当前接入位置 +只有当 `request.objectId.IsRequested()` 为真时，`CameraRenderer` 才会执行这里持有的 pass。 -在 [CameraRenderer](../CameraRenderer/CameraRenderer.md) 里，object-id 阶段当前位于： +## 迁移说明 -1. 执行 pre-scene pass -2. 如请求了 `shadowCaster` / `depthOnly`，先执行对应 scene pass -3. 绘制主 `RenderPipeline` -4. 如果 `request.objectId.IsRequested()`，执行当前注入的 object-id `RenderPass` -5. 再执行 `postScenePasses` -6. 最后执行 `overlayPasses` - -## 当前迁移关系 - -- 如果你要看默认实现，请读 [BuiltinObjectIdPass](../Passes/BuiltinObjectIdPass/BuiltinObjectIdPass.md)。 -- 如果你要看 request 侧目标描述，请读 [ObjectIdRenderRequest](../CameraRenderRequest/ObjectIdRenderRequest/ObjectIdRenderRequest.md)。 -- 如果你要看 object-id 编码协议，请读 [ObjectIdCodec](../Picking/ObjectIdCodec/ObjectIdCodec.md) 与 [ObjectIdEncoding](../ObjectIdEncoding/ObjectIdEncoding.md)。 +- 旧文档里把 `ObjectIdPass` 视为独立接口的描述，已经不再对应当前源码。 +- 需要理解 object-id 语义时，优先查看 [BuiltinObjectIdPass](../Passes/BuiltinObjectIdPass/BuiltinObjectIdPass.md) 和 [ObjectIdCodec](../Picking/ObjectIdCodec/ObjectIdCodec.md)。 +- 需要理解插槽生命周期时，优先查看 [CameraRenderer](../CameraRenderer/CameraRenderer.md)。 ## 相关文档 -- [当前模块](../Rendering.md) +- [Rendering](../Rendering.md) - [CameraRenderer](../CameraRenderer/CameraRenderer.md) - [ObjectIdRenderRequest](../CameraRenderRequest/ObjectIdRenderRequest/ObjectIdRenderRequest.md) - [BuiltinObjectIdPass](../Passes/BuiltinObjectIdPass/BuiltinObjectIdPass.md) diff --git a/docs/api/XCEngine/Rendering/Passes/BuiltinColorScalePostProcessPass/BuiltinColorScalePostProcessPass.md b/docs/api/XCEngine/Rendering/Passes/BuiltinColorScalePostProcessPass/BuiltinColorScalePostProcessPass.md index 0facb795..907b0245 100644 --- a/docs/api/XCEngine/Rendering/Passes/BuiltinColorScalePostProcessPass/BuiltinColorScalePostProcessPass.md +++ b/docs/api/XCEngine/Rendering/Passes/BuiltinColorScalePostProcessPass/BuiltinColorScalePostProcessPass.md @@ -6,53 +6,36 @@ **头文件**: `XCEngine/Rendering/Passes/BuiltinColorScalePostProcessPass.h` -**描述**: 当前内建的 fullscreen post-process pass，对 `sourceColorView` 采样后按给定 `colorScale` 乘算，并输出到目标颜色附件。 +**描述**: 基于 `RenderPassContext::sourceColorView` 的全屏颜色缩放后处理 pass，当前由相机 post-process 栈通过 factory 按需创建。 ## 概览 -`BuiltinColorScalePostProcessPass` 是 `CameraRenderer` fullscreen 阶段当前最简单的一条后处理实现。 +`BuiltinColorScalePostProcessPass` 是当前 post-process 路径里最简单的一类 fullscreen pass： -它的输入输出模型很明确： +- 从 `sourceColorView` 采样输入颜色 +- 把 `m_colorScale` 写入常量集 +- 输出到 `context.surface` -- 输入来自 `RenderPassContext::sourceColorView` -- 输出写入 `RenderPassContext::surface` 的第一个颜色附件 -- 处理方式是对采样结果乘以 `colorScale` +它通常不由调用方手工长期持有，而是通过 [BuildCameraPostProcessPassSequence](../../Planning/CameraPostProcessPassFactory/CameraPostProcessPassFactory.md) 根据 `CameraPostProcessStack` 临时组装。 -## 当前执行前提 +## 当前公开能力 -`Execute(...)` 当前要求： - -- `renderContext` 有效 -- `sourceColorView != nullptr` -- 目标 `surface` 至少有一个有效颜色附件 -- `renderArea.width > 0 && renderArea.height > 0` - -否则直接返回 `false`。 - -## 当前实现细节 - -- 如果构造时没给 `shaderPath`，会回退到 builtin color-scale shader 路径。 -- 资源初始化会按 `(device, backend, renderTargetFormat)` 惰性重建。 -- 当前固定创建三组 descriptor set： - - constants CBV - - source color SRV - - linear clamp sampler -- 提交阶段绘制一个 fullscreen triangle，避免显式 quad 顶点缓冲。 -- 如果 `surface` 开启自动状态切换，会在 `RenderTarget` 与 `surface.GetColorStateAfter()` 之间自动迁移。 - -## 当前公开方法 - -- `GetName()` -- `Execute(...)` -- `Shutdown()` +- 构造时指定 `colorScale` 和可选 `shaderPath` +- `GetName()` / `Execute(...)` / `Shutdown()` - `SetColorScale(...)` / `GetColorScale()` - `SetShaderPath(...)` / `GetShaderPath()` -## 真实使用位置 +## 当前实现边界 -- [CameraPostProcessPassFactory](../../Planning/CameraPostProcessPassFactory/CameraPostProcessPassFactory.md) 当前会把 `ColorScale` 声明转换成它。 -- `SceneRenderer` 把生成的 sequence 挂到 `CameraRenderRequest::postProcess`。 -- `tests/Rendering/integration/post_process_scene/` 覆盖了真实 fullscreen 链路。 +- 只处理单个全屏颜色缩放效果，不负责 tone mapping、output transfer 或 final compositing。 +- 资源初始化按 `RenderContext` 后端和 render target format 惰性建立。 +- 输入颜色必须来自 `RenderPassContext::sourceColorView`；它不会自己分配中间表面。 + +## 真实接入位置 + +- `SceneRenderer` 先根据相机的 `postProcess` 描述构建 `CameraRenderRequest::postProcess`。 +- `BuildCameraPostProcessPassSequence(...)` 读取 [CameraPostProcessPassDesc](../../Planning/CameraPostProcessDesc/CameraPostProcessDesc.md) 并生成当前 pass。 +- `CameraRenderer` 在主场景之后、final-output 之前执行这一阶段。 ## 相关文档 diff --git a/docs/api/XCEngine/Rendering/Passes/BuiltinFinalColorPass/BuiltinFinalColorPass.md b/docs/api/XCEngine/Rendering/Passes/BuiltinFinalColorPass/BuiltinFinalColorPass.md index ed169b3a..820baf3f 100644 --- a/docs/api/XCEngine/Rendering/Passes/BuiltinFinalColorPass/BuiltinFinalColorPass.md +++ b/docs/api/XCEngine/Rendering/Passes/BuiltinFinalColorPass/BuiltinFinalColorPass.md @@ -6,54 +6,37 @@ **头文件**: `XCEngine/Rendering/Passes/BuiltinFinalColorPass.h` -**描述**: 当前内建的 final-output fullscreen pass，对中间 scene color 应用输出传递、曝光、色调映射和最终颜色缩放，再写回最终颜色目标。 +**描述**: final-color 阶段的 fullscreen pass，负责把 `ResolvedFinalColorPolicy` 应用到最终输出颜色上。 ## 概览 -`BuiltinFinalColorPass` 是主场景绘制之后、真正写回最终颜色目标之前的最后一层颜色处理。 +`BuiltinFinalColorPass` 位于 post-process 之后、最终回写目标表面之前。它当前统一承载： -它消费的是 [FinalColorSettings](../../Planning/FinalColorSettings/FinalColorSettings.md)： +- output transfer +- exposure +- tone mapping +- final color scale -- `outputTransferMode` -- `exposureMode` / `exposureValue` -- `toneMappingMode` -- `finalColorScale` +对应的参数通过 `FinalColorSettings` 或 `ResolvedFinalColorPolicy` 注入。 -## 当前执行前提 +## 当前公开能力 -`Execute(...)` 当前要求： - -- `renderContext` 有效 -- `sourceColorView != nullptr` -- 目标 `surface` 至少有一个有效颜色附件 -- `renderArea` 宽高都大于 `0` - -不满足时会记录错误并返回 `false`。 - -## 当前实现细节 - -- 默认 `shaderPath` 会回退到 builtin final-color shader。 -- 内部把 `FinalColorSettings` 写入一份 fullscreen 常量： - - `colorScale` - - `params.x = exposure multiplier` - - `params.y = outputTransferMode` - - `params.z = toneMappingMode` -- `FinalColorExposureMode::Fixed` 会把 `exposureValue` 钳到非负后再参与计算。 -- 和 color-scale pass 一样，当前也使用 constants / texture / sampler 三组 descriptor set 加 fullscreen triangle。 - -## 当前公开方法 - -- `GetName()` -- `Execute(...)` -- `Shutdown()` +- 构造时指定 `FinalColorSettings` 和可选 `shaderPath` +- `GetName()` / `Execute(...)` / `Shutdown()` - `SetSettings(...)` / `GetSettings()` - `SetShaderPath(...)` / `GetShaderPath()` -## 真实使用位置 +## 当前实现边界 -- [FinalColorPassFactory](../../Planning/FinalColorPassFactory/FinalColorPassFactory.md) 当前会在需要处理时生成这条 pass。 -- `SceneRenderer` 把生成的 sequence 挂到 `CameraRenderRequest::finalOutput`。 -- `tests/Rendering/integration/final_color_scene/` 覆盖了真实 final-color 链路。 +- 它只负责 final-color 阶段，不解析相机 override 或 pipeline 默认值。 +- `SceneRenderer` 先在 planning 阶段解析 [ResolvedFinalColorPolicy](../../Planning/FinalColorSettings/FinalColorSettings.md)，再通过 factory 创建当前 pass。 +- 和其他 fullscreen pass 一样，它依赖 `RenderPassContext::sourceColorView`，不会自己管理中间表面生命周期。 + +## 真实接入位置 + +- `SceneRenderer::ResolveCameraFinalColorPolicies(...)` 先解析策略。 +- `BuildFinalColorPassSequence(...)` 根据策略决定是否创建当前 pass。 +- `CameraRenderer` 在 `postProcess` 之后、`objectId` 之前执行 final-output 阶段。 ## 相关文档 diff --git a/docs/api/XCEngine/Rendering/Passes/Passes.md b/docs/api/XCEngine/Rendering/Passes/Passes.md index 683650f0..01b4d478 100644 --- a/docs/api/XCEngine/Rendering/Passes/Passes.md +++ b/docs/api/XCEngine/Rendering/Passes/Passes.md @@ -4,24 +4,20 @@ **类型**: `submodule` -**描述**: 承载 builtin object-id、selection outline、infinite grid、fullscreen post-process / final-color，以及 depth-only / shadow-caster 一类可复用渲染 pass 与配套样式/参数类型。 +**描述**: 承载 builtin object-id、selection outline、infinite grid、fullscreen post-process / final-color，以及 depth-only / shadow-caster 一类可复用渲染 pass 与配套参数类型。 -## 概述 +## 概览 `Rendering::Passes` 不是用来替代 [RenderPipeline](../RenderPipeline/RenderPipeline.md) 的第二套主渲染框架，而是承载几类被 `CameraRenderer`、editor 视口流程和 builtin pipeline 复用的 builtin pass： -- [BuiltinObjectIdPass](BuiltinObjectIdPass/BuiltinObjectIdPass.md) 把可见物体编码成 object-id 颜色，写到辅助渲染目标，供拾取和选中反馈使用。 +- [BuiltinObjectIdPass](BuiltinObjectIdPass/BuiltinObjectIdPass.md) 把可见物体编码成 object-id 颜色，写到辅助渲染目标。 - [BuiltinObjectIdOutlinePass](BuiltinObjectIdOutlinePass/BuiltinObjectIdOutlinePass.md) 读取 object-id 纹理和选中对象列表，把轮廓或调试 mask 叠加回场景颜色。 - [BuiltinInfiniteGridPass](BuiltinInfiniteGridPass/BuiltinInfiniteGridPass.md) 给 Scene View 一类编辑器视口叠加无限网格。 +- [BuiltinColorScalePostProcessPass](BuiltinColorScalePostProcessPass/BuiltinColorScalePostProcessPass.md) 执行基于 `sourceColorView` 的全屏颜色缩放后处理。 +- [BuiltinFinalColorPass](BuiltinFinalColorPass/BuiltinFinalColorPass.md) 执行 exposure、tone mapping、output transfer 和 final color scale 的最终输出阶段。 - [BuiltinDepthStylePassBase](BuiltinDepthStylePassBase/BuiltinDepthStylePassBase.md) 为深度风格场景重绘 pass 提供共享执行骨架。 - [BuiltinDepthOnlyPass](BuiltinDepthOnlyPass/BuiltinDepthOnlyPass.md) 是 `CameraRenderer` 默认 `depthOnly` request 的 builtin 实现。 - [BuiltinShadowCasterPass](BuiltinShadowCasterPass/BuiltinShadowCasterPass.md) 是 `CameraRenderer` 默认 `shadowCaster` request 的 builtin 实现。 -- [BuiltinColorScalePostProcessPass](BuiltinColorScalePostProcessPass/BuiltinColorScalePostProcessPass.md) 是当前 camera post-process stack 的 fullscreen 颜色缩放实现。 -- [BuiltinFinalColorPass](BuiltinFinalColorPass/BuiltinFinalColorPass.md) 是当前 final-output 阶段的 fullscreen 最终颜色处理实现。 - -其中 object-id / outline / infinite-grid 更接近“主场景之外的附加结果”；depth-only / shadow-caster 属于 `ScenePassRenderRequest` 路径；fullscreen post-process / final-color 则对应 `CameraRenderRequest::postProcess` 与 `finalOutput` 两个阶段。 - -当前这些 builtin pass 更多是“底层执行单元”。真正决定 Scene View 要不要画网格、要不要叠选中轮廓、这些效果要挂到 `postScenePasses` 还是 `overlayPasses` 上的逻辑，已经迁移到 editor 侧的 [SceneViewportRenderPlan](../../Editor/Viewport/SceneViewportRenderPlan/SceneViewportRenderPlan.md)；真正决定 depth-only / shadow-caster surface 与 clear 策略的，则是 [CameraRenderRequest](../CameraRenderRequest/CameraRenderRequest.md)。 ## 典型链路 @@ -30,72 +26,64 @@ 当前 Scene View 相关链路大致是： 1. [CameraRenderer](../CameraRenderer/CameraRenderer.md) 先执行主 `RenderPipeline`。 -2. 如果 [CameraRenderRequest](../CameraRenderRequest/CameraRenderRequest.md) 里请求了 `objectId.surface`，则额外执行 [BuiltinObjectIdPass](BuiltinObjectIdPass/BuiltinObjectIdPass.md)，把每个可见物体的 `GameObject` ID 编码进辅助纹理。 -3. editor 侧的 [SceneViewportRenderPlan](../../Editor/Viewport/SceneViewportRenderPlan/SceneViewportRenderPlan.md) 会根据 overlay、选中对象和 render targets 同时构建 `postScenePasses` 与 `overlayPasses`。 -4. 其中 `postScenePasses` 里的 `SceneViewportGridPass` / `SceneViewportSelectionOutlinePass` 包装器，最终分别调用 [BuiltinInfiniteGridPass](BuiltinInfiniteGridPass/BuiltinInfiniteGridPass.md) 与 [BuiltinObjectIdOutlinePass](BuiltinObjectIdOutlinePass/BuiltinObjectIdOutlinePass.md)；`overlayPasses` 则保留给 editor overlay 的最终叠加层。 +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)。 -### Depth-only / shadow-caster request +### Fullscreen post-process / final-color -对 `CameraRenderer` 自身持有的 scene pass，当前链路大致是： +`SceneRenderer` 当前会先在 planning 阶段把： -1. 调用方在 [CameraRenderRequest](../CameraRenderRequest/CameraRenderRequest.md) 的 `shadowCaster` / `depthOnly` 槽位里提供 `ScenePassRenderRequest`。 -2. `CameraRenderer` 在执行主 `RenderPipeline` 前，先按顺序驱动 [BuiltinShadowCasterPass](BuiltinShadowCasterPass/BuiltinShadowCasterPass.md) 与 [BuiltinDepthOnlyPass](BuiltinDepthOnlyPass/BuiltinDepthOnlyPass.md) 的默认实例。 -3. 这两类 pass 共用 [BuiltinDepthStylePassBase::Execute](BuiltinDepthStylePassBase/Execute.md) 的执行框架，因此当前都要求 `surface` 同时提供 `colorAttachments[0]` 与 `depthAttachment`，并复用 `renderArea`、clear flags 与状态迁移逻辑。 +- 相机 `postProcess` 描述栈 +- pipeline 默认 final-color 设置 +- 相机 final-color override -### Fullscreen post-process / final-output +解析成 `CameraRenderRequest::postProcess` 与 `CameraRenderRequest::finalOutput`。 -当前 fullscreen 链路大致是： +随后 `CameraRenderer` 在主场景之后依次执行： -1. [SceneRenderer](../SceneRenderer/SceneRenderer.md) 读取相机上的声明式 post-process stack 与 final-color overrides。 -2. [CameraPostProcessPassFactory](../Planning/CameraPostProcessPassFactory/CameraPostProcessPassFactory.md) 把声明式 stack 转成 [BuiltinColorScalePostProcessPass](BuiltinColorScalePostProcessPass/BuiltinColorScalePostProcessPass.md) 序列。 -3. [FinalColorPassFactory](../Planning/FinalColorPassFactory/FinalColorPassFactory.md) 把解析后的 `ResolvedFinalColorPolicy` 转成 [BuiltinFinalColorPass](BuiltinFinalColorPass/BuiltinFinalColorPass.md) 序列。 -4. [CameraRenderer](../CameraRenderer/CameraRenderer.md) 在 `MainScene` 之后按 `PostProcess -> FinalOutput` 顺序执行 fullscreen pass 链；当序列长度大于 `1` 时，会借助中间 surface cache 在多个目标之间串接读写。 +1. `postProcess` +2. `finalOutput` +3. `objectId` +4. `postScenePasses` +5. `overlayPasses` ## 当前公开概念 -| 类型 / 头文件 | 角色 | +| 类型 / 页面 | 角色 | |------|------| -| [BuiltinObjectIdPass](BuiltinObjectIdPass/BuiltinObjectIdPass.md) | 生成 object-id 颜色缓冲，给拾取与 outline 作为输入。 | -| [BuiltinObjectIdOutlinePass](BuiltinObjectIdOutlinePass/BuiltinObjectIdOutlinePass.md) | 读取 object-id 纹理，在主颜色目标上合成选中轮廓或调试 mask。 | -| [ObjectIdOutlineStyle](ObjectIdOutlineStyle/ObjectIdOutlineStyle.md) | 轮廓颜色、像素宽度、调试模式的配置载体。 | +| [BuiltinObjectIdPass](BuiltinObjectIdPass/BuiltinObjectIdPass.md) | 生成 object-id 颜色缓冲。 | +| [BuiltinObjectIdOutlinePass](BuiltinObjectIdOutlinePass/BuiltinObjectIdOutlinePass.md) | 在主颜色目标上合成选中轮廓。 | | [BuiltinInfiniteGridPass](BuiltinInfiniteGridPass/BuiltinInfiniteGridPass.md) | Scene View 网格覆盖层的底层执行 pass。 | -| [InfiniteGridPassData](BuiltinInfiniteGridPass/InfiniteGridPassData.md) | 网格 pass 使用的相机姿态与裁剪参数。 | -| [InfiniteGridParameters](BuiltinInfiniteGridPass/InfiniteGridParameters.md) | 由相机状态推导出的网格尺度、过渡和淡出参数。 | -| [BuildInfiniteGridParameters](BuiltinInfiniteGridPass/BuildInfiniteGridParameters.md) | 把 Scene View 相机数据折算成稳定的十进制网格参数。 | +| [BuiltinColorScalePostProcessPass](BuiltinColorScalePostProcessPass/BuiltinColorScalePostProcessPass.md) | 相机 post-process 栈当前的颜色缩放全屏 pass。 | +| [BuiltinFinalColorPass](BuiltinFinalColorPass/BuiltinFinalColorPass.md) | final-color 阶段的最终合成 / 输出变换 pass。 | | [BuiltinDepthStylePassBase](BuiltinDepthStylePassBase/BuiltinDepthStylePassBase.md) | depth-only / shadow-caster 场景重绘共享的执行骨架。 | | [BuiltinDepthOnlyPass](BuiltinDepthOnlyPass/BuiltinDepthOnlyPass.md) | `CameraRenderer` 默认的 depth-only scene pass。 | | [BuiltinShadowCasterPass](BuiltinShadowCasterPass/BuiltinShadowCasterPass.md) | `CameraRenderer` 默认的 shadow-caster scene pass。 | -| [BuiltinColorScalePostProcessPass](BuiltinColorScalePostProcessPass/BuiltinColorScalePostProcessPass.md) | camera post-process 栈当前的 fullscreen 颜色缩放 pass。 | -| [BuiltinFinalColorPass](BuiltinFinalColorPass/BuiltinFinalColorPass.md) | final-output 阶段应用输出传递、曝光、色调映射和颜色缩放的 fullscreen pass。 | ## 测试与真实调用点 -- `tests/Rendering/unit/test_camera_scene_renderer.cpp` 验证了 `CameraRenderer` 中 object-id pass 与可选 pass sequence 的接入时机。 -- `engine/src/Rendering/CameraRenderer.cpp` 当前把 [BuiltinShadowCasterPass](BuiltinShadowCasterPass/BuiltinShadowCasterPass.md) 与 [BuiltinDepthOnlyPass](BuiltinDepthOnlyPass/BuiltinDepthOnlyPass.md) 作为默认 scene pass 挂进 `shadowCaster` / `depthOnly` request。 -- `tests/Rendering/unit/test_builtin_forward_pipeline.cpp` 固定了 depth-only / shadow-caster 资源契约与 final-color shader 的显式 fullscreen 资源声明。 -- `tests/Editor/test_scene_viewport_overlay_renderer.cpp` 固定了 `BuildInfiniteGridParameters(...)` 的十进制尺度、过渡和淡出语义。 -- `tests/Editor/test_viewport_render_flow_utils.cpp` 验证了 Scene View render plan 如何组装 grid / selection outline / overlay pass，以及 object-id SRV 缺失时的警告路径。 -- `tests/Rendering/integration/post_process_scene/` 和 `tests/Rendering/integration/final_color_scene/` 分别覆盖了 post-process 与 final-output 的真实 fullscreen 渲染路径。 +- `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`。 +- `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，而不是直接从主颜色结果反推。 -- depth-style 家族当前仍要求 `RenderSurface` 提供首个颜色附件和深度附件；它不是“只给一个 depth target 就能跑”的极简路径。 -- 具体 pass 的资源状态切换大多由调用方保证，单个 pass 本身往往只做最小提交逻辑。 +- fullscreen pass 依赖调用方准备 `sourceColorView` 和中间表面；单个 pass 本身不管理整条阶段链。 ## 相关文档 - [BuiltinObjectIdPass](BuiltinObjectIdPass/BuiltinObjectIdPass.md) -- [BuiltinInfiniteGridPass](BuiltinInfiniteGridPass/BuiltinInfiniteGridPass.md) - [BuiltinObjectIdOutlinePass](BuiltinObjectIdOutlinePass/BuiltinObjectIdOutlinePass.md) -- [ObjectIdOutlineStyle](ObjectIdOutlineStyle/ObjectIdOutlineStyle.md) +- [BuiltinInfiniteGridPass](BuiltinInfiniteGridPass/BuiltinInfiniteGridPass.md) +- [BuiltinColorScalePostProcessPass](BuiltinColorScalePostProcessPass/BuiltinColorScalePostProcessPass.md) +- [BuiltinFinalColorPass](BuiltinFinalColorPass/BuiltinFinalColorPass.md) - [BuiltinDepthStylePassBase](BuiltinDepthStylePassBase/BuiltinDepthStylePassBase.md) - [BuiltinDepthOnlyPass](BuiltinDepthOnlyPass/BuiltinDepthOnlyPass.md) - [BuiltinShadowCasterPass](BuiltinShadowCasterPass/BuiltinShadowCasterPass.md) -- [BuiltinColorScalePostProcessPass](BuiltinColorScalePostProcessPass/BuiltinColorScalePostProcessPass.md) -- [BuiltinFinalColorPass](BuiltinFinalColorPass/BuiltinFinalColorPass.md) -- [SceneViewportRenderPlan](../../Editor/Viewport/SceneViewportRenderPlan/SceneViewportRenderPlan.md) - [CameraRenderRequest](../CameraRenderRequest/CameraRenderRequest.md) - [CameraRenderer](../CameraRenderer/CameraRenderer.md) -- [当前模块](../Rendering.md) +- [Rendering](../Rendering.md) diff --git a/docs/api/XCEngine/Rendering/Planning/CameraPostProcessDesc/CameraPostProcessDesc.md b/docs/api/XCEngine/Rendering/Planning/CameraPostProcessDesc/CameraPostProcessDesc.md index 492688fe..552ac628 100644 --- a/docs/api/XCEngine/Rendering/Planning/CameraPostProcessDesc/CameraPostProcessDesc.md +++ b/docs/api/XCEngine/Rendering/Planning/CameraPostProcessDesc/CameraPostProcessDesc.md @@ -2,13 +2,13 @@ **命名空间**: `XCEngine::Rendering` -**类型**: `enum + structs + alias` +**类型**: `enum + related structs + type alias` **头文件**: `XCEngine/Rendering/Planning/CameraPostProcessDesc.h` -**描述**: 相机后处理描述头，定义相机声明式 post-process 栈当前可用的 pass 类型、参数载体和 stack 别名。 +**描述**: 描述相机 post-process 栈的声明式数据结构；当前公开的 pass 类型只有颜色缩放，但调用链已经按可扩展栈模型组织。 -## 头文件中的主要类型 +## 头文件中的公开项 - `CameraPostProcessPassType` - `CameraColorScalePostProcessDesc` @@ -17,17 +17,23 @@ ## 当前语义 -- `CameraPostProcessPassType` 当前只公开 `ColorScale`。 -- `CameraColorScalePostProcessDesc` 保存全屏颜色缩放向量。 -- `CameraPostProcessPassDesc::MakeColorScale(...)` 提供便捷构造入口。 -- `CameraPostProcessPassDesc::IsValid()` 负责过滤掉当前实现不认识的 pass 类型。 -- `CameraPostProcessStack` 是 `std::vector`，供 `CameraComponent` 直接持有。 +- `CameraPostProcessPassType::ColorScale` 表示全屏颜色缩放 pass。 +- `CameraColorScalePostProcessDesc` 只保存一个 `scale` 向量。 +- `CameraPostProcessPassDesc::MakeColorScale(...)` 提供了当前唯一的便捷构造入口。 +- `IsValid()` 负责校验描述是否属于当前引擎认识的 pass 类型。 -## 当前调用链 +`CameraPostProcessStack` 则是 `std::vector`，供相机按顺序声明多个后处理阶段。 -- `CameraComponent` 序列化、反序列化并持有这份声明式 stack。 -- [CameraPostProcessPassFactory](../CameraPostProcessPassFactory/CameraPostProcessPassFactory.md) 把它转换成运行时 `RenderPassSequence`。 -- `SceneRenderer` 再把生成的 sequence 挂到 `CameraRenderRequest::postProcess`。 +## 当前接入位置 + +- `CameraComponent` 保存 post-process 描述栈。 +- `SceneRenderer` 读取这些描述，构建 `CameraRenderRequest::postProcess`。 +- [BuildCameraPostProcessPassSequence](../CameraPostProcessPassFactory/CameraPostProcessPassFactory.md) 再把描述转换成实际的 `RenderPassSequence`。 + +## 当前边界 + +- 当前只支持 `ColorScale`，还不是完整的 post-process graph。 +- 这里描述的是 planning 数据，不直接拥有 GPU 资源或 fullscreen pass 实例。 ## 相关文档 diff --git a/docs/api/XCEngine/Rendering/Planning/CameraPostProcessPassFactory/CameraPostProcessPassFactory.md b/docs/api/XCEngine/Rendering/Planning/CameraPostProcessPassFactory/CameraPostProcessPassFactory.md index 612c6a09..dea79f5f 100644 --- a/docs/api/XCEngine/Rendering/Planning/CameraPostProcessPassFactory/CameraPostProcessPassFactory.md +++ b/docs/api/XCEngine/Rendering/Planning/CameraPostProcessPassFactory/CameraPostProcessPassFactory.md @@ -6,30 +6,32 @@ **头文件**: `XCEngine/Rendering/Planning/CameraPostProcessPassFactory.h` -**描述**: 相机后处理 pass 工厂头，负责把声明式 `CameraPostProcessStack` 转换成运行时 `RenderPassSequence`。 +**描述**: 把 `CameraPostProcessStack` 转换成实际的 `RenderPassSequence`，供 `SceneRenderer` 写入 `CameraRenderRequest::postProcess`。 -## 当前公开能力 +## 公开函数 -```cpp -std::unique_ptr BuildCameraPostProcessPassSequence( - const CameraPostProcessStack& postProcessStack); -``` +| 函数 | 说明 | +|------|------| +| `BuildCameraPostProcessPassSequence(const CameraPostProcessStack&)` | 根据相机 post-process 描述栈构建全屏 pass 序列。 | -## 当前实现行为 +## 当前行为 -- 如果 stack 为空，直接返回 `nullptr`。 -- 逐条遍历 `CameraPostProcessPassDesc`，跳过 `IsValid()` 为假的项。 -- 当前只识别 `CameraPostProcessPassType::ColorScale`，并创建 [BuiltinColorScalePostProcessPass](../../Passes/BuiltinColorScalePostProcessPass/BuiltinColorScalePostProcessPass.md)。 -- 如果过滤后没有任何有效 pass，同样返回 `nullptr`。 +`BuildCameraPostProcessPassSequence(...)` 当前会： -## 当前调用链 +1. 栈为空时直接返回 `nullptr`。 +2. 逐条遍历 `CameraPostProcessPassDesc`。 +3. 跳过 `IsValid()` 为假的描述。 +4. 遇到 `ColorScale` 时创建 [BuiltinColorScalePostProcessPass](../../Passes/BuiltinColorScalePostProcessPass/BuiltinColorScalePostProcessPass.md)。 +5. 如果最终没有生成任何 pass，则返回 `nullptr`。 -- `SceneRenderer::AttachFullscreenStageRequests(...)` 调用它构建 `CameraRenderRequest::postProcess.passes`。 -- 生成的 sequence 由 `CameraRenderer` 在 `PostProcess` 阶段按 fullscreen pass 链执行。 +## 当前边界 + +- 这里只做“描述到 pass 序列”的转换，不负责创建中间表面。 +- 生成出的 sequence 会由 `SceneRenderer` 暂存，再借用到 `CameraRenderRequest::postProcess.passes`。 +- 当前不会尝试折叠或合并多个 post-process pass。 ## 相关文档 - [Planning](../Planning.md) - [CameraPostProcessDesc](../CameraPostProcessDesc/CameraPostProcessDesc.md) - [BuiltinColorScalePostProcessPass](../../Passes/BuiltinColorScalePostProcessPass/BuiltinColorScalePostProcessPass.md) -- [CameraRenderRequest](../CameraRenderRequest/CameraRenderRequest.md) diff --git a/docs/api/XCEngine/Rendering/Planning/FinalColorPassFactory/FinalColorPassFactory.md b/docs/api/XCEngine/Rendering/Planning/FinalColorPassFactory/FinalColorPassFactory.md index 32b79ff4..bcaa3fbf 100644 --- a/docs/api/XCEngine/Rendering/Planning/FinalColorPassFactory/FinalColorPassFactory.md +++ b/docs/api/XCEngine/Rendering/Planning/FinalColorPassFactory/FinalColorPassFactory.md @@ -6,29 +6,31 @@ **头文件**: `XCEngine/Rendering/Planning/FinalColorPassFactory.h` -**描述**: final-output pass 工厂头，负责把 `ResolvedFinalColorPolicy` 转换成最终的 fullscreen `RenderPassSequence`。 +**描述**: 根据 `ResolvedFinalColorPolicy` 决定是否生成 final-output 阶段的 `RenderPassSequence`。 -## 当前公开能力 +## 公开函数 -```cpp -std::unique_ptr BuildFinalColorPassSequence( - const ResolvedFinalColorPolicy& finalColorPolicy); -``` +| 函数 | 说明 | +|------|------| +| `BuildFinalColorPassSequence(const ResolvedFinalColorPolicy&)` | 当 final-color 策略需要处理时，创建只含 `BuiltinFinalColorPass` 的序列。 | -## 当前实现行为 +## 当前行为 -- 如果 `finalColorPolicy.RequiresProcessing()` 为假，直接返回 `nullptr`。 -- 否则创建一个新的 `RenderPassSequence`。 -- 当前只往序列里压入一个 [BuiltinFinalColorPass](../../Passes/BuiltinFinalColorPass/BuiltinFinalColorPass.md)。 +`BuildFinalColorPassSequence(...)` 当前会： -## 当前调用链 +1. 调用 `finalColorPolicy.RequiresProcessing()`。 +2. 如果结果为假，直接返回 `nullptr`。 +3. 否则创建一个新的 `RenderPassSequence`。 +4. 把 [BuiltinFinalColorPass](../../Passes/BuiltinFinalColorPass/BuiltinFinalColorPass.md) 加进去并返回。 -- `SceneRenderer::AttachFullscreenStageRequests(...)` 调用它构建 `CameraRenderRequest::finalOutput.passes`。 -- `CameraRenderer` 随后在 `FinalOutput` 阶段按 fullscreen pass 链执行这条 sequence。 +## 当前边界 + +- factory 只决定“要不要有 final-output 阶段”，不负责解析 pipeline 默认值或相机 override。 +- 策略解析由 [ResolveFinalColorPolicy](../FinalColorSettings/FinalColorSettings.md) 完成。 +- 生成的 sequence 生命周期由 `SceneRenderer` 持有。 ## 相关文档 - [Planning](../Planning.md) - [FinalColorSettings](../FinalColorSettings/FinalColorSettings.md) - [BuiltinFinalColorPass](../../Passes/BuiltinFinalColorPass/BuiltinFinalColorPass.md) -- [CameraRenderRequest](../CameraRenderRequest/CameraRenderRequest.md) diff --git a/docs/api/XCEngine/Rendering/Planning/FinalColorSettings/FinalColorSettings.md b/docs/api/XCEngine/Rendering/Planning/FinalColorSettings/FinalColorSettings.md index fad2bafa..c114e911 100644 --- a/docs/api/XCEngine/Rendering/Planning/FinalColorSettings/FinalColorSettings.md +++ b/docs/api/XCEngine/Rendering/Planning/FinalColorSettings/FinalColorSettings.md @@ -2,13 +2,13 @@ **命名空间**: `XCEngine::Rendering` -**类型**: `enums + structs + helpers` +**类型**: `enums + related structs + utility functions` **头文件**: `XCEngine/Rendering/Planning/FinalColorSettings.h` -**描述**: 最终颜色处理策略头，定义 final-output 阶段的输出传递、曝光、色调映射、颜色缩放，以及默认值与覆盖值的合并规则。 +**描述**: 定义 final-color 阶段的输出变换、曝光、tone mapping 与颜色缩放策略，以及 pipeline 默认值和相机 override 的合并规则。 -## 头文件中的主要类型 +## 头文件中的公开项 - `FinalColorOutputTransferMode` - `FinalColorExposureMode` @@ -16,31 +16,55 @@ - `FinalColorSettings` - `FinalColorOverrideSettings` - `ResolvedFinalColorPolicy` +- `ApplyFinalColorOverrides(...)` +- `ResolveFinalColorPolicy(...)` ## 当前语义 -- `FinalColorSettings` 表示 pipeline 默认策略或某一层已解析出的最终策略。 -- `RequiresProcessing()` 用来判断是否真的需要挂 final-output fullscreen pass。 -- `FinalColorOverrideSettings` 采用逐字段 `overrideXxx` 开关，允许 camera / volume 只覆盖部分配置。 -- `HasOverrides()` 用来快速判断是否存在任何覆盖项。 -- `ResolvedFinalColorPolicy` 在设置值之外额外记录是否命中了 pipeline defaults、camera overrides 和 volume overrides。 +### `FinalColorSettings` -## 当前 helper +描述一套可直接执行的 final-color 设置： -- `ApplyFinalColorOverrides(...)` - 只把被 `overrideXxx` 标记的字段覆写到目标 settings。 -- `ResolveFinalColorPolicy(...)` - 先拷贝 pipeline 默认值，再依次应用 camera overrides 和 volume overrides。 +- `outputTransferMode` +- `exposureMode` +- `exposureValue` +- `toneMappingMode` +- `finalColorScale` -## 当前调用链 +`RequiresProcessing()` 用来判断这些设置是否真的需要启用 final-output 阶段。 -- `SceneRenderer::ResolveCameraFinalColorPolicies(...)` 为每个 request 生成 `finalColorPolicy`。 -- [FinalColorPassFactory](../FinalColorPassFactory/FinalColorPassFactory.md) 根据 `RequiresProcessing()` 决定是否构建 final-output sequence。 -- [BuiltinFinalColorPass](../../Passes/BuiltinFinalColorPass/BuiltinFinalColorPass.md) 真正消费解析后的策略。 +### `FinalColorOverrideSettings` + +描述相机或体积系统对每个字段的可选覆盖。每个字段都有对应的 `override*` 开关；只有开关为真时才会写回目标设置。 + +### `ResolvedFinalColorPolicy` + +在 `FinalColorSettings` 基础上增加： + +- `hasPipelineDefaults` +- `hasCameraOverrides` +- `hasVolumeOverrides` + +用来记录当前策略是如何解析出来的。 + +## 合并规则 + +`ResolveFinalColorPolicy(...)` 当前按下面顺序合并： + +1. 先复制 pipeline 默认值。 +2. 如果有相机 override，就通过 `ApplyFinalColorOverrides(...)` 覆盖。 +3. 如果有 volume override，再覆盖一次。 + +因此后应用的 override 拥有更高优先级。 + +## 当前接入位置 + +- `RenderPipelineAsset` 可以提供 pipeline 默认 `FinalColorSettings`。 +- `SceneRenderer::ResolveCameraFinalColorPolicies(...)` 把 pipeline 默认值与相机 override 合并成 `ResolvedFinalColorPolicy`。 +- [BuildFinalColorPassSequence](../FinalColorPassFactory/FinalColorPassFactory.md) 根据解析结果决定是否创建 final-output pass。 ## 相关文档 - [Planning](../Planning.md) - [FinalColorPassFactory](../FinalColorPassFactory/FinalColorPassFactory.md) - [BuiltinFinalColorPass](../../Passes/BuiltinFinalColorPass/BuiltinFinalColorPass.md) -- [CameraRenderRequest](../CameraRenderRequest/CameraRenderRequest.md) diff --git a/docs/api/XCEngine/Rendering/Planning/Planning.md b/docs/api/XCEngine/Rendering/Planning/Planning.md index d13125cc..2497f7da 100644 --- a/docs/api/XCEngine/Rendering/Planning/Planning.md +++ b/docs/api/XCEngine/Rendering/Planning/Planning.md @@ -6,12 +6,11 @@ **头文件目录**: `engine/include/XCEngine/Rendering/Planning/` -**描述**: Rendering 请求规划层，负责相机收集、排序、clear 推导、render-area 解析，以及 `CameraRenderRequest` 的组装与 fullscreen 阶段配置。 +**描述**: Rendering 请求规划层，负责相机收集、排序、clear 推导、render-area 解析，以及 `CameraRenderRequest`、post-process 和 final-color 阶段配置。 ## 概览 `Planning` 把“这次要渲染什么”从执行链里拆了出来。 - 当前它统一收口： - [CameraRenderRequest](CameraRenderRequest/CameraRenderRequest.md) @@ -28,7 +27,7 @@ - 统一 base / overlay 相机排序 - 统一 `CameraClearMode::Auto` 推导 - 解析 normalized viewport 到最终 render area -- 把声明式 post-process / final-color 策略转换成 fullscreen 阶段配置 +- 解析相机后处理描述和 final-color 策略 - 给执行层提供显式 request 契约 ## 相关文档 diff --git a/docs/api/XCEngine/Rendering/RenderMaterialUtility/BuildLegacyBuiltinForwardPassResourceBindings.md b/docs/api/XCEngine/Rendering/RenderMaterialUtility/BuildLegacyBuiltinForwardPassResourceBindings.md deleted file mode 100644 index 6a6726e4..00000000 --- a/docs/api/XCEngine/Rendering/RenderMaterialUtility/BuildLegacyBuiltinForwardPassResourceBindings.md +++ /dev/null @@ -1,35 +0,0 @@ -# BuildLegacyBuiltinForwardPassResourceBindings - -**命名空间**: `XCEngine::Rendering` - -**类型**: `removed helper` - -**描述**: 历史上的 builtin forward fallback 绑定列表 helper。当前 public API 已移除该函数，builtin forward 路径改为要求 resolved shader pass 提供显式 `resources` 声明。 - -## 当前状态 - -- 当前 public headers 中已经不存在这个函数声明。 -- [BuiltinForwardPipeline](../Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md) 现在在 `resources.Empty()` 时会直接报错，而不是自动生成 fallback binding plan。 -- 对应的 builtin 资源契约应通过 [BuiltinPassMetadataUtils](../Builtin/BuiltinPassMetadataUtils/BuiltinPassMetadataUtils.md) 与 [BuiltinPassLayoutUtils](../Builtin/BuiltinPassLayoutUtils/BuiltinPassLayoutUtils.md) 解析显式声明。 - -## 迁移建议 - -如果你在写新的 builtin forward shader pass，应显式声明当前消费的 `resources`，至少覆盖： - -- `PerObject` -- `Material` -- `Lighting` - -按需再补： - -- `ShadowReceiver` -- `BaseColorTexture` -- `LinearClampSampler` -- `ShadowMapTexture` -- `ShadowMapSampler` - -## 相关文档 - -- [BuiltinForwardPipeline](../Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md) -- [BuiltinPassLayoutUtils](../Builtin/BuiltinPassLayoutUtils/BuiltinPassLayoutUtils.md) -- [RenderMaterialUtility](RenderMaterialUtility.md) diff --git a/docs/api/XCEngine/Rendering/RenderMaterialUtility/BuildLegacyBuiltinObjectIdPassResourceBindings.md b/docs/api/XCEngine/Rendering/RenderMaterialUtility/BuildLegacyBuiltinObjectIdPassResourceBindings.md deleted file mode 100644 index 75e5e4ca..00000000 --- a/docs/api/XCEngine/Rendering/RenderMaterialUtility/BuildLegacyBuiltinObjectIdPassResourceBindings.md +++ /dev/null @@ -1,31 +0,0 @@ -# BuildLegacyBuiltinObjectIdPassResourceBindings - -**命名空间**: `XCEngine::Rendering` - -**类型**: `removed helper` - -**描述**: 历史上的 builtin object-id fallback 绑定列表 helper。当前 public API 已移除该函数，builtin object-id 路径改为要求 resolved shader pass 提供显式 `resources` 声明。 - -## 当前状态 - -- 当前 public headers 中已经不存在这个函数声明。 -- [BuiltinObjectIdPass](../Passes/BuiltinObjectIdPass/BuiltinObjectIdPass.md) 现在在 `resources.Empty()` 时会直接报错，而不是自动生成 fallback binding plan。 -- 当前 builtin object-id shader 契约要求显式提供唯一的 `PerObject` constant-buffer 绑定。 - -## 迁移建议 - -如果你在写新的 builtin object-id shader pass，应显式声明： - -- `PerObject` - -并确保： - -- 没有重复的 builtin 语义 -- 没有重复的 `set/binding` -- 不混入 object-id 路径当前不消费的纹理或 sampler 语义 - -## 相关文档 - -- [BuiltinObjectIdPass](../Passes/BuiltinObjectIdPass/BuiltinObjectIdPass.md) -- [BuiltinPassLayoutUtils](../Builtin/BuiltinPassLayoutUtils/BuiltinPassLayoutUtils.md) -- [RenderMaterialUtility](RenderMaterialUtility.md) diff --git a/docs/api/XCEngine/Rendering/RenderMaterialUtility/RenderMaterialUtility.md b/docs/api/XCEngine/Rendering/RenderMaterialUtility/RenderMaterialUtility.md index 2c66fa7b..c9759f3c 100644 --- a/docs/api/XCEngine/Rendering/RenderMaterialUtility/RenderMaterialUtility.md +++ b/docs/api/XCEngine/Rendering/RenderMaterialUtility/RenderMaterialUtility.md @@ -2,55 +2,87 @@ **命名空间**: `XCEngine::Rendering` -**类型**: `migration index` +**类型**: `compatibility topic` -**描述**: `RenderMaterialUtility.h` 的历史聚合索引页。当前公共 API 已拆分到 `Builtin` 与 `Materials` 两组头文件中，这里负责说明迁移关系。 +**描述**: 旧的 `RenderMaterialUtility.h` 已经拆分；当前材质解析、builtin pass 契约和 render-state 映射分别落在 `Builtin/*` 与 `Materials/*` 目录下。 -## 概览 +## 拆分结果 -旧的 `RenderMaterialUtility.h` 曾经把 builtin pass 契约、材质解析和 render-state 映射都堆在同一份头文件里。 +当前源码中不再存在单一的 `RenderMaterialUtility.h`。原来的职责已经拆到这些头文件： -当前实现已经拆分为两层： +- `XCEngine/Rendering/Builtin/BuiltinPassTypes.h` +- `XCEngine/Rendering/Builtin/BuiltinPassMetadataUtils.h` +- `XCEngine/Rendering/Builtin/BuiltinPassLayoutUtils.h` +- `XCEngine/Rendering/Builtin/BuiltinPassContract.h` +- `XCEngine/Rendering/Materials/RenderMaterialResolve.h` +- `XCEngine/Rendering/Materials/RenderMaterialStateUtils.h` -- `Builtin/` - 负责 builtin pass 枚举、metadata 匹配和资源布局契约。 -- `Materials/` - 负责材质解析、skybox / base-color / alpha-cutoff helper，以及 render-state 到 RHI 的映射。 +因此这页只保留为兼容入口，用来解释“原先归在 RenderMaterialUtility 名下的文档现在分别去哪了”。 -## 当前迁移关系 +## 当前分层 -| 历史职责 | 当前位置 | -|------|------| -| builtin pass 枚举与资源语义 | [BuiltinPassTypes](../Builtin/BuiltinPassTypes/BuiltinPassTypes.md) | -| pass 名称 / `LightMode` 匹配与资源 semantic 解析 | [BuiltinPassMetadataUtils](../Builtin/BuiltinPassMetadataUtils/BuiltinPassMetadataUtils.md) | -| binding plan 与 set-layout 构建 | [BuiltinPassLayoutUtils](../Builtin/BuiltinPassLayoutUtils/BuiltinPassLayoutUtils.md) | -| 材质、skybox、base-color、alpha-cutoff、render queue 解析 | [RenderMaterialResolve](../Materials/RenderMaterialResolve/RenderMaterialResolve.md) | -| `MaterialRenderState` 到 RHI 的映射 | [RenderMaterialStateUtils](../Materials/RenderMaterialStateUtils/RenderMaterialStateUtils.md) | +### Builtin pass 契约 -## 已移除的旧 helper - -下列 helper 不再属于当前 public API： - -- [BuildLegacyBuiltinForwardPassResourceBindings](BuildLegacyBuiltinForwardPassResourceBindings.md) -- [BuildLegacyBuiltinObjectIdPassResourceBindings](BuildLegacyBuiltinObjectIdPassResourceBindings.md) - -当前 builtin forward 与 builtin object-id 路径都要求 resolved shader pass 提供显式 `resources` 声明，不再从这些历史 helper 自动生成 fallback 列表。 - -## 仍可参考的成员页 - -旧目录下的很多成员页已经把 `头文件` 行改到当前实际头文件，可继续作为符号级文档使用，例如： +这些页面描述 builtin pass 名称、资源语义和 binding-plan 构建规则： - [BuiltinMaterialPass](BuiltinMaterialPass.md) +- [PassResourceBindingLocation](PassResourceBindingLocation.md) +- [BuiltinPassResourceSemantic](BuiltinPassResourceSemantic.md) +- [BuiltinPassResourceBindingDesc](BuiltinPassResourceBindingDesc.md) - [BuiltinPassResourceBindingPlan](BuiltinPassResourceBindingPlan.md) +- [NormalizeBuiltinPassMetadataValue](NormalizeBuiltinPassMetadataValue.md) +- [IsForwardPassName](IsForwardPassName.md) +- [IsUnlitPassName](IsUnlitPassName.md) +- [IsDepthOnlyPassName](IsDepthOnlyPassName.md) +- [IsShadowCasterPassName](IsShadowCasterPassName.md) +- [IsObjectIdPassName](IsObjectIdPassName.md) +- [MatchesBuiltinPassName](MatchesBuiltinPassName.md) +- [ShaderPassHasExplicitBuiltinMetadata](ShaderPassHasExplicitBuiltinMetadata.md) +- [ShaderPassMatchesBuiltinPass](ShaderPassMatchesBuiltinPass.md) +- [ResolveBuiltinPassResourceSemantic](ResolveBuiltinPassResourceSemantic.md) +- [IsBuiltinPassResourceTypeCompatible](IsBuiltinPassResourceTypeCompatible.md) - [TryBuildBuiltinPassResourceBindingPlan](TryBuildBuiltinPassResourceBindingPlan.md) -- [BuildBlendState](BuildBlendState.md) -- [ResolveMaterial](ResolveMaterial.md) + +### 材质解析 + +这些页面描述材质选择、builtin fallback 常量以及 schema-driven 常量布局： + +- [BuiltinForwardMaterialData](BuiltinForwardMaterialData.md) +- [FindShaderPropertyBySemantic](FindShaderPropertyBySemantic.md) +- [MaterialConstantLayoutView](MaterialConstantLayoutView.md) +- [MaterialConstantPayloadView](MaterialConstantPayloadView.md) +- [ResolveBuiltinBaseColorFactor](ResolveBuiltinBaseColorFactor.md) +- [ResolveBuiltinBaseColorTexture](ResolveBuiltinBaseColorTexture.md) +- [BuildBuiltinForwardMaterialData](BuildBuiltinForwardMaterialData.md) - [ResolveSchemaMaterialConstantPayload](ResolveSchemaMaterialConstantPayload.md) +- [ResolveMaterial](ResolveMaterial.md) +- [ResolveMaterialRenderQueue](ResolveMaterialRenderQueue.md) +- [IsTransparentRenderQueue](IsTransparentRenderQueue.md) +- [MatchesBuiltinPass](MatchesBuiltinPass.md) + +### Render-state 映射 + +这些页面描述 `MaterialRenderState` 到 RHI 状态的转换： + +- [ToRHICullMode](ToRHICullMode.md) +- [ToRHIComparisonFunc](ToRHIComparisonFunc.md) +- [ToRHIBlendFactor](ToRHIBlendFactor.md) +- [ToRHIBlendOp](ToRHIBlendOp.md) +- [BuildRasterizerState](BuildRasterizerState.md) +- [BuildBlendState](BuildBlendState.md) +- [BuildDepthStencilState](BuildDepthStencilState.md) +- [ApplyMaterialRenderState](ApplyMaterialRenderState.md) +- [MaterialRenderStateHash](MaterialRenderStateHash.md) + +## 当前边界 + +- 旧的 legacy binding builder 接口已经移除，当前文档不再保留对应页面。 +- `RenderMaterialUtility` 现在更适合被理解成一个主题集合，而不是单个公开头文件。 +- 需要从真实源码入口追踪时，优先看 [Builtin](../Builtin/Builtin.md) 和 [Materials](../Materials/Materials.md)。 ## 相关文档 +- [Rendering](../Rendering.md) - [Builtin](../Builtin/Builtin.md) - [Materials](../Materials/Materials.md) -- [RenderMaterialResolve](../Materials/RenderMaterialResolve/RenderMaterialResolve.md) -- [RenderMaterialStateUtils](../Materials/RenderMaterialStateUtils/RenderMaterialStateUtils.md) - [BuiltinForwardPipeline](../Pipelines/BuiltinForwardPipeline/BuiltinForwardPipeline.md) diff --git a/docs/api/XCEngine/Rendering/RenderMaterialUtility/TryBuildBuiltinPassResourceBindingPlan.md b/docs/api/XCEngine/Rendering/RenderMaterialUtility/TryBuildBuiltinPassResourceBindingPlan.md index 82f85d0f..749f1aba 100644 --- a/docs/api/XCEngine/Rendering/RenderMaterialUtility/TryBuildBuiltinPassResourceBindingPlan.md +++ b/docs/api/XCEngine/Rendering/RenderMaterialUtility/TryBuildBuiltinPassResourceBindingPlan.md @@ -17,34 +17,35 @@ bool TryBuildBuiltinPassResourceBindingPlan( ## 作用 -把 shader 资源绑定列表解析成 builtin pipeline 可直接消费的统一 binding plan。 +把 shader 显式声明的资源绑定列表解析成 builtin pipeline 可直接消费的统一 binding plan。 ## 当前实现行为 1. 先把 `outPlan` 重置为空。 2. 如果 `bindings.Empty()`，直接返回 `true`，保留空 plan。 3. 逐条绑定执行： - - 用 [ResolveBuiltinPassResourceSemantic](ResolveBuiltinPassResourceSemantic.md) 解析 builtin 语义 - - 用 [IsBuiltinPassResourceTypeCompatible](IsBuiltinPassResourceTypeCompatible.md) 校验语义 / 类型组合 + - 通过 [ResolveBuiltinPassResourceSemantic](ResolveBuiltinPassResourceSemantic.md) 解析 builtin 语义 + - 通过 [IsBuiltinPassResourceTypeCompatible](IsBuiltinPassResourceTypeCompatible.md) 校验语义与资源类型 - 拒绝同一 builtin 语义重复出现 - - 拒绝同一个 `set/binding` 对重复出现 - - 记录 `bindings`、`usesConstantBuffers`、`usesTextures`、`usesSamplers` - - 更新 `perObject` / `material` / `baseColorTexture` / `linearClampSampler` + - 拒绝同一 `set/binding` 对重复出现 + - 回填 `bindings`、`usesConstantBuffers`、`usesTextures`、`usesSamplers` + - 更新 `perObject`、`material`、`lighting`、`shadowReceiver`、纹理与采样器槽位 4. 最终计算： - `firstDescriptorSet = 最小 set` - `descriptorSetCount = 最大 set - 最小 set + 1` ## 失败条件 -当前会返回 `false` 并在 `outError` 可用时写入错误字符串： +当前会返回 `false`，并在 `outError` 可用时写入错误字符串： - 解析出 `Unknown` 语义 -- 语义和 shader 资源类型不兼容 +- 语义与 shader 资源类型不兼容 - 同一 builtin 语义出现多次 -- 同一个 `set/binding` 对出现多次 +- 同一 `set/binding` 对出现多次 ## 当前边界 +- 它只解析调用方传入的显式 `bindings` 列表，不再负责生成 legacy fallback 绑定描述。 - 这里还不会检查“是否缺少 `PerObject`”或“同一 set 是否混用 sampler / 非 sampler”；这些更靠后的布局规则属于 `BuiltinForwardPipeline` / `BuiltinObjectIdPass` 的后续阶段。 ## 测试覆盖 @@ -52,8 +53,8 @@ bool TryBuildBuiltinPassResourceBindingPlan( `tests/Rendering/unit/test_builtin_forward_pipeline.cpp` 当前验证了： - 显式 `ForwardLit` / `Unlit` shader 资源声明能正确落成 plan -- 非法 builtin 语义和非法语义 / 资源类型组合会被拒绝 -- 生成的 plan 会正确计算 `firstDescriptorSet` 与 `descriptorSetCount` +- 显式 object-id / depth-style 资源声明也能正确落成 plan +- 语义重复、`set/binding` 重复和语义/类型不兼容时会返回失败 ## 相关文档 diff --git a/docs/api/XCEngine/Resources/AudioClip/AudioClip/AudioClip.md b/docs/api/XCEngine/Resources/AudioClip/AudioClip/AudioClip.md index 75d8bdb5..1d5a143f 100644 --- a/docs/api/XCEngine/Resources/AudioClip/AudioClip/AudioClip.md +++ b/docs/api/XCEngine/Resources/AudioClip/AudioClip/AudioClip.md @@ -6,52 +6,57 @@ **头文件**: `XCEngine/Resources/AudioClip/AudioClip.h` -**描述**: 定义 `XCEngine/Resources/AudioClip` 子目录中的 `AudioClip` public API。 +**描述**: 音频资源类型，保存原始音频字节流、采样参数、播放语义以及可选底层音频缓冲句柄。 ## 概述 -`AudioClip.h` 是 `XCEngine/Resources/AudioClip` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。 +`AudioClip` 表达的是一份已经进入资源系统的音频资产。头文件里当前把音频资源拆成两部分： + +- `AudioFormat` / `AudioType` + - 描述封装格式和用途分类 +- `AudioClip` + - 保存原始音频数据、采样率、声道数、位深、时长、3D / loop 标记和可选 `IRHIAudioBuffer*` ## 声明概览 | 声明 | 类型 | 说明 | |------|------|------| -| `AudioFormat` | `enum class` | 头文件中的公开声明。 | -| `AudioType` | `enum class` | 头文件中的公开声明。 | -| `AudioClip` | `class` | 继承自 `IResource` 的公开声明。 | +| `AudioFormat` | `enum class` | 音频文件或数据格式。 | +| `AudioType` | `enum class` | 音频资源用途分类。 | +| `AudioClip` | `class` | 音频资源对象。 | ## 公共方法 | 方法 | 描述 | |------|------| -| [AudioClip()](Constructor.md) | 构造对象。 | -| [~AudioClip()](Destructor.md) | 销毁对象并释放相关资源。 | -| [GetType](GetType.md) | 获取相关状态或对象。 | -| [GetName](GetName.md) | 获取相关状态或对象。 | -| [GetPath](GetPath.md) | 获取相关状态或对象。 | -| [GetGUID](GetGUID.md) | 获取相关状态或对象。 | -| [IsValid](IsValid.md) | 查询当前状态。 | -| [GetMemorySize](GetMemorySize.md) | 获取相关状态或对象。 | -| [Release](Release.md) | 释放引用或底层资源。 | -| [SetAudioData](SetAudioData.md) | 设置相关状态或配置。 | -| [GetAudioData](GetAudioData.md) | 获取相关状态或对象。 | -| [SetSampleRate](SetSampleRate.md) | 设置相关状态或配置。 | -| [GetSampleRate](GetSampleRate.md) | 获取相关状态或对象。 | -| [SetChannels](SetChannels.md) | 设置相关状态或配置。 | -| [GetChannels](GetChannels.md) | 获取相关状态或对象。 | -| [SetBitsPerSample](SetBitsPerSample.md) | 设置相关状态或配置。 | -| [GetBitsPerSample](GetBitsPerSample.md) | 获取相关状态或对象。 | -| [SetDuration](SetDuration.md) | 设置相关状态或配置。 | -| [GetDuration](GetDuration.md) | 获取相关状态或对象。 | -| [SetAudioFormat](SetAudioFormat.md) | 设置相关状态或配置。 | -| [GetAudioFormat](GetAudioFormat.md) | 获取相关状态或对象。 | -| [SetAudioType](SetAudioType.md) | 设置相关状态或配置。 | -| [GetAudioType](GetAudioType.md) | 获取相关状态或对象。 | -| [SetIs3D](SetIs3D.md) | 设置相关状态或配置。 | -| [Is3D](Is3D.md) | 查询当前状态。 | -| [SetLoop](SetLoop.md) | 设置相关状态或配置。 | -| [IsLoop](IsLoop.md) | 查询当前状态。 | -| [SetRHIResource](SetRHIResource.md) | 设置相关状态或配置。 | +| [AudioClip()](Constructor.md) | 构造 `AudioClip` 实例。 | +| [~AudioClip()](Destructor.md) | 销毁 `AudioClip` 实例。 | +| [GetType](GetType.md) | 返回 `ResourceType::AudioClip`。 | +| [GetName](GetName.md) | 返回 `m_name` 当前值。 | +| [GetPath](GetPath.md) | 返回 `m_path` 当前值。 | +| [GetGUID](GetGUID.md) | 返回 `m_guid` 当前值。 | +| [IsValid](IsValid.md) | 返回 `m_isValid` 当前值。 | +| [GetMemorySize](GetMemorySize.md) | 返回 `m_memorySize` 当前值。 | +| [Release](Release.md) | 执行 `Clear` 协同流程。 | +| [SetAudioData](SetAudioData.md) | 执行该公开方法对应的当前实现。 | +| [GetAudioData](GetAudioData.md) | 返回 `m_audioData` 当前值。 | +| [SetSampleRate](SetSampleRate.md) | 写入 `m_sampleRate`。 | +| [GetSampleRate](GetSampleRate.md) | 返回 `m_sampleRate` 当前值。 | +| [SetChannels](SetChannels.md) | 写入 `m_channels`。 | +| [GetChannels](GetChannels.md) | 返回 `m_channels` 当前值。 | +| [SetBitsPerSample](SetBitsPerSample.md) | 写入 `m_bitsPerSample`。 | +| [GetBitsPerSample](GetBitsPerSample.md) | 返回 `m_bitsPerSample` 当前值。 | +| [SetDuration](SetDuration.md) | 写入 `m_duration`。 | +| [GetDuration](GetDuration.md) | 返回 `m_duration` 当前值。 | +| [SetAudioFormat](SetAudioFormat.md) | 写入 `m_format`。 | +| [GetAudioFormat](GetAudioFormat.md) | 返回 `m_format` 当前值。 | +| [SetAudioType](SetAudioType.md) | 写入 `m_audioType`。 | +| [GetAudioType](GetAudioType.md) | 返回 `m_audioType` 当前值。 | +| [SetIs3D](SetIs3D.md) | 写入 `m_is3D`。 | +| [Is3D](Is3D.md) | 返回 `m_is3D` 当前值。 | +| [SetLoop](SetLoop.md) | 写入 `m_loop`。 | +| [IsLoop](IsLoop.md) | 返回 `m_loop` 当前值。 | +| [SetRHIResource](SetRHIResource.md) | 写入 `m_rhiResource`。 | ## 相关文档 diff --git a/docs/api/XCEngine/Resources/AudioClip/AudioClip/Constructor.md b/docs/api/XCEngine/Resources/AudioClip/AudioClip/Constructor.md index c8038b15..5fd1f81e 100644 --- a/docs/api/XCEngine/Resources/AudioClip/AudioClip/Constructor.md +++ b/docs/api/XCEngine/Resources/AudioClip/AudioClip/Constructor.md @@ -1,28 +1,25 @@ # AudioClip::AudioClip() -构造对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/AudioClip/AudioClip.h` + +## 签名 ```cpp AudioClip(); ``` -该方法声明于 `XCEngine/Resources/AudioClip/AudioClip.h`，当前页面用于固定 `AudioClip` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +构造 `AudioClip` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::AudioClip object; -} -``` +- 当前为默认构造实现。 ## 相关文档 -- [返回类总览](AudioClip.md) -- [返回模块目录](../AudioClip.md) +- [AudioClip](AudioClip.md) diff --git a/docs/api/XCEngine/Resources/AudioClip/AudioClip/Destructor.md b/docs/api/XCEngine/Resources/AudioClip/AudioClip/Destructor.md index 250c37d3..79475ccb 100644 --- a/docs/api/XCEngine/Resources/AudioClip/AudioClip/Destructor.md +++ b/docs/api/XCEngine/Resources/AudioClip/AudioClip/Destructor.md @@ -1,29 +1,25 @@ # AudioClip::~AudioClip() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/AudioClip/AudioClip.h` + +## 签名 ```cpp virtual ~AudioClip() override; ``` -该方法声明于 `XCEngine/Resources/AudioClip/AudioClip.h`，当前页面用于固定 `AudioClip` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +销毁 `AudioClip` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::AudioClip object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 当前为默认析构实现。 ## 相关文档 -- [返回类总览](AudioClip.md) -- [返回模块目录](../AudioClip.md) +- [AudioClip](AudioClip.md) diff --git a/docs/api/XCEngine/Resources/AudioClip/AudioClip/GetAudioData.md b/docs/api/XCEngine/Resources/AudioClip/AudioClip/GetAudioData.md index c8e8bd61..32f32e68 100644 --- a/docs/api/XCEngine/Resources/AudioClip/AudioClip/GetAudioData.md +++ b/docs/api/XCEngine/Resources/AudioClip/AudioClip/GetAudioData.md @@ -1,30 +1,26 @@ # AudioClip::GetAudioData -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/AudioClip/AudioClip.h` + +## 签名 ```cpp const Containers::Array& GetAudioData() const; ``` -该方法声明于 `XCEngine/Resources/AudioClip/AudioClip.h`，当前页面用于固定 `AudioClip` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_audioData` 当前值。 -**返回：** `const Containers::Array&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::AudioClip object; - // 根据上下文补齐参数后调用 AudioClip::GetAudioData(...)。 - (void)object; -} -``` +- 返回 `m_audioData` 当前值。 ## 相关文档 -- [返回类总览](AudioClip.md) -- [返回模块目录](../AudioClip.md) +- [AudioClip](AudioClip.md) +- [SetAudioData](SetAudioData.md) diff --git a/docs/api/XCEngine/Resources/AudioClip/AudioClip/GetAudioFormat.md b/docs/api/XCEngine/Resources/AudioClip/AudioClip/GetAudioFormat.md index 5f0878a7..3cb5b3fe 100644 --- a/docs/api/XCEngine/Resources/AudioClip/AudioClip/GetAudioFormat.md +++ b/docs/api/XCEngine/Resources/AudioClip/AudioClip/GetAudioFormat.md @@ -1,30 +1,26 @@ # AudioClip::GetAudioFormat -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/AudioClip/AudioClip.h` + +## 签名 ```cpp AudioFormat GetAudioFormat() const; ``` -该方法声明于 `XCEngine/Resources/AudioClip/AudioClip.h`，当前页面用于固定 `AudioClip` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_format` 当前值。 -**返回：** `AudioFormat` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::AudioClip object; - // 根据上下文补齐参数后调用 AudioClip::GetAudioFormat(...)。 - (void)object; -} -``` +- 返回 `m_format` 当前值。 ## 相关文档 -- [返回类总览](AudioClip.md) -- [返回模块目录](../AudioClip.md) +- [AudioClip](AudioClip.md) +- [SetAudioFormat](SetAudioFormat.md) diff --git a/docs/api/XCEngine/Resources/AudioClip/AudioClip/GetAudioType.md b/docs/api/XCEngine/Resources/AudioClip/AudioClip/GetAudioType.md index 6cb17253..32c4b3c2 100644 --- a/docs/api/XCEngine/Resources/AudioClip/AudioClip/GetAudioType.md +++ b/docs/api/XCEngine/Resources/AudioClip/AudioClip/GetAudioType.md @@ -1,30 +1,26 @@ # AudioClip::GetAudioType -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/AudioClip/AudioClip.h` + +## 签名 ```cpp AudioType GetAudioType() const; ``` -该方法声明于 `XCEngine/Resources/AudioClip/AudioClip.h`，当前页面用于固定 `AudioClip` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_audioType` 当前值。 -**返回：** `AudioType` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::AudioClip object; - // 根据上下文补齐参数后调用 AudioClip::GetAudioType(...)。 - (void)object; -} -``` +- 返回 `m_audioType` 当前值。 ## 相关文档 -- [返回类总览](AudioClip.md) -- [返回模块目录](../AudioClip.md) +- [AudioClip](AudioClip.md) +- [SetAudioType](SetAudioType.md) diff --git a/docs/api/XCEngine/Resources/AudioClip/AudioClip/GetBitsPerSample.md b/docs/api/XCEngine/Resources/AudioClip/AudioClip/GetBitsPerSample.md index 8006cba8..132337ea 100644 --- a/docs/api/XCEngine/Resources/AudioClip/AudioClip/GetBitsPerSample.md +++ b/docs/api/XCEngine/Resources/AudioClip/AudioClip/GetBitsPerSample.md @@ -1,30 +1,26 @@ # AudioClip::GetBitsPerSample -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/AudioClip/AudioClip.h` + +## 签名 ```cpp Core::uint32 GetBitsPerSample() const; ``` -该方法声明于 `XCEngine/Resources/AudioClip/AudioClip.h`，当前页面用于固定 `AudioClip` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_bitsPerSample` 当前值。 -**返回：** `Core::uint32` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::AudioClip object; - // 根据上下文补齐参数后调用 AudioClip::GetBitsPerSample(...)。 - (void)object; -} -``` +- 返回 `m_bitsPerSample` 当前值。 ## 相关文档 -- [返回类总览](AudioClip.md) -- [返回模块目录](../AudioClip.md) +- [AudioClip](AudioClip.md) +- [SetBitsPerSample](SetBitsPerSample.md) diff --git a/docs/api/XCEngine/Resources/AudioClip/AudioClip/GetChannels.md b/docs/api/XCEngine/Resources/AudioClip/AudioClip/GetChannels.md index c394bf8b..f7a6e370 100644 --- a/docs/api/XCEngine/Resources/AudioClip/AudioClip/GetChannels.md +++ b/docs/api/XCEngine/Resources/AudioClip/AudioClip/GetChannels.md @@ -1,30 +1,26 @@ # AudioClip::GetChannels -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/AudioClip/AudioClip.h` + +## 签名 ```cpp Core::uint32 GetChannels() const; ``` -该方法声明于 `XCEngine/Resources/AudioClip/AudioClip.h`，当前页面用于固定 `AudioClip` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_channels` 当前值。 -**返回：** `Core::uint32` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::AudioClip object; - // 根据上下文补齐参数后调用 AudioClip::GetChannels(...)。 - (void)object; -} -``` +- 返回 `m_channels` 当前值。 ## 相关文档 -- [返回类总览](AudioClip.md) -- [返回模块目录](../AudioClip.md) +- [AudioClip](AudioClip.md) +- [SetChannels](SetChannels.md) diff --git a/docs/api/XCEngine/Resources/AudioClip/AudioClip/GetDuration.md b/docs/api/XCEngine/Resources/AudioClip/AudioClip/GetDuration.md index 691ab5c7..548466ee 100644 --- a/docs/api/XCEngine/Resources/AudioClip/AudioClip/GetDuration.md +++ b/docs/api/XCEngine/Resources/AudioClip/AudioClip/GetDuration.md @@ -1,30 +1,26 @@ # AudioClip::GetDuration -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/AudioClip/AudioClip.h` + +## 签名 ```cpp float GetDuration() const; ``` -该方法声明于 `XCEngine/Resources/AudioClip/AudioClip.h`，当前页面用于固定 `AudioClip` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_duration` 当前值。 -**返回：** `float` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::AudioClip object; - // 根据上下文补齐参数后调用 AudioClip::GetDuration(...)。 - (void)object; -} -``` +- 返回 `m_duration` 当前值。 ## 相关文档 -- [返回类总览](AudioClip.md) -- [返回模块目录](../AudioClip.md) +- [AudioClip](AudioClip.md) +- [SetDuration](SetDuration.md) diff --git a/docs/api/XCEngine/Resources/AudioClip/AudioClip/GetGUID.md b/docs/api/XCEngine/Resources/AudioClip/AudioClip/GetGUID.md index 27e28956..6d3ef0b4 100644 --- a/docs/api/XCEngine/Resources/AudioClip/AudioClip/GetGUID.md +++ b/docs/api/XCEngine/Resources/AudioClip/AudioClip/GetGUID.md @@ -1,30 +1,25 @@ # AudioClip::GetGUID -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/AudioClip/AudioClip.h` + +## 签名 ```cpp ResourceGUID GetGUID() const override; ``` -该方法声明于 `XCEngine/Resources/AudioClip/AudioClip.h`，当前页面用于固定 `AudioClip` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_guid` 当前值。 -**返回：** `ResourceGUID` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::AudioClip object; - // 根据上下文补齐参数后调用 AudioClip::GetGUID(...)。 - (void)object; -} -``` +- 返回 `m_guid` 当前值。 ## 相关文档 -- [返回类总览](AudioClip.md) -- [返回模块目录](../AudioClip.md) +- [AudioClip](AudioClip.md) diff --git a/docs/api/XCEngine/Resources/AudioClip/AudioClip/GetMemorySize.md b/docs/api/XCEngine/Resources/AudioClip/AudioClip/GetMemorySize.md index 44f7525d..0375525c 100644 --- a/docs/api/XCEngine/Resources/AudioClip/AudioClip/GetMemorySize.md +++ b/docs/api/XCEngine/Resources/AudioClip/AudioClip/GetMemorySize.md @@ -1,30 +1,25 @@ # AudioClip::GetMemorySize -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/AudioClip/AudioClip.h` + +## 签名 ```cpp size_t GetMemorySize() const override; ``` -该方法声明于 `XCEngine/Resources/AudioClip/AudioClip.h`，当前页面用于固定 `AudioClip` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_memorySize` 当前值。 -**返回：** `size_t` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::AudioClip object; - // 根据上下文补齐参数后调用 AudioClip::GetMemorySize(...)。 - (void)object; -} -``` +- 返回 `m_memorySize` 当前值。 ## 相关文档 -- [返回类总览](AudioClip.md) -- [返回模块目录](../AudioClip.md) +- [AudioClip](AudioClip.md) diff --git a/docs/api/XCEngine/Resources/AudioClip/AudioClip/GetName.md b/docs/api/XCEngine/Resources/AudioClip/AudioClip/GetName.md index cafc0eb9..bc6424c2 100644 --- a/docs/api/XCEngine/Resources/AudioClip/AudioClip/GetName.md +++ b/docs/api/XCEngine/Resources/AudioClip/AudioClip/GetName.md @@ -1,30 +1,25 @@ # AudioClip::GetName -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/AudioClip/AudioClip.h` + +## 签名 ```cpp const Containers::String& GetName() const override; ``` -该方法声明于 `XCEngine/Resources/AudioClip/AudioClip.h`，当前页面用于固定 `AudioClip` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_name` 当前值。 -**返回：** `const Containers::String&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::AudioClip object; - // 根据上下文补齐参数后调用 AudioClip::GetName(...)。 - (void)object; -} -``` +- 返回 `m_name` 当前值。 ## 相关文档 -- [返回类总览](AudioClip.md) -- [返回模块目录](../AudioClip.md) +- [AudioClip](AudioClip.md) diff --git a/docs/api/XCEngine/Resources/AudioClip/AudioClip/GetPath.md b/docs/api/XCEngine/Resources/AudioClip/AudioClip/GetPath.md index 505afda0..3391c800 100644 --- a/docs/api/XCEngine/Resources/AudioClip/AudioClip/GetPath.md +++ b/docs/api/XCEngine/Resources/AudioClip/AudioClip/GetPath.md @@ -1,30 +1,25 @@ # AudioClip::GetPath -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/AudioClip/AudioClip.h` + +## 签名 ```cpp const Containers::String& GetPath() const override; ``` -该方法声明于 `XCEngine/Resources/AudioClip/AudioClip.h`，当前页面用于固定 `AudioClip` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_path` 当前值。 -**返回：** `const Containers::String&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::AudioClip object; - // 根据上下文补齐参数后调用 AudioClip::GetPath(...)。 - (void)object; -} -``` +- 返回 `m_path` 当前值。 ## 相关文档 -- [返回类总览](AudioClip.md) -- [返回模块目录](../AudioClip.md) +- [AudioClip](AudioClip.md) diff --git a/docs/api/XCEngine/Resources/AudioClip/AudioClip/GetSampleRate.md b/docs/api/XCEngine/Resources/AudioClip/AudioClip/GetSampleRate.md index 7144d246..a3fe23e4 100644 --- a/docs/api/XCEngine/Resources/AudioClip/AudioClip/GetSampleRate.md +++ b/docs/api/XCEngine/Resources/AudioClip/AudioClip/GetSampleRate.md @@ -1,30 +1,26 @@ # AudioClip::GetSampleRate -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/AudioClip/AudioClip.h` + +## 签名 ```cpp Core::uint32 GetSampleRate() const; ``` -该方法声明于 `XCEngine/Resources/AudioClip/AudioClip.h`，当前页面用于固定 `AudioClip` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_sampleRate` 当前值。 -**返回：** `Core::uint32` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::AudioClip object; - // 根据上下文补齐参数后调用 AudioClip::GetSampleRate(...)。 - (void)object; -} -``` +- 返回 `m_sampleRate` 当前值。 ## 相关文档 -- [返回类总览](AudioClip.md) -- [返回模块目录](../AudioClip.md) +- [AudioClip](AudioClip.md) +- [SetSampleRate](SetSampleRate.md) diff --git a/docs/api/XCEngine/Resources/AudioClip/AudioClip/GetType.md b/docs/api/XCEngine/Resources/AudioClip/AudioClip/GetType.md index 2cbe2842..643119ba 100644 --- a/docs/api/XCEngine/Resources/AudioClip/AudioClip/GetType.md +++ b/docs/api/XCEngine/Resources/AudioClip/AudioClip/GetType.md @@ -1,30 +1,25 @@ # AudioClip::GetType -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/AudioClip/AudioClip.h` + +## 签名 ```cpp ResourceType GetType() const override; ``` -该方法声明于 `XCEngine/Resources/AudioClip/AudioClip.h`，当前页面用于固定 `AudioClip` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `ResourceType::AudioClip`。 -**返回：** `ResourceType` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::AudioClip object; - // 根据上下文补齐参数后调用 AudioClip::GetType(...)。 - (void)object; -} -``` +- 返回 `ResourceType::AudioClip`。 ## 相关文档 -- [返回类总览](AudioClip.md) -- [返回模块目录](../AudioClip.md) +- [AudioClip](AudioClip.md) diff --git a/docs/api/XCEngine/Resources/AudioClip/AudioClip/Is3D.md b/docs/api/XCEngine/Resources/AudioClip/AudioClip/Is3D.md index f1720242..2a9fef1f 100644 --- a/docs/api/XCEngine/Resources/AudioClip/AudioClip/Is3D.md +++ b/docs/api/XCEngine/Resources/AudioClip/AudioClip/Is3D.md @@ -1,30 +1,25 @@ # AudioClip::Is3D -查询当前状态。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/AudioClip/AudioClip.h` + +## 签名 ```cpp bool Is3D() const; ``` -该方法声明于 `XCEngine/Resources/AudioClip/AudioClip.h`，当前页面用于固定 `AudioClip` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_is3D` 当前值。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::AudioClip object; - // 根据上下文补齐参数后调用 AudioClip::Is3D(...)。 - (void)object; -} -``` +- 返回 `m_is3D` 当前值。 ## 相关文档 -- [返回类总览](AudioClip.md) -- [返回模块目录](../AudioClip.md) +- [AudioClip](AudioClip.md) diff --git a/docs/api/XCEngine/Resources/AudioClip/AudioClip/IsLoop.md b/docs/api/XCEngine/Resources/AudioClip/AudioClip/IsLoop.md index 1ca3168b..a68a41d7 100644 --- a/docs/api/XCEngine/Resources/AudioClip/AudioClip/IsLoop.md +++ b/docs/api/XCEngine/Resources/AudioClip/AudioClip/IsLoop.md @@ -1,30 +1,25 @@ # AudioClip::IsLoop -查询当前状态。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/AudioClip/AudioClip.h` + +## 签名 ```cpp bool IsLoop() const; ``` -该方法声明于 `XCEngine/Resources/AudioClip/AudioClip.h`，当前页面用于固定 `AudioClip` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_loop` 当前值。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::AudioClip object; - // 根据上下文补齐参数后调用 AudioClip::IsLoop(...)。 - (void)object; -} -``` +- 返回 `m_loop` 当前值。 ## 相关文档 -- [返回类总览](AudioClip.md) -- [返回模块目录](../AudioClip.md) +- [AudioClip](AudioClip.md) diff --git a/docs/api/XCEngine/Resources/AudioClip/AudioClip/IsValid.md b/docs/api/XCEngine/Resources/AudioClip/AudioClip/IsValid.md index 252f827b..8418fc3a 100644 --- a/docs/api/XCEngine/Resources/AudioClip/AudioClip/IsValid.md +++ b/docs/api/XCEngine/Resources/AudioClip/AudioClip/IsValid.md @@ -1,30 +1,25 @@ # AudioClip::IsValid -查询当前状态。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/AudioClip/AudioClip.h` + +## 签名 ```cpp bool IsValid() const override; ``` -该方法声明于 `XCEngine/Resources/AudioClip/AudioClip.h`，当前页面用于固定 `AudioClip` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_isValid` 当前值。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::AudioClip object; - // 根据上下文补齐参数后调用 AudioClip::IsValid(...)。 - (void)object; -} -``` +- 返回 `m_isValid` 当前值。 ## 相关文档 -- [返回类总览](AudioClip.md) -- [返回模块目录](../AudioClip.md) +- [AudioClip](AudioClip.md) diff --git a/docs/api/XCEngine/Resources/AudioClip/AudioClip/Release.md b/docs/api/XCEngine/Resources/AudioClip/AudioClip/Release.md index 92356c99..a937ebb8 100644 --- a/docs/api/XCEngine/Resources/AudioClip/AudioClip/Release.md +++ b/docs/api/XCEngine/Resources/AudioClip/AudioClip/Release.md @@ -1,30 +1,27 @@ # AudioClip::Release -释放引用或底层资源。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/AudioClip/AudioClip.h` + +## 签名 ```cpp void Release() override; ``` -该方法声明于 `XCEngine/Resources/AudioClip/AudioClip.h`，当前页面用于固定 `AudioClip` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `Clear` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::AudioClip object; - // 根据上下文补齐参数后调用 AudioClip::Release(...)。 - (void)object; -} -``` +- 会更新 `m_rhiResource`、`m_isValid`、`m_audioData`。 +- 当前实现会调用 `Clear`。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](AudioClip.md) -- [返回模块目录](../AudioClip.md) +- [AudioClip](AudioClip.md) diff --git a/docs/api/XCEngine/Resources/AudioClip/AudioClip/SetAudioData.md b/docs/api/XCEngine/Resources/AudioClip/AudioClip/SetAudioData.md index 8f541955..8d2a0571 100644 --- a/docs/api/XCEngine/Resources/AudioClip/AudioClip/SetAudioData.md +++ b/docs/api/XCEngine/Resources/AudioClip/AudioClip/SetAudioData.md @@ -1,31 +1,26 @@ # AudioClip::SetAudioData -设置相关状态或配置。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/AudioClip/AudioClip.h` + +## 签名 ```cpp void SetAudioData(const Containers::Array& data); ``` -该方法声明于 `XCEngine/Resources/AudioClip/AudioClip.h`，当前页面用于固定 `AudioClip` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `data` - 参数语义详见头文件声明。 +执行该公开方法对应的当前实现。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::AudioClip object; - // 根据上下文补齐参数后调用 AudioClip::SetAudioData(...)。 - (void)object; -} -``` +- 会更新 `m_audioData`、`m_duration`。 ## 相关文档 -- [返回类总览](AudioClip.md) -- [返回模块目录](../AudioClip.md) +- [AudioClip](AudioClip.md) +- [GetAudioData](GetAudioData.md) diff --git a/docs/api/XCEngine/Resources/AudioClip/AudioClip/SetAudioFormat.md b/docs/api/XCEngine/Resources/AudioClip/AudioClip/SetAudioFormat.md index 26b7965c..94421885 100644 --- a/docs/api/XCEngine/Resources/AudioClip/AudioClip/SetAudioFormat.md +++ b/docs/api/XCEngine/Resources/AudioClip/AudioClip/SetAudioFormat.md @@ -1,31 +1,26 @@ # AudioClip::SetAudioFormat -设置相关状态或配置。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/AudioClip/AudioClip.h` + +## 签名 ```cpp void SetAudioFormat(AudioFormat format); ``` -该方法声明于 `XCEngine/Resources/AudioClip/AudioClip.h`，当前页面用于固定 `AudioClip` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `format` - 参数语义详见头文件声明。 +更新 `m_format`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::AudioClip object; - // 根据上下文补齐参数后调用 AudioClip::SetAudioFormat(...)。 - (void)object; -} -``` +- 会更新 `m_format`。 ## 相关文档 -- [返回类总览](AudioClip.md) -- [返回模块目录](../AudioClip.md) +- [AudioClip](AudioClip.md) +- [GetAudioFormat](GetAudioFormat.md) diff --git a/docs/api/XCEngine/Resources/AudioClip/AudioClip/SetAudioType.md b/docs/api/XCEngine/Resources/AudioClip/AudioClip/SetAudioType.md index c62ddf78..543bf181 100644 --- a/docs/api/XCEngine/Resources/AudioClip/AudioClip/SetAudioType.md +++ b/docs/api/XCEngine/Resources/AudioClip/AudioClip/SetAudioType.md @@ -1,31 +1,26 @@ # AudioClip::SetAudioType -设置相关状态或配置。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/AudioClip/AudioClip.h` + +## 签名 ```cpp void SetAudioType(AudioType type); ``` -该方法声明于 `XCEngine/Resources/AudioClip/AudioClip.h`，当前页面用于固定 `AudioClip` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `type` - 参数语义详见头文件声明。 +更新 `m_audioType`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::AudioClip object; - // 根据上下文补齐参数后调用 AudioClip::SetAudioType(...)。 - (void)object; -} -``` +- 会更新 `m_audioType`。 ## 相关文档 -- [返回类总览](AudioClip.md) -- [返回模块目录](../AudioClip.md) +- [AudioClip](AudioClip.md) +- [GetAudioType](GetAudioType.md) diff --git a/docs/api/XCEngine/Resources/AudioClip/AudioClip/SetBitsPerSample.md b/docs/api/XCEngine/Resources/AudioClip/AudioClip/SetBitsPerSample.md index f6b3bad8..368e7085 100644 --- a/docs/api/XCEngine/Resources/AudioClip/AudioClip/SetBitsPerSample.md +++ b/docs/api/XCEngine/Resources/AudioClip/AudioClip/SetBitsPerSample.md @@ -1,31 +1,26 @@ # AudioClip::SetBitsPerSample -设置相关状态或配置。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/AudioClip/AudioClip.h` + +## 签名 ```cpp void SetBitsPerSample(Core::uint32 bits); ``` -该方法声明于 `XCEngine/Resources/AudioClip/AudioClip.h`，当前页面用于固定 `AudioClip` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `bits` - 参数语义详见头文件声明。 +更新 `m_bitsPerSample`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::AudioClip object; - // 根据上下文补齐参数后调用 AudioClip::SetBitsPerSample(...)。 - (void)object; -} -``` +- 会更新 `m_bitsPerSample`。 ## 相关文档 -- [返回类总览](AudioClip.md) -- [返回模块目录](../AudioClip.md) +- [AudioClip](AudioClip.md) +- [GetBitsPerSample](GetBitsPerSample.md) diff --git a/docs/api/XCEngine/Resources/AudioClip/AudioClip/SetChannels.md b/docs/api/XCEngine/Resources/AudioClip/AudioClip/SetChannels.md index 0395f467..4cd19ecc 100644 --- a/docs/api/XCEngine/Resources/AudioClip/AudioClip/SetChannels.md +++ b/docs/api/XCEngine/Resources/AudioClip/AudioClip/SetChannels.md @@ -1,31 +1,26 @@ # AudioClip::SetChannels -设置相关状态或配置。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/AudioClip/AudioClip.h` + +## 签名 ```cpp void SetChannels(Core::uint32 channels); ``` -该方法声明于 `XCEngine/Resources/AudioClip/AudioClip.h`，当前页面用于固定 `AudioClip` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `channels` - 参数语义详见头文件声明。 +更新 `m_channels`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::AudioClip object; - // 根据上下文补齐参数后调用 AudioClip::SetChannels(...)。 - (void)object; -} -``` +- 会更新 `m_channels`。 ## 相关文档 -- [返回类总览](AudioClip.md) -- [返回模块目录](../AudioClip.md) +- [AudioClip](AudioClip.md) +- [GetChannels](GetChannels.md) diff --git a/docs/api/XCEngine/Resources/AudioClip/AudioClip/SetDuration.md b/docs/api/XCEngine/Resources/AudioClip/AudioClip/SetDuration.md index d3963704..88cd193f 100644 --- a/docs/api/XCEngine/Resources/AudioClip/AudioClip/SetDuration.md +++ b/docs/api/XCEngine/Resources/AudioClip/AudioClip/SetDuration.md @@ -1,31 +1,26 @@ # AudioClip::SetDuration -设置相关状态或配置。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/AudioClip/AudioClip.h` + +## 签名 ```cpp void SetDuration(float seconds); ``` -该方法声明于 `XCEngine/Resources/AudioClip/AudioClip.h`，当前页面用于固定 `AudioClip` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `seconds` - 参数语义详见头文件声明。 +更新 `m_duration`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::AudioClip object; - // 根据上下文补齐参数后调用 AudioClip::SetDuration(...)。 - (void)object; -} -``` +- 会更新 `m_duration`。 ## 相关文档 -- [返回类总览](AudioClip.md) -- [返回模块目录](../AudioClip.md) +- [AudioClip](AudioClip.md) +- [GetDuration](GetDuration.md) diff --git a/docs/api/XCEngine/Resources/AudioClip/AudioClip/SetIs3D.md b/docs/api/XCEngine/Resources/AudioClip/AudioClip/SetIs3D.md index 3a81f5fa..7ac5bd83 100644 --- a/docs/api/XCEngine/Resources/AudioClip/AudioClip/SetIs3D.md +++ b/docs/api/XCEngine/Resources/AudioClip/AudioClip/SetIs3D.md @@ -1,31 +1,25 @@ # AudioClip::SetIs3D -设置相关状态或配置。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/AudioClip/AudioClip.h` + +## 签名 ```cpp void SetIs3D(bool is3D); ``` -该方法声明于 `XCEngine/Resources/AudioClip/AudioClip.h`，当前页面用于固定 `AudioClip` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `is3D` - 参数语义详见头文件声明。 +更新 `m_is3D`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::AudioClip object; - // 根据上下文补齐参数后调用 AudioClip::SetIs3D(...)。 - (void)object; -} -``` +- 会更新 `m_is3D`。 ## 相关文档 -- [返回类总览](AudioClip.md) -- [返回模块目录](../AudioClip.md) +- [AudioClip](AudioClip.md) diff --git a/docs/api/XCEngine/Resources/AudioClip/AudioClip/SetLoop.md b/docs/api/XCEngine/Resources/AudioClip/AudioClip/SetLoop.md index 0cad7b2d..11fcac75 100644 --- a/docs/api/XCEngine/Resources/AudioClip/AudioClip/SetLoop.md +++ b/docs/api/XCEngine/Resources/AudioClip/AudioClip/SetLoop.md @@ -1,31 +1,25 @@ # AudioClip::SetLoop -设置相关状态或配置。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/AudioClip/AudioClip.h` + +## 签名 ```cpp void SetLoop(bool loop); ``` -该方法声明于 `XCEngine/Resources/AudioClip/AudioClip.h`，当前页面用于固定 `AudioClip` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `loop` - 参数语义详见头文件声明。 +更新 `m_loop`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::AudioClip object; - // 根据上下文补齐参数后调用 AudioClip::SetLoop(...)。 - (void)object; -} -``` +- 会更新 `m_loop`。 ## 相关文档 -- [返回类总览](AudioClip.md) -- [返回模块目录](../AudioClip.md) +- [AudioClip](AudioClip.md) diff --git a/docs/api/XCEngine/Resources/AudioClip/AudioClip/SetRHIResource.md b/docs/api/XCEngine/Resources/AudioClip/AudioClip/SetRHIResource.md index c4dcd8e4..9369b748 100644 --- a/docs/api/XCEngine/Resources/AudioClip/AudioClip/SetRHIResource.md +++ b/docs/api/XCEngine/Resources/AudioClip/AudioClip/SetRHIResource.md @@ -1,31 +1,25 @@ # AudioClip::SetRHIResource -设置相关状态或配置。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/AudioClip/AudioClip.h` + +## 签名 ```cpp void SetRHIResource(class IRHIAudioBuffer* resource); ``` -该方法声明于 `XCEngine/Resources/AudioClip/AudioClip.h`，当前页面用于固定 `AudioClip` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `resource` - 参数语义详见头文件声明。 +更新 `m_rhiResource`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::AudioClip object; - // 根据上下文补齐参数后调用 AudioClip::SetRHIResource(...)。 - (void)object; -} -``` +- 会更新 `m_rhiResource`。 ## 相关文档 -- [返回类总览](AudioClip.md) -- [返回模块目录](../AudioClip.md) +- [AudioClip](AudioClip.md) diff --git a/docs/api/XCEngine/Resources/AudioClip/AudioClip/SetSampleRate.md b/docs/api/XCEngine/Resources/AudioClip/AudioClip/SetSampleRate.md index e599f3b8..e85be0cf 100644 --- a/docs/api/XCEngine/Resources/AudioClip/AudioClip/SetSampleRate.md +++ b/docs/api/XCEngine/Resources/AudioClip/AudioClip/SetSampleRate.md @@ -1,31 +1,26 @@ # AudioClip::SetSampleRate -设置相关状态或配置。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/AudioClip/AudioClip.h` + +## 签名 ```cpp void SetSampleRate(Core::uint32 rate); ``` -该方法声明于 `XCEngine/Resources/AudioClip/AudioClip.h`，当前页面用于固定 `AudioClip` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `rate` - 参数语义详见头文件声明。 +更新 `m_sampleRate`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::AudioClip object; - // 根据上下文补齐参数后调用 AudioClip::SetSampleRate(...)。 - (void)object; -} -``` +- 会更新 `m_sampleRate`。 ## 相关文档 -- [返回类总览](AudioClip.md) -- [返回模块目录](../AudioClip.md) +- [AudioClip](AudioClip.md) +- [GetSampleRate](GetSampleRate.md) diff --git a/docs/api/XCEngine/Resources/AudioClip/AudioLoader/AudioLoader.md b/docs/api/XCEngine/Resources/AudioClip/AudioLoader/AudioLoader.md index c7e041f7..fd484f4b 100644 --- a/docs/api/XCEngine/Resources/AudioClip/AudioLoader/AudioLoader.md +++ b/docs/api/XCEngine/Resources/AudioClip/AudioLoader/AudioLoader.md @@ -6,29 +6,32 @@ **头文件**: `XCEngine/Resources/AudioClip/AudioLoader.h` -**描述**: 定义 `XCEngine/Resources/AudioClip` 子目录中的 `AudioLoader` public API。 +**描述**: 音频资源 loader，负责识别音频文件格式、执行导入，并提供默认导入设置。 ## 概述 -`AudioLoader.h` 是 `XCEngine/Resources/AudioClip` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。 +`AudioLoader` 是 `AudioClip` 资源的标准加载入口。按头文件声明，它除了常规 `IResourceLoader` 能力外，还包含两块音频特有逻辑： + +- 根据路径与字节流检测 `AudioFormat` +- 把 WAV 数据解析成 `AudioClip` 当前使用的内存布局 ## 声明概览 | 声明 | 类型 | 说明 | |------|------|------| -| `AudioLoader` | `class` | 继承自 `IResourceLoader` 的公开声明。 | +| `AudioLoader` | `class` | `AudioClip` 资源的加载器。 | ## 公共方法 | 方法 | 描述 | |------|------| -| [AudioLoader()](Constructor.md) | 构造对象。 | -| [~AudioLoader()](Destructor.md) | 销毁对象并释放相关资源。 | -| [GetResourceType](GetResourceType.md) | 获取相关状态或对象。 | -| [GetSupportedExtensions](GetSupportedExtensions.md) | 获取相关状态或对象。 | -| [CanLoad](CanLoad.md) | 判断当前条件下是否可执行。 | -| [Load](Load.md) | 加载资源或数据。 | -| [GetDefaultSettings](GetDefaultSettings.md) | 获取相关状态或对象。 | +| [AudioLoader()](Constructor.md) | 构造 `AudioLoader` 实例。 | +| [~AudioLoader()](Destructor.md) | 销毁 `AudioLoader` 实例。 | +| [GetResourceType](GetResourceType.md) | 返回 `ResourceType::AudioClip`。 | +| [GetSupportedExtensions](GetSupportedExtensions.md) | 执行 `PushBack` 协同流程。 | +| [CanLoad](CanLoad.md) | 执行 `GetExtension(...)` 相关流程。 | +| [Load](Load.md) | 执行 `ReadFileData`、`Empty`、`LoadResult` 协同流程。 | +| [GetDefaultSettings](GetDefaultSettings.md) | 固定返回 `nullptr`。 | ## 相关文档 diff --git a/docs/api/XCEngine/Resources/AudioClip/AudioLoader/CanLoad.md b/docs/api/XCEngine/Resources/AudioClip/AudioLoader/CanLoad.md index da09f4a7..7c2b8830 100644 --- a/docs/api/XCEngine/Resources/AudioClip/AudioLoader/CanLoad.md +++ b/docs/api/XCEngine/Resources/AudioClip/AudioLoader/CanLoad.md @@ -1,31 +1,25 @@ # AudioLoader::CanLoad -判断当前条件下是否可执行。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/AudioClip/AudioLoader.h` + +## 签名 ```cpp bool CanLoad(const Containers::String& path) const override; ``` -该方法声明于 `XCEngine/Resources/AudioClip/AudioLoader.h`，当前页面用于固定 `AudioLoader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `path` - 参数语义详见头文件声明。 +执行 `GetExtension(...)` 相关流程。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::AudioLoader object; - // 根据上下文补齐参数后调用 AudioLoader::CanLoad(...)。 - (void)object; -} -``` +- 当前实现会调用 `GetExtension`。 ## 相关文档 -- [返回类总览](AudioLoader.md) -- [返回模块目录](../AudioClip.md) +- [AudioLoader](AudioLoader.md) diff --git a/docs/api/XCEngine/Resources/AudioClip/AudioLoader/Constructor.md b/docs/api/XCEngine/Resources/AudioClip/AudioLoader/Constructor.md index 1bf01fc4..488bb0ad 100644 --- a/docs/api/XCEngine/Resources/AudioClip/AudioLoader/Constructor.md +++ b/docs/api/XCEngine/Resources/AudioClip/AudioLoader/Constructor.md @@ -1,28 +1,25 @@ # AudioLoader::AudioLoader() -构造对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/AudioClip/AudioLoader.h` + +## 签名 ```cpp AudioLoader(); ``` -该方法声明于 `XCEngine/Resources/AudioClip/AudioLoader.h`，当前页面用于固定 `AudioLoader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +构造 `AudioLoader` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::AudioLoader object; -} -``` +- 当前为默认构造实现。 ## 相关文档 -- [返回类总览](AudioLoader.md) -- [返回模块目录](../AudioClip.md) +- [AudioLoader](AudioLoader.md) diff --git a/docs/api/XCEngine/Resources/AudioClip/AudioLoader/Destructor.md b/docs/api/XCEngine/Resources/AudioClip/AudioLoader/Destructor.md index 260a1396..95bbf2a6 100644 --- a/docs/api/XCEngine/Resources/AudioClip/AudioLoader/Destructor.md +++ b/docs/api/XCEngine/Resources/AudioClip/AudioLoader/Destructor.md @@ -1,29 +1,25 @@ # AudioLoader::~AudioLoader() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/AudioClip/AudioLoader.h` + +## 签名 ```cpp virtual ~AudioLoader() override; ``` -该方法声明于 `XCEngine/Resources/AudioClip/AudioLoader.h`，当前页面用于固定 `AudioLoader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +销毁 `AudioLoader` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::AudioLoader object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 当前为默认析构实现。 ## 相关文档 -- [返回类总览](AudioLoader.md) -- [返回模块目录](../AudioClip.md) +- [AudioLoader](AudioLoader.md) diff --git a/docs/api/XCEngine/Resources/AudioClip/AudioLoader/GetDefaultSettings.md b/docs/api/XCEngine/Resources/AudioClip/AudioLoader/GetDefaultSettings.md index f2a33354..8387df41 100644 --- a/docs/api/XCEngine/Resources/AudioClip/AudioLoader/GetDefaultSettings.md +++ b/docs/api/XCEngine/Resources/AudioClip/AudioLoader/GetDefaultSettings.md @@ -1,30 +1,25 @@ # AudioLoader::GetDefaultSettings -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/AudioClip/AudioLoader.h` + +## 签名 ```cpp ImportSettings* GetDefaultSettings() const override; ``` -该方法声明于 `XCEngine/Resources/AudioClip/AudioLoader.h`，当前页面用于固定 `AudioLoader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +固定返回 `nullptr`。 -**返回：** `ImportSettings*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::AudioLoader object; - // 根据上下文补齐参数后调用 AudioLoader::GetDefaultSettings(...)。 - (void)object; -} -``` +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](AudioLoader.md) -- [返回模块目录](../AudioClip.md) +- [AudioLoader](AudioLoader.md) diff --git a/docs/api/XCEngine/Resources/AudioClip/AudioLoader/GetResourceType.md b/docs/api/XCEngine/Resources/AudioClip/AudioLoader/GetResourceType.md index f24c2365..86b373cf 100644 --- a/docs/api/XCEngine/Resources/AudioClip/AudioLoader/GetResourceType.md +++ b/docs/api/XCEngine/Resources/AudioClip/AudioLoader/GetResourceType.md @@ -1,30 +1,25 @@ # AudioLoader::GetResourceType -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/AudioClip/AudioLoader.h` + +## 签名 ```cpp ResourceType GetResourceType() const override; ``` -该方法声明于 `XCEngine/Resources/AudioClip/AudioLoader.h`，当前页面用于固定 `AudioLoader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `ResourceType::AudioClip`。 -**返回：** `ResourceType` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::AudioLoader object; - // 根据上下文补齐参数后调用 AudioLoader::GetResourceType(...)。 - (void)object; -} -``` +- 返回 `ResourceType::AudioClip`。 ## 相关文档 -- [返回类总览](AudioLoader.md) -- [返回模块目录](../AudioClip.md) +- [AudioLoader](AudioLoader.md) diff --git a/docs/api/XCEngine/Resources/AudioClip/AudioLoader/GetSupportedExtensions.md b/docs/api/XCEngine/Resources/AudioClip/AudioLoader/GetSupportedExtensions.md index 613afe1f..578e7d75 100644 --- a/docs/api/XCEngine/Resources/AudioClip/AudioLoader/GetSupportedExtensions.md +++ b/docs/api/XCEngine/Resources/AudioClip/AudioLoader/GetSupportedExtensions.md @@ -1,30 +1,25 @@ # AudioLoader::GetSupportedExtensions -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/AudioClip/AudioLoader.h` + +## 签名 ```cpp Containers::Array GetSupportedExtensions() const override; ``` -该方法声明于 `XCEngine/Resources/AudioClip/AudioLoader.h`，当前页面用于固定 `AudioLoader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `extensions`。 -**返回：** `Containers::Array` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::AudioLoader object; - // 根据上下文补齐参数后调用 AudioLoader::GetSupportedExtensions(...)。 - (void)object; -} -``` +- 当前实现会调用 `PushBack`。 ## 相关文档 -- [返回类总览](AudioLoader.md) -- [返回模块目录](../AudioClip.md) +- [AudioLoader](AudioLoader.md) diff --git a/docs/api/XCEngine/Resources/AudioClip/AudioLoader/Load.md b/docs/api/XCEngine/Resources/AudioClip/AudioLoader/Load.md index e6f89e58..0882ae55 100644 --- a/docs/api/XCEngine/Resources/AudioClip/AudioLoader/Load.md +++ b/docs/api/XCEngine/Resources/AudioClip/AudioLoader/Load.md @@ -1,32 +1,27 @@ # AudioLoader::Load -加载资源或数据。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/AudioClip/AudioLoader.h` + +## 签名 ```cpp LoadResult Load(const Containers::String& path, const ImportSettings* settings = nullptr) override; ``` -该方法声明于 `XCEngine/Resources/AudioClip/AudioLoader.h`，当前页面用于固定 `AudioLoader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `path` - 参数语义详见头文件声明。 -- `settings` - 参数语义详见头文件声明。 +执行 `ReadFileData`、`Empty`、`LoadResult` 协同流程。 -**返回：** `LoadResult` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::AudioLoader object; - // 根据上下文补齐参数后调用 AudioLoader::Load(...)。 - (void)object; -} -``` +- 会更新 `m_path`、`m_name`、`m_guid`、`m_isValid`。 +- 当前实现会调用 `ReadFileData`、`Empty`、`LoadResult`、`AudioClip`、`Generate`。 +- 包含条件分支，并可能提前返回。 ## 相关文档 -- [返回类总览](AudioLoader.md) -- [返回模块目录](../AudioClip.md) +- [AudioLoader](AudioLoader.md) diff --git a/docs/api/XCEngine/Resources/BuiltinResources/BuiltinResources.md b/docs/api/XCEngine/Resources/BuiltinResources/BuiltinResources.md new file mode 100644 index 00000000..2a2e48f4 --- /dev/null +++ b/docs/api/XCEngine/Resources/BuiltinResources/BuiltinResources.md @@ -0,0 +1,128 @@ +# BuiltinResources + +**命名空间**: `XCEngine::Resources` + +**类型**: `utility header` + +**头文件**: `XCEngine/Resources/BuiltinResources.h` + +**描述**: 定义 `builtin://` 资源命名空间、内置 primitive 路径 helper，以及 builtin mesh / material / shader / texture 的工厂入口。 + +## 概览 + +`BuiltinResources.h` 负责把一小组“引擎自带资源”暴露成统一的虚拟路径体系。 + +这套体系的目的很直接： + +- 编辑器创建 primitive 时，不需要先落地真实资产文件 +- runtime 渲染主路径可以稳定拿到 `forward-lit` 和 `object-id` 这两份引擎内置 shader +- [ResourceManager](../../Core/Asset/ResourceManager/ResourceManager.md) 可以像加载普通资源一样懒加载这些内置对象 + +需要特别区分的一点是：Scene View 专属的 `object-id-outline` 与 `infinite-grid` shader +已经不再属于这里的 `builtin://shaders/` 命名空间。它们当前由 editor 侧通过 +[SceneViewportResourcePaths](../../Editor/Viewport/SceneViewportResourcePaths/SceneViewportResourcePaths.md) +解析 repo 内资源路径，再注入到对应 rendering pass。 + +## 当前路径命名空间 + +内置资源统一使用 `builtin://` 前缀，当前公开的子前缀包括： + +- `builtin://meshes/` +- `builtin://materials/` +- `builtin://shaders/` +- `builtin://textures/` + +对应的判定 helper 为： + +- `IsBuiltinResourcePath()` +- `IsBuiltinMeshPath()` +- `IsBuiltinMaterialPath()` +- `IsBuiltinShaderPath()` +- `IsBuiltinTexturePath()` + +## 内置 primitive + +`BuiltinPrimitiveType` 当前支持六种 primitive： + +- `Cube` +- `Sphere` +- `Capsule` +- `Cylinder` +- `Plane` +- `Quad` + +相关 helper 包括： + +- `GetBuiltinPrimitiveDisplayName()` +- `GetBuiltinPrimitiveMeshPath()` +- `TryParseBuiltinPrimitiveType()` + +## 其他固定 builtin 路径 + +当前还公开了几条固定路径 helper： + +- `GetBuiltinDefaultPrimitiveMaterialPath()` -> `builtin://materials/default-primitive` +- `GetBuiltinForwardLitShaderPath()` -> `builtin://shaders/forward-lit` +- `GetBuiltinUnlitShaderPath()` -> `builtin://shaders/unlit` +- `GetBuiltinDepthOnlyShaderPath()` -> `builtin://shaders/depth-only` +- `GetBuiltinShadowCasterShaderPath()` -> `builtin://shaders/shadow-caster` +- `GetBuiltinObjectIdShaderPath()` -> `builtin://shaders/object-id` +- `GetBuiltinDefaultPrimitiveTexturePath()` -> `builtin://textures/default-primitive-albedo` + +## 工厂函数 + +### mesh + +`CreateBuiltinMeshResource()` 会根据路径解析 primitive 类型，生成对应顶点/索引数据，再统一做一次 triangle winding 翻转，最后构建 `Mesh` 资源。 + +### material + +`CreateBuiltinMaterialResource()` 当前只支持默认 primitive 材质。该材质会进一步通过 `ResourceManager` 懒加载 builtin forward-lit shader 和默认 primitive 贴图。 + +### shader + +`CreateBuiltinShaderResource()` 当前支持五份引擎内置 shader： + +- forward-lit +- unlit +- depth-only +- shadow-caster +- object-id + +测试表明： + +- `forward-lit`、`unlit`、`depth-only`、`shadow-caster` 与 `object-id` 当前都会构建 D3D12 / OpenGL / Vulkan 三套 backend variant + +### texture + +`CreateBuiltinTextureResource()` 当前只支持默认 primitive 贴图。 + +## 真实使用位置 + +- `editor/src/Commands/EntityCommands.h` 通过 builtin primitive 路径创建默认模型对象。 +- `engine/src/Rendering/Pipelines/BuiltinForwardPipeline.cpp` 与 `engine/src/Rendering/Passes/BuiltinObjectIdPass.cpp` 依赖这里的内置 shader 路径。 +- `engine/src/Rendering/Passes/BuiltinDepthStylePassBase.cpp` 会通过这里的 helper 加载 builtin `depth-only` 与 `shadow-caster` shader。 +- `engine/src/Resources/Shader/ShaderLoader.cpp`、`TextureLoader.cpp`、`MeshLoader.cpp` 会识别并消费这些 `builtin://` 路径。 +- `tests/Resources/Shader/test_shader_loader.cpp` 覆盖了 `forward-lit`、`unlit`、`depth-only`、`shadow-caster` 与 `object-id` 这几条 builtin shader 主路径及其 backend variant 结果。 +- `editor/src/Viewport/Passes/SceneViewportGridPass.cpp` 与 `SceneViewportSelectionOutlinePass.cpp` + 不再通过这里取得 Scene View shader；它们改为使用 + [SceneViewportResourcePaths](../../Editor/Viewport/SceneViewportResourcePaths/SceneViewportResourcePaths.md)。 + +## 当前实现边界 + +- 内置 mesh 当前只覆盖六种基础 primitive。 +- 内置 material 和 texture 目前都只有一个默认版本。 +- 内置 shader 当前包括 `forward-lit`、`unlit`、`depth-only`、`shadow-caster` 与 `object-id`；Scene View 专属 grid / outline shader 不再属于这里。 +- 这套资源完全由代码生成，不走项目 `AssetDatabase` 和 artifact 缓存。 +- 目前 builtin shader 的跨后端覆盖只针对这五份 runtime shader。 + +## 相关文档 + +- [当前模块](../Resources.md) +- [ResourceManager](../../Core/Asset/ResourceManager/ResourceManager.md) +- [MeshLoader](../Mesh/MeshLoader/MeshLoader.md) +- [ShaderLoader](../Shader/ShaderLoader/ShaderLoader.md) +- [BuiltinObjectIdPass](../../Rendering/Passes/BuiltinObjectIdPass/BuiltinObjectIdPass.md) +- [BuiltinDepthOnlyPass](../../Rendering/Passes/BuiltinDepthOnlyPass/BuiltinDepthOnlyPass.md) +- [BuiltinShadowCasterPass](../../Rendering/Passes/BuiltinShadowCasterPass/BuiltinShadowCasterPass.md) +- [SceneViewportResourcePaths](../../Editor/Viewport/SceneViewportResourcePaths/SceneViewportResourcePaths.md) diff --git a/docs/api/XCEngine/Resources/Material/Material.md b/docs/api/XCEngine/Resources/Material/Material.md index 4aa56cc9..cc782719 100644 --- a/docs/api/XCEngine/Resources/Material/Material.md +++ b/docs/api/XCEngine/Resources/Material/Material.md @@ -4,7 +4,7 @@ **类型**: `submodule` -**描述**: 材质运行时对象、材质 source 文件解析，以及 `.xcmat` artifact 回读链路所在子模块。 +**描述**: 材质运行时对象、显式 render-state 契约、材质 source 文件解析，以及 `.xcmat` artifact 回读链路所在子模块。 ## 概览 @@ -12,6 +12,8 @@ - [Material](Material/Material.md) 运行时材质对象，负责 shader schema、render metadata、数值属性、texture binding 元数据和 packed constant buffer。 +- [MaterialRenderState](Material/MaterialRenderState.md) + 显式材质 render-state 契约，定义 blend / depth / cull 相关枚举和 `MaterialRenderState` 结构。 - [MaterialLoader](MaterialLoader/MaterialLoader.md) 负责 source 材质与 `.xcmat` artifact 的加载。 - 与项目资产链路的接缝 @@ -20,8 +22,9 @@ 当前材质链路的关键点是： - source 材质里的 texture path 会进入 `AssetDatabase` 的依赖快照 -- `.xcmat` v2 会同时保存编码 `AssetRef` 与可选 path +- 当前 `.xcmat` 版本会同时保存编码 `AssetRef` 与可选 path - `Material::GetTexture(...)` / `GetTextureBindingTexture(...)` 会在首次访问时启动异步纹理兑现 +- blend / depth / cull 等固定功能状态当前已经拆到独立头 `MaterialRenderState.h` ## 当前主链路 @@ -33,6 +36,7 @@ ## 头文件 - [Material](Material/Material.md) - `Material.h` +- [MaterialRenderState](Material/MaterialRenderState.md) - `MaterialRenderState.h` - [MaterialLoader](MaterialLoader/MaterialLoader.md) - `MaterialLoader.h` ## 相关文档 diff --git a/docs/api/XCEngine/Resources/Material/Material/GetRenderState.md b/docs/api/XCEngine/Resources/Material/Material/GetRenderState.md index 3f05b844..fb1de825 100644 --- a/docs/api/XCEngine/Resources/Material/Material/GetRenderState.md +++ b/docs/api/XCEngine/Resources/Material/Material/GetRenderState.md @@ -12,6 +12,7 @@ const MaterialRenderState& GetRenderState() const; - 头文件内联实现为直接返回 `m_renderState` 的常量引用。 - 默认值当前对应 [MaterialRenderState](MaterialRenderState.md) 的默认成员初始化状态。 +- 即使 [HasRenderStateOverride](HasRenderStateOverride.md) 当前为 `false`，这份结构也仍然会保留最近一次写入或默认构造出的缓存值。 - 调用方不应在后续材质写操作后继续持久保存这份引用。 ## 相关文档 @@ -19,3 +20,4 @@ const MaterialRenderState& GetRenderState() const; - [Material](Material.md) - [MaterialRenderState](MaterialRenderState.md) - [SetRenderState](SetRenderState.md) +- [HasRenderStateOverride](HasRenderStateOverride.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/HasRenderStateOverride.md b/docs/api/XCEngine/Resources/Material/Material/HasRenderStateOverride.md new file mode 100644 index 00000000..13169dac --- /dev/null +++ b/docs/api/XCEngine/Resources/Material/Material/HasRenderStateOverride.md @@ -0,0 +1,33 @@ +# Material::HasRenderStateOverride + +```cpp +bool HasRenderStateOverride() const; +``` + +## 作用 + +判断当前 `m_renderState` 是否作为材质侧显式 override 生效。 + +## 当前语义 + +- 头文件内联实现为直接返回 `m_hasRenderStateOverride`。 +- 当它为 `true` 时，`RenderMaterialStateUtils::ResolveEffectiveRenderState(...)` 当前会优先采用材质侧 `renderState`。 +- 当它为 `false` 时，材质对象仍然可能缓存一份 `MaterialRenderState`，但渲染路径会继续优先使用 shader pass 固定功能状态或默认 opaque 基线。 + +## 当前调用链 + +- [SetRenderState](SetRenderState.md) 当前会把它自动置为 `true`。 +- [SetRenderStateOverrideEnabled](SetRenderStateOverrideEnabled.md) 当前允许单独切换这个标志，而不清空已缓存的 `m_renderState`。 +- `MaterialLoader` / `.xcmat` artifact 回读当前依赖它区分“显式材质 override”和“未声明 renderState”。 + +## 测试锚点 + +- `tests/Resources/Material/test_material_loader.cpp` 当前覆盖了 source 材质声明 `renderState` 时返回 `true`，未声明时返回 `false`，以及 artifact round-trip 保留该标志。 +- `tests/Rendering/unit/test_render_scene_extractor.cpp` 当前依赖这条语义决定 shader pass fixed-function state 是否被材质覆盖。 + +## 相关文档 + +- [Material](Material.md) +- [GetRenderState](GetRenderState.md) +- [SetRenderState](SetRenderState.md) +- [SetRenderStateOverrideEnabled](SetRenderStateOverrideEnabled.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/Material.md b/docs/api/XCEngine/Resources/Material/Material/Material.md index 942be82e..7cf168f2 100644 --- a/docs/api/XCEngine/Resources/Material/Material/Material.md +++ b/docs/api/XCEngine/Resources/Material/Material/Material.md @@ -15,7 +15,7 @@ 1. 资源身份 `name`、`path`、`guid`、`isValid`、`memorySize` 2. 渲染元数据 - `shader`、`renderQueue`、`renderState`、`shaderPass`、`tags` + `shader`、`renderQueue`、`renderState`、`render-state override flag`、`shaderPass`、`tags` 3. 数值属性 `Float` / `Float2` / `Float3` / `Float4` / `Int` / `Bool` 4. texture binding 元数据 @@ -30,7 +30,8 @@ `Material` 当前不只是“属性容器”。`renderQueue`、`renderState`、`shaderPass` 与 `tags` 已经是渲染执行链路的正式输入： - `renderQueue` 直接参与可见项排序。 -- `renderState` 由 `RenderMaterialUtility` 映射到 RHI blend/depth/cull 描述。 +- `renderState` 当前只是“材质侧显式 override 缓存”；只有 [HasRenderStateOverride](HasRenderStateOverride.md) 为 `true` 时，渲染路径才会优先采用它。 +- shader pass 若声明了 fixed-function 状态，`RenderMaterialStateUtils` 当前会先以 pass 状态为基线，再由材质 override 决定是否覆盖。 - `shaderPass` 允许材质显式指向目标 shader pass。 - `tags` 则继续承载 `LightMode`、`RenderType` 一类 pass 选择语义。 @@ -105,6 +106,8 @@ texture binding 当前使用“两层状态”： | [GetRenderQueue](GetRenderQueue.md) | 读取当前 render queue 整数值。 | | [SetRenderState](SetRenderState.md) | 整体替换 render state。 | | [GetRenderState](GetRenderState.md) | 读取当前 render state 常量引用。 | +| [HasRenderStateOverride](HasRenderStateOverride.md) | 判断当前 render state 是否作为显式 override 生效。 | +| [SetRenderStateOverrideEnabled](SetRenderStateOverrideEnabled.md) | 显式启用或关闭材质 render-state override。 | | [SetShaderPass](SetShaderPass.md) | 写入显式 shader pass 名。 | | [GetShaderPass](GetShaderPass.md) | 读取当前 shader pass 名。 | diff --git a/docs/api/XCEngine/Resources/Material/Material/MaterialBlendFactor.md b/docs/api/XCEngine/Resources/Material/Material/MaterialBlendFactor.md index 203bb72f..584dfdf2 100644 --- a/docs/api/XCEngine/Resources/Material/Material/MaterialBlendFactor.md +++ b/docs/api/XCEngine/Resources/Material/Material/MaterialBlendFactor.md @@ -4,7 +4,7 @@ **类型**: `enum class` -**头文件**: `XCEngine/Resources/Material/Material.h` +**头文件**: `XCEngine/Resources/Material/MaterialRenderState.h` ## 枚举值 diff --git a/docs/api/XCEngine/Resources/Material/Material/MaterialBlendOp.md b/docs/api/XCEngine/Resources/Material/Material/MaterialBlendOp.md index 1d4d63da..d3046605 100644 --- a/docs/api/XCEngine/Resources/Material/Material/MaterialBlendOp.md +++ b/docs/api/XCEngine/Resources/Material/Material/MaterialBlendOp.md @@ -4,7 +4,7 @@ **类型**: `enum class` -**头文件**: `XCEngine/Resources/Material/Material.h` +**头文件**: `XCEngine/Resources/Material/MaterialRenderState.h` ## 枚举值 diff --git a/docs/api/XCEngine/Resources/Material/Material/MaterialComparisonFunc.md b/docs/api/XCEngine/Resources/Material/Material/MaterialComparisonFunc.md index 9e3fa9a6..738f63a8 100644 --- a/docs/api/XCEngine/Resources/Material/Material/MaterialComparisonFunc.md +++ b/docs/api/XCEngine/Resources/Material/Material/MaterialComparisonFunc.md @@ -4,7 +4,7 @@ **类型**: `enum class` -**头文件**: `XCEngine/Resources/Material/Material.h` +**头文件**: `XCEngine/Resources/Material/MaterialRenderState.h` ## 枚举值 diff --git a/docs/api/XCEngine/Resources/Material/Material/MaterialCullMode.md b/docs/api/XCEngine/Resources/Material/Material/MaterialCullMode.md index e787e49a..634c367a 100644 --- a/docs/api/XCEngine/Resources/Material/Material/MaterialCullMode.md +++ b/docs/api/XCEngine/Resources/Material/Material/MaterialCullMode.md @@ -4,7 +4,7 @@ **类型**: `enum class` -**头文件**: `XCEngine/Resources/Material/Material.h` +**头文件**: `XCEngine/Resources/Material/MaterialRenderState.h` ## 枚举值 diff --git a/docs/api/XCEngine/Resources/Material/Material/MaterialRenderState.md b/docs/api/XCEngine/Resources/Material/Material/MaterialRenderState.md index 951f20b6..fa44b61c 100644 --- a/docs/api/XCEngine/Resources/Material/Material/MaterialRenderState.md +++ b/docs/api/XCEngine/Resources/Material/Material/MaterialRenderState.md @@ -4,7 +4,7 @@ **类型**: `struct` -**头文件**: `XCEngine/Resources/Material/Material.h` +**头文件**: `XCEngine/Resources/Material/MaterialRenderState.h` ## 字段 @@ -26,6 +26,7 @@ ## 当前语义 - 这是 `Material` 当前 render metadata 的核心结构。 +- 该结构当前已经从 `Material.h` 拆到独立头文件 `MaterialRenderState.h`，但 `Material` 仍继续通过 `GetRenderState()` / `SetRenderState()` 暴露它。 - `operator==` / `operator!=` 当前逐字段比较全部 render-state 成员。 - 默认值当前是： - `blendEnable = false` diff --git a/docs/api/XCEngine/Resources/Material/Material/Release.md b/docs/api/XCEngine/Resources/Material/Material/Release.md index 02ecb415..18575e06 100644 --- a/docs/api/XCEngine/Resources/Material/Material/Release.md +++ b/docs/api/XCEngine/Resources/Material/Material/Release.md @@ -13,6 +13,7 @@ void Release(); - `m_shader.Reset()` - 把 `renderQueue` 恢复到 `MaterialRenderQueue::Geometry` - 重置 `renderState` +- 把 render-state override 标志重置为 `false` - 清空 `shaderPass`、`tags`、`m_properties`、`m_textureBindings`、`m_constantBufferData` - 把 `m_changeVersion` 重置为 `1` - 把 `m_isValid` 设为 `false` diff --git a/docs/api/XCEngine/Resources/Material/Material/SetRenderState.md b/docs/api/XCEngine/Resources/Material/Material/SetRenderState.md index 06d6d33a..3e06d6d6 100644 --- a/docs/api/XCEngine/Resources/Material/Material/SetRenderState.md +++ b/docs/api/XCEngine/Resources/Material/Material/SetRenderState.md @@ -11,6 +11,7 @@ void SetRenderState(const MaterialRenderState& renderState); ## 当前行为 - 把传入结构整体复制到 `m_renderState`。 +- 同时把 `m_hasRenderStateOverride` 设为 `true`。 - 随后调用 `MarkChanged(false)`： - 重算 `memorySize` - 推进 `changeVersion` @@ -19,6 +20,7 @@ void SetRenderState(const MaterialRenderState& renderState); ## 当前语义 - 这是整结构写入，不是字段级 merge。 +- 一旦调用该入口，材质侧 render-state override 就会被显式启用。 - 渲染路径当前会把这份状态交给 `RenderMaterialUtility` 做 RHI 状态映射。 ## 测试覆盖 @@ -30,3 +32,5 @@ void SetRenderState(const MaterialRenderState& renderState); - [Material](Material.md) - [MaterialRenderState](MaterialRenderState.md) - [GetRenderState](GetRenderState.md) +- [HasRenderStateOverride](HasRenderStateOverride.md) +- [SetRenderStateOverrideEnabled](SetRenderStateOverrideEnabled.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/SetRenderStateOverrideEnabled.md b/docs/api/XCEngine/Resources/Material/Material/SetRenderStateOverrideEnabled.md new file mode 100644 index 00000000..ae814c80 --- /dev/null +++ b/docs/api/XCEngine/Resources/Material/Material/SetRenderStateOverrideEnabled.md @@ -0,0 +1,35 @@ +# Material::SetRenderStateOverrideEnabled + +```cpp +void SetRenderStateOverrideEnabled(bool enabled); +``` + +## 作用 + +显式打开或关闭材质侧 render-state override 标志，而不修改已缓存的 `MaterialRenderState` 内容。 + +## 当前行为 + +- 直接把 `m_hasRenderStateOverride` 设为传入值。 +- 随后调用 `MarkChanged(false)`： + - 重算 `memorySize` + - 推进 `changeVersion` + - 不重新打包 constant buffer + +## 当前语义 + +- 这不是“清空 render state”；它只切换“材质侧状态是否生效”。 +- 若先前已经通过 [SetRenderState](SetRenderState.md) 写入过状态，再把该标志关掉，缓存值仍会保留在 [GetRenderState](GetRenderState.md) 里。 +- 当前主要用于 loader / artifact 回读链路，把“未声明 renderState”与“显式声明了默认值状态”区分开。 + +## 当前调用链 + +- `MaterialLoader` 在回读 `.xcmat` 时会根据 `MaterialArtifactHeader::hasRenderStateOverride` 调用它。 +- [Release](Release.md) 会把该标志恢复为 `false`。 + +## 相关文档 + +- [Material](Material.md) +- [HasRenderStateOverride](HasRenderStateOverride.md) +- [SetRenderState](SetRenderState.md) +- [Release](Release.md) diff --git a/docs/api/XCEngine/Resources/Material/Material/SetTextureAssetRef.md b/docs/api/XCEngine/Resources/Material/Material/SetTextureAssetRef.md index 5528e29c..452998b2 100644 --- a/docs/api/XCEngine/Resources/Material/Material/SetTextureAssetRef.md +++ b/docs/api/XCEngine/Resources/Material/Material/SetTextureAssetRef.md @@ -24,7 +24,7 @@ void SetTextureAssetRef( ## 关键语义 -- 这是当前 `.xcmat` v2 回读最重要的 texture binding 写入口。 +- 这是当前 `.xcmat` 回读最重要的 texture binding 写入口之一。 - 它保存的是“稳定身份 + 可选定位信息”，不是即时可用的纹理句柄。 - 后续第一次访问纹理时，`Material` 才会再根据 `AssetRef` / path 启动异步加载。 diff --git a/docs/api/XCEngine/Resources/Material/MaterialLoader/Load.md b/docs/api/XCEngine/Resources/Material/MaterialLoader/Load.md index d4b682c3..8fde0e24 100644 --- a/docs/api/XCEngine/Resources/Material/MaterialLoader/Load.md +++ b/docs/api/XCEngine/Resources/Material/MaterialLoader/Load.md @@ -35,17 +35,21 @@ LoadResult Load(const Containers::String& path, const ImportSettings* settings = - `renderState` 枚举值非法 - 结构化对象提取失败 +若 source 材质根本不声明 `renderState`，当前会保持 `HasRenderStateOverride() == false`。 + ## `.xcmat` artifact 分支 当前 `.xcmat` 回读顺序是： 1. 读取 `MaterialArtifactFileHeader` -2. 校验 magic 必须是 `XCMAT02` +2. 校验 magic 必须是 `XCMAT04` 3. 读取材质名、source path、shader path、shader pass 4. 读取 `MaterialArtifactHeader` 5. 恢复 tags -6. 恢复非 texture 属性 -7. 恢复每个 texture binding 的： +6. 恢复 keywords +7. 根据 `hasRenderStateOverride` 恢复材质 override 标志 +8. 恢复非 texture 属性 +9. 恢复每个 texture binding 的： - binding name - 编码 `AssetRef` 字符串 - 可选 texture path @@ -57,6 +61,11 @@ texture binding 恢复时： 因此 artifact 加载完成后的材质，texture binding 通常先只有元数据，没有立即兑现的纹理句柄。 +`MaterialArtifactHeader::hasRenderStateOverride` 当前还负责区分： + +- 材质确实声明了 `renderState` +- 材质只是保留一份默认 `renderState` 缓存，但当前不把它当作显式 override + ## 与延迟纹理加载的关系 `Load()` 本身不会等待纹理依赖同步完成。 diff --git a/docs/api/XCEngine/Resources/Material/MaterialLoader/MaterialLoader.md b/docs/api/XCEngine/Resources/Material/MaterialLoader/MaterialLoader.md index 4e65fb6f..94413a77 100644 --- a/docs/api/XCEngine/Resources/Material/MaterialLoader/MaterialLoader.md +++ b/docs/api/XCEngine/Resources/Material/MaterialLoader/MaterialLoader.md @@ -18,11 +18,13 @@ 3. 材质 artifact `.xcmat` -其中 `.xcmat` 已经是当前材质 artifact v2： +其中 `.xcmat` 已经是当前材质 artifact v4： -- magic `XCMAT02` +- magic `XCMAT04` +- schema `4` - texture binding 保存的是“binding name + 编码 `AssetRef` + 可选 path” - 回读后默认只恢复绑定元数据，不会立即同步加载全部纹理 payload +- 额外保存 `hasRenderStateOverride`，区分“显式材质 override”和“仅保留默认 render-state 缓存” ## source 材质解析能力 @@ -34,6 +36,7 @@ 支持整数或名字 - `tags` - `renderState` + 解析到该对象时会自动启用 `HasRenderStateOverride()` - texture 声明 包括 known key 和 `textures { ... }` 字典 @@ -42,7 +45,7 @@ ## 当前实现边界 - source 解析仍是轻量手写 JSON-like parser，不是完整 JSON AST。 -- `.xcmat` 分支显式检查的是 magic，不是 `schemaVersion` 分支分发。 +- `.xcmat` 分支显式检查的是 magic，不是 `schemaVersion` 分支分发；当前 reader 只覆盖到 `XCMAT04`。 - 异步纹理兑现由 `Material` 在后续访问时触发，而不是在 `Load()` 内一次性完成。 ## 重点方法 diff --git a/docs/api/XCEngine/Resources/Mesh/Mesh/AddMaterial.md b/docs/api/XCEngine/Resources/Mesh/Mesh/AddMaterial.md index 480aaed7..d93f1357 100644 --- a/docs/api/XCEngine/Resources/Mesh/Mesh/AddMaterial.md +++ b/docs/api/XCEngine/Resources/Mesh/Mesh/AddMaterial.md @@ -1,31 +1,26 @@ # Mesh::AddMaterial -添加元素或建立关联。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/Mesh.h` + +## 签名 ```cpp void AddMaterial(Material* material); ``` -该方法声明于 `XCEngine/Resources/Mesh/Mesh.h`，当前页面用于固定 `Mesh` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `material` - 参数语义详见头文件声明。 +更新 `m_materials`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Mesh object; - // 根据上下文补齐参数后调用 Mesh::AddMaterial(...)。 - (void)object; -} -``` +- 会更新 `m_materials`。 +- 当前实现会调用 `PushBack`、`UpdateMemorySize`。 ## 相关文档 -- [返回类总览](Mesh.md) -- [返回模块目录](../Mesh.md) +- [Mesh](Mesh.md) diff --git a/docs/api/XCEngine/Resources/Mesh/Mesh/AddSection.md b/docs/api/XCEngine/Resources/Mesh/Mesh/AddSection.md index 7aa9457d..359a9dbb 100644 --- a/docs/api/XCEngine/Resources/Mesh/Mesh/AddSection.md +++ b/docs/api/XCEngine/Resources/Mesh/Mesh/AddSection.md @@ -1,31 +1,26 @@ # Mesh::AddSection -添加元素或建立关联。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/Mesh.h` + +## 签名 ```cpp void AddSection(const MeshSection& section); ``` -该方法声明于 `XCEngine/Resources/Mesh/Mesh.h`，当前页面用于固定 `Mesh` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `section` - 参数语义详见头文件声明。 +更新 `m_sections`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Mesh object; - // 根据上下文补齐参数后调用 Mesh::AddSection(...)。 - (void)object; -} -``` +- 会更新 `m_sections`。 +- 当前实现会调用 `PushBack`、`UpdateMemorySize`。 ## 相关文档 -- [返回类总览](Mesh.md) -- [返回模块目录](../Mesh.md) +- [Mesh](Mesh.md) diff --git a/docs/api/XCEngine/Resources/Mesh/Mesh/AddTexture.md b/docs/api/XCEngine/Resources/Mesh/Mesh/AddTexture.md index b3bc3736..197640de 100644 --- a/docs/api/XCEngine/Resources/Mesh/Mesh/AddTexture.md +++ b/docs/api/XCEngine/Resources/Mesh/Mesh/AddTexture.md @@ -1,31 +1,26 @@ # Mesh::AddTexture -添加元素或建立关联。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/Mesh.h` + +## 签名 ```cpp void AddTexture(Texture* texture); ``` -该方法声明于 `XCEngine/Resources/Mesh/Mesh.h`，当前页面用于固定 `Mesh` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `texture` - 参数语义详见头文件声明。 +更新 `m_textures`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Mesh object; - // 根据上下文补齐参数后调用 Mesh::AddTexture(...)。 - (void)object; -} -``` +- 会更新 `m_textures`。 +- 当前实现会调用 `PushBack`、`UpdateMemorySize`。 ## 相关文档 -- [返回类总览](Mesh.md) -- [返回模块目录](../Mesh.md) +- [Mesh](Mesh.md) diff --git a/docs/api/XCEngine/Resources/Mesh/Mesh/Constructor.md b/docs/api/XCEngine/Resources/Mesh/Mesh/Constructor.md index 54eb0ff8..e3ceef48 100644 --- a/docs/api/XCEngine/Resources/Mesh/Mesh/Constructor.md +++ b/docs/api/XCEngine/Resources/Mesh/Mesh/Constructor.md @@ -1,28 +1,25 @@ # Mesh::Mesh() -构造对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/Mesh.h` + +## 签名 ```cpp Mesh(); ``` -该方法声明于 `XCEngine/Resources/Mesh/Mesh.h`，当前页面用于固定 `Mesh` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +构造 `Mesh` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Mesh object; -} -``` +- 当前为默认构造实现。 ## 相关文档 -- [返回类总览](Mesh.md) -- [返回模块目录](../Mesh.md) +- [Mesh](Mesh.md) diff --git a/docs/api/XCEngine/Resources/Mesh/Mesh/Destructor.md b/docs/api/XCEngine/Resources/Mesh/Mesh/Destructor.md index 37076605..342db584 100644 --- a/docs/api/XCEngine/Resources/Mesh/Mesh/Destructor.md +++ b/docs/api/XCEngine/Resources/Mesh/Mesh/Destructor.md @@ -1,29 +1,25 @@ # Mesh::~Mesh() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/Mesh.h` + +## 签名 ```cpp virtual ~Mesh() override; ``` -该方法声明于 `XCEngine/Resources/Mesh/Mesh.h`，当前页面用于固定 `Mesh` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +销毁 `Mesh` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Mesh object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 当前为默认析构实现。 ## 相关文档 -- [返回类总览](Mesh.md) -- [返回模块目录](../Mesh.md) +- [Mesh](Mesh.md) diff --git a/docs/api/XCEngine/Resources/Mesh/Mesh/GetBounds.md b/docs/api/XCEngine/Resources/Mesh/Mesh/GetBounds.md index 4673bcff..29eb96f4 100644 --- a/docs/api/XCEngine/Resources/Mesh/Mesh/GetBounds.md +++ b/docs/api/XCEngine/Resources/Mesh/Mesh/GetBounds.md @@ -1,30 +1,26 @@ # Mesh::GetBounds -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/Mesh.h` + +## 签名 ```cpp const Math::Bounds& GetBounds() const; ``` -该方法声明于 `XCEngine/Resources/Mesh/Mesh.h`，当前页面用于固定 `Mesh` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_bounds` 当前值。 -**返回：** `const Math::Bounds&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Mesh object; - // 根据上下文补齐参数后调用 Mesh::GetBounds(...)。 - (void)object; -} -``` +- 返回 `m_bounds` 当前值。 ## 相关文档 -- [返回类总览](Mesh.md) -- [返回模块目录](../Mesh.md) +- [Mesh](Mesh.md) +- [SetBounds](SetBounds.md) diff --git a/docs/api/XCEngine/Resources/Mesh/Mesh/GetGUID.md b/docs/api/XCEngine/Resources/Mesh/Mesh/GetGUID.md index cd1f5eb1..7625eec2 100644 --- a/docs/api/XCEngine/Resources/Mesh/Mesh/GetGUID.md +++ b/docs/api/XCEngine/Resources/Mesh/Mesh/GetGUID.md @@ -1,30 +1,25 @@ # Mesh::GetGUID -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/Mesh.h` + +## 签名 ```cpp ResourceGUID GetGUID() const override; ``` -该方法声明于 `XCEngine/Resources/Mesh/Mesh.h`，当前页面用于固定 `Mesh` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_guid` 当前值。 -**返回：** `ResourceGUID` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Mesh object; - // 根据上下文补齐参数后调用 Mesh::GetGUID(...)。 - (void)object; -} -``` +- 返回 `m_guid` 当前值。 ## 相关文档 -- [返回类总览](Mesh.md) -- [返回模块目录](../Mesh.md) +- [Mesh](Mesh.md) diff --git a/docs/api/XCEngine/Resources/Mesh/Mesh/GetIndexCount.md b/docs/api/XCEngine/Resources/Mesh/Mesh/GetIndexCount.md index 6a32655b..fec0bc89 100644 --- a/docs/api/XCEngine/Resources/Mesh/Mesh/GetIndexCount.md +++ b/docs/api/XCEngine/Resources/Mesh/Mesh/GetIndexCount.md @@ -1,30 +1,25 @@ # Mesh::GetIndexCount -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/Mesh.h` + +## 签名 ```cpp Core::uint32 GetIndexCount() const; ``` -该方法声明于 `XCEngine/Resources/Mesh/Mesh.h`，当前页面用于固定 `Mesh` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_indexCount` 当前值。 -**返回：** `Core::uint32` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Mesh object; - // 根据上下文补齐参数后调用 Mesh::GetIndexCount(...)。 - (void)object; -} -``` +- 返回 `m_indexCount` 当前值。 ## 相关文档 -- [返回类总览](Mesh.md) -- [返回模块目录](../Mesh.md) +- [Mesh](Mesh.md) diff --git a/docs/api/XCEngine/Resources/Mesh/Mesh/GetIndexData.md b/docs/api/XCEngine/Resources/Mesh/Mesh/GetIndexData.md index b5b8b239..b73d7bdc 100644 --- a/docs/api/XCEngine/Resources/Mesh/Mesh/GetIndexData.md +++ b/docs/api/XCEngine/Resources/Mesh/Mesh/GetIndexData.md @@ -1,30 +1,26 @@ # Mesh::GetIndexData -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/Mesh.h` + +## 签名 ```cpp const void* GetIndexData() const; ``` -该方法声明于 `XCEngine/Resources/Mesh/Mesh.h`，当前页面用于固定 `Mesh` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_indexData`。 -**返回：** `const void*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Mesh object; - // 根据上下文补齐参数后调用 Mesh::GetIndexData(...)。 - (void)object; -} -``` +- 会更新 `m_indexData`。 ## 相关文档 -- [返回类总览](Mesh.md) -- [返回模块目录](../Mesh.md) +- [Mesh](Mesh.md) +- [SetIndexData](SetIndexData.md) diff --git a/docs/api/XCEngine/Resources/Mesh/Mesh/GetIndexDataSize.md b/docs/api/XCEngine/Resources/Mesh/Mesh/GetIndexDataSize.md index 44a97a59..1f9b7943 100644 --- a/docs/api/XCEngine/Resources/Mesh/Mesh/GetIndexDataSize.md +++ b/docs/api/XCEngine/Resources/Mesh/Mesh/GetIndexDataSize.md @@ -1,30 +1,25 @@ # Mesh::GetIndexDataSize -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/Mesh.h` + +## 签名 ```cpp size_t GetIndexDataSize() const; ``` -该方法声明于 `XCEngine/Resources/Mesh/Mesh.h`，当前页面用于固定 `Mesh` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_indexData`。 -**返回：** `size_t` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Mesh object; - // 根据上下文补齐参数后调用 Mesh::GetIndexDataSize(...)。 - (void)object; -} -``` +- 会更新 `m_indexData`。 ## 相关文档 -- [返回类总览](Mesh.md) -- [返回模块目录](../Mesh.md) +- [Mesh](Mesh.md) diff --git a/docs/api/XCEngine/Resources/Mesh/Mesh/GetMaterial.md b/docs/api/XCEngine/Resources/Mesh/Mesh/GetMaterial.md index cf0299a1..efa1c0b0 100644 --- a/docs/api/XCEngine/Resources/Mesh/Mesh/GetMaterial.md +++ b/docs/api/XCEngine/Resources/Mesh/Mesh/GetMaterial.md @@ -1,31 +1,27 @@ # Mesh::GetMaterial -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/Mesh.h` + +## 签名 ```cpp Material* GetMaterial(Core::uint32 index) const; ``` -该方法声明于 `XCEngine/Resources/Mesh/Mesh.h`，当前页面用于固定 `Mesh` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `index` - 参数语义详见头文件声明。 +更新 `m_materials`。 -**返回：** `Material*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Mesh object; - // 根据上下文补齐参数后调用 Mesh::GetMaterial(...)。 - (void)object; -} -``` +- 会更新 `m_materials`。 +- 包含条件分支，并可能提前返回。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](Mesh.md) -- [返回模块目录](../Mesh.md) +- [Mesh](Mesh.md) diff --git a/docs/api/XCEngine/Resources/Mesh/Mesh/GetMaterials.md b/docs/api/XCEngine/Resources/Mesh/Mesh/GetMaterials.md index 8d200c8e..b0939ae1 100644 --- a/docs/api/XCEngine/Resources/Mesh/Mesh/GetMaterials.md +++ b/docs/api/XCEngine/Resources/Mesh/Mesh/GetMaterials.md @@ -1,30 +1,25 @@ # Mesh::GetMaterials -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/Mesh.h` + +## 签名 ```cpp const Containers::Array& GetMaterials() const; ``` -该方法声明于 `XCEngine/Resources/Mesh/Mesh.h`，当前页面用于固定 `Mesh` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_materials` 当前值。 -**返回：** `const Containers::Array&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Mesh object; - // 根据上下文补齐参数后调用 Mesh::GetMaterials(...)。 - (void)object; -} -``` +- 返回 `m_materials` 当前值。 ## 相关文档 -- [返回类总览](Mesh.md) -- [返回模块目录](../Mesh.md) +- [Mesh](Mesh.md) diff --git a/docs/api/XCEngine/Resources/Mesh/Mesh/GetMemorySize.md b/docs/api/XCEngine/Resources/Mesh/Mesh/GetMemorySize.md index 3f7a67fb..3db401e3 100644 --- a/docs/api/XCEngine/Resources/Mesh/Mesh/GetMemorySize.md +++ b/docs/api/XCEngine/Resources/Mesh/Mesh/GetMemorySize.md @@ -1,30 +1,25 @@ # Mesh::GetMemorySize -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/Mesh.h` + +## 签名 ```cpp size_t GetMemorySize() const override; ``` -该方法声明于 `XCEngine/Resources/Mesh/Mesh.h`，当前页面用于固定 `Mesh` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_memorySize` 当前值。 -**返回：** `size_t` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Mesh object; - // 根据上下文补齐参数后调用 Mesh::GetMemorySize(...)。 - (void)object; -} -``` +- 返回 `m_memorySize` 当前值。 ## 相关文档 -- [返回类总览](Mesh.md) -- [返回模块目录](../Mesh.md) +- [Mesh](Mesh.md) diff --git a/docs/api/XCEngine/Resources/Mesh/Mesh/GetName.md b/docs/api/XCEngine/Resources/Mesh/Mesh/GetName.md index 39419e0a..3ea29fac 100644 --- a/docs/api/XCEngine/Resources/Mesh/Mesh/GetName.md +++ b/docs/api/XCEngine/Resources/Mesh/Mesh/GetName.md @@ -1,30 +1,25 @@ # Mesh::GetName -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/Mesh.h` + +## 签名 ```cpp const Containers::String& GetName() const override; ``` -该方法声明于 `XCEngine/Resources/Mesh/Mesh.h`，当前页面用于固定 `Mesh` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_name` 当前值。 -**返回：** `const Containers::String&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Mesh object; - // 根据上下文补齐参数后调用 Mesh::GetName(...)。 - (void)object; -} -``` +- 返回 `m_name` 当前值。 ## 相关文档 -- [返回类总览](Mesh.md) -- [返回模块目录](../Mesh.md) +- [Mesh](Mesh.md) diff --git a/docs/api/XCEngine/Resources/Mesh/Mesh/GetPath.md b/docs/api/XCEngine/Resources/Mesh/Mesh/GetPath.md index 0d54c0ba..d7068932 100644 --- a/docs/api/XCEngine/Resources/Mesh/Mesh/GetPath.md +++ b/docs/api/XCEngine/Resources/Mesh/Mesh/GetPath.md @@ -1,30 +1,25 @@ # Mesh::GetPath -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/Mesh.h` + +## 签名 ```cpp const Containers::String& GetPath() const override; ``` -该方法声明于 `XCEngine/Resources/Mesh/Mesh.h`，当前页面用于固定 `Mesh` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_path` 当前值。 -**返回：** `const Containers::String&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Mesh object; - // 根据上下文补齐参数后调用 Mesh::GetPath(...)。 - (void)object; -} -``` +- 返回 `m_path` 当前值。 ## 相关文档 -- [返回类总览](Mesh.md) -- [返回模块目录](../Mesh.md) +- [Mesh](Mesh.md) diff --git a/docs/api/XCEngine/Resources/Mesh/Mesh/GetSections.md b/docs/api/XCEngine/Resources/Mesh/Mesh/GetSections.md index 8dbb4b4a..6da245b7 100644 --- a/docs/api/XCEngine/Resources/Mesh/Mesh/GetSections.md +++ b/docs/api/XCEngine/Resources/Mesh/Mesh/GetSections.md @@ -1,30 +1,25 @@ # Mesh::GetSections -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/Mesh.h` + +## 签名 ```cpp const Containers::Array& GetSections() const; ``` -该方法声明于 `XCEngine/Resources/Mesh/Mesh.h`，当前页面用于固定 `Mesh` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_sections` 当前值。 -**返回：** `const Containers::Array&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Mesh object; - // 根据上下文补齐参数后调用 Mesh::GetSections(...)。 - (void)object; -} -``` +- 返回 `m_sections` 当前值。 ## 相关文档 -- [返回类总览](Mesh.md) -- [返回模块目录](../Mesh.md) +- [Mesh](Mesh.md) diff --git a/docs/api/XCEngine/Resources/Mesh/Mesh/GetTextures.md b/docs/api/XCEngine/Resources/Mesh/Mesh/GetTextures.md index de8602d0..c4d8ec06 100644 --- a/docs/api/XCEngine/Resources/Mesh/Mesh/GetTextures.md +++ b/docs/api/XCEngine/Resources/Mesh/Mesh/GetTextures.md @@ -1,30 +1,25 @@ # Mesh::GetTextures -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/Mesh.h` + +## 签名 ```cpp const Containers::Array& GetTextures() const; ``` -该方法声明于 `XCEngine/Resources/Mesh/Mesh.h`，当前页面用于固定 `Mesh` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_textures` 当前值。 -**返回：** `const Containers::Array&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Mesh object; - // 根据上下文补齐参数后调用 Mesh::GetTextures(...)。 - (void)object; -} -``` +- 返回 `m_textures` 当前值。 ## 相关文档 -- [返回类总览](Mesh.md) -- [返回模块目录](../Mesh.md) +- [Mesh](Mesh.md) diff --git a/docs/api/XCEngine/Resources/Mesh/Mesh/GetType.md b/docs/api/XCEngine/Resources/Mesh/Mesh/GetType.md index 9c5d5c3f..c338e3d2 100644 --- a/docs/api/XCEngine/Resources/Mesh/Mesh/GetType.md +++ b/docs/api/XCEngine/Resources/Mesh/Mesh/GetType.md @@ -1,30 +1,25 @@ # Mesh::GetType -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/Mesh.h` + +## 签名 ```cpp ResourceType GetType() const override; ``` -该方法声明于 `XCEngine/Resources/Mesh/Mesh.h`，当前页面用于固定 `Mesh` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `ResourceType::Mesh`。 -**返回：** `ResourceType` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Mesh object; - // 根据上下文补齐参数后调用 Mesh::GetType(...)。 - (void)object; -} -``` +- 返回 `ResourceType::Mesh`。 ## 相关文档 -- [返回类总览](Mesh.md) -- [返回模块目录](../Mesh.md) +- [Mesh](Mesh.md) diff --git a/docs/api/XCEngine/Resources/Mesh/Mesh/GetVertexAttributes.md b/docs/api/XCEngine/Resources/Mesh/Mesh/GetVertexAttributes.md index 04b32ac0..033e33db 100644 --- a/docs/api/XCEngine/Resources/Mesh/Mesh/GetVertexAttributes.md +++ b/docs/api/XCEngine/Resources/Mesh/Mesh/GetVertexAttributes.md @@ -1,30 +1,25 @@ # Mesh::GetVertexAttributes -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/Mesh.h` + +## 签名 ```cpp VertexAttribute GetVertexAttributes() const; ``` -该方法声明于 `XCEngine/Resources/Mesh/Mesh.h`，当前页面用于固定 `Mesh` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_attributes` 当前值。 -**返回：** `VertexAttribute` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Mesh object; - // 根据上下文补齐参数后调用 Mesh::GetVertexAttributes(...)。 - (void)object; -} -``` +- 返回 `m_attributes` 当前值。 ## 相关文档 -- [返回类总览](Mesh.md) -- [返回模块目录](../Mesh.md) +- [Mesh](Mesh.md) diff --git a/docs/api/XCEngine/Resources/Mesh/Mesh/GetVertexCount.md b/docs/api/XCEngine/Resources/Mesh/Mesh/GetVertexCount.md index aa0ced66..d786ba57 100644 --- a/docs/api/XCEngine/Resources/Mesh/Mesh/GetVertexCount.md +++ b/docs/api/XCEngine/Resources/Mesh/Mesh/GetVertexCount.md @@ -1,30 +1,25 @@ # Mesh::GetVertexCount -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/Mesh.h` + +## 签名 ```cpp Core::uint32 GetVertexCount() const; ``` -该方法声明于 `XCEngine/Resources/Mesh/Mesh.h`，当前页面用于固定 `Mesh` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_vertexCount` 当前值。 -**返回：** `Core::uint32` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Mesh object; - // 根据上下文补齐参数后调用 Mesh::GetVertexCount(...)。 - (void)object; -} -``` +- 返回 `m_vertexCount` 当前值。 ## 相关文档 -- [返回类总览](Mesh.md) -- [返回模块目录](../Mesh.md) +- [Mesh](Mesh.md) diff --git a/docs/api/XCEngine/Resources/Mesh/Mesh/GetVertexData.md b/docs/api/XCEngine/Resources/Mesh/Mesh/GetVertexData.md index a697a765..aa831692 100644 --- a/docs/api/XCEngine/Resources/Mesh/Mesh/GetVertexData.md +++ b/docs/api/XCEngine/Resources/Mesh/Mesh/GetVertexData.md @@ -1,30 +1,26 @@ # Mesh::GetVertexData -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/Mesh.h` + +## 签名 ```cpp const void* GetVertexData() const; ``` -该方法声明于 `XCEngine/Resources/Mesh/Mesh.h`，当前页面用于固定 `Mesh` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_vertexData`。 -**返回：** `const void*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Mesh object; - // 根据上下文补齐参数后调用 Mesh::GetVertexData(...)。 - (void)object; -} -``` +- 会更新 `m_vertexData`。 ## 相关文档 -- [返回类总览](Mesh.md) -- [返回模块目录](../Mesh.md) +- [Mesh](Mesh.md) +- [SetVertexData](SetVertexData.md) diff --git a/docs/api/XCEngine/Resources/Mesh/Mesh/GetVertexDataSize.md b/docs/api/XCEngine/Resources/Mesh/Mesh/GetVertexDataSize.md index f450873e..d7c4f6c1 100644 --- a/docs/api/XCEngine/Resources/Mesh/Mesh/GetVertexDataSize.md +++ b/docs/api/XCEngine/Resources/Mesh/Mesh/GetVertexDataSize.md @@ -1,30 +1,25 @@ # Mesh::GetVertexDataSize -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/Mesh.h` + +## 签名 ```cpp size_t GetVertexDataSize() const; ``` -该方法声明于 `XCEngine/Resources/Mesh/Mesh.h`，当前页面用于固定 `Mesh` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +更新 `m_vertexData`。 -**返回：** `size_t` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Mesh object; - // 根据上下文补齐参数后调用 Mesh::GetVertexDataSize(...)。 - (void)object; -} -``` +- 会更新 `m_vertexData`。 ## 相关文档 -- [返回类总览](Mesh.md) -- [返回模块目录](../Mesh.md) +- [Mesh](Mesh.md) diff --git a/docs/api/XCEngine/Resources/Mesh/Mesh/GetVertexStride.md b/docs/api/XCEngine/Resources/Mesh/Mesh/GetVertexStride.md index 6d2874b8..84e68023 100644 --- a/docs/api/XCEngine/Resources/Mesh/Mesh/GetVertexStride.md +++ b/docs/api/XCEngine/Resources/Mesh/Mesh/GetVertexStride.md @@ -1,30 +1,25 @@ # Mesh::GetVertexStride -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/Mesh.h` + +## 签名 ```cpp Core::uint32 GetVertexStride() const; ``` -该方法声明于 `XCEngine/Resources/Mesh/Mesh.h`，当前页面用于固定 `Mesh` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_vertexStride` 当前值。 -**返回：** `Core::uint32` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Mesh object; - // 根据上下文补齐参数后调用 Mesh::GetVertexStride(...)。 - (void)object; -} -``` +- 返回 `m_vertexStride` 当前值。 ## 相关文档 -- [返回类总览](Mesh.md) -- [返回模块目录](../Mesh.md) +- [Mesh](Mesh.md) diff --git a/docs/api/XCEngine/Resources/Mesh/Mesh/IsUse32BitIndex.md b/docs/api/XCEngine/Resources/Mesh/Mesh/IsUse32BitIndex.md index c6ba9ce8..443c64dc 100644 --- a/docs/api/XCEngine/Resources/Mesh/Mesh/IsUse32BitIndex.md +++ b/docs/api/XCEngine/Resources/Mesh/Mesh/IsUse32BitIndex.md @@ -1,30 +1,25 @@ # Mesh::IsUse32BitIndex -查询当前状态。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/Mesh.h` + +## 签名 ```cpp bool IsUse32BitIndex() const; ``` -该方法声明于 `XCEngine/Resources/Mesh/Mesh.h`，当前页面用于固定 `Mesh` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_use32BitIndex` 当前值。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Mesh object; - // 根据上下文补齐参数后调用 Mesh::IsUse32BitIndex(...)。 - (void)object; -} -``` +- 返回 `m_use32BitIndex` 当前值。 ## 相关文档 -- [返回类总览](Mesh.md) -- [返回模块目录](../Mesh.md) +- [Mesh](Mesh.md) diff --git a/docs/api/XCEngine/Resources/Mesh/Mesh/IsValid.md b/docs/api/XCEngine/Resources/Mesh/Mesh/IsValid.md index 97ae5c75..77ac422d 100644 --- a/docs/api/XCEngine/Resources/Mesh/Mesh/IsValid.md +++ b/docs/api/XCEngine/Resources/Mesh/Mesh/IsValid.md @@ -1,30 +1,25 @@ # Mesh::IsValid -查询当前状态。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/Mesh.h` + +## 签名 ```cpp bool IsValid() const override; ``` -该方法声明于 `XCEngine/Resources/Mesh/Mesh.h`，当前页面用于固定 `Mesh` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_isValid` 当前值。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Mesh object; - // 根据上下文补齐参数后调用 Mesh::IsValid(...)。 - (void)object; -} -``` +- 返回 `m_isValid` 当前值。 ## 相关文档 -- [返回类总览](Mesh.md) -- [返回模块目录](../Mesh.md) +- [Mesh](Mesh.md) diff --git a/docs/api/XCEngine/Resources/Mesh/Mesh/Mesh.md b/docs/api/XCEngine/Resources/Mesh/Mesh/Mesh.md index 4c047cee..c0b57ede 100644 --- a/docs/api/XCEngine/Resources/Mesh/Mesh/Mesh.md +++ b/docs/api/XCEngine/Resources/Mesh/Mesh/Mesh.md @@ -6,54 +6,63 @@ **头文件**: `XCEngine/Resources/Mesh/Mesh.h` -**描述**: 定义 `XCEngine/Resources/Mesh` 子目录中的 `Mesh` public API。 +**描述**: 网格资源类型，保存顶点 / 索引数据、section、包围盒以及材质 / 纹理关联，并作为 `IResource` 参与资源管理。 ## 概述 -`Mesh.h` 是 `XCEngine/Resources/Mesh` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。 +`Mesh` 表达的是一份静态网格资源。当前头文件里除了 `Mesh` 本体，还定义了几类和几何布局直接相关的辅助类型： + +- `VertexAttribute` + - 顶点流里有哪些属性位 +- `StaticMeshVertex` + - 默认静态网格顶点布局 +- `MeshSection` + - 一个 submesh / material section 的索引范围与局部包围盒 + +`Mesh` 自身负责持有顶点数据、索引数据、section 列表、材质 / 纹理关联和整体包围盒。 ## 声明概览 | 声明 | 类型 | 说明 | |------|------|------| -| `VertexAttribute` | `enum class` | 头文件中的公开声明。 | -| `StaticMeshVertex` | `struct` | 头文件中的公开声明。 | -| `MeshSection` | `struct` | 头文件中的公开声明。 | -| `Mesh` | `class` | 继承自 `IResource` 的公开声明。 | +| `VertexAttribute` | `enum class` | 顶点属性位标记。 | +| `StaticMeshVertex` | `struct` | 默认静态网格顶点布局。 | +| `MeshSection` | `struct` | 一个 mesh section 的顶点 / 索引范围与材质槽。 | +| `Mesh` | `class` | 网格资源对象。 | ## 公共方法 | 方法 | 描述 | |------|------| -| [Mesh()](Constructor.md) | 构造对象。 | -| [~Mesh()](Destructor.md) | 销毁对象并释放相关资源。 | -| [GetType](GetType.md) | 获取相关状态或对象。 | -| [GetName](GetName.md) | 获取相关状态或对象。 | -| [GetPath](GetPath.md) | 获取相关状态或对象。 | -| [GetGUID](GetGUID.md) | 获取相关状态或对象。 | -| [IsValid](IsValid.md) | 查询当前状态。 | -| [GetMemorySize](GetMemorySize.md) | 获取相关状态或对象。 | -| [Release](Release.md) | 释放引用或底层资源。 | -| [SetVertexData](SetVertexData.md) | 设置相关状态或配置。 | -| [GetVertexData](GetVertexData.md) | 获取相关状态或对象。 | -| [GetVertexDataSize](GetVertexDataSize.md) | 获取相关状态或对象。 | -| [GetVertexCount](GetVertexCount.md) | 获取相关状态或对象。 | -| [GetVertexStride](GetVertexStride.md) | 获取相关状态或对象。 | -| [GetVertexAttributes](GetVertexAttributes.md) | 获取相关状态或对象。 | -| [SetIndexData](SetIndexData.md) | 设置相关状态或配置。 | -| [GetIndexData](GetIndexData.md) | 获取相关状态或对象。 | -| [GetIndexDataSize](GetIndexDataSize.md) | 获取相关状态或对象。 | -| [GetIndexCount](GetIndexCount.md) | 获取相关状态或对象。 | -| [IsUse32BitIndex](IsUse32BitIndex.md) | 查询当前状态。 | -| [SetBounds](SetBounds.md) | 设置相关状态或配置。 | -| [GetBounds](GetBounds.md) | 获取相关状态或对象。 | -| [AddSection](AddSection.md) | 添加元素或建立关联。 | -| [AddMaterial](AddMaterial.md) | 添加元素或建立关联。 | -| [AddTexture](AddTexture.md) | 添加元素或建立关联。 | -| [GetSections](GetSections.md) | 获取相关状态或对象。 | -| [GetMaterials](GetMaterials.md) | 获取相关状态或对象。 | -| [GetTextures](GetTextures.md) | 获取相关状态或对象。 | -| [GetMaterial](GetMaterial.md) | 获取相关状态或对象。 | +| [Mesh()](Constructor.md) | 构造 `Mesh` 实例。 | +| [~Mesh()](Destructor.md) | 销毁 `Mesh` 实例。 | +| [GetType](GetType.md) | 返回 `ResourceType::Mesh`。 | +| [GetName](GetName.md) | 返回 `m_name` 当前值。 | +| [GetPath](GetPath.md) | 返回 `m_path` 当前值。 | +| [GetGUID](GetGUID.md) | 返回 `m_guid` 当前值。 | +| [IsValid](IsValid.md) | 返回 `m_isValid` 当前值。 | +| [GetMemorySize](GetMemorySize.md) | 返回 `m_memorySize` 当前值。 | +| [Release](Release.md) | 执行 `Clear` 协同流程。 | +| [SetVertexData](SetVertexData.md) | 执行 `Resize`、`memcpy`、`UpdateMemorySize` 协同流程。 | +| [GetVertexData](GetVertexData.md) | 返回 `m_vertexData` 暴露的首地址。 | +| [GetVertexDataSize](GetVertexDataSize.md) | 返回 `m_vertexData` 当前大小。 | +| [GetVertexCount](GetVertexCount.md) | 返回 `m_vertexCount` 当前值。 | +| [GetVertexStride](GetVertexStride.md) | 返回 `m_vertexStride` 当前值。 | +| [GetVertexAttributes](GetVertexAttributes.md) | 返回 `m_attributes` 当前值。 | +| [SetIndexData](SetIndexData.md) | 执行 `Resize`、`memcpy`、`UpdateMemorySize` 协同流程。 | +| [GetIndexData](GetIndexData.md) | 返回 `m_indexData` 暴露的首地址。 | +| [GetIndexDataSize](GetIndexDataSize.md) | 返回 `m_indexData` 当前大小。 | +| [GetIndexCount](GetIndexCount.md) | 返回 `m_indexCount` 当前值。 | +| [IsUse32BitIndex](IsUse32BitIndex.md) | 返回 `m_use32BitIndex` 当前值。 | +| [SetBounds](SetBounds.md) | 写入 `m_bounds`。 | +| [GetBounds](GetBounds.md) | 返回 `m_bounds` 当前值。 | +| [AddSection](AddSection.md) | 更新 `m_sections`。 | +| [AddMaterial](AddMaterial.md) | 更新 `m_materials`。 | +| [AddTexture](AddTexture.md) | 更新 `m_textures`。 | +| [GetSections](GetSections.md) | 返回 `m_sections` 当前值。 | +| [GetMaterials](GetMaterials.md) | 返回 `m_materials` 当前值。 | +| [GetTextures](GetTextures.md) | 返回 `m_textures` 当前值。 | +| [GetMaterial](GetMaterial.md) | 执行该公开方法对应的当前实现。 | ## 相关文档 diff --git a/docs/api/XCEngine/Resources/Mesh/Mesh/Release.md b/docs/api/XCEngine/Resources/Mesh/Mesh/Release.md index d815a037..14aa9d6c 100644 --- a/docs/api/XCEngine/Resources/Mesh/Mesh/Release.md +++ b/docs/api/XCEngine/Resources/Mesh/Mesh/Release.md @@ -1,30 +1,26 @@ # Mesh::Release -释放引用或底层资源。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/Mesh.h` + +## 签名 ```cpp void Release() override; ``` -该方法声明于 `XCEngine/Resources/Mesh/Mesh.h`，当前页面用于固定 `Mesh` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `Clear` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Mesh object; - // 根据上下文补齐参数后调用 Mesh::Release(...)。 - (void)object; -} -``` +- 会更新 `m_vertexCount`、`m_vertexStride`、`m_attributes`、`m_indexCount`。 +- 当前实现会调用 `Clear`。 ## 相关文档 -- [返回类总览](Mesh.md) -- [返回模块目录](../Mesh.md) +- [Mesh](Mesh.md) diff --git a/docs/api/XCEngine/Resources/Mesh/Mesh/SetBounds.md b/docs/api/XCEngine/Resources/Mesh/Mesh/SetBounds.md index 3f29eb79..21555134 100644 --- a/docs/api/XCEngine/Resources/Mesh/Mesh/SetBounds.md +++ b/docs/api/XCEngine/Resources/Mesh/Mesh/SetBounds.md @@ -1,31 +1,26 @@ # Mesh::SetBounds -设置相关状态或配置。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/Mesh.h` + +## 签名 ```cpp void SetBounds(const Math::Bounds& bounds); ``` -该方法声明于 `XCEngine/Resources/Mesh/Mesh.h`，当前页面用于固定 `Mesh` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `bounds` - 参数语义详见头文件声明。 +更新 `m_bounds`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Mesh object; - // 根据上下文补齐参数后调用 Mesh::SetBounds(...)。 - (void)object; -} -``` +- 会更新 `m_bounds`。 ## 相关文档 -- [返回类总览](Mesh.md) -- [返回模块目录](../Mesh.md) +- [Mesh](Mesh.md) +- [GetBounds](GetBounds.md) diff --git a/docs/api/XCEngine/Resources/Mesh/Mesh/SetIndexData.md b/docs/api/XCEngine/Resources/Mesh/Mesh/SetIndexData.md index 4671585b..b0211b79 100644 --- a/docs/api/XCEngine/Resources/Mesh/Mesh/SetIndexData.md +++ b/docs/api/XCEngine/Resources/Mesh/Mesh/SetIndexData.md @@ -1,34 +1,28 @@ # Mesh::SetIndexData -设置相关状态或配置。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/Mesh.h` + +## 签名 ```cpp void SetIndexData(const void* data, size_t size, Core::uint32 indexCount, bool use32Bit); ``` -该方法声明于 `XCEngine/Resources/Mesh/Mesh.h`，当前页面用于固定 `Mesh` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `data` - 参数语义详见头文件声明。 -- `size` - 参数语义详见头文件声明。 -- `indexCount` - 参数语义详见头文件声明。 -- `use32Bit` - 参数语义详见头文件声明。 +执行 `Resize`、`memcpy`、`UpdateMemorySize` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Mesh object; - // 根据上下文补齐参数后调用 Mesh::SetIndexData(...)。 - (void)object; -} -``` +- 会更新 `m_indexCount`、`m_use32BitIndex`、`m_indexData`。 +- 当前实现会调用 `Resize`、`memcpy`、`UpdateMemorySize`。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](Mesh.md) -- [返回模块目录](../Mesh.md) +- [Mesh](Mesh.md) +- [GetIndexData](GetIndexData.md) diff --git a/docs/api/XCEngine/Resources/Mesh/Mesh/SetVertexData.md b/docs/api/XCEngine/Resources/Mesh/Mesh/SetVertexData.md index bc42ce60..a8021512 100644 --- a/docs/api/XCEngine/Resources/Mesh/Mesh/SetVertexData.md +++ b/docs/api/XCEngine/Resources/Mesh/Mesh/SetVertexData.md @@ -1,35 +1,28 @@ # Mesh::SetVertexData -设置相关状态或配置。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/Mesh.h` + +## 签名 ```cpp void SetVertexData(const void* data, size_t size, Core::uint32 vertexCount, Core::uint32 vertexStride, VertexAttribute attributes); ``` -该方法声明于 `XCEngine/Resources/Mesh/Mesh.h`，当前页面用于固定 `Mesh` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `data` - 参数语义详见头文件声明。 -- `size` - 参数语义详见头文件声明。 -- `vertexCount` - 参数语义详见头文件声明。 -- `vertexStride` - 参数语义详见头文件声明。 -- `attributes` - 参数语义详见头文件声明。 +执行 `Resize`、`memcpy`、`UpdateMemorySize` 协同流程。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Mesh object; - // 根据上下文补齐参数后调用 Mesh::SetVertexData(...)。 - (void)object; -} -``` +- 会更新 `m_vertexCount`、`m_vertexStride`、`m_attributes`、`m_vertexData`。 +- 当前实现会调用 `Resize`、`memcpy`、`UpdateMemorySize`。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](Mesh.md) -- [返回模块目录](../Mesh.md) +- [Mesh](Mesh.md) +- [GetVertexData](GetVertexData.md) diff --git a/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/AddImportFlag.md b/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/AddImportFlag.md index d87ba1c3..d705043a 100644 --- a/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/AddImportFlag.md +++ b/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/AddImportFlag.md @@ -1,31 +1,25 @@ # MeshImportSettings::AddImportFlag -添加元素或建立关联。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/MeshImportSettings.h` + +## 签名 ```cpp void AddImportFlag(MeshImportFlags flag); ``` -该方法声明于 `XCEngine/Resources/Mesh/MeshImportSettings.h`，当前页面用于固定 `MeshImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `flag` - 参数语义详见头文件声明。 +更新 `m_importFlags`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::MeshImportSettings object; - // 根据上下文补齐参数后调用 MeshImportSettings::AddImportFlag(...)。 - (void)object; -} -``` +- 会更新 `m_importFlags`。 ## 相关文档 -- [返回类总览](MeshImportSettings.md) -- [返回模块目录](../Mesh.md) +- [MeshImportSettings](MeshImportSettings.md) diff --git a/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/Clone.md b/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/Clone.md index 717ea0d6..235aecf3 100644 --- a/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/Clone.md +++ b/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/Clone.md @@ -1,30 +1,25 @@ # MeshImportSettings::Clone -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/MeshImportSettings.h` + +## 签名 ```cpp Core::UniqueRef Clone() const override; ``` -该方法声明于 `XCEngine/Resources/Mesh/MeshImportSettings.h`，当前页面用于固定 `MeshImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `Clone` 对应的公开操作。 -**返回：** `Core::UniqueRef` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::MeshImportSettings object; - // 根据上下文补齐参数后调用 MeshImportSettings::Clone(...)。 - (void)object; -} -``` +- 具体定义位于 `engine/src/Resources/Mesh/MeshImportSettings.cpp`。 ## 相关文档 -- [返回类总览](MeshImportSettings.md) -- [返回模块目录](../Mesh.md) +- [MeshImportSettings](MeshImportSettings.md) diff --git a/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/Constructor.md b/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/Constructor.md index 32328e01..3fd5cf6b 100644 --- a/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/Constructor.md +++ b/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/Constructor.md @@ -1,28 +1,25 @@ # MeshImportSettings::MeshImportSettings() -构造对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/MeshImportSettings.h` + +## 签名 ```cpp MeshImportSettings(); ``` -该方法声明于 `XCEngine/Resources/Mesh/MeshImportSettings.h`，当前页面用于固定 `MeshImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +构造 `MeshImportSettings` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::MeshImportSettings object; -} -``` +- 当前为默认构造实现。 ## 相关文档 -- [返回类总览](MeshImportSettings.md) -- [返回模块目录](../Mesh.md) +- [MeshImportSettings](MeshImportSettings.md) diff --git a/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/Destructor.md b/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/Destructor.md index 1bcb05cd..f48f3f87 100644 --- a/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/Destructor.md +++ b/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/Destructor.md @@ -1,29 +1,25 @@ # MeshImportSettings::~MeshImportSettings() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/MeshImportSettings.h` + +## 签名 ```cpp virtual ~MeshImportSettings() override; ``` -该方法声明于 `XCEngine/Resources/Mesh/MeshImportSettings.h`，当前页面用于固定 `MeshImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +销毁 `MeshImportSettings` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::MeshImportSettings object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 当前为默认析构实现。 ## 相关文档 -- [返回类总览](MeshImportSettings.md) -- [返回模块目录](../Mesh.md) +- [MeshImportSettings](MeshImportSettings.md) diff --git a/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/GetAxisConversion.md b/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/GetAxisConversion.md index c81d4eca..e2e5afc3 100644 --- a/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/GetAxisConversion.md +++ b/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/GetAxisConversion.md @@ -1,30 +1,26 @@ # MeshImportSettings::GetAxisConversion -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/MeshImportSettings.h` + +## 签名 ```cpp bool GetAxisConversion() const; ``` -该方法声明于 `XCEngine/Resources/Mesh/MeshImportSettings.h`，当前页面用于固定 `MeshImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_axisConversion` 当前值。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::MeshImportSettings object; - // 根据上下文补齐参数后调用 MeshImportSettings::GetAxisConversion(...)。 - (void)object; -} -``` +- 返回 `m_axisConversion` 当前值。 ## 相关文档 -- [返回类总览](MeshImportSettings.md) -- [返回模块目录](../Mesh.md) +- [MeshImportSettings](MeshImportSettings.md) +- [SetAxisConversion](SetAxisConversion.md) diff --git a/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/GetImportFlags.md b/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/GetImportFlags.md index f45b718e..2d9a11d1 100644 --- a/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/GetImportFlags.md +++ b/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/GetImportFlags.md @@ -1,30 +1,26 @@ # MeshImportSettings::GetImportFlags -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/MeshImportSettings.h` + +## 签名 ```cpp MeshImportFlags GetImportFlags() const; ``` -该方法声明于 `XCEngine/Resources/Mesh/MeshImportSettings.h`，当前页面用于固定 `MeshImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_importFlags` 当前值。 -**返回：** `MeshImportFlags` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::MeshImportSettings object; - // 根据上下文补齐参数后调用 MeshImportSettings::GetImportFlags(...)。 - (void)object; -} -``` +- 返回 `m_importFlags` 当前值。 ## 相关文档 -- [返回类总览](MeshImportSettings.md) -- [返回模块目录](../Mesh.md) +- [MeshImportSettings](MeshImportSettings.md) +- [SetImportFlags](SetImportFlags.md) diff --git a/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/GetImportScale.md b/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/GetImportScale.md index 20efa749..fdc795d2 100644 --- a/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/GetImportScale.md +++ b/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/GetImportScale.md @@ -1,30 +1,26 @@ # MeshImportSettings::GetImportScale -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/MeshImportSettings.h` + +## 签名 ```cpp float GetImportScale() const; ``` -该方法声明于 `XCEngine/Resources/Mesh/MeshImportSettings.h`，当前页面用于固定 `MeshImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_importScale` 当前值。 -**返回：** `float` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::MeshImportSettings object; - // 根据上下文补齐参数后调用 MeshImportSettings::GetImportScale(...)。 - (void)object; -} -``` +- 返回 `m_importScale` 当前值。 ## 相关文档 -- [返回类总览](MeshImportSettings.md) -- [返回模块目录](../Mesh.md) +- [MeshImportSettings](MeshImportSettings.md) +- [SetImportScale](SetImportScale.md) diff --git a/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/GetMergeMeshes.md b/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/GetMergeMeshes.md index 7d572957..1018618b 100644 --- a/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/GetMergeMeshes.md +++ b/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/GetMergeMeshes.md @@ -1,30 +1,26 @@ # MeshImportSettings::GetMergeMeshes -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/MeshImportSettings.h` + +## 签名 ```cpp bool GetMergeMeshes() const; ``` -该方法声明于 `XCEngine/Resources/Mesh/MeshImportSettings.h`，当前页面用于固定 `MeshImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_mergeMeshes` 当前值。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::MeshImportSettings object; - // 根据上下文补齐参数后调用 MeshImportSettings::GetMergeMeshes(...)。 - (void)object; -} -``` +- 返回 `m_mergeMeshes` 当前值。 ## 相关文档 -- [返回类总览](MeshImportSettings.md) -- [返回模块目录](../Mesh.md) +- [MeshImportSettings](MeshImportSettings.md) +- [SetMergeMeshes](SetMergeMeshes.md) diff --git a/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/GetOffset.md b/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/GetOffset.md index b30f242a..acae026c 100644 --- a/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/GetOffset.md +++ b/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/GetOffset.md @@ -1,30 +1,26 @@ # MeshImportSettings::GetOffset -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/MeshImportSettings.h` + +## 签名 ```cpp const Math::Vector3& GetOffset() const; ``` -该方法声明于 `XCEngine/Resources/Mesh/MeshImportSettings.h`，当前页面用于固定 `MeshImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_offset` 当前值。 -**返回：** `const Math::Vector3&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::MeshImportSettings object; - // 根据上下文补齐参数后调用 MeshImportSettings::GetOffset(...)。 - (void)object; -} -``` +- 返回 `m_offset` 当前值。 ## 相关文档 -- [返回类总览](MeshImportSettings.md) -- [返回模块目录](../Mesh.md) +- [MeshImportSettings](MeshImportSettings.md) +- [SetOffset](SetOffset.md) diff --git a/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/GetOptimizeThreshold.md b/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/GetOptimizeThreshold.md index 40997261..2f3c6784 100644 --- a/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/GetOptimizeThreshold.md +++ b/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/GetOptimizeThreshold.md @@ -1,30 +1,26 @@ # MeshImportSettings::GetOptimizeThreshold -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/MeshImportSettings.h` + +## 签名 ```cpp float GetOptimizeThreshold() const; ``` -该方法声明于 `XCEngine/Resources/Mesh/MeshImportSettings.h`，当前页面用于固定 `MeshImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_optimizeThreshold` 当前值。 -**返回：** `float` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::MeshImportSettings object; - // 根据上下文补齐参数后调用 MeshImportSettings::GetOptimizeThreshold(...)。 - (void)object; -} -``` +- 返回 `m_optimizeThreshold` 当前值。 ## 相关文档 -- [返回类总览](MeshImportSettings.md) -- [返回模块目录](../Mesh.md) +- [MeshImportSettings](MeshImportSettings.md) +- [SetOptimizeThreshold](SetOptimizeThreshold.md) diff --git a/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/GetScale.md b/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/GetScale.md index ab42fe8a..38f6673d 100644 --- a/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/GetScale.md +++ b/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/GetScale.md @@ -1,30 +1,26 @@ # MeshImportSettings::GetScale -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/MeshImportSettings.h` + +## 签名 ```cpp float GetScale() const; ``` -该方法声明于 `XCEngine/Resources/Mesh/MeshImportSettings.h`，当前页面用于固定 `MeshImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_scale` 当前值。 -**返回：** `float` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::MeshImportSettings object; - // 根据上下文补齐参数后调用 MeshImportSettings::GetScale(...)。 - (void)object; -} -``` +- 返回 `m_scale` 当前值。 ## 相关文档 -- [返回类总览](MeshImportSettings.md) -- [返回模块目录](../Mesh.md) +- [MeshImportSettings](MeshImportSettings.md) +- [SetScale](SetScale.md) diff --git a/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/GetThreshold.md b/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/GetThreshold.md index 871c3fa0..c0631e68 100644 --- a/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/GetThreshold.md +++ b/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/GetThreshold.md @@ -1,30 +1,26 @@ # MeshImportSettings::GetThreshold -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/MeshImportSettings.h` + +## 签名 ```cpp float GetThreshold() const; ``` -该方法声明于 `XCEngine/Resources/Mesh/MeshImportSettings.h`，当前页面用于固定 `MeshImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_threshold` 当前值。 -**返回：** `float` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::MeshImportSettings object; - // 根据上下文补齐参数后调用 MeshImportSettings::GetThreshold(...)。 - (void)object; -} -``` +- 返回 `m_threshold` 当前值。 ## 相关文档 -- [返回类总览](MeshImportSettings.md) -- [返回模块目录](../Mesh.md) +- [MeshImportSettings](MeshImportSettings.md) +- [SetThreshold](SetThreshold.md) diff --git a/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/HasImportFlag.md b/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/HasImportFlag.md index 2d955241..2be40ae2 100644 --- a/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/HasImportFlag.md +++ b/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/HasImportFlag.md @@ -1,31 +1,25 @@ # MeshImportSettings::HasImportFlag -判断是否具备指定状态或能力。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/MeshImportSettings.h` + +## 签名 ```cpp bool HasImportFlag(MeshImportFlags flag) const; ``` -该方法声明于 `XCEngine/Resources/Mesh/MeshImportSettings.h`，当前页面用于固定 `MeshImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `flag` - 参数语义详见头文件声明。 +返回 `(static_cast(m_importFlags) & static_cast(flag)) != 0`。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::MeshImportSettings object; - // 根据上下文补齐参数后调用 MeshImportSettings::HasImportFlag(...)。 - (void)object; -} -``` +- 返回 `(static_cast(m_importFlags) & static_cast(flag)) != 0`。 ## 相关文档 -- [返回类总览](MeshImportSettings.md) -- [返回模块目录](../Mesh.md) +- [MeshImportSettings](MeshImportSettings.md) diff --git a/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/LoadFromJSON.md b/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/LoadFromJSON.md index 80bbb06f..53e76601 100644 --- a/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/LoadFromJSON.md +++ b/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/LoadFromJSON.md @@ -1,31 +1,27 @@ # MeshImportSettings::LoadFromJSON -加载资源或数据。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/MeshImportSettings.h` + +## 签名 ```cpp bool LoadFromJSON(const Containers::String& json) override; ``` -该方法声明于 `XCEngine/Resources/Mesh/MeshImportSettings.h`，当前页面用于固定 `MeshImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `json` - 参数语义详见头文件声明。 +更新 `m_importFlags`。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::MeshImportSettings object; - // 根据上下文补齐参数后调用 MeshImportSettings::LoadFromJSON(...)。 - (void)object; -} -``` +- 会更新 `m_importFlags`。 +- 当前实现会调用 `Empty`、`jsonText`、`CStr`、`TryParseUInt32`、`TryParseFloat`。 +- 包含条件分支，并可能提前返回。 ## 相关文档 -- [返回类总览](MeshImportSettings.md) -- [返回模块目录](../Mesh.md) +- [MeshImportSettings](MeshImportSettings.md) diff --git a/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/MeshImportSettings.md b/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/MeshImportSettings.md index 92782029..83c89c92 100644 --- a/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/MeshImportSettings.md +++ b/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/MeshImportSettings.md @@ -6,47 +6,54 @@ **头文件**: `XCEngine/Resources/Mesh/MeshImportSettings.h` -**描述**: 定义 `XCEngine/Resources/Mesh` 子目录中的 `MeshImportSettings` public API。 +**描述**: 网格导入设置对象，控制导入 flag、缩放 / 偏移、坐标轴转换、合并和优化阈值等行为。 ## 概述 -`MeshImportSettings.h` 是 `XCEngine/Resources/Mesh` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。 +`MeshImportSettings` 是网格导入阶段的配置容器。它继承自 `ImportSettings`，当前头文件暴露的参数主要集中在： + +- `MeshImportFlags` + - 控制是否翻转 UV、重建 normals / tangents、导入材质 / 动画 / skinning 等 +- 几何修正参数 + - 缩放、偏移、坐标轴转换 +- 导入后处理参数 + - merge、optimize threshold、import scale、threshold ## 声明概览 | 声明 | 类型 | 说明 | |------|------|------| -| `MeshImportFlags` | `enum class` | 头文件中的公开声明。 | -| `MeshImportSettings` | `class` | 继承自 `ImportSettings` 的公开声明。 | +| `MeshImportFlags` | `enum class` | 网格导入行为标记。 | +| `MeshImportSettings` | `class` | 网格导入参数对象。 | ## 公共方法 | 方法 | 描述 | |------|------| -| [MeshImportSettings()](Constructor.md) | 构造对象。 | -| [~MeshImportSettings()](Destructor.md) | 销毁对象并释放相关资源。 | -| [Clone](Clone.md) | 公开方法，详见头文件声明。 | -| [LoadFromJSON](LoadFromJSON.md) | 加载资源或数据。 | -| [SaveToJSON](SaveToJSON.md) | 公开方法，详见头文件声明。 | -| [SetImportFlags](SetImportFlags.md) | 设置相关状态或配置。 | -| [GetImportFlags](GetImportFlags.md) | 获取相关状态或对象。 | -| [AddImportFlag](AddImportFlag.md) | 添加元素或建立关联。 | -| [RemoveImportFlag](RemoveImportFlag.md) | 移除元素或解除关联。 | -| [HasImportFlag](HasImportFlag.md) | 判断是否具备指定状态或能力。 | -| [SetScale](SetScale.md) | 设置相关状态或配置。 | -| [GetScale](GetScale.md) | 获取相关状态或对象。 | -| [SetOffset](SetOffset.md) | 设置相关状态或配置。 | -| [GetOffset](GetOffset.md) | 获取相关状态或对象。 | -| [SetAxisConversion](SetAxisConversion.md) | 设置相关状态或配置。 | -| [GetAxisConversion](GetAxisConversion.md) | 获取相关状态或对象。 | -| [SetMergeMeshes](SetMergeMeshes.md) | 设置相关状态或配置。 | -| [GetMergeMeshes](GetMergeMeshes.md) | 获取相关状态或对象。 | -| [SetOptimizeThreshold](SetOptimizeThreshold.md) | 设置相关状态或配置。 | -| [GetOptimizeThreshold](GetOptimizeThreshold.md) | 获取相关状态或对象。 | -| [SetImportScale](SetImportScale.md) | 设置相关状态或配置。 | -| [GetImportScale](GetImportScale.md) | 获取相关状态或对象。 | -| [SetThreshold](SetThreshold.md) | 设置相关状态或配置。 | -| [GetThreshold](GetThreshold.md) | 获取相关状态或对象。 | +| [MeshImportSettings()](Constructor.md) | 构造 `MeshImportSettings` 实例。 | +| [~MeshImportSettings()](Destructor.md) | 销毁 `MeshImportSettings` 实例。 | +| [Clone](Clone.md) | 执行 `MeshImportSettings(...)` 相关流程。 | +| [LoadFromJSON](LoadFromJSON.md) | 更新 `m_importFlags`。 | +| [SaveToJSON](SaveToJSON.md) | 返回 `Containers::String(text.c_str())`。 | +| [SetImportFlags](SetImportFlags.md) | 更新 `m_importFlags`。 | +| [GetImportFlags](GetImportFlags.md) | 返回 `m_importFlags` 当前值。 | +| [AddImportFlag](AddImportFlag.md) | 更新 `m_importFlags`。 | +| [RemoveImportFlag](RemoveImportFlag.md) | 更新 `m_importFlags`。 | +| [HasImportFlag](HasImportFlag.md) | 返回 `(static_cast(m_importFlags) & static_cast(flag)) != 0`。 | +| [SetScale](SetScale.md) | 更新 `m_scale`。 | +| [GetScale](GetScale.md) | 返回 `m_scale` 当前值。 | +| [SetOffset](SetOffset.md) | 更新 `m_offset`。 | +| [GetOffset](GetOffset.md) | 返回 `m_offset` 当前值。 | +| [SetAxisConversion](SetAxisConversion.md) | 更新 `m_axisConversion`。 | +| [GetAxisConversion](GetAxisConversion.md) | 返回 `m_axisConversion` 当前值。 | +| [SetMergeMeshes](SetMergeMeshes.md) | 更新 `m_mergeMeshes`。 | +| [GetMergeMeshes](GetMergeMeshes.md) | 返回 `m_mergeMeshes` 当前值。 | +| [SetOptimizeThreshold](SetOptimizeThreshold.md) | 更新 `m_optimizeThreshold`。 | +| [GetOptimizeThreshold](GetOptimizeThreshold.md) | 返回 `m_optimizeThreshold` 当前值。 | +| [SetImportScale](SetImportScale.md) | 更新 `m_importScale`。 | +| [GetImportScale](GetImportScale.md) | 返回 `m_importScale` 当前值。 | +| [SetThreshold](SetThreshold.md) | 更新 `m_threshold`。 | +| [GetThreshold](GetThreshold.md) | 返回 `m_threshold` 当前值。 | ## 相关文档 diff --git a/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/RemoveImportFlag.md b/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/RemoveImportFlag.md index 85c08b7b..1ed406a4 100644 --- a/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/RemoveImportFlag.md +++ b/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/RemoveImportFlag.md @@ -1,31 +1,25 @@ # MeshImportSettings::RemoveImportFlag -移除元素或解除关联。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/MeshImportSettings.h` + +## 签名 ```cpp void RemoveImportFlag(MeshImportFlags flag); ``` -该方法声明于 `XCEngine/Resources/Mesh/MeshImportSettings.h`，当前页面用于固定 `MeshImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `flag` - 参数语义详见头文件声明。 +更新 `m_importFlags`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::MeshImportSettings object; - // 根据上下文补齐参数后调用 MeshImportSettings::RemoveImportFlag(...)。 - (void)object; -} -``` +- 会更新 `m_importFlags`。 ## 相关文档 -- [返回类总览](MeshImportSettings.md) -- [返回模块目录](../Mesh.md) +- [MeshImportSettings](MeshImportSettings.md) diff --git a/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/SaveToJSON.md b/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/SaveToJSON.md index 3b6a1a6b..ec413ad6 100644 --- a/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/SaveToJSON.md +++ b/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/SaveToJSON.md @@ -1,30 +1,25 @@ # MeshImportSettings::SaveToJSON -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/MeshImportSettings.h` + +## 签名 ```cpp Containers::String SaveToJSON() const override; ``` -该方法声明于 `XCEngine/Resources/Mesh/MeshImportSettings.h`，当前页面用于固定 `MeshImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `SaveToJSON` 对应的公开操作。 -**返回：** `Containers::String` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::MeshImportSettings object; - // 根据上下文补齐参数后调用 MeshImportSettings::SaveToJSON(...)。 - (void)object; -} -``` +- 具体定义位于 `engine/src/Resources/Mesh/MeshImportSettings.cpp`。 ## 相关文档 -- [返回类总览](MeshImportSettings.md) -- [返回模块目录](../Mesh.md) +- [MeshImportSettings](MeshImportSettings.md) diff --git a/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/SetAxisConversion.md b/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/SetAxisConversion.md index afd4faf6..ffbaad07 100644 --- a/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/SetAxisConversion.md +++ b/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/SetAxisConversion.md @@ -1,31 +1,26 @@ # MeshImportSettings::SetAxisConversion -设置相关状态或配置。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/MeshImportSettings.h` + +## 签名 ```cpp void SetAxisConversion(bool convert); ``` -该方法声明于 `XCEngine/Resources/Mesh/MeshImportSettings.h`，当前页面用于固定 `MeshImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `convert` - 参数语义详见头文件声明。 +更新 `m_axisConversion`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::MeshImportSettings object; - // 根据上下文补齐参数后调用 MeshImportSettings::SetAxisConversion(...)。 - (void)object; -} -``` +- 会更新 `m_axisConversion`。 ## 相关文档 -- [返回类总览](MeshImportSettings.md) -- [返回模块目录](../Mesh.md) +- [MeshImportSettings](MeshImportSettings.md) +- [GetAxisConversion](GetAxisConversion.md) diff --git a/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/SetImportFlags.md b/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/SetImportFlags.md index eed72a90..637c95e3 100644 --- a/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/SetImportFlags.md +++ b/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/SetImportFlags.md @@ -1,31 +1,26 @@ # MeshImportSettings::SetImportFlags -设置相关状态或配置。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/MeshImportSettings.h` + +## 签名 ```cpp void SetImportFlags(MeshImportFlags flags); ``` -该方法声明于 `XCEngine/Resources/Mesh/MeshImportSettings.h`，当前页面用于固定 `MeshImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `flags` - 参数语义详见头文件声明。 +更新 `m_importFlags`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::MeshImportSettings object; - // 根据上下文补齐参数后调用 MeshImportSettings::SetImportFlags(...)。 - (void)object; -} -``` +- 会更新 `m_importFlags`。 ## 相关文档 -- [返回类总览](MeshImportSettings.md) -- [返回模块目录](../Mesh.md) +- [MeshImportSettings](MeshImportSettings.md) +- [GetImportFlags](GetImportFlags.md) diff --git a/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/SetImportScale.md b/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/SetImportScale.md index 43d1e5e6..b3b8c8de 100644 --- a/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/SetImportScale.md +++ b/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/SetImportScale.md @@ -1,31 +1,26 @@ # MeshImportSettings::SetImportScale -设置相关状态或配置。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/MeshImportSettings.h` + +## 签名 ```cpp void SetImportScale(float scale); ``` -该方法声明于 `XCEngine/Resources/Mesh/MeshImportSettings.h`，当前页面用于固定 `MeshImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `scale` - 参数语义详见头文件声明。 +更新 `m_importScale`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::MeshImportSettings object; - // 根据上下文补齐参数后调用 MeshImportSettings::SetImportScale(...)。 - (void)object; -} -``` +- 会更新 `m_importScale`。 ## 相关文档 -- [返回类总览](MeshImportSettings.md) -- [返回模块目录](../Mesh.md) +- [MeshImportSettings](MeshImportSettings.md) +- [GetImportScale](GetImportScale.md) diff --git a/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/SetMergeMeshes.md b/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/SetMergeMeshes.md index 5a8d6665..f30f7ba3 100644 --- a/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/SetMergeMeshes.md +++ b/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/SetMergeMeshes.md @@ -1,31 +1,26 @@ # MeshImportSettings::SetMergeMeshes -设置相关状态或配置。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/MeshImportSettings.h` + +## 签名 ```cpp void SetMergeMeshes(bool merge); ``` -该方法声明于 `XCEngine/Resources/Mesh/MeshImportSettings.h`，当前页面用于固定 `MeshImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `merge` - 参数语义详见头文件声明。 +更新 `m_mergeMeshes`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::MeshImportSettings object; - // 根据上下文补齐参数后调用 MeshImportSettings::SetMergeMeshes(...)。 - (void)object; -} -``` +- 会更新 `m_mergeMeshes`。 ## 相关文档 -- [返回类总览](MeshImportSettings.md) -- [返回模块目录](../Mesh.md) +- [MeshImportSettings](MeshImportSettings.md) +- [GetMergeMeshes](GetMergeMeshes.md) diff --git a/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/SetOffset.md b/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/SetOffset.md index c961679a..edae7b65 100644 --- a/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/SetOffset.md +++ b/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/SetOffset.md @@ -1,31 +1,26 @@ # MeshImportSettings::SetOffset -设置相关状态或配置。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/MeshImportSettings.h` + +## 签名 ```cpp void SetOffset(const Math::Vector3& offset); ``` -该方法声明于 `XCEngine/Resources/Mesh/MeshImportSettings.h`，当前页面用于固定 `MeshImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `offset` - 参数语义详见头文件声明。 +更新 `m_offset`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::MeshImportSettings object; - // 根据上下文补齐参数后调用 MeshImportSettings::SetOffset(...)。 - (void)object; -} -``` +- 会更新 `m_offset`。 ## 相关文档 -- [返回类总览](MeshImportSettings.md) -- [返回模块目录](../Mesh.md) +- [MeshImportSettings](MeshImportSettings.md) +- [GetOffset](GetOffset.md) diff --git a/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/SetOptimizeThreshold.md b/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/SetOptimizeThreshold.md index 099427ea..279f0aa6 100644 --- a/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/SetOptimizeThreshold.md +++ b/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/SetOptimizeThreshold.md @@ -1,31 +1,26 @@ # MeshImportSettings::SetOptimizeThreshold -设置相关状态或配置。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/MeshImportSettings.h` + +## 签名 ```cpp void SetOptimizeThreshold(float threshold); ``` -该方法声明于 `XCEngine/Resources/Mesh/MeshImportSettings.h`，当前页面用于固定 `MeshImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `threshold` - 参数语义详见头文件声明。 +更新 `m_optimizeThreshold`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::MeshImportSettings object; - // 根据上下文补齐参数后调用 MeshImportSettings::SetOptimizeThreshold(...)。 - (void)object; -} -``` +- 会更新 `m_optimizeThreshold`。 ## 相关文档 -- [返回类总览](MeshImportSettings.md) -- [返回模块目录](../Mesh.md) +- [MeshImportSettings](MeshImportSettings.md) +- [GetOptimizeThreshold](GetOptimizeThreshold.md) diff --git a/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/SetScale.md b/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/SetScale.md index 672eeb7f..e1d9537c 100644 --- a/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/SetScale.md +++ b/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/SetScale.md @@ -1,31 +1,26 @@ # MeshImportSettings::SetScale -设置相关状态或配置。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/MeshImportSettings.h` + +## 签名 ```cpp void SetScale(float scale); ``` -该方法声明于 `XCEngine/Resources/Mesh/MeshImportSettings.h`，当前页面用于固定 `MeshImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `scale` - 参数语义详见头文件声明。 +更新 `m_scale`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::MeshImportSettings object; - // 根据上下文补齐参数后调用 MeshImportSettings::SetScale(...)。 - (void)object; -} -``` +- 会更新 `m_scale`。 ## 相关文档 -- [返回类总览](MeshImportSettings.md) -- [返回模块目录](../Mesh.md) +- [MeshImportSettings](MeshImportSettings.md) +- [GetScale](GetScale.md) diff --git a/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/SetThreshold.md b/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/SetThreshold.md index 02bc594a..2862382d 100644 --- a/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/SetThreshold.md +++ b/docs/api/XCEngine/Resources/Mesh/MeshImportSettings/SetThreshold.md @@ -1,31 +1,26 @@ # MeshImportSettings::SetThreshold -设置相关状态或配置。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/MeshImportSettings.h` + +## 签名 ```cpp void SetThreshold(float threshold); ``` -该方法声明于 `XCEngine/Resources/Mesh/MeshImportSettings.h`，当前页面用于固定 `MeshImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `threshold` - 参数语义详见头文件声明。 +更新 `m_threshold`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::MeshImportSettings object; - // 根据上下文补齐参数后调用 MeshImportSettings::SetThreshold(...)。 - (void)object; -} -``` +- 会更新 `m_threshold`。 ## 相关文档 -- [返回类总览](MeshImportSettings.md) -- [返回模块目录](../Mesh.md) +- [MeshImportSettings](MeshImportSettings.md) +- [GetThreshold](GetThreshold.md) diff --git a/docs/api/XCEngine/Resources/Mesh/MeshLoader/CanLoad.md b/docs/api/XCEngine/Resources/Mesh/MeshLoader/CanLoad.md index bf182b44..2c4b6330 100644 --- a/docs/api/XCEngine/Resources/Mesh/MeshLoader/CanLoad.md +++ b/docs/api/XCEngine/Resources/Mesh/MeshLoader/CanLoad.md @@ -1,31 +1,26 @@ # MeshLoader::CanLoad -判断当前条件下是否可执行。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/MeshLoader.h` + +## 签名 ```cpp bool CanLoad(const Containers::String& path) const override; ``` -该方法声明于 `XCEngine/Resources/Mesh/MeshLoader.h`，当前页面用于固定 `MeshLoader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `path` - 参数语义详见头文件声明。 +执行 `IsBuiltinMeshPath`、`GetExtension`、`ToLower` 协同流程。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::MeshLoader object; - // 根据上下文补齐参数后调用 MeshLoader::CanLoad(...)。 - (void)object; -} -``` +- 当前实现会调用 `IsBuiltinMeshPath`、`GetExtension`、`ToLower`。 +- 包含条件分支，并可能提前返回。 ## 相关文档 -- [返回类总览](MeshLoader.md) -- [返回模块目录](../Mesh.md) +- [MeshLoader](MeshLoader.md) diff --git a/docs/api/XCEngine/Resources/Mesh/MeshLoader/Constructor.md b/docs/api/XCEngine/Resources/Mesh/MeshLoader/Constructor.md index 76c5907d..87ddd748 100644 --- a/docs/api/XCEngine/Resources/Mesh/MeshLoader/Constructor.md +++ b/docs/api/XCEngine/Resources/Mesh/MeshLoader/Constructor.md @@ -1,28 +1,25 @@ # MeshLoader::MeshLoader() -构造对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/MeshLoader.h` + +## 签名 ```cpp MeshLoader(); ``` -该方法声明于 `XCEngine/Resources/Mesh/MeshLoader.h`，当前页面用于固定 `MeshLoader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +构造 `MeshLoader` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::MeshLoader object; -} -``` +- 当前为默认构造实现。 ## 相关文档 -- [返回类总览](MeshLoader.md) -- [返回模块目录](../Mesh.md) +- [MeshLoader](MeshLoader.md) diff --git a/docs/api/XCEngine/Resources/Mesh/MeshLoader/Destructor.md b/docs/api/XCEngine/Resources/Mesh/MeshLoader/Destructor.md index 9402e8a2..897fe038 100644 --- a/docs/api/XCEngine/Resources/Mesh/MeshLoader/Destructor.md +++ b/docs/api/XCEngine/Resources/Mesh/MeshLoader/Destructor.md @@ -1,29 +1,25 @@ # MeshLoader::~MeshLoader() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/MeshLoader.h` + +## 签名 ```cpp virtual ~MeshLoader() override; ``` -该方法声明于 `XCEngine/Resources/Mesh/MeshLoader.h`，当前页面用于固定 `MeshLoader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +销毁 `MeshLoader` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::MeshLoader object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 当前为默认析构实现。 ## 相关文档 -- [返回类总览](MeshLoader.md) -- [返回模块目录](../Mesh.md) +- [MeshLoader](MeshLoader.md) diff --git a/docs/api/XCEngine/Resources/Mesh/MeshLoader/GetDefaultSettings.md b/docs/api/XCEngine/Resources/Mesh/MeshLoader/GetDefaultSettings.md index 56bf8fd6..52b7da70 100644 --- a/docs/api/XCEngine/Resources/Mesh/MeshLoader/GetDefaultSettings.md +++ b/docs/api/XCEngine/Resources/Mesh/MeshLoader/GetDefaultSettings.md @@ -1,30 +1,25 @@ # MeshLoader::GetDefaultSettings -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/MeshLoader.h` + +## 签名 ```cpp ImportSettings* GetDefaultSettings() const override; ``` -该方法声明于 `XCEngine/Resources/Mesh/MeshLoader.h`，当前页面用于固定 `MeshLoader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `MeshImportSettings(...)` 相关流程。 -**返回：** `ImportSettings*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::MeshLoader object; - // 根据上下文补齐参数后调用 MeshLoader::GetDefaultSettings(...)。 - (void)object; -} -``` +- 当前实现会调用 `MeshImportSettings`。 ## 相关文档 -- [返回类总览](MeshLoader.md) -- [返回模块目录](../Mesh.md) +- [MeshLoader](MeshLoader.md) diff --git a/docs/api/XCEngine/Resources/Mesh/MeshLoader/GetResourceType.md b/docs/api/XCEngine/Resources/Mesh/MeshLoader/GetResourceType.md index 7b315e6c..b3fe1e7f 100644 --- a/docs/api/XCEngine/Resources/Mesh/MeshLoader/GetResourceType.md +++ b/docs/api/XCEngine/Resources/Mesh/MeshLoader/GetResourceType.md @@ -1,30 +1,25 @@ # MeshLoader::GetResourceType -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/MeshLoader.h` + +## 签名 ```cpp ResourceType GetResourceType() const override; ``` -该方法声明于 `XCEngine/Resources/Mesh/MeshLoader.h`，当前页面用于固定 `MeshLoader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `ResourceType::Mesh`。 -**返回：** `ResourceType` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::MeshLoader object; - // 根据上下文补齐参数后调用 MeshLoader::GetResourceType(...)。 - (void)object; -} -``` +- 返回 `ResourceType::Mesh`。 ## 相关文档 -- [返回类总览](MeshLoader.md) -- [返回模块目录](../Mesh.md) +- [MeshLoader](MeshLoader.md) diff --git a/docs/api/XCEngine/Resources/Mesh/MeshLoader/GetSupportedExtensions.md b/docs/api/XCEngine/Resources/Mesh/MeshLoader/GetSupportedExtensions.md index 55784e79..b917888e 100644 --- a/docs/api/XCEngine/Resources/Mesh/MeshLoader/GetSupportedExtensions.md +++ b/docs/api/XCEngine/Resources/Mesh/MeshLoader/GetSupportedExtensions.md @@ -1,30 +1,25 @@ # MeshLoader::GetSupportedExtensions -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/MeshLoader.h` + +## 签名 ```cpp Containers::Array GetSupportedExtensions() const override; ``` -该方法声明于 `XCEngine/Resources/Mesh/MeshLoader.h`，当前页面用于固定 `MeshLoader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `extensions`。 -**返回：** `Containers::Array` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::MeshLoader object; - // 根据上下文补齐参数后调用 MeshLoader::GetSupportedExtensions(...)。 - (void)object; -} -``` +- 当前实现会调用 `PushBack`、`String`。 ## 相关文档 -- [返回类总览](MeshLoader.md) -- [返回模块目录](../Mesh.md) +- [MeshLoader](MeshLoader.md) diff --git a/docs/api/XCEngine/Resources/Mesh/MeshLoader/Load.md b/docs/api/XCEngine/Resources/Mesh/MeshLoader/Load.md index 568d2110..6fb6dc49 100644 --- a/docs/api/XCEngine/Resources/Mesh/MeshLoader/Load.md +++ b/docs/api/XCEngine/Resources/Mesh/MeshLoader/Load.md @@ -1,32 +1,27 @@ # MeshLoader::Load -加载资源或数据。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Mesh/MeshLoader.h` + +## 签名 ```cpp LoadResult Load(const Containers::String& path, const ImportSettings* settings = nullptr) override; ``` -该方法声明于 `XCEngine/Resources/Mesh/MeshLoader.h`，当前页面用于固定 `MeshLoader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `path` - 参数语义详见头文件声明。 -- `settings` - 参数语义详见头文件声明。 +执行 `IsBuiltinMeshPath`、`CreateBuiltinMeshResource`、`GetExtension` 协同流程。 -**返回：** `LoadResult` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::MeshLoader object; - // 根据上下文补齐参数后调用 MeshLoader::Load(...)。 - (void)object; -} -``` +- 当前实现会调用 `IsBuiltinMeshPath`、`CreateBuiltinMeshResource`、`GetExtension`、`ToLower`、`CanLoad`。 +- 包含条件分支，并可能提前返回。 +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](MeshLoader.md) -- [返回模块目录](../Mesh.md) +- [MeshLoader](MeshLoader.md) diff --git a/docs/api/XCEngine/Resources/Mesh/MeshLoader/MeshLoader.md b/docs/api/XCEngine/Resources/Mesh/MeshLoader/MeshLoader.md index a07e8907..73e30286 100644 --- a/docs/api/XCEngine/Resources/Mesh/MeshLoader/MeshLoader.md +++ b/docs/api/XCEngine/Resources/Mesh/MeshLoader/MeshLoader.md @@ -6,29 +6,35 @@ **头文件**: `XCEngine/Resources/Mesh/MeshLoader.h` -**描述**: 定义 `XCEngine/Resources/Mesh` 子目录中的 `MeshLoader` public API。 +**描述**: 网格资源 loader，负责识别可加载的 mesh 文件、执行导入并返回默认导入设置。 ## 概述 -`MeshLoader.h` 是 `XCEngine/Resources/Mesh` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。 +`MeshLoader` 是 `Mesh` 资源的标准加载入口。它继承自 `IResourceLoader`，当前头文件约定的职责包括： + +- 声明自己负责 `ResourceType::Mesh` +- 给出支持的网格文件扩展名 +- 判断某个路径是否适合由当前 loader 处理 +- 从文件加载 mesh，并结合 `ImportSettings` 生成 `LoadResult` +- 提供默认的 `MeshImportSettings` ## 声明概览 | 声明 | 类型 | 说明 | |------|------|------| -| `MeshLoader` | `class` | 继承自 `IResourceLoader` 的公开声明。 | +| `MeshLoader` | `class` | `Mesh` 资源的加载器。 | ## 公共方法 | 方法 | 描述 | |------|------| -| [MeshLoader()](Constructor.md) | 构造对象。 | -| [~MeshLoader()](Destructor.md) | 销毁对象并释放相关资源。 | -| [GetResourceType](GetResourceType.md) | 获取相关状态或对象。 | -| [GetSupportedExtensions](GetSupportedExtensions.md) | 获取相关状态或对象。 | -| [CanLoad](CanLoad.md) | 判断当前条件下是否可执行。 | -| [Load](Load.md) | 加载资源或数据。 | -| [GetDefaultSettings](GetDefaultSettings.md) | 获取相关状态或对象。 | +| [MeshLoader()](Constructor.md) | 构造 `MeshLoader` 实例。 | +| [~MeshLoader()](Destructor.md) | 销毁 `MeshLoader` 实例。 | +| [GetResourceType](GetResourceType.md) | 返回 `ResourceType::Mesh`。 | +| [GetSupportedExtensions](GetSupportedExtensions.md) | 执行 `PushBack`、`String` 协同流程。 | +| [CanLoad](CanLoad.md) | 执行 `IsBuiltinMeshPath`、`GetExtension`、`ToLower` 协同流程。 | +| [Load](Load.md) | 执行 `IsBuiltinMeshPath`、`CreateBuiltinMeshResource`、`GetExtension` 协同流程。 | +| [GetDefaultSettings](GetDefaultSettings.md) | 返回 `new MeshImportSettings()` 的结果。 | ## 相关文档 diff --git a/docs/api/XCEngine/Resources/Resources.md b/docs/api/XCEngine/Resources/Resources.md index f86b7f26..9526cf18 100644 --- a/docs/api/XCEngine/Resources/Resources.md +++ b/docs/api/XCEngine/Resources/Resources.md @@ -10,6 +10,13 @@ 该目录与 `XCEngine/Resources` 对应的 public headers 保持平行，用于承载唯一的 canonical API 文档入口。 +和 [Core/Asset](../Core/Asset/Asset.md) 的区别是： + +- `Core/Asset` 更偏资源系统基础设施、资产数据库和运行时加载 +- `Resources` 更偏具体资源类型本身，以及少量面向调用方的 builtin 资源入口 + +当前 `Resources` 模块除了具体资源类型外，还包含 [BuiltinResources](BuiltinResources/BuiltinResources.md) 这层虚拟资源命名空间。它把 `builtin://` mesh / material / shader / texture 暴露成引擎内部可直接加载的公共入口，既服务 editor primitive 创建，也服务内建渲染 pass。 + ## 子目录 - [AudioClip](AudioClip/AudioClip.md) @@ -20,6 +27,7 @@ ## 头文件 +- [BuiltinResources](BuiltinResources/BuiltinResources.md) - `BuiltinResources.h` - [Resources](Resources/Resources.md) - `Resources.h` ## 相关文档 diff --git a/docs/api/XCEngine/Resources/Resources/Resources.md b/docs/api/XCEngine/Resources/Resources/Resources.md index e0d442ac..676c0076 100644 --- a/docs/api/XCEngine/Resources/Resources/Resources.md +++ b/docs/api/XCEngine/Resources/Resources/Resources.md @@ -6,11 +6,17 @@ **头文件**: `XCEngine/Resources/Resources.h` -**描述**: 定义 `XCEngine/Resources` 子目录中的 `Resources` public API。 +**描述**: 资源模块 umbrella header，统一汇总资源类型、loader、import settings、资源管理器以及资源 IO 辅助入口。 ## 概述 -`Resources.h` 是 `XCEngine/Resources` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。 +`Resources.h` 本身不是某个单独类或系统的实现，而是 `Resources` 模块的聚合入口。它把常用的资源相关 public API 一次性包含进来，主要包括： + +- Core/Asset 层的 `IResource`、`ResourceHandle`、`ResourceManager`、`ResourceCache`、`AsyncLoader` +- 各类资源对象与 loader，例如 `Texture`、`Mesh`、`Material`、`Shader`、`AudioClip` +- 资源导入设置与若干资源 IO 辅助类型 + +适合想一次引入整个资源子系统 public API 的调用方使用。 ## 相关文档 diff --git a/docs/api/XCEngine/Resources/Shader/Shader.md b/docs/api/XCEngine/Resources/Shader/Shader.md index d78096a1..3a0f9ded 100644 --- a/docs/api/XCEngine/Resources/Shader/Shader.md +++ b/docs/api/XCEngine/Resources/Shader/Shader.md @@ -14,6 +14,7 @@ - [Shader](Shader/Shader.md) - `Shader.h` - [ShaderLoader](ShaderLoader/ShaderLoader.md) - `ShaderLoader.h` +- [ShaderKeywordTypes](ShaderKeywordTypes/ShaderKeywordTypes.md) - `ShaderKeywordTypes.h` ## 相关文档 diff --git a/docs/api/XCEngine/Resources/Shader/Shader/AddAttribute.md b/docs/api/XCEngine/Resources/Shader/Shader/AddAttribute.md index ba554d5f..f4a29131 100644 --- a/docs/api/XCEngine/Resources/Shader/Shader/AddAttribute.md +++ b/docs/api/XCEngine/Resources/Shader/Shader/AddAttribute.md @@ -1,31 +1,38 @@ # Shader::AddAttribute -添加元素或建立关联。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Shader/Shader.h` + +## 签名 ```cpp void AddAttribute(const ShaderAttribute& attribute); ``` -该方法声明于 `XCEngine/Resources/Shader/Shader.h`，当前页面用于固定 `Shader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `attribute` - 参数语义详见头文件声明。 +向传统 vertex attribute 反射数组追加一条记录。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** +- 直接调用 `m_attributes.PushBack(attribute)`。 +- 当前不按 `name` 或 `location` 去重。 +- 不会联动 `property/pass/variant` 元数据，也不会更新 `m_memorySize`。 -```cpp -#include +## 当前边界 -void Example() { - XCEngine::Resources::Shader object; - // 根据上下文补齐参数后调用 Shader::AddAttribute(...)。 - (void)object; -} -``` +- 当前 manifest / artifact 路径不会主动构造 attribute 反射数组。 +- 因此这个接口目前更偏向手工构造、legacy 反射或测试用途。 + +## 测试覆盖 + +`tests/Resources/Shader/test_shader.cpp` 当前验证了追加后可通过 `GetAttributes()` 读回记录。 ## 相关文档 -- [返回类总览](Shader.md) -- [返回模块目录](../Shader.md) +- [Shader](Shader.md) +- [ShaderAttribute](ShaderAttribute.md) +- [GetAttributes](GetAttributes.md) diff --git a/docs/api/XCEngine/Resources/Shader/Shader/AddPass.md b/docs/api/XCEngine/Resources/Shader/Shader/AddPass.md new file mode 100644 index 00000000..bbf2bfae --- /dev/null +++ b/docs/api/XCEngine/Resources/Shader/Shader/AddPass.md @@ -0,0 +1,30 @@ +# Shader::AddPass + +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Shader/Shader.h` + +## 签名 + +```cpp +void AddPass(const ShaderPass& pass); +``` + +## 作用 + +把一个完整的 `ShaderPass` 追加到当前 shader。 + +## 当前实现行为 + +- 直接调用 `m_passes.PushBack(pass)`。 +- 当前实现不会按 `pass.name` 去重，也不会合并已有 pass。 +- 该方法常用于 artifact 反序列化时先创建 pass 外壳，再继续补 tag / resource / variant。 + +## 相关文档 + +- [Shader](Shader.md) +- [ClearPasses](ClearPasses.md) +- [GetPassCount](GetPassCount.md) +- [GetPasses](GetPasses.md) diff --git a/docs/api/XCEngine/Resources/Shader/Shader/AddPassKeywordDeclaration.md b/docs/api/XCEngine/Resources/Shader/Shader/AddPassKeywordDeclaration.md new file mode 100644 index 00000000..8397f067 --- /dev/null +++ b/docs/api/XCEngine/Resources/Shader/Shader/AddPassKeywordDeclaration.md @@ -0,0 +1,37 @@ +# Shader::AddPassKeywordDeclaration + +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Shader/Shader.h` + +## 签名 + +```cpp +void AddPassKeywordDeclaration( + const Containers::String& passName, + const ShaderKeywordDeclaration& declaration); +``` + +## 作用 + +为指定 pass 追加一条 keyword 声明；若 pass 不存在，则先创建。 + +## 当前实现行为 + +- 先通过 `GetOrCreatePass(passName)` 获取目标 pass。 +- 然后直接对 `pass.keywordDeclarations` 执行 `PushBack(declaration)`。 +- 当前实现不做去重，也不会自动归一化 `options`。 + +## 当前语义 + +- 这条 API 写入的是 pass 级声明，不是材质当前启用的 keyword 集合。 +- [PassDeclaresKeyword](PassDeclaresKeyword.md) / [DeclaresKeyword](DeclaresKeyword.md) 之后会在读取侧按 option token 做匹配。 + +## 相关文档 + +- [Shader](Shader.md) +- [PassDeclaresKeyword](PassDeclaresKeyword.md) +- [DeclaresKeyword](DeclaresKeyword.md) +- [ShaderKeywordTypes](../ShaderKeywordTypes/ShaderKeywordTypes.md) diff --git a/docs/api/XCEngine/Resources/Shader/Shader/AddPassResourceBinding.md b/docs/api/XCEngine/Resources/Shader/Shader/AddPassResourceBinding.md new file mode 100644 index 00000000..ce0e5437 --- /dev/null +++ b/docs/api/XCEngine/Resources/Shader/Shader/AddPassResourceBinding.md @@ -0,0 +1,36 @@ +# Shader::AddPassResourceBinding + +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Shader/Shader.h` + +## 签名 + +```cpp +void AddPassResourceBinding( + const Containers::String& passName, + const ShaderResourceBindingDesc& binding); +``` + +## 作用 + +向指定 pass 注册一个资源绑定描述；若同名 binding 已存在，则覆盖。 + +## 当前实现行为 + +- 先通过 `GetOrCreatePass(passName)` 取得目标 pass。 +- 以 `binding.name` 为键在线性遍历 `pass.resources` 中查找。 +- 找到同名 binding 时，直接整体覆盖旧条目。 +- 未找到时，调用 `pass.resources.PushBack(binding)` 追加。 + +## 测试覆盖 + +`tests/Resources/Shader/test_shader.cpp` 和 `tests/Resources/Shader/test_shader_loader.cpp` 当前都验证了 pass resource binding 可被写入并按名称取回。 + +## 相关文档 + +- [Shader](Shader.md) +- [FindPassResourceBinding](FindPassResourceBinding.md) +- [FindPass](FindPass.md) diff --git a/docs/api/XCEngine/Resources/Shader/Shader/AddPassVariant.md b/docs/api/XCEngine/Resources/Shader/Shader/AddPassVariant.md new file mode 100644 index 00000000..197cc97d --- /dev/null +++ b/docs/api/XCEngine/Resources/Shader/Shader/AddPassVariant.md @@ -0,0 +1,38 @@ +# Shader::AddPassVariant + +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Shader/Shader.h` + +## 签名 + +```cpp +void AddPassVariant( + const Containers::String& passName, + const ShaderStageVariant& variant); +``` + +## 作用 + +向指定 pass 追加一个 stage variant；若 pass 不存在，则先创建。 + +## 当前实现行为 + +- 先调用私有 helper `GetOrCreatePass(passName)`。 +- 先把传入 `variant.requiredKeywords` 做 `NormalizeShaderKeywordSetInPlace(...)` 归一化。 +- 然后对该 pass 的 `variants` 调用 `PushBack(normalizedVariant)`。 +- 当前实现不会按 `stage`、`backend` 或 `language` 去重；同一 pass 下可以存在多个同 stage variant。 +- `FindVariant(...)` 之后会负责在读取侧做“精确 backend 优先，`Generic` 兜底 + required keyword 更多者优先”的选择。 + +## 测试覆盖 + +`tests/Resources/Shader/test_shader.cpp` 当前验证了 backend-specific variant 命中和 `Generic` fallback。 +`tests/Resources/Shader/test_shader_loader.cpp` 当前还验证了 manifest / builtin shader 加载后可按 pass、stage、backend 取回 variant。 + +## 相关文档 + +- [Shader](Shader.md) +- [FindVariant](FindVariant.md) +- [FindPass](FindPass.md) diff --git a/docs/api/XCEngine/Resources/Shader/Shader/AddProperty.md b/docs/api/XCEngine/Resources/Shader/Shader/AddProperty.md new file mode 100644 index 00000000..d7498710 --- /dev/null +++ b/docs/api/XCEngine/Resources/Shader/Shader/AddProperty.md @@ -0,0 +1,35 @@ +# Shader::AddProperty + +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Shader/Shader.h` + +## 签名 + +```cpp +void AddProperty(const ShaderPropertyDesc& property); +``` + +## 作用 + +向 `m_properties` 写入一个 shader property 描述；若同名 property 已存在，则就地覆盖。 + +## 当前实现行为 + +- 以 `property.name` 作为唯一键做线性查找。 +- 找到同名项时，直接用新的 `property` 覆盖旧值，并保持原有数组位置不变。 +- 未找到同名项时，调用 `m_properties.PushBack(property)` 追加到末尾。 +- 该方法只更新 property 列表，不会联动 pass、variant 或 legacy 单 stage 字段。 + +## 测试覆盖 + +`tests/Resources/Shader/test_shader.cpp` 当前验证了 property 可被存储并通过 `FindProperty(...)` 取回。 +`tests/Resources/Shader/test_shader_loader.cpp` 当前还通过 manifest / artifact 加载路径间接验证了 property 写入行为。 + +## 相关文档 + +- [Shader](Shader.md) +- [GetProperties](GetProperties.md) +- [FindProperty](FindProperty.md) diff --git a/docs/api/XCEngine/Resources/Shader/Shader/AddUniform.md b/docs/api/XCEngine/Resources/Shader/Shader/AddUniform.md index fed33b61..fe1cb613 100644 --- a/docs/api/XCEngine/Resources/Shader/Shader/AddUniform.md +++ b/docs/api/XCEngine/Resources/Shader/Shader/AddUniform.md @@ -1,31 +1,38 @@ # Shader::AddUniform -添加元素或建立关联。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Shader/Shader.h` + +## 签名 ```cpp void AddUniform(const ShaderUniform& uniform); ``` -该方法声明于 `XCEngine/Resources/Shader/Shader.h`，当前页面用于固定 `Shader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `uniform` - 参数语义详见头文件声明。 +向传统 uniform 反射数组追加一条记录。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** +- 直接调用 `m_uniforms.PushBack(uniform)`。 +- 当前不按 `name` 去重，也不覆盖已有同名项。 +- 不会联动 `property/pass/variant` 元数据，也不会更新 `m_memorySize`。 -```cpp -#include +## 当前边界 -void Example() { - XCEngine::Resources::Shader object; - // 根据上下文补齐参数后调用 Shader::AddUniform(...)。 - (void)object; -} -``` +- manifest / artifact 加载路径当前并不主动填充 uniform 反射；主流 shader 元数据路径已经转向 property / pass / resource binding / variant。 +- 因此这个接口目前更偏向手工构造、legacy 反射或测试用途。 + +## 测试覆盖 + +`tests/Resources/Shader/test_shader.cpp` 当前验证了追加后可通过 `GetUniforms()` 读回记录。 ## 相关文档 -- [返回类总览](Shader.md) -- [返回模块目录](../Shader.md) +- [Shader](Shader.md) +- [ShaderUniform](ShaderUniform.md) +- [GetUniforms](GetUniforms.md) diff --git a/docs/api/XCEngine/Resources/Shader/Shader/ClearPasses.md b/docs/api/XCEngine/Resources/Shader/Shader/ClearPasses.md new file mode 100644 index 00000000..69969d39 --- /dev/null +++ b/docs/api/XCEngine/Resources/Shader/Shader/ClearPasses.md @@ -0,0 +1,30 @@ +# Shader::ClearPasses + +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Shader/Shader.h` + +## 签名 + +```cpp +void ClearPasses(); +``` + +## 作用 + +清空当前 shader 的全部 pass。 + +## 当前实现行为 + +- 直接调用 `m_passes.Clear()`。 +- 会一并移除由 legacy 单 stage 同步逻辑自动创建的 `"Default"` pass。 +- 后续若再次调用 `SetShaderType(...)`、`SetShaderLanguage(...)`、`SetSourceCode(...)` 或 `SetCompiledBinary(...)`，`SyncLegacyVariant()` 会按需要重新创建 legacy pass / variant。 + +## 相关文档 + +- [Shader](Shader.md) +- [AddPass](AddPass.md) +- [GetPassCount](GetPassCount.md) +- [GetPasses](GetPasses.md) diff --git a/docs/api/XCEngine/Resources/Shader/Shader/ClearProperties.md b/docs/api/XCEngine/Resources/Shader/Shader/ClearProperties.md new file mode 100644 index 00000000..3559a4a9 --- /dev/null +++ b/docs/api/XCEngine/Resources/Shader/Shader/ClearProperties.md @@ -0,0 +1,29 @@ +# Shader::ClearProperties + +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Shader/Shader.h` + +## 签名 + +```cpp +void ClearProperties(); +``` + +## 作用 + +清空当前 shader 持有的全部 property 描述。 + +## 当前实现行为 + +- 直接调用 `m_properties.Clear()`。 +- 不影响 `m_passes`、`m_uniforms`、`m_attributes`、`m_sourceCode` 或 `m_compiledBinary`。 +- 清空后，`GetProperties()` 返回的数组为空，`FindProperty(...)` 将返回 `nullptr`。 + +## 相关文档 + +- [Shader](Shader.md) +- [AddProperty](AddProperty.md) +- [GetProperties](GetProperties.md) diff --git a/docs/api/XCEngine/Resources/Shader/Shader/Constructor.md b/docs/api/XCEngine/Resources/Shader/Shader/Constructor.md index 8bfb27f0..30b8f265 100644 --- a/docs/api/XCEngine/Resources/Shader/Shader/Constructor.md +++ b/docs/api/XCEngine/Resources/Shader/Shader/Constructor.md @@ -1,28 +1,25 @@ # Shader::Shader() -构造对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Shader/Shader.h` + +## 签名 ```cpp Shader(); ``` -该方法声明于 `XCEngine/Resources/Shader/Shader.h`，当前页面用于固定 `Shader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +构造 `Shader` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Shader object; -} -``` +- 当前为默认构造实现。 ## 相关文档 -- [返回类总览](Shader.md) -- [返回模块目录](../Shader.md) +- [Shader](Shader.md) diff --git a/docs/api/XCEngine/Resources/Shader/Shader/DeclaresKeyword.md b/docs/api/XCEngine/Resources/Shader/Shader/DeclaresKeyword.md new file mode 100644 index 00000000..a59b644e --- /dev/null +++ b/docs/api/XCEngine/Resources/Shader/Shader/DeclaresKeyword.md @@ -0,0 +1,38 @@ +# Shader::DeclaresKeyword + +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Shader/Shader.h` + +## 签名 + +```cpp +bool DeclaresKeyword(const Containers::String& keyword) const; +``` + +## 作用 + +判断任意 pass 是否声明了某个 keyword。 + +## 当前实现行为 + +- 顺序遍历 `m_passes`。 +- 对每个 pass 复用与 [PassDeclaresKeyword](PassDeclaresKeyword.md) 相同的内部匹配规则。 +- 只要任意 pass 命中，就返回 `true`；全部未命中才返回 `false`。 + +## 当前语义 + +- 它回答的是“shader 级声明空间里是否出现过这个 keyword”，不是“所有 pass 都支持它”。 +- 占位 token `_` / `__` 当前依然不会被当成真实声明的 keyword。 + +## 测试锚点 + +`tests/Resources/Shader/test_shader.cpp` 当前覆盖了跨 pass keyword 声明聚合和未知 keyword 返回 `false` 的行为。 + +## 相关文档 + +- [Shader](Shader.md) +- [PassDeclaresKeyword](PassDeclaresKeyword.md) +- [ShaderKeywordTypes](../ShaderKeywordTypes/ShaderKeywordTypes.md) diff --git a/docs/api/XCEngine/Resources/Shader/Shader/Destructor.md b/docs/api/XCEngine/Resources/Shader/Shader/Destructor.md index 8f85ab3e..07926232 100644 --- a/docs/api/XCEngine/Resources/Shader/Shader/Destructor.md +++ b/docs/api/XCEngine/Resources/Shader/Shader/Destructor.md @@ -1,29 +1,25 @@ # Shader::~Shader() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Shader/Shader.h` + +## 签名 ```cpp virtual ~Shader() override; ``` -该方法声明于 `XCEngine/Resources/Shader/Shader.h`，当前页面用于固定 `Shader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +销毁 `Shader` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Shader object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 当前为默认析构实现。 ## 相关文档 -- [返回类总览](Shader.md) -- [返回模块目录](../Shader.md) +- [Shader](Shader.md) diff --git a/docs/api/XCEngine/Resources/Shader/Shader/FindPass.md b/docs/api/XCEngine/Resources/Shader/Shader/FindPass.md new file mode 100644 index 00000000..1883250b --- /dev/null +++ b/docs/api/XCEngine/Resources/Shader/Shader/FindPass.md @@ -0,0 +1,37 @@ +# Shader::FindPass + +**命名空间**: `XCEngine::Resources` + +**类型**: `method overloads` + +**头文件**: `XCEngine/Resources/Shader/Shader.h` + +## 签名 + +```cpp +const ShaderPass* FindPass(const Containers::String& passName) const; +ShaderPass* FindPass(const Containers::String& passName); +``` + +## 作用 + +按名称查找 pass，并返回内部对象指针。 + +## 当前实现行为 + +- `const` 和非 `const` 两个重载都对 `m_passes` 做线性遍历。 +- 仅当 `pass.name == passName` 时命中。 +- 找到后返回数组内部元素地址。 +- 未找到时返回 `nullptr`。 + +## 当前语义 + +- 当前实现不做大小写归一化，也不做别名匹配。 +- 返回的是内部存储地址；后续若数组发生重分配，该地址不应跨修改长期持有。 + +## 相关文档 + +- [Shader](Shader.md) +- [HasPass](HasPass.md) +- [AddPass](AddPass.md) +- [FindVariant](FindVariant.md) diff --git a/docs/api/XCEngine/Resources/Shader/Shader/FindPassResourceBinding.md b/docs/api/XCEngine/Resources/Shader/Shader/FindPassResourceBinding.md new file mode 100644 index 00000000..db70554d --- /dev/null +++ b/docs/api/XCEngine/Resources/Shader/Shader/FindPassResourceBinding.md @@ -0,0 +1,36 @@ +# Shader::FindPassResourceBinding + +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Shader/Shader.h` + +## 签名 + +```cpp +const ShaderResourceBindingDesc* FindPassResourceBinding( + const Containers::String& passName, + const Containers::String& resourceName) const; +``` + +## 作用 + +在指定 pass 内按资源名查找 resource binding 描述。 + +## 当前实现行为 + +- 先调用 `FindPass(passName)` 查找目标 pass。 +- 如果 pass 不存在，立即返回 `nullptr`。 +- 若 pass 存在，则在线性遍历 `pass->resources` 时按 `binding.name == resourceName` 精确匹配。 +- 找到后返回内部元素地址，未找到返回 `nullptr`。 + +## 测试覆盖 + +`tests/Resources/Shader/test_shader.cpp` 和 `tests/Resources/Shader/test_shader_loader.cpp` 当前都验证了该查找路径。 + +## 相关文档 + +- [Shader](Shader.md) +- [AddPassResourceBinding](AddPassResourceBinding.md) +- [FindPass](FindPass.md) diff --git a/docs/api/XCEngine/Resources/Shader/Shader/FindProperty.md b/docs/api/XCEngine/Resources/Shader/Shader/FindProperty.md new file mode 100644 index 00000000..aad3e113 --- /dev/null +++ b/docs/api/XCEngine/Resources/Shader/Shader/FindProperty.md @@ -0,0 +1,34 @@ +# Shader::FindProperty + +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Shader/Shader.h` + +## 签名 + +```cpp +const ShaderPropertyDesc* FindProperty(const Containers::String& propertyName) const; +``` + +## 作用 + +按名称查找 shader property。 + +## 当前实现行为 + +- 对 `m_properties` 做线性遍历。 +- 仅当 `property.name == propertyName` 时命中。 +- 找到后返回内部数组元素地址。 +- 未找到时返回 `nullptr`。 + +## 测试覆盖 + +`tests/Resources/Shader/test_shader.cpp` 和 `tests/Resources/Shader/test_shader_loader.cpp` 当前都验证了可按 property 名称取回解析后的描述。 + +## 相关文档 + +- [Shader](Shader.md) +- [AddProperty](AddProperty.md) +- [GetProperties](GetProperties.md) diff --git a/docs/api/XCEngine/Resources/Shader/Shader/FindVariant.md b/docs/api/XCEngine/Resources/Shader/Shader/FindVariant.md new file mode 100644 index 00000000..ad261302 --- /dev/null +++ b/docs/api/XCEngine/Resources/Shader/Shader/FindVariant.md @@ -0,0 +1,47 @@ +# Shader::FindVariant + +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Shader/Shader.h` + +## 签名 + +```cpp +const ShaderStageVariant* FindVariant( + const Containers::String& passName, + ShaderType stage, + ShaderBackend backend = ShaderBackend::Generic, + const ShaderKeywordSet& enabledKeywords = ShaderKeywordSet()) const; +``` + +## 作用 + +在指定 pass 中查找某个 stage 的最合适 variant。 + +## 当前实现行为 + +- 先调用 `FindPass(passName)`；找不到 pass 时直接返回 `nullptr`。 +- 先把 `enabledKeywords` 做一次归一化。 +- 只考虑 `variant.stage == stage` 且 `variant.requiredKeywords` 是 `enabledKeywords` 子集的条目。 +- 对 `variant.backend == backend` 的候选，记录“required keyword 更多”的那一个作为精确命中。 +- 对 `variant.backend == ShaderBackend::Generic` 的候选，同样记录“required keyword 更多”的那一个作为兜底命中。 +- 最终优先返回精确 backend 命中，否则返回 generic 命中；若都没有，则返回 `nullptr`。 + +## 当前语义 + +- 当前 fallback 仅对 backend 生效，不会跨 stage 兜底。 +- keyword 选择不是精确相等匹配，而是“variant.requiredKeywords 必须被 enabledKeywords 覆盖”。 +- 当同一优先级下存在多个 required-keyword 数量相同的候选时，当前保留最早遇到的那个。 + +## 测试覆盖 + +`tests/Resources/Shader/test_shader.cpp` 当前显式验证了 backend 优先级、keyword 子集命中与 `Generic` 兜底语义。 +`tests/Resources/Shader/test_shader_loader.cpp` 和若干渲染路径测试当前还依赖它按 backend + keyword 取回 builtin / authoring shader variant。 + +## 相关文档 + +- [Shader](Shader.md) +- [AddPassVariant](AddPassVariant.md) +- [FindPass](FindPass.md) diff --git a/docs/api/XCEngine/Resources/Shader/Shader/GetAttributes.md b/docs/api/XCEngine/Resources/Shader/Shader/GetAttributes.md index 1ff28da6..4b1016cf 100644 --- a/docs/api/XCEngine/Resources/Shader/Shader/GetAttributes.md +++ b/docs/api/XCEngine/Resources/Shader/Shader/GetAttributes.md @@ -1,30 +1,33 @@ # Shader::GetAttributes -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Shader/Shader.h` + +## 签名 ```cpp const Containers::Array& GetAttributes() const; ``` -该方法声明于 `XCEngine/Resources/Shader/Shader.h`，当前页面用于固定 `Shader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +读取当前保存的 attribute 反射记录数组。 -**返回：** `const Containers::Array&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** +- 头文件内联实现为直接返回 `m_attributes` 的常量引用。 +- 不做复制，也不做重新反射。 +- 当前 manifest / artifact 路径不会主动填充这些记录；它们目前主要服务于手工构造或测试场景。 -```cpp -#include +## 测试覆盖 -void Example() { - XCEngine::Resources::Shader object; - // 根据上下文补齐参数后调用 Shader::GetAttributes(...)。 - (void)object; -} -``` +`tests/Resources/Shader/test_shader.cpp` 当前验证了 `AddAttribute(...)` 后可通过该接口读回记录。 ## 相关文档 -- [返回类总览](Shader.md) -- [返回模块目录](../Shader.md) +- [Shader](Shader.md) +- [ShaderAttribute](ShaderAttribute.md) +- [AddAttribute](AddAttribute.md) diff --git a/docs/api/XCEngine/Resources/Shader/Shader/GetCompiledBinary.md b/docs/api/XCEngine/Resources/Shader/Shader/GetCompiledBinary.md index d6da4cfe..fce05f5a 100644 --- a/docs/api/XCEngine/Resources/Shader/Shader/GetCompiledBinary.md +++ b/docs/api/XCEngine/Resources/Shader/Shader/GetCompiledBinary.md @@ -1,30 +1,33 @@ # Shader::GetCompiledBinary -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Shader/Shader.h` + +## 签名 ```cpp const Containers::Array& GetCompiledBinary() const; ``` -该方法声明于 `XCEngine/Resources/Shader/Shader.h`，当前页面用于固定 `Shader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +读取 legacy 单 stage 视图中的编译后二进制。 -**返回：** `const Containers::Array&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** +- 头文件内联实现为直接返回 `m_compiledBinary` 的常量引用。 +- 默认构造后数组为空。 +- 与 [GetSourceCode](GetSourceCode.md) 类似，它只反映 legacy 单值视图，不是多 pass shader 全部 variant 二进制的聚合结果。 -```cpp -#include +## 测试覆盖 -void Example() { - XCEngine::Resources::Shader object; - // 根据上下文补齐参数后调用 Shader::GetCompiledBinary(...)。 - (void)object; -} -``` +`tests/Resources/Shader/test_shader.cpp` 当前验证了写入数组后可按索引读回。 ## 相关文档 -- [返回类总览](Shader.md) -- [返回模块目录](../Shader.md) +- [Shader](Shader.md) +- [SetCompiledBinary](SetCompiledBinary.md) +- [ShaderStageVariant](ShaderStageVariant.md) diff --git a/docs/api/XCEngine/Resources/Shader/Shader/GetFallback.md b/docs/api/XCEngine/Resources/Shader/Shader/GetFallback.md new file mode 100644 index 00000000..8b958c80 --- /dev/null +++ b/docs/api/XCEngine/Resources/Shader/Shader/GetFallback.md @@ -0,0 +1,28 @@ +# Shader::GetFallback + +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Shader/Shader.h` + +## 签名 + +```cpp +const Containers::String& GetFallback() const; +``` + +## 作用 + +读取当前 shader 记录的 fallback 字符串元数据。 + +## 当前语义 + +- 头文件内联实现为直接返回 `m_fallback` 的常量引用。 +- 空字符串表示当前 shader 没有显式 fallback。 +- 这只是 metadata 读取，不会触发任何新的资源解析。 + +## 相关文档 + +- [Shader](Shader.md) +- [SetFallback](SetFallback.md) diff --git a/docs/api/XCEngine/Resources/Shader/Shader/GetGUID.md b/docs/api/XCEngine/Resources/Shader/Shader/GetGUID.md index 8cbc98fa..7736c1f9 100644 --- a/docs/api/XCEngine/Resources/Shader/Shader/GetGUID.md +++ b/docs/api/XCEngine/Resources/Shader/Shader/GetGUID.md @@ -1,30 +1,35 @@ # Shader::GetGUID -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Shader/Shader.h` + +## 签名 ```cpp ResourceGUID GetGUID() const override; ``` -该方法声明于 `XCEngine/Resources/Shader/Shader.h`，当前页面用于固定 `Shader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回当前资源对象的稳定资源 GUID。 -**返回：** `ResourceGUID` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** +- 头文件内联实现为直接返回 `m_guid`。 +- 该字段通常由 `IResource::Initialize(...)` 或 loader 手工写入。 +- `Release()` 当前不会清空它。 -```cpp -#include +## 当前语义 -void Example() { - XCEngine::Resources::Shader object; - // 根据上下文补齐参数后调用 Shader::GetGUID(...)。 - (void)object; -} -``` +- manifest / legacy 源资源路径通常用源路径生成 GUID。 +- artifact 加载路径当前也会优先用恢复出的源路径生成 GUID，而不是 artifact 文件本身路径。 +- 因而 `GetGUID()` 代表的是资源身份，不是某次加载过程中的临时磁盘位置。 ## 相关文档 -- [返回类总览](Shader.md) -- [返回模块目录](../Shader.md) +- [Shader](Shader.md) +- [GetName](GetName.md) +- [GetPath](GetPath.md) diff --git a/docs/api/XCEngine/Resources/Shader/Shader/GetMemorySize.md b/docs/api/XCEngine/Resources/Shader/Shader/GetMemorySize.md index 241c5fb5..488f921d 100644 --- a/docs/api/XCEngine/Resources/Shader/Shader/GetMemorySize.md +++ b/docs/api/XCEngine/Resources/Shader/Shader/GetMemorySize.md @@ -1,30 +1,37 @@ # Shader::GetMemorySize -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Shader/Shader.h` + +## 签名 ```cpp size_t GetMemorySize() const override; ``` -该方法声明于 `XCEngine/Resources/Shader/Shader.h`，当前页面用于固定 `Shader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回当前资源对象记录的内存占用估算值。 -**返回：** `size_t` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** +- 头文件内联实现为直接返回 `m_memorySize`。 +- 该字段当前由 `IResource::Initialize(...)` 或 `ShaderLoader` 的 `CalculateShaderMemorySize(...)` 写入。 +- `SetShaderType(...)`、`AddProperty(...)`、`AddPassVariant(...)` 等 mutator 当前不会自动重算它。 +- `Release()` 当前也不会把它清零。 -```cpp -#include +## 当前使用位置 -void Example() { - XCEngine::Resources::Shader object; - // 根据上下文补齐参数后调用 Shader::GetMemorySize(...)。 - (void)object; -} -``` +- `ResourceManager`、`ResourceCache` 当前用它做资源缓存和内存统计。 + +## 当前边界 + +- 这是缓存值，不是实时计算值。 +- 如果调用方在加载后继续手工修改 shader 元数据，`GetMemorySize()` 可能与真实内容大小不再一致。 ## 相关文档 -- [返回类总览](Shader.md) -- [返回模块目录](../Shader.md) +- [Shader](Shader.md) diff --git a/docs/api/XCEngine/Resources/Shader/Shader/GetName.md b/docs/api/XCEngine/Resources/Shader/Shader/GetName.md index 48d402f0..eb076ff9 100644 --- a/docs/api/XCEngine/Resources/Shader/Shader/GetName.md +++ b/docs/api/XCEngine/Resources/Shader/Shader/GetName.md @@ -1,30 +1,35 @@ # Shader::GetName -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Shader/Shader.h` + +## 签名 ```cpp const Containers::String& GetName() const override; ``` -该方法声明于 `XCEngine/Resources/Shader/Shader.h`，当前页面用于固定 `Shader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回当前资源对象的显示名称 / 逻辑名称。 -**返回：** `const Containers::String&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** +- 头文件内联实现为直接返回 `m_name` 的常量引用。 +- 该字段通常由 `IResource::Initialize(...)` 或 loader 手工构造时写入。 +- `Release()` 当前不会清空它。 -```cpp -#include +## 当前语义 -void Example() { - XCEngine::Resources::Shader object; - // 根据上下文补齐参数后调用 Shader::GetName(...)。 - (void)object; -} -``` +- manifest 路径下，名称优先来自 manifest 的 `name` 字段；缺失时回退到文件 stem。 +- artifact 路径下，名称来自 artifact 头中的保存值；为空时回退到当前加载路径。 +- 因此它更接近“资源身份字段”，不是某个 pass 或 variant 的名字。 ## 相关文档 -- [返回类总览](Shader.md) -- [返回模块目录](../Shader.md) +- [Shader](Shader.md) +- [GetPath](GetPath.md) +- [GetGUID](GetGUID.md) diff --git a/docs/api/XCEngine/Resources/Shader/Shader/GetPassCount.md b/docs/api/XCEngine/Resources/Shader/Shader/GetPassCount.md new file mode 100644 index 00000000..e6777592 --- /dev/null +++ b/docs/api/XCEngine/Resources/Shader/Shader/GetPassCount.md @@ -0,0 +1,35 @@ +# Shader::GetPassCount + +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Shader/Shader.h` + +## 签名 + +```cpp +Core::uint32 GetPassCount() const; +``` + +## 作用 + +返回当前 shader 持有的 pass 数量。 + +## 当前实现行为 + +- 头文件内联实现为 `static_cast(m_passes.Size())`。 +- 计数对象是 `m_passes` 当前数组长度。 +- 若 legacy 单 stage 字段已经同步出 `"Default"` pass，则该 pass 也会计入统计。 + +## 测试覆盖 + +`tests/Resources/Shader/test_shader.cpp` 当前验证了 legacy 同步路径和 `Release()` 后的 pass 数量变化。 +`tests/Resources/Shader/test_shader_loader.cpp` 当前还验证了 manifest / artifact 加载后的 pass 数量。 + +## 相关文档 + +- [Shader](Shader.md) +- [AddPass](AddPass.md) +- [ClearPasses](ClearPasses.md) +- [GetPasses](GetPasses.md) diff --git a/docs/api/XCEngine/Resources/Shader/Shader/GetPasses.md b/docs/api/XCEngine/Resources/Shader/Shader/GetPasses.md new file mode 100644 index 00000000..3700b68e --- /dev/null +++ b/docs/api/XCEngine/Resources/Shader/Shader/GetPasses.md @@ -0,0 +1,29 @@ +# Shader::GetPasses + +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Shader/Shader.h` + +## 签名 + +```cpp +const Containers::Array& GetPasses() const; +``` + +## 作用 + +返回当前 shader 的 pass 数组。 + +## 当前实现行为 + +- 直接返回 `m_passes` 的常量引用。 +- 不做复制，也不做按名字重排。 +- 调用方可据此读取 pass、tag、resource 和 variant 的当前原始布局。 + +## 相关文档 + +- [Shader](Shader.md) +- [AddPass](AddPass.md) +- [GetPassCount](GetPassCount.md) diff --git a/docs/api/XCEngine/Resources/Shader/Shader/GetPath.md b/docs/api/XCEngine/Resources/Shader/Shader/GetPath.md index a8e40b0f..f80ec810 100644 --- a/docs/api/XCEngine/Resources/Shader/Shader/GetPath.md +++ b/docs/api/XCEngine/Resources/Shader/Shader/GetPath.md @@ -1,30 +1,39 @@ # Shader::GetPath -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Shader/Shader.h` + +## 签名 ```cpp const Containers::String& GetPath() const override; ``` -该方法声明于 `XCEngine/Resources/Shader/Shader.h`，当前页面用于固定 `Shader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回当前资源对象记录的资源路径。 -**返回：** `const Containers::String&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** +- 头文件内联实现为直接返回 `m_path` 的常量引用。 +- 该字段通常由 `IResource::Initialize(...)` 或 loader 手工写入。 +- `Release()` 当前不会清空它。 -```cpp -#include +## 当前语义 -void Example() { - XCEngine::Resources::Shader object; - // 根据上下文补齐参数后调用 Shader::GetPath(...)。 - (void)object; -} -``` +- 对直接加载的源资源，通常是当前源文件路径。 +- 对 `.xcshader` artifact，当前 loader 会优先恢复 artifact 中保存的源路径；若缺失则回退到 artifact 自身路径。 +- 因而它表达的是“这个 `Shader` 资源代表谁”，不一定等于当前磁盘上真正被读取的那个文件路径。 + +## 测试覆盖 + +`tests/Resources/Shader/test_shader_loader.cpp` 当前验证了 artifact 加载后 `GetPath()` 会回到 manifest 的源路径，而不是 artifact 输出路径。 ## 相关文档 -- [返回类总览](Shader.md) -- [返回模块目录](../Shader.md) +- [Shader](Shader.md) +- [GetName](GetName.md) +- [GetGUID](GetGUID.md) diff --git a/docs/api/XCEngine/Resources/Shader/Shader/GetProperties.md b/docs/api/XCEngine/Resources/Shader/Shader/GetProperties.md new file mode 100644 index 00000000..bd9ccc85 --- /dev/null +++ b/docs/api/XCEngine/Resources/Shader/Shader/GetProperties.md @@ -0,0 +1,30 @@ +# Shader::GetProperties + +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Shader/Shader.h` + +## 签名 + +```cpp +const Containers::Array& GetProperties() const; +``` + +## 作用 + +返回当前 shader 的 property 描述数组。 + +## 当前实现行为 + +- 直接返回 `m_properties` 的常量引用。 +- 不做复制，也不做排序或过滤。 +- 返回结果中的顺序就是当前内部数组顺序。 + +## 相关文档 + +- [Shader](Shader.md) +- [AddProperty](AddProperty.md) +- [ClearProperties](ClearProperties.md) +- [FindProperty](FindProperty.md) diff --git a/docs/api/XCEngine/Resources/Shader/Shader/GetRHIResource.md b/docs/api/XCEngine/Resources/Shader/Shader/GetRHIResource.md new file mode 100644 index 00000000..63bfe984 --- /dev/null +++ b/docs/api/XCEngine/Resources/Shader/Shader/GetRHIResource.md @@ -0,0 +1,33 @@ +# Shader::GetRHIResource + +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Shader/Shader.h` + +## 签名 + +```cpp +class IRHIShader* GetRHIResource() const; +``` + +## 作用 + +返回当前缓存的底层 `IRHIShader*` 句柄。 + +## 当前实现行为 + +- 头文件内联实现为直接返回 `m_rhiResource`。 +- 它不做懒加载，也不做空指针修复。 +- 当前 `Shader` 自身不拥有该指针的释放逻辑；`Release()` 只会把它置空。 + +## 当前边界 + +- 这个句柄只是资源对象上的附加缓存，不代表 `Shader` 文档中的 pass / variant 元数据已经可在所有后端直接执行。 +- manifest / artifact 加载路径主要先构造元数据；是否以及何时生成对应的 RHI shader，取决于更上层渲染管线。 + +## 相关文档 + +- [Shader](Shader.md) +- [SetRHIResource](SetRHIResource.md) diff --git a/docs/api/XCEngine/Resources/Shader/Shader/GetShaderLanguage.md b/docs/api/XCEngine/Resources/Shader/Shader/GetShaderLanguage.md index d8e7e31e..da6d2d64 100644 --- a/docs/api/XCEngine/Resources/Shader/Shader/GetShaderLanguage.md +++ b/docs/api/XCEngine/Resources/Shader/Shader/GetShaderLanguage.md @@ -1,30 +1,33 @@ # Shader::GetShaderLanguage -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Shader/Shader.h` + +## 签名 ```cpp ShaderLanguage GetShaderLanguage() const; ``` -该方法声明于 `XCEngine/Resources/Shader/Shader.h`，当前页面用于固定 `Shader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +读取 legacy 单 stage 视图中的 shader 语言。 -**返回：** `ShaderLanguage` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** +- 头文件内联实现为直接返回 `m_language`。 +- 默认构造值为 `ShaderLanguage::GLSL`。 +- 对多 pass manifest shader，它不是所有 variant 语言的聚合视图。 -```cpp -#include +## 返回值 -void Example() { - XCEngine::Resources::Shader object; - // 根据上下文补齐参数后调用 Shader::GetShaderLanguage(...)。 - (void)object; -} -``` +- 返回当前 legacy 语言字段。 ## 相关文档 -- [返回类总览](Shader.md) -- [返回模块目录](../Shader.md) +- [Shader](Shader.md) +- [SetShaderLanguage](SetShaderLanguage.md) +- [ShaderLanguage](ShaderLanguage.md) diff --git a/docs/api/XCEngine/Resources/Shader/Shader/GetShaderType.md b/docs/api/XCEngine/Resources/Shader/Shader/GetShaderType.md index b841a48a..42425278 100644 --- a/docs/api/XCEngine/Resources/Shader/Shader/GetShaderType.md +++ b/docs/api/XCEngine/Resources/Shader/Shader/GetShaderType.md @@ -1,30 +1,34 @@ # Shader::GetShaderType -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Shader/Shader.h` + +## 签名 ```cpp ShaderType GetShaderType() const; ``` -该方法声明于 `XCEngine/Resources/Shader/Shader.h`，当前页面用于固定 `Shader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +读取 legacy 单 stage 视图中的 shader 阶段。 -**返回：** `ShaderType` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** +- 头文件内联实现为直接返回 `m_shaderType`。 +- 对 legacy 单 stage shader，它通常与默认 `"Default"` pass 下的 generic variant 保持一致。 +- 对多 pass manifest shader，不应把它当成所有 pass / variant 的总览。 -```cpp -#include +## 返回值 -void Example() { - XCEngine::Resources::Shader object; - // 根据上下文补齐参数后调用 Shader::GetShaderType(...)。 - (void)object; -} -``` +- 默认构造后为 `ShaderType::Fragment`。 +- 也可能是最近一次 `SetShaderType(...)` 或 artifact legacy 回填写入的值。 ## 相关文档 -- [返回类总览](Shader.md) -- [返回模块目录](../Shader.md) +- [Shader](Shader.md) +- [SetShaderType](SetShaderType.md) +- [FindVariant](FindVariant.md) diff --git a/docs/api/XCEngine/Resources/Shader/Shader/GetSourceCode.md b/docs/api/XCEngine/Resources/Shader/Shader/GetSourceCode.md index ee18e95a..9a60782b 100644 --- a/docs/api/XCEngine/Resources/Shader/Shader/GetSourceCode.md +++ b/docs/api/XCEngine/Resources/Shader/Shader/GetSourceCode.md @@ -1,30 +1,35 @@ # Shader::GetSourceCode -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Shader/Shader.h` + +## 签名 ```cpp const Containers::String& GetSourceCode() const; ``` -该方法声明于 `XCEngine/Resources/Shader/Shader.h`，当前页面用于固定 `Shader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +读取 legacy 单 stage 视图中的源码文本。 -**返回：** `const Containers::String&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** +- 头文件内联实现为直接返回 `m_sourceCode` 的常量引用。 +- 返回值不做拼接、回退或按 pass 查询。 +- 对手工构造的 legacy shader，它通常与默认 `"Default"` pass 下的 generic variant 源码保持一致。 +- 对 `.shader` manifest 这类多 pass 资源，不应把它当成完整 shader 源码总览；权威数据在各个 `ShaderStageVariant::sourceCode`。 -```cpp -#include +## 测试覆盖 -void Example() { - XCEngine::Resources::Shader object; - // 根据上下文补齐参数后调用 Shader::GetSourceCode(...)。 - (void)object; -} -``` +`tests/Resources/Shader/test_shader.cpp` 当前验证了设置后可直接读回源码。 +`LegacySingleStageStateSyncsIntoDefaultPassVariant` 还间接验证了该字段会镜像到默认 variant。 ## 相关文档 -- [返回类总览](Shader.md) -- [返回模块目录](../Shader.md) +- [Shader](Shader.md) +- [SetSourceCode](SetSourceCode.md) +- [ShaderStageVariant](ShaderStageVariant.md) diff --git a/docs/api/XCEngine/Resources/Shader/Shader/GetType.md b/docs/api/XCEngine/Resources/Shader/Shader/GetType.md index 3ee0d043..9933371f 100644 --- a/docs/api/XCEngine/Resources/Shader/Shader/GetType.md +++ b/docs/api/XCEngine/Resources/Shader/Shader/GetType.md @@ -1,30 +1,30 @@ # Shader::GetType -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Shader/Shader.h` + +## 签名 ```cpp ResourceType GetType() const override; ``` -该方法声明于 `XCEngine/Resources/Shader/Shader.h`，当前页面用于固定 `Shader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回此资源对象的固定资源类型。 -**返回：** `ResourceType` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** +- 头文件内联实现为直接返回 `ResourceType::Shader`。 +- 不依赖对象当前是否有效，也不读取任何运行时字段。 -```cpp -#include +## 返回值 -void Example() { - XCEngine::Resources::Shader object; - // 根据上下文补齐参数后调用 Shader::GetType(...)。 - (void)object; -} -``` +- 始终返回 `ResourceType::Shader`。 ## 相关文档 -- [返回类总览](Shader.md) -- [返回模块目录](../Shader.md) +- [Shader](Shader.md) diff --git a/docs/api/XCEngine/Resources/Shader/Shader/GetUniforms.md b/docs/api/XCEngine/Resources/Shader/Shader/GetUniforms.md index 0f317679..0168ef54 100644 --- a/docs/api/XCEngine/Resources/Shader/Shader/GetUniforms.md +++ b/docs/api/XCEngine/Resources/Shader/Shader/GetUniforms.md @@ -1,30 +1,33 @@ # Shader::GetUniforms -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Shader/Shader.h` + +## 签名 ```cpp const Containers::Array& GetUniforms() const; ``` -该方法声明于 `XCEngine/Resources/Shader/Shader.h`，当前页面用于固定 `Shader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +读取当前保存的 uniform 反射记录数组。 -**返回：** `const Containers::Array&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** +- 头文件内联实现为直接返回 `m_uniforms` 的常量引用。 +- 不做复制，也不做重新反射。 +- 当前 manifest / artifact 加载路径并不主动填充这些记录；它们更像 legacy / 手工维护的反射容器。 -```cpp -#include +## 测试覆盖 -void Example() { - XCEngine::Resources::Shader object; - // 根据上下文补齐参数后调用 Shader::GetUniforms(...)。 - (void)object; -} -``` +`tests/Resources/Shader/test_shader.cpp` 当前验证了 `AddUniform(...)` 后可通过该接口读回记录。 ## 相关文档 -- [返回类总览](Shader.md) -- [返回模块目录](../Shader.md) +- [Shader](Shader.md) +- [ShaderUniform](ShaderUniform.md) +- [AddUniform](AddUniform.md) diff --git a/docs/api/XCEngine/Resources/Shader/Shader/HasPass.md b/docs/api/XCEngine/Resources/Shader/Shader/HasPass.md new file mode 100644 index 00000000..c48e446b --- /dev/null +++ b/docs/api/XCEngine/Resources/Shader/Shader/HasPass.md @@ -0,0 +1,28 @@ +# Shader::HasPass + +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Shader/Shader.h` + +## 签名 + +```cpp +bool HasPass(const Containers::String& passName) const; +``` + +## 作用 + +判断当前 shader 是否存在指定名称的 pass。 + +## 当前实现行为 + +- 当前实现只是 `return FindPass(passName) != nullptr;`。 +- 判断规则完全复用 `FindPass(...)` 的线性查找与名称精确匹配逻辑。 + +## 相关文档 + +- [Shader](Shader.md) +- [FindPass](FindPass.md) +- [GetPassCount](GetPassCount.md) diff --git a/docs/api/XCEngine/Resources/Shader/Shader/IsValid.md b/docs/api/XCEngine/Resources/Shader/Shader/IsValid.md index 02a558e3..da95ac5f 100644 --- a/docs/api/XCEngine/Resources/Shader/Shader/IsValid.md +++ b/docs/api/XCEngine/Resources/Shader/Shader/IsValid.md @@ -1,30 +1,37 @@ # Shader::IsValid -查询当前状态。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Shader/Shader.h` + +## 签名 ```cpp bool IsValid() const override; ``` -该方法声明于 `XCEngine/Resources/Shader/Shader.h`，当前页面用于固定 `Shader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回当前资源是否处于有效状态。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** +- 头文件内联实现为直接返回 `m_isValid`。 +- `IResource::Initialize(...)` 当前会把它设为 `true`。 +- `Release()` 当前会把它设回 `false`。 -```cpp -#include +## 当前语义 -void Example() { - XCEngine::Resources::Shader object; - // 根据上下文补齐参数后调用 Shader::IsValid(...)。 - (void)object; -} -``` +- `IsValid()` 只反映资源对象的生命周期状态，不保证某个特定 backend 的 `ShaderStageVariant` 一定齐全。 +- 例如一个 shader 可以处于 valid，但当前 backend 下仍找不到需要的 graphics variants。 + +## 测试覆盖 + +`tests/Resources/Shader/test_shader.cpp` 当前验证了默认构造时为 invalid，而 `Release()` 后会重新变为 invalid。 ## 相关文档 -- [返回类总览](Shader.md) -- [返回模块目录](../Shader.md) +- [Shader](Shader.md) +- [Release](Release.md) diff --git a/docs/api/XCEngine/Resources/Shader/Shader/PassDeclaresKeyword.md b/docs/api/XCEngine/Resources/Shader/Shader/PassDeclaresKeyword.md new file mode 100644 index 00000000..750efaf0 --- /dev/null +++ b/docs/api/XCEngine/Resources/Shader/Shader/PassDeclaresKeyword.md @@ -0,0 +1,40 @@ +# Shader::PassDeclaresKeyword + +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Shader/Shader.h` + +## 签名 + +```cpp +bool PassDeclaresKeyword( + const Containers::String& passName, + const Containers::String& keyword) const; +``` + +## 作用 + +判断指定 pass 是否声明了某个 keyword。 + +## 当前实现行为 + +- 先调用 `FindPass(passName)`；找不到 pass 时直接返回 `false`。 +- 对找到的 pass，会把输入 keyword 走 `NormalizeShaderKeywordToken(...)`。 +- 然后遍历 `pass.keywordDeclarations[*].options`，只要有某个 option 归一化后与目标 keyword 相同，就返回 `true`。 + +## 当前语义 + +- `_` 和 `__` 这类占位 token 归一化后会被视为“未声明具体 keyword”，因此不会命中。 +- 它检查的是“pass 是否声明过这个 keyword”，不是“当前 variant 是否启用了这个 keyword”。 + +## 测试锚点 + +`tests/Resources/Shader/test_shader.cpp` 与 `tests/Resources/Shader/test_shader_loader.cpp` 当前都覆盖了正向命中与占位 token 不命中的行为。 + +## 相关文档 + +- [Shader](Shader.md) +- [DeclaresKeyword](DeclaresKeyword.md) +- [AddPassKeywordDeclaration](AddPassKeywordDeclaration.md) diff --git a/docs/api/XCEngine/Resources/Shader/Shader/Release.md b/docs/api/XCEngine/Resources/Shader/Shader/Release.md index 50b182f4..ee30eb54 100644 --- a/docs/api/XCEngine/Resources/Shader/Shader/Release.md +++ b/docs/api/XCEngine/Resources/Shader/Shader/Release.md @@ -1,30 +1,41 @@ # Shader::Release -释放引用或底层资源。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Shader/Shader.h` + +## 签名 ```cpp void Release() override; ``` -该方法声明于 `XCEngine/Resources/Shader/Shader.h`，当前页面用于固定 `Shader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +清空当前 shader 的运行时内容，并把资源重新标记为 invalid。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** +- 把 `m_shaderType` 重置为 `ShaderType::Fragment`。 +- 把 `m_language` 重置为 `ShaderLanguage::GLSL`。 +- 清空 `m_sourceCode`、`m_compiledBinary`、`m_uniforms`、`m_attributes`、`m_properties`、`m_passes`。 +- 把 `m_rhiResource` 置为 `nullptr`。 +- 把 `m_isValid` 置为 `false`。 -```cpp -#include +## 当前边界 -void Example() { - XCEngine::Resources::Shader object; - // 根据上下文补齐参数后调用 Shader::Release(...)。 - (void)object; -} -``` +- 当前实现不会清空 `m_name`、`m_path`、`m_guid`。 +- 当前实现不会把 `m_memorySize` 重置为 `0`。 +- 当前实现也不会负责释放 `m_rhiResource` 指向的底层对象，只是丢弃缓存指针。 + +## 测试覆盖 + +`tests/Resources/Shader/test_shader.cpp` 当前验证了 `Release()` 后 property、pass、源码、编译二进制会被清空，且资源重新变为 invalid。 ## 相关文档 -- [返回类总览](Shader.md) -- [返回模块目录](../Shader.md) +- [Shader](Shader.md) +- [IsValid](IsValid.md) +- [GetRHIResource](GetRHIResource.md) diff --git a/docs/api/XCEngine/Resources/Shader/Shader/SetCompiledBinary.md b/docs/api/XCEngine/Resources/Shader/Shader/SetCompiledBinary.md index a733c284..1fdbf225 100644 --- a/docs/api/XCEngine/Resources/Shader/Shader/SetCompiledBinary.md +++ b/docs/api/XCEngine/Resources/Shader/Shader/SetCompiledBinary.md @@ -1,31 +1,33 @@ # Shader::SetCompiledBinary -设置相关状态或配置。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Shader/Shader.h` + +## 签名 ```cpp void SetCompiledBinary(const Containers::Array& binary); ``` -该方法声明于 `XCEngine/Resources/Shader/Shader.h`，当前页面用于固定 `Shader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `binary` - 参数语义详见头文件声明。 +更新 legacy 单 stage 视图中的编译后二进制。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** +- 先把 `m_compiledBinary` 赋值为传入数组。 +- 随后调用 `SyncLegacyVariant()`。 +- 默认 `"Default"` pass 下的 generic variant 会同步得到同一份 `compiledBinary`。 -```cpp -#include +## 当前边界 -void Example() { - XCEngine::Resources::Shader object; - // 根据上下文补齐参数后调用 Shader::SetCompiledBinary(...)。 - (void)object; -} -``` +- 该方法不会触发编译流程，也不会自动生成其他 backend variant。 +- 对多 pass shader，它只更新 legacy 默认视图。 ## 相关文档 -- [返回类总览](Shader.md) -- [返回模块目录](../Shader.md) +- [Shader](Shader.md) +- [GetCompiledBinary](GetCompiledBinary.md) diff --git a/docs/api/XCEngine/Resources/Shader/Shader/SetFallback.md b/docs/api/XCEngine/Resources/Shader/Shader/SetFallback.md new file mode 100644 index 00000000..e9821acd --- /dev/null +++ b/docs/api/XCEngine/Resources/Shader/Shader/SetFallback.md @@ -0,0 +1,38 @@ +# Shader::SetFallback + +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Shader/Shader.h` + +## 签名 + +```cpp +void SetFallback(const Containers::String& fallback); +``` + +## 作用 + +写入 shader 级 fallback 字符串元数据。 + +## 当前实现行为 + +- 当前实现只是把传入值复制到 `m_fallback`。 +- 不会自动改写 pass、variant 或 backend 选择结果。 + +## 当前语义 + +- 这是 authoring / artifact 层保留下来的 metadata。 +- [FindVariant](FindVariant.md) 当前不会在本类内部根据 `m_fallback` 自动继续解析其他 shader。 +- `ShaderLoader`、`AssetDatabase` 与 builtin 资源生成路径当前会把它当作可序列化字段保留下来。 + +## 测试锚点 + +`tests/Resources/Shader/test_shader_loader.cpp` 当前验证了 unity-style / legacy authoring 中的 `Fallback` 字段会回读到这里。 + +## 相关文档 + +- [Shader](Shader.md) +- [GetFallback](GetFallback.md) +- [FindVariant](FindVariant.md) diff --git a/docs/api/XCEngine/Resources/Shader/Shader/SetPassTag.md b/docs/api/XCEngine/Resources/Shader/Shader/SetPassTag.md new file mode 100644 index 00000000..8954fc20 --- /dev/null +++ b/docs/api/XCEngine/Resources/Shader/Shader/SetPassTag.md @@ -0,0 +1,37 @@ +# Shader::SetPassTag + +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Shader/Shader.h` + +## 签名 + +```cpp +void SetPassTag( + const Containers::String& passName, + const Containers::String& tagName, + const Containers::String& tagValue); +``` + +## 作用 + +为指定 pass 设置或覆盖一个 tag。 + +## 当前实现行为 + +- 先通过 `GetOrCreatePass(passName)` 取得目标 pass。 +- 在线性遍历 `pass.tags` 时，若发现同名 `tag.name == tagName`，则仅更新 `tag.value`。 +- 未找到同名 tag 时，通过 `EmplaceBack()` 追加新条目。 +- 因此同一 pass 内，tag 名称当前按实现保持唯一。 + +## 测试覆盖 + +`tests/Resources/Shader/test_shader.cpp` 当前验证了为同一个 pass 写入多条 tag 后可正确保留。 + +## 相关文档 + +- [Shader](Shader.md) +- [AddPass](AddPass.md) +- [FindPass](FindPass.md) diff --git a/docs/api/XCEngine/Resources/Shader/Shader/SetRHIResource.md b/docs/api/XCEngine/Resources/Shader/Shader/SetRHIResource.md index e6a821ab..4acd6809 100644 --- a/docs/api/XCEngine/Resources/Shader/Shader/SetRHIResource.md +++ b/docs/api/XCEngine/Resources/Shader/Shader/SetRHIResource.md @@ -1,31 +1,32 @@ # Shader::SetRHIResource -设置相关状态或配置。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Shader/Shader.h` + +## 签名 ```cpp void SetRHIResource(class IRHIShader* resource); ``` -该方法声明于 `XCEngine/Resources/Shader/Shader.h`，当前页面用于固定 `Shader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `resource` - 参数语义详见头文件声明。 +写入底层 `IRHIShader*` 缓存句柄。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** +- 直接把 `m_rhiResource` 设为传入指针。 +- 不做空指针检查，也不做所有权转移。 -```cpp -#include +## 当前边界 -void Example() { - XCEngine::Resources::Shader object; - // 根据上下文补齐参数后调用 Shader::SetRHIResource(...)。 - (void)object; -} -``` +- `Shader` 当前不负责销毁旧的或新的 `IRHIShader*`。 +- `Release()` 只会把该字段清空，不会释放底层资源。 ## 相关文档 -- [返回类总览](Shader.md) -- [返回模块目录](../Shader.md) +- [Shader](Shader.md) +- [GetRHIResource](GetRHIResource.md) diff --git a/docs/api/XCEngine/Resources/Shader/Shader/SetShaderLanguage.md b/docs/api/XCEngine/Resources/Shader/Shader/SetShaderLanguage.md index bdecef6f..b7e8da9d 100644 --- a/docs/api/XCEngine/Resources/Shader/Shader/SetShaderLanguage.md +++ b/docs/api/XCEngine/Resources/Shader/Shader/SetShaderLanguage.md @@ -1,31 +1,38 @@ # Shader::SetShaderLanguage -设置相关状态或配置。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Shader/Shader.h` + +## 签名 ```cpp void SetShaderLanguage(ShaderLanguage lang); ``` -该方法声明于 `XCEngine/Resources/Shader/Shader.h`，当前页面用于固定 `Shader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `lang` - 参数语义详见头文件声明。 +更新 legacy 单 stage 视图中的 shader 语言。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** +- 先把 `m_language` 设为传入值。 +- 随后调用 `SyncLegacyVariant()`。 +- 默认 `"Default"` pass 下的 generic variant 会随之同步其 `language` 字段。 -```cpp -#include +## 当前边界 -void Example() { - XCEngine::Resources::Shader object; - // 根据上下文补齐参数后调用 Shader::SetShaderLanguage(...)。 - (void)object; -} -``` +- 该方法不会自动修改其他 pass / backend variant 的语言。 +- 它主要服务于 legacy 单 stage 兼容路径和默认 generic variant 镜像。 + +## 测试覆盖 + +`tests/Resources/Shader/test_shader.cpp` 当前验证了语言可被设置和读取。 ## 相关文档 -- [返回类总览](Shader.md) -- [返回模块目录](../Shader.md) +- [Shader](Shader.md) +- [GetShaderLanguage](GetShaderLanguage.md) +- [ShaderLanguage](ShaderLanguage.md) diff --git a/docs/api/XCEngine/Resources/Shader/Shader/SetShaderType.md b/docs/api/XCEngine/Resources/Shader/Shader/SetShaderType.md index 83d66af7..2d27be92 100644 --- a/docs/api/XCEngine/Resources/Shader/Shader/SetShaderType.md +++ b/docs/api/XCEngine/Resources/Shader/Shader/SetShaderType.md @@ -1,31 +1,40 @@ # Shader::SetShaderType -设置相关状态或配置。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Shader/Shader.h` + +## 签名 ```cpp void SetShaderType(ShaderType type); ``` -该方法声明于 `XCEngine/Resources/Shader/Shader.h`，当前页面用于固定 `Shader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `type` - 参数语义详见头文件声明。 +更新 legacy 单 stage 视图中的 shader 阶段。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** +- 先把 `m_shaderType` 设为传入值。 +- 随后调用 `SyncLegacyVariant()`。 +- 若当前不存在默认 `"Default"` pass 或对应的 `ShaderBackend::Generic` variant，`SyncLegacyVariant()` 会隐式创建它。 +- 同步后的默认 variant 会继承当前的 `m_shaderType/m_language/m_sourceCode/m_compiledBinary`。 -```cpp -#include +## 当前边界 -void Example() { - XCEngine::Resources::Shader object; - // 根据上下文补齐参数后调用 Shader::SetShaderType(...)。 - (void)object; -} -``` +- 该方法只维护 legacy 单值视图与默认 generic variant 的镜像关系。 +- 它不会批量改写其他 pass 或其他 backend 的 variant。 + +## 测试覆盖 + +`tests/Resources/Shader/test_shader.cpp` 当前验证了类型可被设置和读取。 +同一测试文件中的 `LegacySingleStageStateSyncsIntoDefaultPassVariant` 还验证了默认 pass / variant 同步语义。 ## 相关文档 -- [返回类总览](Shader.md) -- [返回模块目录](../Shader.md) +- [Shader](Shader.md) +- [GetShaderType](GetShaderType.md) +- [ShaderType](ShaderType.md) diff --git a/docs/api/XCEngine/Resources/Shader/Shader/SetSourceCode.md b/docs/api/XCEngine/Resources/Shader/Shader/SetSourceCode.md index 1f9657c3..fe87e455 100644 --- a/docs/api/XCEngine/Resources/Shader/Shader/SetSourceCode.md +++ b/docs/api/XCEngine/Resources/Shader/Shader/SetSourceCode.md @@ -1,31 +1,33 @@ # Shader::SetSourceCode -设置相关状态或配置。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Shader/Shader.h` + +## 签名 ```cpp void SetSourceCode(const Containers::String& source); ``` -该方法声明于 `XCEngine/Resources/Shader/Shader.h`，当前页面用于固定 `Shader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `source` - 参数语义详见头文件声明。 +更新 legacy 单 stage 视图中的源码文本。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** +- 先把 `m_sourceCode` 赋值为传入源码。 +- 随后调用 `SyncLegacyVariant()`。 +- 默认 `"Default"` pass 下的 generic variant 会同步得到同一份 `sourceCode`。 -```cpp -#include +## 当前边界 -void Example() { - XCEngine::Resources::Shader object; - // 根据上下文补齐参数后调用 Shader::SetSourceCode(...)。 - (void)object; -} -``` +- 该方法不会解析源码，也不会自动生成 `uniform/attribute/property/pass` 元数据。 +- 对多 pass shader，它只更新 legacy 默认视图，不会替换其他 pass 的源码。 ## 相关文档 -- [返回类总览](Shader.md) -- [返回模块目录](../Shader.md) +- [Shader](Shader.md) +- [GetSourceCode](GetSourceCode.md) diff --git a/docs/api/XCEngine/Resources/Shader/Shader/Shader.md b/docs/api/XCEngine/Resources/Shader/Shader/Shader.md index 09f4dbac..0dbb0bc1 100644 --- a/docs/api/XCEngine/Resources/Shader/Shader/Shader.md +++ b/docs/api/XCEngine/Resources/Shader/Shader/Shader.md @@ -6,50 +6,122 @@ **头文件**: `XCEngine/Resources/Shader/Shader.h` -**描述**: 定义 `XCEngine/Resources/Shader` 子目录中的 `Shader` public API。 +**描述**: Shader 资源类型，统一承载 legacy 单 stage 视图、pass-centric 元数据模型，以及可选的底层 `IRHIShader*` 句柄。 -## 概述 +## 概览 -`Shader.h` 是 `XCEngine/Resources/Shader` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。 +`Shader` 不只是“一段源码字符串”。当前头文件已经把它扩展成可承载完整渲染管线元数据的资源对象，主要包括： + +- shader 类型、语言、源码与编译后二进制 +- uniform / attribute 的传统反射信息 +- property、resource binding、pass tag、keyword declaration、fixed-function state、stage variant 等更高层的材质 / pass 描述 +- 一个独立的 `fallback` 字符串元数据 +- 一个可选的底层 `IRHIShader*` 句柄 + +## legacy 单 stage 视图与 pass 模型 + +当前 `Shader` 同时维护两层表示： + +1. legacy 单 stage 字段 + `m_shaderType`、`m_language`、`m_sourceCode`、`m_compiledBinary` +2. 当前主模型 + `m_properties`、`m_passes`、`m_fallback`，以及 pass 下的 `tags/resources/keywordDeclarations/fixedFunctionState/variants` + +按 `Shader.cpp` 当前实现，`SetShaderType()`、`SetShaderLanguage()`、`SetSourceCode()`、`SetCompiledBinary()` 会调用 `SyncLegacyVariant()`，把 legacy 字段镜像到默认 `"Default"` pass 下的一个 `ShaderBackend::Generic` variant。 + +这意味着： + +- 手工构造或 legacy 单 stage loader 路径下，单值 getter 和 pass 模型会保持镜像关系。 +- 对多 pass `.shader` manifest 来说，真正权威的数据通常在 `GetPasses()` / `FindPass()` / `FindVariant()` 这一组接口里。 +- `m_fallback` 当前只是 shader 级字符串元数据，不会被 `FindVariant(...)` 自动消费。 +- 不应把 `GetShaderType()` / `GetShaderLanguage()` / `GetSourceCode()` / `GetCompiledBinary()` 误读为多 pass shader 的完整总览。 + +## 生命周期与资源语义 + +- `IResource::Initialize(...)` 会写入 `name/path/guid/memorySize` 并把 `m_isValid` 置为 `true`。 +- `Release()` 当前会清空源码、属性、pass、RHI 指针并把 `m_isValid` 置回 `false`。 +- `Release()` 不会清空 `m_name`、`m_path`、`m_guid`，也不会重新计算 `m_memorySize`。 +- `m_rhiResource` 只是一个非 owning 原始指针缓存；`Shader` 自身当前不负责释放它。 + +## 线程语义 + +- 当前类没有内部同步。 +- loader、渲染线程和编辑器线程若共享同一 `Shader` 实例，并发读写协调由调用方负责。 + +## 当前实现边界 + +- manifest / artifact 路径当前主要围绕 `property + pass + resource binding + variant` 工作，`uniform/attribute` 反射数组并不是主流数据来源。 +- `GetMemorySize()` 当前返回 loader 写入的缓存值；手工调用 mutator 后不会自动刷新。 +- backend 选择当前依赖 `FindVariant(...)` 的“精确 backend 优先，`Generic` 兜底 + required keyword 更多者优先”规则。 ## 声明概览 | 声明 | 类型 | 说明 | |------|------|------| -| `ShaderType` | `enum class` | 头文件中的公开声明。 | -| `ShaderLanguage` | `enum class` | 头文件中的公开声明。 | -| `ShaderUniform` | `struct` | 头文件中的公开声明。 | -| `ShaderAttribute` | `struct` | 头文件中的公开声明。 | -| `Shader` | `class` | 继承自 `IResource` 的公开声明。 | +| [ShaderType](ShaderType.md) | `enum class` | shader stage 类型。 | +| [ShaderLanguage](ShaderLanguage.md) | `enum class` | shader 源码语言。 | +| [ShaderBackend](ShaderBackend.md) | `enum class` | variant 目标后端。 | +| [ShaderPropertyType](ShaderPropertyType.md) | `enum class` | shader property 类型。 | +| [ShaderResourceType](ShaderResourceType.md) | `enum class` | pass 资源绑定类型。 | +| [ShaderUniform](ShaderUniform.md) | `struct` | uniform 反射记录。 | +| [ShaderAttribute](ShaderAttribute.md) | `struct` | vertex attribute 反射记录。 | +| [ShaderPassTagEntry](ShaderPassTagEntry.md) | `struct` | pass tag 键值对。 | +| [ShaderPropertyDesc](ShaderPropertyDesc.md) | `struct` | 材质层可消费的 shader property 描述。 | +| [ShaderResourceBindingDesc](ShaderResourceBindingDesc.md) | `struct` | pass 资源绑定描述。 | +| [ShaderStageVariant](ShaderStageVariant.md) | `struct` | 某个 stage/backend 的具体 shader variant。 | +| [ShaderPass](ShaderPass.md) | `struct` | pass 名、tag、resources 与 variants 的聚合结构。 | +| `Shader` | `class` | shader 资源对象。 | ## 公共方法 | 方法 | 描述 | |------|------| -| [Shader()](Constructor.md) | 构造对象。 | -| [~Shader()](Destructor.md) | 销毁对象并释放相关资源。 | -| [GetType](GetType.md) | 获取相关状态或对象。 | -| [GetName](GetName.md) | 获取相关状态或对象。 | -| [GetPath](GetPath.md) | 获取相关状态或对象。 | -| [GetGUID](GetGUID.md) | 获取相关状态或对象。 | -| [IsValid](IsValid.md) | 查询当前状态。 | -| [GetMemorySize](GetMemorySize.md) | 获取相关状态或对象。 | -| [Release](Release.md) | 释放引用或底层资源。 | -| [SetShaderType](SetShaderType.md) | 设置相关状态或配置。 | -| [GetShaderType](GetShaderType.md) | 获取相关状态或对象。 | -| [SetShaderLanguage](SetShaderLanguage.md) | 设置相关状态或配置。 | -| [GetShaderLanguage](GetShaderLanguage.md) | 获取相关状态或对象。 | -| [SetSourceCode](SetSourceCode.md) | 设置相关状态或配置。 | -| [GetSourceCode](GetSourceCode.md) | 获取相关状态或对象。 | -| [SetCompiledBinary](SetCompiledBinary.md) | 设置相关状态或配置。 | -| [GetCompiledBinary](GetCompiledBinary.md) | 获取相关状态或对象。 | -| [AddUniform](AddUniform.md) | 添加元素或建立关联。 | -| [GetUniforms](GetUniforms.md) | 获取相关状态或对象。 | -| [AddAttribute](AddAttribute.md) | 添加元素或建立关联。 | -| [GetAttributes](GetAttributes.md) | 获取相关状态或对象。 | -| [SetRHIResource](SetRHIResource.md) | 设置相关状态或配置。 | +| [Shader()](Constructor.md) | 构造 `Shader` 实例。 | +| [~Shader()](Destructor.md) | 销毁 `Shader` 实例。 | +| [GetType](GetType.md) | 返回固定资源类型 `ResourceType::Shader`。 | +| [GetName](GetName.md) | 返回 `IResource` 身份字段中的 `name`。 | +| [GetPath](GetPath.md) | 返回 `IResource` 身份字段中的 `path`。 | +| [GetGUID](GetGUID.md) | 返回 `IResource` 身份字段中的 `guid`。 | +| [IsValid](IsValid.md) | 返回当前资源是否处于有效状态。 | +| [GetMemorySize](GetMemorySize.md) | 返回 loader 写入的缓存内存估算值。 | +| [Release](Release.md) | 清空运行时 shader 数据并把资源置为 invalid。 | +| [SetShaderType](SetShaderType.md) | 更新 legacy 单 stage 类型并同步默认 variant。 | +| [GetShaderType](GetShaderType.md) | 读取 legacy 单 stage 类型视图。 | +| [SetShaderLanguage](SetShaderLanguage.md) | 更新 legacy 单 stage 语言并同步默认 variant。 | +| [GetShaderLanguage](GetShaderLanguage.md) | 读取 legacy 单 stage 语言视图。 | +| [SetSourceCode](SetSourceCode.md) | 更新 legacy 单 stage 源码并同步默认 variant。 | +| [GetSourceCode](GetSourceCode.md) | 读取 legacy 单 stage 源码视图。 | +| [SetCompiledBinary](SetCompiledBinary.md) | 更新 legacy 单 stage 编译后二进制并同步默认 variant。 | +| [GetCompiledBinary](GetCompiledBinary.md) | 读取 legacy 单 stage 编译后二进制视图。 | +| [AddUniform](AddUniform.md) | 追加一条传统 uniform 反射记录。 | +| [GetUniforms](GetUniforms.md) | 读取 uniform 反射数组。 | +| [AddAttribute](AddAttribute.md) | 追加一条传统 attribute 反射记录。 | +| [GetAttributes](GetAttributes.md) | 读取 attribute 反射数组。 | +| [AddProperty](AddProperty.md) | 写入或覆盖 shader property 描述。 | +| [ClearProperties](ClearProperties.md) | 清空全部 property 描述。 | +| [GetProperties](GetProperties.md) | 读取 shader property 列表。 | +| [FindProperty](FindProperty.md) | 按名称查找 shader property。 | +| [SetFallback](SetFallback.md) | 写入 shader 级 fallback 字符串元数据。 | +| [GetFallback](GetFallback.md) | 读取 shader 级 fallback 字符串。 | +| [AddPass](AddPass.md) | 追加一个完整 pass。 | +| [ClearPasses](ClearPasses.md) | 清空全部 pass。 | +| [GetPassCount](GetPassCount.md) | 返回当前 pass 数量。 | +| [GetPasses](GetPasses.md) | 读取 pass 列表。 | +| [AddPassVariant](AddPassVariant.md) | 向指定 pass 追加 stage variant。 | +| [SetPassTag](SetPassTag.md) | 为指定 pass 写入或覆盖 tag。 | +| [AddPassResourceBinding](AddPassResourceBinding.md) | 为指定 pass 写入或覆盖资源绑定描述。 | +| [AddPassKeywordDeclaration](AddPassKeywordDeclaration.md) | 为指定 pass 追加一条 keyword 声明。 | +| [HasPass](HasPass.md) | 判断是否存在指定名称的 pass。 | +| [FindPass](FindPass.md) | 按名称查找 pass。 | +| [PassDeclaresKeyword](PassDeclaresKeyword.md) | 判断指定 pass 是否声明某个 keyword。 | +| [DeclaresKeyword](DeclaresKeyword.md) | 判断任意 pass 是否声明某个 keyword。 | +| [FindPassResourceBinding](FindPassResourceBinding.md) | 在 pass 内按名称查找资源绑定。 | +| [FindVariant](FindVariant.md) | 在 pass 内按 stage/backend 查找最合适的 variant。 | +| [GetRHIResource](GetRHIResource.md) | 返回当前缓存的底层 `IRHIShader*`。 | +| [SetRHIResource](SetRHIResource.md) | 写入底层 `IRHIShader*` 缓存。 | ## 相关文档 - [当前目录](../Shader.md) - 返回 `Shader` 平行目录 +- [ShaderKeywordTypes](../ShaderKeywordTypes/ShaderKeywordTypes.md) - keyword 声明与集合语义 - [API 总索引](../../../../main.md) - 返回顶层索引 diff --git a/docs/api/XCEngine/Resources/Shader/Shader/ShaderAttribute.md b/docs/api/XCEngine/Resources/Shader/Shader/ShaderAttribute.md new file mode 100644 index 00000000..2adb0de6 --- /dev/null +++ b/docs/api/XCEngine/Resources/Shader/Shader/ShaderAttribute.md @@ -0,0 +1,28 @@ +# ShaderAttribute + +**命名空间**: `XCEngine::Resources` + +**类型**: `struct` + +**头文件**: `XCEngine/Resources/Shader/Shader.h` + +## 字段 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `name` | `Containers::String` | attribute 名称。 | +| `location` | `Core::uint32` | 顶点输入位置。 | +| `size` | `Core::uint32` | 反射得到的大小信息。 | +| `type` | `Core::uint32` | 反射得到的底层类型编号。 | + +## 当前语义 + +- 这是传统 vertex attribute 反射记录结构。 +- 与 [ShaderUniform](ShaderUniform.md) 类似，当前 manifest / artifact 路径不会主动构造这类记录；它更像 legacy / 手动填充的反射容器。 +- 目前仓库内直接使用它的地方主要是 `tests/Resources/Shader/test_shader.cpp`。 + +## 相关文档 + +- [Shader](Shader.md) +- [AddAttribute](AddAttribute.md) +- [GetAttributes](GetAttributes.md) diff --git a/docs/api/XCEngine/Resources/Shader/Shader/ShaderBackend.md b/docs/api/XCEngine/Resources/Shader/Shader/ShaderBackend.md new file mode 100644 index 00000000..12c5ad4e --- /dev/null +++ b/docs/api/XCEngine/Resources/Shader/Shader/ShaderBackend.md @@ -0,0 +1,33 @@ +# ShaderBackend + +**命名空间**: `XCEngine::Resources` + +**类型**: `enum class` + +**头文件**: `XCEngine/Resources/Shader/Shader.h` + +## 枚举值 + +| 值 | 含义 | +|------|------| +| `Generic` | 不绑定特定渲染后端的通用 variant。 | +| `D3D12` | Direct3D 12 variant。 | +| `OpenGL` | OpenGL variant。 | +| `Vulkan` | Vulkan variant。 | + +## 当前语义 + +- 该枚举主要用于 `ShaderStageVariant::backend` 和 `Shader::FindVariant(...)` 的 backend 精确匹配 / `Generic` 兜底逻辑。 +- `Rendering::Detail::ToShaderBackend(...)` 当前会把 `RHI::RHIType` 映射成该枚举。 +- 多 backend builtin shader 与 `.shader` manifest 当前都依赖它区分同一 pass 下的多个 stage variant。 + +## 测试覆盖 + +`tests/Resources/Shader/test_shader.cpp` 当前显式验证了 backend 精确命中优先，找不到时回退到 `Generic`。 +`tests/Resources/Shader/test_shader_loader.cpp` 当前还验证了 D3D12 / OpenGL / Vulkan 三套 variant 的加载结果。 + +## 相关文档 + +- [Shader](Shader.md) +- [ShaderStageVariant](ShaderStageVariant.md) +- [FindVariant](FindVariant.md) diff --git a/docs/api/XCEngine/Resources/Shader/Shader/ShaderLanguage.md b/docs/api/XCEngine/Resources/Shader/Shader/ShaderLanguage.md new file mode 100644 index 00000000..0302cb9e --- /dev/null +++ b/docs/api/XCEngine/Resources/Shader/Shader/ShaderLanguage.md @@ -0,0 +1,27 @@ +# ShaderLanguage + +**命名空间**: `XCEngine::Resources` + +**类型**: `enum class` + +**头文件**: `XCEngine/Resources/Shader/Shader.h` + +## 枚举值 + +| 值 | 含义 | +|------|------| +| `GLSL` | OpenGL / 通用 GLSL 源码。 | +| `HLSL` | HLSL 源码。 | +| `SPIRV` | SPIR-V 形式的 shader 代码或二进制语义。 | + +## 当前语义 + +- 这是 `ShaderStageVariant::language` 字段和 legacy `m_language` 字段使用的语言枚举。 +- `Rendering::Detail::ToRHIShaderLanguage(...)` 当前会把它映射到 RHI 层 `RHI::ShaderLanguage`。 +- `ShaderLoader` 当前会在 manifest / artifact / legacy 文件路径上写入该字段，并为 HLSL 生成默认 `entryPoint/profile`。 + +## 相关文档 + +- [Shader](Shader.md) +- [ShaderStageVariant](ShaderStageVariant.md) +- [SetShaderLanguage](SetShaderLanguage.md) diff --git a/docs/api/XCEngine/Resources/Shader/Shader/ShaderPass.md b/docs/api/XCEngine/Resources/Shader/Shader/ShaderPass.md new file mode 100644 index 00000000..a6c8dad4 --- /dev/null +++ b/docs/api/XCEngine/Resources/Shader/Shader/ShaderPass.md @@ -0,0 +1,47 @@ +# ShaderPass + +**命名空间**: `XCEngine::Resources` + +**类型**: `struct` + +**头文件**: `XCEngine/Resources/Shader/Shader.h` + +## 字段 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `name` | `Containers::String` | pass 名称。 | +| `hasFixedFunctionState` | `bool` | 当前 pass 是否显式携带 fixed-function 状态。 | +| `fixedFunctionState` | `MaterialRenderState` | 当前 pass 的 blend / depth / cull 基线状态。 | +| `tags` | `Containers::Array` | pass 级 tag 列表。 | +| `resources` | `Containers::Array` | pass 级资源绑定描述。 | +| `keywordDeclarations` | `Containers::Array` | pass 级 keyword pragma 声明。 | +| `variants` | `Containers::Array` | 该 pass 下的 stage/backend variant 列表。 | + +## 当前语义 + +- 这是 `Shader` 当前 pass-centric 元数据模型的核心结构。 +- 渲染路径不会只看 `name`；通常还会结合： + - `hasFixedFunctionState/fixedFunctionState` 作为 pass 级 fixed-function 渲染状态基线 + - `tags` 判断 builtin material pass 语义 + - `resources` 构建 descriptor layout + - `keywordDeclarations` 描述这个 pass 支持的 keyword 组合 + - `variants` 判断当前 backend 是否存在可编译的 graphics stages +- 若调用 `AddPassVariant(...)`、`SetPassTag(...)`、`AddPassResourceBinding(...)` 或 `AddPassKeywordDeclaration(...)` 时目标 pass 不存在，`Shader` 当前会先按名字自动创建它。 + +## 当前使用位置 + +- `BuiltinForwardPipeline::FindCompatibleSurfacePass(...)` 当前会优先看材质显式 pass 名，其次遍历 `Shader::GetPasses()` 做匹配和 fallback。 +- `ShaderLoader` 当前会把 unity-style / legacy authoring 中的 pass state、keyword pragma 和 backend variant 都落到这里。 +- `AssetDatabase` 与 `BuiltinResources` 当前都会序列化 / 反序列化 pass 下的 tags、resources、keyword declarations、fixed-function state 和 variants。 +- `RenderMaterialStateUtils::ResolveEffectiveRenderState(...)` 当前会把 `fixedFunctionState` 当作 shader pass 基线，再叠加材质 override。 + +## 相关文档 + +- [Shader](Shader.md) +- [ShaderPassTagEntry](ShaderPassTagEntry.md) +- [ShaderResourceBindingDesc](ShaderResourceBindingDesc.md) +- [ShaderStageVariant](ShaderStageVariant.md) +- [ShaderKeywordTypes](../ShaderKeywordTypes/ShaderKeywordTypes.md) +- [MaterialRenderState](../../Material/Material/MaterialRenderState.md) +- [FindPass](FindPass.md) diff --git a/docs/api/XCEngine/Resources/Shader/Shader/ShaderPassTagEntry.md b/docs/api/XCEngine/Resources/Shader/Shader/ShaderPassTagEntry.md new file mode 100644 index 00000000..b3ccb5ea --- /dev/null +++ b/docs/api/XCEngine/Resources/Shader/Shader/ShaderPassTagEntry.md @@ -0,0 +1,26 @@ +# ShaderPassTagEntry + +**命名空间**: `XCEngine::Resources` + +**类型**: `struct` + +**头文件**: `XCEngine/Resources/Shader/Shader.h` + +## 字段 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `name` | `Containers::String` | tag 键名。 | +| `value` | `Containers::String` | tag 值。 | + +## 当前语义 + +- `ShaderPass::tags` 当前使用这一结构表达 pass 级字符串元数据。 +- `.shader` manifest 加载时，`tags` JSON object 会被展开成一组 `ShaderPassTagEntry`。 +- 渲染管线当前会结合 pass 名和 tag 选择合适的 builtin material pass。 + +## 相关文档 + +- [Shader](Shader.md) +- [ShaderPass](ShaderPass.md) +- [SetPassTag](SetPassTag.md) diff --git a/docs/api/XCEngine/Resources/Shader/Shader/ShaderPropertyDesc.md b/docs/api/XCEngine/Resources/Shader/Shader/ShaderPropertyDesc.md new file mode 100644 index 00000000..6326e32e --- /dev/null +++ b/docs/api/XCEngine/Resources/Shader/Shader/ShaderPropertyDesc.md @@ -0,0 +1,35 @@ +# ShaderPropertyDesc + +**命名空间**: `XCEngine::Resources` + +**类型**: `struct` + +**头文件**: `XCEngine/Resources/Shader/Shader.h` + +## 字段 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `name` | `Containers::String` | property 的内部键名。 | +| `displayName` | `Containers::String` | Inspector / 编辑器可显示名称。 | +| `type` | `ShaderPropertyType` | property 类型。 | +| `defaultValue` | `Containers::String` | 默认值的字符串表示。 | +| `semantic` | `Containers::String` | 可选语义标签。 | + +## 当前语义 + +- 它描述材质层可消费的 shader property，而不是底层 descriptor binding。 +- `ShaderLoader` 当前在 manifest / artifact 路径上都会填充这组描述。 +- `Material.cpp` 和 `MaterialLoader.cpp` 当前依赖它决定材质属性类型映射、默认值构造以及材质文件解析策略。 + +## 测试覆盖 + +`tests/Resources/Shader/test_shader.cpp` 和 `tests/Resources/Shader/test_shader_loader.cpp` 当前都验证了 property 描述可被写入和读回。 +`tests/Rendering/unit/test_render_scene_extractor.cpp` 当前还依赖这些 property 语义驱动材质提取行为。 + +## 相关文档 + +- [Shader](Shader.md) +- [ShaderPropertyType](ShaderPropertyType.md) +- [AddProperty](AddProperty.md) +- [FindProperty](FindProperty.md) diff --git a/docs/api/XCEngine/Resources/Shader/Shader/ShaderPropertyType.md b/docs/api/XCEngine/Resources/Shader/Shader/ShaderPropertyType.md new file mode 100644 index 00000000..fae6dec9 --- /dev/null +++ b/docs/api/XCEngine/Resources/Shader/Shader/ShaderPropertyType.md @@ -0,0 +1,31 @@ +# ShaderPropertyType + +**命名空间**: `XCEngine::Resources` + +**类型**: `enum class` + +**头文件**: `XCEngine/Resources/Shader/Shader.h` + +## 枚举值 + +| 值 | 含义 | +|------|------| +| `Float` | 标量浮点属性。 | +| `Range` | 带范围语义的浮点属性。 | +| `Int` | 整型属性。 | +| `Vector` | 向量属性。 | +| `Color` | 颜色属性。 | +| `Texture2D` | 2D 纹理属性。 | +| `TextureCube` | Cubemap 属性。 | + +## 当前语义 + +- 头文件注释当前明确说明：这组 property kind 故意贴近 Unity 的公开 shader property 语义，便于未来复用运行时契约。 +- `Material.cpp` 当前把 `Float/Range` 映射为 `MaterialPropertyType::Float`，把 `Vector/Color` 映射为 `Float4`，把 `Texture2D/TextureCube` 映射为纹理类材质属性。 +- `MaterialLoader.cpp` 当前也按这个枚举解析材质文件里的属性值并校验类型兼容性。 + +## 相关文档 + +- [Shader](Shader.md) +- [ShaderPropertyDesc](ShaderPropertyDesc.md) +- [GetProperties](GetProperties.md) diff --git a/docs/api/XCEngine/Resources/Shader/Shader/ShaderResourceBindingDesc.md b/docs/api/XCEngine/Resources/Shader/Shader/ShaderResourceBindingDesc.md new file mode 100644 index 00000000..83da2002 --- /dev/null +++ b/docs/api/XCEngine/Resources/Shader/Shader/ShaderResourceBindingDesc.md @@ -0,0 +1,30 @@ +# ShaderResourceBindingDesc + +**命名空间**: `XCEngine::Resources` + +**类型**: `struct` + +**头文件**: `XCEngine/Resources/Shader/Shader.h` + +## 字段 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `name` | `Containers::String` | 绑定名。 | +| `type` | `ShaderResourceType` | 资源绑定类型。 | +| `set` | `Core::uint32` | descriptor set / register set。 | +| `binding` | `Core::uint32` | set 内的 binding 槽位。 | +| `semantic` | `Containers::String` | 可选语义标签。 | + +## 当前语义 + +- 它描述 pass 级资源绑定布局，而不是某次 draw call 的具体资源对象。 +- `.shader` manifest 与 `.xcshader` artifact 当前都会把每个 pass 的资源绑定写入这组结构。 +- `BuiltinForwardPipeline`、`BuiltinObjectIdPass` 等渲染路径当前直接消费这些绑定描述来构建 descriptor layout。 + +## 相关文档 + +- [Shader](Shader.md) +- [ShaderResourceType](ShaderResourceType.md) +- [ShaderPass](ShaderPass.md) +- [AddPassResourceBinding](AddPassResourceBinding.md) diff --git a/docs/api/XCEngine/Resources/Shader/Shader/ShaderResourceType.md b/docs/api/XCEngine/Resources/Shader/Shader/ShaderResourceType.md new file mode 100644 index 00000000..a13a07d5 --- /dev/null +++ b/docs/api/XCEngine/Resources/Shader/Shader/ShaderResourceType.md @@ -0,0 +1,31 @@ +# ShaderResourceType + +**命名空间**: `XCEngine::Resources` + +**类型**: `enum class` + +**头文件**: `XCEngine/Resources/Shader/Shader.h` + +## 枚举值 + +| 值 | 含义 | +|------|------| +| `ConstantBuffer` | 常量缓冲区绑定。 | +| `Texture2D` | 2D 纹理资源绑定。 | +| `TextureCube` | Cubemap 资源绑定。 | +| `Sampler` | 采样器绑定。 | + +## 当前语义 + +- 该枚举描述 `ShaderResourceBindingDesc::type`。 +- `BuiltinForwardPipeline.cpp` 当前会把它映射到 descriptor 语义： + - `ConstantBuffer -> CBV` + - `Texture2D/TextureCube -> SRV` + - `Sampler -> Sampler` +- 它也决定资源绑定应落在哪类 descriptor heap。 + +## 相关文档 + +- [Shader](Shader.md) +- [ShaderResourceBindingDesc](ShaderResourceBindingDesc.md) +- [FindPassResourceBinding](FindPassResourceBinding.md) diff --git a/docs/api/XCEngine/Resources/Shader/Shader/ShaderStageVariant.md b/docs/api/XCEngine/Resources/Shader/Shader/ShaderStageVariant.md new file mode 100644 index 00000000..0d3515dc --- /dev/null +++ b/docs/api/XCEngine/Resources/Shader/Shader/ShaderStageVariant.md @@ -0,0 +1,37 @@ +# ShaderStageVariant + +**命名空间**: `XCEngine::Resources` + +**类型**: `struct` + +**头文件**: `XCEngine/Resources/Shader/Shader.h` + +## 字段 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `stage` | `ShaderType` | shader 阶段。 | +| `language` | `ShaderLanguage` | 源码语言。 | +| `backend` | `ShaderBackend` | 目标后端。 | +| `entryPoint` | `Containers::String` | 入口点。 | +| `profile` | `Containers::String` | 编译 profile。 | +| `sourceCode` | `Containers::String` | 当前保存的源码文本。 | +| `compiledBinary` | `Containers::Array` | 可选编译后二进制。 | + +## 当前语义 + +- 这是当前 shader 元数据模型里真正承载“某个 pass 在某个 backend 下某个 stage 的可编译内容”的结构。 +- `ShaderLoader` 当前会为 manifest variant 生成默认 `entryPoint/profile`： + - HLSL 默认 `MainVS/MainPS/...` 与 `vs_5_0/ps_5_0/...` + - GLSL/OpenGL 默认 `main` 与 `*_4_30` + - GLSL/Vulkan 默认 `main` 与 `*_4_50` +- `Rendering::Detail::ApplyShaderStageVariant(...)` 当前直接读取 `sourceCode/language/entryPoint/profile` 填充 RHI 编译描述。 +- `compiledBinary` 当前可由 artifact 反序列化或手动设置写入，但并不是所有运行时路径都会优先消费它。 + +## 相关文档 + +- [Shader](Shader.md) +- [ShaderType](ShaderType.md) +- [ShaderLanguage](ShaderLanguage.md) +- [ShaderBackend](ShaderBackend.md) +- [FindVariant](FindVariant.md) diff --git a/docs/api/XCEngine/Resources/Shader/Shader/ShaderType.md b/docs/api/XCEngine/Resources/Shader/Shader/ShaderType.md new file mode 100644 index 00000000..72f54f4b --- /dev/null +++ b/docs/api/XCEngine/Resources/Shader/Shader/ShaderType.md @@ -0,0 +1,35 @@ +# ShaderType + +**命名空间**: `XCEngine::Resources` + +**类型**: `enum class` + +**头文件**: `XCEngine/Resources/Shader/Shader.h` + +## 枚举值 + +| 值 | 含义 | +|------|------| +| `Vertex` | 顶点阶段。 | +| `Fragment` | 片段 / 像素阶段。 | +| `Geometry` | 几何阶段。 | +| `Compute` | 计算阶段。 | +| `Hull` | 曲面细分 Hull 阶段。 | +| `Domain` | 曲面细分 Domain 阶段。 | + +## 当前语义 + +- 这是 `ShaderStageVariant::stage` 的阶段枚举，也是 `Shader::FindVariant(...)` 的筛选条件之一。 +- legacy 单 stage `Shader` 视图中的 `m_shaderType` 也使用它；调用 `SetShaderType(...)` 时会同步到默认 `"Default"` pass 下的 `Generic` variant。 +- `ShaderLoader` 当前会基于文件扩展名、manifest 字段和 artifact 数据把阶段写入这个枚举。 + +## 当前使用位置 + +- `Rendering::Detail::ShaderPassHasGraphicsVariants(...)` 当前要求同一 pass 至少存在 `Vertex` 和 `Fragment` 两类 variant。 +- `BuiltinForwardPipeline`、`BuiltinInfiniteGridPass`、`BuiltinObjectIdPass` 等渲染路径当前通过它选择具体 backend 的 vertex / fragment variant。 + +## 相关文档 + +- [Shader](Shader.md) +- [ShaderStageVariant](ShaderStageVariant.md) +- [FindVariant](FindVariant.md) diff --git a/docs/api/XCEngine/Resources/Shader/Shader/ShaderUniform.md b/docs/api/XCEngine/Resources/Shader/Shader/ShaderUniform.md new file mode 100644 index 00000000..f93cfeb8 --- /dev/null +++ b/docs/api/XCEngine/Resources/Shader/Shader/ShaderUniform.md @@ -0,0 +1,28 @@ +# ShaderUniform + +**命名空间**: `XCEngine::Resources` + +**类型**: `struct` + +**头文件**: `XCEngine/Resources/Shader/Shader.h` + +## 字段 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `name` | `Containers::String` | uniform 名称。 | +| `location` | `Core::uint32` | 反射得到的位置 / 槽位。 | +| `size` | `Core::uint32` | 反射得到的大小信息。 | +| `type` | `Core::uint32` | 反射得到的底层类型编号。 | + +## 当前语义 + +- 这是传统 uniform 反射记录结构。 +- 当前 `ShaderLoader` 的 manifest / artifact 路径并不会主动填充它；项目中的主流 shader 元数据路径现在更偏向 `property + pass + resource binding + variant`。 +- 目前仓库内该结构的直接写入和读取主要出现在 `tests/Resources/Shader/test_shader.cpp`。 + +## 相关文档 + +- [Shader](Shader.md) +- [AddUniform](AddUniform.md) +- [GetUniforms](GetUniforms.md) diff --git a/docs/api/XCEngine/Resources/Shader/ShaderKeywordTypes/ShaderKeywordTypes.md b/docs/api/XCEngine/Resources/Shader/ShaderKeywordTypes/ShaderKeywordTypes.md new file mode 100644 index 00000000..50542381 --- /dev/null +++ b/docs/api/XCEngine/Resources/Shader/ShaderKeywordTypes/ShaderKeywordTypes.md @@ -0,0 +1,52 @@ +# ShaderKeywordTypes + +**命名空间**: `XCEngine::Resources` + +**类型**: `enum + structs + inline helpers` + +**头文件**: `XCEngine/Resources/Shader/ShaderKeywordTypes.h` + +**描述**: shader keyword 声明、启用集与归一化 helper，服务于 shader variant 生成、材质 keyword 开关和渲染期 variant 选择。 + +## 声明概览 + +| 声明 | 类型 | 说明 | +|------|------|------| +| `ShaderKeywordDeclarationType` | `enum class` | 当前公开 `MultiCompile`、`ShaderFeature`、`ShaderFeatureLocal`、`MultiCompileLocal` 四类 pragma。 | +| `ShaderKeywordDeclaration` | `struct` | 单条 keyword 声明，保存 declaration type 与 `options`。 | +| `ShaderKeywordSet` | `struct` | 当前启用 keyword 的字符串集合。 | +| `IsShaderKeywordPlaceholderToken(...)` | `inline helper` | 识别 `_` / `__` 这种占位 token。 | +| `NormalizeShaderKeywordToken(...)` | `inline helper` | trim、丢弃空串和占位 token。 | +| `NormalizeShaderKeywordSetInPlace(...)` | `inline helper` | 去重、去占位并按字典序排序。 | +| `ShaderKeywordSetContains(...)` | `inline helper` | 在归一化语义下判断 keyword 是否启用。 | +| `IsShaderKeywordSubset(...)` | `inline helper` | 判断一组 required keywords 是否被 enabled 集合覆盖。 | +| `CombineShaderKeywordSets(...)` | `inline helper` | 合并两个集合后再做统一归一化。 | + +## 当前语义 + +- `ShaderKeywordDeclaration::IsLocal()` 当前只把 `ShaderFeatureLocal` 和 `MultiCompileLocal` 视为 local keyword 声明。 +- `NormalizeShaderKeywordToken(...)` 会先 `Trim()`，然后把 `_`、`__` 和空串统一压成“未启用”状态。 +- `NormalizeShaderKeywordSetInPlace(...)` 的最终结果有三个特点： + - 不包含占位 token + - 不包含重复项 + - 结果按 `strcmp` 字典序稳定排序 +- `CombineShaderKeywordSets(...)` 不是简单拼接；它最终仍会回到同一套归一化语义。 + +## 当前调用链 + +- `ShaderLoader.cpp` 用这组类型解析 `#pragma multi_compile`、`#pragma multi_compile_local`、`#pragma shader_feature` 与 `#pragma shader_feature_local`。 +- `Shader.cpp` 用 `IsShaderKeywordSubset(...)` 与归一化后的 `ShaderKeywordSet` 做 variant 命中判定。 +- `Material.cpp` 在材质 keyword 写入时复用 `NormalizeShaderKeywordToken(...)`。 +- `BuiltinForwardPipelineResources.cpp`、`BuiltinDepthStylePassBaseResources.cpp` 与 `CameraRenderer.cpp` 会组合全局 / 材质 keyword 集合后再选 shader variant。 + +## 测试锚点 + +- `tests/Resources/Shader/test_shader_loader.cpp` 当前覆盖了 legacy backend-split 与 unity-style single-source 两条路径下的 keyword 声明解析、variant 展开和 required keyword 顺序。 +- `tests/Resources/Shader/test_shader.cpp` 当前覆盖了 shader 对 keyword 声明和 variant 选择的公开行为。 +- `tests/Rendering/unit/test_camera_scene_renderer.cpp` 当前直接依赖 `ShaderKeywordSetContains(...)` 检查渲染期全局 keyword。 + +## 相关文档 + +- [Shader](../Shader.md) +- [Shader](../Shader/Shader.md) +- [Rendering](../../../Rendering/Rendering.md) diff --git a/docs/api/XCEngine/Resources/Shader/ShaderLoader/CanLoad.md b/docs/api/XCEngine/Resources/Shader/ShaderLoader/CanLoad.md index 57667e99..f8c2d132 100644 --- a/docs/api/XCEngine/Resources/Shader/ShaderLoader/CanLoad.md +++ b/docs/api/XCEngine/Resources/Shader/ShaderLoader/CanLoad.md @@ -1,31 +1,42 @@ # ShaderLoader::CanLoad -判断当前条件下是否可执行。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Shader/ShaderLoader.h` + +## 签名 ```cpp bool CanLoad(const Containers::String& path) const override; ``` -该方法声明于 `XCEngine/Resources/Shader/ShaderLoader.h`，当前页面用于固定 `ShaderLoader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `path` - 参数语义详见头文件声明。 +判断给定路径是否属于当前 loader 可识别的 shader 路径。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** +- 若 `path` 是 builtin shader 虚拟路径，立即返回 `true`。 +- 否则取扩展名并转为小写，接受以下后缀： + - `vert` + - `frag` + - `geom` + - `comp` + - `glsl` + - `hlsl` + - `shader` + - `xcshader` +- 其他扩展名返回 `false`。 -```cpp -#include +## 当前边界 -void Example() { - XCEngine::Resources::ShaderLoader object; - // 根据上下文补齐参数后调用 ShaderLoader::CanLoad(...)。 - (void)object; -} -``` +- 该方法不检查文件是否存在，也不验证内容是否合法。 +- `.shader` 是否走 manifest 解析路径，只有在真正 `Load(...)` 时才会继续判定。 ## 相关文档 -- [返回类总览](ShaderLoader.md) -- [返回模块目录](../Shader.md) +- [ShaderLoader](ShaderLoader.md) +- [GetSupportedExtensions](GetSupportedExtensions.md) +- [Load](Load.md) diff --git a/docs/api/XCEngine/Resources/Shader/ShaderLoader/CollectSourceDependencies.md b/docs/api/XCEngine/Resources/Shader/ShaderLoader/CollectSourceDependencies.md new file mode 100644 index 00000000..2d4f1e07 --- /dev/null +++ b/docs/api/XCEngine/Resources/Shader/ShaderLoader/CollectSourceDependencies.md @@ -0,0 +1,47 @@ +# ShaderLoader::CollectSourceDependencies + +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Shader/ShaderLoader.h` + +## 签名 + +```cpp +bool CollectSourceDependencies( + const Containers::String& path, + Containers::Array& outDependencies) const; +``` + +## 作用 + +收集一个 shader 源资源当前依赖的额外源文件路径，供导入缓存和重导入判定使用。 + +## 当前实现行为 + +- 先清空 `outDependencies`。 +- 若 `path` 是 builtin shader 虚拟路径，直接返回 `true`，且不产生依赖项。 +- 若扩展名不是 `.shader`，当前也直接返回 `true`；这意味着 legacy 单 stage `.vert/.frag/.glsl/.hlsl` 文件不会额外声明依赖。 +- 对 `.shader` 文件，会先读文件内容；读取失败时返回 `false`。 +- 若文件内容是 manifest 形态，会遍历每个 pass 的 `variants`，提取 `source` / `sourcePath` 字段。 +- 若不是 manifest，则会按当前 authoring 风格继续分派： + - unity-style single-source `.shader` 会收集 `HLSLINCLUDE/HLSLPROGRAM` 中的带引号 `#include` + - 其他 legacy 单文件形态保持“无额外依赖”结果 +- 相对路径会基于 manifest 所在目录和当前 `ResourceManager::Get().GetResourceRoot()` 做规范化解析。 +- 最终结果会去重后写入 `outDependencies`。 + +## 当前调用位置 + +- `AssetDatabase::CollectShaderDependencies(...)` 当前直接调用它，把收集到的文件转成 artifact 依赖记录。 +- 这条链路决定了 `.shader` manifest 引用的 stage 文件、以及 unity-style single-source shader 引用的 include 文件改动后，artifact 是否会被重新生成。 + +## 测试覆盖 + +`tests/Resources/Shader/test_shader_loader.cpp` 当前通过 stage 依赖与 unity-style include 依赖场景间接验证了 dependency 收集会驱动 shader artifact 重导入。 + +## 相关文档 + +- [ShaderLoader](ShaderLoader.md) +- [Load](Load.md) +- [AssetDatabase::EnsureArtifact](../../../Core/Asset/AssetDatabase/EnsureArtifact.md) diff --git a/docs/api/XCEngine/Resources/Shader/ShaderLoader/Constructor.md b/docs/api/XCEngine/Resources/Shader/ShaderLoader/Constructor.md index 3ff6a290..800ae437 100644 --- a/docs/api/XCEngine/Resources/Shader/ShaderLoader/Constructor.md +++ b/docs/api/XCEngine/Resources/Shader/ShaderLoader/Constructor.md @@ -1,28 +1,25 @@ # ShaderLoader::ShaderLoader() -构造对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Shader/ShaderLoader.h` + +## 签名 ```cpp ShaderLoader(); ``` -该方法声明于 `XCEngine/Resources/Shader/ShaderLoader.h`，当前页面用于固定 `ShaderLoader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +构造 `ShaderLoader` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::ShaderLoader object; -} -``` +- 当前为默认构造实现。 ## 相关文档 -- [返回类总览](ShaderLoader.md) -- [返回模块目录](../Shader.md) +- [ShaderLoader](ShaderLoader.md) diff --git a/docs/api/XCEngine/Resources/Shader/ShaderLoader/Destructor.md b/docs/api/XCEngine/Resources/Shader/ShaderLoader/Destructor.md index f07b8446..b6eceebe 100644 --- a/docs/api/XCEngine/Resources/Shader/ShaderLoader/Destructor.md +++ b/docs/api/XCEngine/Resources/Shader/ShaderLoader/Destructor.md @@ -1,29 +1,25 @@ # ShaderLoader::~ShaderLoader() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Shader/ShaderLoader.h` + +## 签名 ```cpp virtual ~ShaderLoader() override; ``` -该方法声明于 `XCEngine/Resources/Shader/ShaderLoader.h`，当前页面用于固定 `ShaderLoader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +销毁 `ShaderLoader` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::ShaderLoader object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 当前为默认析构实现。 ## 相关文档 -- [返回类总览](ShaderLoader.md) -- [返回模块目录](../Shader.md) +- [ShaderLoader](ShaderLoader.md) diff --git a/docs/api/XCEngine/Resources/Shader/ShaderLoader/GetDefaultSettings.md b/docs/api/XCEngine/Resources/Shader/ShaderLoader/GetDefaultSettings.md index a89363f1..9e4c7d97 100644 --- a/docs/api/XCEngine/Resources/Shader/ShaderLoader/GetDefaultSettings.md +++ b/docs/api/XCEngine/Resources/Shader/ShaderLoader/GetDefaultSettings.md @@ -1,30 +1,31 @@ # ShaderLoader::GetDefaultSettings -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Shader/ShaderLoader.h` + +## 签名 ```cpp ImportSettings* GetDefaultSettings() const override; ``` -该方法声明于 `XCEngine/Resources/Shader/ShaderLoader.h`，当前页面用于固定 `ShaderLoader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回此 loader 的默认导入设置对象。 -**返回：** `ImportSettings*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** +- 当前固定返回 `nullptr`。 -```cpp -#include +## 当前语义 -void Example() { - XCEngine::Resources::ShaderLoader object; - // 根据上下文补齐参数后调用 ShaderLoader::GetDefaultSettings(...)。 - (void)object; -} -``` +- 这意味着 `ShaderLoader` 当前没有独立的 `ImportSettings` 子类，也没有一套需要由调用方保存和回传的默认 shader 导入配置。 +- `Load(...)` 当前会显式忽略传入的 `settings` 参数。 ## 相关文档 -- [返回类总览](ShaderLoader.md) -- [返回模块目录](../Shader.md) +- [ShaderLoader](ShaderLoader.md) +- [Load](Load.md) diff --git a/docs/api/XCEngine/Resources/Shader/ShaderLoader/GetResourceType.md b/docs/api/XCEngine/Resources/Shader/ShaderLoader/GetResourceType.md index 7d46e57d..3a536659 100644 --- a/docs/api/XCEngine/Resources/Shader/ShaderLoader/GetResourceType.md +++ b/docs/api/XCEngine/Resources/Shader/ShaderLoader/GetResourceType.md @@ -1,30 +1,30 @@ # ShaderLoader::GetResourceType -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Shader/ShaderLoader.h` + +## 签名 ```cpp ResourceType GetResourceType() const override; ``` -该方法声明于 `XCEngine/Resources/Shader/ShaderLoader.h`，当前页面用于固定 `ShaderLoader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回该 loader 所服务的资源类型。 -**返回：** `ResourceType` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** +- 头文件内联实现为直接返回 `ResourceType::Shader`。 +- 不依赖 loader 的任何内部状态。 -```cpp -#include +## 返回值 -void Example() { - XCEngine::Resources::ShaderLoader object; - // 根据上下文补齐参数后调用 ShaderLoader::GetResourceType(...)。 - (void)object; -} -``` +- 始终返回 `ResourceType::Shader`。 ## 相关文档 -- [返回类总览](ShaderLoader.md) -- [返回模块目录](../Shader.md) +- [ShaderLoader](ShaderLoader.md) diff --git a/docs/api/XCEngine/Resources/Shader/ShaderLoader/GetSupportedExtensions.md b/docs/api/XCEngine/Resources/Shader/ShaderLoader/GetSupportedExtensions.md index cfa9694b..986e0dc5 100644 --- a/docs/api/XCEngine/Resources/Shader/ShaderLoader/GetSupportedExtensions.md +++ b/docs/api/XCEngine/Resources/Shader/ShaderLoader/GetSupportedExtensions.md @@ -1,30 +1,41 @@ # ShaderLoader::GetSupportedExtensions -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Shader/ShaderLoader.h` + +## 签名 ```cpp Containers::Array GetSupportedExtensions() const override; ``` -该方法声明于 `XCEngine/Resources/Shader/ShaderLoader.h`，当前页面用于固定 `ShaderLoader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回当前 loader 支持识别的 shader 文件扩展名。 -**返回：** `Containers::Array` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** +- 当前实现依次写入： + - `vert` + - `frag` + - `geom` + - `comp` + - `glsl` + - `hlsl` + - `shader` + - `xcshader` +- 返回值每次调用都会重新构造。 -```cpp -#include +## 当前边界 -void Example() { - XCEngine::Resources::ShaderLoader object; - // 根据上下文补齐参数后调用 ShaderLoader::GetSupportedExtensions(...)。 - (void)object; -} -``` +- 该列表是“扩展名支持集”，不是完整能力说明。 +- 即使扩展名被列出，具体路径是否能成功加载仍取决于后续 `Load(...)` 分支与文件内容。 ## 相关文档 -- [返回类总览](ShaderLoader.md) -- [返回模块目录](../Shader.md) +- [ShaderLoader](ShaderLoader.md) +- [CanLoad](CanLoad.md) +- [Load](Load.md) diff --git a/docs/api/XCEngine/Resources/Shader/ShaderLoader/Load.md b/docs/api/XCEngine/Resources/Shader/ShaderLoader/Load.md index cb35af68..169e6286 100644 --- a/docs/api/XCEngine/Resources/Shader/ShaderLoader/Load.md +++ b/docs/api/XCEngine/Resources/Shader/ShaderLoader/Load.md @@ -1,32 +1,68 @@ # ShaderLoader::Load -加载资源或数据。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Shader/ShaderLoader.h` + +## 签名 ```cpp LoadResult Load(const Containers::String& path, const ImportSettings* settings = nullptr) override; ``` -该方法声明于 `XCEngine/Resources/Shader/ShaderLoader.h`，当前页面用于固定 `ShaderLoader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `path` - 参数语义详见头文件声明。 -- `settings` - 参数语义详见头文件声明。 +把路径对应的 shader 资源加载成 `LoadResult`。 -**返回：** `LoadResult` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** +- 传入的 `settings` 参数当前被显式忽略。 +- builtin shader 虚拟路径会直接走 `CreateBuiltinShaderResource(path)`。 +- 扩展名为 `.xcshader` 时，会走 `LoadShaderArtifact(path)`。 +- 其他路径会先读文件： + - 读取失败时，返回失败的 `LoadResult("Failed to read shader file: ...")` +- 扩展名为 `.shader` 且内容看起来像 manifest 时，会走 `LoadShaderManifest(path, sourceText)`： + - 解析 `properties` + - 解析 `passes/tags/resources/variants` + - 读取 variant `source/sourcePath` + - 自动补全默认 `entryPoint/profile` +- 若不是 manifest，则会进一步检测 authoring 风格： + - unity-style single-source `.shader` -> `LoadUnityStyleSingleSourceShaderAuthoring(path, sourceText)` + - 其他情况 -> `LoadLegacySingleStageShader(path, sourceText)` +- unity-style single-source 分支当前会解析： + - `Shader / Properties / SubShader / Pass` + - `Tags / Fallback` + - `Cull / ZWrite / ZTest / Blend / ColorMask` + - `HLSLINCLUDE / HLSLPROGRAM` + - `#pragma vertex / fragment / target / multi_compile / shader_feature` +- legacy 单文件分支会： + - 语言主要由扩展名决定 + - 阶段主要由路径扩展名决定 + - 结果写入 legacy 单 stage `Shader` 视图 -```cpp -#include +## 失败路径 -void Example() { - XCEngine::Resources::ShaderLoader object; - // 根据上下文补齐参数后调用 ShaderLoader::Load(...)。 - (void)object; -} -``` +- 文件不可读会直接失败。 +- manifest 缺少合法 `passes`、`variants`、`name`、`type`、`backend`、`language`、`source/sourceCode` 等字段时会返回失败。 +- unity-style single-source authoring 当前会拒绝： + - `#pragma backend` + - `Resources { ... }` + - 缺少 `HLSLPROGRAM` 的 `Pass` +- artifact 头、schema 或 payload 非法时也会返回失败。 + +## 测试覆盖 + +`tests/Resources/Shader/test_shader_loader.cpp` 当前覆盖了： + +- legacy 单 stage shader 加载 +- `.shader` manifest 加载 +- `.xcshader` artifact 加载 +- builtin shader 加载 +- manifest 依赖改动触发重导入 ## 相关文档 -- [返回类总览](ShaderLoader.md) -- [返回模块目录](../Shader.md) +- [ShaderLoader](ShaderLoader.md) +- [CollectSourceDependencies](CollectSourceDependencies.md) diff --git a/docs/api/XCEngine/Resources/Shader/ShaderLoader/ShaderLoader.md b/docs/api/XCEngine/Resources/Shader/ShaderLoader/ShaderLoader.md index f0c19981..bc71feef 100644 --- a/docs/api/XCEngine/Resources/Shader/ShaderLoader/ShaderLoader.md +++ b/docs/api/XCEngine/Resources/Shader/ShaderLoader/ShaderLoader.md @@ -6,29 +6,53 @@ **头文件**: `XCEngine/Resources/Shader/ShaderLoader.h` -**描述**: 定义 `XCEngine/Resources/Shader` 子目录中的 `ShaderLoader` public API。 +**描述**: Shader 资源 loader，负责识别 builtin / artifact / manifest / legacy 单文件 shader 路径，并把它们统一转换成 `Shader` 资源对象。 -## 概述 +## 概览 -`ShaderLoader.h` 是 `XCEngine/Resources/Shader` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。 +`ShaderLoader` 是 `Shader` 资源的导入入口。按当前 `ShaderLoader.cpp`，它至少覆盖五条加载路径： + +1. builtin shader 虚拟路径 + 直接走 `CreateBuiltinShaderResource(...)` +2. `.xcshader` artifact + 走二进制 artifact 反序列化 +3. `.shader` manifest + 解析 legacy backend-split manifest +4. `.shader` unity-style single-source authoring + 解析 `Shader / Properties / SubShader / Pass / HLSLPROGRAM` 语法子集 +5. 其他 legacy 单文件 shader + 读文本源码，按路径推断 stage，回填到 legacy 单 stage `Shader` 视图 + +## 当前加载模型 + +- `CanLoad(...)` 只按虚拟 builtin 路径或扩展名判定，不检查文件是否存在。 +- `Load(...)` 对 `.shader` 会先判断是否是 legacy manifest；若不是，再进入 unity-style single-source / legacy 单文件分派。 +- `CollectSourceDependencies(...)` 当前既覆盖 manifest 依赖，也覆盖 unity-style single-source authoring 里的 `#include` 与引用源文件。 + +## 当前实现边界 + +- `GetDefaultSettings()` 当前固定返回 `nullptr`，说明 loader 目前没有独立的 shader import settings 对象。 +- `DetectShaderType(...)` 当前本质上仍以文件路径扩展名为准，没有深入分析源码内容。 +- unity-style single-source parser 当前已经支持一批 ShaderLab 风格语法，但还不是完整 Unity ShaderLab 兼容实现。 ## 声明概览 | 声明 | 类型 | 说明 | |------|------|------| -| `ShaderLoader` | `class` | 继承自 `IResourceLoader` 的公开声明。 | +| `ShaderLoader` | `class` | `Shader` 资源的加载器。 | ## 公共方法 | 方法 | 描述 | |------|------| -| [ShaderLoader()](Constructor.md) | 构造对象。 | -| [~ShaderLoader()](Destructor.md) | 销毁对象并释放相关资源。 | -| [GetResourceType](GetResourceType.md) | 获取相关状态或对象。 | -| [GetSupportedExtensions](GetSupportedExtensions.md) | 获取相关状态或对象。 | -| [CanLoad](CanLoad.md) | 判断当前条件下是否可执行。 | -| [Load](Load.md) | 加载资源或数据。 | -| [GetDefaultSettings](GetDefaultSettings.md) | 获取相关状态或对象。 | +| [ShaderLoader()](Constructor.md) | 构造 `ShaderLoader` 实例。 | +| [~ShaderLoader()](Destructor.md) | 销毁 `ShaderLoader` 实例。 | +| [GetResourceType](GetResourceType.md) | 返回固定资源类型 `ResourceType::Shader`。 | +| [GetSupportedExtensions](GetSupportedExtensions.md) | 返回当前 loader 认可的 shader 扩展名集合。 | +| [CanLoad](CanLoad.md) | 判断路径是否属于 builtin shader 或支持的 shader 扩展名。 | +| [Load](Load.md) | 按 builtin / artifact / manifest / unity-style authoring / legacy 单文件多条路径加载 shader。 | +| [GetDefaultSettings](GetDefaultSettings.md) | 返回当前默认 import settings；当前固定为 `nullptr`。 | +| [CollectSourceDependencies](CollectSourceDependencies.md) | 收集 `.shader` 资源引用的 stage 文件或 include 依赖。 | ## 相关文档 diff --git a/docs/api/XCEngine/Resources/Texture/Texture/Constructor.md b/docs/api/XCEngine/Resources/Texture/Texture/Constructor.md index 852b3656..07f4e495 100644 --- a/docs/api/XCEngine/Resources/Texture/Texture/Constructor.md +++ b/docs/api/XCEngine/Resources/Texture/Texture/Constructor.md @@ -1,28 +1,27 @@ # Texture::Texture() -构造对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/Texture.h` + +## 签名 ```cpp Texture(); ``` -该方法声明于 `XCEngine/Resources/Texture/Texture.h`，当前页面用于固定 `Texture` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +构造一份空的纹理资源对象。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Texture object; -} -``` +- 构造函数是 `= default`。 +- 宽高、mip、数组层数和像素缓冲都保持成员默认值。 ## 相关文档 -- [返回类总览](Texture.md) -- [返回模块目录](../Texture.md) +- [Texture](Texture.md) +- [Create](Create.md) diff --git a/docs/api/XCEngine/Resources/Texture/Texture/Create.md b/docs/api/XCEngine/Resources/Texture/Texture/Create.md index 04bcba99..c84e1c4f 100644 --- a/docs/api/XCEngine/Resources/Texture/Texture/Create.md +++ b/docs/api/XCEngine/Resources/Texture/Texture/Create.md @@ -1,38 +1,30 @@ # Texture::Create -创建新对象或资源。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/Texture.h` + +## 签名 ```cpp bool Create(Core::uint32 width, Core::uint32 height, Core::uint32 depth, Core::uint32 mipLevels, TextureType type, TextureFormat format, const void* data, size_t dataSize); ``` -该方法声明于 `XCEngine/Resources/Texture/Texture.h`，当前页面用于固定 `Texture` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `width` - 参数语义详见头文件声明。 -- `height` - 参数语义详见头文件声明。 -- `depth` - 参数语义详见头文件声明。 -- `mipLevels` - 参数语义详见头文件声明。 -- `type` - 参数语义详见头文件声明。 -- `format` - 参数语义详见头文件声明。 -- `data` - 参数语义详见头文件声明。 -- `dataSize` - 参数语义详见头文件声明。 +写入纹理描述字段，并可选把一段像素数据拷贝到内部缓冲。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Texture object; - // 根据上下文补齐参数后调用 Texture::Create(...)。 - (void)object; -} -``` +- 把 `width`、`height`、`depth`、`mipLevels`、`type`、`format` 写入成员。 +- 如果 `data` 非空且 `dataSize > 0`，会调整 `m_pixelData` 大小并执行一次 `memcpy`。 +- 把 `m_memorySize` 设为 `dataSize`。 +- 当前实现不创建 GPU 资源，也不做额外格式校验；最后始终返回 `true`。 ## 相关文档 -- [返回类总览](Texture.md) -- [返回模块目录](../Texture.md) +- [Texture](Texture.md) +- [GetPixelData](GetPixelData.md) +- [GetMemorySize](GetMemorySize.md) diff --git a/docs/api/XCEngine/Resources/Texture/Texture/Destructor.md b/docs/api/XCEngine/Resources/Texture/Texture/Destructor.md index a1bbb017..a7a828f9 100644 --- a/docs/api/XCEngine/Resources/Texture/Texture/Destructor.md +++ b/docs/api/XCEngine/Resources/Texture/Texture/Destructor.md @@ -1,29 +1,27 @@ # Texture::~Texture() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/Texture.h` + +## 签名 ```cpp virtual ~Texture() override; ``` -该方法声明于 `XCEngine/Resources/Texture/Texture.h`，当前页面用于固定 `Texture` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +销毁纹理对象。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Texture object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 析构函数当前是 `= default`。 +- 不额外执行 GPU 释放或 mip 生成逻辑。 ## 相关文档 -- [返回类总览](Texture.md) -- [返回模块目录](../Texture.md) +- [Texture](Texture.md) +- [Release](Release.md) diff --git a/docs/api/XCEngine/Resources/Texture/Texture/GenerateMipmaps.md b/docs/api/XCEngine/Resources/Texture/Texture/GenerateMipmaps.md index f0506948..2b5a0c88 100644 --- a/docs/api/XCEngine/Resources/Texture/Texture/GenerateMipmaps.md +++ b/docs/api/XCEngine/Resources/Texture/Texture/GenerateMipmaps.md @@ -1,30 +1,27 @@ # Texture::GenerateMipmaps -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/Texture.h` + +## 签名 ```cpp bool GenerateMipmaps(); ``` -该方法声明于 `XCEngine/Resources/Texture/Texture.h`，当前页面用于固定 `Texture` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +为当前纹理生成 mipmaps。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Texture object; - // 根据上下文补齐参数后调用 Texture::GenerateMipmaps(...)。 - (void)object; -} -``` +- `engine/src/Resources/Texture/Texture.cpp` 里当前直接返回 `false`。 +- 也就是说这项能力现在还没有实际实现。 ## 相关文档 -- [返回类总览](Texture.md) -- [返回模块目录](../Texture.md) +- [Texture](Texture.md) +- [GetMipLevels](GetMipLevels.md) diff --git a/docs/api/XCEngine/Resources/Texture/Texture/GetArraySize.md b/docs/api/XCEngine/Resources/Texture/Texture/GetArraySize.md index d3fc8c48..ab1e98f8 100644 --- a/docs/api/XCEngine/Resources/Texture/Texture/GetArraySize.md +++ b/docs/api/XCEngine/Resources/Texture/Texture/GetArraySize.md @@ -1,30 +1,26 @@ # Texture::GetArraySize -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/Texture.h` + +## 签名 ```cpp Core::uint32 GetArraySize() const; ``` -该方法声明于 `XCEngine/Resources/Texture/Texture.h`，当前页面用于固定 `Texture` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回数组纹理的层数。 -**返回：** `Core::uint32` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Texture object; - // 根据上下文补齐参数后调用 Texture::GetArraySize(...)。 - (void)object; -} -``` +- 内联返回成员 `m_arraySize`。 ## 相关文档 -- [返回类总览](Texture.md) -- [返回模块目录](../Texture.md) +- [Texture](Texture.md) +- [GetTextureType](GetTextureType.md) diff --git a/docs/api/XCEngine/Resources/Texture/Texture/GetDepth.md b/docs/api/XCEngine/Resources/Texture/Texture/GetDepth.md index ff589bc4..3f8caf51 100644 --- a/docs/api/XCEngine/Resources/Texture/Texture/GetDepth.md +++ b/docs/api/XCEngine/Resources/Texture/Texture/GetDepth.md @@ -1,30 +1,26 @@ # Texture::GetDepth -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/Texture.h` + +## 签名 ```cpp Core::uint32 GetDepth() const; ``` -该方法声明于 `XCEngine/Resources/Texture/Texture.h`，当前页面用于固定 `Texture` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回纹理深度值。 -**返回：** `Core::uint32` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Texture object; - // 根据上下文补齐参数后调用 Texture::GetDepth(...)。 - (void)object; -} -``` +- 内联返回成员 `m_depth`。 ## 相关文档 -- [返回类总览](Texture.md) -- [返回模块目录](../Texture.md) +- [Texture](Texture.md) +- [GetTextureType](GetTextureType.md) diff --git a/docs/api/XCEngine/Resources/Texture/Texture/GetFormat.md b/docs/api/XCEngine/Resources/Texture/Texture/GetFormat.md index ff662647..49258fa1 100644 --- a/docs/api/XCEngine/Resources/Texture/Texture/GetFormat.md +++ b/docs/api/XCEngine/Resources/Texture/Texture/GetFormat.md @@ -1,30 +1,26 @@ # Texture::GetFormat -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/Texture.h` + +## 签名 ```cpp TextureFormat GetFormat() const; ``` -该方法声明于 `XCEngine/Resources/Texture/Texture.h`，当前页面用于固定 `Texture` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回纹理像素格式。 -**返回：** `TextureFormat` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Texture object; - // 根据上下文补齐参数后调用 Texture::GetFormat(...)。 - (void)object; -} -``` +- 内联返回成员 `m_format`。 ## 相关文档 -- [返回类总览](Texture.md) -- [返回模块目录](../Texture.md) +- [Texture](Texture.md) +- [GetUsage](GetUsage.md) diff --git a/docs/api/XCEngine/Resources/Texture/Texture/GetGUID.md b/docs/api/XCEngine/Resources/Texture/Texture/GetGUID.md index 25c3f259..8c42cc50 100644 --- a/docs/api/XCEngine/Resources/Texture/Texture/GetGUID.md +++ b/docs/api/XCEngine/Resources/Texture/Texture/GetGUID.md @@ -1,30 +1,25 @@ # Texture::GetGUID -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/Texture.h` + +## 签名 ```cpp ResourceGUID GetGUID() const override; ``` -该方法声明于 `XCEngine/Resources/Texture/Texture.h`，当前页面用于固定 `Texture` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回纹理资源的 GUID。 -**返回：** `ResourceGUID` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Texture object; - // 根据上下文补齐参数后调用 Texture::GetGUID(...)。 - (void)object; -} -``` +- 内联返回继承自 `IResource` 的成员 `m_guid`。 ## 相关文档 -- [返回类总览](Texture.md) -- [返回模块目录](../Texture.md) +- [Texture](Texture.md) diff --git a/docs/api/XCEngine/Resources/Texture/Texture/GetHeight.md b/docs/api/XCEngine/Resources/Texture/Texture/GetHeight.md index c97a17aa..dc653061 100644 --- a/docs/api/XCEngine/Resources/Texture/Texture/GetHeight.md +++ b/docs/api/XCEngine/Resources/Texture/Texture/GetHeight.md @@ -1,30 +1,26 @@ # Texture::GetHeight -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/Texture.h` + +## 签名 ```cpp Core::uint32 GetHeight() const; ``` -该方法声明于 `XCEngine/Resources/Texture/Texture.h`，当前页面用于固定 `Texture` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回纹理高度。 -**返回：** `Core::uint32` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Texture object; - // 根据上下文补齐参数后调用 Texture::GetHeight(...)。 - (void)object; -} -``` +- 内联返回成员 `m_height`。 ## 相关文档 -- [返回类总览](Texture.md) -- [返回模块目录](../Texture.md) +- [Texture](Texture.md) +- [GetWidth](GetWidth.md) diff --git a/docs/api/XCEngine/Resources/Texture/Texture/GetMemorySize.md b/docs/api/XCEngine/Resources/Texture/Texture/GetMemorySize.md index 8bd5fcfe..1e1f9b03 100644 --- a/docs/api/XCEngine/Resources/Texture/Texture/GetMemorySize.md +++ b/docs/api/XCEngine/Resources/Texture/Texture/GetMemorySize.md @@ -1,30 +1,27 @@ # Texture::GetMemorySize -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/Texture.h` + +## 签名 ```cpp size_t GetMemorySize() const override; ``` -该方法声明于 `XCEngine/Resources/Texture/Texture.h`，当前页面用于固定 `Texture` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回纹理当前记录的内存占用字节数。 -**返回：** `size_t` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Texture object; - // 根据上下文补齐参数后调用 Texture::GetMemorySize(...)。 - (void)object; -} -``` +- 内联返回继承自 `IResource` 的成员 `m_memorySize`。 +- 当前 `Create()` 会把它设成传入的 `dataSize`。 ## 相关文档 -- [返回类总览](Texture.md) -- [返回模块目录](../Texture.md) +- [Texture](Texture.md) +- [Create](Create.md) diff --git a/docs/api/XCEngine/Resources/Texture/Texture/GetMipLevels.md b/docs/api/XCEngine/Resources/Texture/Texture/GetMipLevels.md index 519f0a3f..db455a64 100644 --- a/docs/api/XCEngine/Resources/Texture/Texture/GetMipLevels.md +++ b/docs/api/XCEngine/Resources/Texture/Texture/GetMipLevels.md @@ -1,30 +1,26 @@ # Texture::GetMipLevels -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/Texture.h` + +## 签名 ```cpp Core::uint32 GetMipLevels() const; ``` -该方法声明于 `XCEngine/Resources/Texture/Texture.h`，当前页面用于固定 `Texture` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回纹理当前记录的 mip 级数。 -**返回：** `Core::uint32` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Texture object; - // 根据上下文补齐参数后调用 Texture::GetMipLevels(...)。 - (void)object; -} -``` +- 内联返回成员 `m_mipLevels`。 ## 相关文档 -- [返回类总览](Texture.md) -- [返回模块目录](../Texture.md) +- [Texture](Texture.md) +- [GenerateMipmaps](GenerateMipmaps.md) diff --git a/docs/api/XCEngine/Resources/Texture/Texture/GetName.md b/docs/api/XCEngine/Resources/Texture/Texture/GetName.md index 4efb1154..5ad0d940 100644 --- a/docs/api/XCEngine/Resources/Texture/Texture/GetName.md +++ b/docs/api/XCEngine/Resources/Texture/Texture/GetName.md @@ -1,30 +1,26 @@ # Texture::GetName -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/Texture.h` + +## 签名 ```cpp const Containers::String& GetName() const override; ``` -该方法声明于 `XCEngine/Resources/Texture/Texture.h`，当前页面用于固定 `Texture` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回纹理资源名。 -**返回：** `const Containers::String&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Texture object; - // 根据上下文补齐参数后调用 Texture::GetName(...)。 - (void)object; -} -``` +- 内联返回继承自 `IResource` 的成员 `m_name`。 ## 相关文档 -- [返回类总览](Texture.md) -- [返回模块目录](../Texture.md) +- [Texture](Texture.md) +- [GetPath](GetPath.md) diff --git a/docs/api/XCEngine/Resources/Texture/Texture/GetPath.md b/docs/api/XCEngine/Resources/Texture/Texture/GetPath.md index e495cdf9..b0485d12 100644 --- a/docs/api/XCEngine/Resources/Texture/Texture/GetPath.md +++ b/docs/api/XCEngine/Resources/Texture/Texture/GetPath.md @@ -1,30 +1,26 @@ # Texture::GetPath -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/Texture.h` + +## 签名 ```cpp const Containers::String& GetPath() const override; ``` -该方法声明于 `XCEngine/Resources/Texture/Texture.h`，当前页面用于固定 `Texture` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回纹理资源路径。 -**返回：** `const Containers::String&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Texture object; - // 根据上下文补齐参数后调用 Texture::GetPath(...)。 - (void)object; -} -``` +- 内联返回继承自 `IResource` 的成员 `m_path`。 ## 相关文档 -- [返回类总览](Texture.md) -- [返回模块目录](../Texture.md) +- [Texture](Texture.md) +- [GetName](GetName.md) diff --git a/docs/api/XCEngine/Resources/Texture/Texture/GetPixelData.md b/docs/api/XCEngine/Resources/Texture/Texture/GetPixelData.md index 7f793fe1..644a1875 100644 --- a/docs/api/XCEngine/Resources/Texture/Texture/GetPixelData.md +++ b/docs/api/XCEngine/Resources/Texture/Texture/GetPixelData.md @@ -1,30 +1,27 @@ # Texture::GetPixelData -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/Texture.h` + +## 签名 ```cpp const void* GetPixelData() const; ``` -该方法声明于 `XCEngine/Resources/Texture/Texture.h`，当前页面用于固定 `Texture` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回内部像素缓冲的首地址。 -**返回：** `const void*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Texture object; - // 根据上下文补齐参数后调用 Texture::GetPixelData(...)。 - (void)object; -} -``` +- 内联返回 `m_pixelData.Data()`。 +- 当像素缓冲为空时，返回值由 `Containers::Array` 的当前实现决定。 ## 相关文档 -- [返回类总览](Texture.md) -- [返回模块目录](../Texture.md) +- [Texture](Texture.md) +- [GetPixelDataSize](GetPixelDataSize.md) diff --git a/docs/api/XCEngine/Resources/Texture/Texture/GetPixelDataSize.md b/docs/api/XCEngine/Resources/Texture/Texture/GetPixelDataSize.md index a762630a..171b8327 100644 --- a/docs/api/XCEngine/Resources/Texture/Texture/GetPixelDataSize.md +++ b/docs/api/XCEngine/Resources/Texture/Texture/GetPixelDataSize.md @@ -1,30 +1,26 @@ # Texture::GetPixelDataSize -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/Texture.h` + +## 签名 ```cpp size_t GetPixelDataSize() const; ``` -该方法声明于 `XCEngine/Resources/Texture/Texture.h`，当前页面用于固定 `Texture` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回内部像素缓冲的字节数。 -**返回：** `size_t` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Texture object; - // 根据上下文补齐参数后调用 Texture::GetPixelDataSize(...)。 - (void)object; -} -``` +- 内联返回 `m_pixelData.Size()`。 ## 相关文档 -- [返回类总览](Texture.md) -- [返回模块目录](../Texture.md) +- [Texture](Texture.md) +- [GetPixelData](GetPixelData.md) diff --git a/docs/api/XCEngine/Resources/Texture/Texture/GetTextureType.md b/docs/api/XCEngine/Resources/Texture/Texture/GetTextureType.md index a109ef85..64cad500 100644 --- a/docs/api/XCEngine/Resources/Texture/Texture/GetTextureType.md +++ b/docs/api/XCEngine/Resources/Texture/Texture/GetTextureType.md @@ -1,30 +1,27 @@ # Texture::GetTextureType -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/Texture.h` + +## 签名 ```cpp TextureType GetTextureType() const; ``` -该方法声明于 `XCEngine/Resources/Texture/Texture.h`，当前页面用于固定 `Texture` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回纹理维度 / 布局类型。 -**返回：** `TextureType` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Texture object; - // 根据上下文补齐参数后调用 Texture::GetTextureType(...)。 - (void)object; -} -``` +- 内联返回成员 `m_textureType`。 ## 相关文档 -- [返回类总览](Texture.md) -- [返回模块目录](../Texture.md) +- [Texture](Texture.md) +- [GetArraySize](GetArraySize.md) +- [GetDepth](GetDepth.md) diff --git a/docs/api/XCEngine/Resources/Texture/Texture/GetType.md b/docs/api/XCEngine/Resources/Texture/Texture/GetType.md index abe219db..d80ce6e5 100644 --- a/docs/api/XCEngine/Resources/Texture/Texture/GetType.md +++ b/docs/api/XCEngine/Resources/Texture/Texture/GetType.md @@ -1,30 +1,25 @@ # Texture::GetType -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/Texture.h` + +## 签名 ```cpp ResourceType GetType() const override; ``` -该方法声明于 `XCEngine/Resources/Texture/Texture.h`，当前页面用于固定 `Texture` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回这份资源的类型枚举。 -**返回：** `ResourceType` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Texture object; - // 根据上下文补齐参数后调用 Texture::GetType(...)。 - (void)object; -} -``` +- 内联返回固定值 `ResourceType::Texture`。 ## 相关文档 -- [返回类总览](Texture.md) -- [返回模块目录](../Texture.md) +- [Texture](Texture.md) diff --git a/docs/api/XCEngine/Resources/Texture/Texture/GetUsage.md b/docs/api/XCEngine/Resources/Texture/Texture/GetUsage.md index ae809c4b..8cec5f23 100644 --- a/docs/api/XCEngine/Resources/Texture/Texture/GetUsage.md +++ b/docs/api/XCEngine/Resources/Texture/Texture/GetUsage.md @@ -1,30 +1,26 @@ # Texture::GetUsage -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/Texture.h` + +## 签名 ```cpp TextureUsage GetUsage() const; ``` -该方法声明于 `XCEngine/Resources/Texture/Texture.h`，当前页面用于固定 `Texture` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回纹理用途标记。 -**返回：** `TextureUsage` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Texture object; - // 根据上下文补齐参数后调用 Texture::GetUsage(...)。 - (void)object; -} -``` +- 内联返回成员 `m_usage`。 ## 相关文档 -- [返回类总览](Texture.md) -- [返回模块目录](../Texture.md) +- [Texture](Texture.md) +- [GetFormat](GetFormat.md) diff --git a/docs/api/XCEngine/Resources/Texture/Texture/GetWidth.md b/docs/api/XCEngine/Resources/Texture/Texture/GetWidth.md index 042c922a..18d95780 100644 --- a/docs/api/XCEngine/Resources/Texture/Texture/GetWidth.md +++ b/docs/api/XCEngine/Resources/Texture/Texture/GetWidth.md @@ -1,30 +1,26 @@ # Texture::GetWidth -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/Texture.h` + +## 签名 ```cpp Core::uint32 GetWidth() const; ``` -该方法声明于 `XCEngine/Resources/Texture/Texture.h`，当前页面用于固定 `Texture` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回纹理宽度。 -**返回：** `Core::uint32` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Texture object; - // 根据上下文补齐参数后调用 Texture::GetWidth(...)。 - (void)object; -} -``` +- 内联返回成员 `m_width`。 ## 相关文档 -- [返回类总览](Texture.md) -- [返回模块目录](../Texture.md) +- [Texture](Texture.md) +- [GetHeight](GetHeight.md) diff --git a/docs/api/XCEngine/Resources/Texture/Texture/IsValid.md b/docs/api/XCEngine/Resources/Texture/Texture/IsValid.md index 548e7f98..3718a79e 100644 --- a/docs/api/XCEngine/Resources/Texture/Texture/IsValid.md +++ b/docs/api/XCEngine/Resources/Texture/Texture/IsValid.md @@ -1,30 +1,26 @@ # Texture::IsValid -查询当前状态。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/Texture.h` + +## 签名 ```cpp bool IsValid() const override; ``` -该方法声明于 `XCEngine/Resources/Texture/Texture.h`，当前页面用于固定 `Texture` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +查询纹理资源当前是否有效。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Texture object; - // 根据上下文补齐参数后调用 Texture::IsValid(...)。 - (void)object; -} -``` +- 内联返回继承自 `IResource` 的成员 `m_isValid`。 ## 相关文档 -- [返回类总览](Texture.md) -- [返回模块目录](../Texture.md) +- [Texture](Texture.md) +- [Release](Release.md) diff --git a/docs/api/XCEngine/Resources/Texture/Texture/Release.md b/docs/api/XCEngine/Resources/Texture/Texture/Release.md index e4ca9754..3eceaf49 100644 --- a/docs/api/XCEngine/Resources/Texture/Texture/Release.md +++ b/docs/api/XCEngine/Resources/Texture/Texture/Release.md @@ -1,30 +1,27 @@ # Texture::Release -释放引用或底层资源。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/Texture.h` + +## 签名 ```cpp void Release() override; ``` -该方法声明于 `XCEngine/Resources/Texture/Texture.h`，当前页面用于固定 `Texture` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +释放当前纹理对象持有的 CPU 侧像素数据，并把资源标记为无效。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::Texture object; - // 根据上下文补齐参数后调用 Texture::Release(...)。 - (void)object; -} -``` +- 调用 `m_pixelData.Clear()` 清空内部像素缓冲。 +- 随后调用 `SetInvalid()`。 ## 相关文档 -- [返回类总览](Texture.md) -- [返回模块目录](../Texture.md) +- [Texture](Texture.md) +- [IsValid](IsValid.md) diff --git a/docs/api/XCEngine/Resources/Texture/Texture/Texture.md b/docs/api/XCEngine/Resources/Texture/Texture/Texture.md index 24981e2b..7f4236a6 100644 --- a/docs/api/XCEngine/Resources/Texture/Texture/Texture.md +++ b/docs/api/XCEngine/Resources/Texture/Texture/Texture.md @@ -6,48 +6,59 @@ **头文件**: `XCEngine/Resources/Texture/Texture.h` -**描述**: 定义 `XCEngine/Resources/Texture` 子目录中的 `Texture` public API。 +**描述**: 纹理资源类型，保存尺寸、格式、像素数据和基本使用语义，并作为 `IResource` 参与资源管理系统。 ## 概述 -`Texture.h` 是 `XCEngine/Resources/Texture` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。 +`Texture` 表达的是一份已经进入资源系统的纹理资产。当前头文件把它拆成两层信息： + +- `TextureType` / `TextureFormat` / `TextureUsage` + - 描述纹理维度、像素格式和用途 +- `Texture` + - 保存尺寸、mipmap、数组大小、CPU 端像素数据和资源元数据 + +按 `engine/src/Resources/Texture/Texture.cpp` 的当前实现，`Texture` 主要是 CPU 侧数据容器： + +- [Create](Create.md) 负责写入描述字段并拷贝像素数据 +- [Release](Release.md) 清空像素缓冲并标记资源失效 +- [GenerateMipmaps](GenerateMipmaps.md) 当前仍未实现，固定返回 `false` ## 声明概览 | 声明 | 类型 | 说明 | |------|------|------| -| `TextureType` | `enum class` | 头文件中的公开声明。 | -| `TextureFormat` | `enum class` | 头文件中的公开声明。 | -| `TextureUsage` | `enum class` | 头文件中的公开声明。 | -| `Texture` | `class` | 继承自 `IResource` 的公开声明。 | +| `TextureType` | `enum class` | 纹理维度与布局类型。 | +| `TextureFormat` | `enum class` | 纹理像素格式。 | +| `TextureUsage` | `enum class` | 纹理用途标记。 | +| `Texture` | `class` | 纹理资源对象。 | ## 公共方法 | 方法 | 描述 | |------|------| -| [Texture()](Constructor.md) | 构造对象。 | -| [~Texture()](Destructor.md) | 销毁对象并释放相关资源。 | -| [GetType](GetType.md) | 获取相关状态或对象。 | -| [GetName](GetName.md) | 获取相关状态或对象。 | -| [GetPath](GetPath.md) | 获取相关状态或对象。 | -| [GetGUID](GetGUID.md) | 获取相关状态或对象。 | -| [IsValid](IsValid.md) | 查询当前状态。 | -| [GetMemorySize](GetMemorySize.md) | 获取相关状态或对象。 | -| [Release](Release.md) | 释放引用或底层资源。 | -| [GetWidth](GetWidth.md) | 获取相关状态或对象。 | -| [GetHeight](GetHeight.md) | 获取相关状态或对象。 | -| [GetDepth](GetDepth.md) | 获取相关状态或对象。 | -| [GetMipLevels](GetMipLevels.md) | 获取相关状态或对象。 | -| [GetArraySize](GetArraySize.md) | 获取相关状态或对象。 | -| [GetTextureType](GetTextureType.md) | 获取相关状态或对象。 | -| [GetFormat](GetFormat.md) | 获取相关状态或对象。 | -| [GetUsage](GetUsage.md) | 获取相关状态或对象。 | -| [GetPixelData](GetPixelData.md) | 获取相关状态或对象。 | -| [GetPixelDataSize](GetPixelDataSize.md) | 获取相关状态或对象。 | -| [Create](Create.md) | 创建新对象或资源。 | -| [GenerateMipmaps](GenerateMipmaps.md) | 公开方法，详见头文件声明。 | +| [Texture()](Constructor.md) | 构造一份空纹理对象。 | +| [~Texture()](Destructor.md) | 按默认析构销毁纹理对象。 | +| [GetType](GetType.md) | 返回固定的 `ResourceType::Texture`。 | +| [GetName](GetName.md) | 返回资源名。 | +| [GetPath](GetPath.md) | 返回资源路径。 | +| [GetGUID](GetGUID.md) | 返回资源 GUID。 | +| [IsValid](IsValid.md) | 查询资源当前是否有效。 | +| [GetMemorySize](GetMemorySize.md) | 返回当前记录的内存占用字节数。 | +| [Release](Release.md) | 清空像素数据并把资源标记为无效。 | +| [GetWidth](GetWidth.md) | 返回纹理宽度。 | +| [GetHeight](GetHeight.md) | 返回纹理高度。 | +| [GetDepth](GetDepth.md) | 返回纹理深度。 | +| [GetMipLevels](GetMipLevels.md) | 返回 mip 数量。 | +| [GetArraySize](GetArraySize.md) | 返回数组层数。 | +| [GetTextureType](GetTextureType.md) | 返回纹理类型。 | +| [GetFormat](GetFormat.md) | 返回纹理格式。 | +| [GetUsage](GetUsage.md) | 返回用途标记。 | +| [GetPixelData](GetPixelData.md) | 返回内部像素缓冲首地址。 | +| [GetPixelDataSize](GetPixelDataSize.md) | 返回内部像素缓冲字节数。 | +| [Create](Create.md) | 写入纹理描述并可选拷贝像素数据。 | +| [GenerateMipmaps](GenerateMipmaps.md) | 当前未实现，固定返回 `false`。 | ## 相关文档 -- [当前目录](../Texture.md) - 返回 `Texture` 平行目录 -- [API 总索引](../../../../main.md) - 返回顶层索引 +- [Texture 模块](../Texture.md) +- [TextureLoader](../TextureLoader/TextureLoader.md) diff --git a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/Clone.md b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/Clone.md index 2a78d2e2..dc7d5a96 100644 --- a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/Clone.md +++ b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/Clone.md @@ -1,30 +1,25 @@ # TextureImportSettings::Clone -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/TextureImportSettings.h` + +## 签名 ```cpp Core::UniqueRef Clone() const override; ``` -该方法声明于 `XCEngine/Resources/Texture/TextureImportSettings.h`，当前页面用于固定 `TextureImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `Clone` 对应的公开操作。 -**返回：** `Core::UniqueRef` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::TextureImportSettings object; - // 根据上下文补齐参数后调用 TextureImportSettings::Clone(...)。 - (void)object; -} -``` +- 具体定义位于 `engine/src/Resources/Texture/TextureImportSettings.cpp`。 ## 相关文档 -- [返回类总览](TextureImportSettings.md) -- [返回模块目录](../Texture.md) +- [TextureImportSettings](TextureImportSettings.md) diff --git a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/Constructor.md b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/Constructor.md index c5000123..718485ca 100644 --- a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/Constructor.md +++ b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/Constructor.md @@ -1,28 +1,25 @@ # TextureImportSettings::TextureImportSettings() -构造对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/TextureImportSettings.h` + +## 签名 ```cpp TextureImportSettings(); ``` -该方法声明于 `XCEngine/Resources/Texture/TextureImportSettings.h`，当前页面用于固定 `TextureImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +构造 `TextureImportSettings` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::TextureImportSettings object; -} -``` +- 当前为默认构造实现。 ## 相关文档 -- [返回类总览](TextureImportSettings.md) -- [返回模块目录](../Texture.md) +- [TextureImportSettings](TextureImportSettings.md) diff --git a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/Destructor.md b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/Destructor.md index 0baea21c..1811efdc 100644 --- a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/Destructor.md +++ b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/Destructor.md @@ -1,29 +1,25 @@ # TextureImportSettings::~TextureImportSettings() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/TextureImportSettings.h` + +## 签名 ```cpp virtual ~TextureImportSettings() override; ``` -该方法声明于 `XCEngine/Resources/Texture/TextureImportSettings.h`，当前页面用于固定 `TextureImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +销毁 `TextureImportSettings` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::TextureImportSettings object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 当前为默认析构实现。 ## 相关文档 -- [返回类总览](TextureImportSettings.md) -- [返回模块目录](../Texture.md) +- [TextureImportSettings](TextureImportSettings.md) diff --git a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/GetBorderColor.md b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/GetBorderColor.md index 52743fb2..73508e98 100644 --- a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/GetBorderColor.md +++ b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/GetBorderColor.md @@ -1,30 +1,26 @@ # TextureImportSettings::GetBorderColor -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/TextureImportSettings.h` + +## 签名 ```cpp const Math::Vector3& GetBorderColor() const; ``` -该方法声明于 `XCEngine/Resources/Texture/TextureImportSettings.h`，当前页面用于固定 `TextureImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_borderColor` 当前值。 -**返回：** `const Math::Vector3&` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::TextureImportSettings object; - // 根据上下文补齐参数后调用 TextureImportSettings::GetBorderColor(...)。 - (void)object; -} -``` +- 返回 `m_borderColor` 当前值。 ## 相关文档 -- [返回类总览](TextureImportSettings.md) -- [返回模块目录](../Texture.md) +- [TextureImportSettings](TextureImportSettings.md) +- [SetBorderColor](SetBorderColor.md) diff --git a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/GetCompressionQuality.md b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/GetCompressionQuality.md index 78ab089e..cbf7dd8a 100644 --- a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/GetCompressionQuality.md +++ b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/GetCompressionQuality.md @@ -1,30 +1,26 @@ # TextureImportSettings::GetCompressionQuality -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/TextureImportSettings.h` + +## 签名 ```cpp CompressionQuality GetCompressionQuality() const; ``` -该方法声明于 `XCEngine/Resources/Texture/TextureImportSettings.h`，当前页面用于固定 `TextureImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_compressionQuality` 当前值。 -**返回：** `CompressionQuality` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::TextureImportSettings object; - // 根据上下文补齐参数后调用 TextureImportSettings::GetCompressionQuality(...)。 - (void)object; -} -``` +- 返回 `m_compressionQuality` 当前值。 ## 相关文档 -- [返回类总览](TextureImportSettings.md) -- [返回模块目录](../Texture.md) +- [TextureImportSettings](TextureImportSettings.md) +- [SetCompressionQuality](SetCompressionQuality.md) diff --git a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/GetFlipHorizontal.md b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/GetFlipHorizontal.md index aedfef83..54d9e04d 100644 --- a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/GetFlipHorizontal.md +++ b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/GetFlipHorizontal.md @@ -1,30 +1,26 @@ # TextureImportSettings::GetFlipHorizontal -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/TextureImportSettings.h` + +## 签名 ```cpp bool GetFlipHorizontal() const; ``` -该方法声明于 `XCEngine/Resources/Texture/TextureImportSettings.h`，当前页面用于固定 `TextureImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_flipHorizontal` 当前值。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::TextureImportSettings object; - // 根据上下文补齐参数后调用 TextureImportSettings::GetFlipHorizontal(...)。 - (void)object; -} -``` +- 返回 `m_flipHorizontal` 当前值。 ## 相关文档 -- [返回类总览](TextureImportSettings.md) -- [返回模块目录](../Texture.md) +- [TextureImportSettings](TextureImportSettings.md) +- [SetFlipHorizontal](SetFlipHorizontal.md) diff --git a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/GetFlipVertical.md b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/GetFlipVertical.md index 22b4ee77..6f33eab4 100644 --- a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/GetFlipVertical.md +++ b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/GetFlipVertical.md @@ -1,30 +1,26 @@ # TextureImportSettings::GetFlipVertical -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/TextureImportSettings.h` + +## 签名 ```cpp bool GetFlipVertical() const; ``` -该方法声明于 `XCEngine/Resources/Texture/TextureImportSettings.h`，当前页面用于固定 `TextureImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_flipVertical` 当前值。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::TextureImportSettings object; - // 根据上下文补齐参数后调用 TextureImportSettings::GetFlipVertical(...)。 - (void)object; -} -``` +- 返回 `m_flipVertical` 当前值。 ## 相关文档 -- [返回类总览](TextureImportSettings.md) -- [返回模块目录](../Texture.md) +- [TextureImportSettings](TextureImportSettings.md) +- [SetFlipVertical](SetFlipVertical.md) diff --git a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/GetGenerateMipmaps.md b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/GetGenerateMipmaps.md index fa55e911..d7f9e595 100644 --- a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/GetGenerateMipmaps.md +++ b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/GetGenerateMipmaps.md @@ -1,30 +1,26 @@ # TextureImportSettings::GetGenerateMipmaps -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/TextureImportSettings.h` + +## 签名 ```cpp bool GetGenerateMipmaps() const; ``` -该方法声明于 `XCEngine/Resources/Texture/TextureImportSettings.h`，当前页面用于固定 `TextureImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_generateMipmaps` 当前值。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::TextureImportSettings object; - // 根据上下文补齐参数后调用 TextureImportSettings::GetGenerateMipmaps(...)。 - (void)object; -} -``` +- 返回 `m_generateMipmaps` 当前值。 ## 相关文档 -- [返回类总览](TextureImportSettings.md) -- [返回模块目录](../Texture.md) +- [TextureImportSettings](TextureImportSettings.md) +- [SetGenerateMipmaps](SetGenerateMipmaps.md) diff --git a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/GetGenerateNormalMap.md b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/GetGenerateNormalMap.md index c85a4d87..015846d8 100644 --- a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/GetGenerateNormalMap.md +++ b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/GetGenerateNormalMap.md @@ -1,30 +1,26 @@ # TextureImportSettings::GetGenerateNormalMap -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/TextureImportSettings.h` + +## 签名 ```cpp bool GetGenerateNormalMap() const; ``` -该方法声明于 `XCEngine/Resources/Texture/TextureImportSettings.h`，当前页面用于固定 `TextureImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_generateNormalMap` 当前值。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::TextureImportSettings object; - // 根据上下文补齐参数后调用 TextureImportSettings::GetGenerateNormalMap(...)。 - (void)object; -} -``` +- 返回 `m_generateNormalMap` 当前值。 ## 相关文档 -- [返回类总览](TextureImportSettings.md) -- [返回模块目录](../Texture.md) +- [TextureImportSettings](TextureImportSettings.md) +- [SetGenerateNormalMap](SetGenerateNormalMap.md) diff --git a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/GetMaxAnisotropy.md b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/GetMaxAnisotropy.md index 88a72f06..58748990 100644 --- a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/GetMaxAnisotropy.md +++ b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/GetMaxAnisotropy.md @@ -1,30 +1,26 @@ # TextureImportSettings::GetMaxAnisotropy -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/TextureImportSettings.h` + +## 签名 ```cpp Core::uint32 GetMaxAnisotropy() const; ``` -该方法声明于 `XCEngine/Resources/Texture/TextureImportSettings.h`，当前页面用于固定 `TextureImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_maxAnisotropy` 当前值。 -**返回：** `Core::uint32` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::TextureImportSettings object; - // 根据上下文补齐参数后调用 TextureImportSettings::GetMaxAnisotropy(...)。 - (void)object; -} -``` +- 返回 `m_maxAnisotropy` 当前值。 ## 相关文档 -- [返回类总览](TextureImportSettings.md) -- [返回模块目录](../Texture.md) +- [TextureImportSettings](TextureImportSettings.md) +- [SetMaxAnisotropy](SetMaxAnisotropy.md) diff --git a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/GetMaxSize.md b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/GetMaxSize.md index 92c97a26..58b24a62 100644 --- a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/GetMaxSize.md +++ b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/GetMaxSize.md @@ -1,30 +1,26 @@ # TextureImportSettings::GetMaxSize -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/TextureImportSettings.h` + +## 签名 ```cpp Core::uint32 GetMaxSize() const; ``` -该方法声明于 `XCEngine/Resources/Texture/TextureImportSettings.h`，当前页面用于固定 `TextureImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_maxSize` 当前值。 -**返回：** `Core::uint32` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::TextureImportSettings object; - // 根据上下文补齐参数后调用 TextureImportSettings::GetMaxSize(...)。 - (void)object; -} -``` +- 返回 `m_maxSize` 当前值。 ## 相关文档 -- [返回类总览](TextureImportSettings.md) -- [返回模块目录](../Texture.md) +- [TextureImportSettings](TextureImportSettings.md) +- [SetMaxSize](SetMaxSize.md) diff --git a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/GetMipmapFilter.md b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/GetMipmapFilter.md index def5199d..e8beb4bf 100644 --- a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/GetMipmapFilter.md +++ b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/GetMipmapFilter.md @@ -1,30 +1,26 @@ # TextureImportSettings::GetMipmapFilter -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/TextureImportSettings.h` + +## 签名 ```cpp MipmapFilter GetMipmapFilter() const; ``` -该方法声明于 `XCEngine/Resources/Texture/TextureImportSettings.h`，当前页面用于固定 `TextureImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_mipmapFilter` 当前值。 -**返回：** `MipmapFilter` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::TextureImportSettings object; - // 根据上下文补齐参数后调用 TextureImportSettings::GetMipmapFilter(...)。 - (void)object; -} -``` +- 返回 `m_mipmapFilter` 当前值。 ## 相关文档 -- [返回类总览](TextureImportSettings.md) -- [返回模块目录](../Texture.md) +- [TextureImportSettings](TextureImportSettings.md) +- [SetMipmapFilter](SetMipmapFilter.md) diff --git a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/GetNormalMapStrength.md b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/GetNormalMapStrength.md index 1c36472e..c6343dbc 100644 --- a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/GetNormalMapStrength.md +++ b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/GetNormalMapStrength.md @@ -1,30 +1,26 @@ # TextureImportSettings::GetNormalMapStrength -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/TextureImportSettings.h` + +## 签名 ```cpp float GetNormalMapStrength() const; ``` -该方法声明于 `XCEngine/Resources/Texture/TextureImportSettings.h`，当前页面用于固定 `TextureImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_normalMapStrength` 当前值。 -**返回：** `float` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::TextureImportSettings object; - // 根据上下文补齐参数后调用 TextureImportSettings::GetNormalMapStrength(...)。 - (void)object; -} -``` +- 返回 `m_normalMapStrength` 当前值。 ## 相关文档 -- [返回类总览](TextureImportSettings.md) -- [返回模块目录](../Texture.md) +- [TextureImportSettings](TextureImportSettings.md) +- [SetNormalMapStrength](SetNormalMapStrength.md) diff --git a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/GetSRGB.md b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/GetSRGB.md index 42bc8fc7..bfae62e7 100644 --- a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/GetSRGB.md +++ b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/GetSRGB.md @@ -1,30 +1,26 @@ # TextureImportSettings::GetSRGB -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/TextureImportSettings.h` + +## 签名 ```cpp bool GetSRGB() const; ``` -该方法声明于 `XCEngine/Resources/Texture/TextureImportSettings.h`，当前页面用于固定 `TextureImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_sRGB` 当前值。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::TextureImportSettings object; - // 根据上下文补齐参数后调用 TextureImportSettings::GetSRGB(...)。 - (void)object; -} -``` +- 返回 `m_sRGB` 当前值。 ## 相关文档 -- [返回类总览](TextureImportSettings.md) -- [返回模块目录](../Texture.md) +- [TextureImportSettings](TextureImportSettings.md) +- [SetSRGB](SetSRGB.md) diff --git a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/GetTargetFormat.md b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/GetTargetFormat.md index c19310f8..b4aa925e 100644 --- a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/GetTargetFormat.md +++ b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/GetTargetFormat.md @@ -1,30 +1,26 @@ # TextureImportSettings::GetTargetFormat -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/TextureImportSettings.h` + +## 签名 ```cpp TextureFormat GetTargetFormat() const; ``` -该方法声明于 `XCEngine/Resources/Texture/TextureImportSettings.h`，当前页面用于固定 `TextureImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_targetFormat` 当前值。 -**返回：** `TextureFormat` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::TextureImportSettings object; - // 根据上下文补齐参数后调用 TextureImportSettings::GetTargetFormat(...)。 - (void)object; -} -``` +- 返回 `m_targetFormat` 当前值。 ## 相关文档 -- [返回类总览](TextureImportSettings.md) -- [返回模块目录](../Texture.md) +- [TextureImportSettings](TextureImportSettings.md) +- [SetTargetFormat](SetTargetFormat.md) diff --git a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/GetTextureType.md b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/GetTextureType.md index a63dd7b9..02f0b49a 100644 --- a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/GetTextureType.md +++ b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/GetTextureType.md @@ -1,30 +1,26 @@ # TextureImportSettings::GetTextureType -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/TextureImportSettings.h` + +## 签名 ```cpp TextureType GetTextureType() const; ``` -该方法声明于 `XCEngine/Resources/Texture/TextureImportSettings.h`，当前页面用于固定 `TextureImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_textureType` 当前值。 -**返回：** `TextureType` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::TextureImportSettings object; - // 根据上下文补齐参数后调用 TextureImportSettings::GetTextureType(...)。 - (void)object; -} -``` +- 返回 `m_textureType` 当前值。 ## 相关文档 -- [返回类总览](TextureImportSettings.md) -- [返回模块目录](../Texture.md) +- [TextureImportSettings](TextureImportSettings.md) +- [SetTextureType](SetTextureType.md) diff --git a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/GetUseHardwareCompression.md b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/GetUseHardwareCompression.md index 74eba5ec..ec679eac 100644 --- a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/GetUseHardwareCompression.md +++ b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/GetUseHardwareCompression.md @@ -1,30 +1,26 @@ # TextureImportSettings::GetUseHardwareCompression -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/TextureImportSettings.h` + +## 签名 ```cpp bool GetUseHardwareCompression() const; ``` -该方法声明于 `XCEngine/Resources/Texture/TextureImportSettings.h`，当前页面用于固定 `TextureImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `m_useHardwareCompression` 当前值。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::TextureImportSettings object; - // 根据上下文补齐参数后调用 TextureImportSettings::GetUseHardwareCompression(...)。 - (void)object; -} -``` +- 返回 `m_useHardwareCompression` 当前值。 ## 相关文档 -- [返回类总览](TextureImportSettings.md) -- [返回模块目录](../Texture.md) +- [TextureImportSettings](TextureImportSettings.md) +- [SetUseHardwareCompression](SetUseHardwareCompression.md) diff --git a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/LoadFromJSON.md b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/LoadFromJSON.md index e97d519e..6a7ff6ca 100644 --- a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/LoadFromJSON.md +++ b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/LoadFromJSON.md @@ -1,31 +1,25 @@ # TextureImportSettings::LoadFromJSON -加载资源或数据。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/TextureImportSettings.h` + +## 签名 ```cpp bool LoadFromJSON(const Containers::String& json) override; ``` -该方法声明于 `XCEngine/Resources/Texture/TextureImportSettings.h`，当前页面用于固定 `TextureImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `json` - 参数语义详见头文件声明。 +固定返回 `false`。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::TextureImportSettings object; - // 根据上下文补齐参数后调用 TextureImportSettings::LoadFromJSON(...)。 - (void)object; -} -``` +- 固定返回 `false`。 ## 相关文档 -- [返回类总览](TextureImportSettings.md) -- [返回模块目录](../Texture.md) +- [TextureImportSettings](TextureImportSettings.md) diff --git a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SaveToJSON.md b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SaveToJSON.md index f2c641f6..b45aa499 100644 --- a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SaveToJSON.md +++ b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SaveToJSON.md @@ -1,30 +1,25 @@ # TextureImportSettings::SaveToJSON -公开方法，详见头文件声明。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/TextureImportSettings.h` + +## 签名 ```cpp Containers::String SaveToJSON() const override; ``` -该方法声明于 `XCEngine/Resources/Texture/TextureImportSettings.h`，当前页面用于固定 `TextureImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +执行 `SaveToJSON` 对应的公开操作。 -**返回：** `Containers::String` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::TextureImportSettings object; - // 根据上下文补齐参数后调用 TextureImportSettings::SaveToJSON(...)。 - (void)object; -} -``` +- 具体定义位于 `engine/src/Resources/Texture/TextureImportSettings.cpp`。 ## 相关文档 -- [返回类总览](TextureImportSettings.md) -- [返回模块目录](../Texture.md) +- [TextureImportSettings](TextureImportSettings.md) diff --git a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SetBorderColor.md b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SetBorderColor.md index 2112c32b..28937553 100644 --- a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SetBorderColor.md +++ b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SetBorderColor.md @@ -1,31 +1,26 @@ # TextureImportSettings::SetBorderColor -设置相关状态或配置。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/TextureImportSettings.h` + +## 签名 ```cpp void SetBorderColor(const Math::Vector3& color); ``` -该方法声明于 `XCEngine/Resources/Texture/TextureImportSettings.h`，当前页面用于固定 `TextureImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `color` - 参数语义详见头文件声明。 +更新 `m_borderColor`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::TextureImportSettings object; - // 根据上下文补齐参数后调用 TextureImportSettings::SetBorderColor(...)。 - (void)object; -} -``` +- 会更新 `m_borderColor`。 ## 相关文档 -- [返回类总览](TextureImportSettings.md) -- [返回模块目录](../Texture.md) +- [TextureImportSettings](TextureImportSettings.md) +- [GetBorderColor](GetBorderColor.md) diff --git a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SetCompressionQuality.md b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SetCompressionQuality.md index d165b6b5..bf21cf49 100644 --- a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SetCompressionQuality.md +++ b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SetCompressionQuality.md @@ -1,31 +1,26 @@ # TextureImportSettings::SetCompressionQuality -设置相关状态或配置。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/TextureImportSettings.h` + +## 签名 ```cpp void SetCompressionQuality(CompressionQuality quality); ``` -该方法声明于 `XCEngine/Resources/Texture/TextureImportSettings.h`，当前页面用于固定 `TextureImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `quality` - 参数语义详见头文件声明。 +更新 `m_compressionQuality`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::TextureImportSettings object; - // 根据上下文补齐参数后调用 TextureImportSettings::SetCompressionQuality(...)。 - (void)object; -} -``` +- 会更新 `m_compressionQuality`。 ## 相关文档 -- [返回类总览](TextureImportSettings.md) -- [返回模块目录](../Texture.md) +- [TextureImportSettings](TextureImportSettings.md) +- [GetCompressionQuality](GetCompressionQuality.md) diff --git a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SetFlipHorizontal.md b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SetFlipHorizontal.md index 42f7f87a..302ef9f7 100644 --- a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SetFlipHorizontal.md +++ b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SetFlipHorizontal.md @@ -1,31 +1,26 @@ # TextureImportSettings::SetFlipHorizontal -设置相关状态或配置。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/TextureImportSettings.h` + +## 签名 ```cpp void SetFlipHorizontal(bool flip); ``` -该方法声明于 `XCEngine/Resources/Texture/TextureImportSettings.h`，当前页面用于固定 `TextureImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `flip` - 参数语义详见头文件声明。 +更新 `m_flipHorizontal`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::TextureImportSettings object; - // 根据上下文补齐参数后调用 TextureImportSettings::SetFlipHorizontal(...)。 - (void)object; -} -``` +- 会更新 `m_flipHorizontal`。 ## 相关文档 -- [返回类总览](TextureImportSettings.md) -- [返回模块目录](../Texture.md) +- [TextureImportSettings](TextureImportSettings.md) +- [GetFlipHorizontal](GetFlipHorizontal.md) diff --git a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SetFlipVertical.md b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SetFlipVertical.md index e433a56e..4bc4e98d 100644 --- a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SetFlipVertical.md +++ b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SetFlipVertical.md @@ -1,31 +1,26 @@ # TextureImportSettings::SetFlipVertical -设置相关状态或配置。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/TextureImportSettings.h` + +## 签名 ```cpp void SetFlipVertical(bool flip); ``` -该方法声明于 `XCEngine/Resources/Texture/TextureImportSettings.h`，当前页面用于固定 `TextureImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `flip` - 参数语义详见头文件声明。 +更新 `m_flipVertical`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::TextureImportSettings object; - // 根据上下文补齐参数后调用 TextureImportSettings::SetFlipVertical(...)。 - (void)object; -} -``` +- 会更新 `m_flipVertical`。 ## 相关文档 -- [返回类总览](TextureImportSettings.md) -- [返回模块目录](../Texture.md) +- [TextureImportSettings](TextureImportSettings.md) +- [GetFlipVertical](GetFlipVertical.md) diff --git a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SetGenerateMipmaps.md b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SetGenerateMipmaps.md index a0a4edb5..d5d9e831 100644 --- a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SetGenerateMipmaps.md +++ b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SetGenerateMipmaps.md @@ -1,31 +1,26 @@ # TextureImportSettings::SetGenerateMipmaps -设置相关状态或配置。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/TextureImportSettings.h` + +## 签名 ```cpp void SetGenerateMipmaps(bool generate); ``` -该方法声明于 `XCEngine/Resources/Texture/TextureImportSettings.h`，当前页面用于固定 `TextureImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `generate` - 参数语义详见头文件声明。 +更新 `m_generateMipmaps`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::TextureImportSettings object; - // 根据上下文补齐参数后调用 TextureImportSettings::SetGenerateMipmaps(...)。 - (void)object; -} -``` +- 会更新 `m_generateMipmaps`。 ## 相关文档 -- [返回类总览](TextureImportSettings.md) -- [返回模块目录](../Texture.md) +- [TextureImportSettings](TextureImportSettings.md) +- [GetGenerateMipmaps](GetGenerateMipmaps.md) diff --git a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SetGenerateNormalMap.md b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SetGenerateNormalMap.md index 7b09581c..d89df50c 100644 --- a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SetGenerateNormalMap.md +++ b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SetGenerateNormalMap.md @@ -1,31 +1,26 @@ # TextureImportSettings::SetGenerateNormalMap -设置相关状态或配置。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/TextureImportSettings.h` + +## 签名 ```cpp void SetGenerateNormalMap(bool generate); ``` -该方法声明于 `XCEngine/Resources/Texture/TextureImportSettings.h`，当前页面用于固定 `TextureImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `generate` - 参数语义详见头文件声明。 +更新 `m_generateNormalMap`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::TextureImportSettings object; - // 根据上下文补齐参数后调用 TextureImportSettings::SetGenerateNormalMap(...)。 - (void)object; -} -``` +- 会更新 `m_generateNormalMap`。 ## 相关文档 -- [返回类总览](TextureImportSettings.md) -- [返回模块目录](../Texture.md) +- [TextureImportSettings](TextureImportSettings.md) +- [GetGenerateNormalMap](GetGenerateNormalMap.md) diff --git a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SetMaxAnisotropy.md b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SetMaxAnisotropy.md index 2dea3f79..7b4034bf 100644 --- a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SetMaxAnisotropy.md +++ b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SetMaxAnisotropy.md @@ -1,31 +1,26 @@ # TextureImportSettings::SetMaxAnisotropy -设置相关状态或配置。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/TextureImportSettings.h` + +## 签名 ```cpp void SetMaxAnisotropy(Core::uint32 anisotropy); ``` -该方法声明于 `XCEngine/Resources/Texture/TextureImportSettings.h`，当前页面用于固定 `TextureImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `anisotropy` - 参数语义详见头文件声明。 +更新 `m_maxAnisotropy`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::TextureImportSettings object; - // 根据上下文补齐参数后调用 TextureImportSettings::SetMaxAnisotropy(...)。 - (void)object; -} -``` +- 会更新 `m_maxAnisotropy`。 ## 相关文档 -- [返回类总览](TextureImportSettings.md) -- [返回模块目录](../Texture.md) +- [TextureImportSettings](TextureImportSettings.md) +- [GetMaxAnisotropy](GetMaxAnisotropy.md) diff --git a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SetMaxSize.md b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SetMaxSize.md index 24be80d0..29c450e3 100644 --- a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SetMaxSize.md +++ b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SetMaxSize.md @@ -1,31 +1,26 @@ # TextureImportSettings::SetMaxSize -设置相关状态或配置。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/TextureImportSettings.h` + +## 签名 ```cpp void SetMaxSize(Core::uint32 size); ``` -该方法声明于 `XCEngine/Resources/Texture/TextureImportSettings.h`，当前页面用于固定 `TextureImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `size` - 参数语义详见头文件声明。 +更新 `m_maxSize`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::TextureImportSettings object; - // 根据上下文补齐参数后调用 TextureImportSettings::SetMaxSize(...)。 - (void)object; -} -``` +- 会更新 `m_maxSize`。 ## 相关文档 -- [返回类总览](TextureImportSettings.md) -- [返回模块目录](../Texture.md) +- [TextureImportSettings](TextureImportSettings.md) +- [GetMaxSize](GetMaxSize.md) diff --git a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SetMipmapFilter.md b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SetMipmapFilter.md index d5bbe59d..40bcc01f 100644 --- a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SetMipmapFilter.md +++ b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SetMipmapFilter.md @@ -1,31 +1,26 @@ # TextureImportSettings::SetMipmapFilter -设置相关状态或配置。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/TextureImportSettings.h` + +## 签名 ```cpp void SetMipmapFilter(MipmapFilter filter); ``` -该方法声明于 `XCEngine/Resources/Texture/TextureImportSettings.h`，当前页面用于固定 `TextureImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `filter` - 参数语义详见头文件声明。 +更新 `m_mipmapFilter`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::TextureImportSettings object; - // 根据上下文补齐参数后调用 TextureImportSettings::SetMipmapFilter(...)。 - (void)object; -} -``` +- 会更新 `m_mipmapFilter`。 ## 相关文档 -- [返回类总览](TextureImportSettings.md) -- [返回模块目录](../Texture.md) +- [TextureImportSettings](TextureImportSettings.md) +- [GetMipmapFilter](GetMipmapFilter.md) diff --git a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SetNormalMapStrength.md b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SetNormalMapStrength.md index 9b91475d..aa1a5ef3 100644 --- a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SetNormalMapStrength.md +++ b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SetNormalMapStrength.md @@ -1,31 +1,26 @@ # TextureImportSettings::SetNormalMapStrength -设置相关状态或配置。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/TextureImportSettings.h` + +## 签名 ```cpp void SetNormalMapStrength(float strength); ``` -该方法声明于 `XCEngine/Resources/Texture/TextureImportSettings.h`，当前页面用于固定 `TextureImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `strength` - 参数语义详见头文件声明。 +更新 `m_normalMapStrength`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::TextureImportSettings object; - // 根据上下文补齐参数后调用 TextureImportSettings::SetNormalMapStrength(...)。 - (void)object; -} -``` +- 会更新 `m_normalMapStrength`。 ## 相关文档 -- [返回类总览](TextureImportSettings.md) -- [返回模块目录](../Texture.md) +- [TextureImportSettings](TextureImportSettings.md) +- [GetNormalMapStrength](GetNormalMapStrength.md) diff --git a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SetSRGB.md b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SetSRGB.md index e617aa7c..f4e624f2 100644 --- a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SetSRGB.md +++ b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SetSRGB.md @@ -1,31 +1,26 @@ # TextureImportSettings::SetSRGB -设置相关状态或配置。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/TextureImportSettings.h` + +## 签名 ```cpp void SetSRGB(bool srgb); ``` -该方法声明于 `XCEngine/Resources/Texture/TextureImportSettings.h`，当前页面用于固定 `TextureImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `srgb` - 参数语义详见头文件声明。 +更新 `m_sRGB`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::TextureImportSettings object; - // 根据上下文补齐参数后调用 TextureImportSettings::SetSRGB(...)。 - (void)object; -} -``` +- 会更新 `m_sRGB`。 ## 相关文档 -- [返回类总览](TextureImportSettings.md) -- [返回模块目录](../Texture.md) +- [TextureImportSettings](TextureImportSettings.md) +- [GetSRGB](GetSRGB.md) diff --git a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SetTargetFormat.md b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SetTargetFormat.md index 645e7413..e0748916 100644 --- a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SetTargetFormat.md +++ b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SetTargetFormat.md @@ -1,31 +1,26 @@ # TextureImportSettings::SetTargetFormat -设置相关状态或配置。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/TextureImportSettings.h` + +## 签名 ```cpp void SetTargetFormat(TextureFormat format); ``` -该方法声明于 `XCEngine/Resources/Texture/TextureImportSettings.h`，当前页面用于固定 `TextureImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `format` - 参数语义详见头文件声明。 +更新 `m_targetFormat`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::TextureImportSettings object; - // 根据上下文补齐参数后调用 TextureImportSettings::SetTargetFormat(...)。 - (void)object; -} -``` +- 会更新 `m_targetFormat`。 ## 相关文档 -- [返回类总览](TextureImportSettings.md) -- [返回模块目录](../Texture.md) +- [TextureImportSettings](TextureImportSettings.md) +- [GetTargetFormat](GetTargetFormat.md) diff --git a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SetTextureType.md b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SetTextureType.md index 1330ff0e..e201784a 100644 --- a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SetTextureType.md +++ b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SetTextureType.md @@ -1,31 +1,26 @@ # TextureImportSettings::SetTextureType -设置相关状态或配置。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/TextureImportSettings.h` + +## 签名 ```cpp void SetTextureType(TextureType type); ``` -该方法声明于 `XCEngine/Resources/Texture/TextureImportSettings.h`，当前页面用于固定 `TextureImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `type` - 参数语义详见头文件声明。 +更新 `m_textureType`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::TextureImportSettings object; - // 根据上下文补齐参数后调用 TextureImportSettings::SetTextureType(...)。 - (void)object; -} -``` +- 会更新 `m_textureType`。 ## 相关文档 -- [返回类总览](TextureImportSettings.md) -- [返回模块目录](../Texture.md) +- [TextureImportSettings](TextureImportSettings.md) +- [GetTextureType](GetTextureType.md) diff --git a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SetUseHardwareCompression.md b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SetUseHardwareCompression.md index 0d781de6..8677e5fd 100644 --- a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SetUseHardwareCompression.md +++ b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/SetUseHardwareCompression.md @@ -1,31 +1,26 @@ # TextureImportSettings::SetUseHardwareCompression -设置相关状态或配置。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/TextureImportSettings.h` + +## 签名 ```cpp void SetUseHardwareCompression(bool use); ``` -该方法声明于 `XCEngine/Resources/Texture/TextureImportSettings.h`，当前页面用于固定 `TextureImportSettings` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `use` - 参数语义详见头文件声明。 +更新 `m_useHardwareCompression`。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::TextureImportSettings object; - // 根据上下文补齐参数后调用 TextureImportSettings::SetUseHardwareCompression(...)。 - (void)object; -} -``` +- 会更新 `m_useHardwareCompression`。 ## 相关文档 -- [返回类总览](TextureImportSettings.md) -- [返回模块目录](../Texture.md) +- [TextureImportSettings](TextureImportSettings.md) +- [GetUseHardwareCompression](GetUseHardwareCompression.md) diff --git a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/TextureImportSettings.md b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/TextureImportSettings.md index 540cef57..4c967b11 100644 --- a/docs/api/XCEngine/Resources/Texture/TextureImportSettings/TextureImportSettings.md +++ b/docs/api/XCEngine/Resources/Texture/TextureImportSettings/TextureImportSettings.md @@ -6,57 +6,63 @@ **头文件**: `XCEngine/Resources/Texture/TextureImportSettings.h` -**描述**: 定义 `XCEngine/Resources/Texture` 子目录中的 `TextureImportSettings` public API。 +**描述**: 纹理导入设置对象，集中描述纹理类型、目标格式、mipmap、采样、翻转、压缩和法线贴图生成选项。 ## 概述 -`TextureImportSettings.h` 是 `XCEngine/Resources/Texture` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。 +`TextureImportSettings` 是纹理导入阶段的参数容器。它继承自 `ImportSettings`，当前头文件把纹理导入关注点集中在几类可调项上： + +- 纹理类型和目标像素格式 +- mipmap 生成策略与各向异性过滤 +- sRGB、水平 / 垂直翻转、边框色 +- 压缩质量、硬件压缩开关和最大尺寸 +- 法线贴图生成与强度 ## 声明概览 | 声明 | 类型 | 说明 | |------|------|------| -| `MipmapFilter` | `enum class` | 头文件中的公开声明。 | -| `CompressionQuality` | `enum class` | 头文件中的公开声明。 | -| `TextureImportSettings` | `class` | 继承自 `ImportSettings` 的公开声明。 | +| `MipmapFilter` | `enum class` | mipmap 生成滤波模式。 | +| `CompressionQuality` | `enum class` | 纹理压缩质量档位。 | +| `TextureImportSettings` | `class` | 纹理导入参数对象。 | ## 公共方法 | 方法 | 描述 | |------|------| -| [TextureImportSettings()](Constructor.md) | 构造对象。 | -| [~TextureImportSettings()](Destructor.md) | 销毁对象并释放相关资源。 | -| [Clone](Clone.md) | 公开方法，详见头文件声明。 | -| [LoadFromJSON](LoadFromJSON.md) | 加载资源或数据。 | -| [SaveToJSON](SaveToJSON.md) | 公开方法，详见头文件声明。 | -| [SetTextureType](SetTextureType.md) | 设置相关状态或配置。 | -| [GetTextureType](GetTextureType.md) | 获取相关状态或对象。 | -| [SetTargetFormat](SetTargetFormat.md) | 设置相关状态或配置。 | -| [GetTargetFormat](GetTargetFormat.md) | 获取相关状态或对象。 | -| [SetGenerateMipmaps](SetGenerateMipmaps.md) | 设置相关状态或配置。 | -| [GetGenerateMipmaps](GetGenerateMipmaps.md) | 获取相关状态或对象。 | -| [SetMipmapFilter](SetMipmapFilter.md) | 设置相关状态或配置。 | -| [GetMipmapFilter](GetMipmapFilter.md) | 获取相关状态或对象。 | -| [SetMaxAnisotropy](SetMaxAnisotropy.md) | 设置相关状态或配置。 | -| [GetMaxAnisotropy](GetMaxAnisotropy.md) | 获取相关状态或对象。 | -| [SetSRGB](SetSRGB.md) | 设置相关状态或配置。 | -| [GetSRGB](GetSRGB.md) | 获取相关状态或对象。 | -| [SetFlipVertical](SetFlipVertical.md) | 设置相关状态或配置。 | -| [GetFlipVertical](GetFlipVertical.md) | 获取相关状态或对象。 | -| [SetFlipHorizontal](SetFlipHorizontal.md) | 设置相关状态或配置。 | -| [GetFlipHorizontal](GetFlipHorizontal.md) | 获取相关状态或对象。 | -| [SetBorderColor](SetBorderColor.md) | 设置相关状态或配置。 | -| [GetBorderColor](GetBorderColor.md) | 获取相关状态或对象。 | -| [SetCompressionQuality](SetCompressionQuality.md) | 设置相关状态或配置。 | -| [GetCompressionQuality](GetCompressionQuality.md) | 获取相关状态或对象。 | -| [SetUseHardwareCompression](SetUseHardwareCompression.md) | 设置相关状态或配置。 | -| [GetUseHardwareCompression](GetUseHardwareCompression.md) | 获取相关状态或对象。 | -| [SetMaxSize](SetMaxSize.md) | 设置相关状态或配置。 | -| [GetMaxSize](GetMaxSize.md) | 获取相关状态或对象。 | -| [SetGenerateNormalMap](SetGenerateNormalMap.md) | 设置相关状态或配置。 | -| [GetGenerateNormalMap](GetGenerateNormalMap.md) | 获取相关状态或对象。 | -| [SetNormalMapStrength](SetNormalMapStrength.md) | 设置相关状态或配置。 | -| [GetNormalMapStrength](GetNormalMapStrength.md) | 获取相关状态或对象。 | +| [TextureImportSettings()](Constructor.md) | 构造 `TextureImportSettings` 实例。 | +| [~TextureImportSettings()](Destructor.md) | 销毁 `TextureImportSettings` 实例。 | +| [Clone](Clone.md) | 执行 `TextureImportSettings(...)` 相关流程。 | +| [LoadFromJSON](LoadFromJSON.md) | 固定返回 `false`。 | +| [SaveToJSON](SaveToJSON.md) | 执行 `String(...)` 相关流程。 | +| [SetTextureType](SetTextureType.md) | 更新 `m_textureType`。 | +| [GetTextureType](GetTextureType.md) | 返回 `m_textureType` 当前值。 | +| [SetTargetFormat](SetTargetFormat.md) | 更新 `m_targetFormat`。 | +| [GetTargetFormat](GetTargetFormat.md) | 返回 `m_targetFormat` 当前值。 | +| [SetGenerateMipmaps](SetGenerateMipmaps.md) | 更新 `m_generateMipmaps`。 | +| [GetGenerateMipmaps](GetGenerateMipmaps.md) | 返回 `m_generateMipmaps` 当前值。 | +| [SetMipmapFilter](SetMipmapFilter.md) | 更新 `m_mipmapFilter`。 | +| [GetMipmapFilter](GetMipmapFilter.md) | 返回 `m_mipmapFilter` 当前值。 | +| [SetMaxAnisotropy](SetMaxAnisotropy.md) | 更新 `m_maxAnisotropy`。 | +| [GetMaxAnisotropy](GetMaxAnisotropy.md) | 返回 `m_maxAnisotropy` 当前值。 | +| [SetSRGB](SetSRGB.md) | 更新 `m_sRGB`。 | +| [GetSRGB](GetSRGB.md) | 返回 `m_sRGB` 当前值。 | +| [SetFlipVertical](SetFlipVertical.md) | 更新 `m_flipVertical`。 | +| [GetFlipVertical](GetFlipVertical.md) | 返回 `m_flipVertical` 当前值。 | +| [SetFlipHorizontal](SetFlipHorizontal.md) | 更新 `m_flipHorizontal`。 | +| [GetFlipHorizontal](GetFlipHorizontal.md) | 返回 `m_flipHorizontal` 当前值。 | +| [SetBorderColor](SetBorderColor.md) | 更新 `m_borderColor`。 | +| [GetBorderColor](GetBorderColor.md) | 返回 `m_borderColor` 当前值。 | +| [SetCompressionQuality](SetCompressionQuality.md) | 更新 `m_compressionQuality`。 | +| [GetCompressionQuality](GetCompressionQuality.md) | 返回 `m_compressionQuality` 当前值。 | +| [SetUseHardwareCompression](SetUseHardwareCompression.md) | 更新 `m_useHardwareCompression`。 | +| [GetUseHardwareCompression](GetUseHardwareCompression.md) | 返回 `m_useHardwareCompression` 当前值。 | +| [SetMaxSize](SetMaxSize.md) | 更新 `m_maxSize`。 | +| [GetMaxSize](GetMaxSize.md) | 返回 `m_maxSize` 当前值。 | +| [SetGenerateNormalMap](SetGenerateNormalMap.md) | 更新 `m_generateNormalMap`。 | +| [GetGenerateNormalMap](GetGenerateNormalMap.md) | 返回 `m_generateNormalMap` 当前值。 | +| [SetNormalMapStrength](SetNormalMapStrength.md) | 更新 `m_normalMapStrength`。 | +| [GetNormalMapStrength](GetNormalMapStrength.md) | 返回 `m_normalMapStrength` 当前值。 | ## 相关文档 diff --git a/docs/api/XCEngine/Resources/Texture/TextureLoader/CanLoad.md b/docs/api/XCEngine/Resources/Texture/TextureLoader/CanLoad.md index a897db00..1dd75c93 100644 --- a/docs/api/XCEngine/Resources/Texture/TextureLoader/CanLoad.md +++ b/docs/api/XCEngine/Resources/Texture/TextureLoader/CanLoad.md @@ -1,31 +1,26 @@ # TextureLoader::CanLoad -判断当前条件下是否可执行。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/TextureLoader.h` + +## 签名 ```cpp bool CanLoad(const Containers::String& path) const override; ``` -该方法声明于 `XCEngine/Resources/Texture/TextureLoader.h`，当前页面用于固定 `TextureLoader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `path` - 参数语义详见头文件声明。 +执行 `IsBuiltinTexturePath`、`GetExtension`、`ToLower` 协同流程。 -**返回：** `bool` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::TextureLoader object; - // 根据上下文补齐参数后调用 TextureLoader::CanLoad(...)。 - (void)object; -} -``` +- 当前实现会调用 `IsBuiltinTexturePath`、`GetExtension`、`ToLower`。 +- 包含条件分支，并可能提前返回。 ## 相关文档 -- [返回类总览](TextureLoader.md) -- [返回模块目录](../Texture.md) +- [TextureLoader](TextureLoader.md) diff --git a/docs/api/XCEngine/Resources/Texture/TextureLoader/Constructor.md b/docs/api/XCEngine/Resources/Texture/TextureLoader/Constructor.md index 235bb24b..5349ee83 100644 --- a/docs/api/XCEngine/Resources/Texture/TextureLoader/Constructor.md +++ b/docs/api/XCEngine/Resources/Texture/TextureLoader/Constructor.md @@ -1,28 +1,25 @@ # TextureLoader::TextureLoader() -构造对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/TextureLoader.h` + +## 签名 ```cpp TextureLoader(); ``` -该方法声明于 `XCEngine/Resources/Texture/TextureLoader.h`，当前页面用于固定 `TextureLoader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +构造 `TextureLoader` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::TextureLoader object; -} -``` +- 当前为默认构造实现。 ## 相关文档 -- [返回类总览](TextureLoader.md) -- [返回模块目录](../Texture.md) +- [TextureLoader](TextureLoader.md) diff --git a/docs/api/XCEngine/Resources/Texture/TextureLoader/Destructor.md b/docs/api/XCEngine/Resources/Texture/TextureLoader/Destructor.md index 977f2c65..8b243767 100644 --- a/docs/api/XCEngine/Resources/Texture/TextureLoader/Destructor.md +++ b/docs/api/XCEngine/Resources/Texture/TextureLoader/Destructor.md @@ -1,29 +1,25 @@ # TextureLoader::~TextureLoader() -销毁对象并释放相关资源。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/TextureLoader.h` + +## 签名 ```cpp virtual ~TextureLoader() override; ``` -该方法声明于 `XCEngine/Resources/Texture/TextureLoader.h`，当前页面用于固定 `TextureLoader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +销毁 `TextureLoader` 实例。 -**返回：** `void` - 无返回值。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::TextureLoader object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 当前为默认析构实现。 ## 相关文档 -- [返回类总览](TextureLoader.md) -- [返回模块目录](../Texture.md) +- [TextureLoader](TextureLoader.md) diff --git a/docs/api/XCEngine/Resources/Texture/TextureLoader/GetDefaultSettings.md b/docs/api/XCEngine/Resources/Texture/TextureLoader/GetDefaultSettings.md index 8650233e..b6745e28 100644 --- a/docs/api/XCEngine/Resources/Texture/TextureLoader/GetDefaultSettings.md +++ b/docs/api/XCEngine/Resources/Texture/TextureLoader/GetDefaultSettings.md @@ -1,30 +1,25 @@ # TextureLoader::GetDefaultSettings -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/TextureLoader.h` + +## 签名 ```cpp ImportSettings* GetDefaultSettings() const override; ``` -该方法声明于 `XCEngine/Resources/Texture/TextureLoader.h`，当前页面用于固定 `TextureLoader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +固定返回 `nullptr`。 -**返回：** `ImportSettings*` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::TextureLoader object; - // 根据上下文补齐参数后调用 TextureLoader::GetDefaultSettings(...)。 - (void)object; -} -``` +- 包含 `nullptr` 相关分支。 ## 相关文档 -- [返回类总览](TextureLoader.md) -- [返回模块目录](../Texture.md) +- [TextureLoader](TextureLoader.md) diff --git a/docs/api/XCEngine/Resources/Texture/TextureLoader/GetResourceType.md b/docs/api/XCEngine/Resources/Texture/TextureLoader/GetResourceType.md index bd3dc7ed..fcbcb7e7 100644 --- a/docs/api/XCEngine/Resources/Texture/TextureLoader/GetResourceType.md +++ b/docs/api/XCEngine/Resources/Texture/TextureLoader/GetResourceType.md @@ -1,30 +1,25 @@ # TextureLoader::GetResourceType -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/TextureLoader.h` + +## 签名 ```cpp ResourceType GetResourceType() const override; ``` -该方法声明于 `XCEngine/Resources/Texture/TextureLoader.h`，当前页面用于固定 `TextureLoader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `ResourceType::Texture`。 -**返回：** `ResourceType` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::TextureLoader object; - // 根据上下文补齐参数后调用 TextureLoader::GetResourceType(...)。 - (void)object; -} -``` +- 返回 `ResourceType::Texture`。 ## 相关文档 -- [返回类总览](TextureLoader.md) -- [返回模块目录](../Texture.md) +- [TextureLoader](TextureLoader.md) diff --git a/docs/api/XCEngine/Resources/Texture/TextureLoader/GetSupportedExtensions.md b/docs/api/XCEngine/Resources/Texture/TextureLoader/GetSupportedExtensions.md index 3b65715d..963bf12e 100644 --- a/docs/api/XCEngine/Resources/Texture/TextureLoader/GetSupportedExtensions.md +++ b/docs/api/XCEngine/Resources/Texture/TextureLoader/GetSupportedExtensions.md @@ -1,30 +1,25 @@ # TextureLoader::GetSupportedExtensions -获取相关状态或对象。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/TextureLoader.h` + +## 签名 ```cpp Containers::Array GetSupportedExtensions() const override; ``` -该方法声明于 `XCEngine/Resources/Texture/TextureLoader.h`，当前页面用于固定 `TextureLoader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** 无。 +返回 `extensions`。 -**返回：** `Containers::Array` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::TextureLoader object; - // 根据上下文补齐参数后调用 TextureLoader::GetSupportedExtensions(...)。 - (void)object; -} -``` +- 当前实现会调用 `PushBack`、`String`。 ## 相关文档 -- [返回类总览](TextureLoader.md) -- [返回模块目录](../Texture.md) +- [TextureLoader](TextureLoader.md) diff --git a/docs/api/XCEngine/Resources/Texture/TextureLoader/Load.md b/docs/api/XCEngine/Resources/Texture/TextureLoader/Load.md index 50b4de09..a58353fd 100644 --- a/docs/api/XCEngine/Resources/Texture/TextureLoader/Load.md +++ b/docs/api/XCEngine/Resources/Texture/TextureLoader/Load.md @@ -1,32 +1,27 @@ # TextureLoader::Load -加载资源或数据。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/TextureLoader.h` + +## 签名 ```cpp LoadResult Load(const Containers::String& path, const ImportSettings* settings = nullptr) override; ``` -该方法声明于 `XCEngine/Resources/Texture/TextureLoader.h`，当前页面用于固定 `TextureLoader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `path` - 参数语义详见头文件声明。 -- `settings` - 参数语义详见头文件声明。 +执行 `IsBuiltinTexturePath`、`CreateBuiltinTextureResource`、`GetExtension` 协同流程。 -**返回：** `LoadResult` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::TextureLoader object; - // 根据上下文补齐参数后调用 TextureLoader::Load(...)。 - (void)object; -} -``` +- 当前实现会调用 `IsBuiltinTexturePath`、`CreateBuiltinTextureResource`、`GetExtension`、`ToLower`、`CanLoad`。 +- 包含条件分支，并可能提前返回。 +- 当前实现仍带有未完成分支。 ## 相关文档 -- [返回类总览](TextureLoader.md) -- [返回模块目录](../Texture.md) +- [TextureLoader](TextureLoader.md) diff --git a/docs/api/XCEngine/Resources/Texture/TextureLoader/LoadFromMemory.md b/docs/api/XCEngine/Resources/Texture/TextureLoader/LoadFromMemory.md index a2bab5f7..5672fe30 100644 --- a/docs/api/XCEngine/Resources/Texture/TextureLoader/LoadFromMemory.md +++ b/docs/api/XCEngine/Resources/Texture/TextureLoader/LoadFromMemory.md @@ -1,33 +1,25 @@ # TextureLoader::LoadFromMemory -加载资源或数据。 +**命名空间**: `XCEngine::Resources` + +**类型**: `method` + +**头文件**: `XCEngine/Resources/Texture/TextureLoader.h` + +## 签名 ```cpp -LoadResult LoadFromMemory(const Containers::String& path, const void* data, size_t dataSize) const; +LoadResult LoadFromMemory( const Containers::String& path, const void* data, size_t dataSize, const ImportSettings* settings = nullptr) const; ``` -该方法声明于 `XCEngine/Resources/Texture/TextureLoader.h`，当前页面用于固定 `TextureLoader` 类目录下的方法级 canonical 路径。 +## 作用 -**参数：** -- `path` - 参数语义详见头文件声明。 -- `data` - 参数语义详见头文件声明。 -- `dataSize` - 参数语义详见头文件声明。 +执行 `LoadFromMemory` 加载流程。 -**返回：** `LoadResult` - 返回值语义详见头文件声明。 +## 当前实现 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Resources::TextureLoader object; - // 根据上下文补齐参数后调用 TextureLoader::LoadFromMemory(...)。 - (void)object; -} -``` +- 具体定义位于 `engine/src/Resources/Texture/TextureLoader.cpp`。 ## 相关文档 -- [返回类总览](TextureLoader.md) -- [返回模块目录](../Texture.md) +- [TextureLoader](TextureLoader.md) diff --git a/docs/api/XCEngine/Resources/Texture/TextureLoader/TextureLoader.md b/docs/api/XCEngine/Resources/Texture/TextureLoader/TextureLoader.md index 207ba63f..e216726c 100644 --- a/docs/api/XCEngine/Resources/Texture/TextureLoader/TextureLoader.md +++ b/docs/api/XCEngine/Resources/Texture/TextureLoader/TextureLoader.md @@ -6,30 +6,36 @@ **头文件**: `XCEngine/Resources/Texture/TextureLoader.h` -**描述**: 定义 `XCEngine/Resources/Texture` 子目录中的 `TextureLoader` public API。 +**描述**: 纹理资源 loader，负责识别支持的纹理文件、执行加载，并提供默认纹理导入设置。 ## 概述 -`TextureLoader.h` 是 `XCEngine/Resources/Texture` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。 +`TextureLoader` 是 `Texture` 资源进入资源系统的标准入口。它继承自 `IResourceLoader`，当前头文件约定的核心职责是： + +- 声明自己负责 `ResourceType::Texture` +- 给出支持的文件扩展名 +- 判断某个路径是否可由当前 loader 处理 +- 从磁盘或内存把内容解码成 `LoadResult` +- 提供默认纹理导入设置 ## 声明概览 | 声明 | 类型 | 说明 | |------|------|------| -| `TextureLoader` | `class` | 继承自 `IResourceLoader` 的公开声明。 | +| `TextureLoader` | `class` | `Texture` 资源的加载器。 | ## 公共方法 | 方法 | 描述 | |------|------| -| [TextureLoader()](Constructor.md) | 构造对象。 | -| [~TextureLoader()](Destructor.md) | 销毁对象并释放相关资源。 | -| [GetResourceType](GetResourceType.md) | 获取相关状态或对象。 | -| [GetSupportedExtensions](GetSupportedExtensions.md) | 获取相关状态或对象。 | -| [CanLoad](CanLoad.md) | 判断当前条件下是否可执行。 | -| [Load](Load.md) | 加载资源或数据。 | -| [LoadFromMemory](LoadFromMemory.md) | 加载资源或数据。 | -| [GetDefaultSettings](GetDefaultSettings.md) | 获取相关状态或对象。 | +| [TextureLoader()](Constructor.md) | 构造 `TextureLoader` 实例。 | +| [~TextureLoader()](Destructor.md) | 销毁 `TextureLoader` 实例。 | +| [GetResourceType](GetResourceType.md) | 返回 `ResourceType::Texture`。 | +| [GetSupportedExtensions](GetSupportedExtensions.md) | 执行 `PushBack`、`String` 协同流程。 | +| [CanLoad](CanLoad.md) | 执行 `IsBuiltinTexturePath`、`GetExtension`、`ToLower` 协同流程。 | +| [Load](Load.md) | 执行 `IsBuiltinTexturePath`、`CreateBuiltinTextureResource`、`GetExtension` 协同流程。 | +| [LoadFromMemory](LoadFromMemory.md) | 执行 `LoadResult`、`String`、`stbi_is_hdr_from_memory` 协同流程。 | +| [GetDefaultSettings](GetDefaultSettings.md) | 固定返回 `nullptr`。 | ## 相关文档 diff --git a/docs/api/XCEngine/Resources/UI/UI.md b/docs/api/XCEngine/Resources/UI/UI.md new file mode 100644 index 00000000..4c848bf4 --- /dev/null +++ b/docs/api/XCEngine/Resources/UI/UI.md @@ -0,0 +1,21 @@ +# UI + +**命名空间**: `XCEngine::Resources` + +**类型**: `submodule` + +**头文件目录**: `engine/include/XCEngine/Resources/UI/` + +**描述**: XCUI 文档资源层，负责 UI 文档类型、加载器、文档集合与文档编译器。 + +## 当前范围 + +- [UIDocumentTypes](UIDocumentTypes/UIDocumentTypes.md) +- [UIDocumentLoaders](UIDocumentLoaders/UIDocumentLoaders.md) +- [UIDocuments](UIDocuments/UIDocuments.md) +- [UIDocumentCompiler](UIDocumentCompiler/UIDocumentCompiler.md) + +## 相关文档 + +- [Resources](../Resources.md) +- [UI](../../UI/UI.md) diff --git a/docs/api/XCEngine/Resources/UI/UIDocumentCompiler/UIDocumentCompiler.md b/docs/api/XCEngine/Resources/UI/UIDocumentCompiler/UIDocumentCompiler.md new file mode 100644 index 00000000..cf8ac5a6 --- /dev/null +++ b/docs/api/XCEngine/Resources/UI/UIDocumentCompiler/UIDocumentCompiler.md @@ -0,0 +1,63 @@ +# UIDocumentCompiler + +**命名空间**: `XCEngine::Resources` + +**类型**: `structs + free functions` + +**头文件**: `XCEngine/Resources/UI/UIDocumentCompiler.h` + +**描述**: XCUI 文档编译与 artifact 读写入口，负责把 `.xcui` / `.xctheme` / `.xcschema` 源文件解析成 `UIDocumentModel`，并把结果序列化或反序列化为 UI artifact。 +## 概览 + +按 `engine/src/Resources/UI/UIDocumentCompiler.cpp` 当前实现，这组 API 的主链是： + +1. `CompileUIDocument(...)` + - 读取源文件 + - 解析 XML 风格节点树 + - 强校验根标签 + - 对 schema 文档构建 `UISchemaDefinition` + - 扫描依赖并汇总诊断 +2. `WriteUIDocumentArtifact(...)` + - 把 `UIDocumentCompileResult` 写成二进制 artifact +3. `LoadUIDocumentArtifact(...)` + - 读取 artifact + - 校验 magic / schema version / kind + - 在旧 schema artifact 缺少显式 schema 定义时回建 `UISchemaDefinition` + +## 公开声明 + +| 声明 | 角色 | +|------|------| +| `UIDocumentCompileRequest` | 调用侧输入，包含 `kind`、`path` 和可选 `expectedRootTag`。 | +| `UIDocumentCompileResult` | 输出对象，包含 `document`、`errorMessage` 和 `succeeded`。 | +| `CompileUIDocument(...)` | 从源文件编译 XCUI 文档。 | +| `WriteUIDocumentArtifact(...)` | 把成功的编译结果写成 artifact。 | +| `LoadUIDocumentArtifact(...)` | 从 artifact 反序列化出文档模型。 | +| `GetUIDocumentDefaultRootTag(...)` | 为 `View` / `Theme` / `Schema` 提供默认根标签。 | + +## 当前实现行为 + +- 源文件读取优先使用传入路径；如果路径是相对路径，且 `ResourceManager::Get().GetResourceRoot()` 非空，会再尝试拼接资源根读取。 +- 解析器当前支持 UTF-8 BOM、XML 注释 `` 和 processing instruction ``，属性值支持单引号和双引号。 +- 当前不支持文本节点；根节点之外出现文本内容会直接报错。 +- 如果 `expectedRootTag` 为空，`CompileUIDocument(...)` 会退回 `GetUIDocumentDefaultRootTag(kind)`。 +- schema 文档要求根节点是 ``，并且只接受 `` / `` 这条 schema 描述链。 +- 依赖收集当前通过“看起来像 `.xcui` / `.xctheme` / `.xcschema` 的属性值”完成；相对依赖路径按源文件目录解析。 +- 缺失依赖会产生 `Error` 诊断，并让编译整体失败。 +- `WriteUIDocumentArtifact(...)` 只接受 `compileResult.succeeded && compileResult.document.valid` 的结果。 +- `LoadUIDocumentArtifact(...)` 当前兼容 schema version `1` 和 `kUIDocumentArtifactSchemaVersion`；读旧版 schema artifact 时，若未带显式 schema 定义，会再次从根节点回建。 + +## 测试与调用链 + +- `tests/Resources/UI/test_ui_schema_document.cpp` 覆盖 schema 编译失败路径、artifact round-trip 与 schema 回建。 +- `tests/Resources/UI/test_ui_document_loader.cpp` 覆盖依赖收集、缺依赖错误与 artifact 导入。 +- `engine/src/Core/Asset/AssetDatabase.cpp` 的 `ImportUIDocumentAsset(...)` 当前直接依赖 `CompileUIDocument(...)` 与 `WriteUIDocumentArtifact(...)`。 +- `engine/src/UI/Runtime/UIScreenDocumentHost.cpp` 当前在运行时热编译 view/theme 文档，并通过 `GetUIDocumentDefaultRootTag(...)` 统一默认根标签。 + +## 相关文档 + +- [Resources UI](../UI.md) +- [UIDocumentTypes](../UIDocumentTypes/UIDocumentTypes.md) +- [UIDocuments](../UIDocuments/UIDocuments.md) +- [UIDocumentLoaders](../UIDocumentLoaders/UIDocumentLoaders.md) +- [ResourceManager](../../../Core/Asset/ResourceManager/ResourceManager.md) diff --git a/docs/api/XCEngine/Resources/UI/UIDocumentLoaders/UIDocumentLoaders.md b/docs/api/XCEngine/Resources/UI/UIDocumentLoaders/UIDocumentLoaders.md new file mode 100644 index 00000000..39139b6c --- /dev/null +++ b/docs/api/XCEngine/Resources/UI/UIDocumentLoaders/UIDocumentLoaders.md @@ -0,0 +1,45 @@ +# UIDocumentLoaders + +**命名空间**: `XCEngine::Resources` + +**类型**: `class family` + +**头文件**: `XCEngine/Resources/UI/UIDocumentLoaders.h` + +**描述**: XCUI view/theme/schema 文档的资源 loader 家族，负责识别 source 与 artifact 扩展名，调用编译器或 artifact 反序列化，再把结果包装成对应的 `IResource` 子类。 +## 概览 + +当前有三种 loader： + +| Loader | `ResourceType` | Source 扩展名 | Artifact 扩展名 | +|------|------|------|------| +| `UIViewLoader` | `UIView` | `.xcui` | `.xcuiasset` | +| `UIThemeLoader` | `UITheme` | `.xctheme` | `.xcthemeasset` | +| `UISchemaLoader` | `UISchema` | `.xcschema` | `.xcschemaasset` | + +按 `engine/src/Resources/UI/UIDocumentLoaders.cpp` 当前实现： + +- `CanLoad(...)` 只按扩展名判断，不验证文件是否存在。 +- `Load(...)` 遇到 artifact 扩展名时走 `LoadUIDocumentArtifact(...)`，否则走 `CompileUIDocument(...)`。 +- 加载成功后，返回的资源名优先使用文档内的 `displayName`，否则回退到路径 stem。 +- 资源路径优先使用编译结果里的 `sourcePath`；artifact 读回时也会尽量保留原始源路径。 + +## 当前实现边界 + +- `GetDefaultSettings()` 当前固定返回 `nullptr`，说明这三类 loader 还没有独立的 import settings 对象。 +- `CompileDocument(...)` 只是公开一个“只编译不包资源”的便利入口，底层仍然调用 `CompileUIDocument(...)`。 +- `ResourceManager::EnsureInitialized()` 当前把 `UIViewLoader`、`UIThemeLoader` 和 `UISchemaLoader` 作为 builtin loader 注册进去；调用侧通常不需要手工挂载。 + +## 测试与调用链 + +- `tests/Resources/UI/test_ui_document_loader.cpp` 当前覆盖三种 loader 的资源类型、扩展名、依赖追踪和 artifact 导入链。 +- `tests/Resources/UI/test_ui_schema_document.cpp` 当前用 `UISchemaLoader` 覆盖 schema 编译与 artifact round-trip。 +- `engine/src/Core/Asset/ResourceManager.cpp` 当前在初始化路径里注册这三个 loader。 + +## 相关文档 + +- [Resources UI](../UI.md) +- [UIDocumentCompiler](../UIDocumentCompiler/UIDocumentCompiler.md) +- [UIDocumentTypes](../UIDocumentTypes/UIDocumentTypes.md) +- [UIDocuments](../UIDocuments/UIDocuments.md) +- [ResourceManager](../../../Core/Asset/ResourceManager/ResourceManager.md) diff --git a/docs/api/XCEngine/Resources/UI/UIDocumentTypes/UIDocumentTypes.md b/docs/api/XCEngine/Resources/UI/UIDocumentTypes/UIDocumentTypes.md new file mode 100644 index 00000000..02d31a41 --- /dev/null +++ b/docs/api/XCEngine/Resources/UI/UIDocumentTypes/UIDocumentTypes.md @@ -0,0 +1,68 @@ +# UIDocumentTypes + +**命名空间**: `XCEngine::Resources` + +**类型**: `enums + structs` + +**头文件**: `XCEngine/Resources/UI/UIDocumentTypes.h` + +**描述**: XCUI 文档编译、artifact 序列化和运行时加载共用的数据模型，覆盖文档种类、诊断、schema 定义、节点树和聚合后的 `UIDocumentModel`。 +## 概览 + +`UIDocumentTypes.h` 当前承载三层公共数据： + +- 文档分类与诊断元数据 + - `UIDocumentKind` + - `UIDocumentDiagnosticSeverity` + - `UIDocumentSourceLocation` + - `UIDocumentDiagnostic` +- schema 描述树 + - `UISchemaValueType` + - `UISchemaAttributeDefinition` + - `UISchemaElementDefinition` + - `UISchemaDefinition` +- 原始文档树与聚合结果 + - `UIDocumentAttribute` + - `UIDocumentNode` + - `UIDocumentModel` + +按 `engine/src/Resources/UI/UIDocumentCompiler.cpp` 当前实现，`CompileUIDocument(...)` 会先构建 `UIDocumentNode` 树，再在 `Schema` 文档上补建 `UISchemaDefinition`，最后把依赖列表和诊断一起塞进 `UIDocumentModel`。 + +## 关键声明 + +| 声明 | 角色 | +|------|------| +| `UIDocumentKind` | 区分 `View`、`Theme`、`Schema` 三种 XCUI 文档。 | +| `UIDocumentDiagnosticSeverity` | 诊断级别，当前只区分 `Info` / `Warning` / `Error`。 | +| `UISchemaValueType` | schema 属性值类型，支持 `String`、`Boolean`、`Integer`、`Number`、`Document`、`Enum`。 | +| `UIDocumentSourceLocation` | 1-based 行列号。 | +| `UIDocumentAttribute` | 单个 XML 风格属性的 `name/value` 对。 | +| `UIDocumentDiagnostic` | 诊断级别、位置和消息。 | +| `UISchemaAttributeDefinition` | schema 属性定义，包含值类型、允许值、文档种类限制与 required 标记。 | +| `UISchemaElementDefinition` | schema 元素定义，包含属性、子元素与 unknown 允许策略。 | +| `UISchemaDefinition` | 编译后的 schema 根对象。 | +| `UIDocumentNode` | 解析后的 XCUI 节点树。 | +| `UIDocumentModel` | 运行时或 artifact 读回后的完整文档模型。 | + +## 当前实现边界 + +- `UIDocumentSourceLocation` 默认从 `1:1` 开始，编译器和 artifact 读写都沿用这套 1-based 坐标。 +- `FindAttribute(...)`、`FindChild(...)`、`FindElement(...)` 当前都是线性扫描；它们只是轻量查询 helper，不维护额外索引。 +- `UISchemaDefinition::Clear()` 会清空名称、元素并把 `valid` 复位为 `false`。 +- `UIDocumentModel::Clear()` 会清空 `sourcePath`、`displayName`、`rootNode`、`schemaDefinition`、`dependencies`、`diagnostics` 并把 `valid` 置回 `false`，但不会改写 `kind`。 +- `UIDocumentModel.dependencies` 当前保存的是规范化后的依赖路径集合；去重规则在编译阶段按大小写不敏感路径键完成。 + +## 测试与调用链 + +- `tests/Resources/UI/test_ui_schema_document.cpp` 当前覆盖 schema 文档编译、枚举 allowed values、document-kind 限制与 artifact round-trip。 +- `tests/Resources/UI/test_ui_document_loader.cpp` 当前覆盖 view/theme/schema 依赖收集与 artifact 导入链。 +- `tests/UI/Core/unit/test_ui_core.cpp` 当前直接验证 `UIDocumentResource` 子类可以接受 move 进来的 `UIDocumentModel`。 +- `AssetDatabase::ImportUIDocumentAsset(...)` 和 `UIDocumentScreenHost::LoadScreen(...)` 都直接消费这里定义的 `UIDocumentModel`、`UIDocumentDiagnostic` 与依赖列表。 + +## 相关文档 + +- [Resources UI](../UI.md) +- [UIDocumentCompiler](../UIDocumentCompiler/UIDocumentCompiler.md) +- [UIDocuments](../UIDocuments/UIDocuments.md) +- [UIDocumentLoaders](../UIDocumentLoaders/UIDocumentLoaders.md) +- [UI](../../../UI/UI.md) diff --git a/docs/api/XCEngine/Resources/UI/UIDocuments/UIDocuments.md b/docs/api/XCEngine/Resources/UI/UIDocuments/UIDocuments.md new file mode 100644 index 00000000..c8871e10 --- /dev/null +++ b/docs/api/XCEngine/Resources/UI/UIDocuments/UIDocuments.md @@ -0,0 +1,54 @@ +# UIDocuments + +**命名空间**: `XCEngine::Resources` + +**类型**: `class family` + +**头文件**: `XCEngine/Resources/UI/UIDocuments.h` + +**描述**: XCUI 文档资源类型族，负责把 `UIDocumentModel` 包装成 `IResource` 子类，并为 view/theme/schema 三种运行时资源提供统一访问面。 +## 概览 + +`UIDocuments.h` 当前由一个基类和三个固定派生类组成： + +- `UIDocumentResource` + - 保存 `UIDocumentModel` + - 提供 `GetRootNode()`、`GetSchemaDefinition()`、`GetDependencies()`、`GetDiagnostics()`、`GetSourcePath()` + - 负责在写入文档模型后重算 `memorySize` +- `UIView` + - `GetType() == ResourceType::UIView` +- `UITheme` + - `GetType() == ResourceType::UITheme` +- `UISchema` + - `GetType() == ResourceType::UISchema` + +## 当前实现行为 + +- `UIDocumentResource` 的基础资源身份仍然来自 `IResource`：`name`、`path`、`guid`、`isValid` 与 `memorySize` 由 `Initialize(...)` / `SetInvalid()` 那条通用链维护。 +- `SetDocumentModel(const UIDocumentModel&)` 和 `SetDocumentModel(UIDocumentModel&&)` 当前都会立即调用 `RecalculateMemorySize()`。 +- `RecalculateMemorySize()` 会递归估算节点树、schema 定义、依赖字符串和诊断字符串的内存占用；这是缓存估算值，不是精确分配器统计。 +- `Release()` 会清空 `m_document`、调用 `SetInvalid()` 并把 `m_memorySize` 归零。 +- `GetRootNode()`、`GetSchemaDefinition()` 等 getter 当前都只是返回 `m_document` 内部成员的常量引用，不做 defensive copy。 + +## 关键声明 + +| 声明 | 角色 | +|------|------| +| `UIDocumentResource` | XCUI 文档资源基类。 | +| `UIView` | `.xcui` / `.xcuiasset` 的运行时资源类型。 | +| `UITheme` | `.xctheme` / `.xcthemeasset` 的运行时资源类型。 | +| `UISchema` | `.xcschema` / `.xcschemaasset` 的运行时资源类型。 | + +## 测试与调用链 + +- `tests/UI/Core/unit/test_ui_core.cpp` 当前直接验证 `UIView` 和 `UISchema` 可以接受 move 进来的 `UIDocumentModel`，且 getter 返回的新状态可见。 +- `engine/src/Resources/UI/UIDocumentLoaders.cpp` 当前通过这组类型把编译结果包装成 `LoadResult.resource`。 +- `engine/src/Core/Asset/ResourceManager.cpp` 在初始化时注册 view/theme/schema loader，因此这些资源类型会进入统一资源系统。 + +## 相关文档 + +- [Resources UI](../UI.md) +- [UIDocumentTypes](../UIDocumentTypes/UIDocumentTypes.md) +- [UIDocumentCompiler](../UIDocumentCompiler/UIDocumentCompiler.md) +- [UIDocumentLoaders](../UIDocumentLoaders/UIDocumentLoaders.md) +- [ResourceManager](../../../Core/Asset/ResourceManager/ResourceManager.md) diff --git a/docs/api/XCEngine/Scene/Scene.md b/docs/api/XCEngine/Scene/Scene.md index d5e99296..81279120 100644 --- a/docs/api/XCEngine/Scene/Scene.md +++ b/docs/api/XCEngine/Scene/Scene.md @@ -13,24 +13,29 @@ - [Scene](Scene/Scene.md) 负责对象树、场景级更新和场景序列化。 - [SceneManager](SceneManager/SceneManager.md) 负责多场景注册与活动场景入口。 - [SceneRuntime](SceneRuntime/SceneRuntime.md) 负责把某个场景真正“跑起来”，并和脚本系统衔接。 +- [RuntimeLoop](RuntimeLoop/RuntimeLoop.md) 则在 `SceneRuntime` 之上补上 fixed step、暂停和单帧步进这一层时间控制。 -这种分层和商业引擎里常见的思路接近：`Scene` 是数据与对象容器，`SceneManager` 负责更高层的场景切换，而 `SceneRuntime` 则承担运行时执行语义。 +这种分层和商业引擎里常见的思路接近：`Scene` 是数据与对象容器，`SceneManager` 负责更高层的场景切换，`SceneRuntime` 负责运行态语义，而 `RuntimeLoop` 则进一步提供可供 editor play mode 复用的时间推进策略。 ## 设计要点 - `Scene` 专注对象拥有权、查询和序列化，不直接变成庞大的运行时调度中心。 - `SceneRuntime` 把脚本生命周期和场景更新顺序集中管理，避免脚本系统散落到 `Scene` 内部。 +- `RuntimeLoop` 把 fixed/update/late-update 的时间控制从 `SceneRuntime` 再剥出来，便于 pause、step 和 editor play session 复用。 - `SceneManager` 让多场景入口和单个场景数据模型解耦，便于以后扩展更复杂的场景切换策略。 +- 场景序列化会尊重组件自己的资源协议；对 mesh / material 项目资产，当前正式持久化身份是 `AssetRef`，而 `builtin://` 这类 virtual resource 才长期依赖显式路径。 ## 当前实现边界 - 当前公开类型都位于 `XCEngine::Components` 命名空间，而不是单独的 `XCEngine::Scene` 命名空间，这反映了引擎当前建模历史。 - `SceneRuntime` 目前只管理单个运行中的场景。 +- `RuntimeLoop` 当前只是 `SceneRuntime` 的时间控制包装，不是全引擎级 player loop。 - `SceneManager::LoadSceneAsync()` 仍是同步包装，不是完整异步加载系统。 - 场景序列化使用引擎私有文本格式，强调可落地而不是通用交换格式。 ## 头文件 +- [RuntimeLoop](RuntimeLoop/RuntimeLoop.md) - `RuntimeLoop.h` - [Scene](Scene/Scene.md) - `Scene.h` - [SceneManager](SceneManager/SceneManager.md) - `SceneManager.h` - [SceneRuntime](SceneRuntime/SceneRuntime.md) - `SceneRuntime.h` diff --git a/docs/api/XCEngine/Scene/Scene/DeserializeFromString.md b/docs/api/XCEngine/Scene/Scene/DeserializeFromString.md index 21e565de..b302257a 100644 --- a/docs/api/XCEngine/Scene/Scene/DeserializeFromString.md +++ b/docs/api/XCEngine/Scene/Scene/DeserializeFromString.md @@ -13,27 +13,45 @@ void DeserializeFromString(const std::string& data); - `m_gameObjects` - `m_rootGameObjects` - `m_gameObjectIDs` -- 全局 registry 里属于旧场景的对象 +- 全局 registry 中属于旧场景的对象 -随后分两阶段重建： +需要注意的是，这个“清空旧场景”过程不会逐个调用 [DestroyGameObject](DestroyGameObject.md)，因此不会触发场景销毁事件，也不会为旧组件补发 `OnDestroy()`。 + +## 两阶段重建流程 + +当前实现按两阶段恢复： 1. 先解析所有对象块，收集 `id`、`uuid`、`name`、`tag`、`active`、`layer`、`parent`、`transform` 和组件 payload -2. 再创建全部 `GameObject`，恢复基础字段、组件和父子关系 +2. 再创建全部 `GameObject`，恢复字段、组件和父子关系 -## tag 与 layer 恢复语义 +恢复组件时，当前依赖 `ComponentFactoryRegistry` 通过组件名创建具体实例。 -- `tag` 会通过 `GameObject::SetTag()` 写回，因此空字符串会回退到 `"Untagged"` -- `layer` 在解析阶段会先限制到 `31`，再通过 `SetLayer()` 写回 +## Tag 与 Layer 恢复语义 -因此按当前实现，场景 round-trip 会保留正常的 tag/layer 语义。 +- `tag` 通过 `GameObject::SetTag()` 写回，因此空字符串会回退到 `"Untagged"` +- `layer` 在解析阶段先把文本数值限制到 `31`，然后再通过 `SetLayer()` 写回 + +因此按当前实现，场景 round-trip 会保留正确的 tag / layer 语义。 + +## 父子关系恢复语义 + +- `parent=INVALID_ID` 的对象会进入根列表 +- 如果某个对象声明了父 ID，但该父对象最终不存在，它也会回退为根对象 +- 父子挂接时调用的是 `SetParent(parent, false)`，因此恢复层级时不会要求保持世界变换 + +## ID 与 UUID 语义 + +- 文本里存在的 `id` 和 `uuid` 会被尽量保留 +- 解析结束后，`GameObject::s_nextID` 会推进到当前最大 ID 之后 + +这样可以避免反序列化后继续新建对象时出现 ID 冲突。 ## 当前实现限制 -- 旧对象清空时不会逐个调用 [DestroyGameObject](DestroyGameObject.md)，因此不会触发销毁事件，也不会对组件调用 `OnDestroy()` -- 新对象不会触发 [OnGameObjectCreated](OnGameObjectCreated.md)，也不会调用 `Awake()` / `Start()` -- 组件创建依赖 `ComponentFactoryRegistry` +- 不会触发 `OnGameObjectCreated` +- 不会调用 `Awake()` / `Start()` - 对损坏数字字段抛出的异常当前不会在这里捕获 -- 如果父对象 ID 缺失或找不到，对象会回退为根对象 +- 组件恢复成功与否依赖注册表和各组件自身反序列化逻辑 ## 参数 @@ -43,6 +61,10 @@ void DeserializeFromString(const std::string& data); - 无。 +## 设计提示 + +这条路径的目标是“尽可能忠实地把场景文本重建回内存状态”，而不是“模拟一次完整运行时创建流程”。这也是它不经过 `CreateGameObject()`、不补发 `Awake()` 的根本原因。 + ## 相关文档 - [Scene](Scene.md) diff --git a/docs/api/XCEngine/Scene/Scene/FindGameObjectWithTag.md b/docs/api/XCEngine/Scene/Scene/FindGameObjectWithTag.md index 40a1689c..33fddd15 100644 --- a/docs/api/XCEngine/Scene/Scene/FindGameObjectWithTag.md +++ b/docs/api/XCEngine/Scene/Scene/FindGameObjectWithTag.md @@ -1,6 +1,6 @@ # Scene::FindGameObjectWithTag -按 tag 递归查找场景中的第一个匹配对象。 +按 tag 递归查找当前场景中的第一个匹配对象。 ```cpp GameObject* FindGameObjectWithTag(const std::string& tag) const; @@ -14,7 +14,24 @@ GameObject* FindGameObjectWithTag(const std::string& tag) const; 2. 再递归检查子对象 3. 找到第一个匹配项后立即返回 -比较的是真实 tag 字段，不是对象名称。 +这里比较的是真实 tag 字段，不是对象名称，也不是全局 registry。 + +## 返回顺序语义 + +“第一个匹配对象”当前取决于两层顺序： + +- `m_rootGameObjects` 里的根对象顺序 +- 每个对象 `m_children` 的当前顺序 + +所以它表达的是“当前场景树遍历顺序下的第一个匹配对象”，而不是稳定的全局排序结果。 + +## 与静态查询的区别 + +和 [GameObject::FindGameObjectsWithTag](../../Components/GameObject/FindGameObjectsWithTag.md) 相比： + +- 这个接口只看当前 `Scene` +- 它返回单个“第一个匹配对象” +- 它按场景树顺序搜索，而不是按全局 registry 扫描 ## 参数 @@ -24,8 +41,13 @@ GameObject* FindGameObjectWithTag(const std::string& tag) const; - `GameObject*` - 第一个匹配对象；找不到时返回 `nullptr`。 +## 托管桥接说明 + +托管脚本通过 `GameObject.tag`、`Component.tag` 或 `CompareTag()` 修改的值，会直接写回同一份原生 `GameObject` 字段，因此本接口会立即观察到这些变化。 + ## 相关文档 - [Scene](Scene.md) - [Find](Find.md) - [GameObject::CompareTag](../../Components/GameObject/CompareTag.md) +- [GameObject::FindGameObjectsWithTag](../../Components/GameObject/FindGameObjectsWithTag.md) diff --git a/docs/api/XCEngine/Scene/Scene/Scene.md b/docs/api/XCEngine/Scene/Scene/Scene.md index d3dd9517..02e59ada 100644 --- a/docs/api/XCEngine/Scene/Scene/Scene.md +++ b/docs/api/XCEngine/Scene/Scene/Scene.md @@ -6,71 +6,162 @@ **头文件**: `XCEngine/Scene/Scene.h` -**描述**: 持有一组 `GameObject`、驱动场景级更新，并提供层级对象树保存/加载能力的场景容器。 +**描述**: 当前对象树的场景级容器，负责 `GameObject` 所有权、根节点入口、场景更新与完整树结构的保存/加载。 -## 概述 +## 设计定位 -`Scene` 是当前引擎里“对象集合”的所有权边界。它内部同时维护： +商业级游戏引擎通常不会让“对象本身”同时承担对象集合管理、生命周期入口和场景存档边界。`Scene` 在这里承担的就是这层容器职责： -- `m_gameObjects`，按 ID 保存 `GameObject` 的唯一所有权 -- `m_rootGameObjects`，保存根对象 ID 列表 -- `m_gameObjectIDs`，保存当前场景内的对象 ID 集合 -- 两个创建/销毁事件入口 +- 统一持有对象所有权 +- 提供根对象遍历入口 +- 驱动场景级 `Update / FixedUpdate / LateUpdate` +- 作为整棵对象树的序列化和反序列化边界 -`Scene` 负责对象集合、根节点入口、保存/加载边界和场景级更新；对象本身再负责组件与层级递归。 +这样拆分的好处是：`GameObject` 可以专注于对象自身与子树，`Scene` 则负责“这一整片运行时世界如何被管理和保存”。 -## 生命周期与所有权 +## 当前真实职责 -- [Constructor](Constructor.md) 创建空场景，默认 `m_active = true` -- [CreateGameObject](CreateGameObject.md) 分配、登记并唤醒一个新对象 -- [DestroyGameObject](DestroyGameObject.md) 从当前场景树中递归移除对象 -- [Destructor](Destructor.md) 当前直接清空内部 `unique_ptr` 容器 +`Scene` 内部当前维护四组关键状态： -查询接口返回的都是观察指针，不转移所有权。 +- `m_gameObjects` + - 以对象 ID 为键保存 `std::unique_ptr` + - 是场景内对象的唯一所有权容器 +- `m_rootGameObjects` + - 保存所有根对象的 ID + - 决定场景遍历和序列化的根入口顺序 +- `m_gameObjectIDs` + - 保存当前场景内对象 ID 集合 + - 用于快速判断成员关系 +- 事件入口 + - [OnGameObjectCreated](OnGameObjectCreated.md) + - [OnGameObjectDestroyed](OnGameObjectDestroyed.md) -## tag 查询与序列化边界 +这种“对象表 + 根列表”的拆法很典型，因为“按 ID 找对象”和“从根入口递归整棵树”是两种不同的使用需求。 -[FindGameObjectWithTag](FindGameObjectWithTag.md) 当前会： +## 创建与销毁路径 + +### CreateGameObject + +[CreateGameObject](CreateGameObject.md) 是当前标准运行时创建入口。它会完成： + +- 分配并持有新的 `GameObject` +- 把对象注册到全局 `GameObject::GetGlobalRegistry()` +- 写入当前场景指针 +- 挂到根节点列表或父对象之下 +- 立刻调用 `Awake()` +- 触发 `OnGameObjectCreated` + +这条路径产生的对象最符合“真实运行时场景对象”的语义。 + +### DestroyGameObject + +[DestroyGameObject](DestroyGameObject.md) 会： + +- 先递归销毁子对象 +- 再把对象从父节点子列表或根列表里移除 +- 触发 `OnGameObjectDestroyed` +- 调用对象的 `OnDestroy()` +- 从场景容器和全局 registry 中删除 + +事件与 `OnDestroy()` 的顺序很重要：当前实现是先发场景销毁事件，再让对象给普通组件分发 `OnDestroy()`。 + +### Destructor + +[Destructor](Destructor.md) 当前不会重放上述显式销毁链。它只会： + +- 从全局 registry 擦除属于本场景的对象 +- 清空内部 `unique_ptr` 容器 + +所以 `~Scene()` 不是“完整生命周期清理器”，而只是容器析构。 + +## 场景更新语义 + +[Update](Update.md)、[FixedUpdate](FixedUpdate.md)、[LateUpdate](LateUpdate.md) 当前都从根对象开始遍历。 + +按当前实现： + +- `Update()` 会先调用每个激活根对象的 `Start()`，再调用 `Update(deltaTime)` +- `FixedUpdate()` 与 `LateUpdate()` 也只会继续驱动 `IsActiveInHierarchy()` 为真的对象 +- `Scene::m_active` 当前不会作为这些接口的门控条件 + +因此更准确的理解方式是： + +- 对象级是否真正参与运行，看 `GameObject::IsActiveInHierarchy()` +- `Scene::IsActive()` 目前更像一个可保存的场景状态位，而不是运行时强门控 + +## Tag / Layer 与场景查询 + +[FindGameObjectWithTag](FindGameObjectWithTag.md) 当前已经是真正的 tag 查询： - 从根对象开始 - 对每个对象调用 `CompareTag(tag)` -- 以深度优先顺序返回第一个匹配对象 +- 按深度优先顺序返回第一个匹配项 -场景保存/加载同样已经覆盖 tag/layer： +场景保存与恢复也已经覆盖 tag / layer： -- [SerializeToString](SerializeToString.md) 会写出每个对象的 `tag` 与 `layer` -- [DeserializeFromString](DeserializeFromString.md) 会恢复这些字段 +- [SerializeToString](SerializeToString.md) 会写出每个对象的 `tag` 和 `layer` +- [DeserializeFromString](DeserializeFromString.md) 会通过 `SetTag()` / `SetLayer()` 恢复它们 -因此场景级 tag 查询、原生对象字段和托管 `GameObject.tag` / `layer` 当前共享同一份底层状态。 +这意味着场景级 tag 查询、原生 `GameObject` 字段，以及托管 `GameObject.tag` / `layer` 当前共享同一份底层状态。`tests/Scripting/test_mono_script_runtime.cpp` 中的 `GameObjectTagAndLayerApiExposeUnityStylePropertiesAndCompareTag` 就验证了脚本侧写回 tag 后，原生场景查询会立即看到结果。 -## 当前实现边界 +## 序列化与反序列化模型 -- `m_active` 当前不会参与更新门控；即使场景 inactive，[Update](Update.md) 系列接口仍会执行 -- [Destructor](Destructor.md) 不会触发 `OnGameObjectDestroyed()`，也不会为组件调用 `OnDestroy()` -- [DeserializeFromString](DeserializeFromString.md) 直接重建内部状态，不经过 [CreateGameObject](CreateGameObject.md)，因此不会触发创建事件或 `Awake()` -- [Save](Save.md) / [Load](Load.md) 打开文件失败时当前只做有限处理，不提供事务式恢复 -- [SetName](SetName.md) 只修改场景对象内部名称；如果场景由 `SceneManager` 管理，管理器 key 不会随之更新 +### SerializeToString -## 线程语义 +[SerializeToString](SerializeToString.md) 输出完整场景文本，包含： -- 当前没有锁 -- 默认应在主线程或外部同步前提下使用 +- 场景名与场景 active 位 +- 每个对象的 `id`、`uuid`、`name`、`tag`、`active`、`layer`、`parent`、`transform` +- 每个普通组件的 `component=;payload` + +对象按“根列表顺序 + 子树深度优先顺序”输出。 + +### DeserializeFromString + +[DeserializeFromString](DeserializeFromString.md) 采用两阶段重建： + +1. 先解析所有对象块与组件 payload +2. 再创建全部对象、恢复字段、挂组件、连接父子关系 + +这条路径当前不会经过 `CreateGameObject()`，因此不会自动触发： + +- `OnGameObjectCreated` +- `Awake()` +- `Start()` + +这是当前场景创建和场景加载之间最重要的行为差异之一。 + +## 当前实现限制 + +- `m_active` 当前不会阻止场景更新 +- 场景析构不会为所有对象补发显式销毁链 +- 反序列化不会触发创建事件，也不会补发 `Awake()` / `Start()` +- 组件恢复依赖 `ComponentFactoryRegistry` +- [Save](Save.md) / [Load](Load.md) 的错误处理目前比较轻，不提供事务式恢复 +- [SetName](SetName.md) 不会同步更新 `SceneManager` 里可能存在的管理 key + +## 推荐使用方式 + +1. 运行时对象创建优先使用 [CreateGameObject](CreateGameObject.md)。 +2. 需要当前场景内“第一个匹配对象”时，用 [FindGameObjectWithTag](FindGameObjectWithTag.md)；需要全局扫描时，再考虑 `GameObject::FindGameObjectsWithTag()`。 +3. 需要保存完整对象树时，使用 [SerializeToString](SerializeToString.md) / [DeserializeFromString](DeserializeFromString.md)。 +4. 从文本反序列化恢复后，如果某些系统依赖 `Awake()` 侧初始化，要显式设计补发或重建流程，不要假设引擎已经自动补齐。 ## 公开方法 | 方法 | 说明 | |------|------| | [Constructor](Constructor.md) | 构造空场景。 | -| [Destructor](Destructor.md) | 销毁场景。 | +| [Destructor](Destructor.md) | 销毁场景容器。 | | [GetName](GetName.md) | 查询场景名称。 | | [SetName](SetName.md) | 设置场景名称。 | | [IsActive](IsActive.md) | 查询场景 active 标志。 | | [SetActive](SetActive.md) | 设置场景 active 标志。 | -| [CreateGameObject](CreateGameObject.md) | 创建场景对象。 | -| [DestroyGameObject](DestroyGameObject.md) | 销毁场景对象。 | +| [CreateGameObject](CreateGameObject.md) | 创建场景对象并注册到场景。 | +| [DestroyGameObject](DestroyGameObject.md) | 从当前场景树中销毁对象。 | | [Find](Find.md) | 按名称查找对象。 | | [FindByID](FindByID.md) | 按 ID 查找对象。 | -| [FindGameObjectWithTag](FindGameObjectWithTag.md) | 按真实 tag 递归查找第一个匹配对象。 | +| [FindGameObjectWithTag](FindGameObjectWithTag.md) | 按真实 tag 深度优先查找第一个匹配对象。 | | [FindObjectOfType](FindObjectOfType.md) | 查找第一个匹配组件。 | | [FindObjectsOfType](FindObjectsOfType.md) | 查找所有匹配组件。 | | [GetRootGameObjects](GetRootGameObjects.md) | 获取根对象列表。 | @@ -79,8 +170,8 @@ | [LateUpdate](LateUpdate.md) | 驱动晚更新。 | | [Save](Save.md) | 保存到文件。 | | [Load](Load.md) | 从文件加载。 | -| [SerializeToString](SerializeToString.md) | 序列化为完整场景文本。 | -| [DeserializeFromString](DeserializeFromString.md) | 从完整场景文本反序列化。 | +| [SerializeToString](SerializeToString.md) | 序列化完整场景文本。 | +| [DeserializeFromString](DeserializeFromString.md) | 从完整场景文本重建场景。 | | [OnGameObjectCreated](OnGameObjectCreated.md) | 访问对象创建事件。 | | [OnGameObjectDestroyed](OnGameObjectDestroyed.md) | 访问对象销毁事件。 | diff --git a/docs/api/XCEngine/Scene/Scene/SerializeToString.md b/docs/api/XCEngine/Scene/Scene/SerializeToString.md index 4a398137..8b9247eb 100644 --- a/docs/api/XCEngine/Scene/Scene/SerializeToString.md +++ b/docs/api/XCEngine/Scene/Scene/SerializeToString.md @@ -8,12 +8,29 @@ std::string SerializeToString() const; ## 行为说明 -当前实现会输出： +当前实现输出的结构大致如下： -- 文件头 `# XCEngine Scene File` -- 场景级 `scene=...` -- 场景级 `active=...` -- 每个对象的 `gameobject_begin` / `gameobject_end` 块 +```text +# XCEngine Scene File +scene=... +active=... + +gameobject_begin +id=... +uuid=... +name=... +tag=... +active=... +layer=... +parent=... +transform=... +component=Type;payload +gameobject_end +``` + +之后会继续按深度优先顺序输出后续对象块。 + +## 当前会保存什么 每个对象块当前包含： @@ -27,9 +44,9 @@ std::string SerializeToString() const; - `transform` - 每个普通组件的 `component=;payload` -对象输出顺序是“当前根对象顺序 + 深度优先递归子树”。 +因此这已经是完整场景树级别的保存接口，而不只是单对象快照。 -## 字符串处理 +## 字符串转义 `name` 和 `tag` 当前会经过 `EscapeString()` 处理，转义： @@ -37,11 +54,30 @@ std::string SerializeToString() const; - 换行 - 回车 -这比 [GameObject::Serialize](../../Components/GameObject/Serialize.md) 的单对象紧凑 token 流更适合完整场景保存。 +这也是它比 [GameObject::Serialize](../../Components/GameObject/Serialize.md) 更适合作为完整场景文本格式的原因之一。 + +## 顺序语义 + +对象输出顺序是： + +- 当前 `m_rootGameObjects` 的顺序 +- 每个根对象之下的深度优先递归顺序 + +这有利于让场景文本和编辑器层级更接近，但它不是专门为稳定 diff 设计的版本化格式。 + +## 当前边界 + +- 组件 payload 的可恢复性依赖各组件自己的 `Serialize()` / `Deserialize()` +- 格式是引擎私有文本格式，不是通用交换协议 +- 当前没有显式 schema version，也没有事务式保存机制 ## 返回值 -- `std::string` - 序列化后的场景文本。 +- `std::string` - 序列化后的完整场景文本。 + +## 设计提示 + +把场景保存做成可读文本而不是直接二进制块，在商业引擎的早期阶段很常见：它便于调试、便于排查坏数据，也更方便逐步演进每个组件自己的 payload 结构。 ## 相关文档 diff --git a/docs/api/XCEngine/Scripting/IScriptRuntime/TryGetAvailableScriptClasses.md b/docs/api/XCEngine/Scripting/IScriptRuntime/TryGetAvailableScriptClasses.md index 9ca45fd7..3220a72a 100644 --- a/docs/api/XCEngine/Scripting/IScriptRuntime/TryGetAvailableScriptClasses.md +++ b/docs/api/XCEngine/Scripting/IScriptRuntime/TryGetAvailableScriptClasses.md @@ -22,9 +22,16 @@ virtual bool TryGetAvailableScriptClasses( - 返回 `true`：后端支持类发现，且当前返回的数据可用。 - 返回 `false`：后端未初始化、当前没有这项能力，或发现流程失败。 -调用前实现应清空 `outClasses`；`ScriptEngine::TryGetAvailableScriptClasses()` 会在此基础上继续过滤空类名并排序。 +## 契约要求 + +- 实现应在调用前清空 `outClasses`。 +- 返回的应该是“可绑定类”，而不是后端里任意可见类型；例如抽象类、工具类或不满足脚本基类约束的类型，通常不应暴露给调用方。 +- 描述里应尽量带上稳定的 `assemblyName`，因为上层会基于它做过滤和重绑定。 +- 接口本身不强制排序，但提供稳定顺序是推荐行为；`ScriptEngine::TryGetAvailableScriptClasses()` 会在此基础上继续过滤空类名并排序。 ## 相关文档 - [IScriptRuntime](IScriptRuntime.md) - [ScriptEngine::TryGetAvailableScriptClasses](../ScriptEngine/TryGetAvailableScriptClasses.md) +- [NullScriptRuntime::TryGetAvailableScriptClasses](../NullScriptRuntime/TryGetAvailableScriptClasses.md) +- [MonoScriptRuntime::TryGetAvailableScriptClasses](../Mono/MonoScriptRuntime/TryGetAvailableScriptClasses.md) diff --git a/docs/api/XCEngine/Scripting/Mono/Mono.md b/docs/api/XCEngine/Scripting/Mono/Mono.md index b1f9bf55..47824ab6 100644 --- a/docs/api/XCEngine/Scripting/Mono/Mono.md +++ b/docs/api/XCEngine/Scripting/Mono/Mono.md @@ -4,51 +4,102 @@ **类型**: `submodule` -**描述**: 收纳基于 Mono 的托管脚本运行时实现。 +**描述**: 收纳基于 Mono 的托管脚本运行时实现，以及当前脚本字段发现、默认值读取与运行时桥接的 Mono 后端文档。 ## 概览 -`docs/api/XCEngine/Scripting/Mono` 对应 `engine/include/XCEngine/Scripting/Mono` 子目录。它不是独立命名空间，而是脚本模块按后端实现拆出来的子目录。 +`docs/api/XCEngine/Scripting/Mono` 对应 `engine/include/XCEngine/Scripting/Mono`。它不是独立命名空间，而是脚本系统按运行时后端拆出的子目录。 -当前这里唯一的公开类型是 [MonoScriptRuntime](MonoScriptRuntime/MonoScriptRuntime.md)。它负责： +当前这里的核心公开类型是 [MonoScriptRuntime](MonoScriptRuntime/MonoScriptRuntime.md)。它负责： -- 初始化 Mono root domain 和 app domain。 -- 解析 `MonoScriptRuntime::Settings`，推导程序集目录、脚本核心程序集和游戏程序集路径。 -- 加载 `XCEngine.ScriptCore.dll` 与 `GameScripts.dll`。 -- 发现应用程序集中的非抽象 `MonoBehaviour` 子类，并缓存支持的公共实例字段与生命周期方法。 -- 为 `ScriptComponent` 创建托管实例，注入 `GameObject`/`ScriptComponent` 上下文，并在生命周期后同步字段。 +- 初始化 Mono root domain / app domain +- 加载 `XCEngine.ScriptCore.dll` 与 `GameScripts.dll` +- 发现应用程序集中的非抽象 `MonoBehaviour` 子类 +- 构建字段元数据与字段默认值查询能力 +- 创建脚本实例、注入上下文并调用生命周期 +- 通过 internal call 把 `Debug`、`Time`、`Input`、`GameObject`、`Transform` 等托管 API 接回原生实现 -## 为什么单独分目录 +## 字段发现模型 -把 Mono 运行时放进独立子目录，而不是直接塞进 `Scripting` 根目录，有两个直接好处： +这一轮最重要的语义更新，是当前 Mono 后端已经不再等同于“只发现 public 实例字段”。 -- 可以清楚区分“脚本系统公共契约”和“具体后端实现”。 -- 以后如果接入别的脚本后端，这里天然就是平行扩展点。 +当前真实规则是： -## 程序集来源 +- 先排除： + - `static` + - `const / literal` + - `readonly / init-only` +- 然后接受： + - `public` 实例字段 + - 或者标了 `[SerializeField]` 的 `private` 实例字段 +- 最后再按当前支持的字段类型过滤 -当前 Mono 后端既支持测试程序集目录，也支持项目资产脚本程序集目录： +这意味着： -- `managed/CMakeLists.txt` 会构建基础 `XCEngine.ScriptCore.dll` 与 `GameScripts.dll`。 -- 同一份 CMake 还会把 `project/Assets/**/*.cs` 编译到 `project/Library/ScriptAssemblies/GameScripts.dll`。 -- `tests/scripting/test_project_script_assembly.cpp` 已验证运行时能从项目程序集目录发现 `ProjectScripts.ProjectScriptProbe` 及其默认字段值。 +- `FieldMetadataProbe.Health` / `Speed` / `Label` 这类 `public` 字段会被发现 +- `FieldMetadataProbe.HiddenFlag` 这种 `[SerializeField] private` 字段也会被发现 +- `IgnoredPrivateCounter` 这类未标注的 `private` 字段仍然会被忽略 +- `SharedCounter` 这类 `static` 字段会被忽略 +- `UnsupportedRotation` 这类当前不支持的类型也会被忽略 + +## 为什么要支持 `[SerializeField] private` + +这是一个很典型的 Unity 风格设计，但它的价值不只是“和 Unity 看齐”。更重要的是它解决了工程里的两个真实矛盾： + +- 你希望字段能被序列化、能被 Inspector 或场景存储驱动 +- 但你又不希望把这个字段暴露成脚本类的公开 API + +支持 `[SerializeField] private` 的好处包括： + +- 保留封装边界，不必为了可持久化而把内部状态全部改成 `public` +- 更适合后续重构，减少脚本 API 面被外部任意依赖 +- 和商业引擎用户的认知模型一致，降低脚本作者迁移成本 + +而继续忽略“未标注的 private 字段”，则能防止把纯运行时内部状态意外持久化。 + +## 为什么要排除 `readonly` + +当前字段同步模型要求： + +- 运行前可以把 `ScriptFieldStorage` 里的覆盖值写回托管实例 +- 运行后可以把托管实例里的值同步回本地存储 + +`readonly` 字段不适合承担这类双向同步职责，因此当前实现把 `init-only` 直接排除。这是一个偏工程安全的取舍。 + +## 程序集事实来源 + +当前 Mono 后端的类发现和字段发现，依赖的是“编译后的程序集事实”，而不是直接扫描 `.cs` 源文件目录： + +- `XCEngine.ScriptCore.dll` 提供托管基类和属性 +- `GameScripts.dll` 提供应用层脚本类 + +这和商业引擎常见的做法一致：Inspector 列表、字段元数据、默认值读取和真正实例化，都应该基于同一份已编译产物。 + +## 测试锚点 + +当前行为直接受到以下测试约束： + +- `ClassFieldMetadataListsSupportedPublicInstanceFields` +- `ClassFieldDefaultValueQueryReturnsSerializeFieldPrivateInitializers` +- `SerializeFieldPrivateFieldsApplyStoredValuesAndPersistAcrossSceneRoundTrip` +- `test_project_script_assembly.cpp` 里的项目程序集发现与默认值读取用例 ## 当前实现边界 -- 当前只实现了 Mono 后端，没有并列的 IL2CPP、Lua 或自研 VM 后端。 -- 目录里只有一个 public header，说明当前重点仍然是把一条 Mono 托管链路跑通。 -- 类发现只扫描当前应用程序集里的非抽象 `MonoBehaviour` 子类，不会把工具类或抽象基类暴露给脚本绑定 UI。 -- 字段发现只接受受支持类型的 `public` 非 `static` 实例字段。 -- internal call 目前已覆盖 `GameObject`、`Transform`、`Camera`、`Light`、`MeshFilter`、`MeshRenderer`、日志和时间桥接，但远不是完整编辑器级脚本 API 面。 +- 当前只有 Mono 后端，没有并列的 IL2CPP / Lua / 自研 VM 后端。 +- 字段发现只扫描应用程序集里的非抽象 `MonoBehaviour` 子类。 +- `[SerializeField] private` 已支持，但“未标注 private”“`readonly`”“不支持类型”仍然不会进入字段模型。 +- 项目脚本能否被发现，取决于它是否成功进入 `GameScripts.dll`，而不是取决于源文件是否存在于目录里。 ## 头文件 -- [MonoScriptRuntime](MonoScriptRuntime/MonoScriptRuntime.md) - `MonoScriptRuntime.h` +- [MonoScriptRuntime](MonoScriptRuntime/MonoScriptRuntime.md) ## 相关指南 - [Scripting Runtime And Field Model](../../../_guides/Scripting/Scripting-Runtime-And-Field-Model.md) - [Project Script Assembly And Field Sync](../../../_guides/Scripting/Project-Script-Assembly-And-Field-Sync.md) +- [Game View Runtime Input Bridge](../../../_guides/Editor/Game-View-Runtime-Input-Bridge.md) ## 相关文档 diff --git a/docs/api/XCEngine/Scripting/Mono/MonoScriptRuntime/DestroyManagedObject.md b/docs/api/XCEngine/Scripting/Mono/MonoScriptRuntime/DestroyManagedObject.md index 364886c1..b558ad7a 100644 --- a/docs/api/XCEngine/Scripting/Mono/MonoScriptRuntime/DestroyManagedObject.md +++ b/docs/api/XCEngine/Scripting/Mono/MonoScriptRuntime/DestroyManagedObject.md @@ -72,7 +72,7 @@ InternalCall_Object_Destroy ## 测试锚点 -`tests/scripting/test_mono_script_runtime.cpp` 中的 +`tests/Scripting/test_mono_script_runtime.cpp` 中的 - `UnityObjectApiSupportsHierarchyLookupAndDestroy` diff --git a/docs/api/XCEngine/Scripting/Mono/MonoScriptRuntime/MonoScriptRuntime.md b/docs/api/XCEngine/Scripting/Mono/MonoScriptRuntime/MonoScriptRuntime.md index a1c7eb44..37078951 100644 --- a/docs/api/XCEngine/Scripting/Mono/MonoScriptRuntime/MonoScriptRuntime.md +++ b/docs/api/XCEngine/Scripting/Mono/MonoScriptRuntime/MonoScriptRuntime.md @@ -6,156 +6,205 @@ **头文件**: `XCEngine/Scripting/Mono/MonoScriptRuntime.h` -**描述**: 基于 Mono 的脚本运行时实现，负责程序集解析与加载、类发现、实例创建、字段桥接、默认值读取和生命周期调用。 +**描述**: 当前唯一的托管脚本运行时后端，实现程序集加载、脚本类发现、字段元数据/默认值查询、实例创建、字段同步和生命周期调用。 ## 概览 -`MonoScriptRuntime` 是当前唯一的真实托管脚本后端。它把 `ScriptEngine` 提供的抽象调用翻译成 Mono 世界里的具体动作： +`MonoScriptRuntime` 是 `IScriptRuntime` 的当前唯一实现。它把 `ScriptEngine` 需要的抽象操作落到 Mono 世界中： -- 初始化 root domain 和 app domain。 -- 加载脚本核心程序集与游戏程序集。 -- 发现继承 `MonoBehaviour` 的可用脚本类，并缓存生命周期方法与字段元数据。 -- 读取类字段默认值。 -- 创建和销毁脚本实例。 -- 通过 internal call 让托管脚本访问原生 `GameObject`、`Transform`、`Camera`、`Light`、`MeshFilter`、`MeshRenderer`、`tag` / `layer` 元数据、日志、输入与时间能力，并把 `Object.Destroy(...)` 这类托管销毁请求回落到原生对象或组件销毁逻辑。 -- 把本地字段覆盖写入托管实例，并在生命周期之后同步回 `ScriptFieldStorage`。 +- 初始化和关闭 Mono 运行时上下文 +- 加载核心程序集与应用程序集 +- 发现可绑定脚本类 +- 缓存字段元数据和生命周期方法 +- 创建/销毁托管实例 +- 读写托管字段 +- 把托管 API 通过 internal call 接回原生系统 -它的设计取向和商业引擎常见方案一致：先把脚本编译成程序集，再以程序集元数据作为类发现、默认值读取和真正实例化的共同事实来源。 +这层分工的关键价值，在于让 `ScriptEngine` 负责“什么时候调度”，让 `MonoScriptRuntime` 负责“如何在 Mono 里执行”。这样后续即使更换后端，场景生命周期和字段同步模型也仍然可以保持一致。 ## Settings -构造函数接收一个 `Settings` 结构体，当前公开字段如下： +构造函数接收一个 `Settings` 结构体。当前重要字段如下： | 字段 | 说明 | |------|------| -| `assemblyDirectory` | 程序集目录；若 `coreAssemblyPath` / `appAssemblyPath` 缺失，会以它为基准推导 DLL 路径。 | -| `corlibDirectory` | Mono 解析 `mscorlib.dll` 的目录；为空时会回退到 `assemblyDirectory` 或 `coreAssemblyPath` 所在目录。 | -| `coreAssemblyPath` | `XCEngine.ScriptCore.dll` 的完整路径。 | -| `appAssemblyPath` | `GameScripts.dll` 的完整路径。 | -| `coreAssemblyName` | 脚本核心程序集名，默认 `XCEngine.ScriptCore`。 | +| `assemblyDirectory` | 程序集目录；若显式路径为空，会以它推导 DLL 路径。 | +| `corlibDirectory` | Mono 查找 `mscorlib.dll` 的目录。 | +| `coreAssemblyPath` | `XCEngine.ScriptCore.dll` 的路径。 | +| `appAssemblyPath` | `GameScripts.dll` 的路径。 | +| `coreAssemblyName` | 核心程序集名，默认 `XCEngine.ScriptCore`。 | | `appAssemblyName` | 应用程序集名，默认 `GameScripts`。 | -| `baseNamespace` | 核心托管 API 的命名空间，默认 `XCEngine`。 | -| `baseClassName` | 作为脚本基类查找入口的类型名，默认 `MonoBehaviour`。 | +| `baseNamespace` | 托管基础 API 命名空间，默认 `XCEngine`。 | +| `baseClassName` | 作为脚本基类入口的类型名，默认 `MonoBehaviour`。 | -`ResolveSettings()` 会在构造时和 `Initialize()` 前再次运行，补全目录和程序集路径。因此只提供 `assemblyDirectory` 也是合法用法；`tests/scripting/test_project_script_assembly.cpp` 就是基于项目脚本程序集目录这样初始化的。 +`ResolveSettings()` 会补全这些路径，因此当前既可以显式指定 DLL，也可以只指定程序集目录。 ## 程序集与类发现模型 -当前 `MonoScriptRuntime` 的类发现有两个关键边界： +当前脚本类发现遵循两个核心边界： -- 只加载两份程序集: - - `XCEngine.ScriptCore.dll` - - `GameScripts.dll` -- 只把应用程序集，也就是 `m_appImage` 这一侧的非抽象 `MonoBehaviour` 子类纳入可绑定脚本类缓存。 +- 只从 `m_appImage`，也就是应用程序集这一侧发现可绑定脚本类 +- 只接受非抽象的 `MonoBehaviour` 子类 这意味着： -- `ScriptCore` 负责基础 API 和托管基类，不负责向 Inspector 暴露可绑定游戏脚本。 -- 项目脚本是否可绑定，不取决于源码目录本身，而取决于它最终有没有进入 `GameScripts.dll`，以及它是不是非抽象 `MonoBehaviour` 子类。 -- `GetScriptClassNames()` 和 `TryGetAvailableScriptClasses()` 都只是读取这份已发现缓存，不会在查询时临时再做一遍程序集扫描。 +- `XCEngine.ScriptCore` 负责基础 API，不直接成为可绑定游戏脚本来源 +- `GameScripts.dll` 才是当前脚本类列表、字段元数据和默认值读取的共同事实来源 -## internal call 桥接语义 +## 字段发现规则 -当前 internal call 已经形成一套相对完整的脚本运行桥： +字段发现发生在 `DiscoverScriptClassesInImage(...)` 阶段。当前真实筛选顺序是： + +1. 排除 `static` +2. 排除 `literal / const` +3. 排除 `init-only / readonly` +4. 接受 `public` 字段，或者带 `[SerializeField]` 的 `private` 字段 +5. 再由 `BuildFieldMetadata(...)` 检查字段类型是否受支持 + +这让当前字段模型和 Unity 风格更加接近：既支持公开字段，也支持“保持封装但允许序列化”的 `[SerializeField] private` 字段。 + +## 当前支持的字段类型 + +`BuildFieldMetadata(...)` 当前支持以下字段类型： + +- `float` +- `double` +- `bool` +- `int32` +- `uint64` +- `string` +- `enum` + - 当前以 `ScriptFieldType::Int32` 暴露 + - 仅支持基础类型为 `I1 / U1 / I2 / U2 / I4 / U4` 的枚举 +- `Vector2` +- `Vector3` +- `Vector4` +- `GameObject` +- 具体组件引用 + - `Transform` + - `Camera` + - `Light` + - `MeshFilter` + - `MeshRenderer` + - 具体脚本组件类型 + +以下类型当前不会进入字段模型： + +- 未标注的 `private` 字段 +- `readonly` 字段 +- `Quaternion` +- `Component` / `MonoBehaviour` 这类过于宽泛的基类引用 +- 数组、列表、泛型容器等当前未桥接类型 +- 64 位底层枚举等未列入支持范围的枚举底层类型 + +## `TryGetClassFieldMetadata()` 与 `TryGetClassFieldDefaultValues()` + +[TryGetClassFieldMetadata](TryGetClassFieldMetadata.md) 和 [TryGetClassFieldDefaultValues](TryGetClassFieldDefaultValues.md) 都只操作“已经通过上述规则进入字段缓存”的字段集合。 + +其中默认值查询当前会： + +1. 切到 app domain +2. 临时创建一个托管对象 +3. 执行默认构造和字段初始化 +4. 逐个读取字段值 + +因此它返回的是“真实 C# 初始化后”的默认值，而不是单纯的 CLR 零值。 + +这也是为什么测试里可以直接读到： + +- `FieldMetadataProbe.State == 2` +- `FieldMetadataProbe.HiddenFlag == true` +- `ProjectScriptProbe.Label == "ProjectScriptProbe"` + +## 实例创建与字段同步 + +当前实例与字段同步模型是： + +- [CreateScriptInstance](CreateScriptInstance.md) + - 根据 `ScriptComponent` 找类 + - 创建托管对象 + - 注入 `gameObjectUUID` / `scriptComponentUUID` + - 把 `ScriptFieldStorage` 里的同名且类型匹配字段写回托管实例 +- [SyncManagedFieldsToStorage](SyncManagedFieldsToStorage.md) + - 把运行中的托管字段同步回本地存储 + +这一模型和商业引擎的常见做法一致：类默认值提供初始模板，场景存储提供覆盖值，运行时再在同一字段集合上做双向同步。 + +## 为什么支持 `[SerializeField] private` + +这是当前设计里非常关键的一点。支持它不是为了“多兼容一个语法糖”，而是为了兼顾两件事： + +- 脚本作者需要字段能进入序列化和 Inspector 体系 +- 但不希望因此把类的外部 API 全部暴露为 `public` + +这带来的直接好处是： + +- 封装边界更清晰 +- Inspector / 场景序列化体验更接近 Unity +- 重构字段访问级别时更安全 + +而继续忽略“未标注的 private 字段”，则能避免把纯内部实现状态误持久化。 + +## internal call 桥接 + +当前 internal call 已经接通一套相对完整的托管 API： -- `Time.deltaTime` - - 来自 `InvokeMethod()` 在生命周期调用前写入的当前 delta。 -- `Time.fixedDeltaTime` - - 直接读取 `ScriptEngine::GetRuntimeFixedDeltaTime()`。 -- `Input` - - 直接转发到原生 [InputManager](../../../Input/InputManager/InputManager.md) 的当前状态。 - - `GetKeyUp()` 当前对应释放边沿语义。 - - `anyKey` / `anyKeyDown` 会把鼠标按钮也计入。 - `Debug.Log*` - - 直接写入原生日志系统。 -- `GameObject.tag` / `GameObject.layer` / `GameObject.CompareTag()` - - 分别落到 `InternalCall_GameObject_GetTag / SetTag / CompareTag / GetLayer / SetLayer` - - `managed/XCEngine.ScriptCore/GameObject.cs` 同时提供 `Tag` / `tag`、`Layer` / `layer` 两组 Unity 风格属性别名 - - `managed/XCEngine.ScriptCore/Component.cs` 再把这些属性直接转发到宿主 `GameObject` - - tag setter 会把 `null` 先归一成空字符串，再由 native `SetTag("")` 回退到 `"Untagged"` - - layer setter 会在 native internal call 中显式 clamp 到 `[0, 31]` - +- `Time` +- `Input` +- `GameObject` +- `Transform` +- `Camera` +- `Light` +- `MeshFilter` +- `MeshRenderer` - `Object.Destroy(...)` - - 会走 `InternalCall_Object_Destroy -> MonoScriptRuntime::DestroyManagedObject(...)` - - 当前支持销毁活动运行时场景里的 `GameObject`，以及由托管包装对象映射到的 `Camera`、`Light`、`MeshFilter`、`MeshRenderer` 与脚本组件 - - `Transform` 包装对象不会被当作可移除组件销毁 -这意味着托管脚本看到的 `Input` / `Time` / `tag` / `layer` 都不是独立副本，而是直接共享原生运行时当前状态。`tests/scripting/test_mono_script_runtime.cpp` 里 `GameObjectTagAndLayerApiExposeUnityStylePropertiesAndCompareTag` 也明确验证了： +这些托管 API 当前并不是各自维护一套独立状态，而是直接桥接回原生系统。 -- 托管脚本能先读到原生侧已有的 tag/layer -- 托管脚本写回后的 `"Player"` / `31` 会真实更新 native `GameObject` -- 原生 `Scene::FindGameObjectWithTag("Player")` 会立刻看到这次更新 +## 测试锚点 -脚本端如果想正确理解边沿输入、fixed step 配置和对象元数据桥接，应同时对照 [Input Flow And Frame Semantics](../../../../_guides/Input/Input-Flow-and-Frame-Semantics.md) 与 [ScriptEngine](../../ScriptEngine/ScriptEngine.md)。 +当前行为直接受到以下测试约束： -## 实例与字段同步 - -`MonoScriptRuntime` 当前把“创建实例”和“字段同步”拆成两步： - -- `CreateScriptInstance()` - - 先根据 `ScriptComponent` 绑定解析类元数据。 - - 创建托管对象并执行构造。 - - 注入 `gameObjectUUID` / `scriptComponentUUID`。 - - 再把 `ScriptFieldStorage` 中同名且类型匹配的字段写入托管实例。 -- `SyncManagedFieldsToStorage()` - - 只遍历本地已经存在的字段名。 - - 只在类元数据仍存在且类型匹配时回写。 - -这种策略比“看到字段就自动持久化”更保守，但更像工程级引擎的做法：场景层和运行时层边界更清楚，不容易被临时字段污染。 - -## 生命周期 - -- 构造时接收一份 `Settings`，并做路径补全。 -- [Initialize](Initialize.md) 会完成完整 Mono 初始化流程。 -- [OnRuntimeStart](OnRuntimeStart.md) 会清空活动场景 / `deltaTime` 共享状态，并在初始化成功后接入当前场景。 -- [OnRuntimeStop](OnRuntimeStop.md) 会清理活动场景与实例缓存，但不会做完整 `Shutdown()`。 -- [Shutdown](Shutdown.md) 会销毁 app domain、清空类缓存与实例缓存。 -- 析构会自动调用 `Shutdown()`。 - -## 设计要点 - -- `ScriptEngine` 不直接碰 Mono API；所有后端细节收敛在这个类里。 -- 类缓存和实例缓存都基于稳定键，便于场景重建、类切换和实例回绑。 -- `TryGetClassFieldDefaultValues()` 会创建一个临时托管对象并读取字段值，因此脚本字段默认值可以反映 C# 初始化表达式，而不只是原生零值。 -- `CreateScriptInstance()` 会先注入上下文 UUID，再把本地存储里同名且类型匹配的字段写入托管实例。 -- `SyncManagedFieldsToStorage()` 只回写本地已有字段，保证运行时不会把临时字段偷偷持久化到场景。 +- `ClassFieldMetadataListsSupportedPublicInstanceFields` +- `ClassFieldDefaultValueQueryReturnsSerializeFieldPrivateInitializers` +- `SerializeFieldPrivateFieldsApplyStoredValuesAndPersistAcrossSceneRoundTrip` +- `test_project_script_assembly.cpp` 中的项目程序集发现与默认值读取用例 ## 当前实现边界 -- 当前只发现应用程序集中的非抽象 `MonoBehaviour` 子类。 -- 支持的公共字段类型只覆盖 `float / double / bool / int32 / uint64 / string / Vector2 / Vector3 / Vector4 / GameObject`。 -- `TryGetAvailableScriptClasses()`、`GetScriptClassNames()` 和字段元数据查询都要求运行时已经初始化完成。 -- `SyncManagedFieldsToStorage()` 只会回写已经存在于 `ScriptFieldStorage` 中且类型仍匹配的字段；运行时临时字段不会自动持久化。 -- `OnRuntimeStop()` 只清理当前活动场景与实例，不会做完整 `Shutdown()`；程序集和类缓存会保留到显式 `Shutdown()` 或析构。 -- 目前没有程序集热重载、增量编译监听或多场景并发运行支持。 +- 当前只发现应用程序集里的非抽象 `MonoBehaviour` 子类。 +- `[SerializeField] private` 已纳入字段模型，但“未标注 private”依旧被忽略。 +- 默认值查询依赖真实托管对象实例化，因此类缺失、实例构造失败或字段读取失败都会让整次查询失败。 +- 当前没有程序集热重载、增量刷新或调试器集成。 ## 公开方法 | 方法 | 说明 | |------|------| -| [Constructor](Constructor.md) | 创建 Mono 运行时对象并解析设置。 | +| [Constructor](Constructor.md) | 创建运行时对象并解析设置。 | | [Destructor](Destructor.md) | 析构时执行 `Shutdown()`。 | | [Initialize](Initialize.md) | 初始化 Mono 域并发现脚本类。 | | [Shutdown](Shutdown.md) | 关闭当前 Mono 运行时。 | | [GetLastError](GetLastError.md) | 读取最近一次错误描述。 | | [IsClassAvailable](IsClassAvailable.md) | 查询脚本类是否已发现。 | -| [GetScriptClassNames](GetScriptClassNames.md) | 返回已发现脚本类名列表。 | -| `IsInitialized()` | 判断运行时是否已完成初始化。 | -| `GetSettings()` | 返回已解析的运行时设置。 | -| [TryGetAvailableScriptClasses](TryGetAvailableScriptClasses.md) | 返回完整脚本类描述列表。 | -| [TryGetClassFieldMetadata](TryGetClassFieldMetadata.md) | 读取脚本类字段元数据。 | -| [TryGetClassFieldDefaultValues](TryGetClassFieldDefaultValues.md) | 读取脚本类字段默认值。 | -| [HasManagedInstance](HasManagedInstance.md) | 判断某脚本组件是否已有托管实例。 | +| [GetScriptClassNames](GetScriptClassNames.md) | 返回已发现脚本类全名列表。 | +| `IsInitialized()` | 判断运行时是否完成初始化。 | +| `GetSettings()` | 返回已解析的设置。 | +| [TryGetAvailableScriptClasses](TryGetAvailableScriptClasses.md) | 返回脚本类描述列表。 | +| [TryGetClassFieldMetadata](TryGetClassFieldMetadata.md) | 返回当前字段模型中的字段元数据。 | +| [TryGetClassFieldDefaultValues](TryGetClassFieldDefaultValues.md) | 返回当前字段模型中的真实默认值。 | +| [HasManagedInstance](HasManagedInstance.md) | 判断脚本组件是否已有托管实例。 | | [GetManagedInstanceCount](GetManagedInstanceCount.md) | 返回当前托管实例数。 | -| [GetManagedInstanceObject](GetManagedInstanceObject.md) | 读取托管对象裸指针。 | +| [GetManagedInstanceObject](GetManagedInstanceObject.md) | 获取托管对象裸指针。 | | [CreateManagedComponentWrapper](CreateManagedComponentWrapper.md) | 为原生组件创建托管包装对象。 | -| [DestroyManagedObject](DestroyManagedObject.md) | 根据托管包装对象销毁对应的原生 `GameObject` 或组件。 | +| [DestroyManagedObject](DestroyManagedObject.md) | 销毁托管对象映射到的原生对象或组件。 | | [TryGetFieldValue](TryGetFieldValue.md) | 直接读取托管实例字段。 | -| [OnRuntimeStart](OnRuntimeStart.md) | 启动脚本运行时上下文。 | -| [OnRuntimeStop](OnRuntimeStop.md) | 停止当前运行场景的托管上下文。 | -| [TrySetManagedFieldValue](TrySetManagedFieldValue.md) | 写托管字段。 | -| [TryGetManagedFieldValue](TryGetManagedFieldValue.md) | 读托管字段。 | -| [SyncManagedFieldsToStorage](SyncManagedFieldsToStorage.md) | 回写本地字段缓存。 | +| [OnRuntimeStart](OnRuntimeStart.md) | 启动当前场景的托管上下文。 | +| [OnRuntimeStop](OnRuntimeStop.md) | 停止当前场景的托管上下文。 | +| [TrySetManagedFieldValue](TrySetManagedFieldValue.md) | 向托管实例写字段。 | +| [TryGetManagedFieldValue](TryGetManagedFieldValue.md) | 从托管实例读字段。 | +| [SyncManagedFieldsToStorage](SyncManagedFieldsToStorage.md) | 把托管字段同步回存储。 | | [CreateScriptInstance](CreateScriptInstance.md) | 创建脚本实例。 | | [DestroyScriptInstance](DestroyScriptInstance.md) | 销毁脚本实例。 | | [InvokeMethod](InvokeMethod.md) | 调用生命周期方法。 | @@ -163,10 +212,11 @@ ## 真实行为依据 - `engine/src/Scripting/Mono/MonoScriptRuntime.cpp` -- `managed/XCEngine.ScriptCore/Input.cs` -- `managed/XCEngine.ScriptCore/Time.cs` -- `tests/scripting/test_mono_script_runtime.cpp` -- `tests/scripting/test_project_script_assembly.cpp` +- `managed/XCEngine.ScriptCore/SerializeField.cs` +- `managed/GameScripts/FieldMetadataProbe.cs` +- `managed/GameScripts/SerializeFieldProbe.cs` +- `tests/Scripting/test_mono_script_runtime.cpp` +- `tests/Scripting/test_project_script_assembly.cpp` ## 相关文档 diff --git a/docs/api/XCEngine/Scripting/Mono/MonoScriptRuntime/TryGetAvailableScriptClasses.md b/docs/api/XCEngine/Scripting/Mono/MonoScriptRuntime/TryGetAvailableScriptClasses.md index d3adbbdf..a51da189 100644 --- a/docs/api/XCEngine/Scripting/Mono/MonoScriptRuntime/TryGetAvailableScriptClasses.md +++ b/docs/api/XCEngine/Scripting/Mono/MonoScriptRuntime/TryGetAvailableScriptClasses.md @@ -39,8 +39,8 @@ bool TryGetAvailableScriptClasses( ## 真实行为依据 - `engine/src/Scripting/Mono/MonoScriptRuntime.cpp` -- `tests/scripting/test_mono_script_runtime.cpp` -- `tests/scripting/test_project_script_assembly.cpp` +- `tests/Scripting/test_mono_script_runtime.cpp` +- `tests/Scripting/test_project_script_assembly.cpp` ## 相关文档 diff --git a/docs/api/XCEngine/Scripting/Mono/MonoScriptRuntime/TryGetClassFieldDefaultValues.md b/docs/api/XCEngine/Scripting/Mono/MonoScriptRuntime/TryGetClassFieldDefaultValues.md index 6f6e92c5..fb5cb26e 100644 --- a/docs/api/XCEngine/Scripting/Mono/MonoScriptRuntime/TryGetClassFieldDefaultValues.md +++ b/docs/api/XCEngine/Scripting/Mono/MonoScriptRuntime/TryGetClassFieldDefaultValues.md @@ -16,33 +16,79 @@ bool TryGetClassFieldDefaultValues( std::vector& outFields) const override; ``` +## 作用 + +返回指定脚本类当前字段模型中各字段的真实默认值。 + +这里的“默认值”不是简单的语言零值，而是 C# 字段初始化和默认构造执行后的结果。 + ## 当前实现流程 1. 清空 `outFields`。 -2. 用 `(assemblyName, namespaceName, className)` 查找缓存的类元数据。 +2. 查找类缓存；找不到则返回 `false`。 3. 切换到当前 app domain。 -4. 创建一个临时托管对象并执行默认构造。 -5. 遍历缓存字段，逐个读取字段值并写入 `ScriptFieldDefaultValue`。 -6. 按 `fieldName` 排序后返回。 +4. 创建一个临时托管对象。 +5. 执行默认初始化。 +6. 遍历字段缓存，逐个读取字段值并填充 `ScriptFieldDefaultValue`。 +7. 按 `fieldName` 排序后返回。 -## 为什么它重要 +如果任何一步失败，当前实现会清空输出并返回 `false`。 -这里返回的是托管类真实初始化后的字段值，所以它能反映： +## 它读取的是哪一批字段 + +这个方法不会自行重新筛字段，而是复用 [TryGetClassFieldMetadata](TryGetClassFieldMetadata.md) 所对应的同一批字段集合。 + +因此它同样支持： + +- `public` 实例字段 +- `[SerializeField] private` 字段 + +并同样排除： + +- `static` +- `const / literal` +- `readonly / init-only` +- 未标注的 `private` +- 不支持的字段类型 + +## 为什么它比“零值表”更有意义 + +因为它真的构造了一个托管对象，所以能反映： - C# 字段初始化表达式 -- 默认构造后留下的初始状态 +- 枚举默认值 +- `string.Empty` +- 布尔或数值的自定义初始值 -`ScriptEngine::TryGetScriptFieldModel()` 和 `ClearScriptFieldOverrides()` 都依赖这条数据。 +例如当前测试直接验证了： -## 失败路径 +- `FieldMetadataProbe.State` 的默认值是 `2` +- `FieldMetadataProbe.HiddenFlag` 的默认值是 `true` +- `ProjectScriptProbe.Label` 的默认值是 `"ProjectScriptProbe"` +- `ProjectScriptProbe.Speed` 的默认值是 `2.5f` -- 类找不到 -- Mono 无法创建临时对象 -- 任意字段读取失败 +这也是商业引擎里常见的设计：Inspector 默认值和运行时实例的首帧初值，都应来自同一份真实脚本初始化结果。 -这些情况都会返回 `false`，并清空输出。 +## `[SerializeField] private` 的默认值也会被读到 + +这一点很重要。既然 `[SerializeField] private` 已经进入字段模型，它的默认值也应和 `public` 字段一样被查询到。 + +当前测试 +`ClassFieldDefaultValueQueryReturnsSerializeFieldPrivateInitializers` +已经明确验证：`FieldMetadataProbe.HiddenFlag` 会以 `true` 返回。 + +## 返回值语义 + +- `true` + - 类存在，且全部字段默认值都成功读取。 +- `false` + - 类不存在、临时对象创建失败，或任意字段读取失败。 + +失败时 `outFields` 会被清空，调用方不应读取旧内容。 ## 相关文档 +- [MonoScriptRuntime](MonoScriptRuntime.md) - [TryGetClassFieldMetadata](TryGetClassFieldMetadata.md) - [Project Script Assembly And Field Sync](../../../../_guides/Scripting/Project-Script-Assembly-And-Field-Sync.md) +- [Scripting Runtime And Field Model](../../../../_guides/Scripting/Scripting-Runtime-And-Field-Model.md) diff --git a/docs/api/XCEngine/Scripting/Mono/MonoScriptRuntime/TryGetClassFieldMetadata.md b/docs/api/XCEngine/Scripting/Mono/MonoScriptRuntime/TryGetClassFieldMetadata.md index a13c73c2..24bc7013 100644 --- a/docs/api/XCEngine/Scripting/Mono/MonoScriptRuntime/TryGetClassFieldMetadata.md +++ b/docs/api/XCEngine/Scripting/Mono/MonoScriptRuntime/TryGetClassFieldMetadata.md @@ -16,21 +16,83 @@ bool TryGetClassFieldMetadata( std::vector& outFields) const override; ``` +## 作用 + +返回指定脚本类当前“可进入字段模型”的字段元数据列表。 + +这里返回的不是类里声明的全部字段，而是经过 Mono 运行时筛选后的字段集合。 + ## 当前实现行为 -- 先查找类缓存。 -- 找不到返回 `false` 并清空输出。 -- 找到后把缓存中的字段元数据复制到 `outFields`。 -- 最终按字段名排序。 +1. 先清空 `outFields`。 +2. 用 `(assemblyName, namespaceName, className)` 查缓存里的类元数据。 +3. 如果类不存在，返回 `false`，并保持 `outFields` 为空。 +4. 如果类存在： + - 遍历 `metadata->fields` + - 复制成 `ScriptFieldMetadata{name, type}` + - 最终按字段名排序后返回 `true` -## 字段来源边界 +因此，这个方法本身不再扫描程序集；它只读取初始化阶段已经构建好的类缓存。 -当前只会收录： +## 字段筛选规则 -- 公共实例字段 -- 非静态字段 -- 可映射到当前支持脚本字段类型的字段 +字段集合来源于 `DiscoverScriptClassesInImage(...)` 的筛选结果。当前真实规则是： + +- 排除 `static` +- 排除 `const / literal` +- 排除 `readonly / init-only` +- 接受： + - `public` 实例字段 + - 或带 `[SerializeField]` 的 `private` 实例字段 +- 再要求字段类型属于当前支持集合 + +这意味着“private”本身不是问题，问题在于它有没有显式进入序列化/字段模型。 + +## 典型例子 + +`managed/GameScripts/FieldMetadataProbe.cs` 当前很好地展示了这些边界： + +- 会被发现： + - `Health` + - `Speed` + - `Label` + - `SpawnPoint` + - `State` + - `Target` + - `HiddenFlag` +- 不会被发现： + - `SharedCounter` + - `IgnoredPrivateCounter` + - `UnsupportedRotation` + +其中 `HiddenFlag` 能被发现，正是因为它是 `[SerializeField] private bool`。 + +## 为什么这很重要 + +这条规则直接决定了： + +- Inspector / 字段编辑 UI 能看到哪些字段 +- 场景序列化允许存哪些字段 +- 运行时字段默认值和字段同步覆盖哪些字段 + +如果一个字段没进入这里，它后续也不会出现在 [TryGetClassFieldDefaultValues](TryGetClassFieldDefaultValues.md) 或字段同步链里。 + +## 返回值语义 + +- `true` + - 类存在；即使类存在但筛完没有可用字段，也仍然可能返回 `true` 且 `outFields` 为空。 +- `false` + - 类不存在，无法找到对应类元数据。 + +## 测试锚点 + +`tests/Scripting/test_mono_script_runtime.cpp` 里的 +`ClassFieldMetadataListsSupportedPublicInstanceFields` +已经明确验证：`HiddenFlag` 会进入字段元数据，而未标注 private 字段不会。 ## 相关文档 +- [MonoScriptRuntime](MonoScriptRuntime.md) +- [TryGetClassFieldDefaultValues](TryGetClassFieldDefaultValues.md) - [IScriptRuntime::TryGetClassFieldMetadata](../../IScriptRuntime/TryGetClassFieldMetadata.md) +- [Scripting Runtime And Field Model](../../../../_guides/Scripting/Scripting-Runtime-And-Field-Model.md) diff --git a/docs/api/XCEngine/Scripting/ScriptComponent/ClearScriptClass.md b/docs/api/XCEngine/Scripting/ScriptComponent/ClearScriptClass.md index cae95108..5bb3733e 100644 --- a/docs/api/XCEngine/Scripting/ScriptComponent/ClearScriptClass.md +++ b/docs/api/XCEngine/Scripting/ScriptComponent/ClearScriptClass.md @@ -20,12 +20,34 @@ void ClearScriptClass(); - 内部等价于调用 `SetScriptClass(m_assemblyName, "", "")`。 - 当前 `assemblyName` 会被保留。 +- `namespaceName` 和 `className` 会被清空，因此 `HasScriptClass()` 立刻变成 `false`。 - 如果运行时正在运行且该组件原本已有脚本类，`ScriptEngine` 会收到类变化通知，并销毁旧跟踪实例。 +当前这条链路的实际停机顺序仍然是： + +1. `OnDisable` +2. `OnDestroy` +3. `DestroyScriptInstance` + +但因为组件字段会先被清空再通知引擎，所以停机过程中如果原生侧读取 `GetFullClassName()`，当前看到的是空字符串。 + ## 设计含义 “清空绑定”不是单纯改两个字符串。对运行时来说，它意味着这个组件不再有可执行脚本类，应该停止继续调度生命周期。 +同时还要注意两点： + +- `ClearScriptClass()` 不会重置 `assemblyName`。 +- `ClearScriptClass()` 不会删除 [ScriptFieldStorage](../ScriptFieldStorage/ScriptFieldStorage.md) 里的本地字段覆盖值。 + +这让脚本槽位可以被清空，但组件上的历史配置数据仍然保留在原生场景层里，便于后续重绑或调试。 + +## 真实行为依据 + +- `engine/src/Scripting/ScriptComponent.cpp` +- `engine/src/Scripting/ScriptEngine.cpp` +- `tests/Scripting/test_script_engine.cpp` + ## 相关文档 - [SetScriptClass](SetScriptClass.md) diff --git a/docs/api/XCEngine/Scripting/ScriptComponent/ScriptComponent.md b/docs/api/XCEngine/Scripting/ScriptComponent/ScriptComponent.md index 85c4169b..2632346a 100644 --- a/docs/api/XCEngine/Scripting/ScriptComponent/ScriptComponent.md +++ b/docs/api/XCEngine/Scripting/ScriptComponent/ScriptComponent.md @@ -14,30 +14,62 @@ - 这个组件绑定的是哪个程序集、命名空间和类。 - 这个脚本组件自己的稳定 UUID。 -- 这份脚本实例的可持久化字段缓存 `ScriptFieldStorage`。 +- 这份脚本实例的可持久化字段缓存 [ScriptFieldStorage](../ScriptFieldStorage/ScriptFieldStorage.md)。 -这和 Unity 场景里挂着的 `MonoBehaviour` 槽位很接近，但当前实现更明确地区分了“原生数据层”和“运行时实例层”。 +这和 Unity 场景里“脚本槽位”的定位很接近，但当前实现更明确地区分了： -## 生命周期 +- 原生场景数据 +- 运行时活体实例 + +也正因为如此，`ScriptComponent` 既可以在 Mono 未初始化时参与序列化和 Inspector 编辑，又可以在运行时作为 `ScriptEngine` 的实例描述对象。 + +## 生命周期与绑定语义 - 构造时会生成一个非零随机 `scriptComponentUUID`。 - 默认程序集名是 `GameScripts`。 -- 首次绑定脚本类时，会通知 `ScriptEngine::OnScriptComponentEnabled()`。 +- 首次从“无脚本类”切到“有脚本类”时，会通知 `ScriptEngine::OnScriptComponentEnabled()`。 - 已绑定脚本类发生变化时，会通知 `ScriptEngine::OnScriptComponentClassChanged()`，触发当前运行时实例停机并按新类重建。 - `ClearScriptClass()` 会保留当前 `assemblyName`，只清空命名空间和类名。 - 启用、禁用、销毁回调会直接转发给 `ScriptEngine`。 -- 序列化/反序列化会持久化 UUID、脚本类绑定和字段存储内容。 +- 序列化 / 反序列化会持久化 UUID、脚本类绑定和字段存储内容。 + +这里有两个容易误判的实现细节： + +- `HasScriptClass()` 当前只检查 `className` 是否非空。 +- `SetScriptClass()` / `ClearScriptClass()` 是会触发运行时链路的高层 API，而 `SetAssemblyName()` / `SetNamespaceName()` / `SetClassName()` 只是裸字段写入。 + +如果你只是改三个字符串，运行时并不会自动知道“类绑定已经变了”。 + +## 为什么它不是“托管实例本身” + +很多脚本系统文档都会把“脚本组件”和“脚本实例”混着讲，但当前实现刻意没这么做。原因很现实： + +- 场景资产在未运行时也要保存脚本绑定和字段覆盖值。 +- 反序列化或拷贝场景对象时，不应该强依赖托管运行时已经启动。 +- 编辑器大量操作只想读写字段和类名，不想立即创建 Mono 对象。 + +因此 `ScriptComponent` 更像“脚本实例描述与持久化容器”，而不是托管对象本体。 + +## 字段存储语义 + +`ScriptFieldStorage` 是 `ScriptComponent` 的内嵌成员，不单独分配。它承担的是“本地持久化覆盖值”这一层语义。 + +当前需要特别注意： + +- `ClearScriptClass()` 不会清空字段存储；只是清空类绑定。 +- `SetFieldStorage()` 是整体覆盖本地缓存，不会自动把当前活体托管实例同步成完全相同的状态。 +- 运行时字段回写也是经由 `ScriptEngine -> IScriptRuntime::SyncManagedFieldsToStorage()` 完成，而不是 `ScriptComponent` 自己主动驱动。 ## 所有权 -- `ScriptComponent` 本身归 `GameObject` 所有。 +- `ScriptComponent` 本身由 `GameObject` 所有。 - `ScriptFieldStorage` 作为成员对象直接内嵌，不单独分配。 ## 当前实现边界 - 只有 `SetScriptClass()` / `ClearScriptClass()` 会通知 `ScriptEngine`；`SetAssemblyName()`、`SetNamespaceName()`、`SetClassName()` 是纯字段写入，不会自动触发重绑定。 -- 反序列化使用引擎私有的分号分隔文本格式，不是通用 JSON/YAML。 -- `SetFieldStorage()` 直接整体覆盖本地字段缓存，不会自动把活体托管实例同步到同一状态。 +- 反序列化使用引擎私有的分号分隔文本格式，不是通用 JSON / YAML。 +- `ClearScriptClass()` 清空的是命名空间和类名，不会重置程序集名，也不会删除字段缓存。 ## 常用访问器 @@ -66,9 +98,10 @@ ## 真实行为依据 +- `engine/include/XCEngine/Scripting/ScriptComponent.h` - `engine/src/Scripting/ScriptComponent.cpp` -- `tests/scripting/test_script_component.cpp` -- `tests/scripting/test_script_engine.cpp` +- `tests/Scripting/test_script_component.cpp` +- `tests/Scripting/test_script_engine.cpp` ## 相关文档 diff --git a/docs/api/XCEngine/Scripting/ScriptComponent/SetScriptClass.md b/docs/api/XCEngine/Scripting/ScriptComponent/SetScriptClass.md index b90eda92..22e4f3a7 100644 --- a/docs/api/XCEngine/Scripting/ScriptComponent/SetScriptClass.md +++ b/docs/api/XCEngine/Scripting/ScriptComponent/SetScriptClass.md @@ -23,18 +23,49 @@ void SetScriptClass( 设置当前脚本组件绑定的托管类信息。 +## 重载差异 + +- `SetScriptClass(namespaceName, className)` + - 只修改命名空间和类名。 + - 保留当前 `assemblyName`，默认场景下一般就是 `GameScripts`。 +- `SetScriptClass(assemblyName, namespaceName, className)` + - 同时修改程序集名、命名空间和类名。 + ## 当前实现行为 -- 两个重载都会先记录“之前是否已经有脚本类”。 -- 然后覆盖程序集名、命名空间和类名。 -- 如果“之前没有脚本类，设置后有脚本类”，会调用 `ScriptEngine::Get().OnScriptComponentEnabled(this)`。 -- 如果之前已经绑定脚本类，并且程序集名 / 命名空间 / 类名发生变化，会调用 `ScriptEngine::Get().OnScriptComponentClassChanged(this)`。 +两个重载都遵循同一套顺序： + +1. 记录调用前是否已有脚本类绑定。 +2. 计算绑定字符串是否真的发生变化。 +3. 先把新的程序集名 / 命名空间 / 类名写入 `ScriptComponent`。 +4. 如果“之前没有脚本类，设置后有脚本类”，调用 `ScriptEngine::Get().OnScriptComponentEnabled(this)`。 +5. 如果之前已经绑定脚本类，并且绑定字符串发生变化，调用 `ScriptEngine::Get().OnScriptComponentClassChanged(this)`。 + +## 关键语义 + +- “首次绑定”走的是 `OnScriptComponentEnabled()` 路径，不是 `OnScriptComponentClassChanged()`。 +- “已绑定后改类”走的是显式重绑定路径。 +- 如果新值和旧值完全相同，当前不会重复通知 `ScriptEngine`。 +- 因为新字符串是先写入再通知引擎，所以运行时收到类切换通知时，`ScriptComponent` 身上已经是新绑定。 + +最后这一点很重要。它意味着： + +- 旧托管实例的停机确实会发生。 +- 但如果停机过程里有原生侧日志或调试代码读取 `component->GetFullClassName()`，读到的会是新类名，而不是旧类名。 ## 设计含义 - 当前实现把“首次绑定脚本类”视作启用事件。 -- 已绑定类发生变化时，`ScriptEngine` 会停掉旧实例并按新类重新跟踪，这已经是当前实现的一部分。 -- 但 `SetAssemblyName()` / `SetNamespaceName()` / `SetClassName()` 这些原始 setter 不会触发同样的流程；需要真正重绑定时应走 `SetScriptClass()`。 +- 已绑定类发生变化时，`ScriptEngine` 会停掉旧实例并按新类重新跟踪，这正是运行时重绑定的 canonical 入口。 +- `SetAssemblyName()` / `SetNamespaceName()` / `SetClassName()` 这些原始 setter 不会触发同样的流程；需要真正重绑定时应走 `SetScriptClass()`。 + +这和商业引擎里常见的“改 Inspector 脚本槽位 = 触发一次受控重绑定”是同一种设计取向。 + +## 真实行为依据 + +- `engine/src/Scripting/ScriptComponent.cpp` +- `engine/src/Scripting/ScriptEngine.cpp` +- `tests/Scripting/test_script_engine.cpp` ## 相关文档 diff --git a/docs/api/XCEngine/Scripting/ScriptEngine/DefaultFixedDeltaTime.md b/docs/api/XCEngine/Scripting/ScriptEngine/DefaultFixedDeltaTime.md new file mode 100644 index 00000000..358b461d --- /dev/null +++ b/docs/api/XCEngine/Scripting/ScriptEngine/DefaultFixedDeltaTime.md @@ -0,0 +1,41 @@ +# ScriptEngine::DefaultFixedDeltaTime + +**命名空间**: `XCEngine::Scripting` + +**类型**: `constant` + +**头文件**: `XCEngine/Scripting/ScriptEngine.h` + +## 定义 + +```cpp +static constexpr float DefaultFixedDeltaTime = 1.0f / 50.0f; +``` + +## 当前语义 + +这是 `ScriptEngine` 的默认运行时固定步长配置，当前值等于 `0.02f`，也就是 `50 Hz`。 + +它会在以下场景被使用： + +- `ScriptEngine` 初始构造时，`m_runtimeFixedDeltaTime` 用它初始化 +- [SetRuntimeFixedDeltaTime](SetRuntimeFixedDeltaTime.md) 传入非正值时回退到该值 +- [OnRuntimeStop](OnRuntimeStop.md) 清理运行态后把当前配置重置为该值 + +## 设计含义 + +它不是 `SceneRuntime` 的强制固定帧率控制器，而是 `ScriptEngine` 暴露给原生和托管脚本的“默认 fixed delta 配置值”。 + +当前具体某次 fixed tick 仍由上层调用 [OnFixedUpdate](OnFixedUpdate.md) 时传入的参数决定。 + +这和商业引擎里的固定步长设置很像：它更接近“推荐配置值”或“当前运行态默认值”，而不是单独一个能自动驱动物理循环的时钟。 + +## 托管侧可见性 + +当运行时没有显式配置过新的 fixed delta，托管 `Time.fixedDeltaTime` 最终读到的也是这份默认值。 + +## 相关文档 + +- [SetRuntimeFixedDeltaTime](SetRuntimeFixedDeltaTime.md) +- [GetRuntimeFixedDeltaTime](GetRuntimeFixedDeltaTime.md) +- [OnRuntimeStop](OnRuntimeStop.md) diff --git a/docs/api/XCEngine/Scripting/ScriptEngine/GetRuntimeFixedDeltaTime.md b/docs/api/XCEngine/Scripting/ScriptEngine/GetRuntimeFixedDeltaTime.md new file mode 100644 index 00000000..efd89236 --- /dev/null +++ b/docs/api/XCEngine/Scripting/ScriptEngine/GetRuntimeFixedDeltaTime.md @@ -0,0 +1,56 @@ +# ScriptEngine::GetRuntimeFixedDeltaTime + +**命名空间**: `XCEngine::Scripting` + +**类型**: `method` + +**头文件**: `XCEngine/Scripting/ScriptEngine.h` + +## 签名 + +```cpp +float GetRuntimeFixedDeltaTime() const; +``` + +## 当前语义 + +返回 `ScriptEngine` 当前持有的运行时固定步长配置值，也就是 `m_runtimeFixedDeltaTime`。 + +它的来源当前只有两类： + +- [SetRuntimeFixedDeltaTime](SetRuntimeFixedDeltaTime.md) 写入的正值 +- 默认回退值 [DefaultFixedDeltaTime](DefaultFixedDeltaTime.md) + +## 生命周期行为 + +- 启动前如果已配置非默认值，[OnRuntimeStart](OnRuntimeStart.md) 会在内部 stop/start 之间保留这份配置。 +- [OnRuntimeStop](OnRuntimeStop.md) 结束后，该值会重置为 [DefaultFixedDeltaTime](DefaultFixedDeltaTime.md)。 +- 调用 [SetRuntimeFixedDeltaTime](SetRuntimeFixedDeltaTime.md) 并传入非正值，也会立刻回到默认值。 + +## 与 `OnFixedUpdate()` 的区别 + +这个 getter 返回的是“配置的固定步长”，不是“某次具体 fixed tick 传进来的参数”。 + +当前 [OnFixedUpdate](OnFixedUpdate.md) 仍使用调用方显式传入的 `fixedDeltaTime` 参数驱动脚本生命周期；如果上层把两者配置成不同值，脚本回调收到的 delta 与这里返回的配置值就可能出现偏差。 + +## 托管侧可见性 + +Mono 运行时的 `Time.fixedDeltaTime` 当前就是通过内部调用直接读取这个 getter，因此它也是托管脚本看到的固定步长配置值。 + +这也是为什么测试里会同时区分： + +- `FixedUpdate()` 里通过 `Time.deltaTime` 观察到的本次 fixed tick delta +- 以及通过 `Time.fixedDeltaTime` 观察到的当前配置值 + +## 真实行为依据 + +- `engine/src/Scripting/ScriptEngine.cpp` +- `engine/src/Scripting/Mono/MonoScriptRuntime.cpp` +- `managed/XCEngine.ScriptCore/Time.cs` +- `tests/Scripting/test_mono_script_runtime.cpp` + +## 相关文档 + +- [SetRuntimeFixedDeltaTime](SetRuntimeFixedDeltaTime.md) +- [DefaultFixedDeltaTime](DefaultFixedDeltaTime.md) +- [OnFixedUpdate](OnFixedUpdate.md) diff --git a/docs/api/XCEngine/Scripting/ScriptEngine/OnFixedUpdate.md b/docs/api/XCEngine/Scripting/ScriptEngine/OnFixedUpdate.md index 30604c03..ecb7f544 100644 --- a/docs/api/XCEngine/Scripting/ScriptEngine/OnFixedUpdate.md +++ b/docs/api/XCEngine/Scripting/ScriptEngine/OnFixedUpdate.md @@ -16,16 +16,42 @@ void OnFixedUpdate(float fixedDeltaTime); - 只在 `m_runtimeRunning` 为真时继续执行。 - 复制当前脚本顺序表，按顺序遍历。 +- 本次回调真正传给脚本生命周期的是调用方传入的 `fixedDeltaTime` 参数。 - 对每个脚本要求同时满足： - `ShouldScriptRun(state)` - `EnsureScriptReady(state, true)` - `state.enabled == true` - 满足后调用运行时 `FixedUpdate` 生命周期。 +- 每次生命周期调用后，`InvokeLifecycleMethod()` 还会立即触发 `SyncManagedFieldsToStorage()`。 + +## 关键语义 + +- `EnsureScriptReady(state, true)` 不只是空检查；如果实例还不存在，它会创建实例，并补发 `Awake / OnEnable`。 +- 因此某个脚本第一次真正进入 fixed step 调度前，可能会先完成实例创建和启用流程。 +- `Start` 不在这里触发；它仍然会留到第一次 [OnUpdate](OnUpdate.md) 前补发。 ## 设计意义 复制顺序表再遍历，可以避免遍历过程中容器被增删时直接打乱当前帧顺序。 +需要注意的是，[GetRuntimeFixedDeltaTime](GetRuntimeFixedDeltaTime.md) 返回的是另一条“运行时固定步长配置值”通道。当前 `OnFixedUpdate()` 并不会主动读取该配置并覆盖自己的参数，所以时间系统调用方应自行保证两者一致。 + +## 托管侧可见性 + +- 当前 fixed tick 传给托管 `Time.deltaTime` 的，是这里的 `fixedDeltaTime` 实参。 +- 托管 `Time.fixedDeltaTime` 读到的，则是 [GetRuntimeFixedDeltaTime](GetRuntimeFixedDeltaTime.md) 返回的配置值。 + +如果上层把两者配成不同值，脚本在同一轮 fixed update 里就可能同时读到两份不一致的时间数据。 + +## 真实行为依据 + +- `engine/src/Scripting/ScriptEngine.cpp` +- `engine/src/Scripting/Mono/MonoScriptRuntime.cpp` +- `managed/XCEngine.ScriptCore/Time.cs` +- `tests/Scripting/test_mono_script_runtime.cpp` + ## 相关文档 +- [SetRuntimeFixedDeltaTime](SetRuntimeFixedDeltaTime.md) +- [GetRuntimeFixedDeltaTime](GetRuntimeFixedDeltaTime.md) - [OnUpdate](OnUpdate.md) diff --git a/docs/api/XCEngine/Scripting/ScriptEngine/OnRuntimeStart.md b/docs/api/XCEngine/Scripting/ScriptEngine/OnRuntimeStart.md index b817b263..5eb6fe55 100644 --- a/docs/api/XCEngine/Scripting/ScriptEngine/OnRuntimeStart.md +++ b/docs/api/XCEngine/Scripting/ScriptEngine/OnRuntimeStart.md @@ -16,20 +16,41 @@ void OnRuntimeStart(Components::Scene* scene); 按 `engine/src/Scripting/ScriptEngine.cpp`： -1. 先调用 `OnRuntimeStop()` 清理旧运行时。 -2. 如果 `scene == nullptr`，直接返回。 -3. 记录 `m_runtimeScene`，置 `m_runtimeRunning = true`。 -4. 调用当前运行时 `m_runtime->OnRuntimeStart(scene)`。 -5. 订阅 `scene->OnGameObjectCreated()`，保证运行中创建的新对象也会被脚本系统追踪。 -6. 递归收集场景现有的所有 `ScriptComponent`。 -7. 对满足 `ShouldScriptRun()` 的组件调用 `EnsureScriptReady(..., true)`，从而创建实例并触发 `Awake / OnEnable`。 +1. 先暂存当前 `m_runtimeFixedDeltaTime` 配置值。 +2. 调用 [OnRuntimeStop](OnRuntimeStop.md) 清理旧运行时。 +3. 把暂存的 fixed delta 配置恢复回 `m_runtimeFixedDeltaTime`。 +4. 如果 `scene == nullptr`，直接返回。 +5. 记录 `m_runtimeScene`，置 `m_runtimeRunning = true`。 +6. 调用当前运行时 `m_runtime->OnRuntimeStart(scene)`。 +7. 订阅 `scene->OnGameObjectCreated()`，保证运行中创建的新对象也会被脚本系统追踪。 +8. 递归收集场景现有的所有 `ScriptComponent`。 +9. 对满足 `ShouldScriptRun()` 的组件调用 `EnsureScriptReady(..., true)`，从而创建实例并触发 `Awake / OnEnable`。 -## 设计重点 +## 关键语义 -- 这一步不会直接触发 `Start`；`Start` 留到第一次 `OnUpdate()` 再补发。 +- 这一步不会直接触发 `Start`；`Start` 留到第一次 [OnUpdate](OnUpdate.md) 再补发。 +- 启动前通过 [SetRuntimeFixedDeltaTime](SetRuntimeFixedDeltaTime.md) 配好的 fixed delta，不会被这次内部 [OnRuntimeStop](OnRuntimeStop.md) 清掉。 - 订阅场景创建事件，保证 runtime-spawn 出来的对象不会漏掉脚本初始化。 +- 这里只会对当前已经满足运行条件的脚本调用 `EnsureScriptReady()`；未激活对象、禁用组件或未绑定类的组件不会在这里被强行创建实例。 + +## 为什么要先 stop 再 start + +这种写法看上去有点“重”，但它解决的是工程上一致性问题： + +- 避免旧场景残留跟踪状态带进新运行态。 +- 保证 fixed delta、场景订阅和实例缓存都回到干净起点。 +- 让“重新开始运行”与“第一次开始运行”共享同一条启动路径。 + +这和商业引擎里 Play 模式切换常见的“全量重建运行时态”思路一致。 + +## 真实行为依据 + +- `engine/src/Scripting/ScriptEngine.cpp` +- `tests/Scene/test_scene_runtime.cpp` +- `tests/Scripting/test_script_engine.cpp` ## 相关文档 +- [SetRuntimeFixedDeltaTime](SetRuntimeFixedDeltaTime.md) - [OnRuntimeStop](OnRuntimeStop.md) - [OnUpdate](OnUpdate.md) diff --git a/docs/api/XCEngine/Scripting/ScriptEngine/OnRuntimeStop.md b/docs/api/XCEngine/Scripting/ScriptEngine/OnRuntimeStop.md index c7a7908c..4ff16219 100644 --- a/docs/api/XCEngine/Scripting/ScriptEngine/OnRuntimeStop.md +++ b/docs/api/XCEngine/Scripting/ScriptEngine/OnRuntimeStop.md @@ -18,19 +18,40 @@ void OnRuntimeStop(); - 若当前并未运行： - 清空 `m_runtimeScene` - 清空跟踪状态和顺序表 + - 把 `m_runtimeFixedDeltaTime` 重置为 [DefaultFixedDeltaTime](DefaultFixedDeltaTime.md) - 返回 - 若正在运行： - 遍历所有跟踪脚本，调用 `StopTrackingScript(..., true)` - 清空状态表与顺序表 - 把 `m_runtimeRunning` 置为 `false` - 清空 `m_runtimeScene` + - 把 `m_runtimeFixedDeltaTime` 重置为 [DefaultFixedDeltaTime](DefaultFixedDeltaTime.md) - 最后调用 `m_runtime->OnRuntimeStop(stoppedScene)` ## 当前真实语义 `StopTrackingScript()` 会在实例存在时按 `OnDisable -> OnDestroy -> DestroyScriptInstance` 清理，因此这不是简单停更，而是完整结束脚本运行态。 +此外，这一步也会把当前运行时固定步长配置恢复成默认值；如果下一次启动仍想使用非默认 fixed delta，需要在启动前重新调用 [SetRuntimeFixedDeltaTime](SetRuntimeFixedDeltaTime.md)。 + +## 关键语义 + +- 即使当前 `m_runtimeRunning == false`，这个方法也仍然会清空 `m_runtimeScene`、跟踪表和 fixed delta 配置。它不只是“停止已运行中的脚本”，也是“把脚本运行时状态整体收回默认值”的统一入口。 +- 只有在原本确实处于运行态时，才会调用底层运行时 `m_runtime->OnRuntimeStop(stoppedScene)`。 +- 场景创建事件的退订发生在最前面，避免停机过程中再被新对象创建事件打断。 + +## 设计意义 + +把“实例停机”“状态表清空”“fixed delta 恢复默认值”“通知具体运行时停机”统一收口到一个出口，可以减少 Play 模式切换和场景重启时的残留状态。 + +## 真实行为依据 + +- `engine/src/Scripting/ScriptEngine.cpp` +- `tests/Scripting/test_script_engine.cpp` + ## 相关文档 +- [DefaultFixedDeltaTime](DefaultFixedDeltaTime.md) +- [SetRuntimeFixedDeltaTime](SetRuntimeFixedDeltaTime.md) - [OnRuntimeStart](OnRuntimeStart.md) - [OnScriptComponentDestroyed](OnScriptComponentDestroyed.md) diff --git a/docs/api/XCEngine/Scripting/ScriptEngine/OnScriptComponentClassChanged.md b/docs/api/XCEngine/Scripting/ScriptEngine/OnScriptComponentClassChanged.md index 8158a967..8fa49315 100644 --- a/docs/api/XCEngine/Scripting/ScriptEngine/OnScriptComponentClassChanged.md +++ b/docs/api/XCEngine/Scripting/ScriptEngine/OnScriptComponentClassChanged.md @@ -24,13 +24,36 @@ void OnScriptComponentClassChanged(ScriptComponent* component); - 如有实例，会触发 `OnDisable -> OnDestroy -> DestroyScriptInstance` - 然后从跟踪表移除 4. 如果组件已经没有脚本类，流程结束。 -5. 否则按新类重新 `TrackScriptComponent()`。 +5. 否则按当前组件上的新绑定重新 `TrackScriptComponent()`。 6. 若新状态满足 `ShouldScriptRun()`，立即 `EnsureScriptReady(..., true)`，从而创建新实例并触发 `Awake / OnEnable`。 +## 关键语义 + +- `ScriptComponent::SetScriptClass()` / `ClearScriptClass()` 是先写入组件上的新绑定，再调用这里。因此这个方法执行时，`component` 身上已经是“新类名”或“清空后的类名”。 +- 这意味着“停掉旧实例”和“读取组件当前绑定字符串”是两件不同的事: + - 停掉的是旧托管实例 + - 但如果此时有人通过 `component->GetFullClassName()` 看组件数据，看到的会是新绑定或空绑定 +- 如果清空绑定，方法会只执行停机和移除跟踪，不会重新创建状态。 +- 如果新绑定仍存在，但运行时后续无法创建新实例，这个方法不会回滚组件上的新绑定；组件会保留新类信息，只是当前没有活体实例。 + ## 使用场景 `ScriptComponent::SetScriptClass()` 在已绑定类发生变化时会调用这里；`ClearScriptClass()` 也会走同一条停机路径。 +## 设计意义 + +商业引擎里脚本类切换通常都不是“裸改字段”，而是“显式重绑定动作”。当前实现把这条链路收口到 `ScriptEngine`，好处是： + +- 生命周期停机顺序固定。 +- 跟踪表和实例缓存不会漏清。 +- 后续即便更换脚本后端，类切换的上层语义也能保持一致。 + +## 真实行为依据 + +- `engine/src/Scripting/ScriptEngine.cpp` +- `engine/src/Scripting/ScriptComponent.cpp` +- `tests/Scripting/test_script_engine.cpp` + ## 相关文档 - [OnScriptComponentEnabled](OnScriptComponentEnabled.md) diff --git a/docs/api/XCEngine/Scripting/ScriptEngine/ScriptEngine.md b/docs/api/XCEngine/Scripting/ScriptEngine/ScriptEngine.md index 7d87ed50..9300e536 100644 --- a/docs/api/XCEngine/Scripting/ScriptEngine/ScriptEngine.md +++ b/docs/api/XCEngine/Scripting/ScriptEngine/ScriptEngine.md @@ -10,29 +10,56 @@ ## 概览 -`ScriptEngine` 是当前脚本模块里最重要的原生协调者。它自己不执行脚本字节码，也不保存场景数据，而是负责把下面几层真正串起来： +`ScriptEngine` 是当前脚本模块里最重要的原生协调者。它自己不执行脚本字节码，也不保存场景资产，而是把下面几层真正串起来： -- `SceneRuntime` 提供“场景开始运行/停止运行/每帧更新”的入口。 +- `SceneRuntime` 提供“场景开始运行 / 停止运行 / 每帧更新”的入口。 - `ScriptComponent` 提供脚本绑定与字段缓存。 - `IScriptRuntime` 提供具体脚本后端能力。 +这也是商业引擎里最常见的做法之一：生命周期顺序和场景级追踪必须掌握在原生调度器手里，不能散落在各个后端实现里，否则脚本后端一换，Play 模式语义就会漂。 + 当前它的核心职责包括： - 在运行时开始时收集场景中的脚本组件并建立追踪表。 - 订阅 `Scene::OnGameObjectCreated()`，把运行中创建的新对象也纳入脚本追踪。 +- 保存运行时固定步长配置，并把它暴露给托管时间查询接口。 - 根据对象激活状态、组件启用状态和脚本类绑定状态决定脚本是否应当运行。 -- 按顺序创建实例、调用 `Awake / OnEnable / Start / Update...`。 +- 按顺序创建实例、调用 `Awake / OnEnable / Start / FixedUpdate / Update / LateUpdate`。 - 在运行时字段、本地字段缓存、类元数据和类默认值之间建立一致的读取模型。 -- 为编辑器/Inspector 提供脚本类列表、字段模型、批量写入和清除覆盖能力。 +- 为编辑器 / Inspector 提供脚本类列表、字段模型、批量写入和清除覆盖能力。 -## 生命周期 +## 生命周期主控 - [Get](Get.md) 返回进程级单例。 - 默认运行时是内部持有的 `NullScriptRuntime`。 - [SetRuntime](SetRuntime.md) 可替换具体后端；传 `nullptr` 时回退到空运行时。 -- [OnRuntimeStart](OnRuntimeStart.md) / [OnRuntimeStop](OnRuntimeStop.md) 管理整条脚本运行链路。 +- [OnRuntimeStart](OnRuntimeStart.md) 启动整条脚本运行链路。 +- [OnRuntimeStop](OnRuntimeStop.md) 停止运行、销毁活体实例并清理跟踪表。 -## 内部追踪模型 +`OnRuntimeStart()` 的当前流程有两个很重要的实现细节： + +- 它会先暂存当前 fixed delta 配置，再内部调用一次 `OnRuntimeStop()` 清旧状态，然后把配置写回去。 +- 它会在通知运行时启动后，再递归收集场景中的脚本组件，并订阅 `Scene::OnGameObjectCreated()`。 + +这让“切场景 / 重启 Play 模式 / 运行中生成对象”的脚本生命周期都收口到一条统一流程里。 + +## 固定步长配置与托管时间 + +`ScriptEngine` 当前把“固定步长配置值”和“某次 fixed tick 的实际回调参数”分成了两层： + +- [SetRuntimeFixedDeltaTime](SetRuntimeFixedDeltaTime.md) 写入的是引擎保存的配置值。 +- [OnFixedUpdate](OnFixedUpdate.md) 使用的是调用方本次传入的 `fixedDeltaTime`。 + +通常这两者应该保持一致，但当前代码不会自动强制它们一致。 + +另外还要注意两点： + +- [OnRuntimeStart](OnRuntimeStart.md) 会在内部 stop/start 之间保留启动前配置的 fixed delta。 +- [OnRuntimeStop](OnRuntimeStop.md) 完成后会把配置重置回 [DefaultFixedDeltaTime](DefaultFixedDeltaTime.md)。 + +Mono 侧 `Time.fixedDeltaTime` 当前直接读取 [GetRuntimeFixedDeltaTime](GetRuntimeFixedDeltaTime.md)，而 `Time.deltaTime` 则来自每次生命周期回调传入的 delta。因此脚本里这两个时间值虽然名字相近，但当前来源并不相同。 + +## 运行时追踪模型 当前 `ScriptEngine` 通过 `(gameObjectUUID, scriptComponentUUID)` 唯一标识一个脚本实例状态，并保存： @@ -43,9 +70,34 @@ - `startCalled` - `startPending` -这说明当前生命周期状态是显式状态机，而不是每次调用都从托管世界反查。 +这说明当前生命周期状态是显式状态机，而不是每次调用都从托管世界反查。好处是： -## 脚本类与字段模型 +- 生命周期顺序可控。 +- 运行中增删对象时更容易保持稳定顺序。 +- 后端只需要关心“如何创建 / 销毁 / 调方法”，而不需要再自己维护一份场景状态机。 + +`ShouldScriptRun()` 当前还明确要求以下条件同时成立： + +- 运行时已经启动。 +- `state.context.scene == m_runtimeScene`。 +- 场景处于激活状态。 +- `GameObject` 处于 hierarchy active。 +- `ScriptComponent` 已启用。 +- `ScriptComponent` 当前仍有脚本类绑定。 + +## 生命周期调用与字段回写 + +`ScriptEngine` 不是只做“调方法”这么简单。当前 `InvokeLifecycleMethod()` 在每次调用运行时生命周期方法后，都会立即调用 `SyncManagedFieldsToStorage()`。 + +这意味着： + +- 字段模型中的活体值和本地存储值会在生命周期边界上持续靠拢。 +- Inspector 或调试工具不需要等到运行时结束，才有机会看到脚本侧最新写回的字段。 +- 当前回写策略仍然是保守的，只同步本地已存在且类型匹配的字段。 + +这也是为什么 `ScriptEngine` 既是生命周期总调度器，也是脚本字段数据服务入口。 + +## 脚本类发现与重绑定 除了生命周期调度，`ScriptEngine` 还负责把运行时暴露成编辑器可消费的数据接口： @@ -54,7 +106,13 @@ - `ApplyScriptFieldWrites()` 会逐项返回 `Applied / UnknownField / TypeMismatch / StoredOnlyField` 等状态。 - `ClearScriptFieldOverrides()` 会把声明字段重置回类默认值，并删除本地存储中的覆盖项。 -这也是当前 Inspector 和脚本字段编辑工具最该依赖的 API 面。 +类重绑定链路也收口在这里： + +- `ScriptComponent::SetScriptClass()` / `ClearScriptClass()` 先更新组件上的绑定字符串。 +- 然后由 `ScriptEngine::OnScriptComponentClassChanged()` 负责停掉旧实例、移除旧跟踪、按新绑定重新跟踪。 +- 如果新绑定满足运行条件，会立即尝试 `EnsureScriptReady()`，也就是创建实例并补发 `Awake / OnEnable`。 + +需要注意的是，`OnScriptComponentClassChanged()` 并不会回滚 `ScriptComponent` 上已经写入的新绑定。如果新类在运行时里不存在，或 `CreateScriptInstance()` 失败，组件仍然保持新绑定，只是当前没有活体实例。 ## 线程语义 @@ -66,6 +124,7 @@ - 只跟踪当前运行场景里的脚本组件。 - `Start` 生命周期会在第一次 `OnUpdate()` 前补发一次，而不是在 `OnRuntimeStart()` 里立即调用。 +- 当前不会自动把 [SetRuntimeFixedDeltaTime](SetRuntimeFixedDeltaTime.md) 的配置值与 [OnFixedUpdate](OnFixedUpdate.md) 的参数强制同步；时间系统调用方需要自己保持一致。 - `TrySetScriptFieldValue()` 只有在后端能返回类字段元数据时，才会强校验字段名和类型；否则会退回到纯本地存储写入。 - `TryGetScriptFieldModel()` 会优先使用运行时返回的类默认值，而不是简单地把每种类型置零。 - `TryGetScriptFieldSnapshots()` 在模型成功但字段为空时会返回 `false`，调用方不能把“返回 `false`”简单等同于“接口失败”。 @@ -73,17 +132,26 @@ ## 常用访问器 - `GetRuntime()` +- `GetRuntimeFixedDeltaTime()` - `IsRuntimeRunning()` - `GetRuntimeScene()` 这些是简单内联访问器，当前文档重点放在影响状态机和运行行为的核心方法上。 +## 公开常量 + +| 常量 | 说明 | +|------|------| +| [DefaultFixedDeltaTime](DefaultFixedDeltaTime.md) | 默认运行时固定步长配置，当前为 `1/50` 秒。 | + ## 公开方法 | 方法 | 说明 | |------|------| | [Get](Get.md) | 获取全局脚本引擎实例。 | | [SetRuntime](SetRuntime.md) | 设置具体脚本后端。 | +| [SetRuntimeFixedDeltaTime](SetRuntimeFixedDeltaTime.md) | 设置运行时固定步长配置。 | +| [GetRuntimeFixedDeltaTime](GetRuntimeFixedDeltaTime.md) | 读取当前运行时固定步长配置。 | | [OnRuntimeStart](OnRuntimeStart.md) | 启动脚本运行时。 | | [OnRuntimeStop](OnRuntimeStop.md) | 停止脚本运行时。 | | [OnFixedUpdate](OnFixedUpdate.md) | 驱动固定步长脚本更新。 | @@ -107,9 +175,9 @@ ## 真实行为依据 - `engine/src/Scripting/ScriptEngine.cpp` -- `tests/scripting/test_script_engine.cpp` +- `tests/Scripting/test_script_engine.cpp` - `tests/Scene/test_scene_runtime.cpp` -- `tests/scripting/test_mono_script_runtime.cpp` +- `tests/Scripting/test_mono_script_runtime.cpp` ## 相关文档 diff --git a/docs/api/XCEngine/Scripting/ScriptEngine/SetRuntimeFixedDeltaTime.md b/docs/api/XCEngine/Scripting/ScriptEngine/SetRuntimeFixedDeltaTime.md new file mode 100644 index 00000000..3f88da56 --- /dev/null +++ b/docs/api/XCEngine/Scripting/ScriptEngine/SetRuntimeFixedDeltaTime.md @@ -0,0 +1,56 @@ +# ScriptEngine::SetRuntimeFixedDeltaTime + +**命名空间**: `XCEngine::Scripting` + +**类型**: `method` + +**头文件**: `XCEngine/Scripting/ScriptEngine.h` + +## 签名 + +```cpp +void SetRuntimeFixedDeltaTime(float fixedDeltaTime); +``` + +## 当前实现行为 + +- 当 `fixedDeltaTime > 0.0f` 时，直接把 `m_runtimeFixedDeltaTime` 设为该值。 +- 当 `fixedDeltaTime <= 0.0f` 时，回退到 [DefaultFixedDeltaTime](DefaultFixedDeltaTime.md)。 + +它不会立即驱动一次 `FixedUpdate`，也不会主动要求场景运行时调整时间步长；当前只是更新 `ScriptEngine` 持有的“运行时固定步长配置值”。 + +## 与运行时启停的关系 + +- 如果在 [OnRuntimeStart](OnRuntimeStart.md) 之前先配置该值，启动时会先暂存当前配置、内部调用一次 [OnRuntimeStop](OnRuntimeStop.md) 清理旧状态，再把这个配置值恢复回来，因此“启动前配置”不会被那次内部清理抹掉。 +- 一旦显式执行 [OnRuntimeStop](OnRuntimeStop.md)，当前配置会被重置回 [DefaultFixedDeltaTime](DefaultFixedDeltaTime.md)。 + +这意味着非默认 fixed delta 更像“本次运行前的配置值”，而不是跨 stop/start 永久保留的全局偏好。 + +## 与 `OnFixedUpdate()` 的关系 + +当前有两条相关但不完全相同的通道： + +- [OnFixedUpdate](OnFixedUpdate.md) 的 `fixedDeltaTime` 参数决定本次 `FixedUpdate` 生命周期回调收到的 delta +- [GetRuntimeFixedDeltaTime](GetRuntimeFixedDeltaTime.md) 返回的是这里设置的运行时配置值 + +`ScriptEngine` 当前不会自动强制这两者一致。正常情况下应由上层时间系统保持同步。 + +## 托管侧可见性 + +Mono 运行时的 `Time.fixedDeltaTime` 内部调用当前直接读取 [GetRuntimeFixedDeltaTime](GetRuntimeFixedDeltaTime.md)，因此这个配置值不仅影响原生侧说明，也会被托管脚本读到。 + +这也是为什么它虽然只是一个原生配置 setter，却会直接影响脚本里 `Time.fixedDeltaTime` 的观察结果。 + +## 真实行为依据 + +- `engine/src/Scripting/ScriptEngine.cpp` +- `engine/src/Scripting/Mono/MonoScriptRuntime.cpp` +- `managed/XCEngine.ScriptCore/Time.cs` + +## 相关文档 + +- [GetRuntimeFixedDeltaTime](GetRuntimeFixedDeltaTime.md) +- [DefaultFixedDeltaTime](DefaultFixedDeltaTime.md) +- [OnRuntimeStart](OnRuntimeStart.md) +- [OnRuntimeStop](OnRuntimeStop.md) +- [OnFixedUpdate](OnFixedUpdate.md) diff --git a/docs/api/XCEngine/Scripting/ScriptEngine/TryGetAvailableScriptClasses.md b/docs/api/XCEngine/Scripting/ScriptEngine/TryGetAvailableScriptClasses.md index ba7412ca..ef5ccc3a 100644 --- a/docs/api/XCEngine/Scripting/ScriptEngine/TryGetAvailableScriptClasses.md +++ b/docs/api/XCEngine/Scripting/ScriptEngine/TryGetAvailableScriptClasses.md @@ -21,15 +21,35 @@ bool TryGetAvailableScriptClasses( ## 当前实现流程 1. 清空 `outClasses`。 -2. 调用运行时 `TryGetAvailableScriptClasses()`。 -3. 若传入了 `assemblyName`，只保留匹配该程序集的类。 -4. 过滤掉 `className` 为空的无效描述。 -5. 按 `assemblyName -> namespaceName -> className` 排序。 +2. 调用当前运行时的 `TryGetAvailableScriptClasses(runtimeClasses)`。 +3. 如果运行时返回 `false`，直接返回 `false`。 +4. 若传入了 `assemblyName`，只保留匹配该程序集的条目。 +5. 过滤掉 `className` 为空的无效描述。 +6. 按 `assemblyName -> namespaceName -> className` 排序。 +7. 返回 `true`。 + +## 关键语义 + +- 这个方法消费的是“运行时已经发现好的类列表”，不会在这里重新扫描程序集，也不会为结果做实例创建验证。 +- 如果运行时能提供列表，但过滤后一个类都不剩，当前仍返回 `true`，只是 `outClasses` 为空。 +- 这一步的排序是给 Inspector / 脚本类选择 UI 做稳定输出用的；调用方不需要再按自己的规则重排一遍。 +- 当前 `MonoScriptRuntime` 本身也会返回排序后的列表，但 `ScriptEngine` 仍然会再做一层规范化，这样换后端时对上层 UI 的输出形态更稳定。 ## 返回值语义 -- 返回 `true`：运行时支持类发现，排序/过滤后的结果可用。 -- 返回 `false`：运行时不支持或当前不能返回类列表。 +- 返回 `true`: 运行时支持类发现，排序 / 过滤后的结果可用。 +- 返回 `false`: 运行时不支持，或当前不能返回类列表。 + +## 典型用途 + +- Inspector 中的脚本类下拉列表。 +- 运行时或编辑器中的脚本类过滤器。 +- 需要显示 `Namespace.Class` 稳定排序结果的调试面板。 + +## 真实行为依据 + +- `engine/src/Scripting/ScriptEngine.cpp` +- `tests/Scripting/test_script_engine.cpp` ## 相关文档 diff --git a/docs/api/XCEngine/Scripting/Scripting.md b/docs/api/XCEngine/Scripting/Scripting.md index 69c84bab..8a1e02f0 100644 --- a/docs/api/XCEngine/Scripting/Scripting.md +++ b/docs/api/XCEngine/Scripting/Scripting.md @@ -8,51 +8,87 @@ ## 概览 -当前脚本模块已经形成一条比较明确的“数据层 -> 调度层 -> 后端层”链路： +当前脚本模块已经形成一条明确的“场景数据层 -> 运行时调度层 -> 托管后端层”链路： 1. [ScriptComponent](ScriptComponent/ScriptComponent.md) 挂在 `GameObject` 上，保存程序集名、命名空间、类名、组件 UUID 和 [ScriptFieldStorage](ScriptFieldStorage/ScriptFieldStorage.md)。 2. [ScriptEngine](ScriptEngine/ScriptEngine.md) 在运行时收集场景内所有脚本组件，按 `(gameObjectUUID, scriptComponentUUID)` 跟踪实例状态，并统一驱动生命周期。 3. [IScriptRuntime](IScriptRuntime/IScriptRuntime.md) 定义“类发现、字段元数据、默认值读取、实例创建、生命周期调用、字段同步”的统一契约。 -4. [NullScriptRuntime](NullScriptRuntime/NullScriptRuntime.md) 负责在没有真实托管后端时兜底，让脚本数据层和编辑流程仍然可工作。 +4. [NullScriptRuntime](NullScriptRuntime/NullScriptRuntime.md) 在没有真实托管后端时兜底，让脚本数据层和编辑流程仍然可工作。 5. [Mono](Mono/Mono.md) 子目录中的 [MonoScriptRuntime](Mono/MonoScriptRuntime/MonoScriptRuntime.md) 是当前唯一的真实托管后端，负责加载 `XCEngine.ScriptCore.dll` 与 `GameScripts.dll`、发现脚本类、创建托管实例并完成字段桥接。 -如果从引擎分层角度理解： +如果从商业级游戏引擎常见的分层方式理解： - `ScriptComponent + ScriptFieldStorage` 是可序列化的数据层。 - `ScriptEngine` 是场景运行时的调度层。 -- `IScriptRuntime`/`MonoScriptRuntime` 是托管执行后端。 +- `IScriptRuntime` / `MonoScriptRuntime` 是托管执行后端。 -## 设计要点 +这种拆分和 Unity 一类引擎的设计取向很接近。核心目的不是“为了抽象而抽象”，而是把“场景持久化”“运行时生命周期”“托管语言桥接”三件本来容易互相缠死的事拆开。 -- 场景序列化只依赖 `ScriptComponent` 和 `ScriptFieldStorage`，不依赖 Mono 是否已经初始化。 -- 字段模型分成“类声明默认值、存储覆盖值、活体托管值”三层，便于 Inspector 和调试工具说明字段来源。 -- `ScriptEngine` 把生命周期顺序、运行中生成对象追踪、类切换重建都集中在一处。 -- `IScriptRuntime` 让主流程只依赖契约，后续可以接别的托管后端，而不是把 Mono API 直接扩散到引擎各处。 +## 为什么当前要这样设计 + +- 场景、Prefab 或 Inspector 在运行时未启动时也必须能稳定保存脚本绑定和字段覆盖值，因此 `ScriptComponent` 不能直接等价于活体托管对象。 +- 生命周期顺序、场景内动态创建对象追踪、类切换重建这些规则需要由原生层统一控制，否则更换脚本后端时行为会漂。 +- 类发现、字段默认值读取和真正实例化都以编译后的程序集为事实来源，能让“下拉列表里看到的类”“Inspector 里看到的默认值”“运行时真正创建出的类”尽量来自同一份元数据。 +- 把 Mono API、GCHandle、internal call 注册等细节收敛在 `MonoScriptRuntime`，可以避免后端实现扩散到引擎各个模块。 + +## 托管桥接的当前真实语义 + +当前 Mono 桥接已经不是单纯“脚本能跑起来”这一层，而是直接暴露了一套和原生状态中心相连的脚本 API 面： + +- `Time.deltaTime` + - 由 `MonoScriptRuntime::InvokeMethod()` 在每次生命周期调用前写入 internal call 全局状态。 + - `FixedUpdate()` 中读到的是本次 `OnFixedUpdate(fixedDeltaTime)` 传入的参数。 + - `Update()` / `LateUpdate()` 中读到的是各自回调传入的逐帧 delta。 +- `Time.fixedDeltaTime` + - 不读取某次 fixed tick 的历史参数，而是直接走 `ScriptEngine::GetRuntimeFixedDeltaTime()`。 + - 也就是说，它反映的是“当前运行时固定步长配置值”，不是“本次 `FixedUpdate()` 实参快照”。 +- `Input` + - `Input.GetKey()` / `GetKeyDown()` / `GetKeyUp()`、`GetButton*()`、`GetAxis*()`、`anyKey` / `anyKeyDown` 都是对 [InputManager](../Input/InputManager/InputManager.md) 当前状态的直接转发。 + - `GetKeyUp()` 当前对应的是释放边沿语义，也就是原生 `IsKeyReleased()`，不是“当前键没有按住”。 + - `anyKey` / `anyKeyDown` 也会把鼠标按钮状态算进去，并继承输入系统的帧边界语义。 + +如果要进一步理解 `Pressed` / `Released` / `anyKeyDown` 的帧语义，应同时阅读 [Input Flow And Frame Semantics](../../_guides/Input/Input-Flow-and-Frame-Semantics.md)。 ## 当前运行链路 1. `SceneRuntime` 启动场景时调用 `ScriptEngine::OnRuntimeStart(scene)`。 2. `ScriptEngine` 先通知当前运行时启动，再递归收集场景里现有的 `ScriptComponent`，同时订阅 `Scene::OnGameObjectCreated()` 以追踪运行中创建的新对象。 -3. 对满足运行条件的组件，运行时创建托管实例；`MonoScriptRuntime` 会先把 `ScriptFieldStorage` 中同名且类型匹配的字段写入实例。 -4. `ScriptEngine` 统一按 `Awake -> OnEnable -> Start -> FixedUpdate/Update/LateUpdate` 驱动生命周期。 -5. 每次生命周期调用后，运行时执行 `SyncManagedFieldsToStorage()`；当前 Mono 实现只会回写“本地已存在且类型仍匹配”的字段。 +3. 对满足运行条件的组件，运行时创建托管实例；`MonoScriptRuntime` 会先注入 `gameObjectUUID` / `scriptComponentUUID`，再把 `ScriptFieldStorage` 中同名且类型匹配的字段写入实例。 +4. `ScriptEngine` 统一按 `Awake -> OnEnable -> Start -> FixedUpdate / Update / LateUpdate` 驱动生命周期；其中 `Start` 会延后到第一次 `OnUpdate()` 前补发，而不是在 `OnRuntimeStart()` 中立即执行。 +5. 每次生命周期调用后，运行时都会执行 `SyncManagedFieldsToStorage()`；当前 Mono 实现只会回写“本地已存在且类型仍匹配”的字段。 6. 编辑器或调试工具可通过 `ScriptEngine::TryGetScriptFieldModel()` / `TryGetScriptFieldSnapshots()` 看到字段默认值、覆盖值、活体值以及 `StoredOnly` / `TypeMismatch` 等诊断状态。 +## 脚本类发现与重绑定 + +当前“脚本类下拉列表”和“运行中改类名”的语义已经明确落在源码里： + +- `MonoScriptRuntime` 只扫描应用程序集，也就是 `GameScripts.dll` 这一侧的非抽象 `MonoBehaviour` 子类，不会把 `XCEngine.ScriptCore.dll` 里的基础类型暴露成可绑定脚本类。 +- `ScriptEngine::TryGetAvailableScriptClasses()` 在运行时列表之上追加两步规范化： + - 可选的按程序集过滤 + - 按 `assemblyName -> namespaceName -> className` 排序，并剔除空类名条目 +- `ScriptComponent::SetScriptClass()` / `ClearScriptClass()` 是显式重绑定入口。 +- 运行时里真正执行“停掉旧实例 -> 重新跟踪 -> 视情况立即创建新实例”的，是 [ScriptEngine::OnScriptComponentClassChanged](ScriptEngine/OnScriptComponentClassChanged.md)。 + +这套设计和商业引擎里常见的 Inspector 行为一致：类切换不是随便改几个字符串，而是走一条受控的重绑定链路。 + ## 项目程序集来源 当 `XCENGINE_ENABLE_MONO_SCRIPTING` 打开时，`managed/CMakeLists.txt` 会构建两类程序集： -- 引擎脚本核心程序集：`XCEngine.ScriptCore.dll` -- 游戏脚本程序集：`GameScripts.dll` +- 引擎脚本核心程序集: `XCEngine.ScriptCore.dll` +- 游戏脚本程序集: `GameScripts.dll` -除了测试用的 `build/managed` 输出，CMake 还会把项目 `project/Assets/**/*.cs` 编译到 `project/Library/ScriptAssemblies/GameScripts.dll`。`MonoScriptRuntime::Settings` 可以直接指向该目录，因此项目资产脚本和默认字段值已经进入当前文档的真实行为范围。 +除了测试用的 `build/managed` 输出，同一套 CMake 还会把项目 `project/Assets/**/*.cs` 编译到 `project/Library/ScriptAssemblies/GameScripts.dll`。如果项目暂时没有任何 `.cs` 文件，还会生成占位源文件，确保 `GameScripts.dll` 仍然存在。 + +`MonoScriptRuntime::Settings` 可以直接指向 `project/Library/ScriptAssemblies`，因此项目资产脚本、它们的字段默认值、类发现结果，已经进入当前文档的真实行为范围，而不是“未来规划”。 ## 当前实现边界 -- 当前公开支持的脚本字段类型是有限集合：标量、字符串、`Vector2/3/4` 和 `GameObject` 引用。 +- 当前公开支持的脚本字段类型是有限集合: 标量、字符串、`Vector2/3/4` 和 `GameObject` 引用。 - 生命周期覆盖 `Awake / OnEnable / Start / FixedUpdate / Update / LateUpdate / OnDisable / OnDestroy`。 - `NullScriptRuntime` 只是桥接占位，不会真正执行脚本代码，也不会返回脚本类列表或字段默认值。 - `MonoScriptRuntime` 目前只发现应用程序集中的非抽象 `MonoBehaviour` 子类，不做热重载、域增量刷新或完整编辑器脚本生态。 +- `Time.fixedDeltaTime` 的配置值与 `OnFixedUpdate(fixedDeltaTime)` 的回调参数当前仍是两条通道，上层时间系统需要自己保持一致。 - 字段同步目前不会自动把“运行中新增但本地没有声明”的字段持久化下来。 ## 头文件 @@ -67,8 +103,9 @@ ## 相关指南 -- [Scripting Runtime And Field Model](../../_guides/Scripting/Scripting-Runtime-And-Field-Model.md) - 解释当前脚本系统如何把场景、脚本字段缓存和 Mono 运行时衔接起来，以及为什么这样设计。 -- [Project Script Assembly And Field Sync](../../_guides/Scripting/Project-Script-Assembly-And-Field-Sync.md) - 解释 `project/Assets/**/*.cs` 如何进入 `GameScripts.dll`，以及默认值、存储覆盖和活体字段如何相互覆盖。 +- [Scripting Runtime And Field Model](../../_guides/Scripting/Scripting-Runtime-And-Field-Model.md) - 把场景、脚本字段缓存、运行时调度和 Mono 后端放回同一条真实链路里解释清楚，并补上设计理念。 +- [Project Script Assembly And Field Sync](../../_guides/Scripting/Project-Script-Assembly-And-Field-Sync.md) - 解释 `project/Assets/**/*.cs` 如何进入 `GameScripts.dll`，哪些类会被发现，以及默认值、存储覆盖和活体字段如何相互覆盖。 +- [Input Flow And Frame Semantics](../../_guides/Input/Input-Flow-and-Frame-Semantics.md) - 解释托管 `Input` API 当前所继承的原生输入帧语义。 ## 相关文档 diff --git a/docs/api/XCEngine/UI/Core/Core.md b/docs/api/XCEngine/UI/Core/Core.md new file mode 100644 index 00000000..6177a3f4 --- /dev/null +++ b/docs/api/XCEngine/UI/Core/Core.md @@ -0,0 +1,24 @@ +# Core + +**命名空间**: `XCEngine::UI` + +**类型**: `submodule` + +**头文件目录**: `engine/include/XCEngine/UI/Core/` + +**描述**: XCUI 核心树结构与失效传播层，负责 build context、UI context、element tree、view-model 基类和 invalidation 协议。 + +## 当前范围 + +- `UIBuildContext` +- `UIContext` +- `UIElementTree` +- `UIInvalidation` +- `UIViewModel` + +## 相关文档 + +- [UI](../UI.md) +- [Input](../Input/Input.md) +- [Layout](../Layout/Layout.md) + diff --git a/docs/api/XCEngine/UI/Core/UIBuildContext/UIBuildContext.md b/docs/api/XCEngine/UI/Core/UIBuildContext/UIBuildContext.md new file mode 100644 index 00000000..b16962a6 --- /dev/null +++ b/docs/api/XCEngine/UI/Core/UIBuildContext/UIBuildContext.md @@ -0,0 +1,54 @@ +# UIBuildContext + +**命名空间**: `XCEngine::UI` + +**类型**: `structs + classes` + +**头文件**: `XCEngine/UI/Core/UIBuildContext.h` + +**描述**: retained-mode UI build 阶段的快照收集层，负责把调用侧声明的元素树写入 `UIBuildList`，并在写入时校验 id、根节点和 view-model revision。 +## 概览 + +这份头文件当前公开四类声明： + +| 声明 | 角色 | +|------|------| +| `UIBuildElement` | build 阶段产出的扁平元素快照。 | +| `UIBuildElementDesc` | 调用侧提交给 build context 的输入描述。 | +| `UIBuildList` | 存放 `UIBuildElement` 序列的轻量容器。 | +| `UIBuildContext` | 收集与校验 build 输出的上下文。 | + +## 当前实现行为 + +- `UIBuildElementDesc` 由调用侧提供 `id`、`typeName`、`structuralRevision`、`localStateRevision` 与可选 `viewModel`。 +- `UIBuildContext` 在追加元素时会把 `viewModel->GetViewModelRevision()` 快照写进 `UIBuildElement.viewModelRevision`；传空 view model 时记为 `0`。 +- `BeginElement(...)` 会把当前元素压栈并保持打开状态；`AddLeaf(...)` 只写入一条叶子元素；`EndElement()` 弹出栈顶。 +- `PushElement(...)` 返回 RAII 风格 `ElementScope`，析构时会自动调用 `EndElement()`；这是当前测试和构建代码里最常用的写法。 +- 当前校验规则包括： + - `id` 不能为 `kInvalidUIElementId` + - `typeName` 不能为空 + - 同一轮 build 里不能重复使用 id + - 整个 build list 只允许一个根节点 +- 一旦首次错误被记录到 `m_lastError`，后续 `AppendElement(...)` 会直接返回 `false`，不再继续写入。 + +## 与 `UIContext` / `UIElementTree` 的关系 + +- `UIContext::Rebuild(...)` 每次都会先 `m_buildList.Reset()`，再创建新的 `UIBuildContext`。 +- `UIBuildContext` 只负责“生成一份合法的 build 快照”，不负责 diff 或 dirty 传播。 +- 真正的增量比较在 [UIElementTree](../UIElementTree/UIElementTree.md) 里完成。 + +## 测试与调用链 + +- `tests/UI/Core/unit/test_ui_core.cpp` 当前覆盖： + - `PushElement(...) + AddLeaf(...)` 的正常建树路径 + - 结构变化、局部状态变化和 view-model revision 变化 + - 未闭合元素 scope 导致 `UIContext::Rebuild(...)` 失败 +- `engine/src/UI/Core/UIBuildContext.cpp` 当前实现中，`ElementScope::Close()` 只是薄封装 `EndElement()`，没有额外副作用。 + +## 相关文档 + +- [Core](../Core.md) +- [UIInvalidation](../UIInvalidation/UIInvalidation.md) +- [UIViewModel](../UIViewModel/UIViewModel.md) +- [UIElementTree](../UIElementTree/UIElementTree.md) +- [UIContext](../UIContext/UIContext.md) diff --git a/docs/api/XCEngine/UI/Core/UIContext/UIContext.md b/docs/api/XCEngine/UI/Core/UIContext/UIContext.md new file mode 100644 index 00000000..ce906dc1 --- /dev/null +++ b/docs/api/XCEngine/UI/Core/UIContext/UIContext.md @@ -0,0 +1,42 @@ +# UIContext + +**命名空间**: `XCEngine::UI` + +**类型**: `class` + +**头文件**: `XCEngine/UI/Core/UIContext.h` + +**描述**: retained-mode UI build/rebuild 的外层入口，持有一份复用的 `UIBuildList` 和一棵 `UIElementTree`，并通过 `BuildCallback` 驱动每轮重建。 +## 概览 + +`UIContext` 当前的公开接口很窄： + +- `using BuildCallback = std::function` +- `UIElementTreeRebuildResult Rebuild(const BuildCallback& buildCallback)` +- `GetElementTree()` / `GetElementTree() const` + +调用模式是： + +1. 调用侧提供一个 `BuildCallback` +2. `UIContext` 创建临时 `UIBuildContext` +3. callback 往 `m_buildList` 写入本轮元素快照 +4. `UIContext` 校验 build 是否成功且所有 element scope 都已闭合 +5. 把 build list 交给 `UIElementTree::Rebuild(...)` + +## 当前实现边界 + +- `Rebuild(...)` 每次都会先 `m_buildList.Reset()`，不会复用上一轮元素快照内容。 +- 如果 `buildCallback` 为空，当前仍然会继续执行，这会把空 build list 交给 `UIElementTree`，从而清空现有树。 +- 如果 `UIBuildContext` 自身已经报错，`Rebuild(...)` 会直接返回失败结果，不会触碰 `UIElementTree`。 +- 如果 callback 结束时仍有未闭合元素，`Rebuild(...)` 会以 `"UIContext::Rebuild finished with unclosed UI elements."` 失败。 + +## 测试与调用链 + +- `tests/UI/Core/unit/test_ui_core.cpp` 当前覆盖正常 build、无变化 rebuild、局部状态变化、view-model 变化、结构性变化和未闭合 scope 失败路径。 +- `engine/src/UI/Core/UIElementTree.cpp` 里当前直接实现了 `UIContext::Rebuild(...)`，说明 `UIContext` 本身只是围绕 `UIBuildContext` 和 `UIElementTree` 的薄协调层。 + +## 相关文档 + +- [Core](../Core.md) +- [UIBuildContext](../UIBuildContext/UIBuildContext.md) +- [UIElementTree](../UIElementTree/UIElementTree.md) diff --git a/docs/api/XCEngine/UI/Core/UIElementTree/UIElementTree.md b/docs/api/XCEngine/UI/Core/UIElementTree/UIElementTree.md new file mode 100644 index 00000000..35a19258 --- /dev/null +++ b/docs/api/XCEngine/UI/Core/UIElementTree/UIElementTree.md @@ -0,0 +1,59 @@ +# UIElementTree + +**命名空间**: `XCEngine::UI` + +**类型**: `enum + structs + class` + +**头文件**: `XCEngine/UI/Core/UIElementTree.h` + +**描述**: retained-mode UI 树的 diff 与 dirty 传播层，负责把一份 `UIBuildList` 重建成元素树，并产出增量变化、dirty roots 与 generation。 +## 概览 + +`UIElementTree.h` 当前公开的核心声明有： + +| 声明 | 角色 | +|------|------| +| `UIElementChangeKind` | `Created` / `Updated` / `Removed` 变化分类。 | +| `UIElementNode` | 树中单个节点的持久状态。 | +| `UIElementChange` | 单个节点在本轮 rebuild 中的变化记录。 | +| `UIElementTreeRebuildResult` | rebuild 结果，包括 `succeeded`、`treeChanged`、`generation`、`changes`、`dirtyRootIds`。 | +| `UIElementTree` | 真正的 retained-mode 树与 diff 引擎。 | + +## 当前实现行为 + +- `Rebuild(const UIBuildList&)` 会把 `generation` 推进到 `m_generation + 1`。 +- 空 `UIBuildList` 当前会删除整棵树，并为旧节点产生 `Removed + Structure|Layout|Paint` 变化。 +- rebuild 前会先校验： + - element id 非零 + - id 唯一 + - 第一项必须是根节点 + - 父节点必须存在 + - 父节点必须先于子节点出现 +- 对已有节点的比较规则当前是： + - `parentId` / `typeName` / `structuralRevision` / `childIds` 改变 + - 记为 `Structure | Layout | Paint` + - `localStateRevision` 改变 + - 记为 `LocalState | Paint` + - `viewModelRevision` 改变 + - 记为 `ViewModel | Paint` +- `MarkDirtyInternal(...)` 会把结构性变化额外向祖先节点冒泡 `Layout` dirty，但不会把 `Structure` 一路冒泡到祖先。 +- `CollectDirtyRootIds()` 只返回“自身 dirty 且父节点不 dirty”的节点，并按 `depth`、`id` 升序排序。 +- `ClearDirtyFlags(id, includeSubtree)` 在 `includeSubtree == false` 时只清当前节点，在 `true` 时递归清子树；`ClearAllDirtyFlags()` 则清空整棵树。 + +## 测试与调用链 + +- `tests/UI/Core/unit/test_ui_core.cpp` 当前直接覆盖： + - 初次建树生成稳定 parent/child 关系 + - 清空 dirty 后的无变化 rebuild + - 局部状态变化只脏化叶子 + - view-model 变化命中 `ViewModel` + - 结构变化让祖先命中 `Layout` +- [UIContext](../UIContext/UIContext.md) 当前在 build 阶段结束后直接调用这里的 `Rebuild(...)`。 + +## 相关文档 + +- [Core](../Core.md) +- [UIInvalidation](../UIInvalidation/UIInvalidation.md) +- [UIViewModel](../UIViewModel/UIViewModel.md) +- [UIBuildContext](../UIBuildContext/UIBuildContext.md) +- [UIContext](../UIContext/UIContext.md) diff --git a/docs/api/XCEngine/UI/Core/UIInvalidation/UIInvalidation.md b/docs/api/XCEngine/UI/Core/UIInvalidation/UIInvalidation.md new file mode 100644 index 00000000..d0a0544b --- /dev/null +++ b/docs/api/XCEngine/UI/Core/UIInvalidation/UIInvalidation.md @@ -0,0 +1,41 @@ +# UIInvalidation + +**命名空间**: `XCEngine::UI` + +**类型**: `alias + enum + free functions` + +**头文件**: `XCEngine/UI/Core/UIInvalidation.h` + +**描述**: XCUI retained-mode 树的脏标记协议，定义元素 id、无效 id、dirty flags 以及按位组合与查询 helper。 +## 概览 + +这份头文件当前只做一件事：给 `UIBuildContext`、`UIElementTree` 和依赖 retained-mode diff 的上层系统提供统一的 invalidation 语言。 + +## 关键声明 + +| 声明 | 角色 | +|------|------| +| `UIElementId` | UI 树节点 id，当前是 `std::uint64_t`。 | +| `kInvalidUIElementId` | 无效元素 id，固定为 `0`。 | +| `UIDirtyFlags` | `Structure`、`Layout`、`Paint`、`LocalState`、`ViewModel` 五类脏标记。 | +| `operator|` / `operator&` / `operator|=` / `operator&=` | 按位组合 dirty flag。 | +| `HasAnyDirtyFlags(...)` | 判定指定标记是否命中。 | +| `IsDirty(...)` | 判定 dirty flag 是否非空。 | + +## 当前实现行为 + +- `UIDirtyFlags` 是显式 bitmask；当前没有单独的 flag-set 类型，组合完全依赖这些内联操作符。 +- `UIElementTree` 当前把结构性变化映射到 `Structure | Layout | Paint`，把局部状态变化映射到 `LocalState | Paint`，把 view-model 变化映射到 `ViewModel | Paint`。 +- `IsDirty(...)` 只检查是否非 `None`，不区分 dirty 来源。 + +## 测试与调用链 + +- `tests/UI/Core/unit/test_ui_core.cpp` 当前直接验证结构变化向祖先冒泡 `Layout`、view-model 变化命中 `ViewModel`、局部状态变化命中 `LocalState`。 +- `engine/include/XCEngine/UI/Widgets/UISplitterInteraction.h` 等 XCUI widget 头文件当前已经直接复用这套 dirty flag 类型。 + +## 相关文档 + +- [Core](../Core.md) +- [UIViewModel](../UIViewModel/UIViewModel.md) +- [UIBuildContext](../UIBuildContext/UIBuildContext.md) +- [UIElementTree](../UIElementTree/UIElementTree.md) diff --git a/docs/api/XCEngine/UI/Core/UIViewModel/UIViewModel.md b/docs/api/XCEngine/UI/Core/UIViewModel/UIViewModel.md new file mode 100644 index 00000000..0bf8c087 --- /dev/null +++ b/docs/api/XCEngine/UI/Core/UIViewModel/UIViewModel.md @@ -0,0 +1,38 @@ +# UIViewModel + +**命名空间**: `XCEngine::UI` + +**类型**: `interface + base class` + +**头文件**: `XCEngine/UI/Core/UIViewModel.h` + +**描述**: retained-mode UI 视图模型 revision 协议，定义只读 revision 接口和一个最小的自增基类实现。 +## 概览 + +`UIViewModel.h` 当前不是复杂的数据绑定系统，而是一份非常窄的契约： + +- `IUIViewModel` + - 只暴露 `GetViewModelRevision() const` +- `RevisionedViewModelBase` + - 保存内部 `m_revision` + - 通过受保护的 `MarkViewModelChanged()` 推进 revision + +`UIBuildContext` 会把 `UIBuildElementDesc.viewModel` 当前 revision 快照写进 `UIBuildElement.viewModelRevision`；随后 `UIElementTree::Rebuild(...)` 再用它与上一帧对比，决定是否标记 `ViewModel | Paint`。 + +## 当前实现边界 + +- `IUIViewModel` 当前没有属性枚举、字段观察器或生命周期 hook；唯一公开契约就是“给我一个可比较的 revision”。 +- `RevisionedViewModelBase` 的自增入口是受保护成员，调用侧需要在派生类里决定什么时候算“view-model 变化”。 +- revision 当前只是 `std::uint64_t` 单调计数器；没有时间戳、脏字段集合或线程同步语义。 + +## 测试与调用链 + +- `tests/UI/Core/unit/test_ui_core.cpp` 当前通过 `TestViewModel : RevisionedViewModelBase` 验证 revision 变化会让绑定元素得到 `ViewModel | Paint` 脏标记。 +- `UIBuildContext.h` 和 `UIElementTree.cpp` 当前是这份协议最直接的生产者与消费者。 + +## 相关文档 + +- [Core](../Core.md) +- [UIInvalidation](../UIInvalidation/UIInvalidation.md) +- [UIBuildContext](../UIBuildContext/UIBuildContext.md) +- [UIElementTree](../UIElementTree/UIElementTree.md) diff --git a/docs/api/XCEngine/UI/DrawData/DrawData.md b/docs/api/XCEngine/UI/DrawData/DrawData.md new file mode 100644 index 00000000..ea62856a --- /dev/null +++ b/docs/api/XCEngine/UI/DrawData/DrawData.md @@ -0,0 +1,52 @@ +# DrawData + +**命名空间**: `XCEngine::UI` + +**类型**: `structs + classes` + +**头文件**: `XCEngine/UI/DrawData.h` + +**描述**: XCUI 绘制命令缓冲区，定义颜色、命令类型、单条命令、draw list 和多 draw-list 聚合容器。 +## 概览 + +`DrawData.h` 当前把绘制层拆成两级： + +- `UIDrawList` + - 面向单个逻辑图层或单个文档的命令顺序缓冲区 + - 通过 `AddFilledRect(...)`、`AddRectOutline(...)`、`AddText(...)`、`AddImage(...)`、`PushClipRect(...)`、`PopClipRect()` 追加命令 +- `UIDrawData` + - 面向一帧或一次提交的 draw-list 集合 + - 通过 `EmplaceDrawList(...)` / `AddDrawList(...)` 聚合多个列表 + +`UIDrawCommand` 当前用一个统一结构承载所有命令；不同 `UIDrawCommandType` 只消费自己需要的字段，未使用字段保持默认值。 + +## 关键声明 + +| 声明 | 角色 | +|------|------| +| `UIColor` | RGBA 颜色。 | +| `UIDrawCommandType` | `FilledRect`、`RectOutline`、`Text`、`Image`、`PushClipRect`、`PopClipRect` 六类命令。 | +| `UIDrawCommand` | 单条绘制命令及其 rect/position/uv/text/texture 等参数。 | +| `UIDrawList` | 追加式命令列表。 | +| `UIDrawData` | 多 draw-list 聚合容器。 | + +## 当前实现行为 + +- `UIDrawList` 当前严格保留追加顺序，不做排序、合批或去重。 +- `PushClipRect(...)` / `PopClipRect()` 只是把 clip 操作编码成命令；真正的 clip stack 语义由消费端实现。 +- `UIDrawData::GetTotalCommandCount()` 当前通过遍历全部 draw list 求和，没有额外缓存。 +- `UIDrawData::Clear()` 会清空整个 draw-list 数组；`UIDrawList::Clear()` 只清空单个列表的命令，不改 `debugName`。 +- `ImGuiTransitionBackend` 当前逐条翻译 `UIDrawCommand` 到 `ImDrawList`；`UIScreenDocumentHost` 则在运行时 UI 渲染末端生成 `UIDrawData`。 + +## 测试与调用链 + +- `tests/Editor/test_xcui_draw_data.cpp` 当前直接验证 `UIDrawList` 的命令顺序、payload 保真和 `UIDrawData` 的多列表聚合计数。 +- `editor/src/XCUIBackend/ImGuiTransitionBackend.h` 当前是最直接的消费端，把 `PushClipRect` / `PopClipRect` / `Text` / `Image` 等命令映射到 ImGui。 +- `engine/src/UI/Runtime/UIScreenDocumentHost.cpp` 当前在 UI runtime 渲染阶段创建 draw list，并把 `drawListCount`、`commandCount` 统计写回运行结果。 +- `new_editor/src/Widgets/UIEditorPanelFrame.cpp`、`editor/src/panels/XCUIDemoPanel.cpp` 和多组 editor integration 测试当前直接构建 `UIDrawList`。 + +## 相关文档 + +- [UI](../UI.md) +- [Types](../Types/Types.md) +- [Runtime](../Runtime/Runtime.md) diff --git a/docs/api/XCEngine/UI/Input/Input.md b/docs/api/XCEngine/UI/Input/Input.md new file mode 100644 index 00000000..bdf5a4b6 --- /dev/null +++ b/docs/api/XCEngine/UI/Input/Input.md @@ -0,0 +1,24 @@ +# Input + +**命名空间**: `XCEngine::UI` + +**类型**: `submodule` + +**头文件目录**: `engine/include/XCEngine/UI/Input/` + +**描述**: XCUI 输入与焦点层，负责输入路径、dispatcher、router、focus controller 和 shortcut registry。 + +## 当前范围 + +- `UIInputPath` +- `UIInputDispatcher` +- `UIInputRouter` +- `UIFocusController` +- `UIShortcutRegistry` + +## 相关文档 + +- [UI](../UI.md) +- [Core](../Core/Core.md) +- [Widgets](../Widgets/Widgets.md) + diff --git a/docs/api/XCEngine/UI/Input/UIFocusController/UIFocusController.md b/docs/api/XCEngine/UI/Input/UIFocusController/UIFocusController.md new file mode 100644 index 00000000..70bbb440 --- /dev/null +++ b/docs/api/XCEngine/UI/Input/UIFocusController/UIFocusController.md @@ -0,0 +1,42 @@ +# UIFocusController + +**命名空间**: `XCEngine::UI` + +**类型**: `struct + class` + +**头文件**: `XCEngine/UI/Input/UIFocusController.h` + +**描述**: XCUI 输入焦点状态控制器，统一维护 focused path、active path 和 pointer capture path，并在 focus 切换时计算 lost/gained 路径后缀。 +## 概览 + +这份头文件当前公开两类声明： + +| 声明 | 角色 | +|------|------| +| `UIFocusChange` | 一次 focus 变化的前后路径与 gained/lost suffix。 | +| `UIFocusController` | focus、active、pointer capture 三条状态路径的持有者。 | + +## 当前实现行为 + +- `SetFocusedPath(...)` 会比较旧路径和新路径的公共前缀，并把变化折叠成： + - `previousPath` + - `currentPath` + - `lostPath` + - `gainedPath` +- `ClearFocus()` 只是 `SetFocusedPath({})` 的薄封装。 +- `activePath` 与 `pointerCapturePath` 当前完全独立于 `focusedPath`；设置或清理它们都不会自动改 focus。 +- `HasFocus()`、`HasActivePath()`、`HasPointerCapture()` 都只是判断对应路径是否为空。 +- `IsFocused(...)`、`IsActive(...)`、`IsCapturingPointer(...)` 都是基于 `UIInputPath::Contains(...)` 的成员测试，不要求元素必须是 target。 + +## 测试与调用链 + +- `tests/Input/test_xcui_input_dispatcher.cpp` 当前直接验证 `SetFocusedPath(...)` 会输出正确的 `lostPath` / `gainedPath` 后缀。 +- `UIInputDispatcher` 当前把 pointer down、keyboard activation、pointer capture 与 pointer up 都统一投递到这里维护状态。 +- `UIScreenDocumentHost` 当前通过 `GetFocusedPath()`、`GetActivePath()` 和 `GetPointerCapturePath()` 参与 hover/focus/active 绘制与事件分发。 + +## 相关文档 + +- [Input](../Input.md) +- [UIInputPath](../UIInputPath/UIInputPath.md) +- [UIInputDispatcher](../UIInputDispatcher/UIInputDispatcher.md) +- [UIInputRouter](../UIInputRouter/UIInputRouter.md) diff --git a/docs/api/XCEngine/UI/Input/UIInputDispatcher/UIInputDispatcher.md b/docs/api/XCEngine/UI/Input/UIInputDispatcher/UIInputDispatcher.md new file mode 100644 index 00000000..90afb89d --- /dev/null +++ b/docs/api/XCEngine/UI/Input/UIInputDispatcher/UIInputDispatcher.md @@ -0,0 +1,45 @@ +# UIInputDispatcher + +**命名空间**: `XCEngine::UI` + +**类型**: `structs + class` + +**头文件**: `XCEngine/UI/Input/UIInputDispatcher.h` + +**描述**: XCUI 输入分发总协调器，负责焦点转移、active path 生命周期、shortcut 匹配、shortcut suppression 和最终的元素路由。 +## 概览 + +`UIInputDispatcher.h` 当前公开三类声明： + +| 声明 | 角色 | +|------|------| +| `UIInputDispatcherOptions` | pointer down 是否转移 focus、是否启动 active path，以及用于转移 focus 的按钮。 | +| `UIInputDispatchSummary` | 一次 dispatch 的 focus 变化、shortcut 结果和 routing 结果汇总。 | +| `UIInputDispatcher` | 分发入口，持有 `UIFocusController`、`UIShortcutRegistry` 与 `UIShortcutContext`。 | + +## 当前实现行为 + +- pointer down 触发的 focus 转移要求同时满足： + - `pointerDownChangesFocus == true` + - 事件类型是 `PointerButtonDown` + - `event.pointerButton == focusTransferButton` + - `hoveredPath` 非空 +- pointer down 启动 active path 时，如果当前存在 pointer capture，会优先把 capture path 设为 active path；否则使用 hovered path。 +- 键盘激活键当前只认 `Enter` 和 `Space`；`KeyDown` 时会把 focused path 设为 active path，配套 `KeyUp` 会清空 active path。 +- shortcut 匹配发生在元素路由之前；如果命中且未被 suppression，当前会直接返回 `shortcutHandled = true`，不再进入 `UIInputRouter`。 +- `textInputActive == true` 时，命中的 shortcut 会被标成 `shortcutSuppressed = true`，随后事件继续进入正常路由。 +- `FinalizeDispatch(...)` 当前只负责在 pointer button up 或激活键 key up 之后清空 active path，没有其他尾处理。 + +## 测试与调用链 + +- `tests/Input/test_xcui_input_dispatcher.cpp` 与 `tests/UI/Core/unit/test_ui_input_dispatcher.cpp` 当前覆盖 pointer down 转焦点、active path 生命周期、pointer capture 路由、键盘激活和 shortcut 先于 routing 的行为。 +- `tests/UI/Core/unit/test_ui_shortcut_scope.cpp` 当前覆盖 text-input suppression 和 command-scope shortcut resolution。 +- `engine/src/UI/Runtime/UIScreenDocumentHost.cpp` 当前把 hovered path、shortcut context 和元素 handler 全部接到这里，作为 runtime XCUI 输入入口。 + +## 相关文档 + +- [Input](../Input.md) +- [UIInputPath](../UIInputPath/UIInputPath.md) +- [UIFocusController](../UIFocusController/UIFocusController.md) +- [UIInputRouter](../UIInputRouter/UIInputRouter.md) +- [UIShortcutRegistry](../UIShortcutRegistry/UIShortcutRegistry.md) diff --git a/docs/api/XCEngine/UI/Input/UIInputPath/UIInputPath.md b/docs/api/XCEngine/UI/Input/UIInputPath/UIInputPath.md new file mode 100644 index 00000000..e93a4740 --- /dev/null +++ b/docs/api/XCEngine/UI/Input/UIInputPath/UIInputPath.md @@ -0,0 +1,47 @@ +# UIInputPath + +**命名空间**: `XCEngine::UI` + +**类型**: `struct + free functions` + +**头文件**: `XCEngine/UI/Input/UIInputPath.h` + +**描述**: XCUI 输入命中路径模型，使用一条从根到目标元素的 `UIElementId` 序列表示 hover、focus、capture 和 popup surface 等输入归属链。 +## 概览 + +`UIInputPath` 当前是 XCUI 输入层最基础的路径值对象： + +- `elements` + - 按根到目标的顺序保存元素 id +- `Root()` + - 返回首元素，空路径时返回 `0` +- `Target()` + - 返回末元素，空路径时返回 `0` +- `Contains(...)` + - 判定某个元素是否出现在路径里 + +配套 free function 提供： + +- `operator==` / `operator!=` +- `GetUIInputPathCommonPrefixLength(...)` +- `BuildUIInputPathSuffix(...)` + +## 当前实现行为 + +- `Contains(...)` 当前通过线性扫描 `elements` 完成，不维护额外索引。 +- `Root()` / `Target()` 在空路径上都返回 `0`，这与 `UIElementId == 0` 作为“无目标”的惯例保持一致。 +- `GetUIInputPathCommonPrefixLength(...)` 逐项比较前缀，常用于 focus 切换时切出 lost/gained suffix。 +- `BuildUIInputPathSuffix(...)` 在 `startIndex >= path.Size()` 时返回空路径，否则拷贝后缀区间。 + +## 测试与调用链 + +- `tests/Input/test_xcui_input_dispatcher.cpp` 当前直接用这组 helper 验证 focus lost/gained suffix 与 capture/hover/focus 路由。 +- `engine/src/UI/Runtime/UIScreenDocumentHost.cpp` 当前大量构造和消费 `UIInputPath`，包括 hovered path、focus path、shortcut command scope 和 popup surface path。 +- `engine/src/UI/Widgets/UIPopupOverlayModel.cpp` 当前通过公共前缀与路径包含关系做 popup 层级裁剪与 dismiss 判定。 + +## 相关文档 + +- [Input](../Input.md) +- [UIFocusController](../UIFocusController/UIFocusController.md) +- [UIInputRouter](../UIInputRouter/UIInputRouter.md) +- [UIShortcutRegistry](../UIShortcutRegistry/UIShortcutRegistry.md) diff --git a/docs/api/XCEngine/UI/Input/UIInputRouter/UIInputRouter.md b/docs/api/XCEngine/UI/Input/UIInputRouter/UIInputRouter.md new file mode 100644 index 00000000..e3046209 --- /dev/null +++ b/docs/api/XCEngine/UI/Input/UIInputRouter/UIInputRouter.md @@ -0,0 +1,48 @@ +# UIInputRouter + +**命名空间**: `XCEngine::UI` + +**类型**: `enums + structs + class` + +**头文件**: `XCEngine/UI/Input/UIInputRouter.h` + +**描述**: XCUI 事件路由规划与分发器，负责根据 hovered/focused/captured path 构建 capture-target-bubble 执行计划，并驱动调用侧 handler。 +## 概览 + +`UIInputRouter.h` 当前公开的核心声明有： + +| 声明 | 角色 | +|------|------| +| `UIInputRoutingPhase` | `Capture` / `Target` / `Bubble` 三段式路由阶段。 | +| `UIInputTargetKind` | 当前命中的目标来源：`Hovered`、`Focused`、`Captured`。 | +| `UIInputRouteContext` | hovered/focused/capture 三条路径输入。 | +| `UIInputRoutingStep` | 单个路由步骤。 | +| `UIInputRoutingPlan` | 一次事件的完整路由计划。 | +| `UIInputDispatchRequest` | 传给 handler 的单步请求。 | +| `UIInputDispatchDecision` | handler 的 handled / stopPropagation 决策。 | +| `UIInputDispatchResult` | 整体分发结果。 | +| `UIInputRouter` | 路由规划与驱动入口。 | + +## 当前实现行为 + +- 指针事件当前优先走 `capturePath`；只有在没有 capture 时，才退回 `hoveredPath`。 +- 键盘事件与 `FocusGained` / `FocusLost` 当前统一走 `focusedPath`。 +- capture-target-bubble 计划的展开顺序是： + - capture: 根到 target 的祖先链 + - target: 目标元素自身 + - bubble: 从目标父节点逆序回到根 +- `Dispatch(...)` 每步都会调用一次 handler，把当前 `phase`、`targetKind`、`elementId` 和 `isTargetElement` 打包进 `UIInputDispatchRequest`。 +- `handled` 会对所有步骤做 OR 聚合；一旦 handler 返回 `stopPropagation = true`，后续步骤立即停止。 + +## 测试与调用链 + +- `tests/Input/test_xcui_input_dispatcher.cpp` 当前验证 pointer capture 会覆盖 hovered path，键盘事件按 capture-target-bubble 顺序路由 focused path。 +- `UIInputDispatcher` 当前在 shortcut 判定之后，直接调用 `UIInputRouter::Dispatch(...)` 进入元素级事件分发。 +- `UIScreenDocumentHost` 当前通过 handler 回调把路由步骤映射到具体 widget / screen document 节点。 + +## 相关文档 + +- [Input](../Input.md) +- [UIInputPath](../UIInputPath/UIInputPath.md) +- [UIFocusController](../UIFocusController/UIFocusController.md) +- [UIInputDispatcher](../UIInputDispatcher/UIInputDispatcher.md) diff --git a/docs/api/XCEngine/UI/Input/UIShortcutRegistry/UIShortcutRegistry.md b/docs/api/XCEngine/UI/Input/UIShortcutRegistry/UIShortcutRegistry.md new file mode 100644 index 00000000..c6e40982 --- /dev/null +++ b/docs/api/XCEngine/UI/Input/UIShortcutRegistry/UIShortcutRegistry.md @@ -0,0 +1,48 @@ +# UIShortcutRegistry + +**命名空间**: `XCEngine::UI` + +**类型**: `enums + structs + class` + +**头文件**: `XCEngine/UI/Input/UIShortcutRegistry.h` + +**描述**: XCUI 快捷键绑定注册表，负责保存快捷键 chord、作用域和 owner，并按当前 shortcut context 解析最佳匹配。 +## 概览 + +`UIShortcutRegistry.h` 当前把快捷键系统拆成以下声明： + +| 声明 | 角色 | +|------|------| +| `UIShortcutScope` | `Global` / `Window` / `Panel` / `Widget` 四级作用域。 | +| `UIShortcutChord` | `keyCode + modifiers + allowRepeat`。 | +| `UIShortcutBinding` | 完整绑定项，包含 scope、ownerId、triggerEventType 和 `commandId`。 | +| `UIShortcutScopeChain` | 当前 command scope 的路径与 window/panel/widget owner。 | +| `UIShortcutContext` | focused/active/hovered path、command scope 和 `textInputActive` 状态。 | +| `UIShortcutMatch` | 匹配结果。 | +| `UIShortcutRegistry` | 绑定注册、移除、清空和匹配入口。 | + +## 当前实现行为 + +- `RegisterBinding(...)` 会为 `bindingId == 0` 的绑定自动分配单调递增 id；如果调用侧显式传入更大的 id，`m_nextBindingId` 也会被推进。 +- `Clear()` 会同时清空绑定并把 `m_nextBindingId` 重置回 `1`。 +- 匹配条件当前包括： + - `triggerEventType` 一致 + - `keyCode` 一致 + - modifiers 完全一致 + - 如果 `allowRepeat == false`，则 `event.repeat` 不能为真 +- 非 `Global` 绑定要求 `ownerId != 0`；否则当前视为 inactive。 +- 作用域 owner 解析优先使用 `commandScope.windowId/panelId/widgetId`，只有拿不到显式 owner 时，才退回到 `commandScope.path` 或 primary shortcut path。 +- 多个绑定同时命中时，优先级是 `Widget > Panel > Window > Global`；同优先级下，`bindingId` 更大的新绑定获胜。 + +## 测试与调用链 + +- `tests/Input/test_xcui_input_dispatcher.cpp` 当前验证 registry 会优先选择最具体作用域，其次选择更新注册的 binding。 +- `tests/UI/Core/unit/test_ui_shortcut_scope.cpp` 当前覆盖 command scope 优先于 active path、panel/window/global 作用域回退，以及 text-input 活跃时 shortcut suppression。 +- `engine/src/UI/Runtime/UIScreenDocumentHost.cpp` 和 `new_editor/src/Core/UIEditorShortcutManager.cpp` 当前都直接消费这套 binding/context/match 数据。 + +## 相关文档 + +- [Input](../Input.md) +- [UIInputPath](../UIInputPath/UIInputPath.md) +- [UIInputDispatcher](../UIInputDispatcher/UIInputDispatcher.md) +- [UIInputRouter](../UIInputRouter/UIInputRouter.md) diff --git a/docs/api/XCEngine/UI/Layout/Layout.md b/docs/api/XCEngine/UI/Layout/Layout.md new file mode 100644 index 00000000..960b672b --- /dev/null +++ b/docs/api/XCEngine/UI/Layout/Layout.md @@ -0,0 +1,37 @@ +# Layout + +**命名空间**: `XCEngine::UI` + +**类型**: `submodule` + +**头文件目录**: `engine/include/XCEngine/UI/Layout/` + +**描述**: XCUI 当前的布局基础层，提供 header-only 的尺寸约束、stack / overlay 布局算法，以及 splitter / tab-strip 这类 runtime 与 editor shell 共用的专用布局 helper。 + +## 当前范围 + +- [LayoutTypes](LayoutTypes/LayoutTypes.md): 基础枚举、约束类型、layout item 与结果结构。 +- [LayoutEngine](LayoutEngine/LayoutEngine.md): stack / overlay 的 measure 与 arrange 算法。 +- [UISplitterLayout](UISplitterLayout/UISplitterLayout.md): 双栏 splitter 的 ratio clamp、矩形分割与指针位置换算。 +- [UITabStripLayout](UITabStripLayout/UITabStripLayout.md): tab header 宽度预算、整体 measure 与 header/content 布局。 + +## 当前调用链 + +- `engine/src/UI/Runtime/UIScreenDocumentHost.cpp` 当前直接消费这组 helper： + - `MeasureUITabStrip(...)` + - `ArrangeUITabStrip(...)` + - `ArrangeUISplitter(...)` + - `MeasureStackLayout(...)` + - `ArrangeStackLayout(...)` +- `tests/UI/Core/unit/test_layout_engine.cpp` +- `tests/UI/Core/unit/test_ui_splitter_layout.cpp` +- `tests/UI/Core/unit/test_ui_splitter_interaction.cpp` +- `tests/UI/Core/unit/test_ui_tab_strip_layout.cpp` +- `tests/Core/Math/test_ui_layout.cpp` + +## 相关文档 + +- [UI](../UI.md) +- [Core](../Core/Core.md) +- [Runtime](../Runtime/Runtime.md) +- [Widgets](../Widgets/Widgets.md) diff --git a/docs/api/XCEngine/UI/Layout/LayoutEngine/LayoutEngine.md b/docs/api/XCEngine/UI/Layout/LayoutEngine/LayoutEngine.md new file mode 100644 index 00000000..b911094f --- /dev/null +++ b/docs/api/XCEngine/UI/Layout/LayoutEngine/LayoutEngine.md @@ -0,0 +1,73 @@ +# LayoutEngine + +**命名空间**: `XCEngine::UI::Layout` + +**类型**: `struct + inline functions` + +**头文件**: `XCEngine/UI/Layout/LayoutEngine.h` + +**描述**: `LayoutEngine.h` 提供 XCUI 当前通用的 header-only 布局算法。它不维护 retained tree，也不负责内容测量，只消费调用方给出的 `UILayoutItem` 输入，返回 stack / overlay 的 desired size 与 child rect。 + +## 概览 + +这份头文件当前公开以下布局入口： + +| 声明 | 角色 | +|------|------| +| `UILayoutPassResult` | 一次 layout pass 的总结果，包含 `desiredSize` 与按输入顺序保存的 `children`。 | +| `MeasureStackLayout(...)` | 计算 stack 容器的 desired size 与每个 child 的 measured size。 | +| `ArrangeStackLayout(...)` | 在给定 `bounds` 内排布 stack child，并返回最终矩形。 | +| `MeasureOverlayLayout(...)` | 计算 overlay 容器的 desired size 与 child measured size。 | +| `ArrangeOverlayLayout(...)` | 在同一矩形上叠放 child，并按 alignment / stretch 计算最终矩形。 | + +## 当前实现行为 + +- 这组 API 全部是 inline helper；当前没有 `.cpp`、缓存层或隐藏状态。 +- `MeasureStackLayout(...)` 的当前行为： + - 先用 `options.padding` 对可用最大尺寸做 deflate。 + - 跳过 `visible == false` 的 child。 + - 每个可见 child 都先按 `desiredContentSize + width/height/min/max` 求基础 measured size。 + - 主轴累加 child 尺寸、margin 和相邻 `spacing`。 + - 交叉轴取所有 child 的最大尺寸，再加上各自的 cross margin。 + - 最终 `desiredSize` 会再被 clamp 到 `constraints.minSize / maxSize`。 +- `ArrangeStackLayout(...)` 的当前行为： + - 先调用一次 `MeasureStackLayout(...)`，但使用 `UILayoutConstraints::Bounded(bounds.width, bounds.height)`。 + - 计算所有可见 child 的基础主轴占用，以及 stretch child 的总权重。 + - 剩余主轴空间只会分配给 `GetMainLength(...).IsStretch()` 为真的 child，按权重线性分摊。 + - cross-axis 的 stretch 既可能来自 `width/height == Stretch`，也可能来自 `horizontalAlignment / verticalAlignment == Stretch`。 + - 不可见 child 会保留 `visible = false`，并把 `arrangedRect` 置为零矩形。 +- `MeasureOverlayLayout(...)` 的当前行为： + - 仍然跳过不可见 child。 + - 容器 desired width / height 取所有 child measured size 加 margin 后的最大值，而不是求和。 + - 最终结果同样会尊重 `constraints.minSize / maxSize`。 +- `ArrangeOverlayLayout(...)` 的当前行为： + - 先测量，再在同一个 `innerBounds` 内为每个 child 单独算对齐。 + - `width.IsStretch()` 或 `horizontalAlignment == Stretch` 时，child 宽度会扩展到可用宽度。 + - `height.IsStretch()` 或 `verticalAlignment == Stretch` 时，child 高度会扩展到可用高度。 + - `Center` / `End` 通过 `ComputeAlignmentOffset(...)` 计算偏移；`Start` 与 `Stretch` 当前都返回 `0` 偏移。 +- 当前实现没有做像素对齐、baseline 布局或文本重测；`desiredContentSize` 完全由调用方负责。 + +## 当前调用链 + +- `engine/src/UI/Runtime/UIScreenDocumentHost.cpp` + - 在 measure 阶段用 `MeasureStackLayout(...)` 计算一般容器与 scroll-view 内容尺寸。 + - 在 arrange 阶段用 `ArrangeStackLayout(...)` 计算普通容器与滚动内容的 child rect。 +- `tests/UI/Core/unit/test_layout_engine.cpp` 当前覆盖： + - 横向 stack 对 `spacing + padding + cross extent` 的累积。 + - stretch child 分配剩余主轴空间。 + - 纵向 stack 的 cross-axis stretch。 + - overlay 的 center / stretch。 + - overlay 对 `min/max + available constraints` 的约束。 +- `tests/Core/Math/test_ui_layout.cpp` 当前保留同一组旧路径测试锚点。 + +## 生命周期与线程语义 + +- 这组 helper 不持有外部资源，也不保留上次调用状态。 +- 线程安全只取决于调用方是否并发读写同一批 `items` / 输出容器；函数本身没有额外共享状态。 + +## 相关文档 + +- [Layout](../Layout.md) +- [LayoutTypes](../LayoutTypes/LayoutTypes.md) +- [UISplitterLayout](../UISplitterLayout/UISplitterLayout.md) +- [UITabStripLayout](../UITabStripLayout/UITabStripLayout.md) diff --git a/docs/api/XCEngine/UI/Layout/LayoutTypes/LayoutTypes.md b/docs/api/XCEngine/UI/Layout/LayoutTypes/LayoutTypes.md new file mode 100644 index 00000000..ac39c8ec --- /dev/null +++ b/docs/api/XCEngine/UI/Layout/LayoutTypes/LayoutTypes.md @@ -0,0 +1,58 @@ +# LayoutTypes + +**命名空间**: `XCEngine::UI::Layout` + +**类型**: `enums + structs + inline helpers` + +**头文件**: `XCEngine/UI/Layout/LayoutTypes.h` + +**描述**: `LayoutTypes.h` 定义 XCUI 布局层最底部的值类型契约，包括 axis / alignment / length 枚举、约束与边距结构，以及 stack / overlay / child result 这类被其它 layout helper 直接消费的 POD。 + +## 概览 + +这份头文件当前公开以下声明： + +| 声明 | 角色 | +|------|------| +| `GetUnboundedLayoutExtent()` | 返回“无上界”布局尺寸，当前实现为 `+infinity`。 | +| `UILayoutAxis` | 指定主轴方向，只有 `Horizontal` 与 `Vertical`。 | +| `UILayoutLengthUnit` | 长度单位枚举，区分 `Auto`、`Pixels` 与 `Stretch`。 | +| `UILayoutAlignment` | 布局对齐方式，区分 `Start`、`Center`、`End` 与 `Stretch`。 | +| `UILayoutLength` | 单轴长度描述，提供 `Auto()`、`Pixels(...)`、`Stretch(...)` 与 `IsStretch()`。 | +| `UILayoutThickness` | 四边距 / padding 描述，提供 `Uniform(...)`、`Symmetric(...)`、`Horizontal()` 与 `Vertical()`。 | +| `UILayoutConstraints` | 最小 / 最大尺寸约束，提供 `Unbounded()`、`Bounded(...)` 与 `Tight(...)`。 | +| `UILayoutItem` | 单个 child 的布局输入，包括 desired size、min/max、margin、alignment 与 visible。 | +| `UIStackLayoutOptions` | stack 布局选项，包含 `axis`、`spacing` 与 `padding`。 | +| `UIOverlayLayoutOptions` | overlay 布局选项，当前只包含 `padding`。 | +| `UILayoutChildResult` | 单个 child 的测量结果与最终矩形。 | + +## 当前实现行为 + +- `GetUnboundedLayoutExtent()` 当前直接返回 `std::numeric_limits::infinity()`；布局层用它表示“没有 max 限制”。 +- `UILayoutLength::Pixels(...)` 与 `UILayoutLength::Stretch(...)` 都会把负值 clamp 到 `0.0f`，因此当前文档不能把负长度写成有效输入。 +- `UILayoutLength::IsStretch()` 只有在 `unit == Stretch` 且 `value > 0.0f` 时才返回 `true`；`Stretch(0.0f)` 当前不会参与剩余空间分配。 +- `UILayoutThickness` 的构造函数和 `Uniform(...)` / `Symmetric(...)` helper 都会把四个边 clamp 到非负值；`Horizontal()` 与 `Vertical()` 只是左右或上下的求和。 +- `UILayoutConstraints::Bounded(...)` 只设置 `maxSize`；`minSize` 仍保持 `0`。`Tight(...)` 则在 `Bounded(...)` 基础上把 `minSize` 也设成同一个尺寸。 +- `UILayoutItem` 是纯输入结构： + - `desiredContentSize` 表示调用方已经测量出的内容尺寸。 + - `width` / `height` 决定当前轴是自动、固定像素还是 stretch。 + - `visible == false` 时，后续 layout helper 会跳过测量与排布。 +- `UILayoutChildResult` 默认产出零尺寸；`LayoutEngine.h` 当前会把不可见 child 的 `arrangedRect` 置成 `(0, 0, 0, 0)`。 + +## 生命周期与线程语义 + +- 这份头文件当前全部是值类型和 inline helper，不持有外部资源，也不维护全局状态。 +- 只要调用方自己管理容器与并发访问，这些声明本身没有额外的线程亲和性要求。 + +## 测试与调用链 + +- `engine/src/UI/Runtime/UIScreenDocumentHost.cpp` 当前把 `UILayoutItem`、`UIStackLayoutOptions`、`UISplitterConstraints` 与 `UITabStripMetrics` 这类值类型作为 retained-mode 运行时布局输入。 +- `tests/UI/Core/unit/test_layout_engine.cpp` 覆盖 stack / overlay 的核心输入组合。 +- `tests/UI/Core/unit/test_ui_splitter_layout.cpp` 与 `tests/UI/Core/unit/test_ui_tab_strip_layout.cpp` 覆盖 splitter / tab-strip 的值类型组合和边界条件。 + +## 相关文档 + +- [Layout](../Layout.md) +- [LayoutEngine](../LayoutEngine/LayoutEngine.md) +- [UISplitterLayout](../UISplitterLayout/UISplitterLayout.md) +- [UITabStripLayout](../UITabStripLayout/UITabStripLayout.md) diff --git a/docs/api/XCEngine/UI/Layout/UISplitterLayout/UISplitterLayout.md b/docs/api/XCEngine/UI/Layout/UISplitterLayout/UISplitterLayout.md new file mode 100644 index 00000000..dc3addda --- /dev/null +++ b/docs/api/XCEngine/UI/Layout/UISplitterLayout/UISplitterLayout.md @@ -0,0 +1,83 @@ +# UISplitterLayout + +**命名空间**: `XCEngine::UI::Layout` + +**类型**: `structs + inline functions` + +**头文件**: `XCEngine/UI/Layout/UISplitterLayout.h` + +**描述**: `UISplitterLayout.h` 定义 XCUI splitter 的纯布局层契约。它负责两块内容区与 divider handle 的尺寸约束、ratio clamp、矩形拆分，以及把指针位置换算成新的 splitter ratio。 + +## 概览 + +这份头文件当前公开以下声明： + +| 声明 | 角色 | +|------|------| +| `UISplitterMetrics` | handle 的视觉厚度与 hit 测试厚度配置。 | +| `UISplitterConstraints` | primary / secondary 两侧的最小与最大主轴尺寸限制。 | +| `UISplitterLayoutOptions` | 直接布局时使用的 axis、ratio、handleThickness 与最小尺寸输入。 | +| `UISplitterLayoutResult` | splitter 排布结果，包含 primary / handle / secondary rect 与最终 ratio。 | +| `MeasureSplitterDesiredSize(...)` | 根据两侧内容尺寸和 handle 厚度计算 splitter 容器 desired size。 | +| `ClampSplitterRatio(...)` | 将请求 ratio clamp 到当前可用主轴尺寸与约束范围内。 | +| `ArrangeSplitterLayout(...)` | 用 `UISplitterLayoutOptions` 直接拆出三块矩形。 | +| `ResolveSplitterRatioFromPointerPosition(...)` | 根据指针主轴位置反推出新的 ratio。 | +| `ArrangeUISplitter(...)` | 结合 `UISplitterConstraints + UISplitterMetrics` 的高层入口。 | + +## 当前实现行为 + +- 这组 API 当前全部是 inline helper；没有独立 `.cpp` 或内部缓存。 +- `UISplitterMetrics` 里： + - `thickness` 决定真正参与布局的 handle 厚度。 + - `hitThickness` 不直接参与矩形拆分，而是给 widget 层扩展 hit rect 用。 +- `MeasureSplitterDesiredSize(...)` 会先把 `handleThickness` clamp 到非负值，再把它加到主轴尺寸上；交叉轴只取两侧内容中的最大值。 +- `ClampSplitterRatio(const UISplitterLayoutOptions&, float)` 的当前行为： + - handle 厚度会被 clamp 到 `totalMainExtent` 以内。 + - 当去掉 handle 后的 `usableExtent <= 0` 时直接回退到 `0.5f`。 + - ratio 会同时受 `minPrimaryExtent` 与 `minSecondaryExtent` 约束。 + - 如果两侧最小值互相冲突，当前实现会回退成 `[0, usableExtent]` 全范围。 +- `ClampSplitterRatio(axis, requestedRatio, totalMainExtent, constraints, metrics)` 比上一个重载多处理： + - `primaryMax` + - `secondaryMax` + - 从 secondary 约束反推 primary 可用区间 +- `ArrangeSplitterLayout(...)` 的当前行为： + - 先 clamp ratio，再计算 primary / secondary 可用尺寸。 + - handle 始终放在两侧矩形之间。 + - 返回的 `primaryExtent` 与 `secondaryExtent` 都是不含 handle 的 usable extent。 + - `splitRatio` 当前等于 `resolvedRatio`。 +- `ResolveSplitterRatioFromPointerPosition(...)` 会把指针位置视为拖到 handle 中心，再复用 `ClampSplitterRatio(...)` 做最终约束。 +- `ArrangeUISplitter(...)` 是当前 runtime 最常用入口： + - 先根据 `constraints + metrics` 计算最终 ratio。 + - 再复用 `ArrangeSplitterLayout(...)` 生成三块矩形。 + - 结果里的 `splitRatio` 与 `resolvedRatio` 都会被写成最终 clamp 后的 ratio。 + +## 与交互层的边界 + +- 这份头文件只负责布局，不负责 hover、hit test 或拖拽状态机。 +- `tests/UI/Core/unit/test_ui_splitter_interaction.cpp` 当前证明：handle hit rect 扩张、拖拽开始 / 更新 / 结束逻辑在 widget 层实现，并通过这里返回的 `handleRect` 与 ratio helper 连接起来。 + +## 测试与调用链 + +- `engine/src/UI/Runtime/UIScreenDocumentHost.cpp` + - 在 splitter 容器 arrange 阶段直接调用 `ArrangeUISplitter(...)`。 + - 随后把 `arranged.handleRect` 交给 widget 层扩展 hit rect。 +- `tests/UI/Core/unit/test_ui_splitter_layout.cpp` 当前覆盖： + - primary minimum clamp + - secondary minimum clamp + - 横向 splitter 三块矩形拆分 +- `tests/UI/Core/unit/test_ui_splitter_interaction.cpp` 当前覆盖： + - expanded hit rect + - handle hit test + - 拖拽过程中 ratio 与尺寸约束的联动 + +## 生命周期与线程语义 + +- 所有类型都是值类型，函数不持有外部资源。 +- 调用方可以把结果结构直接缓存到自己的 UI 状态中；这份头文件本身没有生命周期管理职责。 + +## 相关文档 + +- [Layout](../Layout.md) +- [LayoutTypes](../LayoutTypes/LayoutTypes.md) +- [LayoutEngine](../LayoutEngine/LayoutEngine.md) +- [Widgets](../../Widgets/Widgets.md) diff --git a/docs/api/XCEngine/UI/Layout/UITabStripLayout/UITabStripLayout.md b/docs/api/XCEngine/UI/Layout/UITabStripLayout/UITabStripLayout.md new file mode 100644 index 00000000..bbd704aa --- /dev/null +++ b/docs/api/XCEngine/UI/Layout/UITabStripLayout/UITabStripLayout.md @@ -0,0 +1,63 @@ +# UITabStripLayout + +**命名空间**: `XCEngine::UI::Layout` + +**类型**: `structs + inline functions` + +**头文件**: `XCEngine/UI/Layout/UITabStripLayout.h` + +**描述**: `UITabStripLayout.h` 提供 XCUI tab-strip 的纯布局 helper。它负责 header label 宽度预算、整个 tab-strip 的 desired / minimum size 计算，以及 header 区和 content 区的最终矩形排布。 + +## 概览 + +这份头文件当前公开以下声明： + +| 声明 | 角色 | +|------|------| +| `UITabStripMetrics` | header 高度、单 tab 最小宽度、水平 padding 与 tab gap。 | +| `UITabStripMeasureItem` | 单个 tab 的 measure 输入，包括 label 宽度、desired content 和 minimum content。 | +| `UITabStripMeasureResult` | tab-strip 的 desired size 与 minimum size。 | +| `UITabStripLayoutResult` | headerRect、contentRect 和每个 tab header rect 的布局结果。 | +| `MeasureUITabStripHeaderWidth(...)` | 计算单个 tab header 的目标宽度。 | +| `MeasureUITabStrip(...)` | 计算整个 tab-strip 的 desired / minimum size。 | +| `ArrangeUITabStrip(...)` | 根据 header 宽度预算与 bounds 生成 header/content 布局。 | + +## 当前实现行为 + +- `MeasureUITabStripHeaderWidth(...)` 当前返回： + - `max(tabMinWidth, max(labelWidth, 0) + max(tabHorizontalPadding, 0) * 2)` + - 也就是说负 `labelWidth` 或负 padding 都会先被 clamp 到 `0` +- `MeasureUITabStrip(...)` 的当前行为： + - `desiredHeaderWidth` 是所有 tab header 目标宽度之和，再加相邻 gap。 + - `minimumHeaderWidth` 不看 label 宽度，而是按每个 tab 至少 `tabMinWidth` 预算。 + - content 区的 desired / minimum 尺寸都取所有 item 中的最大值，而不是求和。 + - `items.empty()` 时，headerHeight 会回落为 `0.0f`，最终 desired / minimum size 都是零尺寸。 +- `ArrangeUITabStrip(...)` 的当前行为： + - `headerRect` 总是在顶部，`contentRect` 占用剩余高度。 + - 非空 tab 集合时，header 高度会被 clamp 到 `min(metrics.headerHeight, bounds.height)`。 + - 当所有 header 期望总宽度大于可用宽度时，会按比例缩放每个 tab 宽度。 + - 当总期望宽度为 `0` 时，会把可用宽度平均分给每个 tab。 + - gap 会先从总宽度里扣掉，所以真正可分配的是 `bounds.width - totalGapWidth`。 +- 当前实现不处理“选中 tab 扩张”“滚动 tab bar”或“多行 header”；它只是单行 header + 单个 content rect 的纯几何布局 helper。 + +## 当前调用链 + +- `engine/src/UI/Runtime/UIScreenDocumentHost.cpp` + - 在 measure 阶段把每个 child 的内容尺寸和 tab label 文本宽度组装成 `UITabStripMeasureItem`，然后调用 `MeasureUITabStrip(...)`。 + - 在 arrange 阶段先用 `MeasureUITabStripHeaderWidth(...)` 生成每个 tab 的 header 预算，再调用 `ArrangeUITabStrip(...)`。 + - runtime host 会把结果中的 `contentRect` 用作 tab child 的统一内容区域，并把 `tabHeaderRects` 分发给各个 tab。 +- `tests/UI/Core/unit/test_ui_tab_strip_layout.cpp` 当前覆盖： + - tallest content / widest header budget 的 measure 语义 + - 空 tab 集合返回零尺寸 + - 当 header 总宽超出可用宽度时按比例缩放，同时保留 content area + +## 生命周期与线程语义 + +- 所有类型都是值类型，函数不持有外部资源。 +- tab 选中态、可见性和交互状态不在这里存储，仍由 runtime 或 widget 层自行维护。 + +## 相关文档 + +- [Layout](../Layout.md) +- [LayoutTypes](../LayoutTypes/LayoutTypes.md) +- [LayoutEngine](../LayoutEngine/LayoutEngine.md) diff --git a/docs/api/XCEngine/UI/Runtime/Runtime.md b/docs/api/XCEngine/UI/Runtime/Runtime.md new file mode 100644 index 00000000..8d1ccbeb --- /dev/null +++ b/docs/api/XCEngine/UI/Runtime/Runtime.md @@ -0,0 +1,29 @@ +# Runtime + +**命名空间**: `XCEngine::UI` + +**类型**: `submodule` + +**头文件目录**: `engine/include/XCEngine/UI/Runtime/` + +**描述**: XCUI runtime 层，负责 screen document host、screen player、screen stack controller、screen types 与 `UISystem`。 + +## 当前范围 + +- [UISceneRuntimeContext](UISceneRuntimeContext/UISceneRuntimeContext.md) + - scene runtime 持有的 XCUI 运行时上下文与输入队列。 +- [UIScreenDocumentHost](UIScreenDocumentHost/UIScreenDocumentHost.md) + - 文档编译、运行时布局、输入分发和 draw-data 生成宿主。 +- [UIScreenPlayer](UIScreenPlayer/UIScreenPlayer.md) + - 单个 screen 资源的加载、逐帧更新与错误状态封装。 +- [UIScreenStackController](UIScreenStackController/UIScreenStackController.md) + - 菜单、模态和 HUD 层的高层压栈接口。 +- [UIScreenTypes](UIScreenTypes/UIScreenTypes.md) + - runtime screen 资产、帧输入/输出和 layer 描述数据。 +- [UISystem](UISystem/UISystem.md) + - 多 layer player 的呈现、输入路由与 frame 聚合入口。 + +## 相关文档 + +- [UI](../UI.md) +- [Resources UI](../../Resources/UI/UI.md) diff --git a/docs/api/XCEngine/UI/Runtime/UISceneRuntimeContext/UISceneRuntimeContext.md b/docs/api/XCEngine/UI/Runtime/UISceneRuntimeContext/UISceneRuntimeContext.md new file mode 100644 index 00000000..4ca60f02 --- /dev/null +++ b/docs/api/XCEngine/UI/Runtime/UISceneRuntimeContext/UISceneRuntimeContext.md @@ -0,0 +1,52 @@ +# UISceneRuntimeContext + +**命名空间**: `XCEngine::UI::Runtime` + +**类型**: `class` + +**头文件**: `XCEngine/UI/Runtime/UISceneRuntimeContext.h` + +**源文件**: `engine/src/UI/Runtime/UISceneRuntimeContext.cpp` + +**描述**: scene runtime 持有的 XCUI 上下文，内部自带一个 `UIDocumentScreenHost`、一个 `UISystem` 和一个 `UIScreenStackController`，并维护待投递输入队列与 frame index。 + +## 概览 + +公开接口分成三组： + +- 访问内部子系统 + - `GetSystem()` + - `GetStackController()` + - `GetLastFrame()` / `ConsumeLastFrame()` +- 配置待处理 frame 输入 + - `SetViewportRect(...)` + - `SetFocused(...)` + - `QueueInputEvent(...)` + - `ClearQueuedInputEvents()` +- 运行时控制 + - `Reset()` + - `Update(double deltaTimeSeconds)` + +## 当前实现行为 + +- 构造时会按固定顺序初始化 `m_documentHost -> m_system -> m_stackController`，因此默认就是一个可直接使用的完整 UI runtime。 +- `Update(...)` 会把 `deltaTimeSeconds` 和递增的 `frameIndex` 写进 `m_pendingFrameInput`，然后直接调用 `m_system.Update(...)`。 +- `m_nextFrameIndex` 当前从 `1` 开始；每次 `Update(...)` 后自增。 +- `Update(...)` 完成后会清空 `m_pendingFrameInput.events`，所以排队输入默认只投递一帧。 +- `Reset()` 会清空 layer/players、重置待处理输入和 frame index；viewport 与 focused 状态也会回到默认值。 + +## 调用链与测试 + +- `engine/src/Scene/SceneRuntime.cpp` 当前把它作为 scene 层 UI runtime 的直接成员来驱动。 +- `tests/Scene/test_scene_runtime.cpp` 当前覆盖： + - 每帧更新会推进 UI runtime 并清空 queued events + - `Stop()` / reset 后清空 UI 状态 + - viewport 跨帧保留、停止后重置 + - 多 layer 输入只路由到顶层可交互呈现层 + +## 相关文档 + +- [Runtime](../Runtime.md) +- [UIScreenDocumentHost](../UIScreenDocumentHost/UIScreenDocumentHost.md) +- [UIScreenStackController](../UIScreenStackController/UIScreenStackController.md) +- [UISystem](../UISystem/UISystem.md) diff --git a/docs/api/XCEngine/UI/Runtime/UIScreenDocumentHost/UIScreenDocumentHost.md b/docs/api/XCEngine/UI/Runtime/UIScreenDocumentHost/UIScreenDocumentHost.md new file mode 100644 index 00000000..21bacf54 --- /dev/null +++ b/docs/api/XCEngine/UI/Runtime/UIScreenDocumentHost/UIScreenDocumentHost.md @@ -0,0 +1,60 @@ +# UIScreenDocumentHost + +**命名空间**: `XCEngine::UI::Runtime` + +**类型**: `interface + class + structs` + +**头文件**: `XCEngine/UI/Runtime/UIScreenDocumentHost.h` + +**源文件**: `engine/src/UI/Runtime/UIScreenDocumentHost.cpp` + +**描述**: XCUI 运行时文档宿主，负责把 `.xcui` / `.xctheme` 资源编译成 `UIScreenDocument`，并在逐帧更新中完成布局树构建、样式解析、输入分发、scroll/splitter/tab 状态维护和 `UIDrawData` 输出。 + +## 概览 + +头文件当前公开三层声明： + +- `IUIScreenDocumentHost` + - 抽象出 `LoadScreen(...)` 和 `BuildFrame(...)` 两个最小 runtime 合约。 +- `UIDocumentScreenHost` + - 当前默认实现，内部持有 `UIInputDispatcher`、scroll offset、splitter ratio 和 tab 选中状态缓存。 +- `InputDebugSnapshot` / `ScrollDebugSnapshot` / `SplitterDragRuntimeState` + - 暴露输入、滚轮和 splitter 拖拽调试快照。 + +## 当前实现行为 + +- `LoadScreen(...)` 当前会先编译 view document；如果 `themePath` 非空，再单独编译 theme document，并调用 `Style::TryCompileDocumentStyle(...)` 生成运行时 theme/style sheet。 +- `LoadScreen(...)` 失败时不会返回部分成功结果；任何 view/theme 编译错误都会让 `succeeded = false` 并写入明确错误字符串。 +- `BuildFrame(...)` 当前要求 `document.viewDocument.valid` 且 root tag 存在，否则直接返回错误 frame。 +- 如果输入的 viewport 宽高不大于 `0`，当前实现会用 `max(640x360, root.desiredSize)` 作为兜底视口。 +- 宿主会跨帧保存： + - pointer 跟踪状态 + - focus / active / capture 所在路径 + - scroll view 的纵向 offset + - splitter ratio + - tab-strip 选中索引 +- `BuildFrame(...)` 当前会在每帧重新构建运行时布局树，但把上面的交互状态重新同步回新树，因此 scroll、splitter 和 tab 切换会在文档不变时持续生效。 +- 快捷键、文本输入抑制、scroll wheel 命中、splitter drag 和 tab-strip 键盘导航都在这一个宿主里串行完成；当前没有线程同步。 + +## 运行时边界 + +- 当前实现只支持 `UIDocumentCompiler` 已经能产出的 view/theme 文档语法；未识别节点或非法 widget 结构会在 build/validation 阶段生成显式 frame 错误。 +- `GetInputDebugSnapshot()` / `GetScrollDebugSnapshot()` 返回的是最近一次 `BuildFrame(...)` 后的内部快照，不是历史日志。 +- 宿主是有状态对象；如果调用方每帧重建一个新 `UIDocumentScreenHost`，scroll/focus/tab 等跨帧状态都会丢失。 + +## 测试与调用链 + +- `tests/UI/Runtime/unit/test_ui_runtime_scroll_view.cpp` 当前覆盖滚轮滚动、hover 命中和嵌套 scroll view 目标选择。 +- `tests/UI/Runtime/unit/test_ui_runtime_splitter_validation.cpp` 当前验证 splitter 子节点个数不合法时会返回显式 frame error。 +- `tests/UI/Runtime/unit/test_ui_runtime_tab_strip.cpp` 当前验证 pointer/keyboard 选择 tab 会切换可见内容并跨帧持久化。 +- `tests/UI/Runtime/unit/test_ui_runtime_shortcut_scope.cpp` 当前验证 widget/panel/window/global shortcut scope，以及文本输入焦点对快捷键和 Tab traversal 的抑制。 +- `engine/src/Scene/SceneRuntime.cpp` 和 `engine/src/UI/Runtime/UIScreenPlayer.cpp` 当前都把 `UIDocumentScreenHost` 作为默认 runtime host 使用。 + +## 相关文档 + +- [Runtime](../Runtime.md) +- [UIScreenTypes](../UIScreenTypes/UIScreenTypes.md) +- [UIScreenPlayer](../UIScreenPlayer/UIScreenPlayer.md) +- [UISystem](../UISystem/UISystem.md) +- [DocumentStyleCompiler](../../Style/DocumentStyleCompiler/DocumentStyleCompiler.md) +- [LayoutEngine](../../Layout/LayoutEngine/LayoutEngine.md) diff --git a/docs/api/XCEngine/UI/Runtime/UIScreenPlayer/UIScreenPlayer.md b/docs/api/XCEngine/UI/Runtime/UIScreenPlayer/UIScreenPlayer.md new file mode 100644 index 00000000..dd907f64 --- /dev/null +++ b/docs/api/XCEngine/UI/Runtime/UIScreenPlayer/UIScreenPlayer.md @@ -0,0 +1,52 @@ +# UIScreenPlayer + +**命名空间**: `XCEngine::UI::Runtime` + +**类型**: `class` + +**头文件**: `XCEngine/UI/Runtime/UIScreenPlayer.h` + +**源文件**: `engine/src/UI/Runtime/UIScreenPlayer.cpp` + +**描述**: 单个 UI screen 的运行时播放器，负责持有已加载资产/文档、调用 document host 生成逐帧 `UIScreenFrameResult`，并记录最近错误与已呈现帧数。 + +## 概览 + +`UIScreenPlayer` 当前公开： + +- 生命周期 + - `explicit UIScreenPlayer(IUIScreenDocumentHost& documentHost)` + - `bool Load(const UIScreenAsset& asset)` + - `void Unload()` +- 状态查询 + - `IsLoaded()` + - `GetAsset()` + - `GetDocument()` + - `GetLastFrame()` + - `ConsumeLastFrame()` + - `GetLastError()` + - `GetPresentedFrameCount()` +- 逐帧更新 + - `const UIScreenFrameResult& Update(const UIScreenFrameInput& input)` + +## 当前实现行为 + +- `Load(...)` 会立即通过 `IUIScreenDocumentHost::LoadScreen(...)` 编译并缓存文档；失败时会清空 asset/document/frame，并重置已呈现帧数。 +- `Unload()` 只是清空本地缓存，不会反向通知 document host。 +- `IsLoaded()` 当前由 `m_document.IsValid()` 决定，而不是单独的布尔位。 +- `Update(...)` 在未加载文档时不会崩溃；它会返回一个 `documentLoaded = false` 的错误 frame，错误信息固定为 `"UIScreenPlayer has no loaded screen document."`。 +- 成功更新时，`Update(...)` 会把 draw-list 数、命令数、输入事件数和 `presentedFrameIndex` 写回 `m_lastFrame.stats`，然后递增 `m_presentedFrameCount`。 +- `ConsumeLastFrame()` 会把最近一帧 move 出去并把内部缓存重置为空 frame。 + +## 测试与调用链 + +- `tests/UI/Runtime/unit/test_ui_runtime_tab_strip.cpp`、`test_ui_runtime_scroll_view.cpp`、`test_ui_runtime_shortcut_scope.cpp` 和 `test_ui_runtime_splitter_validation.cpp` 当前都通过 `UIScreenPlayer + UIDocumentScreenHost` 组合验证运行时行为。 +- `engine/src/UI/Runtime/UISystem.cpp` 当前把 `UIScreenPlayer` 作为每个 layer 的最小呈现单元。 +- `tests/UI/Editor/unit/test_structured_editor_shell.cpp` 也直接使用 `UIDocumentScreenHost + UIScreenPlayer` 跑 editor shell 风格的 UI 文档。 + +## 相关文档 + +- [Runtime](../Runtime.md) +- [UIScreenDocumentHost](../UIScreenDocumentHost/UIScreenDocumentHost.md) +- [UIScreenTypes](../UIScreenTypes/UIScreenTypes.md) +- [UISystem](../UISystem/UISystem.md) diff --git a/docs/api/XCEngine/UI/Runtime/UIScreenStackController/UIScreenStackController.md b/docs/api/XCEngine/UI/Runtime/UIScreenStackController/UIScreenStackController.md new file mode 100644 index 00000000..1a3262e3 --- /dev/null +++ b/docs/api/XCEngine/UI/Runtime/UIScreenStackController/UIScreenStackController.md @@ -0,0 +1,58 @@ +# UIScreenStackController + +**命名空间**: `XCEngine::UI::Runtime` + +**类型**: `struct + class` + +**头文件**: `XCEngine/UI/Runtime/UIScreenStackController.h` + +**源文件**: `engine/src/UI/Runtime/UIScreenStackController.cpp` + +**描述**: `UISystem` 之上的高层压栈控制器，用更接近菜单、模态框和 HUD 的语义管理 screen layer。 + +## 概览 + +公开声明包括： + +- `UIScreenStackEntry` + - 保存 `layerId`、`UIScreenAsset` 和 `UIScreenLayerOptions` 的镜像条目。 +- 压栈 helper + - `PushScreen(...)` + - `PushMenu(...)` + - `PushModal(...)` + - `PushHud(...)` +- 栈修改 + - `ReplaceTop(...)` + - `Pop()` + - `Remove(...)` + - `Clear()` +- 查询 + - `GetEntryCount()` + - `GetTop()` + - `GetEntries()` + +## 当前实现行为 + +- `PushScreen(...)` 只是把调用转给底层 `UISystem::PushScreen(...)`，成功后再把相同资产和 options 镜像存进 `m_entries`。 +- `PushMenu(...)` 和 `PushModal(...)` 当前都使用： + - `acceptsInput = true` + - `blocksLayersBelow = true` +- `PushHud(...)` 当前使用： + - `acceptsInput = false` + - `blocksLayersBelow = false` +- `ResolveDebugName(...)` 会优先使用显式 `debugName`，其次回退到 `asset.screenId`，再回退到 `"Menu"` / `"Modal"` / `"HUD"`。 +- `ReplaceTop(...)` 当前先尝试加载新 layer，再移除旧 top；如果替换中途失败，会回滚新 layer，避免把原 top 无条件丢掉。 +- `Clear()` 会调用 `UISystem::DestroyAllPlayers()`，随后清空本地 `m_entries`。 + +## 调用链与测试 + +- `engine/src/Scene/SceneRuntime.cpp` 当前把 stack controller 暴露给 scene 层脚本/游戏逻辑。 +- `tests/Scene/test_scene_runtime.cpp` 当前覆盖 menu/modal/hud layer 的创建、移除、reset 和输入遮挡行为。 +- `tests/Core/UI/test_ui_runtime.cpp` 当前也直接验证 `PushMenu(...)`、`PushModal(...)`、`PushHud(...)` 和 `ReplaceTop(...)` 的基础栈语义。 + +## 相关文档 + +- [Runtime](../Runtime.md) +- [UIScreenTypes](../UIScreenTypes/UIScreenTypes.md) +- [UISceneRuntimeContext](../UISceneRuntimeContext/UISceneRuntimeContext.md) +- [UISystem](../UISystem/UISystem.md) diff --git a/docs/api/XCEngine/UI/Runtime/UIScreenTypes/UIScreenTypes.md b/docs/api/XCEngine/UI/Runtime/UIScreenTypes/UIScreenTypes.md new file mode 100644 index 00000000..4acf0cfb --- /dev/null +++ b/docs/api/XCEngine/UI/Runtime/UIScreenTypes/UIScreenTypes.md @@ -0,0 +1,49 @@ +# UIScreenTypes + +**命名空间**: `XCEngine::UI::Runtime` + +**类型**: `type alias + structs` + +**头文件**: `XCEngine/UI/Runtime/UIScreenTypes.h` + +**描述**: XCUI runtime 层共享的数据模型，覆盖 screen asset、已编译文档、逐帧输入输出和多层呈现结果。 + +## 概览 + +这份头文件当前主要承担 runtime 数据交换职责： + +- `UIScreenLayerId` + - runtime layer 的 64 位标识。 +- `UIScreenAsset` + - 描述 screenId、view document 路径和可选 theme 路径。 +- `UIScreenDocument` + - 保存编译后的 view/theme 文档，以及可选的运行时 theme/style sheet。 +- `UIScreenLoadResult` + - `LoadScreen(...)` 的成功位、错误消息和文档载荷。 +- `UIScreenFrameInput` / `UIScreenFrameResult` + - 单个 player 的逐帧输入和渲染输出。 +- `UIScreenLayerOptions` / `UISystemPresentedLayer` / `UISystemFrameResult` + - 多层系统的 layer 配置、实际呈现层摘要和聚合 frame 结果。 + +## 当前实现边界 + +- `UIScreenAsset::IsValid()` 当前只要求 `documentPath` 非空；`screenId` 和 `themePath` 都是可选项。 +- `UIScreenDocument::IsValid()` 当前只用 `sourcePath` 判定是否加载成功，具体 view/theme 数据由 `UIDocumentScreenHost` 填充。 +- `GetThemeDocument()` / `GetRuntimeTheme()` / `GetRuntimeStyleSheet()` 都依赖 `hasThemeDocument` / `hasRuntimeTheme` 标志；没有主题时返回 `nullptr`。 +- `UIScreenFrameStats` 和 `UISystemFrameResult` 当前都只是统计快照，不负责累计历史值。 +- `UISystemFrameResult.errorMessage` 的填充策略由 `UISystem` 决定；当前实现只保留首个非空 layer 错误。 + +## 调用链与测试 + +- `engine/src/UI/Runtime/UIScreenDocumentHost.cpp` 负责构造 `UIScreenDocument`、`UIScreenFrameResult` 和调试统计。 +- `engine/src/UI/Runtime/UIScreenPlayer.cpp` 直接消费 `UIScreenLoadResult` / `UIScreenFrameInput` / `UIScreenFrameResult`。 +- `engine/src/UI/Runtime/UISystem.cpp` 当前把多个 player 的结果聚合成 `UISystemFrameResult`。 +- `tests/Scene/test_scene_runtime.cpp` 当前通过 `UISystemPresentedLayer` 和 `UISystemFrameResult` 验证多层输入路由与遮挡行为。 + +## 相关文档 + +- [Runtime](../Runtime.md) +- [UIScreenDocumentHost](../UIScreenDocumentHost/UIScreenDocumentHost.md) +- [UIScreenPlayer](../UIScreenPlayer/UIScreenPlayer.md) +- [UIScreenStackController](../UIScreenStackController/UIScreenStackController.md) +- [UISystem](../UISystem/UISystem.md) diff --git a/docs/api/XCEngine/UI/Runtime/UISystem/UISystem.md b/docs/api/XCEngine/UI/Runtime/UISystem/UISystem.md new file mode 100644 index 00000000..9171bc50 --- /dev/null +++ b/docs/api/XCEngine/UI/Runtime/UISystem/UISystem.md @@ -0,0 +1,69 @@ +# UISystem + +**命名空间**: `XCEngine::UI::Runtime` + +**类型**: `class` + +**头文件**: `XCEngine/UI/Runtime/UISystem.h` + +**源文件**: `engine/src/UI/Runtime/UISystem.cpp` + +**描述**: XCUI 多 layer 运行时系统，负责创建 `UIScreenPlayer`、维护 layer options，并把多个 player 的逐帧结果合并成单个 `UISystemFrameResult`。 + +## 概览 + +主要公开接口包括： + +- layer / player 管理 + - `CreatePlayer(...)` + - `PushScreen(...)` + - `RemoveLayer(...)` + - `SetLayerVisibility(...)` + - `SetLayerOptions(...)` + - `FindLayerOptions(...)` + - `GetLayerId(...)` + - `DestroyAllPlayers()` +- 状态查询 + - `GetPlayerCount()` + - `GetLayerCount()` + - `GetPlayers()` +- 逐帧更新 + - `Update(...)` + - `Tick(...)` + - `GetLastFrame()` + - `ConsumeLastFrame()` + +## 当前实现行为 + +- `CreatePlayer(...)` 会同时追加： + - 一个新的 `UIScreenPlayer` + - 一个新的 layer id + - 一份对应的 `UIScreenLayerOptions` +- `PushScreen(...)` 如果 `player.Load(...)` 失败，会把刚追加的 player/id/options 一并回滚，并返回 `0`。 +- `Update(...)` 每帧先重置 `m_lastFrame`，并写入输入 viewport、提交事件数、delta time 和 focus 状态。 +- 当前呈现裁剪规则是： + - 从顶层向下找第一个 `visible && blocksLayersBelow` 的 layer + - 这个 layer 之下的 layer 直接记为 `skipped` +- 当前输入路由规则是： + - 在“被呈现的层集合”里，从顶向下找第一个 `visible && acceptsInput` 的 layer + - 只有这个 layer 会收到原始 `events` 和 `focused = true` + - 其余被呈现层仍会更新，但 `events` 被清空、`focused = false` +- `Update(...)` 会把所有被呈现 layer 的 `UIDrawList` 顺序拼进一个 `UISystemFrameResult.drawData`，并把首个非空 layer error 写入系统级 `errorMessage`。 +- `Tick(...)` 当前只是 `Update(...)` 的别名。 + +## 测试与调用链 + +- `tests/Scene/test_scene_runtime.cpp` 当前直接验证： + - 顶层 interactive layer 独占输入 + - `blocksLayersBelow` 会跳过下层呈现 + - 隐藏层不会抢占输入 +- `tests/Core/UI/test_ui_runtime.cpp` 也覆盖了 `UISystem` 的 layer 创建、移除、可见性切换和 `ConsumeLastFrame()` 语义。 +- `UIScreenStackController` 和 `UISceneRuntimeContext` 当前都把 `UISystem` 当成底层执行器使用。 + +## 相关文档 + +- [Runtime](../Runtime.md) +- [UIScreenTypes](../UIScreenTypes/UIScreenTypes.md) +- [UIScreenPlayer](../UIScreenPlayer/UIScreenPlayer.md) +- [UIScreenStackController](../UIScreenStackController/UIScreenStackController.md) +- [UISceneRuntimeContext](../UISceneRuntimeContext/UISceneRuntimeContext.md) diff --git a/docs/api/XCEngine/UI/Style/DocumentStyleCompiler/DocumentStyleCompiler.md b/docs/api/XCEngine/UI/Style/DocumentStyleCompiler/DocumentStyleCompiler.md new file mode 100644 index 00000000..542d8d0e --- /dev/null +++ b/docs/api/XCEngine/UI/Style/DocumentStyleCompiler/DocumentStyleCompiler.md @@ -0,0 +1,53 @@ +# DocumentStyleCompiler + +**命名空间**: `XCEngine::UI::Style` + +**类型**: `struct + free functions` + +**头文件**: `XCEngine/UI/Style/DocumentStyleCompiler.h` + +**源文件**: `engine/src/UI/Style/DocumentStyleCompiler.cpp` + +**描述**: 把 `Resources::UIDocumentModel` 中的 `` 文档编译成运行时 `UITheme` 和 `UIStyleSheet`，并支持从单个节点属性构建 inline style。 + +## 概览 + +当前公开入口包括： + +- `UIDocumentStyleCompileResult` + - 聚合 `succeeded`、`errorMessage`、`theme` 和 `styleSheet`。 +- `CompileDocumentStyle(...)` + - 返回结构化结果的便捷入口。 +- `TryCompileDocumentStyle(...)` + - 直接写出 theme/style sheet，并把错误信息输出到可选字符串。 +- `BuildInlineStyle(...)` + - 从节点属性里提取当前支持的样式属性。 + +## 当前实现行为 + +- `TryCompileDocumentStyle(...)` 当前要求： + - 文档 `valid` + - root tag 必须是 `` +- `` 当前只解析两类子节点： + - `` + - `` +- `` 当前支持 `Color`、`Spacing/Float/Number`、`Radius`、`Padding/Thickness` 这些 token 节点；值既可以是字面量，也可以是另一个 token 名字。 +- `` 当前只接受 `` 子节点；每个 `` 必须声明 `type` 或 `style` 之一。 +- `` 当前只接受运行时已知属性名；未知属性和值解析失败都会让整次编译失败。 +- `BuildInlineStyle(...)` 只会提取当前能映射到 `UIStylePropertyId` 的属性；未知属性和非法值会被静默忽略。 + +## 测试与调用链 + +- `tests/UI/Core/unit/test_ui_style_system.cpp` 当前直接覆盖： + - 主题文档编译为 `UITheme + UIStyleSheet` + - inline style 抽取与 resolver 集成 +- `engine/src/UI/Runtime/UIScreenDocumentHost.cpp` 当前在加载带 `themePath` 的 screen 时调用 `TryCompileDocumentStyle(...)`，并在构建节点时用 `BuildInlineStyle(...)` 解析节点局部样式。 + +## 相关文档 + +- [Style](../Style.md) +- [StyleTypes](../StyleTypes/StyleTypes.md) +- [StyleSet](../StyleSet/StyleSet.md) +- [StyleResolver](../StyleResolver/StyleResolver.md) +- [Theme](../Theme/Theme.md) +- [UIScreenDocumentHost](../../Runtime/UIScreenDocumentHost/UIScreenDocumentHost.md) diff --git a/docs/api/XCEngine/UI/Style/Style.md b/docs/api/XCEngine/UI/Style/Style.md new file mode 100644 index 00000000..111b6678 --- /dev/null +++ b/docs/api/XCEngine/UI/Style/Style.md @@ -0,0 +1,35 @@ +# Style + +**命名空间**: `XCEngine::UI` + +**类型**: `submodule` + +**头文件目录**: `engine/include/XCEngine/UI/Style/` + +**描述**: XCUI 样式与主题层，负责 style types、style set、style resolver、document style compiler 与 theme。 + +## 当前范围 + +- [DocumentStyleCompiler](DocumentStyleCompiler/DocumentStyleCompiler.md) + - 把 theme 文档编译成运行时 `UITheme + UIStyleSheet`，并提取 inline style。 +- [StyleResolver](StyleResolver/StyleResolver.md) + - local / named / type / default 四层样式解析。 +- [StyleSet](StyleSet/StyleSet.md) + - style set、selector 和 style sheet 容器。 +- [StyleTypes](StyleTypes/StyleTypes.md) + - 基础样式值类型、属性枚举与 token 引用。 +- [Theme](Theme/Theme.md) + - 主题 token、父主题回退和内建主题工厂。 + +## 头文件 + +- [DocumentStyleCompiler](DocumentStyleCompiler/DocumentStyleCompiler.md) - `DocumentStyleCompiler.h` +- [StyleResolver](StyleResolver/StyleResolver.md) - `StyleResolver.h` +- [StyleSet](StyleSet/StyleSet.md) - `StyleSet.h` +- [StyleTypes](StyleTypes/StyleTypes.md) - `StyleTypes.h` +- [Theme](Theme/Theme.md) - `Theme.h` + +## 相关文档 + +- [UI](../UI.md) +- [Resources UI](../../Resources/UI/UI.md) diff --git a/docs/api/XCEngine/UI/Style/StyleResolver/StyleResolver.md b/docs/api/XCEngine/UI/Style/StyleResolver/StyleResolver.md new file mode 100644 index 00000000..0c313231 --- /dev/null +++ b/docs/api/XCEngine/UI/Style/StyleResolver/StyleResolver.md @@ -0,0 +1,55 @@ +# StyleResolver + +**命名空间**: `XCEngine::UI::Style` + +**类型**: `enums + structs + class + free functions` + +**头文件**: `XCEngine/UI/Style/StyleResolver.h` + +**源文件**: `engine/src/UI/Style/StyleResolver.cpp` + +**描述**: XCUI 样式求值层，把 theme token、style sheet 和 node local style 组合成最终 `UIResolvedStyle`。 + +## 概览 + +头文件当前公开： + +- `UIStyleLayer` + - `None / Default / Type / Named / Local` 五层来源枚举。 +- `UIStylePropertyResolution` + - 单个属性的 resolved 标志、来源 layer 和最终值。 +- `UIResolvedStyle` + - 已解析样式结果集合。 +- `UIStyleResolveContext` + - 持有 `theme`、`styleSheet`、`selector` 和可选 `localStyle`。 +- `ResolveStyleProperty(...)` + - 解析单个属性。 +- `ResolveStyle(...)` + - 解析当前已知全部属性。 +- `ToString(UIStyleLayer)` + - layer 调试字符串。 + +## 当前实现行为 + +- `ResolveStyleProperty(...)` 当前固定按 `Local -> Named -> Type -> Default` 顺序查找。 +- 如果高优先级层存在属性，但 token 无法解析或类型不匹配，当前实现会继续回退到下一层，而不是立刻报错。 +- 当前只支持两类轻量 coercion： + - `float -> UIThickness::Uniform(...)` + - `float -> UICornerRadius::Uniform(...)` +- `ResolveStyle(...)` 只枚举运行时已知属性 id 集合，不会自动扫描 `UIStyleSet` 里的所有键。 +- `UIResolvedStyle` 只是解析结果容器，不会保存未解析失败原因；调用方只能看到某属性是否 resolved。 + +## 测试与调用链 + +- `tests/UI/Core/unit/test_ui_style_system.cpp` 当前验证： + - local/named/type/default 优先级 + - 高优先级 token 解析失败时回退到低优先级 + - uniform float 向 padding/radius 的 coercion +- `engine/src/UI/Runtime/UIScreenDocumentHost.cpp` 当前对每个运行时节点构造 `UIStyleResolveContext`，再读取 `UIResolvedStyle` 驱动测量与绘制。 + +## 相关文档 + +- [Style](../Style.md) +- [StyleSet](../StyleSet/StyleSet.md) +- [StyleTypes](../StyleTypes/StyleTypes.md) +- [Theme](../Theme/Theme.md) diff --git a/docs/api/XCEngine/UI/Style/StyleSet/StyleSet.md b/docs/api/XCEngine/UI/Style/StyleSet/StyleSet.md new file mode 100644 index 00000000..40e7b0a8 --- /dev/null +++ b/docs/api/XCEngine/UI/Style/StyleSet/StyleSet.md @@ -0,0 +1,44 @@ +# StyleSet + +**命名空间**: `XCEngine::UI::Style` + +**类型**: `classes + struct` + +**头文件**: `XCEngine/UI/Style/StyleSet.h` + +**描述**: XCUI 样式容器层，负责按属性 id 存储一组样式值，并把默认样式、按类型样式和按名字样式组织成一个 `UIStyleSheet`。 + +## 概览 + +头文件当前公开： + +- `UIStyleSet` + - 以 `std::map` 保存一层样式属性。 +- `UIStyleSelector` + - 同时携带 `typeName` 和 `styleName`，供 resolver 决定 type/named layer。 +- `UIStyleSheet` + - 持有： + - 一份 default style + - 多份 type style + - 多份 named style + +## 当前实现边界 + +- 这份头文件当前完全内联，没有 `.cpp`，也没有额外同步机制。 +- `UIStyleSet` 只提供 `SetProperty(...)`、`RemoveProperty(...)`、`HasProperty(...)` 和 `FindProperty(...)`；没有批量合并或优先级逻辑。 +- `UIStyleSheet::GetOrCreateTypeStyle(...)` / `GetOrCreateNamedStyle(...)` 都会按需创建空 style set。 +- `FindTypeStyle(...)` / `FindNamedStyle(...)` 在样式不存在时返回 `nullptr`，不会隐式回退到 default style。 +- 当前没有“删除整个 named/type style”或“枚举 selector”接口；上层只能通过 resolver 按需查找。 + +## 调用链与测试 + +- `engine/src/UI/Style/StyleResolver.cpp` 当前把它当作四层样式解析的底层数据源。 +- `engine/src/UI/Style/DocumentStyleCompiler.cpp` 当前把 `` 和 `` 编译到 `UIStyleSheet` 的 type/named map。 +- `tests/UI/Core/unit/test_ui_style_system.cpp` 当前直接构造 `UIStyleSet` / `UIStyleSheet` 验证 resolver 的层级优先级。 + +## 相关文档 + +- [Style](../Style.md) +- [StyleTypes](../StyleTypes/StyleTypes.md) +- [StyleResolver](../StyleResolver/StyleResolver.md) +- [Theme](../Theme/Theme.md) diff --git a/docs/api/XCEngine/UI/Style/StyleTypes/StyleTypes.md b/docs/api/XCEngine/UI/Style/StyleTypes/StyleTypes.md new file mode 100644 index 00000000..a47a99e9 --- /dev/null +++ b/docs/api/XCEngine/UI/Style/StyleTypes/StyleTypes.md @@ -0,0 +1,54 @@ +# StyleTypes + +**命名空间**: `XCEngine::UI::Style` + +**类型**: `enums + structs + class + free functions` + +**头文件**: `XCEngine/UI/Style/StyleTypes.h` + +**源文件**: `engine/src/UI/Style/StyleTypes.cpp` + +**描述**: XCUI 样式系统的基础值类型定义，覆盖 thickness、corner radius、token reference、样式值 variant 和样式属性枚举。 + +## 概览 + +这份头文件当前提供： + +- `UIThickness` / `UICornerRadius` + - padding / radius 语义值对象与 `Uniform(...)` 构造 helper。 +- `UITokenReference` + - 指向主题 token 名字的轻量引用。 +- `UIStyleValueType` + - 样式值的运行时类别枚举。 +- `UIStyleValue` + - `float / Color / Thickness / CornerRadius / Size / Point / TokenReference` 的 variant 包装。 +- `UIStylePropertyId` + - 当前样式系统支持的公共属性枚举。 +- `GetExpectedValueType(...)` / `ToString(...)` + - 属性类型映射和调试字符串。 + +## 当前实现行为 + +- `UIStyleValue` 当前不做隐式类型转换；所有具体类型都必须通过显式构造函数或 `Token(...)` 进入 variant。 +- `operator==` / `operator!=` 在 `float`、`Color`、`Thickness`、`CornerRadius`、`Size` 和 `Point` 上都使用 `Math::EPSILON` 风格的近似比较。 +- `UITokenReference::IsValid()` 只检查 `name` 非空，不验证 token 是否真实存在。 +- `GetExpectedValueType(...)` 当前只为已知属性返回固定类型： + - 颜色类属性 -> `Color` + - `BorderWidth` / `Gap` / `FontSize` / `LineWidth` -> `Float` + - `CornerRadius` -> `CornerRadius` + - `Padding` -> `Thickness` +- `UIStylePropertyId` 目前只覆盖 runtime 真正消费的那一组属性，不是开放式键值表。 + +## 测试与调用链 + +- `tests/UI/Core/unit/test_ui_style_system.cpp` 当前覆盖 theme token、token alias、类型不匹配、uniform float 到 padding/radius 的转换前置数据。 +- `engine/src/UI/Style/Theme.cpp`、`StyleResolver.cpp` 和 `DocumentStyleCompiler.cpp` 当前都直接依赖 `UIStyleValue` / `UIStylePropertyId`。 +- `engine/src/UI/Runtime/UIScreenDocumentHost.cpp` 当前通过 resolved style 读取 `BackgroundColor`、`Padding`、`Gap`、`FontSize` 等属性来驱动布局和绘制。 + +## 相关文档 + +- [Style](../Style.md) +- [StyleSet](../StyleSet/StyleSet.md) +- [StyleResolver](../StyleResolver/StyleResolver.md) +- [Theme](../Theme/Theme.md) +- [DocumentStyleCompiler](../DocumentStyleCompiler/DocumentStyleCompiler.md) diff --git a/docs/api/XCEngine/UI/Style/Theme/Theme.md b/docs/api/XCEngine/UI/Style/Theme/Theme.md new file mode 100644 index 00000000..03c11b87 --- /dev/null +++ b/docs/api/XCEngine/UI/Style/Theme/Theme.md @@ -0,0 +1,55 @@ +# Theme + +**命名空间**: `XCEngine::UI::Style` + +**类型**: `enums + structs + class + free functions` + +**头文件**: `XCEngine/UI/Style/Theme.h` + +**源文件**: `engine/src/UI/Style/Theme.cpp` + +**描述**: XCUI 主题 token 层，负责 token 存储、父主题回退、token alias 解析以及内建 `NeutralDark` / `NeutralLight` 主题构建。 + +## 概览 + +当前公开声明包括： + +- `UITokenResolveStatus` / `UITokenResolveResult` + - token 解析状态和最终值。 +- `UIThemeDefinition` + - 纯数据定义对象，适合先收集 token 再构建主题。 +- `UIBuiltinThemeKind` + - 当前只公开 `NeutralDark` 和 `NeutralLight`。 +- `UITheme` + - 运行时主题对象，支持 parent 链和 token 解析。 +- `BuildTheme(...)` / `BuildBuiltinTheme(...)` + - 主题工厂。 + +## 当前实现行为 + +- `UIThemeDefinition` 和 `UITheme` 都用 `std::map` 持有 token。 +- `UITheme::FindToken(...)` 先查本地，再递归查 parent；`RemoveToken(...)` 只移除本地 token。 +- `ResolveToken(...)` 会递归解开 `UITokenReference`，并显式报告： + - `MissingToken` + - `CycleDetected` + - `TypeMismatch` +- `ResolveToken(...)` 的 `expectedType` 当前只影响最终值类型校验，不影响 `FindToken(...)` 的查找范围。 +- `BuildBuiltinTheme(...)` 当前返回一组固定命名 token，覆盖 surface、text、accent、spacing、padding、radius、font 和 line。 +- 当前没有主题继承链的 ownership 管理；`SetParent(...)` 只保存裸指针，调用方必须保证 parent 生命周期。 + +## 测试与调用链 + +- `tests/UI/Core/unit/test_ui_style_system.cpp` 当前覆盖： + - token alias 解析 + - parent token 回退 + - missing/cycle/type mismatch + - 内建 light/dark 主题差异 +- `engine/src/UI/Style/StyleResolver.cpp` 当前通过 `theme->ResolveToken(...)` 完成 token reference 的最终求值。 +- `engine/src/UI/Runtime/UIScreenDocumentHost.cpp` 当前在载入带 `.xctheme` 的 screen 时保存 `runtimeTheme`，随后每帧参与样式解析。 + +## 相关文档 + +- [Style](../Style.md) +- [StyleTypes](../StyleTypes/StyleTypes.md) +- [StyleResolver](../StyleResolver/StyleResolver.md) +- [DocumentStyleCompiler](../DocumentStyleCompiler/DocumentStyleCompiler.md) diff --git a/docs/api/XCEngine/UI/Text/Text.md b/docs/api/XCEngine/UI/Text/Text.md new file mode 100644 index 00000000..bc2aa356 --- /dev/null +++ b/docs/api/XCEngine/UI/Text/Text.md @@ -0,0 +1,21 @@ +# Text + +**命名空间**: `XCEngine::UI` + +**类型**: `submodule` + +**头文件目录**: `engine/include/XCEngine/UI/Text/` + +**描述**: XCUI 文本输入与编辑层，负责文本编辑状态和输入控制器。 + +## 当前范围 + +- [UITextEditing](UITextEditing/UITextEditing.md) + - UTF-8 文本偏移、换行和垂直光标移动 helper。 +- [UITextInputController](UITextInputController/UITextInputController.md) + - 文本输入状态与按键编辑控制器。 + +## 相关文档 + +- [UI](../UI.md) +- [Input](../Input/Input.md) diff --git a/docs/api/XCEngine/UI/Text/UITextEditing/UITextEditing.md b/docs/api/XCEngine/UI/Text/UITextEditing/UITextEditing.md new file mode 100644 index 00000000..b72a7d09 --- /dev/null +++ b/docs/api/XCEngine/UI/Text/UITextEditing/UITextEditing.md @@ -0,0 +1,51 @@ +# UITextEditing + +**命名空间**: `XCEngine::UI::Text` + +**类型**: `free functions` + +**头文件**: `XCEngine/UI/Text/UITextEditing.h` + +**源文件**: `engine/src/UI/Text/UITextEditing.cpp` + +**描述**: XCUI 文本编辑 helper，提供 UTF-8 codepoint 级 offset 移动、换行拆分和纵向光标移动逻辑。 + +## 概览 + +公开函数可分为三组： + +- UTF-8 偏移与编码 + - `CountUtf8Codepoints(...)` + - `AdvanceUtf8Offset(...)` + - `RetreatUtf8Offset(...)` + - `AppendUtf8Codepoint(...)` +- 多行文本辅助 + - `SplitLines(...)` + - `CountTextLines(...)` + - `CountUtf8CodepointsInRange(...)` + - `FindLineStartOffset(...)` + - `FindLineEndOffset(...)` +- 光标移动 + - `MoveCaretVertically(...)` + +## 当前实现边界 + +- 这些 helper 当前都按 UTF-8 codepoint 工作，不理解 grapheme cluster，也不会处理组合字符显示宽度。 +- `CountUtf8Codepoints(...)` 通过“非 continuation byte 计数”工作，对非法 UTF-8 序列没有额外诊断。 +- `AppendUtf8Codepoint(...)` 会跳过 surrogate 区间和大于 `0x10FFFF` 的非法 codepoint。 +- `SplitLines(...)` 只按 `\n` 切行；即使原字符串为空，也会返回一行空字符串。 +- `MoveCaretVertically(...)` 会尽量保持当前 codepoint 列号；到达首行/末行时直接返回原 caret。 + +## 测试与调用链 + +- `tests/UI/Core/unit/test_ui_text_editing.cpp` 当前验证： + - UTF-8 codepoint 计数和 offset 边界 + - codepoint 追加与非法 surrogate 跳过 + - 多行辅助函数 + - 垂直移动时尽量保列 +- `engine/src/UI/Text/UITextInputController.cpp` 当前直接用这些 helper 处理 backspace/delete/home/end/up/down。 + +## 相关文档 + +- [Text](../Text.md) +- [UITextInputController](../UITextInputController/UITextInputController.md) diff --git a/docs/api/XCEngine/UI/Text/UITextInputController/UITextInputController.md b/docs/api/XCEngine/UI/Text/UITextInputController/UITextInputController.md new file mode 100644 index 00000000..cb233e9a --- /dev/null +++ b/docs/api/XCEngine/UI/Text/UITextInputController/UITextInputController.md @@ -0,0 +1,57 @@ +# UITextInputController + +**命名空间**: `XCEngine::UI::Text` + +**类型**: `structs + free functions` + +**头文件**: `XCEngine/UI/Text/UITextInputController.h` + +**源文件**: `engine/src/UI/Text/UITextInputController.cpp` + +**描述**: XCUI 文本输入控制器，维护当前文本值与 caret，并把键盘事件转换为编辑动作或 submit 请求。 + +## 概览 + +头文件当前公开： + +- `UITextInputState` + - 保存 `value` 和字节偏移语义的 `caret`。 +- `UITextInputOptions` + - 控制是否 multiline，以及 Tab 插入的空格宽度。 +- `UITextInputEditResult` + - 返回本次按键是否被消费、是否改值、是否请求 submit。 +- `ClampCaret(...)` +- `InsertCharacter(...)` +- `HandleKeyDown(...)` + +## 当前实现行为 + +- `ClampCaret(...)` 只把 `caret` 钳到 `value.size()`，不主动校正到 UTF-8 codepoint 边界；真正的边界跳转依赖 `UITextEditing` helper。 +- `InsertCharacter(...)` 当前拒绝控制字符 `< 32` 和 `DEL(127)`，并通过 `AppendUtf8Codepoint(...)` 编码插入。 +- `HandleKeyDown(...)` 当前处理： + - `Backspace` / `Delete` + - 左右方向键 + - 多行 `Up` / `Down` + - `Home` / `End` + - `Enter` + - 多行 `Tab` / `Shift+Tab` +- 单行模式下按 `Enter` 不改文本，只设置 `submitRequested = true`。 +- 多行模式下按 `Tab` 会插入 `tabWidth` 个空格；`Shift+Tab` 只会删除当前行开头最多 `tabWidth` 个前导空格。 +- 带 `control/alt/super` 修饰键的 `Tab` 当前不会走本地缩进逻辑，方便上层保留系统快捷键或焦点切换。 +- 可打印字符的插入当前不在 `HandleKeyDown(...)` 里处理，调用方仍需单独调用 `InsertCharacter(...)`。 + +## 测试与调用链 + +- `tests/UI/Core/unit/test_ui_text_input_controller.cpp` 当前覆盖： + - UTF-8 边界上的插入、删除、左右移动 + - 单行/多行 `Enter` + - `Home` / `End` / 垂直移动 + - 多行 `Tab` / `Shift+Tab` + - oversized caret 的恢复 +- `engine/src/UI/Runtime/UIScreenDocumentHost.cpp` 当前把文本输入节点的焦点/快捷键抑制和输入分发接到 runtime build frame 流程里。 + +## 相关文档 + +- [Text](../Text.md) +- [UITextEditing](../UITextEditing/UITextEditing.md) +- [UIInputDispatcher](../../Input/UIInputDispatcher/UIInputDispatcher.md) diff --git a/docs/api/XCEngine/UI/Types/Types.md b/docs/api/XCEngine/UI/Types/Types.md new file mode 100644 index 00000000..538c13b2 --- /dev/null +++ b/docs/api/XCEngine/UI/Types/Types.md @@ -0,0 +1,61 @@ +# Types + +**命名空间**: `XCEngine::UI` + +**类型**: `structs + enums` + +**头文件**: `XCEngine/UI/Types.h` + +**描述**: XCUI 基础几何、纹理句柄和输入事件类型，作为 runtime、editor、绘制层与输入层之间的最小共享 ABI。 +## 概览 + +`Types.h` 当前覆盖三类基础类型： + +- 几何与纹理 + - `UIPoint` + - `UISize` + - `UIRect` + - `UITextureHandleKind` + - `UITextureHandle` +- 指针与键盘事件分类 + - `UIPointerButton` + - `UIInputEventType` +- 输入事件载体 + - `UIInputModifiers` + - `UIInputEvent` + +## 当前实现行为 + +- `UIPoint`、`UISize`、`UIRect` 当前都是轻量 POD 风格结构，只提供默认构造和逐字段构造，不提供命中测试、归一化或裁剪 helper。 +- `UITextureHandle::IsValid()` 当前要求 `nativeHandle != 0` 且 `width > 0 && height > 0`；仅有尺寸或仅有句柄都不算有效纹理。 +- `UITextureHandleKind` 当前区分 `DescriptorHandle` 和 `ShaderResourceView` 两种底层句柄来源，但 `Types.h` 本身不负责跨 API 转换。 +- `UIInputEvent` 是一份扁平输入包：位置、位移、滚轮、键码、字符码点、pointer id、时间戳、按钮、修饰键、`repeat` 与 `synthetic` 都由上层填充。 +- 输入坐标是否是 viewport 空间、客户端空间或屏幕空间，不由这里约束；当前由调用链自行约定。 + +## 测试与调用链 + +- `tests/Input/test_xcui_input_dispatcher.cpp`、`tests/UI/Core/integration/shared/src/Application.cpp` 与 editor/shared integration app 当前直接构造 `UIInputEvent`。 +- `tests/UI/Runtime/unit/*`、`tests/UI/Core/unit/*` 与 `engine/src/UI/Widgets/*` 当前广泛使用 `UIPoint`、`UISize`、`UIRect` 驱动布局、命中测试和 popup/splitter 交互。 +- `editor/src/panels/ViewportPanelContent.h`、`SceneViewPanel.cpp` 和多组 editor viewport 测试当前也直接使用 `UISize` / `UIPoint` 把 ImGui 输入桥接到 editor 侧 API。 +- `UITextureHandle` 当前既被 `UIDrawCommand` 使用，也被 `ImGuiTransitionBackend` 和 editor/runtime 绘制路径直接消费。 + +## 关键声明 + +| 声明 | 角色 | +|------|------| +| `UITextureHandleKind` | 纹理句柄来源分类。 | +| `UIPoint` | 二维点。 | +| `UISize` | 二维尺寸。 | +| `UIRect` | 二维矩形。 | +| `UITextureHandle` | 供绘制层消费的轻量纹理句柄。 | +| `UIPointerButton` | 指针按钮枚举。 | +| `UIInputEventType` | 指针、键盘、字符与焦点事件类型。 | +| `UIInputModifiers` | shift / control / alt / super 状态。 | +| `UIInputEvent` | 统一输入事件包。 | + +## 相关文档 + +- [UI](../UI.md) +- [DrawData](../DrawData/DrawData.md) +- [Core](../Core/Core.md) +- [Input](../Input/Input.md) diff --git a/docs/api/XCEngine/UI/UI.md b/docs/api/XCEngine/UI/UI.md new file mode 100644 index 00000000..eb2ef891 --- /dev/null +++ b/docs/api/XCEngine/UI/UI.md @@ -0,0 +1,31 @@ +# UI + +**命名空间**: `XCEngine::UI` + +**类型**: `module` + +**头文件目录**: `engine/include/XCEngine/UI/` + +**描述**: XCEngine 当前的 XCUI / retained-mode UI 公共 API 根模块，覆盖 UI core、输入、布局、样式、文本、runtime 屏幕系统与 editor/runtime 共用的 widget 状态模型。 + +## 顶层头文件 + +- [Types](Types/Types.md) +- [DrawData](DrawData/DrawData.md) + +## 子模块 + +- [Core](Core/Core.md) +- [Input](Input/Input.md) +- [Layout](Layout/Layout.md) +- [Runtime](Runtime/Runtime.md) +- [Style](Style/Style.md) +- [Text](Text/Text.md) +- [Widgets](Widgets/Widgets.md) + +当前 `UI` 模块已经把 retained-mode 基础层、输入层、布局/样式/文本 helper、screen runtime，以及 popup/tab/splitter 等 widget 状态模型分拆为独立 canonical 子模块页面。 + +## 相关文档 + +- [XCEngine](../XCEngine.md) +- [Resources UI](../Resources/UI/UI.md) diff --git a/docs/api/XCEngine/UI/Widgets/UIExpansionModel/UIExpansionModel.md b/docs/api/XCEngine/UI/Widgets/UIExpansionModel/UIExpansionModel.md new file mode 100644 index 00000000..cd83042b --- /dev/null +++ b/docs/api/XCEngine/UI/Widgets/UIExpansionModel/UIExpansionModel.md @@ -0,0 +1,45 @@ +# UIExpansionModel + +**命名空间**: `XCEngine::UI::Widgets` + +**类型**: `class` + +**头文件**: `XCEngine/UI/Widgets/UIExpansionModel.h` + +**源文件**: `engine/src/UI/Widgets/UIExpansionModel.cpp` + +**描述**: 以字符串 id 集合维护展开状态的轻量模型，适合 tree/list 类控件保存哪些条目处于展开状态。 + +## 概览 + +当前公开接口包括： + +- 查询 + - `HasExpandedItems()` + - `GetExpandedCount()` + - `IsExpanded(...)` +- 修改 + - `SetExpanded(...)` + - `Expand(...)` + - `Collapse(...)` + - `ToggleExpanded(...)` + - `Clear()` + +## 当前实现行为 + +- 内部状态当前只是一个 `std::unordered_set`。 +- `SetExpanded(...)` 只是 `Expand(...)` / `Collapse(...)` 的分派包装。 +- `Expand(...)` 只有在 id 首次插入时返回 `true`；重复展开返回 `false`。 +- `Collapse(...)` 只有在 id 原本存在时返回 `true`。 +- `ToggleExpanded(...)` 当前无论是展开还是折叠都会返回 `true`；它不区分“是否真的改变过外部可见集合”。 +- `Clear()` 在集合原本为空时返回 `false`。 + +## 测试与调用链 + +- `tests/UI/Core/unit/test_ui_expansion_model.cpp` 当前覆盖 expand/collapse/clear 以及 set/toggle 行为。 +- `UIFlatHierarchyHelpers` 是与它最接近的配套 helper：一个维护“谁被展开”，另一个根据展开状态判断扁平层级可见性。 + +## 相关文档 + +- [Widgets](../Widgets.md) +- [UIFlatHierarchyHelpers](../UIFlatHierarchyHelpers/UIFlatHierarchyHelpers.md) diff --git a/docs/api/XCEngine/UI/Widgets/UIFlatHierarchyHelpers/UIFlatHierarchyHelpers.md b/docs/api/XCEngine/UI/Widgets/UIFlatHierarchyHelpers/UIFlatHierarchyHelpers.md new file mode 100644 index 00000000..2d863c26 --- /dev/null +++ b/docs/api/XCEngine/UI/Widgets/UIFlatHierarchyHelpers/UIFlatHierarchyHelpers.md @@ -0,0 +1,42 @@ +# UIFlatHierarchyHelpers + +**命名空间**: `XCEngine::UI::Widgets` + +**类型**: `constants + template free functions` + +**头文件**: `XCEngine/UI/Widgets/UIFlatHierarchyHelpers.h` + +**描述**: 面向“扁平数组 + 深度回调”树表示法的层级查询 helper，负责 parent 查找、可见性判断和首个可见子节点定位。 + +## 概览 + +当前公开符号包括： + +- `kInvalidUIFlatHierarchyItemOffset` + - 层级查询失败时返回的 offset 哨兵。 +- `UIFlatHierarchyHasChildren(...)` +- `UIFlatHierarchyFindParentOffset(...)` +- `UIFlatHierarchyIsVisible(...)` +- `UIFlatHierarchyFindFirstVisibleChildOffset(...)` + +## 当前实现边界 + +- 这份头文件是纯模板 helper，没有运行时状态，也没有 `.cpp`。 +- 所有函数都依赖调用方提供 `itemIndices` 和 `resolveDepth(index)`；helper 本身不关心真实节点类型。 +- `resolveDepth(...)` 返回负值时，当前实现会把它钳到 `0`，按“根层级”处理。 +- `UIFlatHierarchyIsVisible(...)` 通过逆向扫描祖先深度并调用 `isExpanded(...)` 判定可见性，不缓存 parent 索引。 +- `UIFlatHierarchyFindFirstVisibleChildOffset(...)` 只在同一子树分支内查找第一个可见 child；如果根本没有子节点或都不可见，返回无效 offset。 +- 目前工作树里这组 helper 主要由单元测试直接使用，还没有被 runtime host 大量复用。 + +## 测试与调用链 + +- `tests/UI/Core/unit/test_ui_flat_hierarchy_helpers.cpp` 当前验证： + - parent/child 关系推导 + - 折叠祖先导致的可见性变化 + - 首个可见子节点查询 + - 负深度钳到根层级的边界 + +## 相关文档 + +- [Widgets](../Widgets.md) +- [UIExpansionModel](../UIExpansionModel/UIExpansionModel.md) diff --git a/docs/api/XCEngine/UI/Widgets/UIKeyboardNavigationModel/UIKeyboardNavigationModel.md b/docs/api/XCEngine/UI/Widgets/UIKeyboardNavigationModel/UIKeyboardNavigationModel.md new file mode 100644 index 00000000..f5e015ba --- /dev/null +++ b/docs/api/XCEngine/UI/Widgets/UIKeyboardNavigationModel/UIKeyboardNavigationModel.md @@ -0,0 +1,52 @@ +# UIKeyboardNavigationModel + +**命名空间**: `XCEngine::UI::Widgets` + +**类型**: `class` + +**头文件**: `XCEngine/UI/Widgets/UIKeyboardNavigationModel.h` + +**源文件**: `engine/src/UI/Widgets/UIKeyboardNavigationModel.cpp` + +**描述**: 列表式控件的键盘导航状态模型，记录当前索引、选择锚点和 item 总数。 + +## 概览 + +公开接口分为三组： + +- item 总数 + - `GetItemCount()` + - `SetItemCount(...)` + - `ClampToItemCount()` +- 当前索引 + - `HasCurrentIndex()` + - `GetCurrentIndex()` + - `SetCurrentIndex(...)` + - `ClearCurrentIndex()` +- 选择锚点与导航 + - `HasSelectionAnchor()` + - `GetSelectionAnchorIndex()` + - `SetSelectionAnchorIndex(...)` + - `ClearSelectionAnchor()` + - `MoveNext()` / `MovePrevious()` / `MoveHome()` / `MoveEnd()` + +## 当前实现行为 + +- `InvalidIndex` 当前是 `size_t(-1)`。 +- `SetItemCount(...)` 不只是改总数；它还会在需要时自动裁剪 current/anchor，并把“是否裁剪或数量变化”作为返回值。 +- 当 `m_currentIndex` 为空时： + - `MoveNext()` 会把当前项播种到 `0` + - `MovePrevious()` 会把当前项播种到最后一项 +- `SetCurrentIndex(index, updateAnchor)` 在 `updateAnchor = true` 时会让锚点同步到当前索引。 +- `MoveHome()` / `MoveEnd()` 不循环；到头/到尾之后再次调用返回 `false`。 +- item 数量变为 `0` 时，current index 和 selection anchor 都会一起清成 `InvalidIndex`。 + +## 测试与调用链 + +- `tests/UI/Core/unit/test_ui_keyboard_navigation_model.cpp` 当前覆盖空模型、方向导航、anchor 保留与 itemCount 裁剪边界。 +- 目前这份模型主要作为 widget 状态 building block 存在，真实 runtime tab-strip 另有更窄的 `UITabStripModel`。 + +## 相关文档 + +- [Widgets](../Widgets.md) +- [UITabStripModel](../UITabStripModel/UITabStripModel.md) diff --git a/docs/api/XCEngine/UI/Widgets/UIPopupOverlayModel/UIPopupOverlayModel.md b/docs/api/XCEngine/UI/Widgets/UIPopupOverlayModel/UIPopupOverlayModel.md new file mode 100644 index 00000000..6780db43 --- /dev/null +++ b/docs/api/XCEngine/UI/Widgets/UIPopupOverlayModel/UIPopupOverlayModel.md @@ -0,0 +1,47 @@ +# UIPopupOverlayModel + +**命名空间**: `XCEngine::UI::Widgets` + +**类型**: `enums + structs + free functions + class` + +**头文件**: `XCEngine/UI/Widgets/UIPopupOverlayModel.h` + +**源文件**: `engine/src/UI/Widgets/UIPopupOverlayModel.cpp` + +**描述**: popup overlay 的链式状态模型，负责 popup 开关、祖先/子菜单分支裁剪、dismiss 规则和 placement rect 计算。 + +## 概览 + +头文件当前公开： + +- `UIPopupPlacement` / `UIPopupDismissReason` + - placement 和关闭原因枚举。 +- `UIPopupPlacementResult` + - popup rect、最终 placement 和 x/y 钳位标志。 +- `UIPopupOverlayEntry` + - 描述 popup id、父 popup、anchor/surface path、anchor rect 和 dismiss 选项。 +- `UIPopupOverlayMutationResult` + - 一次 open/close/dismiss 的变更结果。 +- `ResolvePopupPlacementRect(...)` + - placement 几何 helper。 +- `UIPopupOverlayModel` + - popup 链状态机。 + +## 当前实现行为 + +- `ResolvePopupPlacementRect(...)` 当前会先尝试首选方向；如果首选放不下但翻转方向能放下，就自动 flip；否则保留当前方向并把位置钳进 viewport。 +- root popup（`parentPopupId` 为空）当前会替换整条已有 popup 链。 +- submenu popup 只能挂到当前链里已存在的父 popup；如果父节点之后已有更深分支，`OpenPopup(...)` 会先裁掉旧分支再追加新 popup。 +- `DismissFromPointerDown(...)` 和 `DismissFromFocusLoss(...)` 都基于 `anchorPath` / `surfacePath` 的前缀包含关系判断“命中了哪一层 popup”。 +- `DismissFromEscape()` 只关闭最顶层第一个允许 `dismissOnEscape` 的 popup。 +- 当前模型只维护链式 popup，不支持一棵并列 popup forest。 + +## 测试与调用链 + +- `tests/UI/Core/unit/test_ui_popup_overlay_model.cpp` 当前覆盖 root/submenu 打开、关闭、pointer dismiss、focus-loss dismiss，以及 placement flip/clamp。 +- `tests/UI/Core/integration/shared/src/PopupMenuOverlayValidationScene.cpp` 和 `tests/UI/Editor/integration/shell/menu_bar_basic/main.cpp` 当前直接调用 `ResolvePopupPlacementRect(...)`。 + +## 相关文档 + +- [Widgets](../Widgets.md) +- [UIInputPath](../../Input/UIInputPath/UIInputPath.md) diff --git a/docs/api/XCEngine/UI/Widgets/UIPropertyEditModel/UIPropertyEditModel.md b/docs/api/XCEngine/UI/Widgets/UIPropertyEditModel/UIPropertyEditModel.md new file mode 100644 index 00000000..50d08d80 --- /dev/null +++ b/docs/api/XCEngine/UI/Widgets/UIPropertyEditModel/UIPropertyEditModel.md @@ -0,0 +1,43 @@ +# UIPropertyEditModel + +**命名空间**: `XCEngine::UI::Widgets` + +**类型**: `class` + +**头文件**: `XCEngine/UI/Widgets/UIPropertyEditModel.h` + +**源文件**: `engine/src/UI/Widgets/UIPropertyEditModel.cpp` + +**描述**: inspector 风格的 staged edit 会话状态，跟踪当前正在编辑的字段、基线值、暂存值和 dirty 标志。 + +## 概览 + +公开接口包括： + +- 查询 + - `HasActiveEdit()` + - `GetActiveFieldId()` + - `GetStagedValue()` + - `IsDirty()` +- 会话控制 + - `BeginEdit(...)` + - `UpdateStagedValue(...)` + - `CommitEdit(...)` + - `CancelEdit()` + +## 当前实现行为 + +- `BeginEdit(...)` 需要非空 `fieldId`；如果 fieldId、baseline、staged 和 dirty 状态都没变，则返回 `false`。 +- `UpdateStagedValue(...)` 只有在已有活动会话时才生效，并按 `staged != baseline` 更新 dirty 标志。 +- `CommitEdit(...)` 即使当前值未 dirty，也会返回字段 id 和 staged value，然后清空整段编辑会话。 +- `CancelEdit()` 不返回旧值，只是丢弃会话状态。 +- 当前模型不做类型校验，也不区分“已经提交”和“提交失败后回滚”；这些都交给上层处理。 + +## 测试与调用链 + +- `tests/UI/Core/unit/test_ui_property_edit_model.cpp` 当前覆盖 begin/update/commit/cancel 的全部状态转换。 + +## 相关文档 + +- [Widgets](../Widgets.md) +- [UISelectionModel](../UISelectionModel/UISelectionModel.md) diff --git a/docs/api/XCEngine/UI/Widgets/UISelectionModel/UISelectionModel.md b/docs/api/XCEngine/UI/Widgets/UISelectionModel/UISelectionModel.md new file mode 100644 index 00000000..511ee3ad --- /dev/null +++ b/docs/api/XCEngine/UI/Widgets/UISelectionModel/UISelectionModel.md @@ -0,0 +1,39 @@ +# UISelectionModel + +**命名空间**: `XCEngine::UI::Widgets` + +**类型**: `class` + +**头文件**: `XCEngine/UI/Widgets/UISelectionModel.h` + +**源文件**: `engine/src/UI/Widgets/UISelectionModel.cpp` + +**描述**: 单选字符串 id 模型，适合列表、树和属性面板中“当前选中项”这类最基础的选择状态。 + +## 概览 + +公开接口非常直接： + +- `HasSelection()` +- `GetSelectedId()` +- `IsSelected(...)` +- `SetSelection(...)` +- `ClearSelection()` +- `ToggleSelection(...)` + +## 当前实现行为 + +- 内部状态当前只有一个 `std::string m_selectedId`。 +- `HasSelection()` 只检查字符串是否为空，因此空字符串等价于“无选择”。 +- `SetSelection(...)` 在传入和当前相同的 id 时返回 `false`；否则直接覆盖当前选中项。 +- `ToggleSelection(...)` 在命中当前选中 id 时会清空选择，否则把它设为新的选中项。 +- 当前模型是严格单选，不提供多选集合或 anchor/range 语义。 + +## 测试与调用链 + +- `tests/UI/Core/unit/test_ui_selection_model.cpp` 当前覆盖 set/clear/toggle 的基础行为。 + +## 相关文档 + +- [Widgets](../Widgets.md) +- [UIKeyboardNavigationModel](../UIKeyboardNavigationModel/UIKeyboardNavigationModel.md) diff --git a/docs/api/XCEngine/UI/Widgets/UISplitterInteraction/UISplitterInteraction.md b/docs/api/XCEngine/UI/Widgets/UISplitterInteraction/UISplitterInteraction.md new file mode 100644 index 00000000..8a0fe1cd --- /dev/null +++ b/docs/api/XCEngine/UI/Widgets/UISplitterInteraction/UISplitterInteraction.md @@ -0,0 +1,45 @@ +# UISplitterInteraction + +**命名空间**: `XCEngine::UI::Widgets` + +**类型**: `struct + free functions` + +**头文件**: `XCEngine/UI/Widgets/UISplitterInteraction.h` + +**描述**: splitter widget 的交互 helper，负责 handle hit-test、drag 状态持久化以及按指针位置更新 split ratio。 + +## 概览 + +当前公开声明包括： + +- `UISplitterDragState` + - 保存 active 标志、ownerId、axis、bounds、constraints、metrics 和当前 `splitRatio`。 +- `ExpandUISplitterHandleHitRect(...)` + - 扩大 handle 的跨轴命中区域。 +- `HitTestUISplitterHandle(...)` + - 判断指针是否命中 handle。 +- `BeginUISplitterDrag(...)` + - 从当前 layout 和指针位置初始化拖拽状态。 +- `UpdateUISplitterDrag(...)` + - 根据指针位置推导新 ratio 和新 layout。 +- `EndUISplitterDrag(...)` + - 清空拖拽状态。 + +## 当前实现行为 + +- `ExpandUISplitterHandleHitRect(...)` 只沿 splitter 的跨轴扩大 hit 区域，默认 padding 为 `3.0f`。 +- `BeginUISplitterDrag(...)` 会把 `(metrics.hitThickness - metrics.thickness) * 0.5f` 额外加到命中区域上，因此命中厚度可大于可见厚度。 +- 只有指针实际命中当前 `handleRect` 扩展区域时，`BeginUISplitterDrag(...)` 才会把 `outState.active` 置真。 +- `UpdateUISplitterDrag(...)` 会调用 `Layout::ResolveSplitterRatioFromPointerPosition(...)` 和 `ArrangeUISplitter(...)`；只有 ratio 变化超过 `0.0001f` 才返回 `true`。 +- `EndUISplitterDrag(...)` 当前直接把整个状态清零。 + +## 测试与调用链 + +- `tests/UI/Core/unit/test_ui_splitter_interaction.cpp` 当前覆盖横纵向 hit rect、命中测试和 drag 更新对约束的裁剪。 +- `engine/src/UI/Runtime/UIScreenDocumentHost.cpp` 当前直接用这组 helper 实现 splitter runtime 拖拽。 + +## 相关文档 + +- [Widgets](../Widgets.md) +- [UISplitterLayout](../../Layout/UISplitterLayout/UISplitterLayout.md) +- [UIScreenDocumentHost](../../Runtime/UIScreenDocumentHost/UIScreenDocumentHost.md) diff --git a/docs/api/XCEngine/UI/Widgets/UITabStripModel/UITabStripModel.md b/docs/api/XCEngine/UI/Widgets/UITabStripModel/UITabStripModel.md new file mode 100644 index 00000000..7a2e1ac9 --- /dev/null +++ b/docs/api/XCEngine/UI/Widgets/UITabStripModel/UITabStripModel.md @@ -0,0 +1,40 @@ +# UITabStripModel + +**命名空间**: `XCEngine::UI::Widgets` + +**类型**: `class` + +**头文件**: `XCEngine/UI/Widgets/UITabStripModel.h` + +**描述**: tab-strip 的最小状态模型，只负责 item 总数和当前选中索引，不承载任何几何或渲染逻辑。 + +## 概览 + +当前公开接口包括： + +- `GetItemCount()` / `SetItemCount(...)` +- `HasSelection()` / `GetSelectedIndex()` / `SetSelectedIndex(...)` +- `SelectFirst()` / `SelectLast()` / `SelectNext()` / `SelectPrevious()` +- `InvalidIndex` + +## 当前实现行为 + +- 这份头文件当前完全内联，没有 `.cpp`。 +- `SetItemCount(...)` 会调用内部 `ClampSelection()`： + - itemCount 变成 `0` 时把选中索引清成 `InvalidIndex` + - itemCount 从 `0` 变成正数且当前未选中时，自动选中第 `0` 项 + - 缩容导致越界时，自动钳到最后一项 +- `SetSelectedIndex(...)` 对越界索引返回 `false`；不会自动 wrap。 +- `SelectNext()` / `SelectPrevious()` 在未选中状态下会先播种到第 `0` 项，然后再按有界方式移动。 +- 当前模型不支持“无自动默认选中”的懒初始化策略；只要 itemCount > 0 且 selection 为空，`ClampSelection()` 就会选中首项。 + +## 测试与调用链 + +- `tests/UI/Core/unit/test_ui_tab_strip_model.cpp` 当前覆盖 itemCount 调整、越界裁剪和前后移动边界。 +- `engine/src/UI/Runtime/UIScreenDocumentHost.cpp` 当前用它维护 tab-strip 的跨帧选中索引，并结合 `UITabStripLayout` 生成 header/content 显示结果。 + +## 相关文档 + +- [Widgets](../Widgets.md) +- [UITabStripLayout](../../Layout/UITabStripLayout/UITabStripLayout.md) +- [UIScreenDocumentHost](../../Runtime/UIScreenDocumentHost/UIScreenDocumentHost.md) diff --git a/docs/api/XCEngine/UI/Widgets/Widgets.md b/docs/api/XCEngine/UI/Widgets/Widgets.md new file mode 100644 index 00000000..725d258b --- /dev/null +++ b/docs/api/XCEngine/UI/Widgets/Widgets.md @@ -0,0 +1,34 @@ +# Widgets + +**命名空间**: `XCEngine::UI` + +**类型**: `submodule` + +**头文件目录**: `engine/include/XCEngine/UI/Widgets/` + +**描述**: XCUI widget 状态与交互辅助层，覆盖选择、展开、键盘导航、popup overlay、property edit、splitter interaction 和 tab-strip model。 + +## 当前范围 + +- [UIExpansionModel](UIExpansionModel/UIExpansionModel.md) + - 展开状态集合。 +- [UIFlatHierarchyHelpers](UIFlatHierarchyHelpers/UIFlatHierarchyHelpers.md) + - 扁平层级树上的 parent/visibility/first-child 查询模板。 +- [UIKeyboardNavigationModel](UIKeyboardNavigationModel/UIKeyboardNavigationModel.md) + - 列表式键盘导航与锚点状态。 +- [UIPopupOverlayModel](UIPopupOverlayModel/UIPopupOverlayModel.md) + - popup 链管理、dismiss 规则和 placement 求解。 +- [UIPropertyEditModel](UIPropertyEditModel/UIPropertyEditModel.md) + - inspector 风格的 staged property edit 会话状态。 +- [UISelectionModel](UISelectionModel/UISelectionModel.md) + - 单选 id 状态模型。 +- [UISplitterInteraction](UISplitterInteraction/UISplitterInteraction.md) + - splitter handle hit-test 与拖拽状态 helper。 +- [UITabStripModel](UITabStripModel/UITabStripModel.md) + - tab-strip 选中索引模型。 + +## 相关文档 + +- [UI](../UI.md) +- [Input](../Input/Input.md) +- [Layout](../Layout/Layout.md) diff --git a/docs/api/_guides/Components/GameObject-Component-Lifecycle-And-Serialization.md b/docs/api/_guides/Components/GameObject-Component-Lifecycle-And-Serialization.md index 2612b896..895d13e7 100644 --- a/docs/api/_guides/Components/GameObject-Component-Lifecycle-And-Serialization.md +++ b/docs/api/_guides/Components/GameObject-Component-Lifecycle-And-Serialization.md @@ -2,67 +2,98 @@ ## 这篇指南解决什么问题 -只看 `Components` 模块下的单个 API 页，很容易知道“有哪些函数”，但不容易知道“应该怎么组织对象”“生命周期到底是谁驱动的”“为什么有些对象能被查到、有些不能”“为什么某些组件保存后会丢状态”。 +单看 `GameObject`、`Component`、`TransformComponent` 这些 API 页，你可以知道“接口叫什么”，但很难立刻建立完整心智模型： -这篇指南专门回答这些问题。它不是第二套 API 参考，而是帮助你建立当前 `XCEngine::Components` 模块的整体心智模型。 +- 为什么 `Transform` 是内建的，而不是普通组件？ +- 为什么有些对象能被全局查询到，有些不能？ +- 为什么 `tag` / `layer` 现在已经可用，但又不等于完整 TagManager？ +- 为什么动态加组件后，有时不会自动进入完整生命周期？ +- 为什么 `GameObject::Serialize()` 和 `Scene::SerializeToString()` 要分成两层？ + +这篇指南的目标就是把这些设计取舍讲清楚。 ## 先建立正确心智模型 -当前引擎采用的是 **GameObject + Component + Scene 树** 模型，而不是 ECS。 +当前 `XCEngine` 采用的是 **Scene -> GameObject -> Component** 这条经典对象树模型，而不是 ECS。 -可以把它粗略类比成 Unity 的对象体系： +可以把它粗略理解成“更轻量的 Unity 风格对象系统”： -- `Scene` 像场景容器，拥有对象并驱动更新与序列化。 -- `GameObject` 像层级树节点，负责身份、轻量 `tag` / `layer`、父子关系、激活状态和组件容器。 -- `TransformComponent` 像内建 `Transform`，每个对象必有一个。 -- 其他组件按职责挂接到对象上，例如 `CameraComponent`、`LightComponent`、`MeshRendererComponent`、`AudioSourceComponent`。 +- `Scene` 负责对象集合、根入口、更新驱动和整棵树的保存/加载。 +- `GameObject` 负责对象身份、层级、激活状态、轻量 `tag/layer` 与组件容器。 +- `TransformComponent` 是每个对象必有的基础设施组件。 +- 普通组件只负责自身行为，例如相机、灯光、网格、音频、脚本等。 -这种设计的优势是： +这种设计的主要好处是： -- 对编辑器层级、脚本调用和运行时调试都比较直观。 -- 对多数游戏开发者来说学习成本低。 -- 场景保存/加载可以直接围绕对象树展开。 +- 编辑器层级和运行时对象是一套直观模型 +- 脚本侧调用方式更贴近多数开发者已有经验 +- 场景保存/加载天然围绕对象树展开 -代价是： +代价则是： -- 生命周期不再只是“组件自己的事”，而是依赖 `Scene -> GameObject -> Component` 这条链路。 -- 某些看起来像全局查询的接口，其实只对场景托管对象成立。 -- 运行时动态加组件时，如果没有自动补发初始化阶段，就会出现“对象在，但逻辑没进入完整生命周期”的情况。 +- 生命周期入口更依赖 `Scene -> GameObject -> Component` +- 全局查询与场景查询有明显边界 +- 运行时动态加组件如果不补生命周期，就会出现“组件挂上了，但初始化没追上”的问题 ## 为什么 `TransformComponent` 是内建组件 -商业级游戏引擎里，`Transform` 往往不是普通业务组件，而是对象树的基础设施。当前实现也是这个思路： +商业引擎通常把 `Transform` 当成对象树基础设施，而不是完全可选的普通功能块。当前实现也是这个思路： - `GameObject` 构造时立即创建 `TransformComponent` - `AddComponent()` 返回已有实例 - `RemoveComponent()` 不能移除它 -这样设计的好处是： +这样设计的直接收益是： -- 所有对象都天然具有空间位置和层级关系 -- 相机、灯光、网格、音频这些组件都可以稳定依赖 `transform()` -- 编辑器和场景序列化不需要处理“这个对象没有变换”的特殊分支 +- 每个对象都天然可放进层级树 +- 组件和脚本不需要处理“这个对象没有 transform”的分支 +- 场景序列化和编辑器层级不用做额外特判 -代价是 `TransformComponent` 不再是完全对称的组件类型。你在上层逻辑里必须把它当成“基础设施组件”，不是“普通可选功能块”。 +代价是 `TransformComponent` 不再与普通组件完全对称。你应该把它理解为对象系统底座，而不是“可以随意增删的业务组件”。 + +## 为什么 Tag / Layer 现在是轻量字段 + +当前 `GameObject` 已经有真实的： + +- `m_tag` +- `m_layer` + +它们不再是旧文档里那种“名字别名”或“预留概念”。但它们也还不是完整的项目级管理系统。 + +### 当前已经具备的能力 + +- `tag` 默认值是 `"Untagged"` +- `SetTag("")` 会回退到 `"Untagged"` +- `CompareTag()` 做真实字符串比较 +- `FindGameObjectsWithTag()` 与 `Scene::FindGameObjectWithTag()` 都按真实 tag 查询 +- `layer` 会进入序列化与反序列化 +- 托管 `GameObject.tag` / `layer` 与 `Component.tag` / `layer` 直接桥接到同一份 native 字段 + +### 当前还没有的能力 + +- 项目级 tag 定义表 +- tag 重命名迁移系统 +- layer mask 资产与可视化管理器 +- 专门的查询索引 + +这正是很多商业引擎早期阶段常见的取舍：先把对象元数据模型做扎实，再决定是否要升级成更重的全局管理系统。 ## 场景托管对象 vs 独立对象 -这是当前模块最容易被忽略的一条边界。 +这是最容易误用的一条边界。 ### 独立对象 ```cpp -XCEngine::Components::GameObject player("Player"); +XCEngine::Components::GameObject probe("Probe"); ``` -这会得到一个可用对象，但它： +它会得到一个合法对象，但当前只保证： -- 只有内建 `Transform` -- 默认不在任何 `Scene` 中 -- 不会自动注册到全局查找表 -- 不会自动触发 `Awake` - -它适合测试、临时对象或手工控制生命周期的场景。 +- 有内建 `Transform` +- 不属于任何 `Scene` +- 不会自动进入全局 registry +- 不会自动触发 `Awake()` ### 场景托管对象 @@ -70,90 +101,74 @@ XCEngine::Components::GameObject player("Player"); auto* player = scene.CreateGameObject("Player"); ``` -按当前实现，这条路径会额外完成： +这条路径当前会额外完成： -- 设置 `m_scene` +- 写入所属 `Scene` - 注册到全局 registry -- 接入场景根节点或父节点 -- 调用 `Awake()` +- 接入根节点或父对象之下 +- 创建后立刻调用 `Awake()` -这才是更接近“真实运行时对象”的创建方式。 - -### 为什么这很重要 - -因为下列能力都和“是否已被场景托管”直接相关： - -- `GameObject::Find()` -- `GameObject::FindObjectsOfType()` -- `GameObject::FindGameObjectsWithTag()` -- `Component::GetScene()` -- 场景级保存/加载 - -如果对象只是裸构造出来的，你不能期待这些能力都成立。 +很多 API 的真实适用范围，都是围绕“场景托管对象”设计的，而不是裸构造对象。 ## 当前真实生命周期 -下面这张表描述的是 **当前代码已经实现的行为**，不是理想化设计图。 +下面这张表描述的是**当前代码已经实现的真实行为**： -| 阶段 | 谁触发 | 当前行为 | +| 阶段 | 触发者 | 当前行为 | |------|------|------| -| 构造 `GameObject` | 用户或 `Scene` | 创建对象、分配 ID/UUID、创建内建 `Transform` | -| `Scene::CreateGameObject()` | `Scene` | 注册全局表、设置场景、挂到父子层级、调用 `Awake()` | -| `Scene::DeserializeFromString()` | `Scene` | 重建对象、Transform、普通组件和父子关系，但当前不会自动补发 `Awake()` | +| `GameObject` 构造 | 用户或 `Scene` | 创建对象、分配 ID/UUID、创建内建 `Transform` | +| `Scene::CreateGameObject()` | `Scene` | 注册场景与全局表、接入层级、调用 `Awake()` | | `GameObject::Awake()` | `Scene` 或用户 | 遍历普通组件并调用 `Awake()` | -| `Scene::Update()` | `Scene` | 对激活 root object 调用 `Start()`，之后 `Update()` | -| `GameObject::Start()` | `Scene` 或用户 | 只调用一次；仅对激活层级中的已启用普通组件生效 | -| `SetEnabled()` / `SetActive()` / `SetParent()` | 用户或内部逻辑 | 根据层级有效激活态触发 `OnEnable()` / `OnDisable()` | +| `Scene::Update()` | `Scene` | 对激活 root 先调用 `Start()`，再调用 `Update()` | +| `GameObject::Start()` | `Scene` 或用户 | 只对 `active in hierarchy` 的对象生效，且每对象只执行一次 | +| `GameObject::FixedUpdate()` / `LateUpdate()` | `Scene` 或用户 | 对激活层级中的已启用普通组件递归分发 | +| `SetActive()` / `SetParent()` | 用户或内部逻辑 | 重算层级有效激活态，并向已启用组件发送 `OnEnable()` / `OnDisable()` | | `Destroy()` | 用户 | 场景托管对象走 `Scene::DestroyGameObject()`；独立对象只发 `OnDestroy()`，不自动 delete | +| `Scene::DeserializeFromString()` | `Scene` | 重建对象、层级与组件，但不经过 `CreateGameObject()`，因此不补发 `Awake()` / `Start()` | ## 运行时 `AddComponent()` 的现实语义 -很多用户会下意识把它当成 Unity 那种“加上就自动进入生命周期”的接口，但当前实现不是。 +很多人会下意识把它理解成 Unity 那种“加上去就自动进入完整生命周期”的接口，但当前实现更保守。 ```cpp -auto* go = scene.CreateGameObject("Emitter"); -auto* source = go->AddComponent(); +auto* emitter = scene.CreateGameObject("Emitter"); +auto* source = emitter->AddComponent(); ``` -这里会发生的事情只有： +这里当前只保证： - 创建组件实例 -- 回填 `component->m_gameObject = go` -- 放进 `m_components` +- 回填 `component->m_gameObject` +- 放入 `m_components` -这里 **不会自动发生**： +这里**不会自动发生**： - `Awake()` - `Start()` - `OnEnable()` -为什么这很关键？因为很多组件初始化逻辑都习惯写在这些阶段里。如果你在运行中动态加组件，就需要自己明确何时让它进入可用状态。 - -还有一个更容易踩坑的点：如果这个 `GameObject` 之前已经进入过 `Start()`，后续再添加的新组件也不会在未来被自动 `Start()`，因为当前实现只用 `m_started` 记录“这个对象是否已经启动过一次”，而不是“每个组件是否已经启动过”。 +这是一条非常关键的工程边界。如果某个组件把重要初始化逻辑写在这些阶段，运行时动态挂载之后就需要你自己决定何时补足初始化，而不是期待引擎自动帮你追平。 ## 激活状态为什么要区分两层 -和 Unity 一样，这里也区分： +当前对象系统和 Unity 一样，明确区分： - `activeSelf` - `activeInHierarchy` -原因很现实： +原因很简单： -- 一个对象自己打开，不代表它真的在运行；只要父对象被禁用，它依然应该整体失活。 -- 组件的 `OnEnable()` / `OnDisable()` 不能只看自己的 `enabled`，还要看宿主对象是否真的在活跃层级里。 +- 对象自己打开，并不代表它真的在运行 +- 只要父对象被禁用，整个子树都应视为失活 +- 组件的 `OnEnable()` / `OnDisable()` 不能只看自己 `enabled`，还要看宿主对象是否处于有效激活层级 -当前实现里，`Component::SetEnabled()` 就按下面的“有效启用态”处理： +这种设计虽然比单布尔值复杂一些，但它能避免大量层级对象状态错乱问题，是商业引擎里成熟且必要的做法。 -`component enabled && gameObject active in hierarchy` +## 为什么序列化要分两层 -这能避免父节点关闭时组件仍然误以为自己处于活动状态。 +初看时可能会觉得：既然 `GameObject` 知道自己的组件和子对象，为什么不让它一个接口把所有东西全写完？ -## 为什么序列化要分层 - -初看时可能会觉得：既然 `GameObject` 有组件容器，为什么不让 `GameObject::Serialize()` 一次把所有内容都写完？ - -当前实现没有这么做，而是分成两层： +当前实现故意没有这么做，而是拆成： ### `GameObject::Serialize()` @@ -169,105 +184,90 @@ auto* source = go->AddComponent(); ### `Scene::SerializeToString()` -负责完整场景结构： +负责完整场景树： -- 所有 root object 递归展开 +- 场景名和场景 active 位 +- 根对象入口 - `parent` 关系 - 每个普通组件的类型名和 payload -- 反序列化时通过 `ComponentFactoryRegistry` 重建组件 +- 递归子对象 -这种分层的好处是职责清晰： +这样拆的好处是职责清晰： -- `GameObject` 负责“我是谁，我的基础状态是什么” -- `Scene` 负责“我如何把整棵对象树持久化” +- 对象级接口关注“这个对象自己是什么状态” +- 场景级接口关注“整棵树如何保存与恢复” -这和商业引擎里把对象局部状态和场景容器职责拆开的思路是一致的。 +这和商业引擎里把对象局部状态与场景容器边界拆开的思路是一致的。 -但当前加载路径还有一个必须知道的现实差异：`Scene::DeserializeFromString()` 在恢复对象和组件后，没有自动重放 `Awake()`。所以“新建场景对象”和“从场景文本加载出来的对象”在初始化阶段并不完全对称。 +## 托管脚本为什么能立刻影响原生查询 -## `ComponentFactoryRegistry` 在这里的作用 +当前 Mono 运行时已经把这些接口桥接到了同一份 native 数据： -反序列化场景时，文本里只有组件类型名，例如： +- `GameObject.tag` +- `GameObject.layer` +- `Component.tag` +- `Component.layer` +- `CompareTag()` -```text -component=Camera;projection=0;fov=60;... -``` +这意味着： -引擎需要把 `"Camera"` 重新变成具体组件实例。当前实现就是通过 `ComponentFactoryRegistry` 完成这件事。 +- 脚本读到的不是副本 +- 脚本写回后，原生对象字段会立即变化 +- 场景查询和全局查询都会立刻看到新值 -它当前预注册了： +这也是为什么 `tests/Scripting/test_mono_script_runtime.cpp` 中，脚本把对象 tag 改成 `"Player"` 之后，原生 `Scene::FindGameObjectWithTag("Player")` 会马上返回同一个对象。 -- `Camera` -- `Light` -- `AudioSource` -- `AudioListener` -- `MeshFilter` -- `MeshRenderer` -- `ScriptComponent` +## 当前你必须知道的限制 -注意 `Transform` 不在里面，因为 `TransformComponent` 不是靠工厂反序列化创建的，它是 `GameObject` 的内建成员。 +### 1. tag / layer 已经可用，但仍是轻量模型 -## 你现在必须知道的限制 +不要再把它理解成“只是名字别名”，但也不要把它理解成已经具备完整项目配置、索引和重命名迁移能力的 TagManager。 -### 1. `FindGameObjectsWithTag()` 现在是真实 tag 查询，但仍是轻量实现 +### 2. 静态全局查询只对已注册对象成立 -当前实现已经有独立 `m_tag` 字段： +裸构造对象默认不会出现在： -- 默认是 `"Untagged"` -- `SetTag("")` 会回退到 `"Untagged"` -- `FindGameObjectsWithTag()` / `Scene::FindGameObjectWithTag()` 都通过 `CompareTag()` 查询 +- `GameObject::Find()` +- `GameObject::FindObjectsOfType()` +- `GameObject::FindGameObjectsWithTag()` -但它仍不是完整 TagManager： +### 3. 独立对象的 `Destroy()` 不会释放对象自身 -- 没有项目级 tag 定义表 -- 没有索引或缓存 -- 查询仍是线性扫描 +它只发送 `OnDestroy()`。真正的内存释放仍由对象所有者负责。 -### 2. `TransformComponent::Find()` 不是局部子树查找 +### 4. 反序列化路径不补发生命周期 -它会从整个场景的 root objects 开始搜索第一个名字匹配项。 +`Scene::DeserializeFromString()` 目前是“忠实恢复内存状态”，不是“模拟一次完整运行时创建流程”。 -### 3. `TransformComponent` 的 sibling API 还不完整 +### 5. `TransformComponent` 不参与普通组件遍历 -`SetSiblingIndex()`、`SetAsFirstSibling()`、`SetAsLastSibling()` 目前只修改索引字段，没有真正重排父节点子列表。 - -### 4. 音频组件当前不参与完整序列化 - -`AudioSourceComponent` 和 `AudioListenerComponent` 没有自定义 `Serialize()` / `Deserialize()`，所以场景保存/加载不会持久化它们的运行时参数。 - -### 5. 独立对象的 `Destroy()` 不会删除对象本身 - -它只调用 `OnDestroy()`。如果对象不是 `Scene` 持有的，内存释放仍然要由真正的所有者负责。 - -### 6. 反序列化路径当前不会自动重放 `Awake()` - -如果某些组件把关键初始化逻辑写在 `Awake()`，那么从场景文本恢复后的状态可能和新建对象不同。 +无论是生命周期还是普通组件列表逻辑，都不要把它当成 `m_components` 里的普通成员来理解。 ## 推荐工作流 -### 场景内对象 +### 运行时对象 1. 用 `Scene::CreateGameObject()` 创建对象。 -2. 用 `GameObject::SetParent()` 组织层级。 -3. 用 `AddComponent()` 挂功能组件。 -4. 用 `Scene::Update()` / `FixedUpdate()` / `LateUpdate()` 驱动生命周期。 -5. 用 `Scene::SerializeToString()` / `DeserializeFromString()` 保存和恢复。 +2. 用 `SetParent()` 组织层级。 +3. 用 `AddComponent()` 挂普通组件。 +4. 用 `SetTag()` / `CompareTag()` / `SetLayer()` 管理轻量元数据。 +5. 用 `Scene::SerializeToString()` / `DeserializeFromString()` 做整棵树持久化。 -### 非场景测试对象 +### 测试或临时对象 -1. 直接构造 `GameObject`。 -2. 只依赖本地组件访问和 `Transform` 操作。 -3. 不要假定静态查找、场景序列化或自动生命周期已经可用。 +1. 可以直接构造 `GameObject`。 +2. 只依赖本地 `Transform` 与组件操作。 +3. 不要假设全局查询、场景序列化和自动生命周期已经可用。 ## 和 Unity 的关系应该怎么理解 -最合理的理解方式是： +比较准确的表述是： - 它在对象模型上明显借鉴了 Unity。 -- 它提供了足够熟悉的 `GameObject + Transform + Component` 心智模型。 -- 但当前实现仍然比 Unity 轻得多，特别是在 tag/layer 管理、运行时加组件生命周期、完整组件序列化和层级顺序控制上。 +- 它已经提供了足够熟悉的 `GameObject + Transform + Component + tag + layer` 心智模型。 +- 但当前实现仍然比 Unity 更轻，特别是在 tag/layer 管理、运行时加组件生命周期、完整组件序列化和项目级对象分类工具方面。 -把它理解成“Unity 风格、但当前版本能力更收敛的对象系统”是比较准确的。 +把它理解成“Unity 风格、但当前阶段更收敛的商业引擎对象系统”是比较准确的。 ## 从这里继续读什么 @@ -275,4 +275,4 @@ component=Camera;projection=0;fov=60;... - [GameObject](../../XCEngine/Components/GameObject/GameObject.md) - [Component](../../XCEngine/Components/Component/Component.md) - [TransformComponent](../../XCEngine/Components/TransformComponent/TransformComponent.md) -- [ComponentFactoryRegistry](../../XCEngine/Components/ComponentFactoryRegistry/ComponentFactoryRegistry.md) +- [Scene](../../XCEngine/Scene/Scene/Scene.md) diff --git a/docs/api/_guides/Editor/Editor-Architecture-And-Workflow.md b/docs/api/_guides/Editor/Editor-Architecture-And-Workflow.md index 9c6c2bb4..2700d5e8 100644 --- a/docs/api/_guides/Editor/Editor-Architecture-And-Workflow.md +++ b/docs/api/_guides/Editor/Editor-Architecture-And-Workflow.md @@ -2,152 +2,354 @@ ## 先建立正确心智模型 -`docs/api/XCEngine/Editor/**` 对应的是编辑器应用层，而不是引擎运行时 public API。 -它更接近 Unity Editor、Unreal Editor 这类“工具壳层”的实现文档，而不是给游戏逻辑直接链接的稳定 SDK。 +`docs/api/XCEngine/Editor/**` 对应的是编辑器应用层，而不是引擎运行时 public API。 -可以把当前架构粗略理解成六层： +当前这套 Editor 已经不是“只有窗口壳和几块早期 ImGui 面板”的状态。按 `editor/src/**`、`project/` 和当前脚本程序集目录来看，它已经形成了一条真实闭环： -1. `Platform` 负责 Win32 进程、窗口消息、崩溃日志和 D3D12 窗口渲染。 -2. `UI` 负责 ImGui 会话、主题、面板 chrome 和通用控件。 -3. `Core` 负责上下文、事件总线、动作路由、选择和撤销。 -4. `Managers` 负责项目和场景服务的默认实现。 -5. `Actions` 负责把按钮、菜单和快捷键翻译成“可执行动作”。 -6. `Commands` 负责真正修改项目、场景、实体和组件状态。 +`Application` -> `EditorContext` -> `Panels / Actions / Commands` -> `ViewportHostService` -> `Rendering / ResourceManager / ScriptEngine` -`panels`、`Layout` 和 `ComponentEditors` 则横向挂在这些层之间： +同时还和项目目录结构直接对接： -- `panels` 是用户直接看到的编辑器窗口 -- `Layout` 决定这些窗口如何 Dock -- `ComponentEditors` 决定 Inspector 如何按组件类型渲染 +- `Project.xcproject` +- `Assets/` +- `.meta` +- `Library/SourceAssetDB` +- `Library/ArtifactDB` +- `Library/Artifacts` +- `Library/ScriptAssemblies` -## 为什么要拆成 Actions 和 Commands +因此这组文档的重点，不是“介绍一个理想中的未来编辑器”，而是解释当前 checkout 下这条链路已经怎么工作。 -这是当前 Editor 文档里最重要的一条设计线。 -如果不拆，最常见的退化就是： +## 顶层宿主是怎样启动的 -- 菜单栏自己写一套保存逻辑 -- 快捷键自己写一套删除逻辑 -- 右键菜单再写一套复制粘贴逻辑 +[Application](../../XCEngine/Editor/Application/Application.md) 是编辑器进程的组合根。 -时间一长，你会得到三个入口、三份行为、三种 bug。 +它的启动顺序大致是： -当前实现把它拆成： +1. 安装崩溃过滤器并把日志重定向到可执行目录。 +2. 通过 `ResolveEditorProjectRootUtf8()` 解析项目根目录。 +3. 若命令行带 `--project` 或 `-p`，优先使用覆盖路径。 +4. 否则在工作目录或可执行目录向上查找 workspace 根，再优先落到 `/project/`。 +5. 初始化主窗口渲染器、`ResourceManager`、`EditorContext`、脚本运行时、ImGui 和 `ViewportHostService`。 +6. 最后挂接 `EditorLayer`，开始每帧驱动。 -- `EditorActions` 定义动作名称、快捷键和启用状态 -- `ActionRouting` 和 `EditorActionRoute` 决定当前动作应该作用在哪个面板上下文 -- `*ActionRouter` 负责具体入口的 UI 交互 -- `Commands` 负责真正修改状态 +这里最关键的一点是：项目根目录不是由某个面板临时决定，而是宿主层在启动时统一解析并固定下来。当前仓库默认就是随仓维护的 `project/` 示例工程。 -这就是商业编辑器很常见的分层方式。Unity 用户会很容易理解这件事： -菜单项、快捷键和 Inspector 按钮看起来入口不同，但背后应该落到同一条编辑命令语义上。 +## 当前 Editor 的六层结构 -## 为什么 Inspector 不走完全反射，而是组件专用 editor +可以把当前实现理解成六层。 -当前 Inspector 采用的是： +### 1. 宿主层 -- `IComponentEditor` -- `ComponentEditorRegistry` -- `TransformComponentEditor` -- `CameraComponentEditor` -- `LightComponentEditor` +- `Application` +- `Platform` +- `D3D12WindowRenderer` +- `ImGuiBackendBridge` +- `ImGuiSession` -这条路线更接近 Unity 的 custom inspector / property drawer 思想，而不是“把所有字段自动反射成一张表”。 +这一层负责窗口、SwapChain、ImGui 帧边界、项目切换和脚本运行时重载。它不直接实现 Hierarchy、Inspector 或 Project Browser 的业务规则。 -这样做的好处是： +### 2. 上下文与共享服务层 -- 条件式 UI 更自然，例如 Camera 的透视/正交分支 -- 撤销、字段分组和按钮布局更可控 -- 组件编辑体验可以按照组件语义而不是成员变量顺序组织 +- `EditorContext` +- `EventBus` +- `SelectionManager` +- `SceneManager` +- `ProjectManager` +- `UndoManager` -代价是： +`EditorContext` 是当前 Editor 的状态容器。它把事件、选择、场景、项目、撤销和 `ViewportHostService` 指针聚合起来，供面板和动作层统一访问。 -- 每个组件都要写专门 editor -- 通用自动化程度较低 +### 3. 面板与布局层 -但对当前阶段的编辑器，这是更稳妥的商业级做法，因为它优先保证可解释性和可维护性。 +- `PanelCollection` +- `HierarchyPanel` +- `ProjectPanel` +- `InspectorPanel` +- `SceneViewPanel` +- `GameViewPanel` +- `ConsolePanel` -## 从一次用户点击看整条链路 +这一层负责“用户看到什么”，以及把即时模式 UI 交互采样成更稳定的意图。 -以 Hierarchy 中“右键删除实体”为例，当前主路径大致是： +其中 `GameViewPanel` 还有一条额外职责：它会把视口里的键鼠状态采样成 `GameViewInputFrameEvent`，再通过 `PlaySessionController` 桥接到运行时 `InputManager`。这一条链路可以单独看： -1. `HierarchyPanel` 负责渲染树和弹出上下文菜单。 -2. `HierarchyActionRouter` 负责把“Delete”菜单项映射为删除动作。 -3. `EntityCommands::DeleteEntity` 负责发起真正的场景修改。 -4. `UndoUtils` 和 `UndoManager` 负责录制撤销快照。 -5. `SceneManager` 负责真正删除实体并发布事件。 -6. `SelectionManager`、`InspectorPanel` 等其它系统通过事件感知更新。 +- [Game View Runtime Input Bridge](Game-View-Runtime-Input-Bridge.md) -这条链路说明了一个核心原则： -面板不应该直接修改场景，面板应该只描述用户意图。 +### 4. 动作与命令层 -## 为什么当前大量使用小型 helper header +- `Actions::*ActionRouter` +- `Commands::*` -很多用户第一次看会觉得：为什么 `UI`、`Actions`、`Commands` 下有这么多小头文件？ +这层负责把“菜单点击、快捷键、右键菜单、拖放、行内重命名”翻译成统一的编辑语义。典型例子是： -这是 Dear ImGui 风格编辑器常见的工程取舍。原因很现实： +- `HierarchyActionRouter` +- `EntityCommands` +- `ProjectCommands` -- 即时模式 UI 很容易把一切都塞进 `Render()` -- 一旦不拆 helper，单个面板 cpp 会迅速膨胀 -- 把“交互语义”“控件语义”“状态容器”拆成小头文件后，代码更容易复用和迁移 +### 5. 视口宿主层 -所以这些 header 不是“碎片化设计”，而是在对抗 UI 工具代码天然容易失控的问题。 +- `ViewportHostService` +- `SceneViewportOverlayProviders` +- `SceneViewportOverlayBuilder` +- `SceneViewportEditorOverlayPass` +- `SceneViewportPicker` -## 当前架构最像 Unity 的部分 +它把 Scene/Game 视口真正接到引擎的 `Rendering + RHI` 上，同时承接 object-id picking、outline、grid 和世界空间 overlay。 -- `HierarchyPanel / ProjectPanel / InspectorPanel / ConsolePanel` 这组窗口组合很像 Unity Editor 的基本工作区。 -- `ComponentEditors` 很像 Unity 的 custom inspector。 -- `SceneCommands + UndoManager` 很像 Unity 编辑态里对场景对象做结构修改时的命令路径。 +### 6. 引擎与资源层 -## 当前又明显还不像 Unity 的地方 +- `Rendering` +- `ResourceManager` +- `AssetDatabase` +- `ScriptEngine` +- `MonoScriptRuntime` -- 当前只有 Windows + D3D12 + ImGui 主路径。 -- Project 面板还不是完整资产导入系统。 -- Inspector 还没有脚本组件、搜索式 Add Component、批量多选混合值等成熟体验。 -- Console 还是轻量列表，不是完整诊断中心。 +这一层不属于 Editor 自身，但 Editor 当前已经大量依赖它们提供真实能力，而不是自己维护一套独立“简化版运行时”。 -所以更准确的表述应该是： -它采用了很多 Unity 风格的编辑器设计理念，但当前实现仍然是一个处在快速重构期的、轻量但方向正确的编辑器壳层。 +## `EditorActionRoute` 为什么重要 -## 如果你要继续扩展这个编辑器，推荐从哪层下手 +很多旧文档容易忽略 [EditorActionRoute](../../XCEngine/Editor/Core/EditorActionRoute/EditorActionRoute.md)，但它对当前 Inspector 和焦点行为非常关键。 -### 新增一个全新面板 +当前只有三个 route： -通常顺序是： +- `None` +- `Hierarchy` +- `Project` -1. 在 `panels` 下建立新 Panel 类型。 -2. 优先复用 `PanelWindowScope / PanelToolbarScope / PanelContentScope`。 -3. 如果面板需要上下文敏感快捷键，再接入 `ActionRouting`。 -4. 如果面板要真正修改数据，优先写 `Commands`，不要直接改 manager。 +这不是菜单状态，而是“最近一次明确的编辑焦点来自哪里”。 -### 给 Inspector 新增一个组件编辑器 +它直接影响 [InspectorPanel](../../XCEngine/Editor/panels/InspectorPanel/InspectorPanel.md) 的检查对象： -推荐顺序是： +- route 是 `Hierarchy` 时，优先检查当前选中实体。 +- route 是 `Project` 时，优先检查当前选中资源。 +- 当前只有 `Material` 资源拥有专用 inspector；其他资源走 unsupported fallback。 -1. 实现新的 `IComponentEditor`。 -2. 在 `ComponentEditorRegistry` 注册。 -3. 优先通过 `PropertyGrid`、`ScalarControls`、`VectorControls` 组装 UI。 -4. 涉及结构性变化时，通过 `ComponentCommands` 或新的命令 helper 进入撤销链。 +所以 Inspector 现在已经不是“只给 GameObject 用”的面板，而是一个带 subject 切换能力的通用检查器。 -### 给菜单栏或快捷键新增动作 +## 一条典型的 Hierarchy 链路 -推荐顺序是： +以“在 Hierarchy 中重命名实体”为例，当前真实链路大致是： -1. 在 `EditorActions` 中先定义动作描述。 -2. 在合适的 `*ActionRouter` 中接 UI 入口。 -3. 真实变更落到 `Commands`。 -4. 如果动作取决于当前焦点面板，再考虑是否需要新的 `EditorActionRoute`。 +1. `HierarchyPanel` 绘制树节点和行内编辑框。 +2. [HierarchyActionRouter](../../XCEngine/Editor/Actions/HierarchyActionRouter/HierarchyActionRouter.md) 负责解释点击、右键、拖放和 rename 请求。 +3. `RequestEntityRename(...)` 通过 [EventBus](../../XCEngine/Editor/Core/EventBus/EventBus.md) 发布 `EntityRenameRequestedEvent`。 +4. 行内编辑结束后，`CommitEntityRename(...)` 调用 [EntityCommands](../../XCEngine/Editor/Commands/EntityCommands/EntityCommands.md)。 +5. `EntityCommands::RenameEntity(...)` 通过 `UndoUtils::ExecuteSceneCommand(...)` 进入撤销栈。 +6. `SceneManager` 完成真正的场景修改。 +7. 其他面板通过选择状态或事件观察到变化。 -## 当前文档应该怎么读 +这条链路体现了当前 editor 的一个硬边界： -如果你是第一次接触这一套代码，推荐按这个顺序： +- 面板负责呈现和采样。 +- router 负责交互语义。 +- commands 负责稳定的编辑命令。 +- manager 负责真正的数据结构修改。 + +## 一条典型的 Project 链路 + +[ProjectPanel](../../XCEngine/Editor/panels/ProjectPanel/ProjectPanel.md) 不是 `AssetDatabase` 本身，而是 `IProjectManager` 的浏览器前端。 + +当前它的主链路是： + +1. 左侧目录树用 `TreeView` 绘制 folder hierarchy。 +2. 右侧浏览区用 `DrawAssetTile(...)` 绘制当前目录条目。 +3. 顶部工具栏只做当前目录内搜索，不做全项目索引。 +4. 面包屑通过 `NavigateToIndex(...)` 回退到任意路径段。 +5. 重命名、创建文件夹、创建材质、移动资源、删除资源都交给 `ProjectCommands`。 +6. 打开资源、开始拖拽、背景点击等交互交给 `Actions` 层 helper。 + +因此当前 `ProjectPanel` 的定位很清楚： + +- 它负责浏览和编辑入口。 +- 它不自己维护资源数据库。 +- 它依赖 project manager 和命令层维持真实状态。 + +还要建立一个新的工作流边界认知： + +- Project 面板负责资源浏览与资源级编辑 +- 项目级保存和脚本程序集重建仍由主菜单触发 +- 旧文档里提到的场景资源批量迁移入口已经不在当前 editor 工作流中 + +## Inspector 已经不只是组件列表 + +[InspectorPanel](../../XCEngine/Editor/panels/InspectorPanel/InspectorPanel.md) 现在至少有四种 subject mode： + +- `None` +- `GameObject` +- `MaterialAsset` +- `UnsupportedAsset` + +### GameObject 模式 + +这一支仍然是最传统的 Inspector： + +- 遍历实体组件列表。 +- 通过 `ComponentEditorRegistry` 找到对应 `IComponentEditor`。 +- 用 `BeginComponentSection(...)` 组织 section UI。 +- 组件 editor 返回 `true` 时，标记场景 dirty。 +- `Add Component` 弹窗走 `DeferredPopupState` 和 `Actions` helper。 + +### Material 资源模式 + +这一支是旧文档最容易写错的地方。当前实现已经支持直接检查材质资源： + +- 从 `ProjectManager` 取当前选中的 `AssetItem`。 +- 仅当 `item->type == "Material"` 时进入专用 inspector。 +- 通过项目相对路径调用 `ResourceManager::Load()`。 +- 当前可编辑： + - Shader 路径 + - Shader Pass + - Render Queue + - Render State + - Tags +- 每次修改都会立刻写回材质文件，并尽量把变更同步到已加载的 `Material` 资源实例。 + +所以现在 Inspector 已经承担了一部分资源编辑器职责，而不是单纯的 scene component inspector。 + +### ScriptComponent 不是缺席状态 + +旧表述里常见“Inspector 还没有脚本组件”之类的说法，但当前这已经不成立。 + +[ScriptComponentEditor](../../XCEngine/Editor/ComponentEditors/ScriptComponentEditor/ScriptComponentEditor.md) 已经接入当前 Inspector 链路，支持： + +- 脚本类选择 +- 字段模型读取 +- 字段 override 写回 +- 运行时缺失 / 程序集缺失状态提示 +- `Rebuild Scripts` / `Reload Scripts` 入口 + +## 脚本程序集链路已经落地 + +当前脚本相关的关键目录是： + +- `managed/XCEngine.ScriptCore/` +- `managed/GameScripts/` +- `project/Assets/**/*.cs` +- `project/Library/ScriptAssemblies/` + +[Application](../../XCEngine/Editor/Application/Application.md) 在启动、切换项目和显式 reload 时，都会把脚本程序集目录固定到： + +- `/Library/ScriptAssemblies/XCEngine.ScriptCore.dll` +- `/Library/ScriptAssemblies/GameScripts.dll` +- `/Library/ScriptAssemblies/mscorlib.dll` + +若程序集缺失： + +- Editor 不会直接崩溃。 +- `ScriptEngine` runtime 会被清空。 +- `ScriptRuntimeStatus` 会保留错误消息，供 Inspector 和其他 UI 展示。 + +若用户触发 `RebuildScriptingAssemblies()`： + +1. `EditorScriptAssemblyBuilder` 重建项目程序集。 +2. 成功后立即 `ReloadScriptingRuntime()`。 +3. 新 runtime 会重新注册到 `ScriptEngine`。 + +这条链路说明当前脚本系统已经进入“编辑器真实工作流的一部分”，而不是实验性质的旁路功能。 + +## 视口链路也已经从面板里抽出来了 + +旧版 editor 很容易把 SceneView 相关逻辑直接堆进面板文件里，但当前实现已经明显走向规范化。 + +按当前结构，典型流程是： + +1. `Application::Render()` 建立主帧边界。 +2. `LayerStack` 和具体面板产生 Scene / Game 视口请求。 +3. `ViewportHostService::BeginFrame()` 清理并准备本帧视口状态。 +4. `RenderRequestedViewports(...)` 真正调用引擎 `SceneRenderer`。 +5. Scene View 额外接入： + - 编辑器私有相机 + - object-id surface + - outline + - grid + - `SceneViewportOverlayProviders` + - `SceneViewportOverlayBuilder` + - `SceneViewportEditorOverlayPass` + +这意味着： + +- editor 是渲染宿主，不是第二套 renderer。 +- 新的 Scene overlay / gizmo 功能应优先沿 `overlay provider -> overlay builder -> overlay pass` 扩展。 +- 不应再把世界空间绘制逻辑继续回堆到 `SceneViewPanel` 的临时 ImGui 路径。 + +更细一层的 Scene View 输入仲裁、pivot / center、global / local、HUD/world overlay 分层以及 gizmo overlay state 传播关系，可继续看 [SceneView Interaction And Gizmo Model](SceneView-Interaction-And-Gizmo-Model.md)。 + +## 当前项目目录结构不是“伪工作流” + +当前工程目录的几个部分都已经参与真实工作流： + +- `project/Assets/` +- `project/Assets.meta` +- `project/Library/` +- `project/Library/ScriptAssemblies/` +- `Project.xcproject` + +尤其是 `project/Library/`，在当前实现里并不只是可以无脑忽略的临时目录。它至少承接： + +- 资源数据库缓存 +- artifact 缓存 +- 脚本程序集输出 + +因此在 editor 文档里，不应再把 `.meta` 和 `Library/` 描述成“未来才会用到”的规划项。 + +## 如果要继续扩展当前 Editor，应该从哪层下手 + +### 新增一个面板 + +优先顺序通常是： + +1. 在 `panels/` 下新建 panel。 +2. 复用已有 `PanelWindowScope`、`PanelToolbarScope`、`PanelContentScope`。 +3. 若面板要参与焦点切换，再接 `EditorActionRoute`。 +4. 若面板会修改项目或场景，优先接命令层而不是直改 manager。 + +### 给 Inspector 新增一种检查对象 + +优先顺序通常是： + +1. 先确认新的 subject 应由哪条 route 驱动。 +2. 在 `InspectorPanel::SyncSubject()` 里定义切换条件。 +3. 为该资源或组件准备独立渲染函数。 +4. 若涉及文件写回或场景写回，尽量复用现有 `Commands` / `ResourceManager` / `ScriptEngine`。 + +### 给 Hierarchy / Project 增加新动作 + +优先顺序通常是： + +1. 在 `Actions` 层描述入口。 +2. 在 router 里解释 UI 交互。 +3. 在 `Commands` 层集中写实际修改逻辑。 +4. 需要后续 UI 同步时，再通过 `EventBus` 发布事件。 + +## 现在不该再沿用的旧说法 + +以下说法已经不再适合当前活跃文档： + +- “Project 面板还不是完整资产导入系统” +- “Inspector 还没有脚本组件” +- “Editor 仍然只是轻量编辑器壳层” +- “脚本程序集和项目目录结构还在规划中” + +更准确的描述应当是： + +- 当前 Editor 仍在持续重构，但主链路已经真实落地。 +- 高层结构已经能覆盖项目根目录解析、资源浏览、材质资源检查、脚本程序集重建与重载、Scene/Game 视口宿主和 object-id picking。 +- 接下来的工作重点是继续把这些现有能力文档化、模块化，而不是再把它描述成只有方向没有实现的雏形。 + +## 推荐阅读顺序 + +如果要快速建立当前 Editor 的整体认识，推荐按这个顺序读： 1. [Editor](../../XCEngine/Editor/Editor.md) 2. [Application](../../XCEngine/Editor/Application/Application.md) -3. [Core](../../XCEngine/Editor/Core/Core.md) -4. [Actions](../../XCEngine/Editor/Actions/Actions.md) -5. [Commands](../../XCEngine/Editor/Commands/Commands.md) -6. [panels](../../XCEngine/Editor/panels/panels.md) -7. [ComponentEditors](../../XCEngine/Editor/ComponentEditors/ComponentEditors.md) -8. [UI](../../XCEngine/Editor/UI/UI.md) +3. [EventBus](../../XCEngine/Editor/Core/EventBus/EventBus.md) +4. [ProjectPanel](../../XCEngine/Editor/panels/ProjectPanel/ProjectPanel.md) +5. [InspectorPanel](../../XCEngine/Editor/panels/InspectorPanel/InspectorPanel.md) +6. [HierarchyActionRouter](../../XCEngine/Editor/Actions/HierarchyActionRouter/HierarchyActionRouter.md) +7. [EntityCommands](../../XCEngine/Editor/Commands/EntityCommands/EntityCommands.md) +8. [ViewportHostService](../../XCEngine/Editor/Viewport/ViewportHostService/ViewportHostService.md) +9. [SceneView Interaction And Gizmo Model](SceneView-Interaction-And-Gizmo-Model.md) +10. [ScriptComponentEditor](../../XCEngine/Editor/ComponentEditors/ScriptComponentEditor/ScriptComponentEditor.md) -这能让你先看清系统骨架，再下钻到具体类型页，而不是一开始就陷进某个 helper 文件里。 +这样读下来，基本就能把“宿主层、共享状态、面板、动作命令、视口和脚本”这几条主线拼起来。 diff --git a/docs/api/_guides/Editor/Game-View-Runtime-Input-Bridge.md b/docs/api/_guides/Editor/Game-View-Runtime-Input-Bridge.md index 32669903..c2838946 100644 --- a/docs/api/_guides/Editor/Game-View-Runtime-Input-Bridge.md +++ b/docs/api/_guides/Editor/Game-View-Runtime-Input-Bridge.md @@ -2,7 +2,7 @@ 这篇 guide 说明当前 Editor 里 `GameViewPanel -> EventBus -> PlaySessionController -> InputManager` 这条运行时输入桥接链路。 -它不是抽象设计图，而是基于当前 `GameViewPanel.cpp`、`PlaySessionController.cpp` 和 `tests/editor/test_play_session_controller.cpp` 的真实实现整理出来的工作流说明。 +它不是抽象设计图，而是基于当前 `GameViewPanel.cpp`、`PlaySessionController.cpp` 和 `tests/Editor/test_play_session_controller.cpp` 的真实实现整理出来的工作流说明。 ## 参与者 @@ -176,7 +176,7 @@ input.hovered || input.focused ## 当前测试覆盖 -[tests/editor/test_play_session_controller.cpp](D:/Xuanchi/Main/XCEngine/tests/editor/test_play_session_controller.cpp) 当前直接覆盖了两条关键规则： +[tests/Editor/test_play_session_controller.cpp](D:/Xuanchi/Main/XCEngine/tests/Editor/test_play_session_controller.cpp) 当前直接覆盖了两条关键规则： - 非 Play mode 下，`GameViewInputFrameEvent` 不会驱动 `InputManager` - Play mode 下，输入会被桥接，并在空事件后释放 diff --git a/docs/api/_guides/Editor/Scene-View-Interaction-Model.md b/docs/api/_guides/Editor/Scene-View-Interaction-Model.md new file mode 100644 index 00000000..7601dcea --- /dev/null +++ b/docs/api/_guides/Editor/Scene-View-Interaction-Model.md @@ -0,0 +1,20 @@ +# Scene View Interaction Model + +这个页面保留为兼容入口，避免旧链接失效。 + +当前 Scene View 交互模型的 canonical 说明已经统一到： + +- [SceneView Interaction And Gizmo Model](SceneView-Interaction-And-Gizmo-Model.md) + +建议直接阅读新页面，它已经把以下内容收口到同一份说明里： + +- `Pivot / Center` +- `Global / Local` +- 主对象与多选 pivot 规则 +- overlay / scene icon / object-id 的命中优先级 +- editor overlay、gizmo overlay state 与 HUD overlay 的分层 + +## 相关文档 + +- [SceneView Interaction And Gizmo Model](SceneView-Interaction-And-Gizmo-Model.md) +- [SceneViewPanel](../../XCEngine/Editor/panels/SceneViewPanel/SceneViewPanel.md) diff --git a/docs/api/_guides/Editor/Scene-Viewport-Render-Plan-And-Failure-Flow.md b/docs/api/_guides/Editor/Scene-Viewport-Render-Plan-And-Failure-Flow.md new file mode 100644 index 00000000..e3a95185 --- /dev/null +++ b/docs/api/_guides/Editor/Scene-Viewport-Render-Plan-And-Failure-Flow.md @@ -0,0 +1,152 @@ +# Scene View Render Plan And Failure Flow + +## 先建立正确心智模型 + +当前 Scene View 不是“把活动场景直接交给 `SceneRenderer`”这么简单。 + +它真实的工作方式更接近商业引擎编辑器常见的两层结构： + +1. 运行时渲染层 + - 负责把场景和相机变成基础 `CameraRenderRequest` +2. 编辑器附加层 + - 负责网格、selection outline、editor overlay、object-id 与状态文案 + +`SceneViewportRenderPlan` 正是第二层里的一个关键中间件，而当前 `ViewportHostService` 与它之间还多了一层 [SceneViewportRenderPassBundle](../../XCEngine/Editor/Viewport/SceneViewportRenderPassBundle/SceneViewportRenderPassBundle.md)，专门负责持有 grid / outline / overlay renderer 并提供 factory。 + +## 当前主调用链 + +按 `ViewportHostService.h` 当前实现，Scene View 一帧渲染大致是： + +1. `RenderRequestedViewports(...)` 遍历本帧请求过的视口。 +2. `RenderViewportEntry(...)` 检查 `colorView` / `depthView` 是否存在。 +3. 如果是 Scene 视口，进入 `RenderSceneViewportEntry(...)`。 +4. 检查隐藏编辑器 Scene View 相机是否可用。 +5. 检查活动场景是否存在。 +6. `BuildSceneViewportRenderState(...)`： + - 读取 `SceneViewportOverlayData` + - 读取当前选中对象列表 + - 读取 `SceneViewportOverlayFrameData` + - 调用 `m_sceneViewportRenderPassBundle.BuildRenderPlan(...)` + - bundle 内部再调用 `BuildSceneViewportRenderPlan(...)` +7. `SceneRenderer::BuildRenderRequests(...)` 生成基础 request。 +8. `ApplySceneViewportRenderPlan(...)` 把 editor 附加项写回 request。 +9. `SceneRenderer::Render(requests)` 执行真正的场景渲染。 +10. `MarkSceneViewportRenderSuccess(...)` 回写颜色状态、object-id 状态和有效标记。 + +## `SceneViewportRenderPlan` 到底负责什么 + +它当前只负责三类附加项： + +- `postScenePasses` + - 无限网格 + - selection outline +- `overlayPasses` + - editor overlay +- clear-color override + - 默认 Scene View 背景色是 `(0.27, 0.27, 0.27, 1.0)` + +这意味着它不是 Scene View 的全部流程，只是“把 Scene View 专属附加能力组织成一个可应用的 plan”。 + +## 为什么要有默认 clear-color override + +因为 Scene View 的定位不是游戏运行结果，而是编辑工作台。 + +如果完全复用场景相机自己的 clear 语义，编辑体验会出现两个问题： + +- 背景风格可能随场景内容波动，不稳定 +- 编辑器 overlay、gizmo、网格失去统一视觉基底 + +当前默认灰色背景，是典型的编辑器视图设计：优先保证工作环境一致性，再叠加运行时内容。 + +## 为什么 warning 不直接终止渲染 + +一个很典型的例子是： + +- 选中了对象 +- 需要 selection outline +- 但 `objectIdShaderView` 不可用 + +这时当前实现不会直接让 Scene View 失败，而是： + +- 返回 warning `Scene object id shader view is unavailable` +- 继续保留网格、主场景和 overlay 的正常渲染 + +这是编辑器设计里非常关键的原则：**局部能力缺口优先降级，而不是整页黑屏**。 + +## 失败回退是怎么接进来的 + +Scene View 的失败回退不在 `SceneViewportRenderPlan` 自己内部处理，而是交给： + +- [ViewportHostRenderFlowUtils](../../XCEngine/Editor/Viewport/ViewportHostRenderFlowUtils/ViewportHostRenderFlowUtils.md) + +其中最关键的策略包括： + +- `BuildSceneViewportRenderFailurePolicy(...)` +- `ApplyViewportFailureStatus(...)` +- `InvalidateViewportObjectIdFrame(...)` +- `MarkSceneViewportRenderSuccess(...)` + +也就是说： + +- render plan 负责“本帧附加画什么” +- flow utils 负责“失败时怎么退、成功后怎么收尾” + +这样的分工会让 Scene View 主链更稳。 + +## 为什么要把 Build 和 Apply 分开 + +如果把 plan 构建和 request 写回混成一个函数，短期看代码会少一些，但长期会带来三个问题： + +1. 很难单独测试规划逻辑 +2. 很容易在复用 `CameraRenderRequest` 时留下脏指针 +3. `ViewportHostService` 会重新变成一大段条件拼装代码 + +当前拆成： + +- `BuildSceneViewportRenderPlan(...)` +- `ApplySceneViewportRenderPlan(...)` + +本质上是在把“决策”和“接线”分离。这种拆法在商业引擎里很常见，因为它更容易维护，也更适合持续往 Scene View 里加新能力。 + +## Game View 为什么不用这套 plan + +Game View 的目标是尽量忠实呈现运行时相机结果，所以它没有： + +- editor 私有背景 +- 网格 +- selection outline +- gizmo overlay + +因此它直接走 `SceneRenderer`，成功后只做最基本的颜色状态回写与 object-id 失效处理。 + +## 当前最重要的设计收益 + +现在这套链路真正带来的收益不是“代码更优雅”，而是三个更现实的好处： + +- Scene View 可以在局部能力缺失时尽量继续工作 +- 编辑器附加渲染和运行时场景渲染保持分层 +- 每一层都可以被单独测试和文档化 + +这正是商业级编辑器最需要的特征：稳定、可诊断、可扩展。 + +## 建议阅读顺序 + +1. [ViewportHostService](../../XCEngine/Editor/Viewport/ViewportHostService/ViewportHostService.md) +2. [ViewportHostService::RenderRequestedViewports](../../XCEngine/Editor/Viewport/ViewportHostService/RenderRequestedViewports.md) +3. [SceneViewportRenderPassBundle](../../XCEngine/Editor/Viewport/SceneViewportRenderPassBundle/SceneViewportRenderPassBundle.md) +4. [SceneViewportRenderPlan](../../XCEngine/Editor/Viewport/SceneViewportRenderPlan/SceneViewportRenderPlan.md) +5. [BuildSceneViewportRenderPlan](../../XCEngine/Editor/Viewport/SceneViewportRenderPlan/BuildSceneViewportRenderPlan.md) +6. [ApplySceneViewportRenderPlan](../../XCEngine/Editor/Viewport/SceneViewportRenderPlan/ApplySceneViewportRenderPlan.md) +7. [ViewportHostRenderFlowUtils](../../XCEngine/Editor/Viewport/ViewportHostRenderFlowUtils/ViewportHostRenderFlowUtils.md) +8. [ApplySceneViewportRenderRequestSetup](../../XCEngine/Editor/Viewport/ViewportHostRenderFlowUtils/ApplySceneViewportRenderRequestSetup.md) +9. [MarkSceneViewportRenderSuccess](../../XCEngine/Editor/Viewport/ViewportHostRenderFlowUtils/MarkSceneViewportRenderSuccess.md) + +## 相关文档 + +- [Editor Architecture And Workflow](Editor-Architecture-And-Workflow.md) +- [SceneView Interaction And Gizmo Model](SceneView-Interaction-And-Gizmo-Model.md) +- [Viewport](../../XCEngine/Editor/Viewport/Viewport.md) +- [ViewportHostService](../../XCEngine/Editor/Viewport/ViewportHostService/ViewportHostService.md) +- [SceneViewportRenderPassBundle](../../XCEngine/Editor/Viewport/SceneViewportRenderPassBundle/SceneViewportRenderPassBundle.md) +- [SceneViewportRenderPlan](../../XCEngine/Editor/Viewport/SceneViewportRenderPlan/SceneViewportRenderPlan.md) +- [ViewportHostRenderFlowUtils](../../XCEngine/Editor/Viewport/ViewportHostRenderFlowUtils/ViewportHostRenderFlowUtils.md) diff --git a/docs/api/_guides/Editor/SceneView-Interaction-And-Gizmo-Model.md b/docs/api/_guides/Editor/SceneView-Interaction-And-Gizmo-Model.md index d1a5e95a..72b84255 100644 --- a/docs/api/_guides/Editor/SceneView-Interaction-And-Gizmo-Model.md +++ b/docs/api/_guides/Editor/SceneView-Interaction-And-Gizmo-Model.md @@ -88,7 +88,7 @@ ### 2. 当前帧 gizmo state -这是 `SceneViewPanel` 每帧通过 `SetSceneViewTransformGizmoOverlayState(...)` 写回宿主服务的数据。它保存的是： +这是 `SceneViewportTransformGizmoCoordinator` 每帧通过 `RefreshAndSubmitSceneViewportTransformGizmoFrame(...)` / `SubmitSceneViewportTransformGizmoOverlaySubmission(...)` 间接写回宿主服务的数据。它保存的是： - 当前是否显示 move / rotate / scale gizmo - 各自的 draw data diff --git a/docs/api/_guides/Input/Input-Flow-and-Frame-Semantics.md b/docs/api/_guides/Input/Input-Flow-and-Frame-Semantics.md index 04191eb7..1ac8aa8e 100644 --- a/docs/api/_guides/Input/Input-Flow-and-Frame-Semantics.md +++ b/docs/api/_guides/Input/Input-Flow-and-Frame-Semantics.md @@ -1,83 +1,261 @@ # Input Flow And Frame Semantics -## 这套输入系统怎么理解 +## 这篇指南解决什么问题 -当前 XCEngine 输入系统更接近“轻量级、同步、帧驱动的输入管理器”，而不是完整设备抽象框架。 +这篇文档不是“列 API 名称”，而是解释 XCEngine 当前输入系统到底按什么规则工作。它直接基于当前这些实现和测试： -它有两个核心层： +- `engine/src/Input/InputManager.cpp` +- `engine/include/XCEngine/Input/InputManager.h` +- `tests/Input/test_input_manager.cpp` -- `InputModule` 负责接平台消息。 -- `InputManager` 负责保存状态并提供事件与查询接口。 +如果你在游戏层、编辑器运行态桥接、脚本绑定或平台输入后端里使用 `InputManager`，最重要的不是记住方法名，而是先建立一致的语义模型。 -这意味着真正的输入流向是： +## 设计理念 -1. 平台窗口系统产生命令或消息。 -2. 平台后端把消息翻译成 `ProcessKeyDown`、`ProcessMouseMove` 一类调用。 -3. `InputManager` 更新状态并同步广播事件。 -4. 游戏或工具层在当前帧读取轮询状态。 -5. `Update()` 在帧边界清理瞬时状态。 +当前输入系统刻意做成两层： -## 为什么同时保留事件和轮询 +- `InputModule` + - 负责接平台消息，把 `WM_KEYDOWN`、`WM_MOUSEMOVE` 这类原始系统消息翻译成引擎调用 +- `InputManager` + - 负责保存状态、提供轮询 API、同步分发事件 -事件和轮询各有适合的地方： +这种设计接近商业引擎里常见的“平台适配层 + 游戏语义层”分工。好处是： -- UI、输入法、编辑器面板更适合订阅事件。 -- 游戏逻辑、相机控制、角色移动更适合每帧轮询。 +- 游戏逻辑和编辑器逻辑不需要直接依赖 Win32 之类的平台细节 +- 平台后端可以替换，输入查询接口可以保持稳定 +- 轮询和事件可以共享同一份底层状态，不需要上层再维护第二套缓存 -`InputManager` 同时提供这两种方式，是为了避免你在上层自己重复维护一套输入缓存。 +从使用风格上看，它也明显借鉴了 Unity 旧版 `Input Manager` 的思想： -## 帧边界怎么理解 +- 支持具名轴，如 `Horizontal`、`Vertical` +- 支持具名按钮，如 `Jump`、`Fire1` +- 以 `GetAxis()`、`GetButton()` 一类游戏层查询接口为中心 -当前实现里，`Update()` 不是“采集输入”，而是“结束上一帧的瞬时状态”。 +但它当前还是一个轻量级、同步、帧驱动的输入管理器，不是完整的设备抽象框架。 -它会清理： +## 输入流到底怎么走 -- `IsKeyPressed` 依赖的本帧按下标记 -- `IsMouseButtonClicked` 依赖的本帧点击标记 -- `GetMouseDelta` -- `GetMouseScrollDelta` +当前一帧内的典型流向是： -所以最重要的实践是： +1. 平台窗口系统产生键盘、鼠标消息。 +2. 平台后端把消息翻译成 `ProcessKeyDown()`、`ProcessKeyUp()`、`ProcessMouseMove()`、`ProcessMouseButton()`、`ProcessMouseWheel()` 等调用。 +3. `InputManager` 立即更新内部缓存，并同步触发 `OnKeyEvent()`、`OnMouseMove()` 等事件。 +4. 游戏逻辑、编辑器运行态桥接或脚本绑定在当前帧查询 `IsKeyDown()`、`GetAxis()`、`GetButtonDown()` 等 API。 +5. 帧末或统一帧边界调用 `Update()`，清空瞬时输入缓存，准备下一帧。 -- 每帧只调用一次 `Update()`。 -- 保持调用时机一致。 -- 在清理之前，先消费掉当前帧的瞬时输入。 +这说明一个关键点：`Update()` 不是“收集输入”，而是“推进帧边界并清空瞬时状态”。 -## 和 Unity 的对照 +## 为什么同时提供事件和轮询 -从使用方式上看，`InputManager` 很像 Unity 旧版 Input Manager： +商业级引擎通常不会强迫所有系统只用一种输入风格。XCEngine 当前的取舍也是一样： -- 有具名轴：`Horizontal`、`Vertical` -- 有具名按钮：`Jump`、`Fire1`、`Fire2`、`Fire3` -- 查询接口偏向 `GetAxis` / `GetButton` +- 事件更适合 UI、文本输入、编辑器面板、平台桥接 +- 轮询更适合角色移动、相机控制、游戏规则判断 -但当前实现并不等同于 Unity： +`InputManager` 把两者放在同一个状态中心里，能减少几类常见问题： -- 没有平滑、重力、灵敏度、死区等高级参数。 -- `GetAxisRaw` 当前只在“按下这一帧”返回非零，不等同于 Unity 中“原始持续值”的语义。 -- `Mouse X` 和 `Mouse Y` 默认虽然被注册了，但当前实现并不会通过鼠标移动更新它们。 +- 上层不需要再手写“本帧按下 / 本帧释放”缓存 +- 事件订阅者和轮询调用者看到的是同一组真实状态 +- 平台输入桥接和游戏输入消费不需要重复实现状态机 -## 平台桥接是怎么接进来的 +## 帧边界语义 -`InputModule` 的意义是把平台消息层隔离掉。当前 Windows 路径里： +当前实现里，`Update()` 会清理这些瞬时状态： -- `WindowsInputModule::HandleMessage` 负责处理 `WM_KEYDOWN`、`WM_MOUSEMOVE`、`WM_MOUSEWHEEL` 等消息。 -- 它再调用 `InputManager::Process*` 统一更新状态。 +- `m_keyDownThisFrame` +- `m_keyUpThisFrame` +- `m_mouseButtonDownThisFrame` +- `m_mouseButtonUpThisFrame` +- `m_mouseDelta` +- `m_mouseScrollDelta` -这样做的好处是： +因此下面这些接口都天然是“本帧有效，过帧清空”： -- 游戏层不用知道 Win32 消息细节。 -- 将来如果换 GLFW、SDL 或其它平台层，`InputManager` 可以不变。 +- `IsKeyPressed()` +- `IsKeyReleased()` +- `IsMouseButtonClicked()` +- `IsMouseButtonReleased()` +- `GetButtonDown()` +- `GetButtonUp()` +- `IsAnyKeyPressed()` +- `GetMouseDelta()` +- `GetMouseScrollDelta()` + +推荐实践只有三条，但都很重要： + +1. 每帧只调用一次 `Update()` +2. 保持调用时机稳定，不要一会儿逻辑前一会儿逻辑后 +3. 先消费瞬时输入，再执行 `Update()` + +## 四类最常用的输入语义 + +先按语义理解 API，比按方法名死记更可靠。 + +| 语义 | 典型 API | 当前真正含义 | +|------|------|------| +| 按住态 | `IsKeyDown()`、`IsMouseButtonDown()`、`GetButton()`、`GetAxis()`、`GetAxisRaw()`、`IsAnyKeyDown()` | 当前是否仍处于按住状态 | +| 抬起态 | `IsKeyUp()`、`IsMouseButtonUp()` | 当前没有按住，不包含“本帧刚释放”含义 | +| 按下边沿 | `IsKeyPressed()`、`IsMouseButtonClicked()`、`GetButtonDown()`、`IsAnyKeyPressed()` | 本帧出现按下消息 | +| 释放边沿 | `IsKeyReleased()`、`IsMouseButtonReleased()`、`GetButtonUp()` | 本帧出现释放消息 | + +这也是很多团队最容易踩错的地方：`Up` 和 `Released` 不是同义词。 + +## `Up` 和 `Released` 为什么必须分开 + +这是当前模块最需要讲透的概念。 + +- `IsKeyUp()` / `IsMouseButtonUp()` + - 只表示“现在没有按住” + - 本质上等价于 `!IsKeyDown()` / `!IsMouseButtonDown()` + - 即使未初始化或索引越界，当前实现里也会表现为 `true` +- `IsKeyReleased()` / `IsMouseButtonReleased()` + - 只表示“这一帧刚收到释放消息” + - 由 `ProcessKeyUp()` / `ProcessMouseButton(..., false, ...)` 写入 + - 会在下一次 `Update()` 时被清空 + +为什么商业引擎通常都要保留这两套语义： + +- “当前没按住”适合状态判断 +- “这一帧刚释放”适合一次性触发逻辑 + +例如“角色是否仍在蓄力”更像 `IsKeyDown()` / `IsKeyUp()` 问题；“松开蓄力键时发射一次”则应该看 `IsKeyReleased()`。 + +## `Pressed` 当前到底是不是“首次按下” + +不是严格意义上的“首次物理按下”。 + +源码里 `ProcessKeyDown()` 的当前行为是： + +- 无论 `repeat` 为 `true` 还是 `false` +- 都会把 `m_keyDown[index] = true` +- 也都会把 `m_keyDownThisFrame[index] = true` + +这带来一个很关键的结果： + +- `IsKeyPressed()` +- `GetButtonDown()` +- `IsAnyKeyPressed()` + +它们当前表达的更准确含义是“这一帧收到了按下消息”，而不是“从这次物理按下开始到松开之前只触发一次”。 + +如果平台在后续帧继续发送自动重复 `KeyDown`： + +- `OnKeyEvent()` 会把事件类型标成 `KeyEvent::Repeat` +- 但按下边沿缓存仍会被写入 +- 所以上述查询接口仍可能在这些帧再次返回 `true` + +如果业务真的需要“严格首次按下”，需要在平台层或更高层自己过滤 repeat。 + +## 轴和按钮映射的真实行为 + +### 逻辑轴 + +当前 `RegisterAxis()` 把一个名字映射到“正方向键 + 负方向键”。 + +`GetAxis()` 和 `GetAxisRaw()` 目前都直接读 `IsKeyDown()`： + +- 正方向键按住时加 `1.0f` +- 负方向键按住时减 `1.0f` +- 同时按下则抵消为 `0.0f` + +当前两者没有行为差异。它们都： + +- 不读取 `InputAxis::m_value` +- 不做平滑、重力、灵敏度或死区处理 +- 不会因为只是“本帧刚按下”而产生非零值 + +这和很多商业引擎早期的“raw axis / smoothed axis”区分还不一样，当前实现更接近“两个名字不同但逻辑相同的持续态接口”。 + +### 逻辑按钮 + +当前 `RegisterButton()` 只是把名字映射到一个 `KeyCode`。 + +- `GetButton()` 转发到 `IsKeyDown()` +- `GetButtonDown()` 转发到 `IsKeyPressed()` +- `GetButtonUp()` 转发到 `IsKeyReleased()` + +因此按钮系统当前不是独立状态机，而只是对键盘查询的命名包装。 + +## 和 Unity 的关系 + +如果你熟悉 Unity，这里最容易建立直觉，但也最容易因为“看起来像”而误判。 + +相似点： + +- 都有具名轴和具名按钮 +- 都强调游戏层直接查询，而不是让业务处理原始平台消息 +- 都适合快速搭建角色控制、相机控制和简单交互 + +不同点： + +- 当前没有 Unity 旧版 Input Manager 里的 gravity、sensitivity、dead zone、snap 等参数 +- `GetAxisRaw()` 目前并不比 `GetAxis()` 更“底层”，两者等价 +- 默认注册的 `Mouse X` / `Mouse Y` 还没有绑定到鼠标移动增量 +- `GetButtonUp()` 是释放边沿，不是“当前按钮没按着就算 up” + +所以，当前更适合把它理解成“Unity 风格接口外观 + XCEngine 当前真实实现语义”，而不是直接按 Unity 经验套用全部行为。 + +## `any-key` 目前到底统计什么 + +当前 `any-key` 会把鼠标按钮也算进去。 + +- `IsAnyKeyDown()` + - 扫描 `m_keyDown` 和 `m_mouseButtonDown` +- `IsAnyKeyPressed()` + - 扫描 `m_keyDownThisFrame` 和 `m_mouseButtonDownThisFrame` + +它目前不包含： + +- 触摸 +- 滚轮 +- 文本输入 +- 摇杆或手柄输入 + +同时，`IsAnyKeyPressed()` 也继承键盘 repeat 语义。只要平台后端在某一帧再次调用 `ProcessKeyDown()`，它就可能再次成立。 + +## 默认映射与当前落地程度 + +初始化后默认注册这些逻辑项： + +- 轴 + - `Horizontal`: `D / A` + - `Vertical`: `W / S` + - `Mouse X`: `None / None` + - `Mouse Y`: `None / None` +- 按钮 + - `Jump`: `Space` + - `Fire1`: `LeftCtrl` + - `Fire2`: `LeftAlt` + - `Fire3`: `LeftShift` + +这说明当前默认配置的实际可用性是分层的： + +- `Horizontal` / `Vertical` 可以直接驱动基础移动逻辑 +- `Jump` / `Fire1-3` 可以直接用于具名按钮查询 +- `Mouse X` / `Mouse Y` 当前更像预留命名位，而不是已经接通的鼠标轴 + +## 平台桥接为什么值得保留独立层 + +当前 Windows 路径里，`WindowsInputModule::HandleMessage()` 会把 Win32 消息翻译成 `InputManager::Process*()` 调用。 + +这种分层设计的直接收益是： + +- 游戏层不用理解平台消息细节 +- 测试可以绕开平台窗口系统，直接驱动 `InputManager::Process*()` 来验证行为 +- 将来替换平台层时，输入消费方可以尽量保持不变 + +这也是为什么现有测试大多直接命中 `InputManager`，而不是依赖完整窗口消息环境。 ## 当前版本最该知道的限制 -- `KeyCode` 底层值当前有重复，部分键会共享状态槽。 +- `KeyCode` 底层值当前存在重复项，部分按键会共享状态槽。 - Windows 路径当前不能准确区分左右 Ctrl / Alt / Shift。 -- 触摸与摇杆接口基本是预留位。 -- 事件回调是同步执行的，不是异步消息队列。 -- `Shutdown()` 当前不会清空事件监听器；如果单例跨生命周期反复初始化，要自己管理订阅者。 +- 触摸与摇杆接口大多还是预留位。 +- 事件回调同步执行，不是异步消息队列。 +- `Shutdown()` 会清空状态和映射，但不会清空事件监听器。 +- `ClearAxes()` 当前会同时清空轴和按钮映射。 -## 推荐使用方式 +## 推荐接入方式 初始化阶段： @@ -97,7 +275,15 @@ windowsInputModule.HandleMessage(hwnd, msg, wParam, lParam); ```cpp if (InputManager::Get().GetButton("Jump")) { - // ... + // 持续按住态 +} + +if (InputManager::Get().GetButtonDown("Jump")) { + // 本帧按下边沿 +} + +if (InputManager::Get().GetButtonUp("Jump")) { + // 本帧释放边沿 } ``` @@ -107,6 +293,8 @@ if (InputManager::Get().GetButton("Jump")) { InputManager::Get().Update(deltaTime); ``` +如果你把 `Update()` 放错位置，或者在同一帧里调用多次，最先出问题的通常就是 `Pressed` / `Released` / `MouseDelta` 这些瞬时语义。 + ## 相关 API - [Input](../../XCEngine/Input/Input.md) diff --git a/docs/api/_guides/Rendering/Camera-Request-Planning-And-Clear-Rules.md b/docs/api/_guides/Rendering/Camera-Request-Planning-And-Clear-Rules.md new file mode 100644 index 00000000..f23880e5 --- /dev/null +++ b/docs/api/_guides/Rendering/Camera-Request-Planning-And-Clear-Rules.md @@ -0,0 +1,171 @@ +# Camera Request Planning And Clear Rules + +## 这条链路现在是谁在负责什么 + +当前 XCEngine 的相机渲染不是“场景直接丢给主管线”这么简单，而是拆成了三层： + +1. `SceneRenderRequestPlanner` 负责决定“这次到底要渲染哪些相机”。 +2. `SceneRenderRequestUtils` 负责决定“这些相机怎样排序、怎样推导 clear、怎样落成 request”。 +3. `SceneRenderer` 负责把 request 组织好，再交给 `CameraRenderer` 真正执行。 + +这种拆法和商业级引擎里常见的“规划层 / 执行层”是同一路思路。原因很现实： + +- 场景侧关心的是相机选择、排序、stack 规则、viewport 解析。 +- 执行侧关心的是 scene extraction、pipeline、object-id、post pass、overlay pass。 +- 如果把这两类职责揉在一个类里，Editor 叠加 pass、离屏目标、手工 request 提交都会很快失控。 + +当前源码正是按这个边界实现的： + +- `SceneRenderer::BuildRenderRequests(...)` + - 直接委托给 `SceneRenderRequestPlanner::BuildRequests(...)` +- `SceneRenderer::Render(const std::vector&)` + - 只做 request 校验、稳定排序和逐条转发 +- `CameraRenderer::Render(...)` + - 才真正做 `RenderSceneExtractor`、主管线、object-id、post / overlay sequence + +## override camera 的真实语义 + +`overrideCamera` 不是“无条件强制渲染这台相机”，而是“如果这台相机当前可用，就只渲染它；否则退回场景相机收集”。 + +可用性的判定来自 `SceneRenderRequestUtils::IsUsableCamera()`，当前必须同时满足： + +- 相机指针非空 +- 组件启用 +- 挂载的 `GameObject` 非空 +- `GameObject::IsActiveInHierarchy()` 为真 + +这很重要，因为它解释了为什么 `overrideCamera` 被禁用或所在对象失活时，系统不会报错，而是自动回退到 `scene.FindObjectsOfType()`。 + +`tests/Rendering/unit/test_scene_render_request_planner.cpp` 已经明确覆盖了这两个分支： + +- `UsesOverrideCameraExclusivelyWhenItIsUsable` +- `FallsBackToSceneCamerasWhenOverrideCameraIsNotUsable` + +## 相机排序为什么是 Base 在前、Overlay 在后 + +当前排序规则非常直接，而且是源码写死的： + +- 场景相机排序：`stackType -> depth` +- request 排序：`cameraStackOrder -> cameraDepth` + +这里 `CameraStackType::Base = 0`，`CameraStackType::Overlay = 1`，因此自然得到： + +- 所有 base camera 先画 +- 所有 overlay camera 后画 +- 同一 stack 内再按 `depth` 升序 + +排序函数都使用 `std::stable_sort()`。这意味着如果排序键完全相同，系统会保留原始相对顺序。 + +这条“稳定性”不是小细节，而是编辑器和复杂场景里很重要的可预期性来源： + +- 从场景收集来的相机，tie 时保留场景遍历顺序 +- 手工提交的 request 数组，tie 时保留调用方提交顺序 + +测试已经分别验证了这两种稳定性： + +- `SceneRenderRequestPlanner_Test.CollectsOnlyUsableSceneCamerasInStableRenderOrder` +- `SceneRenderer_Test.PreservesSceneTraversalOrderForEqualPriorityCameras` +- `SceneRenderer_Test.PreservesManualSubmissionOrderForEqualPriorityRequests` + +这和很多商业引擎的设计取向一致。即使当前还没有完整 camera stacking 依赖图，也先保证“线性规则简单、稳定、可预测”。 + +## Auto clear 为什么不是所有相机都清 Color + +`CameraClearMode::Auto` 的真实语义，不是“总是清屏”，而是“按当前 request 在整次提交里的位置推导一个最保守、最稳定的默认值”。 + +当前实现的规则是： + +- 显式 `ColorAndDepth`：返回 `RenderClearFlags::All` +- 显式 `DepthOnly`：返回 `RenderClearFlags::Depth` +- 显式 `None`：返回 `RenderClearFlags::None` +- `Auto` + - 对 base camera：如果此前还没有成功渲染过 base camera，则 `All`，否则 `Depth` + - 对 overlay camera：如果这是整次提交里的第一个成功 request，则 `All`，否则 `Depth` + +这有两个很现实的工程收益。 + +第一，正常的 base camera 链不会重复清颜色。后续 base camera 只清 depth，就能保留前面已经写好的颜色目标。 + +第二，纯 overlay 场景也不会黑屏或叠脏数据。如果场景里根本没有 base camera，第一个 overlay 仍然会退回到 `All`，保证有一个可预测的起始帧。 + +对应测试锚点是： + +- `SceneRenderRequestUtils_Test.ResolvesClearFlagsForExplicitAndAutoModes` +- `SceneRenderer_Test.RendersBaseCamerasBeforeOverlayCamerasAndResolvesAutoClearPerStackType` +- `SceneRenderer_Test.FallsBackToColorClearForFirstOverlayCameraWhenNoBaseCameraExists` + +## viewport 和 render area 是怎样组合出来的 + +这套系统当前把 `RenderSurface` 当成“输出模板”，而不是最终固定矩形。 + +`BuildCameraRenderRequest()` 会先拷贝调用方传入的 `surface`，再把其中的 `renderArea` 改成当前相机对应的子区域。这个子区域来自： + +- 相机的归一化 `viewportRect` +- 父 `RenderSurface` 当前已经存在的 `renderArea` + +换句话说，它支持“在已有 render area 上再切相机子视口”，而不是只能对整张 surface 做 0..1 映射。 + +当前实现细节是： + +- 左上边界用 `floor` +- 右下边界用 `ceil` + +这样做的好处是边界更稳定，不容易因为浮点截断把应该覆盖到的最后一列 / 最后一行像素吃掉。 + +如果最终算出来的 render area 宽或高为 `0`，这条 request 会被直接丢弃。 + +关键点在于：被丢弃的 base camera 不会推进 `renderedBaseCameraCount`。因此后面的相机 clear 推导仍然基于“真正成功进入请求队列的相机”，不会因为一个零尺寸视口把整条 clear 链搞错。 + +这个行为在下面两条测试里都有明确验证： + +- `SceneRenderRequestPlanner_Test.BuildsRequestsAndDropsZeroSizedViewportsWithoutBreakingClearFlow` +- `SceneRenderRequestUtils_Test.BuildsRequestMetadataAndRejectsZeroSizedRenderAreas` + +## 为什么 `SceneRenderer` 还要对手工 request 再排一次序 + +看起来调用方既然已经自己构造了 `std::vector`，似乎可以按原顺序直接执行。 + +当前实现没有这么做，而是仍然会： + +1. 检查每条 request 的 `IsValid()` +2. 复制一份数组 +3. 用 `SceneRenderRequestUtils::SortCameraRenderRequests(...)` 做稳定排序 +4. 再逐条交给 `CameraRenderer` + +这样做不是多余，而是为了把“相机优先级规则”固定在一个地方。 + +它带来的好处是： + +- 从场景自动生成的 request 和手工注入的 request 遵循同一排序语义 +- Editor、工具链、离屏渲染代码不必自己复制一套 stack/depth 规则 +- 即使外部提交顺序混乱，只要 request 元数据是正确的，最终执行顺序仍然一致 + +测试 `SceneRenderer_Test.SortsManualCameraRequestsByDepthBeforeRendering` 和 `SceneRenderer_Test.PreservesManualSubmissionOrderForEqualPriorityRequests` 就是在验证这条契约。 + +## 当前这套模型的边界 + +这条链路已经合理，但还不是完整商业引擎的最终形态。当前边界很明确： + +- 没有更复杂的 camera dependency graph +- 没有跨帧的 request 缓存或 render graph +- `SceneRenderRequestPlanner` 不会自动补 object-id、post passes、overlay passes +- `SceneRenderer` 不负责 scene extraction 和具体 pipeline 细节 +- `CameraRenderer` 只执行单个 request，不负责多相机策略 + +这其实是一个健康的中间阶段。它先把最容易失控的职责边界分干净，再在每一层之上继续增强。 + +如果以后要往更商业化的方向演进，最自然的扩展点通常会是： + +- 更完整的 camera stacking 依赖 +- 更显式的 renderer asset / render pipeline asset 配置 +- 更系统的 request graph / frame graph +- 更成熟的 Scene View 和 runtime camera 共用编排模型 + +## 相关 API + +- [Rendering](../../XCEngine/Rendering/Rendering.md) +- [SceneRenderer](../../XCEngine/Rendering/SceneRenderer/SceneRenderer.md) +- [SceneRenderRequestPlanner](../../XCEngine/Rendering/SceneRenderRequestPlanner/SceneRenderRequestPlanner.md) +- [SceneRenderRequestUtils](../../XCEngine/Rendering/SceneRenderRequestUtils/SceneRenderRequestUtils.md) +- [CameraRenderRequest](../../XCEngine/Rendering/CameraRenderRequest/CameraRenderRequest.md) +- [CameraRenderer](../../XCEngine/Rendering/CameraRenderer/CameraRenderer.md) diff --git a/docs/api/_guides/Scene/Scene-Lifecycle-And-Serialization.md b/docs/api/_guides/Scene/Scene-Lifecycle-And-Serialization.md index 1c78a52a..d25418c3 100644 --- a/docs/api/_guides/Scene/Scene-Lifecycle-And-Serialization.md +++ b/docs/api/_guides/Scene/Scene-Lifecycle-And-Serialization.md @@ -4,80 +4,164 @@ 商业级游戏引擎很少把“场景”“对象”“组件”揉成一个类。更常见的拆法是： -- 场景负责对象集合、根节点入口和存档边界。 -- 对象负责层级关系与生命周期转发。 -- 组件负责真正的可组合行为。 +- 场景负责对象集合、根入口、更新驱动与存档边界 +- 对象负责层级关系、激活传播与生命周期分发 +- 组件负责可组合行为本身 -`XCEngine` 当前的 `Scene` / `GameObject` / `Component` 关系基本就是这个思路，所以它看上去会比较像 Unity 风格的设计，而不是传统单一 Entity 容器。 +`XCEngine` 当前的 `Scene` / `GameObject` / `Component` 关系就是这个思路，所以它在心智模型上明显更像 Unity 风格对象系统，而不是单一 Entity 容器。 ## `Scene` 真正负责什么 -当前 `Scene` 最核心的职责有三件事： +当前 `Scene` 最核心的职责有四件事： 1. 持有 `GameObject` 的唯一所有权。 -2. 从根对象入口驱动 `Update` / `FixedUpdate` / `LateUpdate`。 -3. 作为保存和加载的边界，把一整棵对象树序列化出去或重新建回来。 +2. 维护根对象入口与按 ID 查找能力。 +3. 从根入口驱动 `Update` / `FixedUpdate` / `LateUpdate`。 +4. 作为完整对象树的保存与加载边界。 -这样做的好处是，场景可以被理解成“一个可整体保存、整体切换的运行时世界片段”。 +这样做的好处是，场景可以被理解成“一个可整体切换、整体保存、整体重新加载的运行时世界片段”。 -## 为什么要有根对象列表 +## 为什么要同时保存对象表和根列表 -场景里既有对象树，又单独保存 `m_rootGameObjects`，这不是重复设计，而是为了让两件事都变简单： +场景里既有 `m_gameObjects`，又单独保存 `m_rootGameObjects`，这不是重复设计，而是为了把两类操作都做得更直接： -- 查“从哪里开始遍历场景”时，不用扫描全体对象找没有父节点的项。 -- 对象挂接和脱离父节点时，只要同步更新根列表即可。 +- 按 ID 找对象时，不需要遍历层级树 +- 从场景入口开始递归更新、递归序列化时，不需要扫描所有对象去找“谁没有父节点” -这是很多商用引擎场景树都会采用的做法，因为“根入口”和“局部子树”是两种不同维度的查询。 +这是很多商业引擎场景树都会采用的结构，因为“对象所有权表”和“层级入口列表”是两个不同维度的数据。 -## 当前 active 状态有两层，但还没有完全打通 +## 当前 active 状态有三层语义 -理解这块很重要： +理解这点很重要： -- `SceneManager::GetActiveScene()` 是“哪一个场景被管理器认为是当前活动场景”。 -- `Scene::IsActive()` 是 `Scene` 自己保存的一个布尔标志。 -- `GameObject::IsActiveInHierarchy()` 才是对象更新真正参与的门槛。 +- `SceneManager::GetActiveScene()` 更接近“当前被管理器选中的场景” +- `Scene::IsActive()` 是场景自己的一个布尔状态位 +- `GameObject::IsActiveInHierarchy()` 才是对象更新真正参与的门槛 -在当前实现里，这三者并没有完全联动： +在当前实现里，它们没有完全联动： -- `Scene::SetActive(false)` 不会阻止 `Scene::Update()`。 -- `SceneManager::SetActiveScene()` 也不会自动改 `Scene::IsActive()`。 +- `Scene::SetActive(false)` 不会阻止 `Scene::Update()` +- `SceneManager::SetActiveScene()` 也不会自动同步 `Scene::IsActive()` -这意味着现在更稳妥的理解方式是： +所以更稳妥的理解方式是： -- `SceneManager` 的 active scene 更接近“当前选中的场景引用”。 -- `Scene::m_active` 更接近“一个可保存的场景状态位”。 +- `SceneManager` 的 active scene 偏向管理器层选择 +- `Scene::m_active` 偏向一个可保存状态位 +- 运行时真正的对象是否活跃，还是看对象自己的层级有效激活态 -## 序列化为什么用自定义文本格式 +## 创建路径和加载路径为什么要分开 -当前 `Scene::SerializeToString()` 没有走 JSON，而是用了非常直接的文本块格式。这样做的现实好处是： +### 创建路径 -- 实现简单。 -- 组件可以继续用自己的 `Serialize(std::ostream&)` 输出。 -- 调试时直接打开文本就能看见对象、父子关系和组件条目。 +`Scene::CreateGameObject()` 当前会： -但代价也很明确： +- 创建对象 +- 注册到场景和全局 registry +- 接入根列表或父对象 +- 立即调用 `Awake()` +- 触发对象创建事件 -- 格式是引擎私有的，没有版本协商。 -- 解析鲁棒性有限。 -- 组件恢复依赖 `ComponentFactoryRegistry`，组件名或注册表变化都会影响加载结果。 +### 反序列化路径 -当前这份文本格式已经覆盖 `GameObject` 的 `tag` / `layer` 字段；场景 round-trip 会把它们和层级、Transform、普通组件一起恢复。 +`Scene::DeserializeFromString()` 当前会： + +- 先清空旧场景容器 +- 再按文本内容两阶段重建对象、组件和父子关系 +- 重新注册到场景和全局 registry + +但它不会： + +- 经过 `CreateGameObject()` +- 触发对象创建事件 +- 自动补发 `Awake()` / `Start()` + +这不是遗漏文档，而是当前实现的真实边界。它意味着“新建对象”和“从存档恢复对象”在初始化链上并不完全对称。 + +## 为什么序列化使用自定义文本格式 + +当前 `Scene::SerializeToString()` 没有走 JSON，而是使用引擎自己的文本块格式。这样做的现实收益是： + +- 实现直接 +- 调试友好 +- 组件仍然可以复用各自的 `Serialize(std::ostream&)` +- 打开文件就能看见对象树、父子关系、tag/layer 与组件条目 + +代价也很明确： + +- 这是引擎私有格式，不是通用交换协议 +- 当前没有显式 schema version +- 组件恢复依赖 `ComponentFactoryRegistry` +- 坏数据的异常恢复能力有限 + +## 当前场景文本里到底会保存什么 + +场景文本当前已经覆盖： + +- 场景名 +- 场景 active 位 +- 对象 `id` / `uuid` +- `name` +- `tag` +- `active` +- `layer` +- `parent` +- `transform` +- 普通组件类型与 payload + +这意味着当前 round-trip 不只是“把树结构存下来”，而是会把对象分类元数据和普通组件数据一起恢复回来。 + +## Tag 查询为什么现在已经是真实查询 + +旧文档最容易误导人的一点就是这里。 + +当前 `Scene::FindGameObjectWithTag()` 已经不再比较对象名字，而是： + +- 从根对象开始 +- 对每个对象调用 `CompareTag(tag)` +- 按深度优先顺序返回第一个匹配项 + +同时，场景保存和加载也会保留 `tag` / `layer`，所以这套对象元数据已经是场景系统的真实组成部分。 + +但仍要注意：它现在还是轻量实现，不是完整 TagManager： + +- 没有项目级 tag 定义表 +- 没有查询索引 +- 仍然是线性扫描 + +## 为什么脚本改 tag / layer 后场景查询会立刻变 + +当前 Mono 运行时把以下接口直接桥接到同一份 native `GameObject` 字段： + +- `GameObject.tag` +- `GameObject.layer` +- `Component.tag` +- `Component.layer` +- `CompareTag()` + +所以： + +- 脚本看到的不是副本 +- 脚本写回后，原生对象会立刻更新 +- 场景级 `FindGameObjectWithTag()` 会立即观察到新值 + +这是一种很典型的商业引擎托管桥接设计：脚本 API 不维护一份平行数据，而是直接操作原生运行时对象。 ## 当前最需要小心的几个事实 -- 场景析构不会自动为所有对象走显式销毁流程，所以不要把 `~Scene()` 当成完整生命周期清理器。 -- `FindGameObjectWithTag()` 当前已经是按真实 tag 做深度优先查询，但它仍是线性扫描，不是带索引的完整 tag 系统。 -- `LoadSceneAsync()` 现在不是异步，更多只是一个名字上预留好的 API。 -- `LoadScene()` 后的管理器 key 来自文件名，而不是场景内部保存的 `scene=` 名称。 +- 场景析构不会自动重放完整销毁流程，所以不要把 `~Scene()` 当成完整清理器。 +- `FindGameObjectWithTag()` 现在是真实 tag 查询，但仍是线性扫描。 +- `Scene::m_active` 当前不会阻止 `Scene::Update()`。 +- 从文本反序列化恢复后，不会自动补发 `Awake()` / `Start()`。 +- `Save()` / `Load()` 的错误处理目前比较轻，不提供事务式恢复。 ## 实际使用建议 如果你现在基于这套系统开发，比较稳妥的做法通常是： -- 需要 `OnDestroy` 或场景事件时，显式调用对象销毁入口，不要只依赖场景析构。 -- 需要稳定查场景时，优先用 `CreateScene()` 的名称或加载文件的文件名 stem，不要假设一定等于场景内部名字。 -- 不要把 `LoadSceneAsync()` 当成真正的后台加载接口。 -- 可以把 `FindGameObjectWithTag()` 当成真实 tag 查询，但不要把它当成带项目配置和索引优化的完整 TagManager。 +- 运行时对象创建优先用 `CreateGameObject()`，不要手工拼接半初始化对象。 +- 需要完整保存和恢复时，用 `SerializeToString()` / `DeserializeFromString()`，不要把单对象序列化当场景格式。 +- 需要生命周期完整对称时，明确区分“新建对象”与“从存档恢复对象”两条流程。 +- 可以放心把 `FindGameObjectWithTag()` 当作真实 tag 查询，但不要把它想象成带项目配置和索引优化的完整 TagManager。 ## 相关 API diff --git a/docs/api/_guides/Scripting/Project-Script-Assembly-And-Field-Sync.md b/docs/api/_guides/Scripting/Project-Script-Assembly-And-Field-Sync.md index c3ef16b7..ac79428a 100644 --- a/docs/api/_guides/Scripting/Project-Script-Assembly-And-Field-Sync.md +++ b/docs/api/_guides/Scripting/Project-Script-Assembly-And-Field-Sync.md @@ -2,122 +2,158 @@ ## 这份指南解决什么问题 -脚本模块这轮更新之后，已经不只是“Mono 能不能跑起来”的问题，还包括两条更具体的链路： +脚本模块现在关心的不只是“Mono 能不能跑起来”，还包括两条更具体的链路： -1. `project/Assets/**/*.cs` 怎么进入当前运行时能发现的 `GameScripts.dll` -2. 字段默认值、场景存储覆盖值、活体托管值到底是怎么互相覆盖和同步的 +1. `project/Assets/**/*.cs` 是怎么进入当前运行时可发现的 `GameScripts.dll` +2. 字段默认值、场景存储覆盖值和运行时托管值是怎么通过同一份程序集事实串起来的 这份指南就是把这两条链路放在一起说明。 +## 为什么商业引擎通常先看程序集而不是直接扫源文件 + +从工程设计上说，先编译、再发现类和字段，有几个非常实际的好处： + +- Inspector 列表和运行时真正能实例化出来的类，来自同一份事实来源 +- 字段元数据和字段默认值直接来自编译产物，不需要再维护第二套源代码分析器 +- 测试可以直接验证“项目脚本是否真的可用”，而不只是验证目录结构 + +当前 XCEngine 也是这一路线：`project/Assets/**/*.cs` 必须先进入 `GameScripts.dll`，后续 [MonoScriptRuntime](../../XCEngine/Scripting/Mono/MonoScriptRuntime/MonoScriptRuntime.md) 才能把它们变成脚本类描述、字段元数据和真实实例。 + ## 项目脚本程序集是怎么生成的 -`managed/CMakeLists.txt` 当前会构建两组托管输出： +`managed/CMakeLists.txt` 当前会生成两类托管输出： -- 通用脚本核心程序集：`XCEngine.ScriptCore.dll` -- 游戏脚本程序集：`GameScripts.dll` +- `XCEngine.ScriptCore.dll` +- `GameScripts.dll` -同时它还会扫描 `project/Assets/**/*.cs`，并把这些项目资产脚本编译到： +同时它还会把项目里的 `project/Assets/**/*.cs` 编译进： - `project/Library/ScriptAssemblies/XCEngine.ScriptCore.dll` - `project/Library/ScriptAssemblies/GameScripts.dll` - `project/Library/ScriptAssemblies/mscorlib.dll` -如果项目目录下暂时没有任何 `.cs` 文件，CMake 会生成一个占位源文件，保证 `GameScripts.dll` 仍然存在。 +因此“项目脚本能否被运行时发现”的关键，不是文件名像不像脚本，而是它有没有成功进入 `GameScripts.dll`。 -## 运行时如何接入这份项目程序集 +## 运行时如何接入这份程序集 -`MonoScriptRuntime::Settings` 可以只指定： +`MonoScriptRuntime::Settings` 当前既可以显式指定： + +- `coreAssemblyPath` +- `appAssemblyPath` + +也可以只指定： - `assemblyDirectory` -- `corlibDirectory` -- 或更显式的 `coreAssemblyPath` / `appAssemblyPath` -`ResolveSettings()` 会根据这些字段补全剩余路径。当前 `tests/scripting/test_project_script_assembly.cpp` 的做法就是把 `assemblyDirectory` 指到 `project/Library/ScriptAssemblies`，再验证运行时能发现项目资产脚本。 +然后由 `ResolveSettings()` 补全路径。 -已验证的真实行为包括： +实际 editor/runtime 项目产物仍会落到 `project/Library/ScriptAssemblies`。 +但 `tests/Scripting/test_project_script_assembly.cpp` 当前并不是直接复用这个工作树目录；它会优先读取 `XCENGINE_TEST_PROJECT_MANAGED_OUTPUT_DIR`，由 `xcengine_test_project_managed_assemblies` target 提供测试专用输出目录，未配置时才 fallback 到 `build/managed/ProjectScriptAssemblies`。 +这条测试验证的是“项目 `Assets/**/*.cs` 被编译成可发现的 `GameScripts.dll`”这条链路，而不是工作树里现成的 `Library/ScriptAssemblies` 快照。 + +## 进入 `GameScripts.dll` 之后，哪些类才会真的被发现 + +编译进程序集只是第一步。当前 Mono 运行时还会继续筛掉： + +- 抽象类 +- 非 `MonoBehaviour` 子类 +- 不在应用程序集这一侧的类型 + +因此当前真正能进入脚本类列表的，是“应用程序集里的非抽象 `MonoBehaviour` 子类”。 + +`ProjectScriptProbe.cs` 当前就是这条链路的最小样例： - 运行时能发现 `ProjectScripts.ProjectScriptProbe` - 能返回它的字段元数据 -- 能返回它的默认字段值： +- 能返回它的真实默认值： - `EnabledOnBoot = true` - `Label = "ProjectScriptProbe"` - `Speed = 2.5f` -项目样例脚本当前位于 [ProjectScriptProbe.cs](../../../../project/Assets/Scripts/ProjectScriptProbe.cs)。 +## 字段默认值和字段同步为什么都依赖同一份程序集事实 -## 字段值的三层来源 +这是当前设计里非常重要的一点。 -当前脚本字段至少可能来自三层： +如果类发现基于“源文件扫描”，但默认值读取和实例化基于“运行时程序集”，就会出现两套事实来源： -1. 类默认值 - 来自 `MonoScriptRuntime::TryGetClassFieldDefaultValues()`，反映 C# 初始化后的真实默认状态。 -2. 存储覆盖值 - 来自 `ScriptComponent::GetFieldStorage()`，会进入场景序列化。 -3. 活体托管值 - 来自当前运行中的托管实例。 +- Inspector 以为这个类和字段存在 +- 运行时却可能根本实例化不出来，或者默认值并不一致 -`ScriptEngine::TryGetScriptFieldModel()` 会把这三层合并成 `ScriptFieldModel`： +当前设计避免了这个问题： -- `defaultValue` 表示类默认值 -- `storedValue` 表示场景/本地缓存中的覆盖值 -- `value` + `valueSource` 表示当前真正应该展示给 UI 的值 +- 类发现来自编译后的程序集 +- 字段元数据来自编译后的程序集 +- 字段默认值来自编译后的程序集 +- 真正实例化也来自同一份程序集 -## 创建实例时字段怎么进入托管世界 +这是商业引擎文档里常见的“单一事实来源”原则。 -`MonoScriptRuntime::CreateScriptInstance()` 当前会按这条顺序工作： +## `[SerializeField] private` 在这条链路里意味着什么 -1. 查类元数据 -2. 创建托管对象 -3. 注入 `gameObjectUUID` 和 `scriptComponentUUID` -4. 遍历 `ScriptFieldStorage` -5. 只把“字段名存在且类型匹配”的覆盖值写进托管实例 +当前字段发现规则已经支持： -这意味着： +- `public` 实例字段 +- `[SerializeField] private` 字段 -- 场景里保存的覆盖值可以覆盖类默认值 -- 存储里已经遗留、但脚本类里不存在的字段，不会被写入托管实例 -- 类型不匹配的字段也不会被偷偷应用 +这条规则对“项目脚本”和“内置测试脚本”是一致的，因为它们最终都走同一份 `MonoScriptRuntime` 字段发现逻辑。 -## 生命周期后为什么还要回写 +这样设计的原因很明确： -`ScriptEngine` 每次调用生命周期方法后，都会紧接着调用运行时的 `SyncManagedFieldsToStorage()`。 +- 你可以把想持久化/想进 Inspector 的字段保留成 private +- 同时又不需要为了序列化而扩大脚本对外 API 面 -Mono 当前只会回写： +这和 Unity 的设计理念一致，但这里更要强调它背后的工程价值： -- 本地已经存在于 `ScriptFieldStorage` 的字段 -- 且字段在类元数据里仍然存在 -- 且存储类型与类声明类型匹配 +- 封装更稳 +- 重构更安全 +- 序列化范围更可控 -这样设计的好处是： +## 哪些 private 字段仍然不会同步 -- 不会把运行时临时字段自动污染到场景数据 -- 类型漂移会显式表现成 `TypeMismatch` -- 存储层和托管层的职责边界更清楚 +当前不会进入字段模型、也不会参与默认值和存储同步的，至少包括： -## 批量编辑和清除覆盖怎么工作 +- 未标注 `[SerializeField]` 的 `private` +- `readonly / init-only` +- `static` +- `const / literal` +- 当前不支持的字段类型 -当前推荐给编辑器用的不是直接操作 `ScriptFieldStorage`，而是： +这不是遗漏，而是当前字段模型的明确边界。 -- [ScriptEngine::ApplyScriptFieldWrites](../../XCEngine/Scripting/ScriptEngine/ApplyScriptFieldWrites.md) -- [ScriptEngine::ClearScriptFieldOverrides](../../XCEngine/Scripting/ScriptEngine/ClearScriptFieldOverrides.md) +## 场景存储、默认值和运行时值如何叠加 -原因很直接： +当前完整链路可以概括为： -- 批量写会同时校验类元数据、活体实例和本地存储 -- 清除覆盖会把活体托管字段恢复到类默认值，而不是只删一份本地缓存 +1. `TryGetClassFieldDefaultValues()` + - 给出类默认值 +2. `ScriptFieldStorage` + - 提供场景/本地覆盖值 +3. `CreateScriptInstance()` + - 把覆盖值写回托管实例 +4. 生命周期运行 + - 托管字段在脚本里继续变化 +5. `SyncManagedFieldsToStorage()` + - 把字段模型内的值同步回存储 -如果脚本类已经丢失，系统仍允许对现有存储字段做有限编辑或删除，但会用 `StoredOnly` / `Missing` 这类状态明确告诉你当前已经脱离类声明。 +对于 `[SerializeField] private` 字段，这条链路同样成立。 + +`SerializeFieldProbe` 的 round-trip 测试已经证明： + +- private 字段可以先吃到场景覆盖值 +- 运行后修改过的值会被回写 +- 场景序列化和重新加载后仍能保持 +- 未标注 private 字段不会被偷偷带进存储 ## 当前限制 -- 只支持受支持类型的 `public` 非 `static` 实例字段 -- 只发现应用程序集里的非抽象 `MonoBehaviour` 子类 -- 没有热重载或程序集增量刷新 -- 不会自动把“运行时新增但本地不存在”的字段持久化 +- 项目脚本是否可被发现，依赖的是已编译出的 `GameScripts.dll`。 +- 当前没有程序集热重载或增量刷新。 +- 字段模型只覆盖当前支持的字段类型和显式允许进入的字段访问级别。 +- 未进入字段模型的字段，不会出现在默认值查询、字段编辑 UI 或场景持久化链里。 ## 推荐阅读 -1. [Scripting](../../XCEngine/Scripting/Scripting.md) -2. [MonoScriptRuntime](../../XCEngine/Scripting/Mono/MonoScriptRuntime/MonoScriptRuntime.md) +1. [MonoScriptRuntime](../../XCEngine/Scripting/Mono/MonoScriptRuntime/MonoScriptRuntime.md) +2. [Scripting Runtime And Field Model](Scripting-Runtime-And-Field-Model.md) 3. [ScriptEngine](../../XCEngine/Scripting/ScriptEngine/ScriptEngine.md) 4. [ScriptField](../../XCEngine/Scripting/ScriptField/ScriptField.md) diff --git a/docs/api/_guides/Scripting/Scripting-Runtime-And-Field-Model.md b/docs/api/_guides/Scripting/Scripting-Runtime-And-Field-Model.md index bd5c93e3..611b8d5f 100644 --- a/docs/api/_guides/Scripting/Scripting-Runtime-And-Field-Model.md +++ b/docs/api/_guides/Scripting/Scripting-Runtime-And-Field-Model.md @@ -2,7 +2,7 @@ ## 这份指南解决什么问题 -只看单个 API 页，很难一下子理解当前脚本系统为什么同时存在： +单看 API 页，很难一下子理解当前脚本系统里为什么同时存在： - `ScriptComponent` - `ScriptFieldStorage` @@ -10,17 +10,17 @@ - `IScriptRuntime` - `MonoScriptRuntime` -这份指南的目标，是把它们放回同一条真实运行链路里解释清楚，并明确“类默认值、存储覆盖值、活体托管值”这三层数据是怎么叠加的。 +这份指南的目标，是把它们放回同一条真实运行链路里解释清楚，并重点说明“类默认值、场景存储覆盖值、活体托管值”这三层数据如何叠加。 ## 一句话理解当前架构 当前脚本系统采用的是“原生场景数据层 + 运行时调度层 + 可替换托管后端”三段式设计： -1. 场景和对象层只保存脚本绑定与字段缓存。 -2. `ScriptEngine` 负责生命周期和实例追踪。 -3. 具体脚本代码执行交给 `IScriptRuntime` 的实现，当前实现是 `MonoScriptRuntime`。 +1. 场景和对象层保存脚本绑定与字段存储。 +2. `ScriptEngine` 负责生命周期调度和实例跟踪。 +3. `IScriptRuntime` 的实现负责真正执行托管代码，当前实现是 [MonoScriptRuntime](../../XCEngine/Scripting/Mono/MonoScriptRuntime/MonoScriptRuntime.md)。 -这种分层和商业引擎里常见的脚本体系很接近。它的核心收益，不是“代码显得更抽象”，而是让三个原本会互相缠死的问题被拆开： +这种设计和商业引擎常见的脚本体系很接近。它的核心收益不是“更抽象”，而是把三个原本会互相缠绕的问题拆开： - 场景序列化 - 运行时生命周期 @@ -28,117 +28,153 @@ ## 为什么 `ScriptComponent` 不直接等于“脚本实例” -很多用户第一反应会是：既然组件名叫 `ScriptComponent`，为什么它不自己持有托管对象？ +`ScriptComponent` 更像“脚本绑定描述 + 字段持久化容器”，而不是托管对象本身。 -原因很现实： +这是因为： -- 场景在未运行时也需要保存脚本绑定信息。 -- 场景加载、复制、序列化、反序列化时，不应该强依赖 Mono 已经初始化。 -- 编辑器或工具链可能只想改字段，不想真正启动托管运行时。 +- 场景在未运行时也要保存脚本类绑定 +- Inspector 和序列化层在未启动 Mono 时也要工作 +- 运行时实例应当可以被创建、销毁和重建，而不污染场景层数据结构 -所以当前 `ScriptComponent` 更像“脚本实例描述与持久化容器”，而不是托管对象本身。真正的托管实例是在运行期由 `ScriptEngine + IScriptRuntime` 动态创建的。 +这和 Unity 的理念一致：序列化壳与运行时实例不是同一个对象。 -## 为什么还要有 `ScriptFieldStorage` - -`ScriptFieldStorage` 的存在，是为了让脚本字段有一个不依赖托管运行时的落点。它解决了三类问题： - -- 场景序列化时，字段值需要写进文本数据。 -- 运行前，用户仍然需要能编辑脚本字段默认值。 -- 运行中，托管对象的字段变化需要有机会回写到本地缓存。 - -这和 Unity Inspector 里的“脚本字段序列化层”在理念上很接近，但当前实现更轻量，也更直接。 - -## 运行时里字段值到底有几层 +## 字段到底有哪几层 当前字段值至少可能来自三层： 1. 类默认值 - 来自运行时 `TryGetClassFieldDefaultValues()`；Mono 实现会真实构造一个托管对象并读取字段初始化结果。 + - 来自 `MonoScriptRuntime::TryGetClassFieldDefaultValues()` + - 它反映的是 C# 初始化后的真实默认值 2. 存储覆盖值 - 来自 `ScriptFieldStorage`；它会在场景序列化、运行前编辑和生命周期回写之间持续存在。 + - 来自 `ScriptFieldStorage` + - 它是场景/本地持久化层 3. 活体托管值 - 来自当前运行中的托管实例；`ScriptEngine::TryGetScriptFieldModel()` 和 `TryGetScriptFieldValue()` 会优先读这一层。 + - 来自当前正在运行的托管实例 -`ScriptFieldSnapshot` 里的 `valueSource` 就是在说明当前展示值到底来自哪一层。 +这三层的意义不同： -## 当前生命周期是怎么串起来的 +- 类默认值回答“如果没有任何场景覆盖，这个字段原本该是什么” +- 存储覆盖值回答“场景目前记住了什么” +- 活体托管值回答“本次运行到现在，这个字段被脚本改成了什么” -真实顺序如下： +## 当前哪些字段会进入字段模型 -1. `SceneRuntime::Start()` 调用 `ScriptEngine::OnRuntimeStart(scene)`。 -2. `ScriptEngine` 收集场景里的 `ScriptComponent`，并订阅 `Scene::OnGameObjectCreated()`，保证运行中生成的新对象也会被继续追踪。 -3. 对满足运行条件的组件，调用运行时 `CreateScriptInstance()`。 -4. 然后按顺序补发 `Awake`、`OnEnable`。 -5. 第一次 `OnUpdate()` 前，会先补发一次 `Start`。 -6. 每个生命周期调用后，运行时会把托管字段同步回 `ScriptFieldStorage`。 -7. 停止运行时，按 `OnDisable -> OnDestroy -> DestroyScriptInstance` 回收。 +当前 Mono 后端的真实规则不是“所有字段都进来”，而是经过一层非常明确的筛选： -这里最关键的一点，是当前引擎把生命周期顺序集中收口在 `ScriptEngine`，而不是让 Mono 运行时自己决定。这样未来即便更换脚本后端，生命周期语义仍然可以保持一致。 +- 排除： + - `static` + - `const / literal` + - `readonly / init-only` +- 接受： + - `public` 实例字段 + - `[SerializeField] private` 字段 +- 最后还要满足当前支持的字段类型 -## `IScriptRuntime` 的真正意义 +这意味着： -`IScriptRuntime` 不是为了“为了抽象而抽象”。它解决的是一个很实际的问题： +- `public` 不是进入序列化/字段模型的唯一方式 +- `private` 也不是天然不行，关键在于它是否被显式声明为可序列化字段 -- 引擎主流程需要操心“什么时候创建实例、什么时候调用生命周期、字段怎么读写”。 -- 但它不应该知道 Mono API、GCHandle、程序集加载这些实现细节。 +## 为什么支持 `[SerializeField] private` -因此 `IScriptRuntime` 只暴露引擎真正关心的契约： +这是当前文档里必须讲清楚的一条设计原则。 -- 运行时启停 -- 类字段元数据查询 -- 托管字段读写 -- 实例创建/销毁 -- 生命周期方法调用 +如果只允许 `public` 字段进入字段模型，会有两个直接问题： -这样 `ScriptEngine` 才能成为“脚本系统总调度器”，而不是某个具体运行时的包装类。 +- 脚本作者为了让字段能进 Inspector / 场景存储，只能把本来应该私有的实现细节也暴露成公开 API +- 类的封装边界会被序列化需求反向破坏 -## 当前 Mono 方案做到了哪一步 +支持 `[SerializeField] private` 的好处是： -`MonoScriptRuntime` 当前已经具备以下实际能力： +- 你可以保留封装，把类对外 API 面控制住 +- 你仍然能让字段参与场景存储和 Inspector +- 字段重构时更安全，不会因为“想序列化”就把内部状态长期公开 -- 初始化 Mono 域并加载核心/游戏程序集。 -- 发现继承 `MonoBehaviour` 的非抽象脚本类。 -- 枚举支持类型的公共实例字段，并读取字段默认值。 -- 创建托管实例，并注入 `GameObject` / `ScriptComponent` 上下文。 -- 通过 internal call 桥接基础引擎 API。 -- 生命周期调用后把已存储字段同步回本地缓存。 +这正是 Unity 一类商业引擎长期采用这套规则的核心原因。 -但也要明确它还没有做到什么： +## 为什么未标注的 private 字段仍然要忽略 -- 没有热重载和程序集增量刷新。 -- 没有完整的脚本调试器集成。 -- 没有更细的域隔离和编辑器运行时分层。 -- `SyncManagedFieldsToStorage()` 当前只回写“本地已经存在的字段”，不会自动持久化运行时临时新增字段。 +因为不是所有 private 字段都应该持久化。 -## 为什么字段同步策略这么保守 +很多 private 字段只是： -当前字段同步只回写 `ScriptFieldStorage` 里已经存在且类型匹配的字段。这种设计看上去保守，但它有明确好处： +- 临时缓存 +- 运行时计数器 +- 中间态标记 +- 纯内部实现细节 -- 不会因为运行时临时字段把场景数据层污染得越来越不可控。 -- 可以保住“场景里声明了哪些持久化字段”这条边界。 -- 对编辑器和序列化格式更安全。 +如果把它们也自动纳入字段模型，会导致： -代价也很明显： +- 场景数据被临时状态污染 +- Inspector 暴露出不该改的内部细节 +- 运行时偶发状态被错误回写到持久化层 -- 运行中动态产生的临时计数器、缓存值，不会自动进场景。 -- 如果字段类型改了，系统会把它标成 mismatch，而不是偷偷帮你转换。 +因此当前策略很明确： -这是一种更偏工程安全的选择。 +- 想进入字段模型，就显式标 `[SerializeField]` +- 不标，就保持私有实现细节身份 -## 类切换为什么要走 `SetScriptClass()` +## 为什么 `readonly` 也被排除 -当前运行时重绑定逻辑并不是“任意改三个字符串都能触发”。 +当前字段同步模型要求： -- `ScriptComponent::SetScriptClass()` / `ClearScriptClass()` 会通知 `ScriptEngine`。 -- 运行时中的 `ScriptEngine::OnScriptComponentClassChanged()` 会停掉旧实例，再按新类重新创建和跟踪。 -- `SetAssemblyName()` / `SetNamespaceName()` / `SetClassName()` 只是原始字段 setter，不会触发这条流程。 +- 运行前把存储覆盖值写回托管实例 +- 运行后把托管值同步回 `ScriptFieldStorage` -也就是说，真正要做脚本类切换时，必须走显式重绑定 API。 +`readonly` 字段不适合承担这个双向同步职责，因此当前实现选择直接排除它。这是偏工程安全的取舍，不是功能缺失。 + +## 一个最直接的例子：`FieldMetadataProbe` + +`managed/GameScripts/FieldMetadataProbe.cs` 当前几乎就是规则样本： + +- `Health` / `Speed` / `Label` / `SpawnPoint` / `State` / `Target` + - 会进入字段元数据 +- `HiddenFlag` + - 因为是 `[SerializeField] private`，也会进入字段元数据 +- `IgnoredPrivateCounter` + - 因为是未标注的 private，不会进入 +- `SharedCounter` + - 因为是 `static`，不会进入 +- `UnsupportedRotation` + - 因为 `Quaternion` 当前不在支持类型里，不会进入 + +这条规则已经被 `ClassFieldMetadataListsSupportedPublicInstanceFields` 和相关默认值测试直接覆盖。 + +## 一个更完整的运行时例子：`SerializeFieldProbe` + +`managed/GameScripts/SerializeFieldProbe.cs` 展示了 `[SerializeField] private` 字段是如何真正走完整个同步链的。 + +当前测试场景做了这几步： + +1. 在 `ScriptFieldStorage` 里预先写入： + - `HiddenCounter = 42` + - `HiddenEnabled = false` +2. 启动运行时并创建托管实例 +3. `CreateScriptInstance()` 把这两个存储覆盖值写回 private 字段 +4. 脚本在 `Start()` 里读取并修改它们 +5. `SyncManagedFieldsToStorage()` 再把更新后的值同步回存储 +6. 场景序列化并重新加载后，值仍然能 round-trip 保持 + +同一测试还验证了一个边界： + +- `IgnoredPrivateCounter` 这种未标注 private 字段不会被写入 `ScriptFieldStorage` + +这正是当前字段模型“支持 `[SerializeField] private`，但保持内部状态边界”的关键体现。 + +## 为什么这种同步策略是保守但合理的 + +当前实现并不是“看到托管字段就自动持久化”，而是更保守地只同步已经进入字段模型的字段。 + +它的好处很现实： + +- 不会把运行时临时字段偷偷带进场景数据 +- 不会因为类里多了一个内部变量，就让序列化格式悄悄膨胀 +- 字段迁移或类型变化时，边界更可控 + +这是更偏商业引擎工程安全的取舍。 ## 推荐阅读顺序 -如果你第一次接触这个模块，建议按下面顺序看： - 1. [Scripting](../../XCEngine/Scripting/Scripting.md) 2. [ScriptComponent](../../XCEngine/Scripting/ScriptComponent/ScriptComponent.md) 3. [ScriptField](../../XCEngine/Scripting/ScriptField/ScriptField.md) diff --git a/docs/api/_meta/_scratch_audit_asset_material_batch4.md b/docs/api/_meta/_scratch_audit_asset_material_batch4.md new file mode 100644 index 00000000..78e05c3b --- /dev/null +++ b/docs/api/_meta/_scratch_audit_asset_material_batch4.md @@ -0,0 +1,147 @@ +# API 文档重构状态 + +**生成时间**: `2026-04-04 00:13:21` + +**来源**: `docs/api/_tools/audit_api_docs.py` + +## 摘要 + +- Markdown 页面数（全部）: `3362` +- Markdown 页面数（canonical）: `3337` +- Public headers 数: `244` +- Editor source headers 数: `127` +- 有效头文件引用数（全部）: `244` +- 有效头文件引用数（canonical）: `244` +- 无效头文件引用数: `0` +- 有效源文件引用数（全部）: `125` +- 有效源文件引用数（Editor canonical）: `125` +- 无效源文件引用数: `1` +- 失效 `.md` 链接数: `70` +- 非 `.md` 相对链接数: `0` +- 旧模板页面数: `0` +- 扁平 header 页面数: `0` +- Canonical 显式过期符号残留数: `0` +- Editor 显式过期符号残留数: `0` +- Editor 残留 canonical 旧页面数: `0` +- Editor 高风险单页目录数: `0` + +## 平行目录 + +- Canonical 根目录: `XCEngine` +- 源码目录节点数: `30` +- 已生成目录总览页节点数: `30` +- 缺失目录总览页节点数: `0` +- 支撑目录: `_meta, _tools` + +## 模块覆盖 + +| 模块 | Public headers | 已覆盖 | 未覆盖 | +|------|----------------|--------|--------| +| `Audio` | `11` | `11` | `0` | +| `Components` | `10` | `10` | `0` | +| `Core` | `48` | `48` | `0` | +| `Debug` | `10` | `10` | `0` | +| `Input` | `5` | `5` | `0` | +| `Memory` | `5` | `5` | `0` | +| `Platform` | `11` | `11` | `0` | +| `RHI` | `87` | `87` | `0` | +| `Rendering` | `22` | `22` | `0` | +| `Resources` | `14` | `14` | `0` | +| `Scene` | `4` | `4` | `0` | +| `Scripting` | `7` | `7` | `0` | +| `Threading` | `10` | `10` | `0` | + +## Editor 源文件页覆盖 + +| 模块 | Source headers | 已覆盖 | 未覆盖 | +|------|----------------|--------|--------| +| `(root)` | `3` | `3` | `0` | +| `Actions` | `9` | `9` | `0` | +| `Commands` | `4` | `4` | `0` | +| `ComponentEditors` | `10` | `10` | `0` | +| `Core` | `20` | `20` | `0` | +| `Layers` | `1` | `1` | `0` | +| `Layout` | `1` | `1` | `0` | +| `Managers` | `3` | `3` | `0` | +| `Platform` | `4` | `4` | `0` | +| `Scripting` | `3` | `3` | `0` | +| `UI` | `29` | `29` | `0` | +| `Utils` | `4` | `4` | `0` | +| `Viewport` | `26` | `24` | `2` | +| `panels` | `10` | `10` | `0` | + +## 元信息覆盖 + +| 字段 | 页面数 | +|------|--------| +| `命名空间` | `2137` | +| `类型` | `2137` | +| `描述` | `424` | +| `头文件` | `1738` | +| `源文件` | `358` | + +## 无效源文件引用 + +| 文档 | 源文件 | +|------|------| +| `XCEngine/Editor/Viewport/SceneViewportOverlayRenderer/SceneViewportOverlayRenderer.md` | `editor/src/Viewport/SceneViewportOverlayRenderer.h` | + +## 失效 Markdown 链接 + +| 文档 | 目标 | +|------|------| +| `XCEngine/Audio/WindowsAudioBackend/Constructor.md` | `WASAPIBackend.md` | +| `XCEngine/Audio/WindowsAudioBackend/Destructor.md` | `WASAPIBackend.md` | +| `XCEngine/Audio/WindowsAudioBackend/GetAvailableDevices.md` | `WASAPIBackend.md` | +| `XCEngine/Audio/WindowsAudioBackend/GetConfig.md` | `WASAPIBackend.md` | +| `XCEngine/Audio/WindowsAudioBackend/GetDeviceName.md` | `WASAPIBackend.md` | +| `XCEngine/Audio/WindowsAudioBackend/GetMasterVolume.md` | `WASAPIBackend.md` | +| `XCEngine/Audio/WindowsAudioBackend/Initialize.md` | `WASAPIBackend.md` | +| `XCEngine/Audio/WindowsAudioBackend/IsMuted.md` | `WASAPIBackend.md` | +| `XCEngine/Audio/WindowsAudioBackend/IsRunning.md` | `WASAPIBackend.md` | +| `XCEngine/Audio/WindowsAudioBackend/ProcessAudio.md` | `WASAPIBackend.md` | +| `XCEngine/Audio/WindowsAudioBackend/Resume.md` | `WASAPIBackend.md` | +| `XCEngine/Audio/WindowsAudioBackend/SetDevice.md` | `WASAPIBackend.md` | +| `XCEngine/Audio/WindowsAudioBackend/SetMasterVolume.md` | `WASAPIBackend.md` | +| `XCEngine/Audio/WindowsAudioBackend/SetMuted.md` | `WASAPIBackend.md` | +| `XCEngine/Audio/WindowsAudioBackend/Shutdown.md` | `WASAPIBackend.md` | +| `XCEngine/Audio/WindowsAudioBackend/Start.md` | `WASAPIBackend.md` | +| `XCEngine/Audio/WindowsAudioBackend/Stop.md` | `WASAPIBackend.md` | +| `XCEngine/Audio/WindowsAudioBackend/Suspend.md` | `WASAPIBackend.md` | +| `XCEngine/Core/Math/Matrix3/Constructor.md` | `Matrix3x3.md` | +| `XCEngine/Core/Math/Matrix3/Determinant.md` | `Matrix3x3.md` | +| `XCEngine/Core/Math/Matrix3/Identity.md` | `Matrix3x3.md` | +| `XCEngine/Core/Math/Matrix3/Inverse.md` | `Matrix3x3.md` | +| `XCEngine/Core/Math/Matrix3/OperatorMultiply.md` | `Matrix3x3.md` | +| `XCEngine/Core/Math/Matrix3/OperatorSubscript.md` | `Matrix3x3.md` | +| `XCEngine/Core/Math/Matrix3/RotationX.md` | `Matrix3x3.md` | +| `XCEngine/Core/Math/Matrix3/RotationY.md` | `Matrix3x3.md` | +| `XCEngine/Core/Math/Matrix3/RotationZ.md` | `Matrix3x3.md` | +| `XCEngine/Core/Math/Matrix3/Scale.md` | `Matrix3x3.md` | +| `XCEngine/Core/Math/Matrix3/Transpose.md` | `Matrix3x3.md` | +| `XCEngine/Core/Math/Matrix3/Zero.md` | `Matrix3x3.md` | +| `XCEngine/Core/Math/Matrix4/Constructor.md` | `Matrix4x4.md` | +| `XCEngine/Core/Math/Matrix4/Decompose.md` | `Matrix4x4.md` | +| `XCEngine/Core/Math/Matrix4/Determinant.md` | `Matrix4x4.md` | +| `XCEngine/Core/Math/Matrix4/GetRotation.md` | `Matrix4x4.md` | +| `XCEngine/Core/Math/Matrix4/GetScale.md` | `Matrix4x4.md` | +| `XCEngine/Core/Math/Matrix4/GetTranslation.md` | `Matrix4x4.md` | +| `XCEngine/Core/Math/Matrix4/Identity.md` | `Matrix4x4.md` | +| `XCEngine/Core/Math/Matrix4/Inverse.md` | `Matrix4x4.md` | +| `XCEngine/Core/Math/Matrix4/LookAt.md` | `Matrix4x4.md` | +| `XCEngine/Core/Math/Matrix4/MultiplyPoint.md` | `Matrix4x4.md` | +| `XCEngine/Core/Math/Matrix4/MultiplyVector.md` | `Matrix4x4.md` | +| `XCEngine/Core/Math/Matrix4/OperatorMultiply.md` | `Matrix4x4.md` | +| `XCEngine/Core/Math/Matrix4/OperatorSubscript.md` | `Matrix4x4.md` | +| `XCEngine/Core/Math/Matrix4/Orthographic.md` | `Matrix4x4.md` | +| `XCEngine/Core/Math/Matrix4/Perspective.md` | `Matrix4x4.md` | +| `XCEngine/Core/Math/Matrix4/Rotation.md` | `Matrix4x4.md` | +| `XCEngine/Core/Math/Matrix4/RotationX.md` | `Matrix4x4.md` | +| `XCEngine/Core/Math/Matrix4/RotationY.md` | `Matrix4x4.md` | +| `XCEngine/Core/Math/Matrix4/RotationZ.md` | `Matrix4x4.md` | +| `XCEngine/Core/Math/Matrix4/Scale.md` | `Matrix4x4.md` | + +## 未覆盖的 Editor 源文件页 + +- `editor/src/Viewport/SceneViewportHudOverlay.h` +- `editor/src/Viewport/SceneViewportInteractionResolver.h` diff --git a/docs/api/_meta/rebuild-status.md b/docs/api/_meta/rebuild-status.md index cbaf81ba..e8e6cd6d 100644 --- a/docs/api/_meta/rebuild-status.md +++ b/docs/api/_meta/rebuild-status.md @@ -1,20 +1,20 @@ # API 文档重构状态 -**生成时间**: `2026-04-03 15:30:08` +**生成时间**: `2026-04-07 01:26:32` **来源**: `docs/api/_tools/audit_api_docs.py` ## 摘要 -- Markdown 页面数（全部）: `3324` -- Markdown 页面数（canonical）: `3298` -- Public headers 数: `244` -- Editor source headers 数: `124` -- 有效头文件引用数（全部）: `244` -- 有效头文件引用数（canonical）: `244` +- Markdown 页面数（全部）: `3753` +- Markdown 页面数（canonical）: `3725` +- Public headers 数: `304` +- Editor source headers 数: `142` +- 有效头文件引用数（全部）: `304` +- 有效头文件引用数（canonical）: `304` - 无效头文件引用数: `0` -- 有效源文件引用数（全部）: `124` -- 有效源文件引用数（Editor canonical）: `124` +- 有效源文件引用数（全部）: `142` +- 有效源文件引用数（Editor canonical）: `142` - 无效源文件引用数: `0` - 失效 `.md` 链接数: `0` - 非 `.md` 相对链接数: `0` @@ -28,8 +28,8 @@ ## 平行目录 - Canonical 根目录: `XCEngine` -- 源码目录节点数: `30` -- 已生成目录总览页节点数: `30` +- 源码目录节点数: `48` +- 已生成目录总览页节点数: `48` - 缺失目录总览页节点数: `0` - 支撑目录: `_meta, _tools` @@ -44,12 +44,13 @@ | `Input` | `5` | `5` | `0` | | `Memory` | `5` | `5` | `0` | | `Platform` | `11` | `11` | `0` | -| `RHI` | `87` | `87` | `0` | -| `Rendering` | `22` | `22` | `0` | -| `Resources` | `14` | `14` | `0` | +| `RHI` | `88` | `88` | `0` | +| `Rendering` | `38` | `38` | `0` | +| `Resources` | `20` | `20` | `0` | | `Scene` | `4` | `4` | `0` | | `Scripting` | `7` | `7` | `0` | | `Threading` | `10` | `10` | `0` | +| `UI` | `37` | `37` | `0` | ## Editor 源文件页覆盖 @@ -63,19 +64,20 @@ | `Layers` | `1` | `1` | `0` | | `Layout` | `1` | `1` | `0` | | `Managers` | `3` | `3` | `0` | -| `Platform` | `4` | `4` | `0` | +| `Platform` | `5` | `5` | `0` | | `Scripting` | `3` | `3` | `0` | | `UI` | `29` | `29` | `0` | | `Utils` | `4` | `4` | `0` | -| `Viewport` | `23` | `23` | `0` | -| `panels` | `10` | `10` | `0` | +| `Viewport` | `37` | `37` | `0` | +| `XCUIBackend` | `2` | `2` | `0` | +| `panels` | `11` | `11` | `0` | ## 元信息覆盖 | 字段 | 页面数 | |------|--------| -| `命名空间` | `941` | -| `类型` | `941` | -| `描述` | `417` | -| `头文件` | `552` | -| `源文件` | `348` | +| `命名空间` | `2471` | +| `类型` | `2471` | +| `描述` | `530` | +| `头文件` | `1892` | +| `源文件` | `512` | diff --git a/docs/api/_tools/__pycache__/audit_api_docs.cpython-313.pyc b/docs/api/_tools/__pycache__/audit_api_docs.cpython-313.pyc deleted file mode 100644 index 8869b67d..00000000 Binary files a/docs/api/_tools/__pycache__/audit_api_docs.cpython-313.pyc and /dev/null differ diff --git a/docs/api/_tools/__pycache__/fix_links.cpython-313.pyc b/docs/api/_tools/__pycache__/fix_links.cpython-313.pyc deleted file mode 100644 index 4d58e68c..00000000 Binary files a/docs/api/_tools/__pycache__/fix_links.cpython-313.pyc and /dev/null differ diff --git a/docs/api/_tools/__pycache__/generate_core_resources_canonical_pages.cpython-313.pyc b/docs/api/_tools/__pycache__/generate_core_resources_canonical_pages.cpython-313.pyc deleted file mode 100644 index 32dbe1a8..00000000 Binary files a/docs/api/_tools/__pycache__/generate_core_resources_canonical_pages.cpython-313.pyc and /dev/null differ diff --git a/docs/api/_tools/__pycache__/generate_rhi_canonical_pages.cpython-313.pyc b/docs/api/_tools/__pycache__/generate_rhi_canonical_pages.cpython-313.pyc deleted file mode 100644 index 797dddda..00000000 Binary files a/docs/api/_tools/__pycache__/generate_rhi_canonical_pages.cpython-313.pyc and /dev/null differ diff --git a/docs/api/_tools/__pycache__/migrate_legacy_method_pages.cpython-313.pyc b/docs/api/_tools/__pycache__/migrate_legacy_method_pages.cpython-313.pyc deleted file mode 100644 index 738dc635..00000000 Binary files a/docs/api/_tools/__pycache__/migrate_legacy_method_pages.cpython-313.pyc and /dev/null differ diff --git a/docs/api/_tools/__pycache__/scaffold_parallel_layout.cpython-313.pyc b/docs/api/_tools/__pycache__/scaffold_parallel_layout.cpython-313.pyc deleted file mode 100644 index b7c7dee5..00000000 Binary files a/docs/api/_tools/__pycache__/scaffold_parallel_layout.cpython-313.pyc and /dev/null differ diff --git a/docs/api/_tools/audit_api_docs.py b/docs/api/_tools/audit_api_docs.py index e83fac52..a99bccec 100644 --- a/docs/api/_tools/audit_api_docs.py +++ b/docs/api/_tools/audit_api_docs.py @@ -13,17 +13,112 @@ DOC_ROOT = SCRIPT_DIR.parent if SCRIPT_DIR.name == "_tools" else SCRIPT_DIR REPO_ROOT = DOC_ROOT.parents[1] INCLUDE_ROOT = REPO_ROOT / "engine" / "include" PUBLIC_INCLUDE_ROOT = INCLUDE_ROOT / "XCEngine" +EDITOR_SOURCE_ROOT = REPO_ROOT / "editor" / "src" PARALLEL_ROOT = DOC_ROOT / "XCEngine" META_ROOT = DOC_ROOT / "_meta" DEFAULT_REPORT = META_ROOT / "rebuild-status.md" HEADER_RE = re.compile(r"^\*\*头文件\*\*:\s*`([^`]+\.h)`", re.MULTILINE) +SOURCE_FILE_RE = re.compile(r"^\*\*源文件\*\*:\s*`([^`]+\.(?:h|hpp))`", re.MULTILINE) NAMESPACE_RE = re.compile(r"^\*\*命名空间\*\*:\s*`[^`]+`", re.MULTILINE) TYPE_RE = re.compile(r"^\*\*类型\*\*:\s*`[^`]+`", re.MULTILINE) DESCRIPTION_RE = re.compile(r"^\*\*描述\*\*:\s*.+$", re.MULTILINE) MD_LINK_RE = re.compile(r"\[([^\]]+)\]\(([^)]+)\)") LEGACY_SECTION_RE = re.compile(r"^## (Syntax|Remarks|See Also|Examples)$", re.MULTILINE) FENCED_CODE_BLOCK_RE = re.compile(r"```.*?```", re.DOTALL) +ACCESS_SPECIFIER_RE = re.compile(r"^(public|private|protected)\s*:\s*$") +IMPORTER_VERSION_RE = re.compile(r"kCurrentImporterVersion\s*=\s*(\d+)") +STALE_EDITOR_DOC_TOKENS: tuple[tuple[str, str], ...] = ( + ("MakeMigrateSceneAssetReferencesAction", "已删除的 Editor action helper"), + ("ExecuteMigrateSceneAssetReferences", "已删除的主菜单动作"), + ("CanMigrateSceneAssetReferences", "已删除的 ProjectCommands guard"), + ("MigrateSceneAssetReferences", "已删除的迁移 API"), + ("SceneAssetReferenceMigrationReport", "已删除的迁移报告类型"), + ("Migrate Scene AssetRefs", "已删除的主菜单项文案"), + ( + "ProjectCommandsMigrateSceneAssetReferencesRewritesLegacyScenePayloads", + "已删除的相关测试锚点", + ), +) +STALE_EDITOR_PAGE_TOKENS: tuple[tuple[str, str, str], ...] = ( + ( + "XCEngine/Editor/Core/EditorConsoleSink/", + "fallback 实例", + "与当前 EditorConsoleSink::GetInstance 生命周期不符的旧描述", + ), + ( + "XCEngine/Editor/Core/EditorConsoleSink/", + "不会返回空指针", + "与当前 EditorConsoleSink::GetInstance 可返回 nullptr 的实现不符", + ), + ( + "XCEngine/Editor/Core/EditorConsoleSink/", + "不会返回 `nullptr`", + "与当前 EditorConsoleSink::GetInstance 可返回 nullptr 的实现不符", + ), + ( + "XCEngine/Editor/Viewport/SceneViewportOverlayBuilder/", + "static SceneViewportOverlayFrameData Build(", + "SceneViewportOverlayBuilder 已改为实例方法 Build(...) + provider registry 驱动，不应再写成 static Build。", + ), + ( + "XCEngine/Editor/Viewport/SceneViewportOverlayBuilder/", + "无状态构建器", + "SceneViewportOverlayBuilder 当前持有 provider registry，不再是无状态 helper。", + ), +) +STALE_CANONICAL_PAGE_TOKENS: tuple[tuple[str, str, str], ...] = ( + ( + "XCEngine/Rendering/CameraRenderRequest/", + "builtinPostProcess", + "与当前 CameraRenderRequest 已删除该字段的实现不符", + ), + ( + "XCEngine/Rendering/CameraRenderRequest/", + "BuiltinPostProcessRequest", + "与当前 CameraRenderRequest 已删除该子请求对象的实现不符", + ), + ( + "XCEngine/Rendering/CameraRenderer/", + "m_builtinPostProcessBuilder", + "与当前 CameraRenderer 已删除该成员的实现不符", + ), + ( + "XCEngine/Core/Asset/ArtifactFormats/", + "kMaterialArtifactSchemaVersion = 1", + "与当前材质 artifact schema 已升级到 v2 的实现不符", + ), + ( + "XCEngine/Core/Asset/ArtifactFormats/", + "XCMAT01", + "与当前材质 artifact magic `XCMAT02` 的实现不符", + ), + ( + "XCEngine/Rendering/Pipelines/BuiltinForwardPipeline/", + "逐材质常量目前只写入 `baseColorFactor`", + "与当前 BuiltinForwardPipeline 优先消费 shader schema 常量 payload、仅在缺失时回退到 `baseColorFactor` 的实现不符", + ), + ( + "XCEngine/Rendering/RenderMaterialUtility/RenderMaterialUtility.md", + "BuildBuiltinForwardMaterialData() 当前只打包 `baseColorFactor`；贴图仍由调用方单独通过 [ResolveBuiltinBaseColorTexture](ResolveBuiltinBaseColorTexture.md) 解析。", + "与当前 BuiltinForwardPipeline 已优先通过 `ResolveSchemaMaterialConstantPayload()` 消费 schema-driven 材质常量 payload 的实现不符", + ), +) +STALE_EDITOR_CANONICAL_PAGES: tuple[tuple[str, str], ...] = ( + ( + "XCEngine/Editor/Managers/ProjectManager/MigrateSceneAssetReferences.md", + "已删除 API 的残留 canonical 页面", + ), +) + + +@dataclass +class EditorRiskEntry: + doc_page: str + source_file: str + direct_page_count: int + public_method_count: int + implementation_line_count: int @dataclass @@ -37,6 +132,21 @@ class ModuleCoverage: return self.public_headers - self.documented_headers +@dataclass +class StaleDocTokenMatch: + doc_page: str + token: str + reason: str + line_number: int + line_text: str + + +@dataclass +class StaleCanonicalPageMatch: + doc_page: str + reason: str + + def normalize_rel_path(path: str) -> str: return path.replace("\\", "/") @@ -63,6 +173,13 @@ def iter_public_headers() -> list[str]: ) +def iter_editor_source_headers() -> list[str]: + return sorted( + normalize_rel_path(path.relative_to(REPO_ROOT).as_posix()) + for path in EDITOR_SOURCE_ROOT.rglob("*.h") + ) + + def iter_public_include_dirs() -> list[str]: dirs = ["XCEngine"] dirs.extend( @@ -90,6 +207,60 @@ def strip_fenced_code_blocks(content: str) -> str: return FENCED_CODE_BLOCK_RE.sub("", content) +def count_non_empty_source_lines(path: Path) -> int: + if not path.exists(): + return 0 + + count = 0 + for line in path.read_text(encoding="utf-8", errors="ignore").splitlines(): + stripped = line.strip() + if not stripped or stripped.startswith("//"): + continue + count += 1 + return count + + +def count_public_method_like_declarations(path: Path) -> int: + if not path.exists(): + return 0 + + in_public_block = False + pending: list[str] = [] + count = 0 + + for raw_line in path.read_text(encoding="utf-8", errors="ignore").splitlines(): + line = raw_line.strip() + if not line or line.startswith("//"): + continue + + access_match = ACCESS_SPECIFIER_RE.match(line) + if access_match: + in_public_block = access_match.group(1) == "public" + pending.clear() + continue + + if not in_public_block: + continue + + pending.append(line) + if not any(token in line for token in (";", "{")): + continue + + declaration = " ".join(pending) + pending.clear() + + if "(" not in declaration or ")" not in declaration: + continue + if declaration.startswith(("using ", "friend ", "static_assert", "#")): + continue + if declaration.startswith(("return ", "if ", "for ", "while ", "switch ")): + continue + + count += 1 + + return count + + def is_dir_index_page(page: Path) -> bool: if not page.is_relative_to(PARALLEL_ROOT): return False @@ -109,29 +280,229 @@ def is_flat_header_page(page: Path, rel_page: str) -> bool: return (INCLUDE_ROOT / Path(rel_page).with_suffix(".h")).exists() +def build_editor_module_coverages( + editor_headers: list[str], + documented_sources: set[str], +) -> list[ModuleCoverage]: + source_by_module: dict[str, list[str]] = defaultdict(list) + documented_by_module: dict[str, set[str]] = defaultdict(set) + + for source in editor_headers: + relative = Path(source).relative_to("editor/src").as_posix() + module = relative.split("/", 1)[0] if "/" in relative else "(root)" + source_by_module[module].append(source) + + for source in documented_sources: + relative = Path(source).relative_to("editor/src").as_posix() + module = relative.split("/", 1)[0] if "/" in relative else "(root)" + documented_by_module[module].add(source) + + return [ + ModuleCoverage( + module=module, + public_headers=len(headers), + documented_headers=len(documented_by_module.get(module, set())), + ) + for module, headers in sorted(source_by_module.items()) + ] + + +def collect_editor_risk_entries( + source_pages: dict[str, list[str]], +) -> list[EditorRiskEntry]: + entries: list[EditorRiskEntry] = [] + + for source_file, doc_pages in sorted(source_pages.items()): + for rel_page in doc_pages: + page_path = DOC_ROOT / rel_page + direct_page_count = len(list(page_path.parent.glob("*.md"))) + header_path = REPO_ROOT / source_file + implementation_path = header_path.with_suffix(".cpp") + public_method_count = count_public_method_like_declarations(header_path) + implementation_line_count = count_non_empty_source_lines(implementation_path) + + if direct_page_count > 1: + continue + if implementation_line_count < 200 and not ( + implementation_line_count >= 50 and public_method_count >= 8 + ): + continue + + entries.append( + EditorRiskEntry( + doc_page=rel_page, + source_file=source_file, + direct_page_count=direct_page_count, + public_method_count=public_method_count, + implementation_line_count=implementation_line_count, + ) + ) + + entries.sort( + key=lambda entry: ( + entry.direct_page_count, + -entry.implementation_line_count, + -entry.public_method_count, + entry.doc_page, + ) + ) + return entries + + +def collect_stale_editor_doc_token_matches( + rel_page: str, + content: str, +) -> list[StaleDocTokenMatch]: + if not rel_page.startswith("XCEngine/Editor/"): + return [] + + matches: list[StaleDocTokenMatch] = [] + for line_number, raw_line in enumerate(content.splitlines(), start=1): + line = raw_line.strip() + if not line: + continue + + for token, reason in STALE_EDITOR_DOC_TOKENS: + if token not in raw_line: + continue + + matches.append( + StaleDocTokenMatch( + doc_page=rel_page, + token=token, + reason=reason, + line_number=line_number, + line_text=line, + ) + ) + + for page_prefix, token, reason in STALE_EDITOR_PAGE_TOKENS: + if not rel_page.startswith(page_prefix): + continue + if token not in raw_line: + continue + + matches.append( + StaleDocTokenMatch( + doc_page=rel_page, + token=token, + reason=reason, + line_number=line_number, + line_text=line, + ) + ) + + return matches + + +def collect_stale_canonical_doc_token_matches( + rel_page: str, + content: str, +) -> list[StaleDocTokenMatch]: + if not rel_page.startswith("XCEngine/"): + return [] + + matches: list[StaleDocTokenMatch] = [] + for line_number, raw_line in enumerate(content.splitlines(), start=1): + line = raw_line.strip() + if not line: + continue + + for page_prefix, token, reason in STALE_CANONICAL_PAGE_TOKENS: + if not rel_page.startswith(page_prefix): + continue + if token not in raw_line: + continue + + matches.append( + StaleDocTokenMatch( + doc_page=rel_page, + token=token, + reason=reason, + line_number=line_number, + line_text=line, + ) + ) + + return matches + + +def collect_dynamic_canonical_doc_token_matches( + rel_page: str, + content: str, +) -> list[StaleDocTokenMatch]: + if rel_page != "XCEngine/Core/Asset/AssetDatabase/AssetDatabase.md": + return [] + + header_path = INCLUDE_ROOT / "XCEngine/Core/Asset/AssetDatabase.h" + if not header_path.exists(): + return [] + + header_content = header_path.read_text(encoding="utf-8", errors="ignore") + header_match = IMPORTER_VERSION_RE.search(header_content) + doc_match = IMPORTER_VERSION_RE.search(content) + if not header_match or not doc_match: + return [] + + current_version = header_match.group(1) + documented_version = doc_match.group(1) + if current_version == documented_version: + return [] + + matches: list[StaleDocTokenMatch] = [] + for line_number, raw_line in enumerate(content.splitlines(), start=1): + if documented_version not in raw_line or "kCurrentImporterVersion" not in raw_line: + continue + + matches.append( + StaleDocTokenMatch( + doc_page=rel_page, + token=f"kCurrentImporterVersion = {documented_version}", + reason=f"与当前 AssetDatabase 头文件中的 importer 版本 `{current_version}` 不符", + line_number=line_number, + line_text=raw_line.strip(), + ) + ) + break + + return matches + + def collect_doc_state(report_path: Path) -> dict[str, object]: markdown_files = iter_markdown_files() canonical_markdown_files = iter_canonical_markdown_files() public_headers = iter_public_headers() + editor_headers = iter_editor_source_headers() public_include_dirs = iter_public_include_dirs() declared_header_refs: set[str] = set() valid_header_refs: set[str] = set() canonical_valid_header_refs: set[str] = set() invalid_header_refs: list[tuple[str, str]] = [] + declared_source_refs: set[str] = set() + valid_source_refs: set[str] = set() + canonical_valid_source_refs: set[str] = set() + invalid_source_refs: list[tuple[str, str]] = [] broken_md_links: list[tuple[str, str]] = [] non_md_relative_links: list[tuple[str, str]] = [] old_template_pages: list[str] = [] flat_header_pages: list[str] = [] + editor_source_pages: dict[str, list[str]] = defaultdict(list) + stale_canonical_doc_token_matches: list[StaleDocTokenMatch] = [] + stale_editor_doc_token_matches: list[StaleDocTokenMatch] = [] + stale_editor_canonical_page_matches: list[StaleCanonicalPageMatch] = [] metadata_counts = { "namespace": 0, "type": 0, "description": 0, "header": 0, + "source_file": 0, } for page in markdown_files: + if page.resolve() == report_path.resolve(): + continue rel_page = normalize_rel_path(page.relative_to(DOC_ROOT).as_posix()) content = page.read_text(encoding="utf-8") is_canonical_page = rel_page.startswith("XCEngine/") @@ -144,6 +515,8 @@ def collect_doc_state(report_path: Path) -> dict[str, object]: metadata_counts["description"] += 1 if is_canonical_page and HEADER_RE.search(content): metadata_counts["header"] += 1 + if is_canonical_page and SOURCE_FILE_RE.search(content): + metadata_counts["source_file"] += 1 if is_canonical_page and LEGACY_SECTION_RE.search(content): old_template_pages.append(rel_page) @@ -151,6 +524,25 @@ def collect_doc_state(report_path: Path) -> dict[str, object]: if is_flat_header_page(page, rel_page): flat_header_pages.append(rel_page) + for stale_page, reason in STALE_EDITOR_CANONICAL_PAGES: + if rel_page == stale_page: + stale_editor_canonical_page_matches.append( + StaleCanonicalPageMatch( + doc_page=rel_page, + reason=reason, + ) + ) + + stale_editor_doc_token_matches.extend( + collect_stale_editor_doc_token_matches(rel_page, content) + ) + stale_canonical_doc_token_matches.extend( + collect_stale_canonical_doc_token_matches(rel_page, content) + ) + stale_canonical_doc_token_matches.extend( + collect_dynamic_canonical_doc_token_matches(rel_page, content) + ) + for match in HEADER_RE.finditer(content): header = normalize_rel_path(match.group(1)) declared_header_refs.add(header) @@ -161,6 +553,17 @@ def collect_doc_state(report_path: Path) -> dict[str, object]: elif is_canonical_page: invalid_header_refs.append((rel_page, header)) + for match in SOURCE_FILE_RE.finditer(content): + source_file = normalize_rel_path(match.group(1)) + declared_source_refs.add(source_file) + if source_file.startswith("editor/src/") and (REPO_ROOT / source_file).exists(): + valid_source_refs.add(source_file) + if rel_page.startswith("XCEngine/Editor/"): + canonical_valid_source_refs.add(source_file) + editor_source_pages[source_file].append(rel_page) + elif rel_page.startswith("XCEngine/Editor/"): + invalid_source_refs.append((rel_page, source_file)) + if is_canonical_page or rel_page.startswith(("_meta/", "_tools/")): link_scan_content = strip_fenced_code_blocks(content) for _, target in MD_LINK_RE.findall(link_scan_content): @@ -197,15 +600,23 @@ def collect_doc_state(report_path: Path) -> dict[str, object]: ) for module, headers in sorted(public_by_module.items()) ] + editor_module_coverages = build_editor_module_coverages( + editor_headers, + canonical_valid_source_refs, + ) missing_headers = [ header for header in public_headers if header not in canonical_valid_header_refs ] + missing_editor_headers = [ + header for header in editor_headers if header not in canonical_valid_source_refs + ] missing_parallel_indexes = [ relative for relative in public_include_dirs if not dir_index_doc_path(relative).exists() ] + editor_risk_entries = collect_editor_risk_entries(editor_source_pages) support_top_dirs = sorted( path.name for path in DOC_ROOT.iterdir() @@ -222,11 +633,22 @@ def collect_doc_state(report_path: Path) -> dict[str, object]: "valid_header_refs": sorted(valid_header_refs), "canonical_valid_header_refs": sorted(canonical_valid_header_refs), "invalid_header_refs": invalid_header_refs, + "declared_source_refs": sorted(declared_source_refs), + "valid_source_refs": sorted(valid_source_refs), + "canonical_valid_source_refs": sorted(canonical_valid_source_refs), + "invalid_source_refs": invalid_source_refs, "broken_md_links": broken_md_links, "non_md_relative_links": non_md_relative_links, "old_template_pages": sorted(old_template_pages), "flat_header_pages": sorted(flat_header_pages), + "stale_canonical_doc_token_matches": stale_canonical_doc_token_matches, + "stale_editor_doc_token_matches": stale_editor_doc_token_matches, + "stale_editor_canonical_page_matches": stale_editor_canonical_page_matches, "missing_headers": missing_headers, + "editor_headers": editor_headers, + "editor_module_coverages": editor_module_coverages, + "missing_editor_headers": missing_editor_headers, + "editor_risk_entries": editor_risk_entries, "module_coverages": module_coverages, "metadata_counts": metadata_counts, "support_top_dirs": support_top_dirs, @@ -249,15 +671,25 @@ def build_report(state: dict[str, object]) -> str: markdown_files: list[Path] = state["markdown_files"] # type: ignore[assignment] canonical_markdown_files: list[Path] = state["canonical_markdown_files"] # type: ignore[assignment] public_headers: list[str] = state["public_headers"] # type: ignore[assignment] + editor_headers: list[str] = state["editor_headers"] # type: ignore[assignment] public_include_dirs: list[str] = state["public_include_dirs"] # type: ignore[assignment] valid_header_refs: list[str] = state["valid_header_refs"] # type: ignore[assignment] canonical_valid_header_refs: list[str] = state["canonical_valid_header_refs"] # type: ignore[assignment] invalid_header_refs: list[tuple[str, str]] = state["invalid_header_refs"] # type: ignore[assignment] + valid_source_refs: list[str] = state["valid_source_refs"] # type: ignore[assignment] + canonical_valid_source_refs: list[str] = state["canonical_valid_source_refs"] # type: ignore[assignment] + invalid_source_refs: list[tuple[str, str]] = state["invalid_source_refs"] # type: ignore[assignment] broken_md_links: list[tuple[str, str]] = state["broken_md_links"] # type: ignore[assignment] non_md_relative_links: list[tuple[str, str]] = state["non_md_relative_links"] # type: ignore[assignment] old_template_pages: list[str] = state["old_template_pages"] # type: ignore[assignment] flat_header_pages: list[str] = state["flat_header_pages"] # type: ignore[assignment] + stale_canonical_doc_token_matches: list[StaleDocTokenMatch] = state["stale_canonical_doc_token_matches"] # type: ignore[assignment] + stale_editor_doc_token_matches: list[StaleDocTokenMatch] = state["stale_editor_doc_token_matches"] # type: ignore[assignment] + stale_editor_canonical_page_matches: list[StaleCanonicalPageMatch] = state["stale_editor_canonical_page_matches"] # type: ignore[assignment] missing_headers: list[str] = state["missing_headers"] # type: ignore[assignment] + missing_editor_headers: list[str] = state["missing_editor_headers"] # type: ignore[assignment] + editor_module_coverages: list[ModuleCoverage] = state["editor_module_coverages"] # type: ignore[assignment] + editor_risk_entries: list[EditorRiskEntry] = state["editor_risk_entries"] # type: ignore[assignment] module_coverages: list[ModuleCoverage] = state["module_coverages"] # type: ignore[assignment] metadata_counts: dict[str, int] = state["metadata_counts"] # type: ignore[assignment] support_top_dirs: list[str] = state["support_top_dirs"] # type: ignore[assignment] @@ -275,13 +707,21 @@ def build_report(state: dict[str, object]) -> str: lines.append(f"- Markdown 页面数（全部）: `{len(markdown_files)}`") lines.append(f"- Markdown 页面数（canonical）: `{len(canonical_markdown_files)}`") lines.append(f"- Public headers 数: `{len(public_headers)}`") + lines.append(f"- Editor source headers 数: `{len(editor_headers)}`") lines.append(f"- 有效头文件引用数（全部）: `{len(valid_header_refs)}`") lines.append(f"- 有效头文件引用数（canonical）: `{len(canonical_valid_header_refs)}`") lines.append(f"- 无效头文件引用数: `{len(invalid_header_refs)}`") + lines.append(f"- 有效源文件引用数（全部）: `{len(valid_source_refs)}`") + lines.append(f"- 有效源文件引用数（Editor canonical）: `{len(canonical_valid_source_refs)}`") + lines.append(f"- 无效源文件引用数: `{len(invalid_source_refs)}`") lines.append(f"- 失效 `.md` 链接数: `{len(broken_md_links)}`") lines.append(f"- 非 `.md` 相对链接数: `{len(non_md_relative_links)}`") lines.append(f"- 旧模板页面数: `{len(old_template_pages)}`") lines.append(f"- 扁平 header 页面数: `{len(flat_header_pages)}`") + lines.append(f"- Canonical 显式过期符号残留数: `{len(stale_canonical_doc_token_matches)}`") + lines.append(f"- Editor 显式过期符号残留数: `{len(stale_editor_doc_token_matches)}`") + lines.append(f"- Editor 残留 canonical 旧页面数: `{len(stale_editor_canonical_page_matches)}`") + lines.append(f"- Editor 高风险单页目录数: `{len(editor_risk_entries)}`") lines.append("") lines.append("## 平行目录") lines.append("") @@ -304,6 +744,16 @@ def build_report(state: dict[str, object]) -> str: f"`{coverage.documented_headers}` | `{coverage.missing_headers}` |" ) lines.append("") + lines.append("## Editor 源文件页覆盖") + lines.append("") + lines.append("| 模块 | Source headers | 已覆盖 | 未覆盖 |") + lines.append("|------|----------------|--------|--------|") + for coverage in editor_module_coverages: + lines.append( + f"| `{coverage.module}` | `{coverage.public_headers}` | " + f"`{coverage.documented_headers}` | `{coverage.missing_headers}` |" + ) + lines.append("") lines.append("## 元信息覆盖") lines.append("") lines.append("| 字段 | 页面数 |") @@ -312,6 +762,7 @@ def build_report(state: dict[str, object]) -> str: lines.append(f"| `类型` | `{metadata_counts['type']}` |") lines.append(f"| `描述` | `{metadata_counts['description']}` |") lines.append(f"| `头文件` | `{metadata_counts['header']}` |") + lines.append(f"| `源文件` | `{metadata_counts['source_file']}` |") lines.append("") if missing_parallel_indexes: @@ -327,6 +778,12 @@ def build_report(state: dict[str, object]) -> str: lines.extend(format_pairs_table(("文档", "头文件"), invalid_header_refs[:50])) lines.append("") + if invalid_source_refs: + lines.append("## 无效源文件引用") + lines.append("") + lines.extend(format_pairs_table(("文档", "源文件"), invalid_source_refs[:50])) + lines.append("") + if broken_md_links: lines.append("## 失效 Markdown 链接") lines.append("") @@ -357,6 +814,49 @@ def build_report(state: dict[str, object]) -> str: lines.append(f"- 其余 `{len(flat_header_pages) - 120}` 个页面请直接运行脚本查看。") lines.append("") + if stale_canonical_doc_token_matches: + lines.append("## Canonical 显式过期符号残留") + lines.append("") + lines.append("| 文档页 | 过期符号 | 原因 | 行号 | 行内容 |") + lines.append("|------|----------|------|------|--------|") + for entry in stale_canonical_doc_token_matches[:80]: + safe_line_text = entry.line_text.replace("|", "\\|") + lines.append( + f"| `{entry.doc_page}` | `{entry.token}` | `{entry.reason}` | " + f"`{entry.line_number}` | `{safe_line_text}` |" + ) + if len(stale_canonical_doc_token_matches) > 80: + lines.append( + f"| `...` | `...` | `...` | `...` | 其余 `{len(stale_canonical_doc_token_matches) - 80}` 项请直接运行脚本查看 |" + ) + lines.append("") + + if stale_editor_doc_token_matches: + lines.append("## Editor 显式过期符号残留") + lines.append("") + lines.append("| 文档页 | 过期符号 | 原因 | 行号 | 行内容 |") + lines.append("|------|----------|------|------|--------|") + for entry in stale_editor_doc_token_matches[:80]: + safe_line_text = entry.line_text.replace("|", "\\|") + lines.append( + f"| `{entry.doc_page}` | `{entry.token}` | `{entry.reason}` | " + f"`{entry.line_number}` | `{safe_line_text}` |" + ) + if len(stale_editor_doc_token_matches) > 80: + lines.append( + f"| `...` | `...` | `...` | `...` | 其余 `{len(stale_editor_doc_token_matches) - 80}` 项请直接运行脚本查看 |" + ) + lines.append("") + + if stale_editor_canonical_page_matches: + lines.append("## Editor 残留 canonical 旧页面") + lines.append("") + lines.append("| 文档页 | 原因 |") + lines.append("|------|------|") + for entry in stale_editor_canonical_page_matches: + lines.append(f"| `{entry.doc_page}` | `{entry.reason}` |") + lines.append("") + if missing_headers: lines.append("## 未覆盖的 public headers") lines.append("") @@ -366,6 +866,32 @@ def build_report(state: dict[str, object]) -> str: lines.append(f"- 其余 `{len(missing_headers) - 120}` 个 header 请直接运行脚本查看。") lines.append("") + if missing_editor_headers: + lines.append("## 未覆盖的 Editor 源文件页") + lines.append("") + for header in missing_editor_headers[:120]: + lines.append(f"- `{header}`") + if len(missing_editor_headers) > 120: + lines.append(f"- 其余 `{len(missing_editor_headers) - 120}` 个源文件请直接运行脚本查看。") + lines.append("") + + if editor_risk_entries: + lines.append("## Editor 高风险单页目录") + lines.append("") + lines.append("| 文档页 | 源文件 | 目录内直系页面数 | public 成员函数数 | 对应 `.cpp` 有效行数 |") + lines.append("|------|--------|------------------|-------------------|----------------------|") + for entry in editor_risk_entries[:40]: + lines.append( + f"| `{entry.doc_page}` | `{entry.source_file}` | " + f"`{entry.direct_page_count}` | `{entry.public_method_count}` | " + f"`{entry.implementation_line_count}` |" + ) + if len(editor_risk_entries) > 40: + lines.append( + f"| `...` | `...` | `...` | `...` | 其余 `{len(editor_risk_entries) - 40}` 项请直接运行脚本查看 |" + ) + lines.append("") + return "\n".join(lines).rstrip() + "\n" @@ -386,14 +912,22 @@ def main() -> int: print(f"Markdown pages (all): {len(state['markdown_files'])}") print(f"Markdown pages (canonical): {len(state['canonical_markdown_files'])}") print(f"Public headers: {len(state['public_headers'])}") + print(f"Editor source headers: {len(state['editor_headers'])}") print(f"Valid header refs (all): {len(state['valid_header_refs'])}") print(f"Valid header refs (canonical): {len(state['canonical_valid_header_refs'])}") print(f"Invalid header refs: {len(state['invalid_header_refs'])}") + print(f"Valid source refs (all): {len(state['valid_source_refs'])}") + print(f"Valid source refs (Editor canonical): {len(state['canonical_valid_source_refs'])}") + print(f"Invalid source refs: {len(state['invalid_source_refs'])}") print(f"Broken .md links: {len(state['broken_md_links'])}") print(f"Non-.md relative links: {len(state['non_md_relative_links'])}") print(f"Old template pages: {len(state['old_template_pages'])}") print(f"Flat header pages: {len(state['flat_header_pages'])}") + print(f"Stale canonical doc tokens: {len(state['stale_canonical_doc_token_matches'])}") + print(f"Stale editor doc tokens: {len(state['stale_editor_doc_token_matches'])}") + print(f"Stale editor canonical pages: {len(state['stale_editor_canonical_page_matches'])}") print(f"Missing directory index pages: {len(state['missing_parallel_indexes'])}") + print(f"Editor high-risk single-page dirs: {len(state['editor_risk_entries'])}") print(f"Report written to: {report_path}") return 0 diff --git a/docs/api/_tools/cleanup_template_api_docs.py b/docs/api/_tools/cleanup_template_api_docs.py new file mode 100644 index 00000000..3f56ebe6 --- /dev/null +++ b/docs/api/_tools/cleanup_template_api_docs.py @@ -0,0 +1,641 @@ +#!/usr/bin/env python3 +from __future__ import annotations + +import re +from dataclasses import dataclass +from pathlib import Path + +from generate_core_resources_canonical_pages import ( + DOC_ROOT, + INCLUDE_ROOT, + REPO_ROOT, + build_namespace_map, + find_declarations, + group_methods, + select_primary, +) + + +TEMPLATE_METHOD_TOKENS = ( + "当前页面用于固定", + "获取相关状态或对象。", + "设置相关状态或配置。", + "加载资源或数据。", + "公开方法，详见头文件声明。", + "参数语义详见头文件声明。", + "返回值语义详见头文件声明。", +) +TEMPLATE_TABLE_TOKENS = ( + "获取相关状态或对象。", + "设置相关状态或配置。", + "加载资源或数据。", + "公开方法，详见头文件声明。", +) +GENERIC_FALLBACK_RE = re.compile( + r"执行该公开方法对应的当前实现。|" + r"返回 `[^`]+` 相关结果。|" + r"更新 `[^`]+` 相关状态。|" + r"判断 `[^`]+` 条件是否成立。|" + r"判断是否具备 `[^`]+`。|" + r"判断当前是否可以执行 `[^`]+`。" +) +METHOD_SECTION_RE = re.compile(r"(?ms)^## 公共方法\n.*?(?=\n## |\Z)") +BLOCK_COMMENT_RE = re.compile(r"/\*.*?\*/", re.DOTALL) +LINE_COMMENT_RE = re.compile(r"//.*") +RETURN_MEMBER_RE = re.compile(r"^return\s+(m_[A-Za-z_]\w*)\s*;?$") +RETURN_MEMBER_METHOD_RE = re.compile( + r"^return\s+(m_[A-Za-z_]\w*)\.(Data|data|Size|size|CStr|c_str|Get)\s*\((.*?)\)\s*;?$" +) +RETURN_SIMPLE_CALL_RE = re.compile(r"^return\s+([A-Za-z_]\w*(?:::[A-Za-z_]\w*)*)\s*\((.*)\)\s*;?$") +RETURN_CONST_RE = re.compile(r"^return\s+([^;]+?)\s*;?$") +ASSIGN_MEMBER_RE = re.compile(r"^(m_[A-Za-z_]\w*)\s*=\s*([^;]+?)\s*;?$") +MEMBER_WRITE_RE = re.compile(r"\b(m_[A-Za-z_]\w*)\b\s*(?:=|\+=|-=|\*=|/=|%=|>>=|<<=|\+\+|--)") +MEMBER_CALL_RE = re.compile(r"\b(m_[A-Za-z_]\w*)\.(\w+)\s*\(") +DIRECT_CALL_RE = re.compile(r"\b([A-Za-z_]\w*(?:::[A-Za-z_]\w*)*)\s*\(") +ARROW_CALL_RE = re.compile(r"->\s*([A-Za-z_]\w*)\s*\(") +DOT_CALL_RE = re.compile(r"\.\s*([A-Za-z_]\w*)\s*\(") +FIELD_NAME_RE = re.compile(r"\bm_[A-Za-z_]\w*\b") + +KEYWORDS = { + "if", + "for", + "while", + "switch", + "return", + "sizeof", + "static_cast", + "reinterpret_cast", + "const_cast", + "dynamic_cast", + "catch", + "new", + "delete", +} +MUTATING_MEMBER_CALLS = { + "Append", + "Assign", + "Clear", + "ClearDirty", + "Emplace", + "Erase", + "Insert", + "PopBack", + "PushBack", + "Release", + "Remove", + "Reset", + "Resize", + "Set", + "SetInvalid", + "Shrink", +} + + +@dataclass +class ImplementationFact: + summary: str | None + details: list[str] + + +@dataclass +class ImplementationBlock: + kind: str + body: str + + +def has_any_token(content: str, tokens: tuple[str, ...]) -> bool: + return any(token in content for token in tokens) + + +def has_generic_fallback(content: str) -> bool: + return GENERIC_FALLBACK_RE.search(content) is not None + + +def strip_comments(text: str) -> str: + return LINE_COMMENT_RE.sub("", BLOCK_COMMENT_RE.sub("", text)) + + +def normalize_whitespace(text: str) -> str: + return " ".join(text.strip().split()) + + +def split_statements(body: str) -> list[str]: + parts: list[str] = [] + current: list[str] = [] + depth_paren = 0 + depth_brace = 0 + depth_angle = 0 + + for char in body: + if char == "(": + depth_paren += 1 + elif char == ")": + depth_paren = max(0, depth_paren - 1) + elif char == "{": + depth_brace += 1 + elif char == "}": + depth_brace = max(0, depth_brace - 1) + elif char == "<": + depth_angle += 1 + elif char == ">": + depth_angle = max(0, depth_angle - 1) + + if char == ";" and depth_paren == 0 and depth_brace == 0 and depth_angle == 0: + statement = "".join(current).strip() + if statement: + parts.append(statement) + current = [] + continue + + current.append(char) + + tail = "".join(current).strip() + if tail: + parts.append(tail) + return parts + + +def camel_tail(name: str, prefix_len: int) -> str: + tail = name[prefix_len:] + return tail or name + + +def format_identifier_list(items: list[str]) -> str: + unique: list[str] = [] + seen: set[str] = set() + for item in items: + if item in seen: + continue + unique.append(item) + seen.add(item) + return "、".join(f"`{item}`" for item in unique) + + +def extract_balanced(text: str, start: int, open_char: str, close_char: str) -> tuple[str, int] | None: + depth = 0 + for index in range(start, len(text)): + char = text[index] + if char == open_char: + depth += 1 + elif char == close_char: + depth -= 1 + if depth == 0: + return text[start:index + 1], index + 1 + return None + + +def scan_definition_suffix(text: str, start: int) -> tuple[str, int]: + index = start + while True: + while index < len(text) and text[index].isspace(): + index += 1 + + if text.startswith("const", index): + index += len("const") + continue + if text.startswith("override", index): + index += len("override") + continue + if text.startswith("final", index): + index += len("final") + continue + if text.startswith("constexpr", index): + index += len("constexpr") + continue + if text.startswith("noexcept", index): + index += len("noexcept") + while index < len(text) and text[index].isspace(): + index += 1 + if index < len(text) and text[index] == "(": + extracted = extract_balanced(text, index, "(", ")") + if extracted: + _, index = extracted + continue + if index < len(text) and text[index] in {"&", "*"}: + index += 1 + continue + break + + if text.startswith("= default", index): + return "default", index + len("= default") + if text.startswith("= delete", index): + return "delete", index + len("= delete") + if index < len(text) and text[index] == "{": + return "body", index + return "", index + + +def extract_qualified_blocks(text: str, class_name: str, method_name: str) -> list[ImplementationBlock]: + pattern = re.compile(rf"{re.escape(class_name)}\s*::\s*{re.escape(method_name)}\s*\(") + blocks: list[ImplementationBlock] = [] + + for match in pattern.finditer(text): + params_start = text.find("(", match.start()) + extracted = extract_balanced(text, params_start, "(", ")") + if not extracted: + continue + _, cursor = extracted + kind, suffix_pos = scan_definition_suffix(text, cursor) + if kind == "body": + body_block = extract_balanced(text, suffix_pos, "{", "}") + if body_block: + body, _ = body_block + blocks.append(ImplementationBlock(kind="body", body=body[1:-1])) + elif kind in {"default", "delete"}: + blocks.append(ImplementationBlock(kind=kind, body="")) + + return blocks + + +def extract_inline_blocks(text: str, method_name: str) -> list[ImplementationBlock]: + pattern = re.compile(rf"{re.escape(method_name)}\s*\(") + blocks: list[ImplementationBlock] = [] + + for match in pattern.finditer(text): + previous = text[match.start() - 1] if match.start() > 0 else "" + if previous.isalnum() or previous in {":", ".", ">"}: + continue + + params_start = text.find("(", match.start()) + extracted = extract_balanced(text, params_start, "(", ")") + if not extracted: + continue + _, cursor = extracted + kind, suffix_pos = scan_definition_suffix(text, cursor) + if kind == "body": + body_block = extract_balanced(text, suffix_pos, "{", "}") + if body_block: + body, _ = body_block + blocks.append(ImplementationBlock(kind="body", body=body[1:-1])) + elif kind in {"default", "delete"}: + blocks.append(ImplementationBlock(kind=kind, body="")) + + return blocks + + +def summarize_return_value(expr: str) -> str: + cleaned = normalize_whitespace(expr) + if cleaned in {"true", "false", "nullptr"}: + return f"固定返回 `{cleaned}`。" + if FIELD_NAME_RE.fullmatch(cleaned): + return f"返回 `{cleaned}` 当前值。" + if cleaned.endswith("()"): + return f"返回 `{cleaned}` 的结果。" + return f"返回 `{cleaned}`。" + + +def analyze_simple_statement(statement: str) -> ImplementationFact | None: + normalized = normalize_whitespace(statement) + if not normalized: + return None + + match = RETURN_MEMBER_RE.match(normalized) + if match: + field = match.group(1) + return ImplementationFact( + summary=f"返回 `{field}` 当前值。", + details=[f"内联返回 `{field}`。"], + ) + + match = RETURN_MEMBER_METHOD_RE.match(normalized) + if match: + field, method, args = match.groups() + if method.lower() == "data": + summary = f"返回 `{field}` 暴露的首地址。" + elif method.lower() == "size": + summary = f"返回 `{field}` 当前大小。" + elif method in {"CStr", "c_str"}: + summary = f"返回 `{field}` 的 C 风格字符串视图。" + else: + summary = f"返回 `{field}.{method}()` 的结果。" + detail = f"当前实现直接调用 `{field}.{method}({args})`。".replace("()", "()") + return ImplementationFact(summary=summary, details=[detail]) + + match = ASSIGN_MEMBER_RE.match(normalized) + if match: + field, value = match.groups() + return ImplementationFact( + summary=f"写入 `{field}`。", + details=[f"当前实现把 `{value}` 写入 `{field}`。"], + ) + + match = RETURN_SIMPLE_CALL_RE.match(normalized) + if match: + call_name = match.group(1) + return ImplementationFact( + summary=f"返回 `{call_name}(...)` 的结果。", + details=[f"当前实现直接转发到 `{call_name}(...)`。"], + ) + + match = RETURN_CONST_RE.match(normalized) + if match: + return ImplementationFact( + summary=summarize_return_value(match.group(1)), + details=[summarize_return_value(match.group(1))], + ) + + return None + + +def collect_calls(body: str) -> list[str]: + calls: list[str] = [] + for regex in (DIRECT_CALL_RE, ARROW_CALL_RE, DOT_CALL_RE): + for match in regex.finditer(body): + name = match.group(1) + short_name = name.split("::")[-1] + if short_name in KEYWORDS: + continue + calls.append(short_name) + return calls + + +def collect_member_writes(body: str) -> list[str]: + writes = MEMBER_WRITE_RE.findall(body) + for field, method in MEMBER_CALL_RE.findall(body): + if method in MUTATING_MEMBER_CALLS or method.startswith("Set"): + writes.append(field) + deduped: list[str] = [] + seen: set[str] = set() + for field in writes: + if field in seen: + continue + deduped.append(field) + seen.add(field) + return deduped + + +def analyze_complex_body(body: str) -> ImplementationFact: + stripped = strip_comments(body) + normalized = normalize_whitespace(stripped) + statements = [normalize_whitespace(item) for item in split_statements(stripped)] + + if not normalized: + return ImplementationFact( + summary="当前实现为空。", + details=["当前函数体为空。"], + ) + + if len(statements) == 1: + simple = analyze_simple_statement(statements[0]) + if simple: + return simple + + details: list[str] = [] + summary: str | None = None + + writes = collect_member_writes(stripped) + if writes: + details.append(f"会更新 {format_identifier_list(writes[:4])}。") + if len(writes) == 1 and summary is None: + summary = f"更新 `{writes[0]}`。" + + calls = collect_calls(stripped) + filtered_calls = [call for call in calls if call not in {"Get", "Set", "Data", "Size"}] + if filtered_calls: + details.append(f"当前实现会调用 {format_identifier_list(filtered_calls[:5])}。") + if summary is None and len(filtered_calls) == 1: + summary = f"执行 `{filtered_calls[0]}(...)` 相关流程。" + elif summary is None: + summary = f"执行 {format_identifier_list(filtered_calls[:3])} 协同流程。" + + return_values = re.findall(r"\breturn\s+([^;]+);", stripped) + if len(return_values) > 1 or ("if (" in stripped and return_values): + details.append("包含条件分支，并可能提前返回。") + elif return_values and summary is None: + summary = summarize_return_value(return_values[0]) + + if "nullptr" in stripped: + details.append("包含 `nullptr` 相关分支。") + if "not implemented" in stripped or "未实现" in stripped: + details.append("当前实现仍带有未完成分支。") + + if summary is None: + summary = "执行该公开方法对应的当前实现。" + + return ImplementationFact(summary=summary, details=details or [summary]) + + +def dedupe_lines(lines: list[str]) -> list[str]: + result: list[str] = [] + seen: set[str] = set() + for line in lines: + if line in seen: + continue + seen.add(line) + result.append(line) + return result + + +def analyze_method_group( + class_name: str, + method_name: str, + overloads: list[dict[str, object]], + header_text: str, + source_text: str, + source_rel: str | None, +) -> ImplementationFact: + implementation_blocks = extract_qualified_blocks(source_text, class_name, method_name) + if not implementation_blocks: + implementation_blocks = extract_inline_blocks(header_text, method_name) + + details: list[str] = [] + summaries: list[str] = [] + + for overload in overloads: + suffix = str(overload.get("suffix", "")).strip() + if "= 0" in suffix: + summaries.append("纯虚接口。") + details.append("该声明是纯虚接口，基类不提供实现。") + + for block in implementation_blocks: + if block.kind == "default": + if method_name == class_name: + summaries.append(f"构造 `{class_name}` 实例。") + details.append("当前为默认构造实现。") + elif method_name == f"~{class_name}": + summaries.append(f"销毁 `{class_name}` 实例。") + details.append("当前为默认析构实现。") + else: + details.append("当前为 `= default` 实现。") + continue + + if block.kind == "delete": + details.append("当前声明为 `= delete`。") + continue + + fact = analyze_complex_body(block.body) + if fact.summary: + summaries.append(fact.summary) + details.extend(fact.details) + + if not details and source_rel: + details.append(f"具体定义位于 `{source_rel}`。") + + short_desc = next((item for item in summaries if item), None) + if short_desc is None: + if method_name == class_name: + short_desc = f"构造 `{class_name}` 实例。" + elif method_name == f"~{class_name}": + short_desc = f"销毁 `{class_name}` 实例。" + elif method_name.startswith("Get"): + short_desc = f"返回 `{camel_tail(method_name, 3)}` 相关结果。" + elif method_name.startswith("Set"): + short_desc = f"更新 `{camel_tail(method_name, 3)}` 相关状态。" + elif method_name.startswith("Is"): + short_desc = f"判断 `{camel_tail(method_name, 2)}` 条件是否成立。" + elif method_name.startswith("Has"): + short_desc = f"判断是否具备 `{camel_tail(method_name, 3)}`。" + elif method_name.startswith("Can"): + short_desc = f"判断当前是否可以执行 `{camel_tail(method_name, 3)}`。" + elif method_name.startswith("Load"): + short_desc = f"执行 `{method_name}` 加载流程。" + elif method_name.startswith("Create"): + short_desc = f"执行 `{method_name}` 创建流程。" + elif method_name.startswith("Update"): + short_desc = f"执行一次 `{method_name}` 更新。" + else: + short_desc = f"执行 `{method_name}` 对应的公开操作。" + + if not details: + details.append(short_desc) + + return ImplementationFact(summary=short_desc, details=dedupe_lines(details)) + + +def build_method_page( + class_name: str, + namespace: str, + relative_header: str, + group: dict[str, object], + analysis: ImplementationFact, +) -> str: + label = str(group["label"]) + method_name = str(group["method_name"]) + overloads: list[dict[str, object]] = group["overloads"] # type: ignore[assignment] + + lines: list[str] = [] + lines.append(f"# {class_name}::{label}") + lines.append("") + lines.append(f"**命名空间**: `{namespace}`") + lines.append("") + lines.append("**类型**: `method`") + lines.append("") + lines.append(f"**头文件**: `{relative_header}`") + lines.append("") + lines.append("## 签名") + lines.append("") + lines.append("```cpp") + for overload in overloads: + lines.append(f"{overload['signature']};") + lines.append("```") + lines.append("") + lines.append("## 作用") + lines.append("") + lines.append(analysis.summary) + lines.append("") + lines.append("## 当前实现") + lines.append("") + for detail in analysis.details: + lines.append(f"- {detail}") + lines.append("") + lines.append("## 相关文档") + lines.append("") + lines.append(f"- [{class_name}]({class_name}.md)") + if method_name.startswith("Get") and any(str(item["file_name"]) == f"Set{method_name[3:]}" for item in group.get("siblings", [])): # type: ignore[operator] + lines.append(f"- [Set{method_name[3:]}](Set{method_name[3:]}.md)") + elif method_name.startswith("Set") and any(str(item["file_name"]) == f"Get{method_name[3:]}" for item in group.get("siblings", [])): # type: ignore[operator] + lines.append(f"- [Get{method_name[3:]}](Get{method_name[3:]}.md)") + + return "\n".join(lines).rstrip() + "\n" + + +def rebuild_method_table( + content: str, + method_groups: list[dict[str, object]], + analyses: dict[str, ImplementationFact], +) -> str: + if "## 公共方法" not in content: + return content + + lines = ["## 公共方法", "", "| 方法 | 描述 |", "|------|------|"] + for group in method_groups: + file_name = str(group["file_name"]) + label = str(group["label"]) + description = analyses[file_name].summary + lines.append(f"| [{label}]({file_name}.md) | {description} |") + section = "\n".join(lines) + "\n" + return METHOD_SECTION_RE.sub(section, content) + + +def main() -> int: + rewritten_method_pages = 0 + rewritten_overviews = 0 + + for header_path in sorted(INCLUDE_ROOT.rglob("*.h")): + relative_header = header_path.relative_to(INCLUDE_ROOT.parent).as_posix() + relative_source = header_path.relative_to(INCLUDE_ROOT).with_suffix(".cpp") + source_path = REPO_ROOT / "engine" / "src" / relative_source + source_text = source_path.read_text(encoding="utf-8", errors="ignore") if source_path.exists() else "" + source_rel = source_path.relative_to(REPO_ROOT).as_posix() if source_path.exists() else None + + header_text = header_path.read_text(encoding="utf-8", errors="ignore") + lines = header_text.splitlines() + declarations = find_declarations(lines, build_namespace_map(lines)) + primary = select_primary(header_path.stem, declarations) + if primary is None or not primary.methods: + continue + + doc_dir = DOC_ROOT / "XCEngine" / header_path.parent.relative_to(INCLUDE_ROOT) / header_path.stem + if not doc_dir.exists(): + continue + + method_groups = group_methods(primary.methods, primary.name) + analyses: dict[str, ImplementationFact] = {} + for group in method_groups: + group["siblings"] = method_groups + analyses[str(group["file_name"])] = analyze_method_group( + primary.name, + str(group["method_name"]), + group["overloads"], # type: ignore[arg-type] + header_text, + source_text, + source_rel, + ) + + overview_path = doc_dir / f"{header_path.stem}.md" + if overview_path.exists(): + overview_content = overview_path.read_text(encoding="utf-8") + if has_any_token(overview_content, TEMPLATE_TABLE_TOKENS) or has_generic_fallback(overview_content): + updated = rebuild_method_table(overview_content, method_groups, analyses) + if updated != overview_content: + overview_path.write_text(updated, encoding="utf-8") + rewritten_overviews += 1 + + for group in method_groups: + file_name = str(group["file_name"]) + page_path = doc_dir / f"{file_name}.md" + if not page_path.exists(): + continue + + content = page_path.read_text(encoding="utf-8") + if not has_any_token(content, TEMPLATE_METHOD_TOKENS) and not has_generic_fallback(content): + continue + + updated = build_method_page( + primary.name, + primary.namespace, + relative_header, + group, + analyses[file_name], + ) + if updated != content: + page_path.write_text(updated, encoding="utf-8") + rewritten_method_pages += 1 + + print(f"Rewritten overview pages: {rewritten_overviews}") + print(f"Rewritten method pages: {rewritten_method_pages}") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/docs/blueprint-skill.md b/docs/blueprint-skill.md index 02c0cd24..8d76a174 100644 --- a/docs/blueprint-skill.md +++ b/docs/blueprint-skill.md @@ -2,42 +2,146 @@ ## 用途 -根据 XCEngine C++ 引擎源码生成符合规范的蓝图文档（系统架构设计文档），用于在 XCSDD 中 -以 3D 可视化图谱方式展示系统的模块结构、子系统依赖关系和接口定义。 +根据 XCEngine 当前工作树生成或重写 `docs/blueprint.md`，用于描述真实已落地的系统结构、子系统依赖、关键数据模型和当前演进方向。 -在开始编写任何蓝图文档之前，必须先完整阅读并深刻理解目标系统的源码上下文——包括设计目的、 -模块划分、依赖关系、数据流、边界条件等。切忌在未读懂系统架构的情况下仅凭目录结构或猜测 -来编写蓝图文档。 +蓝图不是愿景文档，也不是过期设计稿的搬运。它必须服从当前 checkout、当前 `CMakeLists.txt`、当前测试、当前项目布局和当前文档主线。 --- -## 文档目录结构 +## 当前仓库里的事实来源顺序 -``` -docs/ -├── blueprint.md # 蓝图总文档 -├── plan/ # 规划类文档 -└── api/ # API 文档（由 api-skill 管理） -``` +处理蓝图任务时，按下面顺序建立上下文： -**文件命名：** 蓝图文档统一命名为 `blueprint.md`，放在 `docs/` 目录下。 +1. 当前工作树与相关 `CMakeLists.txt` +2. [AGENT.md](../AGENT.md) +3. [README.md](../README.md) 与 [editor/README.md](../editor/README.md) +4. 对应模块的测试目录与聚合 target +5. `docs/plan/` 下仍活跃的设计 / 计划文档 + +如果旧文档与当前代码冲突，先信当前代码，再修文档。 --- -## 文档整体结构 +## 必须同步的活跃文档 -蓝图文档由多个 YAML 代码块通过 Markdown 标题分隔组成，所有 YAML 代码块共同构成 -系统的完整蓝图定义。文档结构如下： +当蓝图所描述的架构事实发生变化时，不要只改 `docs/blueprint.md`。 + +通常至少要检查这些活跃文档是否需要同步： + +- `docs/blueprint.md` +- `docs/blueprint-skill.md` +- `README.md` +- `editor/README.md` +- `AGENT.md` + +如果同时触及 API 术语、Editor 调用链或 source-backed API 页面： + +1. 先检查 `docs/plan/` 下是否有更新的 API 相关任务池或计划。 +2. 再检查 `docs/api-skill.md`。 +3. 必要时同步对应 `docs/api/**` 页面。 + +--- + +## 不要改的归档区域 + +以下目录默认视为归档背景材料，只读，不在本轮蓝图收口里直接改写： + +- `docs/plan/used/**` +- `docs/used/**` + +如果需要引用归档内容，只把它当历史上下文，不能让它覆盖当前事实。 + +--- + +## 蓝图写作的硬约束 + +### 1. 必须以当前工程结构为准 + +当前蓝图至少要覆盖这些活跃部分： + +- `engine/` +- `editor/` +- `managed/` +- `project/` +- `tests/` + +不要再传播这些过期说法： + +- “只有 D3D12 和 OpenGL 双后端” +- “还没有脚本系统” +- “还没有 Editor 主链” +- “`project/Library/` 可以忽略” +- “根目录存在 `native/` 占位项” + +### 2. Project / Library 是当前 workflow 的一部分 + +蓝图必须明确当前工程真实采用： + +- `Assets/ + .meta + Library/` +- `Project.xcproject` +- `Library/SourceAssetDB/assets.db` +- `Library/ArtifactDB/artifacts.db` +- `Library/Artifacts/` +- `Library/ScriptAssemblies/` + +不要把 `project/Library/` 写成“无关生成垃圾目录”。 + +### 3. Editor 是宿主，不是第二套渲染器 + +蓝图里描述 editor 时，要保持当前口径： + +- editor 是 `D3D12` 宿主应用 +- Scene / Game viewport 通过引擎 `Rendering + RHI` 离屏渲染 +- Scene View 当前 helper 链要按真实实现书写 + +当前主链以实际代码为准，最近主线是： + +`SceneViewportChrome -> SceneViewportInteractionFrame -> SceneViewportNavigation -> SceneViewportTransformGizmoCoordinator -> ViewportHostService` + +### 4. 脚本系统必须按当前 Mono 链路描述 + +蓝图必须体现当前脚本链路至少由这几部分构成： + +- `managed/XCEngine.ScriptCore/` +- `managed/GameScripts/` +- `project/Assets/**/*.cs` +- `project/Library/ScriptAssemblies/` +- `engine/src/Scripting/` +- `editor/src/Scripting/` + +如果本轮涉及脚本蓝图，额外核对： + +- `managed/CMakeLists.txt` +- `editor/src/Scripting/EditorScriptAssemblyBuilder.cpp` +- `tests/Scripting/` +- `tests/Editor/` + +### 5. Windows 路径大小写按真实目录名写 + +文档里统一写真实目录名，例如： + +- `tests/Core/` +- `tests/Rendering/` +- `tests/Editor/` +- `tests/Scripting/` + +不要制造无意义的大小写漂移。 + +--- + +## 蓝图文档结构 + +`docs/blueprint.md` 维持以下固定章节： ```markdown -# {系统名称} 蓝图 +# XCEngine 蓝图 --- # SYSTEM_META ```yaml -# 系统元信息 +... ``` --- @@ -45,7 +149,7 @@ docs/ # SYSTEM_STRUCTURE ```yaml -# 系统结构定义（核心必填） +... ``` --- @@ -53,7 +157,7 @@ docs/ # EVOLUTION_MODE ```yaml -# 演化模式 +... ``` --- @@ -61,7 +165,7 @@ docs/ # REQUIREMENTS ```yaml -# 需求列表 +... ``` --- @@ -69,7 +173,7 @@ docs/ # MVS_DEFINITION ```yaml -# 最小可行方案定义 +... ``` --- @@ -77,7 +181,7 @@ docs/ # DATA_MODELS ```yaml -# 数据模型定义 +... ``` --- @@ -85,385 +189,50 @@ docs/ # EVOLUTION_PLAN ```yaml -# 演化计划 +... ``` +``` + +要求： + +- 所有 YAML 代码块都必须能被正常解析 +- `SYSTEM_STRUCTURE` 里的子系统、依赖和模块名称要能在当前代码里找到对应锚点 +- 不要在同一份蓝图里同时保留互相矛盾的新旧架构 --- -## 页面类型与模板 +## 推荐收口流程 -### 1. SYSTEM_META（元信息） - -SYSTEM_META 是整个蓝图文档的元信息区，必须完整填写。 - -```yaml -name: {系统名称} -version: {版本号} -type: {系统类型} -description: "{系统一句话描述}" -target_runtime: {目标运行时} -``` - -### 2. SYSTEM_STRUCTURE（系统结构）—— 核心必填 - -SYSTEM_STRUCTURE 定义系统的子系统和模块结构，是 XCSDD 3D 可视化的核心数据来源。 -`subsystems` 和 `modules` 两个数组都被解析为 3D 图谱节点，依赖关系（`depends_on`）被解析为连线。 - -```yaml -root: {根模块名} - -subsystems: - - name: {子系统名} - responsibilities: - - "{职责描述1}" - - "{职责描述2}" - provides: [{提供的接口1}, {提供的接口2}] - depends_on: [{依赖的子系统名}] - boundary: - inputs: [{输入}] - outputs: [{输出}] - -modules: - - name: {模块名} - parent_subsystem: {所属子系统名} - responsibility: "{模块职责描述}" - public_api: - - fn: {函数名} - params: - - name: {参数名} - type: {参数类型} - returns: type: {返回类型} -``` - -### 3. EVOLUTION_MODE（演化模式） - -```yaml -mode: {build|evolve|maintain} -description: "{模式描述}" -context: | - {多行上下文说明} -``` - -### 4. REQUIREMENTS（需求列表） - -```yaml -- id: {REQ-ID} - title: {需求标题} - description: "{需求描述}" - source: {user|constraint} - type: {functional|non-functional} - acceptance_criteria: - - "{验收标准1}" - priority: {P0|P1|P2} -``` - -### 5. MVS_DEFINITION（MVS 最小可行方案） - -```yaml -mvs_solutions: - - id: {MVS-ID} - name: {方案名称} - goal: "{目标描述}" - - verification_criteria: - - "{验证标准1}" - - scope: - - subsystem: {子系统名} - components: [{组件名}] - - external: [{外部依赖}] - - code_structure: - - file: {文件名} - purpose: "{文件用途}" - contains: - - "{包含的功能1}" - standalone: {true|false} - - integration_plan: - - step: "{集成步骤1}" - - status: {pending|in_progress|completed} -``` - -### 6. DATA_MODELS（数据模型） - -```yaml -- name: {模型名} - description: "{模型描述}" - fields: - - name: {字段名} - type: {类型} - default: {默认值} - constraints: {required|optional} -``` - -### 7. EVOLUTION_PLAN（演化计划） - -```yaml -fix_plan: - - issue_id: {BUG-ID} - description: "{问题描述}" - root_cause: "{根本原因}" - minimal_change: - - file: {文件路径} - verification: "{验证方法}" - -refactor_plan: - - target: "{重构目标}" - constraints: ["{约束条件}"] - steps: ["{步骤1}"] - -feature_plan: - - feature_id: {FEAT-ID} - name: "{功能名称}" - addition: "{功能描述}" - integration_point: "{集成点}" - steps: ["{步骤1}"] -``` +1. 先读 `AGENT.md`、`README.md`、相关 `CMakeLists.txt`。 +2. 只抽取与本次蓝图相关的关键头文件、关键源文件、测试目录。 +3. 识别当前真实子系统边界，而不是沿用旧蓝图里的命名。 +4. 重写 `SYSTEM_META`、`SYSTEM_STRUCTURE`、`EVOLUTION_MODE`。 +5. 再补 `REQUIREMENTS`、`MVS_DEFINITION`、`DATA_MODELS`、`EVOLUTION_PLAN`。 +6. 回读整份蓝图，检查有没有把旧时期说法残留到新结构里。 +7. 如涉及主文档口径变化，同步检查 `README.md` / `editor/README.md` / `AGENT.md`。 --- -## 元信息字段规范 +## 一致性检查清单 -### SYSTEM_META +完成蓝图修改后，至少确认： -| 字段 | 必需 | 说明 | -|------|------|------| -| `name` | 是 | 系统名称，唯一标识 | -| `version` | 是 | 版本号，格式 x.y.z | -| `type` | 是 | 系统类型，如 `game-engine`、`web-framework`、`api-service` | -| `description` | 是 | 系统一句话功能描述 | -| `target_runtime` | 否 | 目标运行时，如 `C++17`、`WebAssembly`、`Python 3.10` | - -### SYSTEM_STRUCTURE - -#### subsystems 数组 - -| 字段 | 必需 | 说明 | -|------|------|------| -| `name` | 是 | 子系统名称，唯一标识 | -| `responsibilities` | 是 | 职责列表，至少 1 项 | -| `provides` | 是 | 提供的接口列表，表示该子系统对外暴露的能力 | -| `depends_on` | 是 | 依赖的子系统列表，引用的子系统必须存在 | -| `boundary` | 否 | 边界定义 | -| `boundary.inputs` | 否 | 该子系统的外部输入项 | -| `boundary.outputs` | 否 | 该子系统的外部输出项 | - -#### modules 数组 - -| 字段 | 必需 | 说明 | -|------|------|------| -| `name` | 是 | 模块名称，唯一标识 | -| `parent_subsystem` | 是 | 所属子系统名称，引用的子系统必须存在 | -| `responsibility` | 是 | 模块职责描述 | -| `public_api` | 是 | 公共 API 列表，至少 1 项 | -| `public_api[].fn` | 是 | 函数名 | -| `public_api[].params` | 是 | 参数列表 | -| `public_api[].params[].name` | 是 | 参数名 | -| `public_api[].params[].type` | 是 | 参数类型 | -| `public_api[].returns` | 否 | 返回值定义 | -| `public_api[].returns.type` | 是（当有 returns 时） | 返回类型 | - -### EVOLUTION_MODE - -| 字段 | 必需 | 说明 | -|------|------|------| -| `mode` | 是 | `build`（从零构建）、`evolve`（演进迭代）、`maintain`（维护修复） | -| `description` | 是 | 模式一句话描述 | -| `context` | 是 | 多行详细上下文说明，使用 `\|` 语法 | - -### REQUIREMENTS - -| 字段 | 必需 | 说明 | -|------|------|------| -| `id` | 是 | 需求 ID，格式 `REQ-XXX` | -| `title` | 是 | 需求标题，简短明确 | -| `description` | 是 | 需求详细描述 | -| `source` | 是 | `user`（用户需求）、`constraint`（约束条件） | -| `type` | 是 | `functional`（功能性）、`non-functional`（非功能性） | -| `acceptance_criteria` | 是 | 验收标准，至少 1 项 | -| `priority` | 是 | `P0`（关键，阻塞开发）、`P1`（重要）、`P2`（次要） | - -### MVS_DEFINITION - -| 字段 | 必需 | 说明 | -|------|------|------| -| `id` | 是 | MVS ID，格式 `MVS-XXX` | -| `name` | 是 | 最小可行方案名称 | -| `goal` | 是 | 目标描述 | -| `verification_criteria` | 是 | 验证标准，至少 1 项 | -| `scope` | 是 | 涉及范围（子系统 + 外部依赖） | -| `code_structure` | 是 | 代码结构文件列表，至少 1 项 | -| `code_structure[].file` | 是 | 文件名 | -| `code_structure[].purpose` | 是 | 文件用途描述 | -| `code_structure[].contains` | 是 | 包含的功能列表 | -| `code_structure[].standalone` | 是 | 是否独立可运行 | -| `integration_plan` | 是 | 集成计划步骤 | -| `status` | 是 | `pending`（待开始）、`in_progress`（进行中）、`completed`（已完成） | - -### DATA_MODELS - -| 字段 | 必需 | 说明 | -|------|------|------| -| `name` | 是 | 模型名称 | -| `description` | 是 | 模型描述 | -| `fields` | 是 | 字段列表 | -| `fields[].name` | 是 | 字段名 | -| `fields[].type` | 是 | 字段类型 | -| `fields[].default` | 否 | 默认值 | -| `fields[].constraints` | 否 | `required`（必填）或 `optional`（可选） | - -### EVOLUTION_PLAN - -| 字段 | 必需 | 说明 | -|------|------|------| -| `issue_id` | 是（在 fix_plan 项中） | 缺陷 ID，格式 `BUG-XXX` | -| `description` | 是 | 问题描述 | -| `root_cause` | 是（在 fix_plan 项中） | 根本原因 | -| `minimal_change` | 是（在 fix_plan 项中） | 最小修改文件列表 | -| `verification` | 是（在 fix_plan 项中） | 验证方法 | -| `target` | 是（在 refactor_plan 项中） | 重构目标 | -| `constraints` | 是（在 refactor_plan 项中） | 约束条件列表 | -| `steps` | 是（在 refactor_plan 项中） | 重构步骤列表 | -| `feature_id` | 是（在 feature_plan 项中） | 特性 ID，格式 `FEAT-XXX` | -| `name` | 是（在 feature_plan 项中） | 功能名称 | -| `addition` | 是（在 feature_plan 项中） | 功能描述 | -| `integration_point` | 是（在 feature_plan 项中） | 集成点 | +1. 后端数量与当前代码一致，`RHI` 现在是 `D3D12 / OpenGL / Vulkan`。 +2. `Rendering` 主链写成当前真实链路，而不是旧 sample 分支。 +3. `Editor` 被描述为宿主层，Scene View helper 链与当前实现一致。 +4. `Resources` / `Core/Asset` 明确覆盖 `.meta`、`assets.db`、`artifacts.db`、`Artifacts/`。 +5. `Scripting` 明确覆盖 `XCEngine.ScriptCore.dll`、`GameScripts.dll`、`project/Assets/**/*.cs` 和 `Library/ScriptAssemblies/`。 +6. `Project` 明确覆盖 `Project.xcproject`、`Assets/Scenes/*.xc` 和 `Library/`。 +7. `Tests` 与当前 `tests/` 目录和聚合 target 口径一致。 +8. 没有修改归档目录。 --- -## 必需章节规范 +## 目标 -### SYSTEM_META +最终产物应当让后来者只看当前蓝图，就能理解： -1. `name` — 系统名称 -2. `version` — 版本号 -3. `type` — 系统类型 -4. `description` — 系统描述 -5. `target_runtime` — 目标运行时 - -### SYSTEM_STRUCTURE - -1. `root` — 根模块名 -2. `subsystems` — 子系统列表，每个子系统至少包含 name、responsibilities、provides、depends_on -3. `modules` — 模块列表，每个模块至少包含 name、parent_subsystem、responsibility、public_api - -### EVOLUTION_MODE - -1. `mode` — 演化模式 -2. `description` — 模式描述 -3. `context` — 详细上下文 - -### REQUIREMENTS - -每个需求项至少包含 id、title、description、source、type、acceptance_criteria、priority。 - -### MVS_DEFINITION - -每个 MVS 方案至少包含 id、name、goal、verification_criteria、scope、code_structure、integration_plan、status。 - -### DATA_MODELS - -每个数据模型至少包含 name、description、fields。 - -### EVOLUTION_PLAN - -fix_plan、refactor_plan、feature_plan 至少包含各自必需字段。 - ---- - -## 依赖关系规范 - -### 子系统依赖 - -- `subsystems[].depends_on` 中引用的子系统名称必须在 `subsystems` 数组中存在 -- 不允许循环依赖（A → B → A），应在校验阶段检测并报告 -- 每个子系统的 `provides` 接口应当被其他子系统的 `depends_on` 引用（强推荐） - -### 模块归属 - -- `modules[].parent_subsystem` 引用的子系统必须在 `subsystems` 数组中存在 - ---- - -## 命名规范 - -### 驼峰命名（必需） - -所有标识符（子系统名、模块名）必须使用**驼峰命名法**，严禁使用下划线分隔。 - -| 正确示例 | 错误示例 | -|---------|---------| -| `CoreTypes` | `Core_Types`、`CoreTypes_` | -| `MathVector` | `Math_Vector`、`mathvector` | -| `RHICommandList` | `RHI_CommandList`、`RHICommand_List` | -| `DebugLogger` | `Debug_Logger` | -| `ResourcesManager` | `Resources_Manager` | - -**规则：** -- 子系统名：`{子系统}{子模块}` 或直接 `{子系统}`（如 `Core`、`Math`、`RHI`） -- 模块名：`{子系统}{功能描述}`（如 `CoreTypes`、`MathVector`、`RHICommandList`） -- 若子系统名本身是多词组合（如 `RHI_D3D12`），模块名前缀应使用完整子系统名（如 `RHID3D12Device`） - -### ID 格式 - -| 对象 | ID 格式 | 示例 | -|------|---------|------| -| 需求 | `REQ-XXX` | `REQ-001`、`REQ-002` | -| MVS 方案 | `MVS-XXX` | `MVS-001`、`MVS-002` | -| 缺陷 | `BUG-XXX` | `BUG-001`、`BUG-002` | -| 特性 | `FEAT-XXX` | `FEAT-001`、`FEAT-002` | - ---- - -## 文档一致性检查 - -生成或修改蓝图文档时，需检查： - -1. **驼峰命名规范** — 所有子系统名和模块名必须使用驼峰命名，严禁下划线 -2. **SYSTEM_STRUCTURE 一致性** — `modules[].parent_subsystem` 引用的子系统必须存在 -3. **依赖关系一致性** — `subsystems[].depends_on` 引用的子系统必须存在，无循环依赖 -4. **命名唯一性** — `subsystems[].name` 和 `modules[].name` 在各自数组内唯一 -5. **ID 格式一致性** — 所有 ID 字段遵循统一格式（REQ-XXX、MVS-XXX 等） -6. **provides/depends_on 配对** — 子系统的对外接口最好被依赖方引用 -7. **MVS 与 REQUIREMENTS 关联** — MVS 的 scope 应覆盖对应 REQ 涉及的所有子系统 -8. **YAML 语法正确性** — YAML 代码块可正常解析，无缩进错误、无重复键 - ---- - -## 生成流程 - -> **核心原则：在动手写蓝图文档之前，必须先完整阅读并深刻理解系统源码上下文。** - -1. **阅读源码**：完整阅读目标系统的核心头文件和关键实现，理解设计目的、模块划分、 - 数据流、依赖关系、边界条件。不要只看目录结构就写蓝图。 -2. **识别子系统**：根据功能边界和依赖关系，划分子系统。每个子系统应有明确的职责边界 - 和对外接口。子系统划分不宜过粗（导致职责重叠）也不宜过细（导致过度碎片化）。 -3. **提取模块和接口**：从代码中提取核心模块及其 public API（函数签名、参数、返回值）。 -4. **构建依赖图**：分析子系统间的依赖关系，确保无循环依赖。 -5. **生成 SYSTEM_META**：填写系统元信息。 -6. **生成 SYSTEM_STRUCTURE**：构建 subsystems 和 modules，确保依赖关系准确。 -7. **生成 REQUIREMENTS**：从源码 TODO、BUG 注释、需求文档中提取需求。 -8. **生成 MVS_DEFINITION**：为关键功能生成最小可行方案，指导分阶段实现。 -9. **补充可选章节**：根据需要补充 DATA_MODELS 和 EVOLUTION_PLAN。 -10. **校验输出**：运行所有一致性检查，检查依赖关系和命名一致性。 -11. **输出报告**：列出生成内容、子系统划分理由、缺失信息和发现的问题。 - ---- - -## 使用示例 - -用户输入： -``` -为 XCEngine 生成蓝图文档 -``` - -AI 执行： -1. 扫描 XCEngine 源码目录，分析代码结构和模块划分 -2. 识别核心子系统（Core、Rendering、Physics、Resource、Scripting 等） -3. 提取各子系统的模块和 public API -4. 分析子系统间的依赖关系，构建依赖图 -5. 生成 `blueprint.md` 文件 -6. 运行校验检查 YAML 结构和依赖关系 -7. 输出报告：子系统划分理由、生成内容、缺失信息 +- 这套工作区现在真正有哪些子系统 +- 它们通过什么链路接起来 +- 当前稳定的数据边界在哪里 +- 下一阶段应该在什么约束下继续演进 diff --git a/docs/blueprint.md b/docs/blueprint.md index 190f76af..75e8b73d 100644 --- a/docs/blueprint.md +++ b/docs/blueprint.md @@ -1,5 +1,7 @@ # XCEngine 蓝图 +本文按当前工作树整理，快照时间为 `2026-04-04`。如果源码、测试、`CMakeLists.txt` 或项目布局继续演进，这份蓝图也必须同步更新。 + --- # SYSTEM_META @@ -7,9 +9,12 @@ ```yaml name: XCEngine version: 0.1.0 -type: game-engine -description: "模块化的 C++17 游戏引擎，支持 D3D12 和 OpenGL 双图形后端" -target_runtime: C++17 +type: editor-first-game-engine-workspace +description: "Windows 优先、编辑器优先的模块化 C++17 游戏引擎工作区，当前已经形成 RHI、Rendering、AssetDatabase/Library、Mono Scripting 与 Editor Viewport 的可运行闭环。" +target_runtime: "C++17 + .NET Framework 4.7.2 + Mono" +snapshot_date: 2026-04-04 +primary_platform: Windows 10/11 +workspace_roots: [engine, editor, managed, project, tests] ``` --- @@ -17,636 +22,547 @@ target_runtime: C++17 # SYSTEM_STRUCTURE ```yaml -root: XCEngine +root: XCEngineWorkspace subsystems: - name: Core responsibilities: - - "提供基础类型别名和断言机制" - - "实现引用计数智能指针" - - "提供线程安全的事件发布/订阅系统" - - "提供文件写入 RAII 封装" - provides: [RefCounted, Event, FileWriter, SmartPtr] + - "提供基础类型、事件、Layer/LayerStack、容器、数学和资源路径等通用基础设施。" + - "为上层 Memory、Threading、Resources、Rendering、Scene 和 Editor 提供共享工具。" + provides: [Types, Event, LayerStack, Containers, Math, ResourcePath] depends_on: [] boundary: inputs: [] - outputs: [类型系统] - - - name: Math - responsibilities: - - "实现向量、矩阵、四元数数学运算" - - "提供变换（Transform）层次组合" - - "实现几何基元（平面、球体、盒子、射线、视锥体）" - provides: [Vector, Matrix, Quaternion, Transform, Geometry] - depends_on: [Core] - boundary: - inputs: [Core 类型] - outputs: [数学计算结果] - - - name: Containers - responsibilities: - - "提供动态数组模板" - - "提供字符串处理功能" - - "提供基于开放寻址的哈希表" - provides: [Array, String, HashMap] - depends_on: [Core, Memory] - boundary: - inputs: [Core 类型] - outputs: [容器实例] + outputs: [基础类型, 通用容器, 几何与路径工具] - name: Memory responsibilities: - - "定义内存分配器抽象接口" - - "实现线性分配器（栈式）" - - "实现池分配器（固定大小块）" - - "提供代理分配器（统计追踪）" - - "管理全局内存系统" - provides: [IAllocator, LinearAllocator, PoolAllocator, ProxyAllocator, MemoryManager] + - "提供 Allocator、LinearAllocator、PoolAllocator、ProxyAllocator 和全局 MemoryManager。" + - "为资源缓存、RHI 资源和长期对象生命周期管理提供分配策略。" + provides: [Allocator, LinearAllocator, PoolAllocator, ProxyAllocator, MemoryManager] depends_on: [Core] boundary: inputs: [分配请求] - outputs: [内存块] + outputs: [内存块, 内存统计] - name: Threading responsibilities: - - "封装线程 RAII 管理" - - "提供互斥锁、自旋锁、读写锁" - - "实现任务系统和线程池" - - "支持任务依赖和优先级调度" - provides: [Thread, Mutex, TaskSystem, TaskGroup] - depends_on: [Core, Containers] + - "提供 Thread、Mutex、SpinLock、ReadWriteLock、TaskSystem、TaskGroup。" + - "支撑资源异步加载、后台导入和部分并行测试场景。" + provides: [Thread, Mutex, ReadWriteLock, TaskSystem, TaskGroup] + depends_on: [Core] boundary: - inputs: [任务函数] - outputs: [执行结果] + inputs: [任务函数, 同步请求] + outputs: [调度结果, 同步原语] - name: Debug responsibilities: - - "提供多层级分类日志系统" - - "支持多种日志输出目标（控制台、文件）" - - "实现性能分析器和 Chrome 追踪导出" - provides: [Logger, Profiler, ILogSink] - depends_on: [Core, Containers, Threading] + - "提供 Logger、ILogSink、Profiler、RenderDocCapture 等诊断能力。" + - "为 engine、editor 和 tests 提供统一日志与性能分析入口。" + provides: [Logger, ILogSink, Profiler, RenderDocCapture] + depends_on: [Core, Threading] boundary: - inputs: [日志消息] - outputs: [日志输出] + inputs: [日志消息, profile 样本] + outputs: [控制台输出, 文件输出, profile 数据] + + - name: Input + responsibilities: + - "维护 InputManager、InputModule、InputEvent、InputAxis 和键鼠状态抽象。" + - "为 runtime 与 editor viewport 导航提供统一输入层。" + provides: [InputManager, InputModule, InputEvent, InputAxis] + depends_on: [Core] + boundary: + inputs: [平台输入事件] + outputs: [输入状态, 输入事件流] + + - name: Project + responsibilities: + - "承载 `Project.xcproject`、`Assets/`、`.meta`、`Library/` 的工程数据布局。" + - "作为 editor、resources、managed、scripting 共享的项目根目录边界。" + provides: [ProjectDescriptor, AssetSourceTree, AssetMetaFiles, ProjectLibrary, StartupScene] + depends_on: [] + boundary: + inputs: [用户资源, 用户脚本, 编辑器操作, 构建产物] + outputs: [Project.xcproject, Assets, Library] - name: Resources responsibilities: - - "管理所有游戏资源的生命周期" - - "实现资源加载器框架和多种格式支持" - - "提供 LRU 缓存和内存预算控制" - - "支持异步加载和依赖图管理" - - "管理资源文件系统路径和资源包" - provides: [IResource, ResourceManager, ResourceHandle, AsyncLoader] - depends_on: [Core, Containers, Memory, Threading, Math, Debug] + - "维护 AssetDatabase、AssetImportService、ProjectAssetIndex、ResourceManager 和 ResourceCache。" + - "把 `Assets/ + .meta` 导入为 `Library/SourceAssetDB`、`Library/ArtifactDB`、`Library/Artifacts`。" + - "统一运行时资源查找、Artifact 解析、ResourceHandle 与异步加载。" + provides: [AssetDatabase, AssetImportService, ProjectAssetIndex, ResourceManager, ResourceHandle, AsyncLoader] + depends_on: [Core, Memory, Threading, Debug, Project] boundary: - inputs: [资源路径] - outputs: [资源对象] + inputs: [projectRoot, assetPath, AssetRef, importer settings] + outputs: [IResource, ArtifactRecord, AssetRef, import status] - name: RHI responsibilities: - - "抽象渲染硬件接口，统一不同图形 API" - - "封装 GPU 资源（缓冲区、纹理、着色器）" - - "提供命令列表录制和提交机制" - - "管理描述符堆和管线状态" - provides: [RHIDevice, RHIBuffer, RHITexture, RHIShader, RHICommandList] + - "提供 RHIDevice、RHICommandList、RHISwapChain、RHITexture、RHIBuffer 等抽象接口。" + - "维护 D3D12、OpenGL、Vulkan 三后端及 RHIFactory 选择逻辑。" + - "为 Rendering 和 editor host 提供统一 GPU 资源与提交契约。" + provides: [RHIFactory, RHIDevice, RHICommandList, RHISwapChain, RHITexture, RHIBuffer] + depends_on: [Core, Debug] + boundary: + inputs: [RHIType, 渲染命令, 资源描述] + outputs: [后端设备, GPU 资源, 提交结果] + + - name: Rendering + responsibilities: + - "维护 `SceneRenderer -> CameraRenderer -> RenderPipeline` 正式主链。" + - "提供 RenderSurface、RenderContext、RenderSceneExtractor、RenderResourceCache 和 builtin passes。" + - "支撑 Scene/Game viewport 离屏渲染、ObjectId picking、Outline、InfiniteGrid 和 overlay passes。" + provides: [SceneRenderer, CameraRenderer, RenderPipeline, RenderSurface, RenderContext, BuiltinPasses] + depends_on: [Core, Debug, Resources, RHI, Components, Scene] + boundary: + inputs: [Scene, CameraRenderRequest, RenderSurface] + outputs: [离屏颜色/深度目标, ObjectId, overlay draw results] + + - name: Components + responsibilities: + - "提供 GameObject、Component、ComponentFactoryRegistry 和内建组件集合。" + - "维护 Transform、Camera、Light、Mesh、Audio 等组件级数据。" + provides: [GameObject, Component, TransformComponent, CameraComponent, LightComponent, MeshFilterComponent, MeshRendererComponent, AudioComponents] + depends_on: [Core, Resources, Audio] + boundary: + inputs: [场景编辑操作, 资源引用] + outputs: [组件树, 运行时组件状态] + + - name: Scene + responsibilities: + - "维护 Scene、SceneManager、SceneRuntime、RuntimeLoop 和场景序列化。" + - "负责 `.xc` 场景文档的读写、运行时更新与层级查询。" + provides: [Scene, SceneManager, SceneRuntime, RuntimeLoop] + depends_on: [Core, Components] + boundary: + inputs: [场景文件, 编辑器命令, deltaTime] + outputs: [场景树, 保存后的场景文档, 生命周期事件] + + - name: Scripting + responsibilities: + - "维护 ScriptComponent、ScriptEngine、ScriptFieldStorage、IScriptRuntime 与 MonoScriptRuntime。" + - "加载 `Library/ScriptAssemblies/` 中的 `XCEngine.ScriptCore.dll`、`GameScripts.dll` 和 `mscorlib.dll`。" + - "提供脚本类发现、字段元数据、默认值、override 和运行时字段同步。" + provides: [ScriptComponent, ScriptEngine, ScriptFieldStorage, IScriptRuntime, MonoScriptRuntime] + depends_on: [Core, Components, Scene, Project] + boundary: + inputs: [程序集路径, Scene, ScriptComponent field writes] + outputs: [脚本实例, 字段快照, 生命周期回调] + + - name: Audio + responsibilities: + - "提供 AudioSystem、AudioMixer、IAudioBackend 和 WindowsAudioBackend。" + - "为 AudioSource / AudioListener 组件提供基础音频运行时支持。" + provides: [AudioSystem, AudioMixer, IAudioBackend, WindowsAudioBackend] depends_on: [Core] boundary: - inputs: [渲染命令] - outputs: [GPU 调用] + inputs: [音频配置, 场景音频源] + outputs: [混音结果, 平台音频提交] - - name: RHI_D3D12 + - name: Editor responsibilities: - - "实现 DirectX 12 后端" - - "封装 D3D12 设备和资源" - - "管理描述符堆和根签名" - provides: [D3D12Device, D3D12Buffer, D3D12Texture] - depends_on: [Core, RHI] + - "维护 `XCEditor` 桌面宿主、项目根解析、SceneManager、ProjectManager、Undo/Selection 和各类面板。" + - "通过 `ViewportHostService` 把引擎 Rendering + RHI 离屏结果接入 ImGui。" + - "当前 Scene View 主链按 `SceneViewportChrome -> SceneViewportInteractionFrame -> SceneViewportNavigation -> SceneViewportTransformGizmoCoordinator -> ViewportHostService` 编排。" + provides: [XCEditor, EditorContext, SceneManager, ProjectManager, ViewportHostService, SceneViewportHelpers] + depends_on: [Core, Debug, Input, Project, Resources, Rendering, Scene, Scripting, RHI] boundary: - inputs: [RHI 调用] - outputs: [D3D12 API] + inputs: [用户交互, 项目路径, viewport host window] + outputs: [编辑器 UI, 场景编辑命令, project workflow, script build trigger] - - name: RHI_OpenGL + - name: Managed responsibilities: - - "实现 OpenGL 4.6+ 后端" - - "封装 OpenGL 设备和资源" - - "管理 VAO 和采样器状态" - provides: [OpenGLDevice, OpenGLBuffer, OpenGLTexture] - depends_on: [Core, RHI] + - "编译 `managed/XCEngine.ScriptCore/` 与 `managed/GameScripts/`。" + - "扫描 `project/Assets/**/*.cs`，生成项目脚本程序集。" + - "把产物复制到 `project/Library/ScriptAssemblies/` 和 tests 专用输出目录。" + provides: [ScriptCoreAssembly, GameScriptsAssembly, ProjectGameScriptsAssembly, MonoCorlibCopy] + depends_on: [Project, Scripting] boundary: - inputs: [RHI 调用] - outputs: [OpenGL API] + inputs: [managed C# source files, project C# source files, Mono corlib] + outputs: [XCEngine.ScriptCore.dll, GameScripts.dll, mscorlib.dll] + + - name: Tests + responsibilities: + - "维护 `tests/` 下对 Core、Resources、RHI、Rendering、Editor、Scripting 等主线模块的回归覆盖。" + - "维持 `rhi_all_tests`、`rendering_all_tests`、`editor_tests`、`scripting_tests` 等聚合 target。" + - "验证资源导入、viewport helper 链、脚本程序集输出和 backend 分层边界。" + provides: [CTestTargets, RegressionSpecs, IntegrationScenes] + depends_on: [Core, Memory, Threading, Debug, Input, Project, Resources, RHI, Rendering, Components, Scene, Scripting, Editor, Managed] + boundary: + inputs: [build targets, test assets, project fixtures] + outputs: [测试结果, 回归信号] modules: - - name: CoreTypes + - name: Event parent_subsystem: Core - responsibility: "定义基础类型别名（int8、uint32 等）和断言宏" - public_api: - - fn: Assert - params: - - name: condition - type: bool - - name: message - type: const char* - returns: type: void - - - name: CoreSmartPtr - parent_subsystem: Core - responsibility: "实现引用计数智能指针 Ref 和 UniqueRef" - public_api: - - fn: MakeRef - params: - - name: args - type: Args... - returns: type: Ref - - fn: MakeUnique - params: - - name: args - type: Args... - returns: type: UniqueRef - - - name: CoreEvent - parent_subsystem: Core - responsibility: "提供线程安全的事件发布/订阅系统" + responsibility: "提供线程安全的订阅、退订和事件广播能力。" public_api: - fn: Subscribe params: - name: callback type: std::function - returns: type: uint32 + returns: + type: uint32 - fn: Unsubscribe params: - name: id type: uint32 - returns: type: void + returns: + type: void - fn: Invoke params: - name: args type: Args... - returns: type: void + returns: + type: void - - name: MathVector - parent_subsystem: Math - responsibility: "实现 Vector2、Vector3、Vector4 及其运算" - public_api: - - fn: Dot - params: - - name: a - type: const Vector3& - - name: b - type: const Vector3& - returns: type: float - - fn: Cross - params: - - name: a - type: const Vector3& - - name: b - type: const Vector3& - returns: type: Vector3 - - fn: Normalize - params: - - name: v - type: const Vector3& - returns: type: Vector3 - - fn: Lerp - params: - - name: a - type: const Vector3& - - name: b - type: const Vector3& - - name: t - type: float - returns: type: Vector3 - - - name: MathMatrix - parent_subsystem: Math - responsibility: "实现 Matrix3x3、Matrix4x4 及其运算" - public_api: - - fn: Perspective - params: - - name: fov - type: float - - name: aspect - type: float - - name: near - type: float - - name: far - type: float - returns: type: Matrix4x4 - - fn: LookAt - params: - - name: eye - type: const Vector3& - - name: target - type: const Vector3& - - name: up - type: const Vector3& - returns: type: Matrix4x4 - - fn: Inverse - params: - - name: m - type: const Matrix4x4& - returns: type: Matrix4x4 - - - name: MathQuaternion - parent_subsystem: Math - responsibility: "实现四元数和旋转变换" - public_api: - - fn: FromAxisAngle - params: - - name: axis - type: const Vector3& - - name: angle - type: float - returns: type: Quaternion - - fn: FromEulerAngles - params: - - name: pitch - type: float - - name: yaw - type: float - - name: roll - type: float - returns: type: Quaternion - - fn: Slerp - params: - - name: a - type: const Quaternion& - - name: b - type: const Quaternion& - - name: t - type: float - returns: type: Quaternion - - - name: MathTransform - parent_subsystem: Math - responsibility: "实现位置/旋转/缩放变换层次" - public_api: - - fn: Translate - params: - - name: position - type: const Vector3& - returns: type: Transform& - - fn: Rotate - params: - - name: rotation - type: const Quaternion& - returns: type: Transform& - - fn: Scale - params: - - name: scale - type: const Vector3& - returns: type: Transform& - - fn: ToMatrix - returns: type: Matrix4x4 - - - name: MathGeometry - parent_subsystem: Math - responsibility: "实现几何基元（Plane、Sphere、Box、Ray、Frustum、AABB、OBB）" - public_api: - - fn: Intersects - params: - - name: ray - type: const Ray& - - name: sphere - type: const Sphere& - returns: type: bool - - fn: Contains - params: - - name: frustum - type: const Frustum& - - name: point - type: const Vector3& - returns: type: bool - - - name: ContainersArray - parent_subsystem: Containers - responsibility: "提供模板动态数组" - public_api: - - fn: push - params: - - name: value - type: const T& - returns: type: void - - fn: emplace - params: - - name: args - type: Args... - returns: type: T& - - fn: Size - returns: type: uint32 - - - name: ContainersString - parent_subsystem: Containers - responsibility: "提供字符串处理功能" - public_api: - - fn: Substring - params: - - name: start - type: uint32 - - name: length - type: uint32 - returns: type: String - - fn: Trim - returns: type: String - - fn: Find - params: - - name: str - type: const String& - returns: type: int32 - - - name: ContainersHashMap - parent_subsystem: Containers - responsibility: "提供基于开放寻址的哈希表" - public_api: - - fn: Insert - params: - - name: key - type: const K& - - name: value - type: const V& - returns: type: bool - - fn: Find - params: - - name: key - type: const K& - returns: type: Iterator - - fn: Remove - params: - - name: key - type: const K& - returns: type: bool - - - name: MemoryAllocators - parent_subsystem: Memory - responsibility: "实现线性分配器、池分配器、代理分配器" - public_api: - - fn: Allocate - params: - - name: size - type: size_t - returns: type: void* - - fn: Free - params: - - name: ptr - type: void* - returns: type: void - - fn: Clear - returns: type: void - - - name: MemoryManager - parent_subsystem: Memory - responsibility: "管理全局内存分配器和追踪统计" - public_api: - - fn: Get - returns: type: MemoryManager& - - fn: CreateLinearAllocator - params: - - name: size - type: size_t - returns: type: LinearAllocator - - fn: CreatePoolAllocator - params: - - name: blockSize - type: size_t - - name: blockCount - type: uint32 - returns: type: PoolAllocator - - - name: ThreadingPrimitives - parent_subsystem: Threading - responsibility: "提供线程、互斥锁、自旋锁、读写锁" - public_api: - - fn: Thread - params: - - name: func - type: std::function - returns: type: void - - fn: Lock - returns: type: void - - fn: Unlock - returns: type: void - - - name: ThreadingTaskSystem - parent_subsystem: Threading - responsibility: "实现任务调度和线程池" - public_api: - - fn: Get - returns: type: TaskSystem& - - fn: ParallelFor - params: - - name: begin - type: uint32 - - name: end - type: uint32 - - name: func - type: std::function - returns: type: void - - fn: Submit - params: - - name: task - type: ITask* - returns: type: void - - fn: Wait - returns: type: void - - - name: DebugLogger - parent_subsystem: Debug - responsibility: "提供多层级分类日志系统" - public_api: - - fn: Get - returns: type: Logger& - - fn: Log - params: - - name: category - type: const char* - - name: level - type: LogLevel - - name: message - type: const char* - returns: type: void - - - name: DebugProfiler - parent_subsystem: Debug - responsibility: "实现性能分析器" - public_api: - - fn: Get - returns: type: Profiler& - - fn: BeginSession - params: - - name: name - type: const char* - returns: type: void - - fn: EndSession - returns: type: void - - fn: ExportChromeTracing - params: - - name: path - type: const char* - returns: type: void - - - name: ResourcesIResource + - name: AssetDatabase parent_subsystem: Resources - responsibility: "定义资源基接口" + responsibility: "维护源资产记录、artifact 记录、.meta 生成和按需重导入。" public_api: - - fn: GetType - returns: type: ResourceType - - fn: GetName - returns: type: const String& - - fn: GetPath - returns: type: const String& - - fn: GetGUID - returns: type: const ResourceGUID& + - fn: Initialize + params: + - name: projectRoot + type: const Containers::String& + returns: + type: void + - fn: Refresh + params: [] + returns: + type: MaintenanceStats + - fn: EnsureArtifact + params: + - name: requestPath + type: const Containers::String& + - name: requestedType + type: ResourceType + - name: outAsset + type: ResolvedAsset& + returns: + type: bool + - fn: TryGetAssetRef + params: + - name: requestPath + type: const Containers::String& + - name: resourceType + type: ResourceType + - name: outRef + type: AssetRef& + returns: + type: bool - - name: ResourcesManager + - name: ResourceManager parent_subsystem: Resources - responsibility: "管理资源生命周期、加载、卸载" + responsibility: "负责统一资源加载、缓存、AssetRef 解析、项目资源刷新和 Library 重建入口。" public_api: - - fn: Get - returns: type: ResourceManager& + - fn: Initialize + params: [] + returns: + type: void - fn: Load params: - name: path - type: const String& - returns: type: LoadResult - - fn: LoadAsync - params: - - name: path - type: const String& - - name: callback - type: std::function)> - returns: type: void - - fn: Unload - params: - - name: guid - type: const ResourceGUID& - returns: type: void - - - name: ResourcesLoaders - parent_subsystem: Resources - responsibility: "实现各类资源加载器" - public_api: - - fn: Load - params: - - name: path - type: const String& - returns: type: IResource* - - fn: GetSupportedExtensions - returns: type: Array - - fn: CanLoad - params: - - name: path - type: const String& - returns: type: bool - - - name: ResourcesFileSystem - parent_subsystem: Resources - responsibility: "管理资源路径和资源包" - public_api: - - fn: Get - returns: type: ResourceFileSystem& - - fn: RegisterLoader - params: - - name: loader - type: IResourceLoader* - returns: type: void - - fn: LoadPackage - params: - - name: path - type: const String& - returns: type: bool - - - name: RHIDevice - parent_subsystem: RHI - responsibility: "创建和管理 RHI 设备及资源" - public_api: - - fn: CreateBuffer - params: - - name: desc - type: const RHIBufferDesc& - returns: type: RHIBuffer* - - fn: CreateTexture - params: - - name: desc - type: const RHITextureDesc& - returns: type: RHITexture* - - fn: CreateShader - params: - - name: desc - type: const RHIShaderDesc& - returns: type: RHIShader* - - fn: CreateCommandList - returns: type: RHICommandList* - - fn: GetCapabilities - returns: type: const RHICapabilities& - - - name: RHICommandList - parent_subsystem: RHI - responsibility: "录制和提交图形命令" - public_api: - - fn: Draw - params: - - name: vertexCount - type: uint32 - - name: instanceCount - type: uint32 - returns: type: void - - fn: DrawIndexed - params: - - name: indexCount - type: uint32 - - name: instanceCount - type: uint32 - returns: type: void - - fn: Dispatch - params: - - name: x - type: uint32 - - name: y - type: uint32 - - name: z - type: uint32 - returns: type: void - - fn: SetPipelineState - params: - - name: state - type: RHIPipelineState* - returns: type: void + type: const Containers::String& + - name: settings + type: ImportSettings* + returns: + type: ResourceHandle + - fn: RefreshProjectAssets + params: [] + returns: + type: void + - fn: RebuildProjectAssetCache + params: [] + returns: + type: bool + - fn: GetProjectAssetImportStatus + params: [] + returns: + type: AssetImportService::ImportStatusSnapshot - name: RHIFactory parent_subsystem: RHI - responsibility: "静态工厂创建后端设备" + responsibility: "根据后端类型创建 RHIDevice，实现抽象层到具体后端的选择。" public_api: - fn: CreateRHIDevice params: - name: type - type: RHIDeviceType - returns: type: RHIDevice* - - - name: RHIBuffer - parent_subsystem: RHI - responsibility: "封装 GPU 缓冲区" - public_api: - - fn: Map + type: RHIType + returns: + type: RHIDevice* + - fn: CreateRHIDevice params: - - name: offset - type: size_t - - name: size - type: size_t - returns: type: void* - - fn: Unmap - returns: type: void + - name: typeName + type: const std::string& + returns: + type: RHIDevice* - - name: RHITexture - parent_subsystem: RHI - responsibility: "封装 GPU 纹理" + - name: SceneRenderer + parent_subsystem: Rendering + responsibility: "构建 CameraRenderRequest 并驱动 CameraRenderer / RenderPipeline 完成场景渲染。" public_api: - - fn: GetWidth - returns: type: uint32 - - fn: GetHeight - returns: type: uint32 - - fn: GetFormat - returns: type: PixelFormat + - fn: BuildRenderRequests + params: + - name: scene + type: const Components::Scene& + - name: overrideCamera + type: Components::CameraComponent* + - name: context + type: const RenderContext& + - name: surface + type: const RenderSurface& + returns: + type: std::vector + - fn: Render + params: + - name: requests + type: const std::vector& + returns: + type: bool + + - name: Scene + parent_subsystem: Scene + responsibility: "负责 GameObject 层级管理、场景更新和 `.xc` 文档读写。" + public_api: + - fn: CreateGameObject + params: + - name: name + type: const std::string& + - name: parent + type: GameObject* + returns: + type: GameObject* + - fn: Update + params: + - name: deltaTime + type: float + returns: + type: void + - fn: Save + params: + - name: filePath + type: const std::string& + returns: + type: void + - fn: Load + params: + - name: filePath + type: const std::string& + returns: + type: void + + - name: ScriptEngine + parent_subsystem: Scripting + responsibility: "管理 ScriptComponent 生命周期、程序集类发现、字段读写和运行时同步。" + public_api: + - fn: SetRuntime + params: + - name: runtime + type: IScriptRuntime* + returns: + type: void + - fn: OnRuntimeStart + params: + - name: scene + type: Components::Scene* + returns: + type: void + - fn: TryGetAvailableScriptClasses + params: + - name: outClasses + type: std::vector& + - name: assemblyName + type: const std::string& + returns: + type: bool + - fn: ApplyScriptFieldWrites + params: + - name: component + type: ScriptComponent* + - name: requests + type: const std::vector& + - name: outResults + type: std::vector& + returns: + type: bool + - fn: TryGetScriptFieldModel + params: + - name: component + type: const ScriptComponent* + - name: outModel + type: ScriptFieldModel& + returns: + type: bool + + - name: ScriptFieldStorage + parent_subsystem: Scripting + responsibility: "保存脚本字段 override，并提供字符串序列化 / 反序列化。" + public_api: + - fn: SetFieldValue + params: + - name: fieldName + type: const std::string& + - name: type + type: ScriptFieldType + - name: value + type: const ScriptFieldValue& + returns: + type: bool + - fn: Remove + params: + - name: fieldName + type: const std::string& + returns: + type: bool + - fn: SerializeToString + params: [] + returns: + type: std::string + - fn: DeserializeFromString + params: + - name: data + type: const std::string& + returns: + type: void + + - name: ISceneManager + parent_subsystem: Editor + responsibility: "为 editor 提供场景创建、加载、保存、脏标记、复制粘贴与 snapshot 恢复接口。" + public_api: + - fn: LoadScene + params: + - name: filePath + type: const std::string& + returns: + type: bool + - fn: SaveSceneAs + params: + - name: filePath + type: const std::string& + returns: + type: bool + - fn: GetScene + params: [] + returns: + type: Components::Scene* + - fn: CaptureSceneSnapshot + params: [] + returns: + type: SceneSnapshot + + - name: SceneViewportChrome + parent_subsystem: Editor + responsibility: "负责 Scene View 顶栏工具条、工具切换 overlay 和对应命令构建。" + public_api: + - fn: RenderSceneViewportTopBar + params: + - name: pivotMode + type: SceneViewportPivotMode& + - name: transformSpaceMode + type: SceneViewportTransformSpaceMode& + returns: + type: void + - fn: RenderSceneViewportToolOverlay + params: + - name: content + type: const ViewportPanelContentResult& + - name: activeTool + type: SceneViewportToolMode + returns: + type: SceneViewportToolOverlayResult + - fn: BuildSceneViewportToolCommand + params: + - name: overlayResult + type: const SceneViewportToolOverlayResult& + - name: shortcutAction + type: const SceneViewportToolShortcutAction& + returns: + type: SceneViewportToolCommand + + - name: SceneViewportInteractionFrame + parent_subsystem: Editor + responsibility: "整合 viewport frame geometry、overlay 数据、gizmo frame 和 presentation 刷新。" + public_api: + - fn: BuildSceneViewportToolState + params: + - name: toolMode + type: SceneViewportToolMode + - name: pivotMode + type: SceneViewportPivotMode + - name: transformSpaceMode + type: SceneViewportTransformSpaceMode + returns: + type: SceneViewportToolState + - fn: BuildSceneViewportFrameGeometry + params: + - name: viewportSize + type: const ImVec2& + - name: viewportMin + type: const ImVec2& + - name: absoluteMousePosition + type: const ImVec2& + returns: + type: SceneViewportFrameGeometry + - fn: BuildSceneViewportInteractionFrameState + params: + - name: context + type: IEditorContext& + - name: viewportHostService + type: IViewportHostService& + - name: hasInteractiveViewport + type: bool + - name: geometry + type: const SceneViewportFrameGeometry& + - name: gizmoFrameOptions + type: const SceneViewportTransformGizmoFrameOptions& + - name: moveGizmo + type: SceneViewportMoveGizmo& + - name: rotateGizmo + type: SceneViewportRotateGizmo& + - name: scaleGizmo + type: SceneViewportScaleGizmo& + - name: emptyOverlayFrameData + type: const SceneViewportOverlayFrameData& + returns: + type: SceneViewportInteractionFrameState + + - name: EditorScriptAssemblyBuilder + parent_subsystem: Editor + responsibility: "从 editor 侧触发项目脚本程序集重建。" + public_api: + - fn: RebuildProjectAssemblies + params: + - name: projectPath + type: const std::string& + returns: + type: EditorScriptAssemblyBuildResult + + - name: ProjectFileUtils + parent_subsystem: Editor + responsibility: "读写 `Project.xcproject`，并在 project root 与相对路径之间做转换。" + public_api: + - fn: SaveProjectDescriptor + params: + - name: projectRoot + type: const std::string& + - name: descriptor + type: const ProjectDescriptor& + returns: + type: bool + - fn: LoadProjectDescriptor + params: + - name: projectRoot + type: const std::string& + returns: + type: std::optional + - fn: ResolveProjectPath + params: + - name: projectRoot + type: const std::string& + - name: pathValue + type: const std::string& + returns: + type: std::string ``` --- @@ -654,91 +570,122 @@ modules: # EVOLUTION_MODE ```yaml -mode: build -description: "XCEngine 处于早期构建阶段，核心基础设施正在逐步完善" +mode: evolve +description: "当前工作重点是在已经成型的 editor-first 主链上继续收口，而不是重新设计另一套全新架构。" context: | - XCEngine 是一个正在开发中的游戏引擎项目，当前版本 0.1.0 专注于建立核心基础设施。 - 核心模块（Core、Math、Containers、Memory）已基本完成，提供了游戏引擎所需的基础构建块。 - - 渲染系统（RHI）已完成双后端支持（D3D12 和 OpenGL），但高级渲染特性（如光线追踪、 - 网格着色器）尚未实现。 - - 资源管理系统（Resources）已具备完整的加载框架，支持异步加载、缓存和依赖管理， - 但仅支持基础格式（纹理、网格、着色器）。 - - 缺少的子系统：物理系统、脚本系统、实体组件系统（ECS）、音频系统、UI 系统。 - 这些将在后续迭代中逐步添加。 + XCEngine 已经不再是“若干独立 sample + 早期渲染实验”的状态。 + 当前真实主线已经包含： + - D3D12 / OpenGL / Vulkan 三后端 RHI + - SceneRenderer -> CameraRenderer -> RenderPipeline 渲染链 + - Assets/ + .meta + Library/ 的项目与资源导入链 + - Mono C# scripting runtime 与 ScriptComponent 字段编辑链 + - 通过 Rendering + RHI 接入 ImGui 的 editor Scene/Game viewport + + 当前演进不是从零构建 build，也不是只做零碎 bugfix maintain，而是： + - 把旧时期残留入口继续收口到当前正式链路 + - 把 project、managed、editor、tests 的边界写实化 + - 在不破坏现有 workflow 的前提下推进 backend parity、viewport helper 正式化、脚本字段持久化和 Library 生命周期工具化 + + 仍需明确的现实约束： + - editor 目前仍是 D3D12 宿主应用 + - Vulkan SDK 当前是配置阶段硬依赖 + - Mono scripting 需要额外外部依赖，但相关代码与构建链已经落地 + - 部分 builtin render pass 仍存在 D3D12-first 假设，需要逐步跨后端收口 ``` --- # REQUIREMENTS +```yaml - id: REQ-001 - title: "核心数学库完善" - description: "扩展数学库以支持 SIMD 优化，提供更高效的向量/矩阵运算" + title: "Editor 必须能加载工程并打开启动场景" + description: "桌面编辑器必须能够识别 project root、读取 `Project.xcproject`，并加载 `startup_scene` 指向的 `.xc` 场景。" source: user - type: non-functional + type: functional acceptance_criteria: - - "向量运算支持 SSE/AVX 加速" - - "矩阵运算支持 SIMD 优化" - - "性能基准测试显示 2x 以上的性能提升" - priority: P1 + - "`editor/bin//XCEngine.exe` 默认可把仓库内 `project/` 识别为工程根。" + - "支持通过 `--project ` 覆盖工程根。" + - "`startup_scene=Assets/Scenes/Main.xc` 这类相对路径可被 editor 正确解析并载入。" + priority: P0 - id: REQ-002 - title: "资源系统扩展" - description: "增加更多资源格式支持，包括音频、动画、骨骼网格" - source: user + title: "项目资源必须通过 Assets/.meta/Library 闭环管理" + description: "资源系统必须维护 `.meta`、源资产数据库、artifact 数据库和 artifact 输出目录，而不是只做裸路径加载。" + source: constraint type: functional acceptance_criteria: - - "支持 WAV 音频加载" - - "支持 glTF 格式模型导入" - - "支持骨骼动画数据" - priority: P1 + - "`AssetDatabase` 能扫描 `Assets/` 并为缺失资源生成 `.meta`。" + - "工程目录下存在 `Library/SourceAssetDB/assets.db` 与 `Library/ArtifactDB/artifacts.db` 两套持久化记录。" + - "`ResourceManager` 能通过路径或 `AssetRef` 解析 artifact 并触发必要的重导入。" + priority: P0 - id: REQ-003 - title: "异步任务系统增强" - description: "支持任务优先级、任务亲和性、任务追踪" - source: user + title: "Viewport 渲染必须走引擎 Rendering + RHI 主链" + description: "Scene/Game viewport 不能退化成 editor 私有渲染器，必须继续使用离屏 RenderSurface、CameraRenderRequest 和 builtin passes。" + source: constraint type: functional acceptance_criteria: - - "支持高/中/低三档任务优先级" - - "支持将任务分配到特定线程" - - "提供任务执行状态查询接口" - priority: P2 + - "Scene/Game viewport 能从引擎离屏颜色目标接入 ImGui。" + - "`ObjectId` picking、outline、grid 和 overlay pass 仍通过 Rendering 合约接入。" + - "Scene View helper 链保持 `Chrome -> InteractionFrame -> Navigation -> TransformGizmoCoordinator -> ViewportHostService` 口径。" + priority: P0 - id: REQ-004 - title: "内存追踪和泄漏检测" - description: "增强内存管理器，提供分配追踪和泄漏检测功能" + title: "脚本程序集必须能从 project/Library/ScriptAssemblies 被发现和加载" + description: "脚本系统必须同时支持 ScriptCore、示例 GameScripts 和项目 `Assets/**/*.cs` 编译结果。" source: user - type: non-functional + type: functional acceptance_criteria: - - "记录每次分配的调用栈" - - "检测并报告内存泄漏" - - "生成内存使用报告" - priority: P1 + - "`xcengine_managed_assemblies` 能生成 `XCEngine.ScriptCore.dll`、`GameScripts.dll` 和 `mscorlib.dll`。" + - "`xcengine_project_managed_assemblies` 能把项目程序集输出到 `project/Library/ScriptAssemblies/`。" + - "`ScriptEngine` / `MonoScriptRuntime` 能发现脚本类并让 Inspector 读取字段元数据。" + priority: P0 - id: REQ-005 - title: "渲染管线扩展" - description: "增加 Compute Shader 支持、GPU 驱动的剔除、延迟渲染管线" + title: "场景与组件必须可编辑、可保存、可恢复" + description: "Scene、GameObject 和内建组件必须支持编辑器中的创建、层级调整、复制粘贴、保存与重新加载。" source: user type: functional acceptance_criteria: - - "支持 Compute Shader 执行" - - "实现视锥体剔除" - - "提供延迟渲染模板" - priority: P2 + - "`ISceneManager` 提供 New/Load/Save/SaveAs、Copy/Paste/Duplicate、snapshot 恢复。" + - "`.xc` 场景文件能保留 GameObject 层级、Transform、Mesh、Light、ScriptComponent 等数据。" + - "重新载入场景后，Inspector 与 viewport 仍能解析对应实体和组件。" + priority: P0 - id: REQ-006 - title: "日志系统国际化" - description: "支持多语言日志输出" - source: user - type: functional + title: "RHI 抽象层必须维持三后端并保持测试分层" + description: "公共 RHI 抽象与 D3D12/OpenGL/Vulkan 后端必须继续分层，不能通过测试反向污染抽象层。" + source: constraint + type: non-functional acceptance_criteria: - - "支持日志消息参数化" - - "支持格式化字符串" - - "提供本地化接口" - priority: P2 + - "`RHIFactory` 继续支持 D3D12、OpenGL、Vulkan 三后端创建。" + - "`tests/RHI/unit/` 与 `tests/RHI/integration/` 不直接依赖后端私有实现。" + - "`rhi_all_tests` 仍可作为统一聚合入口。" + priority: P1 + +- id: REQ-007 + title: "主线测试 target 必须持续可用" + description: "工程需要保留跨模块聚合 target，用于快速验证 Rendering、Editor、Scripting 和 RHI 主线。" + source: constraint + type: non-functional + acceptance_criteria: + - "`rendering_all_tests`、`rendering_phase_regression`、`editor_tests`、`scripting_tests`、`rhi_all_tests` 仍存在。" + - "`tests/Editor/` 覆盖 Scene View helper 新链路。" + - "资源导入和项目脚本程序集输出存在对应 tests。" + priority: P1 + +- id: REQ-008 + title: "构建入口必须真实反映当前外部依赖门槛" + description: "文档和蓝图必须明确 Vulkan、Mono、ImGui、googletest 等依赖的实际门槛，不能继续保留旧时期的过时描述。" + source: constraint + type: non-functional + acceptance_criteria: + - "配置阶段明确 Vulkan SDK 是当前硬依赖。" + - "Mono scripting 可通过 `XCENGINE_ENABLE_MONO_SCRIPTING=OFF` 关闭。" + - "首次配置 editor/tests 时需要考虑 `FetchContent` 的 ImGui 与 googletest。" + priority: P1 +``` --- @@ -747,97 +694,136 @@ context: | ```yaml mvs_solutions: - id: MVS-001 - name: "SIMD 数学优化" - goal: "为数学库添加 SIMD 加速，提升渲染和物理计算性能" + name: "Editor 宿主与 Scene View 渲染闭环" + goal: "确保 editor 能以 D3D12 宿主身份启动，并通过 Rendering + RHI 离屏结果驱动 Scene/Game viewport。" verification_criteria: - - "矩阵乘法性能提升 2x 以上" - - "向量点积/叉积性能提升 2x 以上" - - "不破坏现有 API 兼容性" + - "构建 `XCEditor` 后可打开 `project/Assets/Scenes/Main.xc`。" + - "Scene/Game viewport 能显示离屏渲染结果，而不是空白宿主窗口。" + - "`tests/Editor/` 中与 viewport helper 链相关的测试保持通过。" scope: - - subsystem: Math - components: [Vector, Matrix, Quaternion] - - external: [SSE4.2, AVX2] + - subsystem: Editor + components: [Application, ViewportHostService, SceneViewPanel, SceneViewportChrome, SceneViewportInteractionFrame] + - subsystem: Rendering + components: [SceneRenderer, CameraRenderer, RenderPipeline, RenderSurface] + - subsystem: RHI + components: [RHIFactory, RHIDevice, RHITexture] + - external: [Win32, ImGui, D3D12] code_structure: - - file: "engine/include/XCEngine/Math/Vector3.inl" - purpose: "SIMD 向量实现" + - file: editor/src/Application.cpp + purpose: "初始化 editor 宿主、project root、script runtime status 和 application 生命周期。" contains: - - "SSE/AVX 向量运算内联函数" - - "跨平台 SIMD 选择宏" - standalone: true - - file: "engine/include/XCEngine/Math/Matrix4x4.inl" - purpose: "SIMD 矩阵实现" + - "project root 解析" + - "Library/ScriptAssemblies wiring" + - "editor runtime lifecycle" + standalone: false + - file: editor/src/Viewport/ViewportHostService.h + purpose: "把 Scene View 与引擎 Rendering/RHI 输出连接起来。" contains: - - "SSE/AVX 矩阵乘法" - - "SIMD 矩阵求逆" - standalone: true + - "offscreen render target ownership" + - "overlay data access" + - "viewport render flow" + standalone: false + - file: engine/include/XCEngine/Rendering/SceneRenderer.h + purpose: "构建并执行场景渲染请求。" + contains: + - "CameraRenderRequest build" + - "render dispatch" + standalone: false integration_plan: - - step: "定义 SIMD 抽象层选择宏（XC_USE_SSE/AVX）" - - step: "在 Vector3.h 中引入条件编译的 SIMD 实现" - - step: "在 Matrix4x4.h 中引入 SIMD 乘法实现" - - step: "添加性能基准测试" - status: pending + - step: "由 editor 解析工程根并创建 viewport host。" + - step: "由 Rendering 根据当前 scene 与 camera 构建 render requests。" + - step: "把离屏颜色目标交回 editor，并由 ImGui 面板展示。" + status: completed - id: MVS-002 - name: "音频资源加载器" - goal: "实现 WAV 格式音频加载，为后续音频系统打基础" + name: "Assets/.meta/Library 资源导入与运行时加载闭环" + goal: "确保工程资源从 `Assets/` 到 `Library/Artifacts/` 的导入、记录和运行时解析已经形成统一链路。" verification_criteria: - - "成功加载标准 WAV 文件" - - "正确解析音频参数（采样率、声道、位深）" - - "提供 AudioClip 资源对象" + - "首次扫描工程时能补 `.meta` 并建立 `assets.db` / `artifacts.db`。" + - "`ResourceManager` 能按路径和 `AssetRef` 成功定位 artifact。" + - "材质、网格、shader 等资源的 artifact 重导入路径保持一致。" scope: + - subsystem: Project + components: [Assets, AssetMetaFiles, ProjectLibrary] - subsystem: Resources - components: [AudioLoader, AudioClip] - - external: [stb_vorbis, libwav] + components: [AssetDatabase, AssetImportService, ProjectAssetIndex, ResourceManager] + - subsystem: Tests + components: [asset_tests, material_tests, mesh_tests, shader_tests, texture_tests] code_structure: - - file: "engine/include/XCEngine/Resources/AudioClip.h" - purpose: "音频数据资源" + - file: engine/include/XCEngine/Core/Asset/AssetDatabase.h + purpose: "定义源资产记录、artifact 记录和导入维护接口。" contains: - - "AudioClip 类定义" - - "音频格式枚举" - standalone: true - - file: "engine/src/Resources/AudioLoader.cpp" - purpose: "WAV 加载器实现" + - "SourceAssetRecord" + - "ArtifactRecord" + - "EnsureArtifact / Refresh" + standalone: false + - file: engine/include/XCEngine/Core/Asset/ResourceManager.h + purpose: "统一运行时加载、项目资源刷新和 Library 重建入口。" contains: - - "WAV 文件解析" - - "音频数据解码" + - "Load / LoadAsync" + - "RefreshProjectAssets" + - "RebuildProjectAssetCache" + standalone: false + - file: project/Library/ + purpose: "承载 SourceAssetDB、ArtifactDB、Artifacts、ScriptAssemblies 等工程级缓存。" + contains: + - "SourceAssetDB/assets.db" + - "ArtifactDB/artifacts.db" + - "Artifacts//" standalone: false integration_plan: - - step: "创建 AudioClip 资源类" - - step: "实现 WAV 解析器" - - step: "注册 AudioLoader 到 ResourceManager" - - step: "添加单元测试" - status: pending + - step: "扫描 `Assets/` 并生成缺失 `.meta`。" + - step: "写入源资产与 artifact 数据库。" + - step: "通过 `ResourceManager` 暴露统一的运行时解析入口。" + status: completed - id: MVS-003 - name: "内存泄漏检测器" - goal: "为 Memory 模块添加分配追踪和泄漏报告功能" + name: "Mono 脚本程序集与 ScriptComponent 闭环" + goal: "确保 C# API、示例脚本和项目脚本可构建、可发现、可在 Inspector 与运行时之间同步字段。" verification_criteria: - - "记录所有分配操作和调用栈" - - "在程序结束时输出泄漏报告" - - "支持泄漏检测白名单" + - "`xcengine_managed_assemblies` 与 `xcengine_project_managed_assemblies` 产物齐全。" + - "`ScriptEngine` 能发现可用脚本类并生成字段模型。" + - "Inspector 中对 ScriptComponent 字段的编辑能写回存储并在运行时同步。" scope: - - subsystem: Memory - components: [AllocationTracker, MemoryReport] - - external: [DbgHelp.dll, walkmacros] + - subsystem: Managed + components: [XCEngine.ScriptCore, GameScripts, project asset assemblies] + - subsystem: Scripting + components: [ScriptEngine, ScriptFieldStorage, MonoScriptRuntime, ScriptComponent] + - subsystem: Editor + components: [EditorScriptAssemblyBuilder, ScriptComponentEditor] + - external: [dotnet, Mono] code_structure: - - file: "engine/include/XCEngine/Memory/AllocationTracker.h" - purpose: "分配追踪器" + - file: managed/CMakeLists.txt + purpose: "定义 ScriptCore、示例脚本、项目脚本与 tests 专用程序集输出。" contains: - - "AllocationTracker 单例" - - "调用栈记录器" - standalone: true - - file: "engine/src/Memory/AllocationTracker.cpp" - purpose: "追踪器实现" + - "xcengine_managed_assemblies" + - "xcengine_project_managed_assemblies" + - "xcengine_test_project_managed_assemblies" + standalone: false + - file: engine/include/XCEngine/Scripting/ScriptEngine.h + purpose: "管理脚本生命周期、脚本类发现和字段同步。" contains: - - "DbgHelp 调用栈捕获" - - "泄漏检测算法" + - "TryGetAvailableScriptClasses" + - "ApplyScriptFieldWrites" + - "TryGetScriptFieldModel" + standalone: false + - file: editor/src/Scripting/EditorScriptAssemblyBuilder.h + purpose: "从 editor 触发项目脚本程序集重建。" + contains: + - "RebuildProjectAssemblies" + standalone: false + - file: project/Library/ScriptAssemblies/ + purpose: "承载 editor 与 runtime 实际加载的程序集目录。" + contains: + - "XCEngine.ScriptCore.dll" + - "GameScripts.dll" + - "mscorlib.dll" standalone: false integration_plan: - - step: "创建 AllocationTracker 类" - - step: "修改 ProxyAllocator 集成追踪器" - - step: "实现泄漏报告生成器" - - step: "在程序退出时自动输出报告" - status: pending + - step: "先构建 ScriptCore 与示例脚本程序集。" + - step: "扫描 `project/Assets/**/*.cs` 并生成项目脚本程序集。" + - step: "由 editor/runtime 从 `Library/ScriptAssemblies/` 装载程序集并驱动 ScriptComponent。" + status: completed ``` --- @@ -845,104 +831,192 @@ mvs_solutions: # DATA_MODELS ```yaml -- name: ResourceHandle - description: "类型安全的资源智能指针，自动引用计数" +- name: ProjectDescriptor + description: "`Project.xcproject` 的键值对格式工程描述。" fields: - - name: m_resource - type: T* - default: nullptr - constraints: optional - - name: m_refCount - type: uint32* - default: nullptr - constraints: optional - -- name: ResourceGUID - description: "资源的全局唯一标识符，由路径哈希生成" - fields: - - name: m_hash - type: uint64 - default: 0 + - name: version + type: int + default: 1 + constraints: required + - name: name + type: string + default: project root folder name + constraints: required + - name: startup_scene + type: string + default: Assets/Scenes/Main.xc constraints: required -- name: LoadResult - description: "资源加载结果" +- name: SceneDocument + description: "`.xc` 场景文件；文件头记录 scene 名称和 active 状态，随后以 `gameobject_begin/end` 块序列化实体及组件。" fields: - - name: success + - name: scene + type: string + default: Untitled Scene + constraints: required + - name: active + type: bool + default: true + constraints: required + - name: gameObjects + type: list + default: [] + constraints: required + +- name: AssetMetaFile + description: "与每个工程资源并存的 `.meta` 文件，保存 guid 与 importer 信息。" + fields: + - name: fileFormatVersion + type: int + default: 1 + constraints: required + - name: guid + type: AssetGUID + default: generated + constraints: required + - name: folderAsset type: bool default: false constraints: required - - name: resource - type: IResource* - default: nullptr - constraints: optional - - name: errorMessage - type: String + - name: importer + type: string + default: DefaultImporter + constraints: required + - name: importerVersion + type: int + default: 5 + constraints: required + +- name: SourceAssetRecord + description: "`AssetDatabase` 中对源资产的持久化记录，对应 `Library/SourceAssetDB/assets.db`。" + fields: + - name: guid + type: AssetGUID + default: generated + constraints: required + - name: relativePath + type: string + default: "" + constraints: required + - name: metaPath + type: string + default: "" + constraints: required + - name: isFolder + type: bool + default: false + constraints: required + - name: importerName + type: string + default: DefaultImporter + constraints: required + - name: importerVersion + type: uint32 + default: 5 + constraints: required + - name: metaHash + type: string + default: "" + constraints: required + - name: sourceHash + type: string + default: "" + constraints: required + - name: lastKnownArtifactKey + type: string default: "" constraints: optional -- name: RHICapabilities - description: "GPU 硬件能力查询" +- name: ArtifactRecord + description: "`AssetDatabase` 对 artifact 的持久化记录，对应 `Library/ArtifactDB/artifacts.db`。" fields: - - name: raytracing - type: bool - default: false - constraints: optional - - name: meshShaders - type: bool - default: false - constraints: optional - - name: tessellation - type: bool - default: false - constraints: optional - - name: maxTextureSize + - name: artifactKey + type: string + default: "" + constraints: required + - name: assetGuid + type: AssetGUID + default: generated + constraints: required + - name: importerName + type: string + default: "" + constraints: required + - name: importerVersion type: uint32 - default: 4096 + default: 0 + constraints: required + - name: resourceType + type: ResourceType + default: Unknown + constraints: required + - name: artifactDirectory + type: string + default: "" + constraints: required + - name: mainArtifactPath + type: string + default: "" + constraints: required + - name: dependencies + type: list + default: [] constraints: optional -- name: Transform - description: "位置、旋转、缩放的三维变换" +- name: ScriptFieldStorageModel + description: "`ScriptFieldStorage` 的字段 override 存储模型，可序列化为字符串并挂在 ScriptComponent 上。" fields: - - name: m_position - type: Vector3 - default: (0,0,0) + - name: fields + type: map + default: {} constraints: required - - name: m_rotation - type: Quaternion - default: identity + - name: StoredScriptField.type + type: ScriptFieldType + default: None constraints: required - - name: m_scale - type: Vector3 - default: (1,1,1) + - name: StoredScriptField.value + type: ScriptFieldValue + default: null constraints: required -- name: Frustum - description: "视锥体，用于裁剪检测" +- name: ScriptAssemblySet + description: "`project/Library/ScriptAssemblies/` 中 editor/runtime 解析的一组程序集。" fields: - - name: m_planes - type: Array - default: [] + - name: outputDirectory + type: path + default: project/Library/ScriptAssemblies constraints: required - - name: m_corners - type: Array - default: [] + - name: coreAssembly + type: path + default: XCEngine.ScriptCore.dll + constraints: required + - name: gameAssembly + type: path + default: GameScripts.dll + constraints: required + - name: corlib + type: path + default: mscorlib.dll constraints: required -- name: IResource - description: "所有资源的基接口" +- name: MaterialArtifactHeader + description: "材质 artifact 文件头，对应 `XCMAT02` 和 schema v2。" fields: - - name: m_type - type: ResourceType + - name: magic + type: char[8] + default: XCMAT02 constraints: required - - name: m_name - type: String + - name: schemaVersion + type: uint32 + default: 2 constraints: required - - name: m_path - type: String + - name: renderQueue + type: int32 + default: Geometry constraints: required - - name: m_guid - type: ResourceGUID + - name: textureBindingCount + type: uint32 + default: 0 constraints: required ``` @@ -953,68 +1027,70 @@ mvs_solutions: ```yaml fix_plan: - issue_id: BUG-001 - description: "LinearAllocator Clear 后重新分配时可能返回重叠内存" - root_cause: "Clear 仅重置指针，未清理旧内存映射" + description: "工作树中的 `project/Library/ScriptAssemblies/` 快照可能落后于目标构建产物，容易让 editor 脚本类发现与真实构建状态脱节。" + root_cause: "脚本程序集同时存在 managed 输出、project 输出和 tests 专用输出三处目录，单看仓库快照容易误判。" minimal_change: - - file: "engine/src/Memory/LinearAllocator.cpp" - verification: "连续 Clear 和分配，检查内存区域不重叠" - + - file: managed/CMakeLists.txt + - file: editor/src/Scripting/EditorScriptAssemblyBuilder.cpp + - file: tests/Scripting/test_project_script_assembly.cpp + verification: "执行 `cmake --build build --config Debug --target xcengine_project_managed_assemblies scripting_tests`，确认 editor 与 tests 都从正确输出目录装载程序集。" + - issue_id: BUG-002 - description: "Event 在多线程同时订阅/取消订阅时存在竞态条件" - root_cause: "订阅列表操作未加锁保护" + description: "Scene View 新交互如果绕过 helper 链直接写回旧 world overlay 路径，会导致实现和 `tests/Editor/` 的行为漂移。" + root_cause: "旧入口仍可访问，容易跳过 `SceneViewportChrome -> SceneViewportInteractionFrame -> SceneViewportNavigation -> SceneViewportTransformGizmoCoordinator` 的新编排。" minimal_change: - - file: "engine/include/XCEngine/Core/Event.h" - verification: "压力测试多线程订阅场景，无崩溃和数据错误" + - file: editor/src/Viewport/SceneViewportChrome.h + - file: editor/src/Viewport/SceneViewportInteractionFrame.h + - file: editor/src/panels/SceneViewPanel.cpp + - file: tests/Editor/test_scene_viewport_chrome.cpp + verification: "执行 `cmake --build build --config Debug --target editor_tests`，确认 helper 链相关测试继续通过。" refactor_plan: - - target: "统一内存分配接口" + - target: "继续把 editor 侧 viewport 行为收口到 Rendering overlay pass 与 helper 链" constraints: - - "保持向后兼容" - - "不引入运行时开销" + - "不要把新逻辑重新堆回 `SceneViewPanel.cpp` 或 panel 层临时拼的 immediate draw 路径。" + - "保持 `tests/Editor/` 对 helper 的独立覆盖。" + - "Editor 仍然是宿主层，渲染问题优先回到 Rendering / RHI contract 排查。" steps: - - "提取 IAllocator 接口的最小子集" - - "将 MakeRef/MakeUnique 重构为使用分配器参数" - - "添加便捷宏 XE_NEW/T_XE_DELETE" + - "优先扩展 `SceneViewportInteractionFrame`、`SceneViewportNavigation`、`SceneViewportTransformGizmoCoordinator`。" + - "世界空间 overlay 优先经 `CameraRenderRequest::overlayPasses` 和 `SceneViewportEditorOverlayPass` 接入。" + - "helper 链变化时同步维护 editor README、AGENT 和 API 页面。" - - target: "RHI 资源状态转换自动化" + - target: "统一 `Assets/.meta/Library` 导入链与运行时解析链的契约" constraints: - - "保持性能" - - "兼容现有渲染器" + - "不要把 `project/Library/` 当作无关垃圾目录。" + - "不要在局部代码路径里绕开 `AssetDatabase` / `ProjectAssetIndex` / `ResourceManager`。" + - "artifact schema 变更必须同步 tests 与文档。" steps: - - "引入资源状态跟踪器" - - "自动插入转换 barriers" - - "暴露手动控制接口" + - "继续把资产定位、artifact 生成、AssetRef 解析集中在 `AssetDatabase`、`ProjectAssetIndex`、`ResourceManager`。" + - "保持 `Project.xcproject`、`.meta`、`assets.db`、`artifacts.db` 和 `Artifacts/` 之间的一致性。" + - "对材质、网格、shader artifact 的契约修改补齐 `tests/Resources/`。" feature_plan: - feature_id: FEAT-001 - name: "实体组件系统（ECS）" - addition: "实现高性能 ECS 架构，支持 archetypes 和 query" - integration_point: "Engine 层，位于 Resources 和 Gameplay 之间" + name: "Builtin pass 跨后端收口" + addition: "逐步降低 Rendering 内置 pass 对 D3D12 的硬编码假设，使离屏渲染、ObjectId 和 outline contract 更接近真正的 backend-agnostic。" + integration_point: "engine/src/Rendering/Passes/, engine/src/RHI/, tests/Rendering/, tests/RHI/" steps: - - "定义 Component、Entity、World 接口" - - "实现 Archetype 存储" - - "实现 Query 系统" - - "集成到引擎主循环" + - "梳理 `BuiltinInfiniteGridPass`、`BuiltinObjectIdPass`、`BuiltinObjectIdOutlinePass` 的 backend gating。" + - "把必须留在 D3D12-host 层的逻辑与真正属于 Rendering 的逻辑继续拆开。" + - "为跨后端 contract 补齐单测和场景回归。" - feature_id: FEAT-002 - name: "物理子系统" - addition: "集成物理引擎，支持刚体、碰撞体" - integration_point: "Core 层下方，独立子系统" + name: "脚本字段持久化与编辑器回写深化" + addition: "继续增强 `ScriptFieldStorage`、Inspector 字段编辑与运行时字段同步的一致性。" + integration_point: "engine/src/Scripting/, editor/src/ComponentEditors/, project/Assets/Scripts/, tests/Scripting/, tests/Editor/" steps: - - "评估物理引擎集成（Bullet/PhysX）" - - "封装物理世界接口" - - "实现碰撞检测和响应" - - "集成到渲染管线" + - "扩展字段类型覆盖与默认值解析。" + - "校验默认值、stored override 与 runtime 值三态同步。" + - "保持 scene 保存、重新载入和 play mode 之间的字段一致性。" - feature_id: FEAT-003 - name: "脚本系统" - addition: "支持 Lua 脚本和自定义脚本语言绑定" - integration_point: "Core 层上方，独立子系统" + name: "Project Library 生命周期工具化" + addition: "在不破坏现有 workflow 的前提下增强 Library 清理、重建与状态可视化。" + integration_point: "engine/include/XCEngine/Core/Asset/ResourceManager.h, editor/src/Managers/ProjectManager.cpp, editor/src/Application.cpp" steps: - - "集成 Lua 虚拟机" - - "绑定核心引擎 API" - - "实现脚本组件" - - "支持热重载" + - "把清理与重建入口继续收束到 `ResourceManager` 和 editor commands。" + - "为 `SourceAssetDB`、`ArtifactDB`、`Artifacts`、`ScriptAssemblies` 提供更明确的状态反馈。" + - "补对应 tests 和用户文档，避免再次把 `Library/` 误写成可忽略目录。" ``` - ---- diff --git a/docs/issues/Editor模块_Console面板错误绑定fallback sink导致运行时日志不显示4.3.md b/docs/issues/Editor模块_Console面板错误绑定fallback sink导致运行时日志不显示4.3.md new file mode 100644 index 00000000..b1a6ad55 --- /dev/null +++ b/docs/issues/Editor模块_Console面板错误绑定fallback sink导致运行时日志不显示4.3.md @@ -0,0 +1,179 @@ +# Editor模块 Console面板错误绑定 fallback sink 导致运行时日志不显示 + +## 1. 问题定义 + +当前 editor 底部 `Console` 面板在 PlayMode 下看不到 C# `Debug.Log` 输出。 + +已确认： + +1. `Tick` 正在正常推进，脚本字段计数持续变化 +2. `Debug.Log` 已经成功从 C# 进入 native logger +3. `editor/bin/Debug/editor.log` 中可以看到脚本日志 +4. 但 editor 底部 `Console` 面板仍然为空，或看不到对应运行时日志 + +这说明问题不在脚本运行时本身，而在 editor 控制台面板读取日志数据的链路。 + +--- + +## 2. 复现现象 + +复现方式： + +1. 给场景对象挂上 `project/Assets/Scripts/TickLogProbe.cs` +2. 点击 editor 的 `Play` +3. 观察脚本上的计数字段持续递增 +4. 观察底部 `Console` 面板，没有出现 `[Project TickLogProbe] Awake/Start/Update/...` + +同时检查： + +- `editor/bin/Debug/editor.log` + +可以看到类似日志已经真实写入： + +- `[INFO] [Scripting] [Project TickLogProbe] Awake` +- `[INFO] [Scripting] [Project TickLogProbe] Start` +- `[INFO] [Scripting] [Project TickLogProbe] Update 1` + +--- + +## 3. 排查结论 + +问题不在以下层级： + +1. 不在 `Tick` 系统 +2. 不在 C# `Debug.Log` +3. 不在 Mono internal call 注册 +4. 不在 native `Logger` +5. 不在 `FileLogSink` + +这些链路都已经工作正常。 + +真正出问题的是： + +- editor `ConsolePanel` 读到的不是 logger 中真实注册的 `EditorConsoleSink` +- 它读到的是一个错误的 fallback 实例 + +--- + +## 4. 根本原因 + +根因位于： + +- `editor/src/Core/EditorConsoleSink.cpp` + +当前实现： + +1. `ConfigureEditorLogging()` 启动时会把一个真正的 `EditorConsoleSink` 注册到 `Logger` +2. 后续 `ConsolePanel::OnAttach()` 会调用 `EditorConsoleSink::GetInstance()` +3. `GetInstance()` 内部存在一个 `static EditorConsoleSink fallbackInstance` +4. 但 `EditorConsoleSink` 的构造函数会无条件执行 `s_instance = this` + +这会导致一个严重副作用： + +1. logger 里原本已经注册好的真实 `EditorConsoleSink` 先成为 `s_instance` +2. 当 `ConsolePanel` 第一次调用 `GetInstance()` 时，`fallbackInstance` 被构造 +3. `fallbackInstance` 构造时又把 `s_instance` 覆盖成它自己 +4. 此后 `ConsolePanel` 通过 `GetInstance()` 拿到的是 fallback sink +5. 但 logger 继续写入的仍然是最初注册到 `Logger` 的那一个真实 sink + +最终结果就是： + +1. 文件日志正常 +2. logger 正常 +3. 脚本日志正常 +4. Console 面板读取的是另一份空数据 + +--- + +## 5. 关键代码位置 + +相关位置： + +- `editor/src/Core/EditorLoggingSetup.h` +- `editor/src/Core/EditorConsoleSink.cpp` +- `editor/src/panels/ConsolePanel.cpp` +- `editor/src/Application.cpp` + +关键调用顺序： + +1. `Application::Initialize()` +2. `ConfigureEditorLogging()` +3. `Logger` 注册真实 `EditorConsoleSink` +4. `AttachEditorLayer()` +5. `ConsolePanel::OnAttach()` +6. `EditorConsoleSink::GetInstance()` +7. fallback 实例构造并错误覆盖 `s_instance` + +--- + +## 6. 影响范围 + +这个问题的影响不只是 `TickLogProbe` 看不到日志，而是整个 editor runtime 日志可视化都不可信： + +1. 任何 C# `Debug.Log` +2. 任何 `Scripting` 分类日志 +3. 未来 PlayMode 运行时诊断 +4. 运行时错误追踪 +5. 面向脚本模块的调试体验 + +从开发效率上看，这个问题会直接误导判断： + +1. 容易误以为脚本没执行 +2. 容易误以为 `Debug.Log` 没打通 +3. 容易误以为 Tick 没跑 +4. 实际上只是 Console 面板读错了 sink + +--- + +## 7. 修复方向 + +建议修复方向： + +1. `EditorConsoleSink::GetInstance()` 不应在查询过程中构造会修改全局状态的 fallback 对象 +2. `EditorConsoleSink` 构造函数不应无条件覆盖 `s_instance` +3. 应保证 `ConsolePanel` 永远读取 logger 中真实注册的那一个 sink +4. 如果确实需要 fallback，也应是只读占位对象，不能污染全局 `s_instance` + +更稳妥的方向包括： + +1. 明确区分“真实注册实例”和“空对象返回值” +2. 让 `ConfigureEditorLogging()` 的注册实例成为唯一权威实例 +3. 增加 editor 级回归测试，覆盖“logger 已写入但 ConsolePanel 读取为空”的场景 + +--- + +## 8. 验收标准 + +修复后至少应满足： + +1. `Debug.Log` 能实时显示在 editor 底部 `Console` 面板 +2. `editor.log` 与 `Console` 面板看到的是同一批日志 +3. `ConsolePanel` 读取到的 `EditorConsoleSink` 与 logger 注册实例一致 +4. PlayMode 期间 `Awake/Start/FixedUpdate/Update/LateUpdate` 日志都可见 +5. 不再出现“文件里有日志但面板里没有”的分裂状态 + +--- + +## 9. 优先级 + +高。 + +原因： + +1. 当前脚本运行时其实已经可用 +2. 但最基础的可视化调试入口失效 +3. 会直接阻塞后续对脚本生命周期、PlayMode 行为、运行时异常的验证效率 + +--- + +## 10. 备注 + +本问题已经确认不是以下原因导致： + +1. `Tick` 没运行 +2. `Script` 没挂载成功 +3. `Debug.Log` internal call 没注册 +4. logger category 被禁用 +5. `editor.log` 没写入 + +这是一个纯 editor 层的 Console sink 实例绑定错误问题。 diff --git a/docs/plan/API文档实时同步任务池_2026-04-03.md b/docs/plan/API文档实时同步任务池_2026-04-03.md deleted file mode 100644 index da6c9209..00000000 --- a/docs/plan/API文档实时同步任务池_2026-04-03.md +++ /dev/null @@ -1,248 +0,0 @@ -# API 文档实时同步任务池（2026-04-03，第二轮） - -## 文档定位 - -这份任务池接替已归档的第一轮计划： - -- `docs/plan/used/API文档实时同步任务池_2026-04-03_第一轮归档.md` - -第一轮已经解决的重点是： - -- canonical 目录结构收口 -- 历史缺页补齐 -- 第一轮大规模内容重写 - -本轮重点不再是“补结构”，而是： - -- 重新对照当前工作树源码与测试 -- 清理最近重构后重新出现的内容级失配 -- 继续维护一份适合多人并行认领的增量同步清单 - -## 当前复核快照 - -- 最近一次结构审计时间：`2026-04-03 15:07:08` -- 审计命令：`python -B docs/api/_tools/audit_api_docs.py` -- 当前结果： - - `Public headers: 244` - - `Editor source headers: 124` - - `Invalid header refs: 0` - - `Invalid source refs: 0` - - `Broken .md links: 0` - - `Stale canonical doc tokens: 0` - - `Stale editor doc tokens: 0` - - `Stale editor canonical pages: 0` - -这说明当前结构层面已经恢复全绿；本轮后续工作以内容级持续同步为主。 - -## 认领规则 - -- 一次只认领 `1` 个任务块。 -- 先把 `状态` 改成 `DOING`，再写 `认领人`。 -- 只能改自己任务块的 `写入范围`。 -- 所有改动都必须以“当前源码 + 当前测试 + 当前真实调用链”为依据，不允许按旧文档续写旧行为。 -- 如果清理了过期 API 页面，必须同时清理交叉链接。 - -## 任务池 - -## T01 Editor / Viewport 渲染计划与宿主流程内容同步 - -- 状态: `DONE` -- 认领人: `Codex` -- 优先级: `P0` -- 写入范围: - - `docs/api/XCEngine/Editor/Viewport/SceneViewportRenderPlan/**` - - `docs/api/XCEngine/Editor/Viewport/ViewportHostRenderFlowUtils/**` - - `docs/api/XCEngine/Editor/Viewport/ViewportHostService/**` - - 必要时 `docs/api/XCEngine/Editor/Viewport/IViewportHostService/**` -- 主要源码依据: - - `editor/src/Viewport/SceneViewportRenderPlan.h` - - `editor/src/Viewport/ViewportHostRenderFlowUtils.h` - - `editor/src/Viewport/ViewportHostService.h` - - `tests/editor/test_viewport_render_flow_utils.cpp` -- 已关闭问题: - - 旧文档仍把 Scene View 当前主路径写成 builtin post-process 主导 - - 没写清 grid / selection outline 现在已转为显式 `postScenePasses` - - 没写清 overlay pass 是 `editorOverlayFrameData + transientOverlayFrameData` 合并后再创建 - - 没写清 `Scene object id shader view is unavailable` 是局部降级警告，不是整帧失败 -- 完成记录: - - 已重写 `SceneViewportRenderPlan.md`、`BuildSceneViewportRenderPlan.md`、`ApplySceneViewportRenderPlan.md` - - 已同步 `ViewportHostRenderFlowUtils.md`、`ViewportHostService.md`、`RenderRequestedViewports.md` - - 已清理 `IViewportHostService` 中残留的旧表述 - -## T02 Core / Asset 缓存接口改名与语义重构同步 - -- 状态: `DONE` -- 认领人: `Codex` -- 优先级: `P0` -- 写入范围: - - `docs/api/XCEngine/Core/Asset/ResourceManager/**` - - `docs/api/XCEngine/Core/Asset/AssetImportService/**` - - `docs/api/XCEngine/Core/Asset/ProjectAssetIndex/**` - - 必要时 `docs/api/XCEngine/Core/Asset/Asset.md` - - 必要时 `docs/api/XCEngine/Core/Asset/ArtifactFormats/**` -- 主要源码依据: - - `engine/include/XCEngine/Core/Asset/ResourceManager.h` - - `engine/src/Core/Asset/ResourceManager.cpp` - - `engine/include/XCEngine/Core/Asset/AssetImportService.h` - - `engine/src/Core/Asset/AssetImportService.cpp` - - `engine/include/XCEngine/Core/Asset/ProjectAssetIndex.h` - - `engine/src/Core/Asset/ProjectAssetIndex.cpp` - - `tests/core/Asset/test_resource_manager.cpp` -- 已关闭问题: - - `RefreshAssetDatabase` 已经不存在，但旧文档仍在沿用 - - `RefreshProjectAssets` / `RebuildProjectAssetCache` / `GetProjectLibraryRoot` 缺页或未写清 - - `AssetImportService::EnsureArtifact()` 旧文档仍把输出写成 `ResolvedAsset` - - `BuildLookupSnapshot()` 旧文档仍按“双 map 出参”描述，而不是 `LookupSnapshot` - - `ImportedAsset::runtimeLoadPath` 语义未同步到上层文档 -- 完成记录: - - 已删除过期页 `ResourceManager/RefreshAssetDatabase.md` - - 已补齐 `RefreshProjectAssets.md`、`RebuildProjectAssetCache.md`、`GetProjectLibraryRoot.md` - - 已补齐 `LookupSnapshot.md`、`ImportedAsset.md`、`GetLibraryRoot.md`、`RebuildLibraryCache.md` - - 已同步 `Asset.md`、`ArtifactFormats.md`、`ResourceManager/Load.md` 的 `runtimeLoadPath` 口径 - -## T03 Scripting / Mono 托管销毁入口同步 - -- 状态: `DONE` -- 认领人: `Codex` -- 优先级: `P1` -- 写入范围: - - `docs/api/XCEngine/Scripting/Mono/MonoScriptRuntime/**` -- 主要源码依据: - - `engine/include/XCEngine/Scripting/Mono/MonoScriptRuntime.h` - - `engine/src/Scripting/Mono/MonoScriptRuntime.cpp` - - `tests/scripting/test_mono_script_runtime.cpp` -- 已关闭问题: - - `DestroyManagedObject(MonoObject*)` 已进入头文件与测试，但文档树没有对应页面 - - `MonoScriptRuntime.md` 没写清 `Object.Destroy(...)` 会回落到原生对象 / 组件销毁 -- 完成记录: - - 已新增 `DestroyManagedObject.md` - - 已更新 `MonoScriptRuntime.md` 的 internal call 说明与方法总表 - -## T04 Cross-Module / 教程层与模块总览口径持续复核 - -- 状态: `DONE` -- 认领人: `Codex` -- 优先级: `P2` -- 写入范围: - - `docs/api/_guides/**` - - `docs/api/XCEngine/*/*.md` - - 仅限与本轮已确认 API 变更直接相关的总览页 -- 任务目标: - - 继续检查教程页、模块总览页是否仍在传播旧心智模型 - - 尤其关注： - - Scene View 仍被写成 builtin post-process 主导 - - 资源导入链仍被写成 `artifactMainPath` / `RefreshAssetDatabase` 时代的口径 - - 托管对象销毁路径未在教程层被解释 -- 产出要求: - - 只修正已确认失配的 guide / overview 页面 - - 不做与当前源码无关的泛化扩写 - -## T05 增量变更监控 / 新一轮差异发现 - -- 状态: `OPEN` -- 认领人: `` -- 优先级: `P2` -- 写入范围: - - 只读检查 `engine/include/**`、`engine/src/**`、`editor/src/**`、`tests/**` - - 必要时只向本任务池追加新任务块 -- 任务目标: - - 继续结合工作树最新改动，找出新的“源码已变但文档还没跟上”的内容级失配 - - 优先检查： - - 最近改动过的 public headers - - 最近改动过的 Editor source headers - - 最近新增或更新过的测试 -- 产出要求: - - 只记录已确认的问题 - - 每条新任务都要写明： - - 受影响文档 - - 主要源码依据 - - 真实失配点 - - 建议写入范围 - -## T06 Rendering / Camera request、Passes 与执行链旧口径清理 - -- 状态: `DONE` -- 认领人: `Codex` -- 优先级: `P1` -- 写入范围: - - `docs/api/XCEngine/Rendering/CameraRenderRequest/**` - - `docs/api/XCEngine/Rendering/CameraRenderer/**` - - `docs/api/XCEngine/Rendering/Passes/**` - - `docs/api/XCEngine/Rendering/ObjectIdPass/**` - - `docs/api/XCEngine/Rendering/RenderPipeline/**` - - `docs/api/XCEngine/Rendering/SceneRenderer/**` - - `docs/api/XCEngine/Editor/Viewport/SceneViewportRenderPlan/**` - - 必要时 `docs/api/XCEngine/XCEngine.md` - - 必要时 `docs/api/_tools/audit_api_docs.py` -- 主要源码依据: - - `engine/include/XCEngine/Rendering/CameraRenderRequest.h` - - `engine/include/XCEngine/Rendering/CameraRenderer.h` - - `engine/include/XCEngine/Rendering/Passes/BuiltinObjectIdPass.h` - - `engine/include/XCEngine/Rendering/Passes/BuiltinObjectIdOutlinePass.h` - - `engine/include/XCEngine/Rendering/Passes/BuiltinInfiniteGridPass.h` - - `engine/include/XCEngine/Rendering/ObjectIdPass.h` - - `engine/include/XCEngine/Rendering/RenderPipeline.h` - - `engine/include/XCEngine/Rendering/SceneRenderer.h` - - `engine/src/Rendering/CameraRenderer.cpp` - - `engine/src/Rendering/SceneRenderer.cpp` - - `tests/Rendering/unit/test_camera_scene_renderer.cpp` - - `editor/src/Viewport/SceneViewportRenderPlan.h` - - `editor/src/Viewport/Passes/SceneViewportGridPass.cpp` - - `editor/src/Viewport/Passes/SceneViewportSelectionOutlinePass.cpp` - - `editor/src/Viewport/ViewportHostRenderFlowUtils.h` - - `tests/Editor/test_viewport_render_flow_utils.cpp` - - `tests/Editor/test_scene_viewport_overlay_renderer.cpp` -- 已关闭问题: - - `CameraRenderRequest.md` 仍描述已删除的 `builtinPostProcess` 子请求 - - 页面仍链接到不存在的 `BuiltinPostProcessRequest/BuiltinPostProcessRequest.md` - - Scene View 已改为通过 `postScenePasses` / `overlayPasses` 写回 request，但该页口径未同步 - - `CameraRenderer.md` 仍保留已删除的 `m_builtinPostProcessBuilder` 历史口径 - - `Passes.md` 的典型链路只写了 `postScenePasses`，遗漏当前 `overlayPasses` 组装路径 - - `Rendering/Passes` 下仍残留已删除的 `BuiltinPostProcessPassPlan` / `BuiltinPostProcessPassSequenceBuilder` 页面 - - `BuiltinObjectIdPass`、`BuiltinInfiniteGridPass` 多个公开入口缺页 - - `ObjectIdPass.md`、`RenderPipeline.md`、`SceneRenderer.md` 与顶层 `XCEngine.md` 仍在传播 builtin-post-process 心智模型 -- 完成记录: - - 已重写 `CameraRenderRequest.md` - - 已清理 `2` 个失效 `.md` 链接 - - 已同步 `CameraRenderer.md` 与 `Passes.md` 的当前执行链路表述 - - 已删除 `BuiltinPostProcessPassPlan.md`、`BuiltinPostProcessPassSequenceBuilder.md` -- 已补齐 `BuiltinObjectIdPass` / `BuiltinInfiniteGridPass` 缺失页面，并补充 `SceneViewportRenderPlan` 下 grid / selection outline pass factory 页面 -- 已同步 `ObjectIdPass.md`、`RenderPipeline.md`、`SceneRenderer.md` 与 `XCEngine.md` 的当前口径 -- 已补充 Rendering guide、`CameraRenderer::Render` 与 `ViewportHostService::RenderRequestedViewports` 的 request 级 pass 注入说明 -- 已为 `builtinPostProcess` / `BuiltinPostProcessRequest` / `m_builtinPostProcessBuilder` 增加 canonical 过期符号审计 -- 已复跑结构审计并确认 `Broken .md links: 0` - -## T07 Editor / Core `EditorConsoleSink` 生命周期说明同步 - -- 状态: `DONE` -- 认领人: `Codex` -- 优先级: `P1` -- 写入范围: - - `docs/api/XCEngine/Editor/Core/EditorConsoleSink/**` - - 必要时 `docs/api/XCEngine/Editor/Managers/Managers.md` - - 必要时 `docs/api/_tools/audit_api_docs.py` -- 主要源码依据: - - `editor/src/Core/EditorConsoleSink.h` - - `editor/src/Core/EditorConsoleSink.cpp` - - `editor/src/panels/ConsolePanel.cpp` - - `editor/src/Core/EditorLoggingSetup.h` - - `tests/Editor/test_editor_console_sink.cpp` -- 已关闭问题: - - `EditorConsoleSink::GetInstance()` 旧文档仍把它写成会返回 fallback 实例 - - 相关 overview 页面没有写清活动 sink 销毁后会返回 `nullptr` - - 审计脚本此前无法自动拦截这类旧生命周期表述 -- 完成记录: - - 已同步 `EditorConsoleSink.md`、`GetInstance.md`、`Destructor.md` - - 已同步 `Managers.md` 中对控制台 sink 生命周期的引用口径 - - 已为 `fallback 实例` 与“不会返回空指针”旧表述增加定向审计 - -## 当前结论 - -- 本轮已经关掉五组明确的内容级失配： - - `Viewport` 渲染计划与宿主流程 - - `Core/Asset` 缓存接口与导入服务语义 - - `MonoScriptRuntime` 托管销毁入口 - - `Rendering` 相机请求、Passes 与单相机执行链旧口径 - - `EditorConsoleSink` 生命周期与空指针返回语义 -- 当前结构审计为全绿。 -- 当前仍建议保留 `T04` 与 `T05` 作为持续性并行入口，用来承接你后续重构带来的新文档漂移。 diff --git a/docs/plan/API文档并行更新任务池_2026-04-02.md b/docs/plan/API文档并行更新任务池_2026-04-02.md deleted file mode 100644 index deb03670..00000000 --- a/docs/plan/API文档并行更新任务池_2026-04-02.md +++ /dev/null @@ -1,117 +0,0 @@ -# API 文档并行更新任务池（2026-04-02） - -## 目的 - -基于 `2026-04-02` 当前工作树，这份清单用于把 API 文档更新任务拆成可并行认领的独立块，供多个会话同时推进。 - -## 认领规则 - -- 一次只认领 `1` 个任务块，先改 `状态` 和 `认领人`。 -- 只修改自己任务块的 `写入范围`，不要跨任务顺手改别的模块页。 -- 除 `T09` 之外，其他任务不要更新 `docs/api/_meta/rebuild-status.md`，避免多人冲突。 -- 每个任务都要以源码、实现、测试、真实调用点为依据，不允许只按命名猜测行为。 -- 如果任务执行中发现需要新增 guide，统一放到 `docs/api/_guides//` 下。 - -## 首批并行推荐 - -- 优先并行启动: `T01`、`T03`、`T04`、`T05`、`T07` -- 第二批跟进: `T02`、`T06`、`T08` -- 收尾整合: `T09` - -## 任务池 - -## T01 Editor / Viewport 子模块补齐与重写 - -- 状态: `IN_PROGRESS` -- 认领人: `Codex-Viewport` -- 优先级: `P0` -- 写入范围: `docs/api/XCEngine/Editor/Viewport/**`、`docs/api/XCEngine/Editor/panels/SceneViewPanel/**`、`docs/api/XCEngine/Editor/panels/ViewportPanelContent/**` -- 主要源码依据: `editor/src/Viewport/**`、`editor/src/panels/SceneViewPanel.*`、`editor/src/panels/ViewportPanelContent.h`、`tests/editor/test_scene_viewport_camera_controller.cpp` -- 当前缺口: `Viewport` 整个 canonical 树尚未建立；以下页面当前缺失: `SceneViewportCameraController`、`SceneViewportMoveGizmo`、`SceneViewportRotateGizmo`、`SceneViewportScaleGizmo`、`SceneViewportOverlayRenderer`、`ViewportHostService`、`ViewportHostRenderFlowUtils`、`SceneViewportEditorOverlayData`、`SceneViewportOverlayBuilder`、`ViewportPanelContent` -- 完成标准: 补齐 `Viewport/Viewport.md` 与所有类型页；`SceneViewPanel` 文档重写到当前 gizmo / overlay / host flow 实现；写清楚生命周期、交互链路、渲染路径和测试覆盖 - -## T02 Editor / ScriptComponentEditor 补齐 - -- 状态: `DONE` -- 认领人: `Codex` -- 优先级: `P0` -- 写入范围: `docs/api/XCEngine/Editor/ComponentEditors/ScriptComponentEditor/**`、`docs/api/XCEngine/Editor/ComponentEditors/ScriptComponentEditorUtils/**`、`docs/api/XCEngine/Editor/ComponentEditors/ComponentEditors.md`、`docs/api/XCEngine/Editor/ComponentEditors/ComponentEditorRegistry/**` -- 主要源码依据: `editor/src/ComponentEditors/ScriptComponentEditor.h`、`editor/src/ComponentEditors/ScriptComponentEditorUtils.h`、`editor/src/ComponentEditors/ComponentEditorRegistry.cpp` -- 当前缺口: `ScriptComponentEditor` 与 `ScriptComponentEditorUtils` 还没有 canonical 页面；组件编辑器总览也需要纳入脚本组件编辑器 -- 完成标准: 补齐缺页；说明 Inspector 侧脚本字段绘制、字段元数据来源、与 `ScriptEngine` / `ScriptComponent` 的关系 - -## T03 Core / AssetDatabase 新建与资产数据库链路说明 - -- 状态: `IN_PROGRESS` -- 认领人: `Codex-Asset` -- 优先级: `P0` -- 写入范围: `docs/api/XCEngine/Core/Asset/AssetDatabase/**`、`docs/api/XCEngine/Core/Asset/Asset.md` -- 主要源码依据: `engine/include/XCEngine/Core/Asset/AssetDatabase.h`、相关 `.cpp` 实现、项目目录下新增的 `.meta` 与 `Library` 资产缓存变化 -- 当前缺口: `AssetDatabase` 对应的 canonical 类型页完全缺失；`Core/Asset` 模块总览需要反映新的数据库/导入缓存方向 -- 完成标准: 建立 `AssetDatabase` 页面，明确 GUID、path、meta、导入缓存、查询职责，以及它和 `ProjectPanel` / `ResourceManager` / 资源导入流程的关系 - -## T04 Rendering / Passes 子模块与 BuiltinObjectIdOutlinePass 补齐 - -- 状态: `DONE` -- 认领人: `Codex` -- 优先级: `P0` -- 写入范围: `docs/api/XCEngine/Rendering/Passes/**` -- 主要源码依据: `engine/include/XCEngine/Rendering/Passes/BuiltinObjectIdOutlinePass.h`、`engine/src/Rendering/Passes/BuiltinObjectIdOutlinePass.cpp` -- 当前缺口: `Rendering/Passes` 目录当前没有 canonical 文档树；`BuiltinObjectIdOutlinePass` 页面缺失 -- 完成标准: 新建 `Passes/Passes.md` 和 `BuiltinObjectIdOutlinePass` 类型页；写清楚对象 ID / 轮廓高亮的输入输出、依赖资源、典型使用位置和当前限制 - -## T05 Scripting 模块内容重构 - -- 状态: `DONE` -- 认领人: `Codex` -- 优先级: `P1` -- 写入范围: `docs/api/XCEngine/Scripting/**`、`docs/api/_guides/Scripting/**` -- 主要源码依据: `engine/include/XCEngine/Scripting/IScriptRuntime.h`、`Mono/MonoScriptRuntime.h`、`NullScriptRuntime.h`、`ScriptComponent.h`、`ScriptEngine.h` 及对应 `.cpp`；`tests/scripting/**` -- 当前缺口: 结构存在，但脚本运行时、字段同步、项目脚本程序集、空运行时回退等内容需要按当前实现重写 -- 完成标准: 明确运行时抽象、Mono 后端、Null 后端、字段存储与组件生命周期；必要时补一篇项目脚本程序集 / 字段同步 guide - -## T06 Editor 运行时胶水层与面板内容更新 - -- 状态: `TODO` -- 认领人: `未认领` -- 优先级: `P1` -- 写入范围: `docs/api/XCEngine/Editor/Application/**`、`docs/api/XCEngine/Editor/Core/EventBus/**`、`docs/api/XCEngine/Editor/panels/InspectorPanel/**`、`docs/api/XCEngine/Editor/panels/ProjectPanel/**`、`docs/api/XCEngine/Editor/UI/Widgets/**`、`docs/api/XCEngine/Editor/Actions/HierarchyActionRouter/**`、`docs/api/XCEngine/Editor/Commands/EntityCommands/**` -- 主要源码依据: `editor/src/Application.*`、`editor/src/Core/EventBus.h`、`editor/src/panels/InspectorPanel.*`、`editor/src/panels/ProjectPanel.*`、`editor/src/UI/Widgets.h`、`editor/src/Actions/HierarchyActionRouter.h`、`editor/src/Commands/EntityCommands.h` -- 当前缺口: 这些页面虽然大多存在，但内容容易落后于当前交互链路；`ProjectPanel` 虽已较新，仍要根据这轮源码变化做二次核对 -- 完成标准: 把“Editor 主循环 -> EventBus -> 面板 -> Action/Command”这条链路写清楚；Inspector/Project/Hierarchy 相关页内容与当前实现严格对齐 - -## T07 Rendering 相机请求与对象 ID 渲染链路更新 - -- 状态: `DONE` -- 认领人: `Codex` -- 优先级: `P1` -- 写入范围: `docs/api/XCEngine/Rendering/CameraRenderRequest/**`、`docs/api/XCEngine/Rendering/CameraRenderer/**`、`docs/api/XCEngine/Rendering/RenderMaterialUtility/**`、`docs/api/XCEngine/Rendering/Rendering.md` -- 主要源码依据: `engine/include/XCEngine/Rendering/CameraRenderRequest.h`、`engine/src/Rendering/CameraRenderer.cpp`、`engine/src/Resources/Material/MaterialLoader.cpp`、`engine/src/Rendering/Passes/BuiltinObjectIdOutlinePass.cpp` -- 当前缺口: 文档需要反映这轮 renderer 里对象 ID、outline、camera request、材质 render state 的新关系 -- 完成标准: 写清楚 camera request 的职责边界、camera renderer 的主流程、object-id/outline 的接入点，以及材质 render state 对渲染路径的影响 - -## T08 Components / MeshFilterComponent 与资源绑定链路更新 - -- 状态: `IN_PROGRESS` -- 认领人: `Codex` -- 优先级: `P1` -- 写入范围: `docs/api/XCEngine/Components/MeshFilterComponent/**`、`docs/api/XCEngine/Components/Components.md` -- 主要源码依据: `engine/include/XCEngine/Components/MeshFilterComponent.h`、相关 `.cpp`、`tests/Resources/Mesh/test_mesh_loader.cpp`、`tests/Resources/Material/test_material_loader.cpp` -- 当前缺口: `MeshFilterComponent` 页面存在，但需要重新核对 mesh handle / path / 资源解析链路；模块总览也应补充 MeshFilter 在渲染和资产导入链路中的定位 -- 完成标准: 说明 `MeshFilterComponent` 如何保存 mesh 引用、如何与资源系统和渲染提取流程衔接，以及当前限制 - -## T09 根总览与最终审计 - -- 状态: `TODO` -- 认领人: `未认领` -- 优先级: `P2` -- 写入范围: `docs/api/XCEngine/XCEngine.md`、受影响的模块总览页、`docs/api/_meta/rebuild-status.md` -- 主要源码依据: 前面所有任务的完成结果 -- 当前缺口: 根总览和模块总览需要在前面任务落地后统一收口；审计状态文件只能由一个会话最终更新 -- 完成标准: 统一调整总览页导航；执行 `audit_api_docs.py`、覆盖校验与链接校验；写回新的 `rebuild-status.md` - -## 备注 - -- 如果只有 `2-3` 个会话，优先拿 `T01`、`T05`、`T07` -- 如果有 `4-6` 个会话，推荐并行拿 `T01`、`T03`、`T04`、`T05`、`T06`、`T07` -- `T09` 必须最后做 diff --git a/docs/plan/Editor架构说明.md b/docs/plan/Editor架构说明.md index 24e3f884..472974ab 100644 --- a/docs/plan/Editor架构说明.md +++ b/docs/plan/Editor架构说明.md @@ -6,15 +6,19 @@ - 把视觉样式、交互路由、编辑命令、dock 布局、面板壳层拆开。 - 把 `Hierarchy / Project / Inspector / Console / MenuBar` 统一到同一套 shared UI 和 action 语义上。 -- 保持 `Scene / Game` 先作为空壳 panel，等待后续 `Viewport / RHI` 回归。 +- 把 `Scene / Game` viewport 保持在当前真实主链上：`ViewportHostService -> Rendering + RHI -> ImGui panel`。 +- 把 `Assets + .meta + Library` 项目工作流、脚本程序集构建与运行时状态纳入 editor 正式分层，而不是继续当外围脚本。 -这意味着当前 editor 的重点是“编辑器外壳架构完整”，不是“运行时视口功能完整”。 +这意味着当前 editor 的重点已经不是“先把外壳搭出来”，而是： + +- 在现有外壳分层上继续收口真实可运行的 viewport / project / scripting 主链。 +- 让 panel、viewport helper、commands、managers 和引擎侧 `Rendering / Resources / Scene / Scripting` 的边界继续清晰化。 ## 2. 总体分层 当前 editor 推荐按下面的依赖方向理解： -`Application -> EditorLayer -> EditorWorkspace -> Panels -> Actions -> Commands -> Managers/Core` +`Application -> EditorLayer -> EditorWorkspace -> Panels/Viewport -> Actions -> Commands -> Managers/Core` 同时还有一条横向的共享 UI 层： @@ -24,6 +28,10 @@ `InspectorPanel -> ComponentEditorRegistry -> IComponentEditor` +以及一条已经落地的 editor 到引擎主链： + +`Viewport / Managers / Scripting -> Rendering / Resources / Scene / Scripting / RHI` + 允许依赖的基本原则： - `UI` 只负责样式 token、共享控件、popup/property-grid 等表现层能力，不承担业务语义。 @@ -32,6 +40,7 @@ - `Panels` 只保留最小的渲染壳层和少量局部瞬时状态，不直接堆业务逻辑。 - `Layout` 只负责 dockspace 和布局持久化，不处理 scene/project 业务。 - `Core/Managers` 提供 editor 运行时共享状态与数据入口。 +- `Viewport` 是 editor 宿主和引擎渲染主链之间的正式桥接层，不是 panel 内随手拼的辅助代码。 不允许继续扩散的方向： @@ -272,6 +281,60 @@ 3. 在 `ComponentEditorRegistry.cpp` 注册。 4. 如果涉及复杂交互，优先复用 `UI::PropertyGrid` 和 undo interactive change 机制。 +### 3.10 Viewport + +关键文件： + +- `editor/src/Viewport/ViewportHostService.h` +- `editor/src/Viewport/IViewportHostService.h` +- `editor/src/Viewport/SceneViewportChrome.h` +- `editor/src/Viewport/SceneViewportInteractionFrame.h` +- `editor/src/Viewport/SceneViewportNavigation.h` +- `editor/src/Viewport/SceneViewportTransformGizmoCoordinator.h` +- `editor/src/Viewport/SceneViewportOverlayBuilder.h` +- `editor/src/Viewport/SceneViewportOverlayFrameCache.h` +- `editor/src/Viewport/SceneViewportOverlaySpriteResources.h` +- `editor/src/Viewport/SceneViewportResourcePaths.h` +- `editor/src/Viewport/Passes/SceneViewportEditorOverlayPass.h` + +职责： + +- 作为 editor 宿主与引擎 `Rendering + RHI` 的桥接层，维护 Scene / Game viewport 的离屏渲染接线。 +- 维护当前 Scene View helper 主链： + - `SceneViewportChrome` + - `SceneViewportInteractionFrame` + - `SceneViewportNavigation` + - `SceneViewportTransformGizmoCoordinator` + - `ViewportHostService` +- 负责 overlay builder、overlay frame cache、sprite 资源准备、object-id picking、grid、outline 和 gizmo overlay state。 + +边界： + +- `Viewport` 是正式子系统，不再是“等待未来回归”的空位。 +- panel 不应自己拼接一套独立渲染路径；新的 viewport 行为优先落到 helper、host service 或 overlay pass。 +- `SceneViewportShaderPaths.h` 当前主要是兼容 include；资源路径真实 owner 已经转到 `SceneViewportResourcePaths.h`。 + +### 3.11 Scripting / Project Workflow + +关键文件： + +- `editor/src/Scripting/EditorScriptAssemblyBuilder.h` +- `editor/src/Scripting/EditorScriptRuntimeStatus.h` +- `editor/src/Managers/ProjectManager.h` +- `editor/src/Managers/SceneManager.h` +- `editor/src/Utils/ProjectFileUtils.h` + +职责： + +- 解析项目根目录、读写 `Project.xcproject`，并把仓库内 `project/` 或 `--project ` 解析为当前工程。 +- 驱动 `Assets + .meta + Library` 风格项目 workflow，包括项目资源浏览、脚本程序集重建入口和运行时状态反馈。 +- 把项目脚本程序集与 editor/runtime 实际消费的 `Library/ScriptAssemblies/` 目录连接起来。 + +边界： + +- 与项目资产、`.meta`、`Library`、脚本程序集相关的问题，不应再按“editor 仍处于无工程状态”理解。 +- `ProjectManager`、`SceneManager`、`EditorScriptAssemblyBuilder` 与引擎侧 `ResourceManager / AssetImportService / ScriptEngine` 是协作关系，不应在 panel 里各自复制一层状态机。 + ## 4. EventBus 使用规则 `EventBus` 现在主要承担两类职责： @@ -334,16 +397,19 @@ - dock layout controller 与 editor workspace 装配。 - inspector 的 component editor registry 接入。 - editor 级回归测试基础框架与关键命令测试。 +- `Scene / Game` viewport 已经重新接回当前正式主链：引擎 `Rendering + RHI` 离屏输出 -> `ViewportHostService` -> ImGui panel。 +- `Assets + .meta + Library` 项目工作流、`Project.xcproject`、脚本程序集重建与脚本运行时状态已经进入 editor 正式工作流。 +- viewport helper 已按 `Chrome -> InteractionFrame -> Navigation -> TransformGizmoCoordinator -> ViewportHostService` 显式拆层。 当前明确暂缓： -- `Scene` panel 内容。 -- `Game` panel 内容。 -- `Viewport` 与 RHI 重新接入。 +- 把 editor 主线程上残留的同步资源兜底点继续清理到更严格的异步消费模型。 +- 把 `Library bootstrap / scene streaming / explicit import` 的状态模型继续正式化到 UI。 +- 继续减少 panel 内局部瞬时状态与 helper 间重复规则。 原因很明确： -- 这三部分依赖渲染壳层与后续 renderer/RHI 重构，暂时不适合和 editor UI 架构收尾混在一起。 +- 前三项已经不是“没接回来的未来工作”，而是已经落地、但还要继续收口的当前主线。 ## 8. 后续新增功能时的落点原则 @@ -355,6 +421,7 @@ - 新 inspector 组件面板：放 `ComponentEditors` - 新 dock/window 布局控制：放 `Layout` - 新 editor 全局状态：放 `Core/Managers` +- 新 viewport host / overlay / interaction helper：放 `Viewport` - 只是把已有能力拼进某个窗口：放 `Panels` 如果一个功能不知道放哪，一般先问自己： @@ -371,8 +438,9 @@ - 继续压缩少量 panel 本地瞬时状态，能下沉的继续下沉。 - 继续补命令/路由回归测试，尤其是 inspector interactive undo 边界。 -- 为将来的 viewport 回归预留稳定接入口，但暂不提前接入渲染逻辑。 +- 继续补 viewport helper、project workflow、script assembly builder 与 scene streaming 相关回归测试。 +- 把 `Library bootstrap`、显式导入、后台 scene asset streaming 这三类状态在 editor UI 上分开表达。 结论： -editor 当前已经形成稳定分层，后面再做功能迭代时，应坚持“先看边界，再落代码”，不要回到 panel 内部堆逻辑的旧路线。 +editor 当前已经形成稳定分层，而且这套分层已经承接了真实的 viewport / project / scripting 工作流。后面再做功能迭代时，应坚持“先看边界，再落代码”，不要回到 panel 内部堆逻辑的旧路线。 diff --git a/docs/plan/NanoVDB稀疏体积渲染正式集成计划_2026-04-08.md b/docs/plan/NanoVDB稀疏体积渲染正式集成计划_2026-04-08.md new file mode 100644 index 00000000..22bed9e4 --- /dev/null +++ b/docs/plan/NanoVDB稀疏体积渲染正式集成计划_2026-04-08.md @@ -0,0 +1,765 @@ +# NanoVDB 稀疏体积渲染正式集成计划（Unity 对齐版） + +文档日期：2026-04-08 + +适用范围：当前 `XCEngine` 的 `Resources / Shader / RHI / Rendering / Components / Editor` 体系，以及未来要对齐 Unity 的 C#、Shader、SRP 工作流。 + +文档目标：把 `MVS/VolumeRenderer` 中已经验证过的 `NanoVDB + GPU Buffer + Ray Marching` 原型，整理成一套能正式进入引擎主线、且从一开始就严格兼容 Unity 风格 shader/C# 语义的落地方案。 + +--- + +## 1. 先给结论 + +这条主线的正式方向不是： + +1. 把体积数据退化成 `Texture3D` +2. 给当前引擎临时塞一套 volume 专用 shader 语法 +3. 只在某个后端里私下打通一条 demo 路径 + +这条主线的正式方向必须是： + +1. 保留 `NanoVDB` 的稀疏体积本质 +2. 把 buffer 资源能力补齐到引擎正式架构里 +3. 让高层 authoring 语义严格对齐 Unity +4. 让低层 RHI 分类只存在于引擎内部 +5. 让 volumetric 成为 renderer / future SRP 中的正式 pass，而不是特例后处理 + +因此，这份计划默认坚持一条红线： + +`StructuredBuffer / RawBuffer` 可以作为引擎内部资源分类存在，但作者可见语义、未来 C# API 语义、shader 写法语义，都必须对齐 Unity 既有做法，而不是引擎自创。 + +--- + +## 2. 设计总原则 + +### 2.1 Unity 对齐原则 + +后续所有设计都必须同时满足下面这些条件： + +1. shader 文件继续朝 Unity 风格 `.shader + HLSLPROGRAM` 组织收口。 +2. 作者侧 buffer 语义必须沿用 HLSL/Unity 现成写法，例如： + - `StructuredBuffer` + - `ByteAddressBuffer` + - `RWStructuredBuffer` + - `RWByteAddressBuffer` +3. 不允许为了体积渲染单独发明新的高层 buffer 关键字、声明块或材质 schema。 +4. `Properties` 块只用于可序列化作者参数，不用于声明或承载 GPU buffer。 +5. 未来 C# 层的 buffer 接口方向，必须对齐 Unity 的： + - `ComputeBuffer` + - `GraphicsBuffer` + - `Material.SetBuffer` + - `Shader.SetGlobalBuffer` + - `CommandBuffer.SetGlobalBuffer` +6. renderer 侧对 buffer 的真正绑定，必须是运行时 per-pass / per-object / global resource binding，而不是材质资产直接持有底层 view。 +7. `StructuredBuffer / RawBuffer` 在引擎里首先是底层编译和绑定分类，不是高层 authoring 概念。 + +### 2.2 稀疏体积原则 + +1. `NanoVDB` 必须按稀疏体积方案正式接入。 +2. 不允许把正式路线退化成 `Texture3D` 替代方案。 +3. `Texture3D` 可以作为引擎未来的独立能力预留，但不是这条主线的收口路径。 + +### 2.3 SRP 兼容原则 + +1. volumetric 必须被设计成正式 scene pass。 +2. 它的输入和生命周期要能自然映射到未来 SRP 的 renderer feature / render pass event。 +3. 不允许把它设计成只能在 builtin pipeline 中硬编码存在的特例逻辑。 + +--- + +## 3. Unity 参考基线 + +`参考/Unity NanoVDB` 已经给出了一条对本引擎非常重要的参考方向： + +1. C# 侧使用 `ComputeBuffer` +2. 运行时通过 `Material.SetBuffer("buf", gpuBuffer)` 绑定 +3. shader 侧通过 `StructuredBuffer` 读取 +4. `ComputeBufferType.Default` 对应的正是通用 GPU buffer 资源路径，而不是材质属性系统 + +这说明后续正式集成时，高层语义应该对齐的是： + +1. Unity 的 buffer authoring / binding 模式 +2. Unity 的 shader 资源声明模式 +3. Unity/HDRP 中把体积渲染插入 render pass 的方式 + +而不是： + +1. 直接照抄 `MVS` 的 D3D12 私有代码 +2. 用引擎内部 `RawBuffer` 这个名词去污染高层 shader/C# 接口 +3. 为了先出图，临时开 volume 专用旁路 + +--- + +## 4. 本轮明确不做什么 + +为了防止架构被 demo 反向拖偏，本轮明确不做下面这些事： + +1. 不把 `NanoVDB` 退化成正式 `Texture3D` 方案。 +2. 不把 `MVS/VolumeRenderer` 的 D3D12 私有 helper、私有绑定逻辑直接搬进引擎主线。 +3. 不先做全局体积雾、froxel fog、clustered volumetrics。 +4. 不先做复杂编辑器 authoring 工具，例如体积笔刷和节点编辑器。 +5. 不先做 DXR / path tracing 体渲染。 +6. 不为体积渲染另开一套与 Unity 不一致的 shader/material/C# 表层语法。 + +--- + +## 5. 当前真正缺的不是“算法”，而是正式能力 + +当前原型已经证明了下面几件事： + +1. `NanoVDB` 数据可以读。 +2. `NanoVDB` 数据可以上传到 GPU buffer。 +3. shader 可以基于 `pnanovdb` 做树遍历、HDDA 跳空和 ray marching。 +4. D3D12 原型能完成从数据到画面的闭环。 + +但引擎主线真正还缺下面这些正式能力： + +1. `.nvdb` 如何进入资产与 artifact 体系。 +2. shader 如何用 Unity 风格语义正式声明 buffer 资源。 +3. 材质系统如何和运行时 buffer 绑定做严格职责分离。 +4. RHI 三后端如何正式支持 buffer SRV/UAV。 +5. renderer 如何把体积渲染作为正式 pass 插入 frame。 +6. 未来 C# 层如何以 Unity 风格接口绑定 buffer。 +7. editor 和测试如何验证整条链路不会回归。 + +所以本计划的本质不是“移植 demo”，而是“先补正式能力，再把 demo 算法放到正式能力之上”。 + +--- + +## 6. 正式架构目标 + +### 6.1 作者可见层：严格对齐 Unity 风格 + +这一层是未来引擎用户、shader 作者、C# 脚本作者看到的语义表面。 + +要求如下： + +1. `.shader` 文件语法继续按 Unity 风格推进。 +2. buffer 在 shader 中的声明使用 HLSL 现成资源类型，不使用自定义资源关键字。 +3. 材质面板暴露的是作者参数，而不是底层 GPU buffer 本体。 +4. 如果未来提供脚本绑定接口，脚本看到的应该是 `ComputeBuffer / GraphicsBuffer` 风格对象和 `SetBuffer` 风格 API。 + +这层明确禁止： + +1. 在 `Properties` 中定义 `StructuredBuffer` 或 `RawBuffer` +2. 在 `.shader` 外层再发明 `BufferResources { ... }` 之类自定义块 +3. 让作者直接接触 `RHIResourceView` 或后端 view descriptor + +### 6.2 引擎中层：运行时绑定契约 + +这一层负责把“作者声明的 shader 资源”和“运行时真实绑定的 GPU 资源”接起来。 + +正式边界应该是： + +1. `Material` 只持有： + - shader 引用 + - keyword / render state + - 序列化参数 + - 常规纹理/采样器类作者资源 +2. `VolumeField` 或其他 runtime producer 提供真实 GPU buffer 资源 +3. `Renderer` / `CommandBuffer` / future script binding API 在渲染阶段把 buffer 绑定进 pass + +也就是说： + +1. `NanoVDB` 主数据不是普通 material property +2. 它是运行时资源绑定 +3. 材质只负责“怎么渲染” +4. `VolumeField` 负责“渲染的数据是什么” + +### 6.3 引擎底层：RHI 资源分类 + +在 RHI 与编译反射层，可以存在正式的内部分类，例如： + +1. `StructuredBuffer` +2. `RawBuffer` +3. 后续可扩展： + - `ByteAddressBuffer` 的内部映射 + - `RWStructuredBuffer` + - `RWByteAddressBuffer` + +但要强调： + +1. 这些是内部分类，不是高层 authoring 语法。 +2. 高层写的是 Unity/HLSL 资源声明。 +3. 引擎负责把这些声明反射并落到底层分类。 + +### 6.4 资源层：正式 VolumeField 资产 + +新增正式资源抽象： + +1. `ResourceType::VolumeField` +2. `Resources::VolumeField` +3. `VolumeFieldLoader` +4. `NanoVDBVolumeImporter` + +导入链路建议： + +1. 源资产：`Assets/.../*.nvdb` +2. artifact：`Library/Artifacts/.../main.xcvol` + +`main.xcvol` 建议包含： + +1. schema version +2. storage kind +3. grid type / grid class +4. world bbox +5. voxel size +6. active voxel statistics +7. payload byte size +8. 原始 `NanoVDB` blob + +原则： + +1. 第一阶段不做有损转换。 +2. artifact 中保留原始稀疏表示。 +3. metadata 单独结构化，供 loader / renderer 快速读取。 + +### 6.5 渲染层：正式体积 pass + +正式新增： + +1. `VolumeRendererComponent` +2. `VisibleVolumeItem` +3. `RenderSceneData.visibleVolumes` +4. `BuiltinVolumetricPass` + +该 pass 的职责： + +1. 消费 `VisibleVolumeItem` +2. 绑定 camera / depth / lighting / shadow / volume buffer / material 参数 +3. 执行 ray marching +4. 合成到 scene color + +推荐阶段位置： + +1. `ShadowCaster` +2. `Depth / Opaque` +3. `Skybox` +4. `Volumetrics` +5. `Transparent` +6. `PostProcess` +7. `FinalColor` + +这保证它天然兼容未来 SRP 的 renderer feature / pass event 方向。 + +### 6.6 C# 层预留目标 + +即使当前 C# 模块还没完全落地，这条计划也必须先把接口方向冻结。 + +后续需要预留的高层语义包括： + +1. `ComputeBuffer`/`GraphicsBuffer` 风格资源对象 +2. `Material.SetBuffer` +3. `Shader.SetGlobalBuffer` +4. `CommandBuffer.SetGlobalBuffer` + +这一层的原则是： + +1. 先冻结语义，再决定托管层具体封装细节 +2. 不允许等到以后 C# 接入时再发现底层 buffer 路径与 Unity 语义冲突 + +--- + +## 7. 关键命名与职责冻结 + +为了避免后续反复推翻命名，这一轮先冻结： + +1. 正式资源抽象：`VolumeField` +2. 存储种类：`VolumeStorageKind::NanoVDB` +3. 导入器：`NanoVDBVolumeImporter` +4. 运行时加载器：`VolumeFieldLoader` +5. 组件：`VolumeRendererComponent` +6. frame data：`VisibleVolumeItem` +7. pass：`BuiltinVolumetricPass` + +命名原则： + +1. 引擎对外抽象是 `VolumeField` +2. `NanoVDB` 是第一种正式存储后端 +3. 不把具体文件格式命名泄露到整个 renderer 表面 + +--- + +## 8. Shader 与 Buffer 的正式契约 + +这是整个计划最关键的部分。 + +### 8.1 shader 作者看到的语义 + +作者应该写的是： + +1. `StructuredBuffer` 这类 Unity/HLSL 现成声明 +2. 未来必要时的 `ByteAddressBuffer` +3. 如果进入写路径，再扩到 `RWStructuredBuffer` / `RWByteAddressBuffer` + +作者不应该写的是： + +1. `RawBuffer` +2. `StructuredRawBuffer` +3. 任何引擎自创的高层 buffer 类型关键字 + +### 8.2 材质系统的职责边界 + +材质系统只负责： + +1. 密度、吸收、散射、步长、相位函数参数 +2. tint / emission +3. shader variant / keyword +4. render state + +材质系统不负责： + +1. 序列化 `NanoVDB` payload +2. 序列化 GPU buffer handle +3. 序列化底层 SRV/UAV view + +### 8.3 运行时绑定职责 + +运行时绑定应该由以下层级之一完成： + +1. `Renderer` +2. `CommandBuffer` +3. future script API + +典型语义应接近： + +1. `material.SetBuffer("buf", volumeBuffer)` +2. `commandBuffer.SetGlobalBuffer(name, buffer)` + +### 8.4 内部映射规则 + +建议的内部映射是： + +1. `StructuredBuffer` -> `ShaderResourceType::StructuredBuffer` +2. `ByteAddressBuffer` -> `ShaderResourceType::RawBuffer` +3. `RWStructuredBuffer` -> UAV + structured 分类 +4. `RWByteAddressBuffer` -> UAV + raw 分类 + +这里的重点不是名字，而是边界： + +1. 高层保持 Unity/HLSL 语义 +2. 中层做反射和 metadata +3. 低层做真正 view 创建与 descriptor 绑定 + +### 8.5 一个硬性前置条件 + +如果当前 shader authoring 体系还不能正式表达 Unity 风格 buffer 声明，那么这个缺口的优先级高于体积渲染本身。 + +也就是说： + +1. 不允许为了先做 volumetric，单独给它走私有 shader 语法 +2. 必须先把正式 shader authoring / reflection / runtime binding 路径打通 + +--- + +## 9. RHI 正式能力目标 + +RHI 侧至少需要补齐： + +1. `RHIDevice::CreateShaderResourceView(RHIBuffer*, const ResourceViewDesc&)` +2. `RHIDevice::CreateUnorderedAccessView(RHIBuffer*, const ResourceViewDesc&)` +3. `ResourceViewDesc` 的 buffer 字段： + - firstElement + - elementCount + - structureByteStride + - raw / structured / formatted 标记 +4. `RHIResourceView` 对 buffer SRV/UAV 的统一表达 +5. descriptor set / bind group 更新路径对 buffer view 的正式支持 + +三后端预期映射： + +1. D3D12： + - buffer SRV + - buffer UAV +2. Vulkan： + - storage buffer + - 需要时使用 texel buffer 路径 +3. OpenGL： + - SSBO 优先 + - 明确 GLSL 转译和绑定规则 + +这里必须强调： + +1. 这些是底层实现能力 +2. 它们服务于高层 Unity 风格语义 +3. 它们不能反过来决定高层作者接口长什么样 + +--- + +## 10. 正式实施阶段 + +## 阶段 0：冻结 Unity 对齐边界 + +### 目标 + +在改代码前，先冻结高层语义、中层契约、低层分类三层边界。 + +### 任务 + +1. 冻结 `VolumeField` / `VolumeRendererComponent` / `VisibleVolumeItem` / `BuiltinVolumetricPass` 命名 +2. 冻结体积渲染在 scene pass 中的阶段位置 +3. 冻结高层 buffer 语义： + - 只接受 Unity/HLSL 写法 +4. 冻结材质边界： + - buffer 不进 `Properties` +5. 冻结未来 C# 方向： + - `ComputeBuffer / GraphicsBuffer + SetBuffer` 语义 +6. 冻结内部映射： + - `StructuredBuffer` -> internal structured + - `ByteAddressBuffer` -> internal raw + +### 验收标准 + +1. 后续实现阶段不再反复摇摆高层语义 + +--- + +## 阶段 1：先补底层 buffer 资源视图能力 + +### 目标 + +补齐 renderer 目前缺失的“buffer 作为正式 shader 资源”的底层能力。 + +### 任务 + +1. 完成 `RHIBuffer` 的 SRV/UAV 创建接口 +2. 补齐 `ResourceViewDesc` 的 buffer 视图字段 +3. 让 descriptor set 更新路径正式支持 buffer 类 view +4. D3D12 / Vulkan / OpenGL 三后端同时按正式接口设计 +5. 明确 backend capability 与错误回报，不允许 silent wrong image + +### 测试 + +1. `tests/RHI/unit` 增加 buffer SRV/UAV 创建测试 +2. descriptor set buffer binding 测试 +3. 三后端分别验证 buffer view 不再被误当成 texture view + +### 验收标准 + +1. 引擎能在不依赖 texture hack 的前提下，正式把 GPU buffer 绑定给 shader + +--- + +## 阶段 2：打通 Unity 风格 shader buffer 语义 + +### 目标 + +让 shader authoring / parser / reflection / artifact / runtime binding 能正式表达 Unity/HLSL 风格 buffer 资源。 + +### 任务 + +1. 扩展 shader 反射模型以支持 structured/raw buffer 资源 +2. 明确 `StructuredBuffer` 与 `ByteAddressBuffer` 的内部映射 +3. 扩展 runtime build、pass layout、descriptor metadata 对新资源类型的支持 +4. 明确 OpenGL 的 GLSL/SSBO 转译规则 +5. 严格禁止 volume 专属私有 shader 语法旁路 + +### 强约束 + +1. 不新增高层 `RawBuffer` 关键字 +2. 不新增 `MaterialPropertyType::StructuredBuffer / RawBuffer` +3. 如果 `Properties` 中尝试声明 buffer，必须报错或拒绝导入 + +### 测试 + +1. `tests/Resources/Shader` +2. `tests/Resources/Material` +3. `tests/Rendering/unit` 中的 pass layout / metadata 测试 +4. authoring 约束测试： + - Unity/HLSL 风格 buffer 声明可以被正确反射 + - 非法把 buffer 塞进 `Properties` 会被拒绝 + +### 验收标准 + +1. shader 资源描述层正式支持 buffer 资源 +2. 高层 authoring 语义仍保持 Unity 风格，不被底层分类污染 + +--- + +## 阶段 3：冻结 future C# buffer 绑定契约 + +### 目标 + +在 C# 模块尚未完全落地前，先把与本主线相关的 buffer 绑定语义冻结。 + +### 任务 + +1. 定义 native 侧可对应 future C# 的 buffer 绑定入口 +2. 约束 API 形状向 Unity 对齐： + - `Material.SetBuffer` + - `Shader.SetGlobalBuffer` + - `CommandBuffer.SetGlobalBuffer` +3. 明确 `VolumeField` 与 runtime buffer producer 的关系 +4. 保证未来托管层不会直接看到 RHI view 对象 + +### 测试 + +1. native 侧 binding metadata 测试 +2. material/runtime/global 三类 buffer 绑定路径测试 + +### 验收标准 + +1. 当前实现方向已经为 future C# 留好 Unity 风格接口落点 + +--- + +## 阶段 4：接入正式 VolumeField 资产链路 + +### 目标 + +让 `.nvdb` 成为项目里的正式资源，而不是 demo 私有文件。 + +### 任务 + +1. 新增 `ResourceType::VolumeField` +2. 新增 `Resources::VolumeField` +3. 新增 `VolumeFieldLoader` +4. 新增 `NanoVDBVolumeImporter` +5. `AssetDatabase` 识别 `.nvdb` +6. 生成 `main.xcvol` +7. 接入 reimport / dependency / cache / runtime load + +### 测试 + +1. `tests/Resources/Volume` +2. `tests/Core/Asset` +3. `.nvdb` 改动后的 reimport 测试 + +### 验收标准 + +1. `.nvdb` 可以像 mesh / material / shader 一样进入正式资产体系 + +--- + +## 阶段 5：接入组件、提取与 frame data + +### 目标 + +让场景系统知道“什么是可渲染的体积对象”。 + +### 任务 + +1. 新增 `VolumeRendererComponent` +2. 组件持有： + - `VolumeField` + - `Material` + - enable/disable + - 局部参数 override + - bounds / transform +3. `RenderSceneExtractor` 增加体积对象提取 +4. 新增 `VisibleVolumeItem` +5. `RenderSceneData.visibleVolumes` 接入 + +### 测试 + +1. 组件序列化 / 反序列化 +2. `VisibleVolumeItem` 提取测试 +3. frustum / bounds culling 与稳定顺序测试 + +### 验收标准 + +1. renderer 已经能从正式场景数据中拿到体积对象输入 + +--- + +## 阶段 6：BuiltinVolumetricPass 首次正式点亮 + +### 目标 + +在当前 renderer 正式链路中点亮第一版 `NanoVDB` 稀疏体积渲染。 + +### 任务 + +1. 新增 `BuiltinVolumetricPass` +2. pass 输入包括： + - camera + - depth + - scene color + - light / shadow + - volume buffer + - material parameters +3. D3D12 首次点亮 +4. 允许保留一条集成测试级别的 fullscreen debug path +5. 正式运行时路径收口到 proxy box / unit cube volume renderer + +### 强约束 + +1. fullscreen path 只能作为 bring-up / integration debug 路径 +2. 正式场景运行时不能停留在 fullscreen 方案 +3. 不得保留 `MVS` 风格直接文件加载或私有绑定路径 + +### 测试 + +1. `tests/Rendering/integration/volume_nanovdb_minimal` +2. GT 对比 +3. 中间调试图输出： + - `volume_mask_debug` + - `depth_debug` + - 必要时的 shadow debug + +### 验收标准 + +1. 正式 renderer 已经能稳定渲染一个来自 `.nvdb` 的体积对象 + +--- + +## 阶段 7：深度、阴影、合成规则收口 + +### 目标 + +把“能出图”收口成“行为正确”。 + +### 任务 + +1. 深度遮挡规则确定 +2. scene color 合成规则确定 +3. 主方向光与阴影采样接入 +4. transform 与 bbox 变换一致 +5. 步长、阴影采样步数、质量参数稳定化 + +### 测试 + +1. `volume_nanovdb_occlusion` +2. `volume_nanovdb_transform` +3. 光照方向变化的回归测试 + +### 验收标准 + +1. 画面行为能解释、能回归、能维护，不再只是 demo level + +--- + +## 阶段 8：多后端 rollout + +### 目标 + +把已在 D3D12 验证的正式能力推进到 Vulkan 与 OpenGL。 + +### 任务 + +1. Vulkan storage buffer 路线点亮 +2. OpenGL SSBO 路线点亮 +3. 明确 capability 检测与 fallback / disable 行为 +4. 补齐 backend-specific shader compile / runtime binding 回归 + +### 测试 + +1. 各后端统一 GT 对比 +2. backend-specific shader compile 测试 +3. buffer binding 回归测试 + +### 验收标准 + +1. 不是只有 D3D12 demo 可用，而是正式进入多后端 renderer 能力集合 + +--- + +## 阶段 9：Editor 最小工作流接入 + +### 目标 + +让这项能力进入项目工作流，而不是只能靠测试程序看图。 + +### 任务 + +1. `ProjectPanel` 识别 `.nvdb` +2. `Inspector` 显示 `VolumeField` metadata +3. `VolumeRendererComponent` inspector 编辑 +4. scene view / game view 中体积对象可见 +5. 资源缺失、编译失败、后端不支持时给出明确状态 + +### 验收标准 + +1. 用户可以从资产、组件、场景三个层面完整使用这项能力 + +--- + +## 11. 测试体系规划 + +### 11.1 单元测试 + +需要新增或扩展： + +1. `tests/RHI/unit` + - buffer SRV/UAV 创建 + - descriptor set buffer binding +2. `tests/Resources/Shader` + - Unity/HLSL 风格 buffer 声明解析 + - 非法 `Properties` buffer 声明拒绝 +3. `tests/Resources/Material` + - 材质参数 schema 与 runtime buffer 绑定边界 +4. `tests/Resources/Volume` + - `.nvdb -> .xcvol` + - metadata roundtrip + - reimport +5. `tests/Rendering/unit` + - `VisibleVolumeItem` 提取 + - `BuiltinVolumetricPass` 输入校验 + +### 11.2 集成测试 + +建议新增： + +1. `tests/Rendering/integration/volume_nanovdb_minimal` +2. `tests/Rendering/integration/volume_nanovdb_occlusion` +3. `tests/Rendering/integration/volume_nanovdb_transform` + +GT 规则： + +1. 使用单一 `GT.ppm` +2. 各后端输出都对同一张 `GT.ppm` 做对比 +3. 必要时保留中间调试图，但不把调试图当正式输出 + +### 11.3 性能与稳定性验收 + +至少记录： + +1. 单体积对象 frame time +2. 多体积对象 frame time +3. `.nvdb` 首次导入时长 +4. artifact 命中后的加载时长 + +--- + +## 12. 关键风险 + +### 12.1 最大风险不是算法，而是语义边界被做脏 + +如果一开始把 `StructuredBuffer / RawBuffer` 直接暴露成高层 authoring 概念，后面整个 shader/material/C# 体系都会被污染。 + +### 12.2 OpenGL 路线风险最高 + +原因： + +1. `StructuredBuffer` 到 GLSL/SSBO 的映射最容易出边角问题 +2. `PNanoVDB` 这种大 include 在 GLSL 转译路径上更容易暴露兼容性问题 + +### 12.3 fullscreen debug path 容易反客为主 + +它只能用于 bring-up 和集成测试，不能变成正式场景架构。 + +### 12.4 如果当前 shader 体系还没正式支持 Unity 风格 buffer 语义，这会成为主阻塞项 + +这不是额外问题，而是本主线的前置依赖。 + +--- + +## 13. 本阶段收口标准 + +当下面条件同时满足时，可以认为“稀疏体积渲染第一阶段正式完成”： + +1. `.nvdb` 已成为正式项目资源，可导入、可 reimport、可 artifact 化。 +2. 引擎 shader / runtime binding / RHI 已正式支持 Unity 风格 buffer 资源链路。 +3. 高层 authoring 没有引入任何体积专用自定义 buffer 语法。 +4. `VolumeRendererComponent` 能把 `VolumeField` 放进场景。 +5. `BuiltinVolumetricPass` 已作为正式 scene pass 存在。 +6. D3D12 至少已经在正式链路中点亮。 +7. 集成测试能稳定出图并做 GT 对比。 +8. future C# 的 `SetBuffer` 风格接口已经有明确落点，不会和当前底层设计冲突。 +9. 代码中不再依赖 `MVS/VolumeRenderer` 那套 D3D12 私有 demo 实现。 + +--- + +## 14. 一句话结论 + +这条主线的正确做法不是“先做出体积渲染再说”，而是“从第一天开始就按 Unity 风格的 shader/C# 语义设计 buffer 路径，把 `NanoVDB` 作为正式稀疏体积能力接入 renderer”，这样后面无论是 C# 层还是 SRP，都不会被今天的底层实现反噬。 diff --git a/docs/plan/Renderer下一阶段_CameraPostProcess描述层正式化计划_2026-04-06.md b/docs/plan/Renderer下一阶段_CameraPostProcess描述层正式化计划_2026-04-06.md deleted file mode 100644 index 49b7b467..00000000 --- a/docs/plan/Renderer下一阶段_CameraPostProcess描述层正式化计划_2026-04-06.md +++ /dev/null @@ -1,127 +0,0 @@ -# Renderer 下一阶段: Camera PostProcess 描述层正式化计划 - -日期: `2026-04-06` - -## 1. 阶段目标 - -在已经完成 runtime `SceneColor -> PostProcess -> FinalOutput` 主链收口的基础上， -把相机上的后处理配置从临时的 `ColorScale` 专用字段，提升为正式的描述层。 - -这一阶段只解决一件事: - -- `CameraComponent` 持有正式的 post-process pass 描述 -- `SceneRenderer` 通过工厂把描述翻译成 runtime pass sequence -- 旧的 `ColorScale` 接口继续兼容，旧场景序列化继续可读 - -## 2. 已完成内容 - -### 2.1 相机后处理描述层 - -已新增: - -- `CameraPostProcessPassType` -- `CameraPostProcessPassDesc` -- `CameraPostProcessStack` - -当前首个正式 builtin effect 仍然是: - -- `ColorScale` - -但它已经不再通过 `CameraComponent -> vector -> SceneRenderer if/for` 这种硬编码链路传递。 - -### 2.2 CameraComponent 正式化 - -已完成: - -- `CameraComponent` 内部存储迁移到 `CameraPostProcessStack` -- 新增通用接口: - - `GetPostProcessPasses` - - `SetPostProcessPasses` - - `AddPostProcessPass` - - `ClearPostProcessPasses` -- 旧接口继续保留: - - `SetColorScalePostProcessEnabled` - - `SetColorScalePostProcessScale` - - `SetColorScalePostProcessPasses` - - `GetColorScalePostProcessPasses` - -兼容规则: - -- 旧接口继续映射到 `ColorScale` 类型的描述 -- 新格式序列化写出正式 `postProcessPassN*` 字段 -- 反序列化同时兼容旧的 `colorScalePostProcess*` 字段 - -### 2.3 SceneRenderer 工厂翻译层 - -已完成: - -- 从 `SceneRenderer` 中移除 `ColorScale` 专用硬编码构造 -- 新增 `BuildCameraPostProcessPassSequence(...)` -- `SceneRenderer` 现在只关心: - - 读取相机的 `CameraPostProcessStack` - - 为 post-process 分配 source surface - - 调用工厂生成 `RenderPassSequence` - -这意味着后续增加新的 builtin camera post-process 时， -修改点已经收缩到描述层和工厂，而不是继续把分支堆进 `SceneRenderer`。 - -## 3. 验证结果 - -### 3.1 构建 - -已通过: - -- `cmake --build --preset debug --target components_tests rendering_unit_tests rendering_integration_camera_post_process_scene rendering_integration_post_process_scene -- /m:1` - -### 3.2 单元测试 - -已通过: - -- `components_tests --gtest_filter=CameraComponent_Test.*` -- `rendering_unit_tests --gtest_filter=SceneRenderer_Test.*:CameraRenderer_Test.*` - -覆盖点包括: - -- 新描述层 round-trip -- 旧 `ColorScale` 字段反序列化兼容 -- `SceneRenderer` 从 camera post-process stack 构建正式 request - -### 3.3 集成测试 - -已通过: - -- `rendering_integration_camera_post_process_scene` - - D3D12 - - OpenGL - - Vulkan -- `rendering_integration_post_process_scene` - - D3D12 - - OpenGL - - Vulkan - -说明: - -- `camera_post_process_scene` 验证 formal scene path -- `post_process_scene` 保留为 manual / low-level multi-pass 覆盖 - -## 4. 当前结论 - -这一阶段已经完成。 - -当前 renderer 在 camera post-process 这一层，已经从“单个效果的临时接线”升级为“正式描述 + 工厂翻译”的结构。 - -但现阶段仍然有两个边界: - -- 描述层虽然正式化了，但当前 builtin effect 仍只有 `ColorScale` -- editor / asset / material 侧还没有把 camera post-process 做成完整的资产化与配置面板体系 - -## 5. 下一步建议 - -下一步不要回头继续往 `SceneRenderer` 里塞特判，而应沿着下面的方向推进: - -1. 继续扩展 `CameraPostProcessPassDesc` - - 例如 tone mapping / exposure / gamma / final color transform -2. 让新的 builtin camera effect 继续只经过“描述层 + 工厂” -3. 等 shader/material 主线更稳定后，再决定 camera post-process 的资产化形式和 editor 配置入口 - -本阶段的核心收口标准已经满足，可以提交归档。 diff --git a/docs/plan/Scene选中描边彻底修复计划_2026-04-08.md b/docs/plan/Scene选中描边彻底修复计划_2026-04-08.md new file mode 100644 index 00000000..6d28102c --- /dev/null +++ b/docs/plan/Scene选中描边彻底修复计划_2026-04-08.md @@ -0,0 +1,291 @@ +# Scene 选中描边彻底修复计划 + +日期：2026-04-08 + +## 1. 文档定位 + +本文档只解决一个问题： + +- `Scene` 面板里，选中对象的描边效果需要达到稳定、可扩展、接近商业编辑器的质量。 + +本文档不讨论： + +- 层级面板右键菜单 +- 灯光 gizmo 图标 +- 运行时高亮 +- 游戏内选中反馈 + +## 2. 当前问题结论 + +当前实现不是“可见外轮廓提取”，而是“基于 object-id 的屏幕空间膨胀”。 + +现状链路如下： + +1. 主场景正常渲染。 +2. `BuiltinObjectIdPass` 把屏幕上最前面的物体 id 写入 `objectIdTexture`。 +3. `BuiltinObjectIdOutlinePass` 在全屏 shader 中检查当前像素周围是否存在“选中对象的 object-id”。 +4. 只要邻域中存在选中 object-id，当前像素就会被涂成 outline。 + +这个算法的根本缺陷是： + +- 它只知道“邻域里有没有选中对象”。 +- 它不知道“当前像素前面是不是别的物体挡住了选中对象”。 +- 它也不知道“这条边是可见外轮廓，还是选中大平面与前景遮挡物之间的内部接触边界”。 + +所以当选中一个大平面时，平面上方的 cube、sphere、capsule 这些前景物体边缘也会被错误描边。 + +这不是数据污染，也不是拾取错误，而是算法层面的必然结果。 + +## 3. 根因 + +根因可以归纳为两条： + +### 3.1 描边输入选错了 + +当前描边 pass 直接消费 `objectIdTexture`。 + +但 `objectIdTexture` 的职责本质上是： + +- 告诉编辑器“当前屏幕像素最前面的对象是谁”，用于 picking。 + +它不适合作为“选中描边”的唯一依据，因为它不包含： + +- 选中对象的可见 mask +- 选中对象自己的深度 +- 当前场景深度与选中对象深度之间的遮挡关系 + +### 3.2 描边算法缺少深度裁决 + +当前 outline shader 的判断规则是： + +- 当前像素不是选中对象 +- 但周围像素里存在选中对象 + +满足这两个条件就画 outline。 + +这套规则没有使用场景深度，也没有使用选中对象的可见性信息，因此无法区分： + +- 真正应该画的外轮廓 +- 不应该画的前景遮挡边界 + +## 4. 修复目标 + +本次彻底修复后的目标是： + +1. 选中大平面时，前景物体边缘不再被错误染成 outline。 +2. 选中普通 mesh 时，outline 仍然能稳定出现在可见外轮廓处。 +3. 被遮挡区域不画“伪外轮廓”。 +4. picking 与 selection outline 两套能力彻底解耦。 +5. 后续如果要做 Unity 风格的 x-ray 选中、被遮挡高亮、hover outline，可以在当前结构上继续扩展，而不是推倒重来。 + +## 5. 非目标 + +这次修复不做以下内容： + +1. 不做运行时游戏内高亮系统。 +2. 不做完整的“透视遮挡时仍显示淡色轮廓”的 x-ray 选中风格。 +3. 不借这次机会重写整个 editor render pipeline。 +4. 不继续在现有 `object-id-outline.shader` 上做只针对单个 case 的临时补丁。 + +## 6. 总体方案 + +正确方案是把“拾取”和“描边”拆开，改成： + +- `object id for picking` +- `visible selection mask for outline` +- `depth-aware outline composite` + +### 6.1 picking 继续走 object-id + +现有 `objectIdTexture` 继续只用于： + +- 场景点击选中 +- object-id readback + +它不再直接决定 outline 的视觉结果。 + +### 6.2 新增 selection mask pass + +新增一张仅服务于 outline 的 `selectionMaskTexture`。 + +它的规则是： + +1. 只渲染当前选中的对象。 +2. 渲染时绑定主场景已有的深度缓冲。 +3. 依赖深度测试，只把“真正可见的 selected fragment”写进 `selectionMaskTexture`。 + +这样得到的不是 picking id 图，而是“选中对象可见区域 mask”。 + +### 6.3 scene viewport 暴露深度 SRV + +为了做真正的 depth-aware composite，`Scene` viewport 需要同时持有： + +1. `depthView` +2. `depthShaderView` + +也就是说，Scene viewport 的深度纹理既要能作为 DSV 使用，也要能在全屏 composite shader 中作为 SRV 读取。 + +底层 RHI 已经具备这条能力，阴影缓存已有相同用法，因此这不是架构冒险，而是 viewport 资源层尚未接线。 + +### 6.4 重写 outline composite pass + +新的 outline shader 不再直接从 `objectIdTexture` 做邻域膨胀，而是读取： + +1. `selectionMaskTexture` +2. `sceneDepthTexture` + +必要时预留： + +3. `selectionDepthTexture` + +新的裁决规则应为： + +1. 中心像素若属于 selected mask，本像素不直接着色。 +2. 若邻域存在 selected mask，则该像素可能位于 selected 的边界附近。 +3. 只有在深度关系证明“当前像素不是更近的前景遮挡物”时，才允许输出 outline。 + +这一步的本质是： + +- 只画可见 selected 外轮廓。 +- 不把前景遮挡物边界误判为 selected outline。 + +## 7. 具体实施步骤 + +### Phase 1：补齐 viewport 资源 + +目标： + +- Scene viewport 持有可采样深度。 +- Scene viewport 持有单独的 selection mask render target。 + +需要修改： + +1. `editor/src/Viewport/ViewportHostRenderTargets.h` +2. 相关 viewport resource reuse / destroy / create 流程 + +新增资源建议： + +1. `depthShaderView` +2. `selectionMaskTexture` +3. `selectionMaskView` +4. `selectionMaskShaderView` +5. `selectionMaskState` + +验收标准： + +- Scene viewport 创建/销毁/复用逻辑能完整覆盖新资源。 +- 编译通过。 +- 不影响现有 Scene 视图展示。 + +### Phase 2：新增 selection mask pass + +目标： + +- 只把当前选中对象的可见区域写入 mask。 + +实现建议： + +1. 新建 editor 专用 `SelectionMaskPass`。 +2. 输入为选中对象 id 列表。 +3. 输出到 `selectionMaskTexture`。 +4. 渲染时绑定主场景同一套深度。 + +实现关键点： + +1. 这个 pass 的语义不是 picking。 +2. 它只关心“选中对象哪些像素当前可见”。 +3. 它不需要写 object id，只需要写统一 mask 值或选中组 id。 + +验收标准： + +- 选中对象时可以输出稳定的可见 mask。 +- 未选中时 pass 可被跳过。 + +### Phase 3：重写 outline composite + +目标： + +- outline 只出现在选中对象的可见外轮廓。 + +实现建议： + +1. 保留全屏 pass 形式。 +2. 输入从 `objectIdTexture` 改为 `selectionMaskTexture + depthShaderView`。 +3. 邻域检查继续保留，但结果必须经过深度裁决。 + +最低正确规则： + +1. 中心像素若是别的前景几何，且深度显著近于 selected 边界，不画 outline。 +2. 中心像素若是背景或更远表面，可以画 outline。 + +验收标准： + +1. 选中大平面时，前景 cube/sphere/capsule 边缘不再被错误描边。 +2. 选中单个 mesh 时，外轮廓仍连续稳定。 + +### Phase 4：移除旧耦合 + +目标： + +- 彻底消除 “outline 直接依赖 object-id picking 纹理” 这一旧逻辑。 + +需要完成： + +1. 旧 `object-id-outline.shader` 逻辑下线或重命名。 +2. `SceneViewportSelectionOutlinePass` 的输入契约改为新资源。 +3. 保证 `objectIdTexture` 仅服务于 picking。 + +验收标准： + +- 代码层不再存在“outline 直接读 object id 邻域并膨胀”的核心路径。 + +## 8. 测试计划 + +至少补以下回归验证： + +### 8.1 功能场景 + +1. 选中大平面，前面摆放 cube / sphere / capsule： + - 前景物体边缘不能被错误描边。 +2. 选中单个 cube，背景是地面： + - outline 能稳定显示在 cube 可见外轮廓上。 +3. 选中被部分遮挡的物体： + - 只允许可见区域出现 outline。 +4. 多选相邻物体： + - outline 不串边，不污染第三方前景物体。 + +### 8.2 回归类型 + +1. shader 资源加载测试 +2. render plan 接线测试 +3. pass 构建与资源存在性测试 +4. 视口级人工验证截图 + +## 9. 风险与边界 + +### 9.1 风险 + +1. 仅使用 `sceneDepth + selectionMask` 可能仍有少数边界 case 需要 `selectionDepth` 才能更稳。 +2. Scene viewport 新增 render target 后，资源管理和状态切换复杂度会上升。 +3. 若后续要兼容 Vulkan / OpenGL，需要同步确认深度 SRV 路径与资源状态语义。 + +### 9.2 边界 + +本计划的第一目标不是“做最炫的 outline”，而是： + +- 先把语义做对 +- 再把视觉做稳 + +只要还在复用 picking 的 `objectIdTexture` 直接做 outline，问题就不可能彻底解决。 + +## 10. 最终结论 + +这次 bug 不能靠继续修补当前 `object-id-outline.shader` 解决。 + +彻底方案必须满足三点： + +1. picking 与 outline 解耦 +2. 选中对象生成独立可见 mask +3. outline composite 引入深度裁决 + +只有这样，Scene 视图选中描边才会从“屏幕空间膨胀特效”升级为“真正可用的编辑器轮廓系统”。 diff --git a/docs/plan/XCUI_Phase_Status_2026-04-05.md b/docs/plan/used/XCUI_Phase_Status_2026-04-05.md similarity index 100% rename from docs/plan/XCUI_Phase_Status_2026-04-05.md rename to docs/plan/used/XCUI_Phase_Status_2026-04-05.md diff --git a/docs/plan/xcui-subplans/README.md b/docs/plan/xcui-subplans/README.md deleted file mode 100644 index 9fcd89ad..00000000 --- a/docs/plan/xcui-subplans/README.md +++ /dev/null @@ -1,38 +0,0 @@ -# XCUI Parallel Subplans - -基于 [XCUI完整架构设计与执行计划](../XCUI完整架构设计与执行计划.md) 的并行拆分版本。 - -当前建议： -- `Phase 0` 由主线继续推进，目标是把 ImGui 从 `engine/editor` 公共边界剥离出来。 -- 其他人不要再去碰 `Phase 0` 正在修改的边界文件，优先认领下面的独立 subplan。 -- 每个人只领一个 subplan，按“自己负责的目录”做增量开发，避免跨 subplan 修改核心契约。 - -推荐并行顺序： -- 可以立即开始：`03` `06` -- 建议在 Core/Backend 契约初步稳定后启动：`07` `08` `09` - -已完成归档： -- `Subplan-01`：已于 `2026-04-04` 归档到 [../used/XCUI_Subplan-01_Core_Tree_State_完成归档_2026-04-04.md](../used/XCUI_Subplan-01_Core_Tree_State_完成归档_2026-04-04.md) -- `Subplan-02`：已于 `2026-04-04` 归档到 [../used/XCUI_Subplan-02_LayoutEngine_完成归档_2026-04-04.md](../used/XCUI_Subplan-02_LayoutEngine_完成归档_2026-04-04.md) -- `Subplan-04`：已于 `2026-04-04` 归档到 [../used/XCUI_Input_Focus_Shortcut_Subplan_完成归档_2026-04-04.md](../used/XCUI_Input_Focus_Shortcut_Subplan_完成归档_2026-04-04.md) -- `Subplan-05`：已于 `2026-04-04` 归档到 [../used/XCUI_Subplan-05_ImGui_Transition_Backend_完成归档_2026-04-04.md](../used/XCUI_Subplan-05_ImGui_Transition_Backend_完成归档_2026-04-04.md) - -统一协作约束： -- 共享契约文件尽量只由主线或对应 owner 修改。 -- 新模块优先放到新目录，不要把 XCUI 新逻辑继续塞进旧的 ImGui helper。 -- 每个 subplan 都要自带最小测试或样例，不接受只落抽象不落验证。 -- 每个 subplan 完成后，至少产出一个可被其他 subplan 直接依赖的稳定入口。 - -共享高风险边界： -- `engine/include/XCEngine/UI/` -- `engine/include/XCEngine/Core/Layer.h` -- `engine/include/XCEngine/Core/LayerStack.h` -- `editor/src/Application.cpp` -- `editor/src/Viewport/IViewportHostService.h` - -Subplan 列表： -- `Subplan-03`：XCUI Style / Theme / Token -- `Subplan-06`：XCUI Markup / Import / Hot Reload -- `Subplan-07`：XCUI Schema Inspector / PropertyGrid -- `Subplan-08`：XCUI DockHost / Menu / Panel Shell -- `Subplan-09`：XCUI ViewportSlot / Editor Integration diff --git a/docs/plan/xcui-subplans/Subplan-04_XCUI-Input-Focus-Shortcut.md b/docs/plan/xcui-subplans/Subplan-04_XCUI-Input-Focus-Shortcut.md deleted file mode 100644 index ab3dc121..00000000 --- a/docs/plan/xcui-subplans/Subplan-04_XCUI-Input-Focus-Shortcut.md +++ /dev/null @@ -1,53 +0,0 @@ -# Subplan 04：XCUI Input / Focus / Shortcut - -状态： - -- 已于 `2026-04-04` 完成当前 subplan 定义边界内的实现。 -- 已归档到： - [../used/XCUI_Input_Focus_Shortcut_Subplan_完成归档_2026-04-04.md](../used/XCUI_Input_Focus_Shortcut_Subplan_完成归档_2026-04-04.md) - -目标： - -- 建立 XCUI 的输入事件、焦点流转和快捷键分发模型。 -- 让输入不再直接写死在 ImGui 调用点里。 - -负责人边界： - -- 负责 `engine/src/UI/Input/`。 -- 负责 pointer / keyboard / focus / command dispatch 的抽象。 -- 不负责平台消息采集本身。 - -建议目录： - -- `engine/include/XCEngine/UI/Input/` -- `engine/src/UI/Input/` -- `tests` 中 input/focus 测试 - -前置依赖： - -- 依赖 `Subplan 01` 的 tree 和 hit-test 基础契约。 -- 需要和 `Subplan 05` 对齐 adapter 输入桥接接口。 - -现在就可以先做的内容： - -- 设计 `UIInputEvent` 丰富版本 -- 设计 focus path / active path / capture path -- 设计 shortcut scope：global / window / panel / widget -- 写 focus 切换和冒泡/捕获测试 - -明确不做： - -- 不做 Win32 原生消息处理细节 -- 不做具体文本输入 widget - -交付物： - -- XCUI 输入分发器 -- 焦点管理器 -- 快捷键绑定与分发机制 - -验收标准： - -- 可以确定事件从哪里来、往哪里走、谁消费 -- 焦点切换规则稳定可测 -- 快捷键系统可与 editor shell 直接对接 diff --git a/docs/used/API文档实时同步任务池_2026-04-03.md b/docs/used/API文档实时同步任务池_2026-04-03.md new file mode 100644 index 00000000..6815960c --- /dev/null +++ b/docs/used/API文档实时同步任务池_2026-04-03.md @@ -0,0 +1,776 @@ +# API文档实时同步任务池（2026-04-03，第三轮） + +## 文档定位 + +这份任务池接替已归档的第二轮计划： + +- `docs/plan/used/API文档实时同步任务池_2026-04-03_第二轮归档.md` + +前两轮已经完成的重点包括： + +- canonical API 目录结构收口 +- 大批缺页补齐 +- 多轮模板页清理与内容重写 +- 结构层审计修复到全绿 + +第三轮不再以“结构补齐”为主，而是专门处理“源码/测试已经变化，但 API 文档内容还没有跟上”的增量漂移。 + +## 当前复核快照 + +- 最近一次结构审计时间：`2026-04-07 01:26:32` +- 审计命令：`python -B docs/api/_tools/audit_api_docs.py` +- 当前结果： + - `Public headers: 304` + - `Editor source headers: 142` + - `Valid header refs (canonical): 304` + - `Invalid header refs: 0` + - `Invalid source refs: 0` + - `Valid source refs (Editor canonical): 142` + - `Broken .md links: 0` + - `Missing directory index pages: 0` + - `Stale canonical doc tokens: 0` + - `Stale editor doc tokens: 0` + - `Stale editor canonical pages: 0` + +这说明当前 canonical public header 覆盖与全部 Editor source-backed API 都已恢复全绿；此前集中在 `engine/include/XCEngine/UI/**` 的缺口已经收口完成。 + +### 已复核、暂不新开任务的区域 + +- `Resources/Material` / `RenderMaterialUtility` / `BuiltinForwardPipeline` +- `Components/MeshFilterComponent` / `MeshRendererComponent` +- `Scene` 中 builtin mesh / material 路径 round-trip +- `Components/GameObject` 辅助访问器与层级辅助页 + +这些区域本轮已对照当前源码和测试抽查，暂时没有发现新的明确失配。 + +## 认领规则 + +- 一次只认领 `1` 个任务块。 +- 先把 `状态` 改成 `DOING`，再写 `认领人`。 +- 只允许修改自己任务块声明的 `写入范围`。 +- 所有改动都必须基于“当前头文件 + 当前实现 + 当前测试 + 当前真实调用链”。 +- 如果需要同步 `_guides` 或模块总览页，必须在对应任务块内明确列出，避免多人撞写。 +- 做完后必须补一次最小复核，至少确认相关链接和交叉引用没有坏掉。 + +## 任务池 + +## T01 Core / Asset `AssetDatabase` 显式重导入接口补页 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P0` +- 写入范围: + - `docs/api/XCEngine/Core/Asset/AssetDatabase/**` +- 主要源码依据: + - `engine/include/XCEngine/Core/Asset/AssetDatabase.h` + - `engine/src/Core/Asset/AssetDatabase.cpp` + - `tests/Core/Asset/test_resource_manager.cpp` +- 已确认问题: + - 头文件已新增 `TryGetImportableResourceType()`、`ReimportAsset()`、`ReimportAllAssets()`，但 canonical 目录下没有对应方法页。 + - `AssetDatabase.md` 的公开方法表仍停在旧集合，没有把“可导入类型探测 / 单资产重导入 / 批量重导入”纳入公开能力。 + - `kCurrentImporterVersion` 已升到 `5`，总览页需要同步当前 importer 版本口径。 +- 产出要求: + - 新增 `TryGetImportableResourceType.md`、`ReimportAsset.md`、`ReimportAllAssets.md`。 + - 更新 `AssetDatabase.md`，必要时同步 `ResolvedAsset.md` 的交叉引用。 + - 文档必须写清以下真实边界： + - 只接受项目 `Assets/...` 内、存在且非目录的 source asset。 + - `TryGetImportableResourceType()` 只返回当前 importer 的 primary `ResourceType`；`Unknown` 直接失败。 + - `ReimportAsset()` 会重建单个 artifact、更新 source/artifact DB，并返回可直接消费的 `ResolvedAsset`。 + - `ReimportAllAssets()` 会遍历全部可导入 source record；单个条目失败不会中断全量循环，但最终返回总体成功位。 + +## T02 Core / Asset `AssetImportService` Library 工具接口与 `ImportedAsset` 语义同步 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P0` +- 写入范围: + - `docs/api/XCEngine/Core/Asset/AssetImportService/**` +- 主要源码依据: + - `engine/include/XCEngine/Core/Asset/AssetImportService.h` + - `engine/src/Core/Asset/AssetImportService.cpp` + - `tests/Core/Asset/test_resource_manager.cpp` +- 已确认问题: + - 缺少 `ClearLibraryCache.md`、`ReimportAllAssets.md`、`ReimportAsset.md`、`TryGetImportableResourceType.md`。 + - `AssetImportService.md` 还没有把这批显式工具接口纳入生命周期和能力说明。 + - `ImportedAsset` 页虽然已存在，但需要按当前 `ConvertResolvedAsset()` 口径复核 `runtimeLoadPath`、`artifactDirectory`、`mainLocalID` 和成功路径语义。 +- 产出要求: + - 新增缺失方法页，并更新 `AssetImportService.md`、必要时同步 `ImportedAsset.md` 与 `EnsureArtifact.md`。 + - 文档必须写清以下真实边界： + - `ClearLibraryCache()` 会关停数据库、删除整个 `Library` 目录、再重新初始化；它本身不会批量重导入所有资产。 + - `RebuildLibraryCache()` 等于 `ClearLibraryCache() + ReimportAllAssets()`。 + - `ReimportAsset()` 会先 `Refresh()`，再强制重导入指定路径，返回 `ImportedAsset`。 + - `TryGetImportableResourceType()` 只是服务层转发；项目根无效时必须返回失败并把输出设为 `Unknown`。 + - `AssetImportService_Test.RebuildLibraryCacheKeepsStableAssetRefs` 证明：重建 `Library` 不应破坏现有 `.meta` 驱动的稳定 `AssetRef`。 + +## T03 Core / Asset `ResourceManager` 项目资产工具入口同步 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P0` +- 写入范围: + - `docs/api/XCEngine/Core/Asset/ResourceManager/**` +- 主要源码依据: + - `engine/include/XCEngine/Core/Asset/ResourceManager.h` + - `engine/src/Core/Asset/ResourceManager.cpp` + - `tests/Core/Asset/test_resource_manager.cpp` +- 已确认问题: + - 缺少 `CanReimportProjectAsset.md`、`ReimportProjectAsset.md`、`ClearProjectLibraryCache.md`。 + - `ResourceManager.md` 还没有覆盖当前项目资产工具入口，也没有把这些接口和 `UnloadAll()` / `ProjectAssetIndex::RefreshFrom()` 的关系写清。 + - `RebuildProjectAssetCache.md`、`GetProjectLibraryRoot.md` 需要和新接口形成正确对比与交叉链接。 +- 产出要求: + - 新增缺失方法页，更新 `ResourceManager.md`，必要时补交叉链接。 + - 文档必须写清以下真实边界： + - 这批接口都要求 `m_resourceRoot` 非空；否则直接失败。 + - `CanReimportProjectAsset()` 只做“当前路径是否可导入”的无副作用判断。 + - `ReimportProjectAsset()` 会先 `UnloadAll()`，再重导入单路径资产，随后刷新 `ProjectAssetIndex`，成功时补记 `RememberResolvedPath(...)`。 + - `ClearProjectLibraryCache()` 会先卸载运行时资源，再清空 `Library`，然后刷新 snapshot，但不会自动批量重导入。 + - `ResourceManager_Test.ReimportProjectAssetBuildsArtifactForSelectedPath` 与 `RebuildProjectAssetCacheRefreshesLookupState` 是当前最直接的行为锚点。 + +## T04 Scripting / Mono `[SerializeField] private` 字段发现与持久化语义同步 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P0` +- 写入范围: + - `docs/api/XCEngine/Scripting/Mono/Mono.md` + - `docs/api/XCEngine/Scripting/Mono/MonoScriptRuntime/**` + - `docs/api/_guides/Scripting/Scripting-Runtime-And-Field-Model.md` + - `docs/api/_guides/Scripting/Project-Script-Assembly-And-Field-Sync.md` +- 主要源码依据: + - `engine/include/XCEngine/Scripting/Mono/MonoScriptRuntime.h` + - `engine/src/Scripting/Mono/MonoScriptRuntime.cpp` + - `managed/XCEngine.ScriptCore/SerializeField.cs` + - `managed/GameScripts/FieldMetadataProbe.cs` + - `managed/GameScripts/SerializeFieldProbe.cs` + - `tests/Scripting/test_mono_script_runtime.cpp` + - `tests/Scripting/test_project_script_assembly.cpp` +- 已确认问题: + - `Mono.md`、`TryGetClassFieldMetadata.md`、两篇 scripting guide 仍在沿用“只收录 public 实例字段”的旧口径。 + - 当前真实实现已经变成： + - 过滤掉 `static` / `literal` / `init-only` + - 然后接受“public 字段”或“标了 `[SerializeField]` 的 private 字段” + - 最后再按支持类型过滤 + - 测试已经明确覆盖 `HiddenFlag`、`HiddenCounter`、`HiddenEnabled` 这类 `[SerializeField] private` 字段的元数据发现、默认值读取、运行时写回与场景 round-trip。 + - 未标 `[SerializeField]` 的 private 字段仍应保持忽略，但当前文档没有把这条边界讲清。 +- 产出要求: + - 至少同步 `Mono.md`、`MonoScriptRuntime.md`、`TryGetClassFieldMetadata.md`、`TryGetClassFieldDefaultValues.md`。 + - 两篇 guide 需要补上 Unity 风格设计解释： + - 为什么支持 `[SerializeField] private` + - 这样做对 Inspector、字段持久化、重构安全性有什么好处 + - 哪些 private 字段仍不会进序列化层 + - 文档必须明确当前排除项： + - `static` + - `const/literal` + - `readonly/init-only` + - 不支持的字段类型 + - 未标 `[SerializeField]` 的 private 字段 + +## T05 Editor / Viewport `SceneViewportOverlayBuilder` provider-registry 口径同步 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P1` +- 写入范围: + - `docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayBuilder/**` + - `docs/api/XCEngine/Editor/Viewport/Viewport.md` + - `docs/api/XCEngine/Editor/Viewport/ViewportHostService/**` +- 主要源码依据: + - `editor/src/Viewport/SceneViewportOverlayBuilder.h` + - `editor/src/Viewport/SceneViewportOverlayBuilder.cpp` + - `editor/src/Viewport/SceneViewportOverlayProviders.h` + - `editor/src/Viewport/SceneViewportOverlayProviders.cpp` + - `editor/src/Viewport/ViewportHostService.h` + - `tests/Editor/test_scene_viewport_overlay_providers.cpp` +- 已确认问题: + - `SceneViewportOverlayBuilder.md` 与 `Build.md` 仍沿用旧版“静态 / 无状态 / 单体 builder”口径，没有同步当前实例 builder + provider registry 模型。 + - `SceneViewportOverlayBuilder` 目录缺少 `Constructor.md` 与 `GetProviderRegistry.md`，导致新公开入口没有 canonical 页面。 + - `Viewport.md`、`ViewportHostService.md` 与 `SceneView-Overlay-Frame-Data.md` 仍把基础 editor overlay 的来源写成 `SceneViewportOverlayBuilder::Build(...)`，没有同步宿主当前持有成员 `m_sceneViewportOverlayBuilder` 且默认聚合 camera / light provider 的事实。 +- 完成记录: + - 已重写 `SceneViewportOverlayBuilder.md` 与 `Build.md`，改成当前实例 builder + registry 分发语义。 + - 已新增 `Constructor.md` 与 `GetProviderRegistry.md`。 + - 已同步 `Viewport.md`、`ViewportHostService.md` 与 `SceneView-Overlay-Frame-Data.md` 的上层调用链表述。 + - 已重新运行 `python -B docs/api/_tools/audit_api_docs.py`，并确认 `Broken .md links: 0`、`Stale editor doc tokens: 0`、`Stale editor canonical pages: 0`。 + +## T06 Editor / Viewport HUD / interaction-actions / canonical overlay-state 口径同步 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P1` +- 写入范围: + - `docs/api/XCEngine/Editor/Viewport/Viewport.md` + - `docs/api/XCEngine/Editor/Viewport/IViewportHostService/**` + - `docs/api/XCEngine/Editor/Viewport/ViewportHostService/**` + - `docs/api/XCEngine/Editor/Viewport/SceneViewportHudOverlay/**` + - `docs/api/XCEngine/Editor/Viewport/SceneViewportInteractionResolver/**` + - `docs/api/XCEngine/Editor/Viewport/SceneViewportInteractionActions/**` + - `docs/api/XCEngine/Editor/Viewport/SceneViewportTransformGizmoCoordinator/**` + - `docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayBuilder/**` + - `docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/**` + - `docs/api/XCEngine/Editor/Viewport/SceneViewportEditorOverlayData/**` + - `docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayHitTester/**` + - `docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportEditorOverlayPass/**` + - `docs/api/XCEngine/Editor/panels/SceneViewPanel/**` + - `docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayHandleBuilder/**` + - `docs/api/XCEngine/Editor/Viewport/SceneViewportMoveGizmo/**` + - `docs/api/XCEngine/Editor/Viewport/SceneViewportRotateGizmo/**` + - `docs/api/XCEngine/Editor/Viewport/SceneViewportScaleGizmo/**` +- 主要源码依据: + - `editor/src/Viewport/SceneViewportHudOverlay.h` + - `editor/src/Viewport/SceneViewportHudOverlay.cpp` + - `editor/src/Viewport/SceneViewportInteractionResolver.h` + - `editor/src/Viewport/SceneViewportInteractionResolver.cpp` + - `editor/src/Viewport/SceneViewportInteractionActions.h` + - `editor/src/Viewport/SceneViewportInteractionActions.cpp` + - `editor/src/Viewport/SceneViewportTransformGizmoCoordinator.h` + - `editor/src/Viewport/SceneViewportTransformGizmoCoordinator.cpp` + - `editor/src/Viewport/IViewportHostService.h` + - `editor/src/Viewport/ViewportHostService.h` + - `editor/src/Viewport/SceneViewportOverlayBuilder.h` + - `editor/src/Viewport/SceneViewportOverlayProviders.h` + - `editor/src/Viewport/SceneViewportOverlayProviders.cpp` + - `editor/src/Panels/SceneViewPanel.cpp` + - `editor/src/Viewport/SceneViewportOverlayHandleBuilder.h` + - `editor/src/Viewport/SceneViewportMoveGizmo.h` + - `editor/src/Viewport/SceneViewportRotateGizmo.h` + - `editor/src/Viewport/SceneViewportScaleGizmo.h` + - `tests/Editor/test_scene_viewport_interaction_actions.cpp` + - `tests/Editor/test_scene_viewport_transform_gizmo_coordinator.cpp` + - `tests/Editor/test_scene_viewport_interaction_resolver.cpp` + - `tests/Editor/test_scene_viewport_overlay_providers.cpp` +- 已确认问题: + - `IViewportHostService` / `ViewportHostService` / `SceneViewPanel` 文档仍在使用 `GetSceneViewInteractionOverlayFrameData(...)` 与 `SetSceneViewTransientTransformGizmoOverlayData(...)` 的旧双轨口径，但当前真实接口只剩 `SetSceneViewTransformGizmoOverlayState(...)` + `GetSceneViewEditorOverlayFrameData(...)`。 + - `SceneViewportOverlayBuilder` / `SceneViewportOverlayProviders` 文档没有同步当前 optional `transformGizmoOverlayState`、`CreateSceneViewportTransformGizmoOverlayProvider()`，以及默认 registry 已注册 camera / light / transform gizmo provider 的事实。 + - `SceneViewportEditorOverlayData` / `SceneViewportEditorOverlayPass` / `SceneViewportOverlayHitTester` 文档仍把 canonical frame 当成“仅世界线和图标”，没有同步 `screenTriangles` 与 `handleRecords` 已并入统一 frame data。 + - 缺少 `SceneViewportInteractionActions.h` 的 canonical 目录，导致交互动作规范层没有文档入口。 + - 缺少 `SceneViewportTransformGizmoCoordinator.h` 的 canonical 目录，且 `SceneViewPanel` 文档没有同步当前 overlay submission / lifecycle command helper 链路。 + - move / rotate / scale gizmo 的 draw-data 与 state-query 页面仍在传播“面板直接把 `GetDrawData()` 变成临时 render overlay”的旧口径，未同步统一 gizmo state + provider 模式。 +- 完成记录: + - 已新增 `SceneViewportInteractionActions/**`，补齐 hover-state / click-action / dispatch API 页面。 + - 已新增 `SceneViewportTransformGizmoCoordinator/**`，补齐 overlay submission 与 gizmo lifecycle command 页面。 + - 已重写 `Viewport.md`、`IViewportHostService/**`、`ViewportHostService/**`、`SceneViewPanel/**`，统一到当前 `SetSceneViewTransformGizmoOverlayState(...)` + canonical `SceneViewportOverlayFrameData` 链路。 + - 已同步 `SceneViewportOverlayBuilder/**`、`SceneViewportOverlayProviders/**`、`SceneViewportEditorOverlayData/**`、`SceneViewportOverlayHitTester/**` 与 `SceneViewportEditorOverlayPass/**` 到当前 provider-registry + 统一 gizmo state 架构。 + - 已同步 move / rotate / scale gizmo 的 draw-data / state-query 页面到当前统一 state 消费口径。 + - 已重新运行 `python -B docs/api/_tools/audit_api_docs.py`，结果为：`Valid source refs (Editor canonical): 129`、`Invalid header refs: 0`、`Invalid source refs: 0`、`Broken .md links: 0`、`Stale editor canonical pages: 0`。 + +## T07 Scripting guide / 项目脚本程序集测试输出目录口径修正 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P1` +- 写入范围: + - `docs/api/_guides/Scripting/Project-Script-Assembly-And-Field-Sync.md` +- 主要源码依据: + - `managed/CMakeLists.txt` + - `tests/Scripting/CMakeLists.txt` + - `tests/Scripting/test_project_script_assembly.cpp` +- 已确认问题: + - guide 仍把 `tests/Scripting/test_project_script_assembly.cpp` 描述成“直接把 `assemblyDirectory` 指向 `project/Library/ScriptAssemblies`”。 + - 当前真实测试口径已经改成优先使用 `XCENGINE_TEST_PROJECT_MANAGED_OUTPUT_DIR`，由 `xcengine_test_project_managed_assemblies` target 提供测试专用输出目录；未配置时 fallback 到 `build/managed/ProjectScriptAssemblies`。 + - `project/Library/ScriptAssemblies/` 仍是 editor/runtime 项目程序集的真实输出目录，但它和测试专用输出目录不能混写成同一个概念。 +- 完成记录: + - 已改写 `Project-Script-Assembly-And-Field-Sync.md`，把“真实项目输出目录”和“测试专用输出目录”拆开描述。 + - 已明确 `test_project_script_assembly.cpp` 验证的是“项目 `Assets/**/*.cs` 被编译成可发现的 `GameScripts.dll`”这条链路，而不是直接依赖工作树里的 `project/Library/ScriptAssemblies/` 快照。 + - 已重新运行 `python -B docs/api/_tools/audit_api_docs.py`，结果为：`Public headers: 244`、`Editor source headers: 129`、`Broken .md links: 0`、`Stale canonical doc tokens: 0`、`Stale editor canonical pages: 0`。 + +## T08 Rendering / `RenderMaterialUtility` builtin-pass 元数据与资源绑定契约补页 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P1` +- 写入范围: + - `docs/api/XCEngine/Rendering/RenderMaterialUtility/**` + - `docs/api/XCEngine/Rendering/Pipelines/BuiltinForwardPipeline/**` + - `docs/api/XCEngine/Rendering/Passes/BuiltinObjectIdPass/**` +- 主要源码依据: + - `engine/include/XCEngine/Rendering/RenderMaterialUtility.h` + - `engine/src/Rendering/Pipelines/BuiltinForwardPipeline.cpp` + - `engine/src/Rendering/Passes/BuiltinObjectIdPass.cpp` + - `tests/Rendering/unit/test_builtin_forward_pipeline.cpp` + - `tests/Rendering/unit/test_render_scene_extractor.cpp` +- 已确认问题: + - `RenderMaterialUtility.h` 当前已经公开 `BuiltinMaterialPass`、binding-plan struct、legacy fallback 绑定构造和 builtin pass 元数据匹配 helper，但 canonical 文档树仍只覆盖旧的材质解析 / render-state 子集。 + - `MaterialConstantPayloadView` 与 `ResolveSchemaMaterialConstantPayload()` 文档仍停留在“只有 `data + size`”的旧口径，没有同步当前 `layout` 视图和 `layout.size == size` 的有效性约束。 + - `BuiltinForwardPipeline` 与 `BuiltinObjectIdPass` 文档虽然已经写到 explicit resource contract，但还没有把 canonical 入口回链到 `RenderMaterialUtility` 的 binding-plan helper。 +- 完成记录: + - 已新增 builtin pass 元数据 / 资源绑定契约页面，覆盖 `BuiltinMaterialPass`、`BuiltinPassResourceBindingPlan`、`TryBuildBuiltinPassResourceBindingPlan()`、legacy fallback 绑定构造与 shader-pass 元数据匹配 helper。 + - 已新增 `MaterialConstantLayoutView.md`、`FindShaderPropertyBySemantic.md`，并同步 `MaterialConstantPayloadView.md`、`ResolveSchemaMaterialConstantPayload.md` 到当前 layout-aware 语义。 + - 已重写 `RenderMaterialUtility.md` 的公开类型 / 函数索引，把 builtin pass 规范化与 binding-plan 契约纳入模块总览。 + - 已同步 `BuiltinForwardPipeline.md` 与 `BuiltinObjectIdPass.md` 到当前 explicit binding-plan + legacy fallback 口径。 + +## T09 Rendering / `RenderMaterialUtility` 顶层 helper completeness 补页 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P1` +- 写入范围: + - `docs/api/XCEngine/Rendering/RenderMaterialUtility/**` +- 主要源码依据: + - `engine/include/XCEngine/Rendering/RenderMaterialUtility.h` + - `engine/src/Rendering/Pipelines/BuiltinForwardPipeline.cpp` + - `tests/Rendering/unit/test_builtin_forward_pipeline.cpp` + - `tests/Rendering/unit/test_render_scene_extractor.cpp` +- 已确认问题: + - `RenderMaterialUtility.h` 的顶层公开符号里，`IsForwardPassName()` 等 pass-name alias helper、`ToRHI*` 状态映射 helper，以及 `MaterialRenderStateHash` 仍无对应 canonical 页面。 + - `RenderMaterialUtility.md` 的索引也没有把这批顶层 helper 纳入公开函数 / 类型列表，导致文档目录和实际公开符号仍有一层颗粒度缺口。 +- 完成记录: + - 已新增 `IsForwardPassName.md`、`IsUnlitPassName.md`、`IsDepthOnlyPassName.md`、`IsShadowCasterPassName.md`、`IsObjectIdPassName.md`。 + - 已新增 `ToRHICullMode.md`、`ToRHIComparisonFunc.md`、`ToRHIBlendFactor.md`、`ToRHIBlendOp.md` 与 `MaterialRenderStateHash.md`。 + - 已同步 `RenderMaterialUtility.md`，把这批 helper 和 hash functor 纳入模块索引。 + - 已对照 `RenderMaterialUtility.h` 的顶层公开类型 / 函数名，确认当前 canonical 页已全覆盖。 + +## T10 Active API docs / 测试路径大小写按真实目录统一 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P1` +- 写入范围: + - `docs/api/_guides/**` + - `docs/api/XCEngine/**` +- 主要源码依据: + - `tests/` +- 已确认问题: + - 活跃文档里曾残留 `tests/core/...`、`tests/math/...`、`tests/scripting/...` 这类小写路径。 + - 当前工作树真实目录名是 `tests/Core/`、`tests/Core/Math/`、`tests/Scripting/`；继续沿用小写写法会让文档和工程现实脱节。 + - 这类问题与此前已收口的 `tests/Editor/` 一样，属于 Windows 工作树里最容易被忽略、但会持续制造噪音的路径口径漂移。 +- 完成记录: + - 已把活跃 guide 与 canonical API 文档中的 `tests/Core/...`、`tests/Core/Math/...`、`tests/Scripting/...` 统一改成真实目录大小写。 + - 本轮只收口活跃文档；`docs/plan/used/`、`docs/used/` 等归档材料继续保留历史写法。 + +## T11 Editor / Viewport 新增 header helper 补页 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P1` +- 写入范围: + - `docs/api/XCEngine/Editor/Viewport/Viewport.md` + - `docs/api/XCEngine/Editor/Viewport/SceneViewportEditorModes/**` + - `docs/api/XCEngine/Editor/Viewport/SceneViewportInteractionFrame/**` + - `docs/api/XCEngine/Editor/Viewport/SceneViewportNavigation/**` + - `docs/api/_meta/rebuild-status.md` +- 主要源码依据: + - `editor/src/Viewport/SceneViewportEditorModes.h` + - `editor/src/Viewport/SceneViewportInteractionFrame.h` + - `editor/src/Viewport/SceneViewportNavigation.h` + - `editor/src/Panels/SceneViewPanel.cpp` +- 已确认问题: + - 工作树里新增了 `SceneViewportEditorModes.h`、`SceneViewportInteractionFrame.h`、`SceneViewportNavigation.h` 三个 editor source header，但 canonical 文档树还没有对应目录页。 + - `Viewport.md` 也没有把这三块新 helper 纳入当前职责拆分，导致 Scene View 交互装配和导航状态管理的真实入口在模块总览里缺席。 +- 完成记录: + - 已新增 `SceneViewportEditorModes/SceneViewportEditorModes.md`，收口 tool / pivot / transform-space 三类模式枚举。 + - 已新增 `SceneViewportInteractionFrame/SceneViewportInteractionFrame.md`，补齐 tool state、frame geometry、interaction frame state 与 resolve request 装配语义。 + - 已新增 `SceneViewportNavigation/SceneViewportNavigation.md`，补齐快捷键、look/pan 导航、capture flags 与 `SceneViewportInput` 构建逻辑。 + - 已补齐 `BuildSceneViewportTransformGizmoOverlayState.md`，并重写 `SceneViewPanel/**`、`SceneViewportOverlayHandleBuilder/**` 与 `SceneView-Interaction-And-Gizmo-Model.md` 的残留旧口径。 + - 已顺手修复 `BuildSceneViewportGridPassData.md` 指向旧页名的坏链接。 + - 已重新运行 `python -B docs/api/_tools/audit_api_docs.py`，确认 `Editor source headers: 133`、`Valid source refs (Editor canonical): 133`、`Invalid source refs: 0`、`Broken .md links: 0`。 + +## T12 Editor / Viewport `SceneViewportInteractionFrame` Phase 5G focus 与 presentation helper 同步 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P1` +- 写入范围: + - `docs/api/XCEngine/Editor/Viewport/SceneViewportInteractionFrame/**` + - `docs/api/XCEngine/Editor/Viewport/SceneViewportNavigation/SceneViewportNavigationUpdate.md` + - `docs/api/XCEngine/Editor/Viewport/Viewport.md` + - `docs/api/XCEngine/Editor/panels/SceneViewPanel/**` + - `docs/api/_meta/rebuild-status.md` +- 主要源码依据: + - `editor/src/Viewport/SceneViewportInteractionFrame.h` + - `editor/src/panels/SceneViewPanel.cpp` + - `tests/Editor/test_scene_viewport_interaction_frame.cpp` +- 已确认问题: + - `SceneViewportInteractionFrame.h` 当前已经新增 `ShouldFocusSceneViewportAfterInteraction()`、`SceneViewportPresentationRequest` 与 `RefreshAndDrawSceneViewportPresentation()`，但 canonical 目录下还没有对应页面，模块总览也仍停在“只做交互前 frame-state 装配”的旧口径。 + - `SceneViewportNavigationUpdate.md` 仍写成 `beginLookDrag` / `beginPanDrag` 直接决定 `ImGui::SetWindowFocus()`；当前真实逻辑已经改成由 `ShouldFocusSceneViewportAfterInteraction(...)` 统一折叠 tool command、interaction action 与 navigation begin 标志。 + - `Viewport.md` 与 `SceneViewPanel/**` 对 `SceneViewportInteractionFrame` 的职责描述还没有完整纳入 focus / presentation helper 这一层尾段语义。 +- 完成记录: + - 已新增 `ShouldFocusSceneViewportAfterInteraction.md`、`SceneViewportPresentationRequest.md` 与 `RefreshAndDrawSceneViewportPresentation.md`，补齐 `SceneViewportInteractionFrame.h` 的新增公开入口。 + - 已重写 `SceneViewportInteractionFrame.md`，把模块职责从“交互前 frame-state 装配”扩展到当前真实的 focus 决策与 presentation 尾段收口语义。 + - 已同步 `SceneViewportNavigationUpdate.md`、`Viewport.md`、`SceneViewPanel/Render.md` 与 `SceneViewPanel.md`，移除 `SetWindowFocus()` / presentation tail 的旧口径描述。 + - 已重新运行 `python -B docs/api/_tools/audit_api_docs.py`，确认 `Editor source headers: 133`、`Valid source refs (Editor canonical): 133`、`Invalid source refs: 0`、`Broken .md links: 0`、`Stale editor canonical pages: 0`。 + +## T13 Editor / Viewport `SceneViewportChrome` 与 `SceneViewPanel` 当前编排链补正 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P1` +- 写入范围: + - `docs/api/XCEngine/Editor/Viewport/SceneViewportChrome/**` + - `docs/api/XCEngine/Editor/panels/SceneViewPanel/**` + - `docs/api/_meta/rebuild-status.md` +- 主要源码依据: + - `editor/src/Viewport/SceneViewportChrome.h` + - `editor/src/Viewport/SceneViewportChrome.cpp` + - `editor/src/panels/SceneViewPanel.h` + - `editor/src/panels/SceneViewPanel.cpp` + - `tests/Editor/test_scene_viewport_chrome.cpp` +- 已确认问题: + - `SceneViewportChrome.md` 仍写成“没有独立单元测试”，但当前工作树已经存在 `tests/Editor/test_scene_viewport_chrome.cpp`，并覆盖工具命令折叠与执行规则。 + - `SceneViewPanel.md` 与 `Render.md` 仍残留旧的 helper 列表和编排口径，没有完整对齐当前真实调用顺序，包括工具命令执行、focus 决策以及 `RefreshAndDrawSceneViewportPresentation(...)` 收口。 +- 完成记录: + - 已修正 `SceneViewportChrome.md` 的测试锚点描述，明确区分“命令折叠规则已有单测”和“UI 绘制细节仍由源码调用链锚定”。 + - 已重写 `SceneViewPanel.md` 与 `Render.md`，按当前源码同步 `Chrome -> InteractionFrame -> Navigation -> InteractionActions -> Presentation` 的真实编排链。 + - 已重新运行 `python -B docs/api/_tools/audit_api_docs.py`，确认 `Editor source headers: 133`、`Valid source refs (Editor canonical): 133`、`Invalid source refs: 0`、`Broken .md links: 0`、`Stale editor canonical pages: 0`。 + +## T14 Core / Asset `ArtifactFormats` shader artifact 正文布局补页 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P1` +- 写入范围: + - `docs/api/XCEngine/Core/Asset/ArtifactFormats/ArtifactFormats.md` + - `docs/api/_meta/rebuild-status.md` +- 主要源码依据: + - `engine/include/XCEngine/Core/Asset/ArtifactFormats.h` + - `engine/src/Core/Asset/AssetDatabase.cpp` + - `engine/src/Resources/Shader/ShaderLoader.cpp` + - `tests/Resources/Shader/test_shader_loader.cpp` +- 已确认问题: + - `ArtifactFormats.md` 的 shader artifact 小节当前只列出了几种头结构名，没有像 material / mesh 一样写清真实正文布局，缺少 name/source-path 字符串、property 段、per-pass tag/resource/variant 段以及 `compiledBinary` payload 的写入顺序。 + - 同页“读取侧”当前漏写了 `.xcshader` 的真实消费者 `ShaderLoader`。 + - 写入侧对 shader 只写了“产出 shader artifact”，没有和当前实现保持同样的主 artifact 文件名口径 `main.xcshader`。 +- 完成记录: + - 已为 `ArtifactFormats.md` 的 shader artifact 小节补齐当前正文布局，明确名称/路径字符串、property 段、pass tag/resource/variant 段以及 `compiledBinary` payload 的写入顺序。 + - 已补充 shader artifact 的 schema 值、`main.xcshader` 主 artifact 文件名，以及读取侧 `ShaderLoader` 的真实消费链。 + - 已重新运行 `python -B docs/api/_tools/audit_api_docs.py`，确认 `Public headers: 244`、`Editor source headers: 133`、`Invalid header refs: 0`、`Invalid source refs: 0`、`Broken .md links: 0`、`Stale editor canonical pages: 0`。 + +## T15 Resources / Material `Material.h` 公开符号 completeness 补页 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P1` +- 写入范围: + - `docs/api/XCEngine/Resources/Material/Material/**` + - `docs/api/_meta/rebuild-status.md` +- 主要源码依据: + - `engine/include/XCEngine/Resources/Material/Material.h` + - `engine/src/Resources/Material/Material.cpp` + - `tests/Resources/Material/test_material.cpp` + - `tests/Resources/Material/test_material_loader.cpp` + - `tests/Rendering/unit/test_render_scene_extractor.cpp` +- 已确认问题: + - `Material.h` 当前已经公开 `renderQueue / renderState / shaderPass / tags / constant layout / change version` 这一整组运行时接口，但 canonical 文档树仍主要停留在“数值属性 + 纹理绑定”子集，缺少大量类型页与方法页。 + - 缺页不仅包括 `SetRenderQueue()`、`SetRenderState()`、`SetShaderPass()`、tag API、`GetConstantLayout()`、`FindConstantField()`、`GetChangeVersion()`、`RecalculateMemorySize()`，还包括 `MaterialRenderQueue`、`MaterialRenderState`、`MaterialConstantFieldDesc`、`MaterialTagEntry`、`PendingTextureLoadState` 等公开类型。 + - `Material/Material.md` 的声明索引也没有把这批 render metadata / tag / constant-layout 相关公开符号纳入模块总览。 +- 完成记录: + - 已补齐 `Material.h` 当前公开的 render metadata / tag / constant-layout 相关类型页与方法页，并重写 `Material.md` 的模块索引。 + - 已把 `renderQueue / renderState / shaderPass / tags / texture bindings / properties / constant layout / change version` 这一整组运行时接口同步到 canonical 文档树。 + - 已重新运行 `python -B docs/api/_tools/audit_api_docs.py`，确认 `Public headers: 247`、`Editor source headers: 136`、`Invalid header refs: 0`、`Invalid source refs: 0`、`Broken .md links: 0`。 + +## T16 Editor / Viewport `SceneViewportOverlaySpriteResources` 新增头文件补页 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P1` +- 写入范围: + - `docs/api/XCEngine/Editor/Viewport/SceneViewportOverlaySpriteResources/**` + - `docs/api/XCEngine/Editor/Viewport/Viewport.md` + - `docs/api/XCEngine/Editor/Viewport/SceneViewportEditorOverlayData/SceneViewportEditorOverlayData.md` + - `docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportEditorOverlayPass/**` + - `docs/api/_meta/rebuild-status.md` +- 主要源码依据: + - `editor/src/Viewport/SceneViewportOverlaySpriteResources.h` + - `editor/src/Viewport/SceneViewportOverlaySpriteResources.cpp` + - `editor/src/Viewport/Passes/SceneViewportEditorOverlayPass.h` + - `editor/src/Viewport/Passes/SceneViewportEditorOverlayPass.cpp` + - `tests/Editor/test_scene_viewport_overlay_sprite_resources.cpp` +- 已确认问题: + - 工作树当前新增了 `SceneViewportOverlaySpriteResources.h`，但 canonical 文档树还没有对应目录页，导致结构审计一度出现 `Editor source headers: 136` / `Valid source refs (Editor canonical): 135`。 + - `SceneViewportEditorOverlayPass` 文档仍把 camera / light icon 纹理描述成 pass 内部细节，没有同步当前已经拆出的“资源路径解析 + RGBA 解码 + descriptor set 缓存”辅助层。 + - `SceneViewportOverlaySpriteTextureKind` 当前已经不再直接隐含具体文件路径；真实资源解析口径来自新头文件里的 helper 与 cache。 +- 完成记录: + - 已新增 `SceneViewportOverlaySpriteResources` canonical 目录，补齐 texture-kind 映射、asset spec、pixel payload、像素加载与 GPU 资源缓存页面。 + - 已同步 `Viewport.md`、`SceneViewportEditorOverlayData.md` 与 `SceneViewportEditorOverlayPass/**`，把 sprite overlay 资源准备链路改写为当前真实的 helper-header + cache 模型。 + - 已重新运行 `python -B docs/api/_tools/audit_api_docs.py`，确认 `Public headers: 247`、`Editor source headers: 136`、`Valid source refs (Editor canonical): 136`、`Invalid source refs: 0`、`Broken .md links: 0`。 + +## T17 Editor / Viewport `SceneViewportShaderPaths` 兼容层化与 pass-spec wrapper 类型口径收口 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P1` +- 写入范围: + - `docs/api/XCEngine/Editor/Viewport/SceneViewportShaderPaths/**` + - `docs/api/XCEngine/Editor/Viewport/ViewportHostRenderFlowUtils/**` + - `docs/api/XCEngine/Editor/Viewport/SceneViewportRenderPlan/**` + - `docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportGridPass/**` + - `docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportSelectionOutlinePass/**` + - `docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportEditorOverlayPass/**` + - `docs/api/XCEngine/Resources/BuiltinResources/BuiltinResources.md` + - `docs/api/_meta/rebuild-status.md` +- 主要源码依据: + - `editor/src/Viewport/SceneViewportShaderPaths.h` + - `editor/src/Viewport/SceneViewportResourcePaths.h` + - `editor/src/Viewport/SceneViewportPassSpecs.h` + - `editor/src/Viewport/ViewportHostRenderFlowUtils.h` + - `editor/src/Viewport/SceneViewportRenderPlan.h` + - `editor/src/Viewport/Passes/SceneViewportGridPass.h` + - `editor/src/Viewport/Passes/SceneViewportGridPass.cpp` + - `editor/src/Viewport/Passes/SceneViewportSelectionOutlinePass.h` + - `editor/src/Viewport/Passes/SceneViewportSelectionOutlinePass.cpp` + - `editor/src/Viewport/Passes/SceneViewportEditorOverlayPass.h` + - `editor/src/Viewport/Passes/SceneViewportEditorOverlayPass.cpp` + - `engine/include/XCEngine/Resources/BuiltinResources.h` + - `tests/Editor/test_scene_viewport_shader_paths.cpp` + - `tests/Editor/test_viewport_render_flow_utils.cpp` +- 已确认问题: + - `SceneViewportShaderPaths.h` 当前已经退化为只包含 `SceneViewportResourcePaths.h` 的兼容头，但部分文档仍把它写成路径 helper 的真实 owner。 + - `BuildSceneViewportGridPassData()`、`BuildSceneViewportSelectionOutlineStyle()`、两类 factory alias，以及 grid / selection-outline pass 适配页仍沿用旧签名，把 editor wrapper 类型写成 runtime `InfiniteGridPassData` / `ObjectIdOutlineStyle`。 + - `SceneViewportEditorOverlayPass` 与 `BuiltinResources.md` 仍残留一部分旧口径，没有完全同步 sprite resource cache 和新的 builtin shader 集合。 +- 完成记录: + - 已把 `SceneViewportShaderPaths/**` 收口为“兼容 include 层 + 迁移说明”口径，并统一回链当前真实 owner `SceneViewportResourcePaths`。 + - 已同步 `ViewportHostRenderFlowUtils/**`、`SceneViewportRenderPlan/**`、`SceneViewportGridPass/**` 与 `SceneViewportSelectionOutlinePass/**` 到当前 `SceneViewportGridPassData` / `SceneViewportSelectionOutlineStyle` wrapper 类型，以及 `ToBuiltin...` 转换链。 + - 已补充 `SceneViewportEditorOverlayPass/**` 对 `SceneViewportOverlaySpriteResourceCache` 的引用，并把 `BuiltinResources.md` 改到当前 builtin shader 集合 `forward-lit / unlit / depth-only / shadow-caster / object-id`。 + - 已重新运行 `python -B docs/api/_tools/audit_api_docs.py`，确认 `Public headers: 247`、`Editor source headers: 136`、`Valid header refs (canonical): 247`、`Valid source refs (Editor canonical): 136`、`Broken .md links: 0`。 + +## T18 Rendering / `CameraRenderer` depth-only 与 shadow-caster pass 注入链补页 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P1` +- 写入范围: + - `docs/api/XCEngine/Rendering/CameraRenderer/**` +- 主要源码依据: + - `engine/include/XCEngine/Rendering/CameraRenderer.h` + - `engine/src/Rendering/CameraRenderer.cpp` + - `tests/Rendering/unit/test_camera_scene_renderer.cpp` +- 已确认问题: + - `CameraRenderer.h` 当前已经公开 `SetDepthOnlyPass()`、`SetShadowCasterPass()`、`GetDepthOnlyPass()`、`GetShadowCasterPass()`，但 canonical 文档树还停留在只有主管线与 object-id pass 的旧索引。 + - `Constructor.md` 仍把最高阶构造重载写成只有 `(pipeline, objectIdPass)`，没有同步当前 `depthOnlyPass / shadowCasterPass` 注入点。 + - `Render.md` 仍把执行链写成 `pre -> pipeline -> object-id -> post -> overlay`，没有同步当前先跑 `shadowCaster` 和 `depthOnly` 请求的真实顺序。 +- 完成记录: + - 已补齐 `SetDepthOnlyPass.md`、`SetShadowCasterPass.md`、`GetDepthOnlyPass.md`、`GetShadowCasterPass.md`。 + - 已重写 `CameraRenderer.md`、`Constructor.md`、`Render.md` 与 `Destructor.md`，同步当前 depth-only / shadow-caster pass 的持有、回退与执行链语义。 + - 已重新运行 `python -B docs/api/_tools/audit_api_docs.py`，确认 `Public headers: 247`、`Broken .md links: 0`、`Stale canonical doc tokens: 0`。 + +## T19 Editor / Viewport `SceneViewportOverlayFrameCache` 新增头文件补页 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P1` +- 写入范围: + - `docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayFrameCache/**` + - `docs/api/XCEngine/Editor/Viewport/Viewport.md` + - `docs/api/XCEngine/Editor/Viewport/ViewportHostService/SceneView-Overlay-Frame-Data.md` + - `docs/api/_meta/rebuild-status.md` +- 主要源码依据: + - `editor/src/Viewport/SceneViewportOverlayFrameCache.h` + - `editor/src/Viewport/SceneViewportOverlayFrameCache.cpp` + - `editor/src/Viewport/ViewportHostService.h` + - `tests/Editor/test_scene_viewport_overlay_frame_cache.cpp` +- 已确认问题: + - 工作树新增了 `SceneViewportOverlayFrameCache.h`，但 canonical 文档树没有对应目录页，导致结构审计一度出现 `Editor source headers: 137` / `Valid source refs (Editor canonical): 136`。 + - `Viewport` 与 `ViewportHostService/SceneView-Overlay-Frame-Data.md` 仍在用“宿主类内部散落 cache key”的旧口径，没有把 viewport 尺寸解析、内容签名与重建判定收口到新 helper header。 +- 完成记录: + - 已新增 `SceneViewportOverlayFrameCache/**`，补齐 cache state、viewport 尺寸解析、内容签名、overlay 比较与重建判定页面。 + - 已同步 `Viewport.md` 与 `ViewportHostService/SceneView-Overlay-Frame-Data.md`，把 Scene View editor overlay frame 的缓存链路改写到当前 helper-header 模型。 + - 已重新运行 `python -B docs/api/_tools/audit_api_docs.py`，确认 `Public headers: 247`、`Editor source headers: 137`、`Valid source refs (Editor canonical): 137`、`Broken .md links: 0`。 + +## T20 Editor / Viewport `SceneViewportRenderPassBundle` 上层总览与 guide 口径同步 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P1` +- 写入范围: + - `docs/api/XCEngine/Editor/Viewport/Viewport.md` + - `docs/api/XCEngine/Editor/Viewport/ViewportHostService/**` + - `docs/api/XCEngine/Editor/Viewport/SceneViewportRenderPlan/**` + - `docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportGridPass/SceneViewportGridPass.md` + - `docs/api/XCEngine/Editor/Viewport/Passes/SceneViewportSelectionOutlinePass/SceneViewportSelectionOutlinePass.md` + - `docs/api/_guides/Editor/Scene-Viewport-Render-Plan-And-Failure-Flow.md` + - `docs/api/_meta/rebuild-status.md` +- 主要源码依据: + - `editor/src/Viewport/ViewportHostService.h` + - `editor/src/Viewport/SceneViewportRenderPassBundle.h` + - `editor/src/Viewport/SceneViewportRenderPassBundle.cpp` + - `editor/src/Viewport/SceneViewportRenderPlan.h` + - `editor/src/Viewport/Passes/SceneViewportGridPass.h` + - `editor/src/Viewport/Passes/SceneViewportSelectionOutlinePass.h` + - `tests/Editor/test_scene_viewport_render_pass_bundle.cpp` + - `tests/Editor/test_viewport_render_flow_utils.cpp` +- 已确认问题: + - `SceneViewportRenderPassBundle` 的 canonical 页面虽然已经存在，但 `Viewport.md`、`ViewportHostService.md`、`Initialize-And-Shutdown.md`、`RenderRequestedViewports.md`、`SceneViewportRenderPlan.md` 与 Scene View render-plan guide 仍在传播旧口径，把宿主服务写成“直接持有三个 pass renderer”或“直接调用 `BuildSceneViewportRenderPlan(...)`”。 + - `SceneViewportGridPass.md`、`SceneViewportSelectionOutlinePass.md` 与 `SceneViewportGridPassFactory.md` 仍把 factory 绑定位置写成 `ViewportHostService` 上的旧 renderer 成员，而不是当前 bundle 内部成员。 + - `Viewport.md` 还没有把 `SceneViewportResourcePaths`、`SceneViewportPassSpecs`、`SceneViewportRenderPlan`、`SceneViewportRenderPassBundle` 与 `ViewportHostRenderFlowUtils` 纳入当前模块总览。 +- 完成记录: + - 已同步 `Viewport.md`、`ViewportHostService/**`、`SceneViewportRenderPlan/**` 与 Scene View render-plan guide 到当前真实链路：`ViewportHostService -> SceneViewportRenderPassBundle -> BuildSceneViewportRenderPlan / ApplySceneViewportRenderPlan`。 + - 已修正 grid / selection-outline 相关页面，把 factory 绑定和 renderer 生命周期表述改成 bundle 持有模型，并补上新的上层交叉链接。 + - 已重新运行 `python -B docs/api/_tools/audit_api_docs.py`，确认 `Public headers: 247`、`Editor source headers: 138`、`Valid source refs (Editor canonical): 138`、`Broken .md links: 0`、`Stale editor canonical pages: 0`。 + +## T21 XCUI / `Resources/UI` / `UI/Types` / `UI/DrawData` / Editor transition header 补页 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P0` +- 写入范围: + - `docs/api/XCEngine/Resources/UI/**` + - `docs/api/XCEngine/UI/UI.md` + - `docs/api/XCEngine/UI/Types/**` + - `docs/api/XCEngine/UI/DrawData/**` + - `docs/api/XCEngine/Editor/Editor.md` + - `docs/api/XCEngine/Editor/XCUIBackend/**` + - `docs/api/XCEngine/Editor/Platform/Platform.md` + - `docs/api/XCEngine/Editor/Platform/D3D12WindowRendererImGuiInterop/**` + - `docs/api/XCEngine/Editor/panels/panels.md` + - `docs/api/XCEngine/Editor/panels/XCUIDemoPanel/**` +- 主要源码依据: + - `engine/include/XCEngine/Resources/UI/UIDocumentTypes.h` + - `engine/include/XCEngine/Resources/UI/UIDocumentCompiler.h` + - `engine/include/XCEngine/Resources/UI/UIDocuments.h` + - `engine/include/XCEngine/Resources/UI/UIDocumentLoaders.h` + - `engine/src/Resources/UI/UIDocumentCompiler.cpp` + - `engine/src/Resources/UI/UIDocuments.cpp` + - `engine/src/Resources/UI/UIDocumentLoaders.cpp` + - `engine/include/XCEngine/UI/Types.h` + - `engine/include/XCEngine/UI/DrawData.h` + - `editor/src/XCUIBackend/ImGuiTransitionBackend.h` + - `editor/src/XCUIBackend/XCUIDemoRuntime.h` + - `editor/src/Platform/D3D12WindowRendererImGuiInterop.h` + - `editor/src/panels/XCUIDemoPanel.h` + - `editor/src/panels/XCUIDemoPanel.cpp` + - `editor/src/Application.cpp` + - `editor/src/Core/EditorWorkspace.h` + - `tests/Resources/UI/test_ui_document_loader.cpp` + - `tests/Resources/UI/test_ui_schema_document.cpp` + - `tests/UI/Core/unit/test_ui_core.cpp` + - `tests/Editor/test_xcui_imgui_transition_backend.cpp` + - `tests/Editor/test_window_renderer_api.cpp` +- 已确认问题: + - `Resources/UI` 模块总览已经存在，但四个 public header 仍缺少 canonical 页面。 + - `UI/Types.h` 与 `UI/DrawData.h` 已被 runtime、Scene 和 editor transition backend 大量使用，但根模块入口页还没有把它们纳入顶层 API。 + - `editor/src/XCUIBackend`、`editor/src/Platform/D3D12WindowRendererImGuiInterop.h` 与 `editor/src/panels/XCUIDemoPanel.h` 没有 source-backed API 页面，导致 Editor 侧 XCUI transition 链路存在结构缺口。 +- 完成记录: + - 已新增 `UIDocumentTypes`、`UIDocumentCompiler`、`UIDocumentLoaders`、`UIDocuments`、`Types`、`DrawData`、`XCUIBackend`、`ImGuiTransitionBackend`、`XCUIDemoRuntime`、`D3D12WindowRendererImGuiInterop`、`XCUIDemoPanel` 页面。 + - 已同步 `Resources/UI/UI.md`、`UI/UI.md`、`Editor.md`、`Platform.md` 与 `panels.md`，把 UI 资源层、XCUI transition backend 和 demo panel 纳入当前模块入口。 + - 已重新运行 `python -B docs/api/_tools/audit_api_docs.py`，确认 `Editor source headers: 142`、`Valid source refs (Editor canonical): 142`、`Invalid source refs: 0`、`Broken .md links: 0`。 + +## T22 RHI / Shader formalization 文档补页与 `MaterialRenderState` 归位 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P1` +- 写入范围: + - `docs/api/XCEngine/RHI/ShaderCompiler/**` + - `docs/api/XCEngine/Resources/Shader/**` + - `docs/api/XCEngine/Resources/Material/**` +- 主要源码依据: + - `engine/include/XCEngine/RHI/ShaderCompiler/SpirvShaderCompiler.h` + - `engine/src/RHI/ShaderCompiler/SpirvShaderCompiler.cpp` + - `engine/src/RHI/Vulkan/VulkanShaderCompiler.cpp` + - `engine/src/RHI/OpenGL/OpenGLDevice.cpp` + - `engine/include/XCEngine/Resources/Shader/ShaderKeywordTypes.h` + - `engine/src/Resources/Shader/ShaderLoader.cpp` + - `engine/src/Resources/Shader/Shader.cpp` + - `engine/include/XCEngine/Resources/Material/MaterialRenderState.h` + - `engine/src/Resources/Material/Material.cpp` + - `tests/Resources/Shader/test_shader_loader.cpp` + - `tests/Resources/Shader/test_shader.cpp` + - `tests/Resources/Material/test_material.cpp` + - `tests/Rendering/unit/test_render_scene_extractor.cpp` +- 已确认问题: + - `SpirvShaderCompiler.h` 与 `ShaderKeywordTypes.h` 已进入当前工作树，但 canonical API 树缺少对应入口页。 + - `MaterialRenderState` 及其相关枚举页仍沿用旧归属，`头文件` 元信息还停在 `Material.h`。 + - 复核过程中发现 `ShaderRenderState.h` 并不在当前 public header 集合里，说明不能把计划中的 formalized pass-state 设想误写成现有 API 页面。 +- 完成记录: + - 已新增 `SpirvShaderCompiler/SpirvShaderCompiler.md` 与 `ShaderKeywordTypes/ShaderKeywordTypes.md`，并同步 `ShaderCompiler.md`、`Resources/Shader/Shader.md`。 + - 已把 `MaterialRenderState`、`MaterialCullMode`、`MaterialComparisonFunc`、`MaterialBlendOp`、`MaterialBlendFactor` 的 `头文件` 归位到 `MaterialRenderState.h`，并更新 `Resources/Material/Material.md`。 + - 已删除误建的 `ShaderRenderState` canonical 页面，并重新运行审计，确认 `Public headers: 304`、`Invalid header refs: 0`、`Broken .md links: 0`。 + +## T23 UI / Core + Input header coverage 补页 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P0` +- 写入范围: + - `docs/api/XCEngine/UI/Core/**` + - `docs/api/XCEngine/UI/Input/**` + - `docs/api/XCEngine/UI/UI.md` +- 主要源码依据: + - `engine/include/XCEngine/UI/Core/UIBuildContext.h` + - `engine/include/XCEngine/UI/Core/UIContext.h` + - `engine/include/XCEngine/UI/Core/UIElementTree.h` + - `engine/include/XCEngine/UI/Core/UIInvalidation.h` + - `engine/include/XCEngine/UI/Core/UIViewModel.h` + - `engine/include/XCEngine/UI/Input/UIFocusController.h` + - `engine/include/XCEngine/UI/Input/UIInputDispatcher.h` + - `engine/include/XCEngine/UI/Input/UIInputPath.h` + - `engine/include/XCEngine/UI/Input/UIInputRouter.h` + - `engine/include/XCEngine/UI/Input/UIShortcutRegistry.h` + - `engine/src/UI/Core/**` + - `engine/src/UI/Input/**` + - `tests/UI/Core/unit/**` + - `tests/UI/Runtime/unit/**` +- 已确认问题: + - 最新审计显示 `UI` 模块当前只覆盖 `2 / 37`，剩余缺口里最基础的一批就是 `Core` 与 `Input`。 + - 这些头文件已经有真实 `.cpp`、单测和 runtime 调用链，但 canonical API 树仍停留在目录总览页。 +- 完成记录: + - 已新增 `UIBuildContext`、`UIContext`、`UIElementTree`、`UIInvalidation`、`UIViewModel`、`UIFocusController`、`UIInputDispatcher`、`UIInputPath`、`UIInputRouter`、`UIShortcutRegistry` 页面。 + - 已同步 `Core.md`、`Input.md` 与 `UI.md`，把 retained-mode build / diff 主链和输入分发主链纳入当前模块入口。 + - 已重新运行 `python -B docs/api/_tools/audit_api_docs.py`，确认 `Valid header refs (canonical): 279`、`Invalid header refs: 0`、`Invalid source refs: 0`、`Broken .md links: 0`。 + +## T24 UI / Layout + Runtime + Style + Text + Widgets header coverage 补页 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P0` +- 写入范围: + - `docs/api/XCEngine/UI/Layout/**` + - `docs/api/XCEngine/UI/Runtime/**` + - `docs/api/XCEngine/UI/Style/**` + - `docs/api/XCEngine/UI/Text/**` + - `docs/api/XCEngine/UI/Widgets/**` + - `docs/api/XCEngine/UI/UI.md` +- 主要源码依据: + - `engine/include/XCEngine/UI/Layout/*.h` + - `engine/include/XCEngine/UI/Runtime/*.h` + - `engine/include/XCEngine/UI/Style/*.h` + - `engine/include/XCEngine/UI/Text/*.h` + - `engine/include/XCEngine/UI/Widgets/*.h` + - `engine/src/UI/Runtime/**` + - `engine/src/UI/Style/**` + - `engine/src/UI/Text/**` + - `engine/src/UI/Widgets/**` + - `tests/UI/Core/unit/**` + - `tests/UI/Runtime/unit/**` + - `tests/Scene/test_scene_runtime.cpp` +- 已确认问题: + - `Layout / Runtime / Style / Text / Widgets` 还剩 `25` 个未覆盖 public headers，是当前 API 文档最大的连续缺口。 + - 这些头文件里既有 header-only layout / interaction helper，也有真实 source-backed runtime / style / widget 状态模型；如果不拆开写，overview 很容易继续混淆“声明契约”和“当前实现行为”。 +- 当前进展: + - 已新增 `LayoutTypes`、`LayoutEngine`、`UISplitterLayout`、`UITabStripLayout`、`UIScreenTypes`、`UISceneRuntimeContext`、`UIScreenDocumentHost`、`UIScreenPlayer`、`UIScreenStackController`、`UISystem`、`StyleTypes`、`StyleSet`、`Theme`、`StyleResolver`、`DocumentStyleCompiler`、`UITextEditing`、`UITextInputController`、`UIExpansionModel`、`UIFlatHierarchyHelpers`、`UIKeyboardNavigationModel`、`UIPopupOverlayModel`、`UIPropertyEditModel`、`UISelectionModel`、`UISplitterInteraction`、`UITabStripModel` 页面。 + - 已同步 `Layout.md`、`Runtime.md`、`Style.md`、`Text.md`、`Widgets.md` 与 `UI.md`，把 header-only helper 和 source-backed runtime/style/widget 状态模型拆开归位。 + - 已重新运行 `python -B docs/api/_tools/audit_api_docs.py`，结果为：`Valid header refs (canonical): 304`、`UI: 37/37`、`Invalid source refs: 0`、`Broken .md links: 0`。 + +## T25 Editor UI 壳层与 `RenderMaterialResolve` 增量漂移复核 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P1` +- 写入范围: + - `docs/api/XCEngine/Editor/UI/ImGuiSession/ImGuiSession.md` + - `docs/api/XCEngine/Editor/panels/ViewportPanelContent/ViewportPanelContent.md` + - `docs/api/XCEngine/Editor/Layout/DockLayoutController/DockLayoutController.md` + - `docs/api/XCEngine/Rendering/Materials/RenderMaterialResolve/RenderMaterialResolve.md` +- 主要源码依据: + - `editor/src/UI/ImGuiSession.h` + - `editor/src/panels/ViewportPanelContent.h` + - `editor/src/Layout/DockLayoutController.h` + - `engine/include/XCEngine/Rendering/Materials/RenderMaterialResolve.h` + - `engine/src/RHI/D3D12/D3D12ResourceView.cpp` + - `engine/include/XCEngine/Input/InputTypes.h` + - `engine/include/XCEngine/Threading/TaskSystem.h` +- 已确认问题: + - `ImGuiSession.md` 仍停留在旧的“单字体 + 简单初始化”口径，没有同步 `SetProjectPath()` / `GetIniPath()`、双字体回退链和 DPI 配置。 + - `ViewportPanelContent.md` 没有写出当前 `AllowWhenOverlappedByItem` 的 hover/click 采样语义，容易误解 toolbar 覆盖视口时的交互行为。 + - `DockLayoutController.md` 没有同步当前 main viewport work-area、dock tab bar chrome 配置和 reset 延迟到下一帧重建的真实路径。 + - `RenderMaterialResolve.md` 漏掉了一批已经公开的 render-queue / legacy pass-fallback helper，也没把常量 payload 有效性和 skybox 模式优先级写清。 +- 完成记录: + - 已重写 `ImGuiSession.md`，补齐 `Initialize(projectPath, mainDpiScale)`、`GetIniPath()`、`SetProjectPath()`、Segoe UI + 微软雅黑 fallback 和 DPI 钳制逻辑。 + - 已更新 `ViewportPanelContent.md`，补上 overlappable 交互表面、root-child focus 与状态文案依赖 item rect 的当前实现说明。 + - 已更新 `DockLayoutController.md`，同步 dock host work-area、tab bar chrome 配置与 reset/rebuild 触发链。 + - 已更新 `RenderMaterialResolve.md`，补齐 render queue tag 解析、legacy builtin pass fallback、skybox 纹理模式优先级和常量 payload 有效性边界。 + - 抽查 `InputTypes`、`TaskSystem` 与 `D3D12ResourceView` 后，本轮未发现新的明确文档失配。 + +## 当前结论 + +- 第三轮复核当前已确认 `25` 组失配；`T01` 到 `T25` 已全部完成。 +- 当前 `Public headers` 已达到 `304/304`，`Editor source headers` 已达到 `142/142`；结构层、Resources、RHI、Rendering、UI 和全部 Editor source-backed API 均为全绿状态。 +- 后续如果 `docs/plan/` 再出现新的 API 相关计划，或工作树新增/改动 public header、Editor source header，应继续在此任务池追加新任务块，并在收口前重新运行 `python -B docs/api/_tools/audit_api_docs.py`。 diff --git a/docs/used/API文档实时同步任务池_2026-04-03_第一轮归档.md b/docs/used/API文档实时同步任务池_2026-04-03_第一轮归档.md new file mode 100644 index 00000000..10ca1c7f --- /dev/null +++ b/docs/used/API文档实时同步任务池_2026-04-03_第一轮归档.md @@ -0,0 +1,376 @@ +# API 文档实时同步任务池（2026-04-03） + +## 文档定位 + +这份任务池接替已归档的： + +- `docs/plan/used/API文档并行更新任务池_2026-04-02.md` + +旧任务池解决的是： + +- canonical 目录结构收口 +- 历史缺页补齐 +- 第一轮大规模内容重写 + +本轮不再以“补结构”为主，而是以“跟踪当前工作树真实实现变化，持续清理失准内容和过期 API 页面”为主。 + +## 本轮复核方法 + +本轮按下面三层做交叉复核： + +1. 重新执行 `python docs/api/_tools/audit_api_docs.py` +2. 检查当前工作树里真实发生变化的源码与测试： + - `engine/src/Components/MeshFilterComponent.cpp` + - `engine/src/Components/MeshRendererComponent.cpp` + - `editor/src/Actions/EditorActions.h` + - `editor/src/Actions/MainMenuActionRouter.h` + - `editor/src/Commands/ProjectCommands.h` + - `editor/src/Core/IProjectManager.h` + - `editor/src/Managers/ProjectManager.h` + - `editor/src/Managers/ProjectManager.cpp` + - `tests/Components/test_mesh_render_components.cpp` + - `tests/Scene/test_scene.cpp` + - `tests/editor/test_action_routing.cpp` +3. 反向搜索 API 文档里对旧行为、旧菜单和旧序列化键的残留描述 + +## 当前总判断 + +- 旧的内容级失准问题已经全部关闭： + - `Editor`：旧的项目迁移菜单、命令、接口、manager 和报告结构残留页已在 `2026-04-03 14:04:49` 收口完成 + - `Components`：`MeshFilterComponent / MeshRendererComponent` 的旧键名、普通项目路径 fallback 和模块总览口径已在 `2026-04-03 14:09:47` 对齐到当前源码 / 测试 +- 新暴露出的 `SceneViewportRenderPlan.h` 缺页问题已在 `2026-04-03 14:17:02` 收口完成 +- 当前结构项重新回到全绿： + - public headers `246/246` + - Editor source headers `122/122` + - 失效 `.md` 链接 `0` + - 无效 header / source ref `0` + - Editor 显式过期符号残留 `0` + - Editor 残留 canonical 旧页面 `0` + +这说明当前审计工具已经同时具备三种能力：兜住结构一致性、自动报出已删除 API 的旧符号残留、以及发现工作树中新冒出的未补页 header；后续工作进入“继续跟踪新增 API 与计划文件新增任务块”的阶段。 + +## 认领规则 + +- 一次只认领 `1` 个任务块，先改 `状态` 和 `认领人` +- 只修改自己任务块的 `写入范围`，不要跨任务顺手扩写其它模块 +- 每个任务都要以当前工作树源码、测试和真实调用点为依据，不允许只按旧文档重写旧文档 +- 除最后的审计收口任务外，不要随意覆盖 `docs/api/_meta/rebuild-status.md` +- 如果任务涉及删除过期 API 页面，必须同步清理所有交叉链接 + +## 任务池 + +## T01 Components / Mesh 资产引用最终协议同步 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P0` +- 写入范围: + - `docs/api/XCEngine/Components/MeshFilterComponent/**` + - `docs/api/XCEngine/Components/MeshRendererComponent/**` + - 必要时 `docs/api/XCEngine/Components/Components.md` + - 必要时 `docs/api/_guides/Components/**` +- 主要源码依据: + - `engine/src/Components/MeshFilterComponent.cpp` + - `engine/src/Components/MeshRendererComponent.cpp` + - `tests/Components/test_mesh_render_components.cpp` + - `tests/Scene/test_scene.cpp` + - `engine/include/XCEngine/Components/MeshFilterComponent.h` + - `engine/include/XCEngine/Components/MeshRendererComponent.h` +- 当前确认缺口: + - `MeshFilterComponent.md` 仍写“反序列化会读取 `mesh=`”，而当前实现只识别 `meshPath` + - `MeshFilterComponent.md` / `Serialize.md` 仍写“序列化输出 `mesh=`”，而当前实现对项目资产已转向 `meshRef` 主路径，只在 virtual scheme 下保留 `meshPath` + - `MeshFilterComponent::Deserialize.md` 仍写“只有路径时会补算 `AssetRef` 并接受普通路径”，而当前实现已忽略没有 `AssetRef` 的普通项目路径，只保留 virtual scheme 路径 + - `MeshRendererComponent.md` / `Serialize.md` / `Deserialize.md` 仍写“兼容 `materials=` 历史键”和“项目资产路径 fallback 仍是主恢复路径”，而当前实现已经不再读取 `materials=`，并且会清掉无 `AssetRef` 的普通 `materialPaths` + - 组件模块总览当前对“路径 + AssetRef + 运行时句柄双轨”的描述仍偏旧，没有强调“项目资产主协议已经收口为 `AssetRef`，路径主要保留给 `builtin://` / 其它 virtual scheme” +- 完成标准: + - 把 `MeshFilterComponent` / `MeshRendererComponent` 类型页和序列化方法页全部改到当前实现 + - 明确“项目资产只依赖 `AssetRef`，普通项目路径不再作为长期兼容协议” + - 明确“只有 virtual scheme 路径会稳定保留在 `meshPath` / `materialPaths` 里” + - 清掉所有关于 `mesh=`、`materials=` 仍被当前实现兼容的说法 +- 完成记录: + - 已重新核对 `MeshFilterComponent.h/.cpp`、`MeshRendererComponent.h/.cpp`、`tests/Components/test_mesh_render_components.cpp` 与 `tests/Scene/test_scene.cpp` + - `MeshFilterComponent.md`、`Serialize.md`、`Deserialize.md` 与 `MeshRendererComponent.md`、`Serialize.md`、`Deserialize.md` 已确认按当前实现描述 `meshRef / materialRefs` 主协议 + - 已继续修正 `SetMeshPath.md`、`SetMaterialPath.md` 与 `Components.md`，把“运行时路径缓存”和“正式序列化协议”明确拆开 + - `2026-04-03 14:09:47` 审计后，当前仓库中这组页面不再把 `mesh=` / `materials=` 或普通项目路径 fallback 写成当前协议 + +## T02 Editor / 移除场景资产引用迁移链路文档与过期页 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P0` +- 写入范围: + - `docs/api/XCEngine/Editor/Actions/EditorActions/**` + - `docs/api/XCEngine/Editor/Actions/MainMenuActionRouter/**` + - `docs/api/XCEngine/Editor/Commands/ProjectCommands/**` + - `docs/api/XCEngine/Editor/Core/IProjectManager/**` + - `docs/api/XCEngine/Editor/Managers/ProjectManager/**` + - `docs/api/XCEngine/Editor/panels/ProjectPanel/**` + - 必要时 `docs/api/_guides/Editor/**` +- 主要源码依据: + - `editor/src/Actions/EditorActions.h` + - `editor/src/Actions/MainMenuActionRouter.h` + - `editor/src/Commands/ProjectCommands.h` + - `editor/src/Core/IProjectManager.h` + - `editor/src/Managers/ProjectManager.h` + - `editor/src/Managers/ProjectManager.cpp` + - `tests/editor/test_action_routing.cpp` +- 当前确认缺口: + - `EditorActions.md` 仍包含 `MakeMigrateSceneAssetReferencesAction` + - `MainMenuActionRouter.md` 仍把 `File -> Migrate Scene AssetRefs` 当成当前菜单项 + - `ProjectCommands.md` 仍写 `CanMigrateSceneAssetReferences()` / `MigrateSceneAssetReferences()` + - `IProjectManager.md` 仍声明 `SceneAssetReferenceMigrationReport` 和 `MigrateSceneAssetReferences()` + - `ProjectManager.md` 仍把“场景资产引用迁移”写成当前公开职责 + - `ProjectPanel.md` 仍把 `Migrate Scene AssetRefs` 记为项目级命令之一 + - 过期 canonical 页面仍存在： + - `docs/api/XCEngine/Editor/Managers/ProjectManager/MigrateSceneAssetReferences.md` +- 完成标准: + - 把上述页面全部改成当前源码状态 + - 删除已不存在的 API 页面，并清理所有交叉引用 + - 把项目工作流文档收口到当前仍存在的入口：项目切换、保存、脚本重建、资源浏览与文件操作 +- 完成记录: + - 已重写 `EditorActions.md`、`MainMenuActionRouter.md`、`ProjectCommands.md`、`IProjectManager.md`、`ProjectManager.md`、`ProjectPanel.md` + - 已把 `IProjectManager` 进一步拆成 `Current Items And Selection`、`Navigation And Path`、`Initialization And Refresh`、`File Operations` 四页，按当前头文件分组收口 + - `docs/api/XCEngine/Editor/Managers/ProjectManager/MigrateSceneAssetReferences.md` 已删除；旧迁移 API 不再保留兼容入口页 + - `2026-04-03 14:04:49` 已重新执行 `python docs/api/_tools/audit_api_docs.py`，结果为： + - `Stale editor doc tokens: 0` + - `Broken .md links: 0` + - `Valid source refs (Editor canonical): 121` + +## T03 Cross-Module / 资产引用协议与编辑器工作流交叉说明收口 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P1` +- 写入范围: + - `docs/api/XCEngine/Components/Components.md` + - `docs/api/XCEngine/Scene/Scene.md` + - `docs/api/_guides/Editor/Editor-Architecture-And-Workflow.md` + - 必要时 `docs/api/main.md` +- 主要源码依据: + - `engine/src/Components/MeshFilterComponent.cpp` + - `engine/src/Components/MeshRendererComponent.cpp` + - `editor/src/Actions/MainMenuActionRouter.h` + - `editor/src/Commands/ProjectCommands.h` + - `editor/src/Managers/ProjectManager.cpp` + - `tests/Scene/test_scene.cpp` + - `tests/editor/test_action_routing.cpp` +- 当前确认缺口: + - 模块总览层还没有把“项目资产最终序列化协议已收口到 `AssetRef`，virtual path 只保留给 builtin/虚拟资源”讲透 + - Editor 架构层仍有旧项目维护入口的残留心智，需要删掉“场景迁移”这条已不存在的分支 + - 目前用户如果只读模块总览，仍容易得出“普通项目路径仍是第一公民协议”“主菜单还带场景迁移入口”的错误结论 +- 完成标准: + - 模块页和 guide 页不再沿用旧心智模型 + - 用户只看总览页，也能得出当前正确结论： + - 项目资产靠 `AssetRef` + - `builtin://` / 其它 virtual scheme 才保留路径 + - 主菜单已无 `Migrate Scene AssetRefs` +- 完成记录: + - 已修正 `docs/api/XCEngine/Components/Components.md`，明确项目资产正式协议优先 `AssetRef` + - 已复核 `docs/api/XCEngine/Scene/Scene.md`、`docs/api/_guides/Editor/Editor-Architecture-And-Workflow.md` 与 `docs/api/main.md`，确认不再传播旧菜单入口或“普通项目路径仍是第一公民协议”的说法 + - 当前仅阅读模块总览 / guide，也能得出“项目资产靠 `AssetRef`、virtual scheme 才稳定保留路径、主菜单没有旧迁移入口”的正确结论 + +## T04 API 审计工具补强 / 过期 API 页面检测 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P1` +- 写入范围: + - `docs/api/_tools/audit_api_docs.py` + - 必要时 `docs/api/_meta/rebuild-status.md` + - 必要时在 `docs/plan` 中补充审计口径说明 +- 主要依据: + - 本轮复核结论 + - 当前 audit 全绿但仍漏报 `MigrateSceneAssetReferences` 这类已删除 API 残留页 +- 当前确认缺口: + - 现有审计能发现“缺页”和“断链”，但不能发现“源码已经删除，文档页仍然存在” + - 也不能发现模块页仍在描述已删除菜单项或已删除 helper +- 完成标准: + - 至少新增一种轻量检测，能把“已删除 API 的残留 canonical 页面”或“显式过期 helper 名称残留”暴露出来 + - 让后续复核不再完全依赖人工 grep +- 完成记录: + - `docs/api/_tools/audit_api_docs.py` 已新增 Editor 显式过期符号残留检测 + - `2026-04-03 13:53:21` 审计已能自动报出 `49` 处 `MigrateSceneAssetReferences` 相关残留 + +## T05 收口审计与进度回写 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P2` +- 写入范围: + - `docs/api/_meta/rebuild-status.md` + - `docs/plan/API文档实时同步任务池_2026-04-03.md` +- 主要依据: + - `T01-T04` 完成结果 +- 完成标准: + - 重新执行 `python docs/api/_tools/audit_api_docs.py` + - 回写新的审计时间和结果 + - 明确记录本轮哪些失准点已关闭、哪些仍待继续跟踪 +- 完成记录: + - 已在 `2026-04-03 14:20:04` 重新执行 `python docs/api/_tools/audit_api_docs.py` + - 已回写 `docs/api/_meta/rebuild-status.md` + - 本轮已关闭： + - `T01` 对应的 Components / Mesh 资产引用协议失准 + - `T02` 对应的 Editor 旧迁移链路文档残留 + - `T03` 对应的跨模块总览与 guide 口径收口 + - `T07` 对应的 `SceneViewportRenderPlan.h` 缺页 + - 本轮剩余待继续跟踪： + - 当前任务池内无未完成块；后续按新增 API 或新增计划任务继续开块 + +## 最新收口结论（2026-04-03 14:20:04） + +- 已重新执行 `python docs/api/_tools/audit_api_docs.py` +- 当前结构性问题重新回到 `0` + - public headers `246/246` + - Editor source headers `122/122` + - 失效 `.md` 链接 `0` + - 无效 header / source ref `0` +- 本轮新增收口结果: + - `T01 Components / Mesh 资产引用最终协议同步` 已完成 + - `T02 Editor / 移除场景资产引用迁移链路文档与过期页` 已完成 + - `T03 Cross-Module / 资产引用协议与编辑器工作流交叉说明收口` 已完成 + - `T07 Editor / SceneViewportRenderPlan 新增头文件补页` 已完成 + - `T09 Editor / EditorConsoleSink 生命周期与 Managers 总览口径复核` 已完成 + - `IProjectManager` 已按当前头文件拆成 4 个职责页，`ProjectManager` / `ProjectCommands` / `MainMenuActionRouter` / `EditorActions` / `ProjectPanel` 已全部同步到当前源码 + - Components 模块总览与 mesh/material 组件页已统一到“项目资产优先 `AssetRef`、virtual scheme 才稳定保留路径”的当前协议 + - 对应的旧迁移 canonical 页已删除，已删除 API 名称也不再出现在正文里 + - `EditorConsoleSink` 文档已改回当前真实生命周期：`GetInstance()` 没有 fallback 实例，未注册时会返回 `nullptr` + - `docs/api/_meta/rebuild-status.md` 当前显示： + - `Markdown pages (canonical): 3273` + - `Stale editor doc tokens: 0` + - `Stale editor canonical pages: 0` + - `Editor high-risk single-page dirs: 0` +- 当前仍待处理的内容级问题: + - 当前任务池内无未完成块 + +## T06 Rendering / CameraRenderer 与主管线职责边界收口 +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P1` +- 写入范围: + - `docs/api/XCEngine/Rendering/CameraRenderer/**` + - `docs/api/XCEngine/Rendering/RenderPipeline/**` + - `docs/api/XCEngine/Rendering/RenderPipelineAsset/**` + - `docs/api/XCEngine/Rendering/Pipelines/BuiltinForwardPipelineAsset/**` + - 必要时 `docs/api/XCEngine/Rendering/Rendering.md` +- 主要源码依据: + - `engine/include/XCEngine/Rendering/CameraRenderer.h` + - `engine/src/Rendering/CameraRenderer.cpp` + - `engine/include/XCEngine/Rendering/RenderPipeline.h` + - `engine/include/XCEngine/Rendering/RenderPipelineAsset.h` + - `engine/include/XCEngine/Rendering/Pipelines/BuiltinForwardPipeline.h` + - `tests/Rendering/unit/test_camera_scene_renderer.cpp` +- 当前缺口: + - 已重写 `CameraRenderer.md`、`Constructor.md`、`Render.md`、`Rendering.md`、`RenderPipeline.md`，把“`SceneRenderer` 负责请求规划、`CameraRenderer` 负责执行单 request”的真实分层，以及默认 `BuiltinForwardPipelineAsset -> BuiltinForwardPipeline` 链路同步到当前实现。 + - 已继续重写 `RenderPipeline/Initialize.md`、`Render.md`、`Shutdown.md`、`Destructor.md`，明确 `RenderPipeline` 只覆盖主场景 runtime 绘制，不承担 object-id / builtin post-process / overlay 编排；同时写清 `Initialize()` 不是上层强制预热点，`Shutdown()` 调用路径由 `CameraRenderer` 托管。 + - 已校正 `RenderPipelineAsset.md`、`CreatePipeline.md`、`BuiltinForwardPipelineAsset.md`、`CreatePipeline.md`，把“asset 负责创建 runtime pipeline”与“空 asset / 空返回后的 fallback 由 `CameraRenderer` 处理”拆开说明，避免把调用方策略误记到 asset 接口本身。 +- 完成标准: + - 用户只看 `CameraRenderer` / `RenderPipeline` / `RenderPipelineAsset` 这一组页面，也能得出当前正确结论： + - `SceneRenderer` 负责请求规划，`CameraRenderer` 负责执行单 request + - `RenderPipeline` 只负责主场景 runtime 绘制 + - fallback 属于调用方装配逻辑，不属于 `RenderPipelineAsset` 接口本身 + +## T07 Editor / SceneViewportRenderPlan 新增头文件补页 +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P1` +- 写入范围: + - `docs/api/XCEngine/Editor/Viewport/SceneViewportRenderPlan/**` + - 必要时 `docs/api/XCEngine/Editor/Viewport/Viewport.md` + - 必要时 `docs/api/_guides/Editor/**` +- 主要源码依据: + - `editor/src/Viewport/SceneViewportRenderPlan.h` + - `editor/src/Viewport/ViewportHostService.h` +- 当前缺口: + - `docs/api/_tools/audit_api_docs.py` 于 `2026-04-03 14:11:12` 报出新增未覆盖 header：`editor/src/Viewport/SceneViewportRenderPlan.h` + - 当前缺的不只是类型页，还包括内联 helper： + - `SceneViewportRenderPlan` + - `SceneViewportRenderPlanBuildResult` + - `BuildSceneViewportRenderPlan(...)` + - `ApplySceneViewportRenderPlan(...)` + - 从 `ViewportHostService.h` 的调用关系看，这个头文件已经成为 Scene View request 装配链的一部分，不能继续留白 +- 完成标准: + - 为 `SceneViewportRenderPlan.h` 建立 canonical 目录与类型页 + - 把 plan 结构、build result、build/apply 两个 helper 的职责边界写清楚 + - 用户只看这组页面，也能得出当前正确结论： + - 它负责把 Scene View 的 builtin post-process、overlay passes 与 clear-color override 收口成一个 request plan + - `Build...` 负责从 overlay / targets 生成 plan + - `Apply...` 负责把 plan 回写到 `CameraRenderRequest` +- 完成记录: + - 已新增： + - `docs/api/XCEngine/Editor/Viewport/SceneViewportRenderPlan/SceneViewportRenderPlan.md` + - `docs/api/XCEngine/Editor/Viewport/SceneViewportRenderPlan/SceneViewportRenderPlanBuildResult.md` + - `docs/api/XCEngine/Editor/Viewport/SceneViewportRenderPlan/BuildSceneViewportRenderPlan.md` + - `docs/api/XCEngine/Editor/Viewport/SceneViewportRenderPlan/ApplySceneViewportRenderPlan.md` + - 已同步更新： + - `docs/api/XCEngine/Editor/Viewport/Viewport.md` + - `docs/api/XCEngine/Editor/Viewport/ViewportHostService/ViewportHostService.md` + - `2026-04-03 14:20:04` 审计结果已恢复为： + - `Editor source headers 122/122` + - `失效 .md 链接 0` + - `Stale editor doc tokens 0` + - `Stale editor canonical pages 0` + +## T08 Rendering / RenderCameraData 与 builtin forward 材质契约补齐 +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P2` +- 写入范围: + - `docs/api/XCEngine/Rendering/RenderCameraData/**` + - `docs/api/XCEngine/Rendering/RenderSceneUtility/**` + - `docs/api/XCEngine/Rendering/RenderMaterialUtility/**` +- 主要源码依据: + - `engine/include/XCEngine/Rendering/RenderCameraData.h` + - `engine/include/XCEngine/Rendering/RenderSceneUtility.h` + - `engine/src/Rendering/RenderSceneUtility.cpp` + - `engine/include/XCEngine/Rendering/RenderMaterialUtility.h` + - `tests/Rendering/unit/test_render_scene_extractor.cpp` + - `tests/Rendering/unit/test_render_scene_utility.cpp` +- 当前缺口: + - 已重写 `RenderCameraData.md`，补齐此前遗漏的 `clearFlags` 字段，以及 `RenderClearFlags` / `HasRenderClearFlag(...)` 的当前位标志语义；同时写清 `BuildRenderCameraData()` 不负责 clear mode 推导，真正的 per-request clear 规则由 `CameraRenderer` 回写。 + - 已重写 `RenderSceneUtility.md` 中 `BuildRenderCameraData()` 的职责边界，明确它只构建矩阵、世界位置、默认清屏色和 viewport，不直接决定相机 request 的 clear 规则。 + - 已补齐 `ResolveBuiltinBaseColorFactor.md`、`ResolveBuiltinBaseColorTexture.md`、`BuildBuiltinForwardMaterialData.md`，并更新 `RenderMaterialUtility.md`，把 builtin forward 当前公开消费的 base-color 因子 / 贴图契约、semantic 优先级、别名回退与 alpha-only fallback 写到当前实现。 +- 完成标准: + - 用户只看 `RenderCameraData` / `RenderSceneUtility` / `RenderMaterialUtility`，也能得出当前正确结论： + - clear flags 不是 extractor 里按相机直接定死的，而是 request 层再覆盖写回 + - builtin forward 当前公开消费的材质契约至少包括 `baseColorFactor` 与 base-color 贴图解析规则 + +## T09 Editor / EditorConsoleSink 生命周期与 Managers 总览口径复核 +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P2` +- 写入范围: + - `docs/api/XCEngine/Editor/Core/EditorConsoleSink/**` + - `docs/api/XCEngine/Editor/Managers/Managers.md` + - `docs/api/_tools/audit_api_docs.py` + - 必要时 `docs/api/_meta/rebuild-status.md` + - 必要时 `docs/plan/API文档实时同步任务池_2026-04-03.md` +- 主要源码依据: + - `editor/src/Core/EditorConsoleSink.h` + - `editor/src/Core/EditorConsoleSink.cpp` + - `tests/Editor/test_editor_console_sink.cpp` + - `editor/src/Managers/ProjectManager.h` + - `editor/src/Managers/ProjectManager.cpp` +- 当前缺口: + - `EditorConsoleSink.md`、`GetInstance.md`、`Destructor.md` 仍把 `GetInstance()` 写成“无活动实例时回退到 fallback sink”，但当前实现只是直接返回 `s_instance` + - 新增测试 `GetInstanceTracksRegisteredSinkOnly` 已明确要求：活动实例析构后 `GetInstance()` 返回 `nullptr` + - `Managers.md` 仍把“场景资产引用迁移”写成 `ProjectManager` 的当前职责之一，与本轮已删除的旧迁移链路不一致 +- 完成标准: + - `EditorConsoleSink` 生命周期相关页面全部对齐到当前实现： + - `GetInstance()` 可能返回 `nullptr` + - 没有静态 fallback sink + - `Managers.md` 不再残留旧迁移职责表述 + - 审计工具新增轻量兜底，后续若 `EditorConsoleSink` 文档再次写回 fallback 语义，能够被自动报出 +- 完成记录: + - 已修正 `EditorConsoleSink.md`、`GetInstance.md`、`Destructor.md` + - 已修正 `Managers.md` 中 `ProjectManager` 的职责概述 + - `docs/api/_tools/audit_api_docs.py` 已新增针对 `EditorConsoleSink` 旧 fallback 生命周期表述的定向检测 + +## 现阶段优先级建议 + +- 当前这份实时任务池里的已知问题已全部收口 +- `T01`、`T02`、`T03`、`T05`、`T06`、`T07`、`T09` 都已完成，不再作为并行入口重复认领 +- 若工作树继续新增 API 或计划文件继续追加任务块，再按新增内容开新任务 + +## 一句话结论 + +旧任务池解决了“API 文档树有没有建起来”的问题；这份实时任务池目前已经把 Editor 旧迁移链路、Components 资产引用协议、跨模块总览口径、`SceneViewportRenderPlan.h` 的缺页，以及 `EditorConsoleSink` 生命周期文档失准全部收口，后续只需要继续跟踪新增 API 与新增计划任务。 diff --git a/docs/used/API文档实时同步任务池_2026-04-03_第二轮归档.md b/docs/used/API文档实时同步任务池_2026-04-03_第二轮归档.md new file mode 100644 index 00000000..10ed39ce --- /dev/null +++ b/docs/used/API文档实时同步任务池_2026-04-03_第二轮归档.md @@ -0,0 +1,600 @@ +# API 文档实时同步任务池（2026-04-03，第二轮） + +## 文档定位 + +这份任务池接替已归档的第一轮计划： + +- `docs/plan/used/API文档实时同步任务池_2026-04-03_第一轮归档.md` + +第一轮已经解决的重点是： + +- canonical 目录结构收口 +- 历史缺页补齐 +- 第一轮大规模内容重写 + +本轮重点不再是“补结构”，而是： + +- 重新对照当前工作树源码与测试 +- 清理最近重构后重新出现的内容级失配 +- 继续维护一份适合多人并行认领的增量同步清单 + +## 当前复核快照 + +- 最近一次结构审计时间：`2026-04-03 16:21:55` +- 审计命令：`python -B docs/api/_tools/audit_api_docs.py` +- 当前结果： + - `Public headers: 244` + - `Editor source headers: 126` + - `Invalid header refs: 0` + - `Invalid source refs: 0` + - `Broken .md links: 0` + - `Stale canonical doc tokens: 0` + - `Stale editor doc tokens: 0` + - `Stale editor canonical pages: 0` + +这说明当前结构层面已经恢复全绿；本轮已确认的内容级失配也已收口，后续以持续巡检为主。 + +## 认领规则 + +- 一次只认领 `1` 个任务块。 +- 先把 `状态` 改成 `DOING`，再写 `认领人`。 +- 只能改自己任务块的 `写入范围`。 +- 所有改动都必须以“当前源码 + 当前测试 + 当前真实调用链”为依据，不允许按旧文档续写旧行为。 +- 如果清理了过期 API 页面，必须同时清理交叉链接。 + +## 任务池 + +## T01 Editor / Viewport 渲染计划与宿主流程内容同步 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P0` +- 写入范围: + - `docs/api/XCEngine/Editor/Viewport/SceneViewportRenderPlan/**` + - `docs/api/XCEngine/Editor/Viewport/ViewportHostRenderFlowUtils/**` + - `docs/api/XCEngine/Editor/Viewport/ViewportHostService/**` + - 必要时 `docs/api/XCEngine/Editor/Viewport/IViewportHostService/**` +- 主要源码依据: + - `editor/src/Viewport/SceneViewportRenderPlan.h` + - `editor/src/Viewport/ViewportHostRenderFlowUtils.h` + - `editor/src/Viewport/ViewportHostService.h` + - `tests/editor/test_viewport_render_flow_utils.cpp` +- 已关闭问题: + - 旧文档仍把 Scene View 当前主路径写成 builtin post-process 主导 + - 没写清 grid / selection outline 现在已转为显式 `postScenePasses` + - 没写清 overlay pass 是 `editorOverlayFrameData + transientOverlayFrameData` 合并后再创建 + - 没写清 `Scene object id shader view is unavailable` 是局部降级警告，不是整帧失败 +- 完成记录: + - 已重写 `SceneViewportRenderPlan.md`、`BuildSceneViewportRenderPlan.md`、`ApplySceneViewportRenderPlan.md` + - 已同步 `ViewportHostRenderFlowUtils.md`、`ViewportHostService.md`、`RenderRequestedViewports.md` + - 已清理 `IViewportHostService` 中残留的旧表述 + +## T02 Core / Asset 缓存接口改名与语义重构同步 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P0` +- 写入范围: + - `docs/api/XCEngine/Core/Asset/ResourceManager/**` + - `docs/api/XCEngine/Core/Asset/AssetImportService/**` + - `docs/api/XCEngine/Core/Asset/ProjectAssetIndex/**` + - 必要时 `docs/api/XCEngine/Core/Asset/Asset.md` + - 必要时 `docs/api/XCEngine/Core/Asset/ArtifactFormats/**` +- 主要源码依据: + - `engine/include/XCEngine/Core/Asset/ResourceManager.h` + - `engine/src/Core/Asset/ResourceManager.cpp` + - `engine/include/XCEngine/Core/Asset/AssetImportService.h` + - `engine/src/Core/Asset/AssetImportService.cpp` + - `engine/include/XCEngine/Core/Asset/ProjectAssetIndex.h` + - `engine/src/Core/Asset/ProjectAssetIndex.cpp` + - `tests/core/Asset/test_resource_manager.cpp` +- 已关闭问题: + - `RefreshAssetDatabase` 已经不存在，但旧文档仍在沿用 + - `RefreshProjectAssets` / `RebuildProjectAssetCache` / `GetProjectLibraryRoot` 缺页或未写清 + - `AssetImportService::EnsureArtifact()` 旧文档仍把输出写成 `ResolvedAsset` + - `BuildLookupSnapshot()` 旧文档仍按“双 map 出参”描述，而不是 `LookupSnapshot` + - `ImportedAsset::runtimeLoadPath` 语义未同步到上层文档 +- 完成记录: + - 已删除过期页 `ResourceManager/RefreshAssetDatabase.md` + - 已补齐 `RefreshProjectAssets.md`、`RebuildProjectAssetCache.md`、`GetProjectLibraryRoot.md` + - 已补齐 `LookupSnapshot.md`、`ImportedAsset.md`、`GetLibraryRoot.md`、`RebuildLibraryCache.md` + - 已同步 `Asset.md`、`ArtifactFormats.md`、`ResourceManager/Load.md` 的 `runtimeLoadPath` 口径 + +## T03 Scripting / Mono 托管销毁入口同步 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P1` +- 写入范围: + - `docs/api/XCEngine/Scripting/Mono/MonoScriptRuntime/**` +- 主要源码依据: + - `engine/include/XCEngine/Scripting/Mono/MonoScriptRuntime.h` + - `engine/src/Scripting/Mono/MonoScriptRuntime.cpp` + - `tests/scripting/test_mono_script_runtime.cpp` +- 已关闭问题: + - `DestroyManagedObject(MonoObject*)` 已进入头文件与测试，但文档树没有对应页面 + - `MonoScriptRuntime.md` 没写清 `Object.Destroy(...)` 会回落到原生对象 / 组件销毁 +- 完成记录: + - 已新增 `DestroyManagedObject.md` + - 已更新 `MonoScriptRuntime.md` 的 internal call 说明与方法总表 + +## T04 Cross-Module / 教程层与模块总览口径持续复核 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P2` +- 写入范围: + - `docs/api/_guides/**` + - `docs/api/XCEngine/*/*.md` + - 仅限与本轮已确认 API 变更直接相关的总览页 +- 任务目标: + - 继续检查教程页、模块总览页是否仍在传播旧心智模型 + - 尤其关注： + - Scene View 仍被写成 builtin post-process 主导 + - 资源导入链仍被写成 `artifactMainPath` / `RefreshAssetDatabase` 时代的口径 + - 托管对象销毁路径未在教程层被解释 +- 产出要求: + - 只修正已确认失配的 guide / overview 页面 + - 不做与当前源码无关的泛化扩写 +- 完成记录: + - 已完成一轮 guide / overview 复核 + - 已确认 `GameObject / Scene` 教程层仍在传播“tag 只是 name 别名”的旧心智 + - 已把后续需要实改的页面收口到 `T08` + +## T05 增量变更监控 / 新一轮差异发现 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P2` +- 写入范围: + - 只读检查 `engine/include/**`、`engine/src/**`、`editor/src/**`、`tests/**` + - 必要时只向本任务池追加新任务块 +- 任务目标: + - 继续结合工作树最新改动，找出新的“源码已变但文档还没跟上”的内容级失配 + - 优先检查： + - 最近改动过的 public headers + - 最近改动过的 Editor source headers + - 最近新增或更新过的测试 +- 产出要求: + - 只记录已确认的问题 + - 每条新任务都要写明： + - 受影响文档 + - 主要源码依据 + - 真实失配点 + - 建议写入范围 +- 完成记录: + - 已重新扫描当前工作树改动过的 public header、Editor source header、实现文件和测试 + - 已确认并追加 `T08` 与 `T09` 两组新的内容级失配 + +## T06 Rendering / Camera request、Passes 与执行链旧口径清理 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P1` +- 写入范围: + - `docs/api/XCEngine/Rendering/CameraRenderRequest/**` + - `docs/api/XCEngine/Rendering/CameraRenderer/**` + - `docs/api/XCEngine/Rendering/Passes/**` + - `docs/api/XCEngine/Rendering/ObjectIdPass/**` + - `docs/api/XCEngine/Rendering/RenderPipeline/**` + - `docs/api/XCEngine/Rendering/SceneRenderer/**` + - `docs/api/XCEngine/Editor/Viewport/SceneViewportRenderPlan/**` + - `docs/api/XCEngine/Editor/Viewport/Passes/**` + - 必要时 `docs/api/XCEngine/Editor/Viewport/Viewport.md` + - 必要时 `docs/api/XCEngine/XCEngine.md` + - 必要时 `docs/api/_tools/audit_api_docs.py` +- 主要源码依据: + - `engine/include/XCEngine/Rendering/CameraRenderRequest.h` + - `engine/include/XCEngine/Rendering/CameraRenderer.h` + - `engine/include/XCEngine/Rendering/Passes/BuiltinObjectIdPass.h` + - `engine/include/XCEngine/Rendering/Passes/BuiltinObjectIdOutlinePass.h` + - `engine/include/XCEngine/Rendering/Passes/BuiltinInfiniteGridPass.h` + - `engine/include/XCEngine/Rendering/ObjectIdPass.h` + - `engine/include/XCEngine/Rendering/RenderPipeline.h` + - `engine/include/XCEngine/Rendering/SceneRenderer.h` + - `engine/src/Rendering/CameraRenderer.cpp` + - `engine/src/Rendering/SceneRenderer.cpp` + - `tests/Rendering/unit/test_camera_scene_renderer.cpp` + - `editor/src/Viewport/SceneViewportRenderPlan.h` + - `editor/src/Viewport/Passes/SceneViewportGridPass.cpp` + - `editor/src/Viewport/Passes/SceneViewportSelectionOutlinePass.cpp` + - `editor/src/Viewport/ViewportHostRenderFlowUtils.h` + - `tests/Editor/test_viewport_render_flow_utils.cpp` + - `tests/Editor/test_scene_viewport_overlay_renderer.cpp` +- 已关闭问题: + - `CameraRenderRequest.md` 仍描述已删除的 `builtinPostProcess` 子请求 + - 页面仍链接到不存在的 `BuiltinPostProcessRequest/BuiltinPostProcessRequest.md` + - Scene View 已改为通过 `postScenePasses` / `overlayPasses` 写回 request，但该页口径未同步 + - `CameraRenderer.md` 仍保留已删除的 `m_builtinPostProcessBuilder` 历史口径 + - `Passes.md` 的典型链路只写了 `postScenePasses`，遗漏当前 `overlayPasses` 组装路径 + - `Rendering/Passes` 下仍残留已删除的 `BuiltinPostProcessPassPlan` / `BuiltinPostProcessPassSequenceBuilder` 页面 + - `BuiltinObjectIdPass`、`BuiltinInfiniteGridPass` 多个公开入口缺页 + - `ObjectIdPass.md`、`RenderPipeline.md`、`SceneRenderer.md` 与顶层 `XCEngine.md` 仍在传播 builtin-post-process 心智模型 +- 完成记录: + - 已重写 `CameraRenderRequest.md` + - 已清理 `2` 个失效 `.md` 链接 + - 已同步 `CameraRenderer.md` 与 `Passes.md` 的当前执行链路表述 + - 已删除 `BuiltinPostProcessPassPlan.md`、`BuiltinPostProcessPassSequenceBuilder.md` + - 已补齐 `BuiltinObjectIdPass` / `BuiltinInfiniteGridPass` 缺失页面，并补充 `SceneViewportRenderPlan` 下 grid / selection outline pass factory 页面 + - 已新增 `SceneViewportGridPass` / `SceneViewportSelectionOutlinePass` 页面，并同步 `Editor/Viewport/Passes/Passes.md` 与 `Viewport.md` 的当前口径 + - 已同步 `ObjectIdPass.md`、`RenderPipeline.md`、`SceneRenderer.md` 与 `XCEngine.md` 的当前口径 + - 已补充 Rendering guide、`CameraRenderer::Render` 与 `ViewportHostService::RenderRequestedViewports` 的 request 级 pass 注入说明 + - 已为 `builtinPostProcess` / `BuiltinPostProcessRequest` / `m_builtinPostProcessBuilder` 增加 canonical 过期符号审计 + - 已复跑结构审计并确认 `Broken .md links: 0` + +## T07 Editor / Core `EditorConsoleSink` 生命周期说明同步 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P1` +- 写入范围: + - `docs/api/XCEngine/Editor/Core/EditorConsoleSink/**` + - 必要时 `docs/api/XCEngine/Editor/Managers/Managers.md` + - 必要时 `docs/api/_tools/audit_api_docs.py` +- 主要源码依据: + - `editor/src/Core/EditorConsoleSink.h` + - `editor/src/Core/EditorConsoleSink.cpp` + - `editor/src/panels/ConsolePanel.cpp` + - `editor/src/Core/EditorLoggingSetup.h` + - `tests/Editor/test_editor_console_sink.cpp` +- 已关闭问题: + - `EditorConsoleSink::GetInstance()` 旧文档仍把它写成会返回 fallback 实例 + - 相关 overview 页面没有写清活动 sink 销毁后会返回 `nullptr` + - 审计脚本此前无法自动拦截这类旧生命周期表述 +- 完成记录: + - 已同步 `EditorConsoleSink.md`、`GetInstance.md`、`Destructor.md` + - 已同步 `Managers.md` 中对控制台 sink 生命周期的引用口径 + - 已为 `fallback 实例` 与“不会返回空指针”旧表述增加定向审计 + +## T08 Components / Scene / Scripting `GameObject` tag-layer 语义同步 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P0` +- 写入范围: + - `docs/api/XCEngine/Components/GameObject/**` + - `docs/api/XCEngine/Scene/Scene/**` + - `docs/api/XCEngine/Scripting/Mono/MonoScriptRuntime/**` + - 必要时 `docs/api/_guides/Components/GameObject-Component-Lifecycle-And-Serialization.md` + - 必要时 `docs/api/_guides/Scene/Scene-Lifecycle-And-Serialization.md` +- 主要源码依据: + - `engine/include/XCEngine/Components/GameObject.h` + - `engine/src/Components/GameObject.cpp` + - `engine/src/Scene/Scene.cpp` + - `engine/src/Scripting/Mono/MonoScriptRuntime.cpp` + - `managed/XCEngine.ScriptCore/GameObject.cs` + - `managed/XCEngine.ScriptCore/Component.cs` + - `managed/XCEngine.ScriptCore/InternalCalls.cs` + - `tests/Components/test_game_object.cpp` + - `tests/Scene/test_scene.cpp` + - `tests/scripting/test_mono_script_runtime.cpp` +- 已确认问题: + - `GameObject.md` 仍写“没有真正的 tag 系统”，并把 `FindGameObjectsWithTag()` 描述成按名字匹配；这与当前 `m_tag` / `CompareTag()` / `SetTag()` 实现已不符 + - `Scene.md` 与 `FindGameObjectWithTag.md` 仍在传播“按名字查 tag”的旧口径 + - `GameObject` 目录缺少 `GetTag.md`、`SetTag.md`、`CompareTag.md`、`GetLayer.md`、`SetLayer.md` + - `Serialize.md` / `Deserialize.md` 尚未同步 `tag=` 字段、默认 `Untagged` 以及 layer clamp 语义 + - `MonoScriptRuntime` 总览页尚未解释 Unity 风格 `GameObject.tag` / `layer` / `CompareTag()` 已通过 internal call 暴露到托管侧 +- 产出要求: + - 类型页与方法页都要明确区分当前原生实现、场景查询语义和托管暴露语义 + - 教程页要从“tag 只是名字别名”改成“当前已有独立 tag 字段，但仍是轻量 Unity 风格模型” + - 需要写清：空 tag 会回落到 `Untagged`，layer 会 clamp 到 `[0, 31]` +- 完成记录: + - 已重写 `GameObject.md`、`Scene.md`、`FindGameObjectWithTag.md` + - 已补齐 `GetTag.md`、`SetTag.md`、`CompareTag.md`、`GetLayer.md`、`SetLayer.md` + - 已同步 `Serialize.md` / `Deserialize.md` 的 `tag=`、`layer=`、`Untagged` 与 clamp 语义 + - 已同步 `MonoScriptRuntime.md` 对托管 `GameObject.tag` / `layer` / `CompareTag()` 的 internal call 桥接说明 + - 已同步 `GameObject-Component-Lifecycle-And-Serialization.md` 与 `Scene-Lifecycle-And-Serialization.md` 的心智模型口径 + - 已补充 `Constructor`、`AddComponent`、`SetActive`、`SetParent`、`IsActive`、`IsActiveInHierarchy`、`Find`、`FindObjectsOfType`、`Awake`、`Start`、`Update`、`FixedUpdate`、`LateUpdate`、`OnDestroy`、`Destroy` 的真实生命周期与查询语义 + +## T09 Resources / Material 与材质 Artifact v2 语义同步 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P0` +- 写入范围: + - `docs/api/XCEngine/Resources/Material/**` + - `docs/api/XCEngine/Core/Asset/ArtifactFormats/**` + - `docs/api/XCEngine/Core/Asset/AssetDatabase/**` + - 必要时 `docs/api/XCEngine/Core/Asset/Asset.md` +- 主要源码依据: + - `engine/include/XCEngine/Resources/Material/Material.h` + - `engine/src/Resources/Material/Material.cpp` + - `engine/src/Resources/Material/MaterialLoader.cpp` + - `engine/include/XCEngine/Core/Asset/ArtifactFormats.h` + - `engine/src/Core/Asset/AssetDatabase.cpp` + - `tests/Resources/Material/test_material.cpp` + - `tests/Resources/Material/test_material_loader.cpp` +- 已确认问题: + - `Resources/Material/Material.md` 仍是旧模板式总览，没有覆盖当前公开语义 + - `Material` 目录缺少 `SetTextureAssetRef.md`、`GetTextureBindingAssetRef.md`、`GetTextureBindingLoadedTexture.md` + - `ArtifactFormats.md` 仍写 `kMaterialArtifactSchemaVersion = 1`、magic `XCMAT01`，与当前 schema v2 / `XCMAT02` 不符 + - 材质 artifact 文档还没写清每个 texture binding 现在会序列化“编码后的 `AssetRef` + 可选 artifact/path 字符串” + - `Material` 文档尚未解释纹理绑定现在既有 loaded handle，也有稳定 `AssetRef` 元数据，并且 `GetTexture()` 可在首次访问时通过 `TryResolveAssetPath()` 兑现延迟资源 +- 产出要求: + - 重写 `Material.md`，把 shader 属性、texture binding 元数据、lazy resolve、路径与 `AssetRef` 的边界写清 + - 为新增公开方法补页，并把现有 `SetTexture` / `GetTexture` / `GetTextureBindingCount` 等页面更新到当前实现 + - 更新 `ArtifactFormats.md` 与 `AssetDatabase` 相关页面，写清材质 artifact v2 的字段顺序、兼容边界和设计动机 +- 完成记录: + - 已重写 `docs/api/XCEngine/Resources/Material/Material.md` 与 `docs/api/XCEngine/Resources/Material/Material/Material.md` + - 已新增 `SetTextureAssetRef.md`、`SetTexturePath.md`、`GetTextureBindingName.md`、`GetTextureBindingAssetRef.md`、`GetTextureBindingPath.md`、`GetTextureBindingLoadedTexture.md`、`GetTextureBindingTexture.md` + - 已同步 `SetTexture.md`、`GetTexture.md`、`GetTextureBindingCount.md` 的当前 lazy-load 与 binding metadata 语义 + - 已更新 `ArtifactFormats.md`，把材质 artifact 修正到 schema v2 / `XCMAT02`，并写清 texture binding 三元组布局 + - 已更新 `AssetDatabase.md` 的当前 importerVersion 常量，并在 `Asset.md` 补充 `.xcmat` v2 的跨模块说明 + - 已为旧 `kMaterialArtifactSchemaVersion = 1` / `XCMAT01` 文案增加审计回归保护 + - 已复跑结构审计并确认 `Broken .md links: 0` + +## T10 Editor / Viewport `SceneViewportShaderPaths` canonical 补页 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P1` +- 写入范围: + - `docs/api/XCEngine/Editor/Viewport/SceneViewportShaderPaths/**` + - 必要时 `docs/api/XCEngine/Editor/Viewport/Viewport.md` +- 主要源码依据: + - `editor/src/Viewport/SceneViewportShaderPaths.h` + - `editor/src/Viewport/Passes/SceneViewportGridPass.cpp` + - `editor/src/Viewport/Passes/SceneViewportSelectionOutlinePass.cpp` +- 已关闭问题: + - `editor/src/Viewport/SceneViewportShaderPaths.h` 新进入工作树后还没有 canonical 页面 + - 结构审计一度出现 `Editor source headers: 125` 但 `Valid source refs (Editor canonical): 124` +- 完成记录: + - 已新增 `SceneViewportShaderPaths.md` 与 5 个 helper/function 页面 + - 已同步 `Viewport.md` 的目录结构总览 + - 已复跑结构审计并确认 `Valid source refs (Editor canonical): 125` + +## T11 Platform / 概述页与方法页模板化表述清理 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P1` +- 写入范围: + - `docs/api/XCEngine/Platform/**` +- 主要源码依据: + - `engine/include/XCEngine/Platform/GameTime.h` + - `engine/include/XCEngine/Platform/PlatformTypes.h` + - `engine/include/XCEngine/Platform/IClock.h` + - `engine/include/XCEngine/Platform/IWindow.h` + - `engine/include/XCEngine/Platform/IFileSystem.h` + - `engine/include/XCEngine/Platform/IPlatform.h` + - `engine/include/XCEngine/Platform/IDynamicLibrary.h` + - `engine/include/XCEngine/Platform/IDisplayEnumerator.h` + - `engine/include/XCEngine/Platform/Window.h` + - `engine/include/XCEngine/Platform/Windows/WindowsWindow.h` + - `engine/include/XCEngine/Platform/Windows/WindowsInputModule.h` + - `engine/src/Platform/Window.cpp` + - `engine/src/Platform/Windows/WindowsWindow.cpp` + - `engine/src/Platform/Windows/WindowsInputModule.cpp` +- 已关闭问题: + - `Platform` 下多组概述页仍把自己写成“canonical 总览”，没有说明符号本身的职责和边界 + - 大量方法页仍残留“获取相关状态或对象”“公开方法，详见头文件声明”“参数语义详见头文件声明”等模板废话 + - `WindowsInputModule::PumpEvents()` 当前是空实现，但旧页没有说明，容易误导成真实消息泵入口 + - `WindowsWindow` 的 Win32 当前实现路径没有写清，例如 `Create()`、`Destroy()`、`PumpEvents()`、`SetFullscreen()` 与 `ShouldClose()` +- 完成记录: + - 已重写 `GameTime`、`PlatformTypes`、`IClock`、`IWindow`、`IFileSystem`、`IPlatform`、`IDynamicLibrary`、`IDisplayEnumerator`、`Window`、`WindowsWindow`、`WindowsInputModule` 相关 overview 与方法页 + - 已把 `Platform` 下残留模板短语、参数占位语和 canonical 占位说明清理到 `0` + - 已写清 `Window` / `WindowsWindow` / `WindowsInputModule` 的当前实现语义与输入桥接关系 + - 已复跑结构审计并确认 `Old template pages: 0`、`Broken .md links: 0` + +## T12 Cross-Module / canonical 式概述废话清理 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P1` +- 写入范围: + - `docs/api/XCEngine/RHI/D3D12/**` + - `docs/api/XCEngine/Resources/**` +- 主要源码依据: + - `engine/include/XCEngine/RHI/D3D12/D3D12Types.h` + - `engine/include/XCEngine/RHI/D3D12/D3D12Common.h` + - `engine/include/XCEngine/RHI/D3D12/D3D12Enums.h` + - `engine/include/XCEngine/RHI/D3D12/D3D12RootSignature.h` + - `engine/include/XCEngine/RHI/D3D12/D3D12PipelineState.h` + - `engine/include/XCEngine/Resources/Resources.h` + - `engine/include/XCEngine/Resources/Texture/Texture.h` + - `engine/include/XCEngine/Resources/Texture/TextureLoader.h` + - `engine/include/XCEngine/Resources/Texture/TextureImportSettings.h` + - `engine/include/XCEngine/Resources/Mesh/Mesh.h` + - `engine/include/XCEngine/Resources/Mesh/MeshLoader.h` + - `engine/include/XCEngine/Resources/Mesh/MeshImportSettings.h` + - `engine/include/XCEngine/Resources/Shader/Shader.h` + - `engine/include/XCEngine/Resources/Shader/ShaderLoader.h` + - `engine/include/XCEngine/Resources/AudioClip/AudioClip.h` + - `engine/include/XCEngine/Resources/AudioClip/AudioLoader.h` +- 已关闭问题: + - `RHI/D3D12` 与 `Resources` 下仍有一批 overview 页把“概述”写成“当前页面作为平行目录中的 canonical 总览”，没有解释符号本身做什么 + - `Texture`、`Mesh`、`Shader`、`AudioClip` 等资源类型页没有把类型边界、持有的数据和辅助声明写清 + - `D3D12Types`、`D3D12Common`、`D3D12Enums` 这类 helper header 页没有说明它们是转换 / 构造 / 检查函数集合 +- 完成记录: + - 已重写 `RHI/D3D12` 与 `Resources` 下全部 `16` 个 canonical 式 overview 页 + - 已把全仓库 `docs/api/XCEngine/**` 中“当前页面作为平行目录中的 canonical 总览”这类概述废话清理到 `0` + - 已复跑结构审计并确认 `Broken .md links: 0`、`Old template pages: 0` + +## T13 Components / `GameObject` 剩余辅助页内容化补齐 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P2` +- 写入范围: + - `docs/api/XCEngine/Components/GameObject/DetachChildren.md` + - `docs/api/XCEngine/Components/GameObject/DetachFromParent.md` + - `docs/api/XCEngine/Components/GameObject/Destructor.md` + - `docs/api/XCEngine/Components/GameObject/GetChild.md` + - `docs/api/XCEngine/Components/GameObject/GetChildCount.md` + - `docs/api/XCEngine/Components/GameObject/GetChildren.md` + - `docs/api/XCEngine/Components/GameObject/GetComponent.md` + - `docs/api/XCEngine/Components/GameObject/GetComponentInChildren.md` + - `docs/api/XCEngine/Components/GameObject/GetComponentInParent.md` + - `docs/api/XCEngine/Components/GameObject/GetComponents.md` + - `docs/api/XCEngine/Components/GameObject/GetComponentsInChildren.md` + - `docs/api/XCEngine/Components/GameObject/GetID.md` + - `docs/api/XCEngine/Components/GameObject/GetName.md` + - `docs/api/XCEngine/Components/GameObject/GetParent.md` + - `docs/api/XCEngine/Components/GameObject/GetScene.md` + - `docs/api/XCEngine/Components/GameObject/GetTransform.md` + - `docs/api/XCEngine/Components/GameObject/GetUUID.md` + - `docs/api/XCEngine/Components/GameObject/RemoveComponent.md` + - `docs/api/XCEngine/Components/GameObject/SetName.md` +- 主要源码依据: + - `engine/include/XCEngine/Components/GameObject.h` + - `engine/src/Components/GameObject.cpp` + - `tests/Components/test_game_object.cpp` + - `tests/Scene/test_scene.cpp` + - `tests/scripting/test_mono_script_runtime.cpp` +- 已关闭问题: + - `GameObject` 模块的核心生命周期、tag/layer 与场景边界已经完成，但上述辅助页仍残留模板式表述 + - 这些页面尚未写清模板接口的真实语义，例如 `Transform` 特例、层级递归查询、观察指针返回与移除边界 +- 产出要求: + - 把这些方法页全部改成基于当前源码的行为说明 + - 优先写清组件查询模板、层级辅助接口和对象身份访问器的真实边界 + - 不重复改动本轮已经完成内容化的生命周期和 tag/layer 页面 +- 完成记录: + - 已重写 `DetachChildren.md`、`DetachFromParent.md`、`Destructor.md`、`GetChild.md`、`GetChildCount.md`、`GetChildren.md` + - 已重写 `GetComponent.md`、`GetComponentInChildren.md`、`GetComponentInParent.md`、`GetComponents.md`、`GetComponentsInChildren.md`、`RemoveComponent.md` + - 已重写 `GetID.md`、`GetName.md`、`GetParent.md`、`GetScene.md`、`GetTransform.md`、`GetUUID.md`、`SetName.md` + - 已写清 `Transform` 特例、层级查询顺序、`Scene` / registry 观察指针语义，以及 `RemoveComponent` 当前不会补发 `OnDestroy()` + +## T14 Rendering / `RenderMaterialUtility` schema-driven 材质常量 payload 语义同步 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P1` +- 写入范围: + - `docs/api/XCEngine/Rendering/RenderMaterialUtility/**` + - `docs/api/XCEngine/Rendering/Pipelines/BuiltinForwardPipeline/**` + - 必要时 `docs/api/_tools/audit_api_docs.py` +- 主要源码依据: + - `engine/include/XCEngine/Rendering/RenderMaterialUtility.h` + - `engine/include/XCEngine/Rendering/Pipelines/BuiltinForwardPipeline.h` + - `engine/src/Rendering/Pipelines/BuiltinForwardPipeline.cpp` + - `engine/include/XCEngine/Resources/Material/Material.h` + - `tests/Rendering/unit/test_render_scene_extractor.cpp` +- 已关闭问题: + - `RenderMaterialUtility` 总览页尚未覆盖新进入 public header 的 `MaterialConstantPayloadView` 与 `ResolveSchemaMaterialConstantPayload(...)` + - `BuiltinForwardPipeline.md` 仍把逐材质常量写成“目前只写入 `baseColorFactor`”，没有同步当前优先消费 schema-driven payload、仅在缺失时回退 fallback 的实现 + - `BuildBuiltinForwardMaterialData.md` 还没把自己定位成兼容 fallback helper，容易与当前主路径混淆 +- 完成记录: + - 已新增 `BuiltinForwardMaterialData.md`、`MaterialConstantPayloadView.md`、`ResolveSchemaMaterialConstantPayload.md` + - 已重写 `RenderMaterialUtility.md` 与 `BuildBuiltinForwardMaterialData.md`，写清 schema payload 与 builtin forward fallback 的边界 + - 已同步 `BuiltinForwardPipeline.md` 与 `Render.md`，补入 `Material::GetConstantBufferData()` 主路径和 `FallbackPerMaterialConstants` 回退逻辑 +- 已为“逐材质常量目前只写入 `baseColorFactor`”等旧口径增加 canonical 审计回归保护 +- 已复跑结构审计并确认 `Stale canonical doc tokens: 0` + +## T15 Editor / Scripting 脚本程序集重建与运行时锁语义同步 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P1` +- 写入范围: + - `docs/api/XCEngine/Editor/Scripting/EditorScriptAssemblyBuilder/**` + - `docs/api/XCEngine/Editor/Application/RebuildScriptingAssemblies.md` + - 必要时 `docs/api/XCEngine/Editor/Application/Application.md` +- 主要源码依据: + - `editor/src/Scripting/EditorScriptAssemblyBuilder.cpp` + - `editor/src/Application.cpp` + - `tests/Editor/test_editor_script_assembly_builder.cpp` +- 已关闭问题: + - `EditorScriptAssemblyBuilder` 文档仍把 `mscorlib.dll` 写成“每次重建都复制”，没有同步当前“首次复制、后续复用项目本地 corlib”的实现 + - `RebuildProjectAssemblies.md` 没写清活动 Mono runtime 仍持有 `GameScripts.dll` 时可能出现文件锁失败 + - `Application::RebuildScriptingAssemblies` 文档仍写“构建失败会保留旧 runtime”，与当前先 `ShutdownScriptingRuntime()` 再构建的实现不符 +- 完成记录: + - 已同步 `EditorScriptAssemblyBuilder.md` 与 `RebuildProjectAssemblies.md`，补入项目本地 `mscorlib.dll` 复用策略、Mono 文件锁失败路径与测试锚点 + - 已同步 `Application::RebuildScriptingAssemblies` 与 `Application.md`，写清“先卸载当前 runtime 释放程序集锁，再重建并在成功后重载”的真实顺序 + - 已复跑结构审计并确认 `Broken .md links: 0`、`Stale canonical doc tokens: 0` + +## T16 Resources / Rendering Passes SceneView shader ownership 口径同步 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P1` +- 写入范围: + - `docs/api/XCEngine/Resources/BuiltinResources/**` + - `docs/api/XCEngine/Rendering/Passes/BuiltinInfiniteGridPass/**` + - `docs/api/XCEngine/Rendering/Passes/BuiltinObjectIdOutlinePass/**` +- 主要源码依据: + - `engine/include/XCEngine/Resources/BuiltinResources.h` + - `engine/src/Resources/BuiltinResources.cpp` + - `engine/include/XCEngine/Rendering/Passes/BuiltinInfiniteGridPass.h` + - `engine/src/Rendering/Passes/BuiltinInfiniteGridPass.cpp` + - `engine/include/XCEngine/Rendering/Passes/BuiltinObjectIdOutlinePass.h` + - `engine/src/Rendering/Passes/BuiltinObjectIdOutlinePass.cpp` + - `editor/src/Viewport/SceneViewportShaderPaths.h` +- 已关闭问题: + - `BuiltinResources.md` 仍把 `object-id-outline` / `infinite-grid` 写成 engine `builtin://shaders/*` helper 与 builtin shader 工厂的一部分，但当前头文件与实现已只保留 `forward-lit`、`object-id` + - `BuiltinInfiniteGridPass` 与 `BuiltinObjectIdOutlinePass` 已改为由调用方注入 `shaderPath`，文档却仍在传播“固定 builtin shader”口径 + - 两个 pass 的文档树缺少 `SetShaderPath.md`、`GetShaderPath.md`；`BuiltinInfiniteGridPass` 还缺少 `Constructor.md` 与 `Destructor.md` +- 完成记录: + - 已更新 `BuiltinResources.md`，把 builtin shader 集合收口到 `forward-lit` / `object-id`，并写清 Scene View grid / outline shader 现在由 editor 侧 `SceneViewportShaderPaths` 提供 + - 已重写 `BuiltinInfiniteGridPass.md`、`Render.md`、`Shutdown.md`，补上 `Constructor.md`、`Destructor.md`、`SetShaderPath.md`、`GetShaderPath.md` + - 已重写 `BuiltinObjectIdOutlinePass.md`、`Constructor.md`、`Render.md`、`Shutdown.md`，补上 `SetShaderPath.md` 与 `GetShaderPath.md` + +## T17 Editor / Viewport `SceneViewportOverlayProviders` canonical 补页 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P1` +- 写入范围: + - `docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayProviders/**` +- 主要源码依据: + - `editor/src/Viewport/SceneViewportOverlayProviders.h` + - `editor/src/Viewport/SceneViewportOverlayProviders.cpp` + - `editor/src/Viewport/SceneViewportOverlayBuilder.h` + - `tests/editor/test_scene_viewport_overlay_providers.cpp` +- 已关闭问题: + - `editor/src/Viewport/SceneViewportOverlayProviders.h` 新进入工作树后还没有 canonical 页面 + - 结构审计出现 `Editor source headers: 126` 但 `Valid source refs (Editor canonical): 125` + - 缺少对 overlay build context、provider registry 和默认相机 / 灯光 provider 工厂的当前语义说明 +- 完成记录: + - 已新增 `SceneViewportOverlayProviders.md`、`SceneViewportOverlayBuildContext.md`、`ISceneViewportOverlayProvider.md`、`SceneViewportOverlayProviderRegistry.md` + - 已新增 `CreateSceneViewportCameraOverlayProvider.md`、`CreateSceneViewportLightOverlayProvider.md`、`BuildDefaultSceneViewportOverlayProviderRegistry.md` + - 已复跑结构审计并确认 `Valid source refs (Editor canonical): 126`、`Broken .md links: 0` + +## T18 Editor / Viewport overlay builder provider 化口径同步 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P1` +- 写入范围: + - `docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayBuilder/**` + - `docs/api/XCEngine/Editor/Viewport/ViewportHostService/**` + - `docs/api/XCEngine/Editor/Viewport/Viewport.md` + - 必要时 `docs/api/_guides/Editor/**` +- 主要源码依据: + - `editor/src/Viewport/SceneViewportOverlayBuilder.h` + - `editor/src/Viewport/SceneViewportOverlayBuilder.cpp` + - `editor/src/Viewport/SceneViewportOverlayProviders.h` + - `editor/src/Viewport/ViewportHostService.h` + - `tests/editor/test_scene_viewport_overlay_providers.cpp` +- 已关闭问题: + - `SceneViewportOverlayBuilder` 文档仍把类型写成“无状态构建器 + static Build(...)”，没有同步当前实例化 builder + provider registry 的实现 + - `SceneViewportOverlayBuilder` 目录缺少 `Constructor.md` 与 `GetProviderRegistry.md` + - `ViewportHostService.md` 仍把基础 overlay 来源写成 `SceneViewportOverlayBuilder::Build(...)`，没有同步当前成员 `m_sceneViewportOverlayBuilder` + - guide 层仍在传播 `overlay builder -> overlay pass` 与“先把 scene icon 塞进 builder”的旧扩展口径 +- 完成记录: + - 已重写 `SceneViewportOverlayBuilder.md` 与 `Build.md`，把默认 registry、build context 和 provider 聚合链路写清 + - 已新增 `Constructor.md` 与 `GetProviderRegistry.md` + - 已同步 `ViewportHostService.md`、`Viewport.md` 以及两篇 Editor guide 的当前 provider 化心智模型 + - 已把新扩展建议改成 `overlay provider -> overlay builder -> overlay pass` + +## 当前结论 + +- 本轮已经关掉十七组明确的内容级失配： + - `Viewport` 渲染计划与宿主流程 + - `Core/Asset` 缓存接口与导入服务语义 + - `MonoScriptRuntime` 托管销毁入口 + - `Rendering` 相机请求、Passes 与单相机执行链旧口径 + - `EditorConsoleSink` 生命周期与空指针返回语义 + - 跨模块 guide / overview 漂移的本轮复核与拆分 + - `Material` / `ArtifactFormats` / `AssetDatabase` 的材质 artifact v2 与 texture `AssetRef` 语义 + - `GameObject` / `Scene` / `Mono` 的 tag-layer 与托管暴露语义 + - `GameObject` 剩余辅助访问器 / 层级辅助页的内容化补齐 + - `SceneViewportShaderPaths` canonical 缺页 + - `Platform` 模块概述页与方法页的模板化废话清理 +- `RHI/D3D12` 与 `Resources` 的 canonical 式概述废话清理 +- `RenderMaterialUtility` / `BuiltinForwardPipeline` 的 schema-driven 材质常量 payload 语义 +- `Editor` 脚本程序集重建流程中的 corlib 复用与 runtime 文件锁语义 +- `BuiltinResources` 与 Scene View grid / outline shader ownership、`shaderPath` 注入口径 +- `SceneViewportOverlayProviders` canonical 缺页 +- `SceneViewportOverlayBuilder` / `ViewportHostService` / guide 层的 provider 化心智模型同步 +- 当前结构审计为全绿。 +- 当前仍建议保留 `T04` 与 `T05` 作为持续性复核入口，用来承接后续源码变更带来的新文档漂移。 diff --git a/docs/used/API文档并行更新任务池_2026-04-02.md b/docs/used/API文档并行更新任务池_2026-04-02.md new file mode 100644 index 00000000..9d3e26dd --- /dev/null +++ b/docs/used/API文档并行更新任务池_2026-04-02.md @@ -0,0 +1,590 @@ +# API 文档并行更新任务池（2026-04-02） + +## 目的 + +基于 `2026-04-02` 当前工作树，这份清单用于把 API 文档更新任务拆成可并行认领的独立块，供多个会话同时推进。 + +## 认领规则 + +- 一次只认领 `1` 个任务块，先改 `状态` 和 `认领人`。 +- 只修改自己任务块的 `写入范围`，不要跨任务顺手改别的模块页。 +- 除 `T09` 之外，其他任务不要更新 `docs/api/_meta/rebuild-status.md`，避免多人冲突。 +- 每个任务都要以源码、实现、测试、真实调用点为依据，不允许只按命名猜测行为。 +- 如果任务执行中发现需要新增 guide，统一放到 `docs/api/_guides//` 下。 + +## 当前并行推荐 + +- 历史任务 `T01-T20` 已完成，本轮文档内容同步与收口已落地。 +- 如果继续并行推进，重点不再是补历史缺页，而是： + - 跟踪新增源码 API + - 继续人工抽样审阅审计中提示的高风险单页目录 +- `2026-04-03 00:24:08` 这轮复核后，已新增 `T21-T27`；优先从 `Input`、`Editor` 项目工作流、`Game View -> Runtime Input` 三块并行切入。 + +## 任务池 + +## T01 Editor / Viewport 子模块补齐与重写 + +- 状态: `DONE` +- 认领人: `Codex-Viewport` +- 优先级: `P0` +- 写入范围: `docs/api/XCEngine/Editor/Viewport/**`、`docs/api/XCEngine/Editor/panels/SceneViewPanel/**`、`docs/api/XCEngine/Editor/panels/ViewportPanelContent/**` +- 主要源码依据: `editor/src/Viewport/**`、`editor/src/panels/SceneViewPanel.*`、`editor/src/panels/ViewportPanelContent.h`、`tests/editor/test_scene_viewport_camera_controller.cpp` +- 当前缺口: `Viewport` 整个 canonical 树尚未建立；以下页面当前缺失: `SceneViewportCameraController`、`SceneViewportMoveGizmo`、`SceneViewportRotateGizmo`、`SceneViewportScaleGizmo`、`SceneViewportOverlayRenderer`、`ViewportHostService`、`ViewportHostRenderFlowUtils`、`SceneViewportEditorOverlayData`、`SceneViewportOverlayBuilder`、`ViewportPanelContent` +- 完成标准: 补齐 `Viewport/Viewport.md` 与所有类型页；`SceneViewPanel` 文档重写到当前 gizmo / overlay / host flow 实现；写清楚生命周期、交互链路、渲染路径和测试覆盖 + +## T02 Editor / ScriptComponentEditor 补齐 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P0` +- 写入范围: `docs/api/XCEngine/Editor/ComponentEditors/ScriptComponentEditor/**`、`docs/api/XCEngine/Editor/ComponentEditors/ScriptComponentEditorUtils/**`、`docs/api/XCEngine/Editor/ComponentEditors/ComponentEditors.md`、`docs/api/XCEngine/Editor/ComponentEditors/ComponentEditorRegistry/**` +- 主要源码依据: `editor/src/ComponentEditors/ScriptComponentEditor.h`、`editor/src/ComponentEditors/ScriptComponentEditorUtils.h`、`editor/src/ComponentEditors/ComponentEditorRegistry.cpp` +- 当前缺口: `ScriptComponentEditor` 与 `ScriptComponentEditorUtils` 还没有 canonical 页面；组件编辑器总览也需要纳入脚本组件编辑器 +- 完成标准: 补齐缺页；说明 Inspector 侧脚本字段绘制、字段元数据来源、与 `ScriptEngine` / `ScriptComponent` 的关系 + +## T03 Core / AssetDatabase 新建与资产数据库链路说明 + +- 状态: `DONE` +- 认领人: `Codex-Asset` +- 优先级: `P0` +- 写入范围: `docs/api/XCEngine/Core/Asset/AssetDatabase/**`、`docs/api/XCEngine/Core/Asset/Asset.md` +- 主要源码依据: `engine/include/XCEngine/Core/Asset/AssetDatabase.h`、相关 `.cpp` 实现、项目目录下新增的 `.meta` 与 `Library` 资产缓存变化 +- 当前缺口: `AssetDatabase` 对应的 canonical 类型页完全缺失；`Core/Asset` 模块总览需要反映新的数据库/导入缓存方向 +- 完成标准: 建立 `AssetDatabase` 页面，明确 GUID、path、meta、导入缓存、查询职责，以及它和 `ProjectPanel` / `ResourceManager` / 资源导入流程的关系 + +## T04 Rendering / Passes 子模块与 BuiltinObjectIdOutlinePass 补齐 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P0` +- 写入范围: `docs/api/XCEngine/Rendering/Passes/**` +- 主要源码依据: `engine/include/XCEngine/Rendering/Passes/BuiltinObjectIdOutlinePass.h`、`engine/src/Rendering/Passes/BuiltinObjectIdOutlinePass.cpp` +- 当前缺口: `Rendering/Passes` 目录当前没有 canonical 文档树；`BuiltinObjectIdOutlinePass` 页面缺失 +- 完成标准: 新建 `Passes/Passes.md` 和 `BuiltinObjectIdOutlinePass` 类型页；写清楚对象 ID / 轮廓高亮的输入输出、依赖资源、典型使用位置和当前限制 + +## T05 Scripting 模块内容重构 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P1` +- 写入范围: `docs/api/XCEngine/Scripting/**`、`docs/api/_guides/Scripting/**` +- 主要源码依据: `engine/include/XCEngine/Scripting/IScriptRuntime.h`、`Mono/MonoScriptRuntime.h`、`NullScriptRuntime.h`、`ScriptComponent.h`、`ScriptEngine.h` 及对应 `.cpp`；`tests/scripting/**` +- 当前缺口: 结构存在，但脚本运行时、字段同步、项目脚本程序集、空运行时回退等内容需要按当前实现重写 +- 完成标准: 明确运行时抽象、Mono 后端、Null 后端、字段存储与组件生命周期；必要时补一篇项目脚本程序集 / 字段同步 guide + +## T06 Editor 运行时胶水层与面板内容更新 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P1` +- 写入范围: `docs/api/XCEngine/Editor/Application/**`、`docs/api/XCEngine/Editor/Core/EventBus/**`、`docs/api/XCEngine/Editor/panels/InspectorPanel/**`、`docs/api/XCEngine/Editor/panels/ProjectPanel/**`、`docs/api/XCEngine/Editor/UI/Widgets/**`、`docs/api/XCEngine/Editor/Actions/HierarchyActionRouter/**`、`docs/api/XCEngine/Editor/Commands/EntityCommands/**` +- 主要源码依据: `editor/src/Application.*`、`editor/src/Core/EventBus.h`、`editor/src/panels/InspectorPanel.*`、`editor/src/panels/ProjectPanel.*`、`editor/src/UI/Widgets.h`、`editor/src/Actions/HierarchyActionRouter.h`、`editor/src/Commands/EntityCommands.h` +- 当前缺口: 这些页面虽然大多存在，但内容容易落后于当前交互链路；`ProjectPanel` 虽已较新，仍要根据这轮源码变化做二次核对 +- 完成标准: 把“Editor 主循环 -> EventBus -> 面板 -> Action/Command”这条链路写清楚；Inspector/Project/Hierarchy 相关页内容与当前实现严格对齐 + +## T07 Rendering 相机请求与对象 ID 渲染链路更新 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P1` +- 写入范围: `docs/api/XCEngine/Rendering/CameraRenderRequest/**`、`docs/api/XCEngine/Rendering/CameraRenderer/**`、`docs/api/XCEngine/Rendering/RenderMaterialUtility/**`、`docs/api/XCEngine/Rendering/Rendering.md` +- 主要源码依据: `engine/include/XCEngine/Rendering/CameraRenderRequest.h`、`engine/src/Rendering/CameraRenderer.cpp`、`engine/src/Resources/Material/MaterialLoader.cpp`、`engine/src/Rendering/Passes/BuiltinObjectIdOutlinePass.cpp` +- 当前缺口: 文档需要反映这轮 renderer 里对象 ID、outline、camera request、材质 render state 的新关系 +- 完成标准: 写清楚 camera request 的职责边界、camera renderer 的主流程、object-id/outline 的接入点，以及材质 render state 对渲染路径的影响 + +## T08 Components / MeshFilterComponent 与资源绑定链路更新 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P1` +- 写入范围: `docs/api/XCEngine/Components/MeshFilterComponent/**`、`docs/api/XCEngine/Components/Components.md` +- 主要源码依据: `engine/include/XCEngine/Components/MeshFilterComponent.h`、相关 `.cpp`、`tests/Resources/Mesh/test_mesh_loader.cpp`、`tests/Resources/Material/test_material_loader.cpp` +- 当前缺口: `MeshFilterComponent` 页面存在，但需要重新核对 mesh handle / path / 资源解析链路；模块总览也应补充 MeshFilter 在渲染和资产导入链路中的定位 +- 完成标准: 说明 `MeshFilterComponent` 如何保存 mesh 引用、如何与资源系统和渲染提取流程衔接，以及当前限制 + +## T09 根总览与最终审计 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P2` +- 写入范围: `docs/api/XCEngine/XCEngine.md`、受影响的模块总览页、`docs/api/_meta/rebuild-status.md` +- 主要源码依据: 前面所有任务的完成结果 +- 当前缺口: 已完成根总览与模块总览收口；`2026-04-02 23:22:27` 的最终审计结果显示 `246/246` 个 public headers 全量覆盖，结构性问题保持 `0` +- 完成标准: 在 `T10-T13` 完成后统一调整总览页导航；重新执行 `audit_api_docs.py`、覆盖校验与链接校验；确认未覆盖 public headers 归零后写回最终 `rebuild-status.md` + +## 审计结论（2026-04-02 23:22:27） + +- 本轮全量审计已执行: `python docs/api/_tools/audit_api_docs.py` +- 当前结构性问题为 `0`: 无失效 `.md` 链接、无非 `.md` 相对链接、无旧模板页面、无扁平 header 页面、无缺失目录总览页 +- 当前剩余覆盖缺口: `0` 个 public headers 未覆盖 +- 受影响模块: + - `Core`: `0` + - `Rendering`: `0` + - `Resources`: `0` + - `Scene`: `0` +- 说明: + - `T01-T13` 对应的结构重构、基础层补页与总览收口已全部落地 + - `AssetImportService` 与 `ProjectAssetIndex` 两个 `Core/Asset` 尾项已补齐 + - canonical API 文档树当前与 `engine/include/XCEngine` 的 public header 集合保持全量对齐 + +## T10 Core / Asset 标识与产物格式补齐 + +- 状态: `DONE` +- 认领人: `Codex-Asset2` +- 优先级: `P1` +- 写入范围: `docs/api/XCEngine/Core/Asset/ArtifactFormats/**`、`docs/api/XCEngine/Core/Asset/AssetGUID/**`、`docs/api/XCEngine/Core/Asset/AssetRef/**` +- 主要源码依据: `engine/include/XCEngine/Core/Asset/ArtifactFormats.h`、`engine/include/XCEngine/Core/Asset/AssetGUID.h`、`engine/include/XCEngine/Core/Asset/AssetRef.h`、相关使用点 `engine/src/Components/MeshFilterComponent.cpp`、`engine/src/Resources/*/*Loader.cpp`、`tests/core/Asset/test_resource_manager.cpp`、`tests/Resources/Texture/test_texture_loader.cpp` +- 当前缺口: 已补齐 `ArtifactFormats`、`AssetGUID`、`AssetRef` 三个 canonical 页面，并将资产身份 / 引用 / artifact 格式链路并入 `Core/Asset` 模块叙述 +- 完成标准: 建立三个 canonical 类型页，写清楚 GUID 格式、AssetRef 结构语义、artifact 产物文件格式在资源导入与反序列化链路中的作用 + +## T11 Rendering / RenderPass 与 SceneRenderRequest 基础层补齐 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P1` +- 写入范围: `docs/api/XCEngine/Rendering/ObjectIdEncoding/**`、`docs/api/XCEngine/Rendering/ObjectIdPass/**`、`docs/api/XCEngine/Rendering/RenderPass/**`、`docs/api/XCEngine/Rendering/RenderSceneUtility/**`、`docs/api/XCEngine/Rendering/SceneRenderRequestPlanner/**`、`docs/api/XCEngine/Rendering/SceneRenderRequestUtils/**` +- 主要源码依据: `engine/include/XCEngine/Rendering/ObjectIdEncoding.h`、`ObjectIdPass.h`、`RenderPass.h`、`RenderSceneUtility.h`、`SceneRenderRequestPlanner.h`、`SceneRenderRequestUtils.h`，对应 `.cpp`，以及 `tests/Rendering/unit/test_render_pass.cpp`、`test_render_scene_utility.cpp`、`test_scene_render_request_planner.cpp`、`test_scene_render_request_utils.cpp`、`test_camera_scene_renderer.cpp`、`tests/Editor/test_viewport_render_flow_utils.cpp` +- 当前缺口: 已补齐 `ObjectIdEncoding`、`ObjectIdPass`、`RenderPass`、`RenderSceneUtility`、`SceneRenderRequestPlanner`、`SceneRenderRequestUtils` 六个基础层页面，并回写 Rendering 总览导航 +- 完成标准: 补齐六个类型页，明确 render pass 生命周期、object-id 编解码语义、scene request 规划规则，以及这些基础设施与 `CameraRenderer` / editor viewport 的衔接 + +## T12 Resources / BuiltinResources 补齐 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P1` +- 写入范围: `docs/api/XCEngine/Resources/BuiltinResources/**` +- 主要源码依据: `engine/include/XCEngine/Resources/BuiltinResources.h`、`engine/src/Resources/BuiltinResources.cpp`、相关调用点 `editor/src/Commands/EntityCommands.h`、`engine/src/Rendering/Passes/BuiltinObjectIdPass.cpp`、`engine/src/Rendering/Passes/BuiltinObjectIdOutlinePass.cpp`、`engine/src/Rendering/Pipelines/BuiltinForwardPipeline.cpp`、`tests/Resources/Shader/test_shader_loader.cpp` +- 当前缺口: 已建立 `BuiltinResources` canonical 页面，并纳入 `Resources` 模块总览 +- 完成标准: 建立 `BuiltinResources` 类型页，写清楚内置 mesh / material / shader / primitive display name 的职责边界、典型调用点与当前限制 + +## T13 Scene / RuntimeLoop 补齐 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P1` +- 写入范围: `docs/api/XCEngine/Scene/RuntimeLoop/**` +- 主要源码依据: `engine/include/XCEngine/Scene/RuntimeLoop.h`、`engine/src/Scene/RuntimeLoop.cpp`、`editor/src/Core/PlaySessionController.h`、`tests/Scene/test_runtime_loop.cpp` +- 当前缺口: 已建立 `RuntimeLoop` canonical 页面，并把 fixed step / pause / step-frame 语义并入 `Scene` 模块导航 +- 完成标准: 建立 `RuntimeLoop` 类型页，说明 fixed step / max delta / max fixed steps 这些设置的语义，以及它与 play mode、scene tick 生命周期的关系 + +## T14 Core / Asset 服务与索引尾项补齐 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P1` +- 写入范围: `docs/api/XCEngine/Core/Asset/AssetImportService/**`、`docs/api/XCEngine/Core/Asset/ProjectAssetIndex/**`、必要时补充 `docs/api/XCEngine/Core/Asset/Asset.md` +- 主要源码依据: `engine/include/XCEngine/Core/Asset/AssetImportService.h`、`engine/src/Core/Asset/AssetImportService.cpp`、`engine/include/XCEngine/Core/Asset/ProjectAssetIndex.h`、`engine/src/Core/Asset/ProjectAssetIndex.cpp`、`tests/core/Asset/test_resource_manager.cpp` +- 当前缺口: 已补齐 `AssetImportService`、`ProjectAssetIndex` 两个 canonical 页面，并把它们补入 `Core/Asset` 模块总览 +- 完成标准: 建立两个类型页，写清楚 `AssetDatabase -> AssetImportService -> ProjectAssetIndex -> ResourceManager` 这条项目资产查询链路 + +## 二次审核结论（2026-04-02 23:31:03） + +- 本轮全量结构审计已执行: `python docs/api/_tools/audit_api_docs.py` +- 当前结构性问题为 `0`: 无失效 `.md` 链接、无非 `.md` 相对链接、无旧模板页面、无扁平 header 页面、无缺失目录总览页 +- 当前剩余覆盖缺口: `0` 个 public headers 未覆盖 +- 审计口径说明: + - 当前 `docs/api/_meta/rebuild-status.md` 的覆盖口径仍是 `engine/include/XCEngine` 的 public headers。 + - `Editor` 下基于 `editor/src/**` 的源文件页、方法页颗粒度，以及说明性内容是否跟随源码重构同步，仍需要人工复核。 +- 抽样确认出的实际遗留问题: + - `Editor/Application` 目录当前只有 `Application.md`，`ReloadScriptingRuntime()`、`RebuildScriptingAssemblies()`、`GetScriptRuntimeStatus()` 只在总览页有概述，缺少按商业级 API 文档颗粒度拆出的独立方法页。 + - `Editor/panels/SceneViewPanel` 目录当前只有 `SceneViewPanel.md`，尚未把 pivot / center、global / local、scene icon 命中优先级、transient overlay 注入链路拆开讲透。 + +## T15 Components / MeshRendererComponent 内容同步 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P0` +- 写入范围: `docs/api/XCEngine/Components/MeshRendererComponent/**`、必要时 `docs/api/XCEngine/Components/Components.md` +- 主要源码依据: `engine/include/XCEngine/Components/MeshRendererComponent.h`、`engine/src/Components/MeshRendererComponent.cpp`、`tests/Components/test_mesh_render_components.cpp` +- 当前缺口: 已核对 `MeshRendererComponent.md`、`Serialize.md`、`Deserialize.md`、`GetMaterial.md`、`GetMaterialHandle.md`、`SetMaterialPath.md` 与 `Components.md`；文档已覆盖 `materialPaths + materialRefs` 双轨序列化、deferred async material load 与首次访问触发加载的当前行为 +- 完成标准: 重写 `MeshRendererComponent.md`、`Serialize.md`、`Deserialize.md`、`GetMaterial.md`、`GetMaterialHandle.md`、`SetMaterialPath.md` 等核心页面，写清楚 deferred load、asset ref 回填与测试覆盖 + +## T16 Scripting / ScriptEngine 固定步长配置补齐 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P0` +- 写入范围: `docs/api/XCEngine/Scripting/ScriptEngine/**`、必要时 `docs/api/XCEngine/Scripting/Scripting.md`、`docs/api/_guides/Scripting/**` +- 主要源码依据: `engine/include/XCEngine/Scripting/ScriptEngine.h`、`engine/src/Scripting/ScriptEngine.cpp`、`tests/scripting/test_script_engine.cpp` +- 当前缺口: 已补齐 `SetRuntimeFixedDeltaTime()`、`GetRuntimeFixedDeltaTime()`、`DefaultFixedDeltaTime` 页面，并把 fixed delta 配置、运行时启停复位语义与 `OnFixedUpdate()` 的关系补入 `ScriptEngine` 与 `Scripting` 总览 +- 完成标准: 补齐固定步长相关页面，并写清楚它与 `OnFixedUpdate()`、运行时启动/停止、脚本类重绑定之间的关系 + +## T17 Editor / Application 脚本运行时方法页补齐 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P1` +- 写入范围: `docs/api/XCEngine/Editor/Application/**`、必要时 `docs/api/XCEngine/Editor/Scripting/**` +- 主要源码依据: `editor/src/Application.h`、`editor/src/Application.cpp`、`editor/src/Scripting/EditorScriptAssemblyBuilder.h`、`editor/src/Scripting/EditorScriptRuntimeStatus.h`、`tests/Editor/test_editor_script_assembly_builder.cpp` +- 当前缺口: 已补齐 `ReloadScriptingRuntime()`、`RebuildScriptingAssemblies()`、`GetScriptRuntimeStatus()` 独立页面，并补入“程序集缺失时如何降级到不可用状态”的明确说明 +- 完成标准: 为上述方法补齐独立页面，写清楚构建成功/失败路径、Mono 后端缺失时的回退、状态快照如何供 Inspector/脚本 UI 消费 + +## T18 Editor / SceneViewPanel 交互语义深化 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P1` +- 写入范围: `docs/api/XCEngine/Editor/panels/SceneViewPanel/**`、必要时 `docs/api/XCEngine/Editor/Viewport/**`、`docs/api/_guides/Editor/**` +- 主要源码依据: `editor/src/panels/SceneViewPanel.h`、`editor/src/panels/SceneViewPanel.cpp`、`editor/src/Viewport/SceneViewportOverlayHandleBuilder.h`、`editor/src/Viewport/SceneViewportOverlayHitTester.h`、`editor/src/Viewport/IViewportHostService.h` +- 当前缺口: 已重写 `SceneViewPanel.md`，并新增 `SceneView Interaction And Gizmo Model` guide；文档已明确 pivot / center 的计算依据、global / local 轴向语义、scene icon 与 gizmo 的命中优先级，以及 cached / interaction / transient 三层 overlay 数据流 +- 完成标准: 把 Scene View 交互模型补成商业级说明，尤其是 selection pivot、transform space、overlay hit-test 与 scene icon 选择这几条链路 + +## T19 审计工具口径扩展 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P2` +- 写入范围: `docs/api/_tools/audit_api_docs.py`、必要时 `docs/api/_meta/rebuild-status.md` +- 主要源码依据: 当前审计脚本口径与 `docs/api/XCEngine/Editor/**` 的实际页面分布 +- 当前缺口: 自动审计目前能确认 public headers 与链接结构，但无法自动暴露 `Editor` 源文件页是否缺少方法页，也无法报告像 `Application`、`SceneViewPanel` 这种“只有总览页”的高风险目录 +- 完成标准: 让审计结果至少能额外报告 source-file 页覆盖概况或方法页缺口统计，降低后续人工抽样成本 + +## T20 二次内容收口与最终复核 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P2` +- 写入范围: `docs/api/_meta/rebuild-status.md`、`docs/plan/API文档并行更新任务池_2026-04-02.md`、必要时受影响的模块总览页 +- 主要源码依据: `T15-T19` 的完成结果 +- 当前缺口: 已在 `2026-04-03 00:16:11` 重新执行 `python docs/api/_tools/audit_api_docs.py` 并回写 `rebuild-status.md`；结构性问题继续保持 `0`，`246/246` public headers 与 `120/120` Editor source headers 继续全量覆盖；审计中的 `Editor 高风险单页目录数: 19` 属于启发式抽样信号，不等同于仍有 19 处缺页 +- 完成标准: 在 `T15-T19` 完成后重新执行结构审计与人工抽样复核，把新的结论写回进度表 + +## 收口结论（2026-04-03 00:16:11） + +- 本轮收口审计已执行: `python docs/api/_tools/audit_api_docs.py` +- 当前结构性问题继续为 `0`: + - 无失效 `.md` 链接 + - 无非 `.md` 相对链接 + - 无旧模板页面 + - 无扁平 header 页面 + - 无失效 header / source ref +- 当前覆盖状态: + - public headers `246/246` + - Editor source headers `120/120` +- 本轮内容级收口结果: + - `MeshRendererComponent` 内容同步已完成 + - `ScriptEngine` 固定步长配置页已补齐 + - `Application` 脚本运行时方法页已补齐 + - `SceneViewPanel` 交互语义与 guide 已补齐 +- 审计提示解释: + - `Editor 高风险单页目录数: 19` 是新增启发式报告，用于提示“目录只有单页但实现较大，建议继续人工抽样” + - 它不是“当前仍缺 19 个 canonical 页面”的等价表达 + +## 三次审核结论（2026-04-03 00:24:08） + +- 已重新执行 `python docs/api/_tools/audit_api_docs.py` +- 当前结构性问题仍为 `0` + - public headers `246/246` + - Editor source headers `120/120` + - 失效 `.md` 链接 `0` + - 无效 header / source ref `0` +- 本轮新增问题不在“结构覆盖”，而在“内容与源码同步” +- 经过 `git diff`、源码抽样与文档抽样，当前确认的内容级缺口有： + - `Input/InputManager` 文档已失准 + - `Input.md` / `InputManager.md` 仍把 `GetAxisRaw()` 解释成“按下边沿”语义 + - `GetButtonUp()` 的未注册按钮返回值说明仍是旧行为 + - 缺少 `IsKeyReleased.md`、`IsMouseButtonReleased.md`、`IsAnyKeyDown.md`、`IsAnyKeyPressed.md` + - `Editor` 的 Game View 输入桥接链路没有写完整 + - [GameViewPanel](../api/XCEngine/Editor/panels/GameViewPanel/GameViewPanel.md) 还在按“薄视口壳层”描述 + - [EditorEvents](../api/XCEngine/Editor/Core/EditorEvents/EditorEvents.md) 还没纳入 `GameViewInputFrameEvent` + - `GameViewPanel -> EventBus -> PlaySessionController -> InputManager` 这条运行时输入链路没有统一说明 + - `Editor` 项目工作流文档落后于当前功能 + - [MainMenuActionRouter](../api/XCEngine/Editor/Actions/MainMenuActionRouter/MainMenuActionRouter.md) 未写 `Scripts` 菜单与“迁移场景资产引用” + - [ProjectCommands](../api/XCEngine/Editor/Commands/ProjectCommands/ProjectCommands.md) 未写 `MigrateSceneAssetReferences` + - [IProjectManager](../api/XCEngine/Editor/Core/IProjectManager/IProjectManager.md) / [ProjectManager](../api/XCEngine/Editor/Managers/ProjectManager/ProjectManager.md) 未写迁移报告结构与批量重写场景流程 + - `Core/Asset` 局部页存在陈旧说明 + - [AssetDatabase](../api/XCEngine/Core/Asset/AssetDatabase/AssetDatabase.md) 仍提到已不存在的 `ResourceManager::m_ioMutex` + - 新增的 artifact 依赖快照、`BuildLookupSnapshot()` 热路径、`AssetImportService + ProjectAssetIndex` 分层关系需要再校对一次叙述是否完全一致 + - `Scripting` 虽已补齐 fixed delta 页面，但托管输入桥接与类发现/类切换行为还没有在模块页和 guide 层讲透 +- 另外有一个文档组织问题需要收口： + - `docs/api/_guides/Editor/Scene-View-Interaction-Model.md` + - `docs/api/_guides/Editor/SceneView-Interaction-And-Gizmo-Model.md` + - 这两篇主题重叠，当前链接入口分叉，需统一 canonical guide +- `Editor 高风险单页目录数: 19` 仍保留为抽样队列，不等同于这 19 处都已确认失准 + +## T21 Input / InputManager 内容校准与方法补页 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P0` +- 写入范围: `docs/api/XCEngine/Input/**`、必要时 `docs/api/_guides/Input/**` +- 主要源码依据: `engine/include/XCEngine/Input/InputManager.h`、`engine/src/Input/InputManager.cpp`、`tests/Input/test_input_manager.cpp` +- 当前缺口: + - 已重写 `Input.md`、`InputManager.md` 与 `Input-Flow-and-Frame-Semantics.md` + - 已补齐 `IsKeyReleased.md`、`IsMouseButtonReleased.md`、`IsAnyKeyDown.md`、`IsAnyKeyPressed.md` + - 文档已按当前源码校正 `GetAxisRaw()`、`GetButtonUp()`、`ProcessKeyUp()`、`ProcessMouseButton()` 与 `Update()` 的帧语义 + - 已进一步补充 `IsKeyPressed()` / `GetButtonDown()` / `IsAnyKeyPressed()` 的 `repeat` 语义，以及 `IsKeyUp()` / `IsMouseButtonUp()` 和释放边沿接口的区别 +- 完成标准: 重写模块页与类型页，补齐 4 个方法页，并把键鼠释放态、any-key 语义、默认映射和测试覆盖按当前源码写清楚 + +## T22 Editor / Game View 输入桥接链路补写 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P0` +- 写入范围: `docs/api/XCEngine/Editor/panels/GameViewPanel/**`、`docs/api/XCEngine/Editor/Core/EditorEvents/**`、`docs/api/XCEngine/Editor/Core/PlaySessionController/**`、必要时 `docs/api/_guides/Editor/**` +- 主要源码依据: `editor/src/panels/GameViewPanel.cpp`、`editor/src/Core/EditorEvents.h`、`editor/src/Core/PlaySessionController.h`、`editor/src/Core/PlaySessionController.cpp`、`tests/editor/test_play_session_controller.cpp` +- 当前缺口: + - 已重写 `GameViewPanel.md`，补入 ImGui 键鼠采集、逐帧发布 `GameViewInputFrameEvent` 与空事件释放语义 + - `EditorEvents.md` 已纳入 `GameViewInputFrameEvent` + - `PlaySessionController.md` 已明确“只有运行态 `Update()` 才会把 Game View 输入桥接到 `InputManager`”及 `hovered/focused` 门控规则 + - 已补齐 `GameViewPanel/Constructor.md` 与 `GameViewPanel/Render.md` + - 已新增 `docs/api/_guides/Editor/Game-View-Runtime-Input-Bridge.md`，把 `GameViewPanel -> EventBus -> PlaySessionController -> InputManager` 收口成单条连续说明 +- 完成标准: 把 `GameViewPanel -> EventBus -> PlaySessionController -> InputManager` 这条桥接链路写成一组可追踪的 API 文档，明确 `hovered/focused`、键鼠状态快照与帧边界 + +## T23 Editor / 项目工作流与脚本菜单同步 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P0` +- 写入范围: `docs/api/XCEngine/Editor/Actions/MainMenuActionRouter/**`、`docs/api/XCEngine/Editor/Actions/EditorActions/**`、`docs/api/XCEngine/Editor/Actions/ProjectActionRouter/**`、`docs/api/XCEngine/Editor/Commands/ProjectCommands/**`、`docs/api/XCEngine/Editor/Core/IProjectManager/**`、`docs/api/XCEngine/Editor/Managers/ProjectManager/**`、必要时 `docs/api/XCEngine/Editor/panels/ProjectPanel/**` +- 主要源码依据: `editor/src/Actions/MainMenuActionRouter.h`、`editor/src/Commands/ProjectCommands.h`、`editor/src/Core/IProjectManager.h`、`editor/src/Managers/ProjectManager.h`、`editor/src/Managers/ProjectManager.cpp`、`tests/editor/test_action_routing.cpp` +- 当前缺口: + - 已重写 `MainMenuActionRouter.md`，补入 `Scripts` 菜单、`Migrate Scene AssetRefs` 文件菜单入口，以及菜单到 `ProjectCommands` / `EventBus` 的下游链路 + - 已重写 `ProjectCommands.md`，补入 `RebuildScriptAssemblies`、`MigrateSceneAssetReferences`、`SwitchProject` 与 `SaveProject` 的真实 guard 和执行流程 + - 已重写 `IProjectManager.md` / `ProjectManager.md`，补入 `SceneAssetReferenceMigrationReport` 结构、`Assets/**/*.xc` 批量迁移流程、`ResourceManager::ScopedDeferredSceneLoad` 与日志/刷新语义 + - 已进一步补充“菜单层不消费返回值”“脚本重建产物不在 `ProjectPanel` 视图内”“`.meta` sidecar 跟随规则”“迁移报告只给汇总计数”的边界说明 + - 已校对 `ProjectPanel.md` 与 `EditorActions.md`，明确面板只消费资源级命令，而项目保存 / 脚本重建 / 场景迁移入口位于主菜单 +- 完成标准: 把项目工作流文档升级到“菜单入口 -> command -> manager -> 场景重写报告”的完整链路，并校对 `ProjectPanel` 对这些命令的消费关系 + +## T24 Core / AssetDatabase 与项目资产快照链路复核 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P1` +- 写入范围: `docs/api/XCEngine/Core/Asset/AssetDatabase/**`、`docs/api/XCEngine/Core/Asset/ResourceManager/**`、必要时 `docs/api/XCEngine/Core/Asset/Asset.md` +- 主要源码依据: `engine/include/XCEngine/Core/Asset/AssetDatabase.h`、`engine/src/Core/Asset/AssetDatabase.cpp`、`engine/include/XCEngine/Core/Asset/ResourceManager.h`、`engine/src/Core/Asset/ResourceManager.cpp`、`engine/src/Resources/Material/MaterialLoader.cpp`、`tests/core/Asset/test_resource_manager.cpp` +- 当前缺口: + - 已移除 `AssetDatabase.md` 中陈旧的 `m_ioMutex` 叙述，并改成当前 `AssetImportService::recursive_mutex` 的真实封装关系 + - 已重写 `BuildLookupSnapshot()`、`TryGetAssetRef()`、`EnsureArtifact()` 和 `Asset.md` 中关于 snapshot 消费链路、cache miss 自刷新和 artifact 导入边界的说明 + - 已补入材质纹理绑定依赖、`.obj -> .mtl -> texture` 依赖快照，以及 `BuildLookupSnapshot()` 只导出主资产 path/GUID 表而不导出 artifact 路径的语义 + - 已继续重写 `ResourceManager` 下残留的通用占位方法页，补齐 `Get()`、`AddRef()/Release()`、`Find()/Exists()`、`Unload*()`、`ResolvePath()`、`LoadGroup()` 等真实行为与当前限制 +- 完成标准: 把 `AssetDatabase -> ResourceManager` 的当前链路与依赖快照行为写实，并消除与 `AssetImportService` / `ProjectAssetIndex` 相关的陈旧描述 + +## T25 Scripting / 托管输入桥接与类发现链路补强 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P1` +- 写入范围: `docs/api/XCEngine/Scripting/**`、必要时 `docs/api/_guides/Scripting/**` +- 主要源码依据: `engine/include/XCEngine/Scripting/IScriptRuntime.h`、`engine/include/XCEngine/Scripting/Mono/MonoScriptRuntime.h`、`engine/include/XCEngine/Scripting/NullScriptRuntime.h`、`engine/include/XCEngine/Scripting/ScriptComponent.h`、`engine/include/XCEngine/Scripting/ScriptEngine.h`、对应 `.cpp`、`managed/XCEngine.ScriptCore/Input.cs`、`managed/XCEngine.ScriptCore/Time.cs`、`managed/XCEngine.ScriptCore/KeyCode.cs`、`tests/scripting/test_mono_script_runtime.cpp`、`tests/scripting/test_script_engine.cpp` +- 当前缺口: + - 已重写 `Scripting.md`、`ScriptEngine.md` 与 `MonoScriptRuntime.md`，把托管 `Input` / `Time` internal call、`Time.fixedDeltaTime` 配置来源，以及 `InputManager` 消费边界收口到同一条说明链。 + - 已补强 `TryGetAvailableScriptClasses()`、`SetScriptClass()`、`ClearScriptClass()` 与 `IScriptRuntime` 契约页，明确排序、按程序集过滤、项目程序集发现和类切换重建语义。 + - 已重写两篇 `Scripting` guide，把 `project/Assets/**/*.cs -> GameScripts.dll -> ScriptClassDescriptor -> ScriptComponent::SetScriptClass()` 以及运行时切类后的实例销毁/重建流程串成连续入口。 +- 完成标准: 在不扩散成两套文档体系的前提下，把原生 `ScriptEngine`、Mono internal call、项目脚本类发现与类切换重建写成一组连续说明 + +## 四次审核结论（2026-04-03 11:39:21） + +- 已重新执行 `python docs/api/_tools/audit_api_docs.py` +- 当前结构性问题继续为 `0` + - public headers `246/246` + - Editor source headers `121/121` + - 失效 `.md` 链接 `0` + - 无效 header / source ref `0` +- 本轮新增与收口结果: + - `EditorConsoleSink` 已从单页目录重构为“类型页 + record 页 + 方法页” + - `ConsoleFilterState` 已按真实字段与别名关系重写 + - 工作树新增的 `editor/src/Viewport/SceneViewportTransformGizmoFrameBuilder.h` 已补入 canonical 文档树 +- 审计抽样结果: + - `Editor 高风险单页目录数` 已从 `14` 下降到 `10` + - `ConsolePanel` 与 `EditorConsoleSink` 已移出高风险单页目录清单 + - 当前剩余抽样池见 `T26` + +## 五次审核结论（2026-04-03 11:56:30） + +- 已重新执行 `python docs/api/_tools/audit_api_docs.py` +- 当前结构性问题继续为 `0` + - public headers `246/246` + - Editor source headers `121/121` + - 失效 `.md` 链接 `0` + - 无效 header / source ref `0` +- 本轮新增与收口结果: + - 已补齐 `GameViewPanel/Constructor.md` 与 `GameViewPanel/Render.md` + - 已新增 `Game View Runtime Input Bridge` guide，并把 `GameViewPanel`、`EditorEvents`、`PlaySessionController` 和 `Editor-Architecture-And-Workflow` 串成统一入口 +- 审计抽样结果: + - `Editor 高风险单页目录数` 已从 `10` 下降到 `5` + - 当前剩余抽样池已进一步收缩到 `Viewport gizmo + SceneManager` + +## 六次审核结论（2026-04-03 12:00:34） + +- 已重新执行 `python docs/api/_tools/audit_api_docs.py` +- 当前结构性问题继续为 `0` + - public headers `246/246` + - Editor source headers `121/121` + - 失效 `.md` 链接 `0` + - 无效 header / source ref `0` +- 本轮新增与收口结果: + - 已重写 `SceneManager.md`，并补齐实体编辑、场景文件生命周期、快照恢复相关方法页 + - `ISceneManager.md` 已按当前实现职责更新接口说明 +- 审计抽样结果: + - `Editor 高风险单页目录数` 已从 `5` 下降到 `0` + - `T26` 对应的启发式抽样队列已全部清空 + +## T26 Editor / 高风险单页目录抽样复核队列 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P2` +- 写入范围: `docs/api/XCEngine/Editor/Managers/SceneManager/**`、`docs/api/XCEngine/Editor/Viewport/SceneViewportMoveGizmo/**`、`docs/api/XCEngine/Editor/Viewport/SceneViewportRotateGizmo/**`、`docs/api/XCEngine/Editor/Viewport/SceneViewportScaleGizmo/**`、`docs/api/XCEngine/Editor/Viewport/SceneViewportOrientationGizmo/**` +- 主要源码依据: `docs/api/_meta/rebuild-status.md` 中的高风险单页目录清单及对应 `editor/src/**` +- 当前缺口: + - `2026-04-03 12:00:34` 这轮复核后，审计中的 `Editor 高风险单页目录数` 已下降到 `0`。 + - 启发式抽样队列已收口完成，当前不再保留剩余目录。 +- 完成标准: 至少抽样复核一遍源码与现有页面；若发现失准则直接重写，若确认足够则在任务认领记录里注明“已复核” + +## T27 Editor / Scene View 交互 guide 去重与入口收口 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P2` +- 写入范围: `docs/api/_guides/Editor/Scene-View-Interaction-Model.md`、`docs/api/_guides/Editor/SceneView-Interaction-And-Gizmo-Model.md`、以及所有引用这两篇 guide 的 API 页面 +- 主要依据: 当前 guide 内容本身与 `SceneViewPanel` / `IViewportHostService` / `ViewportHostService` / `Viewport.md` 的交叉链接分布 +- 当前缺口: + - 已确认 `SceneView-Interaction-And-Gizmo-Model.md` 作为唯一 canonical guide；旧 `Scene-View-Interaction-Model.md` 保留为兼容入口页，只负责跳转说明。 + - 已把残留的业务页引用统一切到 canonical guide，当前仓库里已无 API 页面继续把旧 guide 当主入口。 +- 完成标准: 统一保留一个 canonical guide 或明确拆分两篇职责，并把全部入口链接收口到一致命名 + +## 四次审核结论（2026-04-03 11:44:52） + +- 已重新执行 `python docs/api/_tools/audit_api_docs.py` +- 当前结构性问题仍为 `0` + - public headers `246/246` + - Editor source headers `121/121` + - 失效 `.md` 链接 `0` + - 无效 header / source ref `0` +- 本轮新增收口结果: + - `T21 Input / InputManager` 已补充 `Pressed` / `Up` / `Released` / `repeat` 的内容级语义说明 + - `Input-Flow-and-Frame-Semantics.md` 已提升为面向接入与设计理解的 canonical guide +- 当前自动审计提示: + - `Editor high-risk single-page dirs: 10` + - 这仍是人工抽样优先队列，不等同于已经确认存在 10 处失准 +- 后续并行优先级建议保持为: + - `T23` + - `T24` / `T25` + - `T26` / `T27` + +## 五次审核结论（2026-04-03 11:53:48） + +- 已重新执行 `python docs/api/_tools/audit_api_docs.py` +- 当前结构性问题仍为 `0` + - public headers `246/246` + - Editor source headers `121/121` + - 失效 `.md` 链接 `0` + - 无效 header / source ref `0` +- 本轮新增收口结果: + - `T23 Editor / 项目工作流与脚本菜单同步` 已继续补强内容级说明 + - 已明确主菜单层只负责触发项目维护动作，不消费 `RebuildScriptAssemblies` / `MigrateSceneAssetReferences` 的返回结果 + - 已明确 `ProjectPanel` 只投影 `/Assets`，因此脚本重建成功后不保证出现可见树变化 + - 已明确 `ProjectManager` 的 `.meta` sidecar 跟随语义、resource root 临时切换 / 恢复，以及迁移报告只提供汇总计数 +- 当前自动审计提示: + - `Editor high-risk single-page dirs: 6` + - 仍属于人工抽样队列，不等同于已经确认失准 +- 后续并行优先级建议调整为: + - `T24` / `T25` + - `T26` + - `T27` + +## 六次审核结论（2026-04-03 11:57:51） + +- 已重新执行 `python docs/api/_tools/audit_api_docs.py` +- 当前结构性问题仍为 `0` + - public headers `246/246` + - Editor source headers `121/121` + - 失效 `.md` 链接 `0` + - 无效 header / source ref `0` +- 本轮新增收口结果: + - `T24 Core / AssetDatabase 与项目资产快照链路复核` 已完成 + - 已修正 `AssetDatabase` 的锁模型、`BuildLookupSnapshot()` 的真实消费链路、`TryGetAssetRef()` 与 `EnsureArtifact()` 的职责边界 + - 已把材质贴图依赖与模型依赖快照的真实采集方式补入文档 +- 当前自动审计提示: + - `Editor high-risk single-page dirs: 4` + - 仍属于人工抽样队列，不等同于已经确认失准 + +## 七次审核结论（2026-04-03 12:16:18） + +- 已重新执行 `python docs/api/_tools/audit_api_docs.py` +- 当前结构性问题仍为 `0` + - public headers `246/246` + - Editor source headers `121/121` + - 失效 `.md` 链接 `0` + - 无效 header / source ref `0` +- 本轮新增收口结果: + - `T24` 已继续补齐 `ResourceManager` 目录下残留的占位方法页 + - `ResolvePath()`、`Exists()/Find()`、`Unload*()`、`LoadGroup()` 等方法页已改成按源码解释当前行为与限制 +- 当前自动审计提示: + - `Editor high-risk single-page dirs: 0` + - 当前追踪表中的内容级收口任务已全部落地 +- 后续并行优先级建议调整为: + - `T25` + - `T26` + - `T27` + +## 八次审核结论（2026-04-03 12:21:03） + +- 已重新执行 `python docs/api/_tools/audit_api_docs.py` +- 当前结构性问题仍为 `0` + - public headers `246/246` + - Editor source headers `121/121` + - 失效 `.md` 链接 `0` + - 无效 header / source ref `0` +- 本轮新增收口结果: + - `T25 Scripting / 托管输入桥接与类发现链路补强` 已完成最后一轮内容级重写 + - 已把托管 `Input` / `Time` internal call、`Time.fixedDeltaTime` 配置来源、`TryGetAvailableScriptClasses()` 的排序与按程序集过滤语义、`SetScriptClass()` / `ClearScriptClass()` 的运行时重建链路补入模块页、类型页与 guide + - `MonoScriptRuntime` 与两篇 `Scripting` guide 已明确项目脚本程序集入口、类发现约束、字段默认值与本地覆盖同步的设计边界 +- 当前自动审计提示: + - `Editor high-risk single-page dirs: 0` + - 当前任务池中的内容级收口任务已全部完成 +- 后续并行优先级建议调整为: + - 跟踪后续源码新增 API + - 发现新的内容失准后再按模块开新任务 + - 保持 `docs/api/_meta/rebuild-status.md` 的周期性审计回写 + +## T28 Rendering / BuiltinForwardPipeline 资源契约与描述符布局同步 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P1` +- 写入范围: `docs/api/XCEngine/Rendering/Pipelines/BuiltinForwardPipeline/**`、必要时 `docs/api/XCEngine/Rendering/Pipelines/Pipelines.md`、`docs/api/XCEngine/Rendering/Rendering.md` +- 主要源码依据: `engine/include/XCEngine/Rendering/Pipelines/BuiltinForwardPipeline.h`、`engine/src/Rendering/Pipelines/BuiltinForwardPipeline.cpp`、`tests/Rendering/unit/test_builtin_forward_pipeline.cpp` +- 当前缺口: + - 已重写 `BuiltinForwardPipeline.md`、`Initialize.md`、`Render.md`、`Shutdown.md`，把 `RenderPassSequence`、`PassResourceLayout`、动态/静态 descriptor set 分流与 legacy binding 回退补齐到当前实现。 + - 已新增 `Constructor.md` 与 `BuildInputLayout.md`，补齐公开构造入口和 `StaticMeshVertex` 输入布局契约。 + - 已新增 `BuiltinForwardPipelineAsset/BuiltinForwardPipelineAsset.md`、`BuiltinForwardPipelineAsset/CreatePipeline.md`，补清默认 pipeline asset 工厂与 runtime pipeline 的衔接关系。 + - 已更新 `Pipelines.md`、`RenderPipeline.md`、`RenderPipelineAsset.md`、`RenderPipelineAsset/CreatePipeline.md`、`Rendering.md` 与渲染 guide，使 `ForwardLit` 资源契约、`visibleItems` 和默认 pipeline asset 链路保持一致。 +- 完成标准: 把 `BuiltinForwardPipeline` 类型页与核心方法页重写到当前实现，明确 shader pass 资源契约、descriptor set 生命周期、legacy 回退语义和当前限制 + +## T29 Rendering / SceneRenderer 与 RenderSceneExtractor 口径复核 + +- 状态: `DONE` +- 认领人: `Codex` +- 优先级: `P1` +- 写入范围: `docs/api/XCEngine/Rendering/SceneRenderer/**`、`docs/api/XCEngine/Rendering/RenderSceneExtractor/**`、`docs/api/XCEngine/Rendering/VisibleRenderObject/**` +- 主要源码依据: `engine/include/XCEngine/Rendering/SceneRenderer.h`、`engine/src/Rendering/SceneRenderer.cpp`、`engine/include/XCEngine/Rendering/RenderSceneExtractor.h`、`engine/src/Rendering/RenderSceneExtractor.cpp`、`tests/Rendering/unit/test_camera_scene_renderer.cpp`、`tests/Rendering/unit/test_scene_render_request_planner.cpp` +- 当前缺口: + - 已重写 `SceneRenderer.md`、`Constructor.md`、`Destructor.md`、`SetPipeline.md`、`GetPipeline.md`、`Render.md`，纠正“`SceneRenderer` 直接做 scene extraction / 直接创建 `BuiltinForwardPipeline`”的旧口径。 + - 已新增 `BuildRenderRequests.md`、`SetPipelineAsset.md`、`GetPipelineAsset.md`，补齐 `SceneRenderer` 当前公开方法页。 + - 已重写 `RenderSceneExtractor.md` 与 `Extract.md`，并新增 `ExtractForCamera.md`、`SelectCamera.md`，把 `visibleItems`、相机选择、光照提取与排序规则同步到当前实现。 + - 已重写 `VisibleRenderObject.md`，把它明确为 `VisibleRenderItem` 的兼容别名入口，并补齐 `material / section / renderQueue / cameraDistanceSq` 等当前字段。 +- 完成标准: 把 `SceneRenderer` 更新为“请求规划 + 转发到 `CameraRenderer`”的真实职责模型；把 `RenderSceneExtractor` 更新为 `visibleItems` 与当前排序 / 相机选择语义 + +## 九次审核结论（2026-04-03 13:30:05） + +- 已重新执行 `python docs/api/_tools/audit_api_docs.py` +- 当前结构性问题仍为 `0` + - public headers `246/246` + - Editor source headers `121/121` + - 失效 `.md` 链接 `0` + - 无效 header / source ref `0` +- 本轮新增收口结果: + - `T28 Rendering / BuiltinForwardPipeline 资源契约与描述符布局同步` 已完成 + - 已补齐 `BuiltinForwardPipeline/Constructor.md`、`BuiltinForwardPipeline/BuildInputLayout.md` 与 `BuiltinForwardPipelineAsset` 类目录 + - 已把默认 `BuiltinForwardPipelineAsset -> BuiltinForwardPipeline -> CameraRenderer` 链路补入 `Pipelines`、`RenderPipelineAsset`、`RenderPipeline`、`Rendering` 与 rendering guide +- 当前自动审计提示: + - `Editor high-risk single-page dirs: 0` + - 当前 canonical API 树与 public headers / Editor source headers 仍保持全量覆盖 + +## 备注 + +- `T01-T20` 当前已全部完成 +- `T21-T27` 当前也已全部完成 +- 下一阶段重点已经从“补历史缺页”切换为“跟踪源码新增行为并持续校正文档内容” diff --git a/docs/plan/C#脚本模块的设计与实现.md b/docs/used/C#脚本模块的设计与实现_阶段一归档_2026-04-03.md similarity index 99% rename from docs/plan/C#脚本模块的设计与实现.md rename to docs/used/C#脚本模块的设计与实现_阶段一归档_2026-04-03.md index 96774f1d..87272c1a 100644 --- a/docs/plan/C#脚本模块的设计与实现.md +++ b/docs/used/C#脚本模块的设计与实现_阶段一归档_2026-04-03.md @@ -1,5 +1,7 @@ # C#脚本模块的设计与实现 +日期：3.27 + ## 1. 背景 XCEngine 的整体方向是模仿传统 Unity 引擎架构，而不是 DOTS/ECS-first 路线。 diff --git a/docs/plan/EditorViewport宿主渲染收口总结4.1.md b/docs/used/EditorViewport宿主渲染收口总结4.1.md similarity index 100% rename from docs/plan/EditorViewport宿主渲染收口总结4.1.md rename to docs/used/EditorViewport宿主渲染收口总结4.1.md diff --git a/docs/issues/Editor模块_CMake直链Release版XCEngine库破坏配置一致性3.28.md b/docs/used/Editor模块_CMake直链Release版XCEngine库破坏配置一致性3.28.md similarity index 100% rename from docs/issues/Editor模块_CMake直链Release版XCEngine库破坏配置一致性3.28.md rename to docs/used/Editor模块_CMake直链Release版XCEngine库破坏配置一致性3.28.md diff --git a/docs/issues/Editor模块_宿主渲染与EngineRHI未统一导致Viewport纹理无法接入3.28.md b/docs/used/Editor模块_宿主渲染与EngineRHI未统一导致Viewport纹理无法接入3.28.md similarity index 100% rename from docs/issues/Editor模块_宿主渲染与EngineRHI未统一导致Viewport纹理无法接入3.28.md rename to docs/used/Editor模块_宿主渲染与EngineRHI未统一导致Viewport纹理无法接入3.28.md diff --git a/docs/issues/Editor模块_项目根路径仍绑定可执行目录阻塞真实场景与资源加载3.28.md b/docs/used/Editor模块_项目根路径仍绑定可执行目录阻塞真实场景与资源加载3.28.md similarity index 100% rename from docs/issues/Editor模块_项目根路径仍绑定可执行目录阻塞真实场景与资源加载3.28.md rename to docs/used/Editor模块_项目根路径仍绑定可执行目录阻塞真实场景与资源加载3.28.md diff --git a/docs/used/Editor资源缓存.png b/docs/used/Editor资源缓存.png new file mode 100644 index 00000000..255d23d4 Binary files /dev/null and b/docs/used/Editor资源缓存.png differ diff --git a/docs/plan/Editor重构3.26.md b/docs/used/Editor重构3.26.md similarity index 100% rename from docs/plan/Editor重构3.26.md rename to docs/used/Editor重构3.26.md diff --git a/docs/used/Library资产导入与缓存系统收口计划_完成归档_2026-04-03.md b/docs/used/Library资产导入与缓存系统收口计划_完成归档_2026-04-03.md new file mode 100644 index 00000000..6b254216 --- /dev/null +++ b/docs/used/Library资产导入与缓存系统收口计划_完成归档_2026-04-03.md @@ -0,0 +1,536 @@ +# Library资产导入与缓存系统收口计划 + +归档状态：2026-04-03，当前 `project` 范围内的 Library 导入与缓存系统收口已完成，本文档转为归档记录。 + +## 0. 文档定位 + +这份文档不是上一轮“从零搭一套 Unity 式 Library 体系”的继续描述，而是当前阶段的正式收口文档。 + +### 0.1 当前执行进度（2026-04-03） + +| 阶段 | 状态 | 当前结果 | +| --- | --- | --- | +| 阶段 A：协议定稿与旧兼容删除 | 已完成 | 已删除 `mesh=` / `materials=` 旧兼容读取，项目资产序列化正式收敛到 `AssetRef`，路径字段仅保留给虚拟资源；scene 迁移工具链已移除。 | +| 阶段 B：导入与缓存边界收口 | 已完成 | `AssetImportService` 已接管 Library 根目录、快照构建、缓存重建与 artifact 保证入口；`ProjectAssetIndex` 已只消费服务快照；`ResourceManager` 已收口为运行时缓存/异步调度入口，并提供 `RefreshProjectAssets` / `RebuildProjectAssetCache`。 | +| 阶段 C：进行中 | 已完成 `xcmat` 纹理绑定的 `AssetRef + lazy resolve` 首轮收口；下一步继续压缩缓存命中后的恢复成本，并检查是否还存在主线程等待点。 | +| 阶段 D：最小工具闭环 | 已完成 | 已完成 `Reimport Selected Asset / Reimport All Assets / Clear Library` 正式入口；已补 `Project` 面板最小导入状态输出；已接入 orphan artifact 清理。 | + +### 0.2 当前已完成的收口结果（2026-04-03） + +- 阶段 A 已完成并验证通过： + - `MeshFilterComponent` 对项目 mesh 只序列化 `meshRef`，`meshPath` 只保留给 `builtin://...` + - `MeshRendererComponent` 对项目 material 只序列化 `materialRefs`，`materialPaths` 只保留给 `builtin://...` + - 旧的 `mesh=` / `materials=` 兼容读取已移除 + - scene 迁移命令、菜单、report 链路已删除 +- 阶段 B 已完成并验证通过： + - `AssetImportService` 对外新增 `LookupSnapshot`、`ImportedAsset`、`GetLibraryRoot()`、`RebuildLibraryCache()` + - `ProjectAssetIndex` 不再直接拼装 `AssetDatabase` 细节，而是只刷新服务快照 + - `ResourceManager` 不再暴露旧式导入数据库心智，新增 `RefreshProjectAssets()`、`RebuildProjectAssetCache()`、`GetProjectLibraryRoot()` + - `AssetDatabase` 初始化后会落盘 `ArtifactDB/artifacts.db`，使空 Library 结构稳定成型 +- 阶段 C 已开始并完成首个子项： + - `Material` 纹理绑定新增稳定 `AssetRef` 元数据，运行时按需把 `AssetRef` 解析为加载路径 + - `xcmat` 协议已升级为纹理绑定写入 `AssetRef + load path hint` + - `AssetDatabase` importer version 已提升，旧 material artifact 将自动失效并重建 +- 阶段 D 已开始并完成首轮工具口： + - `AssetDatabase` 已新增 `TryGetImportableResourceType()`、`ReimportAsset()`、`ReimportAllAssets()` + - `AssetImportService` 已新增 `ClearLibraryCache()`、`ReimportAllAssets()`、`ReimportAsset()` + - `ResourceManager` 已新增 `CanReimportProjectAsset()`、`ReimportProjectAsset()`、`ClearProjectLibraryCache()` + - editor `Assets` 菜单已新增 `Reimport Selected Asset`、`Reimport All Assets`、`Clear Library` + - `AssetImportService` 已新增导入状态快照，`Project` 面板工具栏会显示最近一次导入/清库/清理状态 + - `AssetDatabase` 已新增 orphan artifact 清理，`Refresh / Reimport / 自动重导入` 后都会回收未被 `ArtifactDB` 引用的 `Library/Artifacts/*` 目录 +- 已完成 focused 验证： + - `asset_tests`： + - `ResourceManager_Test.ConcurrentAsyncLoadsCoalesceSameMeshPath` + - `ResourceManager_Test.AssetLookupFallbackRefreshesSnapshotForNewProjectAsset` + - `ProjectAssetIndex_Test.RefreshesSnapshotThroughImportServiceOnCacheMiss` + - `AssetImportService_Test.RebuildLibraryCacheKeepsStableAssetRefs` + - `ResourceManager_Test.RebuildProjectAssetCacheRefreshesLookupState` + - `AssetImportService_Test.ClearLibraryAndReimportAllAssetsManageArtifactsExplicitly` + - `AssetImportService_Test.ImportStatusTracksExplicitOperationsAndRefreshCleanup` + - `ResourceManager_Test.ReimportProjectAssetBuildsArtifactForSelectedPath` + - `editor_tests`： + - `EditorActionRoutingTest.ProjectCommandsExposeAssetCacheMaintenanceActions` + - `EditorActionRoutingTest.ProjectCommandsReimportSelectedAssetAndClearLibraryDriveAssetCache` + - `EditorActionRoutingTest.ProjectCommandsReportWhenScriptAssembliesCanBeRebuilt` + - `components_tests`： + - `MeshRendererComponent_Test.SerializeAndDeserializeLoadsProjectMaterialByAssetRef` + - `MeshRendererComponent_Test.DeferredSceneDeserializeLoadsProjectMaterialAsync` + - `material_tests`：46/46 通过 + - `mesh_tests`：33/33 通过 + - `scene_tests`： + - `Scene_ProjectSample.DeferredLoadBackpackSceneEventuallyRestoresBackpackMesh` + - `Scene_ProjectSample.DeferredLoadBackpackSceneEventuallyProducesVisibleRenderItems` + - `XCEditor` Release 已成功编译 + +旧方案文档已经归档到： + +- `docs/plan/used/Unity式Library资产导入与缓存系统重构方案.md` + +归档原因很简单： + +- 旧文档解决的是“从没有 Library，到建立 Library 基础设施”的问题。 +- 现在的问题已经不是“要不要做 Library”，而是“怎么把当前这套半过渡、半正式的实现收成一套干净的正式系统”。 + +本轮收口以以下前提为准： + +- 只服务当前 `project` 这一个项目。 +- 不兼容旧版本 scene / component 资产引用格式。 +- 不再提供旧格式迁移工具。 +- 可以直接改写 `project` 下现有场景和资源源文件。 +- 目标不是继续堆补丁，而是形成一套边界清晰、行为稳定、可长期维护的正式实现。 + +--- + +## 1. 当前收口基线 + +当前系统已经具备以下基础，这些不是本轮要推倒重来，而是本轮收口的起点： + +- 已有 Unity 风格的 `Library` 目录结构： + - `Library/SourceAssetDB` + - `Library/ArtifactDB` + - `Library/Artifacts` +- 已有 `.meta + AssetGUID` 机制，项目资产已经具备稳定身份。 +- 已有 `AssetRef` 结构，运行时已经可以通过 `AssetRef` 回查项目资产。 +- 已有纹理、材质、模型 artifact： + - `xctex` + - `xcmat` + - `xcmesh` +- 已有 `AssetImportService`，用于承接导入与 artifact 保证逻辑。 +- 已有 `ProjectAssetIndex`，用于承接项目资产路径与 `AssetRef` 快照索引。 +- `ResourceManager` 已不再直接承担全部导入数据库职责，而是开始回到运行时调度器角色。 +- scene 打开链路已经接入 deferred restore，`MeshFilterComponent` / `MeshRendererComponent` 能在反序列化后异步恢复项目资源。 +- 当前 `project/Assets/Scenes/Main.xc`、`project/Assets/Scenes/Backpack.xc` 已经具备 `AssetRef` 版本数据，可作为最终格式收口的直接修改对象。 + +当前真正没有收口的，不是“功能不存在”，而是下面这三类问题还在： + +- 还保留着旧格式兼容和双写逻辑。 +- 组件 / scene / editor 工具链里还残留过渡期代码。 +- 材质与贴图恢复仍不够轻，缓存命中后仍有额外同步成本。 + +--- + +## 2. 本轮收口的核心原则 + +### 2.1 不保留旧版本兼容 + +这是本轮与上一轮最大的区别。 + +本轮明确不做以下事情： + +- 不兼容历史 `mesh=` / `materials=` 场景字段。 +- 不兼容“项目资产仍按普通文件路径序列化”的旧格式。 +- 不保留 `path + AssetRef` 双写作为长期状态。 +- 不保留 `Migrate Scene AssetRefs` 之类的迁移工具与菜单。 + +允许保留的只有两类稳定引用： + +- `AssetRef` + - 用于 `project/Assets` 下的正式项目资产。 +- `builtin://...` + - 用于内置几何体、内置默认材质等虚拟内置资源。 + +这里的 `builtin://` 不是旧版本兼容，而是引擎内部稳定资源协议，可以继续保留。 + +### 2.2 只对当前项目做干净落地 + +因为当前只服务一个项目，所以这轮不需要为了“以后可能导入旧项目”保留复杂迁移链路。 + +本轮允许直接做以下事情： + +- 直接改写 `project/Assets/Scenes/*.xc` +- 直接删除旧序列化字段的读写逻辑 +- 直接删除旧迁移命令、菜单、报告结构 +- 直接调整测试数据到最终格式 + +### 2.3 运行时只负责“用缓存”，不负责“解释历史” + +收口完成后，运行时层要满足： + +- scene 反序列化只恢复最终格式数据 +- `ResourceManager` 只做运行时缓存、异步调度、artifact 读取入口 +- 导入与索引职责留在 `AssetImportService` / `ProjectAssetIndex` +- 不再在运行时主链路里背负旧协议兼容判断 + +### 2.4 收口优先级高于“继续设计更大系统” + +本轮目标是把现有系统收干净，不追求继续扩成更庞大的框架。 + +因此本轮只做两件事： + +- 删除过渡态 +- 补齐正式版闭环 + +不在本轮追求： + +- prefab 全面资产管线化 +- 动画、音频、shader 全类型导入器 +- 远程缓存 +- 多项目兼容框架 +- 一步到位把所有内部类都拆到最细 + +--- + +## 3. 收口后的目标形态 + +### 3.1 最终数据协议 + +收口后，scene / component 的资产引用协议定为： + +- 项目 mesh：只写 `meshRef` +- 项目 material：只写 `materialRefs` +- 内置 mesh：写 `meshPath=builtin://...` +- 内置 material：写 `materialPaths=builtin://...` + +不再允许以下状态作为正式协议存在： + +- 项目资产依旧只存普通文件路径 +- 项目资产同时写路径和 `AssetRef` +- 反序列化时优先猜测旧字段再兜底 + +### 3.2 最终运行时边界 + +收口后各层职责如下： + +- `AssetImportService` + - 工程扫描 + - `.meta` 管理 + - SourceAssetDB / ArtifactDB 维护 + - `EnsureArtifact` + - `Refresh` + - `Reimport` / `Clear Library` 入口 +- `ProjectAssetIndex` + - 项目资产路径快照 + - `AssetRef <-> 项目路径` 映射 + - 项目资产查找缓存 +- `ResourceManager` + - runtime object cache + - async load coalescing + - artifact runtime load dispatch + - deferred scene load 控制 +- Component / Scene + - 只保存最终资产引用 + - 不承担旧协议迁移职责 + +### 3.3 最终用户行为 + +收口后应达到以下体验： + +- 第一次导入可能慢，但之后再打开同一个 scene，不应再同步重跑原始 `obj/png/jpg` 导入。 +- 打开含有大型 OBJ 的 scene 时，不应长时间卡死 editor 主窗口。 +- 命中 artifact 后，mesh/material 恢复应尽量走异步路径。 +- 关闭 editor 再打开后，项目资产引用应稳定恢复，不出现“模型丢失、材质丢失、内置 sphere 丢失”这类状态回退问题。 +- 用户能明确知道当前是“命中缓存”还是“正在导入/重建缓存”。 + +--- + +## 4. 本轮必须删除的过渡态 + +这部分是收口计划的关键，不删掉这些内容，系统就始终处于过渡状态。 + +### 4.1 删除旧序列化兼容 + +目标： + +- 删除 `MeshFilterComponent` 对旧 `mesh=` 字段的长期兼容读取。 +- 删除 `MeshRendererComponent` 对旧 `materials=` 字段的长期兼容读取。 +- 删除“项目资产 path 与 `AssetRef` 双写”的长期行为。 + +允许保留： + +- 对 `builtin://` 的显式处理。 + +禁止保留： + +- “先读 path，不行再猜 `AssetRef`” +- “为了兼容老场景继续支持项目文件路径” + +### 4.2 删除场景迁移工具 + +以下过渡期工具应整体移除： + +- `Migrate Scene AssetRefs` 菜单项 +- 对应 action / command / project manager migration report +- 专门为旧场景迁移设计的 editor 流程 + +原因： + +- 当前项目只有一个，已有 scene 可以直接重写。 +- 继续保留迁移工具，只会让新系统一直背着旧协议。 + +### 4.3 删除长期双轨测试 + +需要同步清理测试中的过渡态假设： + +- 旧格式 scene 兼容测试 +- 双写格式测试 +- 迁移工具测试 + +替换成正式版测试： + +- 最终 scene 协议测试 +- 关闭 editor 重开后的稳定恢复测试 +- artifact 命中路径测试 +- 异步恢复与渲染可见性测试 + +--- + +## 5. 本轮必须补齐的正式能力 + +### 5.1 材质与贴图真正 lazy 化 + +当前模型 artifact 虽然已经存在，但材质恢复后仍然容易把关联贴图一起拉进来，导致： + +- 场景虽然不在反序列化阶段阻塞 +- 但资源真正恢复时仍然偏重 + +本轮必须补齐： + +- `xcmat` 成为正式稳定 artifact +- `Material` 运行时对象只持有 texture `AssetRef` +- texture runtime handle 按槽位、按需解析 +- mesh 恢复不顺手触发整套材质贴图同步加载 + +这是“缓存命中了但还是觉得重”的核心收口项。 + +### 5.2 明确导入与运行时边界 + +虽然最近已经引入： + +- `AssetImportService` +- `ProjectAssetIndex` + +但本轮要进一步明确： + +- `ResourceManager` 外部不再暴露旧式导入心智 +- 项目资产查找统一经过 `ProjectAssetIndex` +- artifact 生成统一经过 `AssetImportService` +- `AssetDatabase` 作为底层实现细节继续收口到 service 后面 + +本轮的目标不是一定把 `AssetDatabase` 拆成三个类，而是先把“对外边界”收干净。 + +也就是说，本轮要求： + +- 类内可暂时还偏胖 +- 但对外职责必须已经清晰 + +### 5.3 缓存运维闭环 + +正式版至少要有以下最小运维能力： + +- 单资源 Reimport +- `Reimport All` +- `Clear Library` +- 项目启动时检查并重建缺失缓存 +- 删除源资源后识别 orphan artifact + +如果这些没有，系统虽然能工作，但一旦缓存脏掉就难以恢复，仍然不算收口。 + +### 5.4 可观测性闭环 + +本轮至少要做到用户能看见： + +- 当前资源是命中 artifact 还是触发重导入 +- 正在导入哪个资源 +- 导入失败原因 +- scene 正在等待哪些资源恢复 + +不要求本轮先做完整面板，但至少要把日志、状态文案、必要的调试输出整理成稳定可用的最小版本。 + +--- + +## 6. 实施阶段 + +## 阶段 A：协议定稿与旧兼容删除 + +### 目标 + +把当前半兼容、半正式的 scene / component 数据协议收成最终格式。 + +### 任务 + +- 改 `MeshFilterComponent`： + - 项目资产只写 `meshRef` + - 只对 `builtin://` 保留 `meshPath` + - 删除旧 `mesh=` 历史兼容读取 +- 改 `MeshRendererComponent`： + - 项目资产只写 `materialRefs` + - 只对 `builtin://` 保留 `materialPaths` + - 删除旧 `materials=` 历史兼容读取 +- 直接改写 `project/Assets/Scenes/Main.xc` +- 直接改写 `project/Assets/Scenes/Backpack.xc` +- 如果项目里还有其他 scene / snapshot / prefab 使用旧项目资产路径，一并直接改成最终格式 + +### 同步删除 + +- `Migrate Scene AssetRefs` action +- `ProjectCommands` 中对应 migration command +- `ProjectManager` 中对应 migration report / migration logic +- 相关测试 + +### 阶段完成标准 + +- 项目场景中不再存在旧项目资产路径协议 +- engine/editor 中不再存在迁移工具入口 +- 组件反序列化代码只处理最终协议与 builtin 协议 + +## 阶段 B：导入与缓存边界收口 + +### 目标 + +让 `Library` 系统对外呈现为一套明确的正式接口，而不是几个类拼在一起的过渡实现。 + +### 任务 + +- 把项目资产索引访问统一走 `ProjectAssetIndex` +- 把 artifact 生成与保证统一走 `AssetImportService` +- 收敛 `ResourceManager` 中剩余的导入数据库耦合 +- 梳理 `AssetDatabase` 内部接口，限制它作为 service 内部实现使用 +- 增加明确的 `Refresh / Reimport / Clear Library` 入口 + +### 阶段完成标准 + +- editor / runtime 外部调用时，心智模型已经稳定为： + - 找项目资产：`ProjectAssetIndex` + - 产出或校验 artifact：`AssetImportService` + - 取 runtime object：`ResourceManager` + +## 阶段 C：性能闭环 + +### 目标 + +把“看起来已经异步，但恢复仍然偏重”的成本继续压下去。 + +### 任务 + +- 材质贴图 lazy resolve +- 减少 mesh 恢复时顺手加载整套关联资源 +- 校验首次导入、二次打开、关闭重开三种路径的时间差异 +- 清理仍可能在主线程触发的大锁与同步等待点 +- 必要时加入轻量 placeholder / loading state 文案 + +### 阶段完成标准 + +- 含 OBJ 的 scene 再次打开时，editor 主窗口不出现长时间假死 +- artifact 命中时恢复成本显著低于首次导入 +- 关闭 editor 重开后的恢复链路仍然稳定 + +## 阶段 D：最小工具闭环 + +### 目标 + +把这套系统变成“可维护”的，而不是只能靠调试日志救火。 + +### 任务 + +- 已完成：增加 `Reimport Asset` +- 已完成：增加 `Reimport All` +- 已完成：增加 `Clear Library` +- 已完成：增加最小导入状态输出 +- 已完成：增加 orphan artifact 清理 + +### 阶段完成标准 + +- 用户可以主动重建缓存 +- 缓存脏掉时不需要手工删文件再碰运气 +- 导入失败时能直接看到原因 + +--- + +## 7. 验收标准 + +本轮收口完成，必须同时满足以下条件： + +### 7.1 协议层 + +- 项目资产引用正式统一为 `AssetRef` +- 不再保留旧 scene / component 项目资产路径兼容协议 +- 不再保留迁移工具 + +### 7.2 架构层 + +- `AssetImportService` / `ProjectAssetIndex` / `ResourceManager` 的对外职责稳定 +- 运行时不再承担旧协议解释职责 +- `Library` 已经是正式依赖，而不是临时缓存补丁 + +### 7.3 功能层 + +- OBJ / 贴图 / 材质二次打开优先命中 artifact +- 关闭 editor 重开后项目 scene 能稳定恢复 +- builtin sphere / cube / default material 不会因为缓存系统而丢失 + +### 7.4 性能层 + +- 打开含大型 OBJ 的 scene 时不长时间卡死 editor +- 二次打开与首次导入的体感耗时有明显区分 +- 命中 artifact 后不再退回源文件同步导入主路径 + +### 7.5 工具层 + +- 具备最小 `Reimport / Reimport All / Clear Library` 能力 +- 有最小可观测性输出 + +--- + +## 8. 本轮不做的内容 + +为了尽快收口，本轮明确不做以下扩展： + +- prefab 全量资产协议翻新 +- 动画 / 音频 / shader 新 importer +- 远程缓存 +- 多项目历史版本兼容框架 +- 完整图形化导入面板 +- 一次性把所有 `AssetDatabase` 内部实现拆到最细 + +这些内容后续可以继续做，但不应该阻塞当前正式收口。 + +--- + +## 9. 推荐执行顺序 + +建议按下面顺序推进，避免边做边反复回滚： + +1. 先做阶段 A，直接把项目协议和旧兼容删干净。 +2. 再做阶段 B，把对外边界稳定下来。 +3. 然后做阶段 C，把“缓存命中了但恢复仍然重”的问题收掉。 +4. 最后做阶段 D，补齐最小运维与可观测性。 + +原因是： + +- 不先删旧兼容，后面所有逻辑都要双轨维护。 +- 不先把边界定清，性能问题会一直和历史兼容问题缠在一起。 +- 不先把主链路收稳，工具做出来也只是给过渡态续命。 + +--- + +## 10. 本轮涉及的主要代码范围 + +本轮预计重点落在以下文件： + +- `engine/src/Components/MeshFilterComponent.cpp` +- `engine/src/Components/MeshRendererComponent.cpp` +- `engine/include/XCEngine/Core/Asset/ResourceManager.h` +- `engine/src/Core/Asset/ResourceManager.cpp` +- `engine/include/XCEngine/Core/Asset/AssetImportService.h` +- `engine/src/Core/Asset/AssetImportService.cpp` +- `engine/include/XCEngine/Core/Asset/ProjectAssetIndex.h` +- `engine/src/Core/Asset/ProjectAssetIndex.cpp` +- `engine/include/XCEngine/Core/Asset/AssetDatabase.h` +- `engine/src/Core/Asset/AssetDatabase.cpp` +- `editor/src/Managers/ProjectManager.cpp` +- `editor/src/Commands/ProjectCommands.h` +- `editor/src/Actions/EditorActions.h` +- `editor/src/Actions/MainMenuActionRouter.h` +- `tests/core/Asset/test_resource_manager.cpp` +- `tests/Components/test_mesh_render_components.cpp` +- `tests/Scene/test_scene.cpp` +- `project/Assets/Scenes/Main.xc` +- `project/Assets/Scenes/Backpack.xc` + +--- + +## 11. 一句话结论 + +从这一刻开始，这个模块的目标不再是“继续兼容旧系统”，而是： + +把当前已经跑起来的 `Library`、artifact、`AssetRef`、异步恢复链路，收成一套只服务当前项目、无旧包袱、可稳定重开的正式资产系统。 diff --git a/docs/plan/Material Inspector与Shader属性面板收口计划_2026-04-07.md b/docs/used/Material Inspector与Shader属性面板收口计划_2026-04-07.md similarity index 100% rename from docs/plan/Material Inspector与Shader属性面板收口计划_2026-04-07.md rename to docs/used/Material Inspector与Shader属性面板收口计划_2026-04-07.md diff --git a/docs/used/Renderer下一阶段_ShaderMaterial与Pass体系设计.md b/docs/used/Renderer下一阶段_ShaderMaterial与Pass体系设计.md new file mode 100644 index 00000000..f51d5d5c --- /dev/null +++ b/docs/used/Renderer下一阶段_ShaderMaterial与Pass体系设计.md @@ -0,0 +1,656 @@ +# Renderer 下一阶段：Shader、Material 与 Pass 体系设计 + +日期：`2026-04-02` + +## 1. 阶段判断 + +当前 Renderer 阶段已经完成的事情，是把下面这条主链正式接通并收口： + +`RHI -> Rendering -> Editor Scene/Game Viewport` + +当前已经具备： + +- `SceneRenderer -> CameraRenderer -> RenderPipeline` 的主执行边界 +- scene camera request 组织能力 +- built-in forward 主几何绘制 +- `object-id` 渲染与 editor picking +- built-in post-process 入口 +- editor viewport 宿主接入 +- 对应的 renderer/editor 自动化测试闭环 + +这意味着 Renderer 已经不再是“RHI 之上的一堆零散 draw call”，而是已经形成了真实的模块边界。 + +但这并不意味着 Renderer 已经进入“可长期扩展”的状态。 + +当前阶段的真正短板，不是 render graph，而是： + +- shader 还没有进入正式 renderer 主路径 +- material 还不是正式 GPU 参数绑定载体 +- pass contract 还不完整 +- 三后端虽然都能跑，但 shader authoring 仍是内建硬编码 + +所以 Renderer 的下一阶段主线，不应优先做 render graph，而应优先完成： + +- `Shader` +- `Material` +- `Builtin Pass Contract` +- `Renderer-owned Feature Contract` + +--- + +## 2. 为什么下一阶段不是 Render Graph + +`render graph` 不是简单优化项，它本质上是更高一层的资源依赖与多 pass 调度框架。 + +但当前工程还没有满足它最该承接的前提： + +1. 还没有足够正式的 pass 分类体系 +2. 还没有正式的 shader / material 执行契约 +3. editor helper pass 与 runtime pass 还没有统一语义 +4. 还没有稳定的 renderer feature 输入输出边界 + +如果现在直接上 render graph，会出现一个问题： + +- graph 框架先做了 +- 真正的 shader/material/pass 契约还没收紧 +- 最后 graph 里承载的还是一批语义松散的临时 pass + +这会让架构“看起来高级”，但基础层仍然不稳。 + +因此下一阶段正确顺序应当是： + +1. 先收紧 shader/material/pass contract +2. 再把更多 renderer feature 统一为正式能力 +3. 等真正的多 pass 复杂度上来后，再引入 render graph + +--- + +## 3. 当前 Renderer 的真实问题 + +### 3.1 Shader 仍未进入正式主路径 + +当前 built-in forward pipeline 的 shader 仍然是直接硬编码在 C++ 中： + +- D3D12: HLSL +- OpenGL: GLSL 430 +- Vulkan: GLSL 450 + +这意味着： + +- `Material::GetShader()` 虽然存在，但不控制当前主渲染 +- shader 资源尚未成为正式运行时契约 +- 新增 pass 或 shader 变体时，仍然需要直接改 pipeline C++ + +这不符合后续 Unity 风格 SRP 的方向。 + +### 3.2 Material 还是“资源状态载体”，不是正式 GPU 材质实例 + +当前 `Material` 已具备： + +- render queue +- rasterizer / blend / depth-stencil render state +- tag +- property +- texture binding +- shader 引用 + +但真正进入 GPU 执行链路的内容，仍然很少： + +- per-object constant +- 一张主纹理 +- 一个 sampler +- 少量 pass metadata 过滤 + +也就是说： + +- material property 还没有正式映射到 GPU layout +- material constant buffer 还没有进入正式绑定链路 +- texture binding 还没有从“约定名字查一张图”升级为“按 pass layout 正式绑定” + +### 3.3 Pass contract 仍然不够完整 + +当前比较明确的 pass 只有： + +- forward 主几何 +- object-id +- grid +- selection outline +- debug mask + +但如果后面要走 Unity 风格 renderer，至少需要明确区分： + +- `ForwardLit` +- `Unlit` +- `DepthOnly` +- `ShadowCaster` +- `ObjectId` +- editor helper pass + +否则后面一旦加入阴影、深度预通道、材质分流、后处理和 SRP 注入，就会重新回到“if/else 管线”。 + +### 3.4 三后端能跑，但还不是正式 shader 资产体系 + +当前三后端运行没问题，不代表 shader 体系已经成熟。 + +当前缺的是： + +- 统一的 shader 资产描述 +- 每个 shader pass 的 backend variant 管理 +- 统一的 descriptor / constant layout 描述 +- renderer 内部的 pipeline cache key 规范 + +现在只是“每个 backend 有一份能工作的内建 shader”，离正式体系还有明显距离。 + +--- + +## 4. 下一阶段的核心目标 + +下一阶段目标不是“把所有渲染功能做完”，而是建立正式可扩展的 renderer 执行契约。 + +核心目标分四层。 + +### 4.1 正式建立 Shader Asset Contract + +下一阶段应把 `Shader` 从资源占位，提升为 renderer 正式消费的资源。 + +建议 shader 资产至少包含： + +- shader 名称与 GUID +- pass 列表 +- 每个 pass 的逻辑名称 +- 每个 pass 的 tag，例如 `LightMode` +- 每个 pass 的 property layout +- 每个 pass 的 resource binding layout +- 每个 backend 的 shader variant + +建议的概念模型： + +```text +ShaderAsset + -> ShaderPassDesc[] + -> passName + -> tags + -> propertyLayout + -> backendVariants +``` + +这里的关键点不是一开始就做复杂 shader graph，而是先明确： + +- renderer 以后创建 pipeline，不再直接从 C++ 字符串取 shader +- renderer 应从 shader asset 的某个 pass 中取当前 backend 对应 variant + +### 4.2 正式建立 Material Instance Contract + +`Material` 下一阶段要从“资源状态容器”升级为“可绑定的材质实例”。 + +Material 至少应当明确： + +- 它引用哪个 shader +- 它选择 shader 的哪个 pass +- 它当前有哪些 property override +- 它有哪些 texture binding +- 它导出的 render state 是什么 + +下一阶段不要求一开始就做复杂材质编辑器，但必须完成： + +- property -> GPU 常量区布局 +- texture binding -> descriptor binding +- pass 过滤规则 +- material instance 的缓存与脏标记 + +### 4.3 正式建立 Builtin Pass Contract + +下一阶段应当把当前 renderer 内建 pass 明确分层： + +- 几何主 pass +- 深度/阴影类 pass +- object-id/editor helper pass +- post-process / overlay pass + +建议第一批正式化的 pass 名称： + +- `ForwardLit` +- `Unlit` +- `DepthOnly` +- `ShadowCaster` +- `ObjectId` + +说明： + +- `ForwardLit` 支撑当前主线 +- `Unlit` 用于 editor helper、gizmo、调试对象、简单 UI mesh +- `DepthOnly` 和 `ShadowCaster` 为后面阴影与可见性阶段铺路 +- `ObjectId` 让 editor/runtime picking 有正式 renderer 合约 + +### 4.4 正式建立 Renderer Feature Contract + +当前 grid / outline / object-id / debug mask 已经部分进入 renderer，但仍然带有明显 editor 来路。 + +下一阶段应继续把它们定义为 renderer feature，而不是 editor 特判： + +- object-id output +- selection / mask debug +- overlay helper contract +- camera request 上的 feature request + +目标不是马上做完整 feature graph，而是明确： + +- 哪些 feature 属于 renderer +- 哪些输入由 editor 组装 +- 哪些输出由 renderer 提供 + +--- + +## 5. 三后端 Shader 策略 + +这一节必须进一步说透两个问题： + +1. 三后端语言不同，shader 资产到底怎么组织 +2. shader authoring 到底采用“Unity 式一份 shader 里写多个 stage”，还是把 vertex / fragment 拆成独立文件 + +### 5.1 当前阶段不建议直接追求“单源码全平台自动转译” + +理论上可以追求： + +- 统一 HLSL +- 再编到 SPIR-V / GLSL + +但这会立刻引入： + +- 工具链依赖 +- shader reflection +- backend 兼容差异处理 +- 调试复杂度 + +对于当前工程，这不是下一阶段最优先的问题。 + +### 5.2 下一阶段建议采用“统一逻辑资产 + 后端分 variant”的务实方案 + +建议下一阶段的 shader 策略是： + +- 逻辑上一个 shader asset +- 资产里按 pass 持有多个 backend variant +- renderer 根据 backend 选择对应源码/二进制 + +例如： + +```text +BuiltinLit.shader + Pass: ForwardLit + D3D12 -> HLSL + OpenGL -> GLSL 430 + Vulkan -> GLSL 450 / SPIR-V +``` + +这样做的优点： + +- 三后端路径清晰 +- 不引入过早的跨编译复杂度 +- 仍然能在资产层统一 shader 逻辑身份 +- 后续要切换成统一 authoring 也有演进空间 + +### 5.3 Vulkan 的长期方向 + +Vulkan 长期更适合进入： + +- 预编译 SPIR-V +- 反射生成 binding layout + +但这属于再下一阶段的工程化增强。 + +当前下一阶段只要求： + +- Vulkan 不再依赖 pipeline cpp 内嵌 shader 字符串的散乱模式 +- Vulkan variant 被纳入正式 shader asset contract + +### 5.4 推荐的 Shader 资产组织方式 + +建议下一阶段采用： + +- **逻辑上一个 ShaderAsset** +- **资产内部按 Pass 组织** +- **每个 Pass 内再按 Stage 与 Backend 持有 variant** + +推荐概念模型： + +```text +ShaderAsset + -> Pass: ForwardLit + -> Stage: Vertex + -> D3D12 : xxx.vs.hlsl + -> OpenGL : xxx.vs.glsl + -> Vulkan : xxx.vs.vk.glsl / xxx.vs.spv + -> Stage: Fragment + -> D3D12 : xxx.ps.hlsl + -> OpenGL : xxx.fs.glsl + -> Vulkan : xxx.fs.vk.glsl / xxx.fs.spv + + -> Pass: DepthOnly + -> ... +``` + +也就是说： + +- 对 renderer 来说，真正识别的是一个 `ShaderAsset` +- 对 pass 来说，拿到的是“这个 pass 在当前 backend 下对应的各 stage 变体” +- 对后端来说，最终看到的仍然是它自己能吃的 shader 源码或二进制 + +这样处理后： + +- shader 逻辑身份是统一的 +- backend 差异被收进 variant 层 +- pass / stage / backend 三个维度都清楚 + +### 5.5 不建议直接照搬 Unity ShaderLab 的单文件大一统方案 + +如果完全模仿 Unity，最直观的形式是： + +- 一份 shader 文件 +- 里面写 `Pass` +- `Pass` 里面再写 `Vertex/Fragment` + +这种方式的优点是： + +- 对材质和 pass 关系表达很强 +- 很适合后续 editor / inspector / C# SRP 暴露 + +但它当前直接落地的缺点也很明显： + +- 你现在有三个 backend +- backend shader 语言并不统一 +- 还没有自己的 shader import / include / preprocess / reflection 工具链 + +如果现在直接做成 Unity 那种单文件 DSL，等于同时要解决： + +- shader 语法设计 +- parser +- include 系统 +- multi-pass 语义 +- backend variant 分发 +- material property layout + +这会把下一阶段的复杂度一下子拉爆。 + +### 5.6 下一阶段更务实的做法 + +下一阶段建议采用“两层模型”： + +#### 第一层：逻辑层接近 Unity + +保留 Unity 风格的核心语义： + +- 一个 shader 有多个 pass +- 每个 pass 有名字和 tag +- material 绑定的是 shader 与 pass + +#### 第二层：物理文件层先按 stage 分开 + +实际文件先拆成： + +- `*.vs.hlsl` +- `*.ps.hlsl` +- `*.vs.glsl` +- `*.fs.glsl` +- `*.vs.vk.glsl` +- `*.fs.vk.glsl` + +或者编译后： + +- `*.spv` + +也就是说： + +- **逻辑上用 Unity 式“一个 shader 拥有多个 pass”** +- **物理落地上暂时不用 Unity 式“一个文件里硬塞所有 backend/stage”** + +这是当前阶段最稳妥的方案。 + +### 5.7 对“vertex / fragment 是合一还是分开”的明确结论 + +结论分两层： + +#### 从逻辑资产视角看 + +应当是“合一”的。 + +也就是： + +- 一个 `ShaderAsset` +- 下面有一个或多个 `Pass` +- 一个 `Pass` 同时拥有 vertex / fragment 等 stage + +这和 Unity 的思路一致。 + +#### 从实际源码文件视角看 + +应当先“分开”。 + +也就是： + +- vertex shader 单独文件 +- fragment shader 单独文件 +- backend variant 单独文件 + +原因： + +- 更容易做 backend 分发 +- 更容易调试编译错误 +- 更容易做最小 shader import +- 更适合你当前三后端并行维护 + +所以不要把“逻辑合一”和“源码物理文件合一”混为一谈。 + +最终建议是： + +- **逻辑模型采用 Unity 风格** +- **文件组织先采用分 stage、分 backend** + +### 5.8 未来再向 Unity ShaderLab 靠拢的演进路径 + +等下一阶段把下面这些都做稳之后： + +- shader asset contract +- material property binding +- backend variant 选择 +- pass contract + +后面再往上加一层更接近 Unity ShaderLab 的 authoring 语法，就顺理成章： + +```text +ShaderLab-like Authoring + -> Shader Importer + -> ShaderAsset / Pass / Variant + -> RenderPipeline Runtime +``` + +也就是说： + +- 现在先做 runtime contract +- 以后再做更高级的 shader authoring front-end + +这样不会把工程顺序做反。 + +--- + +## 6. 建议的新分层 + +建议 Renderer 下一阶段形成下面这套更稳定的分层： + +```text +Scene / Components / Resources + -> RenderSceneExtractor / RenderRequestPlanner + -> Shader & Material Runtime + -> CameraRenderer / RenderPipeline + -> Builtin Feature Passes + -> RHI + -> D3D12 / OpenGL / Vulkan +``` + +其中新增的重点层是： + +### 6.1 Shader & Material Runtime + +负责： + +- 解析 shader asset / material asset +- 生成 pass 级 binding layout +- 维护 material GPU 数据与脏标记 +- 提供 pipeline cache key + +### 6.2 Builtin Feature Passes + +负责： + +- object-id +- grid +- outline +- shadow/depth 等 builtin pass + +这样可以让： + +- `RenderPipeline` 更聚焦于场景主流程组织 +- 各 pass 更聚焦于自己真正的职责 + +--- + +## 7. 推荐的落地顺序 + +### 阶段 A：Formalize Builtin Pass Metadata + +先完成： + +- `ForwardLit` +- `Unlit` +- `DepthOnly` +- `ObjectId` + +需要落地的内容： + +- pass name +- pass tag +- renderer 如何选择某个 material 的 pass +- builtin pipeline 不再依赖模糊字符串判断 + +完成标志： + +- `MatchesBuiltinPass(...)` 不再只是当前这种最小过滤，而是更接近正式 pass contract + +### 阶段 B：Material GPU Binding 最小闭环 + +先完成： + +- material 常量数据打包 +- texture binding 正式映射 +- sampler 策略统一 +- material 脏标记 -> GPU 缓存更新 + +完成标志： + +- forward pipeline 不再只会找一张 `_MainTex` 风格贴图 +- material property 真正进入 shader 执行链 + +### 阶段 C：Shader Asset 真正进入 Render Pipeline + +先完成： + +- builtin shader 资产化 +- 每个 builtin shader 具备 backend variant +- pipeline state 从 shader asset pass 创建 + +完成标志： + +- `BuiltinForwardPipeline.cpp` 中的大段后端 shader 字符串不再是长期正式实现 + +### 阶段 D：Renderer-owned Feature Contract 收口 + +先完成： + +- object-id request/output 正式化 +- outline/grid 继续从 editor 逻辑脱耦 +- camera request 上的 feature request 更明确 + +完成标志： + +- editor 侧更多只做 request 装配，而不是 feature 逻辑承担者 + +### 阶段 E：验证与回归 + +必须补的测试： + +- renderer unit tests +- shader/material runtime unit tests +- pass metadata 选择测试 +- backend integration smoke tests +- editor viewport regression + +--- + +## 8. 下一阶段明确不做的内容 + +以下内容不进入下一阶段主线： + +- render graph +- 完整 shader graph +- 完整 deferred renderer +- 大规模后处理栈 +- 完整阴影系统产品化 +- C# SRP 真正脚本驱动落地 + +原因不是这些不重要，而是它们依赖下一阶段先把基础契约做稳。 + +--- + +## 9. 与 Unity 风格架构的承接关系 + +如果后面目标是做 Unity 风格的 C# SRP，那么下一阶段必须先把“原生 renderer 可被脚本驱动”的基础层做好。 + +Unity 风格承接关系应理解为： + +```text +Shader / Material / Pass Contract + -> Native Render Pipeline Runtime + -> ScriptableRenderContext / CommandBuffer + -> C# RenderPipelineAsset / RenderPipeline +``` + +也就是说： + +- 当前下一阶段做的不是 SRP 本身 +- 但做的是 SRP 能否成立的地基 + +如果这一层继续缺失，后面脚本层会直接耦合到一堆临时内建逻辑上，最后 SRP 只会沦为“脚本包装的硬编码 forward pipeline”。 + +--- + +## 10. 阶段成功标准 + +这一阶段完成时，至少应满足： + +1. shader asset 已进入 renderer 主路径 +2. material property 与 texture binding 已形成正式 GPU 绑定链 +3. builtin pass contract 已具备最小完整集 +4. 三后端 shader 不再依赖 pipeline cpp 中散乱硬编码作为长期实现 +5. object-id / outline / grid 等 renderer feature 边界进一步明确 +6. renderer/editor 对应测试体系同步补齐 + +--- + +## 11. 一句话总结 + +Renderer 下一阶段的正确主线不是 render graph，而是： + +- 先把 `Shader` +- `Material` +- `Pass Contract` +- `Renderer Feature Contract` + +做成正式能力。 + +只有这一层站稳之后，后面的： + +- 阴影 +- 更多 pass +- render graph +- C# SRP + +才会是顺势生长，而不是继续堆临时方案。 diff --git a/docs/plan/Renderer下一阶段_Unity风格Shader体系正式化计划_2026-04-06.md b/docs/used/Renderer下一阶段_Unity风格Shader体系正式化计划_完成归档_2026-04-07.md similarity index 100% rename from docs/plan/Renderer下一阶段_Unity风格Shader体系正式化计划_2026-04-06.md rename to docs/used/Renderer下一阶段_Unity风格Shader体系正式化计划_完成归档_2026-04-07.md diff --git a/docs/used/Renderer下一阶段_方向光阴影与光照闭环计划_完成归档_2026-04-05.md b/docs/used/Renderer下一阶段_方向光阴影与光照闭环计划_完成归档_2026-04-05.md new file mode 100644 index 00000000..d9bb7d4e --- /dev/null +++ b/docs/used/Renderer下一阶段_方向光阴影与光照闭环计划_完成归档_2026-04-05.md @@ -0,0 +1,462 @@ +# Renderer 下一阶段：方向光阴影与光照闭环计划 + +日期：`2026-04-04` + +## 1. 阶段背景 + +当前 `shader / material / rendering` 主线已经完成了这一阶段应有的基础闭环： + +- `Shader` 已具备 `properties / passes / resources / backend variants` 运行时契约 +- `Material` 已具备 schema 驱动的属性、纹理、常量布局与 pass resource binding plan +- `SceneRenderer / CameraRenderer / BuiltinForwardPipeline` 已经打通 +- `ObjectId / DepthOnly / ShadowCaster` 已具备独立 pass 与 request 骨架 +- 三后端 `D3D12 / OpenGL / Vulkan` 的当前渲染集成测试已全绿 + +但这仍然只是“能稳定出图的基础 forward renderer”，还不是“能承担引擎默认场景渲染”的完整运行时。 +下一阶段不应该优先做 `render graph`，也不应该先追求更复杂的编辑器功能，而应该把当前 renderer 推进成一个真正可用的默认前向渲染器。 + +这一阶段的主线目标只有一句话： + +**把当前 renderer 从“无阴影的基础出图器”推进到“具备方向光、阴影、基础多光源闭环，并可稳定承接 Scene/Game 视图”的运行时渲染器。** + +## 2. 为什么下一步是这个 + +当前代码结构已经说明了下一阶段的最短主路径： + +- `RenderSceneExtractor` 里已经有 `RenderLightingData.mainDirectionalLight` +- `BuiltinForwardPipeline` 已经在 per-object constants 中消费主方向光方向和颜色 +- `CameraRenderRequest` 已经有 `shadowCaster / depthOnly / objectId` request +- `BuiltinShadowCasterPass / BuiltinDepthOnlyPass` 已经存在 + +也就是说： + +1. 光照数据通路已经有最小入口 +2. 阴影 pass 的执行骨架已经有了 +3. 缺的是把这些骨架真正接成 frame 级闭环 + +如果这时跳去做 `render graph`，只会把尚未收紧的运行时逻辑包上一层更复杂的调度壳。 +如果这时去做更复杂的 editor 特效，也是在建立在“runtime lighting 还不完整”的地基上。 + +所以本阶段应当严格沿着 Unity 风格的自然演进路径推进： + +1. 先把默认前向运行时补完整 +2. 再谈更高层调度与优化 + +## 3. 与 Unity 式架构的对齐原则 + +本阶段继续遵循现有总设计，不偏离 `RHI -> Renderer -> Editor/Runtime` 这条主分层： + +- `RHI` 只负责统一 GPU 抽象，不承载场景渲染逻辑 +- `Renderer` 负责场景提取、光照数据组织、shadow/depth/object-id/forward 等 pass 执行 +- `Editor` 只是 renderer 的宿主与附加 overlay/pass 使用方，不拥有独立的一套 runtime 渲染逻辑 + +与 Unity 对齐时，要注意以下边界： + +- 阴影图、主光照、相机渲染请求，这些属于 runtime renderer 的正式能力 +- grid、outline、gizmo、icon，这些属于 editor 专属叠加能力 +- editor 需要复用 renderer，但不能反向污染 runtime 主链 + +因此，这一阶段做的方向光阴影、基础多光源、GameView/SceneView 统一接入，都是正式主线。 +`GPU picking`、editor outline、gizmo 美术化这些，都不应抢主线优先级。 + +## 4. 当前真实现状 + +从当前代码看，renderer 已具备但尚未闭环的点如下。 + +### 4.1 已经具备的能力 + +- `SceneRenderer` 已支持多 camera request、camera stack、surface render area +- `CameraRenderer` 已支持 `pre -> shadowCaster -> depthOnly -> main pipeline -> objectId -> post` +- `BuiltinForwardPipeline` 已支持 `ForwardLit / Unlit` 的统一 shader/material contract +- `BuiltinObjectIdPass` 已正式接入 object-id 渲染路径 +- `BuiltinDepthOnlyPass / BuiltinShadowCasterPass` 已经具备 pass 级执行能力 +- `RenderSceneExtractor` 已能提取主方向光 + +### 4.2 尚未闭环的能力 + +- 阴影图尚未由 `SceneRenderer/CameraRenderer` 正式规划、分配、执行与回收 +- forward 主通道尚未消费 shadow map 结果 +- 光照仍停留在“单主方向光最小数据”，没有正式多光源提交模型 +- shadow request 目前更像通用 hook，而不是 renderer 自动生成的正式帧请求 +- 缺少以“阴影正确性”为目标的正式集成测试场景 +- 缺少以“多光源正确性”为目标的正式集成测试场景 + +### 4.3 这意味着什么 + +当前 renderer 的问题已经不再是“架构没有”，而是： + +**架构有了，但 runtime lighting/shadow 这条主业务链尚未贯通。** + +## 5. 本阶段总体目标 + +本阶段拆成四个连续目标： + +1. 建立正式的方向光阴影闭环 +2. 建立正式的前向多光源数据通路 +3. 统一 SceneView / GameView 对 runtime renderer 的使用方式 +4. 为下一阶段的 post-process 与 renderer 扩展收紧边界 + +其中优先级严格如下： + +1. `Directional Light + Shadow Map` +2. `Forward 多光源` +3. `Scene/Game 视图统一使用正式 renderer 能力` +4. `补文档、补测试、清理旧临时路径` + +## 6. 分阶段实施计划 + +## 6.1 Phase A：方向光阴影闭环 + +### 目标 + +让场景中的主方向光真正生成 shadow map，并在主 forward pass 中被采样，形成跨三后端稳定一致的阴影结果。 + +### 具体工作 + +#### A1. 正式定义 shadow frame 数据模型 + +新增或收紧 renderer 内部数据结构，至少明确： + +- 主方向光是否需要阴影 +- shadow map 尺寸与格式 +- light-space view/projection 矩阵 +- shadow caster 渲染 surface +- forward receiver 采样所需的阴影参数 + +这里的目标不是先做复杂 cascades，而是先做单张 directional shadow map MVP。 + +#### A2. 由 renderer 自动生成 shadow caster request + +不能继续依赖测试或上层调用者手工拼 `shadowCaster` request。 +应由 `SceneRenderer` 或 `CameraRenderer` 在主 camera 渲染前自动生成： + +- 主方向光对应的 shadow camera data +- shadow surface +- clear flags +- shadow pass 执行顺序 + +也就是说，要把“有 shadow pass 骨架”提升成“runtime renderer 正式调度 shadow pass”。 + +#### A3. 收紧 `BuiltinShadowCasterPass` + +确认并补齐以下行为： + +- 只渲染 `castShadows = true` 的可见物体 +- 正确处理 section/material pass 选择 +- 只依赖 shadow caster 所需最小资源 +- 在三后端下都使用统一的深度输出语义 + +#### A4. 在 `BuiltinForwardPipeline` 中消费 shadow map + +forward pass 至少补齐： + +- shadow map SRV 绑定 +- light-space position 计算 +- shadow compare +- 基础 bias +- 基础 PCF 或最小稳定采样 + +这一阶段不追求高级阴影质量，但必须追求： + +- 没有明显自阴影灾难 +- 没有跨后端严重不一致 +- 测试图可稳定固化 GT + +#### A5. 增加阴影集成测试 + +新增至少一个正式场景： + +- `tests/Rendering/integration/directional_shadow_scene` + +场景要求： + +- 至少包含一盏方向光 +- 至少包含一个会投影的物体 +- 至少包含一个接收阴影的地面或大平面 +- 阴影边界、方向、遮挡关系都足够稳定，适合 GT 比对 + +### 验收标准 + +- 三后端都能稳定生成方向光阴影 +- forward pass 正式消费 shadow map +- `directional_shadow_scene` 三后端 GT 全绿 +- 不破坏现有全部 rendering integration + +## 6.2 Phase B：前向多光源闭环 + +### 目标 + +把当前只支持主方向光的 lighting 数据模型，推进为可正式承接多个灯光的前向运行时。 + +### 具体工作 + +#### B1. 扩展 `RenderLightingData` + +从当前的： + +- `mainDirectionalLight` + +扩展到至少可描述： + +- `main directional light` +- `additional directional lights` +- `point lights` +- `spot lights` + +注意这里不一定一步到位做完整 Unity 灯光体系，但要保证数据模型不会很快被推翻。 + +#### B2. 明确本阶段多光源策略 + +当前阶段建议使用： + +- 单主方向光 +- 有上限的 additional lights +- CPU 侧整理一份稳定 light list +- GPU 侧通过常量缓冲或结构化数据提交 + +本阶段**不做**： + +- clustered lighting +- tiled lighting +- deferred lighting + +这是为了保证先把可验证的前向路径收紧。 + +#### B3. 扩展 forward shader/material contract + +补齐多光源所需的 shader 输入： + +- additional light count +- light position / direction / color / range / spot angle +- shadowed main light 与 non-shadowed additional lights 的职责边界 + +要求仍沿用当前的 shader/material/pass contract，不要回退成硬编码散乱常量。 + +#### B4. 新增多光源集成测试 + +新增至少两个场景： + +- `multi_light_scene` +- `spot_light_scene` + +场景目标： + +- 验证 point/spot 的衰减与照明范围 +- 验证 additional lights 会真实影响画面 +- 验证三后端输出保持一致 + +### 验收标准 + +- `RenderSceneExtractor` 能提取正式多光源数据 +- `BuiltinForwardPipeline` 能消费多光源 +- 新增多光源场景三后端 GT 全绿 +- 方向光阴影能力不被破坏 + +## 6.3 Phase C：SceneView / GameView runtime 接入收紧 + +### 目标 + +让 editor 的场景与游戏视图都建立在同一套 runtime renderer 能力上，而不是继续沿着临时 editor 路径分叉。 + +### 具体工作 + +#### C1. 明确 runtime pass 与 editor overlay pass 的边界 + +正式定义： + +- runtime 正式 pass：shadow caster、depth only、forward、object-id、offscreen copy 等 +- editor 附加 pass：grid、outline、icon、gizmo 等 + +要求： + +- runtime pass 可脱离 editor 独立工作 +- editor pass 只能叠加，不能挟持 runtime 主流程 + +#### C2. GameView 走正式相机渲染请求 + +GameView 必须通过标准 `CameraRenderRequest` 驱动 renderer，不能再依赖 editor 特殊逻辑直接拼接。 + +#### C3. SceneView 继续复用 renderer + +SceneView 应： + +- 复用正式相机渲染链 +- 在其上叠加 editor overlay +- 允许 object-id / outline / grid 等继续作为 editor 增量能力存在 + +### 验收标准 + +- SceneView 与 GameView 都走正式 renderer 主链 +- editor 专属 overlay 不污染 runtime pass +- 不出现“editor 正常、runtime 不正常”或反之的分叉 + +## 6.4 Phase D：收口与稳定性整理 + +### 目标 + +在新能力落地后，把这一阶段的测试、文档、边界彻底收紧。 + +### 具体工作 + +#### D1. 补齐测试矩阵 + +至少确保以下持续可跑： + +- `shader_tests` +- `material_tests` +- `mesh_tests` +- `rendering_unit_tests` +- 全部 `tests/Rendering/integration` + +新增场景至少包括： + +- `directional_shadow_scene` +- `multi_light_scene` +- `spot_light_scene` + +#### D2. 清理临时路径 + +逐项检查并收紧： + +- 是否仍有测试手工拼 shadow request +- 是否仍有 runtime/editor 职责混用 +- 是否仍有与 shader/material contract 相冲突的旧 lighting 常量路径 + +#### D3. 文档归档 + +这一阶段结束后，应补一份阶段收口说明，并把过期计划归档到 `docs/plan/used/`。 + +### 验收标准 + +- 阴影、多光源、Scene/Game 接入均通过测试 +- 当前计划中的临时方案被收紧到清晰边界内 +- 下一阶段可以自然承接 skybox/post-process，而不是继续补地基 + +## 7. 测试策略 + +这一阶段的测试必须比前一阶段更严格，因为它开始影响真正的场景表现。 + +### 7.1 单元测试 + +重点补以下测试： + +- `RenderSceneExtractor` 的多光源提取 +- shadow request 自动生成逻辑 +- shadow matrix / light camera 参数构建 +- forward shader resource binding 对 shadow map 的消费 +- additional lights 排序与裁剪规则 + +### 7.2 集成测试 + +必须新增： + +- `directional_shadow_scene` +- `multi_light_scene` +- `spot_light_scene` + +保底回归集： + +- `textured_quad_scene` +- `unlit_scene` +- `object_id_scene` +- `backpack_scene` +- `backpack_lit_scene` +- `camera_stack_scene` +- `transparent_material_scene` +- `cull_material_scene` +- `depth_sort_scene` +- `material_state_scene` +- `offscreen_scene` + +### 7.3 三后端要求 + +本阶段所有新增集成测试都必须同时覆盖： + +- `D3D12` +- `OpenGL` +- `Vulkan` + +如果某一步只在单后端通过，不算完成。 +这一阶段绝不接受“先在一个后端跑通，另外两个后面再补”的收口标准。 + +## 8. 明确不做 + +为了避免主线失控，这一阶段明确不做下面这些： + +- `render graph` +- `deferred renderer` +- `clustered/tiled lighting` +- `cascaded shadow maps` +- `PCSS / VSM / EVSM` 等高级阴影方案 +- `post-process` 大框架 +- `shader graph` +- editor gizmo 的进一步美术化与交互打磨 + +这些都应该建立在“方向光阴影 + 基础多光源 + runtime renderer 稳定闭环”完成之后。 + +## 9. 风险点与处理策略 + +### 9.1 风险：阴影路径把 pass/resource contract 搞散 + +处理策略： + +- 阴影采样与 shadow caster 仍必须走正式 shader/material/pass contract +- 不允许为了赶进度，在 pipeline 内重新堆一套散乱硬编码绑定 + +### 9.2 风险：editor 需求重新污染 runtime 主线 + +处理策略： + +- SceneView 只复用 renderer +- grid/outline/gizmo 始终作为 editor overlay +- runtime 主链以 GameView/真实场景渲染为准 + +### 9.3 风险：三后端阴影精度差异导致 GT 不稳定 + +处理策略： + +- 第一版 shadow scene 场景构图应保守 +- 阈值控制应严格，但允许合理的小误差 +- 优先追求稳定一致，而不是追求复杂阴影表现 + +### 9.4 风险：多光源一步做太大 + +处理策略： + +- 先做“有限 additional lights 的前向提交” +- 不提前引入 forward+ 或 deferred +- 以可验证场景为主，不以理论最优为目标 + +## 10. 提交与执行节奏 + +这一阶段继续按“每一步可验证、每一步可提交”的节奏推进： + +1. 先做 `Phase A` 的数据模型与 shadow request 自动生成 +2. 测试通过后提交 +3. 再做 `ShadowCaster -> Forward` 的 shadow map 消费 +4. 测试通过后提交 +5. 再做 `Phase B` 的多光源数据模型与 shader 消费 +6. 测试通过后提交 +7. 最后做 `Phase C / D` 的接入收口与文档归档 + +每一步的“通过”都必须包含： + +- 至少相关 unit tests 通过 +- 至少相关 integration tests 通过 +- 如影响主线，必须补跑 rendering regression + +## 11. 成功标准 + +本阶段完成时，应满足以下判断： + +- renderer 能正式生成并消费方向光阴影 +- renderer 能正式消费基础多光源 +- SceneView 与 GameView 都建立在统一 runtime renderer 主链上 +- editor overlay 与 runtime pass 边界清晰 +- rendering 测试体系在三后端下持续稳定 + +## 12. 一句话总结 + +下一阶段的核心不是“做更多花哨渲染功能”，而是： + +**把当前已经具备架构基础的 renderer，推进成一个真正能承担默认场景渲染的 Unity 风格前向运行时。** diff --git a/docs/plan/Renderer模块设计与实现.md b/docs/used/Renderer模块设计与实现.md similarity index 100% rename from docs/plan/Renderer模块设计与实现.md rename to docs/used/Renderer模块设计与实现.md diff --git a/docs/plan/Renderer结构收口与代码正式化计划_2026-04-05.md b/docs/used/Renderer结构收口与代码正式化计划_完成归档_2026-04-05.md similarity index 100% rename from docs/plan/Renderer结构收口与代码正式化计划_2026-04-05.md rename to docs/used/Renderer结构收口与代码正式化计划_完成归档_2026-04-05.md diff --git a/docs/plan/Renderer阶段收口_旧兼容路径清理与正式化计划_2026-04-08.md b/docs/used/Renderer阶段收口_旧兼容路径清理与正式化计划_完成归档_2026-04-08.md similarity index 100% rename from docs/plan/Renderer阶段收口_旧兼容路径清理与正式化计划_2026-04-08.md rename to docs/used/Renderer阶段收口_旧兼容路径清理与正式化计划_完成归档_2026-04-08.md diff --git a/docs/plan/Renderer阶段收口补充_ObjectIdPicking正式化.md b/docs/used/Renderer阶段收口补充_ObjectIdPicking正式化.md similarity index 100% rename from docs/plan/Renderer阶段收口补充_ObjectIdPicking正式化.md rename to docs/used/Renderer阶段收口补充_ObjectIdPicking正式化.md diff --git a/docs/plan/Renderer阶段收口说明.md b/docs/used/Renderer阶段收口说明.md similarity index 100% rename from docs/plan/Renderer阶段收口说明.md rename to docs/used/Renderer阶段收口说明.md diff --git a/docs/plan/used/SceneViewport_Overlay_Gizmo_Rework_Plan_完成归档_2026-04-04.md b/docs/used/SceneViewport_Overlay_Gizmo_Rework_Plan_完成归档_2026-04-04.md similarity index 100% rename from docs/plan/used/SceneViewport_Overlay_Gizmo_Rework_Plan_完成归档_2026-04-04.md rename to docs/used/SceneViewport_Overlay_Gizmo_Rework_Plan_完成归档_2026-04-04.md diff --git a/docs/used/Shader与Material下一阶段_ShaderLab正式化与BuiltinShader资产布局计划_完成归档_2026-04-07.md b/docs/used/Shader与Material下一阶段_ShaderLab正式化与BuiltinShader资产布局计划_完成归档_2026-04-07.md new file mode 100644 index 00000000..878965d6 --- /dev/null +++ b/docs/used/Shader与Material下一阶段_ShaderLab正式化与BuiltinShader资产布局计划_完成归档_2026-04-07.md @@ -0,0 +1,247 @@ +# Shader 与 Material 下一阶段：ShaderLab 正式化与 Builtin Shader 资产布局计划 +日期：`2026-04-07` + +## 1. 阶段结论 + +上一阶段已经完成了最关键的主线收口： + +- `.shader` 现在只表示 authoring shader，不再兼容 JSON manifest。 +- 旧的 manifest 主路径已经从运行时主流程移除。 +- shader / material / editor 相关测试已经回归通过。 +- 当前 shader 主线终于从“过渡态”进入了“可以继续正规化”的状态。 + +这意味着接下来不应该再围绕“兼容旧双路径”打补丁，而应该开始正式推进： + +- `ShaderLab authoring` +- `Material contract` +- `builtin shader asset layout` +- `runtime pass contract` + +一起向 Unity 风格继续收口。 + +--- + +## 2. 当前真实状态 + +当前已经成立的事实： + +1. `.shader` 主语义已经统一。 +2. authoring parser 已经能承载基础的 `Shader / Properties / SubShader / Pass / Tags / HLSLPROGRAM / pragma / 基础状态`。 +3. runtime 已经有 `Shader -> Pass -> Variant` 数据模型。 +4. builtin shader 已经基本都迁入 authoring 主路径。 + +但当前还没有完全完成的部分也很明确： + +1. 语法还只是 Unity ShaderLab 的一个子集。 +2. builtin shader 资产目录结构还带有明显的过渡痕迹。 +3. material 与 shader 的契约虽然比之前干净，但还没完全达到 Unity 式心智模型。 +4. renderer 对 pass contract 的消费还可以继续正规化。 + +--- + +## 3. Builtin Shader 资产目录结论 + +这里先把结论写死： + +- `engine/assets/builtin/shaders` 下的**主入口 shader 文件**，不需要再一 shader 一子文件夹。 +- 既然当前主入口已经都是单个 `.shader` 文件，那么更合理的结构应该是： + +```text +engine/assets/builtin/shaders/ + forward-lit.shader + unlit.shader + depth-only.shader + shadow-caster.shader + object-id.shader + object-id-outline.shader + skybox.shader + color-scale-post-process.shader + final-color.shader +``` + +- 需要保留子目录的，不是 builtin shader 入口文件本身，而是**公用 include / shader library**。 +- 因此公共代码应该独立成类似： + +```text +engine/assets/shaderlib/ + Core.hlsl + Common.hlsl + Lighting.hlsl + SpaceTransforms.hlsl + Shadow.hlsl + MaterialInput.hlsl +``` + +也就是说： + +- `builtin/shaders/`：放“逻辑 shader 资产入口” +- `shaderlib/`：放“共享 include 库” + +而不是继续维持“每个 shader 一个文件夹，文件名还重复一遍”的结构。 + +这更符合现在的真实资产形态，也更利于后续继续扩展 builtin shader 数量。 + +--- + +## 4. 下一阶段目标 + +下一阶段的目标不是做更多渲染效果，而是把 shader/material 底座继续正规化，达到可以稳定承接后续 SRP 的程度。 + +这一阶段的目标分成四件事： + +1. 收口 builtin shader 资产布局。 +2. 扩展 ShaderLab authoring 子集，继续向 Unity 靠拢。 +3. 继续压缩 material 中残留的临时职责。 +4. 让 renderer 对 pass / keyword / variant 的消费边界更正式。 + +--- + +## 5. 分阶段执行 + +### Phase A：Builtin Shader 资产布局拍平 + +目标： + +- 把 `engine/assets/builtin/shaders/*/* .shader` 收口成单层 `.shader` 文件布局。 +- 同步清理 `BuiltinResources` 中的路径映射和命名。 + +工作项： + +1. 拍平 builtin shader 文件路径。 +2. 更新 `BuiltinResources.cpp/.h` 中的 builtin shader relative path 表。 +3. 回归所有 builtin shader loader 测试。 +4. 回归 editor / renderer 中依赖 builtin shader path 的测试。 + +完成标准： + +- `engine/assets/builtin/shaders/` 单层化。 +- 所有 builtin shader 路径 helper 仍稳定工作。 + +### Phase B：扩展 ShaderLab authoring 子集 + +目标： + +- 把当前 authoring 语法从“基础可用”推进到“真正像 Unity ShaderLab 的工程可用子集”。 + +优先支持： + +- `BlendOp` +- `Offset` +- `Stencil` +- `UsePass` +- 更完整的 `Tags` +- 更稳的 `SubShader` 级状态继承与覆盖规则 + +工作项： + +1. 扩 parser / IR。 +2. 为新增语法补单测。 +3. 为 builtin shader 和后续材质/渲染用例补回归用例。 + +完成标准： + +- 这些语法不再停留在计划里，而是进入实际 parser / runtime contract。 + +### Phase C：Material 契约继续收口 + +目标： + +- 让 material 更接近 Unity 的角色定位：只管理 shader、properties、textures、keywords、必要的 render state override。 + +工作项： + +1. 继续压缩 legacy `shaderPass` 的主路径影响范围。 +2. 梳理 property 到 constant buffer 的稳定映射。 +3. 梳理 keyword 集与 variant lookup 的契约边界。 +4. 审查 material loader 中是否还存在对旧 shader 体系的隐式兼容假设。 + +完成标准： + +- material 不再承担本应属于 renderer 的 pass 选择职责。 + +### Phase D：Renderer 消费链继续正规化 + +目标： + +- 让 renderer 更正式地围绕 `LightMode / pass contract / keywords / backend` 选用 pass 与 variant。 + +工作项： + +1. 审查 builtin pipeline 中的 pass 选择逻辑。 +2. 审查 keyword 参与 variant 选择与 pipeline cache 的路径。 +3. 清理仍然依赖旧约定字符串兜底的代码。 + +完成标准： + +- shader/material/runtime 三者的职责边界更加稳定，不再互相越界兜底。 + +--- + +## 6. 测试要求 + +这一阶段必须保持“每做一层就立刻回归”，不能再先堆实现后补测试。 + +至少要持续回归： + +- `shader_tests` +- `material_tests` +- `editor_tests` 中 shader path / viewport render flow / overlay 相关用例 +- `XCEditor` 编译 +- 受影响的 rendering 单测与关键集成测试 + +如果 builtin shader 资产布局拍平，必须额外回归： + +- builtin shader loader +- object-id / outline / grid / final-color / skybox 相关路径与运行时消费 + +--- + +## 7. 风险与控制 + +### 风险 1：目录结构重构把路径引用打坏 + +控制策略： + +- 先只拍平 builtin shader 主入口文件。 +- `shaderlib` 不混入 `builtin/shaders` 同层迁移，避免一次改太多。 +- 先跑 loader / editor path / renderer path 回归，再考虑下一层。 + +### 风险 2：语法扩展过快，把当前稳定 authoring 再次打回过渡态 + +控制策略： + +- 只扩“明确服务于 Unity 风格主线”的语法。 +- 不引入新的双路径兼容层。 +- 任何新语法都必须先建测试，再接运行时。 + +### 风险 3：material 与 renderer 职责再次混淆 + +控制策略： + +- 每做一项都用“这件事在 Unity 里是谁负责”来校验职责归属。 + +--- + +## 8. 收口判定 + +满足下面条件时，这一阶段可以认为完成： + +1. builtin shader 资产目录已经拍平到单层主入口结构。 +2. `BuiltinResources` 与相关路径 helper 已同步完成。 +3. ShaderLab authoring 子集新增一轮关键语法支持并有测试覆盖。 +4. material 对旧路径的临时兼容进一步缩小。 +5. renderer 的 pass / variant 消费逻辑进一步正规化。 +6. shader / material / editor / XCEditor 回归全部稳定。 + +--- + +## 9. 下一步执行顺序 + +建议的实际执行顺序如下： + +1. 先做 builtin shader 资产布局拍平。 +2. 立刻回归 shader/material/editor 路径相关测试。 +3. 再开始扩 ShaderLab 子集。 +4. 然后收 material 与 renderer 的契约边界。 + +也就是说，**下一步最应该先做的不是再加语法，而是先把 builtin shader 资产布局收干净。** diff --git a/docs/plan/used/Shader与Material系统下一阶段计划_完成归档_2026-04-04.md b/docs/used/Shader与Material系统下一阶段计划_完成归档_2026-04-04.md similarity index 100% rename from docs/plan/used/Shader与Material系统下一阶段计划_完成归档_2026-04-04.md rename to docs/used/Shader与Material系统下一阶段计划_完成归档_2026-04-04.md diff --git a/docs/used/Subplan-01_XCUI-Core-Tree-State.md b/docs/used/Subplan-01_XCUI-Core-Tree-State.md new file mode 100644 index 00000000..48531028 --- /dev/null +++ b/docs/used/Subplan-01_XCUI-Core-Tree-State.md @@ -0,0 +1,48 @@ +# Subplan 01：XCUI Core Tree / State / Invalidation + +目标： + +- 搭出 XCUI 的 retained-mode 核心骨架。 +- 明确 `ElementTree`、`NodeId`、`View`、`ViewModel`、`dirty flag`、`rebuild`、`lifecycle` 的最小闭环。 + +负责人边界： + +- 负责 `engine/include/XCEngine/UI/` 与 `engine/src/UI/Core/` 的核心树模型。 +- 不负责具体布局算法。 +- 不负责 ImGui 适配绘制。 + +建议目录： + +- `engine/include/XCEngine/UI/Core/` +- `engine/src/UI/Core/` +- `tests` 中对应 XCUI core 测试文件 + +前置依赖： + +- 依赖主线完成 `Phase 0` 的基础类型和 UI 生命周期边界清理。 + +现在就可以先做的内容： + +- 设计 `UIElementId` / `UIElement` / `UIContext` / `UIBuildContext` +- 设计 dirty 标记与增量重建规则 +- 设计 ViewModel 读写边界和 command 回调入口 +- 写最小 tree rebuild 测试 + +明确不做： + +- 不接入 `.xcui` 文件 +- 不接入 editor 面板 +- 不写具体 widget 大库 + +交付物： + +- XCUI core 基础类与生命周期定义 +- tree rebuild / invalidation / state propagation 单元测试 +- 一个最小 demo：代码构建 UI tree 并触发一次增量更新 + +验收标准： + +- 可以构建一棵稳定的 UI tree +- 局部状态变化时只标脏必要节点 +- 重建逻辑与布局/渲染解耦 +- 其他 subplan 可以基于该模块定义控件树和状态更新 diff --git a/docs/plan/xcui-subplans/Subplan-03_XCUI-Style-Theme-Token.md b/docs/used/Subplan-03_XCUI-Style-Theme-Token.md similarity index 100% rename from docs/plan/xcui-subplans/Subplan-03_XCUI-Style-Theme-Token.md rename to docs/used/Subplan-03_XCUI-Style-Theme-Token.md diff --git a/docs/plan/xcui-subplans/Subplan-06_XCUI-Markup-Import-HotReload.md b/docs/used/Subplan-06_XCUI-Markup-Import-HotReload.md similarity index 100% rename from docs/plan/xcui-subplans/Subplan-06_XCUI-Markup-Import-HotReload.md rename to docs/used/Subplan-06_XCUI-Markup-Import-HotReload.md diff --git a/docs/plan/Unity式Library资产导入与缓存系统重构方案.md b/docs/used/Unity式Library资产导入与缓存系统重构方案.md similarity index 100% rename from docs/plan/Unity式Library资产导入与缓存系统重构方案.md rename to docs/used/Unity式Library资产导入与缓存系统重构方案.md diff --git a/docs/plan/Unity式SceneView_Gizmo系统完整审查与正式化重构方案.md b/docs/used/Unity式SceneView_Gizmo系统完整审查与正式化重构方案_完成归档_2026-04-06.md similarity index 100% rename from docs/plan/Unity式SceneView_Gizmo系统完整审查与正式化重构方案.md rename to docs/used/Unity式SceneView_Gizmo系统完整审查与正式化重构方案_完成归档_2026-04-06.md diff --git a/docs/plan/Unity式Tick系统与PlayMode运行时方案-阶段进展.md b/docs/used/Unity式Tick系统与PlayMode运行时方案-阶段进展.md similarity index 100% rename from docs/plan/Unity式Tick系统与PlayMode运行时方案-阶段进展.md rename to docs/used/Unity式Tick系统与PlayMode运行时方案-阶段进展.md diff --git a/docs/plan/Unity式Tick系统与PlayMode运行时方案.md b/docs/used/Unity式Tick系统与PlayMode运行时方案.md similarity index 100% rename from docs/plan/Unity式Tick系统与PlayMode运行时方案.md rename to docs/used/Unity式Tick系统与PlayMode运行时方案.md diff --git a/docs/plan/used/XCUI_Input_Focus_Shortcut_Subplan_完成归档_2026-04-04.md b/docs/used/XCUI_Input_Focus_Shortcut_Subplan_完成归档_2026-04-04.md similarity index 96% rename from docs/plan/used/XCUI_Input_Focus_Shortcut_Subplan_完成归档_2026-04-04.md rename to docs/used/XCUI_Input_Focus_Shortcut_Subplan_完成归档_2026-04-04.md index ce76dc47..5ae37630 100644 --- a/docs/plan/used/XCUI_Input_Focus_Shortcut_Subplan_完成归档_2026-04-04.md +++ b/docs/used/XCUI_Input_Focus_Shortcut_Subplan_完成归档_2026-04-04.md @@ -129,9 +129,9 @@ ## 5. 原 subplan 文件 -原始 subplan 文件保留在： +原始 subplan 文件已从活跃 `xcui-subplans` 目录移出。 -- `docs/plan/xcui-subplans/Subplan-04_XCUI-Input-Focus-Shortcut.md` +当前这份文件就是 `Subplan-04` 的最终归档版本。 其状态应视为： diff --git a/docs/plan/used/XCUI_Subplan-01_Core_Tree_State_完成归档_2026-04-04.md b/docs/used/XCUI_Subplan-01_Core_Tree_State_完成归档_2026-04-04.md similarity index 100% rename from docs/plan/used/XCUI_Subplan-01_Core_Tree_State_完成归档_2026-04-04.md rename to docs/used/XCUI_Subplan-01_Core_Tree_State_完成归档_2026-04-04.md diff --git a/docs/plan/used/XCUI_Subplan-02_LayoutEngine_完成归档_2026-04-04.md b/docs/used/XCUI_Subplan-02_LayoutEngine_完成归档_2026-04-04.md similarity index 100% rename from docs/plan/used/XCUI_Subplan-02_LayoutEngine_完成归档_2026-04-04.md rename to docs/used/XCUI_Subplan-02_LayoutEngine_完成归档_2026-04-04.md diff --git a/docs/plan/used/XCUI_Subplan-05_ImGui_Transition_Backend_完成归档_2026-04-04.md b/docs/used/XCUI_Subplan-05_ImGui_Transition_Backend_完成归档_2026-04-04.md similarity index 100% rename from docs/plan/used/XCUI_Subplan-05_ImGui_Transition_Backend_完成归档_2026-04-04.md rename to docs/used/XCUI_Subplan-05_ImGui_Transition_Backend_完成归档_2026-04-04.md