Name String

XR_ANDROID_recommended_settings

Typ rozszerzenia

Rozszerzenie instancji

Zarejestrowany numer wewnętrzny

455

Wersja

1

Stan ratyfikacji

Nie ratyfikowano

Zależności rozszerzeń i wersji

OpenXR 1.0

Data ostatniej modyfikacji

2026-03-16

Twórcy

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

Przegląd

Domyślne środowisko użytkownika może być w różnych stanach, które są kombinacją trybu mieszania i modalności wejściowej. To rozszerzenie udostępnia użytkownikowi zalecane ustawienia, które odpowiadają stanowi domyślnego środowiska użytkownika przed uruchomieniem aplikacji, aby zapewnić płynne przejście.

Struktury i wyliczenia

Bity XrInputModalityFlagsANDROID identyfikują różne modalności danych wejściowych, które mogą być używane.

typedef XrFlags64 XrInputModalityFlagsANDROID;

Prawidłowe bity dla XrInputModalityFlagsANDROID są definiowane przez XrInputModalityFlagBitsANDROID , które są określone jako:

// 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;

Opisy flag

  • XR_INPUT_MODALITY_HEAD_BIT_ANDROID – wskazuje tryb wprowadzania, który korzysta ze śledzenia ruchów głowy.
  • XR_INPUT_MODALITY_CONTROLLER_BIT_ANDROID – wskazuje modalność wejściową, która używa dowolnych danych wejściowych kontrolera XR.
  • XR_INPUT_MODALITY_HANDS_BIT_ANDROID – wskazuje tryb wprowadzania danych, który korzysta ze śledzenia rąk.
  • XR_INPUT_MODALITY_MOUSE_BIT_ANDROID – wskazuje, że używana jest modalność wprowadzania sygnału myszy.
  • XR_INPUT_MODALITY_GAZE_AND_GESTURE_BIT_ANDROID – wskazuje metodę wprowadzania danych, która łączy śledzenie wzroku i śledzenie rąk.

Struktura XrRecommendedSettingsANDROID jest zdefiniowana w ten sposób:

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

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.
  • blendMode to XrEnvironmentBlendMode wskazujący domyślny tryb mieszania środowiska tuż przed uruchomieniem aplikacji.
  • passthroughOpacity to float, który wskazuje domyślną przezroczystość środowiska tuż przed uruchomieniem aplikacji. W przypadku urządzeń OST środowisko wykonawcze musi ustawić tę wartość na (1.0 – dimming_value).
  • activeInputModalities to maska bitowa XrInputModalityFlagsANDROID wskazująca metody wprowadzania danych używane w środowisku domyślnym tuż przed uruchomieniem aplikacji.

Prawidłowe użycie (pośrednie)

Wyliczanie obsługiwanych stanów środowiska

Aplikacja może określić, które tryby mieszania i stany modalności wejściowej są obsługiwane przez system, za pomocą xrEnumerateEnvironmentBlendModes i rozszerzenia XrSystemProperties o strukturę XrSystemInputModalityPropertiesANDROID podczas wywoływania xrGetSystemProperties .

Struktura XrSystemInputModalityPropertiesANDROID jest zdefiniowana w ten sposób:

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

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.
  • supportedInputModalities to co najmniej 1 flaga XrInputModalityFlagsANDROID wskazująca tryby wprowadzania obsługiwane przez system.

Prawidłowe użycie (pośrednie)

Zalecane ustawienia (domyślny stan środowiska przed wprowadzeniem na rynek)

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

Opisy parametrów

Prawidłowe użycie (pośrednie)

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_SYSTEM_INVALID

Przykładowy kod zalecanych ustawień

Poniższy przykładowy kod pokazuje, jak uzyskać obsługiwane metody wprowadzania danych, zalecane ustawienia i potwierdzić, że zgłoszone ustawienia są obsługiwane przez system.

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

Nowe polecenia

Nowe domy

Nowe wartości w polu enum

Nowe maski bitowe

Nowe stałe typu wyliczeniowego

  • XR_ANDROID_RECOMMENDED_SETTINGS_EXTENSION_NAME
  • XR_ANDROID_recommended_settings_SPEC_VERSION

  • Rozszerzanie XrStructureType :

    • XR_TYPE_RECOMMENDED_SETTINGS_ANDROID
    • XR_TYPE_SYSTEM_INPUT_MODALITY_PROPERTIES_ANDROID

Problemy

Historia zmian

  • Wersja 3, 16.03.2026 (Salar Khan)

    • Przeniesiono do publicznych, utworzono bity flagi modalności wejściowych i zmieniono nazwę rozszerzenia na XR_ANDROID_recommended_settings .

  • Wersja 2, 28 marca 2025 r. (Salar Khan)

    • Zmieniono na ANDROIDX i dodano passthroughOpacity.

  • Wersja 1, 18 lutego 2025 r. (Salar Khan)

    • Wersja początkowa.