VK_KHR_maintenance7

Some implementations treat writes to a single aspect of mixed depth/stencil attachments as writes to both aspects, while some implementations treat these writes as single-aspect writes in isolation. It is important for applications to know which behavior is in use by an implementation.

When the Vulkan driver is provided by a layered implementation, it may be necessary to query the details of the underlying device. For example, running on Mesa/Venus, driver ID is returned as VK_DRIVER_ID_MESA_VENUS, but it may be necessary to know what the real driver under the hood is.

Vulkan 1.0 required that the contents of a render pass subpass are either entirely inlined or are provided in a single secondary command buffer. In some situations, it may be beneficial to be able to mix inline and secondary command buffers inside the same render pass subpass, or executed multiple secondary command buffers.

The maximum count of dynamic uniform buffers and dynamic storage buffers that can be included in a pipeline layout are reported separately. While some implementations treat dynamic offsets of uniform buffers and storage buffers the same way, reporting the total count along with maximum count of dynamic uniform and storage buffers could relax the limitation and expose device capabilities more accurately.

The DirectX 12 Variable Shading Rate feature allows applications to specify a shading rate image that is smaller than would be required to provide shading rates for all rendered texels. When a fragment is rendered outside of the area covered by the shading rate image, default values are returned, in line with the usual out of bounds values for images that it guarantees.

In Vulkan however, this is currently outright banned, making it difficult to guarantee portability for apps relying on this or for emulation layers.

A property that indicates whether single-aspect writes to a depth/stencil attachment will result in writes to both aspects.

A new set of structures are included, accessible through VkPhysicalDeviceLayeredApiPropertiesListKHR when chained to VkPhysicalDeviceProperties2.

Flags from the VK_EXT_nested_command_buffer extension provide this functionality, and are promoted to this extension.

A limit that indicates the maximum total count of dynamic uniform buffers and storage buffers that can be included in a pipeline layout is added.

At the basic level, the first hurdle is allowing applications to specify fragment shading rate attachments that are too small for the render area, and giving it some sense of defined behavior. The second challenge is ensuring that implementations all return the expected values.

This could be achieved by using new language to describe the specifics of these lookups, but notably image reads with robust access already have the desired behavior. As such, this proposal retools fragment shading rate attachment reads as general image reads, and guarantees the values match DirectX 12’s guarantees when the VkPhysicalDeviceRobustness2FeaturesEXT::robustImageAccess2 feature is enabled.

Previously when the 32-bit unsigned integer query result overflows, the implementation may either wrap or saturate. However, MESA Virtio-GPU Venus layered implementation needs determined behavior to implement vkGetQueryPoolResults based on vkCmdCopyQueryPoolResults in an efficient way. This is solved by requiring that for an unsigned integer query, the 32-bit result value must be equal to the 32 least significant bits of the equivalent 64-bit result value.

The following features are exposed:

The following properties are added by this extension:

The VK_RENDERING_CONTENTS_INLINE_BIT_KHR flag promoted from the VK_EXT_nested_command_buffer extension allows the render pass instance to be recorded inline within the current command buffer. Combined with the VK_RENDERING_CONTENTS_SECONDARY_COMMAND_BUFFERS_BIT bit, the contents of the render pass instance can be recorded both inline and in secondary command buffers executed with vkCmdExecuteCommands.

The VK_SUBPASS_CONTENTS_INLINE_AND_SECONDARY_COMMAND_BUFFERS_KHR flag promoted from the VK_EXT_nested_command_buffer extension allows the contents of a render pass subpass to be recorded both inline and in secondary command buffers executed with vkCmdExecuteCommands.

To query information regarding layered implementations, chain the following to vkGetPhysicalDeviceProperties2.

Where:

In the above, vendorID, deviceID, and deviceName are similar to members of the same name in VkPhysicalDeviceProperties. layeredAPI is an enum that identifies the underlying API of the layered implementation, for example VK_PHYSICAL_DEVICE_LAYERED_API_D3D12_KHR if the layer implements the D3D12 API.

In the presence of multiple layers, the contents of pLayeredApis[0] corresponds to the bottom-most layer, with the following indices (if any) ordered by layer order. This allows applications who are purely interested in the ultimate vendor ID or API that is executing the commands to avoid querying the layer count, always provide a layeredApiCount of 1, and inspect only pLayeredApis[0].

To query API-specific details of the layered implementation, an API-specific struct can be chained to VkPhysicalDeviceLayeredApiPropertiesKHR. For layered Vulkan implementations (i.e. VK_PHYSICAL_DEVICE_LAYERED_API_VULKAN_KHR) this extension introduces VkPhysicalDeviceLayeredApiVulkanPropertiesKHR to be chained, with structs for other APIs potentially added in future extensions. The implementation will fill in the chained struct that corresponds to the layered API, and leave structs for other APIs untouched. This allows the application to chain structs for multiple APIs and retrieve all necessary information in a single query.

In the above struct, the application may additionally chain VkPhysicalDeviceDriverProperties and VkPhysicalDeviceIDProperties to properties to extract further information from the underlying Vulkan device. properties.properties.limits and properties.properties.sparseProperties will however be 0-initialized and will not contain meaningful values.

For example, an application running through Mesa’s Venus, atop Mesa’s Dozen, atop the Nvidia proprietary D3D12 implementation would receive:

In the above example, the properties of the top layer (Mesa’s Venus) will be returned as usual in VkPhysicalDeviceProperties2. Note: if there are layers underneath a non-Vulkan implementation, they may not be visible in this query. For example, if the application is running through Mesa’s Dozen, atop VKD3D-proton and so on, the query may return layered implementations only up to Mesa’s Dozen as other APIs may lack such a query.

The VkPhysicalDeviceLayeredApiKHR enum is defined as:

A dedicated struct VkPhysicalDeviceLayeredApiVulkanPropertiesKHR should be used, with a VkPhysicalDeviceProperties2 member. Additional information can be queried by chaining VkPhysicalDeviceDriverProperties and VkPhysicalDeviceIDProperties structs to that member.

Chaining VkPhysicalDeviceProperties2, VkPhysicalDeviceDriverProperties and VkPhysicalDeviceIDProperties directly to VkPhysicalDeviceLayeredApiPropertiesKHR can be confusing for a number of reasons. In particular, VkPhysicalDeviceProperties2 is a "root" structure which can accept VkPhysicalDeviceDriverProperties and VkPhysicalDeviceIDProperties in its chain; allowing those structs to be chained to VkPhysicalDeviceLayeredApiPropertiesKHR means that it would be valid for an application to create a chain such as VkPhysicalDeviceLayeredApiPropertiesKHR → VkPhysicalDeviceDriverProperties → VkPhysicalDeviceProperties2 which can be confusing.

A future extension could also provide functionality to query properties of another layered API, such as D3D. This extension allows the API-specific structs to be chained to VkPhysicalDeviceLayeredApiPropertiesKHR to facilitate querying all information at once, which means the pNext chain of VkPhysicalDeviceLayeredApiPropertiesKHR could include property structs for both Vulkan and D3D for example. Allowing multiple structs per API, potentially interleaved would just add to the confusion.

By wrapping VkPhysicalDeviceProperties2 in a VkPhysicalDeviceLayeredApiVulkanPropertiesKHR struct, the pNext chain of VkPhysicalDeviceLayeredApiPropertiesKHR would contain only one struct per API, and avoid confusion in drivers, applications and validation layers.