From 7ea62a02a910ba4dfe0dfa2c7ef464f731d1453c Mon Sep 17 00:00:00 2001 From: Jon Leech Date: Sat, 29 Sep 2018 03:23:41 -0700 Subject: [PATCH] Change log for September 29, 2018 Vulkan 1.1.86 spec update: * Update release number to 86. Internal Issues: * Add new <> section and reference that from valid usage statements, reducing combinatorial complexity of extension-dependent VUs. Also fixes some underspecified limits (such as pname:maxMipLevels) in the VUs for slink:VkImageCreateInfo when slink:VkExternalMemoryImageCreateInfo::pname:externalMemoryHandles contains multiple bits, and fixes incorrectly (and underspecified) limits when an Android external format is used (internal issue 1370). * Remove unused "`Fragment Area Granularity`" glossary entry accidentally introduced in the 1.1.85 update. New Extensions: * `VK_KHR_driver_properties` * `VK_KHR_shader_atomic_int64` * The specification sources contain text for another extension, `VK_EXT_image_drm_format_modifier`, but this extension is not yet complete, and is marked disabled in `vk.xml`. The extension will be enabled, and become part of the spec, only when the authors decide it is ready. --- ChangeLog.txt | 29 + Makefile | 2 +- .../VK_EXT_image_drm_format_modifier.txt | 435 ++++++++ appendices/VK_KHR_driver_properties.txt | 61 ++ appendices/VK_KHR_shader_atomic_int64.txt | 44 + appendices/glossary.txt | 47 +- appendices/spirvenv.txt | 22 +- chapters/VK_NVX_raytracing/raytracing.txt | 16 +- chapters/clears.txt | 5 + chapters/copies.txt | 5 + chapters/devsandqueues.txt | 72 ++ chapters/features.txt | 254 ++++- chapters/renderpass.txt | 5 + chapters/resources.txt | 953 ++++++++++++------ include/vulkan/vulkan_core.h | 74 +- reflow_count.py | 2 +- xml/vk.xml | 241 ++++- 17 files changed, 1926 insertions(+), 341 deletions(-) create mode 100644 appendices/VK_EXT_image_drm_format_modifier.txt create mode 100644 appendices/VK_KHR_driver_properties.txt create mode 100644 appendices/VK_KHR_shader_atomic_int64.txt diff --git a/ChangeLog.txt b/ChangeLog.txt index e3105bc6..c5e101a9 100644 --- a/ChangeLog.txt +++ b/ChangeLog.txt @@ -8,6 +8,35 @@ public pull requests that have been accepted. ----------------------------------------------------- +Change log for September 29, 2018 Vulkan 1.1.86 spec update: + + * Update release number to 86. + +Internal Issues: + + * Add new <> + section and reference that from valid usage statements, reducing + combinatorial complexity of extension-dependent VUs. Also fixes some + underspecified limits (such as pname:maxMipLevels) in the VUs for + slink:VkImageCreateInfo when + slink:VkExternalMemoryImageCreateInfo::pname:externalMemoryHandles + contains multiple bits, and fixes incorrectly (and underspecified) + limits when an Android external format is used (internal issue 1370). + * Remove unused "`Fragment Area Granularity`" glossary entry accidentally + introduced in the 1.1.85 update. + +New Extensions: + + * `VK_KHR_driver_properties` + * `VK_KHR_shader_atomic_int64` + * The specification sources contain text for another extension, + `VK_EXT_image_drm_format_modifier`, but this extension is not yet + complete, and is marked disabled in `vk.xml`. The extension will be + enabled, and become part of the spec, only when the authors decide it is + ready. + +----------------------------------------------------- + Change log for September 19, 2018 Vulkan 1.1.85 spec update: * Update release number to 85. diff --git a/Makefile b/Makefile index 94a25d59..2881e254 100644 --- a/Makefile +++ b/Makefile @@ -107,7 +107,7 @@ VERBOSE = # EXTRAATTRIBS sets additional attributes, if passed to make # ADOCOPTS options for asciidoc->HTML5 output NOTEOPTS = -a editing-notes -a implementation-guide -PATCHVERSION = 85 +PATCHVERSION = 86 ifneq (,$(findstring VK_VERSION_1_1,$(VERSIONS))) SPECREVISION = 1.1.$(PATCHVERSION) else 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 00000000..383f2ee9 --- /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`^<>^ +and +`EGL_MESA_image_dma_buf_export`^<>^. +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 + <>, <>, + and <> 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`^<>^ +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`^<>^ +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`^<>^ 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`^<>^, 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`^<>^; +and symmetrically allows exporting the same data from the `gbm_bo`. See the +references to _modifier_ and _plane_ in +`gbm.h`^<>^. + + +=== 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`^<>^, +`struct drm_mode_fb_cmd2`^<>^, and +`struct gbm_import_fd_modifier_data`^<>^, +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::<> +must: be 0. + +*DISCUSSION.* +Prior art, such as +`EGL_EXT_image_dma_buf_import_modifiers`^<>^, +`struct drm_mode_fb_cmd2`^<>^, and +`struct gbm_import_fd_modifier_data`^<>^, 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/VK_KHR_driver_properties.txt b/appendices/VK_KHR_driver_properties.txt new file mode 100644 index 00000000..a433d9d2 --- /dev/null +++ b/appendices/VK_KHR_driver_properties.txt @@ -0,0 +1,61 @@ +// Copyright (c) 2016-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_KHR_driver_properties.txt[] + +*Last Modified Date*:: + 2018-04-11 +*IP Status*:: + No known IP claims. +*Contributors*:: + - Baldur Karlsson + - Matthaeus G. Chajdas, AMD + - Piers Daniell, NVIDIA + - Alexander Galazin, Arm + - Jesse Hall, Google + - Daniel Rakos, AMD + +This extension provides a new physical device query which allows retrieving +information about the driver implementation, allowing applications to +determine which physical device corresponds to which particular vendor's +driver, and which conformance test suite version the driver implementation +is compliant with. + +=== New Object Types + +None. + +=== New Enum Constants + + * Extending elink:VkStructureType: + ** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DRIVER_PROPERTIES_KHR + + * ename:VK_MAX_DRIVER_NAME_SIZE_KHR + * ename:VK_MAX_DRIVER_INFO_SIZE_KHR + +=== New Enums + +None. + +=== New Structures + + * slink:VkConformanceVersionKHR + * slink:VkPhysicalDeviceDriverPropertiesKHR + +=== New Functions + +None. + +=== Issues + +None. + +=== Examples + +None. + +=== Version History + + * Revision 1, 2018-04-11 (Daniel Rakos) + - Internal revisions diff --git a/appendices/VK_KHR_shader_atomic_int64.txt b/appendices/VK_KHR_shader_atomic_int64.txt new file mode 100644 index 00000000..4c0d4b67 --- /dev/null +++ b/appendices/VK_KHR_shader_atomic_int64.txt @@ -0,0 +1,44 @@ +// Copyright (c) 2014-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_KHR_shader_atomic_int64.txt[] + +*Last Modified Data*:: + 2018-07-05 +*Interactions and External Dependencies*:: + - This extension requires the + https://www.khronos.org/registry/OpenGL/extensions/ARB/ARB_gpu_shader_int64.txt[+GL_ARB_gpu_shader_int64+] + and + https://github.com/KhronosGroup/GLSL/tree/master/extensions/ext/GL_EXT_shader_atomic_int64.txt[+GL_EXT_shader_atomic_int64+] + extensions for GLSL source languages. +*Contributors*:: + - Aaron Hagan, AMD + - Daniel Rakos, AMD + - Jeff Bolz, NVIDIA + - Neil Henning, Codeplay + +This extension advertises the SPIR-V *Int64Atomics* capability for Vulkan, +which allows a shader to contain 64-bit atomic operations on signed and +unsigned integers. +The supported operations include OpAtomicMin, OpAtomicMax, OpAtomicAnd, +OpAtomicOr, OpAtomicXor, OpAtomicAdd, OpAtomicExchange, and +OpAtomicCompSwap. + +=== New Enum Constants + + * Extending elink:VkStructureType: + ** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_ATOMIC_INT64_FEATURES_KHR + +=== New SPIR-V Capabilities + + * <> + +=== New Structures + + * slink:VkPhysicalDeviceShaderAtomicInt64FeaturesKHR + +=== Version History + + * Revision 1, 2018-07-05 (Aaron Hagan) + - Internal revisions diff --git a/appendices/glossary.txt b/appendices/glossary.txt index 52db7b2c..f0919023 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 @@ -496,11 +499,6 @@ Fragment:: Fragment Area:: The width and height, in pixels, of a fragment. -[[glossary-fragment-area-granularity]] -Fragment Area Granularity:: - The framebuffer granularity in x and y for which unique fragment areas - may: be specified. - Fragment Input Attachment Interface:: Variables with code:UniformConstant storage class and a decoration of code:InputAttachmentIndex that are statically used by a fragment @@ -777,10 +775,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 <> + 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 <> + 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 + <>. +endif::VK_EXT_image_drm_format_modifier[] Local Workgroup:: A collection of compute shader invocations invoked by a single dispatch diff --git a/appendices/spirvenv.txt b/appendices/spirvenv.txt index f0ccb2aa..0f441002 100755 --- a/appendices/spirvenv.txt +++ b/appendices/spirvenv.txt @@ -60,6 +60,10 @@ with that capability. | code:Tessellation | <> | code:Float64 | <> | code:Int64 | <> +ifdef::VK_KHR_shader_atomic_int64[] +[[spirvenv-capabilities-table-int64atomics]] +| code:Int64Atomics | <> +endif::VK_KHR_shader_atomic_int64[] | code:Int16 | <> | code:TessellationPointSize | <> | code:GeometryPointSize | <> @@ -600,8 +604,20 @@ ifdef::VK_VERSION_1_1[] ** *InclusiveScan* ** *ExclusiveScan* endif::VK_VERSION_1_1[] - * Atomic instructions must: declare a scalar 32-bit integer type for the - _Result Type_ and the type of the value pointed to by _Pointer_. + * Atomic instructions must: declare a scalar 32-bit integer type, +ifdef::VK_KHR_shader_atomic_int64[] + or a scalar 64-bit integer type if the code:Int64Atomics capability is + enabled, +endif::VK_KHR_shader_atomic_int64[] + for the _Result Type_ and the type of the value pointed to by _Pointer_. +ifdef::VK_KHR_shader_atomic_int64[] + ** <> + must: be enabled for 64-bit integer atomic operations to be supported + on buffers. + ** <> + must: be enabled for 64-bit integer atomic operations to be supported + on shared variables. +endif::VK_KHR_shader_atomic_int64[] ifdef::VK_EXT_descriptor_indexing[] * If an instruction loads from or stores to a resource (including atomics and image instructions) and the resource descriptor being accessed is @@ -679,7 +695,7 @@ any result, otherwise let the largest permitted value in any of the ranges be [eq]#F~max~# and the smallest be [eq]#F~min~#. The operation must return a value in the range [eq]#[x - E, x + E]# where latexmath:[E = \mathrm{max} \left( | x - F_{\mathrm{min}} |, | x - -F_{\mathrm{max}} | \right) ] +F_{\mathrm{max}} | \right) ]. For single precision (32 bit) instructions, precisions are required: to be at least as follows, unless decorated with RelaxedPrecision: diff --git a/chapters/VK_NVX_raytracing/raytracing.txt b/chapters/VK_NVX_raytracing/raytracing.txt index 3bc27199..270c42bd 100644 --- a/chapters/VK_NVX_raytracing/raytracing.txt +++ b/chapters/VK_NVX_raytracing/raytracing.txt @@ -316,7 +316,7 @@ performance. Before copying, an application must: query the size of the resulting acceleration structure. -[open,refpage='vkCmdWriteAccelerationStructurePropertiesNVX',desc='Copy an acceleration structure',type='protos'] +[open,refpage='vkCmdWriteAccelerationStructurePropertiesNVX',desc='Write acceleration structure result parameters to query results.',type='protos'] -- To query acceleration structure size parameters call: @@ -376,8 +376,16 @@ specifying additional operations to perform during the copy, are: include::../../api/enums/VkCopyAccelerationStructureModeNVX.txt[] -// Needs to be filled in -// * ename:VK_COPY_ACCELERATION_STRUCTURE_MODE_CLONE_NVX specifies ... -// * ename:VK_COPY_ACCELERATION_STRUCTURE_MODE_COMPACT_NVX specifies ... + * ename:VK_COPY_ACCELERATION_STRUCTURE_MODE_CLONE_NVX creates a direct + copy of the acceleration structure specified in pname:src into the one + specified by pname:dst. + The pname:dst acceleration structure must: have been created with the + same parameters as pname:src. + * ename:VK_COPY_ACCELERATION_STRUCTURE_MODE_COMPACT_NVX creates a more + compact version of an acceleration structure pname:src into pname:dst. + The acceleration structure pname:dst must: have been created with a + pname:compactedSize corresponding to the one returned by + slink:vkCmdWriteAccelerationStructurePropertiesNVX after the build of + the acceleration structure specified by pname:src. -- diff --git a/chapters/clears.txt b/chapters/clears.txt index 92acd57b..154ca86d 100644 --- a/chapters/clears.txt +++ b/chapters/clears.txt @@ -324,6 +324,11 @@ 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[] + * [[VUID-VkClearAttachment-aspectMask-02246]] + 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 81958094..b76bfbe9 100644 --- a/chapters/copies.txt +++ b/chapters/copies.txt @@ -801,6 +801,11 @@ 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[] + * [[VUID-VkImageSubresourceLayers-aspectMask-02247]] + 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/devsandqueues.txt b/chapters/devsandqueues.txt index 4befe21d..264a2ccd 100644 --- a/chapters/devsandqueues.txt +++ b/chapters/devsandqueues.txt @@ -392,6 +392,78 @@ include::../validity/structs/VkPhysicalDeviceIDProperties.txt[] endif::VK_VERSION_1_1,VK_KHR_external_memory_capabilities,VK_KHR_external_semaphore_capabilities,VK_KHR_external_fence_capabilities[] +ifdef::VK_KHR_driver_properties[] + +[open,refpage='VkPhysicalDeviceDriverPropertiesKHR',desc='Structure containing driver identification information',type='structs'] +-- + +To query the properties of the driver corresponding to a physical device, +add slink:VkPhysicalDeviceDriverPropertiesKHR to the pname:pNext chain of +the slink:VkPhysicalDeviceProperties2 structure. +The sname:VkPhysicalDeviceDriverPropertiesKHR structure is defined as: + +include::../api/structs/VkPhysicalDeviceDriverPropertiesKHR.txt[] + + * pname:sType is the type of this structure. + * pname:pNext is `NULL` or a pointer to an extension specific structure. + * pname:driverID is a unique identifier for the driver of the physical + device. + * pname:driverName is a null-terminated UTF-8 string containing the name + of the driver. + * pname:driverInfo is a null-terminated UTF-8 string containing additional + information about the driver. + * pname:conformanceVersion is the version of the Vulkan conformance test + this driver is conformant against (see slink:VkConformanceVersionKHR). + +pname:driverID must: be immutable for a given driver across instances, +processes, driver versions, and system reboots. + +include::../validity/structs/VkPhysicalDeviceDriverPropertiesKHR.txt[] +-- + +[open,refpage='VkDriverIdKHR',desc='Khronos driver IDs',type='enums'] +-- +Khronos driver IDs which may: be returned in +slink:VkPhysicalDeviceDriverPropertiesKHR::pname:driverID are: + +include::../api/enums/VkDriverIdKHR.txt[] + +[NOTE] +.Note +==== +Khronos driver IDs may be allocated by vendors at any time. +There may be multiple driver IDs for the same vendor, representing different +drivers (for e.g. different platforms, proprietary or open source, etc.). +Only the latest canonical versions of this Specification, of the +corresponding `vk.xml` API Registry, and of the corresponding +`vulkan_core.h` header file must: contain all reserved Khronos driver IDs. + +Only driver IDs registered with Khronos are given symbolic names. +There may: be unregistered driver IDs returned. +==== + +-- + +[open,refpage='VkConformanceVersionKHR',desc='Structure containing the conformance test suite version the implementation is compliant with',type='structs'] +-- + +The conformance test suite version an implementation is compliant with is +described with an instance of the sname:VkConformanceVersionKHR structure. +The sname:VkConformanceVersionKHR structure is defined as: + +include::../api/structs/VkConformanceVersionKHR.txt[] + + * pname:major is the major version number of the conformance test suite. + * pname:minor is the minor version number of the conformance test suite. + * pname:subminor is the subminor version number of the conformance test + suite. + * pname:patch is the patch version number of the conformance test suite. + +include::../validity/structs/VkConformanceVersionKHR.txt[] +-- + +endif::VK_KHR_driver_properties[] + endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] [open,refpage='vkGetPhysicalDeviceQueueFamilyProperties',desc='Reports properties of the queues of the specified physical device',type='protos'] diff --git a/chapters/features.txt b/chapters/features.txt index b7a19a4f..d45a7199 100755 --- a/chapters/features.txt +++ b/chapters/features.txt @@ -877,6 +877,36 @@ include::../validity/structs/VkPhysicalDeviceMultiviewFeatures.txt[] endif::VK_VERSION_1_1,VK_KHR_multiview[] +ifdef::VK_KHR_shader_atomic_int64[] +[open,refpage='VkPhysicalDeviceShaderAtomicInt64FeaturesKHR',desc='Structure describing features supported by VK_KHR_shader_atomic_int64',type='structs'] +-- + +To query 64-bit atomic support for signed and unsigned integers call +flink:vkGetPhysicalDeviceFeatures2 with a +sname:VkPhysicalDeviceShaderAtomicInt64FeaturesKHR structure included in the +pname:pNext chain of its pname:pFeatures parameter. + +The slink:VkPhysicalDeviceShaderAtomicInt64FeaturesKHR structure is defined +as: + +include::../api/structs/VkPhysicalDeviceShaderAtomicInt64FeaturesKHR.txt[] + + * pname:sType is the type of this structure. + * pname:pNext is `NULL` or a pointer to an extension-specific structure. + * [[features-features-shaderBufferInt64Atomics]] + pname:shaderBufferInt64Atomics indicates whether shaders can: support + 64-bit unsigned and signed integer atomic operations on buffers. + * [[features-features-shaderSharedInt64Atomics]] + pname:shaderSharedInt64Atomics indicates whether shaders can: support + 64-bit unsigned and signed integer atomic operations on shared memory. + +include::../validity/structs/VkPhysicalDeviceShaderAtomicInt64FeaturesKHR.txt[] + +-- +endif::VK_KHR_shader_atomic_int64[] + + + ifdef::VK_KHR_8bit_storage[] [open,refpage='VkPhysicalDevice8BitStorageFeaturesKHR',desc='Structure describing features supported by VK_KHR_8bit_storage',type='structs'] -- @@ -6018,14 +6048,24 @@ 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[] +<>, +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 -<> or <> created with the queried +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 +<>, +endif::VK_EXT_image_drm_format_modifier[] +specifying that the features are supported by <> or +<> created with the queried flink:vkGetPhysicalDeviceFormatProperties::pname:format: * ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT specifies that an image view @@ -6223,8 +6263,135 @@ 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 <> 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 +<>. +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 +<> +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 <>, 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 <>, 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 +7068,15 @@ 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 +**** + * [[VUID-vkGetPhysicalDeviceImageFormatProperties-tiling-02248]] + 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 +7098,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 +7109,20 @@ 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 <>. @@ -7059,6 +7248,16 @@ 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 +**** + * [[VUID-VkPhysicalDeviceImageFormatInfo2KHR-tiling-02249]] + 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 +7643,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 +<>, 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 9e0ee4c0..f9a65075 100644 --- a/chapters/renderpass.txt +++ b/chapters/renderpass.txt @@ -583,6 +583,11 @@ 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[] + * [[VUID-VkInputAttachmentAspectReferenceKHR-aspectMask-02250]] + 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 7448c39f..1bee503b 100644 --- a/chapters/resources.txt +++ b/chapters/resources.txt @@ -608,38 +608,15 @@ supported unless other parameters meet all of the constraints: Implementations may: support additional limits and capabilities beyond those listed above. -To query an implementation's specific capabilities for a given combination -of pname:format, pname:imageType, pname:tiling, pname:usage, -ifdef::VK_VERSION_1_1,VK_KHR_external_memory_capabilities[] -slink:VkExternalMemoryImageCreateInfo::pname:handleTypes -endif::VK_VERSION_1_1,VK_KHR_external_memory_capabilities[] -and pname:flags, call -ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] -flink:vkGetPhysicalDeviceImageFormatProperties2. -endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] -ifndef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] -flink:vkGetPhysicalDeviceImageFormatProperties. -endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] -The return value specifies whether that combination of image settings is -supported. -On success, the sname:VkImageFormatProperties output parameter specifies the -set of valid pname:samples bits and the limits for pname:extent, -pname:mipLevels, pname:arrayLayers, and pname:maxResourceSize. -Even if -ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] -flink:vkGetPhysicalDeviceImageFormatProperties2. -endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] -ifndef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] -flink:vkGetPhysicalDeviceImageFormatProperties. -endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] -returns success and the parameters to fname:vkCreateImage are all within the -returned limits, fname:vkCreateImage must: fail and return -ename:VK_ERROR_OUT_OF_DEVICE_MEMORY if the resulting size of the image would -be larger than pname:maxResourceSize. - To determine the set of valid pname:usage bits for a given format, call flink:vkGetPhysicalDeviceFormatProperties. +If the size of the resultant image would exceed pname:maxResourceSize, then +fname:vkCreateImage must: fail and return +ename:VK_ERROR_OUT_OF_DEVICE_MEMORY. +This failure may: occur even when all image creation parameters satisfy +their valid usage requirements. + ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] [NOTE] .Note @@ -655,26 +632,222 @@ a sname:VkImageView created from the image can: have (see ==== endif::VK_VERSION_1_1,VK_KHR_maintenance2[] +[[resources-image-creation-limits]] +.Image Creation Limits +**** +Valid values for some image creation parameters are limited by a numerical +upper bound or by inclusion in a bitset. +For example, sname:VkImageCreateInfo::pname:arrayLayers is limited by +pname:imageCreateMaxArrayLayers, defined below; and +sname:VkImageCreateInfo::pname:samples is limited by +pname:imageCreateSampleCounts, also defined below. + +Several limiting values are defined below, as well as assisting values from +which the limiting values are derived. +The limiting values are referenced by the relevant valid usage statements of +sname:VkImageCreateInfo. + +ifdef::VK_VERSION_1_1,VK_KHR_external_memory_capabilities[] +* Let `VkExternalMemoryHandleTypeFlags imageCreateExternalMemoryHandles` be + the set of external memory handle types that may: be used with the + resultant image. + If sname:VkImageCreateInfo::pname:pNext contains an instance of + slink:VkExternalMemoryImageCreateInfo, then + pname:imageCreateExternalMemoryHandles is the value of + slink:VkExternalMemoryImageCreateInfo::pname:handleTypes. + Otherwise, pname:imageCreateExternalMemoryHandles is `0` +endif::VK_VERSION_1_1,VK_KHR_external_memory_capabilities[] + +ifdef::VK_EXT_image_drm_format_modifier[] +* Let `uint64_t imageCreateDrmFormatModifiers[]` be the set of + <> 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 <>. +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. + ** If pname:tiling is ename:VK_IMAGE_TILING_LINEAR, then + pname:imageCreateFormatFeatures is the value of + slink:VkImageFormatProperties::pname:linearTilingFeatures found by + calling flink:vkGetPhysicalDeviceFormatProperties with parameter + pname:format equal to sname:VkImageCreateInfo::pname:format. + ** If pname:tiling is ename:VK_IMAGE_TILING_OPTIMAL, +ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] + and if the pname:pNext chain contains no instance of + slink:VkExternalFormatANDROID with non-zero pname:externalFormat, +endif::VK_ANDROID_external_memory_android_hardware_buffer[] + then pname:imageCreateFormatFeatures is value of + slink:VkImageFormatProperties::pname:optimalTilingFeatures found by + calling flink:vkGetPhysicalDeviceFormatProperties with parameter + pname:format equal to sname:VkImageCreateInfo::pname:format. +ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] + ** If pname:tiling is ename:VK_IMAGE_TILING_OPTIMAL, and if the + pname:pNext chain contains an instance of slink:VkExternalFormatANDROID + with non-zero pname:externalFormat, then + pname:imageCreateFormatFeatures is the value of + slink:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures + 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 +ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] + defined as follows. + ** If sname:VkImageCreateInfo::pname:pNext contains no instance of + slink:VkExternalFormatANDROID with non-zero pname:externalFormat, then + pname:imageCreateImageFormatPropertiesList is +endif::VK_ANDROID_external_memory_android_hardware_buffer[] + the list of structures obtained by calling + flink:vkGetPhysicalDeviceImageFormatProperties2 for each bit in + pname:imageCreateExternalMemoryHandles, with + slink:VkPhysicalDeviceExternalImageFormatInfo::pname:handleType 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. + If any call returns an error, then + pname:imageCreateImageFormatPropertiesList is defined to be the empty + list. +ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] + ** If sname:VkImageCreateInfo::pname:pNext contains an instance of + slink:VkExternalFormatANDROID with non-zero pname:externalFormat, then + pname:imageCreateImageFormatPropertiesList contains a single element + where: + *** sname:VkImageFormatProperties::pname:maxMipLevels is + [eq]#{lfloor}log~2~(max(pname:extent.width, pname:extent.height, + pname:extent.depth)){rfloor} {plus} 1#. + *** sname:VkImageFormatProperties::pname:maxArrayLayers is + slink:VkPhysicalDeviceLimits::maxImageArrayLayers. + *** Each component of sname:VkImageFormatProperties::pname:maxExtent is + slink:VkPhysicalDeviceLimits::maxImageDimension2D. + *** sname:VkImageFormatPropertoies::pname:sampleCounts contains exactly + ename:VK_SAMPLE_COUNT_1_BIT. +endif::VK_ANDROID_external_memory_android_hardware_buffer[] + +* Let `uint32_t imageCreateMaxMipLevels` be +ifndef::VK_VERSION_1_1,VK_KHR_external_memory[] + the value of slink:VkImageFormatProperties::pname:maxMipLevels found by + calling flink:vkGetPhysicalDeviceImageFormatProperties with parameters + pname:format, pname:imageType, pname:tiling, pname:usage, and pname:flags + equal to those in sname:VkImageCreateInfo. + If fname:vkGetPhysicalDeviceFormatProperties returns an error, then + pname:imageCreateMaxMipLevels is undefined. +endif::VK_VERSION_1_1,VK_KHR_external_memory[] +ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] + the minimum value of slink:VkImageFormatProperties::pname:maxMipLevels in + pname:imageCreateImageFormatPropertiesList. + The value is undefined if pname:imageCreateImageFormatPropertiesList is + empty. +endif::VK_VERSION_1_1,VK_KHR_external_memory[] + +* Let `uint32_t imageCreateMaxArrayLayers` be +ifndef::VK_VERSION_1_1,VK_KHR_external_memory[] + defined analogously to pname:imageCreateMaxMipLevels. +endif::VK_VERSION_1_1,VK_KHR_external_memory[] +ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] + the minimum value of slink:VkImageFormatProperties::pname:maxArrayLayers + in pname:imageCreateImageFormatPropertiesList. + The value is undefined if pname:imageCreateImageFormatPropertiesList is + empty. +endif::VK_VERSION_1_1,VK_KHR_external_memory[] + +* Let `VkExtent3D imageCreateMaxExtent` be +ifndef::VK_VERSION_1_1,VK_KHR_external_memory[] + defined analogously to pname:imageCreateMaxMipLevels. +endif::VK_VERSION_1_1,VK_KHR_external_memory[] +ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] + the component-wise minimum over all + slink:VkImageFormatProperties::pname:maxExtent values in + pname:imageCreateImageFormatPropertiesList. + The value is undefined if pname:imageCreateImageFormatPropertiesList is + empty. +endif::VK_VERSION_1_1,VK_KHR_external_memory[] + +* Let `VkSampleCountFlags imageCreateSampleCounts` be +ifndef::VK_VERSION_1_1,VK_KHR_external_memory[] + defined analogously to pname:imageCreateMaxMipLevels. +endif::VK_VERSION_1_1,VK_KHR_external_memory[] +ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] + the intersection of each slink:VkImageFormatProperties::pname:sampleCounts + in pname:imageCreateImageFormatPropertiesList. + The value is undefined if pname:imageCreateImageFormatPropertiesList is + empty. +endif::VK_VERSION_1_1,VK_KHR_external_memory[] +**** + .Valid Usage **** -ifndef::VK_ANDROID_external_memory_android_hardware_buffer[] - * [[VUID-VkImageCreateInfo-format-00940]] - The combination of pname:format, pname:imageType, pname:tiling, - pname:usage, and pname:flags must: be supported, as indicated by a - ename:VK_SUCCESS return value from - fname:vkGetPhysicalDeviceImageFormatProperties invoked with the same - values passed to the corresponding parameters. -endif::VK_ANDROID_external_memory_android_hardware_buffer[] -ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] - * [[VUID-VkImageCreateInfo-pNext-01889]] - If the pname:pNext chain does not contain an instance of - slink:VkExternalFormatANDROID, or if pname:format is not - ename:VK_FORMAT_UNDEFINED, the combination of pname:format, - pname:imageType, pname:tiling, pname:usage, and pname:flags must: be - supported, as indicated by a ename:VK_SUCCESS return value from - fname:vkGetPhysicalDeviceImageFormatProperties invoked with the same - values passed to the corresponding parameters. -endif::VK_ANDROID_external_memory_android_hardware_buffer[] + * [[VUID-VkImageCreateInfo-imageCreateMaxMipLevels-02251]] + Each of the following values (as described in + <>) must: not be + undefined: pname:imageCreateMaxMipLevels, + pname:imageCreateMaxArrayLayers, pname:imageCreateMaxExtent, and + pname:imageCreateSampleCounts. * [[VUID-VkImageCreateInfo-sharingMode-00941]] If pname:sharingMode is ename:VK_SHARING_MODE_CONCURRENT, pname:pQueueFamilyIndices must: be a valid pointer to an array of @@ -732,45 +905,23 @@ ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] If pname:flags contains ename:VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT, pname:imageType must: be ename:VK_IMAGE_TYPE_3D endif::VK_VERSION_1_1,VK_KHR_maintenance1[] - * [[VUID-VkImageCreateInfo-imageType-00951]] - If pname:imageType is ename:VK_IMAGE_TYPE_1D, pname:extent.width must: - be less than or equal to - sname:VkPhysicalDeviceLimits::pname:maxImageDimension1D, or - sname:VkImageFormatProperties::pname:maxExtent.width (as returned by - fname:vkGetPhysicalDeviceImageFormatProperties with pname:format, - pname:imageType, pname:tiling, pname:usage, and pname:flags equal to - those in this structure) - whichever is higher - * [[VUID-VkImageCreateInfo-imageType-00952]] - If pname:imageType is ename:VK_IMAGE_TYPE_2D and pname:flags does not - contain ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT, pname:extent.width - and pname:extent.height must: be less than or equal to - sname:VkPhysicalDeviceLimits::pname:maxImageDimension2D, or - sname:VkImageFormatProperties::pname:maxExtent.width/pname:height (as - returned by fname:vkGetPhysicalDeviceImageFormatProperties with - pname:format, pname:imageType, pname:tiling, pname:usage, and - pname:flags equal to those in this structure) - whichever is higher - * [[VUID-VkImageCreateInfo-imageType-00953]] - If pname:imageType is ename:VK_IMAGE_TYPE_2D and pname:flags contains - ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT, pname:extent.width and + * [[VUID-VkImageCreateInfo-extent-02252]] + pname:extent.width must: be less than or equal to + pname:imageCreateMaxExtent.pname:width (as defined in + <>). + * [[VUID-VkImageCreateInfo-extent-02253]] pname:extent.height must: be less than or equal to - sname:VkPhysicalDeviceLimits::pname:maxImageDimensionCube, or - sname:VkImageFormatProperties::pname:maxExtent.width/pname:height (as - returned by fname:vkGetPhysicalDeviceImageFormatProperties with - pname:format, pname:imageType, pname:tiling, pname:usage, and - pname:flags equal to those in this structure) - whichever is higher + pname:imageCreateMaxExtent.pname:height (as defined in + <>). + * [[VUID-VkImageCreateInfo-extent-02254]] + pname:extent.depth must: be less than or equal to + pname:imageCreateMaxExtent.pname:depth (as defined in + <>). * [[VUID-VkImageCreateInfo-imageType-00954]] If pname:imageType is ename:VK_IMAGE_TYPE_2D and pname:flags contains ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT, pname:extent.width and pname:extent.height must: be equal and pname:arrayLayers must: be greater than or equal to 6 - * [[VUID-VkImageCreateInfo-imageType-00955]] - If pname:imageType is ename:VK_IMAGE_TYPE_3D, pname:extent.width, - pname:extent.height and pname:extent.depth must: be less than or equal - to sname:VkPhysicalDeviceLimits::pname:maxImageDimension3D, or - sname:VkImageFormatProperties::pname:maxExtent.width/pname:height/pname:depth - (as returned by fname:vkGetPhysicalDeviceImageFormatProperties with - pname:format, pname:imageType, pname:tiling, pname:usage, and - pname:flags equal to those in this structure) - whichever is higher * [[VUID-VkImageCreateInfo-imageType-00956]] If pname:imageType is ename:VK_IMAGE_TYPE_1D, both pname:extent.height and pname:extent.depth must: be `1` @@ -781,26 +932,24 @@ endif::VK_VERSION_1_1,VK_KHR_maintenance1[] pname:mipLevels must: be less than or equal to the number of levels in the complete mipmap chain based on [eq]#pname:extent.width#, [eq]#pname:extent.height#, and [eq]#pname:extent.depth#. - * [[VUID-VkImageCreateInfo-extent-00959]] + * [[VUID-VkImageCreateInfo-mipLevels-02255]] pname:mipLevels must: be less than or equal to - sname:VkImageFormatProperties::pname:maxMipLevels (as returned by - fname:vkGetPhysicalDeviceImageFormatProperties with pname:format, - pname:imageType, pname:tiling, pname:usage, and pname:flags equal to - those in this structure) - * [[VUID-VkImageCreateInfo-arrayLayers-00960]] + pname:imageCreateMaxMipLevels (as defined in + <>). + * [[VUID-VkImageCreateInfo-arrayLayers-02256]] pname:arrayLayers must: be less than or equal to - sname:VkImageFormatProperties::pname:maxArrayLayers (as returned by - fname:vkGetPhysicalDeviceImageFormatProperties with pname:format, - pname:imageType, pname:tiling, pname:usage, and pname:flags equal to - those in this structure) + pname:imageCreateMaxArrayLayers (as defined in + <>). * [[VUID-VkImageCreateInfo-imageType-00961]] If pname:imageType is ename:VK_IMAGE_TYPE_3D, pname:arrayLayers must: be `1`. - * [[VUID-VkImageCreateInfo-samples-00962]] - If pname:samples is not ename:VK_SAMPLE_COUNT_1_BIT, pname:imageType - must: be ename:VK_IMAGE_TYPE_2D, pname:flags must: not contain - ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT, pname:tiling must: be - ename:VK_IMAGE_TILING_OPTIMAL, and pname:mipLevels must: be equal to `1` + * [[VUID-VkImageCreateInfo-samples-02257]] + If pname:samples is not ename:VK_SAMPLE_COUNT_1_BIT, then + pname:imageType must: be ename:VK_IMAGE_TYPE_2D, pname:flags must: not + contain ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT, pname:mipLevels must: + be equal to `1`, and pname:imageCreateMaybeLinear (as defined in + <>) must: be + `false`, * [[VUID-VkImageCreateInfo-usage-00963]] If pname:usage includes ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT, then bits other than ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, @@ -826,12 +975,10 @@ endif::VK_VERSION_1_1,VK_KHR_maintenance1[] ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, or ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT. - * [[VUID-VkImageCreateInfo-samples-00967]] + * [[VUID-VkImageCreateInfo-samples-02258]] pname:samples must: be a bit value that is set in - sname:VkImageFormatProperties::pname:sampleCounts returned by - fname:vkGetPhysicalDeviceImageFormatProperties with pname:format, - pname:imageType, pname:tiling, pname:usage, and pname:flags equal to - those in this structure + pname:imageCreateSampleCounts (as defined in + <>). * [[VUID-VkImageCreateInfo-usage-00968]] If the <> feature is not enabled, and pname:usage contains @@ -938,12 +1085,14 @@ ifdef::VK_VERSION_1_1,VK_KHR_device_group[] slink:VkDeviceGroupDeviceCreateInfo::pname:physicalDeviceCount equal to 1, pname:flags must: not contain ename:VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT - * [[VUID-VkImageCreateInfo-flags-00992]] + * [[VUID-VkImageCreateInfo-flags-02259]] If pname:flags contains ename:VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT, then pname:mipLevels must: be one, pname:arrayLayers must: be one, - pname:imageType must: be ename:VK_IMAGE_TYPE_2D, and pname:tiling must: - be ename:VK_IMAGE_TILING_OPTIMAL + pname:imageType must: be ename:VK_IMAGE_TYPE_2D. + and pname:imageCreateMaybeLinear (as defined in + <>) must: be + `false`. endif::VK_VERSION_1_1,VK_KHR_device_group[] ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] * [[VUID-VkImageCreateInfo-flags-01572]] @@ -979,25 +1128,29 @@ ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] ** pname:samples must be ename:VK_SAMPLE_COUNT_1_BIT ** pname:imageType must: be ename:VK_IMAGE_TYPE_2D ** pname:arrayLayers must: be 1 - * [[VUID-VkImageCreateInfo-tiling-01575]] - If pname:tiling is ename:VK_IMAGE_TILING_OPTIMAL, pname:format is a - _multi-planar_ format, and - sname:VkFormatProperties::pname:optimalTilingFeatures (as returned by - fname:vkGetPhysicalDeviceFormatProperties with the same value of - pname:format) does not include ename:VK_FORMAT_FEATURE_DISJOINT_BIT, - pname:flags must: not contain ename:VK_IMAGE_CREATE_DISJOINT_BIT - * [[VUID-VkImageCreateInfo-tiling-01576]] - If pname:tiling is ename:VK_IMAGE_TILING_LINEAR, pname:format is a - _multi-planar_ format, and - sname:VkFormatProperties::pname:linearTilingFeatures (as returned by - fname:vkGetPhysicalDeviceFormatProperties with the same value of - pname:format) does not include ename:VK_FORMAT_FEATURE_DISJOINT_BIT, - pname:flags must: not contain ename:VK_IMAGE_CREATE_DISJOINT_BIT + * [[VUID-VkImageCreateInfo-imageCreateFormatFeatures-02260]] + If pame:format is a _multi-planar_ format, and if + pname:imageCreateFormatFeatures (as defined in + <>) does not + contain ename:VK_FORMAT_FEATURE_DISJOINT_BIT, then pname:flags must: not + contain ename:VK_IMAGE_CREATE_DISJOINT_BIT. * [[VUID-VkImageCreateInfo-format-01577]] If pname:format is not a _multi-planar_ format, and pname:flags does not 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[] + * [[VUID-VkImageCreateInfo-tiling-02261]] + 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. + * [[VUID-VkImageCreateInfo-pNext-02262]] + 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 @@ -1014,12 +1167,6 @@ ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] ** pname:mipLevels must: either be `1` or equal to the number of levels in the complete mipmap chain based on [eq]#pname:extent.width#, [eq]#pname:extent.height#, and [eq]#pname:extent.depth#. - ** If pname:format is not ename:VK_FORMAT_UNDEFINED, then pname:format, - pname:imageType, pname:tiling, pname:usage, pname:flags, - pname:mipLevels, and pname:samples must: be supported with - ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID - external memory handle types according to - flink:vkGetPhysicalDeviceImageFormatProperties2 ** If pname:format is ename:VK_FORMAT_UNDEFINED, then the pname:pNext chain must: include a slink:VkExternalFormatANDROID structure whose pname:externalFormat member is not `0` @@ -1276,6 +1423,108 @@ 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 <> 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 +**** + * [[VUID-VkImageDrmFormatModifierListCreateInfoEXT-pDrmFormatModifiers-02263]] + 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 <> +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 +**** + * [[VUID-VkImageDrmFormatModifierExplicitCreateInfoEXT-drmFormatModifier-02264]] + 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. + * [[VUID-VkImageDrmFormatModifierExplicitCreateInfoEXT-drmFormatModifierPlaneCount-02265]] + 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. + * [[VUID-VkImageDrmFormatModifierExplicitCreateInfoEXT-pPlaneLayouts-02266]] + For each element of pname:pPlaneLayouts: + ** [[VUID-VkImageDrmFormatModifierExplicitCreateInfoEXT-size-02267]] + pname:size must: be 0 + ** [[VUID-VkImageDrmFormatModifierExplicitCreateInfoEXT-arrayPitch-02268]] + pname:arrayPitch must: be 0 if + slink:VkImageCreateInfo::pname:arrayLayers is 1. + ** [[VUID-VkImageDrmFormatModifierExplicitCreateInfoEXT-depthPitch-02269]] + 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'] -- @@ -1474,14 +1723,21 @@ 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 <>. + 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[] @@ -1492,11 +1748,36 @@ 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 <>. +The +endif::VK_EXT_image_drm_format_modifier[] +ifdef::VK_EXT_image_drm_format_modifier[] +If the image is <>, then the +endif::VK_EXT_image_drm_format_modifier[] +returned layout is valid for <>. + 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 <>, -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 <>, then the returned +layout has an implementation-dependent meaning; the vendor of the image's +<> 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. @@ -1509,9 +1790,17 @@ 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[] + * [[VUID-vkGetImageSubresourceLayout-image-02270]] + 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 @@ -1525,13 +1814,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 <> 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 <> with three planes, the pname:aspectMask member of pname:pSubresource must: be ename:VK_IMAGE_ASPECT_PLANE_0_BIT, @@ -1543,6 +1834,18 @@ 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[] + * [[VUID-vkGetImageSubresourceLayout-tiling-02271]] + 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 + <> + associated with the image's + <> and + <>. +endif::VK_EXT_image_drm_format_modifier[] **** include::../validity/protos/vkGetImageSubresourceLayout.txt[] @@ -1571,8 +1874,11 @@ sname:VkSubresourceLayout structure: include::../api/structs/VkSubresourceLayout.txt[] - * pname:offset is the byte offset from the start of the image where the - image subresource begins. + * pname:offset is the byte offset from the start of the image +ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] + or the plane +endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] + where the image subresource begins. * pname:size is the size in bytes of the image subresource. pname:size includes any extra memory that is required based on pname:rowPitch. @@ -1583,9 +1889,9 @@ include::../api/structs/VkSubresourceLayout.txt[] * pname:depthPitch describes the number of bytes between each slice of 3D image. -For images created with linear tiling, pname:rowPitch, pname:arrayPitch and -pname:depthPitch describe the layout of the image subresource in linear -memory. +If the image is <>, 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 texels with the same x coordinate in adjacent rows (y coordinates differ by one). @@ -1619,14 +1925,23 @@ 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: -be ename:VK_IMAGE_ASPECT_COLOR_BIT. -For depth/stencil formats, pname:aspectMask must: be either -ename:VK_IMAGE_ASPECT_DEPTH_BIT or ename:VK_IMAGE_ASPECT_STENCIL_BIT. +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. + +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 and pname:size representing the region of memory used for that aspect. @@ -1635,18 +1950,97 @@ 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 <>, the pname:aspectMask member of sname:VkImageSubresource must: be +If the image has a +<> +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. +If the image is _disjoint_, then the pname:offset is relative to the base +address of the plane. +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 +<> +associated with the image's <> and +<>. +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 <>, 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 <>. +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 +**** + * [[VUID-vkGetImageDrmFormatModifierPropertiesEXT-image-02272]] + pname:image must: have been created with + <> 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 + <>. + +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'] -- @@ -1706,6 +2100,23 @@ 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]] @@ -1850,8 +2261,8 @@ 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 +<> 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. @@ -1884,8 +2295,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 - layout defined for ename:VK_IMAGE_TILING_OPTIMAL images. + <> 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 color or resolve attachment in a sname:VkFramebuffer. @@ -2379,13 +2790,6 @@ ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] must: not be ename:VK_IMAGE_VIEW_TYPE_2D or ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY endif::VK_VERSION_1_1,VK_KHR_maintenance1[] - * [[VUID-VkImageViewCreateInfo-image-01006]] - If pname:image was created with ename:VK_IMAGE_TILING_LINEAR, - pname:format must: be format that has at least one supported feature bit - present in the value of - sname:VkFormatProperties::pname:linearTilingFeatures returned by - fname:vkGetPhysicalDeviceFormatProperties with the same value of - pname:format ifndef::VK_NV_shading_rate_image[] * [[VUID-VkImageViewCreateInfo-image-01007]] pname:image must: have been created with a pname:usage value containing @@ -2405,124 +2809,27 @@ ifdef::VK_NV_shading_rate_image[] ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT, or ename:VK_IMAGE_USAGE_SHADING_RATE_IMAGE_BIT_NV endif::VK_NV_shading_rate_image[] - * [[VUID-VkImageViewCreateInfo-image-01008]] - If pname:image was created with ename:VK_IMAGE_TILING_LINEAR and - pname:usage contains ename:VK_IMAGE_USAGE_SAMPLED_BIT, pname:format - must: be supported for sampled images, as specified by the - ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT flag in - sname:VkFormatProperties::pname:linearTilingFeatures returned by - fname:vkGetPhysicalDeviceFormatProperties with the same value of - pname:format - * [[VUID-VkImageViewCreateInfo-image-01009]] - If pname:image was created with ename:VK_IMAGE_TILING_LINEAR and - pname:usage contains ename:VK_IMAGE_USAGE_STORAGE_BIT, pname:format - must: be supported for storage images, as specified by the - ename:VK_FORMAT_FEATURE_STORAGE_IMAGE_BIT flag in - sname:VkFormatProperties::pname:linearTilingFeatures returned by - fname:vkGetPhysicalDeviceFormatProperties with the same value of - pname:format - * [[VUID-VkImageViewCreateInfo-image-01010]] - If pname:image was created with ename:VK_IMAGE_TILING_LINEAR and - pname:usage contains ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, - pname:format must: be supported for color attachments, as specified by - the ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT flag in - sname:VkFormatProperties::pname:linearTilingFeatures returned by - fname:vkGetPhysicalDeviceFormatProperties with the same value of - pname:format - * [[VUID-VkImageViewCreateInfo-image-01011]] - If pname:image was created with ename:VK_IMAGE_TILING_LINEAR and - pname:usage contains ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, - pname:format must: be supported for depth/stencil attachments, as - specified by the ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT - flag in sname:VkFormatProperties::pname:linearTilingFeatures returned by - fname:vkGetPhysicalDeviceFormatProperties with the same value of - pname:format -ifndef::VK_ANDROID_external_memory_android_hardware_buffer[] - * [[VUID-VkImageViewCreateInfo-image-01012]] - If pname:image was created with ename:VK_IMAGE_TILING_OPTIMAL, - pname:format must: be format that has at least one supported feature bit - present in the value of - sname:VkFormatProperties::pname:optimalTilingFeatures returned by - fname:vkGetPhysicalDeviceFormatProperties with the same value of - pname:format - * [[VUID-VkImageViewCreateInfo-image-01013]] - If pname:image was created with ename:VK_IMAGE_TILING_OPTIMAL and - pname:usage contains ename:VK_IMAGE_USAGE_SAMPLED_BIT, pname:format - must: be supported for sampled images, as specified by the - ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT flag in - sname:VkFormatProperties::pname:optimalTilingFeatures returned by - fname:vkGetPhysicalDeviceFormatProperties with the same value of - pname:format - * [[VUID-VkImageViewCreateInfo-image-01014]] - If pname:image was created with ename:VK_IMAGE_TILING_OPTIMAL and - pname:usage contains ename:VK_IMAGE_USAGE_STORAGE_BIT, pname:format - must: be supported for storage images, as specified by the - ename:VK_FORMAT_FEATURE_STORAGE_IMAGE_BIT flag in - sname:VkFormatProperties::pname:optimalTilingFeatures returned by - fname:vkGetPhysicalDeviceFormatProperties with the same value of - pname:format - * [[VUID-VkImageViewCreateInfo-image-01015]] - If pname:image was created with ename:VK_IMAGE_TILING_OPTIMAL and - pname:usage contains ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, - pname:format must: be supported for color attachments, as specified by - the ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT flag in - sname:VkFormatProperties::pname:optimalTilingFeatures returned by - fname:vkGetPhysicalDeviceFormatProperties with the same value of - pname:format - * [[VUID-VkImageViewCreateInfo-image-01016]] - If pname:image was created with ename:VK_IMAGE_TILING_OPTIMAL and - pname:usage contains ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, - pname:format must: be supported for depth/stencil attachments, as - specified by the ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT - flag in sname:VkFormatProperties::pname:optimalTilingFeatures returned - by fname:vkGetPhysicalDeviceFormatProperties with the same value of - pname:format -endif::VK_ANDROID_external_memory_android_hardware_buffer[] -ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] - * [[VUID-VkImageViewCreateInfo-image-01965]] - If pname:image was created with ename:VK_IMAGE_TILING_OPTIMAL and - pname:format is not ename:VK_FORMAT_UNDEFINED, pname:format must: be - format that has at least one supported feature bit present in the value - of sname:VkFormatProperties::pname:optimalTilingFeatures returned by - fname:vkGetPhysicalDeviceFormatProperties with the same value of - pname:format - * [[VUID-VkImageViewCreateInfo-image-01966]] - If pname:image was created with ename:VK_IMAGE_TILING_OPTIMAL, and - pname:format is not ename:VK_FORMAT_UNDEFINED, and pname:usage contains - ename:VK_IMAGE_USAGE_SAMPLED_BIT, pname:format must: be supported for - sampled images, as specified by the - ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT flag in - sname:VkFormatProperties::pname:optimalTilingFeatures returned by - fname:vkGetPhysicalDeviceFormatProperties with the same value of - pname:format - * [[VUID-VkImageViewCreateInfo-image-01967]] - If pname:image was created with ename:VK_IMAGE_TILING_OPTIMAL, and - pname:format is not ename:VK_FORMAT_UNDEFINED, and pname:usage contains - ename:VK_IMAGE_USAGE_STORAGE_BIT, pname:format must: be supported for - storage images, as specified by the - ename:VK_FORMAT_FEATURE_STORAGE_IMAGE_BIT flag in - sname:VkFormatProperties::pname:optimalTilingFeatures returned by - fname:vkGetPhysicalDeviceFormatProperties with the same value of - pname:format - * [[VUID-VkImageViewCreateInfo-image-01968]] - If pname:image was created with ename:VK_IMAGE_TILING_OPTIMAL, and - pname:format is not ename:VK_FORMAT_UNDEFINED, and pname:usage contains - ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, pname:format must: be - supported for color attachments, as specified by the - ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT flag in - sname:VkFormatProperties::pname:optimalTilingFeatures returned by - fname:vkGetPhysicalDeviceFormatProperties with the same value of - pname:format - * [[VUID-VkImageViewCreateInfo-image-01969]] - If pname:image was created with ename:VK_IMAGE_TILING_OPTIMAL, and - pname:format is not ename:VK_FORMAT_UNDEFINED, and pname:usage contains - ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, pname:format must: be - supported for depth/stencil attachments, as specified by the - ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT flag in - sname:VkFormatProperties::pname:optimalTilingFeatures returned by - fname:vkGetPhysicalDeviceFormatProperties with the same value of - pname:format -endif::VK_ANDROID_external_memory_android_hardware_buffer[] + * [[VUID-VkImageViewCreateInfo-None-02273]] + The <> of the + resultant image view must: contain at least one bit. + * [[VUID-VkImageViewCreateInfo-usage-02274]] + If pname:usage contains ename:VK_IMAGE_USAGE_SAMPLED_BIT, then the + <> of the + resultant image view must: contain + ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT. + * [[VUID-VkImageViewCreateInfo-usage-02275]] + If pname:usage contains ename:VK_IMAGE_USAGE_STORAGE_BIT, then the image + view's <> must: + contain ename:VK_FORMAT_FEATURE_STORAGE_IMAGE_BIT. + * [[VUID-VkImageViewCreateInfo-usage-02276]] + If pname:usage contains ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, then + the image view's <> must: contain ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT. + * [[VUID-VkImageViewCreateInfo-usage-02277]] + If pname:usage contains + ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, then the image view's + <> must: contain + ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT. * [[VUID-VkImageViewCreateInfo-subresourceRange-01478]] pname:subresourceRange.baseMipLevel must: be less than the pname:mipLevels specified in slink:VkImageCreateInfo when pname:image @@ -2908,6 +3215,11 @@ 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[] + * [[VUID-VkImageSubresourceRange-aspectMask-02278]] + 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[] @@ -3129,6 +3441,23 @@ 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 @@ -3271,9 +3600,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 + <> 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 @@ -3495,15 +3822,32 @@ 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[] + * [[VUID-VkImageMemoryRequirementsInfo2KHR-image-02279]] + 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[] + * [[VUID-VkImageMemoryRequirementsInfo2KHR-image-02280]] + 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 @@ -3542,13 +3886,27 @@ 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 + * [[VUID-VkImagePlaneMemoryRequirementsInfoKHR-planeAspect-02281]] + 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[] + * [[VUID-VkImagePlaneMemoryRequirementsInfoKHR-planeAspect-02282]] + 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 + <> + associated with the image's + <> and + <>.) +endif::VK_EXT_image_drm_format_modifier[] **** include::../validity/structs/VkImagePlaneMemoryRequirementsInfo.txt[] @@ -4466,13 +4824,27 @@ 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 - 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) + * [[VUID-VkBindImagePlaneMemoryInfoKHR-planeAspect-02283]] + 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.) +ifdef::VK_EXT_image_drm_format_modifier[] + * [[VUID-VkBindImagePlaneMemoryInfoKHR-planeAspect-02284]] + 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 + <> + associated with the image's + <> and + <>.) +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 @@ -4711,9 +5083,9 @@ of an application, if some large resources are used for disjoint periods of time. ==== -When an opaque, non-ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT image is -bound to an aliased range, all image subresources of the image _overlap_ the -range. +When a <>, +non-ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT image is bound to an aliased +range, all image subresources of the image _overlap_ the range. When a linear image is bound to an aliased range, the image subresources that (according to the image's advertised layout) include bytes from the aliased range overlap the range. @@ -4772,6 +5144,11 @@ endif::VK_VERSION_1_1,VK_KHR_device_group[] from the multi-planar image's dimensions in the manner listed for <> 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 + <>. +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 2d1b3f5d..39f4dc6f 100644 --- a/include/vulkan/vulkan_core.h +++ b/include/vulkan/vulkan_core.h @@ -43,7 +43,7 @@ extern "C" { #define VK_VERSION_MINOR(version) (((uint32_t)(version) >> 12) & 0x3ff) #define VK_VERSION_PATCH(version) ((uint32_t)(version) & 0xfff) // Version of this file -#define VK_HEADER_VERSION 85 +#define VK_HEADER_VERSION 86 #define VK_NULL_HANDLE 0 @@ -427,10 +427,12 @@ typedef enum VkStructureType { VK_STRUCTURE_TYPE_IMPORT_MEMORY_HOST_POINTER_INFO_EXT = 1000178000, VK_STRUCTURE_TYPE_MEMORY_HOST_POINTER_PROPERTIES_EXT = 1000178001, VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_EXTERNAL_MEMORY_HOST_PROPERTIES_EXT = 1000178002, + VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_ATOMIC_INT64_FEATURES_KHR = 1000180000, VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_CORE_PROPERTIES_AMD = 1000185000, VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VERTEX_ATTRIBUTE_DIVISOR_PROPERTIES_EXT = 1000190000, VK_STRUCTURE_TYPE_PIPELINE_VERTEX_INPUT_DIVISOR_STATE_CREATE_INFO_EXT = 1000190001, VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VERTEX_ATTRIBUTE_DIVISOR_FEATURES_EXT = 1000190002, + VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DRIVER_PROPERTIES_KHR = 1000196000, VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_COMPUTE_SHADER_DERIVATIVES_FEATURES_NV = 1000201000, VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MESH_SHADER_FEATURES_NV = 1000202000, VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MESH_SHADER_PROPERTIES_NV = 1000202001, @@ -6044,6 +6046,60 @@ typedef struct VkPhysicalDevice8BitStorageFeaturesKHR { +#define VK_KHR_shader_atomic_int64 1 +#define VK_KHR_SHADER_ATOMIC_INT64_SPEC_VERSION 1 +#define VK_KHR_SHADER_ATOMIC_INT64_EXTENSION_NAME "VK_KHR_shader_atomic_int64" + +typedef struct VkPhysicalDeviceShaderAtomicInt64FeaturesKHR { + VkStructureType sType; + void* pNext; + VkBool32 shaderBufferInt64Atomics; + VkBool32 shaderSharedInt64Atomics; +} VkPhysicalDeviceShaderAtomicInt64FeaturesKHR; + + + +#define VK_KHR_driver_properties 1 +#define VK_MAX_DRIVER_NAME_SIZE_KHR 256 +#define VK_MAX_DRIVER_INFO_SIZE_KHR 256 +#define VK_KHR_DRIVER_PROPERTIES_SPEC_VERSION 1 +#define VK_KHR_DRIVER_PROPERTIES_EXTENSION_NAME "VK_KHR_driver_properties" + + +typedef enum VkDriverIdKHR { + VK_DRIVER_ID_AMD_PROPRIETARY_KHR = 1, + VK_DRIVER_ID_AMD_OPEN_SOURCE_KHR = 2, + VK_DRIVER_ID_MESA_RADV_KHR = 3, + VK_DRIVER_ID_NVIDIA_PROPRIETARY_KHR = 4, + VK_DRIVER_ID_INTEL_PROPRIETARY_WINDOWS_KHR = 5, + VK_DRIVER_ID_INTEL_OPEN_SOURCE_MESA_KHR = 6, + VK_DRIVER_ID_IMAGINATION_PROPRIETARY_KHR = 7, + VK_DRIVER_ID_QUALCOMM_PROPRIETARY_KHR = 8, + VK_DRIVER_ID_ARM_PROPRIETARY_KHR = 9, + VK_DRIVER_ID_BEGIN_RANGE_KHR = VK_DRIVER_ID_AMD_PROPRIETARY_KHR, + VK_DRIVER_ID_END_RANGE_KHR = VK_DRIVER_ID_ARM_PROPRIETARY_KHR, + VK_DRIVER_ID_RANGE_SIZE_KHR = (VK_DRIVER_ID_ARM_PROPRIETARY_KHR - VK_DRIVER_ID_AMD_PROPRIETARY_KHR + 1), + VK_DRIVER_ID_MAX_ENUM_KHR = 0x7FFFFFFF +} VkDriverIdKHR; + +typedef struct VkConformanceVersionKHR { + uint8_t major; + uint8_t minor; + uint8_t subminor; + uint8_t patch; +} VkConformanceVersionKHR; + +typedef struct VkPhysicalDeviceDriverPropertiesKHR { + VkStructureType sType; + void* pNext; + uint32_t driverID; + char driverName[VK_MAX_DRIVER_NAME_SIZE_KHR]; + char driverInfo[VK_MAX_DRIVER_INFO_SIZE_KHR]; + VkConformanceVersionKHR conformanceVersion; +} VkPhysicalDeviceDriverPropertiesKHR; + + + #define VK_KHR_vulkan_memory_model 1 #define VK_KHR_VULKAN_MEMORY_MODEL_SPEC_VERSION 2 #define VK_KHR_VULKAN_MEMORY_MODEL_EXTENSION_NAME "VK_KHR_vulkan_memory_model" @@ -8044,13 +8100,13 @@ typedef void (VKAPI_PTR *PFN_vkDestroyAccelerationStructureNVX)(VkDevice device, typedef void (VKAPI_PTR *PFN_vkGetAccelerationStructureMemoryRequirementsNVX)(VkDevice device, const VkAccelerationStructureMemoryRequirementsInfoNVX* pInfo, VkMemoryRequirements2KHR* pMemoryRequirements); typedef void (VKAPI_PTR *PFN_vkGetAccelerationStructureScratchMemoryRequirementsNVX)(VkDevice device, const VkAccelerationStructureMemoryRequirementsInfoNVX* pInfo, VkMemoryRequirements2KHR* pMemoryRequirements); typedef VkResult (VKAPI_PTR *PFN_vkBindAccelerationStructureMemoryNVX)(VkDevice device, uint32_t bindInfoCount, const VkBindAccelerationStructureMemoryInfoNVX* pBindInfos); -typedef void (VKAPI_PTR *PFN_vkCmdBuildAccelerationStructureNVX)(VkCommandBuffer cmdBuf, VkAccelerationStructureTypeNVX type, uint32_t instanceCount, VkBuffer instanceData, VkDeviceSize instanceOffset, uint32_t geometryCount, const VkGeometryNVX* pGeometries, VkBuildAccelerationStructureFlagsNVX flags, VkBool32 update, VkAccelerationStructureNVX dst, VkAccelerationStructureNVX src, VkBuffer scratch, VkDeviceSize scratchOffset); -typedef void (VKAPI_PTR *PFN_vkCmdCopyAccelerationStructureNVX)(VkCommandBuffer cmdBuf, VkAccelerationStructureNVX dst, VkAccelerationStructureNVX src, VkCopyAccelerationStructureModeNVX mode); -typedef void (VKAPI_PTR *PFN_vkCmdTraceRaysNVX)(VkCommandBuffer cmdBuf, VkBuffer raygenShaderBindingTableBuffer, VkDeviceSize raygenShaderBindingOffset, VkBuffer missShaderBindingTableBuffer, VkDeviceSize missShaderBindingOffset, VkDeviceSize missShaderBindingStride, VkBuffer hitShaderBindingTableBuffer, VkDeviceSize hitShaderBindingOffset, VkDeviceSize hitShaderBindingStride, uint32_t width, uint32_t height); +typedef void (VKAPI_PTR *PFN_vkCmdBuildAccelerationStructureNVX)(VkCommandBuffer commandBuffer, VkAccelerationStructureTypeNVX type, uint32_t instanceCount, VkBuffer instanceData, VkDeviceSize instanceOffset, uint32_t geometryCount, const VkGeometryNVX* pGeometries, VkBuildAccelerationStructureFlagsNVX flags, VkBool32 update, VkAccelerationStructureNVX dst, VkAccelerationStructureNVX src, VkBuffer scratch, VkDeviceSize scratchOffset); +typedef void (VKAPI_PTR *PFN_vkCmdCopyAccelerationStructureNVX)(VkCommandBuffer commandBuffer, VkAccelerationStructureNVX dst, VkAccelerationStructureNVX src, VkCopyAccelerationStructureModeNVX mode); +typedef void (VKAPI_PTR *PFN_vkCmdTraceRaysNVX)(VkCommandBuffer commandBuffer, VkBuffer raygenShaderBindingTableBuffer, VkDeviceSize raygenShaderBindingOffset, VkBuffer missShaderBindingTableBuffer, VkDeviceSize missShaderBindingOffset, VkDeviceSize missShaderBindingStride, VkBuffer hitShaderBindingTableBuffer, VkDeviceSize hitShaderBindingOffset, VkDeviceSize hitShaderBindingStride, uint32_t width, uint32_t height); typedef VkResult (VKAPI_PTR *PFN_vkCreateRaytracingPipelinesNVX)(VkDevice device, VkPipelineCache pipelineCache, uint32_t createInfoCount, const VkRaytracingPipelineCreateInfoNVX* pCreateInfos, const VkAllocationCallbacks* pAllocator, VkPipeline* pPipelines); typedef VkResult (VKAPI_PTR *PFN_vkGetRaytracingShaderHandlesNVX)(VkDevice device, VkPipeline pipeline, uint32_t firstGroup, uint32_t groupCount, size_t dataSize, void* pData); typedef VkResult (VKAPI_PTR *PFN_vkGetAccelerationStructureHandleNVX)(VkDevice device, VkAccelerationStructureNVX accelerationStructure, size_t dataSize, void* pData); -typedef void (VKAPI_PTR *PFN_vkCmdWriteAccelerationStructurePropertiesNVX)(VkCommandBuffer cmdBuf, VkAccelerationStructureNVX accelerationStructure, VkQueryType queryType, VkQueryPool queryPool, uint32_t query); +typedef void (VKAPI_PTR *PFN_vkCmdWriteAccelerationStructurePropertiesNVX)(VkCommandBuffer commandBuffer, VkAccelerationStructureNVX accelerationStructure, VkQueryType queryType, VkQueryPool queryPool, uint32_t query); typedef VkResult (VKAPI_PTR *PFN_vkCompileDeferredNVX)(VkDevice device, VkPipeline pipeline, uint32_t shader); #ifndef VK_NO_PROTOTYPES @@ -8081,7 +8137,7 @@ VKAPI_ATTR VkResult VKAPI_CALL vkBindAccelerationStructureMemoryNVX( const VkBindAccelerationStructureMemoryInfoNVX* pBindInfos); VKAPI_ATTR void VKAPI_CALL vkCmdBuildAccelerationStructureNVX( - VkCommandBuffer cmdBuf, + VkCommandBuffer commandBuffer, VkAccelerationStructureTypeNVX type, uint32_t instanceCount, VkBuffer instanceData, @@ -8096,13 +8152,13 @@ VKAPI_ATTR void VKAPI_CALL vkCmdBuildAccelerationStructureNVX( VkDeviceSize scratchOffset); VKAPI_ATTR void VKAPI_CALL vkCmdCopyAccelerationStructureNVX( - VkCommandBuffer cmdBuf, + VkCommandBuffer commandBuffer, VkAccelerationStructureNVX dst, VkAccelerationStructureNVX src, VkCopyAccelerationStructureModeNVX mode); VKAPI_ATTR void VKAPI_CALL vkCmdTraceRaysNVX( - VkCommandBuffer cmdBuf, + VkCommandBuffer commandBuffer, VkBuffer raygenShaderBindingTableBuffer, VkDeviceSize raygenShaderBindingOffset, VkBuffer missShaderBindingTableBuffer, @@ -8137,7 +8193,7 @@ VKAPI_ATTR VkResult VKAPI_CALL vkGetAccelerationStructureHandleNVX( void* pData); VKAPI_ATTR void VKAPI_CALL vkCmdWriteAccelerationStructurePropertiesNVX( - VkCommandBuffer cmdBuf, + VkCommandBuffer commandBuffer, VkAccelerationStructureNVX accelerationStructure, VkQueryType queryType, VkQueryPool queryPool, diff --git a/reflow_count.py b/reflow_count.py index 3564e942..513b5759 100644 --- a/reflow_count.py +++ b/reflow_count.py @@ -1,2 +1,2 @@ # The value to start tagging VU statements at, unless overridden by -nextvu -startVUID = 2246 +startVUID = 2285 diff --git a/xml/vk.xml b/xml/vk.xml index fb1eb501..3eb0fe02 100644 --- a/xml/vk.xml +++ b/xml/vk.xml @@ -147,7 +147,7 @@ server. // Vulkan 1.1 version number #define VK_API_VERSION_1_1 VK_MAKE_VERSION(1, 1, 0)// Patch version should always be set to 0 // Version of this file -#define VK_HEADER_VERSION 85 +#define VK_HEADER_VERSION 86 #define VK_DEFINE_HANDLE(object) typedef struct object##_T* object; @@ -523,6 +523,7 @@ server. Enumerated types in the header, but not used by the API + @@ -1972,6 +1973,20 @@ server. void* pNext uint32_t maxPushDescriptors + + uint8_t major + uint8_t minor + uint8_t subminor + uint8_t patch + + + VkStructureType sType + void* pNext + uint32_t driverID + char driverName[VK_MAX_DRIVER_NAME_SIZE_KHR] + char driverInfo[VK_MAX_DRIVER_INFO_SIZE_KHR] + VkConformanceVersionKHR conformanceVersion + VkStructureType sType const void* pNext @@ -3243,6 +3258,12 @@ server. VkBool32 vulkanMemoryModel VkBool32 vulkanMemoryModelDeviceScope + + VkStructureType sType + void* pNext + VkBool32 shaderBufferInt64Atomics + VkBool32 shaderSharedInt64Atomics + VkStructureType sType void* pNext @@ -3464,6 +3485,40 @@ server. uint32_t maxRecursionDepth uint32_t maxGeometryCount + + VkStructureType sType + void* pNext + uint32_t drmFormatModifierCount + VkDrmFormatModifierPropertiesEXT* pDrmFormatModifierProperties + + + uint64_t drmFormatModifier + uint32_t drmFormatModifierPlaneCount + VkFormatFeatureFlags drmFormatModifierTilingFeatures + + + VkStructureType sType + const void* pNext + uint64_t drmFormatModifier + + + VkStructureType sType + const void* pNext + uint32_t drmFormatModifierCount + const uint64_t* pDrmFormatModifiers + + + VkStructureType sType + const void* pNext + uint64_t drmFormatModifier + uint32_t drmFormatModifierPlaneCount + const VkSubresourceLayout* pPlaneLayouts + + + VkStructureType sType + void* pNext + uint64_t drmFormatModifier + Vulkan enumerant (token) definitions @@ -3491,6 +3546,8 @@ server. + + @@ -4043,6 +4100,7 @@ server. + @@ -4549,6 +4607,20 @@ server. + + Driver IDs are now represented as enums instead of the old + <driverids> tag, allowing them to be included in the + API headers. + + + + + + + + + + @@ -6658,14 +6730,14 @@ server. void vkCmdCopyAccelerationStructureNVX - VkCommandBuffer cmdBuf + VkCommandBuffer commandBuffer VkAccelerationStructureNVX dst VkAccelerationStructureNVX src VkCopyAccelerationStructureModeNVX mode void vkCmdWriteAccelerationStructurePropertiesNVX - VkCommandBuffer cmdBuf + VkCommandBuffer commandBuffer VkAccelerationStructureNVX accelerationStructure VkQueryType queryType VkQueryPool queryPool @@ -6673,7 +6745,7 @@ server. void vkCmdBuildAccelerationStructureNVX - VkCommandBuffer cmdBuf + VkCommandBuffer commandBuffer VkAccelerationStructureTypeNVX type uint32_t instanceCount VkBuffer instanceData @@ -6689,7 +6761,7 @@ server. void vkCmdTraceRaysNVX - VkCommandBuffer cmdBuf + VkCommandBuffer commandBuffer VkBuffer raygenShaderBindingTableBuffer VkDeviceSize raygenShaderBindingOffset VkBuffer missShaderBindingTableBuffer @@ -6726,6 +6798,12 @@ server. const VkAllocationCallbacks* pAllocator VkPipeline* pPipelines + + VkResult vkGetImageDrmFormatModifierPropertiesEXT + VkDevice device + VkImage image + VkImageDrmFormatModifierPropertiesEXT* pProperties + @@ -9115,10 +9193,38 @@ server. - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + @@ -9383,10 +9489,12 @@ server. - + - - + + + + @@ -9488,10 +9596,16 @@ server. - + - - + + + + + + + + @@ -9670,5 +9784,108 @@ server. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +