XR_ANDROID_global_passthrough_dimming

Name String

XR_ANDROID_global_passthrough_dimming

Extension Type

Instance extension

Registered Extension Number

797

Revision

1

Ratification Status

Not ratified

Extension and Version Dependencies

OpenXR 1.0

Last Modified Date

2026-03-10

IP Status

No known IP claims.

Contributors

Brian Chen, Google
Kyle Chen, Google
Nihav Jain, Google
Spencer Quin, Google

Overview

As optical see-through devices are introduced, it’s important to not only allow applications to adjust the darkness of the passthrough in order to provide the best blending with the app context to the user, but also let system undim the passthrough for safety reasons.

This extension provides two functions for apps to set and get the current dimming level, as well as an event to broadcast when the dimming level changes.

Inspect system capability

The XrSystemGlobalDimmingPropertiesANDROID structure is defined as:

typedef struct XrSystemGlobalDimmingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsGlobalDimming;
} XrSystemGlobalDimmingPropertiesANDROID;

Member Descriptions

  • type is the XrStructureType of this structure.
  • next is NULL or a pointer to the next structure in a structure chain. No such structures are defined in core OpenXR or this extension. No such structures are defined in core OpenXR or this extension.
  • supportsGlobalDimming is an XrBool32 , indicating if the current system supports global dimming.

An application can inspect whether the system supports global dimming by chaining an XrSystemGlobalDimmingPropertiesANDROID structure to the XrSystemProperties when calling xrGetSystemProperties .

If the runtime returns XR_FALSE for supportsGlobalDimming , the runtime must return XR_ERROR_FEATURE_UNSUPPORTED when xrGetGlobalDimmingLevelANDROID is called.

Valid Usage (Implicit)

Enumerate supported global dimming levels

The xrEnumerateSupportedGlobalDimmingLevelsANDROID structure is defined as:

XrResult xrEnumerateSupportedGlobalDimmingLevelsANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    supportedGlobalDimmingLevelCapacityInput,
    uint32_t*                                   supportedGlobalDimmingLevelCountOutput,
    float*                                      supportedGlobalDimmingLevels);

Member Descriptions

  • instance is the instance from which systemId was retrieved.
  • systemId is the XrSystemId whose supported levels will be enumerated.
  • supportedGlobalDimmingLevelCapacityInput is the capacity of the supportedGlobalDimmingLevels array, or 0 to indicate a request to retrieve the required capacity.
  • supportedGlobalDimmingLevelCountOutput is a pointer to the count of supportedGlobalDimmingLevels written, or a pointer to the required capacity in the case that supportedGlobalDimmingLevelCapacityInput is insufficient.
  • supportedGlobalDimmingLevels is a pointer to an array of supported levels, but can be NULL if supportedGlobalDimmingLevelCapacityInput is 0.

If returned supportedGlobalDimmingLevelCountOutput is 0, all global dimming levels between 0.0 and 1.0 are supported.

xrEnumerateSupportedGlobalDimmingLevelsANDROID enumerates the global dimming levels supported by the XrSystemId . The supported levels must not change during the lifetime of its XrInstance . The returned list of levels must be sorted in ascending order.

Runtimes must always return identical buffer contents from this enumeration for the given systemId and for the lifetime of the instance .

Valid Usage (Implicit)

  • The XR_ANDROID_global_passthrough_dimming extension must be enabled prior to calling xrEnumerateSupportedGlobalDimmingLevelsANDROID
  • instance must be a valid XrInstance handle
  • supportedGlobalDimmingLevelCountOutput must be a pointer to a uint32_t value
  • If supportedGlobalDimmingLevelCapacityInput is not 0 , supportedGlobalDimmingLevels must be a pointer to an array of supportedGlobalDimmingLevelCapacityInput float values

Return Codes

Success

  • XR_SUCCESS

Failure

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SYSTEM_INVALID
  • XR_ERROR_VALIDATION_FAILURE

Configure Global Dimming Level

The XrGlobalDimmingFrameEndInfoANDROID structure is defined as:

typedef struct XrGlobalDimmingFrameEndInfoANDROID {
    XrStructureType    type;
    const void*        next;
    float              globalDimmingLevel;
} XrGlobalDimmingFrameEndInfoANDROID;

Parameter Descriptions

  • type is the XrStructureType of this structure.
  • next is NULL or a pointer to the next structure in a structure chain. No such structures are defined in core OpenXR or this extension.
  • globalDimmingLevel is a value between 0.0 (transparent) and 1.0 (opaque). The runtime may map this value to the closest supported global dimming level. The application can set this value to -1.0 to indicate that the current dimming level is preferred.

The globalDimmingLevel value specifies the percentage of light being blocked, where a value of 0.0 corresponds to 0% light blocking and 1.0 corresponds to 100% light blocking. The percentage of blocked light can be represented in general as:

100% - Light Transmittance%

