Geospatial API は、VPS データと GPS データを組み合わせて、高精度の地理空間ポーズを生成します。この API は、デバイスが現在地を特定できる場所であればどこでも使用できます。
- 屋内空間や密集した都市環境など、GPS の精度が低いエリアでは、API は VPS の受信可能範囲を利用して、高精度のポーズを生成します。
- 頭上の障害物がほとんどないか、まったくない屋外環境では、Geospatial API は利用可能な GPS 位置情報を使用して、地理空間のポーズを高精度で生成できる場合があります。
AR セッションの開始前に特定の水平位置での VPS の可用性を判断し、それを使用してより具体的なエクスペリエンスを創出できます。たとえば、VPS が使用可能な場合にのみ [AR を入力] ボタンを表示します。
ARCore API を有効にする
VPS が利用可能を確認するには、アプリで ARCore API を有効にする必要があります。
ARCore API を有効にすると、以下なしで VPS が利用可能かどうかを確認できます。
- 現在の実行中の
ArSession
(ArSession_resume()
を呼び出す前)。 ArGeospatialMode
を設定する。
アプリで VPS の提供状況を確認する
Geospatial API は、デバイスが位置を特定できる場所であればどこでも使用できます。AR エクスペリエンスが VPS の受信可能範囲に左右される場合は、ArSession_checkVpsAvailabilityAsync()
を使用して ArVpsAvailabilityFuture
(特定の水平位置での VPS の可用性を確認する非同期タスク)を取得できます。
ArVpsAvailabilityFuture
を取得すると、ポーリングまたはコールバックによって結果を取得できます。
結果をポーリングする
ArFuture_getState()
を使用して ArFuture
の状態を取得します。次の 3 つの状態があります。
AR_FUTURE_STATE_PENDING
: オペレーションはまだ完了していないため、結果は不明です。AR_FUTURE_STATE_CANCELLED
: オペレーションはArFuture_cancel()
によってキャンセルされました。登録済みのコールバックが呼び出されることはありません。AR_FUTURE_STATE_DONE
: オペレーションが完了しました。ArVpsAvailabilityFuture_getResult()
を使用して結果を取得します。
タスクが完了するまで、引き続き 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 で十分な精度のポーズを生成できます。
次のステップ
- デバイスカメラの地理空間ポーズを取得して、現実世界におけるユーザーのデバイスの正確な位置を特定します。