地理空間 API 結合 VPS 和 GPS 資料,產生高精確度的地理空間姿勢。您可在裝置能夠判斷其位置的任何位置使用此 API:
- 如果是 GPS 精確度偏低的區域 (例如室內空間和人口密集的都市環境),API 就會仰賴 VPS 覆蓋範圍來產生高精確度姿勢。
- 在幾乎沒有高架障礙的戶外環境中,地理空間 API 或許能夠使用現有的 GPS 位置資料,製作出精準的地理空間姿勢。
你可以在 AR 工作階段開始前以特定水平位置判斷 VPS 適用情形,並使用這項功能打造更精準的體驗,舉例來說,只有在 VPS 可用時才會顯示「進入 AR」按鈕。
啟用 ARCore API
您的應用程式必須啟用 ARCore API,才能檢查 VPS 可用性。
啟用 ARCore API 後,即可檢查 VPS 可用性,但這不會:
- 目前執行中的
ArSession
(在呼叫ArSession_resume()
之前)。 - 設定
ArGeospatialMode
。
檢查應用程式中的 VPS 可用性
地理空間 API 可用於裝置判斷其位置的任何位置。如果您的 AR 體驗取決於 VPS 涵蓋率,可以使用 ArSession_checkVpsAvailabilityAsync()
取得 ArVpsAvailabilityFuture
,這項非同步工作會在特定水平位置檢查 VPS 可用性。
取得 ArVpsAvailabilityFuture
後,您可以透過輪詢或回呼取得相關結果。
意見調查結果
使用 ArFuture_getState()
取得 ArFuture
的狀態。狀態分為三種:
AR_FUTURE_STATE_PENDING
:作業尚未完成,因此未得知任何結果。AR_FUTURE_STATE_CANCELLED
:ArFuture_cancel()
已取消作業。系統一律不會呼叫任何已註冊的回呼。AR_FUTURE_STATE_DONE
:作業已完成,使用ArVpsAvailabilityFuture_getResult()
取得結果。
您可以繼續查看 ArFuture_getState()
,直到工作完成為止。
// Obtain a ArVpsAvailabilityFuture and store it somewhere. ArVpsAvailabilityFuture* future = NULL; CHECK(ArSession_checkVpsAvailabilityAsync(ar_session, latitude, longitude, NULL, NULL, &future) == AR_SUCCESS); // Poll ArVpsAvailabilityFuture later, for example, in a render loop. ArFutureState future_state = AR_FUTURE_STATE_PENDING; ArFuture_getState(ar_session, (ArFuture*)future, &future_state); if (future_state == AR_FUTURE_STATE_DONE) { ArVpsAvailability vps_availability = AR_VPS_AVAILABILITY_UNKNOWN; ArVpsAvailabilityFuture_getResult(ar_session, future, &vps_availability); switch (vps_availability) { case AR_VPS_AVAILABILITY_AVAILABLE: // VPS is available at this location. break; case AR_VPS_AVAILABILITY_UNAVAILABLE: // VPS is unavailable at this location. break; case AR_VPS_AVAILABILITY_ERROR_NETWORK_CONNECTION: // The external service could not be reached due to a network connection // error. break; // Handle other error states, e.g. // AR_VPS_AVAILABILITY_ERROR_RESOURCE_EXHAUSTED, // AR_VPS_AVAILABILITY_ERROR_INTERNAL, ... } ArFuture_release((ArFuture*)future); }
透過回呼取得結果
您也可以透過回呼取得 ArFuture
的結果。使用 ArSession_checkVpsAvailabilityAsync()
並提供 callback
。ArFuture
有狀態 AR_FUTURE_STATE_DONE
後,系統就會在主執行緒上呼叫這個 callback
。
void vps_availability_callback(void* context, ArVpsAvailability availability) { // Callback is called on the Main thread. // Handle the ArVpsAvailability result as shown above. // For example, show UI that enables your AR view. // It is a best practice to free `context` memory at the end of the callback. free(context); } void check_availability_with_callback(ArSession* ar_session, double latitude, double longitude) { ArVpsAvailabilityFuture* future = NULL; void* context = NULL; CHECK(ArSession_checkVpsAvailabilityAsync( ar_session, latitude, longitude, context, vps_availability_callback, &future) == AR_SUCCESS); }
取消ArFuture
使用 ArFuture_cancel()
嘗試取消 ArFuture
。由於執行緒平行處理,您的取消嘗試實際上可能不會成功。如果嘗試成功,ArFuture_cancel()
會傳回 1
,否則會傳回 0
。
使用地理空間 API,且未涵蓋 VPS 涵蓋範圍
地理空間 API 也可用於沒有 VPS 涵蓋範圍的區域。在幾乎沒有俯瞰障礙的戶外環境中,GPS 可能足以產生具有高準確度的姿勢。
後續步驟
- 取得裝置相機的地理空間姿勢,判斷使用者裝置在實際位置。