# libolivenode.so — 节点图系统 > **依赖**：`libolivecore.so`, `libolivecodec.so` > **外部依赖**：Qt::Core（QObject, QString, XML） > **包含源码**：`app/node/`, `app/timeline/`, `app/undo/`, `app/config/` > **当前状态**：整个项目的**核心枢纽**，被 `render/`, `widget/`, `panel/`, `task/` 等几乎所有上层模块依赖 > **改造难度**：⭐⭐⭐⭐⭐（最困难，耦合最深） --- ## 1. 当前状态分析 `app/node/` 是整个编辑器的**数据与计算模型核心**，采用节点图范式组织所有处理。其特点是： 1. **被几乎所有模块依赖**：`render/` 遍历节点图，`widget/` 绘制节点连接，`panel/` 包装节点编辑器，`task/` 在导出时读取节点图。 2. **头文件耦合严重**：`Node.h` 直接 `#include` 了 `codec/frame.h` 和 `render/` 下的多个头文件（缓存类型、作业类型等）。 3. **Qt 深度集成**：`Node` 继承 `QObject`，使用信号槽、元对象系统、`QVariant`。 4. **序列化内建**：`ProjectSerializer` 支持将节点图保存/加载为 XML。 ### 1.1 关键耦合点与解耦策略 | 耦合点 | 当前状态 | 解耦策略 | |---|---|---| | `Node.h` 包含 `render/rendercache.h` | `Node` 直接操作 `FrameHashCache` | 将缓存失效抽象为虚函数 `InvalidateCache()`，或注入 `NodeCacheCallbacks` 接口指针。移除 `rendercache.h` 的包含。 | | `Node.h` 包含 `render/job/*.h` | `Node::ProcessShader()` 等虚函数使用具体 Job 类型 | 将 `ProcessShader` 等改为接受 `const void* job_data` + `JobType` 枚举，内部再 `static_cast`。或前向声明 Job 类（若已是不透明指针）。 | | `Footage`（`node/project/footage/`）依赖 `Decoder` | `Footage` 需要解码器信息预览 | 保留此依赖，`libolivenode.so` 链接 `libolivecodec.so` 是合理的。 | | `ViewerOutput` 被 UI 直接引用 | `ViewerOutput` 是节点图与 UI 的桥梁 | `ViewerOutput` 保留在 `node/` 中，C API 暴露 `OliveViewerOutput*` 句柄。 | | `timeline/` 依赖 `node/` | `TimelineMarker` 等引用 `Node` | `timeline/` 并入 `libolivenode.so`，不单独拆分。 | | `undo/` 依赖 `node/` | `UndoCommand` 操作 `Node` 对象 | `undo/` 并入 `libolivenode.so`。 | --- ## 2. C API 设计 ### 2.1 头文件：`c_api/include/olive/node_api.h` ```c #ifndef OLIVE_NODE_API_H #define OLIVE_NODE_API_H #ifdef __cplusplus extern "C" { #endif #include "core_api.h" #define OLIVE_NODE_API_VERSION 1 #ifdef OLIVE_BUILDING_NODE # define OLIVE_NODE_API __attribute__((visibility("default"))) #else # define OLIVE_NODE_API #endif /* ========== 不透明类型 ========== */ typedef struct OliveNodeGraph OliveNodeGraph; typedef struct OliveNode OliveNode; typedef struct OliveNodeInput OliveNodeInput; typedef struct OliveNodeOutput OliveNodeOutput; typedef struct OliveParam OliveParam; typedef struct OliveKeyframe OliveKeyframe; typedef struct OliveProject OliveProject; typedef struct OliveSequence OliveSequence; typedef struct OliveTrack OliveTrack; typedef struct OliveClip OliveClip; typedef struct OliveViewerOutput OliveViewerOutput; /* ========== 枚举 ========== */ typedef enum { OLIVE_NODE_TYPE_UNKNOWN = 0, OLIVE_NODE_TYPE_INPUT, OLIVE_NODE_TYPE_OUTPUT, OLIVE_NODE_TYPE_FILTER, OLIVE_NODE_TYPE_DISTORT, OLIVE_NODE_TYPE_GENERATOR, OLIVE_NODE_TYPE_COLOR, OLIVE_NODE_TYPE_AUDIO, OLIVE_NODE_TYPE_TRANSITION, OLIVE_NODE_TYPE_PLUGIN, OLIVE_NODE_TYPE_GROUP, } OliveNodeType; typedef enum { OLIVE_PARAM_TYPE_INT = 0, OLIVE_PARAM_TYPE_DOUBLE, OLIVE_PARAM_TYPE_STRING, OLIVE_PARAM_TYPE_RATIONAL, OLIVE_PARAM_TYPE_COLOR, OLIVE_PARAM_TYPE_BOOL, OLIVE_PARAM_TYPE_VECTOR2, OLIVE_PARAM_TYPE_VECTOR3, OLIVE_PARAM_TYPE_VECTOR4, } OliveParamType; /* ========== API 版本 ========== */ OLIVE_NODE_API int olive_node_api_version(void); /* ========== NodeGraph ========== */ OLIVE_NODE_API OliveNodeGraph* olive_node_graph_create(void); OLIVE_NODE_API void olive_node_graph_destroy(OliveNodeGraph* g); // 序列化 OLIVE_NODE_API int olive_node_graph_load_xml(OliveNodeGraph* g, const char* xml_data, size_t xml_len); OLIVE_NODE_API char* olive_node_graph_save_xml(OliveNodeGraph* g, size_t* out_len); // 节点增删查 OLIVE_NODE_API OliveNode* olive_node_graph_add_node(OliveNodeGraph* g, const char* node_type_id, const char* node_id); OLIVE_NODE_API int olive_node_graph_remove_node(OliveNodeGraph* g, OliveNode* node); OLIVE_NODE_API OliveNode* olive_node_graph_find_node(OliveNodeGraph* g, const char* node_id); OLIVE_NODE_API int olive_node_graph_node_count(OliveNodeGraph* g); OLIVE_NODE_API OliveNode* olive_node_graph_get_node(OliveNodeGraph* g, int index); // 连接管理 OLIVE_NODE_API int olive_node_connect(OliveNode* from_node, int output_index, OliveNode* to_node, int input_index); OLIVE_NODE_API int olive_node_disconnect(OliveNode* node, int input_index); OLIVE_NODE_API OliveNode* olive_node_get_connected_node(OliveNode* node, int input_index); /* ========== Node 属性 ========== */ OLIVE_NODE_API const char* olive_node_get_id(OliveNode* node); OLIVE_NODE_API const char* olive_node_get_label(OliveNode* node); OLIVE_NODE_API OliveNodeType olive_node_get_type(OliveNode* node); OLIVE_NODE_API const char* olive_node_get_type_id(OliveNode* node); OLIVE_NODE_API int olive_node_input_count(OliveNode* node); OLIVE_NODE_API int olive_node_output_count(OliveNode* node); /* ========== Param 操作 ========== */ OLIVE_NODE_API int olive_node_param_count(OliveNode* node); OLIVE_NODE_API OliveParam* olive_node_get_param(OliveNode* node, int index); OLIVE_NODE_API OliveParam* olive_node_find_param(OliveNode* node, const char* param_name); OLIVE_NODE_API const char* olive_param_get_name(OliveParam* param); OLIVE_NODE_API OliveParamType olive_param_get_type(OliveParam* param); OLIVE_NODE_API int olive_param_set_int(OliveParam* param, int64_t value); OLIVE_NODE_API int olive_param_set_double(OliveParam* param, double value); OLIVE_NODE_API int olive_param_set_rational(OliveParam* param, OliveRational value); OLIVE_NODE_API int olive_param_set_color(OliveParam* param, OliveColor value); OLIVE_NODE_API int olive_param_set_string(OliveParam* param, const char* value); OLIVE_NODE_API int64_t olive_param_get_int(OliveParam* param); OLIVE_NODE_API double olive_param_get_double(OliveParam* param); OLIVE_NODE_API OliveRational olive_param_get_rational(OliveParam* param); OLIVE_NODE_API OliveColor olive_param_get_color(OliveParam* param); /* ========== Keyframe ========== */ OLIVE_NODE_API int olive_param_add_keyframe(OliveParam* param, OliveRational time, double value); OLIVE_NODE_API int olive_param_remove_keyframe(OliveParam* param, OliveRational time); OLIVE_NODE_API int olive_param_keyframe_count(OliveParam* param); /* ========== Project ========== */ OLIVE_NODE_API OliveProject* olive_project_create(const char* name); OLIVE_NODE_API void olive_project_destroy(OliveProject* proj); OLIVE_NODE_API int olive_project_load_file(OliveProject* proj, const char* filename); OLIVE_NODE_API int olive_project_save_file(OliveProject* proj, const char* filename); OLIVE_NODE_API OliveNodeGraph* olive_project_get_graph(OliveProject* proj); /* ========== Sequence / Timeline ========== */ OLIVE_NODE_API OliveSequence* olive_sequence_create(const char* name, OliveVideoParams vparams, OliveAudioParams aparams); OLIVE_NODE_API OliveViewerOutput* olive_sequence_get_viewer_output(OliveSequence* seq); /* ========== ViewerOutput（渲染目标） ========== */ OLIVE_NODE_API const char* olive_viewer_output_get_node_id(OliveViewerOutput* viewer); OLIVE_NODE_API OliveVideoParams olive_viewer_output_get_video_params(OliveViewerOutput* viewer); OLIVE_NODE_API OliveAudioParams olive_viewer_output_get_audio_params(OliveViewerOutput* viewer); /* ========== Undo ========== */ typedef struct OliveUndoStack OliveUndoStack; OLIVE_NODE_API OliveUndoStack* olive_undo_stack_create(void); OLIVE_NODE_API void olive_undo_stack_destroy(OliveUndoStack* stack); OLIVE_NODE_API void olive_undo_stack_push(OliveUndoStack* stack, const char* action_name, void* undo_data, void (*undo_fn)(void*), void (*redo_fn)(void*), void (*free_fn)(void*)); OLIVE_NODE_API int olive_undo_stack_can_undo(OliveUndoStack* stack); OLIVE_NODE_API int olive_undo_stack_can_redo(OliveUndoStack* stack); OLIVE_NODE_API void olive_undo_stack_undo(OliveUndoStack* stack); OLIVE_NODE_API void olive_undo_stack_redo(OliveUndoStack* stack); OLIVE_NODE_API void olive_undo_stack_clear(OliveUndoStack* stack); #ifdef __cplusplus } #endif #endif // OLIVE_NODE_API_H ``` ### 2.2 关键解耦实现：NodeCacheCallbacks ```cpp // app/node/node.h（改造后，移除 render/ 头文件包含） // 前向声明 class NodeCacheCallbacks; class Node : public QObject { // ... void SetCacheCallbacks(NodeCacheCallbacks* callbacks); protected: virtual void InvalidateCacheInternal(const TimeRange& range); private: NodeCacheCallbacks* cache_callbacks_ = nullptr; }; // app/node/nodecachecallbacks.h（新增） class NodeCacheCallbacks { public: virtual ~NodeCacheCallbacks() = default; virtual void InvalidateCache(const QString& cache_id, const TimeRange& range) = 0; virtual void InvalidateAllCaches() = 0; }; ``` `RenderManager`（在 `liboliverender.so` 中）实现 `NodeCacheCallbacks`，并在创建节点时注入： ```cpp class RenderCacheCallbacks : public NodeCacheCallbacks { void InvalidateCache(const QString& cache_id, const TimeRange& range) override { // 原有 FrameHashCache 的失效逻辑 } // ... }; ``` 这样 `Node.h` 不再需要包含 `render/rendercache.h`，编译期依赖被打破。 ### 2.3 关键解耦实现：RenderJob 虚函数参数抽象 当前 `Node` 有虚函数： ```cpp // 改造前 virtual void ProcessShader(TexturePtr destination, const Node* node, const ShaderJob* job); ``` 改造后： ```cpp // app/node/jobtypes.h（新增，只含枚举和基类，无 render/ 依赖） enum class NodeJobType { kShader, kGenerate, kFootage, kColorTransform, kSample, kCache, }; struct NodeJobData { NodeJobType type; void* data; // 实际数据由 render/ 中的具体类解释 }; // app/node/node.h virtual void ProcessJob(TexturePtr destination, const NodeJobData& job); ``` `RenderProcessor`（在 `liboliverender.so` 中）调用时： ```cpp ShaderJob job = ...; NodeJobData data{NodeJobType::kShader, &job}; node->ProcessJob(destination, data); ``` --- ## 3. CMake 改造 ```cmake # app/node/CMakeLists.txt set(NODE_INTERNAL_SOURCES node.cpp node.h traverser.cpp traverser.h traverserproxy.cpp traverserproxy.h nodevalue.cpp nodevalue.h # ... 所有 node/ 子目录源文件 ) set(TIMELINE_SOURCES ../timeline/timelinecoordinate.cpp ../timeline/timelinecoordinate.h ../timeline/timelinemarker.cpp ../timeline/timelinemarker.h ../timeline/timelineworkarea.cpp ../timeline/timelineworkarea.h ../timeline/undo/*.cpp ../timeline/undo/*.h ) set(UNDO_SOURCES ../undo/undocommand.cpp ../undo/undocommand.h ../undo/undostack.cpp ../undo/undostack.h ) set(CONFIG_SOURCES ../config/config.cpp ../config/config.h ) set(NODE_API_SOURCES ${CMAKE_SOURCE_DIR}/c_api/src/node_api.cpp ) add_library(olivenode SHARED ${NODE_INTERNAL_SOURCES} ${TIMELINE_SOURCES} ${UNDO_SOURCES} ${CONFIG_SOURCES} ${NODE_API_SOURCES} ) target_compile_definitions(olivenode PRIVATE OLIVE_BUILDING_NODE) target_include_directories(olivenode PRIVATE ${CMAKE_SOURCE_DIR}/app ${CMAKE_SOURCE_DIR}/c_api/include PUBLIC $ ) target_link_libraries(olivenode PUBLIC olivecore olivecodec Qt${QT_VERSION_MAJOR}::Core ) set_target_properties(olivenode PROPERTIES CXX_VISIBILITY_PRESET hidden VISIBILITY_INLINES_HIDDEN YES ) install(TARGETS olivenode DESTINATION lib) install(FILES ${CMAKE_SOURCE_DIR}/c_api/include/olive/node_api.h DESTINATION include/olive) ``` --- ## 4. 小步快跑实施步骤 ### Step 0: 头文件解耦（3–4 天，最关键） - [ ] 创建 `app/node/nodecachecallbacks.h`，定义 `NodeCacheCallbacks` 接口。 - [ ] 修改 `Node.h`：移除 `render/rendercache.h` 包含，添加 `NodeCacheCallbacks*` 成员和 `SetCacheCallbacks()` 方法。 - [ ] 创建 `app/node/jobtypes.h`，定义 `NodeJobType` 枚举和 `NodeJobData` 结构体。 - [ ] 修改 `Node.h`：将所有 `ProcessXxx` 虚函数合并为 `ProcessJob(TexturePtr, const NodeJobData&)`，或保留原签名但将参数类型改为前向声明。 - [ ] 修改 `RenderProcessor`：适配新的 `NodeCacheCallbacks` 和 `NodeJobData`。 **验收标准**：`app/node/` 目录可以独立编译，不直接或间接包含 `app/render/` 下的任何头文件。 ### Step 1: 独立编译 libolivenode.so（1 天） - [ ] 将 `node/`, `timeline/`, `undo/`, `config/` 的源文件聚合，构建为 `olivenode SHARED`。 - [ ] 处理 `node/` 下的 `add_subdirectory` 嵌套，确保所有源文件被正确收集。 **验收标准**：`libolivenode.so` 编译成功，`nm -D libolivenode.so | grep olive_node` 能看到导出的 C 符号。 ### Step 2: 最小 C API（2 天） - [ ] 先实现项目级接口： - `olive_project_create/destroy/load_file/save_file` - `olive_node_graph_create/destroy/load_xml/save_xml` - [ ] 这些接口是渲染子进程最需要的：子进程需要加载 XML 节点图并渲染。 **验收标准**：可以用 C API 创建一个项目、保存为 XML、再加载回来，内容一致。 ### Step 3: 节点操作 API（2 天） - [ ] 实现节点增删查改：`add_node`, `remove_node`, `find_node`, `connect`, `disconnect`。 - [ ] 实现参数读写：`set_param_double`, `get_param_double`, `set_param_rational` 等。 **验收标准**：可以用 C API 构建一个简单的节点图（如 Generator -> ViewerOutput），并序列化为 XML。 ### Step 4: Undo API（1 天） - [ ] 实现 `olive_undo_stack_*` 系列函数。 - [ ] C API 的 undo 采用函数指针回调模式，避免暴露 C++ 的 `UndoCommand` 类。 ### Step 5: ViewerOutput 和 Sequence（1 天） - [ ] 实现 `OliveSequence*` 和 `OliveViewerOutput*` 的 C API。 - [ ] 这是渲染的入口：渲染子进程需要知道哪个 `ViewerOutput` 是输出目标。 --- ## 5. 风险与回退 | 风险 | 对策 | |---|---| | Node.h 解耦工作量过大，影响面太广 | **分阶段**：第一阶段只做"编译期解耦"（移除 include），不改虚函数签名。若仍然困难，允许 `libolivenode.so` 和 `liboliverender.so` 暂时合并为 `libolive-engine.so`，后续再拆分。 | | `QObject` 信号槽跨动态库 | Qt 信号槽跨动态库在正确链接 Qt 的情况下工作正常。确保所有含 `Q_OBJECT` 的类在动态库内被 `moc` 处理。 | | `NodeValueTable` 等模板类难以导出 C 接口 | 不在 C API 中暴露模板类。`NodeTraverser` 的遍历结果（`NodeValueTable`）在 C++ 内部处理，C API 只提供高阶函数如 `olive_node_graph_evaluate_at_time`。 | | 序列化 XML 格式变更 | C API 中的 `load_xml`/`save_xml` 直接使用现有的 `ProjectSerializer`，XML 格式完全不变，向下兼容。 | | `Footage` 节点持有 `Decoder` | `Footage` 内部持有 `DecoderPtr`，C API 不暴露 Decoder 细节，只暴露 `Footage` 的文件路径设置/获取。 |