core/demuxers: document module

1 files changed, 81 insertions, 4 deletions

diff --git a/nihav-core/src/demuxers/mod.rs b/nihav-core/src/demuxers/mod.rs
index ee2fe58..8857cee 100644
--- a/nihav-core/src/demuxers/mod.rs
+++ b/nihav-core/src/demuxers/mod.rs
@@ -1,30 +1,49 @@
+//! Demuxer definitions.
 pub use crate::frame::*;
 pub use crate::io::byteio::*;
 
+/// A list specifying general demuxing errors.
 #[derive(Debug,Clone,Copy,PartialEq)]
 #[allow(dead_code)]
 pub enum DemuxerError {
+    /// Reader got to end of stream.
     EOF,
+    /// Demuxer encountered empty container.
     NoSuchInput,
+    /// Demuxer encountered invalid input data.
     InvalidData,
+    /// Data reading error.
     IOError,
+    /// Feature is not implemented.
     NotImplemented,
+    /// Allocation failed.
     MemoryError,
+    /// The operation should be repeated.
     TryAgain,
+    /// Seeking failed.
     SeekError,
+    /// Operation cannot succeed in principle (e.g. seeking in a format not supporting seeking).
     NotPossible,
 }
 
+/// A specialised `Result` type for demuxing operations.
 pub type DemuxerResult<T> = Result<T, DemuxerError>;
 
+/// A trait for demuxing operations.
 pub trait DemuxCore<'a> {
+    /// Opens the input stream, reads required headers and prepares everything for packet demuxing.
     fn open(&mut self, strmgr: &mut StreamManager, seek_idx: &mut SeekIndex) -> DemuxerResult<()>;
+    /// Demuxes a packet.
     fn get_frame(&mut self, strmgr: &mut StreamManager) -> DemuxerResult<NAPacket>;
+    /// Seeks to the requested time.
     fn seek(&mut self, time: u64, seek_idx: &SeekIndex) -> DemuxerResult<()>;
 }
 
+/// An auxiliary trait to make bytestream reader read packet data.
 pub trait NAPacketReader {
+    /// Reads input and constructs a packet containing it.
     fn read_packet(&mut self, str: NAStreamRef, ts: NATimeInfo, keyframe: bool, size: usize) -> DemuxerResult<NAPacket>;
+    /// Reads input into already existing packet.
     fn fill_packet(&mut self, pkt: &mut NAPacket) -> DemuxerResult<()>;
 }
 
@@ -45,6 +64,7 @@ impl<'a> NAPacketReader for ByteReader<'a> {
     }
 }
 
