デバイスの現在地での VPS の提供状況を確認する

Geospatial API は、VPS データと GPS データを組み合わせて、高精度の地理空間ポーズを生成します。この API は、デバイスが現在地を特定できる場所であればどこでも使用できます。

  • 屋内空間や密集した都市環境など、GPS の精度が低いエリアでは、API は VPS の受信可能範囲を利用して、高精度のポーズを生成します。
  • 頭上の障害物がほとんどないか、まったくない屋外環境では、Geospatial API は利用可能な GPS 位置情報を使用して、地理空間のポーズを高精度で生成できる場合があります。

AR セッションの開始前に特定の水平位置での VPS の可用性を判断し、それを使用してより具体的なエクスペリエンスを創出できます。たとえば、VPS が使用可能な場合にのみ [AR を入力] ボタンを表示します。

ARCore API を有効にする

VPS が利用可能を確認するには、アプリで ARCore API を有効にする必要があります。

ARCore API を有効にすると、以下なしで VPS が利用可能かどうかを確認できます。

アプリで VPS の提供状況を確認する

Geospatial API は、デバイスが位置を特定できる場所であればどこでも使用できます。AR エクスペリエンスが VPS の受信可能範囲に左右される場合は、ArSession_checkVpsAvailabilityAsync() を使用して ArVpsAvailabilityFuture（特定の水平位置での VPS の可用性を確認する非同期タスク）を取得できます。 ArVpsAvailabilityFuture を取得すると、ポーリングまたはコールバックによって結果を取得できます。

結果をポーリングする

ArFuture_getState() を使用して ArFuture の状態を取得します。次の 3 つの状態があります。

タスクが完了するまで、引き続き 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 を指定します。この callback は、ArFuture の状態が AR_FUTURE_STATE_DONE になった直後にメインスレッドで呼び出されます。

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 で十分な精度のポーズを生成できます。

次のステップ