VkDescriptorSetAndBindingMappingEXT(3)

# VkDescriptorSetAndBindingMappingEXT(3) Manual Page

## Name

VkDescriptorSetAndBindingMappingEXT - Structure specifying mappings from a set of shader resources to a descriptor heap

## C Specification

The `VkDescriptorSetAndBindingMappingEXT` structure is defined as:

    // Provided by VK_EXT_descriptor_heap
    typedef struct VkDescriptorSetAndBindingMappingEXT {
        VkStructureType                     sType;
        const void*                         pNext;
        uint32_t                            descriptorSet;
        uint32_t                            firstBinding;
        uint32_t                            bindingCount;
        VkSpirvResourceTypeFlagsEXT         resourceMask;
        VkDescriptorMappingSourceEXT        source;
        VkDescriptorMappingSourceDataEXT    sourceData;
    } VkDescriptorSetAndBindingMappingEXT;

## Members

- `sType` is a VkStructureType value identifying this structure.

- `pNext` is `NULL` or a pointer to a structure extending this structure.

- `descriptorSet` is the value of `DescriptorSet` for resources that this mapping affects.

- `firstBinding` is the first value of `Binding` of resources that this mapping affects.

- `bindingCount` is the number of consecutive `Binding` values of resources that this mapping affects.

- `resourceMask` is a mask of VkSpirvResourceTypeFlagBitsEXT values indicating which resource types are specified by this mapping.

- `source` is a VkDescriptorMappingSourceEXT value specifying the method of mapping specified for the affected resources.

- `sourceData` is a VkDescriptorMappingSourceDataEXT that provides the details of how each mapping is specified according to `source`.

## Description

Resources specified in a shader with a `DescriptorSet` decoration set to `descriptorSet`, a `Binding` decoration greater than or equal to `firstBinding` and less than the sum of `firstBinding` and `bindingCount`, and a resource type matching one of the bits in `resourceMask` will be mapped according to `source` and `sourceData`.

Note | Applications are free to overspecify bindings that are not present; allowing reuse of the same mapping structures with multiple shaders, even when those shaders only partially reuse those mappings. This includes things like setting binding counts higher than the number used in the shader, specifying bindings that are not present in the shader, and setting `resourceMask` to all possible resources that may be encountered.

If `source` selects an element of `sourceData` defined by a structure, the description of that structure defines how resources are mapped. Source mappings using a single base type are defined here.

If `source` is VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_CONSTANT_OFFSET_EXT, the resource will be backed by heap data as specified by `constantOffset`.

If `source` is VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_PUSH_INDEX_EXT, the resource will be backed by heap data as specified by `pushIndex`.

If `source` is VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_INDIRECT_INDEX_EXT, the resource will be backed by heap data as specified by `indirectIndex`.

If `source` is VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_INDIRECT_INDEX_ARRAY_EXT, the resource will be backed by heap data as specified by `indirectIndexArray`.

If `source` is VK_DESCRIPTOR_MAPPING_SOURCE_RESOURCE_HEAP_DATA_EXT, the resource will be backed by heap data as specified by `heapData`.

If `source` is VK_DESCRIPTOR_MAPPING_SOURCE_PUSH_DATA_EXT, the resource will be backed by push data at a range from `pushDataOffset` to the size of the resource, allowing a uniform buffer to be backed by push data access push data. Accessing data in the uniform buffer at an offset of shaderOffset in the shader will access push data at an offset equal to

  offset = shaderOffset + pushDataOffset.

If `source` is VK_DESCRIPTOR_MAPPING_SOURCE_PUSH_ADDRESS_EXT, the resource will be backed by data pointed to by a device address in push data at an offset of `pushAddressOffset`. Accessing data via the mapped resource in the shader will access data backing the address specified in push data:

  address = ((VkDeviceAddress*)pPushData)[pushAddressOffset/8]

