avcodec.h 168 KB
Newer Older
1 2 3
/*
 * copyright (c) 2001 Fabrice Bellard
 *
4 5 6
 * This file is part of FFmpeg.
 *
 * FFmpeg is free software; you can redistribute it and/or
7 8
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
9
 * version 2.1 of the License, or (at your option) any later version.
10
 *
11
 * FFmpeg is distributed in the hope that it will be useful,
12 13 14 15 16
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
17
 * License along with FFmpeg; if not, write to the Free Software
18
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
19 20
 */

21 22
#ifndef AVCODEC_AVCODEC_H
#define AVCODEC_AVCODEC_H
Fabrice Bellard's avatar
Fabrice Bellard committed
23

24
/**
25
 * @file
26 27
 * @ingroup libavc
 * Libavcodec external API header
28 29
 */

30
#include <errno.h>
31
#include "libavutil/samplefmt.h"
32
#include "libavutil/attributes.h"
33
#include "libavutil/avutil.h"
34
#include "libavutil/buffer.h"
35
#include "libavutil/cpu.h"
36
#include "libavutil/channel_layout.h"
37
#include "libavutil/dict.h"
38
#include "libavutil/frame.h"
39
#include "libavutil/log.h"
40
#include "libavutil/pixfmt.h"
41
#include "libavutil/rational.h"
Fabrice Bellard's avatar
Fabrice Bellard committed
42

43
#include "libavcodec/version.h"
44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74
/**
 * @defgroup libavc Encoding/Decoding Library
 * @{
 *
 * @defgroup lavc_decoding Decoding
 * @{
 * @}
 *
 * @defgroup lavc_encoding Encoding
 * @{
 * @}
 *
 * @defgroup lavc_codec Codecs
 * @{
 * @defgroup lavc_codec_native Native Codecs
 * @{
 * @}
 * @defgroup lavc_codec_wrappers External library wrappers
 * @{
 * @}
 * @defgroup lavc_codec_hwaccel Hardware Accelerators bridge
 * @{
 * @}
 * @}
 * @defgroup lavc_internal Internal
 * @{
 * @}
 * @}
 *
 */

75 76 77 78 79 80 81 82
/**
 * @defgroup lavc_core Core functions/structures.
 * @ingroup libavc
 *
 * Basic definitions, functions for querying libavcodec capabilities,
 * allocating core structures, etc.
 * @{
 */
83

84

85
/**
Måns Rullgård's avatar
Måns Rullgård committed
86
 * Identify the syntax and semantics of the bitstream.
87 88 89 90 91
 * The principle is roughly:
 * Two decoders with the same ID can decode the same streams.
 * Two encoders with the same ID can encode compatible streams.
 * There may be slight deviations from the principle due to implementation
 * details.
92
 *
Diego Biurrun's avatar
Diego Biurrun committed
93 94
 * If you add a codec ID to this list, add it so that
 * 1. no value of a existing codec ID changes (that would break ABI),
95
 * 2. Give it a value which when taken as ASCII is recognized uniquely by a human as this specific codec.
96
 *    This ensures that 2 forks can independently add AVCodecIDs without producing conflicts.
97 98 99
 *
 * After adding new codec IDs, do not forget to add an entry to the codec
 * descriptor list and bump libavcodec minor version.
100
 */
101 102
enum AVCodecID {
    AV_CODEC_ID_NONE,
103 104

    /* video codecs */
105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271
    AV_CODEC_ID_MPEG1VIDEO,
    AV_CODEC_ID_MPEG2VIDEO, ///< preferred ID for MPEG-1/2 video decoding
    AV_CODEC_ID_MPEG2VIDEO_XVMC,
    AV_CODEC_ID_H261,
    AV_CODEC_ID_H263,
    AV_CODEC_ID_RV10,
    AV_CODEC_ID_RV20,
    AV_CODEC_ID_MJPEG,
    AV_CODEC_ID_MJPEGB,
    AV_CODEC_ID_LJPEG,
    AV_CODEC_ID_SP5X,
    AV_CODEC_ID_JPEGLS,
    AV_CODEC_ID_MPEG4,
    AV_CODEC_ID_RAWVIDEO,
    AV_CODEC_ID_MSMPEG4V1,
    AV_CODEC_ID_MSMPEG4V2,
    AV_CODEC_ID_MSMPEG4V3,
    AV_CODEC_ID_WMV1,
    AV_CODEC_ID_WMV2,
    AV_CODEC_ID_H263P,
    AV_CODEC_ID_H263I,
    AV_CODEC_ID_FLV1,
    AV_CODEC_ID_SVQ1,
    AV_CODEC_ID_SVQ3,
    AV_CODEC_ID_DVVIDEO,
    AV_CODEC_ID_HUFFYUV,
    AV_CODEC_ID_CYUV,
    AV_CODEC_ID_H264,
    AV_CODEC_ID_INDEO3,
    AV_CODEC_ID_VP3,
    AV_CODEC_ID_THEORA,
    AV_CODEC_ID_ASV1,
    AV_CODEC_ID_ASV2,
    AV_CODEC_ID_FFV1,
    AV_CODEC_ID_4XM,
    AV_CODEC_ID_VCR1,
    AV_CODEC_ID_CLJR,
    AV_CODEC_ID_MDEC,
    AV_CODEC_ID_ROQ,
    AV_CODEC_ID_INTERPLAY_VIDEO,
    AV_CODEC_ID_XAN_WC3,
    AV_CODEC_ID_XAN_WC4,
    AV_CODEC_ID_RPZA,
    AV_CODEC_ID_CINEPAK,
    AV_CODEC_ID_WS_VQA,
    AV_CODEC_ID_MSRLE,
    AV_CODEC_ID_MSVIDEO1,
    AV_CODEC_ID_IDCIN,
    AV_CODEC_ID_8BPS,
    AV_CODEC_ID_SMC,
    AV_CODEC_ID_FLIC,
    AV_CODEC_ID_TRUEMOTION1,
    AV_CODEC_ID_VMDVIDEO,
    AV_CODEC_ID_MSZH,
    AV_CODEC_ID_ZLIB,
    AV_CODEC_ID_QTRLE,
    AV_CODEC_ID_TSCC,
    AV_CODEC_ID_ULTI,
    AV_CODEC_ID_QDRAW,
    AV_CODEC_ID_VIXL,
    AV_CODEC_ID_QPEG,
    AV_CODEC_ID_PNG,
    AV_CODEC_ID_PPM,
    AV_CODEC_ID_PBM,
    AV_CODEC_ID_PGM,
    AV_CODEC_ID_PGMYUV,
    AV_CODEC_ID_PAM,
    AV_CODEC_ID_FFVHUFF,
    AV_CODEC_ID_RV30,
    AV_CODEC_ID_RV40,
    AV_CODEC_ID_VC1,
    AV_CODEC_ID_WMV3,
    AV_CODEC_ID_LOCO,
    AV_CODEC_ID_WNV1,
    AV_CODEC_ID_AASC,
    AV_CODEC_ID_INDEO2,
    AV_CODEC_ID_FRAPS,
    AV_CODEC_ID_TRUEMOTION2,
    AV_CODEC_ID_BMP,
    AV_CODEC_ID_CSCD,
    AV_CODEC_ID_MMVIDEO,
    AV_CODEC_ID_ZMBV,
    AV_CODEC_ID_AVS,
    AV_CODEC_ID_SMACKVIDEO,
    AV_CODEC_ID_NUV,
    AV_CODEC_ID_KMVC,
    AV_CODEC_ID_FLASHSV,
    AV_CODEC_ID_CAVS,
    AV_CODEC_ID_JPEG2000,
    AV_CODEC_ID_VMNC,
    AV_CODEC_ID_VP5,
    AV_CODEC_ID_VP6,
    AV_CODEC_ID_VP6F,
    AV_CODEC_ID_TARGA,
    AV_CODEC_ID_DSICINVIDEO,
    AV_CODEC_ID_TIERTEXSEQVIDEO,
    AV_CODEC_ID_TIFF,
    AV_CODEC_ID_GIF,
    AV_CODEC_ID_DXA,
    AV_CODEC_ID_DNXHD,
    AV_CODEC_ID_THP,
    AV_CODEC_ID_SGI,
    AV_CODEC_ID_C93,
    AV_CODEC_ID_BETHSOFTVID,
    AV_CODEC_ID_PTX,
    AV_CODEC_ID_TXD,
    AV_CODEC_ID_VP6A,
    AV_CODEC_ID_AMV,
    AV_CODEC_ID_VB,
    AV_CODEC_ID_PCX,
    AV_CODEC_ID_SUNRAST,
    AV_CODEC_ID_INDEO4,
    AV_CODEC_ID_INDEO5,
    AV_CODEC_ID_MIMIC,
    AV_CODEC_ID_RL2,
    AV_CODEC_ID_ESCAPE124,
    AV_CODEC_ID_DIRAC,
    AV_CODEC_ID_BFI,
    AV_CODEC_ID_CMV,
    AV_CODEC_ID_MOTIONPIXELS,
    AV_CODEC_ID_TGV,
    AV_CODEC_ID_TGQ,
    AV_CODEC_ID_TQI,
    AV_CODEC_ID_AURA,
    AV_CODEC_ID_AURA2,
    AV_CODEC_ID_V210X,
    AV_CODEC_ID_TMV,
    AV_CODEC_ID_V210,
    AV_CODEC_ID_DPX,
    AV_CODEC_ID_MAD,
    AV_CODEC_ID_FRWU,
    AV_CODEC_ID_FLASHSV2,
    AV_CODEC_ID_CDGRAPHICS,
    AV_CODEC_ID_R210,
    AV_CODEC_ID_ANM,
    AV_CODEC_ID_BINKVIDEO,
    AV_CODEC_ID_IFF_ILBM,
    AV_CODEC_ID_IFF_BYTERUN1,
    AV_CODEC_ID_KGV1,
    AV_CODEC_ID_YOP,
    AV_CODEC_ID_VP8,
    AV_CODEC_ID_PICTOR,
    AV_CODEC_ID_ANSI,
    AV_CODEC_ID_A64_MULTI,
    AV_CODEC_ID_A64_MULTI5,
    AV_CODEC_ID_R10K,
    AV_CODEC_ID_MXPEG,
    AV_CODEC_ID_LAGARITH,
    AV_CODEC_ID_PRORES,
    AV_CODEC_ID_JV,
    AV_CODEC_ID_DFA,
    AV_CODEC_ID_WMV3IMAGE,
    AV_CODEC_ID_VC1IMAGE,
    AV_CODEC_ID_UTVIDEO,
    AV_CODEC_ID_BMV_VIDEO,
    AV_CODEC_ID_VBLE,
    AV_CODEC_ID_DXTORY,
    AV_CODEC_ID_V410,
    AV_CODEC_ID_XWD,
    AV_CODEC_ID_CDXL,
    AV_CODEC_ID_XBM,
    AV_CODEC_ID_ZEROCODEC,
    AV_CODEC_ID_MSS1,
    AV_CODEC_ID_MSA1,
    AV_CODEC_ID_TSCC2,
    AV_CODEC_ID_MTS2,
    AV_CODEC_ID_CLLC,
Alberto Delmás's avatar
Alberto Delmás committed
272
    AV_CODEC_ID_MSS2,
Tom Finegan's avatar
Tom Finegan committed
273
    AV_CODEC_ID_VP9,
274
    AV_CODEC_ID_AIC,
275
    AV_CODEC_ID_ESCAPE130_DEPRECATED,
276
    AV_CODEC_ID_G2M_DEPRECATED,
277

278
    AV_CODEC_ID_BRENDER_PIX= MKBETAG('B','P','I','X'),
279 280 281 282 283
    AV_CODEC_ID_Y41P       = MKBETAG('Y','4','1','P'),
    AV_CODEC_ID_ESCAPE130  = MKBETAG('E','1','3','0'),
    AV_CODEC_ID_EXR        = MKBETAG('0','E','X','R'),
    AV_CODEC_ID_AVRP       = MKBETAG('A','V','R','P'),

Carl Eugen Hoyos's avatar
Carl Eugen Hoyos committed
284
    AV_CODEC_ID_012V       = MKBETAG('0','1','2','V'),
285 286 287
    AV_CODEC_ID_G2M        = MKBETAG( 0 ,'G','2','M'),
    AV_CODEC_ID_AVUI       = MKBETAG('A','V','U','I'),
    AV_CODEC_ID_AYUV       = MKBETAG('A','Y','U','V'),
288
    AV_CODEC_ID_TARGA_Y216 = MKBETAG('T','2','1','6'),
289 290 291 292 293
    AV_CODEC_ID_V308       = MKBETAG('V','3','0','8'),
    AV_CODEC_ID_V408       = MKBETAG('V','4','0','8'),
    AV_CODEC_ID_YUV4       = MKBETAG('Y','U','V','4'),
    AV_CODEC_ID_SANM       = MKBETAG('S','A','N','M'),
    AV_CODEC_ID_PAF_VIDEO  = MKBETAG('P','A','F','V'),
294
    AV_CODEC_ID_AVRN       = MKBETAG('A','V','R','n'),
Stephan Hilb's avatar
Stephan Hilb committed
295
    AV_CODEC_ID_CPIA       = MKBETAG('C','P','I','A'),
296
    AV_CODEC_ID_XFACE      = MKBETAG('X','F','A','C'),
Peter Ross's avatar
Peter Ross committed
297
    AV_CODEC_ID_SGIRLE     = MKBETAG('S','G','I','R'),
298 299
    AV_CODEC_ID_MVC1       = MKBETAG('M','V','C','1'),
    AV_CODEC_ID_MVC2       = MKBETAG('M','V','C','2'),
300
    AV_CODEC_ID_SNOW       = MKBETAG('S','N','O','W'),
301
    AV_CODEC_ID_WEBP       = MKBETAG('W','E','B','P'),
Ash Hughes's avatar
Ash Hughes committed
302
    AV_CODEC_ID_SMVJPEG    = MKBETAG('S','M','V','J'),
Dirk Farin's avatar
Dirk Farin committed
303
    AV_CODEC_ID_H265       = MKBETAG('H','2','6','5'),
304

Diego Biurrun's avatar
Diego Biurrun committed
305
    /* various PCM "codecs" */
306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334
    AV_CODEC_ID_FIRST_AUDIO = 0x10000,     ///< A dummy id pointing at the start of audio codecs
    AV_CODEC_ID_PCM_S16LE = 0x10000,
    AV_CODEC_ID_PCM_S16BE,
    AV_CODEC_ID_PCM_U16LE,
    AV_CODEC_ID_PCM_U16BE,
    AV_CODEC_ID_PCM_S8,
    AV_CODEC_ID_PCM_U8,
    AV_CODEC_ID_PCM_MULAW,
    AV_CODEC_ID_PCM_ALAW,
    AV_CODEC_ID_PCM_S32LE,
    AV_CODEC_ID_PCM_S32BE,
    AV_CODEC_ID_PCM_U32LE,
    AV_CODEC_ID_PCM_U32BE,
    AV_CODEC_ID_PCM_S24LE,
    AV_CODEC_ID_PCM_S24BE,
    AV_CODEC_ID_PCM_U24LE,
    AV_CODEC_ID_PCM_U24BE,
    AV_CODEC_ID_PCM_S24DAUD,
    AV_CODEC_ID_PCM_ZORK,
    AV_CODEC_ID_PCM_S16LE_PLANAR,
    AV_CODEC_ID_PCM_DVD,
    AV_CODEC_ID_PCM_F32BE,
    AV_CODEC_ID_PCM_F32LE,
    AV_CODEC_ID_PCM_F64BE,
    AV_CODEC_ID_PCM_F64LE,
    AV_CODEC_ID_PCM_BLURAY,
    AV_CODEC_ID_PCM_LXF,
    AV_CODEC_ID_S302M,
    AV_CODEC_ID_PCM_S8_PLANAR,
335 336
    AV_CODEC_ID_PCM_S24LE_PLANAR = MKBETAG(24,'P','S','P'),
    AV_CODEC_ID_PCM_S32LE_PLANAR = MKBETAG(32,'P','S','P'),
337
    AV_CODEC_ID_PCM_S16BE_PLANAR = MKBETAG('P','S','P',16),
338

Diego Biurrun's avatar
Diego Biurrun committed
339
    /* various ADPCM codecs */
340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369
    AV_CODEC_ID_ADPCM_IMA_QT = 0x11000,
    AV_CODEC_ID_ADPCM_IMA_WAV,
    AV_CODEC_ID_ADPCM_IMA_DK3,
    AV_CODEC_ID_ADPCM_IMA_DK4,
    AV_CODEC_ID_ADPCM_IMA_WS,
    AV_CODEC_ID_ADPCM_IMA_SMJPEG,
    AV_CODEC_ID_ADPCM_MS,
    AV_CODEC_ID_ADPCM_4XM,
    AV_CODEC_ID_ADPCM_XA,
    AV_CODEC_ID_ADPCM_ADX,
    AV_CODEC_ID_ADPCM_EA,
    AV_CODEC_ID_ADPCM_G726,
    AV_CODEC_ID_ADPCM_CT,
    AV_CODEC_ID_ADPCM_SWF,
    AV_CODEC_ID_ADPCM_YAMAHA,
    AV_CODEC_ID_ADPCM_SBPRO_4,
    AV_CODEC_ID_ADPCM_SBPRO_3,
    AV_CODEC_ID_ADPCM_SBPRO_2,
    AV_CODEC_ID_ADPCM_THP,
    AV_CODEC_ID_ADPCM_IMA_AMV,
    AV_CODEC_ID_ADPCM_EA_R1,
    AV_CODEC_ID_ADPCM_EA_R3,
    AV_CODEC_ID_ADPCM_EA_R2,
    AV_CODEC_ID_ADPCM_IMA_EA_SEAD,
    AV_CODEC_ID_ADPCM_IMA_EA_EACS,
    AV_CODEC_ID_ADPCM_EA_XAS,
    AV_CODEC_ID_ADPCM_EA_MAXIS_XA,
    AV_CODEC_ID_ADPCM_IMA_ISS,
    AV_CODEC_ID_ADPCM_G722,
    AV_CODEC_ID_ADPCM_IMA_APC,
370
    AV_CODEC_ID_VIMA       = MKBETAG('V','I','M','A'),
Paul B Mahol's avatar
Paul B Mahol committed
371
    AV_CODEC_ID_ADPCM_AFC  = MKBETAG('A','F','C',' '),
372
    AV_CODEC_ID_ADPCM_IMA_OKI = MKBETAG('O','K','I',' '),
James Almer's avatar
James Almer committed
373
    AV_CODEC_ID_ADPCM_DTK  = MKBETAG('D','T','K',' '),
James Almer's avatar
James Almer committed
374
    AV_CODEC_ID_ADPCM_IMA_RAD = MKBETAG('R','A','D',' '),
375

376
    /* AMR */
377 378
    AV_CODEC_ID_AMR_NB = 0x12000,
    AV_CODEC_ID_AMR_WB,
379

380
    /* RealAudio codecs*/
381 382
    AV_CODEC_ID_RA_144 = 0x13000,
    AV_CODEC_ID_RA_288,
383 384

    /* various DPCM codecs */
385 386 387 388
    AV_CODEC_ID_ROQ_DPCM = 0x14000,
    AV_CODEC_ID_INTERPLAY_DPCM,
    AV_CODEC_ID_XAN_DPCM,
    AV_CODEC_ID_SOL_DPCM,
389

390
    /* audio codecs */
391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422
    AV_CODEC_ID_MP2 = 0x15000,
    AV_CODEC_ID_MP3, ///< preferred ID for decoding MPEG audio layer 1, 2 or 3
    AV_CODEC_ID_AAC,
    AV_CODEC_ID_AC3,
    AV_CODEC_ID_DTS,
    AV_CODEC_ID_VORBIS,
    AV_CODEC_ID_DVAUDIO,
    AV_CODEC_ID_WMAV1,
    AV_CODEC_ID_WMAV2,
    AV_CODEC_ID_MACE3,
    AV_CODEC_ID_MACE6,
    AV_CODEC_ID_VMDAUDIO,
    AV_CODEC_ID_FLAC,
    AV_CODEC_ID_MP3ADU,
    AV_CODEC_ID_MP3ON4,
    AV_CODEC_ID_SHORTEN,
    AV_CODEC_ID_ALAC,
    AV_CODEC_ID_WESTWOOD_SND1,
    AV_CODEC_ID_GSM, ///< as in Berlin toast format
    AV_CODEC_ID_QDM2,
    AV_CODEC_ID_COOK,
    AV_CODEC_ID_TRUESPEECH,
    AV_CODEC_ID_TTA,
    AV_CODEC_ID_SMACKAUDIO,
    AV_CODEC_ID_QCELP,
    AV_CODEC_ID_WAVPACK,
    AV_CODEC_ID_DSICINAUDIO,
    AV_CODEC_ID_IMC,
    AV_CODEC_ID_MUSEPACK7,
    AV_CODEC_ID_MLP,
    AV_CODEC_ID_GSM_MS, /* as found in WAV */
    AV_CODEC_ID_ATRAC3,
423
#if FF_API_VOXWARE
424
    AV_CODEC_ID_VOXWARE,
425
#endif
426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453
    AV_CODEC_ID_APE,
    AV_CODEC_ID_NELLYMOSER,
    AV_CODEC_ID_MUSEPACK8,
    AV_CODEC_ID_SPEEX,
    AV_CODEC_ID_WMAVOICE,
    AV_CODEC_ID_WMAPRO,
    AV_CODEC_ID_WMALOSSLESS,
    AV_CODEC_ID_ATRAC3P,
    AV_CODEC_ID_EAC3,
    AV_CODEC_ID_SIPR,
    AV_CODEC_ID_MP1,
    AV_CODEC_ID_TWINVQ,
    AV_CODEC_ID_TRUEHD,
    AV_CODEC_ID_MP4ALS,
    AV_CODEC_ID_ATRAC1,
    AV_CODEC_ID_BINKAUDIO_RDFT,
    AV_CODEC_ID_BINKAUDIO_DCT,
    AV_CODEC_ID_AAC_LATM,
    AV_CODEC_ID_QDMC,
    AV_CODEC_ID_CELT,
    AV_CODEC_ID_G723_1,
    AV_CODEC_ID_G729,
    AV_CODEC_ID_8SVX_EXP,
    AV_CODEC_ID_8SVX_FIB,
    AV_CODEC_ID_BMV_AUDIO,
    AV_CODEC_ID_RALF,
    AV_CODEC_ID_IAC,
    AV_CODEC_ID_ILBC,
454
    AV_CODEC_ID_OPUS_DEPRECATED,
455
    AV_CODEC_ID_COMFORT_NOISE,
456
    AV_CODEC_ID_TAK_DEPRECATED,
457
    AV_CODEC_ID_METASOUND,
458 459 460 461 462
    AV_CODEC_ID_FFWAVESYNTH = MKBETAG('F','F','W','S'),
    AV_CODEC_ID_SONIC       = MKBETAG('S','O','N','C'),
    AV_CODEC_ID_SONIC_LS    = MKBETAG('S','O','N','L'),
    AV_CODEC_ID_PAF_AUDIO   = MKBETAG('P','A','F','A'),
    AV_CODEC_ID_OPUS        = MKBETAG('O','P','U','S'),
463
    AV_CODEC_ID_TAK         = MKBETAG('t','B','a','K'),
464 465
    AV_CODEC_ID_EVRC        = MKBETAG('s','e','v','c'),
    AV_CODEC_ID_SMV         = MKBETAG('s','s','m','v'),
466

467
    /* subtitle codecs */
468 469 470 471 472 473 474 475 476 477
    AV_CODEC_ID_FIRST_SUBTITLE = 0x17000,          ///< A dummy ID pointing at the start of subtitle codecs.
    AV_CODEC_ID_DVD_SUBTITLE = 0x17000,
    AV_CODEC_ID_DVB_SUBTITLE,
    AV_CODEC_ID_TEXT,  ///< raw UTF-8 text
    AV_CODEC_ID_XSUB,
    AV_CODEC_ID_SSA,
    AV_CODEC_ID_MOV_TEXT,
    AV_CODEC_ID_HDMV_PGS_SUBTITLE,
    AV_CODEC_ID_DVB_TELETEXT,
    AV_CODEC_ID_SRT,
478 479 480 481 482
    AV_CODEC_ID_MICRODVD   = MKBETAG('m','D','V','D'),
    AV_CODEC_ID_EIA_608    = MKBETAG('c','6','0','8'),
    AV_CODEC_ID_JACOSUB    = MKBETAG('J','S','U','B'),
    AV_CODEC_ID_SAMI       = MKBETAG('S','A','M','I'),
    AV_CODEC_ID_REALTEXT   = MKBETAG('R','T','X','T'),
483
    AV_CODEC_ID_SUBVIEWER1 = MKBETAG('S','b','V','1'),
484
    AV_CODEC_ID_SUBVIEWER  = MKBETAG('S','u','b','V'),
485
    AV_CODEC_ID_SUBRIP     = MKBETAG('S','R','i','p'),
486
    AV_CODEC_ID_WEBVTT     = MKBETAG('W','V','T','T'),
487
    AV_CODEC_ID_MPL2       = MKBETAG('M','P','L','2'),
488
    AV_CODEC_ID_VPLAYER    = MKBETAG('V','P','l','r'),
489
    AV_CODEC_ID_PJS        = MKBETAG('P','h','J','S'),
490
    AV_CODEC_ID_ASS        = MKBETAG('A','S','S',' '),  ///< ASS as defined in Matroska
491

Diego Biurrun's avatar
Diego Biurrun committed
492
    /* other specific kind of codecs (generally used for attachments) */
493 494
    AV_CODEC_ID_FIRST_UNKNOWN = 0x18000,           ///< A dummy ID pointing at the start of various fake codecs.
    AV_CODEC_ID_TTF = 0x18000,
495 496 497
    AV_CODEC_ID_BINTEXT    = MKBETAG('B','T','X','T'),
    AV_CODEC_ID_XBIN       = MKBETAG('X','B','I','N'),
    AV_CODEC_ID_IDF        = MKBETAG( 0 ,'I','D','F'),
498
    AV_CODEC_ID_OTF        = MKBETAG( 0 ,'O','T','F'),
499
    AV_CODEC_ID_SMPTE_KLV  = MKBETAG('K','L','V','A'),
500 501
    AV_CODEC_ID_DVD_NAV    = MKBETAG('D','N','A','V'),

502

503
    AV_CODEC_ID_PROBE = 0x19000, ///< codec_id is not known (like AV_CODEC_ID_NONE) but lavf should attempt to identify it
504

505
    AV_CODEC_ID_MPEG2TS = 0x20000, /**< _FAKE_ codec to indicate a raw MPEG-2 TS
Diego Biurrun's avatar
Diego Biurrun committed
506
                                * stream (only used by libavformat) */
507
    AV_CODEC_ID_MPEG4SYSTEMS = 0x20001, /**< _FAKE_ codec to indicate a MPEG-4 Systems
508
                                * stream (only used by libavformat) */
509
    AV_CODEC_ID_FFMETADATA = 0x21000,   ///< Dummy codec for streams containing only metadata information.
510 511 512 513

#if FF_API_CODEC_ID
#include "old_codec_ids.h"
#endif
Fabrice Bellard's avatar
Fabrice Bellard committed
514
};
515

516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533
/**
 * This struct describes the properties of a single codec described by an
 * AVCodecID.
 * @see avcodec_get_descriptor()
 */
typedef struct AVCodecDescriptor {
    enum AVCodecID     id;
    enum AVMediaType type;
    /**
     * Name of the codec described by this descriptor. It is non-empty and
     * unique for each codec descriptor. It should contain alphanumeric
     * characters and '_' only.
     */
    const char      *name;
    /**
     * A more descriptive name for this codec. May be NULL.
     */
    const char *long_name;
534 535 536 537
    /**
     * Codec properties, a combination of AV_CODEC_PROP_* flags.
     */
    int             props;
538 539
} AVCodecDescriptor;

540 541 542 543 544
/**
 * Codec uses only intra compression.
 * Video codecs only.
 */
#define AV_CODEC_PROP_INTRA_ONLY    (1 << 0)
545 546 547 548 549 550 551 552 553 554
/**
 * Codec supports lossy compression. Audio and video codecs only.
 * @note a codec may support both lossy and lossless
 * compression modes
 */
