XR_ANDROID_geospatial_anchor

Name String

XR_ANDROID_geospatial_anchor

拡張機能のタイプ

インスタンス拡張機能

Registered Extension Number

798

リビジョン

1

Ratification Status（批准ステータス）

未批准

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

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 アンカーと Surface アンカーを提供します。地理空間アンカーは、特定の緯度、経度、高度で地球を基準に空間内に配置されるアンカーです。サーフェス アンカーは、地球を基準とするアンカーです。Visual Positioning Service が認識しているサーフェスを基準として、特定の緯度、経度、高度に配置されます。地球に対するランタイムの位置の精度が向上すると、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 にしなければなりません。

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

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

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

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

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。
  • shouldTrackPlanes は、サーフェス ロック アンカーの位置合わせを改善するために、地理空間トラッカーが平面をトラッキングするかどうかを示す XrBool32 です。

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

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

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

地理空間アンカー

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_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 へのポインタです。

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

表面アンカー

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

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 関数は、サーフェス アンカーを作成する非同期オペレーションを開始します。標準の地理空間アンカーとは異なり、ランタイムは正しい高度を特定するために地形データを取得する場合があります。アプリケーションが一度に 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_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);

パラメータの説明

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

戻りコード

成功

  • 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

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

例

地形アンカーを作成する

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.
}

新しいコマンド

新しい構造体

新しい列挙型

新しい列挙型定数

  • 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）

    • 初版ドラフト。