XR_ANDROID_global_passthrough_dimming

Name String

XR_ANDROID_global_passthrough_dimming

Typ rozszerzenia

Rozszerzenie instancji

Zarejestrowany numer wewnętrzny

797

Wersja

1

Stan ratyfikacji

Nie ratyfikowano

Zależności rozszerzeń i wersji

OpenXR 1.0

Data ostatniej modyfikacji

2026-03-10

Stan IP

Brak znanych roszczeń dotyczących własności intelektualnej.

Twórcy

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

Przegląd

Wraz z wprowadzeniem urządzeń z optycznym trybem przezroczystości ważne jest nie tylko umożliwienie aplikacjom dostosowywania poziomu przyciemnienia trybu przezroczystości, aby zapewnić użytkownikowi najlepsze połączenie z kontekstem aplikacji, ale także umożliwienie systemowi rozjaśniania trybu przezroczystości ze względów bezpieczeństwa.

To rozszerzenie udostępnia aplikacjom 2 funkcje do ustawiania i pobierania bieżącego poziomu przyciemnienia, a także zdarzenie do transmitowania, gdy poziom przyciemnienia się zmieni.

Sprawdzanie możliwości systemu

Struktura XrSystemGlobalDimmingPropertiesANDROID jest zdefiniowana w ten sposób:

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

Opisy członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur. W podstawowym interfejsie OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur. W podstawowym interfejsie OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.
  • supportsGlobalDimming to XrBool32, który wskazuje, czy bieżący system obsługuje globalne przyciemnianie.

Aplikacja może sprawdzić, czy system obsługuje globalne przyciemnianie, przez połączenie struktury XrSystemGlobalDimmingPropertiesANDROID z XrSystemProperties podczas wywoływania xrGetSystemProperties .

Jeśli środowisko wykonawcze zwraca XR_FALSE dla supportsGlobalDimming, musi zwracać XR_ERROR_FEATURE_UNSUPPORTED, gdy wywoływana jest funkcja xrGetGlobalDimmingLevelANDROID.

Prawidłowe użycie (pośrednie)

Wylicz obsługiwane poziomy globalnego przyciemniania

Struktura xrEnumerateSupportedGlobalDimmingLevelsANDROID jest zdefiniowana w ten sposób:

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

Opisy członków

  • instance to instancja, z której pobrano systemId.
  • systemId to XrSystemId, którego obsługiwane poziomy zostaną wymienione.
  • supportedGlobalDimmingLevelCapacityInput to pojemność tablicy supportedGlobalDimmingLevels lub 0, co oznacza prośbę o pobranie wymaganej pojemności.
  • supportedGlobalDimmingLevelCountOutput to wskaźnik liczby zapisanych supportedGlobalDimmingLevels lub wskaźnik wymaganej pojemności, jeśli supportedGlobalDimmingLevelCapacityInput jest niewystarczająca.
  • supportedGlobalDimmingLevels to wskaźnik do tablicy obsługiwanych poziomów, ale może mieć wartość NULL, jeśli supportedGlobalDimmingLevelCapacityInput wynosi 0.

Jeśli zwrócona wartość supportedGlobalDimmingLevelCountOutput wynosi 0, obsługiwane są wszystkie poziomy globalnego przyciemniania od 0,0 do 1,0.

xrEnumerateSupportedGlobalDimmingLevelsANDROID wylicza poziomy globalnego przyciemniania obsługiwane przez XrSystemId . Obsługiwane poziomy nie mogą się zmieniać w czasie istnienia instancji XrInstance . Zwrócona lista poziomów musi być posortowana w kolejności rosnącej.

Środowiska wykonawcze muszą zawsze zwracać identyczną zawartość bufora z tego wyliczenia dla danego systemId i przez cały okres istnienia instance .

Prawidłowe użycie (pośrednie)

  • Rozszerzenie XR_ANDROID_global_passthrough_dimming musi być włączone przed wywołaniem funkcji xrEnumerateSupportedGlobalDimmingLevelsANDROID.
  • instance musi być prawidłowym uchwytem XrInstance
  • supportedGlobalDimmingLevelCountOutput musi być wskaźnikiem do wartości uint32_t
  • Jeśli supportedGlobalDimmingLevelCapacityInput nie jest 0 , supportedGlobalDimmingLevels musi być wskaźnikiem do tablicy wartości supportedGlobalDimmingLevelCapacityInput float

Kody zwrotu

Sukces

  • XR_SUCCESS

Błąd

  • 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

Konfigurowanie poziomu globalnego przyciemnienia

Struktura XrGlobalDimmingFrameEndInfoANDROID jest zdefiniowana w ten sposób:

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