where pPushData is the total set of push data specified by vkCmdPushDataEXT. If the shader resource is an acceleration structure, the address must be a valid acceleration structure address.

If `source` is VK_DESCRIPTOR_MAPPING_SOURCE_INDIRECT_ADDRESS_EXT, the resource will be backed by heap data as specified by `indirectAddress`.

Note | Accesses to resources using mappings to anything that is not a descriptor in a heap are not subject to robustness guarantees; resources for such mappings must not be accessed out of bounds.

If `source` is VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_SHADER_RECORD_INDEX_EXT, the resource will be backed by heap data as specified by `shaderRecordIndex`.

If `source` is VK_DESCRIPTOR_MAPPING_SOURCE_SHADER_RECORD_DATA_EXT, the resource will be backed by shader record data at a range from `shaderRecordDataOffset` to the size of the resource, allowing a uniform buffer to be used as a way to access shader record data. Accessing data in the uniform buffer at an offset shaderOffset in the shader will access shader record data at an offset equal to

  offset = shaderOffset + shaderRecordDataOffset.

If `source` is VK_DESCRIPTOR_MAPPING_SOURCE_SHADER_RECORD_ADDRESS_EXT, the resource will be backed by data pointed to by a device address in the shader record at `shaderRecordAddressOffset`. Accessing data via the mapped resource in the shader will access data backing the address specified in shader record data:

  address = ((VkDeviceAddress*)pShaderRecordData)[shaderRecordAddressOffset/8]

where pShaderRecord is the memory associated with a given shader as its shader record. If the shader resource is an acceleration structure, the address must be a valid acceleration structure address.

Note | Accesses to resources using VK_DESCRIPTOR_MAPPING_SOURCE_SHADER_RECORD_ADDRESS_EXT mappings are not subject to robustness guarantees; data must not be accessed outside of the allocated memory range.

Mappings must be declared for all variables with a `DescriptorSet` and `Binding` in the shader resource interface.

Valid Usage

- VUID-VkDescriptorSetAndBindingMappingEXT-source-11245
  If `source` is VK_DESCRIPTOR_MAPPING_SOURCE_PUSH_DATA_EXT, VK_DESCRIPTOR_MAPPING_SOURCE_PUSH_ADDRESS_EXT, VK_DESCRIPTOR_MAPPING_SOURCE_INDIRECT_ADDRESS_EXT, or VK_DESCRIPTOR_MAPPING_SOURCE_RESOURCE_HEAP_DATA_EXT, `bindingCount` must be 1

- VUID-VkDescriptorSetAndBindingMappingEXT-source-11246
  If `source` is VK_DESCRIPTOR_MAPPING_SOURCE_PUSH_DATA_EXT, `sourceData.pushDataOffset` must be a multiple of 4

- VUID-VkDescriptorSetAndBindingMappingEXT-source-12452
  If `source` is VK_DESCRIPTOR_MAPPING_SOURCE_PUSH_DATA_EXT, `sourceData.pushDataOffset` must be less than or equal to `maxPushDataSize` - 4

- VUID-VkDescriptorSetAndBindingMappingEXT-source-11247
  If `source` is VK_DESCRIPTOR_MAPPING_SOURCE_PUSH_ADDRESS_EXT, `sourceData.pushAddressOffset` must be a multiple of 8

- VUID-VkDescriptorSetAndBindingMappingEXT-source-12453
  If `source` is VK_DESCRIPTOR_MAPPING_SOURCE_PUSH_ADDRESS_EXT, `sourceData.pushAddressOffset` must be less than or equal to `maxPushDataSize` - 8

- VUID-VkDescriptorSetAndBindingMappingEXT-source-11248
  If `source` is VK_DESCRIPTOR_MAPPING_SOURCE_SHADER_RECORD_DATA_EXT or VK_DESCRIPTOR_MAPPING_SOURCE_SHADER_RECORD_ADDRESS_EXT, `bindingCount` must be 1

