docs: refresh editor xcui and material inspector pages
This commit is contained in:
@@ -33,8 +33,8 @@
|
||||
|
||||
## 当前调用链
|
||||
|
||||
- `XCUIDemoPanel::Render()` 当前每帧都会 `BeginFrame() -> Submit(drawData) -> EndFrame(ImGui::GetWindowDrawList())`。
|
||||
- `tests/Editor/test_xcui_imgui_transition_backend.cpp` 当前直接验证了 pending state 重置和 flush 后 `ImDrawList` 顶点 / 命令缓冲被写入。
|
||||
- 当前代码树里已经没有 `editor/src/panels/XCUIDemoPanel.h/.cpp`；旧版 demo panel 文档仅作为历史迁移锚点保留，不再代表真实 source-backed 调用链。
|
||||
|
||||
## 当前实现边界
|
||||
|
||||
@@ -46,4 +46,5 @@
|
||||
|
||||
- [XCUIBackend](../XCUIBackend.md)
|
||||
- [DrawData](../../../UI/DrawData/DrawData.md)
|
||||
- [XCUIDemoRuntime](../XCUIDemoRuntime/XCUIDemoRuntime.md)
|
||||
- [XCUIDemoPanel](../../panels/XCUIDemoPanel/XCUIDemoPanel.md)
|
||||
|
||||
@@ -15,7 +15,7 @@
|
||||
|
||||
## 当前定位
|
||||
|
||||
- `ImGuiTransitionBackend` 已经接上真实测试和 demo 面板，是当前过渡期可运行的桥接器。
|
||||
- `ImGuiTransitionBackend` 是当前唯一 source-backed、可直接落到 Dear ImGui `ImDrawList` 的 XCUI 过渡桥接器；当前代码树里已经没有 `XCUIDemoPanel` 这类 demo 面板调用链。
|
||||
- `XCUIDemoRuntime` 目前只有头文件声明，还没有 `.cpp` 和真实调用链，更像后续 demo runtime 的占位入口。
|
||||
|
||||
## 相关文档
|
||||
|
||||
@@ -0,0 +1,62 @@
|
||||
# MaterialInspectorMaterialState
|
||||
|
||||
**命名空间**: `XCEngine::Editor`
|
||||
|
||||
**类型**: `state structs`
|
||||
|
||||
**源文件**: `editor/src/panels/MaterialInspectorMaterialState.h`
|
||||
|
||||
**描述**: Material Inspector 的本地编辑状态模型，集中保存标签、keyword、属性、render-state 覆盖和加载/dirty/error 标志。
|
||||
|
||||
## 概述
|
||||
|
||||
`MaterialInspectorMaterialState.h` 不是一个 panel，而是 `InspectorPanel` 中材质资产编辑流程使用的状态容器集合。当前主要包括：
|
||||
|
||||
- `MaterialTagEditRow`
|
||||
- 一行 tag 名/值编辑缓存。
|
||||
- `MaterialKeywordState`
|
||||
- 单个 shader keyword 的值和是否需要序列化。
|
||||
- `MaterialPropertyState`
|
||||
- 单个材质属性的编辑态，覆盖 float/int/bool/texture 等值。
|
||||
- `MaterialAssetState`
|
||||
- 整个材质资产当前在 Inspector 中的编辑快照。
|
||||
|
||||
## 当前状态内容
|
||||
|
||||
`MaterialAssetState` 当前收口了：
|
||||
|
||||
- 资产路径、全路径和显示名
|
||||
- `shaderPath` 文本缓冲
|
||||
- `renderQueue`
|
||||
- `renderState` 与 `hasRenderStateOverride`
|
||||
- `tags`
|
||||
- `keywords`
|
||||
- `properties`
|
||||
- `errorMessage`
|
||||
- `dirty`
|
||||
- `loaded`
|
||||
|
||||
这说明 Inspector 当前并不是直接把 `Material` 运行时对象原地当作 UI 状态使用，而是维护一份偏 authoring/editor 语义的独立快照。
|
||||
|
||||
## Reset 语义
|
||||
|
||||
`MaterialAssetState::Reset()` 当前会：
|
||||
|
||||
- 清空路径、名称和错误信息
|
||||
- 把 `shaderPath` 缓冲归零
|
||||
- 把 `renderQueue` 还原到 `Geometry`
|
||||
- 清空 `renderState` override 标志和内容
|
||||
- 清空 tags / keywords / properties
|
||||
- 把 `dirty` 与 `loaded` 复位为 `false`
|
||||
|
||||
## 当前使用位置
|
||||
|
||||
- `editor/src/panels/InspectorPanel.h`
|
||||
- `editor/src/panels/InspectorPanel.cpp`
|
||||
- [MaterialInspectorMaterialStateIO](../MaterialInspectorMaterialStateIO/MaterialInspectorMaterialStateIO.md) 会基于这份状态做同步与序列化
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [panels](../panels.md)
|
||||
- [MaterialInspectorMaterialStateIO](../MaterialInspectorMaterialStateIO/MaterialInspectorMaterialStateIO.md)
|
||||
- [Material](../../../Resources/Material/Material/Material.md)
|
||||
@@ -0,0 +1,23 @@
|
||||
# ApplyMaterialAuthoringPresenceToState
|
||||
|
||||
**命名空间**: `XCEngine::Editor`
|
||||
|
||||
**类型**: `free function`
|
||||
|
||||
**源文件**: `editor/src/panels/MaterialInspectorMaterialStateIO.h`
|
||||
|
||||
**描述**: 根据材质源文本里实际出现的 `keywords`、`properties`、`textures` 与 `renderState` 字段，回填 `MaterialAssetState` 的 authored/serialized 标记。
|
||||
|
||||
## 当前行为
|
||||
|
||||
- 会先解析 source text 中是否存在 `renderState`
|
||||
- 普通属性从 `properties` 对象取键集合
|
||||
- texture/cubemap 属性从 `textures` 对象取键集合
|
||||
- keyword 从 `keywords` 数组取值集合
|
||||
- 最终把这些 presence 信息写回 `state.keywords` 与 `state.properties`
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [MaterialInspectorMaterialStateIO](MaterialInspectorMaterialStateIO.md)
|
||||
- [MaterialInspectorMaterialState](../MaterialInspectorMaterialState/MaterialInspectorMaterialState.md)
|
||||
- [BuildMaterialAssetFileText](BuildMaterialAssetFileText.md)
|
||||
@@ -0,0 +1,30 @@
|
||||
# BuildMaterialAssetFileText
|
||||
|
||||
**命名空间**: `XCEngine::Editor`
|
||||
|
||||
**类型**: `free function`
|
||||
|
||||
**源文件**: `editor/src/panels/MaterialInspectorMaterialStateIO.h`
|
||||
|
||||
**描述**: 把 `MaterialAssetState` 编码成最终材质资产 JSON 文本，并省略未序列化的默认项。
|
||||
|
||||
## 当前行为
|
||||
|
||||
- 会写出 `shader` 与 `renderQueue`
|
||||
- 非空 `tags` 会编码成对象
|
||||
- 只输出 `serialized == true` 的 keyword
|
||||
- 只输出 `serialized == true` 的普通属性与 texture 属性
|
||||
- `hasRenderStateOverride == true` 时才写出 `renderState`
|
||||
- 最终返回带换行的完整 JSON 字符串
|
||||
|
||||
## 测试
|
||||
|
||||
- `tests/Editor/test_material_inspector_material_state_io.cpp` 覆盖：
|
||||
- 省略默认值与未序列化条目
|
||||
- 写出 texture 覆盖
|
||||
- 写出 render-state 覆盖
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [MaterialInspectorMaterialStateIO](MaterialInspectorMaterialStateIO.md)
|
||||
- [MaterialInspectorMaterialState](../MaterialInspectorMaterialState/MaterialInspectorMaterialState.md)
|
||||
@@ -0,0 +1,22 @@
|
||||
# CollectMaterialPropertyStates
|
||||
|
||||
**命名空间**: `XCEngine::Editor`
|
||||
|
||||
**类型**: `free function`
|
||||
|
||||
**源文件**: `editor/src/panels/MaterialInspectorMaterialStateIO.h`
|
||||
|
||||
**描述**: 从运行时 `Material` 收集 Inspector 可编辑的 `MaterialPropertyState` 列表，并按 shader schema 或名字排序。
|
||||
|
||||
## 当前行为
|
||||
|
||||
- 先读取 `Material::GetProperties()`
|
||||
- 若材质带有效 shader schema，则优先按 shader property 顺序排序
|
||||
- 若没有 schema，则退回名字排序
|
||||
- texture/cubemap 属性会额外尝试解析当前 texture binding 路径
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [MaterialInspectorMaterialStateIO](MaterialInspectorMaterialStateIO.md)
|
||||
- [MaterialInspectorMaterialState](../MaterialInspectorMaterialState/MaterialInspectorMaterialState.md)
|
||||
- [Material](../../../Resources/Material/Material/Material.md)
|
||||
@@ -0,0 +1,20 @@
|
||||
# IsTextureMaterialPropertyType
|
||||
|
||||
**命名空间**: `XCEngine::Editor`
|
||||
|
||||
**类型**: `free function`
|
||||
|
||||
**源文件**: `editor/src/panels/MaterialInspectorMaterialStateIO.h`
|
||||
|
||||
**描述**: 判断给定 `MaterialPropertyType` 是否属于 texture 或 cubemap 一类需要走 texture authoring 分支的属性。
|
||||
|
||||
## 当前行为
|
||||
|
||||
- 对 `Texture` 和 `Cubemap` 返回 `true`
|
||||
- 其它属性类型返回 `false`
|
||||
- `ApplyMaterialAuthoringPresenceToState(...)` 与 `BuildMaterialAssetFileText(...)` 会用它区分 `textures` 和普通 `properties`
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [MaterialInspectorMaterialStateIO](MaterialInspectorMaterialStateIO.md)
|
||||
- [MaterialInspectorMaterialState](../MaterialInspectorMaterialState/MaterialInspectorMaterialState.md)
|
||||
@@ -0,0 +1,69 @@
|
||||
# MaterialInspectorMaterialStateIO
|
||||
|
||||
**命名空间**: `XCEngine::Editor`
|
||||
|
||||
**类型**: `free functions`
|
||||
|
||||
**源文件**: `editor/src/panels/MaterialInspectorMaterialStateIO.h`
|
||||
|
||||
**描述**: Material Inspector 状态与 shader/material/source text 之间的同步 helper，负责属性快照收集、schema 对齐、authoring presence 标记和材质文件文本生成。
|
||||
|
||||
## 概述
|
||||
|
||||
`MaterialInspectorMaterialStateIO` 把 Material Inspector 的几条关键数据流集中到一起：
|
||||
|
||||
1. 从运行时 `Material` 收集可编辑属性状态
|
||||
2. 按 shader schema 把现有状态重排、补齐或丢弃
|
||||
3. 根据 source text 标记哪些 keyword / property / texture 真正来自作者输入
|
||||
4. 把编辑状态重新编码成材质资产文本
|
||||
|
||||
## 公开函数
|
||||
|
||||
| 函数 | 说明 |
|
||||
|------|------|
|
||||
| [IsTextureMaterialPropertyType](IsTextureMaterialPropertyType.md) | 判断属性是否属于 texture/cubemap。 |
|
||||
| [CollectMaterialPropertyStates](CollectMaterialPropertyStates.md) | 从 `Material` 收集并排序属性编辑状态。 |
|
||||
| [SyncMaterialAssetStateWithShader](SyncMaterialAssetStateWithShader.md) | 以 shader schema 为准同步 keyword 与 property 列表，同时尽量保留兼容旧值。 |
|
||||
| [ResetMaterialPropertyStateToShaderDefault](ResetMaterialPropertyStateToShaderDefault.md) | 把指定属性恢复到 shader 默认值，并清除 serialized 标志。 |
|
||||
| [ApplyMaterialAuthoringPresenceToState](ApplyMaterialAuthoringPresenceToState.md) | 从原始 source text 判断哪些 keyword / property / texture 真正出现在 authoring 文本里。 |
|
||||
| [BuildMaterialAssetFileText](BuildMaterialAssetFileText.md) | 按当前状态生成材质资产 JSON 文本。 |
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- `CollectMaterialPropertyStates(...)` 会优先按 shader property 顺序排序；没有 shader schema 时才退回名字排序。
|
||||
- `SyncMaterialAssetStateWithShader(...)` 会保留“同名且类型兼容”的旧编辑值，同时丢弃陈旧属性。
|
||||
- shader pass 里声明的 keyword 会被整理成 `MaterialKeywordState`；之前已启用的 keyword 会尽量保留 `serialized` 状态。
|
||||
- `ApplyMaterialAuthoringPresenceToState(...)` 会区分：
|
||||
- `properties`
|
||||
- `textures`
|
||||
- `keywords`
|
||||
- `renderState`
|
||||
这样 Inspector 可以知道某项是默认值，还是作者在材质文件里显式写过的覆盖。
|
||||
- `BuildMaterialAssetFileText(...)` 会省略未序列化的默认项，只写当前确实需要落盘的字段。
|
||||
- `BuildMaterialAssetFileText(...)` 同时负责把 `renderQueue`、tags、textures 和 `renderState` override 编码成最终 JSON。
|
||||
|
||||
## 测试
|
||||
|
||||
- `tests/Editor/test_material_inspector_material_state_io.cpp` 当前覆盖：
|
||||
- 只标记 source authored 的 entries
|
||||
- 按 shader schema 保留兼容 override 并丢弃陈旧属性
|
||||
- 把声明过的 keyword 补成 disabled entries
|
||||
- 恢复 shader 默认值
|
||||
- 省略未序列化默认值
|
||||
- 写出 texture 与 render-state 覆盖
|
||||
|
||||
## 相关函数页面
|
||||
|
||||
- [IsTextureMaterialPropertyType](IsTextureMaterialPropertyType.md)
|
||||
- [CollectMaterialPropertyStates](CollectMaterialPropertyStates.md)
|
||||
- [SyncMaterialAssetStateWithShader](SyncMaterialAssetStateWithShader.md)
|
||||
- [ResetMaterialPropertyStateToShaderDefault](ResetMaterialPropertyStateToShaderDefault.md)
|
||||
- [ApplyMaterialAuthoringPresenceToState](ApplyMaterialAuthoringPresenceToState.md)
|
||||
- [BuildMaterialAssetFileText](BuildMaterialAssetFileText.md)
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [panels](../panels.md)
|
||||
- [MaterialInspectorMaterialState](../MaterialInspectorMaterialState/MaterialInspectorMaterialState.md)
|
||||
- [Material](../../../Resources/Material/Material/Material.md)
|
||||
- [Shader](../../../Resources/Shader/Shader/Shader.md)
|
||||
@@ -0,0 +1,21 @@
|
||||
# ResetMaterialPropertyStateToShaderDefault
|
||||
|
||||
**命名空间**: `XCEngine::Editor`
|
||||
|
||||
**类型**: `free function`
|
||||
|
||||
**源文件**: `editor/src/panels/MaterialInspectorMaterialStateIO.h`
|
||||
|
||||
**描述**: 把指定材质属性恢复到 shader 默认值，并清除该属性的 `serialized` 覆盖标志。
|
||||
|
||||
## 当前行为
|
||||
|
||||
- 只有 shader 有效、属性名非空且目标属性存在时才可能成功
|
||||
- 会在 shader 默认属性列表中查找同名同类型的默认值
|
||||
- 成功后把属性值恢复为默认值，并把 `serialized` 置回 `false`
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [MaterialInspectorMaterialStateIO](MaterialInspectorMaterialStateIO.md)
|
||||
- [MaterialInspectorMaterialState](../MaterialInspectorMaterialState/MaterialInspectorMaterialState.md)
|
||||
- [SyncMaterialAssetStateWithShader](SyncMaterialAssetStateWithShader.md)
|
||||
@@ -0,0 +1,22 @@
|
||||
# SyncMaterialAssetStateWithShader
|
||||
|
||||
**命名空间**: `XCEngine::Editor`
|
||||
|
||||
**类型**: `free function`
|
||||
|
||||
**源文件**: `editor/src/panels/MaterialInspectorMaterialStateIO.h`
|
||||
|
||||
**描述**: 以 shader schema 为准重建 `MaterialAssetState` 的 property/keyword 列表，同时尽量保留兼容的已有编辑值。
|
||||
|
||||
## 当前行为
|
||||
|
||||
- shader 无效时会清空 `keywords` 与 `properties`
|
||||
- 会先生成 shader 默认属性状态，再把“同名且类型兼容”的旧值拷回去
|
||||
- 陈旧或已不在 schema 内的属性会被丢弃
|
||||
- keyword 列表按 shader pass 声明重建，并尽量保留旧的 `serialized` 状态
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [MaterialInspectorMaterialStateIO](MaterialInspectorMaterialStateIO.md)
|
||||
- [MaterialInspectorMaterialState](../MaterialInspectorMaterialState/MaterialInspectorMaterialState.md)
|
||||
- [Shader](../../../Resources/Shader/Shader/Shader.md)
|
||||
@@ -2,46 +2,22 @@
|
||||
|
||||
**命名空间**: `XCEngine::Editor`
|
||||
|
||||
**类型**: `class`
|
||||
**类型**: `historical page`
|
||||
|
||||
**源文件**: `editor/src/panels/XCUIDemoPanel.h`
|
||||
**描述**: 历史保留页，记录旧版 editor 曾存在的 XCUI demo panel。当前 `editor/src/panels` 源树里已经没有对应 header，因此这页不再作为 source-backed 的 active panel 文档。
|
||||
|
||||
**描述**: 一个编辑器工作区面板，用固定 demo draw list 演示“XCUI draw command -> ImGuiTransitionBackend -> ImDrawList”的过渡渲染链。
|
||||
## 当前状态
|
||||
|
||||
## 概览
|
||||
- 旧文档引用的 `editor/src/panels/XCUIDemoPanel.h` 已不在当前代码树中。
|
||||
- 当前 `editor/src/panels` 更接近真实结构的新增 source-backed 页面是：
|
||||
- [MaterialInspectorMaterialState](../MaterialInspectorMaterialState/MaterialInspectorMaterialState.md)
|
||||
- [MaterialInspectorMaterialStateIO](../MaterialInspectorMaterialStateIO/MaterialInspectorMaterialStateIO.md)
|
||||
- 因此这页应被理解为历史迁移记录，而不是当前 editor 面板目录的 canonical 入口。
|
||||
|
||||
`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<XCUIDemoPanel>()`。
|
||||
- `Render()` 最终通过成员 `m_backend` 调用：
|
||||
- `BeginFrame()`
|
||||
- `Submit(drawData)`
|
||||
- `EndFrame(ImGui::GetWindowDrawList())`
|
||||
|
||||
## 当前边界
|
||||
|
||||
- 这是展示过渡后端的 demo panel，不是正式 editor XCUI shell。
|
||||
- 当前没有独立单测；它的关键桥接行为主要由 `tests/Editor/test_xcui_imgui_transition_backend.cpp` 间接覆盖。
|
||||
- 旧版文档树里它曾经用于说明 XCUI 到 ImGui 过渡渲染链的实验性 panel。
|
||||
- 当前保留该页，主要是避免旧链接直接失效，并为后续文档重构提供迁移锚点。
|
||||
|
||||
## 相关文档
|
||||
|
||||
|
||||
@@ -33,7 +33,8 @@
|
||||
- [SceneViewPanel](SceneViewPanel/SceneViewPanel.md)
|
||||
- [GameViewPanel](GameViewPanel/GameViewPanel.md)
|
||||
- [ViewportPanelContent](ViewportPanelContent/ViewportPanelContent.md)
|
||||
- [XCUIDemoPanel](XCUIDemoPanel/XCUIDemoPanel.md)
|
||||
- [MaterialInspectorMaterialState](MaterialInspectorMaterialState/MaterialInspectorMaterialState.md)
|
||||
- [MaterialInspectorMaterialStateIO](MaterialInspectorMaterialStateIO/MaterialInspectorMaterialStateIO.md)
|
||||
|
||||
## 分层关系
|
||||
|
||||
@@ -63,11 +64,18 @@
|
||||
|
||||
这几页则更多承担“把视口请求嵌入面板”的职责，真正的渲染仍由 `ViewportHostService` 管理。
|
||||
|
||||
### XCUI 过渡演示面板
|
||||
### Inspector 材质状态 helper
|
||||
|
||||
- `XCUIDemoPanel`
|
||||
- `MaterialInspectorMaterialState`
|
||||
- `MaterialInspectorMaterialStateIO`
|
||||
|
||||
它当前不是正式 XCUI shell，而是把 `UIDrawData` 通过 `ImGuiTransitionBackend` 刷到 ImGui 的演示入口。
|
||||
这两页不是 panel 本体，而是挂在 `editor/src/panels` 目录下、服务 `InspectorPanel` 材质 authoring 流程的状态与 I/O helper。
|
||||
|
||||
### 历史过渡页面
|
||||
|
||||
- [XCUIDemoPanel](XCUIDemoPanel/XCUIDemoPanel.md)
|
||||
|
||||
这是一页保留的历史文档；当前 `editor/src/panels` 源树里已经没有对应 header。
|
||||
|
||||
## 当前实现特点
|
||||
|
||||
|
||||
@@ -43,7 +43,7 @@
|
||||
- `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`。
|
||||
- `new_editor/src/Shell/UIEditorPanelFrame.cpp` 和多组 editor integration 测试当前直接构建 `UIDrawList`；旧版 `editor/src/panels/XCUIDemoPanel.cpp` 已不在当前代码树中。
|
||||
|
||||
## 相关文档
|
||||
|
||||
|
||||
Reference in New Issue
Block a user