1 /*****************************************************************************
2 * vlc_codec.h: Definition of the decoder and encoder structures
3 *****************************************************************************
4 * Copyright (C) 1999-2003 VLC authors and VideoLAN
6 * Authors: Gildas Bazin <gbazin@netcourrier.com>
8 * This program is free software; you can redistribute it and/or modify it
9 * under the terms of the GNU Lesser General Public License as published by
10 * the Free Software Foundation; either version 2.1 of the License, or
11 * (at your option) any later version.
13 * This program is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 * GNU Lesser General Public License for more details.
18 * You should have received a copy of the GNU Lesser General Public License
19 * along with this program; if not, write to the Free Software Foundation,
20 * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
21 *****************************************************************************/
28 #include <vlc_block.h>
30 #include <vlc_vout_window.h>
31 #include <vlc_picture.h>
32 #include <vlc_subpicture.h>
35 * \defgroup decoder Decoder
37 * Audio, video and text decoders
41 * Decoder and encoder modules interface
44 typedef struct decoder_cc_desc_t decoder_cc_desc_t
;
46 struct decoder_owner_callbacks
52 vlc_decoder_device
* (*get_device
)( decoder_t
* );
53 int (*format_update
)( decoder_t
*, vlc_video_context
* );
55 /* cf. decoder_NewPicture, can be called from any decoder thread */
56 picture_t
* (*buffer_new
)( decoder_t
* );
57 /* cf. decoder_AbortPictures */
58 void (*abort_pictures
)( decoder_t
*, bool b_abort
);
59 /* cf.decoder_QueueVideo */
60 void (*queue
)( decoder_t
*, picture_t
* );
61 /* cf.decoder_QueueCC */
62 void (*queue_cc
)( decoder_t
*, block_t
*,
63 const decoder_cc_desc_t
* );
66 * cf. decoder_GetDisplayDate */
67 vlc_tick_t (*get_display_date
)( decoder_t
*, vlc_tick_t
, vlc_tick_t
);
69 * cf. decoder_GetDisplayRate */
70 float (*get_display_rate
)( decoder_t
* );
74 int (*format_update
)( decoder_t
* );
76 /* cf.decoder_QueueAudio */
77 void (*queue
)( decoder_t
*, block_t
* );
81 /* cf. decoder_NewSubpicture */
82 subpicture_t
* (*buffer_new
)( decoder_t
*,
83 const subpicture_updater_t
* );
85 /* cf.decoder_QueueSub */
86 void (*queue
)( decoder_t
*, subpicture_t
*);
91 * cf. decoder_GetInputAttachments */
92 int (*get_attachments
)( decoder_t
*p_dec
,
93 input_attachment_t
***ppp_attachment
,
98 * BIG FAT WARNING : the code relies in the first 4 members of filter_t
99 * and decoder_t to be the same, so if you have anything to add, do it
100 * at the end of the structure.
104 struct vlc_object_t obj
;
106 /* Module properties */
110 /* Input format ie from demuxer (XXX: a lot of field could be invalid) */
113 /* Output format of decoder/packetizer */
116 /* Tell the decoder if it is allowed to drop frames */
117 bool b_frame_drop_allowed
;
120 * Number of extra (ie in addition to the DPB) picture buffers
121 * needed for decoding.
123 int i_extra_picture_buffers
;
127 # define VLCDEC_SUCCESS VLC_SUCCESS
128 # define VLCDEC_ECRITICAL VLC_EGENERIC
129 # define VLCDEC_RELOAD (-100)
130 /* This function is called to decode one packetized block.
132 * The module implementation will own the input block (p_block) and should
133 * process and release it. Depending of the decoder type, the module should
134 * send output frames/blocks via decoder_QueueVideo(), decoder_QueueAudio()
135 * or decoder_QueueSub().
137 * If p_block is NULL, the decoder asks the module to drain itself. The
138 * module should return all available output frames/block via the queue
141 * Return values can be:
142 * VLCDEC_SUCCESS: pf_decode will be called again
143 * VLCDEC_ECRITICAL: in case of critical error, pf_decode won't be called
145 * VLCDEC_RELOAD: Request that the decoder should be reloaded. The current
146 * module will be unloaded. Reloading a module may cause a loss of frames.
147 * When returning this status, the implementation shouldn't release or
148 * modify the p_block in argument (The same p_block will be feed to the
149 * next decoder module).
151 int ( * pf_decode
) ( decoder_t
*, block_t
*p_block
);
153 /* This function is called in a loop with the same pp_block argument until
154 * it returns NULL. This allows a module implementation to return more than
155 * one output blocks for one input block.
157 * pp_block or *pp_block can be NULL.
159 * If pp_block and *pp_block are not NULL, the module implementation will
160 * own the input block (*pp_block) and should process and release it. The
161 * module can also process a part of the block. In that case, it should
162 * modify (*pp_block)->p_buffer/i_buffer accordingly and return a valid
163 * output block. The module can also set *pp_block to NULL when the input
166 * If pp_block is not NULL but *pp_block is NULL, a previous call of the pf
167 * function has set the *pp_block to NULL. Here, the module can return new
168 * output block for the same, already processed, input block (the
169 * pf_packetize function will be called as long as the module return an
172 * When the pf function returns NULL, the next call to this function will
173 * have a new a valid pp_block (if the packetizer is not drained).
175 * If pp_block is NULL, the packetizer asks the module to drain itself. In
176 * that case, the module has to return all output frames available (the
177 * pf_packetize function will be called as long as the module return an
180 block_t
* ( * pf_packetize
)( decoder_t
*, block_t
**pp_block
);
184 void ( * pf_flush
) ( decoder_t
* );
186 /* Closed Caption (CEA 608/708) extraction.
187 * If set, it *may* be called after pf_packetize returned data. It should
188 * return CC for the pictures returned by the last pf_packetize call only,
189 * channel bitmaps will be used to known which cc channel are present (but
190 * globaly, not necessary for the current packet. Video decoders should use
191 * the decoder_QueueCc() function to pass closed captions. */
192 block_t
* ( * pf_get_cc
) ( decoder_t
*, decoder_cc_desc_t
* );
194 /* Meta data at codec level
195 * The decoder owner set it back to NULL once it has retreived what it needs.
196 * The decoder owner is responsible of its release except when you overwrite it.
198 vlc_meta_t
*p_description
;
200 /* Private structure for the owner of the decoder */
201 const struct decoder_owner_callbacks
*cbs
;
204 /* struct for packetizer get_cc polling/decoder queue_cc
205 * until we have a proper metadata way */
206 struct decoder_cc_desc_t
208 uint8_t i_608_channels
; /* 608 channels bitmap */
209 uint64_t i_708_channels
; /* 708 */
210 int i_reorder_depth
; /* reorder depth, -1 for no reorder, 0 for old P/B flag based */
217 struct encoder_owner_callbacks
221 vlc_decoder_device
*(*get_device
)( encoder_t
* );
226 * Creates/Updates the output decoder device.
229 * This function is not reentrant.
231 * @return the held decoder device, NULL if none should be used
233 VLC_API vlc_decoder_device
*vlc_encoder_GetDecoderDevice( encoder_t
* );
237 * \defgroup encoder Encoder
239 * Audio, video and text encoders
245 struct vlc_object_t obj
;
247 /* Module properties */
251 /* Properties of the input data fed to the encoder */
253 vlc_video_context
*vctx_in
; /* for video */
255 /* Properties of the output of the encoder */
258 block_t
* ( * pf_encode_video
)( encoder_t
*, picture_t
* );
259 block_t
* ( * pf_encode_audio
)( encoder_t
*, block_t
* );
260 block_t
* ( * pf_encode_sub
)( encoder_t
*, subpicture_t
* );
262 /* Common encoder options */
263 int i_threads
; /* Number of threads to use during encoding */
264 int i_iframes
; /* One I frame per i_iframes */
265 int i_bframes
; /* One B frame per i_bframes */
266 int i_tolerance
; /* Bitrate tolerance */
269 config_chain_t
*p_cfg
;
271 /* Private structure for the owner of the encoder */
272 const struct encoder_owner_callbacks
*cbs
;
283 * Creates/Updates the output decoder device.
285 * This function notifies the video output pipeline of a new video output
286 * format (fmt_out.video). If there was no decoder device so far or a new
287 * decoder device is required, a new decoder device will be set up.
288 * decoder_UpdateVideoOutput() can then be used.
290 * If the format is unchanged, this function has no effects and returns zero.
292 * \param dec the decoder object
295 * This function is not reentrant.
297 * @return the received of the held decoder device, NULL not to get one
299 static inline vlc_decoder_device
* decoder_GetDecoderDevice( decoder_t
*dec
)
301 vlc_assert( dec
->fmt_in
.i_cat
== VIDEO_ES
&& dec
->cbs
!= NULL
);
302 if ( unlikely(dec
->fmt_in
.i_cat
!= VIDEO_ES
|| dec
->cbs
== NULL
) )
305 vlc_assert(dec
->cbs
->video
.get_device
!= NULL
);
306 return dec
->cbs
->video
.get_device( dec
);
310 * Creates/Updates the rest of the video output pipeline.
312 * After a call to decoder_GetDecoderDevice() this function notifies the
313 * video output pipeline of a new video output format (fmt_out.video). If there
314 * was no video output from the decoder so far, a new decoder video output will
315 * be set up. decoder_NewPicture() can then be used to allocate picture buffers.
317 * If the format is unchanged, this function has no effects and returns zero.
320 * This function is not reentrant.
322 * @return 0 if the video output was set up successfully, -1 otherwise.
324 VLC_API
int decoder_UpdateVideoOutput( decoder_t
*dec
, vlc_video_context
*vctx_out
);
327 * Updates the video output format.
329 * This function notifies the video output pipeline of a new video output
330 * format (fmt_out.video). If there was no video output from the decoder so far
331 * or if the video output format has changed, a new video output will be set
332 * up. decoder_NewPicture() can then be used to allocate picture buffers.
334 * If the format is unchanged, this function has no effects and returns zero.
337 * This function is not reentrant.
339 * @return 0 if the video output was set up successfully, -1 otherwise.
341 VLC_API
int decoder_UpdateVideoFormat( decoder_t
*dec
);
344 * Allocates an output picture buffer.
346 * This function pulls an output picture buffer for the decoder from the
347 * buffer pool of the video output. The picture must be released with
348 * picture_Release() when it is no longer referenced by the decoder.
351 * This function is reentrant. However, decoder_UpdateVideoFormat() cannot be
352 * used concurrently; the caller is responsible for serialization.
355 * The behaviour is undefined if decoder_UpdateVideoFormat() was not called or
356 * if the last call returned an error.
358 * \return a picture buffer on success, NULL on error
360 VLC_API picture_t
*decoder_NewPicture( decoder_t
*dec
);
363 * Abort any calls of decoder_NewPicture
365 * If b_abort is true, all pending and futures calls of decoder_NewPicture
366 * will be aborted. This function can be used by asynchronous video decoders
367 * to unblock a thread that is waiting for a picture.
369 VLC_API
void decoder_AbortPictures( decoder_t
*dec
, bool b_abort
);
372 * Initialize a decoder structure before creating the decoder.
374 * To be used by decoder owners.
375 * By default frame drop is not allowed.
377 VLC_API
void decoder_Init( decoder_t
*dec
, const es_format_t
* );
380 * Destroy a decoder and reset the structure.
382 * To be used by decoder owners.
384 VLC_API
void decoder_Destroy( decoder_t
*p_dec
);
387 * Unload a decoder module and reset the input/output formats.
389 * To be used by decoder owners.
391 VLC_API
void decoder_Clean( decoder_t
*p_dec
);
394 * This function queues a single picture to the video output.
397 * The caller doesn't own the picture anymore after this call (even in case of
399 * FIXME: input_DecoderFrameNext won't work if a module use this function.
401 static inline void decoder_QueueVideo( decoder_t
*dec
, picture_t
*p_pic
)
403 vlc_assert( dec
->fmt_in
.i_cat
== VIDEO_ES
&& dec
->cbs
!= NULL
);
404 vlc_assert( p_pic
->p_next
== NULL
);
405 vlc_assert( dec
->cbs
->video
.queue
!= NULL
);
406 dec
->cbs
->video
.queue( dec
, p_pic
);
410 * This function queues the Closed Captions
412 * \param dec the decoder object
413 * \param p_cc the closed-caption to queue
414 * \param p_desc decoder_cc_desc_t description structure
416 static inline void decoder_QueueCc( decoder_t
*dec
, block_t
*p_cc
,
417 const decoder_cc_desc_t
*p_desc
)
419 vlc_assert( dec
->fmt_in
.i_cat
== VIDEO_ES
&& dec
->cbs
!= NULL
);
421 if( dec
->cbs
->video
.queue_cc
== NULL
)
422 block_Release( p_cc
);
424 dec
->cbs
->video
.queue_cc( dec
, p_cc
, p_desc
);
428 * This function queues a single audio block to the audio output.
431 * The caller doesn't own the audio block anymore after this call (even in case
434 static inline void decoder_QueueAudio( decoder_t
*dec
, block_t
*p_aout_buf
)
436 vlc_assert( dec
->fmt_in
.i_cat
== AUDIO_ES
&& dec
->cbs
!= NULL
);
437 vlc_assert( p_aout_buf
->p_next
== NULL
);
438 vlc_assert( dec
->cbs
->audio
.queue
!= NULL
);
439 dec
->cbs
->audio
.queue( dec
, p_aout_buf
);
443 * This function queues a single subtitle to the video output.
446 * The caller doesn't own the subtitle anymore after this call (even in case of
449 static inline void decoder_QueueSub( decoder_t
*dec
, subpicture_t
*p_spu
)
451 vlc_assert( dec
->fmt_in
.i_cat
== SPU_ES
&& dec
->cbs
!= NULL
);
452 vlc_assert( p_spu
->p_next
== NULL
);
453 vlc_assert( dec
->cbs
->spu
.queue
!= NULL
);
454 dec
->cbs
->spu
.queue( dec
, p_spu
);
458 * This function notifies the audio output pipeline of a new audio output
459 * format (fmt_out.audio). If there is currently no audio output or if the
460 * audio output format has changed, a new audio output will be set up.
461 * @return 0 if the audio output is working, -1 if not. */
463 static inline int decoder_UpdateAudioFormat( decoder_t
*dec
)
465 vlc_assert( dec
->fmt_in
.i_cat
== AUDIO_ES
&& dec
->cbs
!= NULL
);
467 if( dec
->fmt_in
.i_cat
== AUDIO_ES
&& dec
->cbs
->audio
.format_update
!= NULL
)
468 return dec
->cbs
->audio
.format_update( dec
);
474 * This function will return a new audio buffer usable by a decoder as an
475 * output buffer. It must be released with block_Release() or returned it to
476 * the caller as a decoder_QueueAudio parameter.
478 VLC_API block_t
* decoder_NewAudioBuffer( decoder_t
*, int i_nb_samples
) VLC_USED
;
481 * This function will return a new subpicture usable by a decoder as an output
482 * buffer. You have to release it using subpicture_Delete() or by returning
483 * it to the caller as a decoder_QueueSub parameter.
486 static inline subpicture_t
*decoder_NewSubpicture( decoder_t
*dec
,
487 const subpicture_updater_t
*p_dyn
)
489 vlc_assert( dec
->fmt_in
.i_cat
== SPU_ES
&& dec
->cbs
!= NULL
);
491 subpicture_t
*p_subpicture
= dec
->cbs
->spu
.buffer_new( dec
, p_dyn
);
493 msg_Warn( dec
, "can't get output subpicture" );
498 * This function gives all input attachments at once.
500 * You MUST release the returned values
502 static inline int decoder_GetInputAttachments( decoder_t
*dec
,
503 input_attachment_t
***ppp_attachment
,
506 vlc_assert( dec
->cbs
!= NULL
);
508 if( !dec
->cbs
->get_attachments
)
511 return dec
->cbs
->get_attachments( dec
, ppp_attachment
, pi_attachment
);
515 * This function converts a decoder timestamp into a display date comparable
517 * You MUST use it *only* for gathering statistics about speed.
520 static inline vlc_tick_t
decoder_GetDisplayDate( decoder_t
*dec
,
521 vlc_tick_t system_now
,
524 vlc_assert( dec
->fmt_in
.i_cat
== VIDEO_ES
&& dec
->cbs
!= NULL
);
526 if( !dec
->cbs
->video
.get_display_date
)
527 return VLC_TICK_INVALID
;
529 return dec
->cbs
->video
.get_display_date( dec
, system_now
, i_ts
);
533 * This function returns the current input rate.
534 * You MUST use it *only* for gathering statistics about speed.
537 static inline float decoder_GetDisplayRate( decoder_t
*dec
)
539 vlc_assert( dec
->fmt_in
.i_cat
== VIDEO_ES
&& dec
->cbs
!= NULL
);
541 if( !dec
->cbs
->video
.get_display_rate
)
544 return dec
->cbs
->video
.get_display_rate( dec
);
550 * \defgroup decoder_device Decoder hardware device
555 /** Decoder device type */
556 enum vlc_decoder_device_type
558 VLC_DECODER_DEVICE_VAAPI
,
559 VLC_DECODER_DEVICE_VDPAU
,
560 VLC_DECODER_DEVICE_DXVA2
,
561 VLC_DECODER_DEVICE_D3D11VA
,
562 VLC_DECODER_DEVICE_VIDEOTOOLBOX
,
563 VLC_DECODER_DEVICE_AWINDOW
,
564 VLC_DECODER_DEVICE_NVDEC
,
565 VLC_DECODER_DEVICE_MMAL
,
568 struct vlc_decoder_device_operations
570 void (*close
)(struct vlc_decoder_device
*);
574 * Decoder context struct
576 typedef struct vlc_decoder_device
578 struct vlc_object_t obj
;
580 const struct vlc_decoder_device_operations
*ops
;
582 /** Private context that could be used by the "decoder device" module
586 /** Must be set from the "decoder device" module open entry point */
587 enum vlc_decoder_device_type type
;
590 * Could be set from the "decoder device" module open entry point and will
591 * be used by hardware decoder modules.
593 * The type of pointer will depend of the type:
596 * DXVA2: d3d9_decoder_device_t*
597 * D3D11VA: d3d11_decoder_device_t*
599 * AWindow: android AWindowHandler*
600 * NVDEC: decoder_device_nvdec_t*
604 } vlc_decoder_device
;
607 * "decoder device" module open entry point
609 * @param device the "decoder device" structure to initialize
610 * @param window pointer to a window to help device initialization (can be NULL)
612 typedef int (*vlc_decoder_device_Open
)(vlc_decoder_device
*device
,
613 vout_window_t
*window
);
615 #define set_callback_dec_device(activate, priority) \
617 vlc_decoder_device_Open open__ = activate; \
619 set_callback(activate) \
621 set_capability( "decoder device", priority )
625 * Create a decoder device from a window
627 * This function will be hidden in the future. It is now used by opengl vout
628 * module as a transition.
630 VLC_API vlc_decoder_device
*
631 vlc_decoder_device_Create(vlc_object_t
*, vout_window_t
*window
) VLC_USED
;
634 * Hold a decoder device
636 VLC_API vlc_decoder_device
*
637 vlc_decoder_device_Hold(vlc_decoder_device
*device
);
640 * Release a decoder device
643 vlc_decoder_device_Release(vlc_decoder_device
*device
);
646 #endif /* _VLC_CODEC_H */