docs: align widgets and editor panel notes with refactor
This commit is contained in:
@@ -2,61 +2,39 @@
|
||||
|
||||
**命名空间**: `XCEngine::Editor`
|
||||
|
||||
**类型**: `state structs`
|
||||
**类型**: `struct family`
|
||||
|
||||
**源文件**: `editor/src/panels/MaterialInspectorMaterialState.h`
|
||||
|
||||
**描述**: Material Inspector 的本地编辑状态模型，集中保存标签、keyword、属性、render-state 覆盖和加载/dirty/error 标志。
|
||||
**描述**: 材质 Inspector 编辑状态头文件，定义标签、关键字、属性以及整个材质资产编辑会话的内存态。
|
||||
|
||||
## 概述
|
||||
## 公开声明
|
||||
|
||||
`MaterialInspectorMaterialState.h` 不是一个 panel，而是 `InspectorPanel` 中材质资产编辑流程使用的状态容器集合。当前主要包括：
|
||||
| 声明 | 说明 |
|
||||
|------|------|
|
||||
| `MaterialTagEditRow` | 单条 tag 编辑行 |
|
||||
| `MaterialKeywordState` | 单个 shader keyword 的值与 serialized 标志 |
|
||||
| `MaterialPropertyState` | 单个材质属性的编辑状态 |
|
||||
| `MaterialAssetState` | 一整份材质资产在 Inspector 里的临时编辑状态 |
|
||||
|
||||
- `MaterialTagEditRow`
|
||||
- 一行 tag 名/值编辑缓存。
|
||||
- `MaterialKeywordState`
|
||||
- 单个 shader keyword 的值和是否需要序列化。
|
||||
- `MaterialPropertyState`
|
||||
- 单个材质属性的编辑态，覆盖 float/int/bool/texture 等值。
|
||||
- `MaterialAssetState`
|
||||
- 整个材质资产当前在 Inspector 中的编辑快照。
|
||||
## 当前角色
|
||||
|
||||
## 当前状态内容
|
||||
`MaterialInspectorMaterialState.h` 不负责文件读写，也不直接驱动 UI 绘制。
|
||||
它的职责是把材质编辑链路中需要长期驻留在面板里的状态统一收口，包括：
|
||||
|
||||
`MaterialAssetState` 当前收口了：
|
||||
- 资产路径与展示名称
|
||||
- shader 路径文本
|
||||
- render queue / render state override
|
||||
- tags / keywords / properties 的 staged 值
|
||||
- 错误信息、dirty 标志和 loaded 标志
|
||||
|
||||
- 资产路径、全路径和显示名
|
||||
- `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) 会基于这份状态做同步与序列化
|
||||
- `MaterialAssetState::Reset()` 会把整份编辑状态恢复到初始空态
|
||||
- `MaterialPropertyState` 同时覆盖 float/int/bool/texture 四类值槽位
|
||||
- `serialized` 标志用于区分“当前值是否显式存在于材质 authoring 文本中”
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [panels](../panels.md)
|
||||
- [MaterialInspectorMaterialStateIO](../MaterialInspectorMaterialStateIO/MaterialInspectorMaterialStateIO.md)
|
||||
- [Material](../../../Resources/Material/Material/Material.md)
|
||||
|
||||
@@ -6,64 +6,34 @@
|
||||
|
||||
**源文件**: `editor/src/panels/MaterialInspectorMaterialStateIO.h`
|
||||
|
||||
**描述**: Material Inspector 状态与 shader/material/source text 之间的同步 helper，负责属性快照收集、schema 对齐、authoring presence 标记和材质文件文本生成。
|
||||
**描述**: 材质 Inspector 状态与 shader / authoring 文本之间的同步与序列化辅助函数集合。
|
||||
|
||||
## 概述
|
||||
## 概览
|
||||
|
||||
`MaterialInspectorMaterialStateIO` 把 Material Inspector 的几条关键数据流集中到一起：
|
||||
`MaterialInspectorMaterialStateIO.h` 是 [MaterialInspectorMaterialState](../MaterialInspectorMaterialState/MaterialInspectorMaterialState.md)
|
||||
的配套辅助层，负责三类工作：
|
||||
|
||||
1. 从运行时 `Material` 收集可编辑属性状态
|
||||
2. 按 shader schema 把现有状态重排、补齐或丢弃
|
||||
3. 根据 source text 标记哪些 keyword / property / texture 真正来自作者输入
|
||||
4. 把编辑状态重新编码成材质资产文本
|
||||
- 从运行时 `Material` 收集属性状态
|
||||
- 根据 shader 元数据同步和重置状态
|
||||
- 根据当前状态重新生成材质资产文本
|
||||
|
||||
## 公开函数
|
||||
|
||||
| 函数 | 说明 |
|
||||
|------|------|
|
||||
| [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 文本。 |
|
||||
| `IsTextureMaterialPropertyType(...)` | 判断某个属性类型是否按纹理处理 |
|
||||
| `CollectMaterialPropertyStates(...)` | 从 `Material` 抽取属性状态数组 |
|
||||
| `SyncMaterialAssetStateWithShader(...)` | 依据 shader 元数据补齐或修正状态 |
|
||||
| `ResetMaterialPropertyStateToShaderDefault(...)` | 把指定属性重置为 shader 默认值 |
|
||||
| `ApplyMaterialAuthoringPresenceToState(...)` | 根据 authoring 文本标记哪些字段已显式序列化 |
|
||||
| `BuildMaterialAssetFileText(...)` | 按当前状态生成材质资产文本 |
|
||||
|
||||
## 当前实现行为
|
||||
## 当前角色
|
||||
|
||||
- `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)
|
||||
这组函数把“面板里的 staged 状态”与“磁盘上的材质 authoring 文件”连接起来，
|
||||
因此它们是 Material Inspector 从查看模式走向可编辑模式的关键拼装层。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [panels](../panels.md)
|
||||
- [MaterialInspectorMaterialState](../MaterialInspectorMaterialState/MaterialInspectorMaterialState.md)
|
||||
- [Material](../../../Resources/Material/Material/Material.md)
|
||||
- [Shader](../../../Resources/Shader/Shader/Shader.md)
|
||||
|
||||
@@ -2,25 +2,33 @@
|
||||
|
||||
**命名空间**: `XCEngine::Editor`
|
||||
|
||||
**类型**: `historical page`
|
||||
**类型**: `legacy panel note`
|
||||
|
||||
**描述**: 历史保留页，记录旧版 editor 曾存在的 XCUI demo panel。当前 `editor/src/panels` 源树里已经没有对应 header，因此这页不再作为 source-backed 的 active panel 文档。
|
||||
**描述**: 已退役的 XCUI 过渡演示面板说明页。当前源码树中不再存在 `editor/src/panels/XCUIDemoPanel.h/.cpp`。
|
||||
|
||||
## 当前状态
|
||||
|
||||
- 旧文档引用的 `editor/src/panels/XCUIDemoPanel.h` 已不在当前代码树中。
|
||||
- 当前 `editor/src/panels` 更接近真实结构的新增 source-backed 页面是：
|
||||
- [MaterialInspectorMaterialState](../MaterialInspectorMaterialState/MaterialInspectorMaterialState.md)
|
||||
- [MaterialInspectorMaterialStateIO](../MaterialInspectorMaterialStateIO/MaterialInspectorMaterialStateIO.md)
|
||||
- 因此这页应被理解为历史迁移记录，而不是当前 editor 面板目录的 canonical 入口。
|
||||
`XCUIDemoPanel` 对应的 panel 实现已经从当前 editor 源树移除，因此这里不再把它描述成“仍在运行中的当前面板”。
|
||||
|
||||
## 保留原因
|
||||
## 历史角色
|
||||
|
||||
- 旧版文档树里它曾经用于说明 XCUI 到 ImGui 过渡渲染链的实验性 panel。
|
||||
- 当前保留该页，主要是避免旧链接直接失效，并为后续文档重构提供迁移锚点。
|
||||
这个页面保留的原因，是它曾经承担过一段明确的过渡职责：
|
||||
|
||||
- 在 editor 仍由 ImGui 承载主工作区时，给 XCUI draw data 提供一个演示入口
|
||||
- 通过 `ImGuiTransitionBackend` 把 `UIDrawData` 翻译为 ImGui `ImDrawList`
|
||||
- 用于验证 XCUI 绘制命令与编辑器旧前端之间的桥接链路
|
||||
|
||||
## 当前替代关系
|
||||
|
||||
在当前源码布局里，这条旧链路已经被拆散并下沉到更明确的部件：
|
||||
|
||||
- XCUI demo runtime 声明收口到 [XCUIDemoRuntime](../../XCUIBackend/XCUIDemoRuntime/XCUIDemoRuntime.md)
|
||||
- 过渡渲染桥接逻辑收口到 [ImGuiTransitionBackend](../../XCUIBackend/ImGuiTransitionBackend/ImGuiTransitionBackend.md)
|
||||
- 通用绘制命令模型仍由 [DrawData](../../../UI/DrawData/DrawData.md) 描述
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [panels](../panels.md)
|
||||
- [XCUIDemoRuntime](../../XCUIBackend/XCUIDemoRuntime/XCUIDemoRuntime.md)
|
||||
- [ImGuiTransitionBackend](../../XCUIBackend/ImGuiTransitionBackend/ImGuiTransitionBackend.md)
|
||||
- [DrawData](../../../UI/DrawData/DrawData.md)
|
||||
|
||||
Reference in New Issue
Block a user