[FFmpeg-cvslog] lavu/frame: improve AVFrame.opaque[_ref] documentation

[Anton Khirnov]

ffmpeg | branch: master | Anton Khirnov <anton at khirnov.net> | Tue Jan 26 16:59:16 2021 +0100| [d732db3a384a6cf2e9431277bd98b363889e62f5] | committer: Anton Khirnov

lavu/frame: improve AVFrame.opaque[_ref] documentation

Make them match each other, mention interaction with
AV_CODEC_FLAG_COPY_OPAQUE.

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

 libavutil/frame.h | 30 +++++++++++++++++++++++-------
 1 file changed, 23 insertions(+), 7 deletions(-)

diff --git a/libavutil/frame.h b/libavutil/frame.h
index 2580269549..4ed27cf43f 100644
--- a/libavutil/frame.h
+++ b/libavutil/frame.h
@@ -470,7 +470,18 @@ typedef struct AVFrame {
     int quality;
 
     /**
-     * for some private data of the user
+     * Frame owner's private data.
+     *
+     * This field may be set by the code that allocates/owns the frame data.
+     * It is then not touched by any library functions, except:
+     * - it is copied to other references by av_frame_copy_props() (and hence by
+     *   av_frame_ref());
+     * - it is set to NULL when the frame is cleared by av_frame_unref()
+     * - on the caller's explicit request. E.g. libavcodec encoders/decoders
+     *   will copy this field to/from @ref AVPacket "AVPackets" if the caller sets
+     *   @ref AV_CODEC_FLAG_COPY_OPAQUE.
+     *
+     * @see opaque_ref the reference-counted analogue
      */
     void *opaque;
 
@@ -678,13 +689,18 @@ typedef struct AVFrame {
     AVBufferRef *hw_frames_ctx;
 
     /**
-     * AVBufferRef for free use by the API user. FFmpeg will never check the
-     * contents of the buffer ref. FFmpeg calls av_buffer_unref() on it when
-     * the frame is unreferenced. av_frame_copy_props() calls create a new
-     * reference with av_buffer_ref() for the target frame's opaque_ref field.
+     * Frame owner's private data.
+     *
+     * This field may be set by the code that allocates/owns the frame data.
+     * It is then not touched by any library functions, except:
+     * - a new reference to the underlying buffer is propagated by
+     *   av_frame_copy_props() (and hence by av_frame_ref());
+     * - it is unreferenced in av_frame_unref();
+     * - on the caller's explicit request. E.g. libavcodec encoders/decoders
+     *   will propagate a new reference to/from @ref AVPacket "AVPackets" if the
+     *   caller sets @ref AV_CODEC_FLAG_COPY_OPAQUE.
      *
-     * This is unrelated to the opaque field, although it serves a similar
-     * purpose.
+     * @see opaque the plain pointer analogue
      */
     AVBufferRef *opaque_ref;