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 を呼び出すときに XrSystemProperties を XrSystemDeviceAnchorPersistencePropertiesANDROID 構造で拡張することで、システムが空間アンカーを保持できるかどうかを検査できます（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 トラッケーブルでアンカーの永続性がサポートされているかどうかを確認できます。

特定の XrTrackableTypeANDROID が trackableTypes 配列で返されない場合、そのタイプのアンカーを操作するデバイス アンカー永続化関数から 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_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;

列挙型

説明

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

新しいオブジェクト タイプ

新しい列挙型定数

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）
    • 最初の拡張機能の説明