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; 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 */ 360 const 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 */ 368 AVCodec *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 */ 376 AVCodec *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 */ 384 AVCodec *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 */ 392 AVCodec *avcodec_find_encoder_by_name(const char *name); 393 /** 394 * @return a non-zero number if codec is an encoder, zero otherwise 395 */ 396 int av_codec_is_encoder(const AVCodec *codec); 397 398 /** 399 * @return a non-zero number if codec is a decoder, zero otherwise 400 */ 401 int av_codec_is_decoder(const AVCodec *codec); 402 403 enum { 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 443 typedef 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 */ 474 const AVCodecHWConfig *avcodec_get_hw_config(const AVCodec *codec, int index); 475 476 /** 477 * @} 478 */ 479 480 #endif /* AVCODEC_CODEC_H */ 481