137 lines
9.0 KiB
Markdown
137 lines
9.0 KiB
Markdown
# 消灭 EngineEventBridge：引擎纯库化计划
|
||
|
||
## 背景与目标
|
||
|
||
现状：app 通过 `EngineEventBridge`（app/engineeventbridge.*，十几个实例）+ 引擎 C 事件
|
||
（engine/src/capi/events.cpp，75 个 OAKENGINE_EVENT_*）接收引擎回调。问题：
|
||
|
||
- 约 60% 的事件是 app 自己调用引擎时同步产生的，app 本来就知道，不需要被"通知"。
|
||
- 裸 C 回调（userdata=this）无生命周期追踪，已制造多起 UAF 崩溃（最近修掉 3 处，仍有
|
||
14 处靠人工 unsubscribe 保命）。
|
||
- `OAKENGINE_EVENT_AUDIO_MANAGER_OUTPUT_NOTIFY(141)` 与
|
||
`PLAYBACK_CACHE_INVALIDATED(141)` ID 撞号，音频续推订阅实际从未生效（现存 bug）。
|
||
- 引擎因此不是一个纯库，且后续 AI 助理等新写入方会进一步放大"变更来源"的复杂度。
|
||
|
||
目标架构（单向依赖）：
|
||
|
||
```
|
||
app 编辑路径 ──同步调用──> engine（纯库，只保留内部 Qt 信号供自身机制使用）
|
||
app 编辑路径 ──app 内部 Qt 信号──> app 各视图（播放头、undo、结构、参数）
|
||
engine 异步事件（任务/缓存/音频）──极窄 C 通道（queue 到 GUI 线程）──> app
|
||
```
|
||
|
||
- 引擎内部信号（Node::value_changed、Project::node_added 等）保留——它们是
|
||
PreviewAutoCacher/ProjectCopier 等引擎自身机制的生命线，但不许越界给 app 同步事件。
|
||
- C ABI 事件面从 75 个收窄到 ~10 个真异步事件。
|
||
- 消灭 `EngineEventBridge` 类和全部裸 `oakengine_event_subscribe` 调用点。
|
||
|
||
## 事件分类结论（来自全量盘点）
|
||
|
||
- **(a) 同步 app 发起（~60%）**：Node 编辑族、folder、track/block 结构、marker、
|
||
workarea、viewer 参数、color、context position、group passthrough。
|
||
注意每个都有三个旁路来源：undo/redo 重放、项目加载批量、引擎内部联动——
|
||
不能只在调用点处理，必须经"命令执行器/加载完成"统一钩子。
|
||
- **(b) 真异步（必须保留通知）**：TASK 族（120–127）、PLAYBACK_CACHE_VALIDATED/
|
||
INVALIDATED、FRAME_CACHE_INVALIDATED、AUDIO_MANAGER_OUTPUT_PARAMS/NOTIFY。
|
||
- **(b') playhead/length**：playhead 是 app 播放循环自己 set 的，消费者遍布 10+ 组件
|
||
——本质是 app 内部广播，挪进 app 侧 PlaybackController，引擎零参与。
|
||
length 是引擎推导状态，改为编辑后主动查询。
|
||
- **(c) undo 驱动**：UNDO_INDEX_CHANGED、PROJECT_MODIFIED_CHANGED 及全部会被
|
||
undo 重放重发的结构事件——app 侧 UndoController 发粗粒度信号，视图惰性刷新。
|
||
|
||
## 阶段计划
|
||
|
||
### P0 — 冻结分类表 + 修音频事件 ID 撞号（先行 bug fix）
|
||
- events.h 给 AUDIO_MANAGER_OUTPUT_NOTIFY 分配新 ID（如 144），events.cpp 补
|
||
AudioManager::output_notify 的 wire-up（当前 case 141 只做 PlaybackCache cast，
|
||
音频订阅永远返回 0）。
|
||
- 产出 docs/zh/event-bridge-inventory.md：75 事件 → (a)/(b)/(b')/(c) 四类的映射表
|
||
（基于本次盘点结果），作为后续迁移的对账单。
|
||
|
||
### P1 — PlaybackController（消灭 playhead/length 订阅，~12 处）
|
||
- 新建 `app/playback/playbackcontroller.{h,cpp}`（QObject，Core 持有单例）：
|
||
- 信号：`playhead_changed(oak::Node viewer, Rational time)`、
|
||
`viewer_length_changed(oak::Node, Rational)`。
|
||
- ViewerWidget 播放循环/seek 的 `oakengine_viewer_set_playhead` 调用处统一经它发出；
|
||
其它 set_playhead 调用点（timelinewidget、timeruler、multicam）同样经它。
|
||
- length：各 viewer 参数编辑点 + undo 后主动 `viewer_output_length()` 查询并广播变化。
|
||
- 迁移订阅者：timebasedview、resizabletimelinescrollbar（部分）、
|
||
nodeparamviewwidgetbridge/keyframecontrol/connectedlabel（3 个裸 C）、export dialog、
|
||
timelinewidget、viewerdisplay。
|
||
- 收益：顺带消灭 4 个裸 C 订阅中的 3 个和播放头族全部事件。
|
||
|
||
### P2 — EngineAsyncEvents（收窄 C 事件面到 ~10 个）
|
||
- 新建 `app/asyncengineevents.{h,cpp}`（唯一 dispatcher，Core 持有）：
|
||
- 对 TASK 族、CACHE_VALIDATED/INVALIDATED、FRAME_CACHE_INVALIDATED、
|
||
AUDIO_OUTPUT_PARAMS/NOTIFY 各建一个 C 订阅，回调里只做
|
||
`QMetaObject::invokeMethod(this, ..., Qt::QueuedConnection)` 统一回 GUI 线程，
|
||
再 emit 类型化 Qt 信号。
|
||
- 明确文档化：这是引擎→app 的唯一反向通道，只覆盖真异步事件。
|
||
- 迁移订阅者：mainstatusbar、taskmanager 面板、taskviewitem、task dialog、
|
||
timeruler 缓存条、viewer 的 cache invalidated、viewer 音频续推（接 P0 修好的 ID）。
|
||
- engine/include/oakengine/events.h：同步事件常量标注 deprecated（先不删，P5 后清理）。
|
||
|
||
### P3 — UndoController + 粗粒度模型变更信号（消灭 undo 族 + 结构类订阅）
|
||
- 新建 `app/undo/undonotifier.{h,cpp}`：
|
||
- 包装所有 `oakengine_undo_push/undo/redo` 的 app 调用点（集中在少数几处：
|
||
oakengine_undo_push_or_run 的 app 侧、Core、各面板直接 push 处）；
|
||
命令执行后、undo/redo 后、项目加载完成后，emit：
|
||
- `structure_changed()`（节点/边/track/block/folder 增删移动）
|
||
- `params_changed()`（值/关键帧/label/flags）
|
||
- `modified_changed(bool)`（给 core.cpp:1108 的 setWindowModified）
|
||
- `undo_index_changed(int)`（给 historywidget）
|
||
- 项目加载（TaskDialog 完成）后也发一次 structure_changed + params_changed，
|
||
替代加载期批量事件驱动建视图的路径（nodeviewcontext、projectviewmodel 依赖它）。
|
||
- 迁移结构类订阅：nodeviewcontext（节点/边增删）、nodeview（removed_from_graph）、
|
||
timelinewidget（track/block 结构）、projectviewmodel（folder/label）、
|
||
mainwindow（ViewerPanel 关闭）、trackviewitem。
|
||
迁移方式：订阅粗粒度信号 → 对应视图做惰性重建/刷新（NodeView/Timeline 本就按
|
||
context 重建，成本可控；projectviewmodel 用 model reset）。
|
||
- historywidget 与 core.cpp 的 UNDO_INDEX_CHANGED/MODIFIED 订阅改为 UndoController 信号。
|
||
|
||
### P4 — 参数类订阅迁移（最大量、逐面板）
|
||
- 原则：编辑发起处直接刷新 + UndoController::params_changed 惰性兜底。
|
||
- nodeparamviewwidgetbridge（滑条值）：SliderBase 编辑路径已知道新值（直接 set）；
|
||
undo/加载后靠 params_changed 触发受影响 item 重读。
|
||
- keyframeview/keyframecontrol（关键帧按钮/曲线）：编辑路径直接刷新 +
|
||
params_changed 全量重读。
|
||
- nodeviewitem（label/color/message/array size）、nodeparamviewitem/arraywidget、
|
||
connectedlabel、seekablewidget（marker/workarea）、viewerdisplay（字幕）、
|
||
multicamwidget（size/par）、manageddisplay（OCIO 配置）、audiowaveformview。
|
||
- 每迁完一个面板，删除其 EngineEventBridge 成员与全部 `bridge_->subscribe` 调用。
|
||
|
||
### P5 — 拆除与收尾
|
||
- 删除 app/engineeventbridge.{h,cpp} 及全部引用；删除各裸
|
||
`oakengine_event_subscribe` 调用点（P1–P4 应已清零，grep 验证）。
|
||
- engine/src/capi/events.cpp：同步事件订阅路径下线（保内部引擎信号）；
|
||
events.h 同步事件常量删除或移入内部头；C ABI 只保留 P2 的异步集合 + undo 族
|
||
（undo 族是否保留视 P3 后 app 是否还有 C 调用方——AI 助理未来仍可能需要，
|
||
保留 UNDO_INDEX_CHANGED 和 MODIFIED 两个 C 事件是可接受的例外）。
|
||
- 更新 docs/zh/event-bridge-inventory.md 为"迁移完成对照表"，
|
||
更新 docs/zh/investigation-edge-display-and-playback.md 收尾记录。
|
||
|
||
## 验证方案（每阶段都要过）
|
||
|
||
1. `cmake --build cmake-build-debug -j8` 零错误零新警告。
|
||
2. `ctest -j4` 122/122。
|
||
3. 手工检查表（每阶段对应项）：
|
||
- 播放：画面/声音正常、播放头移动、拖动播放头不崩。
|
||
- 节点图：边全部显示、增删节点/边即时刷新、切换素材不丢。
|
||
- 时间线：增删 clip/track 即时刷新、缓存条随渲染增长。
|
||
- 参数面板：滑条值随编辑/undo 刷新、关键帧按钮状态正确。
|
||
- 项目浏览器：导入素材/改名/撤销即时刷新。
|
||
- 状态栏/任务面板：转码任务进度实时更新。
|
||
- 历史面板：undo/redo 列表与选中行正确，标题栏修改标记正确。
|
||
|
||
## 风险与对策
|
||
|
||
- **粗粒度信号导致过度刷新**：NodeView/Timeline 重建成本高。对策：P3 先只在
|
||
structure_changed 上做惰性（queued + 合并多次变更一次刷）；profiling 不行再退回
|
||
按面板细化。
|
||
- **漏掉旁路发射源**（引擎内部联动、multicam）：对策：迁移期在引擎 emit 点临时加
|
||
计数日志（复用 OAK_DEBUG_EDGES 模式），手工操作对照表逐项过一遍确认无未覆盖事件。
|
||
- **加载期建视图路径**：原来靠批量事件驱动；P3 的"加载完成后 structure_changed"
|
||
必须覆盖 nodeviewcontext、projectviewmodel、timelinewidget 三处的初始构建。
|
||
- **UndoController 覆盖不全**（某些面板直接 oakengine_undo_push）：grep 全部调用点
|
||
收口，禁止新增未经 UndoController 的 push（code review 条目）。
|