Android XR for OpenXR | Android Developers

Android Dev Summit이 Android XR 전용 트랙과 함께 돌아왔습니다. 직접 사용해 보고 의견을 보내주세요.

Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

XR_ANDROID_global_passthrough_dimming

이름 문자열

XR_ANDROID_global_passthrough_dimming

확장 프로그램 유형

인스턴스 확장 프로그램

등록된 내선 번호

797

버전

승인 상태

비준되지 않음

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

OpenXR 1.0

최종 수정일

2026-03-10

IP 상태

알려진 IP 소유권 주장이 없습니다.

도움을 주신 분들

Brian Chen, Google
Kyle Chen, Google
Nihav Jain, Google
Spencer Quin, Google

개요

광학 시스루 기기가 도입됨에 따라 애플리케이션이 패스스루의 어두운 정도를 조정하여 사용자에게 앱 컨텍스트와 가장 잘 어우러지는 환경을 제공할 수 있도록 허용하는 것뿐만 아니라 안전상의 이유로 시스템이 패스스루를 어둡게 하지 않도록 하는 것도 중요합니다.

이 확장 프로그램은 앱에서 현재 디밍 수준을 설정하고 가져오는 두 가지 함수와 디밍 수준이 변경될 때 브로드캐스트하는 이벤트를 제공합니다.

시스템 기능 검사

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

typedef struct XrSystemGlobalDimmingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsGlobalDimming;
} XrSystemGlobalDimmingPropertiesANDROID;

회원 설명

type는 이 구조의 XrStructureType입니다.
next는 NULL 또는 구조 체인의 다음 구조에 대한 포인터입니다. 핵심 OpenXR 또는 이 확장 프로그램에는 이러한 구조가 정의되어 있지 않습니다. 핵심 OpenXR 또는 이 확장 프로그램에는 이러한 구조가 정의되어 있지 않습니다.
supportsGlobalDimming은 XrBool32이며 현재 시스템이 글로벌 디밍을 지원하는지 나타냅니다.

애플리케이션은 xrGetSystemProperties를 호출할 때 XrSystemGlobalDimmingPropertiesANDROID 구조를 XrSystemProperties에 연결하여 시스템이 전역 디밍을 지원하는지 검사할 수 있습니다.

런타임이 supportsGlobalDimming에 대해 XR_FALSE를 반환하는 경우 런타임은 xrGetGlobalDimmingLevelANDROID가 호출될 때 XR_ERROR_FEATURE_UNSUPPORTED를 반환해야 합니다(MUST).

올바른 사용 (암시적)

XrSystemGlobalDimmingPropertiesANDROID를 사용하기 전에 XR_ANDROID_global_passthrough_dimming 확장 프로그램을 사용 설정해야 합니다.
type은(는) XR_TYPE_SYSTEM_GLOBAL_DIMMING_PROPERTIES_ANDROID여야 합니다.
next는 NULL 또는 구조 체인의 다음 구조에 대한 유효한 포인터여야 합니다.

지원되는 전역 디밍 수준 열거

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

XrResult xrEnumerateSupportedGlobalDimmingLevelsANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    supportedGlobalDimmingLevelCapacityInput,
    uint32_t*                                   supportedGlobalDimmingLevelCountOutput,
    float*                                      supportedGlobalDimmingLevels);

회원 설명

instance는 systemId가 검색된 인스턴스입니다.
systemId은 지원되는 수준이 열거되는 XrSystemId입니다.
supportedGlobalDimmingLevelCapacityInput는 supportedGlobalDimmingLevels 배열의 용량입니다. 필요한 용량을 가져오라는 요청을 나타내려면 0으로 설정합니다.
supportedGlobalDimmingLevelCountOutput는 작성된 supportedGlobalDimmingLevels의 개수에 대한 포인터이거나 supportedGlobalDimmingLevelCapacityInput가 부족한 경우 필요한 용량에 대한 포인터입니다.
supportedGlobalDimmingLevels은 지원되는 수준의 배열에 대한 포인터이지만 supportedGlobalDimmingLevelCapacityInput가 0인 경우 NULL일 수 있습니다.

반환된 supportedGlobalDimmingLevelCountOutput이 0이면 0.0~1.0 사이의 모든 전역 디밍 수준이 지원됩니다.

xrEnumerateSupportedGlobalDimmingLevelsANDROID는 XrSystemId에서 지원하는 전역 디밍 수준을 열거합니다. 지원되는 수준은 XrInstance의 전체 기간 동안 변경되면 안 됩니다. 반환된 수준 목록은 오름차순으로 정렬되어야 합니다.

런타임은 지정된 systemId 및 instance의 전체 기간에 대해 이 열거에서 항상 동일한 버퍼 콘텐츠를 반환해야 합니다(MUST).

올바른 사용 (암시적)

