Name String

XR_ANDROID_recommended_settings

Erweiterungstyp

Instanzerweiterung

Registrierte Durchwahl

455

Revision

1

Ratification Status

Nicht ratifiziert

Erweiterungs- und Versionsabhängigkeiten

OpenXR 1.0

Datum der letzten Änderung

2026-03-16

Mitwirkende

Spencer Quin, Google
Jared Finder, Google
Kevin Moule, Google
Nihav Jain, Google
Levana Chen, Google
Alvin Shi, Google
Salar Khan, Google

Übersicht

Die Standardumgebung des Nutzers kann sich in verschiedenen Zuständen befinden, die sich aus einer Kombination aus einem Mischmodus und einer Eingabemodalität ergeben. Diese Erweiterung bietet die empfohlenen Einstellungen für den Nutzer, die dem Zustand der Standardumgebung des Nutzers vor dem Start der Anwendung entsprechen, um einen reibungslosen Übergang zu ermöglichen.

Strukturen und Enums

Die XrInputModalityFlagsANDROID-Bits identifizieren verschiedene Eingabemodalitäten, die möglicherweise verwendet werden.

typedef XrFlags64 XrInputModalityFlagsANDROID;

Gültige Bits für XrInputModalityFlagsANDROID werden durch XrInputModalityFlagBitsANDROID definiert, das so angegeben wird:

// Flag bits for XrInputModalityFlagsANDROID
static const XrInputModalityFlagsANDROID XR_INPUT_MODALITY_HEAD_BIT_ANDROID = 0x00000001;
static const XrInputModalityFlagsANDROID XR_INPUT_MODALITY_CONTROLLER_BIT_ANDROID = 0x00000002;
static const XrInputModalityFlagsANDROID XR_INPUT_MODALITY_HANDS_BIT_ANDROID = 0x00000004;
static const XrInputModalityFlagsANDROID XR_INPUT_MODALITY_MOUSE_BIT_ANDROID = 0x00000008;
static const XrInputModalityFlagsANDROID XR_INPUT_MODALITY_GAZE_AND_GESTURE_BIT_ANDROID = 0x00000010;

Flag-Beschreibungen

  • XR_INPUT_MODALITY_HEAD_BIT_ANDROID: Gibt eine Eingabemodalität an, die die Erfassung von Kopfbewegungen verwendet.
  • XR_INPUT_MODALITY_CONTROLLER_BIT_ANDROID: Gibt eine Eingabemodalität an, die Eingaben von XR-Controllern verwendet.
  • XR_INPUT_MODALITY_HANDS_BIT_ANDROID: Gibt eine Eingabemodalität an, die Handtracking verwendet.
  • XR_INPUT_MODALITY_MOUSE_BIT_ANDROID: Gibt eine Eingabemodalität an, die Mauseingaben verwendet.
  • XR_INPUT_MODALITY_GAZE_AND_GESTURE_BIT_ANDROID: Gibt eine Eingabemodalität an, die Eye-Tracking und Handtracking kombiniert.

Die Struktur XrRecommendedSettingsANDROID ist so definiert:

typedef struct XrRecommendedSettingsANDROID {
    XrStructureType                type;
    void*                          next;
    XrEnvironmentBlendMode         blendMode;
    float                          passthroughOpacity;
    XrInputModalityFlagsANDROID    activeInputModalities;
} XrRecommendedSettingsANDROID;

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.
  • blendMode ist ein XrEnvironmentBlendMode, der den Standard-Mischmodus der Umgebung unmittelbar vor dem Start der Anwendung angibt.
  • passthroughOpacity ist ein float, der die Passthrough-Deckkraft der Standardumgebung unmittelbar vor dem Start der Anwendung angibt. Die Laufzeit muss diesen Wert für OST-Geräte auf (1,0 - dimming_value) festlegen.
  • activeInputModalities ist eine Bitmaske von XrInputModalityFlagsANDROID, die die Eingabemodalitäten angibt, die in der Standardumgebung unmittelbar vor dem Start der Anwendung verwendet werden.

Gültige Verwendung (implizit)

Unterstützte Umgebungsstatus auflisten

