Draft: Add a VK_MESA_legacy_dma_buf_drm_format_modifier_query extension

appendices/VK_MESA_legacy_dma_buf_drm_format_modifier_query.adoc

@@ -0,0 +1,30 @@
+// Copyright 2023-2025 The Khronos Group Inc.
+//
+// SPDX-License-Identifier: CC-BY-4.0
+
+include::{generated}/meta/{refprefix}VK_MESA_legacy_dma_buf_drm_format_modifier_query.adoc[]
+
+=== Other Extension Metadata
+
+*Last Modified Date*::
+    2025-03-06
+*Interactions and External Dependencies*::
+  - apitext:VK_KHR_external_memory_fd
+*Contributors*::
+  - Faith Ekstrand, Collabora
+
+=== Description
+
+This extension provides a way to query a legacy Linux dma-buf for its
+embedded modifier.
+This is needed by emulation layers which implement OpenGL on top of Vulkan
+and need to interact with legacy window-system components as the X server.
+This extension is not intended for general-purpose use and modifiers should
+be passed explicitly between applications or components whenever possible.
+
+include::{generated}/interfaces/VK_MESA_legacy_dma_buf_drm_format_modifier_query.adoc[]
+
+=== Version History
+
+  * Revision 0, 2025-03-06(Faith Ekstrand)
+  ** Internal revisions

chapters/features.adoc

@@ -8547,6 +8547,31 @@ include::{generated}/validity/structs/VkPhysicalDevicePresentMeteringFeaturesNV.
 endif::VK_NV_present_metering[]
 
 
+ifdef::VK_MESA_legacy_dma_buf_drm_format_modifier_query[]
+[open,refpage='VkPhysicalDeviceLegacyDmaBufDrmFormatModifierQueryFeaturesMESA',desc='Structure describing whether the legacy dma-buf DRM format modifier query feature can be supported by an implementation',type='structs']
+--
+The sname:VkPhysicalDeviceLegacyDmaBufDrmFormatModifierQueryFeaturesMESA structure is defined as:
+
+include::{generated}/api/structs/VkPhysicalDeviceLegacyDmaBufDrmFormatModifierQueryFeaturesMESA.adoc[]
+
+This structure describes the following features:
+
+  * pname:sType is a elink:VkStructureType value identifying this structure.
+  * pname:pNext is `NULL` or a pointer to a structure extending this
+    structure.
+  * [[features-legacyDmaBufDrmFormatModifierQuery]]
+    pname:legacyDmaBufDrmFormatModifierQuery indicates whether the
+    implementation supports querying a DRM format modifier from a legacy
+    dma-buf.
+
+:refpage: VkPhysicalDeviceLegacyDmaBufDrmFormatModifierQueryFeaturesMESA
+include::{chapters}/features.adoc[tag=features]
+
+include::{generated}/validity/structs/VkPhysicalDeviceLegacyDmaBufDrmFormatModifierQueryFeaturesMESA.adoc[]
+--
+endif::VK_MESA_legacy_dma_buf_drm_format_modifier_query[]
+
+
 [[features-requirements]]
 == Feature Requirements
 

chapters/memory.adoc

@@ -2476,6 +2476,12 @@ include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[]
   * [[VUID-vkGetMemoryFdPropertiesKHR-handleType-00674]]
     pname:handleType must: not be
     ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD_BIT
+ifdef::VK_MESA_legacy_dma_buf_drm_format_modifier_query[]
+  * If the pname:pNext chain of sname:VkMemoryFdPropertiesKHR includes a
+    stype:VkMemoryFdLegacyDmaBufDrmFormatModifierPropertiesMESA,
+    pname:handleType must: be
+    ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_DMA_BUF_BIT_EXT.
+endif::VK_MESA_legacy_dma_buf_drm_format_modifier_query[]
 ****
 
 include::{generated}/validity/protos/vkGetMemoryFdPropertiesKHR.adoc[]
@@ -2498,6 +2504,33 @@ include::{generated}/validity/structs/VkMemoryFdPropertiesKHR.adoc[]
 endif::VK_KHR_external_memory_fd[]
 
 
