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     /// Checksum verification failed.
  22     ChecksumError,
  23     /// Provided input turned out to be incomplete.
  24     ShortData,
  25     /// Decoder could not decode provided frame because it references some missing previous frame.
  26     MissingReference,
  27     /// Feature is not implemented.
  28     NotImplemented,
  29     /// Some bug in decoder. It should not happen yet it might.
  30     Bug,
  31 }
  32
  33 /// A specialised `Result` type for decoding operations.
  34 pub type DecoderResult<T> = Result<T, DecoderError>;
  35
  36 impl From<ByteIOError> for DecoderError {
  37     fn from(_: ByteIOError) -> Self { DecoderError::ShortData }
  38 }
  39
  40 impl From<BitReaderError> for DecoderError {
  41     fn from(e: BitReaderError) -> Self {
  42         match e {
  43             BitReaderError::BitstreamEnd => DecoderError::ShortData,
  44             _ => DecoderError::InvalidData,
  45         }
  46     }
  47 }
  48
  49 impl From<CodebookError> for DecoderError {
  50     fn from(_: CodebookError) -> Self { DecoderError::InvalidData }
  51 }
  52
  53 impl From<AllocatorError> for DecoderError {
  54     fn from(_: AllocatorError) -> Self { DecoderError::AllocError }
  55 }
  56
  57 /// Auxiliary structure for storing data used by decoder but also controlled by the caller.
  58 pub struct NADecoderSupport {
  59     /// Frame buffer pool for 8-bit or packed video frames.
  60     pub pool_u8:        NAVideoBufferPool<u8>,
  61     /// Frame buffer pool for 16-bit video frames.
  62     pub pool_u16:       NAVideoBufferPool<u16>,
  63     /// Frame buffer pool for 32-bit video frames.
  64     pub pool_u32:       NAVideoBufferPool<u32>,
  65 }
  66
  67 impl NADecoderSupport {
  68     /// Constructs a new instance of `NADecoderSupport`.
  69     pub fn new() -> Self {
  70         Self {
  71             pool_u8:        NAVideoBufferPool::new(0),
  72             pool_u16:       NAVideoBufferPool::new(0),
  73             pool_u32:       NAVideoBufferPool::new(0),
  74         }
  75     }
  76 }
  77
  78 impl Default for NADecoderSupport {
  79     fn default() -> Self { Self::new() }
  80 }
  81
  82 /// Decoder trait.
  83 pub trait NADecoder: NAOptionHandler {
  84     /// Initialises the decoder.
  85     ///
  86     /// It takes [`NADecoderSupport`] allocated by the caller and `NACodecInfoRef` provided by demuxer.
  87     ///
  88     /// [`NADecoderSupport`]: ./struct.NADecoderSupport.html
  89     fn init(&mut self, supp: &mut NADecoderSupport, info: NACodecInfoRef) -> DecoderResult<()>;
  90     /// Decodes a single frame.
  91     fn decode(&mut self, supp: &mut NADecoderSupport, pkt: &NAPacket) -> DecoderResult<NAFrameRef>;
  92     /// Tells decoder to clear internal state (e.g. after error or seeking).
  93     fn flush(&mut self);
  94 }
  95
  96 /// Decoder information used during creating a decoder for requested codec.
  97 #[derive(Clone,Copy)]
  98 pub struct DecoderInfo {
  99     /// Short decoder name.
 100     pub name: &'static str,
 101     /// The function that creates a decoder instance.
 102     pub get_decoder: fn () -> Box<dyn NADecoder + Send>,
 103 }
 104
 105 /// Structure for registering known decoders.
 106 ///
 107 /// 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.
 108 #[derive(Default)]
 109 pub struct RegisteredDecoders {
 110     decs:   Vec<DecoderInfo>,
 111 }
 112
 113 impl RegisteredDecoders {
 114     /// Constructs a new instance of `RegisteredDecoders`.
 115     pub fn new() -> Self {
 116         Self { decs: Vec::new() }
 117     }
 118     /// Adds another decoder to the registry.
 119     pub fn add_decoder(&mut self, dec: DecoderInfo) {
 120         self.decs.push(dec);
 121     }
 122     /// Searches for the decoder for the provided name and returns a function for creating it on success.
 123     pub fn find_decoder(&self, name: &str) -> Option<fn () -> Box<dyn NADecoder + Send>> {
 124         for &dec in self.decs.iter() {
 125             if dec.name == name {
 126                 return Some(dec.get_decoder);
 127             }
 128         }
 129         None
 130     }
 131     /// Provides an iterator over currently registered decoders.
 132     pub fn iter(&self) -> std::slice::Iter<DecoderInfo> {
 133         self.decs.iter()
 134     }
 135 }
 136
 137 /// Multithreaded decoder trait.
 138 pub trait NADecoderMT: NAOptionHandler {
 139     /// Initialises the decoder.
 140     ///
 141     /// It takes [`NADecoderSupport`] allocated by the caller and `NACodecInfoRef` provided by demuxer.
 142     ///
 143     /// [`NADecoderSupport`]: ./struct.NADecoderSupport.html
 144     fn init(&mut self, supp: &mut NADecoderSupport, info: NACodecInfoRef, nthreads: usize) -> DecoderResult<()>;
 145     /// Checks if a new frame can be queued for encoding.
 146     fn can_take_input(&mut self) -> bool;
 147     /// Queues a frame for decoding.
 148     ///
 149     /// Returns flag signalling whether the frame was queued or an error if it occured during the preparation stage.
 150     ///
 151     /// Parameter `id` is used to distinguish pictures as the output may be an error code with no timestamp available.
 152     fn queue_pkt(&mut self, supp: &mut NADecoderSupport, pkt: &NAPacket, id: u32) -> DecoderResult<bool>;
 153     /// Checks if some frames are already decoded and waiting to be retrieved.
 154     fn has_output(&mut self) -> bool;
 155     /// Waits for a frame to be decoded.
 156     ///
 157     /// In case there are no decoded frames yet, `None` is returned.
 158     /// Otherwise, a decoding result and the input picture ID are returned.
 159     fn get_frame(&mut self) -> (DecoderResult<NAFrameRef>, u32);
 160     /// Tells decoder to clear internal state (e.g. after error or seeking).
 161     fn flush(&mut self);
 162 }
 163
 164 /// Decoder information used during creating a multi-threaded decoder for requested codec.
 165 #[derive(Clone,Copy)]
 166 pub struct MTDecoderInfo {
 167     /// Short decoder name.
 168     pub name: &'static str,
 169     /// The function that creates a multi-threaded decoder instance.
 170     pub get_decoder: fn () -> Box<dyn NADecoderMT + Send>,
 171 }
 172
 173 /// Structure for registering known multi-threaded decoders.
 174 ///
 175 /// It is supposed to be filled using `register_all_mt_decoders()` from some decoders crate and then it can be used to create multi-threaded decoders for the requested codecs.
 176 #[derive(Default)]
 177 pub struct RegisteredMTDecoders {
 178     decs:   Vec<MTDecoderInfo>,
 179 }
 180
 181 impl RegisteredMTDecoders {
 182     /// Constructs a new instance of `RegisteredMTDecoders`.
 183     pub fn new() -> Self {
 184         Self { decs: Vec::new() }
 185     }
 186     /// Adds another decoder to the registry.
 187     pub fn add_decoder(&mut self, dec: MTDecoderInfo) {
 188         self.decs.push(dec);
 189     }
 190     /// Searches for the decoder for the provided name and returns a function for creating it on success.
 191     pub fn find_decoder(&self, name: &str) -> Option<fn () -> Box<dyn NADecoderMT + Send>> {
 192         for &dec in self.decs.iter() {
 193             if dec.name == name {
 194                 return Some(dec.get_decoder);
 195             }
 196         }
 197         None
 198     }
 199     /// Provides an iterator over currently registered decoders.
 200     pub fn iter(&self) -> std::slice::Iter<MTDecoderInfo> {
 201         self.decs.iter()
 202     }
 203 }
 204
 205 /// Frame skipping mode for decoders.
 206 #[derive(Clone,Copy,PartialEq,Debug,Default)]
 207 pub enum FrameSkipMode {
 208     /// Decode all frames.
 209     #[default]
 210     None,
 211     /// Decode all key frames.
 212     KeyframesOnly,
 213     /// Decode only intra frames.
 214     IntraOnly,
 215 }
 216
 217 impl FromStr for FrameSkipMode {
 218     type Err = DecoderError;
 219
 220     fn from_str(s: &str) -> Result<Self, Self::Err> {
 221         match s {
 222             FRAME_SKIP_OPTION_VAL_NONE      => Ok(FrameSkipMode::None),
 223             FRAME_SKIP_OPTION_VAL_KEYFRAME  => Ok(FrameSkipMode::KeyframesOnly),
 224             FRAME_SKIP_OPTION_VAL_INTRA     => Ok(FrameSkipMode::IntraOnly),
 225             _ => Err(DecoderError::InvalidData),
 226         }
 227     }
 228 }
 229
 230 impl ToString for FrameSkipMode {
 231     fn to_string(&self) -> String {
 232         match *self {
 233             FrameSkipMode::None             => FRAME_SKIP_OPTION_VAL_NONE.to_string(),
 234             FrameSkipMode::KeyframesOnly    => FRAME_SKIP_OPTION_VAL_KEYFRAME.to_string(),
 235             FrameSkipMode::IntraOnly        => FRAME_SKIP_OPTION_VAL_INTRA.to_string(),
 236         }
 237     }
 238 }
 239
 240 /// A list specifying general encoding errors.
 241 #[derive(Debug,Clone,Copy,PartialEq)]
 242 #[allow(dead_code)]
 243 pub enum EncoderError {
 244     /// No frame was provided.
 245     NoFrame,
 246     /// Allocation failed.
 247     AllocError,
 248     /// Operation requires repeating.
 249     TryAgain,
 250     /// Input format is not supported by codec.
 251     FormatError,
 252     /// Invalid input parameters were provided.
 253     InvalidParameters,
 254     /// Feature is not implemented.
 255     NotImplemented,
 256     /// Some bug in encoder. It should not happen yet it might.
 257     Bug,
 258 }
 259
 260 /// A specialised `Result` type for decoding operations.
 261 pub type EncoderResult<T> = Result<T, EncoderError>;
 262
 263 impl From<ByteIOError> for EncoderError {
 264     fn from(_: ByteIOError) -> Self { EncoderError::Bug }
 265 }
 266
 267 impl From<AllocatorError> for EncoderError {
 268     fn from(_: AllocatorError) -> Self { EncoderError::AllocError }
 269 }
 270
 271 /// Encoding parameter flag to force constant bitrate mode.
 272 pub const ENC_MODE_CBR: u64 = 1 << 0;
 273 /// Encoding parameter flag to force constant framerate mode.
 274 pub const ENC_MODE_CFR: u64 = 1 << 1;
 275
 276 /// Encoder supports constant bitrate mode.
 277 pub const ENC_CAPS_CBR: u64 = 1 << 0;
 278 /// Encoder supports skip frames.
 279 pub const ENC_CAPS_SKIPFRAME: u64 = 1 << 1;
 280 /// Encoder supports mid-stream parameters change.
 281 pub const ENC_CAPS_PARAMCHANGE: u64 = 1 << 2;
 282
 283 /// Encoding parameters.
 284 #[derive(Clone,Copy,PartialEq)]
 285 pub struct EncodeParameters {
 286     /// Input format.
 287     pub format:     NACodecTypeInfo,
 288     /// Time base numerator.
 289     ///
 290     /// Audio encoders generally do not need it but some may use it to set e.g. frame length, so set it to the video/container codec timebase in such case.
 291     pub tb_num:     u32,
 292     /// Time base denominator.
 293     ///
 294     /// Audio encoders generally do not need it but some may use it to set e.g. frame length, so set it to the video/container codec timebase in such case.
 295     pub tb_den:     u32,
 296     /// Bitrate in bits per second.
 297     pub bitrate:    u32,
 298     /// A collection of various boolean encoder settings like CBR mode.
 299     ///
 300     /// See `ENC_MODE_*` constants for available options.
 301     pub flags:      u64,
 302     /// Encoding quality.
 303     pub quality:    u8,
 304 }
 305
 306 impl Default for EncodeParameters {
 307     fn default() -> EncodeParameters {
 308         EncodeParameters {
 309             format:     NACodecTypeInfo::None,
 310             tb_num:     0,
 311             tb_den:     0,
 312             bitrate:    0,
 313             flags:      0,
 314             quality:    0,
 315         }
 316     }
 317 }
 318
 319 /// Encoder trait.
 320 ///
 321 /// Overall encoding is more complex than decoding.
 322 /// There are at least two issues that should be addressed: input format and the need for lookahead.
 323 ///
 324 /// Some formats (like MPEG-1 ones) have fixed picture dimensions and framerate, or sampling rate.
 325 /// Some formats accept only pictures with dimensions being multiple of eight or sixteen.
 326 /// Some audio formats work only with monaural sound.
 327 /// 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.
 328 /// That is why `NAEncoder` has [`negotiate_format`] function that performs such check and returns what encoder can handle.
 329 ///
 330 /// 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.
 331 /// That is why encoder has two functions, one for queueing frames for encoding and one for obtaining encoded packets when they are available.
 332 /// 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.
 333 ///
 334 /// Overall encoding loop should look like this:
 335 /// ```ignore
 336 /// let encoder = ...; // create encoder
 337 /// let enc_params = encoder.negotiate_format(input_enc_params)?; // negotiate format
 338 /// let output_stream = encoder.init(stream_no, enc_params)?;
 339 /// while let Some(frame) = queue.get_frame() {
 340 ///     // convert to the format encoder expects if required
 341 ///     encoder.encode(frame)?;
 342 ///     while let Ok(enc_pkt) = encoder.get_packet()? {
 343 ///         // send encoded packet to a muxer for example
 344 ///     }
 345 /// }
 346 /// // retrieve the rest of encoded packets
 347 /// encoder.flush()?;
 348 /// while let Ok(enc_pkt) = encoder.get_packet()? {
 349 ///     // send encoded packet to a muxer for example
 350 /// }
 351 /// ```
 352 ///
 353 /// [`negotiate_format`]: ./trait.NAEncoder.html#tymethod.negotiate_format
 354 /// [`encode`]: ./trait.NAEncoder.html#tymethod.encode
 355 /// [`get_packet`]: ./trait.NAEncoder.html#tymethod.get_packet
 356 pub trait NAEncoder: NAOptionHandler {
 357     /// Tries to negotiate input format.
 358     ///
 359     /// This function takes input encoding parameters and returns adjusted encoding parameters if input ones make sense.
 360     /// If input parameters are empty then the default parameters are returned.
 361     ///
 362     /// # Example
 363     /// ```ignore
 364     /// let enc_params = [ EncodeParameters {...}, ..., EncodeParameters::default() ];
 365     /// let mut target_params = EncodeParameters::default();
 366     /// for params in enc_params.iter() {
 367     ///     if let Ok(dparams) = encoder.negotiate_format(params) {
 368     ///         target_params = dparams;
 369     ///         break;
 370     ///     }
 371     /// }
 372     /// // since negotiate_format(EncodeParameters::default()) will return a valid format, target_params should be valid here
 373     /// let stream = encoder.init(stream_id, target_params)?;
 374     /// // convert input into format defined in target_params, feed to the encoder, ...
 375     /// ```
 376     fn negotiate_format(&self, encinfo: &EncodeParameters) -> EncoderResult<EncodeParameters>;
 377     /// Queries encoder capabilities.
 378     ///
 379     /// See `ENC_CAPS_*` for examples.
 380     fn get_capabilities(&self) -> u64;
 381     /// Initialises the encoder.
 382     fn init(&mut self, stream_id: u32, encinfo: EncodeParameters) -> EncoderResult<NAStreamRef>;
 383     /// Takes a single frame for encoding.
 384     fn encode(&mut self, frm: &NAFrame) -> EncoderResult<()>;
 385     /// Returns encoded packet if available.
 386     fn get_packet(&mut self) -> EncoderResult<Option<NAPacket>>;
 387     /// Tells encoder to encode all data it currently has.
 388     fn flush(&mut self) -> EncoderResult<()>;
 389 }
 390
 391 /// Encoder information used during creating an encoder for requested codec.
 392 #[derive(Clone,Copy)]
 393 pub struct EncoderInfo {
 394     /// Short encoder name.
 395     pub name: &'static str,
 396     /// The function that creates an encoder instance.
 397     pub get_encoder: fn () -> Box<dyn NAEncoder + Send>,
 398 }
 399
 400 /// Structure for registering known encoders.
 401 ///
 402 /// 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.
 403 #[derive(Default)]
 404 pub struct RegisteredEncoders {
 405     encs:   Vec<EncoderInfo>,
 406 }
 407
 408 impl RegisteredEncoders {
 409     /// Constructs a new instance of `RegisteredEncoders`.
 410     pub fn new() -> Self {
 411         Self { encs: Vec::new() }
 412     }
 413     /// Adds another encoder to the registry.
 414     pub fn add_encoder(&mut self, enc: EncoderInfo) {
 415         self.encs.push(enc);
 416     }
 417     /// Searches for the encoder for the provided name and returns a function for creating it on success.
 418     pub fn find_encoder(&self, name: &str) -> Option<fn () -> Box<dyn NAEncoder + Send>> {
 419         for &enc in self.encs.iter() {
 420             if enc.name == name {
 421                 return Some(enc.get_encoder);
 422             }
 423         }
 424         None
 425     }
 426     /// Provides an iterator over currently registered encoders.
 427     pub fn iter(&self) -> std::slice::Iter<EncoderInfo> {
 428         self.encs.iter()
 429     }
 430 }
 431
 432 /// Trait for packetisers (objects that form full packets from raw stream data).
 433 pub trait NAPacketiser {
 434     /// Provides the reference stream from the demuxer to the packetiser.
 435     ///
 436     /// This may be useful in cases when packetiser cannot determine stream parameters by itself.
 437     fn attach_stream(&mut self, stream: NAStreamRef);
 438     /// Queues new raw stream data for parsing.
 439     ///
 440     /// Returns false is the internal buffer grows too large.
 441     fn add_data(&mut self, src: &[u8]) -> bool;
 442     /// Tries to retrieve stream information from the data.
 443     ///
 444     /// Returns [`NAStream`] reference on success (with stream ID set to `id`), [`ShortData`] when there is not enough data to parse the headers, [`MissingReference`] when stream parsing is not possible without reference information provided by [`attach_stream`] and other errors in case there was an error parsing the data.
 445     ///
 446     /// [`NAStream`]: ../frame/struct.NAStream.html
 447     /// [`ShortData`]: ./enum.DecoderError.html#variant.ShortData
 448     /// [`MissingReference`]: ./enum.DecoderError.html#variant.MissingReference
 449     /// [`attach_stream`]: ./trait.NAPacketiser.html#tymethod.attach_stream
 450     fn parse_stream(&mut self, id: u32) -> DecoderResult<NAStreamRef>;
 451     /// Tries to discard junk data until the first possible packet header.
 452     ///
 453     /// Returns the number of bytes skipped.
 454     fn skip_junk(&mut self) -> DecoderResult<usize>;
 455     /// Tries to form full packet from the already queued data.
 456     ///
 457     /// The function should be called repeatedly until it returns nothing or an error.
 458     fn get_packet(&mut self, stream: NAStreamRef) -> DecoderResult<Option<NAPacket>>;
 459     /// Resets the internal buffer.
 460     fn reset(&mut self);
 461     /// Tells how much data is left in the internal buffer.
 462     fn bytes_left(&self) -> usize;
 463 }
 464
 465 /// Decoder information used during creating a packetiser for requested codec.
 466 #[derive(Clone,Copy)]
 467 pub struct PacketiserInfo {
 468     /// Short packetiser name.
 469     pub name: &'static str,
 470     /// The function that creates a packetiser instance.
 471     pub get_packetiser: fn () -> Box<dyn NAPacketiser + Send>,
 472 }
 473
 474 /// Structure for registering known packetisers.
 475 ///
 476 /// It is supposed to be filled using `register_all_packetisers()` from some decoders crate and then it can be used to create packetisers for the requested codecs.
 477 #[derive(Default)]
 478 pub struct RegisteredPacketisers {
 479     packs:  Vec<PacketiserInfo>,
 480 }
 481
 482 impl RegisteredPacketisers {
 483     /// Constructs a new instance of `RegisteredPacketisers`.
 484     pub fn new() -> Self {
 485         Self { packs: Vec::new() }
 486     }
 487     /// Adds another packetiser to the registry.
 488     pub fn add_packetiser(&mut self, pack: PacketiserInfo) {
 489         self.packs.push(pack);
 490     }
 491     /// Searches for the packetiser for the provided name and returns a function for creating it on success.
 492     pub fn find_packetiser(&self, name: &str) -> Option<fn () -> Box<dyn NAPacketiser + Send>> {
 493         for &pack in self.packs.iter() {
 494             if pack.name == name {
 495                 return Some(pack.get_packetiser);
 496             }
 497         }
 498         None
 499     }
 500     /// Provides an iterator over currently registered packetiser.
 501     pub fn iter(&self) -> std::slice::Iter<PacketiserInfo> {
 502         self.packs.iter()
 503     }
 504 }
 505