[FFmpeg-cvslog] lavc: improve AVCodecContext.extradata/subtitle_header documentation

[Anton Khirnov]

ffmpeg | branch: master | Anton Khirnov <anton at khirnov.net> | Thu Dec  5 10:52:03 2024 +0100| [183c59b4738c20e65ffe63b456c6f7bb0d5caf5b] | committer: Anton Khirnov

lavc: improve AVCodecContext.extradata/subtitle_header documentation

Mention they are always owned and freed by the codec, except when using
deprecated avcodec_close().

Reported-By: DEATH on IRC

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

 libavcodec/avcodec.h | 40 ++++++++++++++++++++++++++++------------
 1 file changed, 28 insertions(+), 12 deletions(-)

diff --git a/libavcodec/avcodec.h b/libavcodec/avcodec.h
index 77ca8dee1f..12e6e8749f 100644
--- a/libavcodec/avcodec.h
+++ b/libavcodec/avcodec.h
@@ -515,16 +515,24 @@ typedef struct AVCodecContext {
     int flags2;
 
     /**
-     * some codecs need / can use extradata like Huffman tables.
-     * MJPEG: Huffman tables
-     * rv10: additional flags
-     * MPEG-4: global headers (they can be in the bitstream or here)
-     * The allocated memory should be AV_INPUT_BUFFER_PADDING_SIZE bytes larger
-     * than extradata_size to avoid problems if it is read with the bitstream reader.
-     * The bytewise contents of extradata must not depend on the architecture or CPU endianness.
-     * Must be allocated with the av_malloc() family of functions.
-     * - encoding: Set/allocated/freed by libavcodec.
-     * - decoding: Set/allocated/freed by user.
+     * Out-of-band global headers that may be used by some codecs.
+     *
+     * - decoding: Should be set by the caller when available (typically from a
+     *   demuxer) before opening the decoder; some decoders require this to be
+     *   set and will fail to initialize otherwise.
+     *
+     *   The array must be allocated with the av_malloc() family of functions;
+     *   allocated size must be at least AV_INPUT_BUFFER_PADDING_SIZE bytes
+     *   larger than extradata_size.
+     *
+     * - encoding: May be set by the encoder in avcodec_open2() (possibly
+     *   depending on whether the AV_CODEC_FLAG_GLOBAL_HEADER flag is set).
+     *
+     * After being set, the array is owned by the codec and freed in
+     * avcodec_free_context().
+     *
+     * @warning the deprecated avcodec_close() function DOES NOT free this array
+     * for decoding, it must be freed manually by the caller.
      */
     uint8_t *extradata;
     int extradata_size;
@@ -1895,8 +1903,16 @@ typedef struct AVCodecContext {
      * For SUBTITLE_ASS subtitle type, it should contain the whole ASS
      * [Script Info] and [V4+ Styles] section, plus the [Events] line and
      * the Format line following. It shouldn't include any Dialogue line.
-     * - encoding: Set/allocated/freed by user (before avcodec_open2())
-     * - decoding: Set/allocated/freed by libavcodec (by avcodec_open2())
+     *
+     * - encoding: May be set by the caller before avcodec_open2() to an array
+     *   allocated with the av_malloc() family of functions.
+     * - decoding: May be set by libavcodec in avcodec_open2().
+     *
+     * After being set, the array is owned by the codec and freed in
+     * avcodec_free_context().
+     *
+     * @warning the deprecated avcodec_close() function DOES NOT free this array
+     * for encoding, it must be freed manually by the caller.
      */
     int subtitle_header_size;
     uint8_t *subtitle_header;