Crate otf_pixels_core

Expand description

Core engine for otf-pixels: the op graph, tiles, codec traits, and the M1 reference evaluator.

Most users want the otf-pixels facade instead — this crate is the substrate it and the op/codec crates are built on. Depend on it directly when implementing a codec or an op.

§The model

An Image is a handle onto a node of an immutable lazy DAG. Chaining ops builds graph structure and computes descriptors; it reads no pixels. Pixels move only when a terminal pulls them, at which point demand propagates backwards through Op::input_regions and pixels flow forwards through Op::compute (ADR-0001).

use otf_pixels_core::{Format, Image, ImageDescriptor, PixelFormat, TileBuf, evaluate};
use otf_pixels_core::{BufferSource, Producer, Region};
use std::sync::Arc;

let descriptor = ImageDescriptor::new(2, 2, PixelFormat::Gray8)?;
let pixels = TileBuf::from_vec(descriptor.region(), PixelFormat::Gray8, vec![1, 2, 3, 4])?;
let source = BufferSource::new(descriptor, Arc::new(pixels))?;

// Construction and chaining do no pixel work.
let image = Image::from_producer(Arc::new(source), Format::Raw);
assert_eq!(image.metadata()?.width, 2);

// A terminal pulls.
assert_eq!(evaluate(&image)?.bytes(), &[1, 2, 3, 4]);

§Errors never panic

Every fallible path returns PixelsError. Malformed input is a value, not a panic — this crate forbids unsafe and denies unwrap/expect/panic! outside tests, because a hostile image must not be able to take down a process embedding the engine (ARCHITECTURE §Failure model).

§Concurrency

The core is synchronous (ADR-0005). Image is Send + Sync and cheap to clone, so an async host integrates by running pipelines on its own worker threads and meeting the engine at the Source/Sink boundary.

Macros§

dispatch_sample: Dispatch once on a SampleKind into a kernel generic over Sample.

Structs§

Animation: How an animated image plays: its frames and their timing.
BufferSource: A producer over pixels already in memory.
CacheStats: Counters describing cache behaviour, for tests and diagnostics.
DecodedSource: A producer that decodes a stream on demand, forward only.
EncodeOptions: Encoder tuning shared across formats.
Image: A lazily evaluated image: a handle onto one node of an op graph.
ImageDescriptor: The shape of an image at a point in the graph.
Limits: Safety limits applied before any pixel memory is allocated.
Metadata: Header-only facts about an image.
Node: A node in the immutable operation graph.
NodeId: A unique identifier for a graph node.
NodePlan: How the scheduler must treat one node.
Plan: The analysis result for one pipeline.
PlanOptions: Knobs for Plan::build.
Prefixed: A source that replays a buffered prefix before delegating to the rest.
Reduction: A source resolution the planner lowered.
Region: An axis-aligned rectangle of pixels, in image coordinates.
RunStats: Counters describing one run, for tests and diagnostics.
Scheduler: A demand-driven, parallel tile evaluator.
SchedulerOptions: Tuning for a Scheduler.
ThreadPool: A work-stealing pool of worker threads.
Tile: An immutable strided view over a region of pixels.
TileBuf: An owned, densely packed buffer of pixels for one region.
TileCache: A byte-budgeted LRU cache of graph intermediates.
TileKey: Identifies one cached intermediate: a region of one node’s output.
TileMut: A mutable strided view over a region of pixels.

Enums§

AccessPattern: The tile shape an op wants its input delivered in.
ChannelLayout: The channel layout of a pixel, independent of sample type.
ColorModel: The color model a descriptor’s samples are interpreted in.
DecodeCapability: What a decoder can produce without a full decode.
ErrorCode: A stable, machine-readable error classification.
Format: A container format.
Limit: The safety limit that a PixelsError::LimitExceeded refers to.
Orientation: One of the eight orientations the EXIF/TIFF Orientation tag (274) can name.
PixelFormat: An interleaved pixel format: a ChannelLayout over a SampleKind.
PixelsError: The error type returned by every fallible engine operation.
SampleKind: The numeric type of one channel sample.
TileShape: The shape tiles take through a segment of the graph.

Traits§

Codec: Format sniffing.
Decoder: Decodes a byte stream into rows of pixels.
Encoder: Encodes rows of pixels into a byte stream.
Op: A node in the op graph.
Producer: A source of pixels at the root of a graph.
Sample: A channel sample type that kernels can be monomorphized over.
Sink: A sink for encoded bytes.
Source: A forward-only source of bytes.

Functions§

copy_region: Copy the pixels of region from src into dst.
demand: The regions each node of image’s graph would be asked for, for diagnostics.
evaluate: Evaluate image to a whole-image buffer.
evaluate_rows: Evaluate image and hand each output row, top to bottom, to consume.
evaluate_tiled: Evaluate image into one whole-image buffer using the tile scheduler.
shrink_on_load: Rebuild image over a reduced source, if the graph permits it.

Type Aliases§

Result: The engine’s result alias.