Mit räumlichen Containern entwickeln

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 →

Spatial Containers bringen volumetrische Fenster in OpenXR. Ein räumlicher Container wird durch die Erweiterungen XR_EXT_spatial_container und XR_EXT_spatial_container_self_rendering in OpenXR 1.1 definiert und ist ein vom System verwalteter 3D-Volumenbereich im Raum des Nutzers, in dem Ihre App 3D-Inhalte mithilfe von Standard-OpenXR-Kompositionsebenen rendert.

In der Regel beansprucht eine OpenXR-Sitzung exklusiven Zugriff auf das gesamte Sichtfeld des Nutzers. Mit Spatial Containers kann Ihre App 3D-OpenXR-Inhalte in einer begrenzten 3D-Box in der Umgebung des Nutzers rendern oder jederzeit in eine unbegrenzte, immersive Vollbildansicht wechseln.

Informationen zu räumlichen Containern

Ein räumlicher Container ist ein begrenzter oder unbegrenzter 3D-Bereich, der vom Android XR-System verwaltet und von Ihrer OpenXR-App gerendert wird:

  • Begrenzter Modus: Ihre App schlägt 3D-Abmessungen (Breite, Höhe und Tiefe in Metern) vor und das System weist einen 3D-Begrenzungsrahmen in der Umgebung des Nutzers zu. Ihre App rendert Stereo-3D-Inhalte innerhalb des Volumens und das System schneidet gerenderte Inhalte an den Grenzen der 3D-Box ab.
  • Immersiver Modus: Der räumliche Container wird unendlich erweitert, sodass Ihre App das gesamte Sichtfeld des Nutzers einnimmt, wie bei einer herkömmlichen OpenXR-Sitzung im Vollbildmodus.
Drei räumliche Container, die gleichzeitig im Modus „Gesamter Bereich“ ausgeführt werden: ein orangefarbener, am Boden fixierter 3D-Geländecontainer, ein blaues 3D-Entenmodell mit angehängter 2D-UI und ein grüner 2D-UI-Container.
Abbildung 1. Mehrere räumliche Container im Modus „Full Space“: ein am Boden fixiertes 3D-Geländevolumen (links), ein 3D-Entenvolumen mit 2D-UI (Mitte) und ein 2D-UI-Container (rechts).

Wie Nutzer mit räumlichen Containern interagieren

Das Android XR-System verwaltet die Fenstersteuerung des räumlichen Containers und die Platzierung im physischen Raum. So wird ein einheitliches Interaktionsmodell für alle Apps bereitgestellt:

  • Verschieben und neu positionieren: Nutzer können den System-Handle eines räumlichen Containers mit Handgesten (z. B. Zusammenführen von Daumen und Zeigefinger) oder Motion-Controllern greifen, um ihn im 3D-Raum neu zu positionieren.
  • Minimieren und Schließen: Mit den Steuerelementen für Systemfenster können Nutzer einzelne räumliche Container minimieren oder schließen. Wenn ein Nutzer einen Container schließt, benachrichtigt das System Ihre App, damit sie Ressourcen bereinigen kann.
  • Am Boden fixieren mit Szenenerkennung: Wenn Ihre App die Berechtigung android.permission.SCENE_UNDERSTANDING_COARSE deklariert und anfordert, aktiviert das System automatisch das Einrasten an Oberflächen. Nutzer können dann einen räumlichen Container ohne zusätzliche App-Konfiguration auf dem physischen Boden platzieren und fixieren, wie in Abbildung 1 durch den orangefarbenen Terrain-Container dargestellt.
  • Direkte 3D-Interaktion: Wenn ein Container fokussiert und interaktiv ist, können Nutzer über Handtracking, Blickrichtung oder 6DoF-Controller direkt mit den 3D-Inhalten im Volume interagieren.
Ein Nutzer interagiert per Handtracking mit einer 3D-Ente in einem begrenzten blauen räumlichen Container.
Abbildung 2. Ein Nutzer interagiert mit 3D-Inhalten in einem begrenzten räumlichen Container mithilfe von Handtracking.
  • Wechsel zwischen begrenztem und immersivem Modus: Entweder der Nutzer oder Ihre App kann einen Container zwischen einer begrenzten 3D-Box und einer unbegrenzten immersiven Vollbildansicht wechseln, ohne die OpenXR-Sitzung neu zu starten.
