XR_ANDROID_geospatial

Name String

XR_ANDROID_geospatial

拡張機能の種類

インスタンス拡張

登録済みの内線番号

790

リビジョン

1

承認ステータス

未批准

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

XR_EXT_future

最終更新日

2025-12-18

IP ステータス

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

寄与者

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

概要

この拡張機能は、Google の Geospatial API の Geospatial トラッキングを提供します。これにより、正確な地理的位置と向きが提供され、アプリケーションは地球を基準にコンテンツを配置できます。この機能は、モーショントラッキング、GPS、その他のセンサー、Google のビジュアル ポジショニング システム（VPS）を組み合わせて使用します。VPS は、デバイスのカメラからの画像とストリートビューの画像を比較して、正確な位置情報と向きを特定します。Geospatial API は、多くの場合、1 メートル未満の位置精度（GPS よりも桁違いに優れている）と 1 度未満の向きの精度を提供します。

この拡張機能の API を正常に使用するには（拡張機能のサポートを確認する場合を除く）、アプリケーションが XR_ANDROID_google_cloud_auth などのメカニズムを介して認証情報を正常に設定している必要があります。設定とエラー結果の詳細については、認証拡張機能のドキュメントをご覧ください。

権限

この拡張機能を使用するには、Android アプリのマニフェストに android.permission.ACCESS_FINE_LOCATION 権限が記載されている必要があります。android.permission.ACCESS_FINE_LOCATION 権限は危険な権限と見なされます。アプリは、これらの関数を使用するために、実行時に権限をリクエストしなければなりません。

• xrCreateGeospatialTrackerANDROID

（保護レベル: dangerous）

システム機能を検査する

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

typedef struct XrSystemGeospatialPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsGeospatial;
} XrSystemGeospatialPropertiesANDROID;

メンバーの説明

• type は、この構造の XrStructureType です。
• next は、NULL または構造体チェーン内の次の構造体へのポインタです。このような構造体は、コア OpenXR またはこの拡張機能では定義されていません。
• supportsGeospatial は XrBool32 で、現在のシステムが地理空間機能をサポートしているかどうかを示します。

アプリは、xrGetSystemProperties を呼び出すときに XrSystemGeospatialPropertiesANDROID 構造体を XrSystemProperties にチェーンすることで、システムが地理空間機能をサポートしているかどうかを検査できます。

ランタイムが supportsGeospatial に対して XR_FALSE を返す場合、システムは地理空間機能をサポートしていないため、xrCreateGeospatialTrackerANDROID から XR_ERROR_FEATURE_UNSUPPORTED を返す必要があります。supportsGeospatial が XR_FALSE の場合、アプリケーションは地理空間機能の使用を避けるべきです。

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

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

Geospatial Tracker ハンドルを作成する

XR_DEFINE_HANDLE(XrGeospatialTrackerANDROID)

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

XrResult xrCreateGeospatialTrackerANDROID(
    XrSession                                   session,
    const XrGeospatialTrackerCreateInfoANDROID* createInfo,
    XrGeospatialTrackerANDROID*                 geospatialTrackerOutput);

パラメータの説明

• session は、地理空間トラッカーがアクティブになる XrSession です。
• createInfo は、初期の地理空間トラッカー パラメータを指定する XrGeospatialTrackerCreateInfoANDROID 構造体へのポインタです。
• geospatialTrackerOutput は、作成された XrGeospatialTrackerANDROID が返されるハンドルへのポインタです。

アプリケーションは、xrCreateGeospatialTrackerANDROID を呼び出すことで、XrGeospatialTrackerANDROID ハンドルを作成できます。返された XrGeospatialTrackerANDROID ハンドルは、後続の API 呼び出しで使用できます。アプリケーションが必要な権限を取得していない場合、ランタイムは XR_ERROR_PERMISSION_INSUFFICIENT を返さなければなりません。特定の XrSession に対して、一度に存在できる XrGeospatialTrackerANDROID は 1 つだけです。アプリケーションは、この関数を再度呼び出す前に、以前の XrGeospatialTrackerANDROID オブジェクトが破棄されていることを確認しなければなりません。そうでない場合、ランタイムは XR_ERROR_LIMIT_REACHED を返さなければなりません。トラッカーが正常に作成されると、最初は XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID 状態になります。アプリは、トラッカーを使用する前に、状態が XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID に変わるまで待機する必要があります。XrEventDataGeospatialTrackerStateChangedANDROID をご覧ください。アプリが、XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID 状態ではない XrGeospatialTrackerANDROID を、それを必要とする関数に渡した場合、ランタイムは XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID を返さなければなりません。

