diff options
Diffstat (limited to 'libavutil/frame.h')
-rw-r--r-- | libavutil/frame.h | 30 |
1 files 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; |