Eine Anwendung kann mit xrEnumerateEnvironmentBlendModes und durch Erweitern von XrSystemProperties mit der Struktur XrSystemInputModalityPropertiesANDROID beim Aufrufen von xrGetSystemProperties ermitteln, welche Mischmodi und Eingabemodalitätszustände vom System unterstützt werden.

Die Struktur XrSystemInputModalityPropertiesANDROID ist so definiert:

typedef struct XrSystemInputModalityPropertiesANDROID {
    XrStructureType                type;
    void*                          next;
    XrInputModalityFlagsANDROID    supportedInputModalities;
} XrSystemInputModalityPropertiesANDROID;

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.
  • supportedInputModalities ist ein oder mehrere XrInputModalityFlagsANDROID, die die vom System unterstützten Eingabemodalitäten angeben.

Gültige Verwendung (implizit)

Empfohlene Einstellungen abrufen (Standardumgebungsstatus vor der Einführung)

XrResult xrGetRecommendedSettingsANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrRecommendedSettingsANDROID*               output);

Parameterbeschreibungen

Gültige Verwendung (implizit)

Rückgabecodes

Erfolg

  • XR_SUCCESS

Fehler

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SYSTEM_INVALID

Beispielcode für empfohlene Einstellungen

Im folgenden Beispielcode wird gezeigt, wie Sie unterstützte Eingabemodalitäten und empfohlene Einstellungen abrufen und prüfen, ob die gemeldeten Einstellungen vom System unterstützt werden.

XrInstance instance;  // Created at app startup
XrSystemId systemId;  // previously initialized from xrGetSystem
XrViewConfigurationType viewType;  // previously initialized to select desired view configuration

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrGetRecommendedSettingsANDROID xrGetRecommendedSettingsANDROID; // previously initialized

XrSystemInputModalityPropertiesANDROID props = {
  .type = XR_TYPE_SYSTEM_INPUT_MODALITY_PROPERTIES_ANDROID
};
XrSystemProperties base = {
  .type = XR_TYPE_SYSTEM_PROPERTIES,
  .next = &props
};
CHK_XR(xrGetSystemProperties(instance, systemId, &base));

uint32_t blendModeCount = 0;
CHK_XR(
 xrEnumerateEnvironmentBlendModes(instance, systemId, viewType, 0, &blendModeCount, nullptr));
std::vector<XrEnvironmentBlendMode> supportedBlendModes(blendModeCount);
CHK_XR(
  xrEnumerateEnvironmentBlendModes(
    instance, systemId, viewType, blendModeCount, &blendModeCount, supportedBlendModes.data()));

XrRecommendedSettingsANDROID output = {
  .type = XR_TYPE_RECOMMENDED_SETTINGS_ANDROID
};

XrResult result = xrGetRecommendedSettingsANDROID(instance, systemId, &output);

if (result == XR_SUCCESS) {
  // We now know the current state of the default environment as recommended settings

  bool correctBlendMode = false;
  for(XrEnvironmentBlendMode blendMode : supportedBlendModes) {
    if (blendMode == output.blendMode) {
      correctBlendMode = true;
      break;
    }
  }
  assert(correctBlendMode);
  assert((~props.supportedInputModalities & output.activeInputModalities) == 0);
}

Neue Befehle

Neue Gebäude

Neue Enums

Neue Bitmasken

Neue Enum-Konstanten

  • XR_ANDROID_RECOMMENDED_SETTINGS_EXTENSION_NAME
  • XR_ANDROID_recommended_settings_SPEC_VERSION

  • Erweiterung von XrStructureType :

    • XR_TYPE_RECOMMENDED_SETTINGS_ANDROID
    • XR_TYPE_SYSTEM_INPUT_MODALITY_PROPERTIES_ANDROID

Probleme

Versionsverlauf

  • Version 3, 16.03.2026 (Salar Khan)

    • Öffentlich gemacht, Eingabemodalitäten zu Flag-Bits gemacht und den Namen der Erweiterung in XR_ANDROID_recommended_settings geändert.

  • Version 2, 28.03.2025 (Salar Khan)

    • Änderung zu ANDROIDX und Einbeziehung von passthroughOpacity.

  • Version 1, 18.02.2025 (Salar Khan)

    • Ursprüngliche Version