oak-editor/docs/zh/plans/riir/notes.md

# 记录项

## common

CancelableObject只在render和task处有🚰，移入对应模块。

## 从 oakcommon（src/common）移除的类（2026-08-05）

判据：不严重依赖 common 其他类，且只有一个非 common 模块使用它
（tests/gtest 不计入使用方）。以下类已从 `src/common/` 移除，
拆分时应放到对应模块：

| 类 | 唯一使用方 | 应放到 |
|---|---|---|
| `Html`（html.h/.cpp） | engine/node | oaknode（M3）。注意它依赖 common 的 xmlutils，迁移时需连同 XML 辅助或改为调用 oakcommon C API |
| `JobTime`（jobtime.h/.cpp） | engine/render | oakrender（M7） |
| `OTIOUtils`（otioutils.h） | engine/task | oaktask（M8） |
| `PlaybackAudioClock`（playbackaudioclock.h） | engine/audio | oakaudio（M6） |
| `to_hex`（tohex.h） | engine/node | oaknode（M3） |
| `mid()`（util.h） | engine/node | oaknode（M3） |
| `AVFramePtr`（avframeptr.h） | engine/render | oakrender（M7） |
| `CrashpadInterface`（crashpadinterface.h/.cpp） | app/main.cpp | app（crashhandler 相关） |
| crashpadutils.h | app/crashhandler | app/crashhandler |
| `AutoScroll`（autoscroll.h，oakutil shim） | app/dialog、app/widget | app |
| `digit.h`（oakutil shim） | app/dialog | app |
| `range.h`（oakutil shim） | app/widget | app |

另：`power.h`、`memorypool.h`、`threadsafemap.h` 当前没有任何
common 模块外的使用方（零用户），不满足移除判据，暂保留在
oakcommon；后续若确认无用途可直接删除。

## oakcommon 去Qt化的删除与语义变更（2026-08-05）

去Qt化过程中以下函数被删除或语义变化，迁移调用方时需注意：

- `CommandLineParser::print_help()`：不再自动读取
  `QCoreApplication::applicationName()/applicationVersion()`，需先调
  `set_app_info()`（C API：`oakcommon_commandlineparser_set_app_info`），
  否则打印默认 `"oak"` + 空版本。
- `FileFunctions::get_unique_file_identifier`：哈希由 SHA-1 改为
  FNV-1a 64-bit，旧缓存 key 全部失效（需一次重建）。
  `get_configuration_location`/`get_application_path`/
  `get_temp_file_path`/`get_auto_recovery_root` 的标准路径改为手写
  平台实现，路径与原 Qt 版不同。`read_file_as_string(":/...")` 的
  qrc 资源路径不再可用，shader 等资源调用方需改为磁盘路径或内嵌。
- xmlutils：`xml_read_next_start_element(reader, CancelAtom*)`
  重载与 cancel_atom 参数删除（依赖 render/cancelatom.h），取消语义
  由调用方在循环外自行检查；`XMLAttributeLoop` 宏删除，由
  `XmlStreamReader::attributes()` + range-for 替代；
  `QXmlStreamReader/Writer` 由基于 expat 的
  `olive::XmlStreamReader/Writer` 替代（不支持 XML 命名空间）。
- `OIIOUtils::frame_to_buffer/buffer_to_frame`：未进 C API，C++ 侧签名
  拍平为 `(const void *data, int64_t linesize_bytes, OIIO::ImageBuf *)`，
  engine/codec/frame.cpp 迁移时传成员即可。`OakCommonPixelFormat` 枚举
  目前定义在 include/common/ocioutils.h，oiioutils 复用，后续可抽成
  独立的 include/common/pixelformat.h。
- `MemoryPool`：删除 QTimer 每 5 秒自动回收空 arena，改为公有
  `clear_empty_arenas()` 由调用方周期调用；不再继承 QObject。
  memorypool/threadsafemap 零使用方且为模板/多态基类，未包 C API。
- `debug_handler`：丢失 `QMessageLogContext`（文件/行号）参数（原实现
  本就未用）；`qInstallMessageHandler` 无对应物。