XrGeospatialTrackerANDROID ハンドルは、最終的に xrDestroyGeospatialTrackerANDROID 関数を介して解放しなければなりません。

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

• xrCreateGeospatialTrackerANDROID を呼び出す前に、XR_ANDROID_geospatial 拡張機能を有効にする必要があります。
• session は、有効な XrSession ハンドルでなければなりません。
• createInfo は、有効な XrGeospatialTrackerCreateInfoANDROID 構造体へのポインタでなければなりません
• geospatialTrackerOutput は XrGeospatialTrackerANDROID ハンドルへのポインタでなければなりません。

戻りコード

成功

• 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_PERMISSION_INSUFFICIENT
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_SESSION_LOST
• XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrGeospatialTrackerCreateInfoANDROID {
    XrStructureType    type;
    const void*        next;
} XrGeospatialTrackerCreateInfoANDROID;

メンバーの説明

• type は、この構造の XrStructureType です。
• next は、NULL または構造体チェーン内の次の構造体へのポインタです。

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

• XrGeospatialTrackerCreateInfoANDROID を使用する前に、XR_ANDROID_geospatial 拡張機能を有効にする必要があります。
• type は XR_TYPE_GEOSPATIAL_TRACKER_CREATE_INFO_ANDROID にする必要があります。
• next は、NULL または構造体チェーン内の次の構造体への有効なポインタである必要があります。XrGeospatialTrackerAnchorTrackingInfoANDROID もご覧ください。

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

XrResult xrDestroyGeospatialTrackerANDROID(
    XrGeospatialTrackerANDROID                  geospatialTracker);

パラメータの説明

• geospatialTracker は、破棄する XrGeospatialTrackerANDROID です。

アプリは、xrDestroyGeospatialTrackerANDROID 関数を使用して、Geospatial Tracker と基盤となるリソースを解放できます。

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

• xrDestroyGeospatialTrackerANDROID を呼び出す前に、XR_ANDROID_geospatial 拡張機能を有効にする必要があります。
• geospatialTracker は、有効な XrGeospatialTrackerANDROID ハンドルでなければなりません。

スレッドセーフ

• geospatialTracker とその子ハンドルへのアクセスは、外部で同期する必要があります。

戻りコード

成功

• XR_SUCCESS

失敗

• XR_ERROR_CALL_ORDER_INVALID
• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_RUNTIME_FAILURE

Geospatial Tracker の状態

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

