VK_EXT_descriptor_buffer

Descriptors in Vulkan as it stands are generally considered quite abstract. They do not have a size, and when creating descriptor pools it is only specified how many descriptors can be allocated.

This abstraction is removed by the proposal and it assumes that a VkDescriptorSetLayout can be expressed as a list of binding points with a known:

The element size depends on the descriptor type and is a property of the physical device.

Implementations are free to control the byte offset, and so can freely repack descriptors for optimal memory access. For exact control over byte offsets for different descriptors, descriptor indexing should be used, since arrays have guaranteed packing.

If we think in terms of VkDescriptorPool with this model, an implementation of that could be something like an arena allocator where size is derived from the descriptor counts, and a VkDescriptorSet with VkDescriptorSetLayout just allocates a certain number of bytes from the pool. This is essentially the same model as VkBuffer and VkImage allocation.

When we call vkCmdBindDescriptorSets, what we are really doing is binding a buffer of a certain size. The shader compiler looks at VkPipelineLayout and based on the DescriptorSet and Binding decorations, it can look up that a descriptor can be read from the bound descriptor set at a specific offset.

As VK_EXT_descriptor_indexing is required, its descriptor limits apply.

This extension introduces new commands to put shader-accessible descriptors directly in memory. Properties of descriptor set layouts may vary based on enabled device features, so new device-level functions are added to query the properties of layouts. These calls are invariant across the lifetime of the device, and between VkDevice objects created from the same physical device(s), with the same creation parameters.

Applications are responsible for writing data into memory, but the application does not control the memory location directly – descriptor set layouts dictate where each descriptor lives, so that the shader interface continues to work as-is with set and binding numbers.

The size and offset of descriptors is exposed to applications, so they know how to copy it into memory. This is important since applications are free to copy descriptors on the device itself.

The sizes for different descriptor types are defined in the properties: samplerDescriptorSize, combinedImageSamplerDescriptorSize, sampledImageDescriptorSize, storageImageDescriptorSize, uniformTexelBufferDescriptorSize, robustUniformTexelBufferDescriptorSize, storageTexelBufferDescriptorSize, robustStorageTexelBufferDescriptorSize, uniformBufferDescriptorSize, robustUniformBufferDescriptorSize, storageBufferDescriptorSize, robustStorageBufferDescriptorSize, inputAttachmentDescriptorSize, accelerationStructureDescriptorSize, combinedImageSamplerDensityMapDescriptorSize.

Descriptor arrays have guaranteed packing, such that each element of an array for a given binding has an offset from that binding’s base offset equal to the size of the descriptor multiplied by the array offset. Bindings can be moved around as the driver sees fit, but variable-sized descriptor arrays must be packed at the end.

For use cases where layouts contain a variable-sized descriptor count, the size returned reflects the upper bound described in the descriptor set layout. The size required for a descriptor set layout with a variable size descriptor array can be obtained by adding the product of the number of descriptors that are actually used and the size of the descriptor.

Descriptor set layouts used for this purpose must be created with a new create flag:

Layouts created with this flag must not be used to create a VkDescriptorSet and must not include dynamic uniform buffers or dynamic storage buffers. Applications can achieve the same dynamic offsetting by either updating a descriptor buffer, using push constants, or by using push descriptors. The blob of memory corresponding to a descriptor is obtained from resource views directly. How applications get that data into device memory is entirely up to them, but the offset must match that obtained from the layout.

These APIs extract raw descriptor blob data from objects. The data obtained from these calls can be freely copied around. Note that these calls do not know anything about descriptor set layouts. It is the application’s responsibility to write descriptors to a suitable location.

A notable change here is that there is no longer any need for VkBufferView objects. Texel buffers are built from buffer device addresses and format instead. This improvement is motivated by DX12 portability. In some use cases, texel buffers are linearly allocated and having to create and manage a large number of unique view objects is problematic. With descriptor buffers, this style of API is now feasible in Vulkan.

A similar improvement is that uniform buffers and storage buffer also take buffer device addresses.

Acceleration structure descriptors are also built from device addresses, or handles retrieved from vkGetAccelerationStructureHandleNV when using VkAccelerationStructureNV objects.

Inline uniform buffers do not have a descriptor data getter API associated with them. Instead, the descriptor data is copied directly into the buffer offset obtained by vkGetDescriptorSetLayoutBindingOffsetEXT. As the name suggests, inline uniform buffers are embedded into the descriptor set itself.

