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