VkMicromapBuildInfoEXT(3)

# VkMicromapBuildInfoEXT(3) Manual Page

## Name

VkMicromapBuildInfoEXT - Structure specifying the data used to build a micromap

Loading… please wait.

## 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 the type of 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.

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.

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`

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

SPDX-License-Identifier: CC-BY-4.0