Class EXTImageDrmFormatModifier
Its functionality closely overlaps with EGL_EXT_image_dma_buf_import_modifiers
2 and EGL_MESA_image_dma_buf_export
3. Unlike the EGL extensions, this extension does not require the use of a specific handle type (such as a dma_buf) for external memory and provides more explicit control of image creation.
Introduction to DRM Format Modifiers
A DRM format modifier is a 64-bit, vendor-prefixed, semi-opaque unsigned integer. Most modifiers represent a concrete, vendor-specific tiling format for images. Some exceptions are DRM_FORMAT_MOD_LINEAR
(which is not vendor-specific); DRM_FORMAT_MOD_NONE
(which is an alias of DRM_FORMAT_MOD_LINEAR
due to historical accident); and DRM_FORMAT_MOD_INVALID
(which does not represent a tiling format). The modifier’s vendor prefix consists of the 8 most significant bits. The canonical list of modifiers and vendor prefixes is found in drm_fourcc.h
in the Linux kernel source. The other dominant source of modifiers are vendor kernel trees.
One goal of modifiers in the Linux ecosystem is to enumerate for each vendor a reasonably sized set of tiling formats that are appropriate for images shared across processes, APIs, and/or devices, where each participating component may possibly be from different vendors. A non-goal is to enumerate all tiling formats supported by all vendors. Some tiling formats used internally by vendors are inappropriate for sharing; no modifiers should be assigned to such tiling formats.
Modifier values typically do not describe memory layouts. More precisely, a modifier's lower 56 bits usually have no structure. Instead, modifiers name memory layouts; they name a small set of vendor-preferred layouts for image sharing. As a consequence, in each vendor namespace the modifier values are often sequentially allocated starting at 1.
Each modifier is usually supported by a single vendor and its name matches the pattern {VENDOR}_FORMAT_MOD_*
or DRM_FORMAT_MOD_{VENDOR}_*
. Examples are I915_FORMAT_MOD_X_TILED
and DRM_FORMAT_MOD_BROADCOM_VC4_T_TILED
. An exception is DRM_FORMAT_MOD_LINEAR
, which is supported by most vendors.
Many APIs in Linux use modifiers to negotiate and specify the memory layout of shared images. For example, a Wayland compositor and Wayland client may, by relaying modifiers over the Wayland protocol zwp_linux_dmabuf_v1
, negotiate a vendor-specific tiling format for a shared wl_buffer
. The client may allocate the underlying memory for the wl_buffer
with GBM, providing the chosen modifier to gbm_bo_create_with_modifiers
. The client may then import the wl_buffer
into Vulkan for producing image content, providing the resource’s dma_buf to VkImportMemoryFdInfoKHR
and its modifier to VkImageDrmFormatModifierExplicitCreateInfoEXT
. The compositor may then import the wl_buffer
into OpenGL for sampling, providing the resource’s dma_buf and modifier to eglCreateImage
. The compositor may also bypass OpenGL and submit the wl_buffer
directly to the kernel’s display API, providing the dma_buf and modifier through drm_mode_fb_cmd2
.
Format Translation
Modifier-capable APIs often pair modifiers with DRM formats, which are defined in drm_fourcc.h
. However, VK_EXT_image_drm_format_modifier
uses VkFormat
instead of DRM formats. The application must convert between VkFormat
and DRM format when it sends or receives a DRM format to or from an external API.
The mapping from VkFormat
to DRM format is lossy. Therefore, when receiving a DRM format from an external API, often the application must use information from the external API to accurately map the DRM format to a VkFormat
. For example, DRM formats do not distinguish between RGB and sRGB (as of 2018-03-28); external information is required to identify the image’s color space.
The mapping between VkFormat
and DRM format is also incomplete. For some DRM formats there exist no corresponding Vulkan format, and for some Vulkan formats there exist no corresponding DRM format.
Usage Patterns
Three primary usage patterns are intended for this extension:
- Negotiation. The application negotiates with modifier-aware, external components to determine sets of image creation parameters supported among all components.
In the Linux ecosystem, the negotiation usually assumes the image is a 2D, single-sampled, non-mipmapped, non-array image; this extension permits that assumption but does not require it. The result of the negotiation usually resembles a set of tuples such as (drmFormat, drmFormatModifier), where each participating component supports all tuples in the set.
Many details of this negotiation - such as the protocol used during negotiation, the set of image creation parameters expressible in the protocol, and how the protocol chooses which process and which API will create the image - are outside the scope of this specification.
In this extension,
GetPhysicalDeviceFormatProperties2
withVkDrmFormatModifierPropertiesListEXT
serves a primary role during the negotiation, andGetPhysicalDeviceImageFormatProperties2
withVkPhysicalDeviceImageDrmFormatModifierInfoEXT
serves a secondary role. - Import. The application imports an image with a modifier.
In this pattern, the application receives from an external source the image’s memory and its creation parameters, which are often the result of the negotiation described above. Some image creation parameters are implicitly defined by the external source; for example,
IMAGE_TYPE_2D
is often assumed. Some image creation parameters are usually explicit, such as the image’sformat
,drmFormatModifier
, andextent
; and each plane’soffset
androwPitch
.Before creating the image, the application first verifies that the physical device supports the received creation parameters by querying
GetPhysicalDeviceFormatProperties2
withVkDrmFormatModifierPropertiesListEXT
andGetPhysicalDeviceImageFormatProperties2
withVkPhysicalDeviceImageDrmFormatModifierInfoEXT
. Then the application creates the image by chainingVkImageDrmFormatModifierExplicitCreateInfoEXT
andVkExternalMemoryImageCreateInfo
ontoVkImageCreateInfo
. - Export. The application creates an image and allocates its memory. Then the application exports to modifier-aware consumers the image’s memory handles; its creation parameters; its modifier; and the
offset
,size
, androwPitch
of each memory plane. In this pattern, the Vulkan device is the authority for the image; it is the allocator of the image’s memory and the decider of the image’s creation parameters. When choosing the image’s creation parameters, the application usually chooses a tuple (format, drmFormatModifier) from the result of the negotiation described above. The negotiation’s result often contains multiple tuples that share the same format but differ in their modifier. In this case, the application should defer the choice of the image’s modifier to the Vulkan implementation by providing all such modifiers toVkImageDrmFormatModifierListCreateInfoEXT
::pDrmFormatModifiers
; and the implementation should choose frompDrmFormatModifiers
the optimal modifier in consideration with the other image parameters.The application creates the image by chaining
VkImageDrmFormatModifierListCreateInfoEXT
andVkExternalMemoryImageCreateInfo
ontoVkImageCreateInfo
. The protocol and APIs by which the application will share the image with external consumers will likely determine the value ofVkExternalMemoryImageCreateInfo
::handleTypes
. The implementation chooses for the image an optimal modifier fromVkImageDrmFormatModifierListCreateInfoEXT
::pDrmFormatModifiers
. The application then queries the implementation-chosen modifier withGetImageDrmFormatModifierPropertiesEXT
, and queries the memory layout of each plane withGetImageSubresourceLayout
.The application then allocates the image’s memory with
VkMemoryAllocateInfo
, adding chained extending structures for external memory; binds it to the image; and exports the memory, for example, withGetMemoryFdKHR
.Finally, the application sends the image’s creation parameters, its modifier, its per-plane memory layout, and the exported memory handle to the external consumers. The details of how the application transmits this information to external consumers is outside the scope of this specification.
Prior Art
Extension EGL_EXT_image_dma_buf_import
1 introduced the ability to create an EGLImage
by importing for each plane a dma_buf, offset, and row pitch.
Later, extension EGL_EXT_image_dma_buf_import_modifiers
2 introduced the ability to query which combination of formats and modifiers the implementation supports and to specify modifiers during creation of the EGLImage
.
Extension EGL_MESA_image_dma_buf_export
3 is the inverse of EGL_EXT_image_dma_buf_import_modifiers
.
The Linux kernel modesetting API (KMS), when configuring the display’s framebuffer with struct drm_mode_fb_cmd2
4, allows one to specify the framebuffer’s modifier as well as a per-plane memory handle, offset, and row pitch.
GBM, a graphics buffer manager for Linux, allows creation of a gbm_bo
(that is, a graphics buffer object) by importing data similar to that in EGL_EXT_image_dma_buf_import_modifiers
1; and symmetrically allows exporting the same data from the gbm_bo
. See the references to modifier and plane in gbm.h
5.
VK_EXT_image_drm_format_modifier
- Name String
VK_EXT_image_drm_format_modifier
- Extension Type
- Device extension
- Registered Extension Number
- 159
- Revision
- 2
- Extension and Version Dependencies
VK_KHR_bind_memory2
andVK_KHR_get_physical_device_properties2
andVK_KHR_sampler_ycbcr_conversion
or Version 1.1 andVK_KHR_image_format_list
or Version 1.2- Contact
- Lina Versace versalinyaa
Other Extension Metadata
- Last Modified Date
- 2021-09-30
- IP Status
- No known IP claims.
- Contributors
- Antoine Labour, Google
- Bas Nieuwenhuizen, Google
- Lina Versace, Google
- James Jones, NVIDIA
- Faith Ekstrand, Intel
- Jőrg Wagner, ARM
- Kristian Høgsberg Kristensen, Google
- Ray Smith, ARM
-
Field Summary
Modifier and TypeFieldDescriptionstatic final int
ExtendsVkResult
.static final String
The extension name.static final int
The extension specification version.static final int
ExtendsVkImageAspectFlagBits
.static final int
ExtendsVkImageAspectFlagBits
.static final int
ExtendsVkImageAspectFlagBits
.static final int
ExtendsVkImageAspectFlagBits
.static final int
ExtendsVkImageTiling
.static final int
ExtendsVkStructureType
.static final int
ExtendsVkStructureType
.static final int
ExtendsVkStructureType
.static final int
ExtendsVkStructureType
.static final int
ExtendsVkStructureType
.static final int
ExtendsVkStructureType
. -
Method Summary
Modifier and TypeMethodDescriptionstatic int
nvkGetImageDrmFormatModifierPropertiesEXT
(VkDevice device, long image, long pProperties) Unsafe version of:GetImageDrmFormatModifierPropertiesEXT
static int
vkGetImageDrmFormatModifierPropertiesEXT
(VkDevice device, long image, VkImageDrmFormatModifierPropertiesEXT pProperties) Returns an image’s DRM format modifier.
-
Field Details
-
VK_EXT_IMAGE_DRM_FORMAT_MODIFIER_SPEC_VERSION
public static final int VK_EXT_IMAGE_DRM_FORMAT_MODIFIER_SPEC_VERSIONThe extension specification version.- See Also:
-
VK_EXT_IMAGE_DRM_FORMAT_MODIFIER_EXTENSION_NAME
The extension name.- See Also:
-
VK_ERROR_INVALID_DRM_FORMAT_MODIFIER_PLANE_LAYOUT_EXT
public static final int VK_ERROR_INVALID_DRM_FORMAT_MODIFIER_PLANE_LAYOUT_EXTExtendsVkResult
.- See Also:
-
VK_STRUCTURE_TYPE_DRM_FORMAT_MODIFIER_PROPERTIES_LIST_EXT
public static final int VK_STRUCTURE_TYPE_DRM_FORMAT_MODIFIER_PROPERTIES_LIST_EXTExtendsVkStructureType
.Enum values:
STRUCTURE_TYPE_DRM_FORMAT_MODIFIER_PROPERTIES_LIST_EXT
STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_DRM_FORMAT_MODIFIER_INFO_EXT
STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_LIST_CREATE_INFO_EXT
STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_EXPLICIT_CREATE_INFO_EXT
STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_PROPERTIES_EXT
- See Also:
-
VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_DRM_FORMAT_MODIFIER_INFO_EXT
public static final int VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_DRM_FORMAT_MODIFIER_INFO_EXTExtendsVkStructureType
.Enum values:
STRUCTURE_TYPE_DRM_FORMAT_MODIFIER_PROPERTIES_LIST_EXT
STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_DRM_FORMAT_MODIFIER_INFO_EXT
STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_LIST_CREATE_INFO_EXT
STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_EXPLICIT_CREATE_INFO_EXT
STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_PROPERTIES_EXT
- See Also:
-
VK_STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_LIST_CREATE_INFO_EXT
public static final int VK_STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_LIST_CREATE_INFO_EXTExtendsVkStructureType
.Enum values:
STRUCTURE_TYPE_DRM_FORMAT_MODIFIER_PROPERTIES_LIST_EXT
STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_DRM_FORMAT_MODIFIER_INFO_EXT
STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_LIST_CREATE_INFO_EXT
STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_EXPLICIT_CREATE_INFO_EXT
STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_PROPERTIES_EXT
- See Also:
-
VK_STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_EXPLICIT_CREATE_INFO_EXT
public static final int VK_STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_EXPLICIT_CREATE_INFO_EXTExtendsVkStructureType
.Enum values:
STRUCTURE_TYPE_DRM_FORMAT_MODIFIER_PROPERTIES_LIST_EXT
STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_DRM_FORMAT_MODIFIER_INFO_EXT
STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_LIST_CREATE_INFO_EXT
STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_EXPLICIT_CREATE_INFO_EXT
STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_PROPERTIES_EXT
- See Also:
-
VK_STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_PROPERTIES_EXT
public static final int VK_STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_PROPERTIES_EXTExtendsVkStructureType
.Enum values:
STRUCTURE_TYPE_DRM_FORMAT_MODIFIER_PROPERTIES_LIST_EXT
STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_DRM_FORMAT_MODIFIER_INFO_EXT
STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_LIST_CREATE_INFO_EXT
STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_EXPLICIT_CREATE_INFO_EXT
STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_PROPERTIES_EXT
- See Also:
-
VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT
public static final int VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXTExtendsVkImageTiling
.- See Also:
-
VK_IMAGE_ASPECT_MEMORY_PLANE_0_BIT_EXT
public static final int VK_IMAGE_ASPECT_MEMORY_PLANE_0_BIT_EXTExtendsVkImageAspectFlagBits
.Enum values:
- See Also:
-
VK_IMAGE_ASPECT_MEMORY_PLANE_1_BIT_EXT
public static final int VK_IMAGE_ASPECT_MEMORY_PLANE_1_BIT_EXTExtendsVkImageAspectFlagBits
.Enum values:
- See Also:
-
VK_IMAGE_ASPECT_MEMORY_PLANE_2_BIT_EXT
public static final int VK_IMAGE_ASPECT_MEMORY_PLANE_2_BIT_EXTExtendsVkImageAspectFlagBits
.Enum values:
- See Also:
-
VK_IMAGE_ASPECT_MEMORY_PLANE_3_BIT_EXT
public static final int VK_IMAGE_ASPECT_MEMORY_PLANE_3_BIT_EXTExtendsVkImageAspectFlagBits
.Enum values:
- See Also:
-
VK_STRUCTURE_TYPE_DRM_FORMAT_MODIFIER_PROPERTIES_LIST_2_EXT
public static final int VK_STRUCTURE_TYPE_DRM_FORMAT_MODIFIER_PROPERTIES_LIST_2_EXTExtendsVkStructureType
.- See Also:
-
-
Method Details
-
nvkGetImageDrmFormatModifierPropertiesEXT
public static int nvkGetImageDrmFormatModifierPropertiesEXT(VkDevice device, long image, long pProperties) Unsafe version of:GetImageDrmFormatModifierPropertiesEXT
-
vkGetImageDrmFormatModifierPropertiesEXT
public static int vkGetImageDrmFormatModifierPropertiesEXT(VkDevice device, long image, VkImageDrmFormatModifierPropertiesEXT pProperties) Returns an image’s DRM format modifier.C Specification
If an image was created with
IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT
, then the image has a Linux DRM format modifier. To query the modifier, call:VkResult vkGetImageDrmFormatModifierPropertiesEXT( VkDevice device, VkImage image, VkImageDrmFormatModifierPropertiesEXT* pProperties);
Valid Usage
image
must have been created withtiling
equal toIMAGE_TILING_DRM_FORMAT_MODIFIER_EXT
Valid Usage (Implicit)
device
must be a validVkDevice
handleimage
must be a validVkImage
handlepProperties
must be a valid pointer to aVkImageDrmFormatModifierPropertiesEXT
structureimage
must have been created, allocated, or retrieved fromdevice
Return Codes
- On success, this command returns
- On failure, this command returns
See Also
- Parameters:
device
- the logical device that owns the image.image
- the queried image.pProperties
- a pointer to aVkImageDrmFormatModifierPropertiesEXT
structure in which properties of the image’s DRM format modifier are returned.
-