C Specification

The VkMicromapBuildInfoEXT structure is defined as:

// Provided by VK_EXT_opacity_micromap
typedef struct VkMicromapBuildInfoEXT {
    VkStructureType                     sType;
    const void*                         pNext;
    VkMicromapTypeEXT                   type;
    VkBuildMicromapFlagsEXT             flags;
    VkBuildMicromapModeEXT              mode;
    VkMicromapEXT                       dstMicromap;
    uint32_t                            usageCountsCount;
    const VkMicromapUsageEXT*           pUsageCounts;
    const VkMicromapUsageEXT* const*    ppUsageCounts;
    VkDeviceOrHostAddressConstKHR       data;
    VkDeviceOrHostAddressKHR            scratchData;
    VkDeviceOrHostAddressConstKHR       triangleArray;
    VkDeviceSize                        triangleArrayStride;
} VkMicromapBuildInfoEXT;

Members

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • type is a VkMicromapTypeEXT value specifying the type of micromap being built.

  • flags is a bitmask of VkBuildMicromapFlagBitsEXT specifying additional parameters of the micromap.

  • mode is a VkBuildMicromapModeEXT value specifying the type of operation to perform.

  • dstMicromap is a pointer to the target micromap for the build.

  • usageCountsCount specifies the number of usage counts structures that will be used to determine the size of this micromap.

  • pUsageCounts is a pointer to an array of VkMicromapUsageEXT structures.

  • ppUsageCounts is a pointer to an array of pointers to VkMicromapUsageEXT structures.

  • data is the device or host address to memory which contains the data for the micromap.

  • scratchData is the device or host address to memory that will be used as scratch memory for the build.

  • triangleArray is the device or host address to memory containing the VkMicromapTriangleEXT data

  • triangleArrayStride is the stride in bytes between each element of triangleArray

Description

Only one of pUsageCounts or ppUsageCounts can be a valid pointer, the other must be NULL. The elements of the non-NULL array describe the total counts used to build each micromap. Each element contains a count which is the number of micromap triangles of that format and subdivisionLevel contained in the micromap. Multiple elements with the same format and subdivisionLevel are allowed and the total count for that format and subdivisionLevel is the sum of the count for each element.

Each micromap triangle refers to one element in triangleArray which contains the format and subdivisionLevel for that particular triangle as well as a dataOffset in bytes which is the location relative to data where that triangle’s micromap data begins. The data at triangleArray is laid out as a 4 byte unsigned integer for the dataOffset followed by a 2 byte unsigned integer for the subdivision level then a 2 byte unsigned integer for the format. In practice, compilers compile VkMicromapTriangleEXT to match this pattern.

For opacity micromaps, the data at data is packed as either one bit per element for VK_OPACITY_MICROMAP_FORMAT_2_STATE_EXT or two bits per element for VK_OPACITY_MICROMAP_FORMAT_4_STATE_EXT and is packed from LSB to MSB in each byte. The data at each index in those bytes is interpreted as discussed in Ray Opacity Micromap.

For displacement micromaps, the data at data is interpreted as discussed in Displacement Micromap Encoding.

Valid Usage

  • VUID-VkMicromapBuildInfoEXT-pUsageCounts-07516
    Only one of pUsageCounts or ppUsageCounts can be a valid pointer, the other must be NULL

  • VUID-VkMicromapBuildInfoEXT-type-07517
    If type is VK_MICROMAP_TYPE_OPACITY_MICROMAP_EXT the format member of VkMicromapUsageEXT must be a valid value from VkOpacityMicromapFormatEXT

  • VUID-VkMicromapBuildInfoEXT-type-07518
    If type is VK_MICROMAP_TYPE_OPACITY_MICROMAP_EXT the format member of VkMicromapTriangleEXT must be a valid value from VkOpacityMicromapFormatEXT

  • VUID-VkMicromapBuildInfoEXT-type-08704
    If type is VK_MICROMAP_TYPE_DISPLACEMENT_MICROMAP_NV the format member of VkMicromapUsageEXT must be a valid value from VkDisplacementMicromapFormatNV

  • VUID-VkMicromapBuildInfoEXT-type-08705
    If type is VK_MICROMAP_TYPE_DISPLACEMENT_MICROMAP_NV the format member of VkMicromapTriangleEXT must be a valid value from VkDisplacementMicromapFormatNV

Valid Usage (Implicit)

  • VUID-VkMicromapBuildInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_MICROMAP_BUILD_INFO_EXT

  • VUID-VkMicromapBuildInfoEXT-pNext-pNext
    pNext must be NULL

  • VUID-VkMicromapBuildInfoEXT-type-parameter
    type must be a valid VkMicromapTypeEXT value

  • VUID-VkMicromapBuildInfoEXT-flags-parameter
    flags must be a valid combination of VkBuildMicromapFlagBitsEXT values

  • VUID-VkMicromapBuildInfoEXT-pUsageCounts-parameter
    If usageCountsCount is not 0, and pUsageCounts is not NULL, pUsageCounts must be a valid pointer to an array of usageCountsCount VkMicromapUsageEXT structures

  • VUID-VkMicromapBuildInfoEXT-ppUsageCounts-parameter
    If usageCountsCount is not 0, and ppUsageCounts is not NULL, ppUsageCounts must be a valid pointer to an array of usageCountsCount valid pointers to VkMicromapUsageEXT structures

See Also

VK_EXT_opacity_micromap, VkBuildMicromapFlagsEXT, VkBuildMicromapModeEXT, VkDeviceOrHostAddressConstKHR, VkDeviceOrHostAddressKHR, VkDeviceSize, VkMicromapEXT, VkMicromapTypeEXT, VkMicromapUsageEXT, VkStructureType, vkBuildMicromapsEXT, vkCmdBuildMicromapsEXT, vkGetMicromapBuildSizesEXT

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