VkAccelerationStructureTrianglesOpacityMicromapEXT(3)

# VkAccelerationStructureTrianglesOpacityMicromapEXT(3) Manual Page

## Name

VkAccelerationStructureTrianglesOpacityMicromapEXT - Structure specifying an opacity micromap in a bottom-level acceleration structure

## C Specification

The `VkAccelerationStructureTrianglesOpacityMicromapEXT` structure is defined as:

    // Provided by VK_EXT_opacity_micromap
    typedef struct VkAccelerationStructureTrianglesOpacityMicromapEXT {
        VkStructureType                     sType;
        void*                               pNext;
        VkIndexType                         indexType;
        VkDeviceOrHostAddressConstKHR       indexBuffer;
        VkDeviceSize                        indexStride;
        uint32_t                            baseTriangle;
        uint32_t                            usageCountsCount;
        const VkMicromapUsageEXT*           pUsageCounts;
        const VkMicromapUsageEXT* const*    ppUsageCounts;
        VkMicromapEXT                       micromap;
    } VkAccelerationStructureTrianglesOpacityMicromapEXT;

## Members

- `sType` is a VkStructureType value identifying this structure.

- `pNext` is `NULL` or a pointer to a structure extending this structure.

- `indexType` is the type of triangle indices used when indexing this micromap.

- `indexBuffer` is a device or host address of memory containing the triangle indices. When `indexType` is VK_INDEX_TYPE_NONE_KHR it must be `NULL`.

- `indexStride` is the byte stride between triangle indices.

- `baseTriangle` is the base value added to the non-negative triangle indices.

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

- `micromap` is the handle to the micromap object to include in this geometry.

## Description

If `VkAccelerationStructureTrianglesOpacityMicromapEXT` is included in the `pNext` chain of a VkAccelerationStructureDenseGeometryFormatTrianglesDataAMDX or VkAccelerationStructureGeometryTrianglesDataKHR structure, that geometry will reference that micromap.

For each triangle in the geometry, the acceleration structure build fetches an index from `indexBuffer` using `indexType` and `indexStride` if present. If `indexType` is VK_INDEX_TYPE_NONE_KHR, then the index used is the index of the triangle in the geometry.

If that value is the unsigned cast of one of the values from VkOpacityMicromapSpecialIndexEXT then that triangle behaves as described for that special value in Ray Opacity Micromap.

Otherwise that triangle uses the opacity micromap information from micromap at that index plus `baseTriangle`.

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 count used to build this geometry. For a given `format` and `subdivisionLevel` the number of triangles in this geometry matching those values after indirection and special index handling must be equal to the sum of matching `count` provided.

If `micromap` is VK_NULL_HANDLE, then every value read from `indexBuffer` must be one of the values in VkOpacityMicromapSpecialIndexEXT.

Valid Usage

- VUID-VkAccelerationStructureTrianglesOpacityMicromapEXT-pUsageCounts-07335
  Only one of `pUsageCounts` or `ppUsageCounts` can be a valid pointer, the other must be `NULL`

- VUID-VkAccelerationStructureTrianglesOpacityMicromapEXT-indexType-10719
  `indexType` must be VK_INDEX_TYPE_UINT16, VK_INDEX_TYPE_UINT32, or VK_INDEX_TYPE_NONE_KHR

- VUID-VkAccelerationStructureTrianglesOpacityMicromapEXT-indexType-10722
  If `indexType` is not VK_INDEX_TYPE_NONE_KHR, then `indexStride` must be a multiple of the size in bytes of `indexType`

- VUID-VkAccelerationStructureTrianglesOpacityMicromapEXT-indexType-10723
  If `indexType` is not VK_INDEX_TYPE_NONE_KHR, then `indexStride` must be less than or equal to 232-1

- VUID-VkAccelerationStructureTrianglesOpacityMicromapEXT-format-11679
  If `micromap` is not VK_NULL_HANDLE, the `type` used to construct `micromap` is VK_MICROMAP_TYPE_OPACITY_MICROMAP_EXT, the `format` member of each element of `pUsageCounts` or `ppUsageCounts` must be a valid value from VkOpacityMicromapFormatEXT

- VUID-VkAccelerationStructureTrianglesOpacityMicromapEXT-subdivisionLevel-11680
  If `micromap` is not VK_NULL_HANDLE, the `type` used to build `micromap` is VK_MICROMAP_TYPE_OPACITY_MICROMAP_EXT, for each member of `pUsageCounts` or `ppUsageCounts` with `format` equal to VK_OPACITY_MICROMAP_FORMAT_2_STATE_EXT, `subdivisionLevel` must be less than or equal to VkPhysicalDeviceOpacityMicromapPropertiesEXT::`maxOpacity2StateSubdivisionLevel`

- VUID-VkAccelerationStructureTrianglesOpacityMicromapEXT-subdivisionLevel-11681
  If `micromap` is not VK_NULL_HANDLE, the `type` used to build `micromap` is VK_MICROMAP_TYPE_OPACITY_MICROMAP_EXT, for each member of `pUsageCounts` or `ppUsageCounts` with `format` equal to VK_OPACITY_MICROMAP_FORMAT_4_STATE_EXT, `subdivisionLevel` must be less than or equal to VkPhysicalDeviceOpacityMicromapPropertiesEXT::`maxOpacity4StateSubdivisionLevel`

- VUID-VkAccelerationStructureTrianglesOpacityMicromapEXT-format-11682
  If `micromap` is not VK_NULL_HANDLE, the `type` used to construct `micromap` is VK_MICROMAP_TYPE_DISPLACEMENT_MICROMAP_NV, the `format` member of each element of `pUsageCounts` or `ppUsageCounts` must be a valid value from VkDisplacementMicromapFormatNV

- VUID-VkAccelerationStructureTrianglesOpacityMicromapEXT-subdivisionLevel-11683
  If `micromap` is not VK_NULL_HANDLE, the `type` used to construct `micromap` is VK_MICROMAP_TYPE_DISPLACEMENT_MICROMAP_NV, for each member of `pUsageCounts` or `ppUsageCounts` `subdivisionLevel` must be less than or equal to VkPhysicalDeviceDisplacementMicromapPropertiesNV::`maxDisplacementMicromapSubdivisionLevel`

Valid Usage (Implicit)

- VUID-VkAccelerationStructureTrianglesOpacityMicromapEXT-sType-sType
  `sType` must be VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_TRIANGLES_OPACITY_MICROMAP_EXT

- VUID-VkAccelerationStructureTrianglesOpacityMicromapEXT-indexType-parameter
  `indexType` must be a valid VkIndexType value

- VUID-VkAccelerationStructureTrianglesOpacityMicromapEXT-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-VkAccelerationStructureTrianglesOpacityMicromapEXT-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

- VUID-VkAccelerationStructureTrianglesOpacityMicromapEXT-micromap-parameter
  If `micromap` is not VK_NULL_HANDLE, `micromap` must be a valid VkMicromapEXT handle

Structure Chaining

Extends the structures

  - VkAccelerationStructureDenseGeometryFormatTrianglesDataAMDX

  - VkAccelerationStructureGeometryTrianglesDataKHR

## See Also

VK_EXT_opacity_micromap, VkDeviceOrHostAddressConstKHR, VkDeviceSize, VkIndexType, VkMicromapEXT, VkMicromapUsageEXT, 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.

## Copyright

Copyright 2014-2026 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0