XR_ANDROID_device_anchor_persistence OpenXR 扩展

名称字符串

XR_ANDROID_device_anchor_persistence

扩展程序类型

实例扩展

已注册的扩展号码

458

修订版本

1

扩展程序和版本依赖项

XR_EXT_uuid和XR_ANDROID_trackables

上次修改日期

2024-10-10

IP 状态

没有已知的 IP 版权主张。

创作贡献者

Nihav Jain，Google

Levana Chen，Google

Spencer Quin，Google

Kenny Vercaemer，Google

概览

借助此扩展程序，应用可以在当前设备上为当前用户跨应用和设备会话保留、检索和取消保留锚点。

检查系统功能

XrSystemDeviceAnchorPersistencePropertiesANDROID 结构的定义如下：

typedef struct XrSystemDeviceAnchorPersistencePropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsAnchorPersistence;
} XrSystemDeviceAnchorPersistencePropertiesANDROID;

成员说明

  • type 是此结构的 XrStructureType。
  • next 是 NULL 或指向结构链中下一个结构的指针。核心 OpenXR 或此扩展中未定义任何此类结构。
  • supportsAnchorPersistence 是一个 XrBool32，用于指示当前系统是否支持空间锚点的锚点持久性。

应用可以在调用 xrGetSystemProperties 时使用 XrSystemDeviceAnchorPersistencePropertiesANDROID 结构扩展 XrSystemProperties，以检查系统是否能够保留空间锚点（请参阅 xrCreateAnchorSpaceANDROID）。对于受支持的可跟踪锚点，应用可以使用 xrEnumerateSupportedPersistenceAnchorTypesANDROID 查询受支持的类型。

如果针对 supportsAnchorPersistence 返回 XR_FALSE，则设备锚点持久性函数（对空间锚点进行操作）将返回 XR_ERROR_FEATURE_UNSUPPORTED。

有效用法（隐式）

xrEnumerateSupportedPersistenceAnchorTypesANDROID 函数的定义如下：

XrResult xrEnumerateSupportedPersistenceAnchorTypesANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    trackableTypeCapacityInput,
    uint32_t*                                   trackableTypeCountOutput,
    XrTrackableTypeANDROID*                     trackableTypes);

参数说明

  • session 是创建 XrDeviceAnchorPersistenceANDROID 的 XrSession。
  • trackableTypeCapacityInput 是 trackableTypes 的容量，或 0 以检索所需的容量。
  • trackableTypeCountOutput 是指向数组计数的指针，如果 trackableTypeCapacityInput 不足，则是指向所需容量的指针。
  • trackableTypes 是指向 XrTrackableTypeANDROID 数组的指针，但如果 trackableTypeCapacityInput 为 0，则可以为 NULL。
  • 如需详细了解如何检索所需的 trackableTypes 大小，请参阅缓冲区大小参数部分。

应用可以使用 xrEnumerateSupportedPersistenceAnchorTypesANDROID 检查其他 XrTrackableTypeANDROID 可跟踪对象是否支持锚点持久性。

如果 trackableTypes 数组中未返回给定的 XrTrackableTypeANDROID，则设备锚点持久性函数（对该类型的锚点进行操作）将返回 XR_ERROR_FEATURE_UNSUPPORTED。

有效用法（隐式）

返回代码

成功

  • XR_SUCCESS

失败

  • XR_ERROR_SYSTEM_INVALID
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_FUNCTION_UNSUPPORTED

创建设备锚点持久性句柄

XrDeviceAnchorPersistenceANDROID 是一个句柄，表示保留和跟踪保留的锚点所需的资源。

XR_DEFINE_HANDLE(XrDeviceAnchorPersistenceANDROID)

xrCreateDeviceAnchorPersistenceANDROID 函数的定义如下：

XrResult xrCreateDeviceAnchorPersistenceANDROID(
    XrSession                                   session,
    const XrDeviceAnchorPersistenceCreateInfoANDROID* createInfo,
    XrDeviceAnchorPersistenceANDROID*           outHandle);

参数说明

应用可以通过调用 xrCreateDeviceAnchorPersistenceANDROID 创建 XrDeviceAnchorPersistenceANDROID 句柄。XrDeviceAnchorPersistenceANDROID 可在后续 API 调用中用于保留或取消保留锚点。最终必须使用 xrDestroyDeviceAnchorPersistenceANDROID 函数释放 XrDeviceAnchorPersistenceANDROID 句柄。

有效用法（隐式）

返回代码

成功

  • 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_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED

XrDeviceAnchorPersistenceCreateInfoANDROID 结构的定义如下：

