检查设备当前所在位置的 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

Geospatial API 也可以在没有 VPS 覆盖范围的区域使用。在没有上部障碍物或上部障碍物的户外环境中，GPS 可能足以生成非常准确的姿势。

后续步骤