XR_ANDROID_geospatial_anchor

Name String

XR_ANDROID_geospatial_anchor

拡張機能の種類

インスタンス拡張

登録済みの内線番号

798

リビジョン

1

承認ステータス

未批准

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

XR_ANDROID_geospatial
および
XR_EXT_future
および
XR_EXT_spatial_entity
および
XR_EXT_spatial_anchor

最終更新日

2025-10-30

IP ステータス

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

寄与者

John Ullman、Google
Ben King、Google
Nihav Jain、Google
Jared Finder、Google

概要

この拡張機能は、ベースの Geospatial 拡張機能を基盤とする Geospatial Anchor と Surface Anchor を提供します。地理空間アンカーは、特定の緯度、経度、高度で地球を基準として空間に配置されるアンカーです。サーフェス アンカーは、ビジュアル ポジショニング サービスで認識されるサーフェスを基準として、特定の緯度、経度、高度に配置される地球を基準としたアンカーです。地球に対する位置のランタイムの精度が向上すると、それに応じてアンカーのポーズが調整されます。

Geospatial Anchor のシステム機能

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

typedef struct XrSystemGeospatialAnchorPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    uint32_t           maxSurfaceAnchorCount;
} XrSystemGeospatialAnchorPropertiesANDROID;

メンバーの説明

• type は、この構造の XrStructureType です。
• next は、NULL または構造体チェーン内の次の構造体へのポインタです。このような構造体は、コア OpenXR またはこの拡張機能では定義されていません。
• maxSurfaceAnchorCount は、作成可能なサーフェス アンカーの最大数を示す uint32_t です。

アプリは、xrGetSystemProperties を呼び出すときに XrSystemGeospatialAnchorPropertiesANDROID 構造体を XrSystemProperties にチェーンすることで、システムの地理空間アンカー機能を検査できます。

XrSystemGeospatialPropertiesANDROID :: supportsGeospatial が XR_TRUE の場合、maxSurfaceAnchorCount はランタイムがサポートするサーフェス アンカーの最大数を示します。この場合、上限は 0 より大きい値にする必要があります。

XrSystemGeospatialPropertiesANDROID :: supportsGeospatial が XR_TRUE でない場合、maxSurfaceAnchorCount は 0 でなければなりません。

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

• XrSystemGeospatialAnchorPropertiesANDROID を使用する前に、XR_ANDROID_geospatial_anchor 拡張機能を有効にする必要があります。
• type は XR_TYPE_SYSTEM_GEOSPATIAL_ANCHOR_PROPERTIES_ANDROID にする必要があります。
• next は、NULL または構造体チェーン内の次の構造体への有効なポインタでなければなりません。

アンカーの平面トラッキング

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

typedef struct XrGeospatialTrackerAnchorTrackingInfoANDROID {
    XrStructureType    type;
    const void*        next;
    XrBool32           shouldTrackPlanes;
} XrGeospatialTrackerAnchorTrackingInfoANDROID;

メンバーの説明

• type は、この構造の XrStructureType です。
• next は、NULL または構造体チェーン内の次の構造体へのポインタです。
• shouldTrackPlanes は、Geospatial Tracker が平面をトラッキングして、サーフェスにロックされたアンカーの配置を改善するかどうかを示す XrBool32 です。

平面トラッキングを有効にすると、サーフェスロック アンカーの配置を改善できます。

アプリケーションで平面トラッキングを有効にしてサーフェス アンカーのポーズを改善する場合は、xrCreateGeospatialTrackerANDROID を呼び出すときに、XrGeospatialTrackerAnchorTrackingInfoANDROID 構造体を XrGeospatialTrackerCreateInfoANDROID にチェーンできます。

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

• XrGeospatialTrackerAnchorTrackingInfoANDROID を使用する前に、XR_ANDROID_geospatial_anchor 拡張機能を有効にする必要があります。
• type は XR_TYPE_GEOSPATIAL_TRACKER_ANCHOR_TRACKING_INFO_ANDROID にする必要があります。
• next は、NULL または構造体チェーン内の次の構造体への有効なポインタでなければなりません。

Geospatial Anchor

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

