WebXR DOM 오버레이 모듈

1. 소개

1.1. 개요

2. HTML API 통합

이 모듈은 GlobalEventHandlers 정의에 새 이벤트 유형을 추가합니다.

2.1. onbeforexrselect

입력 소스의 targetRaySpace의 -Z 축이 입력 장치의 primary action이 트리거된 시점에 DOM 오버레이 요소와 교차하는 경우, WebXR selectstart 입력 이벤트를 생성하기 전에 beforexrselect 유형의 XRSessionEvent가 DOM 오버레이 요소에 발송됩니다.

partial interface mixin GlobalEventHandlers {
  attribute EventHandler onbeforexrselect;
};

이 이벤트는 beforexrselect 유형을 가진 XRSessionEvent이며, 버블링하고, 취소 가능하며, 합성됩니다. 이 이벤트의 target 요소는 targetRaySpace와 교차하는 최상위 이벤트 대상이며, DOM 오버레이 요소의 자손이거나 DOM 오버레이 요소 자체입니다.

preventDefault()를 호출하여 이 이벤트를 취소하면, 이 primary action에 대해 입력 소스가 일반적으로 생성하는 기본 WebXR 입력 이벤트가 억제됩니다. 이 상호작용 시퀀스에 대해서는 selectstart, selectend, 및 select 이벤트가 발생하지 않습니다.

Note: 향후 WebXR 모듈은 이 이벤트를 취소하면 영향을 받는 추가 이벤트나 WebXR 입력 의존 데이터를 정의할 수 있습니다. 예를 들어 일시적 입력 소스의 히트 테스트 구독 결과를 억제하는 경우입니다.

이 이벤트와 이벤트 핸들러가 수행하는 동작은 DOM 이벤트 처리에 영향을 주지 않으며, DOM 이벤트 발송과 동기화되지 않습니다. 사용자의 동작은 `"pointerdown"`과 같은 적절한 DOM 이벤트를 별도로 생성하며, 이러한 DOM 이벤트는 대응하는 beforexrselect 이벤트보다 먼저 또는 나중에 발생할 수 있습니다. 이는 beforexrselect 이벤트가 취소되었는지 여부와 관계없이 발생하며, XR 입력 이벤트 핸들러에서 수행되는 추가 동작과도 독립적입니다.

Note: 이 이벤트는 사용자가 DOM UI와 상호작용하는 동안 애플리케이션이 중복 XR 입력 이벤트를 억제하는 방법을 제공합니다. 이 이벤트는 버블링 이벤트이므로, 애플리케이션은 적절한 컨테이너 요소에 핸들러를 등록하여 DOM 오버레이의 영역을 XR 입력을 차단하는 영역으로 효과적으로 표시할 수 있습니다. 이는 DOM 요소의 시각적 불투명도와 독립적입니다. XR 입력 이벤트를 차단하지 않는 텍스트 설명과 같은 비상호작용 불투명 또는 반투명 DOM 콘텐츠를 표시할 수 있습니다.

document.getElementById('button-container').addEventListener(
  'beforexrselect', ev => ev.preventDefault());

2.2. CSS 의사 클래스

:xr-overlay 의사 클래스는 DOM 오버레이를 사용하는 몰입형 세션이 지속되는 동안 오버레이 요소와 일치해야 합니다.

오버레이 요소는 backdrop root입니다.

NOTE: DOM 오버레이 요소 또는 그 자손에 대한 backdrop 필터 효과는 AR 카메라 이미지(해당하는 경우)나 몰입형 세션의 XRWebGLLayer에 그려진 렌더링 콘텐츠를 수정하지 않습니다.

오버레이 요소의 조상에 대한 스태킹 컨텍스트가 있더라도, 이는 몰입형 세션의 디스플레이에 페인트되지 않습니다.

NOTE: 오버레이 요소 자체는 `position: fixed` 스타일링으로 인해 스태킹 컨텍스트입니다.

NOTE: 다중 디스플레이 시스템에서 UA는 오버레이 요소의 조상 또는 형제 트리에 대한 스태킹 컨텍스트를 데스크톱 모니터와 같은 별도 디스플레이에 페인트하고 그릴 수 있습니다.

2.3. 사용자 에이전트 수준 스타일 시트 기본값

