XR_ANDROID_global_passthrough_dimming

Name String

XR_ANDROID_global_passthrough_dimming

Tipo de extensión

Extensión de instancia

Número de extensión registrado

797

Revisión

1

Estado de ratificación

No ratificado

Dependencias de extensiones y versiones

OpenXR 1.0

Fecha de la última modificación

2026-03-10

Estado de la IP

No hay reclamos de IP conocidos.

Colaboradores

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

Descripción general

A medida que se introducen los dispositivos ópticos transparentes, es importante no solo permitir que las aplicaciones ajusten la oscuridad de la transferencia para proporcionar la mejor combinación con el contexto de la app al usuario, sino también permitir que el sistema atenúe la transferencia por motivos de seguridad.

Esta extensión proporciona dos funciones para que las apps establezcan y obtengan el nivel de atenuación actual, así como un evento para transmitir cuando cambia el nivel de atenuación.

Inspecciona la capacidad del sistema

La estructura XrSystemGlobalDimmingPropertiesANDROID se define de la siguiente manera:

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

Descripciones de los miembros

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión. No se definen tales estructuras en OpenXR principal ni en esta extensión.
  • supportsGlobalDimming es un XrBool32 que indica si el sistema actual admite la atenuación global.

Una aplicación puede inspeccionar si el sistema admite la atenuación global encadenando una estructura XrSystemGlobalDimmingPropertiesANDROID a XrSystemProperties cuando se llama a xrGetSystemProperties .

Si el entorno de ejecución devuelve XR_FALSE para supportsGlobalDimming, debe devolver XR_ERROR_FEATURE_UNSUPPORTED cuando se llama a xrGetGlobalDimmingLevelANDROID.

Uso válido (implícito)

Enumera los niveles de atenuación global admitidos

La estructura xrEnumerateSupportedGlobalDimmingLevelsANDROID se define de la siguiente manera:

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

Descripciones de los miembros

  • instance es la instancia de la que se recuperó systemId.
  • systemId es el XrSystemId cuyos niveles admitidos se enumerarán.
  • supportedGlobalDimmingLevelCapacityInput es la capacidad del array supportedGlobalDimmingLevels, o 0 para indicar una solicitud de recuperación de la capacidad requerida.
  • supportedGlobalDimmingLevelCountOutput es un puntero al recuento de supportedGlobalDimmingLevels escritos o un puntero a la capacidad requerida en caso de que supportedGlobalDimmingLevelCapacityInput sea insuficiente.
  • supportedGlobalDimmingLevels es un puntero a un array de niveles admitidos, pero puede ser NULL si supportedGlobalDimmingLevelCapacityInput es 0.

Si el valor de supportedGlobalDimmingLevelCountOutput que se devuelve es 0, se admiten todos los niveles de atenuación global entre 0.0 y 1.0.

xrEnumerateSupportedGlobalDimmingLevelsANDROID enumera los niveles de atenuación global que admite el XrSystemId . Los niveles admitidos no deben cambiar durante el ciclo de vida de su XrInstance . La lista de niveles que se muestra debe ordenarse de forma ascendente.

Los entornos de ejecución deben siempre mostrar contenidos de búfer idénticos de esta enumeración para el systemId determinado y durante el ciclo de vida de instance .

Uso válido (implícito)

  • La extensión XR_ANDROID_global_passthrough_dimming debe estar habilitada antes de llamar a xrEnumerateSupportedGlobalDimmingLevelsANDROID.
  • instance debe ser un controlador XrInstance válido.
  • supportedGlobalDimmingLevelCountOutput debe ser un puntero a un valor uint32_t
  • Si supportedGlobalDimmingLevelCapacityInput no es 0 , supportedGlobalDimmingLevels debe ser un puntero a un array de valores supportedGlobalDimmingLevelCapacityInput float

Códigos de retorno

Listo

  • XR_SUCCESS

Falla

  • 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

Configura el nivel de atenuación global

La estructura XrGlobalDimmingFrameEndInfoANDROID se define de la siguiente manera:

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

