vkCmdBindSamplerHeapEXT(3)

# vkCmdBindSamplerHeapEXT(3) Manual Page

## Name

vkCmdBindSamplerHeapEXT - Binds a sampler heap to a command buffer

## C Specification

To bind a sampler heap to a command buffer, call:

    // Provided by VK_EXT_descriptor_heap
    void vkCmdBindSamplerHeapEXT(
        VkCommandBuffer                             commandBuffer,
        const VkBindHeapInfoEXT*                    pBindInfo);

## Parameters

- `commandBuffer` is the command buffer that the sampler heap will be bound to.

- `pBindInfo` is a VkBindHeapInfoEXT specifying the device address range used for the heap and any implementation reservations.

## Description

Addresses in the range defined by `pBindInfo->heapRange` are bound as the sampler heap. The application can access samplers and data through this heap anywhere except for the reserved range specified by `pBindInfo->reservedRangeOffset`. Addresses in the range [`pBindInfo->reservedRangeOffset`, `pBindInfo->reservedRangeOffset` + `pBindInfo->reservedRangeSize`) are reserved for the implementation and must not be accessed by the application at any time from when this command is recorded until there are no command buffers with that range bound.

The reserved range is bound to the command buffer until it has been reset.

Note | Implementations may require a larger sampler heap reservation to store embedded sampler descriptors when used in a mapping, as advertised by `minSamplerHeapReservedRangeWithEmbedded`.

Shaders executed by commands recorded after this command can use the specified sampler heap to access resources. `pBindInfo->heapRange.address` will be available to shaders to access samplers and data through the `SamplerHeapEXT` `BuiltIn` or via shader bindings.

When `vkCmdBindSamplerHeapEXT` is recorded, it immediately invalidates all non-heap descriptor state. Similarly, recording any non-heap descriptor state commands immediately invalidates state set by this command.

Valid Usage

- VUID-vkCmdBindSamplerHeapEXT-pBindInfo-11223
  The sum of `pBindInfo->reservedRangeOffset` and `pBindInfo->reservedRangeSize` must be less than or equal to `pBindInfo->heapRange.size`

- VUID-vkCmdBindSamplerHeapEXT-pBindInfo-11224
  `pBindInfo->reservedRangeSize` must be greater than or equal to `minSamplerHeapReservedRange`

- VUID-vkCmdBindSamplerHeapEXT-pBindInfo-11225
  `pBindInfo->heapRange.size` must less than or equal to `maxSamplerHeapSize`

- VUID-vkCmdBindSamplerHeapEXT-pBindInfo-11226
  `pBindInfo->heapRange.address` must be a multiple of `samplerHeapAlignment`

- VUID-vkCmdBindSamplerHeapEXT-pBindInfo-11434
  `pBindInfo->reservedRangeOffset` must be a multiple of `samplerDescriptorAlignment`

- VUID-vkCmdBindSamplerHeapEXT-pBindInfo-11228
  Memory bound to addresses in the range [`pBindInfo->heapRange.address` + `pBindInfo->reservedRangeOffset`, `pBindInfo->heapRange.address` + `pBindInfo->reservedRangeOffset` + `pBindInfo->reservedRangeSize`) must not be bound to any other command buffer as a reserved range for any heap unless the reserved range matches exactly and it is the same heap type

- VUID-vkCmdBindSamplerHeapEXT-heapRange-11230
  `heapRange` must be a device address range allocated to the application from a buffer created with the VK_BUFFER_USAGE_DESCRIPTOR_HEAP_BIT_EXT usage flag set

- VUID-vkCmdBindSamplerHeapEXT-commandBuffer-11231
  If `commandBuffer` is a secondary command buffer, it must have begun with VkCommandBufferInheritanceDescriptorHeapInfoEXT::`pSamplerHeapBindInfo` equal to `NULL`

Valid Usage (Implicit)

- VUID-vkCmdBindSamplerHeapEXT-commandBuffer-parameter
  `commandBuffer` must be a valid VkCommandBuffer handle

- VUID-vkCmdBindSamplerHeapEXT-pBindInfo-parameter
  `pBindInfo` must be a valid pointer to a valid VkBindHeapInfoEXT structure

- VUID-vkCmdBindSamplerHeapEXT-commandBuffer-recording
  `commandBuffer` must be in the recording state

- VUID-vkCmdBindSamplerHeapEXT-commandBuffer-cmdpool
  The `VkCommandPool` that `commandBuffer` was allocated from must support VK_QUEUE_COMPUTE_BIT, or VK_QUEUE_GRAPHICS_BIT operations

- VUID-vkCmdBindSamplerHeapEXT-videocoding
  This command must only be called outside of a video coding scope

Host Synchronization

- Host access to `commandBuffer` must be externally synchronized

- Host access to the `VkCommandPool` that `commandBuffer` was allocated from must be externally synchronized

Command Properties

Command Buffer Levels | Render Pass Scope | Video Coding Scope | Supported Queue Types | Command Type
--- | --- | --- | --- | ---
Primary Secondary | Both | Outside | VK_QUEUE_COMPUTE_BIT VK_QUEUE_GRAPHICS_BIT | State

Conditional Rendering

vkCmdBindSamplerHeapEXT is not affected by conditional rendering

## See Also

VK_EXT_descriptor_heap, VkBindHeapInfoEXT, VkCommandBuffer

## 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