Crate edgefirst_codec 

Image codec for decoding JPEG/PNG into pre-allocated EdgeFirst tensors.

This crate provides the ImageDecoder struct and ImageLoad extension trait for decoding image files directly into existing tensor buffers — including DMA-BUF tensors with GPU-aligned pitch padding. The core design goal is allocate once, decode many: users create a tensor at the maximum expected image size during program initialisation, then call ImageLoad::load_image in the hot loop with zero per-frame allocations.

Quick Start

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

// Allocate once (at init), sized for the largest expected image. The
// decoder CPU-writes the pixels: declare `CpuAccess::Write`.
let mut tensor = Tensor::<u8>::image(1920, 1080, PixelFormat::Nv12, Some(TensorMemory::Mem),
                                      CpuAccess::Write)
    .expect("allocation");
let mut decoder = ImageDecoder::new();

// Decode many (in hot loop). The decoder sets the tensor's dimensions and
// native format (JPEG → Nv12/Grey); call `convert()` for RGB.
let jpeg_bytes = std::fs::read("frame.jpg").unwrap();
let info = tensor.load_image(&mut decoder, &jpeg_bytes).expect("decode");
assert!(info.width <= 1920);
assert!(info.height <= 1080);

Performance

For best performance, allocate tensors via ImageProcessor::create_image() which selects the optimal memory backend (DMA → PBO → Mem) with GPU-aligned pitch. Free-standing tensors work but cannot use PBO and may not have aligned pitch.

Strided Buffers

The decoder respects effective_row_stride() on the destination tensor. When a DMA tensor has GPU-aligned pitch padding, decoded pixel rows are written at the correct stride offsets — no intermediate contiguous buffer is exposed to the caller.

Structs

ImageDecoder

Reusable image decoder with internal scratch buffers.

ImageInfo

Metadata returned after a successful image decode.

Enums

CodecError

Errors that can occur during image decoding.

DctMethod

IDCT accuracy/speed selection for the software JPEG decoder.

UnsupportedFeature

A specific image-format feature that the codec does not implement.

Traits

ImageLoad

Extension trait for loading images into pre-allocated tensors.

ImagePixel

Marker trait for pixel element types supported by image decoding.

Functions

nvjpeg_available

Returns true when the nvJPEG GPU JPEG decoder is available at runtime — Linux with CUDA + libnvjpeg loaded and opted in via EDGEFIRST_ENABLE_NVJPEG (off by default, so it never silently contends with CUDA inference). When true the codec prefers it over the V4L2/CPU backends for CUDA-backed destinations. Always false on other platforms or when the nvjpeg feature is disabled. Useful for benchmarks and consumers that branch on backend availability.

peek_info

Parse image headers and return the native dimensions, format, and EXIF orientation without decoding pixels.

v4l2_available

Returns true when a V4L2 memory-to-memory JPEG decoder (e.g. the i.MX mxc-jpeg block) is present and not opted out via EDGEFIRST_DISABLE_V4L2. Opens and drops the device once; the decode path re-probes lazily and keeps its own context. Always false on other platforms or when the v4l2 feature is disabled. Useful for benchmarks and consumers that must fail fast instead of silently falling back to the CPU decoder.

Type Aliases

Result

Result type for codec operations.