오버레이 요소에 대한 사용자 에이전트 스타일 시트 기본값은 다음과 같습니다.

:xr-overlay {
    /* 투명한 배경을 강제함 */
    background: rgba(0,0,0,0) !important;

    /* 자손의 컨테이닝 블록처럼 동작함 */
    contain: paint !important;

    /* 다음 스타일링은 :fullscreen과 동일함 */
    position: fixed !important;
    top: 0 !important;
    right: 0 !important;
    bottom: 0 !important;
    left: 0 !important;
    margin: 0 !important;
    box-sizing: border-box !important;
    min-width: 0 !important;
    max-width: none !important;
    min-height: 0 !important;
    max-height: none !important;
    width: 100% !important;
    height: 100% !important;
    transform: none !important;

    /* 의도적으로 !important가 아님 */
    object-fit: contain;
}

NOTE: 이는 Fullscreen API § 5.2 사용자 에이전트 수준 스타일 시트 기본값을 기반으로 하며, 오버레이 요소의 배경을 투명하게 만들기 위한 추가 스타일링을 포함합니다. :xr-overlay에 대한 스타일링은 Fullscreen API의 의사 클래스나 스타일링에 명시적으로 의존하지 않으므로, 사용자 에이전트가 Fullscreen API와 독립적으로 이를 구현할 유연성을 가집니다.

NOTE: Fullscreen API는 현재 `contain: paint` 규칙을 명시하지 않지만, 이는 일반적인 UA 동작과 일치하며 해당 명세의 향후 개정판에 추가될 예정입니다.

NOTE: 애플리케이션은 세션 중 인터페이스 요소의 가시성 제어를 포함하여 UI 요소를 조건부로 스타일링하기 위해 :xr-overlay 의사 클래스를 사용하는 것이 권장됩니다.

2.4. Fullscreen API 통합

UA는 DOM 오버레이를 [FULLSCREEN] API의 특수한 경우로 구현할 수 있습니다. 이 경우 UA는 몰입형 세션이 지속되는 동안 활성 전체화면 요소에 대한 변경을 방지하고, requestFullscreen 요청을 거부해야 합니다.

NOTE: DOM Overlay API는 세션 시작 시 오버레이 요소를 지정할 것을 요구하며, 세션 중 활성 오버레이 요소를 변경하는 메커니즘을 제공하지 않습니다. 애플리케이션이 Fullscreen API를 사용하여 활성 오버레이 요소를 간접적으로 변경할 수 있다면 플랫폼 간 동작이 일관되지 않을 수 있습니다.

DOM 오버레이가 Fullscreen API를 통해 구현되는 경우, root 요소 스태킹 컨텍스트는 몰입형 디스플레이에 페인트되지 않습니다. 최상위 레이어에 있는 요소들의 스태킹 컨텍스트만이, 오버레이 요소를 포함하여, 몰입형 디스플레이에 페인트됩니다.

NOTE: 기본적으로 전체화면 모드는 불투명한 검은색 backdrop을 사용합니다. 수정된 페인트 규칙은 이 backdrop을 그릴 필요가 없고, 오버레이 요소의 조상이나 형제 트리가 투명한 오버레이 요소를 통해 보이지 않도록 보장합니다.

NOTE: Fullscreen API 기반 구현을 허용하는 것은 주로 몰입형 세션 중 페이지의 나머지 부분이 보이지 않는 단일 디스플레이 시스템을 위한 것입니다. 다중 디스플레이 시스템은 나머지 페이지를 데스크톱 모니터와 같은 별도 디스플레이에 표시하면서도 기술적으로 오버레이 요소에 Fullscreen API를 사용할 수 있으며, 이 경우 UA는 오버레이 요소의 조상 또는 형제 트리에 대한 스태킹 컨텍스트를 별도 디스플레이에 페인트하고 그릴 수 있습니다.

또는 UA는 [FULLSCREEN] API와 독립적으로 DOM 오버레이를 구현할 수 있습니다. 이 경우 오버레이 요소는 여전히 :xr-overlay 의사 클래스와 일치해야 하며, 이 의사 클래스에 대해 § 2.3 사용자 에이전트 수준 스타일 시트 기본값을 사용하여 몰입형 뷰에서 스타일링되어야 합니다. UA는 오버레이 요소 밖의 요소에 대해 fullscreen API 사용을 별도로 지원할 수 있지만, 이는 DOM 오버레이 콘텐츠가 표시되는 방식에 어떠한 영향도 주어서는 안 됩니다.

