zencodec/
lib.rs

1//! Shared traits and types for zen* image codecs.
2//!
3//! This crate defines the common API surface that all zen* codecs implement.
4//!
5//! # Module organization
6//!
7//! - [`encode`] — encoder traits, dyn dispatch, output types
8//! - [`decode`] — decoder traits, streaming/animation decode, dyn dispatch, output types
9//! - Root — shared types used by both encode and decode paths
10//!
11//! # Shared types (root)
12//!
13//! - [`ImageFormat`] — format detection from magic bytes
14//! - [`ImageInfo`] / [`Metadata`] / [`Orientation`] / [`OrientationHint`] — image metadata
15//! - [`ResourceLimits`] / [`ThreadingPolicy`] — resource limit and threading configuration
16//! - [`UnsupportedOperation`] / [`CodecErrorExt`] — standard unsupported operation reporting and error chain inspection
17//!
18//! # Re-exported crates
19//!
20//! The [`enough`] crate is re-exported for cooperative cancellation
21//! (`enough::Stop`).
22//!
23//! ```rust,ignore
24//! use enough::Stop;
25//! ```
26//!
27//! Individual codecs (zenjpeg, zenwebp, zengif, zenavif) implement the
28//! [`encode`] and [`decode`] traits on their own config types.
29//! Format-specific methods live on the concrete types, not on the traits.
30//!
31//! `zencodecs` provides multi-format dispatch and convenience entry points.
32
33#![no_std]
34#![forbid(unsafe_code)]
35
36extern crate alloc;
37
38whereat::define_at_crate_info!();
39
40mod capabilities;
41mod cost;
42mod detect;
43mod error;
44mod extensions;
45mod format;
46/// Cross-codec gain map types (ISO 21496-1).
47pub mod gainmap;
48/// Codec implementation helpers (not consumer API).
49pub mod helpers;
50mod info;
51mod limits;
52mod metadata;
53mod negotiate;
54mod orientation;
55mod output;
56mod policy;
57mod sink;
58mod traits;
59
60// =========================================================================
61// Public root: shared types used by both encode and decode
62// =========================================================================
63
64pub use extensions::Extensions;
65pub use format::{ImageFormat, ImageFormatDefinition, ImageFormatRegistry};
66pub use gainmap::{
67    GainMapChannel, GainMapDirection, GainMapInfo, GainMapParams, GainMapPresence, Iso21496Format,
68};
69pub use info::{
70    Cicp, ContentLightLevel, ImageInfo, ImageSequence, MasteringDisplay, Resolution,
71    ResolutionUnit, SourceColor, Supplements,
72};
73pub use limits::{LimitExceeded, ResourceLimits, ThreadingPolicy};
74pub use metadata::Metadata;
75pub use orientation::{Orientation, OrientationHint};
76pub use output::{AnimationFrame, OwnedAnimationFrame};
77
78pub use capabilities::UnsupportedOperation;
79pub use detect::SourceEncodingDetails;
80pub use error::{CodecErrorExt, find_cause};
81pub use traits::Unsupported;
82
83// =========================================================================
84// Crate-level re-exports (qualified access, not individual types)
85// =========================================================================
86//
87/// Owned, clonable, type-erased stop token.
88///
89/// Re-exported from [`almost_enough::StopToken`]. Wraps any `Stop` in an
90/// enum that avoids vtable dispatch for `Stopper`/`SyncStopper`/`Unstoppable`,
91/// collapses nested tokens, and is `Clone + Send + Sync + 'static`.
92pub use almost_enough::StopToken;
93pub use enough;
94pub use enough::Unstoppable;
95
96// =========================================================================
97// pub(crate) re-exports — keep internal `use crate::Foo` paths working
98// for items that moved out of the public root into sub-modules.
99// =========================================================================
100
101pub(crate) use capabilities::{DecodeCapabilities, EncodeCapabilities};
102pub(crate) use cost::OutputInfo;
103pub(crate) use output::{DecodeOutput, EncodeOutput};
104pub(crate) use policy::{DecodePolicy, EncodePolicy};
105pub(crate) use sink::DecodeRowSink;
106
107// =========================================================================
108// Public sub-modules
109// =========================================================================
110
111/// Encode traits, types, and configuration.
112///
113/// # Trait hierarchy
114///
115/// ```text
116///                                  ┌→ Enc (implements Encoder)
117/// EncoderConfig → EncodeJob ──────┤
118///                                  └→ AnimationFrameEnc (implements AnimationFrameEncoder)
119/// ```
120///
121/// # Object-safe dyn dispatch
122///
123/// ```text
124/// DynEncoderConfig → DynEncodeJob → DynEncoder / DynAnimationFrameEncoder
125/// ```
126///
127/// Codec implementors implement the generic traits. Dispatch callers
128/// use the `Dyn*` variants for codec-agnostic operation.
129pub mod encode {
130    // Traits — config, job, execution
131    pub use crate::traits::{AnimationFrameEncoder, EncodeJob, Encoder, EncoderConfig};
132
133    // Object-safe dyn dispatch
134    pub use crate::traits::{
135        BoxedError, DynAnimationFrameEncoder, DynEncodeJob, DynEncoder, DynEncoderConfig,
136    };
137
138    // Types
139    pub use crate::capabilities::EncodeCapabilities;
140    pub use crate::negotiate::best_encode_format;
141    pub use crate::output::EncodeOutput;
142    pub use crate::policy::EncodePolicy;
143}
144
145/// Decode traits, types, and configuration.
146///
147/// # Trait hierarchy
148///
149/// ```text
150///                                  ┌→ Dec (implements Decode)
151/// DecoderConfig → DecodeJob<'a> ──┤→ StreamDec (implements StreamingDecode)
152///                                  └→ AnimationFrameDec (implements AnimationFrameDecoder)
153/// ```
154///
155/// # Object-safe dyn dispatch
156///
157/// ```text
158/// DynDecoderConfig → DynDecodeJob → DynDecoder / DynAnimationFrameDecoder / DynStreamingDecoder
159/// ```
160///
161/// Codec implementors implement the generic traits. Dispatch callers
162/// use the `Dyn*` variants for codec-agnostic operation.
163pub mod decode {
164    // Traits — config, job, execution
165    pub use crate::traits::{
166        AnimationFrameDecoder, Decode, DecodeJob, DecoderConfig, StreamingDecode,
167    };
168
169    // Object-safe dyn dispatch
170    pub use crate::traits::{
171        BoxedError, DynAnimationFrameDecoder, DynDecodeJob, DynDecoder, DynDecoderConfig,
172        DynStreamingDecoder,
173    };
174
175    // Types
176    pub use crate::capabilities::DecodeCapabilities;
177    pub use crate::cost::OutputInfo;
178    pub use crate::output::{AnimationFrame, DecodeOutput, OwnedAnimationFrame};
179    pub use crate::policy::DecodePolicy;
180    pub use crate::sink::{DecodeRowSink, SinkError};
181
182    pub use crate::negotiate::{is_format_available, negotiate_pixel_format};
183
184    // Source encoding detection
185    pub use crate::detect::SourceEncodingDetails;
186
187    // Shared types re-exported for convenience (commonly needed alongside decode)
188    pub use crate::info::{EmbeddedMetadata, SourceColor};
189}
zencodec/lib.rs

zencodec/
lib.rs
