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

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

  • 屋内や密集した都市環境など、GPS 精度の低い地域では、API は VPS カバレッジに基づいて高精度のポーズを生成します。
  • オーバーヘッドの障害物がほとんどまたはまったくない屋外環境では、Geospatial API は利用可能な GPS 位置情報データを使用して、地理空間のポーズを高い精度で生成できます。

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

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

次のステップ