XrResult xrCreateGeospatialAnchorANDROID(
    XrSpatialContextEXT                         spatialContext,
    const XrGeospatialAnchorCreateInfoANDROID*  createInfo,
    XrSpatialEntityIdEXT*                       anchorEntityId);

パラメータの説明

• spatialContext は、アンカーを作成する XrSpatialContextEXT です。コンテキストは XR_SPATIAL_CAPABILITY_ANCHOR_EXT 用に構成する必要があります。そうでない場合、ランタイムは XR_ERROR_VALIDATION_FAILURE を返す必要があります。
• createInfo は、アンカー作成パラメータを含む XrGeospatialAnchorCreateInfoANDROID へのポインタです。
• anchorEntityId は、アンカー エンティティ ID が返される XrSpatialEntityIdEXT へのポインタです。

XrGeospatialAnchorCreateInfoANDROID :: geospatialTracker で指定された XrGeospatialTrackerANDROID が XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID 状態でない場合、ランタイムは XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID を返さなければなりません。

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

• xrCreateGeospatialAnchorANDROID を呼び出す前に、XR_ANDROID_geospatial_anchor 拡張機能を有効にする必要があります。
• spatialContext は有効な XrSpatialContextEXT ハンドルでなければなりません
• createInfo は、有効な XrGeospatialAnchorCreateInfoANDROID 構造体へのポインタでなければなりません。
• anchorEntityId は XrSpatialEntityIdEXT 値へのポインタでなければなりません。

戻りコード

成功

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

失敗

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_GEOSPATIAL_COORDINATES_INVALID_ANDROID
• XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID
• 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_VALIDATION_FAILURE

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

typedef struct XrGeospatialAnchorCreateInfoANDROID {
    XrStructureType               type;
    const void*                   next;
    XrGeospatialTrackerANDROID    geospatialTracker;
    XrGeospatialPoseANDROID       geospatialPose;
} XrGeospatialAnchorCreateInfoANDROID;

メンバーの説明

• type は、この構造の XrStructureType です。
• next は、NULL または構造体チェーン内の次の構造体へのポインタです。
• geospatialTracker は、アンカーの作成に使用する XrGeospatialTrackerANDROID です。
• geospatialPose は、アンカーの位置と向きを定義する XrGeospatialPoseANDROID へのポインタです。

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

• XrGeospatialAnchorCreateInfoANDROID を使用する前に、XR_ANDROID_geospatial_anchor 拡張機能を有効にする必要があります。
• type は XR_TYPE_GEOSPATIAL_ANCHOR_CREATE_INFO_ANDROID にする必要があります。
• next は、NULL または構造体チェーン内の次の構造体への有効なポインタでなければなりません。
• geospatialTracker は、有効な XrGeospatialTrackerANDROID ハンドルでなければなりません。
• geospatialPose は、有効な XrGeospatialPoseANDROID 構造体でなければなりません。

サーフェス アンカー

サーフェス アンカーは、地形や屋上などのサーフェスを基準にして配置されるアンカーです。

XrSurfaceAnchorTypeANDROID 列挙型は次のように定義されます。

