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;

成員說明

如要取得環境光照明立方圖、環境光線、球面調和以及主要方向光線的光線估計資訊，應用程式可以將以下結構的例項連結至 XrLightEstimateANDROID::next，分別為 XrEnvironmentLightingCubemapANDROID、XrAmbientLightANDROID、XrSphericalHarmonicsANDROID 和 XrDirectionalLightANDROID。

有效用法 (隱含)

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;

這些列舉的意思如下：

Enum

說明

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;

這些列舉的意思如下：

Enum

說明

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)
    • 初始擴充功能說明