NOTE: DOM 오버레이와 Fullscreen API를 독립적으로 처리하는 것은 VR 헤드셋이 연결된 데스크톱 PC와 같은 다중 디스플레이 시스템을 지원하기 위한 것입니다. 이 경우 Fullscreen API는 예를 들어 3인칭 렌더링 뷰가 있는 전체화면 canvas 요소를 표시하는 등 2D 모니터의 페이지 콘텐츠를 제어하는 데 사용할 수 있으며, DOM 오버레이 요소와 몰입형 콘텐츠는 헤드셋에 별도로 표시될 수 있습니다.

몰입형 세션이 원래 표시된 웹 페이지와 별도의 출력 장치를 사용하는 다중 디스플레이 시스템에서, 오버레이 요소는 몰입형 뷰에 표시되는 동안 다른 디스플레이에서 2D 웹 페이지의 일부로 보이거나 상호작용 가능해서는 안 됩니다. UA는 세션이 지속되는 동안 다른 디스플레이에서 전체 페이지를 숨기거나 비활성화하도록 선택할 수 있습니다.

NOTE: DOM 오버레이 콘텐츠를 비상호작용 헤드셋 미러 뷰 또는 유사한 비웹페이지 UI의 일부로 표시하는 것은 괜찮습니다. 이 다중 디스플레이 제한의 의도는 오버레이 요소가 동시에 두 곳에 표시될 경우 발생할 수 있는 일관되지 않은 표시와 잠재적으로 혼란스러운 상호작용을 피하는 것입니다. 이는 DOM 요소를 두 개의 별도 디스플레이에 동시에 표시하는 것과 관련된 구현상의 어려움도 피합니다.

3. WebXR Device API 통합

이 모듈은 XRSessionInit 및 XRSession의 정의를 확장하고, XRInputSource 이벤트의 동작을 수정합니다.

3.1. XRSessionInit

이 모듈은 immersive sessions에 대한 requiredFeatures 또는 optionalFeatures 시퀀스에서 사용하기 위한 새 유효한 feature descriptor로 문자열 dom-overlay를 도입합니다.

장치는 몰입형 세션이 지속되는 동안 사용자가 DOM 콘텐츠를 보고 상호작용할 수 있는 방법을 제공하는 경우 DOM 오버레이 기능을 capable of supporting합니다.

NOTE: 구현 선택지에는 휴대용 AR 장치의 전체화면 오버레이나, VR 또는 AR 헤드셋을 위한 공간상의 떠 있는 직사각형이 포함됩니다.

DOM 콘텐츠는 최상위 콘텐츠 레이어인 것처럼 합성되어야 합니다. XRWebGLLayer의 콘텐츠나 AR 장치의 패스스루 카메라 이미지에 의해 가려져서는 안 됩니다. 애플리케이션은 일반 CSS 규칙을 사용하여 DOM 오버레이 자체 내에서 콘텐츠의 투명도와 2D 배치를 제어할 수 있습니다.

DOM 오버레이는 세션 시작부터 사용자가 자동으로 볼 수 있어야 하며, 이를 보이게 하기 위해 사용자가 버튼을 누르거나 기타 수동 동작을 수행할 필요가 없어야 합니다.

NOTE: 콘텐츠 요소가 간접적으로만 보이는 경우, 예를 들어 사용자가 세션 중 일반적으로 보이지 않는 별도의 2D 모니터에서 콘텐츠를 보려면 헤드셋을 벗거나 패스스루 카메라를 수동으로 활성화해야 하는 경우, 장치는 DOM 오버레이를 지원한다고 주장해서는 안 됩니다. 그러나 사용자가 DOM 오버레이 콘텐츠를 표시하는 물리적 터치스크린 장치를 들고 있는 몰입형 CAVE 시스템은 유효한 구현입니다.

XRSessionInit 딕셔너리는 새 domOverlay 멤버를 추가하여 확장됩니다. 이는 XRSessionInit의 선택적 멤버이지만, 기본 오버레이 요소가 없으므로 DOM 오버레이 기능을 사용할 때는 반드시 지정해야 합니다.

