Function Prototype

vkWriteResourceDescriptorsEXT

Write resource descriptors to memory

To write resource descriptors to memory, call:

VkResult vkWriteResourceDescriptorsEXT(
    VkDevice                                                device,
    uint32_t                                                resourceCount,
    const VkResourceDescriptorInfoEXT*  pResources,
    const VkHostAddressRangeEXT*        pDescriptors);
  • device is the logical device that the descriptors are for.
  • resourceCount is the number of elements in pResources and pDescriptors.
  • pResources is a pointer to an array of VkResourceDescriptorInfoEXT structures defining properties of the resource descriptors that will be written.
  • pDescriptors is a pointer to an array of VkHostAddressRangeEXT structures defining the host address ranges that will be written to for each descriptor.

Each descriptor will be written to pDescriptors[i].address where i is the index of its create info in pResources.

If any image descriptor written by this command includes a VkSamplerYcbcrConversion, multiple descriptors will be written adjacent to each other for that descriptor, equal to VkSamplerYcbcrConversionImageFormatProperties::combinedImageSamplerDescriptorCount for the image.

If any image descriptor written by this command is for an image created with flags containing VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT, multiple descriptors will be written adjacent to each other for that descriptor, equal to VkSubsampledImageFormatPropertiesEXT::subsampledImageDescriptorCount for the image.

Descriptors using the same type and written using a fully identical VkTexelBufferDescriptorInfoEXT or VkDeviceAddressRangeEXT structure on the same VkDevice will always return the same bit pattern. If the descriptorHeapCaptureReplay feature is enabled, this applies to any VkDevice created with identical parameters from the same VkPhysicalDevice.

Recreating the same buffer descriptor during replay of a prior capture requires that the device address is the same, which requires additional data to be captured and provided during replay when creating a buffer and allocating memory for it.

Image descriptors using the same type and written using a fully identical VkImageDescriptorInfoEXT other than VkImageDescriptorInfoEXT::pView→image, where image was successfully created with VK_IMAGE_CREATE_DESCRIPTOR_HEAP_CAPTURE_REPLAY_BIT_EXT and a VkOpaqueCaptureDataCreateInfoEXT with data captured via vkGetImageOpaqueCaptureDataEXT from an image used previously, will write a descriptor with the same bit pattern if possible; if the same bit pattern cannot be generated, VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS will be returned instead.

Tensor descriptors using the same type and written using a fully identical VkTensorViewCreateInfoARM other than VkTensorViewCreateInfoARM::tensor, where tensor was successfully created with VkOpaqueCaptureDataCreateInfoEXT with VK_TENSOR_CREATE_DESCRIPTOR_HEAP_CAPTURE_REPLAY_BIT_ARM and a VkOpaqueCaptureDataCreateInfoEXT with data captured via vkGetTensorOpaqueCaptureDataARM from a tensor used previously, will write a descriptor with the same bit pattern if possible; if the same bit pattern cannot be generated, VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS will be returned instead.

Image creation is sufficiently complex that it may not be possible to recreate all possible descriptors from an image during replay, even if the image itself was successfully recreated. The conditions for this happening will be largely the same as those which could cause allocating a buffer with the same device address during replay to fail. Replay tools are advised to recreate captured descriptors for an image immediately after recreating the image itself wherever possible. The same is true for tensors.

Valid Usage

VUID-vkWriteResourceDescriptorsEXT-size-11207

The size member of each element of pDescriptors must be greater than or equal to the value returned by vkGetPhysicalDeviceDescriptorSizeEXT with a descriptorType equal to type

VUID-vkWriteResourceDescriptorsEXT-pResources-11208

If any element of pResources specifies a VkImageViewCreateInfo structure with a VkSamplerYcbcrConversionInfo structure in its pNext chain, the corresponding element of pDescriptors must have a size member that is greater than or equal to the product of the value returned by vkGetPhysicalDeviceDescriptorSizeEXT with a descriptorType equal to type and VkSamplerYcbcrConversionImageFormatProperties::combinedImageSamplerDescriptorCount, as queried from VkPhysicalDeviceImageFormatInfo2 with image format info equivalent to the image view the descriptor is being created for

VUID-vkWriteResourceDescriptorsEXT-pResources-11209

If any element of pResources specifies a VkImageViewCreateInfo structure with an image created with flags containing VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT, the corresponding element of pDescriptors must have a size member that is greater than or equal to the product of the value returned by vkGetPhysicalDeviceDescriptorSizeEXT with a descriptorType equal to type and VkSubsampledImageFormatPropertiesEXT::subsampledImageDescriptorCount, as queried from VkPhysicalDeviceImageFormatInfo2 with image format info equivalent to the image view the descriptor is being created for

Valid Usage (Implicit)

VUID-vkWriteResourceDescriptorsEXT-pResources-parameter

pResources must be a valid pointer to an array of resourceCount valid VkResourceDescriptorInfoEXT structures

VUID-vkWriteResourceDescriptorsEXT-pDescriptors-parameter

pDescriptors must be a valid pointer to an array of resourceCount valid VkHostAddressRangeEXT structures