XR_ANDROID_spatial_anchor_space

Name String

XR_ANDROID_spatial_anchor_space

拡張機能の種類

インスタンス拡張

登録済みの内線番号

796

リビジョン

1

承認ステータス

未批准

拡張機能とバージョンの依存関係

XR_EXT_spatial_anchor

最終更新日

2025-09-15

IP ステータス

既知の IP 申し立てはありません。

寄与者

YuSheng Chang、Google
Kyle Chen、Google
Levana Chen、Google
Nihav Jain、Google
Spencer Quin、Google

概要

XR_EXT_spatial_anchor 拡張機能で定義されている xrCreateSpatialAnchorEXT 関数を使用すると、アプリは XrSpatialEntityEXT ハンドルで表される空間アンカーを作成できます。一方、この拡張機能では、代わりに XrSpace ハンドルで表される空間アンカーが作成されます。これは、アプリケーションが次のことを行う場合に役立ちます。

  • xrLocateSpaces を使用して、アンカーの位置を取得します。
  • アンカーを基準にして他のスペースを特定する。
  • XR_ANDROID_anchor_sharing_export を使用してアンカーをエクスポートします。
  • アプリがアンカーを配置し、アンカーの場所（仮想コンテンツをアタッチする場所）のみを考慮し、アンカーの作成に使用された XrSpatialContextEXT を介して検出された他のエンティティの他のコンポーネントを考慮しない場合、アプリは空間コンテキストを破棄できます。

この拡張機能で作成されたアンカーは、XR_ANDROID_device_anchor_persistence 拡張機能を使用して永続化することはできません。代わりに、アプリケーションは XR_EXT_spatial_persistence_operations を使用する必要があります。XrPersistedAnchorSpaceInfoANDROID :: anchor が xrCreateSpatialAnchorSpaceANDROID または xrCreateSpatialAnchorSpaceFromIdANDROID を使用して作成された場合、ランタイムは xrPersistAnchorANDROID から XR_ERROR_VALIDATION_FAILURE を返さなければなりません。

空間アンカーの XrSpace を作成する

空間アンカーと空間を作成する

xrCreateSpatialAnchorSpaceANDROID 関数は次のように定義されます。

XrResult xrCreateSpatialAnchorSpaceANDROID(
    XrSession                                   session,
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialAnchorCreateInfoEXT*         createInfo,
    XrSpatialEntityIdEXT*                       anchorEntityId,
    XrSpace*                                    anchorSpace);

パラメータの説明

xrCreateSpatialAnchorSpaceANDROID 関数は、XrSpatialEntityIdEXT と XrSpace ハンドルを出力するアンカーを作成します。xrCreateSpatialAnchorSpaceANDROID の検証要件は、xrCreateSpatialAnchorEXT と同じです。

xrCreateSpatialAnchorSpaceANDROID に渡された XrSpatialContextEXT が XR_SPATIAL_CAPABILITY_ANCHOR_EXT で構成されていない場合、ランタイムは XR_ERROR_VALIDATION_FAILURE を返さなければなりません。

xrCreateSpatialAnchorSpaceANDROID による作成されたアンカーの検出可能性については、xrCreateSpatialAnchorEXT 仕様の最後の段落が適用されます。

有効な使用方法（暗黙的）

  • xrCreateSpatialAnchorSpaceANDROID を呼び出す前に、XR_ANDROID_spatial_anchor_space 拡張機能を有効にする必要があります。
  • session は、有効な XrSession ハンドルでなければなりません。
  • spatialContext は有効な XrSpatialContextEXT ハンドルでなければなりません
  • createInfo は、有効な XrSpatialAnchorCreateInfoEXT 構造体へのポインタでなければなりません
  • anchorEntityId は XrSpatialEntityIdEXT 値へのポインタでなければなりません。
  • anchorSpace は XrSpace ハンドルへのポインタでなければなりません
  • spatialContext は、session から作成、割り当て、または取得されている必要があります。

戻りコード

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失敗

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_POSE_INVALID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_ANCHOR_ATTACHABLE_COMPONENT_NOT_FOUND_ANDROID
  • XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

既存の空間アンカーから XrSpace を作成する

xrCreateSpatialAnchorSpaceFromIdANDROID 関数は次のように定義されます。

XrResult xrCreateSpatialAnchorSpaceFromIdANDROID(
    XrSession                                   session,
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialAnchorSpaceFromIdCreateInfoANDROID* createInfo,
    XrSpace*                                    anchorSpace);

パラメータの説明

空間アンカー エンティティがすでに存在しているシナリオ（永続性など）では、アプリは空間エンティティ ID を指定することで、これらの空間アンカーから XrSpace を作成できます。

xrCreateSpatialAnchorSpaceFromIdANDROID 関数は、XrSpatialAnchorSpaceFromIdCreateInfoANDROID ::entityId フィールドに XrSpatialEntityIdEXT を指定して、XrSpace ハンドルを作成します。

