Merge commit '418693bdc5edad72b0d055f741931612d797eb05'

* commit '418693bdc5edad72b0d055f741931612d797eb05':
  lavc: rewrite and extend AVFrame doxy
  opt: avoid segfault in av_opt_next() if the class does not have an option list
  ttadec: fix last frame handling when seeking
  alacdec: do not be too strict about the extradata size

Conflicts:
	libavcodec/alac.c
	libavcodec/avcodec.h
	libavcodec/tta.c
	libavutil/opt.c

Merged-by: Michael Niedermayer <michaelni@gmx.at>

1 files changed, 14 insertions, 6 deletions

diff --git a/libavcodec/avcodec.h b/libavcodec/avcodec.h
index 0241c8a96b..9ee9af1311 100644
--- a/libavcodec/avcodec.h
+++ b/libavcodec/avcodec.h
@@ -1074,14 +1074,22 @@ enum AVSideDataParamChangeFlags {
  */
 
 /**
- * Audio Video Frame.
- * New fields can be added to the end of AVFRAME with minor version
- * bumps. Similarly fields that are marked as to be only accessed by
+ * 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.
+ * Similarly fields that are marked as to be only accessed by
  * av_opt_ptr() can be reordered. This allows 2 forks to add fields
  * without breaking compatibility with each other.
- * Removal, reordering and changes in the remaining cases require
- * a major version bump.
- * sizeof(AVFrame) must not be used outside libavcodec.
  */
 typedef struct AVFrame {
 #define AV_NUM_DATA_POINTERS 8