typedef struct XrDeviceAnchorPersistenceCreateInfoANDROID {
    XrStructureType    type;
    void*              next;
} XrDeviceAnchorPersistenceCreateInfoANDROID;

成员说明

  • type 是此结构的 XrStructureType。
  • next 是 NULL 或指向结构链中下一个结构的指针。核心 OpenXR 或此扩展中未定义任何此类结构。

XrDeviceAnchorPersistenceCreateInfoANDROID 结构在传递给 xrCreateDeviceAnchorPersistenceANDROID 时，会为 XrDeviceAnchorPersistenceANDROID 提供创建选项。

有效用法（隐式）

xrDestroyDeviceAnchorPersistenceANDROID 函数的定义如下：

XrResult xrDestroyDeviceAnchorPersistenceANDROID(
    XrDeviceAnchorPersistenceANDROID            handle);

参数说明

xrDestroyDeviceAnchorPersistenceANDROID 函数会销毁设备锚点持久性句柄。

有效用法（隐式）

线程安全

  • 对 handle 和任何子句柄的访问必须在外部进行同步

返回代码

成功

  • XR_SUCCESS

失败

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

保留锚点

xrPersistAnchorANDROID 函数的定义如下：

XrResult xrPersistAnchorANDROID(
    XrDeviceAnchorPersistenceANDROID            handle,
    const XrPersistedAnchorSpaceInfoANDROID*    persistedInfo,
    XrUuidEXT*                                  anchorIdOutput);

参数说明

应用可以通过调用 xrPersistAnchorANDROID 请求将锚点持久化。应用不得假定成功返回值意味着锚点会立即持久化。应用应使用 xrGetAnchorPersistStateANDROID 检查返回的锚点 XrUuidEXT 的持久化状态。应用可以使用 xrUnpersistAnchorANDROID 取消保留锚点。

  • 如果在调用时未跟踪锚点，则会返回 XR_ERROR_ANCHOR_NOT_TRACKING_ANDROID。
  • 如果持久化数据尚未准备就绪，则会返回 XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID。
  • 将锚点加入持久化队列后，系统会返回 XR_SUCCESS。

有效用法（隐式）

返回代码

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失败

  • XR_ERROR_ANCHOR_NOT_TRACKING_ANDROID
  • 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_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED

XrPersistedAnchorSpaceInfoANDROID 结构的定义如下： 

typedef struct XrPersistedAnchorSpaceInfoANDROID {
    XrStructureType    type;
    void*              next;
    XrSpace            anchor;
} XrPersistedAnchorSpaceInfoANDROID;

成员说明

  • type 是此结构的 XrStructureType。
  • next 是 NULL 或指向结构链中下一个结构的指针。核心 OpenXR 或此扩展中未定义任何此类结构。
  • anchor 是之前由 xrCreateAnchorSpaceANDROID 创建的锚点 XrSpace，用于持久化。

有效用法（隐式）

xrGetAnchorPersistStateANDROID 函数的定义如下： 

XrResult xrGetAnchorPersistStateANDROID(
    XrDeviceAnchorPersistenceANDROID            handle,
    const XrUuidEXT*                            anchorId,
    XrAnchorPersistStateANDROID*                persistState);

参数说明

有效用法（隐式）

返回代码

成功

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

XrAnchorPersistStateANDROID 枚举的定义如下： 

typedef enum XrAnchorPersistStateANDROID {
    XR_ANCHOR_PERSIST_STATE_PERSIST_NOT_REQUESTED_ANDROID = 0,
    XR_ANCHOR_PERSIST_STATE_PERSIST_PENDING_ANDROID = 1,
    XR_ANCHOR_PERSIST_STATE_PERSISTED_ANDROID = 2
} XrAnchorPersistStateANDROID;

枚举

说明

XR_ANCHOR_PERSIST_STATE_PERSIST_NOT_REQUESTED_ANDROID

应用尚未请求将锚点保留。

XR_ANCHOR_PERSIST_STATE_PERSIST_PENDING_ANDROID

系统已请求保留锚点，但尚未保留。

XR_ANCHOR_PERSIST_STATE_PERSISTED_ANDROID

运行时已成功保留锚点。

基于持久化数据创建锚点

xrCreatePersistedAnchorSpaceANDROID 函数的定义如下：

XrResult xrCreatePersistedAnchorSpaceANDROID(
    XrDeviceAnchorPersistenceANDROID            handle,
    const XrPersistedAnchorSpaceCreateInfoANDROID* createInfo,
    XrSpace*                                    anchorOutput);

参数说明

