XR_ANDROID_light_estimation

名称字符串

XR_ANDROID_light_estimation

扩展程序类型

实例扩展程序

已注册的扩展程序编号

701

修订版本

1

批准状态

未批准

扩展程序和版本依赖项

OpenXR 1.0

上次修改日期

2025-03-13

IP 状态

没有已知的 IP 权利主张。

创作贡献者

Jared Finder，Google
Cairn Overturf，Google
Spencer Quin，Google
Levana Chen，Google
Nihav Jain，Google
Salar Khan，Google
Scott Chung，Google

概览

借助此扩展程序，应用可以请求表示头戴式设备周围真实环境照明情况的数据。应用可以 使用此信息在与虚拟对象所处真实场景相同的条件下照亮虚拟对象。

权限

Android 应用必须 在清单中列出 android.permission.SCENE_UNDERSTANDING_COARSE 权限，因为此扩展程序会公开环境的照明信息。android.permission.SCENE_UNDERSTANDING_COARSE 权限被视为危险权限。应用必须 在运行时请求该权限才能使用以下函数：

（保护级别：危险）

检查系统功能

XrSystemLightEstimationPropertiesANDROID 结构的定义如下：

typedef struct XrSystemLightEstimationPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsLightEstimation;
} XrSystemLightEstimationPropertiesANDROID;

成员说明

  • type 是此结构的 XrStructureType。
  • next 是 NULL 或指向结构链中下一个结构的指针。核心 OpenXR 或此扩展程序中未定义任何此类结构。
  • supportsLightEstimation 是一个 XrBool32，用于指示当前系统是否支持光照估计。

应用可以 通过在调用 xrGetSystemProperties 时使用 XrSystemLightEstimationPropertiesANDROID 结构扩展 XrSystemProperties，检查系统是否能够支持光照估计。

当且仅当运行时为 supportsLightEstimation 返回 XR_FALSE 时，运行时 必须 从 xrCreateLightEstimatorANDROID 返回 XR_ERROR_FEATURE_UNSUPPORTED。

有效用法（隐式）

创建光照估计器句柄

XR_DEFINE_HANDLE(XrLightEstimatorANDROID)

光照估计数据由运行时生成，并使用 XrLightEstimatorANDROID 句柄与应用共享。

此句柄可以 用于使用此扩展程序中的其他函数访问光照估计信息。

xrCreateLightEstimatorANDROID 函数的定义如下：

XrResult xrCreateLightEstimatorANDROID(
    XrSession                                   session,
    XrLightEstimatorCreateInfoANDROID*          createInfo,
    XrLightEstimatorANDROID*                    outHandle);

参数说明

应用使用 xrCreateLightEstimatorANDROID 函数来创建光照估计器。

  • 如果系统不支持光照估计，运行时必须 返回 XR_ERROR_FEATURE_UNSUPPORTED。
  • 如果发出调用的应用未被授予所需权限，运行时必须 返回 XR_ERROR_PERMISSION_INSUFFICIENT。

如果应用想要向运行时表明它已完成对光照估计数据的访问，它 必须 通过 xrDestroyLightEstimatorANDROID 销毁句柄。

有效用法（隐式）

返回代码

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失败

  • XR_ERROR_FEATURE_UNSUPPORTED
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_PERMISSION_INSUFFICIENT
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST

XrLightEstimatorCreateInfoANDROID 结构描述了用于创建 XrLightEstimatorANDROID 句柄的信息。

typedef struct XrLightEstimatorCreateInfoANDROID {
    XrStructureType    type;
    const void*        next;
} XrLightEstimatorCreateInfoANDROID;

成员说明

  • type 是此结构的 XrStructureType。
  • next 是 NULL 或指向结构链中下一个结构的指针。核心 OpenXR 或此扩展程序中未定义任何此类结构。

有效用法（隐式）

xrDestroyLightEstimatorANDROID 函数的定义如下：

XrResult xrDestroyLightEstimatorANDROID(
    XrLightEstimatorANDROID                     estimator);

参数说明

The xrDestroyLightEstimatorANDROID 函数会释放 estimator 和任何底层资源。

有效用法（隐式）

线程安全

  • 对 estimator 及其任何子句柄的访问必须 在外部进行同步

返回代码

