dri_interface: add __DRI_IMAGE_TRANSFER_USER_STRIDE

Allow the caller to specify the row stride (in bytes) with which an image
should be mapped. Note that completely ignoring USER_STRIDE is a valid
implementation of mapImage.

This is horrible API design. Unfortunately, cros_gralloc does indeed have
a horrible API design -- in that arbitrary images should be allowed to be
mapped with the stride that a linear image of the same width would have.

There is no separate capability bit because it's unclear how stricter
requirements should be defined.

1 files changed, 13 insertions, 3 deletions

diff --git a/include/GL/internal/dri_interface.h b/include/GL/internal/dri_interface.h
index f72531a7a9..34437efe29 100644
--- a/include/GL/internal/dri_interface.h
+++ b/include/GL/internal/dri_interface.h
@@ -1196,7 +1196,7 @@ struct __DRIdri2ExtensionRec {
  * extensions.
  */
 #define __DRI_IMAGE "DRI_IMAGE"
-#define __DRI_IMAGE_VERSION 17
+#define __DRI_IMAGE_VERSION 18
 
 /**
  * These formats correspond to the similarly named MESA_FORMAT_*
@@ -1243,6 +1243,7 @@ struct __DRIdri2ExtensionRec {
 #define __DRI_IMAGE_TRANSFER_WRITE           0x2
 #define __DRI_IMAGE_TRANSFER_READ_WRITE      \
         (__DRI_IMAGE_TRANSFER_READ | __DRI_IMAGE_TRANSFER_WRITE)
+#define __DRI_IMAGE_TRANSFER_USER_STRIDE     0x4 /* since version 18 */
 
 /**
  * Four CC formats that matches with WL_DRM_FORMAT_* from wayland_drm.h,
@@ -1533,8 +1534,17 @@ struct __DRIimageExtensionRec {
     * __DRI_IMAGE_TRANSFER_WRITE; if __DRI_IMAGE_TRANSFER_WRITE is not
     * included, behaviour when writing the mapping is undefined.
     *
-    * Returns the byte stride in *stride, and an opaque pointer to data
-    * tracking the mapping in **data, which must be passed to unmapImage().
+    * When __DRI_IMAGE_TRANSFER_USER_STRIDE is set in \p flags (since version 18),
+    * the driver should attempt to map the image with the byte stride given in
+    * *stride. The caller must ensure that *stride is large enough to hold a
+    * row of the mapping. If the requested stride is not supported, the mapping
+    * may fail, or a mapping with a different stride may be created (in which
+    * case the actual stride is returned in *stride).
+    *
+    * Returns an opaque pointer to data tracking the mapping in **data, which
+    * must be passed to unmapImage().
+    *
+    * Returns the byte stride in *stride.
     *
     * Returns NULL on error.
     *