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             vlc_decoder_device * (*get_device)( decoder_t * );
  53             int         (*format_update)( decoder_t *, vlc_video_context * );
  54
  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 * );
  64
  65             /* Display date
  66              * cf. decoder_GetDisplayDate */
  67             vlc_tick_t  (*get_display_date)( decoder_t *, vlc_tick_t, vlc_tick_t );
  68             /* Display rate
  69              * cf. decoder_GetDisplayRate */
  70             float       (*get_display_rate)( decoder_t * );
  71         } video;
  72         struct
  73         {
  74             int     (*format_update)( decoder_t * );
  75
  76             /* cf.decoder_QueueAudio */
  77             void    (*queue)( decoder_t *, block_t * );
  78         } audio;
  79         struct
  80         {
  81             /* cf. decoder_NewSubpicture */
  82             subpicture_t*   (*buffer_new)( decoder_t *,
  83                                            const subpicture_updater_t * );
  84
  85             /* cf.decoder_QueueSub */
  86             void            (*queue)( decoder_t *, subpicture_t *);
  87         } spu;
  88     };
  89
  90     /* Input attachments
  91      * cf. decoder_GetInputAttachments */
  92     int (*get_attachments)( decoder_t *p_dec,
  93                             input_attachment_t ***ppp_attachment,
  94                             int *pi_attachment );
  95 };
  96
  97 /*
  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.
 101  */
 102 struct decoder_t
 103 {
 104     struct vlc_object_t obj;
 105
 106     /* Module properties */
 107     module_t *          p_module;
 108     void               *p_sys;
 109
 110     /* Input format ie from demuxer (XXX: a lot of field could be invalid) */
 111     es_format_t         fmt_in;
 112
 113     /* Output format of decoder/packetizer */
 114     es_format_t         fmt_out;
 115
 116     /* Tell the decoder if it is allowed to drop frames */
 117     bool                b_frame_drop_allowed;
 118
 119     /**
 120      * Number of extra (ie in addition to the DPB) picture buffers
 121      * needed for decoding.
 122      */
 123     int                 i_extra_picture_buffers;
 124
 125     union
 126     {
 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.
 131          *
 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().
 136          *
 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
 139          * functions.
 140          *
 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
 144          *  again.
 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).
 150          */
 151         int             ( * pf_decode )   ( decoder_t *, block_t *p_block );
 152
 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.
 156          *
 157          * pp_block or *pp_block can be NULL.
 158          *
 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
 164          * block is consumed.
 165          *
 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
 170          * output block).
 171          *
 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).
 174          *
 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
 178          * output block).
 179          */
 180         block_t *       ( * pf_packetize )( decoder_t *, block_t **pp_block );
 181     };
 182
 183     /* */
 184     void                ( * pf_flush ) ( decoder_t * );
 185
 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 * );
 193
 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.
 197      */
 198     vlc_meta_t          *p_description;
 199
 200     /* Private structure for the owner of the decoder */
 201     const struct decoder_owner_callbacks *cbs;
 202 };
 203
 204 /* struct for packetizer get_cc polling/decoder queue_cc
 205  * until we have a proper metadata way */
 206 struct decoder_cc_desc_t
 207 {
 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 */
 211 };
 212
 213 /**
 214  * @}
 215  */
 216
 217 /**
 218  * \defgroup encoder Encoder
 219  * \ingroup sout
 220  * Audio, video and text encoders
 221  * @{
 222  */
 223
 224 struct encoder_t
 225 {
 226     struct vlc_object_t obj;
 227
 228     /* Module properties */
 229     module_t *          p_module;
 230     void               *p_sys;
 231
 232     /* Properties of the input data fed to the encoder */
 233     es_format_t         fmt_in;
 234
 235     /* Properties of the output of the encoder */
 236     es_format_t         fmt_out;
 237
 238     block_t *           ( * pf_encode_video )( encoder_t *, picture_t * );
 239     block_t *           ( * pf_encode_audio )( encoder_t *, block_t * );
 240     block_t *           ( * pf_encode_sub )( encoder_t *, subpicture_t * );
 241
 242     /* Common encoder options */
 243     int i_threads;               /* Number of threads to use during encoding */
 244     int i_iframes;               /* One I frame per i_iframes */
 245     int i_bframes;               /* One B frame per i_bframes */
 246     int i_tolerance;             /* Bitrate tolerance */
 247
 248     /* Encoder config */
 249     config_chain_t *p_cfg;
 250 };
 251
 252 /**
 253  * @}
 254  *
 255  * \ingroup decoder
 256  * @{
 257  */
 258
 259 /**
 260  * Creates/Updates the output decoder device.
 261  *
 262  * This function notifies the video output pipeline of a new video output
 263  * format (fmt_out.video). If there was no decoder device so far or a new
 264  * decoder device is required, a new decoder device will be set up.
 265  * decoder_UpdateVideoOutput() can then be used.
 266  *
 267  * If the format is unchanged, this function has no effects and returns zero.
 268  *
 269  * \param dec the decoder object
 270  *
 271  * \note
 272  * This function is not reentrant.
 273  *
 274  * @return the received of the held decoder device, NULL not to get one
 275  */
 276 static inline vlc_decoder_device * decoder_GetDecoderDevice( decoder_t *dec )
 277 {
 278     vlc_assert( dec->fmt_in.i_cat == VIDEO_ES && dec->cbs != NULL );
 279     if ( unlikely(dec->fmt_in.i_cat != VIDEO_ES || dec->cbs == NULL ) )
 280         return NULL;
 281
 282     vlc_assert(dec->cbs->video.get_device != NULL);
 283     return dec->cbs->video.get_device( dec );
 284 }
 285
 286 /**
 287  * Creates/Updates the rest of the video output pipeline.
 288  *
 289  * After a call to decoder_GetDecoderDevice() this function notifies the
 290  * video output pipeline of a new video output format (fmt_out.video). If there
 291  * was no video output from the decoder so far, a new decoder video output will
 292  * be set up. decoder_NewPicture() can then be used to allocate picture buffers.
 293  *
 294  * If the format is unchanged, this function has no effects and returns zero.
 295  *
 296  * \note
 297  * This function is not reentrant.
 298  *
 299  * @return 0 if the video output was set up successfully, -1 otherwise.
 300  */
 301 VLC_API int decoder_UpdateVideoOutput( decoder_t *dec, vlc_video_context *vctx_out );
 302
 303 /**
 304  * Updates the video output format.
 305  *
 306  * This function notifies the video output pipeline of a new video output
 307  * format (fmt_out.video). If there was no video output from the decoder so far
 308  * or if the video output format has changed, a new video output will be set
 309  * up. decoder_NewPicture() can then be used to allocate picture buffers.
 310  *
 311  * If the format is unchanged, this function has no effects and returns zero.
 312  *
 313  * \note
 314  * This function is not reentrant.
 315  *
 316  * @return 0 if the video output was set up successfully, -1 otherwise.
 317  */
 318 VLC_API int decoder_UpdateVideoFormat( decoder_t *dec );
 319
 320 /**
 321  * Allocates an output picture buffer.
 322  *
 323  * This function pulls an output picture buffer for the decoder from the
 324  * buffer pool of the video output. The picture must be released with
 325  * picture_Release() when it is no longer referenced by the decoder.
 326  *
 327  * \note
 328  * This function is reentrant. However, decoder_UpdateVideoFormat() cannot be
 329  * used concurrently; the caller is responsible for serialization.
 330  *
 331  * \warning
 332  * The behaviour is undefined if decoder_UpdateVideoFormat() was not called or
 333  * if the last call returned an error.
 334  *
 335  * \return a picture buffer on success, NULL on error
 336  */
 337 VLC_API picture_t *decoder_NewPicture( decoder_t *dec );
 338
 339 /**
 340  * Abort any calls of decoder_NewPicture
 341  *
 342  * If b_abort is true, all pending and futures calls of decoder_NewPicture
 343  * will be aborted. This function can be used by asynchronous video decoders
 344  * to unblock a thread that is waiting for a picture.
 345  */
 346 VLC_API void decoder_AbortPictures( decoder_t *dec, bool b_abort );
 347
 348 /**
 349  * Initialize a decoder structure before creating the decoder.
 350  *
 351  * To be used by decoder owners.
 352  * By default frame drop is not allowed.
 353  */
 354 VLC_API void decoder_Init( decoder_t *dec, const es_format_t * );
 355
 356 /**
 357  * Destroy a decoder and reset the structure.
 358  *
 359  * To be used by decoder owners.
 360  */
 361 VLC_API void decoder_Destroy( decoder_t *p_dec );
 362
 363 /**
 364  * Unload a decoder module and reset the input/output formats.
 365  *
 366  * To be used by decoder owners.
 367  */
 368 VLC_API void decoder_Clean( decoder_t *p_dec );
 369
 370 /**
 371  * This function queues a single picture to the video output.
 372  *
 373  * \note
 374  * The caller doesn't own the picture anymore after this call (even in case of
 375  * error).
 376  * FIXME: input_DecoderFrameNext won't work if a module use this function.
 377  */
 378 static inline void decoder_QueueVideo( decoder_t *dec, picture_t *p_pic )
 379 {
 380     vlc_assert( dec->fmt_in.i_cat == VIDEO_ES && dec->cbs != NULL );
 381     vlc_assert( p_pic->p_next == NULL );
 382     vlc_assert( dec->cbs->video.queue != NULL );
 383     dec->cbs->video.queue( dec, p_pic );
 384 }
 385
 386 /**
 387  * This function queues the Closed Captions
 388  *
 389  * \param dec the decoder object
 390  * \param p_cc the closed-caption to queue
 391  * \param p_desc decoder_cc_desc_t description structure
 392  */
 393 static inline void decoder_QueueCc( decoder_t *dec, block_t *p_cc,
 394                                    const decoder_cc_desc_t *p_desc )
 395 {
 396     vlc_assert( dec->fmt_in.i_cat == VIDEO_ES && dec->cbs != NULL );
 397
 398     if( dec->cbs->video.queue_cc == NULL )
 399         block_Release( p_cc );
 400     else
 401         dec->cbs->video.queue_cc( dec, p_cc, p_desc );
 402 }
 403
 404 /**
 405  * This function queues a single audio block to the audio output.
 406  *
 407  * \note
 408  * The caller doesn't own the audio block anymore after this call (even in case
 409  * of error).
 410  */
 411 static inline void decoder_QueueAudio( decoder_t *dec, block_t *p_aout_buf )
 412 {
 413     vlc_assert( dec->fmt_in.i_cat == AUDIO_ES && dec->cbs != NULL );
 414     vlc_assert( p_aout_buf->p_next == NULL );
 415     vlc_assert( dec->cbs->audio.queue != NULL );
 416     dec->cbs->audio.queue( dec, p_aout_buf );
 417 }
 418
 419 /**
 420  * This function queues a single subtitle to the video output.
 421  *
 422  * \note
 423  * The caller doesn't own the subtitle anymore after this call (even in case of
 424  * error).
 425  */
 426 static inline void decoder_QueueSub( decoder_t *dec, subpicture_t *p_spu )
 427 {
 428     vlc_assert( dec->fmt_in.i_cat == SPU_ES && dec->cbs != NULL );
 429     vlc_assert( p_spu->p_next == NULL );
 430     vlc_assert( dec->cbs->spu.queue != NULL );
 431     dec->cbs->spu.queue( dec, p_spu );
 432 }
 433
 434 /**
 435  * This function notifies the audio output pipeline of a new audio output
 436  * format (fmt_out.audio). If there is currently no audio output or if the
 437  * audio output format has changed, a new audio output will be set up.
 438  * @return 0 if the audio output is working, -1 if not. */
 439 VLC_USED
 440 static inline int decoder_UpdateAudioFormat( decoder_t *dec )
 441 {
 442     vlc_assert( dec->fmt_in.i_cat == AUDIO_ES && dec->cbs != NULL );
 443
 444     if( dec->fmt_in.i_cat == AUDIO_ES && dec->cbs->audio.format_update != NULL )
 445         return dec->cbs->audio.format_update( dec );
 446     else
 447         return -1;
 448 }
 449
 450 /**
 451  * This function will return a new audio buffer usable by a decoder as an
 452  * output buffer. It must be released with block_Release() or returned it to
 453  * the caller as a decoder_QueueAudio parameter.
 454  */
 455 VLC_API block_t * decoder_NewAudioBuffer( decoder_t *, int i_nb_samples ) VLC_USED;
 456
 457 /**
 458  * This function will return a new subpicture usable by a decoder as an output
 459  * buffer. You have to release it using subpicture_Delete() or by returning
 460  * it to the caller as a decoder_QueueSub parameter.
 461  */
 462 VLC_USED
 463 static inline subpicture_t *decoder_NewSubpicture( decoder_t *dec,
 464                                                    const subpicture_updater_t *p_dyn )
 465 {
 466     vlc_assert( dec->fmt_in.i_cat == SPU_ES && dec->cbs != NULL );
 467
 468     subpicture_t *p_subpicture = dec->cbs->spu.buffer_new( dec, p_dyn );
 469     if( !p_subpicture )
 470         msg_Warn( dec, "can't get output subpicture" );
 471     return p_subpicture;
 472 }
 473
 474 /**
 475  * This function gives all input attachments at once.
 476  *
 477  * You MUST release the returned values
 478  */
 479 static inline int decoder_GetInputAttachments( decoder_t *dec,
 480                                                input_attachment_t ***ppp_attachment,
 481                                                int *pi_attachment )
 482 {
 483     vlc_assert( dec->cbs != NULL );
 484
 485     if( !dec->cbs->get_attachments )
 486         return VLC_EGENERIC;
 487
 488     return dec->cbs->get_attachments( dec, ppp_attachment, pi_attachment );
 489 }
 490
 491 /**
 492  * This function converts a decoder timestamp into a display date comparable
 493  * to vlc_tick_now().
 494  * You MUST use it *only* for gathering statistics about speed.
 495  */
 496 VLC_USED
 497 static inline vlc_tick_t decoder_GetDisplayDate( decoder_t *dec,
 498                                                  vlc_tick_t system_now,
 499                                                  vlc_tick_t i_ts )
 500 {
 501     vlc_assert( dec->fmt_in.i_cat == VIDEO_ES && dec->cbs != NULL );
 502
 503     if( !dec->cbs->video.get_display_date )
 504         return VLC_TICK_INVALID;
 505
 506     return dec->cbs->video.get_display_date( dec, system_now, i_ts );
 507 }
 508
 509 /**
 510  * This function returns the current input rate.
 511  * You MUST use it *only* for gathering statistics about speed.
 512  */
 513 VLC_USED
 514 static inline float decoder_GetDisplayRate( decoder_t *dec )
 515 {
 516     vlc_assert( dec->fmt_in.i_cat == VIDEO_ES && dec->cbs != NULL );
 517
 518     if( !dec->cbs->video.get_display_rate )
 519         return 1.f;
 520
 521     return dec->cbs->video.get_display_rate( dec );
 522 }
 523
 524 /** @} */
 525
 526 /**
 527  * \defgroup decoder_device Decoder hardware device
 528  * \ingroup input
 529  * @{
 530  */
 531
 532 /** Decoder device type */
 533 enum vlc_decoder_device_type
 534 {
 535     VLC_DECODER_DEVICE_VAAPI,
 536     VLC_DECODER_DEVICE_VDPAU,
 537     VLC_DECODER_DEVICE_DXVA2,
 538     VLC_DECODER_DEVICE_D3D11VA,
 539     VLC_DECODER_DEVICE_AWINDOW,
 540     VLC_DECODER_DEVICE_NVDEC,
 541     VLC_DECODER_DEVICE_MMAL,
 542 };
 543
 544 struct vlc_decoder_device_operations
 545 {
 546     void (*close)(struct vlc_decoder_device *);
 547 };
 548
 549 /**
 550  * Decoder context struct
 551  */
 552 typedef struct vlc_decoder_device
 553 {
 554     struct vlc_object_t obj;
 555
 556     const struct vlc_decoder_device_operations *ops;
 557
 558     /** Private context that could be used by the "decoder device" module
 559      * implementation */
 560     void *sys;
 561
 562     /** Must be set from the "decoder device" module open entry point */
 563     enum vlc_decoder_device_type type;
 564
 565     /**
 566      * Could be set from the "decoder device" module open entry point and will
 567      * be used by hardware decoder modules.
 568      *
 569      * The type of pointer will depend of the type:
 570      * VAAPI: VADisplay
 571      * VDPAU: vdp_t *
 572      * DXVA2: d3d9_decoder_device_t*
 573      * D3D11VA: d3d11_decoder_device_t*
 574      * AWindow: android AWindowHandler*
 575      * NVDEC: decoder_device_nvdec_t*
 576      * MMAL: MMAL_PORT_T*
 577      */
 578     void *opaque;
 579 } vlc_decoder_device;
 580
 581 /**
 582  * "decoder device" module open entry point
 583  *
 584  * @param device the "decoder device" structure to initialize
 585  * @param window pointer to a window to help device initialization (can be NULL)
 586  **/
 587 typedef int (*vlc_decoder_device_Open)(vlc_decoder_device *device,
 588                                         vout_window_t *window);
 589
 590 #define set_callback_dec_device(activate, priority) \
 591     { \
 592         vlc_decoder_device_Open open__ = activate; \
 593         (void) open__; \
 594         set_callback(activate) \
 595     } \
 596     set_capability( "decoder device", priority )
 597
 598
 599 /**
 600  * Create a decoder device from a window
 601  *
 602  * This function will be hidden in the future. It is now used by opengl vout
 603  * module as a transition.
 604  */
 605 VLC_API vlc_decoder_device *
 606 vlc_decoder_device_Create(vlc_object_t *, vout_window_t *window) VLC_USED;
 607
 608 /**
 609  * Hold a decoder device
 610  */
 611 VLC_API vlc_decoder_device *
 612 vlc_decoder_device_Hold(vlc_decoder_device *device);
 613
 614 /**
 615  * Release a decoder device
 616  */
 617 VLC_API void
 618 vlc_decoder_device_Release(vlc_decoder_device *device);
 619
 620 /** @} */
 621 #endif /* _VLC_CODEC_H */