WebXR 조명 추정 API 레벨 1

이 문서의 상태

이 절은 이 문서가 공개된 시점의 상태를 설명한다. 현재 W3C 공개 문서 목록과 이 기술 보고서의 최신 개정판은 W3C 표준 및 초안 색인에서 확인할 수 있다.

Immersive Web Working Group은 그룹이 아직 처리하지 않은 모든 버그 보고서 목록을 관리한다. 이 초안은 워킹 그룹에서 아직 논의해야 하는 일부 보류 중인 이슈를 강조한다. 이러한 이슈가 유효한지를 포함해 그 결과에 대해서는 어떤 결정도 내려지지 않았다. 미해결 이슈에 대한 제안 사양 텍스트가 포함된 풀 리퀘스트를 강력히 권장한다.

이 문서는 Immersive Web Working Group이 권고안 트랙을 사용하여 작업 초안으로 공개했다. 이 문서는 W3C 권고안이 되는 것을 목표로 한다.

작업 초안으로 공개되었다고 해서 W3C와 그 회원이 이를 승인한다는 의미는 아니다. 이는 초안 문서이며 언제든지 다른 문서로 갱신, 대체 또는 폐기될 수 있다. 이 문서를 진행 중인 작업 이외의 것으로 인용하는 것은 부적절하다.

이 문서는 W3C 특허 정책에 따라 운영되는 그룹에서 작성했다. W3C는 해당 그룹의 산출물과 관련하여 이루어진 특허 공개의 공개 목록을 관리하며, 이 페이지에는 특허 공개를 위한 지침도 포함되어 있다. 자신이 실제로 알고 있는 특허가 필수 청구항을 포함한다고 믿는 개인은 W3C 특허 정책 제6절에 따라 그 정보를 공개해야 한다.

이 문서는 2025년 8월 18일 W3C 프로세스 문서의 적용을 받는다.

1. 소개

WebXR 조명 추정 모듈은 WebXR Device API, WebXR 증강 현실 모듈, 그리고 WebXR Layers 모듈을 사용자의 환경에 대한 조명 조건의 추정치를 노출할 수 있는 기능으로 확장한다.

2. 조명 프리미티브

2.1. XRLightProbe

XRLightProbe는 사용자 환경의 주어진 지점에서 추정된 조명 정보를 수집한다.

[SecureContext, Exposed=Window]
interface XRLightProbe : EventTarget {
  readonly attribute XRSpace probeSpace;
  attribute EventHandler onreflectionchange;
};

probeSpace 속성은 XRSpace이며, XRLightProbe의 조명 추정이 생성되는 기준이 되는 위치와 방향을 추적하는 native origin을 가진다.

onreflectionchange 속성은 reflectionchange 이벤트 유형에 대한 이벤트 핸들러 IDL 속성이다.

2.2. XRReflectionFormat

enum XRReflectionFormat {
  "srgba8",
  "rgba16f",
};

반사 큐브 맵은 텍스처 데이터가 어떻게 표현되는지를 나타내는 내부 반사 형식을 가지며, 애플리케이션이 텍스처를 사용하는 방식을 변경할 수 있다. 큐브 맵은 "srgba8" 형식 또는 라이트 프로브의 preferredReflectionFormat으로 요청할 수 있다.

`XRReflectionFormat`	WebGL 형식	WebGL 내부 형식	WebGPU 형식	HDR
`"srgba8"`	RGBA	SRGB8_ALPHA8	"rgba8unorm-srgb"
`"rgba16f"`	RGBA	RGBA16F	"rgba16float"	✓

2.3. XRLightEstimate

XRLightEstimate는 XRFrame이 나타내는 시점의 XRLightProbe에 대한 추정 조명 값을 제공한다. XRLightEstimate는 XRLightProbe를 XRFrame의 getLightEstimate() 메서드에 전달하여 질의한다.

[SecureContext, Exposed=Window]
interface XRLightEstimate {
  readonly attribute Float32Array sphericalHarmonicsCoefficients;
  readonly attribute DOMPointReadOnly primaryLightDirection;
  readonly attribute DOMPointReadOnly primaryLightIntensity;
};

sphericalHarmonicsCoefficients 속성은 9개의 구면 조화 계수를 포함하는 Float32Array를 반환한다. 배열은 길이가 27개 요소여야 하며, 3개 요소마다 단일 계수의 빨강, 초록, 파랑 성분을 각각 정의한다. sphericalHarmonicsCoefficients의 첫 번째 항, 즉 배열의 처음 3개 요소는 유효한 조명 추정치를 나타내야 한다. 다른 모든 항은 선택 사항이며, 사용자 개인정보 설정 또는 플랫폼 기능으로 인해 해당 조명 추정치를 사용할 수 없는 경우 0일 수 있다.