#define AV_CODEC_PROP_LOSSY         (1 << 1)
/**
 * Codec supports lossless compression. Audio and video codecs only.
 */
#define AV_CODEC_PROP_LOSSLESS      (1 << 2)
555 556
/**
 * Subtitle codec is bitmap based
557
 * Decoded AVSubtitle data can be read from the AVSubtitleRect->pict field.
558 559
 */
#define AV_CODEC_PROP_BITMAP_SUB    (1 << 16)
560 561 562 563 564
/**
 * Subtitle codec is text based.
 * Decoded AVSubtitle data can be read from the AVSubtitleRect->ass field.
 */
#define AV_CODEC_PROP_TEXT_SUB      (1 << 17)
565

566
/**
567
 * @ingroup lavc_decoding
568
 * Required number of additionally allocated bytes at the end of the input bitstream for decoding.
569 570
 * This is mainly needed because some optimized bitstream readers read
 * 32 or 64 bit at once and could read over the end.<br>
Diego Biurrun's avatar
Diego Biurrun committed
571 572
 * Note: If the first 23 bits of the additional bytes are not 0, then damaged
 * MPEG bitstreams could cause overread and segfault.
573
 */
574
#define FF_INPUT_BUFFER_PADDING_SIZE 16
575

576
/**
577
 * @ingroup lavc_encoding
Diego Biurrun's avatar
Diego Biurrun committed
578 579
 * minimum encoding buffer size
 * Used to avoid some checks during header writing.
580 581 582
 */
#define FF_MIN_BUFFER_SIZE 16384

583

584
/**
585
 * @ingroup lavc_encoding
586
 * motion estimation type.
587
 */
588
enum Motion_Est_ID {
589
    ME_ZERO = 1,    ///< no search, that is use 0,0 vector whenever one is needed
590 591 592
    ME_FULL,
    ME_LOG,
    ME_PHODS,
593 594 595 596
    ME_EPZS,        ///< enhanced predictive zonal search
    ME_X1,          ///< reserved for experiments
    ME_HEX,         ///< hexagon based search
    ME_UMH,         ///< uneven multi-hexagon search
Loren Merritt's avatar
Loren Merritt committed
597
    ME_TESA,        ///< transformed exhaustive search algorithm
598
    ME_ITER=50,     ///< iterative search
599 600
};

601 602 603
/**
 * @ingroup lavc_decoding
 */
Michael Niedermayer's avatar
Michael Niedermayer committed
604
enum AVDiscard{
Diego Biurrun's avatar
Diego Biurrun committed
605 606
    /* We leave some space between them for extensions (drop some
     * keyframes for intra-only or drop just some bidir frames). */
607 608 609 610 611 612
    AVDISCARD_NONE    =-16, ///< discard nothing
    AVDISCARD_DEFAULT =  0, ///< discard useless packets like 0 size packets in avi
    AVDISCARD_NONREF  =  8, ///< discard all non reference
    AVDISCARD_BIDIR   = 16, ///< discard all bidirectional frames
    AVDISCARD_NONKEY  = 32, ///< discard all frames except keyframes
    AVDISCARD_ALL     = 48, ///< discard all
Michael Niedermayer's avatar
Michael Niedermayer committed
613 614
};

615
enum AVColorPrimaries{
616 617 618 619 620 621 622 623
    AVCOL_PRI_BT709       = 1, ///< also ITU-R BT1361 / IEC 61966-2-4 / SMPTE RP177 Annex B
    AVCOL_PRI_UNSPECIFIED = 2,
    AVCOL_PRI_BT470M      = 4,
    AVCOL_PRI_BT470BG     = 5, ///< also ITU-R BT601-6 625 / ITU-R BT1358 625 / ITU-R BT1700 625 PAL & SECAM
    AVCOL_PRI_SMPTE170M   = 6, ///< also ITU-R BT601-6 525 / ITU-R BT1358 525 / ITU-R BT1700 NTSC
    AVCOL_PRI_SMPTE240M   = 7, ///< functionally identical to above
    AVCOL_PRI_FILM        = 8,
    AVCOL_PRI_NB             , ///< Not part of ABI
624 625 626
};

enum AVColorTransferCharacteristic{
627 628 629 630
    AVCOL_TRC_BT709       = 1, ///< also ITU-R BT1361
    AVCOL_TRC_UNSPECIFIED = 2,
    AVCOL_TRC_GAMMA22     = 4, ///< also ITU-R BT470M / ITU-R BT1700 625 PAL & SECAM
    AVCOL_TRC_GAMMA28     = 5, ///< also ITU-R BT470BG
631
    AVCOL_TRC_SMPTE240M   = 7,
632
    AVCOL_TRC_NB             , ///< Not part of ABI
633 634
};

635 636 637 638 639 640
/**
 *  X   X      3 4 X      X are luma samples,
 *             1 2        1-6 are possible chroma positions
 *  X   X      5 6 X      0 is undefined/unknown position
 */
enum AVChromaLocation{
641 642 643 644 645 646 647 648
    AVCHROMA_LOC_UNSPECIFIED = 0,
    AVCHROMA_LOC_LEFT        = 1, ///< mpeg2/4, h264 default
    AVCHROMA_LOC_CENTER      = 2, ///< mpeg1, jpeg, h263
    AVCHROMA_LOC_TOPLEFT     = 3, ///< DV
    AVCHROMA_LOC_TOP         = 4,
    AVCHROMA_LOC_BOTTOMLEFT  = 5,
    AVCHROMA_LOC_BOTTOM      = 6,
    AVCHROMA_LOC_NB             , ///< Not part of ABI
649 650
};

651 652 653 654 655 656 657 658 659 660 661 662 663
enum AVAudioServiceType {
    AV_AUDIO_SERVICE_TYPE_MAIN              = 0,
    AV_AUDIO_SERVICE_TYPE_EFFECTS           = 1,
    AV_AUDIO_SERVICE_TYPE_VISUALLY_IMPAIRED = 2,
    AV_AUDIO_SERVICE_TYPE_HEARING_IMPAIRED  = 3,
    AV_AUDIO_SERVICE_TYPE_DIALOGUE          = 4,
    AV_AUDIO_SERVICE_TYPE_COMMENTARY        = 5,
    AV_AUDIO_SERVICE_TYPE_EMERGENCY         = 6,
    AV_AUDIO_SERVICE_TYPE_VOICE_OVER        = 7,
    AV_AUDIO_SERVICE_TYPE_KARAOKE           = 8,
    AV_AUDIO_SERVICE_TYPE_NB                   , ///< Not part of ABI
};

664 665 666
/**
 * @ingroup lavc_encoding
 */
667 668 669
typedef struct RcOverride{
    int start_frame;
    int end_frame;
Diego Biurrun's avatar
Diego Biurrun committed
670
    int qscale; // If this is 0 then quality_factor will be used instead.
671 672 673
    float quality_factor;
} RcOverride;

674
#define FF_MAX_B_FRAMES 16
675

676
/* encoding support
Diego Biurrun's avatar
Diego Biurrun committed
677 678
   These flags can be passed in AVCodecContext.flags before initialization.
   Note: Not everything is supported yet.
679
*/
Fabrice Bellard's avatar
Fabrice Bellard committed
680

681 682 683 684 685
/**
 * Allow decoders to produce frames with data planes that are not aligned
 * to CPU requirements (e.g. due to cropping).
 */
#define CODEC_FLAG_UNALIGNED 0x0001
Diego Biurrun's avatar
Diego Biurrun committed
686 687 688 689 690
#define CODEC_FLAG_QSCALE 0x0002  ///< Use fixed qscale.
#define CODEC_FLAG_4MV    0x0004  ///< 4 MV per MB allowed / advanced prediction for H.263.
#define CODEC_FLAG_QPEL   0x0010  ///< Use qpel MC.
#define CODEC_FLAG_GMC    0x0020  ///< Use GMC.
#define CODEC_FLAG_MV0    0x0040  ///< Always try a MB with MV=<0,0>.
691 692
/**
 * The parent program guarantees that the input for B-frames containing
Diego Biurrun's avatar
Diego Biurrun committed
693
 * streams is not written to for at least s->max_b_frames+1 frames, if
694 695
 * this is not set the input will be copied.
 */
696
#define CODEC_FLAG_INPUT_PRESERVED 0x0100
Diego Biurrun's avatar
Diego Biurrun committed
697 698 699 700 701 702 703
#define CODEC_FLAG_PASS1           0x0200   ///< Use internal 2pass ratecontrol in first pass mode.
#define CODEC_FLAG_PASS2           0x0400   ///< Use internal 2pass ratecontrol in second pass mode.
#define CODEC_FLAG_GRAY            0x2000   ///< Only decode/encode grayscale.
#define CODEC_FLAG_EMU_EDGE        0x4000   ///< Don't draw edges.
#define CODEC_FLAG_PSNR            0x8000   ///< error[?] variables will be set during encoding.
#define CODEC_FLAG_TRUNCATED       0x00010000 /** Input bitstream might be truncated at a random
                                                  location instead of only at frame boundaries. */
Diego Biurrun's avatar
Diego Biurrun committed
704 705 706 707 708
#define CODEC_FLAG_NORMALIZE_AQP  0x00020000 ///< Normalize adaptive quantization.
#define CODEC_FLAG_INTERLACED_DCT 0x00040000 ///< Use interlaced DCT.
#define CODEC_FLAG_LOW_DELAY      0x00080000 ///< Force low delay.
#define CODEC_FLAG_GLOBAL_HEADER  0x00400000 ///< Place global headers in extradata instead of every keyframe.
#define CODEC_FLAG_BITEXACT       0x00800000 ///< Use only bitexact stuff (except (I)DCT).
709
/* Fx : Flag for h263+ extra options */
Diego Biurrun's avatar
Diego Biurrun committed
710
#define CODEC_FLAG_AC_PRED        0x01000000 ///< H.263 advanced intra coding / MPEG-4 AC prediction
Michael Niedermayer's avatar
Michael Niedermayer committed
711
#define CODEC_FLAG_LOOP_FILTER    0x00000800 ///< loop filter
712
#define CODEC_FLAG_INTERLACED_ME  0x20000000 ///< interlaced motion estimation
713
#define CODEC_FLAG_CLOSED_GOP     0x80000000
Diego Biurrun's avatar
Diego Biurrun committed
714 715 716
#define CODEC_FLAG2_FAST          0x00000001 ///< Allow non spec compliant speedup tricks.
#define CODEC_FLAG2_NO_OUTPUT     0x00000004 ///< Skip bitstream encoding.
#define CODEC_FLAG2_LOCAL_HEADER  0x00000008 ///< Place global headers at every keyframe instead of in extradata.
717
#define CODEC_FLAG2_DROP_FRAME_TIMECODE 0x00002000 ///< timecode is in drop frame format. DEPRECATED!!!!
718 719
#define CODEC_FLAG2_IGNORE_CROP   0x00010000 ///< Discard cropping information from SPS.

720
#define CODEC_FLAG2_CHUNKS        0x00008000 ///< Input bitstream might be truncated at a packet boundaries instead of only at frame boundaries.
721
#define CODEC_FLAG2_SHOW_ALL      0x00400000 ///< Show all frames before the first keyframe
722

723
/* Unsupported options :
724 725
 *              Syntax Arithmetic coding (SAC)
 *              Reference Picture Selection
726
 *              Independent Segment Decoding */
727
/* /Fx */
728 729
/* codec capabilities */

Diego Biurrun's avatar
Diego Biurrun committed
730
#define CODEC_CAP_DRAW_HORIZ_BAND 0x0001 ///< Decoder can use draw_horiz_band callback.
731
/**
732 733 734
 * Codec uses get_buffer() for allocating buffers and supports custom allocators.
 * If not set, it might not use get_buffer() at all or use operations that
 * assume the buffer was allocated by avcodec_default_get_buffer.
735 736
 */
#define CODEC_CAP_DR1             0x0002
737
#define CODEC_CAP_TRUNCATED       0x0008
Diego Biurrun's avatar
Diego Biurrun committed
738
/* Codec can export data for HW decoding (XvMC). */
739
#define CODEC_CAP_HWACCEL         0x0010
740
/**
741 742 743 744 745 746 747 748 749 750
 * Encoder or decoder requires flushing with NULL input at the end in order to
 * give the complete and correct output.
 *
 * NOTE: If this flag is not set, the codec is guaranteed to never be fed with
 *       with NULL data. The user can still send NULL data to the public encode
 *       or decode function, but libavcodec will not pass it along to the codec
 *       unless this flag is set.
 *
 * Decoders:
 * The decoder has a non-zero delay and needs to be fed with avpkt->data=NULL,
751
 * avpkt->size=0 at the end to get the delayed data until the decoder no longer
752 753 754 755 756
 * returns frames.
 *
 * Encoders:
 * The encoder needs to be fed with NULL data at the end of encoding until the
 * encoder no longer returns data.
757 758 759 760 761
 *
 * NOTE: For encoders implementing the AVCodec.encode2() function, setting this
 *       flag also means that the encoder must set the pts and duration for
 *       each output packet. If this flag is not set, the pts and duration will
 *       be determined by libavcodec from the input frame.
762
 */
763
#define CODEC_CAP_DELAY           0x0020
764 765 766 767 768
/**
 * Codec can be fed a final frame with a smaller size.
 * This can be used to prevent truncation of the last audio samples.
 */
#define CODEC_CAP_SMALL_LAST_FRAME 0x0040
769
#if FF_API_CAP_VDPAU
770 771 772 773
/**
 * Codec can export data for HW decoding (VDPAU).
 */
#define CODEC_CAP_HWACCEL_VDPAU    0x0080
774
#endif
775 776
/**
 * Codec can output multiple frames per AVPacket
777 778 779 780 781 782 783 784
 * Normally demuxers return one frame at a time, demuxers which do not do
 * are connected to a parser to split what they return into proper frames.
 * This flag is reserved to the very rare category of codecs which have a
 * bitstream that cannot be split into frames without timeconsuming
 * operations like full decoding. Demuxers carring such bitstreams thus
 * may return multiple frames in a packet. This has many disadvantages like
 * prohibiting stream copy in many cases thus it should only be considered
 * as a last resort.
785 786
 */
#define CODEC_CAP_SUBFRAMES        0x0100
787 788 789 790 791
/**
 * Codec is experimental and is thus avoided in favor of non experimental
 * encoders
 */
#define CODEC_CAP_EXPERIMENTAL     0x0200
792 793 794 795
/**
 * Codec should fill in channel configuration and samplerate instead of container
 */
#define CODEC_CAP_CHANNEL_CONF     0x0400
796

797 798 799 800
/**
 * Codec is able to deal with negative linesizes
 */
#define CODEC_CAP_NEG_LINESIZES    0x0800
801

802 803 804 805
/**
 * Codec supports frame-level multithreading.
 */
#define CODEC_CAP_FRAME_THREADS    0x1000
806 807 808 809
/**
 * Codec supports slice-based (or partition-based) multithreading.
 */
#define CODEC_CAP_SLICE_THREADS    0x2000
810 811 812 813
/**
 * Codec supports changed parameters at any point.
 */
#define CODEC_CAP_PARAM_CHANGE     0x4000
814 815 816 817
/**
 * Codec supports avctx->thread_count == 0 (auto).
 */
#define CODEC_CAP_AUTO_THREADS     0x8000
818 819 820 821
/**
 * Audio encoder supports receiving a different number of samples in each call.
 */
#define CODEC_CAP_VARIABLE_FRAME_SIZE 0x10000
822 823 824 825
/**
 * Codec is intra only.
 */
#define CODEC_CAP_INTRA_ONLY       0x40000000
826 827 828 829
/**
 * Codec is lossless.
 */
#define CODEC_CAP_LOSSLESS         0x80000000
830

Diego Biurrun's avatar
Diego Biurrun committed
831
//The following defines may change, don't expect compatibility if you use them.
832
#define MB_TYPE_INTRA4x4   0x0001
Diego Biurrun's avatar
Diego Biurrun committed
833 834
#define MB_TYPE_INTRA16x16 0x0002 //FIXME H.264-specific
#define MB_TYPE_INTRA_PCM  0x0004 //FIXME H.264-specific
835 836 837 838 839
#define MB_TYPE_16x16      0x0008
#define MB_TYPE_16x8       0x0010
#define MB_TYPE_8x16       0x0020
#define MB_TYPE_8x8        0x0040
#define MB_TYPE_INTERLACED 0x0080
Diego Biurrun's avatar
Diego Biurrun committed
840
#define MB_TYPE_DIRECT2    0x0100 //FIXME
841 842 843 844 845 846 847 848 849 850 851 852 853 854
#define MB_TYPE_ACPRED     0x0200
#define MB_TYPE_GMC        0x0400
#define MB_TYPE_SKIP       0x0800
#define MB_TYPE_P0L0       0x1000
#define MB_TYPE_P1L0       0x2000
#define MB_TYPE_P0L1       0x4000
#define MB_TYPE_P1L1       0x8000
#define MB_TYPE_L0         (MB_TYPE_P0L0 | MB_TYPE_P1L0)
#define MB_TYPE_L1         (MB_TYPE_P0L1 | MB_TYPE_P1L1)
#define MB_TYPE_L0L1       (MB_TYPE_L0   | MB_TYPE_L1)
#define MB_TYPE_QUANT      0x00010000
#define MB_TYPE_CBP        0x00020000
//Note bits 24-31 are reserved for codec specific use (h264 ref0, mpeg1 0mv, ...)

855 856
/**
 * Pan Scan area.
Diego Biurrun's avatar
Diego Biurrun committed
857 858
 * This specifies the area which should be displayed.
 * Note there may be multiple such areas for one frame.
859 860 861
 */
typedef struct AVPanScan{
    /**
Diego Biurrun's avatar
Diego Biurrun committed
862 863 864
     * id
     * - encoding: Set by user.
     * - decoding: Set by libavcodec.
865 866 867 868 869
     */
    int id;

    /**
     * width and height in 1/16 pel
Diego Biurrun's avatar
Diego Biurrun committed
870 871
     * - encoding: Set by user.
     * - decoding: Set by libavcodec.
872 873 874 875 876
     */
    int width;
    int height;

    /**
Diego Biurrun's avatar
Diego Biurrun committed
877 878 879
     * position of the top left corner in 1/16 pel for up to 3 fields/frames
     * - encoding: Set by user.
     * - decoding: Set by libavcodec.
880 881 882 883
     */
    int16_t position[3][2];
}AVPanScan;

884 885 886
#define FF_QSCALE_TYPE_MPEG1 0
#define FF_QSCALE_TYPE_MPEG2 1
#define FF_QSCALE_TYPE_H264  2
887
#define FF_QSCALE_TYPE_VP56  3
Michael Niedermayer's avatar
Michael Niedermayer committed
888

889
#if FF_API_GET_BUFFER
Michael Niedermayer's avatar
Michael Niedermayer committed
890
#define FF_BUFFER_TYPE_INTERNAL 1
Diego Biurrun's avatar
Diego Biurrun committed
891 892 893
#define FF_BUFFER_TYPE_USER     2 ///< direct rendering buffers (image is (de)allocated by user)
#define FF_BUFFER_TYPE_SHARED   4 ///< Buffer from somewhere else; don't deallocate image (data/base), all other tables are not shared.
#define FF_BUFFER_TYPE_COPY     8 ///< Just a (modified) copy of some other buffer, don't deallocate anything.
Michael Niedermayer's avatar
Michael Niedermayer committed
894

Diego Biurrun's avatar
Diego Biurrun committed
895 896 897 898
#define FF_BUFFER_HINTS_VALID    0x01 // Buffer hints value is meaningful (if 0 ignore).
#define FF_BUFFER_HINTS_READABLE 0x02 // Codec will read from buffer.
#define FF_BUFFER_HINTS_PRESERVE 0x04 // User must not alter buffer content.
#define FF_BUFFER_HINTS_REUSABLE 0x08 // Codec will reuse the buffer (update).
899 900 901 902 903 904
#endif

/**
 * The decoder will keep a reference to the frame and may reuse it later.
 */
#define AV_GET_BUFFER_FLAG_REF (1 << 0)
905

906 907 908 909 910 911
/**
 * @defgroup lavc_packet AVPacket
 *
 * Types and functions for working with AVPacket.
 * @{
 */
912 913
enum AVPacketSideDataType {
    AV_PKT_DATA_PALETTE,
914
    AV_PKT_DATA_NEW_EXTRADATA,
915 916 917

    /**
     * An AV_PKT_DATA_PARAM_CHANGE side data packet is laid out as follows:
918
     * @code
919 920 921 922 923 924 925 926 927 928
     * u32le param_flags
     * if (param_flags & AV_SIDE_DATA_PARAM_CHANGE_CHANNEL_COUNT)
     *     s32le channel_count
     * if (param_flags & AV_SIDE_DATA_PARAM_CHANGE_CHANNEL_LAYOUT)
     *     u64le channel_layout
     * if (param_flags & AV_SIDE_DATA_PARAM_CHANGE_SAMPLE_RATE)
     *     s32le sample_rate
     * if (param_flags & AV_SIDE_DATA_PARAM_CHANGE_DIMENSIONS)
     *     s32le width
     *     s32le height
929
     * @endcode
930
     */
931
    AV_PKT_DATA_PARAM_CHANGE,
932 933 934 935 936 937 938 939 940

    /**
     * An AV_PKT_DATA_H263_MB_INFO side data packet contains a number of
     * structures with info about macroblocks relevant to splitting the
     * packet into smaller packets on macroblock edges (e.g. as for RFC 2190).
     * That is, it does not necessarily contain info about all macroblocks,
     * as long as the distance between macroblocks in the info is smaller
     * than the target payload size.
     * Each MB info structure is 12 bytes, and is laid out as follows:
941
     * @code
942 943 944 945 946 947 948 949
     * u32le bit offset from the start of the packet
     * u8    current quantizer at the start of the macroblock
     * u8    GOB number
     * u16le macroblock address within the GOB
     * u8    horizontal MV predictor
     * u8    vertical MV predictor
     * u8    horizontal MV predictor for block number 3
     * u8    vertical MV predictor for block number 3
950
     * @endcode
951
     */
952
    AV_PKT_DATA_H263_MB_INFO,
953 954 955 956 957 958 959 960 961 962 963

    /**
     * Recommmends skipping the specified number of samples
     * @code
     * u32le number of samples to skip from start of this packet
     * u32le number of samples to skip from end of this packet
     * u8    reason for start skip
     * u8    reason for end   skip (0=padding silence, 1=convergence)
     * @endcode
     */
    AV_PKT_DATA_SKIP_SAMPLES=70,
964 965 966 967 968 969 970 971 972 973

    /**
     * An AV_PKT_DATA_JP_DUALMONO side data packet indicates that
     * the packet may contain "dual mono" audio specific to Japanese DTV
     * and if it is true, recommends only the selected channel to be used.
     * @code
     * u8    selected channels (0=mail/left, 1=sub/right, 2=both)
     * @endcode
     */
    AV_PKT_DATA_JP_DUALMONO,
974 975 976 977 978 979

    /**
     * A list of zero terminated key/value strings. There is no end marker for
     * the list, so it is required to rely on the side data size to stop.
     */
    AV_PKT_DATA_STRINGS_METADATA,
980 981 982 983 984 985 986 987 988 989 990

    /**
     * Subtitle event position
     * @code
     * u32le x1
     * u32le y1
     * u32le x2
     * u32le y2
     * @endcode
     */
    AV_PKT_DATA_SUBTITLE_POSITION,
991 992 993 994 995 996 997 998

    /**
     * Data found in BlockAdditional element of matroska container. There is
     * no end marker for the data, so it is required to rely on the side data
     * size to recognize the end. 8 byte id (as found in BlockAddId) followed
     * by data.
     */
    AV_PKT_DATA_MATROSKA_BLOCKADDITIONAL,
999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009

    /**
     * The optional first identifier line of a WebVTT cue.
     */
    AV_PKT_DATA_WEBVTT_IDENTIFIER,

    /**
     * The optional settings (rendering instructions) that immediately
     * follow the timestamp specifier of a WebVTT cue.
     */
    AV_PKT_DATA_WEBVTT_SETTINGS,
1010 1011
};

1012 1013 1014 1015 1016 1017 1018 1019
/**
 * This structure stores compressed data. It is typically exported by demuxers
 * and then passed as input to decoders, or received as output from encoders and
 * then passed to muxers.
 *
 * For video, it should typically contain one compressed frame. For audio it may
 * contain several compressed frames.
 *
1020
 * AVPacket is one of the few structs in FFmpeg, whose size is a part of public
1021 1022 1023
 * ABI. Thus it may be allocated on stack and no new fields can be added to it
 * without libavcodec and libavformat major bump.
 *
1024 1025 1026 1027 1028 1029
 * The semantics of data ownership depends on the buf or destruct (deprecated)
 * fields. If either is set, the packet data is dynamically allocated and is
 * valid indefinitely until av_free_packet() is called (which in turn calls
 * av_buffer_unref()/the destruct callback to free the data). If neither is set,
 * the packet data is typically backed by some static buffer somewhere and is
 * only valid for a limited time (e.g. until the next read call when demuxing).
1030 1031 1032 1033
 *
 * The side data is always allocated with av_malloc() and is freed in
 * av_free_packet().
 */
1034
typedef struct AVPacket {
1035 1036 1037 1038 1039 1040
    /**
     * A reference to the reference-counted buffer where the packet data is
     * stored.
     * May be NULL, then the packet data is not reference-counted.
     */
    AVBufferRef *buf;
1041
    /**
1042 1043
     * Presentation timestamp in AVStream->time_base units; the time at which
     * the decompressed packet will be presented to the user.
1044 1045 1046 1047 1048 1049 1050 1051
     * Can be AV_NOPTS_VALUE if it is not stored in the file.
     * pts MUST be larger or equal to dts as presentation cannot happen before
     * decompression, unless one wants to view hex dumps. Some formats misuse
     * the terms dts and pts/cts to mean something different. Such timestamps
     * must be converted to true pts/dts before they are stored in AVPacket.
     */
    int64_t pts;
    /**
1052 1053
     * Decompression timestamp in AVStream->time_base units; the time at which
     * the packet is decompressed.
1054 1055 1056 1057 1058 1059
     * Can be AV_NOPTS_VALUE if it is not stored in the file.
     */
    int64_t dts;
    uint8_t *data;
    int   size;
    int   stream_index;
1060 1061 1062
    /**
     * A combination of AV_PKT_FLAG values
     */
1063
    int   flags;
1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074
    /**
     * Additional packet data that can be provided by the container.
     * Packet can contain several types of side information.
     */
    struct {
        uint8_t *data;
        int      size;
        enum AVPacketSideDataType type;
    } *side_data;
    int side_data_elems;

1075
    /**
1076
     * Duration of this packet in AVStream->time_base units, 0 if unknown.
1077 1078 1079
     * Equals next_pts - this_pts in presentation order.
     */
    int   duration;
1080 1081
#if FF_API_DESTRUCT_PACKET
    attribute_deprecated
1082
    void  (*destruct)(struct AVPacket *);
1083
    attribute_deprecated
1084
    void  *priv;
1085
#endif
1086 1087 1088
    int64_t pos;                            ///< byte position in stream, -1 if unknown

    /**
1089
     * Time difference in AVStream->time_base units from the pts of this
1090 1091 1092 1093 1094 1095
     * packet to the point at which the output from the decoder has converged
     * independent from the availability of previous frames. That is, the
     * frames are virtually identical no matter if decoding started from
     * the very first frame or from this keyframe.
     * Is AV_NOPTS_VALUE if unknown.
     * This field is not the display duration of the current packet.
Aurelien Jacobs's avatar
Aurelien Jacobs committed
1096 1097
     * This field has no meaning if the packet does not have AV_PKT_FLAG_KEY
     * set.
1098 1099 1100 1101 1102 1103 1104 1105 1106
     *
     * The purpose of this field is to allow seeking in streams that have no
     * keyframes in the conventional sense. It corresponds to the
     * recovery point SEI in H.264 and match_time_delta in NUT. It is also
     * essential for some types of subtitle streams to ensure that all
     * subtitles are correctly displayed after seeking.
     */
    int64_t convergence_duration;
} AVPacket;
1107 1108
#define AV_PKT_FLAG_KEY     0x0001 ///< The packet contains a keyframe
#define AV_PKT_FLAG_CORRUPT 0x0002 ///< The packet content is corrupted
1109

