public class EXTImageDrmFormatModifier
extends java.lang.Object
This extension provides the ability to use DRM format modifiers with images, enabling Vulkan to better integrate with the Linux ecosystem of graphics, video, and display APIs.
Its functionality closely overlaps with EGL_EXT_image_dma_buf_import_modifiers2 and EGL_MESA_image_dma_buf_export3. 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.
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.
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 colorspace.
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.
Three primary usage patterns are intended for this extension:
Many details of this negotiation—such as the protocol used during negotiation, the set of image creation parameters expressable 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 with VkDrmFormatModifierPropertiesListEXT serves a primary role during the negotiation, and GetPhysicalDeviceImageFormatProperties2 with VkPhysicalDeviceImageDrmFormatModifierInfoEXT serves a secondary role.
IMAGE_TYPE_2D is often assumed. Some image creation parameters are usually explicit, such as the image's format, drmFormatModifier, and extent; and each plane's offset and rowPitch.
Before creating the image, the application first verifies that the physical device supports the received creation parameters by querying GetPhysicalDeviceFormatProperties2 with VkDrmFormatModifierPropertiesListEXT and GetPhysicalDeviceImageFormatProperties2 with VkPhysicalDeviceImageDrmFormatModifierInfoEXT. Then the application creates the image by chaining VkImageDrmFormatModifierExplicitCreateInfoEXT and VkExternalMemoryImageCreateInfo onto VkImageCreateInfo.
offset, size, and rowPitch 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 to VkImageDrmFormatModifierListCreateInfoEXT::pDrmFormatModifiers; and the implementation should choose from pDrmFormatModifiers the optimal modifier in consideration with the other image parameters.
The application creates the image by chaining VkImageDrmFormatModifierListCreateInfoEXT and VkExternalMemoryImageCreateInfo onto VkImageCreateInfo. The protocol and APIs by which the application will share the image with external consumers will likely determine the value of VkExternalMemoryImageCreateInfo::handleTypes. The implementation chooses for the image an optimal modifier from VkImageDrmFormatModifierListCreateInfoEXT::pDrmFormatModifiers. The application then queries the implementation-chosen modifier with GetImageDrmFormatModifierPropertiesEXT, and queries the memory layout of each plane with GetImageSubresourceLayout.
The application then allocates the image's memory with VkMemoryAllocateInfo, adding chained extension structures for external memory; binds it to the image; and exports the memory, for example, with GetMemoryFdKHR.
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.
Extension EGL_EXT_image_dma_buf_import1 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_modifiers2 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_export3 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_cmd24, allows one to specify the frambuffer'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_modifiers1; and symmetrically allows exporting the same data from the gbm_bo. See the references to modifier and plane in gbm.h5.
VK_EXT_image_drm_format_modifierVK_KHR_bind_memory2VK_KHR_get_physical_device_properties2VK_KHR_image_format_listVK_KHR_sampler_ycbcr_conversion| Modifier and Type | Method and Description |
|---|---|
static int |
nvkGetImageDrmFormatModifierPropertiesEXT(org.lwjgl.vulkan.VkDevice device,
long image,
long pProperties)
Unsafe version of:
GetImageDrmFormatModifierPropertiesEXT |
static int |
vkGetImageDrmFormatModifierPropertiesEXT(org.lwjgl.vulkan.VkDevice device,
long image,
VkImageDrmFormatModifierPropertiesEXT pProperties)
Returns an image's DRM format modifier.
|
public static final int VK_EXT_IMAGE_DRM_FORMAT_MODIFIER_SPEC_VERSION
public static final java.lang.String VK_EXT_IMAGE_DRM_FORMAT_MODIFIER_EXTENSION_NAME
public static final int VK_ERROR_INVALID_DRM_FORMAT_MODIFIER_PLANE_LAYOUT_EXT
VkResult.public static final int VK_STRUCTURE_TYPE_DRM_FORMAT_MODIFIER_PROPERTIES_LIST_EXT
VkStructureType.
STRUCTURE_TYPE_DRM_FORMAT_MODIFIER_PROPERTIES_LIST_EXTSTRUCTURE_TYPE_DRM_FORMAT_MODIFIER_PROPERTIES_EXTSTRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_DRM_FORMAT_MODIFIER_INFO_EXTSTRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_LIST_CREATE_INFO_EXTSTRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_EXPLICIT_CREATE_INFO_EXTSTRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_PROPERTIES_EXTpublic static final int VK_STRUCTURE_TYPE_DRM_FORMAT_MODIFIER_PROPERTIES_EXT
VkStructureType.
STRUCTURE_TYPE_DRM_FORMAT_MODIFIER_PROPERTIES_LIST_EXTSTRUCTURE_TYPE_DRM_FORMAT_MODIFIER_PROPERTIES_EXTSTRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_DRM_FORMAT_MODIFIER_INFO_EXTSTRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_LIST_CREATE_INFO_EXTSTRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_EXPLICIT_CREATE_INFO_EXTSTRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_PROPERTIES_EXTpublic static final int VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_DRM_FORMAT_MODIFIER_INFO_EXT
VkStructureType.
STRUCTURE_TYPE_DRM_FORMAT_MODIFIER_PROPERTIES_LIST_EXTSTRUCTURE_TYPE_DRM_FORMAT_MODIFIER_PROPERTIES_EXTSTRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_DRM_FORMAT_MODIFIER_INFO_EXTSTRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_LIST_CREATE_INFO_EXTSTRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_EXPLICIT_CREATE_INFO_EXTSTRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_PROPERTIES_EXTpublic static final int VK_STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_LIST_CREATE_INFO_EXT
VkStructureType.
STRUCTURE_TYPE_DRM_FORMAT_MODIFIER_PROPERTIES_LIST_EXTSTRUCTURE_TYPE_DRM_FORMAT_MODIFIER_PROPERTIES_EXTSTRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_DRM_FORMAT_MODIFIER_INFO_EXTSTRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_LIST_CREATE_INFO_EXTSTRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_EXPLICIT_CREATE_INFO_EXTSTRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_PROPERTIES_EXTpublic static final int VK_STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_EXPLICIT_CREATE_INFO_EXT
VkStructureType.
STRUCTURE_TYPE_DRM_FORMAT_MODIFIER_PROPERTIES_LIST_EXTSTRUCTURE_TYPE_DRM_FORMAT_MODIFIER_PROPERTIES_EXTSTRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_DRM_FORMAT_MODIFIER_INFO_EXTSTRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_LIST_CREATE_INFO_EXTSTRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_EXPLICIT_CREATE_INFO_EXTSTRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_PROPERTIES_EXTpublic static final int VK_STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_PROPERTIES_EXT
VkStructureType.
STRUCTURE_TYPE_DRM_FORMAT_MODIFIER_PROPERTIES_LIST_EXTSTRUCTURE_TYPE_DRM_FORMAT_MODIFIER_PROPERTIES_EXTSTRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_DRM_FORMAT_MODIFIER_INFO_EXTSTRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_LIST_CREATE_INFO_EXTSTRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_EXPLICIT_CREATE_INFO_EXTSTRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_PROPERTIES_EXTpublic static final int VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT
VkImageTiling.public static final int VK_IMAGE_ASPECT_MEMORY_PLANE_0_BIT_EXT
VkImageAspectFlagBits.
public static final int VK_IMAGE_ASPECT_MEMORY_PLANE_1_BIT_EXT
VkImageAspectFlagBits.
public static final int VK_IMAGE_ASPECT_MEMORY_PLANE_2_BIT_EXT
VkImageAspectFlagBits.
public static final int VK_IMAGE_ASPECT_MEMORY_PLANE_3_BIT_EXT
VkImageAspectFlagBits.
public static int nvkGetImageDrmFormatModifierPropertiesEXT(org.lwjgl.vulkan.VkDevice device,
long image,
long pProperties)
GetImageDrmFormatModifierPropertiesEXTpublic static int vkGetImageDrmFormatModifierPropertiesEXT(org.lwjgl.vulkan.VkDevice device,
long image,
VkImageDrmFormatModifierPropertiesEXT pProperties)
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);image must have been created with tiling equal to IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT.device must be a valid VkDevice handleimage must be a valid VkImage handlepProperties must be a valid pointer to a VkImageDrmFormatModifierPropertiesEXT structureimage must have been created, allocated, or retrieved from devicedevice - the logical device that owns the image.image - the queried image.pProperties - will return properties of the image’s DRM format modifier.Copyright LWJGL. All Rights Reserved. License terms.