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