1110 1111 1112 1113 1114 1115
enum AVSideDataParamChangeFlags {
    AV_SIDE_DATA_PARAM_CHANGE_CHANNEL_COUNT  = 0x0001,
    AV_SIDE_DATA_PARAM_CHANGE_CHANNEL_LAYOUT = 0x0002,
    AV_SIDE_DATA_PARAM_CHANGE_SAMPLE_RATE    = 0x0004,
    AV_SIDE_DATA_PARAM_CHANGE_DIMENSIONS     = 0x0008,
};
1116 1117 1118
/**
 * @}
 */
1119

1120 1121
struct AVCodecInternal;

1122 1123 1124 1125 1126 1127 1128 1129 1130
enum AVFieldOrder {
    AV_FIELD_UNKNOWN,
    AV_FIELD_PROGRESSIVE,
    AV_FIELD_TT,          //< Top coded_first, top displayed first
    AV_FIELD_BB,          //< Bottom coded first, bottom displayed first
    AV_FIELD_TB,          //< Top coded first, bottom displayed first
    AV_FIELD_BT,          //< Bottom coded first, top displayed first
};

Michael Niedermayer's avatar
Michael Niedermayer committed
1131
/**
1132 1133
 * main external API structure.
 * New fields can be added to the end with minor version bumps.
Diego Biurrun's avatar
Diego Biurrun committed
1134
 * Removal, reordering and changes to existing fields require a major
1135
 * version bump.
1136
 * Please use AVOptions (av_opt* / av_set/get*()) to access these fields from user
1137
 * applications.
Diego Biurrun's avatar
Diego Biurrun committed
1138
 * sizeof(AVCodecContext) must not be used outside libav*.
Michael Niedermayer's avatar
Michael Niedermayer committed
1139
 */
