docs: facade migration roadmap for the remaining UI migration work
This commit is contained in:
@@ -0,0 +1,77 @@
|
||||
# liboakengine Facade 迁移路线图
|
||||
|
||||
本文把"编辑器 UI 迁移到 liboakengine C ABI(facade)"这一独立工程拆解为可执行的阶段。背景与已完成的基础见各提交:`28c442623`(引擎拆分)、`bff06e00e`(Core 拆分)、以及 facade 各族提交(ipc/init/project/timeline/renderer/footage/export + 两轮编辑原语)。
|
||||
|
||||
## 终态定义
|
||||
|
||||
1. `liboakengine.so` 只导出 `oakengine_*` C 符号(`nm -D --defined-only` 除 `oakengine_*` 外为零,与 liboakcore 相同标准)。
|
||||
2. oak-editor 与 oak-render-worker 不再引用任何引擎 C++ 符号,全部经 facade(或其 C++ 包装层,模式同 liboakcore 的 wrapper)访问引擎。
|
||||
3. 全部现有测试(gtest + CLI ctest + 各 C ABI 测试)持续全绿,GL/Vulkan 相关用例可跳过。
|
||||
|
||||
## 现状盘点(已完成)
|
||||
|
||||
- 引擎物理拆分完毕:`engine/` 树 + liboakengine.so;worker 脱 UI(336MB→2.9MB)。
|
||||
- facade 7 族约 118 函数 + 5 个纯 C 测试 + 6 个 CLI ctest;oak-cli 是现成的纯 C ABI 消费者(info/probe/render/transcode)。
|
||||
- 编辑器与引擎的 UI 依赖已全部反转(Core/EngineCore 拆分、handler 钩子体系、枚举下沉、布局数据纯净化)。
|
||||
- 测试基建:make_oakengine_test、GL 门控 SKIP 模式、CLI ctest、沙箱 config。
|
||||
|
||||
## API 缺口(按 UI 需求倒推)
|
||||
|
||||
facade 现状覆盖:项目/序列读写、素材探测与导入、时间线查询与片段编辑、渲染、导出、IPC。缺口按优先级:
|
||||
|
||||
1. **节点图族(oakengine_node_*)**——最大缺口,编辑器操作的实体。
|
||||
- 节点枚举/查询:type id、label、category、输入定义(id/类型/默认值/属性)。
|
||||
- 参数读写:get/set_input(类型化值,参照 NodeValue::Type 到 C 类型映射:float/int/rational(num,den)/color(rgba)/string/bool/vec234)。
|
||||
- 图操作:add_node(factory id)、remove_node、connect(input,output)/disconnect。
|
||||
- 效果链读取:某 sequence/clip 的效果栈遍历。
|
||||
2. **关键帧族(oakengine_keyframe_*)**:增删改、时间/值/缓动(bezier 四点)、按参数遍历。
|
||||
3. **序列结构族**:轨道高度、静音/锁定、轨道重命名/重排/删除;marker 增删改;播放头 scrub 状态。
|
||||
4. **选择/命令族**:undo 命令描述(label)、按命名命令打包的编辑操作(对齐 app 命令名,便于 UI 直接映射)。
|
||||
5. **素材管理族**:relink、代理状态查询/生成(ProxyManager 已有引擎实现,直接包)、footage 参数覆盖。
|
||||
6. **预览控制族**:播放/暂停/倍速、音频表读数(AudioMonitor)、scrub、工作区循环。
|
||||
|
||||
## 阶段计划
|
||||
|
||||
### 阶段 0:冻结契约(1 周)
|
||||
- 将 facade 头文件与语义写进 `docs/facade-api-reference.md`(从各头 Javadoc 生成骨架)。
|
||||
- C++ 包装层生成器/模板定稿(照 liboakcore wrapper 模式,按族手写而非生成,规模可控)。
|
||||
- CI 增加 facade 测试目标(make_oakengine_test 已全部进 ctest,确认 Win/mac 也跑)。
|
||||
|
||||
### 阶段 1:worker 与 CLI 对齐(1-2 周)
|
||||
- oak-render-worker 内部一律改用 oliveimpl 内部头(当前已是),确认其**不依赖** facade; facade 专为外部消费者。
|
||||
- oak-cli 覆盖到 proxy 生成/媒体信息全命令,作为 facade 回归基准。
|
||||
|
||||
### 阶段 2:节点图族(2-4 周)
|
||||
- oakengine_node_* 设计与落地(参数值映射表先行)。
|
||||
- 测试:程序化建图(Solid→LUT→渲染)、参数往返、连接校验、undo。
|
||||
- **里程碑**:oak-cli 能 `oak-cli graph <ove>` 打印效果栈,`oak-cli lut <ove> <lut>` 给指定 clip 加 LUT。
|
||||
|
||||
### 阶段 3:编辑面迁移(4-8 周,按面板逐个)
|
||||
顺序(依赖递增):
|
||||
1. **Export 对话框**—— facade export 族已就绪,最先切,删 UI 侧 ExportTask 直驱。
|
||||
2. **Footage 属性/项目浏览器**—— footage 族 + 素材管理族。
|
||||
3. **序列参数/时间标尺/工作区**—— timeline 族已就绪。
|
||||
4. **时间线面板**—— 需要选择族+编辑原语全集;UI 动作→facade 命令一一映射(参照 timelineundogeneral 的命名)。
|
||||
5. **节点参数面板/效果控件**—— 需要节点图族+关键帧族。
|
||||
6. **预览/播放**—— 预览控制族。
|
||||
7. **多机位/标记/其余面板**。
|
||||
|
||||
每切一个面板:该面板的 UI 代码改为只调 facade(或 wrapper),对应引擎类从 UI 侧 include 中移除;全量测试必须保持绿。
|
||||
|
||||
### 阶段 4:隐藏 C++ 符号(1 周)
|
||||
- app/worker 的引擎符号引用清零后:visibility=hidden + version script(`oakengine_*` 白名单)。
|
||||
- 验收:`nm -D` 仅 `oakengine_*`;全部测试(含 CLI)绿;三平台打包复验。
|
||||
|
||||
## 风险与对策
|
||||
|
||||
- **节点参数类型膨胀**:NodeValue 有 ~20 种类型。先支持编辑器最常用的 8 种(float/int/bool/string/rational/color/vec/combo),其余按面板需要逐个加。
|
||||
- **性能**:参数级 facade 调用频率低(用户操作粒度),不构成问题;渲染/帧路径已有同步封装。
|
||||
- **Qt 对象生命周期**:节点/序列/clip 均为 borrowed handle 随 project;文档已有约定,迁移时沿用。
|
||||
- **undo 语义**:所有编辑原语必须经全局 UndoStack(facade 已强制),UI 侧不得再直接 new 命令。
|
||||
|
||||
## 验收清单(阶段 4 完成时)
|
||||
|
||||
- [ ] `nm -D --defined-only liboakengine.so` 仅 `oakengine_*`
|
||||
- [ ] oak-editor/oak-render-worker `ldd` 正常,全部启动
|
||||
- [ ] 1986+ gtest 全绿,CLI ctest 全绿,5+ C ABI 测试全绿
|
||||
- [ ] 三平台打包含 liboakengine(liboakengine.so/dylib/oakengine.dll),Linux 位于标准 libdir
|
||||
Reference in New Issue
Block a user