diff mbox series

[FFmpeg-devel,1/8] lavu/frame: improve AVFrame.opaque[_ref] documentation

Message ID 20230228120104.2347-1-anton@khirnov.net
State Accepted
Commit d732db3a384a6cf2e9431277bd98b363889e62f5
Headers show
Series [FFmpeg-devel,1/8] lavu/frame: improve AVFrame.opaque[_ref] documentation | expand

Checks

Context Check Description
yinshiyou/make_loongarch64 success Make finished
yinshiyou/make_fate_loongarch64 success Make fate finished
andriy/make_x86 success Make finished
andriy/make_fate_x86 success Make fate finished

Commit Message

Anton Khirnov Feb. 28, 2023, noon UTC 
Make them match each other, mention interaction with
AV_CODEC_FLAG_COPY_OPAQUE.
---
 libavutil/frame.h | 30 +++++++++++++++++++++++-------
 1 file changed, 23 insertions(+), 7 deletions(-)
diff mbox series

Patch

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;