sphericalHarmonicsCoefficients의 계수 순서는 [C₀⁰, C₁^-1, C₁⁰, C₁¹, C₂^-2, C₂^-1, C₂⁰, C₂¹, C₂²]이며, 여기서 C_l^m은 구면 조화 Y_l^m의 계수다.

primaryLightDirection은 XRLightEstimate를 생성한 XRLightProbe의 probeSpace의 native origin에서 주 광원으로 향하는 방향을 나타낸다. 값은 단위 길이 3D 벡터여야 하며, w 값은 0.0이어야 한다. 사용자 환경에서 추정값을 사용할 수 없는 경우 primaryLightDirection은 { x: 0.0, y: 1.0, z: 0.0, w: 0.0 }이어야 하며, 이는 위에서 곧장 아래로 비추는 빛을 나타낸다.

primaryLightIntensity는 주 광원의 색을 나타낸다. 값은 RGB 값을 각각 x, y, 그리고 z 값에 매핑한 것을 나타내야 하며, 각 성분은 0.0 이상이고 w 값은 1.0이어야 한다. 사용자 환경에서 추정값을 사용할 수 없는 경우 primaryLightIntensity는 {x: 0.0, y: 0.0, z: 0.0, w: 1.0}이어야 하며, 이는 조명이 없음을 나타낸다.

3. WebXR Device API 통합

WebXR Device API의 XRSession 및 XRFrame 인터페이스는 이 모듈에 의해 확장된다.

3.1. 세션 초기화

문자열 "light-estimation"은 이 모듈에서 새로운 유효한 feature descriptor로 도입된다. 조명 추정 기능을 사용하려는 애플리케이션은 "light-estimation" feature descriptor와 함께 요청되어야 한다.

3.2. XRSession

XRSession 인터페이스는 새로운 XRLightProbe 인스턴스를 생성할 수 있는 기능으로 확장된다. XRLightProbe 인스턴스에는 이 XRLightProbe를 생성한 XRSession인 session 객체가 있다. 그리고 라이트 프로브가 가져올 수 있는 XRReflectionFormat인 reflection format 객체가 있다.

XRSession 인터페이스는 preferredReflectionFormat 속성으로도 확장되며, 하위 XR device가 가장 가깝게 지원하는 XRReflectionFormat을 나타낸다.

dictionary XRLightProbeInit {
  XRReflectionFormat reflectionFormat = "srgba8";
};

partial interface XRSession {
  Promise<XRLightProbe> requestLightProbe(optional XRLightProbeInit options = {});
  readonly attribute XRReflectionFormat preferredReflectionFormat;
};

requestLightProbe(options) 메서드가 XRSession session에서 호출되면, 사용자 에이전트는 다음 단계를 실행해야 한다:

promise를 새로운 Promise로 둔다.
light-estimation 기능 기술자가 session의 list of enabled features에 포함되어 있지 않으면, promise를 NotSupportedError로 거부하고 이 단계를 중단한다.
session의 ended 값이 true이면, InvalidStateError를 던지고 이 단계를 중단한다.
options의 reflectionFormat이 "srgba8"이거나 session의 preferredReflectionFormat과 일치하면:
1. probe를 새로운 XRLightProbe로 둔다.
2. probe의 session을 session으로 설정한다.
3. probe의 reflection format을 options의 reflectionFormat으로 설정한다.
4. promise를 probe로 해결한다.
그 밖의 경우
1. promise를 "NotSupportedError" DOMException으로 거부한다.

3.3. XRFrame

XRFrame 인터페이스는 주어진 XRLightProbe에 대한 XRLightEstimate를 질의할 수 있는 기능으로 확장된다.

partial interface XRFrame {
  XRLightEstimate? getLightEstimate(XRLightProbe lightProbe);
};

getLightEstimate(lightProbe) 메서드가 XRFrame frame에서 호출되면, 사용자 에이전트는 다음 단계를 실행해야 한다:

frame의 active 불리언이 `false`이면, InvalidStateError를 던지고 이 단계를 중단한다.
session을 frame의 session 객체로 둔다.
lightProbe의 session이 session과 같지 않으면, InvalidStateError를 던지고 이 단계를 중단한다.
device를 session의 XR device로 둔다.
device가 이 프레임의 조명을 추정할 수 없으면 null을 반환한다.
estimate를 새로운 XRLightEstimate로 둔다.
device가 제공한 계수로 estimate의 sphericalHarmonicsCoefficients를 채운다.
device에 광원에 대한 추정 방향이 있으면
1. estimate의 primaryLightDirection을 광원의 추정 방향으로 설정한다.
그 밖의 경우
1. estimate의 primaryLightDirection을 { x: 0.0, y: 1.0, z: 0.0, w: 0.0 }으로 설정한다.
device에 광원에 대한 추정 강도가 있으면
1. estimate의 primaryLightIntensity를 광원의 추정 강도로 설정한다.
그 밖의 경우
1. estimate의 primaryLightIntensity를 {x: 0.0, y: 0.0, z: 0.0, w: 1.0}으로 설정한다.
estimate를 반환한다.

