Function Prototype

vkCmdBuildMicromapsEXT

Build a micromap
primary / secondary
outside
compute
action

To build micromaps call:

void vkCmdBuildMicromapsEXT(
    VkCommandBuffer                                    commandBuffer,
    uint32_t infoCount,
    const VkMicromapBuildInfoEXT* pInfos);
  • commandBuffer is the command buffer into which the command will be recorded.
  • infoCount is the number of micromaps to build. It specifies the number of the pInfos structures that must be provided.
  • pInfos is a pointer to an array of infoCount
    VkMicromapBuildInfoEXT structures defining the data used to build each micromap.

The vkCmdBuildMicromapsEXT command provides the ability to initiate multiple micromaps builds, however there is no ordering or synchronization implied between any of the individual micromap builds.

This means that there cannot be any memory aliasing between any micromap memories or scratch memories being used by any of the builds.

Accesses to the micromap scratch buffers as identified by the VkMicromapBuildInfoEXT::scratchData buffer device addresses must be synchronized with the VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT

pipeline stage and an access type of (VK_ACCESS_2_MICROMAP_READ_BIT_EXT | VK_ACCESS_2_MICROMAP_WRITE_BIT_EXT). Accesses to VkMicromapBuildInfoEXT::dstMicromap must be synchronized with the VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT

pipeline stage and an access type of VK_ACCESS_2_MICROMAP_WRITE_BIT_EXT.

Accesses to other input buffers as identified by any used values of VkMicromapBuildInfoEXT::data or VkMicromapBuildInfoEXT::triangleArray must be synchronized with the VK_PIPELINE_STAGE_2_MICROMAP_BUILD_BIT_EXT

pipeline stage and an access type of VK_ACCESS_SHADER_READ_BIT.

Valid Usage

VUID-vkCmdBuildMicromapsEXT-pInfos-07461

For each pInfos[i], dstMicromap must have been created with a value of VkMicromapCreateInfoEXT::size greater than or equal to the memory size required by the build operation, as returned by vkGetMicromapBuildSizesEXT with pBuildInfo = pInfos[i]

VUID-vkCmdBuildMicromapsEXT-mode-07462

The mode member of each element of pInfos must be a valid VkBuildMicromapModeEXT value

VUID-vkCmdBuildMicromapsEXT-dstMicromap-07463

The dstMicromap member of any element of pInfos must be a valid VkMicromapEXT handle

VUID-vkCmdBuildMicromapsEXT-pInfos-07464

For each element of pInfos its type member must match the value of VkMicromapCreateInfoEXT::type when its dstMicromap was created

VUID-vkCmdBuildMicromapsEXT-dstMicromap-07465

The range of memory backing the dstMicromap member of any element of pInfos that is accessed by this command must not overlap the memory backing the dstMicromap member of any other element of pInfos, which is accessed by this command

VUID-vkCmdBuildMicromapsEXT-dstMicromap-07466

The range of memory backing the dstMicromap member of any element of pInfos that is accessed by this command must not overlap the memory backing the scratchData member of any element of pInfos (including the same element), which is accessed by this command

VUID-vkCmdBuildMicromapsEXT-scratchData-07467

The range of memory backing the scratchData member of any element of pInfos that is accessed by this command must not overlap the memory backing the scratchData member of any other element of pInfos, which is accessed by this command

VUID-vkCmdBuildMicromapsEXT-pInfos-07508

For each element of pInfos, the buffer used to create its dstMicromap member must be bound to device memory

VUID-vkCmdBuildMicromapsEXT-pInfos-07509

If pInfos[i].mode is VK_BUILD_MICROMAP_MODE_BUILD_EXT, all addresses between pInfos[i].scratchData.deviceAddress and pInfos[i].scratchData.deviceAddress + N - 1 must be in the buffer device address range of the same buffer, where N is given by the buildScratchSize member of the VkMicromapBuildSizesInfoEXT structure returned from a call to vkGetMicromapBuildSizesEXT with an identical VkMicromapBuildInfoEXT structure and primitive count

VUID-vkCmdBuildMicromapsEXT-data-07510

The buffers from which the buffer device addresses for all of the data and triangleArray members of all pInfos[i] are queried must have been created with the VK_BUFFER_USAGE_MICROMAP_BUILD_INPUT_READ_ONLY_BIT_EXT usage flag

VUID-vkCmdBuildMicromapsEXT-pInfos-07511

For each element of pInfos[i] the buffer from which the buffer device address pInfos[i].scratchData.deviceAddress is queried must have been created with VK_BUFFER_USAGE_STORAGE_BUFFER_BIT usage flag

VUID-vkCmdBuildMicromapsEXT-pInfos-07512

For each element of pInfos, its scratchData.deviceAddress, data.deviceAddress, and triangleArray.deviceAddress members must be valid device addresses obtained from vkGetBufferDeviceAddress

VUID-vkCmdBuildMicromapsEXT-pInfos-07513

For each element of pInfos, if scratchData.deviceAddress, data.deviceAddress, or triangleArray.deviceAddress is the address of a non-sparse buffer then it must be bound completely and contiguously to a single VkDeviceMemory object

VUID-vkCmdBuildMicromapsEXT-pInfos-07514

For each element of pInfos, its scratchData.deviceAddress member must be a multiple of VkPhysicalDeviceAccelerationStructurePropertiesKHR::minAccelerationStructureScratchOffsetAlignment

VUID-vkCmdBuildMicromapsEXT-pInfos-07515

For each element of pInfos, its triangleArray.deviceAddress and data.deviceAddress members must be a multiple of 256

Valid Usage (Implicit)

VUID-vkCmdBuildMicromapsEXT-pInfos-parameter

pInfos must be a valid pointer to an array of infoCount valid VkMicromapBuildInfoEXT structures

VUID-vkCmdBuildMicromapsEXT-commandBuffer-cmdpool

The VkCommandPool that commandBuffer was allocated from must support compute operations

VUID-vkCmdBuildMicromapsEXT-renderpass

This command must only be called outside of a render pass instance

VUID-vkCmdBuildMicromapsEXT-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 ::