Fabrice Bellard's avatar
Fabrice Bellard committed
1140
typedef struct AVCodecContext {
1141
    /**
Diego Biurrun's avatar
Diego Biurrun committed
1142
     * information on struct for av_log
1143
     * - set by avcodec_alloc_context3
1144
     */
1145
    const AVClass *av_class;
1146 1147 1148
    int log_level_offset;

    enum AVMediaType codec_type; /* see AVMEDIA_TYPE_xxx */
1149
    const struct AVCodec  *codec;
1150
    char             codec_name[32];
1151
    enum AVCodecID     codec_id; /* see AV_CODEC_ID_xxx */
1152 1153

    /**
1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164
     * fourcc (LSB first, so "ABCD" -> ('D'<<24) + ('C'<<16) + ('B'<<8) + 'A').
     * This is used to work around some encoder bugs.
     * A demuxer should set this to what is stored in the field used to identify the codec.
     * If there are multiple such fields in a container then the demuxer should choose the one
     * which maximizes the information about the used codec.
     * If the codec tag field in a container is larger than 32 bits then the demuxer should
     * remap the longer ID to 32 bits with a table or other structure. Alternatively a new
     * extra_codec_tag + size could be added but for this a clear advantage must be demonstrated
     * first.
     * - encoding: Set by user, if not then the default based on codec_id will be used.
     * - decoding: Set by user, will be converted to uppercase by libavcodec during init.
1165
     */
1166
    unsigned int codec_tag;
1167 1168

    /**
1169 1170 1171 1172
     * fourcc from the AVI stream header (LSB first, so "ABCD" -> ('D'<<24) + ('C'<<16) + ('B'<<8) + 'A').
     * This is used to work around some encoder bugs.
     * - encoding: unused
     * - decoding: Set by user, will be converted to uppercase by libavcodec during init.
1173
     */
1174
    unsigned int stream_codec_tag;
1175

1176 1177
    void *priv_data;

1178
    /**
1179 1180 1181 1182
     * Private context used for internal data.
     *
     * Unlike priv_data, this is not codec-specific. It is used in general
     * libavcodec functions.
1183
     */
1184
    struct AVCodecInternal *internal;
1185 1186

    /**
1187 1188 1189
     * Private data of the user, can be used to carry app specific stuff.
     * - encoding: Set by user.
     * - decoding: Set by user.
1190
     */
1191
    void *opaque;
1192

1193
    /**
Diego Biurrun's avatar
Diego Biurrun committed
1194 1195 1196
     * the average bitrate
     * - encoding: Set by user; unused for constant quantizer encoding.
     * - decoding: Set by libavcodec. 0 or some bitrate if this info is available in the stream.
1197
     */
Fabrice Bellard's avatar
Fabrice Bellard committed
1198
    int bit_rate;
1199

1200
    /**
1201
     * number of bits the bitstream is allowed to diverge from the reference.
1202
     *           the reference can be CBR (for CBR pass1) or VBR (for pass2)
Diego Biurrun's avatar
Diego Biurrun committed
1203
     * - encoding: Set by user; unused for constant quantizer encoding.
1204
     * - decoding: unused
1205
     */
1206 1207
    int bit_rate_tolerance;

1208
    /**
1209 1210
     * Global quality for codecs which cannot change it per frame.
     * This should be proportional to MPEG-1/2/4 qscale.
Diego Biurrun's avatar
Diego Biurrun committed
1211
     * - encoding: Set by user.
1212
     * - decoding: unused
1213
     */
1214
    int global_quality;
1215 1216

    /**
Diego Biurrun's avatar
Diego Biurrun committed
1217
     * - encoding: Set by user.
1218
     * - decoding: unused
1219
     */
1220 1221
    int compression_level;
#define FF_COMPRESSION_DEFAULT -1
1222 1223

    /**
1224
     * CODEC_FLAG_*.
Diego Biurrun's avatar
Diego Biurrun committed
1225
     * - encoding: Set by user.
1226
     * - decoding: Set by user.
1227
     */
1228
    int flags;
1229

1230
    /**
1231 1232
     * CODEC_FLAG2_*
     * - encoding: Set by user.
Diego Biurrun's avatar
Diego Biurrun committed
1233
     * - decoding: Set by user.
1234
     */
1235
    int flags2;
1236

1237
    /**
Diego Biurrun's avatar
Diego Biurrun committed
1238 1239
     * some codecs need / can use extradata like Huffman tables.
     * mjpeg: Huffman tables
1240
     * rv10: additional flags
1241
     * mpeg4: global headers (they can be in the bitstream or here)
Diego Biurrun's avatar
Diego Biurrun committed
1242
     * The allocated memory should be FF_INPUT_BUFFER_PADDING_SIZE bytes larger
1243
     * than extradata_size to avoid problems if it is read with the bitstream reader.
Diego Biurrun's avatar
Diego Biurrun committed
1244 1245 1246
     * The bytewise contents of extradata must not depend on the architecture or CPU endianness.
     * - encoding: Set/allocated/freed by libavcodec.
     * - decoding: Set/allocated/freed by user.
1247
     */
1248
    uint8_t *extradata;
1249
    int extradata_size;
1250 1251

    /**
Diego Biurrun's avatar
Diego Biurrun committed
1252 1253
     * This is the fundamental unit of time (in seconds) in terms
     * of which frame timestamps are represented. For fixed-fps content,
1254 1255
     * timebase should be 1/framerate and timestamp increments should be
     * identically 1.
Diego Biurrun's avatar
Diego Biurrun committed
1256 1257
     * - encoding: MUST be set by user.
     * - decoding: Set by libavcodec.
1258
     */
1259
    AVRational time_base;
Fabrice Bellard's avatar
Fabrice Bellard committed
1260

1261
    /**
1262 1263 1264 1265 1266
     * For some codecs, the time base is closer to the field rate than the frame rate.
     * Most notably, H.264 and MPEG-2 specify time_base as half of frame duration
     * if no telecine is used ...
     *
     * Set to time_base ticks per frame. Default 1, e.g., H.264/MPEG-2 set it to 2.
1267
     */
1268
    int ticks_per_frame;
1269

1270
    /**
1271
     * Codec delay.
1272
     *
1273 1274 1275 1276
     * Encoding: Number of frames delay there will be from the encoder input to
     *           the decoder output. (we assume the decoder matches the spec)
     * Decoding: Number of frames delay in addition to what a standard decoder
     *           as specified in the spec would produce.
1277 1278 1279 1280 1281 1282
     *
     * Video:
     *   Number of frames the decoded output will be delayed relative to the
     *   encoded input.
     *
     * Audio:
1283 1284 1285 1286 1287 1288 1289 1290 1291
     *   For encoding, this is the number of "priming" samples added to the
     *   beginning of the stream. The decoded output will be delayed by this
     *   many samples relative to the input to the encoder. Note that this
     *   field is purely informational and does not directly affect the pts
     *   output by the encoder, which should always be based on the actual
     *   presentation time, including any delay.
     *   For decoding, this is the number of samples the decoder needs to
     *   output before the decoder's output is valid. When seeking, you should
     *   start decoding this many samples prior to your desired seek point.
1292
     *
Diego Biurrun's avatar
Diego Biurrun committed
1293
     * - encoding: Set by libavcodec.
1294
     * - decoding: Set by libavcodec.
1295 1296
     */
    int delay;
1297 1298


1299
    /* video only */
1300
    /**
1301
     * picture width / height.
1302
     * - encoding: MUST be set by user.
1303 1304 1305 1306
     * - decoding: May be set by the user before opening the decoder if known e.g.
     *             from the container. Some decoders will require the dimensions
     *             to be set by the caller. During decoding, the decoder may
     *             overwrite those values as required.
1307
     */
Fabrice Bellard's avatar
Fabrice Bellard committed
1308
    int width, height;
1309 1310

    /**
1311
     * Bitstream width / height, may be different from width/height e.g. when
1312
     * the decoded frame is cropped before being output or lowres is enabled.
1313
     * - encoding: unused
1314 1315 1316
     * - decoding: May be set by the user before opening the decoder if known
     *             e.g. from the container. During decoding, the decoder may
     *             overwrite those values as required.
1317 1318 1319
     */
    int coded_width, coded_height;

1320
#define FF_ASPECT_EXTENDED 15
1321 1322

    /**
Diego Biurrun's avatar
Diego Biurrun committed
1323 1324
     * the number of pictures in a group of pictures, or 0 for intra_only
     * - encoding: Set by user.
1325
     * - decoding: unused
1326 1327 1328 1329
     */
    int gop_size;

    /**
1330
     * Pixel format, see AV_PIX_FMT_xxx.
1331
     * May be set by the demuxer if known from headers.
1332
     * May be overridden by the decoder if it knows better.
Diego Biurrun's avatar
Diego Biurrun committed
1333
     * - encoding: Set by user.
1334
     * - decoding: Set by user if known, overridden by libavcodec if known
1335
     */
1336
    enum AVPixelFormat pix_fmt;
1337

1338 1339 1340 1341 1342
    /**
     * Motion estimation algorithm used for video coding.
     * 1 (zero), 2 (full), 3 (log), 4 (phods), 5 (epzs), 6 (x1), 7 (hex),
     * 8 (umh), 9 (iter), 10 (tesa) [7, 8, 10 are x264 specific, 9 is snow specific]
     * - encoding: MUST be set by user.
1343
     * - decoding: unused
1344
     */
1345 1346
    int me_method;

1347
    /**
Diego Biurrun's avatar
Diego Biurrun committed
1348 1349
     * If non NULL, 'draw_horiz_band' is called by the libavcodec
     * decoder to draw a horizontal band. It improves cache usage. Not
1350
     * all codecs can do that. You must check the codec capabilities
Diego Biurrun's avatar
Diego Biurrun committed
1351
     * beforehand.
1352 1353 1354 1355
     * When multithreading is used, it may be called from multiple threads
     * at the same time; threads might draw different parts of the same AVFrame,
     * or multiple AVFrames, and there is no guarantee that slices will be drawn
     * in order.
1356 1357 1358 1359 1360 1361 1362
     * The function is also used by hardware acceleration APIs.
     * It is called at least once during frame decoding to pass
     * the data needed for hardware render.
     * In that mode instead of pixel data, AVFrame points to
     * a structure specific to the acceleration API. The application
     * reads the structure and can change some fields to indicate progress
     * or mark state.
1363
     * - encoding: unused
Diego Biurrun's avatar
Diego Biurrun committed
1364
     * - decoding: Set by user.
1365 1366 1367 1368
     * @param height the height of the slice
     * @param y the y position of the slice
     * @param type 1->top field, 2->bottom field, 3->frame
     * @param offset offset into the AVFrame.data from which the slice should be read
1369
     */
1370
    void (*draw_horiz_band)(struct AVCodecContext *s,
1371
                            const AVFrame *src, int offset[AV_NUM_DATA_POINTERS],
1372
                            int y, int type, int height);
1373

1374
    /**
1375 1376 1377 1378 1379 1380 1381
     * callback to negotiate the pixelFormat
     * @param fmt is the list of formats which are supported by the codec,
     * it is terminated by -1 as 0 is a valid format, the formats are ordered by quality.
     * The first is always the native one.
     * @return the chosen format
     * - encoding: unused
     * - decoding: Set by user, if not set the native format will be chosen.
1382
     */
1383
    enum AVPixelFormat (*get_format)(struct AVCodecContext *s, const enum AVPixelFormat * fmt);
1384 1385

    /**
Diego Biurrun's avatar
Diego Biurrun committed
1386 1387 1388
     * maximum number of B-frames between non-B-frames
     * Note: The output will be delayed by max_b_frames+1 relative to the input.
     * - encoding: Set by user.
1389
     * - decoding: unused
1390 1391 1392 1393
     */
    int max_b_frames;

    /**
Diego Biurrun's avatar
Diego Biurrun committed
1394
     * qscale factor between IP and B-frames
1395 1396
     * If > 0 then the last P-frame quantizer will be used (q= lastp_q*factor+offset).
     * If < 0 then normal ratecontrol will be done (q= -normal_q*factor+offset).
Diego Biurrun's avatar
Diego Biurrun committed
1397
     * - encoding: Set by user.
1398
     * - decoding: unused
1399 1400
     */
    float b_quant_factor;
1401

1402 1403
    /** obsolete FIXME remove */
    int rc_strategy;
1404 1405
#define FF_RC_STRATEGY_XVID 1

1406
    int b_frame_strategy;
1407

1408
    /**
1409
     * qscale offset between IP and B-frames
Diego Biurrun's avatar
Diego Biurrun committed
1410
     * - encoding: Set by user.
1411
     * - decoding: unused
1412
     */
1413
    float b_quant_offset;
1414

1415
    /**
1416 1417
     * Size of the frame reordering buffer in the decoder.
     * For MPEG-2 it is 1 IPB or 0 low delay IP.
Diego Biurrun's avatar
Diego Biurrun committed
1418
     * - encoding: Set by libavcodec.
1419
     * - decoding: Set by libavcodec.
1420
     */
1421
    int has_b_frames;
1422

1423
    /**
1424
     * 0-> h263 quant 1-> mpeg quant
Diego Biurrun's avatar
Diego Biurrun committed
1425
     * - encoding: Set by user.
1426
     * - decoding: unused
1427
     */
1428
    int mpeg_quant;
1429

1430
    /**
1431 1432
     * qscale factor between P and I-frames
     * If > 0 then the last p frame quantizer will be used (q= lastp_q*factor+offset).
1433
     * If < 0 then normal ratecontrol will be done (q= -normal_q*factor+offset).
Diego Biurrun's avatar
Diego Biurrun committed
1434
     * - encoding: Set by user.
1435
     * - decoding: unused
1436
     */
1437
    float i_quant_factor;
1438

1439
    /**
1440 1441 1442
     * qscale offset between P and I-frames
     * - encoding: Set by user.
     * - decoding: unused
1443
     */
1444
    float i_quant_offset;
1445

1446
    /**
1447
     * luminance masking (0-> disabled)
Diego Biurrun's avatar
Diego Biurrun committed
1448
     * - encoding: Set by user.
1449
     * - decoding: unused
1450
     */
1451
    float lumi_masking;
1452

1453
    /**
1454
     * temporary complexity masking (0-> disabled)
Diego Biurrun's avatar
Diego Biurrun committed
1455
     * - encoding: Set by user.
1456
     * - decoding: unused
1457
     */
1458
    float temporal_cplx_masking;
1459

1460
    /**
1461
     * spatial complexity masking (0-> disabled)
Diego Biurrun's avatar
Diego Biurrun committed
1462
     * - encoding: Set by user.
1463
     * - decoding: unused
1464
     */
1465
    float spatial_cplx_masking;
1466

1467
    /**
1468
     * p block masking (0-> disabled)
Diego Biurrun's avatar
Diego Biurrun committed
1469
     * - encoding: Set by user.
1470
     * - decoding: unused
1471
     */
1472
    float p_masking;
1473

1474
    /**
1475
     * darkness masking (0-> disabled)
Diego Biurrun's avatar
Diego Biurrun committed
1476
     * - encoding: Set by user.
1477
     * - decoding: unused
1478
     */
1479
    float dark_masking;
1480

1481
    /**
1482 1483 1484
     * slice count
     * - encoding: Set by libavcodec.
     * - decoding: Set by user (or 0).
1485
     */
1486
    int slice_count;
1487
    /**
1488
     * prediction method (needed for huffyuv)
Diego Biurrun's avatar
Diego Biurrun committed
1489
     * - encoding: Set by user.
1490
     * - decoding: unused
1491
     */
1492 1493 1494 1495
     int prediction_method;
#define FF_PRED_LEFT   0
#define FF_PRED_PLANE  1
#define FF_PRED_MEDIAN 2
1496 1497

    /**
1498 1499 1500
     * slice offsets in the frame in bytes
     * - encoding: Set/allocated by libavcodec.
     * - decoding: Set/allocated by user (or NULL).
1501
     */
1502
    int *slice_offset;
1503

1504
    /**
1505 1506 1507
     * sample aspect ratio (0 if unknown)
     * That is the width of a pixel divided by the height of the pixel.
     * Numerator and denominator must be relatively prime and smaller than 256 for some video standards.
Diego Biurrun's avatar
Diego Biurrun committed
1508 1509
     * - encoding: Set by user.
     * - decoding: Set by libavcodec.
1510
     */
1511
    AVRational sample_aspect_ratio;
1512

1513
    /**
1514
     * motion estimation comparison function
Diego Biurrun's avatar
Diego Biurrun committed
1515
     * - encoding: Set by user.
1516
     * - decoding: unused
1517
     */
1518
    int me_cmp;
1519
    /**
1520
     * subpixel motion estimation comparison function
Diego Biurrun's avatar
Diego Biurrun committed
1521
     * - encoding: Set by user.
1522
     * - decoding: unused
1523
     */
1524
    int me_sub_cmp;
1525
    /**
1526
     * macroblock comparison function (not supported yet)
Diego Biurrun's avatar
Diego Biurrun committed
1527
     * - encoding: Set by user.
1528
     * - decoding: unused
1529
     */
1530
    int mb_cmp;
1531
    /**
1532
     * interlaced DCT comparison function
Diego Biurrun's avatar
Diego Biurrun committed
1533
     * - encoding: Set by user.
1534
     * - decoding: unused
1535
     */
1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552
    int ildct_cmp;
#define FF_CMP_SAD    0
#define FF_CMP_SSE    1
#define FF_CMP_SATD   2
#define FF_CMP_DCT    3
#define FF_CMP_PSNR   4
#define FF_CMP_BIT    5
#define FF_CMP_RD     6
#define FF_CMP_ZERO   7
#define FF_CMP_VSAD   8
#define FF_CMP_VSSE   9
#define FF_CMP_NSSE   10
#define FF_CMP_W53    11
#define FF_CMP_W97    12
#define FF_CMP_DCTMAX 13
#define FF_CMP_DCT264 14
#define FF_CMP_CHROMA 256
1553

1554
    /**
1555
     * ME diamond size & shape
Diego Biurrun's avatar
Diego Biurrun committed
1556
     * - encoding: Set by user.
1557
     * - decoding: unused
1558
     */
1559
    int dia_size;
1560

1561
    /**
1562
     * amount of previous MV predictors (2a+1 x 2a+1 square)
Diego Biurrun's avatar
Diego Biurrun committed
1563
     * - encoding: Set by user.
1564
     * - decoding: unused
1565
     */
1566
    int last_predictor_count;
1567

1568
    /**
1569
     * prepass for motion estimation
Diego Biurrun's avatar
Diego Biurrun committed
1570
     * - encoding: Set by user.
1571
     * - decoding: unused
1572
     */
1573
    int pre_me;
1574

1575
    /**
1576
     * motion estimation prepass comparison function
Diego Biurrun's avatar
Diego Biurrun committed
1577
     * - encoding: Set by user.
1578
     * - decoding: unused
1579
     */
1580
    int me_pre_cmp;
1581 1582

    /**
1583
     * ME prepass diamond size & shape
Diego Biurrun's avatar
Diego Biurrun committed
1584
     * - encoding: Set by user.
1585
     * - decoding: unused
1586
     */
1587
    int pre_dia_size;
1588

1589
    /**
1590
     * subpel ME quality
Diego Biurrun's avatar
Diego Biurrun committed
1591
     * - encoding: Set by user.
1592
     * - decoding: unused
1593
     */
1594
    int me_subpel_quality;
1595

1596
    /**
1597 1598 1599 1600 1601 1602
     * DTG active format information (additional aspect ratio
     * information only used in DVB MPEG-2 transport streams)
     * 0 if not set.
     *
     * - encoding: unused
     * - decoding: Set by decoder.
1603
     */
1604 1605 1606 1607 1608 1609 1610 1611
    int dtg_active_format;
#define FF_DTG_AFD_SAME         8
#define FF_DTG_AFD_4_3          9
#define FF_DTG_AFD_16_9         10
#define FF_DTG_AFD_14_9         11
#define FF_DTG_AFD_4_3_SP_14_9  13
#define FF_DTG_AFD_16_9_SP_14_9 14
#define FF_DTG_AFD_SP_4_3       15
1612

1613
    /**
1614 1615 1616
     * maximum motion estimation search range in subpel units
     * If 0 then no limit.
     *
Diego Biurrun's avatar
Diego Biurrun committed
1617
     * - encoding: Set by user.
1618
     * - decoding: unused
1619
     */
1620
    int me_range;
1621

1622
    /**
1623
     * intra quantizer bias
Diego Biurrun's avatar
Diego Biurrun committed
1624
     * - encoding: Set by user.
1625
     * - decoding: unused
1626
     */
1627 1628
    int intra_quant_bias;
#define FF_DEFAULT_QUANT_BIAS 999999
1629

1630
    /**
1631
     * inter quantizer bias
Diego Biurrun's avatar
Diego Biurrun committed
1632
     * - encoding: Set by user.
1633
     * - decoding: unused
1634
     */
1635
    int inter_quant_bias;
1636

1637
    /**
1638 1639 1640
     * slice flags
     * - encoding: unused
     * - decoding: Set by user.
1641
     */
1642 1643 1644 1645
    int slice_flags;
#define SLICE_FLAG_CODED_ORDER    0x0001 ///< draw_horiz_band() is called in coded order instead of display
#define SLICE_FLAG_ALLOW_FIELD    0x0002 ///< allow draw_horiz_band() with field slices (MPEG2 field pics)
#define SLICE_FLAG_ALLOW_PLANE    0x0004 ///< allow draw_horiz_band() with 1 component at a time (SVQ1)
1646

1647
    /**
1648 1649 1650
     * XVideo Motion Acceleration
     * - encoding: forbidden
     * - decoding: set by decoder
1651
     */
1652
    int xvmc_acceleration;
1653

1654
    /**
1655
     * macroblock decision mode
Diego Biurrun's avatar
Diego Biurrun committed
1656
     * - encoding: Set by user.
1657
     * - decoding: unused
1658
     */
1659 1660 1661 1662
    int mb_decision;
#define FF_MB_DECISION_SIMPLE 0        ///< uses mb_cmp
#define FF_MB_DECISION_BITS   1        ///< chooses the one which needs the fewest bits
#define FF_MB_DECISION_RD     2        ///< rate distortion
1663

1664
    /**
1665 1666 1667
     * custom intra quantization matrix
     * - encoding: Set by user, can be NULL.
     * - decoding: Set by libavcodec.
1668
     */
1669
    uint16_t *intra_matrix;
1670

1671
    /**
1672 1673 1674
     * custom inter quantization matrix
     * - encoding: Set by user, can be NULL.
     * - decoding: Set by libavcodec.
1675
     */
1676
    uint16_t *inter_matrix;
1677

1678
    /**
1679 1680
     * scene change detection threshold
     * 0 is default, larger means fewer detected scene changes.
Diego Biurrun's avatar
Diego Biurrun committed
1681
     * - encoding: Set by user.
1682
     * - decoding: unused
1683
     */
1684
    int scenechange_threshold;
1685

1686
    /**
1687
     * noise reduction strength
Diego Biurrun's avatar
Diego Biurrun committed
1688
     * - encoding: Set by user.
1689
     * - decoding: unused
1690
     */
1691
    int noise_reduction;
1692

Michael Niedermayer's avatar
Michael Niedermayer committed
1693
    /**
1694 1695 1696
     * Motion estimation threshold below which no motion estimation is
     * performed, but instead the user specified motion vectors are used.
     *
Diego Biurrun's avatar
Diego Biurrun committed
1697
     * - encoding: Set by user.
1698
     * - decoding: unused
Michael Niedermayer's avatar
Michael Niedermayer committed
1699
     */
1700
    int me_threshold;
1701

1702
    /**
1703
     * Macroblock threshold below which the user specified macroblock types will be used.
Diego Biurrun's avatar
Diego Biurrun committed
1704
     * - encoding: Set by user.
1705
     * - decoding: unused
1706
     */
1707
    int mb_threshold;
Michael Niedermayer's avatar
Michael Niedermayer committed
1708 1709

    /**
1710
     * precision of the intra DC coefficient - 8
Diego Biurrun's avatar
Diego Biurrun committed
1711
     * - encoding: Set by user.
1712
     * - decoding: unused
Michael Niedermayer's avatar
Michael Niedermayer committed
1713
     */
1714
    int intra_dc_precision;
1715 1716

    /**
1717 1718
     * Number of macroblock rows at the top which are skipped.
     * - encoding: unused
Diego Biurrun's avatar
Diego Biurrun committed
1719
     * - decoding: Set by user.
1720
     */
1721
    int skip_top;
1722

1723
    /**
1724 1725
     * Number of macroblock rows at the bottom which are skipped.
     * - encoding: unused
Diego Biurrun's avatar
Diego Biurrun committed
1726
     * - decoding: Set by user.
1727
     */
1728
    int skip_bottom;
1729

1730
    /**
1731 1732
     * Border processing masking, raises the quantizer for mbs on the borders
     * of the picture.
Diego Biurrun's avatar
Diego Biurrun committed
1733
     * - encoding: Set by user.
1734
     * - decoding: unused
1735
     */
1736
    float border_masking;
1737

Michael Niedermayer's avatar
Michael Niedermayer committed
1738
    /**
1739
     * minimum MB lagrange multipler
Diego Biurrun's avatar
Diego Biurrun committed
1740
     * - encoding: Set by user.
1741
     * - decoding: unused
Michael Niedermayer's avatar
Michael Niedermayer committed
1742
     */
1743
    int mb_lmin;
1744

Michael Niedermayer's avatar
Michael Niedermayer committed
1745
    /**
1746
     * maximum MB lagrange multipler
Diego Biurrun's avatar
Diego Biurrun committed
1747
     * - encoding: Set by user.
1748
     * - decoding: unused
Michael Niedermayer's avatar
Michael Niedermayer committed
1749
     */
1750
    int mb_lmax;
1751

Michael Niedermayer's avatar
Michael Niedermayer committed
1752
    /**
1753
     *
Diego Biurrun's avatar
Diego Biurrun committed
1754
     * - encoding: Set by user.
1755
     * - decoding: unused
Michael Niedermayer's avatar
Michael Niedermayer committed
1756
     */
1757
    int me_penalty_compensation;
1758

1759
    /**
1760
     *
Diego Biurrun's avatar
Diego Biurrun committed
1761
     * - encoding: Set by user.
1762 1763
     * - decoding: unused
     */
1764
    int bidir_refine;
1765

Michael Niedermayer's avatar
Michael Niedermayer committed
1766
    /**
1767
     *
Diego Biurrun's avatar
Diego Biurrun committed
1768
     * - encoding: Set by user.
1769
     * - decoding: unused
Michael Niedermayer's avatar
Michael Niedermayer committed
1770
     */
1771
    int brd_scale;
1772 1773

    /**
1774
     * minimum GOP size
Diego Biurrun's avatar
Diego Biurrun committed
1775
     * - encoding: Set by user.
1776
     * - decoding: unused
1777
     */
1778
    int keyint_min;
1779

1780
    /**
1781 1782 1783
     * number of reference frames
     * - encoding: Set by user.
     * - decoding: Set by lavc.
Michael Niedermayer's avatar
Michael Niedermayer committed
1784
     */
1785
    int refs;
1786 1787

    /**
1788
     * chroma qp offset from luma
Diego Biurrun's avatar
Diego Biurrun committed
1789
     * - encoding: Set by user.
1790
     * - decoding: unused
1791
     */
1792
    int chromaoffset;
1793

1794
    /**
1795
     * Multiplied by qscale for each frame and added to scene_change_score.
Diego Biurrun's avatar
Diego Biurrun committed
1796
     * - encoding: Set by user.
1797
     * - decoding: unused
1798
     */
1799
    int scenechange_factor;
Michael Niedermayer's avatar
Michael Niedermayer committed
1800

1801
    /**
1802 1803
     *
     * Note: Value depends upon the compare function used for fullpel ME.
Diego Biurrun's avatar
Diego Biurrun committed
1804
     * - encoding: Set by user.
1805
     * - decoding: unused
1806
     */
1807
    int mv0_threshold;
1808

Michael Niedermayer's avatar
Michael Niedermayer committed
1809
    /**
1810
     * Adjust sensitivity of b_frame_strategy 1.
Diego Biurrun's avatar
Diego Biurrun committed
1811
     * - encoding: Set by user.
1812
     * - decoding: unused
Michael Niedermayer's avatar
Michael Niedermayer committed
1813
     */
1814
    int b_sensitivity;
Michael Niedermayer's avatar
Michael Niedermayer committed
1815

Michael Niedermayer's avatar
Michael Niedermayer committed
1816
    /**
1817 1818 1819
     * Chromaticity coordinates of the source primaries.
     * - encoding: Set by user
     * - decoding: Set by libavcodec
Michael Niedermayer's avatar
Michael Niedermayer committed
1820
     */
1821
    enum AVColorPrimaries color_primaries;
1822 1823

    /**
1824 1825 1826
     * Color Transfer Characteristic.
     * - encoding: Set by user
     * - decoding: Set by libavcodec
1827
     */
1828
    enum AVColorTransferCharacteristic color_trc;
1829

1830
    /**
1831 1832 1833
     * YUV colorspace type.
     * - encoding: Set by user
     * - decoding: Set by libavcodec
1834
     */
1835
    enum AVColorSpace colorspace;
1836

1837
    /**
1838 1839 1840
     * MPEG vs JPEG YUV range.
     * - encoding: Set by user
     * - decoding: Set by libavcodec
1841
     */
1842
    enum AVColorRange color_range;
1843 1844

    /**
1845 1846 1847
     * This defines the location of chroma samples.
     * - encoding: Set by user
     * - decoding: Set by libavcodec
1848
     */
1849
    enum AVChromaLocation chroma_sample_location;
1850

Michael Niedermayer's avatar
Michael Niedermayer committed
1851
    /**
1852 1853 1854 1855
     * Number of slices.
     * Indicates number of picture subdivisions. Used for parallelized
     * decoding.
     * - encoding: Set by user
Michael Niedermayer's avatar
Michael Niedermayer committed
1856 1857
     * - decoding: unused
     */
1858
    int slices;
1859

1860 1861
    /** Field order
     * - encoding: set by libavcodec
1862
     * - decoding: Set by user.
Michael Niedermayer's avatar
Michael Niedermayer committed
1863
     */
1864 1865 1866 1867 1868
    enum AVFieldOrder field_order;

    /* audio only */
    int sample_rate; ///< samples per second
    int channels;    ///< number of audio channels
Michael Niedermayer's avatar
Michael Niedermayer committed
1869 1870

    /**
1871
     * audio sample format
Diego Biurrun's avatar
Diego Biurrun committed
1872
     * - encoding: Set by user.
1873
     * - decoding: Set by libavcodec.
Michael Niedermayer's avatar
Michael Niedermayer committed
1874
     */
1875
    enum AVSampleFormat sample_fmt;  ///< sample format
1876

1877
    /* The following data should not be initialized. */
1878
    /**
1879 1880 1881 1882 1883 1884 1885
     * Number of samples per channel in an audio frame.
     *
     * - encoding: set by libavcodec in avcodec_open2(). Each submitted frame
     *   except the last must contain exactly frame_size samples per channel.
     *   May be 0 when the codec has CODEC_CAP_VARIABLE_FRAME_SIZE set, then the
     *   frame size is not restricted.
     * - decoding: may be set by some decoders to indicate constant frame size
1886
     */
1887
    int frame_size;
1888 1889 1890 1891 1892 1893 1894 1895 1896 1897 1898

    /**
     * Frame counter, set by libavcodec.
     *
     * - decoding: total number of frames returned from the decoder so far.
     * - encoding: total number of frames passed to the encoder so far.
     *
     *   @note the counter is not incremented if encoding/decoding resulted in
     *   an error.
     */
    int frame_number;
1899

Ivan Kalvachev's avatar
Ivan Kalvachev committed
1900
    /**
1901 1902
     * number of bytes per packet if constant and known or 0
     * Used by some WAV based audio codecs.
Ivan Kalvachev's avatar
Ivan Kalvachev committed
1903
     */
1904
    int block_align;
1905

1906
    /**
1907
     * Audio cutoff bandwidth (0 means "automatic")
Diego Biurrun's avatar
Diego Biurrun committed
1908
     * - encoding: Set by user.
1909 1910
     * - decoding: unused
     */
1911
    int cutoff;
1912

1913
#if FF_API_REQUEST_CHANNELS
1914
    /**
1915 1916 1917 1918
     * Decoder should decode to this many channels if it can (0 for default)
     * - encoding: unused
     * - decoding: Set by user.
     * @deprecated Deprecated in favor of request_channel_layout.
1919
     */
1920
    attribute_deprecated int request_channels;
1921
#endif
1922 1923

    /**
1924 1925
     * Audio channel layout.
     * - encoding: set by user.
1926
     * - decoding: set by user, may be overwritten by libavcodec.
1927
     */
1928
    uint64_t channel_layout;
1929

1930
    /**
1931
     * Request decoder to use this channel layout if it can (0 for default)
1932
     * - encoding: unused
1933
     * - decoding: Set by user.
1934
     */
1935
    uint64_t request_channel_layout;
1936 1937

    /**
1938
     * Type of service that the audio stream conveys.
Diego Biurrun's avatar
Diego Biurrun committed
1939
     * - encoding: Set by user.
1940
     * - decoding: Set by libavcodec.
1941
     */
1942
    enum AVAudioServiceType audio_service_type;
1943 1944

    /**
1945 1946
     * desired sample format
     * - encoding: Not used.
1947
     * - decoding: Set by user.
1948
     * Decoder will decode to this format if it can.
1949
     */
1950
    enum AVSampleFormat request_sample_fmt;
1951

1952
#if FF_API_GET_BUFFER
1953
    /**
1954 1955 1956 1957 1958 1959 1960 1961 1962 1963 1964 1965 1966 1967 1968 1969 1970 1971 1972 1973 1974 1975 1976 1977 1978 1979 1980 1981 1982 1983 1984 1985 1986 1987 1988 1989 1990 1991 1992 1993 1994
     * Called at the beginning of each frame to get a buffer for it.
     *
     * The function will set AVFrame.data[], AVFrame.linesize[].
     * AVFrame.extended_data[] must also be set, but it should be the same as
     * AVFrame.data[] except for planar audio with more channels than can fit
     * in AVFrame.data[]. In that case, AVFrame.data[] shall still contain as
     * many data pointers as it can hold.
     *
     * if CODEC_CAP_DR1 is not set then get_buffer() must call
     * avcodec_default_get_buffer() instead of providing buffers allocated by
     * some other means.
     *
     * AVFrame.data[] should be 32- or 16-byte-aligned unless the CPU doesn't
     * need it. avcodec_default_get_buffer() aligns the output buffer properly,
     * but if get_buffer() is overridden then alignment considerations should
     * be taken into account.
     *
     * @see avcodec_default_get_buffer()
     *
     * Video:
     *
     * If pic.reference is set then the frame will be read later by libavcodec.
     * avcodec_align_dimensions2() should be used to find the required width and
     * height, as they normally need to be rounded up to the next multiple of 16.
     *
     * If frame multithreading is used and thread_safe_callbacks is set,
     * it may be called from a different thread, but not from more than one at
     * once. Does not need to be reentrant.
     *
     * @see release_buffer(), reget_buffer()
     * @see avcodec_align_dimensions2()
     *
     * Audio:
     *
     * Decoders request a buffer of a particular size by setting
     * AVFrame.nb_samples prior to calling get_buffer(). The decoder may,
     * however, utilize only part of the buffer by setting AVFrame.nb_samples
     * to a smaller value in the output frame.
     *
     * Decoders cannot use the buffer after returning from
     * avcodec_decode_audio4(), so they will not call release_buffer(), as it
1995 1996 1997 1998 1999 2000
     * is assumed to be released immediately upon return. In some rare cases,
     * a decoder may need to call get_buffer() more than once in a single
     * call to avcodec_decode_audio4(). In that case, when get_buffer() is
     * called again after it has already been called once, the previously
     * acquired buffer is assumed to be released at that time and may not be
     * reused by the decoder.
2001 2002 2003 2004 2005 2006 2007 2008 2009 2010 2011
     *
     * As a convenience, av_samples_get_buffer_size() and
     * av_samples_fill_arrays() in libavutil may be used by custom get_buffer()
     * functions to find the required data size and to fill data pointers and
     * linesize. In AVFrame.linesize, only linesize[0] may be set for audio
     * since all planes must be the same size.
     *
     * @see av_samples_get_buffer_size(), av_samples_fill_arrays()
     *
     * - encoding: unused
     * - decoding: Set by libavcodec, user can override.
2012 2013
     *
     * @deprecated use get_buffer2()
2014
     */
2015
    attribute_deprecated
2016
    int (*get_buffer)(struct AVCodecContext *c, AVFrame *pic);
2017

2018
    /**
2019 2020 2021 2022 2023 2024 2025
     * Called to release buffers which were allocated with get_buffer.
     * A released buffer can be reused in get_buffer().
     * pic.data[*] must be set to NULL.
     * May be called from a different thread if frame multithreading is used,
     * but not by more than one thread at once, so does not need to be reentrant.
     * - encoding: unused
     * - decoding: Set by libavcodec, user can override.
2026 2027
     *
     * @deprecated custom freeing callbacks should be set from get_buffer2()
2028
     */
2029
    attribute_deprecated
2030
    void (*release_buffer)(struct AVCodecContext *c, AVFrame *pic);
2031

2032
    /**
Diego Biurrun's avatar
Diego Biurrun committed
2033 2034 2035
     * Called at the beginning of a frame to get cr buffer for it.
     * Buffer type (size, hints) must be the same. libavcodec won't check it.
     * libavcodec will pass previous buffer in pic, function should return
2036
     * same buffer or new buffer with old frame "painted" into it.
Diego Biurrun's avatar
Diego Biurrun committed
2037
     * If pic.data[0] == NULL must behave like get_buffer().
2038 2039 2040
     * if CODEC_CAP_DR1 is not set then reget_buffer() must call
     * avcodec_default_reget_buffer() instead of providing buffers allocated by
     * some other means.
2041
     * - encoding: unused
2042
     * - decoding: Set by libavcodec, user can override.
2043
     */
2044
    attribute_deprecated
2045
    int (*reget_buffer)(struct AVCodecContext *c, AVFrame *pic);
2046
#endif
2047

2048 2049 2050
    /**
     * This callback is called at the beginning of each frame to get data
     * buffer(s) for it. There may be one contiguous buffer for all the data or
2051 2052 2053 2054
     * there may be a buffer per each data plane or anything in between. What
     * this means is, you may set however many entries in buf[] you feel necessary.
     * Each buffer must be reference-counted using the AVBuffer API (see description
     * of buf[] below).
2055 2056 2057 2058 2059 2060 2061 2062 2063 2064 2065 2066 2067 2068 2069 2070 2071 2072 2073 2074
     *
     * The following fields will be set in the frame before this callback is
     * called:
     * - format
     * - width, height (video only)
     * - sample_rate, channel_layout, nb_samples (audio only)
     * Their values may differ from the corresponding values in
     * AVCodecContext. This callback must use the frame values, not the codec
     * context values, to calculate the required buffer size.
     *
     * This callback must fill the following fields in the frame:
     * - data[]
     * - linesize[]
     * - extended_data:
     *   * if the data is planar audio with more than 8 channels, then this
     *     callback must allocate and fill extended_data to contain all pointers
     *     to all data planes. data[] must hold as many pointers as it can.
     *     extended_data must be allocated with av_malloc() and will be freed in
     *     av_frame_unref().
     *   * otherwise exended_data must point to data
2075 2076 2077 2078 2079
     * - buf[] must contain one or more pointers to AVBufferRef structures. Each of
     *   the frame's data and extended_data pointers must be contained in these. That
     *   is, one AVBufferRef for each allocated chunk of memory, not necessarily one
     *   AVBufferRef per data[] entry. See: av_buffer_create(), av_buffer_alloc(),
     *   and av_buffer_ref().
2080 2081 2082 2083 2084 2085 2086 2087 2088 2089 2090 2091 2092 2093 2094 2095 2096 2097 2098 2099 2100 2101 2102 2103 2104 2105 2106 2107 2108 2109 2110 2111 2112 2113 2114 2115 2116 2117 2118 2119 2120 2121 2122 2123 2124 2125 2126 2127 2128 2129 2130 2131 2132 2133 2134 2135 2136 2137 2138 2139 2140 2141 2142
     * - extended_buf and nb_extended_buf must be allocated with av_malloc() by
     *   this callback and filled with the extra buffers if there are more
     *   buffers than buf[] can hold. extended_buf will be freed in
     *   av_frame_unref().
     *
     * If CODEC_CAP_DR1 is not set then get_buffer2() must call
     * avcodec_default_get_buffer2() instead of providing buffers allocated by
     * some other means.
     *
     * Each data plane must be aligned to the maximum required by the target
     * CPU.
     *
     * @see avcodec_default_get_buffer2()
     *
     * Video:
     *
     * If AV_GET_BUFFER_FLAG_REF is set in flags then the frame may be reused
     * (read and/or written to if it is writable) later by libavcodec.
     *
     * If CODEC_FLAG_EMU_EDGE is not set in s->flags, the buffer must contain an
     * edge of the size returned by avcodec_get_edge_width() on all sides.
     *
     * avcodec_align_dimensions2() should be used to find the required width and
     * height, as they normally need to be rounded up to the next multiple of 16.
     *
     * If frame multithreading is used and thread_safe_callbacks is set,
     * this callback may be called from a different thread, but not from more
     * than one at once. Does not need to be reentrant.
     *
     * @see avcodec_align_dimensions2()
     *
     * Audio:
     *
     * Decoders request a buffer of a particular size by setting
     * AVFrame.nb_samples prior to calling get_buffer2(). The decoder may,
     * however, utilize only part of the buffer by setting AVFrame.nb_samples
     * to a smaller value in the output frame.
     *
     * As a convenience, av_samples_get_buffer_size() and
     * av_samples_fill_arrays() in libavutil may be used by custom get_buffer2()
     * functions to find the required data size and to fill data pointers and
     * linesize. In AVFrame.linesize, only linesize[0] may be set for audio
     * since all planes must be the same size.
     *
     * @see av_samples_get_buffer_size(), av_samples_fill_arrays()
     *
     * - encoding: unused
     * - decoding: Set by libavcodec, user can override.
     */
    int (*get_buffer2)(struct AVCodecContext *s, AVFrame *frame, int flags);

    /**
     * If non-zero, the decoded audio and video frames returned from
     * avcodec_decode_video2() and avcodec_decode_audio4() are reference-counted
     * and are valid indefinitely. The caller must free them with
     * av_frame_unref() when they are not needed anymore.
     * Otherwise, the decoded frames must not be freed by the caller and are
     * only valid until the next decode call.
     *
     * - encoding: unused
     * - decoding: set by the caller before avcodec_open2().
     */
    int refcounted_frames;
2143

2144 2145 2146
    /* - encoding parameters */
    float qcompress;  ///< amount of qscale change between easy & hard scenes (0.0-1.0)
    float qblur;      ///< amount of qscale smoothing over time (0.0-1.0)
2147 2148

    /**
2149
     * minimum quantizer
Diego Biurrun's avatar
Diego Biurrun committed
2150
     * - encoding: Set by user.
2151 2152
     * - decoding: unused
     */
2153
    int qmin;
2154 2155

    /**
2156
     * maximum quantizer
Diego Biurrun's avatar
Diego Biurrun committed
2157
     * - encoding: Set by user.
2158 2159
     * - decoding: unused
     */
2160
    int qmax;
2161 2162

    /**
2163
     * maximum quantizer difference between frames
Diego Biurrun's avatar
Diego Biurrun committed
2164
     * - encoding: Set by user.
2165
     * - decoding: unused
2166
     */
2167
    int max_qdiff;
2168 2169

    /**
2170
     * ratecontrol qmin qmax limiting method
2171
     * 0-> clipping, 1-> use a nice continuous function to limit qscale wthin qmin/qmax.
Diego Biurrun's avatar
Diego Biurrun committed
2172 2173
     * - encoding: Set by user.
     * - decoding: unused
2174
     */
2175
    float rc_qsquish;
2176

2177 2178
    float rc_qmod_amp;
    int rc_qmod_freq;
2179

2180
    /**
2181
     * decoder bitstream buffer size
Diego Biurrun's avatar
Diego Biurrun committed
2182
     * - encoding: Set by user.
2183 2184
     * - decoding: unused
     */
2185
    int rc_buffer_size;
2186 2187

    /**
2188 2189
     * ratecontrol override, see RcOverride
     * - encoding: Allocated/set/freed by user.
2190
     * - decoding: unused
2191
     */
2192 2193
    int rc_override_count;
    RcOverride *rc_override;
2194

2195
    /**
2196 2197
     * rate control equation
     * - encoding: Set by user
2198
     * - decoding: unused
2199
     */
2200
    const char *rc_eq;
2201 2202

    /**
2203
     * maximum bitrate
Diego Biurrun's avatar
Diego Biurrun committed
2204
     * - encoding: Set by user.
2205
     * - decoding: unused
2206
     */
2207
    int rc_max_rate;
2208 2209

    /**
2210
     * minimum bitrate
Diego Biurrun's avatar
Diego Biurrun committed
2211
     * - encoding: Set by user.
2212 2213
     * - decoding: unused
     */
2214
    int rc_min_rate;
2215

2216
    float rc_buffer_aggressivity;
2217 2218

    /**
2219
     * initial complexity for pass1 ratecontrol
Diego Biurrun's avatar
Diego Biurrun committed
2220
     * - encoding: Set by user.
2221 2222
     * - decoding: unused
     */
2223
    float rc_initial_cplx;
Michael Niedermayer's avatar
Michael Niedermayer committed
2224 2225

    /**
2226
     * Ratecontrol attempt to use, at maximum, <value> of what can be used without an underflow.
Diego Biurrun's avatar
Diego Biurrun committed
2227
     * - encoding: Set by user.
2228
     * - decoding: unused.
Michael Niedermayer's avatar
Michael Niedermayer committed
2229
     */
2230
    float rc_max_available_vbv_use;
2231 2232

    /**
2233
     * Ratecontrol attempt to use, at least, <value> times the amount needed to prevent a vbv overflow.
Diego Biurrun's avatar
Diego Biurrun committed
2234
     * - encoding: Set by user.
2235
     * - decoding: unused.
2236
     */
2237
    float rc_min_vbv_overflow_use;
2238 2239

    /**
2240
     * Number of bits which should be loaded into the rc buffer before decoding starts.
Diego Biurrun's avatar
Diego Biurrun committed
2241
     * - encoding: Set by user.
Michael Niedermayer's avatar
Michael Niedermayer committed
2242
     * - decoding: unused
2243
     */
2244
    int rc_initial_buffer_occupancy;
2245

2246 2247 2248 2249 2250
#define FF_CODER_TYPE_VLC       0
#define FF_CODER_TYPE_AC        1
#define FF_CODER_TYPE_RAW       2
#define FF_CODER_TYPE_RLE       3
#define FF_CODER_TYPE_DEFLATE   4
2251
    /**
2252
     * coder type
Diego Biurrun's avatar
Diego Biurrun committed
2253
     * - encoding: Set by user.
2254
     * - decoding: unused
2255
     */
2256
    int coder_type;
2257

2258
    /**
2259
     * context model
Diego Biurrun's avatar
Diego Biurrun committed
2260
     * - encoding: Set by user.
2261
     * - decoding: unused
2262
     */
2263
    int context_model;
2264 2265

    /**
2266
     * minimum Lagrange multipler
Diego Biurrun's avatar
Diego Biurrun committed
2267
     * - encoding: Set by user.
2268
     * - decoding: unused
2269
     */
2270
    int lmin;
2271 2272

    /**
2273
     * maximum Lagrange multipler
Diego Biurrun's avatar
Diego Biurrun committed
2274
     * - encoding: Set by user.
2275
     * - decoding: unused
2276
     */
2277
    int lmax;
Michael Niedermayer's avatar
Michael Niedermayer committed
2278 2279 2280

    /**
     * frame skip threshold
Diego Biurrun's avatar
Diego Biurrun committed
2281
     * - encoding: Set by user.
Michael Niedermayer's avatar
Michael Niedermayer committed
2282 2283 2284 2285 2286 2287
     * - decoding: unused
     */
    int frame_skip_threshold;

    /**
     * frame skip factor
Diego Biurrun's avatar
Diego Biurrun committed
2288
     * - encoding: Set by user.
Michael Niedermayer's avatar
Michael Niedermayer committed
2289 2290 2291
     * - decoding: unused
     */
    int frame_skip_factor;
2292 2293 2294

    /**
     * frame skip exponent
Diego Biurrun's avatar
Diego Biurrun committed
2295
     * - encoding: Set by user.
2296 2297 2298 2299 2300
     * - decoding: unused
     */
    int frame_skip_exp;

    /**
Diego Biurrun's avatar
Diego Biurrun committed
2301 2302
     * frame skip comparison function
     * - encoding: Set by user.
2303 2304 2305
     * - decoding: unused
     */
    int frame_skip_cmp;
2306 2307

    /**
2308
     * trellis RD quantization
Diego Biurrun's avatar
Diego Biurrun committed
2309
     * - encoding: Set by user.
2310 2311
     * - decoding: unused
     */
2312
    int trellis;
2313 2314

    /**
Diego Biurrun's avatar
Diego Biurrun committed
2315
     * - encoding: Set by user.
2316 2317
     * - decoding: unused
     */
2318
    int min_prediction_order;
2319 2320

    /**
Diego Biurrun's avatar
Diego Biurrun committed
2321
     * - encoding: Set by user.
2322 2323
     * - decoding: unused
     */
2324
    int max_prediction_order;
2325 2326

    /**
2327 2328 2329
     * GOP timecode frame start number
     * - encoding: Set by user, in non drop frame format
     * - decoding: Set by libavcodec (timecode in the 25 bits format, -1 if unset)
2330
     */
2331
    int64_t timecode_frame_start;
Michael Niedermayer's avatar
Michael Niedermayer committed
2332

2333 2334 2335 2336 2337 2338 2339
    /* The RTP callback: This function is called    */
    /* every time the encoder has a packet to send. */
    /* It depends on the encoder if the data starts */
    /* with a Start Code (it should). H.263 does.   */
    /* mb_nb contains the number of macroblocks     */
    /* encoded in the RTP payload.                  */
    void (*rtp_callback)(struct AVCodecContext *avctx, void *data, int size, int mb_nb);
Michael Niedermayer's avatar
Michael Niedermayer committed
2340

2341 2342 2343 2344 2345 2346
    int rtp_payload_size;   /* The size of the RTP payload: the coder will  */
                            /* do its best to deliver a chunk with size     */
                            /* below rtp_payload_size, the chunk will start */
                            /* with a start code on some codecs like H.263. */
                            /* This doesn't take account of any particular  */
                            /* headers inside the transmitted RTP payload.  */
Michael Niedermayer's avatar
Michael Niedermayer committed
2347

2348 2349 2350 2351 2352 2353 2354 2355 2356
    /* statistics, used for 2-pass encoding */
    int mv_bits;
    int header_bits;
    int i_tex_bits;
    int p_tex_bits;
    int i_count;
    int p_count;
    int skip_count;
    int misc_bits;
2357 2358

    /**
2359 2360
     * number of bits used for the previously encoded frame
     * - encoding: Set by libavcodec.
2361 2362
     * - decoding: unused
     */
2363
    int frame_bits;
2364 2365

    /**
2366 2367
     * pass1 encoding statistics output buffer
     * - encoding: Set by libavcodec.
2368 2369
     * - decoding: unused
     */
2370
    char *stats_out;
Robert Swain's avatar
Robert Swain committed
2371 2372

    /**
2373 2374 2375
     * pass2 encoding statistics input buffer
     * Concatenated stuff from stats_out of pass1 should be placed here.
     * - encoding: Allocated/set/freed by user.
Robert Swain's avatar
Robert Swain committed
2376 2377
     * - decoding: unused
     */
2378
    char *stats_in;
Robert Swain's avatar
Robert Swain committed
2379 2380

    /**
2381 2382 2383
     * Work around bugs in encoders which sometimes cannot be detected automatically.
     * - encoding: Set by user
     * - decoding: Set by user
Robert Swain's avatar
Robert Swain committed
2384
     */
2385 2386 2387 2388 2389 2390 2391 2392 2393 2394 2395 2396 2397 2398 2399 2400 2401
    int workaround_bugs;
#define FF_BUG_AUTODETECT       1  ///< autodetection
#define FF_BUG_OLD_MSMPEG4      2
#define FF_BUG_XVID_ILACE       4
#define FF_BUG_UMP4             8
#define FF_BUG_NO_PADDING       16
#define FF_BUG_AMV              32
#define FF_BUG_AC_VLC           0  ///< Will be removed, libavcodec can now handle these non-compliant files by default.
#define FF_BUG_QPEL_CHROMA      64
#define FF_BUG_STD_QPEL         128
#define FF_BUG_QPEL_CHROMA2     256
#define FF_BUG_DIRECT_BLOCKSIZE 512
#define FF_BUG_EDGE             1024
#define FF_BUG_HPEL_CHROMA      2048
#define FF_BUG_DC_CLIP          4096
#define FF_BUG_MS               8192 ///< Work around various bugs in Microsoft's broken decoders.
#define FF_BUG_TRUNCATED       16384
Robert Swain's avatar
Robert Swain committed
2402 2403

    /**
2404
     * strictly follow the standard (MPEG4, ...).
Diego Biurrun's avatar
Diego Biurrun committed
2405
     * - encoding: Set by user.
2406 2407 2408 2409 2410 2411 2412 2413
     * - decoding: Set by user.
     * Setting this to STRICT or higher means the encoder and decoder will
     * generally do stupid things, whereas setting it to unofficial or lower
     * will mean the encoder might produce output that is not supported by all
     * spec-compliant decoders. Decoders don't differentiate between normal,
     * unofficial and experimental (that is, they always try to decode things
     * when they can) unless they are explicitly asked to behave stupidly
     * (=strictly conform to the specs)
Robert Swain's avatar
Robert Swain committed
2414
     */
2415 2416 2417 2418 2419 2420
    int strict_std_compliance;
#define FF_COMPLIANCE_VERY_STRICT   2 ///< Strictly conform to an older more strict version of the spec or reference software.
#define FF_COMPLIANCE_STRICT        1 ///< Strictly conform to all the things in the spec no matter what consequences.
#define FF_COMPLIANCE_NORMAL        0
#define FF_COMPLIANCE_UNOFFICIAL   -1 ///< Allow unofficial extensions
#define FF_COMPLIANCE_EXPERIMENTAL -2 ///< Allow nonstandardized experimental things.
Robert Swain's avatar
Robert Swain committed
2421 2422

    /**
2423 2424 2425
     * error concealment flags
     * - encoding: unused
     * - decoding: Set by user.
Robert Swain's avatar
Robert Swain committed
2426
     */
2427 2428 2429
    int error_concealment;
#define FF_EC_GUESS_MVS   1
#define FF_EC_DEBLOCK     2
Robert Swain's avatar
Robert Swain committed
2430

2431
    /**
2432
     * debug
Diego Biurrun's avatar
Diego Biurrun committed
2433
     * - encoding: Set by user.
2434
     * - decoding: Set by user.
2435
     */
2436 2437 2438 2439 2440 2441 2442 2443 2444 2445 2446 2447 2448 2449 2450 2451 2452 2453
    int debug;
#define FF_DEBUG_PICT_INFO   1
#define FF_DEBUG_RC          2
#define FF_DEBUG_BITSTREAM   4
#define FF_DEBUG_MB_TYPE     8
#define FF_DEBUG_QP          16
#define FF_DEBUG_MV          32
#define FF_DEBUG_DCT_COEFF   0x00000040
#define FF_DEBUG_SKIP        0x00000080
#define FF_DEBUG_STARTCODE   0x00000100
#define FF_DEBUG_PTS         0x00000200
#define FF_DEBUG_ER          0x00000400
#define FF_DEBUG_MMCO        0x00000800
#define FF_DEBUG_BUGS        0x00001000
#define FF_DEBUG_VIS_QP      0x00002000
#define FF_DEBUG_VIS_MB_TYPE 0x00004000
#define FF_DEBUG_BUFFERS     0x00008000
#define FF_DEBUG_THREADS     0x00010000
2454 2455

    /**
2456
     * debug
Diego Biurrun's avatar
Diego Biurrun committed
2457
     * - encoding: Set by user.
2458
     * - decoding: Set by user.
2459
     */
2460 2461 2462 2463
    int debug_mv;
#define FF_DEBUG_VIS_MV_P_FOR  0x00000001 //visualize forward predicted MVs of P frames
#define FF_DEBUG_VIS_MV_B_FOR  0x00000002 //visualize forward predicted MVs of B frames
#define FF_DEBUG_VIS_MV_B_BACK 0x00000004 //visualize backward predicted MVs of B frames
2464 2465

    /**
2466
     * Error recognition; may misdetect some more or less valid parts as errors.
2467 2468
     * - encoding: unused
     * - decoding: Set by user.
2469
     */
2470 2471 2472 2473 2474
    int err_recognition;
#define AV_EF_CRCCHECK  (1<<0)
#define AV_EF_BITSTREAM (1<<1)
#define AV_EF_BUFFER    (1<<2)
#define AV_EF_EXPLODE   (1<<3)
2475

2476 2477 2478 2479
#define AV_EF_CAREFUL    (1<<16)
#define AV_EF_COMPLIANT  (1<<17)
#define AV_EF_AGGRESSIVE (1<<18)

2480 2481

    /**
2482 2483
     * opaque 64bit number (generally a PTS) that will be reordered and
     * output in AVFrame.reordered_opaque
2484
     * @deprecated in favor of pkt_pts
2485 2486
     * - encoding: unused
     * - decoding: Set by user.
2487
     */
2488
    int64_t reordered_opaque;
2489 2490

    /**
2491 2492 2493
     * Hardware accelerator in use
     * - encoding: unused.
     * - decoding: Set by libavcodec
2494
     */
2495
    struct AVHWAccel *hwaccel;
2496 2497

    /**
2498 2499 2500
     * Hardware accelerator context.
     * For some hardware accelerators, a global context needs to be
     * provided by the user. In that case, this holds display-dependent
2501 2502
     * data FFmpeg cannot instantiate itself. Please refer to the
     * FFmpeg HW accelerator documentation to know how to fill this
2503 2504 2505
     * is. e.g. for VA API, this is a struct vaapi_context.
     * - encoding: unused
     * - decoding: Set by user
2506
     */
2507
    void *hwaccel_context;
2508 2509

    /**
2510 2511
     * error
     * - encoding: Set by libavcodec if flags&CODEC_FLAG_PSNR.
Diego Biurrun's avatar
Diego Biurrun committed
2512
     * - decoding: unused
2513
     */
2514
    uint64_t error[AV_NUM_DATA_POINTERS];
2515 2516

    /**
2517
     * DCT algorithm, see FF_DCT_* below
Diego Biurrun's avatar
Diego Biurrun committed
2518 2519
     * - encoding: Set by user.
     * - decoding: unused
2520
     */
2521 2522 2523 2524 2525 2526 2527
    int dct_algo;
#define FF_DCT_AUTO    0
#define FF_DCT_FASTINT 1
#define FF_DCT_INT     2
#define FF_DCT_MMX     3
#define FF_DCT_ALTIVEC 5
#define FF_DCT_FAAN    6
2528

2529
    /**
2530
     * IDCT algorithm, see FF_IDCT_* below.
2531
     * - encoding: Set by user.
2532
     * - decoding: Set by user.
2533
     */
2534 2535 2536 2537 2538 2539 2540 2541 2542 2543 2544 2545 2546 2547 2548 2549 2550
    int idct_algo;
#define FF_IDCT_AUTO          0
#define FF_IDCT_INT           1
#define FF_IDCT_SIMPLE        2
#define FF_IDCT_SIMPLEMMX     3
#define FF_IDCT_ARM           7
#define FF_IDCT_ALTIVEC       8
#define FF_IDCT_SH4           9
#define FF_IDCT_SIMPLEARM     10
#define FF_IDCT_IPP           13
#define FF_IDCT_XVIDMMX       14
#define FF_IDCT_SIMPLEARMV5TE 16
#define FF_IDCT_SIMPLEARMV6   17
#define FF_IDCT_SIMPLEVIS     18
#define FF_IDCT_FAAN          20
#define FF_IDCT_SIMPLENEON    22
#define FF_IDCT_SIMPLEALPHA   23
2551

2552
    /**
2553 2554
     * bits per sample/pixel from the demuxer (needed for huffyuv).
     * - encoding: Set by libavcodec.
2555 2556
     * - decoding: Set by user.
     */
2557
     int bits_per_coded_sample;
2558 2559 2560 2561 2562 2563 2564

    /**
     * Bits per sample/pixel of internal libavcodec pixel/sample format.
     * - encoding: set by user.
     * - decoding: set by libavcodec.
     */
    int bits_per_raw_sample;
2565

2566
#if FF_API_LOWRES
2567
    /**
2568
     * low resolution decoding, 1-> 1/2 size, 2->1/4 size
2569 2570
     * - encoding: unused
     * - decoding: Set by user.
2571 2572
     * Code outside libavcodec should access this field using:
     * av_codec_{get,set}_lowres(avctx)
2573
     */
Michael Niedermayer's avatar
Michael Niedermayer committed
2574
     int lowres;
2575
#endif
2576 2577

    /**
2578 2579 2580
     * the picture in the bitstream
     * - encoding: Set by libavcodec.
     * - decoding: Set by libavcodec.
2581
     */
2582
    AVFrame *coded_frame;
2583 2584

    /**
2585 2586
     * thread count
     * is used to decide how many independent tasks should be passed to execute()
2587
     * - encoding: Set by user.
2588
     * - decoding: Set by user.
2589
     */
2590
    int thread_count;
2591 2592

    /**
2593 2594 2595
     * Which multithreading methods to use.
     * Use of FF_THREAD_FRAME will increase decoding delay by one frame per thread,
     * so clients which cannot provide future frames should not use it.
2596
     *
2597 2598
     * - encoding: Set by user, otherwise the default is used.
     * - decoding: Set by user, otherwise the default is used.
2599
     */
2600 2601 2602
    int thread_type;
#define FF_THREAD_FRAME   1 ///< Decode more than one frame at once
#define FF_THREAD_SLICE   2 ///< Decode more than one part of a single frame at once
2603 2604

    /**
2605 2606 2607
     * Which multithreading methods are in use by the codec.
     * - encoding: Set by libavcodec.
     * - decoding: Set by libavcodec.
2608
     */
2609
    int active_thread_type;
2610 2611

    /**
2612
     * Set by the client if its custom get_buffer() callback can be called
2613
     * synchronously from another thread, which allows faster multithreaded decoding.
2614 2615 2616 2617
     * draw_horiz_band() will be called from other threads regardless of this setting.
     * Ignored if the default get_buffer() is used.
     * - encoding: Set by user.
     * - decoding: Set by user.
2618
     */
2619
    int thread_safe_callbacks;
2620 2621

    /**
2622 2623 2624 2625 2626 2627 2628
     * The codec may call this to execute several independent things.
     * It will return only after finishing all tasks.
     * The user may replace this with some multithreaded implementation,
     * the default implementation will execute the parts serially.
     * @param count the number of things to execute
     * - encoding: Set by libavcodec, user can override.
     * - decoding: Set by libavcodec, user can override.
2629
     */
2630
    int (*execute)(struct AVCodecContext *c, int (*func)(struct AVCodecContext *c2, void *arg), void *arg2, int *ret, int count, int size);
2631 2632 2633 2634 2635 2636 2637 2638 2639 2640 2641 2642 2643 2644 2645 2646 2647 2648 2649 2650

    /**
     * The codec may call this to execute several independent things.
     * It will return only after finishing all tasks.
     * The user may replace this with some multithreaded implementation,
     * the default implementation will execute the parts serially.
     * Also see avcodec_thread_init and e.g. the --enable-pthread configure option.
     * @param c context passed also to func
     * @param count the number of things to execute
     * @param arg2 argument passed unchanged to func
     * @param ret return values of executed functions, must have space for "count" values. May be NULL.
     * @param func function that will be called count times, with jobnr from 0 to count-1.
     *             threadnr will be in the range 0 to c->thread_count-1 < MAX_THREADS and so that no
     *             two instances of func executing at the same time will have the same threadnr.
     * @return always 0 currently, but code should handle a future improvement where when any call to func
     *         returns < 0 no further calls to func may be done and < 0 is returned.
     * - encoding: Set by libavcodec, user can override.
     * - decoding: Set by libavcodec, user can override.
     */
    int (*execute2)(struct AVCodecContext *c, int (*func)(struct AVCodecContext *c2, void *arg, int jobnr, int threadnr), void *arg2, int *ret, int count);
2651

2652 2653 2654 2655 2656 2657 2658
    /**
     * thread opaque
     * Can be used by execute() to store some per AVCodecContext stuff.
     * - encoding: set by execute()
     * - decoding: set by execute()
     */
    void *thread_opaque;
2659

2660
    /**
2661 2662
     * noise vs. sse weight for the nsse comparsion function
     * - encoding: Set by user.
2663 2664
     * - decoding: unused
     */
2665
     int nsse_weight;
2666 2667

    /**
2668 2669 2670
     * profile
     * - encoding: Set by user.
     * - decoding: Set by libavcodec.
2671
     */
2672 2673 2674 2675 2676 2677 2678 2679
     int profile;
#define FF_PROFILE_UNKNOWN -99
#define FF_PROFILE_RESERVED -100

#define FF_PROFILE_AAC_MAIN 0
#define FF_PROFILE_AAC_LOW  1
#define FF_PROFILE_AAC_SSR  2
#define FF_PROFILE_AAC_LTP  3
2680 2681 2682 2683
#define FF_PROFILE_AAC_HE   4
#define FF_PROFILE_AAC_HE_V2 28
#define FF_PROFILE_AAC_LD   22
#define FF_PROFILE_AAC_ELD  38
2684 2685
#define FF_PROFILE_MPEG2_AAC_LOW 128
#define FF_PROFILE_MPEG2_AAC_HE  131
2686 2687 2688 2689 2690 2691 2692 2693 2694 2695 2696 2697 2698 2699 2700 2701 2702 2703 2704 2705 2706 2707 2708 2709 2710 2711 2712 2713 2714 2715 2716 2717 2718 2719 2720 2721 2722 2723 2724 2725 2726 2727 2728 2729 2730 2731 2732 2733 2734 2735 2736 2737

#define FF_PROFILE_DTS         20
#define FF_PROFILE_DTS_ES      30
#define FF_PROFILE_DTS_96_24   40
#define FF_PROFILE_DTS_HD_HRA  50
#define FF_PROFILE_DTS_HD_MA   60

#define FF_PROFILE_MPEG2_422    0
#define FF_PROFILE_MPEG2_HIGH   1
#define FF_PROFILE_MPEG2_SS     2
#define FF_PROFILE_MPEG2_SNR_SCALABLE  3
#define FF_PROFILE_MPEG2_MAIN   4
#define FF_PROFILE_MPEG2_SIMPLE 5

#define FF_PROFILE_H264_CONSTRAINED  (1<<9)  // 8+1; constraint_set1_flag
#define FF_PROFILE_H264_INTRA        (1<<11) // 8+3; constraint_set3_flag

#define FF_PROFILE_H264_BASELINE             66
#define FF_PROFILE_H264_CONSTRAINED_BASELINE (66|FF_PROFILE_H264_CONSTRAINED)
#define FF_PROFILE_H264_MAIN                 77
#define FF_PROFILE_H264_EXTENDED             88
#define FF_PROFILE_H264_HIGH                 100
#define FF_PROFILE_H264_HIGH_10              110
#define FF_PROFILE_H264_HIGH_10_INTRA        (110|FF_PROFILE_H264_INTRA)
#define FF_PROFILE_H264_HIGH_422             122
#define FF_PROFILE_H264_HIGH_422_INTRA       (122|FF_PROFILE_H264_INTRA)
#define FF_PROFILE_H264_HIGH_444             144
#define FF_PROFILE_H264_HIGH_444_PREDICTIVE  244
#define FF_PROFILE_H264_HIGH_444_INTRA       (244|FF_PROFILE_H264_INTRA)
#define FF_PROFILE_H264_CAVLC_444            44

#define FF_PROFILE_VC1_SIMPLE   0
#define FF_PROFILE_VC1_MAIN     1
#define FF_PROFILE_VC1_COMPLEX  2
#define FF_PROFILE_VC1_ADVANCED 3

#define FF_PROFILE_MPEG4_SIMPLE                     0
#define FF_PROFILE_MPEG4_SIMPLE_SCALABLE            1
#define FF_PROFILE_MPEG4_CORE                       2
#define FF_PROFILE_MPEG4_MAIN                       3
#define FF_PROFILE_MPEG4_N_BIT                      4
#define FF_PROFILE_MPEG4_SCALABLE_TEXTURE           5
#define FF_PROFILE_MPEG4_SIMPLE_FACE_ANIMATION      6
#define FF_PROFILE_MPEG4_BASIC_ANIMATED_TEXTURE     7
#define FF_PROFILE_MPEG4_HYBRID                     8
#define FF_PROFILE_MPEG4_ADVANCED_REAL_TIME         9
#define FF_PROFILE_MPEG4_CORE_SCALABLE             10
#define FF_PROFILE_MPEG4_ADVANCED_CODING           11
#define FF_PROFILE_MPEG4_ADVANCED_CORE             12
#define FF_PROFILE_MPEG4_ADVANCED_SCALABLE_TEXTURE 13
#define FF_PROFILE_MPEG4_SIMPLE_STUDIO             14
#define FF_PROFILE_MPEG4_ADVANCED_SIMPLE           15
2738

2739 2740 2741 2742 2743 2744
#define FF_PROFILE_JPEG2000_CSTREAM_RESTRICTION_0   0
#define FF_PROFILE_JPEG2000_CSTREAM_RESTRICTION_1   1
#define FF_PROFILE_JPEG2000_CSTREAM_NO_RESTRICTION  2
#define FF_PROFILE_JPEG2000_DCINEMA_2K              3
#define FF_PROFILE_JPEG2000_DCINEMA_4K              4

2745
    /**
2746 2747 2748
     * level
     * - encoding: Set by user.
     * - decoding: Set by libavcodec.
2749
     */
2750 2751
     int level;
#define FF_LEVEL_UNKNOWN -99
2752

2753
    /**
2754
     * Skip loop filtering for selected frames.
2755 2756
     * - encoding: unused
     * - decoding: Set by user.
2757
     */
2758
    enum AVDiscard skip_loop_filter;
2759 2760

    /**
2761
     * Skip IDCT/dequantization for selected frames.
2762 2763
     * - encoding: unused
     * - decoding: Set by user.
2764
     */
2765
    enum AVDiscard skip_idct;
2766 2767

    /**
2768
     * Skip decoding for selected frames.
2769
     * - encoding: unused
2770 2771
     * - decoding: Set by user.
     */
2772
    enum AVDiscard skip_frame;
2773

2774
    /**
2775 2776 2777 2778 2779 2780
     * Header containing style information for text subtitles.
     * For SUBTITLE_ASS subtitle type, it should contain the whole ASS
     * [Script Info] and [V4+ Styles] section, plus the [Events] line and
     * the Format line following. It shouldn't include any Dialogue line.
     * - encoding: Set/allocated/freed by user (before avcodec_open2())
     * - decoding: Set/allocated/freed by libavcodec (by avcodec_open2())
2781
     */
2782 2783
    uint8_t *subtitle_header;
    int subtitle_header_size;
2784

2785
    /**
2786
     * Simulates errors in the bitstream to test error concealment.
2787
     * - encoding: Set by user.
2788
     * - decoding: unused
2789
     */
2790
    int error_rate;
2791

2792
    /**
2793 2794 2795 2796
     * Current packet as passed into the decoder, to avoid having
     * to pass the packet into every function. Currently only valid
     * inside lavc and get/release_buffer callbacks.
     * - decoding: set by avcodec_decode_*, read by get_buffer() for setting pkt_pts
2797 2798
     * - encoding: unused
     */
2799
    AVPacket *pkt;
2800

2801
    /**
2802 2803 2804 2805
     * VBV delay coded in the last frame (in periods of a 27 MHz clock).
     * Used for compliant TS muxing.
     * - encoding: Set by libavcodec.
     * - decoding: unused.
2806
     */
2807
    uint64_t vbv_delay;
2808

2809 2810 2811
    /**
     * Timebase in which pkt_dts/pts and AVPacket.dts/pts are.
     * Code outside libavcodec should access this field using:
2812
     * av_codec_{get,set}_pkt_timebase(avctx)
2813
     * - encoding unused.
2814
     * - decoding set by user.
2815 2816 2817
     */
    AVRational pkt_timebase;

2818 2819 2820
    /**
     * AVCodecDescriptor
     * Code outside libavcodec should access this field using:
2821
     * av_codec_{get,set}_codec_descriptor(avctx)
2822 2823 2824
     * - encoding: unused.
     * - decoding: set by libavcodec.
     */
2825
    const AVCodecDescriptor *codec_descriptor;
2826

2827 2828 2829 2830 2831 2832 2833 2834 2835 2836 2837
#if !FF_API_LOWRES
    /**
     * low resolution decoding, 1-> 1/2 size, 2->1/4 size
     * - encoding: unused
     * - decoding: Set by user.
     * Code outside libavcodec should access this field using:
     * av_codec_{get,set}_lowres(avctx)
     */
     int lowres;
#endif

2838 2839
    /**
     * Current statistics for PTS correction.
2840
     * - decoding: maintained and used by libavcodec, not intended to be used by user apps
2841 2842 2843 2844 2845 2846
     * - encoding: unused
     */
    int64_t pts_correction_num_faulty_pts; /// Number of incorrect PTS values so far
    int64_t pts_correction_num_faulty_dts; /// Number of incorrect DTS values so far
    int64_t pts_correction_last_pts;       /// PTS of the last frame
    int64_t pts_correction_last_dts;       /// DTS of the last frame
2847

2848 2849 2850 2851 2852 2853 2854 2855 2856 2857 2858 2859 2860 2861 2862 2863 2864
    /**
     * Character encoding of the input subtitles file.
     * - decoding: set by user
     * - encoding: unused
     */
    char *sub_charenc;

    /**
     * Subtitles character encoding mode. Formats or codecs might be adjusting
     * this setting (if they are doing the conversion themselves for instance).
     * - decoding: set by libavcodec
     * - encoding: unused
     */
    int sub_charenc_mode;
#define FF_SUB_CHARENC_MODE_DO_NOTHING  -1  ///< do nothing (demuxer outputs a stream supposed to be already in UTF-8, or the codec is bitmap for instance)
#define FF_SUB_CHARENC_MODE_AUTOMATIC    0  ///< libavcodec will select the mode itself
#define FF_SUB_CHARENC_MODE_PRE_DECODER  1  ///< the AVPacket data needs to be recoded to UTF-8 before being fed to the decoder, requires iconv
2865

Fabrice Bellard's avatar
Fabrice Bellard committed
2866 2867
} AVCodecContext;