typedef enum XrGeospatialTrackerStateANDROID {
    XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID = 0,
    XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID = 1,
    XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID = 2,
    XR_GEOSPATIAL_TRACKER_STATE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrGeospatialTrackerStateANDROID;

XrGeospatialTrackerStateANDROID 列挙型は、地理空間トラッカーのさまざまな状態を識別します。

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

列挙型の説明

XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID

Geospatial Tracker が実行されていません。

XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID

Geospatial トラッカーは実行中で、使用可能です。

XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID

Geospatial Tracker の初期化に失敗しました。使用できません。

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

typedef struct XrEventDataGeospatialTrackerStateChangedANDROID {
    XrStructureType                    type;
    const void*                        next;
    XrGeospatialTrackerANDROID         geospatialTracker;
    XrGeospatialTrackerStateANDROID    state;
    XrResult                           initializationResult;
    XrTime                             time;
} XrEventDataGeospatialTrackerStateChangedANDROID;

メンバーの説明

• type は、この構造の XrStructureType です。
• next は、NULL または構造体チェーン内の次の構造体へのポインタです。
• geospatialTracker は、状態が変更された XrGeospatialTrackerANDROID です。
• state は新しい XrGeospatialTrackerStateANDROID です。
• initializationResult は、state が XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID の場合はエラー結果、それ以外の場合は XR_SUCCESS です。
• time は、状態変更が発生した XrTime です。

XrEventDataGeospatialTrackerStateChangedANDROID 構造体は、地理空間トラッカーの状態が変化したときに送信されます。アプリケーションに有効な XrGeospatialTrackerANDROID がある場合、このイベントをポーリングすべきです。トラッカーが最初に受信したイベントには state XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID が含まれます。ランタイムで決定された時間が経過すると、状態は XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID または XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID に変更しなければなりません。この移行には任意の時間がかかります。state が XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID に変更された場合、このトラッカーで最後に受信されたイベントである必要があります。initializationResult フィールドにはエラーコードが格納されます。エラーが発生するまでに数秒かかることがあります。この場合、アプリはトラッカーを破棄する必要があります。state が XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID に変更された場合、以前に作成されたすべての Geospatial アンカーは、トラッキングを完全に停止しなければならず、アプリケーションによって破棄されるべきです。状態は、XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID と XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID の間で任意に何回も切り替わる可能性があります。

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

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

地理空間ポーズ

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

typedef struct XrGeospatialPoseANDROID {
    XrQuaternionf    eastUpSouthOrientation;
    double           latitude;
    double           longitude;
    double           altitude;
} XrGeospatialPoseANDROID;

メンバーの説明

• eastUpSouthOrientation は、+X=東、+Y=上、+Z=南の座標系に対する向きを定義する XrQuaternionf です。
• latitude は緯度（度単位）で、-90 ～+90 の範囲で指定します。
• longitude は経度（度単位、-180 ～+180）です。
• altitude は、WGS84 楕円体からの高度（メートル単位）です。

XrGeospatialPoseANDROID 構造体は、WGS84 楕円体を使用して、地球に対する位置と向きを表します。

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

• XrGeospatialPoseANDROID を使用する前に、XR_ANDROID_geospatial 拡張機能を有効にする必要があります。
• latitude は有効な double 値でなければなりません
• longitude は有効な double 値でなければなりません
• altitude は有効な double 値でなければなりません

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

// Flag bits for XrGeospatialPoseFlagsANDROID
static const XrGeospatialPoseFlagsANDROID XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID = 0x00000001;
static const XrGeospatialPoseFlagsANDROID XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID = 0x00000002;

XrGeospatialPoseFlagBitsANDROID 列挙型は、地理空間ポーズのフラグを指定します。

フラグビットの意味は次のとおりです。

フラグの説明

• XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID - 向きのメンバーに有効なデータが含まれていることを示します。
• XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID - 位置メンバーに有効なデータが含まれていることを示します。

XrGeospatialPoseFlagsANDROID 型は、XrGeospatialPoseFlagBitsANDROID のビットマスクです。

typedef XrFlags64 XrGeospatialPoseFlagsANDROID;

XrPosef を Geospatial Pose に変換する

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

XrResult xrLocateGeospatialPoseFromPoseANDROID(
    XrGeospatialTrackerANDROID                  geospatialTracker,
    const XrGeospatialPoseFromPoseLocateInfoANDROID* locateInfo,
    XrGeospatialPoseResultANDROID*              geospatialPoseResult);

パラメータの説明

• geospatialTracker は、変換に使用する XrGeospatialTrackerANDROID です。
• locateInfo は、クエリ パラメータを含む XrGeospatialPoseFromPoseLocateInfoANDROID へのポインタです。
• geospatialPoseResult は、結果を受け取る XrGeospatialPoseResultANDROID へのポインタです。

xrLocateGeospatialPoseFromPoseANDROID 関数は、XrGeospatialPoseFromPoseLocateInfoANDROID :: space のポーズを地理空間ポーズに変換します。geospatialTracker の状態が XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID でない場合、ランタイムは XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID を返さなければなりません。関数が XR_SUCCESS を返す場合、geospatialPoseResult の XrGeospatialPoseResultANDROID :: poseFlags フィールドによって、有効な出力フィールドが決定されます。XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID が XrGeospatialPoseResultANDROID :: poseFlags に設定されていない場合、アプリは XrGeospatialPoseResultANDROID のフィールド XrGeospatialPoseANDROID :: latitude、XrGeospatialPoseANDROID :: longitude、XrGeospatialPoseANDROID :: altitude、XrGeospatialPoseResultANDROID :: horizontalAccuracy、XrGeospatialPoseResultANDROID :: verticalAccuracy を読み取ってはなりません。XrGeospatialPoseResultANDROID :: poseFlags で XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID が設定されていない場合、アプリは XrGeospatialPoseANDROID :: eastUpSouthOrientation または XrGeospatialPoseResultANDROID :: orientationYawAccuracy を読み取ってはなりません。XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID が設定されていない場合は、XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID も設定しないでください。

精度が想定よりも低い場合は、デバイスが VPS ローカライズを利用していない可能性があります。アプリは、ローカライズを改善するために、デバイスを標識や建物に向けるようユーザーに指示できます。

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

• XR_ANDROID_geospatial 拡張機能は、xrLocateGeospatialPoseFromPoseANDROID を呼び出す前に有効にする必要があります。
• geospatialTracker は、有効な XrGeospatialTrackerANDROID ハンドルでなければなりません。
• locateInfo は、有効な XrGeospatialPoseFromPoseLocateInfoANDROID 構造体へのポインタでなければなりません。
• geospatialPoseResult は、XrGeospatialPoseResultANDROID 構造体へのポインタでなければなりません

戻りコード

成功

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

失敗

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_POSE_INVALID
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_SESSION_LOST
• XR_ERROR_TIME_INVALID
• XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrGeospatialPoseFromPoseLocateInfoANDROID {
    XrStructureType    type;
    const void*        next;
    XrSpace            space;
    XrTime             time;
    XrPosef            pose;
} XrGeospatialPoseFromPoseLocateInfoANDROID;

メンバーの説明

• type は、この構造の XrStructureType です。
• next は、NULL または構造体チェーン内の次の構造体へのポインタです。
• space は、pose が定義されている XrSpace です。
• time は、pose を評価する XrTime です。
• pose は、地理空間ポーズに変換する space の XrPosef です。

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

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

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

typedef struct XrGeospatialPoseResultANDROID {
    XrStructureType                 type;
    void*                           next;
    XrGeospatialPoseFlagsANDROID    poseFlags;
    XrGeospatialPoseANDROID         geospatialPose;
    double                          horizontalAccuracy;
    double                          verticalAccuracy;
    double                          orientationYawAccuracy;
} XrGeospatialPoseResultANDROID;

メンバーの説明

• type は、この構造の XrStructureType です。
• next は、NULL または構造体チェーン内の次の構造体へのポインタです。
• poseFlags は、ポーズ コンポーネントの有効性を示す XrGeospatialPoseFlagsANDROID のビットマスクです。
• geospatialPose は、結果の XrGeospatialPoseANDROID です。
• horizontalAccuracy は、Geospatial のポーズ位置の推定水平精度です。指定された緯度と経度を中心とする 68% 信頼区間の円の半径（メートル単位）として定義されます。
• verticalAccuracy は、Geospatial のポーズ位置の推定垂直精度です。指定された高度の周囲の 68% 信頼区間の距離（メートル単位）として定義されます。つまり、真の高度が [ XrGeospatialPoseANDROID :: altitude - verticalAccuracy , XrGeospatialPoseANDROID :: altitude \+ verticalAccuracy ] の範囲内にある確率は 68% です。
• orientationYawAccuracy は、Geospatial のポーズの向きの推定ヨー精度です。指定された向きを中心とする 68% の信頼水準の半径（度単位）として定義されます。

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

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

Geospatial Pose を XrPosef に変換する

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

XrResult xrLocateGeospatialPoseANDROID(
    XrGeospatialTrackerANDROID                  geospatialTracker,
    const XrGeospatialPoseLocateInfoANDROID*    locateInfo,
    XrSpaceLocation*                            location);

パラメータの説明

• geospatialTracker は、変換に使用する XrGeospatialTrackerANDROID です。
• locateInfo は、クエリ パラメータを含む XrGeospatialPoseLocateInfoANDROID へのポインタです。
• location は、結果のポーズを受け取る XrSpaceLocation へのポインタです。

xrLocateGeospatialPoseANDROID 関数は、地理空間ポーズを XrSpaceLocation に変換します。XrGeospatialTrackerANDROID が実行されていない場合、ランタイムは XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID を返さなければなりません。関数が XR_SUCCESS を返した場合、location の XrSpaceLocation :: locationFlags フィールドによって、どの出力フィールドが有効かが決まります。

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

• xrLocateGeospatialPoseANDROID を呼び出す前に、XR_ANDROID_geospatial 拡張機能を有効にする必要があります。
• geospatialTracker は、有効な XrGeospatialTrackerANDROID ハンドルでなければなりません。
• locateInfo は、有効な XrGeospatialPoseLocateInfoANDROID 構造体へのポインタでなければなりません
• location は XrSpaceLocation 構造体へのポインタでなければなりません。

戻りコード

成功

• 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_POSE_INVALID
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_SESSION_LOST
• XR_ERROR_TIME_INVALID
• XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrGeospatialPoseLocateInfoANDROID {
    XrStructureType            type;
    const void*                next;
    XrSpace                    space;
    XrTime                     time;
    XrGeospatialPoseANDROID    geospatialPose;
} XrGeospatialPoseLocateInfoANDROID;

メンバーの説明

• type は、この構造の XrStructureType です。
• next は、NULL または構造体チェーン内の次の構造体へのポインタです。
• space は、結果のポーズが表される XrSpace です。
• time は、ポーズを配置する XrTime です。
• geospatialPose は、変換する XrGeospatialPoseANDROID です。

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

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

VPS の提供状況

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

typedef enum XrVPSAvailabilityANDROID {
    XR_VPS_AVAILABILITY_UNAVAILABLE_ANDROID = 1,
    XR_VPS_AVAILABILITY_AVAILABLE_ANDROID = 2,
    XR_VPSAVAILABILITY_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrVPSAvailabilityANDROID;

XrVPSAvailabilityANDROID 列挙型は、VPS の可用性を示します。

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

列挙型の説明

XR_VPS_AVAILABILITY_UNAVAILABLE_ANDROID

指定された場所の近くでは VPS を利用できません。

XR_VPS_AVAILABILITY_AVAILABLE_ANDROID

指定された場所の近くで VPS を利用できる。

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

XrResult xrCheckVpsAvailabilityAsyncANDROID(
    XrSession                                   session,
    double                                      latitude,
    double                                      longitude,
    XrFutureEXT*                                future);

パラメータの説明

• session は、チェックに使用する XrSession です。
• latitude は緯度（度単位）です。
• longitude は経度（度単位）です。
• future は、非同期オペレーションの結果を保持する XrFutureEXT へのポインタです。

ビジュアル ポジショニング サービス（VPS）の可用性は、特定の場所で地理空間の精度を向上させるために VPS を使用できるかどうかを示します。

xrCheckVpsAvailabilityAsyncANDROID 関数は、指定された場所での VPS の可用性の非同期チェックを開始します。この関数を呼び出すために XrGeospatialTrackerANDROID は必要ありません。このオペレーションの結果を使用して、作成するかどうかを決定できます。アプリケーションが必要な権限を取得していない場合、ランタイムは XR_ERROR_PERMISSION_INSUFFICIENT を返さなければなりません。

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

• xrCheckVpsAvailabilityAsyncANDROID を呼び出す前に、XR_ANDROID_geospatial 拡張機能を有効にする必要があります。
• session は、有効な XrSession ハンドルでなければなりません。
• latitude は有効な double 値でなければなりません
• longitude は有効な double 値でなければなりません
• future は XrFutureEXT 値へのポインタでなければなりません。

戻りコード

成功

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

失敗

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_GEOSPATIAL_COORDINATES_INVALID_ANDROID
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_SESSION_LOST
• XR_ERROR_VALIDATION_FAILURE

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

XrResult xrCheckVpsAvailabilityCompleteANDROID(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrVPSAvailabilityCheckCompletionANDROID*    completion);

パラメータの説明

• session は、チェックに使用される XrSession です。
• future は、xrCheckVpsAvailabilityAsyncANDROID によって返される XrFutureEXT です。
• completion は、結果を受け取る XrVPSAvailabilityCheckCompletionANDROID へのポインタです。

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

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

戻りコード

成功

• 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_RUNTIME_FAILURE
• XR_ERROR_SESSION_LOST
• XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrVPSAvailabilityCheckCompletionANDROID {
    XrStructureType             type;
    void*                       next;
    XrResult                    futureResult;
    XrVPSAvailabilityANDROID    availability;
} XrVPSAvailabilityCheckCompletionANDROID;

メンバーの説明

• type は、この構造の XrStructureType です。
• next は、NULL または構造体チェーン内の次の構造体へのポインタです。
• futureResult は、チェック オペレーションの XrResult です。futureResult が XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID の場合、next チェーンの構造が失敗に関する詳細情報を提供する可能性があります。
• availability は、結果の XrVPSAvailabilityANDROID です。futureResult が XR_SUCCESS でない限り、アプリはこのフィールドを読み取ってはなりません。

今後の返品コード

futureResult の値:

成功

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

失敗

• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_SESSION_LOST
• XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID

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

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

例

Geospatial Tracker を設定する

PFN_xrCheckVpsAvailabilityAsyncANDROID xrCheckVpsAvailabilityAsyncANDROID;
PFN_xrPollFutureEXT xrPollFutureEXT;
PFN_xrCheckVpsAvailabilityCompleteANDROID xrCheckVpsAvailabilityCompleteANDROID;
PFN_xrCreateGeospatialTrackerANDROID xrCreateGeospatialTrackerANDROID;
XrInstance instance = XR_NULL_HANDLE;
XrSystemId systemId = XR_NULL_SYSTEM_ID;
XrSession session = XR_NULL_HANDLE;
double lat = 37.422, lng = -122.084;

// Check for support.
XrSystemGeospatialPropertiesANDROID geospatialSystemProperties{
    XR_TYPE_SYSTEM_GEOSPATIAL_PROPERTIES_ANDROID};
XrSystemProperties systemProperties{XR_TYPE_SYSTEM_PROPERTIES,
                                    &geospatialSystemProperties};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (!geospatialSystemProperties.supportsGeospatial) {
  return;
}

// Check VPS Availability.
XrFutureEXT future = XR_NULL_FUTURE_EXT;
CHK_XR(xrCheckVpsAvailabilityAsyncANDROID(session, lat, lng, &future));

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

XrVPSAvailabilityCheckCompletionANDROID vpsCompletion{
    XR_TYPE_VPS_AVAILABILITY_CHECK_COMPLETION_ANDROID};
CHK_XR(xrCheckVpsAvailabilityCompleteANDROID(session, future, &vpsCompletion));
if (vpsCompletion.futureResult == XR_SUCCESS) {
  if (vpsCompletion.availability == XR_VPS_AVAILABILITY_UNAVAILABLE_ANDROID) {
    // Visual Positioning Service is not available. Accuracy of positions and
    // orientations from Geospatial APIs are expected to be lower at this location.
  } else {
    // Visual Positioning Service is available. Higher accuracy of position and
    // orientation is achievable at this location.
  }
}

// Create Geospatial Tracker.
XrGeospatialTrackerCreateInfoANDROID createInfo{
    XR_TYPE_GEOSPATIAL_TRACKER_CREATE_INFO_ANDROID};
XrGeospatialTrackerANDROID geospatialTracker = XR_NULL_HANDLE;
CHK_XR(xrCreateGeospatialTrackerANDROID(session, &createInfo, &geospatialTracker));

// In application main event loop:
while (true) {
  XrEventDataBuffer event = {XR_TYPE_EVENT_DATA_BUFFER};
  if (xrPollEvent(instance, &event) != XR_SUCCESS) {
    continue;
  }
  switch (event.type) {
    case XR_TYPE_EVENT_DATA_GEOSPATIAL_TRACKER_STATE_CHANGED_ANDROID:
      const XrEventDataGeospatialTrackerStateChangedANDROID& eventData =
          *reinterpret_cast<XrEventDataGeospatialTrackerStateChangedANDROID*>(&event);
      switch (eventData.state) {
        case XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID:
          // Destroy existing anchors, if any.
          break;
        case XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID:
          // Start adding content.
          break;
        case XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID:
          // Handle eventData.initializationResult error result.
          break;
      }
  }
}

Geospatial Pose API を呼び出す

PFN_xrLocateGeospatialPoseFromPoseANDROID xrLocateGeospatialPoseFromPoseANDROID;
PFN_xrLocateGeospatialPoseANDROID xrLocateGeospatialPoseANDROID;

XrGeospatialTrackerANDROID geospatialTracker;

// Get pose from view space.
XrSpace viewSpace;
XrPosef identityPose = {{0,0,0,1},{0,0,0}};
XrGeospatialPoseFromPoseLocateInfoANDROID poseGetInfo{
    XR_TYPE_GEOSPATIAL_POSE_FROM_POSE_LOCATE_INFO_ANDROID};
XrGeospatialPoseResultANDROID poseResult{
    XR_TYPE_GEOSPATIAL_POSE_RESULT_ANDROID};
poseGetInfo.space = viewSpace;
poseGetInfo.pose = identityPose;
poseGetInfo.time = 0;  // Next frame timestamp.
CHK_XR(xrLocateGeospatialPoseFromPoseANDROID(geospatialTracker, &poseGetInfo, &poseResult));
if ((poseResult.poseFlags & XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID) &&
    (poseResult.poseFlags & XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID)) {
  // poseResult.geospatialPose is valid.
}

// Convert Geospatial pose to an XrSpaceLocation.
XrGeospatialPoseLocateInfoANDROID poseLocateInfo{
    XR_TYPE_GEOSPATIAL_POSE_LOCATE_INFO_ANDROID};
XrSpaceLocation location{XR_TYPE_SPACE_LOCATION};
poseLocateInfo.space = viewSpace;
poseLocateInfo.geospatialPose = poseResult.geospatialPose;
poseLocateInfo.time = 0; // Next frame timestamp.
CHK_XR(xrLocateGeospatialPoseANDROID(geospatialTracker, &poseLocateInfo, &location));
if ((location.locationFlags & XR_SPACE_LOCATION_ORIENTATION_VALID_BIT) &&
    (location.locationFlags & XR_SPACE_LOCATION_POSITION_VALID_BIT)) {
  // location.pose is valid.
}

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

• XrGeospatialTrackerANDROID

新しいコマンド

• xrCheckVpsAvailabilityAsyncANDROID
• xrCheckVpsAvailabilityCompleteANDROID
• xrCreateGeospatialTrackerANDROID
• xrDestroyGeospatialTrackerANDROID
• xrLocateGeospatialPoseANDROID
• xrLocateGeospatialPoseFromPoseANDROID

新しい構造

• XrEventDataGeospatialTrackerStateChangedANDROID
• XrGeospatialPoseANDROID
• XrGeospatialPoseFromPoseLocateInfoANDROID
• XrGeospatialPoseLocateInfoANDROID
• XrGeospatialPoseResultANDROID
• XrGeospatialTrackerCreateInfoANDROID
• XrVPSAvailabilityCheckCompletionANDROID

• XrSystemProperties の拡張:

  • XrSystemGeospatialPropertiesANDROID

新しい列挙型

• XrGeospatialPoseFlagBitsANDROID
• XrGeospatialTrackerStateANDROID
• XrVPSAvailabilityANDROID

新しいビットマスク

• XrGeospatialPoseFlagsANDROID

新しい列挙型定数

• XR_ANDROID_GEOSPATIAL_EXTENSION_NAME
• XR_ANDROID_geospatial_SPEC_VERSION

• XrObjectType の拡張:

  • XR_OBJECT_TYPE_GEOSPATIAL_TRACKER_ANDROID

• XrResult の拡張:

  • XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID
  • XR_ERROR_GEOSPATIAL_COORDINATES_INVALID_ANDROID
  • XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID

• XrStructureType の拡張:

  • XR_TYPE_EVENT_DATA_GEOSPATIAL_TRACKER_STATE_CHANGED_ANDROID
  • XR_TYPE_GEOSPATIAL_POSE_FROM_POSE_LOCATE_INFO_ANDROID
  • XR_TYPE_GEOSPATIAL_POSE_LOCATE_INFO_ANDROID
  • XR_TYPE_GEOSPATIAL_POSE_RESULT_ANDROID
  • XR_TYPE_GEOSPATIAL_TRACKER_CREATE_INFO_ANDROID
  • XR_TYPE_SYSTEM_GEOSPATIAL_PROPERTIES_ANDROID
  • XR_TYPE_VPS_AVAILABILITY_CHECK_COMPLETION_ANDROID

問題

変更履歴

• リビジョン 1、2025 年 12 月 18 日（Ben King）

  • 拡張機能の初期説明。