Android XR SDK 現已在開發人員預覽版中推出。敬請提供意見回饋！請前往支援頁面與我們聯絡。

本頁面由 Cloud Translation API 翻譯而成。

XR_ANDROID_light_estimation OpenXR 擴充功能

名稱字串

XR_ANDROID_light_estimation

擴充功能類型

延長執行個體期限

已註冊的分機號碼

701

修訂

擴充功能和版本依附元件

OpenXR 1.0

上次修改日期

2025-01-17

IP 狀態

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

著作人

Google 員工 Jared Finder

Google 的 Cairn Overturf

Google 員工 Spencer Quin

Google 產品經理 Levana Chen

Google 的 Nihav Jain

Google 的 Salar Khan

Google 的 Scott Chung

總覽

這項擴充功能可讓應用程式要求代表頭戴式裝置周圍真實環境光照的資料。這項資訊可用於顯示虛擬物件，讓物件在與放置場景相同的條件下發光。

檢查系統功能

應用程式可以在呼叫 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。

有效用量 (隱含)

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

建立光線估算器控制代碼

XR_DEFINE_HANDLE(XrLightEstimatorANDROID)

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

xrCreateLightEstimatorANDROID 函式定義如下：

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

參數說明

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

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

如果系統不支援光線估算，xrCreateLightEstimatorANDROID 會傳回 XR_ERROR_FEATURE_UNSUPPORTED。
如果呼叫應用程式未獲授與必要權限，xrCreateLightEstimatorANDROID 會傳回 XR_ERROR_PERMISSION_INSUFFICIENT。

傳回的光線估算器控制代碼可能會隨後用於 API 呼叫。如果應用程式想向執行階段指出已完成存取光線估算資料，必須使用 xrDestroyLightEstimatorANDROID 銷毀控制代碼。

有效用量 (隱含)

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

傳回代碼

成功

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 或這個擴充功能中未定義這類結構。

有效用量 (隱含)

使用 XrLightEstimatorCreateInfoANDROID 前，XR_ANDROID_light_estimation 擴充功能必須啟用。
type 必須為 XR_TYPE_LIGHT_ESTIMATOR_CREATE_INFO_ANDROID
next 必須是 NULL，或是指向結構體鏈結中下一個結構體的有效指標

xrDestroyLightEstimatorANDROID 函式會釋放 estimator 和任何基礎資源。

XrResult xrDestroyLightEstimatorANDROID(
    XrLightEstimatorANDROID                     estimator);

參數說明

estimator 是先前由 xrCreateLightEstimatorANDROID 建立的 XrLightEstimatorANDROID。

有效用量 (隱含)

XR_ANDROID_light_estimation 擴充功能必須先啟用，才能呼叫 xrDestroyLightEstimatorANDROID
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 結構體的指標。

有效用量 (隱含)

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

傳回代碼

成功

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，用於說明應用程式要查詢光線估計值的時間。

有效用量 (隱含)

使用 XrLightEstimateGetInfoANDROID 前，XR_ANDROID_light_estimation 擴充功能必須啟用
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、 XrEnvironmentLightingCubemapANDROID 和 XrDirectionalLightANDROID。
state 是 XrLightEstimateStateANDROID，代表光線估計狀態。
lastUpdatedTime 是 XrTime，代表上次計算預估值的時間。

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

有效用量 (隱含)

使用 XrLightEstimateANDROID 前，XR_ANDROID_light_estimation 擴充功能必須啟用
type 必須為 XR_TYPE_LIGHT_ESTIMATE_ANDROID
next 必須是 NULL，或是結構體鏈結中下一個結構體的有效指標。另請參閱：XrAmbientLightANDROID、 XrDirectionalLightANDROID、 XrEnvironmentLightingCubemapANDROID、 XrSphericalHarmonicsANDROID
「state」必須是有效的 XrLightEstimateStateANDROID 值

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 是代表立方體地圖頂端 R32G32B32_SFLOAT 緩衝區的 float*。請注意，這是 HDR，因此浮點值可以大於 1.0。
cubemapBottomImage 是 float*，代表立方體地圖底部的 R32G32B32_SFLOAT 緩衝區。請注意，這是 HDR，因此浮點值可以大於 1.0。
cubemapFrontImage 是 float*，代表立方體貼圖正面的 R32G32B32_SFLOAT 緩衝區。請注意，這是 HDR，因此浮點值可以大於 1.0。
resolution 是 uint32_t，代表立方體貼圖各邊圖片的寬度和高度。
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;

成員說明

type 是這個結構的 XrStructureType。
next 是 NULL，或是指向結構鏈中下一個結構的指標。有效結構為 XrSphericalHarmonicsANDROID、XrEnvironmentLightingCubemapANDROID 和 XrDirectionalLightANDROID。
state 是 XrLightEstimateStateANDROID，代表光線估計狀態。
intensity 是 XrVector3，代表環境光的強度。向量的每個分量分別對應紅色、綠色和藍色通道。
colorCorrection 是 XrVector3，值位於 Gamma 空間。將 Gamma 校正後算繪的顏色與這些值逐一相乘。

有效用量 (隱含)

使用 XrAmbientLightANDROID 前，XR_ANDROID_light_estimation 擴充功能必須啟用。
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、XrEnvironmentLightingCubemapANDROID 和 XrDirectionalLightANDROID。
state 是 XrLightEstimateStateANDROID，代表光線估計狀態。
kind 是應用程式要求的 XrSphericalHarmonicsKindANDROID。
coefficients 是二維 float 陣列，維度為 9 列和 3 欄。分別對應紅色、綠色和藍色色版的 3 個資料欄。每個聲道都有 9 個球諧係數。

有效用量 (隱含)

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

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 是 XrVector3，代表方向光的強度。向量的每個分量都對應到紅色、綠色和藍色通道。
direction 是代表光線方向的 XrVector3。

有效用量 (隱含)

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

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

新列舉

XrSphericalHarmonicsKindANDROID
XrLightEstimateStateANDROID

新結構

XrLightEstimatorCreateInfoANDROID
XrLightEstimateGetInfoANDROID
XrLightEstimateANDROID
XrDirectionalLightANDROID
XrSphericalHarmonicsANDROID
XrAmbientLightANDROID
XrSystemLightEstimationPropertiesANDROID
XrEnvironmentLightingCubemapANDROID

新函式

xrCreateLightEstimatorANDROID
xrDestroyLightEstimatorANDROID
xrGetLightEstimateANDROID

問題

版本記錄

修訂版本 2，2025-01-17 (Salar Khan)
- 新增環境照明立方體貼圖支援
修訂版本 1，2024-09-16 (Cairn Overturf)
- 擴充功能初始說明

OpenXR™ 和 OpenXR 標誌是 The Khronos Group Inc. 的商標，已在中國、歐盟、日本和英國註冊為商標。

XR_ANDROID_light_estimation OpenXR 擴充功能 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

總覽

檢查系統功能

成員說明

有效用量 (隱含)

建立光線估算器控制代碼

參數說明

有效用量 (隱含)

成員說明

有效用量 (隱含)

參數說明

有效用量 (隱含)

執行緒安全

傳回代碼

存取光線估算資料

參數說明

有效用量 (隱含)

傳回代碼

成員說明

有效用量 (隱含)

成員說明

有效用量 (隱含)

成員說明

有效用量 (隱含)

成員說明

有效用量 (隱含)

成員說明

有效用量 (隱含)

成員說明

有效用量 (隱含)

光線估算範例程式碼

XR_ANDROID_light_estimation OpenXR 擴充功能