xrCreateSpatialAnchorSpaceFromIdANDROID に渡された XrSpatialContextEXT が XR_SPATIAL_CAPABILITY_ANCHOR_EXT で構成されていない場合、ランタイムは XR_ERROR_VALIDATION_FAILURE を返さなければなりません。

有効な使用方法（暗黙的）

  • xrCreateSpatialAnchorSpaceFromIdANDROID を呼び出す前に、XR_ANDROID_spatial_anchor_space 拡張機能を有効にする必要があります。
  • session は、有効な XrSession ハンドルでなければなりません。
  • spatialContext は有効な XrSpatialContextEXT ハンドルでなければなりません
  • createInfo は、有効な XrSpatialAnchorSpaceFromIdCreateInfoANDROID 構造体へのポインタでなければなりません。
  • anchorSpace は XrSpace ハンドルへのポインタでなければなりません
  • spatialContext は、session から作成、割り当て、または取得されている必要があります。

戻りコード

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失敗

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_ANCHOR_ENTITY_ID_INVALID_ANDROID
  • XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

XrSpatialAnchorSpaceFromIdCreateInfoANDROID 構造体は次のように定義されます。

typedef struct XrSpatialAnchorSpaceFromIdCreateInfoANDROID {
    XrStructureType         type;
    const void*             next;
    XrSpatialEntityIdEXT    anchorEntityId;
} XrSpatialAnchorSpaceFromIdCreateInfoANDROID;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。
  • anchorEntityId は、XrSpace の作成元となる既存の空間アンカーの XrSpatialEntityIdEXT です。

XrSpatialAnchorSpaceFromIdCreateInfoANDROID ::entityId が spatialContext の有効な ID でない場合、ランタイムは XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT を返さなければなりません。

XrSpatialAnchorSpaceFromIdCreateInfoANDROID ::entityId がアンカーの有効なエンティティ ID でない場合、ランタイムは XR_ERROR_SPATIAL_ANCHOR_ENTITY_ID_INVALID_ANDROID を返さなければなりません。

有効な使用方法（暗黙的）

アンカーのライフサイクル

XrSpace ハンドルの親は XrSession です。つまり、アンカーを表す XrSpace ハンドルは、xrCreateSpatialAnchorSpaceFromIdANDROID :: spatialContext または xrCreateSpatialAnchorSpaceANDROID :: spatialContext が破棄された後も有効なままになります。空間エンティティ アンカーを表す XrSpace を作成すると、アプリケーションは XR_SPATIAL_CAPABILITY_ANCHOR_EXT で構成された XrSpatialContextEXT を破棄しながら、xrLocateSpaces で XrSpace を使用してアンカーの最新のポーズを取得し続けることができます。つまり、ランタイムは、アンカーを表す XrSpace ハンドルがすべて破棄されるまで、アンカーを追跡し続ける必要があります。

コード例

空間アンカーを XrSpace として作成する

次のサンプルコードは、空間アンカーを作成して XrSpace として返す方法を示しています。

XrSpatialEntityIdEXT spatialAnchorEntityId;
XrSpace spatialAnchorSpace {XR_NULL_HANDLE}; // XrSpace handle of anchor

// Spatial anchor create info
XrSpatialAnchorCreateInfoEXT createInfo{
  .type = XR_TYPE_SPATIAL_ANCHOR_CREATE_INFO_EXT,
  .baseSpace = localSpace,
  .time = predictedDisplayTime,
  .pose = {{0, 0, 0, 1}, {1, 1, 1}},
};

// Create spatial anchor using the new API
CHK_XR(xrCreateSpatialAnchorSpaceANDROID(session, spatialContext, &createInfo, &spatialAnchorEntityId, &spatialAnchorSpace));

// ...

アンカー エンティティ ID から XrSpace を作成する

次のサンプルコードは、既存のアンカー エンティティ ID から XrSpace を作成する方法を示しています。

XrSpace anchorSpace = XR_NULL_HANDLE;

// Spatial anchor from XrSpace create info
XrSpatialAnchorSpaceFromIdCreateInfoANDROID createInfoFromId{
  .type = XR_TYPE_SPATIAL_ANCHOR_SPACE_FROM_ID_CREATE_INFO_ANDROID,
  .anchorEntityId = spatialAnchorEntityId,
};

// Create XrSpace handle from spatial anchor ID
CHK_XR(xrCreateSpatialAnchorSpaceFromIdANDROID(session, spatialContext, &createInfoFromId, &anchorSpace));

// ...

新しいコマンド

新しい構造

新しい列挙型定数

  • XR_ANDROID_SPATIAL_ANCHOR_SPACE_EXTENSION_NAME
  • XR_ANDROID_spatial_anchor_space_SPEC_VERSION

  • XrResult の拡張:

    • XR_ERROR_SPATIAL_ANCHOR_ENTITY_ID_INVALID_ANDROID

  • XrStructureType の拡張:

    • XR_TYPE_SPATIAL_ANCHOR_SPACE_FROM_ID_CREATE_INFO_ANDROID

問題

変更履歴

  • リビジョン 1、2025-09-15（YuSheng Chang、Kyle Chen）

    • 拡張機能の初期説明。