Android XR for OpenXR | Android Developers

Android XR SDK 已推出開發人員預覽版 3，歡迎提供意見！歡迎試用，如有任何問題，請前往支援頁面與我們聯絡。

XR_ANDROID_geospatial

名稱字串

XR_ANDROID_geospatial

擴充功能類型

執行個體擴充功能

擴充功能註冊編號

790

修訂版本

批准狀態

未批准

擴充功能和版本依附元件

XR_EXT_future

上次修改日期

2025-12-18

IP 狀態

未發現任何智慧財產權聲明。

著作人

John Ullman (Google)
Ben King (Google)
Nihav Jain (Google)
Jared Finder (Google)

總覽

這項擴充功能提供 Google 地理空間 API 的地理空間追蹤功能，可提供精確的地理位置和方向，並讓應用程式根據地球放置內容。這項功能會結合動作追蹤、GPS 和其他感應器，以及 Google 的視覺定位系統 (VPS)，VPS 會比較裝置相機拍攝的圖像和街景服務圖像，判斷精確位置和方向。Geospatial API 通常可提供公尺以下的定位準確度 (比 GPS 準確度高出幾個數量級)，以及度以下的方位準確度。

如要順利使用這個擴充功能中的 API (檢查擴充功能支援除外)，應用程式必須透過某種機制 (例如 XR_ANDROID_google_cloud_auth ) 成功設定驗證憑證。如要進一步瞭解設定和錯誤結果，請參閱 Auth 擴充功能的說明文件。

權限

Android 應用程式必須在資訊清單中列出 android.permission.ACCESS_FINE_LOCATION 權限，才能使用這項擴充功能。android.permission.ACCESS_FINE_LOCATION 權限視為危險權限。應用程式必須在執行階段要求權限，才能使用下列函式：

xrCreateGeospatialTrackerANDROID

(防護等級：危險)

檢查系統功能

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，應用程式應避免使用地理空間功能。

有效用量 (隱含)

XR_ANDROID_geospatial 擴充功能必須先啟用，才能使用 XrSystemGeospatialPropertiesANDROID
 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 。應用程式必須確保先前所有 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 函式釋出。

有效用量 (隱含)

必須先啟用 XR_ANDROID_geospatial 擴充功能，才能呼叫 xrCreateGeospatialTrackerANDROID
session must 為有效的 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 函式，釋放地理空間追蹤器和基礎資源。

有效用量 (隱含)

呼叫 xrDestroyGeospatialTrackerANDROID 前，XR_ANDROID_geospatial 擴充功能必須啟用
geospatialTracker must 為有效的 XrGeospatialTrackerANDROID 控制代碼

執行緒安全

geospatialTracker 和任何子項控制代碼的存取權必須從外部同步處理

傳回代碼

成功

XR_SUCCESS

失敗

XR_ERROR_CALL_ORDER_INVALID
XR_ERROR_FUNCTION_UNSUPPORTED
XR_ERROR_HANDLE_INVALID

地理空間追蹤器狀態

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

地理空間追蹤器正在執行且可供使用。

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。
如果 state 為 XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID，則 initializationResult 為錯誤結果，否則為 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變更，所有先前建立的地理空間錨點必須永久停止追蹤，且應由應用程式毀損。狀態可能會在 XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID 和 XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID 之間任意次數來回變更。

有效用量 (隱含)

XR_ANDROID_geospatial 擴充功能必須先啟用，才能使用 XrEventDataGeospatialTrackerStateChangedANDROID
 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 是 XrQuaternionf，定義相對於座標系統的方向，其中 +X=東、+Y=上，而 +Z=南。
latitude 是以度為單位的緯度，介於 -90 到 +90 之間。
longitude 是經度 (以度為單位)，介於 -180 到 +180 之間。
altitude 是高於 WGS84 橢球體的高度 (以公尺為單位)。

XrGeospatialPoseANDROID 結構體代表相對於地球的位置和方向，使用 WGS84 橢球體。

有效用量 (隱含)

XR_ANDROID_geospatial 擴充功能必須先啟用，才能使用 XrGeospatialPoseANDROID
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 轉換為地理空間姿勢

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 中設定，應用程式「不得」讀取 XrGeospatialPoseANDROID :: latitude、XrGeospatialPoseANDROID :: longitude、XrGeospatialPoseANDROID :: altitude、XrGeospatialPoseResultANDROID :: horizontalAccuracy 或 XrGeospatialPoseResultANDROID :: verticalAccuracy XrGeospatialPoseResultANDROID 中的欄位。如果 XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID 未在 XrGeospatialPoseResultANDROID :: poseFlags 中設定，應用程式不得讀取 XrGeospatialPoseANDROID :: eastUpSouthOrientation 或 XrGeospatialPoseResultANDROID :: orientationYawAccuracy。如果未設定 XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID，則不得設定 XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID。

如果精確度低於預期，這可能表示裝置未採用 VPS 定位。應用程式可以指示使用者將裝置對準標誌和建築物，以提升定位準確度。

有效用量 (隱含)

呼叫 xrLocateGeospatialPoseFromPoseANDROID 前，XR_ANDROID_geospatial 擴充功能必須啟用。
geospatialTracker must 為有效的 XrGeospatialTrackerANDROID 控制代碼
locateInfo must 是有效 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% 信賴水準的距離 (以公尺為單位)。換句話說，真實海拔高度有 68% 的機率落在 [ XrGeospatialPoseANDROID :: altitude - verticalAccuracy , XrGeospatialPoseANDROID :: altitude \+ verticalAccuracy ] 範圍內。
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 must 為有效的 XrGeospatialTrackerANDROID 控制代碼
locateInfo must 是有效 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_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 must 為有效的 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 的指標，用於接收結果。

有效用量 (隱含)

呼叫 xrCheckVpsAvailabilityCompleteANDROID 前，必須先啟用 XR_ANDROID_geospatial 擴充功能
session must 為有效的 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

有效用量 (隱含)

必須先啟用 XR_ANDROID_geospatial 擴充功能，才能使用 XrVPSAvailabilityCheckCompletionANDROID
 type 必須為 XR_TYPE_VPS_AVAILABILITY_CHECK_COMPLETION_ANDROID
next 必須是 NULL，或是指向結構體鏈結中下一個結構體的有效指標
futureResult 必須是有效的 XrResult 值
availability 必須是有效的 XrVPSAvailabilityANDROID 值

範例

設定地理空間追蹤器

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

新結構

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)
- 擴充功能的初始說明。