zenjxl_decoder/api/mod.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// #![warn(missing_docs)]
7
8mod color;
9mod convenience;
10mod data_types;
11mod decoder;
12mod inner;
13mod input;
14#[cfg(feature = "cms")]
15mod moxcms_wrapper;
16mod options;
17mod signature;
18mod xyb_constants;
19
20pub use crate::image::JxlOutputBuffer;
21pub use color::*;
22pub use convenience::{JxlImage, JxlImageInfo, decode, decode_with, read_header, read_header_with};
23#[cfg(feature = "jpeg")]
24pub use convenience::{reconstruct_jpeg, reconstruct_jpeg_with};
25pub use data_types::*;
26pub use decoder::*;
27pub use enough::{Stop, Unstoppable};
28pub use inner::*;
29pub use input::*;
30#[cfg(feature = "cms")]
31pub use moxcms_wrapper::*;
32pub use options::*;
33pub use signature::*;
34
35// Error types
36pub use crate::error::{Error, Result};
37
38// Image types used by CLI/fuzz for output buffer construction
39pub use crate::image::{
40 DataTypeTag, Image, ImageDataType, ImageRect, ImageRectMut, OwnedRawImage, RawImageRect,
41 RawImageRectMut, Rect,
42};
43
44// Header types that appear in public API structs
45pub use crate::headers::color_encoding::RenderingIntent;
46pub use crate::headers::extra_channels::ExtraChannel;
47pub use crate::headers::image_metadata::Orientation;
48
49// Container box types
50pub use crate::container::gain_map::GainMapBundle;
51
52// Point type used in Error variants
53pub use crate::features::spline::Point;
54
55// Profiling (feature-gated, used by CLI)
56#[cfg(feature = "profiling")]
57pub use crate::util::profiling::print_profile_report;
58
59/// This type represents the return value of a function that reads input from a bitstream. The
60/// variant `Complete` indicates that the operation was completed successfully, and its return
61/// value is available. The variant `NeedsMoreInput` indicates that more input is needed, and the
62/// function should be called again. This variant comes with a `size_hint`, representing an
63/// estimate of the number of additional bytes needed, and a `fallback`, representing additional
64/// information that might be needed to call the function again (i.e. because it takes a decoder
65/// object by value).
66#[derive(Debug, PartialEq)]
67pub enum ProcessingResult<T, U> {
68 Complete { result: T },
69 NeedsMoreInput { size_hint: usize, fallback: U },
70}
71
72impl<T> ProcessingResult<T, ()> {
73 fn new(
74 result: Result<T, crate::error::Error>,
75 ) -> Result<ProcessingResult<T, ()>, crate::error::Error> {
76 match result {
77 Ok(v) => Ok(ProcessingResult::Complete { result: v }),
78 Err(crate::error::Error::OutOfBounds(v)) => Ok(ProcessingResult::NeedsMoreInput {
79 size_hint: v,
80 fallback: (),
81 }),
82 Err(e) => Err(e),
83 }
84 }
85}
86
87#[derive(Clone)]
88#[non_exhaustive]
89pub struct ToneMapping {
90 pub intensity_target: f32,
91 pub min_nits: f32,
92 pub relative_to_max_display: bool,
93 pub linear_below: f32,
94}
95
96#[derive(Clone)]
97#[non_exhaustive]
98pub struct JxlBasicInfo {
99 /// Dimensions of the pixel data the decoder will emit, in the order the
100 /// output buffer must be laid out (`(width, height)`).
101 ///
102 /// This depends on [`JxlDecoderOptions::adjust_orientation`]:
103 /// - When orientation is adjusted (the default, "Correct"), the stored
104 /// orientation is baked into the output, so this is the *display* size
105 /// (width/height are swapped relative to [`Self::coded_size`] for
106 /// transposing orientations).
107 /// - When orientation adjustment is disabled ("Preserve"), pixels are
108 /// emitted in their stored orientation, so this equals
109 /// [`Self::coded_size`].
110 ///
111 /// Allocate output buffers against this size.
112 pub size: (usize, usize),
113 /// The stored (coded) dimensions of the image as written in the codestream,
114 /// `(width, height)`, *before* any orientation is applied. Unaffected by
115 /// [`JxlDecoderOptions::adjust_orientation`]. For transposing orientations
116 /// this differs from the display size; see [`Self::size`].
117 pub coded_size: (usize, usize),
118 pub bit_depth: JxlBitDepth,
119 /// Orientation of the pixels the decoder emits, i.e. the residual transform
120 /// a caller must still apply to obtain an upright image.
121 ///
122 /// This depends on [`JxlDecoderOptions::adjust_orientation`]:
123 /// - When orientation is adjusted (the default, "Correct"), the stored
124 /// orientation has already been baked into the output pixels, so this is
125 /// [`Orientation::Identity`].
126 /// - When orientation adjustment is disabled ("Preserve"), this is the
127 /// image's stored orientation (equal to [`Self::intrinsic_orientation`]),
128 /// which the caller should bake into the [`Self::coded_size`] pixels to
129 /// display them upright.
130 pub orientation: Orientation,
131 /// The image's intrinsic (stored) EXIF/container orientation as written in
132 /// the codestream, regardless of [`JxlDecoderOptions::adjust_orientation`].
133 ///
134 /// Use this to re-tag re-encoded output or to decide how to bake the stored
135 /// orientation. In "Correct" mode the emitted pixels are already upright
136 /// even though this reports a non-Identity value; in "Preserve" mode this
137 /// equals [`Self::orientation`].
138 pub intrinsic_orientation: Orientation,
139 pub extra_channels: Vec<JxlExtraChannel>,
140 pub animation: Option<JxlAnimation>,
141 pub uses_original_profile: bool,
142 pub tone_mapping: ToneMapping,
143 pub preview_size: Option<(usize, usize)>,
144 /// Intrinsic display size, if different from coded size.
145 ///
146 /// When present, the image should be rendered at this `(width, height)`
147 /// rather than the coded `size`. Used for resolution-independence
148 /// (e.g. a 4000×3000 image meant to display at 2000×1500).
149 pub intrinsic_size: Option<(usize, usize)>,
150}