Revision f5bccd85

View differences:

libavcodec/avcodec.h
23 23

  
24 24
/**
25 25
 * @file avcodec.h
26
 * external api header.
26
 * external API header
27 27
 */
28 28

  
29 29

  
......
49 49

  
50 50
/**
51 51
 *
52
 * if you add a codec id to this list add it so that
53
 * 1. no value of a existing codec id changes (that would break ABI)
54
 * 2. closest to similar codecs
52
 * If you add a codec ID to this list, add it so that
53
 * 1. no value of a existing codec ID changes (that would break ABI),
54
 * 2. it is as close as possible to similar codecs.
55 55
 */
56 56
enum CodecID {
57 57
    CODEC_ID_NONE,
58 58
    CODEC_ID_MPEG1VIDEO,
59
    CODEC_ID_MPEG2VIDEO, /* prefered ID for MPEG Video 1 or 2 decoding */
59
    CODEC_ID_MPEG2VIDEO, /* preferred ID for MPEG-1/2 video decoding */
60 60
    CODEC_ID_MPEG2VIDEO_XVMC,
61 61
    CODEC_ID_H261,
62 62
    CODEC_ID_H263,
......
161 161
    CODEC_ID_THP,
162 162
    CODEC_ID_SGI,
163 163

  
164
    /* various pcm "codecs" */
164
    /* various PCM "codecs" */
165 165
    CODEC_ID_PCM_S16LE= 0x10000,
166 166
    CODEC_ID_PCM_S16BE,
167 167
    CODEC_ID_PCM_U16LE,
......
180 180
    CODEC_ID_PCM_U24BE,
181 181
    CODEC_ID_PCM_S24DAUD,
182 182

  
183
    /* various adpcm codecs */
183
    /* various ADPCM codecs */
184 184
    CODEC_ID_ADPCM_IMA_QT= 0x11000,
185 185
    CODEC_ID_ADPCM_IMA_WAV,
186 186
    CODEC_ID_ADPCM_IMA_DK3,
......
215 215
    CODEC_ID_SOL_DPCM,
216 216

  
217 217
    CODEC_ID_MP2= 0x15000,
218
    CODEC_ID_MP3, /* prefered ID for MPEG Audio layer 1, 2 or3 decoding */
218
    CODEC_ID_MP3, /* preferred ID for decoding MPEG audio layer 1, 2 or 3 */
219 219
    CODEC_ID_AAC,
220 220
#if LIBAVCODEC_VERSION_INT < ((52<<16)+(0<<8)+0)
221 221
    CODEC_ID_MPEG4AAC,
......
237 237
    CODEC_ID_SHORTEN,
238 238
    CODEC_ID_ALAC,
239 239
    CODEC_ID_WESTWOOD_SND1,
240
    CODEC_ID_GSM, /* As in Berlin toast format */
240
    CODEC_ID_GSM, /* as in Berlin toast format */
241 241
    CODEC_ID_QDM2,
242 242
    CODEC_ID_COOK,
243 243
    CODEC_ID_TRUESPEECH,
......
249 249
    CODEC_ID_IMC,
250 250
    CODEC_ID_MUSEPACK7,
251 251
    CODEC_ID_MLP,
252
    CODEC_ID_GSM_MS, /* As found in WAV */
252
    CODEC_ID_GSM_MS, /* as found in WAV */
253 253

  
254 254
    /* subtitle codecs */
255 255
    CODEC_ID_DVD_SUBTITLE= 0x17000,
256 256
    CODEC_ID_DVB_SUBTITLE,
257 257

  
258
    CODEC_ID_MPEG2TS= 0x20000, /* _FAKE_ codec to indicate a raw MPEG2 transport
259
                         stream (only used by libavformat) */
258
    CODEC_ID_MPEG2TS= 0x20000, /* _FAKE_ codec to indicate a raw MPEG-2 TS
259
                                * stream (only used by libavformat) */
260 260
};
261 261

  
262 262
#if LIBAVCODEC_VERSION_INT < ((52<<16)+(0<<8)+0)
263
/* CODEC_ID_MP3LAME is absolete */
263
/* CODEC_ID_MP3LAME is obsolete */
264 264
#define CODEC_ID_MP3LAME CODEC_ID_MP3
265 265
#define CODEC_ID_MPEG4AAC CODEC_ID_AAC
266 266
#endif
......
274 274
    CODEC_TYPE_NB
