From 3ba717790e58eeaefa8449e4437a2a06eacabc61 Mon Sep 17 00:00:00 2001 From: Kostya Shishkov Date: Mon, 17 Feb 2020 18:30:08 +0100 Subject: [PATCH] core/codecs: document module --- nihav-core/src/codecs/mod.rs | 137 ++++++++++++++++++++++++++++++++++- 1 file changed, 136 insertions(+), 1 deletion(-) diff --git a/nihav-core/src/codecs/mod.rs b/nihav-core/src/codecs/mod.rs index 9c59c40..b409f67 100644 --- a/nihav-core/src/codecs/mod.rs +++ b/nihav-core/src/codecs/mod.rs @@ -1,3 +1,4 @@ +//! Decoder interface definitions. use std::fmt; use std::ops::{Add, AddAssign, Sub, SubAssign}; @@ -7,19 +8,29 @@ use crate::io::byteio::ByteIOError; 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 = Result; impl From for DecoderError { @@ -43,20 +54,43 @@ impl From 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>, } 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) { 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> { if let Some(ref mut frm) = self.lastframe { @@ -67,6 +101,7 @@ impl HAMShuffler { 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> { match self.lastframe { @@ -80,20 +115,42 @@ impl Default for HAMShuffler { 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>, } 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) { 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> { if let Some(ref frm) = self.lastframe { @@ -108,6 +165,35 @@ impl Default for IPShuffler { 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>, @@ -115,15 +201,19 @@ pub struct IPBShuffler { } 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) { 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> { if let Some(ref frm) = self.lastframe { @@ -132,6 +222,7 @@ impl IPBShuffler { None } } + /// Returns second last reference frame or `None` if it is not present. #[allow(dead_code)] pub fn get_nextref(&mut self) -> Option> { if let Some(ref frm) = self.nextframe { @@ -140,6 +231,7 @@ impl IPBShuffler { 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> { if let Some(ref frm) = self.nextframe { @@ -148,6 +240,7 @@ impl IPBShuffler { 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> { if let Some(ref frm) = self.lastframe { @@ -162,16 +255,34 @@ impl Default for IPBShuffler { 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 { @@ -205,6 +316,7 @@ impl MV { } } +/// Zero motion vector. pub const ZERO_MV: MV = MV { x: 0, y: 0 }; impl Add for MV { @@ -231,13 +343,18 @@ impl fmt::Display 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, + /// Frame buffer pool for 16-bit video frames. pub pool_u16: NAVideoBufferPool, + /// Frame buffer pool for 32-bit video frames. pub pool_u32: NAVideoBufferPool, } impl NADecoderSupport { + /// Constructs a new instance of `NADecoderSupport`. pub fn new() -> Self { Self { pool_u8: NAVideoBufferPool::new(0), @@ -251,16 +368,26 @@ impl Default for NADecoderSupport { 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; + /// 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, } @@ -270,18 +397,24 @@ pub mod blockdsp; #[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, } 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 Box> { for &dec in self.decs.iter() { if dec.name == name { @@ -290,11 +423,13 @@ impl RegisteredDecoders { } None } + /// Provides an iterator over currently registered decoders. pub fn iter(&self) -> std::slice::Iter { 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, -- 2.30.2