XR_ANDROID_global_passthrough_dimming

Name String

XR_ANDROID_global_passthrough_dimming

Erweiterungstyp

Instanzerweiterung

Registrierte Durchwahl

797

Revision

1

Ratification Status

Nicht ratifiziert

Erweiterungs- und Versionsabhängigkeiten

OpenXR 1.0

Datum der letzten Änderung

2026-03-10

IP-Status

Keine bekannten Ansprüche auf geistiges Eigentum.

Mitwirkende

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

Übersicht

Mit der Einführung von Geräten mit optischem Durchblick ist es wichtig, dass Anwendungen die Dunkelheit des Passthrough anpassen können, um dem Nutzer die beste Verschmelzung mit dem App-Kontext zu bieten. Außerdem muss das System den Passthrough aus Sicherheitsgründen aufhellen können.

Diese Erweiterung bietet zwei Funktionen, mit denen Apps die aktuelle Dimmstufe festlegen und abrufen können, sowie ein Ereignis, das übertragen wird, wenn sich die Dimmstufe ändert.

Systemkapazität prüfen

Die Struktur XrSystemGlobalDimmingPropertiesANDROID ist so definiert:

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

Mitgliederbeschreibungen

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind weder in OpenXR noch in dieser Erweiterung definiert. Solche Strukturen sind weder in OpenXR noch in dieser Erweiterung definiert.
  • supportsGlobalDimming ist ein XrBool32, der angibt, ob das aktuelle System globales Dimmen unterstützt.

Eine Anwendung kann prüfen, ob das System globales Dimmen unterstützt, indem sie beim Aufruf von xrGetSystemProperties eine XrSystemGlobalDimmingPropertiesANDROID-Struktur an die XrSystemProperties anhängt.

Wenn die Laufzeit XR_FALSE für supportsGlobalDimming zurückgibt, muss sie XR_ERROR_FEATURE_UNSUPPORTED zurückgeben, wenn xrGetGlobalDimmingLevelANDROID aufgerufen wird.

Gültige Verwendung (implizit)

Unterstützte globale Dimmstufen aufzählen

Die Struktur xrEnumerateSupportedGlobalDimmingLevelsANDROID ist so definiert:

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

Mitgliederbeschreibungen

  • instance ist die Instanz, aus der systemId abgerufen wurde.
  • systemId ist die XrSystemId, deren unterstützte Stufen aufgezählt werden.
  • supportedGlobalDimmingLevelCapacityInput ist die Kapazität des supportedGlobalDimmingLevels-Arrays oder 0, um eine Anfrage zum Abrufen der erforderlichen Kapazität anzugeben.
  • supportedGlobalDimmingLevelCountOutput ist ein Zeiger auf die Anzahl der geschriebenen supportedGlobalDimmingLevels oder ein Zeiger auf die erforderliche Kapazität, falls supportedGlobalDimmingLevelCapacityInput nicht ausreicht.
  • supportedGlobalDimmingLevels ist ein Zeiger auf ein Array unterstützter Level, kann aber NULL sein, wenn supportedGlobalDimmingLevelCapacityInput 0 ist.

Wenn der zurückgegebene supportedGlobalDimmingLevelCountOutput-Wert 0 ist, werden alle globalen Dimmstufen zwischen 0,0 und 1,0 unterstützt.

xrEnumerateSupportedGlobalDimmingLevelsANDROID listet die globalen Dimmstufen auf, die von XrSystemId unterstützt werden. Die unterstützten Ebenen dürfen sich während der Lebensdauer der XrInstance nicht ändern. Die zurückgegebene Liste der Ebenen muss in aufsteigender Reihenfolge sortiert sein.

Laufzeiten müssen für die angegebene systemId und für die Lebensdauer der instance immer identische Pufferinhalte aus dieser Aufzählung zurückgeben.

Gültige Verwendung (implizit)

  • Die Erweiterung XR_ANDROID_global_passthrough_dimming muss aktiviert sein, bevor xrEnumerateSupportedGlobalDimmingLevelsANDROID aufgerufen wird.
  • instance muss ein gültiges XrInstance-Handle sein
  • supportedGlobalDimmingLevelCountOutput muss ein Zeiger auf einen uint32_t-Wert sein
  • Wenn supportedGlobalDimmingLevelCapacityInput nicht 0 ist, muss supportedGlobalDimmingLevels ein Zeiger auf ein Array von supportedGlobalDimmingLevelCapacityInput-float-Werten sein.

Rückgabecodes

Erfolg

  • XR_SUCCESS

Fehler

  • 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

Globales Dimmen konfigurieren

Die Struktur XrGlobalDimmingFrameEndInfoANDROID ist so definiert:

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

