vkCmdBuildMicromapsEXT(3)

C Specification

To build micromaps call:

// Provided by VK_EXT_opacity_micromap
void vkCmdBuildMicromapsEXT(
    VkCommandBuffer                             commandBuffer,
    uint32_t                                    infoCount,
    const VkMicromapBuildInfoEXT*               pInfos);

Parameters

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.

Description

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.

Note

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-commandBuffer-parameter
commandBuffer must be a valid VkCommandBuffer handle
VUID-vkCmdBuildMicromapsEXT-pInfos-parameter
pInfos must be a valid pointer to an array of infoCount valid VkMicromapBuildInfoEXT structures
VUID-vkCmdBuildMicromapsEXT-commandBuffer-recording
commandBuffer must be in the recording state
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
VUID-vkCmdBuildMicromapsEXT-infoCount-arraylength
infoCount must be greater than 0

Host Synchronization

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