XR_EXT_spatial_container

Name String

XR_EXT_spatial_container

Erweiterungstyp

Instanzerweiterung

Registrierte Durchwahl

811

Revision

1

Ratification Status

Nicht ratifiziert

Erweiterungs- und Versionsabhängigkeiten

OpenXR 1.0

Datum der letzten Änderung

2026-08-06

IP-Status

Keine bekannten Ansprüche auf geistiges Eigentum.

Mitwirkende

Jared Finder, Google
Andreas Loeve Selvik, Meta Platforms
Lachlan Ford, Google
Cass Everitt, Meta Platforms
Adam Gousetis, Meta Platforms
Ankur Agrawal, Unity Technologies
Bjorn Swenson, LÖVR
Denny Rönngren, Varjo Technologies
Fredia Huya-Kouadio, Godot Engine
Guodong Rong, Meta Platforms
Jakob Bornecrantz, NVIDIA
Jian Zhang, ByteDance
John Kearney, Meta Platforms
Jonathan Wright, Meta Platforms
Junfeng She, ByteDance
Kenny Vercaemer, Google
Kurtis Eveleigh, Qualcomm
Mauricio Narvaez, Meta Platforms
Nathan Nuber, Valve Corporation
Nihav Jain, Google
Nikita Lutsenko, Meta Platforms
Praveen Babu J D, ByteDance
Rylie Pavlik, Collabora
Salar Khan, Google
Shuai Liu, ByteDance
Walter Luh, Meta Platforms
Yin Li, Microsoft
Zhipeng Liu, ByteDance

Übersicht

Diese Erweiterung definiert eine neue Klasse von darstellbaren Entitäten, die als „räumliche Container“ bezeichnet werden und dem Konzept von „Fenstern“ in 2D-Fenstersystemen für Desktops ähneln.

In OpenXR 1.x haben Apps die exklusive Kontrolle darüber, was der Nutzer sieht und wie es über die reale oder virtuelle Umgebung des Nutzers gelegt wird. Laufzeiten nehmen nur geringfügige Änderungen an den angezeigten Inhalten vor, um die Sicherheit der Nutzer zu gewährleisten. Dieses App-Modell eignet sich gut, um Nutzern eine einzelne immersive Erfahrung zu bieten, aber es lässt sich nicht auf mehrere gleichzeitige Erfahrungen ausweiten. Insbesondere in AR- und Mixed-Reality-Umgebungen möchten Nutzer oft mehrere verschiedene Apps gleichzeitig verwenden.

Räumliche Container sind wie Fenster, die auf 3D erweitert wurden. Der Nutzer kann mehrere räumliche Container gleichzeitig sehen und Eingaben für eine Teilmenge davon machen. Die sichtbaren räumlichen Container können zu verschiedenen Apps gehören und die Laufzeiten verwalten ihre Größe und Platzierung im Namen des Nutzers.

Diese Erweiterung unterstützt zusätzlich zu den vorhandenen immersiven OpenXR-Erlebnissen diese neuen Arten von räumlich begrenzten Erlebnissen. In begrenzten OpenXR-Anwendungen sind leicht dreidimensionale Inhalte (flache Bereiche mit geringen Tiefenversätzen) oder Volumen mit vollständig dreidimensionalen Inhalten zulässig. Immersive OpenXR-Erlebnisse sind die vorhandenen immersiven Vollbild-Apps, die seit OpenXR 1.0 unterstützt werden. Apps können zwischen den beiden Inhaltstypen wechseln, wenn die App dies zulässt.

Diese Erweiterung definiert keine Methode, mit der eine App ihre Inhalte rendern kann. Wie Inhalte gezeichnet werden, wird in anderen Erweiterungen definiert: XR_EXT_spatial_container_self_rendering .

Räumliche Container verwenden

Ein XrSpatialContainerEXT ist ein Handle, das einen räumlichen Container darstellt.

XR_DEFINE_HANDLE(XrSpatialContainerEXT)

Eine Anwendung beginnt mit dem Rendern über einen räumlichen Container. Dazu sind die folgenden Schritte erforderlich:

  1. Erstellen Sie mit xrCreateSpatialContainerEXT einen räumlichen Container.
  2. Ändern Sie einen beliebigen Status des Containers für die erste Darstellung, z. B. den Begrenzungsmodus.
  3. Fordern Sie die Laufzeit auf, den Container mit xrRequestSpatialContainerVisibleEXT anzuzeigen.
  4. Warten Sie, bis die Laufzeit bereit ist, den Container anzuzeigen. Wenn die Laufzeit bereit ist, wird ein XrEventDataSpatialContainerVisibleChangedEXT-Ereignis in die Warteschlange gestellt, wobei visible auf XR_TRUE gesetzt ist.
  5. Beginnt mit dem Rendern für den räumlichen Container.

So wird ein räumlicher Container abgebaut:

  1. Fordern Sie die Laufzeit auf, den Container mit xrRequestSpatialContainerVisibleEXT auszublenden.
  2. Warten Sie, bis die Laufzeit den Container ausgeblendet hat. Wenn die Laufzeit den Container vollständig ausgeblendet hat, wird ein XrEventDataSpatialContainerVisibleChangedEXT-Ereignis in die Warteschlange gestellt, wobei visible auf XR_FALSE gesetzt ist.
  3. Rendering für den räumlichen Container beenden.
  4. Löschen Sie den Container mit xrDestroySpatialContainerEXT .

Hinweis

Diese Erweiterung delegiert die Sichtbarkeit und Fokusverwaltung an einzelne räumliche Container. Da die Sitzung als Ganzes nicht mehr ein einzelnes sichtbares oder fokussiertes Objekt darstellt, durchläuft sie nicht die Standard-OpenXR-Zustandsmaschine (READY, SYNCHRONIZED, VISIBLE, FOCUSED). Stattdessen bleibt die Sitzung für ihre aktive Lebensdauer in XR_SESSION_STATE_IDLE und die Regeln unter Änderungen am Sitzungsstatus geben an, wie die wichtigsten OpenXR-Vorgänge diesem Modus zugeordnet werden.

Räumlichen Container erstellen

Mit der Funktion xrCreateSpatialContainerEXT wird ein neuer räumlicher Container erstellt.

XrResult xrCreateSpatialContainerEXT(
    XrSession                                   session,
    const XrSpatialContainerCreateInfoEXT*      createInfo,
    XrSpatialContainerEXT*                      spatialContainer);

Parameterbeschreibungen

  • session ist die XrSession, die den räumlichen Container erstellt.
  • createInfo ist ein Zeiger auf ein XrSpatialContainerCreateInfoEXT, das Parameter zum Erstellen des räumlichen Containers enthält.
  • spatialContainer ist ein Zeiger auf ein Handle, in dem der erstellte XrSpatialContainerEXT zurückgegeben wird.

Ein neu erstellter XrSpatialContainerEXT darf nicht sichtbar und nicht interaktiv sein und muss sich im Begrenzungsmodus XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT befinden. Wenn eine App möchte, dass ein räumlicher Container im immersiven Modus gestartet wird, kann sie einen Begrenzungsmodus von XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT anfordern, bevor sie die Anzeige eines räumlichen Containers anfordert.

Laufzeiten müssen XR_ERROR_VALIDATION_FAILURE zurückgeben, wenn eine Dimension von XrSpatialContainerCreateInfoEXT :: suggestedBounds negativ, unendlich oder keine Zahl ist. Laufzeiten müssen XR_ERROR_LIMIT_REACHED zurückgeben, wenn eine App versucht, mehr räumliche Container zu erstellen, als in XrSystemSpatialContainerPropertiesEXT :: maxSpatialContainerCount angegeben sind. Wenn räumliche Container nicht für diese Sitzung aktiviert wurden, müssen Laufzeiten XR_ERROR_SPATIAL_CONTAINERS_NOT_ENABLED_EXT zurückgeben.

Gültige Verwendung (implizit)

Rückgabecodes

Erfolg

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Fehler

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_CONTAINERS_NOT_ENABLED_EXT
  • XR_ERROR_VALIDATION_FAILURE

XrSpatialContainerCreateInfoEXT wird an xrCreateSpatialContainerEXT übergeben, um einen räumlichen Container zu erstellen.

typedef struct XrSpatialContainerCreateInfoEXT {
    XrStructureType                              type;
    const void*                                  next;
    XrSpatialContainerGraphicsPresentationEXT    graphicsPresentation;
    XrExtent3Df                                  suggestedBounds;
} XrSpatialContainerCreateInfoEXT;

