HORIZON HASKELLDocslts/ghc-9.14.x45dd5372026-10-11Search names, modules, packages, or :: a typeCtrl K

GHC 9.14.1 · lts/ghc-9.14.x · 45dd537 · 2026-10-11

Modulevulkan-3.27GHC2021

Vulkan.Extensions.VK_KHR_opacity_micromap

Name

VK_KHR_opacity_micromap - device extension

VK_KHR_opacity_micromap

Name String

VK_KHR_opacity_micromap

Extension Type

Device extension

Registered Extension Number

624

Revision

1

Ratification Status

Ratified

Extension and Version Dependencies

VK_KHR_acceleration_structure

and

VK_KHR_device_address_commands

API Interactions

  • Interacts with VK_VERSION_1_4

  • Interacts with VK_EXT_shader_object

  • Interacts with VK_KHR_maintenance5

SPIR-V Dependencies
Contact
Extension Proposal

VK_KHR_opacity_micromap

Other Extension Metadata

Last Modified Date

2026-05-08

Interactions and External Dependencies
Contributors

  • Matthew Netsch, Qualcomm Technologies, Inc

  • Aleksandra Krstic, Qualcomm Technologies, Inc

  • Eric Werness, NVIDIA

  • Daniel Koch, NVIDIA

  • Stu Smith, AMD

  • Sven Woop, Intel

  • Anton Berko, MediaTek

  • Radoslaw Drabinski, Intel

  • Simon Fenney, Imagination Technologies

  • Andrew Garrard, Imagination Technologies

  • Dae Kim, Imagination Technologies

  • Fred Saucedo, Qualcomm Technologies, Inc

  • Ramesh babu Admimula, Qualcomm Technologies, Inc

  • Zedian Zhang, Qualcomm Technologies, Inc

  • Hans-Kristian Arntzen, Valve

  • Vikram Kushwaha, NVIDIA

  • Spencer Fricke, LunarG

  • Revanth Ponna, Qualcomm Technologies, Inc

  • Contributors to VK_EXT_opacity_micromap

Description

When adding transparency to a ray traced scene, an application can choose between further tessellating the geometry or using an any-hit shader to allow the ray through specific parts of the geometry. These options have the downside of either significantly increasing memory consumption or adding runtime overhead to run shader code in the middle of traversal, respectively.

This extension adds the ability to add an opacity micromap to geometry when building an acceleration structure. The opacity micromap compactly encodes opacity information which can be read by the implementation to mark parts of triangles as opaque or transparent. The format is externally visible to allow the application to compress its internal geometry and surface representations into the compressed format ahead of time. The compressed format subdivides each triangle into a set of subtriangles, each of which can be assigned either two or four opacity values. These opacity values can control if a ray hitting that subtriangle is treated as an opaque hit, complete miss, or possible hit, depending on the controls described in Ray Opacity Micromap.

This extension provides:

New Structures

New Enums

New Enum Constants

If VK_EXT_shader_object is supported:

If VK_KHR_maintenance5 or Vulkan Version 1.4 is supported:

Reference Code

The following code illustrates an algorithm that converts the barycentric coordinates inside a triangle into an OMM array index:

uint32_t BarycentricsToSpaceFillingCurveIndex(float u, float v, uint32_t level)
{
    u = clamp(u, 0.0f, 1.0f);
    v = clamp(v, 0.0f, 1.0f);

    uint32_t iu, iv, iw;

    // Quantize barycentric coordinates
    float fu = u * (1u << level);
    float fv = v * (1u << level);

    iu = (uint32_t)fu;
    iv = (uint32_t)fv;

    float uf = fu - float(iu);
    float vf = fv - float(iv);

    if (iu >= (1u << level)) iu = (1u << level) - 1u;
    if (iv >= (1u << level)) iv = (1u << level) - 1u;

    uint32_t iuv = iu + iv;

    if (iuv >= (1u << level))
        iu -= iuv - (1u << level) + 1u;

    iw = ~(iu + iv);

    if (uf + vf >= 1.0f && iuv < (1u << level) - 1u) --iw;

    uint32_t b0 = ~(iu ^ iw);
    b0 &= ((1u << level) - 1u);
    uint32_t t = (iu ^ iv) & b0;

    uint32_t f = t;
    f ^= f >> 1u;
    f ^= f >> 2u;
    f ^= f >> 4u;
    f ^= f >> 8u;
    uint32_t b1 = ((f ^ iu) & ~b0) | t;

    // Interleave bits
    b0 = (b0 | (b0 << 8u)) & 0x00ff00ffu;
    b0 = (b0 | (b0 << 4u)) & 0x0f0f0f0fu;
    b0 = (b0 | (b0 << 2u)) & 0x33333333u;
    b0 = (b0 | (b0 << 1u)) & 0x55555555u;
    b1 = (b1 | (b1 << 8u)) & 0x00ff00ffu;
    b1 = (b1 | (b1 << 4u)) & 0x0f0f0f0fu;
    b1 = (b1 | (b1 << 2u)) & 0x33333333u;
    b1 = (b1 | (b1 << 1u)) & 0x55555555u;

    return b0 | (b1 << 1u);
}

