XR_ANDROID_light_estimation OpenXR 扩展程序

名称字符串

XR_ANDROID_light_estimation

扩展程序类型

实例扩展程序

注册的扩展程序编号

701

修订版

1

扩展程序和版本依赖项

OpenXR 1.0

上次修改日期

2025-01-17

知识产权状态

无已知知识产权声明。

贡献者

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，表示立方体贴图每侧图像的宽度和高度。请注意，这是 HDR，因此浮点值可以大于 1.0。
  • rotation 是一个 XrQuaternionf，表示立方体贴图的旋转。
  • centerExposureTime 是一个 XrTime，表示立方体贴图捕获的时间。这对于立方体贴图之间的插值很有用。

有效用法（隐式）

  • 在使用 XrEnvironmentLightingCubemapANDROID 之前，必须启用 XR_ANDROID_light_estimation 扩展程序。
  • 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 (Salar Khan)
    • 添加了环境光照立方体贴图支持
  • 修订版 1，2024-09-16 (Cairn Overturf)
    • 初始扩展程序说明

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