XR_ANDROID_global_passthrough_dimming

Name String

XR_ANDROID_global_passthrough_dimming

Type d'extension

Extension d'instance

Numéro d'extension enregistré

797

Révision

1

État de la ratification

Non ratifié

Dépendances d'extension et de version

OpenXR 1.0

Date de dernière modification

2026-03-10

État de l'adresse IP

Aucune réclamation de propriété intellectuelle connue.

Participants

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

Présentation

Avec l'introduction des appareils optiques transparents, il est important de permettre aux applications d'ajuster l'obscurité du passthrough afin d'offrir à l'utilisateur la meilleure intégration possible avec le contexte de l'application, mais aussi de permettre au système d'éclaircir le passthrough pour des raisons de sécurité.

Cette extension fournit deux fonctions permettant aux applications de définir et d'obtenir le niveau d'atténuation actuel, ainsi qu'un événement à diffuser lorsque le niveau d'atténuation change.

Inspecter les capacités du système

La structure XrSystemGlobalDimmingPropertiesANDROID est définie comme suit :

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

Descriptions des membres

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures. Aucune structure de ce type n'est définie dans OpenXR de base ou dans cette extension. Aucune structure de ce type n'est définie dans OpenXR de base ou dans cette extension.
  • supportsGlobalDimming est un XrBool32 , qui indique si le système actuel est compatible avec la gradation globale.

Une application peut vérifier si le système est compatible avec l'atténuation globale en associant une structure XrSystemGlobalDimmingPropertiesANDROID à XrSystemProperties lors de l'appel de xrGetSystemProperties .

Si l'environnement d'exécution renvoie XR_FALSE pour supportsGlobalDimming , il doit renvoyer XR_ERROR_FEATURE_UNSUPPORTED lorsque xrGetGlobalDimmingLevelANDROID est appelé.

Utilisation valide (implicite)

Énumérer les niveaux de gradation globale compatibles

La structure xrEnumerateSupportedGlobalDimmingLevelsANDROID est définie comme suit :

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

Descriptions des membres

  • instance est l'instance à partir de laquelle systemId a été récupéré.
  • systemId est l'élément XrSystemId dont les niveaux compatibles seront énumérés.
  • supportedGlobalDimmingLevelCapacityInput est la capacité du tableau supportedGlobalDimmingLevels, ou 0 pour indiquer une requête de récupération de la capacité requise.
  • supportedGlobalDimmingLevelCountOutput est un pointeur vers le nombre de supportedGlobalDimmingLevels écrits, ou un pointeur vers la capacité requise si supportedGlobalDimmingLevelCapacityInput est insuffisant.
  • supportedGlobalDimmingLevels est un pointeur vers un tableau de niveaux compatibles, mais peut être NULL si supportedGlobalDimmingLevelCapacityInput est égal à 0.

Si la valeur supportedGlobalDimmingLevelCountOutput renvoyée est 0, tous les niveaux de gradation globale compris entre 0,0 et 1,0 sont acceptés.

xrEnumerateSupportedGlobalDimmingLevelsANDROID énumère les niveaux d'assombrissement global acceptés par le XrSystemId . Les niveaux acceptés ne doivent pas changer pendant la durée de vie de son XrInstance . La liste des niveaux renvoyée doit être triée par ordre croissant.

Les environnements d'exécution doivent toujours renvoyer un contenu de tampon identique à partir de cette énumération pour le systemId donné et pendant la durée de vie de instance .

Utilisation valide (implicite)

  • L'extension XR_ANDROID_global_passthrough_dimming doit être activée avant d'appeler xrEnumerateSupportedGlobalDimmingLevelsANDROID.
  • instance doit être un handle XrInstance valide
  • supportedGlobalDimmingLevelCountOutput doit être un pointeur vers une valeur uint32_t
  • Si supportedGlobalDimmingLevelCapacityInput n'est pas 0 , supportedGlobalDimmingLevels doit être un pointeur vers un tableau de valeurs supportedGlobalDimmingLevelCapacityInput float.

Codes renvoyés

Opération réussie

  • XR_SUCCESS

Échec

  • 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

Configurer le niveau de réduction globale de la luminosité

La structure XrGlobalDimmingFrameEndInfoANDROID est définie comme suit :

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

