FFmpeg
codec.h
Go to the documentation of this file.
1 /*
2  * AVCodec public API
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_CODEC_H
22 #define AVCODEC_CODEC_H
23 
24 #include <stdint.h>
25 
26 #include "libavutil/avutil.h"
27 #include "libavutil/hwcontext.h"
28 #include "libavutil/log.h"
29 #include "libavutil/pixfmt.h"
30 #include "libavutil/rational.h"
31 #include "libavutil/samplefmt.h"
32 
33 #include "libavcodec/codec_id.h"
34 #include "libavcodec/version.h"
35 
36 /**
37  * @addtogroup lavc_core
38  * @{
39  */
40 
41 /**
42  * Decoder can use draw_horiz_band callback.
43  */
44 #define AV_CODEC_CAP_DRAW_HORIZ_BAND (1 << 0)
45 /**
46  * Codec uses get_buffer() or get_encode_buffer() for allocating buffers and
47  * supports custom allocators.
48  * If not set, it might not use get_buffer() or get_encode_buffer() at all, or
49  * use operations that assume the buffer was allocated by
50  * avcodec_default_get_buffer2 or avcodec_default_get_encode_buffer.
51  */
52 #define AV_CODEC_CAP_DR1 (1 << 1)
53 #define AV_CODEC_CAP_TRUNCATED (1 << 3)
54 /**
55  * Encoder or decoder requires flushing with NULL input at the end in order to
56  * give the complete and correct output.
57  *
58  * NOTE: If this flag is not set, the codec is guaranteed to never be fed with
59  * with NULL data. The user can still send NULL data to the public encode
60  * or decode function, but libavcodec will not pass it along to the codec
61  * unless this flag is set.
62  *
63  * Decoders:
64  * The decoder has a non-zero delay and needs to be fed with avpkt->data=NULL,
65  * avpkt->size=0 at the end to get the delayed data until the decoder no longer
66  * returns frames.
67  *
68  * Encoders:
69  * The encoder needs to be fed with NULL data at the end of encoding until the
70  * encoder no longer returns data.
71  *
72  * NOTE: For encoders implementing the AVCodec.encode2() function, setting this
73  * flag also means that the encoder must set the pts and duration for
74  * each output packet. If this flag is not set, the pts and duration will
75  * be determined by libavcodec from the input frame.
76  */
77 #define AV_CODEC_CAP_DELAY (1 << 5)
78 /**
79  * Codec can be fed a final frame with a smaller size.
80  * This can be used to prevent truncation of the last audio samples.
81  */
82 #define AV_CODEC_CAP_SMALL_LAST_FRAME (1 << 6)
83 
84 /**
85  * Codec can output multiple frames per AVPacket
86  * Normally demuxers return one frame at a time, demuxers which do not do
87  * are connected to a parser to split what they return into proper frames.
88  * This flag is reserved to the very rare category of codecs which have a
89  * bitstream that cannot be split into frames without timeconsuming
90  * operations like full decoding. Demuxers carrying such bitstreams thus
91  * may return multiple frames in a packet. This has many disadvantages like
92  * prohibiting stream copy in many cases thus it should only be considered
93  * as a last resort.
94  */
95 #define AV_CODEC_CAP_SUBFRAMES (1 << 8)
96 /**
97  * Codec is experimental and is thus avoided in favor of non experimental
98  * encoders
99  */
100 #define AV_CODEC_CAP_EXPERIMENTAL (1 << 9)
101 /**
102  * Codec should fill in channel configuration and samplerate instead of container
103  */
104 #define AV_CODEC_CAP_CHANNEL_CONF (1 << 10)
105 /**
106  * Codec supports frame-level multithreading.
107  */
108 #define AV_CODEC_CAP_FRAME_THREADS (1 << 12)
109 /**
110  * Codec supports slice-based (or partition-based) multithreading.
111  */
112 #define AV_CODEC_CAP_SLICE_THREADS (1 << 13)
113 /**
114  * Codec supports changed parameters at any point.
115  */
116 #define AV_CODEC_CAP_PARAM_CHANGE (1 << 14)
117 /**
118  * Codec supports multithreading through a method other than slice- or
119  * frame-level multithreading. Typically this marks wrappers around
120  * multithreading-capable external libraries.
121  */
122 #define AV_CODEC_CAP_OTHER_THREADS (1 << 15)
123 #if FF_API_AUTO_THREADS
124 #define AV_CODEC_CAP_AUTO_THREADS AV_CODEC_CAP_OTHER_THREADS
125 #endif
126 /**
127  * Audio encoder supports receiving a different number of samples in each call.
128  */
129 #define AV_CODEC_CAP_VARIABLE_FRAME_SIZE (1 << 16)
130 /**
131  * Decoder is not a preferred choice for probing.
132  * This indicates that the decoder is not a good choice for probing.
133  * It could for example be an expensive to spin up hardware decoder,
134  * or it could simply not provide a lot of useful information about
135  * the stream.
136  * A decoder marked with this flag should only be used as last resort
137  * choice for probing.
138  */
139 #define AV_CODEC_CAP_AVOID_PROBING (1 << 17)
140 
141 #if FF_API_UNUSED_CODEC_CAPS
142 /**
143  * Deprecated and unused. Use AVCodecDescriptor.props instead
144  */
145 #define AV_CODEC_CAP_INTRA_ONLY 0x40000000
146 /**
147  * Deprecated and unused. Use AVCodecDescriptor.props instead
148  */
149 #define AV_CODEC_CAP_LOSSLESS 0x80000000
150 #endif
151 
152 /**
153  * Codec is backed by a hardware implementation. Typically used to
154  * identify a non-hwaccel hardware decoder. For information about hwaccels, use
155  * avcodec_get_hw_config() instead.
156  */
157 #define AV_CODEC_CAP_HARDWARE (1 << 18)
158 
159 /**
160  * Codec is potentially backed by a hardware implementation, but not
161  * necessarily. This is used instead of AV_CODEC_CAP_HARDWARE, if the
162  * implementation provides some sort of internal fallback.
163  */
164 #define AV_CODEC_CAP_HYBRID (1 << 19)
165 
166 /**
167  * This codec takes the reordered_opaque field from input AVFrames
168  * and returns it in the corresponding field in AVCodecContext after
169  * encoding.
170  */
171 #define AV_CODEC_CAP_ENCODER_REORDERED_OPAQUE (1 << 20)
172 
173 /**
174  * This encoder can be flushed using avcodec_flush_buffers(). If this flag is
175  * not set, the encoder must be closed and reopened to ensure that no frames
176  * remain pending.
177  */
178 #define AV_CODEC_CAP_ENCODER_FLUSH (1 << 21)
179 
180 /**
181  * AVProfile.
182  */
183 typedef struct AVProfile {
184  int profile;
185  const char *name; ///< short name for the profile
186 } AVProfile;
187 
188 typedef struct AVCodecDefault AVCodecDefault;
189 
190 struct AVCodecContext;
191 struct AVSubtitle;
192 struct AVPacket;
193 
194 /**
195  * AVCodec.
196  */
197 typedef struct AVCodec {
198  /**
199  * Name of the codec implementation.
200  * The name is globally unique among encoders and among decoders (but an
201  * encoder and a decoder can share the same name).
202  * This is the primary way to find a codec from the user perspective.
203  */
204  const char *name;
205  /**
206  * Descriptive name for the codec, meant to be more human readable than name.
207  * You should use the NULL_IF_CONFIG_SMALL() macro to define it.
208  */
209  const char *long_name;
211  enum AVCodecID id;
212  /**
213  * Codec capabilities.
214  * see AV_CODEC_CAP_*
215  */
217  const AVRational *supported_framerates; ///< array of supported framerates, or NULL if any, array is terminated by {0,0}
218  const enum AVPixelFormat *pix_fmts; ///< array of supported pixel formats, or NULL if unknown, array is terminated by -1
219  const int *supported_samplerates; ///< array of supported audio samplerates, or NULL if unknown, array is terminated by 0
220  const enum AVSampleFormat *sample_fmts; ///< array of supported sample formats, or NULL if unknown, array is terminated by -1
221  const uint64_t *channel_layouts; ///< array of support channel layouts, or NULL if unknown. array is terminated by 0
222  uint8_t max_lowres; ///< maximum value for lowres supported by the decoder
223  const AVClass *priv_class; ///< AVClass for the private context
224  const AVProfile *profiles; ///< array of recognized profiles, or NULL if unknown, array is terminated by {FF_PROFILE_UNKNOWN}
225 
226  /**
227  * Group name of the codec implementation.
228  * This is a short symbolic name of the wrapper backing this codec. A
229  * wrapper uses some kind of external implementation for the codec, such
230  * as an external library, or a codec implementation provided by the OS or
231  * the hardware.
232  * If this field is NULL, this is a builtin, libavcodec native codec.
233  * If non-NULL, this will be the suffix in AVCodec.name in most cases
234  * (usually AVCodec.name will be of the form "<codec_name>_<wrapper_name>").
235  */
236  const char *wrapper_name;
237 
238  /*****************************************************************
239  * No fields below this line are part of the public API. They
240  * may not be used outside of libavcodec and can be changed and
241  * removed at will.
242  * New public fields should be added right above.
243  *****************************************************************
244  */
246 #if FF_API_NEXT
247  struct AVCodec *next;
248 #endif
249  /**
250  * @name Frame-level threading support functions
251  * @{
252  */
253  /**
254  * Copy necessary context variables from a previous thread context to the current one.
255  * If not defined, the next thread will start automatically; otherwise, the codec
256  * must call ff_thread_finish_setup().
257  *
258  * dst and src will (rarely) point to the same context, in which case memcpy should be skipped.
259  */
261 
262  /**
263  * Copy variables back to the user-facing context
264  */
265  int (*update_thread_context_for_user)(struct AVCodecContext *dst, const struct AVCodecContext *src);
266  /** @} */
267 
268  /**
269  * Private codec-specific defaults.
270  */
272 
273  /**
274  * Initialize codec static data, called from av_codec_iterate().
275  *
276  * This is not intended for time consuming operations as it is
277  * run for every codec regardless of that codec being used.
278  */
279  void (*init_static_data)(struct AVCodec *codec);
280 
281  int (*init)(struct AVCodecContext *);
282  int (*encode_sub)(struct AVCodecContext *, uint8_t *buf, int buf_size,
283  const struct AVSubtitle *sub);
284  /**
285  * Encode data to an AVPacket.
286  *
287  * @param avctx codec context
288  * @param avpkt output AVPacket
289  * @param[in] frame AVFrame containing the raw data to be encoded
290  * @param[out] got_packet_ptr encoder sets to 0 or 1 to indicate that a
291  * non-empty packet was returned in avpkt.
292  * @return 0 on success, negative error code on failure
293  */
294  int (*encode2)(struct AVCodecContext *avctx, struct AVPacket *avpkt,
295  const struct AVFrame *frame, int *got_packet_ptr);
296  /**
297  * Decode picture or subtitle data.
298  *
299  * @param avctx codec context
300  * @param outdata codec type dependent output struct
301  * @param[out] got_frame_ptr decoder sets to 0 or 1 to indicate that a
302  * non-empty frame or subtitle was returned in
303  * outdata.
304  * @param[in] avpkt AVPacket containing the data to be decoded
305  * @return amount of bytes read from the packet on success, negative error
306  * code on failure
307  */
308  int (*decode)(struct AVCodecContext *avctx, void *outdata,
309  int *got_frame_ptr, struct AVPacket *avpkt);
310  int (*close)(struct AVCodecContext *);
311  /**
312  * Encode API with decoupled frame/packet dataflow. This function is called
313  * to get one output packet. It should call ff_encode_get_frame() to obtain
314  * input data.
315  */
316  int (*receive_packet)(struct AVCodecContext *avctx, struct AVPacket *avpkt);
317 
318  /**
319  * Decode API with decoupled packet/frame dataflow. This function is called
320  * to get one output frame. It should call ff_decode_get_packet() to obtain
321  * input data.
322  */
323  int (*receive_frame)(struct AVCodecContext *avctx, struct AVFrame *frame);
324  /**
325  * Flush buffers.
326  * Will be called when seeking
327  */
328  void (*flush)(struct AVCodecContext *);
329  /**
330  * Internal codec capabilities.
331  * See FF_CODEC_CAP_* in internal.h
332  */
334 
335  /**
336  * Decoding only, a comma-separated list of bitstream filters to apply to
337  * packets before decoding.
338  */
339  const char *bsfs;
340 
341  /**
342  * Array of pointers to hardware configurations supported by the codec,
343  * or NULL if no hardware supported. The array is terminated by a NULL
344  * pointer.
345  *
346  * The user can only access this field via avcodec_get_hw_config().
347  */
348  const struct AVCodecHWConfigInternal *const *hw_configs;
349 
350  /**
351  * List of supported codec_tags, terminated by FF_CODEC_TAGS_END.
352  */
353  const uint32_t *codec_tags;
354 } AVCodec;
355 
356 /**
357  * Iterate over all registered codecs.
358  *
359  * @param opaque a pointer where libavcodec will store the iteration state. Must
360  * point to NULL to start the iteration.
361  *
362  * @return the next registered codec or NULL when the iteration is
363  * finished
364  */
365 const AVCodec *av_codec_iterate(void **opaque);
366 
367 /**
368  * Find a registered decoder with a matching codec ID.
369  *
370  * @param id AVCodecID of the requested decoder
371  * @return A decoder if one was found, NULL otherwise.
372  */
374 
375 /**
376  * Find a registered decoder with the specified name.
377  *
378  * @param name name of the requested decoder
379  * @return A decoder if one was found, NULL otherwise.
380  */
382 
383 /**
384  * Find a registered encoder with a matching codec ID.
385  *
386  * @param id AVCodecID of the requested encoder
387  * @return An encoder if one was found, NULL otherwise.
388  */
390 
391 /**
392  * Find a registered encoder with the specified name.
393  *
394  * @param name name of the requested encoder
395  * @return An encoder if one was found, NULL otherwise.
396  */
398 /**
399  * @return a non-zero number if codec is an encoder, zero otherwise
400  */
401 int av_codec_is_encoder(const AVCodec *codec);
402 
403 /**
404  * @return a non-zero number if codec is a decoder, zero otherwise
405  */
406 int av_codec_is_decoder(const AVCodec *codec);
407 
408 enum {
409  /**
410  * The codec supports this format via the hw_device_ctx interface.
411  *
412  * When selecting this format, AVCodecContext.hw_device_ctx should
413  * have been set to a device of the specified type before calling
414  * avcodec_open2().
415  */
417  /**
418  * The codec supports this format via the hw_frames_ctx interface.
419  *
420  * When selecting this format for a decoder,
421  * AVCodecContext.hw_frames_ctx should be set to a suitable frames
422  * context inside the get_format() callback. The frames context
423  * must have been created on a device of the specified type.
424  *
425  * When selecting this format for an encoder,
426  * AVCodecContext.hw_frames_ctx should be set to the context which
427  * will be used for the input frames before calling avcodec_open2().
428  */
430  /**
431  * The codec supports this format by some internal method.
432  *
433  * This format can be selected without any additional configuration -
434  * no device or frames context is required.
435  */
437  /**
438  * The codec supports this format by some ad-hoc method.
439  *
440  * Additional settings and/or function calls are required. See the
441  * codec-specific documentation for details. (Methods requiring
442  * this sort of configuration are deprecated and others should be
443  * used in preference.)
444  */
446 };
447 
448 typedef struct AVCodecHWConfig {
449  /**
450  * For decoders, a hardware pixel format which that decoder may be
451  * able to decode to if suitable hardware is available.
452  *
453  * For encoders, a pixel format which the encoder may be able to
454  * accept. If set to AV_PIX_FMT_NONE, this applies to all pixel
455  * formats supported by the codec.
456  */
458  /**
459  * Bit set of AV_CODEC_HW_CONFIG_METHOD_* flags, describing the possible
460  * setup methods which can be used with this configuration.
461  */
462  int methods;
463  /**
464  * The device type associated with the configuration.
465  *
466  * Must be set for AV_CODEC_HW_CONFIG_METHOD_HW_DEVICE_CTX and
467  * AV_CODEC_HW_CONFIG_METHOD_HW_FRAMES_CTX, otherwise unused.
468  */
471 
472 /**
473  * Retrieve supported hardware configurations for a codec.
474  *
475  * Values of index from zero to some maximum return the indexed configuration
476  * descriptor; all other values return NULL. If the codec does not support
477  * any hardware configurations then it will always return NULL.
478  */
479 const AVCodecHWConfig *avcodec_get_hw_config(const AVCodec *codec, int index);
480 
481 /**
482  * @}
483  */
484 
485 #endif /* AVCODEC_CODEC_H */
static enum AVPixelFormat pix_fmt
This structure describes decoded (raw) audio or video data.
Definition: frame.h:318
int av_codec_is_encoder(const AVCodec *codec)
Definition: utils.c:74
static void flush(AVCodecContext *avctx)
static av_cold int init(AVCodecContext *avctx)
Definition: avrndec.c:31
int av_codec_is_decoder(const AVCodec *codec)
Definition: utils.c:79
Convenience header that includes libavutil&#39;s core.
GLint GLenum type
Definition: opengl_enc.c:104
static CopyRet receive_frame(AVCodecContext *avctx, AVFrame *frame, int *got_frame)
Definition: crystalhd.c:560
The codec supports this format via the hw_frames_ctx interface.
Definition: codec.h:429
fg index
const AVCodec * av_codec_iterate(void **opaque)
Iterate over all registered codecs.
Definition: allcodecs.c:859
AVCodec.
Definition: codec.h:197
static void decode(AVCodecContext *dec_ctx, AVPacket *pkt, AVFrame *frame, FILE *outfile)
Definition: decode_audio.c:71
AVCodec * avcodec_find_decoder_by_name(const char *name)
Find a registered decoder with the specified name.
Definition: allcodecs.c:974
uint8_t
const uint32_t * codec_tags
List of supported codec_tags, terminated by FF_CODEC_TAGS_END.
Definition: codec.h:353
Libavcodec version macros.
#define src
Definition: vp8dsp.c:255
const uint64_t * channel_layouts
array of support channel layouts, or NULL if unknown. array is terminated by 0
Definition: codec.h:221
const AVCodecDefault * defaults
Private codec-specific defaults.
Definition: codec.h:271
AVCodecID
Identify the syntax and semantics of the bitstream.
Definition: codec_id.h:46
const struct AVCodecHWConfigInternal *const * hw_configs
Array of pointers to hardware configurations supported by the codec, or NULL if no hardware supported...
Definition: codec.h:348
int methods
Bit set of AV_CODEC_HW_CONFIG_METHOD_* flags, describing the possible setup methods which can be used...
Definition: codec.h:462
int capabilities
Codec capabilities.
Definition: codec.h:216
AVCodec * avcodec_find_encoder(enum AVCodecID id)
Find a registered encoder with a matching codec ID.
Definition: allcodecs.c:941
enum AVHWDeviceType device_type
Definition: hwcontext_qsv.c:90
const char * name
Name of the codec implementation.
Definition: codec.h:204
enum AVPixelFormat * pix_fmts
array of supported pixel formats, or NULL if unknown, array is terminated by -1
Definition: codec.h:218
AVCodec * avcodec_find_encoder_by_name(const char *name)
Find a registered encoder with the specified name.
Definition: allcodecs.c:969
typedef void(APIENTRY *FF_PFNGLACTIVETEXTUREPROC)(GLenum texture)
int priv_data_size
Definition: codec.h:245
static av_cold void init_static_data(void)
Definition: mv30.c:660
int profile
Definition: codec.h:184
these buffered frames must be flushed immediately if a new input produces new the filter must not call request_frame to get more It must just process the frame or queue it The task of requesting more frames is left to the filter s request_frame method or the application If a filter has several the filter must be ready for frames arriving randomly on any input any filter with several inputs will most likely require some kind of queuing mechanism It is perfectly acceptable to have a limited queue and to drop frames when the inputs are too unbalanced request_frame For filters that do not use the this method is called when a frame is wanted on an output For a it should directly call filter_frame on the corresponding output For a if there are queued frames already one of these frames should be pushed If the filter should request a frame on one of its repeatedly until at least one frame has been pushed Return or at least make progress towards producing a frame
const AVProfile * profiles
array of recognized profiles, or NULL if unknown, array is terminated by {FF_PROFILE_UNKNOWN} ...
Definition: codec.h:224
const char * bsfs
Decoding only, a comma-separated list of bitstream filters to apply to packets before decoding...
Definition: codec.h:339
const char * long_name
Descriptive name for the codec, meant to be more human readable than name.
Definition: codec.h:209
const char * wrapper_name
Group name of the codec implementation.
Definition: codec.h:236
const AVRational * supported_framerates
array of supported framerates, or NULL if any, array is terminated by {0,0}
Definition: codec.h:217
AVSampleFormat
Audio sample formats.
Definition: samplefmt.h:58
const AVCodecHWConfig * avcodec_get_hw_config(const AVCodec *codec, int index)
Retrieve supported hardware configurations for a codec.
Definition: utils.c:873
main external API structure.
Definition: avcodec.h:536
the pkt_dts and pkt_pts fields in AVFrame will work as usual Restrictions on codec whose streams don t reset across will not work because their bitstreams cannot be decoded in parallel *The contents of buffers must not be read before as well as code calling up to before the decode process starts Call have update_thread_context() run it in the next thread.Add AV_CODEC_CAP_FRAME_THREADS to the codec capabilities.There will be very little speed gain at this point but it should work.If there are inter-frame dependencies
Describe the class of an AVClass context structure.
Definition: log.h:67
Rational number (pair of numerator and denominator).
Definition: rational.h:58
const char * name
short name for the profile
Definition: codec.h:185
The codec supports this format via the hw_device_ctx interface.
Definition: codec.h:416
AVMediaType
Definition: avutil.h:199
AVCodec * avcodec_find_decoder(enum AVCodecID id)
Find a registered decoder with a matching codec ID.
Definition: allcodecs.c:946
The codec supports this format by some internal method.
Definition: codec.h:436
const AVClass * priv_class
AVClass for the private context.
Definition: codec.h:223
uint8_t max_lowres
maximum value for lowres supported by the decoder
Definition: codec.h:222
int
Utilties for rational number calculation.
AVProfile.
Definition: codec.h:183
The codec supports this format by some ad-hoc method.
Definition: codec.h:445
int caps_internal
Internal codec capabilities.
Definition: codec.h:333
pixel format definitions
AVHWDeviceType
Definition: hwcontext.h:27
const int * supported_samplerates
array of supported audio samplerates, or NULL if unknown, array is terminated by 0 ...
Definition: codec.h:219
static float sub(float src0, float src1)
enum AVSampleFormat * sample_fmts
array of supported sample formats, or NULL if unknown, array is terminated by -1
Definition: codec.h:220
enum AVCodecID id
AVPixelFormat
Pixel format.
Definition: pixfmt.h:64
This structure stores compressed data.
Definition: packet.h:346
const char * name
Definition: opengl_enc.c:102