String de nome

XR_ANDROID_recommended_settings

Tipo de extensão

Extensão de instância

Número de ramal registrado

455

Revisão

1

Status de ratificação

Não ratificado

Dependências de extensão e versão

OpenXR 1.0

Data da última modificação

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

Visão geral

O ambiente padrão do usuário pode estar em vários estados usando uma combinação de um modo de mesclagem e uma modalidade de entrada. Essa extensão fornece as configurações recomendadas para o usuário, que correspondem ao estado do ambiente padrão do usuário antes do lançamento do aplicativo, para garantir uma transição tranquila.

Structs e enums

Os bits XrInputModalityFlagsANDROID identificam diferentes modalidades de entrada que podem estar em uso.

typedef XrFlags64 XrInputModalityFlagsANDROID;

Os bits válidos para XrInputModalityFlagsANDROID são definidos por XrInputModalityFlagBitsANDROID , que é especificado como:

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

Descrições de flags

  • XR_INPUT_MODALITY_HEAD_BIT_ANDROID: indica uma modalidade de entrada que usa o rastreamento da cabeça.
  • XR_INPUT_MODALITY_CONTROLLER_BIT_ANDROID: indica uma modalidade de entrada que está usando qualquer entrada do controlador XR.
  • XR_INPUT_MODALITY_HANDS_BIT_ANDROID: indica uma modalidade de entrada que usa a captura de movimentos das mãos.
  • XR_INPUT_MODALITY_MOUSE_BIT_ANDROID: indica uma modalidade de entrada que está usando entradas do mouse.
  • XR_INPUT_MODALITY_GAZE_AND_GESTURE_BIT_ANDROID: indica uma modalidade de entrada que combina o acompanhamento ocular e a captura de movimentos das mãos.

A estrutura XrRecommendedSettingsANDROID é definida como:

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

Descrições dos membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma estrutura desse tipo é definida no OpenXR principal ou nesta extensão.
  • blendMode é um XrEnvironmentBlendMode que indica o modo de mesclagem do ambiente padrão antes do lançamento do aplicativo.
  • passthroughOpacity é um float que indica a opacidade de passagem do ambiente padrão logo antes do lançamento do aplicativo. O ambiente de execução precisa definir esse valor como (1.0 - dimming_value) para dispositivos OST.
  • activeInputModalities é uma máscara de bits de XrInputModalityFlagsANDROID que indica as modalidades de entrada em uso no ambiente padrão logo antes do lançamento do aplicativo.

Uso válido (implícito)

Como enumerar estados de ambiente compatíveis

Um aplicativo pode determinar quais estados de modo de combinação e modalidade de entrada são compatíveis com o sistema usando xrEnumerateEnvironmentBlendModes e estendendo as XrSystemProperties com a estrutura XrSystemInputModalityPropertiesANDROID ao chamar xrGetSystemProperties .

A estrutura XrSystemInputModalityPropertiesANDROID é definida como:

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

Descrições dos membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma estrutura desse tipo é definida no OpenXR principal ou nesta extensão.
  • supportedInputModalities é um ou mais XrInputModalityFlagsANDROID que indicam as modalidades de entrada compatíveis com o sistema.

Uso válido (implícito)

Receber as configurações recomendadas (estado padrão do ambiente antes do lançamento)

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

Descrições dos parâmetros

Uso válido (implícito)

Códigos de retorno

Sucesso

  • XR_SUCCESS

Falha

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SYSTEM_INVALID

Exemplo de código para as configurações recomendadas

O exemplo de código a seguir demonstra como receber as modalidades de entrada compatíveis, receber as configurações recomendadas e confirmar se as configurações informadas são compatíveis com o 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);
}

Novos comandos

Novas estruturas

Novos tipos enumerados

Novas máscaras de bits

Novas constantes de tipo enumerado

  • XR_ANDROID_RECOMMENDED_SETTINGS_EXTENSION_NAME
  • XR_ANDROID_recommended_settings_SPEC_VERSION

  • Estendendo XrStructureType :

    • XR_TYPE_RECOMMENDED_SETTINGS_ANDROID
    • XR_TYPE_SYSTEM_INPUT_MODALITY_PROPERTIES_ANDROID

Problemas

Histórico de versões

  • Revisão 3, 16/03/2026 (Salar Khan)

    • Promovido para público, transformou as modalidades de entrada em bits de flag e mudou o nome da extensão para XR_ANDROID_recommended_settings .

  • Revisão 2, 28/03/2025 (Salar Khan)

    • Mudança para ANDROIDX e inclusão de passthroughOpacity.

  • Revisão 1, 18/02/2025 (Salar Khan)

    • Versão inicial.