diff --git a/libavutil/adler32.h b/libavutil/adler32.h index 913db2d0b6e6a9b435e03c642ee561d042b8ff84..a8ff6f9d41c24814952b62b4b85c188c9fdb5278 100644 --- a/libavutil/adler32.h +++ b/libavutil/adler32.h @@ -25,6 +25,7 @@ #include "attributes.h" /** + * @ingroup lavu_crypto * Calculate the Adler32 checksum of a buffer. * * Passing the return value to a subsequent av_adler32_update() call diff --git a/libavutil/aes.h b/libavutil/aes.h index 6e5d32048715ae4f423bed4f8888fc5581607dbf..cf7b462092764561253adf176a3517c17aa553e8 100644 --- a/libavutil/aes.h +++ b/libavutil/aes.h @@ -23,6 +23,12 @@ #include <stdint.h> +/** + * @defgroup lavu_aes AES + * @ingroup lavu_crypto + * @{ + */ + extern const int av_aes_size; struct AVAES; @@ -44,4 +50,8 @@ int av_aes_init(struct AVAES *a, const uint8_t *key, int key_bits, int decrypt); */ void av_aes_crypt(struct AVAES *a, uint8_t *dst, const uint8_t *src, int count, uint8_t *iv, int decrypt); +/** + * @} + */ + #endif /* AVUTIL_AES_H */ diff --git a/libavutil/audioconvert.h b/libavutil/audioconvert.h index e37a2e84c1e58a42660ed43cd6072d68f71b20ad..1c5cfa0a8e63271152edba9d094fdd2765d6313c 100644 --- a/libavutil/audioconvert.h +++ b/libavutil/audioconvert.h @@ -29,7 +29,15 @@ * audio conversion routines */ -/* Audio channel masks */ +/** + * @addtogroup lavu_audio + * @{ + */ + +/** + * @defgroup channel_masks Audio channel masks + * @{ + */ #define AV_CH_FRONT_LEFT 0x00000001 #define AV_CH_FRONT_RIGHT 0x00000002 #define AV_CH_FRONT_CENTER 0x00000004 @@ -56,7 +64,11 @@ to be the native codec channel order. */ #define AV_CH_LAYOUT_NATIVE 0x8000000000000000LL -/* Audio channel convenience macros */ +/** + * @} + * @defgroup channel_mask_c Audio channel convenience macros + * @{ + * */ #define AV_CH_LAYOUT_MONO (AV_CH_FRONT_CENTER) #define AV_CH_LAYOUT_STEREO (AV_CH_FRONT_LEFT|AV_CH_FRONT_RIGHT) #define AV_CH_LAYOUT_2_1 (AV_CH_LAYOUT_STEREO|AV_CH_BACK_CENTER) @@ -73,6 +85,10 @@ #define AV_CH_LAYOUT_7POINT1_WIDE (AV_CH_LAYOUT_5POINT1_BACK|AV_CH_FRONT_LEFT_OF_CENTER|AV_CH_FRONT_RIGHT_OF_CENTER) #define AV_CH_LAYOUT_STEREO_DOWNMIX (AV_CH_STEREO_LEFT|AV_CH_STEREO_RIGHT) +/** + * @} + */ + /** * Return a channel layout id that matches name, 0 if no match. */ @@ -92,4 +108,8 @@ void av_get_channel_layout_string(char *buf, int buf_size, int nb_channels, int6 */ int av_get_channel_layout_nb_channels(int64_t channel_layout); +/** + * @} + */ + #endif /* AVUTIL_AUDIOCONVERT_H */ diff --git a/libavutil/avstring.h b/libavutil/avstring.h index 6988f0e3e8c46e23893442533f98c98b72888693..35b3d46c035060ba23cf46cc18487aae47f4da96 100644 --- a/libavutil/avstring.h +++ b/libavutil/avstring.h @@ -24,6 +24,11 @@ #include <stddef.h> #include "attributes.h" +/** + * @addtogroup lavu_string + * @{ + */ + /** * Return non-zero if pfx is a prefix of str. If it is, *ptr is set to * the address of the first character in str after the prefix. @@ -72,7 +77,7 @@ char *av_stristr(const char *haystack, const char *needle); * @param size size of destination buffer * @return the length of src * - * WARNING: since the return value is the length of src, src absolutely + * @warning since the return value is the length of src, src absolutely * _must_ be a properly 0-terminated string, otherwise this will read beyond * the end of the buffer and possibly crash. */ @@ -90,9 +95,9 @@ size_t av_strlcpy(char *dst, const char *src, size_t size); * @param size size of destination buffer * @return the total length of src and dst * - * WARNING: since the return value use the length of src and dst, these absolutely - * _must_ be a properly 0-terminated strings, otherwise this will read beyond - * the end of the buffer and possibly crash. + * @warning since the return value use the length of src and dst, these + * absolutely _must_ be a properly 0-terminated strings, otherwise this + * will read beyond the end of the buffer and possibly crash. */ size_t av_strlcat(char *dst, const char *src, size_t size); @@ -153,14 +158,18 @@ static inline int av_tolower(int c) /* * Locale independent case-insensitive compare. - * Note: This means only ASCII-range characters are case-insensitive + * @note This means only ASCII-range characters are case-insensitive */ int av_strcasecmp(const char *a, const char *b); /** * Locale independent case-insensitive compare. - * Note: This means only ASCII-range characters are case-insensitive + * @note This means only ASCII-range characters are case-insensitive */ int av_strncasecmp(const char *a, const char *b, size_t n); +/** + * @} + */ + #endif /* AVUTIL_AVSTRING_H */ diff --git a/libavutil/avutil.h b/libavutil/avutil.h index 436f79b82dddae5e25be0f3ed222fe527e8fb396..659a10f0703c966cb02b5d4c805fb4cdd24592d4 100644 --- a/libavutil/avutil.h +++ b/libavutil/avutil.h @@ -26,6 +26,95 @@ * external API header */ +/** + * @mainpage + * + * @section libav_intro Introduction + * + * This document describe the usage of the different libraries + * provided by Libav. + * + * @li @subpage libavcodec encoding/decoding library + * @li @subpage libavfilter graph based frame editing library + * @li @subpage libavformat I/O and muxing/demuxing library + * @li @ref lavu "libavutil" common utility library + * @li @subpage libpostproc post processing library + * @li @subpage libswscale color conversion and scaling library + * + */ + +/** + * @defgroup lavu Common utility functions + * + * @brief + * libavutil contains the code shared across all the other Libav + * 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 + * + * @{ + * + * @} + * + * @defgroup lavu_misc Other + * + * @{ + * + * @defgroup lavu_internal Internal + * + * Not exported functions, for internal usage only + * + * @{ + * + * @} + */ + + +/** + * @defgroup preproc_misc Preprocessor String Macros + * + * String manipulation macros + * + * @{ + */ #define AV_STRINGIFY(s) AV_TOSTRING(s) #define AV_TOSTRING(s) #s @@ -35,10 +124,34 @@ #define AV_PRAGMA(s) _Pragma(#s) +/** + * @} + */ + +/** + * @defgroup version_utils Library Version Macros + * + * Useful to check and match library version in order to maintain + * backward compatibility. + * + * @{ + */ + #define AV_VERSION_INT(a, b, c) (a<<16 | b<<8 | c) #define AV_VERSION_DOT(a, b, c) a ##.## b ##.## c #define AV_VERSION(a, b, c) AV_VERSION_DOT(a, b, c) +/** + * @} + * + * @defgroup lavu_ver Version and Build diagnostics + * + * Macros and function useful to check at compiletime and at runtime + * which version of libavutil is in use. + * + * @{ + */ + #define LIBAVUTIL_VERSION_MAJOR 51 #define LIBAVUTIL_VERSION_MINOR 16 #define LIBAVUTIL_VERSION_MICRO 0 @@ -54,8 +167,16 @@ #define LIBAVUTIL_IDENT "Lavu" AV_STRINGIFY(LIBAVUTIL_VERSION) /** + * @} + * + * @defgroup depr_guards Deprecation guards * Those FF_API_* defines are not part of public API. * They may change, break or disappear at any time. + * + * They are used mostly internally to mark code that will be removed + * on the next major version. + * + * @{ */ #ifndef FF_API_GET_BITS_PER_SAMPLE_FMT #define FF_API_GET_BITS_PER_SAMPLE_FMT (LIBAVUTIL_VERSION_MAJOR < 52) @@ -70,6 +191,15 @@ #define FF_API_OLD_AVOPTIONS (LIBAVUTIL_VERSION_MAJOR < 52) #endif +/** + * @} + */ + +/** + * @addtogroup lavu_ver + * @{ + */ + /** * Return the LIBAVUTIL_VERSION_INT constant. */ @@ -85,16 +215,35 @@ const char *avutil_configuration(void); */ const char *avutil_license(void); +/** + * @} + */ + +/** + * @addtogroup lavu_media Media Type + * @brief Media Type + */ + enum AVMediaType { - AVMEDIA_TYPE_UNKNOWN = -1, + AVMEDIA_TYPE_UNKNOWN = -1, ///< Usually treated as AVMEDIA_TYPE_DATA AVMEDIA_TYPE_VIDEO, AVMEDIA_TYPE_AUDIO, - AVMEDIA_TYPE_DATA, + AVMEDIA_TYPE_DATA, ///< Opaque data information usually continuous AVMEDIA_TYPE_SUBTITLE, - AVMEDIA_TYPE_ATTACHMENT, + AVMEDIA_TYPE_ATTACHMENT, ///< Opaque data information usually sparse AVMEDIA_TYPE_NB }; +/** + * @defgroup lavu_const Constants + * @{ + * + * @defgroup lavu_enc Encoding specific + * + * @note those definition should move to avcodec + * @{ + */ + #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 @@ -102,10 +251,46 @@ enum AVMediaType { #define FF_QUALITY_SCALE FF_LAMBDA_SCALE //FIXME maybe remove +/** + * @} + * @defgroup lavu_time Timestamp specific + * + * Libav internal timebase and timestamp definitions + * + * @{ + */ + +/** + * @brief Undefined timestamp value + * + * Usually reported by demuxer that work on containers that do not provide + * either pts or dts. + */ + #define AV_NOPTS_VALUE INT64_C(0x8000000000000000) + +/** + * Internal time base represented as integer + */ + #define AV_TIME_BASE 1000000 + +/** + * Internal time base represented as fractional value + */ + #define AV_TIME_BASE_Q (AVRational){1, AV_TIME_BASE} +/** + * @} + * @} + * @defgroup lavu_picture Image related + * + * AVPicture types, pixel formats and basic image planes manipulation. + * + * @{ + */ + enum AVPictureType { AV_PICTURE_TYPE_I = 1, ///< Intra AV_PICTURE_TYPE_P, ///< Predicted @@ -125,7 +310,16 @@ enum AVPictureType { */ char av_get_picture_type_char(enum AVPictureType pict_type); +/** + * @} + */ + #include "common.h" #include "error.h" +/** + * @} + * @} + */ + #endif /* AVUTIL_AVUTIL_H */ diff --git a/libavutil/base64.h b/libavutil/base64.h index 96c0a4a41e339a5f155f2391e3e9bd02d50c32bd..4750cf5c724aeea26a3940fb8ba9ffe6264507df 100644 --- a/libavutil/base64.h +++ b/libavutil/base64.h @@ -23,6 +23,13 @@ #include <stdint.h> +/** + * @defgroup lavu_base64 Base64 + * @ingroup lavu_crypto + * @{ + */ + + /** * Decode a base64-encoded string. * @@ -51,4 +58,8 @@ char *av_base64_encode(char *out, int out_size, const uint8_t *in, int in_size); */ #define AV_BASE64_SIZE(x) (((x)+2) / 3 * 4 + 1) + /** + * @} + */ + #endif /* AVUTIL_BASE64_H */ diff --git a/libavutil/dict.h b/libavutil/dict.h index b0061c8475a019a673bb4acbd96e2683f186d841..6e28b61406f782677f385af22a91fb6dd6ec7f83 100644 --- a/libavutil/dict.h +++ b/libavutil/dict.h @@ -26,7 +26,11 @@ #define AVUTIL_DICT_H /** - * @defgroup dict_api Public Dictionary API + * @addtogroup lavu_dict AVDictionary + * @ingroup lavu_data + * + * @brief Simple key:value store + * * @{ * Dictionaries are used for storing key:value pairs. To create * an AVDictionary, simply pass an address of a NULL pointer to @@ -52,7 +56,6 @@ * av_dict_free(&d); * @endcode * - * @} */ #define AV_DICT_MATCH_CASE 1 @@ -111,4 +114,8 @@ void av_dict_copy(AVDictionary **dst, AVDictionary *src, int flags); */ void av_dict_free(AVDictionary **m); +/** + * @} + */ + #endif // AVUTIL_DICT_H diff --git a/libavutil/error.h b/libavutil/error.h index ba12d2bfaee0f03419c395f7f68d5273963b619b..8ed77342ef199b871182f7da07f33959652c9c23 100644 --- a/libavutil/error.h +++ b/libavutil/error.h @@ -27,6 +27,13 @@ #include <errno.h> #include "avutil.h" +/** + * @addtogroup lavu_error + * + * @{ + */ + + /* error handling */ #if EDOM > 0 #define AVERROR(e) (-(e)) ///< Returns a negative error code from a POSIX error code, to return from library functions. @@ -65,4 +72,8 @@ */ int av_strerror(int errnum, char *errbuf, size_t errbuf_size); +/** + * @} + */ + #endif /* AVUTIL_ERROR_H */ diff --git a/libavutil/imgutils.h b/libavutil/imgutils.h index 6017a70f71ceb97905752dc0378f89821328a615..3815a49ae4f1db60c5f123a0500a6e055f2fa2a8 100644 --- a/libavutil/imgutils.h +++ b/libavutil/imgutils.h @@ -22,6 +22,9 @@ /** * @file * misc image utilities + * + * @addtogroup lavu_picture + * @{ */ #include "avutil.h" @@ -127,4 +130,9 @@ int av_image_check_size(unsigned int w, unsigned int h, int log_offset, void *lo int ff_set_systematic_pal2(uint32_t pal[256], enum PixelFormat pix_fmt); +/** + * @} + */ + + #endif /* AVUTIL_IMGUTILS_H */ diff --git a/libavutil/intmath.h b/libavutil/intmath.h index 3325975556fa9dee83686dc1ffb2e58b317a901c..e6a2e102c414fd648f4d38d04a3a9cef904b1aaa 100644 --- a/libavutil/intmath.h +++ b/libavutil/intmath.h @@ -25,6 +25,11 @@ #include "config.h" #include "attributes.h" +/** + * @addtogroup lavu_internal + * @{ + */ + extern const uint32_t ff_inverse[257]; #if ARCH_ARM @@ -76,4 +81,7 @@ static inline av_const unsigned int ff_sqrt(unsigned int a) return b - (a < b * b); } +/** + * @} + */ #endif /* AVUTIL_INTMATH_H */ diff --git a/libavutil/lzo.h b/libavutil/lzo.h index be86bba6bc3ea56444f6b82513d958a00cb0a565..b4c71c0933e5c53431f55a70f1679528686c7844 100644 --- a/libavutil/lzo.h +++ b/libavutil/lzo.h @@ -22,6 +22,13 @@ #ifndef AVUTIL_LZO_H #define AVUTIL_LZO_H +/** + * @defgroup lavu_lzo LZO + * @ingroup lavu_crypto + * + * @{ + */ + #include <stdint.h> /** @name Error flags returned by av_lzo1x_decode @@ -63,4 +70,8 @@ int av_lzo1x_decode(void *out, int *outlen, const void *in, int *inlen); */ void av_memcpy_backptr(uint8_t *dst, int back, int cnt); +/** + * @} + */ + #endif /* AVUTIL_LZO_H */ diff --git a/libavutil/mathematics.h b/libavutil/mathematics.h index 35494bb39115b253e05269b2c80d466b365416f2..0b072ebe63cfcda52b757737651ba4a1e0fab453 100644 --- a/libavutil/mathematics.h +++ b/libavutil/mathematics.h @@ -57,6 +57,12 @@ #define INFINITY (1.0/0.0) #endif +/** + * @addtogroup lavu_math + * @{ + */ + + enum AVRounding { AV_ROUND_ZERO = 0, ///< Round toward zero. AV_ROUND_INF = 1, ///< Round away from zero. @@ -109,4 +115,8 @@ int av_compare_ts(int64_t ts_a, AVRational tb_a, int64_t ts_b, AVRational tb_b); */ int64_t av_compare_mod(uint64_t a, uint64_t b, uint64_t mod); +/** + * @} + */ + #endif /* AVUTIL_MATHEMATICS_H */ diff --git a/libavutil/md5.h b/libavutil/md5.h index c178bbb4d55a52b7b57da61cd68b82a269c51569..1412ee240112cdd1d38e48bda4e2c2db5bf82f4f 100644 --- a/libavutil/md5.h +++ b/libavutil/md5.h @@ -23,6 +23,12 @@ #include <stdint.h> +/** + * @defgroup lavu_md5 MD5 + * @ingroup lavu_crypto + * @{ + */ + extern const int av_md5_size; struct AVMD5; @@ -32,5 +38,9 @@ void av_md5_update(struct AVMD5 *ctx, const uint8_t *src, const int len); void av_md5_final(struct AVMD5 *ctx, uint8_t *dst); void av_md5_sum(uint8_t *dst, const uint8_t *src, const int len); +/** + * @} + */ + #endif /* AVUTIL_MD5_H */ diff --git a/libavutil/mem.h b/libavutil/mem.h index e14e8d038c5450fbfc60d671d42aa08354561e9f..cd8490b2dae9e885f79921da9693c28f9ed20abd 100644 --- a/libavutil/mem.h +++ b/libavutil/mem.h @@ -29,6 +29,12 @@ #include "attributes.h" #include "avutil.h" +/** + * @addtogroup lavu_mem + * @{ + */ + + #if defined(__ICC) && _ICC < 1200 || defined(__SUNPRO_C) #define DECLARE_ALIGNED(n,t,v) t __attribute__ ((aligned (n))) v #define DECLARE_ASM_CONST(n,t,v) const t __attribute__ ((aligned (n))) v @@ -123,4 +129,8 @@ char *av_strdup(const char *s) av_malloc_attrib; */ void av_freep(void *ptr); +/** + * @} + */ + #endif /* AVUTIL_MEM_H */ diff --git a/libavutil/opt.h b/libavutil/opt.h index 6182326af28fe103f439749854358f0898ee6d03..19549408e2e3df94e7059b24a25e367211920c60 100644 --- a/libavutil/opt.h +++ b/libavutil/opt.h @@ -34,6 +34,7 @@ /** * @defgroup avoptions AVOptions + * @ingroup lavu_data * @{ * AVOptions provide a generic system to declare options on arbitrary structs * ("objects"). An option can have a help text, a type and a range of possible @@ -212,7 +213,6 @@ * filled with option as a parameter. This allows to set some options * that cannot be set otherwise, since e.g. the input file format is not known * before the file is actually opened. - * @} */ enum AVOptionType{ @@ -584,6 +584,7 @@ int av_opt_get_int (void *obj, const char *name, int search_flags, int64_t int av_opt_get_double(void *obj, const char *name, int search_flags, double *out_val); int av_opt_get_q (void *obj, const char *name, int search_flags, AVRational *out_val); /** + * @} * @} */ diff --git a/libavutil/random_seed.h b/libavutil/random_seed.h index 5bfeb8b8351f077d776f7f40e98443a3afd499e1..b1fad13d0757a04b151640146e2f4e5d2327b55b 100644 --- a/libavutil/random_seed.h +++ b/libavutil/random_seed.h @@ -22,6 +22,10 @@ #define AVUTIL_RANDOM_SEED_H #include <stdint.h> +/** + * @addtogroup lavu_crypto + * @{ + */ /** * Get random data. @@ -33,4 +37,8 @@ */ uint32_t av_get_random_seed(void); +/** + * @} + */ + #endif /* AVUTIL_RANDOM_SEED_H */ diff --git a/libavutil/rational.h b/libavutil/rational.h index a4871148bdde239b4c5ea9a26f0cbb466eb67f1a..0ec18ec9697a311ab23ce331db6ed4fd1a1a61a8 100644 --- a/libavutil/rational.h +++ b/libavutil/rational.h @@ -32,6 +32,11 @@ #include <limits.h> #include "attributes.h" +/** + * @addtogroup lavu_math + * @{ + */ + /** * rational number numerator/denominator */ @@ -132,4 +137,8 @@ int av_nearer_q(AVRational q, AVRational q1, AVRational q2); */ int av_find_nearest_q_idx(AVRational q, const AVRational* q_list); +/** + * @} + */ + #endif /* AVUTIL_RATIONAL_H */ diff --git a/libavutil/sha.h b/libavutil/sha.h index df261fa4b57a448b4dd84ba16967f84f791409e4..8350954c4b4897eac7f67472c536239bdf113d16 100644 --- a/libavutil/sha.h +++ b/libavutil/sha.h @@ -23,6 +23,12 @@ #include <stdint.h> +/** + * @defgroup lavu_sha SHA + * @ingroup lavu_crypto + * @{ + */ + extern const int av_sha_size; struct AVSHA; @@ -53,4 +59,8 @@ void av_sha_update(struct AVSHA* context, const uint8_t* data, unsigned int len) */ void av_sha_final(struct AVSHA* context, uint8_t *digest); +/** + * @} + */ + #endif /* AVUTIL_SHA_H */ diff --git a/libavutil/tree.h b/libavutil/tree.h index 9115e2fec1cbe58b52c3861ff534ddbc68c620c0..59ea01dbdb049b3b627806a0ada1cb29989a5af4 100644 --- a/libavutil/tree.h +++ b/libavutil/tree.h @@ -21,14 +21,24 @@ /** * @file * A tree container. - * Insertion, removal, finding equal, largest which is smaller than and - * smallest which is larger than, all have O(log n) worst case complexity. * @author Michael Niedermayer <michaelni@gmx.at> */ #ifndef AVUTIL_TREE_H #define AVUTIL_TREE_H +/** + * @addtogroup lavu_tree AVTree + * @ingroup lavu_data + * + * Low complexity tree container + * + * Insertion, removal, finding equal, largest which is smaller than and + * smallest which is larger than, all have O(log n) worst case complexity. + * @{ + */ + + struct AVTreeNode; extern const int av_tree_node_size; @@ -91,5 +101,8 @@ void av_tree_destroy(struct AVTreeNode *t); */ void av_tree_enumerate(struct AVTreeNode *t, void *opaque, int (*cmp)(void *opaque, void *elem), int (*enu)(void *opaque, void *elem)); +/** + * @} + */ #endif /* AVUTIL_TREE_H */