Die 3D-Entenszene nach dem Wechsel von einem begrenzten räumlichen Container zu einer unbegrenzten immersiven Vollbildansicht.
Abbildung 3. Der räumliche Container nach dem Wechsel vom begrenzten Modus in den immersiven Modus, der das Sichtfeld des Nutzers ausfüllt.
  • Folgemodus für unterwegs: Da das System die Position des Koordinatenraums jedes räumlichen Containers (xrCreateSpatialContainerSpaceEXT) steuert, können Nutzer den Folgemodus über die Systemfenstersteuerung aktivieren. So folgt ihnen ein begrenzter 3D-Container automatisch und bleibt in ihrem Sichtfeld, während sie sich bewegen – ohne dass zusätzliche Konfigurationen in Ihrer App erforderlich sind.

Spatial Containers unter Android XR verwenden

Wenn Sie eine App mit räumlichen Containern erstellen, sollten Sie Ihre Szene unter Berücksichtigung der Containergrenzen, Statusänderungen und des Hintergrund-Mischmodus entwerfen.

3D-Inhalte an Containergrenzen anpassen

Im begrenzten Modus befindet sich der Ursprung (0, 0, 0) des räumlichen Containerbereichs (xrCreateSpatialContainerSpaceEXT) in der Mitte des 3D-Begrenzungsrahmens. Da das System die Position des Containerbereichs in der Umgebung des Nutzers verwaltet, rendert Ihre App ihre 3D-Inhalte relativ zu (0, 0, 0), während das System die Neupositionierung durch den Nutzer und den Folgemodus übernimmt. Das System schneidet alle Geometrien ab, die außerhalb der Breite, Höhe oder Tiefe des Felds gerendert werden, damit der Inhalt innerhalb des zugewiesenen Volumens bleibt.

Ihre App sollte auf Ereignisse zur Änderung der Begrenzungen von der Laufzeitumgebung warten und Ihre 3D-Szene so skalieren oder neu positionieren, dass wichtige Inhalte in die aktuellen Abmessungen des Containers passen. Wenn der Container in den immersiven Modus wechselt, werden die Grenzen unendlich und Sie können die Szene im vollen 1:1-Maßstab wiederherstellen.

Auf Änderungen des Containerstatus reagieren

Anstatt Sichtbarkeit und Fokus nur auf Anwendungsebene zu verwalten, meldet jeder räumliche Container seinen eigenen Status, sodass Ihre App entsprechend reagieren kann:

  • Sichtbarkeit: Gibt an, ob der Container derzeit ein- oder ausgeblendet ist. Pausieren Sie Animationen, Audio oder Simulationsaktualisierungen, während der Container ausgeblendet ist. Ihre App kann auch anfordern, dass ein Container ein- oder ausgeblendet wird.
  • Interaktionsfähigkeit: Gibt an, ob der Container fokussiert ist und Nutzereingaben über Handtracking, Controller oder Blickerfassung empfängt. Aktivieren oder deaktivieren Sie interaktive Hervorhebungen und die Eingabeverarbeitung, wenn sich der Fokus ändert.
  • Bounds mode: Gibt an, ob sich der Container derzeit im Modus XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT (auf eine 3D-Box zugeschnitten) oder XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT (unbegrenzter Vollbildmodus) befindet. Aktualisieren Sie die Skalierung der Szene und schalten Sie die Umgebungsvisualisierungen (z. B. Skyboxen oder Passthrough) um, wenn sich der Modus ändert. Ihre App kann auch jederzeit Übergänge zwischen dem begrenzten und dem immersiven Modus anfordern.

Alpha-Blended-Transparenz im begrenzten Modus verwenden

Im begrenzten Modus sorgt ein transparenter Hintergrund dafür, dass die physische Umgebung des Nutzers und andere Fenster um Ihre 3D-Modelle herum sichtbar bleiben. Konfiguriere deine Kamera oder deinen Viewport mit einem transparenten Hintergrund und verwende den Alpha-Blend-Umgebungsmodus. Wenn du in den immersiven Modus wechselst, kannst du entweder den Passthrough-Modus aktiviert lassen oder zu einer undurchsichtigen Skybox-Umgebung wechseln.

Verfügbarkeit von Funktionen prüfen und Manifest konfigurieren

