XR_ANDROID_light_estimation

名稱字串

XR_ANDROID_light_estimation

擴充功能類型

執行個體擴充功能

擴充功能註冊編號

701

修訂版本

1

批准狀態

未批准

擴充功能和版本依附元件

OpenXR 1.0

上次修改日期

2025-03-13

IP 狀態

未發現任何智慧財產權聲明。

著作人

Google 的 Jared Finder
Google 的 Cairn Overturf
Google 的 Spencer Quin
Google 的 Levana Chen
Google 的 Nihav Jain
Google 的 Salar Khan
Google 的 Scott Chung

總覽

透過這項擴充功能，應用程式可要求取得頭戴式裝置周圍真實環境光照的資料。應用程式可以使用這項資訊，在虛擬物體所處的真實場景中，以相同條件照亮虛擬物體。

權限

Android 應用程式必須在資訊清單中列出 android.permission.SCENE_UNDERSTANDING_COARSE 權限，因為這項擴充功能會公開環境的光照資訊。android.permission.SCENE_UNDERSTANDING_COARSE 權限視為危險權限。應用程式必須在執行階段要求權限，才能使用下列函式：

• xrCreateLightEstimatorANDROID

(防護等級：危險)

檢查系統功能

XrSystemLightEstimationPropertiesANDROID 結構體的定義如下：

typedef struct XrSystemLightEstimationPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsLightEstimation;
} XrSystemLightEstimationPropertiesANDROID;

成員說明

• type 是這個結構的 XrStructureType。
• next 是 NULL，或是指向結構鏈中下一個結構的指標。核心 OpenXR 或這個擴充功能中未定義這類結構。
• supportsLightEstimation 是 XrBool32，指出目前的系統是否支援光線估算。

應用程式可以在呼叫 xrGetSystemProperties 時，使用 XrSystemLightEstimationPropertiesANDROID 結構體擴充 XrSystemProperties，檢查系統是否支援光線估算。

如果且僅當執行階段為 supportsLightEstimation 傳回 XR_FALSE 做為 supportsLightEstimation 時，執行階段必須從 xrCreateLightEstimatorANDROID 傳回 XR_ERROR_FEATURE_UNSUPPORTED。

有效用量 (隱含)

• XR_ANDROID_light_estimation 擴充功能必須先啟用，才能使用 XrSystemLightEstimationPropertiesANDROID
•  type 必須為 XR_TYPE_SYSTEM_LIGHT_ESTIMATION_PROPERTIES_ANDROID
• next 必須是 NULL，或是指向結構體鏈結中下一個結構體的有效指標

建立光線估算器控制代碼

XR_DEFINE_HANDLE(XrLightEstimatorANDROID)

執行階段會產生光線估算資料，並使用 XrLightEstimatorANDROID 控制代碼與應用程式共用。

這個控制代碼可用於透過這個擴充功能中的其他函式存取光線估算資訊。

xrCreateLightEstimatorANDROID 函式定義如下：

XrResult xrCreateLightEstimatorANDROID(
    XrSession                                   session,
    XrLightEstimatorCreateInfoANDROID*          createInfo,
    XrLightEstimatorANDROID*                    outHandle);

參數說明

• session 是建立光線估算器的 XrSession。
• createInfo 是 XrLightEstimatorCreateInfoANDROID 結構的指標，內含用於建立光線估算器的參數。
• outHandle 是控制代碼的指標，建立的 XrLightEstimatorANDROID 會傳回至該指標。

應用程式會使用 xrCreateLightEstimatorANDROID 函式建立光線估算器。

• 如果系統不支援光線估算，執行階段必須傳回 XR_ERROR_FEATURE_UNSUPPORTED。
• 如果呼叫應用程式未獲得必要權限，執行階段必須傳回 XR_ERROR_PERMISSION_INSUFFICIENT。

如果應用程式要向執行階段指出已完成存取光線估算資料，必須透過 xrDestroyLightEstimatorANDROID 銷毀控制代碼。

有效用量 (隱含)

• 呼叫 xrCreateLightEstimatorANDROID 前，XR_ANDROID_light_estimation 擴充功能必須啟用
• session must 為有效的 XrSession 控制代碼
• createInfo 必須是指向 XrLightEstimatorCreateInfoANDROID 結構體的指標
• outHandle 必須是指向 XrLightEstimatorANDROID 控制代碼的指標

傳回代碼

成功

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

失敗

• XR_ERROR_FEATURE_UNSUPPORTED
• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_LIMIT_REACHED
• XR_ERROR_OUT_OF_MEMORY
• XR_ERROR_PERMISSION_INSUFFICIENT
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_SESSION_LOST

