[FFmpeg-cvslog] avcodec/vlc: Add documentation for ff_init_vlc_sparse()

[Andreas Rheinhardt]

ffmpeg | branch: master | Andreas Rheinhardt <andreas.rheinhardt at outlook.com> | Fri Sep  8 14:10:10 2023 +0200| [7b98a1875d9d0229d647dcabd0bba5f97b6c4975] | committer: Andreas Rheinhardt

avcodec/vlc: Add documentation for ff_init_vlc_sparse()

Mostly taken from the documentation for ff_init_vlc_from_lengths();
also remove the documentation in vlc.c.

Signed-off-by: Andreas Rheinhardt <andreas.rheinhardt at outlook.com>

> http://git.videolan.org/gitweb.cgi/ffmpeg.git/?a=commit;h=7b98a1875d9d0229d647dcabd0bba5f97b6c4975
---

 libavcodec/vlc.c | 23 -----------------------
 libavcodec/vlc.h | 29 +++++++++++++++++++++++++++++
 2 files changed, 29 insertions(+), 23 deletions(-)

diff --git a/libavcodec/vlc.c b/libavcodec/vlc.c
index 9656a9472c..1740b2f80f 100644
--- a/libavcodec/vlc.c
+++ b/libavcodec/vlc.c
@@ -247,29 +247,6 @@ static int vlc_common_end(VLC *vlc, int nb_bits, int nb_codes, VLCcode *codes,
     return 0;
 }
 
-/* Build VLC decoding tables suitable for use with get_vlc().
-
-   'nb_bits' sets the decoding table size (2^nb_bits) entries. The
-   bigger it is, the faster is the decoding. But it should not be too
-   big to save memory and L1 cache. '9' is a good compromise.
-
-   'nb_codes' : number of vlcs codes
-
-   'bits' : table which gives the size (in bits) of each vlc code.
-
-   'codes' : table which gives the bit pattern of of each vlc code.
-
-   'symbols' : table which gives the values to be returned from get_vlc().
-
-   'xxx_wrap' : give the number of bytes between each entry of the
-   'bits' or 'codes' tables.
-
-   'xxx_size' : gives the number of bytes of each entry of the 'bits'
-   or 'codes' tables. Currently 1,2 and 4 are supported.
-
-   'wrap' and 'size' make it possible to use any memory configuration and types
-   (byte/word/long) to store the 'bits', 'codes', and 'symbols' tables.
-*/
 int ff_init_vlc_sparse(VLC *vlc, int nb_bits, int nb_codes,
                        const void *bits, int bits_wrap, int bits_size,
                        const void *codes, int codes_wrap, int codes_size,
diff --git a/libavcodec/vlc.h b/libavcodec/vlc.h
index 46063862f6..8f2f478f9b 100644
--- a/libavcodec/vlc.h
+++ b/libavcodec/vlc.h
@@ -62,6 +62,35 @@ typedef struct RL_VLC_ELEM {
                        codes, codes_wrap, codes_size,   \
                        NULL, 0, 0, flags)
 
+/**
+ * Build VLC decoding tables suitable for use with get_vlc2().
+ *
+ * @param[in,out] vlc      The VLC to be initialized; table and table_allocated
+ *                         must have been set when initializing a static VLC,
+ *                         otherwise this will be treated as uninitialized.
+ * @param[in] nb_bits      The number of bits to use for the VLC table;
+ *                         higher values take up more memory and cache, but
+ *                         allow to read codes with fewer reads.
+ *                         Corresponds to the `bits` parameter of get_vlc2().
+ * @param[in] nb_codes     The number of provided bits, codes and (if supplied)
+ *                         symbol entries.
+ * @param[in] bits         The lengths (in bits) of the codes. Entries > 0
+ *                         correspond to valid codes; entries == 0 will be skipped.
+ * @param[in] bits_wrap    Stride (in bytes) of the bits table.
+ * @param[in] codes_size   Size of the bits. 1, 2 and 4 are supported.
+ * @param[in] codes        Table which gives the bit pattern of of each vlc code.
+ * @param[in] codes_wrap   Stride (in bytes) of the codes table.
+ * @param[in] codes_size   Size of the codes. 1, 2 and 4 are supported.
+ * @param[in] symbols      The symbols, i.e. what is returned from get_vlc2()
+ *                         when the corresponding code is encountered.
+ *                         May be NULL, then 0, 1, 2, 3, 4,... will be used.
+ * @param[in] symbols_wrap Stride (in bytes) of the symbols table.
+ * @param[in] symbols_size Size of the symbols. 1 and 2 are supported.
+ * @param[in] flags        A combination of the INIT_VLC_* flags.
+ *
+ * 'wrap' and 'size' make it possible to use any memory configuration and types
+ * (byte/word/int) to store the 'bits', 'codes', and 'symbols' tables.
+ */
 int ff_init_vlc_sparse(VLC *vlc, int nb_bits, int nb_codes,
                        const void *bits, int bits_wrap, int bits_size,
                        const void *codes, int codes_wrap, int codes_size,