アプリに空間環境を追加する

Jetpack XR SDK では、空間環境は没入型の周囲環境であり、アプリに追加して仮想シーンの背景をカスタマイズできます。空間環境は、アプリがフルスペースにある場合にのみ表示されます。

空間環境の概要

SpatialEnvironment は、アプリの空間環境の設定を管理するために使用されます。これは、スタンドアロンのスカイボックス画像と glTF で指定されたジオメトリの複合体です。一度に設定できるのは、1 つのスカイボックス画像と 1 つの glTF ジオメトリ ファイルのみです。

スカイボックスは、仮想シーンでユーザーの周囲に見える画像を表し、空、山、街並みなどの遠くの背景環境の錯覚を生み出します。ユーザーはスカイボックスを操作したり、近づいたりすることはできません。Jetpack XR SDK は、OpenEXR 標準の球体スカイボックスをサポートしています。EXR スカイボックスは、アプリの没入型背景を提供するだけでなく、アプリで読み込まれた 3D モデルに画像ベースのライティング（IBL）も提供します。詳しくは、3D モデルの操作に関するガイドをご覧ください。

空間環境には、glTF 標準の 3D ジオメトリ コンテンツを含めることもできます。この方法で読み込まれた環境ジオメトリは、現実世界の床に自動的に配置されます。環境ジオメトリは、視差効果でスカイボックスに溶け込むフォアグラウンド要素とミッドグラウンド要素を使用して、環境にリアリズムを加える優れた方法です。

空間環境の設計ガイダンスでは、空間環境の作成に使用できるさまざまなタイプのアセットと、安全で楽しい空間環境を作成する方法について説明しています。

アプリの空間環境は、次の 3 つの構成のいずれかに設定できます。

  • スカイボックス画像と glTF ジオメトリの組み合わせ。
  • パススルー サーフェス。表示される環境は、デバイスの外向きカメラからのライブフィードです。不透明度が 100% の場合、このパススルー サーフェスはスカイボックスとジオメトリを完全に遮ります。
  • パススルー サーフェスが完全に不透明でも完全に透明でもない混合構成。この場合、パススルー サーフェスは半透明になり、背後のスカイボックスとジオメトリにアルファ ブレンドされます。

空間環境の空間機能

空間環境リソースをインポートして読み込む

空間環境の glTF リソースと EXR リソースは、Session クラスを使用して非同期で読み込まれます。

glTF リソースを作成する

glTF リソースは GltfModel として作成できます。この場合、glTF はローカル ファイルから読み込まれます。GltfModel は、空間アプリ環境の一部として使用できます。

val environmentGeometry = GltfModel.create(session, Paths.get("DayGeometry.glb"))
Environments.kt

EXR イメージ リソースを作成する

EXR 画像リソースは ExrImage として作成できます。この場合、EXR はローカル ファイルから読み込まれます。ExrImage を cmgen と組み合わせて使用すると、スカイボックスの IBL の ZIP ファイルを作成できます。詳しくは、環境アセットの最適化に関するガイドをご覧ください。

val lightingForSkybox = ExrImage.createFromZip(session, Paths.get("BlueSkyboxLighting.zip"))
Environments.kt

アプリの SpatialEnvironmentPreference を設定する

preferredSpatialEnvironment プロパティは、アプリの優先空間環境を制御します。このプロパティを使用して設定を行っても、isPreferredSpatialEnvironmentActive がすでに true でない限り、すぐに変更されることはありません。デバイスが XR の背景を変更でき、SpatialCapabilities.SPATIAL_CAPABILITY_APP_ENVIRONMENT 機能が利用可能な状態になると、アプリの優先空間環境が自動的に表示されます。

設定を null にすると、アプリの優先空間環境が無効になり、代わりにデフォルトのシステム環境が表示されます。

指定された SpatialEnvironmentPreference が null ではなく、そのプロパティがすべて null の場合、空間環境は黒いスカイボックスとジオメトリで構成されます。