xrEnumerateSupportedGlobalDimmingLevelsANDROID를 호출하기 전에 XR_ANDROID_global_passthrough_dimming 확장 프로그램을 사용 설정해야 합니다(must).
instance는 유효한 XrInstance 핸들이어야 합니다.
supportedGlobalDimmingLevelCountOutput는 uint32_t 값에 대한 포인터여야 합니다.
supportedGlobalDimmingLevelCapacityInput가 0가 아닌 경우 supportedGlobalDimmingLevels는 supportedGlobalDimmingLevelCapacityInput float 값 배열의 포인터여야 합니다.

반품 코드

성공

XR_SUCCESS

실패

XR_ERROR_FUNCTION_UNSUPPORTED
XR_ERROR_HANDLE_INVALID
XR_ERROR_INSTANCE_LOST
XR_ERROR_RUNTIME_FAILURE
XR_ERROR_SIZE_INSUFFICIENT
XR_ERROR_SYSTEM_INVALID
XR_ERROR_VALIDATION_FAILURE

전체 디밍 수준 구성

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

typedef struct XrGlobalDimmingFrameEndInfoANDROID {
    XrStructureType    type;
    const void*        next;
    float              globalDimmingLevel;
} XrGlobalDimmingFrameEndInfoANDROID;

파라미터 설명

type는 이 구조의 XrStructureType입니다.
next는 NULL 또는 구조 체인의 다음 구조에 대한 포인터입니다. 핵심 OpenXR 또는 이 확장 프로그램에는 이러한 구조가 정의되어 있지 않습니다.
globalDimmingLevel은 0.0 (투명)과 1.0 (불투명) 사이의 값입니다. 런타임은 이 값을 지원되는 가장 가까운 전역 디밍 수준에 매핑할 수 있습니다(may). 애플리케이션은 이 값을 -1.0으로 설정하여 현재 디밍 수준이 선호됨을 나타낼 수 있습니다.

globalDimmingLevel 값은 차단되는 빛의 비율을 지정합니다. 여기서 0.0 값은 0% 빛 차단에 해당하고 1.0은 100% 빛 차단에 해당합니다. 차단된 빛의 비율은 일반적으로 다음과 같이 표현할 수 있습니다.

100% - Light Transmittance%

ISO 8980-3:2022에 따른 광 투과율 비율은 가시광선 파장 (380nm~780nm)에서 입사 복사속에 대한 투과 복사속의 비율로 측정할 수 있습니다.

XrGlobalDimmingFrameEndInfoANDROID는 애플리케이션이 XrFrameEndInfo에서 체이닝하여 선호하는 전역 디밍 수준을 요청할 수 있는 구조입니다.

런타임은 요청된 디밍 수준이 현재 디밍 수준과 다른 경우 요청된 디밍 수준을 적용해야 합니다(MUST).

런타임은 전역 디밍 수준을 제어하며 안전상의 이유로 선호하는 전역 디밍 수준을 무시할 수 있습니다(may).

올바른 사용 (암시적)

XrGlobalDimmingFrameEndInfoANDROID를 사용하기 전에 XR_ANDROID_global_passthrough_dimming 확장 프로그램을 사용 설정해야 합니다.
type은(는) XR_TYPE_GLOBAL_DIMMING_FRAME_END_INFO_ANDROID여야 합니다.
next는 NULL 또는 구조 체인의 다음 구조에 대한 유효한 포인터여야 합니다.

xrGetGlobalDimmingLevelANDROID 함수는 다음과 같이 정의됩니다.

XrResult xrGetGlobalDimmingLevelANDROID(
    XrSession                                   session,
    float*                                      dimmingLevel);

파라미터 설명

session는 유효한 XrSession 핸들입니다.
dimmingLevel는 현재 어둡게 하기 수준을 가리키는 포인터입니다.

반환된 dimmingLevel는 0.0과 1.0 사이여야 합니다. 0.0은 완전히 투명함을 의미하고 1.0은 완전히 어두워짐을 의미합니다.

어둡게 하기 수준이 설정되지 않은 경우 런타임은 패스 스루가 사용 설정되면 어둡게 하기 수준을 0.0으로, 패스 스루가 사용 중지되면 1.0으로 설정해야 합니다(MUST).

올바른 사용 (암시적)

xrGetGlobalDimmingLevelANDROID를 호출하기 전에 XR_ANDROID_global_passthrough_dimming 확장 프로그램을 사용 설정해야 합니다.
session는 유효한 XrSession 핸들이어야 합니다.
dimmingLevel는 float 값에 대한 포인터여야 합니다.

반품 코드

성공

XR_SUCCESS
XR_SESSION_LOSS_PENDING

실패

XR_ERROR_FUNCTION_UNSUPPORTED
XR_ERROR_HANDLE_INVALID
XR_ERROR_INSTANCE_LOST
XR_ERROR_RUNTIME_FAILURE
XR_ERROR_SESSION_LOST
XR_ERROR_VALIDATION_FAILURE

조도 수준 변경 이벤트

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