- VUID-VkDescriptorSetAndBindingMappingEXT-source-11249
  If `source` is VK_DESCRIPTOR_MAPPING_SOURCE_SHADER_RECORD_DATA_EXT, `sourceData.shaderRecordDataOffset` must be a multiple of 4

- VUID-VkDescriptorSetAndBindingMappingEXT-source-11250
  If `source` is VK_DESCRIPTOR_MAPPING_SOURCE_SHADER_RECORD_ADDRESS_EXT, `sourceData.shaderRecordAddressOffset` must be a multiple of 8

- VUID-VkDescriptorSetAndBindingMappingEXT-source-11251
  If `source` is VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_CONSTANT_OFFSET_EXT, VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_PUSH_INDEX_EXT, VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_INDIRECT_INDEX_EXT, VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_INDIRECT_INDEX_ARRAY_EXT, or VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_SHADER_RECORD_INDEX_EXT, and `descriptorSet`, `firstBinding`, and `bindingCount` identify any `OpTypeImage` variables, any `heapOffset`, and `heapArrayStride` members of the corresponding member of `sourceData` must be 0 or a multiple of `imageDescriptorAlignment`

- VUID-VkDescriptorSetAndBindingMappingEXT-source-11252
  If `source` is VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_CONSTANT_OFFSET_EXT, VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_PUSH_INDEX_EXT, VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_INDIRECT_INDEX_EXT, VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_INDIRECT_INDEX_ARRAY_EXT, or VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_SHADER_RECORD_INDEX_EXT, and `descriptorSet`, `firstBinding`, and `bindingCount` identify any `OpTypeStruct` variables, any `heapOffset`, and `heapArrayStride` members of the corresponding member of `sourceData` must be 0 or a multiple of `bufferDescriptorAlignment`

- VUID-VkDescriptorSetAndBindingMappingEXT-source-11253
  If `source` is VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_CONSTANT_OFFSET_EXT, VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_PUSH_INDEX_EXT, VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_INDIRECT_INDEX_EXT, VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_INDIRECT_INDEX_ARRAY_EXT, or VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_SHADER_RECORD_INDEX_EXT, and `descriptorSet`, `firstBinding`, and `bindingCount` identify any `OpTypeSampler` variables, any `heapOffset` and `heapArrayStride` members of the corresponding member of `sourceData` must be 0 or a multiple of `samplerDescriptorAlignment`

- VUID-VkDescriptorSetAndBindingMappingEXT-source-11254
  If `source` is VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_CONSTANT_OFFSET_EXT, VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_PUSH_INDEX_EXT, VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_INDIRECT_INDEX_EXT, VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_INDIRECT_INDEX_ARRAY_EXT, or VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_SHADER_RECORD_INDEX_EXT, and `descriptorSet`, `firstBinding`, and `bindingCount` identify any `OpTypeSampledImage` variables, and `pEmbeddedSampler` is `NULL`, then any `samplerHeapOffset` and `samplerHeapArrayStride` members of the corresponding member of `sourceData` must be 0 or a multiple of `samplerDescriptorAlignment`

- VUID-VkDescriptorSetAndBindingMappingEXT-source-12406
  If `source` is VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_CONSTANT_OFFSET_EXT, VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_PUSH_INDEX_EXT, VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_INDIRECT_INDEX_EXT, VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_INDIRECT_INDEX_ARRAY_EXT, or VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_SHADER_RECORD_INDEX_EXT, and `descriptorSet`, `firstBinding`, and `bindingCount` identify any `OpTypeSampledImage` variables, any `heapOffset` and `heapArrayStride` members of the corresponding member of `sourceData` must be 0 or a multiple of `imageDescriptorAlignment`

- VUID-VkDescriptorSetAndBindingMappingEXT-source-12456
  If `source` is VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_PUSH_INDEX_EXT, and `descriptorSet`, `firstBinding`, and `bindingCount` identify any `OpTypeSampledImage` variables, and `pEmbeddedSampler` is `NULL`, `samplerPushOffset` must be a multiple of 4

