lavc: rewrite and extend AVFrame doxy
authorAnton Khirnov <anton@khirnov.net>
Fri, 21 Dec 2012 20:50:50 +0000 (21:50 +0100)
committerAnton Khirnov <anton@khirnov.net>
Sun, 23 Dec 2012 09:35:27 +0000 (10:35 +0100)
libavcodec/avcodec.h

index d12c72b..d9a2dc2 100644 (file)
@@ -972,11 +972,19 @@ enum AVSideDataParamChangeFlags {
  */
 
 /**
  */
 
 /**
- * Audio Video Frame.
- * New fields can be added to the end of AVFRAME with minor version
- * bumps. Removal, reordering and changes to existing fields require
- * a major version bump.
- * sizeof(AVFrame) must not be used outside libav*.
+ * This structure describes decoded (raw) audio or video data.
+ *
+ * AVFrame must be allocated using avcodec_alloc_frame() and freed with
+ * avcodec_free_frame(). Note that this allocates only the AVFrame itself. The
+ * buffers for the data must be managed through other means.
+ *
+ * AVFrame is typically allocated once and then reused multiple times to hold
+ * different data (e.g. a single AVFrame to hold frames received from a
+ * decoder). In such a case, avcodec_get_frame_defaults() should be used to
+ * reset the frame to its original clean state before it is reused again.
+ *
+ * sizeof(AVFrame) is not a part of the public ABI, so new fields may be added
+ * to the end with a minor bump.
  */
 typedef struct AVFrame {
 #define AV_NUM_DATA_POINTERS 8
  */
 typedef struct AVFrame {
 #define AV_NUM_DATA_POINTERS 8