imgutils: expose av_image_copy_plane_uc_from()

The reason why the generic av_image_copy_uc_from() doesn't really
fit in the case for Vulkan is because some planes may be copied via
other methods (such as mapping GPU memory), and if they don't satisfy
the strict alignment requirements, a gpu image->gpu buffer->cpu ram
copy is performed.

We need this for hwcontext_vulkan, and I think this will also be
useful to API users like libplacebo who would rather not write
a custom SIMD memcpy.

doc/APIchanges

@@ -14,6 +14,9 @@ libavutil:     2021-04-27
 
 API changes, most recent first:
 
+2021-08-14 - xxxxxxxxxx - lavu 57.4.100 - imgutils.h
+  Add av_image_copy_plane_uc_from()
+
 2021-08-02 - xxxxxxxxxx - lavc 59.4.100 - packet.h
   Add AVPacket.opaque, AVPacket.opaque_ref, AVPacket.time_base.
 

libavutil/imgutils.c

@@ -356,9 +356,9 @@ static void image_copy_plane(uint8_t       *dst, ptrdiff_t dst_linesize,
     }
 }
 
-static void image_copy_plane_uc_from(uint8_t       *dst, ptrdiff_t dst_linesize,
-                                     const uint8_t *src, ptrdiff_t src_linesize,
-                                     ptrdiff_t bytewidth, int height)
+void av_image_copy_plane_uc_from(uint8_t *dst, ptrdiff_t dst_linesize,
+                                 const uint8_t *src, ptrdiff_t src_linesize,
+                                 ptrdiff_t bytewidth, int height)
 {
     int ret = -1;
 
@@ -440,7 +440,7 @@ void av_image_copy_uc_from(uint8_t *dst_data[4], const ptrdiff_t dst_linesizes[4
                            enum AVPixelFormat pix_fmt, int width, int height)
 {
     image_copy(dst_data, dst_linesizes, src_data, src_linesizes, pix_fmt,
-               width, height, image_copy_plane_uc_from);
+               width, height, av_image_copy_plane_uc_from);
 }
 
 int av_image_fill_arrays(uint8_t *dst_data[4], int dst_linesize[4],

libavutil/imgutils.h

@@ -124,6 +124,24 @@ void av_image_copy_plane(uint8_t       *dst, int dst_linesize,
                          const uint8_t *src, int src_linesize,
                          int bytewidth, int height);
 
+/**
+ * Copy image data located in uncacheable (e.g. GPU mapped) memory. Where
+ * available, this function will use special functionality for reading from such
+ * memory, which may result in greatly improved performance compared to plain
+ * av_image_copy_plane().
+ *
+ * bytewidth must be contained by both absolute values of dst_linesize
+ * and src_linesize, otherwise the function behavior is undefined.
+ *
+ * @note The linesize parameters have the type ptrdiff_t here, while they are
+ *       int for av_image_copy_plane().
+ * @note On x86, the linesizes currently need to be aligned to the cacheline
+ *       size (i.e. 64) to get improved performance.
+ */
+void av_image_copy_plane_uc_from(uint8_t       *dst, ptrdiff_t dst_linesize,
+                                 const uint8_t *src, ptrdiff_t src_linesize,
+                                 ptrdiff_t bytewidth, int height);
+
 /**
  * Copy image in src_data to dst_data.
  *

libavutil/version.h

@@ -79,7 +79,7 @@
  */
 
 #define LIBAVUTIL_VERSION_MAJOR  57
-#define LIBAVUTIL_VERSION_MINOR   3
+#define LIBAVUTIL_VERSION_MINOR   4
 #define LIBAVUTIL_VERSION_MICRO 100
 
 #define LIBAVUTIL_VERSION_INT   AV_VERSION_INT(LIBAVUTIL_VERSION_MAJOR, \