应用可以使用相同的 XrUuidEXT 调用 xrCreatePersistedAnchorSpaceANDROID，从之前保留的锚点创建 XrSpace 锚点。这是创建锚点的另一种方法，如 XR_ANDROID_trackables 中所定义。

  • 如果找不到锚点 XrUuidEXT，则返回 XR_ERROR_ANCHOR_ID_NOT_FOUND_ANDROID。

有效用法（隐式）

返回代码

成功

  • 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_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_ANCHOR_ID_NOT_FOUND_ANDROID
  • XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID

XrPersistedAnchorSpaceCreateInfoANDROID 结构的定义如下：

typedef struct XrPersistedAnchorSpaceCreateInfoANDROID {
    XrStructureType    type;
    void*              next;
    XrUuidEXT          anchorId;
} XrPersistedAnchorSpaceCreateInfoANDROID;

成员说明

  • type 是此结构的 XrStructureType。
  • next 是 NULL 或指向结构链中下一个结构的指针。核心 OpenXR 或此扩展中未定义任何此类结构。
  • anchorId 是要从中创建锚点 XrSpace 的持久锚点的 XrUuidEXT。

XrPersistedAnchorSpaceCreateInfoANDROID 结构在传递给 xrCreateDeviceAnchorPersistenceANDROID 时，会为锚点提供创建选项。

有效用法（隐式）

枚举持久性锚点

xrEnumeratePersistedAnchorsANDROID 函数的定义如下： 

XrResult xrEnumeratePersistedAnchorsANDROID(
    XrDeviceAnchorPersistenceANDROID            handle,
    uint32_t                                    anchorIdsCapacityInput,
    uint32_t*                                   anchorIdsCountOutput,
    XrUuidEXT*                                  anchorIds);

参数说明

  • handle 是 XrDeviceAnchorPersistenceANDROID。
  • anchorIdsCapacityInput 是 anchorIds 数组的容量，或 0，表示请求检索所需的容量。
  • anchorIdsCountOutput 是指向已写入 anchorIds 的计数的指针，或者指向所需容量的指针（如果 anchorIdsCapacityInput 不足）。
  • anchorIds 是指向 XrUuidEXT 结构数组的指针。如果 anchorIdsCapacityInput 为 0，则 可以为 NULL。
  • 如需详细了解如何检索所需的 anchorIds 大小，请参阅缓冲区大小参数部分。

应用可以通过调用 xrEnumeratePersistedAnchorsANDROID 来枚举当前的所有持久锚点。anchorIds 将存储已持久化锚点的 UUID，最多可存储数组的容量。如果容量不足，应用无法保证返回哪些锚点。

有效用法（隐式）

返回代码

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失败

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

取消持久化锚点

xrUnpersistAnchorANDROID 函数的定义如下： 

XrResult xrUnpersistAnchorANDROID(
    XrDeviceAnchorPersistenceANDROID            handle,
    const XrUuidEXT*                            anchorId);

参数说明

应用可以通过调用 xrUnpersistAnchorANDROID 并传递要取消持久化的锚点的 XrUuidEXT 来取消持久化锚点。

  • 如果持久化数据尚未准备就绪，则会返回 XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID。
  • 如果找不到锚点 XrUuidEXT，则返回 XR_ERROR_ANCHOR_ID_NOT_FOUND_ANDROID。

有效用法（隐式）

返回代码

成功

  • 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_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_ANCHOR_ID_NOT_FOUND_ANDROID
  • XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID

锚点持久性的示例代码

以下示例代码演示了如何检查系统功能、保留、枚举和取消保留锚点，以及如何基于保留的锚点 XrUuidEXT 创建锚点。

XrSession session; // previously initialized
XrSpace anchor; // previously initialized

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrEnumerateSupportedPersistenceAnchorTypesANDROID xrEnumerateSupportedPersistenceAnchorTypesANDROID; // previously initialized
PFN_xrCreateDeviceAnchorPersistenceANDROID xrCreateDeviceAnchorPersistenceANDROID; // previously initialized
PFN_xrDestroyDeviceAnchorPersistenceANDROID xrDestroyDeviceAnchorPersistenceANDROID; // previously initialized
PFN_xrPersistAnchorANDROID xrPersistAnchorANDROID; // previously initialized
PFN_xrGetAnchorPersistStateANDROID xrGetAnchorPersistStateANDROID; // previously initialized
PFN_xrCreatePersistedAnchorSpaceANDROID xrCreatePersistedAnchorSpaceANDROID; // previously initialized
PFN_xrEnumeratePersistedAnchorsANDROID xrEnumeratePersistedAnchorsANDROID; // previously initialized
PFN_xrUnpersistAnchorANDROID xrUnpersistAnchorANDROID; // previously initialized

