XR_ANDROID_recommended_settings
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
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
typeest le XrStructureType de cette structure.nextestNULLou 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.blendModeest un XrEnvironmentBlendMode indiquant le mode de fusion de l'environnement par défaut juste avant le lancement de l'application.passthroughOpacityest unfloatindiquant 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.activeInputModalitiesest 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)
- L'extension
XR_ANDROID_recommended_settingsdoit être activée avant d'utiliser XrRecommendedSettingsANDROID. -
typedoit êtreXR_TYPE_RECOMMENDED_SETTINGS_ANDROID -
nextdoit êtreNULLou un pointeur valide vers la structure suivante dans une chaîne de structures -
blendModedoit être une valeur XrEnvironmentBlendMode valide -
activeInputModalitiesdoit être une combinaison valide de valeurs XrInputModalityFlagBitsANDROID -
activeInputModalitiesne doit pas être0
É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
typeest le XrStructureType de cette structure.nextestNULLou 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.supportedInputModalitiescorrespond à un ou plusieurs XrInputModalityFlagsANDROID indiquant les modalités d'entrée compatibles avec le système.
Utilisation valide (implicite)
- L'extension
XR_ANDROID_recommended_settingsdoit être activée avant d'utiliser XrSystemInputModalityPropertiesANDROID. -
typedoit êtreXR_TYPE_SYSTEM_INPUT_MODALITY_PROPERTIES_ANDROID -
nextdoit êtreNULLou un pointeur valide vers la structure suivante dans une chaîne de structures
Obtenir les paramètres recommandés (état de l'environnement par défaut avant le lancement)
XrResult xrGetRecommendedSettingsANDROID(
XrInstance instance,
XrSystemId systemId,
XrRecommendedSettingsANDROID* output);
Description des paramètres
instanceest un handle XrInstance précédemment créé avec xrCreateInstance .systemIdest unXrSystemIdprécédemment récupéré à partir de xrGetSystem .outputest un pointeur vers une structure XrRecommendedSettingsANDROID qui est générée avec l'état de l'environnement par défaut.
Utilisation valide (implicite)
- L'extension
XR_ANDROID_recommended_settingsdoit être activée avant d'appeler xrGetRecommendedSettingsANDROID. -
instancedoit être un handle XrInstance valide -
outputdoit être un pointeur vers une structure XrRecommendedSettingsANDROID.
Codes renvoyés
XR_SUCCESS
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_RUNTIME_FAILUREXR_ERROR_SYSTEM_INVALID
Exemple de code pour les paramètres recommandés
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
- XrRecommendedSettingsANDROID
Extension de XrSystemProperties :
Nouvelles énumérations
Nouveaux masques de bits
Nouvelles constantes d'énumération
XR_ANDROID_RECOMMENDED_SETTINGS_EXTENSION_NAMEXR_ANDROID_recommended_settings_SPEC_VERSIONExtension de XrStructureType :
XR_TYPE_RECOMMENDED_SETTINGS_ANDROIDXR_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.
- Passage à l'état public, transformation des modalités d'entrée en bits d'indicateur et modification du nom de l'extension en
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.