avutil.h 8.69 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
/*
 * copyright (c) 2006 Michael Niedermayer <michaelni@gmx.at>
 *
 * This file is part of FFmpeg.
 *
 * FFmpeg is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * FFmpeg is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with FFmpeg; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 */

21 22
#ifndef AVUTIL_AVUTIL_H
#define AVUTIL_AVUTIL_H
23 24

/**
25
 * @file
Diego Biurrun's avatar
Diego Biurrun committed
26
 * external API header
27 28
 */

29
/**
30 31
 * @mainpage
 *
32
 * @section ffmpeg_intro Introduction
33
 *
34
 * This document describes the usage of the different libraries
35
 * provided by FFmpeg.
36
 *
37
 * @li @ref libavc "libavcodec" encoding/decoding library
38
 * @li @ref lavfi "libavfilter" graph-based frame editing library
39
 * @li @ref libavf "libavformat" I/O and muxing/demuxing library
40
 * @li @ref lavd "libavdevice" special devices muxing/demuxing library
41
 * @li @ref lavu "libavutil" common utility library
42
 * @li @ref lswr "libswresample" audio resampling, format conversion and mixing
43
 * @li @ref lpp  "libpostproc" post processing library
44
 * @li @ref libsws "libswscale" color conversion and scaling library
45
 *
46
 * @section ffmpeg_versioning Versioning and compatibility
47
 *
48
 * Each of the FFmpeg libraries contains a version.h header, which defines a
49 50 51 52 53 54 55 56 57 58
 * major, minor and micro version number with the
 * <em>LIBRARYNAME_VERSION_{MAJOR,MINOR,MICRO}</em> macros. The major version
 * number is incremented with backward incompatible changes - e.g. removing
 * parts of the public API, reordering public struct members, etc. The minor
 * version number is incremented for backward compatible API changes or major
 * new features - e.g. adding a new public function or a new decoder. The micro
 * version number is incremented for smaller changes that a calling program
 * might still want to check for - e.g. changing behavior in a previously
 * unspecified situation.
 *
59
 * FFmpeg guarantees backward API and ABI compatibility for each library as long
60 61 62 63 64 65
 * as its major version number is unchanged. This means that no public symbols
 * will be removed or renamed. Types and names of the public struct members and
 * values of public macros and enums will remain the same (unless they were
 * explicitly declared as not part of the public API). Documented behavior will
 * not change.
 *
66
 * In other words, any correct program that works with a given FFmpeg snapshot
67 68
 * should work just as well without any changes with any later snapshot with the
 * same major versions. This applies to both rebuilding the program against new
69
 * FFmpeg versions or to replacing the dynamic FFmpeg libraries that a program
70 71 72 73
 * links against.
 *
 * However, new public symbols may be added and new members may be appended to
 * public structs whose size is not part of public ABI (most public structs in
74
 * FFmpeg). New macros and enum values may be added. Behavior in undocumented
75 76 77
 * situations may change slightly (and be documented). All those are accompanied
 * by an entry in doc/APIchanges and incrementing either the minor or micro
 * version number.
78 79 80 81 82 83
 */

/**
 * @defgroup lavu Common utility functions
 *
 * @brief
84
 * libavutil contains the code shared across all the other FFmpeg
85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130
 * libraries
 *
 * @note In order to use the functions provided by avutil you must include
 * the specific header.
 *
 * @{
 *
 * @defgroup lavu_crypto Crypto and Hashing
 *
 * @{
 * @}
 *
 * @defgroup lavu_math Maths
 * @{
 *
 * @}
 *
 * @defgroup lavu_string String Manipulation
 *
 * @{
 *
 * @}
 *
 * @defgroup lavu_mem Memory Management
 *
 * @{
 *
 * @}
 *
 * @defgroup lavu_data Data Structures
 * @{
 *
 * @}
 *
 * @defgroup lavu_audio Audio related
 *
 * @{
 *
 * @}
 *
 * @defgroup lavu_error Error Codes
 *
 * @{
 *
 * @}
 *
Luca Barbato's avatar
Luca Barbato committed
131 132 133 134 135 136
 * @defgroup lavu_log Logging Facility
 *
 * @{
 *
 * @}
 *
137 138 139 140 141 142 143 144 145 146 147 148
 * @defgroup lavu_misc Other
 *
 * @{
 *
 * @defgroup lavu_internal Internal
 *
 * Not exported functions, for internal usage only
 *
 * @{
 *
 * @}
 *
149
 * @defgroup preproc_misc Preprocessor String Macros
150 151
 *
 * @{
152
 *
153
 * @}
154 155 156 157 158 159
 *
 * @defgroup version_utils Library Version Macros
 *
 * @{
 *
 * @}
160 161 162 163 164 165 166 167
 */


/**
 * @addtogroup lavu_ver
 * @{
 */

168
/**
169
 * Return the LIBAVUTIL_VERSION_INT constant.
170 171
 */
unsigned avutil_version(void);
172