Issues

  1. Is the build actually similar to an acceleration structure build?

  • Resolved: The build should be much lighter-weight than an acceleration structure build

  1. Why does VkMicromapUsageKHR not have type/pNext?

  • Resolved: There can be a very large number of these structures, so doubling the size of these can be significant memory consumption. Also, an application may be loading these directly from a file which is more compatible with it being a flat structure. The including structures are extensible and are probably a more suitable place to add extensibility.

  1. Why is there a SPIR-V extension?

  • Resolved: There is a ray flag and an execution mode. To be consistent with how the existing ray tracing extensions work that these needs its own extension.

  1. Should there be indirect micromap build?

  • Resolved: Not for now. There is more in-depth usage metadata required and it seems less likely that something like a GPU culling system would need to change the counts for a micromap.

  1. Should the feature struct be aliased with VkPhysicalDeviceOpacityMicromapFeaturesEXT?

  • Resolved: No. This extension is not an exact promotion of VK_EXT_opacity_micromap and provides significantly different functionality.

  1. Should micromaps API be similar to the VK_EXT_opacity_micromap?

VK_EXT_opacity_micromap introduced almost an identical set of functionality for micromaps as acceleration structures. Should this promotion fold in micromaps as an acceleration structure type?

  • Resolved: Yes. While this is significant API breakage from the EXT, it is a better design choice going forward and can eliminate significant API surface area if promoted in the future.

  1. Should micromaps support host commands?

  • Resolved: No. Host commands are deprecated and not widely supported.

  1. Should createAccelerationStructureKHR be used to create micromaps?

This interface that uses Buffer to back micromaps is deprecated, but is still available for acceleration structure object creation.

  • Resolved: No. Make a new entry point that uses a device address to back micromaps and other acceleration structures instead of a buffer. Eliminate the ability to provide a separate capture/replay address as well. Top-level acceleration structures must reference the device address that backs the bottom-level acceleration structures and implementations must not expose an indirect handle.

  1. Should BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_DATA_UPDATE_BIT_EXT be promoted from VK_EXT_opacity_micromap to this extension?

BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_DATA_UPDATE_BIT_EXT distinguished between replacing a micromap with one of a different shape (BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_UPDATE_BIT_EXT) and replacing one where the shape is identical and only the opacity values have changed (DATA_UPDATE). The DATA_UPDATE flag was correlated with the discardable micromap feature, where an implementation might embed micromap state directly in the acceleration structure and exploit the tighter constraint to avoid a full rebuild. However, the spec never required DATA_UPDATE to be restricted to discardable micromaps, and it was already legal to treat DATA_UPDATE identically to UPDATE.

  • Resolved: No. The discardable micromap feature is not promoted to this extension, removing the primary motivation for DATA_UPDATE. No implementation identified a meaningful optimization from the stricter constraint beyond what UPDATE already provides, and no CTS coverage existed for either opacity micromap update flag in the EXT. Removing it is a pure API simplification with no functional loss. Applications must still perform a BLAS build update when opacity micromap data changes, even if only values and not structure have changed.

Version History

  • Revision 1, 2026-05-08 (Matthew Netsch)

    • Initial draft

See Also

No cross-references are available

Document Notes

For more information, see the Vulkan Specification.

This page is a generated document. Fixes and changes should be made to the generator scripts, not directly.

  • 20 types
  • Packagevulkan-3.27
  • Exports71
  • LanguageGHC2021
  • LicenceBSD-3-Clause
  • SourceVK_KHR_opacity_micromap.hs
datadata AccelerationStructureGeometryMicromapDataKHR
#

VkAccelerationStructureGeometryMicromapDataKHR - Structure specifying the data used to build a micromap

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 MicromapTriangleKHR to match this pattern.

For opacity micromaps, the data at data is packed as either one bit per element for OPACITY_MICROMAP_FORMAT_2_STATE_KHR or two bits per element for 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

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

