vkCmdBuildMicromapsEXT(3)

# vkCmdBuildMicromapsEXT(3) Manual Page

## Name

vkCmdBuildMicromapsEXT - Build a micromap

Loading… please wait.

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

Command Properties

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

## 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-2024 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0