indicatrix_dispatch/lib.rs
1//! Sample-range and work-item scheduling for indicatrix render lanes.
2//!
3//! This crate is the scheduler a render coordinator runs: several backends ("lanes":
4//! a joined remote worker, the coordinator's own CPU/GPU, anything implementing
5//! [`WorkerLane`]) contribute disjoint absolute sample ranges to ONE image, and their
6//! per-chunk radiance sums are merged into one buffer with an exact sample count.
7//!
8//! It holds no networking, no GUI and no GPU code. It depends only on the protocol
9//! crate (for [`indicatrix_net::SceneState`]) and `glam`, so it can be linked into the
10//! worker binary as well as the desktop app.
11//!
12//! # Why merging by plain addition is sound
13//!
14//! A path sample is identified by `(global_pixel_index, absolute_sample_index)` and
15//! nothing else, on every backend. Any set of backends tracing **disjoint** sample
16//! ranges of the **same scene at the same resolution** therefore merges by per-pixel
17//! addition, divided by the total count. Disjointness is the whole correctness
18//! guarantee, and [`SampleCursor`] provides it by construction.
19//!
20//! # Contents
21//!
22//! - [`SampleCursor`]: the atomic claim point handing out disjoint sample ranges.
23//! - [`WorkerLane`], [`ChunkResult`], [`SampleRange`]: what a lane is and returns.
24//! - [`RateModel`], [`ChunkPolicy`]: per-lane throughput calibration and chunk sizing.
25//! - [`LanePool`]: N lanes against one cursor for one image epoch, with failure
26//! reclaim, backoff, retirement, cancellation and events.
27//! - [`Merger`]: the deterministic, chunk-start-ordered merge of chunk sums.
28//! - [`CancelToken`]: a cloneable cancellation flag.
29
30mod cancel;
31mod lane;
32mod merge;
33mod pool;
34mod rate;
35mod sample_cursor;
36
37pub use cancel::CancelToken;
38pub use lane::{ChunkResult, SampleRange, WorkerLane};
39pub use merge::{MergeError, Merger, ParkedBudget};
40pub use pool::{
41 LaneFeed, LanePool, MergerMismatch, PoolConfig, PoolEvent, PoolOutcome, PoolStatus,
42};
43pub use rate::{ChunkPolicy, DEFAULT_MAX_CHUNK_SAMPLES, RateModel, marginal_rate};
44pub use sample_cursor::SampleCursor;