avcodec/anm: Don't unnecessarily use context variables
[ffmpeg.git] / libavcodec / avcodec.h
1 /*
2  * copyright (c) 2001 Fabrice Bellard
3  *
4  * This file is part of FFmpeg.
5  *
6  * FFmpeg is free software; you can redistribute it and/or
7  * modify it under the terms of the GNU Lesser General Public
8  * 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  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14  * Lesser General Public License for more details.
15  *
16  * 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 #ifndef AVCODEC_AVCODEC_H
22 #define AVCODEC_AVCODEC_H
23
24 /**
25  * @file
26  * @ingroup libavc
27  * 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/hwcontext.h"
40 #include "libavutil/log.h"
41 #include "libavutil/pixfmt.h"
42 #include "libavutil/rational.h"
43
44 #include "bsf.h"
45 #include "codec.h"
46 #include "codec_desc.h"
47 #include "codec_par.h"
48 #include "codec_id.h"
49 #include "packet.h"
50 #include "version.h"
51
52 /**
53  * @defgroup libavc libavcodec
54  * Encoding/Decoding Library
55  *
56  * @{
57  *
58  * @defgroup lavc_decoding Decoding
59  * @{
60  * @}
61  *
62  * @defgroup lavc_encoding Encoding
63  * @{
64  * @}
65  *
66  * @defgroup lavc_codec Codecs
67  * @{
68  * @defgroup lavc_codec_native Native Codecs
69  * @{
70  * @}
71  * @defgroup lavc_codec_wrappers External library wrappers
72  * @{
73  * @}
74  * @defgroup lavc_codec_hwaccel Hardware Accelerators bridge
75  * @{
76  * @}
77  * @}
78  * @defgroup lavc_internal Internal
79  * @{
80  * @}
81  * @}
82  */
83
84 /**
85  * @ingroup libavc
86  * @defgroup lavc_encdec send/receive encoding and decoding API overview
87  * @{
88  *
89  * The avcodec_send_packet()/avcodec_receive_frame()/avcodec_send_frame()/
90  * avcodec_receive_packet() functions provide an encode/decode API, which
91  * decouples input and output.
92  *
93  * The API is very similar for encoding/decoding and audio/video, and works as
94  * follows:
95  * - Set up and open the AVCodecContext as usual.
96  * - Send valid input:
97  *   - For decoding, call avcodec_send_packet() to give the decoder raw
98  *     compressed data in an AVPacket.
99  *   - For encoding, call avcodec_send_frame() to give the encoder an AVFrame
100  *     containing uncompressed audio or video.
101  *
102  *   In both cases, it is recommended that AVPackets and AVFrames are
103  *   refcounted, or libavcodec might have to copy the input data. (libavformat
104  *   always returns refcounted AVPackets, and av_frame_get_buffer() allocates
105  *   refcounted AVFrames.)
106  * - Receive output in a loop. Periodically call one of the avcodec_receive_*()
107  *   functions and process their output:
108  *   - For decoding, call avcodec_receive_frame(). On success, it will return
109  *     an AVFrame containing uncompressed audio or video data.
110  *   - For encoding, call avcodec_receive_packet(). On success, it will return
111  *     an AVPacket with a compressed frame.
112  *
113  *   Repeat this call until it returns AVERROR(EAGAIN) or an error. The
114  *   AVERROR(EAGAIN) return value means that new input data is required to
115  *   return new output. In this case, continue with sending input. For each
116  *   input frame/packet, the codec will typically return 1 output frame/packet,
117  *   but it can also be 0 or more than 1.
118  *
119  * At the beginning of decoding or encoding, the codec might accept multiple
120  * input frames/packets without returning a frame, until its internal buffers
121  * are filled. This situation is handled transparently if you follow the steps
122  * outlined above.
123  *
124  * In theory, sending input can result in EAGAIN - this should happen only if
125  * not all output was received. You can use this to structure alternative decode
126  * or encode loops other than the one suggested above. For example, you could
127  * try sending new input on each iteration, and try to receive output if that
128  * returns EAGAIN.
129  *
130  * End of stream situations. These require "flushing" (aka draining) the codec,
131  * as the codec might buffer multiple frames or packets internally for
132  * performance or out of necessity (consider B-frames).
133  * This is handled as follows:
134  * - Instead of valid input, send NULL to the avcodec_send_packet() (decoding)
135  *   or avcodec_send_frame() (encoding) functions. This will enter draining
136  *   mode.
137  * - Call avcodec_receive_frame() (decoding) or avcodec_receive_packet()
138  *   (encoding) in a loop until AVERROR_EOF is returned. The functions will
139  *   not return AVERROR(EAGAIN), unless you forgot to enter draining mode.
140  * - Before decoding can be resumed again, the codec has to be reset with
141  *   avcodec_flush_buffers().
142  *
143  * Using the API as outlined above is highly recommended. But it is also
144  * possible to call functions outside of this rigid schema. For example, you can
145  * call avcodec_send_packet() repeatedly without calling
146  * avcodec_receive_frame(). In this case, avcodec_send_packet() will succeed
147  * until the codec's internal buffer has been filled up (which is typically of
148  * size 1 per output frame, after initial input), and then reject input with
149  * AVERROR(EAGAIN). Once it starts rejecting input, you have no choice but to
150  * read at least some output.
151  *
152  * Not all codecs will follow a rigid and predictable dataflow; the only
153  * guarantee is that an AVERROR(EAGAIN) return value on a send/receive call on
154  * one end implies that a receive/send call on the other end will succeed, or
155  * at least will not fail with AVERROR(EAGAIN). In general, no codec will
156  * permit unlimited buffering of input or output.
157  *
158  * This API replaces the following legacy functions:
159  * - avcodec_decode_video2() and avcodec_decode_audio4():
160  *   Use avcodec_send_packet() to feed input to the decoder, then use
161  *   avcodec_receive_frame() to receive decoded frames after each packet.
162  *   Unlike with the old video decoding API, multiple frames might result from
163  *   a packet. For audio, splitting the input packet into frames by partially
164  *   decoding packets becomes transparent to the API user. You never need to
165  *   feed an AVPacket to the API twice (unless it is rejected with AVERROR(EAGAIN) - then
166  *   no data was read from the packet).
167  *   Additionally, sending a flush/draining packet is required only once.
168  * - avcodec_encode_video2()/avcodec_encode_audio2():
169  *   Use avcodec_send_frame() to feed input to the encoder, then use
170  *   avcodec_receive_packet() to receive encoded packets.
171  *   Providing user-allocated buffers for avcodec_receive_packet() is not
172  *   possible.
173  * - The new API does not handle subtitles yet.
174  *
175  * Mixing new and old function calls on the same AVCodecContext is not allowed,
176  * and will result in undefined behavior.
177  *
178  * Some codecs might require using the new API; using the old API will return
179  * an error when calling it. All codecs support the new API.
180  *
181  * A codec is not allowed to return AVERROR(EAGAIN) for both sending and receiving. This
182  * would be an invalid state, which could put the codec user into an endless
183  * loop. The API has no concept of time either: it cannot happen that trying to
184  * do avcodec_send_packet() results in AVERROR(EAGAIN), but a repeated call 1 second
185  * later accepts the packet (with no other receive/flush API calls involved).
186  * The API is a strict state machine, and the passage of time is not supposed
187  * to influence it. Some timing-dependent behavior might still be deemed
188  * acceptable in certain cases. But it must never result in both send/receive
189  * returning EAGAIN at the same time at any point. It must also absolutely be
190  * avoided that the current state is "unstable" and can "flip-flop" between
191  * the send/receive APIs allowing progress. For example, it's not allowed that
192  * the codec randomly decides that it actually wants to consume a packet now
193  * instead of returning a frame, after it just returned AVERROR(EAGAIN) on an
194  * avcodec_send_packet() call.
195  * @}
196  */
197
198 /**
199  * @defgroup lavc_core Core functions/structures.
200  * @ingroup libavc
201  *
202  * Basic definitions, functions for querying libavcodec capabilities,
203  * allocating core structures, etc.
204  * @{
205  */
206
207 /**
208  * @ingroup lavc_decoding
209  * Required number of additionally allocated bytes at the end of the input bitstream for decoding.
210  * This is mainly needed because some optimized bitstream readers read
211  * 32 or 64 bit at once and could read over the end.<br>
212  * Note: If the first 23 bits of the additional bytes are not 0, then damaged
213  * MPEG bitstreams could cause overread and segfault.
214  */
215 #define AV_INPUT_BUFFER_PADDING_SIZE 64
216
217 /**
218  * @ingroup lavc_encoding
219  * minimum encoding buffer size
220  * Used to avoid some checks during header writing.
221  */
222 #define AV_INPUT_BUFFER_MIN_SIZE 16384
223
224 /**
225  * @ingroup lavc_decoding
226  */
227 enum AVDiscard{
228     /* We leave some space between them for extensions (drop some
229      * keyframes for intra-only or drop just some bidir frames). */
230     AVDISCARD_NONE    =-16, ///< discard nothing
231     AVDISCARD_DEFAULT =  0, ///< discard useless packets like 0 size packets in avi
232     AVDISCARD_NONREF  =  8, ///< discard all non reference
233     AVDISCARD_BIDIR   = 16, ///< discard all bidirectional frames
234     AVDISCARD_NONINTRA= 24, ///< discard all non intra frames
235     AVDISCARD_NONKEY  = 32, ///< discard all frames except keyframes
236     AVDISCARD_ALL     = 48, ///< discard all
237 };
238
239 enum AVAudioServiceType {
240     AV_AUDIO_SERVICE_TYPE_MAIN              = 0,
241     AV_AUDIO_SERVICE_TYPE_EFFECTS           = 1,
242     AV_AUDIO_SERVICE_TYPE_VISUALLY_IMPAIRED = 2,
243     AV_AUDIO_SERVICE_TYPE_HEARING_IMPAIRED  = 3,
244     AV_AUDIO_SERVICE_TYPE_DIALOGUE          = 4,
245     AV_AUDIO_SERVICE_TYPE_COMMENTARY        = 5,
246     AV_AUDIO_SERVICE_TYPE_EMERGENCY         = 6,
247     AV_AUDIO_SERVICE_TYPE_VOICE_OVER        = 7,
248     AV_AUDIO_SERVICE_TYPE_KARAOKE           = 8,
249     AV_AUDIO_SERVICE_TYPE_NB                   , ///< Not part of ABI
250 };
251
252 /**
253  * @ingroup lavc_encoding
254  */
255 typedef struct RcOverride{
256     int start_frame;
257     int end_frame;
258     int qscale; // If this is 0 then quality_factor will be used instead.
259     float quality_factor;
260 } RcOverride;
261
262 /* encoding support
263    These flags can be passed in AVCodecContext.flags before initialization.
264    Note: Not everything is supported yet.
265 */
266
267 /**
268  * Allow decoders to produce frames with data planes that are not aligned
269  * to CPU requirements (e.g. due to cropping).
270  */
271 #define AV_CODEC_FLAG_UNALIGNED       (1 <<  0)
272 /**
273  * Use fixed qscale.
274  */
275 #define AV_CODEC_FLAG_QSCALE          (1 <<  1)
276 /**
277  * 4 MV per MB allowed / advanced prediction for H.263.
278  */
279 #define AV_CODEC_FLAG_4MV             (1 <<  2)
280 /**
281  * Output even those frames that might be corrupted.
282  */
283 #define AV_CODEC_FLAG_OUTPUT_CORRUPT  (1 <<  3)
284 /**
285  * Use qpel MC.
286  */
287 #define AV_CODEC_FLAG_QPEL            (1 <<  4)
288 /**
289  * Don't output frames whose parameters differ from first
290  * decoded frame in stream.
291  */
292 #define AV_CODEC_FLAG_DROPCHANGED     (1 <<  5)
293 /**
294  * Use internal 2pass ratecontrol in first pass mode.
295  */
296 #define AV_CODEC_FLAG_PASS1           (1 <<  9)
297 /**
298  * Use internal 2pass ratecontrol in second pass mode.
299  */
300 #define AV_CODEC_FLAG_PASS2           (1 << 10)
301 /**
302  * loop filter.
303  */
304 #define AV_CODEC_FLAG_LOOP_FILTER     (1 << 11)
305 /**
306  * Only decode/encode grayscale.
307  */
308 #define AV_CODEC_FLAG_GRAY            (1 << 13)
309 /**
310  * error[?] variables will be set during encoding.
311  */
312 #define AV_CODEC_FLAG_PSNR            (1 << 15)
313 /**
314  * Input bitstream might be truncated at a random location
315  * instead of only at frame boundaries.
316  */
317 #define AV_CODEC_FLAG_TRUNCATED       (1 << 16)
318 /**
319  * Use interlaced DCT.
320  */
321 #define AV_CODEC_FLAG_INTERLACED_DCT  (1 << 18)
322 /**
323  * Force low delay.
324  */
325 #define AV_CODEC_FLAG_LOW_DELAY       (1 << 19)
326 /**
327  * Place global headers in extradata instead of every keyframe.
328  */
329 #define AV_CODEC_FLAG_GLOBAL_HEADER   (1 << 22)
330 /**
331  * Use only bitexact stuff (except (I)DCT).
332  */
333 #define AV_CODEC_FLAG_BITEXACT        (1 << 23)
334 /* Fx : Flag for H.263+ extra options */
335 /**
336  * H.263 advanced intra coding / MPEG-4 AC prediction
337  */
338 #define AV_CODEC_FLAG_AC_PRED         (1 << 24)
339 /**
340  * interlaced motion estimation
341  */
342 #define AV_CODEC_FLAG_INTERLACED_ME   (1 << 29)
343 #define AV_CODEC_FLAG_CLOSED_GOP      (1U << 31)
344
345 /**
346  * Allow non spec compliant speedup tricks.
347  */
348 #define AV_CODEC_FLAG2_FAST           (1 <<  0)
349 /**
350  * Skip bitstream encoding.
351  */
352 #define AV_CODEC_FLAG2_NO_OUTPUT      (1 <<  2)
353 /**
354  * Place global headers at every keyframe instead of in extradata.
355  */
356 #define AV_CODEC_FLAG2_LOCAL_HEADER   (1 <<  3)
357
358 /**
359  * timecode is in drop frame format. DEPRECATED!!!!
360  */
361 #define AV_CODEC_FLAG2_DROP_FRAME_TIMECODE (1 << 13)
362
363 /**
364  * Input bitstream might be truncated at a packet boundaries
365  * instead of only at frame boundaries.
366  */
367 #define AV_CODEC_FLAG2_CHUNKS         (1 << 15)
368 /**
369  * Discard cropping information from SPS.
370  */
371 #define AV_CODEC_FLAG2_IGNORE_CROP    (1 << 16)
372
373 /**
374  * Show all frames before the first keyframe
375  */
376 #define AV_CODEC_FLAG2_SHOW_ALL       (1 << 22)
377 /**
378  * Export motion vectors through frame side data
379  */
380 #define AV_CODEC_FLAG2_EXPORT_MVS     (1 << 28)
381 /**
382  * Do not skip samples and export skip information as frame side data
383  */
384 #define AV_CODEC_FLAG2_SKIP_MANUAL    (1 << 29)
385 /**
386  * Do not reset ASS ReadOrder field on flush (subtitles decoding)
387  */
388 #define AV_CODEC_FLAG2_RO_FLUSH_NOOP  (1 << 30)
389
390 /* Unsupported options :
391  *              Syntax Arithmetic coding (SAC)
392  *              Reference Picture Selection
393  *              Independent Segment Decoding */
394 /* /Fx */
395 /* codec capabilities */
396
397 /* Exported side data.
398    These flags can be passed in AVCodecContext.export_side_data before initialization.
399 */
400 /**
401  * Export motion vectors through frame side data
402  */
403 #define AV_CODEC_EXPORT_DATA_MVS         (1 << 0)
404 /**
405  * Export encoder Producer Reference Time through packet side data
406  */
407 #define AV_CODEC_EXPORT_DATA_PRFT        (1 << 1)
408 /**
409  * Decoding only.
410  * Export the AVVideoEncParams structure through frame side data.
411  */
412 #define AV_CODEC_EXPORT_DATA_VIDEO_ENC_PARAMS (1 << 2)
413
414 /**
415  * Pan Scan area.
416  * This specifies the area which should be displayed.
417  * Note there may be multiple such areas for one frame.
418  */
419 typedef struct AVPanScan {
420     /**
421      * id
422      * - encoding: Set by user.
423      * - decoding: Set by libavcodec.
424      */
425     int id;
426
427     /**
428      * width and height in 1/16 pel
429      * - encoding: Set by user.
430      * - decoding: Set by libavcodec.
431      */
432     int width;
433     int height;
434
435     /**
436      * position of the top left corner in 1/16 pel for up to 3 fields/frames
437      * - encoding: Set by user.
438      * - decoding: Set by libavcodec.
439      */
440     int16_t position[3][2];
441 } AVPanScan;
442
443 /**
444  * This structure describes the bitrate properties of an encoded bitstream. It
445  * roughly corresponds to a subset the VBV parameters for MPEG-2 or HRD
446  * parameters for H.264/HEVC.
447  */
448 typedef struct AVCPBProperties {
449     /**
450      * Maximum bitrate of the stream, in bits per second.
451      * Zero if unknown or unspecified.
452      */
453 #if FF_API_UNSANITIZED_BITRATES
454     int max_bitrate;
455 #else
456     int64_t max_bitrate;
457 #endif
458     /**
459      * Minimum bitrate of the stream, in bits per second.
460      * Zero if unknown or unspecified.
461      */
462 #if FF_API_UNSANITIZED_BITRATES
463     int min_bitrate;
464 #else
465     int64_t min_bitrate;
466 #endif
467     /**
468      * Average bitrate of the stream, in bits per second.
469      * Zero if unknown or unspecified.
470      */
471 #if FF_API_UNSANITIZED_BITRATES
472     int avg_bitrate;
473 #else
474     int64_t avg_bitrate;
475 #endif
476
477     /**
478      * The size of the buffer to which the ratecontrol is applied, in bits.
479      * Zero if unknown or unspecified.
480      */
481     int buffer_size;
482
483     /**
484      * The delay between the time the packet this structure is associated with
485      * is received and the time when it should be decoded, in periods of a 27MHz
486      * clock.
487      *
488      * UINT64_MAX when unknown or unspecified.
489      */
490     uint64_t vbv_delay;
491 } AVCPBProperties;
492
493 /**
494  * This structure supplies correlation between a packet timestamp and a wall clock
495  * production time. The definition follows the Producer Reference Time ('prft')
496  * as defined in ISO/IEC 14496-12
497  */
498 typedef struct AVProducerReferenceTime {
499     /**
500      * A UTC timestamp, in microseconds, since Unix epoch (e.g, av_gettime()).
501      */
502     int64_t wallclock;
503     int flags;
504 } AVProducerReferenceTime;
505
506 /**
507  * The decoder will keep a reference to the frame and may reuse it later.
508  */
509 #define AV_GET_BUFFER_FLAG_REF (1 << 0)
510
511 struct AVCodecInternal;
512
513 /**
514  * main external API structure.
515  * New fields can be added to the end with minor version bumps.
516  * Removal, reordering and changes to existing fields require a major
517  * version bump.
518  * You can use AVOptions (av_opt* / av_set/get*()) to access these fields from user
519  * applications.
520  * The name string for AVOptions options matches the associated command line
521  * parameter name and can be found in libavcodec/options_table.h
522  * The AVOption/command line parameter names differ in some cases from the C
523  * structure field names for historic reasons or brevity.
524  * sizeof(AVCodecContext) must not be used outside libav*.
525  */
526 typedef struct AVCodecContext {
527     /**
528      * information on struct for av_log
529      * - set by avcodec_alloc_context3
530      */
531     const AVClass *av_class;
532     int log_level_offset;
533
534     enum AVMediaType codec_type; /* see AVMEDIA_TYPE_xxx */
535     const struct AVCodec  *codec;
536     enum AVCodecID     codec_id; /* see AV_CODEC_ID_xxx */
537
538     /**
539      * fourcc (LSB first, so "ABCD" -> ('D'<<24) + ('C'<<16) + ('B'<<8) + 'A').
540      * This is used to work around some encoder bugs.
541      * A demuxer should set this to what is stored in the field used to identify the codec.
542      * If there are multiple such fields in a container then the demuxer should choose the one
543      * which maximizes the information about the used codec.
544      * If the codec tag field in a container is larger than 32 bits then the demuxer should
545      * remap the longer ID to 32 bits with a table or other structure. Alternatively a new
546      * extra_codec_tag + size could be added but for this a clear advantage must be demonstrated
547      * first.
548      * - encoding: Set by user, if not then the default based on codec_id will be used.
549      * - decoding: Set by user, will be converted to uppercase by libavcodec during init.
550      */
551     unsigned int codec_tag;
552
553     void *priv_data;
554
555     /**
556      * Private context used for internal data.
557      *
558      * Unlike priv_data, this is not codec-specific. It is used in general
559      * libavcodec functions.
560      */
561     struct AVCodecInternal *internal;
562
563     /**
564      * Private data of the user, can be used to carry app specific stuff.
565      * - encoding: Set by user.
566      * - decoding: Set by user.
567      */
568     void *opaque;
569
570     /**
571      * the average bitrate
572      * - encoding: Set by user; unused for constant quantizer encoding.
573      * - decoding: Set by user, may be overwritten by libavcodec
574      *             if this info is available in the stream
575      */
576     int64_t bit_rate;
577
578     /**
579      * number of bits the bitstream is allowed to diverge from the reference.
580      *           the reference can be CBR (for CBR pass1) or VBR (for pass2)
581      * - encoding: Set by user; unused for constant quantizer encoding.
582      * - decoding: unused
583      */
584     int bit_rate_tolerance;
585
586     /**
587      * Global quality for codecs which cannot change it per frame.
588      * This should be proportional to MPEG-1/2/4 qscale.
589      * - encoding: Set by user.
590      * - decoding: unused
591      */
592     int global_quality;
593
594     /**
595      * - encoding: Set by user.
596      * - decoding: unused
597      */
598     int compression_level;
599 #define FF_COMPRESSION_DEFAULT -1
600
601     /**
602      * AV_CODEC_FLAG_*.
603      * - encoding: Set by user.
604      * - decoding: Set by user.
605      */
606     int flags;
607
608     /**
609      * AV_CODEC_FLAG2_*
610      * - encoding: Set by user.
611      * - decoding: Set by user.
612      */
613     int flags2;
614
615     /**
616      * some codecs need / can use extradata like Huffman tables.
617      * MJPEG: Huffman tables
618      * rv10: additional flags
619      * MPEG-4: global headers (they can be in the bitstream or here)
620      * The allocated memory should be AV_INPUT_BUFFER_PADDING_SIZE bytes larger
621      * than extradata_size to avoid problems if it is read with the bitstream reader.
622      * The bytewise contents of extradata must not depend on the architecture or CPU endianness.
623      * Must be allocated with the av_malloc() family of functions.
624      * - encoding: Set/allocated/freed by libavcodec.
625      * - decoding: Set/allocated/freed by user.
626      */
627     uint8_t *extradata;
628     int extradata_size;
629
630     /**
631      * This is the fundamental unit of time (in seconds) in terms
632      * of which frame timestamps are represented. For fixed-fps content,
633      * timebase should be 1/framerate and timestamp increments should be
634      * identically 1.
635      * This often, but not always is the inverse of the frame rate or field rate
636      * for video. 1/time_base is not the average frame rate if the frame rate is not
637      * constant.
638      *
639      * Like containers, elementary streams also can store timestamps, 1/time_base
640      * is the unit in which these timestamps are specified.
641      * As example of such codec time base see ISO/IEC 14496-2:2001(E)
642      * vop_time_increment_resolution and fixed_vop_rate
643      * (fixed_vop_rate == 0 implies that it is different from the framerate)
644      *
645      * - encoding: MUST be set by user.
646      * - decoding: the use of this field for decoding is deprecated.
647      *             Use framerate instead.
648      */
649     AVRational time_base;
650
651     /**
652      * For some codecs, the time base is closer to the field rate than the frame rate.
653      * Most notably, H.264 and MPEG-2 specify time_base as half of frame duration
654      * if no telecine is used ...
655      *
656      * Set to time_base ticks per frame. Default 1, e.g., H.264/MPEG-2 set it to 2.
657      */
658     int ticks_per_frame;
659
660     /**
661      * Codec delay.
662      *
663      * Encoding: Number of frames delay there will be from the encoder input to
664      *           the decoder output. (we assume the decoder matches the spec)
665      * Decoding: Number of frames delay in addition to what a standard decoder
666      *           as specified in the spec would produce.
667      *
668      * Video:
669      *   Number of frames the decoded output will be delayed relative to the
670      *   encoded input.
671      *
672      * Audio:
673      *   For encoding, this field is unused (see initial_padding).
674      *
675      *   For decoding, this is the number of samples the decoder needs to
676      *   output before the decoder's output is valid. When seeking, you should
677      *   start decoding this many samples prior to your desired seek point.
678      *
679      * - encoding: Set by libavcodec.
680      * - decoding: Set by libavcodec.
681      */
682     int delay;
683
684
685     /* video only */
686     /**
687      * picture width / height.
688      *
689      * @note Those fields may not match the values of the last
690      * AVFrame output by avcodec_decode_video2 due frame
691      * reordering.
692      *
693      * - encoding: MUST be set by user.
694      * - decoding: May be set by the user before opening the decoder if known e.g.
695      *             from the container. Some decoders will require the dimensions
696      *             to be set by the caller. During decoding, the decoder may
697      *             overwrite those values as required while parsing the data.
698      */
699     int width, height;
700
701     /**
702      * Bitstream width / height, may be different from width/height e.g. when
703      * the decoded frame is cropped before being output or lowres is enabled.
704      *
705      * @note Those field may not match the value of the last
706      * AVFrame output by avcodec_receive_frame() due frame
707      * reordering.
708      *
709      * - encoding: unused
710      * - decoding: May be set by the user before opening the decoder if known
711      *             e.g. from the container. During decoding, the decoder may
712      *             overwrite those values as required while parsing the data.
713      */
714     int coded_width, coded_height;
715
716     /**
717      * the number of pictures in a group of pictures, or 0 for intra_only
718      * - encoding: Set by user.
719      * - decoding: unused
720      */
721     int gop_size;
722
723     /**
724      * Pixel format, see AV_PIX_FMT_xxx.
725      * May be set by the demuxer if known from headers.
726      * May be overridden by the decoder if it knows better.
727      *
728      * @note This field may not match the value of the last
729      * AVFrame output by avcodec_receive_frame() due frame
730      * reordering.
731      *
732      * - encoding: Set by user.
733      * - decoding: Set by user if known, overridden by libavcodec while
734      *             parsing the data.
735      */
736     enum AVPixelFormat pix_fmt;
737
738     /**
739      * If non NULL, 'draw_horiz_band' is called by the libavcodec
740      * decoder to draw a horizontal band. It improves cache usage. Not
741      * all codecs can do that. You must check the codec capabilities
742      * beforehand.
743      * When multithreading is used, it may be called from multiple threads
744      * at the same time; threads might draw different parts of the same AVFrame,
745      * or multiple AVFrames, and there is no guarantee that slices will be drawn
746      * in order.
747      * The function is also used by hardware acceleration APIs.
748      * It is called at least once during frame decoding to pass
749      * the data needed for hardware render.
750      * In that mode instead of pixel data, AVFrame points to
751      * a structure specific to the acceleration API. The application
752      * reads the structure and can change some fields to indicate progress
753      * or mark state.
754      * - encoding: unused
755      * - decoding: Set by user.
756      * @param height the height of the slice
757      * @param y the y position of the slice
758      * @param type 1->top field, 2->bottom field, 3->frame
759      * @param offset offset into the AVFrame.data from which the slice should be read
760      */
761     void (*draw_horiz_band)(struct AVCodecContext *s,
762                             const AVFrame *src, int offset[AV_NUM_DATA_POINTERS],
763                             int y, int type, int height);
764
765     /**
766      * callback to negotiate the pixelFormat
767      * @param fmt is the list of formats which are supported by the codec,
768      * it is terminated by -1 as 0 is a valid format, the formats are ordered by quality.
769      * The first is always the native one.
770      * @note The callback may be called again immediately if initialization for
771      * the selected (hardware-accelerated) pixel format failed.
772      * @warning Behavior is undefined if the callback returns a value not
773      * in the fmt list of formats.
774      * @return the chosen format
775      * - encoding: unused
776      * - decoding: Set by user, if not set the native format will be chosen.
777      */
778     enum AVPixelFormat (*get_format)(struct AVCodecContext *s, const enum AVPixelFormat * fmt);
779
780     /**
781      * maximum number of B-frames between non-B-frames
782      * Note: The output will be delayed by max_b_frames+1 relative to the input.
783      * - encoding: Set by user.
784      * - decoding: unused
785      */
786     int max_b_frames;
787
788     /**
789      * qscale factor between IP and B-frames
790      * If > 0 then the last P-frame quantizer will be used (q= lastp_q*factor+offset).
791      * If < 0 then normal ratecontrol will be done (q= -normal_q*factor+offset).
792      * - encoding: Set by user.
793      * - decoding: unused
794      */
795     float b_quant_factor;
796
797 #if FF_API_PRIVATE_OPT
798     /** @deprecated use encoder private options instead */
799     attribute_deprecated
800     int b_frame_strategy;
801 #endif
802
803     /**
804      * qscale offset between IP and B-frames
805      * - encoding: Set by user.
806      * - decoding: unused
807      */
808     float b_quant_offset;
809
810     /**
811      * Size of the frame reordering buffer in the decoder.
812      * For MPEG-2 it is 1 IPB or 0 low delay IP.
813      * - encoding: Set by libavcodec.
814      * - decoding: Set by libavcodec.
815      */
816     int has_b_frames;
817
818 #if FF_API_PRIVATE_OPT
819     /** @deprecated use encoder private options instead */
820     attribute_deprecated
821     int mpeg_quant;
822 #endif
823
824     /**
825      * qscale factor between P- and I-frames
826      * If > 0 then the last P-frame quantizer will be used (q = lastp_q * factor + offset).
827      * If < 0 then normal ratecontrol will be done (q= -normal_q*factor+offset).
828      * - encoding: Set by user.
829      * - decoding: unused
830      */
831     float i_quant_factor;
832
833     /**
834      * qscale offset between P and I-frames
835      * - encoding: Set by user.
836      * - decoding: unused
837      */
838     float i_quant_offset;
839
840     /**
841      * luminance masking (0-> disabled)
842      * - encoding: Set by user.
843      * - decoding: unused
844      */
845     float lumi_masking;
846
847     /**
848      * temporary complexity masking (0-> disabled)
849      * - encoding: Set by user.
850      * - decoding: unused
851      */
852     float temporal_cplx_masking;
853
854     /**
855      * spatial complexity masking (0-> disabled)
856      * - encoding: Set by user.
857      * - decoding: unused
858      */
859     float spatial_cplx_masking;
860
861     /**
862      * p block masking (0-> disabled)
863      * - encoding: Set by user.
864      * - decoding: unused
865      */
866     float p_masking;
867
868     /**
869      * darkness masking (0-> disabled)
870      * - encoding: Set by user.
871      * - decoding: unused
872      */
873     float dark_masking;
874
875     /**
876      * slice count
877      * - encoding: Set by libavcodec.
878      * - decoding: Set by user (or 0).
879      */
880     int slice_count;
881
882 #if FF_API_PRIVATE_OPT
883     /** @deprecated use encoder private options instead */
884     attribute_deprecated
885      int prediction_method;
886 #define FF_PRED_LEFT   0
887 #define FF_PRED_PLANE  1
888 #define FF_PRED_MEDIAN 2
889 #endif
890
891     /**
892      * slice offsets in the frame in bytes
893      * - encoding: Set/allocated by libavcodec.
894      * - decoding: Set/allocated by user (or NULL).
895      */
896     int *slice_offset;
897
898     /**
899      * sample aspect ratio (0 if unknown)
900      * That is the width of a pixel divided by the height of the pixel.
901      * Numerator and denominator must be relatively prime and smaller than 256 for some video standards.
902      * - encoding: Set by user.
903      * - decoding: Set by libavcodec.
904      */
905     AVRational sample_aspect_ratio;
906
907     /**
908      * motion estimation comparison function
909      * - encoding: Set by user.
910      * - decoding: unused
911      */
912     int me_cmp;
913     /**
914      * subpixel motion estimation comparison function
915      * - encoding: Set by user.
916      * - decoding: unused
917      */
918     int me_sub_cmp;
919     /**
920      * macroblock comparison function (not supported yet)
921      * - encoding: Set by user.
922      * - decoding: unused
923      */
924     int mb_cmp;
925     /**
926      * interlaced DCT comparison function
927      * - encoding: Set by user.
928      * - decoding: unused
929      */
930     int ildct_cmp;
931 #define FF_CMP_SAD          0
932 #define FF_CMP_SSE          1
933 #define FF_CMP_SATD         2
934 #define FF_CMP_DCT          3
935 #define FF_CMP_PSNR         4
936 #define FF_CMP_BIT          5
937 #define FF_CMP_RD           6
938 #define FF_CMP_ZERO         7
939 #define FF_CMP_VSAD         8
940 #define FF_CMP_VSSE         9
941 #define FF_CMP_NSSE         10
942 #define FF_CMP_W53          11
943 #define FF_CMP_W97          12
944 #define FF_CMP_DCTMAX       13
945 #define FF_CMP_DCT264       14
946 #define FF_CMP_MEDIAN_SAD   15
947 #define FF_CMP_CHROMA       256
948
949     /**
950      * ME diamond size & shape
951      * - encoding: Set by user.
952      * - decoding: unused
953      */
954     int dia_size;
955
956     /**
957      * amount of previous MV predictors (2a+1 x 2a+1 square)
958      * - encoding: Set by user.
959      * - decoding: unused
960      */
961     int last_predictor_count;
962
963 #if FF_API_PRIVATE_OPT
964     /** @deprecated use encoder private options instead */
965     attribute_deprecated
966     int pre_me;
967 #endif
968
969     /**
970      * motion estimation prepass comparison function
971      * - encoding: Set by user.
972      * - decoding: unused
973      */
974     int me_pre_cmp;
975
976     /**
977      * ME prepass diamond size & shape
978      * - encoding: Set by user.
979      * - decoding: unused
980      */
981     int pre_dia_size;
982
983     /**
984      * subpel ME quality
985      * - encoding: Set by user.
986      * - decoding: unused
987      */
988     int me_subpel_quality;
989
990     /**
991      * maximum motion estimation search range in subpel units
992      * If 0 then no limit.
993      *
994      * - encoding: Set by user.
995      * - decoding: unused
996      */
997     int me_range;
998
999     /**
1000      * slice flags
1001      * - encoding: unused
1002      * - decoding: Set by user.
1003      */
1004     int slice_flags;
1005 #define SLICE_FLAG_CODED_ORDER    0x0001 ///< draw_horiz_band() is called in coded order instead of display
1006 #define SLICE_FLAG_ALLOW_FIELD    0x0002 ///< allow draw_horiz_band() with field slices (MPEG-2 field pics)
1007 #define SLICE_FLAG_ALLOW_PLANE    0x0004 ///< allow draw_horiz_band() with 1 component at a time (SVQ1)
1008
1009     /**
1010      * macroblock decision mode
1011      * - encoding: Set by user.
1012      * - decoding: unused
1013      */
1014     int mb_decision;
1015 #define FF_MB_DECISION_SIMPLE 0        ///< uses mb_cmp
1016 #define FF_MB_DECISION_BITS   1        ///< chooses the one which needs the fewest bits
1017 #define FF_MB_DECISION_RD     2        ///< rate distortion
1018
1019     /**
1020      * custom intra quantization matrix
1021      * Must be allocated with the av_malloc() family of functions, and will be freed in
1022      * avcodec_free_context().
1023      * - encoding: Set/allocated by user, freed by libavcodec. Can be NULL.
1024      * - decoding: Set/allocated/freed by libavcodec.
1025      */
1026     uint16_t *intra_matrix;
1027
1028     /**
1029      * custom inter quantization matrix
1030      * Must be allocated with the av_malloc() family of functions, and will be freed in
1031      * avcodec_free_context().
1032      * - encoding: Set/allocated by user, freed by libavcodec. Can be NULL.
1033      * - decoding: Set/allocated/freed by libavcodec.
1034      */
1035     uint16_t *inter_matrix;
1036
1037 #if FF_API_PRIVATE_OPT
1038     /** @deprecated use encoder private options instead */
1039     attribute_deprecated
1040     int scenechange_threshold;
1041
1042     /** @deprecated use encoder private options instead */
1043     attribute_deprecated
1044     int noise_reduction;
1045 #endif
1046
1047     /**
1048      * precision of the intra DC coefficient - 8
1049      * - encoding: Set by user.
1050      * - decoding: Set by libavcodec
1051      */
1052     int intra_dc_precision;
1053
1054     /**
1055      * Number of macroblock rows at the top which are skipped.
1056      * - encoding: unused
1057      * - decoding: Set by user.
1058      */
1059     int skip_top;
1060
1061     /**
1062      * Number of macroblock rows at the bottom which are skipped.
1063      * - encoding: unused
1064      * - decoding: Set by user.
1065      */
1066     int skip_bottom;
1067
1068     /**
1069      * minimum MB Lagrange multiplier
1070      * - encoding: Set by user.
1071      * - decoding: unused
1072      */
1073     int mb_lmin;
1074
1075     /**
1076      * maximum MB Lagrange multiplier
1077      * - encoding: Set by user.
1078      * - decoding: unused
1079      */
1080     int mb_lmax;
1081
1082 #if FF_API_PRIVATE_OPT
1083     /**
1084      * @deprecated use encoder private options instead
1085      */
1086     attribute_deprecated
1087     int me_penalty_compensation;
1088 #endif
1089
1090     /**
1091      * - encoding: Set by user.
1092      * - decoding: unused
1093      */
1094     int bidir_refine;
1095
1096 #if FF_API_PRIVATE_OPT
1097     /** @deprecated use encoder private options instead */
1098     attribute_deprecated
1099     int brd_scale;
1100 #endif
1101
1102     /**
1103      * minimum GOP size
1104      * - encoding: Set by user.
1105      * - decoding: unused
1106      */
1107     int keyint_min;
1108
1109     /**
1110      * number of reference frames
1111      * - encoding: Set by user.
1112      * - decoding: Set by lavc.
1113      */
1114     int refs;
1115
1116 #if FF_API_PRIVATE_OPT
1117     /** @deprecated use encoder private options instead */
1118     attribute_deprecated
1119     int chromaoffset;
1120 #endif
1121
1122     /**
1123      * Note: Value depends upon the compare function used for fullpel ME.
1124      * - encoding: Set by user.
1125      * - decoding: unused
1126      */
1127     int mv0_threshold;
1128
1129 #if FF_API_PRIVATE_OPT
1130     /** @deprecated use encoder private options instead */
1131     attribute_deprecated
1132     int b_sensitivity;
1133 #endif
1134
1135     /**
1136      * Chromaticity coordinates of the source primaries.
1137      * - encoding: Set by user
1138      * - decoding: Set by libavcodec
1139      */
1140     enum AVColorPrimaries color_primaries;
1141
1142     /**
1143      * Color Transfer Characteristic.
1144      * - encoding: Set by user
1145      * - decoding: Set by libavcodec
1146      */
1147     enum AVColorTransferCharacteristic color_trc;
1148
1149     /**
1150      * YUV colorspace type.
1151      * - encoding: Set by user
1152      * - decoding: Set by libavcodec
1153      */
1154     enum AVColorSpace colorspace;
1155
1156     /**
1157      * MPEG vs JPEG YUV range.
1158      * - encoding: Set by user
1159      * - decoding: Set by libavcodec
1160      */
1161     enum AVColorRange color_range;
1162
1163     /**
1164      * This defines the location of chroma samples.
1165      * - encoding: Set by user
1166      * - decoding: Set by libavcodec
1167      */
1168     enum AVChromaLocation chroma_sample_location;
1169
1170     /**
1171      * Number of slices.
1172      * Indicates number of picture subdivisions. Used for parallelized
1173      * decoding.
1174      * - encoding: Set by user
1175      * - decoding: unused
1176      */
1177     int slices;
1178
1179     /** Field order
1180      * - encoding: set by libavcodec
1181      * - decoding: Set by user.
1182      */
1183     enum AVFieldOrder field_order;
1184
1185     /* audio only */
1186     int sample_rate; ///< samples per second
1187     int channels;    ///< number of audio channels
1188
1189     /**
1190      * audio sample format
1191      * - encoding: Set by user.
1192      * - decoding: Set by libavcodec.
1193      */
1194     enum AVSampleFormat sample_fmt;  ///< sample format
1195
1196     /* The following data should not be initialized. */
1197     /**
1198      * Number of samples per channel in an audio frame.
1199      *
1200      * - encoding: set by libavcodec in avcodec_open2(). Each submitted frame
1201      *   except the last must contain exactly frame_size samples per channel.
1202      *   May be 0 when the codec has AV_CODEC_CAP_VARIABLE_FRAME_SIZE set, then the
1203      *   frame size is not restricted.
1204      * - decoding: may be set by some decoders to indicate constant frame size
1205      */
1206     int frame_size;
1207
1208     /**
1209      * Frame counter, set by libavcodec.
1210      *
1211      * - decoding: total number of frames returned from the decoder so far.
1212      * - encoding: total number of frames passed to the encoder so far.
1213      *
1214      *   @note the counter is not incremented if encoding/decoding resulted in
1215      *   an error.
1216      */
1217     int frame_number;
1218
1219     /**
1220      * number of bytes per packet if constant and known or 0
1221      * Used by some WAV based audio codecs.
1222      */
1223     int block_align;
1224
1225     /**
1226      * Audio cutoff bandwidth (0 means "automatic")
1227      * - encoding: Set by user.
1228      * - decoding: unused
1229      */
1230     int cutoff;
1231
1232     /**
1233      * Audio channel layout.
1234      * - encoding: set by user.
1235      * - decoding: set by user, may be overwritten by libavcodec.
1236      */
1237     uint64_t channel_layout;
1238
1239     /**
1240      * Request decoder to use this channel layout if it can (0 for default)
1241      * - encoding: unused
1242      * - decoding: Set by user.
1243      */
1244     uint64_t request_channel_layout;
1245
1246     /**
1247      * Type of service that the audio stream conveys.
1248      * - encoding: Set by user.
1249      * - decoding: Set by libavcodec.
1250      */
1251     enum AVAudioServiceType audio_service_type;
1252
1253     /**
1254      * desired sample format
1255      * - encoding: Not used.
1256      * - decoding: Set by user.
1257      * Decoder will decode to this format if it can.
1258      */
1259     enum AVSampleFormat request_sample_fmt;
1260
1261     /**
1262      * This callback is called at the beginning of each frame to get data
1263      * buffer(s) for it. There may be one contiguous buffer for all the data or
1264      * there may be a buffer per each data plane or anything in between. What
1265      * this means is, you may set however many entries in buf[] you feel necessary.
1266      * Each buffer must be reference-counted using the AVBuffer API (see description
1267      * of buf[] below).
1268      *
1269      * The following fields will be set in the frame before this callback is
1270      * called:
1271      * - format
1272      * - width, height (video only)
1273      * - sample_rate, channel_layout, nb_samples (audio only)
1274      * Their values may differ from the corresponding values in
1275      * AVCodecContext. This callback must use the frame values, not the codec
1276      * context values, to calculate the required buffer size.
1277      *
1278      * This callback must fill the following fields in the frame:
1279      * - data[]
1280      * - linesize[]
1281      * - extended_data:
1282      *   * if the data is planar audio with more than 8 channels, then this
1283      *     callback must allocate and fill extended_data to contain all pointers
1284      *     to all data planes. data[] must hold as many pointers as it can.
1285      *     extended_data must be allocated with av_malloc() and will be freed in
1286      *     av_frame_unref().
1287      *   * otherwise extended_data must point to data
1288      * - buf[] must contain one or more pointers to AVBufferRef structures. Each of
1289      *   the frame's data and extended_data pointers must be contained in these. That
1290      *   is, one AVBufferRef for each allocated chunk of memory, not necessarily one
1291      *   AVBufferRef per data[] entry. See: av_buffer_create(), av_buffer_alloc(),
1292      *   and av_buffer_ref().
1293      * - extended_buf and nb_extended_buf must be allocated with av_malloc() by
1294      *   this callback and filled with the extra buffers if there are more
1295      *   buffers than buf[] can hold. extended_buf will be freed in
1296      *   av_frame_unref().
1297      *
1298      * If AV_CODEC_CAP_DR1 is not set then get_buffer2() must call
1299      * avcodec_default_get_buffer2() instead of providing buffers allocated by
1300      * some other means.
1301      *
1302      * Each data plane must be aligned to the maximum required by the target
1303      * CPU.
1304      *
1305      * @see avcodec_default_get_buffer2()
1306      *
1307      * Video:
1308      *
1309      * If AV_GET_BUFFER_FLAG_REF is set in flags then the frame may be reused
1310      * (read and/or written to if it is writable) later by libavcodec.
1311      *
1312      * avcodec_align_dimensions2() should be used to find the required width and
1313      * height, as they normally need to be rounded up to the next multiple of 16.
1314      *
1315      * Some decoders do not support linesizes changing between frames.
1316      *
1317      * If frame multithreading is used and thread_safe_callbacks is set,
1318      * this callback may be called from a different thread, but not from more
1319      * than one at once. Does not need to be reentrant.
1320      *
1321      * @see avcodec_align_dimensions2()
1322      *
1323      * Audio:
1324      *
1325      * Decoders request a buffer of a particular size by setting
1326      * AVFrame.nb_samples prior to calling get_buffer2(). The decoder may,
1327      * however, utilize only part of the buffer by setting AVFrame.nb_samples
1328      * to a smaller value in the output frame.
1329      *
1330      * As a convenience, av_samples_get_buffer_size() and
1331      * av_samples_fill_arrays() in libavutil may be used by custom get_buffer2()
1332      * functions to find the required data size and to fill data pointers and
1333      * linesize. In AVFrame.linesize, only linesize[0] may be set for audio
1334      * since all planes must be the same size.
1335      *
1336      * @see av_samples_get_buffer_size(), av_samples_fill_arrays()
1337      *
1338      * - encoding: unused
1339      * - decoding: Set by libavcodec, user can override.
1340      */
1341     int (*get_buffer2)(struct AVCodecContext *s, AVFrame *frame, int flags);
1342
1343     /**
1344      * If non-zero, the decoded audio and video frames returned from
1345      * avcodec_decode_video2() and avcodec_decode_audio4() are reference-counted
1346      * and are valid indefinitely. The caller must free them with
1347      * av_frame_unref() when they are not needed anymore.
1348      * Otherwise, the decoded frames must not be freed by the caller and are
1349      * only valid until the next decode call.
1350      *
1351      * This is always automatically enabled if avcodec_receive_frame() is used.
1352      *
1353      * - encoding: unused
1354      * - decoding: set by the caller before avcodec_open2().
1355      */
1356     attribute_deprecated
1357     int refcounted_frames;
1358
1359     /* - encoding parameters */
1360     float qcompress;  ///< amount of qscale change between easy & hard scenes (0.0-1.0)
1361     float qblur;      ///< amount of qscale smoothing over time (0.0-1.0)
1362
1363     /**
1364      * minimum quantizer
1365      * - encoding: Set by user.
1366      * - decoding: unused
1367      */
1368     int qmin;
1369
1370     /**
1371      * maximum quantizer
1372      * - encoding: Set by user.
1373      * - decoding: unused
1374      */
1375     int qmax;
1376
1377     /**
1378      * maximum quantizer difference between frames
1379      * - encoding: Set by user.
1380      * - decoding: unused
1381      */
1382     int max_qdiff;
1383
1384     /**
1385      * decoder bitstream buffer size
1386      * - encoding: Set by user.
1387      * - decoding: unused
1388      */
1389     int rc_buffer_size;
1390
1391     /**
1392      * ratecontrol override, see RcOverride
1393      * - encoding: Allocated/set/freed by user.
1394      * - decoding: unused
1395      */
1396     int rc_override_count;
1397     RcOverride *rc_override;
1398
1399     /**
1400      * maximum bitrate
1401      * - encoding: Set by user.
1402      * - decoding: Set by user, may be overwritten by libavcodec.
1403      */
1404     int64_t rc_max_rate;
1405
1406     /**
1407      * minimum bitrate
1408      * - encoding: Set by user.
1409      * - decoding: unused
1410      */
1411     int64_t rc_min_rate;
1412
1413     /**
1414      * Ratecontrol attempt to use, at maximum, <value> of what can be used without an underflow.
1415      * - encoding: Set by user.
1416      * - decoding: unused.
1417      */
1418     float rc_max_available_vbv_use;
1419
1420     /**
1421      * Ratecontrol attempt to use, at least, <value> times the amount needed to prevent a vbv overflow.
1422      * - encoding: Set by user.
1423      * - decoding: unused.
1424      */
1425     float rc_min_vbv_overflow_use;
1426
1427     /**
1428      * Number of bits which should be loaded into the rc buffer before decoding starts.
1429      * - encoding: Set by user.
1430      * - decoding: unused
1431      */
1432     int rc_initial_buffer_occupancy;
1433
1434 #if FF_API_CODER_TYPE
1435 #define FF_CODER_TYPE_VLC       0
1436 #define FF_CODER_TYPE_AC        1
1437 #define FF_CODER_TYPE_RAW       2
1438 #define FF_CODER_TYPE_RLE       3
1439     /**
1440      * @deprecated use encoder private options instead
1441      */
1442     attribute_deprecated
1443     int coder_type;
1444 #endif /* FF_API_CODER_TYPE */
1445
1446 #if FF_API_PRIVATE_OPT
1447     /** @deprecated use encoder private options instead */
1448     attribute_deprecated
1449     int context_model;
1450 #endif
1451
1452 #if FF_API_PRIVATE_OPT
1453     /** @deprecated use encoder private options instead */
1454     attribute_deprecated
1455     int frame_skip_threshold;
1456
1457     /** @deprecated use encoder private options instead */
1458     attribute_deprecated
1459     int frame_skip_factor;
1460
1461     /** @deprecated use encoder private options instead */
1462     attribute_deprecated
1463     int frame_skip_exp;
1464
1465     /** @deprecated use encoder private options instead */
1466     attribute_deprecated
1467     int frame_skip_cmp;
1468 #endif /* FF_API_PRIVATE_OPT */
1469
1470     /**
1471      * trellis RD quantization
1472      * - encoding: Set by user.
1473      * - decoding: unused
1474      */
1475     int trellis;
1476
1477 #if FF_API_PRIVATE_OPT
1478     /** @deprecated use encoder private options instead */
1479     attribute_deprecated
1480     int min_prediction_order;
1481
1482     /** @deprecated use encoder private options instead */
1483     attribute_deprecated
1484     int max_prediction_order;
1485
1486     /** @deprecated use encoder private options instead */
1487     attribute_deprecated
1488     int64_t timecode_frame_start;
1489 #endif
1490
1491 #if FF_API_RTP_CALLBACK
1492     /**
1493      * @deprecated unused
1494      */
1495     /* The RTP callback: This function is called    */
1496     /* every time the encoder has a packet to send. */
1497     /* It depends on the encoder if the data starts */
1498     /* with a Start Code (it should). H.263 does.   */
1499     /* mb_nb contains the number of macroblocks     */
1500     /* encoded in the RTP payload.                  */
1501     attribute_deprecated
1502     void (*rtp_callback)(struct AVCodecContext *avctx, void *data, int size, int mb_nb);
1503 #endif
1504
1505 #if FF_API_PRIVATE_OPT
1506     /** @deprecated use encoder private options instead */
1507     attribute_deprecated
1508     int rtp_payload_size;   /* The size of the RTP payload: the coder will  */
1509                             /* do its best to deliver a chunk with size     */
1510                             /* below rtp_payload_size, the chunk will start */
1511                             /* with a start code on some codecs like H.263. */
1512                             /* This doesn't take account of any particular  */
1513                             /* headers inside the transmitted RTP payload.  */
1514 #endif
1515
1516 #if FF_API_STAT_BITS
1517     /* statistics, used for 2-pass encoding */
1518     attribute_deprecated
1519     int mv_bits;
1520     attribute_deprecated
1521     int header_bits;
1522     attribute_deprecated
1523     int i_tex_bits;
1524     attribute_deprecated
1525     int p_tex_bits;
1526     attribute_deprecated
1527     int i_count;
1528     attribute_deprecated
1529     int p_count;
1530     attribute_deprecated
1531     int skip_count;
1532     attribute_deprecated
1533     int misc_bits;
1534
1535     /** @deprecated this field is unused */
1536     attribute_deprecated
1537     int frame_bits;
1538 #endif
1539
1540     /**
1541      * pass1 encoding statistics output buffer
1542      * - encoding: Set by libavcodec.
1543      * - decoding: unused
1544      */
1545     char *stats_out;
1546
1547     /**
1548      * pass2 encoding statistics input buffer
1549      * Concatenated stuff from stats_out of pass1 should be placed here.
1550      * - encoding: Allocated/set/freed by user.
1551      * - decoding: unused
1552      */
1553     char *stats_in;
1554
1555     /**
1556      * Work around bugs in encoders which sometimes cannot be detected automatically.
1557      * - encoding: Set by user
1558      * - decoding: Set by user
1559      */
1560     int workaround_bugs;
1561 #define FF_BUG_AUTODETECT       1  ///< autodetection
1562 #define FF_BUG_XVID_ILACE       4
1563 #define FF_BUG_UMP4             8
1564 #define FF_BUG_NO_PADDING       16
1565 #define FF_BUG_AMV              32
1566 #define FF_BUG_QPEL_CHROMA      64
1567 #define FF_BUG_STD_QPEL         128
1568 #define FF_BUG_QPEL_CHROMA2     256
1569 #define FF_BUG_DIRECT_BLOCKSIZE 512
1570 #define FF_BUG_EDGE             1024
1571 #define FF_BUG_HPEL_CHROMA      2048
1572 #define FF_BUG_DC_CLIP          4096
1573 #define FF_BUG_MS               8192 ///< Work around various bugs in Microsoft's broken decoders.
1574 #define FF_BUG_TRUNCATED       16384
1575 #define FF_BUG_IEDGE           32768
1576
1577     /**
1578      * strictly follow the standard (MPEG-4, ...).
1579      * - encoding: Set by user.
1580      * - decoding: Set by user.
1581      * Setting this to STRICT or higher means the encoder and decoder will
1582      * generally do stupid things, whereas setting it to unofficial or lower
1583      * will mean the encoder might produce output that is not supported by all
1584      * spec-compliant decoders. Decoders don't differentiate between normal,
1585      * unofficial and experimental (that is, they always try to decode things
1586      * when they can) unless they are explicitly asked to behave stupidly
1587      * (=strictly conform to the specs)
1588      */
1589     int strict_std_compliance;
1590 #define FF_COMPLIANCE_VERY_STRICT   2 ///< Strictly conform to an older more strict version of the spec or reference software.
1591 #define FF_COMPLIANCE_STRICT        1 ///< Strictly conform to all the things in the spec no matter what consequences.
1592 #define FF_COMPLIANCE_NORMAL        0
1593 #define FF_COMPLIANCE_UNOFFICIAL   -1 ///< Allow unofficial extensions
1594 #define FF_COMPLIANCE_EXPERIMENTAL -2 ///< Allow nonstandardized experimental things.
1595
1596     /**
1597      * error concealment flags
1598      * - encoding: unused
1599      * - decoding: Set by user.
1600      */
1601     int error_concealment;
1602 #define FF_EC_GUESS_MVS   1
1603 #define FF_EC_DEBLOCK     2
1604 #define FF_EC_FAVOR_INTER 256
1605
1606     /**
1607      * debug
1608      * - encoding: Set by user.
1609      * - decoding: Set by user.
1610      */
1611     int debug;
1612 #define FF_DEBUG_PICT_INFO   1
1613 #define FF_DEBUG_RC          2
1614 #define FF_DEBUG_BITSTREAM   4
1615 #define FF_DEBUG_MB_TYPE     8
1616 #define FF_DEBUG_QP          16
1617 #if FF_API_DEBUG_MV
1618 /**
1619  * @deprecated this option does nothing
1620  */
1621 #define FF_DEBUG_MV          32
1622 #endif
1623 #define FF_DEBUG_DCT_COEFF   0x00000040
1624 #define FF_DEBUG_SKIP        0x00000080
1625 #define FF_DEBUG_STARTCODE   0x00000100
1626 #define FF_DEBUG_ER          0x00000400
1627 #define FF_DEBUG_MMCO        0x00000800
1628 #define FF_DEBUG_BUGS        0x00001000
1629 #if FF_API_DEBUG_MV
1630 #define FF_DEBUG_VIS_QP      0x00002000
1631 #define FF_DEBUG_VIS_MB_TYPE 0x00004000
1632 #endif
1633 #define FF_DEBUG_BUFFERS     0x00008000
1634 #define FF_DEBUG_THREADS     0x00010000
1635 #define FF_DEBUG_GREEN_MD    0x00800000
1636 #define FF_DEBUG_NOMC        0x01000000
1637
1638 #if FF_API_DEBUG_MV
1639     /**
1640      * debug
1641      * - encoding: Set by user.
1642      * - decoding: Set by user.
1643      */
1644     int debug_mv;
1645 #define FF_DEBUG_VIS_MV_P_FOR  0x00000001 // visualize forward predicted MVs of P-frames
1646 #define FF_DEBUG_VIS_MV_B_FOR  0x00000002 // visualize forward predicted MVs of B-frames
1647 #define FF_DEBUG_VIS_MV_B_BACK 0x00000004 // visualize backward predicted MVs of B-frames
1648 #endif
1649
1650     /**
1651      * Error recognition; may misdetect some more or less valid parts as errors.
1652      * - encoding: unused
1653      * - decoding: Set by user.
1654      */
1655     int err_recognition;
1656
1657 /**
1658  * Verify checksums embedded in the bitstream (could be of either encoded or
1659  * decoded data, depending on the codec) and print an error message on mismatch.
1660  * If AV_EF_EXPLODE is also set, a mismatching checksum will result in the
1661  * decoder returning an error.
1662  */
1663 #define AV_EF_CRCCHECK  (1<<0)
1664 #define AV_EF_BITSTREAM (1<<1)          ///< detect bitstream specification deviations
1665 #define AV_EF_BUFFER    (1<<2)          ///< detect improper bitstream length
1666 #define AV_EF_EXPLODE   (1<<3)          ///< abort decoding on minor error detection
1667
1668 #define AV_EF_IGNORE_ERR (1<<15)        ///< ignore errors and continue
1669 #define AV_EF_CAREFUL    (1<<16)        ///< consider things that violate the spec, are fast to calculate and have not been seen in the wild as errors
1670 #define AV_EF_COMPLIANT  (1<<17)        ///< consider all spec non compliances as errors
1671 #define AV_EF_AGGRESSIVE (1<<18)        ///< consider things that a sane encoder should not do as an error
1672
1673
1674     /**
1675      * opaque 64-bit number (generally a PTS) that will be reordered and
1676      * output in AVFrame.reordered_opaque
1677      * - encoding: Set by libavcodec to the reordered_opaque of the input
1678      *             frame corresponding to the last returned packet. Only
1679      *             supported by encoders with the
1680      *             AV_CODEC_CAP_ENCODER_REORDERED_OPAQUE capability.
1681      * - decoding: Set by user.
1682      */
1683     int64_t reordered_opaque;
1684
1685     /**
1686      * Hardware accelerator in use
1687      * - encoding: unused.
1688      * - decoding: Set by libavcodec
1689      */
1690     const struct AVHWAccel *hwaccel;
1691
1692     /**
1693      * Hardware accelerator context.
1694      * For some hardware accelerators, a global context needs to be
1695      * provided by the user. In that case, this holds display-dependent
1696      * data FFmpeg cannot instantiate itself. Please refer to the
1697      * FFmpeg HW accelerator documentation to know how to fill this
1698      * is. e.g. for VA API, this is a struct vaapi_context.
1699      * - encoding: unused
1700      * - decoding: Set by user
1701      */
1702     void *hwaccel_context;
1703
1704     /**
1705      * error
1706      * - encoding: Set by libavcodec if flags & AV_CODEC_FLAG_PSNR.
1707      * - decoding: unused
1708      */
1709     uint64_t error[AV_NUM_DATA_POINTERS];
1710
1711     /**
1712      * DCT algorithm, see FF_DCT_* below
1713      * - encoding: Set by user.
1714      * - decoding: unused
1715      */
1716     int dct_algo;
1717 #define FF_DCT_AUTO    0
1718 #define FF_DCT_FASTINT 1
1719 #define FF_DCT_INT     2
1720 #define FF_DCT_MMX     3
1721 #define FF_DCT_ALTIVEC 5
1722 #define FF_DCT_FAAN    6
1723
1724     /**
1725      * IDCT algorithm, see FF_IDCT_* below.
1726      * - encoding: Set by user.
1727      * - decoding: Set by user.
1728      */
1729     int idct_algo;
1730 #define FF_IDCT_AUTO          0
1731 #define FF_IDCT_INT           1
1732 #define FF_IDCT_SIMPLE        2
1733 #define FF_IDCT_SIMPLEMMX     3
1734 #define FF_IDCT_ARM           7
1735 #define FF_IDCT_ALTIVEC       8
1736 #define FF_IDCT_SIMPLEARM     10
1737 #define FF_IDCT_XVID          14
1738 #define FF_IDCT_SIMPLEARMV5TE 16
1739 #define FF_IDCT_SIMPLEARMV6   17
1740 #define FF_IDCT_FAAN          20
1741 #define FF_IDCT_SIMPLENEON    22
1742 #define FF_IDCT_NONE          24 /* Used by XvMC to extract IDCT coefficients with FF_IDCT_PERM_NONE */
1743 #define FF_IDCT_SIMPLEAUTO    128
1744
1745     /**
1746      * bits per sample/pixel from the demuxer (needed for huffyuv).
1747      * - encoding: Set by libavcodec.
1748      * - decoding: Set by user.
1749      */
1750      int bits_per_coded_sample;
1751
1752     /**
1753      * Bits per sample/pixel of internal libavcodec pixel/sample format.
1754      * - encoding: set by user.
1755      * - decoding: set by libavcodec.
1756      */
1757     int bits_per_raw_sample;
1758
1759 #if FF_API_LOWRES
1760     /**
1761      * low resolution decoding, 1-> 1/2 size, 2->1/4 size
1762      * - encoding: unused
1763      * - decoding: Set by user.
1764      */
1765      int lowres;
1766 #endif
1767
1768 #if FF_API_CODED_FRAME
1769     /**
1770      * the picture in the bitstream
1771      * - encoding: Set by libavcodec.
1772      * - decoding: unused
1773      *
1774      * @deprecated use the quality factor packet side data instead
1775      */
1776     attribute_deprecated AVFrame *coded_frame;
1777 #endif
1778
1779     /**
1780      * thread count
1781      * is used to decide how many independent tasks should be passed to execute()
1782      * - encoding: Set by user.
1783      * - decoding: Set by user.
1784      */
1785     int thread_count;
1786
1787     /**
1788      * Which multithreading methods to use.
1789      * Use of FF_THREAD_FRAME will increase decoding delay by one frame per thread,
1790      * so clients which cannot provide future frames should not use it.
1791      *
1792      * - encoding: Set by user, otherwise the default is used.
1793      * - decoding: Set by user, otherwise the default is used.
1794      */
1795     int thread_type;
1796 #define FF_THREAD_FRAME   1 ///< Decode more than one frame at once
1797 #define FF_THREAD_SLICE   2 ///< Decode more than one part of a single frame at once
1798
1799     /**
1800      * Which multithreading methods are in use by the codec.
1801      * - encoding: Set by libavcodec.
1802      * - decoding: Set by libavcodec.
1803      */
1804     int active_thread_type;
1805
1806     /**
1807      * Set by the client if its custom get_buffer() callback can be called
1808      * synchronously from another thread, which allows faster multithreaded decoding.
1809      * draw_horiz_band() will be called from other threads regardless of this setting.
1810      * Ignored if the default get_buffer() is used.
1811      * - encoding: Set by user.
1812      * - decoding: Set by user.
1813      */
1814     int thread_safe_callbacks;
1815
1816     /**
1817      * The codec may call this to execute several independent things.
1818      * It will return only after finishing all tasks.
1819      * The user may replace this with some multithreaded implementation,
1820      * the default implementation will execute the parts serially.
1821      * @param count the number of things to execute
1822      * - encoding: Set by libavcodec, user can override.
1823      * - decoding: Set by libavcodec, user can override.
1824      */
1825     int (*execute)(struct AVCodecContext *c, int (*func)(struct AVCodecContext *c2, void *arg), void *arg2, int *ret, int count, int size);
1826
1827     /**
1828      * The codec may call this to execute several independent things.
1829      * It will return only after finishing all tasks.
1830      * The user may replace this with some multithreaded implementation,
1831      * the default implementation will execute the parts serially.
1832      * Also see avcodec_thread_init and e.g. the --enable-pthread configure option.
1833      * @param c context passed also to func
1834      * @param count the number of things to execute
1835      * @param arg2 argument passed unchanged to func
1836      * @param ret return values of executed functions, must have space for "count" values. May be NULL.
1837      * @param func function that will be called count times, with jobnr from 0 to count-1.
1838      *             threadnr will be in the range 0 to c->thread_count-1 < MAX_THREADS and so that no
1839      *             two instances of func executing at the same time will have the same threadnr.
1840      * @return always 0 currently, but code should handle a future improvement where when any call to func
1841      *         returns < 0 no further calls to func may be done and < 0 is returned.
1842      * - encoding: Set by libavcodec, user can override.
1843      * - decoding: Set by libavcodec, user can override.
1844      */
1845     int (*execute2)(struct AVCodecContext *c, int (*func)(struct AVCodecContext *c2, void *arg, int jobnr, int threadnr), void *arg2, int *ret, int count);
1846
1847     /**
1848      * noise vs. sse weight for the nsse comparison function
1849      * - encoding: Set by user.
1850      * - decoding: unused
1851      */
1852      int nsse_weight;
1853
1854     /**
1855      * profile
1856      * - encoding: Set by user.
1857      * - decoding: Set by libavcodec.
1858      */
1859      int profile;
1860 #define FF_PROFILE_UNKNOWN -99
1861 #define FF_PROFILE_RESERVED -100
1862
1863 #define FF_PROFILE_AAC_MAIN 0
1864 #define FF_PROFILE_AAC_LOW  1
1865 #define FF_PROFILE_AAC_SSR  2
1866 #define FF_PROFILE_AAC_LTP  3
1867 #define FF_PROFILE_AAC_HE   4
1868 #define FF_PROFILE_AAC_HE_V2 28
1869 #define FF_PROFILE_AAC_LD   22
1870 #define FF_PROFILE_AAC_ELD  38
1871 #define FF_PROFILE_MPEG2_AAC_LOW 128
1872 #define FF_PROFILE_MPEG2_AAC_HE  131
1873
1874 #define FF_PROFILE_DNXHD         0
1875 #define FF_PROFILE_DNXHR_LB      1
1876 #define FF_PROFILE_DNXHR_SQ      2
1877 #define FF_PROFILE_DNXHR_HQ      3
1878 #define FF_PROFILE_DNXHR_HQX     4
1879 #define FF_PROFILE_DNXHR_444     5
1880
1881 #define FF_PROFILE_DTS         20
1882 #define FF_PROFILE_DTS_ES      30
1883 #define FF_PROFILE_DTS_96_24   40
1884 #define FF_PROFILE_DTS_HD_HRA  50
1885 #define FF_PROFILE_DTS_HD_MA   60
1886 #define FF_PROFILE_DTS_EXPRESS 70
1887
1888 #define FF_PROFILE_MPEG2_422    0
1889 #define FF_PROFILE_MPEG2_HIGH   1
1890 #define FF_PROFILE_MPEG2_SS     2
1891 #define FF_PROFILE_MPEG2_SNR_SCALABLE  3
1892 #define FF_PROFILE_MPEG2_MAIN   4
1893 #define FF_PROFILE_MPEG2_SIMPLE 5
1894
1895 #define FF_PROFILE_H264_CONSTRAINED  (1<<9)  // 8+1; constraint_set1_flag
1896 #define FF_PROFILE_H264_INTRA        (1<<11) // 8+3; constraint_set3_flag
1897
1898 #define FF_PROFILE_H264_BASELINE             66
1899 #define FF_PROFILE_H264_CONSTRAINED_BASELINE (66|FF_PROFILE_H264_CONSTRAINED)
1900 #define FF_PROFILE_H264_MAIN                 77
1901 #define FF_PROFILE_H264_EXTENDED             88
1902 #define FF_PROFILE_H264_HIGH                 100
1903 #define FF_PROFILE_H264_HIGH_10              110
1904 #define FF_PROFILE_H264_HIGH_10_INTRA        (110|FF_PROFILE_H264_INTRA)
1905 #define FF_PROFILE_H264_MULTIVIEW_HIGH       118
1906 #define FF_PROFILE_H264_HIGH_422             122
1907 #define FF_PROFILE_H264_HIGH_422_INTRA       (122|FF_PROFILE_H264_INTRA)
1908 #define FF_PROFILE_H264_STEREO_HIGH          128
1909 #define FF_PROFILE_H264_HIGH_444             144
1910 #define FF_PROFILE_H264_HIGH_444_PREDICTIVE  244
1911 #define FF_PROFILE_H264_HIGH_444_INTRA       (244|FF_PROFILE_H264_INTRA)
1912 #define FF_PROFILE_H264_CAVLC_444            44
1913
1914 #define FF_PROFILE_VC1_SIMPLE   0
1915 #define FF_PROFILE_VC1_MAIN     1
1916 #define FF_PROFILE_VC1_COMPLEX  2
1917 #define FF_PROFILE_VC1_ADVANCED 3
1918
1919 #define FF_PROFILE_MPEG4_SIMPLE                     0
1920 #define FF_PROFILE_MPEG4_SIMPLE_SCALABLE            1
1921 #define FF_PROFILE_MPEG4_CORE                       2
1922 #define FF_PROFILE_MPEG4_MAIN                       3
1923 #define FF_PROFILE_MPEG4_N_BIT                      4
1924 #define FF_PROFILE_MPEG4_SCALABLE_TEXTURE           5
1925 #define FF_PROFILE_MPEG4_SIMPLE_FACE_ANIMATION      6
1926 #define FF_PROFILE_MPEG4_BASIC_ANIMATED_TEXTURE     7
1927 #define FF_PROFILE_MPEG4_HYBRID                     8
1928 #define FF_PROFILE_MPEG4_ADVANCED_REAL_TIME         9
1929 #define FF_PROFILE_MPEG4_CORE_SCALABLE             10
1930 #define FF_PROFILE_MPEG4_ADVANCED_CODING           11
1931 #define FF_PROFILE_MPEG4_ADVANCED_CORE             12
1932 #define FF_PROFILE_MPEG4_ADVANCED_SCALABLE_TEXTURE 13
1933 #define FF_PROFILE_MPEG4_SIMPLE_STUDIO             14
1934 #define FF_PROFILE_MPEG4_ADVANCED_SIMPLE           15
1935
1936 #define FF_PROFILE_JPEG2000_CSTREAM_RESTRICTION_0   1
1937 #define FF_PROFILE_JPEG2000_CSTREAM_RESTRICTION_1   2
1938 #define FF_PROFILE_JPEG2000_CSTREAM_NO_RESTRICTION  32768
1939 #define FF_PROFILE_JPEG2000_DCINEMA_2K              3
1940 #define FF_PROFILE_JPEG2000_DCINEMA_4K              4
1941
1942 #define FF_PROFILE_VP9_0                            0
1943 #define FF_PROFILE_VP9_1                            1
1944 #define FF_PROFILE_VP9_2                            2
1945 #define FF_PROFILE_VP9_3                            3
1946
1947 #define FF_PROFILE_HEVC_MAIN                        1
1948 #define FF_PROFILE_HEVC_MAIN_10                     2
1949 #define FF_PROFILE_HEVC_MAIN_STILL_PICTURE          3
1950 #define FF_PROFILE_HEVC_REXT                        4
1951
1952 #define FF_PROFILE_AV1_MAIN                         0
1953 #define FF_PROFILE_AV1_HIGH                         1
1954 #define FF_PROFILE_AV1_PROFESSIONAL                 2
1955
1956 #define FF_PROFILE_MJPEG_HUFFMAN_BASELINE_DCT            0xc0
1957 #define FF_PROFILE_MJPEG_HUFFMAN_EXTENDED_SEQUENTIAL_DCT 0xc1
1958 #define FF_PROFILE_MJPEG_HUFFMAN_PROGRESSIVE_DCT         0xc2
1959 #define FF_PROFILE_MJPEG_HUFFMAN_LOSSLESS                0xc3
1960 #define FF_PROFILE_MJPEG_JPEG_LS                         0xf7
1961
1962 #define FF_PROFILE_SBC_MSBC                         1
1963
1964 #define FF_PROFILE_PRORES_PROXY     0
1965 #define FF_PROFILE_PRORES_LT        1
1966 #define FF_PROFILE_PRORES_STANDARD  2
1967 #define FF_PROFILE_PRORES_HQ        3
1968 #define FF_PROFILE_PRORES_4444      4
1969 #define FF_PROFILE_PRORES_XQ        5
1970
1971 #define FF_PROFILE_ARIB_PROFILE_A 0
1972 #define FF_PROFILE_ARIB_PROFILE_C 1
1973
1974     /**
1975      * level
1976      * - encoding: Set by user.
1977      * - decoding: Set by libavcodec.
1978      */
1979      int level;
1980 #define FF_LEVEL_UNKNOWN -99
1981
1982     /**
1983      * Skip loop filtering for selected frames.
1984      * - encoding: unused
1985      * - decoding: Set by user.
1986      */
1987     enum AVDiscard skip_loop_filter;
1988
1989     /**
1990      * Skip IDCT/dequantization for selected frames.
1991      * - encoding: unused
1992      * - decoding: Set by user.
1993      */
1994     enum AVDiscard skip_idct;
1995
1996     /**
1997      * Skip decoding for selected frames.
1998      * - encoding: unused
1999      * - decoding: Set by user.
2000      */
2001     enum AVDiscard skip_frame;
2002
2003     /**
2004      * Header containing style information for text subtitles.
2005      * For SUBTITLE_ASS subtitle type, it should contain the whole ASS
2006      * [Script Info] and [V4+ Styles] section, plus the [Events] line and
2007      * the Format line following. It shouldn't include any Dialogue line.
2008      * - encoding: Set/allocated/freed by user (before avcodec_open2())
2009      * - decoding: Set/allocated/freed by libavcodec (by avcodec_open2())
2010      */
2011     uint8_t *subtitle_header;
2012     int subtitle_header_size;
2013
2014 #if FF_API_VBV_DELAY
2015     /**
2016      * VBV delay coded in the last frame (in periods of a 27 MHz clock).
2017      * Used for compliant TS muxing.
2018      * - encoding: Set by libavcodec.
2019      * - decoding: unused.
2020      * @deprecated this value is now exported as a part of
2021      * AV_PKT_DATA_CPB_PROPERTIES packet side data
2022      */
2023     attribute_deprecated
2024     uint64_t vbv_delay;
2025 #endif
2026
2027 #if FF_API_SIDEDATA_ONLY_PKT
2028     /**
2029      * Encoding only and set by default. Allow encoders to output packets
2030      * that do not contain any encoded data, only side data.
2031      *
2032      * Some encoders need to output such packets, e.g. to update some stream
2033      * parameters at the end of encoding.
2034      *
2035      * @deprecated this field disables the default behaviour and
2036      *             it is kept only for compatibility.
2037      */
2038     attribute_deprecated
2039     int side_data_only_packets;
2040 #endif
2041
2042     /**
2043      * Audio only. The number of "priming" samples (padding) inserted by the
2044      * encoder at the beginning of the audio. I.e. this number of leading
2045      * decoded samples must be discarded by the caller to get the original audio
2046      * without leading padding.
2047      *
2048      * - decoding: unused
2049      * - encoding: Set by libavcodec. The timestamps on the output packets are
2050      *             adjusted by the encoder so that they always refer to the
2051      *             first sample of the data actually contained in the packet,
2052      *             including any added padding.  E.g. if the timebase is
2053      *             1/samplerate and the timestamp of the first input sample is
2054      *             0, the timestamp of the first output packet will be
2055      *             -initial_padding.
2056      */
2057     int initial_padding;
2058
2059     /**
2060      * - decoding: For codecs that store a framerate value in the compressed
2061      *             bitstream, the decoder may export it here. { 0, 1} when
2062      *             unknown.
2063      * - encoding: May be used to signal the framerate of CFR content to an
2064      *             encoder.
2065      */
2066     AVRational framerate;
2067
2068     /**
2069      * Nominal unaccelerated pixel format, see AV_PIX_FMT_xxx.
2070      * - encoding: unused.
2071      * - decoding: Set by libavcodec before calling get_format()
2072      */
2073     enum AVPixelFormat sw_pix_fmt;
2074
2075     /**
2076      * Timebase in which pkt_dts/pts and AVPacket.dts/pts are.
2077      * - encoding unused.
2078      * - decoding set by user.
2079      */
2080     AVRational pkt_timebase;
2081
2082     /**
2083      * AVCodecDescriptor
2084      * - encoding: unused.
2085      * - decoding: set by libavcodec.
2086      */
2087     const AVCodecDescriptor *codec_descriptor;
2088
2089 #if !FF_API_LOWRES
2090     /**
2091      * low resolution decoding, 1-> 1/2 size, 2->1/4 size
2092      * - encoding: unused
2093      * - decoding: Set by user.
2094      */
2095      int lowres;
2096 #endif
2097
2098     /**
2099      * Current statistics for PTS correction.
2100      * - decoding: maintained and used by libavcodec, not intended to be used by user apps
2101      * - encoding: unused
2102      */
2103     int64_t pts_correction_num_faulty_pts; /// Number of incorrect PTS values so far
2104     int64_t pts_correction_num_faulty_dts; /// Number of incorrect DTS values so far
2105     int64_t pts_correction_last_pts;       /// PTS of the last frame
2106     int64_t pts_correction_last_dts;       /// DTS of the last frame
2107
2108     /**
2109      * Character encoding of the input subtitles file.
2110      * - decoding: set by user
2111      * - encoding: unused
2112      */
2113     char *sub_charenc;
2114
2115     /**
2116      * Subtitles character encoding mode. Formats or codecs might be adjusting
2117      * this setting (if they are doing the conversion themselves for instance).
2118      * - decoding: set by libavcodec
2119      * - encoding: unused
2120      */
2121     int sub_charenc_mode;
2122 #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)
2123 #define FF_SUB_CHARENC_MODE_AUTOMATIC    0  ///< libavcodec will select the mode itself
2124 #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
2125 #define FF_SUB_CHARENC_MODE_IGNORE       2  ///< neither convert the subtitles, nor check them for valid UTF-8
2126
2127     /**
2128      * Skip processing alpha if supported by codec.
2129      * Note that if the format uses pre-multiplied alpha (common with VP6,
2130      * and recommended due to better video quality/compression)
2131      * the image will look as if alpha-blended onto a black background.
2132      * However for formats that do not use pre-multiplied alpha
2133      * there might be serious artefacts (though e.g. libswscale currently
2134      * assumes pre-multiplied alpha anyway).
2135      *
2136      * - decoding: set by user
2137      * - encoding: unused
2138      */
2139     int skip_alpha;
2140
2141     /**
2142      * Number of samples to skip after a discontinuity
2143      * - decoding: unused
2144      * - encoding: set by libavcodec
2145      */
2146     int seek_preroll;
2147
2148 #if !FF_API_DEBUG_MV
2149     /**
2150      * debug motion vectors
2151      * - encoding: Set by user.
2152      * - decoding: Set by user.
2153      */
2154     int debug_mv;
2155 #define FF_DEBUG_VIS_MV_P_FOR  0x00000001 //visualize forward predicted MVs of P frames
2156 #define FF_DEBUG_VIS_MV_B_FOR  0x00000002 //visualize forward predicted MVs of B frames
2157 #define FF_DEBUG_VIS_MV_B_BACK 0x00000004 //visualize backward predicted MVs of B frames
2158 #endif
2159
2160     /**
2161      * custom intra quantization matrix
2162      * - encoding: Set by user, can be NULL.
2163      * - decoding: unused.
2164      */
2165     uint16_t *chroma_intra_matrix;
2166
2167     /**
2168      * dump format separator.
2169      * can be ", " or "\n      " or anything else
2170      * - encoding: Set by user.
2171      * - decoding: Set by user.
2172      */
2173     uint8_t *dump_separator;
2174
2175     /**
2176      * ',' separated list of allowed decoders.
2177      * If NULL then all are allowed
2178      * - encoding: unused
2179      * - decoding: set by user
2180      */
2181     char *codec_whitelist;
2182
2183     /**
2184      * Properties of the stream that gets decoded
2185      * - encoding: unused
2186      * - decoding: set by libavcodec
2187      */
2188     unsigned properties;
2189 #define FF_CODEC_PROPERTY_LOSSLESS        0x00000001
2190 #define FF_CODEC_PROPERTY_CLOSED_CAPTIONS 0x00000002
2191
2192     /**
2193      * Additional data associated with the entire coded stream.
2194      *
2195      * - decoding: unused
2196      * - encoding: may be set by libavcodec after avcodec_open2().
2197      */
2198     AVPacketSideData *coded_side_data;
2199     int            nb_coded_side_data;
2200
2201     /**
2202      * A reference to the AVHWFramesContext describing the input (for encoding)
2203      * or output (decoding) frames. The reference is set by the caller and
2204      * afterwards owned (and freed) by libavcodec - it should never be read by
2205      * the caller after being set.
2206      *
2207      * - decoding: This field should be set by the caller from the get_format()
2208      *             callback. The previous reference (if any) will always be
2209      *             unreffed by libavcodec before the get_format() call.
2210      *
2211      *             If the default get_buffer2() is used with a hwaccel pixel
2212      *             format, then this AVHWFramesContext will be used for
2213      *             allocating the frame buffers.
2214      *
2215      * - encoding: For hardware encoders configured to use a hwaccel pixel
2216      *             format, this field should be set by the caller to a reference
2217      *             to the AVHWFramesContext describing input frames.
2218      *             AVHWFramesContext.format must be equal to
2219      *             AVCodecContext.pix_fmt.
2220      *
2221      *             This field should be set before avcodec_open2() is called.
2222      */
2223     AVBufferRef *hw_frames_ctx;
2224
2225     /**
2226      * Control the form of AVSubtitle.rects[N]->ass
2227      * - decoding: set by user
2228      * - encoding: unused
2229      */
2230     int sub_text_format;
2231 #define FF_SUB_TEXT_FMT_ASS              0
2232 #if FF_API_ASS_TIMING
2233 #define FF_SUB_TEXT_FMT_ASS_WITH_TIMINGS 1
2234 #endif
2235
2236     /**
2237      * Audio only. The amount of padding (in samples) appended by the encoder to
2238      * the end of the audio. I.e. this number of decoded samples must be
2239      * discarded by the caller from the end of the stream to get the original
2240      * audio without any trailing padding.
2241      *
2242      * - decoding: unused
2243      * - encoding: unused
2244      */
2245     int trailing_padding;
2246
2247     /**
2248      * The number of pixels per image to maximally accept.
2249      *
2250      * - decoding: set by user
2251      * - encoding: set by user
2252      */
2253     int64_t max_pixels;
2254
2255     /**
2256      * A reference to the AVHWDeviceContext describing the device which will
2257      * be used by a hardware encoder/decoder.  The reference is set by the
2258      * caller and afterwards owned (and freed) by libavcodec.
2259      *
2260      * This should be used if either the codec device does not require
2261      * hardware frames or any that are used are to be allocated internally by
2262      * libavcodec.  If the user wishes to supply any of the frames used as
2263      * encoder input or decoder output then hw_frames_ctx should be used
2264      * instead.  When hw_frames_ctx is set in get_format() for a decoder, this
2265      * field will be ignored while decoding the associated stream segment, but
2266      * may again be used on a following one after another get_format() call.
2267      *
2268      * For both encoders and decoders this field should be set before
2269      * avcodec_open2() is called and must not be written to thereafter.
2270      *
2271      * Note that some decoders may require this field to be set initially in
2272      * order to support hw_frames_ctx at all - in that case, all frames
2273      * contexts used must be created on the same device.
2274      */
2275     AVBufferRef *hw_device_ctx;
2276
2277     /**
2278      * Bit set of AV_HWACCEL_FLAG_* flags, which affect hardware accelerated
2279      * decoding (if active).
2280      * - encoding: unused
2281      * - decoding: Set by user (either before avcodec_open2(), or in the
2282      *             AVCodecContext.get_format callback)
2283      */
2284     int hwaccel_flags;
2285
2286     /**
2287      * Video decoding only. Certain video codecs support cropping, meaning that
2288      * only a sub-rectangle of the decoded frame is intended for display.  This
2289      * option controls how cropping is handled by libavcodec.
2290      *
2291      * When set to 1 (the default), libavcodec will apply cropping internally.
2292      * I.e. it will modify the output frame width/height fields and offset the
2293      * data pointers (only by as much as possible while preserving alignment, or
2294      * by the full amount if the AV_CODEC_FLAG_UNALIGNED flag is set) so that
2295      * the frames output by the decoder refer only to the cropped area. The
2296      * crop_* fields of the output frames will be zero.
2297      *
2298      * When set to 0, the width/height fields of the output frames will be set
2299      * to the coded dimensions and the crop_* fields will describe the cropping
2300      * rectangle. Applying the cropping is left to the caller.
2301      *
2302      * @warning When hardware acceleration with opaque output frames is used,
2303      * libavcodec is unable to apply cropping from the top/left border.
2304      *
2305      * @note when this option is set to zero, the width/height fields of the
2306      * AVCodecContext and output AVFrames have different meanings. The codec
2307      * context fields store display dimensions (with the coded dimensions in
2308      * coded_width/height), while the frame fields store the coded dimensions
2309      * (with the display dimensions being determined by the crop_* fields).
2310      */
2311     int apply_cropping;
2312
2313     /*
2314      * Video decoding only.  Sets the number of extra hardware frames which
2315      * the decoder will allocate for use by the caller.  This must be set
2316      * before avcodec_open2() is called.
2317      *
2318      * Some hardware decoders require all frames that they will use for
2319      * output to be defined in advance before decoding starts.  For such
2320      * decoders, the hardware frame pool must therefore be of a fixed size.
2321      * The extra frames set here are on top of any number that the decoder
2322      * needs internally in order to operate normally (for example, frames
2323      * used as reference pictures).
2324      */
2325     int extra_hw_frames;
2326
2327     /**
2328      * The percentage of damaged samples to discard a frame.
2329      *
2330      * - decoding: set by user
2331      * - encoding: unused
2332      */
2333     int discard_damaged_percentage;
2334
2335     /**
2336      * The number of samples per frame to maximally accept.
2337      *
2338      * - decoding: set by user
2339      * - encoding: set by user
2340      */
2341     int64_t max_samples;
2342
2343     /**
2344      * Bit set of AV_CODEC_EXPORT_DATA_* flags, which affects the kind of
2345      * metadata exported in frame, packet, or coded stream side data by
2346      * decoders and encoders.
2347      *
2348      * - decoding: set by user
2349      * - encoding: set by user
2350      */
2351     int export_side_data;
2352 } AVCodecContext;
2353
2354 #if FF_API_CODEC_GET_SET
2355 /**
2356  * Accessors for some AVCodecContext fields. These used to be provided for ABI
2357  * compatibility, and do not need to be used anymore.
2358  */
2359 attribute_deprecated
2360 AVRational av_codec_get_pkt_timebase         (const AVCodecContext *avctx);
2361 attribute_deprecated
2362 void       av_codec_set_pkt_timebase         (AVCodecContext *avctx, AVRational val);
2363
2364 attribute_deprecated
2365 const AVCodecDescriptor *av_codec_get_codec_descriptor(const AVCodecContext *avctx);
2366 attribute_deprecated
2367 void                     av_codec_set_codec_descriptor(AVCodecContext *avctx, const AVCodecDescriptor *desc);
2368
2369 attribute_deprecated
2370 unsigned av_codec_get_codec_properties(const AVCodecContext *avctx);
2371
2372 #if FF_API_LOWRES
2373 attribute_deprecated
2374 int  av_codec_get_lowres(const AVCodecContext *avctx);
2375 attribute_deprecated
2376 void av_codec_set_lowres(AVCodecContext *avctx, int val);
2377 #endif
2378
2379 attribute_deprecated
2380 int  av_codec_get_seek_preroll(const AVCodecContext *avctx);
2381 attribute_deprecated
2382 void av_codec_set_seek_preroll(AVCodecContext *avctx, int val);
2383
2384 attribute_deprecated
2385 uint16_t *av_codec_get_chroma_intra_matrix(const AVCodecContext *avctx);
2386 attribute_deprecated
2387 void av_codec_set_chroma_intra_matrix(AVCodecContext *avctx, uint16_t *val);
2388 #endif
2389
2390 struct AVSubtitle;
2391
2392 #if FF_API_CODEC_GET_SET
2393 attribute_deprecated
2394 int av_codec_get_max_lowres(const AVCodec *codec);
2395 #endif
2396
2397 struct MpegEncContext;
2398
2399 /**
2400  * @defgroup lavc_hwaccel AVHWAccel
2401  *
2402  * @note  Nothing in this structure should be accessed by the user.  At some
2403  *        point in future it will not be externally visible at all.
2404  *
2405  * @{
2406  */
2407 typedef struct AVHWAccel {
2408     /**
2409      * Name of the hardware accelerated codec.
2410      * The name is globally unique among encoders and among decoders (but an
2411      * encoder and a decoder can share the same name).
2412      */
2413     const char *name;
2414
2415     /**
2416      * Type of codec implemented by the hardware accelerator.
2417      *
2418      * See AVMEDIA_TYPE_xxx
2419      */
2420     enum AVMediaType type;
2421
2422     /**
2423      * Codec implemented by the hardware accelerator.
2424      *
2425      * See AV_CODEC_ID_xxx
2426      */
2427     enum AVCodecID id;
2428
2429     /**
2430      * Supported pixel format.
2431      *
2432      * Only hardware accelerated formats are supported here.
2433      */
2434     enum AVPixelFormat pix_fmt;
2435
2436     /**
2437      * Hardware accelerated codec capabilities.
2438      * see AV_HWACCEL_CODEC_CAP_*
2439      */
2440     int capabilities;
2441
2442     /*****************************************************************
2443      * No fields below this line are part of the public API. They
2444      * may not be used outside of libavcodec and can be changed and
2445      * removed at will.
2446      * New public fields should be added right above.
2447      *****************************************************************
2448      */
2449
2450     /**
2451      * Allocate a custom buffer
2452      */
2453     int (*alloc_frame)(AVCodecContext *avctx, AVFrame *frame);
2454
2455     /**
2456      * Called at the beginning of each frame or field picture.
2457      *
2458      * Meaningful frame information (codec specific) is guaranteed to
2459      * be parsed at this point. This function is mandatory.
2460      *
2461      * Note that buf can be NULL along with buf_size set to 0.
2462      * Otherwise, this means the whole frame is available at this point.
2463      *
2464      * @param avctx the codec context
2465      * @param buf the frame data buffer base
2466      * @param buf_size the size of the frame in bytes
2467      * @return zero if successful, a negative value otherwise
2468      */
2469     int (*start_frame)(AVCodecContext *avctx, const uint8_t *buf, uint32_t buf_size);
2470
2471     /**
2472      * Callback for parameter data (SPS/PPS/VPS etc).
2473      *
2474      * Useful for hardware decoders which keep persistent state about the
2475      * video parameters, and need to receive any changes to update that state.
2476      *
2477      * @param avctx the codec context
2478      * @param type the nal unit type
2479      * @param buf the nal unit data buffer
2480      * @param buf_size the size of the nal unit in bytes
2481      * @return zero if successful, a negative value otherwise
2482      */
2483     int (*decode_params)(AVCodecContext *avctx, int type, const uint8_t *buf, uint32_t buf_size);
2484
2485     /**
2486      * Callback for each slice.
2487      *
2488      * Meaningful slice information (codec specific) is guaranteed to
2489      * be parsed at this point. This function is mandatory.
2490      * The only exception is XvMC, that works on MB level.
2491      *
2492      * @param avctx the codec context
2493      * @param buf the slice data buffer base
2494      * @param buf_size the size of the slice in bytes
2495      * @return zero if successful, a negative value otherwise
2496      */
2497     int (*decode_slice)(AVCodecContext *avctx, const uint8_t *buf, uint32_t buf_size);
2498
2499     /**
2500      * Called at the end of each frame or field picture.
2501      *
2502      * The whole picture is parsed at this point and can now be sent
2503      * to the hardware accelerator. This function is mandatory.
2504      *
2505      * @param avctx the codec context
2506      * @return zero if successful, a negative value otherwise
2507      */
2508     int (*end_frame)(AVCodecContext *avctx);
2509
2510     /**
2511      * Size of per-frame hardware accelerator private data.
2512      *
2513      * Private data is allocated with av_mallocz() before
2514      * AVCodecContext.get_buffer() and deallocated after
2515      * AVCodecContext.release_buffer().
2516      */
2517     int frame_priv_data_size;
2518
2519     /**
2520      * Called for every Macroblock in a slice.
2521      *
2522      * XvMC uses it to replace the ff_mpv_reconstruct_mb().
2523      * Instead of decoding to raw picture, MB parameters are
2524      * stored in an array provided by the video driver.
2525      *
2526      * @param s the mpeg context
2527      */
2528     void (*decode_mb)(struct MpegEncContext *s);
2529
2530     /**
2531      * Initialize the hwaccel private data.
2532      *
2533      * This will be called from ff_get_format(), after hwaccel and
2534      * hwaccel_context are set and the hwaccel private data in AVCodecInternal
2535      * is allocated.
2536      */
2537     int (*init)(AVCodecContext *avctx);
2538
2539     /**
2540      * Uninitialize the hwaccel private data.
2541      *
2542      * This will be called from get_format() or avcodec_close(), after hwaccel
2543      * and hwaccel_context are already uninitialized.
2544      */
2545     int (*uninit)(AVCodecContext *avctx);
2546
2547     /**
2548      * Size of the private data to allocate in
2549      * AVCodecInternal.hwaccel_priv_data.
2550      */
2551     int priv_data_size;
2552
2553     /**
2554      * Internal hwaccel capabilities.
2555      */
2556     int caps_internal;
2557
2558     /**
2559      * Fill the given hw_frames context with current codec parameters. Called
2560      * from get_format. Refer to avcodec_get_hw_frames_parameters() for
2561      * details.
2562      *
2563      * This CAN be called before AVHWAccel.init is called, and you must assume
2564      * that avctx->hwaccel_priv_data is invalid.
2565      */
2566     int (*frame_params)(AVCodecContext *avctx, AVBufferRef *hw_frames_ctx);
2567 } AVHWAccel;
2568
2569 /**
2570  * HWAccel is experimental and is thus avoided in favor of non experimental
2571  * codecs
2572  */
2573 #define AV_HWACCEL_CODEC_CAP_EXPERIMENTAL 0x0200
2574
2575 /**
2576  * Hardware acceleration should be used for decoding even if the codec level
2577  * used is unknown or higher than the maximum supported level reported by the
2578  * hardware driver.
2579  *
2580  * It's generally a good idea to pass this flag unless you have a specific
2581  * reason not to, as hardware tends to under-report supported levels.
2582  */
2583 #define AV_HWACCEL_FLAG_IGNORE_LEVEL (1 << 0)
2584
2585 /**
2586  * Hardware acceleration can output YUV pixel formats with a different chroma
2587  * sampling than 4:2:0 and/or other than 8 bits per component.
2588  */
2589 #define AV_HWACCEL_FLAG_ALLOW_HIGH_DEPTH (1 << 1)
2590
2591 /**
2592  * Hardware acceleration should still be attempted for decoding when the
2593  * codec profile does not match the reported capabilities of the hardware.
2594  *
2595  * For example, this can be used to try to decode baseline profile H.264
2596  * streams in hardware - it will often succeed, because many streams marked
2597  * as baseline profile actually conform to constrained baseline profile.
2598  *
2599  * @warning If the stream is actually not supported then the behaviour is
2600  *          undefined, and may include returning entirely incorrect output
2601  *          while indicating success.
2602  */
2603 #define AV_HWACCEL_FLAG_ALLOW_PROFILE_MISMATCH (1 << 2)
2604
2605 /**
2606  * @}
2607  */
2608
2609 #if FF_API_AVPICTURE
2610 /**
2611  * @defgroup lavc_picture AVPicture
2612  *
2613  * Functions for working with AVPicture
2614  * @{
2615  */
2616
2617 /**
2618  * Picture data structure.
2619  *
2620  * Up to four components can be stored into it, the last component is
2621  * alpha.
2622  * @deprecated use AVFrame or imgutils functions instead
2623  */
2624 typedef struct AVPicture {
2625     attribute_deprecated
2626     uint8_t *data[AV_NUM_DATA_POINTERS];    ///< pointers to the image data planes
2627     attribute_deprecated
2628     int linesize[AV_NUM_DATA_POINTERS];     ///< number of bytes per line
2629 } AVPicture;
2630
2631 /**
2632  * @}
2633  */
2634 #endif
2635
2636 enum AVSubtitleType {
2637     SUBTITLE_NONE,
2638
2639     SUBTITLE_BITMAP,                ///< A bitmap, pict will be set
2640
2641     /**
2642      * Plain text, the text field must be set by the decoder and is
2643      * authoritative. ass and pict fields may contain approximations.
2644      */
2645     SUBTITLE_TEXT,
2646
2647     /**
2648      * Formatted text, the ass field must be set by the decoder and is
2649      * authoritative. pict and text fields may contain approximations.
2650      */
2651     SUBTITLE_ASS,
2652 };
2653
2654 #define AV_SUBTITLE_FLAG_FORCED 0x00000001
2655
2656 typedef struct AVSubtitleRect {
2657     int x;         ///< top left corner  of pict, undefined when pict is not set
2658     int y;         ///< top left corner  of pict, undefined when pict is not set
2659     int w;         ///< width            of pict, undefined when pict is not set
2660     int h;         ///< height           of pict, undefined when pict is not set
2661     int nb_colors; ///< number of colors in pict, undefined when pict is not set
2662
2663 #if FF_API_AVPICTURE
2664     /**
2665      * @deprecated unused
2666      */
2667     attribute_deprecated
2668     AVPicture pict;
2669 #endif
2670     /**
2671      * data+linesize for the bitmap of this subtitle.
2672      * Can be set for text/ass as well once they are rendered.
2673      */
2674     uint8_t *data[4];
2675     int linesize[4];
2676
2677     enum AVSubtitleType type;
2678
2679     char *text;                     ///< 0 terminated plain UTF-8 text
2680
2681     /**
2682      * 0 terminated ASS/SSA compatible event line.
2683      * The presentation of this is unaffected by the other values in this
2684      * struct.
2685      */
2686     char *ass;
2687
2688     int flags;
2689 } AVSubtitleRect;
2690
2691 typedef struct AVSubtitle {
2692     uint16_t format; /* 0 = graphics */
2693     uint32_t start_display_time; /* relative to packet pts, in ms */
2694     uint32_t end_display_time; /* relative to packet pts, in ms */
2695     unsigned num_rects;
2696     AVSubtitleRect **rects;
2697     int64_t pts;    ///< Same as packet pts, in AV_TIME_BASE
2698 } AVSubtitle;
2699
2700 #if FF_API_NEXT
2701 /**
2702  * If c is NULL, returns the first registered codec,
2703  * if c is non-NULL, returns the next registered codec after c,
2704  * or NULL if c is the last one.
2705  */
2706 attribute_deprecated
2707 AVCodec *av_codec_next(const AVCodec *c);
2708 #endif
2709
2710 /**
2711  * Return the LIBAVCODEC_VERSION_INT constant.
2712  */
2713 unsigned avcodec_version(void);
2714
2715 /**
2716  * Return the libavcodec build-time configuration.
2717  */
2718 const char *avcodec_configuration(void);
2719
2720 /**
2721  * Return the libavcodec license.
2722  */
2723 const char *avcodec_license(void);
2724
2725 #if FF_API_NEXT
2726 /**
2727  * Register the codec codec and initialize libavcodec.
2728  *
2729  * @warning either this function or avcodec_register_all() must be called
2730  * before any other libavcodec functions.
2731  *
2732  * @see avcodec_register_all()
2733  */
2734 attribute_deprecated
2735 void avcodec_register(AVCodec *codec);
2736
2737 /**
2738  * Register all the codecs, parsers and bitstream filters which were enabled at
2739  * configuration time. If you do not call this function you can select exactly
2740  * which formats you want to support, by using the individual registration
2741  * functions.
2742  *
2743  * @see avcodec_register
2744  * @see av_register_codec_parser
2745  * @see av_register_bitstream_filter
2746  */
2747 attribute_deprecated
2748 void avcodec_register_all(void);
2749 #endif
2750
2751 /**
2752  * Allocate an AVCodecContext and set its fields to default values. The
2753  * resulting struct should be freed with avcodec_free_context().
2754  *
2755  * @param codec if non-NULL, allocate private data and initialize defaults
2756  *              for the given codec. It is illegal to then call avcodec_open2()
2757  *              with a different codec.
2758  *              If NULL, then the codec-specific defaults won't be initialized,
2759  *              which may result in suboptimal default settings (this is
2760  *              important mainly for encoders, e.g. libx264).
2761  *
2762  * @return An AVCodecContext filled with default values or NULL on failure.
2763  */
2764 AVCodecContext *avcodec_alloc_context3(const AVCodec *codec);
2765
2766 /**
2767  * Free the codec context and everything associated with it and write NULL to
2768  * the provided pointer.
2769  */
2770 void avcodec_free_context(AVCodecContext **avctx);
2771
2772 #if FF_API_GET_CONTEXT_DEFAULTS
2773 /**
2774  * @deprecated This function should not be used, as closing and opening a codec
2775  * context multiple time is not supported. A new codec context should be
2776  * allocated for each new use.
2777  */
2778 int avcodec_get_context_defaults3(AVCodecContext *s, const AVCodec *codec);
2779 #endif
2780
2781 /**
2782  * Get the AVClass for AVCodecContext. It can be used in combination with
2783  * AV_OPT_SEARCH_FAKE_OBJ for examining options.
2784  *
2785  * @see av_opt_find().
2786  */
2787 const AVClass *avcodec_get_class(void);
2788
2789 #if FF_API_COPY_CONTEXT
2790 /**
2791  * Get the AVClass for AVFrame. It can be used in combination with
2792  * AV_OPT_SEARCH_FAKE_OBJ for examining options.
2793  *
2794  * @see av_opt_find().
2795  */
2796 const AVClass *avcodec_get_frame_class(void);
2797
2798 /**
2799  * Get the AVClass for AVSubtitleRect. It can be used in combination with
2800  * AV_OPT_SEARCH_FAKE_OBJ for examining options.
2801  *
2802  * @see av_opt_find().
2803  */
2804 const AVClass *avcodec_get_subtitle_rect_class(void);
2805
2806 /**
2807  * Copy the settings of the source AVCodecContext into the destination
2808  * AVCodecContext. The resulting destination codec context will be
2809  * unopened, i.e. you are required to call avcodec_open2() before you
2810  * can use this AVCodecContext to decode/encode video/audio data.
2811  *
2812  * @param dest target codec context, should be initialized with
2813  *             avcodec_alloc_context3(NULL), but otherwise uninitialized
2814  * @param src source codec context
2815  * @return AVERROR() on error (e.g. memory allocation error), 0 on success
2816  *
2817  * @deprecated The semantics of this function are ill-defined and it should not
2818  * be used. If you need to transfer the stream parameters from one codec context
2819  * to another, use an intermediate AVCodecParameters instance and the
2820  * avcodec_parameters_from_context() / avcodec_parameters_to_context()
2821  * functions.
2822  */
2823 attribute_deprecated
2824 int avcodec_copy_context(AVCodecContext *dest, const AVCodecContext *src);
2825 #endif
2826
2827 /**
2828  * Fill the parameters struct based on the values from the supplied codec
2829  * context. Any allocated fields in par are freed and replaced with duplicates
2830  * of the corresponding fields in codec.
2831  *
2832  * @return >= 0 on success, a negative AVERROR code on failure
2833  */
2834 int avcodec_parameters_from_context(AVCodecParameters *par,
2835                                     const AVCodecContext *codec);
2836
2837 /**
2838  * Fill the codec context based on the values from the supplied codec
2839  * parameters. Any allocated fields in codec that have a corresponding field in
2840  * par are freed and replaced with duplicates of the corresponding field in par.
2841  * Fields in codec that do not have a counterpart in par are not touched.
2842  *
2843  * @return >= 0 on success, a negative AVERROR code on failure.
2844  */
2845 int avcodec_parameters_to_context(AVCodecContext *codec,
2846                                   const AVCodecParameters *par);
2847
2848 /**
2849  * Initialize the AVCodecContext to use the given AVCodec. Prior to using this
2850  * function the context has to be allocated with avcodec_alloc_context3().
2851  *
2852  * The functions avcodec_find_decoder_by_name(), avcodec_find_encoder_by_name(),
2853  * avcodec_find_decoder() and avcodec_find_encoder() provide an easy way for
2854  * retrieving a codec.
2855  *
2856  * @warning This function is not thread safe!
2857  *
2858  * @note Always call this function before using decoding routines (such as
2859  * @ref avcodec_receive_frame()).
2860  *
2861  * @code
2862  * avcodec_register_all();
2863  * av_dict_set(&opts, "b", "2.5M", 0);
2864  * codec = avcodec_find_decoder(AV_CODEC_ID_H264);
2865  * if (!codec)
2866  *     exit(1);
2867  *
2868  * context = avcodec_alloc_context3(codec);
2869  *
2870  * if (avcodec_open2(context, codec, opts) < 0)
2871  *     exit(1);
2872  * @endcode
2873  *
2874  * @param avctx The context to initialize.
2875  * @param codec The codec to open this context for. If a non-NULL codec has been
2876  *              previously passed to avcodec_alloc_context3() or
2877  *              for this context, then this parameter MUST be either NULL or
2878  *              equal to the previously passed codec.
2879  * @param options A dictionary filled with AVCodecContext and codec-private options.
2880  *                On return this object will be filled with options that were not found.
2881  *
2882  * @return zero on success, a negative value on error
2883  * @see avcodec_alloc_context3(), avcodec_find_decoder(), avcodec_find_encoder(),
2884  *      av_dict_set(), av_opt_find().
2885  */
2886 int avcodec_open2(AVCodecContext *avctx, const AVCodec *codec, AVDictionary **options);
2887
2888 /**
2889  * Close a given AVCodecContext and free all the data associated with it
2890  * (but not the AVCodecContext itself).
2891  *
2892  * Calling this function on an AVCodecContext that hasn't been opened will free
2893  * the codec-specific data allocated in avcodec_alloc_context3() with a non-NULL
2894  * codec. Subsequent calls will do nothing.
2895  *
2896  * @note Do not use this function. Use avcodec_free_context() to destroy a
2897  * codec context (either open or closed). Opening and closing a codec context
2898  * multiple times is not supported anymore -- use multiple codec contexts
2899  * instead.
2900  */
2901 int avcodec_close(AVCodecContext *avctx);
2902
2903 /**
2904  * Free all allocated data in the given subtitle struct.
2905  *
2906  * @param sub AVSubtitle to free.
2907  */
2908 void avsubtitle_free(AVSubtitle *sub);
2909
2910 /**
2911  * @}
2912  */
2913
2914 /**
2915  * @addtogroup lavc_decoding
2916  * @{
2917  */
2918
2919 /**
2920  * The default callback for AVCodecContext.get_buffer2(). It is made public so
2921  * it can be called by custom get_buffer2() implementations for decoders without
2922  * AV_CODEC_CAP_DR1 set.
2923  */
2924 int avcodec_default_get_buffer2(AVCodecContext *s, AVFrame *frame, int flags);
2925
2926 /**
2927  * Modify width and height values so that they will result in a memory
2928  * buffer that is acceptable for the codec if you do not use any horizontal
2929  * padding.
2930  *
2931  * May only be used if a codec with AV_CODEC_CAP_DR1 has been opened.
2932  */
2933 void avcodec_align_dimensions(AVCodecContext *s, int *width, int *height);
2934
2935 /**
2936  * Modify width and height values so that they will result in a memory
2937  * buffer that is acceptable for the codec if you also ensure that all
2938  * line sizes are a multiple of the respective linesize_align[i].
2939  *
2940  * May only be used if a codec with AV_CODEC_CAP_DR1 has been opened.
2941  */
2942 void avcodec_align_dimensions2(AVCodecContext *s, int *width, int *height,
2943                                int linesize_align[AV_NUM_DATA_POINTERS]);
2944
2945 /**
2946  * Converts AVChromaLocation to swscale x/y chroma position.
2947  *
2948  * The positions represent the chroma (0,0) position in a coordinates system
2949  * with luma (0,0) representing the origin and luma(1,1) representing 256,256
2950  *
2951  * @param xpos  horizontal chroma sample position
2952  * @param ypos  vertical   chroma sample position
2953  */
2954 int avcodec_enum_to_chroma_pos(int *xpos, int *ypos, enum AVChromaLocation pos);
2955
2956 /**
2957  * Converts swscale x/y chroma position to AVChromaLocation.
2958  *
2959  * The positions represent the chroma (0,0) position in a coordinates system
2960  * with luma (0,0) representing the origin and luma(1,1) representing 256,256
2961  *
2962  * @param xpos  horizontal chroma sample position
2963  * @param ypos  vertical   chroma sample position
2964  */
2965 enum AVChromaLocation avcodec_chroma_pos_to_enum(int xpos, int ypos);
2966
2967 /**
2968  * Decode the audio frame of size avpkt->size from avpkt->data into frame.
2969  *
2970  * Some decoders may support multiple frames in a single AVPacket. Such
2971  * decoders would then just decode the first frame and the return value would be
2972  * less than the packet size. In this case, avcodec_decode_audio4 has to be
2973  * called again with an AVPacket containing the remaining data in order to
2974  * decode the second frame, etc...  Even if no frames are returned, the packet
2975  * needs to be fed to the decoder with remaining data until it is completely
2976  * consumed or an error occurs.
2977  *
2978  * Some decoders (those marked with AV_CODEC_CAP_DELAY) have a delay between input
2979  * and output. This means that for some packets they will not immediately
2980  * produce decoded output and need to be flushed at the end of decoding to get
2981  * all the decoded data. Flushing is done by calling this function with packets
2982  * with avpkt->data set to NULL and avpkt->size set to 0 until it stops
2983  * returning samples. It is safe to flush even those decoders that are not
2984  * marked with AV_CODEC_CAP_DELAY, then no samples will be returned.
2985  *
2986  * @warning The input buffer, avpkt->data must be AV_INPUT_BUFFER_PADDING_SIZE
2987  *          larger than the actual read bytes because some optimized bitstream
2988  *          readers read 32 or 64 bits at once and could read over the end.
2989  *
2990  * @note The AVCodecContext MUST have been opened with @ref avcodec_open2()
2991  * before packets may be fed to the decoder.
2992  *
2993  * @param      avctx the codec context
2994  * @param[out] frame The AVFrame in which to store decoded audio samples.
2995  *                   The decoder will allocate a buffer for the decoded frame by
2996  *                   calling the AVCodecContext.get_buffer2() callback.
2997  *                   When AVCodecContext.refcounted_frames is set to 1, the frame is
2998  *                   reference counted and the returned reference belongs to the
2999  *                   caller. The caller must release the frame using av_frame_unref()
3000  *                   when the frame is no longer needed. The caller may safely write
3001  *                   to the frame if av_frame_is_writable() returns 1.
3002  *                   When AVCodecContext.refcounted_frames is set to 0, the returned
3003  *                   reference belongs to the decoder and is valid only until the
3004  *                   next call to this function or until closing or flushing the
3005  *                   decoder. The caller may not write to it.
3006  * @param[out] got_frame_ptr Zero if no frame could be decoded, otherwise it is
3007  *                           non-zero. Note that this field being set to zero
3008  *                           does not mean that an error has occurred. For
3009  *                           decoders with AV_CODEC_CAP_DELAY set, no given decode
3010  *                           call is guaranteed to produce a frame.
3011  * @param[in]  avpkt The input AVPacket containing the input buffer.
3012  *                   At least avpkt->data and avpkt->size should be set. Some
3013  *                   decoders might also require additional fields to be set.
3014  * @return A negative error code is returned if an error occurred during
3015  *         decoding, otherwise the number of bytes consumed from the input
3016  *         AVPacket is returned.
3017  *
3018 * @deprecated Use avcodec_send_packet() and avcodec_receive_frame().
3019  */
3020 attribute_deprecated
3021 int avcodec_decode_audio4(AVCodecContext *avctx, AVFrame *frame,
3022                           int *got_frame_ptr, const AVPacket *avpkt);
3023
3024 /**
3025  * Decode the video frame of size avpkt->size from avpkt->data into picture.
3026  * Some decoders may support multiple frames in a single AVPacket, such
3027  * decoders would then just decode the first frame.
3028  *
3029  * @warning The input buffer must be AV_INPUT_BUFFER_PADDING_SIZE larger than
3030  * the actual read bytes because some optimized bitstream readers read 32 or 64
3031  * bits at once and could read over the end.
3032  *
3033  * @warning The end of the input buffer buf should be set to 0 to ensure that
3034  * no overreading happens for damaged MPEG streams.
3035  *
3036  * @note Codecs which have the AV_CODEC_CAP_DELAY capability set have a delay
3037  * between input and output, these need to be fed with avpkt->data=NULL,
3038  * avpkt->size=0 at the end to return the remaining frames.
3039  *
3040  * @note The AVCodecContext MUST have been opened with @ref avcodec_open2()
3041  * before packets may be fed to the decoder.
3042  *
3043  * @param avctx the codec context
3044  * @param[out] picture The AVFrame in which the decoded video frame will be stored.
3045  *             Use av_frame_alloc() to get an AVFrame. The codec will
3046  *             allocate memory for the actual bitmap by calling the
3047  *             AVCodecContext.get_buffer2() callback.
3048  *             When AVCodecContext.refcounted_frames is set to 1, the frame is
3049  *             reference counted and the returned reference belongs to the
3050  *             caller. The caller must release the frame using av_frame_unref()
3051  *             when the frame is no longer needed. The caller may safely write
3052  *             to the frame if av_frame_is_writable() returns 1.
3053  *             When AVCodecContext.refcounted_frames is set to 0, the returned
3054  *             reference belongs to the decoder and is valid only until the
3055  *             next call to this function or until closing or flushing the
3056  *             decoder. The caller may not write to it.
3057  *
3058  * @param[in] avpkt The input AVPacket containing the input buffer.
3059  *            You can create such packet with av_init_packet() and by then setting
3060  *            data and size, some decoders might in addition need other fields like
3061  *            flags&AV_PKT_FLAG_KEY. All decoders are designed to use the least
3062  *            fields possible.
3063  * @param[in,out] got_picture_ptr Zero if no frame could be decompressed, otherwise, it is nonzero.
3064  * @return On error a negative value is returned, otherwise the number of bytes
3065  * used or zero if no frame could be decompressed.
3066  *
3067  * @deprecated Use avcodec_send_packet() and avcodec_receive_frame().
3068  */
3069 attribute_deprecated
3070 int avcodec_decode_video2(AVCodecContext *avctx, AVFrame *picture,
3071                          int *got_picture_ptr,
3072                          const AVPacket *avpkt);
3073
3074 /**
3075  * Decode a subtitle message.
3076  * Return a negative value on error, otherwise return the number of bytes used.
3077  * If no subtitle could be decompressed, got_sub_ptr is zero.
3078  * Otherwise, the subtitle is stored in *sub.
3079  * Note that AV_CODEC_CAP_DR1 is not available for subtitle codecs. This is for
3080  * simplicity, because the performance difference is expected to be negligible
3081  * and reusing a get_buffer written for video codecs would probably perform badly
3082  * due to a potentially very different allocation pattern.
3083  *
3084  * Some decoders (those marked with AV_CODEC_CAP_DELAY) have a delay between input
3085  * and output. This means that for some packets they will not immediately
3086  * produce decoded output and need to be flushed at the end of decoding to get
3087  * all the decoded data. Flushing is done by calling this function with packets
3088  * with avpkt->data set to NULL and avpkt->size set to 0 until it stops
3089  * returning subtitles. It is safe to flush even those decoders that are not
3090  * marked with AV_CODEC_CAP_DELAY, then no subtitles will be returned.
3091  *
3092  * @note The AVCodecContext MUST have been opened with @ref avcodec_open2()
3093  * before packets may be fed to the decoder.
3094  *
3095  * @param avctx the codec context
3096  * @param[out] sub The preallocated AVSubtitle in which the decoded subtitle will be stored,
3097  *                 must be freed with avsubtitle_free if *got_sub_ptr is set.
3098  * @param[in,out] got_sub_ptr Zero if no subtitle could be decompressed, otherwise, it is nonzero.
3099  * @param[in] avpkt The input AVPacket containing the input buffer.
3100  */
3101 int avcodec_decode_subtitle2(AVCodecContext *avctx, AVSubtitle *sub,
3102                             int *got_sub_ptr,
3103                             AVPacket *avpkt);
3104
3105 /**
3106  * Supply raw packet data as input to a decoder.
3107  *
3108  * Internally, this call will copy relevant AVCodecContext fields, which can
3109  * influence decoding per-packet, and apply them when the packet is actually
3110  * decoded. (For example AVCodecContext.skip_frame, which might direct the
3111  * decoder to drop the frame contained by the packet sent with this function.)
3112  *
3113  * @warning The input buffer, avpkt->data must be AV_INPUT_BUFFER_PADDING_SIZE
3114  *          larger than the actual read bytes because some optimized bitstream
3115  *          readers read 32 or 64 bits at once and could read over the end.
3116  *
3117  * @warning Do not mix this API with the legacy API (like avcodec_decode_video2())
3118  *          on the same AVCodecContext. It will return unexpected results now
3119  *          or in future libavcodec versions.
3120  *
3121  * @note The AVCodecContext MUST have been opened with @ref avcodec_open2()
3122  *       before packets may be fed to the decoder.
3123  *
3124  * @param avctx codec context
3125  * @param[in] avpkt The input AVPacket. Usually, this will be a single video
3126  *                  frame, or several complete audio frames.
3127  *                  Ownership of the packet remains with the caller, and the
3128  *                  decoder will not write to the packet. The decoder may create
3129  *                  a reference to the packet data (or copy it if the packet is
3130  *                  not reference-counted).
3131  *                  Unlike with older APIs, the packet is always fully consumed,
3132  *                  and if it contains multiple frames (e.g. some audio codecs),
3133  *                  will require you to call avcodec_receive_frame() multiple
3134  *                  times afterwards before you can send a new packet.
3135  *                  It can be NULL (or an AVPacket with data set to NULL and
3136  *                  size set to 0); in this case, it is considered a flush
3137  *                  packet, which signals the end of the stream. Sending the
3138  *                  first flush packet will return success. Subsequent ones are
3139  *                  unnecessary and will return AVERROR_EOF. If the decoder
3140  *                  still has frames buffered, it will return them after sending
3141  *                  a flush packet.
3142  *
3143  * @return 0 on success, otherwise negative error code:
3144  *      AVERROR(EAGAIN):   input is not accepted in the current state - user
3145  *                         must read output with avcodec_receive_frame() (once
3146  *                         all output is read, the packet should be resent, and
3147  *                         the call will not fail with EAGAIN).
3148  *      AVERROR_EOF:       the decoder has been flushed, and no new packets can
3149  *                         be sent to it (also returned if more than 1 flush
3150  *                         packet is sent)
3151  *      AVERROR(EINVAL):   codec not opened, it is an encoder, or requires flush
3152  *      AVERROR(ENOMEM):   failed to add packet to internal queue, or similar
3153  *      other errors: legitimate decoding errors
3154  */
3155 int avcodec_send_packet(AVCodecContext *avctx, const AVPacket *avpkt);
3156
3157 /**
3158  * Return decoded output data from a decoder.
3159  *
3160  * @param avctx codec context
3161  * @param frame This will be set to a reference-counted video or audio
3162  *              frame (depending on the decoder type) allocated by the
3163  *              decoder. Note that the function will always call
3164  *              av_frame_unref(frame) before doing anything else.
3165  *
3166  * @return
3167  *      0:                 success, a frame was returned
3168  *      AVERROR(EAGAIN):   output is not available in this state - user must try
3169  *                         to send new input
3170  *      AVERROR_EOF:       the decoder has been fully flushed, and there will be
3171  *                         no more output frames
3172  *      AVERROR(EINVAL):   codec not opened, or it is an encoder
3173  *      AVERROR_INPUT_CHANGED:   current decoded frame has changed parameters
3174  *                               with respect to first decoded frame. Applicable
3175  *                               when flag AV_CODEC_FLAG_DROPCHANGED is set.
3176  *      other negative values: legitimate decoding errors
3177  */
3178 int avcodec_receive_frame(AVCodecContext *avctx, AVFrame *frame);
3179
3180 /**
3181  * Supply a raw video or audio frame to the encoder. Use avcodec_receive_packet()
3182  * to retrieve buffered output packets.
3183  *
3184  * @param avctx     codec context
3185  * @param[in] frame AVFrame containing the raw audio or video frame to be encoded.
3186  *                  Ownership of the frame remains with the caller, and the
3187  *                  encoder will not write to the frame. The encoder may create
3188  *                  a reference to the frame data (or copy it if the frame is
3189  *                  not reference-counted).
3190  *                  It can be NULL, in which case it is considered a flush
3191  *                  packet.  This signals the end of the stream. If the encoder
3192  *                  still has packets buffered, it will return them after this
3193  *                  call. Once flushing mode has been entered, additional flush
3194  *                  packets are ignored, and sending frames will return
3195  *                  AVERROR_EOF.
3196  *
3197  *                  For audio:
3198  *                  If AV_CODEC_CAP_VARIABLE_FRAME_SIZE is set, then each frame
3199  *                  can have any number of samples.
3200  *                  If it is not set, frame->nb_samples must be equal to
3201  *                  avctx->frame_size for all frames except the last.
3202  *                  The final frame may be smaller than avctx->frame_size.
3203  * @return 0 on success, otherwise negative error code:
3204  *      AVERROR(EAGAIN):   input is not accepted in the current state - user
3205  *                         must read output with avcodec_receive_packet() (once
3206  *                         all output is read, the packet should be resent, and
3207  *                         the call will not fail with EAGAIN).
3208  *      AVERROR_EOF:       the encoder has been flushed, and no new frames can
3209  *                         be sent to it
3210  *      AVERROR(EINVAL):   codec not opened, refcounted_frames not set, it is a
3211  *                         decoder, or requires flush
3212  *      AVERROR(ENOMEM):   failed to add packet to internal queue, or similar
3213  *      other errors: legitimate encoding errors
3214  */
3215 int avcodec_send_frame(AVCodecContext *avctx, const AVFrame *frame);
3216
3217 /**
3218  * Read encoded data from the encoder.
3219  *
3220  * @param avctx codec context
3221  * @param avpkt This will be set to a reference-counted packet allocated by the
3222  *              encoder. Note that the function will always call
3223  *              av_packet_unref(avpkt) before doing anything else.
3224  * @return 0 on success, otherwise negative error code:
3225  *      AVERROR(EAGAIN):   output is not available in the current state - user
3226  *                         must try to send input
3227  *      AVERROR_EOF:       the encoder has been fully flushed, and there will be
3228  *                         no more output packets
3229  *      AVERROR(EINVAL):   codec not opened, or it is a decoder
3230  *      other errors: legitimate encoding errors
3231  */
3232 int avcodec_receive_packet(AVCodecContext *avctx, AVPacket *avpkt);
3233
3234 /**
3235  * Create and return a AVHWFramesContext with values adequate for hardware
3236  * decoding. This is meant to get called from the get_format callback, and is
3237  * a helper for preparing a AVHWFramesContext for AVCodecContext.hw_frames_ctx.
3238  * This API is for decoding with certain hardware acceleration modes/APIs only.
3239  *
3240  * The returned AVHWFramesContext is not initialized. The caller must do this
3241  * with av_hwframe_ctx_init().
3242  *
3243  * Calling this function is not a requirement, but makes it simpler to avoid
3244  * codec or hardware API specific details when manually allocating frames.
3245  *
3246  * Alternatively to this, an API user can set AVCodecContext.hw_device_ctx,
3247  * which sets up AVCodecContext.hw_frames_ctx fully automatically, and makes
3248  * it unnecessary to call this function or having to care about
3249  * AVHWFramesContext initialization at all.
3250  *
3251  * There are a number of requirements for calling this function:
3252  *
3253  * - It must be called from get_format with the same avctx parameter that was
3254  *   passed to get_format. Calling it outside of get_format is not allowed, and
3255  *   can trigger undefined behavior.
3256  * - The function is not always supported (see description of return values).
3257  *   Even if this function returns successfully, hwaccel initialization could
3258  *   fail later. (The degree to which implementations check whether the stream
3259  *   is actually supported varies. Some do this check only after the user's
3260  *   get_format callback returns.)
3261  * - The hw_pix_fmt must be one of the choices suggested by get_format. If the
3262  *   user decides to use a AVHWFramesContext prepared with this API function,
3263  *   the user must return the same hw_pix_fmt from get_format.
3264  * - The device_ref passed to this function must support the given hw_pix_fmt.
3265  * - After calling this API function, it is the user's responsibility to
3266  *   initialize the AVHWFramesContext (returned by the out_frames_ref parameter),
3267  *   and to set AVCodecContext.hw_frames_ctx to it. If done, this must be done
3268  *   before returning from get_format (this is implied by the normal
3269  *   AVCodecContext.hw_frames_ctx API rules).
3270  * - The AVHWFramesContext parameters may change every time time get_format is
3271  *   called. Also, AVCodecContext.hw_frames_ctx is reset before get_format. So
3272  *   you are inherently required to go through this process again on every
3273  *   get_format call.
3274  * - It is perfectly possible to call this function without actually using
3275  *   the resulting AVHWFramesContext. One use-case might be trying to reuse a
3276  *   previously initialized AVHWFramesContext, and calling this API function
3277  *   only to test whether the required frame parameters have changed.
3278  * - Fields that use dynamically allocated values of any kind must not be set
3279  *   by the user unless setting them is explicitly allowed by the documentation.
3280  *   If the user sets AVHWFramesContext.free and AVHWFramesContext.user_opaque,
3281  *   the new free callback must call the potentially set previous free callback.
3282  *   This API call may set any dynamically allocated fields, including the free
3283  *   callback.
3284  *
3285  * The function will set at least the following fields on AVHWFramesContext
3286  * (potentially more, depending on hwaccel API):
3287  *
3288  * - All fields set by av_hwframe_ctx_alloc().
3289  * - Set the format field to hw_pix_fmt.
3290  * - Set the sw_format field to the most suited and most versatile format. (An
3291  *   implication is that this will prefer generic formats over opaque formats
3292  *   with arbitrary restrictions, if possible.)
3293  * - Set the width/height fields to the coded frame size, rounded up to the
3294  *   API-specific minimum alignment.
3295  * - Only _if_ the hwaccel requires a pre-allocated pool: set the initial_pool_size
3296  *   field to the number of maximum reference surfaces possible with the codec,
3297  *   plus 1 surface for the user to work (meaning the user can safely reference
3298  *   at most 1 decoded surface at a time), plus additional buffering introduced
3299  *   by frame threading. If the hwaccel does not require pre-allocation, the
3300  *   field is left to 0, and the decoder will allocate new surfaces on demand
3301  *   during decoding.
3302  * - Possibly AVHWFramesContext.hwctx fields, depending on the underlying
3303  *   hardware API.
3304  *
3305  * Essentially, out_frames_ref returns the same as av_hwframe_ctx_alloc(), but
3306  * with basic frame parameters set.
3307  *
3308  * The function is stateless, and does not change the AVCodecContext or the
3309  * device_ref AVHWDeviceContext.
3310  *
3311  * @param avctx The context which is currently calling get_format, and which
3312  *              implicitly contains all state needed for filling the returned
3313  *              AVHWFramesContext properly.
3314  * @param device_ref A reference to the AVHWDeviceContext describing the device
3315  *                   which will be used by the hardware decoder.
3316  * @param hw_pix_fmt The hwaccel format you are going to return from get_format.
3317  * @param out_frames_ref On success, set to a reference to an _uninitialized_
3318  *                       AVHWFramesContext, created from the given device_ref.
3319  *                       Fields will be set to values required for decoding.
3320  *                       Not changed if an error is returned.
3321  * @return zero on success, a negative value on error. The following error codes
3322  *         have special semantics:
3323  *      AVERROR(ENOENT): the decoder does not support this functionality. Setup
3324  *                       is always manual, or it is a decoder which does not
3325  *                       support setting AVCodecContext.hw_frames_ctx at all,
3326  *                       or it is a software format.
3327  *      AVERROR(EINVAL): it is known that hardware decoding is not supported for
3328  *                       this configuration, or the device_ref is not supported
3329  *                       for the hwaccel referenced by hw_pix_fmt.
3330  */
3331 int avcodec_get_hw_frames_parameters(AVCodecContext *avctx,
3332                                      AVBufferRef *device_ref,
3333                                      enum AVPixelFormat hw_pix_fmt,
3334                                      AVBufferRef **out_frames_ref);
3335
3336
3337
3338 /**
3339  * @defgroup lavc_parsing Frame parsing
3340  * @{
3341  */
3342
3343 enum AVPictureStructure {
3344     AV_PICTURE_STRUCTURE_UNKNOWN,      //< unknown
3345     AV_PICTURE_STRUCTURE_TOP_FIELD,    //< coded as top field
3346     AV_PICTURE_STRUCTURE_BOTTOM_FIELD, //< coded as bottom field
3347     AV_PICTURE_STRUCTURE_FRAME,        //< coded as frame
3348 };
3349
3350 typedef struct AVCodecParserContext {
3351     void *priv_data;
3352     struct AVCodecParser *parser;
3353     int64_t frame_offset; /* offset of the current frame */
3354     int64_t cur_offset; /* current offset
3355                            (incremented by each av_parser_parse()) */
3356     int64_t next_frame_offset; /* offset of the next frame */
3357     /* video info */
3358     int pict_type; /* XXX: Put it back in AVCodecContext. */
3359     /**
3360      * This field is used for proper frame duration computation in lavf.
3361      * It signals, how much longer the frame duration of the current frame
3362      * is compared to normal frame duration.
3363      *
3364      * frame_duration = (1 + repeat_pict) * time_base
3365      *
3366      * It is used by codecs like H.264 to display telecined material.
3367      */
3368     int repeat_pict; /* XXX: Put it back in AVCodecContext. */
3369     int64_t pts;     /* pts of the current frame */
3370     int64_t dts;     /* dts of the current frame */
3371
3372     /* private data */
3373     int64_t last_pts;
3374     int64_t last_dts;
3375     int fetch_timestamp;
3376
3377 #define AV_PARSER_PTS_NB 4
3378     int cur_frame_start_index;
3379     int64_t cur_frame_offset[AV_PARSER_PTS_NB];
3380     int64_t cur_frame_pts[AV_PARSER_PTS_NB];
3381     int64_t cur_frame_dts[AV_PARSER_PTS_NB];
3382
3383     int flags;
3384 #define PARSER_FLAG_COMPLETE_FRAMES           0x0001
3385 #define PARSER_FLAG_ONCE                      0x0002
3386 /// Set if the parser has a valid file offset
3387 #define PARSER_FLAG_FETCHED_OFFSET            0x0004
3388 #define PARSER_FLAG_USE_CODEC_TS              0x1000
3389
3390     int64_t offset;      ///< byte offset from starting packet start
3391     int64_t cur_frame_end[AV_PARSER_PTS_NB];
3392
3393     /**
3394      * Set by parser to 1 for key frames and 0 for non-key frames.
3395      * It is initialized to -1, so if the parser doesn't set this flag,
3396      * old-style fallback using AV_PICTURE_TYPE_I picture type as key frames
3397      * will be used.
3398      */
3399     int key_frame;
3400
3401 #if FF_API_CONVERGENCE_DURATION
3402     /**
3403      * @deprecated unused
3404      */
3405     attribute_deprecated
3406     int64_t convergence_duration;
3407 #endif
3408
3409     // Timestamp generation support:
3410     /**
3411      * Synchronization point for start of timestamp generation.
3412      *
3413      * Set to >0 for sync point, 0 for no sync point and <0 for undefined
3414      * (default).
3415      *
3416      * For example, this corresponds to presence of H.264 buffering period
3417      * SEI message.
3418      */
3419     int dts_sync_point;
3420
3421     /**
3422      * Offset of the current timestamp against last timestamp sync point in
3423      * units of AVCodecContext.time_base.
3424      *
3425      * Set to INT_MIN when dts_sync_point unused. Otherwise, it must
3426      * contain a valid timestamp offset.
3427      *
3428      * Note that the timestamp of sync point has usually a nonzero
3429      * dts_ref_dts_delta, which refers to the previous sync point. Offset of
3430      * the next frame after timestamp sync point will be usually 1.
3431      *
3432      * For example, this corresponds to H.264 cpb_removal_delay.
3433      */
3434     int dts_ref_dts_delta;
3435
3436     /**
3437      * Presentation delay of current frame in units of AVCodecContext.time_base.
3438      *
3439      * Set to INT_MIN when dts_sync_point unused. Otherwise, it must
3440      * contain valid non-negative timestamp delta (presentation time of a frame
3441      * must not lie in the past).
3442      *
3443      * This delay represents the difference between decoding and presentation
3444      * time of the frame.
3445      *
3446      * For example, this corresponds to H.264 dpb_output_delay.
3447      */
3448     int pts_dts_delta;
3449
3450     /**
3451      * Position of the packet in file.
3452      *
3453      * Analogous to cur_frame_pts/dts
3454      */
3455     int64_t cur_frame_pos[AV_PARSER_PTS_NB];
3456
3457     /**
3458      * Byte position of currently parsed frame in stream.
3459      */
3460     int64_t pos;
3461
3462     /**
3463      * Previous frame byte position.
3464      */
3465     int64_t last_pos;
3466
3467     /**
3468      * Duration of the current frame.
3469      * For audio, this is in units of 1 / AVCodecContext.sample_rate.
3470      * For all other types, this is in units of AVCodecContext.time_base.
3471      */
3472     int duration;
3473
3474     enum AVFieldOrder field_order;
3475
3476     /**
3477      * Indicate whether a picture is coded as a frame, top field or bottom field.
3478      *
3479      * For example, H.264 field_pic_flag equal to 0 corresponds to
3480      * AV_PICTURE_STRUCTURE_FRAME. An H.264 picture with field_pic_flag
3481      * equal to 1 and bottom_field_flag equal to 0 corresponds to
3482      * AV_PICTURE_STRUCTURE_TOP_FIELD.
3483      */
3484     enum AVPictureStructure picture_structure;
3485
3486     /**
3487      * Picture number incremented in presentation or output order.
3488      * This field may be reinitialized at the first picture of a new sequence.
3489      *
3490      * For example, this corresponds to H.264 PicOrderCnt.
3491      */
3492     int output_picture_number;
3493
3494     /**
3495      * Dimensions of the decoded video intended for presentation.
3496      */
3497     int width;
3498     int height;
3499
3500     /**
3501      * Dimensions of the coded video.
3502      */
3503     int coded_width;
3504     int coded_height;
3505
3506     /**
3507      * The format of the coded data, corresponds to enum AVPixelFormat for video
3508      * and for enum AVSampleFormat for audio.
3509      *
3510      * Note that a decoder can have considerable freedom in how exactly it
3511      * decodes the data, so the format reported here might be different from the
3512      * one returned by a decoder.
3513      */
3514     int format;
3515 } AVCodecParserContext;
3516
3517 typedef struct AVCodecParser {
3518     int codec_ids[5]; /* several codec IDs are permitted */
3519     int priv_data_size;
3520     int (*parser_init)(AVCodecParserContext *s);
3521     /* This callback never returns an error, a negative value means that
3522      * the frame start was in a previous packet. */
3523     int (*parser_parse)(AVCodecParserContext *s,
3524                         AVCodecContext *avctx,
3525                         const uint8_t **poutbuf, int *poutbuf_size,
3526                         const uint8_t *buf, int buf_size);
3527     void (*parser_close)(AVCodecParserContext *s);
3528     int (*split)(AVCodecContext *avctx, const uint8_t *buf, int buf_size);
3529     struct AVCodecParser *next;
3530 } AVCodecParser;
3531
3532 /**
3533  * Iterate over all registered codec parsers.
3534  *
3535  * @param opaque a pointer where libavcodec will store the iteration state. Must
3536  *               point to NULL to start the iteration.
3537  *
3538  * @return the next registered codec parser or NULL when the iteration is
3539  *         finished
3540  */
3541 const AVCodecParser *av_parser_iterate(void **opaque);
3542
3543 attribute_deprecated
3544 AVCodecParser *av_parser_next(const AVCodecParser *c);
3545
3546 attribute_deprecated
3547 void av_register_codec_parser(AVCodecParser *parser);
3548 AVCodecParserContext *av_parser_init(int codec_id);
3549
3550 /**
3551  * Parse a packet.
3552  *
3553  * @param s             parser context.
3554  * @param avctx         codec context.
3555  * @param poutbuf       set to pointer to parsed buffer or NULL if not yet finished.
3556  * @param poutbuf_size  set to size of parsed buffer or zero if not yet finished.
3557  * @param buf           input buffer.
3558  * @param buf_size      buffer size in bytes without the padding. I.e. the full buffer
3559                         size is assumed to be buf_size + AV_INPUT_BUFFER_PADDING_SIZE.
3560                         To signal EOF, this should be 0 (so that the last frame
3561                         can be output).
3562  * @param pts           input presentation timestamp.
3563  * @param dts           input decoding timestamp.
3564  * @param pos           input byte position in stream.
3565  * @return the number of bytes of the input bitstream used.
3566  *
3567  * Example:
3568  * @code
3569  *   while(in_len){
3570  *       len = av_parser_parse2(myparser, AVCodecContext, &data, &size,
3571  *                                        in_data, in_len,
3572  *                                        pts, dts, pos);
3573  *       in_data += len;
3574  *       in_len  -= len;
3575  *
3576  *       if(size)
3577  *          decode_frame(data, size);
3578  *   }
3579  * @endcode
3580  */
3581 int av_parser_parse2(AVCodecParserContext *s,
3582                      AVCodecContext *avctx,
3583                      uint8_t **poutbuf, int *poutbuf_size,
3584                      const uint8_t *buf, int buf_size,
3585                      int64_t pts, int64_t dts,
3586                      int64_t pos);
3587
3588 /**
3589  * @return 0 if the output buffer is a subset of the input, 1 if it is allocated and must be freed
3590  * @deprecated use AVBitStreamFilter
3591  */
3592 int av_parser_change(AVCodecParserContext *s,
3593                      AVCodecContext *avctx,
3594                      uint8_t **poutbuf, int *poutbuf_size,
3595                      const uint8_t *buf, int buf_size, int keyframe);
3596 void av_parser_close(AVCodecParserContext *s);
3597
3598 /**
3599  * @}
3600  * @}
3601  */
3602
3603 /**
3604  * @addtogroup lavc_encoding
3605  * @{
3606  */
3607
3608 /**
3609  * Encode a frame of audio.
3610  *
3611  * Takes input samples from frame and writes the next output packet, if
3612  * available, to avpkt. The output packet does not necessarily contain data for
3613  * the most recent frame, as encoders can delay, split, and combine input frames
3614  * internally as needed.
3615  *
3616  * @param avctx     codec context
3617  * @param avpkt     output AVPacket.
3618  *                  The user can supply an output buffer by setting
3619  *                  avpkt->data and avpkt->size prior to calling the
3620  *                  function, but if the size of the user-provided data is not
3621  *                  large enough, encoding will fail. If avpkt->data and
3622  *                  avpkt->size are set, avpkt->destruct must also be set. All
3623  *                  other AVPacket fields will be reset by the encoder using
3624  *                  av_init_packet(). If avpkt->data is NULL, the encoder will
3625  *                  allocate it. The encoder will set avpkt->size to the size
3626  *                  of the output packet.
3627  *
3628  *                  If this function fails or produces no output, avpkt will be
3629  *                  freed using av_packet_unref().
3630  * @param[in] frame AVFrame containing the raw audio data to be encoded.
3631  *                  May be NULL when flushing an encoder that has the
3632  *                  AV_CODEC_CAP_DELAY capability set.
3633  *                  If AV_CODEC_CAP_VARIABLE_FRAME_SIZE is set, then each frame
3634  *                  can have any number of samples.
3635  *                  If it is not set, frame->nb_samples must be equal to
3636  *                  avctx->frame_size for all frames except the last.
3637  *                  The final frame may be smaller than avctx->frame_size.
3638  * @param[out] got_packet_ptr This field is set to 1 by libavcodec if the
3639  *                            output packet is non-empty, and to 0 if it is
3640  *                            empty. If the function returns an error, the
3641  *                            packet can be assumed to be invalid, and the
3642  *                            value of got_packet_ptr is undefined and should
3643  *                            not be used.
3644  * @return          0 on success, negative error code on failure
3645  *
3646  * @deprecated use avcodec_send_frame()/avcodec_receive_packet() instead
3647  */
3648 attribute_deprecated
3649 int avcodec_encode_audio2(AVCodecContext *avctx, AVPacket *avpkt,
3650                           const AVFrame *frame, int *got_packet_ptr);
3651
3652 /**
3653  * Encode a frame of video.
3654  *
3655  * Takes input raw video data from frame and writes the next output packet, if
3656  * available, to avpkt. The output packet does not necessarily contain data for
3657  * the most recent frame, as encoders can delay and reorder input frames
3658  * internally as needed.
3659  *
3660  * @param avctx     codec context
3661  * @param avpkt     output AVPacket.
3662  *                  The user can supply an output buffer by setting
3663  *                  avpkt->data and avpkt->size prior to calling the
3664  *                  function, but if the size of the user-provided data is not
3665  *                  large enough, encoding will fail. All other AVPacket fields
3666  *                  will be reset by the encoder using av_init_packet(). If
3667  *                  avpkt->data is NULL, the encoder will allocate it.
3668  *                  The encoder will set avpkt->size to the size of the
3669  *                  output packet. The returned data (if any) belongs to the
3670  *                  caller, he is responsible for freeing it.
3671  *
3672  *                  If this function fails or produces no output, avpkt will be
3673  *                  freed using av_packet_unref().
3674  * @param[in] frame AVFrame containing the raw video data to be encoded.
3675  *                  May be NULL when flushing an encoder that has the
3676  *                  AV_CODEC_CAP_DELAY capability set.
3677  * @param[out] got_packet_ptr This field is set to 1 by libavcodec if the
3678  *                            output packet is non-empty, and to 0 if it is
3679  *                            empty. If the function returns an error, the
3680  *                            packet can be assumed to be invalid, and the
3681  *                            value of got_packet_ptr is undefined and should
3682  *                            not be used.
3683  * @return