XR_ANDROID_global_passthrough_dimming

Name String

XR_ANDROID_global_passthrough_dimming

Tipo di estensione

Estensione dell'istanza

Numero di interno registrato

797

Revisione

1

Stato della ratifica

Non ratificato

Dipendenze di estensioni e versioni

OpenXR 1.0

Data ultima modifica

2026-03-10

Stato IP

Nessuna rivendicazione di PI nota.

Collaboratori

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

Panoramica

Con l'introduzione dei dispositivi ottici trasparenti, è importante non solo consentire alle applicazioni di regolare l'oscurità del passthrough per fornire all'utente la migliore combinazione con il contesto dell'app, ma anche consentire al sistema di disattivare l'oscuramento del passthrough per motivi di sicurezza.

Questa estensione fornisce due funzioni per consentire alle app di impostare e ottenere il livello di oscuramento corrente, nonché un evento da trasmettere quando il livello di oscuramento cambia.

Ispeziona la funzionalità del sistema

La struttura XrSystemGlobalDimmingPropertiesANDROID è definita come:

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

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Nessuna struttura di questo tipo è definita in OpenXR di base o in questa estensione. Nessuna struttura di questo tipo è definita in OpenXR di base o in questa estensione.
  • supportsGlobalDimming è un XrBool32 che indica se il sistema attuale supporta l'attenuazione globale.

Un'applicazione può verificare se il sistema supporta l'oscuramento globale concatenando una struttura XrSystemGlobalDimmingPropertiesANDROID a XrSystemProperties quando chiama xrGetSystemProperties .

Se il runtime restituisce XR_FALSE per supportsGlobalDimming , il runtime deve restituire XR_ERROR_FEATURE_UNSUPPORTED quando viene chiamato xrGetGlobalDimmingLevelANDROID.

Utilizzo valido (implicito)

Enumera i livelli di attenuazione globale supportati

La struttura xrEnumerateSupportedGlobalDimmingLevelsANDROID è definita come:

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

Descrizioni dei membri

  • instance è l'istanza da cui è stato recuperato systemId.
  • systemId è il XrSystemId di cui verranno enumerati i livelli supportati.
  • supportedGlobalDimmingLevelCapacityInput è la capacità dell'array supportedGlobalDimmingLevels o 0 per indicare una richiesta di recupero della capacità richiesta.
  • supportedGlobalDimmingLevelCountOutput è un puntatore al conteggio di supportedGlobalDimmingLevels scritti o un puntatore alla capacità richiesta nel caso in cui supportedGlobalDimmingLevelCapacityInput non sia sufficiente.
  • supportedGlobalDimmingLevels è un puntatore a un array di livelli supportati, ma può essere NULL se supportedGlobalDimmingLevelCapacityInput è 0.

Se il valore supportedGlobalDimmingLevelCountOutput restituito è 0, sono supportati tutti i livelli di attenuazione globale compresi tra 0,0 e 1,0.

xrEnumerateSupportedGlobalDimmingLevelsANDROID enumera i livelli di oscuramento globale supportati da XrSystemId . I livelli supportati non devono cambiare durante la durata della relativa XrInstance . L'elenco dei livelli restituito deve essere ordinato in ordine crescente.

I runtime devono sempre restituire contenuti del buffer identici da questa enumerazione per il systemId specificato e per la durata del instance .

Utilizzo valido (implicito)

  • L'estensione XR_ANDROID_global_passthrough_dimming deve essere abilitata prima di chiamare xrEnumerateSupportedGlobalDimmingLevelsANDROID
  • instance deve essere un handle XrInstance valido
  • supportedGlobalDimmingLevelCountOutput deve essere un puntatore a un valore uint32_t
  • Se supportedGlobalDimmingLevelCapacityInput non è 0 , supportedGlobalDimmingLevels deve essere un puntatore a un array di valori supportedGlobalDimmingLevelCapacityInput float

Codici di risposta

Operazione riuscita

  • XR_SUCCESS

Errore

  • 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 il livello di abbassamento globale

La struttura XrGlobalDimmingFrameEndInfoANDROID è definita come:

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

