Files

T

Mike-Solar fec6e9dba7 render: the M3 OFX host — one oak-worker --ofx-host process for every plugin job

docs/zh/plans/render-pipeline-threads.md M3 (design 3.2): OpenFX crash
isolation moves from "every worker hosts plugins" to a single dedicated
host process, served over NDJSON + shared memory.

- oak-worker --ofx-host mode (src/ofx_host.rs): loads every plugin once,
  resolves jobs by the cross-process-stable OFX identifier, and renders
  through the same in-process executor the workers used to install.
- oak-render/ofxhost.rs: the single-host client. The render manager
  creates and installs it for the Pipeline backend (lazy spawn on the
  first plugin job); eval::process_plugin_job prefers it and falls back
  to the in-process executor otherwise, so the process backend keeps its
  current behavior until M4.
- Data plane: input/output FrameSlotPool pairs (the handshake's input_*
  fields are used for the first time). Named clips and the source frame
  are written to input slots after the explicit CPU readback; the plugin
  output returns through an output slot. Pool size/capacity grow by a
  host restart when a job needs more (safe: submissions are serialized
  and one job is in flight).
- Crash loop: reader EOF fails the in-flight submit, which respawns the
  host and re-posts the same job (frames are read back once); after three
  consecutive crashes the client is permanently dead and the evaluator
  falls back to a purple frame. The dead child is reaped immediately, and
  a submit mutex enforces the one-job-in-flight contract.
- Progress/cancel: the host flushes plugin_progress immediately (live
  progress), and reads stdin on its own thread so plugin_cancel takes
  effect mid-render at the plugin's next progressUpdate; the sticky flag
  resets at progressStart and request_plugin_cancel_all broadcasts to
  both the worker pool and the host.
- JobSpec::Plugin / PluginJobPayload carry the plugin type_id (stable
  across processes); `--ofx-crash-once` / `--ofx-crash-always` are the
  deterministic crash hooks, matching the worker's env hooks.
- Tests: wire round-trips; host unit tests (crash budget, cancel-flag
  reset through the factory, source mapping); oak-worker integration
  tests against the real host + bundled test plugin (render + progress,
  crash respawn and re-post, three-crash give-up, mid-render cancel on
  the new slow variant, concurrent submits); eval's purple fallback.

2026-09-12 23:10:43 +08:00

src

render: the M3 OFX host — one oak-worker --ofx-host process for every plugin job

2026-09-12 23:10:43 +08:00

tests

workspace: zero compiler warnings across all targets

2026-09-11 16:38:44 +08:00

Cargo.lock

core: merge oak-common into oak-core

2026-09-03 17:42:20 +08:00

Cargo.toml

workspace: zero compiler warnings across all targets

2026-09-11 16:38:44 +08:00

COVERAGE.md

workspace: kebab-case crates, app under crates/oak-app, shared versions

2026-08-22 16:58:37 +08:00

README.md

core: merge oak-common into oak-core

2026-09-03 17:42:20 +08:00

README.md

oaknode Rust crate (implementation)

Status: all FFI headers implemented. Phase 1 (core engine: graph arena, values, keyframes, project, factory, ~55 FFI exports), Phase 2 (sequence/track/block/footage/colormanager + traverser + serializer, the folder/group/keyframe/dragger FFI families, the undo/XML bridges with test stubs, and the contract tests) and Phase 3 (the multicam grid family and the deferred bridge exports: markers/work-area/frame cache accessors, viewer params, sequence/footage stream params via the videoparams/audioparams C ABIs, and the colormanager compliant transform) are complete; cargo test --features test-stubs is green (84 tests, 1 ignored byte-exact golden). The remaining todo!()s are the concrete node-type behaviors under src/nodes/ (registered in the factory, bodies deferred) — the multicam node behavior and the effect/generator nodes. The crate template (FFI discipline, testing layers) follows crates/oakplugin/README.md.

Scope