- `Current::set_current_video_params/audio_params`：由按值拷贝改为持有
  `std::shared_ptr<void>`（类型擦除），调用方需自行管理生命周期并用
  `static_pointer_cast` 还原（调用点：olivehost.cpp、
  timebasedwidget.cpp、plugin.cpp 等 6 处）。
- qtutils：engine 未使用的纯 UI 函数（`q_font_metrics_width`、
  `create_horizontal/vertical_line`、`set_combo_box_data`、
  `word_wrap_string`、`flip_control_and_shift_modifiers`、
  `get_formatted_date_time`、`to_q_color`、`core::qHash`、
  `Q_DECLARE_METATYPE` 宏组）未迁入 oakcommon，app 层继续用 Qt 版。
  `ptr_to_value/value_to_ptr` 载体由 QVariant 改为 `uintptr_t`，
  迁移时调用点需同步改（renderprocessor.cpp、rendermanager.cpp、
  previewautocacher.cpp、src/capi/worker.cpp）。`get_parent_of_type`
  依赖 C++ 模板+RTTI，未进 C API。
- define.h：删除 `MACRO_NAME_AS_STR`/`MACRO_VAL_AS_STR`/
  `OLIVE_NS_CONST_ARG`/`OLIVE_NS_ARG`/`OLIVE_NS_RETURN_ARG`
  （依赖 Qt QArgument，全仓无使用）。
- decibel.h：删除 `ALLOW_RETURNING_INFINITY` 编译开关分支（代码库
  未定义该宏，行为不变）。
- `FFmpegUtils`：新增类内常量 `k_rgb_channel_count/k_rgba_channel_count`
  （3/4）取代对 `VideoParams` 同名常量的引用，消除 common→render
  反向依赖。

## oakundo 去Qt化的删除与语义变更（2026-08-05）

`src/undo/`（olive::UndoCommand / MultiUndoCommand / UndoStack）去Qt化
过程中以下删除与语义变化，迁移调用方时需注意：

- `UndoStack` 不再继承 `QAbstractItemModel`（删除 `Q_OBJECT`、
  `columnCount/data/index/parent/rowCount/headerData/hasChildren` 全部
  model overrides 及 `begin/end*Rows` 通知）。历史面板（QTreeView 等）
  属 app UI 层，迁移时应以 facade 的行式查询
  （command_count/done_count/command_name/command_is_done）自行实现
  model。
- `UndoStack::GetUndoAction/GetRedoAction/update_actions`（QAction 成员
  及其文本/使能维护）删除——QAction 属 app 菜单层，app 应自行创建
  action 并连接 undo/redo；`index_changed(int)` signal 改为 C++ 侧
  `std::function<void(int)>`（`set_index_changed_callback`），C ABI
  不暴露事件，调用方在变更命令后读 `oakundo_undostack_index`。
- `UndoCommand` 与 `olive::Project` 解耦：删除纯虚
  `get_relevant_project()`（含 MultiUndoCommand/EmptyCommand 的
  override）与 `project_` 成员；`redo_and_set_modified/
  undo_and_set_modified` 的修改标记语义改为可选回调对
  `set_modified_callbacks(is_modified, set_modified)`：redo 时记录当前
  修改标记并置 true，undo 时恢复记录值；不挂回调则退化为纯
  redo/undo。读写顺序与 Qt 版一致（redo_now() 之后读取并置位），
  行为对齐。Project 侧迁移时在适配层把 `Project::is_modified/
  set_modified` 绑到这对回调即可。
- `UndoStack` 析构不再调用 `clear()`（Qt 版在析构里 clear 会再 push
  一个 EmptyCommand 造成泄漏），改为直接删除所有持有命令。
- 顺带修复三处 engine 原版就存在的缺陷（迁移调用方无需适配，但
  行为与旧版不同，特此记录）：
  - `jump(0)` 死循环：底部 EmptyCommand 不可 undo，`jump` 现以
    `can_undo()/can_redo()` 为守卫，跳到 0 时停在 index 1；
  - `MultiUndoCommand` 原来不拥有子命令（析构泄漏），现析构删除
    全部 children；
  - `push_pre_executed` 原来不置 `done_` 标记，导致入栈后 undo
    为空操作（facade undo-group 的组撤销实际不生效），现入栈前
    `set_done(true)`（UndoCommand 新增 `set_done()`）。
