Trait DecodeJob 

pub trait DecodeJob<'a>: Sized {
    type Error: Error + Send + Sync + 'static;
    type Dec: Decode<Error = Self::Error>;
    type StreamDec: StreamingDecode<Error = Self::Error> + Send;
    type AnimationFrameDec: AnimationFrameDecoder<Error = Self::Error> + Send + 'static;

    // Required methods
    fn with_stop(self, stop: StopToken) -> Self;
    fn with_limits(self, limits: ResourceLimits) -> Self;
    fn probe(&self, data: &[u8]) -> Result<ImageInfo, Self::Error>;
    fn output_info(&self, data: &[u8]) -> Result<OutputInfo, Self::Error>;
    fn decoder(
        self,
        data: Cow<'a, [u8]>,
        preferred: &[PixelDescriptor],
    ) -> Result<Self::Dec, Self::Error>;
    fn push_decoder(
        self,
        data: Cow<'a, [u8]>,
        sink: &mut dyn DecodeRowSink,
        preferred: &[PixelDescriptor],
    ) -> Result<OutputInfo, Self::Error>;
    fn streaming_decoder(
        self,
        data: Cow<'a, [u8]>,
        preferred: &[PixelDescriptor],
    ) -> Result<Self::StreamDec, Self::Error>;
    fn animation_frame_decoder(
        self,
        data: Cow<'a, [u8]>,
        preferred: &[PixelDescriptor],
    ) -> Result<Self::AnimationFrameDec, Self::Error>;

    // Provided methods
    fn with_policy(self, _policy: DecodePolicy) -> Self { ... }
    fn probe_full(&self, data: &[u8]) -> Result<ImageInfo, Self::Error> { ... }
    fn with_crop_hint(self, _x: u32, _y: u32, _width: u32, _height: u32) -> Self { ... }
    fn with_orientation(self, _hint: OrientationHint) -> Self { ... }
    fn with_start_frame_index(self, _index: u32) -> Self { ... }
    fn with_extract_gain_map(self, _extract: bool) -> Self { ... }
    fn extensions(&self) -> Option<&dyn Any> { ... }
    fn extensions_mut(&mut self) -> Option<&mut dyn Any> { ... }
    fn dyn_decoder(
        self,
        data: Cow<'a, [u8]>,
        preferred: &[PixelDescriptor],
    ) -> Result<Box<dyn DynDecoder + 'a>, BoxedError>
       where Self: 'a { ... }
    fn dyn_animation_frame_decoder(
        self,
        data: Cow<'a, [u8]>,
        preferred: &[PixelDescriptor],
    ) -> Result<Box<dyn DynAnimationFrameDecoder>, BoxedError>
       where Self: 'a,
             Self::AnimationFrameDec: Send { ... }
    fn dyn_streaming_decoder(
        self,
        data: Cow<'a, [u8]>,
        preferred: &[PixelDescriptor],
    ) -> Result<Box<dyn DynStreamingDecoder + 'a>, BoxedError>
       where Self: 'a,
             Self::StreamDec: Send { ... }
}

Per-operation decode job.

Created by DecoderConfig::job(). Holds limits, cancellation, and decode hints. Probing lives here because it needs the limits/stop context.

Decode hints

Hints let the caller request spatial transforms (crop, scale, orientation) that the decoder may apply during decode. The decoder is free to ignore any hint. Call output_info() after setting hints to learn what the decoder will actually produce.

Required Associated Types

type Error: Error + Send + Sync + 'static

The codec-specific error type.

type Dec: Decode<Error = Self::Error>

Single-image decoder type.

type StreamDec: StreamingDecode<Error = Self::Error> + Send

Streaming decoder type.

Implements StreamingDecode for batch/scanline-level decode. Set to () if the codec does not support streaming decode.

type AnimationFrameDec: AnimationFrameDecoder<Error = Self::Error> + Send + 'static

Full-frame animation decoder type.

Must be 'static and Send — frame decoders own their data (typically by copying the input slice at construction time). This lets callers drop the input buffer while still iterating frames, and use decoders across thread boundaries (e.g., in pipeline Source implementations).

Required Methods

fn with_stop(self, stop: StopToken) -> Self

Set cooperative cancellation token.

StopToken is Clone + Send + Sync + 'static — an owned, type-erased stop. Convert any Stop + 'static with StopToken::new(stop).

fn with_limits(self, limits: ResourceLimits) -> Self

Override resource limits for this operation.

fn probe(&self, data: &[u8]) -> Result<ImageInfo, Self::Error>

Probe image metadata cheaply (header parse only).

O(header), not O(pixels). Parses container headers to extract dimensions, format, and basic metadata. May not return frame counts or data requiring a full parse.

fn output_info(&self, data: &[u8]) -> Result<OutputInfo, Self::Error>

Predict what the decoder will produce given current hints.

Returns dimensions, pixel format, and which hints were honored. Call after setting hints, before creating a decoder.

