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

概览

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

注意 ：

权限

Android 应用必须在其清单中列出 android.permission.SCENE_UNDERSTANDING 权限，因为此扩展程序依赖于 XR_ANDROID_trackables 并公开环境的几何图形。android.permission.SCENE_UNDERSTANDING 权限被视为危险权限。应用必须在运行时请求权限才能使用以下函数：
xrCreateDeviceAnchorPersistenceANDROID
（保护级别：/dangerous）

检查系统功能

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。

有效用法（隐式）

• 必须先启用 XR_ANDROID_device_anchor_persistence 扩展程序，然后才能使用 XrSystemDeviceAnchorPersistencePropertiesANDROID
• type 必须为 XR_TYPE_SYSTEM_DEVICE_ANCHOR_PERSISTENCE_PROPERTIES_ANDROID
• next 必须为 NULL，或者指向结构链中的下一个结构的有效指针

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_ANDROID_device_anchor_persistence 扩展程序，然后才能调用 xrEnumerateSupportedPersistenceAnchorTypesANDROID
• instance 必须是有效的 XrInstance 句柄
• trackableTypeCountOutput 必须是指向 uint32_t 值的指针
• 如果 trackableTypeCapacityInput 不为 0, trackableTypes，则必须是指向 trackableTypeCapacityInput XrTrackableTypeANDROID 值数组的指针

返回代码

成功

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

参数说明

• session 是创建 XrDeviceAnchorPersistenceANDROID 的 XrSession。
• createInfo 是包含 XrDeviceAnchorPersistenceANDROID 参数的 XrDeviceAnchorPersistenceCreateInfoANDROID。
• outHandle 是指向返回创建的 XrDeviceAnchorPersistenceANDROID 的句柄的指针。

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

有效用法（隐式）

• 必须先启用 XR_ANDROID_device_anchor_persistence 扩展程序，然后才能调用 xrCreateDeviceAnchorPersistenceANDROID
• session 必须是有效的 XrSession 句柄
• createInfo 必须是指向有效 XrDeviceAnchorPersistenceCreateInfoANDROID 结构的指针
• outHandle 必须是指向 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 提供创建选项。

有效用法（隐式）

• 必须先启用 XR_ANDROID_device_anchor_persistence 扩展程序，然后才能使用 XrDeviceAnchorPersistenceCreateInfoANDROID
• type 必须为 XR_TYPE_DEVICE_ANCHOR_PERSISTENCE_CREATE_INFO_ANDROID
• next 必须为 NULL，或者指向结构链中的下一个结构的有效指针

xrDestroyDeviceAnchorPersistenceANDROID 函数的定义如下：

XrResult xrDestroyDeviceAnchorPersistenceANDROID(
    XrDeviceAnchorPersistenceANDROID            handle);

参数说明

• handle 是之前由 xrCreateDeviceAnchorPersistenceANDROID 创建的 XrDeviceAnchorPersistenceANDROID 句柄。

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

有效用法（隐式）

• 必须先启用 XR_ANDROID_device_anchor_persistence 扩展程序，然后才能调用 xrDestroyDeviceAnchorPersistenceANDROID
• handle 必须是有效的 XrDeviceAnchorPersistenceANDROID 句柄

线程安全

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

返回代码

成功

• XR_SUCCESS

失败

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID

保留锚点

xrPersistAnchorANDROID 函数的定义如下：

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

参数说明

• handle 是 XrDeviceAnchorPersistenceANDROID。
• persistedInfo 是包含锚点持久性参数的 XrPersistedAnchorSpaceInfoANDROID。
• anchorIdOutput 是指向 XrUuidEXT 的指针，其中会返回持久锚点的 UUID。

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

• 如果在调用时未跟踪锚点，则会返回 XR_ERROR_ANCHOR_NOT_TRACKING_ANDROID。
• 将锚点加入持久化队列后，系统会返回 XR_SUCCESS。

有效用法（隐式）

• 必须先启用 XR_ANDROID_device_anchor_persistence 扩展程序，然后才能调用 xrPersistAnchorANDROID
• handle 必须是有效的 XrDeviceAnchorPersistenceANDROID 句柄
• persistedInfo 必须是指向有效 XrPersistedAnchorSpaceInfoANDROID 结构的指针
• anchorIdOutput 必须是指向 XrUuidEXT 结构的指针

返回代码

成功

• 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，用于持久化。

有效用法（隐式）

