include/vlc_codec.h

   1 /*****************************************************************************
   2  * vlc_codec.h: Definition of the decoder and encoder structures
   3  *****************************************************************************
   4  * Copyright (C) 1999-2003 VLC authors and VideoLAN
   5  *
   6  * Authors: Gildas Bazin <gbazin@netcourrier.com>
   7  *
   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.
  12  *
  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.
  17  *
  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  *****************************************************************************/
  22
  23 #ifndef VLC_CODEC_H
  24 #define VLC_CODEC_H 1
  25
  26 #include <assert.h>
  27
  28 #include <vlc_block.h>
  29 #include <vlc_es.h>
  30 #include <vlc_vout_window.h>
  31 #include <vlc_picture.h>
  32 #include <vlc_subpicture.h>
  33
  34 /**
  35  * \defgroup decoder Decoder
  36  * \ingroup input
  37  * Audio, video and text decoders
  38  * @{
  39  *
  40  * \file
  41  * Decoder and encoder modules interface
  42  */
  43
  44 typedef struct decoder_cc_desc_t decoder_cc_desc_t;
  45
  46 struct decoder_owner_callbacks
  47 {
  48     union
  49     {
  50         struct
  51         {
  52             int         (*format_update)( decoder_t * );
  53
  54             /* cf. decoder_NewPicture, can be called from any decoder thread */
  55             picture_t*  (*buffer_new)( decoder_t * );
  56             /* cf.decoder_QueueVideo */
  57             void        (*queue)( decoder_t *, picture_t * );
  58             /* cf.decoder_QueueCC */
  59             void        (*queue_cc)( decoder_t *, block_t *,
  60                                      const decoder_cc_desc_t * );
  61
  62             /* Display date
  63              * cf. decoder_GetDisplayDate */
  64             vlc_tick_t  (*get_display_date)( decoder_t *, vlc_tick_t, vlc_tick_t );
  65             /* Display rate
  66              * cf. decoder_GetDisplayRate */
  67             float       (*get_display_rate)( decoder_t * );
  68         } video;
  69         struct
  70         {
  71             int     (*format_update)( decoder_t * );
  72
  73             /* cf.decoder_QueueAudio */
  74             void    (*queue)( decoder_t *, block_t * );
  75         } audio;
  76         struct
  77         {
  78             /* cf. decoder_NewSubpicture */
  79             subpicture_t*   (*buffer_new)( decoder_t *,
  80                                            const subpicture_updater_t * );
  81
  82             /* cf.decoder_QueueSub */
  83             void            (*queue)( decoder_t *, subpicture_t *);
  84         } spu;
  85     };
  86
  87     /* Input attachments
  88      * cf. decoder_GetInputAttachments */
  89     int (*get_attachments)( decoder_t *p_dec,
  90                             input_attachment_t ***ppp_attachment,
  91                             int *pi_attachment );
  92 };
  93
  94 /*
  95  * BIG FAT WARNING : the code relies in the first 4 members of filter_t
  96  * and decoder_t to be the same, so if you have anything to add, do it
  97  * at the end of the structure.
  98  */
  99 struct decoder_t
 100 {
 101     struct vlc_object_t obj;
 102
 103     /* Module properties */
 104     module_t *          p_module;
 105     void               *p_sys;
 106
 107     /* Input format ie from demuxer (XXX: a lot of field could be invalid) */
 108     es_format_t         fmt_in;
 109
 110     /* Output format of decoder/packetizer */
 111     es_format_t         fmt_out;
 112
 113     /* Tell the decoder if it is allowed to drop frames */
 114     bool                b_frame_drop_allowed;
 115
 116     /**
 117      * Number of extra (ie in addition to the DPB) picture buffers
 118      * needed for decoding.
 119      */
 120     int                 i_extra_picture_buffers;
 121
 122     union
 123     {
 124 #       define VLCDEC_SUCCESS   VLC_SUCCESS
 125 #       define VLCDEC_ECRITICAL VLC_EGENERIC
 126 #       define VLCDEC_RELOAD    (-100)
 127         /* This function is called to decode one packetized block.
 128          *
 129          * The module implementation will own the input block (p_block) and should
 130          * process and release it. Depending of the decoder type, the module should
 131          * send output frames/blocks via decoder_QueueVideo(), decoder_QueueAudio()
 132          * or decoder_QueueSub().
 133          *
 134          * If p_block is NULL, the decoder asks the module to drain itself. The
 135          * module should return all available output frames/block via the queue
 136          * functions.
 137          *
 138          * Return values can be:
 139          *  VLCDEC_SUCCESS: pf_decode will be called again
 140          *  VLCDEC_ECRITICAL: in case of critical error, pf_decode won't be called
 141          *  again.
 142          *  VLCDEC_RELOAD: Request that the decoder should be reloaded. The current
 143          *  module will be unloaded. Reloading a module may cause a loss of frames.
 144          *  When returning this status, the implementation shouldn't release or
 145          *  modify the p_block in argument (The same p_block will be feed to the
 146          *  next decoder module).
 147          */
 148         int             ( * pf_decode )   ( decoder_t *, block_t *p_block );
 149
 150         /* This function is called in a loop with the same pp_block argument until
 151          * it returns NULL. This allows a module implementation to return more than
 152          * one output blocks for one input block.
 153          *
 154          * pp_block or *pp_block can be NULL.
 155          *
 156          * If pp_block and *pp_block are not NULL, the module implementation will
 157          * own the input block (*pp_block) and should process and release it. The
 158          * module can also process a part of the block. In that case, it should
 159          * modify (*pp_block)->p_buffer/i_buffer accordingly and return a valid
 160          * output block. The module can also set *pp_block to NULL when the input
 161          * block is consumed.
 162          *
 163          * If pp_block is not NULL but *pp_block is NULL, a previous call of the pf
 164          * function has set the *pp_block to NULL. Here, the module can return new
 165          * output block for the same, already processed, input block (the
 166          * pf_packetize function will be called as long as the module return an
 167          * output block).
 168          *
 169          * When the pf function returns NULL, the next call to this function will
 170          * have a new a valid pp_block (if the packetizer is not drained).
 171          *
 172          * If pp_block is NULL, the packetizer asks the module to drain itself. In
 173          * that case, the module has to return all output frames available (the
 174          * pf_packetize function will be called as long as the module return an
 175          * output block).
 176          */
 177         block_t *       ( * pf_packetize )( decoder_t *, block_t **pp_block );
 178     };
 179
 180     /* */
 181     void                ( * pf_flush ) ( decoder_t * );
 182
 183     /* Closed Caption (CEA 608/708) extraction.
 184      * If set, it *may* be called after pf_packetize returned data. It should
 185      * return CC for the pictures returned by the last pf_packetize call only,
 186      * channel bitmaps will be used to known which cc channel are present (but
 187      * globaly, not necessary for the current packet. Video decoders should use
 188      * the decoder_QueueCc() function to pass closed captions. */
 189     block_t *           ( * pf_get_cc )      ( decoder_t *, decoder_cc_desc_t * );
 190
 191     /* Meta data at codec level
 192      *  The decoder owner set it back to NULL once it has retreived what it needs.
 193      *  The decoder owner is responsible of its release except when you overwrite it.
 194      */
 195     vlc_meta_t          *p_description;
 196
 197     /* Private structure for the owner of the decoder */
 198     const struct decoder_owner_callbacks *cbs;
 199 };
 200
 201 /* struct for packetizer get_cc polling/decoder queue_cc
 202  * until we have a proper metadata way */
 203 struct decoder_cc_desc_t
 204 {
 205     uint8_t i_608_channels;  /* 608 channels bitmap */
 206     uint64_t i_708_channels; /* 708 */
 207     int i_reorder_depth;     /* reorder depth, -1 for no reorder, 0 for old P/B flag based */
 208 };
 209
 210 /**
 211  * @}
 212  */
 213
 214 /**
 215  * \defgroup encoder Encoder
 216  * \ingroup sout
 217  * Audio, video and text encoders
 218  * @{
 219  */
 220
 221 struct encoder_t
 222 {
 223     struct vlc_object_t obj;
 224
 225     /* Module properties */
 226     module_t *          p_module;
 227     void               *p_sys;
 228
 229     /* Properties of the input data fed to the encoder */
 230     es_format_t         fmt_in;
 231
 232     /* Properties of the output of the encoder */
 233     es_format_t         fmt_out;
 234
 235     block_t *           ( * pf_encode_video )( encoder_t *, picture_t * );
 236     block_t *           ( * pf_encode_audio )( encoder_t *, block_t * );
 237     block_t *           ( * pf_encode_sub )( encoder_t *, subpicture_t * );
 238
 239     /* Common encoder options */
 240     int i_threads;               /* Number of threads to use during encoding */
 241     int i_iframes;               /* One I frame per i_iframes */
 242     int i_bframes;               /* One B frame per i_bframes */
 243     int i_tolerance;             /* Bitrate tolerance */
 244
 245     /* Encoder config */
 246     config_chain_t *p_cfg;
 247 };
 248
 249 /**
 250  * @}
 251  *
 252  * \ingroup decoder
 253  * @{
 254  */
 255
 256 /**
 257  * Updates the video output format.
 258  *
 259  * This function notifies the video output pipeline of a new video output
 260  * format (fmt_out.video). If there was no video output from the decoder so far
 261  * or if the video output format has changed, a new video output will be set
 262  * up. decoder_NewPicture() can then be used to allocate picture buffers.
 263  *
 264  * If the format is unchanged, this function has no effects and returns zero.
 265  *
 266  * \note
 267  * This function is not reentrant.
 268  *
 269  * @return 0 if the video output was set up successfully, -1 otherwise.
 270  */
 271 VLC_API int decoder_UpdateVideoFormat( decoder_t *dec );
 272
 273 /**
 274  * Allocates an output picture buffer.
 275  *
 276  * This function pulls an output picture buffer for the decoder from the
 277  * buffer pool of the video output. The picture must be released with
 278  * picture_Release() when it is no longer referenced by the decoder.
 279  *
 280  * \note
 281  * This function is reentrant. However, decoder_UpdateVideoFormat() cannot be
 282  * used concurrently; the caller is responsible for serialization.
 283  *
 284  * \warning
 285  * The behaviour is undefined if decoder_UpdateVideoFormat() was not called or
 286  * if the last call returned an error.
 287  *
 288  * \return a picture buffer on success, NULL on error
 289  */
 290 VLC_API picture_t *decoder_NewPicture( decoder_t *dec );
 291
 292 /**
 293  * Abort any calls of decoder_NewPicture
 294  *
 295  * If b_abort is true, all pending and futures calls of decoder_NewPicture
 296  * will be aborted. This function can be used by asynchronous video decoders
 297  * to unblock a thread that is waiting for a picture.
 298  */
 299 VLC_API void decoder_AbortPictures( decoder_t *dec, bool b_abort );
 300
 301 /**
 302  * Initialize a decoder structure before creating the decoder.
 303  *
 304  * To be used by decoder owners.
 305  * By default frame drop is not allowed.
 306  */
 307 VLC_API void decoder_Init( decoder_t *dec, const es_format_t * );
 308
 309 /**
 310  * Destroy a decoder and reset the structure.
 311  *
 312  * To be used by decoder owners.
 313  */
 314 VLC_API void decoder_Destroy( decoder_t *p_dec );
 315
 316 /**
 317  * Unload a decoder module and reset the input/output formats.
 318  *
 319  * To be used by decoder owners.
 320  */
 321 VLC_API void decoder_Clean( decoder_t *p_dec );
 322
 323 /**
 324  * This function queues a single picture to the video output.
 325  *
 326  * \note
 327  * The caller doesn't own the picture anymore after this call (even in case of
 328  * error).
 329  * FIXME: input_DecoderFrameNext won't work if a module use this function.
 330  */
 331 static inline void decoder_QueueVideo( decoder_t *dec, picture_t *p_pic )
 332 {
 333     vlc_assert( dec->fmt_in.i_cat == VIDEO_ES && dec->cbs != NULL );
 334     vlc_assert( p_pic->p_next == NULL );
 335     vlc_assert( dec->cbs->video.queue != NULL );
 336     dec->cbs->video.queue( dec, p_pic );
 337 }
 338
 339 /**
 340  * This function queues the Closed Captions
 341  *
 342  * \param dec the decoder object
 343  * \param p_cc the closed-caption to queue
 344  * \param p_desc decoder_cc_desc_t description structure
 345  */
 346 static inline void decoder_QueueCc( decoder_t *dec, block_t *p_cc,
 347                                    const decoder_cc_desc_t *p_desc )
 348 {
 349     vlc_assert( dec->fmt_in.i_cat == VIDEO_ES && dec->cbs != NULL );
 350
 351     if( dec->cbs->video.queue_cc == NULL )
 352         block_Release( p_cc );
 353     else
 354         dec->cbs->video.queue_cc( dec, p_cc, p_desc );
 355 }
 356
 357 /**
 358  * This function queues a single audio block to the audio output.
 359  *
 360  * \note
 361  * The caller doesn't own the audio block anymore after this call (even in case
 362  * of error).
 363  */
 364 static inline void decoder_QueueAudio( decoder_t *dec, block_t *p_aout_buf )
 365 {
 366     vlc_assert( dec->fmt_in.i_cat == AUDIO_ES && dec->cbs != NULL );
 367     vlc_assert( p_aout_buf->p_next == NULL );
 368     vlc_assert( dec->cbs->audio.queue != NULL );
 369     dec->cbs->audio.queue( dec, p_aout_buf );
 370 }
 371
 372 /**
 373  * This function queues a single subtitle to the video output.
 374  *
 375  * \note
 376  * The caller doesn't own the subtitle anymore after this call (even in case of
 377  * error).
 378  */
 379 static inline void decoder_QueueSub( decoder_t *dec, subpicture_t *p_spu )
 380 {
 381     vlc_assert( dec->fmt_in.i_cat == SPU_ES && dec->cbs != NULL );
 382     vlc_assert( p_spu->p_next == NULL );
 383     vlc_assert( dec->cbs->spu.queue != NULL );
 384     dec->cbs->spu.queue( dec, p_spu );
 385 }
 386
 387 /**
 388  * This function notifies the audio output pipeline of a new audio output
 389  * format (fmt_out.audio). If there is currently no audio output or if the
 390  * audio output format has changed, a new audio output will be set up.
 391  * @return 0 if the audio output is working, -1 if not. */
 392 VLC_USED
 393 static inline int decoder_UpdateAudioFormat( decoder_t *dec )
 394 {
 395     vlc_assert( dec->fmt_in.i_cat == AUDIO_ES && dec->cbs != NULL );
 396
 397     if( dec->fmt_in.i_cat == AUDIO_ES && dec->cbs->audio.format_update != NULL )
 398         return dec->cbs->audio.format_update( dec );
 399     else
 400         return -1;
 401 }
 402
 403 /**
 404  * This function will return a new audio buffer usable by a decoder as an
 405  * output buffer. It must be released with block_Release() or returned it to
 406  * the caller as a decoder_QueueAudio parameter.
 407  */
 408 VLC_API block_t * decoder_NewAudioBuffer( decoder_t *, int i_nb_samples ) VLC_USED;
 409
 410 /**
 411  * This function will return a new subpicture usable by a decoder as an output
 412  * buffer. You have to release it using subpicture_Delete() or by returning
 413  * it to the caller as a decoder_QueueSub parameter.
 414  */
 415 VLC_USED
 416 static inline subpicture_t *decoder_NewSubpicture( decoder_t *dec,
 417                                                    const subpicture_updater_t *p_dyn )
 418 {
 419     vlc_assert( dec->fmt_in.i_cat == SPU_ES && dec->cbs != NULL );
 420
 421     subpicture_t *p_subpicture = dec->cbs->spu.buffer_new( dec, p_dyn );
 422     if( !p_subpicture )
 423         msg_Warn( dec, "can't get output subpicture" );
 424     return p_subpicture;
 425 }
 426
 427 /**
 428  * This function gives all input attachments at once.
 429  *
 430  * You MUST release the returned values
 431  */
 432 static inline int decoder_GetInputAttachments( decoder_t *dec,
 433                                                input_attachment_t ***ppp_attachment,
 434                                                int *pi_attachment )
 435 {
 436     vlc_assert( dec->cbs != NULL );
 437
 438     if( !dec->cbs->get_attachments )
 439         return VLC_EGENERIC;
 440
 441     return dec->cbs->get_attachments( dec, ppp_attachment, pi_attachment );
 442 }
 443
 444 /**
 445  * This function converts a decoder timestamp into a display date comparable
 446  * to vlc_tick_now().
 447  * You MUST use it *only* for gathering statistics about speed.
 448  */
 449 VLC_USED
 450 static inline vlc_tick_t decoder_GetDisplayDate( decoder_t *dec,
 451                                                  vlc_tick_t system_now,
 452                                                  vlc_tick_t i_ts )
 453 {
 454     vlc_assert( dec->fmt_in.i_cat == VIDEO_ES && dec->cbs != NULL );
 455
 456     if( !dec->cbs->video.get_display_date )
 457         return VLC_TICK_INVALID;
 458
 459     return dec->cbs->video.get_display_date( dec, system_now, i_ts );
 460 }
 461
 462 /**
 463  * This function returns the current input rate.
 464  * You MUST use it *only* for gathering statistics about speed.
 465  */
 466 VLC_USED
 467 static inline float decoder_GetDisplayRate( decoder_t *dec )
 468 {
 469     vlc_assert( dec->fmt_in.i_cat == VIDEO_ES && dec->cbs != NULL );
 470
 471     if( !dec->cbs->video.get_display_rate )
 472         return 1.f;
 473
 474     return dec->cbs->video.get_display_rate( dec );
 475 }
 476
 477 /** @} */
 478
 479 /**
 480  * \defgroup decoder_device Decoder hardware device
 481  * \ingroup input
 482  * @{
 483  */
 484
 485 /** Decoder device type */
 486 enum vlc_decoder_device_type
 487 {
 488     VLC_DECODER_DEVICE_NONE,
 489     VLC_DECODER_DEVICE_VAAPI,
 490     VLC_DECODER_DEVICE_VDPAU,
 491     VLC_DECODER_DEVICE_DXVA2,
 492     VLC_DECODER_DEVICE_D3D11VA,
 493     VLC_DECODER_DEVICE_AWINDOW,
 494 };
 495
 496 /**
 497  * Decoder context struct
 498  */
 499 typedef struct vlc_decoder_device
 500 {
 501     struct vlc_object_t obj;
 502
 503     /** Private context that could be used by the "decoder device" module
 504      * implementation */
 505     void *sys;
 506
 507     /** Must be set from the "decoder device" module open entry point */
 508     enum vlc_decoder_device_type type;
 509
 510     /**
 511      * Could be set from the "decoder device" module open entry point and will
 512      * be used by hardware decoder modules.
 513      *
 514      * The type of pointer will depend of the type:
 515      * VAAPI: VADisplay
 516      * VDPAU: vdp_t *
 517      */
 518     void *opaque;
 519 } vlc_decoder_device;
 520
 521 /**
 522  * "decoder device" module open entry point
 523  *
 524  * @param device the "decoder device" structure to initialize
 525  * @param window pointer to a window to help device initialization (can be NULL)
 526  **/
 527 typedef int (*vlc_decoder_device_Open)(vlc_decoder_device *device,
 528                                         vout_window_t *window);
 529 /** "decoder device" module close entry point */
 530 typedef void (*vlc_decoder_device_Close)(vlc_decoder_device *device);
 531
 532 /**
 533  * Create a decoder device from a window
 534  *
 535  * This function will be hidden in the future. It is now used by opengl vout
 536  * module as a transition.
 537  */
 538 VLC_USED vlc_decoder_device *
 539 vlc_decoder_device_Create(vout_window_t *window);
 540
 541 /**
 542  * Hold a decoder device
 543  */
 544 VLC_API vlc_decoder_device *
 545 vlc_decoder_device_Hold(vlc_decoder_device *device);
 546
 547 /**
 548  * Release a decoder device
 549  */
 550 VLC_API void
 551 vlc_decoder_device_Release(vlc_decoder_device *device);
 552
 553 /** @} */
 554 #endif /* _VLC_CODEC_H */