XrLightEstimatorCreateInfoANDROID 結構會說明建立 XrLightEstimatorANDROID 控制代碼的資訊。

typedef struct XrLightEstimatorCreateInfoANDROID {
    XrStructureType    type;
    const void*        next;
} XrLightEstimatorCreateInfoANDROID;

成員說明

• type 是這個結構的 XrStructureType。
• next 是 NULL，或是指向結構鏈中下一個結構的指標。核心 OpenXR 或這個擴充功能中未定義這類結構。

有效用量 (隱含)

• XR_ANDROID_light_estimation 擴充功能必須先啟用，才能使用 XrLightEstimatorCreateInfoANDROID
•  type 必須為 XR_TYPE_LIGHT_ESTIMATOR_CREATE_INFO_ANDROID
• next must 為 NULL，或指向結構鏈中下一個結構的有效指標。另請參閱：XrCubemapLightEstimatorCreateInfoANDROID、XrPointLightsEstimatorCreateInfoANDROIDX1

xrDestroyLightEstimatorANDROID 函式定義如下：

XrResult xrDestroyLightEstimatorANDROID(
    XrLightEstimatorANDROID                     estimator);

參數說明

• estimator 是先前由 xrCreateLightEstimatorANDROID 建立的 XrLightEstimatorANDROID。

xrDestroyLightEstimatorANDROID 函式會釋放 estimator 和所有基礎資源。

有效用量 (隱含)

• 呼叫 xrDestroyLightEstimatorANDROID 前，XR_ANDROID_light_estimation 擴充功能必須啟用
• estimator 必須是有效的 XrLightEstimatorANDROID 控制代碼

執行緒安全

• estimator 和任何子項控制代碼的存取權必須從外部同步處理

傳回代碼

成功

• XR_SUCCESS

失敗

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID

存取光線估算資料

xrGetLightEstimateANDROID 函式定義如下：

XrResult xrGetLightEstimateANDROID(
    XrLightEstimatorANDROID                     estimator,
    const XrLightEstimateGetInfoANDROID*        input,
    XrLightEstimateANDROID*                     output);

參數說明

• estimator 是 xrCreateLightEstimatorANDROID 先前建立的 XrLightEstimatorANDROID 控制代碼。
• input 是 XrLightEstimateGetInfoANDROID 結構的指標。
• output 是 XrLightEstimateANDROID 結構的指標。

有效用量 (隱含)

• 呼叫 xrGetLightEstimateANDROID 前，XR_ANDROID_light_estimation 擴充功能必須啟用
• estimator 必須是有效的 XrLightEstimatorANDROID 控制代碼
• input 必須是指向有效 XrLightEstimateGetInfoANDROID 結構體的指標
• output 必須是指向 XrLightEstimateANDROID 結構的指標

傳回代碼

成功

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

失敗

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_OUT_OF_MEMORY
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_SESSION_LOST
• XR_ERROR_TIME_INVALID
• XR_ERROR_VALIDATION_FAILURE

XrLightEstimateGetInfoANDROID 結構體的定義如下：

typedef struct XrLightEstimateGetInfoANDROID {
    XrStructureType    type;
    const void*        next;
    XrSpace            space;
    XrTime             time;
} XrLightEstimateGetInfoANDROID;

成員說明

• type 是這個結構的 XrStructureType。
• next 是 NULL，或是指向結構鏈中下一個結構的指標。
• space 是 XrSpace，用於定義參考空間，其中會表示傳回的光線方向和球諧函數。
• time 是 XrTime，說明應用程式要查詢光線估計值的時間。

有效用量 (隱含)

• 必須先啟用 XR_ANDROID_light_estimation 擴充功能，才能使用 XrLightEstimateGetInfoANDROID
•  type 必須為 XR_TYPE_LIGHT_ESTIMATE_GET_INFO_ANDROID
• next 必須是 NULL，或是指向結構體鏈結中下一個結構體的有效指標
• space 必須是有效的 XrSpace 控制代碼

XrLightEstimateANDROID 結構包含光線估算資料：

typedef struct XrLightEstimateANDROID {
    XrStructureType                type;
    void*                          next;
    XrLightEstimateStateANDROID    state;
    XrTime                         lastUpdatedTime;
} XrLightEstimateANDROID;

成員說明

• type 是這個結構的 XrStructureType。
• next 是 NULL，或是指向結構鏈中下一個結構的指標。有效結構包括 XrAmbientLightANDROID、XrSphericalHarmonicsANDROID 和 XrDirectionalLightANDROID。
• state 是代表光線估算狀態的 XrLightEstimateStateANDROID。
• lastUpdatedTime 是 XrTime，代表上次計算預估值的時間。

