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  * $Id$
   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 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 */
  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 );
  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_common_members 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_common_members 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_USED
 272 static inline int decoder_UpdateVideoFormat( decoder_t *dec )
 273 {
 274     vlc_assert( dec->fmt_in.i_cat == VIDEO_ES && dec->cbs != NULL );
 275
 276     if( dec->fmt_in.i_cat == VIDEO_ES && dec->cbs->video.format_update != NULL )
 277         return dec->cbs->video.format_update( dec );
 278     else
 279         return -1;
 280 }
 281
 282 /**
 283  * Allocates an output picture buffer.
 284  *
 285  * This function pulls an output picture buffer for the decoder from the
 286  * buffer pool of the video output. The picture must be released with
 287  * picture_Release() when it is no longer referenced by the decoder.
 288  *
 289  * \note
 290  * This function is reentrant. However, decoder_UpdateVideoFormat() cannot be
 291  * used concurrently; the caller is responsible for serialization.
 292  *
 293  * \warning
 294  * The behaviour is undefined if decoder_UpdateVideoFormat() was not called or
 295  * if the last call returned an error.
 296  *
 297  * \return a picture buffer on success, NULL on error
 298  */
 299 VLC_USED
 300 static inline picture_t *decoder_NewPicture( decoder_t *dec )
 301 {
 302     vlc_assert( dec->fmt_in.i_cat == VIDEO_ES && dec->cbs != NULL );
 303     return dec->cbs->video.buffer_new( dec );
 304 }
 305
 306 /**
 307  * Abort any calls of decoder_NewPicture
 308  *
 309  * If b_abort is true, all pending and futures calls of decoder_NewPicture
 310  * will be aborted. This function can be used by asynchronous video decoders
 311  * to unblock a thread that is waiting for a picture.
 312  */
 313 VLC_API void decoder_AbortPictures( decoder_t *dec, bool b_abort );
 314
 315 /**
 316  * This function queues a single picture to the video output.
 317  *
 318  * \note
 319  * The caller doesn't own the picture anymore after this call (even in case of
 320  * error).
 321  * FIXME: input_DecoderFrameNext won't work if a module use this function.
 322  */
 323 static inline void decoder_QueueVideo( decoder_t *dec, picture_t *p_pic )
 324 {
 325     vlc_assert( dec->fmt_in.i_cat == VIDEO_ES && dec->cbs != NULL );
 326     vlc_assert( p_pic->p_next == NULL );
 327     vlc_assert( dec->cbs->video.queue != NULL );
 328     dec->cbs->video.queue( dec, p_pic );
 329 }
 330
 331 /**
 332  * This function queues the Closed Captions
 333  *
 334  * \param dec the decoder object
 335  * \param p_cc the closed-caption to queue
 336  * \param p_desc decoder_cc_desc_t description structure
 337  */
 338 static inline void decoder_QueueCc( decoder_t *dec, block_t *p_cc,
 339                                    const decoder_cc_desc_t *p_desc )
 340 {
 341     vlc_assert( dec->fmt_in.i_cat == VIDEO_ES && dec->cbs != NULL );
 342
 343     if( dec->cbs->video.queue_cc == NULL )
 344         block_Release( p_cc );
 345     else
 346         dec->cbs->video.queue_cc( dec, p_cc, p_desc );
 347 }
 348
 349 /**
 350  * This function queues a single audio block to the audio output.
 351  *
 352  * \note
 353  * The caller doesn't own the audio block anymore after this call (even in case
 354  * of error).
 355  */
 356 static inline void decoder_QueueAudio( decoder_t *dec, block_t *p_aout_buf )
 357 {
 358     vlc_assert( dec->fmt_in.i_cat == AUDIO_ES && dec->cbs != NULL );
 359     vlc_assert( p_aout_buf->p_next == NULL );
 360     vlc_assert( dec->cbs->audio.queue != NULL );
 361     dec->cbs->audio.queue( dec, p_aout_buf );
 362 }
 363
 364 /**
 365  * This function queues a single subtitle to the video output.
 366  *
 367  * \note
 368  * The caller doesn't own the subtitle anymore after this call (even in case of
 369  * error).
 370  */
 371 static inline void decoder_QueueSub( decoder_t *dec, subpicture_t *p_spu )
 372 {
 373     vlc_assert( dec->fmt_in.i_cat == SPU_ES && dec->cbs != NULL );
 374     vlc_assert( p_spu->p_next == NULL );
 375     vlc_assert( dec->cbs->spu.queue != NULL );
 376     dec->cbs->spu.queue( dec, p_spu );
 377 }
 378
 379 /**
 380  * This function notifies the audio output pipeline of a new audio output
 381  * format (fmt_out.audio). If there is currently no audio output or if the
 382  * audio output format has changed, a new audio output will be set up.
 383  * @return 0 if the audio output is working, -1 if not. */
 384 VLC_USED
 385 static inline int decoder_UpdateAudioFormat( decoder_t *dec )
 386 {
 387     vlc_assert( dec->fmt_in.i_cat == AUDIO_ES && dec->cbs != NULL );
 388
 389     if( dec->fmt_in.i_cat == AUDIO_ES && dec->cbs->audio.format_update != NULL )
 390         return dec->cbs->audio.format_update( dec );
 391     else
 392         return -1;
 393 }
 394
 395 /**
 396  * This function will return a new audio buffer usable by a decoder as an
 397  * output buffer. It must be released with block_Release() or returned it to
 398  * the caller as a decoder_QueueAudio parameter.
 399  */
 400 VLC_API block_t * decoder_NewAudioBuffer( decoder_t *, int i_nb_samples ) VLC_USED;
 401
 402 /**
 403  * This function will return a new subpicture usable by a decoder as an output
 404  * buffer. You have to release it using subpicture_Delete() or by returning
 405  * it to the caller as a decoder_QueueSub parameter.
 406  */
 407 VLC_USED
 408 static inline subpicture_t *decoder_NewSubpicture( decoder_t *dec,
 409                                                    const subpicture_updater_t *p_dyn )
 410 {
 411     vlc_assert( dec->fmt_in.i_cat == SPU_ES && dec->cbs != NULL );
 412
 413     subpicture_t *p_subpicture = dec->cbs->spu.buffer_new( dec, p_dyn );
 414     if( !p_subpicture )
 415         msg_Warn( dec, "can't get output subpicture" );
 416     return p_subpicture;
 417 }
 418
 419 /**
 420  * This function gives all input attachments at once.
 421  *
 422  * You MUST release the returned values
 423  */
 424 static inline int decoder_GetInputAttachments( decoder_t *dec,
 425                                                input_attachment_t ***ppp_attachment,
 426                                                int *pi_attachment )
 427 {
 428     vlc_assert( dec->cbs != NULL );
 429
 430     if( !dec->cbs->get_attachments )
 431         return VLC_EGENERIC;
 432
 433     return dec->cbs->get_attachments( dec, ppp_attachment, pi_attachment );
 434 }
 435
 436 /**
 437  * This function converts a decoder timestamp into a display date comparable
 438  * to vlc_tick_now().
 439  * You MUST use it *only* for gathering statistics about speed.
 440  */
 441 VLC_USED
 442 static inline vlc_tick_t decoder_GetDisplayDate( decoder_t *dec, vlc_tick_t i_ts )
 443 {
 444     vlc_assert( dec->fmt_in.i_cat == VIDEO_ES && dec->cbs != NULL );
 445
 446     if( !dec->cbs->video.get_display_date )
 447         return VLC_TICK_INVALID;
 448
 449     return dec->cbs->video.get_display_date( dec, i_ts );
 450 }
 451
 452 /**
 453  * This function returns the current input rate.
 454  * You MUST use it *only* for gathering statistics about speed.
 455  */
 456 VLC_USED
 457 static inline float decoder_GetDisplayRate( decoder_t *dec )
 458 {
 459     vlc_assert( dec->fmt_in.i_cat == VIDEO_ES && dec->cbs != NULL );
 460
 461     if( !dec->cbs->video.get_display_rate )
 462         return 1.f;
 463
 464     return dec->cbs->video.get_display_rate( dec );
 465 }
 466
 467 /** @} */
 468 /** @} */
 469 #endif /* _VLC_CODEC_H */