partial dictionary XRSessionInit {
  XRDOMOverlayInit? domOverlay;
};

DOM 오버레이 기능이 필수 기능이지만 애플리케이션이 domOverlay 멤버를 제공하지 않은 경우, UA는 이를 해결되지 않은 필수 기능으로 취급하고 requestSession() promise를 NotSupportedError로 거부해야 합니다. 선택적 기능으로 요청된 경우, UA는 기능 요청을 무시하고 DOM 오버레이를 활성화하지 않아야 합니다.

NOTE: UA는 DOM 오버레이가 활성화되지 않은 이유를 설명하는 개발자 콘솔 메시지와 같은 로컬 경고를 내보낼 수 있습니다.

3.2. XRSession

이 모듈은 DOM 오버레이 기능의 현재 상태를 반영하는 새 readonly 속성을 추가하도록 XRSession 인터페이스를 확장합니다.

partial interface XRSession {
  readonly attribute XRDOMOverlayState? domOverlayState;
};

domOverlayState 속성은 dom-overlay 기능이 지원되지 않거나 활성화되지 않은 경우 null이어야 합니다.

기능이 활성화된 경우, 속성 값이 존재해야 합니다.

NOTE: 애플리케이션은 domOverlayState의 존재 여부를 확인하여, 예를 들어 선택적 기능으로 요청된 경우 DOM 오버레이 기능이 활성화되어 작동하는지 검증할 수 있습니다.

NOTE: DOM 오버레이는 사용자가 일시적으로 보지 못할 수 있습니다. 예를 들어 사용자 에이전트가 고정된 방향이나 위치에 배치하여 사용자 움직임 후에 사용자의 시야 밖에 놓이게 되는 경우입니다. 이 일이 발생하는 동안에도 domOverlayState 속성은 계속 설정된 상태로 남아 있습니다.

세션이 보이는 DOM 오버레이와 함께 활성 상태인 동안, UA는 이를 렌더링 기회로 취급하고, DOM 콘텐츠 애니메이션에 적합한 속도로 Window requestAnimationFrame() 콜백을 실행해야 합니다. 이는 requestAnimationFrame() 콜백이 XRWebGLLayer 콘텐츠를 그리는 데 사용되는 시점 및 빈도와 다를 수 있습니다.

3.3. XRInputSource

XRInputSource가 그 primary action에 해당하는 플랫폼별 동작을 시작할 때, UA는 입력 처리를 시작하기 전에 이것이 primary action으로 취급되는지 결정하기 위해 다음 단계를 실행해야 합니다.

NOTE: 실제로 beforexrselect 이벤트를 취소하면 XR 입력 select 이벤트가 억제되며, 이 동작에 대해서는 selectstart, selectend, 또는 select가 생성되지 않습니다. 일시적 입력 소스의 경우, inputsourceschange 이벤트는 여전히 생성되지만, beforexrselect 이벤트를 취소하면 해당 동작은 보조 손가락 입력과 유사하게 auxiliary action으로 취급됩니다.

4. 초기화

애플리케이션은 domOverlay 딕셔너리를 통해 DOM 오버레이에 대한 구성을 제공해야 합니다.

dictionary XRDOMOverlayInit {
  required Element root;
};

root 속성은 DOM 오버레이의 콘텐츠로 사용자에게 표시될 오버레이 요소를 지정합니다. 이는 필수 속성이며, 기본값은 없습니다.

let uiElement = document.getElementById('ui');
navigator.xr.requestSession('immersive-ar', {
    optionalFeatures: ['dom-overlay'],
    domOverlay: { root: uiElement } }).then((session) => {
    // 지원되는 경우 session.domOverlayState.type이 이제 설정됩니다.
    // 또는 기능이 지원되지 않으면 null입니다.
  }
}

활성 상태인 동안, DOM 오버레이 요소는 UA가 제공하는 DOM 오버레이 직사각형의 치수를 채우도록 자동으로 크기가 조정됩니다. 그 배경색은 세션이 지속되는 동안 자동으로 투명하게 스타일링됩니다.

NOTE: UA는 DOM 오버레이 요소를 스타일링하기 위해 Fullscreen API § 5.2 사용자 에이전트 수준 스타일 시트 기본값을 사용할 수 있으며, 배경을 투명하게 설정하기 위해 background-color: rgba(0,0,0,0) !important;를 포함하는 추가 규칙을 사용할 수 있습니다.

