Skip to content

Commit 32ea34b

Browse files
gfxstrandgfxstrand
committed
Add a VK_MESA_legacy_dma_buf_drm_format_modifier_query extension
1 parent d32c4ad commit 32ea34b

6 files changed

+189
-3
lines changed

‎appendices/VK_MESA_legacy_dma_buf_drm_format_modifier_query.adoc

+30
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
// Copyright 2023-2025 The Khronos Group Inc.
2+
//
3+
// SPDX-License-Identifier: CC-BY-4.0
4+
5+
include::{generated}/meta/{refprefix}VK_MESA_legacy_dma_buf_drm_format_modifier_query.adoc[]
6+
7+
=== Other Extension Metadata
8+
9+
*Last Modified Date*::
10+
2025-03-06
11+
*Interactions and External Dependencies*::
12+
- apitext:VK_KHR_external_memory_fd
13+
*Contributors*::
14+
- Faith Ekstrand, Collabora
15+
16+
=== Description
17+
18+
This extension provides a way to query a legacy Linux dma-buf for its
19+
embedded modifier.
20+
This is needed by emulation layers which implement OpenGL on top of Vulkan
21+
and need to interact with legacy window-system components as the X server.
22+
This extension is not intended for general-purpose use and modifiers should
23+
be passed explicitly between applications or components whenever possible.
24+
25+
include::{generated}/interfaces/VK_MESA_legacy_dma_buf_drm_format_modifier_query.adoc[]
26+
27+
=== Version History
28+
29+
* Revision 0, 2025-03-06(Faith Ekstrand)
30+
** Internal revisions

‎chapters/features.adoc

+25
Original file line numberDiff line numberDiff line change
@@ -8547,6 +8547,31 @@ include::{generated}/validity/structs/VkPhysicalDevicePresentMeteringFeaturesNV.
85478547
endif::VK_NV_present_metering[]
85488548

85498549

8550+
ifdef::VK_MESA_legacy_dma_buf_drm_format_modifier_query[]
8551+
[open,refpage='VkPhysicalDeviceLegacyDmaBufDrmFormatModifierQueryFeaturesMESA',desc='Structure describing whether the legacy dma-buf DRM format modifier query feature can be supported by an implementation',type='structs']
8552+
--
8553+
The sname:VkPhysicalDeviceLegacyDmaBufDrmFormatModifierQueryFeaturesMESA structure is defined as:
8554+
8555+
include::{generated}/api/structs/VkPhysicalDeviceLegacyDmaBufDrmFormatModifierQueryFeaturesMESA.adoc[]
8556+
8557+
This structure describes the following features:
8558+
8559+
* pname:sType is a elink:VkStructureType value identifying this structure.
8560+
* pname:pNext is `NULL` or a pointer to a structure extending this
8561+
structure.
8562+
* [[features-legacyDmaBufDrmFormatModifierQuery]]
8563+
pname:legacyDmaBufDrmFormatModifierQuery indicates whether the
8564+
implementation supports querying a DRM format modifier from a legacy
8565+
dma-buf.
8566+
8567+
:refpage: VkPhysicalDeviceLegacyDmaBufDrmFormatModifierQueryFeaturesMESA
8568+
include::{chapters}/features.adoc[tag=features]
8569+
8570+
include::{generated}/validity/structs/VkPhysicalDeviceLegacyDmaBufDrmFormatModifierQueryFeaturesMESA.adoc[]
8571+
--
8572+
endif::VK_MESA_legacy_dma_buf_drm_format_modifier_query[]
8573+
8574+
85508575
[[features-requirements]]
85518576
== Feature Requirements
85528577

‎chapters/memory.adoc

+33
Original file line numberDiff line numberDiff line change
@@ -2476,6 +2476,12 @@ include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[]
24762476
* [[VUID-vkGetMemoryFdPropertiesKHR-handleType-00674]]
24772477
pname:handleType must: not be
24782478
ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD_BIT
2479+
ifdef::VK_MESA_legacy_dma_buf_drm_format_modifier_query[]
2480+
* If the pname:pNext chain of sname:VkMemoryFdPropertiesKHR includes a
2481+
stype:VkMemoryFdLegacyDmaBufDrmFormatModifierPropertiesMESA,
2482+
pname:handleType must: be
2483+
ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_DMA_BUF_BIT_EXT.
2484+
endif::VK_MESA_legacy_dma_buf_drm_format_modifier_query[]
24792485
****
24802486

24812487
include::{generated}/validity/protos/vkGetMemoryFdPropertiesKHR.adoc[]
@@ -2498,6 +2504,33 @@ include::{generated}/validity/structs/VkMemoryFdPropertiesKHR.adoc[]
24982504
endif::VK_KHR_external_memory_fd[]
24992505