173
/**
174 175 176
 * Return an informative version string. This usually is the actual release
 * version number or a git commit description. This string has no fixed format
 * 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 196 197 198
/**
 * @}
 */

/**
 * @addtogroup lavu_media Media Type
 * @brief Media Type
 */

199
enum AVMediaType {
200
    AVMEDIA_TYPE_UNKNOWN = -1,  ///< Usually treated as AVMEDIA_TYPE_DATA
201 202
    AVMEDIA_TYPE_VIDEO,
    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 207 208
    AVMEDIA_TYPE_NB
};

209 210 211 212 213 214
/**
 * Return a string describing the media_type enum, NULL if media_type
 * is unknown.
 */
const char *av_get_media_type_string(enum AVMediaType media_type);

215 216 217 218 219 220 221 222 223 224
/**
 * @defgroup lavu_const Constants
 * @{
 *
 * @defgroup lavu_enc Encoding specific
 *
 * @note those definition should move to avcodec
 * @{
 */

225 226 227 228 229 230 231
#define FF_LAMBDA_SHIFT 7
#define FF_LAMBDA_SCALE (1<<FF_LAMBDA_SHIFT)
#define FF_QP2LAMBDA 118 ///< factor to convert from H.263 QP to lambda
#define FF_LAMBDA_MAX (256*128-1)

#define FF_QUALITY_SCALE FF_LAMBDA_SCALE //FIXME maybe remove

232 233 234 235
/**
 * @}
 * @defgroup lavu_time Timestamp specific
 *
236
 * FFmpeg internal timebase and timestamp definitions
237 238 239 240 241 242 243 244 245 246 247
 *
 * @{
 */

/**
 * @brief Undefined timestamp value
 *
 * Usually reported by demuxer that work on containers that do not provide
 * either pts or dts.
 */

248
#define AV_NOPTS_VALUE          ((int64_t)UINT64_C(0x8000000000000000))
249 250 251 252 253

/**
 * Internal time base represented as integer
 */

254
#define AV_TIME_BASE            1000000
255 256 257 258 259

/**
 * Internal time base represented as fractional value
 */

260 261
#define AV_TIME_BASE_Q          (AVRational){1, AV_TIME_BASE}

262 263 264 265 266 267 268 269 270 271
/**
 * @}
 * @}
 * @defgroup lavu_picture Image related
 *
 * AVPicture types, pixel formats and basic image planes manipulation.
 *
 * @{
 */

272
enum AVPictureType {
273 274
    AV_PICTURE_TYPE_NONE = 0, ///< Undefined
    AV_PICTURE_TYPE_I,     ///< Intra
275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291
    AV_PICTURE_TYPE_P,     ///< Predicted
    AV_PICTURE_TYPE_B,     ///< Bi-dir predicted
    AV_PICTURE_TYPE_S,     ///< S(GMC)-VOP MPEG4
    AV_PICTURE_TYPE_SI,    ///< Switching Intra
    AV_PICTURE_TYPE_SP,    ///< Switching Predicted
    AV_PICTURE_TYPE_BI,    ///< BI type
};

/**
 * Return a single letter to describe the given picture type
 * pict_type.
 *
 * @param[in] pict_type the picture type @return a single character
 * representing the picture type, '?' if pict_type is unknown
 */
char av_get_picture_type_char(enum AVPictureType pict_type);

292 293 294 295
/**
 * @}
 */

296
#include "common.h"
297
#include "error.h"
298
#include "rational.h"
299
#include "version.h"
300
#include "macros.h"
301
#include "mathematics.h"
302 303
#include "log.h"
#include "pixfmt.h"
304

305 306 307 308 309 310 311 312
/**
 * Return x default pointer in case p is NULL.
 */
static inline void *av_x_if_null(const void *p, const void *x)
{
    return (void *)(intptr_t)(p ? p : x);
}

313 314 315 316 317 318 319 320 321
/**
 * Compute the length of an integer list.
 *
 * @param elsize  size in bytes of each list element (only 1, 2, 4 or 8)
 * @param term    list terminator (usually 0 or -1)
 * @param list    pointer to the list
 * @return  length of the list, in elements, not counting the terminator
 */
unsigned av_int_list_length_for_size(unsigned elsize,
322
                                     const void *list, uint64_t term) av_pure;
323 324 325 326 327 328 329 330 331

/**
 * Compute the length of an integer list.
 *
 * @param term  list terminator (usually 0 or -1)
 * @param list  pointer to the list
 * @return  length of the list, in elements, not counting the terminator
 */
#define av_int_list_length(list, term) \
332
    av_int_list_length_for_size(sizeof(*(list)), list, term)
333

334 335 336 337 338 339 340
/**
 * Open a file using a UTF-8 filename.
 * The API of this function matches POSIX fopen(), errors are returned through
 * errno.
 */
FILE *av_fopen_utf8(const char *path, const char *mode);

341 342 343 344 345
/**
 * Return the fractional representation of the internal time base.
 */
AVRational av_get_time_base_q(void);

346 347 348 349 350
/**
 * @}
 * @}
 */

351
#endif /* AVUTIL_AVUTIL_H */