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

SPDX-License-Identifier: CC-BY-4.0