Für räumliche Container ist ein Android XR-Gerät erforderlich, das Spatial API-Level 4 oder höher unterstützt. Anstatt das Android API-Level direkt zu prüfen, fragen Sie die OpenXR-Laufzeit ab, um festzustellen, ob Spatial Container unterstützt werden. Rufen Sie dazu xrEnumerateInstanceExtensionProperties auf, um zu prüfen, ob XR_EXT_spatial_container und XR_EXT_spatial_container_self_rendering verfügbar sind, und rufen Sie xrGetSystemProperties mit XrSystemSpatialContainerPropertiesEXT auf, um supportsBounded und supportsImmersive zu prüfen.

Bevor du eine App erstellst, die räumliche Container verwendet, musst du den Startmodus für Aktivitäten und alle funktionsspezifischen Berechtigungen in AndroidManifest.xml konfigurieren.

Full Space-Modus in AndroidManifest.xml aktivieren

Für räumliche Container ist der Modus „Gesamter Bereich (verwaltet)“ erforderlich, auch für eigenständige OpenXR-Apps. Herkömmliche OpenXR-Vollbild-Apps deklarieren XR_ACTIVITY_START_MODE_FULL_SPACE_UNMANAGED, um die exklusive Kontrolle über das Display ohne Systemfensterverwaltung zu übernehmen. Im Gegensatz dazu nutzt eine App, die Spatial Container verwendet, den Android XR-System-Compositor, um 3D-begrenzte Volumes, Fenstersteuerelemente und die räumliche Platzierung im Full Space-Modus zu verwalten. Sie muss android.window.PROPERTY_XR_ACTIVITY_START_MODE auf XR_ACTIVITY_START_MODE_FULL_SPACE_MANAGED setzen:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <application ...>
        <!-- Spatial Containers require Full Space Managed mode -->
        <property
            android:name="android.window.PROPERTY_XR_ACTIVITY_START_MODE"
            android:value="XR_ACTIVITY_START_MODE_FULL_SPACE_MANAGED" />

        <activity android:name=".MainActivity" ...>
            <!-- Optional hint declaring which bounds modes the activity uses -->
            <property
                android:name="org.khronos.openxr.PROPERTY_ACTIVITY_HINT_XR_SPATIAL_CONTAINER_USED_BOUNDS_MODES"
                android:value="XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT|XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT" />
        </activity>
    </application>
</manifest>

Funktionsspezifische Berechtigungen deklarieren und anfordern

Zum Erstellen und Rendern eines einfachen räumlichen Containers sind keine gefährlichen Laufzeitberechtigungen erforderlich. Für bestimmte Funktionen müssen jedoch die entsprechenden Android XR-Berechtigungen deklariert und angefordert werden:

  • Wenn Sie einen räumlichen Container mithilfe von Szenenerkennung am physischen Boden verankern und fixieren möchten, deklarieren und fordern Sie die gefährliche Berechtigung android.permission.SCENE_UNDERSTANDING_COARSE zur Laufzeit an.
  • Wenn du die Kopfposition des Nutzers in OpenXR erfassen möchtest, musst du android.permission.HEAD_TRACKING deklarieren und anfordern.
<uses-permission android:name="android.permission.HEAD_TRACKING" />
<uses-permission android:name="android.permission.SCENE_UNDERSTANDING_COARSE" />

Weitere Informationen zum Deklarieren und Anfordern gefährlicher XR-Berechtigungen zur Laufzeit finden Sie unter Berechtigungen für XR.

Spatial Containers in Ihrem Projekt aktivieren

Sie können mit Spatial Containers in Unity, Godot oder direkt mit OpenXR in C++ entwickeln. Wählen Sie einen Tab aus, um die Voraussetzungen, die Einrichtung des Editors und ein Codebeispiel für Ihre bevorzugte Umgebung aufzurufen:

Unity

Voraussetzungen

Projekt konfigurieren

  1. Gehen Sie zu Edit > Project Settings > XR Plug-in Management > OpenXR (Bearbeiten > Projekteinstellungen > XR-Plug-in-Verwaltung > OpenXR).
  2. Klicken Sie neben Android XR (Erweiterungen): Sitzungsverwaltung auf die Einstellungen und entfernen Sie das Häkchen bei Immersive XR.
  3. Aktivieren Sie in der Liste OpenXR Feature Groups die Option Spatial Container.