As descriptors are now in regular memory, drivers cannot hide copies of immutable samplers that end up in descriptor sets from the application. As such, applications are required to provide these samplers as if they were not provided immutably. These samplers must have identical parameters to the immutable samplers in the descriptor set layout. Alternatively, applications can use dedicated descriptor sets for immutable samplers that do not require app-managed memory, by embedding them in a special descriptor set.

If the descriptorBufferImageLayoutIgnored feature is enabled, the imageLayout in VkDescriptorImageInfo is ignored, otherwise it specifies the layout that the descriptor will be used with. type must not be VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC or VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC. 'format' in VkDescriptorAddressInfoEXT is ignored for non-texel buffers.

The combinedImageSamplerDescriptorSingleArray property indicates that the implementation does not require an array of VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER descriptors to be written into a descriptor buffer as an array of image descriptors, immediately followed by an array of sampler descriptors. If VK_FALSE, applications are expected to write the first sampledImageDescriptorSize bytes of the data returned through pDescriptor to the first array, and the remaining samplerDescriptorSize bytes of the data to the second array. On these implementations, variable descriptor counts of combined image samplers may be supported, but it is not useful as the descriptor set size must assume the upper bound.

To use pipelines with descriptor buffers a new VkPipelineCreateFlag must be used:

Descriptor buffers are bound to the command buffer directly (similar to vertex buffers).

Unlike binding descriptor sets, there’s no invalidating going on with this binding – a buffer remains bound and is interpreted by a pipeline in the manner the pipeline expects, irrespective of what layout was used to construct the buffer for each set.

There must be no more than maxSamplerDescriptorBufferBindings descriptor buffers containing sampler descriptor data bound. Such buffers must be created with VK_BUFFER_USAGE_SAMPLER_DESCRIPTOR_BUFFER_BIT_EXT.

There must be no more than maxResourceDescriptorBufferBindings descriptor buffers containing resource descriptors bound. Such buffers must be bound with VK_BUFFER_USAGE_RESOURCE_DESCRIPTOR_BUFFER_BIT_EXT.

If a buffer contains both usage flags, it counts once against both limits.

If the bufferlessPushDescriptors property is VK_FALSE and a buffer contains the VK_BUFFER_USAGE_PUSH_DESCRIPTORS_DESCRIPTOR_BUFFER_BIT usage flag, a VkDescriptorBufferBindingPushDescriptorBufferHandleEXT structure must be added to the pNext chain of VkDescriptorBufferBindingInfoEXT.

bufferCount must be less than or equal to maxDescriptorBufferBindings.

Any previously bound buffers at binding points greater than or equal to bufferCount are unbound.

Each entry in pBindingInfos contains the device address of a descriptor buffer and the usage flags that the buffer was created with.

Changing buffers may be an expensive operation and should be done infrequently (if ever).

The maximum available range of each binding to a shader is maxSamplerDescriptorBufferRange and/or maxResourceDescriptorBufferRange.

The samplerDescriptorBufferAddressSpaceSize, resourceDescriptorBufferAddressSpaceSize, and descriptorBufferAddressSpaceSize properties give the upper bound for the total amount of address space used for descriptor buffers.

Buffers used for this purpose need to be created with a new usage flags:

VK_BUFFER_USAGE_SAMPLER_DESCRIPTOR_BUFFER_BIT_EXT specifies that the buffer will be used to contain sampler descriptors when bound as a descriptor buffer. VK_BUFFER_USAGE_RESOURCE_DESCRIPTOR_BUFFER_BIT_EXT specifies that the buffer will be used to contain resource descriptors, i.e. non-sampler descriptors, when bound as a descriptor buffer. Buffers containing VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER descriptors must have been created with both VK_BUFFER_USAGE_SAMPLER_DESCRIPTOR_BUFFER_BIT_EXT and VK_BUFFER_USAGE_RESOURCE_DESCRIPTOR_BUFFER_BIT_EXT.

Each descriptor set is associated with a buffer and an offset into that buffer which can be set by:

vkCmdSetDescriptorBufferOffsetsEXT causes the sets numbered [firstSet.. firstSet+setCount-1] to use the bindings stored in the buffer bound at pBufferIndices[i] at an offset of pOffsets[i] for subsequent bound pipeline commands set by pipelineBindPoint. Any bindings that were previously applied via these sets, or calls to vkCmdBindDescriptorSets, are no longer valid. Calling vkCmdBindDescriptorSets invalidates bindings previously applied via vkCmdSetDescriptorBufferOffsetsEXT.

