204 lines
10 KiB
Markdown
204 lines
10 KiB
Markdown
# oak-worker (Rust)
|
|
|
|
Headless render worker process — the Rust rewrite of `worker/workermain.cpp`
|
|
(contract: `engine/include/oakengine/worker.h` and
|
|
`engine/include/oakengine/ipc.h`).
|
|
|
|
## Build and test
|
|
|
|
```sh
|
|
cargo build --release # binary: target/release/oak-worker
|
|
cargo test # unit + integration tests
|
|
```
|
|
|
|
The worker is **self-contained** (M14 R2): the whole runtime is compiled
|
|
into this binary and links the module crates directly — no `liboakengine`
|
|
dylib is needed at build or run time.
|
|
|
|
- `src/worker.rs` is the port of `engine/src/capi/worker.cpp`
|
|
`oakengine_worker_main()` and owns the whole runtime: render backend
|
|
selection through the oakrender crate's direct Rust API (dynamic →
|
|
OpenGL fallback), the startup handshake and the NDJSON control loop.
|
|
Since M15 S1 it also renders for real: `load_graph` deserializes the
|
|
snapshot through `oaknode::serializer`, and `render_frame` /
|
|
`render_batch` render through `oakrender::eval` (generated frames,
|
|
footage decode via oakcodec/ffmpeg, montage compositing) directly into
|
|
the main-assigned shared-memory slots. M15 S3 adds `render_audio_batch`
|
|
(audio range pulls mixed by `oakrender::eval::render_audio_samples_into`
|
|
into `SLOT_FORMAT_AUDIO_F32` slots — interleaved f32 — so audio plugin
|
|
crashes take down this process, not the editor).
|
|
- `src/ipc.rs` is a shim re-exporting `oakrender::ipc` (M15 S1): the
|
|
NDJSON protocol and the shared-memory frame-slot transport moved to the
|
|
oakrender crate so both ends of the pipe link one copy (the
|
|
main-process dispatcher in `oakrender::procpool` creates the segments;
|
|
this worker attaches to them).
|
|
|
|
The oakrender module crate (`../oakrender`) is a plain Rust dependency;
|
|
it depends on `ocio-rs` with the `bundled` feature, whose first-time build
|
|
fetches a vendored OpenColorIO dependency (`sse2neon`) from github.com. On
|
|
networks without github access, build with a shared target directory that
|
|
already contains a completed oakrender build tree, e.g.:
|
|
|
|
```sh
|
|
CARGO_TARGET_DIR=/path/to/oak/crates/oakrender/target cargo build --release
|
|
```
|
|
|
|
## What the worker does
|
|
|
|
Same flow as the C++ main, in the same order:
|
|
|
|
1. **parse `--backend <name>`** (the pool spawns workers with `auto`;
|
|
`none` skips renderer creation and the process exits 1, like the C++
|
|
main; `cpu` is the M15 headless render mode — no renderer, but the
|
|
session stays fully operational and renders through the CPU
|
|
evaluation path).
|
|
2. **initialize the render backend** (inside `src/worker.rs`): the
|
|
oakrender `DisplayRenderer` direct Rust API. Under `auto` a failed
|
|
initialization degrades to a cpu-mode session (logged) instead of
|
|
exiting — GPU-less machines keep rendering through the CPU fallback.
|
|
Then the runtime services load (color-manager default config,
|
|
the oakplugin render executor).
|
|
3. **write the startup handshake** (protocol version 1, empty shared-memory
|
|
geometry — same as the C++ worker's startup handshake; the parent
|
|
creates the segments and announces their geometry in its reply).
|
|
4. **serve the NDJSON control loop** on stdin/stdout until a `shutdown`
|
|
message or EOF: `handshake` attaches the announced shared-memory
|
|
frame-slot pools through the real transport and answers `hello_caps`
|
|
(protocol v2: supported slot formats + max slot size); `load_graph`
|
|
deserializes the graph snapshot; `render_frame` renders one frame
|
|
into an acquired slot; `render_batch` renders a batch of
|
|
main-assigned-slot tickets (`batch_accepted` claim confirmation, then
|
|
one `frame_ready`/`frame_failed` per ticket); `cancel` / `shutdown`
|
|
are dispatched by the session. Responses are one compact JSON line
|
|
per message.
|
|
|
|
## Where the rendering happens (no render thread)
|
|
|
|
A frequent reading trap: **oak-worker spawns no render thread.** The
|
|
binary is a deliberately single-threaded NDJSON loop — `main.rs` →
|
|
`worker::worker_main` (`src/worker.rs`) reads one control line from
|
|
stdin, handles it, writes the response, repeat. Rendering happens
|
|
**synchronously on that loop thread** the moment a batch arrives:
|
|
|
|
```
|
|
stdin "render_batch"
|
|
→ WorkerSession::handle_render_batch_stream (src/worker.rs)
|
|
→ render_ticket_to_slot (acquire shm slot)
|
|
→ render_spec_pixels (the actual render)
|
|
→ stdout "frame_ready" / "frame_failed" (one line per ticket)
|
|
```
|
|
|
|
`render_spec_pixels` picks between two render paths per ticket:
|
|
|
|
- **Graph path** (the default when a project snapshot is loaded):
|
|
tickets carry `viewer_node` (the sequence's node identity), the worker
|
|
evaluates the deserialized project through `oak_node::traverser`
|
|
(time-aware, keyframe-resolving), and every node `value()` pushes a
|
|
job payload that `oakrender::eval`'s resolve hooks execute — footage
|
|
decode, **shader effects as wgpu fullscreen passes**
|
|
(`oakrender::shaderfx`: the nodes' embedded GLSL is translated to WGSL
|
|
through naga, uniforms packed std140), OFX plugins through the
|
|
oakplugin render driver. Textures stay GPU-resident across the effect
|
|
chain; the frame is read back once, at the end, into the shm slot.
|
|
- **Montage path** (fallback: no snapshot loaded / legacy tickets): the
|
|
flat wire-spec CPU pipeline (`render_montage_frame_into`).
|
|
|
|
The parallelism is **across processes, not threads**: the main process
|
|
(app side) spawns the pool of `oak-worker` children in
|
|
`oakrender::procpool::ProcessDispatcher` (`spawn_worker` in
|
|
`crates/oak-render/src/procpool.rs`), one shared-memory segment and one
|
|
reader thread per child, and shards ticket batches across them. So
|
|
"no worker ⇒ no rendering" does not imply a hidden render thread — the
|
|
dispatcher has no in-process rendering path at all (M15 S2 deleted it;
|
|
only the test-only inline backend renders in-process). Audio follows
|
|
the same shape via `render_audio_batch` → `render_audio_ticket_to_slot`
|
|
→ `oakrender::eval::render_audio_samples_into`.
|
|
|
|
Consequences worth knowing before editing this file:
|
|
|
|
- A frame render blocks the control loop: `cancel` is observed only
|
|
between batches (batch granularity), which is why the main process
|
|
also stops the render loop on its side.
|
|
- A crash mid-render kills the whole loop — that is the point (OFX
|
|
crash isolation); the dispatcher reaps, re-queues and respawns.
|
|
|
|
## Implemented vs stubbed (nothing is faked)
|
|
|
|
**Real:** argument parsing, render backend initialization (real wgpu
|
|
renderer, dynamic → OpenGL fallback), runtime initialization (color
|
|
config + oakplugin render executor), startup handshake, NDJSON framing,
|
|
message validation (protocol version, handshake geometry, `load_graph`
|
|
file existence/size), the **shared-memory frame-slot transport**
|
|
(`oakrender::ipc` — POSIX `shm_open`/`mmap`/`munmap`/`shm_unlink`, the
|
|
SPSC ring buffer and the frame-slot pool with the exact version-1 shared
|
|
layout; a `handshake` genuinely attaches the output and input pools),
|
|
**graph deserialization** (`oaknode::serializer::load`, plus the minimal
|
|
`{"project_copy":N}` identity payload), **frame rendering into shm
|
|
slots** (`render_frame` v1 + `render_batch` v2: generated frames,
|
|
footage decode, montage compositing, end-of-pipe F32→BGRA8 conversion),
|
|
unknown-type/malformed-message errors, shutdown/EOF termination.
|
|
|
|
**Deferred / known limits:** the graph path is live (tickets with
|
|
`viewer_node` evaluate the loaded project through the node graph). Still
|
|
open: transition blocks render as plain cuts, polygon/mask's CPU
|
|
rasterization stage (the matte generators pass through with a TODO), and
|
|
audio still renders from the montage wire spec (graph audio evaluation
|
|
is later work).
|
|
|
|
**Deviation from the C++:** the startup handshake omits `gl_major`/
|
|
`gl_minor` — the oakrender module exposes no GL context version (the C++
|
|
worker reads them off its `QOpenGLContext`).
|
|
|
|
## Crash-isolation test hooks
|
|
|
|
The batch render path honors two environment variables used by the
|
|
crash-isolation integration tests (`tests/procpool_integration.rs`):
|
|
|
|
- `OAK_WORKER_CRASH_ON_TICKET=<n>` — raise `SIGSEGV` while rendering
|
|
ticket `n` (like a real plugin crash).
|
|
- `OAK_WORKER_CRASH_MARKER=<path>` — when the marker file exists the
|
|
crash is skipped; the hook writes the marker before dying, making the
|
|
crash one-shot so the restarted worker renders the re-queued frame.
|
|
|
|
They are test-only; unset in production.
|
|
|
|
## Layout
|
|
|
|
```
|
|
src/
|
|
main.rs argv --backend scanning (default opengl; last flag wins);
|
|
forwards to worker::worker_main
|
|
worker.rs the real worker runtime: backend selection (oakrender
|
|
DisplayRenderer, dynamic -> OpenGL fallback), WorkerSession,
|
|
handshake + NDJSON loop, real load_graph + render_frame +
|
|
render_batch (M15 S1)
|
|
ipc.rs shim re-exporting oakrender::ipc (M15 S1: both pipe ends
|
|
link one copy of the protocol + shm transport)
|
|
tests/worker.rs binary-level tests (--backend none exit 1;
|
|
--backend cpu handshake + clean exit)
|
|
tests/procpool_integration.rs M15 S1 end-to-end: real workers spawned by
|
|
oakrender::procpool::ProcessDispatcher — batch
|
|
renders into shm slots, crash isolation with
|
|
restart + re-dispatch, zero-copy assertions
|
|
```
|
|
|
|
The NDJSON control-loop behavior is exercised in-process in `src/worker.rs`
|
|
against the local real shared memory (`--backend none` / `--backend cpu`
|
|
sessions, no GPU needed); `tests/procpool_integration.rs` drives real
|
|
worker processes end-to-end through the main-process dispatcher. Run the
|
|
binary against a created segment to see the real attach path:
|
|
|
|
```sh
|
|
target/release/oak-worker --backend cpu <<< '{"type":"shutdown"}'
|
|
```
|
|
|
|
## M15 S2 status
|
|
|
|
The process-isolated backend is now the **default** `RenderManager`
|
|
backend; the in-process render thread pool was deleted (the app drives the
|
|
dispatcher from its UI tick and from blocking ticket waits, and the
|
|
pre-render window feeds the scheduler ahead of the playhead). The worker
|
|
binary is located at `target/debug/oak-worker` next to the main executable
|
|
during development (or via `OAK_WORKER_BIN` / `DispatcherConfig::worker_bin`),
|
|
and bundled alongside the main binaries by the packager (root `Cargo.toml`).
|