Struct ImageDecoder 

pub struct ImageDecoder { /* private fields */ }

Reusable image decoder with internal scratch buffers.

Create one ImageDecoder at program initialisation and pass it to ImageLoad::load_image in the hot loop. The scratch buffers grow to the high-water mark and are reused across calls — no per-frame allocations after the first few frames.

By default the decoder produces the source’s native format and configures the destination tensor’s dimensions + pixel format accordingly (JPEG → Nv12/Nv16/Nv24/Grey, PNG → Rgb/Rgba/Grey). set_output_format opts a JPEG decode into a fused Rgb or Nv12 output, where the colour conversion or chroma downsample happens at the MCU write stage instead of in a second pass. The decoder never rotates or resizes; use ImageProcessor::convert() for that.

Example

use edgefirst_codec::{ImageDecoder, ImageLoad};
use edgefirst_tensor::{CpuAccess, Tensor, TensorTrait, TensorMemory, PixelFormat};

let mut decoder = ImageDecoder::new();
// Allocate a buffer large enough for the biggest expected image. The
// decoder CPU-writes the pixels, so declare `CpuAccess::Write`.
let mut tensor = Tensor::<u8>::image(1920, 1080, PixelFormat::Nv12, Some(TensorMemory::Mem),
                                      CpuAccess::Write)
    .expect("alloc");

for _ in 0..100 {
    let frame = std::fs::read("frame.jpg").unwrap();
    let _info = tensor.load_image(&mut decoder, &frame);
}

Implementations

impl ImageDecoder

pub fn new() -> Self

Create a new decoder with empty scratch buffers.

pub fn set_output_format(&mut self, format: Option<PixelFormat>)

Request a fused decode output format instead of the source’s native format (JPEG only; PNG is unaffected).

This is a pure CPU, single-pass path inside the software JPEG decoder — colour conversion / chroma downsample happens at the MCU write stage. It is not a GPU hybrid or nvJPEG path; V4L2/nvJPEG are bypassed whenever the resolved output differs from native.

• Some(Rgb): 4:4:4 colour JPEGs decode straight to interleaved RGB (no chroma resampling); native 4:2:0 colour JPEGs also decode straight to RGB, with a 2×2 nearest-neighbour (box) chroma upsample fused into the write — not libjpeg’s fancy/triangle upsampling, a deliberate speed tradeoff (see BENCHMARKS.md). Other sources (4:2:2, greyscale, non-standard subsamplings) cannot honour an RGB request: the decode returns CodecError::UnsupportedFormat rather than silently substituting the native semi-planar format. Check the source’s subsampling first (e.g. via crate::peek_info) if it isn’t known to be 4:4:4 or 4:2:0.
• Some(Nv12): colour JPEGs decode to NV12, downsampling chroma at the write stage (2×2 average for 4:4:4, vertical for 4:2:2).
• None (default): native format (Nv12/Nv16/Nv24/Grey).

Callers still run ImageProcessor::convert() on the result for model-input preprocessing (letterbox, resize, EXIF orientation). With fused RGB that convert step is typically a pure resize.

pub fn set_dct_method(&mut self, method: DctMethod)

Select the software JPEG IDCT kernel class — see DctMethod. Off (Accurate) by default; EDGEFIRST_CODEC_DCT=fast in the environment flips a new decoder’s default for A/B runs.

pub fn set_chroma_upsample(&mut self, mode: ChromaUpsample)

Select the chroma upsampling filter for a fused native-4:2:0 Rgb decode — see ChromaUpsample. ChromaUpsample::Box (the default) is the only filter implemented today; this setter exists so a future filter can be selected without changing set_output_format’s signature. Has no effect on 4:4:4 sources (no chroma resampling occurs there) or when the output format isn’t Rgb.

pub fn decode_into<T: ImagePixel>( &mut self, data: &[u8], dst: &mut Tensor<T>, ) -> Result<ImageInfo>

Decode image data into a typed tensor, configuring its dimensions and pixel format to the decoded output format — the source’s native format unless set_output_format selected a fused one.

Detects the image format (JPEG or PNG) from magic bytes.

Errors

• CodecError::InsufficientCapacity if the image is larger than the tensor’s allocation
• CodecError::UnsupportedDtype if T is not valid for the output format (JPEG NV12/NV16/NV24/RGB/GREY require u8)
• CodecError::InvalidData if the data is not a valid JPEG or PNG, including a JPEG whose entropy-coded scan is truncated

pub fn decode_into_dyn( &mut self, data: &[u8], dst: &mut TensorDyn, ) -> Result<ImageInfo>

Decode image data into a type-erased tensor.

pub fn decode_from_reader<T: ImagePixel, R: Read>( &mut self, reader: R, dst: &mut Tensor<T>, ) -> Result<ImageInfo>

Read all bytes from a Read source into the internal input buffer, then decode. The input buffer is reused across calls.

pub fn decode_from_reader_dyn<R: Read>( &mut self, reader: R, dst: &mut TensorDyn, ) -> Result<ImageInfo>

Read all bytes from a Read source, then decode into a type-erased tensor.

Trait Implementations

impl Default for ImageDecoder

fn default() -> Self

Returns the “default value” for a type.