Name String

XR_ANDROID_recommended_settings

Type d'extension

Extension d'instance

Numéro d'extension enregistré

455

Révision

1

État de la ratification

Non ratifié

Dépendances d'extension et de version

OpenXR 1.0

Date de dernière modification

2026-03-16

Participants

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

Présentation

L'environnement par défaut de l'utilisateur peut se trouver dans différents états en utilisant une combinaison d'un mode de fusion et d'une modalité de saisie. Cette extension fournit les paramètres recommandés pour l'utilisateur, qui correspondent à l'état de l'environnement par défaut de l'utilisateur avant le lancement de l'application, afin d'assurer une transition fluide.

Structures et énumérations

Les bits XrInputModalityFlagsANDROID identifient les différentes modalités d'entrée qui peuvent être utilisées.

typedef XrFlags64 XrInputModalityFlagsANDROID;

Les bits valides pour XrInputModalityFlagsANDROID sont définis par XrInputModalityFlagBitsANDROID , qui est spécifié comme suit :

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

Descriptions des flags

  • XR_INPUT_MODALITY_HEAD_BIT_ANDROID : indique une modalité d'entrée qui utilise le suivi de la tête.
  • XR_INPUT_MODALITY_CONTROLLER_BIT_ANDROID : indique une modalité d'entrée qui utilise des entrées de manette XR.
  • XR_INPUT_MODALITY_HANDS_BIT_ANDROID : indique une modalité de saisie qui utilise le suivi des mains.
  • XR_INPUT_MODALITY_MOUSE_BIT_ANDROID : indique une modalité d'entrée qui utilise la saisie à la souris.
  • XR_INPUT_MODALITY_GAZE_AND_GESTURE_BIT_ANDROID : indique une modalité de saisie qui combine le suivi oculaire et le suivi des mains.

La structure XrRecommendedSettingsANDROID est définie comme suit :

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

Descriptions des membres

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures. Aucune structure de ce type n'est définie dans OpenXR de base ou dans cette extension.
  • blendMode est un XrEnvironmentBlendMode indiquant le mode de fusion de l'environnement par défaut juste avant le lancement de l'application.
  • passthroughOpacity est un float indiquant l'opacité de la vue réelle de l'environnement par défaut juste avant le lancement de l'application. L'environnement d'exécution doit définir cette valeur sur (1.0 - dimming_value) pour les appareils OST.
  • activeInputModalities est un masque de bits de XrInputModalityFlagsANDROID indiquant les modalités d'entrée utilisées dans l'environnement par défaut juste avant le lancement de l'application.

Utilisation valide (implicite)

Énumérer les états d'environnement compatibles

Une application peut déterminer les états de mode de fusion et de modalité d'entrée compatibles avec le système à l'aide de xrEnumerateEnvironmentBlendModes et en étendant XrSystemProperties avec la structure XrSystemInputModalityPropertiesANDROID lors de l'appel de xrGetSystemProperties .

La structure XrSystemInputModalityPropertiesANDROID est définie comme suit :

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

Descriptions des membres

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures. Aucune structure de ce type n'est définie dans OpenXR de base ou dans cette extension.
  • supportedInputModalities correspond à un ou plusieurs XrInputModalityFlagsANDROID indiquant les modalités d'entrée compatibles avec le système.

Utilisation valide (implicite)

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

Description des paramètres

Utilisation valide (implicite)

Codes renvoyés

Opération réussie

  • XR_SUCCESS

Échec

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SYSTEM_INVALID

L'exemple de code suivant montre comment obtenir les modalités d'entrée compatibles, obtenir les paramètres recommandés et vérifier que les paramètres signalés sont compatibles avec le système.

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

Nouvelles commandes

Nouvelles structures

Nouvelles énumérations

Nouveaux masques de bits

Nouvelles constantes d'énumération

  • XR_ANDROID_RECOMMENDED_SETTINGS_EXTENSION_NAME
  • XR_ANDROID_recommended_settings_SPEC_VERSION
  • Extension de XrStructureType :

    • XR_TYPE_RECOMMENDED_SETTINGS_ANDROID
    • XR_TYPE_SYSTEM_INPUT_MODALITY_PROPERTIES_ANDROID

Problèmes

L'historique des versions

  • Révision 3, 16/03/2026 (Salar Khan)

    • Passage à l'état public, transformation des modalités d'entrée en bits d'indicateur et modification du nom de l'extension en XR_ANDROID_recommended_settings .
  • Révision 2, 28/03/2025 (Salar Khan)

    • Remplacement par ANDROIDX et ajout de passthroughOpacity.
  • Révision 1, 18/02/2025 (Salar Khan)

    • Version initiale.