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

Google 的 Kenny Vercaemer

總覽

這個擴充功能可讓應用程式在跨應用程式和裝置工作階段的情況下，為目前使用者在目前裝置上持續、擷取及取消持續錨點。

檢查系統能力

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 呼叫中使用，以保留或取消保留錨點。XrDeviceAnchorPersistenceANDROID 句柄必須最終使用 xrDestroyDeviceAnchorPersistenceANDROID 函式釋放。

有效用法 (隱含)

傳回代碼

成功

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

參數說明

  • handle 是 XrDeviceAnchorPersistenceANDROID。
  • anchorId 是錨點的 XrUuidEXT。
  • persistState 是指向 XrAnchorPersistStateANDROID 的指標，其中會傳回錨點的狀態。
  • 如果找不到錨點 XrUuidEXT，系統會傳回 XR_ERROR_ANCHOR_ID_NOT_FOUND_ANDROID。
  • 如果 anchorId 的已儲存資料尚未準備就緒，系統會傳回 XR_ERROR_PERSISTED_DATA_NOT_READY_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_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;

Enum

說明

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 是已儲存錨點的 XrUuidEXT，可用於建立錨點 XrSpace。

當 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 標誌是 The Khronos Group Inc. 擁有的商標，並已在中國、歐盟、日本和英國註冊為商標。