VkAccelerationStructureGeometryMicromapDataKHR(3)

Name

VkAccelerationStructureGeometryMicromapDataKHR - Structure specifying the data used to build a micromap

C Specification

When building micromaps with vkCmdBuildAccelerationStructuresKHR, a VkAccelerationStructureGeometryMicromapDataKHR structure can be added to the pNext chain of VkAccelerationStructureGeometryKHR to specify the data used to build the micromap.

The VkAccelerationStructureGeometryMicromapDataKHR structure is defined as:

// Provided by VK_KHR_opacity_micromap
typedef struct VkAccelerationStructureGeometryMicromapDataKHR {
    VkStructureType                     sType;
    const void*                         pNext;
    uint32_t                            usageCountsCount;
    const VkMicromapUsageKHR*           pUsageCounts;
    const VkMicromapUsageKHR* const*    ppUsageCounts;
    VkDeviceAddress                     data;
    VkDeviceAddress                     triangleArray;
    VkDeviceSize                        triangleArrayStride;
} VkAccelerationStructureGeometryMicromapDataKHR;

Members

  • sType is a VkStructureType value identifying this structure.

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

  • 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 VkMicromapUsageKHR structures.

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

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

  • triangleArray is the device address to memory containing the VkMicromapTriangleKHR 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 VkMicromapTriangleKHR 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_KHR or two bits per element for VK_OPACITY_MICROMAP_FORMAT_4_STATE_KHR 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-VkAccelerationStructureGeometryMicromapDataKHR-pUsageCounts-11642
    Only one of pUsageCounts or ppUsageCounts can be a valid pointer, the other must be NULL

  • VUID-VkAccelerationStructureGeometryMicromapDataKHR-count-11643
    The total sum of count from all elements of pUsageCounts and ppUsageCounts must be less than or equal to maxMicromapTriangles

  • VUID-VkAccelerationStructureGeometryMicromapDataKHR-subdivisionLevel-11645
    For each member of pUsageCounts or ppUsageCounts, if format is VK_OPACITY_MICROMAP_FORMAT_2_STATE_KHR, subdivisionLevel must be less than or equal to maxOpacity2StateSubdivisionLevel

  • VUID-VkAccelerationStructureGeometryMicromapDataKHR-triangleArrayStride-11646
    triangleArrayStride must be greater than or equal to 8 bytes

  • VUID-VkAccelerationStructureGeometryMicromapDataKHR-triangleArrayStride-11647
    triangleArrayStride must be a multiple of 4 bytes

Valid Usage (Implicit)

  • VUID-VkAccelerationStructureGeometryMicromapDataKHR-sType-sType
    sType must be VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_GEOMETRY_MICROMAP_DATA_KHR

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

  • VUID-VkAccelerationStructureGeometryMicromapDataKHR-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 valid VkMicromapUsageKHR structures

Structure Chaining
Extends the structure

See Also

VK_KHR_opacity_micromap, VkDeviceAddress, VkDeviceSize, VkMicromapUsageKHR, VkStructureType

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.