Setting offsets should be a cheap operation and can be performed frequently. The offsets must be aligned to descriptorBufferOffsetAlignment.

Embedded immutable samplers can be bound using:

vkCmdBindDescriptorBufferEmbeddedSamplersEXT binds the embedded immutable samplers in layout at set index set to the same set in the command buffer. Set bindings are invalidated in the same manner as they are for vkCmdSetDescriptorBufferOffsetEXT. The VkDescriptorSetLayout at index set of layout must have been created with the VK_DESCRIPTOR_SET_LAYOUT_CREATE_EMBEDDED_IMMUTABLE_SAMPLERS_BIT_EXT bit. There must be no more than maxEmbeddedImmutableSamplerBindings embedded immutable sampler sets bound. Like DX12, there is a limit to how many unique embedded immutable samplers may be alive in a device at any one point. This limit is designed to match DX12.

As descriptors are just a blob of memory, descriptor updates can be performed by any operation on either the host or device that can access memory, enabling a form of GPU descriptor update. Descriptor buffer reads can be synchronized using a new access bit in the relevant shader stage:

Note that host writes are implicitly made visible to all stages in vkQueueSubmit, so this access flag is only relevant when performing GPU-side updates of descriptors.

If the allowSamplerImageViewPostSubmitCreation property is VK_FALSE there are special requirements for when descriptor data for VkSampler or VkImageView objects can be used. Those objects must have been created before any vkQueueSubmit (or vkQueueSubmit2) call that executes a command buffer which accesses descriptor data for them.

For example, if allowSamplerImageViewPostSubmitCreation is VK_FALSE, this is disallowed:

Support for descriptor buffers combined with push descriptors is supported if the descriptorBufferPushDescriptors feature bit is set.

To support push descriptors on certain implementations, additional buffer usage flags are added:

If the application desires to use push descriptors and descriptor buffers together, a descriptor set layout must be declared with VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR and VK_DESCRIPTOR_SET_LAYOUT_CREATE_DESCRIPTOR_BUFFER_BIT_EXT bits set.

If the bufferlessPushDescriptors property is VK_FALSE, there are special requirements for using push descriptors with descriptor buffers. VK_BUFFER_USAGE_PUSH_DESCRIPTORS_DESCRIPTOR_BUFFER_BIT_EXT is a special buffer flag which is required for certain implementations in order for push descriptors to interoperate with descriptor buffers. When pushing descriptors using this kind of set layout, it is required that a descriptor buffer is bound to the command list with the VK_BUFFER_USAGE_PUSH_DESCRIPTORS_DESCRIPTOR_BUFFER_BIT_EXT usage flag. The intention here is that implementation can reserve scratch space in descriptor buffers for the purposes of dealing with push descriptors. The mechanics here are highly magical and implementation defined in nature and is considered too burdensome to expect that applications deal with it.

Binding a buffer that was created with VK_BUFFER_USAGE_PUSH_DESCRIPTORS_DESCRIPTOR_BUFFER_BIT_EXT requires the application to record any current push descriptors again.

When creating a resource with the capture/replay feature enabled, an opaque handle can be obtained which can be passed into creation calls in a future replay, causing descriptors to be created with the same data.

New flags to be supplied when creating buffers, images, and samplers to be captured/replayed:

There are separate commands to get opaque data for buffers, images, and samplers:

Once queried, this must be provided to buffer/image/imageview/sampler/acceleration structure creation in a similar manner to buffer device address creation, by chaining the following structure to buffer, image, imageview, sampler, or acceleration structure creation:

In each case, the size of the capture data is sized to the bufferCaptureReplayDescriptorDataSize, imageCaptureReplayDescriptorDataSize, imageViewCaptureReplayDescriptorDataSize, samplerCaptureReplayDescriptorDataSize, or accelerationStructureCaptureReplayDescriptorDataSize limits as appropriate.

In addition, vkGetDeviceMemoryOpaqueCaptureAddress must be used to capture the opaque address and replay it with VkMemoryOpaqueCaptureAddressAllocateInfo, for any memory used by resources with these handles.

The following features are exposed:

If the descriptorBuffer feature is enabled, VK_AMD_shader_fragment_mask must not be enabled. If the descriptorBufferImageLayoutIgnored feature is enabled, the image layout provided when getting a descriptor is ignored. The descriptorBufferCaptureReplay feature is primarily for capture replay tools, and allows opaque data to be captured and replayed, allowing the same descriptor handles to be used on replay. If the descriptorBufferPushDescriptors features is enabled push descriptors can be used with descriptor buffers.

