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，表示立方体的每个面的图片的宽度和高度。请注意，这是 HDR，因此浮点值可以大于 1.0。
  • 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 年 1 月 17 日（Salar Khan）
    • 添加了对环境光照立方体贴图的支持
  • 修订版 1，2024 年 9 月 16 日（Cairn Overturf）
    • 初始扩展程序说明