typedef struct XrEventDataGlobalDimmingLevelChangedANDROID {
    XrStructureType    type;
    const void*        next;
    XrSession          session;
} XrEventDataGlobalDimmingLevelChangedANDROID;

회원 설명

type는 이 구조의 XrStructureType입니다.
next는 NULL 또는 구조 체인의 다음 구조에 대한 포인터입니다. 핵심 OpenXR 또는 이 확장 프로그램에는 이러한 구조가 정의되어 있지 않습니다.
session는 유효한 XrSession 핸들입니다.

애플리케이션은 xrPollEvent를 사용하여 이 이벤트를 가져올 수 있습니다. 이 이벤트는 앱 또는 기기의 물리적 버튼에 의해 디밍 수준이 변경될 때 전송됩니다.

포커스가 맞춰진 앱이 다른 앱으로 전환될 때는 이 이벤트가 전송되지 않습니다.

애플리케이션은 xrGetGlobalDimmingLevelANDROID를 호출하여 새 디밍 수준을 가져오고 이에 따라 XrGlobalDimmingFrameEndInfoANDROID :: globalDimmingLevel를 업데이트함으로써 이벤트에 응답해야 합니다(should). 이벤트에 응답하면 애플리케이션이 선호하는 디밍 수준을 변경할 때 런타임에 신호가 전송됩니다.

올바른 사용 (암시적)

XR_ANDROID_global_passthrough_dimming 확장 프로그램은 XrEventDataGlobalDimmingLevelChangedANDROID를 사용하기 전에 사용 설정해야 합니다.
type은(는) XR_TYPE_EVENT_DATA_GLOBAL_DIMMING_LEVEL_CHANGED_ANDROID여야 합니다.
next는 NULL 또는 구조 체인의 다음 구조에 대한 유효한 포인터여야 합니다.

예시 코드

시스템 기능 확인 및 지원되는 전역 디밍 수준 열거

다음 예시 코드는 글로벌 디밍이 지원되는지 확인하는 방법을 보여줍니다.

XrInstance instance; // previously initialized
XrSystemId systemId; // previously initialized

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrEnumerateSupportedGlobalDimmingLevelsANDROID xrEnumerateSupportedGlobalDimmingLevelsANDROID;

XrSystemGlobalDimmingPropertiesANDROID dimmingControlSystemProperties { XR_TYPE_SYSTEM_GLOBAL_DIMMING_PROPERTIES_ANDROID };

XrSystemProperties systemProperties; // Chain dimmingControlSystemProperties

// ...
// Run xrGetSystemProperties()
// ...

if (!dimmingControlSystemProperties.supportsGlobalDimming) {
  // The system does not support global dimming
  return;
}

// Enumerate supported levels
uint32_t count = 0;
CHK_XR(xrEnumerateSupportedGlobalDimmingLevelsANDROID(instance, systemId, count, &count, nullptr));

std::vector<float> supportedLevels(count);
CHK_XR(xrEnumerateSupportedGlobalDimmingLevelsANDROID(instance, systemId, count, &count, supportedLevels.data()));

디밍 수준 변경 이벤트 폴링

다음 코드 예는 디밍 수준 변경 이벤트를 폴링하는 방법을 보여줍니다.

XrEventDataBuffer event{ XR_TYPE_EVENT_DATA_BUFFER };

// ...
// Run xrPollEvent()
// ...

switch (event.type) {
  // This event will not be sent when focused app switches
  case XR_TYPE_EVENT_DATA_GLOBAL_DIMMING_LEVEL_CHANGED_ANDROID:
  {
    const XrEventDataGlobalDimmingLevelChangedANDROID &dimmingLevelChangedEvent =
            *reinterpret_cast<XrEventDataGlobalDimmingLevelChangedANDROID *>(&event);

    // Query new dimming level using xrGetGlobalDimmingLevelANDROID()
  }
}

새 명령어

xrEnumerateSupportedGlobalDimmingLevelsANDROID
xrGetGlobalDimmingLevelANDROID

새로운 구조

XrEventDataGlobalDimmingLevelChangedANDROID
XrFrameEndInfo 확장:
- XrGlobalDimmingFrameEndInfoANDROID
XrSystemProperties 확장:
- XrSystemGlobalDimmingPropertiesANDROID

새 enum 상수

XR_ANDROID_GLOBAL_PASSTHROUGH_DIMMING_EXTENSION_NAME
XR_ANDROID_global_passthrough_dimming_SPEC_VERSION
XrStructureType 확장:
- XR_TYPE_EVENT_DATA_GLOBAL_DIMMING_LEVEL_CHANGED_ANDROID
- XR_TYPE_GLOBAL_DIMMING_FRAME_END_INFO_ANDROID
- XR_TYPE_SYSTEM_GLOBAL_DIMMING_PROPERTIES_ANDROID

문제

버전 기록

버전 1, 2025-10-07 (브라이언 첸)
- 초기 확장 프로그램 설명입니다.