typedef enum XrSurfaceAnchorTypeANDROID {
    XR_SURFACE_ANCHOR_TYPE_TERRAIN_ANDROID = 1,
    XR_SURFACE_ANCHOR_TYPE_ROOFTOP_ANDROID = 2,
    XR_SURFACE_ANCHOR_TYPE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSurfaceAnchorTypeANDROID;

XrSurfaceAnchorTypeANDROID 列挙型は、アンカーが相対するサーフェスのタイプを指定します。

列挙子には次の値があります。

列挙型の説明

XR_SURFACE_ANCHOR_TYPE_TERRAIN_ANDROID

地面を基準に配置されたアンカーのタイプ。

XR_SURFACE_ANCHOR_TYPE_ROOFTOP_ANDROID

屋上、または建物がない地面を基準に配置されたアンカーのタイプ。

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

XrResult xrCreateSurfaceAnchorAsyncANDROID(
    XrSpatialContextEXT                         spatialContext,
    const XrSurfaceAnchorCreateInfoANDROID*     createInfo,
    XrFutureEXT*                                future);

パラメータの説明

• spatialContext は、アンカーを作成する XrSpatialContextEXT です。
• createInfo は、アンカー作成パラメータを含む XrSurfaceAnchorCreateInfoANDROID へのポインタです。
• future は、非同期オペレーションの結果を保持する XrFutureEXT へのポインタです。

xrCreateSurfaceAnchorAsyncANDROID 関数は、サーフェス アンカーを作成する非同期オペレーションを開始します。標準の Geospatial Anchor とは異なり、ランタイムは地形データを取得して正しい高度を判断する場合があります。アプリケーションが一度に XrSystemGeospatialAnchorPropertiesANDROID :: maxSurfaceAnchorCount を超えるサーフェス アンカーを作成しようとした場合、ランタイムは XR_ERROR_LIMIT_REACHED を返さなければなりません。XrSurfaceAnchorCreateInfoANDROID :: geospatialTracker で指定された XrGeospatialTrackerANDROID が XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID 状態でない場合、ランタイムは XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID を返さなければなりません。指定された位置にサーフェス データがない場合、このオペレーションは非同期的に失敗し、結果 XR_ERROR_SURFACE_ANCHOR_LOCATION_UNSUPPORTED_ANDROID が返される可能性があります。spatialContext に XR_SPATIAL_CAPABILITY_ANCHOR_EXT が構成されていない場合、ランタイムは XR_ERROR_VALIDATION_FAILURE を返す必要があります。

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

• xrCreateSurfaceAnchorAsyncANDROID を呼び出す前に、XR_ANDROID_geospatial_anchor 拡張機能を有効にする必要があります。
• spatialContext は有効な XrSpatialContextEXT ハンドルでなければなりません
• createInfo は、有効な XrSurfaceAnchorCreateInfoANDROID 構造体へのポインタでなければなりません
• future は XrFutureEXT 値へのポインタでなければなりません。

戻りコード

成功

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

失敗

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_GEOSPATIAL_COORDINATES_INVALID_ANDROID
• XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID
• 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_VALIDATION_FAILURE

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

typedef struct XrSurfaceAnchorCreateInfoANDROID {
    XrStructureType               type;
    const void*                   next;
    XrGeospatialTrackerANDROID    geospatialTracker;
    XrSurfaceAnchorTypeANDROID    surfaceAnchorType;
    XrQuaternionf                 eastUpSouthOrientation;
    double                        latitude;
    double                        longitude;
    double                        altitudeRelativeToSurface;
} XrSurfaceAnchorCreateInfoANDROID;

メンバーの説明

• type は、この構造の XrStructureType です。
• next は、NULL または構造体チェーン内の次の構造体へのポインタです。
• geospatialTracker は、使用する XrGeospatialTrackerANDROID です。
• surfaceAnchorType は、アンカーの XrSurfaceAnchorTypeANDROID です。
• eastUpSouthOrientation は、+X=東、+Y=上、+Z=南の座標系に対する向きです。
• latitude は緯度（度単位）で、-89.9 ～+89.9 の範囲で指定します。
• longitude は経度（度単位、-180 ～+180）です。
• altitudeRelativeToSurface は、surfaceAnchorType で指定された地表を基準とした高度（メートル単位）です。

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

• XrSurfaceAnchorCreateInfoANDROID を使用する前に、XR_ANDROID_geospatial_anchor 拡張機能を有効にする必要があります。
• type は XR_TYPE_SURFACE_ANCHOR_CREATE_INFO_ANDROID にする必要があります。
• next は、NULL または構造体チェーン内の次の構造体への有効なポインタでなければなりません。
• geospatialTracker は、有効な XrGeospatialTrackerANDROID ハンドルでなければなりません。
• surfaceAnchorType は、有効な XrSurfaceAnchorTypeANDROID 値でなければなりません。
• latitude は有効な double 値でなければなりません
• longitude は有効な double 値でなければなりません
• altitudeRelativeToSurface は有効な double 値でなければなりません

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

XrResult xrCreateSurfaceAnchorCompleteANDROID(
    XrSpatialContextEXT                         spatialContext,
    XrFutureEXT                                 future,
    XrSurfaceAnchorCreateCompletionANDROID*     completion);

パラメータの説明

• spatialContext は、作成に使用される XrSpatialContextEXT です。
• future は、xrCreateSurfaceAnchorAsyncANDROID によって返される XrFutureEXT です。
• completion は、結果を受け取る XrSurfaceAnchorCreateCompletionANDROID へのポインタです。

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

• xrCreateSurfaceAnchorCompleteANDROID を呼び出す前に、XR_ANDROID_geospatial_anchor 拡張機能を有効にする必要があります。
• spatialContext は有効な XrSpatialContextEXT ハンドルでなければなりません
• completion は、XrSurfaceAnchorCreateCompletionANDROID 構造体へのポインタでなければなりません。

戻りコード

成功

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

失敗

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_FUTURE_INVALID_EXT
• XR_ERROR_FUTURE_PENDING_EXT
• 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_VALIDATION_FAILURE

XrSurfaceAnchorCreateCompletionANDROID 構造体は、非同期サーフェス アンカー作成の結果を保持します。

typedef struct XrSurfaceAnchorCreateCompletionANDROID {
    XrStructureType         type;
    void*                   next;
    XrResult                futureResult;
    XrSpatialEntityIdEXT    anchorEntityId;
} XrSurfaceAnchorCreateCompletionANDROID;

メンバーの説明

• type は、この構造の XrStructureType です。
• next は、NULL または構造体チェーン内の次の構造体へのポインタです。
• futureResult は、作成オペレーションの XrResult です。futureResult が XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID の場合、next チェーンの構造が失敗に関する詳細情報を提供する可能性があります。
• anchorEntityId は、作成されたアンカーの XrSpatialEntityIdEXT です。futureResult が XR_SUCCESS でない場合は XR_NULL_SPATIAL_ENTITY_ID_EXT です。

今後の返品コード

futureResult の値:

成功

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

失敗

• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_SESSION_LOST
• XR_ERROR_OUT_OF_MEMORY
• XR_ERROR_LIMIT_REACHED
• XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID
• XR_ERROR_SURFACE_ANCHOR_LOCATION_UNSUPPORTED_ANDROID
• XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID

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

• XrSurfaceAnchorCreateCompletionANDROID を使用する前に、XR_ANDROID_geospatial_anchor 拡張機能を有効にしなければなりません。
• type は XR_TYPE_SURFACE_ANCHOR_CREATE_COMPLETION_ANDROID にする必要があります。
• next は、NULL または構造体チェーン内の次の構造体への有効なポインタでなければなりません。
• futureResult は有効な XrResult 値でなければなりません。

例

地形アンカーを作成する

PFN_xrCreateSpatialContextAsyncEXT xrCreateSpatialContextAsyncEXT;
PFN_xrCreateSpatialContextCompleteEXT xrCreateSpatialContextCompleteEXT;
PFN_xrCreateSurfaceAnchorAsyncANDROID xrCreateSurfaceAnchorAsyncANDROID;
PFN_xrPollFutureEXT xrPollFutureEXT;
PFN_xrCreateSurfaceAnchorCompleteANDROID xrCreateSurfaceAnchorCompleteANDROID;
XrInstance instance;
XrSession session;
XrGeospatialTrackerANDROID geospatialTracker;

// Create a spatial context
XrSpatialContextEXT spatialContext{};
{
  std::vector<XrSpatialComponentTypeEXT> enabledComponents = {
    XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT,
  };

  XrSpatialCapabilityConfigurationAnchorEXT
       anchorConfig{XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_ANCHOR_EXT};
  anchorConfig.capability = XR_SPATIAL_CAPABILITY_ANCHOR_EXT;
  anchorConfig.enabledComponentCount = enabledComponents.size();
  anchorConfig.enabledComponents = enabledComponents.data();

  std::array<XrSpatialCapabilityConfigurationBaseHeaderEXT*, 1> capabilityConfigs = {
    reinterpret_cast<XrSpatialCapabilityConfigurationBaseHeaderEXT*>(&anchorConfig),
  };

  XrSpatialContextCreateInfoEXT spatialContextCreateInfo{XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT};
  spatialContextCreateInfo.capabilityConfigCount = capabilityConfigs.size();
  spatialContextCreateInfo.capabilityConfigs = capabilityConfigs.data();
  XrFutureEXT createContextFuture;
  CHK_XR(xrCreateSpatialContextAsyncEXT(session, &spatialContextCreateInfo, &createContextFuture));

  // ... wait until future is ready ...

  XrCreateSpatialContextCompletionEXT contextCompletion{XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialContextCompleteEXT(session, createContextFuture, &contextCompletion));
  if (contextCompletion.futureResult != XR_SUCCESS) {
    return;
  }

  spatialContext = contextCompletion.spatialContext;
}

XrSurfaceAnchorCreateInfoANDROID anchorCreateInfo{
    XR_TYPE_SURFACE_ANCHOR_CREATE_INFO_ANDROID};
anchorCreateInfo.surfaceAnchorType = XR_SURFACE_ANCHOR_TYPE_TERRAIN_ANDROID;
anchorCreateInfo.eastUpSouthOrientation = {0, 0, 0, 1};
anchorCreateInfo.latitude = 37.7749;
anchorCreateInfo.longitude = -122.4194;
anchorCreateInfo.altitudeRelativeToSurface = 0;
anchorCreateInfo.geospatialTracker = geospatialTracker;
XrFutureEXT anchorFuture = XR_NULL_FUTURE_EXT;
CHK_XR(xrCreateSurfaceAnchorAsyncANDROID(spatialContext, &anchorCreateInfo, &anchorFuture));

XrFuturePollInfoEXT anchorPollInfo{XR_TYPE_FUTURE_POLL_INFO_EXT};
XrFuturePollResultEXT anchorPollResult{XR_TYPE_FUTURE_POLL_RESULT_EXT};
anchorPollInfo.future = anchorFuture;
anchorPollResult.state = XR_FUTURE_STATE_PENDING_EXT;
while (anchorPollResult.state == XR_FUTURE_STATE_PENDING_EXT) {
  // Do in render loop/state loop.
  CHK_XR(xrPollFutureEXT(instance, &anchorPollInfo, &anchorPollResult));
}

XrSurfaceAnchorCreateCompletionANDROID anchorCompletion{
    XR_TYPE_SURFACE_ANCHOR_CREATE_COMPLETION_ANDROID};
CHK_XR(xrCreateSurfaceAnchorCompleteANDROID(spatialContext, anchorFuture, &anchorCompletion));
if (anchorCompletion.futureResult == XR_SUCCESS) {
  // Use completion.anchorEntityId.
  XrSpatialEntityIdEXT anchorId = anchorCompletion.anchorEntityId;

  // Query in UpdateSnapshot.
}

新しいコマンド

• xrCreateGeospatialAnchorANDROID
• xrCreateSurfaceAnchorAsyncANDROID
• xrCreateSurfaceAnchorCompleteANDROID

新しい構造

• XrGeospatialAnchorCreateInfoANDROID
• XrSurfaceAnchorCreateCompletionANDROID
• XrSurfaceAnchorCreateInfoANDROID

• XrGeospatialTrackerCreateInfoANDROID の拡張:

  • XrGeospatialTrackerAnchorTrackingInfoANDROID

• XrSystemProperties の拡張:

  • XrSystemGeospatialAnchorPropertiesANDROID

新しい列挙型

• XrSurfaceAnchorTypeANDROID

新しい列挙型定数

• XR_ANDROID_GEOSPATIAL_ANCHOR_EXTENSION_NAME
• XR_ANDROID_geospatial_anchor_SPEC_VERSION

• XrResult の拡張:

  • XR_ERROR_SURFACE_ANCHOR_LOCATION_UNSUPPORTED_ANDROID

• XrStructureType の拡張:

  • XR_TYPE_GEOSPATIAL_ANCHOR_CREATE_INFO_ANDROID
  • XR_TYPE_GEOSPATIAL_TRACKER_ANCHOR_TRACKING_INFO_ANDROID
  • XR_TYPE_SURFACE_ANCHOR_CREATE_COMPLETION_ANDROID
  • XR_TYPE_SURFACE_ANCHOR_CREATE_INFO_ANDROID
  • XR_TYPE_SYSTEM_GEOSPATIAL_ANCHOR_PROPERTIES_ANDROID

問題

変更履歴

• リビジョン 1、2025-10-30（Ben King）

  • 初版ドラフト。