lavu: improve documentation of some AVFrame functions

[ffmpeg] / libavutil / frame.h

diff --git a/libavutil/frame.h b/libavutil/frame.h
index 8dc4049072075bca4db285666c6934d2e8552df3..89f41fc7befe631e86edc6c716d2805961905967 100644 (file)
--- a/libavutil/frame.h
+++ b/libavutil/frame.h
@@ -1,5 +1,4 @@
 /*
- *
  * This file is part of FFmpeg.
  *
  * FFmpeg is free software; you can redistribute it and/or
@@ -188,6 +187,9 @@ typedef struct AVFrame {
      * see avcodec_align_dimensions2(). Some filters and swscale can read
      * up to 16 bytes beyond the planes, if these filters are to be used,
      * then 16 extra bytes must be allocated.
+     *
+     * NOTE: Except for hwaccel formats, pointers not needed by the format
+     * MUST be set to NULL.
      */
     uint8_t *data[AV_NUM_DATA_POINTERS];
 
@@ -421,6 +423,12 @@ typedef struct AVFrame {
 
     enum AVChromaLocation chroma_location;
 
+    /**
+     * For hwaccel-format frames, this should be a reference to the
+     * AVHWFramesContext describing the frame.
+     */
+    AVBufferRef *hw_frames_ctx;
+
     /**
      * frame timestamp estimated using various heuristics, in stream time base
      * Code outside libavutil should access this field using:
@@ -583,6 +591,10 @@ void av_frame_free(AVFrame **frame);
  * If src is not reference counted, new buffers are allocated and the data is
  * copied.
  *
+ * @warning: dst MUST have been either unreferenced with av_frame_unref(dst),
+ *           or newly allocated with av_frame_alloc() before calling this
+ *           function, or undefined behavior will occur.
+ *
  * @return 0 on success, a negative AVERROR on error
  */
 int av_frame_ref(AVFrame *dst, const AVFrame *src);
@@ -603,6 +615,10 @@ void av_frame_unref(AVFrame *frame);
 
 /**
  * Move everything contained in src to dst and reset src.
+ *
+ * @warning: dst is not unreferenced, but directly overwritten without reading
+ *           or deallocating its contents. Call av_frame_unref(dst) manually
+ *           before calling this function to ensure that no memory is leaked.
  */
 void av_frame_move_ref(AVFrame *dst, AVFrame *src);
 
@@ -618,6 +634,9 @@ void av_frame_move_ref(AVFrame *dst, AVFrame *src);
  * necessary, allocate and fill AVFrame.extended_data and AVFrame.extended_buf.
  * For planar formats, one buffer will be allocated for each plane.
  *
+ * @warning: if frame already has been allocated, undefined behaviour, including
+ *           memory leaks, can occur.
+ *
  * @param frame frame in which to store the new buffers.
  * @param align required buffer size alignment
  *