X-Git-Url: https://git.nihav.org/?p=nihav.git;a=blobdiff_plain;f=nihav-core%2Fsrc%2Fcodecs%2Fmod.rs;h=58757efaf867ab449f7907e6cae51e343a6ace28;hp=7ce056db4143aa455420d6d39dd010a176b91897;hb=78fb6560c73965d834b215fb0b49505ae5443288;hpb=f9be4e750dccff762b9a3d894faec50ffdb59233

diff --git a/nihav-core/src/codecs/mod.rs b/nihav-core/src/codecs/mod.rs
dissimilarity index 67%
index 7ce056d..58757ef 100644
--- a/nihav-core/src/codecs/mod.rs
+++ b/nihav-core/src/codecs/mod.rs
@@ -1,307 +1,351 @@
-use std::fmt;
-use std::ops::{Add, AddAssign, Sub, SubAssign};
-
-pub use crate::frame::*;
-use std::mem;
-use crate::io::byteio::ByteIOError;
-use crate::io::bitreader::BitReaderError;
-use crate::io::codebook::CodebookError;
-
-#[derive(Debug,Clone,Copy,PartialEq)]
-#[allow(dead_code)]
-pub enum DecoderError {
-    NoFrame,
-    AllocError,
-    TryAgain,
-    InvalidData,
-    ShortData,
-    MissingReference,
-    NotImplemented,
-    Bug,
-}
-
-pub type DecoderResult<T> = Result<T, DecoderError>;
-
-impl From<ByteIOError> for DecoderError {
-    fn from(_: ByteIOError) -> Self { DecoderError::ShortData }
-}
-
-impl From<BitReaderError> for DecoderError {
-    fn from(e: BitReaderError) -> Self {
-        match e {
-            BitReaderError::BitstreamEnd => DecoderError::ShortData,
-            _ => DecoderError::InvalidData,
-        }
-    }
-}
-
-impl From<CodebookError> for DecoderError {
-    fn from(_: CodebookError) -> Self { DecoderError::InvalidData }
-}
-
-impl From<AllocatorError> for DecoderError {
-    fn from(_: AllocatorError) -> Self { DecoderError::AllocError }
-}
-
-#[allow(dead_code)]
-pub struct HAMShuffler {
-    lastframe: Option<NAVideoBufferRef<u8>>,
-}
-
-impl HAMShuffler {
-    #[allow(dead_code)]
-    pub fn new() -> Self { HAMShuffler { lastframe: None } }
-    #[allow(dead_code)]
-    pub fn clear(&mut self) { self.lastframe = None; }
-    #[allow(dead_code)]
-    pub fn add_frame(&mut self, buf: NAVideoBufferRef<u8>) {
-        self.lastframe = Some(buf);
-    }
-    #[allow(dead_code)]
-    pub fn clone_ref(&mut self) -> Option<NAVideoBufferRef<u8>> {
-        if let Some(ref mut frm) = self.lastframe {
-            let newfrm = frm.copy_buffer();
-            *frm = newfrm.clone().into_ref();
-            Some(newfrm.into_ref())
-        } else {
-            None
-        }
-    }
-    #[allow(dead_code)]
-    pub fn get_output_frame(&mut self) -> Option<NAVideoBufferRef<u8>> {
-        match self.lastframe {
-            Some(ref frm) => Some(frm.clone()),
-            None => None,
-        }
-    }
-}
-
-impl Default for HAMShuffler {
-    fn default() -> Self { Self { lastframe: None } }
-}
-
-#[allow(dead_code)]
-pub struct IPShuffler {
-    lastframe: Option<NAVideoBufferRef<u8>>,
-}
-
-impl IPShuffler {
-    #[allow(dead_code)]
-    pub fn new() -> Self { IPShuffler { lastframe: None } }
-    #[allow(dead_code)]
-    pub fn clear(&mut self) { self.lastframe = None; }
-    #[allow(dead_code)]
-    pub fn add_frame(&mut self, buf: NAVideoBufferRef<u8>) {
-        self.lastframe = Some(buf);
-    }
-    #[allow(dead_code)]
-    pub fn get_ref(&mut self) -> Option<NAVideoBufferRef<u8>> {
-        if let Some(ref frm) = self.lastframe {
-            Some(frm.clone())
-        } else {
-            None
-        }
-    }
-}
-
-impl Default for IPShuffler {
-    fn default() -> Self { Self { lastframe: None } }
-}
-
-#[allow(dead_code)]
-pub struct IPBShuffler {
-    lastframe: Option<NAVideoBufferRef<u8>>,
-    nextframe: Option<NAVideoBufferRef<u8>>,
-}
-
-impl IPBShuffler {
-    #[allow(dead_code)]
-    pub fn new() -> Self { IPBShuffler { lastframe: None, nextframe: None } }
-    #[allow(dead_code)]
-    pub fn clear(&mut self) { self.lastframe = None; self.nextframe = None; }
-    #[allow(dead_code)]
-    pub fn add_frame(&mut self, buf: NAVideoBufferRef<u8>) {
-        mem::swap(&mut self.lastframe, &mut self.nextframe);
-        self.lastframe = Some(buf);
-    }
-    #[allow(dead_code)]
-    pub fn get_lastref(&mut self) -> Option<NAVideoBufferRef<u8>> {
-        if let Some(ref frm) = self.lastframe {
-            Some(frm.clone())
-        } else {
-            None
-        }
-    }
-    #[allow(dead_code)]
-    pub fn get_nextref(&mut self) -> Option<NAVideoBufferRef<u8>> {
-        if let Some(ref frm) = self.nextframe {
-            Some(frm.clone())
-        } else {
-            None
-        }
-    }
-    #[allow(dead_code)]
-    pub fn get_b_fwdref(&mut self) -> Option<NAVideoBufferRef<u8>> {
-        if let Some(ref frm) = self.nextframe {
-            Some(frm.clone())
-        } else {
-            None
-        }
-    }
-    #[allow(dead_code)]
-    pub fn get_b_bwdref(&mut self) -> Option<NAVideoBufferRef<u8>> {
-        if let Some(ref frm) = self.lastframe {
-            Some(frm.clone())
-        } else {
-            None
-        }
-    }
-}
-
-impl Default for IPBShuffler {
-    fn default() -> Self { Self { lastframe: None, nextframe: None } }
-}
-
-#[derive(Debug,Clone,Copy,Default,PartialEq)]
-pub struct MV {
-    pub x: i16,
-    pub y: i16,
-}
-
-#[allow(clippy::many_single_char_names)]
-#[allow(clippy::collapsible_if)]
-impl MV {
-    pub fn new(x: i16, y: i16) -> Self { MV{ x, y } }
-    pub fn pred(a: MV, b: MV, c: MV) -> Self {
-        let x;
-        if a.x < b.x {
-            if b.x < c.x {
-                x = b.x;
-            } else {
-                if a.x < c.x { x = c.x; } else { x = a.x; }
-            }
-        } else {
-            if b.x < c.x {
-                if a.x < c.x { x = a.x; } else { x = c.x; }
-            } else {
-                x = b.x;
-            }
-        }
-        let y;
-        if a.y < b.y {
-            if b.y < c.y {
-                y = b.y;
-            } else {
-                if a.y < c.y { y = c.y; } else { y = a.y; }
-            }
-        } else {
-            if b.y < c.y {
-                if a.y < c.y { y = a.y; } else { y = c.y; }
-            } else {
-                y = b.y;
-            }
-        }
-        MV { x, y }
-    }
-}
-
-pub const ZERO_MV: MV = MV { x: 0, y: 0 };
-
-impl Add for MV {
-    type Output = MV;
-    fn add(self, other: MV) -> MV { MV { x: self.x + other.x, y: self.y + other.y } }
-}
-
-impl AddAssign for MV {
-    fn add_assign(&mut self, other: MV) { self.x += other.x; self.y += other.y; }
-}
-
-impl Sub for MV {
-    type Output = MV;
-    fn sub(self, other: MV) -> MV { MV { x: self.x - other.x, y: self.y - other.y } }
-}
-
-impl SubAssign for MV {
-    fn sub_assign(&mut self, other: MV) { self.x -= other.x; self.y -= other.y; }
-}
-
-impl fmt::Display for MV {
-    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
-        write!(f, "{},{}", self.x, self.y)
-    }
-}
-
-pub struct NADecoderSupport {
-    pub pool_u8:        NAVideoBufferPool<u8>,
-    pub pool_u16:       NAVideoBufferPool<u16>,
-    pub pool_u32:       NAVideoBufferPool<u32>,
-}
-
-impl NADecoderSupport {
-    pub fn new() -> Self {
-        Self {
-            pool_u8:        NAVideoBufferPool::new(0),
-            pool_u16:       NAVideoBufferPool::new(0),
-            pool_u32:       NAVideoBufferPool::new(0),
-        }
-    }
-}
-
-impl Default for NADecoderSupport {
-    fn default() -> Self { Self::new() }
-}
-
-
-pub trait NADecoder {
-    fn init(&mut self, supp: &mut NADecoderSupport, info: NACodecInfoRef) -> DecoderResult<()>;
-    fn decode(&mut self, supp: &mut NADecoderSupport, pkt: &NAPacket) -> DecoderResult<NAFrameRef>;
-    fn flush(&mut self);
-}
-
-#[derive(Clone,Copy)]
-pub struct DecoderInfo {
-    pub name: &'static str,
-    pub get_decoder: fn () -> Box<dyn NADecoder>,
-}
-
-#[cfg(any(feature="blockdsp"))]
-pub mod blockdsp;
-
-#[cfg(feature="h263")]
-pub mod h263;
-
-#[derive(Default)]
-pub struct RegisteredDecoders {
-    decs:   Vec<DecoderInfo>,
-}
-
-impl RegisteredDecoders {
-    pub fn new() -> Self {
-        Self { decs: Vec::new() }
-    }
-    pub fn add_decoder(&mut self, dec: DecoderInfo) {
-        self.decs.push(dec);
-    }
-    pub fn find_decoder(&self, name: &str) -> Option<fn () -> Box<dyn NADecoder>> {
-        for &dec in self.decs.iter() {
-            if dec.name == name {
-                return Some(dec.get_decoder);
-            }
-        }
-        None
-    }
-    pub fn iter(&self) -> std::slice::Iter<DecoderInfo> {
-        self.decs.iter()
-    }
-}
-
-pub const ZIGZAG: [usize; 64] = [
-     0,  1,  8, 16,  9,  2,  3, 10,
-    17, 24, 32, 25, 18, 11,  4,  5,
-    12, 19, 26, 33, 40, 48, 41, 34,
-    27, 20, 13,  6,  7, 14, 21, 28,
-    35, 42, 49, 56, 57, 50, 43, 36,
-    29, 22, 15, 23, 30, 37, 44, 51,
-    58, 59, 52, 45, 38, 31, 39, 46,
-    53, 60, 61, 54, 47, 55, 62, 63
-];
+//! Decoder interface definitions.
+pub use crate::frame::*;
+use crate::io::byteio::ByteIOError;
+use crate::io::bitreader::BitReaderError;
+use crate::io::codebook::CodebookError;
+pub use crate::options::*;
+pub use std::str::FromStr;
+
+/// 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(_: ByteIOError) -> Self { DecoderError::ShortData }
+}
+
+impl From<BitReaderError> for DecoderError {
+    fn from(e: BitReaderError) -> Self {
+        match e {
+            BitReaderError::BitstreamEnd => DecoderError::ShortData,
+            _ => DecoderError::InvalidData,
+        }
+    }
+}
+
+impl From<CodebookError> for DecoderError {
+    fn from(_: CodebookError) -> Self { DecoderError::InvalidData }
+}
+
+impl From<AllocatorError> for DecoderError {
+    fn from(_: AllocatorError) -> Self { DecoderError::AllocError }
+}
+
+/// 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),
+            pool_u16:       NAVideoBufferPool::new(0),
+            pool_u32:       NAVideoBufferPool::new(0),
+        }
+    }
+}
+
+impl Default for NADecoderSupport {
+    fn default() -> Self { Self::new() }
+}
+
+/// Decoder trait.
+pub trait NADecoder: NAOptionHandler {
+    /// 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 used 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>,
+}
+
+/// Structure for registering known decoders.
+///
+/// It is supposed to be filled using `register_all_decoders()` 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 {
+                return Some(dec.get_decoder);
+            }
+        }
+        None
+    }
+    /// Provides an iterator over currently registered decoders.
+    pub fn iter(&self) -> std::slice::Iter<DecoderInfo> {
+        self.decs.iter()
+    }
+}
+
+/// Frame skipping mode for decoders.
+#[derive(Clone,Copy,PartialEq,Debug)]
+pub enum FrameSkipMode {
+    /// Decode all frames.
+    None,
+    /// Decode all key frames.
+    KeyframesOnly,
+    /// Decode only intra frames.
+    IntraOnly,
+}
+
+impl Default for FrameSkipMode {
+    fn default() -> Self {
+        FrameSkipMode::None
+    }
+}
+
+impl FromStr for FrameSkipMode {
+    type Err = DecoderError;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        match s {
+            FRAME_SKIP_OPTION_VAL_NONE      => Ok(FrameSkipMode::None),
+            FRAME_SKIP_OPTION_VAL_KEYFRAME  => Ok(FrameSkipMode::KeyframesOnly),
+            FRAME_SKIP_OPTION_VAL_INTRA     => Ok(FrameSkipMode::IntraOnly),
+            _ => Err(DecoderError::InvalidData),
+        }
+    }
+}
+
+impl ToString for FrameSkipMode {
+    fn to_string(&self) -> String {
+        match *self {
+            FrameSkipMode::None             => FRAME_SKIP_OPTION_VAL_NONE.to_string(),
+            FrameSkipMode::KeyframesOnly    => FRAME_SKIP_OPTION_VAL_KEYFRAME.to_string(),
+            FrameSkipMode::IntraOnly        => FRAME_SKIP_OPTION_VAL_INTRA.to_string(),
+        }
+    }
+}
+
+/// A list specifying general encoding errors.
+#[derive(Debug,Clone,Copy,PartialEq)]
+#[allow(dead_code)]
+pub enum EncoderError {
+    /// No frame was provided.
+    NoFrame,
+    /// Allocation failed.
+    AllocError,
+    /// Operation requires repeating.
+    TryAgain,
+    /// Input format is not supported by codec.
+    FormatError,
+    /// Invalid input parameters were provided.
+    InvalidParameters,
+    /// Feature is not implemented.
+    NotImplemented,
+    /// Some bug in encoder. It should not happen yet it might.
+    Bug,
+}
+
+/// A specialised `Result` type for decoding operations.
+pub type EncoderResult<T> = Result<T, EncoderError>;
+
+impl From<ByteIOError> for EncoderError {
+    fn from(_: ByteIOError) -> Self { EncoderError::Bug }
+}
+
+impl From<AllocatorError> for EncoderError {
+    fn from(_: AllocatorError) -> Self { EncoderError::AllocError }
+}
+
+/// Encoding parameter flag to force constant bitrate mode.
+pub const ENC_MODE_CBR: u64 = 1 << 0;
+/// Encoding parameter flag to force constant framerate mode.
+pub const ENC_MODE_CFR: u64 = 1 << 1;
+
+/// Encoding parameters.
+#[derive(Clone,Copy,PartialEq)]
+pub struct EncodeParameters {
+    /// Input format.
+    pub format:     NACodecTypeInfo,
+    /// Time base numerator. Ignored for audio.
+    pub tb_num:     u32,
+    /// Time base denominator. Ignored for audio.
+    pub tb_den:     u32,
+    /// Bitrate in kilobits per second.
+    pub bitrate:    u32,
+    /// A collection of various boolean encoder settings like CBR mode.
+    ///
+    /// See `ENC_MODE_*` constants for available options.
+    pub flags:      u64,
+    /// Encoding quality.
+    pub quality:    u8,
+}
+
+impl Default for EncodeParameters {
+    fn default() -> EncodeParameters {
+        EncodeParameters {
+            format:     NACodecTypeInfo::None,
+            tb_num:     0,
+            tb_den:     0,
+            bitrate:    0,
+            flags:      0,
+            quality:    0,
+        }
+    }
+}
+
+/// Encoder trait.
+///
+/// Overall encoding is more complex than decoding.
+/// There are at least two issues that should be addressed: input format and the need for lookahead.
+///
+/// Some formats (like MPEG-1 ones) have fixed picture dimensions and framerate, or sampling rate.
+/// Some formats accept only pictures with dimensions being multiple of eight or sixteen.
+/// Some audio formats work only with monaural sound.
+/// In order to account for all this user first needs to check whether encoder can handle provided input format as is or some conversion is required.
+/// That is why `NAEncoder` has [`negotiate_format`] function that performs such check and returns what encoder can handle.
+///
+/// Additionally, encoders for complex formats often need several frames lookahead to encode data efficiently, actual frame encoding may take place only when some frames are accumulated.
+/// That is why encoder has two functions, one for queueing frames for encoding and one for obtaining encoded packets when they are available.
+/// In result encoder should first queue a frame for encoding with [`encode`] and then retrieve zero or more encoded packets with [`get_packet`] in a loop.
+///
+/// Overall encoding loop should look like this:
+/// ```ignore
+/// let encoder = ...; // create encoder
+/// let enc_params = encoder.negotiate_format(input_enc_params)?; // negotiate format
+/// let output_stream = encoder.init(stream_no, enc_params)?;
+/// while let Some(frame) = queue.get_frame() {
+///     // convert to the format encoder expects if required
+///     encoder.encode(frame)?;
+///     while let Some(enc_pkt) = encoder.get_packet()? {
+///         // send encoded packet to a muxer for example
+///     }
+/// }
+/// // retrieve the rest of encoded packets
+/// encoder.flush()?;
+/// while let Ok(enc_pkt) = encoder.get_packet()? {
+///     // send encoded packet to a muxer for example
+/// }
+/// ```
+///
+/// [`negotiate_format`]: ./trait.NAEncoder.html#tymethod.negotiate_format
+/// [`encode`]: ./trait.NAEncoder.html#tymethod.encode
+/// [`get_packet`]: ./trait.NAEncoder.html#tymethod.get_packet
+pub trait NAEncoder: NAOptionHandler {
+    /// Tries to negotiate input format.
+    ///
+    /// This function takes input encoding parameters and returns adjusted encoding parameters if input ones make sense.
+    /// If input parameters are empty then the default parameters are returned.
+    ///
+    /// # Example
+    /// ```ignore
+    /// let enc_params = [ EncodeParameters {...}, ..., EncodeParameters::default() ];
+    /// let mut target_params = EncodeParameters::default();
+    /// for params in enc_params.iter() {
+    ///     if let Ok(dparams) = encoder.negotiate_format(params) {
+    ///         target_params = dparams;
+    ///         break;
+    ///     }
+    /// }
+    /// // since negotiate_format(EncodeParameters::default()) will return a valid format, target_params should be valid here
+    /// let stream = encoder.init(stream_id, target_params)?;
+    /// // convert input into format defined in target_params, feed to the encoder, ...
+    /// ```
+    fn negotiate_format(&self, encinfo: &EncodeParameters) -> EncoderResult<EncodeParameters>;
+    /// Initialises the encoder.
+    fn init(&mut self, stream_id: u32, encinfo: EncodeParameters) -> EncoderResult<NAStreamRef>;
+    /// Takes a single frame for encoding.
+    fn encode(&mut self, frm: &NAFrame) -> EncoderResult<()>;
+    /// Returns encoded packet if available.
+    fn get_packet(&mut self) -> EncoderResult<Option<NAPacket>>;
+    /// Tells encoder to encode all data it currently has.
+    fn flush(&mut self) -> EncoderResult<()>;
+}
+
+/// Encoder information used during creating an encoder for requested codec.
+#[derive(Clone,Copy)]
+pub struct EncoderInfo {
+    /// Short encoder name.
+    pub name: &'static str,
+    /// The function that creates an encoder instance.
+    pub get_encoder: fn () -> Box<dyn NAEncoder + Send>,
+}
+
+/// Structure for registering known encoders.
+///
+/// It is supposed to be filled using `register_all_decoders()` from some encoders crate and then it can be used to create encoders for the requested codecs.
+#[derive(Default)]
+pub struct RegisteredEncoders {
+    encs:   Vec<EncoderInfo>,
+}
+
+impl RegisteredEncoders {
+    /// Constructs a new instance of `RegisteredEncoders`.
+    pub fn new() -> Self {
+        Self { encs: Vec::new() }
+    }
+    /// Adds another encoder to the registry.
+    pub fn add_encoder(&mut self, enc: EncoderInfo) {
+        self.encs.push(enc);
+    }
+    /// Searches for the encoder for the provided name and returns a function for creating it on success.
+    pub fn find_encoder(&self, name: &str) -> Option<fn () -> Box<dyn NAEncoder + Send>> {
+        for &enc in self.encs.iter() {
+            if enc.name == name {
+                return Some(enc.get_encoder);
+            }
+        }
+        None
+    }
+    /// Provides an iterator over currently registered encoders.
+    pub fn iter(&self) -> std::slice::Iter<EncoderInfo> {
+        self.encs.iter()
+    }
+}
+