如果每個光線估計值結構體的 state 為 XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID，則結構體中的所有其他欄位都是任意值，也就是未定義值。

如要取得環境光、球諧函數和主要方向光的估算資訊，應用程式可以分別鏈結下列結構的執行個體：XrAmbientLightANDROID、XrSphericalHarmonicsANDROID 和 XrDirectionalLightANDROID，至 XrLightEstimateANDROID :: next。

有效用量 (隱含)

• XR_ANDROID_light_estimation 擴充功能必須先啟用，才能使用 XrLightEstimateANDROID
•  type 必須為 XR_TYPE_LIGHT_ESTIMATE_ANDROID
• next must 為 NULL，或指向結構鏈中下一個結構的有效指標。另請參閱：XrAmbientLightANDROID、XrCubemapLightingDataANDROID、XrDirectionalLightANDROID、XrPointLightsANDROIDX1、XrSphericalHarmonicsANDROID
• state 必須是有效的 XrLightEstimateStateANDROID 值

XrAmbientLightANDROID 結構包含場景中環境光的光線估算資料。

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

成員說明

• type 是這個結構的 XrStructureType。
• next 是 NULL，或是指向結構鏈中下一個結構的指標。有效結構包括 XrSphericalHarmonicsANDROID 和 XrDirectionalLightANDROID。
• state 是代表光線估算狀態的 XrLightEstimateStateANDROID。
• intensity 是代表環境光強度的 XrVector3f。向量的每個分量分別對應紅色、綠色和藍色通道。

• colorCorrection 是 XrVector3f，值位於 Gamma 空間。如果要在 Gamma 色彩空間中算繪，請在算繪後，將這些值與最終計算出的色彩逐一相乘。如要在線性空間中算繪，請先將值升至 2.2 次方，轉換為線性空間，然後與算繪後最終計算出的顏色逐一相乘。

  The purpose of pname:colorCorrection is to make a scene appear natural and
  blend with the real world.
  

有效用量 (隱含)

• 必須先啟用 XR_ANDROID_light_estimation 擴充功能，才能使用 XrAmbientLightANDROID
•  type 必須為 XR_TYPE_AMBIENT_LIGHT_ANDROID
• next 必須是 NULL，或是指向結構體鏈結中下一個結構體的有效指標
• state 必須是有效的 XrLightEstimateStateANDROID 值

XrSphericalHarmonicsANDROID 結構包含代表場景光源的球諧函數。

typedef struct XrSphericalHarmonicsANDROID {
    XrStructureType                    type;
    void*                              next;
    XrLightEstimateStateANDROID        state;
    XrSphericalHarmonicsKindANDROID    kind;
    float                              coefficients[9][3];
} XrSphericalHarmonicsANDROID;

成員說明

• type 是這個結構的 XrStructureType。
• next 是 NULL，或是指向結構鏈中下一個結構的指標。有效結構包括 XrAmbientLightANDROID 和 XrDirectionalLightANDROID。
• state 是代表光線估算狀態的 XrLightEstimateStateANDROID。
• kind 是應用程式要求的 XrSphericalHarmonicsKindANDROID。
• coefficients 是二維 float 陣列，維度為 9 列和 3 欄。分別對應紅色、綠色和藍色通道的 3 個資料欄。每個通道都有 9 個球諧係數。

coefficients 會用於特殊函式，該函式會將方向做為輸入內容，並輸出來自該方向的光線顏色。詳情請參閱這份文件。

有效用量 (隱含)

• XR_ANDROID_light_estimation 擴充功能必須先啟用，才能使用 XrSphericalHarmonicsANDROID
•  type 必須為 XR_TYPE_SPHERICAL_HARMONICS_ANDROID
• next 必須是 NULL，或是指向結構體鏈結中下一個結構體的有效指標
• state 必須是有效的 XrLightEstimateStateANDROID 值
• kind 必須是有效的 XrSphericalHarmonicsKindANDROID 值

XrSphericalHarmonicsKindANDROID 列舉會向執行階段指出應用程式要求哪種球諧函數。

