Ihrer App Umgebungen hinzufügen

Im Jetpack XR SDK sind räumliche Umgebungen immersive Umgebungen, die Sie Ihrer App hinzufügen können, um den Hintergrund der virtuellen Szene anzupassen. Räumliche Umgebungen sind nur sichtbar, wenn sich eine App im Vollbildmodus befindet.

Übersicht über räumliche Umgebungen

Eine SpatialEnvironment wird verwendet, um die Einstellungen für die räumliche Umgebung einer App zu verwalten. Es ist ein zusammengesetztes Objekt aus einem eigenständigen Skybox-Bild und einer glTF-spezifizierten Geometrie. Es kann jeweils nur ein Skybox-Bild und eine glTF-Geometriedatei festgelegt werden.

Eine Skybox ist das Bild, das ein Nutzer in der virtuellen Szene um sich herum sieht. Sie erzeugt die Illusion einer entfernten Hintergrundumgebung wie Himmel, Berge oder eine Stadtlandschaft. Der Nutzer kann nicht mit der Skybox interagieren oder sich ihr nähern. Das Jetpack XR SDK unterstützt sphärische Skyboxen im OpenEXR-Standard. Eine EXR-Skybox bietet nicht nur einen immersiven Hintergrund für Ihre App, sondern auch bildbasierte Beleuchtung (Image Based Lighting, IBL) für 3D‑Modelle, die von Ihrer App geladen werden. Weitere Informationen finden Sie im Leitfaden für die Arbeit mit 3D‑Modellen.

Räumliche Umgebungen können auch 3D-Geometrieinhalte im glTF-Standard enthalten. Auf diese Weise geladene Umgebungsgeometrie wird automatisch am realen Boden ausgerichtet. Mit der Umgebungsgeometrie können Sie Ihrer Umgebung Realismus verleihen, indem Sie Vordergrund- und Mittelgrundelemente hinzufügen, die sich mit dem Parallaxeneffekt in die Skybox einfügen.

In den Designrichtlinien für räumliche Umgebungen erfährst du mehr über die verschiedenen Arten von Assets, die du zum Erstellen räumlicher Umgebungen verwenden kannst, und wie du sichere und ansprechende räumliche Umgebungen erstellst.

Sie können die räumliche Umgebung Ihrer App auf eine der folgenden drei Konfigurationen festlegen:

  • Eine Kombination aus einem Skybox-Bild und einer glTF-Geometrie.
  • Eine Passthrough-Oberfläche, auf der die Umgebung als Livefeed von den nach außen gerichteten Kameras des Geräts angezeigt wird. Bei voller Deckkraft verdeckt diese Passthrough-Oberfläche die Skybox und die Geometrie vollständig.
  • Eine gemischte Konfiguration, bei der die Passthrough-Oberfläche weder vollständig blickdicht noch vollständig transparent ist. In diesem Fall wird die Passthrough-Oberfläche halbtransparent und per Alpha-Blending mit der Skybox und der Geometrie dahinter kombiniert.

Räumliche Funktionen für räumliche Umgebungen

Ressourcen für räumliche Umgebungen importieren und laden

glTF- und EXR-Ressourcen für räumliche Umgebungen werden asynchron mit der Klasse Session geladen.

glTF-Ressource erstellen

Eine glTF-Ressource kann als GltfModel erstellt werden, wobei die glTF-Datei aus einer lokalen Datei geladen wird. Ein GltfModel kann als Teil einer räumlichen App-Umgebung verwendet werden.

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

EXR-Bildressource erstellen

Eine EXR-Bildressource kann als ExrImage erstellt werden, wobei das EXR aus einer lokalen Datei geladen wird. Eine ExrImage kann mit cmgen verwendet werden, um eine ZIP-Datei der IBL für Ihre Skyboxen zu erstellen. Weitere Informationen finden Sie in unserem Leitfaden zur Optimierung von Umgebungsobjekten.

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

SpatialEnvironmentPreference für Ihre App festlegen

