WebXR 光照估计 API 第 1 级

本文档的状态

本节描述本文档在发布时的状态。当前 W3C 出版物以及此技术报告最新修订版的列表，可在 W3C 标准和草案索引中找到。

沉浸式 Web 工作组维护着该小组尚未处理的所有错误报告列表。此草案突出显示了一些仍有待在工作组中讨论的待处理问题。对这些问题的结果尚未作出决定，包括它们是否有效。强烈鼓励针对未解决问题提交带有拟议规范文本的 pull request。

本文档由沉浸式 Web 工作组使用推荐标准轨道作为工作草案发布。本文档旨在成为 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 生成光照估计时所相对的位置和方向。

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 的原生原点到主光源的方向。该值必须是单位长度的 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”由本模块作为新的有效特性描述符引入。希望使用光照估计特性的应用，必须使用“light-estimation”特性描述符来请求。

3.2. XRSession

XRSession 接口被扩展为能够创建新的 XRLightProbe 实例。XRLightProbe 实例具有一个会话对象，即创建此 XRLightProbe 的 XRSession。还具有一个反射格式对象，即该光照探针可以取得的 XRReflectionFormat。

XRSession 接口进一步扩展了一个属性 preferredReflectionFormat，指示底层 XR 设备最接近支持的 XRReflectionFormat

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

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

当在 XRSession session 上调用 requestLightProbe(options) 方法时，用户代理必须运行以下步骤：

令 promise 为一个新的 Promise。
如果 light-estimation 特性描述符未被包含在 session 的已启用特性列表中，则用 NotSupportedError 拒绝 promise，并中止这些步骤。
如果 session 的 ended 值为 true，则抛出 InvalidStateError 并中止这些步骤。
如果 options 的 reflectionFormat 是 "srgba8" 或与 session 的 preferredReflectionFormat 匹配：
1. 令 probe 为一个新的 XRLightProbe。
2. 将 probe 的会话设为 session。
3. 将 probe 的反射格式设为 options 的 reflectionFormat
4. 用 probe 解决 promise。
否则
1. 用“NotSupportedError” DOMException 拒绝 promise

3.3. XRFrame

XRFrame 接口被扩展为能够为给定的 XRLightProbe 查询 XRLightEstimate。

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

当在 XRFrame frame 上调用 getLightEstimate(lightProbe) 方法时，用户代理必须运行以下步骤：

如果 frame 的 active 布尔值为 `false`，则抛出 InvalidStateError 并中止这些步骤。
令 session 为 frame 的 session 对象。
如果 lightProbe 的会话不等于 session，则抛出 InvalidStateError 并中止这些步骤。
令 device 为 session 的 XR 设备。
如果 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);
};

当在 XRWebGLBinding binding 上调用 getReflectionCubeMap(lightProbe) 方法时，用户代理必须运行以下步骤：

如果 binding 的上下文已丢失，则抛出 InvalidStateError 并中止这些步骤。
令 session 为 binding 的会话。
如果 session 的 ended 值为 true，则抛出 InvalidStateError 并中止这些步骤。
如果 session 与 lightProbe 的会话不匹配，则抛出 InvalidStateError 并中止这些步骤。
令 device 为 session 的 XR 设备。
如果没有可从 device 获得的反射立方体贴图，则返回 null。
返回一个新的 WebGLTexture 立方体贴图，其格式由 lightProbe 的反射格式指定，并填充来自 device 的数据。

5. 事件

除非另有规定，本规范中所有排队任务的任务源是 XR 任务源。

5.1. 事件类型

每当通过调用 getReflectionCubeMap() 返回的立方体贴图内容发生变化时，用户代理必须在 XRLightProbe 对象上触发一个事件，其名称为 reflectionchange。

6. 隐私与安全考量

光照估计 API 与 Ambient Light Sensor API [AMBIENT-LIGHT] 共享许多潜在的隐私和安全风险，包括：

画像：光照估计可能泄露有关用户使用模式和周围环境的信息。此信息可用于增强用户画像和行为分析。
跨设备关联：两个设备可以访问包含相同第三方脚本的网站，该脚本会随时间关联光照水平。
跨设备通信：一种简单的广播通信方法可以使用设备屏幕或相机 LED 闪光来广播消息，并由附近设备上的光照估计读取出来。

除此之外，还需要考虑一些光照估计特有的向量。

WebXR API 返回的光照估计明确描述了用户近距离范围内的真实世界环境。
足够高分辨率的反射立方体贴图接近与相机访问相同的级别。

创建 XR Session 时，必须将光照估计声明为一个特性描述符，这将允许用户代理通知用户允许网站使用光照估计 API 的潜在隐私影响。鼓励用户代理不要为光照估计 API 的任何部分提供实时更新，尤其是反射立方体贴图。默认情况下，WebXR API 应仅返回低空间频率和低时间频率信息。除非用户还同意了特定源的相机权限，否则反射立方体贴图应保持低分辨率。作为进一步缓解措施，球谐系数和主光方向可以被量化。

变更

自 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" 与规范性文本区分开来，如下所示：

注，这是一个资料性注释。