檢查裝置的 VPS 可用性';目前位置

Geospatial API 會結合 VPS 和 GPS 資料,產生高精確度的地理空間姿勢。您可以在裝置能夠判斷其位置的任何位置使用此 API:

  • 在 GPS 準確度較低的地區 (例如室內空間和人口稠密的都市環境),API 會透過 VPS 覆蓋範圍產生高精確度姿勢。
  • 在沒有或幾乎沒有上方遮蔽物的戶外環境中,Geospatial API 可能可以使用可用的 GPS 位置資料,產生高精確度的地理空間姿勢。

你可以在 AR 工作階段開始前,在特定水平位置決定 VPS 可用性,然後利用這個位置打造更具體的體驗,例如顯示「進入 AR」模式按鈕。

啟用 ARCore API

應用程式必須啟用 ARCore API 才能檢查 VPS 可用性。

啟用 ARCore API 後,不必執行下列操作,就能檢查 VPS 可用性:

檢查應用程式中的 VPS 可用性

Geospatial API 可用於裝置能夠判斷其位置的任何位置。如果 AR 體驗以 VPS 涵蓋率為依據,可以使用 ArSession_checkVpsAvailabilityAsync() 取得 ArVpsAvailabilityFuture,這項非同步工作會檢查特定水平位置的 VPS 可用性。 取得 ArVpsAvailabilityFuture 後,您可以透過輪詢或回呼取得結果。

輪詢結果

使用 ArFuture_getState() 取得 ArFuture 的狀態。狀態共有三種:

你可以繼續查看 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() 並提供 callbackArFuture 狀態變成 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

在沒有 VPS 涵蓋範圍的情況下使用 Geospatial API

Geospatial API 也可用於沒有 VPS 涵蓋範圍的區域中。在幾乎沒有或完全沒有障礙物的戶外環境中,GPS 可能足以產生高精確度的姿勢。

後續步驟