zenjxl_decoder/lib.rs
1// Copyright (c) the JPEG XL Project Authors. All rights reserved.
2//
3// Use of this source code is governed by a BSD-style
4// license that can be found in the LICENSE file.
5
6//! A JPEG XL decoder in safe Rust.
7//!
8//! `zenjxl-decoder` is a pure-Rust decoder for the JPEG XL bitstream format
9//! (ISO/IEC 18181). It is a fork of the upstream
10//! [`libjxl/jxl-rs`](https://github.com/libjxl/jxl-rs) reference decoder,
11//! which in turn tracks the C++ [`libjxl`](https://github.com/libjxl/libjxl)
12//! implementation. Upstream remains the source of truth for codec behaviour;
13//! this fork adds resource limits, cooperative cancellation, parallel decode,
14//! and a handful of bug fixes and hardening changes on top.
15//!
16//! # Crate layout
17//!
18//! Most users only need the [`api`] module:
19//!
20//! ```no_run
21//! use zenjxl_decoder::api::decode;
22//!
23//! let bytes = std::fs::read("image.jxl").unwrap();
24//! let image = decode(&bytes).unwrap();
25//! ```
26//!
27//! Pass [`api::JxlDecoderOptions`] to [`api::decode_with`] to configure
28//! resource limits, cancellation, or colour conversion.
29//!
30//! # SIMD
31//!
32//! Multi-architecture SIMD (SSE4.2, AVX2, AVX-512, NEON, WASM128) lives in
33//! the companion [`zenjxl-decoder-simd`](https://crates.io/crates/zenjxl-decoder-simd)
34//! crate and is enabled via the `all-simd` feature (or per-ISA features such
35//! as `avx`, `neon`, `wasm128`). Dispatch is runtime, via
36//! [`archmage`](https://crates.io/crates/archmage).
37//!
38//! # Safety
39//!
40//! The main `jxl` crate is `#![forbid(unsafe_code)]` by default. Enabling the
41//! `allow-unsafe` feature opts into a small set of `unsafe` fast paths guarded
42//! by safe fallbacks.
43//!
44//! # Features
45//!
46//! - `threads` -- rayon-based parallel group decode and render.
47//! - `cms` -- [`moxcms`](https://crates.io/crates/moxcms) ICC profile transforms
48//! (required for CMYK input).
49//! - `jpeg` -- lossless JPEG reconstruction from JXL containers.
50//! - `all-simd` / `sse42` / `avx` / `avx512` / `neon` / `wasm128` -- SIMD backends.
51//! - `allow-unsafe` -- opt in to `unsafe` fast paths.
52//!
53//! # License
54//!
55//! BSD-3-Clause, matching upstream [`libjxl/jxl-rs`](https://github.com/libjxl/jxl-rs).
56
57#![cfg_attr(not(feature = "allow-unsafe"), forbid(unsafe_code))]
58#![cfg_attr(feature = "allow-unsafe", deny(unsafe_code))]
59
60pub mod api;
61pub use api::{decode, decode_with, read_header, read_header_with};
62pub(crate) mod bit_reader;
63pub(crate) mod color;
64pub(crate) mod container;
65pub(crate) mod entropy_coding;
66pub(crate) mod error;
67pub(crate) mod features;
68pub(crate) mod frame;
69pub(crate) mod headers;
70pub(crate) mod icc;
71pub(crate) mod image;
72pub(crate) mod render;
73pub(crate) mod transforms;
74pub(crate) mod util;
75
76#[cfg(feature = "jpeg")]
77pub(crate) mod jpeg;
78
79#[cfg(test)]
80mod tests;
81
82// TODO: Move these to a more appropriate location.
83const GROUP_DIM: usize = 256;
84const BLOCK_DIM: usize = 8;
85const BLOCK_SIZE: usize = BLOCK_DIM * BLOCK_DIM;
86#[allow(clippy::excessive_precision)]
87const MIN_SIGMA: f32 = -3.90524291751269967465540850526868;