• 必须先启用 XR_ANDROID_device_anchor_persistence 扩展程序，然后才能使用 XrPersistedAnchorSpaceInfoANDROID
• type 必须为 XR_TYPE_PERSISTED_ANCHOR_SPACE_INFO_ANDROID
• next 必须为 NULL，或者指向结构链中的下一个结构的有效指针
• anchor 必须是有效的 XrSpace 句柄

xrGetAnchorPersistStateANDROID 函数的定义如下：

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

参数说明

• handle 是 XrDeviceAnchorPersistenceANDROID。
• anchorId 是锚点的 XrUuidEXT。
• persistState 是指向 XrAnchorPersistStateANDROID 的指针，其中会返回锚点的状态。
• 如果找不到锚点 XrUuidEXT，则会返回 XR_ERROR_ANCHOR_ID_NOT_FOUND_ANDROID。
• 如果 anchorId 的持久化数据尚未准备就绪，则会返回 XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID。

有效用法（隐式）

• 必须先启用 XR_ANDROID_device_anchor_persistence 扩展程序，然后才能调用 xrGetAnchorPersistStateANDROID
• handle 必须是有效的 XrDeviceAnchorPersistenceANDROID 句柄
• anchorId 必须是指向有效 XrUuidEXT 结构的指针
• persistState 必须是指向 XrAnchorPersistStateANDROID 值的指针

返回代码

成功

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

参数说明

• handle 是 XrDeviceAnchorPersistenceANDROID。
• createInfo 是包含锚点创建参数的 XrPersistedAnchorSpaceCreateInfoANDROID。
• anchorOutput 是指向返回新锚点空间的 XrSpace 的指针。

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

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

有效用法（隐式）

• 必须先启用 XR_ANDROID_device_anchor_persistence 扩展程序，然后才能调用 xrCreatePersistedAnchorSpaceANDROID
• handle 必须是有效的 XrDeviceAnchorPersistenceANDROID 句柄
• createInfo 必须是指向有效 XrPersistedAnchorSpaceCreateInfoANDROID 结构的指针
• anchorOutput 必须是指向 XrSpace 句柄的指针

返回代码

成功

• 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 时，会为锚点提供创建选项。

有效用法（隐式）

• 必须先启用 XR_ANDROID_device_anchor_persistence 扩展，然后才能使用 XrPersistedAnchorSpaceCreateInfoANDROID
• type 必须为 XR_TYPE_PERSISTED_ANCHOR_SPACE_CREATE_INFO_ANDROID
• next 必须为 NULL，或者指向结构链中的下一个结构的有效指针

枚举持久性锚点

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_ANDROID_device_anchor_persistence 扩展程序，然后才能调用 xrEnumeratePersistedAnchorsANDROID
• handle 必须是有效的 XrDeviceAnchorPersistenceANDROID 句柄
• anchorIdsCountOutput 必须是指向 uint32_t 值的指针
• 如果 anchorIdsCapacityInput 不是 0, anchorIds，则必须是指向 anchorIdsCapacityInput XrUuidEXT 结构数组的指针

返回代码

成功

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

参数说明

• handle 是 XrDeviceAnchorPersistenceANDROID。
• anchorId 是要取消持久化的锚点的 XrUuidEXT。

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

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

有效用法（隐式）

• 必须先启用 XR_ANDROID_device_anchor_persistence 扩展程序，然后才能调用 xrUnpersistAnchorANDROID
• handle 必须是有效的 XrDeviceAnchorPersistenceANDROID 句柄
• anchorId 必须是指向有效 XrUuidEXT 结构的指针

返回代码

成功

• 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;
CHK_XR(xrPersistAnchorANDROID(persistenceHandle, &anchorSpaceInfo, &anchorId));

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

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

新的对象类型

• XrDeviceAnchorPersistenceANDROID

新的枚举常量

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

新枚举

• XrAnchorPersistStateANDROID

新结构

• XrDeviceAnchorPersistenceCreateInfoANDROID
• XrPersistedAnchorSpaceCreateInfoANDROID
• XrPersistedAnchorSpaceInfoANDROID
• XrSystemDeviceAnchorPersistencePropertiesANDROID

新函数

• xrEnumerateSupportedPersistenceAnchorTypesANDROID
• xrCreateDeviceAnchorPersistenceANDROID
• xrDestroyDeviceAnchorPersistenceANDROID
• xrPersistAnchorANDROID
• xrGetAnchorPersistStateANDROID
• xrCreatePersistedAnchorSpaceANDROID
• xrEnumeratePersistedAnchorsANDROID
• xrUnpersistAnchorANDROID

问题

版本历史记录

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