The percentage of light transmittance, according to ISO 8980-3:2022 , can be measured as the ratio of transmitted radiant flux to incident radiant flux at wavelengths of visible light (380nm to 780nm).

The XrGlobalDimmingFrameEndInfoANDROID is a structure that an application can chain in XrFrameEndInfo to request a preferred global dimming level.

The runtime must honor the requested dimming level if the requested dimming level is different from the current dimming level.

The runtime will have control of the global dimming level and may disregard the preferred global dimming level for safety reasons.

Valid Usage (Implicit)

The xrGetGlobalDimmingLevelANDROID function is defined as:

XrResult xrGetGlobalDimmingLevelANDROID(
    XrSession                                   session,
    float*                                      dimmingLevel);

Parameter Descriptions

  • session is a valid XrSession handle.
  • dimmingLevel is a pointer to the current dimming level.

The returned dimmingLevel must be between 0.0 and 1.0 while 0.0 means fully transparent and 1.0 means fully dimmed.

If the dimming level has not been set, the runtime must set the dimming level to 0.0 when passthrough is enabled and 1.0 when passthrough is disabled.

Valid Usage (Implicit)

  • The XR_ANDROID_global_passthrough_dimming extension must be enabled prior to calling xrGetGlobalDimmingLevelANDROID
  • session must be a valid XrSession handle
  • dimmingLevel must be a pointer to a float value

Return Codes

Success

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Failure

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

Dimming Level Changed Event

The XrEventDataGlobalDimmingLevelChangedANDROID structure is defined as:

typedef struct XrEventDataGlobalDimmingLevelChangedANDROID {
    XrStructureType    type;
    const void*        next;
    XrSession          session;
} XrEventDataGlobalDimmingLevelChangedANDROID;

Member Descriptions

  • type is the XrStructureType of this structure.
  • next is NULL or a pointer to the next structure in a structure chain. No such structures are defined in core OpenXR or this extension.
  • session is a valid XrSession handle.

The application can retrieve this event by using xrPollEvent . This event will be sent when the dimming level is changed by either apps or physical buttons on devices.

This event will not be sent when focused app switches to another.

The application should respond to the event by calling xrGetGlobalDimmingLevelANDROID to get the new dimming level and update XrGlobalDimmingFrameEndInfoANDROID :: globalDimmingLevel accordingly. Responding to the event guarantees the runtime will be signaled when the application changes preferred dimming level.

Valid Usage (Implicit)

Example code

Check system capability & Enumerate supported global dimming levels

The following example code demonstrates how to check if the global dimming is supported.

XrInstance instance; // previously initialized
XrSystemId systemId; // previously initialized

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrEnumerateSupportedGlobalDimmingLevelsANDROID xrEnumerateSupportedGlobalDimmingLevelsANDROID;

XrSystemGlobalDimmingPropertiesANDROID dimmingControlSystemProperties { XR_TYPE_SYSTEM_GLOBAL_DIMMING_PROPERTIES_ANDROID };

XrSystemProperties systemProperties; // Chain dimmingControlSystemProperties

// ...
// Run xrGetSystemProperties()
// ...

if (!dimmingControlSystemProperties.supportsGlobalDimming) {
  // The system does not support global dimming
  return;
}

// Enumerate supported levels
uint32_t count = 0;
CHK_XR(xrEnumerateSupportedGlobalDimmingLevelsANDROID(instance, systemId, count, &count, nullptr));

std::vector<float> supportedLevels(count);
CHK_XR(xrEnumerateSupportedGlobalDimmingLevelsANDROID(instance, systemId, count, &count, supportedLevels.data()));

Poll Dimming Level Changed Event

The following example code demonstrates how to poll the dimming level changed event.

XrEventDataBuffer event{ XR_TYPE_EVENT_DATA_BUFFER };

// ...
// Run xrPollEvent()
// ...

switch (event.type) {
  // This event will not be sent when focused app switches
  case XR_TYPE_EVENT_DATA_GLOBAL_DIMMING_LEVEL_CHANGED_ANDROID:
  {
    const XrEventDataGlobalDimmingLevelChangedANDROID &dimmingLevelChangedEvent =
            *reinterpret_cast<XrEventDataGlobalDimmingLevelChangedANDROID *>(&event);

    // Query new dimming level using xrGetGlobalDimmingLevelANDROID()
  }
}

New Commands

New Structures

New Enum Constants

  • XR_ANDROID_GLOBAL_PASSTHROUGH_DIMMING_EXTENSION_NAME
  • XR_ANDROID_global_passthrough_dimming_SPEC_VERSION

  • Extending XrStructureType :

    • XR_TYPE_EVENT_DATA_GLOBAL_DIMMING_LEVEL_CHANGED_ANDROID
    • XR_TYPE_GLOBAL_DIMMING_FRAME_END_INFO_ANDROID
    • XR_TYPE_SYSTEM_GLOBAL_DIMMING_PROPERTIES_ANDROID

Issues

Version History

  • Revision 1, 2025-10-07 (Brian Chen)

    • Initial extension description.