// Create a device anchor persistence handle
XrDeviceAnchorPersistenceCreateInfoANDROID persistenceHandleCreateInfo;
persistenceHandleCreateInfo.type = XR_TYPE_DEVICE_ANCHOR_PERSISTENCE_CREATE_INFO_ANDROID;
persistenceHandleCreateInfo.next = nullptr;

XrDeviceAnchorPersistenceANDROID persistenceHandle;
CHK_XR(xrCreateDeviceAnchorPersistenceANDROID(session, &persistenceHandleCreateInfo, &persistenceHandle));

/// Persist an anchor
XrPersistedAnchorSpaceInfo anchorSpaceInfo;
anchorSpaceInfo.type = XR_TYPE_PERSISTED_ANCHOR_SPACE_INFO_ANDROID;
anchorSpaceInfo.next = nullptr;
anchorSpaceInfo.anchor = anchor;

XrUuidEXT anchorId;
do {
  XrResult result = xrPersistAnchorANDROID(
    persistenceHandle, &anchorSpaceInfo, &anchorId);
} while (result == XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID ||
         result == XR_ERROR_ANCHOR_NOT_TRACKING_ANDROID);
if (result != XR_SUCCESS) {
  // Handle errors
}


// ... Update loop ...
// Poll for anchor persist state to confirm if it was successfully persisted
XrAnchorPersistStateANDROID persistState;
CHK_XR(xrGetAnchorPersistStateANDROID(persistenceHandle, &anchorId, &persistState));
if (persistState == XR_ANCHOR_PERSIST_STATE_PERSISTED_ANDROID)  {
  // The anchor was persisted successfully
}

// Enumerate all persisted anchors
uint32_t anchorCountOutput = 0;
std::vector<XrUuidEXT> allAnchors;

CHK_XR(xrEnumeratePersistedAnchorsANDROID(
  persistenceHandle,
  anchorCountOutput,
  &anchorCountOutput,
  nullptr
));
allAnchors.resize(anchorCountOutput, XR_NULL_HANDLE);

// Fetch the actual anchors in an appropriately resized array.
CHK_XR(xrEnumeratePersistedAnchorsANDROID(
  persistenceHandle,
  anchorCountOutput,
  &anchorCountOutput,
  allAnchors.data()
));

// Creating an anchor from a previously persisted anchor using its UUID
XrTime updateTime; // Time used for the current frame's simulation update.
XrUuidEXT anchorId = allAnchors[0];

XrPersistedAnchorSpaceCreateInfo createInfo;
createInfo.type = XR_TYPE_PERSISTED_ANCHOR_CREATE_INFO_ANDROID;
createInfo.next = nullptr;
createInfo.anchorId = anchorId;

XrSpace anchorSpace = XR_NULL_HANDLE;
CHK_XR(xrCreatePersistedAnchorSpaceANDROID(
  persistenceHandle,
  &createInfo,
  &anchorSpace
));

// The anchor was found and retrieved from the local device successfully.
XrSpaceLocation anchorLocation = { XR_TYPE_SPACE_LOCATION };
CHK_XR(xrLocateSpace(anchorSpace, appSpace, updateTime, &anchorLocation));
XrPosef pose = anchorLocation.pose;

// Unpersist the anchor
do {
  XrResult result = xrUnpersistAnchorANDROID(persistenceHandle, &anchorId);
} while (result == XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID);
if (result != XR_SUCCESS) {
  // Handle errors
}

// Once app is done with all persistence related tasks
CHK_XR(xrDestroySpace(anchorSpace));
CHK_XR(xrDestroyDeviceAnchorPersistenceANDROID(persistenceHandle));

新的对象类型

新的枚举常量

XrObjectType 枚举已扩展为：

  • XR_OBJECT_TYPE_DEVICE_ANCHOR_PERSISTENCE_ANDROID

XrResult 枚举已扩展为：

  • XR_ERROR_ANCHOR_ID_NOT_FOUND_ANDROID
  • XR_ERROR_ANCHOR_ALREADY_PERSISTED_ANDROID
  • XR_ERROR_ANCHOR_NOT_TRACKING_ANDROID
  • XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID

XrStructureType 枚举已扩展为：

  • XR_TYPE_PERSISTED_ANCHOR_ANDROID
  • XR_TYPE_PERSISTED_ANCHOR_SPACE_CREATE_INFO_ANDROID
  • XR_TYPE_PERSISTED_ANCHOR_SPACE_INFO_ANDROID
  • XR_TYPE_DEVICE_ANCHOR_PERSISTENCE_CREATE_INFO_ANDROID

新枚举

新结构

新函数

问题

版本历史记录

  • 修订版 1，2024 年 10 月 10 日 (Kenny Vercaemer)
    • 初始扩展程序说明

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