25002506

2507+
ifdef::VK_MESA_legacy_dma_buf_drm_format_modifier_query[]
2508+
[open,refpage='VkMemoryFdLegacyDmaBufDrmFormatModifierPropertiesMESA',desc='DRM format modifier properties of a legacy Linux dma-buf',type='structs']
2509+
--
2510+
The sname:VkMemoryFdLegacyDmaBufDrmFormatModifierPropertiesMESA structure returned is defined as:
2511+
2512+
include::{generated}/api/structs/VkMemoryFdLegacyDmaBufDrmFormatModifierPropertiesMESA.adoc[]
2513+
2514+
* pname:sType is a elink:VkStructureType value identifying this structure.
2515+
* pname:pNext is `NULL` or a pointer to a structure extending this
2516+
structure.
2517+
* pname:drmFormatModifier is the DRM format modifier associated with
2518+
legacy Linux dma-buf.
2519+
2520+
The implementation must: return a valid format modifier in
2521+
pname:drmFormatModifier or etext:DRM_FORMAT_MOD_INVALID to indicate that
2522+
the implementation cannot determine an implicit modifier.
2523+
However, due to the long history of Linux dma-buf, no guarantees can be
2524+
made that modifier returned by this query accurately describes the image
2525+
layout of the data in the dma-buf.
2526+
This query should only ever be used if the client has a priori knowledge
2527+
that the given dma-buf was allocated using legacy window system paths.
2528+
2529+
include::{generated}/validity/structs/VkMemoryFdLegacyDmaBufDrmFormatModifierPropertiesMESA.adoc[]
2530+
--
2531+
endif::VK_MESA_legacy_dma_buf_drm_format_modifier_query[]
2532+
2533+
25012534
ifdef::VK_EXT_external_memory_host[]
25022535
=== Host External Memory
25032536

‎config/CI/codespell-allowed

+1
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ calle
2626
ser
2727
labour
2828
morrisette
29+
zink
2930
# proposals/ words
3031
pares
3132
# vk.xml words

‎proposals/VK_MESA_legacy_dma_buf_drm_format_modifier_query.adoc

+82
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
// Copyright 2022-2025 The Khronos Group Inc.
2+
// SPDX-License-Identifier: CC-BY-4.0
3+
4+
# VK_MESA_legacy_dma_buf_drm_format_modifier_query
5+
:toc: left
6+
:docs: https://docs.vulkan.org/spec/latest/
7+
:extensions: {docs}appendices/extensions.html#
8+
:sectnums:
9+
10+
This document proposes adding support for querying the implicit DRM format
11+
modifier from a legacy dma-buf.
12+
13+
## Problem Statement
14+
15+
Buffer sharing within the Linux graphics stack has a long history.
16+
Before we had DRM format modifiers, individual DRM drivers often had ways
17+
of attaching a small amount of tiling information to a dma-buf.
18+
Selecting an image tiling was done by convention and the tiling information
19+
was passed side-band in a vendor-specific way, assuming all drivers in the
20+
system would know what to do with it.
21+
This method of handling tiled images was severely limiting and has since
22+
been replaced by DRM format modifiers which allows for explicit
23+
communication of tiling information and negotiation of image tiling between
24+
components.
25+
26+
Unfortunately, some legacy components such as the X server still use
27+
implicit image tiling.
28+
This extension provides a way to import these legacy dma-buf images into
29+
Vulkan.
30+
For example, this allows Zink (an OpenGL implementation on top of Vulkan)
31+
to properly implement `glXBindTexImageEXT()`, even if the image comes from
32+
an OpenGL driver which assumes the legacy tiling conventions.
33+
34+
## Proposal
35+
36+
### Dependencies
37+
38+
- VK_KHR_external_memory_fd
39+
40+
### API Features
41+
42+
The following features are exposed by this extension:
43+
44+
[source,c]
45+
----
46+
typedef struct VkPhysicalDeviceLegacyDmaBufDrmFormatModifierQueryFeaturesEXT {
47+
VkStructureType sType;
48+
void* pNext;
49+
VkBool32 legacyDmaBufDrmFormatModifierQuery;
50+
} VkPhysicalDeviceLegacyDmaBufDrmFormatModifierQueryFeaturesEXT;
51+
----
52+
53+
. `legacyDmaBufDrmFormatModifierQuery` indicates support for querying
54+
DRM format modifiers from legacy dma-bufs.
55+
56+
The DRM format modifier associated with a legacy dma-buf may be queried by
57+
adding a `VkMemoryFdLegacyDmaBufDrmFormatModifierPropertiesMESA` struct to
58+
the `pNext` chain of `VkMemoryFdPropertiesKHR`.
59+
60+
----
61+
typedef struct VkMemoryFdLegacyDmaBufDrmFormatModifierPropertiesMESA {
62+
VkStructureType sType;
63+
void* pNext;
64+
uint64_t drmFormatModifier;
65+
} VkMemoryFdLegacyDmaBufDrmFormatModifierPropertiesMESA;
66+
----
67+
68+
The returned modifier may then be passed into `vkCreateImage()` via
69+
`VkImageDrmFormatModifierExplicitCreateInfoEXT` and used to create a
70+
`VkImage` which is bound to the dma-buf at offset 0.
71+
72+
Unfortunately, due to the history of dma-buf, there is no way to tell the
73+
difference between a dma-buf which has been created using the modifiers
74+
protocol and a legacy dma-buf.
75+
This query may return the wrong modifier in that case.
76+
The legacy dma-buf format modifier query should only ever be used in the
77+
case where the client knows that the dma-buf image has been created via
78+
legacy paths and not modifiers.
79+
80+
## Issues
81+
82+
None.

