이름 문자열

XR_ANDROID_recommended_settings

확장 프로그램 유형

인스턴스 확장 프로그램

등록된 내선 번호

455

버전

1

승인 상태

비준되지 않음

확장 프로그램 및 버전 종속 항목

OpenXR 1.0

최종 수정일

2026-03-16

도움을 주신 분들

스펜서 퀸, Google
제러드 파인더, Google
케빈 몰, Google
니하브 자인, Google
레바나 첸, Google
앨빈 시, Google
살라 칸, Google

개요

사용자의 기본 환경은 블렌드 모드와 입력 모달리티의 조합을 사용하여 다양한 상태에 있을 수 있습니다. 이 확장 프로그램은 원활한 전환을 위해 애플리케이션 실행 전 사용자의 기본 환경 상태에 해당하는 권장 설정을 사용자에게 제공합니다.

구조체 및 enum

XrInputModalityFlagsANDROID 비트는 사용 중일 수 있는 다양한 입력 모달리티를 식별합니다.

typedef XrFlags64 XrInputModalityFlagsANDROID;

XrInputModalityFlagsANDROID의 유효한 비트는 XrInputModalityFlagBitsANDROID에 의해 정의되며 다음과 같이 지정됩니다.

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

플래그 설명

  • XR_INPUT_MODALITY_HEAD_BIT_ANDROID: 헤드 트래킹을 사용하는 입력 모달리티를 나타냅니다.
  • XR_INPUT_MODALITY_CONTROLLER_BIT_ANDROID: XR 컨트롤러 입력을 사용하는 입력 모달리티를 나타냅니다.
  • XR_INPUT_MODALITY_HANDS_BIT_ANDROID: 핸드 트래킹을 사용하는 입력 모달리티를 나타냅니다.
  • XR_INPUT_MODALITY_MOUSE_BIT_ANDROID: 마우스 입력을 사용하는 입력 형식을 나타냅니다.
  • XR_INPUT_MODALITY_GAZE_AND_GESTURE_BIT_ANDROID: 눈 추적과 핸드 트래킹을 결합한 입력 방식을 나타냅니다.

XrRecommendedSettingsANDROID 구조는 다음과 같이 정의됩니다.

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

회원 설명

  • type는 이 구조의 XrStructureType입니다.
  • next는 NULL 또는 구조 체인의 다음 구조에 대한 포인터입니다. 핵심 OpenXR 또는 이 확장 프로그램에는 이러한 구조가 정의되어 있지 않습니다.
  • blendMode는 애플리케이션 실행 직전의 기본 환경 블렌드 모드를 나타내는 XrEnvironmentBlendMode입니다.
  • passthroughOpacity는 애플리케이션 실행 직전의 기본 환경 패스 스루 불투명도를 나타내는 float입니다. 런타임은 OST 기기의 경우 이 값을 (1.0 - dimming_value)로 설정해야 합니다(must).
  • activeInputModalities은 애플리케이션 실행 직전에 기본 환경 내에서 사용 중인 입력 모달리티를 나타내는 XrInputModalityFlagsANDROID의 비트 마스크입니다.

올바른 사용 (암시적)

지원되는 환경 상태 열거

애플리케이션은 xrEnumerateEnvironmentBlendModes를 사용하고 xrGetSystemProperties를 호출할 때 XrSystemInputModalityPropertiesANDROID 구조로 XrSystemProperties를 확장하여 시스템에서 지원하는 블렌드 모드와 입력 방식 상태를 확인할 수 있습니다(can).

XrSystemInputModalityPropertiesANDROID 구조는 다음과 같이 정의됩니다.

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

회원 설명

  • type는 이 구조의 XrStructureType입니다.
  • next는 NULL 또는 구조 체인의 다음 구조에 대한 포인터입니다. 핵심 OpenXR 또는 이 확장 프로그램에는 이러한 구조가 정의되어 있지 않습니다.
  • supportedInputModalities은 시스템에서 지원하는 입력 형식을 나타내는 하나 이상의 XrInputModalityFlagsANDROID입니다.

올바른 사용 (암시적)

권장 설정 가져오기 (출시 전 기본 환경 상태)

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

파라미터 설명

올바른 사용 (암시적)

반품 코드

성공

  • XR_SUCCESS

실패

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SYSTEM_INVALID

권장 설정의 예시 코드

다음 예시 코드는 지원되는 입력 형식을 가져오고, 권장 설정을 가져오고, 보고된 설정이 시스템에서 지원되는지 확인하는 방법을 보여줍니다.

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

새 명령어

새로운 구조

새 enum

새 비트마스크

새 enum 상수

  • XR_ANDROID_RECOMMENDED_SETTINGS_EXTENSION_NAME
  • XR_ANDROID_recommended_settings_SPEC_VERSION

  • XrStructureType 확장:

    • XR_TYPE_RECOMMENDED_SETTINGS_ANDROID
    • XR_TYPE_SYSTEM_INPUT_MODALITY_PROPERTIES_ANDROID

문제

버전 기록

  • 버전 3, 2026-03-16 (살라르 칸)

    • 공개로 승격하고 입력 모달리티 플래그 비트를 만들고 확장 프로그램 이름을 XR_ANDROID_recommended_settings로 변경했습니다.

  • 버전 2, 2025년 3월 28일 (살라르 칸)

    • ANDROIDX로 변경하고 passthroughOpacity를 포함했습니다.

  • 버전 1, 2025-02-18 (살라르 칸)

    • 최초 버전