Mit der Eigenschaft preferredSpatialEnvironment wird die bevorzugte räumliche Umgebung für eine App festgelegt. Wenn diese Eigenschaft verwendet wird, um eine Einstellung festzulegen, führt dies nicht zu einer sofortigen Änderung, es sei denn, isPreferredSpatialEnvironmentActive ist bereits true. Sobald das Gerät einen Zustand erreicht, in dem der XR-Hintergrund geändert werden kann und die Funktion SpatialCapabilities.SPATIAL_CAPABILITY_APP_ENVIRONMENT verfügbar ist, wird automatisch die bevorzugte räumliche Umgebung für die Anwendung angezeigt.

Wenn Sie die Einstellung auf null festlegen, wird die bevorzugte räumliche Umgebung für die App deaktiviert. Stattdessen wird die Standardumgebung des Systems angezeigt.

Wenn der angegebene SpatialEnvironmentPreference nicht null ist, aber alle seine Eigenschaften null sind, besteht die räumliche Umgebung aus einer schwarzen Skybox und keiner Geometrie.

Wenn Sie über Änderungen am Status von SpatialEnvironment benachrichtigt werden möchten, verwenden Sie addOnSpatialEnvironmentChangedListener.

Grundlegende Nutzung

Mit diesem Code-Snippet werden die Ressourcen für die Umgebungsgeometrie und die Skybox erstellt und dann die räumliche Umgebung festgelegt. Diese Einstellung wird gespeichert und angewendet, wenn die App ihre eigene Umgebung festlegen kann.

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

Erweiterte Nutzung

Für komplexere Anwendungsfälle, in denen Sie mehr Kontrolle über die Umgebung benötigen, können Sie SpatialCapabilities-Prüfungen einbauen und ein addOnSpatialEnvironmentChangedListener implementieren, um festzulegen, wann Sie die räumliche Umgebungseinstellung festlegen möchten.

PassthroughOpacityPreference für die räumliche Umgebung für Ihre App festlegen

Eine der Komponenten des immersiven virtuellen Hintergrunds einer App ist eine Passthrough-Oberfläche. In diesem Fall wird als Hintergrund ein Livestream der nach außen gerichteten Kameras des Geräts angezeigt.

Mit setPassthroughOpacityPreference wird die bevorzugte Passthrough-Deckkraft für eine App festgelegt. Mit dieser Methode wird nur eine Einstellung festgelegt. Es erfolgt keine sofortige Änderung, es sei denn, die Funktion SpatialCapabilities.SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL ist verfügbar. Sobald das Gerät einen Zustand erreicht, in dem die Passthrough-Deckkraft geändert werden kann, und die SpatialCapabilities.SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL-Funktion verfügbar ist, wird die bevorzugte Passthrough-Deckkraft für die Anwendung automatisch angewendet.

Die Werte für die Passthrough-Deckkraft reichen von 0.0f (keine Deckkraft, die Passthrough-Oberfläche ist nicht sichtbar) bis 1.0f (volle Deckkraft, die Passthrough-Oberfläche verdeckt die räumliche Umgebung). Der Parameter setPassthroughOpacityPreference ist ein Nullable-Gleitkommawert. Wenn Sie den Wert auf „null“ setzen, gibt dies an, dass die App keine bevorzugte Passthrough-Deckkraft hat und die Passthrough-Steuerung an das System zurückgegeben wird.

Grundlegende Nutzung

Mit diesem Code-Snippet wird die Einstellung für die Passthrough-Deckkraft festgelegt. Diese Einstellung wird gespeichert und angewendet, wenn die App die Möglichkeit hat, die Durchlässigkeit festzulegen.

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

Erweiterte Nutzung

Für komplexere Anwendungsfälle, in denen Sie die Transparenz des Passthrough-Modus genauer steuern müssen, können Sie SpatialCapabilities-Prüfungen einbauen und mit addOnPassthroughOpacityChangedListener einen Listener hinzufügen, um festzulegen, wann Sie die Einstellung für die Transparenz des Passthrough-Modus festlegen möchten.

Asset-Optimierung

Achten Sie beim Erstellen von Assets für die SpatialEnvironment Ihrer Nutzer darauf, dass die Assets eine hohe Auflösung haben, aber gleichzeitig eine angemessene Dateigröße beibehalten. Weitere Informationen zum Optimieren von Umgebungs-Assets

Aktuelle Passthrough-Deckkraft bestimmen

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

Siehe auch