VulkanHub

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

  • VK_KHR_OPACITY_MICROMAP_EXTENSION_NAME
  • VK_KHR_OPACITY_MICROMAP_SPEC_VERSION
  • Extending VkAccelerationStructureTypeKHR:
    • VK_ACCELERATION_STRUCTURE_TYPE_OPACITY_MICROMAP_KHR
  • Extending VkBuildAccelerationStructureFlagBitsKHR:
    • VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_DISABLE_OPACITY_MICROMAPS_BIT_KHR
    • VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_UPDATE_BIT_KHR
    • VK_BUILD_ACCELERATION_STRUCTURE_MICROMAP_LOSSY_BIT_KHR
  • Extending VkGeometryInstanceFlagBitsKHR:
    • VK_GEOMETRY_INSTANCE_DISABLE_OPACITY_MICROMAPS_BIT_KHR
    • VK_GEOMETRY_INSTANCE_FORCE_OPACITY_MICROMAP_2_STATE_BIT_KHR
  • Extending VkGeometryTypeKHR:
    • VK_GEOMETRY_TYPE_MICROMAP_KHR
  • Extending VkPipelineCreateFlagBits:
    • VK_PIPELINE_CREATE_RAY_TRACING_OPACITY_MICROMAP_BIT_KHR
  • Extending VkStructureType:
    • VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_GEOMETRY_MICROMAP_DATA_KHR
    • VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_TRIANGLES_OPACITY_MICROMAP_KHR
    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_OPACITY_MICROMAP_FEATURES_KHR
    • VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_OPACITY_MICROMAP_PROPERTIES_KHR

If VK_EXT_shader_object is supported:

If VK_KHR_maintenance5 or Vulkan Version 1.4 is supported:

  • Extending VkPipelineCreateFlagBits2:
    • VK_PIPELINE_CREATE_2_OPACITY_MICROMAP_DISALLOW_MIXED_SPECIAL_INDEX_BIT_KHR
    • VK_PIPELINE_CREATE_2_RAY_TRACING_OPACITY_MICROMAP_BIT_KHR

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

(2) 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.

(3) 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.

(4) 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.

(5) 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.

(6) 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.

(7) Should micromaps support host commands?

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

(8) Should vkCreateAccelerationStructureKHR be used to create micromaps?

This interface that uses VkBuffer 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.

(9) Should VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_DATA_UPDATE_BIT_EXT be promoted from VK_EXT_opacity_micromap to this extension?

VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_OPACITY_MICROMAP_DATA_UPDATE_BIT_EXT distinguished between replacing a micromap with one of a different shape (VK_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