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_major.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 #if FF_API_FLAG_TRUNCATED 54 /** 55 * @deprecated Use parsers to always send proper frames. 56 */ 57 #define AV_CODEC_CAP_TRUNCATED (1 << 3) 58 #endif 59 /** 60 * Encoder or decoder requires flushing with NULL input at the end in order to 61 * give the complete and correct output. 62 * 63 * NOTE: If this flag is not set, the codec is guaranteed to never be fed with 64 * with NULL data. The user can still send NULL data to the public encode 65 * or decode function, but libavcodec will not pass it along to the codec 66 * unless this flag is set. 67 * 68 * Decoders: 69 * The decoder has a non-zero delay and needs to be fed with avpkt->data=NULL, 70 * avpkt->size=0 at the end to get the delayed data until the decoder no longer 71 * returns frames. 72 * 73 * Encoders: 74 * The encoder needs to be fed with NULL data at the end of encoding until the 75 * encoder no longer returns data. 76 * 77 * NOTE: For encoders implementing the AVCodec.encode2() function, setting this 78 * flag also means that the encoder must set the pts and duration for 79 * each output packet. If this flag is not set, the pts and duration will 80 * be determined by libavcodec from the input frame. 81 */ 82 #define AV_CODEC_CAP_DELAY (1 << 5) 83 /** 84 * Codec can be fed a final frame with a smaller size. 85 * This can be used to prevent truncation of the last audio samples. 86 */ 87 #define AV_CODEC_CAP_SMALL_LAST_FRAME (1 << 6) 88 89 /** 90 * Codec can output multiple frames per AVPacket 91 * Normally demuxers return one frame at a time, demuxers which do not do 92 * are connected to a parser to split what they return into proper frames. 93 * This flag is reserved to the very rare category of codecs which have a 94 * bitstream that cannot be split into frames without timeconsuming 95 * operations like full decoding. Demuxers carrying such bitstreams thus 96 * may return multiple frames in a packet. This has many disadvantages like 97 * prohibiting stream copy in many cases thus it should only be considered 98 * as a last resort. 99 */ 100 #define AV_CODEC_CAP_SUBFRAMES (1 << 8) 101 /** 102 * Codec is experimental and is thus avoided in favor of non experimental 103 * encoders 104 */ 105 #define AV_CODEC_CAP_EXPERIMENTAL (1 << 9) 106 /** 107 * Codec should fill in channel configuration and samplerate instead of container 108 */ 109 #define AV_CODEC_CAP_CHANNEL_CONF (1 << 10) 110 /** 111 * Codec supports frame-level multithreading. 112 */ 113 #define AV_CODEC_CAP_FRAME_THREADS (1 << 12) 114 /** 115 * Codec supports slice-based (or partition-based) multithreading. 116 */ 117 #define AV_CODEC_CAP_SLICE_THREADS (1 << 13) 118 /** 119 * Codec supports changed parameters at any point. 120 */ 121 #define AV_CODEC_CAP_PARAM_CHANGE (1 << 14) 122 /** 123 * Codec supports multithreading through a method other than slice- or 124 * frame-level multithreading. Typically this marks wrappers around 125 * multithreading-capable external libraries. 126 */ 127 #define AV_CODEC_CAP_OTHER_THREADS (1 << 15) 128 #if FF_API_AUTO_THREADS 129 #define AV_CODEC_CAP_AUTO_THREADS AV_CODEC_CAP_OTHER_THREADS 130 #endif 131 /** 132 * Audio encoder supports receiving a different number of samples in each call. 133 */ 134 #define AV_CODEC_CAP_VARIABLE_FRAME_SIZE (1 << 16) 135 /** 136 * Decoder is not a preferred choice for probing. 137 * This indicates that the decoder is not a good choice for probing. 138 * It could for example be an expensive to spin up hardware decoder, 139 * or it could simply not provide a lot of useful information about 140 * the stream. 141 * A decoder marked with this flag should only be used as last resort 142 * choice for probing. 143 */ 144 #define AV_CODEC_CAP_AVOID_PROBING (1 << 17) 145 146 #if FF_API_UNUSED_CODEC_CAPS 147 /** 148 * Deprecated and unused. Use AVCodecDescriptor.props instead 149 */ 150 #define AV_CODEC_CAP_INTRA_ONLY 0x40000000 151 /** 152 * Deprecated and unused. Use AVCodecDescriptor.props instead 153 */ 154 #define AV_CODEC_CAP_LOSSLESS 0x80000000 155 #endif 156 157 /** 158 * Codec is backed by a hardware implementation. Typically used to 159 * identify a non-hwaccel hardware decoder. For information about hwaccels, use 160 * avcodec_get_hw_config() instead. 161 */ 162 #define AV_CODEC_CAP_HARDWARE (1 << 18) 163 164 /** 165 * Codec is potentially backed by a hardware implementation, but not 166 * necessarily. This is used instead of AV_CODEC_CAP_HARDWARE, if the 167 * implementation provides some sort of internal fallback. 168 */ 169 #define AV_CODEC_CAP_HYBRID (1 << 19) 170 171 /** 172 * This codec takes the reordered_opaque field from input AVFrames 173 * and returns it in the corresponding field in AVCodecContext after 174 * encoding. 175 */ 176 #define AV_CODEC_CAP_ENCODER_REORDERED_OPAQUE (1 << 20) 177 178 /** 179 * This encoder can be flushed using avcodec_flush_buffers(). If this flag is 180 * not set, the encoder must be closed and reopened to ensure that no frames 181 * remain pending. 182 */ 183 #define AV_CODEC_CAP_ENCODER_FLUSH (1 << 21) 184 185 /** 186 * AVProfile. 187 */ 188 typedef struct AVProfile { 189 int profile; 190 const char *name; ///< short name for the profile 191 } AVProfile; 192 193 /** 194 * AVCodec. 195 */ 196 typedef struct AVCodec { 197 /** 198 * Name of the codec implementation. 199 * The name is globally unique among encoders and among decoders (but an 200 * encoder and a decoder can share the same name). 201 * This is the primary way to find a codec from the user perspective. 202 */ 203 const char *name; 204 /** 205 * Descriptive name for the codec, meant to be more human readable than name. 206 * You should use the NULL_IF_CONFIG_SMALL() macro to define it. 207 */ 208 const char *long_name; 209 enum AVMediaType type; 210 enum AVCodecID id; 211 /** 212 * Codec capabilities. 213 * see AV_CODEC_CAP_* 214 */ 215 int capabilities; 216 uint8_t max_lowres; ///< maximum value for lowres supported by the decoder 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 #if FF_API_OLD_CHANNEL_LAYOUT 222 /** 223 * @deprecated use ch_layouts instead 224 */ 225 attribute_deprecated 226 const uint64_t *channel_layouts; ///< array of support channel layouts, or NULL if unknown. array is terminated by 0 227 #endif 228 const AVClass *priv_class; ///< AVClass for the private context 229 const AVProfile *profiles; ///< array of recognized profiles, or NULL if unknown, array is terminated by {FF_PROFILE_UNKNOWN} 230 231 /** 232 * Group name of the codec implementation. 233 * This is a short symbolic name of the wrapper backing this codec. A 234 * wrapper uses some kind of external implementation for the codec, such 235 * as an external library, or a codec implementation provided by the OS or 236 * the hardware. 237 * If this field is NULL, this is a builtin, libavcodec native codec. 238 * If non-NULL, this will be the suffix in AVCodec.name in most cases 239 * (usually AVCodec.name will be of the form "<codec_name>_<wrapper_name>"). 240 */ 241 const char *wrapper_name; 242 243 /** 244 * Array of supported channel layouts, terminated with a zeroed layout. 245 */ 246 const AVChannelLayout *ch_layouts; 247 } AVCodec; 248 249 /** 250 * Iterate over all registered codecs. 251 * 252 * @param opaque a pointer where libavcodec will store the iteration state. Must 253 * point to NULL to start the iteration. 254 * 255 * @return the next registered codec or NULL when the iteration is 256 * finished 257 */ 258 const AVCodec *av_codec_iterate(void **opaque); 259 260 /** 261 * Find a registered decoder with a matching codec ID. 262 * 263 * @param id AVCodecID of the requested decoder 264 * @return A decoder if one was found, NULL otherwise. 265 */ 266 const AVCodec *avcodec_find_decoder(enum AVCodecID id); 267 268 /** 269 * Find a registered decoder with the specified name. 270 * 271 * @param name name of the requested decoder 272 * @return A decoder if one was found, NULL otherwise. 273 */ 274 const AVCodec *avcodec_find_decoder_by_name(const char *name); 275 276 /** 277 * Find a registered encoder with a matching codec ID. 278 * 279 * @param id AVCodecID of the requested encoder 280 * @return An encoder if one was found, NULL otherwise. 281 */ 282 const AVCodec *avcodec_find_encoder(enum AVCodecID id); 283 284 /** 285 * Find a registered encoder with the specified name. 286 * 287 * @param name name of the requested encoder 288 * @return An encoder if one was found, NULL otherwise. 289 */ 290 const AVCodec *avcodec_find_encoder_by_name(const char *name); 291 /** 292 * @return a non-zero number if codec is an encoder, zero otherwise 293 */ 294 int av_codec_is_encoder(const AVCodec *codec); 295 296 /** 297 * @return a non-zero number if codec is a decoder, zero otherwise 298 */ 299 int av_codec_is_decoder(const AVCodec *codec); 300 301 /** 302 * Return a name for the specified profile, if available. 303 * 304 * @param codec the codec that is searched for the given profile 305 * @param profile the profile value for which a name is requested 306 * @return A name for the profile if found, NULL otherwise. 307 */ 308 const char *av_get_profile_name(const AVCodec *codec, int profile); 309 310 enum { 311 /** 312 * The codec supports this format via the hw_device_ctx interface. 313 * 314 * When selecting this format, AVCodecContext.hw_device_ctx should 315 * have been set to a device of the specified type before calling 316 * avcodec_open2(). 317 */ 318 AV_CODEC_HW_CONFIG_METHOD_HW_DEVICE_CTX = 0x01, 319 /** 320 * The codec supports this format via the hw_frames_ctx interface. 321 * 322 * When selecting this format for a decoder, 323 * AVCodecContext.hw_frames_ctx should be set to a suitable frames 324 * context inside the get_format() callback. The frames context 325 * must have been created on a device of the specified type. 326 * 327 * When selecting this format for an encoder, 328 * AVCodecContext.hw_frames_ctx should be set to the context which 329 * will be used for the input frames before calling avcodec_open2(). 330 */ 331 AV_CODEC_HW_CONFIG_METHOD_HW_FRAMES_CTX = 0x02, 332 /** 333 * The codec supports this format by some internal method. 334 * 335 * This format can be selected without any additional configuration - 336 * no device or frames context is required. 337 */ 338 AV_CODEC_HW_CONFIG_METHOD_INTERNAL = 0x04, 339 /** 340 * The codec supports this format by some ad-hoc method. 341 * 342 * Additional settings and/or function calls are required. See the 343 * codec-specific documentation for details. (Methods requiring 344 * this sort of configuration are deprecated and others should be 345 * used in preference.) 346 */ 347 AV_CODEC_HW_CONFIG_METHOD_AD_HOC = 0x08, 348 }; 349 350 typedef struct AVCodecHWConfig { 351 /** 352 * For decoders, a hardware pixel format which that decoder may be 353 * able to decode to if suitable hardware is available. 354 * 355 * For encoders, a pixel format which the encoder may be able to 356 * accept. If set to AV_PIX_FMT_NONE, this applies to all pixel 357 * formats supported by the codec. 358 */ 359 enum AVPixelFormat pix_fmt; 360 /** 361 * Bit set of AV_CODEC_HW_CONFIG_METHOD_* flags, describing the possible 362 * setup methods which can be used with this configuration. 363 */ 364 int methods; 365 /** 366 * The device type associated with the configuration. 367 * 368 * Must be set for AV_CODEC_HW_CONFIG_METHOD_HW_DEVICE_CTX and 369 * AV_CODEC_HW_CONFIG_METHOD_HW_FRAMES_CTX, otherwise unused. 370 */ 371 enum AVHWDeviceType device_type; 372 } AVCodecHWConfig; 373 374 /** 375 * Retrieve supported hardware configurations for a codec. 376 * 377 * Values of index from zero to some maximum return the indexed configuration 378 * descriptor; all other values return NULL. If the codec does not support 379 * any hardware configurations then it will always return NULL. 380 */ 381 const AVCodecHWConfig *avcodec_get_hw_config(const AVCodec *codec, int index); 382 383 /** 384 * @} 385 */ 386 387 #endif /* AVCODEC_CODEC_H */ 388