Descripciones de los parámetros

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.
  • globalDimmingLevel es un valor entre 0.0 (transparente) y 1.0 (opaco). El entorno de ejecución puede asignar este valor al nivel de atenuación global compatible más cercano. La aplicación puede establecer este valor en -1.0 para indicar que se prefiere el nivel de atenuación actual.

El valor globalDimmingLevel especifica el porcentaje de luz que se bloquea, donde un valor de 0.0 corresponde al 0% de bloqueo de luz y 1.0 corresponde al 100% de bloqueo de luz. El porcentaje de luz bloqueada se puede representar, en general, de la siguiente manera:

100% - Light Transmittance%

El porcentaje de transmisión de luz, según la norma ISO 8980-3:2022 , se puede medir como la proporción entre el flujo radiante transmitido y el flujo radiante incidente en longitudes de onda de luz visible (de 380 nm a 780 nm).

XrGlobalDimmingFrameEndInfoANDROID es una estructura que una aplicación puede encadenar en XrFrameEndInfo para solicitar un nivel de atenuación global preferido.

El entorno de ejecución debe respetar el nivel de atenuación solicitado si este es diferente del nivel de atenuación actual.

El entorno de ejecución tendrá el control del nivel de atenuación global y puede ignorar el nivel de atenuación global preferido por motivos de seguridad.

Uso válido (implícito)

La función xrGetGlobalDimmingLevelANDROID se define de la siguiente manera:

XrResult xrGetGlobalDimmingLevelANDROID(
    XrSession                                   session,
    float*                                      dimmingLevel);

Descripciones de los parámetros

  • session es un controlador XrSession válido.
  • dimmingLevel es un puntero al nivel de atenuación actual.

El valor dimmingLevel que se muestra debe estar entre 0.0 y 1.0, donde 0.0 significa completamente transparente y 1.0 significa completamente atenuado.

Si no se estableció el nivel de atenuación, el entorno de ejecución debe establecerlo en 0.0 cuando la transferencia esté habilitada y en 1.0 cuando esté inhabilitada.

Uso válido (implícito)

  • La extensión XR_ANDROID_global_passthrough_dimming debe estar habilitada antes de llamar a xrGetGlobalDimmingLevelANDROID.
  • session debe ser un controlador XrSession válido
  • dimmingLevel debe ser un puntero a un valor float

Códigos de retorno

Listo

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falla

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

Evento de cambio de nivel de atenuación

La estructura XrEventDataGlobalDimmingLevelChangedANDROID se define de la siguiente manera:

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

Descripciones de los miembros

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.
  • session es un controlador XrSession válido.

La aplicación puede recuperar este evento con xrPollEvent . Este evento se enviará cuando el nivel de atenuación cambie por las apps o los botones físicos de los dispositivos.

Este evento no se enviará cuando la app enfocada cambie a otra.

La aplicación debería responder al evento llamando a xrGetGlobalDimmingLevelANDROID para obtener el nuevo nivel de atenuación y actualizar XrGlobalDimmingFrameEndInfoANDROID :: globalDimmingLevel según corresponda. Responder al evento garantiza que se indicará al entorno de ejecución cuando la aplicación cambie el nivel de atenuación preferido.

Uso válido (implícito)

Ejemplo de código

Verifica la capacidad del sistema y enumera los niveles de atenuación global admitidos

En el siguiente código de ejemplo, se muestra cómo verificar si se admite la atenuación global.

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()));

Evento de cambio de nivel de atenuación de sondeo

En el siguiente código de ejemplo, se muestra cómo sondear el evento de cambio de nivel de atenuación.

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()
  }
}

Comandos nuevos

Estructuras nuevas

Nuevas constantes de enum

  • XR_ANDROID_GLOBAL_PASSTHROUGH_DIMMING_EXTENSION_NAME
  • XR_ANDROID_global_passthrough_dimming_SPEC_VERSION

  • Extiende 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

Problemas

Historial de versiones

  • Revisión 1, 7 de octubre de 2025 (Brian Chen)

    • Descripción inicial de la extensión.