XR_ANDROID_depth_texture
Name String
XR_ANDROID_depth_texture
擴充功能類型
執行個體擴充功能
擴充功能註冊編號
703
修訂版本
1
批准狀態
未批准
擴充功能和版本依附元件
上次修改日期
2024-09-11
IP 狀態
沒有已知的智慧財產權聲明。
著作人
Sushant Kulkarni, Google
Cairn Overturf, Google
Spencer Quin, Google
Levana Chen, Google
總覽
透過這項擴充功能,應用程式可要求取得頭戴式裝置周圍真實環境的深度圖,並在建立時查詢支援的深度解析度。
這項擴充功能旨在提供原始和流暢的深度資訊,用於遮蔽、點擊測試和其他特定工作,例如仿冒臉部偵測,這些工作需要準確的場景幾何圖形。
注意事項
深度圖是由執行階段產生,並使用 XrDepthSwapchainANDROID 與應用程式共用。在應用程式的生命週期內,執行階段「不得」變更透過 xrEnumerateDepthResolutionsANDROID 傳回的深度圖像解析度。
權限
這項擴充功能會提供降取樣的深度紋理,降低個人識別資訊 (PII) 相關疑慮。Android 應用程式必須在資訊清單中列出 android.permission.SCENE_UNDERSTANDING_FINE 權限,因為這項擴充功能會公開環境的幾何圖形。android.permission.SCENE_UNDERSTANDING_FINE 權限視為危險權限。應用程式必須在執行階段要求權限,才能使用下列函式:
(防護等級:危險)
檢查系統功能
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_tresolutions數量的指標,或在resolutionCapacityInput不足的情況下指向所需容量的指標。resolutions是 XrDepthCameraResolutionANDROID 陣列的指標,但如果resolutionCapacityInput是0,則可以是NULL。- 如要進一步瞭解如何擷取必要的
resolutions大小,請參閱「緩衝區大小參數」一節。
xrEnumerateDepthResolutionsANDROID 會列舉目前工作階段支援的深度解析度。深度解析度應按照執行階段偏好設定,由高到低排序。應用程式應使用支援的最高偏好設定,以獲得最佳效能和品質。
在工作階段的生命週期內,執行階段必須一律從這個列舉傳回相同的緩衝區內容。
有效用途 (隱含)
- 必須先啟用
XR_ANDROID_depth_texture擴充功能,才能呼叫 xrEnumerateDepthResolutionsANDROID -
session「必須」是有效的 XrSession 控制代碼 -
resolutionCountOutput「必須」是指向uint32_t值的指標 - 如果
resolutionCapacityInput不是0,resolutions必須是指向resolutionCapacityInputXrDepthCameraResolutionANDROID 值陣列的指標
傳回代碼
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_SIZE_INSUFFICIENTXR_ERROR_VALIDATION_FAILURE
XrDepthCameraResolutionANDROID 列舉會說明建立 XrDepthSwapchainANDROID 時支援的深度解析度。
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。 - 只有在建立 swapchain 時為
createInfo設定對應的位元,執行階段才應建立深度信賴度圖片。
傳回的深度 Swapchain 控制代碼可能會在後續的 API 呼叫中使用。XrDepthSwapchainANDROID 控制代碼必須最終透過 xrDestroyDepthSwapchainANDROID 函式釋放。
有效用途 (隱含)
- 呼叫 xrCreateDepthSwapchainANDROID 前,必須啟用
XR_ANDROID_depth_texture擴充功能 -
session「必須」是有效的 XrSession 控制代碼 -
createInfo「必須」是指向有效 XrDepthSwapchainCreateInfoANDROID 結構的指標 -
swapchain「必須」是指向 XrDepthSwapchainANDROID 控制代碼的指標
傳回代碼
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FEATURE_UNSUPPORTEDXR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_PERMISSION_INSUFFICIENTXR_ERROR_RUNTIME_FAILUREXR_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 結構會提供 XrDepthSwapchainANDROID 的建立選項,並傳遞至 xrCreateDepthSwapchainANDROID。
有效用途 (隱含)
- 必須先啟用
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「必須」是有效的 XrDepthSwapchainANDROID 控制代碼
執行緒安全
- 存取
swapchain和任何子項控制代碼時,必須從外部同步
傳回代碼
XR_SUCCESS
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_RUNTIME_FAILURE
存取深度紋理
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 類似。
在交換鏈的生命週期內,執行階段必須一律從這個列舉傳回相同的緩衝區內容。
有效用途 (隱含)
- 必須先啟用
XR_ANDROID_depth_texture擴充功能,才能呼叫 xrEnumerateDepthSwapchainImagesANDROID -
depthSwapchain「必須」是有效的 XrDepthSwapchainANDROID 控制代碼 -
depthImageCountOutput「必須」是指向uint32_t值的指標 - 如果
depthImageCapacityInput不是0,depthImages必須是指向depthImageCapacityInputXrDepthSwapchainImageANDROID 結構陣列的指標
傳回代碼
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_SIZE_INSUFFICIENTXR_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 的值,並由 XrDepthSwapchainCreateInfoANDROID ::
resolution在呼叫 xrCreateDepthSwapchainANDROID 時設定。舉例來說,如果 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。
- 如果執行階段仍在使用先前取得的交換鏈圖片,則可能會遭到封鎖。
- 如果在 xrBeginFrame 之前或 xrEndFrame 之後呼叫 xrAcquireDepthSwapchainImagesANDROID,執行階段必須傳回
XR_ERROR_CALL_ORDER_INVALID。 - 如果每個影格呼叫 xrAcquireDepthSwapchainImagesANDROID 超過一次,也就是在執行中的工作階段,呼叫 xrBeginFrame 後沒有相關聯的 xrEndFrame,執行階段必須傳回
XR_ERROR_LIMIT_REACHED。 - 如果環境深度資料尚未提供,執行階段可能會傳回
XR_ERROR_DEPTH_NOT_AVAILABLE_ANDROID。如果發生這種情況,應用程式應在後續影格再次呼叫 xrAcquireDepthSwapchainImagesANDROID。
有效用途 (隱含)
- 必須先啟用
XR_ANDROID_depth_texture擴充功能,才能呼叫 xrAcquireDepthSwapchainImagesANDROID -
depthSwapchain「必須」是有效的 XrDepthSwapchainANDROID 控制代碼 -
acquireInfo「必須」是指向有效 XrDepthAcquireInfoANDROID 結構的指標 -
acquireResult「必須」是指向 XrDepthAcquireResultANDROID 結構的指標
傳回代碼
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_CALL_ORDER_INVALIDXR_ERROR_DEPTH_NOT_AVAILABLE_ANDROIDXR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_TIME_INVALIDXR_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
// ...
}
新物件類型
新指令
- xrAcquireDepthSwapchainImagesANDROID
- xrCreateDepthSwapchainANDROID
- xrDestroyDepthSwapchainANDROID
- xrEnumerateDepthResolutionsANDROID
- xrEnumerateDepthSwapchainImagesANDROID
新結構
- XrDepthAcquireInfoANDROID
- XrDepthAcquireResultANDROID
- XrDepthSwapchainCreateInfoANDROID
- XrDepthSwapchainImageANDROID
- XrDepthViewANDROID
新列舉
新位元遮罩
新列舉常數
XR_ANDROID_DEPTH_TEXTURE_EXTENSION_NAMEXR_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_ANDROIDXR_TYPE_DEPTH_ACQUIRE_RESULT_ANDROIDXR_TYPE_DEPTH_SWAPCHAIN_CREATE_INFO_ANDROIDXR_TYPE_DEPTH_SWAPCHAIN_IMAGE_ANDROIDXR_TYPE_DEPTH_VIEW_ANDROIDXR_TYPE_SYSTEM_DEPTH_TRACKING_PROPERTIES_ANDROID
問題
版本記錄
修訂版本 1,2024-09-09 (Levana Chen)
- 初始擴充功能說明