jpegli/lib.rs
1#![cfg_attr(
2 not(any(feature = "unsafe_simd", feature = "archmage-simd")),
3 forbid(unsafe_code)
4)]
5#![cfg_attr(not(feature = "std"), no_std)]
6
7//! # jpegli
8//!
9//! Pure Rust JPEG encoder with perceptual optimizations.
10//!
11//! jpegli provides enhanced compression quality compared to standard JPEG
12//! through adaptive quantization, optional XYB color space, and other
13//! perceptual optimizations.
14//!
15//! ## Quick Start
16//!
17//! ```rust,ignore
18//! use jpegli::encoder::{EncoderConfig, ChromaSubsampling, PixelLayout, Unstoppable};
19//!
20//! // Create reusable config (quality + color mode in constructor)
21//! let config = EncoderConfig::ycbcr(85, ChromaSubsampling::Quarter)
22//! .progressive(true);
23//!
24//! // Encode from raw bytes
25//! let mut enc = config.encode_from_bytes(1920, 1080, PixelLayout::Rgb8Srgb)?;
26//! enc.push_packed(&rgb_bytes, Unstoppable)?;
27//! let jpeg = enc.finish()?;
28//! ```
29//!
30//! ## Encoder API
31//!
32//! All encoder types are in [`encoder`]:
33//!
34//! ```rust,ignore
35//! use jpegli::encoder::{
36//! // Core types
37//! EncoderConfig, // Builder for encoder configuration
38//! BytesEncoder, // Encoder for raw byte buffers
39//! RgbEncoder, // Encoder for rgb crate types
40//! YCbCrPlanarEncoder, // Encoder for planar YCbCr
41//!
42//! // Configuration
43//! Quality, // Quality settings (ApproxJpegli, ApproxMozjpeg, etc.)
44//! PixelLayout, // Pixel format for raw bytes
45//! ChromaSubsampling, // 4:4:4, 4:2:0, 4:2:2, 4:4:0
46//! ColorMode, // YCbCr, XYB, Grayscale
47//! DownsamplingMethod, // Box, GammaAware, GammaAwareIterative
48//!
49//! // Cancellation
50//! Stop, // Trait for cancellation tokens
51//! Unstoppable, // Use when no cancellation needed
52//!
53//! // Results
54//! Error, Result, // Error handling
55//! };
56//! ```
57//!
58//! ### Three Entry Points
59//!
60//! | Method | Input Type | Use Case |
61//! |--------|------------|----------|
62//! | [`encoder::EncoderConfig::encode_from_bytes`] | `&[u8]` | Raw byte buffers |
63//! | [`encoder::EncoderConfig::encode_from_rgb`] | `rgb` crate types | Type-safe pixels |
64//! | [`encoder::EncoderConfig::encode_from_ycbcr_planar`] | [`YCbCrPlanes`](encoder::YCbCrPlanes) | Video pipelines |
65//!
66//! ### Configuration Options
67//!
68//! ```rust,ignore
69//! // YCbCr mode (standard JPEG - most compatible)
70//! let config = EncoderConfig::ycbcr(85, ChromaSubsampling::Quarter)
71//! .progressive(true) // Progressive JPEG (~3% smaller)
72//! .sharp_yuv(true) // Better color edges (~3x slower)
73//! .icc_profile(bytes); // Attach ICC profile
74//!
75//! // XYB mode (perceptual color space - better quality)
76//! let config = EncoderConfig::xyb(85, XybSubsampling::BQuarter)
77//! .progressive(true);
78//!
79//! // Grayscale mode
80//! let config = EncoderConfig::grayscale(85);
81//!
82//! // Quality can also use enum variants:
83//! let config = EncoderConfig::ycbcr(Quality::ApproxSsim2(90.0), ChromaSubsampling::None);
84//! let config = EncoderConfig::ycbcr(Quality::ApproxButteraugli(1.0), ChromaSubsampling::Quarter);
85//! ```
86//!
87//! ## Decoder API
88//!
89//! The decoder is in prerelease. Enable with `features = ["decoder"]`.
90//!
91//! ```rust,ignore
92//! #[cfg(feature = "decoder")]
93//! use jpegli::decoder::{Decoder, DecodedImage};
94//!
95//! let image = Decoder::new().decode(&jpeg_data)?;
96//! let pixels: &[u8] = image.pixels();
97//! ```
98//!
99//! ## Feature Flags
100//!
101//! | Feature | Default | Description |
102//! |---------|---------|-------------|
103//! | `decoder` | No | Enable decoder API (prerelease) |
104//! | `parallel` | No | Multi-threaded encoding via rayon |
105//! | `cms-lcms2` | Yes | Color management via lcms2 |
106//! | `cms-moxcms` | No | Pure Rust color management |
107//! | `unsafe_simd` | No | Raw AVX2/SSE intrinsics (~10-20% faster) |
108//!
109//! ## Capabilities
110//!
111//! - **Baseline JPEG**: Standard 8-bit JPEG encoding
112//! - **Progressive JPEG**: Multi-scan encoding (~3% smaller files)
113//! - **XYB Color Space**: Perceptually optimized for better quality
114//! - **Adaptive Quantization**: Content-aware bit allocation
115//! - **16-bit / f32 Input**: High bit-depth source support
116//! - **Streaming API**: Memory-efficient row-by-row encoding
117//! - **Parallel Encoding**: Multi-threaded for large images
118
119// Lint configuration is in workspace Cargo.toml [workspace.lints.clippy]
120#![allow(missing_docs)]
121#![allow(clippy::module_name_repetitions)]
122
123extern crate alloc;
124
125// Error tracing with location tracking
126whereat::define_at_crate_info!(path = "jpegli-rs/");
127
128// ============================================================================
129// Public API Modules
130// ============================================================================
131
132/// JPEG encoder - public API.
133///
134/// Contains: `EncoderConfig`, `BytesEncoder`, `RgbEncoder`, `Error`, `Result`, etc.
135pub mod encoder;
136
137/// Resource estimation heuristics for encoding and decoding.
138///
139/// Provides min/typical/max estimates for peak memory and time.
140pub mod heuristics;
141
142/// JPEG decoder - public API.
143///
144/// Contains: `Decoder`, `DecodedImage`, `Error`, `Result`, etc.
145///
146/// **Note:** The decoder is in prerelease and the API will have breaking changes.
147/// Enable with the `decoder` feature flag.
148#[cfg(feature = "decoder")]
149pub mod decoder;
150
151/// UltraHDR support - HDR gain map encoding and decoding.
152///
153/// Provides integration with `ultrahdr-core` for:
154/// - HDR to SDR tonemapping
155/// - Gain map computation and application
156/// - XMP metadata generation and parsing
157/// - Adaptive tonemapper for re-encoding
158///
159/// Enable with the `ultrahdr` feature flag.
160#[cfg(feature = "ultrahdr")]
161pub mod ultrahdr;
162
163// ============================================================================
164// Internal Implementation Modules
165// ============================================================================
166
167// Internal encoder implementation (exposed via test-utils for benchmarks)
168#[cfg(feature = "test-utils")]
169pub mod encode;
170#[cfg(not(feature = "test-utils"))]
171pub(crate) mod encode;
172
173// Internal decoder implementation
174#[cfg(all(feature = "decoder", feature = "test-utils"))]
175pub mod decode;
176#[cfg(all(feature = "decoder", not(feature = "test-utils")))]
177pub(crate) mod decode;
178
179// Internal shared error type (encoder/decoder have their own public errors)
180pub(crate) mod error;
181
182// Internal modules (exposed via test-utils for debugging tools and benchmarks)
183#[cfg(feature = "test-utils")]
184pub mod color;
185#[cfg(not(feature = "test-utils"))]
186pub(crate) mod color;
187
188pub(crate) mod encode_simd;
189
190#[cfg(feature = "test-utils")]
191pub mod entropy;
192#[cfg(not(feature = "test-utils"))]
193pub(crate) mod entropy;
194
195#[cfg(feature = "test-utils")]
196pub mod foundation;
197#[cfg(not(feature = "test-utils"))]
198pub(crate) mod foundation;
199
200#[cfg(feature = "test-utils")]
201pub mod huffman;
202#[cfg(not(feature = "test-utils"))]
203pub(crate) mod huffman;
204
205// Make quant accessible for benchmarks when test-utils enabled
206#[cfg(feature = "test-utils")]
207#[doc(hidden)]
208pub mod quant;
209#[cfg(not(feature = "test-utils"))]
210pub(crate) mod quant;
211
212#[cfg(feature = "test-utils")]
213pub mod types;
214#[cfg(not(feature = "test-utils"))]
215pub(crate) mod types;
216
217// Test utilities - only compiled when feature enabled (requires std)
218#[cfg(feature = "test-utils")]
219pub mod test_utils;
220
221// Hybrid quantization (jpegli AQ + mozjpeg trellis)
222#[cfg(feature = "experimental-hybrid-trellis")]
223pub mod hybrid;
224
225// Profiling instrumentation (zero-cost when disabled)
226pub mod profile;