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

Mit SpatialEnvironment werden die Einstellungen für die räumliche Umgebung einer App verwaltet. 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 ist das Bild, das ein Nutzer in der virtuellen Szene um sich herum sieht. Dadurch 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 (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. 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 Elemente im Vorder- und Mittelgrund hinzufügen, die mit dem Parallaxeneffekt in die Skybox übergehen.

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 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 von den 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 weder volle noch keine Deckkraft hat. In diesem Fall wird die Passthrough-Oberfläche halbtransparent und mit der Skybox und der Geometrie dahinter überblendet.

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 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 IBL 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 Eigenschaft preferredSpatialEnvironment steuert die bevorzugte räumliche Umgebung für eine App. Wenn diese Eigenschaft verwendet wird, um eine Einstellung festzulegen, wird keine sofortige Änderung vorgenommen, 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_ENVIRONMENT Funktion 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 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.
}

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 von den 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 bewirkt keine sofortige Änderung, es sei denn, die Funktion SpatialCapabilities.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 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 bevorzugte Passthrough-Deckkraft hat und die Passthrough-Steuerung an das System zurückgegeben wird.

Grundlegende Nutzung

In diesem Code-Snippet wird die bevorzugte Passthrough-Deckkraft festgelegt. Diese Einstellung wird gespeichert und angewendet, wenn die App die Passthrough-Deckkraft festlegen kann.

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 addOnPassthroughOpacityChangedListener einen Listener hinzufügen, um festzulegen, wann die bevorzugte Passthrough-Deckkraft festgelegt werden soll.

Asset-Optimierung

Wenn Sie Assets zum Festlegen der SpatialEnvironment Ihrer Nutzer erstellen, achten Sie 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