The following properties are exposed:

If VK_VALVE_mutable_descriptor_type is used, a descriptor is considered to be a union of all the enabled types, so the size of a descriptor is the maximum of all enabled types.

DX12 has the following command to create a heap:

Implementing the equivalent functionality in Vulkan would mean the following operations:

This model would support the full TIER_3 resource binding feature in DX12 and shader model 6.6 direct heap access, but can be simplified a lot for applications with DX11-style binding models.

Unlike DX12, Vulkan (and this extension) requires view objects and sampler objects to exist and have their lifetimes managed by the application. These objects need to be kept alive for the descriptor itself to be valid. How this is managed precisely is going to depend on the application’s usage patterns, though vkd3d-proton suggests one viable option. The scheme used by vkd3d-proton involves keeping a hash map of the views associated with each resource object (or the device for samplers), using creation parameters as a key, so that their lifetime is tied to the underlying resource and can be reused. When actually creating the UAV/SRV/Sampler, the object should be looked up in the relevant hash map, and created there if necessary. The descriptor itself is then written directly to the provided CPU pointer. Note that 'VkBufferView' objects are not used and have been replaced by an explicit address, range, and format. This is very important since applications have a tendency to linearly allocate texel buffers and might end up rapidly create these views at different offsets. If applications were forced to hold on to all unique 'VkBufferView' objects, things get out of hand quickly. vkd3d-proton currently works around this problem by quantizing the texel buffer offset and range, and instead performs offset/range checks per access in shaders to keep the number of objects low, which is obviously not desirable.

For image views on the other hand, the number of unique views in flight per resource tends to be constrained and manageable. In terms of performance characteristics, creating SRVs and UAVs is already far more expensive in DX12 than copying descriptors. The style observed in most DX12 applications is that view objects are created in non-shader visible heaps, which are then streamed into shader visible heaps.

Descriptor heaps provide methods to query the “start” pointer for the descriptor heap on both the CPU and GPU.

GetGPUDescriptorHandleForHeapStart should be the VkDeviceAddress for the device-local buffer. GetCPUDescriptorHandleForHeapStart should be the mapped host address for the host-visible buffer. GetDescriptorHandleIncrementSize should be the size of the largest descriptor possible in the buffer.

However, this model can fall through fairly quickly if the descriptor set layout is more complicated. When more than one descriptor array is used to emulate the union-style descriptor heap of DX12, it is not possible to provide a unique pointer to host memory that is suitable for copying.

An engine abstraction that takes descriptor heap and offset separately is much easier to implement overall and avoids all these pitfalls.

D3D12-style descriptor copies can be performed using memcpy on the host-visible descriptor buffer memory, but applications need to make sure the memory that is being read from is cached on the host. Alternatively, it is possible to use staging buffer copies.

Binding descriptors to shaders in DX12 consists of two operations: setting the descriptor heaps, and setting tables as offsets into those heaps.

SetDescriptorHeaps allows applications to set one sampler heap, and one CBV/SRV/UAV heap (containing other resources). This command should straightforwardly map to vkCmdBindDescriptorBuffersEXT, with each heap being bound as a separate buffer.

Set{Graphics|Compute}RootDescriptorTable allows applications to set various offsets to the descriptor heap, to be more or less used like descriptor sets in Vulkan. This command will map fairly directly to vkCmdSetDescriptorBufferOffsetsEXT, but if implementing DX12 root signatures natively, this approach will not work easily. The core assumption of DX12 is that the heap is a big array and a table offset should be seen more as an index offset into that big array. descriptorBufferOffsetAlignment might be larger than one descriptor, so binding at the desired offset might not be possible. Descriptor buffer offsets are better suited for suballocating individual descriptor sets rather than slicing existing descriptor sets.

An engine abstraction can decide to take this into account when allocating descriptor sets:

If native DX12 root signature compatibility is required however, the suggested implementation is to bind the heap in its entirety with a single vkCmdSetDescriptorBufferOffsetEXT of 0. The shader declares global unsized arrays and from there we can implement shader model 6.6 by just indexing into the descriptor array directly. For older models, descriptor table offsets can translate to u32 push constants that add an extra offset, meaning that we promote legacy root signatures to shader model 6.6. This is a fairly invasive process and it is only expected that translation layers would go to this length.

There may be cases where a driver needs immutable samplers stored as part of the descriptor, rather than solely existing as a part of the pipeline. With descriptor sets, this could be hidden from the application as the driver controlled how writes were performed – not so with this API. To fix this, samplers must be used to populate these descriptor bindings as if they were not immutable, and they must have been created with identical parameters.

