vkBuildMicromapsEXT(3)

# vkBuildMicromapsEXT(3) Manual Page

## Name

vkBuildMicromapsEXT - Build a micromap on the host

## C Specification

To build VkMicromapEXT on the host, call:

Warning | This functionality is superseded by vkCmdBuildMicromapsEXT. See Legacy Functionality for more information.

    // Provided by VK_EXT_opacity_micromap
    VkResult vkBuildMicromapsEXT(
        VkDevice                                    device,
        VkDeferredOperationKHR                      deferredOperation,
        uint32_t                                    infoCount,
        const VkMicromapBuildInfoEXT*               pInfos);

## Parameters

- `device` is the `VkDevice` for which the micromaps are being built.

- `deferredOperation` is an optional VkDeferredOperationKHR to request deferral for this command.

- `infoCount` is the number of micromaps to build. It specifies the number of the `pInfos` that must be provided.

- `pInfos` is a pointer to an array of `infoCount` VkMicromapBuildInfoEXT structures defining the geometry used to build each micromap.

## Description

This command fulfills the same task as vkCmdBuildMicromapsEXT but is executed by the host.

The `vkBuildMicromapsEXT` 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. Micromaps must be fully self-contained. The application can reuse or free any memory which was used by the command 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.

Valid Usage

- VUID-vkBuildMicromapsEXT-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-vkBuildMicromapsEXT-mode-07462
  The `mode` member of each element of `pInfos` must be a valid VkBuildMicromapModeEXT value

- VUID-vkBuildMicromapsEXT-dstMicromap-07463
  The `dstMicromap` member of any element of `pInfos` must be a valid VkMicromapEXT handle

- VUID-vkBuildMicromapsEXT-pInfos-07464
  For each element of `pInfos` its `type` member must match the value of VkMicromapCreateInfoEXT::`type` when its `dstMicromap` was created

- VUID-vkBuildMicromapsEXT-pInfos-07552
  For each element of `pInfos`, the `buffer` used to create its `dstMicromap` member must be bound to host-visible device memory

- VUID-vkBuildMicromapsEXT-pInfos-07553
  For each element of `pInfos`, all referenced addresses of `pInfos`[i].`data.hostAddress` must be valid host memory

- VUID-vkBuildMicromapsEXT-pInfos-07554
  For each element of `pInfos`, all referenced addresses of `pInfos`[i].`triangleArray.hostAddress` must be valid host memory

- VUID-vkBuildMicromapsEXT-micromapHostCommands-07555
  The `VkPhysicalDeviceOpacityMicromapFeaturesEXT`::`micromapHostCommands` feature must be enabled

- VUID-vkBuildMicromapsEXT-pInfos-07556
  If `pInfos`[i].`mode` is VK_BUILD_MICROMAP_MODE_BUILD_EXT, and N is not `0`, then all addresses between `pInfos`[i].`scratchData.hostAddress` and `pInfos`[i].`scratchData.hostAddress` + N - 1 must be valid host memory, where N is given by the value of VkMicromapBuildSizesInfoEXT::`buildScratchSize` returned from a call to vkGetMicromapBuildSizesEXT with an identical VkMicromapBuildInfoEXT structure

- VUID-vkBuildMicromapsEXT-pInfos-07557
  For each element of `pInfos`, the `buffer` used to create its `dstMicromap` member must be bound to memory that was not allocated with multiple instances

- VUID-vkBuildMicromapsEXT-dstMicromap-11667
  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-vkBuildMicromapsEXT-dstMicromap-11668
  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-vkBuildMicromapsEXT-scratchData-11669
  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

Valid Usage (Implicit)

- VUID-vkBuildMicromapsEXT-device-parameter
  `device` must be a valid VkDevice handle

- VUID-vkBuildMicromapsEXT-deferredOperation-parameter
  If `deferredOperation` is not VK_NULL_HANDLE, `deferredOperation` must be a valid VkDeferredOperationKHR handle

- VUID-vkBuildMicromapsEXT-pInfos-parameter
  `pInfos` must be a valid pointer to an array of `infoCount` valid VkMicromapBuildInfoEXT structures

- VUID-vkBuildMicromapsEXT-infoCount-arraylength
  `infoCount` must be greater than `0`

- VUID-vkBuildMicromapsEXT-deferredOperation-parent
  If `deferredOperation` is a valid handle, it must have been created, allocated, or retrieved from `device`

Return Codes

On success, this command returns

  - VK_OPERATION_DEFERRED_KHR

  - VK_OPERATION_NOT_DEFERRED_KHR

  - VK_SUCCESS

On failure, this command returns

  - VK_ERROR_OUT_OF_DEVICE_MEMORY

  - VK_ERROR_OUT_OF_HOST_MEMORY

  - VK_ERROR_UNKNOWN

  - VK_ERROR_VALIDATION_FAILED

## See Also

VK_EXT_opacity_micromap, VkDeferredOperationKHR, VkDevice, 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