Name String

XR_ANDROID_recommended_settings

Tipo de extensión

Extensión de instancia

Número de extensión registrado

455

Revisión

1

Estado de ratificación

No ratificado

Dependencias de extensiones y versiones

OpenXR 1.0

Fecha de la última modificación

2026-03-16

Colaboradores

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

Descripción general

El entorno predeterminado del usuario puede estar en varios estados con una combinación de un modo de fusión y una modalidad de entrada. Esta extensión proporciona la configuración recomendada para el usuario, que corresponde al estado del entorno predeterminado del usuario antes del inicio de la aplicación, para garantizar una transición fluida.

Structs y enums

Los bits XrInputModalityFlagsANDROID identifican diferentes modalidades de entrada que pueden estar en uso.

typedef XrFlags64 XrInputModalityFlagsANDROID;

Los bits válidos para XrInputModalityFlagsANDROID se definen con XrInputModalityFlagBitsANDROID , que se especifica de la siguiente manera:

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

Descripciones de las marcas

  • XR_INPUT_MODALITY_HEAD_BIT_ANDROID: Indica una modalidad de entrada que usa el monitoreo de cabeza.
  • XR_INPUT_MODALITY_CONTROLLER_BIT_ANDROID: Indica una modalidad de entrada que usa cualquier entrada de control de RE.
  • XR_INPUT_MODALITY_HANDS_BIT_ANDROID: Indica una modalidad de entrada que usa el monitoreo de manos.
  • XR_INPUT_MODALITY_MOUSE_BIT_ANDROID: Indica una modalidad de entrada que usa entradas del mouse.
  • XR_INPUT_MODALITY_GAZE_AND_GESTURE_BIT_ANDROID: Indica una modalidad de entrada que combina el seguimiento de ojos y el monitoreo de manos.

La estructura XrRecommendedSettingsANDROID se define de la siguiente manera:

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

Descripciones de los miembros

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.
  • blendMode es un XrEnvironmentBlendMode que indica el modo de fusión del entorno predeterminado justo antes del inicio de la aplicación.
  • passthroughOpacity es un float que indica la opacidad de la transferencia del entorno predeterminado justo antes del inicio de la aplicación. El entorno de ejecución debe establecer este valor en (1.0 - dimming_value) para los dispositivos OST.
  • activeInputModalities es una máscara de bits de XrInputModalityFlagsANDROID que indica las modalidades de entrada que se usan en el entorno predeterminado justo antes del inicio de la aplicación.

Uso válido (implícito)

Enumera los estados de entorno admitidos

Una aplicación puede determinar qué estados de modo de fusión y modalidad de entrada admite el sistema con xrEnumerateEnvironmentBlendModes y extender XrSystemProperties con la estructura XrSystemInputModalityPropertiesANDROID cuando se llama a xrGetSystemProperties .

La estructura XrSystemInputModalityPropertiesANDROID se define de la siguiente manera:

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

Descripciones de los miembros

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.
  • supportedInputModalities es uno o más XrInputModalityFlagsANDROID que indican las modalidades de entrada que admite el sistema.

Uso válido (implícito)

Obtén la configuración recomendada (estado del entorno predeterminado antes del lanzamiento)

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

Descripciones de los parámetros

Uso válido (implícito)

Códigos de retorno

Listo

  • XR_SUCCESS

Falla

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SYSTEM_INVALID

Código de ejemplo para la configuración recomendada

En el siguiente código de ejemplo, se muestra cómo obtener las modalidades de entrada admitidas, obtener la configuración recomendada y verificar que el sistema admita la configuración informada.

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

Comandos nuevos

Estructuras nuevas

Enums nuevas

Máscaras de bits nuevas

Nuevas constantes de enum

  • XR_ANDROID_RECOMMENDED_SETTINGS_EXTENSION_NAME
  • XR_ANDROID_recommended_settings_SPEC_VERSION

  • Extiende XrStructureType :

    • XR_TYPE_RECOMMENDED_SETTINGS_ANDROID
    • XR_TYPE_SYSTEM_INPUT_MODALITY_PROPERTIES_ANDROID

Problemas

Historial de versiones

  • Revisión 3, 16 de marzo de 2026 (Salar Khan)

    • Se ascendió a público, se crearon bits de marca de modalidades de entrada y se cambió el nombre de la extensión a XR_ANDROID_recommended_settings .

  • Revisión 2, 28 de marzo de 2025 (Salar Khan)

    • Se cambió a ANDROIDX y se incluyó passthroughOpacity.

  • Revisión 1, 18 de febrero de 2025 (Salar Khan)

    • Versión inicial.