檢查裝置的 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() 並提供 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。

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

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

後續步驟