세션이 활성 상태가 되면, domOverlayState 속성이 DOM 오버레이에 대한 정보를 제공합니다.

enum XRDOMOverlayType {
  "screen",
  "floating",
  "head-locked"
};

dictionary XRDOMOverlayState {
  XRDOMOverlayType type; 
};

사용자 에이전트는 DOM 오버레이가 어떻게 표시되는지를 나타내도록 type을 설정해야 합니다. 이 값은 세션이 지속되는 동안 변경되지 않아야 합니다.

• screen 오버레이 유형은 DOM 오버레이 요소가 휴대용 AR과 같은 화면 기반 장치의 전체 물리적 화면을 덮는다는 것을 나타냅니다. 그 시각적 범위는 XRWebGLLayer 렌더링에 사용되는 XRViewport(들)의 시각적 범위와 일치해야 합니다. 단안 디스플레이의 경우 이는 단일 viewport입니다. 입체 디스플레이 화면은 두 개의 viewport를 제공하며, 이 경우 DOM 오버레이는 물리적 화면 위치와 일치하는 Z 위치에서 렌더링되어 양쪽 눈 뷰에 동일하게 나타나야 합니다.

• floating 오버레이 유형은 DOM 오버레이가 공간상의 떠 있는 직사각형으로 나타난다는 것을 나타냅니다. 이 직사각형의 월드 공간에서의 초기 위치는 UA에 달려 있으며, UA는 이를 계속 보이게 하기 위해 세션 중 이동시키거나, 사용자가 시작하는 수동 배치를 지원할 수 있습니다.

• head-locked 오버레이 유형은 DOM 오버레이가 사용자의 머리 움직임을 일관되게 따라가며, 헬멧형 헤드업 디스플레이와 유사하게 나타난다는 것을 나타냅니다.

NOTE: 사용자의 관점에서 "floating" 오버레이는 실제 세계 위치에 고정된 것처럼 렌더링될 때 정지해 있는 것으로 인식되며, 이 방식은 VR에서 상호작용 가능한 표시 표면에 흔히 선택됩니다. "head-locked" 오버레이는 머리 회전과 함께 움직이며 고정된 실제 세계 위치를 갖지 않습니다.

NOTE: 이 명세의 향후 버전은 floating 오버레이의 월드 공간 내 현재 위치와 같은 추가 속성을 오버레이 상태에 추가할 수 있습니다.

5. 교차 출처 콘텐츠에 대한 이벤트 처리

사용자 에이전트는 DOM 오버레이 요소 안에 중첩된 HTMLIFrameElement와 같은 교차 출처 콘텐츠와의 사용자 상호작용에 대해 자세나 게임패드 입력 상태를 제공해서는 안 됩니다.

사용자 에이전트는 예를 들어 해당 콘텐츠가 일반적으로 수신할 DOM 이벤트를 차단하거나, 교차 출처 콘텐츠를 전혀 로드 및 표시하지 않음으로써, 교차 출처 콘텐츠와의 사용자 상호작용을 방지하여 이 요구 사항을 충족할 수 있습니다.

사용자 에이전트가 DOM 오버레이의 교차 출처 콘텐츠와의 상호작용을 지원하고, 입력 소스의 targetRaySpace가 최상위 이벤트 대상으로서 교차 출처 콘텐츠와 교차하는 경우, UA는 WebXR Device API § 13.4.3 제한 데이터 조정을 활성화하고, 해당 입력 소스와 관련된 XRSpace에 대해 populate the pose를 수행할 때 limit 불리언을 true로 취급해야 합니다. 또한 UA는 자세가 제한되는 동안 이 입력 소스에 대한 게임패드 데이터를 업데이트해서는 안 됩니다.

NOTE: 애플리케이션은 이런 방식으로 자세가 제한되는 동안 컨트롤러나 그 타기팅 광선의 자세 업데이트를 수신하지 않습니다. UA는 상호작용을 가능하게 하기 위해 필요에 따라 포인터 광선이나 기타 적절한 시각화를 그릴 책임이 있습니다.

