Struct Output 

pub struct Output { /* private fields */ }

A pipeline with its output format chosen, ready to be pulled.

Nothing has executed yet: the terminals on this type are what pull pixels through the graph.

Implementations

impl Output

pub const fn format(&self) -> Format

The format this output will be encoded as.

pub const fn options(&self) -> EncodeOptions

The encoder options in effect.

pub fn threads(self, threads: usize) -> Self

Run this pipeline on a private pool of threads worker threads.

Zero means one per available core. One gives a fully deterministic serial run, which is what the differential tests against the reference evaluator use.

This is for tests, benchmarks and one-off tools. The pool is spawned for this run and joined when it ends, so a host running many outputs at once should leave this unset and let them share Scheduler::global — or pass its own with Output::with_scheduler.

pub fn with_scheduler(self, scheduler: Arc<Scheduler>) -> Self

Run on scheduler instead of Scheduler::global.

For a host that wants image work on a pool it sized itself — say, four threads on a sixteen-core machine — build one Scheduler at startup and pass the same one to every output. Building one per request defeats the point: each brings its own threads. Many pipelines may run on one scheduler at once, from any threads. Output::threads and Output::scheduler_options are ignored when one is set: the scheduler was configured when it was built.

pub const fn scheduler_options(self, options: SchedulerOptions) -> Self

Run this pipeline on a private pool tuned by options.

As with Output::threads, the pool exists for this run only. To tune the pool every output shares, build a Scheduler with these options once and pass it to Output::with_scheduler.

pub fn write(self, sink: impl Sink) -> Result<()>

Run the pipeline, streaming encoded bytes into sink.

Rows are encoded and written in order as they are produced. A failure anywhere fails the whole call; partial output is never reported as success (ARCHITECTURE §Failure model), though bytes already handed to sink are of course already gone — a caller needing all-or-nothing should write to a buffer or a temporary and commit on success.

Errors

Returns PixelsError::Unsupported if the format has no encoder in this build, and otherwise any error from the pipeline or the sink.

pub fn write_with_stats(self, sink: impl Sink) -> Result<RunStats>

Stream to sink, reporting what the run did.

The same work as Output::write, with RunStats returned instead of discarded. Use it to confirm a pipeline streamed rather than materialized, or that a JPEG thumbnail took the shrink-on-load path: stats.reduction is None when the source decoded at full size, which is the difference between a fast thumbnail and a slow one.

Errors

As Output::write.

pub fn bytes_via_reference(self) -> Result<Vec<u8>>

Run the pipeline through the reference evaluator instead of the tile scheduler, collecting encoded bytes.

The reference evaluator is single-threaded and whole-image: it holds every intermediate in full, so it is slow and its memory scales with the image. It exists because it is obviously correct, which makes it the oracle the scheduler is verified against — the two must produce byte-identical output for every pipeline (ROADMAP M2).

Use it to verify, to debug a suspected scheduler bug, or where an image is small and determinism matters more than throughput. Prefer Output::bytes otherwise.

Errors

As Output::bytes.

pub fn bytes(self) -> Result<Vec<u8>>

Run the pipeline, collecting encoded bytes into a Vec.

Errors

As Output::write.

Trait Implementations

impl Clone for Output

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Output

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.