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;

成員說明

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

有效用法 (隱含)

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。將 Gamma 修正算繪的顏色乘以這些值。

有效用法 (隱含)

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

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-09-16 (Cairn Overturf)
    • 初始擴充功能說明