zencodec/traits/

decoding.rs

//! Decoder configuration and decode jobs.

use alloc::borrow::Cow;
use alloc::boxed::Box;

use crate::estimate::{ComputeEnvironment, ImageCharacteristics, ResourceEstimate};
use crate::format::ImageFormat;
use crate::orientation::OrientationHint;
use crate::{DecodeCapabilities, DecodeOutput, ImageInfo, OutputInfo, ResourceLimits, StopToken};
use zenpixels::PixelDescriptor;

use super::BoxedError;
use super::decoder::{AnimationFrameDecoder, Decode, StreamingDecode};
use super::dyn_decoding::{
    AnimationFrameDecoderShim, DecoderShim, DynAnimationFrameDecoder, DynDecoder,
    DynStreamingDecoder, StreamingDecoderShim,
};

// ===========================================================================
// Decoder configuration
// ===========================================================================

/// Reusable decoder configuration.
///
/// Implemented by each codec's config type. Config types are `Clone + Send +
/// Sync` with no lifetimes.
///
/// Probing lives on [`DecodeJob`], not here, because probing needs limits
/// and cancellation context.
pub trait DecoderConfig: Clone + Send + Sync {
    /// The codec-specific error type.
    type Error: core::error::Error + Send + Sync + 'static;

    /// Per-operation job type.
    ///
    /// The GAT lifetime `'a` is the data lifetime — it becomes concrete
    /// when the caller passes data to [`DecodeJob::decoder`].
    type Job<'a>: DecodeJob<'a, Error = Self::Error> + 'static;

    /// The image formats this decoder handles.
    ///
    /// A single-format decoder returns one element. Multi-format decoders
    /// (e.g., a bitmap crate handling BMP, ICO, CUR, TGA, PNM) return all
    /// formats they can decode. The dispatch layer registers this config
    /// for each format in the list.
    ///
    /// Must not be empty.
    fn formats() -> &'static [ImageFormat];

    /// Pixel formats this decoder can produce natively.
    ///
    /// Every descriptor is a guarantee: the decoder can produce this format
    /// without lossy conversion. Must not be empty.
    fn supported_descriptors() -> &'static [PixelDescriptor];

    /// Decoder capabilities (metadata support, cancellation, etc.).
    ///
    /// Returns a static reference describing what this decoder supports.
    fn capabilities() -> &'static DecodeCapabilities {
        &DecodeCapabilities::EMPTY
    }

    /// Predict peak memory, wall time, and CPU-core scaling for decoding an
    /// image with the given [`ImageCharacteristics`] on the `compute`
    /// environment.
    ///
    /// The default is [`ResourceEstimate::unknown`] — every field `None`,
    /// i.e. "this codec does not model its resource use." Codecs with a
    /// calibrated decode `heuristics` model override this (a quick option is
    /// [`ResourceEstimate::conservative`]`(image).at_cores(compute.cores())`).
    fn estimate_decode_resources(
        &self,
        image: &ImageCharacteristics,
        compute: &ComputeEnvironment,
    ) -> ResourceEstimate {
        let _ = (image, compute);
        ResourceEstimate::unknown()
    }

    /// Create a per-operation job, consuming the config.
    ///
    /// The job owns the config and all configuration set on it.
    /// The lifetime parameter is the data lifetime, inferred from usage.
    fn job<'a>(self) -> Self::Job<'a>;

    /// One-shot convenience: decode `data` to owned pixels in the decoder's
    /// native pixel format, with default job settings.
    ///
    /// Equivalent to `self.job().decoder(Cow::Borrowed(data), &[])?.decode()`.
    /// For limits, cancellation, decode hints, or pixel-format preferences, go
    /// through [`job()`](DecoderConfig::job).
    ///
    /// ```rust,ignore
    /// let image = zenjpeg::JpegDecoderConfig::new().decode(&bytes)?;
    /// ```
    fn decode(self, data: &[u8]) -> Result<DecodeOutput, Self::Error>
    where
        Self: Sized,
    {
        self.job().decoder(Cow::Borrowed(data), &[])?.decode()
    }

    /// One-shot convenience: probe image metadata (header parse only, cheap)
    /// with default job settings.
    ///
    /// Equivalent to `self.clone().job().probe(data)`. For limits or
    /// cancellation context, go through [`job()`](DecoderConfig::job).
    ///
    /// ```rust,ignore
    /// let info = zenjpeg::JpegDecoderConfig::new().probe(&bytes)?;
    /// println!("{}x{}", info.width, info.height);
    /// ```
    fn probe(&self, data: &[u8]) -> Result<ImageInfo, Self::Error>
    where
        Self: Sized,
    {
        self.clone().job().probe(data)
    }
}