- `clear()` 推入的占位命令名固定为字面量 "New/Open Project"（原
  `tr()` 翻译移除，翻译由 app 层负责）。
- `push/push_pre_executed` 的命令名由 `QString` 改为 `std::string`；
  C ABI 中 NULL name 视同空串。
- C ABI 句柄语义：`oakundo_command_init/init_multi` 返回的句柄拥有
  底层命令；push 或 `oakundo_command_multi_add_child` 成功后所有权
  转移、wrapper 被消费（不可再用/再 free）；
  `oakundo_command_multi_child` 返回 borrowed wrapper（free 只释放
  wrapper）。

## oaknode 去Qt化的删除与语义变更（2026-08-05）

`src/node/`（Node 族、Project 族、Sequence/Track/Block 族、serializer、
ColorManager）去Qt化过程中的删除与语义变化，迁移调用方时需注意
（详细约定见 `src/node/DEQT.md` §4/§7）：

- 信号槽整组删除：Node 的 28 个信号（label_changed、input_connected、
  keyframe_added、added_to_graph 等）、NodeKeyframe 的 5 个、
  Project/Folder/Sequence/Footage 的全部信号（name_changed、
  modified_changed、track_added、begin/end_insert_item 等），变更通知
  统一由 facade 经 `oakengine_event` 发出，oaknode 不持有上层回调。
- QObject 父子生命周期改显式所有权：Project 持有全部节点
  （`add_node`/`remove_node`，`clear()`/析构删除）；nodeundo 用
  `std::unique_ptr<Node>` 替代 `memory_manager_`；keyframe 经
  `Node::add_keyframe()/remove_keyframe()` 显式注册（自动 set_parent），
  gizmo 经 `Node::add_gizmo()/remove_gizmo()` 显式注册（构造不再自
  注册）；`NodeInputImmediate::delete_all_keyframes(reclaimed)` 替代
  "reparent 续命"。
- polygon/text 的 `generate_frame()` 光栅化（QPainter/QTextDocument）
  改后端钩子：`PathFillBackend`（geometry.h）、`TextMeasureBackend`/
  `TextRenderBackend`（textbackend.h），facade 未安装前输出空白
  （被迫行为差异）。
- gizmo 绘制与 hit-test 归 app 层：各 gizmo 的 `draw(QPainter*)`、
  `PointGizmo::get_clicking_rect()/get_drawing_rect()` 等删除；
  `DraggableGizmo` 的拖拽信号改直调 `parent_node()->gizmo_drag_*()`；
  drag 回调里的 `sender()` 由 `Node::current_gizmo()` 替代。
- footage 离线媒体警示帧：QImage/QPainter 改纯像素循环（深红底+斜纹），
  "Media Offline" 文字叠层与抗锯齿丢失（被迫行为差异）。
- `:/ocioconf` Qt 资源路径不可用：ColorManager 默认配置的 qrc 提取必然
  失败，需 `OCIO` 环境变量指向磁盘 config.ocio（测试用
  `engine/render/ocioconf/config.ocio`）。
- `NodeGroupAddInputPassthrough` 的上游 bug 原样保留（去Qt化不改行为
  逻辑，待单独裁决修复）。
- track.h 的 `QFontMetrics` 13px 常量：轨道默认高度原依赖
  `QFontMetrics(qApp->font()).height()`，去Qt后固化为 13px 字面量，
  换字体/DPI 不再自适应。
- `Footage::check_footage()` 的 QTimer 周期回调删除，函数本体保留为
  public 由 facade 周期调用；`qApp->activeWindow()` 门槛移到 app 层。
- 序列化 XML 元素/属性名与读写顺序逐字节不变；`XmlStreamWriter` 输出
  紧凑 XML（无声明无缩进）；OVEC 压缩段保持 qCompress 兼容
  （zlib + 4 字节大端长度）。
- 修复三个上游真实 bug（行为因此与旧版不同，特此记录）：
  `Project::clear()` 现重置 `root_`（clear 后可再次 initialize）；
  clear 不再先 `set_parent(nullptr)` 再 delete（否则 ~Node 的
  disconnect_edge 触发 parent 不等的 assert）；
  `Sequence` 新增析构删除三个 `TrackList`（原来构造 new 后泄漏）。