‎xml/vk.xml

+18-3
Original file line numberDiff line numberDiff line change
@@ -10175,6 +10175,16 @@ typedef void* <name>MTLSharedEvent_id</name>;
1017510175
<member optional="true"><type>void</type>* <name>pNext</name></member>
1017610176
<member><type>VkBool32</type> <name>presentMetering</name></member>
1017710177
</type>
10178+
<type category="struct" name="VkPhysicalDeviceLegacyDmaBufDrmFormatModifierQueryFeaturesMESA" structextends="VkPhysicalDeviceFeatures2,VkDeviceCreateInfo">
10179+
<member values="VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LEGACY_DMA_BUF_DRM_FORMAT_MODIFIER_QUERY_FEATURES_MESA"><type>VkStructureType</type> <name>sType</name></member>
10180+
<member optional="true"><type>void</type>* <name>pNext</name></member>
10181+
<member><type>VkBool32</type> <name>legacyDmaBufDrmFormatModifierQuery</name></member>
10182+
</type>
10183+
<type category="struct" name="VkMemoryFdLegacyDmaBufDrmFormatModifierPropertiesMESA" structextends="VkMemoryFdPropertiesKHR">
10184+
<member values="VK_STRUCTURE_TYPE_MEMORY_FD_LEGACY_DMA_BUF_DRM_FORMAT_MODIFIER_PROPERTIES_MESA"><type>VkStructureType</type> <name>sType</name></member>
10185+
<member optional="true"><type>void</type>* <name>pNext</name></member>
10186+
<member><type>uint64_t</type> <name>drmFormatModifier</name></member>
10187+
</type>
1017810188
</types>
1017910189

1018010190

@@ -27132,10 +27142,15 @@ typedef void* <name>MTLSharedEvent_id</name>;
2713227142
<enum value="&quot;VK_EXT_extension_619&quot;" name="VK_EXT_EXTENSION_619_EXTENSION_NAME"/>
2713327143
</require>
2713427144
</extension>
27135-
<extension name="VK_EXT_extension_620" number="620" author="EXT" contact="Faith Ekstrand @gfxstrand" supported="disabled">
27145+
<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">
2713627146
<require>
27137-
<enum value="0" name="VK_EXT_EXTENSION_620_SPEC_VERSION"/>
27138-
<enum value="&quot;VK_EXT_extension_620&quot;" name="VK_EXT_EXTENSION_620_EXTENSION_NAME"/>
27147+
<enum value="0" name="VK_MESA_LEGACY_DMA_BUF_DRM_FORMAT_MODIFIER_QUERY_SPEC_VERSION"/>
27148+
<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"/>
27149+
<enum offset="0" extends="VkStructureType" name="VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LEGACY_DMA_BUF_DRM_FORMAT_MODIFIER_QUERY_FEATURES_MESA"/>
27150+
<enum offset="1" extends="VkStructureType" name="VK_STRUCTURE_TYPE_MEMORY_FD_LEGACY_DMA_BUF_DRM_FORMAT_MODIFIER_PROPERTIES_MESA"/>
27151+
<type name="VkPhysicalDeviceLegacyDmaBufDrmFormatModifierQueryFeaturesMESA" />
27152+
<feature name="legacyDmaBufDrmFormatModifierQuery" struct="VkPhysicalDeviceLegacyDmaBufDrmFormatModifierQueryFeaturesMESA"/>
27153+
<type name="VkMemoryFdLegacyDmaBufDrmFormatModifierPropertiesMESA" />
2713927154
</require>
2714027155
</extension>
2714127156
</extensions>

0 commit comments

Comments
 (0)