XR_ANDROID_depth_texture OpenXR 扩展

名称字符串

XR_ANDROID_depth_texture

扩展类型

实例扩展

注册扩展号

703

修订版

1

扩展和版本依赖项

OpenXR 1.0

最后修改日期

2024-09-11

知识产权状态

无已知知识产权声明。

贡献者

Sushant Kulkarni, Google

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 函数获取最新的可用交换链图像索引，例如 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）
    • 初始扩展描述

OpenXR™ 和 OpenXR 徽标是 The Khronos Group Inc. 拥有的商标，并在中国、欧盟、日本和英国注册为商标。