For partity with DX12, a special kind of descriptor set - embedded immutable samplers - are supported as an alternative which follow DX12 restrictions.

No, these have very specialized support paths in some drivers, and end up being more pain than it’s worth to support. Applications can achieve the same using device addresses in push constants, or pipelined descriptor buffer updates.

There’s some extra complication with whether descriptor set layouts work with buffers or sets (VK_DESCRIPTOR_SET_LAYOUT_CREATE_DESCRIPTOR_BUFFER_BIT_EXT) that will need sorting. Shouldn’t be too difficult and will likely just be along the lines of invalidating sets that don’t match in this regard when binding a new pipeline layout, but it’s too much detail for this design document.

Guarantees about how arrays work makes it much easier to work with GPU-side updates, as it avoids having to either add a “get offset” shader intrinsic, or for apps to keep a mapping when doing GPU copies.

We should allow developers to put as many constants into descriptor buffers as they want, thus removing the limit, at least when it interacts with this extension. This is likely to remove an indirection compared to putting these in a uniform buffer. Potentially we might want to at least have it match the uniform buffer limit rather than being independent.

DX12 has dedicated heap objects which allow implementations to hide a lot of implementation detail behind them; without them, some vendors rely on view objects to store metadata. Introducing heaps to Vulkan as-is was too complex alongside the other changes in this extension, when the primary goal is to enable explicit memory management, rather than precise DX12 compatibility. If this turns out to be a significant problem, a future extension could be developed to bridge this gap.

No – there is no reason why pulling this loop into the driver should provide any benefit.

While some consider these deprecated, removing them would prevent some applications being able to port to this extension. Additionally, YCbCr support currently relies on this descriptor type, which is required on some platforms. It might be possible to remove that requirement in the YCbCr feature, but it is a lot of work for a fairly low payoff.

The variable flag is allowed; vkGetDescriptorSetLayoutSize returns a size assuming the maximum size will be used - but developers are free to use the set with a buffer sized for a smaller number of descriptors. The exception to this is when combinedImageSamplerDescriptorSingleArray is VK_FALSE and the binding contains VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER descriptors; in this case the image and sampler descriptors are still arranged in the descriptor buffer as though the maximum number of descriptors are used, and so the buffer must be sized accordingly.

Some vendors use non-zero values for null descriptors, so applications can retrieve these using VK_NULL_HANDLE with vkGetDescriptorEXT. For descriptor types which take buffer devices addresses, a 0 address is used instead.

YCbCr descriptors can have multiple descriptors associated with them; applications must allow for this space. VkSamplerYcbcrConversionImageFormatProperties::combinedImageSamplerDescriptorCount determines how many descriptors each image format requires. When calling vkGetDescriptorEXT for a YCbCr combined descriptor, applications must provide a pointer to enough memory for this many combined sampled image descriptors, and factor this in when copying descriptors.

A capture replay bit on image/buffer creation will be added to enable descriptors to be reused between runs. This allows capture tools to capture the buffer data as bound, and replay with the same descriptors, rather than attempting to do a mapping. Some sort of GPU feedback is still desirable on capture to determine which handles are accessed, but this will be similar to the situation with descriptor indexing.

This could be done a number of ways – e.g. having unique memory types that guarantee allocation in a 4GB range.

No - the alignment of a descriptor is always the size of the descriptor.

The crucial part of getting data into a shader quickly is mostly dominated by number of indirections, and cache behavior. Static accesses with fewer indirections and minimal memory model interactions (e.g. read-only and not NonPrivate) will be fastest. Push constants should be favored for small amounts of data. For larger amounts of data, applications should favor allocating buffers and putting data into those buffers according with whichever of the below API mechanisms is most straightforward for their use case, with some potential degradation at each step.

This order listed above is not necessarily true for all IHVs.

Originally the intention was to support this, but at least one vendor cannot support this natively.

Buffer parameters in recent extensions have been using device address arguments, so this extension aims to be consistent. Part of the reason for this though, is so that the base address can be modified with a single pointer argument instead of object + offset. However, this extension explicitly uses a separate command for setting the offset dynamically compared to the base address, to allow for the application to set the base address statically. Having the base address specified with a device address is still useful for consistency though.

There is no way to request robust and non-robust descriptors separately, or specify robust/non-robust descriptors in the set layout, so if the robustBufferAccess feature is enabled then robust descriptors are always used.