Verwenden Sie XRSpatialContainerFeature in C#, um Grenzen abzufragen, auf Containerereignisse zu reagieren und zwischen dem begrenzten und dem immersiven Modus zu wechseln:

void OnEnable()
{
    XRSpatialContainerFeature.OnSpatialContainerBoundsChanged += OnBoundsChanged;
}

private void OnBoundsChanged(Vector3 bounds, bool infiniteBounds)
{
    float minScale = Mathf.Min(bounds.x, bounds.y, bounds.z);
    transform.localScale = infiniteBounds ? Vector3.one : Vector3.one * minScale;
}

public void SetImmersiveMode(bool immersive)
{
    XRSpatialContainerFeature.TryRequestBoundsMode(immersive);
}

Eine vollständige Anleitung zur Projekteinrichtung, Manifestkonfiguration und Berechtigungsverarbeitung finden Sie unter Räumliche Container in Unity verwenden.

Godot

Voraussetzungen

Projekt konfigurieren

  1. Gehen Sie zu Projekt > Projekteinstellungen, aktivieren Sie Erweiterte Einstellungen und rufen Sie Allgemein > XR > OpenXR > Erweiterungen auf.
  2. Wählen Sie im Unterabschnitt Spatial Container die Option Enabled aus und konfigurieren Sie Bounds Mode und Bounds.
  3. Gehen Sie zu Projekt > Exportieren… > Android und wählen Sie unter Android XR-Funktionen die Option Experimentelle Funktionen verwenden aus.

Verwenden Sie das Singleton OpenXRSpatialContainerExtension in GDScript, um auf Änderungen der Containergrenzen und des Modus zu reagieren:

func _ready() -> void:
    if OpenXRSpatialContainerExtension.is_enabled():
        OpenXRSpatialContainerExtension.spatial_container_bounds_changed.connect(
            _on_bounds_changed
        )

func _on_bounds_changed(_rid: RID, bounds: Vector3) -> void:
    scale = Vector3.ONE * min(bounds.x, bounds.y, bounds.z)

func set_immersive_mode() -> void:
    OpenXRSpatialContainerExtension.request_main_spatial_container_bounds_mode(
        OpenXRSpatialContainerState.IMMERSIVE
    )

Vollständige Projekteinstellungen, Exportberechtigungen und GDScript-Beispiele finden Sie unter Spatial Container in Godot verwenden.

OpenXR

Voraussetzungen

Aktivieren Sie XR_EXT_spatial_container und XR_EXT_spatial_container_self_rendering, wenn Sie XrInstance erstellen, und erstellen und rendern Sie dann den räumlichen Container:

// 1. Enable the Spatial Container extensions during xrCreateInstance
const char* enabledExtensions[] = {
    XR_EXT_SPATIAL_CONTAINER_EXTENSION_NAME,
    XR_EXT_SPATIAL_CONTAINER_SELF_RENDERING_EXTENSION_NAME,
};

// 2. Configure and create a self-rendering spatial container
XrSpatialContainerConfigurationSelfRenderingEXT selfRenderingConfig{
    .type = XR_TYPE_SPATIAL_CONTAINER_CONFIGURATION_SELF_RENDERING_EXT,
    .next = nullptr,
    .viewConfigurationType = XR_VIEW_CONFIGURATION_TYPE_PRIMARY_STEREO,
    .suggestedBounds = {1.5f, 1.5f, 1.5f}, // Width, height, depth in meters
};

XrSpatialContainerCreateInfoEXT createInfo{
    .type = XR_TYPE_SPATIAL_CONTAINER_CREATE_INFO_EXT,
    .next = &selfRenderingConfig,
    .spatialContainerConfig =
        reinterpret_cast<const XrSpatialContainerConfigurationBaseHeaderEXT*>(
            &selfRenderingConfig),
};

XrSpatialContainerEXT spatialContainer = XR_NULL_HANDLE;
xrCreateSpatialContainerEXT(session, &createInfo, &spatialContainer);

// 3. Request bounded mode and make the container visible
xrRequestSpatialContainerBoundsModeEXT(
    spatialContainer, XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT);
xrRequestSpatialContainerVisibilityEXT(spatialContainer, XR_TRUE);

Weitere Informationen

OpenXR™ und das OpenXR-Logo sind Marken von The Khronos Group Inc. und in China, der Europäischen Union, Japan und dem Vereinigten Königreich als Marken eingetragen.