// ===========================================================================
// Decode job
// ===========================================================================

/// 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()`](DecodeJob::output_info) after setting
/// hints to learn what the decoder will actually produce.
pub trait DecodeJob<'a>: Sized {
    /// The codec-specific error type.
    type Error: core::error::Error + Send + Sync + 'static;

    /// Single-image decoder type.
    type Dec: Decode<Error = Self::Error>;

    /// Streaming decoder type.
    ///
    /// Implements [`StreamingDecode`] for batch/scanline-level decode.
    /// Set to `()` if the codec does not support streaming decode.
    type StreamDec: StreamingDecode<Error = Self::Error> + Send;

    /// 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).
    type AnimationFrameDec: AnimationFrameDecoder<Error = Self::Error> + Send + 'static;

    /// Legacy cancellation-only adapter. Prefer the complete operation pulse.
    #[deprecated(note = "use with_pulse; wrap cancellation-only controls in how_far::StopOnly")]
    fn with_stop(self, stop: StopToken) -> Self {
        self.with_pulse(how_far::SharedPulse::new(how_far::StopOnly::new(stop)))
    }

    /// Retain progress, cancellation, phase planning and sharing for this job.
    /// Codecs must not erase this to a cancellation-only token.
    fn with_pulse(self, pulse: how_far::SharedPulse) -> Self;

    /// Override resource limits for this operation.
    fn with_limits(self, limits: ResourceLimits) -> Self;

    /// Set decode security policy (controls metadata extraction, parsing strictness, etc.).
    ///
    /// # Note
    ///
    /// The default implementation is a no-op. This published setter is
    /// best-effort; static capability flags do not confirm policy enforcement.
    /// Use [`try_set_policy`](Self::try_set_policy) or
    /// [`try_with_policy`](Self::try_with_policy) for a required policy.
    #[deprecated(
        note = "may silently ignore policy; use try_with_policy or a checked operation request"
    )]
    fn with_policy(self, _policy: crate::DecodePolicy) -> Self {
        self
    }

    /// Apply every specified policy field, or reject without changing this job.
    ///
    /// The default accepts only [`DecodePolicy::none()`](crate::DecodePolicy::none)
    /// as a no-op. Codecs override this single primitive once they can enforce
    /// the requested fields; type-erased jobs delegate to the same primitive.
    /// Acceptance does not guarantee that content-dependent processing succeeds.
    fn try_set_policy(
        &mut self,
        policy: crate::DecodePolicy,
    ) -> Result<(), crate::UnsupportedOperation> {
        if policy != crate::DecodePolicy::none() {
            return Err(crate::UnsupportedOperation::DecodePolicy);
        }
        Ok(())
    }

    /// Builder form of [`try_set_policy`](Self::try_set_policy).
    ///
    /// A rejection consumes this builder. Use the mutable setter to retain it.
    fn try_with_policy(
        mut self,
        policy: crate::DecodePolicy,
    ) -> Result<Self, crate::UnsupportedOperation> {
        self.try_set_policy(policy)?;
        Ok(self)
    }

    // --- Probing (needs limits + stop context) ---

    /// 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 probe(&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()`](DecodeJob::probe).
    fn probe_full(&self, data: &[u8]) -> Result<ImageInfo, Self::Error> {
        self.probe(data)
    }

    /// Map every structural part of `data` without decoding pixels.
    ///
    /// The returned [`Inventory`](crate::inventory::Inventory) attributes every
    /// byte of the input to a part — segment, chunk, box, item extent, block,
    /// trailer or gap — and says what this decoder does with it
    /// ([`Disposition`](crate::inventory::Disposition)). Bytes the decoder never
    /// reads are listed, not skipped, so the inventory can be used to audit a
    /// file for metadata that would slip through a pipeline.
    ///
    /// Malformed or truncated input still yields an inventory: record what was
    /// understood and mark the rest
    /// [`Malformed`](crate::inventory::Disposition::Malformed). Reserve errors
    /// for cancellation and resource limits. The result must pass
    /// [`Inventory::validate`](crate::inventory::Inventory::validate).
    ///
    /// Default: an [`UnsupportedOperation::Inventory`](crate::UnsupportedOperation::Inventory)
    /// error. Codecs gate the walker behind a default-off `inventory` feature;
    /// this method stays callable when that feature is disabled. A codec that
    /// enables it also sets
    /// [`DecodeCapabilities::with_inventory`](crate::decode::DecodeCapabilities::with_inventory).
    /// The shared error envelope lets this default work without changing the
    /// published bounds on [`Self::Error`]. Implementations preserve native
    /// errors as its detail and retain location traces.
    fn inventory(
        &self,
        data: &[u8],
    ) -> Result<crate::inventory::Inventory, crate::At<crate::CodecError>> {
        let _ = data;
        Err(crate::inventory::unsupported())
    }

    // --- Decode hints (optional, decoder may ignore) ---

    /// Hint: crop to this region in source coordinates.
    ///
    /// The decoder may adjust for block alignment (JPEG MCU boundaries).
    fn with_crop_hint(self, _x: u32, _y: u32, _width: u32, _height: u32) -> Self {
        self
    }

    /// Set orientation handling strategy.
    ///
    /// See [`OrientationHint`] for the available strategies.
    /// Default: [`OrientationHint::Preserve`].
    fn with_orientation(self, _hint: OrientationHint) -> Self {
        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()`](DecodeJob::animation_frame_decoder).
    fn with_start_frame_index(self, _index: u32) -> Self {
        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.
    ///
    /// This is the 2-way toggle; `with_extract_gain_map(true)` is equivalent to
    /// [`with_gain_map_render`](Self::with_gain_map_render) with
    /// [`GainMapRender::Components`](crate::decode::GainMapRender::Components). Prefer
    /// `with_gain_map_render` when you also want the HDR-reconstruction intent.
    fn with_extract_gain_map(self, _extract: bool) -> Self {
        self
    }

    /// Select how a gain-map (HDR) image is rendered — the caller's intent for what
    /// `decode()` produces (SDR base, surfaced components, or reconstructed HDR).
    ///
    /// Default is a no-op (the codec's own default, normally
    /// [`GainMapRender::BaseOnly`](crate::decode::GainMapRender)). Codecs that
    /// support gain maps override this; check the codec's
    /// [`DecodeCapabilities`](crate::decode::DecodeCapabilities) —
    /// [`gain_map`](crate::decode::DecodeCapabilities::gain_map) for
    /// `Components`/extraction, and
    /// [`reconstructs_hdr`](crate::decode::DecodeCapabilities::reconstructs_hdr) for
    /// [`ReconstructHdr`](crate::decode::GainMapRender::ReconstructHdr). zencodec
    /// carries no HDR math: a codec that can't reconstruct surfaces `Components` (or
    /// errors), and the apply happens one layer up (`ultrahdr-core`).
    fn with_gain_map_render(self, _render: crate::GainMapRender) -> Self {
        self
    }

    /// 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(&self) -> Option<&dyn core::any::Any> {
        None
    }

    /// Mutable access to codec-specific extensions.
    fn extensions_mut(&mut self) -> Option<&mut dyn core::any::Any> {
        None
    }

    // --- Output prediction ---

    /// 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. This method receives
    /// no output preferences: `native_format` is not proof of the format selected
    /// by a subsequent negotiated decode. Do not use it to reject a requested
    /// format that differs from the native default.
    fn output_info(&self, data: &[u8]) -> Result<OutputInfo, Self::Error>;

    // --- Executor creation ---
    //
    // All executors bind `data` here so the DecodeJob is the single
    // place where input is provided. This keeps Decode/StreamingDecode/
    // AnimationFrameDecoder free of data parameters, and prepares for future
    // IO-read sources (the job can bind a reader instead of a slice).
    //
    // Consistent parameter order: data, [sink], preferred.

    /// 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 decoder(
        self,
        data: Cow<'a, [u8]>,
        preferred: &[PixelDescriptor],
    ) -> Result<Self::Dec, Self::Error>;

    /// Decode directly into a caller-owned sink (push model).
    ///
    /// Calls [`begin()`](crate::DecodeRowSink::begin) once, then pushes
    /// strips via [`provide_next_buffer()`](crate::DecodeRowSink::provide_next_buffer),
    /// then calls [`finish()`](crate::DecodeRowSink::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()`](crate::helpers::copy_decode_to_sink) as a fallback.
    fn push_decoder(
        self,
        data: Cow<'a, [u8]>,
        sink: &mut dyn crate::DecodeRowSink,
        preferred: &[PixelDescriptor],
    ) -> Result<OutputInfo, 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 streaming_decoder(
        self,
        data: Cow<'a, [u8]>,
        preferred: &[PixelDescriptor],
    ) -> Result<Self::StreamDec, 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.
    fn animation_frame_decoder(
        self,
        data: Cow<'a, [u8]>,
        preferred: &[PixelDescriptor],
    ) -> Result<Self::AnimationFrameDec, Self::Error>;

    // --- Type-erased convenience methods ---

    /// 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
    ///
    /// ```rust,ignore
    /// let decode = config.job()
    ///     .with_crop_hint(0, 0, 800, 600)
    ///     .dyn_decoder(data, &[PixelDescriptor::rgb8()])?;
    ///
    /// let output: DecodeOutput = decode.decode()?;
    /// ```
    fn dyn_decoder(
        self,
        data: Cow<'a, [u8]>,
        preferred: &[PixelDescriptor],
    ) -> Result<Box<dyn DynDecoder + 'a>, BoxedError>
    where
        Self: 'a,
    {
        let dec = self
            .decoder(data, preferred)
            .map_err(|e| Box::new(e) as BoxedError)?;
        Ok(Box::new(DecoderShim(dec)))
    }

    /// Create a type-erased full-frame animation decoder.
    ///
    /// # Example
    ///
    /// ```rust,ignore
    /// let mut dec = config.job()
    ///     .dyn_animation_frame_decoder(data, &[])?;
    ///
    /// while let Some(frame) = dec.render_next_frame_owned(None)? {
    ///     // process frame
    /// }
    /// ```
    fn dyn_animation_frame_decoder(
        self,
        data: Cow<'a, [u8]>,
        preferred: &[PixelDescriptor],
    ) -> Result<Box<dyn DynAnimationFrameDecoder>, BoxedError>
    where
        Self: 'a,
        Self::AnimationFrameDec: Send,
    {
        let dec = self
            .animation_frame_decoder(data, preferred)
            .map_err(|e| Box::new(e) as BoxedError)?;
        Ok(Box::new(AnimationFrameDecoderShim(dec)))
    }

    /// Create a type-erased streaming decoder.
    ///
    /// # Example
    ///
    /// ```rust,ignore
    /// let mut dec = config.job()
    ///     .dyn_streaming_decoder(data, &[])?;
    ///
    /// while let Some((y, strip)) = dec.next_batch()? {
    ///     // process strip
    /// }
    /// ```
    fn dyn_streaming_decoder(
        self,
        data: Cow<'a, [u8]>,
        preferred: &[PixelDescriptor],
    ) -> Result<Box<dyn DynStreamingDecoder + 'a>, BoxedError>
    where
        Self: 'a,
        Self::StreamDec: Send,
    {
        let dec = self
            .streaming_decoder(data, preferred)
            .map_err(|e| Box::new(e) as BoxedError)?;
        Ok(Box::new(StreamingDecoderShim(dec)))
    }

    /// Create a type-erased incremental (Sans-I/O) decoder.
    ///
    /// Codecs that support incremental decoding override this method.
    /// Default implementation returns [`UnsupportedOperation::IncrementalDecode`](crate::UnsupportedOperation::IncrementalDecode).
    ///
    /// The returned decoder is built with
    /// [`erase_incremental`](crate::decode::erase_incremental), so the
    /// termination rules hold whatever the codec does. Drivers for files,
    /// streams and async sources are in `zencodec-io`; this loop is the
    /// whole protocol, over bytes already in memory:
    ///
    /// ```
    /// use zencodec::decode::{BoxedError, DecodeJob, DecodeRowSink, Event, Input, InputRequest};
    ///
    /// fn decode_in_memory<'a, J: DecodeJob<'a>>(
    ///     job: J,
    ///     data: &[u8],
    ///     sink: &mut dyn DecodeRowSink,
    /// ) -> Result<(), BoxedError> {
    ///     let mut dec = job.dyn_incremental_decoder(&[])?;
    ///     let total = data.len() as u64;
    ///     let mut at = 0usize;
    ///     loop {
    ///         let input = Input::new(at as u64, &data[at..]).with_total_len(total);
    ///         let p = dec.step(input, sink, None)?;
    ///         at += p.consumed;
    ///         match p.event {
    ///             // Satisfy any one request; the length is always known here.
    ///             Event::Need => match dec.requested()[0] {
    ///                 InputRequest::AtLeast { offset, .. } => at = offset as usize,
    ///                 InputRequest::Range(r) => at = r.offset as usize,
    ///                 _ => {}
    ///             },
    ///             Event::Done(_) => return Ok(()),
    ///             _ => {} // rows, metadata, or an event added later
    ///         }
    ///         at = at.min(data.len());
    ///     }
    /// }
    /// ```
    fn dyn_incremental_decoder(
        self,
        preferred: &[PixelDescriptor],
    ) -> Result<Box<super::incremental::DynIncrementalDecoder>, BoxedError> {
        let _ = preferred;
        Err(Box::new(
            crate::capabilities::UnsupportedOperation::IncrementalDecode,
        ))
    }

    /// Start a decoder that must suspend before interpretation-dependent work.
    ///
    /// The default refuses; ordinary incremental support does not establish this
    /// contract. Implementations preserve this job's configuration and return an
    /// [`erase_controlled`](crate::decode::erase_controlled) session. `storage`
    /// admits participating owned buffers; it is not a native-workspace bound.
    /// Preferred descriptors remain preferences. A required output is checked
    /// before adoption by [`DecodeRequest`](crate::operation::DecodeRequest).
    fn dyn_controlled_decoder(
        self,
        preferred: &[PixelDescriptor],
        storage: crate::storage::StorageBudget,
    ) -> Result<Box<super::control::DynControlledDecoder>, BoxedError> {
        let _ = (preferred, storage);
        Err(Box::new(super::control::ControlError::NotControlled))
    }

    /// Decode from a random-access source into a caller-owned sink (pull
    /// model).
    ///
    /// The codec reads exactly the byte ranges it needs from `source`, in
    /// straight-line code, and writes rows into `sink` exactly as
    /// [`push_decoder`](DecodeJob::push_decoder) does. Crop and region
    /// intent stay bound on the job; the sink's coordinate space is the
    /// output image. Codecs whose core reads a seekable input natively
    /// (directory and tile formats) override this and set
    /// [`DecodeCapabilities::with_seekable`](crate::decode::DecodeCapabilities::with_seekable);
    /// drivers with a sequential or async source manufacture one with the
    /// adapters in `zencodec-io`.
    ///
    /// Default implementation returns [`UnsupportedOperation::SeekableDecode`](crate::UnsupportedOperation::SeekableDecode).
    fn push_decoder_from_source(
        self,
        source: &mut dyn crate::source::DynReadAt,
        sink: &mut dyn crate::DecodeRowSink,
        preferred: &[PixelDescriptor],
    ) -> Result<OutputInfo, BoxedError> {
        let _ = (source, sink, preferred);
        Err(Box::new(
            crate::capabilities::UnsupportedOperation::SeekableDecode,
        ))
    }
}