2868 2869 2870
AVRational av_codec_get_pkt_timebase         (const AVCodecContext *avctx);
void       av_codec_set_pkt_timebase         (AVCodecContext *avctx, AVRational val);

2871 2872
const AVCodecDescriptor *av_codec_get_codec_descriptor(const AVCodecContext *avctx);
void                     av_codec_set_codec_descriptor(AVCodecContext *avctx, const AVCodecDescriptor *desc);
2873

2874 2875 2876
int  av_codec_get_lowres(const AVCodecContext *avctx);
void av_codec_set_lowres(AVCodecContext *avctx, int val);

2877 2878 2879 2880 2881 2882 2883 2884
/**
 * AVProfile.
 */
typedef struct AVProfile {
    int profile;
    const char *name; ///< short name for the profile
} AVProfile;

2885 2886
typedef struct AVCodecDefault AVCodecDefault;

2887 2888
struct AVSubtitle;

2889 2890 2891
/**
 * AVCodec.
 */
Fabrice Bellard's avatar
Fabrice Bellard committed
2892
typedef struct AVCodec {
2893 2894 2895 2896 2897 2898
    /**
     * Name of the codec implementation.
     * The name is globally unique among encoders and among decoders (but an
     * encoder and a decoder can share the same name).
     * This is the primary way to find a codec from the user perspective.
     */
2899
    const char *name;
2900 2901 2902 2903 2904
    /**
     * Descriptive name for the codec, meant to be more human readable than name.
     * You should use the NULL_IF_CONFIG_SMALL() macro to define it.
     */
    const char *long_name;
2905
    enum AVMediaType type;
2906
    enum AVCodecID id;
2907 2908 2909 2910
    /**
     * Codec capabilities.
     * see CODEC_CAP_*
     */
2911
    int capabilities;
2912
    const AVRational *supported_framerates; ///< array of supported framerates, or NULL if any, array is terminated by {0,0}
2913
    const enum AVPixelFormat *pix_fmts;     ///< array of supported pixel formats, or NULL if unknown, array is terminated by -1
2914
    const int *supported_samplerates;       ///< array of supported audio samplerates, or NULL if unknown, array is terminated by 0
2915
    const enum AVSampleFormat *sample_fmts; ///< array of supported sample formats, or NULL if unknown, array is terminated by -1
2916
    const uint64_t *channel_layouts;         ///< array of support channel layouts, or NULL if unknown. array is terminated by 0
Michael Niedermayer's avatar
Michael Niedermayer committed
2917
    uint8_t max_lowres;                     ///< maximum value for lowres supported by the decoder
2918
    const AVClass *priv_class;              ///< AVClass for the private context
2919
    const AVProfile *profiles;              ///< array of recognized profiles, or NULL if unknown, array is terminated by {FF_PROFILE_UNKNOWN}
2920

2921 2922 2923 2924 2925 2926 2927 2928 2929
    /*****************************************************************
     * No fields below this line are part of the public API. They
     * may not be used outside of libavcodec and can be changed and
     * removed at will.
     * New public fields should be added right above.
     *****************************************************************
     */
    int priv_data_size;
    struct AVCodec *next;
2930
    /**
2931
     * @name Frame-level threading support functions
2932 2933 2934 2935 2936 2937 2938 2939 2940 2941 2942 2943 2944 2945 2946 2947 2948
     * @{
     */
    /**
     * If defined, called on thread contexts when they are created.
     * If the codec allocates writable tables in init(), re-allocate them here.
     * priv_data will be set to a copy of the original.
     */
    int (*init_thread_copy)(AVCodecContext *);
    /**
     * Copy necessary context variables from a previous thread context to the current one.
     * If not defined, the next thread will start automatically; otherwise, the codec
     * must call ff_thread_finish_setup().
     *
     * dst and src will (rarely) point to the same context, in which case memcpy should be skipped.
     */
    int (*update_thread_context)(AVCodecContext *dst, const AVCodecContext *src);
    /** @} */
2949 2950 2951 2952 2953

    /**
     * Private codec-specific defaults.
     */
    const AVCodecDefault *defaults;
2954 2955 2956 2957 2958

    /**
     * Initialize codec static data, called from avcodec_register().
     */
    void (*init_static_data)(struct AVCodec *codec);
2959

2960
    int (*init)(AVCodecContext *);
2961 2962
    int (*encode_sub)(AVCodecContext *, uint8_t *buf, int buf_size,
                      const struct AVSubtitle *sub);
2963 2964 2965 2966 2967 2968 2969 2970 2971 2972 2973 2974
    /**
     * Encode data to an AVPacket.
     *
     * @param      avctx          codec context
     * @param      avpkt          output AVPacket (may contain a user-provided buffer)
     * @param[in]  frame          AVFrame containing the raw data to be encoded
     * @param[out] got_packet_ptr encoder sets to 0 or 1 to indicate that a
     *                            non-empty packet was returned in avpkt.
     * @return 0 on success, negative error code on failure
     */
    int (*encode2)(AVCodecContext *avctx, AVPacket *avpkt, const AVFrame *frame,
                   int *got_packet_ptr);
2975 2976 2977 2978 2979 2980 2981
    int (*decode)(AVCodecContext *, void *outdata, int *outdata_size, AVPacket *avpkt);
    int (*close)(AVCodecContext *);
    /**
     * Flush buffers.
     * Will be called when seeking
     */
    void (*flush)(AVCodecContext *);
Fabrice Bellard's avatar
Fabrice Bellard committed
2982 2983
} AVCodec;

2984 2985 2986 2987 2988 2989 2990 2991 2992 2993 2994 2995 2996 2997
/**
 * AVHWAccel.
 */
typedef struct AVHWAccel {
    /**
     * Name of the hardware accelerated codec.
     * The name is globally unique among encoders and among decoders (but an
     * encoder and a decoder can share the same name).
     */
    const char *name;

    /**
     * Type of codec implemented by the hardware accelerator.
     *
2998
     * See AVMEDIA_TYPE_xxx
2999
     */
3000
    enum AVMediaType type;
3001 3002 3003 3004

    /**
     * Codec implemented by the hardware accelerator.
     *
3005
     * See AV_CODEC_ID_xxx
3006
     */
3007
    enum AVCodecID id;
3008 3009 3010 3011 3012 3013

    /**
     * Supported pixel format.
     *
     * Only hardware accelerated formats are supported here.
     */
3014
    enum AVPixelFormat pix_fmt;
3015 3016 3017 3018 3019 3020 3021 3022 3023 3024 3025 3026 3027 3028 3029

    /**
     * Hardware accelerated codec capabilities.
     * see FF_HWACCEL_CODEC_CAP_*
     */
    int capabilities;

    struct AVHWAccel *next;

    /**
     * Called at the beginning of each frame or field picture.
     *
     * Meaningful frame information (codec specific) is guaranteed to
     * be parsed at this point. This function is mandatory.
     *
3030
     * Note that buf can be NULL along with buf_size set to 0.
3031 3032 3033 3034 3035 3036 3037 3038 3039 3040 3041 3042 3043 3044 3045 3046 3047 3048 3049 3050 3051 3052 3053 3054 3055 3056 3057 3058 3059 3060 3061 3062
     * Otherwise, this means the whole frame is available at this point.
     *
     * @param avctx the codec context
     * @param buf the frame data buffer base
     * @param buf_size the size of the frame in bytes
     * @return zero if successful, a negative value otherwise
     */
    int (*start_frame)(AVCodecContext *avctx, const uint8_t *buf, uint32_t buf_size);

    /**
     * Callback for each slice.
     *
     * Meaningful slice information (codec specific) is guaranteed to
     * be parsed at this point. This function is mandatory.
     *
     * @param avctx the codec context
     * @param buf the slice data buffer base
     * @param buf_size the size of the slice in bytes
     * @return zero if successful, a negative value otherwise
     */
    int (*decode_slice)(AVCodecContext *avctx, const uint8_t *buf, uint32_t buf_size);

    /**
     * Called at the end of each frame or field picture.
     *
     * The whole picture is parsed at this point and can now be sent
     * to the hardware accelerator. This function is mandatory.
     *
     * @param avctx the codec context
     * @return zero if successful, a negative value otherwise
     */
    int (*end_frame)(AVCodecContext *avctx);
3063 3064 3065 3066

    /**
     * Size of HW accelerator private data.
     *
3067 3068 3069
     * Private data is allocated with av_mallocz() before
     * AVCodecContext.get_buffer() and deallocated after
     * AVCodecContext.release_buffer().
3070 3071
     */
    int priv_data_size;
3072 3073
} AVHWAccel;

