]> git.nihav.org Git - nihav.git/commitdiff
core/codecs: document module
authorKostya Shishkov <kostya.shishkov@gmail.com>
Mon, 17 Feb 2020 17:30:08 +0000 (18:30 +0100)
committerKostya Shishkov <kostya.shishkov@gmail.com>
Mon, 17 Feb 2020 17:30:08 +0000 (18:30 +0100)
nihav-core/src/codecs/mod.rs

index 9c59c40184029358038e1a87bdcc25910503ae28..b409f67f17eac132bf240d89107e57708811c600 100644 (file)
@@ -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<T> = Result<T, DecoderError>;
 
 impl From<ByteIOError> for DecoderError {
@@ -43,20 +54,43 @@ impl From<AllocatorError> 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 {
@@ -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<NAVideoBufferRef<u8>> {
         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<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 {
@@ -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<NAVideoBufferRef<u8>>,
@@ -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<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 {
@@ -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<NAVideoBufferRef<u8>> {
         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<NAVideoBufferRef<u8>> {
         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<NAVideoBufferRef<u8>> {
         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<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),
@@ -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<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>,
 }
 
@@ -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<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 {
@@ -290,11 +423,13 @@ impl RegisteredDecoders {
         }
         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,