FFmpeg
avutil.h
Go to the documentation of this file.
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 
200  AVMEDIA_TYPE_UNKNOWN = -1, ///< Usually treated as AVMEDIA_TYPE_DATA
203  AVMEDIA_TYPE_DATA, ///< Opaque data information usually continuous
205  AVMEDIA_TYPE_ATTACHMENT, ///< Opaque data information usually sparse
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 #define AV_TIME_BASE_Q (AVRational){1, AV_TIME_BASE}
261 
262 /**
263  * @}
264  * @}
265  * @defgroup lavu_picture Image related
266  *
267  * AVPicture types, pixel formats and basic image planes manipulation.
268  *
269  * @{
270  */
271 
273  AV_PICTURE_TYPE_NONE = 0, ///< Undefined
274  AV_PICTURE_TYPE_I, ///< Intra
275  AV_PICTURE_TYPE_P, ///< Predicted
276  AV_PICTURE_TYPE_B, ///< Bi-dir predicted
277  AV_PICTURE_TYPE_S, ///< S(GMC)-VOP MPEG-4
278  AV_PICTURE_TYPE_SI, ///< Switching Intra
279  AV_PICTURE_TYPE_SP, ///< Switching Predicted
280  AV_PICTURE_TYPE_BI, ///< BI type
281 };
282 
283 /**
284  * Return a single letter to describe the given picture type
285  * pict_type.
286  *
287  * @param[in] pict_type the picture type @return a single character
288  * representing the picture type, '?' if pict_type is unknown
289  */
290 char av_get_picture_type_char(enum AVPictureType pict_type);
291 
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 #include "log.h"
303 #include "pixfmt.h"
304 
305 /**
306  * Return x default pointer in case p is NULL.
307  */
308 static inline void *av_x_if_null(const void *p, const void *x)
309 {
310  return (void *)(intptr_t)(p ? p : x);
311 }
312 
313 /**
314  * Compute the length of an integer list.
315  *
316  * @param elsize size in bytes of each list element (only 1, 2, 4 or 8)
317  * @param term list terminator (usually 0 or -1)
318  * @param list pointer to the list
319  * @return length of the list, in elements, not counting the terminator
320  */
321 unsigned av_int_list_length_for_size(unsigned elsize,
322  const void *list, uint64_t term) av_pure;
323 
324 /**
325  * Compute the length of an integer list.
326  *
327  * @param term list terminator (usually 0 or -1)
328  * @param list pointer to the list
329  * @return length of the list, in elements, not counting the terminator
330  */
331 #define av_int_list_length(list, term) \
332  av_int_list_length_for_size(sizeof(*(list)), list, term)
333 
334 #if FF_API_AV_FOPEN_UTF8
335 /**
336  * Open a file using a UTF-8 filename.
337  * The API of this function matches POSIX fopen(), errors are returned through
338  * errno.
339  * @deprecated Avoid using it, as on Windows, the FILE* allocated by this
340  * function may be allocated with a different CRT than the caller
341  * who uses the FILE*. No replacement provided in public API.
342  */
344 FILE *av_fopen_utf8(const char *path, const char *mode);
345 #endif
346 
347 /**
348  * Return the fractional representation of the internal time base.
349  */
351 
352 #define AV_FOURCC_MAX_STRING_SIZE 32
353 
354 #define av_fourcc2str(fourcc) av_fourcc_make_string((char[AV_FOURCC_MAX_STRING_SIZE]){0}, fourcc)
355 
356 /**
357  * Fill the provided buffer with a string containing a FourCC (four-character
358  * code) representation.
359  *
360  * @param buf a buffer with size in bytes of at least AV_FOURCC_MAX_STRING_SIZE
361  * @param fourcc the fourcc to represent
362  * @return the buffer in input
363  */
364 char *av_fourcc_make_string(char *buf, uint32_t fourcc);
365 
366 /**
367  * @}
368  * @}
369  */
370 
371 #endif /* AVUTIL_AVUTIL_H */
AVMEDIA_TYPE_SUBTITLE
@ AVMEDIA_TYPE_SUBTITLE
Definition: avutil.h:204
AVPictureType
AVPictureType
Definition: avutil.h:272
rational.h
mathematics.h
av_pure
#define av_pure
Definition: attributes.h:78
av_version_info
const char * av_version_info(void)
Return an informative version string.
Definition: version.c:35
macros.h
avutil_version
unsigned avutil_version(void)
Return the LIBAVUTIL_VERSION_INT constant.
Definition: version.c:40
AVMEDIA_TYPE_AUDIO
@ AVMEDIA_TYPE_AUDIO
Definition: avutil.h:202
AVMEDIA_TYPE_NB
@ AVMEDIA_TYPE_NB
Definition: avutil.h:206
av_int_list_length_for_size
unsigned av_int_list_length_for_size(unsigned elsize, const void *list, uint64_t term) av_pure
Compute the length of an integer list.
Definition: utils.c:54
AVMEDIA_TYPE_DATA
@ AVMEDIA_TYPE_DATA
Opaque data information usually continuous.
Definition: avutil.h:203
avutil_configuration
const char * avutil_configuration(void)
Return the libavutil build-time configuration.
Definition: version.c:62
AVRational
Rational number (pair of numerator and denominator).
Definition: rational.h:58
AV_PICTURE_TYPE_SI
@ AV_PICTURE_TYPE_SI
Switching Intra.
Definition: avutil.h:278
AV_PICTURE_TYPE_I
@ AV_PICTURE_TYPE_I
Intra.
Definition: avutil.h:274
list
Filter the word “frame” indicates either a video frame or a group of audio as stored in an AVFrame structure Format for each input and each output the list of supported formats For video that means pixel format For audio that means channel sample they are references to shared objects When the negotiation mechanism computes the intersection of the formats supported at each end of a all references to both lists are replaced with a reference to the intersection And when a single format is eventually chosen for a link amongst the remaining list
Definition: filter_design.txt:25
AV_PICTURE_TYPE_SP
@ AV_PICTURE_TYPE_SP
Switching Predicted.
Definition: avutil.h:279
error.h
FFFILE::buf
unsigned char * buf
Definition: avsscanf.c:39
AVMediaType
AVMediaType
Definition: avutil.h:199
av_get_time_base_q
AVRational av_get_time_base_q(void)
Return the fractional representation of the internal time base.
Definition: utils.c:96
av_fopen_utf8
attribute_deprecated FILE * av_fopen_utf8(const char *path, const char *mode)
Open a file using a UTF-8 filename.
Definition: file_open.c:194
av_fourcc_make_string
char * av_fourcc_make_string(char *buf, uint32_t fourcc)
Fill the provided buffer with a string containing a FourCC (four-character code) representation.
Definition: utils.c:73
AVMEDIA_TYPE_UNKNOWN
@ AVMEDIA_TYPE_UNKNOWN
Usually treated as AVMEDIA_TYPE_DATA.
Definition: avutil.h:200
AV_PICTURE_TYPE_NONE
@ AV_PICTURE_TYPE_NONE
Undefined.
Definition: avutil.h:273
attribute_deprecated
#define attribute_deprecated
Definition: attributes.h:104
avutil_license
const char * avutil_license(void)
Return the libavutil license.
Definition: version.c:67
av_get_picture_type_char
char av_get_picture_type_char(enum AVPictureType pict_type)
Return a single letter to describe the given picture type pict_type.
Definition: utils.c:40
log.h
common.h
AVMEDIA_TYPE_ATTACHMENT
@ AVMEDIA_TYPE_ATTACHMENT
Opaque data information usually sparse.
Definition: avutil.h:205
version.h
pixfmt.h
av_get_media_type_string
const char * av_get_media_type_string(enum AVMediaType media_type)
Return a string describing the media_type enum, NULL if media_type is unknown.
Definition: utils.c:28
AV_PICTURE_TYPE_B
@ AV_PICTURE_TYPE_B
Bi-dir predicted.
Definition: avutil.h:276
mode
mode
Definition: ebur128.h:83
AV_PICTURE_TYPE_P
@ AV_PICTURE_TYPE_P
Predicted.
Definition: avutil.h:275
AVMEDIA_TYPE_VIDEO
@ AVMEDIA_TYPE_VIDEO
Definition: avutil.h:201
AV_PICTURE_TYPE_BI
@ AV_PICTURE_TYPE_BI
BI type.
Definition: avutil.h:280
AV_PICTURE_TYPE_S
@ AV_PICTURE_TYPE_S
S(GMC)-VOP MPEG-4.
Definition: avutil.h:277
fourcc
uint32_t fourcc
Definition: vaapi_decode.c:241
av_x_if_null
static void * av_x_if_null(const void *p, const void *x)
Return x default pointer in case p is NULL.
Definition: avutil.h:308