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 */
183typedef struct AVProfile {
184 int profile;
185 const char *name; ///< short name for the profile
186} AVProfile;
187
188typedef struct AVCodecDefault AVCodecDefault;
189
190struct AVCodecContext;
191struct AVSubtitle;
192struct AVPacket;
193
194/**
195 * AVCodec.
196 */
197typedef 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;
210 enum AVMediaType type;
211 enum AVCodecID id;
212 /**
213 * Codec capabilities.
214 * see AV_CODEC_CAP_*
215 */
216 int capabilities;
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 */
245 int priv_data_size;
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 */
260 int (*update_thread_context)(struct AVCodecContext *dst, const struct AVCodecContext *src);
261 /** @} */
262
263 /**
264 * Private codec-specific defaults.
265 */
266 const AVCodecDefault *defaults;
267
268 /**
269 * Initialize codec static data, called from av_codec_iterate().
270 *
271 * This is not intended for time consuming operations as it is
272 * run for every codec regardless of that codec being used.
273 */
274 void (*init_static_data)(struct AVCodec *codec);
275
276 int (*init)(struct AVCodecContext *);
277 int (*encode_sub)(struct AVCodecContext *, uint8_t *buf, int buf_size,
278 const struct AVSubtitle *sub);
279 /**
280 * Encode data to an AVPacket.
281 *
282 * @param avctx codec context
283 * @param avpkt output AVPacket
284 * @param[in] frame AVFrame containing the raw data to be encoded
285 * @param[out] got_packet_ptr encoder sets to 0 or 1 to indicate that a
286 * non-empty packet was returned in avpkt.
287 * @return 0 on success, negative error code on failure
288 */
289 int (*encode2)(struct AVCodecContext *avctx, struct AVPacket *avpkt,
290 const struct AVFrame *frame, int *got_packet_ptr);
291 /**
292 * Decode picture or subtitle data.
293 *
294 * @param avctx codec context
295 * @param outdata codec type dependent output struct
296 * @param[out] got_frame_ptr decoder sets to 0 or 1 to indicate that a
297 * non-empty frame or subtitle was returned in
298 * outdata.
299 * @param[in] avpkt AVPacket containing the data to be decoded
300 * @return amount of bytes read from the packet on success, negative error
301 * code on failure
302 */
303 int (*decode)(struct AVCodecContext *avctx, void *outdata,
304 int *got_frame_ptr, struct AVPacket *avpkt);
305 int (*close)(struct AVCodecContext *);
306 /**
307 * Encode API with decoupled frame/packet dataflow. This function is called
308 * to get one output packet. It should call ff_encode_get_frame() to obtain
309 * input data.
310 */
311 int (*receive_packet)(struct AVCodecContext *avctx, struct AVPacket *avpkt);
312
313 /**
314 * Decode API with decoupled packet/frame dataflow. This function is called
315 * to get one output frame. It should call ff_decode_get_packet() to obtain
316 * input data.
317 */
318 int (*receive_frame)(struct AVCodecContext *avctx, struct AVFrame *frame);
319 /**
320 * Flush buffers.
321 * Will be called when seeking
322 */
323 void (*flush)(struct AVCodecContext *);
324 /**
325 * Internal codec capabilities.
326 * See FF_CODEC_CAP_* in internal.h
327 */
328 int caps_internal;
329
330 /**
331 * Decoding only, a comma-separated list of bitstream filters to apply to
332 * packets before decoding.
333 */
334 const char *bsfs;
335
336 /**
337 * Array of pointers to hardware configurations supported by the codec,
338 * or NULL if no hardware supported. The array is terminated by a NULL
339 * pointer.
340 *
341 * The user can only access this field via avcodec_get_hw_config().
342 */
343 const struct AVCodecHWConfigInternal *const *hw_configs;
344
345 /**
346 * List of supported codec_tags, terminated by FF_CODEC_TAGS_END.
347 */
348 const uint32_t *codec_tags;
349} AVCodec;
350
351/**
352 * Iterate over all registered codecs.
353 *
354 * @param opaque a pointer where libavcodec will store the iteration state. Must
355 * point to NULL to start the iteration.
356 *
357 * @return the next registered codec or NULL when the iteration is
358 * finished
359 */
360const AVCodec *av_codec_iterate(void **opaque);
361
362/**
363 * Find a registered decoder with a matching codec ID.
364 *
365 * @param id AVCodecID of the requested decoder
366 * @return A decoder if one was found, NULL otherwise.
367 */
368AVCodec *avcodec_find_decoder(enum AVCodecID id);
369
370/**
371 * Find a registered decoder with the specified name.
372 *
373 * @param name name of the requested decoder
374 * @return A decoder if one was found, NULL otherwise.
375 */
376AVCodec *avcodec_find_decoder_by_name(const char *name);
377
378/**
379 * Find a registered encoder with a matching codec ID.
380 *
381 * @param id AVCodecID of the requested encoder
382 * @return An encoder if one was found, NULL otherwise.
383 */
384AVCodec *avcodec_find_encoder(enum AVCodecID id);
385
386/**
387 * Find a registered encoder with the specified name.
388 *
389 * @param name name of the requested encoder
390 * @return An encoder if one was found, NULL otherwise.
391 */
392AVCodec *avcodec_find_encoder_by_name(const char *name);
393/**
394 * @return a non-zero number if codec is an encoder, zero otherwise
395 */
396int av_codec_is_encoder(const AVCodec *codec);
397
398/**
399 * @return a non-zero number if codec is a decoder, zero otherwise
400 */
401int av_codec_is_decoder(const AVCodec *codec);
402
403enum {
404 /**
405 * The codec supports this format via the hw_device_ctx interface.
406 *
407 * When selecting this format, AVCodecContext.hw_device_ctx should
408 * have been set to a device of the specified type before calling
409 * avcodec_open2().
410 */
411 AV_CODEC_HW_CONFIG_METHOD_HW_DEVICE_CTX = 0x01,
412 /**
413 * The codec supports this format via the hw_frames_ctx interface.
414 *
415 * When selecting this format for a decoder,
416 * AVCodecContext.hw_frames_ctx should be set to a suitable frames
417 * context inside the get_format() callback. The frames context
418 * must have been created on a device of the specified type.
419 *
420 * When selecting this format for an encoder,
421 * AVCodecContext.hw_frames_ctx should be set to the context which
422 * will be used for the input frames before calling avcodec_open2().
423 */
424 AV_CODEC_HW_CONFIG_METHOD_HW_FRAMES_CTX = 0x02,
425 /**
426 * The codec supports this format by some internal method.
427 *
428 * This format can be selected without any additional configuration -
429 * no device or frames context is required.
430 */
431 AV_CODEC_HW_CONFIG_METHOD_INTERNAL = 0x04,
432 /**
433 * The codec supports this format by some ad-hoc method.
434 *
435 * Additional settings and/or function calls are required. See the
436 * codec-specific documentation for details. (Methods requiring
437 * this sort of configuration are deprecated and others should be
438 * used in preference.)
439 */
440 AV_CODEC_HW_CONFIG_METHOD_AD_HOC = 0x08,
441};
442
443typedef struct AVCodecHWConfig {
444 /**
445 * For decoders, a hardware pixel format which that decoder may be
446 * able to decode to if suitable hardware is available.
447 *
448 * For encoders, a pixel format which the encoder may be able to
449 * accept. If set to AV_PIX_FMT_NONE, this applies to all pixel
450 * formats supported by the codec.
451 */
452 enum AVPixelFormat pix_fmt;
453 /**
454 * Bit set of AV_CODEC_HW_CONFIG_METHOD_* flags, describing the possible
455 * setup methods which can be used with this configuration.
456 */
457 int methods;
458 /**
459 * The device type associated with the configuration.
460 *
461 * Must be set for AV_CODEC_HW_CONFIG_METHOD_HW_DEVICE_CTX and
462 * AV_CODEC_HW_CONFIG_METHOD_HW_FRAMES_CTX, otherwise unused.
463 */
464 enum AVHWDeviceType device_type;
465} AVCodecHWConfig;
466
467/**
468 * Retrieve supported hardware configurations for a codec.
469 *
470 * Values of index from zero to some maximum return the indexed configuration
471 * descriptor; all other values return NULL. If the codec does not support
472 * any hardware configurations then it will always return NULL.
473 */
474const AVCodecHWConfig *avcodec_get_hw_config(const AVCodec *codec, int index);
475
476/**
477 * @}
478 */
479
480#endif /* AVCODEC_CODEC_H */
481

source code of include/x86_64-linux-gnu/libavcodec/codec.h