edgefirst_codec/lib.rs
1// SPDX-FileCopyrightText: Copyright 2026 Au-Zone Technologies
2// SPDX-License-Identifier: Apache-2.0
3
4//! Image codec for decoding JPEG/PNG into pre-allocated EdgeFirst tensors.
5//!
6//! This crate provides the [`ImageDecoder`] struct and [`ImageLoad`] extension
7//! trait for decoding image files directly into existing tensor buffers —
8//! including DMA-BUF tensors with GPU-aligned pitch padding. The core design
9//! goal is **allocate once, decode many**: users create a tensor at the maximum
10//! expected image size during program initialisation, then call
11//! [`ImageLoad::load_image`] in the hot loop with zero per-frame allocations.
12//!
13//! # Quick Start
14//!
15//! ```rust,no_run
16//! use edgefirst_codec::{ImageDecoder, ImageLoad, DecodeOptions};
17//! use edgefirst_tensor::{Tensor, TensorTrait, TensorMemory, PixelFormat};
18//!
19//! // Allocate once (at init)
20//! let mut tensor = Tensor::<u8>::image(1920, 1080, PixelFormat::Rgb, Some(TensorMemory::Mem))
21//! .expect("allocation");
22//! let mut decoder = ImageDecoder::new();
23//!
24//! // Decode many (in hot loop)
25//! let jpeg_bytes = std::fs::read("frame.jpg").unwrap();
26//! let info = tensor.load_image(&mut decoder, &jpeg_bytes, &DecodeOptions::default())
27//! .expect("decode");
28//! assert!(info.width <= 1920);
29//! assert!(info.height <= 1080);
30//! ```
31//!
32//! # Performance
33//!
34//! For best performance, allocate tensors via
35//! [`ImageProcessor::create_image()`](https://docs.rs/edgefirst-image/latest/edgefirst_image/struct.ImageProcessor.html#method.create_image)
36//! which selects the optimal memory backend (DMA → PBO → Mem) with
37//! GPU-aligned pitch. Free-standing tensors work but cannot use PBO
38//! and may not have aligned pitch.
39//!
40//! # Strided Buffers
41//!
42//! The decoder respects `effective_row_stride()` on the destination tensor.
43//! When a DMA tensor has GPU-aligned pitch padding, decoded pixel rows are
44//! written at the correct stride offsets — no intermediate contiguous buffer
45//! is exposed to the caller.
46
47mod decoder;
48mod error;
49mod exif;
50mod jpeg;
51mod options;
52mod pixel;
53mod png;
54mod traits;
55
56pub use decoder::{peek_info, ImageDecoder};
57pub use error::{CodecError, UnsupportedFeature};
58pub use options::{DecodeOptions, ImageInfo};
59pub use pixel::ImagePixel;
60pub use traits::ImageLoad;
61
62/// Result type for codec operations.
63pub type Result<T> = std::result::Result<T, CodecError>;