3074 3075 3076 3077 3078 3079 3080
/**
 * @defgroup lavc_picture AVPicture
 *
 * Functions for working with AVPicture
 * @{
 */

3081
/**
3082 3083 3084 3085
 * Picture data structure.
 *
 * Up to four components can be stored into it, the last component is
 * alpha.
3086
 */
Fabrice Bellard's avatar
Fabrice Bellard committed
3087
typedef struct AVPicture {
3088
    uint8_t *data[AV_NUM_DATA_POINTERS];    ///< pointers to the image data planes
3089
    int linesize[AV_NUM_DATA_POINTERS];     ///< number of bytes per line
Fabrice Bellard's avatar
Fabrice Bellard committed
3090 3091
} AVPicture;

3092 3093 3094 3095
/**
 * @}
 */

3096 3097 3098 3099 3100 3101 3102 3103 3104 3105 3106 3107 3108 3109 3110 3111 3112 3113
enum AVSubtitleType {
    SUBTITLE_NONE,

    SUBTITLE_BITMAP,                ///< A bitmap, pict will be set

    /**
     * Plain text, the text field must be set by the decoder and is
     * authoritative. ass and pict fields may contain approximations.
     */
    SUBTITLE_TEXT,

    /**
     * Formatted text, the ass field must be set by the decoder and is
     * authoritative. pict and text fields may contain approximations.
     */
    SUBTITLE_ASS,
};

3114 3115
#define AV_SUBTITLE_FLAG_FORCED 0x00000001

3116
typedef struct AVSubtitleRect {
3117 3118 3119 3120 3121
    int x;         ///< top left corner  of pict, undefined when pict is not set
    int y;         ///< top left corner  of pict, undefined when pict is not set
    int w;         ///< width            of pict, undefined when pict is not set
    int h;         ///< height           of pict, undefined when pict is not set
    int nb_colors; ///< number of colors in pict, undefined when pict is not set
3122 3123 3124 3125 3126 3127

    /**
     * data+linesize for the bitmap of this subtitle.
     * can be set for text/ass as well once they where rendered
     */
    AVPicture pict;
3128 3129 3130 3131 3132 3133
    enum AVSubtitleType type;

    char *text;                     ///< 0 terminated plain UTF-8 text

    /**
     * 0 terminated ASS/SSA compatible event line.
3134
     * The presentation of this is unaffected by the other values in this
3135 3136 3137
     * struct.
     */
    char *ass;
3138

3139
    int flags;
3140 3141 3142 3143 3144 3145
} AVSubtitleRect;

typedef struct AVSubtitle {
    uint16_t format; /* 0 = graphics */
    uint32_t start_display_time; /* relative to packet pts, in ms */
    uint32_t end_display_time; /* relative to packet pts, in ms */
3146
    unsigned num_rects;
3147
    AVSubtitleRect **rects;
3148
    int64_t pts;    ///< Same as packet pts, in AV_TIME_BASE
3149 3150
} AVSubtitle;

3151
/**
3152 3153 3154
 * If c is NULL, returns the first registered codec,
 * if c is non-NULL, returns the next registered codec after c,
 * or NULL if c is the last one.
3155
 */
3156
AVCodec *av_codec_next(const AVCodec *c);
3157 3158

/**
3159
 * Return the LIBAVCODEC_VERSION_INT constant.
3160
 */
3161
unsigned avcodec_version(void);
3162 3163

/**
3164
 * Return the libavcodec build-time configuration.
3165
 */
3166
const char *avcodec_configuration(void);
3167 3168

/**
3169
 * Return the libavcodec license.
3170
 */
3171
const char *avcodec_license(void);
3172

3173
/**
3174
 * Register the codec codec and initialize libavcodec.
3175
 *
3176 3177 3178 3179
 * @warning either this function or avcodec_register_all() must be called
 * before any other libavcodec functions.
 *
 * @see avcodec_register_all()
3180
 */
3181
void avcodec_register(AVCodec *codec);
3182

3183
/**
3184 3185 3186 3187
 * Register all the codecs, parsers and bitstream filters which were enabled at
 * configuration time. If you do not call this function you can select exactly
 * which formats you want to support, by using the individual registration
 * functions.
3188
 *
3189 3190 3191
 * @see avcodec_register
 * @see av_register_codec_parser
 * @see av_register_bitstream_filter
3192
 */
3193
void avcodec_register_all(void);
3194

3195

3196
#if FF_API_ALLOC_CONTEXT
3197
/**
3198 3199
 * Allocate an AVCodecContext and set its fields to default values.  The
 * resulting struct can be deallocated by simply calling av_free().
3200
 *
3201 3202 3203 3204
 * @return An AVCodecContext filled with default values or NULL on failure.
 * @see avcodec_get_context_defaults
 *
 * @deprecated use avcodec_alloc_context3()
3205
 */
3206 3207 3208 3209 3210 3211 3212
attribute_deprecated
AVCodecContext *avcodec_alloc_context(void);

/** THIS FUNCTION IS NOT YET PART OF THE PUBLIC API!
 *  we WILL change its arguments and name a few times! */
attribute_deprecated
AVCodecContext *avcodec_alloc_context2(enum AVMediaType);
3213

3214
/**
3215
 * Set the fields of the given AVCodecContext to default values.
3216
 *
3217 3218
 * @param s The AVCodecContext of which the fields should be set to default values.
 * @deprecated use avcodec_get_context_defaults3
3219
 */
3220 3221 3222 3223 3224 3225 3226 3227
attribute_deprecated
void avcodec_get_context_defaults(AVCodecContext *s);

/** THIS FUNCTION IS NOT YET PART OF THE PUBLIC API!
 *  we WILL change its arguments and name a few times! */
attribute_deprecated
void avcodec_get_context_defaults2(AVCodecContext *s, enum AVMediaType);
#endif
3228

3229
/**
3230 3231 3232
 * Allocate an AVCodecContext and set its fields to default values.  The
 * resulting struct can be deallocated by calling avcodec_close() on it followed
 * by av_free().
3233
 *
3234 3235 3236 3237 3238 3239 3240 3241 3242
 * @param codec if non-NULL, allocate private data and initialize defaults
 *              for the given codec. It is illegal to then call avcodec_open2()
 *              with a different codec.
 *              If NULL, then the codec-specific defaults won't be initialized,
 *              which may result in suboptimal default settings (this is
 *              important mainly for encoders, e.g. libx264).
 *
 * @return An AVCodecContext filled with default values or NULL on failure.
 * @see avcodec_get_context_defaults
3243
 */
3244
AVCodecContext *avcodec_alloc_context3(const AVCodec *codec);
3245

3246
/**
3247 3248
 * Set the fields of the given AVCodecContext to default values corresponding
 * to the given codec (defaults may be codec-dependent).
3249
 *
3250 3251 3252 3253
 * Do not call this function if a non-NULL codec has been passed
 * to avcodec_alloc_context3() that allocated this AVCodecContext.
 * If codec is non-NULL, it is illegal to call avcodec_open2() with a
 * different codec on this AVCodecContext.
3254
 */
3255
int avcodec_get_context_defaults3(AVCodecContext *s, const AVCodec *codec);
Fabrice Bellard's avatar
Fabrice Bellard committed
3256

3257
/**
3258 3259
 * Get the AVClass for AVCodecContext. It can be used in combination with
 * AV_OPT_SEARCH_FAKE_OBJ for examining options.
3260
 *
3261
 * @see av_opt_find().
3262
 */
3263
const AVClass *avcodec_get_class(void);
3264 3265

/**
3266 3267
 * Get the AVClass for AVFrame. It can be used in combination with
 * AV_OPT_SEARCH_FAKE_OBJ for examining options.
3268
 *
3269
 * @see av_opt_find().
3270
 */
3271
const AVClass *avcodec_get_frame_class(void);
3272

3273 3274 3275 3276 3277 3278 3279 3280
/**
 * Get the AVClass for AVSubtitleRect. It can be used in combination with
 * AV_OPT_SEARCH_FAKE_OBJ for examining options.
 *
 * @see av_opt_find().
 */
const AVClass *avcodec_get_subtitle_rect_class(void);

3281
/**
3282 3283 3284 3285 3286 3287
 * Copy the settings of the source AVCodecContext into the destination
 * AVCodecContext. The resulting destination codec context will be
 * unopened, i.e. you are required to call avcodec_open2() before you
 * can use this AVCodecContext to decode/encode video/audio data.
 *
 * @param dest target codec context, should be initialized with
3288
 *             avcodec_alloc_context3(NULL), but otherwise uninitialized
3289 3290
 * @param src source codec context
 * @return AVERROR() on error (e.g. memory allocation error), 0 on success
3291
 */
3292
int avcodec_copy_context(AVCodecContext *dest, const AVCodecContext *src);
3293 3294

/**
3295
 * Allocate an AVFrame and set its fields to default values.  The resulting
3296
 * struct must be freed using avcodec_free_frame().
3297 3298 3299
 *
 * @return An AVFrame filled with default values or NULL on failure.
 * @see avcodec_get_frame_defaults
3300
 */
3301
AVFrame *avcodec_alloc_frame(void);
3302 3303

/**
3304
 * Set the fields of the given AVFrame to default values.
3305
 *
3306
 * @param frame The AVFrame of which the fields should be set to default values.
3307
 */
3308
void avcodec_get_frame_defaults(AVFrame *frame);
3309

3310 3311 3312 3313 3314 3315 3316 3317 3318 3319 3320
/**
 * Free the frame and any dynamically allocated objects in it,
 * e.g. extended_data.
 *
 * @param frame frame to be freed. The pointer will be set to NULL.
 *
 * @warning this function does NOT free the data buffers themselves
 * (it does not know how, since they might have been allocated with
 *  a custom get_buffer()).
 */
void avcodec_free_frame(AVFrame **frame);
3321

3322
#if FF_API_AVCODEC_OPEN
Drew Hess's avatar
Drew Hess committed
3323
/**
3324 3325
 * Initialize the AVCodecContext to use the given AVCodec. Prior to using this
 * function the context has to be allocated.
3326
 *
3327 3328 3329
 * The functions avcodec_find_decoder_by_name(), avcodec_find_encoder_by_name(),
 * avcodec_find_decoder() and avcodec_find_encoder() provide an easy way for
 * retrieving a codec.
Drew Hess's avatar
Drew Hess committed
3330
 *
3331
 * @warning This function is not thread safe!
3332
 *
3333 3334
 * @code
 * avcodec_register_all();
3335
 * codec = avcodec_find_decoder(AV_CODEC_ID_H264);
3336 3337 3338 3339 3340 3341 3342 3343 3344 3345 3346 3347 3348 3349 3350
 * if (!codec)
 *     exit(1);
 *
 * context = avcodec_alloc_context3(codec);
 *
 * if (avcodec_open(context, codec) < 0)
 *     exit(1);
 * @endcode
 *
 * @param avctx The context which will be set up to use the given codec.
 * @param codec The codec to use within the context.
 * @return zero on success, a negative value on error
 * @see avcodec_alloc_context3, avcodec_find_decoder, avcodec_find_encoder, avcodec_close
 *
 * @deprecated use avcodec_open2
3351
 */
3352 3353 3354
attribute_deprecated
int avcodec_open(AVCodecContext *avctx, AVCodec *codec);
#endif
Drew Hess's avatar
Drew Hess committed
3355

3356
/**
3357 3358
 * Initialize the AVCodecContext to use the given AVCodec. Prior to using this
 * function the context has to be allocated with avcodec_alloc_context3().
3359
 *
3360 3361 3362
 * The functions avcodec_find_decoder_by_name(), avcodec_find_encoder_by_name(),
 * avcodec_find_decoder() and avcodec_find_encoder() provide an easy way for
 * retrieving a codec.
3363
 *
3364 3365 3366 3367 3368
 * @warning This function is not thread safe!
 *
 * @code
 * avcodec_register_all();
 * av_dict_set(&opts, "b", "2.5M", 0);
3369
 * codec = avcodec_find_decoder(AV_CODEC_ID_H264);
3370 3371 3372 3373 3374 3375 3376 3377 3378 3379 3380 3381 3382 3383 3384 3385 3386 3387 3388 3389 3390
 * if (!codec)
 *     exit(1);
 *
 * context = avcodec_alloc_context3(codec);
 *
 * if (avcodec_open2(context, codec, opts) < 0)
 *     exit(1);
 * @endcode
 *
 * @param avctx The context to initialize.
 * @param codec The codec to open this context for. If a non-NULL codec has been
 *              previously passed to avcodec_alloc_context3() or
 *              avcodec_get_context_defaults3() for this context, then this
 *              parameter MUST be either NULL or equal to the previously passed
 *              codec.
 * @param options A dictionary filled with AVCodecContext and codec-private options.
 *                On return this object will be filled with options that were not found.
 *
 * @return zero on success, a negative value on error
 * @see avcodec_alloc_context3(), avcodec_find_decoder(), avcodec_find_encoder(),
 *      av_dict_set(), av_opt_find().
3391
 */
3392
int avcodec_open2(AVCodecContext *avctx, const AVCodec *codec, AVDictionary **options);
3393 3394

/**
3395 3396
 * Close a given AVCodecContext and free all the data associated with it
 * (but not the AVCodecContext itself).
3397
 *
3398 3399 3400 3401
 * Calling this function on an AVCodecContext that hasn't been opened will free
 * the codec-specific data allocated in avcodec_alloc_context3() /
 * avcodec_get_context_defaults3() with a non-NULL codec. Subsequent calls will
 * do nothing.
3402
 */
3403
int avcodec_close(AVCodecContext *avctx);
3404 3405

/**
3406
 * Free all allocated data in the given subtitle struct.
3407
 *
3408
 * @param sub AVSubtitle to free.
3409
 */
3410
void avsubtitle_free(AVSubtitle *sub);
3411

3412
/**
3413
 * @}
3414
 */
3415

3416
/**
3417 3418
 * @addtogroup lavc_packet
 * @{
3419
 */
3420

3421
#if FF_API_DESTRUCT_PACKET
3422 3423
/**
 * Default packet destructor.
3424
 * @deprecated use the AVBuffer API instead
3425
 */
3426
attribute_deprecated
3427
void av_destruct_packet(AVPacket *pkt);
3428
#endif
3429

3430
/**
3431
 * Initialize optional fields of a packet with default values.
3432
 *
3433 3434 3435
 * Note, this does not touch the data and size members, which have to be
 * initialized separately.
 *
3436
 * @param pkt packet
3437
 */
3438
void av_init_packet(AVPacket *pkt);
3439 3440

/**
3441 3442
 * Allocate the payload of a packet and initialize its fields with
 * default values.
3443
 *
3444 3445 3446
 * @param pkt packet
 * @param size wanted payload size
 * @return 0 if OK, AVERROR_xxx otherwise
3447
 */
3448
int av_new_packet(AVPacket *pkt, int size);
3449

3450
/**
3451
 * Reduce packet size, correctly zeroing padding
3452
 *
3453 3454
 * @param pkt packet
 * @param size new size
3455
 */
3456
void av_shrink_packet(AVPacket *pkt, int size);
Fabrice Bellard's avatar
Fabrice Bellard committed
3457

3458
/**
3459 3460 3461 3462
 * Increase packet size, correctly zeroing padding
 *
 * @param pkt packet
 * @param grow_by number of bytes by which to increase the size of the packet
3463
 */
3464
int av_grow_packet(AVPacket *pkt, int grow_by);
Fabrice Bellard's avatar
Fabrice Bellard committed
3465

3466 3467 3468 3469 3470 3471 3472 3473 3474 3475 3476 3477 3478 3479 3480
/**
 * Initialize a reference-counted packet from av_malloc()ed data.
 *
 * @param pkt packet to be initialized. This function will set the data, size,
 *        buf and destruct fields, all others are left untouched.
 * @param data Data allocated by av_malloc() to be used as packet data. If this
 *        function returns successfully, the data is owned by the underlying AVBuffer.
 *        The caller may not access the data through other means.
 * @param size size of data in bytes, without the padding. I.e. the full buffer
 *        size is assumed to be size + FF_INPUT_BUFFER_PADDING_SIZE.
 *
 * @return 0 on success, a negative AVERROR on error
 */
int av_packet_from_data(AVPacket *pkt, uint8_t *data, int size);

3481
/**
3482 3483
 * @warning This is a hack - the packet memory allocation stuff is broken. The
 * packet is allocated if it was not really allocated.
3484
 */
3485
int av_dup_packet(AVPacket *pkt);
3486

Andrey Utkin's avatar
Andrey Utkin committed
3487 3488 3489 3490 3491 3492 3493
/**
 * Copy packet, including contents
 *
 * @return 0 on success, negative AVERROR on fail
 */
int av_copy_packet(AVPacket *dst, AVPacket *src);

3494 3495 3496 3497 3498 3499 3500
/**
 * Copy packet side data
 *
 * @return 0 on success, negative AVERROR on fail
 */
int av_copy_packet_side_data(AVPacket *dst, AVPacket *src);

3501
/**
3502
 * Free a packet.
3503
 *
3504
 * @param pkt packet to free
3505
 */
Ramiro Polla's avatar
Ramiro Polla committed
3506
void av_free_packet(AVPacket *pkt);
3507 3508

/**
3509
 * Allocate new information of a packet.
3510
 *
3511 3512 3513 3514
 * @param pkt packet
 * @param type side information type
 * @param size side information size
 * @return pointer to fresh allocated data or NULL otherwise
3515
 */
3516 3517
uint8_t* av_packet_new_side_data(AVPacket *pkt, enum AVPacketSideDataType type,
                                 int size);
Fabrice Bellard's avatar
Fabrice Bellard committed
3518

3519
/**
3520
 * Shrink the already allocated side data buffer
3521
 *
3522 3523 3524 3525
 * @param pkt packet
 * @param type side information type
 * @param size new side information size
 * @return 0 on success, < 0 on failure
3526
 */
3527 3528
int av_packet_shrink_side_data(AVPacket *pkt, enum AVPacketSideDataType type,
                               int size);
3529

3530
/**
3531
 * Get side information from packet.
3532
 *
3533 3534 3535 3536
 * @param pkt packet
 * @param type desired side information type
 * @param size pointer for side information size to store (optional)
 * @return pointer to data if present or NULL otherwise
3537
 */
3538 3539
uint8_t* av_packet_get_side_data(AVPacket *pkt, enum AVPacketSideDataType type,
                                 int *size);
3540

3541
int av_packet_merge_side_data(AVPacket *pkt);
3542

3543
int av_packet_split_side_data(AVPacket *pkt);
3544

3545

3546 3547 3548 3549 3550 3551 3552 3553 3554 3555 3556 3557 3558 3559 3560 3561 3562 3563 3564 3565 3566 3567 3568 3569 3570 3571 3572 3573 3574 3575 3576 3577 3578 3579 3580 3581 3582 3583 3584 3585 3586 3587 3588 3589 3590 3591 3592 3593 3594 3595 3596 3597 3598 3599 3600 3601 3602 3603 3604 3605
/**
 * Convenience function to free all the side data stored.
 * All the other fields stay untouched.
 *
 * @param pkt packet
 */
void av_packet_free_side_data(AVPacket *pkt);

/**
 * Setup a new reference to the data described by a given packet
 *
 * If src is reference-counted, setup dst as a new reference to the
 * buffer in src. Otherwise allocate a new buffer in dst and copy the
 * data from src into it.
 *
 * All the other fields are copied from src.
 *
 * @see av_packet_unref
 *
 * @param dst Destination packet
 * @param src Source packet
 *
 * @return 0 on success, a negative AVERROR on error.
 */
int av_packet_ref(AVPacket *dst, AVPacket *src);

/**
 * Wipe the packet.
 *
 * Unreference the buffer referenced by the packet and reset the
 * remaining packet fields to their default values.
 *
 * @param pkt The packet to be unreferenced.
 */
void av_packet_unref(AVPacket *pkt);

/**
 * Move every field in src to dst and reset src.
 *
 * @see av_packet_unref
 *
 * @param src Source packet, will be reset
 * @param dst Destination packet
 */
void av_packet_move_ref(AVPacket *dst, AVPacket *src);

/**
 * Copy only "properties" fields from src to dst.
 *
 * Properties for the purpose of this function are all the fields
 * beside those related to the packet data (buf, data, size)
 *
 * @param dst Destination packet
 * @param src Source packet
 *
 * @return 0 on success AVERROR on failure.
 *
 */
int av_packet_copy_props(AVPacket *dst, const AVPacket *src);

3606
/**
3607
 * @}
3608
 */
3609

3610
/**
3611 3612
 * @addtogroup lavc_decoding
 * @{
3613 3614
 */

3615
/**
3616
 * Find a registered decoder with a matching codec ID.
3617
 *
3618
 * @param id AVCodecID of the requested decoder
3619
 * @return A decoder if one was found, NULL otherwise.
3620
 */
3621
AVCodec *avcodec_find_decoder(enum AVCodecID id);
3622 3623

/**
3624
 * Find a registered decoder with the specified name.
3625
 *
3626 3627
 * @param name name of the requested decoder
 * @return A decoder if one was found, NULL otherwise.
3628
 */
3629
AVCodec *avcodec_find_decoder_by_name(const char *name);
Michael Niedermayer's avatar
Michael Niedermayer committed
3630

3631 3632 3633 3634 3635 3636 3637 3638 3639 3640 3641 3642
#if FF_API_GET_BUFFER
attribute_deprecated int avcodec_default_get_buffer(AVCodecContext *s, AVFrame *pic);
attribute_deprecated void avcodec_default_release_buffer(AVCodecContext *s, AVFrame *pic);
attribute_deprecated int avcodec_default_reget_buffer(AVCodecContext *s, AVFrame *pic);
#endif

/**
 * The default callback for AVCodecContext.get_buffer2(). It is made public so
 * it can be called by custom get_buffer2() implementations for decoders without
 * CODEC_CAP_DR1 set.
 */
int avcodec_default_get_buffer2(AVCodecContext *s, AVFrame *frame, int flags);
3643 3644

/**
3645
 * Return the amount of padding in pixels which the get_buffer callback must
3646 3647 3648 3649 3650 3651
 * provide around the edge of the image for codecs which do not have the
 * CODEC_FLAG_EMU_EDGE flag.
 *
 * @return Required padding in pixels.
 */
unsigned avcodec_get_edge_width(void);
3652

3653
/**
3654
 * Modify width and height values so that they will result in a memory
3655 3656
 * buffer that is acceptable for the codec if you do not use any horizontal
 * padding.
3657 3658 3659 3660
 *
 * May only be used if a codec with CODEC_CAP_DR1 has been opened.
 * If CODEC_FLAG_EMU_EDGE is not set, the dimensions must have been increased
 * according to avcodec_get_edge_width() before.
3661
 */
3662
void avcodec_align_dimensions(AVCodecContext *s, int *width, int *height);
Drew Hess's avatar
Drew Hess committed
3663

3664
/**
3665
 * Modify width and height values so that they will result in a memory
3666 3667
 * buffer that is acceptable for the codec if you also ensure that all
 * line sizes are a multiple of the respective linesize_align[i].
3668 3669 3670 3671
 *
 * May only be used if a codec with CODEC_CAP_DR1 has been opened.
 * If CODEC_FLAG_EMU_EDGE is not set, the dimensions must have been increased
 * according to avcodec_get_edge_width() before.
3672 3673
 */
void avcodec_align_dimensions2(AVCodecContext *s, int *width, int *height,
3674
                               int linesize_align[AV_NUM_DATA_POINTERS]);
3675

3676 3677 3678 3679 3680 3681 3682 3683 3684 3685 3686
/**
 * Converts AVChromaLocation to swscale x/y chroma position.
 *
 * The positions represent the chroma (0,0) position in a coordinates system
 * with luma (0,0) representing the origin and luma(1,1) representing 256,256
 *
 * @param xpos  horizontal chroma sample position
 * @param ypos  vertical   chroma sample position
 */
int avcodec_enum_to_chroma_pos(int *xpos, int *ypos, enum AVChromaLocation pos);

3687 3688 3689 3690 3691 3692 3693 3694 3695 3696 3697
/**
 * Converts swscale x/y chroma position to AVChromaLocation.
 *
 * The positions represent the chroma (0,0) position in a coordinates system
 * with luma (0,0) representing the origin and luma(1,1) representing 256,256
 *
 * @param xpos  horizontal chroma sample position
 * @param ypos  vertical   chroma sample position
 */
enum AVChromaLocation avcodec_chroma_pos_to_enum(int xpos, int ypos);

3698
#if FF_API_OLD_DECODE_AUDIO
3699
/**
3700 3701 3702 3703
 * Wrapper function which calls avcodec_decode_audio4.
 *
 * @deprecated Use avcodec_decode_audio4 instead.
 *
3704
 * Decode the audio frame of size avpkt->size from avpkt->data into samples.
3705
 * Some decoders may support multiple frames in a single AVPacket, such
3706 3707 3708
 * decoders would then just decode the first frame. In this case,
 * avcodec_decode_audio3 has to be called again with an AVPacket that contains
 * the remaining data in order to decode the second frame etc.
3709
 * If no frame
3710
 * could be outputted, frame_size_ptr is zero. Otherwise, it is the
3711
 * decompressed frame size in bytes.
3712
 *
3713
 * @warning You must set frame_size_ptr to the allocated size of the
3714
 * output buffer before calling avcodec_decode_audio3().
3715
 *
3716
 * @warning The input buffer must be FF_INPUT_BUFFER_PADDING_SIZE larger than
3717 3718 3719
 * the actual read bytes because some optimized bitstream readers read 32 or 64
 * bits at once and could read over the end.
 *
3720
 * @warning The end of the input buffer avpkt->data should be set to 0 to ensure that
3721
 * no overreading happens for damaged MPEG streams.
3722
 *
3723 3724 3725 3726 3727
 * @warning You must not provide a custom get_buffer() when using
 * avcodec_decode_audio3().  Doing so will override it with
 * avcodec_default_get_buffer.  Use avcodec_decode_audio4() instead,
 * which does allow the application to provide a custom get_buffer().
 *
3728
 * @note You might have to align the input buffer avpkt->data and output buffer
Diego Biurrun's avatar
Diego Biurrun committed
3729
 * samples. The alignment requirements depend on the CPU: On some CPUs it isn't
3730
 * necessary at all, on others it won't work at all if not aligned and on others
3731 3732 3733 3734 3735
 * it will work but it will have an impact on performance.
 *
 * In practice, avpkt->data should have 4 byte alignment at minimum and
 * samples should be 16 byte aligned unless the CPU doesn't need it
 * (AltiVec and SSE do).
3736
 *
3737 3738 3739 3740
 * @note Codecs which have the CODEC_CAP_DELAY capability set have a delay
 * between input and output, these need to be fed with avpkt->data=NULL,
 * avpkt->size=0 at the end to return the remaining frames.
 *
Diego Biurrun's avatar
Diego Biurrun committed
3741
 * @param avctx the codec context
3742
 * @param[out] samples the output buffer, sample type in avctx->sample_fmt
3743 3744
 *                     If the sample format is planar, each channel plane will
 *                     be the same size, with no padding between channels.
Diego Biurrun's avatar
Diego Biurrun committed
3745
 * @param[in,out] frame_size_ptr the output buffer size in bytes
3746
 * @param[in] avpkt The input AVPacket containing the input buffer.
3747 3748 3749
 *            You can create such packet with av_init_packet() and by then setting
 *            data and size, some decoders might in addition need other fields.
 *            All decoders are designed to use the least fields possible though.
3750
 * @return On error a negative value is returned, otherwise the number of bytes
3751
 * used or zero if no frame data was decompressed (used) from the input AVPacket.
3752
 */
