Trait Decoder 

pub trait Decoder: Send + Debug {
    // Required methods
    fn descriptor(&self) -> ImageDescriptor;
    fn read_row(&mut self, out: &mut [u8]) -> Result<()>;

    // Provided methods
    fn capability(&self) -> DecodeCapability { ... }
    fn orientation(&self) -> Orientation { ... }
    fn animation(&self) -> Option<Animation> { ... }
    fn icc_profile(&self) -> Option<&[u8]> { ... }
    fn read_region(
        &mut self,
        region: Region,
        out: &mut TileMut<'_>,
    ) -> Result<()> { ... }
    fn reduced_descriptor(&self, target: (u32, u32)) -> Option<ImageDescriptor> { ... }
    fn reduce_to(&mut self, descriptor: ImageDescriptor) -> Result<()> { ... }
}

Decodes a byte stream into rows of pixels.

Implementations must return PixelsError::Malformed for every input they cannot parse. Panicking on hostile bytes is a defect, not a caller error (ARCHITECTURE §Failure model); every parser is fuzzed in CI from the first codec onward.

Dimension limits are enforced at header parse, before any pixel buffer is allocated, so a header claiming enormous dimensions costs nothing.

Required Methods

fn descriptor(&self) -> ImageDescriptor

The shape of the image, known after the header is parsed.

fn read_row(&mut self, out: &mut [u8]) -> Result<()>

Decode the next row, top to bottom, into out.

out is exactly ImageDescriptor::row_bytes long. Each call advances the cursor by one row; the caller reads descriptor().height rows.

Errors

Returns PixelsError::Malformed on invalid or truncated input, PixelsError::Io on source failure, or PixelsError::InvalidArgument if out is the wrong length or every row has already been read.

Provided Methods

fn capability(&self) -> DecodeCapability

What this decoder can produce without a full decode.

fn orientation(&self) -> Orientation

How the stored image must be turned to display upright, as its metadata declares.

Reported, never applied: rows come out in stored order whatever this says. Applying it is the pipeline’s auto_orient decision (SPEC §Safety and limits), which a decoder that rotated its own output would take away from the caller. Known after the header is parsed, like Decoder::descriptor.

fn animation(&self) -> Option<Animation>

The source’s animation, if it has more than one frame.

Reported, like Decoder::orientation: rows are always the first frame’s. Known once the decoder is constructed; a format that must read further to count its frames does so up front.

fn icc_profile(&self) -> Option<&[u8]>

The embedded ICC colour profile, if the file carries one.

Reported, never applied, like Decoder::orientation: samples come out as stored, and converting them is the pipeline’s decision. Known after the header is parsed; a profile stored after the image data is not seen.

fn read_region(&mut self, region: Region, out: &mut TileMut<'_>) -> Result<()>

Decode an arbitrary region into out.

Only meaningful when Decoder::capability is DecodeCapability::Regions; the default implementation reports that this decoder is sequential.

Errors

Returns PixelsError::Unsupported for sequential decoders, and otherwise as Decoder::read_row.

fn reduced_descriptor(&self, target: (u32, u32)) -> Option<ImageDescriptor>

What this decoder would produce if asked for target or larger, when the format lets it reach that size more cheaply than a full decode.

JPEG is the motivating case — the low-frequency corner of a DCT block is a smaller version of that block, so 1/8, 1/4 and 1/2 come almost free — but nothing here is JPEG-specific: a pyramidal TIFF or a WebP with scaled decode fits the same shape.

Pure: nothing is committed. The planner asks before it knows whether the reduction is legal for the pipeline as a whole.

The returned descriptor is never smaller than target in either axis.

fn reduce_to(&mut self, descriptor: ImageDescriptor) -> Result<()>

Commit to producing descriptor, which Decoder::reduced_descriptor must have returned.

Errors

Returns PixelsError::Unsupported if this decoder has one resolution, or PixelsError::InvalidArgument if any row has already been read — the resolution is fixed from the first row onward.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors