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

コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

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

空間環境の概要

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

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

空間環境には、glTF 標準の 3D ジオメトリ コンテンツを含めることもできます。この方法で読み込まれた環境ジオメトリは、実際の床と自動的に調整されます。環境ジオメトリは、パララックス エフェクトでスカイボックスにブレンドされるフォアグラウンドとミッドグラウンドの要素を使用して、環境にリアリズムを追加するのに最適な方法です。

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

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

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

空間環境の空間機能

• SpatialCapabilities: 現在のセッションの空間機能を表します。特定の空間機能は空間環境に関連しています。

• SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL: アクティビティが現在、パススルーを有効または無効にできるかどうかを示します。

• SPATIAL_CAPABILITY_APP_ENVIRONMENT: アクティビティが現在の時点で独自の空間環境を設定できるかどうかを示します。

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

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

glTF リソースを作成する

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

val environmentGeometryFuture = GltfModel.create(session, "DayGeometry.glb")
val environmentGeometry = environmentGeometryFuture.await()
Environments.kt

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

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

val lightingForSkybox = ExrImage.create(session, "BlueSkyboxLighting.zip")
Environments.kt

アプリの SpatialEnvironmentPreference を設定する

setSpatialEnvironmentPreference は、アプリの優先空間環境を設定するために使用します。このメソッドは設定のみを行い、isSpatialEnvironmentPreferenceActive がすでに true でない限り、すぐに変更は行われません。デバイスが XR の背景を変更できる状態になり、SpatialCapabilities.SPATIAL_CAPABILITY_APP_ENVIRONMENT 機能が使用可能になると、アプリに適した空間環境が自動的に表示されます。

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

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

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

基本的な使用方法

このコード スニペットは、環境ジオメトリとスカイボックス リソースを作成し、空間環境の設定を設定します。この設定は記憶され、アプリが独自の環境を設定できる場合に適用されます。

val spatialEnvironmentPreference =
    SpatialEnvironment.SpatialEnvironmentPreference(lightingForSkybox, environmentGeometry)
val preferenceResult =
    session.scene.spatialEnvironment.setSpatialEnvironmentPreference(spatialEnvironmentPreference)
if (preferenceResult == SpatialEnvironment.SetSpatialEnvironmentPreferenceChangeApplied()) {
    // The environment was successfully updated and is now visible, and any listeners
    // specified using addOnSpatialEnvironmentChangedListener will be notified.
} else if (preferenceResult == SpatialEnvironment.SetSpatialEnvironmentPreferenceChangePending()) {
    // The environment is in the process of being updated. Once visible, 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（不透明度 0、パススルー サーフェスが非表示）から 1.0f（完全な不透明度、パススルー サーフェスが空間環境を非表示）です。setPassthroughOpacityPreference パラメータは null 許容型の浮動小数点数です。値を null に設定すると、アプリにパススルーの不透明度の設定がないことを示し、パススルー制御をシステムに戻します。

基本的な使用方法

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

val preferenceResult = session.scene.spatialEnvironment.setPassthroughOpacityPreference(1.0f)
if (preferenceResult == SpatialEnvironment.SetPassthroughOpacityPreferenceChangeApplied()) {
    // The passthrough opacity request succeeded and should be visible now, and any listeners
    // specified using addOnPassthroughOpacityChangedListener will be notified
} else if (preferenceResult == SpatialEnvironment.SetPassthroughOpacityPreferenceChangePending()) {
    // 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.getCurrentPassthroughOpacity()
Environments.kt

関連ドキュメント

• 空間環境の設計ガイダンス