Description des paramètres

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures. Aucune structure de ce type n'est définie dans OpenXR de base ou dans cette extension.
  • globalDimmingLevel est une valeur comprise entre 0,0 (transparent) et 1,0 (opaque). L'environnement d'exécution peut mapper cette valeur au niveau de gradation globale compatible le plus proche. L'application peut définir cette valeur sur -1,0 pour indiquer que le niveau d'atténuation actuel est préférable.

La valeur globalDimmingLevel spécifie le pourcentage de lumière bloquée, où une valeur de 0,0 correspond à 0 % de lumière bloquée et 1,0 correspond à 100 % de lumière bloquée. Le pourcentage de lumière bloquée peut être représenté de manière générale comme suit :

100% - Light Transmittance%

Le pourcentage de transmission de la lumière, conformément à la norme ISO 8980-3:2022 , peut être mesuré comme le rapport entre le flux radiant transmis et le flux radiant incident aux longueurs d'onde de la lumière visible (380 nm à 780 nm).

XrGlobalDimmingFrameEndInfoANDROID est une structure qu'une application peut enchaîner dans XrFrameEndInfo pour demander un niveau de gradation globale préféré.

L'environnement d'exécution doit respecter le niveau de gradation demandé s'il est différent du niveau de gradation actuel.

L'environnement d'exécution contrôlera le niveau d'assombrissement global et pourra ignorer le niveau d'assombrissement global préféré pour des raisons de sécurité.

Utilisation valide (implicite)

La fonction xrGetGlobalDimmingLevelANDROID est définie comme suit :

XrResult xrGetGlobalDimmingLevelANDROID(
    XrSession                                   session,
    float*                                      dimmingLevel);

Description des paramètres

  • session est un handle XrSession valide.
  • dimmingLevel est un pointeur vers le niveau d'atténuation actuel.

La valeur dimmingLevel renvoyée doit être comprise entre 0,0 et 1,0, où 0,0 signifie "totalement transparent" et 1,0 signifie "totalement assombri".

Si le niveau d'atténuation n'a pas été défini, l'environnement d'exécution doit le définir sur 0,0 lorsque le passthrough est activé et sur 1,0 lorsqu'il est désactivé.

Utilisation valide (implicite)

  • L'extension XR_ANDROID_global_passthrough_dimming doit être activée avant d'appeler xrGetGlobalDimmingLevelANDROID.
  • session doit être un handle XrSession valide
  • dimmingLevel doit être un pointeur vers une valeur float

Codes renvoyés

Opération réussie

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Échec

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

Événement de modification du niveau de luminosité

La structure XrEventDataGlobalDimmingLevelChangedANDROID est définie comme suit :

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

Descriptions des membres

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures. Aucune structure de ce type n'est définie dans OpenXR de base ou dans cette extension.
  • session est un handle XrSession valide.

L'application peut récupérer cet événement à l'aide de xrPollEvent . Cet événement est envoyé lorsque le niveau de luminosité est modifié par des applications ou par des boutons physiques sur les appareils.

Cet événement n'est pas envoyé lorsque l'application sélectionnée passe à une autre.

L'application doit répondre à l'événement en appelant xrGetGlobalDimmingLevelANDROID pour obtenir le nouveau niveau d'atténuation et mettre à jour XrGlobalDimmingFrameEndInfoANDROID :: globalDimmingLevel en conséquence. La réponse à l'événement garantit que l'environnement d'exécution sera signalé lorsque l'application modifiera le niveau d'assombrissement préféré.

Utilisation valide (implicite)

Exemple de code

Vérifier les capacités du système et énumérer les niveaux de gradation globale compatibles

L'exemple de code suivant montre comment vérifier si la gradation globale est prise en charge.

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

Événement de modification du niveau de gradation de l'interrogation

L'exemple de code suivant montre comment interroger l'événement de modification du niveau de luminosité.

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

Nouvelles commandes

Nouvelles structures

Nouvelles constantes d'énumération

  • XR_ANDROID_GLOBAL_PASSTHROUGH_DIMMING_EXTENSION_NAME
  • XR_ANDROID_global_passthrough_dimming_SPEC_VERSION

  • Extension de 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

Problèmes

Historique des versions

  • Révision 1, 07/10/2025 (Brian Chen)

    • Description initiale de l'extension.