Android XR for OpenXR | Android Developers

Android XR SDK 已推出開發人員預覽版 3，歡迎提供意見！歡迎試用，如有任何問題，請前往支援頁面與我們聯絡。

XR_ANDROID_depth_texture

名稱字串

XR_ANDROID_depth_texture

擴充功能類型

執行個體擴充功能

擴充功能註冊編號

703

修訂版本

批准狀態

未批准

擴充功能和版本依附元件

OpenXR 1.0

上次修改日期

2024-09-11

IP 狀態

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

著作人

Google 的 Sushant Kulkarni
Google 的 Cairn Overturf
Google 的 Spencer Quin
Google 的 Levana Chen

總覽

透過這項擴充功能，應用程式可要求取得頭戴式裝置周圍真實環境的深度地圖，並在建立時查詢支援的深度解析度。

這項擴充功能旨在公開遮蔽、命中測試和其他特定任務的原始和平滑深度，以利用準確的場景幾何圖形，例如偵測偽造臉孔。

附註

深度地圖由執行階段產生，並使用 XrDepthSwapchainANDROID 與應用程式共用。在應用程式的生命週期中，執行階段不得變更透過 xrEnumerateDepthResolutionsANDROID 傳回的深度影像解析度。

權限

這項擴充功能會公開經過下採樣的深度紋理，以減輕個人識別資訊 (PII) 疑慮。Android 應用程式必須在資訊清單中列出 android.permission.SCENE_UNDERSTANDING_FINE 權限，因為這項擴充功能會公開環境的幾何結構。android.permission.SCENE_UNDERSTANDING_FINE 權限視為危險權限。應用程式必須在執行階段要求權限，才能使用下列函式：

xrCreateDepthSwapchainANDROID

(防護等級：危險)

檢查系統功能

XrSystemDepthTrackingPropertiesANDROID 結構體的定義如下：

typedef struct XrSystemDepthTrackingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsDepthTracking;
} XrSystemDepthTrackingPropertiesANDROID;

成員說明

type 是這個結構的 XrStructureType。
next 是 NULL，或是指向結構鏈中下一個結構的指標。核心 OpenXR 或這個擴充功能中未定義這類結構。
supportsDepthTracking 是 XrBool32，表示目前系統是否支援深度追蹤。

應用程式可以在呼叫 xrGetSystemProperties 時，使用 XrSystemDepthTrackingPropertiesANDROID 結構體擴充 XrSystemProperties，檢查系統是否支援深度追蹤。

如果執行階段為 supportsDepthTracking 傳回 XR_FALSE，則執行階段「必須」從 xrCreateDepthSwapchainANDROID 傳回 XR_ERROR_FEATURE_UNSUPPORTED。

有效用量 (隱含)

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

查詢深度解決方案

xrEnumerateDepthResolutionsANDROID 函式定義如下：

XrResult xrEnumerateDepthResolutionsANDROID(
    XrSession                                   session,
    uint32_t                                    resolutionCapacityInput,
    uint32_t*                                   resolutionCountOutput,
    XrDepthCameraResolutionANDROID*             resolutions);

參數說明

session 是列舉支援的深度解析度的 XrSession。
resolutionCapacityInput 是 resolutions 的容量，或 0 (如要擷取必要容量)。
resolutionCountOutput 是指向所寫入 uint64_t resolutions 數量的指標，或指向容量不足時所需容量的指標。resolutionCapacityInput
resolutions 是 XrDepthCameraResolutionANDROID 陣列的指標，但如果 resolutionCapacityInput 為 0，則可以是 NULL。
如要詳細瞭解如何擷取必要的 resolutions 大小，請參閱「緩衝區大小參數」一節。

xrEnumerateDepthResolutionsANDROID 會列舉目前工作階段支援的深度解析度。深度解析度應依執行階段偏好程度排序，從最高到最低。應用程式應使用支援的最高偏好設定，以獲得最佳效能和品質。

在工作階段的生命週期內，執行階段必須一律從這個列舉傳回相同的緩衝區內容。

有效用量 (隱含)

