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 struct encoder_owner_callbacks
 218 {
 219     struct
 220     {
 221         vlc_decoder_device *(*get_device)( encoder_t * );
 222     } video;
 223 };
 224
 225 /**
 226  * Creates/Updates the output decoder device.
 227  *
 228  * \note
 229  * This function is not reentrant.
 230  *
 231  * @return the held decoder device, NULL if none should be used
 232  */
 233 VLC_API vlc_decoder_device *vlc_encoder_GetDecoderDevice( encoder_t * );
 234
 235
 236 /**
 237  * \defgroup encoder Encoder
 238  * \ingroup sout
 239  * Audio, video and text encoders
 240  * @{
 241  */
 242
 243 struct encoder_t
 244 {
 245     struct vlc_object_t obj;
 246
 247     /* Module properties */
 248     module_t *          p_module;
 249     void               *p_sys;
 250
 251     /* Properties of the input data fed to the encoder */
 252     es_format_t         fmt_in;
 253     vlc_video_context   *vctx_in; /* for video */
 254
 255     /* Properties of the output of the encoder */
 256     es_format_t         fmt_out;
 257
 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 * );
 261
 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 */
 267
 268     /* Encoder config */
 269     config_chain_t *p_cfg;
 270
 271     /* Private structure for the owner of the encoder */
 272     const struct encoder_owner_callbacks *cbs;
 273 };
 274
 275 /**
 276  * @}
 277  *
 278  * \ingroup decoder
 279  * @{
 280  */
 281
 282 /**
 283  * Creates/Updates the output decoder device.
 284  *
 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.
 289  *
 290  * If the format is unchanged, this function has no effects and returns zero.
 291  *
 292  * \param dec the decoder object
 293  *
 294  * \note
 295  * This function is not reentrant.
 296  *
 297  * @return the received of the held decoder device, NULL not to get one
 298  */
 299 static inline vlc_decoder_device * decoder_GetDecoderDevice( decoder_t *dec )
 300 {
 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 ) )
 303         return NULL;
 304
 305     vlc_assert(dec->cbs->video.get_device != NULL);
 306     return dec->cbs->video.get_device( dec );
 307 }
 308
 309 /**
 310  * Creates/Updates the rest of the video output pipeline.
 311  *
 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.
 316  *
 317  * If the format is unchanged, this function has no effects and returns zero.
 318  *
 319  * \note
 320  * This function is not reentrant.
 321  *
 322  * @return 0 if the video output was set up successfully, -1 otherwise.
 323  */
 324 VLC_API int decoder_UpdateVideoOutput( decoder_t *dec, vlc_video_context *vctx_out );
 325
 326 /**
 327  * Updates the video output format.
 328  *
 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.
 333  *
 334  * If the format is unchanged, this function has no effects and returns zero.
 335  *
 336  * \note
 337  * This function is not reentrant.
 338  *
 339  * @return 0 if the video output was set up successfully, -1 otherwise.
 340  */
 341 VLC_API int decoder_UpdateVideoFormat( decoder_t *dec );
 342
 343 /**
 344  * Allocates an output picture buffer.
 345  *
 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.
 349  *
 350  * \note
 351  * This function is reentrant. However, decoder_UpdateVideoFormat() cannot be
 352  * used concurrently; the caller is responsible for serialization.
 353  *
 354  * \warning
 355  * The behaviour is undefined if decoder_UpdateVideoFormat() was not called or
 356  * if the last call returned an error.
 357  *
 358  * \return a picture buffer on success, NULL on error
 359  */
 360 VLC_API picture_t *decoder_NewPicture( decoder_t *dec );
 361
 362 /**
 363  * Abort any calls of decoder_NewPicture
 364  *
 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.
 368  */
 369 VLC_API void decoder_AbortPictures( decoder_t *dec, bool b_abort );
 370
 371 /**
 372  * Initialize a decoder structure before creating the decoder.
 373  *
 374  * To be used by decoder owners.
 375  * By default frame drop is not allowed.
 376  */
 377 VLC_API void decoder_Init( decoder_t *dec, const es_format_t * );
 378
 379 /**
 380  * Destroy a decoder and reset the structure.
 381  *
 382  * To be used by decoder owners.
 383  */
 384 VLC_API void decoder_Destroy( decoder_t *p_dec );
 385
 386 /**
 387  * Unload a decoder module and reset the input/output formats.
 388  *
 389  * To be used by decoder owners.
 390  */
 391 VLC_API void decoder_Clean( decoder_t *p_dec );
 392
 393 /**
 394  * This function queues a single picture to the video output.
 395  *
 396  * \note
 397  * The caller doesn't own the picture anymore after this call (even in case of
 398  * error).
 399  * FIXME: input_DecoderFrameNext won't work if a module use this function.
 400  */
 401 static inline void decoder_QueueVideo( decoder_t *dec, picture_t *p_pic )
 402 {
 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 );
 407 }
 408
 409 /**
 410  * This function queues the Closed Captions
 411  *
 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
 415  */
 416 static inline void decoder_QueueCc( decoder_t *dec, block_t *p_cc,
 417                                    const decoder_cc_desc_t *p_desc )
 418 {
 419     vlc_assert( dec->fmt_in.i_cat == VIDEO_ES && dec->cbs != NULL );
 420
 421     if( dec->cbs->video.queue_cc == NULL )
 422         block_Release( p_cc );
 423     else
 424         dec->cbs->video.queue_cc( dec, p_cc, p_desc );
 425 }
 426
 427 /**
 428  * This function queues a single audio block to the audio output.
 429  *
 430  * \note
 431  * The caller doesn't own the audio block anymore after this call (even in case
 432  * of error).
 433  */
 434 static inline void decoder_QueueAudio( decoder_t *dec, block_t *p_aout_buf )
 435 {
 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 );
 440 }
 441
 442 /**
 443  * This function queues a single subtitle to the video output.
 444  *
 445  * \note
 446  * The caller doesn't own the subtitle anymore after this call (even in case of
 447  * error).
 448  */
 449 static inline void decoder_QueueSub( decoder_t *dec, subpicture_t *p_spu )
 450 {
 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 );
 455 }
 456
 457 /**
 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. */
 462 VLC_USED
 463 static inline int decoder_UpdateAudioFormat( decoder_t *dec )
 464 {
 465     vlc_assert( dec->fmt_in.i_cat == AUDIO_ES && dec->cbs != NULL );
 466
 467     if( dec->fmt_in.i_cat == AUDIO_ES && dec->cbs->audio.format_update != NULL )
 468         return dec->cbs->audio.format_update( dec );
 469     else
 470         return -1;
 471 }
 472
 473 /**
 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.
 477  */
 478 VLC_API block_t * decoder_NewAudioBuffer( decoder_t *, int i_nb_samples ) VLC_USED;
 479
 480 /**
 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.
 484  */
 485 VLC_USED
 486 static inline subpicture_t *decoder_NewSubpicture( decoder_t *dec,
 487                                                    const subpicture_updater_t *p_dyn )
 488 {
 489     vlc_assert( dec->fmt_in.i_cat == SPU_ES && dec->cbs != NULL );
 490
 491     subpicture_t *p_subpicture = dec->cbs->spu.buffer_new( dec, p_dyn );
 492     if( !p_subpicture )
 493         msg_Warn( dec, "can't get output subpicture" );
 494     return p_subpicture;
 495 }
 496
 497 /**
 498  * This function gives all input attachments at once.
 499  *
 500  * You MUST release the returned values
 501  */
 502 static inline int decoder_GetInputAttachments( decoder_t *dec,
 503                                                input_attachment_t ***ppp_attachment,
 504                                                int *pi_attachment )
 505 {
 506     vlc_assert( dec->cbs != NULL );
 507
 508     if( !dec->cbs->get_attachments )
 509         return VLC_EGENERIC;
 510
 511     return dec->cbs->get_attachments( dec, ppp_attachment, pi_attachment );
 512 }
 513
 514 /**
 515  * This function converts a decoder timestamp into a display date comparable
 516  * to vlc_tick_now().
 517  * You MUST use it *only* for gathering statistics about speed.
 518  */
 519 VLC_USED
 520 static inline vlc_tick_t decoder_GetDisplayDate( decoder_t *dec,
 521                                                  vlc_tick_t system_now,
 522                                                  vlc_tick_t i_ts )
 523 {
 524     vlc_assert( dec->fmt_in.i_cat == VIDEO_ES && dec->cbs != NULL );
 525
 526     if( !dec->cbs->video.get_display_date )
 527         return VLC_TICK_INVALID;
 528
 529     return dec->cbs->video.get_display_date( dec, system_now, i_ts );
 530 }
 531
 532 /**
 533  * This function returns the current input rate.
 534  * You MUST use it *only* for gathering statistics about speed.
 535  */
 536 VLC_USED
 537 static inline float decoder_GetDisplayRate( decoder_t *dec )
 538 {
 539     vlc_assert( dec->fmt_in.i_cat == VIDEO_ES && dec->cbs != NULL );
 540
 541     if( !dec->cbs->video.get_display_rate )
 542         return 1.f;
 543
 544     return dec->cbs->video.get_display_rate( dec );
 545 }
 546
 547 /** @} */
 548
 549 /**
 550  * \defgroup decoder_device Decoder hardware device
 551  * \ingroup input
 552  * @{
 553  */
 554
 555 /** Decoder device type */
 556 enum vlc_decoder_device_type
 557 {
 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,
 566 };
 567
 568 struct vlc_decoder_device_operations
 569 {
 570     void (*close)(struct vlc_decoder_device *);
 571 };
 572
 573 /**
 574  * Decoder context struct
 575  */
 576 typedef struct vlc_decoder_device
 577 {
 578     struct vlc_object_t obj;
 579
 580     const struct vlc_decoder_device_operations *ops;
 581
 582     /** Private context that could be used by the "decoder device" module
 583      * implementation */
 584     void *sys;
 585
 586     /** Must be set from the "decoder device" module open entry point */
 587     enum vlc_decoder_device_type type;
 588
 589     /**
 590      * Could be set from the "decoder device" module open entry point and will
 591      * be used by hardware decoder modules.
 592      *
 593      * The type of pointer will depend of the type:
 594      * VAAPI: VADisplay
 595      * VDPAU: vdp_t *
 596      * DXVA2: d3d9_decoder_device_t*
 597      * D3D11VA: d3d11_decoder_device_t*
 598      * VIDEOTOOLBOX: NULL
 599      * AWindow: android AWindowHandler*
 600      * NVDEC: decoder_device_nvdec_t*
 601      * MMAL: MMAL_PORT_T*
 602      */
 603     void *opaque;
 604 } vlc_decoder_device;
 605
 606 /**
 607  * "decoder device" module open entry point
 608  *
 609  * @param device the "decoder device" structure to initialize
 610  * @param window pointer to a window to help device initialization (can be NULL)
 611  **/
 612 typedef int (*vlc_decoder_device_Open)(vlc_decoder_device *device,
 613                                         vout_window_t *window);
 614
 615 #define set_callback_dec_device(activate, priority) \
 616     { \
 617         vlc_decoder_device_Open open__ = activate; \
 618         (void) open__; \
 619         set_callback(activate) \
 620     } \
 621     set_capability( "decoder device", priority )
 622
 623
 624 /**
 625  * Create a decoder device from a window
 626  *
 627  * This function will be hidden in the future. It is now used by opengl vout
 628  * module as a transition.
 629  */
 630 VLC_API vlc_decoder_device *
 631 vlc_decoder_device_Create(vlc_object_t *, vout_window_t *window) VLC_USED;
 632
 633 /**
 634  * Hold a decoder device
 635  */
 636 VLC_API vlc_decoder_device *
 637 vlc_decoder_device_Hold(vlc_decoder_device *device);
 638
 639 /**
 640  * Release a decoder device
 641  */
 642 VLC_API void
 643 vlc_decoder_device_Release(vlc_decoder_device *device);
 644
 645 /** @} */
 646 #endif /* _VLC_CODEC_H */