[FFmpeg-cvslog] avcodec/packet: add some documentation for AVPacketSideData

[James Almer]

ffmpeg | branch: master | James Almer <jamrial at gmail.com> | Tue Sep 26 19:24:06 2023 -0300| [e500eb5a95afefb4a012814b7f8af2dd6869a641] | committer: James Almer

avcodec/packet: add some documentation for AVPacketSideData

Explaining what or who may use it, and in what scenarios.

Signed-off-by: James Almer <jamrial at gmail.com>

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

 libavcodec/packet.h | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/libavcodec/packet.h b/libavcodec/packet.h
index 96fc0084d6..b19409b719 100644
--- a/libavcodec/packet.h
+++ b/libavcodec/packet.h
@@ -312,6 +312,33 @@ enum AVPacketSideDataType {
 
 #define AV_PKT_DATA_QUALITY_FACTOR AV_PKT_DATA_QUALITY_STATS //DEPRECATED
 
+/**
+ * This structure stores auxiliary information for decoding, presenting, or
+ * otherwise processing the coded stream. It is typically exported by demuxers
+ * and encoders and can be fed to decoders and muxers either in a per packet
+ * basis, or as global side data (applying to the entire coded stream).
+ *
+ * Global side data is handled as follows:
+ * - During demuxing, it may be exported through
+ *   @ref AVStream.codecpar.side_data "AVStream's codec parameters", which can
+ *   then be passed as input to decoders through the
+ *   @ref AVCodecContext.coded_side_data "decoder context's side data", for
+ *   initialization.
+ * - For muxing, it can be fed through @ref AVStream.codecpar.side_data
+ *   "AVStream's codec parameters", typically  the output of encoders through
+ *   the @ref AVCodecContext.coded_side_data "encoder context's side data", for
+ *   initialization.
+ *
+ * Packet specific side data is handled as follows:
+ * - During demuxing, it may be exported through @ref AVPacket.side_data
+ *   "AVPacket's side data", which can then be passed as input to decoders.
+ * - For muxing, it can be fed through @ref AVPacket.side_data "AVPacket's
+ *   side data", typically the output of encoders.
+ *
+ * Different modules may accept or export different types of side data
+ * depending on media type and codec. Refer to @ref AVPacketSideDataType for a
+ * list of defined types and where they may be found or used.
+ */
 typedef struct AVPacketSideData {
     uint8_t *data;
     size_t   size;