Geospatial API 結合 VPS 和 GPS 資料，產生高精確度的地理空間姿勢。只要裝置能夠判斷自身位置，這個 API 就能在任何地方使用：
- 在 GPS 準確度較低的地區 (例如室內空間和人口稠密的都市環境)，API 會透過 VPS 覆蓋範圍產生高精確度姿勢。
- 在沒有或幾乎沒有上方遮蔽物的戶外環境中，Geospatial API 可能可以使用可用的 GPS 位置資料，產生高精確度的地理空間姿勢。
您可以在 AR 工作階段開始前，判斷特定水平位置的 VPS 可用性，並利用這項資訊打造更具體的體驗，例如只在 VPS 可用時顯示「進入 AR」按鈕。
啟用 ARCore API
應用程式必須啟用 ARCore API 才能檢查 VPS 可用性。
啟用 ARCore API 後，不必執行下列操作，就能檢查 VPS 可用性：
- 目前執行中的
Session(在呼叫Session.resume()之前)。 - 設定
GeospatialMode。
檢查應用程式中的 VPS 供應情形
Geospatial API 可用於裝置能夠判斷其位置的任何位置。如果 AR 體驗取決於 VPS 涵蓋範圍，您可以使用 Session.checkVpsAvailabilityAsync() 取得 VpsAvailabilityFuture，這是一個非同步工作，可檢查特定水平位置的 VPS 可用性。取得 VpsAvailabilityFuture 後，您可以透過輪詢或回呼取得結果。
輪詢結果
使用 Future.getState() 取得 Future 的狀態。狀態共有三種：
PENDING：作業尚未完成，因此無法取得任何結果。CANCELLED：Future.cancel()已取消該作業。系統一律不會呼叫任何已註冊的回呼。DONE：作業已完成。使用VpsAvailabilityFuture.getResult()取得結果。
你可以繼續查看 Future.getState()，直到工作完成為止。
Java
// Obtain a VpsAvailabilityFuture and store it somewhere.
VpsAvailabilityFuture future = session.checkVpsAvailabilityAsync(latitude, longitude, null);
// Poll VpsAvailabilityFuture later, for example, in a render loop.
if (future.getState() == FutureState.DONE) {
switch (future.getResult()) {
case AVAILABLE:
// VPS is available at this location.
break;
case UNAVAILABLE:
// VPS is unavailable at this location.
break;
case ERROR_NETWORK_CONNECTION:
// The external service could not be reached due to a network connection error.
break;
// Handle other error states, e.g. ERROR_RESOURCE_EXHAUSTED, ERROR_INTERNAL, ...
}
}
Kotlin
// Obtain a VpsAvailabilityFuture and store it somewhere.
val future = session.checkVpsAvailabilityAsync(latitude, longitude, null)
// Poll VpsAvailabilityFuture later, for example, in a render loop.
if (future.state == FutureState.DONE) {
when (future.result) {
VpsAvailability.AVAILABLE -> {
// VPS is available at this location.
}
VpsAvailability.UNAVAILABLE -> {
// VPS is unavailable at this location.
}
VpsAvailability.ERROR_NETWORK_CONNECTION -> {
// The external service could not be reached due to a network connection error.
}
else -> {
TODO("Handle other error states, e.g. ERROR_RESOURCE_EXHAUSTED, ERROR_INTERNAL, ...")
}
}
}
透過回呼取得結果
您也可以透過回呼取得 Future 的結果。請使用 Session.checkVpsAvailabilityAsync() 並提供 callback。在 Future 具有 DONE 狀態後，系統會在主執行緒上立即呼叫這個 callback。
Java
session.checkVpsAvailabilityAsync(
latitude,
longitude,
result -> {
// Callback is called on the Main thread.
switch (result) {
// Handle the VpsAvailability result as shown above.
// For example, show UI that enables your AR view.
}
});
Kotlin
session.checkVpsAvailabilityAsync(latitude, longitude) { result ->
// Callback is called on the Main thread.
// Handle the VpsAvailability result as shown above.
// For example, show UI that enables your AR view.
TODO("Handle VpsAvailability " + result)
}
取消 Future
使用 Future.cancel() 嘗試取消 Future。由於執行緒並行，取消嘗試可能實際上並未成功。如果這次嘗試成功，Future.cancel() 會傳回 true，否則會傳回 false。
在沒有 VPS 涵蓋範圍的情況下使用 Geospatial API
Geospatial API 也可用於沒有 VPS 涵蓋範圍的區域中。在幾乎沒有或完全沒有障礙物的戶外環境中，GPS 可能足以產生高精確度的姿勢。
後續步驟
- 取得裝置攝影機的地理空間姿勢，藉此判斷使用者裝置的實際位置。