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 <vlc_block.h>
  28 #include <vlc_es.h>
  29 #include <vlc_picture.h>
  30 #include <vlc_subpicture.h>
  31
  32 /**
  33  * \defgroup codec Codec
  34  * Decoders and encoders
  35  * @{
  36  * \file
  37  * Decoder and encoder modules interface
  38  *
  39  * \defgroup decoder Decoder
  40  * Audio, video and text decoders
  41  * @{
  42  */
  43
  44 typedef struct decoder_owner_sys_t decoder_owner_sys_t;
  45
  46 /*
  47  * BIG FAT WARNING : the code relies in the first 4 members of filter_t
  48  * and decoder_t to be the same, so if you have anything to add, do it
  49  * at the end of the structure.
  50  */
  51 struct decoder_t
  52 {
  53     VLC_COMMON_MEMBERS
  54
  55     /* Module properties */
  56     module_t *          p_module;
  57     decoder_sys_t *     p_sys;
  58
  59     /* Input format ie from demuxer (XXX: a lot of field could be invalid) */
  60     es_format_t         fmt_in;
  61
  62     /* Output format of decoder/packetizer */
  63     es_format_t         fmt_out;
  64
  65     /* Tell the decoder if it is allowed to drop frames */
  66     bool                b_frame_drop_allowed;
  67
  68     /* All pf_decode_* and pf_packetize functions have the same behavior.
  69      *
  70      * These functions are called in a loop with the same pp_block argument
  71      * until they return NULL. This allows a module implementation to return
  72      * more than one frames/samples for one input block.
  73      *
  74      * pp_block or *pp_block can be NULL.
  75      *
  76      * If pp_block and *pp_block are not NULL, the module implementation will
  77      * own the input block (*pp_block) and should process and release it. The
  78      * module can also process a part of the block. In that case, it should
  79      * modify (*pp_block)->p_buffer/i_buffer accordingly and return a valid
  80      * frame/samples. The module can also set *pp_block to NULL when the input
  81      * block is consumed.
  82      *
  83      * If pp_block is not NULL but *pp_block is NULL, a previous call of the pf
  84      * function has set the *pp_block to NULL. Here, the module can return new
  85      * frames/samples for the same, already processed, input block (the pf
  86      * function will be called as long as the module return a frame/samples).
  87      *
  88      * When the pf function returns NULL, the next call to this function will
  89      * have a new a valid pp_block (if the decoder is not drained).
  90      *
  91      * If pp_block is NULL, the decoder asks the module to drain itself. In
  92      * that case, the module has to return all frames/samples available (the pf
  93      * function will be called as long as the module return a frame/samples).
  94      */
  95     picture_t *         ( * pf_decode_video )( decoder_t *, block_t **pp_block );
  96     block_t *           ( * pf_decode_audio )( decoder_t *, block_t **pp_block );
  97     subpicture_t *      ( * pf_decode_sub)   ( decoder_t *, block_t **pp_block );
  98     block_t *           ( * pf_packetize )   ( decoder_t *, block_t **pp_block );
  99     /* */
 100     void                ( * pf_flush ) ( decoder_t * );
 101
 102     /* Closed Caption (CEA 608/708) extraction.
 103      * If set, it *may* be called after pf_decode_video/pf_packetize
 104      * returned data. It should return CC for the pictures returned by the
 105      * last pf_packetize/pf_decode_video call only,
 106      * pb_present will be used to known which cc channel are present (but
 107      * globaly, not necessary for the current packet */
 108     block_t *           ( * pf_get_cc )      ( decoder_t *, bool pb_present[4] );
 109
 110     /* Meta data at codec level
 111      *  The decoder owner set it back to NULL once it has retreived what it needs.
 112      *  The decoder owner is responsible of its release except when you overwrite it.
 113      */
 114     vlc_meta_t          *p_description;
 115
 116     /*
 117      * Owner fields
 118      * XXX You MUST not use them directly.
 119      */
 120
 121     /* Video output callbacks
 122      * XXX use decoder_NewPicture */
 123     int             (*pf_vout_format_update)( decoder_t * );
 124     picture_t      *(*pf_vout_buffer_new)( decoder_t * );
 125
 126     /**
 127      * Number of extra (ie in addition to the DPB) picture buffers
 128      * needed for decoding.
 129      */
 130     int             i_extra_picture_buffers;
 131
 132     /* Audio output callbacks */
 133     int             (*pf_aout_format_update)( decoder_t * );
 134
 135     /* SPU output callbacks
 136      * XXX use decoder_NewSubpicture */
 137     subpicture_t   *(*pf_spu_buffer_new)( decoder_t *, const subpicture_updater_t * );
 138
 139     /* Input attachments
 140      * XXX use decoder_GetInputAttachments */
 141     int             (*pf_get_attachments)( decoder_t *p_dec, input_attachment_t ***ppp_attachment, int *pi_attachment );
 142
 143     /* Display date
 144      * XXX use decoder_GetDisplayDate */
 145     mtime_t         (*pf_get_display_date)( decoder_t *, mtime_t );
 146
 147     /* Display rate
 148      * XXX use decoder_GetDisplayRate */
 149     int             (*pf_get_display_rate)( decoder_t * );
 150
 151     /* XXX use decoder_QueueVideo */
 152     int             (*pf_queue_video)( decoder_t *, picture_t * );
 153     /* XXX use decoder_QueueAudio */
 154     int             (*pf_queue_audio)( decoder_t *, block_t * );
 155     /* XXX use decoder_QueueSub */
 156     int             (*pf_queue_sub)( decoder_t *, subpicture_t *);
 157
 158     /* Private structure for the owner of the decoder */
 159     decoder_owner_sys_t *p_owner;
 160
 161     bool                b_error;
 162 };
 163
 164 /**
 165  * @}
 166  */
 167
 168 /**
 169  * \defgroup encoder Encoder
 170  * Audio, video and text encoders
 171  * @{
 172  */
 173
 174 struct encoder_t
 175 {
 176     VLC_COMMON_MEMBERS
 177
 178     /* Module properties */
 179     module_t *          p_module;
 180     encoder_sys_t *     p_sys;
 181
 182     /* Properties of the input data fed to the encoder */
 183     es_format_t         fmt_in;
 184
 185     /* Properties of the output of the encoder */
 186     es_format_t         fmt_out;
 187
 188     block_t *           ( * pf_encode_video )( encoder_t *, picture_t * );
 189     block_t *           ( * pf_encode_audio )( encoder_t *, block_t * );
 190     block_t *           ( * pf_encode_sub )( encoder_t *, subpicture_t * );
 191
 192     /* Common encoder options */
 193     int i_threads;               /* Number of threads to use during encoding */
 194     int i_iframes;               /* One I frame per i_iframes */
 195     int i_bframes;               /* One B frame per i_bframes */
 196     int i_tolerance;             /* Bitrate tolerance */
 197
 198     /* Encoder config */
 199     config_chain_t *p_cfg;
 200 };
 201
 202 /**
 203  * @}
 204  *
 205  * \ingroup decoder
 206  * @{
 207  */
 208
 209 /**
 210  * Updates the video output format.
 211  *
 212  * This function notifies the video output pipeline of a new video output
 213  * format (fmt_out.video). If there was no video output from the decoder so far
 214  * or if the video output format has changed, a new video output will be set
 215  * up. decoder_GetPicture() can then be used to allocate picture buffers.
 216  *
 217  * If the format is unchanged, this function has no effects and returns zero.
 218  *
 219  * \note
 220  * This function is not reentrant.
 221  *
 222  * @return 0 if the video output was set up succesfully, -1 otherwise.
 223  */
 224 static inline int decoder_UpdateVideoFormat( decoder_t *dec )
 225 {
 226     if( dec->pf_vout_format_update != NULL )
 227         return dec->pf_vout_format_update( dec );
 228     else
 229         return -1;
 230 }
 231
 232 /**
 233  * Allocates an output picture buffer.
 234  *
 235  * This function pulls an output picture buffer for the decoder from the
 236  * buffer pool of the video output. The picture must be released with
 237  * picture_Release() when it is no longer referenced by the decoder.
 238  *
 239  * \note
 240  * This function is reentrant. However, decoder_UpdateVideoFormat() cannot be
 241  * used concurrently; the caller is responsible for serialization.
 242  *
 243  * \warning
 244  * The behaviour is undefined if decoder_UpdateVideoFormat() was not called or
 245  * if the last call returned an error.
 246  *
 247  * \return a picture buffer on success, NULL on error
 248  */
 249 VLC_USED
 250 static inline picture_t *decoder_GetPicture( decoder_t *dec )
 251 {
 252     return dec->pf_vout_buffer_new( dec );
 253 }
 254
 255 /**
 256  * Checks the format and allocates a picture buffer.
 257  *
 258  * This common helper function sets the output video output format and
 259  * allocates a picture buffer in that format. The picture must be released with
 260  * picture_Release() when it is no longer referenced by the decoder.
 261  *
 262  * \note
 263  * Lile decoder_UpdateVideoFormat(), this function is not reentrant.
 264  *
 265  * \return a picture buffer on success, NULL on error
 266  */
 267 VLC_USED
 268 static inline picture_t *decoder_NewPicture( decoder_t *dec )
 269 {
 270     if( decoder_UpdateVideoFormat(dec) )
 271         return NULL;
 272     return decoder_GetPicture( dec );
 273 }
 274
 275 /**
 276  * Abort any calls of decoder_NewPicture / decoder_GetPicture
 277  *
 278  * If b_abort is true, all pending and futures calls of decoder_NewPicture /
 279  * decoder_GetPicture will be aborted. This function can be used by
 280  * asynchronous video decoders to unblock a thread that is waiting for a
 281  * picture.
 282  */
 283 VLC_API void decoder_AbortPictures( decoder_t *dec, bool b_abort );
 284
 285 /**
 286  * This function queues a picture to the video output.
 287  *
 288  * \note
 289  * The caller doesn't own the picture anymore after this call (even in case of
 290  * error).
 291  * FIXME: input_DecoderFrameNext won't work if a module use this function.
 292  *
 293  * \return 0 if the picture is queued, -1 on error
 294  */
 295 static inline int decoder_QueueVideo( decoder_t *dec, picture_t *p_pic )
 296 {
 297     if( !dec->pf_queue_video )
 298     {
 299         picture_Release( p_pic );
 300         return -1;
 301     }
 302     return dec->pf_queue_video( dec, p_pic );
 303 }
 304
 305 /**
 306  * This function queues an audio block to the audio output.
 307  *
 308  * \note
 309  * The caller doesn't own the audio block anymore after this call (even in case
 310  * of error).
 311  *
 312  * \return 0 if the block is queued, -1 on error
 313  */
 314 static inline int decoder_QueueAudio( decoder_t *dec, block_t *p_aout_buf )
 315 {
 316     if( !dec->pf_queue_audio )
 317     {
 318         block_Release( p_aout_buf );
 319         return -1;
 320     }
 321     return dec->pf_queue_audio( dec, p_aout_buf );
 322 }
 323
 324 /**
 325  * This function queues a subtitle to the video output.
 326  *
 327  * \note
 328  * The caller doesn't own the subtitle anymore after this call (even in case of
 329  * error).
 330  *
 331  * \return 0 if the subtitle is queued, -1 on error
 332  */
 333 static inline int decoder_QueueSub( decoder_t *dec, subpicture_t *p_spu )
 334 {
 335     if( !dec->pf_queue_sub )
 336     {
 337         subpicture_Delete( p_spu );
 338         return -1;
 339     }
 340     return dec->pf_queue_sub( dec, p_spu );
 341 }
 342
 343 /**
 344  * This function notifies the audio output pipeline of a new audio output
 345  * format (fmt_out.audio). If there is currently no audio output or if the
 346  * audio output format has changed, a new audio output will be set up.
 347  * @return 0 if the audio output is working, -1 if not. */
 348 static inline int decoder_UpdateAudioFormat( decoder_t *dec )
 349 {
 350     if( dec->pf_aout_format_update != NULL )
 351         return dec->pf_aout_format_update( dec );
 352     else
 353         return -1;
 354 }
 355
 356 /**
 357  * This function will return a new audio buffer usable by a decoder as an
 358  * output buffer. It must be released with block_Release() or returned it to
 359  * the caller as a pf_decode_audio return value.
 360  */
 361 VLC_API block_t * decoder_NewAudioBuffer( decoder_t *, int i_size ) VLC_USED;
 362
 363 /**
 364  * This function will return a new subpicture usable by a decoder as an output
 365  * buffer. You have to release it using subpicture_Delete() or by returning
 366  * it to the caller as a pf_decode_sub return value.
 367  */
 368 VLC_API subpicture_t * decoder_NewSubpicture( decoder_t *, const subpicture_updater_t * ) VLC_USED;
 369
 370 /**
 371  * This function gives all input attachments at once.
 372  *
 373  * You MUST release the returned values
 374  */
 375 VLC_API int decoder_GetInputAttachments( decoder_t *, input_attachment_t ***ppp_attachment, int *pi_attachment );
 376
 377 /**
 378  * This function converts a decoder timestamp into a display date comparable
 379  * to mdate().
 380  * You MUST use it *only* for gathering statistics about speed.
 381  */
 382 VLC_API mtime_t decoder_GetDisplayDate( decoder_t *, mtime_t ) VLC_USED;
 383
 384 /**
 385  * This function returns the current input rate.
 386  * You MUST use it *only* for gathering statistics about speed.
 387  */
 388 VLC_API int decoder_GetDisplayRate( decoder_t * ) VLC_USED;
 389
 390 /** @} */
 391 /** @} */
 392 #endif /* _VLC_CODEC_H */