Descrizioni dei parametri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Nessuna struttura di questo tipo è definita in OpenXR di base o in questa estensione.
  • globalDimmingLevel è un valore compreso tra 0,0 (trasparente) e 1,0 (opaco). Il runtime può mappare questo valore al livello di attenuazione globale supportato più vicino. L'applicazione può impostare questo valore su -1.0 per indicare che è preferibile il livello di oscuramento attuale.

Il valore globalDimmingLevel specifica la percentuale di luce bloccata, dove un valore pari a 0,0 corrisponde allo 0% di luce bloccata e 1,0 corrisponde al 100% di luce bloccata. La percentuale di luce bloccata può essere rappresentata in generale come:

100% - Light Transmittance%

La percentuale di trasmissione della luce, secondo lo standard ISO 8980-3:2022 , può essere misurata come il rapporto tra il flusso radiante trasmesso e il flusso radiante incidente alle lunghezze d'onda della luce visibile (da 380 nm a 780 nm).

XrGlobalDimmingFrameEndInfoANDROID è una struttura che un'applicazione può concatenare in XrFrameEndInfo per richiedere un livello di attenuazione globale preferito.

Il runtime deve rispettare il livello di oscuramento richiesto se è diverso da quello attuale.

Il runtime avrà il controllo del livello di oscuramento globale e potrebbe ignorare il livello di oscuramento globale preferito per motivi di sicurezza.

Utilizzo valido (implicito)

La funzione xrGetGlobalDimmingLevelANDROID è definita come:

XrResult xrGetGlobalDimmingLevelANDROID(
    XrSession                                   session,
    float*                                      dimmingLevel);

Descrizioni dei parametri

  • session è un handle XrSession valido.
  • dimmingLevel è un puntatore al livello di luminosità attuale.

Il valore dimmingLevel restituito deve essere compreso tra 0,0 e 1,0, dove 0,0 indica la trasparenza totale e 1,0 l'oscuramento totale.

Se il livello di oscuramento non è stato impostato, il runtime deve impostarlo su 0,0 quando il passthrough è attivo e su 1,0 quando è disattivato.

Utilizzo valido (implicito)

  • L'estensione XR_ANDROID_global_passthrough_dimming deve essere attivata prima di chiamare xrGetGlobalDimmingLevelANDROID
  • session deve essere un handle XrSession valido
  • dimmingLevel deve essere un puntatore a un valore float

Codici di risposta

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • 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 di modifica del livello di regolazione della luminosità

La struttura XrEventDataGlobalDimmingLevelChangedANDROID è definita come:

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

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Nessuna struttura di questo tipo è definita in OpenXR di base o in questa estensione.
  • session è un handle XrSession valido.

L'applicazione può recuperare questo evento utilizzando xrPollEvent . Questo evento verrà inviato quando il livello di oscuramento viene modificato dalle app o dai pulsanti fisici sui dispositivi.

Questo evento non viene inviato quando l'app attiva passa a un'altra.

L'applicazione dovrebbe rispondere all'evento chiamando xrGetGlobalDimmingLevelANDROID per ottenere il nuovo livello di oscuramento e aggiornare XrGlobalDimmingFrameEndInfoANDROID :: globalDimmingLevel di conseguenza. La risposta all'evento garantisce che il runtime riceva un segnale quando l'applicazione modifica il livello di attenuazione preferito.

Utilizzo valido (implicito)

Esempio di codice

Controlla la funzionalità del sistema ed enumera i livelli di attenuazione globale supportati

Il seguente codice di esempio mostra come verificare se l'oscuramento globale è supportato.

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 di modifica del livello di regolazione della luminosità del sondaggio

Il seguente codice di esempio mostra come eseguire il polling dell'evento di modifica del livello di regolazione della 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()
  }
}

Nuovi comandi

Nuove strutture

Nuove costanti enum

  • XR_ANDROID_GLOBAL_PASSTHROUGH_DIMMING_EXTENSION_NAME
  • XR_ANDROID_global_passthrough_dimming_SPEC_VERSION

  • Estensione di 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

Problemi

Cronologia delle versioni

  • Revisione 1, 7 ottobre 2025 (Brian Chen)

    • Descrizione iniziale dell'estensione.