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