From 6c9578bed2944ca6e21aec8d97c8a2e73b24b5fc Mon Sep 17 00:00:00 2001 From: Kostya Shishkov Date: Mon, 17 Feb 2020 16:13:18 +0100 Subject: [PATCH] core: document reorder module --- nihav-core/src/reorder.rs | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/nihav-core/src/reorder.rs b/nihav-core/src/reorder.rs index fe6670c..83896df 100644 --- a/nihav-core/src/reorder.rs +++ b/nihav-core/src/reorder.rs @@ -1,18 +1,32 @@ +//! Output frame reordering. +//! +//! NihAV decoders output frames in the same order as they are put in. +//! In result if you want to have frames in display order you might need some frame reorderer. +//! This module provides such functionality depending on codec type: audio codecs and video codecs without B-frames do not need any reorderer and can use `NoReorderer` if the common interface is required. Codecs with B-frames should use `IPBReorderer`. For codecs with very complex reordering rules like H.264 or H.256 `PictureIDReorderer` will be added eventually. +//! +//! You can find out required reorderer by quering codec properties using `nihav_core::register` module. use std::mem::swap; pub use crate::frame::{FrameType, NAFrameRef}; +/// A trait for frame reorderer. pub trait FrameReorderer { + /// Stores a newly decoded frame. fn add_frame(&mut self, fref: NAFrameRef) -> bool; + /// Gets the next frame to be displayed (or `None` if that is not possible). fn get_frame(&mut self) -> Option; + /// Clears all stored frames. fn flush(&mut self); + /// Retrieves the last frames stored by the reorderer. fn get_last_frames(&mut self) -> Option; } +/// Zero reorderer. pub struct NoReorderer { fref: Option, } impl NoReorderer { + /// Constructs a new instance of `NoReorderer`. pub fn new() -> Self { Self { fref: None } } @@ -36,6 +50,7 @@ impl FrameReorderer for NoReorderer { fn get_last_frames(&mut self) -> Option { None } } +/// Frame reorderer for codecs with I/P/B frames. #[derive(Default)] pub struct IPBReorderer { rframe: Option, @@ -43,6 +58,7 @@ pub struct IPBReorderer { } impl IPBReorderer { + /// Constructs a new instance of `IPBReorderer`. pub fn new() -> Self { Self::default() } } -- 2.30.2