XR_ANDROID_light_estimation OpenXR 扩展

名称字符串

XR_ANDROID_light_estimation

扩展程序类型

实例扩展

已注册的扩展号码

701

修订版本

1

扩展程序和版本依赖项

OpenXR 1.0

上次修改日期

2024-09-18

IP 状态

没有已知的 IP 版权主张。

创作贡献者

Jared Finder，Google

Cairn Overturf，Google

Spencer Quin，Google

Levana Chen，Google

Nihav Jain，Google

概览

借助此扩展程序，应用可以请求表示头盔周围真实环境的照明数据。在渲染虚拟对象时，可以使用这些信息，以便在与其所放置场景相同的条件下对其进行光照。

检查系统功能

应用可以在调用 xrGetSystemProperties 时将 XrSystemLightEstimationPropertiesANDROID 结构链接到 XrSystemProperties，以检查系统是否支持光照估算。

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 函数创建光照估算器。

返回的光照估算器句柄可以在后续的 API 调用中使用。如果应用想要向运行时指明已完成对光照估算数据的访问，则必须使用 xrDestroyLightEstimatorANDROID 销毁句柄。

有效用法（隐式）

返回代码

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失败

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

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

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

成员说明

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

有效用法（隐式）

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

XrResult xrDestroyLightEstimatorANDROID(
    XrLightEstimatorANDROID                     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_VALIDATION_FAILURE
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_TIME_INVALID

XrLightEstimateGetInfoANDROID 描述了获取光照估算数据所需的信息。

typedef struct XrLightEstimateGetInfoANDROID {
    XrStructureType    type;
    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;

成员说明

如需获取环境光、球面调和和主定向光的光估算信息，应用可以将以下结构的各个实例（分别为 XrAmbientLightANDROID、XrSphericalHarmonicsANDROID 和 XrDirectionalLightANDROID）链接到 XrLightEstimateANDROID::next。

有效用法（隐式）

XrAmbientLightANDROID 结构包含有关场景中环境光的光照估算数据。

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

成员说明

  • type 是此结构的 XrStructureType。
  • next 是 NULL 或指向结构链中下一个结构的指针。有效结构为 XrSphericalHarmonicsANDROID 和 XrDirectionalLightANDROID。
  • state 是 XrLightEstimateStateANDROID，表示光照估算的状态。
  • intensity 是一个 XrVector3，表示环境光的强度。矢量的每个分量对应于红色、绿色和蓝色通道。
  • colorCorrection 是一个值位于伽玛色彩空间的 XrVector3。将经过伽玛校正的渲染的颜色按组件乘以这些值。

有效用法（隐式）

XrSphericalHarmonicsANDROID 结构包含表示场景光照的球面调和函数。

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

成员说明

有效用法（隐式）

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

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

成员说明

有效用法（隐式）

XrSphericalHarmonicsKindANDROID 枚举用于向运行时指明应用请求的球谐函数类型。

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

枚举的含义如下：

枚举

说明

XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID

球谐系数表示环境光照度函数，不包括主光源的贡献。

XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID

球谐系数表示环境光照度函数，包括主光源的贡献。

XrLightEstimateStateANDROID 枚举用于向运行时指明应用请求的球谐函数类型。

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

枚举的含义如下：

枚举

说明

XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID

光照估算值有效

XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID

光照估算值无效

光照估算的示例代码

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

XrSession session;  // Created at app startup
XrSpace appSpace;   // 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 totalSh = {
    .type = XR_TYPE_SPHERICAL_HARMONICS_ANDROID,
    .kind = XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID,
    .next = &directionalLight,
};

XrSphericalHarmonicsANDROID ambientSh = {
    .type = XR_TYPE_SPHERICAL_HARMONICS_ANDROID,
    .kind = XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID,
    .next = &totalSh,
};

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

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));

新的对象类型

  • XrLightEstimator

XrObjectType 枚举已扩展为：

  • XR_OBJECT_TYPE_LIGHT_ESTIMATOR_ANDROID

XrStructureType 枚举已扩展为：

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

新枚举

新结构

新函数

问题

版本历史记录

  • 修订版 1，2024 年 9 月 16 日（Cairn Overturf）
    • 初始扩展程序说明