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

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

  • 如果是 GPS 精確度偏低的區域 (例如室內空間和人口密集的都市環境)，API 就會仰賴 VPS 覆蓋範圍來產生高精確度姿勢。
  • 在幾乎沒有高架障礙的戶外環境中，地理空間 API 或許能夠使用現有的 GPS 位置資料，製作出精準的地理空間姿勢。

你可以在 AR 工作階段開始前以特定水平位置判斷 VPS 適用情形，並使用這項功能打造更精準的體驗，舉例來說，只有在 VPS 可用時才會顯示「進入 AR」按鈕。

啟用 ARCore API

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

啟用 ARCore API 後，即可檢查 VPS 可用性，但這不會：

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

地理空間 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。

使用地理空間 API，且未涵蓋 VPS 涵蓋範圍

地理空間 API 也可用於沒有 VPS 涵蓋範圍的區域。在幾乎沒有俯瞰障礙的戶外環境中，GPS 可能足以產生具有高準確度的姿勢。

後續步驟