+//! Decoder interface definitions.
use std::fmt;
use std::ops::{Add, AddAssign, Sub, SubAssign};
use crate::io::bitreader::BitReaderError;
use crate::io::codebook::CodebookError;
+/// A list specifying general decoding errors.
#[derive(Debug,Clone,Copy,PartialEq)]
#[allow(dead_code)]
pub enum DecoderError {
+ /// No frame was provided.
NoFrame,
+ /// Allocation failed.
AllocError,
+ /// Operation requires repeating.
TryAgain,
+ /// Invalid input data was provided.
InvalidData,
+ /// Provided input turned out to be incomplete.
ShortData,
+ /// Decoder could not decode provided frame because it references some missing previous frame.
MissingReference,
+ /// Feature is not implemented.
NotImplemented,
+ /// Some bug in decoder. It should not happen yet it might.
Bug,
}
+/// A specialised `Result` type for decoding operations.
pub type DecoderResult<T> = Result<T, DecoderError>;
impl From<ByteIOError> for DecoderError {
fn from(_: AllocatorError) -> Self { DecoderError::AllocError }
}
+/// Frame manager for hold-and-modify codecs.
+///
+/// This frame manager simplifies frame management for the case when codec decodes new frame by updating parts of the previous frame.
+///
+/// # Examples
+///
+/// ````norun
+/// let mut frame = if is_intra_frame {
+/// allocate_video_frame()
+/// } else {
+/// let ret = shuffler.clone_ref();
+/// if ret.is_none() {
+/// return Err(DecodingError::MissingReference);
+/// }
+/// ret.unwrap()
+/// };
+/// // output data into the frame
+/// shuffler.add_frame(frame.clone()); // tells frame manager to use the frame as the next reference
+/// ````
#[allow(dead_code)]
pub struct HAMShuffler {
lastframe: Option<NAVideoBufferRef<u8>>,
}
impl HAMShuffler {
+ /// Constructs a new instance of frame manager.
#[allow(dead_code)]
pub fn new() -> Self { HAMShuffler { lastframe: None } }
+ /// Clears the reference.
#[allow(dead_code)]
pub fn clear(&mut self) { self.lastframe = None; }
+ /// Sets a new frame reference.
#[allow(dead_code)]
pub fn add_frame(&mut self, buf: NAVideoBufferRef<u8>) {
self.lastframe = Some(buf);
}
+ /// Provides a copy of the reference frame if present or `None` if it is not.
#[allow(dead_code)]
pub fn clone_ref(&mut self) -> Option<NAVideoBufferRef<u8>> {
if let Some(ref mut frm) = self.lastframe {
None
}
}
+ /// Returns the original saved reference frame or `None` if it is not present.
#[allow(dead_code)]
pub fn get_output_frame(&mut self) -> Option<NAVideoBufferRef<u8>> {
match self.lastframe {
fn default() -> Self { Self { lastframe: None } }
}
+/// Frame manager for codecs with intra and inter frames.
+///
+/// This frame manager simplifies frame management for the case when codec decodes new frame using previous frame as source of some data.
+///
+/// # Examples
+///
+/// ````norun
+/// let mut frame = allocate_video_frame();
+/// if is_inter_frame {
+/// let ret = shuffler.get_ref();
+/// if ret.is_none() {
+/// return Err(DecodingError::MissingReference);
+/// }
+/// let ref_frame = ret.unwrap();
+/// // keep decoding using data from ref_frame
+/// }
+/// shuffler.add_frame(frame.clone()); // tells frame manager to use the frame as the next reference
+/// ````
#[allow(dead_code)]
pub struct IPShuffler {
lastframe: Option<NAVideoBufferRef<u8>>,
}
impl IPShuffler {
+ /// Constructs a new instance of frame manager.
#[allow(dead_code)]
pub fn new() -> Self { IPShuffler { lastframe: None } }
+ /// Clears the reference.
#[allow(dead_code)]
pub fn clear(&mut self) { self.lastframe = None; }
+ /// Sets a new frame reference.
#[allow(dead_code)]
pub fn add_frame(&mut self, buf: NAVideoBufferRef<u8>) {
self.lastframe = Some(buf);
}
+ /// Returns the original saved reference frame or `None` if it is not present.
#[allow(dead_code)]
pub fn get_ref(&mut self) -> Option<NAVideoBufferRef<u8>> {
if let Some(ref frm) = self.lastframe {
fn default() -> Self { Self { lastframe: None } }
}
+/// Frame manager for codecs with I-, P- and B-frames.
+///
+/// This frame manager simplifies frame management for the case when codec uses I/P/B frame scheme.
+///
+/// # Examples
+///
+/// ````norun
+/// let mut frame = allocate_video_frame();
+/// for mb in all_macroblocks {
+/// // decode macroblock type
+/// match mb_type {
+/// MBType::Inter => {
+/// do_mc(&mut frame, shuffler.get_lastref().unwrap());
+/// },
+/// MBType::BForward => {
+/// do_mc(&mut frame, shuffler.get_b_fwdref().unwrap());
+/// },
+/// MBType::BBackward => {
+/// do_mc(&mut frame, shuffler.get_b_bwdref().unwrap());
+/// },
+/// // handle the rest of cases
+/// };
+/// if is_random_access_frame {
+/// shuffler.clear(); // remove all saved references
+/// }
+/// if is_intra_frame || is_p_frame {
+/// shuffler.add_frame(frame.clone()); // tells frame manager to use the frame as the next reference
+/// }
+/// ````
#[allow(dead_code)]
pub struct IPBShuffler {
lastframe: Option<NAVideoBufferRef<u8>>,
}
impl IPBShuffler {
+ /// Constructs a new instance of frame manager.
#[allow(dead_code)]
pub fn new() -> Self { IPBShuffler { lastframe: None, nextframe: None } }
+ /// Clears the reference.
#[allow(dead_code)]
pub fn clear(&mut self) { self.lastframe = None; self.nextframe = None; }
+ /// Sets a new frame reference.
#[allow(dead_code)]
pub fn add_frame(&mut self, buf: NAVideoBufferRef<u8>) {
mem::swap(&mut self.lastframe, &mut self.nextframe);
self.lastframe = Some(buf);
}
+ /// Returns the previous reference frame or `None` if it is not present.
#[allow(dead_code)]
pub fn get_lastref(&mut self) -> Option<NAVideoBufferRef<u8>> {
if let Some(ref frm) = self.lastframe {
None
}
}
+ /// Returns second last reference frame or `None` if it is not present.
#[allow(dead_code)]
pub fn get_nextref(&mut self) -> Option<NAVideoBufferRef<u8>> {
if let Some(ref frm) = self.nextframe {
None
}
}
+ /// Returns the temporally following reference for B-frame or `None` if it is not present.
#[allow(dead_code)]
pub fn get_b_fwdref(&mut self) -> Option<NAVideoBufferRef<u8>> {
if let Some(ref frm) = self.nextframe {
None
}
}
+ /// Returns the temporally preceeding reference for B-frame or `None` if it is not present.
#[allow(dead_code)]
pub fn get_b_bwdref(&mut self) -> Option<NAVideoBufferRef<u8>> {
if let Some(ref frm) = self.lastframe {
fn default() -> Self { Self { lastframe: None, nextframe: None } }
}
+/// Motion vector data type.
+///
+/// # Examples
+///
+/// ```
+/// use nihav_core::codecs::MV;
+///
+/// let mv0 = MV::new(1, 3);
+/// let mv1 = MV { x: 2, y: 3 }; // choose whatever style you prefer
+/// let mv2 = mv1 - mv0;
+/// let mv_pred = MV::pred(mv0, mv1, mv2); // get median prediction for the vectors (1, 0)
+/// ```
#[derive(Debug,Clone,Copy,Default,PartialEq)]
pub struct MV {
+ /// X coordinate of the vector.
pub x: i16,
+ /// Y coordinate of the vector.
pub y: i16,
}
#[allow(clippy::many_single_char_names)]
#[allow(clippy::collapsible_if)]
impl MV {
+ /// Creates a new motion vector instance.
pub fn new(x: i16, y: i16) -> Self { MV{ x, y } }
+ /// Predicts median from provided motion vectors.
+ ///
+ /// Each component of the vector is predicted as the median of corresponding input vector components.
pub fn pred(a: MV, b: MV, c: MV) -> Self {
let x;
if a.x < b.x {
}
}
+/// Zero motion vector.
pub const ZERO_MV: MV = MV { x: 0, y: 0 };
impl Add for MV {
}
}
+/// Auxiliary structure for storing data used by decoder but also controlled by the caller.
pub struct NADecoderSupport {
+ /// Frame buffer pool for 8-bit or packed video frames.
pub pool_u8: NAVideoBufferPool<u8>,
+ /// Frame buffer pool for 16-bit video frames.
pub pool_u16: NAVideoBufferPool<u16>,
+ /// Frame buffer pool for 32-bit video frames.
pub pool_u32: NAVideoBufferPool<u32>,
}
impl NADecoderSupport {
+ /// Constructs a new instance of `NADecoderSupport`.
pub fn new() -> Self {
Self {
pool_u8: NAVideoBufferPool::new(0),
fn default() -> Self { Self::new() }
}
-
+/// Decoder trait.
pub trait NADecoder {
+ /// Initialises the decoder.
+ ///
+ /// It takes [`NADecoderSupport`] allocated by the caller and `NACodecInfoRef` provided by demuxer.
+ ///
+ /// [`NADecoderSupport`]: ./struct.NADecoderSupport.html
fn init(&mut self, supp: &mut NADecoderSupport, info: NACodecInfoRef) -> DecoderResult<()>;
+ /// Decodes a single frame.
fn decode(&mut self, supp: &mut NADecoderSupport, pkt: &NAPacket) -> DecoderResult<NAFrameRef>;
+ /// Tells decoder to clear internal state (e.g. after error or seeking).
fn flush(&mut self);
}
+/// Decoder information using during creating a decoder for requested codec.
#[derive(Clone,Copy)]
pub struct DecoderInfo {
+ /// Short decoder name.
pub name: &'static str,
+ /// The function that creates a decoder instance.
pub get_decoder: fn () -> Box<dyn NADecoder + Send>,
}
#[cfg(feature="h263")]
pub mod h263;
+/// Structure for registering known decoders.
+///
+/// It is supposed to be filled using `register_all_codecs()` from some decoders crate and then it can be used to create decoders for the requested codecs.
#[derive(Default)]
pub struct RegisteredDecoders {
decs: Vec<DecoderInfo>,
}
impl RegisteredDecoders {
+ /// Constructs a new instance of `RegisteredDecoders`.
pub fn new() -> Self {
Self { decs: Vec::new() }
}
+ /// Adds another decoder to the registry.
pub fn add_decoder(&mut self, dec: DecoderInfo) {
self.decs.push(dec);
}
+ /// Searches for the decoder for the provided name and returns a function for creating it on success.
pub fn find_decoder(&self, name: &str) -> Option<fn () -> Box<dyn NADecoder + Send>> {
for &dec in self.decs.iter() {
if dec.name == name {
}
None
}
+ /// Provides an iterator over currently registered decoders.
pub fn iter(&self) -> std::slice::Iter<DecoderInfo> {
self.decs.iter()
}
}
+/// The common 8x8 zigzag scan.
pub const ZIGZAG: [usize; 64] = [
0, 1, 8, 16, 9, 2, 3, 10,
17, 24, 32, 25, 18, 11, 4, 5,
projects / nihav.git / commitdiff