rav1e/api/
util.rs

1// Copyright (c) 2018-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#![deny(missing_docs)]
10
11use crate::frame::*;
12use crate::serialize::{Deserialize, Serialize};
13use crate::stats::EncoderStats;
14use crate::util::Pixel;
15
16use std::any::Any;
17use std::fmt;
18use std::sync::Arc;
19
20use thiserror::*;
21
22/// Opaque type to be passed from Frame to Packet
23#[derive(Debug)]
24pub struct Opaque(Box<dyn Any + Send + Sync>);
25
26impl Opaque {
27  /// Wrap a type in the opaque struct
28  pub fn new<T: Any + Send + Sync>(t: T) -> Self {
29    Opaque(Box::new(t) as Box<dyn Any + Send + Sync>)
30  }
31
32  /// Attempt to downcast the opaque to a concrete type.
33  ///
34  /// # Errors
35  ///
36  /// Returns `Err(Self)` if the value could not be downcast to `T`.
37  pub fn downcast<T: Any + Send + Sync>(self) -> Result<Box<T>, Opaque> {
38    if self.0.is::<T>() {
39      // SAFETY: We verified the type of `T` before this cast.
40      unsafe {
41        let raw: *mut (dyn Any + Send + Sync) = Box::into_raw(self.0);
42        Ok(Box::from_raw(raw as *mut T))
43      }
44    } else {
45      Err(self)
46    }
47  }
48}
49
50// TODO: use the num crate?
51/// A rational number.
52#[derive(Clone, Copy, Debug)]
53#[repr(C)]
54pub struct Rational {
55  /// Numerator.
56  pub num: u64,
57  /// Denominator.
58  pub den: u64,
59}
60
61impl Rational {
62  /// Creates a rational number from the given numerator and denominator.
63  pub const fn new(num: u64, den: u64) -> Self {
64    Rational { num, den }
65  }
66
67  /// Returns a rational number that is the reciprocal of the given one.
68  pub const fn from_reciprocal(reciprocal: Self) -> Self {
69    Rational { num: reciprocal.den, den: reciprocal.num }
70  }
71
72  /// Returns the rational number as a floating-point number.
73  pub fn as_f64(self) -> f64 {
74    self.num as f64 / self.den as f64
75  }
76}
77
78#[cfg(feature = "serialize")]
79impl serde::Serialize for Rational {
80  fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
81  where
82    S: serde::Serializer,
83  {
84    (self.num, self.den).serialize(serializer)
85  }
86}
87
88#[cfg(feature = "serialize")]
89impl<'a> serde::Deserialize<'a> for Rational {
90  fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
91  where
92    D: serde::Deserializer<'a>,
93  {
94    let (num, den) = serde::Deserialize::deserialize(deserializer)?;
95
96    Ok(Rational::new(num, den))
97  }
98}
99
100/// Possible types of a frame.
101#[allow(dead_code, non_camel_case_types)]
102#[derive(Debug, Eq, PartialEq, Clone, Copy, Serialize, Deserialize)]
103#[repr(C)]
104pub enum FrameType {
105  /// Key frame.
106  KEY,
107  /// Inter-frame.
108  INTER,
109  /// Intra-only frame.
110  INTRA_ONLY,
111  /// Switching frame.
112  SWITCH,
113}
114
115impl FrameType {
116  /// Returns whether frame can have inter blocks
117  #[inline]
118  pub fn has_inter(self) -> bool {
119    self == FrameType::INTER || self == FrameType::SWITCH
120  }
121  /// Returns whether frame is only intra blocks
122  #[inline]
123  pub fn all_intra(self) -> bool {
124    self == FrameType::KEY || self == FrameType::INTRA_ONLY
125  }
126}
127
128impl fmt::Display for FrameType {
129  fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
130    use self::FrameType::*;
131    match self {
132      KEY => write!(f, "Key frame"),
133      INTER => write!(f, "Inter frame"),
134      INTRA_ONLY => write!(f, "Intra only frame"),
135      SWITCH => write!(f, "Switching frame"),
136    }
137  }
138}
139
140/// A single T.35 metadata packet.
141#[derive(Clone, Debug, Default)]
142pub struct T35 {
143  /// Country code.
144  pub country_code: u8,
145  /// Country code extension bytes (if country_code == 0xFF)
146  pub country_code_extension_byte: u8,
147  /// T.35 payload.
148  pub data: Box<[u8]>,
149}
150
151/// Status that can be returned by [`Context`] functions.
152///
153/// [`Context`]: struct.Context.html
154#[derive(Clone, Copy, Debug, Eq, PartialEq, Error)]
155pub enum EncoderStatus {
156  /// The encoder needs more data to produce an output packet.
157  ///
158  /// May be emitted by [`Context::receive_packet()`] when frame reordering is
159  /// enabled.
160  ///
161  /// [`Context::receive_packet()`]: struct.Context.html#method.receive_packet
162  #[error("need more data")]
163  NeedMoreData,
164  /// There are enough frames in the queue.
165  ///
166  /// May be emitted by [`Context::send_frame()`] when trying to send a frame
167  /// after the encoder has been flushed.
168  ///
169  /// [`Context::send_frame()`]: struct.Context.html#method.send_frame
170  #[error("enough data")]
171  EnoughData,
172  /// The encoder has already produced the number of frames requested.
173  ///
174  /// May be emitted by [`Context::receive_packet()`] after a flush request had
175  /// been processed or the frame limit had been reached.
176  ///
177  /// [`Context::receive_packet()`]: struct.Context.html#method.receive_packet
178  #[error("limit reached")]
179  LimitReached,
180  /// A frame had been encoded but not emitted yet.
181  #[error("encoded")]
182  Encoded,
183  /// Generic fatal error.
184  #[error("failure")]
185  Failure,
186  /// A frame was encoded in the first pass of a 2-pass encode, but its stats
187  /// data was not retrieved with [`Context::twopass_out()`], or not enough
188  /// stats data was provided in the second pass of a 2-pass encode to encode
189  /// the next frame.
190  ///
191  /// [`Context::twopass_out()`]: struct.Context.html#method.twopass_out
192  #[error("not ready")]
193  NotReady,
194}
195
196/// Represents a packet.
197///
198/// A packet contains one shown frame together with zero or more additional
199/// frames.
200#[derive(Debug, Serialize, Deserialize)]
201pub struct Packet<T: Pixel> {
202  /// The packet data.
203  pub data: Vec<u8>,
204  /// The reconstruction of the shown frame.
205  #[cfg_attr(feature = "serialize", serde(skip))]
206  pub rec: Option<Arc<Frame<T>>>,
207  /// The Reference Frame
208  #[cfg_attr(feature = "serialize", serde(skip))]
209  pub source: Option<Arc<Frame<T>>>,
210  /// The number of the input frame corresponding to the one shown frame in the
211  /// TU stored in this packet. Since AV1 does not explicitly reorder frames,
212  /// these will increase sequentially.
213  // TODO: When we want to add VFR support, we will need a more explicit time
214  // stamp here.
215  pub input_frameno: u64,
216  /// Type of the shown frame.
217  pub frame_type: FrameType,
218  /// QP selected for the frame.
219  pub qp: u8,
220  /// Block-level encoding stats for the frame
221  pub enc_stats: EncoderStats,
222  /// Optional user-provided opaque data
223  #[cfg_attr(feature = "serialize", serde(skip))]
224  pub opaque: Option<Opaque>,
225}
226
227impl<T: Pixel> PartialEq for Packet<T> {
228  fn eq(&self, other: &Self) -> bool {
229    self.data == other.data
230      && self.input_frameno == other.input_frameno
231      && self.frame_type == other.frame_type
232      && self.qp == other.qp
233  }
234}
235
236impl<T: Pixel> fmt::Display for Packet<T> {
237  fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
238    write!(
239      f,
240      "Frame {} - {} - {} bytes",
241      self.input_frameno,
242      self.frame_type,
243      self.data.len()
244    )
245  }
246}
247
248/// Types which can be converted into frames.
249///
250/// This trait is used in [`Context::send_frame`] to allow for passing in
251/// frames with optional frame parameters and optionally frames wrapped in
252/// `Arc` (to allow for zero-copy, since the encoder uses frames in `Arc`
253/// internally).
254///
255/// [`Context::send_frame`]: struct.Context.html#method.send_frame
256pub trait IntoFrame<T: Pixel> {
257  /// Converts the type into a tuple of frame and parameters.
258  fn into(self) -> (Option<Arc<Frame<T>>>, Option<FrameParameters>);
259}
260
261impl<T: Pixel> IntoFrame<T> for Option<Arc<Frame<T>>> {
262  fn into(self) -> (Option<Arc<Frame<T>>>, Option<FrameParameters>) {
263    (self, None)
264  }
265}
266
267impl<T: Pixel> IntoFrame<T> for Arc<Frame<T>> {
268  fn into(self) -> (Option<Arc<Frame<T>>>, Option<FrameParameters>) {
269    (Some(self), None)
270  }
271}
272
273impl<T: Pixel> IntoFrame<T> for (Arc<Frame<T>>, FrameParameters) {
274  fn into(self) -> (Option<Arc<Frame<T>>>, Option<FrameParameters>) {
275    (Some(self.0), Some(self.1))
276  }
277}
278
279impl<T: Pixel> IntoFrame<T> for (Arc<Frame<T>>, Option<FrameParameters>) {
280  fn into(self) -> (Option<Arc<Frame<T>>>, Option<FrameParameters>) {
281    (Some(self.0), self.1)
282  }
283}
284
285impl<T: Pixel> IntoFrame<T> for Frame<T> {
286  fn into(self) -> (Option<Arc<Frame<T>>>, Option<FrameParameters>) {
287    (Some(Arc::new(self)), None)
288  }
289}
290
291impl<T: Pixel> IntoFrame<T> for (Frame<T>, FrameParameters) {
292  fn into(self) -> (Option<Arc<Frame<T>>>, Option<FrameParameters>) {
293    (Some(Arc::new(self.0)), Some(self.1))
294  }
295}
296
297impl<T: Pixel> IntoFrame<T> for (Frame<T>, Option<FrameParameters>) {
298  fn into(self) -> (Option<Arc<Frame<T>>>, Option<FrameParameters>) {
299    (Some(Arc::new(self.0)), self.1)
300  }
301}
rav1e/api/util.rs

rav1e/api/
util.rs