- VUID-VkDescriptorSetAndBindingMappingEXT-source-12457
  If `source` is VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_PUSH_INDEX_EXT, and `descriptorSet`, `firstBinding`, and `bindingCount` identify any `OpTypeSampledImage` variables, and `pEmbeddedSampler` is `NULL`, `samplerPushOffset` must be less than or equal to `maxPushDataSize` - 4

- VUID-VkDescriptorSetAndBindingMappingEXT-source-12458
  If `source` is VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_INDIRECT_INDEX_EXT or VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_INDIRECT_INDEX_ARRAY_EXT, and `descriptorSet`, `firstBinding`, and `bindingCount` identify any `OpTypeSampledImage` variables, and `pEmbeddedSampler` is `NULL`, `samplerPushOffset` must be a multiple of 8

- VUID-VkDescriptorSetAndBindingMappingEXT-source-12459
  If `source` is VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_INDIRECT_INDEX_EXT or VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_INDIRECT_INDEX_ARRAY_EXT, and `descriptorSet`, `firstBinding`, and `bindingCount` identify any `OpTypeSampledImage` variables, and `pEmbeddedSampler` is `NULL`, `samplerPushOffset` must be less than or equal to `maxPushDataSize` - 8

- VUID-VkDescriptorSetAndBindingMappingEXT-source-12460
  If `source` is VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_INDIRECT_INDEX_EXT or VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_INDIRECT_INDEX_ARRAY_EXT, and `descriptorSet`, `firstBinding`, and `bindingCount` identify any `OpTypeSampledImage` variables, and `pEmbeddedSampler` is `NULL`, `samplerAddressOffset` must be a multiple of 4

- VUID-VkDescriptorSetAndBindingMappingEXT-source-11356
  If `source` is VK_DESCRIPTOR_MAPPING_SOURCE_RESOURCE_HEAP_DATA_EXT, VK_DESCRIPTOR_MAPPING_SOURCE_SHADER_RECORD_DATA_EXT, or VK_DESCRIPTOR_MAPPING_SOURCE_PUSH_DATA_EXT, `resourceMask` must include VK_SPIRV_RESOURCE_TYPE_UNIFORM_BUFFER_BIT_EXT

- VUID-VkDescriptorSetAndBindingMappingEXT-source-11357
  If `source` is VK_DESCRIPTOR_MAPPING_SOURCE_SHADER_RECORD_ADDRESS_EXT or VK_DESCRIPTOR_MAPPING_SOURCE_PUSH_ADDRESS_EXT, `resourceMask` must include at least one of VK_SPIRV_RESOURCE_TYPE_UNIFORM_BUFFER_BIT_EXT, VK_SPIRV_RESOURCE_TYPE_READ_ONLY_STORAGE_BUFFER_BIT_EXT, VK_SPIRV_RESOURCE_TYPE_READ_WRITE_STORAGE_BUFFER_BIT_EXT, or VK_SPIRV_RESOURCE_TYPE_ACCELERATION_STRUCTURE_BIT_EXT

- VUID-VkDescriptorSetAndBindingMappingEXT-source-11358
  If `source` is VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_SHADER_RECORD_INDEX_EXT, VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_PUSH_INDEX_EXT, or VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_INDIRECT_INDEX_EXT, VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_INDIRECT_INDEX_ARRAY_EXT, and the mapping sets `useCombinedImageSamplerIndex` to VK_TRUE, `resourceMask` must include at least one of VK_SPIRV_RESOURCE_TYPE_COMBINED_SAMPLED_IMAGE_BIT_EXT, VK_SPIRV_RESOURCE_TYPE_SAMPLED_IMAGE_BIT_EXT, or VK_SPIRV_RESOURCE_TYPE_SAMPLER_BIT_EXT

