XR_ANDROID_depth_texture OpenXR 擴充功能

名稱字串

XR_ANDROID_depth_texture

擴充功能類型

執行個體擴充功能

已註冊的擴充號碼

703

修訂版本

1

擴充功能和版本依附元件

OpenXR 1.0

上次修改日期

2024-09-11

IP 狀態

沒有已知的 IP 版權聲明。

貢獻者

Google 的 Sushant Kulkarni

Cairn Overturf，Google

Spencer Quin，Google

Levana Chen，Google

總覽

這個擴充功能可讓應用程式在建立時，要求頭戴式裝置周圍實境環境的深度地圖，以及查詢支援的深度解析度。

這個擴充功能旨在提供遮蔽、命中測試和其他使用精確場景幾何圖形的特定工作，例如假臉偵測，以便公開原始和平滑深度。

檢查系統能力

XrSystemDepthTrackingPropertiesANDROID 結構的定義如下：

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

成員說明

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

應用程式可在呼叫 xrGetSystemProperties 時，使用 XrSystemDepthTrackingPropertiesANDROID 結構來擴充 XrSystemProperties，藉此檢查系統是否具備深度追蹤功能。

有效用法 (隱含)

查詢深度解析

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 會列舉目前工作階段支援的深度解析度。深度解析度應依執行階段偏好設定由高至低排序。應用程式應使用支援的最高偏好設定，以便取得最佳效能和品質。

有效用法 (隱含)

傳回代碼

成功

  • 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_SIZE_INSUFFICIENT

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

參數說明

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

傳回的深度交換鏈結句柄「可能」會在後續的 API 呼叫中使用。XrDepthSwapchainANDROID 句柄必須最終使用 xrDestroyDepthSwapchainANDROID 函式釋放。

有效用法 (隱含)

傳回代碼

成功

  • 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

XrDepthSwapchainCreateInfoANDROID 結構的定義如下：

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

成員說明

當 XrDepthSwapchainCreateInfoANDROID 結構體傳遞至 xrCreateDepthSwapchainANDROID 時，會為 XrDepthSwapchainANDROID 提供建立選項。

有效用法 (隱含)

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;

xrDestroyDepthSwapchainANDROID 函式定義如下：

XrResult xrDestroyDepthSwapchainANDROID(
    XrDepthSwapchainANDROID                     swapchain);

參數說明

xrDestroyDepthSwapchainANDROID 函式會刪除深度交換鏈結。

有效用法 (隱含)

執行緒安全性

  • 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 相似。

有效用法 (隱含)

傳回代碼

成功

  • 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_SIZE_INSUFFICIENT

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 中的深度影像，分配方式如呼叫 xrCreateDepthSwapchainANDROID 時的 XrDepthSwapchainCreateInfoANDROID::resolution 和 XrDepthSwapchainCreateInfoANDROID::createFlags 所述。針對每張深度影像：

有效用法 (隱含)

xrAcquireDepthSwapchainImagesANDROID 函式定義如下：

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

參數說明

應用程式可以使用 xrAcquireDepthSwapchainImagesANDROID 函式，將最新可用的 Swapchain 圖像索引 (例如 XrDepthAcquireResultANDROID::acquiredIndex) 取得，並將其放入由 xrEnumerateDepthSwapchainImagesANDROID 列舉的 XrDepthSwapchainImageANDROID 陣列中。傳回的 XrDepthAcquireResultANDROID 也包含其他資訊，例如解讀深度資料所需的視野和姿勢。在下次呼叫 xrAcquireDepthSwapchainImagesANDROID 之前，您可以安全地從圖片陣列中已取得的資料槽讀取資料。

在工作階段中，每對相應的 xrBeginFrame 和 xrEndFrame 呼叫之間，最多只能呼叫 xrAcquireDepthSwapchainImagesANDROID 一次。

有效用法 (隱含)

傳回代碼

成功

  • 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_DEPTH_NOT_AVAILABLE_ANDROID
  • XR_ERROR_CALL_ORDER_INVALID
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_TIME_INVALID

XrDepthAcquireInfoANDROID 結構的定義如下：

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

成員說明

有效用法 (隱含)

XrDepthAcquireResultANDROID 結構的定義如下：

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

成員說明

有效用法 (隱含)

XrDepthViewANDROID 結構的定義如下：

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

成員說明

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

有效用法 (隱含)

深度追蹤程式碼範例

以下程式碼範例說明如何擷取深度影像。

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

// 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,
  .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,

  // Use the resolution supported by the runtime.
  .resolution = supportedDepthResolution,
};

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,
        .time = time};
    XrDepthAcquireResultANDROID acquireResult = {
        .type = XR_TYPE_DEPTH_ACQUIRE_RESULT_ANDROID,
    };
    CHK_XR(xrAcquireDepthImagesANDROID(
        depthSwapchain, &acquireInfo, &acquireResult));

    // Each value in a depth image corresponds to a point in the real world.
    // The sample code in this section 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.acquireIndex];

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

    // Get depth value from left eye.
    // A right depth value would be 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 = (tanB + (tanU - tanB)*t)*depthL;

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

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

新物件類型

新的列舉常數

XrObjectType 列舉已擴充以下項目：

  • XR_OBJECT_TYPE_DEPTH_SWAPCHAIN_ANDROID

XrResult 列舉已擴充以下項目：

  • XR_ERROR_DEPTH_NOT_AVAILABLE_ANDROID

XrStructureType 列舉已擴充以下項目：

  • XR_TYPE_DEPTH_SWAPCHAIN_CREATE_INFO_ANDROID
  • XR_TYPE_DEPTH_VIEW_ANDROID
  • XR_TYPE_DEPTH_ACQUIRE_INFO_ANDROID
  • XR_TYPE_DEPTH_ACQUIRE_RESULT_ANDROID
  • XR_TYPE_SYSTEM_DEPTH_TRACKING_PROPERTIES_ANDROID
  • XR_TYPE_DEPTH_SWAPCHAIN_IMAGE_ANDROID

新列舉

新結構

新函式

問題

版本記錄

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