vkBuildMicromapsEXT(3)

# vkBuildMicromapsEXT(3) Manual Page

## Name

vkBuildMicromapsEXT - Build a micromap on the host

Loading… please wait.

## C Specification

To build micromaps on the host, call:

    // 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.

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-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-vkBuildMicromapsEXT-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-vkBuildMicromapsEXT-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-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`, 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 `buildScratchSize` member of the VkMicromapBuildSizesInfoEXT structure returned from a call to vkGetMicromapBuildSizesEXT with an identical VkMicromapBuildInfoEXT structure and primitive count

- 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

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_SUCCESS`

  - `VK_OPERATION_DEFERRED_KHR`

  - `VK_OPERATION_NOT_DEFERRED_KHR`

On failure, this command returns

  - `VK_ERROR_OUT_OF_HOST_MEMORY`

  - `VK_ERROR_OUT_OF_DEVICE_MEMORY`

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

SPDX-License-Identifier: CC-BY-4.0