[FFmpeg-cvslog] lavc: Deprecate AVPicture structure and related functions

[Vittorio Giovara]

ffmpeg | branch: master | Vittorio Giovara <vittorio.giovara at gmail.com> | Wed Oct 14 11:33:28 2015 +0200| [dca23ffbc7568c9af5c5fbaa86e6a0761ecae50c] | committer: Vittorio Giovara

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 at gmail.com>

> http://git.videolan.org/gitweb.cgi/ffmpeg.git/?a=commit;h=dca23ffbc7568c9af5c5fbaa86e6a0761ecae50c
---

 libavcodec/avcodec.h    |   50 ++++++++++++++++++++---------------------------
 libavcodec/avpicture.c  |    3 ++-
 libavcodec/imgconvert.c |    2 ++
 3 files changed, 25 insertions(+), 30 deletions(-)

diff --git a/libavcodec/avcodec.h b/libavcodec/avcodec.h
index 42f90d5..0876343 100644
--- a/libavcodec/avcodec.h
+++ b/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.
- *
- * @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
+ * @deprecated unused
  */
+attribute_deprecated
 int avpicture_alloc(AVPicture *picture, enum AVPixelFormat pix_fmt, int width, int height);
 
 /**
- * Free a picture previously allocated by avpicture_alloc().
- * The data buffer used by the AVPicture is freed, but the AVPicture structure
- * itself is not.
- *
- * @param picture the AVPicture to be freed
+ * @deprecated unused
  */
+attribute_deprecated
 void avpicture_free(AVPicture *picture);
 
 /**
- * Fill in the AVPicture fields, always assume a linesize alignment of 1.
- *
- * @see av_image_fill_arrays().
+ * @deprecated use av_image_fill_arrays() instead.
  */
+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
- * linesize alignment of 1.
- *
- * @see av_image_copy_to_buffer().
+ * @deprecated use av_image_copy_to_buffer() instead.
  */
+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
- * would occupy if stored in the given picture format.
- * Always assume a linesize alignment of 1.
- *
- * @see av_image_get_buffer_size().
+ * @deprecated use av_image_get_buffer_size() instead.
  */
+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
diff --git a/libavcodec/avpicture.c b/libavcodec/avpicture.c
index 6bde0f8..eaa5c26 100644
--- a/libavcodec/avpicture.c
+++ b/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 */
diff --git a/libavcodec/imgconvert.c b/libavcodec/imgconvert.c
index 53e7df8..55a9213 100644
--- a/libavcodec/imgconvert.c
+++ b/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 */