[FFmpeg-devel] [PATCH] lavc/avcodec.h: extend documentation for AVPicture API

[Stefano Sabatini]

---
 libavcodec/avcodec.h | 52 ++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 46 insertions(+), 6 deletions(-)

diff --git a/libavcodec/avcodec.h b/libavcodec/avcodec.h
index 12a11aa..d0e206d 100644
--- a/libavcodec/avcodec.h
+++ b/libavcodec/avcodec.h
@@ -4286,15 +4286,18 @@ void av_resample_close(struct AVResampleContext *c);
  */
 
 /**
- * Allocate memory for a picture.  Call avpicture_free() to free it.
+ * Allocate memory for a picture and fill picture fields with data
+ * associated to the new allocated buffer.
  *
- * @see avpicture_fill()
+ * Call avpicture_free() to free it.
  *
  * @param picture the picture to be filled in
  * @param pix_fmt the format of the picture
  * @param width the width of the picture
  * @param height the height of the picture
- * @return zero if successful, a negative value if not
+ * @return zero if successful, a negative error code otherwise
+ *
+ * @see av_image_alloc()
  */
 int avpicture_alloc(AVPicture *picture, enum AVPixelFormat pix_fmt, int width, int height);
 
@@ -4308,8 +4311,26 @@ int avpicture_alloc(AVPicture *picture, enum AVPixelFormat pix_fmt, int width, i
 void avpicture_free(AVPicture *picture);
 
 /**
- * Fill in the AVPicture fields, always assume a linesize alignment of
- * 1.
+ * Setup the picture fields based on the specified image parameters
+ * and the provided buffer.
+ *
+ * The picture fields are filled in by using the image data buffer
+ * pointed to by ptr. The image linesize alignment is always supposed
+ * to be 1.
+ *
+ * If ptr is NULL, the function will fill the picture linesize array
+ * and return the required size for the image buffer.
+ *
+ * To allocate an image buffer and fill the picture data in one call,
+ * use av_picture_alloc().
+ *
+ * @param picture       the picture to be filled in
+ * @param ptr           buffer which will contain or contains the actual image data, can be NULL
+ * @param pix_fmt       the pixel format of the image
+ * @param width         the width of the image in pixels
+ * @param height        the height of the image in pixels
+ * @return the size in bytes required for src, a negative error code
+ * in case of failure
  *
  * @see av_image_fill_arrays()
  */
@@ -4320,9 +4341,22 @@ int avpicture_fill(AVPicture *picture, const uint8_t *ptr,
  * Copy pixel data from an AVPicture into a buffer, always assume a
  * linesize alignment of 1.
  *
+ * avpicture_get_size() can be used to compute the required size for
+ * the buffer to fill.
+ *
+ * @param src        source picture with filled data
+ * @param pix_fmt    picture pixel format
+ * @param width      picture width
+ * @param height     picture height
+ * @param dest       destination buffer
+ * @param dest_size  destination buffer size in bytes
+ * @return the number of bytes written to dest, or a negative value
+ * (error code) on error, for example if the destination buffer is not
+ * big enough
+ *
  * @see av_image_copy_to_buffer()
  */
-int avpicture_layout(const AVPicture* src, enum AVPixelFormat pix_fmt,
+int avpicture_layout(const AVPicture *src, enum AVPixelFormat pix_fmt,
                      int width, int height,
                      unsigned char *dest, int dest_size);
 
@@ -4331,6 +4365,12 @@ int avpicture_layout(const AVPicture* src, enum AVPixelFormat pix_fmt,
  * would occupy if stored in the given picture format.
  * Always assume a linesize alignment of 1.
  *
+ * @param pix_fmt    picture pixel format
+ * @param width      picture width
+ * @param height     picture height
+ * @return the computed picture buffer size or a negative error code
+ * in case of error
+ *
  * @see av_image_get_buffer_size().
  */
 int avpicture_get_size(enum AVPixelFormat pix_fmt, int width, int height);
-- 
1.8.1.2