Beschreibung des Mitglieds

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind weder in OpenXR noch in dieser Erweiterung definiert.
  • graphicsPresentation ist ein XrSpatialContainerGraphicsPresentationEXT, der beschreibt, wie dieser Spatial Container Grafiken darstellt.
  • suggestedBounds ist ein XrExtent3Df, der die angeforderten Abmessungen des räumlichen Containers in Metern beschreibt.

Eine App, die keine Präferenz für ihre Größe hat, kann suggestedBounds auf {0, 0, 0} setzen. Eine Laufzeit kann die angeforderte suggestedBounds ignorieren.

Eine Laufzeit, die es ermöglicht, räumliche Container durch andere Formen als ausgerichtete Boxen zu begrenzen, muss „suggestedBounds“ als Begrenzungsrahmen um die anderen Formen verwenden. Orientierte Boxen sind die am häufigsten verwendete Begrenzungsform.

Gültige Verwendung (implizit)

Wenn ein räumlicher Container nicht mehr verwendet werden kann, müssen Laufzeiten ein XrEventDataSpatialContainerClosedEXT-Ereignis in die Warteschlange stellen.

typedef struct XrEventDataSpatialContainerClosedEXT {
    XrStructureType          type;
    const void*              next;
    XrSpatialContainerEXT    spatialContainer;
} XrEventDataSpatialContainerClosedEXT;

Beschreibung des Mitglieds

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind weder in OpenXR noch in dieser Erweiterung definiert.
  • spatialContainer ist der XrSpatialContainerEXT, für den dieses Ereignis gilt.

Wenn das Ereignis XrEventDataSpatialContainerClosedEXT empfangen wird, bedeutet das, dass die Laufzeitumgebung keinen räumlichen Container mehr anzeigen kann, z. B. weil der Nutzer auf einen „Schließen“-Button geklickt hat oder die Sitzung in den Status XR_SESSION_STATE_LOSS_PENDING wechselt.

Nachdem eine App das Ereignis XrEventDataSpatialContainerClosedEXT empfangen hat, sollte sie den räumlichen Container nicht mehr verwenden, alle zugehörigen Zustände wie eine Renderschleife beenden und den Container zerstören. Laufzeiten müssen XR_ERROR_SPATIAL_CONTAINER_CLOSED_EXT von allen Funktionen zurückgeben, die auf diesem Container ausgeführt werden, mit Ausnahme von xrDestroySpatialContainerEXT .

Wenn ein räumlicher Container sichtbar ist, wenn die Laufzeit ein Schließereignis in die Warteschlange stellt, müssen Laufzeiten zuerst den Container auf „nicht sichtbar“ ändern und ein XrEventDataSpatialContainerVisibleChangedEXT-Ereignis in die Warteschlange stellen.

Gültige Verwendung (implizit)

Mit der Funktion xrDestroySpatialContainerEXT wird ein vorhandener räumlicher Container gelöscht.

XrResult xrDestroySpatialContainerEXT(
    XrSpatialContainerEXT                       spatialContainer);

Parameterbeschreibungen

Nachdem ein räumlicher Container zerstört wurde, dürfen Laufzeiten den Inhalt des Containers nicht mehr anzeigen und dürfen keine weiteren Ereignisse im Zusammenhang mit dem Container in die Warteschlange stellen.

Eine App sollte einen sichtbaren räumlichen Container nicht zerstören, da dies zu grafischen Artefakten führen kann. Stattdessen sollte eine App mit xrRequestSpatialContainerVisibleEXT anfordern, dass der räumliche Container ausgeblendet wird, auf ein XrEventDataSpatialContainerVisibleChangedEXT-Ereignis warten und dann den Container zerstören.

Gültige Verwendung (implizit)

Threadsicherheit

  • Der Zugriff auf spatialContainer und alle untergeordneten Handles muss extern synchronisiert werden.

Rückgabecodes

Erfolg

  • XR_SUCCESS

Fehler

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Der räumliche Containerbereich

Die Funktion xrCreateSpatialContainerSpaceEXT erstellt ein XrSpace-Handle für den räumlichen Containerbereich eines bestimmten räumlichen Containers.

XrResult xrCreateSpatialContainerSpaceEXT(
    XrSession                                   session,
    const XrSpatialContainerSpaceCreateInfoEXT* createInfo,
    XrSpace*                                    space);

Parameterbeschreibungen

Der „räumliche Containerbereich“ für einen bestimmten räumlichen Container ist ein Koordinatensystem, dessen Ursprung sich in der Mitte der Grenzen dieses räumlichen Containers befindet. Dieser Raum wird normalerweise als Basisraum für Funktionen wie xrLocateSpace verwendet.

+X zeigt auf die rechte Seite des Containers, +Y auf die Oberseite des Containers und +Z auf die Vorderseite des Containers. Wenn ein Container beispielsweise an der Schwerkraft ausgerichtet ist, sich vor dem Betrachter befindet und der Betrachter sich in der Identitätspose relativ zum LOCAL-Raum befindet, müssen Laufzeiten den Containerraum mit der Identitätsausrichtung relativ zum LOCAL-Raum ausrichten. Laufzeiten können die Position eines Containerbereichs relativ zum LOCAL-Bereich auf eine beliebige Position festlegen, wenn dieser Container sichtbar wird.

ext spatial container space convention

Abbildung 18: Achsenkonvention des räumlichen Containerbereichs

Der räumliche Containerbereich ist ein nicht an die Welt gebundener Ursprung. Apps, die im immersiven Modus einen weltgebundenen Ursprung benötigen, können einen weltgebundenen Raum wie XR_REFERENCE_SPACE_TYPE_LOCAL verwenden.

Laufzeiten können die Position eines räumlichen Containerbereichs jederzeit ändern, in der Regel, um Nutzern das Verschieben eines räumlichen Containers an eine andere Position oder das Drehen zu ermöglichen. Laufzeiten können die Pose auch ändern, wenn zwischen den Begrenzungsmodi XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT und XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT gewechselt wird.

Ein räumlicher Containerbereich muss auch dann ein gültiges Handle bleiben, wenn der räumliche Container, für den er bestimmt ist, mit xrDestroySpatialContainerEXT zerstört wird. Wenn ein räumlicher Container nicht sichtbar oder zerstört ist, darf der Raum des räumlichen Containers relativ zu anderen Räumen nicht lokalisierbar sein. XrSpaceLocation :: locationFlags und XrViewState ::viewStateFlags sind 0.

Gültige Verwendung (implizit)

Rückgabecodes

Erfolg

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Fehler

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_CONTAINER_CLOSED_EXT
  • XR_ERROR_VALIDATION_FAILURE

XrSpatialContainerSpaceCreateInfoEXT wird mit xrCreateSpatialContainerSpaceEXT verwendet, um ein XrSpace-Handle zu erstellen.

typedef struct XrSpatialContainerSpaceCreateInfoEXT {
    XrStructureType          type;
    const void*              next;
    XrSpatialContainerEXT    spatialContainer;
} XrSpatialContainerSpaceCreateInfoEXT;

Beschreibung des Mitglieds

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind weder in OpenXR noch in dieser Erweiterung definiert.
  • spatialContainer ist ein XrSpatialContainerEXT, für den ein Space erstellt werden soll.

Gültige Verwendung (implizit)

Präsentieren eines räumlichen Containers

Das Senden der Inhalte eines räumlichen Containers an OpenXR zur Anzeige wird von anderen Erweiterungen übernommen: XR_EXT_spatial_container_self_rendering .

Damit andere Erweiterungen die Methode zur Grafikdarstellung für einen räumlichen Container angeben können, definiert diese Erweiterung das Enum XrSpatialContainerGraphicsPresentationEXT.