Replaces the C++ oaknode module (src/node/src, ~40k lines): the node graph engine, project/folder/sequence/track/block hierarchy, footage, color manager, keyframes, evaluation (traverser), project serialization, and the undo bridge.

Public contract: include/node/*.h (14 headers, ~280 functions) — frozen, implemented verbatim by src/ffi.rs.

Key architectural decisions (C++ → Rust mapping)

Inheritance → arena + trait objects. The C++ design is deep inheritance (Node → ViewerOutput/Track/Block/… and ~50 effect nodes). Rust: a slab-allocated Graph arena of NodeEntry { core: NodeCore, behavior: Box<dyn NodeBehavior> }, addressed by generational NodeId. No reference cycles exist by construction (edges are IDs, not pointers).
Cross-module inheritance disappears. C++ RenderProcessor : NodeTraverser (render subclassing a node class) becomes a plain evaluation API: traverser::evaluate(...) -> NodeValueTable is a function, and oakrender supplies backend hooks via a trait (RenderHooks) instead of overriding virtuals.
Value system. olive::Variant/type-erasure becomes a closed NodeValue enum (value.rs). C ABI marshalling lives only in ffi.rs.
Undo. Commands are created through the oakundo C ABI (bridge::undo); the C++ UndoCommand subclass hierarchy becomes vtable commands whose userdata is a Rust closure.
Serialization. XML read/write goes through the oak_core C ABI (bridge::common) until oak_core itself is rewritten.
Threading. The C++ code relied on Qt's event thread + called_on_owner_thread() assertions. Rust replaces this with Mutex<Graph> interior mutability plus explicit &mut Graph phases for structural edits; the threading contract is documented per function.

Layout

COVERAGE.md maps every method of the C++ olive::Node (260 declaration lines, ~150 unique methods) to its Rust home — trait / core / graph / ops / bridge / drop-with-reason. Review that first.

src/
  lib.rs         crate doc + module map
  error.rs       error codes (mirrors include/node/error.h)
  handle.rs      refcounted-handle scaffolding (same pattern as plugin)
  value.rs       NodeValue / NodeValueTable / ValueHint
  id.rs          NodeId, generational arena ids
  node.rs        NodeCore + NodeBehavior trait (the virtual surface)
  graph.rs       Graph arena, edges, topological order
  input.rs       Input descriptors, flags, array inputs, hints
  keyframe.rs    NodeKeyframe + track interpolation
  project.rs     Project, settings, folder tree
  sequence.rs    Sequence (ViewerOutput equivalent)
  track.rs       Track, TrackList
  block.rs       Block/ClipBlock/GapBlock/TransitionBlock
  footage.rs     Footage (probe via oakcodec C ABI)
  colormanager.rs ColorManager (OCIO via oakrender C ABI for now)
  traverser.rs   Evaluation engine (iterative, hook-based)
  serializer.rs  XML project load/save (bridge::common)
  factory.rs     Node type registry (id -> constructor)
  nodes/         The concrete built-in node types
  bridge/        C ABI imports: common.rs, undo.rs, render.rs, codec.rs
  ffi.rs         include/node/*.h export layer
tests/           contract + golden tests (see README test section)

Hard rules for the implementer

Every extern "C" body goes through handle::guard*; no panic crosses FFI.
Graph is the only owner of nodes; the public API never hands out references into the arena, only NodeId-carrying handles.
Behavior parity with C++ is proven by the C ABI test-suite (src/node/tests, unchanged) plus the golden tests in tests/.
Where C++ behavior is genuinely load-bearing but ugly (e.g. Block length-change side effects on Track), port the behavior, not the aesthetics; leave a // CPP-PARITY: comment with the C++ file:line.

Dependency policy

Prefer mature third-party crates (MIT/Apache-2.0/BSD, GPL-compatible) over hand-rolling; register each addition (name + reason) here. Large existing C++ libraries (OTIO, OCIO, OIIO, FFmpeg) are NEVER rewritten — they are consumed through their C ABI / bridge layers.