@@ -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

@@ -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 */

@@ -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)

@@ -74,6 +86,10 @@

 #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.

  */

 int64_t av_get_channel_layout(const char *name);

@@ -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 */

@@ -25,6 +25,11 @@

 #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 */

@@ -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)

@@ -71,6 +192,15 @@

 #endif

 /**

+ * @}

+ */

+

+/**

+ * @addtogroup lavu_ver

+ * @{

+ */

+

+/**

  * Return the LIBAVUTIL_VERSION_INT constant.

  */

 unsigned avutil_version(void);

@@ -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 */

@@ -24,6 +24,13 @@

 #include <stdint.h>

 /**

+ * @defgroup lavu_base64 Base64

+ * @ingroup lavu_crypto

+ * @{

+ */

+

+

+/**

  * Decode a base64-encoded string.

  *

  * @param out      buffer for decoded data

@@ -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 */

@@ -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

@@ -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 */

@@ -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 */

@@ -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 */

@@ -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 */

@@ -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 */

@@ -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 */

@@ -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 */

@@ -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{

@@ -585,6 +585,7 @@ int av_opt_get_double(void *obj, const char *name, int search_flags, double

 int av_opt_get_q     (void *obj, const char *name, int search_flags, AVRational *out_val);

 /**

  * @}

+ * @}

  */

 #endif /* AVUTIL_OPT_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 */

@@ -33,6 +33,11 @@

 #include "attributes.h"

 /**

+ * @addtogroup lavu_math

+ * @{

+ */

+

+/**

  * rational number numerator/denominator

  */

 typedef struct AVRational{

@@ -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 */

@@ -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 */

@@ -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 */