- `sender()` 的其他替代：原 keyframe signal→Node 的 5 条失效通知链
  （invalidate_from_keyframe_*）函数本体保留为 public 成员，带
  `NodeKeyframe *key` 显式参数，待 facade 接线。

## 信号与槽的处理策略（2026-08-05）

去Qt化对 Qt 信号槽的统一处理模式，M1–M3 一致执行，后续模块照此：

1. **模块内通知改显式回调/直调（std::function）**：通知双方都在同一
   模块内时，去掉 connect，改为 `std::function` 回调注册或成员直调。
   例：oakundo `UndoStack::index_changed(int)` signal →
   `set_index_changed_callback(std::function<void(int)>)`；oaknode
   `Node::current_gizmo()/set_current_gizmo()` 机制替代 gizmo drag
   回调里的 `sender()`；`DraggableGizmo` 的 handle_start/handle_movement
   信号改直调 `parent_node()->gizmo_drag_start()/gizmo_drag_move()`；
   TrackList 原 track_list_changed/length_changed 发射点直调
   `sequence->update_track_cache()/verify_length()`。
2. **跨层/跨界通知删除，由 facade 经 oakengine_event 统一发出**：
   一切指向 app/UI/其他模块的信号整组删除（Node 28 个、NodeKeyframe
   5 个、Project/Folder/Sequence/Footage 全部），oaknode 自身不持有
   任何上层回调；facade 在执行命令后经既有 `oakengine_event` 通道发
   通知（事件 id 沿用 `oakengine/events.h` 70-95 段，值不变）。依据：
   oaknode 的所有修改都经命令函数完成，调用方知道影响（M3 §2 特殊
   约定 2，04 §3）。
3. **QObject 父子生命周期改显式所有权**：`setParent`/childEvent 机制
   删除，所有权用显式容器与注册函数表达。例：Project 持有节点
   （`add_node`/`remove_node`/`clear()`）；`ColorManager` 由
   `std::unique_ptr` 持有；nodeundo 用 `std::unique_ptr<Node>` 替代
   `memory_manager_`；keyframe/gizmo 分别经 `add_keyframe()`/
   `add_gizmo()` 显式注册；UndoCommand 树由 MultiUndoCommand 析构
   删除 children。
4. **sender() 的替代**：两种形态——拖曳场景用
   `Node::current_gizmo()`（DraggableGizmo 直调回调前后
   `set_current_gizmo(this/nullptr)` 包一层）；通知链场景改显式参数，
   如 `invalidate_from_keyframe_*(NodeKeyframe *key)`。
5. **原 slot 函数本体保留为 public 成员，待 facade 接线**：signal 删了
   但 slot 承载的业务逻辑不删，改为 public 成员函数由上层直调。清单
   见 `src/node/DEQT.md` §7（如 `Sequence::update_track_cache()`、
   `Footage::check_footage()/default_color_space_changed()/
   proxy_ready()/proxy_finished()`、5 条 invalidate_from_keyframe_*）。

## oakrender 去Qt化的删除与语义变更（2026-08-05）

- `RenderTicket::finished` 不再跨线程补发：回调在调用 finish() 的
  线程上触发；未决状态由 facade 自查 `is_running()`。
- PreviewAutoCacher 延迟重排队改显式标志：单次 QTimer 重排队删除，
  `try_render()` 置 `delayed_requeue_pending_`，facade 在
  `requeue_delay_ms()` 后重调 `try_render()`。
- DiskCacheFolder 周期存盘由 GUI 线程 QTimer 改后台线程，数据保护
  用 `std::recursive_mutex`（原靠 QObject 线程亲和串行化）。
- PlaybackCache 的 Qt 信号改单回调注册：`set_invalidated_callback`/
  `set_validated_callback`/`set_requested_callback`/
  `set_cancel_all_callback`；跨层 invalidated/validated 通知由 facade
  在命令后重发（M7 §2.2：oakrender 不持有上层回调）。
- `DiskManager::instance()` 惰性自建（原 app 启动时显式
  create_instance；库消费者不经 facade 也能用）。