+/// An auxiliary structure for operations with individual streams inside the container.
 #[derive(Default)]
 pub struct StreamManager {
     streams: Vec<NAStreamRef>,
@@ -53,6 +73,7 @@ pub struct StreamManager {
 }
 
 impl StreamManager {
+    /// Constructs a new instance of `StreamManager`.
     pub fn new() -> Self {
         StreamManager {
             streams: Vec::new(),
@@ -60,8 +81,10 @@ impl StreamManager {
             no_ign:  true,
         }
     }
+    /// Returns stream iterator.
     pub fn iter(&self) -> StreamIter { StreamIter::new(&self.streams) }
 
+    /// Adds a new stream.
     pub fn add_stream(&mut self, stream: NAStream) -> Option<usize> {
         let stream_num = self.streams.len();
         let mut str = stream.clone();
@@ -70,6 +93,7 @@ impl StreamManager {
         self.ignored.push(false);
         Some(stream_num)
     }
+    /// Returns stream with the requested index.
     pub fn get_stream(&self, idx: usize) -> Option<NAStreamRef> {
         if idx < self.streams.len() {
             Some(self.streams[idx].clone())
@@ -77,6 +101,7 @@ impl StreamManager {
             None
         }
     }
+    /// Returns stream with the requested stream ID.
     pub fn get_stream_by_id(&self, id: u32) -> Option<NAStreamRef> {
         for i in 0..self.streams.len() {
             if self.streams[i].get_id() == id {
@@ -85,7 +110,9 @@ impl StreamManager {
         }
         None
     }
+    /// Returns the number of known streams.
     pub fn get_num_streams(&self) -> usize { self.streams.len() }
+    /// Reports whether the stream is marked as ignored.
     pub fn is_ignored(&self, idx: usize) -> bool {
         if self.no_ign {
             true
@@ -95,6 +122,7 @@ impl StreamManager {
             false
         }
     }
+    /// Reports whether the stream with certain ID is marked as ignored.
     pub fn is_ignored_id(&self, id: u32) -> bool {
         for i in 0..self.streams.len() {
             if self.streams[i].get_id() == id {
@@ -103,12 +131,14 @@ impl StreamManager {
         }
         false
     }
+    /// Marks requested stream as ignored.
     pub fn set_ignored(&mut self, idx: usize) {
         if idx < self.ignored.len() {
             self.ignored[idx] = true;
             self.no_ign = false;
         }
     }
+    /// Clears the ignored mark for the requested stream.
     pub fn set_unignored(&mut self, idx: usize) {
         if idx < self.ignored.len() {
             self.ignored[idx] = false;
@@ -116,12 +146,14 @@ impl StreamManager {
     }
 }
 
+/// Stream iterator.
 pub struct StreamIter<'a> {
     streams:    &'a [NAStreamRef],
     pos:        usize,
 }
 
 impl<'a> StreamIter<'a> {
+    /// Constructs a new instance of `StreamIter`.
     pub fn new(streams: &'a [NAStreamRef]) -> Self {
         StreamIter { streams, pos: 0 }
     }
@@ -138,10 +170,14 @@ impl<'a> Iterator for StreamIter<'a> {
     }
 }
 
+/// Seeking modes.
 #[derive(Clone,Copy,PartialEq)]
 pub enum SeekIndexMode {
+    /// No seeking index present.
     None,
+    /// Seeking index is present.
     Present,
+    /// Seeking index should be constructed by the demuxer if possible.
     Automatic,
 }
 
@@ -149,21 +185,30 @@ impl Default for SeekIndexMode {
     fn default() -> Self { SeekIndexMode::None }
 }
 
+/// A structure holding seeking information.
 #[derive(Clone,Copy,Default)]
 pub struct SeekEntry {
-    pub time:   u64, // in milliseconds
+    /// Time in milliseconds.
+    pub time:   u64,
+    /// PTS
     pub pts:    u64,
+    /// Position in file.
     pub pos:    u64,
 }
 
+/// Seeking information for individual streams.
 #[derive(Clone)]
 pub struct StreamSeekInfo {
+    /// Stream ID.
     pub id:         u32,
+    /// Index is present.
     pub filled:     bool,
+    /// Packet seeking information.
     pub entries:    Vec<SeekEntry>,
 }
 
 impl StreamSeekInfo {
+    /// Constructs a new `StreamSeekInfo` instance.
     pub fn new(id: u32) -> Self {
         Self {
             id,
@@ -171,9 +216,11 @@ impl StreamSeekInfo {
             entries:    Vec::new(),
         }
     }
+    /// Adds new seeking point.
     pub fn add_entry(&mut self, entry: SeekEntry) {
         self.entries.push(entry);
     }
+    /// Searches for an appropriate seek position before requested time.
     pub fn find_pos(&self, time: u64) -> Option<SeekEntry> {
         if !self.entries.is_empty() {
 // todo something faster like binary search
@@ -192,21 +239,30 @@ impl StreamSeekInfo {
     }
 }
 
+/// Structure for holding seeking point search results.
 #[derive(Clone,Copy,Default)]
 pub struct SeekIndexResult {
+    /// Packet PTS.
     pub pts:        u64,
+    /// Position in file.
     pub pos:        u64,
+    /// Stream ID.
     pub str_id:     u32,
 }
 
+/// Seek information for the whole container.
 #[derive(Default)]
 pub struct SeekIndex {
+    /// Seek information for individual streams.
     pub seek_info:  Vec<StreamSeekInfo>,
+    /// Seeking index mode.
     pub mode:       SeekIndexMode,
+    /// Ignore index flag.
     pub skip_index: bool,
 }
 
 impl SeekIndex {
+    /// Constructs a new `SeekIndex` instance.
     pub fn new() -> Self { Self::default() }
     pub fn add_stream(&mut self, id: u32) -> usize {
         let ret = self.stream_id_to_index(id);
@@ -217,6 +273,7 @@ impl SeekIndex {
             ret.unwrap()
         }
     }
+    /// Adds a new stream to the index.
     pub fn stream_id_to_index(&self, id: u32) -> Option<usize> {
         for (idx, str) in self.seek_info.iter().enumerate() {
             if str.id == id {
@@ -225,6 +282,7 @@ impl SeekIndex {
         }
         None
     }
+    /// Returns stream reference for provided stream ID.
     pub fn get_stream_index(&mut self, id: u32) -> Option<&mut StreamSeekInfo> {
         for str in self.seek_info.iter_mut() {
             if str.id == id {
@@ -233,6 +291,7 @@ impl SeekIndex {
         }
         None
     }
+    /// Adds seeking information to the index.
     pub fn add_entry(&mut self, id: u32, entry: SeekEntry) {
         let mut idx = self.stream_id_to_index(id);
         if idx.is_none() {
@@ -241,6 +300,7 @@ impl SeekIndex {
         self.seek_info[idx.unwrap()].add_entry(entry);
         self.seek_info[idx.unwrap()].filled = true;
     }
+    /// Searches for a seek position before requested time.
     pub fn find_pos(&self, time: u64) -> Option<SeekIndexResult> {
         let mut cand = None;
         for str in self.seek_info.iter() {
@@ -260,6 +320,7 @@ impl SeekIndex {
     }
 }
 
+/// Demuxer structure with auxiliary data.
 pub struct Demuxer<'a> {
     dmx:        Box<dyn DemuxCore<'a> + 'a>,
     streams:    StreamManager,
@@ -267,6 +328,7 @@ pub struct Demuxer<'a> {
 }
 
 impl<'a> Demuxer<'a> {
+    /// Constructs a new `Demuxer` instance.
     fn new(dmx: Box<dyn DemuxCore<'a> + 'a>, str: StreamManager, seek_idx: SeekIndex) -> Self {
         Demuxer {
             dmx,
@@ -274,28 +336,36 @@ impl<'a> Demuxer<'a> {
             seek_idx,
         }
     }
+    /// Returns a stream reference by its number.
     pub fn get_stream(&self, idx: usize) -> Option<NAStreamRef> {
         self.streams.get_stream(idx)
     }
+    /// Returns a stream reference by its ID.
     pub fn get_stream_by_id(&self, id: u32) -> Option<NAStreamRef> {
         self.streams.get_stream_by_id(id)
     }
+    /// Reports the total number of streams.
     pub fn get_num_streams(&self) -> usize {
         self.streams.get_num_streams()
     }
+    /// Returns an iterator over streams.
     pub fn get_streams(&self) -> StreamIter {
         self.streams.iter()
     }
+    /// Returns 'ignored' marker for requested stream.
     pub fn is_ignored_stream(&self, idx: usize) -> bool {
         self.streams.is_ignored(idx)
     }
+    /// Sets 'ignored' marker for requested stream.
     pub fn set_ignored_stream(&mut self, idx: usize) {
         self.streams.set_ignored(idx)
     }
+    /// Clears 'ignored' marker for requested stream.
     pub fn set_unignored_stream(&mut self, idx: usize) {
         self.streams.set_unignored(idx)
     }
 
+    /// Demuxes a new packet from the container.
     pub fn get_frame(&mut self) -> DemuxerResult<NAPacket> {
         loop {
             let res = self.dmx.get_frame(&mut self.streams);
@@ -307,12 +377,14 @@ impl<'a> Demuxer<'a> {
             }
         }
     }
+    /// Seeks to the requested time (in milliseconds) if possible.
     pub fn seek(&mut self, time: u64) -> DemuxerResult<()> {
         if self.seek_idx.skip_index {
             return Err(DemuxerError::NotPossible);
         }
         self.dmx.seek(time, &self.seek_idx)
     }
+    /// Returns internal seek index.
     pub fn get_seek_index(&self) -> &SeekIndex {
         &self.seek_idx
     }
@@ -322,14 +394,15 @@ impl From<ByteIOError> for DemuxerError {
     fn from(_: ByteIOError) -> Self { DemuxerError::IOError }
 }
 
-///The structure used to create demuxers.
+/// The trait for creating demuxers.
 pub trait DemuxerCreator {
-    /// Create new demuxer instance that will use `ByteReader` source as an input.
+    /// Creates new demuxer instance that will use `ByteReader` source as an input.
     fn new_demuxer<'a>(&self, br: &'a mut ByteReader<'a>) -> Box<dyn DemuxCore<'a> + 'a>;
-    /// Get the name of current demuxer creator.
+    /// Returns the name of current demuxer creator (equal to the container name it can demux).
     fn get_name(&self) -> &'static str;
 }
 
+/// Creates demuxer for a provided bytestream.
 pub fn create_demuxer<'a>(dmxcr: &DemuxerCreator, br: &'a mut ByteReader<'a>) -> DemuxerResult<Demuxer<'a>> {
     let mut dmx = dmxcr.new_demuxer(br);
     let mut str = StreamManager::new();
@@ -338,18 +411,22 @@ pub fn create_demuxer<'a>(dmxcr: &DemuxerCreator, br: &'a mut ByteReader<'a>) ->
     Ok(Demuxer::new(dmx, str, seek_idx))
 }
 
+/// List of registered demuxers.
 #[derive(Default)]
 pub struct RegisteredDemuxers {
     dmxs:   Vec<&'static DemuxerCreator>,
 }
 
 impl RegisteredDemuxers {
+    /// Constructs a new `RegisteredDemuxers` instance.
     pub fn new() -> Self {
         Self { dmxs: Vec::new() }
     }
+    /// Registers a new demuxer.
     pub fn add_demuxer(&mut self, dmx: &'static DemuxerCreator) {
         self.dmxs.push(dmx);
     }
+    /// Searches for a demuxer that supports requested container format.
     pub fn find_demuxer(&self, name: &str) -> Option<&DemuxerCreator> {
         for &dmx in self.dmxs.iter() {
             if dmx.get_name() == name {