avutil.h (9495B)
1 /* 2 * copyright (c) 2006 Michael Niedermayer <michaelni@gmx.at> 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 AVUTIL_AVUTIL_H 22 #define AVUTIL_AVUTIL_H 23 24 /** 25 * @file 26 * @ingroup lavu 27 * Convenience header that includes @ref lavu "libavutil"'s core. 28 */ 29 30 /** 31 * @mainpage 32 * 33 * @section ffmpeg_intro Introduction 34 * 35 * This document describes the usage of the different libraries 36 * provided by FFmpeg. 37 * 38 * @li @ref libavc "libavcodec" encoding/decoding library 39 * @li @ref lavfi "libavfilter" graph-based frame editing library 40 * @li @ref libavf "libavformat" I/O and muxing/demuxing library 41 * @li @ref lavd "libavdevice" special devices muxing/demuxing library 42 * @li @ref lavu "libavutil" common utility library 43 * @li @ref lswr "libswresample" audio resampling, format conversion and mixing 44 * @li @ref lpp "libpostproc" post processing library 45 * @li @ref libsws "libswscale" color conversion and scaling library 46 * 47 * @section ffmpeg_versioning Versioning and compatibility 48 * 49 * Each of the FFmpeg libraries contains a version.h header, which defines a 50 * major, minor and micro version number with the 51 * <em>LIBRARYNAME_VERSION_{MAJOR,MINOR,MICRO}</em> macros. The major version 52 * number is incremented with backward incompatible changes - e.g. removing 53 * parts of the public API, reordering public struct members, etc. The minor 54 * version number is incremented for backward compatible API changes or major 55 * new features - e.g. adding a new public function or a new decoder. The micro 56 * version number is incremented for smaller changes that a calling program 57 * might still want to check for - e.g. changing behavior in a previously 58 * unspecified situation. 59 * 60 * FFmpeg guarantees backward API and ABI compatibility for each library as long 61 * as its major version number is unchanged. This means that no public symbols 62 * will be removed or renamed. Types and names of the public struct members and 63 * values of public macros and enums will remain the same (unless they were 64 * explicitly declared as not part of the public API). Documented behavior will 65 * not change. 66 * 67 * In other words, any correct program that works with a given FFmpeg snapshot 68 * should work just as well without any changes with any later snapshot with the 69 * same major versions. This applies to both rebuilding the program against new 70 * FFmpeg versions or to replacing the dynamic FFmpeg libraries that a program 71 * links against. 72 * 73 * However, new public symbols may be added and new members may be appended to 74 * public structs whose size is not part of public ABI (most public structs in 75 * FFmpeg). New macros and enum values may be added. Behavior in undocumented 76 * situations may change slightly (and be documented). All those are accompanied 77 * by an entry in doc/APIchanges and incrementing either the minor or micro 78 * version number. 79 */ 80 81 /** 82 * @defgroup lavu libavutil 83 * Common code shared across all FFmpeg libraries. 84 * 85 * @note 86 * libavutil is designed to be modular. In most cases, in order to use the 87 * functions provided by one component of libavutil you must explicitly include 88 * the specific header containing that feature. If you are only using 89 * media-related components, you could simply include libavutil/avutil.h, which 90 * brings in most of the "core" components. 91 * 92 * @{ 93 * 94 * @defgroup lavu_crypto Crypto and Hashing 95 * 96 * @{ 97 * @} 98 * 99 * @defgroup lavu_math Mathematics 100 * @{ 101 * 102 * @} 103 * 104 * @defgroup lavu_string String Manipulation 105 * 106 * @{ 107 * 108 * @} 109 * 110 * @defgroup lavu_mem Memory Management 111 * 112 * @{ 113 * 114 * @} 115 * 116 * @defgroup lavu_data Data Structures 117 * @{ 118 * 119 * @} 120 * 121 * @defgroup lavu_video Video related 122 * 123 * @{ 124 * 125 * @} 126 * 127 * @defgroup lavu_audio Audio related 128 * 129 * @{ 130 * 131 * @} 132 * 133 * @defgroup lavu_error Error Codes 134 * 135 * @{ 136 * 137 * @} 138 * 139 * @defgroup lavu_log Logging Facility 140 * 141 * @{ 142 * 143 * @} 144 * 145 * @defgroup lavu_misc Other 146 * 147 * @{ 148 * 149 * @defgroup preproc_misc Preprocessor String Macros 150 * 151 * @{ 152 * 153 * @} 154 * 155 * @defgroup version_utils Library Version Macros 156 * 157 * @{ 158 * 159 * @} 160 */ 161 162 163 /** 164 * @addtogroup lavu_ver 165 * @{ 166 */ 167 168 /** 169 * Return the LIBAVUTIL_VERSION_INT constant. 170 */ 171 unsigned avutil_version(void); 172 173 /** 174 * Return an informative version string. This usually is the actual release 175 * version number or a git commit description. This string has no fixed format 176 * and can change any time. It should never be parsed by code. 177 */ 178 const char *av_version_info(void); 179 180 /** 181 * Return the libavutil build-time configuration. 182 */ 183 const char *avutil_configuration(void); 184 185 /** 186 * Return the libavutil license. 187 */ 188 const char *avutil_license(void); 189 190 /** 191 * @} 192 */ 193 194 /** 195 * @addtogroup lavu_media Media Type 196 * @brief Media Type 197 */ 198 199 enum AVMediaType { 200 AVMEDIA_TYPE_UNKNOWN = -1, ///< Usually treated as AVMEDIA_TYPE_DATA 201 AVMEDIA_TYPE_VIDEO, 202 AVMEDIA_TYPE_AUDIO, 203 AVMEDIA_TYPE_DATA, ///< Opaque data information usually continuous 204 AVMEDIA_TYPE_SUBTITLE, 205 AVMEDIA_TYPE_ATTACHMENT, ///< Opaque data information usually sparse 206 AVMEDIA_TYPE_NB 207 }; 208 209 /** 210 * Return a string describing the media_type enum, NULL if media_type 211 * is unknown. 212 */ 213 const char *av_get_media_type_string(enum AVMediaType media_type); 214 215 /** 216 * @defgroup lavu_const Constants 217 * @{ 218 * 219 * @defgroup lavu_enc Encoding specific 220 * 221 * @note those definition should move to avcodec 222 * @{ 223 */ 224 225 #define FF_LAMBDA_SHIFT 7 226 #define FF_LAMBDA_SCALE (1<<FF_LAMBDA_SHIFT) 227 #define FF_QP2LAMBDA 118 ///< factor to convert from H.263 QP to lambda 228 #define FF_LAMBDA_MAX (256*128-1) 229 230 #define FF_QUALITY_SCALE FF_LAMBDA_SCALE //FIXME maybe remove 231 232 /** 233 * @} 234 * @defgroup lavu_time Timestamp specific 235 * 236 * FFmpeg internal timebase and timestamp definitions 237 * 238 * @{ 239 */ 240 241 /** 242 * @brief Undefined timestamp value 243 * 244 * Usually reported by demuxer that work on containers that do not provide 245 * either pts or dts. 246 */ 247 248 #define AV_NOPTS_VALUE ((int64_t)UINT64_C(0x8000000000000000)) 249 250 /** 251 * Internal time base represented as integer 252 */ 253 254 #define AV_TIME_BASE 1000000 255 256 /** 257 * Internal time base represented as fractional value 258 */ 259 260 #ifdef __cplusplus 261 /* ISO C++ forbids compound-literals. */ 262 #define AV_TIME_BASE_Q av_make_q(1, AV_TIME_BASE) 263 #else 264 #define AV_TIME_BASE_Q (AVRational){1, AV_TIME_BASE} 265 #endif 266 267 /** 268 * @} 269 * @} 270 * @defgroup lavu_picture Image related 271 * 272 * AVPicture types, pixel formats and basic image planes manipulation. 273 * 274 * @{ 275 */ 276 277 enum AVPictureType { 278 AV_PICTURE_TYPE_NONE = 0, ///< Undefined 279 AV_PICTURE_TYPE_I, ///< Intra 280 AV_PICTURE_TYPE_P, ///< Predicted 281 AV_PICTURE_TYPE_B, ///< Bi-dir predicted 282 AV_PICTURE_TYPE_S, ///< S(GMC)-VOP MPEG-4 283 AV_PICTURE_TYPE_SI, ///< Switching Intra 284 AV_PICTURE_TYPE_SP, ///< Switching Predicted 285 AV_PICTURE_TYPE_BI, ///< BI type 286 }; 287 288 /** 289 * Return a single letter to describe the given picture type 290 * pict_type. 291 * 292 * @param[in] pict_type the picture type @return a single character 293 * representing the picture type, '?' if pict_type is unknown 294 */ 295 char av_get_picture_type_char(enum AVPictureType pict_type); 296 297 /** 298 * @} 299 */ 300 301 #include "common.h" 302 #include "rational.h" 303 #include "version.h" 304 #include "macros.h" 305 #include "mathematics.h" 306 #include "log.h" 307 #include "pixfmt.h" 308 309 /** 310 * Return x default pointer in case p is NULL. 311 */ 312 static inline void *av_x_if_null(const void *p, const void *x) 313 { 314 return (void *)(intptr_t)(p ? p : x); 315 } 316 317 /** 318 * Compute the length of an integer list. 319 * 320 * @param elsize size in bytes of each list element (only 1, 2, 4 or 8) 321 * @param term list terminator (usually 0 or -1) 322 * @param list pointer to the list 323 * @return length of the list, in elements, not counting the terminator 324 */ 325 unsigned av_int_list_length_for_size(unsigned elsize, 326 const void *list, uint64_t term) av_pure; 327 328 /** 329 * Compute the length of an integer list. 330 * 331 * @param term list terminator (usually 0 or -1) 332 * @param list pointer to the list 333 * @return length of the list, in elements, not counting the terminator 334 */ 335 #define av_int_list_length(list, term) \ 336 av_int_list_length_for_size(sizeof(*(list)), list, term) 337 338 /** 339 * Return the fractional representation of the internal time base. 340 */ 341 AVRational av_get_time_base_q(void); 342 343 #define AV_FOURCC_MAX_STRING_SIZE 32 344 345 #define av_fourcc2str(fourcc) av_fourcc_make_string((char[AV_FOURCC_MAX_STRING_SIZE]){0}, fourcc) 346 347 /** 348 * Fill the provided buffer with a string containing a FourCC (four-character 349 * code) representation. 350 * 351 * @param buf a buffer with size in bytes of at least AV_FOURCC_MAX_STRING_SIZE 352 * @param fourcc the fourcc to represent 353 * @return the buffer in input 354 */ 355 char *av_fourcc_make_string(char *buf, uint32_t fourcc); 356 357 /** 358 * @} 359 * @} 360 */ 361 362 #endif /* AVUTIL_AVUTIL_H */