Name String

XR_ANDROID_recommended_settings

Tipo di estensione

Estensione dell'istanza

Numero di interno registrato

455

Revisione

1

Stato della ratifica

Non ratificato

Dipendenze di estensioni e versioni

OpenXR 1.0

Data ultima modifica

2026-03-16

Collaboratori

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

Panoramica

L'ambiente predefinito dell'utente può trovarsi in vari stati utilizzando una combinazione di modalità di fusione e modalità di input. Questa estensione fornisce le impostazioni consigliate per l'utente, che corrispondono allo stato dell'ambiente predefinito dell'utente prima del lancio dell'applicazione, per garantire una transizione senza problemi.

Struct ed enum

I bit XrInputModalityFlagsANDROID identificano diverse modalità di input che potrebbero essere in uso.

typedef XrFlags64 XrInputModalityFlagsANDROID;

I bit validi per XrInputModalityFlagsANDROID sono definiti da XrInputModalityFlagBitsANDROID , che viene specificato come:

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

Descrizioni dei flag

  • XR_INPUT_MODALITY_HEAD_BIT_ANDROID: indica una modalità di input che utilizza il tracciamento della testa.
  • XR_INPUT_MODALITY_CONTROLLER_BIT_ANDROID: indica una modalità di input che utilizza qualsiasi input del controller XR.
  • XR_INPUT_MODALITY_HANDS_BIT_ANDROID: indica una modalità di input che utilizza il tracciamento delle mani.
  • XR_INPUT_MODALITY_MOUSE_BIT_ANDROID: indica una modalità di input che utilizza gli input del mouse.
  • XR_INPUT_MODALITY_GAZE_AND_GESTURE_BIT_ANDROID: indica una modalità di input che combina il tracciamento oculare e il tracciamento delle mani.

La struttura XrRecommendedSettingsANDROID è definita come:

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

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.
  • blendMode è un XrEnvironmentBlendMode che indica la modalità di fusione dell'ambiente predefinito appena prima del lancio dell'applicazione.
  • passthroughOpacity è un float che indica l'opacità passthrough dell'ambiente predefinito appena prima del lancio dell'applicazione. Il runtime deve impostare questo valore su (1.0 - dimming_value) per i dispositivi OST.
  • activeInputModalities è una maschera di bit di XrInputModalityFlagsANDROID che indica le modalità di input in uso nell'ambiente predefinito appena prima del lancio dell'applicazione.

Utilizzo valido (implicito)

Enumerazione degli stati dell'ambiente supportati

Un'applicazione può determinare quali stati della modalità di fusione e della modalità di input sono supportati dal sistema con xrEnumerateEnvironmentBlendModes ed estendendo XrSystemProperties con la struttura XrSystemInputModalityPropertiesANDROID quando chiama xrGetSystemProperties .

La struttura XrSystemInputModalityPropertiesANDROID è definita come:

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

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.
  • supportedInputModalities è uno o più XrInputModalityFlagsANDROID che indicano le modalità di input supportate dal sistema.

Utilizzo valido (implicito)

Ottieni le impostazioni consigliate (stato dell'ambiente predefinito prima del lancio)

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

Descrizioni dei parametri

Utilizzo valido (implicito)

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_SYSTEM_INVALID

Codice di esempio per le impostazioni consigliate

Il seguente codice di esempio mostra come ottenere le modalità di input supportate, ottenere le impostazioni consigliate e verificare che le impostazioni segnalate siano supportate dal sistema.

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

Nuovi comandi

Nuove strutture

Nuovi enum

Nuove maschere di bit

Nuove costanti enum

  • XR_ANDROID_RECOMMENDED_SETTINGS_EXTENSION_NAME
  • XR_ANDROID_recommended_settings_SPEC_VERSION

  • Estensione di XrStructureType :

    • XR_TYPE_RECOMMENDED_SETTINGS_ANDROID
    • XR_TYPE_SYSTEM_INPUT_MODALITY_PROPERTIES_ANDROID

Problemi

Cronologia delle versioni

  • Revisione 3, 16/03/2026 (Salar Khan)

    • Promossa a pubblica, ha reso i bit dei flag delle modalità di input e ha cambiato il nome dell'estensione in XR_ANDROID_recommended_settings .

  • Revisione 2, 28 marzo 2025 (Salar Khan)

    • Passaggio ad ANDROIDX e inclusione di passthroughOpacity.

  • Revisione 1, 18 febbraio 2025 (Salar Khan)

    • Versione iniziale.