成功

  • XR_SUCCESS

失败

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

访问光照估计数据

xrGetLightEstimateANDROID 函数的定义如下：

XrResult xrGetLightEstimateANDROID(
    XrLightEstimatorANDROID                     estimator,
    const XrLightEstimateGetInfoANDROID*        input,
    XrLightEstimateANDROID*                     output);

参数说明

有效用法（隐式）

返回代码

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失败

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

XrLightEstimateGetInfoANDROID 结构的定义如下：

typedef struct XrLightEstimateGetInfoANDROID {
    XrStructureType    type;
    const void*        next;
    XrSpace            space;
    XrTime             time;
} XrLightEstimateGetInfoANDROID;

成员说明

  • type 是此结构的 XrStructureType。
  • next 是 NULL 或指向结构链中下一个结构的指针。
  • space 是 XrSpace，用于定义返回的光照方向和球面谐波所表示的参考空间。
  • time 是 XrTime，用于描述应用希望查询光线估计的时间。

有效用法（隐式）

XrLightEstimateANDROID 结构包含光照估计数据：

typedef struct XrLightEstimateANDROID {
    XrStructureType                type;
    void*                          next;
    XrLightEstimateStateANDROID    state;
    XrTime                         lastUpdatedTime;
} XrLightEstimateANDROID;

成员说明

对于每个光照估计结构体，如果 state 为 XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID，则结构体中的所有其他字段都是任意的，这意味着它们的值未定义。

如需获取环境光、球面谐波和主定向光的估计信息，应用可以 将以下结构的实例分别链接到 XrLightEstimateANDROID :: next：XrAmbientLightANDROID、XrSphericalHarmonicsANDROID 和 XrDirectionalLightANDROID。

有效用法（隐式）

XrAmbientLightANDROID 结构包含有关场景中氛围灯的光照估计数据。

typedef struct XrAmbientLightANDROID {
    XrStructureType                type;
    void*                          next;
    XrLightEstimateStateANDROID    state;
    XrVector3f                     intensity;
    XrVector3f                     colorCorrection;
} XrAmbientLightANDROID;

成员说明

  • type 是此结构的 XrStructureType。
  • next 是 NULL 或指向结构链中下一个结构的指针。有效结构包括 XrSphericalHarmonicsANDROID 和 XrDirectionalLightANDROID。
  • state 是 XrLightEstimateStateANDROID，表示光照估计的状态。
  • intensity 是 XrVector3f，表示环境光的强度。向量的每个分量分别对应于红色、绿色和蓝色通道。

  • colorCorrection 是一个 XrVector3f，其值位于伽马空间中。如果在伽马色彩空间中渲染，请在渲染后将它们与最终计算出的颜色按分量相乘。如果在线性空间中渲染，请先将值转换为线性空间（方法是将其提升到 2.2 次方），然后在渲染后将它们与最终计算出的颜色按分量相乘。

    The purpose of pname:colorCorrection is to make a scene appear natural and
blend with the real world.

有效用法（隐式）

XrSphericalHarmonicsANDROID 结构包含表示场景照明情况的球面谐波。

typedef struct XrSphericalHarmonicsANDROID {
    XrStructureType                    type;
    void*                              next;
    XrLightEstimateStateANDROID        state;
    XrSphericalHarmonicsKindANDROID    kind;
    float                              coefficients[9][3];
} XrSphericalHarmonicsANDROID;

成员说明

coefficients 将在特殊函数中使用，该函数将方向作为输入，并输出来自该方向的光照颜色。如需了解更多详细信息，请参阅此论文。

有效用法（隐式）

XrSphericalHarmonicsKindANDROID 枚举向运行时标识应用请求的球面谐波类型。

