]>
Commit | Line | Data |
---|---|---|
3ba71779 | 1 | //! Decoder interface definitions. |
4e8b4f31 | 2 | pub use crate::frame::*; |
aca89041 KS |
3 | use crate::io::byteio::ByteIOError; |
4 | use crate::io::bitreader::BitReaderError; | |
5 | use crate::io::codebook::CodebookError; | |
20766f15 | 6 | pub use crate::options::*; |
0975e7e7 | 7 | pub use std::str::FromStr; |
77d06de2 | 8 | |
3ba71779 | 9 | /// A list specifying general decoding errors. |
77d06de2 KS |
10 | #[derive(Debug,Clone,Copy,PartialEq)] |
11 | #[allow(dead_code)] | |
12 | pub enum DecoderError { | |
3ba71779 | 13 | /// No frame was provided. |
6d3bb0b2 | 14 | NoFrame, |
3ba71779 | 15 | /// Allocation failed. |
e35062e7 | 16 | AllocError, |
3ba71779 | 17 | /// Operation requires repeating. |
503374e7 | 18 | TryAgain, |
3ba71779 | 19 | /// Invalid input data was provided. |
77d06de2 | 20 | InvalidData, |
3ba71779 | 21 | /// Provided input turned out to be incomplete. |
77d06de2 | 22 | ShortData, |
3ba71779 | 23 | /// Decoder could not decode provided frame because it references some missing previous frame. |
77d06de2 | 24 | MissingReference, |
3ba71779 | 25 | /// Feature is not implemented. |
77d06de2 | 26 | NotImplemented, |
3ba71779 | 27 | /// Some bug in decoder. It should not happen yet it might. |
77d06de2 KS |
28 | Bug, |
29 | } | |
30 | ||
3ba71779 | 31 | /// A specialised `Result` type for decoding operations. |
cf64af13 | 32 | pub type DecoderResult<T> = Result<T, DecoderError>; |
77d06de2 KS |
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 | ||
e35062e7 KS |
51 | impl From<AllocatorError> for DecoderError { |
52 | fn from(_: AllocatorError) -> Self { DecoderError::AllocError } | |
53 | } | |
54 | ||
3ba71779 | 55 | /// Auxiliary structure for storing data used by decoder but also controlled by the caller. |
01613464 | 56 | pub struct NADecoderSupport { |
3ba71779 | 57 | /// Frame buffer pool for 8-bit or packed video frames. |
01613464 | 58 | pub pool_u8: NAVideoBufferPool<u8>, |
3ba71779 | 59 | /// Frame buffer pool for 16-bit video frames. |
01613464 | 60 | pub pool_u16: NAVideoBufferPool<u16>, |
3ba71779 | 61 | /// Frame buffer pool for 32-bit video frames. |
01613464 KS |
62 | pub pool_u32: NAVideoBufferPool<u32>, |
63 | } | |
64 | ||
65 | impl NADecoderSupport { | |
3ba71779 | 66 | /// Constructs a new instance of `NADecoderSupport`. |
01613464 KS |
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 | ||
e243ceb4 KS |
76 | impl Default for NADecoderSupport { |
77 | fn default() -> Self { Self::new() } | |
78 | } | |
79 | ||
3ba71779 | 80 | /// Decoder trait. |
7d57ae2f | 81 | pub trait NADecoder: NAOptionHandler { |
3ba71779 KS |
82 | /// Initialises the decoder. |
83 | /// | |
84 | /// It takes [`NADecoderSupport`] allocated by the caller and `NACodecInfoRef` provided by demuxer. | |
85 | /// | |
86 | /// [`NADecoderSupport`]: ./struct.NADecoderSupport.html | |
01613464 | 87 | fn init(&mut self, supp: &mut NADecoderSupport, info: NACodecInfoRef) -> DecoderResult<()>; |
3ba71779 | 88 | /// Decodes a single frame. |
01613464 | 89 | fn decode(&mut self, supp: &mut NADecoderSupport, pkt: &NAPacket) -> DecoderResult<NAFrameRef>; |
3ba71779 | 90 | /// Tells decoder to clear internal state (e.g. after error or seeking). |
f9be4e75 | 91 | fn flush(&mut self); |
77d06de2 KS |
92 | } |
93 | ||
377400a1 | 94 | /// Decoder information used during creating a decoder for requested codec. |
70259941 | 95 | #[derive(Clone,Copy)] |
2a4130ba | 96 | pub struct DecoderInfo { |
3ba71779 | 97 | /// Short decoder name. |
5641dccf | 98 | pub name: &'static str, |
3ba71779 | 99 | /// The function that creates a decoder instance. |
08a1fab7 | 100 | pub get_decoder: fn () -> Box<dyn NADecoder + Send>, |
70259941 KS |
101 | } |
102 | ||
3ba71779 KS |
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. | |
e243ceb4 | 106 | #[derive(Default)] |
5641dccf KS |
107 | pub struct RegisteredDecoders { |
108 | decs: Vec<DecoderInfo>, | |
109 | } | |
110 | ||
111 | impl RegisteredDecoders { | |
3ba71779 | 112 | /// Constructs a new instance of `RegisteredDecoders`. |
5641dccf KS |
113 | pub fn new() -> Self { |
114 | Self { decs: Vec::new() } | |
115 | } | |
3ba71779 | 116 | /// Adds another decoder to the registry. |
5641dccf KS |
117 | pub fn add_decoder(&mut self, dec: DecoderInfo) { |
118 | self.decs.push(dec); | |
119 | } | |
3ba71779 | 120 | /// Searches for the decoder for the provided name and returns a function for creating it on success. |
08a1fab7 | 121 | pub fn find_decoder(&self, name: &str) -> Option<fn () -> Box<dyn NADecoder + Send>> { |
5641dccf KS |
122 | for &dec in self.decs.iter() { |
123 | if dec.name == name { | |
124 | return Some(dec.get_decoder); | |
125 | } | |
70259941 | 126 | } |
5641dccf | 127 | None |
70259941 | 128 | } |
3ba71779 | 129 | /// Provides an iterator over currently registered decoders. |
d10c9311 KS |
130 | pub fn iter(&self) -> std::slice::Iter<DecoderInfo> { |
131 | self.decs.iter() | |
132 | } | |
70259941 | 133 | } |
0b257d9f | 134 | |
0975e7e7 KS |
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 | ||
0b257d9f KS |
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 | ||
2dbe1e64 KS |
202 | impl From<AllocatorError> for EncoderError { |
203 | fn from(_: AllocatorError) -> Self { EncoderError::AllocError } | |
204 | } | |
205 | ||
0b257d9f KS |
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 | |
20766f15 | 280 | pub trait NAEncoder: NAOptionHandler { |
0b257d9f KS |
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 |