检查设备当前所在位置的 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 可能足以生成高精度姿势。

后续步骤