fn decoder( self, data: Cow<'a, [u8]>, preferred: &[PixelDescriptor], ) -> Result<Self::Dec, Self::Error>

Create a one-shot decoder bound to data.

The decoder stores the Cow and borrows from it via core::ops::Deref. Pass Cow::Borrowed(&slice) for zero-copy slice access, or Cow::Owned(vec) to donate a buffer (avoids a copy in codecs that need owned data internally).

preferred is a ranked list of desired output formats. The decoder picks the first it can produce without lossy conversion. Pass &[] for the decoder’s native format.

fn push_decoder( self, data: Cow<'a, [u8]>, sink: &mut dyn DecodeRowSink, preferred: &[PixelDescriptor], ) -> Result<OutputInfo, Self::Error>

Decode directly into a caller-owned sink (push model).

Calls begin() once, then pushes strips via provide_next_buffer(), then calls finish(). Returns OutputInfo describing what was produced.

preferred is a ranked list of desired output formats.

Codecs with native row/strip streaming should write decoded rows directly into the sink. Codecs that can only do one-shot decode should call zencodec::helpers::copy_decode_to_sink() as a fallback.

fn streaming_decoder( self, data: Cow<'a, [u8]>, preferred: &[PixelDescriptor], ) -> Result<Self::StreamDec, Self::Error>

Create a streaming decoder that yields scanline batches.

Returns an error if the codec does not support streaming decode.

preferred is a ranked list of desired output formats.

See StreamingDecode for the batch pull API.

fn animation_frame_decoder( self, data: Cow<'a, [u8]>, preferred: &[PixelDescriptor], ) -> Result<Self::AnimationFrameDec, Self::Error>

Create a full-frame animation decoder.

The decoder composites internally and yields full-canvas frames. The decoder calls Cow::into_owned() to take ownership of the data (required because AnimationFrameDec: 'static). When the caller passes Cow::Owned(vec), this is a free move with no copy.

preferred is a ranked list of desired output formats.

Provided Methods

fn with_policy(self, _policy: DecodePolicy) -> Self

Set decode security policy (controls metadata extraction, parsing strictness, etc.).

Default no-op. Codecs that support policy check the flags in DecodePolicy to decide what to extract and accept.

fn probe_full(&self, data: &[u8]) -> Result<ImageInfo, Self::Error>

Probe image metadata with a full parse.

May be expensive (e.g., parsing all GIF frames to count them). Returns complete metadata including frame counts.

Default: delegates to probe().

fn with_crop_hint(self, _x: u32, _y: u32, _width: u32, _height: u32) -> Self

Hint: crop to this region in source coordinates.

The decoder may adjust for block alignment (JPEG MCU boundaries).

fn with_orientation(self, _hint: OrientationHint) -> Self

Set orientation handling strategy.

See OrientationHint for the available strategies. Default: OrientationHint::Preserve.

fn with_start_frame_index(self, _index: u32) -> Self

Hint: start decoding from a specific frame (0-based).

For animation formats, the decoder seeks to the nearest keyframe at or before index and composites forward to produce the requested frame as the first yielded result.

Only meaningful before animation_frame_decoder().

fn with_extract_gain_map(self, _extract: bool) -> Self

Opt in to supplementary gain map extraction.

When true, codecs that support gain maps (AVIF tmap, JXL jhgm, JPEG UltraHDR) extract and attach gain map data to decode output extras. Typically set after probing reveals a gain map is present.

fn extensions(&self) -> Option<&dyn Any>

Access codec-specific extensions for this job.

Returns a reference to a 'static extension type stored inside the job. Callers downcast via Any::downcast_ref to the codec’s extension type. Returns None if the codec has no extensions.

fn extensions_mut(&mut self) -> Option<&mut dyn Any>

Mutable access to codec-specific extensions.

fn dyn_decoder( self, data: Cow<'a, [u8]>, preferred: &[PixelDescriptor], ) -> Result<Box<dyn DynDecoder + 'a>, BoxedError>

where Self: 'a,

Create a type-erased one-shot decoder.

Returns a boxed closure that decodes to owned pixels. All hints and preferences are bound before this call.

Example

let decode = config.job()
    .with_crop_hint(0, 0, 800, 600)
    .dyn_decoder(data, &[PixelDescriptor::rgb8()])?;

let output: DecodeOutput = decode.decode()?;

fn dyn_animation_frame_decoder( self, data: Cow<'a, [u8]>, preferred: &[PixelDescriptor], ) -> Result<Box<dyn DynAnimationFrameDecoder>, BoxedError>

where Self: 'a, Self::AnimationFrameDec: Send,

Create a type-erased full-frame animation decoder.

Example

let mut dec = config.job()
    .dyn_animation_frame_decoder(data, &[])?;

while let Some(frame) = dec.render_next_frame_owned(None)? {
    // process frame
}

fn dyn_streaming_decoder( self, data: Cow<'a, [u8]>, preferred: &[PixelDescriptor], ) -> Result<Box<dyn DynStreamingDecoder + 'a>, BoxedError>

where Self: 'a, Self::StreamDec: Send,

Create a type-erased streaming decoder.

Example

let mut dec = config.job()
    .dyn_streaming_decoder(data, &[])?;

while let Some((y, strip)) = dec.next_batch()? {
    // process strip
}

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors