liboakengine Facade 迁移路线图

本文把"编辑器 UI 迁移到 liboakengine C ABI(facade)"这一独立工程拆解为可执行的阶段。背景与已完成的基础见各提交:28c442623(引擎拆分)、bff06e00e(Core 拆分)、以及 facade 各族提交(ipc/init/project/timeline/renderer/footage/export + 两轮编辑原语)。

终态定义

liboakengine.so 只导出 oakengine_* C 符号(nm -D --defined-only 除 oakengine_* 外为零,与 liboakcore 相同标准)。
oak-editor 与 oak-render-worker 不再引用任何引擎 C++ 符号,全部经 facade(或其 C++ 包装层,模式同 liboakcore 的 wrapper)访问引擎。
全部现有测试(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。缺口按优先级:

节点图族(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 的效果栈遍历。
关键帧族(oakengine_keyframe_*):增删改、时间/值/缓动(bezier 四点)、按参数遍历。
序列结构族:轨道高度、静音/锁定、轨道重命名/重排/删除;marker 增删改;播放头 scrub 状态。
选择/命令族:undo 命令描述(label)、按命名命令打包的编辑操作(对齐 app 命令名,便于 UI 直接映射)。
素材管理族:relink、代理状态查询/生成(ProxyManager 已有引擎实现,直接包)、footage 参数覆盖。
预览控制族:播放/暂停/倍速、音频表读数(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 周,按面板逐个)

顺序(依赖递增):

Export 对话框—— facade export 族已就绪,最先切,删 UI 侧 ExportTask 直驱。
Footage 属性/项目浏览器—— footage 族 + 素材管理族。
序列参数/时间标尺/工作区—— timeline 族已就绪。
时间线面板—— 需要选择族+编辑原语全集;UI 动作→facade 命令一一映射(参照 timelineundogeneral 的命名)。
节点参数面板/效果控件—— 需要节点图族+关键帧族。
预览/播放—— 预览控制族。
多机位/标记/其余面板。

每切一个面板:该面板的 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

5.2 KiB Raw Blame History