typedef enum XrSphericalHarmonicsKindANDROID {
    XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID = 0,
    XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID = 1,
    XR_SPHERICAL_HARMONICS_KIND_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSphericalHarmonicsKindANDROID;

列舉值具有下列意義：

列舉說明

XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID

球諧係數代表環境光輻射函數，不包括主燈的貢獻。

XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID

球諧係數代表環境光輻射函數，包括主要光源的貢獻。

XrDirectionalLightANDROID 結構包含光線估算資料。

typedef struct XrDirectionalLightANDROID {
    XrStructureType                type;
    void*                          next;
    XrLightEstimateStateANDROID    state;
    XrVector3f                     intensity;
    XrVector3f                     direction;
} XrDirectionalLightANDROID;

成員說明

• type 是這個結構的 XrStructureType。
• next 是 NULL，或是指向結構鏈中下一個結構的指標。有效結構包括 XrAmbientLightANDROID、XrSphericalHarmonicsANDROID 和 XrDirectionalLightANDROID。
• state 是代表光線估算狀態的 XrLightEstimateStateANDROID。
• intensity 是代表方向光強度的 XrVector3f。向量的每個分量分別對應紅色、綠色和藍色通道。
• direction 是代表光線方向的 XrVector3f。

有效用量 (隱含)

• 必須先啟用 XR_ANDROID_light_estimation 擴充功能，才能使用 XrDirectionalLightANDROID
•  type 必須為 XR_TYPE_DIRECTIONAL_LIGHT_ANDROID
• next 必須是 NULL，或是指向結構體鏈結中下一個結構體的有效指標
• state 必須是有效的 XrLightEstimateStateANDROID 值

XrLightEstimateStateANDROID 列舉會指出執行階段傳回的光線估算狀態。

typedef enum XrLightEstimateStateANDROID {
    XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID = 0,
    XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID = 1,
    XR_LIGHT_ESTIMATE_STATE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrLightEstimateStateANDROID;

列舉值具有下列意義：

列舉說明

XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID

光線估算值有效

XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID

預估值無效

光線估算範例程式碼

下列程式碼範例說明如何從執行階段取得所有可能的燈光估算量

XrSession session;  // Created at app startup
XrSpace appSpace;   // Created previously.
PFN_xrCreateLightEstimatorANDROID xrCreateLightEstimatorANDROID; // Created previously.
PFN_xrDestroyLightEstimatorANDROID xrDestroyLightEstimatorANDROID; // Created previously.
PFN_xrGetLightEstimateANDROID xrGetLightEstimateANDROID; // 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 sphericalHarmonics = {
    .type = XR_TYPE_SPHERICAL_HARMONICS_ANDROID,
    .next = &directionalLight,
};

// Querying both TOTAL or AMBIENT spherical harmonics in one call will result in an error because chaining two structs with the same type is not allowed
bool useTotalSH;
if (useTotalSH) {
  sphericalHarmonics.kind = XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID;
} else {
  sphericalHarmonics.kind = XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID;
}

XrAmbientLightANDROID ambientLight = {
    .type = XR_TYPE_AMBIENT_LIGHT_ANDROID,
    .next = &sphericalHarmonics,
};

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));

新物件類型

• XrLightEstimatorANDROID

新指令

• xrCreateLightEstimatorANDROID
• xrDestroyLightEstimatorANDROID
• xrGetLightEstimateANDROID

新結構

• XrLightEstimateANDROID
• XrLightEstimateGetInfoANDROID
• XrLightEstimatorCreateInfoANDROID

• 擴充 XrLightEstimateANDROID：

  • XrAmbientLightANDROID
  • XrDirectionalLightANDROID
  • XrSphericalHarmonicsANDROID

• 擴充 XrSystemProperties：

  • XrSystemLightEstimationPropertiesANDROID

新列舉

• XrLightEstimateStateANDROID
• XrSphericalHarmonicsKindANDROID

新增列舉常數

• XR_ANDROID_LIGHT_ESTIMATION_EXTENSION_NAME
• XR_ANDROID_light_estimation_SPEC_VERSION

• 擴充 XrObjectType：

  • XR_OBJECT_TYPE_LIGHT_ESTIMATOR_ANDROID

• 擴充 XrStructureType：

  • XR_TYPE_AMBIENT_LIGHT_ANDROID
  • XR_TYPE_DIRECTIONAL_LIGHT_ANDROID
  • XR_TYPE_LIGHT_ESTIMATE_ANDROID
  • XR_TYPE_LIGHT_ESTIMATE_GET_INFO_ANDROID
  • XR_TYPE_LIGHT_ESTIMATOR_CREATE_INFO_ANDROID
  • XR_TYPE_SPHERICAL_HARMONICS_ANDROID
  • XR_TYPE_SYSTEM_LIGHT_ESTIMATION_PROPERTIES_ANDROID

問題

版本記錄

• 修訂版本 1，2024 年 9 月 16 日 (Cairn Overturf)

  • 擴充功能初始說明