]>
Commit | Line | Data |
---|---|---|
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. Ignored for audio. | |
289 | pub tb_num: u32, | |
290 | /// Time base denominator. Ignored for audio. | |
291 | pub tb_den: u32, | |
292 | /// Bitrate in bits per second. | |
293 | pub bitrate: u32, | |
294 | /// A collection of various boolean encoder settings like CBR mode. | |
295 | /// | |
296 | /// See `ENC_MODE_*` constants for available options. | |
297 | pub flags: u64, | |
298 | /// Encoding quality. | |
299 | pub quality: u8, | |
300 | } | |
301 | ||
302 | impl Default for EncodeParameters { | |
303 | fn default() -> EncodeParameters { | |
304 | EncodeParameters { | |
305 | format: NACodecTypeInfo::None, | |
306 | tb_num: 0, | |
307 | tb_den: 0, | |
308 | bitrate: 0, | |
309 | flags: 0, | |
310 | quality: 0, | |
311 | } | |
312 | } | |
313 | } | |
314 | ||
315 | /// Encoder trait. | |
316 | /// | |
317 | /// Overall encoding is more complex than decoding. | |
318 | /// There are at least two issues that should be addressed: input format and the need for lookahead. | |
319 | /// | |
320 | /// Some formats (like MPEG-1 ones) have fixed picture dimensions and framerate, or sampling rate. | |
321 | /// Some formats accept only pictures with dimensions being multiple of eight or sixteen. | |
322 | /// Some audio formats work only with monaural sound. | |
323 | /// 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. | |
324 | /// That is why `NAEncoder` has [`negotiate_format`] function that performs such check and returns what encoder can handle. | |
325 | /// | |
326 | /// 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. | |
327 | /// That is why encoder has two functions, one for queueing frames for encoding and one for obtaining encoded packets when they are available. | |
328 | /// 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. | |
329 | /// | |
330 | /// Overall encoding loop should look like this: | |
331 | /// ```ignore | |
332 | /// let encoder = ...; // create encoder | |
333 | /// let enc_params = encoder.negotiate_format(input_enc_params)?; // negotiate format | |
334 | /// let output_stream = encoder.init(stream_no, enc_params)?; | |
335 | /// while let Some(frame) = queue.get_frame() { | |
336 | /// // convert to the format encoder expects if required | |
337 | /// encoder.encode(frame)?; | |
338 | /// while let Ok(enc_pkt) = encoder.get_packet()? { | |
339 | /// // send encoded packet to a muxer for example | |
340 | /// } | |
341 | /// } | |
342 | /// // retrieve the rest of encoded packets | |
343 | /// encoder.flush()?; | |
344 | /// while let Ok(enc_pkt) = encoder.get_packet()? { | |
345 | /// // send encoded packet to a muxer for example | |
346 | /// } | |
347 | /// ``` | |
348 | /// | |
349 | /// [`negotiate_format`]: ./trait.NAEncoder.html#tymethod.negotiate_format | |
350 | /// [`encode`]: ./trait.NAEncoder.html#tymethod.encode | |
351 | /// [`get_packet`]: ./trait.NAEncoder.html#tymethod.get_packet | |
352 | pub trait NAEncoder: NAOptionHandler { | |
353 | /// Tries to negotiate input format. | |
354 | /// | |
355 | /// This function takes input encoding parameters and returns adjusted encoding parameters if input ones make sense. | |
356 | /// If input parameters are empty then the default parameters are returned. | |
357 | /// | |
358 | /// # Example | |
359 | /// ```ignore | |
360 | /// let enc_params = [ EncodeParameters {...}, ..., EncodeParameters::default() ]; | |
361 | /// let mut target_params = EncodeParameters::default(); | |
362 | /// for params in enc_params.iter() { | |
363 | /// if let Ok(dparams) = encoder.negotiate_format(params) { | |
364 | /// target_params = dparams; | |
365 | /// break; | |
366 | /// } | |
367 | /// } | |
368 | /// // since negotiate_format(EncodeParameters::default()) will return a valid format, target_params should be valid here | |
369 | /// let stream = encoder.init(stream_id, target_params)?; | |
370 | /// // convert input into format defined in target_params, feed to the encoder, ... | |
371 | /// ``` | |
372 | fn negotiate_format(&self, encinfo: &EncodeParameters) -> EncoderResult<EncodeParameters>; | |
373 | /// Queries encoder capabilities. | |
374 | /// | |
375 | /// See `ENC_CAPS_*` for examples. | |
376 | fn get_capabilities(&self) -> u64; | |
377 | /// Initialises the encoder. | |
378 | fn init(&mut self, stream_id: u32, encinfo: EncodeParameters) -> EncoderResult<NAStreamRef>; | |
379 | /// Takes a single frame for encoding. | |
380 | fn encode(&mut self, frm: &NAFrame) -> EncoderResult<()>; | |
381 | /// Returns encoded packet if available. | |
382 | fn get_packet(&mut self) -> EncoderResult<Option<NAPacket>>; | |
383 | /// Tells encoder to encode all data it currently has. | |
384 | fn flush(&mut self) -> EncoderResult<()>; | |
385 | } | |
386 | ||
387 | /// Encoder information used during creating an encoder for requested codec. | |
388 | #[derive(Clone,Copy)] | |
389 | pub struct EncoderInfo { | |
390 | /// Short encoder name. | |
391 | pub name: &'static str, | |
392 | /// The function that creates an encoder instance. | |
393 | pub get_encoder: fn () -> Box<dyn NAEncoder + Send>, | |
394 | } | |
395 | ||
396 | /// Structure for registering known encoders. | |
397 | /// | |
398 | /// 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. | |
399 | #[derive(Default)] | |
400 | pub struct RegisteredEncoders { | |
401 | encs: Vec<EncoderInfo>, | |
402 | } | |
403 | ||
404 | impl RegisteredEncoders { | |
405 | /// Constructs a new instance of `RegisteredEncoders`. | |
406 | pub fn new() -> Self { | |
407 | Self { encs: Vec::new() } | |
408 | } | |
409 | /// Adds another encoder to the registry. | |
410 | pub fn add_encoder(&mut self, enc: EncoderInfo) { | |
411 | self.encs.push(enc); | |
412 | } | |
413 | /// Searches for the encoder for the provided name and returns a function for creating it on success. | |
414 | pub fn find_encoder(&self, name: &str) -> Option<fn () -> Box<dyn NAEncoder + Send>> { | |
415 | for &enc in self.encs.iter() { | |
416 | if enc.name == name { | |
417 | return Some(enc.get_encoder); | |
418 | } | |
419 | } | |
420 | None | |
421 | } | |
422 | /// Provides an iterator over currently registered encoders. | |
423 | pub fn iter(&self) -> std::slice::Iter<EncoderInfo> { | |
424 | self.encs.iter() | |
425 | } | |
426 | } | |
427 | ||
428 | /// Trait for packetisers (objects that form full packets from raw stream data). | |
429 | pub trait NAPacketiser { | |
430 | /// Queues new raw stream data for parsing. | |
431 | /// | |
432 | /// Returns false is the internal buffer grows too large. | |
433 | fn add_data(&mut self, src: &[u8]) -> bool; | |
434 | /// Tries to retrieve stream information from the data. | |
435 | /// | |
436 | /// Returns [`NAStream`] reference on success (with stream ID set to `id`), [`ShortData`] when there is not enough data to parse the headers and other errors in case there was an error parsing the data. | |
437 | /// | |
438 | /// [`NAStream`]: ../frame/struct.NAStream.html | |
439 | /// [`ShortData`]: ./enum.DecoderError.html#variant.ShortData | |
440 | fn parse_stream(&mut self, id: u32) -> DecoderResult<NAStreamRef>; | |
441 | /// Tries to discard junk data until the first possible packet header. | |
442 | /// | |
443 | /// Returns the number of bytes skipped. | |
444 | fn skip_junk(&mut self) -> DecoderResult<usize>; | |
445 | /// Tries to form full packet from the already queued data. | |
446 | /// | |
447 | /// The function should be called repeatedly until it returns nothing or an error. | |
448 | fn get_packet(&mut self, stream: NAStreamRef) -> DecoderResult<Option<NAPacket>>; | |
449 | /// Resets the internal buffer. | |
450 | fn reset(&mut self); | |
451 | /// Tells how much data is left in the internal buffer. | |
452 | fn bytes_left(&self) -> usize; | |
453 | } | |
454 | ||
455 | /// Decoder information used during creating a packetiser for requested codec. | |
456 | #[derive(Clone,Copy)] | |
457 | pub struct PacketiserInfo { | |
458 | /// Short packetiser name. | |
459 | pub name: &'static str, | |
460 | /// The function that creates a packetiser instance. | |
461 | pub get_packetiser: fn () -> Box<dyn NAPacketiser + Send>, | |
462 | } | |
463 | ||
464 | /// Structure for registering known packetisers. | |
465 | /// | |
466 | /// 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. | |
467 | #[derive(Default)] | |
468 | pub struct RegisteredPacketisers { | |
469 | packs: Vec<PacketiserInfo>, | |
470 | } | |
471 | ||
472 | impl RegisteredPacketisers { | |
473 | /// Constructs a new instance of `RegisteredPacketisers`. | |
474 | pub fn new() -> Self { | |
475 | Self { packs: Vec::new() } | |
476 | } | |
477 | /// Adds another packetiser to the registry. | |
478 | pub fn add_packetiser(&mut self, pack: PacketiserInfo) { | |
479 | self.packs.push(pack); | |
480 | } | |
481 | /// Searches for the packetiser for the provided name and returns a function for creating it on success. | |
482 | pub fn find_packetiser(&self, name: &str) -> Option<fn () -> Box<dyn NAPacketiser + Send>> { | |
483 | for &pack in self.packs.iter() { | |
484 | if pack.name == name { | |
485 | return Some(pack.get_packetiser); | |
486 | } | |
487 | } | |
488 | None | |
489 | } | |
490 | /// Provides an iterator over currently registered packetiser. | |
491 | pub fn iter(&self) -> std::slice::Iter<PacketiserInfo> { | |
492 | self.packs.iter() | |
493 | } | |
494 | } | |
495 |