Parameterbeschreibungen

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind weder in OpenXR noch in dieser Erweiterung definiert.
  • globalDimmingLevel ist ein Wert zwischen 0,0 (transparent) und 1,0 (undurchsichtig). Die Laufzeit kann diesen Wert der nächstgelegenen unterstützten globalen Dimmstufe zuordnen. Die Anwendung kann diesen Wert auf -1,0 setzen, um anzugeben, dass die aktuelle Dimmstufe bevorzugt wird.

Der Wert globalDimmingLevel gibt den Prozentsatz des blockierten Lichts an, wobei ein Wert von 0,0 0 % und 1,0 100 % blockiertem Licht entspricht. Der Prozentsatz des blockierten Lichts kann im Allgemeinen so dargestellt werden:

100% - Light Transmittance%

Der Prozentsatz der Lichtdurchlässigkeit gemäß ISO 8980-3:2022 kann als Verhältnis des durchgelassenen Strahlungsflusses zum einfallenden Strahlungsfluss bei Wellenlängen des sichtbaren Lichts (380 nm bis 780 nm) gemessen werden.

XrGlobalDimmingFrameEndInfoANDROID ist eine Struktur, die eine Anwendung in XrFrameEndInfo verketten kann, um eine bevorzugte globale Dimmstufe anzufordern.

Die Laufzeit muss die angeforderte Dimmstufe berücksichtigen, wenn sie sich von der aktuellen Dimmstufe unterscheidet.

Die Laufzeit hat die Kontrolle über die globale Dimmstufe und kann die bevorzugte globale Dimmstufe aus Sicherheitsgründen ignorieren.

Gültige Verwendung (implizit)

Die Funktion xrGetGlobalDimmingLevelANDROID ist so definiert:

XrResult xrGetGlobalDimmingLevelANDROID(
    XrSession                                   session,
    float*                                      dimmingLevel);

Parameterbeschreibungen

  • session ist ein gültiges XrSession-Handle.
  • dimmingLevel ist ein Zeiger auf die aktuelle Dimmstufe.

Der zurückgegebene dimmingLevel-Wert muss zwischen 0,0 und 1,0 liegen, wobei 0,0 für vollständig transparent und 1,0 für vollständig gedimmt steht.

Wenn die Dimmstufe nicht festgelegt wurde, muss die Laufzeit die Dimmstufe auf 0,0 setzen, wenn Passthrough aktiviert ist, und auf 1,0, wenn Passthrough deaktiviert ist.

Gültige Verwendung (implizit)

  • Die Erweiterung XR_ANDROID_global_passthrough_dimming muss aktiviert sein, bevor xrGetGlobalDimmingLevelANDROID aufgerufen wird.
  • session muss ein gültiges XrSession-Handle sein
  • dimmingLevel muss ein Zeiger auf einen float-Wert sein

Rückgabecodes

Erfolg

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Fehler

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

Ereignis „Dimmstufe geändert“

Die Struktur XrEventDataGlobalDimmingLevelChangedANDROID ist so definiert:

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

Mitgliederbeschreibungen

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind weder in OpenXR noch in dieser Erweiterung definiert.
  • session ist ein gültiges XrSession-Handle.

Die Anwendung kann dieses Ereignis mit xrPollEvent abrufen. Dieses Ereignis wird gesendet, wenn die Helligkeitsstufe entweder durch Apps oder durch physische Tasten auf Geräten geändert wird.

Dieses Ereignis wird nicht gesendet, wenn die App im Vordergrund zu einer anderen wechselt.

Die Anwendung sollte auf das Ereignis reagieren, indem sie xrGetGlobalDimmingLevelANDROID aufruft, um die neue Dimmstufe abzurufen und XrGlobalDimmingFrameEndInfoANDROID :: globalDimmingLevel entsprechend zu aktualisieren. Wenn Sie auf das Ereignis reagieren, wird die Laufzeitumgebung benachrichtigt, wenn die Anwendung die bevorzugte Dimmstufe ändert.

Gültige Verwendung (implizit)

Beispielcode

Systemkapazität prüfen und unterstützte globale Dimmstufen auflisten

Der folgende Beispielcode zeigt, wie Sie prüfen, ob globales Dimmen unterstützt wird.

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

Ereignis „Dimmstufe geändert“ abfragen

Der folgende Beispielcode zeigt, wie das Ereignis „Dimmstufe geändert“ abgefragt wird.

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

Neue Befehle

Neue Gebäude

Neue Enum-Konstanten

  • XR_ANDROID_GLOBAL_PASSTHROUGH_DIMMING_EXTENSION_NAME
  • XR_ANDROID_global_passthrough_dimming_SPEC_VERSION

  • Erweiterung von 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

Probleme

Versionsverlauf

  • Version 1, 07.10.2025 (Brian Chen)

    • Erste Beschreibung der Erweiterung.