Valid Usage (Implicit)

  • If usageCountsCount is not 0, and pUsageCounts is not NULL, pUsageCounts must be a valid pointer to an array of usageCountsCount valid MicromapUsageKHR structures

  • 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 MicromapUsageKHR structures

Structure Chaining

Extends the structure

See Also

VK_KHR_opacity_micromap, DeviceAddress, DeviceSize, MicromapUsageKHR, StructureType

Constructors

Instances4Show, FromCStruct, ToCStruct, Zero
datadata MicromapUsageKHR
#

VkMicromapUsageKHR - Structure specifying the usage information used to build a micromap

Description

The format is interpreted based on the type of the micromap using it.

Valid Usage (Implicit)

See Also

VK_KHR_opacity_micromap, AccelerationStructureGeometryMicromapDataKHR, OpacityMicromapFormatKHR

Constructors

Instances6Eq, Show, Storable, FromCStruct, ToCStruct, Zero
datadata MicromapTriangleKHR
#

VkMicromapTriangleKHR - Structure specifying the micromap format and data for a triangle

Description

The format is interpreted based on the type of the micromap using it.

See Also

VK_EXT_opacity_micromap, VK_KHR_opacity_micromap

Constructors

Instances6Eq, Show, Storable, FromCStruct, ToCStruct, Zero
datadata PhysicalDeviceOpacityMicromapFeaturesKHR
#

VkPhysicalDeviceOpacityMicromapFeaturesKHR - Structure describing the ray tracing opacity micromap features that can be supported by an implementation

Members

This structure describes the following feature:

Description

If the PhysicalDeviceOpacityMicromapFeaturesKHR structure is included in the pNext chain of the PhysicalDeviceFeatures2 structure passed to getPhysicalDeviceFeatures2, it is filled in to indicate whether each corresponding feature is supported. If the application wishes to use a Device with any features described by PhysicalDeviceOpacityMicromapFeaturesKHR, it must add an instance of the structure, with the desired feature members set to TRUE, to the pNext chain of DeviceCreateInfo when creating the Device.

Structure Chaining

Extends the structures

See Also

VK_KHR_opacity_micromap, Bool32, StructureType

Constructors

Instances6Eq, Show, Storable, FromCStruct, ToCStruct, Zero
datadata PhysicalDeviceOpacityMicromapPropertiesKHR
#

VkPhysicalDeviceOpacityMicromapPropertiesKHR - Structure describing the opacity micromap properties of a physical device

Description

If the PhysicalDeviceOpacityMicromapPropertiesKHR structure is included in the pNext chain of the PhysicalDeviceProperties2 structure passed to getPhysicalDeviceProperties2, it is filled in with each corresponding implementation-dependent property.

Structure Chaining

Extends the structure

See Also

VK_KHR_opacity_micromap, StructureType

Constructors

Instances6Eq, Show, Storable, FromCStruct, ToCStruct, Zero
datadata AccelerationStructureTrianglesOpacityMicromapKHR
#

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

Description

If AccelerationStructureTrianglesOpacityMicromapKHR is included in the pNext chain of a AccelerationStructureDenseGeometryFormatTrianglesDataAMDX or AccelerationStructureGeometryTrianglesDataKHR 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 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 OpacityMicromapSpecialIndexKHR 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.

Valid Usage

  • If indexType is INDEX_TYPE_NONE_KHR, indexBuffer must be 0

  • If indexType is not INDEX_TYPE_NONE_KHR, indexBuffer must be a valid DeviceAddress

  • If indexType is not INDEX_TYPE_NONE_KHR, indexStride must be a multiple of the size in bytes of indexType

  • If indexType is not INDEX_TYPE_NONE_KHR, indexStride must be less than or equal to 232-1

  • If indexType is INDEX_TYPE_NONE_KHR, for each triangle index in the geometry, index plus baseTriangle must be less than or equal to numTriangles, where numTriangles is given by the sum of all count parameters in the pUsageCounts or ppUsageCounts provided to the micromap’s build command

  • If indexType is INDEX_TYPE_NONE_KHR, micromap must not be NULL_HANDLE

Valid Usage (Implicit)

Structure Chaining

Extends the structures

See Also

VK_KHR_opacity_micromap, AccelerationStructureKHR, DeviceAddress, DeviceSize, IndexType, StructureType

Constructors

Instances6Eq, Show, Storable, FromCStruct, ToCStruct, Zero
newtypenewtype OpacityMicromapFormatKHR
#

VkOpacityMicromapFormatKHR - Format enum for opacity micromaps

Description

For compactness, these values are stored as 16-bit in some structures.

See Also