275 275
};
276 276

  
277
/* currently unused, may be used if 24/32 bits samples ever supported */
278
/* all in native endian */
277
/* Currently unused, may be used if 24/32 bits samples are ever supported. */
278
/* all in native-endian format */
279 279
enum SampleFormat {
280 280
    SAMPLE_FMT_NONE = -1,
281 281
    SAMPLE_FMT_U8,              ///< unsigned 8 bits
......
290 290

  
291 291
/**
292 292
 * Required number of additionally allocated bytes at the end of the input bitstream for decoding.
293
 * this is mainly needed because some optimized bitstream readers read
294
 * 32 or 64 bit at once and could read over the end<br>
295
 * Note, if the first 23 bits of the additional bytes are not 0 then damaged
296
 * MPEG bitstreams could cause overread and segfault
293
 * This is mainly needed because some optimized bitstream readers read
294
 * 32 or 64 bit at once and could read over the end.<br>
295
 * Note: If the first 23 bits of the additional bytes are not 0, then damaged
296
 * MPEG bitstreams could cause overread and segfault.
297 297
 */
298 298
#define FF_INPUT_BUFFER_PADDING_SIZE 8
299 299

  
300 300
/**
301
 * minimum encoding buffer size.
302
 * used to avoid some checks during header writing
301
 * minimum encoding buffer size
302
 * Used to avoid some checks during header writing.
303 303
 */
304 304
#define FF_MIN_BUFFER_SIZE 16384
305 305

  
......
317 317
};
318 318

  
319 319
enum AVDiscard{
320
//we leave some space between them for extensions (drop some keyframes for intra only or drop just some bidir frames)
320
    /* We leave some space between them for extensions (drop some
321
     * keyframes for intra-only or drop just some bidir frames). */
321 322
    AVDISCARD_NONE   =-16, ///< discard nothing
322 323
    AVDISCARD_DEFAULT=  0, ///< discard useless packets like 0 size packets in avi
323 324
    AVDISCARD_NONREF =  8, ///< discard all non reference
......
329 330
typedef struct RcOverride{
330 331
    int start_frame;
331 332
    int end_frame;
332
    int qscale; // if this is 0 then quality_factor will be used instead
333
    int qscale; // If this is 0 then quality_factor will be used instead.
333 334
    float quality_factor;
334 335
} RcOverride;
335 336

  
336 337
#define FF_MAX_B_FRAMES 16
337 338

  
338 339
/* encoding support
339
   these flags can be passed in AVCodecContext.flags before initing
340
   Note: not everything is supported yet.
340
   These flags can be passed in AVCodecContext.flags before initialization.
341
   Note: Not everything is supported yet.
341 342
*/
342 343

  
343
#define CODEC_FLAG_QSCALE 0x0002  ///< use fixed qscale
344
#define CODEC_FLAG_4MV    0x0004  ///< 4 MV per MB allowed / Advanced prediction for H263
345
#define CODEC_FLAG_QPEL   0x0010  ///< use qpel MC
346
#define CODEC_FLAG_GMC    0x0020  ///< use GMC
347
#define CODEC_FLAG_MV0    0x0040  ///< always try a MB with MV=<0,0>
348
#define CODEC_FLAG_PART   0x0080  ///< use data partitioning
349
/* parent program guarantees that the input for b-frame containing streams is not written to
350
   for at least s->max_b_frames+1 frames, if this is not set than the input will be copied */
344
#define CODEC_FLAG_QSCALE 0x0002  ///< Use fixed qscale.
345
#define CODEC_FLAG_4MV    0x0004  ///< 4 MV per MB allowed / advanced prediction for H.263.
346
#define CODEC_FLAG_QPEL   0x0010  ///< Use qpel MC.
347
#define CODEC_FLAG_GMC    0x0020  ///< Use GMC.
348
#define CODEC_FLAG_MV0    0x0040  ///< Always try a MB with MV=<0,0>.
349
#define CODEC_FLAG_PART   0x0080  ///< Use data partitioning.
350
/* The parent program guarantees that the input for B-frames containing
351
 * streams is not written to for at least s->max_b_frames+1 frames, if
352
 * this is not set the input will be copied. */
351 353
#define CODEC_FLAG_INPUT_PRESERVED 0x0100
352
#define CODEC_FLAG_PASS1 0x0200   ///< use internal 2pass ratecontrol in first  pass mode
353
#define CODEC_FLAG_PASS2 0x0400   ///< use internal 2pass ratecontrol in second pass mode
354
#define CODEC_FLAG_EXTERN_HUFF 0x1000 ///< use external huffman table (for mjpeg)
355
#define CODEC_FLAG_GRAY  0x2000   ///< only decode/encode grayscale
356
#define CODEC_FLAG_EMU_EDGE 0x4000///< don't draw edges
357
#define CODEC_FLAG_PSNR           0x8000 ///< error[?] variables will be set during encoding
358
#define CODEC_FLAG_TRUNCATED  0x00010000 /** input bitstream might be truncated at a random location instead
359
                                            of only at frame boundaries */
360
#define CODEC_FLAG_NORMALIZE_AQP  0x00020000 ///< normalize adaptive quantization
361
#define CODEC_FLAG_INTERLACED_DCT 0x00040000 ///< use interlaced dct
362
#define CODEC_FLAG_LOW_DELAY      0x00080000 ///< force low delay
363
#define CODEC_FLAG_ALT_SCAN       0x00100000 ///< use alternate scan
364
#define CODEC_FLAG_TRELLIS_QUANT  0x00200000 ///< use trellis quantization
365
#define CODEC_FLAG_GLOBAL_HEADER  0x00400000 ///< place global headers in extradata instead of every keyframe
366
#define CODEC_FLAG_BITEXACT       0x00800000 ///< use only bitexact stuff (except (i)dct)
354
#define CODEC_FLAG_PASS1 0x0200   ///< Use internal 2pass ratecontrol in first pass mode.
355
#define CODEC_FLAG_PASS2 0x0400   ///< Use internal 2pass ratecontrol in second pass mode.
356
#define CODEC_FLAG_EXTERN_HUFF 0x1000 ///< Use external Huffman table (for MJPEG).
357
#define CODEC_FLAG_GRAY  0x2000   ///< Only decode/encode grayscale.
358
#define CODEC_FLAG_EMU_EDGE 0x4000///< Don't draw edges.
359
#define CODEC_FLAG_PSNR           0x8000 ///< error[?] variables will be set during encoding.
360
#define CODEC_FLAG_TRUNCATED  0x00010000 /** Input bitstream might be truncated at a random location instead
361
                                            of only at frame boundaries. */
362
#define CODEC_FLAG_NORMALIZE_AQP  0x00020000 ///< Normalize adaptive quantization.
363
#define CODEC_FLAG_INTERLACED_DCT 0x00040000 ///< Use interlaced DCT.
364
#define CODEC_FLAG_LOW_DELAY      0x00080000 ///< Force low delay.
365
#define CODEC_FLAG_ALT_SCAN       0x00100000 ///< Use alternate scan.
366
#define CODEC_FLAG_TRELLIS_QUANT  0x00200000 ///< Use trellis quantization.
367
#define CODEC_FLAG_GLOBAL_HEADER  0x00400000 ///< Place global headers in extradata instead of every keyframe.
368
#define CODEC_FLAG_BITEXACT       0x00800000 ///< Use only bitexact stuff (except (I)DCT).
367 369
/* Fx : Flag for h263+ extra options */
368 370
#if LIBAVCODEC_VERSION_INT < ((52<<16)+(0<<8)+0)
369
#define CODEC_FLAG_H263P_AIC      0x01000000 ///< H263 Advanced intra coding / MPEG4 AC prediction (remove this)
371
#define CODEC_FLAG_H263P_AIC      0x01000000 ///< H.263 advanced intra coding / MPEG-4 AC prediction (remove this)
370 372
#endif
371
#define CODEC_FLAG_AC_PRED        0x01000000 ///< H263 Advanced intra coding / MPEG4 AC prediction
372
#define CODEC_FLAG_H263P_UMV      0x02000000 ///< Unlimited motion vector
373
#define CODEC_FLAG_CBP_RD         0x04000000 ///< use rate distortion optimization for cbp
374
#define CODEC_FLAG_QP_RD          0x08000000 ///< use rate distortion optimization for qp selectioon
375
#define CODEC_FLAG_H263P_AIV      0x00000008 ///< H263 Alternative inter vlc
373
#define CODEC_FLAG_AC_PRED        0x01000000 ///< H.263 advanced intra coding / MPEG-4 AC prediction
374
#define CODEC_FLAG_H263P_UMV      0x02000000 ///< unlimited motion vector
375
#define CODEC_FLAG_CBP_RD         0x04000000 ///< Use rate distortion optimization for cbp.
376
#define CODEC_FLAG_QP_RD          0x08000000 ///< Use rate distortion optimization for qp selectioon.
377
#define CODEC_FLAG_H263P_AIV      0x00000008 ///< H.263 alternative inter VLC
376 378
#define CODEC_FLAG_OBMC           0x00000001 ///< OBMC
377 379
#define CODEC_FLAG_LOOP_FILTER    0x00000800 ///< loop filter
378 380
#define CODEC_FLAG_H263P_SLICE_STRUCT 0x10000000
379 381
#define CODEC_FLAG_INTERLACED_ME  0x20000000 ///< interlaced motion estimation
380
#define CODEC_FLAG_SVCD_SCAN_OFFSET 0x40000000 ///< will reserve space for SVCD scan offset user data
382
#define CODEC_FLAG_SVCD_SCAN_OFFSET 0x40000000 ///< Will reserve space for SVCD scan offset user data.
381 383
#define CODEC_FLAG_CLOSED_GOP     ((int)0x80000000)
382
#define CODEC_FLAG2_FAST          0x00000001 ///< allow non spec compliant speedup tricks
383
#define CODEC_FLAG2_STRICT_GOP    0x00000002 ///< strictly enforce GOP size
384
#define CODEC_FLAG2_NO_OUTPUT     0x00000004 ///< skip bitstream encoding
385
#define CODEC_FLAG2_LOCAL_HEADER  0x00000008 ///< place global headers at every keyframe instead of in extradata
386
#define CODEC_FLAG2_BPYRAMID      0x00000010 ///< H.264 allow b-frames to be used as references
387
#define CODEC_FLAG2_WPRED         0x00000020 ///< H.264 weighted biprediction for b-frames
384
#define CODEC_FLAG2_FAST          0x00000001 ///< Allow non spec compliant speedup tricks.
385
#define CODEC_FLAG2_STRICT_GOP    0x00000002 ///< Strictly enforce GOP size.
386
#define CODEC_FLAG2_NO_OUTPUT     0x00000004 ///< Skip bitstream encoding.
387
#define CODEC_FLAG2_LOCAL_HEADER  0x00000008 ///< Place global headers at every keyframe instead of in extradata.
388
#define CODEC_FLAG2_BPYRAMID      0x00000010 ///< H.264 allow B-frames to be used as references.
389
#define CODEC_FLAG2_WPRED         0x00000020 ///< H.264 weighted biprediction for B-frames
388 390
#define CODEC_FLAG2_MIXED_REFS    0x00000040 ///< H.264 one reference per partition, as opposed to one reference per macroblock
389 391
#define CODEC_FLAG2_8X8DCT        0x00000080 ///< H.264 high profile 8x8 transform
390 392
#define CODEC_FLAG2_FASTPSKIP     0x00000100 ///< H.264 fast pskip
391 393
#define CODEC_FLAG2_AUD           0x00000200 ///< H.264 access unit delimiters
392
#define CODEC_FLAG2_BRDO          0x00000400 ///< b-frame rate-distortion optimization
393
#define CODEC_FLAG2_INTRA_VLC     0x00000800 ///< use MPEG-2 intra VLC table
394
#define CODEC_FLAG2_MEMC_ONLY     0x00001000 ///< only do ME/MC (I frames -> ref, P frame -> ME+MC)
395
#define CODEC_FLAG2_DROP_FRAME_TIMECODE 0x00002000 ///< timecode is in drop frame format
396
#define CODEC_FLAG2_SKIP_RD       0x00004000 ///< RD optimal MB level residual skiping
397
#define CODEC_FLAG2_CHUNKS        0x00008000 ///< input bitstream might be truncated at a packet boundaries instead of only at frame boundaries
398
#define CODEC_FLAG2_NON_LINEAR_QUANT 0x00010000 ///< use MPEG-2 non linear quantizer
394
#define CODEC_FLAG2_BRDO          0x00000400 ///< B-frame rate-distortion optimization
395
#define CODEC_FLAG2_INTRA_VLC     0x00000800 ///< Use MPEG-2 intra VLC table.
396
#define CODEC_FLAG2_MEMC_ONLY     0x00001000 ///< Only do ME/MC (I frames -> ref, P frame -> ME+MC).
397
#define CODEC_FLAG2_DROP_FRAME_TIMECODE 0x00002000 ///< timecode is in drop frame format.
398
#define CODEC_FLAG2_SKIP_RD       0x00004000 ///< RD optimal MB level residual skipping
399
#define CODEC_FLAG2_CHUNKS        0x00008000 ///< Input bitstream might be truncated at a packet boundaries instead of only at frame boundaries.
400
#define CODEC_FLAG2_NON_LINEAR_QUANT 0x00010000 ///< Use MPEG-2 nonlinear quantizer.
399 401

  
400 402
/* Unsupported options :
401 403
 *              Syntax Arithmetic coding (SAC)
......
404 406
/* /Fx */
405 407
/* codec capabilities */
406 408

  
407
#define CODEC_CAP_DRAW_HORIZ_BAND 0x0001 ///< decoder can use draw_horiz_band callback
409
#define CODEC_CAP_DRAW_HORIZ_BAND 0x0001 ///< Decoder can use draw_horiz_band callback.
408 410
/**
409 411
 * Codec uses get_buffer() for allocating buffers.
410 412
 * direct rendering method 1
411 413
 */
412 414
#define CODEC_CAP_DR1             0x0002
413
/* if 'parse_only' field is true, then avcodec_parse_frame() can be
414
   used */
415
/* If 'parse_only' field is true, then avcodec_parse_frame() can be used. */
415 416
#define CODEC_CAP_PARSE_ONLY      0x0004
416 417
#define CODEC_CAP_TRUNCATED       0x0008
417
/* codec can export data for HW decoding (XvMC) */
418
/* Codec can export data for HW decoding (XvMC). */
418 419
#define CODEC_CAP_HWACCEL         0x0010
419 420
/**
420
 * codec has a non zero delay and needs to be feeded with NULL at the end to get the delayed data.
421
 * if this is not set, the codec is guaranteed to never be feeded with NULL data
421
 * Codec has a nonzero delay and needs to be fed with NULL at the end to get the delayed data.
422
 * If this is not set, the codec is guaranteed to never be fed with NULL data.
422 423
 */
423 424
#define CODEC_CAP_DELAY           0x0020
424 425
/**
......
427 428
 */
428 429
#define CODEC_CAP_SMALL_LAST_FRAME 0x0040
429 430

  
430
//the following defines may change, don't expect compatibility if you use them
431
//The following defines may change, don't expect compatibility if you use them.
431 432
#define MB_TYPE_INTRA4x4   0x0001
432
#define MB_TYPE_INTRA16x16 0x0002 //FIXME h264 specific
433
#define MB_TYPE_INTRA_PCM  0x0004 //FIXME h264 specific
433
#define MB_TYPE_INTRA16x16 0x0002 //FIXME H.264-specific
434
#define MB_TYPE_INTRA_PCM  0x0004 //FIXME H.264-specific
434 435
#define MB_TYPE_16x16      0x0008
435 436
#define MB_TYPE_16x8       0x0010
436 437
#define MB_TYPE_8x16       0x0020
......
453 454

  
454 455
/**
455 456
 * Pan Scan area.
456
 * this specifies the area which should be displayed. Note there may be multiple such areas for one frame
457
 * This specifies the area which should be displayed.
458
 * Note there may be multiple such areas for one frame.
457 459
 */
458 460
typedef struct AVPanScan{
459 461
    /**
460
     * id.
461
     * - encoding: set by user.
462
     * - decoding: set by lavc
462
     * id
463
     * - encoding: Set by user.
464
     * - decoding: Set by libavcodec.
463 465
     */
464 466
    int id;
465 467

  
466 468
    /**
467 469
     * width and height in 1/16 pel
468
     * - encoding: set by user.
469
     * - decoding: set by lavc
470
     * - encoding: Set by user.
471
     * - decoding: Set by libavcodec.
470 472
     */
471 473
    int width;
472 474
    int height;
473 475

  
474 476
    /**
475
     * position of the top left corner in 1/16 pel for up to 3 fields/frames.
476
     * - encoding: set by user.
477
     * - decoding: set by lavc
477
     * position of the top left corner in 1/16 pel for up to 3 fields/frames
478
     * - encoding: Set by user.
479
     * - decoding: Set by libavcodec.
478 480
     */
479 481
    int16_t position[3][2];
480 482
}AVPanScan;
......
482 484
#define FF_COMMON_FRAME \
483 485
    /**\
484 486
     * pointer to the picture planes.\
485
     * this might be different from the first allocated byte\
487
     * This might be different from the first allocated byte\
486 488
     * - encoding: \
487 489
     * - decoding: \
488 490
     */\
489 491
    uint8_t *data[4];\
490 492
    int linesize[4];\
491 493
    /**\
492
     * pointer to the first allocated byte of the picture. can be used in get_buffer/release_buffer\
493
     * this isn't used by lavc unless the default get/release_buffer() is used\
494
     * pointer to the first allocated byte of the picture. Can be used in get_buffer/release_buffer.\
495
     * This isn't used by libavcodec unless the default get/release_buffer() is used.\
494 496
     * - encoding: \
495 497
     * - decoding: \
496 498
     */\
497 499
    uint8_t *base[4];\
498 500
    /**\
499 501
     * 1 -> keyframe, 0-> not\
500
     * - encoding: set by lavc\
501
     * - decoding: set by lavc\
502
     * - encoding: Set by libavcodec.\
503
     * - decoding: Set by libavcodec.\
502 504
     */\
503 505
    int key_frame;\
504 506
\
505 507
    /**\
506
     * picture type of the frame, see ?_TYPE below.\
507
     * - encoding: set by lavc for coded_picture (and set by user for input)\
508
     * - decoding: set by lavc\
508
     * Picture type of the frame, see ?_TYPE below.\
509
     * - encoding: Set by libavcodec. for coded_picture (and set by user for input).\
510
     * - decoding: Set by libavcodec.\
509 511
     */\
510 512
    int pict_type;\
511 513
\
512 514
    /**\
513 515
     * presentation timestamp in time_base units (time when frame should be shown to user)\
514
     * if AV_NOPTS_VALUE then frame_rate = 1/time_base will be assumed\
515
     * - encoding: MUST be set by user\
516
     * - decoding: set by lavc\
516
     * If AV_NOPTS_VALUE then frame_rate = 1/time_base will be assumed.\
517
     * - encoding: MUST be set by user.\
518
     * - decoding: Set by libavcodec.\
517 519
     */\
518 520
    int64_t pts;\
519 521
\
520 522
    /**\
521
     * picture number in bitstream order.\
523
     * picture number in bitstream order\
522 524
     * - encoding: set by\
523
     * - decoding: set by lavc\
525
     * - decoding: Set by libavcodec.\
524 526
     */\
525 527
    int coded_picture_number;\
526 528
    /**\
527
     * picture number in display order.\
529
     * picture number in display order\
528 530
     * - encoding: set by\
529
     * - decoding: set by lavc\
531
     * - decoding: Set by libavcodec.\
530 532
     */\
531 533
    int display_picture_number;\
532 534
\
533 535
    /**\
534 536
     * quality (between 1 (good) and FF_LAMBDA_MAX (bad)) \
535
     * - encoding: set by lavc for coded_picture (and set by user for input)\
536
     * - decoding: set by lavc\
537
     * - encoding: Set by libavcodec. for coded_picture (and set by user for input).\
538
     * - decoding: Set by libavcodec.\
537 539
     */\
538 540
    int quality; \
539 541
\
540 542
    /**\
541 543
     * buffer age (1->was last buffer and dint change, 2->..., ...).\
542
     * set to INT_MAX if the buffer has not been used yet \
544
     * Set to INT_MAX if the buffer has not been used yet.\
543 545
     * - encoding: unused\
544
     * - decoding: MUST be set by get_buffer()\
546
     * - decoding: MUST be set by get_buffer().\
545 547
     */\
546 548
    int age;\
547 549
\
548 550
    /**\
549 551
     * is this picture used as reference\
550 552
     * - encoding: unused\
551
     * - decoding: set by lavc (before get_buffer() call))\
553
     * - decoding: Set by libavcodec. (before get_buffer() call)).\
552 554
     */\
553 555
    int reference;\
554 556
\
555 557
    /**\
556 558
     * QP table\
557 559
     * - encoding: unused\
558
     * - decoding: set by lavc\
560
     * - decoding: Set by libavcodec.\
559 561
     */\
560 562
    int8_t *qscale_table;\
561 563
    /**\
562 564
     * QP store stride\
563 565
     * - encoding: unused\
564
     * - decoding: set by lavc\
566
     * - decoding: Set by libavcodec.\
565 567
     */\
566 568
    int qstride;\
567 569
\
568 570
    /**\
569
     * mbskip_table[mb]>=1 if MB didnt change\
571
     * mbskip_table[mb]>=1 if MB didn't change\
570 572
     * stride= mb_width = (width+15)>>4\
571 573
     * - encoding: unused\
572
     * - decoding: set by lavc\
574
     * - decoding: Set by libavcodec.\
573 575
     */\
574 576
    uint8_t *mbskip_table;\
575 577
\
576 578
    /**\
577
     * Motion vector table.\
579
     * motion vector table\
578 580
     * @code\
579 581
     * example:\
580 582
     * int mv_sample_log2= 4 - motion_subsample_log2;\
......
582 584
     * int mv_stride= (mb_width << mv_sample_log2) + 1;\
583 585
     * motion_val[direction][x + y*mv_stride][0->mv_x, 1->mv_y];\
584 586
     * @endcode\
585
     * - encoding: set by user\
586
     * - decoding: set by lavc\
587
     * - encoding: Set by user.\
588
     * - decoding: Set by libavcodec.\
587 589
     */\
588 590
    int16_t (*motion_val[2])[2];\
589 591
\
590 592
    /**\
591
     * Macroblock type table\
593
     * macroblock type table\
592 594
     * mb_type_base + mb_width + 2\
593
     * - encoding: set by user\
594
     * - decoding: set by lavc\
595
     * - encoding: Set by user.\
596
     * - decoding: Set by libavcodec.\
595 597
     */\
596 598
    uint32_t *mb_type;\
597 599
\
......
599 601
     * log2 of the size of the block which a single vector in motion_val represents: \
600 602
     * (4->16x16, 3->8x8, 2-> 4x4, 1-> 2x2)\
601 603
     * - encoding: unused\
602
     * - decoding: set by lavc\
604
     * - decoding: Set by libavcodec.\
603 605
     */\
604 606
    uint8_t motion_subsample_log2;\
605 607
\
606 608
    /**\
607 609
     * for some private data of the user\
608 610
     * - encoding: unused\
609
     * - decoding: set by user\
611
     * - decoding: Set by user.\
610 612
     */\
611 613
    void *opaque;\
612 614
\
613 615
    /**\
614 616
     * error\
615
     * - encoding: set by lavc if flags&CODEC_FLAG_PSNR\
617
     * - encoding: Set by libavcodec. if flags&CODEC_FLAG_PSNR.\
616 618
     * - decoding: unused\
617 619
     */\
618 620
    uint64_t error[4];\
619 621
\
620 622
    /**\
621
     * type of the buffer (to keep track of who has to dealloc data[*])\
622
     * - encoding: set by the one who allocs it\
623
     * - decoding: set by the one who allocs it\
624
     * Note: user allocated (direct rendering) & internal buffers can not coexist currently\
623
     * type of the buffer (to keep track of who has to deallocate data[*])\
624
     * - encoding: Set by the one who allocates it.\
625
     * - decoding: Set by the one who allocates it.\
626
     * Note: User allocated (direct rendering) & internal buffers cannot coexist currently.\
625 627
     */\
626 628
    int type;\
627 629
    \
628 630
    /**\
629
     * when decoding, this signal how much the picture must be delayed.\
631
     * When decoding, this signals how much the picture must be delayed.\
630 632
     * extra_delay = repeat_pict / (2*fps)\
631 633
     * - encoding: unused\
632
     * - decoding: set by lavc\
634
     * - decoding: Set by libavcodec.\
633 635
     */\
634 636
    int repeat_pict;\
635 637
    \
......
640 642
    \
641 643
    /**\
642 644
     * The content of the picture is interlaced.\
643
     * - encoding: set by user\
644
     * - decoding: set by lavc (default 0)\
645
     * - encoding: Set by user.\
646
     * - decoding: Set by libavcodec. (default 0)\
645 647
     */\
646 648
    int interlaced_frame;\
647 649
    \
648 650
    /**\
649
     * if the content is interlaced, is top field displayed first.\
650
     * - encoding: set by user\
651
     * - decoding: set by lavc\
651
     * If the content is interlaced, is top field displayed first.\
652
     * - encoding: Set by user.\
653
     * - decoding: Set by libavcodec.\
652 654
     */\
653 655
    int top_field_first;\
654 656
    \
655 657
    /**\
656 658
     * Pan scan.\
657
     * - encoding: set by user\
658
     * - decoding: set by lavc\
659
     * - encoding: Set by user.\
660
     * - decoding: Set by libavcodec.\
659 661
     */\
660 662
    AVPanScan *pan_scan;\
661 663
    \
662 664
    /**\
663
     * tell user application that palette has changed from previous frame.\
665
     * Tell user application that palette has changed from previous frame.\
664 666
     * - encoding: ??? (no palette-enabled encoder yet)\
665
     * - decoding: set by lavc (default 0)\
667
     * - decoding: Set by libavcodec. (default 0).\
666 668
     */\
667 669
    int palette_has_changed;\
668 670
    \
669 671
    /**\
670
     * Codec suggestion on buffer type if != 0\
672
     * codec suggestion on buffer type if != 0\
671 673
     * - encoding: unused\
672
     * - decoding: set by lavc (before get_buffer() call))\
674
     * - decoding: Set by libavcodec. (before get_buffer() call)).\
673 675
     */\
674 676
    int buffer_hints;\
675 677
\
676 678
    /**\
677
     * DCT coeffitients\
679
     * DCT coefficients\
678 680
     * - encoding: unused\
679
     * - decoding: set by lavc\
681
     * - decoding: Set by libavcodec.\
680 682
     */\
681 683
    short *dct_coeff;\
682 684
\
683 685
    /**\
684
     * Motion referece frame index\
685
     * - encoding: set by user\
686
     * - decoding: set by lavc\
686
     * motion referece frame index\
687
     * - encoding: Set by user.\
688
     * - decoding: Set by libavcodec.\
687 689
     */\
688 690
    int8_t *ref_index[2];
689 691

  
......
692 694
#define FF_QSCALE_TYPE_H264  2
693 695

  
694 696
#define FF_BUFFER_TYPE_INTERNAL 1
695
#define FF_BUFFER_TYPE_USER     2 ///< Direct rendering buffers (image is (de)allocated by user)
696
#define FF_BUFFER_TYPE_SHARED   4 ///< buffer from somewhere else, don't dealloc image (data/base), all other tables are not shared
697
#define FF_BUFFER_TYPE_COPY     8 ///< just a (modified) copy of some other buffer, don't dealloc anything
697
#define FF_BUFFER_TYPE_USER     2 ///< direct rendering buffers (image is (de)allocated by user)
698
#define FF_BUFFER_TYPE_SHARED   4 ///< Buffer from somewhere else; don't deallocate image (data/base), all other tables are not shared.
699
#define FF_BUFFER_TYPE_COPY     8 ///< Just a (modified) copy of some other buffer, don't deallocate anything.
698 700

  
699 701

  
700 702
#define FF_I_TYPE 1 // Intra
......
704 706
#define FF_SI_TYPE 5
705 707
#define FF_SP_TYPE 6
706 708

  
707
#define FF_BUFFER_HINTS_VALID    0x01 // Buffer hints value is meaningful (if 0 ignore)
708
#define FF_BUFFER_HINTS_READABLE 0x02 // Codec will read from buffer
709
#define FF_BUFFER_HINTS_PRESERVE 0x04 // User must not alter buffer content
710
#define FF_BUFFER_HINTS_REUSABLE 0x08 // Codec will reuse the buffer (update)
709
#define FF_BUFFER_HINTS_VALID    0x01 // Buffer hints value is meaningful (if 0 ignore).
710
#define FF_BUFFER_HINTS_READABLE 0x02 // Codec will read from buffer.
711
#define FF_BUFFER_HINTS_PRESERVE 0x04 // User must not alter buffer content.
712
#define FF_BUFFER_HINTS_REUSABLE 0x08 // Codec will reuse the buffer (update).
711 713

  
712 714
/**
713 715
 * Audio Video Frame.
......
719 721
#define DEFAULT_FRAME_RATE_BASE 1001000
720 722

  
721 723
/**
722
 * main external api structure.
724
 * main external API structure
723 725
 */
724 726
typedef struct AVCodecContext {
725 727
    /**
726
     * Info on struct for av_log
728
     * information on struct for av_log
727 729
     * - set by avcodec_alloc_context
728 730
     */
729 731
    AVClass *av_class;
730 732
    /**
731
     * the average bitrate.
732
     * - encoding: set by user. unused for constant quantizer encoding
733
     * - decoding: set by lavc. 0 or some bitrate if this info is available in the stream
733
     * the average bitrate
734
     * - encoding: Set by user; unused for constant quantizer encoding.
735
     * - decoding: Set by libavcodec. 0 or some bitrate if this info is available in the stream.
734 736
     */
735 737
    int bit_rate;
736 738

  
737 739
    /**
738 740
     * number of bits the bitstream is allowed to diverge from the reference.
739 741
     *           the reference can be CBR (for CBR pass1) or VBR (for pass2)
740
     * - encoding: set by user. unused for constant quantizer encoding
742
     * - encoding: Set by user; unused for constant quantizer encoding.
741 743
     * - decoding: unused
742 744
     */
743 745
    int bit_rate_tolerance;
744 746

  
745 747
    /**
746 748
     * CODEC_FLAG_*.
747
     * - encoding: set by user.
748
     * - decoding: set by user.
749
     * - encoding: Set by user.
750
     * - decoding: Set by user.
749 751
     */
750 752
    int flags;
751 753

  
752 754
    /**
753
     * some codecs needs additionnal format info. It is stored here
754
     * if any muxer uses this then ALL demuxers/parsers AND encoders for the specific codec MUST set it correctly
755
     * too otherwise stream copy breaks
756
     * in general use of this field by muxers is not recommanded
757
     * - encoding: set by lavc.
758
     * - decoding: set by lavc. (FIXME is this ok?)
755
     * Some codecs need additional format info. It is stored here.
756
     * If any muxer uses this then ALL demuxers/parsers AND encoders for the
757
     * specific codec MUST set it correctly otherwise stream copy breaks.
758
     * In general use of this field by muxers is not recommanded.
759
     * - encoding: Set by libavcodec.
760
     * - decoding: Set by libavcodec. (FIXME: Is this OK?)
759 761
     */
760 762
    int sub_id;
761 763

  
762 764
    /**
763
     * motion estimation algorithm used for video coding.
765
     * Motion estimation algorithm used for video coding.
764 766
     * 1 (zero), 2 (full), 3 (log), 4 (phods), 5 (epzs), 6 (x1), 7 (hex),
765 767
     * 8 (umh), 9 (iter) [7, 8 are x264 specific, 9 is snow specific]
766 768
     * - encoding: MUST be set by user.
......
769 771
    int me_method;
770 772

  
771 773
    /**
772
     * some codecs need / can use extra-data like huffman tables.
773
     * mjpeg: huffman tables
774
     * some codecs need / can use extradata like Huffman tables.
775
     * mjpeg: Huffman tables
774 776
     * rv10: additional flags
775 777
     * mpeg4: global headers (they can be in the bitstream or here)
776
     * the allocated memory should be FF_INPUT_BUFFER_PADDING_SIZE bytes larger
777
     * then extradata_size to avoid prolems if its read with the bitstream reader
778
     * the bytewise contents of extradata must not depend on the architecture or cpu endianness
779
     * - encoding: set/allocated/freed by lavc.
780
     * - decoding: set/allocated/freed by user.
778
     * The allocated memory should be FF_INPUT_BUFFER_PADDING_SIZE bytes larger
779
     * than extradata_size to avoid prolems if it is read with the bitstream reader.
780
     * The bytewise contents of extradata must not depend on the architecture or CPU endianness.
781
     * - encoding: Set/allocated/freed by libavcodec.
782
     * - decoding: Set/allocated/freed by user.
781 783
     */
782 784
    uint8_t *extradata;
783 785
    int extradata_size;
784 786

  
785 787
    /**
786
     * this is the fundamental unit of time (in seconds) in terms
787
     * of which frame timestamps are represented. for fixed-fps content,
788
     * This is the fundamental unit of time (in seconds) in terms
789
     * of which frame timestamps are represented. For fixed-fps content,
788 790
     * timebase should be 1/framerate and timestamp increments should be
789 791
     * identically 1.
790
     * - encoding: MUST be set by user
791
     * - decoding: set by lavc.
792
     * - encoding: MUST be set by user.
793
     * - decoding: Set by libavcodec.
792 794
     */
793 795
    AVRational time_base;
794 796

  
......
796 798
    /**
797 799
     * picture width / height.
798 800
     * - encoding: MUST be set by user.
799
     * - decoding: set by lavc.
800
     * Note, for compatibility its possible to set this instead of
801
     * coded_width/height before decoding
801
     * - decoding: Set by libavcodec.
802
     * Note: For compatibility it is possible to set this instead of
803
     * coded_width/height before decoding.
802 804
     */
803 805
    int width, height;
804 806

  
805 807
#define FF_ASPECT_EXTENDED 15
806 808

  
807 809
    /**
808
     * the number of pictures in a group of pitures, or 0 for intra_only.
809
     * - encoding: set by user.
810
     * the number of pictures in a group of pictures, or 0 for intra_only
811
     * - encoding: Set by user.
810 812
     * - decoding: unused
811 813
     */
812 814
    int gop_size;
813 815

  
814 816
    /**
815
     * pixel format, see PIX_FMT_xxx.
816
     * - encoding: set by user.
817
     * - decoding: set by lavc.
817
     * Pixel format, see PIX_FMT_xxx.
818
     * - encoding: Set by user.
819
     * - decoding: Set by libavcodec.
818 820
     */
819 821
    enum PixelFormat pix_fmt;
820 822

  
821 823
    /**
822
     * Frame rate emulation. If not zero lower layer (i.e. format handler)
824
     * Frame rate emulation. If not zero, the lower layer (i.e. format handler)
823 825
     * has to read frames at native frame rate.
824
     * - encoding: set by user.
825
     * - decoding: unused.
826
     * - encoding: Set by user.
827
     * - decoding: unused
826 828
     */
827 829
    int rate_emu;
828 830

  
829 831
    /**
830
     * if non NULL, 'draw_horiz_band' is called by the libavcodec
831
     * decoder to draw an horizontal band. It improve cache usage. Not
832
     * If non NULL, 'draw_horiz_band' is called by the libavcodec
833
     * decoder to draw a horizontal band. It improves cache usage. Not
832 834
     * all codecs can do that. You must check the codec capabilities
833
     * before
835
     * beforehand.
834 836
     * - encoding: unused
835
     * - decoding: set by user.
837
     * - decoding: Set by user.
836 838
     * @param height the height of the slice
837 839
     * @param y the y position of the slice
838 840
     * @param type 1->top field, 2->bottom field, 3->frame
......
843 845
                            int y, int type, int height);
844 846

  
845 847
    /* audio only */
846
    int sample_rate; ///< samples per sec
848
    int sample_rate; ///< samples per second
847 849
    int channels;
848 850

  
849 851
    /**
850
     * audio sample format.
851
     * - encoding: set by user.
852
     * - decoding: set by lavc.
852
     * audio sample format
853
     * - encoding: Set by user.
854
     * - decoding: Set by libavcodec.
853 855
     */
854
    enum SampleFormat sample_fmt;  ///< sample format, currenly unused
856
    enum SampleFormat sample_fmt;  ///< sample format, currently unused
855 857

  
856
    /* the following data should not be initialized */
858
    /* The following data should not be initialized. */
857 859
    /**
858
     * samples per packet. initialized when calling 'init'
860
     * Samples per packet, initialized when calling 'init'.
859 861
     */
860 862
    int frame_size;
861 863
    int frame_number;   ///< audio or video frame number
862
    int real_pict_num;  ///< returns the real picture number of previous encoded frame
864
    int real_pict_num;  ///< Returns the real picture number of previous encoded frame.
863 865

  
864 866
    /**
865
     * number of frames the decoded output will be delayed relative to
867
     * Number of frames the decoded output will be delayed relative to
866 868
     * the encoded input.
867
     * - encoding: set by lavc.
869
     * - encoding: Set by libavcodec.
868 870
     * - decoding: unused
869 871
     */
870 872
    int delay;
......
874 876
    float qblur;      ///< amount of qscale smoothing over time (0.0-1.0)
875 877

  
876 878
    /**
877
     * minimum quantizer.
878
     * - encoding: set by user.
879
     * minimum quantizer
880
     * - encoding: Set by user.
879 881
     * - decoding: unused
880 882
     */
881 883
    int qmin;
882 884

  
883 885
    /**
884
     * maximum quantizer.
885
     * - encoding: set by user.
886
     * maximum quantizer
887
     * - encoding: Set by user.
886 888
     * - decoding: unused
887 889
     */
888 890
    int qmax;
889 891

  
890 892
    /**
891
     * maximum quantizer difference between frames.
892
     * - encoding: set by user.
893
     * maximum quantizer difference between frames
894
     * - encoding: Set by user.
893 895
     * - decoding: unused
894 896
     */
895 897
    int max_qdiff;
896 898

  
897 899
    /**
898
     * maximum number of b frames between non b frames.
899
     * note: the output will be delayed by max_b_frames+1 relative to the input
900
     * - encoding: set by user.
900
     * maximum number of B-frames between non-B-frames
901
     * Note: The output will be delayed by max_b_frames+1 relative to the input.
902
     * - encoding: Set by user.
901 903
     * - decoding: unused
902 904
     */
903 905
    int max_b_frames;
904 906

  
905 907
    /**
906
     * qscale factor between ip and b frames.
907
     * - encoding: set by user.
908
     * qscale factor between IP and B-frames
909
     * - encoding: Set by user.
908 910
     * - decoding: unused
909 911
     */
910 912
    float b_quant_factor;
......
916 918
    int b_frame_strategy;
917 919

  
918 920
    /**
919
     * hurry up amount.
921
     * hurry up amount
920 922
     * - encoding: unused
921
     * - decoding: set by user. 1-> skip b frames, 2-> skip idct/dequant too, 5-> skip everything except header
923
     * - decoding: Set by user. 1-> Skip B-frames, 2-> Skip IDCT/dequant too, 5-> Skip everything except header
922 924
     * @deprecated Deprecated in favor of skip_idct and skip_frame.
923 925
     */
924 926
    int hurry_up;
......
933 935
#endif
934 936

  
935 937
    int rtp_payload_size;   /* The size of the RTP payload: the coder will  */
936
                            /* do it's best to deliver a chunk with size    */
938
                            /* do its best to deliver a chunk with size     */
937 939
                            /* below rtp_payload_size, the chunk will start */
938
                            /* with a start code on some codecs like H.263  */
940
                            /* with a start code on some codecs like H.263. */
939 941
                            /* This doesn't take account of any particular  */
940
                            /* headers inside the transmited RTP payload    */
942
                            /* headers inside the transmitted RTP payload.  */
941 943

  
942 944

  
943
    /* The RTP callback: This function is called   */
944
    /* every time the encoder has a packet to send */
945
    /* Depends on the encoder if the data starts   */
946
    /* with a Start Code (it should) H.263 does.   */
947
    /* mb_nb contains the number of macroblocks    */
948
    /* encoded in the RTP payload                  */
945
    /* The RTP callback: This function is called    */
946
    /* every time the encoder has a packet to send. */
947
    /* It depends on the encoder if the data starts */
948
    /* with a Start Code (it should). H.263 does.   */
949
    /* mb_nb contains the number of macroblocks     */
950
    /* encoded in the RTP payload.                  */
949 951
    void (*rtp_callback)(struct AVCodecContext *avctx, void *data, int size, int mb_nb);
950 952

  
951 953
    /* statistics, used for 2-pass encoding */
......
959 961
    int misc_bits;
960 962

  
961 963
    /**
962
     * number of bits used for the previously encoded frame.
963
     * - encoding: set by lavc
964
     * number of bits used for the previously encoded frame
965
     * - encoding: Set by libavcodec.
964 966
     * - decoding: unused
965 967
     */
966 968
    int frame_bits;
967 969

  
968 970
    /**
969
     * private data of the user, can be used to carry app specific stuff.
970
     * - encoding: set by user
971
     * - decoding: set by user
971
     * Private data of the user, can be used to carry app specific stuff.
972
     * - encoding: Set by user.
973
     * - decoding: Set by user.
972 974
     */
973 975
    void *opaque;
974 976

  
......
978 980

  
979 981
    /**
980 982
     * fourcc (LSB first, so "ABCD" -> ('D'<<24) + ('C'<<16) + ('B'<<8) + 'A').
981
     * this is used to workaround some encoder bugs
982
     * a demuxer should set this to what is stored in the field used to identify the codec
983
     * if there are mutiple such fields in a container then the demuxer should choose the one
984
     * which maximizes the information about the used codec
985
     * if the codec tag field in a container is larger then 32bit then the demxuer should
986
     * remap the longer id to 32bit with a table or other structure alternatively a new
983
     * This is used to work around some encoder bugs.
984
     * A demuxer should set this to what is stored in the field used to identify the codec.
985
     * If there are multiple such fields in a container then the demuxer should choose the one
986
     * which maximizes the information about the used codec.
987
     * If the codec tag field in a container is larger then 32 bits then the demuxer should
988
     * remap the longer ID to 32 bits with a table or other structure. Alternatively a new
987 989
     * extra_codec_tag + size could be added but for this a clear advantage must be demonstrated
988
     * first
989
     * - encoding: set by user, if not then the default based on codec_id will be used
990
     * - decoding: set by user, will be converted to upper case by lavc during init
990
     * first.
991
     * - encoding: Set by user, if not then the default based on codec_id will be used.
992
     * - decoding: Set by user, will be converted to uppercase by libavcodec during init.
991 993
     */
992 994
    unsigned int codec_tag;
993 995

  
994 996
    /**
995
     * workaround bugs in encoders which sometimes cannot be detected automatically.
996
     * - encoding: set by user
997
     * - decoding: set by user
997
     * Work around bugs in encoders which sometimes cannot be detected automatically.
998
     * - encoding: Set by user
999
     * - decoding: Set by user
998 1000
     */
999 1001
    int workaround_bugs;
1000 1002
#define FF_BUG_AUTODETECT       1  ///< autodetection
......
1003 1005
#define FF_BUG_UMP4             8
1004 1006
#define FF_BUG_NO_PADDING       16
1005 1007
#define FF_BUG_AMV              32
1006
#define FF_BUG_AC_VLC           0  ///< will be removed, libavcodec can now handle these non compliant files by default
1008
#define FF_BUG_AC_VLC           0  ///< Will be removed, libavcodec can now handle these non-compliant files by default.
1007 1009
#define FF_BUG_QPEL_CHROMA      64
1008 1010
#define FF_BUG_STD_QPEL         128
1009 1011
#define FF_BUG_QPEL_CHROMA2     256
......
1011 1013
#define FF_BUG_EDGE             1024
1012 1014
#define FF_BUG_HPEL_CHROMA      2048
1013 1015
#define FF_BUG_DC_CLIP          4096
1014
#define FF_BUG_MS               8192 ///< workaround various bugs in microsofts broken decoders
1015
//#define FF_BUG_FAKE_SCALABILITY 16 //autodetection should work 100%
1016
#define FF_BUG_MS               8192 ///< Work around various bugs in Microsoft's broken decoders.
1017
//#define FF_BUG_FAKE_SCALABILITY 16 //Autodetection should work 100%.
1016 1018

  
1017 1019
    /**
1018
     * luma single coeff elimination threshold.
1019
     * - encoding: set by user
1020
     * luma single coefficient elimination threshold
1021
     * - encoding: Set by user.
1020 1022
     * - decoding: unused
1021 1023
     */
1022 1024
    int luma_elim_threshold;
1023 1025

  
1024 1026
    /**
1025
     * chroma single coeff elimination threshold.
1026
     * - encoding: set by user
1027
     * chroma single coeff elimination threshold
1028
     * - encoding: Set by user.
1027 1029
     * - decoding: unused
1028 1030
     */
1029 1031
    int chroma_elim_threshold;
1030 1032

  
1031 1033
    /**
1032
     * strictly follow the std (MPEG4, ...).
1033
     * - encoding: set by user
1034
     * strictly follow the standard (MPEG4, ...).
1035
     * - encoding: Set by user.
1034 1036
     * - decoding: unused
1035 1037
     */
1036 1038
    int strict_std_compliance;
1037
#define FF_COMPLIANCE_VERY_STRICT   2 ///< strictly conform to a older more strict version of the spec or reference software
1038
#define FF_COMPLIANCE_STRICT        1 ///< strictly conform to all the things in the spec no matter what consequences
1039
#define FF_COMPLIANCE_VERY_STRICT   2 ///< Strictly conform to a older more strict version of the spec or reference software.
1040
#define FF_COMPLIANCE_STRICT        1 ///< Strictly conform to all the things in the spec no matter what consequences.
1039 1041
#define FF_COMPLIANCE_NORMAL        0
1040
#define FF_COMPLIANCE_INOFFICIAL   -1 ///< allow inofficial extensions
1041
#define FF_COMPLIANCE_EXPERIMENTAL -2 ///< allow non standarized experimental things
1042
#define FF_COMPLIANCE_INOFFICIAL   -1 ///< Allow inofficial extensions.
1043
#define FF_COMPLIANCE_EXPERIMENTAL -2 ///< Allow nonstandardized experimental things.
1042 1044

  
1043 1045
    /**
1044
     * qscale offset between ip and b frames.
1045
     * if > 0 then the last p frame quantizer will be used (q= lastp_q*factor+offset)
1046
     * if < 0 then normal ratecontrol will be done (q= -normal_q*factor+offset)
1047
     * - encoding: set by user.
1046
     * qscale offset between IP and B-frames
1047
     * If > 0 then the last P-frame quantizer will be used (q= lastp_q*factor+offset).
1048
     * If < 0 then normal ratecontrol will be done (q= -normal_q*factor+offset).
1049
     * - encoding: Set by user.
1048 1050
     * - decoding: unused
1049 1051
     */
1050 1052
    float b_quant_offset;
1051 1053

  
1052 1054
    /**
1053
     * error resilience higher values will detect more errors but may missdetect
1054
     * some more or less valid parts as errors.
1055
     * Error resilience; higher values will detect more errors but may
1056
     * misdetect some more or less valid parts as errors.
1055 1057
     * - encoding: unused
1056
     * - decoding: set by user
1058
     * - decoding: Set by user.
1057 1059
     */
1058 1060
    int error_resilience;
1059 1061
#define FF_ER_CAREFUL         1
......
1062 1064
#define FF_ER_VERY_AGGRESSIVE 4
1063 1065

  
1064 1066
    /**
1065
     * called at the beginning of each frame to get a buffer for it.
1066
     * if pic.reference is set then the frame will be read later by lavc
1067
     * Called at the beginning of each frame to get a buffer for it.
1068
     * If pic.reference is set then the frame will be read later by libavcodec.
1067 1069
     * avcodec_align_dimensions() should be used to find the required width and
1068
     * height, as they normally need to be rounded up to the next multiple of 16
1070
     * height, as they normally need to be rounded up to the next multiple of 16.
1069 1071
     * - encoding: unused
1070
     * - decoding: set by lavc, user can override
1072
     * - decoding: Set by libavcodec., user can override.
1071 1073
     */
1072 1074
    int (*get_buffer)(struct AVCodecContext *c, AVFrame *pic);
1073 1075

  
1074 1076
    /**
1075
     * called to release buffers which where allocated with get_buffer.
1076
     * a released buffer can be reused in get_buffer()
1077
     * pic.data[*] must be set to NULL
1077
     * Called to release buffers which where allocated with get_buffer.
1078
     * A released buffer can be reused in get_buffer().
1079
     * pic.data[*] must be set to NULL.
1078 1080
     * - encoding: unused
1079
     * - decoding: set by lavc, user can override
1081
     * - decoding: Set by libavcodec., user can override.
1080 1082
     */
1081 1083
    void (*release_buffer)(struct AVCodecContext *c, AVFrame *pic);
1082 1084

  
1083 1085
    /**
1084
     * if 1 the stream has a 1 frame delay during decoding.
1085
     * - encoding: set by lavc
1086
     * - decoding: set by lavc
1086
     * If 1 the stream has a 1 frame delay during decoding.
1087
     * - encoding: Set by libavcodec.
1088
     * - decoding: Set by libavcodec.
1087 1089
     */
1088 1090
    int has_b_frames;
1089 1091

  
1090 1092
    /**
1091 1093
     * number of bytes per packet if constant and known or 0
1092
     * used by some WAV based audio codecs
1094
     * Used by some WAV based audio codecs.
1093 1095
     */
1094 1096
    int block_align;
1095 1097

  
1096
    int parse_only; /* - decoding only: if true, only parsing is done
1098
    int parse_only; /* - decoding only: If true, only parsing is done
1097 1099
                       (function avcodec_parse_frame()). The frame
1098 1100
                       data is returned. Only MPEG codecs support this now. */
1099 1101

  
1100 1102
    /**
1101
     * 0-> h263 quant 1-> mpeg quant.
1102
     * - encoding: set by user.
1103
     * 0-> h263 quant 1-> mpeg quant
1104
     * - encoding: Set by user.
1103 1105
     * - decoding: unused
1104 1106
     */
1105 1107
    int mpeg_quant;
1106 1108

  
1107 1109
    /**
1108
     * pass1 encoding statistics output buffer.
1109
     * - encoding: set by lavc
1110
     * pass1 encoding statistics output buffer
1111
     * - encoding: Set by libavcodec.
1110 1112
     * - decoding: unused
1111 1113
     */
1112 1114
    char *stats_out;
1113 1115

  
1114 1116
    /**
1115
     * pass2 encoding statistics input buffer.
1116
     * concatenated stuff from stats_out of pass1 should be placed here
1117
     * - encoding: allocated/set/freed by user
1117
     * pass2 encoding statistics input buffer
1118
     * Concatenated stuff from stats_out of pass1 should be placed here.
1119
     * - encoding: Allocated/set/freed by user.
1118 1120
     * - decoding: unused
1119 1121
     */
1120 1122
    char *stats_in;
1121 1123

  
1122 1124
    /**
1123
     * ratecontrol qmin qmax limiting method.
1124
     * 0-> clipping, 1-> use a nice continous function to limit qscale wthin qmin/qmax
1125
     * - encoding: set by user.
1125
     * ratecontrol qmin qmax limiting method
1126
     * 0-> clipping, 1-> use a nice continous function to limit qscale wthin qmin/qmax.
1127
     * - encoding: Set by user.
1126 1128
     * - decoding: unused
1127 1129
     */
1128 1130
    float rc_qsquish;
......
1131 1133
    int rc_qmod_freq;
1132 1134

  
1133 1135
    /**
1134
     * ratecontrol override, see RcOverride.
1135
     * - encoding: allocated/set/freed by user.
1136
     * ratecontrol override, see RcOverride
1137
     * - encoding: Allocated/set/freed by user.
1136 1138
     * - decoding: unused
1137 1139
     */
1138 1140
    RcOverride *rc_override;
1139 1141
    int rc_override_count;
1140 1142

  
1141 1143
    /**
1142
     * rate control equation.
1143
     * - encoding: set by user
1144
     * rate control equation
1145
     * - encoding: Set by user
1144 1146
     * - decoding: unused
1145 1147
     */
1146 1148
    char *rc_eq;
1147 1149

  
1148 1150
    /**
1149
     * maximum bitrate.
1150
     * - encoding: set by user.
1151
     * maximum bitrate
1152
     * - encoding: Set by user.
1151 1153
     * - decoding: unused
1152 1154
     */
1153 1155
    int rc_max_rate;
1154 1156

  
1155 1157
    /**
1156
     * minimum bitrate.
1157
     * - encoding: set by user.
1158
     * minimum bitrate
1159
     * - encoding: Set by user.
1158 1160
     * - decoding: unused
1159 1161
     */
1160 1162
    int rc_min_rate;
1161 1163

  
1162 1164
    /**
1163
     * decoder bitstream buffer size.
1164
     * - encoding: set by user.
1165
     * decoder bitstream buffer size
1166
     * - encoding: Set by user.
1165 1167
     * - decoding: unused
1166 1168
     */
1167 1169
    int rc_buffer_size;
1168 1170
    float rc_buffer_aggressivity;
1169 1171

  
1170 1172
    /**
1171
     * qscale factor between p and i frames.
1172
     * if > 0 then the last p frame quantizer will be used (q= lastp_q*factor+offset)
1173
     * if < 0 then normal ratecontrol will be done (q= -normal_q*factor+offset)
1174
     * - encoding: set by user.
1173
     * qscale factor between P and I-frames
1174
     * If > 0 then the last p frame quantizer will be used (q= lastp_q*factor+offset).
1175
     * If < 0 then normal ratecontrol will be done (q= -normal_q*factor+offset).
1176
     * - encoding: Set by user.
1175 1177
     * - decoding: unused
1176 1178
     */
1177 1179
    float i_quant_factor;
1178 1180

  
1179 1181
    /**
1180
     * qscale offset between p and i frames.
1181
     * - encoding: set by user.
1182
     * qscale offset between P and I-frames
1183
     * - encoding: Set by user.
1182 1184
     * - decoding: unused
1183 1185
     */
1184 1186
    float i_quant_offset;
1185 1187

  
1186 1188
    /**
1187
     * initial complexity for pass1 ratecontrol.
1188
     * - encoding: set by user.
1189
     * initial complexity for pass1 ratecontrol
1190
     * - encoding: Set by user.
1189 1191
     * - decoding: unused
1190 1192
     */
1191 1193
    float rc_initial_cplx;
1192 1194

  
1193 1195
    /**
1194
     * dct algorithm, see FF_DCT_* below.
1195
     * - encoding: set by user
1196
     * DCT algorithm, see FF_DCT_* below
1197
     * - encoding: Set by user.
1196 1198
     * - decoding: unused
1197 1199
     */
1198 1200
    int dct_algo;
......
1205 1207
#define FF_DCT_FAAN    6
1206 1208

  
1207 1209
    /**
1208
     * luminance masking (0-> disabled).
1209
     * - encoding: set by user
1210
     * luminance masking (0-> disabled)
1211
     * - encoding: Set by user.
1210 1212
     * - decoding: unused
1211 1213
     */
1212 1214
    float lumi_masking;
1213 1215

  
1214 1216
    /**
1215
     * temporary complexity masking (0-> disabled).
1216
     * - encoding: set by user
1217
     * temporary complexity masking (0-> disabled)
1218
     * - encoding: Set by user.
1217 1219
     * - decoding: unused
1218 1220
     */
1219 1221
    float temporal_cplx_masking;
1220 1222

  
1221 1223
    /**
1222
     * spatial complexity masking (0-> disabled).
1223
     * - encoding: set by user
1224
     * spatial complexity masking (0-> disabled)
1225
     * - encoding: Set by user.
1224 1226
     * - decoding: unused
1225 1227
     */
1226 1228
    float spatial_cplx_masking;
1227 1229

  
1228 1230
    /**
1229
     * p block masking (0-> disabled).
1230
     * - encoding: set by user
1231
     * p block masking (0-> disabled)
1232
     * - encoding: Set by user.
1231 1233
     * - decoding: unused
1232 1234
     */
1233 1235
    float p_masking;
1234 1236

  
1235 1237
    /**
1236
     * darkness masking (0-> disabled).
1237
     * - encoding: set by user
1238
     * darkness masking (0-> disabled)
1239
     * - encoding: Set by user.
1238 1240
     * - decoding: unused
1239 1241
     */
1240 1242
    float dark_masking;
......
1244 1246
    int unused;
1245 1247

  
1246 1248
    /**
1247
     * idct algorithm, see FF_IDCT_* below.
1248
     * - encoding: set by user
1249
     * - decoding: set by user
1249
     * IDCT algorithm, see FF_IDCT_* below.
1250
     * - encoding: Set by user.
1251
     * - decoding: Set by user.
1250 1252
     */
1251 1253
    int idct_algo;
1252 1254
#define FF_IDCT_AUTO         0
......
1269 1271
#define FF_IDCT_SIMPLEARMV6  17
1270 1272

  
1271 1273
    /**
1272
     * slice count.
1273
     * - encoding: set by lavc
1274
     * - decoding: set by user (or 0)
1274
     * slice count
1275
     * - encoding: Set by libavcodec.
1276
     * - decoding: Set by user (or 0).
1275 1277
     */
1276 1278
    int slice_count;
1277 1279
    /**
1278
     * slice offsets in the frame in bytes.
1279
     * - encoding: set/allocated by lavc
1280
     * - decoding: set/allocated by user (or NULL)
1280
     * slice offsets in the frame in bytes
1281
     * - encoding: Set/allocated by libavcodec.
1282
     * - decoding: Set/allocated by user (or NULL).
1281 1283
     */
1282 1284
    int *slice_offset;
1283 1285

  
1284 1286
    /**
1285
     * error concealment flags.
1287
     * error concealment flags
1286 1288
     * - encoding: unused
1287
     * - decoding: set by user
1289
     * - decoding: Set by user.
1288 1290
     */
1289 1291
    int error_concealment;
1290 1292
#define FF_EC_GUESS_MVS   1
......
1294 1296
     * dsp_mask could be add used to disable unwanted CPU features
1295 1297
     * CPU features (i.e. MMX, SSE. ...)
1296 1298
     *
1297
     * with FORCE flag you may instead enable given CPU features
1298
     * (Dangerous: usable in case of misdetection, improper usage however will
1299
     * result into program crash)
1299
     * With the FORCE flag you may instead enable given CPU features.
1300
     * (Dangerous: Usable in case of misdetection, improper usage however will
1301
     * result into program crash.)
1300 1302
     */
1301 1303
    unsigned dsp_mask;
1302
#define FF_MM_FORCE    0x80000000 /* force usage of selected flags (OR) */
1304
#define FF_MM_FORCE    0x80000000 /* Force usage of selected flags (OR) */
1303 1305
    /* lower 16 bits - CPU features */
1304 1306
#ifdef HAVE_MMX
1305 1307
#define FF_MM_MMX      0x0001 /* standard MMX */
......
1315 1317

  
1316 1318
    /**
1317 1319
     * bits per sample/pixel from the demuxer (needed for huffyuv).
1318
     * - encoding: set by lavc
1319
     * - decoding: set by user
1320
     * - encoding: Set by libavcodec.
1321
     * - decoding: Set by user.
1320 1322
     */
1321 1323
     int bits_per_sample;
1322 1324

  
1323 1325
    /**
1324
     * prediction method (needed for huffyuv).
1325
     * - encoding: set by user
1326
     * prediction method (needed for huffyuv)
1327
     * - encoding: Set by user.
1326 1328
     * - decoding: unused
1327 1329
     */
1328 1330
     int prediction_method;
......
1331 1333
#define FF_PRED_MEDIAN 2
1332 1334

  
1333 1335
    /**
1334
     * sample aspect ratio (0 if unknown).
1335
     * numerator and denominator must be relative prime and smaller then 256 for some video standards
1336
     * - encoding: set by user.
1337
     * - decoding: set by lavc.
1336
     * sample aspect ratio (0 if unknown)
1337
     * Numerator and denominator must be relatively prime and smaller than 256 for some video standards.
1338
     * - encoding: Set by user.
1339
     * - decoding: Set by libavcodec.
1338 1340
     */
1339 1341
    AVRational sample_aspect_ratio;
1340 1342

  
1341 1343
    /**
1342
     * the picture in the bitstream.
1343
     * - encoding: set by lavc
1344
     * - decoding: set by lavc
1344
     * the picture in the bitstream
1345
     * - encoding: Set by libavcodec.
1346
     * - decoding: Set by libavcodec.
1345 1347
     */
1346 1348
    AVFrame *coded_frame;
1347 1349

  
1348 1350
    /**
1349
     * debug.
1350
     * - encoding: set by user.
1351
     * - decoding: set by user.
1351
     * debug
1352
     * - encoding: Set by user.
1353
     * - decoding: Set by user.
1352 1354
     */
1353 1355
    int debug;
1354 1356
#define FF_DEBUG_PICT_INFO 1
......
1368 1370
#define FF_DEBUG_VIS_MB_TYPE 0x00004000
1369 1371

  
1370 1372
    /**
1371
     * debug.
1372
     * - encoding: set by user.
1373
     * - decoding: set by user.
1373
     * debug
1374
     * - encoding: Set by user.
1375
     * - decoding: Set by user.
1374 1376
     */
1375 1377
    int debug_mv;
1376 1378
#define FF_DEBUG_VIS_MV_P_FOR  0x00000001 //visualize forward predicted MVs of P frames
......
1378 1380
#define FF_DEBUG_VIS_MV_B_BACK 0x00000004 //visualize backward predicted MVs of B frames
1379 1381

  
1380 1382
    /**
1381
     * error.
1382
     * - encoding: set by lavc if flags&CODEC_FLAG_PSNR
1383
     * error
1384
     * - encoding: Set by libavcodec if flags&CODEC_FLAG_PSNR.
1383 1385
     * - decoding: unused
1384 1386
     */
1385 1387
    uint64_t error[4];
1386 1388

  
1387 1389
    /**
1388
     * minimum MB quantizer.
1390
     * minimum MB quantizer
1389 1391
     * - encoding: unused
1390 1392
     * - decoding: unused
1391 1393
     */
1392 1394
    int mb_qmin;
1393 1395

  
1394 1396
    /**
1395
     * maximum MB quantizer.
1397
     * maximum MB quantizer
1396 1398
     * - encoding: unused
1397 1399
     * - decoding: unused
1398 1400
     */
1399 1401
    int mb_qmax;
1400 1402

  
1401 1403
    /**
1402
     * motion estimation compare function.
1403
     * - encoding: set by user.
1404
     * motion estimation comparison function
1405
     * - encoding: Set by user.
1404 1406
     * - decoding: unused
1405 1407
     */
1406 1408
    int me_cmp;
1407 1409
    /**
1408
     * subpixel motion estimation compare function.
1409
     * - encoding: set by user.
1410
     * subpixel motion estimation comparison function
1411
     * - encoding: Set by user.
1410 1412
     * - decoding: unused
1411 1413
     */
1412 1414
    int me_sub_cmp;
1413 1415
    /**
1414
     * macroblock compare function (not supported yet).
1415
     * - encoding: set by user.
1416
     * macroblock comparison function (not supported yet)
1417
     * - encoding: Set by user.
1416 1418
     * - decoding: unused
1417 1419
     */
1418 1420
    int mb_cmp;
1419 1421
    /**
1420
     * interlaced dct compare function
1421
     * - encoding: set by user.
1422
     * interlaced DCT comparison function
1423
     * - encoding: Set by user.
1422 1424
     * - decoding: unused
1423 1425
     */
1424 1426
    int ildct_cmp;
......
1440 1442
#define FF_CMP_CHROMA 256
1441 1443

  
1442 1444
    /**
1443
     * ME diamond size & shape.
1444
     * - encoding: set by user.
1445
     * ME diamond size & shape
1446
     * - encoding: Set by user.
1445 1447
     * - decoding: unused
1446 1448
     */
1447 1449
    int dia_size;
1448 1450

  
1449 1451
    /**
1450
     * amount of previous MV predictors (2a+1 x 2a+1 square).
1451
     * - encoding: set by user.
1452
     * amount of previous MV predictors (2a+1 x 2a+1 square)
1453
     * - encoding: Set by user.
1452 1454
     * - decoding: unused
1453 1455
     */
1454 1456
    int last_predictor_count;
1455 1457

  
1456 1458
    /**
1457
     * pre pass for motion estimation.
1458
     * - encoding: set by user.
1459
     * prepass for motion estimation
1460
     * - encoding: Set by user.
1459 1461
     * - decoding: unused
... This diff was truncated because it exceeds the maximum size that can be displayed.

Also available in: Unified diff