typedef enum XrSphericalHarmonicsKindANDROID {
    XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID = 0,
    XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID = 1,
    XR_SPHERICAL_HARMONICS_KIND_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSphericalHarmonicsKindANDROID;

枚举值具有以下含义：

枚举说明

XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID

球面谐波系数表示环境光辐射函数，不包括主光的贡献。

XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID

球面谐波系数表示环境光辐射函数，包括主光的贡献。

XrDirectionalLightANDROID 结构包含光照估计数据。

typedef struct XrDirectionalLightANDROID {
    XrStructureType                type;
    void*                          next;
    XrLightEstimateStateANDROID    state;
    XrVector3f                     intensity;
    XrVector3f                     direction;
} XrDirectionalLightANDROID;

成员说明

有效用法（隐式）

XrLightEstimateStateANDROID 枚举指示运行时返回的光照估计的状态。

typedef enum XrLightEstimateStateANDROID {
    XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID = 0,
    XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID = 1,
    XR_LIGHT_ESTIMATE_STATE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrLightEstimateStateANDROID;

枚举值具有以下含义：

枚举说明

XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID

光照估计有效

XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID

光照估计无效

光照估计的示例代码

以下示例代码演示了如何从运行时获取所有可能的光照估计量

XrSession session;  // Created at app startup
XrSpace appSpace;   // Created previously.
PFN_xrCreateLightEstimatorANDROID xrCreateLightEstimatorANDROID; // Created previously.
PFN_xrDestroyLightEstimatorANDROID xrDestroyLightEstimatorANDROID; // Created previously.
PFN_xrGetLightEstimateANDROID xrGetLightEstimateANDROID; // Created previously.

XrLightEstimatorANDROID estimator;
XrLightEstimatorCreateInfoANDROID createInfo = {
    .type = XR_TYPE_LIGHT_ESTIMATOR_CREATE_INFO_ANDROID};
CHK_XR(xrCreateLightEstimatorANDROID(session, &createInfo, &estimator));

// Every frame
XrTime updateTime;  // Time used for the current frame's simulation update.

XrLightEstimateGetInfoANDROID info = {
    .type = XR_TYPE_LIGHT_ESTIMATE_GET_INFO_ANDROID,
    .space = appSpace,
    .time = updateTime,
};

XrDirectionalLightANDROID directionalLight = {
    .type = XR_TYPE_DIRECTIONAL_LIGHT_ANDROID,
};

XrSphericalHarmonicsANDROID sphericalHarmonics = {
    .type = XR_TYPE_SPHERICAL_HARMONICS_ANDROID,
    .next = &directionalLight,
};

// Querying both TOTAL or AMBIENT spherical harmonics in one call will result in an error because chaining two structs with the same type is not allowed
bool useTotalSH;
if (useTotalSH) {
  sphericalHarmonics.kind = XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID;
} else {
  sphericalHarmonics.kind = XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID;
}

XrAmbientLightANDROID ambientLight = {
    .type = XR_TYPE_AMBIENT_LIGHT_ANDROID,
    .next = &sphericalHarmonics,
};

XrLightEstimateANDROID estimate = {
    .type = XR_TYPE_LIGHT_ESTIMATE_ANDROID,
    .next = &ambientLight,
};

XrResult result = xrGetLightEstimateANDROID(estimator, &info, &estimate);
if (result == XR_SUCCESS &&
    estimate.state == XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID) {
  // use directionalLight, totalSh, ambientSh, ambientLight if each
  // struct has a valid state field
}

// When you want to disable light estimation
CHK_XR(xrDestroyLightEstimatorANDROID(estimator));

新对象类型

新命令

新结构

新枚举

新枚举常量

  • XR_ANDROID_LIGHT_ESTIMATION_EXTENSION_NAME
  • XR_ANDROID_light_estimation_SPEC_VERSION

  • 扩展 XrObjectType：

    • XR_OBJECT_TYPE_LIGHT_ESTIMATOR_ANDROID

  • 扩展 XrStructureType：

    • XR_TYPE_AMBIENT_LIGHT_ANDROID
    • XR_TYPE_DIRECTIONAL_LIGHT_ANDROID
    • XR_TYPE_LIGHT_ESTIMATE_ANDROID
    • XR_TYPE_LIGHT_ESTIMATE_GET_INFO_ANDROID
    • XR_TYPE_LIGHT_ESTIMATOR_CREATE_INFO_ANDROID
    • XR_TYPE_SPHERICAL_HARMONICS_ANDROID
    • XR_TYPE_SYSTEM_LIGHT_ESTIMATION_PROPERTIES_ANDROID

问题

版本记录

  • 修订版本 1，2024 年 9 月 16 日 (Cairn Overturf)

    • 初始扩展程序说明