3753
attribute_deprecated int avcodec_decode_audio3(AVCodecContext *avctx, int16_t *samples,
Fabrice Bellard's avatar
Fabrice Bellard committed
3754
                         int *frame_size_ptr,
3755
                         AVPacket *avpkt);
3756 3757 3758 3759 3760 3761 3762 3763 3764 3765 3766 3767 3768 3769 3770 3771 3772 3773 3774 3775 3776
#endif

/**
 * Decode the audio frame of size avpkt->size from avpkt->data into frame.
 *
 * Some decoders may support multiple frames in a single AVPacket. Such
 * decoders would then just decode the first frame. In this case,
 * avcodec_decode_audio4 has to be called again with an AVPacket containing
 * the remaining data in order to decode the second frame, etc...
 * Even if no frames are returned, the packet needs to be fed to the decoder
 * with remaining data until it is completely consumed or an error occurs.
 *
 * @warning The input buffer, avpkt->data must be FF_INPUT_BUFFER_PADDING_SIZE
 *          larger than the actual read bytes because some optimized bitstream
 *          readers read 32 or 64 bits at once and could read over the end.
 *
 * @note You might have to align the input buffer. The alignment requirements
 *       depend on the CPU and the decoder.
 *
 * @param      avctx the codec context
 * @param[out] frame The AVFrame in which to store decoded audio samples.
3777 3778 3779 3780 3781 3782 3783 3784 3785 3786 3787
 *                   The decoder will allocate a buffer for the decoded frame by
 *                   calling the AVCodecContext.get_buffer2() callback.
 *                   When AVCodecContext.refcounted_frames is set to 1, the frame is
 *                   reference counted and the returned reference belongs to the
 *                   caller. The caller must release the frame using av_frame_unref()
 *                   when the frame is no longer needed. The caller may safely write
 *                   to the frame if av_frame_is_writable() returns 1.
 *                   When AVCodecContext.refcounted_frames is set to 0, the returned
 *                   reference belongs to the decoder and is valid only until the
 *                   next call to this function or until closing the decoder.
 *                   The caller may not write to it.
3788 3789 3790 3791 3792 3793 3794 3795 3796 3797
 * @param[out] got_frame_ptr Zero if no frame could be decoded, otherwise it is
 *                           non-zero.
 * @param[in]  avpkt The input AVPacket containing the input buffer.
 *                   At least avpkt->data and avpkt->size should be set. Some
 *                   decoders might also require additional fields to be set.
 * @return A negative error code is returned if an error occurred during
 *         decoding, otherwise the number of bytes consumed from the input
 *         AVPacket is returned.
 */
int avcodec_decode_audio4(AVCodecContext *avctx, AVFrame *frame,
3798
                          int *got_frame_ptr, const AVPacket *avpkt);
3799

3800
/**
3801
 * Decode the video frame of size avpkt->size from avpkt->data into picture.
3802 3803
 * Some decoders may support multiple frames in a single AVPacket, such
 * decoders would then just decode the first frame.
3804
 *
3805
 * @warning The input buffer must be FF_INPUT_BUFFER_PADDING_SIZE larger than
3806 3807 3808
 * the actual read bytes because some optimized bitstream readers read 32 or 64
 * bits at once and could read over the end.
 *
3809
 * @warning The end of the input buffer buf should be set to 0 to ensure that
3810 3811
 * no overreading happens for damaged MPEG streams.
 *
3812 3813
 * @note You might have to align the input buffer avpkt->data.
 * The alignment requirements depend on the CPU: on some CPUs it isn't
3814
 * necessary at all, on others it won't work at all if not aligned and on others
3815 3816 3817
 * it will work but it will have an impact on performance.
 *
 * In practice, avpkt->data should have 4 byte alignment at minimum.
3818
 *
3819 3820 3821
 * @note Codecs which have the CODEC_CAP_DELAY capability set have a delay
 * between input and output, these need to be fed with avpkt->data=NULL,
 * avpkt->size=0 at the end to return the remaining frames.
3822
 *
Diego Biurrun's avatar
Diego Biurrun committed
3823
 * @param avctx the codec context
3824
 * @param[out] picture The AVFrame in which the decoded video frame will be stored.
3825 3826 3827 3828 3829 3830 3831 3832 3833 3834 3835 3836
 *             Use av_frame_alloc() to get an AVFrame. The codec will
 *             allocate memory for the actual bitmap by calling the
 *             AVCodecContext.get_buffer2() callback.
 *             When AVCodecContext.refcounted_frames is set to 1, the frame is
 *             reference counted and the returned reference belongs to the
 *             caller. The caller must release the frame using av_frame_unref()
 *             when the frame is no longer needed. The caller may safely write
 *             to the frame if av_frame_is_writable() returns 1.
 *             When AVCodecContext.refcounted_frames is set to 0, the returned
 *             reference belongs to the decoder and is valid only until the
 *             next call to this function or until closing the decoder. The
 *             caller may not write to it.
3837
 *
3838
 * @param[in] avpkt The input AVPacket containing the input buffer.
3839 3840
 *            You can create such packet with av_init_packet() and by then setting
 *            data and size, some decoders might in addition need other fields like
3841
 *            flags&AV_PKT_FLAG_KEY. All decoders are designed to use the least
3842
 *            fields possible.
Diego Biurrun's avatar
Diego Biurrun committed
3843
 * @param[in,out] got_picture_ptr Zero if no frame could be decompressed, otherwise, it is nonzero.
3844 3845 3846
 * @return On error a negative value is returned, otherwise the number of bytes
 * used or zero if no frame could be decompressed.
 */
3847
int avcodec_decode_video2(AVCodecContext *avctx, AVFrame *picture,
Fabrice Bellard's avatar
Fabrice Bellard committed
3848
                         int *got_picture_ptr,
3849
                         const AVPacket *avpkt);
3850

3851
/**
3852
 * Decode a subtitle message.
Måns Rullgård's avatar
Måns Rullgård committed
3853
 * Return a negative value on error, otherwise return the number of bytes used.
3854 3855
 * If no subtitle could be decompressed, got_sub_ptr is zero.
 * Otherwise, the subtitle is stored in *sub.
3856 3857 3858 3859
 * Note that CODEC_CAP_DR1 is not available for subtitle codecs. This is for
 * simplicity, because the performance difference is expect to be negligible
 * and reusing a get_buffer written for video codecs would probably perform badly
 * due to a potentially very different allocation pattern.
3860 3861
 *
 * @param avctx the codec context
3862 3863
 * @param[out] sub The AVSubtitle in which the decoded subtitle will be stored, must be
                   freed with avsubtitle_free if *got_sub_ptr is set.
3864 3865 3866 3867 3868 3869
 * @param[in,out] got_sub_ptr Zero if no subtitle could be decompressed, otherwise, it is nonzero.
 * @param[in] avpkt The input AVPacket containing the input buffer.
 */
int avcodec_decode_subtitle2(AVCodecContext *avctx, AVSubtitle *sub,
                            int *got_sub_ptr,
                            AVPacket *avpkt);
3870 3871

/**
3872 3873
 * @defgroup lavc_parsing Frame parsing
 * @{
3874 3875
 */

3876 3877 3878 3879 3880 3881 3882
enum AVPictureStructure {
    AV_PICTURE_STRUCTURE_UNKNOWN,      //< unknown
    AV_PICTURE_STRUCTURE_TOP_FIELD,    //< coded as top field
    AV_PICTURE_STRUCTURE_BOTTOM_FIELD, //< coded as bottom field
    AV_PICTURE_STRUCTURE_FRAME,        //< coded as frame
};

3883 3884 3885 3886 3887 3888 3889 3890 3891 3892 3893 3894 3895 3896 3897 3898 3899 3900 3901 3902 3903 3904 3905 3906 3907 3908 3909 3910 3911 3912 3913 3914 3915 3916 3917 3918 3919 3920
typedef struct AVCodecParserContext {
    void *priv_data;
    struct AVCodecParser *parser;
    int64_t frame_offset; /* offset of the current frame */
    int64_t cur_offset; /* current offset
                           (incremented by each av_parser_parse()) */
    int64_t next_frame_offset; /* offset of the next frame */
    /* video info */
    int pict_type; /* XXX: Put it back in AVCodecContext. */
    /**
     * This field is used for proper frame duration computation in lavf.
     * It signals, how much longer the frame duration of the current frame
     * is compared to normal frame duration.
     *
     * frame_duration = (1 + repeat_pict) * time_base
     *
     * It is used by codecs like H.264 to display telecined material.
     */
    int repeat_pict; /* XXX: Put it back in AVCodecContext. */
    int64_t pts;     /* pts of the current frame */
    int64_t dts;     /* dts of the current frame */

    /* private data */
    int64_t last_pts;
    int64_t last_dts;
    int fetch_timestamp;

#define AV_PARSER_PTS_NB 4
    int cur_frame_start_index;
    int64_t cur_frame_offset[AV_PARSER_PTS_NB];
    int64_t cur_frame_pts[AV_PARSER_PTS_NB];
    int64_t cur_frame_dts[AV_PARSER_PTS_NB];

    int flags;
#define PARSER_FLAG_COMPLETE_FRAMES           0x0001
#define PARSER_FLAG_ONCE                      0x0002
/// Set if the parser has a valid file offset
#define PARSER_FLAG_FETCHED_OFFSET            0x0004
3921
#define PARSER_FLAG_USE_CODEC_TS              0x1000
3922 3923 3924 3925 3926 3927 3928 3929 3930 3931 3932 3933 3934 3935 3936 3937 3938 3939 3940 3941 3942 3943 3944 3945 3946 3947 3948 3949 3950 3951 3952 3953 3954 3955 3956 3957 3958 3959 3960 3961 3962 3963 3964 3965 3966 3967 3968 3969 3970 3971 3972 3973 3974 3975 3976 3977 3978 3979 3980 3981 3982 3983 3984 3985 3986 3987 3988 3989 3990 3991 3992 3993 3994 3995 3996 3997 3998 3999 4000 4001 4002 4003 4004 4005 4006 4007 4008 4009 4010 4011 4012 4013 4014 4015 4016

    int64_t offset;      ///< byte offset from starting packet start
    int64_t cur_frame_end[AV_PARSER_PTS_NB];

    /**
     * Set by parser to 1 for key frames and 0 for non-key frames.
     * It is initialized to -1, so if the parser doesn't set this flag,
     * old-style fallback using AV_PICTURE_TYPE_I picture type as key frames
     * will be used.
     */
    int key_frame;

    /**
     * Time difference in stream time base units from the pts of this
     * packet to the point at which the output from the decoder has converged
     * independent from the availability of previous frames. That is, the
     * frames are virtually identical no matter if decoding started from
     * the very first frame or from this keyframe.
     * Is AV_NOPTS_VALUE if unknown.
     * This field is not the display duration of the current frame.
     * This field has no meaning if the packet does not have AV_PKT_FLAG_KEY
     * set.
     *
     * The purpose of this field is to allow seeking in streams that have no
     * keyframes in the conventional sense. It corresponds to the
     * recovery point SEI in H.264 and match_time_delta in NUT. It is also
     * essential for some types of subtitle streams to ensure that all
     * subtitles are correctly displayed after seeking.
     */
    int64_t convergence_duration;

    // Timestamp generation support:
    /**
     * Synchronization point for start of timestamp generation.
     *
     * Set to >0 for sync point, 0 for no sync point and <0 for undefined
     * (default).
     *
     * For example, this corresponds to presence of H.264 buffering period
     * SEI message.
     */
    int dts_sync_point;

    /**
     * Offset of the current timestamp against last timestamp sync point in
     * units of AVCodecContext.time_base.
     *
     * Set to INT_MIN when dts_sync_point unused. Otherwise, it must
     * contain a valid timestamp offset.
     *
     * Note that the timestamp of sync point has usually a nonzero
     * dts_ref_dts_delta, which refers to the previous sync point. Offset of
     * the next frame after timestamp sync point will be usually 1.
     *
     * For example, this corresponds to H.264 cpb_removal_delay.
     */
    int dts_ref_dts_delta;

    /**
     * Presentation delay of current frame in units of AVCodecContext.time_base.
     *
     * Set to INT_MIN when dts_sync_point unused. Otherwise, it must
     * contain valid non-negative timestamp delta (presentation time of a frame
     * must not lie in the past).
     *
     * This delay represents the difference between decoding and presentation
     * time of the frame.
     *
     * For example, this corresponds to H.264 dpb_output_delay.
     */
    int pts_dts_delta;

    /**
     * Position of the packet in file.
     *
     * Analogous to cur_frame_pts/dts
     */
    int64_t cur_frame_pos[AV_PARSER_PTS_NB];

    /**
     * Byte position of currently parsed frame in stream.
     */
    int64_t pos;

    /**
     * Previous frame byte position.
     */
    int64_t last_pos;

    /**
     * Duration of the current frame.
     * For audio, this is in units of 1 / AVCodecContext.sample_rate.
     * For all other types, this is in units of AVCodecContext.time_base.
     */
    int duration;
4017 4018

    enum AVFieldOrder field_order;
4019 4020 4021 4022 4023 4024 4025 4026 4027 4028

    /**
     * Indicate whether a picture is coded as a frame, top field or bottom field.
     *
     * For example, H.264 field_pic_flag equal to 0 corresponds to
     * AV_PICTURE_STRUCTURE_FRAME. An H.264 picture with field_pic_flag
     * equal to 1 and bottom_field_flag equal to 0 corresponds to
     * AV_PICTURE_STRUCTURE_TOP_FIELD.
     */
    enum AVPictureStructure picture_structure;
4029 4030 4031 4032 4033 4034 4035 4036

    /**
     * Picture number incremented in presentation or output order.
     * This field may be reinitialized at the first picture of a new sequence.
     *
     * For example, this corresponds to H.264 PicOrderCnt.
     */
    int output_picture_number;
4037 4038 4039 4040 4041 4042 4043 4044 4045 4046 4047 4048 4049 4050 4051 4052 4053 4054 4055 4056 4057 4058 4059 4060 4061 4062 4063 4064 4065 4066 4067 4068 4069 4070 4071 4072 4073 4074 4075 4076 4077 4078 4079 4080 4081 4082 4083 4084 4085 4086 4087 4088 4089 4090 4091
} AVCodecParserContext;

typedef struct AVCodecParser {
    int codec_ids[5]; /* several codec IDs are permitted */
    int priv_data_size;
    int (*parser_init)(AVCodecParserContext *s);
    int (*parser_parse)(AVCodecParserContext *s,
                        AVCodecContext *avctx,
                        const uint8_t **poutbuf, int *poutbuf_size,
                        const uint8_t *buf, int buf_size);
    void (*parser_close)(AVCodecParserContext *s);
    int (*split)(AVCodecContext *avctx, const uint8_t *buf, int buf_size);
    struct AVCodecParser *next;
} AVCodecParser;

AVCodecParser *av_parser_next(AVCodecParser *c);

void av_register_codec_parser(AVCodecParser *parser);
AVCodecParserContext *av_parser_init(int codec_id);

/**
 * Parse a packet.
 *
 * @param s             parser context.
 * @param avctx         codec context.
 * @param poutbuf       set to pointer to parsed buffer or NULL if not yet finished.
 * @param poutbuf_size  set to size of parsed buffer or zero if not yet finished.
 * @param buf           input buffer.
 * @param buf_size      input length, to signal EOF, this should be 0 (so that the last frame can be output).
 * @param pts           input presentation timestamp.
 * @param dts           input decoding timestamp.
 * @param pos           input byte position in stream.
 * @return the number of bytes of the input bitstream used.
 *
 * Example:
 * @code
 *   while(in_len){
 *       len = av_parser_parse2(myparser, AVCodecContext, &data, &size,
 *                                        in_data, in_len,
 *                                        pts, dts, pos);
 *       in_data += len;
 *       in_len  -= len;
 *
 *       if(size)
 *          decode_frame(data, size);
 *   }
 * @endcode
 */
int av_parser_parse2(AVCodecParserContext *s,
                     AVCodecContext *avctx,
                     uint8_t **poutbuf, int *poutbuf_size,
                     const uint8_t *buf, int buf_size,
                     int64_t pts, int64_t dts,
                     int64_t pos);

4092 4093
/**
 * @return 0 if the output buffer is a subset of the input, 1 if it is allocated and must be freed
Paul B Mahol's avatar
Paul B Mahol committed
4094
 * @deprecated use AVBitStreamFilter
4095
 */
4096 4097 4098 4099 4100 4101 4102 4103 4104 4105 4106
int av_parser_change(AVCodecParserContext *s,
                     AVCodecContext *avctx,
                     uint8_t **poutbuf, int *poutbuf_size,
                     const uint8_t *buf, int buf_size, int keyframe);
void av_parser_close(AVCodecParserContext *s);

/**
 * @}
 * @}
 */

4107 4108 4109 4110 4111 4112 4113 4114
/**
 * @addtogroup lavc_encoding
 * @{
 */

/**
 * Find a registered encoder with a matching codec ID.
 *
4115
 * @param id AVCodecID of the requested encoder
4116 4117
 * @return An encoder if one was found, NULL otherwise.
 */
4118
AVCodec *avcodec_find_encoder(enum AVCodecID id);
4119 4120 4121 4122 4123 4124 4125 4126 4127 4128 4129 4130 4131 4132 4133 4134 4135 4136 4137 4138 4139 4140 4141 4142

/**
 * Find a registered encoder with the specified name.
 *
 * @param name name of the requested encoder
 * @return An encoder if one was found, NULL otherwise.
 */
AVCodec *avcodec_find_encoder_by_name(const char *name);

#if FF_API_OLD_ENCODE_AUDIO
/**
 * Encode an audio frame from samples into buf.
 *
 * @deprecated Use avcodec_encode_audio2 instead.
 *
 * @note The output buffer should be at least FF_MIN_BUFFER_SIZE bytes large.
 * However, for codecs with avctx->frame_size equal to 0 (e.g. PCM) the user
 * will know how much space is needed because it depends on the value passed
 * in buf_size as described below. In that case a lower value can be used.
 *
 * @param avctx the codec context
 * @param[out] buf the output buffer
 * @param[in] buf_size the output buffer size
 * @param[in] samples the input buffer containing the samples
4143
 * The number of samples read from this buffer is frame_size*channels,
4144
 * both of which are defined in avctx.
4145 4146 4147 4148 4149
 * For codecs which have avctx->frame_size equal to 0 (e.g. PCM) the number of
 * samples read from samples is equal to:
 * buf_size * 8 / (avctx->channels * av_get_bits_per_sample(avctx->codec_id))
 * This also implies that av_get_bits_per_sample() must not return 0 for these
 * codecs.
Diego Biurrun's avatar
Diego Biurrun committed
4150
 * @return On error a negative value is returned, on success zero or the number
4151
 * of bytes used to encode the data read from the input buffer.
4152
 */
4153 4154 4155 4156 4157 4158 4159 4160 4161 4162 4163 4164 4165 4166 4167 4168 4169 4170
int attribute_deprecated avcodec_encode_audio(AVCodecContext *avctx,
                                              uint8_t *buf, int buf_size,
                                              const short *samples);
#endif

/**
 * Encode a frame of audio.
 *
 * Takes input samples from frame and writes the next output packet, if
 * available, to avpkt. The output packet does not necessarily contain data for
 * the most recent frame, as encoders can delay, split, and combine input frames
 * internally as needed.
 *
 * @param avctx     codec context
 * @param avpkt     output AVPacket.
 *                  The user can supply an output buffer by setting
 *                  avpkt->data and avpkt->size prior to calling the
 *                  function, but if the size of the user-provided data is not
4171 4172 4173 4174 4175 4176
 *                  large enough, encoding will fail. If avpkt->data and
 *                  avpkt->size are set, avpkt->destruct must also be set. All
 *                  other AVPacket fields will be reset by the encoder using
 *                  av_init_packet(). If avpkt->data is NULL, the encoder will
 *                  allocate it. The encoder will set avpkt->size to the size
 *                  of the output packet.
4177 4178 4179 4180
 *
 *                  If this function fails or produces no output, avpkt will be
 *                  freed using av_free_packet() (i.e. avpkt->destruct will be
 *                  called to free the user supplied buffer).
4181 4182 4183 4184 4185
 * @param[in] frame AVFrame containing the raw audio data to be encoded.
 *                  May be NULL when flushing an encoder that has the
 *                  CODEC_CAP_DELAY capability set.
 *                  If CODEC_CAP_VARIABLE_FRAME_SIZE is set, then each frame
 *                  can have any number of samples.
4186 4187 4188
 *                  If it is not set, frame->nb_samples must be equal to
 *                  avctx->frame_size for all frames except the last.
 *                  The final frame may be smaller than avctx->frame_size.
4189 4190 4191 4192 4193 4194 4195 4196 4197 4198
 * @param[out] got_packet_ptr This field is set to 1 by libavcodec if the
 *                            output packet is non-empty, and to 0 if it is
 *                            empty. If the function returns an error, the
 *                            packet can be assumed to be invalid, and the
 *                            value of got_packet_ptr is undefined and should
 *                            not be used.
 * @return          0 on success, negative error code on failure
 */
int avcodec_encode_audio2(AVCodecContext *avctx, AVPacket *avpkt,
                          const AVFrame *frame, int *got_packet_ptr);
4199

4200
#if FF_API_OLD_ENCODE_VIDEO
4201
/**
4202 4203
 * @deprecated use avcodec_encode_video2() instead.
 *
4204
 * Encode a video frame from pict into buf.
4205
 * The input picture should be
4206
 * stored using a specific format, namely avctx.pix_fmt.
4207
 *
Diego Biurrun's avatar
Diego Biurrun committed
4208 4209 4210 4211
 * @param avctx the codec context
 * @param[out] buf the output buffer for the bitstream of encoded frame
 * @param[in] buf_size the size of the output buffer in bytes
 * @param[in] pict the input picture to encode
4212
 * @return On error a negative value is returned, on success zero or the number
4213
 * of bytes used from the output buffer.
4214
 */
4215
attribute_deprecated
4216
int avcodec_encode_video(AVCodecContext *avctx, uint8_t *buf, int buf_size,
4217
                         const AVFrame *pict);
4218 4219 4220 4221 4222 4223 4224 4225 4226 4227 4228 4229 4230 4231 4232 4233 4234 4235 4236 4237 4238
#endif

/**
 * Encode a frame of video.
 *
 * Takes input raw video data from frame and writes the next output packet, if
 * available, to avpkt. The output packet does not necessarily contain data for
 * the most recent frame, as encoders can delay and reorder input frames
 * internally as needed.
 *
 * @param avctx     codec context
 * @param avpkt     output AVPacket.
 *                  The user can supply an output buffer by setting
 *                  avpkt->data and avpkt->size prior to calling the
 *                  function, but if the size of the user-provided data is not
 *                  large enough, encoding will fail. All other AVPacket fields
 *                  will be reset by the encoder using av_init_packet(). If
 *                  avpkt->data is NULL, the encoder will allocate it.
 *                  The encoder will set avpkt->size to the size of the
 *                  output packet. The returned data (if any) belongs to the
 *                  caller, he is responsible for freeing it.
4239 4240 4241 4242
 *
 *                  If this function fails or produces no output, avpkt will be
 *                  freed using av_free_packet() (i.e. avpkt->destruct will be
 *                  called to free the user supplied buffer).
4243 4244 4245 4246 4247 4248 4249 4250 4251 4252 4253 4254 4255 4256
 * @param[in] frame AVFrame containing the raw video data to be encoded.
 *                  May be NULL when flushing an encoder that has the
 *                  CODEC_CAP_DELAY capability set.
 * @param[out] got_packet_ptr This field is set to 1 by libavcodec if the
 *                            output packet is non-empty, and to 0 if it is
 *                            empty. If the function returns an error, the
 *                            packet can be assumed to be invalid, and the
 *                            value of got_packet_ptr is undefined and should
 *                            not be used.
 * @return          0 on success, negative error code on failure
 */
int avcodec_encode_video2(AVCodecContext *avctx, AVPacket *avpkt,
                          const AVFrame *frame, int *got_packet_ptr);

4257
int avcodec_encode_subtitle(AVCodecContext *avctx, uint8_t *buf, int buf_size,
4258
                            const AVSubtitle *sub);
Fabrice Bellard's avatar
Fabrice Bellard committed
4259

4260

4261
/**
4262 4263 4264
 * @}
 */

4265 4266 4267 4268 4269 4270 4271 4272 4273 4274 4275 4276 4277 4278 4279 4280 4281 4282 4283 4284 4285 4286 4287 4288 4289 4290 4291 4292 4293 4294 4295 4296 4297 4298 4299 4300 4301 4302 4303 4304 4305 4306 4307 4308 4309 4310 4311 4312 4313 4314 4315 4316 4317 4318 4319 4320 4321 4322 4323 4324 4325 4326 4327 4328 4329 4330 4331 4332 4333 4334 4335 4336 4337 4338 4339 4340 4341 4342 4343 4344 4345 4346 4347 4348 4349 4350 4351 4352 4353 4354 4355 4356 4357 4358 4359 4360 4361
#if FF_API_AVCODEC_RESAMPLE
/**
 * @defgroup lavc_resample Audio resampling
 * @ingroup libavc
 * @deprecated use libswresample instead
 *
 * @{
 */
struct ReSampleContext;
struct AVResampleContext;

typedef struct ReSampleContext ReSampleContext;

/**
 *  Initialize audio resampling context.
 *
 * @param output_channels  number of output channels
 * @param input_channels   number of input channels
 * @param output_rate      output sample rate
 * @param input_rate       input sample rate
 * @param sample_fmt_out   requested output sample format
 * @param sample_fmt_in    input sample format
 * @param filter_length    length of each FIR filter in the filterbank relative to the cutoff frequency
 * @param log2_phase_count log2 of the number of entries in the polyphase filterbank
 * @param linear           if 1 then the used FIR filter will be linearly interpolated
                           between the 2 closest, if 0 the closest will be used
 * @param cutoff           cutoff frequency, 1.0 corresponds to half the output sampling rate
 * @return allocated ReSampleContext, NULL if error occurred
 */
attribute_deprecated
ReSampleContext *av_audio_resample_init(int output_channels, int input_channels,
                                        int output_rate, int input_rate,
                                        enum AVSampleFormat sample_fmt_out,
                                        enum AVSampleFormat sample_fmt_in,
                                        int filter_length, int log2_phase_count,
                                        int linear, double cutoff);

attribute_deprecated
int audio_resample(ReSampleContext *s, short *output, short *input, int nb_samples);

/**
 * Free resample context.
 *
 * @param s a non-NULL pointer to a resample context previously
 *          created with av_audio_resample_init()
 */
attribute_deprecated
void audio_resample_close(ReSampleContext *s);


/**
 * Initialize an audio resampler.
 * Note, if either rate is not an integer then simply scale both rates up so they are.
 * @param filter_length length of each FIR filter in the filterbank relative to the cutoff freq
 * @param log2_phase_count log2 of the number of entries in the polyphase filterbank
 * @param linear If 1 then the used FIR filter will be linearly interpolated
                 between the 2 closest, if 0 the closest will be used
 * @param cutoff cutoff frequency, 1.0 corresponds to half the output sampling rate
 */
attribute_deprecated
struct AVResampleContext *av_resample_init(int out_rate, int in_rate, int filter_length, int log2_phase_count, int linear, double cutoff);

/**
 * Resample an array of samples using a previously configured context.
 * @param src an array of unconsumed samples
 * @param consumed the number of samples of src which have been consumed are returned here
 * @param src_size the number of unconsumed samples available
 * @param dst_size the amount of space in samples available in dst
 * @param update_ctx If this is 0 then the context will not be modified, that way several channels can be resampled with the same context.
 * @return the number of samples written in dst or -1 if an error occurred
 */
attribute_deprecated
int av_resample(struct AVResampleContext *c, short *dst, short *src, int *consumed, int src_size, int dst_size, int update_ctx);


/**
 * Compensate samplerate/timestamp drift. The compensation is done by changing
 * the resampler parameters, so no audible clicks or similar distortions occur
 * @param compensation_distance distance in output samples over which the compensation should be performed
 * @param sample_delta number of output samples which should be output less
 *
 * example: av_resample_compensate(c, 10, 500)
 * here instead of 510 samples only 500 samples would be output
 *
 * note, due to rounding the actual compensation might be slightly different,
 * especially if the compensation_distance is large and the in_rate used during init is small
 */