- FrameHashCache 帧缓存 JPEG 读写 QImage→OIIO/OpenEXR。
- AudioWaveformCache/PlaybackCache 的 QPainter 绘制归 app 层；
  缓存指示条高度固化为常量 4（`oakrender_cache_indicator_height()`，
  原 `QFontMetrics(QFont()).height()/4`）。
- 离屏 GL 上下文共享组需 app 显式传入（原 QOpenGLContext
  globalShareContext 隐式共享）。
- OpenGLContext/Vulkan 上下文抽象层（OpenGLContextProvider 等）替代
  QOpenGLContext 直用。
- WorkerProcess 仅 POSIX 实现（Windows 占位未做）。
- worker IPC 的 NDJSON 协议未变，workerjson 为本地（去 Qt）实现。
- `:/shaders` qrc 资源缺口：着色器源码的 Qt 资源路径在库形态下
  不可用，需 app 侧提供文件映射。
- 删除 ipc/ipcmessage.cpp 等 3 个过期 .cpp（对应头已自包含 inline，
  .cpp 内容失效）。
- displayinternal.h 分层违规（render→src/capi）并入 texturehandle.h。
- Renderer 线程亲和由 QObject::thread() 改显式 owner thread
  （`set_owner_thread_to_current()`/`called_on_owner_thread()`）。

## oaktimeline 去Qt化的删除与语义变更（2026-08-05）

- TimelineMarker/TimelineWorkArea 的信号（time_changed/name_changed/
  color_changed/enabled_changed/range_changed/marker_added/removed/
  modified）全部删除，变更通知由 facade 层在命令后发出；list 的重排由
  TimelineMarker::set_time 直调 parent_->resort(this)。
- TimelineMarker::draw()/get_marker_height()（QPainter/QFontMetrics）
  删除，归 app 层。
- TimelineMarkerList 的 QObject childEvent 自动注册改为显式
  add_marker(std::unique_ptr)/remove_marker 所有权转移；marker 构造
  不再带 parent 参数（oaknode 的 4 个 serializer 调用点已适配）。
- ViewerOutput 的 workarea_/markers_ 由 QObject 父子管理改为
  std::unique_ptr 持有。
- timeline 全部 undo 命令类改为持有 oaknode C 句柄
  （OakNodeTrack/OakNodeBlock/OakNodeSequence），图操作全部经
  oaknode C ABI（01 §0 铁律 6）；为此 oaknode C API 新增：
  copy_in_graph、clip_add_cache_passthrough_from、block_get_kind、
  block_as_node/from_node、track_as_node、nearest_block_before/after_or_at、
  command_create_remove_node/add_node/set_position_recursive、
  node_get_project、input_array_insert/remove、connect/disconnect_element、
  tracklist_get_sequence/track_input_id/array_append/array_remove_last/
  get_array_index_from_cache_index、sequence_as_node、node_get_markers/
  get_work_area（后两个为 oaktimeline 的借用出口）。
- UndoCommand 跨模块继承（oaktimeline 命令类继承 oakundo 的
  olive::UndoCommand）保留——undo 架构的既有跨模块模式，记录为
  01 §5 的明确例外（oaknode 的 nodeundo 同例）。
- **修复 de-Qt 断链**：Block 长度变化不再经信号通知 Track，改为
  Block::InputValueChangedEvent 里对 track_->block_length_changed(this)
  直调（原 Qt 版 connect 链，wave-2 遗留的 facade 接线项提前兑现）。
- 命令创建的 GapBlock 在插入 track 前必须先进项目图
  （block_add_to_graph/block_remove_from_graph helper，对齐原版
  setParent(graph)/setParent(memory) 语义）；孤立句柄用 orphan 标志
  跟踪，析构时 oaknode_block_free。
- oaknode↔oaktimeline 运行期互相解析（add_default_nodes →
  TimelineAddTrackCommand），双方 dylib dynamic_lookup，测试二进制
  必须同时链两个库（各 standalone 驱动已接线）。
- oakcommon xml C API 新增 get_native 借用访问器（C++ only），
  oaktimeline 的 load/save 经它取回 XmlStreamReader/Writer。