typedef enum XrSpatialContainerGraphicsPresentationEXT {
    XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SELF_RENDERING_EXT = 1000813000,
    XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_CONFORMANCE_AUTOMATION_EXT = 1000814000,
    XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SYSTEM_RENDERING_EXTX1 = 1000815000,
    XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialContainerGraphicsPresentationEXT;

Enum-Beschreibung

XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SELF_RENDERING_EXT

Der räumliche Container verwendet OpenXR-Kompositionsebenen (hinzugefügt durch die Erweiterung XR_EXT_spatial_container_self_rendering)

XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_CONFORMANCE_AUTOMATION_EXT

Der räumliche Container wird für Konformitätstests erstellt und hat keinen Rendering-Pfad (von der XR_EXT_spatial_container_conformance_automation-Erweiterung hinzugefügt)

XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SYSTEM_RENDERING_EXTX1

Der räumliche Container verwendet das OpenXR-Systemrendering (hinzugefügt durch die Erweiterung XR_EXTX1_system_renderer)

Status des räumlichen Containers

Der Status des räumlichen Containers wird von Laufzeiten basierend auf App-Anfragen und den Anforderungen des Nutzers verwaltet. Daher wird für jeden Aspekt des räumlichen Containerstatus Folgendes dokumentiert:

  • Wenn Laufzeiten den Status des räumlichen Containers ändern dürfen. Für die meisten räumlichen Containerzustände können Laufzeiten den Zustand jederzeit ändern.
  • Wie eine App Änderungen am Status anfordert. Laufzeiten können jede Anfrage zurückstellen, bis sie der Meinung sind, dass die Anfrage geeignet ist. Laufzeiten stellen Ereignisse nicht in die Warteschlange, wenn eine Anfrage zurückgestellt wird. Anwendungen sollten also nicht auf ein solches Ereignis für nicht zugehörige Logik warten.
  • Welche Ereignislaufzeiten in die Warteschlange gestellt werden, wenn sich der Status des räumlichen Containers ändert. Laufzeiten stellen Ereignisse für alle Änderungen in die Warteschlange, einschließlich von der Anwendung angeforderter Änderungen und von der Laufzeit initiierter Änderungen. Laufzeiten dürfen keine Ereignisse zur Statusänderung in die Warteschlange stellen, die keine Änderung anzeigen, z. B. wenn eine App zwei Anfragen zum Ausblenden eines Containers in schneller Folge stellt.
  • Welche Ereignislaufzeiten in die Warteschlange gestellt werden, wenn eine Anfrage zur App-Änderung abgelehnt wird. Laufzeiten können eine Anfrage aus beliebigem Grund ablehnen, in der Regel aufgrund von Systemrichtlinien, die für eine hohe Nutzerfreundlichkeit sorgen sollen.

Mit der Funktion xrGetSpatialContainerStateEXT wird der aktuelle Status des räumlichen Containers abgefragt.

XrResult xrGetSpatialContainerStateEXT(
    XrSpatialContainerEXT                       spatialContainer,
    const XrSpatialContainerStateGetInfoEXT*    getInfo,
    XrSpatialContainerStateEXT*                 state);

Parameterbeschreibungen

Gültige Verwendung (implizit)

Rückgabecodes

Erfolg

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Fehler

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_CONTAINER_CLOSED_EXT
  • XR_ERROR_VALIDATION_FAILURE

XrSpatialContainerStateGetInfoEXT wird mit xrGetSpatialContainerStateEXT verwendet, um einen XrSpatialContainerStateEXT abzufragen.

typedef struct XrSpatialContainerStateGetInfoEXT {
    XrStructureType    type;
    const void*        next;
} XrSpatialContainerStateGetInfoEXT;

Beschreibung des Mitglieds

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind weder in OpenXR noch in dieser Erweiterung definiert.

Gültige Verwendung (implizit)

typedef struct XrSpatialContainerStateEXT {
    XrStructureType                    type;
    void*                              next;
    XrBool32                           visible;
    XrBool32                           interactable;
    XrSpatialContainerBoundsModeEXT    boundsMode;
} XrSpatialContainerStateEXT;

Beschreibung des Mitglieds

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind weder in OpenXR noch in dieser Erweiterung definiert.
  • visible gibt an, ob ein räumlicher Container sichtbar ist.
  • interactable gibt an, ob ein räumlicher Container derzeit Eingaben empfangen kann. Es ähnelt dem „Fokus“ bei 2D-Fenstersystemen für Computer, mit dem Unterschied, dass mehrere räumliche Container gleichzeitig interaktiv sein können.
  • boundsMode ist der aktuelle XrSpatialContainerBoundsModeEXT des räumlichen Containers.

Änderungen am Status eines räumlichen Containers werden über Ereignisse kommuniziert.

Ereignis „Feld geändert“

visible

XrEventDataSpatialContainerVisibleChangedEXT

interactable

XrEventDataSpatialContainerInteractableChangedEXT

boundsMode

XrEventDataSpatialContainerBoundsChangedEXT

Gültige Verwendung (implizit)

Sichtbarkeit

Apps fordern mit xrRequestSpatialContainerVisibleEXT an, dass ein räumlicher Container ein- oder ausgeblendet wird.

XrResult xrRequestSpatialContainerVisibleEXT(
    XrSpatialContainerEXT                       spatialContainer,
    const XrSpatialContainerVisibleRequestInfoEXT* info);

Parameterbeschreibungen

Das Ein- oder Ausblenden eines räumlichen Containers ist ein asynchroner Vorgang.

Apps sollten das Ausblenden eines räumlichen Containers anfordern, bevor sie ihn zerstören, damit Laufzeiten einen reibungslosen Übergang anzeigen können. Laufzeiten sollten Anfragen zum Ausblenden eines räumlichen Containers berücksichtigen.

Eine Laufzeit kann Anfragen zum Anzeigen eines räumlichen Containers ablehnen. In diesem Fall muss die Laufzeit ein XrEventDataSpatialContainerVisibleRequestDeniedEXT-Ereignis in die Warteschlange stellen. Beispielsweise lehnen einige Laufzeiten eine Anfrage zum Anzeigen eines räumlichen Containers ab, den der Nutzer durch Interaktion mit einer vom System bereitgestellten Schaltfläche zum Minimieren ausgeblendet hat.

Laufzeiten dürfen keinen räumlichen Container anzeigen, bevor die App mindestens einmal die Anzeige dieses räumlichen Containers angefordert hat. Nach der ersten Anfrage der App, einen räumlichen Container anzuzeigen, können Laufzeiten die Sichtbarkeit dieses räumlichen Containers unabhängig von den Anfragen einer App ändern. So kann die App den Anfangszustand und den Inhalt eines räumlichen Containers steuern und Laufzeiten können eine System-UI wie eine Taskleiste bereitstellen, über die Nutzer auswählen können, welche räumlichen Container sichtbar sind.

Laufzeiten müssen Anfragen zum Anzeigen eines räumlichen Containers in einem Begrenzungsmodus ablehnen, der basierend auf XrSystemSpatialContainerPropertiesEXT :: supportsBounded und XrSystemSpatialContainerPropertiesEXT :: supportsImmersive nicht unterstützt wird. Das ist möglich, wenn der Standardgrenzenmodus XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT für ein bestimmtes System nicht unterstützt wird.

Hinweis

Bei einigen Implementierungen ist für das Ein- oder Ausblenden eines räumlichen Containers die Kommunikation mit Systemdiensten erforderlich. Dies kann verschoben werden, bis der Nutzer mit einem Systemdialogfeld interagiert hat. Das asynchrone Design für die Anfrage von Änderungen des Sichtbarkeitsstatus soll Laufzeiten die Zeit geben, beide Vorgänge abzuschließen.

Gültige Verwendung (implizit)

Rückgabecodes

Erfolg

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Fehler

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_CONTAINER_CLOSED_EXT
  • XR_ERROR_VALIDATION_FAILURE

XrSpatialContainerVisibleRequestInfoEXT wird mit xrRequestSpatialContainerVisibleEXT verwendet, um die Sichtbarkeit eines räumlichen Containers zu ändern.

typedef struct XrSpatialContainerVisibleRequestInfoEXT {
    XrStructureType    type;
    const void*        next;
    XrBool32           visible;
} XrSpatialContainerVisibleRequestInfoEXT;

Beschreibung des Mitglieds

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind weder in OpenXR noch in dieser Erweiterung definiert.
  • visible gibt an, ob ein räumlicher Container angezeigt oder ausgeblendet werden soll.

Gültige Verwendung (implizit)

Jedes Mal, wenn eine Laufzeit die Sichtbarkeit eines räumlichen Containers ändert, muss die Laufzeit ein XrEventDataSpatialContainerVisibleChangedEXT-Ereignis mit dem neuen Status in die Warteschlange stellen.

typedef struct XrEventDataSpatialContainerVisibleChangedEXT {
    XrStructureType          type;
    const void*              next;
    XrSpatialContainerEXT    spatialContainer;
    XrBool32                 visible;
} XrEventDataSpatialContainerVisibleChangedEXT;

Beschreibung des Mitglieds

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind weder in OpenXR noch in dieser Erweiterung definiert.
  • spatialContainer ist der XrSpatialContainerEXT, für den dieses Ereignis gilt.
  • visible ist der neue Sichtbarkeitsstatus für den räumlichen Container.

Dieses Ereignis ersetzt XR_SESSION_STATE_VISIBLE , sodass der Wert pro Container unterschiedlich sein kann. Das Ereignis muss für alle Änderungen in die Warteschlange gestellt werden, einschließlich von der App angeforderter Änderungen und von der Laufzeit initiierter Änderungen.

Eine Laufzeit kann das Rendern eines Containers um einige Frames verzögern, nachdem dieses Ereignis mit visible auf XR_TRUE in die Warteschlange gestellt wurde. So wird vermieden, dass ein leerer Container angezeigt wird, und die App hat Zeit, ihre ersten Inhalte zu senden. Während dieser Zeit ist XrSpatialContainerStateEXT ::visible XR_TRUE . Laufzeiten sollten das Rendern eines Containers nicht um mehr als 0,5 Sekunden verzögern.

Gültige Verwendung (implizit)

Jedes Mal, wenn eine Laufzeit eine Anfrage zum Anzeigen eines Containers ablehnt, muss die Laufzeit ein XrEventDataSpatialContainerVisibleRequestDeniedEXT-Ereignis in die Warteschlange stellen.

typedef struct XrEventDataSpatialContainerVisibleRequestDeniedEXT {
    XrStructureType          type;
    const void*              next;
    XrSpatialContainerEXT    spatialContainer;
} XrEventDataSpatialContainerVisibleRequestDeniedEXT;

Beschreibung des Mitglieds

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind weder in OpenXR noch in dieser Erweiterung definiert.
  • spatialContainer ist der XrSpatialContainerEXT, für den dieses Ereignis gilt.

Gültige Verwendung (implizit)

Interaktiv

Eine App kann nicht anfordern, dass ein räumlicher Container interaktiv ist. Welche räumlichen Container interaktiv sind, wird vollständig von Laufzeiten gesteuert. Ein interaktiver räumlicher Container muss auch sichtbar sein.

Jedes Mal, wenn eine Laufzeit den Interaktionsstatus eines räumlichen Containers ändert, muss die Laufzeit ein XrEventDataSpatialContainerInteractableChangedEXT-Ereignis mit dem neuen Status in die Warteschlange stellen.

typedef struct XrEventDataSpatialContainerInteractableChangedEXT {
    XrStructureType          type;
    const void*              next;
    XrSpatialContainerEXT    spatialContainer;
    XrBool32                 interactable;
} XrEventDataSpatialContainerInteractableChangedEXT;

Beschreibung des Mitglieds

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind weder in OpenXR noch in dieser Erweiterung definiert.
  • spatialContainer ist der XrSpatialContainerEXT, für den dieses Ereignis gilt.
  • interactable ist der neue interaktive Status für den räumlichen Container.

Dieses Ereignis ersetzt XR_SESSION_STATE_FOCUSED , sodass der Wert pro Container unterschiedlich sein kann. Das Ereignis wird für alle Änderungen in die Warteschlange gestellt, einschließlich der von der Laufzeit initiierten Änderungen.

Laufzeiten können die Interaktion mit einem räumlichen Container jederzeit aktivieren oder deaktivieren. Wenn eine Laufzeit nur maximal einen interaktiven räumlichen Container gleichzeitig unterstützt, muss die Laufzeit beim Ändern des interaktiven räumlichen Containers das Ereignis für den räumlichen Container, der nicht mehr interaktiv ist ( interactable auf „false“ gesetzt), vor dem Ereignis für den Container, der interaktiv wird ( interactable auf „true“ gesetzt), in die Warteschlange stellen.

Gültige Verwendung (implizit)

Grenzwerte

Ein räumlicher Container hat einen Begrenzungsmodus und einen Begrenzungsrahmen. Der Begrenzungsmodus eines räumlichen Containers beschreibt, wie sich die Begrenzungen verhalten. Der Begrenzungsrahmen ist der Bereich, in dem der räumliche Container gezeichnet wird.

Die Aufzählung XrSpatialContainerBoundsModeEXT gibt die verschiedenen Modi an, in denen sich die Grenzen eines räumlichen Containers befinden können.

typedef enum XrSpatialContainerBoundsModeEXT {
    XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT = 1,
    XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT = 2,
    XR_SPATIAL_CONTAINER_BOUNDS_MODE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialContainerBoundsModeEXT;

Enum-Beschreibung

XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT

Der räumliche Container ist begrenzt. Die Grenzen sind ein endlicher Bereich. Der räumliche Container wird nur in dieser Region angezeigt.

XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT

Der räumliche Container ist immersiv und hat unendliche Grenzen. Der räumliche Container wird auf dem gesamten Bildschirm angezeigt.

Für räumliche Container im Begrenzungsmodus XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT gelten zusätzliche Anforderungen:

  • Laufzeiten müssen diese räumlichen Container genauso behandeln wie eine Vollbild- und immersive App, die ohne räumliche Container erstellt wurde, mit Ausnahme der Verhaltensänderungen, die unter Änderungen am Sitzungsstatus beschrieben werden.
  • Laufzeiten können zusätzliche Erweiterungen bereitstellen, mit denen sich immersive räumliche Container anders verhalten als Vollbild- und immersive Apps, die ohne diese Erweiterung erstellt wurden.
  • Laufzeiten müssen unendliche Grenzen für diese räumlichen Container melden.
  • Laufzeiten können andere räumliche Container ausblenden, während ein immersiver räumlicher Container sichtbar ist. Da dies je nach Laufzeit unterschiedlich sein kann, sollten sich Apps nicht darauf verlassen, dass räumliche Container automatisch ein- oder ausgeblendet werden, wenn immersive räumliche Container sichtbar sind. Wie bei allen anderen sichtbaren Zustandsübergängen müssen Laufzeiten ein XrEventDataSpatialContainerVisibleChangedEXT-Ereignis in die Warteschlange stellen, wenn ein räumlicher Container ausgeblendet wird, weil ein immersiver Container sichtbar ist.

Hinweis

Die oben genannten Anforderungen bedeuten, dass alle Laufzeiten den OpenXR 1.x-Pfad ohne diese Erweiterung implementieren können, indem sie implizit einen räumlichen Container erstellen, den Begrenzungsmodus des Containers auf „Immersiv“ festlegen und anfordern, dass er sichtbar ist.

Apps fordern mit xrRequestSpatialContainerBoundsModeEXT eine Änderung des Begrenzungsmodus eines räumlichen Containers an.

XrResult xrRequestSpatialContainerBoundsModeEXT(
    XrSpatialContainerEXT                       spatialContainer,
    const XrSpatialContainerBoundsModeRequestInfoEXT* info);

Parameterbeschreibungen

Das Ändern des Begrenzungsmodus eines räumlichen Containers ist ein asynchroner Vorgang. Laufzeiten können ein Änderungs- oder Ablehnungsereignis viele Sekunden nach der Änderungsanfrage der App in die Warteschlange stellen. So können Laufzeiten eine Benutzeroberfläche einblenden, die erforderlich ist, damit ein Nutzer sicher in den immersiven Modus wechseln kann.

Laufzeiten müssen eine Anfrage zum Ändern des Begrenzungsmodus für einen nicht sichtbaren räumlichen Container berücksichtigen. Wenn eine Laufzeit eine Anfrage für den Begrenzungsmodus für einen nicht sichtbaren Container ablehnen würde, kann sie stattdessen eine Anfrage zum Anzeigen eines solchen räumlichen Containers ablehnen oder zurückstellen. Dadurch können Apps einen Container als immersiven Container starten. Eine Laufzeit kann Anfragen zum Ändern des Begrenzungsmodus eines sichtbaren räumlichen Containers ablehnen. In diesem Fall muss die Laufzeit ein XrEventDataSpatialContainerBoundsModeRequestDeniedEXT-Ereignis in die Warteschlange stellen. Einige Laufzeiten lehnen beispielsweise eine Anfrage zum Ändern des Begrenzungsmodus eines sichtbaren räumlichen Containers ab, mit dem der Nutzer nicht aktiv interagiert.

Laufzeiten müssen XR_ERROR_VALIDATION_FAILURE zurückgeben, wenn eine App einen Begrenzungsmodus anfordert, der basierend auf XrSystemSpatialContainerPropertiesEXT :: supportsBounded und XrSystemSpatialContainerPropertiesEXT :: supportsImmersive nicht unterstützt wird.

Gültige Verwendung (implizit)

Rückgabecodes

Erfolg

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Fehler

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_CONTAINER_CLOSED_EXT
  • XR_ERROR_VALIDATION_FAILURE

XrSpatialContainerBoundsModeRequestInfoEXT wird mit xrRequestSpatialContainerBoundsModeEXT verwendet, um den Begrenzungsmodus eines räumlichen Containers zu ändern.

typedef struct XrSpatialContainerBoundsModeRequestInfoEXT {
    XrStructureType                    type;
    const void*                        next;
    XrSpatialContainerBoundsModeEXT    boundsMode;
} XrSpatialContainerBoundsModeRequestInfoEXT;

Beschreibung des Mitglieds

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind weder in OpenXR noch in dieser Erweiterung definiert.
  • boundsMode ist der gewünschte XrSpatialContainerBoundsModeEXT für den räumlichen Container.

Gültige Verwendung (implizit)

Jedes Mal, wenn eine Laufzeit die Grenzen oder den Grenzmodus eines räumlichen Containers ändert, muss die Laufzeit ein XrEventDataSpatialContainerBoundsChangedEXT-Ereignis mit den neuen Grenzdaten in die Warteschlange stellen.

typedef struct XrEventDataSpatialContainerBoundsChangedEXT {
    XrStructureType                    type;
    const void*                        next;
    XrSpatialContainerEXT              spatialContainer;
    XrExtent3Df                        bounds;
    XrBool32                           infiniteBounds;
    XrSpatialContainerBoundsModeEXT    boundsMode;
} XrEventDataSpatialContainerBoundsChangedEXT;

Beschreibung des Mitglieds

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind weder in OpenXR noch in dieser Erweiterung definiert.
  • spatialContainer ist der XrSpatialContainerEXT, für den dieses Ereignis gilt.
  • bounds ist die neue Breite, Höhe und Tiefe der Grenzen des räumlichen Containers.
  • infiniteBounds ist „true“, wenn der Container unendliche Grenzen hat.
  • boundsMode ist der neue XrSpatialContainerBoundsModeEXT des räumlichen Containers.

Das Ereignis wird für alle Änderungen in die Warteschlange gestellt, einschließlich von der App angeforderter Änderungen und von der Laufzeit initiierter Änderungen.

Wenn ein Nutzer die Größe eines räumlichen Containers interaktiv ändert, müssen sich Laufzeiten auf eine der folgenden Arten verhalten:

  • Viele Ereignisse in die Warteschlange stellen, wahrscheinlich mit Framerate, während der Nutzer die Größe des räumlichen Containers ändert
  • ein einzelnes Ereignis am Ende der Größenänderung in die Warteschlange stellen

Wenn eine Laufzeit am Ende der Größenänderung nur ein einzelnes Ereignis in die Warteschlange stellt, muss diese Laufzeit weiterhin die alten Grenzen von xrGetSpatialContainerBoundsEXT melden, bis die Laufzeit ein Ereignis zur Größenänderung in die Warteschlange stellt. Laufzeiten müssen mehrere Ereignisse, die nicht abgefragt wurden und bei denen sich die Grenzen geändert haben, zusammenfassen. Wenn sich also die Grenzen oder der Grenzmodus ändern, während ein XrEventDataSpatialContainerBoundsChangedEXT-Ereignis noch in der Warteschlange ist, müssen Laufzeiten nur ein einzelnes Ereignis melden, das die letzte Grenzänderung enthält. Da Apps die Grenzen eines räumlichen Containers auch direkt mit xrGetSpatialContainerBoundsEXT abfragen können, kann sich die Anzahl der Grenzänderungen aus Ereignissen von der Anzahl der Änderungen aus Abfragen unterscheiden. Dies hängt vom Zeitpunkt der von der Laufzeit generierten Grenzänderungen, von App-Aufrufen von xrPollEvent und von App-Aufrufen von xrGetSpatialContainerBoundsEXT ab.

Wenn sich die Grenzen eines räumlichen Containers ändern, kann sich auch der lokale Ursprung des räumlichen Containers ändern. Wenn eine Laufzeitumgebung es einem Nutzer beispielsweise ermöglicht, die Grenzen des räumlichen Containers durch Ziehen an einer der Kanten des Containers zu ändern, ändern sich die Grenzen und der lokale Ursprung dieses Containers, wenn der Nutzer eine einzelne Kante zieht. In solchen Situationen muss die Laufzeit die Grenzen und den lokalen Ursprung gleichzeitig ändern.

Laufzeiten müssen infiniteBounds auf XR_TRUE und Breite, Höhe und Tiefe auf 0,0 setzen, um unendliche Grenzen darzustellen. Laufzeiten müssen infiniteBounds auf XR_FALSE und Breite, Höhe und Tiefe auf endliche positive Zahlen für endliche Grenzen festlegen.

Laufzeiten müssen bounds und infiniteBounds nach denselben Regeln wie für XrSpatialContainerBoundsEXT festlegen.

Gültige Verwendung (implizit)

Jedes Mal, wenn eine Laufzeit eine Anfrage zum Ändern des Begrenzungsmodus eines Containers ablehnt, muss die Laufzeit ein XrEventDataSpatialContainerBoundsModeRequestDeniedEXT-Ereignis in die Warteschlange stellen.

typedef struct XrEventDataSpatialContainerBoundsModeRequestDeniedEXT {
    XrStructureType          type;
    const void*              next;
    XrSpatialContainerEXT    spatialContainer;
} XrEventDataSpatialContainerBoundsModeRequestDeniedEXT;

Beschreibung des Mitglieds

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind weder in OpenXR noch in dieser Erweiterung definiert.
  • spatialContainer ist der XrSpatialContainerEXT, für den dieses Ereignis gilt.

Gültige Verwendung (implizit)

Die Struktur XrSpatialContainerBoundsEXT beschreibt den Begrenzungsrahmen eines räumlichen Containers.

typedef struct XrSpatialContainerBoundsEXT {
    XrStructureType    type;
    void*              next;
    XrExtent3Df        bounds;
    XrBool32           infiniteBounds;
} XrSpatialContainerBoundsEXT;

Beschreibung des Mitglieds

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind weder in OpenXR noch in dieser Erweiterung definiert.
  • bounds ist die Breite, Höhe und Tiefe der Grenzen des räumlichen Containers. Die Grenzen werden in Metern angegeben.
  • infiniteBounds ist „true“, wenn der Container unendliche Grenzen hat.

Laufzeiten müssen infiniteBounds auf XR_TRUE und Breite, Höhe und Tiefe auf 0,0 setzen, um unendliche Grenzen darzustellen. Laufzeiten müssen infiniteBounds auf XR_FALSE und Breite, Höhe und Tiefe auf endliche positive Zahlen für endliche Grenzen festlegen.

Gültige Verwendung (implizit)

Mit der Funktion xrGetSpatialContainerBoundsEXT werden die aktuellen Grenzen eines räumlichen Containers abgefragt.

XrResult xrGetSpatialContainerBoundsEXT(
    XrSpatialContainerEXT                       spatialContainer,
    const XrSpatialContainerBoundsGetInfoEXT*   getInfo,
    XrSpatialContainerBoundsEXT*                bounds);

Parameterbeschreibungen

Ein begrenzter räumlicher Container darf keine unendlichen Grenzen haben, während ein immersiver räumlicher Container unendliche Grenzen haben muss.

Laufzeiten können die Grenzen eines räumlichen Containers jederzeit in einen beliebigen positiven endlichen Wert ändern, solange der räumliche Container begrenzt ist. Änderungen an den Grenzen eines räumlichen Containers werden über XrEventDataSpatialContainerBoundsChangedEXT kommuniziert.

Mit dieser Erweiterung kann eine App keine Änderungen an den Grenzen anfordern, außer zwischen begrenztem und immersivem Modus mit xrRequestSpatialContainerBoundsModeEXT zu wechseln. Andere Erweiterungen bieten diese Möglichkeit in Zukunft vielleicht.

Gültige Verwendung (implizit)

Rückgabecodes

Erfolg

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Fehler

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_CONTAINER_CLOSED_EXT
  • XR_ERROR_VALIDATION_FAILURE

Die Struktur XrSpatialContainerBoundsGetInfoEXT ist eine Eingabestruktur, die für zukünftige Erweiterungen vorgesehen ist.

typedef struct XrSpatialContainerBoundsGetInfoEXT {
    XrStructureType    type;
    const void*        next;
} XrSpatialContainerBoundsGetInfoEXT;

Beschreibung des Mitglieds

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind weder in OpenXR noch in dieser Erweiterung definiert.

Gültige Verwendung (implizit)

Die Aufzählung XrSpatialContainerVolumeClippingEXT gibt verschiedene Verhaltensweisen für das Volume-Clipping für einen räumlichen Container an.

typedef enum XrSpatialContainerVolumeClippingEXT {
    XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_NONE_EXT = 0,
    XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_STRICT_EXT = 1,
    XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialContainerVolumeClippingEXT;

Enum-Beschreibung

XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_NONE_EXT

Es werden keine Inhalte auf das Begrenzungsvolumen des räumlichen Containers zugeschnitten. Inhalte können außerhalb der Grenzen des räumlichen Containers dargestellt werden.

XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_STRICT_EXT

Inhalte werden strikt auf das Begrenzungsvolumen des räumlichen Containers zugeschnitten.

Diese Aufzählung wird in dieser Erweiterung nicht verwendet. Sie ist so definiert, dass andere Erweiterungen das gewünschte Verhalten für das Abschneiden von Lautstärke angeben können. Eine App möchte beispielsweise einen Hintergrund für einen begrenzten räumlichen Container zeichnen. Eine monokulare Cubemap ist eine praktische Möglichkeit, einen Hintergrund anzugeben. Sie ist jedoch konzeptionell im Unendlichen positioniert, also außerhalb des Containers.

Systemfunktionen

Eine App kann die Systemfunktionen prüfen, indem sie beim Aufruf von xrGetSystemProperties eine XrSystemSpatialContainerPropertiesEXT-Struktur mit den XrSystemProperties verknüpft.

typedef struct XrSystemSpatialContainerPropertiesEXT {
    XrStructureType    type;
    void*              next;
    uint32_t           maxSpatialContainerCount;
    XrBool32           supportsBounded;
    XrBool32           supportsImmersive;
} XrSystemSpatialContainerPropertiesEXT;

Beschreibung des Mitglieds

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind weder in OpenXR noch in dieser Erweiterung definiert.
  • maxSpatialContainerCount ist die maximale Anzahl von räumlichen Containern, die erstellt werden können.
  • supportsBounded ist „true“, wenn räumliche Container begrenzt werden können.
  • supportsImmersive ist „true“, wenn räumliche Container immersiv sein dürfen.

Laufzeiten, die diese Erweiterung unterstützen, sollten eine App unterstützen, die viele räumliche Container erstellt, die nur durch die Arbeitsspeicherzuweisung begrenzt sind. Eine Laufzeit kann ein anderes Limit für die Anzahl der gleichzeitig angezeigten räumlichen Container haben. Es ist nicht möglich, die Anzahl der gleichzeitig angezeigten Container in dieser Erweiterung abzufragen, da eine Laufzeit einzelne Apps basierend auf dem Status aller ausgeführten Apps einschränken kann. Es wird davon ausgegangen, dass für stark eingeschränkte Geräte und weniger eingeschränkte Geräte unterschiedliche Limits für die Anzahl der gleichzeitig angezeigten Container gelten. Stark eingeschränkte Geräte unterstützen möglicherweise nur einen räumlichen Container, der gleichzeitig angezeigt wird, und weniger eingeschränkte Geräte unterstützen möglicherweise eine große Anzahl von räumlichen Containern, die gleichzeitig angezeigt werden, vorbehaltlich der Rendering-Rechenlimits.

Laufzeiten, die diese Erweiterung unterstützen, müssen mindestens einen der beiden Container (begrenzte räumliche Container oder immersive räumliche Container) unterstützen.

Gültige Verwendung (implizit)

Die Funktion xrEnumerateSupportedSpatialContainerGraphicsPresentationsEXT gibt die auf einem System unterstützten Methoden zur Grafikpräsentation zurück.

XrResult xrEnumerateSupportedSpatialContainerGraphicsPresentationsEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    graphicsPresentationCapacityInput,
    uint32_t*                                   graphicsPresentationCountOutput,
    XrSpatialContainerGraphicsPresentationEXT*  graphicsPresentations);

Parameterbeschreibungen

  • instance ist die XrInstance, aus der systemId abgerufen wurde.
  • systemId ist die abgefragte XrSystemId.
  • graphicsPresentationCapacityInput ist die Kapazität des graphicsPresentations-Arrays oder 0, um eine Anfrage zum Abrufen der erforderlichen Kapazität anzugeben.
  • graphicsPresentationCountOutput ist ein Zeiger auf die Anzahl der geschriebenen Grafikpräsentationen oder ein Zeiger auf die erforderliche Kapazität, wenn graphicsPresentationCapacityInput 0 ist.
  • graphicsPresentations ist ein Zeiger auf ein Array von XrSpatialContainerGraphicsPresentationEXT-Werten, kann aber null sein, wenn graphicsPresentationCapacityInput 0 ist.
  • Eine detaillierte Beschreibung zum Abrufen der erforderlichen graphicsPresentations-Größe finden Sie im Abschnitt Parameter für die Puffergröße.

Laufzeiten müssen für die angegebene systemId und für die Lebensdauer der Instanz immer identische Pufferinhalte aus dieser Aufzählung zurückgeben.

Gültige Verwendung (implizit)

Rückgabecodes

Erfolg

  • XR_SUCCESS

Fehler

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SYSTEM_INVALID
  • XR_ERROR_VALIDATION_FAILURE

Änderungen am Sitzungsstatus

Die Unterstützung von räumlichen Containern wird für eine Sitzung aktiviert, indem beim Aufrufen von xrCreateSession ein XrSessionCreateInfoSpatialContainersEXT verkettet wird.

typedef struct XrSessionCreateInfoSpatialContainersEXT {
    XrStructureType    type;
    const void*        next;
} XrSessionCreateInfoSpatialContainersEXT;

Wenn die Unterstützung für räumliche Container aktiviert ist, verhält sich eine XrSession anders. Das liegt daran, dass bei der Verwendung von räumlichen Containern die Sitzung keine Bildinhalte mehr auf den Displays anzeigt, sondern die räumlichen Container. Wenn diese Erweiterung aktiviert ist, ist eine Sitzung daher praktisch „headless“. Im Gegensatz zu anderen Headless-Erweiterungen können Apps Bilddaten über die räumlichen Container senden.

Durch die Aktivierung der Unterstützung für räumliche Container werden die wichtigsten OpenXR-APIs folgendermaßen geändert.

Laufzeit: Verlust des Systems oder Geräts

Laufzeit: Verlust des Systems oder Geräts

xrDestroySession

xrDestroySession

IDLE
(running)

IDLE...

xrGetSystem
xrCreateSession

xrGetSystem...

xrCreateInstance

xrCreateIn...

xrDestroySession

xrDestroySession

LOSS_PENDING
(nicht ausgeführt)

LOSS_PENDING...

xrDestroyInstance

xrDestroyInstance

App: optional
XR neu starten

app: optional...

Abbildung 19. Zustandsautomat für neue Sitzung

  • Die Sitzung wechselt nie in die Status XR_SESSION_STATE_VISIBLE, XR_SESSION_STATE_FOCUSED oder XR_SESSION_STATE_EXITING . Laufzeiten dürfen niemals Ereignisse für diese Status in die Warteschlange stellen. Diese Zustände werden durch die Ereignisse XrEventDataSpatialContainerVisibleChangedEXT, XrEventDataSpatialContainerInteractableChangedEXT und XrEventDataSpatialContainerClosedEXT für jeden räumlichen Container ersetzt.
  • Die Sitzung wechselt auch nie in die Status XR_SESSION_STATE_READY , XR_SESSION_STATE_SYNCHRONIZED , XR_SESSION_STATE_STOPPING . Laufzeiten dürfen niemals Ereignisse für diese Status in die Warteschlange stellen. Für diese Status gibt es keinen Ersatz.
  • Laufzeiten müssen die Sitzung als aktiv behandeln, wenn sie sich im Status XR_SESSION_STATE_IDLE befindet.
  • Laufzeiten müssen die Sitzung als fokussiert behandeln, wenn sie sich im Status XR_SESSION_STATE_IDLE befindet und mindestens ein räumlicher Container vorhanden ist, mit dem interagiert werden kann.
  • Die Funktionen xrBeginSession und xrEndSession sind nicht mehr erforderlich. Laufzeiten müssen XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT zurückgeben, wenn diese Funktionen aufgerufen werden. Andere Erweiterungen können Ersatz für diese Funktionen bieten.
  • Die Funktion xrRequestExitSession ist ebenfalls nicht mehr erforderlich. Laufzeiten müssen XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT zurückgeben, wenn diese Funktion aufgerufen wird. Apps, die eine laufende Sitzung beenden möchten, können xrRequestSpatialContainerVisibleEXT aufrufen, um ihre Container auszublenden, und die Sitzung beenden, nachdem alle Container nicht mehr sichtbar sind.

  • Erweiterungen, die zusätzliche Ereignisse in die Warteschlange stellen würden, wenn die Sitzung gestartet wird, müssen diese Ereignisse jetzt nach der Erstellung der Sitzung in die Warteschlange stellen. Diese Erweiterungen sind unten aufgeführt.

    Erweiterungsereignis

XR_EXT_user_presence

XrEventDataUserPresenceChangedEXT

XR_META_boundary_visibility

XrEventDataBoundaryVisibilityChangedMETA

  • Die Funktion xrLocateViews kann für die Sitzung nicht aufgerufen werden. Laufzeiten müssen XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT von xrLocateViews zurückgeben. Andere Erweiterungen bieten möglicherweise Möglichkeiten, die Ansichten für einen bestimmten räumlichen Container zu finden.
  • Die Funktion xrWaitFrame muss XrFrameState :: shouldRender immer auf „false“ setzen. Andere Erweiterungen können Möglichkeiten bieten, um festzustellen, ob ein bestimmter räumlicher Container seine Kompositionsebenen aktualisieren sollte.
  • Die Funktion xrEndFrame ist keine gültige Methode zum Senden von Kompositionsebenen. Wenn eine App XrFrameEndInfo :: layerCount auf einen Wert ungleich null setzt, müssen Laufzeiten XR_ERROR_VALIDATION_FAILURE zurückgeben. Andere Erweiterungen bieten möglicherweise Möglichkeiten, Kompositionsebenen für einen bestimmten räumlichen Container einzureichen.
  • Wenn der Status XR_SESSION_STATE_LOSS_PENDING aktiviert wird, werden auch alle räumlichen Container geschlossen. Laufzeiten müssen für jeden aktiven räumlichen Container ein XrEventDataSpatialContainerClosedEXT-Ereignis in die Warteschlange stellen, bevor sie eine Änderung des Sitzungsstatus für XR_SESSION_STATE_LOSS_PENDING in die Warteschlange stellen.
  • Die Funktion xrCreateSession benötigt keine Bindungsstruktur für die Grafik-API mehr. Andere Erweiterungen erfordern möglicherweise eine Grafikbindung, z. B. damit ein räumlicher Container mit einer Grafik-API gerendert werden kann.

Das obige Verhalten unterscheidet sich geringfügig vom Verhalten in XR_MND_headless . Laufzeiten dürfen das Headless-Sitzungsverhalten von XR_MND_headless nicht aktivieren, wenn die Unterstützung für räumliche Container für diese Sitzung aktiviert ist.

Hinweis

Wenn räumliche Container aktiviert sind, wechselt eine Sitzung nur zwischen zwei Zuständen: XR_SESSION_STATE_IDLE (wird ausgeführt) und XR_SESSION_STATE_LOSS_PENDING (wird nicht ausgeführt). Daher geben Laufzeiten nicht mehr XR_ERROR_SESSION_RUNNING oder XR_ERROR_SESSION_NOT_RUNNING zurück. Wenn keine Sitzung ausgeführt wird, geben Laufzeiten stattdessen entweder XR_ERROR_SESSION_LOST oder XR_SESSION_LOSS_PENDING gemäß den Regeln im OpenXR-Kern zurück. Außerdem gibt xrBeginSession, die einzige Funktion, die XR_ERROR_SESSION_RUNNING zurückgibt, jetzt immer XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT zurück.

Gültige Verwendung (implizit)

Android-Manifesteinträge

AOSP-basierte Laufzeiten können ein benutzerdefiniertes Verhalten aufweisen, das auf dem ursprünglichen Zustand des räumlichen Containers basiert, der vor dem Ausführen von App-Code gestartet wird. Eine Laufzeit kann beispielsweise die für die Aktivität zugewiesenen Ressourcen, die Startanimationen oder die Anzeige des Splash Screens ändern. Hierfür sind die folgenden Properties verfügbar. Sie ersetzen das Tag <category android:name="org.khronos.openxr.intent.category.IMMERSIVE_HMD" />, das von Apps, die auf räumlichen Containern basieren, nicht angegeben werden sollte, außer aus Gründen der Kompatibilität mit früheren AOSP-basierten Laufzeiten.

<property android:name="org.khronos.openxr.PROPERTY_ACTIVITY_HINT_XR_SPATIAL_CONTAINER_USED_BOUNDS_MODES"
          android:value="list of modes" />

Dieses Attribut gibt Laufzeiten Hinweise zu den von einer Aktivität verwendeten Begrenzungsmodi. Standardmäßig ist die Liste leer, was bedeutet, dass kein Hinweis vorhanden ist.

Die folgenden Strings sind für dieses Attribut gültig. Mehrere Werte werden durch | getrennt, z. B. "bounded|immersive".

Wert

Beschreibung

"2d_panel"

Die Aktivität wird mit dem 2D-Ansichts-Framework von Android angezeigt.

"bounded"

Bei der Aktivität wird XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT verwendet.

"immersive"

Bei der Aktivität wird XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT verwendet.

<property android:name="org.khronos.openxr.PROPERTY_ACTIVITY_HINT_XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE"
          android:value="XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_BOUNDED|
                         XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_IMMERSIVE|
                         XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_UNDEFINED" />

Diese Property gibt Laufzeiten den anfänglichen XrSpatialContainerBoundsModeEXT der Aktivität an, wenn sie zum ersten Mal erstellt wird. Standardmäßig ist dies der String XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_UNDEFINED, was bedeutet, dass kein Hinweis vorhanden ist.

Laufzeiten dürfen nicht erfordern, dass Apps diese Eigenschaften haben, um sich ansonsten gemäß dieser Spezifikation zu verhalten. Laufzeiten dürfen das sichtbare Verhalten von Apps nicht aufgrund dieser Eigenschaften ändern. Alle diese Metadaten müssen entweder auf der Ebene <activity> oder <application> angegeben werden können. Wenn sie auf der Ebene <application> angegeben wird, gilt sie für alle Aktivitäten in der Anwendung, für die keine eigenen Werte angegeben sind.

Beispielcode

Der folgende Code zeigt, wie diese Erweiterung für reine Wahrnehmungsanwendungsfälle ohne Rendering verwendet wird.

XrInstance instance;    // Already initialized


// Create the session with spatial containers enabled
XrSession session;

XrSessionCreateInfoSpatialContainersEXT spatialContainerCreateInfo {
  .type = XR_TYPE_SESSION_CREATE_INFO_SPATIAL_CONTAINERS_EXT,
};
XrSessionCreateInfo sessionCreateInfo {
  .type = XR_TYPE_SESSION_CREATE_INFO,
  .next = &spatialContainerCreateInfo,   // Enable spatial containers
};
(void)sessionCreateInfo.systemId;                             // Other create fields set in usual way

CHK_XR(xrCreateSession(instance, &sessionCreateInfo, &session));


// Because spatial containers are enabled, the session is considered
// running. App is able to query perception data such as head poses and hand
// poses.


// Based on app logic or when a system lost event happens, destroy the
// session
CHK_XR(xrDestroySession(session));

Neue Objekttypen

Neue Befehle

Neue Gebäude

Neue Enums

Neue Enum-Konstanten

  • XR_EXT_SPATIAL_CONTAINER_EXTENSION_NAME
  • XR_EXT_spatial_container_SPEC_VERSION

  • Erweiterung von XrObjectType :

    • XR_OBJECT_TYPE_SPATIAL_CONTAINER_EXT

  • Erweiterung von XrResult :

    • XR_ERROR_COMPATIBLE_SPATIAL_CONTAINER_MISSING_EXT
    • XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT
    • XR_ERROR_SPATIAL_CONTAINERS_NOT_ENABLED_EXT
    • XR_ERROR_SPATIAL_CONTAINER_CLOSED_EXT

  • Erweiterung von XrStructureType :

    • XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_BOUNDS_CHANGED_EXT
    • XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_BOUNDS_MODE_REQUEST_DENIED_EXT
    • XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_CLOSED_EXT
    • XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_INTERACTABLE_CHANGED_EXT
    • XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_VISIBLE_CHANGED_EXT
    • XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_VISIBLE_REQUEST_DENIED_EXT
    • XR_TYPE_SESSION_CREATE_INFO_SPATIAL_CONTAINERS_EXT
    • XR_TYPE_SPATIAL_CONTAINER_BOUNDS_EXT
    • XR_TYPE_SPATIAL_CONTAINER_BOUNDS_GET_INFO_EXT
    • XR_TYPE_SPATIAL_CONTAINER_BOUNDS_MODE_REQUEST_INFO_EXT
    • XR_TYPE_SPATIAL_CONTAINER_CREATE_INFO_EXT
    • XR_TYPE_SPATIAL_CONTAINER_SPACE_CREATE_INFO_EXT
    • XR_TYPE_SPATIAL_CONTAINER_STATE_EXT
    • XR_TYPE_SPATIAL_CONTAINER_STATE_GET_INFO_EXT
    • XR_TYPE_SPATIAL_CONTAINER_VISIBLE_REQUEST_INFO_EXT
    • XR_TYPE_SYSTEM_SPATIAL_CONTAINER_PROPERTIES_EXT

Probleme

  • Wie gehen wir mit mehreren ausstehenden sichtbaren Anfragen um? Sollte die App eine Änderung/Ablehnung oder mehrere erhalten? Die Antwort kann anders ausfallen, wenn die Aufrufe über mehrere Frames erfolgen. Die Antwort kann auch anders ausfallen, wenn die mehreren Anfragen zu einem Noop führen, d.h. wenn ein räumlicher Container sichtbar und dann nicht sichtbar sein soll, obwohl er anfangs nicht sichtbar war.

    • Gelöst. Verschiedene Optionen für Änderungsereignisse und abgelehnte Ereignisse. Noop-Anfragen stellen kein Änderungsereignis in die Warteschlange. Sie erzeugen nur Rauschen für den App-Entwickler und können von Laufzeiten leicht herausgefiltert werden. Wenn mehrere sichtbare Anfragen abgelehnt werden, müssen Laufzeiten jeweils ein entsprechendes Ablehnungsereignis generieren.

  • Wie wird eine Erweiterung für die Konformitätsautomatisierung definiert, damit der gesamte optionale Spezifikationstext für Richtlinienverhalten weiterhin vom CTS getestet werden kann?

    • Gelöst. Separate Testerweiterung. Es wird eine Test-Erweiterungslaufzeit nur für CTS implementiert, damit CTS die gesamte Systemrichtlinie steuern kann.

  • Benötigen wir ein Ereignis, wenn sich die Position eines räumlichen Containers ändert?

    • Gelöst. Nein. Der räumliche Containerbereich ist nicht an die Welt gebunden und andere solche Bereiche wie XR_REFERENCE_SPACE_TYPE_VIEW haben keine Ereignisse, wenn sie sich ändern.

  • Wie funktioniert xrSyncActions, wenn es mehrere räumliche Container gibt?

    • Gelöst. Es ist keine Änderung erforderlich. xrSyncActions würde auf alle räumlichen Container in der Sitzung angewendet werden. Wenn eine App die Eingabeaktionen an einen bestimmten räumlichen Container weiterleiten möchte, kann sie den interaktiven Status pro Container prüfen, um zu ermitteln, welche Container gültige Ziele sind. Wenn eine App nur den Status der Eingabeaktion für einen einzelnen räumlichen Container synchronisieren möchte, ist eine zusätzliche Erweiterung erforderlich. Wir gehen jedoch davon aus, dass wir uns stattdessen auf eine Erweiterung konzentrieren werden, mit der Apps vollständig ereignisbasiert sein können und kein xrSyncActions-Aufruf in einer Frame-Schleife erforderlich ist.

  • Wie gehen selten aktualisierte Apps mit Eingaben um?

    • Gelöst. Keine Änderung erforderlich. Sie ist zwar für EXT_spatial_container nützlich, aber auch außerhalb von räumlichen Containern. Dies kann über eine Ereigniskanal-Erweiterung erfolgen und funktioniert in beiden Fällen. Für räumliche Container werden wir zusätzliche Möglichkeiten zum Filtern von Ereignissen für einen einzelnen räumlichen Container hinzufügen.

  • Müssen wir die Eingabeschleife für Apps mit entkoppelten Eingabe- und Renderingschleifen drosseln oder steuern?

    • Gelöst. Keine Änderung erforderlich. Dies soll über den Ereigniskanal und die vorhandenen Anfrageerweiterungen abgewickelt werden. Mit der Erweiterung „Present Request“ kann das Rendering ereignisbasiert und von einer Frame-Schleife entkoppelt werden.

  • Kann ein räumlicher Container seine Position relativ zu anderen räumlichen Containern erhalten? Wichtige Überlegungen: Haben wir einen Anwendungsfall dafür? Und wenn ja, wie sind die räumlichen Containerbereiche mit LOCAL verbunden?

    • Gelöst. Ja. Dies ist bereits für räumliche Container innerhalb derselben Sitzung über XR_REFERENCE_SPACE_TYPE_VIEW möglich. Die Unterstützung von ansichtsabhängigen Inhalten ist wünschenswert. Wenn Sie räumliche Container-Positionen sitzungsübergreifend (z. B. für einen anderen Prozess) freigeben möchten, sollten Sie XR_EXT_spatial_anchor und die vorhandenen Persistenz- und Freigabemuster verwenden.

  • Ist der Raum eines räumlichen Containers lokalisierbar, wenn er nicht sichtbar ist?

    • Gelöst. Nein. Der Bereich des räumlichen Containers ist nicht auffindbar, wenn der räumliche Container nicht sichtbar ist. Das bedeutet, dass die App weder Spatial Audio unterstützt noch in der Lage ist, ansichtsabhängige Inhalte vorab zu laden, wenn der „spatial_container“ nicht sichtbar ist. Beide sind in Ordnung, da die App bei nicht sichtbarem räumlichen Container die CPU-/GPU-Last, die für diesen räumlichen Container verwendet wird, beenden sollte.

  • Wo soll der räumliche Containerbereich im räumlichen Container platziert werden? Vorschläge waren der Mittelpunkt oder der minimale Punkt (minX, minY, minZ).

    • Gelöst. In der Mitte. Es gibt keine Position, die sich nicht so bewegt, wie es bei der Größenänderung eines räumlichen Containers erwartet wird (Bewegen der Kanten). „Center“ wird häufig in anderen Teilen von OpenXR verwendet. Wir haben uns nicht an Fenstern im 2D-Computing orientiert, die die Mindestkoordinate verwenden, da 3D-Modell-Viewer dieser Konvention oft nicht folgen.

  • Wann wird von einer Laufzeit erwartet, dass sie Ressourcen erstellt, die dem räumlichen Container zugrunde liegen? Dazu ist manchmal eine IPC mit Systemdiensten erforderlich.

    • Gelöst. Synchron als Teil von xrCreateSpatialContainerEXT . Auch wenn IPC beteiligt sein kann, ist die tatsächliche Erstellung eines Containers im Allgemeinen kostengünstig. Einige Anbieter haben globale Mutexe für die Verwaltung von Containern, aber diese sollten normalerweise nicht zu langen Wartezeiten führen. Probleme mit Mutex-Konflikten sind herstellerspezifische Fehler, die von den jeweiligen Herstellern behoben werden sollten.

  • Benötigen wir ein Signal, dass eine XrSession räumliche Container erstellt und daher den alten Rendering-Pfad nicht unterstützt?

    • Gelöst. Ja. Wir ändern die Sitzungszustandsmaschine grundlegend.

Versionsverlauf

  • Version 1, 06.08.2026 (Jared Finder, Google)

    • Anfängliche Beschreibung der Erweiterung