+ifdef::VK_MESA_legacy_dma_buf_drm_format_modifier_query[]
+[open,refpage='VkMemoryFdLegacyDmaBufDrmFormatModifierPropertiesMESA',desc='DRM format modifier properties of a legacy Linux dma-buf',type='structs']
+--
+The sname:VkMemoryFdLegacyDmaBufDrmFormatModifierPropertiesMESA structure returned is defined as:
+
+include::{generated}/api/structs/VkMemoryFdLegacyDmaBufDrmFormatModifierPropertiesMESA.adoc[]
+
+  * pname:sType is a elink:VkStructureType value identifying this structure.
+  * pname:pNext is `NULL` or a pointer to a structure extending this
+    structure.
+  * pname:drmFormatModifier is the DRM format modifier associated with
+    legacy Linux dma-buf.
+
+The implementation must: return a valid format modifier in
+pname:drmFormatModifier or etext:DRM_FORMAT_MOD_INVALID to indicate that
+the implementation cannot determine an implicit modifier.
+However, due to the long history of Linux dma-buf, no guarantees can be
+made that modifier returned by this query accurately describes the image
+layout of the data in the dma-buf.
+This query should only ever be used if the client has a priori knowledge
+that the given dma-buf was allocated using legacy window system paths.
+
+include::{generated}/validity/structs/VkMemoryFdLegacyDmaBufDrmFormatModifierPropertiesMESA.adoc[]
+--
+endif::VK_MESA_legacy_dma_buf_drm_format_modifier_query[]
+
+
 ifdef::VK_EXT_external_memory_host[]
 === Host External Memory
 

config/CI/codespell-allowed

@@ -26,6 +26,7 @@ calle
 ser
 labour
 morrisette
+zink
 # proposals/ words
 pares
 # vk.xml words

proposals/VK_MESA_legacy_dma_buf_drm_format_modifier_query.adoc

@@ -0,0 +1,82 @@
+// Copyright 2022-2025 The Khronos Group Inc.
+// SPDX-License-Identifier: CC-BY-4.0
+
+# VK_MESA_legacy_dma_buf_drm_format_modifier_query
+:toc: left
+:docs: https://docs.vulkan.org/spec/latest/
+:extensions: {docs}appendices/extensions.html#
+:sectnums:
+
+This document proposes adding support for querying the implicit DRM format
+modifier from a legacy dma-buf.
+
+## Problem Statement
+
+Buffer sharing within the Linux graphics stack has a long history.
+Before we had DRM format modifiers, individual DRM drivers often had ways
+of attaching a small amount of tiling information to a dma-buf.
+Selecting an image tiling was done by convention and the tiling information
+was passed side-band in a vendor-specific way, assuming all drivers in the
+system would know what to do with it.
+This method of handling tiled images was severely limiting and has since
+been replaced by DRM format modifiers which allows for explicit
+communication of tiling information and negotiation of image tiling between
+components.
+
+Unfortunately, some legacy components such as the X server still use
+implicit image tiling.
+This extension provides a way to import these legacy dma-buf images into
+Vulkan.
+For example, this allows Zink (an OpenGL implementation on top of Vulkan)
+to properly implement `glXBindTexImageEXT()`, even if the image comes from
+an OpenGL driver which assumes the legacy tiling conventions.
+
+## Proposal
+
+### Dependencies
+
+ - VK_KHR_external_memory_fd
+
+### API Features
+
+The following features are exposed by this extension:
+
+[source,c]
+----
+typedef struct VkPhysicalDeviceLegacyDmaBufDrmFormatModifierQueryFeaturesEXT {
+    VkStructureType    sType;
+    void*              pNext;
+    VkBool32           legacyDmaBufDrmFormatModifierQuery;
+} VkPhysicalDeviceLegacyDmaBufDrmFormatModifierQueryFeaturesEXT;
+----
+
+ . `legacyDmaBufDrmFormatModifierQuery` indicates support for querying
+   DRM format modifiers from legacy dma-bufs.
+
+The DRM format modifier associated with a legacy dma-buf may be queried by
+adding a `VkMemoryFdLegacyDmaBufDrmFormatModifierPropertiesMESA` struct to
+the `pNext` chain of `VkMemoryFdPropertiesKHR`.
+
+----
+typedef struct VkMemoryFdLegacyDmaBufDrmFormatModifierPropertiesMESA {
+    VkStructureType    sType;
+    void*              pNext;
+    uint64_t           drmFormatModifier;
+} VkMemoryFdLegacyDmaBufDrmFormatModifierPropertiesMESA;
+----
+
+The returned modifier may then be passed into `vkCreateImage()` via
+`VkImageDrmFormatModifierExplicitCreateInfoEXT` and used to create a
+`VkImage` which is bound to the dma-buf at offset 0.
+
+Unfortunately, due to the history of dma-buf, there is no way to tell the
+difference between a dma-buf which has been created using the modifiers
+protocol and a legacy dma-buf.
+This query may return the wrong modifier in that case.
+The legacy dma-buf format modifier query should only ever be used in the
+case where the client knows that the dma-buf image has been created via
+legacy paths and not modifiers.
+
+## Issues
+
+None.

