XR_ANDROID_depth_texture OpenXR 扩展

名称字符串

XR_ANDROID_depth_texture

扩展程序类型

实例扩展

已注册的扩展号码

703

修订版本

1

扩展程序和版本依赖项

OpenXR 1.0

上次修改日期

2024-09-11

IP 状态

没有已知的 IP 版权主张。

贡献者

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 的调用次数不得超过 1 次。

有效用法（隐式）

返回代码

成功

  • 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 年 9 月 9 日（Levana Chen）
    • 初始扩展程序说明