VK_EXT_opacity_micromap, VK_KHR_opacity_micromap, MicromapUsageKHR

Constructors

Instances6Eq, Ord, Read, Show, Storable, Zero
newtypenewtype OpacityMicromapSpecialIndexKHR
#

VkOpacityMicromapSpecialIndexKHR - Enum for special indices in the opacity micromap

Description

See Also

VK_EXT_opacity_micromap, VK_KHR_opacity_micromap

Constructors

Instances6Eq, Ord, Read, Show, Storable, Zero
newtypenewtype AccelerationStructureSerializedBlockTypeKHR
#

VkAccelerationStructureSerializedBlockTypeKHR - Enum for block types in a serialized acceleration structure

Description

See Also

VK_KHR_opacity_micromap

Constructors

Instances6Eq, Ord, Read, Show, Storable, Zero
newtypenewtype AccelerationStructureKHR
#

VkAccelerationStructureKHR - Opaque handle to an acceleration structure object

See Also

VK_DEFINE_NON_DISPATCHABLE_HANDLE, VK_KHR_acceleration_structure, AccelerationStructureBuildGeometryInfoKHR, AccelerationStructureCaptureDescriptorDataInfoEXT, AccelerationStructureDeviceAddressInfoKHR, AccelerationStructureTrianglesOpacityMicromapKHR, CopyAccelerationStructureInfoKHR, CopyAccelerationStructureToMemoryInfoKHR, CopyMemoryToAccelerationStructureInfoKHR, WriteDescriptorSetAccelerationStructureKHR, cmdWriteAccelerationStructuresPropertiesKHR, createAccelerationStructure2KHR, createAccelerationStructureKHR, destroyAccelerationStructureKHR, writeAccelerationStructuresPropertiesKHR

Constructors

Instances7Eq, Ord, Show, Storable, HasObjectType, IsHandle, …
newtypenewtype GeometryInstanceFlagBitsKHR
#

VkGeometryInstanceFlagBitsKHR - Instance flag bits

Description

GEOMETRY_INSTANCE_FORCE_NO_OPAQUE_BIT_KHR and GEOMETRY_INSTANCE_FORCE_OPAQUE_BIT_KHR must not be used in the same flag.

See Also

VK_KHR_acceleration_structure, VK_NV_ray_tracing, GeometryInstanceFlagsKHR

Constructors

Instances8Eq, Ord, Read, Show, Bits, FiniteBits, …
newtypenewtype BuildAccelerationStructureFlagBitsKHR
#

VkBuildAccelerationStructureFlagBitsKHR - Bitmask specifying additional parameters for acceleration structure builds

Description

BUILD_ACCELERATION_STRUCTURE_ALLOW_UPDATE_BIT_KHR and BUILD_ACCELERATION_STRUCTURE_ALLOW_COMPACTION_BIT_KHR may take more time and memory than a normal build, and so should only be used when those features are needed.

BUILD_ACCELERATION_STRUCTURE_ALLOW_UPDATE_BIT_KHR and BUILD_ACCELERATION_STRUCTURE_ALLOW_COMPACTION_BIT_KHR are allowed to be used together. In that case, the result of the compaction copy is used as the source of a build with mode of BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR to perform the compacted update.

See Also

VK_KHR_acceleration_structure, VK_NV_ray_tracing, BuildAccelerationStructureFlagsKHR

Constructors

Instances8Eq, Ord, Read, Show, Bits, FiniteBits, …
newtypenewtype AccelerationStructureTypeKHR
#

VkAccelerationStructureTypeKHR - Type of acceleration structure

Description

See Also

VK_KHR_acceleration_structure, VK_NV_ray_tracing, AccelerationStructureBuildGeometryInfoKHR, AccelerationStructureCreateInfo2KHR, AccelerationStructureCreateInfoKHR, AccelerationStructureInfoNV

Constructors

Instances6Eq, Ord, Read, Show, Storable, Zero
newtypenewtype GeometryTypeKHR
#

VkGeometryTypeKHR - Enum specifying which type of geometry is provided

Description

See Also

VK_KHR_acceleration_structure, VK_NV_ray_tracing, AccelerationStructureGeometryKHR, GeometryNV

Constructors

Instances6Eq, Ord, Read, Show, Storable, Zero
newtypenewtype ShaderCreateFlagBitsEXT
#

VkShaderCreateFlagBitsEXT - Bitmask controlling how a shader object is created

Description

See Also

VK_EXT_shader_object, ShaderCreateFlagsEXT

Constructors

Instances8Eq, Ord, Read, Show, Bits, FiniteBits, …