Opisy parametrów

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur. W podstawowym interfejsie OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.
  • globalDimmingLevel to wartość z zakresu od 0,0 (przezroczysty) do 1,0 (nieprzezroczysty). Środowisko wykonawcze może zmapować tę wartość na najbliższy obsługiwany poziom globalnego przyciemniania. Aplikacja może ustawić tę wartość na -1,0, aby wskazać, że preferowany jest bieżący poziom przyciemnienia.

Wartość globalDimmingLevel określa procent blokowanego światła, gdzie wartość 0,0 odpowiada 0% blokowanego światła, a 1,0 odpowiada 100% blokowanego światła. Odsetek zablokowanego światła można ogólnie przedstawić w ten sposób:

100% - Light Transmittance%

Zgodnie z normą ISO 8980-3:2022 procent przepuszczalności światła można mierzyć jako stosunek przepuszczanego strumienia promieniowania do padającego strumienia promieniowania przy długościach fal światła widzialnego (od 380 nm do 780 nm).

XrGlobalDimmingFrameEndInfoANDROID to struktura, którą aplikacja może połączyć w łańcuch w XrFrameEndInfo, aby poprosić o preferowany poziom globalnego przyciemnienia.

Środowisko wykonawcze musi uwzględniać żądany poziom przyciemnienia, jeśli różni się on od bieżącego.

Środowisko wykonawcze będzie kontrolować poziom globalnego przyciemnienia i może ze względów bezpieczeństwa ignorować preferowany poziom globalnego przyciemnienia.

Prawidłowe użycie (pośrednie)

Funkcja xrGetGlobalDimmingLevelANDROID jest zdefiniowana w ten sposób:

XrResult xrGetGlobalDimmingLevelANDROID(
    XrSession                                   session,
    float*                                      dimmingLevel);

Opisy parametrów

  • session to prawidłowy uchwyt XrSession.
  • dimmingLevel to wskaźnik bieżącego poziomu przyciemnienia.

Zwrócona wartość dimmingLevel musi mieścić się w zakresie od 0,0 do 1,0, gdzie 0,0 oznacza pełną przezroczystość, a 1,0 – pełne przyciemnienie.

Jeśli poziom przyciemnienia nie został ustawiony, środowisko wykonawcze musi ustawić poziom przyciemnienia na 0,0, gdy tryb passthrough jest włączony, i na 1,0, gdy tryb passthrough jest wyłączony.

Prawidłowe użycie (pośrednie)

  • Rozszerzenie XR_ANDROID_global_passthrough_dimming musi być włączone przed wywołaniem xrGetGlobalDimmingLevelANDROID.
  • session musi być prawidłowym uchwytem XrSession
  • dimmingLevel musi być wskaźnikiem do wartości float

Kody zwrotu

Sukces

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Błąd

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

Zdarzenie zmiany poziomu ściemniania

Struktura XrEventDataGlobalDimmingLevelChangedANDROID jest zdefiniowana w ten sposób:

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

Opisy członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur. W podstawowym interfejsie OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.
  • session to prawidłowy uchwyt XrSession.

Aplikacja może pobrać to zdarzenie za pomocą xrPollEvent . To zdarzenie zostanie wysłane, gdy poziom przyciemnienia zostanie zmieniony przez aplikacje lub przyciski fizyczne na urządzeniach.

To zdarzenie nie zostanie wysłane, gdy aplikacja, na której skupia się użytkownik, zostanie przełączona na inną.

Aplikacja powinna odpowiedzieć na zdarzenie, wywołując funkcję xrGetGlobalDimmingLevelANDROID, aby uzyskać nowy poziom przyciemnienia i odpowiednio zaktualizować XrGlobalDimmingFrameEndInfoANDROID :: globalDimmingLevel. Odpowiedź na zdarzenie gwarantuje, że środowisko wykonawcze otrzyma sygnał, gdy aplikacja zmieni preferowany poziom przyciemnienia.

Prawidłowe użycie (pośrednie)

Przykładowy kod

Sprawdzanie możliwości systemu i wyliczanie obsługiwanych poziomów globalnego przyciemniania

Poniższy przykładowy kod pokazuje, jak sprawdzić, czy globalne przyciemnianie jest obsługiwane.

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

Zdarzenie zmiany poziomu ściemniania podczas sondowania

Poniższy przykładowy kod pokazuje, jak odpytywać zdarzenie zmiany poziomu ściemnienia.

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

Nowe polecenia

Nowe domy

Nowe stałe typu wyliczeniowego

  • XR_ANDROID_GLOBAL_PASSTHROUGH_DIMMING_EXTENSION_NAME
  • XR_ANDROID_global_passthrough_dimming_SPEC_VERSION

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

Problemy

Historia zmian

  • Wersja 1, 7 października 2025 r. (Brian Chen)

    • Początkowy opis rozszerzenia.