SpatialEnvironment 状態の変更に関する通知を受け取るには、addOnSpatialEnvironmentChangedListener を使用します。

基本的な使用方法

このコード スニペットは、環境ジオメトリとスカイボックス リソースを作成し、空間環境の設定を行います。この設定は保存され、アプリが独自の環境を設定できるようになったときに適用されます。

val spatialEnvironmentPreference =
    SpatialEnvironment.SpatialEnvironmentPreference(lightingForSkybox, environmentGeometry)
session.scene.spatialEnvironment.preferredSpatialEnvironment = spatialEnvironmentPreference
if (session.scene.spatialEnvironment.isPreferredSpatialEnvironmentActive) {
    // The environment was successfully updated and is now visible, and any listeners
    // specified using addOnSpatialEnvironmentChangedListener will be notified.
} else {
    // The passthrough opacity preference was successfully set, but not
    // immediately visible. The passthrough opacity change will be applied
    // when the activity has the SPATIAL_CAPABILITY_APP_ENVIRONMENT capability.
    // Then, any listeners specified using addOnSpatialEnvironmentChangedListener
    // will be notified.
}
Environments.kt

高度な使用方法

環境をより細かく制御する必要がある高度なユースケースでは、SpatialCapabilities チェックを組み込み、addOnSpatialEnvironmentChangedListener を実装して、空間環境の設定をいつ行うかを決定できます。

アプリの空間環境の PassthroughOpacityPreference を設定する

アプリの没入型仮想背景のコンポーネントの 1 つは、パススルー サーフェスです。この場合、表示される背景は、デバイスの外向きカメラからのライブフィードです。

setPassthroughOpacityPreference は、アプリの優先パススルーの不透明度を設定するために使用されます。このメソッドは設定のみを行い、SpatialCapabilities.SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL 機能が利用可能でない限り、即座に変更されることはありません。デバイスがパススルーの不透明度を変更できる状態になり、SpatialCapabilities.SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL 機能が利用可能になると、アプリの推奨パススルー不透明度が自動的に適用されます。

パススルーの不透明度の設定値の範囲は、0.0f（不透明度ゼロ。パススルー サーフェスは表示されません）から 1.0f（不透明度 100%。パススルー サーフェスが空間環境を隠します）までです。setPassthroughOpacityPreference パラメータは null 許容型の浮動小数点数です。値を null に設定すると、アプリにパススルーの不透明度の設定がないことを示し、パススルーの制御がシステムに返されます。

基本的な使用方法

このコード スニペットは、パススルーの不透明度設定を設定します。この設定は保存され、アプリにパススルーの不透明度を設定する機能がある場合に適用されます。

session.scene.spatialEnvironment.preferredPassthroughOpacity = 1.0f
if (session.scene.spatialEnvironment.currentPassthroughOpacity == 1.0f) {
    // The passthrough opacity request succeeded and should be visible now, and any listeners
    // specified using addOnPassthroughOpacityChangedListener will be notified.
} else {
    // The passthrough opacity preference was successfully set, but not
    // immediately visible. The passthrough opacity change will be applied
    // when the activity has the
    // SpatialCapabilities.SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL capability.
    // Then, any listeners specified using addOnPassthroughOpacityChangedListener
    // will be notified.
}
Environments.kt

高度な使用方法

パススルーの不透明度をより細かく制御する必要がある高度なユースケースでは、SpatialCapabilities チェックを組み込み、addOnPassthroughOpacityChangedListener を使用してリスナーを追加し、パススルーの不透明度の設定をいつ行うかを判断できます。

アセットの最適化

ユーザーの SpatialEnvironment を設定するためのアセットを作成する場合は、適度なファイルサイズを維持しながら、アセットで高品質の解像度を実現するようにしてください。詳細については、環境アセットの最適化に関するガイダンスをご覧ください。

現在のパススルーの不透明度を特定する

val currentPassthroughOpacity = session.scene.spatialEnvironment.currentPassthroughOpacity
Environments.kt

関連ドキュメント