diff options
author | Chad Versace <chadversary@google.com> | 2018-07-18 09:40:54 -0700 |
---|---|---|
committer | Chad Versace <chadversary@google.com> | 2018-09-28 11:03:05 +0200 |
commit | 3e150e0a1eae9fd163f26a0e0804b9bba9e4dbeb (patch) | |
tree | 02627e00558c815c77f8aa13e49f6d56cc2819f1 | |
parent | c86fc5b238d48c451a19e4fa3c3231ccc77dcc1c (diff) | |
download | vulkan-spec-1.0-VK_EXT_image_drm_format_modifier.zip vulkan-spec-1.0-VK_EXT_image_drm_format_modifier.tar.xz |
VK_EXT_image_drm_format_modifier: New extension1.0-VK_EXT_image_drm_format_modifier
Closes #961.
-rw-r--r-- | appendices/VK_EXT_image_drm_format_modifier.txt | 435 | ||||
-rw-r--r-- | appendices/glossary.txt | 42 | ||||
-rw-r--r-- | chapters/clears.txt | 4 | ||||
-rw-r--r-- | chapters/copies.txt | 4 | ||||
-rwxr-xr-x | chapters/features.txt | 226 | ||||
-rw-r--r-- | chapters/renderpass.txt | 4 | ||||
-rw-r--r-- | chapters/resources.txt | 430 | ||||
-rw-r--r-- | include/vulkan/vulkan_core.h | 68 | ||||
-rw-r--r-- | xml/vk.xml | 70 |
9 files changed, 1232 insertions, 51 deletions
diff --git a/appendices/VK_EXT_image_drm_format_modifier.txt b/appendices/VK_EXT_image_drm_format_modifier.txt new file mode 100644 index 0000000..383f2ee --- /dev/null +++ b/appendices/VK_EXT_image_drm_format_modifier.txt @@ -0,0 +1,435 @@ +// Copyright (c) 2018 Khronos Group. This work is licensed under a +// Creative Commons Attribution 4.0 International License; see +// http://creativecommons.org/licenses/by/4.0/ + +include::meta/VK_EXT_image_drm_format_modifier.txt[] + +*Last Modified Date*:: + 2018-08-29 +*IP Status*:: + No known IP claims. +*Contributors*:: + - Antoine Labour, Google + - Chad Versace, Google + - James Jones, NVIDIA + - Jason Ekstrand, Intel + - Jőrg Wagner, ARM + - Kristian Høgsberg Kristensen, Google + - Ray Smith, ARM + +=== Overview + +==== Summary + +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_modifiers`^<<VK_EXT_image_drm_format_modifier-fn2,2>>^ +and +`EGL_MESA_image_dma_buf_export`^<<VK_EXT_image_drm_format_modifier-fn3,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 etext:DRM_FORMAT_MOD_LINEAR (which is not vendor-specific); +etext:DRM_FORMAT_MOD_NONE (which is an alias of etext:DRM_FORMAT_MOD_LINEAR due +to historical accident); +and etext:DRM_FORMAT_MOD_INVALID (which does not represent a tiling format). +The _modifier's_ vendor prefix consists of the 8 most signficant bits. +The canonical list of _modifiers_ and vendor prefixes is found in +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/uapi/drm/drm_fourcc.h[`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 +etext:I915_FORMAT_MOD_X_TILED and +etext:DRM_FORMAT_MOD_BROADCOM_VC4_T_TILED. +An exception is etext: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 +stext:wl_buffer. The client may allocate the underlying memory for the +stext:wl_buffer with GBM, providing the chosen _modifier_ to +fname:gbm_bo_create_with_modifiers. The client may then import the stext:wl_buffer +into Vulkan for producing image content, providing the resource's +dma_buf to slink:VkImportMemoryFdInfo and +its _modifier_ to slink:VkImageDrmFormatModifierExplicitCreateInfoEXT. +The compositor may then import the stext:wl_buffer into OpenGL for sampling, +providing the resource's dma_buf and _modifier_ to +fname:eglCreateImage. +The compositor may also bypass OpenGL and submit the stext:wl_buffer directly +to the kernel's display API, providing the dma_buf and _modifier_ through +stext:drm_mode_fb_cmd2. + +==== Format Translation + +_Modifier_-capable APIs often pair _modifiers_ with DRM formats, +which are defined in +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/uapi/drm/drm_fourcc.h[`drm_fourcc.h`]. +However, `VK_EXT_image_drm_format_modifier` uses elink:VkFormat instead of DRM formats. +The application must convert between elink:VkFormat and DRM format +when it sends or receives a DRM format to or from an external API. + +The mapping from elink: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 elink: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 elink: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 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, flink:vkGetPhysicalDeviceFormatProperties2 with +slink:VkDrmFormatModifierPropertiesListEXT serves a primary role during the +negotiation, and flink:vkGetPhysicalDeviceImageFormatProperties2 with +slink:VkPhysicalDeviceImageDrmFormatModifierInfoEXT 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, +ename:VK_IMAGE_TYPE_2D is often assumed. Some image creation parameters are +usually explicit, such as the image's pname:format, +pname:drmFormatModifier, and pname:extent; and each plane's pname:offset +and pname:rowPitch. + +Before creating the image, the application first verifies that the physical device +supports the received creation parameters by querying +flink:vkGetPhysicalDeviceFormatProperties2 with +slink:VkDrmFormatModifierPropertiesListEXT and +flink:vkGetPhysicalDeviceImageFormatProperties2 with +slink:VkPhysicalDeviceImageDrmFormatModifierInfoEXT. Then the application creates +the image by chaining slink:VkImageDrmFormatModifierExplicitCreateInfoEXT +and slink:VkExternalMemoryImageCreateInfo onto slink:VkImageCreateInfo. +-- + + * *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 + <<VkSubresourceLayout,pname:offset>>, <<VkSubresourceLayout,pname:size>>, + and <<VkSubresourceLayout,pname: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 +slink:VkImageDrmFormatModifierListCreateInfoEXT::pname:pDrmFormatModifiers; +and the implementation should choose from pname:pDrmFormatModifiers the +optimal _modifier_ in consideration with the other image parameters. + +The application creates the image by chaining +slink:VkImageDrmFormatModifierListCreateInfoEXT and +slink:VkExternalMemoryImageCreateInfo onto slink:VkImageCreateInfo. The +protocol and APIs by which the application will share the image with external +consumers will likely determine the value of +slink:VkExternalMemoryImageCreateInfo::pname:handleTypes. The +implementation chooses for the image an optimal _modifier_ from +slink:VkImageDrmFormatModifierListCreateInfoEXT::pname:pDrmFormatModifiers. +The application then queries the implementation-chosen _modifier_ with +flink:vkGetImageDrmFormatModifierPropertiesEXT, and queries the memory +layout of each plane with flink:vkGetImageSubresourceLayout. + +The application then allocates the image's memory with slink:VkMemoryAllocateInfo, +adding chained extension structures for external memory; binds it to the +image; and exports the memory, for example, with flink:vkGetMemoryFd. + +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`^<<VK_EXT_image_drm_format_modifier-fn1,1>>^ +introduced the ability to create an stext:EGLImage by importing for each plane +a dma_buf, offset, and row pitch. + +Later, extension +`EGL_EXT_image_dma_buf_import_modifiers`^<<VK_EXT_image_drm_format_modifier-fn2,2>>^ +introduced the ability to query which combination of formats and _modifiers_ +the implementation supports and to specify _modifiers_ during creation of the +stext:EGLImage. + +Extension +`EGL_MESA_image_dma_buf_export`^<<VK_EXT_image_drm_format_modifier-fn3,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`^<<VK_EXT_image_drm_format_modifier-fn4,4>>^, 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_modifiers`^<<VK_EXT_image_drm_format_modifier-fn1,1>>^; +and symmetrically allows exporting the same data from the `gbm_bo`. See the +references to _modifier_ and _plane_ in +`gbm.h`^<<VK_EXT_image_drm_format_modifier-fn5,5>>^. + + +=== New Object Types + +None. + +=== New Enum Constants + + * Extending elink:VkResult: + ** ename:VK_ERROR_INVALID_DRM_FORMAT_MODIFIER_PLANE_LAYOUT_EXT + + * Extending elink:VkStructureType: + ** ename:VK_STRUCTURE_TYPE_DRM_FORMAT_MODIFIER_PROPERTIES_LIST_EXT + ** ename:VK_STRUCTURE_TYPE_DRM_FORMAT_MODIFIER_PROPERTIES_EXT + ** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_DRM_FORMAT_MODIFIER_INFO_EXT + ** ename:VK_STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_LIST_CREATE_INFO_EXT + ** ename:VK_STRUCTURE_TYPE_IMAGE_EXPLICIT_DRM_FORMAT_MODIFIER_CREATE_INFO_EXT + ** ename:VK_STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_PROPERTIES_EXT + + * Extending elink:VkImageTiling: + ** ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT + + * Extending elink:VkImageAspectFlagBits: + ** ename:VK_IMAGE_ASPECT_MEMORY_PLANE_0_BIT_EXT + ** ename:VK_IMAGE_ASPECT_MEMORY_PLANE_1_BIT_EXT + ** ename:VK_IMAGE_ASPECT_MEMORY_PLANE_2_BIT_EXT + ** ename:VK_IMAGE_ASPECT_MEMORY_PLANE_3_BIT_EXT + +=== New Enums + +None. + +=== New Structures + + * Extends elink:VkFormatProperties2: + ** slink:VkDrmFormatModifierPropertiesListEXT + + * Member of slink:VkDrmFormatModifierPropertiesListEXT: + ** slink:VkDrmFormatModifierPropertiesEXT + + * Extends slink:VkPhysicalDeviceImageFormatInfo2: + ** slink:VkPhysicalDeviceImageDrmFormatModifierInfoEXT + + * Extends slink:VkImageCreateInfo: + ** slink:VkImageDrmFormatModifierListCreateInfoEXT + ** slink:VkImageDrmFormatModifierExplicitCreateInfoEXT + + * Parameter to flink:vkGetImageDrmFormatModifierPropertiesEXT: + ** slink:VkImageDrmFormatModifierPropertiesEXT + +=== New Functions + + * flink:vkGetImageDrmFormatModifierPropertiesEXT + +=== Issues + +1. Should this extension define a single DRM format modifier per + sname:VkImage? Or define one per plane? ++ +-- +*RESOLVED.* +There exists a single DRM format modifier per sname:VkImage. + +*DISCUSSION.* +Prior art, such as +`EGL_EXT_image_dma_buf_import_modifiers`^<<VK_EXT_image_drm_format_modifier-fn2,2>>^, +`struct drm_mode_fb_cmd2`^<<VK_EXT_image_drm_format_modifier-fn4,4>>^, and +`struct gbm_import_fd_modifier_data`^<<VK_EXT_image_drm_format_modifier-fn5,5>>^, +allows defining one _modifier_ per plane. +However, developers of the GBM and kernel APIs concede it was a mistake. Beginning in +Linux 4.10, the kernel requires that the application provide the same DRM format +_modifier_ for each plane. +(See Linux commit https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=bae781b259269590109e8a4a8227331362b88212[bae781b259269590109e8a4a8227331362b88212]). +And GBM provides an entrypoint, ftext:gbm_bo_get_modifier, for querying the +_modifier_ of the image but does not provide one to query the modifier of +individual planes. +-- + +2. When creating an image with slink:VkImageDrmFormatModifierExplicitCreateInfoEXT, + which is typically used when _importing_ an image, + should the application explicitly provide the size of each plane? ++ +-- +*RESOLVED.* No. The application must: not provide the size. To enforce this, +the API requires that +slink:VkImageDrmFormatModifierExplicitCreateInfoEXT::pname:pPlaneLayouts::<<VkSubresourceLayout,pname:size>> +must: be 0. + +*DISCUSSION.* +Prior art, such as +`EGL_EXT_image_dma_buf_import_modifiers`^<<VK_EXT_image_drm_format_modifier-fn2,2>>^, +`struct drm_mode_fb_cmd2`^<<VK_EXT_image_drm_format_modifier-fn4,4>>^, and +`struct gbm_import_fd_modifier_data`^<<VK_EXT_image_drm_format_modifier-fn5,5>>^, omits +from the API the size of each plane. Instead, the APIs infer each plane's size +from the import parameters, which include the image's pixel format and +a dma_buf, offset, and row pitch for each plane. + +However, Vulkan differs from EGL and GBM with regards to image +creation in the following ways: + +.Differences in Image Creation + + - *Undedicated allocation by default.* + When importing or exporting a set of dma_bufs as an stext:EGLImage or + stext:gbm_bo, common practice mandates that each dma_buf's memory be + dedicated (in the sense of `VK_KHR_dedicated_allocation`) to the image + (though not necessarily dedicated to a single plane). In particular, + neither the GBM documentation nor the EGL extension specifications explicitly + state this requirement, but in light of common practice this is likely due to + under-specification rather than intentional omission. In contrast, + `VK_EXT_image_drm_format_modifier` permits, but does not require, the + implementation to require dedicated allocations for images created with + ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT. + + - *Separation of image creation and memory allocation.* + When importing a set of dma_bufs as an stext:EGLImage or stext:gbm_bo, EGL + and GBM create the image resource and bind it to memory (the dma_bufs) + simultaneously. This allows EGL and GBM to query each dma_buf's size during + image creation. In Vulkan, image creation and memory allocation are + independent unless a dedicated allocation is used (as in + `VK_KHR_dedicated_allocation`). Therefore, without requiring dedicated + allocation, Vulkan cannot query the size of each dma_buf (or other external + handle) when calculating the image's memory layout. Even if dedication + allocation were required, Vulkan cannot calculate the image's memory layout + until after the image is bound to its dma_ufs. + +The above differences complicate the potential inference of plane size in +Vulkan. Consider the following problematic cases: + +.Problematic Plane Size Calculations + + - *Padding.* Some plane of the image may require implementation-dependent padding. + + - *Metadata.* For some _modifiers_, the image may have a metadata plane which + requires a non-trivial calculation to determine its size. + + - *Mipmapped, array, and 3D images.* The implementation may support + ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT for images whose + pname:mipLevels, pname:arrayLayers, or pname:depth is greater than 1. For + such images with certain _modifiers_, the calculation of each plane's size + may be non-trivial. + +However, an application-provided plane size solves none of the above problems. + +For simplicity, consider an external image with a single memory plane. The +implementation is obviously capable calculating the image's size when its +tiling is ename:VK_IMAGE_TILING_OPTIMAL. Likewise, any reasonable +implementation is capable of calculating the image's size when its tiling uses +a supported _modifier_. + +Suppose that the external image's size is smaller than the +implementation-calculated size. If the application provided the external +image's size to slink:vkCreateImage, the implementation would observe the +mismatched size and recognize its inability to comprehend the external image's +layout (unless the implementation used the application-provided size to select +a refinement of the tiling layout indicated by the _modifier_, which is +strongly discouraged). The implementation would observe the conflict, and +reject image creation with +ename:VK_ERROR_INVALID_DRM_FORMAT_MODIFIER_PLANE_LAYOUT_EXT. On the other +hand, if the application did not provide the external image's size to +slink:vkCreateImage, then the application would observe after +calling flink:vkGetImageMemoryRequirements that the external image's size is +less than the size required by the implementation. The application would +observe the conflict and refuse to bind the sname:VkImage to the external +memory. In both cases, the result is explicit failure. + +Suppose that the external image's size is larger than the +implementation-calculated size. If the application provided the external +image's size to slink:vkCreateImage, for reasons similar to above the +implementation would observe the mismatched size and recognize its inability to +comprehend the image data residing in the extra size. The implementation, +however, must assume that image data resides in the entire size provided by the +application. The implementation would observe the conflict and reject image +creation with ename:VK_ERROR_INVALID_DRM_FORMAT_MODIFIER_PLANE_LAYOUT_EXT. On +the other hand, if the application did not provide the external image's size to +flink:vkCreateImage, then the application would observe after calling +flink:vkGetImageMemoryRequirements that the external image's size is larger +than the implementation-usable size. The application would observe the +conflict and refuse to bind the sname:VkImage to the external memory. In both +cases, the result is explicit failure. + +Therefore, an application-provided size provides no benefit, and this extension +should not require it. This decision renders +slink:VkSubresourceLayout::pname:size an unused field during image creation, +and thus introduces a risk that implementations may require applications to +submit sideband creation parameters in the unused field. To prevent +implementations from relying on sideband data, this extension _requires_ the +application to set pname:size to 0. +-- + +==== References + +1. [[VK_EXT_image_drm_format_modifier-fn1]] https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_image_dma_buf_import.txt[EGL_EXT_image_dma_buf_import] +2. [[VK_EXT_image_drm_format_modifier-fn2]] https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_image_dma_buf_import_modifiers.txt[EGL_EXT_image_dma_buf_import_modifiers] +3. [[VK_EXT_image_drm_format_modifier-fn3]] https://www.khronos.org/registry/EGL/extensions/MESA/EGL_MESA_image_dma_buf_export.txt[EGL_MESA_image_dma_buf_export] +4. [[VK_EXT_image_drm_format_modifier-fn4]] https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/include/uapi/drm/drm_mode.h?id=refs/tags/v4.10#n392[struct drm_mode_fb_cmd2] +5. [[VK_EXT_image_drm_format_modifier-fn5]] https://cgit.freedesktop.org/mesa/mesa/tree/src/gbm/main/gbm.h?id=refs/tags/mesa-18.0.0-rc1[gbm.h] + +==== Version History + + * Revision 1.0, 2018-08-29 (Chad Versace) + - First stable revision diff --git a/appendices/glossary.txt b/appendices/glossary.txt index 52db7b2..db8a307 100644 --- a/appendices/glossary.txt +++ b/appendices/glossary.txt @@ -159,9 +159,12 @@ endif::VK_AMD_shader_fragment_mask[] Color Renderable Format:: A elink:VkFormat where ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT is - set in the pname:optimalTilingFeatures or pname:linearTilingFeatures - member of slink:VkFormatProperties returned by - flink:vkGetPhysicalDeviceFormatProperties, depending on the tiling used. + set in one of the following, depending on the image's tiling: + * slink:VkImageFormatProperties::pname:linearTilingFeatures + * slink:VkImageFormatProperties::pname:optimalTilingFeatures +ifdef::VK_EXT_image_drm_format_modifier[] + * slink:VkDrmFormatPropertiesEXT::pname:drmFormatModifierTilingFeatures +endif::VK_EXT_image_drm_format_modifier[] Color Sample Mask:: A bitfield associated with a fragment, with one bit for each sample in @@ -777,10 +780,35 @@ Invocation Group:: [[glossary-linear-resource]] Linear Resource:: - A resource is _linear_ if it is a slink:VkBuffer, or a slink:VkImage - created with ename:VK_IMAGE_TILING_LINEAR. - A resource is _non-linear_ if it is a slink:VkImage created with - ename:VK_IMAGE_TILING_OPTIMAL. + A resource is _linear_ if it is one of the following: + * a slink:VkBuffer + * a slink:VkImage created with ename:VK_IMAGE_TILING_LINEAR +ifdef::VK_EXT_image_drm_format_modifier[] + * a slink:VkImage created with ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT + and whose <<glossary-drm-format-modifier,Linux DRM format modifier>> + is ename:DRM_FORMAT_MOD_LINEAR +endif::VK_EXT_image_drm_format_modifier[] ++ +A resource is _non-linear_ if it is one of the following: + * a slink:VkImage created with ename:VK_IMAGE_TILING_OPTIMAL +ifdef::VK_EXT_image_drm_format_modifier[] + * a slink:VkImage created with ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT + and whose <<glossary-drm-format-modifier,Linux DRM format modifier>> + is not ename:DRM_FORMAT_MOD_LINEAR +endif::VK_EXT_image_drm_format_modifier[] + +ifdef::VK_EXT_image_drm_format_modifier[] +[[glossary-drm-format-modifier,Linux DRM format modifier]] +Linux DRM Format Modifier:: + A 64-bit, vendor-prefixed, semi-opaque unsigned integer that describes + vendor-specific details of an image's memory layout. In Linux graphics APIs, + _modifiers_ are + commonly used to specify the memory layout of externally shared images. + An image has a _modifier_ if and only if it is created with pname:tiling + equal to ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT. + For more details, refer to the appendix for extension + <<VK_EXT_image_drm_format_modifier>>. +endif::VK_EXT_image_drm_format_modifier[] Local Workgroup:: A collection of compute shader invocations invoked by a single dispatch diff --git a/chapters/clears.txt b/chapters/clears.txt index 92acd57..98dcaec 100644 --- a/chapters/clears.txt +++ b/chapters/clears.txt @@ -324,6 +324,10 @@ described for flink:vkCreateRenderPass. ename:VK_IMAGE_ASPECT_STENCIL_BIT * [[VUID-VkClearAttachment-aspectMask-00020]] pname:aspectMask must: not include ename:VK_IMAGE_ASPECT_METADATA_BIT +ifdef::VK_EXT_image_drm_format_modifier[] + * pname:aspectMask must: not include etext:VK_IMAGE_ASPECT_MEMORY_PLANE___i___BIT_EXT + for any index __i__. +endif::VK_EXT_image_drm_format_modifier[] * [[VUID-VkClearAttachment-clearValue-00021]] pname:clearValue must: be a valid sname:VkClearValue union ifdef::VK_VERSION_1_1[] diff --git a/chapters/copies.txt b/chapters/copies.txt index 8195809..143f055 100644 --- a/chapters/copies.txt +++ b/chapters/copies.txt @@ -801,6 +801,10 @@ include::../api/structs/VkImageSubresourceLayers.txt[] ename:VK_IMAGE_ASPECT_STENCIL_BIT * [[VUID-VkImageSubresourceLayers-aspectMask-00168]] pname:aspectMask must: not contain ename:VK_IMAGE_ASPECT_METADATA_BIT +ifdef::VK_EXT_image_drm_format_modifier[] + * pname:aspectMask must: not include etext:VK_IMAGE_ASPECT_MEMORY_PLANE___i___BIT_EXT + for any index __i__. +endif::VK_EXT_image_drm_format_modifier[] * [[VUID-VkImageSubresourceLayers-layerCount-01700]] pname:layerCount must: be greater than 0 **** diff --git a/chapters/features.txt b/chapters/features.txt index b7a19a4..b5246ea 100755 --- a/chapters/features.txt +++ b/chapters/features.txt @@ -6018,13 +6018,23 @@ include::../validity/structs/VkFormatProperties.txt[] -- Bits which can: be set in the slink:VkFormatProperties features -pname:linearTilingFeatures, pname:optimalTilingFeatures, and -pname:bufferFeatures are: +pname:linearTilingFeatures, pname:optimalTilingFeatures, +ifdef::VK_EXT_image_drm_format_modifier[] +<<VkDrmFormatModifierPropertiesEXT,pname:drmFormatModifierTilingFeatures>>, +endif::VK_EXT_image_drm_format_modifier[] +and pname:bufferFeatures are: include::../api/enums/VkFormatFeatureFlagBits.txt[] -The following bits may: be set in pname:linearTilingFeatures and -pname:optimalTilingFeatures, specifying that the features are supported by +The following bits may: be set in +ifndef::VK_EXT_image_drm_format_modifier[] +pname:linearTilingFeatures and pname:optimalTilingFeatures, +endif::VK_EXT_image_drm_format_modifier[] +ifdef::VK_EXT_image_drm_format_modifier[] +pname:linearTilingFeatures, pname:optimalTilingFeatures, +and <<VkDrmFormatModifierPropertiesEXT,pname:drmFormatModifierTilingFeatures>>, +endif::VK_EXT_image_drm_format_modifier[] +specifying that the features are supported by <<VkImage,images>> or <<VkImageView,image views>> created with the queried flink:vkGetPhysicalDeviceFormatProperties::pname:format: @@ -6223,8 +6233,138 @@ endif::VK_KHR_get_physical_device_properties2[] include::../validity/structs/VkFormatProperties2.txt[] -- -endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] +ifdef::VK_EXT_image_drm_format_modifier[] +[open,refpage='VkDrmFormatModifierPropertiesListEXT',desc='Structure specifying the list of DRM format modifiers supported for a format',type='structs'] +-- +To obtain the list of <<glossary-drm-format-modifier,Linux DRM format modifiers>> +compatible with a elink:VkFormat, add +slink:VkDrmFormatModifierPropertiesListEXT to the pname:pNext chain of +slink:VkFormatProperties2. + +The slink:VkDrmFormatModifierPropertiesListEXT structure is defined as: + +include::../api/structs/VkDrmFormatModifierPropertiesListEXT.txt[] + * pname:sType is the type of this structure. + * pname:pNext is `NULL` or a pointer to an extension-specific structure. + * pname:drmFormatModifierCount is an inout parameter related to the number + of modifiers compatible with the pname:format, as descibed below. + * pname:pDrmFormatModifierProperties is either `NULL` or an array of + slink:VkDrmFormatModifierPropertiesEXT structures. + +If pname:pDrmFormatModifierProperties is `NULL`, +then the function returns in pname:drmFormatModifierCount +the number of modifiers compatible with the queried pname:format. +Otherwise, the application must: set pname:drmFormatModifierCount +to the length of the array pname:pDrmFormatModifierProperties; +the function will write +at most pname:drmFormatModifierCount elements to the array, +and will return in pname:drmFormatModifierCount the number of elements written. + +Among the elements in array pname:pDrmFormatModifierProperties, each +returned pname:drmFormatModifier must: be unique. + +include::../validity/structs/VkDrmFormatModifierPropertiesListEXT.txt[] +-- + +[open,refpage='VkDrmFormatModifierPropertiesEXT',desc='Structure specifying properties of a format when combined with a DRM format modifier',type='structs'] +-- +The slink:VkDrmFormatModifierPropertiesEXT structure describes properties of +a elink:VkFormat when that format is combined with +a <<glossary-drm-format-modifier,Linux DRM format modifier>>. +These properties, like those of slink:VkFormatProperties2, are independent of +any particular image. + +The slink:VkDrmFormatModifierPropertiesEXT structure is defined as: + +include::../api/structs/VkDrmFormatModifierPropertiesEXT.txt[] + + * pname:drmFormatModifier is a _Linux DRM format modifier_. + * pname:drmFormatModifierPlaneCount is the number of _memory planes_ in any + image created with pname:format and pname:drmFormatModifier. An image's + _memory planecount_ is distinct from its _format planecount_, as + explained below. + * pname:drmFormatModifierTilingFeatures is a bitmask of + elink:VkFormatFeatureFlagBits that are supported by any image created with + pname:format and pname:drmFormatModifier. + +The returned pname:drmFormatModifierTilingFeatures must: contain at least one +bit. + +The implementation must: not return etext:DRM_FORMAT_MOD_INVALID in +pname:drmFormatModifier. + +An image's _memory planecount_ (as returned by +pname:drmFormatModifierPlaneCount) is distinct from its _format planecount_ +(in the sense of <<features-formats-requiring-sampler-ycbcr-conversion,multi-planar>> Y'C~B~C~R~ formats). +In elink:VkImageAspectFlags, +each etext:VK_IMAGE_ASPECT_MEMORY_PLANE___i___BIT_EXT represents a _memory plane_ +and each etext:VK_IMAGE_ASPECT_PLANE___i___BIT a _format plane_. + +An image's set of _format planes_ is an ordered partition of the image's *content* +into separable groups of format channels. +The ordered partition is encoded in the name of each elink:VkFormat. +For example, ename:VK_FORMAT_G8_B8R8_2PLANE_420_UNORM contains two _format planes_; +the first plane contains the green channel +and the second plane contains the blue channel and red channel. +If the format name does not contain `PLANE`, +then the format contains a single plane; +for example, ename:VK_FORMAT_R8G8B8A8_UNORM. +Some commands, such as flink:vkCmdBufferToImage, do +not operate on all format channels in the image, but instead operate only on +the _format planes_ explicitly chosen by the application and operate on each +_format plane_ independently. + +An image's set of _memory planes_ is an ordered partition of the image's *memory* +rather than the image's *content*. +Each _memory plane_ is a contiguous range of memory. +The union of an image's _memory planes_ is not necessarily contiguous. + +If an image is <<glossary-linear-resource,linear>>, +then the partition is the same for _memory planes_ and for _format planes_. +Therefore, if the returned pname:drmFormatModifier is ename:DRM_FORMAT_MOD_LINEAR, +then pname:drmFormatModifierPlaneCount must: equal the _format planecount_, +and pname:drmFormatModifierTilingFeatures must: be identical to the +slink:VkFormatProperties2::pname:linearTilingFeatures +returned in the same pname:pNext chain. + +If an image is <<glossary-linear-resource,non-linear>>, +then the partition of the image's *memory* into _memory planes_ +is implementation-specific +and may: be unrelated +to the partition of the image's *content* into _format planes_. +For example, consider an image whose +pname:format is ename:VK_FORMAT_G8_B8_R8_3PLANE_420_UNORM, +pname:tiling is ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, +whose pname:drmFormatModifier is not ename:DRM_FORMAT_MOD_LINEAR, +and pname:flags lacks ename:VK_IMAGE_CREATE_DISJOINT_BIT. +The image has 3 _format planes_, +and commands such flink:vkCmdCopyBufferToImage +act on each _format plane_ independently +as if the data of each _format plane_ were separable from the data of the other planes. +In a straightforward implementation, +the implementation may: store the image's content +in 3 adjacent _memory planes_ +where each _memory plane_ corresponds exactly to a _format plane_. +However, the implementation may: also store the image's content +in a single _memory plane_ where all format channels are combined +using an implementation-private block-compressed format; +or the implementation may: store the image's content +in a collection of 7 adjacent _memory planes_ +using an implementation-private sharding technique. +Because the image is non-linear and non-disjoint, +the implementation has much freedom +when choosing the image's placement in memory. + +The _memory planecount_ applies to function parameters and structures +only when the API specifies an explicit requirement +on pname:drmFormatModifierPlaneCount. +In all other cases, the _memory planecount_ is ignored. + +include::../validity/structs/VkDrmFormatModifierPropertiesEXT.txt[] +-- +endif::VK_EXT_image_drm_format_modifier[] +endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] [[features-required-format-support]] === Required Format Support @@ -6901,6 +7041,14 @@ then the limitations for code:usage1 and code:flags1 must: be no more strict than the limitations for code:usage2 and code:flags2, for all values of pname:format, pname:type, and pname:tiling. +ifdef::VK_EXT_image_drm_format_modifier[] +.Valid Usage +**** + * pname:tiling must: not be ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT. + (Use flink:vkGetPhysicalDeviceImageFormatProperties2 instead). +**** +endif::VK_EXT_image_drm_format_modifier[] + include::../validity/protos/vkGetPhysicalDeviceImageFormatProperties.txt[] -- @@ -6922,6 +7070,10 @@ include::../api/structs/VkImageFormatProperties.txt[] instead be `1`: ** fname:vkGetPhysicalDeviceImageFormatProperties::pname:tiling was ename:VK_IMAGE_TILING_LINEAR +ifdef::VK_EXT_image_drm_format_modifier[] + ** slink:VkPhysicalDeviceImageFormatInfo2::pname:tiling was + ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT +endif::VK_EXT_image_drm_format_modifier[] ifdef::VK_VERSION_1_1,VK_KHR_external_memory_capabilities[] ** the slink:VkPhysicalDeviceImageFormatInfo2::pname:pNext chain included an instance of slink:VkPhysicalDeviceExternalImageFormatInfo @@ -6929,11 +7081,23 @@ ifdef::VK_VERSION_1_1,VK_KHR_external_memory_capabilities[] mipmap image support is not required endif::VK_VERSION_1_1,VK_KHR_external_memory_capabilities[] * pname:maxArrayLayers is the maximum number of array layers. - pname:maxArrayLayers must: either be equal to 1 or be greater than or - equal to the pname:maxImageArrayLayers member of - slink:VkPhysicalDeviceLimits. - A value of 1 is valid only if pname:tiling is - ename:VK_IMAGE_TILING_LINEAR or if pname:type is ename:VK_IMAGE_TYPE_3D. + * If pname:tiling is ename:VK_IMAGE_TILING_LINEAR, + then pname:maxArrayLayers must: either + be equal to 1 or + be no less than slink:VkPhysicalDeviceLimits::pname:maxImageArrayLayers. + * If pname:tiling is ename:VK_IMAGE_TILING_OPTIMAL and + pname:type is ename:VK_IMAGE_TYPE_3D, + then pname:maxArrayLayers must: either + be equal to 1 or + be no less than slink:VkPhysicalDeviceLimits::pname:maxImageArrayLayers. + * If pname:tiling is ename:VK_IMAGE_TILING_OPTIMAL and + pname:type is not ename:VK_IMAGE_TYPE_3D, + then pname:maxArrayLayers must: + be no less than slink:VkPhysicalDeviceLimits::pname:maxImageArrayLayers. +ifdef::VK_EXT_image_drm_format_modifier[] + * If pname:tiling is ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, + then pname:maxArrayLayers must: not be 0. +endif::VK_EXT_image_drm_format_modifier[] * pname:sampleCounts is a bitmask of elink:VkSampleCountFlagBits specifying all the supported sample counts for this image as described <<features-supported-sample-counts, below>>. @@ -7059,6 +7223,15 @@ The members of sname:VkPhysicalDeviceImageFormatInfo2 correspond to the arguments to flink:vkGetPhysicalDeviceImageFormatProperties, with pname:sType and pname:pNext added for extensibility. +ifdef::VK_EXT_image_drm_format_modifier[] +.Valid Usage +**** + * pname:tiling must: be ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT + if and only if the pname:pNext chain contains + slink:VkPhysicalDeviceImageDrmFormatModifierInfoEXT. +**** +endif::VK_EXT_image_drm_format_modifier[] + include::../validity/structs/VkPhysicalDeviceImageFormatInfo2.txt[] -- @@ -7444,6 +7617,39 @@ zero or more slink:VkExternalMemoryFeatureFlagBits. endif::VK_VERSION_1_1,VK_KHR_external_memory_capabilities[] +ifdef::VK_EXT_image_drm_format_modifier[] +[open,refpage='VkPhysicalDeviceImageDrmFormatModifierInfoEXT',desc='Structure specifying a DRM format modifier as image creation parameter',type='structs'] +-- +To query the image capabilities that are compatible with a +<<glossary-drm-format-modifier,Linux DRM format modifier>>, +set slink:VkPhysicalDeviceImageFormatInfo2::pname:tiling to +ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT and add +slink:VkPhysicalDeviceImageDrmFormatModifierInfoEXT to the pname:pNext chain of +slink:VkPhysicalDeviceImageFormatInfo2. + +The slink:VkPhysicalDeviceImageDrmFormatModifierInfoEXT structure is +defined as: + +include::../api/structs/VkPhysicalDeviceImageDrmFormatModifierInfoEXT.txt[] + + * pname:sType is the type of this structure. + * pname:pNext is `NULL` or a pointer to an extension-specific structure. + * pname:drmFormatModifier is the image's _Linux DRM format modifier_, + corresponding to + slink:VkImageDrmFormatModifierExplicitCreateInfoEXT::pname:modifier or to + slink:VkImageDrmFormatModifierListCreateInfoEXT::pname:pModifiers. + +If the pname:drmFormatModifier is incompatible with the parameters specified in +slink:VkPhysicalDeviceImageFormatInfo2 and its pname:pNext chain, then +flink:vkGetPhysicalDeviceImageFormatProperties2 returns +ename:VK_ERROR_FORMAT_NOT_SUPPORTED. +The implementation must: support the query of any pname:drmFormatModifier, +including unknown and invalid modifier values. + +include::../validity/structs/VkPhysicalDeviceImageDrmFormatModifierInfoEXT.txt[] +-- +endif::VK_EXT_image_drm_format_modifier[] + ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] [open,refpage='VkSamplerYcbcrConversionImageFormatProperties',desc='Structure specifying combined image sampler descriptor count for multi-planar images',type='structs'] diff --git a/chapters/renderpass.txt b/chapters/renderpass.txt index 9e0ee4c..b21f4b9 100644 --- a/chapters/renderpass.txt +++ b/chapters/renderpass.txt @@ -583,6 +583,10 @@ endif::VK_KHR_maintenance2[] **** * [[VUID-VkInputAttachmentAspectReference-aspectMask-01964]] pname:aspectMask must: not include ename:VK_IMAGE_ASPECT_METADATA_BIT +ifdef::VK_EXT_image_drm_format_modifier[] + * pname:aspectMask must: not include etext:VK_IMAGE_ASPECT_MEMORY_PLANE___i___BIT_EXT + for any index __i__. +endif::VK_EXT_image_drm_format_modifier[] **** include::../validity/structs/VkInputAttachmentAspectReference.txt[] diff --git a/chapters/resources.txt b/chapters/resources.txt index 4fe7739..6975cd7 100644 --- a/chapters/resources.txt +++ b/chapters/resources.txt @@ -659,16 +659,37 @@ ifdef::VK_VERSION_1_1,VK_KHR_external_memory_capabilities[] Otherwise, pname:imageCreateExternalMemoryHandles is `0` endif::VK_VERSION_1_1,VK_KHR_external_memory_capabilities[] -// NOTE: The following definition is currently trivial, but -// VK_EXT_image_drm_format_modifier will complicate it. +ifdef::VK_EXT_image_drm_format_modifier[] +* Let `uint64_t imageCreateDrmFormatModifiers[]` be the set of + <<glossary-drm-format-modifier,Linux DRM format modifiers>> + that the resultant image may: have. + ** If pname:tiling is not ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, + then pname:imageCreateDrmFormatModifiers is empty. + ** If sname:VkImageCreateInfo::pname:pNext contains + slink:VkImageDrmFormatModifierExplicitCreateInfoEXT, + then pname:imageCreateDrmFormatModifiers contains exactly one modifier, + sname:VkImageDrmFormatModifierExplicitCreateInfoEXT::pname:drmFormatModifier. + ** If sname:VkImageCreateInfo::pname:pNext contains + slink:VkImageDrmFormatModifierListCreateInfoEXT, + then pname:imageCreateDrmFormatModifiers contains the exactly the modifiers + in sname:VkImageDrmFormatModifierListCreateInfoEXT::pname:pDrmFormatModifiers. +endif::VK_EXT_image_drm_format_modifier[] + * Let `VkBool32 imageCreateMaybeLinear` indicate if the resulant image may be <<glossary-linear-image,linear>>. +ifndef::VK_EXT_image_drm_format_modifier[] (The definition below is trivial because certain extensions are disabled in this build of the specification). +endif::VK_EXT_image_drm_format_modifier[] ** If pname:tiling is ename:VK_IMAGE_TILING_LINEAR, then pname:imageCreateMaybeLinear is `true`. ** If pname:tiling is ename:VK_IMAGE_TILING_OPTIMAL, then pname:imageCreateMaybeLinear is `false`. +ifdef::VK_EXT_image_drm_format_modifier[] + ** If pname:tiling is ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, + then pname:imageCreateMaybeLinear_ is `true` if and only if + pname:imageCreateDrmFormatModifiers contains etext:DRM_FORMAT_MOD_LINEAR. +endif::VK_EXT_image_drm_format_modifier[] * Let `VkFormatFeatureFlags imageCreateFormatFeatures` be the set of format features available during image creation. @@ -697,6 +718,23 @@ ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] obtained by flink:vkGetAndroidHardwareBufferPropertiesANDROID with a matching pname:externalFormat value. endif::VK_ANDROID_external_memory_android_hardware_buffer[] +ifdef::VK_EXT_image_drm_format_modifier[] + ** If pname:tiling is ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, + then the value of pname:imageCreateFormatFeatures is found + by calling flink:vkGetPhysicalDeviceFormatProperties2 + with slink:VkImageFormatProperties::pname:format + equal to sname:VkImageCreateInfo::pname:format + and with slink:VkDrmFormatModifierPropertiesListEXT + chained into slink:VkImageFormatProperties2; + by collecting all members + of the returned array + slink:VkDrmFormatModifierPropertiesListEXT::pDrmFormatModifierProperties + whose pname:drmFormatModifier belongs to pname:imageCreateDrmFormatModifiers; + and by taking the bitwise intersection, + over the collected array members, + of pname:drmFormatModifierTilingFeatures. + (The resultant pname:imageCreateFormatFeatures may: be empty). +endif::VK_EXT_image_drm_format_modifier[] ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] * Let `VkImageFormatProperties2 imageCreateImageFormatPropertiesList[]` be @@ -711,13 +749,27 @@ endif::VK_ANDROID_external_memory_android_hardware_buffer[] by calling flink:vkGetPhysicalDeviceImageFormatProperties2 for each bit in pname:imageCreateExternalMemoryHandles, with slink:VkPhysicalDeviceExternalImageFormatInfo::pname:handleType - set to that bit. + set to that bit +ifndef::VK_EXT_image_drm_format_modifier[.] +ifdef::VK_EXT_image_drm_format_modifier[,] +ifdef::VK_EXT_image_drm_format_modifier[] + and for each modifier in pname:imageCreateDrmFormatModifiers, + with slink:VkPhysicalDeviceImageDrmFormatModifierInfoEXT::pname:drmFormatModifier + set to that modifier. +endif::VK_EXT_image_drm_format_modifier[] (If pname:imageCreateExternalMemoryHandles is empty, then pname:imageCreateImageFormatPropertiesList is the list of structures obtained by calling flink:vkGetPhysicalDeviceImageFormatProperties2 with slink:VkPhysicalDeviceExternalImageFormatInfo omitted or with slink:VkPhysicalDeviceExternalImageFormatInfo::pname:handleType equal to `0`). +ifdef::VK_EXT_image_drm_format_modifier[] + (If pname:imageCreateDrmFormatModifiers is empty, then + pname:imageCreateImageFormatPropertiesList + is the list of structures obtained + by calling flink:vkGetPhysicalDeviceImageFormatProperties2 + with slink:VkPhysicalDeviceImageDrmFormatModifierInfoEXT omitted). +endif::VK_EXT_image_drm_format_modifier[] In each call, the parameters slink:VkPhysicalDeviceImageFormatInfo2::pname:format, pname:imageType, pname:tiling, pname:usage, and pname:flags must: be equal to those in sname:VkImageCreateInfo. @@ -1077,6 +1129,16 @@ ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] include ename:VK_IMAGE_CREATE_ALIAS_BIT, pname:flags must: not contain ename:VK_IMAGE_CREATE_DISJOINT_BIT endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] +ifdef::VK_EXT_image_drm_format_modifier[] + * If pname:tiling is ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, + then the pname:pNext chain must: contain exactly one of + slink:VkImageDrmFormatModifierListCreateInfoEXT or + slink:VkImageDrmFormatModifierExplicitCreateInfoEXT. + * If the pname:pNext chain contains + slink:VkImageDrmFormatModifierListCreateInfoEXT or + slink:VkImageDrmFormatModifierExplicitCreateInfoEXT, + then pname:tiling must: be ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT. +endif::VK_EXT_image_drm_format_modifier[] ifdef::VK_EXT_sample_locations[] * [[VUID-VkImageCreateInfo-flags-01533]] If pname:flags contains @@ -1349,6 +1411,99 @@ include::../validity/structs/VkImageFormatListCreateInfoKHR.txt[] endif::VK_KHR_image_format_list[] +ifdef::VK_EXT_image_drm_format_modifier[] +[open,refpage='VkImageDrmFormatModifierListCreateInfoEXT',desc='Specify that an image must be created with a DRM format modifier from the provided list',type='structs'] +-- +If the pname:pNext chain of slink:VkImageCreateInfo contains +slink:VkImageDrmFormatModifierListCreateInfoEXT, then the image will +be created with one of the +<<glossary-drm-format-modifier,Linux DRM format modifiers>> +listed in the structure. The choice of modifier is implementation-dependent. + +The slink:VkImageDrmFormatModifierListCreateInfoEXT structure is defined as: + +include::../api/structs/VkImageDrmFormatModifierListCreateInfoEXT.txt[] + + * pname:sType is the type of this structure. + * pname:pNext is `NULL` or a pointer to an extension-specific structure. + * pname:drmFormatModifierCount is the length of the + pname:pDrmFormatModifiers array. + * pname:pDrmFormatModifiers is an array of _Linux DRM format modifiers_. + +.Valid Usage +**** + * Each _modifier_ in pname:pDrmFormatModifiers must be compatible with + the parameters in slink:VkImageCreateInfo and its pname:pNext chain, + as determined by querying slink:VkPhysicalDeviceImageFormatInfo2 + extended with slink:VkPhysicalDeviceImageDrmFormatModifierInfoEXT. +**** + +include::../validity/structs/VkImageDrmFormatModifierListCreateInfoEXT.txt[] +-- + +[open,refpage='VkImageDrmFormatModifierExplicitCreateInfoEXT',desc='Specify that an image be created with the provided DRM format modifier and explicit memory layout',type='structs'] +-- +If the pname:pNext chain of slink:VkImageCreateInfo contains +slink:VkImageDrmFormatModifierExplicitCreateInfoEXT, then the image will +be created with the <<glossary-drm-format-modifier,Linux DRM format modifier>> +and memory layout defined by the structure. + +The slink:VkImageDrmFormatModifierExplicitCreateInfoEXT structure is defined as: + +include::../api/structs/VkImageDrmFormatModifierExplicitCreateInfoEXT.txt[] + + * pname:sType is the type of this structure. + * pname:pNext is `NULL` or a pointer to an extension-specific structure. + * pname:drmFormatModifier is the _Linux DRM format modifier_ with which the + image will be created. + * pname:drmFormatModifierPlaneCount is the number of _memory planes_ in the + image (as reported by slink:VkDrmFormatModifierPropertiesEXT) + as well as the length of the pname:pPlaneLayouts array. + * pname:pPlaneLayouts is an array of slink:VkSubresourceLayout structures + that describe the image's _memory planes_. + +The i^th^ member of pname:pPlaneLayouts +describes the layout of the image's i^th^ _memory plane_ +(that is, etext:VK_IMAGE_ASPECT_MEMORY_PLANE___i___BIT_EXT). +In each element of pname:pPlaneLayouts, +the implementation must: ignore pname:size. +The implementation calculates the size of each plane, +which the application can: query with flink:vkGetImageSubresourceLayout. + +When creating an image with +slink:VkImageDrmFormatModifierExplicitCreateInfoEXT, +it is the application's responsibility to satisfy all +Valid Usage+ requirements. +However, the implementation must: validate that the provided pname:pPlaneLayouts, +when combined with the provided pname:drmFormatModifier and other +creation parameters in slink:VkImageCreateInfo and its pname:pNext chain, +produce a valid image. (This validation is necessarily implementation-dependent +and outside the scope of Vulkan, and therefore not described by +Valid Usage+ requirements). +If this validation fails, then flink:vkCreateImage returns +ename:VK_ERROR_INVALID_DRM_FORMAT_MODIFIER_PLANE_LAYOUT_EXT. + +.Valid Usage +**** + * pname:drmFormatModifier must be compatible with + the parameters in slink:VkImageCreateInfo and its pname:pNext chain, + as determined by querying slink:VkPhysicalDeviceImageFormatInfo2KHR + extended with slink:VkPhysicalDeviceImageDrmFormatModifierInfoEXT. + * pname:drmFormatModifierPlaneCount must: be equal to the + slink:VkDrmFormatModifierPropertiesEXT::pname:drmFormatModifierPlaneCount + associated with slink:VkImageCreateInfo::pname:format and + pname:drmFormatModifier, + as found by querying slink:VkDrmFormatModifierPropertiesListEXT. + * For each element of pname:pPlaneLayouts: + ** pname:size must: be 0 + ** pname:arrayPitch must: be 0 if slink:VkImageCreateInfo::pname:arrayLayers + is 1. + ** pname:depthPitch must: be 0 if + slink:VkImageCreateInfo::pname:extent::pname:depth is 1. +**** + +include::../validity/structs/VkImageDrmFormatModifierExplicitCreateInfoEXT.txt[] +-- +endif::VK_EXT_image_drm_format_modifier[] + [open,refpage='VkImageUsageFlagBits',desc='Bitmask specifying intended usage of an image',type='enums'] -- @@ -1547,14 +1702,20 @@ include::../api/enums/VkImageTiling.txt[] * ename:VK_IMAGE_TILING_LINEAR specifies linear tiling (texels are laid out in memory in row-major order, possibly with some padding on each row). - +ifdef::VK_EXT_image_drm_format_modifier[] + * ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT indicates that the image's + tiling is defined by a <<glossary-drm-format-modifier,Linux DRM format modifier>>. + The modifier is specified at image creation with + slink:VkImageDrmFormatModifierListCreateInfoEXT or + slink:VkImageDrmFormatModifierExplicitCreateInfoEXT, + and can: be queried with slink:vkGetImageDrmFormatModifierPropertiesEXT. +endif::VK_EXT_image_drm_format_modifier[] -- [open,refpage='vkGetImageSubresourceLayout',desc='Retrieve information about an image subresource',type='protos'] -- -To query the host access layout of an image subresource, for an image -created with linear tiling, call: +To query the memory layout of an image subresource, call: include::../api/protos/vkGetImageSubresourceLayout.txt[] @@ -1565,11 +1726,38 @@ include::../api/protos/vkGetImageSubresourceLayout.txt[] * pname:pLayout points to a slink:VkSubresourceLayout structure in which the layout is returned. +ifndef::VK_EXT_image_drm_format_modifier[] +The image must: be <<glossary-linear-resource,linear>>. The +endif::VK_EXT_image_drm_format_modifier[] +ifdef::VK_EXT_image_drm_format_modifier[] +If the image is <<glossary-linear-resource,linear>>, then the +endif::VK_EXT_image_drm_format_modifier[] +returned layout is valid for <<memory-device-hostacces, host access>>. + ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] -If the elink:VkFormat of pname:image is a +If the image's +ifdef::VK_EXT_image_drm_format_modifier[] +tiling is ename:VK_IMAGE_TILING_LINEAR and its +endif::VK_EXT_image_drm_format_modifier[] +format is a <<features-formats-requiring-sampler-ycbcr-conversion,multi-planar format>>, -fname:vkGetImageSubresourceLayout describes one plane of the image. +then fname:vkGetImageSubresourceLayout describes one +ifdef::VK_EXT_image_drm_format_modifier[_format plane_] +ifndef::VK_EXT_image_drm_format_modifier[plane] +of the image. endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] +ifdef::VK_EXT_image_drm_format_modifier[] +If the image's tiling is ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, +then fname:vkGetImageSubresourceLayout describes +one _memory plane_ of the image. +If the image's tiling is ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT +and the image is <<glossary-linear-resource,non-linear>>, +then the returned layout has an implementation-dependent meaning; +the vendor of the image's +<<glossary-drm-format-modifier,DRM format modifier>> +may: provide documentation +that explains how to interpret the returned layout. +endif::VK_EXT_image_drm_format_modifier[] fname:vkGetImageSubresourceLayout is invariant for the lifetime of a single image. @@ -1582,9 +1770,15 @@ endif::VK_ANDROID_external_memory_android_hardware_buffer[] .Valid Usage **** +ifndef::VK_EXT_image_drm_format_modifier[] * [[VUID-vkGetImageSubresourceLayout-image-00996]] pname:image must: have been created with pname:tiling equal to ename:VK_IMAGE_TILING_LINEAR +endif::VK_EXT_image_drm_format_modifier[] +ifdef::VK_EXT_image_drm_format_modifier[] + * pname:image must: have been created with pname:tiling equal to + ename:VK_IMAGE_TILING_LINEAR or ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT +endif::VK_EXT_image_drm_format_modifier[] * [[VUID-vkGetImageSubresourceLayout-aspectMask-00997]] The pname:aspectMask member of pname:pSubresource must: only have a single bit set @@ -1598,13 +1792,15 @@ endif::VK_ANDROID_external_memory_android_hardware_buffer[] was created ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] * [[VUID-vkGetImageSubresourceLayout-format-01581]] - If the pname:format of pname:image is a + If the pname:tiling of the pname:image is ename:VK_IMAGE_TILING_LINEAR + and its pname:format is a <<features-formats-requiring-sampler-ycbcr-conversion,multi-planar format>> with two planes, the pname:aspectMask member of pname:pSubresource must: be ename:VK_IMAGE_ASPECT_PLANE_0_BIT or ename:VK_IMAGE_ASPECT_PLANE_1_BIT * [[VUID-vkGetImageSubresourceLayout-format-01582]] - If the pname:format of pname:image is a + If the pname:tiling of the pname:image is ename:VK_IMAGE_TILING_LINEAR + and its pname:format is a <<features-formats-requiring-sampler-ycbcr-conversion,multi-planar format>> with three planes, the pname:aspectMask member of pname:pSubresource must: be ename:VK_IMAGE_ASPECT_PLANE_0_BIT, @@ -1616,6 +1812,16 @@ ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID external memory handle type, then pname:image must: be bound to memory. endif::VK_ANDROID_external_memory_android_hardware_buffer[] +ifdef::VK_EXT_image_drm_format_modifier[] + * If the pname:tiling of the pname:image is ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, + then the pname:aspectMask member of pname:pSubresource must: be + etext:VK_IMAGE_ASPECT_MEMORY_PLANE___i___BIT_EXT + and the index __i__ must: be less than the + <<VkDrmFormatModifierPropertiesEXT,pname:drmFormatModifierPlaneCount>> + associated with the image's + <<VkImageCreateInfo,pname:format>> and + <<VkImageDrmFormatModifierPropertiesEXT,pname:drmFormatModifier>>. +endif::VK_EXT_image_drm_format_modifier[] **** include::../validity/protos/vkGetImageSubresourceLayout.txt[] @@ -1659,7 +1865,8 @@ endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] * pname:depthPitch describes the number of bytes between each slice of 3D image. -For images created with linear tiling, pname:rowPitch, pname:arrayPitch and +If the image is <<glossary-linear-resource,linear>>, +then pname:rowPitch, pname:arrayPitch and pname:depthPitch describe the layout of the image subresource in linear memory. For uncompressed formats, pname:rowPitch is the number of bytes between @@ -1695,13 +1902,22 @@ address(x,y,z,layer) = layer*arrayPitch + z*depthPitch + y*rowPitch + x*compress pname:arrayPitch is undefined for images that were not created as arrays. pname:depthPitch is defined only for 3D images. -For +If the image has a ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] _single-plane_ endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] -color formats, the pname:aspectMask member of sname:VkImageSubresource must: +color format +ifdef::VK_EXT_image_drm_format_modifier[] +and its tiling is ename:VK_IMAGE_TILING_LINEAR +endif::VK_EXT_image_drm_format_modifier[] +, then the pname:aspectMask member of sname:VkImageSubresource must: be ename:VK_IMAGE_ASPECT_COLOR_BIT. -For depth/stencil formats, pname:aspectMask must: be either + +If the image has a depth/stencil format +ifdef::VK_EXT_image_drm_format_modifier[] +and its tiling is ename:VK_IMAGE_TILING_LINEAR +endif::VK_EXT_image_drm_format_modifier[] +, then pname:aspectMask must: be either ename:VK_IMAGE_ASPECT_DEPTH_BIT or ename:VK_IMAGE_ASPECT_STENCIL_BIT. On implementations that store depth and stencil aspects separately, querying each of these image subresource layouts will return a different pname:offset @@ -1711,10 +1927,15 @@ same pname:offset and pname:size are returned and represent the interleaved memory allocation. ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] -For <<features-formats-requiring-sampler-ycbcr-conversion,multi-planar -formats>>, the pname:aspectMask member of sname:VkImageSubresource must: be -ename:VK_IMAGE_ASPECT_PLANE_0_BIT, ename:VK_IMAGE_ASPECT_PLANE_1_BIT, or -(for 3-plane formats only) ename:VK_IMAGE_ASPECT_PLANE_2_BIT. +If the image has a +<<features-formats-requiring-sampler-ycbcr-conversion,multi-planar format>> +ifdef::VK_EXT_image_drm_format_modifier[] +and its tiling is ename:VK_IMAGE_TILING_LINEAR +endif::VK_EXT_image_drm_format_modifier[] +, then the pname:aspectMask member of sname:VkImageSubresource must: be +ename:VK_IMAGE_ASPECT_PLANE_0_BIT, +ename:VK_IMAGE_ASPECT_PLANE_1_BIT, or (for 3-plane formats only) +ename:VK_IMAGE_ASPECT_PLANE_2_BIT. Querying each of these image subresource layouts will return a different pname:offset and pname:size representing the region of memory used for that plane. @@ -1724,9 +1945,76 @@ If the image is _non-disjoint_, then the pname:offset is relative to the base address of the image. endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] +ifdef::VK_EXT_image_drm_format_modifier[] +If the image's tiling is ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, +then the pname:aspectMask member of sname:VkImageSubresource must: be +one of etext:VK_IMAGE_ASPECT_MEMORY_PLANE___i___BIT_EXT, +where the maximum allowed plane index __i__ is defined by the +<<VkDrmFormatModifierPropertiesEXT,pname:drmFormatModifierPlaneCount>> associated +with the image's <<VkImageCreateInfo,pname:format>> and <<glossary-drm-format-modifier,modifier>>. +The memory range used by the subresource is described by +pname:offset and pname:size. +If the image is _disjoint_, +then the pname:offset is relative to the base address of the _memory plane_. +If the image is _non-disjoint_, +then the pname:offset is relative to the base address of the image. +If the image is <<glossary-linear-resource,non-linear>>, +then pname:rowPitch, pname:arrayPitch, and pname:depthPitch +have an implementation-dependent meaning. +endif::VK_EXT_image_drm_format_modifier[] + include::../validity/structs/VkSubresourceLayout.txt[] -- +ifdef::VK_EXT_image_drm_format_modifier[] +[open,refpage='vkGetImageDrmFormatModifierPropertiesEXT',desc='Returns an image's DRM format modifier',type='protos'] +-- +If an image was created with ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, +then the image has a <<glossary-drm-format-modifier,Linux DRM format modifier>>. +To query the _modifier_, call: + +include::../api/protos/vkGetImageDrmFormatModifierPropertiesEXT.txt[] + + * pname:device is the logical device that owns the image. + * pname:image is the queried image. + * pname:pProperties will return properties of the image's _DRM format modifier_. + +.Valid Usage +**** + * pname:image must: have been created + with <<VkImageCreateInfo,pname:tiling>> + equal to ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT. +**** + +include::../validity/protos/vkGetImageDrmFormatModifierPropertiesEXT.txt[] +-- + +[open,refpage='VkImageDrmFormatModifierPropertiesEXT',desc='Properties of an image's Linux DRM format modifier'] +-- +The slink:VkImageDrmFormatModifierPropertiesEXT structure is defined as: + +include::../api/structs/VkImageDrmFormatModifierPropertiesEXT.txt[] + + * pname:sType is the type of this structure. + * pname:pNext is `NULL` or a pointer to an extension-specific structure. + * pname:drmFormatModifier returns the image's + <<glossary-drm-format-modifier,Linux DRM format modifier>>. + +If the pname:image was created +with slink:VkImageDrmFormatModifierListCreateInfoEXT, +then the returned pname:drmFormatModifier +must: belong to the list of modifiers provided at time of image creation +in slink:VkImageDrmFormatModifierListCreateInfoEXT::pname:pDrmFormatModifiers. +If the pname:image was created +with slink:VkImageDrmFormatModifierExplicitCreateInfoEXT, +then the returned pname:drmFormatModifier +must: be the modifier provided at time of image creation +in slink:VkImageDrmFormatModifierExplicitCreateInfoEXT::pname:drmFormatModifier. + +include::../validity/structs/VkImageDrmFormatModifierPropertiesEXT.txt[] +-- +endif::VK_EXT_image_drm_format_modifier[] + [open,refpage='vkDestroyImage',desc='Destroy an image object',type='protos'] -- @@ -1786,6 +2074,21 @@ ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] the Android hardware buffer that was imported to the slink:VkDeviceMemory to which the image is bound. endif::VK_ANDROID_external_memory_android_hardware_buffer[] +ifdef::VK_EXT_image_drm_format_modifier[] + * If the image was created + with ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then: + ** The image's DRM format modifier is the value + of slink:VkImageDrmFormatModifierListCreateInfoEXT::pname:drmFormatModifier + found by calling flink:vkGetImageDrmFormatModifierPropertiesEXT. + ** Let slink:VkDrmFormatModifierPropertiesListEXT::pname:pDrmFormatModifierProperties + be the array found by calling flink:vkGetPhysicalDeviceFormatProperties2 + on the same pname:format as slink:VkImageCreateInfo::pname:format. + ** Let slink:VkDrmModifierPropertiesEXT be the array element + whose pname:drmFormatModifier member + is the value of the image's DRM format modifier. + ** Then the image set of _format features_ + is the value of slink:VkDrmFormatModifierPropertiesEXT::drmFormatModifierTilingFeatures. +endif::VK_EXT_image_drm_format_modifier[] ifdef::VK_NV_corner_sampled_image[] [[resources-images-corner-sampled]] @@ -1930,8 +2233,9 @@ guaranteed to preserve that data. For either of these initial layouts, any image subresources must: be transitioned to another layout before they are accessed by the device. -Host access to image memory is only well-defined for images created with -ename:VK_IMAGE_TILING_LINEAR tiling and for image subresources of those +Host access to image memory is only well-defined +for <<glossary-linear-resource>> images +and for image subresources of those images which are currently in either the ename:VK_IMAGE_LAYOUT_PREINITIALIZED or ename:VK_IMAGE_LAYOUT_GENERAL layout. @@ -1964,7 +2268,8 @@ The type(s) of device access supported by each layout are: written to memory immediately, without first executing a layout transition. Currently, ename:VK_IMAGE_LAYOUT_PREINITIALIZED is only useful with - ename:VK_IMAGE_TILING_LINEAR images because there is not a standard + <<glossary-linear-resource,linear>> images + because there is not a standard layout defined for ename:VK_IMAGE_TILING_OPTIMAL images. * ename:VK_IMAGE_LAYOUT_GENERAL supports all types of device access. * ename:VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL must: only be used as a @@ -2878,6 +3183,10 @@ ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] must: not include any of ename:VK_IMAGE_ASPECT_PLANE_0_BIT, ename:VK_IMAGE_ASPECT_PLANE_1_BIT, or ename:VK_IMAGE_ASPECT_PLANE_2_BIT endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] +ifdef::VK_EXT_image_drm_format_modifier[] + * pname:aspectMask must: not include etext:VK_IMAGE_ASPECT_MEMORY_PLANE___i___BIT_EXT + for any index __i__. +endif::VK_EXT_image_drm_format_modifier[] **** include::../validity/structs/VkImageSubresourceRange.txt[] @@ -3099,6 +3408,21 @@ ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] the Android hardware buffer that was imported to the slink:VkDeviceMemory to which the image is bound. endif::VK_ANDROID_external_memory_android_hardware_buffer[] +ifdef::VK_EXT_image_drm_format_modifier[] + * If the view's image was created + with ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then: + ** The image's DRM format modifier is the value + of slink:VkImageDrmFormatModifierListCreateInfoEXT::pname:drmFormatModifier + found by calling flink:vkGetImageDrmFormatModifierPropertiesEXT. + ** Let slink:VkDrmFormatModifierPropertiesListEXT::pname:pDrmFormatModifierProperties + be the array found by calling flink:vkGetPhysicalDeviceFormatProperties2 + on the same pname:format as slink:VkImageViewCreateInfo::pname:format. + ** Let slink:VkDrmModifierPropertiesEXT be the array element + whose pname:drmFormatModifier member + is the value of the image's DRM format modifier. + ** Then the image view's set of _format features_ + is the value of slink:VkDrmFormatModifierPropertiesEXT::drmFormatModifierTilingFeatures. +endif::VK_EXT_image_drm_format_modifier[] [[resources-association]] == Resource Memory Association @@ -3241,9 +3565,7 @@ flink:vkGetImageMemoryRequirements: * The pname:memoryTypeBits member always contains at least one bit set. * If pname:buffer is a sname:VkBuffer not created with the ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT bit set, or if pname:image is - a sname:VkImage that was created with a ename:VK_IMAGE_TILING_LINEAR - value in the pname:tiling member of the sname:VkImageCreateInfo - structure passed to fname:vkCreateImage, then the pname:memoryTypeBits + <<glossary-linear-resource,linear>> image, then the pname:memoryTypeBits member always contains at least one bit set corresponding to a sname:VkMemoryType with a pname:propertyFlags that has both the ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT bit and the @@ -3465,15 +3787,31 @@ ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] ename:VK_IMAGE_CREATE_DISJOINT_BIT flag, there must: be a slink:VkImagePlaneMemoryRequirementsInfo in the pname:pNext chain of the slink:VkImageMemoryRequirementsInfo2 structure +ifdef::VK_EXT_image_drm_format_modifier[] + * If pname:image was created + with ename:VK_IMAGE_CREATE_DISJOINT_BIT and + with ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, + then there must: be a + slink:VkImagePlaneMemoryRequirementsInfo in the pname:pNext chain of the + slink:VkImageMemoryRequirementsInfo2 structure +endif::VK_EXT_image_drm_format_modifier[] * [[VUID-VkImageMemoryRequirementsInfo2-image-01590]] If pname:image was not created with the ename:VK_IMAGE_CREATE_DISJOINT_BIT flag, there must: not be a slink:VkImagePlaneMemoryRequirementsInfo in the pname:pNext chain of the slink:VkImageMemoryRequirementsInfo2 structure +ifndef::VK_EXT_image_drm_format_modifier[] * [[VUID-VkImageMemoryRequirementsInfo2-image-01591]] If pname:image was created with a single-plane format, there must: not be a slink:VkImagePlaneMemoryRequirementsInfo in the pname:pNext chain of the slink:VkImageMemoryRequirementsInfo2 structure +endif::VK_EXT_image_drm_format_modifier[] +ifdef::VK_EXT_image_drm_format_modifier[] + * If pname:image was created with a single-plane format and with any + pname:tiling other than ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then + there must: not be a slink:VkImagePlaneMemoryRequirementsInfo in the + pname:pNext chain of the slink:VkImageMemoryRequirementsInfo2 structure +endif::VK_EXT_image_drm_format_modifier[] ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] * [[VUID-VkImageMemoryRequirementsInfo2-image-01897]] If pname:image was created with the @@ -3512,13 +3850,24 @@ endif::VK_KHR_sampler_ycbcr_conversion[] .Valid Usage **** - * [[VUID-VkImagePlaneMemoryRequirementsInfo-planeAspect-01592]] - pname:planeAspect must: be an aspect that exists in the format; that is, - for a two-plane image pname:planeAspect must: be + * If the image's tiling is ename:VK_IMAGE_TILING_LINEAR + or ename:VK_IMAGE_TILING_OPTIMAL, then + pname:planeAspect must: be a single valid + _format plane_ for the image. + (That is, for a two-plane image pname:planeAspect must: be ename:VK_IMAGE_ASPECT_PLANE_0_BIT or ename:VK_IMAGE_ASPECT_PLANE_1_BIT, and for a three-plane image pname:planeAspect must: be ename:VK_IMAGE_ASPECT_PLANE_0_BIT, ename:VK_IMAGE_ASPECT_PLANE_1_BIT or - ename:VK_IMAGE_ASPECT_PLANE_2_BIT + ename:VK_IMAGE_ASPECT_PLANE_2_BIT). +ifdef::VK_EXT_image_drm_format_modifier[] + * If the image's tiling is ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, + then pname:planeAspect must: be a single valid _memory plane_ for the image. + (That is, pname:aspectMask must: specify a plane index that is less than + the <<VkDrmFormatModifierPropertiesEXT,pname:drmFormatModifierPlaneCount>> + associated with the image's + <<VkImageCreateInfo,pname:format>> and + <<VkImageDrmFormatModifierPropertiesEXT,pname:drmFormatModifier>>.) +endif::VK_EXT_image_drm_format_modifier[] **** include::../validity/structs/VkImagePlaneMemoryRequirementsInfo.txt[] @@ -4436,13 +4785,24 @@ endif::VK_KHR_sampler_ycbcr_conversion[] .Valid Usage **** - * [[VUID-VkBindImagePlaneMemoryInfo-planeAspect-01642]] - pname:planeAspect must: be a single valid plane aspect for the image - format (that is, pname:planeAspect must: be + * If the image's tiling is ename:VK_IMAGE_TILING_LINEAR + or ename:VK_IMAGE_TILING_OPTIMAL, then + pname:planeAspect must: be a single valid + _format plane_ for the image. + (That is, pname:planeAspect must: be ename:VK_IMAGE_ASPECT_PLANE_0_BIT or ename:VK_IMAGE_ASPECT_PLANE_1_BIT for "`etext:_2PLANE`" formats and pname:planeAspect must: be ename:VK_IMAGE_ASPECT_PLANE_0_BIT, ename:VK_IMAGE_ASPECT_PLANE_1_BIT, or - ename:VK_IMAGE_ASPECT_PLANE_2_BIT for "`etext:_3PLANE`" formats) + ename:VK_IMAGE_ASPECT_PLANE_2_BIT for "`etext:_3PLANE`" formats.) +ifdef::VK_EXT_image_drm_format_modifier[] + * If the image's tiling is ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, + then pname:planeAspect must: be a single valid _memory plane_ for the image. + (That is, pname:aspectMask must: specify a plane index that is less than + the <<VkDrmFormatModifierPropertiesEXT,pname:drmFormatModifierPlaneCount>> + associated with the image's + <<VkImageCreateInfo,pname:format>> and + <<VkImageDrmFormatModifierPropertiesEXT,pname:drmFormatModifier>>.) +endif::VK_EXT_image_drm_format_modifier[] * [[VUID-VkBindImagePlaneMemoryInfo-None-01643]] A single call to flink:vkBindImageMemory2 must: bind all or none of the planes of an image (i.e. bindings to all planes of an image must: be @@ -4681,7 +5041,7 @@ of an application, if some large resources are used for disjoint periods of time. ==== -When an <<glossary-linear-resource,non-linear>>, +When a <<glossary-linear-resource,non-linear>>, non-ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT image is bound to an aliased range, all image subresources of the image _overlap_ the range. @@ -4743,6 +5103,10 @@ endif::VK_VERSION_1_1,VK_KHR_device_group[] from the multi-planar image's dimensions in the manner listed for <<features-formats-compatible-planes,plane compatibility>> for the aliased plane. +ifdef::VK_EXT_image_drm_format_modifier[] + * If either image's pname:tiling is ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, + then both images must: be <<glossary-linear-resource,linear>>. +endif::VK_EXT_image_drm_format_modifier[] * All other creation parameters must: be identical endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] diff --git a/include/vulkan/vulkan_core.h b/include/vulkan/vulkan_core.h index 2d1b3f5..f6cb898 100644 --- a/include/vulkan/vulkan_core.h +++ b/include/vulkan/vulkan_core.h @@ -147,6 +147,7 @@ typedef enum VkResult { VK_ERROR_INCOMPATIBLE_DISPLAY_KHR = -1000003001, VK_ERROR_VALIDATION_FAILED_EXT = -1000011001, VK_ERROR_INVALID_SHADER_NV = -1000012000, + VK_ERROR_INVALID_DRM_FORMAT_MODIFIER_PLANE_LAYOUT_EXT = -1000158000, VK_ERROR_FRAGMENTATION_EXT = -1000161000, VK_ERROR_NOT_PERMITTED_EXT = -1000174001, VK_ERROR_OUT_OF_POOL_MEMORY_KHR = VK_ERROR_OUT_OF_POOL_MEMORY, @@ -398,6 +399,12 @@ typedef enum VkStructureType { VK_STRUCTURE_TYPE_PIPELINE_COLOR_BLEND_ADVANCED_STATE_CREATE_INFO_EXT = 1000148002, VK_STRUCTURE_TYPE_PIPELINE_COVERAGE_TO_COLOR_STATE_CREATE_INFO_NV = 1000149000, VK_STRUCTURE_TYPE_PIPELINE_COVERAGE_MODULATION_STATE_CREATE_INFO_NV = 1000152000, + VK_STRUCTURE_TYPE_DRM_FORMAT_MODIFIER_PROPERTIES_LIST_EXT = 1000158000, + VK_STRUCTURE_TYPE_DRM_FORMAT_MODIFIER_PROPERTIES_EXT = 1000158001, + VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_DRM_FORMAT_MODIFIER_INFO_EXT = 1000158002, + VK_STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_LIST_CREATE_INFO_EXT = 1000158003, + VK_STRUCTURE_TYPE_IMAGE_EXCPLICIT_DRM_FORMAT_MODIFIER_CREATE_INFO_EXT = 1000158004, + VK_STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_PROPERTIES_EXT = 1000158005, VK_STRUCTURE_TYPE_VALIDATION_CACHE_CREATE_INFO_EXT = 1000160000, VK_STRUCTURE_TYPE_SHADER_MODULE_VALIDATION_CACHE_CREATE_INFO_EXT = 1000160001, VK_STRUCTURE_TYPE_DESCRIPTOR_SET_LAYOUT_BINDING_FLAGS_CREATE_INFO_EXT = 1000161000, @@ -809,6 +816,7 @@ typedef enum VkImageType { typedef enum VkImageTiling { VK_IMAGE_TILING_OPTIMAL = 0, VK_IMAGE_TILING_LINEAR = 1, + VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT = 1000158000, VK_IMAGE_TILING_BEGIN_RANGE = VK_IMAGE_TILING_OPTIMAL, VK_IMAGE_TILING_END_RANGE = VK_IMAGE_TILING_LINEAR, VK_IMAGE_TILING_RANGE_SIZE = (VK_IMAGE_TILING_LINEAR - VK_IMAGE_TILING_OPTIMAL + 1), @@ -1445,6 +1453,10 @@ typedef enum VkImageAspectFlagBits { VK_IMAGE_ASPECT_PLANE_0_BIT = 0x00000010, VK_IMAGE_ASPECT_PLANE_1_BIT = 0x00000020, VK_IMAGE_ASPECT_PLANE_2_BIT = 0x00000040, + VK_IMAGE_ASPECT_MEMORY_PLANE_0_BIT_EXT = 0x00000080, + VK_IMAGE_ASPECT_MEMORY_PLANE_1_BIT_EXT = 0x00000100, + VK_IMAGE_ASPECT_MEMORY_PLANE_2_BIT_EXT = 0x00000200, + VK_IMAGE_ASPECT_MEMORY_PLANE_3_BIT_EXT = 0x00000400, VK_IMAGE_ASPECT_PLANE_0_BIT_KHR = VK_IMAGE_ASPECT_PLANE_0_BIT, VK_IMAGE_ASPECT_PLANE_1_BIT_KHR = VK_IMAGE_ASPECT_PLANE_1_BIT, VK_IMAGE_ASPECT_PLANE_2_BIT_KHR = VK_IMAGE_ASPECT_PLANE_2_BIT, @@ -7620,6 +7632,62 @@ typedef struct VkPipelineCoverageModulationStateCreateInfoNV { #define VK_EXT_POST_DEPTH_COVERAGE_EXTENSION_NAME "VK_EXT_post_depth_coverage" +#define VK_EXT_image_drm_format_modifier 1 +#define VK_EXT_EXTENSION_159_SPEC_VERSION 0 +#define VK_EXT_EXTENSION_159_EXTENSION_NAME "VK_EXT_extension_159" +#define VK_EXT_IMAGE_DRM_FORMAT_MODIFIER_SPEC_VERSION 1 +#define VK_EXT_IMAGE_DRM_FORMAT_MODIFIER_EXTENSION_NAME "VK_EXT_image_drm_format_modifier" + +typedef struct VkDrmFormatModifierPropertiesEXT { + uint64_t drmFormatModifier; + uint32_t drmFormatModifierPlaneCount; + VkFormatFeatureFlags drmFormatModifierTilingFeatures; +} VkDrmFormatModifierPropertiesEXT; + +typedef struct VkDrmFormatModifierPropertiesListEXT { + VkStructureType sType; + void* pNext; + uint32_t drmFormatModifierCount; + VkDrmFormatModifierPropertiesEXT* pDrmFormatModifierProperties; +} VkDrmFormatModifierPropertiesListEXT; + +typedef struct VkPhysicalDeviceImageDrmFormatModifierInfoEXT { + VkStructureType sType; + const void* pNext; + uint64_t drmFormatModifier; +} VkPhysicalDeviceImageDrmFormatModifierInfoEXT; + +typedef struct VkImageDrmFormatModifierListCreateInfoEXT { + VkStructureType sType; + const void* pNext; + uint32_t drmFormatModifierCount; + const uint64_t* pDrmFormatModifiers; +} VkImageDrmFormatModifierListCreateInfoEXT; + +typedef struct VkImageDrmFormatModifierExplicitCreateInfoEXT { + VkStructureType sType; + const void* pNext; + uint64_t drmFormatModifier; + uint32_t drmFormatModifierPlaneCount; + const VkSubresourceLayout* pPlaneLayouts; +} VkImageDrmFormatModifierExplicitCreateInfoEXT; + +typedef struct VkImageDrmFormatModifierPropertiesEXT { + VkStructureType sType; + void* pNext; + uint64_t drmFormatModifier; +} VkImageDrmFormatModifierPropertiesEXT; + + +typedef VkResult (VKAPI_PTR *PFN_vkGetImageDrmFormatModifierPropertiesEXT)(VkDevice device, VkImage image, VkImageDrmFormatModifierPropertiesEXT* pProperties); + +#ifndef VK_NO_PROTOTYPES +VKAPI_ATTR VkResult VKAPI_CALL vkGetImageDrmFormatModifierPropertiesEXT( + VkDevice device, + VkImage image, + VkImageDrmFormatModifierPropertiesEXT* pProperties); +#endif + #define VK_EXT_validation_cache 1 VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkValidationCacheEXT) @@ -3464,6 +3464,40 @@ server. <member><type>uint32_t</type> <name>maxRecursionDepth</name></member> <member><type>uint32_t</type> <name>maxGeometryCount</name></member> </type> + <type category="struct" name="VkDrmFormatModifierPropertiesListEXT" structextends="VkFormatProperties2"> + <member values="VK_STRUCTURE_TYPE_DRM_FORMAT_MODIFIER_PROPERTIES_LIST_EXT"><type>VkStructureType</type> <name>sType</name></member> + <member><type>void</type>* <name>pNext</name></member> + <member optional="true"><type>uint32_t</type> <name>drmFormatModifierCount</name></member> + <member optional="true,false" len="drmFormatModifierCount"><type>VkDrmFormatModifierPropertiesEXT</type>* <name>pDrmFormatModifierProperties</name></member> + </type> + <type category="struct" name="VkDrmFormatModifierPropertiesEXT" returnedonly="true"> + <member><type>uint64_t</type> <name>drmFormatModifier</name></member> + <member><type>uint32_t</type> <name>drmFormatModifierPlaneCount</name></member> + <member><type>VkFormatFeatureFlags</type> <name>drmFormatModifierTilingFeatures</name></member> + </type> + <type category="struct" name="VkPhysicalDeviceImageDrmFormatModifierInfoEXT" structextends="VkPhysicalDeviceImageFormatInfo2"> + <member values="VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_DRM_FORMAT_MODIFIER_INFO_EXT"><type>VkStructureType</type> <name>sType</name></member> + <member>const <type>void</type>* <name>pNext</name></member> + <member><type>uint64_t</type> <name>drmFormatModifier</name></member> + </type> + <type category="struct" name="VkImageDrmFormatModifierListCreateInfoEXT" structextends="VkImageCreateInfo"> + <member values="VK_STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_LIST_CREATE_INFO_EXT"><type>VkStructureType</type> <name>sType</name></member> + <member>const <type>void</type>* <name>pNext</name></member> + <member><type>uint32_t</type> <name>drmFormatModifierCount</name></member> + <member len="drmFormatModifierCount">const <type>uint64_t</type>* <name>pDrmFormatModifiers</name></member> + </type> + <type category="struct" name="VkImageDrmFormatModifierExplicitCreateInfoEXT" structextends="VkImageCreateInfo"> + <member values="VK_STRUCTURE_TYPE_IMAGE_EXCPLICIT_DRM_FORMAT_MODIFIER_CREATE_INFO_EXT"><type>VkStructureType</type> <name>sType</name></member> + <member>const <type>void</type>* <name>pNext</name></member> + <member><type>uint64_t</type> <name>drmFormatModifier</name></member> + <member optional="false"><type>uint32_t</type> <name>drmFormatModifierPlaneCount</name></member> + <member len="drmFormatModifierPlaneCount">const <type>VkSubresourceLayout</type>* <name>pPlaneLayouts</name></member> + </type> + <type category="struct" name="VkImageDrmFormatModifierPropertiesEXT" returnedonly="true"> + <member values="VK_STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_PROPERTIES_EXT"><type>VkStructureType</type> <name>sType</name></member> + <member><type>void</type>* <name>pNext</name></member> + <member><type>uint64_t</type> <name>drmFormatModifier</name></member> + </type> </types> <comment>Vulkan enumerant (token) definitions</comment> @@ -6726,6 +6760,12 @@ server. <param optional="true">const <type>VkAllocationCallbacks</type>* <name>pAllocator</name></param> <param len="createInfoCount"><type>VkPipeline</type>* <name>pPipelines</name></param> </command> + <command> + <proto><type>VkResult</type> <name>vkGetImageDrmFormatModifierPropertiesEXT</name></proto> + <param><type>VkDevice</type> <name>device</name></param> + <param><type>VkImage</type> <name>image</name></param> + <param><type>VkImageDrmFormatModifierPropertiesEXT</type>* <name>pProperties</name></param> + </command> </commands> <feature api="vulkan" name="VK_VERSION_1_0" number="1.0" comment="Vulkan core API interface definitions"> @@ -9115,10 +9155,38 @@ server. <type name="VkBindImageMemoryInfoKHR"/> </require> </extension> - <extension name="VK_EXT_extension_159" number="159" author="EXT" contact="Chad Versace @chadversary" supported="disabled"> + <extension name="VK_EXT_image_drm_format_modifier" number="159" type="device" requires="VK_KHR_bind_memory2,VK_KHR_get_physical_device_properties2,VK_KHR_sampler_ycbcr_conversion" author="EXT" contact="Chad Versace @chadversary" supported="vulkan"> <require> <enum value="0" name="VK_EXT_EXTENSION_159_SPEC_VERSION"/> <enum value=""VK_EXT_extension_159"" name="VK_EXT_EXTENSION_159_EXTENSION_NAME"/> + + <enum value="1" name="VK_EXT_IMAGE_DRM_FORMAT_MODIFIER_SPEC_VERSION"/> + <enum value=""VK_EXT_image_drm_format_modifier"" name="VK_EXT_IMAGE_DRM_FORMAT_MODIFIER_EXTENSION_NAME"/> + + <enum offset="0" dir="-" extends="VkResult" name="VK_ERROR_INVALID_DRM_FORMAT_MODIFIER_PLANE_LAYOUT_EXT"/> + + <enum offset="0" extends="VkStructureType" name="VK_STRUCTURE_TYPE_DRM_FORMAT_MODIFIER_PROPERTIES_LIST_EXT"/> + <enum offset="1" extends="VkStructureType" name="VK_STRUCTURE_TYPE_DRM_FORMAT_MODIFIER_PROPERTIES_EXT"/> + <enum offset="2" extends="VkStructureType" name="VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_IMAGE_DRM_FORMAT_MODIFIER_INFO_EXT"/> + <enum offset="3" extends="VkStructureType" name="VK_STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_LIST_CREATE_INFO_EXT"/> + <enum offset="4" extends="VkStructureType" name="VK_STRUCTURE_TYPE_IMAGE_EXCPLICIT_DRM_FORMAT_MODIFIER_CREATE_INFO_EXT"/> + <enum offset="5" extends="VkStructureType" name="VK_STRUCTURE_TYPE_IMAGE_DRM_FORMAT_MODIFIER_PROPERTIES_EXT"/> + + <enum offset="0" extends="VkImageTiling" name="VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT"/> + + <enum bitpos="7" extends="VkImageAspectFlagBits" name="VK_IMAGE_ASPECT_MEMORY_PLANE_0_BIT_EXT"/> + <enum bitpos="8" extends="VkImageAspectFlagBits" name="VK_IMAGE_ASPECT_MEMORY_PLANE_1_BIT_EXT"/> + <enum bitpos="9" extends="VkImageAspectFlagBits" name="VK_IMAGE_ASPECT_MEMORY_PLANE_2_BIT_EXT"/> + <enum bitpos="10" extends="VkImageAspectFlagBits" name="VK_IMAGE_ASPECT_MEMORY_PLANE_3_BIT_EXT"/> + + <type name="VkDrmFormatModifierPropertiesListEXT"/> + <type name="VkDrmFormatModifierPropertiesEXT"/> + <type name="VkPhysicalDeviceImageDrmFormatModifierInfoEXT"/> + <type name="VkImageDrmFormatModifierListCreateInfoEXT"/> + <type name="VkImageDrmFormatModifierExplicitCreateInfoEXT"/> + <type name="VkImageDrmFormatModifierPropertiesEXT"/> + + <command name="vkGetImageDrmFormatModifierPropertiesEXT"/> </require> </extension> <extension name="VK_EXT_extension_160" number="160" author="EXT" contact="Mark Young @marky-lunarg" supported="disabled"> |