4. WebXR Layers 통합

WebXR Layers 모듈의 XRWebGLBinding 인터페이스는 이 모듈에 의해 확장된다.

4.1. XRWebGLBinding

XRWebGLBinding 인터페이스는 주어진 XRLightProbe에 대한 반사 큐브 맵을 질의할 수 있는 기능으로 확장된다.

partial interface XRWebGLBinding {
  WebGLTexture? getReflectionCubeMap(XRLightProbe lightProbe);
};

getReflectionCubeMap(lightProbe) 메서드가 XRWebGLBinding binding에서 호출되면, 사용자 에이전트는 다음 단계를 실행해야 한다:

binding의 context가 손실된 경우, InvalidStateError를 던지고 이 단계를 중단한다.
session을 binding의 session으로 둔다.
session의 ended 값이 true이면, InvalidStateError를 던지고 이 단계를 중단한다.
session이 lightProbe의 session과 일치하지 않으면, InvalidStateError를 던지고 이 단계를 중단한다.
device를 session의 XR Device로 둔다.
device에서 사용할 수 있는 반사 큐브 맵이 없으면 null을 반환한다.
lightProbe의 reflection format이 지정한 형식이고 device의 데이터로 채운 새로운 WebGLTexture cubemap을 반환한다.

5. 이벤트

달리 명시되지 않는 한, 이 사양에서 큐에 넣는 모든 태스크 소스는 XR 태스크 소스다.

5.1. 이벤트 유형

getReflectionCubeMap()를 호출하여 반환된 큐브 맵의 내용이 변경될 때마다, 사용자 에이전트는 XRLightProbe 객체에서 reflectionchange라는 이름의 이벤트를 발생시켜야 한다.

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

조명 추정 API는 다음을 포함하여 Ambient Light Sensor API [AMBIENT-LIGHT]와 많은 잠재적인 개인정보 보호 및 보안 위험을 공유한다:

프로파일링: Lighting Estimation은 사용자의 사용 패턴과 주변 환경에 대한 정보를 누출할 수 있다. 이 정보는 사용자 프로파일링과 행동 분석을 강화하는 데 사용될 수 있다.
기기 간 연결: 두 기기가 시간에 따른 조명 수준을 상호 연관시키는 동일한 서드 파티 스크립트가 포함된 웹 사이트에 접근할 수 있다.
기기 간 통신: 간단한 브로드캐스트 통신 방식은 기기 화면 또는 카메라 LED 플래시를 사용하여 근처 기기에서 조명 추정으로 읽을 수 있는 메시지를 브로드캐스트할 수 있다.

이 외에도, 조명 추정에 고유한 몇 가지 벡터를 고려해야 한다.

WebXR API가 반환하는 조명 추정은 사용자와 가까운 실제 환경을 명시적으로 설명한다.
충분히 높은 해상도의 반사 큐브 맵은 카메라 접근과 같은 수준에 가까워진다.

조명 추정은 XR Session을 생성할 때 feature descriptor로 선언되어야 하며, 이를 통해 사용자 에이전트는 웹사이트가 조명 추정 API를 사용하도록 허용하는 것의 잠재적인 개인정보 보호 영향을 사용자에게 알릴 수 있다. 사용자 에이전트는 조명 추정 API의 어떤 부분에도, 특히 반사 큐브 맵에는 실시간 업데이트를 제공하지 않는 것이 권장된다. 기본적으로 WebXR API는 낮은 공간 주파수와 낮은 시간 주파수 정보만 반환해야 한다. 반사 큐브 맵은 사용자가 특정 출처에 대해 카메라 권한에도 동의하지 않은 한 낮은 해상도로 유지해야 한다. 추가 완화책으로, Spherical Harmonics와 주 광원 방향은 양자화될 수 있다.

변경 사항

2021년 9월 9일 첫 공개 작업 초안 이후의 변경 사항

준수

문서 관례

준수 요구사항은 설명적 단언과 RFC 2119 용어의 조합으로 표현된다. 이 문서의 규범 부분에서 쓰이는 핵심어 “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, 그리고 “OPTIONAL”은 RFC 2119에 설명된 대로 해석해야 한다. 그러나 가독성을 위해, 이 사양에서는 이러한 단어들이 모두 대문자로 표시되지는 않는다.

명시적으로 비규범으로 표시된 절, 예제, 참고를 제외한 이 사양의 모든 텍스트는 규범적이다. [RFC2119]

이 사양의 예제는 “예를 들어”라는 말로 도입되거나 class="example"으로 규범 텍스트와 구분되어 표시된다. 다음과 같다:

이는 정보 제공용 예제의 예다.

정보 제공용 참고는 “참고”라는 말로 시작하며 class="note"로 규범 텍스트와 구분되어 표시된다. 다음과 같다:

참고, 이는 정보 제공용 참고다.