XR_ANDROID_geospatial

Name String

XR_ANDROID_geospatial

擴充功能類型

執行個體擴充功能

擴充功能註冊編號

790

修訂版本

1

批准狀態

未批准

擴充功能和版本依附元件

XR_EXT_future

上次修改日期

2025-12-18

IP 狀態

沒有已知的智慧財產權聲明。

著作人

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

總覽

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

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

權限

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

(防護等級：危險)

檢查系統功能

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_DEFINE_HANDLE(XrGeospatialTrackerANDROID)

xrCreateGeospatialTrackerANDROID 函式的定義如下：

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

參數說明

應用程式可以呼叫 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_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，或指向結構鏈中下一個結構的指標。

有效用途 (隱含)

xrDestroyGeospatialTrackerANDROID 函式的定義如下：

XrResult xrDestroyGeospatialTrackerANDROID(
    XrGeospatialTrackerANDROID                  geospatialTracker);

參數說明

應用程式可以使用 xrDestroyGeospatialTrackerANDROID 函式，釋出地理空間追蹤器和基礎資源。

有效用途 (隱含)

執行緒安全

  • 存取 geospatialTracker 和任何子項控制代碼時，必須從外部同步

傳回代碼

成功

  • XR_SUCCESS

失敗

  • XR_ERROR_CALL_ORDER_INVALID
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

地理空間追蹤器狀態

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

地理空間追蹤器未執行。

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 之間來回變更任意次數。

有效用途 (隱含)

地理空間姿勢

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);

參數說明

xrLocateGeospatialPoseFromPoseANDROID 函式會將 XrGeospatialPoseFromPoseLocateInfoANDROID :: space 中的姿勢轉換為地理空間姿勢。如果 geospatialTracker 的狀態不是 XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID，執行階段「必須」傳回 XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID。如果函式傳回 XR_SUCCESS，geospatialPoseResult 的 XrGeospatialPoseResultANDROID :: poseFlags 欄位會決定哪些輸出欄位有效。如果 XrGeospatialPoseResultANDROID :: poseFlags 中未設定 XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID，應用程式不得讀取 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_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，用於轉換為地理空間姿勢。

有效用途 (隱含)

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 是地理空間姿勢位置的預估水平精確度，定義為指定經緯度周圍 68% 信賴水準圓形的半徑 (以公尺為單位)。
  • verticalAccuracy 是地理空間姿勢位置的預估垂直精確度，定義為指定高度周圍 68% 信心水準的距離 (以公尺為單位)。換句話說，實際海拔高度有 68% 的機率落在 [ XrGeospatialPoseANDROID :: altitude - verticalAccuracy , XrGeospatialPoseANDROID :: altitude \+ verticalAccuracy ] 範圍內。
  • orientationYawAccuracy 是地理空間姿勢方向的預估偏航準確度，定義為指定方向周圍 68% 信賴水準的半徑 (以度為單位)。

有效用途 (隱含)

將地理空間姿勢轉換為 XrPosef

xrLocateGeospatialPoseANDROID 函式的定義如下：

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

參數說明

xrLocateGeospatialPoseANDROID 函式會將地理空間姿勢轉換為 XrSpaceLocation。如果 XrGeospatialTrackerANDROID 未執行，執行階段必須傳回 XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID。如果函式傳回 XR_SUCCESS，location 的 XrSpaceLocation :: locationFlags 欄位會決定哪些輸出欄位有效。

有效用途 (隱含)

傳回代碼

成功

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

有效用途 (隱含)

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。

有效用途 (隱含)

  • 必須先啟用 XR_ANDROID_geospatial 擴充功能，才能呼叫 xrCheckVpsAvailabilityAsyncANDROID
  • 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);

參數說明

有效用途 (隱含)

傳回代碼

成功

  • 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

有效用途 (隱含)

範例

設定地理空間追蹤器

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

新物件類型

新指令

新結構

新列舉

新位元遮罩

新列舉常數

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

    • 初始擴充功能說明。