avcodec: add constants for KLV pseudo-profile.
[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 #define FF_PROFILE_KLVA_SYNC 0
1975 #define FF_PROFILE_KLVA_ASYNC 1
1976
1977     /**
1978      * level
1979      * - encoding: Set by user.
1980      * - decoding: Set by libavcodec.
1981      */
1982      int level;
1983 #define FF_LEVEL_UNKNOWN -99
1984
1985     /**
1986      * Skip loop filtering for selected frames.
1987      * - encoding: unused
1988      * - decoding: Set by user.
1989      */
1990     enum AVDiscard skip_loop_filter;
1991
1992     /**
1993      * Skip IDCT/dequantization for selected frames.
1994      * - encoding: unused
1995      * - decoding: Set by user.
1996      */
1997     enum AVDiscard skip_idct;
1998
1999     /**
2000      * Skip decoding for selected frames.
2001      * - encoding: unused
2002      * - decoding: Set by user.
2003      */
2004     enum AVDiscard skip_frame;
2005
2006     /**
2007      * Header containing style information for text subtitles.
2008      * For SUBTITLE_ASS subtitle type, it should contain the whole ASS
2009      * [Script Info] and [V4+ Styles] section, plus the [Events] line and
2010      * the Format line following. It shouldn't include any Dialogue line.
2011      * - encoding: Set/allocated/freed by user (before avcodec_open2())
2012      * - decoding: Set/allocated/freed by libavcodec (by avcodec_open2())
2013      */
2014     uint8_t *subtitle_header;
2015     int subtitle_header_size;
2016
2017 #if FF_API_VBV_DELAY
2018     /**
2019      * VBV delay coded in the last frame (in periods of a 27 MHz clock).
2020      * Used for compliant TS muxing.
2021      * - encoding: Set by libavcodec.
2022      * - decoding: unused.
2023      * @deprecated this value is now exported as a part of
2024      * AV_PKT_DATA_CPB_PROPERTIES packet side data
2025      */
2026     attribute_deprecated
2027     uint64_t vbv_delay;
2028 #endif
2029
2030 #if FF_API_SIDEDATA_ONLY_PKT
2031     /**
2032      * Encoding only and set by default. Allow encoders to output packets
2033      * that do not contain any encoded data, only side data.
2034      *
2035      * Some encoders need to output such packets, e.g. to update some stream
2036      * parameters at the end of encoding.
2037      *
2038      * @deprecated this field disables the default behaviour and
2039      *             it is kept only for compatibility.
2040      */
2041     attribute_deprecated
2042     int side_data_only_packets;
2043 #endif
2044
2045     /**
2046      * Audio only. The number of "priming" samples (padding) inserted by the
2047      * encoder at the beginning of the audio. I.e. this number of leading
2048      * decoded samples must be discarded by the caller to get the original audio
2049      * without leading padding.
2050      *
2051      * - decoding: unused
2052      * - encoding: Set by libavcodec. The timestamps on the output packets are
2053      *             adjusted by the encoder so that they always refer to the
2054      *             first sample of the data actually contained in the packet,
2055      *             including any added padding.  E.g. if the timebase is
2056      *             1/samplerate and the timestamp of the first input sample is
2057      *             0, the timestamp of the first output packet will be
2058      *             -initial_padding.
2059      */
2060     int initial_padding;
2061
2062     /**
2063      * - decoding: For codecs that store a framerate value in the compressed
2064      *             bitstream, the decoder may export it here. { 0, 1} when
2065      *             unknown.
2066      * - encoding: May be used to signal the framerate of CFR content to an
2067      *             encoder.
2068      */
2069     AVRational framerate;
2070
2071     /**
2072      * Nominal unaccelerated pixel format, see AV_PIX_FMT_xxx.
2073      * - encoding: unused.
2074      * - decoding: Set by libavcodec before calling get_format()
2075      */
2076     enum AVPixelFormat sw_pix_fmt;
2077
2078     /**
2079      * Timebase in which pkt_dts/pts and AVPacket.dts/pts are.
2080      * - encoding unused.
2081      * - decoding set by user.
2082      */
2083     AVRational pkt_timebase;
2084
2085     /**
2086      * AVCodecDescriptor
2087      * - encoding: unused.
2088      * - decoding: set by libavcodec.
2089      */
2090     const AVCodecDescriptor *codec_descriptor;
2091
2092 #if !FF_API_LOWRES
2093     /**
2094      * low resolution decoding, 1-> 1/2 size, 2->1/4 size
2095      * - encoding: unused
2096      * - decoding: Set by user.
2097      */
2098      int lowres;
2099 #endif
2100
2101     /**
2102      * Current statistics for PTS correction.
2103      * - decoding: maintained and used by libavcodec, not intended to be used by user apps
2104      * - encoding: unused
2105      */
2106     int64_t pts_correction_num_faulty_pts; /// Number of incorrect PTS values so far
2107     int64_t pts_correction_num_faulty_dts; /// Number of incorrect DTS values so far
2108     int64_t pts_correction_last_pts;       /// PTS of the last frame
2109     int64_t pts_correction_last_dts;       /// DTS of the last frame
2110
2111     /**
2112      * Character encoding of the input subtitles file.
2113      * - decoding: set by user
2114      * - encoding: unused
2115      */
2116     char *sub_charenc;
2117
2118     /**
2119      * Subtitles character encoding mode. Formats or codecs might be adjusting
2120      * this setting (if they are doing the conversion themselves for instance).
2121      * - decoding: set by libavcodec
2122      * - encoding: unused
2123      */
2124     int sub_charenc_mode;
2125 #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)
2126 #define FF_SUB_CHARENC_MODE_AUTOMATIC    0  ///< libavcodec will select the mode itself
2127 #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
2128 #define FF_SUB_CHARENC_MODE_IGNORE       2  ///< neither convert the subtitles, nor check them for valid UTF-8
2129
2130     /**
2131      * Skip processing alpha if supported by codec.
2132      * Note that if the format uses pre-multiplied alpha (common with VP6,
2133      * and recommended due to better video quality/compression)
2134      * the image will look as if alpha-blended onto a black background.
2135      * However for formats that do not use pre-multiplied alpha
2136      * there might be serious artefacts (though e.g. libswscale currently
2137      * assumes pre-multiplied alpha anyway).
2138      *
2139      * - decoding: set by user
2140      * - encoding: unused
2141      */
2142     int skip_alpha;
2143
2144     /**
2145      * Number of samples to skip after a discontinuity
2146      * - decoding: unused
2147      * - encoding: set by libavcodec
2148      */
2149     int seek_preroll;
2150
2151 #if !FF_API_DEBUG_MV
2152     /**
2153      * debug motion vectors
2154      * - encoding: Set by user.
2155      * - decoding: Set by user.
2156      */
2157     int debug_mv;
2158 #define FF_DEBUG_VIS_MV_P_FOR  0x00000001 //visualize forward predicted MVs of P frames
2159 #define FF_DEBUG_VIS_MV_B_FOR  0x00000002 //visualize forward predicted MVs of B frames
2160 #define FF_DEBUG_VIS_MV_B_BACK 0x00000004 //visualize backward predicted MVs of B frames
2161 #endif
2162
2163     /**
2164      * custom intra quantization matrix
2165      * - encoding: Set by user, can be NULL.
2166      * - decoding: unused.
2167      */
2168     uint16_t *chroma_intra_matrix;
2169
2170     /**
2171      * dump format separator.
2172      * can be ", " or "\n      " or anything else
2173      * - encoding: Set by user.
2174      * - decoding: Set by user.
2175      */
2176     uint8_t *dump_separator;
2177
2178     /**
2179      * ',' separated list of allowed decoders.
2180      * If NULL then all are allowed
2181      * - encoding: unused
2182      * - decoding: set by user
2183      */
2184     char *codec_whitelist;
2185
2186     /**
2187      * Properties of the stream that gets decoded
2188      * - encoding: unused
2189      * - decoding: set by libavcodec
2190      */
2191     unsigned properties;
2192 #define FF_CODEC_PROPERTY_LOSSLESS        0x00000001
2193 #define FF_CODEC_PROPERTY_CLOSED_CAPTIONS 0x00000002
2194
2195     /**
2196      * Additional data associated with the entire coded stream.
2197      *
2198      * - decoding: unused
2199      * - encoding: may be set by libavcodec after avcodec_open2().
2200      */
2201     AVPacketSideData *coded_side_data;
2202     int            nb_coded_side_data;
2203
2204     /**
2205      * A reference to the AVHWFramesContext describing the input (for encoding)
2206      * or output (decoding) frames. The reference is set by the caller and
2207      * afterwards owned (and freed) by libavcodec - it should never be read by
2208      * the caller after being set.
2209      *
2210      * - decoding: This field should be set by the caller from the get_format()
2211      *             callback. The previous reference (if any) will always be
2212      *             unreffed by libavcodec before the get_format() call.
2213      *
2214      *             If the default get_buffer2() is used with a hwaccel pixel
2215      *             format, then this AVHWFramesContext will be used for
2216      *             allocating the frame buffers.
2217      *
2218      * - encoding: For hardware encoders configured to use a hwaccel pixel
2219      *             format, this field should be set by the caller to a reference
2220      *             to the AVHWFramesContext describing input frames.
2221      *             AVHWFramesContext.format must be equal to
2222      *             AVCodecContext.pix_fmt.
2223      *
2224      *             This field should be set before avcodec_open2() is called.
2225      */
2226     AVBufferRef *hw_frames_ctx;
2227
2228     /**
2229      * Control the form of AVSubtitle.rects[N]->ass
2230      * - decoding: set by user
2231      * - encoding: unused
2232      */
2233     int sub_text_format;
2234 #define FF_SUB_TEXT_FMT_ASS              0
2235 #if FF_API_ASS_TIMING
2236 #define FF_SUB_TEXT_FMT_ASS_WITH_TIMINGS 1
2237 #endif
2238
2239     /**
2240      * Audio only. The amount of padding (in samples) appended by the encoder to
2241      * the end of the audio. I.e. this number of decoded samples must be
2242      * discarded by the caller from the end of the stream to get the original
2243      * audio without any trailing padding.
2244      *
2245      * - decoding: unused
2246      * - encoding: unused
2247      */
2248     int trailing_padding;
2249
2250     /**
2251      * The number of pixels per image to maximally accept.
2252      *
2253      * - decoding: set by user
2254      * - encoding: set by user
2255      */
2256     int64_t max_pixels;
2257
2258     /**
2259      * A reference to the AVHWDeviceContext describing the device which will
2260      * be used by a hardware encoder/decoder.  The reference is set by the
2261      * caller and afterwards owned (and freed) by libavcodec.
2262      *
2263      * This should be used if either the codec device does not require
2264      * hardware frames or any that are used are to be allocated internally by
2265      * libavcodec.  If the user wishes to supply any of the frames used as
2266      * encoder input or decoder output then hw_frames_ctx should be used
2267      * instead.  When hw_frames_ctx is set in get_format() for a decoder, this
2268      * field will be ignored while decoding the associated stream segment, but
2269      * may again be used on a following one after another get_format() call.
2270      *
2271      * For both encoders and decoders this field should be set before
2272      * avcodec_open2() is called and must not be written to thereafter.
2273      *
2274      * Note that some decoders may require this field to be set initially in
2275      * order to support hw_frames_ctx at all - in that case, all frames
2276      * contexts used must be created on the same device.
2277      */
2278     AVBufferRef *hw_device_ctx;
2279
2280     /**
2281      * Bit set of AV_HWACCEL_FLAG_* flags, which affect hardware accelerated
2282      * decoding (if active).
2283      * - encoding: unused
2284      * - decoding: Set by user (either before avcodec_open2(), or in the
2285      *             AVCodecContext.get_format callback)
2286      */
2287     int hwaccel_flags;
2288
2289     /**
2290      * Video decoding only. Certain video codecs support cropping, meaning that
2291      * only a sub-rectangle of the decoded frame is intended for display.  This
2292      * option controls how cropping is handled by libavcodec.
2293      *
2294      * When set to 1 (the default), libavcodec will apply cropping internally.
2295      * I.e. it will modify the output frame width/height fields and offset the
2296      * data pointers (only by as much as possible while preserving alignment, or
2297      * by the full amount if the AV_CODEC_FLAG_UNALIGNED flag is set) so that
2298      * the frames output by the decoder refer only to the cropped area. The
2299      * crop_* fields of the output frames will be zero.
2300      *
2301      * When set to 0, the width/height fields of the output frames will be set
2302      * to the coded dimensions and the crop_* fields will describe the cropping
2303      * rectangle. Applying the cropping is left to the caller.
2304      *
2305      * @warning When hardware acceleration with opaque output frames is used,
2306      * libavcodec is unable to apply cropping from the top/left border.
2307      *
2308      * @note when this option is set to zero, the width/height fields of the
2309      * AVCodecContext and output AVFrames have different meanings. The codec
2310      * context fields store display dimensions (with the coded dimensions in
2311      * coded_width/height), while the frame fields store the coded dimensions
2312      * (with the display dimensions being determined by the crop_* fields).
2313      */
2314     int apply_cropping;
2315
2316     /*
2317      * Video decoding only.  Sets the number of extra hardware frames which
2318      * the decoder will allocate for use by the caller.  This must be set
2319      * before avcodec_open2() is called.
2320      *
2321      * Some hardware decoders require all frames that they will use for
2322      * output to be defined in advance before decoding starts.  For such
2323      * decoders, the hardware frame pool must therefore be of a fixed size.
2324      * The extra frames set here are on top of any number that the decoder
2325      * needs internally in order to operate normally (for example, frames
2326      * used as reference pictures).
2327      */
2328     int extra_hw_frames;
2329
2330     /**
2331      * The percentage of damaged samples to discard a frame.
2332      *
2333      * - decoding: set by user
2334      * - encoding: unused
2335      */
2336     int discard_damaged_percentage;
2337
2338     /**
2339      * The number of samples per frame to maximally accept.
2340      *
2341      * - decoding: set by user
2342      * - encoding: set by user
2343      */
2344     int64_t max_samples;
2345
2346     /**
2347      * Bit set of AV_CODEC_EXPORT_DATA_* flags, which affects the kind of
2348      * metadata exported in frame, packet, or coded stream side data by
2349      * decoders and encoders.
2350      *
2351      * - decoding: set by user
2352      * - encoding: set by user
2353      */
2354     int export_side_data;
2355 } AVCodecContext;
2356
2357 #if FF_API_CODEC_GET_SET
2358 /**
2359  * Accessors for some AVCodecContext fields. These used to be provided for ABI
2360  * compatibility, and do not need to be used anymore.
2361  */
2362 attribute_deprecated
2363 AVRational av_codec_get_pkt_timebase         (const AVCodecContext *avctx);
2364 attribute_deprecated
2365 void       av_codec_set_pkt_timebase         (AVCodecContext *avctx, AVRational val);
2366
2367 attribute_deprecated
2368 const AVCodecDescriptor *av_codec_get_codec_descriptor(const AVCodecContext *avctx);
2369 attribute_deprecated
2370 void                     av_codec_set_codec_descriptor(AVCodecContext *avctx, const AVCodecDescriptor *desc);
2371
2372 attribute_deprecated
2373 unsigned av_codec_get_codec_properties(const AVCodecContext *avctx);
2374
2375 #if FF_API_LOWRES
2376 attribute_deprecated
2377 int  av_codec_get_lowres(const AVCodecContext *avctx);
2378 attribute_deprecated
2379 void av_codec_set_lowres(AVCodecContext *avctx, int val);
2380 #endif
2381
2382 attribute_deprecated
2383 int  av_codec_get_seek_preroll(const AVCodecContext *avctx);
2384 attribute_deprecated
2385 void av_codec_set_seek_preroll(AVCodecContext *avctx, int val);
2386
2387 attribute_deprecated
2388 uint16_t *av_codec_get_chroma_intra_matrix(const AVCodecContext *avctx);
2389 attribute_deprecated
2390 void av_codec_set_chroma_intra_matrix(AVCodecContext *avctx, uint16_t *val);
2391 #endif
2392
2393 struct AVSubtitle;
2394
2395 #if FF_API_CODEC_GET_SET
2396 attribute_deprecated
2397 int av_codec_get_max_lowres(const AVCodec *codec);
2398 #endif
2399
2400 struct MpegEncContext;
2401
2402 /**
2403  * @defgroup lavc_hwaccel AVHWAccel
2404  *
2405  * @note  Nothing in this structure should be accessed by the user.  At some
2406  *        point in future it will not be externally visible at all.
2407  *
2408  * @{
2409  */
2410 typedef struct AVHWAccel {
2411     /**
2412      * Name of the hardware accelerated codec.
2413      * The name is globally unique among encoders and among decoders (but an
2414      * encoder and a decoder can share the same name).
2415      */
2416     const char *name;
2417
2418     /**
2419      * Type of codec implemented by the hardware accelerator.
2420      *
2421      * See AVMEDIA_TYPE_xxx
2422      */
2423     enum AVMediaType type;
2424
2425     /**
2426      * Codec implemented by the hardware accelerator.
2427      *
2428      * See AV_CODEC_ID_xxx
2429      */
2430     enum AVCodecID id;
2431
2432     /**
2433      * Supported pixel format.
2434      *
2435      * Only hardware accelerated formats are supported here.
2436      */
2437     enum AVPixelFormat pix_fmt;
2438
2439     /**
2440      * Hardware accelerated codec capabilities.
2441      * see AV_HWACCEL_CODEC_CAP_*
2442      */
2443     int capabilities;
2444
2445     /*****************************************************************
2446      * No fields below this line are part of the public API. They
2447      * may not be used outside of libavcodec and can be changed and
2448      * removed at will.
2449      * New public fields should be added right above.
2450      *****************************************************************
2451      */
2452
2453     /**
2454      * Allocate a custom buffer
2455      */
2456     int (*alloc_frame)(AVCodecContext *avctx, AVFrame *frame);
2457
2458     /**
2459      * Called at the beginning of each frame or field picture.
2460      *
2461      * Meaningful frame information (codec specific) is guaranteed to
2462      * be parsed at this point. This function is mandatory.
2463      *
2464      * Note that buf can be NULL along with buf_size set to 0.
2465      * Otherwise, this means the whole frame is available at this point.
2466      *
2467      * @param avctx the codec context
2468      * @param buf the frame data buffer base
2469      * @param buf_size the size of the frame in bytes
2470      * @return zero if successful, a negative value otherwise
2471      */
2472     int (*start_frame)(AVCodecContext *avctx, const uint8_t *buf, uint32_t buf_size);
2473
2474     /**
2475      * Callback for parameter data (SPS/PPS/VPS etc).
2476      *
2477      * Useful for hardware decoders which keep persistent state about the
2478      * video parameters, and need to receive any changes to update that state.
2479      *
2480      * @param avctx the codec context
2481      * @param type the nal unit type
2482      * @param buf the nal unit data buffer
2483      * @param buf_size the size of the nal unit in bytes
2484      * @return zero if successful, a negative value otherwise
2485      */
2486     int (*decode_params)(AVCodecContext *avctx, int type, const uint8_t *buf, uint32_t buf_size);
2487
2488     /**
2489      * Callback for each slice.
2490      *
2491      * Meaningful slice information (codec specific) is guaranteed to
2492      * be parsed at this point. This function is mandatory.
2493      * The only exception is XvMC, that works on MB level.
2494      *
2495      * @param avctx the codec context
2496      * @param buf the slice data buffer base
2497      * @param buf_size the size of the slice in bytes
2498      * @return zero if successful, a negative value otherwise
2499      */
2500     int (*decode_slice)(AVCodecContext *avctx, const uint8_t *buf, uint32_t buf_size);
2501
2502     /**
2503      * Called at the end of each frame or field picture.
2504      *
2505      * The whole picture is parsed at this point and can now be sent
2506      * to the hardware accelerator. This function is mandatory.
2507      *
2508      * @param avctx the codec context
2509      * @return zero if successful, a negative value otherwise
2510      */
2511     int (*end_frame)(AVCodecContext *avctx);
2512
2513     /**
2514      * Size of per-frame hardware accelerator private data.
2515      *
2516      * Private data is allocated with av_mallocz() before
2517      * AVCodecContext.get_buffer() and deallocated after
2518      * AVCodecContext.release_buffer().
2519      */
2520     int frame_priv_data_size;
2521
2522     /**
2523      * Called for every Macroblock in a slice.
2524      *
2525      * XvMC uses it to replace the ff_mpv_reconstruct_mb().
2526      * Instead of decoding to raw picture, MB parameters are
2527      * stored in an array provided by the video driver.
2528      *
2529      * @param s the mpeg context
2530      */
2531     void (*decode_mb)(struct MpegEncContext *s);
2532
2533     /**
2534      * Initialize the hwaccel private data.
2535      *
2536      * This will be called from ff_get_format(), after hwaccel and
2537      * hwaccel_context are set and the hwaccel private data in AVCodecInternal
2538      * is allocated.
2539      */
2540     int (*init)(AVCodecContext *avctx);
2541
2542     /**
2543      * Uninitialize the hwaccel private data.
2544      *
2545      * This will be called from get_format() or avcodec_close(), after hwaccel
2546      * and hwaccel_context are already uninitialized.
2547      */
2548     int (*uninit)(AVCodecContext *avctx);
2549
2550     /**
2551      * Size of the private data to allocate in
2552      * AVCodecInternal.hwaccel_priv_data.
2553      */
2554     int priv_data_size;
2555
2556     /**
2557      * Internal hwaccel capabilities.
2558      */
2559     int caps_internal;
2560
2561     /**
2562      * Fill the given hw_frames context with current codec parameters. Called
2563      * from get_format. Refer to avcodec_get_hw_frames_parameters() for
2564      * details.
2565      *
2566      * This CAN be called before AVHWAccel.init is called, and you must assume
2567      * that avctx->hwaccel_priv_data is invalid.
2568      */
2569     int (*frame_params)(AVCodecContext *avctx, AVBufferRef *hw_frames_ctx);
2570 } AVHWAccel;
2571
2572 /**
2573  * HWAccel is experimental and is thus avoided in favor of non experimental
2574  * codecs
2575  */
2576 #define AV_HWACCEL_CODEC_CAP_EXPERIMENTAL 0x0200
2577
2578 /**
2579  * Hardware acceleration should be used for decoding even if the codec level
2580  * used is unknown or higher than the maximum supported level reported by the
2581  * hardware driver.
2582  *
2583  * It's generally a good idea to pass this flag unless you have a specific
2584  * reason not to, as hardware tends to under-report supported levels.
2585  */
2586 #define AV_HWACCEL_FLAG_IGNORE_LEVEL (1 << 0)
2587
2588 /**
2589  * Hardware acceleration can output YUV pixel formats with a different chroma
2590  * sampling than 4:2:0 and/or other than 8 bits per component.
2591  */
2592 #define AV_HWACCEL_FLAG_ALLOW_HIGH_DEPTH (1 << 1)
2593
2594 /**
2595  * Hardware acceleration should still be attempted for decoding when the
2596  * codec profile does not match the reported capabilities of the hardware.
2597  *
2598  * For example, this can be used to try to decode baseline profile H.264
2599  * streams in hardware - it will often succeed, because many streams marked
2600  * as baseline profile actually conform to constrained baseline profile.
2601  *
2602  * @warning If the stream is actually not supported then the behaviour is
2603  *          undefined, and may include returning entirely incorrect output
2604  *          while indicating success.
2605  */
2606 #define AV_HWACCEL_FLAG_ALLOW_PROFILE_MISMATCH (1 << 2)
2607
2608 /**
2609  * @}
2610  */
2611
2612 #if FF_API_AVPICTURE
2613 /**
2614  * @defgroup lavc_picture AVPicture
2615  *
2616  * Functions for working with AVPicture
2617  * @{
2618  */
2619
2620 /**
2621  * Picture data structure.
2622  *
2623  * Up to four components can be stored into it, the last component is
2624  * alpha.
2625  * @deprecated use AVFrame or imgutils functions instead
2626  */
2627 typedef struct AVPicture {
2628     attribute_deprecated
2629     uint8_t *data[AV_NUM_DATA_POINTERS];    ///< pointers to the image data planes
2630     attribute_deprecated
2631     int linesize[AV_NUM_DATA_POINTERS];     ///< number of bytes per line
2632 } AVPicture;
2633
2634 /**
2635  * @}
2636  */
2637 #endif
2638
2639 enum AVSubtitleType {
2640     SUBTITLE_NONE,
2641
2642     SUBTITLE_BITMAP,                ///< A bitmap, pict will be set
2643
2644     /**
2645      * Plain text, the text field must be set by the decoder and is
2646      * authoritative. ass and pict fields may contain approximations.
2647      */
2648     SUBTITLE_TEXT,
2649
2650     /**
2651      * Formatted text, the ass field must be set by the decoder and is
2652      * authoritative. pict and text fields may contain approximations.
2653      */
2654     SUBTITLE_ASS,
2655 };
2656
2657 #define AV_SUBTITLE_FLAG_FORCED 0x00000001
2658
2659 typedef struct AVSubtitleRect {
2660     int x;         ///< top left corner  of pict, undefined when pict is not set
2661     int y;         ///< top left corner  of pict, undefined when pict is not set
2662     int w;         ///< width            of pict, undefined when pict is not set
2663     int h;         ///< height           of pict, undefined when pict is not set
2664     int nb_colors; ///< number of colors in pict, undefined when pict is not set
2665
2666 #if FF_API_AVPICTURE
2667     /**
2668      * @deprecated unused
2669      */
2670     attribute_deprecated
2671     AVPicture pict;
2672 #endif
2673     /**
2674      * data+linesize for the bitmap of this subtitle.
2675      * Can be set for text/ass as well once they are rendered.
2676      */
2677     uint8_t *data[4];
2678     int linesize[4];
2679
2680     enum AVSubtitleType type;
2681
2682     char *text;                     ///< 0 terminated plain UTF-8 text
2683
2684     /**
2685      * 0 terminated ASS/SSA compatible event line.
2686      * The presentation of this is unaffected by the other values in this
2687      * struct.
2688      */
2689     char *ass;
2690
2691     int flags;
2692 } AVSubtitleRect;
2693
2694 typedef struct AVSubtitle {
2695     uint16_t format; /* 0 = graphics */
2696     uint32_t start_display_time; /* relative to packet pts, in ms */
2697     uint32_t end_display_time; /* relative to packet pts, in ms */
2698     unsigned num_rects;
2699     AVSubtitleRect **rects;
2700     int64_t pts;    ///< Same as packet pts, in AV_TIME_BASE
2701 } AVSubtitle;
2702
2703 #if FF_API_NEXT
2704 /**
2705  * If c is NULL, returns the first registered codec,
2706  * if c is non-NULL, returns the next registered codec after c,
2707  * or NULL if c is the last one.
2708  */
2709 attribute_deprecated
2710 AVCodec *av_codec_next(const AVCodec *c);
2711 #endif
2712
2713 /**
2714  * Return the LIBAVCODEC_VERSION_INT constant.
2715  */
2716 unsigned avcodec_version(void);
2717
2718 /**
2719  * Return the libavcodec build-time configuration.
2720  */
2721 const char *avcodec_configuration(void);
2722
2723 /**
2724  * Return the libavcodec license.
2725  */
2726 const char *avcodec_license(void);
2727
2728 #if FF_API_NEXT
2729 /**
2730  * Register the codec codec and initialize libavcodec.
2731  *
2732  * @warning either this function or avcodec_register_all() must be called
2733  * before any other libavcodec functions.
2734  *
2735  * @see avcodec_register_all()
2736  */
2737 attribute_deprecated
2738 void avcodec_register(AVCodec *codec);
2739
2740 /**
2741  * Register all the codecs, parsers and bitstream filters which were enabled at
2742  * configuration time. If you do not call this function you can select exactly
2743  * which formats you want to support, by using the individual registration
2744  * functions.
2745  *
2746  * @see avcodec_register
2747  * @see av_register_codec_parser
2748  * @see av_register_bitstream_filter
2749  */
2750 attribute_deprecated
2751 void avcodec_register_all(void);
2752 #endif
2753
2754 /**
2755  * Allocate an AVCodecContext and set its fields to default values. The
2756  * resulting struct should be freed with avcodec_free_context().
2757  *
2758  * @param codec if non-NULL, allocate private data and initialize defaults
2759  *              for the given codec. It is illegal to then call avcodec_open2()
2760  *              with a different codec.
2761  *              If NULL, then the codec-specific defaults won't be initialized,
2762  *              which may result in suboptimal default settings (this is
2763  *              important mainly for encoders, e.g. libx264).
2764  *
2765  * @return An AVCodecContext filled with default values or NULL on failure.
2766  */
2767 AVCodecContext *avcodec_alloc_context3(const AVCodec *codec);
2768
2769 /**
2770  * Free the codec context and everything associated with it and write NULL to
2771  * the provided pointer.
2772  */
2773 void avcodec_free_context(AVCodecContext **avctx);
2774
2775 #if FF_API_GET_CONTEXT_DEFAULTS
2776 /**
2777  * @deprecated This function should not be used, as closing and opening a codec
2778  * context multiple time is not supported. A new codec context should be
2779  * allocated for each new use.
2780  */
2781 int avcodec_get_context_defaults3(AVCodecContext *s, const AVCodec *codec);
2782 #endif
2783
2784 /**
2785  * Get the AVClass for AVCodecContext. It can be used in combination with
2786  * AV_OPT_SEARCH_FAKE_OBJ for examining options.
2787  *
2788  * @see av_opt_find().
2789  */
2790 const AVClass *avcodec_get_class(void);
2791
2792 #if FF_API_COPY_CONTEXT
2793 /**
2794  * Get the AVClass for AVFrame. It can be used in combination with
2795  * AV_OPT_SEARCH_FAKE_OBJ for examining options.
2796  *
2797  * @see av_opt_find().
2798  */
2799 const AVClass *avcodec_get_frame_class(void);
2800
2801 /**
2802  * Get the AVClass for AVSubtitleRect. It can be used in combination with
2803  * AV_OPT_SEARCH_FAKE_OBJ for examining options.
2804  *
2805  * @see av_opt_find().
2806  */
2807 const AVClass *avcodec_get_subtitle_rect_class(void);
2808
2809 /**
2810  * Copy the settings of the source AVCodecContext into the destination
2811  * AVCodecContext. The resulting destination codec context will be
2812  * unopened, i.e. you are required to call avcodec_open2() before you
2813  * can use this AVCodecContext to decode/encode video/audio data.
2814  *
2815  * @param dest target codec context, should be initialized with
2816  *             avcodec_alloc_context3(NULL), but otherwise uninitialized
2817  * @param src source codec context
2818  * @return AVERROR() on error (e.g. memory allocation error), 0 on success
2819  *
2820  * @deprecated The semantics of this function are ill-defined and it should not
2821  * be used. If you need to transfer the stream parameters from one codec context
2822  * to another, use an intermediate AVCodecParameters instance and the
2823  * avcodec_parameters_from_context() / avcodec_parameters_to_context()
2824  * functions.
2825  */
2826 attribute_deprecated
2827 int avcodec_copy_context(AVCodecContext *dest, const AVCodecContext *src);
2828 #endif
2829
2830 /**
2831  * Fill the parameters struct based on the values from the supplied codec
2832  * context. Any allocated fields in par are freed and replaced with duplicates
2833  * of the corresponding fields in codec.
2834  *
2835  * @return >= 0 on success, a negative AVERROR code on failure
2836  */
2837 int avcodec_parameters_from_context(AVCodecParameters *par,
2838                                     const AVCodecContext *codec);
2839
2840 /**
2841  * Fill the codec context based on the values from the supplied codec
2842  * parameters. Any allocated fields in codec that have a corresponding field in
2843  * par are freed and replaced with duplicates of the corresponding field in par.
2844  * Fields in codec that do not have a counterpart in par are not touched.
2845  *
2846  * @return >= 0 on success, a negative AVERROR code on failure.
2847  */
2848 int avcodec_parameters_to_context(AVCodecContext *codec,
2849                                   const AVCodecParameters *par);
2850
2851 /**
2852  * Initialize the AVCodecContext to use the given AVCodec. Prior to using this
2853  * function the context has to be allocated with avcodec_alloc_context3().
2854  *
2855  * The functions avcodec_find_decoder_by_name(), avcodec_find_encoder_by_name(),
2856  * avcodec_find_decoder() and avcodec_find_encoder() provide an easy way for
2857  * retrieving a codec.
2858  *
2859  * @warning This function is not thread safe!
2860  *
2861  * @note Always call this function before using decoding routines (such as
2862  * @ref avcodec_receive_frame()).
2863  *
2864  * @code
2865  * avcodec_register_all();
2866  * av_dict_set(&opts, "b", "2.5M", 0);
2867  * codec = avcodec_find_decoder(AV_CODEC_ID_H264);
2868  * if (!codec)
2869  *     exit(1);
2870  *
2871  * context = avcodec_alloc_context3(codec);
2872  *
2873  * if (avcodec_open2(context, codec, opts) < 0)
2874  *     exit(1);
2875  * @endcode
2876  *
2877  * @param avctx The context to initialize.
2878  * @param codec The codec to open this context for. If a non-NULL codec has been
2879  *              previously passed to avcodec_alloc_context3() or
2880  *              for this context, then this parameter MUST be either NULL or
2881  *              equal to the previously passed codec.
2882  * @param options A dictionary filled with AVCodecContext and codec-private options.
2883  *                On return this object will be filled with options that were not found.
2884  *
2885  * @return zero on success, a negative value on error
2886  * @see avcodec_alloc_context3(), avcodec_find_decoder(), avcodec_find_encoder(),
2887  *      av_dict_set(), av_opt_find().
2888  */
2889 int avcodec_open2(AVCodecContext *avctx, const AVCodec *codec, AVDictionary **options);
2890
2891 /**
2892  * Close a given AVCodecContext and free all the data associated with it
2893  * (but not the AVCodecContext itself).
2894  *
2895  * Calling this function on an AVCodecContext that hasn't been opened will free
2896  * the codec-specific data allocated in avcodec_alloc_context3() with a non-NULL
2897  * codec. Subsequent calls will do nothing.
2898  *
2899  * @note Do not use this function. Use avcodec_free_context() to destroy a
2900  * codec context (either open or closed). Opening and closing a codec context
2901  * multiple times is not supported anymore -- use multiple codec contexts
2902  * instead.
2903  */
2904 int avcodec_close(AVCodecContext *avctx);
2905
2906 /**
2907  * Free all allocated data in the given subtitle struct.
2908  *
2909  * @param sub AVSubtitle to free.
2910  */
2911 void avsubtitle_free(AVSubtitle *sub);
2912
2913 /**
2914  * @}
2915  */
2916
2917 /**
2918  * @addtogroup lavc_decoding
2919  * @{
2920  */
2921
2922 /**
2923  * The default callback for AVCodecContext.get_buffer2(). It is made public so
2924  * it can be called by custom get_buffer2() implementations for decoders without
2925  * AV_CODEC_CAP_DR1 set.
2926  */
2927 int avcodec_default_get_buffer2(AVCodecContext *s, AVFrame *frame, int flags);
2928
2929 /**
2930  * Modify width and height values so that they will result in a memory
2931  * buffer that is acceptable for the codec if you do not use any horizontal
2932  * padding.
2933  *
2934  * May only be used if a codec with AV_CODEC_CAP_DR1 has been opened.
2935  */
2936 void avcodec_align_dimensions(AVCodecContext *s, int *width, int *height);
2937
2938 /**
2939  * Modify width and height values so that they will result in a memory
2940  * buffer that is acceptable for the codec if you also ensure that all
2941  * line sizes are a multiple of the respective linesize_align[i].
2942  *
2943  * May only be used if a codec with AV_CODEC_CAP_DR1 has been opened.
2944  */
2945 void avcodec_align_dimensions2(AVCodecContext *s, int *width, int *height,
2946                                int linesize_align[AV_NUM_DATA_POINTERS]);
2947
2948 /**
2949  * Converts AVChromaLocation to swscale x/y chroma position.
2950  *
2951  * The positions represent the chroma (0,0) position in a coordinates system
2952  * with luma (0,0) representing the origin and luma(1,1) representing 256,256
2953  *
2954  * @param xpos  horizontal chroma sample position
2955  * @param ypos  vertical   chroma sample position
2956  */
2957 int avcodec_enum_to_chroma_pos(int *xpos, int *ypos, enum AVChromaLocation pos);
2958
2959 /**
2960  * Converts swscale x/y chroma position to AVChromaLocation.
2961  *
2962  * The positions represent the chroma (0,0) position in a coordinates system
2963  * with luma (0,0) representing the origin and luma(1,1) representing 256,256
2964  *
2965  * @param xpos  horizontal chroma sample position
2966  * @param ypos  vertical   chroma sample position
2967  */
2968 enum AVChromaLocation avcodec_chroma_pos_to_enum(int xpos, int ypos);
2969
2970 /**
2971  * Decode the audio frame of size avpkt->size from avpkt->data into frame.
2972  *
2973  * Some decoders may support multiple frames in a single AVPacket. Such
2974  * decoders would then just decode the first frame and the return value would be
2975  * less than the packet size. In this case, avcodec_decode_audio4 has to be
2976  * called again with an AVPacket containing the remaining data in order to
2977  * decode the second frame, etc...  Even if no frames are returned, the packet
2978  * needs to be fed to the decoder with remaining data until it is completely
2979  * consumed or an error occurs.
2980  *
2981  * Some decoders (those marked with AV_CODEC_CAP_DELAY) have a delay between input
2982  * and output. This means that for some packets they will not immediately
2983  * produce decoded output and need to be flushed at the end of decoding to get
2984  * all the decoded data. Flushing is done by calling this function with packets
2985  * with avpkt->data set to NULL and avpkt->size set to 0 until it stops
2986  * returning samples. It is safe to flush even those decoders that are not
2987  * marked with AV_CODEC_CAP_DELAY, then no samples will be returned.
2988  *
2989  * @warning The input buffer, avpkt->data must be AV_INPUT_BUFFER_PADDING_SIZE
2990  *          larger than the actual read bytes because some optimized bitstream
2991  *          readers read 32 or 64 bits at once and could read over the end.
2992  *
2993  * @note The AVCodecContext MUST have been opened with @ref avcodec_open2()
2994  * before packets may be fed to the decoder.
2995  *
2996  * @param      avctx the codec context
2997  * @param[out] frame The AVFrame in which to store decoded audio samples.
2998  *                   The decoder will allocate a buffer for the decoded frame by
2999  *                   calling the AVCodecContext.get_buffer2() callback.
3000  *                   When AVCodecContext.refcounted_frames is set to 1, the frame is
3001  *                   reference counted and the returned reference belongs to the
3002  *                   caller. The caller must release the frame using av_frame_unref()
3003  *                   when the frame is no longer needed. The caller may safely write
3004  *                   to the frame if av_frame_is_writable() returns 1.
3005  *                   When AVCodecContext.refcounted_frames is set to 0, the returned
3006  *                   reference belongs to the decoder and is valid only until the
3007  *                   next call to this function or until closing or flushing the
3008  *                   decoder. The caller may not write to it.
3009  * @param[out] got_frame_ptr Zero if no frame could be decoded, otherwise it is
3010  *                           non-zero. Note that this field being set to zero
3011  *                           does not mean that an error has occurred. For
3012  *                           decoders with AV_CODEC_CAP_DELAY set, no given decode
3013  *                           call is guaranteed to produce a frame.
3014  * @param[in]  avpkt The input AVPacket containing the input buffer.
3015  *                   At least avpkt->data and avpkt->size should be set. Some
3016  *                   decoders might also require additional fields to be set.
3017  * @return A negative error code is returned if an error occurred during
3018  *         decoding, otherwise the number of bytes consumed from the input
3019  *         AVPacket is returned.
3020  *
3021 * @deprecated Use avcodec_send_packet() and avcodec_receive_frame().
3022  */
3023 attribute_deprecated
3024 int avcodec_decode_audio4(AVCodecContext *avctx, AVFrame *frame,
3025                           int *got_frame_ptr, const AVPacket *avpkt);
3026
3027 /**
3028  * Decode the video frame of size avpkt->size from avpkt->data into picture.
3029  * Some decoders may support multiple frames in a single AVPacket, such
3030  * decoders would then just decode the first frame.
3031  *
3032  * @warning The input buffer must be AV_INPUT_BUFFER_PADDING_SIZE larger than
3033  * the actual read bytes because some optimized bitstream readers read 32 or 64
3034  * bits at once and could read over the end.
3035  *
3036  * @warning The end of the input buffer buf should be set to 0 to ensure that
3037  * no overreading happens for damaged MPEG streams.
3038  *
3039  * @note Codecs which have the AV_CODEC_CAP_DELAY capability set have a delay
3040  * between input and output, these need to be fed with avpkt->data=NULL,
3041  * avpkt->size=0 at the end to return the remaining frames.
3042  *
3043  * @note The AVCodecContext MUST have been opened with @ref avcodec_open2()
3044  * before packets may be fed to the decoder.
3045  *
3046  * @param avctx the codec context
3047  * @param[out] picture The AVFrame in which the decoded video frame will be stored.
3048  *             Use av_frame_alloc() to get an AVFrame. The codec will
3049  *             allocate memory for the actual bitmap by calling the
3050  *             AVCodecContext.get_buffer2() callback.
3051  *             When AVCodecContext.refcounted_frames is set to 1, the frame is
3052  *             reference counted and the returned reference belongs to the
3053  *             caller. The caller must release the frame using av_frame_unref()
3054  *             when the frame is no longer needed. The caller may safely write
3055  *             to the frame if av_frame_is_writable() returns 1.
3056  *             When AVCodecContext.refcounted_frames is set to 0, the returned
3057  *             reference belongs to the decoder and is valid only until the
3058  *             next call to this function or until closing or flushing the
3059  *             decoder. The caller may not write to it.
3060  *
3061  * @param[in] avpkt The input AVPacket containing the input buffer.
3062  *            You can create such packet with av_init_packet() and by then setting
3063  *            data and size, some decoders might in addition need other fields like
3064  *            flags&AV_PKT_FLAG_KEY. All decoders are designed to use the least
3065  *            fields possible.
3066  * @param[in,out] got_picture_ptr Zero if no frame could be decompressed, otherwise, it is nonzero.
3067  * @return On error a negative value is returned, otherwise the number of bytes
3068  * used or zero if no frame could be decompressed.
3069  *
3070  * @deprecated Use avcodec_send_packet() and avcodec_receive_frame().
3071  */
3072 attribute_deprecated
3073 int avcodec_decode_video2(AVCodecContext *avctx, AVFrame *picture,
3074                          int *got_picture_ptr,
3075                          const AVPacket *avpkt);
3076
3077 /**
3078  * Decode a subtitle message.
3079  * Return a negative value on error, otherwise return the number of bytes used.
3080  * If no subtitle could be decompressed, got_sub_ptr is zero.
3081  * Otherwise, the subtitle is stored in *sub.
3082  * Note that AV_CODEC_CAP_DR1 is not available for subtitle codecs. This is for
3083  * simplicity, because the performance difference is expected to be negligible
3084  * and reusing a get_buffer written for video codecs would probably perform badly
3085  * due to a potentially very different allocation pattern.
3086  *
3087  * Some decoders (those marked with AV_CODEC_CAP_DELAY) have a delay between input
3088  * and output. This means that for some packets they will not immediately
3089  * produce decoded output and need to be flushed at the end of decoding to get
3090  * all the decoded data. Flushing is done by calling this function with packets
3091  * with avpkt->data set to NULL and avpkt->size set to 0 until it stops
3092  * returning subtitles. It is safe to flush even those decoders that are not
3093  * marked with AV_CODEC_CAP_DELAY, then no subtitles will be returned.
3094  *
3095  * @note The AVCodecContext MUST have been opened with @ref avcodec_open2()
3096  * before packets may be fed to the decoder.
3097  *
3098  * @param avctx the codec context
3099  * @param[out] sub The preallocated AVSubtitle in which the decoded subtitle will be stored,
3100  *                 must be freed with avsubtitle_free if *got_sub_ptr is set.
3101  * @param[in,out] got_sub_ptr Zero if no subtitle could be decompressed, otherwise, it is nonzero.
3102  * @param[in] avpkt The input AVPacket containing the input buffer.
3103  */
3104 int avcodec_decode_subtitle2(AVCodecContext *avctx, AVSubtitle *sub,
3105                             int *got_sub_ptr,
3106                             AVPacket *avpkt);
3107
3108 /**
3109  * Supply raw packet data as input to a decoder.
3110  *
3111  * Internally, this call will copy relevant AVCodecContext fields, which can
3112  * influence decoding per-packet, and apply them when the packet is actually
3113  * decoded. (For example AVCodecContext.skip_frame, which might direct the
3114  * decoder to drop the frame contained by the packet sent with this function.)
3115  *
3116  * @warning The input buffer, avpkt->data must be AV_INPUT_BUFFER_PADDING_SIZE
3117  *          larger than the actual read bytes because some optimized bitstream
3118  *          readers read 32 or 64 bits at once and could read over the end.
3119  *
3120  * @warning Do not mix this API with the legacy API (like avcodec_decode_video2())
3121  *          on the same AVCodecContext. It will return unexpected results now
3122  *          or in future libavcodec versions.
3123  *
3124  * @note The AVCodecContext MUST have been opened with @ref avcodec_open2()
3125  *       before packets may be fed to the decoder.
3126  *
3127  * @param avctx codec context
3128  * @param[in] avpkt The input AVPacket. Usually, this will be a single video
3129  *                  frame, or several complete audio frames.
3130  *                  Ownership of the packet remains with the caller, and the
3131  *                  decoder will not write to the packet. The decoder may create
3132  *                  a reference to the packet data (or copy it if the packet is
3133  *                  not reference-counted).
3134  *                  Unlike with older APIs, the packet is always fully consumed,
3135  *                  and if it contains multiple frames (e.g. some audio codecs),
3136  *                  will require you to call avcodec_receive_frame() multiple
3137  *                  times afterwards before you can send a new packet.
3138  *                  It can be NULL (or an AVPacket with data set to NULL and
3139  *                  size set to 0); in this case, it is considered a flush
3140  *                  packet, which signals the end of the stream. Sending the
3141  *                  first flush packet will return success. Subsequent ones are
3142  *                  unnecessary and will return AVERROR_EOF. If the decoder
3143  *                  still has frames buffered, it will return them after sending
3144  *                  a flush packet.
3145  *
3146  * @return 0 on success, otherwise negative error code:
3147  *      AVERROR(EAGAIN):   input is not accepted in the current state - user
3148  *                         must read output with avcodec_receive_frame() (once
3149  *                         all output is read, the packet should be resent, and
3150  *                         the call will not fail with EAGAIN).
3151  *      AVERROR_EOF:       the decoder has been flushed, and no new packets can
3152  *                         be sent to it (also returned if more than 1 flush
3153  *                         packet is sent)
3154  *      AVERROR(EINVAL):   codec not opened, it is an encoder, or requires flush
3155  *      AVERROR(ENOMEM):   failed to add packet to internal queue, or similar
3156  *      other errors: legitimate decoding errors
3157  */
3158 int avcodec_send_packet(AVCodecContext *avctx, const AVPacket *avpkt);
3159
3160 /**
3161  * Return decoded output data from a decoder.
3162  *
3163  * @param avctx codec context
3164  * @param frame This will be set to a reference-counted video or audio
3165  *              frame (depending on the decoder type) allocated by the
3166  *              decoder. Note that the function will always call
3167  *              av_frame_unref(frame) before doing anything else.
3168  *
3169  * @return
3170  *      0:                 success, a frame was returned
3171  *      AVERROR(EAGAIN):   output is not available in this state - user must try
3172  *                         to send new input
3173  *      AVERROR_EOF:       the decoder has been fully flushed, and there will be
3174  *                         no more output frames
3175  *      AVERROR(EINVAL):   codec not opened, or it is an encoder
3176  *      AVERROR_INPUT_CHANGED:   current decoded frame has changed parameters
3177  *                               with respect to first decoded frame. Applicable
3178  *                               when flag AV_CODEC_FLAG_DROPCHANGED is set.
3179  *      other negative values: legitimate decoding errors
3180  */
3181 int avcodec_receive_frame(AVCodecContext *avctx, AVFrame *frame);
3182
3183 /**
3184  * Supply a raw video or audio frame to the encoder. Use avcodec_receive_packet()
3185  * to retrieve buffered output packets.
3186  *
3187  * @param avctx     codec context
3188  * @param[in] frame AVFrame containing the raw audio or video frame to be encoded.
3189  *                  Ownership of the frame remains with the caller, and the
3190  *                  encoder will not write to the frame. The encoder may create
3191  *                  a reference to the frame data (or copy it if the frame is
3192  *                  not reference-counted).
3193  *                  It can be NULL, in which case it is considered a flush
3194  *                  packet.  This signals the end of the stream. If the encoder
3195  *                  still has packets buffered, it will return them after this
3196  *                  call. Once flushing mode has been entered, additional flush
3197  *                  packets are ignored, and sending frames will return
3198  *                  AVERROR_EOF.
3199  *
3200  *                  For audio:
3201  *                  If AV_CODEC_CAP_VARIABLE_FRAME_SIZE is set, then each frame
3202  *                  can have any number of samples.
3203  *                  If it is not set, frame->nb_samples must be equal to
3204  *                  avctx->frame_size for all frames except the last.
3205  *                  The final frame may be smaller than avctx->frame_size.
3206  * @return 0 on success, otherwise negative error code:
3207  *      AVERROR(EAGAIN):   input is not accepted in the current state - user
3208  *                         must read output with avcodec_receive_packet() (once
3209  *                         all output is read, the packet should be resent, and
3210  *                         the call will not fail with EAGAIN).
3211  *      AVERROR_EOF:       the encoder has been flushed, and no new frames can
3212  *                         be sent to it
3213  *      AVERROR(EINVAL):   codec not opened, refcounted_frames not set, it is a
3214  *                         decoder, or requires flush
3215  *      AVERROR(ENOMEM):   failed to add packet to internal queue, or similar
3216  *      other errors: legitimate encoding errors
3217  */
3218 int avcodec_send_frame(AVCodecContext *avctx, const AVFrame *frame);
3219
3220 /**
3221  * Read encoded data from the encoder.
3222  *
3223  * @param avctx codec context
3224  * @param avpkt This will be set to a reference-counted packet allocated by the
3225  *              encoder. Note that the function will always call
3226  *              av_packet_unref(avpkt) before doing anything else.
3227  * @return 0 on success, otherwise negative error code:
3228  *      AVERROR(EAGAIN):   output is not available in the current state - user
3229  *                         must try to send input
3230  *      AVERROR_EOF:       the encoder has been fully flushed, and there will be
3231  *                         no more output packets
3232  *      AVERROR(EINVAL):   codec not opened, or it is a decoder
3233  *      other errors: legitimate encoding errors
3234  */
3235 int avcodec_receive_packet(AVCodecContext *avctx, AVPacket *avpkt);
3236
3237 /**
3238  * Create and return a AVHWFramesContext with values adequate for hardware
3239  * decoding. This is meant to get called from the get_format callback, and is
3240  * a helper for preparing a AVHWFramesContext for AVCodecContext.hw_frames_ctx.
3241  * This API is for decoding with certain hardware acceleration modes/APIs only.
3242  *
3243  * The returned AVHWFramesContext is not initialized. The caller must do this
3244  * with av_hwframe_ctx_init().
3245  *
3246  * Calling this function is not a requirement, but makes it simpler to avoid
3247  * codec or hardware API specific details when manually allocating frames.
3248  *
3249  * Alternatively to this, an API user can set AVCodecContext.hw_device_ctx,
3250  * which sets up AVCodecContext.hw_frames_ctx fully automatically, and makes
3251  * it unnecessary to call this function or having to care about
3252  * AVHWFramesContext initialization at all.
3253  *
3254  * There are a number of requirements for calling this function:
3255  *
3256  * - It must be called from get_format with the same avctx parameter that was
3257  *   passed to get_format. Calling it outside of get_format is not allowed, and
3258  *   can trigger undefined behavior.
3259  * - The function is not always supported (see description of return values).
3260  *   Even if this function returns successfully, hwaccel initialization could
3261  *   fail later. (The degree to which implementations check whether the stream
3262  *   is actually supported varies. Some do this check only after the user's
3263  *   get_format callback returns.)
3264  * - The hw_pix_fmt must be one of the choices suggested by get_format. If the
3265  *   user decides to use a AVHWFramesContext prepared with this API function,
3266  *   the user must return the same hw_pix_fmt from get_format.
3267  * - The device_ref passed to this function must support the given hw_pix_fmt.
3268  * - After calling this API function, it is the user's responsibility to
3269  *   initialize the AVHWFramesContext (returned by the out_frames_ref parameter),
3270  *   and to set AVCodecContext.hw_frames_ctx to it. If done, this must be done
3271  *   before returning from get_format (this is implied by the normal
3272  *   AVCodecContext.hw_frames_ctx API rules).
3273  * - The AVHWFramesContext parameters may change every time time get_format is
3274  *   called. Also, AVCodecContext.hw_frames_ctx is reset before get_format. So
3275  *   you are inherently required to go through this process again on every
3276  *   get_format call.
3277  * - It is perfectly possible to call this function without actually using
3278  *   the resulting AVHWFramesContext. One use-case might be trying to reuse a
3279  *   previously initialized AVHWFramesContext, and calling this API function
3280  *   only to test whether the required frame parameters have changed.
3281  * - Fields that use dynamically allocated values of any kind must not be set
3282  *   by the user unless setting them is explicitly allowed by the documentation.
3283  *   If the user sets AVHWFramesContext.free and AVHWFramesContext.user_opaque,
3284  *   the new free callback must call the potentially set previous free callback.
3285  *   This API call may set any dynamically allocated fields, including the free
3286  *   callback.
3287  *
3288  * The function will set at least the following fields on AVHWFramesContext
3289  * (potentially more, depending on hwaccel API):
3290  *
3291  * - All fields set by av_hwframe_ctx_alloc().
3292  * - Set the format field to hw_pix_fmt.
3293  * - Set the sw_format field to the most suited and most versatile format. (An
3294  *   implication is that this will prefer generic formats over opaque formats
3295  *   with arbitrary restrictions, if possible.)
3296  * - Set the width/height fields to the coded frame size, rounded up to the
3297  *   API-specific minimum alignment.
3298  * - Only _if_ the hwaccel requires a pre-allocated pool: set the initial_pool_size
3299  *   field to the number of maximum reference surfaces possible with the codec,
3300  *   plus 1 surface for the user to work (meaning the user can safely reference
3301  *   at most 1 decoded surface at a time), plus additional buffering introduced
3302  *   by frame threading. If the hwaccel does not require pre-allocation, the
3303  *   field is left to 0, and the decoder will allocate new surfaces on demand
3304  *   during decoding.
3305  * - Possibly AVHWFramesContext.hwctx fields, depending on the underlying
3306  *   hardware API.
3307  *
3308  * Essentially, out_frames_ref returns the same as av_hwframe_ctx_alloc(), but
3309  * with basic frame parameters set.
3310  *
3311  * The function is stateless, and does not change the AVCodecContext or the
3312  * device_ref AVHWDeviceContext.
3313  *
3314  * @param avctx The context which is currently calling get_format, and which
3315  *              implicitly contains all state needed for filling the returned
3316  *              AVHWFramesContext properly.
3317  * @param device_ref A reference to the AVHWDeviceContext describing the device
3318  *                   which will be used by the hardware decoder.
3319  * @param hw_pix_fmt The hwaccel format you are going to return from get_format.
3320  * @param out_frames_ref On success, set to a reference to an _uninitialized_
3321  *                       AVHWFramesContext, created from the given device_ref.
3322  *                       Fields will be set to values required for decoding.
3323  *                       Not changed if an error is returned.
3324  * @return zero on success, a negative value on error. The following error codes
3325  *         have special semantics:
3326  *      AVERROR(ENOENT): the decoder does not support this functionality. Setup
3327  *                       is always manual, or it is a decoder which does not
3328  *                       support setting AVCodecContext.hw_frames_ctx at all,
3329  *                       or it is a software format.
3330  *      AVERROR(EINVAL): it is known that hardware decoding is not supported for
3331  *                       this configuration, or the device_ref is not supported
3332  *                       for the hwaccel referenced by hw_pix_fmt.
3333  */
3334 int avcodec_get_hw_frames_parameters(AVCodecContext *avctx,
3335                                      AVBufferRef *device_ref,
3336                                      enum AVPixelFormat hw_pix_fmt,
3337                                      AVBufferRef **out_frames_ref);
3338
3339
3340
3341 /**
3342  * @defgroup lavc_parsing Frame parsing
3343  * @{
3344  */
3345
3346 enum AVPictureStructure {
3347     AV_PICTURE_STRUCTURE_UNKNOWN,      //< unknown
3348     AV_PICTURE_STRUCTURE_TOP_FIELD,    //< coded as top field
3349     AV_PICTURE_STRUCTURE_BOTTOM_FIELD, //< coded as bottom field
3350     AV_PICTURE_STRUCTURE_FRAME,        //< coded as frame
3351 };
3352
3353 typedef struct AVCodecParserContext {
3354     void *priv_data;
3355     struct AVCodecParser *parser;
3356     int64_t frame_offset; /* offset of the current frame */
3357     int64_t cur_offset; /* current offset
3358                            (incremented by each av_parser_parse()) */
3359     int64_t next_frame_offset; /* offset of the next frame */
3360     /* video info */
3361     int pict_type; /* XXX: Put it back in AVCodecContext. */
3362     /**
3363      * This field is used for proper frame duration computation in lavf.
3364      * It signals, how much longer the frame duration of the current frame
3365      * is compared to normal frame duration.
3366      *
3367      * frame_duration = (1 + repeat_pict) * time_base
3368      *
3369      * It is used by codecs like H.264 to display telecined material.
3370      */
3371     int repeat_pict; /* XXX: Put it back in AVCodecContext. */
3372     int64_t pts;     /* pts of the current frame */
3373     int64_t dts;     /* dts of the current frame */
3374
3375     /* private data */
3376     int64_t last_pts;
3377     int64_t last_dts;
3378     int fetch_timestamp;
3379
3380 #define AV_PARSER_PTS_NB 4
3381     int cur_frame_start_index;
3382     int64_t cur_frame_offset[AV_PARSER_PTS_NB];
3383     int64_t cur_frame_pts[AV_PARSER_PTS_NB];
3384     int64_t cur_frame_dts[AV_PARSER_PTS_NB];
3385
3386     int flags;
3387 #define PARSER_FLAG_COMPLETE_FRAMES           0x0001
3388 #define PARSER_FLAG_ONCE                      0x0002
3389 /// Set if the parser has a valid file offset
3390 #define PARSER_FLAG_FETCHED_OFFSET            0x0004
3391 #define PARSER_FLAG_USE_CODEC_TS              0x1000
3392
3393     int64_t offset;      ///< byte offset from starting packet start
3394     int64_t cur_frame_end[AV_PARSER_PTS_NB];
3395
3396     /**
3397      * Set by parser to 1 for key frames and 0 for non-key frames.
3398      * It is initialized to -1, so if the parser doesn't set this flag,
3399      * old-style fallback using AV_PICTURE_TYPE_I picture type as key frames
3400      * will be used.
3401      */
3402     int key_frame;
3403
3404 #if FF_API_CONVERGENCE_DURATION
3405     /**
3406      * @deprecated unused
3407      */
3408     attribute_deprecated
3409     int64_t convergence_duration;
3410 #endif
3411
3412     // Timestamp generation support:
3413     /**
3414      * Synchronization point for start of timestamp generation.
3415      *
3416      * Set to >0 for sync point, 0 for no sync point and <0 for undefined
3417      * (default).
3418      *
3419      * For example, this corresponds to presence of H.264 buffering period
3420      * SEI message.
3421      */
3422     int dts_sync_point;
3423
3424     /**
3425      * Offset of the current timestamp against last timestamp sync point in
3426      * units of AVCodecContext.time_base.
3427      *
3428      * Set to INT_MIN when dts_sync_point unused. Otherwise, it must
3429      * contain a valid timestamp offset.
3430      *
3431      * Note that the timestamp of sync point has usually a nonzero
3432      * dts_ref_dts_delta, which refers to the previous sync point. Offset of
3433      * the next frame after timestamp sync point will be usually 1.
3434      *
3435      * For example, this corresponds to H.264 cpb_removal_delay.
3436      */
3437     int dts_ref_dts_delta;
3438
3439     /**
3440      * Presentation delay of current frame in units of AVCodecContext.time_base.
3441      *
3442      * Set to INT_MIN when dts_sync_point unused. Otherwise, it must
3443      * contain valid non-negative timestamp delta (presentation time of a frame
3444      * must not lie in the past).
3445      *
3446      * This delay represents the difference between decoding and presentation
3447      * time of the frame.
3448      *
3449      * For example, this corresponds to H.264 dpb_output_delay.
3450      */
3451     int pts_dts_delta;
3452
3453     /**
3454      * Position of the packet in file.
3455      *
3456      * Analogous to cur_frame_pts/dts
3457      */
3458     int64_t cur_frame_pos[AV_PARSER_PTS_NB];
3459
3460     /**
3461      * Byte position of currently parsed frame in stream.
3462      */
3463     int64_t pos;
3464
3465     /**
3466      * Previous frame byte position.
3467      */
3468     int64_t last_pos;
3469
3470     /**
3471      * Duration of the current frame.
3472      * For audio, this is in units of 1 / AVCodecContext.sample_rate.
3473      * For all other types, this is in units of AVCodecContext.time_base.
3474      */
3475     int duration;
3476
3477     enum AVFieldOrder field_order;
3478
3479     /**
3480      * Indicate whether a picture is coded as a frame, top field or bottom field.
3481      *
3482      * For example, H.264 field_pic_flag equal to 0 corresponds to
3483      * AV_PICTURE_STRUCTURE_FRAME. An H.264 picture with field_pic_flag
3484      * equal to 1 and bottom_field_flag equal to 0 corresponds to
3485      * AV_PICTURE_STRUCTURE_TOP_FIELD.
3486      */
3487     enum AVPictureStructure picture_structure;
3488
3489     /**
3490      * Picture number incremented in presentation or output order.
3491      * This field may be reinitialized at the first picture of a new sequence.
3492      *
3493      * For example, this corresponds to H.264 PicOrderCnt.
3494      */
3495     int output_picture_number;
3496
3497     /**
3498      * Dimensions of the decoded video intended for presentation.
3499      */
3500     int width;
3501     int height;
3502
3503     /**
3504      * Dimensions of the coded video.
3505      */
3506     int coded_width;
3507     int coded_height;
3508
3509     /**
3510      * The format of the coded data, corresponds to enum AVPixelFormat for video
3511      * and for enum AVSampleFormat for audio.
3512      *
3513      * Note that a decoder can have considerable freedom in how exactly it
3514      * decodes the data, so the format reported here might be different from the
3515      * one returned by a decoder.
3516      */
3517     int format;
3518 } AVCodecParserContext;
3519
3520 typedef struct AVCodecParser {
3521     int codec_ids[5]; /* several codec IDs are permitted */
3522     int priv_data_size;
3523     int (*parser_init)(AVCodecParserContext *s);
3524     /* This callback never returns an error, a negative value means that
3525      * the frame start was in a previous packet. */
3526     int (*parser_parse)(AVCodecParserContext *s,
3527                         AVCodecContext *avctx,
3528                         const uint8_t **poutbuf, int *poutbuf_size,
3529                         const uint8_t *buf, int buf_size);
3530     void (*parser_close)(AVCodecParserContext *s);
3531     int (*split)(AVCodecContext *avctx, const uint8_t *buf, int buf_size);
3532     struct AVCodecParser *next;
3533 } AVCodecParser;
3534
3535 /**
3536  * Iterate over all registered codec parsers.
3537  *
3538  * @param opaque a pointer where libavcodec will store the iteration state. Must
3539  *               point to NULL to start the iteration.
3540  *
3541  * @return the next registered codec parser or NULL when the iteration is
3542  *         finished
3543  */
3544 const AVCodecParser *av_parser_iterate(void **opaque);
3545
3546 attribute_deprecated
3547 AVCodecParser *av_parser_next(const AVCodecParser *c);
3548
3549 attribute_deprecated
3550 void av_register_codec_parser(AVCodecParser *parser);
3551 AVCodecParserContext *av_parser_init(int codec_id);
3552
3553 /**
3554  * Parse a packet.
3555  *
3556  * @param s             parser context.
3557  * @param avctx         codec context.
3558  * @param poutbuf       set to pointer to parsed buffer or NULL if not yet finished.
3559  * @param poutbuf_size  set to size of parsed buffer or zero if not yet finished.
3560  * @param buf           input buffer.
3561  * @param buf_size      buffer size in bytes without the padding. I.e. the full buffer
3562                         size is assumed to be buf_size + AV_INPUT_BUFFER_PADDING_SIZE.
3563                         To signal EOF, this should be 0 (so that the last frame
3564                         can be output).
3565  * @param pts           input presentation timestamp.
3566  * @param dts           input decoding timestamp.
3567  * @param pos           input byte position in stream.
3568  * @return the number of bytes of the input bitstream used.
3569  *
3570  * Example:
3571  * @code
3572  *   while(in_len){
3573  *       len = av_parser_parse2(myparser, AVCodecContext, &data, &size,
3574  *                                        in_data, in_len,
3575  *                                        pts, dts, pos);
3576  *       in_data += len;
3577  *       in_len  -= len;
3578  *
3579  *       if(size)
3580  *          decode_frame(data, size);
3581  *   }
3582  * @endcode
3583  */
3584 int av_parser_parse2(AVCodecParserContext *s,
3585                      AVCodecContext *avctx,
3586                      uint8_t **poutbuf, int *poutbuf_size,
3587                      const uint8_t *buf, int buf_size,
3588                      int64_t pts, int64_t dts,
3589                      int64_t pos);
3590
3591 /**
3592  * @return 0 if the output buffer is a subset of the input, 1 if it is allocated and must be freed
3593  * @deprecated use AVBitStreamFilter
3594  */
3595 int av_parser_change(AVCodecParserContext *s,
3596                      AVCodecContext *avctx,
3597                      uint8_t **poutbuf, int *poutbuf_size,
3598                      const uint8_t *buf, int buf_size, int keyframe);
3599 void av_parser_close(AVCodecParserContext *s);
3600
3601 /**
3602  * @}
3603  * @}
3604  */
3605
3606 /**
3607  * @addtogroup lavc_encoding
3608  * @{
3609  */
3610
3611 /**
3612  * Encode a frame of audio.
3613  *
3614  * Takes input samples from frame and writes the next output packet, if
3615  * available, to avpkt. The output packet does not necessarily contain data for
3616  * the most recent frame, as encoders can delay, split, and combine input frames
3617  * internally as needed.
3618  *
3619  * @param avctx     codec context
3620  * @param avpkt     output AVPacket.
3621  *                  The user can supply an output buffer by setting
3622  *                  avpkt->data and avpkt->size prior to calling the
3623  *                  function, but if the size of the user-provided data is not
3624  *                  large enough, encoding will fail. If avpkt->data and
3625  *                  avpkt->size are set, avpkt->destruct must also be set. All
3626  *                  other AVPacket fields will be reset by the encoder using
3627  *                  av_init_packet(). If avpkt->data is NULL, the encoder will
3628  *                  allocate it. The encoder will set avpkt->size to the size
3629  *                  of the output packet.
3630  *
3631  *                  If this function fails or produces no output, avpkt will be
3632  *                  freed using av_packet_unref().
3633  * @param[in] frame AVFrame containing the raw audio data to be encoded.
3634  *                  May be NULL when flushing an encoder that has the
3635  *                  AV_CODEC_CAP_DELAY capability set.
3636  *                  If AV_CODEC_CAP_VARIABLE_FRAME_SIZE is set, then each frame
3637  *                  can have any number of samples.
3638  *                  If it is not set, frame->nb_samples must be equal to
3639  *                  avctx->frame_size for all frames except the last.
3640  *                  The final frame may be smaller than avctx->frame_size.
3641  * @param[out] got_packet_ptr This field is set to 1 by libavcodec if the
3642  *                            output packet is non-empty, and to 0 if it is
3643  *                            empty. If the function returns an error, the
3644  *                            packet can be assumed to be invalid, and the
3645  *                            value of got_packet_ptr is undefined and should
3646  *                            not be used.
3647  * @return          0 on success, negative error code on failure
3648  *
3649  * @deprecated use avcodec_send_frame()/avcodec_receive_packet() instead
3650  */
3651 attribute_deprecated
3652 int avcodec_encode_audio2(AVCodecContext *avctx, AVPacket *avpkt,
3653                           const AVFrame *frame, int *got_packet_ptr);
3654
3655 /**
3656  * Encode a frame of video.
3657  *
3658  * Takes input raw video data from frame and writes the next output packet, if
3659  * available, to avpkt. The output packet does not necessarily contain data for
3660  * the most recent frame, as encoders can delay and reorder input frames
3661  * internally as needed.
3662  *
3663  * @param avctx     codec context
3664  * @param avpkt     output AVPacket.
3665  *                  The user can supply an output buffer by setting
3666  *                  avpkt->data and avpkt->size prior to calling the
3667  *                  function, but if the size of the user-provided data is not
3668  *                  large enough, encoding will fail. All other AVPacket fields
3669  *                  will be reset by the encoder using av_init_packet(). If
3670  *                  avpkt->data is NULL, the encoder will allocate it.
3671  *                  The encoder will set avpkt->size to the size of the
3672  *                  output packet. The returned data (if any) belongs to the
3673  *                  caller, he is responsible for freeing it.
3674  *
3675  *                  If this function fails or produces no output, avpkt will be
3676  *                  freed using av_packet_unref().
3677  * @param[in] frame AVFrame containing the raw video data to be encoded.
3678  *                  May be NULL when flushing an encoder that has the
3679  *                  AV_CODEC_CAP_DELAY capability set.
3680  * @param[out] got_packet_ptr This field is set to 1 by libavcodec if the
3681  *                            output packet is non-empty, and to 0 if it is
3682  *                            empty. If the function returns an error, the
3683  *                            packet can be assumed to be invalid, and the
3684  *                            value of got_packet_