1 /*****************************************************************************
2 * vlc_codec.h: Definition of the decoder and encoder structures
3 *****************************************************************************
4 * Copyright (C) 1999-2003 VLC authors and VideoLAN
5 * $Id: 3499ede27c1dbb94ff665a51d000c55bd45f2794 $
6 *
7 * Authors: Gildas Bazin <gbazin@netcourrier.com>
8 *
9 * This program is free software; you can redistribute it and/or modify it
10 * under the terms of the GNU Lesser General Public License as published by
11 * the Free Software Foundation; either version 2.1 of the License, or
12 * (at your option) any later version.
13 *
14 * This program is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 * GNU Lesser General Public License for more details.
18 *
19 * You should have received a copy of the GNU Lesser General Public License
20 * along with this program; if not, write to the Free Software Foundation,
21 * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
22 *****************************************************************************/
23
24 #ifndef VLC_CODEC_H
25 #define VLC_CODEC_H 1
26
27 #include <assert.h>
28
29 #include <vlc_block.h>
30 #include <vlc_es.h>
31 #include <vlc_picture.h>
32 #include <vlc_subpicture.h>
33
34 /**
35 * \defgroup codec Codec
36 * Decoders and encoders
37 * @{
38 * \file
39 * Decoder and encoder modules interface
40 *
41 * \defgroup decoder Decoder
42 * Audio, video and text decoders
43 * @{
44 */
45
46 typedef struct decoder_owner_sys_t decoder_owner_sys_t;
47
48 typedef struct decoder_cc_desc_t decoder_cc_desc_t;
49
50 /*
51 * BIG FAT WARNING : the code relies in the first 4 members of filter_t
52 * and decoder_t to be the same, so if you have anything to add, do it
53 * at the end of the structure.
54 */
55 struct decoder_t
56 {
57 VLC_COMMON_MEMBERS
58
59 /* Module properties */
60 module_t * p_module;
61 decoder_sys_t * p_sys;
62
63 /* Input format ie from demuxer (XXX: a lot of field could be invalid) */
64 es_format_t fmt_in;
65
66 /* Output format of decoder/packetizer */
67 es_format_t fmt_out;
68
69 /* Tell the decoder if it is allowed to drop frames */
70 bool b_frame_drop_allowed;
71
72 # define VLCDEC_SUCCESS VLC_SUCCESS
73 # define VLCDEC_ECRITICAL VLC_EGENERIC
74 # define VLCDEC_RELOAD (-100)
75 /* This function is called to decode one packetized block.
76 *
77 * The module implementation will own the input block (p_block) and should
78 * process and release it. Depending of the decoder type, the module should
79 * send output frames/blocks via decoder_QueueVideo(), decoder_QueueAudio()
80 * or decoder_QueueSub().
81 *
82 * If p_block is NULL, the decoder asks the module to drain itself. The
83 * module should return all available output frames/block via the queue
84 * functions.
85 *
86 * Return values can be:
87 * VLCDEC_SUCCESS: pf_decode will be called again
88 * VLCDEC_ECRITICAL: in case of critical error, pf_decode won't be called
89 * again.
90 * VLCDEC_RELOAD: Request that the decoder should be reloaded. The current
91 * module will be unloaded. Reloading a module may cause a loss of frames.
92 * When returning this status, the implementation shouldn't release or
93 * modify the p_block in argument (The same p_block will be feed to the
94 * next decoder module).
95 */
96 int ( * pf_decode ) ( decoder_t *, block_t *p_block );
97
98 /* This function is called in a loop with the same pp_block argument until
99 * it returns NULL. This allows a module implementation to return more than
100 * one output blocks for one input block.
101 *
102 * pp_block or *pp_block can be NULL.
103 *
104 * If pp_block and *pp_block are not NULL, the module implementation will
105 * own the input block (*pp_block) and should process and release it. The
106 * module can also process a part of the block. In that case, it should
107 * modify (*pp_block)->p_buffer/i_buffer accordingly and return a valid
108 * output block. The module can also set *pp_block to NULL when the input
109 * block is consumed.
110 *
111 * If pp_block is not NULL but *pp_block is NULL, a previous call of the pf
112 * function has set the *pp_block to NULL. Here, the module can return new
113 * output block for the same, already processed, input block (the
114 * pf_packetize function will be called as long as the module return an
115 * output block).
116 *
117 * When the pf function returns NULL, the next call to this function will
118 * have a new a valid pp_block (if the packetizer is not drained).
119 *
120 * If pp_block is NULL, the packetizer asks the module to drain itself. In
121 * that case, the module has to return all output frames available (the
122 * pf_packetize function will be called as long as the module return an
123 * output block).
124 */
125 block_t * ( * pf_packetize )( decoder_t *, block_t **pp_block );
126 /* */
127 void ( * pf_flush ) ( decoder_t * );
128
129 /* Closed Caption (CEA 608/708) extraction.
130 * If set, it *may* be called after pf_packetize returned data. It should
131 * return CC for the pictures returned by the last pf_packetize call only,
132 * channel bitmaps will be used to known which cc channel are present (but
133 * globaly, not necessary for the current packet. Video decoders should use
134 * the decoder_QueueCc() function to pass closed captions. */
135 block_t * ( * pf_get_cc ) ( decoder_t *, decoder_cc_desc_t * );
136
137 /* Meta data at codec level
138 * The decoder owner set it back to NULL once it has retreived what it needs.
139 * The decoder owner is responsible of its release except when you overwrite it.
140 */
141 vlc_meta_t *p_description;
142
143 /*
144 * Owner fields
145 * XXX You MUST not use them directly.
146 */
147
148 /* Video output callbacks
149 * XXX use decoder_NewPicture */
150 int (*pf_vout_format_update)( decoder_t * );
151 picture_t *(*pf_vout_buffer_new)( decoder_t * );
152
153 /**
154 * Number of extra (ie in addition to the DPB) picture buffers
155 * needed for decoding.
156 */
157 int i_extra_picture_buffers;
158
159 /* Audio output callbacks */
160 int (*pf_aout_format_update)( decoder_t * );
161
162 /* SPU output callbacks
163 * XXX use decoder_NewSubpicture */
164 subpicture_t *(*pf_spu_buffer_new)( decoder_t *, const subpicture_updater_t * );
165
166 /* Input attachments
167 * XXX use decoder_GetInputAttachments */
168 int (*pf_get_attachments)( decoder_t *p_dec, input_attachment_t ***ppp_attachment, int *pi_attachment );
169
170 /* Display date
171 * XXX use decoder_GetDisplayDate */
172 mtime_t (*pf_get_display_date)( decoder_t *, mtime_t );
173
174 /* Display rate
175 * XXX use decoder_GetDisplayRate */
176 int (*pf_get_display_rate)( decoder_t * );
177
178 /* XXX use decoder_QueueVideo or decoder_QueueVideoWithCc */
179 int (*pf_queue_video)( decoder_t *, picture_t * );
180 /* XXX use decoder_QueueAudio */
181 int (*pf_queue_audio)( decoder_t *, block_t * );
182 /* XXX use decoder_QueueCC */
183 int (*pf_queue_cc)( decoder_t *, block_t *, const decoder_cc_desc_t * );
184 /* XXX use decoder_QueueSub */
185 int (*pf_queue_sub)( decoder_t *, subpicture_t *);
186 void *p_queue_ctx;
187
188 /* Private structure for the owner of the decoder */
189 decoder_owner_sys_t *p_owner;
190 };
191
192 /* struct for packetizer get_cc polling/decoder queue_cc
193 * until we have a proper metadata way */
194 struct decoder_cc_desc_t
195 {
196 uint8_t i_608_channels; /* 608 channels bitmap */
197 uint64_t i_708_channels; /* 708 */
198 int i_reorder_depth; /* reorder depth, -1 for no reorder, 0 for old P/B flag based */
199 };
200
201 /**
202 * @}
203 */
204
205 /**
206 * \defgroup encoder Encoder
207 * Audio, video and text encoders
208 * @{
209 */
210
211 struct encoder_t
212 {
213 VLC_COMMON_MEMBERS
214
215 /* Module properties */
216 module_t * p_module;
217 encoder_sys_t * p_sys;
218
219 /* Properties of the input data fed to the encoder */
220 es_format_t fmt_in;
221
222 /* Properties of the output of the encoder */
223 es_format_t fmt_out;
224
225 block_t * ( * pf_encode_video )( encoder_t *, picture_t * );
226 block_t * ( * pf_encode_audio )( encoder_t *, block_t * );
227 block_t * ( * pf_encode_sub )( encoder_t *, subpicture_t * );
228
229 /* Common encoder options */
230 int i_threads; /* Number of threads to use during encoding */
231 int i_iframes; /* One I frame per i_iframes */
232 int i_bframes; /* One B frame per i_bframes */
233 int i_tolerance; /* Bitrate tolerance */
234
235 /* Encoder config */
236 config_chain_t *p_cfg;
237 };
238
239 /**
240 * @}
241 *
242 * \ingroup decoder
243 * @{
244 */
245
246 /**
247 * Updates the video output format.
248 *
249 * This function notifies the video output pipeline of a new video output
250 * format (fmt_out.video). If there was no video output from the decoder so far
251 * or if the video output format has changed, a new video output will be set
252 * up. decoder_NewPicture() can then be used to allocate picture buffers.
253 *
254 * If the format is unchanged, this function has no effects and returns zero.
255 *
256 * \note
257 * This function is not reentrant.
258 *
259 * @return 0 if the video output was set up successfully, -1 otherwise.
260 */
261 VLC_USED
decoder_UpdateVideoFormat(decoder_t * dec)262 static inline int decoder_UpdateVideoFormat( decoder_t *dec )
263 {
264 assert( dec->fmt_in.i_cat == VIDEO_ES );
265 if( dec->fmt_in.i_cat == VIDEO_ES && dec->pf_vout_format_update != NULL )
266 return dec->pf_vout_format_update( dec );
267 else
268 return -1;
269 }
270
271 /**
272 * Allocates an output picture buffer.
273 *
274 * This function pulls an output picture buffer for the decoder from the
275 * buffer pool of the video output. The picture must be released with
276 * picture_Release() when it is no longer referenced by the decoder.
277 *
278 * \note
279 * This function is reentrant. However, decoder_UpdateVideoFormat() cannot be
280 * used concurrently; the caller is responsible for serialization.
281 *
282 * \warning
283 * The behaviour is undefined if decoder_UpdateVideoFormat() was not called or
284 * if the last call returned an error.
285 *
286 * \return a picture buffer on success, NULL on error
287 */
288 VLC_USED
decoder_NewPicture(decoder_t * dec)289 static inline picture_t *decoder_NewPicture( decoder_t *dec )
290 {
291 return dec->pf_vout_buffer_new( dec );
292 }
293
294 /**
295 * Abort any calls of decoder_NewPicture
296 *
297 * If b_abort is true, all pending and futures calls of decoder_NewPicture
298 * will be aborted. This function can be used by asynchronous video decoders
299 * to unblock a thread that is waiting for a picture.
300 */
301 VLC_API void decoder_AbortPictures( decoder_t *dec, bool b_abort );
302
303 /**
304 * This function queues a single picture to the video output.
305 *
306 * \note
307 * The caller doesn't own the picture anymore after this call (even in case of
308 * error).
309 * FIXME: input_DecoderFrameNext won't work if a module use this function.
310 *
311 * \return 0 if the picture is queued, -1 on error
312 */
decoder_QueueVideo(decoder_t * dec,picture_t * p_pic)313 static inline int decoder_QueueVideo( decoder_t *dec, picture_t *p_pic )
314 {
315 assert( p_pic->p_next == NULL );
316 assert( dec->pf_queue_video != NULL );
317 return dec->pf_queue_video( dec, p_pic );
318 }
319
320 /**
321 * This function queues the Closed Captions
322 *
323 * \param dec the decoder object
324 * \param p_cc the closed-caption to queue
325 * \param p_desc decoder_cc_desc_t description structure
326 * \return 0 if queued, -1 on error
327 */
decoder_QueueCc(decoder_t * dec,block_t * p_cc,const decoder_cc_desc_t * p_desc)328 static inline int decoder_QueueCc( decoder_t *dec, block_t *p_cc,
329 const decoder_cc_desc_t *p_desc )
330 {
331 if( dec->pf_queue_cc == NULL )
332 {
333 block_Release( p_cc );
334 return -1;
335 }
336 return dec->pf_queue_cc( dec, p_cc, p_desc );
337 }
338
339 /**
340 * This function queues a single audio block to the audio output.
341 *
342 * \note
343 * The caller doesn't own the audio block anymore after this call (even in case
344 * of error).
345 *
346 * \return 0 if the block is queued, -1 on error
347 */
decoder_QueueAudio(decoder_t * dec,block_t * p_aout_buf)348 static inline int decoder_QueueAudio( decoder_t *dec, block_t *p_aout_buf )
349 {
350 assert( p_aout_buf->p_next == NULL );
351 assert( dec->pf_queue_audio != NULL );
352 return dec->pf_queue_audio( dec, p_aout_buf );
353 }
354
355 /**
356 * This function queues a single subtitle to the video output.
357 *
358 * \note
359 * The caller doesn't own the subtitle anymore after this call (even in case of
360 * error).
361 *
362 * \return 0 if the subtitle is queued, -1 on error
363 */
decoder_QueueSub(decoder_t * dec,subpicture_t * p_spu)364 static inline int decoder_QueueSub( decoder_t *dec, subpicture_t *p_spu )
365 {
366 assert( p_spu->p_next == NULL );
367 assert( dec->pf_queue_sub != NULL );
368 return dec->pf_queue_sub( dec, p_spu );
369 }
370
371 /**
372 * This function notifies the audio output pipeline of a new audio output
373 * format (fmt_out.audio). If there is currently no audio output or if the
374 * audio output format has changed, a new audio output will be set up.
375 * @return 0 if the audio output is working, -1 if not. */
376 VLC_USED
decoder_UpdateAudioFormat(decoder_t * dec)377 static inline int decoder_UpdateAudioFormat( decoder_t *dec )
378 {
379 assert(dec->fmt_in.i_cat == AUDIO_ES);
380 if( dec->fmt_in.i_cat == AUDIO_ES && dec->pf_aout_format_update != NULL )
381 return dec->pf_aout_format_update( dec );
382 else
383 return -1;
384 }
385
386 /**
387 * This function will return a new audio buffer usable by a decoder as an
388 * output buffer. It must be released with block_Release() or returned it to
389 * the caller as a decoder_QueueAudio parameter.
390 */
391 VLC_API block_t * decoder_NewAudioBuffer( decoder_t *, int i_nb_samples ) VLC_USED;
392
393 /**
394 * This function will return a new subpicture usable by a decoder as an output
395 * buffer. You have to release it using subpicture_Delete() or by returning
396 * it to the caller as a decoder_QueueSub parameter.
397 */
398 VLC_API subpicture_t * decoder_NewSubpicture( decoder_t *, const subpicture_updater_t * ) VLC_USED;
399
400 /**
401 * This function gives all input attachments at once.
402 *
403 * You MUST release the returned values
404 */
405 VLC_API int decoder_GetInputAttachments( decoder_t *, input_attachment_t ***ppp_attachment, int *pi_attachment );
406
407 /**
408 * This function converts a decoder timestamp into a display date comparable
409 * to mdate().
410 * You MUST use it *only* for gathering statistics about speed.
411 */
412 VLC_API mtime_t decoder_GetDisplayDate( decoder_t *, mtime_t ) VLC_USED;
413
414 /**
415 * This function returns the current input rate.
416 * You MUST use it *only* for gathering statistics about speed.
417 */
418 VLC_API int decoder_GetDisplayRate( decoder_t * ) VLC_USED;
419
420 /** @} */
421 /** @} */
422 #endif /* _VLC_CODEC_H */
423