Name Strings

SPV_KHR_opacity_micromap

Contact

See Issues list in the Khronos SPIRV-Headers repository: https://github.com/KhronosGroup/SPIRV-Headers

Contributors

  • Daniel Koch, NVIDIA

  • Eric Werness, NVIDIA

  • Joshua Barczak, Intel

  • Matt Netsch, Qualcomm

Status

  • Approved by the SPIR-V Working Group: 2026-01-07

  • Ratified by the Khronos Board: 2026-02-20

Version

Last Modified Date

2026-09-10

Revision

5

Dependencies

This extension is written against the SPIR-V Specification, Version 1.6 Revision 6.

This extension requires SPIR-V 1.4.

This extension requires SPV_KHR_ray_query or SPV_KHR_ray_tracing.

Overview

This extension adds new functionality to support the Vulkan VK_KHR_opacity_micromap extension in SPIR-V.

Extension Name

To use this extension within a SPIR-V module, at least one of the following OpExtension strings must be present in the module:

OpExtension "SPV_KHR_opacity_micromap"
OpExtension "SPV_EXT_opacity_micromap"

Modifications to the SPIR-V Specification

(Modify Section 3.2.5, Execution Mode, adding to the existing table)
Execution mode Enabling Capabilities Extra Operands

6031

OpacityMicromapIdKHR

Indicates whether the shader can use opacity micromaps or not. The <id> operand is the id of a constant instruction of OpTypeBool which may be a specialization constant. If ray query traversal uses acceleration structures with opacity micromaps, this execution mode must be specified with a value of true; otherwise, undefined behavior results.

RayTracingOpacityMicromapExecutionModeKHR

<id>
Enable
(Modify Section 3.2.31, Ray Flags, adding to the existing table)
Ray Flags Enabling Capabilities

1024

ForceOpacityMicromap2StateKHR
Force opacity micromaps intersected by this ray to be evaluated in the 2 state mode. See the Ray Opacity Micromap in the Vulkan API specification.

RayTracingOpacityMicromapKHR
(Modify Section 3.2.30, Capability, adding a row to the Capability table)
Capability Implicitly Declares

5381

RayTracingOpacityMicromapKHR
Uses the ForceOpacityMicromap2StateKHR enumerant.

Shader

6032

RayTracingOpacityMicromapExecutionModeKHR
Uses the OpacityMicromapIdKHR execution mode.

Shader

Validation Rules

An OpExtension must be added to the SPIR-V for validation layers to check legal use of this extension:

OpExtension "SPV_KHR_opacity_micromap"
OpExtension "SPV_EXT_opacity_micromap"

Either OpExtension string is accepted, it’s not necessary to include both.

If a shader uses execution mode OpacityMicromapIdKHR, it must have the SPV_KHR_opacity_micromap extension string.

Issues

(1) Why are there two OpExtension strings?

RESOLVED: This extension is identical to SPV_EXT_opacity_micromap except that it adds a new execution mode named OpacityMicromapIdKHR. There is a strong desire to keep the existing behaviors when a module does not use the new execution mode.

Specifically:

  • Declaring either OpExtension string without the OpacityMicromapIdKHR execution mode produces the same behavior. A module that declares SPV_EXT_opacity_micromap behaves identically to one that declares SPV_KHR_opacity_micromap without OpacityMicromapIdKHR.

  • Declaring an OpExtension string in a module does not, by itself, determine whether opacity micromap data is used during ray query traversal. That is determined by which Vulkan opacity_micromap extension is enabled at the API level:

    • With VK_EXT_opacity_micromap enabled, opacity micromap data present in the acceleration structure is always used during ray query traversal.

    • With only VK_KHR_opacity_micromap enabled and its micromap feature enabled, opacity micromap data present in the acceleration structure is used during ray query traversal only when the module declares the OpacityMicromapIdKHR execution mode with its specialization-constant operand equal to VK_TRUE.

      This execution mode does not affect traversal initiated by pipeline
trace ray instructions, which is governed separately by the Vulkan
API, however it does apply to ray queries issued from a shader in a ray
tracing pipeline.

  • If ray query traversal uses an acceleration structure that contains opacity micromap data with only VK_KHR_opacity_micromap enabled and its micromap feature enabled, but the module does not declare the OpacityMicromapIdKHR execution mode with its specialization-constant operand equal to VK_TRUE, the traversal result is undefined. This is not equivalent to skipping opacity micromaps; applications must explicitly opt in via the execution mode when they intend to use opacity micromap data.

  • Declaring the OpacityMicromapIdKHR execution mode requires the VK_KHR_opacity_micromap micromap feature to be enabled at the API level: the execution mode uses the RayTracingOpacityMicromapExecutionModeKHR capability, which the Vulkan SPIR-V environment only makes valid when that feature is enabled. A module that declares OpacityMicromapIdKHR without the VK_KHR_opacity_micromap micromap feature enabled is invalid.

Revision History

Rev Date Author Changes

1

2025-04-09

Eric Werness/Wooyoung Kim

Initial revision

2

2025-11-12

Wooyoung Kim

Add ExecutionMode OpacityMicromapIdKHR, Updated to SPIR-V 1.6.6

3

2025-12-10

Wooyoung Kim

Allow "OpExtension SPV_EXT_opacity_micromap" to use the extension

4

2026-07-10

Daniel Koch

Clarify SPV_EXT vs SPV_KHR behavior equivalence (#4842)

5

2026-09-10

Daniel Koch

Scope execution mode wording to ray query traversal (#2810)