attribute_deprecated
void av_resample_compensate(struct AVResampleContext *c, int sample_delta, int compensation_distance);
attribute_deprecated
void av_resample_close(struct AVResampleContext *c);

/**
 * @}
 */
#endif

4362 4363 4364 4365 4366
/**
 * @addtogroup lavc_picture
 * @{
 */

4367
/**
4368 4369 4370 4371
 * Allocate memory for the pixels of a picture and setup the AVPicture
 * fields for it.
 *
 * Call avpicture_free() to free it.
4372
 *
4373 4374 4375 4376 4377
 * @param picture            the picture structure to be filled in
 * @param pix_fmt            the pixel format of the picture
 * @param width              the width of the picture
 * @param height             the height of the picture
 * @return zero if successful, a negative error code otherwise
4378
 *
4379
 * @see av_image_alloc(), avpicture_fill()
4380
 */
4381
int avpicture_alloc(AVPicture *picture, enum AVPixelFormat pix_fmt, int width, int height);
4382 4383 4384 4385 4386 4387 4388 4389 4390 4391 4392

/**
 * Free a picture previously allocated by avpicture_alloc().
 * The data buffer used by the AVPicture is freed, but the AVPicture structure
 * itself is not.
 *
 * @param picture the AVPicture to be freed
 */
void avpicture_free(AVPicture *picture);

/**
4393 4394 4395 4396 4397 4398 4399 4400 4401 4402 4403 4404 4405 4406 4407 4408 4409 4410 4411
 * Setup the picture fields based on the specified image parameters
 * and the provided image data buffer.
 *
 * The picture fields are filled in by using the image data buffer
 * pointed to by ptr.
 *
 * If ptr is NULL, the function will fill only the picture linesize
 * array and return the required size for the image buffer.
 *
 * To allocate an image buffer and fill the picture data in one call,
 * use avpicture_alloc().
 *
 * @param picture       the picture to be filled in
 * @param ptr           buffer where the image data is stored, or NULL
 * @param pix_fmt       the pixel format of the image
 * @param width         the width of the image in pixels
 * @param height        the height of the image in pixels
 * @return the size in bytes required for src, a negative error code
 * in case of failure
4412
 *
4413
 * @see av_image_fill_arrays()
4414
 */
4415
int avpicture_fill(AVPicture *picture, const uint8_t *ptr,
4416
                   enum AVPixelFormat pix_fmt, int width, int height);
4417 4418

/**
4419 4420 4421 4422 4423 4424 4425 4426 4427 4428 4429 4430 4431 4432
 * Copy pixel data from an AVPicture into a buffer.
 *
 * avpicture_get_size() can be used to compute the required size for
 * the buffer to fill.
 *
 * @param src        source picture with filled data
 * @param pix_fmt    picture pixel format
 * @param width      picture width
 * @param height     picture height
 * @param dest       destination buffer
 * @param dest_size  destination buffer size in bytes
 * @return the number of bytes written to dest, or a negative value
 * (error code) on error, for example if the destination buffer is not
 * big enough
4433
 *
4434
 * @see av_image_copy_to_buffer()
4435
 */
4436
int avpicture_layout(const AVPicture *src, enum AVPixelFormat pix_fmt,
4437
                     int width, int height,
4438 4439 4440 4441 4442
                     unsigned char *dest, int dest_size);

/**
 * Calculate the size in bytes that a picture of the given width and height
 * would occupy if stored in the given picture format.
4443 4444 4445 4446 4447 4448
 *
 * @param pix_fmt    picture pixel format
 * @param width      picture width
 * @param height     picture height
 * @return the computed picture buffer size or a negative error code
 * in case of error
4449
 *
4450
 * @see av_image_get_buffer_size().
4451
 */
4452
int avpicture_get_size(enum AVPixelFormat pix_fmt, int width, int height);
4453

4454
#if FF_API_DEINTERLACE
4455 4456
/**
 *  deinterlace - if not supported return -1
4457
 *
4458
 * @deprecated - use yadif (in libavfilter) instead
4459
 */
4460
attribute_deprecated
4461
int avpicture_deinterlace(AVPicture *dst, const AVPicture *src,
4462
                          enum AVPixelFormat pix_fmt, int width, int height);
4463
#endif
4464
/**
4465
 * Copy image src to dst. Wraps av_image_copy().
4466 4467
 */
void av_picture_copy(AVPicture *dst, const AVPicture *src,
4468
                     enum AVPixelFormat pix_fmt, int width, int height);
4469 4470 4471 4472 4473

/**
 * Crop image top and left side.
 */
int av_picture_crop(AVPicture *dst, const AVPicture *src,
4474
                    enum AVPixelFormat pix_fmt, int top_band, int left_band);
4475 4476 4477 4478

/**
 * Pad image.
 */
4479
int av_picture_pad(AVPicture *dst, const AVPicture *src, int height, int width, enum AVPixelFormat pix_fmt,
4480 4481 4482 4483 4484 4485
            int padtop, int padbottom, int padleft, int padright, int *color);

/**
 * @}
 */

4486 4487 4488 4489 4490 4491 4492 4493
/**
 * @defgroup lavc_misc Utility functions
 * @ingroup libavc
 *
 * Miscellaneous utility functions related to both encoding and decoding
 * (or neither).
 * @{
 */
4494

4495 4496 4497 4498 4499 4500 4501
/**
 * @defgroup lavc_misc_pixfmt Pixel formats
 *
 * Functions for working with pixel formats.
 * @{
 */

4502
/**
4503 4504 4505 4506 4507 4508 4509 4510
 * Utility function to access log2_chroma_w log2_chroma_h from
 * the pixel format AVPixFmtDescriptor.
 *
 * This function asserts that pix_fmt is valid. See av_pix_fmt_get_chroma_sub_sample
 * for one that returns a failure code and continues in case of invalid
 * pix_fmts.
 *
 * @param[in]  pix_fmt the pixel format
4511 4512
 * @param[out] h_shift store log2_chroma_w
 * @param[out] v_shift store log2_chroma_h
4513 4514
 *
 * @see av_pix_fmt_get_chroma_sub_sample
4515 4516
 */

4517
void avcodec_get_chroma_sub_sample(enum AVPixelFormat pix_fmt, int *h_shift, int *v_shift);
4518 4519 4520 4521 4522 4523

/**
 * Return a value representing the fourCC code associated to the
 * pixel format pix_fmt, or 0 if no associated fourCC code can be
 * found.
 */
4524
unsigned int avcodec_pix_fmt_to_codec_tag(enum AVPixelFormat pix_fmt);
4525

4526 4527 4528 4529 4530 4531
#define FF_LOSS_RESOLUTION  0x0001 /**< loss due to resolution change */
#define FF_LOSS_DEPTH       0x0002 /**< loss due to color depth change */
#define FF_LOSS_COLORSPACE  0x0004 /**< loss due to color space conversion */
#define FF_LOSS_ALPHA       0x0008 /**< loss of alpha bits */
#define FF_LOSS_COLORQUANT  0x0010 /**< loss due to color quantization */
#define FF_LOSS_CHROMA      0x0020 /**< loss of chroma (e.g. RGB to gray conversion) */
4532

4533
/**
4534
 * Compute what kind of losses will occur when converting from one specific
4535 4536 4537 4538 4539 4540 4541
 * pixel format to another.
 * When converting from one pixel format to another, information loss may occur.
 * For example, when converting from RGB24 to GRAY, the color information will
 * be lost. Similarly, other losses occur when converting from some formats to
 * other formats. These losses can involve loss of chroma, but also loss of
 * resolution, loss of color depth, loss due to the color space conversion, loss
 * of the alpha bits or loss due to color quantization.
Diego Biurrun's avatar
Diego Biurrun committed
4542 4543
 * avcodec_get_fix_fmt_loss() informs you about the various types of losses
 * which will occur when converting from one pixel format to another.
4544
 *
Diego Biurrun's avatar
Diego Biurrun committed
4545 4546
 * @param[in] dst_pix_fmt destination pixel format
 * @param[in] src_pix_fmt source pixel format
4547
 * @param[in] has_alpha Whether the source pixel format alpha channel is used.
4548 4549
 * @return Combination of flags informing you what kind of losses will occur
 * (maximum loss for an invalid dst_pix_fmt).
4550
 */
4551
int avcodec_get_pix_fmt_loss(enum AVPixelFormat dst_pix_fmt, enum AVPixelFormat src_pix_fmt,
4552
                             int has_alpha);
4553

4554 4555 4556 4557 4558
/**
 * Find the best pixel format to convert to given a certain source pixel
 * format.  When converting from one pixel format to another, information loss
 * may occur.  For example, when converting from RGB24 to GRAY, the color
 * information will be lost. Similarly, other losses occur when converting from
4559
 * some formats to other formats. avcodec_find_best_pix_fmt_of_2() searches which of
4560 4561 4562 4563 4564
 * the given pixel formats should be used to suffer the least amount of loss.
 * The pixel formats from which it chooses one, are determined by the
 * pix_fmt_list parameter.
 *
 *
4565
 * @param[in] pix_fmt_list AV_PIX_FMT_NONE terminated array of pixel formats to choose from
4566 4567 4568 4569 4570
 * @param[in] src_pix_fmt source pixel format
 * @param[in] has_alpha Whether the source pixel format alpha channel is used.
 * @param[out] loss_ptr Combination of flags informing you what kind of losses will occur.
 * @return The best pixel format to convert to or -1 if none was found.
 */
4571 4572
enum AVPixelFormat avcodec_find_best_pix_fmt_of_list(enum AVPixelFormat *pix_fmt_list,
                                            enum AVPixelFormat src_pix_fmt,
4573
                                            int has_alpha, int *loss_ptr);
4574

4575 4576 4577 4578 4579
/**
 * Find the best pixel format to convert to given a certain source pixel
 * format and a selection of two destination pixel formats. When converting from
 * one pixel format to another, information loss may occur.  For example, when converting
 * from RGB24 to GRAY, the color information will be lost. Similarly, other losses occur when
4580
 * converting from some formats to other formats. avcodec_find_best_pix_fmt_of_2() selects which of
4581 4582
 * the given pixel formats should be used to suffer the least amount of loss.
 *
4583
 * If one of the destination formats is AV_PIX_FMT_NONE the other pixel format (if valid) will be
4584 4585 4586
 * returned.
 *
 * @code
4587 4588 4589 4590
 * src_pix_fmt = AV_PIX_FMT_YUV420P;
 * dst_pix_fmt1= AV_PIX_FMT_RGB24;
 * dst_pix_fmt2= AV_PIX_FMT_GRAY8;
 * dst_pix_fmt3= AV_PIX_FMT_RGB8;
4591
 * loss= FF_LOSS_CHROMA; // don't care about chroma loss, so chroma loss will be ignored.
4592 4593
 * dst_pix_fmt = avcodec_find_best_pix_fmt_of_2(dst_pix_fmt1, dst_pix_fmt2, src_pix_fmt, alpha, &loss);
 * dst_pix_fmt = avcodec_find_best_pix_fmt_of_2(dst_pix_fmt, dst_pix_fmt3, src_pix_fmt, alpha, &loss);
4594 4595 4596 4597 4598 4599 4600 4601 4602 4603 4604
 * @endcode
 *
 * @param[in] dst_pix_fmt1 One of the two destination pixel formats to choose from
 * @param[in] dst_pix_fmt2 The other of the two destination pixel formats to choose from
 * @param[in] src_pix_fmt Source pixel format
 * @param[in] has_alpha Whether the source pixel format alpha channel is used.
 * @param[in, out] loss_ptr Combination of loss flags. In: selects which of the losses to ignore, i.e.
 *                               NULL or value of zero means we care about all losses. Out: the loss
 *                               that occurs when converting from src to selected dst pixel format.
 * @return The best pixel format to convert to or -1 if none was found.
 */
4605 4606
enum AVPixelFormat avcodec_find_best_pix_fmt_of_2(enum AVPixelFormat dst_pix_fmt1, enum AVPixelFormat dst_pix_fmt2,
                                            enum AVPixelFormat src_pix_fmt, int has_alpha, int *loss_ptr);
4607 4608

attribute_deprecated
4609
#if AV_HAVE_INCOMPATIBLE_LIBAV_ABI
4610 4611 4612
enum AVPixelFormat avcodec_find_best_pix_fmt2(enum AVPixelFormat *pix_fmt_list,
                                              enum AVPixelFormat src_pix_fmt,
                                              int has_alpha, int *loss_ptr);
4613
#else
4614 4615
enum AVPixelFormat avcodec_find_best_pix_fmt2(enum AVPixelFormat dst_pix_fmt1, enum AVPixelFormat dst_pix_fmt2,
                                            enum AVPixelFormat src_pix_fmt, int has_alpha, int *loss_ptr);
4616 4617
#endif

4618

4619
enum AVPixelFormat avcodec_default_get_format(struct AVCodecContext *s, const enum AVPixelFormat * fmt);
4620 4621 4622 4623 4624 4625 4626 4627 4628 4629 4630 4631 4632 4633 4634

/**
 * @}
 */

void avcodec_set_dimensions(AVCodecContext *s, int width, int height);

/**
 * Put a string representing the codec tag codec_tag in buf.
 *
 * @param buf_size size in bytes of buf
 * @return the length of the string that would have been generated if
 * enough space had been available, excluding the trailing null
 */
size_t av_get_codec_tag_string(char *buf, size_t buf_size, unsigned int codec_tag);
4635 4636

void avcodec_string(char *buf, int buf_size, AVCodecContext *enc, int encode);
4637

4638
/**
4639
 * Return a name for the specified profile, if available.
4640
 *
4641 4642 4643
 * @param codec the codec that is searched for the given profile
 * @param profile the profile value for which a name is requested
 * @return A name for the profile if found, NULL otherwise.
4644
 */
4645 4646 4647 4648 4649
const char *av_get_profile_name(const AVCodec *codec, int profile);

int avcodec_default_execute(AVCodecContext *c, int (*func)(AVCodecContext *c2, void *arg2),void *arg, int *ret, int count, int size);
int avcodec_default_execute2(AVCodecContext *c, int (*func)(AVCodecContext *c2, void *arg2, int, int),void *arg, int *ret, int count);
//FIXME func typedef
4650

4651
/**
4652 4653 4654 4655 4656 4657
 * Fill AVFrame audio data and linesize pointers.
 *
 * The buffer buf must be a preallocated buffer with a size big enough
 * to contain the specified samples amount. The filled AVFrame data
 * pointers will point to this buffer.
 *
4658 4659
 * AVFrame extended_data channel pointers are allocated if necessary for
 * planar audio.
4660
 *
4661 4662 4663 4664 4665 4666 4667 4668
 * @param frame       the AVFrame
 *                    frame->nb_samples must be set prior to calling the
 *                    function. This function fills in frame->data,
 *                    frame->extended_data, frame->linesize[0].
 * @param nb_channels channel count
 * @param sample_fmt  sample format
 * @param buf         buffer to use for frame data
 * @param buf_size    size of buffer
4669
 * @param align       plane size sample alignment (0 = default)
4670
 * @return            >=0 on success, negative error code on failure
4671 4672
 * @todo return the size in bytes required to store the samples in
 * case of success, at the next libavutil bump
4673
 */
4674 4675 4676
int avcodec_fill_audio_frame(AVFrame *frame, int nb_channels,
                             enum AVSampleFormat sample_fmt, const uint8_t *buf,
                             int buf_size, int align);
Fabrice Bellard's avatar
Fabrice Bellard committed
4677

4678 4679 4680
/**
 * Flush buffers, should be called when seeking or when switching to a different stream.
 */
4681 4682
void avcodec_flush_buffers(AVCodecContext *avctx);

4683
/**
4684
 * Return codec bits per sample.
4685
 *
Diego Biurrun's avatar
Diego Biurrun committed
4686
 * @param[in] codec_id the codec
4687
 * @return Number of bits per sample or zero if unknown for the given codec.
4688
 */
4689
int av_get_bits_per_sample(enum AVCodecID codec_id);
4690

4691 4692 4693 4694
/**
 * Return the PCM codec associated with a sample format.
 * @param be  endianness, 0 for little, 1 for big,
 *            -1 (or anything else) for native
4695
 * @return  AV_CODEC_ID_PCM_* or AV_CODEC_ID_NONE
4696
 */
4697
enum AVCodecID av_get_pcm_codec(enum AVSampleFormat fmt, int be);
4698

4699 4700 4701 4702 4703 4704 4705 4706
/**
 * Return codec bits per sample.
 * Only return non-zero if the bits per sample is exactly correct, not an
 * approximation.
 *
 * @param[in] codec_id the codec
 * @return Number of bits per sample or zero if unknown for the given codec.
 */
4707
int av_get_exact_bits_per_sample(enum AVCodecID codec_id);
4708

4709 4710 4711 4712 4713 4714 4715 4716 4717 4718
/**
 * Return audio frame duration.
 *
 * @param avctx        codec context
 * @param frame_bytes  size of the frame, or 0 if unknown
 * @return             frame duration, in samples, if known. 0 if not able to
 *                     determine.
 */
int av_get_audio_frame_duration(AVCodecContext *avctx, int frame_bytes);

4719 4720

typedef struct AVBitStreamFilterContext {
4721
    void *priv_data;
4722 4723 4724 4725 4726 4727 4728 4729
    struct AVBitStreamFilter *filter;
    AVCodecParserContext *parser;
    struct AVBitStreamFilterContext *next;
} AVBitStreamFilterContext;


typedef struct AVBitStreamFilter {
    const char *name;
4730
    int priv_data_size;
4731 4732 4733 4734
    int (*filter)(AVBitStreamFilterContext *bsfc,
                  AVCodecContext *avctx, const char *args,
                  uint8_t **poutbuf, int *poutbuf_size,
                  const uint8_t *buf, int buf_size, int keyframe);
4735
    void (*close)(AVBitStreamFilterContext *bsfc);
4736 4737 4738
    struct AVBitStreamFilter *next;
} AVBitStreamFilter;

4739 4740 4741 4742 4743 4744 4745 4746 4747
/**
 * Register a bitstream filter.
 *
 * The filter will be accessible to the application code through
 * av_bitstream_filter_next() or can be directly initialized with
 * av_bitstream_filter_init().
 *
 * @see avcodec_register_all()
 */
4748
void av_register_bitstream_filter(AVBitStreamFilter *bsf);
4749 4750 4751 4752 4753 4754 4755 4756 4757 4758 4759

/**
 * Create and initialize a bitstream filter context given a bitstream
 * filter name.
 *
 * The returned context must be freed with av_bitstream_filter_close().
 *
 * @param name    the name of the bitstream filter
 * @return a bitstream filter context if a matching filter was found
 * and successfully initialized, NULL otherwise
 */
4760
AVBitStreamFilterContext *av_bitstream_filter_init(const char *name);
4761 4762 4763 4764 4765 4766 4767 4768 4769 4770 4771 4772 4773 4774 4775 4776 4777 4778 4779 4780 4781 4782 4783 4784

/**
 * Filter bitstream.
 *
 * This function filters the buffer buf with size buf_size, and places the
 * filtered buffer in the buffer pointed to by poutbuf.
 *
 * The output buffer must be freed by the caller.
 *
 * @param bsfc            bitstream filter context created by av_bitstream_filter_init()
 * @param avctx           AVCodecContext accessed by the filter, may be NULL.
 *                        If specified, this must point to the encoder context of the
 *                        output stream the packet is sent to.
 * @param args            arguments which specify the filter configuration, may be NULL
 * @param poutbuf         pointer which is updated to point to the filtered buffer
 * @param poutbuf_size    pointer which is updated to the filtered buffer size in bytes
 * @param buf             buffer containing the data to filter
 * @param buf_size        size in bytes of buf
 * @param keyframe        set to non-zero if the buffer to filter corresponds to a key-frame packet data
 * @return >= 0 in case of success, or a negative error code in case of failure
 *
 * If the return value is positive, an output buffer is allocated and
 * is availble in *poutbuf, and is distinct from the input buffer.
 *
4785 4786 4787 4788
 * If the return value is 0, the output buffer is not allocated and
 * should be considered identical to the input buffer, or in case
 * *poutbuf was set it points to the input buffer (not necessarily to
 * its starting address).
4789
 */
4790 4791 4792 4793
int av_bitstream_filter_filter(AVBitStreamFilterContext *bsfc,
                               AVCodecContext *avctx, const char *args,
                               uint8_t **poutbuf, int *poutbuf_size,
                               const uint8_t *buf, int buf_size, int keyframe);
4794 4795 4796 4797 4798 4799 4800

/**
 * Release bitstream filter context.
 *
 * @param bsf the bitstream filter context created with
 * av_bitstream_filter_init(), can be NULL
 */
4801 4802
void av_bitstream_filter_close(AVBitStreamFilterContext *bsf);

4803 4804 4805 4806 4807 4808 4809 4810
/**
 * If f is NULL, return the first registered bitstream filter,
 * if f is non-NULL, return the next registered bitstream filter
 * after f, or NULL if f is the last one.
 *
 * This function can be used to iterate over all registered bitstream
 * filters.
 */
4811
AVBitStreamFilter *av_bitstream_filter_next(AVBitStreamFilter *f);
4812

4813
/* memory */
4814 4815

/**
4816
 * Reallocate the given block if it is not large enough, otherwise do nothing.
4817 4818
 *
 * @see av_realloc
4819
 */
4820
void *av_fast_realloc(void *ptr, unsigned int *size, size_t min_size);
4821

4822
/**
4823
 * Allocate a buffer, reusing the given one if large enough.
4824 4825 4826 4827 4828 4829 4830 4831 4832 4833
 *
 * Contrary to av_fast_realloc the current buffer contents might not be
 * preserved and on error the old buffer is freed, thus no special
 * handling to avoid memleaks is necessary.
 *
 * @param ptr pointer to pointer to already allocated buffer, overwritten with pointer to new buffer
 * @param size size of the buffer *ptr points to
 * @param min_size minimum size of *ptr buffer after returning, *ptr will be NULL and
 *                 *size 0 if an error occurred.
 */
4834
void av_fast_malloc(void *ptr, unsigned int *size, size_t min_size);
4835

4836 4837
/**
 * Same behaviour av_fast_malloc but the buffer has additional
4838
 * FF_INPUT_BUFFER_PADDING_SIZE at the end which will always be 0.
4839 4840 4841 4842 4843 4844
 *
 * In addition the whole buffer will initially and after resizes
 * be 0-initialized so that no uninitialized data will ever appear.
 */
void av_fast_padded_malloc(void *ptr, unsigned int *size, size_t min_size);

4845 4846 4847 4848 4849 4850
/**
 * Same behaviour av_fast_padded_malloc except that buffer will always
 * be 0-initialized after call.
 */
void av_fast_padded_mallocz(void *ptr, unsigned int *size, size_t min_size);

4851
/**
4852
 * Encode extradata length to a buffer. Used by xiph codecs.
4853 4854 4855 4856 4857
 *
 * @param s buffer to write to; must be at least (v/255+1) bytes long
 * @param v size of extradata in bytes
 * @return number of bytes written to the buffer.
 */
4858
unsigned int av_xiphlacing(unsigned char *s, unsigned int v);
4859

4860
#if FF_API_MISSING_SAMPLE
4861
/**
4862
 * Log a generic warning message about a missing feature. This function is
4863
 * intended to be used internally by FFmpeg (libavcodec, libavformat, etc.)
4864
 * only, and would normally not be used by applications.
4865 4866 4867 4868 4869 4870 4871
 * @param[in] avc a pointer to an arbitrary struct of which the first field is
 * a pointer to an AVClass struct
 * @param[in] feature string containing the name of the missing feature
 * @param[in] want_sample indicates if samples are wanted which exhibit this feature.
 * If want_sample is non-zero, additional verbage will be added to the log
 * message which tells the user how to report samples to the development
 * mailing list.
4872
 * @deprecated Use avpriv_report_missing_feature() instead.
4873
 */
4874
attribute_deprecated
4875 4876 4877
void av_log_missing_feature(void *avc, const char *feature, int want_sample);

/**
4878
 * Log a generic warning message asking for a sample. This function is
4879 4880
 * intended to be used internally by FFmpeg (libavcodec, libavformat, etc.)
 * only, and would normally not be used by applications.
4881 4882 4883
 * @param[in] avc a pointer to an arbitrary struct of which the first field is
 * a pointer to an AVClass struct
 * @param[in] msg string containing an optional message, or NULL if no message
4884
 * @deprecated Use avpriv_request_sample() instead.
4885
 */
4886
attribute_deprecated
4887
void av_log_ask_for_sample(void *avc, const char *msg, ...) av_printf_format(2, 3);
4888
#endif /* FF_API_MISSING_SAMPLE */
4889

4890
/**
4891
 * Register the hardware accelerator hwaccel.
4892 4893 4894 4895 4896 4897 4898 4899 4900 4901
 */
void av_register_hwaccel(AVHWAccel *hwaccel);

/**
 * If hwaccel is NULL, returns the first registered hardware accelerator,
 * if hwaccel is non-NULL, returns the next registered hardware accelerator
 * after hwaccel, or NULL if hwaccel is the last one.
 */
AVHWAccel *av_hwaccel_next(AVHWAccel *hwaccel);

4902 4903 4904 4905 4906 4907 4908 4909 4910 4911 4912 4913 4914

/**
 * Lock operation used by lockmgr
 */
enum AVLockOp {
  AV_LOCK_CREATE,  ///< Create a mutex
  AV_LOCK_OBTAIN,  ///< Lock the mutex
  AV_LOCK_RELEASE, ///< Unlock the mutex
  AV_LOCK_DESTROY, ///< Free mutex resources
};

/**
 * Register a user provided lock manager supporting the operations
4915
 * specified by AVLockOp. mutex points to a (void *) where the
4916 4917 4918 4919 4920 4921 4922 4923 4924 4925 4926 4927
 * lockmgr should store/get a pointer to a user allocated mutex. It's
 * NULL upon AV_LOCK_CREATE and != NULL for all other ops.
 *
 * @param cb User defined callback. Note: FFmpeg may invoke calls to this
 *           callback during the call to av_lockmgr_register().
 *           Thus, the application must be prepared to handle that.
 *           If cb is set to NULL the lockmgr will be unregistered.
 *           Also note that during unregistration the previously registered
 *           lockmgr callback may also be invoked.
 */
int av_lockmgr_register(int (*cb)(void **mutex, enum AVLockOp op));

4928 4929 4930
/**
 * Get the type of the given codec.
 */
4931
enum AVMediaType avcodec_get_type(enum AVCodecID codec_id);
4932

4933
/**
4934 4935
 * Get the name of a codec.
 * @return  a static string identifying the codec; never NULL
4936
 */
4937
const char *avcodec_get_name(enum AVCodecID id);
4938

4939 4940 4941 4942 4943 4944
/**
 * @return a positive value if s is open (i.e. avcodec_open2() was called on it
 * with no corresponding avcodec_close()), 0 otherwise.
 */
int avcodec_is_open(AVCodecContext *s);

4945 4946 4947
/**
 * @return a non-zero number if codec is an encoder, zero otherwise
 */
4948
int av_codec_is_encoder(const AVCodec *codec);
4949 4950 4951 4952

/**
 * @return a non-zero number if codec is a decoder, zero otherwise
 */
4953
int av_codec_is_decoder(const AVCodec *codec);
4954

4955 4956 4957 4958 4959 4960 4961 4962 4963 4964 4965 4966 4967 4968
/**
 * @return descriptor for given codec ID or NULL if no descriptor exists.
 */
const AVCodecDescriptor *avcodec_descriptor_get(enum AVCodecID id);

/**
 * Iterate over all codec descriptors known to libavcodec.
 *
 * @param prev previous descriptor. NULL to get the first descriptor.
 *
 * @return next descriptor or NULL after the last descriptor
 */
const AVCodecDescriptor *avcodec_descriptor_next(const AVCodecDescriptor *prev);

4969 4970 4971 4972 4973 4974
/**
 * @return codec descriptor with the given name or NULL if no such descriptor
 *         exists.
 */
const AVCodecDescriptor *avcodec_descriptor_get_by_name(const char *name);

4975 4976 4977 4978
/**
 * @}
 */

4979
#endif /* AVCODEC_AVCODEC_H */