Ihrer App Umgebungen hinzufügen

XR‑Geräte, für die der Leitfaden gilt
Dieser Leitfaden hilft Ihnen dabei, Erlebnisse für die folgenden Arten von XR-Geräten zu entwickeln.
Informationen zu XR-Gerätetypen →
XR-Headsets
Kabelgebundene XR-Datenbrille
Informationen zu XR-Gerätetypen →

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 Full Space befindet.

Übersicht über räumliche Umgebungen

Ein SpatialEnvironment verwaltet die Einstellungen für die räumliche Umgebung einer App. Es ist eine Kombination 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. Dadurch entsteht die Illusion einer fernen Hintergrundumgebung, z. B. eines Himmels, von Bergen oder einer 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 zum Arbeiten mit 3D-Modellen.

Räumliche Umgebungen können auch 3D-Geometrieinhalte im glTF-Standard enthalten. Die so geladene Umgebungsgeometrie wird automatisch am realen Boden ausgerichtet. Mit der Umgebungsgeometrie können Sie Ihrer Umgebung durch Vorder- und Mittelgrundelemente, die mit dem Parallaxeneffekt in die Skybox übergehen, mehr Realismus verleihen.

In den Designrichtlinien für räumliche Umgebungen finden Sie Informationen zu den verschiedenen Arten von Assets, die Sie zum Erstellen räumlicher Umgebungen verwenden können, und dazu, wie Sie sichere und angenehme räumliche Umgebungen erstellen.

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 deckend noch vollständig transparent ist. In diesem Fall wird die Passthrough-Oberfläche halbtransparent und mit der Skybox und der Geometrie dahinter per Alpha-Blending gemischt.

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"))

Bildbasierte Beleuchtungsressource erstellen

Eine bildbasierte Beleuchtungsressource kann als ImageBasedLightingAsset erstellt werden, wobei die Beleuchtung aus einer lokalen Datei geladen wird. Ein ImageBasedLightingAsset 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 Umgebungs-Assets.

val lightingForSkybox = ImageBasedLightingAsset.createFromZip(session, Paths.get("BlueSkyboxLighting.zip"))

SpatialEnvironmentPreference für Ihre App festlegen

Mit dem Attribut preferredSpatialEnvironment wird die bevorzugte räumliche Umgebung für eine App festgelegt. Wenn dieses Attribut 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 in einen Zustand wechselt, in dem der XR-Hintergrund geändert werden kann, und die Funktion SpatialCapability.APP_ENVIRONMENT verfügbar ist, wird die bevorzugte räumliche Umgebung für die Anwendung automatisch angezeigt.

Wenn Sie die Einstellung auf null setzen, wird die bevorzugte räumliche Umgebung für die App deaktiviert. Stattdessen wird die Standard-Systemumgebung angezeigt.

Wenn die angegebene SpatialEnvironmentPreference nicht null ist, aber alle ihre Attribute 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 Umgebungsgeometrie und die Skybox-Ressourcen erstellt und dann die Einstellung für die räumliche Umgebung festgelegt. Diese Einstellung wird gespeichert und angewendet, wenn die App die Möglichkeit hat, ihre eigene Umgebung festzulegen.

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.
}

Fortgeschrittene Nutzung

Für komplexere Anwendungsfälle, in denen Sie mehr Kontrolle über die Umgebung benötigen, können Sie SpatialCapability-Prüfungen einbinden und einen addOnSpatialEnvironmentChangedListener implementieren, um festzulegen, wann die Einstellung für die räumliche Umgebung festgelegt werden soll.

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

Eine der Komponenten des immersiven virtuellen Hintergrunds einer App ist eine Passthrough-Oberfläche. In diesem Fall ist der angezeigte Hintergrund ein Livefeed von den nach außen gerichteten Kameras des Geräts.

setPassthroughOpacityPreference wird verwendet, um die bevorzugte Passthrough-Deckkraft für eine App festzulegen. Mit dieser Methode wird nur eine Einstellung festgelegt. Sie führt nicht zu einer sofortigen Änderung, es sei denn, die Funktion SpatialCapability.PASSTHROUGH_CONTROL ist verfügbar. Sobald das Gerät in einen Zustand wechselt, in dem die Passthrough-Deckkraft geändert werden kann, und die Funktion SpatialCapability.PASSTHROUGH_CONTROL verfügbar ist, wird die bevorzugte Passthrough-Deckkraft für die Anwendung automatisch angewendet.

Die Werte für die bevorzugte 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 Gleitkommawert, der null sein kann. Wenn der Wert auf „null“ gesetzt wird, hat die App keine bevorzugte Passthrough-Deckkraft und die Passthrough-Steuerung wird an das System zurückgegeben.

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 Passthrough-Deckkraft 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.
}

Fortgeschrittene Nutzung

Für komplexere Anwendungsfälle, in denen Sie die Deckkraft des Passthrough genauer steuern müssen, können Sie SpatialCapability-Prüfungen einbinden und mit addOnPassthroughOpacityChangedListener einen Listener hinzufügen, um festzulegen, wann die Deckkraft des Passthrough festgelegt werden soll.

Asset-Optimierung

Wenn du Assets für die SpatialEnvironment deiner Nutzer erstellst, achte darauf, dass deine Assets eine hohe Qualität haben, aber die Dateigröße im Rahmen bleibt. Weitere Informationen finden Sie in unserem Leitfaden zur Optimierung von Umgebungs-Assets.

Aktuelle Passthrough-Deckkraft ermitteln

val currentPassthroughOpacity = session.scene.spatialEnvironment.currentPassthroughOpacity

Weitere Informationen