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

Geospatial API 會結合 VPS 和 GPS 資料，產生高精確度的地理空間姿勢。只要裝置能夠判斷自身位置，這個 API 就能在任何地方使用：

  • 在 GPS 精確度較低的區域 (例如室內空間和擁擠的都會環境)，API 會依靠 VPS 涵蓋範圍產生高精確度姿勢。
  • 在沒有或幾乎沒有上方遮蔽物的戶外環境中，Geospatial API 可能可以使用可用的 GPS 位置資料，產生高精確度的地理空間姿勢。

您可以在 AR 工作階段開始前，判斷特定水平位置的 VPS 可用性，並利用這項資訊打造更具體的體驗，例如只在 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

地理空間 API 也適用於未涵蓋 VPS 的區域。在沒有或幾乎沒有上方遮蔽物的室外環境中，GPS 可能就足以產生高精確度的姿勢。

後續步驟