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 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 durchsichtigen Oberflä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

Ressourcen für die räumliche Umgebung importieren und laden

glTF- und EXR-Ressourcen für räumliche Umgebungen werden asynchron mithilfe 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 environmentGeometryFuture = GltfModel.create(session, "DayGeometry.glb")
val environmentGeometry = environmentGeometryFuture.await()
Environments.kt

EXR-Bildressource erstellen

Eine EXR-Bildressource kann als ExrImage erstellt werden, wobei die EXR-Datei aus einer lokalen Datei geladen wird. Mit einer ExrImage können Sie mit cmgen eine ZIP-Datei der IBL für Ihre Skyboxen erstellen. Weitere Informationen finden Sie in unserem Leitfaden zur Optimierung von Umgebungs-Assets.

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

„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 der SpatialEnvironment ändert, 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 ihre eigene Umgebung festlegen kann.

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

Erweiterte Nutzung

Bei erweiterten Anwendungsfällen, in denen Sie die Umgebung genauer steuern möchten, können Sie SpatialCapabilities-Prüfungen einbinden und einen 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 Transparenz 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 Transparenz der Durchlässigkeit geändert werden kann und die SpatialCapabilities.SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL-Funktion verfügbar ist, wird die bevorzugte Transparenz der Durchlässigkeit für die Anwendung automatisch angewendet.

Die Werte für die 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 Nutzung

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

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

Erweiterte Nutzung

Bei erweiterten Anwendungsfällen, in denen Sie die Deckkraft der Durchlässigkeit genauer steuern möchten, können Sie SpatialCapabilities-Prüfungen einbinden und einen Listener mit addOnPassthroughOpacityChangedListener hinzufügen, um festzulegen, wann die Einstellung für die Deckkraft der Durchlässigkeit festgelegt werden soll.

Asset-Optimierung

Achten Sie beim Erstellen von Assets für die SpatialEnvironment Ihrer Nutzer darauf, dass sie eine hohe Auflösung bei einer angemessenen Dateigröße haben. Weitere Informationen finden Sie in unserem Leitfaden zur Optimierung von Umgebungs-Assets.

Aktuelle Transparenz des Passes bestimmen

val currentPassthroughOpacity = session.scene.spatialEnvironment.getCurrentPassthroughOpacity()
Environments.kt

Siehe auch