NOTE: 게임패드 데이터 업데이트 제한은 교차 출처 콘텐츠와의 상호작용에서 애플리케이션으로 정보가 누출되는 것을 피하기 위한 것입니다. 예를 들어 입력 소스의 primary action이 특정 트리거 임계값에서 발생하는 아날로그 트리거를 사용하는 경우, 애플리케이션은 대응하는 이벤트가 차단되더라도 트리거 값으로부터 사용자가 primary action을 시작하고 끝낸 시점을 추론할 수 있습니다. 또 다른 예로 DOM 콘텐츠에서 텍스트 입력을 위해 트랙패드나 조이스틱을 사용하는 장치가 있으며, 축 값을 읽으면 애플리케이션이 입력 중인 텍스트를 추론할 수 있습니다.

primary action이 교차 출처 콘텐츠 안에서 끝나는 경우, UA는 primary action을 취소된 것으로 취급해야 하며, select 이벤트를 보내서는 안 됩니다. UA는 자세를 제한된 것으로 취급하여 교차 출처 콘텐츠에 진입하기 전의 마지막 사용 가능한 자세를 사용해 selectend 이벤트를 보내야 합니다.

입력이 transient input source이고 transient action이 교차 출처 콘텐츠 안에서 시작되는 경우, 사용자 에이전트는 입력 위치가 교차 출처 콘텐츠 밖으로 이동할 때까지 adding the input source를 지연해야 합니다. transient action이 여전히 교차 출처 콘텐츠 안에 있는 동안 끝나는 경우, 일시적 입력 소스는 전혀 추가되지 않습니다.

NOTE: screen 모드 입력을 사용하는 휴대용 AR 장치에서는, 이는 교차 출처 콘텐츠 안에 머무르는 터치가 입력 소스나 관련 XR 입력 이벤트를 생성하지 않음을 의미합니다. 드래그 움직임이 교차 출처 콘텐츠 안에서 시작되면, 터치 위치가 교차 출처 콘텐츠를 벗어나는 위치에서 입력 소스가 생성되고, 평소처럼 취소 가능한 beforexrselect 이벤트를 내보냅니다.

6. 보안, 개인정보 보호 및 편안함 고려사항

6.1. 보호되는 기능

DOM 오버레이는 그 자체로 새로운 민감한 정보를 도입하지 않습니다. 그러나 기존 기술들을 결합하므로, 이 결합이 예상치 못한 상호작용으로 이어지지 않도록 보장하는 것이 중요합니다.

이 모듈의 주요 설계 목표는 DOM 오버레이가 가능한 경우 2D 콘텐츠에 대한 기존 의미론을 따르도록 하는 것이었습니다. 특히 교차 출처 임베디드 콘텐츠와 관련된 정보 흐름은 2D 페이지에서 iframe을 사용하는 경우와 유사해야 합니다. 예를 들어 2D 페이지는 교차 출처 콘텐츠를 iframe에 임베드한 다음, 이 iframe을 투명 요소로 덮을 수 있습니다. 이 경우 페이지는 마우스 이동 정보를 계속 수신하지만, 교차 출처 콘텐츠는 덮인 영역에서 어떤 입력 이벤트도 수신하지 않습니다. DOM 오버레이의 경우, XR 입력 이벤트 데이터는 마우스 이동 데이터와 유사하게 취급됩니다. 교차 출처 콘텐츠가 없거나 교차 출처 콘텐츠가 입력을 수신하지 않는 경우 자세는 외부 페이지에서 계속 사용할 수 있지만, 교차 출처 콘텐츠와 상호작용할 때는 제한(차단)됩니다.

교차 출처 콘텐츠는 클릭재킹 위협에 잠재적으로 취약합니다. UA는 DOM 오버레이에서 iframe이 사용될 때 Content Security Policy 3 § 6.1.5 frame-src와 같은 완화 조치를 계속 적용해야 합니다. UA는 특정 위협을 해결하기 위해 필요한 경우 DOM 오버레이의 교차 출처 콘텐츠에 대해 추가 제한을 구현할 수 있습니다.

변경 사항

2021년 8월 31일 최초 공개 작업 초안 이후 변경 사항

7. 감사의 말

다음 사람들은 WebXR DOM 오버레이 명세의 설계에 기여했습니다.

• Brandon Jones (Google)

• Nell Waliczek (Amazon [2018년까지 Microsoft])