XR_ANDROID_light_estimation OpenXR 扩展

名称字符串

XR_ANDROID_light_estimation

扩展类型

实例扩展程序

已注册的扩展程序编号

701

修订版本

1

扩展程序和版本依赖项

OpenXR 1.0

上次修改日期

2025-01-17

IP 状态

没有已知的 IP 权利主张。

创作贡献者

Jared Finder，Google

Cairn Overturf，Google

Spencer Quin，Google

Levana Chen，Google

Nihav Jain，Google

Salar Khan，Google

Scott Chung，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;

会员说明

如需获取环境光照立方贴图、环境光、球面谐波和主方向光的轻量级估计信息，应用可以将以下结构的实例（XrEnvironmentLightingCubemapANDROID、XrAmbientLightANDROID、XrSphericalHarmonicsANDROID 和 XrDirectionalLightANDROID）分别链接到 XrLightEstimateANDROID::next。

有效使用情况（隐式）

XrEnvironmentLightingCubemapANDROID 结构体包含场景环境光照的立方体贴图格式的光照估计数据。

typedef struct XrEnvironmentLightingCubemapANDROID {
    XrStructureType                type;
    void*                          next;
    XrLightEstimateStateANDROID    state;
    const float*                   cubemapRightImage;
    const float*                   cubemapLeftImage;
    const float*                   cubemapTopImage;
    const float*                   cubemapBottomImage;
    const float*                   cubemapFrontImage;
    const float*                   cubemapBackImage;
    uint32_t                       resolution;
    XrQuaternionf                  rotation;
    XrTime                         centerExposureTime;
} XrEnvironmentLightingCubemapANDROID;

会员说明

  • type 是相应结构的 XrStructureType。
  • next 是 NULL 或指向结构链中下一个结构的指针。有效结构包括 XrSphericalHarmonicsANDROID、XrAmbientLightANDROID 和 XrDirectionalLightANDROID。
  • state 是表示光估测状态的 XrLightEstimateStateANDROID。
  • cubemapRightImage 是一个 float*，表示立方体贴图右侧的 R32G32B32_SFLOAT 缓冲区。请注意，这是 HDR，因此浮点值可以大于 1.0。
  • cubemapLeftImage 是一个 float*，表示立方体贴图左侧的 R32G32B32_SFLOAT 缓冲区。请注意，这是 HDR，因此浮点值可以大于 1.0。
  • cubemapTopImage 是一个 float*，表示立方体贴图顶面的 R32G32B32_SFLOAT 缓冲区。请注意，这是 HDR，因此浮点值可以大于 1.0。
  • cubemapBottomImage 是一个 float*，表示立方体贴图底面的 R32G32B32_SFLOAT 缓冲区。请注意，这是 HDR，因此浮点值可以大于 1.0。
  • cubemapFrontImage 是一个 float*，表示立方体贴图正面的 R32G32B32_SFLOAT 缓冲区。请注意，这是 HDR，因此浮点值可以大于 1.0。
  • resolution 是一个 uint32_t，表示立方体贴图每个面的图像的宽度和高度。
  • rotation 是表示立方体贴图旋转的 XrQuaternionf。
  • centerExposureTime 是一个 XrTime，表示拍摄立方体贴图的时间。有助于在立方体贴图之间进行插值。

有效使用情况（隐式）

  • 必须先启用 XR_ANDROID_light_estimation 扩展程序，然后才能使用 XrEnvironmentLightingCubemapANDROID
  • type 必须为 XR_TYPE_ENVIRONMENT_LIGHTING_CUBEMAP_ANDROID
  • next 必须为 NULL 或指向结构链中下一个结构的有效指针
  • state 必须是有效的 XrLightEstimateStateANDROID 值
  • cubemapRightImage 必须是指向有效浮点值的指针
  • cubemapLeftImage 必须是指向有效浮点值的指针
  • cubemapTopImage 必须是指向有效浮点值的指针
  • cubemapBottomImage 必须是指向有效浮点值的指针
  • cubemapFrontImage 必须是指向有效浮点值的指针
  • cubemapBackImage 必须是指向有效浮点值的指针

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

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

会员说明

有效使用情况（隐式）

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,
};


XrEnvironmentLightingCubemapANDROID lightingCubemap {
    .type = XR_TYPE_ENVIRONMENT_LIGHTING_CUBEMAP_ANDROID,
    .next = &ambientLight,
}

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

XrResult result = xrGetLightEstimateANDROID(estimator, &info, &estimate);
if (result == XR_SUCCESS &&
    estimate.state == XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID) {
  // use directionalLight, totalSh, ambientSh, ambientLight,
  // lightingCubemap, 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
  • XR_TYPE_ENVIRONMENT_LIGHTING_CUBEMAP_ANDROID

新枚举

新结构

新函数

问题

版本历史记录

  • 修订版 2，2025-01-17（萨拉尔·汗）
    • 添加了环境光照立方体贴图支持
  • 修订版 1，2024-09-16（Cairn Overturf）
    • 初始扩展程序说明

OpenXR™ 和 OpenXR 徽标是 The Khronos Group Inc. 拥有的商标，已在中国、欧盟、日本和英国注册为商标。