rav1e/
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//! rav1e is an [AV1] video encoder. It is designed to eventually cover all use
11//! cases, though in its current form it is most suitable for cases where
12//! libaom (the reference encoder) is too slow.
13//!
14//! ## Features
15//!
16//! * Intra and inter frames
17//! * 64x64 superblocks
18//! * 4x4 to 64x64 RDO-selected square and 2:1/1:2 rectangular blocks
19//! * DC, H, V, Paeth, smooth, and a subset of directional prediction modes
20//! * DCT, (FLIP-)ADST and identity transforms (up to 64x64, 16x16 and 32x32
21//!   respectively)
22//! * 8-, 10- and 12-bit depth color
23//! * 4:2:0 (full support), 4:2:2 and 4:4:4 (limited) chroma sampling
24//! * Variable speed settings
25//! * Near real-time encoding at high speed levels
26//!
27//! ## Usage
28//!
29//! Encoding is done through the [`Context`] struct. Examples on
30//! [`Context::receive_packet`] show how to create a [`Context`], send frames
31//! into it and receive packets of encoded data.
32//!
33//! [AV1]: https://aomediacodec.github.io/av1-spec/av1-spec.pdf
34//! [`Context`]: struct.Context.html
35//! [`Context::receive_packet`]: struct.Context.html#method.receive_packet
36
37#![allow(missing_abi)]
38#![allow(unused_unsafe)]
39
40#[cfg(test)]
41#[macro_use]
42extern crate pretty_assertions;
43
44pub use crate::api::color;
45pub use crate::api::{
46  Config, Context, EncoderConfig, EncoderStatus, InvalidConfig, Packet,
47};
48use crate::encoder::*;
49pub use crate::frame::Frame;
50pub use crate::util::{CastFromPrimitive, Pixel, PixelType};
51
52pub(crate) mod built_info {
53  // The file has been placed there by the build script.
54  include!(concat!(env!("OUT_DIR"), "/built.rs"));
55}
56
57mod serialize {
58  cfg_if::cfg_if! {
59    if #[cfg(feature="serialize")] {
60      pub use serde::*;
61    } else {
62      pub use noop_proc_macro::{Deserialize, Serialize};
63    }
64  }
65}
66
67mod wasm_bindgen {
68  cfg_if::cfg_if! {
69    if #[cfg(feature="wasm")] {
70      pub use wasm_bindgen::prelude::*;
71    } else {
72      pub use noop_proc_macro::wasm_bindgen;
73    }
74  }
75}
76
77#[cfg(any(cargo_c, feature = "capi"))]
78pub mod capi;
79
80#[macro_use]
81mod transform;
82#[macro_use]
83mod cpu_features;
84
85mod activity;
86pub(crate) mod asm;
87mod dist;
88mod ec;
89mod partition;
90mod predict;
91mod quantize;
92mod rdo;
93mod rdo_tables;
94#[macro_use]
95mod util;
96mod cdef;
97#[doc(hidden)]
98pub mod context;
99mod deblock;
100mod encoder;
101mod entropymode;
102mod levels;
103mod lrf;
104mod mc;
105mod me;
106mod rate;
107mod recon_intra;
108mod scan_order;
109mod segmentation;
110mod stats;
111#[doc(hidden)]
112pub mod tiling;
113mod token_cdfs;
114
115mod api;
116mod frame;
117mod header;
118
119/// Commonly used types and traits.
120pub mod prelude {
121  pub use crate::api::*;
122  pub use crate::encoder::{Sequence, Tune};
123  pub use crate::frame::{
124    Frame, FrameParameters, FrameTypeOverride, Plane, PlaneConfig,
125  };
126  pub use crate::partition::BlockSize;
127  pub use crate::predict::PredictionMode;
128  pub use crate::transform::TxType;
129  pub use crate::util::{CastFromPrimitive, Pixel, PixelType};
130}
131
132/// Basic data structures
133pub mod data {
134  pub use crate::api::{
135    ChromaticityPoint, EncoderStatus, FrameType, Packet, Rational,
136  };
137  pub use crate::frame::{Frame, FrameParameters};
138  pub use crate::stats::EncoderStats;
139  pub use crate::util::{CastFromPrimitive, Pixel, PixelType};
140}
141
142/// Encoder configuration and settings
143pub mod config {
144  pub use crate::api::config::{
145    GrainTableSegment, NoiseGenArgs, TransferFunction, NUM_UV_COEFFS,
146    NUM_UV_POINTS, NUM_Y_COEFFS, NUM_Y_POINTS,
147  };
148  pub use crate::api::{
149    Config, EncoderConfig, InvalidConfig, PredictionModesSetting,
150    RateControlConfig, RateControlError, RateControlSummary, SpeedSettings,
151  };
152  pub use crate::cpu_features::CpuFeatureLevel;
153}
154
155/// Version information
156///
157/// The information is recovered from `Cargo.toml` and `git describe`, when available.
158///
159/// ```
160/// use rav1e::version;
161/// use semver::Version;
162///
163/// let major = version::major();
164/// let minor = version::minor();
165/// let patch = version::patch();
166///
167/// let short = version::short();
168///
169/// let v1 = Version::new(major, minor, patch);
170/// let v2 = Version::parse(&short).unwrap();
171///
172/// assert_eq!(v1.major, v2.major);
173/// ```
174pub mod version {
175  /// Major version component
176  ///
177  /// It is increased every time a release presents a incompatible API change.
178  ///
179  /// # Panics
180  ///
181  /// Will panic if package is not built with Cargo,
182  /// or if the package version is not a valid triplet of integers.
183  pub fn major() -> u64 {
184    env!("CARGO_PKG_VERSION_MAJOR").parse().unwrap()
185  }
186  /// Minor version component
187  ///
188  /// It is increased every time a release presents new functionalities are added
189  /// in a backwards-compatible manner.
190  ///
191  /// # Panics
192  ///
193  /// Will panic if package is not built with Cargo,
194  /// or if the package version is not a valid triplet of integers.
195  pub fn minor() -> u64 {
196    env!("CARGO_PKG_VERSION_MINOR").parse().unwrap()
197  }
198  /// Patch version component
199  ///
200  /// It is increased every time a release provides only backwards-compatible bugfixes.
201  ///
202  /// # Panics
203  ///
204  /// Will panic if package is not built with Cargo,
205  /// or if the package version is not a valid triplet of integers.
206  pub fn patch() -> u64 {
207    env!("CARGO_PKG_VERSION_PATCH").parse().unwrap()
208  }
209
210  /// Version information as presented in `[package]` `version`.
211  ///
212  /// e.g. `0.1.0`
213  ///
214  /// Can be parsed by [semver](https://crates.io/crates/semver).
215  pub fn short() -> String {
216    env!("CARGO_PKG_VERSION").to_string()
217  }
218
219  /// Version information as presented in `[package] version` followed by the
220  /// short commit hash if present.
221  ///
222  /// e.g. `0.1.0 - g743d464`
223  ///
224  pub fn long() -> String {
225    let s = short();
226    let hash = hash();
227
228    if hash.is_empty() {
229      s
230    } else {
231      format!("{s} - {hash}")
232    }
233  }
234
235  cfg_if::cfg_if! {
236    if #[cfg(feature="git_version")] {
237      fn git_version() -> &'static str {
238        crate::built_info::GIT_VERSION.unwrap_or_default()
239      }
240
241      fn git_hash() -> &'static str {
242        crate::built_info::GIT_COMMIT_HASH.unwrap_or_default()
243      }
244    } else {
245      fn git_version() -> &'static str {
246        "UNKNOWN"
247      }
248
249      fn git_hash() -> &'static str {
250        "UNKNOWN"
251      }
252    }
253  }
254  /// Commit hash (short)
255  ///
256  /// Short hash of the git commit used by this build
257  ///
258  /// e.g. `g743d464`
259  ///
260  pub fn hash() -> String {
261    git_hash().to_string()
262  }
263
264  /// Version information with the information
265  /// provided by `git describe --tags`.
266  ///
267  /// e.g. `0.1.0 (v0.1.0-1-g743d464)`
268  ///
269  pub fn full() -> String {
270    format!("{} ({})", short(), git_version(),)
271  }
272}
273#[cfg(all(
274  any(test, fuzzing),
275  any(feature = "decode_test", feature = "decode_test_dav1d")
276))]
277mod test_encode_decode;
278
279#[cfg(feature = "bench")]
280pub mod bench {
281  pub mod api {
282    pub use crate::api::*;
283  }
284  pub mod cdef {
285    pub use crate::cdef::*;
286  }
287  pub mod context {
288    pub use crate::context::*;
289  }
290  pub mod dist {
291    pub use crate::dist::*;
292  }
293  pub mod ec {
294    pub use crate::ec::*;
295  }
296  pub mod encoder {
297    pub use crate::encoder::*;
298  }
299  pub mod mc {
300    pub use crate::mc::*;
301  }
302  pub mod partition {
303    pub use crate::partition::*;
304  }
305  pub mod frame {
306    pub use crate::frame::*;
307  }
308  pub mod predict {
309    pub use crate::predict::*;
310  }
311  pub mod rdo {
312    pub use crate::rdo::*;
313  }
314  pub mod tiling {
315    pub use crate::tiling::*;
316  }
317  pub mod transform {
318    pub use crate::transform::*;
319  }
320  pub mod util {
321    pub use crate::util::*;
322  }
323  pub mod cpu_features {
324    pub use crate::cpu_features::*;
325  }
326}
327
328#[cfg(fuzzing)]
329pub mod fuzzing;
rav1e/lib.rs

rav1e/
lib.rs