xml/vk.xml

@@ -10175,6 +10175,16 @@ typedef void* <name>MTLSharedEvent_id</name>;
             <member optional="true"><type>void</type>*                           <name>pNext</name></member>
             <member><type>VkBool32</type>                                        <name>presentMetering</name></member>
         </type>
+        <type category="struct" name="VkPhysicalDeviceLegacyDmaBufDrmFormatModifierQueryFeaturesMESA" structextends="VkPhysicalDeviceFeatures2,VkDeviceCreateInfo">
+            <member values="VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LEGACY_DMA_BUF_DRM_FORMAT_MODIFIER_QUERY_FEATURES_MESA"><type>VkStructureType</type> <name>sType</name></member>
+            <member optional="true"><type>void</type>*                           <name>pNext</name></member>
+            <member><type>VkBool32</type>                                        <name>legacyDmaBufDrmFormatModifierQuery</name></member>
+        </type>
+        <type category="struct" name="VkMemoryFdLegacyDmaBufDrmFormatModifierPropertiesMESA" structextends="VkMemoryFdPropertiesKHR">
+            <member values="VK_STRUCTURE_TYPE_MEMORY_FD_LEGACY_DMA_BUF_DRM_FORMAT_MODIFIER_PROPERTIES_MESA"><type>VkStructureType</type> <name>sType</name></member>
+            <member optional="true"><type>void</type>*                           <name>pNext</name></member>
+            <member><type>uint64_t</type>                                        <name>drmFormatModifier</name></member>
+        </type>
     </types>
 
 
@@ -27132,6 +27142,17 @@ typedef void* <name>MTLSharedEvent_id</name>;
                 <enum value="&quot;VK_EXT_extension_619&quot;"              name="VK_EXT_EXTENSION_619_EXTENSION_NAME"/>
             </require>
         </extension>
+        <extension name="VK_MESA_legacy_dma_buf_drm_format_modifier_query" number="620" type="device" author="MESA" contact="Faith Ekstrand @gfxstrand" depends="VK_KHR_external_memory_fd,VK_EXT_image_drm_format_modifier" supported="vulkan">
+            <require>
+                <enum value="0"                                             name="VK_MESA_LEGACY_DMA_BUF_DRM_FORMAT_MODIFIER_QUERY_SPEC_VERSION"/>
+                <enum value="&quot;VK_MESA_legacy_dma_buf_drm_format_modifier_query&quot;" name="VK_MESA_LEGACY_DMA_BUF_DRM_FORMAT_MODIFIER_QUERY_EXTENSION_NAME"/>
+                <enum offset="0" extends="VkStructureType" name="VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LEGACY_DMA_BUF_DRM_FORMAT_MODIFIER_QUERY_FEATURES_MESA"/>
+                <enum offset="1" extends="VkStructureType" name="VK_STRUCTURE_TYPE_MEMORY_FD_LEGACY_DMA_BUF_DRM_FORMAT_MODIFIER_PROPERTIES_MESA"/>
+                <type name="VkPhysicalDeviceLegacyDmaBufDrmFormatModifierQueryFeaturesMESA" />
+                <feature name="legacyDmaBufDrmFormatModifierQuery" struct="VkPhysicalDeviceLegacyDmaBufDrmFormatModifierQueryFeaturesMESA"/>
+                <type name="VkMemoryFdLegacyDmaBufDrmFormatModifierPropertiesMESA" />
+            </require>
+        </extension>
     </extensions>
     <formats>
         <format name="VK_FORMAT_R4G4_UNORM_PACK8" class="8-bit" blockSize="1" texelsPerBlock="1" packed="8">