lavc: Deprecate AVPicture structure and related functions

This structure served as a bridge between data pointers and frames,
but it suffers from several limitations:
- it is not refcounted and data must be copied to every time
- it cannot be expanded without ABI break due to being used on the stack
- its functions are just wrappers to imgutils which add a layer of
  unneeded indirection, and maintenance burden
- it allows hacks like embedding uncompressed data in packets
- its use is often confusing to our users

AVFrame provides a much better API, and, if a full blown frame is not
needed, it is just as simple and more straightfoward to use data and
linesize arrays directly.

Signed-off-by: Vittorio Giovara <vittorio.giovara@gmail.com>

libavcodec/avcodec.h

@@ -3165,6 +3165,7 @@ typedef struct AVHWAccel {
  * @}
  */
 
+#if FF_API_AVPICTURE
 /**
  * @defgroup lavc_picture AVPicture
  *
@@ -3176,6 +3177,7 @@ typedef struct AVHWAccel {
  * four components are given, that's all.
  * the last component is alpha
  */
+attribute_deprecated
 typedef struct AVPicture {
     uint8_t *data[AV_NUM_DATA_POINTERS];
     int linesize[AV_NUM_DATA_POINTERS];     ///< number of bytes per line
@@ -3184,6 +3186,7 @@ typedef struct AVPicture {
 /**
  * @}
  */
+#endif
 
 #define AVPALETTE_SIZE 1024
 #define AVPALETTE_COUNT 256
@@ -4132,81 +4135,70 @@ int avcodec_encode_subtitle(AVCodecContext *avctx, uint8_t *buf, int buf_size,
  * @}
  */
 
+#if FF_API_AVPICTURE
 /**
  * @addtogroup lavc_picture
  * @{
  */
 
 /**
- * Allocate memory for a picture.  Call avpicture_free() to free it.
+ * @deprecated unused
- *
- * @see avpicture_fill()
- *
- * @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
  */
+attribute_deprecated
 int avpicture_alloc(AVPicture *picture, enum AVPixelFormat pix_fmt, int width, int height);
 
 /**
- * Free a picture previously allocated by avpicture_alloc().
+ * @deprecated unused
- * The data buffer used by the AVPicture is freed, but the AVPicture structure
- * itself is not.
- *
- * @param picture the AVPicture to be freed
  */
+attribute_deprecated
 void avpicture_free(AVPicture *picture);
 
 /**
- * Fill in the AVPicture fields, always assume a linesize alignment of 1.
+ * @deprecated use av_image_fill_arrays() instead.
- *
- * @see av_image_fill_arrays().
  */
+attribute_deprecated
 int avpicture_fill(AVPicture *picture, uint8_t *ptr,
                    enum AVPixelFormat pix_fmt, int width, int height);
 
 /**
- * Copy pixel data from an AVPicture into a buffer, always assume a
+ * @deprecated use av_image_copy_to_buffer() instead.
- * linesize alignment of 1.
- *
- * @see av_image_copy_to_buffer().
  */
+attribute_deprecated
 int avpicture_layout(const AVPicture* src, enum AVPixelFormat pix_fmt,
                      int width, int height,
                      unsigned char *dest, int dest_size);
 
 /**
- * Calculate the size in bytes that a picture of the given width and height
+ * @deprecated use av_image_get_buffer_size() instead.
- * would occupy if stored in the given picture format.
- * Always assume a linesize alignment of 1.
- *
- * @see av_image_get_buffer_size().
  */
+attribute_deprecated
 int avpicture_get_size(enum AVPixelFormat pix_fmt, int width, int height);
 
 /**
- * Copy image src to dst. Wraps av_picture_data_copy() above.
+ * @deprecated av_image_copy() instead.
  */
+attribute_deprecated
 void av_picture_copy(AVPicture *dst, const AVPicture *src,
                      enum AVPixelFormat pix_fmt, int width, int height);
 
 /**
- * Crop image top and left side.
+ * @deprecated unused
  */
+attribute_deprecated
 int av_picture_crop(AVPicture *dst, const AVPicture *src,
                     enum AVPixelFormat pix_fmt, int top_band, int left_band);
 
 /**
- * Pad image.
+ * @deprecated unused
  */
+attribute_deprecated
 int av_picture_pad(AVPicture *dst, const AVPicture *src, int height, int width, enum AVPixelFormat pix_fmt,
             int padtop, int padbottom, int padleft, int padright, int *color);
 
 /**
  * @}
  */
+#endif
 
 /**
  * @defgroup lavc_misc Utility functions

libavcodec/avpicture.c

@@ -31,6 +31,7 @@
 #include "libavutil/imgutils.h"
 #include "libavutil/colorspace.h"
 
+#if FF_API_AVPICTURE
 int avpicture_fill(AVPicture *picture, uint8_t *ptr,
                    enum AVPixelFormat pix_fmt, int width, int height)
 {
@@ -76,4 +77,4 @@ void av_picture_copy(AVPicture *dst, const AVPicture *src,
     av_image_copy(dst->data, dst->linesize, src->data,
                   src->linesize, pix_fmt, width, height);
 }
-
+#endif /* FF_API_AVPICTURE */

libavcodec/imgconvert.c

@@ -252,6 +252,7 @@ static inline int is_yuv_planar(const AVPixFmtDescriptor *desc)
              (desc->flags & AV_PIX_FMT_FLAG_PLANAR));
 }
 
+#if FF_API_AVPICTURE
 int av_picture_crop(AVPicture *dst, const AVPicture *src,
                     enum AVPixelFormat pix_fmt, int top_band, int left_band)
 {
@@ -335,3 +336,4 @@ int av_picture_pad(AVPicture *dst, const AVPicture *src, int height, int width,
     }
     return 0;
 }
+#endif /* FF_API_AVPICTURE */