呼叫 xrEnumerateDepthResolutionsANDROID 前，XR_ANDROID_depth_texture 擴充功能必須啟用
session must 為有效的 XrSession 控制代碼
resolutionCountOutput 必須是指向 uint32_t 值的指標
如果 resolutionCapacityInput 不是 0，resolutions 必須是指向 resolutionCapacityInput 個 XrDepthCameraResolutionANDROID 值陣列的指標

傳回代碼

成功

XR_SUCCESS
XR_SESSION_LOSS_PENDING

失敗

XR_ERROR_FUNCTION_UNSUPPORTED
XR_ERROR_HANDLE_INVALID
XR_ERROR_INSTANCE_LOST
XR_ERROR_RUNTIME_FAILURE
XR_ERROR_SESSION_LOST
XR_ERROR_SIZE_INSUFFICIENT
XR_ERROR_VALIDATION_FAILURE

建立 XrDepthSwapchainANDROID 時，XrDepthCameraResolutionANDROID 列舉會說明支援的深度解析度。

typedef enum XrDepthCameraResolutionANDROID {
    XR_DEPTH_CAMERA_RESOLUTION_80x80_ANDROID = 0,
    XR_DEPTH_CAMERA_RESOLUTION_160x160_ANDROID = 1,
    XR_DEPTH_CAMERA_RESOLUTION_320x320_ANDROID = 2,
    XR_DEPTH_CAMERA_RESOLUTION_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrDepthCameraResolutionANDROID;

列舉值說明

XR_DEPTH_CAMERA_RESOLUTION_80x80_ANDROID - 深度和信心圖片的解析度為 80x80。
XR_DEPTH_CAMERA_RESOLUTION_160x160_ANDROID：深度和信賴度圖片的解析度為 160x160。
XR_DEPTH_CAMERA_RESOLUTION_320x320_ANDROID - 深度和信賴度圖片的解析度為 320x320。

建立深度交換鏈

XR_DEFINE_HANDLE(XrDepthSwapchainANDROID)

XrDepthSwapchainANDROID 是深度交換鏈控制代碼。

xrCreateDepthSwapchainANDROID 函式定義如下：

XrResult xrCreateDepthSwapchainANDROID(
    XrSession                                   session,
    const XrDepthSwapchainCreateInfoANDROID*    createInfo,
    XrDepthSwapchainANDROID*                    swapchain);

參數說明

session 是建立深度交換鏈的 XrSession。
createInfo 是 XrDepthSwapchainCreateInfoANDROID 結構體的指標，內含用於建立交換鏈的參數。
swapchain 是控制代碼的指標，建立的 XrDepthSwapchainANDROID 會傳回至該指標。

應用程式可以使用 xrCreateDepthSwapchainANDROID 函式建立深度交換鏈，管理深度和置信度圖像。

如果系統不支援深度追蹤，執行階段必須傳回 XR_ERROR_FEATURE_UNSUPPORTED。
如果呼叫應用程式未獲得必要權限，執行階段必須傳回 XR_ERROR_PERMISSION_INSUFFICIENT。
如果系統不支援 XrDepthSwapchainCreateInfoANDROID 中指定的深度解析度，執行階段必須傳回 XR_ERROR_VALIDATION_FAILURE。
只有在為交換鏈建立作業設定對應位元時，執行階段才應建立深度信賴度圖像。createInfo

傳回的深度交換鏈結控制代碼可能會用於後續的 API 呼叫。XrDepthSwapchainANDROID 控制代碼必須最終透過 xrDestroyDepthSwapchainANDROID 函式釋放。

有效用量 (隱含)

呼叫 xrCreateDepthSwapchainANDROID 前，XR_ANDROID_depth_texture 擴充功能必須啟用
session must 為有效的 XrSession 控制代碼
createInfo 必須是指向有效 XrDepthSwapchainCreateInfoANDROID 結構體的指標
swapchain 必須是指向 XrDepthSwapchainANDROID 控制代碼的指標

傳回代碼

成功

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

XrDepthSwapchainCreateInfoANDROID 結構體的定義如下：

typedef struct XrDepthSwapchainCreateInfoANDROID {
    XrStructureType                       type;
    const void*                           next;
    XrDepthCameraResolutionANDROID        resolution;
    XrDepthSwapchainCreateFlagsANDROID    createFlags;
} XrDepthSwapchainCreateInfoANDROID;

成員說明

type 是這個結構的 XrStructureType。
next 是 NULL，或是指向結構鏈中下一個結構的指標。核心 OpenXR 或這個擴充功能中未定義這類結構。
resolution 是用來建立深度和信賴度紋理的 XrDepthCameraResolutionANDROID。
createFlags 是一或多個 XrDepthSwapchainCreateFlagsANDROID。

將 XrDepthSwapchainCreateInfoANDROID 結構體傳遞至 xrCreateDepthSwapchainANDROID 時，可提供 XrDepthSwapchainANDROID 的建立選項。

有效用量 (隱含)

必須先啟用 XR_ANDROID_depth_texture 擴充功能，才能使用 XrDepthSwapchainCreateInfoANDROID
 type 必須為 XR_TYPE_DEPTH_SWAPCHAIN_CREATE_INFO_ANDROID
next 必須是 NULL，或是指向結構體鏈結中下一個結構體的有效指標
resolution 必須是有效的 XrDepthCameraResolutionANDROID 值
createFlags 必須是 XrDepthSwapchainCreateFlagBitsANDROID 值的有效組合
createFlags 不得為 0

XrDepthSwapchainCreateFlagsANDROID 會指定 XrDepthSwapchainANDROID 的建立選項。

typedef XrFlags64 XrDepthSwapchainCreateFlagsANDROID;

XrDepthSwapchainCreateFlagsANDROID 的有效位元由 XrDepthSwapchainCreateFlagBitsANDROID 定義，指定方式如下：

// Flag bits for XrDepthSwapchainCreateFlagsANDROID
static const XrDepthSwapchainCreateFlagsANDROID XR_DEPTH_SWAPCHAIN_CREATE_SMOOTH_DEPTH_IMAGE_BIT_ANDROID = 0x00000001;
static const XrDepthSwapchainCreateFlagsANDROID XR_DEPTH_SWAPCHAIN_CREATE_SMOOTH_CONFIDENCE_IMAGE_BIT_ANDROID = 0x00000002;
static const XrDepthSwapchainCreateFlagsANDROID XR_DEPTH_SWAPCHAIN_CREATE_RAW_DEPTH_IMAGE_BIT_ANDROID = 0x00000004;
static const XrDepthSwapchainCreateFlagsANDROID XR_DEPTH_SWAPCHAIN_CREATE_RAW_CONFIDENCE_IMAGE_BIT_ANDROID = 0x00000008;

旗標說明

XR_DEPTH_SWAPCHAIN_CREATE_SMOOTH_DEPTH_IMAGE_BIT_ANDROID：表示交換鏈會提供流暢的深度影像。
XR_DEPTH_SWAPCHAIN_CREATE_SMOOTH_CONFIDENCE_IMAGE_BIT_ANDROID：表示交換鏈會提供平滑的深度信賴度圖像。
XR_DEPTH_SWAPCHAIN_CREATE_RAW_DEPTH_IMAGE_BIT_ANDROID：表示交換鏈會提供原始深度影像。
XR_DEPTH_SWAPCHAIN_CREATE_RAW_CONFIDENCE_IMAGE_BIT_ANDROID：表示交換鏈會提供原始深度信賴度圖片。

xrDestroyDepthSwapchainANDROID 函式定義如下：

XrResult xrDestroyDepthSwapchainANDROID(
    XrDepthSwapchainANDROID                     swapchain);

參數說明

swapchain 是先前由 xrCreateDepthSwapchainANDROID 建立的 XrDepthSwapchainANDROID 控制代碼。

xrDestroyDepthSwapchainANDROID 函式會刪除深度交換鏈。通話結束後，執行階段「可能」會釋放所有相關記憶體和資源。

有效用量 (隱含)

呼叫 xrDestroyDepthSwapchainANDROID 前，XR_ANDROID_depth_texture 擴充功能必須啟用
swapchain must 為有效的 XrDepthSwapchainANDROID 控制代碼

執行緒安全

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

傳回代碼

成功

XR_SUCCESS

失敗

XR_ERROR_FUNCTION_UNSUPPORTED
XR_ERROR_HANDLE_INVALID

存取深度紋理

xrEnumerateDepthSwapchainImagesANDROID 函式定義如下：

XrResult xrEnumerateDepthSwapchainImagesANDROID(
    XrDepthSwapchainANDROID                     depthSwapchain,
    uint32_t                                    depthImageCapacityInput,
    uint32_t*                                   depthImageCountOutput,
    XrDepthSwapchainImageANDROID*               depthImages);

參數說明

depthSwapchain 是要從中取得圖像的 XrDepthSwapchainANDROID。
depthImageCapacityInput 是 depthImages 陣列的容量，或 0 (表示要求擷取必要容量)。
depthImageCountOutput 是寫入的 depthImages 數量指標，或在 depthImageCapacityInput 不足時，是所需容量的指標。
depthImages 是 XrDepthSwapchainImageANDROID 結構陣列的指標。如果 depthImageCapacityInput 為 0，則可以是 NULL。
如要詳細瞭解如何擷取必要的 depthImages 大小，請參閱「緩衝區大小參數」一節。

xrEnumerateDepthSwapchainImagesANDROID 會填入 XrDepthSwapchainImageANDROID 結構的陣列。資源必須在 XrDepthSwapchainANDROID 的生命週期內保持不變且有效。這個函式的行為與 xrEnumerateSwapchainImages 類似。

在交換鏈的生命週期內，執行階段必須一律從這個列舉傳回相同的緩衝區內容。

有效用量 (隱含)

呼叫 xrEnumerateDepthSwapchainImagesANDROID 前，XR_ANDROID_depth_texture 擴充功能必須啟用
depthSwapchain must 為有效的 XrDepthSwapchainANDROID 控制代碼
depthImageCountOutput 必須是指向 uint32_t 值的指標
如果 depthImageCapacityInput 不是 0，depthImages 必須是指向 depthImageCapacityInput 個 XrDepthSwapchainImageANDROID 結構陣列的指標

傳回代碼

成功

XR_SUCCESS
XR_SESSION_LOSS_PENDING

失敗

XR_ERROR_FUNCTION_UNSUPPORTED
XR_ERROR_HANDLE_INVALID
XR_ERROR_INSTANCE_LOST
XR_ERROR_RUNTIME_FAILURE
XR_ERROR_SESSION_LOST
XR_ERROR_SIZE_INSUFFICIENT
XR_ERROR_VALIDATION_FAILURE

XrDepthSwapchainImageANDROID 結構體的定義如下：

typedef struct XrDepthSwapchainImageANDROID {
    XrStructureType    type;
    void*              next;
    const float*       rawDepthImage;
    const uint8_t*     rawDepthConfidenceImage;
    const float*       smoothDepthImage;
    const uint8_t*     smoothDepthConfidenceImage;
} XrDepthSwapchainImageANDROID;

成員說明

type 是這個結構的 XrStructureType。
next 是 NULL，或是指向結構鏈中下一個結構的指標。核心 OpenXR 或這個擴充功能中未定義這類結構。
rawDepthImage 是 NULL，或是執行階段為左右檢視畫面分配的原始深度圖片指標。測得的值以公尺為單位。特殊值：0.0 表示原始深度中無效或空白的深度像素，Inf 表示已知深度，但實際上無限遠，
rawDepthConfidenceImage 是 NULL，或是執行階段為左右檢視畫面配置的原始深度信賴度圖像指標。
smoothDepthImage 或指標，可平滑處理執行階段分配的左右視角深度影像。NULL測得的值以公尺為單位。特殊值：0.0 表示平滑深度中的深度像素無效或空白，Inf 表示已知深度，但實際上無限遠。
smoothDepthConfidenceImage 是 NULL，或是指標，可平滑處理執行階段為左右檢視畫面分配的深度信賴度圖片。

圖像緩衝區指標只會在交換鏈的生命週期內有效。交換鏈一經銷毀，指標就會視為懸空。

XrDepthSwapchainImageANDROID 代表來自可讀取 XrDepthSwapchainANDROID 的深度圖像，分配方式如 XrDepthSwapchainCreateInfoANDROID :: resolution 和 XrDepthSwapchainCreateInfoANDROID :: createFlags 所述，同時呼叫 xrCreateDepthSwapchainANDROID。針對每張深度影像：

圖片值會以列優先順序配置在記憶體中，且列之間沒有邊框間距。
第一個值是左上角，最後一個值是右下角。
所指向記憶體的大小取決於 xrEnumerateDepthSwapchainImagesANDROID 的值，並由呼叫 xrCreateDepthSwapchainANDROID 時的 XrDepthSwapchainCreateInfoANDROID :: resolution 設定。舉例來說，如果 XrDepthSwapchainCreateInfoANDROID :: resolution 為 XR_DEPTH_CAMERA_RESOLUTION_160x160_ANDROID，深度圖片的大小將為 2*160*160*sizeof(float)。
如果 XrDepthSwapchainCreateInfoANDROID :: createFlags 未包含 XR_DEPTH_SWAPCHAIN_CREATE_RAW_DEPTH_IMAGE_BIT_ANDROID，則 rawDepthImage 的值必須為 NULL。
如果 XrDepthSwapchainCreateInfoANDROID :: createFlags 未包含 XR_DEPTH_SWAPCHAIN_CREATE_RAW_CONFIDENCE_IMAGE_BIT_ANDROID，則 rawDepthConfidenceImage 的值必須為 NULL。
如果 XrDepthSwapchainCreateInfoANDROID :: createFlags 未包含 XR_DEPTH_SWAPCHAIN_CREATE_SMOOTH_DEPTH_IMAGE_BIT_ANDROID，則 smoothDepthImage 的值必須為 NULL。
如果 XrDepthSwapchainCreateInfoANDROID :: createFlags 未包含 XR_DEPTH_SWAPCHAIN_CREATE_SMOOTH_CONFIDENCE_IMAGE_BIT_ANDROID，則 smoothDepthImage 的值必須為 NULL。

有效用量 (隱含)

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

xrAcquireDepthSwapchainImagesANDROID 函式定義如下：

XrResult xrAcquireDepthSwapchainImagesANDROID(
    XrDepthSwapchainANDROID                     depthSwapchain,
    const XrDepthAcquireInfoANDROID*            acquireInfo,
    XrDepthAcquireResultANDROID*                acquireResult);

參數說明

depthSwapchain 是深度影像的 XrDepthSwapchainANDROID 控制代碼。
acquireInfo 是 XrDepthAcquireInfoANDROID，內含如何取得深度影像的資訊。
acquireResult 是傳回的 XrDepthAcquireResultANDROID，內含所取得深度影像的相關資訊。

應用程式可以使用 xrAcquireDepthSwapchainImagesANDROID 函式，將最新的可用交換鏈結圖片索引 (即 XrDepthAcquireResultANDROID :: acquiredIndex ) 擷取到 xrEnumerateDepthSwapchainImagesANDROID 列舉的 XrDepthSwapchainImageANDROID 陣列中。傳回的 XrDepthAcquireResultANDROID 也包含其他資訊，例如解讀深度資料所需的視野和姿勢。在下次呼叫 xrAcquireDepthSwapchainImagesANDROID 之前，可以安全地從圖像陣列中取得的時段讀取資料。

在工作階段中，任何一對對應的 xrBeginFrame 和 xrEndFrame 呼叫之間，不得有超過一次的 xrAcquireDepthSwapchainImagesANDROID 呼叫。

如果執行階段先前取得的交換鏈結圖片仍在使用中，執行階段可能會遭到封鎖。
如果 xrAcquireDepthSwapchainImagesANDROID 在 xrBeginFrame 之前或 xrEndFrame 之後呼叫，執行階段「必須」傳回 XR_ERROR_CALL_ORDER_INVALID。
如果每個影格呼叫 xrAcquireDepthSwapchainImagesANDROID 超過一次，也就是在執行中的工作階段中，呼叫 xrBeginFrame 後未呼叫相關聯的 xrEndFrame，則執行階段必須傳回 XR_ERROR_LIMIT_REACHED。
如果環境深度資料尚未提供，執行階段可能會傳回 XR_ERROR_DEPTH_NOT_AVAILABLE_ANDROID。如果發生這種情況，應用程式「應」在稍後的影格再次呼叫 xrAcquireDepthSwapchainImagesANDROID。

有效用量 (隱含)

呼叫 xrAcquireDepthSwapchainImagesANDROID 前，XR_ANDROID_depth_texture 擴充功能必須啟用
depthSwapchain must 為有效的 XrDepthSwapchainANDROID 控制代碼
acquireInfo 必須是指向有效 XrDepthAcquireInfoANDROID 結構體的指標
acquireResult 必須是指向 XrDepthAcquireResultANDROID 結構體的指標

傳回代碼

成功

XR_SUCCESS
XR_SESSION_LOSS_PENDING

失敗

XR_ERROR_CALL_ORDER_INVALID
XR_ERROR_DEPTH_NOT_AVAILABLE_ANDROID
XR_ERROR_FUNCTION_UNSUPPORTED
XR_ERROR_HANDLE_INVALID
XR_ERROR_INSTANCE_LOST
XR_ERROR_LIMIT_REACHED
XR_ERROR_RUNTIME_FAILURE
XR_ERROR_SESSION_LOST
XR_ERROR_TIME_INVALID
XR_ERROR_VALIDATION_FAILURE

XrDepthAcquireInfoANDROID 結構體的定義如下：

typedef struct XrDepthAcquireInfoANDROID {
    XrStructureType    type;
    const void*        next;
    XrSpace            space;
    XrTime             displayTime;
} XrDepthAcquireInfoANDROID;

成員說明

type 是這個結構的 XrStructureType。
next 是 NULL，或是指向結構鏈中下一個結構的指標。核心 OpenXR 或這個擴充功能中未定義這類結構。
space 是 XrSpace，用於定義 XrDepthAcquireResultANDROID :: views 中傳回姿勢的參考影格。
displayTime 是 XrTime，用於指定計算 XrDepthAcquireResultANDROID :: views 中傳回姿勢的時間。應用程式應傳遞目前影格的預測顯示時間。

有效用量 (隱含)

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

XrDepthAcquireResultANDROID 結構體的定義如下：

typedef struct XrDepthAcquireResultANDROID {
    XrStructureType       type;
    const void*           next;
    uint32_t              acquiredIndex;
    XrTime                exposureTimestamp;
    XrDepthViewANDROID    views[2];
} XrDepthAcquireResultANDROID;

成員說明

type 是這個結構的 XrStructureType。
next 是 NULL，或是指向結構鏈中下一個結構的指標。核心 OpenXR 或這個擴充功能中未定義這類結構。
acquiredIndex 是擷取的紋理在 xrEnumerateDepthSwapchainImagesANDROID 列舉的 XrDepthSwapchainImageANDROID 陣列中的索引。
exposureTimestamp 是 XrTime，指定擷取深度地圖的時間。
views 是兩個 XrDepthViewANDROID 的陣列，每個眼睛各一個，其中索引 0 是左眼，索引 1 是右眼。

有效用量 (隱含)

必須先啟用 XR_ANDROID_depth_texture 擴充功能，才能使用 XrDepthAcquireResultANDROID
 type 必須為 XR_TYPE_DEPTH_ACQUIRE_RESULT_ANDROID
next 必須是 NULL，或是指向結構體鏈結中下一個結構體的有效指標
views 的任何元素必須是有效的 XrDepthViewANDROID 結構

XrDepthViewANDROID 結構體的定義如下：

typedef struct XrDepthViewANDROID {
    XrStructureType    type;
    const void*        next;
    XrFovf             fov;
    XrPosef            pose;
} XrDepthViewANDROID;

成員說明

type 是這個結構的 XrStructureType。
next 是 NULL，或是指向結構鏈中下一個結構的指標。核心 OpenXR 或這個擴充功能中未定義這類結構。
fov 是 XrFovf，用於指定產生這個檢視區塊的視野。系統絕不會水平或垂直翻轉檢視畫面。
pose 是 XrPosef，用於指定深度地圖的算繪姿勢。參考影格是在 XrDepthAcquireInfoANDROID 中指定。

有效用量 (隱含)

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

深度追蹤的程式碼範例

下列程式碼範例說明如何取得深度圖片，並使用深度值將深度圖片座標對應至舞台空間。

XrInstance instance;  // previously initialized
XrSystemId systemId;  // previously initialized
XrSession session; // previously initialized
XrSpace stageSpace; // space created for XR_REFERENCE_SPACE_TYPE_STAGE.

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrCreateDepthSwapchainANDROID xrCreateDepthSwapchainANDROID; // previously initialized
PFN_xrDestroyDepthSwapchainANDROID xrDestroyDepthSwapchainANDROID; // previously initialized
PFN_xrEnumerateDepthSwapchainImagesANDROID xrEnumerateDepthSwapchainImagesANDROID; // previously initialized
PFN_xrEnumerateDepthResolutionsANDROID xrEnumerateDepthResolutionsANDROID; // previously initialized
PFN_xrAcquireDepthSwapchainImagesANDROID xrAcquireDepthSwapchainImagesANDROID; // previously initialized

float tanf(float);

// Inspect system capability
XrSystemProperties properties{XR_TYPE_SYSTEM_PROPERTIES};
XrSystemDepthTrackingPropertiesANDROID depthTrackingProperties{XR_TYPE_SYSTEM_DEPTH_TRACKING_PROPERTIES_ANDROID};
properties.next = &depthTrackingProperties;
CHK_XR(xrGetSystemProperties(instance, systemId, &properties));
if (!depthTrackingProperties.supportsDepthTracking) {
  // depth tracking is not supported.
  return;
}

// Query the supported depth resolution.
XrDepthCameraResolutionANDROID supportedDepthResolution;
uint32_t supportedResolutionCount = 0;
CHK_XR(xrEnumerateDepthResolutionsANDROID(
    session, 1, &supportedResolutionCount, &supportedDepthResolution));

// Define metadata to access the raw and smooth depth along with confidences.
XrDepthSwapchainCreateInfoANDROID swapchainCreateInfo = {
  .type = XR_TYPE_DEPTH_SWAPCHAIN_CREATE_INFO_ANDROID,
  .next = nullptr,
  // Use the resolution supported by the runtime.
  .resolution = supportedDepthResolution,
  .createFlags =
    XR_DEPTH_SWAPCHAIN_CREATE_SMOOTH_DEPTH_IMAGE_BIT_ANDROID |
    XR_DEPTH_SWAPCHAIN_CREATE_SMOOTH_CONFIDENCE_IMAGE_BIT_ANDROID |
    XR_DEPTH_SWAPCHAIN_CREATE_RAW_DEPTH_IMAGE_BIT_ANDROID |
    XR_DEPTH_SWAPCHAIN_CREATE_RAW_CONFIDENCE_IMAGE_BIT_ANDROID,
};

XrDepthSwapchainANDROID depthSwapchain;
CHK_XR(xrCreateDepthSwapchainANDROID(
    session, &swapchainCreateInfo, &depthSwapchain));

// Enumerate depth images.
uint32_t imageCountOutput = 0;
CHK_XR(xrEnumerateDepthSwapchainImagesANDROID(
    depthSwapchain, 0, &imageCountOutput, nullptr));
std::vector<XrDepthSwapchainImageANDROID> depthImages(imageCountOutput);
for (int i = 0; i < imageCountOutput; i++) {
  depthImages[i].type = XR_TYPE_DEPTH_SWAPCHAIN_IMAGE_ANDROID;
}
CHK_XR(xrEnumerateDepthSwapchainImagesANDROID(
  depthSwapchain, imageCountOutput, &imageCountOutput, depthImages.data()));

while (1) {
    // ...
    // For every frame in frame loop
    // ...

    XrFrameState frameState;  // previously returned from xrWaitFrame
    const XrTime time = frameState.predictedDisplayTime;

    XrDepthAcquireInfoANDROID acquireInfo = {
        .type = XR_TYPE_DEPTH_ACQUIRE_INFO_ANDROID,
        .space = stageSpace,
        .displayTime = time
    };
    XrDepthAcquireResultANDROID acquireResult = {
        .type = XR_TYPE_DEPTH_ACQUIRE_RESULT_ANDROID,
    };
    CHK_XR(xrAcquireDepthSwapchainImagesANDROID(
        depthSwapchain, &acquireInfo, &acquireResult));

    // Each value in a depth image corresponds to a point in the real world.
    // The sample code below shows how to find the stageSpace position of
    // the point corresponding to a particular value in the depth image.

    // For this sample code, assume we are using a right handed coordinate system
    // with +X to the right, +Y up and -Z forward.

    XrDepthSwapchainImageANDROID *image =
        &depthImages[acquireResult.acquiredIndex];

    // Assume supported resolution is XR_DEPTH_CAMERA_RESOLUTION_160x160_ANDROID.
    const int imageResolution = 160;
    int imageY = 80; // value in [0, imageResolution)
    int imageX = 80; // value in [0, imageResolution)

    // Get depth value from left eye.
    // A right depth value is obtained with the following expression:
    // depthR = image->rawDepthImage[imageResolution*imageResolution+i*imageResolution+j]
    float depthL = image->rawDepthImage[imageY*imageResolution + imageX];
    XrDepthViewANDROID viewL = acquireResult.views[0];

    float tanL = tanf(viewL.fov.angleLeft);
    float tanR = tanf(viewL.fov.angleRight);
    float tanU = tanf(viewL.fov.angleUp);
    float tanD = tanf(viewL.fov.angleDown);

    float s = (imageX + 0.5f) / (float)imageResolution;
    float t = (imageY + 0.5f) / (float)imageResolution;

    // Calculate the depth camera space position of the point
    // corresponding to this depth value.
    XrVector3f posInCameraSpace;
    posInCameraSpace.z = -depthL;
    posInCameraSpace.x = (tanL + (tanR - tanL)*s)*depthL;
    posInCameraSpace.y = (tanD + (tanU - tanD)*t)*depthL;

    XrPosef depthCameraPoseL = viewL.pose;
    // Transform posInCameraSpace by depthCameraPoseL

    // ...
    // Finish frame loop
    // ...
}

新物件類型

XrDepthSwapchainANDROID

新結構

XrDepthAcquireInfoANDROID
XrDepthAcquireResultANDROID
XrDepthSwapchainCreateInfoANDROID
XrDepthSwapchainImageANDROID
XrDepthViewANDROID
擴充 XrSystemProperties：
- XrSystemDepthTrackingPropertiesANDROID

新列舉

XrDepthCameraResolutionANDROID
XrDepthSwapchainCreateFlagBitsANDROID

新位元遮罩

XrDepthSwapchainCreateFlagsANDROID

新增列舉常數

XR_ANDROID_DEPTH_TEXTURE_EXTENSION_NAME
XR_ANDROID_depth_texture_SPEC_VERSION
擴充 XrObjectType：
- XR_OBJECT_TYPE_DEPTH_SWAPCHAIN_ANDROID
擴充 XrResult：
- XR_ERROR_DEPTH_NOT_AVAILABLE_ANDROID
擴充 XrStructureType：
- XR_TYPE_DEPTH_ACQUIRE_INFO_ANDROID
- XR_TYPE_DEPTH_ACQUIRE_RESULT_ANDROID
- XR_TYPE_DEPTH_SWAPCHAIN_CREATE_INFO_ANDROID
- XR_TYPE_DEPTH_SWAPCHAIN_IMAGE_ANDROID
- XR_TYPE_DEPTH_VIEW_ANDROID
- XR_TYPE_SYSTEM_DEPTH_TRACKING_PROPERTIES_ANDROID

問題

版本記錄

修訂版本 1，2024-09-09 (Levana Chen)
- 擴充功能初始說明