nihav-core/src/codecs/mod.rs

   1 //! Decoder interface definitions.
   2 pub use crate::frame::*;
   3 use crate::io::byteio::ByteIOError;
   4 use crate::io::bitreader::BitReaderError;
   5 use crate::io::codebook::CodebookError;
   6 pub use crate::options::*;
   7 pub use std::str::FromStr;
   8
   9 /// A list specifying general decoding errors.
  10 #[derive(Debug,Clone,Copy,PartialEq)]
  11 #[allow(dead_code)]
  12 pub enum DecoderError {
  13     /// No frame was provided.
  14     NoFrame,
  15     /// Allocation failed.
  16     AllocError,
  17     /// Operation requires repeating.
  18     TryAgain,
  19     /// Invalid input data was provided.
  20     InvalidData,
  21     /// Provided input turned out to be incomplete.
  22     ShortData,
  23     /// Decoder could not decode provided frame because it references some missing previous frame.
  24     MissingReference,
  25     /// Feature is not implemented.
  26     NotImplemented,
  27     /// Some bug in decoder. It should not happen yet it might.
  28     Bug,
  29 }
  30
  31 /// A specialised `Result` type for decoding operations.
  32 pub type DecoderResult<T> = Result<T, DecoderError>;
  33
  34 impl From<ByteIOError> for DecoderError {
  35     fn from(_: ByteIOError) -> Self { DecoderError::ShortData }
  36 }
  37
  38 impl From<BitReaderError> for DecoderError {
  39     fn from(e: BitReaderError) -> Self {
  40         match e {
  41             BitReaderError::BitstreamEnd => DecoderError::ShortData,
  42             _ => DecoderError::InvalidData,
  43         }
  44     }
  45 }
  46
  47 impl From<CodebookError> for DecoderError {
  48     fn from(_: CodebookError) -> Self { DecoderError::InvalidData }
  49 }
  50
  51 impl From<AllocatorError> for DecoderError {
  52     fn from(_: AllocatorError) -> Self { DecoderError::AllocError }
  53 }
  54
  55 /// Auxiliary structure for storing data used by decoder but also controlled by the caller.
  56 pub struct NADecoderSupport {
  57     /// Frame buffer pool for 8-bit or packed video frames.
  58     pub pool_u8:        NAVideoBufferPool<u8>,
  59     /// Frame buffer pool for 16-bit video frames.
  60     pub pool_u16:       NAVideoBufferPool<u16>,
  61     /// Frame buffer pool for 32-bit video frames.
  62     pub pool_u32:       NAVideoBufferPool<u32>,
  63 }
  64
  65 impl NADecoderSupport {
  66     /// Constructs a new instance of `NADecoderSupport`.
  67     pub fn new() -> Self {
  68         Self {
  69             pool_u8:        NAVideoBufferPool::new(0),
  70             pool_u16:       NAVideoBufferPool::new(0),
  71             pool_u32:       NAVideoBufferPool::new(0),
  72         }
  73     }
  74 }
  75
  76 impl Default for NADecoderSupport {
  77     fn default() -> Self { Self::new() }
  78 }
  79
  80 /// Decoder trait.
  81 pub trait NADecoder: NAOptionHandler {
  82     /// Initialises the decoder.
  83     ///
  84     /// It takes [`NADecoderSupport`] allocated by the caller and `NACodecInfoRef` provided by demuxer.
  85     ///
  86     /// [`NADecoderSupport`]: ./struct.NADecoderSupport.html
  87     fn init(&mut self, supp: &mut NADecoderSupport, info: NACodecInfoRef) -> DecoderResult<()>;
  88     /// Decodes a single frame.
  89     fn decode(&mut self, supp: &mut NADecoderSupport, pkt: &NAPacket) -> DecoderResult<NAFrameRef>;
  90     /// Tells decoder to clear internal state (e.g. after error or seeking).
  91     fn flush(&mut self);
  92 }
  93
  94 /// Decoder information used during creating a decoder for requested codec.
  95 #[derive(Clone,Copy)]
  96 pub struct DecoderInfo {
  97     /// Short decoder name.
  98     pub name: &'static str,
  99     /// The function that creates a decoder instance.
 100     pub get_decoder: fn () -> Box<dyn NADecoder + Send>,
 101 }
 102
 103 /// Structure for registering known decoders.
 104 ///
 105 /// 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.
 106 #[derive(Default)]
 107 pub struct RegisteredDecoders {
 108     decs:   Vec<DecoderInfo>,
 109 }
 110
 111 impl RegisteredDecoders {
 112     /// Constructs a new instance of `RegisteredDecoders`.
 113     pub fn new() -> Self {
 114         Self { decs: Vec::new() }
 115     }
 116     /// Adds another decoder to the registry.
 117     pub fn add_decoder(&mut self, dec: DecoderInfo) {
 118         self.decs.push(dec);
 119     }
 120     /// Searches for the decoder for the provided name and returns a function for creating it on success.
 121     pub fn find_decoder(&self, name: &str) -> Option<fn () -> Box<dyn NADecoder + Send>> {
 122         for &dec in self.decs.iter() {
 123             if dec.name == name {
 124                 return Some(dec.get_decoder);
 125             }
 126         }
 127         None
 128     }
 129     /// Provides an iterator over currently registered decoders.
 130     pub fn iter(&self) -> std::slice::Iter<DecoderInfo> {
 131         self.decs.iter()
 132     }
 133 }
 134
 135 /// Frame skipping mode for decoders.
 136 #[derive(Clone,Copy,PartialEq,Debug)]
 137 pub enum FrameSkipMode {
 138     /// Decode all frames.
 139     None,
 140     /// Decode all key frames.
 141     KeyframesOnly,
 142     /// Decode only intra frames.
 143     IntraOnly,
 144 }
 145
 146 impl Default for FrameSkipMode {
 147     fn default() -> Self {
 148         FrameSkipMode::None
 149     }
 150 }
 151
 152 impl FromStr for FrameSkipMode {
 153     type Err = DecoderError;
 154
 155     fn from_str(s: &str) -> Result<Self, Self::Err> {
 156         match s {
 157             FRAME_SKIP_OPTION_VAL_NONE      => Ok(FrameSkipMode::None),
 158             FRAME_SKIP_OPTION_VAL_KEYFRAME  => Ok(FrameSkipMode::KeyframesOnly),
 159             FRAME_SKIP_OPTION_VAL_INTRA     => Ok(FrameSkipMode::IntraOnly),
 160             _ => Err(DecoderError::InvalidData),
 161         }
 162     }
 163 }
 164
 165 impl ToString for FrameSkipMode {
 166     fn to_string(&self) -> String {
 167         match *self {
 168             FrameSkipMode::None             => FRAME_SKIP_OPTION_VAL_NONE.to_string(),
 169             FrameSkipMode::KeyframesOnly    => FRAME_SKIP_OPTION_VAL_KEYFRAME.to_string(),
 170             FrameSkipMode::IntraOnly        => FRAME_SKIP_OPTION_VAL_INTRA.to_string(),
 171         }
 172     }
 173 }
 174
 175 /// A list specifying general encoding errors.
 176 #[derive(Debug,Clone,Copy,PartialEq)]
 177 #[allow(dead_code)]
 178 pub enum EncoderError {
 179     /// No frame was provided.
 180     NoFrame,
 181     /// Allocation failed.
 182     AllocError,
 183     /// Operation requires repeating.
 184     TryAgain,
 185     /// Input format is not supported by codec.
 186     FormatError,
 187     /// Invalid input parameters were provided.
 188     InvalidParameters,
 189     /// Feature is not implemented.
 190     NotImplemented,
 191     /// Some bug in encoder. It should not happen yet it might.
 192     Bug,
 193 }
 194
 195 /// A specialised `Result` type for decoding operations.
 196 pub type EncoderResult<T> = Result<T, EncoderError>;
 197
 198 impl From<ByteIOError> for EncoderError {
 199     fn from(_: ByteIOError) -> Self { EncoderError::Bug }
 200 }
 201
 202 impl From<AllocatorError> for EncoderError {
 203     fn from(_: AllocatorError) -> Self { EncoderError::AllocError }
 204 }
 205
 206 /// Encoding parameter flag to force constant bitrate mode.
 207 pub const ENC_MODE_CBR: u64 = 1 << 0;
 208 /// Encoding parameter flag to force constant framerate mode.
 209 pub const ENC_MODE_CFR: u64 = 1 << 1;
 210
 211 /// Encoding parameters.
 212 #[derive(Clone,Copy,PartialEq)]
 213 pub struct EncodeParameters {
 214     /// Input format.
 215     pub format:     NACodecTypeInfo,
 216     /// Time base numerator. Ignored for audio.
 217     pub tb_num:     u32,
 218     /// Time base denominator. Ignored for audio.
 219     pub tb_den:     u32,
 220     /// Bitrate in kilobits per second.
 221     pub bitrate:    u32,
 222     /// A collection of various boolean encoder settings like CBR mode.
 223     ///
 224     /// See `ENC_MODE_*` constants for available options.
 225     pub flags:      u64,
 226     /// Encoding quality.
 227     pub quality:    u8,
 228 }
 229
 230 impl Default for EncodeParameters {
 231     fn default() -> EncodeParameters {
 232         EncodeParameters {
 233             format:     NACodecTypeInfo::None,
 234             tb_num:     0,
 235             tb_den:     0,
 236             bitrate:    0,
 237             flags:      0,
 238             quality:    0,
 239         }
 240     }
 241 }
 242
 243 /// Encoder trait.
 244 ///
 245 /// Overall encoding is more complex than decoding.
 246 /// There are at least two issues that should be addressed: input format and the need for lookahead.
 247 ///
 248 /// Some formats (like MPEG-1 ones) have fixed picture dimensions and framerate, or sampling rate.
 249 /// Some formats accept only pictures with dimensions being multiple of eight or sixteen.
 250 /// Some audio formats work only with monaural sound.
 251 /// 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.
 252 /// That is why `NAEncoder` has [`negotiate_format`] function that performs such check and returns what encoder can handle.
 253 ///
 254 /// 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.
 255 /// That is why encoder has two functions, one for queueing frames for encoding and one for obtaining encoded packets when they are available.
 256 /// 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.
 257 ///
 258 /// Overall encoding loop should look like this:
 259 /// ```ignore
 260 /// let encoder = ...; // create encoder
 261 /// let enc_params = encoder.negotiate_format(input_enc_params)?; // negotiate format
 262 /// let output_stream = encoder.init(stream_no, enc_params)?;
 263 /// while let Some(frame) = queue.get_frame() {
 264 ///     // convert to the format encoder expects if required
 265 ///     encoder.encode(frame)?;
 266 ///     while let Some(enc_pkt) = encoder.get_packet()? {
 267 ///         // send encoded packet to a muxer for example
 268 ///     }
 269 /// }
 270 /// // retrieve the rest of encoded packets
 271 /// encoder.flush()?;
 272 /// while let Ok(enc_pkt) = encoder.get_packet()? {
 273 ///     // send encoded packet to a muxer for example
 274 /// }
 275 /// ```
 276 ///
 277 /// [`negotiate_format`]: ./trait.NAEncoder.html#tymethod.negotiate_format
 278 /// [`encode`]: ./trait.NAEncoder.html#tymethod.encode
 279 /// [`get_packet`]: ./trait.NAEncoder.html#tymethod.get_packet
 280 pub trait NAEncoder: NAOptionHandler {
 281     /// Tries to negotiate input format.
 282     ///
 283     /// This function takes input encoding parameters and returns adjusted encoding parameters if input ones make sense.
 284     /// If input parameters are empty then the default parameters are returned.
 285     ///
 286     /// # Example
 287     /// ```ignore
 288     /// let enc_params = [ EncodeParameters {...}, ..., EncodeParameters::default() ];
 289     /// let mut target_params = EncodeParameters::default();
 290     /// for params in enc_params.iter() {
 291     ///     if let Ok(dparams) = encoder.negotiate_format(params) {
 292     ///         target_params = dparams;
 293     ///         break;
 294     ///     }
 295     /// }
 296     /// // since negotiate_format(EncodeParameters::default()) will return a valid format, target_params should be valid here
 297     /// let stream = encoder.init(stream_id, target_params)?;
 298     /// // convert input into format defined in target_params, feed to the encoder, ...
 299     /// ```
 300     fn negotiate_format(&self, encinfo: &EncodeParameters) -> EncoderResult<EncodeParameters>;
 301     /// Initialises the encoder.
 302     fn init(&mut self, stream_id: u32, encinfo: EncodeParameters) -> EncoderResult<NAStreamRef>;
 303     /// Takes a single frame for encoding.
 304     fn encode(&mut self, frm: &NAFrame) -> EncoderResult<()>;
 305     /// Returns encoded packet if available.
 306     fn get_packet(&mut self) -> EncoderResult<Option<NAPacket>>;
 307     /// Tells encoder to encode all data it currently has.
 308     fn flush(&mut self) -> EncoderResult<()>;
 309 }
 310
 311 /// Encoder information used during creating an encoder for requested codec.
 312 #[derive(Clone,Copy)]
 313 pub struct EncoderInfo {
 314     /// Short encoder name.
 315     pub name: &'static str,
 316     /// The function that creates an encoder instance.
 317     pub get_encoder: fn () -> Box<dyn NAEncoder + Send>,
 318 }
 319
 320 /// Structure for registering known encoders.
 321 ///
 322 /// It is supposed to be filled using `register_all_codecs()` from some encoders crate and then it can be used to create encoders for the requested codecs.
 323 #[derive(Default)]
 324 pub struct RegisteredEncoders {
 325     encs:   Vec<EncoderInfo>,
 326 }
 327
 328 impl RegisteredEncoders {
 329     /// Constructs a new instance of `RegisteredEncoders`.
 330     pub fn new() -> Self {
 331         Self { encs: Vec::new() }
 332     }
 333     /// Adds another encoder to the registry.
 334     pub fn add_encoder(&mut self, enc: EncoderInfo) {
 335         self.encs.push(enc);
 336     }
 337     /// Searches for the encoder for the provided name and returns a function for creating it on success.
 338     pub fn find_encoder(&self, name: &str) -> Option<fn () -> Box<dyn NAEncoder + Send>> {
 339         for &enc in self.encs.iter() {
 340             if enc.name == name {
 341                 return Some(enc.get_encoder);
 342             }
 343         }
 344         None
 345     }
 346     /// Provides an iterator over currently registered encoders.
 347     pub fn iter(&self) -> std::slice::Iter<EncoderInfo> {
 348         self.encs.iter()
 349     }
 350 }
 351