From 757cd8d876b18c07e00b53fd4e5c01bedc106d2e Mon Sep 17 00:00:00 2001 From: Luca Barbato Date: Sun, 20 Nov 2011 20:38:24 +0100 Subject: [PATCH] doxy: provide a start page and document libavutil Introduce a basic layout, the subpages are currently left empty. Split libavutil in multiple groups as example of the structure --- libavutil/adler32.h | 1 + libavutil/aes.h | 10 ++ libavutil/audioconvert.h | 24 ++++- libavutil/avstring.h | 21 ++-- libavutil/avutil.h | 200 ++++++++++++++++++++++++++++++++++++++- libavutil/base64.h | 11 +++ libavutil/dict.h | 11 ++- libavutil/error.h | 11 +++ libavutil/imgutils.h | 8 ++ libavutil/intmath.h | 8 ++ libavutil/lzo.h | 11 +++ libavutil/mathematics.h | 10 ++ libavutil/md5.h | 10 ++ libavutil/mem.h | 10 ++ libavutil/opt.h | 3 +- libavutil/random_seed.h | 8 ++ libavutil/rational.h | 9 ++ libavutil/sha.h | 10 ++ libavutil/tree.h | 17 +++- 19 files changed, 377 insertions(+), 16 deletions(-) diff --git a/libavutil/adler32.h b/libavutil/adler32.h index 913db2d0b6..a8ff6f9d41 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 6e5d320487..cf7b462092 100644 --- a/libavutil/aes.h +++ b/libavutil/aes.h @@ -23,6 +23,12 @@ #include +/** + * @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 e37a2e84c1..1c5cfa0a8e 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 6988f0e3e8..35b3d46c03 100644 --- a/libavutil/avstring.h +++ b/libavutil/avstring.h @@ -24,6 +24,11 @@ #include #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 436f79b82d..659a10f070 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< +/** + * @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 b0061c8475..6e28b61406 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 ba12d2bfae..8ed77342ef 100644 --- a/libavutil/error.h +++ b/libavutil/error.h @@ -27,6 +27,13 @@ #include #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 6017a70f71..3815a49ae4 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 3325975556..e6a2e102c4 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 be86bba6bc..b4c71c0933 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 /** @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 35494bb391..0b072ebe63 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 c178bbb4d5..1412ee2401 100644 --- a/libavutil/md5.h +++ b/libavutil/md5.h @@ -23,6 +23,12 @@ #include +/** + * @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 e14e8d038c..cd8490b2da 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 6182326af2..19549408e2 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 5bfeb8b835..b1fad13d07 100644 --- a/libavutil/random_seed.h +++ b/libavutil/random_seed.h @@ -22,6 +22,10 @@ #define AVUTIL_RANDOM_SEED_H #include +/** + * @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 a4871148bd..0ec18ec969 100644 --- a/libavutil/rational.h +++ b/libavutil/rational.h @@ -32,6 +32,11 @@ #include #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 df261fa4b5..8350954c4b 100644 --- a/libavutil/sha.h +++ b/libavutil/sha.h @@ -23,6 +23,12 @@ #include +/** + * @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 9115e2fec1..59ea01dbdb 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 */ #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 */