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 eine App im Vollbildschirmmodus ausgeführt wird.
Übersicht über räumliche Umgebungen
Mit einem SpatialEnvironment werden die Einstellungen für die Umgebung einer App verwaltet. Es ist eine Kombination aus einem eigenständigen Skybox-Bild und glTF-definierter Geometrie. Es kann jeweils nur ein Skybox-Bild und eine glTF-Geometriedatei festgelegt werden.
Ein Skybox stellt das Bild dar, das ein Nutzer in der virtuellen Szene um sich herum sieht, und schafft so die Illusion einer entfernten Hintergrundumgebung wie Himmel, Berge oder Stadtbild. Der Nutzer kann nicht mit dem Skybox interagieren oder näher herangehen. Das Jetpack XR SDK unterstützt sphärische Skyboxes im OpenEXR-Standard. Ein 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 zur Arbeit mit 3D‑Modellen.
Räumliche Umgebungen können auch 3D-Geometrieinhalte im glTF-Standard enthalten. Die Umgebungsgeometrie, die auf diese Weise geladen wird, wird automatisch an den realen Boden ausgerichtet. Mithilfe von Umgebungsgeometrie können Sie Ihrer Umgebung mehr Realismus verleihen, indem Sie Elemente im Vordergrund und im Mittelgrund verwenden, die sich mit dem Parallaxeneffekt in den Skybox einfügen.
In den Designrichtlinien für räumliche 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 angenehme räumliche Umgebungen schaffen.
Sie können die räumliche Umgebung Ihrer App auf eine dieser drei Konfigurationen festlegen:
- Eine Kombination aus einem Skybox-Bild und glTF-Geometrie.
- Eine Durchsichtsfläche, auf der die Umgebung als Livefeed von den nach außen gerichteten Kameras des Geräts angezeigt wird. Bei voller Deckkraft verdeckt diese Transparentfläche den Skybox und die Geometrie vollständig.
- Eine gemischte Konfiguration, bei der die Transparenz der Durchlassfläche weder vollständig noch null ist. In diesem Fall wird die Durchlassfläche halbtransparent und das Alpha-Mischverfahren wird mit dem Skybox und der Geometrie dahinter kombiniert.
Raumbezogene Funktionen für räumliche Umgebungen
SpatialCapabilities: Stellt die räumlichen Funktionen der aktuellen Sitzung dar. Bestimmte räumliche Funktionen sind für räumliche Umgebungen relevant.SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL: Gibt an, ob die Aktivität den Passthrough derzeit aktivieren oder deaktivieren kann.SPATIAL_CAPABILITY_APP_ENVIRONMENT: Gibt an, ob die Aktivität zum aktuellen Zeitpunkt eine eigene räumliche Umgebung festlegen kann oder nicht.
Ressourcen für die räumliche Umgebung importieren und laden
glTF- und EXR-Ressourcen für räumliche Umgebungen werden asynchron in der Klasse Session geladen. Diese Dateien müssen im Ordner „Assets“ gespeichert sein.
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.
// assume that session is a Session that has been previously created
val environmentGeometryFuture = session.createGltfResourceAsync("DayGeometry.glb")
val environmentGeometry = environmentGeometryFuture.await()
EXR-Bildressource erstellen
Eine EXR-Bildressource kann als ExrImage erstellt werden, wobei die EXR aus einer lokalen Datei geladen wird. Ein ExrImage kann als Teil einer räumlichen App-Umgebung zum Zeichnen von Skyboxes verwendet werden.
// assume that session is a Session that has been previously created
val skyboxExrFuture = session.createExrImageResourceAsync("BlueSkybox.exr")
val skyboxExr = skyboxExrFuture.await()
SpatialEnvironmentPreference für Ihre App festlegen
Mit setSpatialEnvironmentPreference wird die bevorzugte Umgebung für eine App festgelegt. Diese Methode legt nur eine Einstellung fest und führt nicht zu einer sofortigen Änderung, es sei denn, isSpatialEnvironmentPreferenceActive ist bereits wahr. Sobald sich das Gerät in einem Zustand befindet, in dem der XR-Hintergrund geändert werden kann und die Funktion SpatialCapabilities.SPATIAL_CAPABILITY_APP_ENVIRONMENT verfügbar ist, wird die bevorzugte 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 Standardsystemumgebung angezeigt.
Wenn das angegebene SpatialEnvironmentPreference nicht null ist, aber alle seine Eigenschaften null sind, besteht die räumliche Umgebung aus einem schwarzen Skybox und keiner Geometrie.
Wenn Sie benachrichtigt werden möchten, wenn sich der Status von „SpatialEnvironment“ ändert, verwenden Sie addOnSpatialEnvironmentChangedListener.
Grundlegende Verwendung
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 ihre eigene Umgebung festlegen kann.
// Assume that session is a Session that has been previously created
// Create a GLTFResource
val environmentGeometry = session.createGltfResourceAsync("DayGeometry.glb").await()
// Create an ExrImage for the skybox
val skyboxExr = session.createExrImageResourceAsync("BlueSkybox.exr").await()
val spatialEnvironmentPreference = SpatialEnvironmentPreference(skyboxExr, environmentGeometry)
val preferenceResult = session.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.
}
Erweiterte Nutzung
Bei erweiterten Anwendungsfällen, in denen Sie die Umgebung genauer steuern möchten, können Sie SpatialCapabilities-Prüfungen einbinden und eine addOnSpatialEnvironmentChangedListener implementieren, um festzulegen, wann die Einstellung für die 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 Durchlassfläche. In diesem Fall ist der angezeigte Hintergrund ein Livefeed von den nach außen gerichteten Kameras des Geräts.
Mit setPassthroughOpacityPreference wird die bevorzugte Transluzenz für eine App festgelegt. Diese Methode legt nur eine Einstellung fest und führt nicht zu einer sofortigen Änderung, es sei denn, die Funktion SpatialCapabilities.SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL ist verfügbar. Sobald das Gerät einen Status erreicht, in dem die Deckkraft der Durchlässigkeit geändert werden kann und die SpatialCapabilities.SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL-Funktion verfügbar ist, wird die bevorzugte Deckkraft der Durchlässigkeit für die Anwendung automatisch angewendet.
Die Werte für die Einstellung der Deckkraft der Durchsichtigen Oberfläche reichen von 0.0f (keine Deckkraft, d. h. die Durchsichtige Oberfläche ist nicht sichtbar) bis 1.0f (volle Deckkraft, d. h. die Durchsichtige Oberfläche verbirgt die Umgebung). Der Parameter setPassthroughOpacityPreference ist ein optionaler Gleitkommawert. Wenn Sie den Wert auf „null“ festlegen, gibt die App keine Einstellung für die Transparenz des Passes zurück und die Steuerung der Übertragung wird an das System zurückgegeben.
Grundlegende Verwendung
In diesem Code-Snippet wird die Einstellung für die Transparenz der Durchlässigkeit festgelegt. Diese Einstellung wird gespeichert und angewendet, wenn die App die Möglichkeit hat, die Deckkraft der Durchlässigkeit festzulegen.
// Assume that session is a Session that has been previously created
val preferenceResult = session.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
}
Erweiterte Nutzung
Bei erweiterten Anwendungsfällen, in denen Sie die Deckkraft der Durchlässigkeit genauer steuern möchten, können Sie SpatialCapabilities-Prüfungen und eine addOnPassthroughOpacityChangedListener implementieren, um festzulegen, wann die Einstellung für die Deckkraft der Durchlässigkeit festgelegt werden soll.
Asset-Optimierung
Wenn Sie Assets zum Festlegen der SpatialEnvironment Ihrer Nutzer erstellen, sollten Sie darauf achten, dass Ihre Assets eine hohe Auflösung bei einer angemessenen Dateigröße haben. Achten Sie darauf, dass Ihre glb-Datei Mipmaps und KTX2-Texturen verwendet. Achten Sie auch auf die Anzahl der Polygone in Ihren glb-Dateien, da eine hohe Polygonanzahl zu unnötigem Stromverbrauch führen kann. Der Großteil der Dateigröße bei den meisten SpatialEnvironment-Instanzen entfällt auf das Bild, das für die Himmelskuppel verwendet wird. Damit Ihre Bilder optimiert sind, sollten Sie die Assets mit einem Optimierungstool bearbeiten, z. B. ktx.
Aktuelle Transparenz des Passes bestimmen
val currentPassthroughOpacity = session.spatialEnvironment.getCurrentPassthroughOpacity()