- VUID-VkDescriptorSetAndBindingMappingEXT-source-11389
  If `source` is VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_CONSTANT_OFFSET_EXT, VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_PUSH_INDEX_EXT, VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_SHADER_RECORD_INDEX_EXT, VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_INDIRECT_INDEX_EXT, or VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_INDIRECT_INDEX_ARRAY_EXT, and `bindingCount` is not `1`, the `pEmbeddedSampler` member of the corresponding mapping structure must be `NULL`

- VUID-VkDescriptorSetAndBindingMappingEXT-source-11390
  If `source` is VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_CONSTANT_OFFSET_EXT, VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_PUSH_INDEX_EXT, VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_SHADER_RECORD_INDEX_EXT, VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_INDIRECT_INDEX_EXT, or VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_INDIRECT_INDEX_ARRAY_EXT, and `descriptorSet`, `firstBinding`, and `bindingCount` identify any `OpTypeTensorARM` variables, the `heapOffset`, and `heapArrayStride` members of the corresponding member of `sourceData` must be 0 or a multiple of `tensorDescriptorAlignment`

Valid Usage (Implicit)

- VUID-VkDescriptorSetAndBindingMappingEXT-sType-sType
  `sType` must be VK_STRUCTURE_TYPE_DESCRIPTOR_SET_AND_BINDING_MAPPING_EXT

- VUID-VkDescriptorSetAndBindingMappingEXT-pNext-pNext
  `pNext` must be `NULL` or a pointer to a valid instance of VkPushConstantBankInfoNV

- VUID-VkDescriptorSetAndBindingMappingEXT-sType-unique
  The `sType` value of each structure in the `pNext` chain must be unique

- VUID-VkDescriptorSetAndBindingMappingEXT-resourceMask-parameter
  `resourceMask` must be a valid combination of VkSpirvResourceTypeFlagBitsEXT values

- VUID-VkDescriptorSetAndBindingMappingEXT-resourceMask-requiredbitmask
  `resourceMask` must not be `0`

- VUID-VkDescriptorSetAndBindingMappingEXT-source-parameter
  `source` must be a valid VkDescriptorMappingSourceEXT value

- VUID-VkDescriptorSetAndBindingMappingEXT-constantOffset-parameter
  If `source` is VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_CONSTANT_OFFSET_EXT, the `constantOffset` member of `sourceData` must be a valid VkDescriptorMappingSourceConstantOffsetEXT structure

- VUID-VkDescriptorSetAndBindingMappingEXT-pushIndex-parameter
  If `source` is VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_PUSH_INDEX_EXT, the `pushIndex` member of `sourceData` must be a valid VkDescriptorMappingSourcePushIndexEXT structure

- VUID-VkDescriptorSetAndBindingMappingEXT-indirectIndex-parameter
  If `source` is VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_INDIRECT_INDEX_EXT, the `indirectIndex` member of `sourceData` must be a valid VkDescriptorMappingSourceIndirectIndexEXT structure

- VUID-VkDescriptorSetAndBindingMappingEXT-indirectIndexArray-parameter
  If `source` is VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_INDIRECT_INDEX_ARRAY_EXT, the `indirectIndexArray` member of `sourceData` must be a valid VkDescriptorMappingSourceIndirectIndexArrayEXT structure

- VUID-VkDescriptorSetAndBindingMappingEXT-shaderRecordIndex-parameter
  If `source` is VK_DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_SHADER_RECORD_INDEX_EXT, the `shaderRecordIndex` member of `sourceData` must be a valid VkDescriptorMappingSourceShaderRecordIndexEXT structure

## See Also

VK_EXT_descriptor_heap, VkDescriptorMappingSourceDataEXT, VkDescriptorMappingSourceEXT, VkShaderDescriptorSetAndBindingMappingInfoEXT, VkSpirvResourceTypeFlagsEXT, VkStructureType

## Document Notes

For more information, see the Vulkan Specification.

This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.

## Copyright

Copyright 2014-2026 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0