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

Übersicht über räumliche Umgebungen

Ein SpatialEnvironment wird verwendet, um die Einstellungen für die räumliche Umgebung einer App zu verwalten. Sie besteht aus einem eigenständigen Skybox-Image und einer in glTF angegebenen Geometrie. Es kann jeweils nur ein Skybox-Image und eine glTF-Geometriedatei festgelegt werden.

Eine Skybox stellt das Bild dar, das ein Nutzer in der virtuellen Szene um sich herum sieht. So wird die Illusion einer entfernten Hintergrundumgebung wie Himmel, Berge oder eine Stadtlandschaft erzeugt. 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 (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. Auf diese Weise geladene Umgebungsgeometrie wird automatisch an den Boden der realen Welt angepasst. Mit der Umgebungsgeometrie können Sie Ihrer Umgebung Realismus verleihen, indem Sie Vordergrund- und Mittelgrundelemente hinzufügen, die mit dem Parallaxeneffekt in die Skybox übergehen.

Im Leitfaden zum Design räumlicher Umgebungen erfahren Sie mehr über die verschiedenen Arten von Assets, die Sie zum Erstellen räumlicher Umgebungen verwenden können, und wie Sie sichere und ansprechende 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-Image und einer glTF-Geometrie.
  • Eine Passthrough-Oberfläche, bei der die angezeigte Umgebung ein Livestream der nach außen gerichteten Kameras des Geräts ist. Bei voller Deckkraft verdeckt diese Passthrough-Oberfläche die Skybox und die Geometrie vollständig.
  • Eine gemischte Konfiguration, bei der die Passthrough-Oberfläche nicht die volle Deckkraft hat und auch nicht völlig transparent ist. In diesem Fall wird die Passthrough-Oberfläche halbtransparent und verschmilzt mit der Skybox und der Geometrie dahinter.

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. GltfModel kann als Teil einer räumlichen App-Umgebung verwendet werden.

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

Ressource für bildbasierte Beleuchtung erstellen

Eine Ressource für bildbasierte Beleuchtung kann als ImageBasedLightingAsset erstellt werden, wobei die Beleuchtung aus einer lokalen Datei geladen wird. ImageBasedLightingAsset kann mit cmgen verwendet werden, um eine ZIP-Datei der bildbasierten Beleuchtung für Ihre Skyboxen zu erstellen. Weitere Informationen finden Sie in unserem Leitfaden zum Optimieren von Umgebungs-Assets.

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

SpatialEnvironmentPreference für Ihre App festlegen

Die preferredSpatialEnvironment Eigenschaft steuert die bevorzugte räumliche Umgebung für eine App. Wenn diese Eigenschaft zum Festlegen einer Einstellung verwendet wird, führt sie 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 SpatialCapabilities.SPATIAL_CAPABILITY_APP_ENVIRONMENTFunktion verfügbar ist, wird automatisch die bevorzugte räumliche Umgebung für die Anwendung angezeigt.

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

Wenn die angegebene SpatialEnvironmentPreference nicht null ist, aber alle ihrer Eigenschaften null sind, besteht die räumliche Umgebung aus einer schwarzen Skybox ohne Geometrie.

Mit addOnSpatialEnvironmentChangedListener können Sie sich über Änderungen am Status von SpatialEnvironment benachrichtigen lassen.

Grundlegende Nutzung

In 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 SpatialCapabilities-Prüfungen einbauen und ein 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 Livestream der nach außen gerichteten Kameras des Geräts.

setPassthroughOpacityPreference wird verwendet, um die bevorzugte Passthrough -Deckkraft für eine App festzulegen. Diese Methode legt nur eine Einstellung fest und führt nicht zu einer sofortigen Änderung, es sei denn, die FunktionSpatialCapabilities.SPATIAL_CAPABILITY_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 SpatialCapabilities.SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL verfügbar ist, wird automatisch die bevorzugte Passthrough-Deckkraft für die Anwendung angewendet.

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

Grundlegende Nutzung

In 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 mehr Kontrolle über die Passthrough Deckkraft benötigen, können Sie SpatialCapabilities Prüfungen einbauen und mit einem Listener mithilfe von addOnPassthroughOpacityChangedListener festlegen, wann die Einstellung für die Passthrough-Deckkraft festgelegt werden soll.

Asset-Optimierung

Achten Sie beim Erstellen von Assets zum Festlegen der SpatialEnvironment Ihrer Nutzer darauf, dass Ihre Assets eine hohe Auflösung haben und gleichzeitig eine angemessene Dateigröße beibehalten. Weitere Informationen finden Sie in unserem Leitfaden zum Optimieren von Umgebungs-Assets.

Aktuelle Passthrough-Deckkraft bestimmen

val currentPassthroughOpacity = session.scene.spatialEnvironment.currentPassthroughOpacity

Weitere Informationen