vkCmdBuildMicromapsEXT(3)

C Specification

To build micromaps represented as a VkMicromapEXT object 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.

The input buffers passed to this command will be referenced by the implementation for the duration of the command’s execution on the device. Micromaps must be fully self-contained. The application can reuse or free any memory which was used by this command’s execution on the device as an input or as scratch without affecting the results of a subsequent acceleration structure build using the micromap or traversal of that acceleration structure, provided proper synchronization is used as described below.

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-micromap-11648
The VkPhysicalDeviceOpacityMicromapFeaturesEXT::micromap feature must be enabled
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 set
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 the VK_BUFFER_USAGE_STORAGE_BUFFER_BIT usage flag set
VUID-vkCmdBuildMicromapsEXT-pInfos-07512
For each element of pInfos, if the value of VkMicromapBuildSizesInfoEXT::buildScratchSize, returned from a call to vkGetMicromapBuildSizesEXT with an identical VkMicromapBuildInfoEXT structure, is not 0, scratchData.deviceAddress must be a valid VkDeviceAddress
VUID-vkCmdBuildMicromapsEXT-pInfos-10896
For each element of pInfos, data.deviceAddress must be a valid VkDeviceAddress
VUID-vkCmdBuildMicromapsEXT-pInfos-10897
For each element of pInfos, triangleArray.deviceAddress must be a valid VkDeviceAddress
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
VUID-vkCmdBuildMicromapsEXT-dstMicromap-11649
The range of memory backing the dstMicromap member of any element of pInfos that is accessed by the execution of this command on the device must not overlap the memory backing the dstMicromap member of any other element of pInfos, which is accessed by the execution of this command on the device
VUID-vkCmdBuildMicromapsEXT-dstMicromap-11650
The range of memory backing the dstMicromap member of any element of pInfos that is accessed by the execution of this command on the device must not overlap the memory backing the scratchData member of any element of pInfos (including the same element), which is accessed by the execution of this command on the device
VUID-vkCmdBuildMicromapsEXT-scratchData-11651
The range of memory backing the scratchData member of any element of pInfos that is accessed by the execution of this command on the device must not overlap the memory backing the scratchData member of any other element of pInfos, which is accessed by the execution of this command on the device

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 VK_QUEUE_COMPUTE_BIT operations
VUID-vkCmdBuildMicromapsEXT-renderpass
This command must only be called outside of a render pass instance
VUID-vkCmdBuildMicromapsEXT-suspended
This command must not be called between suspended render pass instances
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