zenrav1e/
lib.rs

1// Copyright (c) 2017-2022, The rav1e contributors. All rights reserved
2//
3// This source code is subject to the terms of the BSD 2 Clause License and
4// the Alliance for Open Media Patent License 1.0. If the BSD 2 Clause License
5// was not distributed with this source code in the LICENSE file, you can
6// obtain it at www.aomedia.org/license/software. If the Alliance for Open
7// Media Patent License 1.0 was not distributed with this source code in the
8// PATENTS file, you can obtain it at www.aomedia.org/license/patent.
9
10//! zenrav1e is an [AV1] encoder optimized for still and animated AVIF images.
11//!
12//! This is Imazen's fork of [rav1e](https://github.com/xiph/rav1e), focused on
13//! compression efficiency for photographic content. Key improvements over upstream:
14//!
15//! * **Quantization matrices** — frequency-dependent quantization weights (~10% BD-rate gain)
16//! * **Filter intra prediction** — 5 recursive filter modes for smooth gradients
17//! * **Lossless mode** — mathematically lossless encoding via `quantizer: 0`
18//! * **Still picture mode** — single-frame encoding without video overhead
19//!
20//! Also supports full video encoding (intra, inter, switch frames) inherited from upstream rav1e.
21//!
22//! ## Usage
23//!
24//! Encoding is done through the [`Context`] struct. Examples on
25//! [`Context::receive_packet`] show how to create a [`Context`], send frames
26//! into it and receive packets of encoded data.
27//!
28//! [AV1]: https://aomediacodec.github.io/av1-spec/av1-spec.pdf
29//! [`Context`]: struct.Context.html
30//! [`Context::receive_packet`]: struct.Context.html#method.receive_packet
31
32#![allow(missing_abi)]
33#![allow(unused_unsafe)]
34
35#[cfg(test)]
36#[macro_use]
37extern crate pretty_assertions;
38
39pub use crate::api::color;
40pub use crate::api::{
41  Config, Context, EncoderConfig, EncoderStatus, InvalidConfig, Packet,
42};
43use crate::encoder::*;
44pub use crate::frame::Frame;
45pub use crate::util::{CastFromPrimitive, Pixel, PixelType};
46
47#[cfg(feature = "stop")]
48pub use enough::{Stop, StopReason, Unstoppable};
49
50pub(crate) mod built_info {
51  // The file has been placed there by the build script.
52  include!(concat!(env!("OUT_DIR"), "/built.rs"));
53}
54
55mod serialize {
56  cfg_if::cfg_if! {
57    if #[cfg(feature="serialize")] {
58      pub use serde::*;
59    } else {
60      pub use noop_proc_macro::{Deserialize, Serialize};
61    }
62  }
63}
64
65mod wasm_bindgen {
66  cfg_if::cfg_if! {
67    if #[cfg(feature="wasm")] {
68      pub use wasm_bindgen::prelude::*;
69    } else {
70      pub use noop_proc_macro::wasm_bindgen;
71    }
72  }
73}
74
75#[cfg(any(cargo_c, feature = "capi"))]
76pub mod capi;
77
78#[macro_use]
79mod transform;
80#[macro_use]
81mod cpu_features;
82
83mod activity;
84pub(crate) mod asm;
85mod dist;
86mod ec;
87mod partition;
88mod predict;
89mod quantize;
90mod rdo;
91mod rdo_tables;
92#[macro_use]
93mod util;
94mod cdef;
95#[doc(hidden)]
96pub mod context;
97mod deblock;
98mod encoder;
99mod entropymode;
100mod levels;
101mod lrf;
102mod mc;
103mod me;
104mod rate;
105mod recon_intra;
106mod scan_order;
107mod segmentation;
108mod stats;
109#[doc(hidden)]
110pub mod tiling;
111mod token_cdfs;
112
113#[cfg(not(feature = "scenechange"))]
114#[path = "scenechange_stub.rs"]
115mod av_scenechange;
116
117mod api;
118mod frame;
119mod header;
120
121/// Commonly used types and traits.
122pub mod prelude {
123  pub use crate::api::*;
124  pub use crate::encoder::{Sequence, Tune};
125  pub use crate::frame::{
126    Frame, FrameParameters, FrameTypeOverride, Plane, PlaneConfig,
127  };
128  pub use crate::partition::BlockSize;
129  pub use crate::predict::PredictionMode;
130  pub use crate::transform::TxType;
131  pub use crate::util::{CastFromPrimitive, Pixel, PixelType};
132}
133
134/// Basic data structures
135pub mod data {
136  pub use crate::api::{
137    ChromaticityPoint, EncoderStatus, FrameType, Packet, Rational,
138  };
139  pub use crate::frame::{Frame, FrameParameters};
140  pub use crate::stats::EncoderStats;
141  pub use crate::util::{CastFromPrimitive, Pixel, PixelType};
142}
143
144/// Encoder configuration and settings
145pub mod config {
146  pub use crate::api::config::{
147    GrainTableSegment, NUM_UV_COEFFS, NUM_UV_POINTS, NUM_Y_COEFFS,
148    NUM_Y_POINTS, NoiseGenArgs, TransferFunction,
149  };
150  pub use crate::api::{
151    Config, EncoderConfig, InvalidConfig, PredictionModesSetting,
152    RateControlConfig, RateControlError, RateControlSummary, SpeedSettings,
153  };
154  pub use crate::cpu_features::CpuFeatureLevel;
155}
156
157/// Version information
158///
159/// The information is recovered from `Cargo.toml` and `git describe`, when available.
160///
161/// ```
162/// use zenrav1e::version;
163/// use semver::Version;
164///
165/// let major = version::major();
166/// let minor = version::minor();
167/// let patch = version::patch();
168///
169/// let short = version::short();
170///
171/// let v1 = Version::new(major, minor, patch);
172/// let v2 = Version::parse(&short).unwrap();
173///
174/// assert_eq!(v1.major, v2.major);
175/// ```
176pub mod version {
177  /// Major version component
178  ///
179  /// It is increased every time a release presents a incompatible API change.
180  ///
181  /// # Panics
182  ///
183  /// Will panic if package is not built with Cargo,
184  /// or if the package version is not a valid triplet of integers.
185  pub fn major() -> u64 {
186    env!("CARGO_PKG_VERSION_MAJOR").parse().unwrap()
187  }
188  /// Minor version component
189  ///
190  /// It is increased every time a release presents new functionalities are added
191  /// in a backwards-compatible manner.
192  ///
193  /// # Panics
194  ///
195  /// Will panic if package is not built with Cargo,
196  /// or if the package version is not a valid triplet of integers.
197  pub fn minor() -> u64 {
198    env!("CARGO_PKG_VERSION_MINOR").parse().unwrap()
199  }
200  /// Patch version component
201  ///
202  /// It is increased every time a release provides only backwards-compatible bugfixes.
203  ///
204  /// # Panics
205  ///
206  /// Will panic if package is not built with Cargo,
207  /// or if the package version is not a valid triplet of integers.
208  pub fn patch() -> u64 {
209    env!("CARGO_PKG_VERSION_PATCH").parse().unwrap()
210  }
211
212  /// Version information as presented in `[package]` `version`.
213  ///
214  /// e.g. `0.1.0`
215  ///
216  /// Can be parsed by [semver](https://crates.io/crates/semver).
217  pub fn short() -> String {
218    env!("CARGO_PKG_VERSION").to_string()
219  }
220
221  /// Version information as presented in `[package] version` followed by the
222  /// short commit hash if present.
223  ///
224  /// e.g. `0.1.0 - g743d464`
225  ///
226  pub fn long() -> String {
227    let s = short();
228    let hash = hash();
229
230    if hash.is_empty() { s } else { format!("{s} - {hash}") }
231  }
232
233  cfg_if::cfg_if! {
234    if #[cfg(feature="git_version")] {
235      fn git_version() -> &'static str {
236        crate::built_info::GIT_VERSION.unwrap_or_default()
237      }
238
239      fn git_hash() -> &'static str {
240        crate::built_info::GIT_COMMIT_HASH.unwrap_or_default()
241      }
242    } else {
243      fn git_version() -> &'static str {
244        "UNKNOWN"
245      }
246
247      fn git_hash() -> &'static str {
248        "UNKNOWN"
249      }
250    }
251  }
252  /// Commit hash (short)
253  ///
254  /// Short hash of the git commit used by this build
255  ///
256  /// e.g. `g743d464`
257  ///
258  pub fn hash() -> String {
259    git_hash().to_string()
260  }
261
262  /// Version information with the information
263  /// provided by `git describe --tags`.
264  ///
265  /// e.g. `0.1.0 (v0.1.0-1-g743d464)`
266  ///
267  pub fn full() -> String {
268    format!("{} ({})", short(), git_version(),)
269  }
270}
271#[cfg(all(
272  any(test, fuzzing),
273  any(feature = "decode_test", feature = "decode_test_dav1d")
274))]
275mod test_encode_decode;
276
277#[cfg(feature = "bench")]
278pub mod bench {
279  pub mod api {
280    pub use crate::api::*;
281  }
282  pub mod cdef {
283    pub use crate::cdef::*;
284  }
285  pub mod context {
286    pub use crate::context::*;
287  }
288  pub mod dist {
289    pub use crate::dist::*;
290  }
291  pub mod ec {
292    pub use crate::ec::*;
293  }
294  pub mod encoder {
295    pub use crate::encoder::*;
296  }
297  pub mod mc {
298    pub use crate::mc::*;
299  }
300  pub mod partition {
301    pub use crate::partition::*;
302  }
303  pub mod frame {
304    pub use crate::frame::*;
305  }
306  pub mod predict {
307    pub use crate::predict::*;
308  }
309  pub mod rdo {
310    pub use crate::rdo::*;
311  }
312  pub mod tiling {
313    pub use crate::tiling::*;
314  }
315  pub mod transform {
316    pub use crate::transform::*;
317  }
318  pub mod util {
319    pub use crate::util::*;
320  }
321  pub mod cpu_features {
322    pub use crate::cpu_features::*;
323  }
324}
325
326#[cfg(fuzzing)]
327pub mod fuzzing;
zenrav1e/lib.rs

zenrav1e/
lib.rs
