From d732db3a384a6cf2e9431277bd98b363889e62f5 Mon Sep 17 00:00:00 2001 From: Anton Khirnov <anton@khirnov.net> Date: Tue, 26 Jan 2021 16:59:16 +0100 Subject: [PATCH] lavu/frame: improve AVFrame.opaque[_ref] documentation 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 --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;