vkCmdBuildMicromapsEXT(3)

# vkCmdBuildMicromapsEXT(3) Manual Page

## Name

vkCmdBuildMicromapsEXT - Build a micromap

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

Command Properties

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

Conditional Rendering

vkCmdBuildMicromapsEXT is not affected by conditional rendering

## See Also

VK_EXT_opacity_micromap, VkCommandBuffer, VkMicromapBuildInfoEXT

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