XR_EXT_spatial_container

Name String

XR_EXT_spatial_container

Typ rozszerzenia

Rozszerzenie instancji

Zarejestrowany numer wewnętrzny

811

Wersja

1

Stan ratyfikacji

Nie ratyfikowano

Zależności rozszerzeń i wersji

OpenXR 1.0

Data ostatniej modyfikacji

2026-08-06

Stan IP

Brak znanych roszczeń dotyczących własności intelektualnej.

Twórcy

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

Przegląd

To rozszerzenie definiuje nową klasę elementów, które można wyświetlać, nazywanych „kontenerami przestrzennymi”, które są analogiczne do „okien” w systemach okienkowych 2D na komputerach.

W OpenXR 1.x aplikacje mają wyłączną kontrolę nad tym, co widzi użytkownik, i nad tym, jak jest to nakładane na rzeczywiste lub wirtualne środowisko użytkownika. Środowiska wykonawcze wprowadzają tylko niewielkie zmiany w wyświetlanych treściach, aby zapewnić bezpieczeństwo użytkowników. Ten model aplikacji jest dobry do zanurzenia użytkownika w jednym doświadczeniu, ale nie obejmuje wielu jednoczesnych doświadczeń. W szczególności w środowiskach AR i rzeczywistości mieszanej użytkownicy często chcą korzystać z kilku różnych aplikacji jednocześnie.

Kontenery przestrzenne są jak okna rozszerzone do 3D. Użytkownik może widzieć wiele kontenerów przestrzennych jednocześnie i wprowadzać dane do podzbioru z nich. Widoczne kontenery przestrzenne mogą należeć do różnych aplikacji, a środowiska wykonawcze zarządzają ich rozmiarem i umiejscowieniem w imieniu użytkownika.

To rozszerzenie obsługuje te nowe typy przestrzennie ograniczonych doświadczeń, a także istniejące immersyjne doświadczenia OpenXR. Ograniczone środowiska OpenXR mogą zawierać treści z lekkim efektem 3D (płaskie panele z niewielkimi przesunięciami głębi) lub woluminy, które zawierają treści w pełni 3D. Immersyjne środowiska OpenXR to istniejące aplikacje immersyjne na pełnym ekranie, które są obsługiwane od wersji OpenXR 1.0. Aplikacje mogą przełączać się między tymi 2 typami treści, jeśli jest to konieczne.

To rozszerzenie nie definiuje żadnej metody renderowania treści przez aplikację. Sposób rysowania treści jest zdefiniowany w innych rozszerzeniach: XR_EXT_spatial_container_self_rendering .

Używanie kontenerów przestrzennych

XrSpatialContainerEXT to uchwyt reprezentujący kontener przestrzenny.

XR_DEFINE_HANDLE(XrSpatialContainerEXT)

Aplikacja zaczyna renderowanie w kontenerze przestrzennym, wykonując te czynności:

  1. Utwórz kontener przestrzenny za pomocą xrCreateSpatialContainerEXT .
  2. Zmień dowolny stan kontenera na potrzeby początkowej prezentacji, np. tryb granic.
  3. Poproś środowisko wykonawcze o wyświetlenie kontenera za pomocą xrRequestSpatialContainerVisibleEXT .
  4. Poczekaj, aż środowisko wykonawcze będzie gotowe do wyświetlenia kontenera. Gdy środowisko wykonawcze jest gotowe, umieszcza w kolejce zdarzenie XrEventDataSpatialContainerVisibleChangedEXT, w którym parametr visible ma wartość XR_TRUE .
  5. Rozpocznij renderowanie kontenera przestrzennego.

Aby usunąć kontener przestrzenny:

  1. Poproś środowisko wykonawcze o ukrycie kontenera za pomocą xrRequestSpatialContainerVisibleEXT .
  2. Poczekaj, aż środowisko wykonawcze zakończy ukrywanie kontenera. Gdy środowisko wykonawcze całkowicie ukryje kontener, umieści w kolejce zdarzenie XrEventDataSpatialContainerVisibleChangedEXT z parametrem visible ustawionym na XR_FALSE .
  3. Zakończ renderowanie kontenera przestrzennego.
  4. Zniszcz kontener za pomocą xrDestroySpatialContainerEXT .

Uwaga

To rozszerzenie zostało zaprojektowane tak, aby przekazywać zarządzanie widocznością i fokusem poszczególnym kontenerom przestrzennym. Sesja jako całość nie reprezentuje już pojedynczego widocznego lub aktywnego obiektu, więc nie przechodzi przez standardową maszynę stanów OpenXR (READY, SYNCHRONIZED, VISIBLE, FOCUSED). Zamiast tego sesja pozostaje w stanie XR_SESSION_STATE_IDLE przez cały czas jej aktywności, a reguły opisane w sekcji Zmiany stanu sesji określają, jak podstawowe operacje OpenXR są mapowane na ten tryb.

Tworzenie kontenera przestrzennego

Funkcja xrCreateSpatialContainerEXT tworzy nowy kontener przestrzenny.

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

Opisy parametrów

Nowo utworzony obiekt XrSpatialContainerEXT musi być niewidoczny, nieinteraktywny i w trybie granic XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT . Aplikacja, która chce, aby kontener przestrzenny uruchamiał się w trybie imersji, może poprosić o tryb granic XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT przed wysłaniem prośby o wyświetlenie kontenera przestrzennego.

Środowiska wykonawcze muszą zwracać XR_ERROR_VALIDATION_FAILURE, jeśli dowolny wymiar XrSpatialContainerCreateInfoEXT :: suggestedBounds jest ujemny, nieskończony lub nie jest liczbą. Środowiska wykonawcze muszą zwracać XR_ERROR_LIMIT_REACHED, jeśli aplikacja próbuje utworzyć więcej kontenerów przestrzennych niż określono w XrSystemSpatialContainerPropertiesEXT :: maxSpatialContainerCount . Jeśli kontenery przestrzenne nie zostały włączone w tej sesji , środowiska wykonawcze muszą zwracać wartość XR_ERROR_SPATIAL_CONTAINERS_NOT_ENABLED_EXT .

Prawidłowe użycie (pośrednie)

Kody zwrotu

Sukces

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Błąd

  • 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

Struktura XrSpatialContainerCreateInfoEXT jest przekazywana do funkcji xrCreateSpatialContainerEXT w celu utworzenia kontenera przestrzennego.

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

Opis członka

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur. W podstawowym interfejsie OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.
  • graphicsPresentation to XrSpatialContainerGraphicsPresentationEXT, który opisuje, jak ten kontener przestrzenny prezentuje grafikę.
  • suggestedBounds to XrExtent3Df, który opisuje żądane wymiary kontenera przestrzennego w metrach.

Aplikacja, która nie ma preferencji dotyczących rozmiaru, może ustawić suggestedBounds na {0, 0, 0}. Środowisko wykonawcze może zignorować żądany suggestedBounds .

Środowisko wykonawcze, które umożliwia ograniczanie kontenerów przestrzennych za pomocą kształtów innych niż zorientowane pola, musi używać sugerowanych granic jako ramki ograniczającej wokół innych kształtów. Zorientowane pola są najczęściej używanym kształtem ograniczającym.

Prawidłowe użycie (pośrednie)

Gdy kontener przestrzenny nie nadaje się już do użytku, środowiska wykonawcze muszą dodać do kolejki zdarzenie XrEventDataSpatialContainerClosedEXT.

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

Opis członka

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur. W podstawowym interfejsie OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.
  • spatialContainer to XrSpatialContainerEXT, którego dotyczy to zdarzenie.

Otrzymanie zdarzenia XrEventDataSpatialContainerClosedEXT oznacza, że środowisko wykonawcze nie może już wyświetlać kontenera przestrzennego, na przykład dlatego, że użytkownik kliknął przycisk „Zamknij” lub sesja przeszła w stan XR_SESSION_STATE_LOSS_PENDING.

Po otrzymaniu zdarzenia XrEventDataSpatialContainerClosedEXT aplikacja powinna przestać używać tego kontenera przestrzennego, usunąć wszystkie powiązane stany, takie jak pętla renderowania, i zniszczyć kontener. Środowiska wykonawcze muszą zwracać XR_ERROR_SPATIAL_CONTAINER_CLOSED_EXT ze wszystkich funkcji działających w tym kontenerze innych niż xrDestroySpatialContainerEXT .

Jeśli kontener przestrzenny jest widoczny, gdy środowisko wykonawcze umieszcza w kolejce zdarzenie zamknięcia, środowiska wykonawcze muszą najpierw zmienić stan kontenera na niewidoczny i umieścić w kolejce zdarzenie XrEventDataSpatialContainerVisibleChangedEXT.

Prawidłowe użycie (pośrednie)

Funkcja xrDestroySpatialContainerEXT niszczy istniejący kontener przestrzenny.

XrResult xrDestroySpatialContainerEXT(
    XrSpatialContainerEXT                       spatialContainer);

Opisy parametrów

Po zniszczeniu kontenera przestrzennego środowiska wykonawcze nie mogą już wyświetlać jego zawartości ani dodawać do kolejki żadnych dodatkowych zdarzeń dotyczących kontenera.

Aplikacja nie powinna niszczyć widocznego kontenera przestrzennego, ponieważ może to spowodować błędy graficzne. Zamiast tego aplikacja powinna poprosić o ukrycie kontenera przestrzennego za pomocą xrRequestSpatialContainerVisibleEXT , poczekać na zdarzenie XrEventDataSpatialContainerVisibleChangedEXT, a następnie zniszczyć kontener.

Prawidłowe użycie (pośrednie)

Bezpieczeństwo wątków

  • Dostęp do spatialContainer i wszystkich uchwytów podrzędnych musi być synchronizowany zewnętrznie.

Kody zwrotu

Sukces

  • XR_SUCCESS

Błąd

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Przestrzeń kontenera przestrzennego

Funkcja xrCreateSpatialContainerSpaceEXT tworzy uchwyt XrSpace dla przestrzeni kontenera przestrzennego konkretnego kontenera przestrzennego.

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

Opisy parametrów

„Przestrzeń kontenera przestrzennego” dla danego kontenera przestrzennego to układ współrzędnych, którego początek znajduje się w środku granic tego kontenera. Ta przestrzeń jest zwykle używana jako przestrzeń podstawowa dla funkcji takich jak xrLocateSpace .

+X wskazuje prawą ścianę kontenera, +Y – górną, a +Z – przednią. Jeśli na przykład kontener jest wyrównany do grawitacji, znajduje się przed użytkownikiem, a użytkownik znajduje się w pozycji tożsamości względem przestrzeni LOCAL, środowiska wykonawcze muszą zorientować przestrzeń kontenera z orientacją tożsamości względem przestrzeni LOCAL . Środowiska wykonawcze mogą ustawić pozycję przestrzeni kontenera względem przestrzeni LOCAL na dowolną pozycję, gdy ten kontener stanie się widoczny.

konwencja przestrzeni kontenera przestrzennego ext

Rysunek 18. Konwencja osi przestrzeni kontenera przestrzennego

Przestrzeń kontenera przestrzennego to niepowiązany ze światem punkt początkowy. Aplikacje, które wymagają punktu początkowego zablokowanego w świecie w trybie imersji, mogą używać przestrzeni zablokowanej w świecie, takiej jak XR_REFERENCE_SPACE_TYPE_LOCAL .

Środowiska wykonawcze mogą w każdej chwili zmienić położenie przestrzeni kontenera przestrzennego, zwykle po to, aby umożliwić użytkownikowi przeniesienie kontenera przestrzennego w inne miejsce lub jego obrócenie. Środowiska wykonawcze mogą też zmieniać pozę podczas przechodzenia między trybami granic XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT i XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT.

Przestrzeń kontenera przestrzennego musi nadal być prawidłowym uchwytem, nawet jeśli kontener przestrzenny, do którego się odnosi, zostanie zniszczony za pomocą xrDestroySpatialContainerEXT . Gdy kontener przestrzenny jest niewidoczny lub zniszczony, przestrzeń kontenera przestrzennego musi być niemożliwa do zlokalizowania względem innych przestrzeni. XrSpaceLocation :: locationFlags i XrViewState ::viewStateFlags będą miały wartość 0.

Prawidłowe użycie (pośrednie)

Kody zwrotu

Sukces

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Błąd

  • 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 jest używany z xrCreateSpatialContainerSpaceEXT do tworzenia uchwytu XrSpace.

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

Opis członka

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur. W podstawowym interfejsie OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.
  • spatialContainer to XrSpatialContainerEXT, dla którego chcesz utworzyć przestrzeń.

Prawidłowe użycie (pośrednie)

Prezentowanie kontenera przestrzennego

Przesyłanie zawartości kontenera przestrzennego do OpenXR w celu wyświetlenia jest obsługiwane przez inne rozszerzenia: XR_EXT_spatial_container_self_rendering .

Aby umożliwić innym rozszerzeniom określanie metody prezentacji grafiki w kontenerze przestrzennym, to rozszerzenie definiuje typ wyliczeniowy 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;

Opis typu wyliczeniowego

XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SELF_RENDERING_EXT

Kontener przestrzenny używa warstw kompozycji OpenXR (dodanych przez rozszerzenie XR_EXT_spatial_container_self_rendering)

XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_CONFORMANCE_AUTOMATION_EXT

Kontener przestrzenny został utworzony na potrzeby testów zgodności i nie ma ścieżki renderowania (dodane przez rozszerzenie XR_EXT_spatial_container_conformance_automation)

XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SYSTEM_RENDERING_EXTX1

Kontener przestrzenny używa renderowania systemowego OpenXR (dodane przez rozszerzenie XR_EXTX1_system_renderer)

Stan kontenera przestrzennego

Stan kontenera przestrzennego jest zarządzany przez środowiska wykonawcze na podstawie żądań aplikacji i potrzeb użytkownika. Z tego powodu każdy aspekt stanu kontenera przestrzennego dokumentuje te elementy:

  • Gdy środowiska wykonawcze mogą zmieniać stan kontenera przestrzennego. W przypadku większości stanów kontenera przestrzennego środowiska wykonawcze mogą zmienić stan w dowolnym momencie.
  • Jak aplikacja prosi o zmianę stanu. Środowiska wykonawcze mogą odroczyć dowolne żądanie, dopóki nie uznają, że jest ono odpowiednie. Środowiska wykonawcze nie umieszczają zdarzeń w kolejce, gdy żądanie jest odroczone, więc aplikacje nie powinny czekać na takie zdarzenie w przypadku niepowiązanej logiki.
  • Jakie środowiska wykonawcze zdarzeń są umieszczane w kolejce, gdy zmienia się stan kontenera przestrzennego. Środowiska wykonawcze umieszczają w kolejce zdarzenia dotyczące wszystkich zmian, w tym zmian żądanych przez aplikację i zmian inicjowanych przez środowisko wykonawcze. Środowiska wykonawcze nie mogą umieszczać w kolejce zdarzeń zmiany stanu, które nie wskazują na zmianę, np. gdy aplikacja wysyła 2 żądania ukrycia kontenera w krótkich odstępach czasu.
  • Jakie środowiska wykonawcze zdarzeń są umieszczane w kolejce, gdy odrzucasz prośbę o zmianę aplikacji. Środowiska wykonawcze mogą odrzucić żądanie z dowolnego powodu, zwykle ze względu na zasady systemowe związane z zapewnianiem wysokiej jakości obsługi użytkowników.

Funkcja xrGetSpatialContainerStateEXT sprawdza bieżący stan kontenera przestrzennego.

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

Opisy parametrów

Prawidłowe użycie (pośrednie)

Kody zwrotu

Sukces

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Błąd

  • 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 jest używany z xrGetSpatialContainerStateEXT do wysyłania zapytań do XrSpatialContainerStateEXT .

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

Opis członka

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur. W podstawowym interfejsie OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.

Prawidłowe użycie (pośrednie)

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

Opis członka

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur. W podstawowym interfejsie OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.
  • visible określa, czy kontener przestrzenny jest widoczny.
  • interactable wskazuje, czy kontener przestrzenny może obecnie odbierać dane wejściowe dowolnego typu. Jest to podobne do „fokusu” w systemach okienkowych 2D na komputerach, z tą różnicą, że można wchodzić w interakcję z wieloma kontenerami przestrzennymi jednocześnie.
  • boundsMode to bieżący tryb XrSpatialContainerBoundsModeEXT kontenera przestrzennego.

Zmiany stanu kontenera przestrzennego są przekazywane za pomocą zdarzeń.

Zdarzenie zmiany pola

visible

XrEventDataSpatialContainerVisibleChangedEXT

interactable

XrEventDataSpatialContainerInteractableChangedEXT

boundsMode

XrEventDataSpatialContainerBoundsChangedEXT

Prawidłowe użycie (pośrednie)

Widoczność

Aplikacje żądają wyświetlenia lub ukrycia kontenera przestrzennego za pomocą funkcji xrRequestSpatialContainerVisibleEXT .

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

Opisy parametrów

Wyświetlanie lub ukrywanie kontenera przestrzennego jest operacją asynchroniczną.

Aplikacje powinny prosić o ukrycie kontenera przestrzennego przed jego zniszczeniem, aby środowiska wykonawcze mogły wyświetlić płynne przejście. Środowiska wykonawcze powinny uwzględniać żądania ukrycia kontenera przestrzennego.

Środowisko wykonawcze może odrzucić żądania wyświetlenia kontenera przestrzennego. W takim przypadku środowisko wykonawcze musi dodać do kolejki zdarzenie XrEventDataSpatialContainerVisibleRequestDeniedEXT. Na przykład niektóre środowiska wykonawcze odrzucą prośbę o wyświetlenie kontenera przestrzennego, który użytkownik ukrył, klikając przycisk „Minimalizuj” udostępniony przez system.

Środowiska wykonawcze nie mogą wyświetlać kontenera przestrzennego, dopóki aplikacja nie poprosi o jego wyświetlenie co najmniej raz. Po pierwszym żądaniu aplikacji dotyczącym wyświetlenia kontenera przestrzennego środowiska wykonawcze mogą zmienić widoczność tego kontenera niezależnie od żądań aplikacji. Dzięki temu aplikacja może kontrolować stan początkowy i zawartość kontenera przestrzennego, a środowiska wykonawcze mogą udostępniać interfejs systemowy, taki jak pasek zadań, który umożliwia użytkownikowi wybór widocznych kontenerów przestrzennych.

Środowiska wykonawcze muszą odrzucać żądania wyświetlenia kontenera przestrzennego w trybie granic, który nie jest obsługiwany na podstawie XrSystemSpatialContainerPropertiesEXT :: supportsBounded i XrSystemSpatialContainerPropertiesEXT :: supportsImmersive . Może się tak zdarzyć, gdy domyślny tryb granic, XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT, nie jest obsługiwany w danym systemie.

Uwaga

W niektórych implementacjach wyświetlanie lub ukrywanie kontenera przestrzennego wymaga komunikacji z usługami systemowymi i może zostać odroczone do momentu, gdy użytkownik wejdzie w interakcję z oknem systemowym. Asynchroniczny projekt żądania zmiany stanu widoczności ma na celu zapewnienie środowiskom wykonawczym czasu na wykonanie obu tych operacji.

Prawidłowe użycie (pośrednie)

Kody zwrotu

Sukces

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Błąd

  • 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 jest używany z xrRequestSpatialContainerVisibleEXT do zmiany widoczności kontenera przestrzennego.

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

Opis członka

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur. W podstawowym interfejsie OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.
  • visible wskazuje, czy kontener przestrzenny ma być wyświetlany czy ukryty.

Prawidłowe użycie (pośrednie)

Za każdym razem, gdy środowisko wykonawcze zmienia widoczność kontenera przestrzennego, musi dodać do kolejki zdarzenie XrEventDataSpatialContainerVisibleChangedEXT z nowym stanem.

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

Opis członka

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur. W podstawowym interfejsie OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.
  • spatialContainer to XrSpatialContainerEXT, którego dotyczy to zdarzenie.
  • visible to nowy stan widoczności kontenera przestrzennego.

To zdarzenie zastępuje zdarzenie XR_SESSION_STATE_VISIBLE , dzięki czemu wartość może być różna w poszczególnych kontenerach. Zdarzenie musi zostać dodane do kolejki w przypadku wszystkich zmian, w tym zmian żądanych przez aplikację i zmian zainicjowanych w czasie działania.

Środowisko wykonawcze może opóźnić renderowanie kontenera o kilka klatek po dodaniu tego zdarzenia do kolejki z parametrem visible ustawionym na XR_TRUE, aby uniknąć wyświetlania pustego kontenera i dać aplikacji czas na przesłanie początkowej zawartości. W tym czasie XrSpatialContainerStateEXT ::visible będzie mieć wartość XR_TRUE . Środowiska wykonawcze nie powinny opóźniać renderowania kontenera o więcej niż 0,5 sekundy.

Prawidłowe użycie (pośrednie)

Za każdym razem, gdy środowisko wykonawcze odrzuca żądanie wyświetlenia kontenera, musi dodać do kolejki zdarzenie XrEventDataSpatialContainerVisibleRequestDeniedEXT.

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

Opis członka

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur. W podstawowym interfejsie OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.
  • spatialContainer to XrSpatialContainerEXT, którego dotyczy to zdarzenie.

Prawidłowe użycie (pośrednie)

Interaktywny

Aplikacja nie może żądać, aby kontener przestrzenny był interaktywny. Środowiska wykonawcze w pełni kontrolują, które kontenery przestrzenne są interaktywne. Kontener przestrzenny, z którym można wejść w interakcję, musi być też widoczny.

Za każdym razem, gdy środowisko wykonawcze zmienia stan interaktywności kontenera przestrzennego, musi dodać do kolejki zdarzenie XrEventDataSpatialContainerInteractableChangedEXT z nowym stanem.

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

Opis członka

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur. W podstawowym interfejsie OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.
  • spatialContainer to XrSpatialContainerEXT, którego dotyczy to zdarzenie.
  • interactable to nowy stan interaktywny kontenera przestrzennego.

To zdarzenie zastępuje zdarzenie XR_SESSION_STATE_FOCUSED , dzięki czemu wartość może być różna w poszczególnych kontenerach. Zdarzenie jest umieszczane w kolejce w przypadku wszystkich zmian, w tym zmian zainicjowanych w czasie działania.

Środowiska wykonawcze mogą w każdej chwili włączyć lub wyłączyć interakcję z kontenerem przestrzennym. Jeśli środowisko wykonawcze obsługuje tylko 1 kontener przestrzenny, z którym można wejść w interakcję, to gdy środowisko wykonawcze zmienia kontener przestrzenny, z którym można wejść w interakcję, musi dodać do kolejki zdarzenie dla kontenera przestrzennego, z którym nie można już wejść w interakcję ( interactable ustawione na wartość false), przed zdarzeniem dla kontenera, z którym można wejść w interakcję ( interactable ustawione na wartość true).

Prawidłowe użycie (pośrednie)

Ograniczenia

Kontener przestrzenny ma tryb granic i ramkę ograniczającą. Tryb granic kontenera przestrzennego określa, jak zachowują się granice. Ramka ograniczająca to obszar, w którym rysowany jest kontener przestrzenny.

Wyliczenie XrSpatialContainerBoundsModeEXT określa różne tryby, w których mogą znajdować się granice kontenera przestrzennego.

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;

Opis typu wyliczeniowego

XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT

Kontener przestrzenny jest ograniczony. Granice są skończonym polem. Kontener przestrzenny będzie widoczny tylko w tym regionie.

XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT

Kontener przestrzenny jest immersyjny i ma nieskończone granice. Kontener przestrzenny jest wyświetlany na całym ekranie.

Kontenery przestrzenne w trybie granic XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT mają dodatkowe wymagania:

  • Środowiska wykonawcze muszą traktować te kontenery przestrzenne tak samo jak aplikacje pełnoekranowe i immersyjne utworzone bez użycia kontenera przestrzennego, z wyjątkiem zmian w zachowaniu opisanych w sekcji Zmiany stanu sesji .
  • Środowiska wykonawcze mogą udostępniać dodatkowe rozszerzenia, które umożliwiają kontenerom przestrzennym zachowywanie się inaczej niż aplikacje pełnoekranowe i aplikacje immersyjne utworzone bez tego rozszerzenia.
  • Środowiska wykonawcze muszą zgłaszać nieskończone granice tych kontenerów przestrzennych.
  • Środowiska wykonawcze mogą ukrywać inne kontenery przestrzenne, gdy widoczny jest immersyjny kontener przestrzenny. Ponieważ może się to różnić w zależności od środowiska wykonawczego, aplikacje nie powinny polegać na automatycznym wyświetlaniu lub ukrywaniu kontenerów przestrzennych na podstawie widoczności immersyjnego kontenera przestrzennego. Podobnie jak w przypadku wszystkich innych widocznych zmian stanu, środowiska wykonawcze muszą umieścić w kolejce zdarzenie XrEventDataSpatialContainerVisibleChangedEXT, gdy kontener przestrzenny jest ukryty, ponieważ kontener immersyjny jest widoczny.

Uwaga

Powyższe wymagania oznaczają, że wszystkie środowiska wykonawcze mogą implementować ścieżkę OpenXR 1.x bez tego rozszerzenia, niejawnie tworząc kontener przestrzenny, ustawiając tryb granic kontenera na immersyjny i żądając, aby był widoczny.

Aplikacje proszą o zmianę trybu granic kontenera przestrzennego za pomocą funkcji xrRequestSpatialContainerBoundsModeEXT .

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

Opisy parametrów

Zmiana trybu granic kontenera przestrzennego jest operacją asynchroniczną, a środowiska wykonawcze mogą dodać do kolejki zdarzenie zmiany lub odmowy wiele sekund po tym, jak aplikacja poprosi o zmianę. Dzięki temu środowiska wykonawcze mogą wyświetlać interfejs, który jest niezbędny, aby użytkownik mógł bezpiecznie przejść do trybu imersji.

Środowiska wykonawcze muszą uwzględniać żądanie zmiany trybu granic w przypadku niewidocznego kontenera przestrzennego. Jeśli środowisko wykonawcze odrzuci żądanie trybu granic dla niewidocznego kontenera, może odrzucić lub odroczyć żądanie wyświetlenia takiego kontenera przestrzennego. Dzięki temu aplikacje mogą uruchamiać kontener jako kontener immersyjny. Środowisko wykonawcze może odrzucić żądania zmiany trybu granic widocznego kontenera przestrzennego. W takim przypadku środowisko wykonawcze musi dodać do kolejki zdarzenie XrEventDataSpatialContainerBoundsModeRequestDeniedEXT. Na przykład niektóre środowiska wykonawcze odrzucą żądanie zmiany trybu granic widocznego kontenera przestrzennego, z którym użytkownik nie wchodzi aktywnie w interakcję.

Środowiska wykonawcze muszą zwracać XR_ERROR_VALIDATION_FAILURE, jeśli aplikacja żąda trybu granic, który nie jest obsługiwany na podstawie XrSystemSpatialContainerPropertiesEXT :: supportsBounded i XrSystemSpatialContainerPropertiesEXT :: supportsImmersive .

Prawidłowe użycie (pośrednie)

Kody zwrotu

Sukces

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Błąd

  • 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 jest używany z xrRequestSpatialContainerBoundsModeEXT do zmiany trybu granic kontenera przestrzennego.

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

Opis członka

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur. W podstawowym interfejsie OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.
  • boundsMode to żądany tryb XrSpatialContainerBoundsModeEXT dla kontenera przestrzennego.

Prawidłowe użycie (pośrednie)

Za każdym razem, gdy środowisko wykonawcze zmienia granice lub tryb granic kontenera przestrzennego, musi dodać do kolejki zdarzenie XrEventDataSpatialContainerBoundsChangedEXT z nowymi informacjami o granicach.

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

Opis członka

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur. W podstawowym interfejsie OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.
  • spatialContainer to XrSpatialContainerEXT, którego dotyczy to zdarzenie.
  • bounds to nowa szerokość, wysokość i głębokość granic kontenera przestrzennego.
  • infiniteBounds ma wartość „true”, jeśli kontener ma nieskończone granice.
  • boundsMode to nowy tryb XrSpatialContainerBoundsModeEXT kontenera przestrzennego.

Zdarzenie jest umieszczane w kolejce w przypadku wszystkich zmian, w tym zmian żądanych przez aplikację i zmian inicjowanych w czasie działania.

Gdy użytkownik interaktywnie zmienia rozmiar kontenera przestrzennego, środowiska wykonawcze muszą zachowywać się w jeden z tych sposobów:

  • kolejkować wiele zdarzeń, prawdopodobnie z częstotliwością klatek, gdy użytkownik zmienia rozmiar kontenera przestrzennego;
  • kolejkować pojedyncze zdarzenie na końcu zmiany rozmiaru,

Jeśli środowisko wykonawcze umieszcza w kolejce tylko jedno zdarzenie na końcu zmiany rozmiaru, musi nadal zgłaszać stare granice z xrGetSpatialContainerBoundsEXT, dopóki nie umieści w kolejce zdarzenia zmiany rozmiaru. Środowiska wykonawcze muszą łączyć wiele nieodpytywanych zdarzeń zmiany granic. Innymi słowy, jeśli granice lub tryb granic ulegną zmianie, gdy zdarzenie XrEventDataSpatialContainerBoundsChangedEXT jest nadal w kolejce, środowiska wykonawcze muszą zgłosić tylko jedno zdarzenie zawierające ostatnią zmianę granic. Ponieważ aplikacje mogą też bezpośrednio odpytywać granice kontenera przestrzennego za pomocą funkcji xrGetSpatialContainerBoundsEXT, liczba zmian granic wynikających ze zdarzeń może się różnić od liczby zmian wynikających z odpytywania w zależności od czasu zmian granic generowanych w czasie działania, wywołań xrPollEvent przez aplikację i wywołań xrGetSpatialContainerBoundsEXT przez aplikację.

Gdy zmieniają się granice kontenera przestrzennego, może się też zmienić jego lokalny punkt początkowy. Jeśli na przykład środowisko wykonawcze umożliwia użytkownikowi zmianę rozmiaru granic kontenera przestrzennego przez przeciągnięcie jednej z jego krawędzi, granice i lokalny punkt początkowy tego kontenera zmienią się, gdy użytkownik przeciągnie pojedynczą krawędź. W takich sytuacjach środowisko wykonawcze musi jednocześnie zmienić granice i lokalny punkt początkowy.

Środowiska wykonawcze muszą ustawić infiniteBounds na XR_TRUE, a szerokość, wysokość i głębokość na 0,0, aby reprezentować nieskończone granice. Środowiska wykonawcze muszą ustawić infiniteBounds na XR_FALSE oraz ustawić szerokość, wysokość i głębokość na skończone liczby dodatnie w przypadku skończonych granic.

Środowiska wykonawcze muszą ustawiać wartości bounds i infiniteBounds zgodnie z tymi samymi regułami co w przypadku XrSpatialContainerBoundsEXT .

Prawidłowe użycie (pośrednie)

Za każdym razem, gdy środowisko wykonawcze odrzuca żądanie zmiany trybu granic kontenera, musi dodać do kolejki zdarzenie XrEventDataSpatialContainerBoundsModeRequestDeniedEXT.

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

Opis członka

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur. W podstawowym interfejsie OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.
  • spatialContainer to XrSpatialContainerEXT, którego dotyczy to zdarzenie.

Prawidłowe użycie (pośrednie)

Struktura XrSpatialContainerBoundsEXT opisuje ramkę ograniczającą kontenera przestrzennego.

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

Opis członka

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur. W podstawowym interfejsie OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.
  • bounds to szerokość, wysokość i głębokość granic kontenera przestrzennego. Granice są podane w metrach.
  • infiniteBounds ma wartość „true”, jeśli kontener ma nieskończone granice.

Środowiska wykonawcze muszą ustawić infiniteBounds na XR_TRUE, a szerokość, wysokość i głębokość na 0,0, aby reprezentować nieskończone granice. Środowiska wykonawcze muszą ustawić infiniteBounds na XR_FALSE oraz szerokość, wysokość i głębokość na skończone liczby dodatnie w przypadku skończonych granic.

Prawidłowe użycie (pośrednie)

Funkcja xrGetSpatialContainerBoundsEXT wysyła zapytanie o bieżące granice kontenera przestrzennego.

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

Opisy parametrów

Kontener przestrzenny, który jest ograniczony, nie może mieć nieskończonych granic, a kontener przestrzenny, który jest immersyjny, musi mieć nieskończone granice.

Środowiska wykonawcze mogą w dowolnym momencie zmienić granice kontenera przestrzennego na dowolną dodatnią wartość skończoną, gdy kontener przestrzenny jest ograniczony. Zmiany granic kontenera przestrzennego są przekazywane za pomocą XrEventDataSpatialContainerBoundsChangedEXT .

Za pomocą tego rozszerzenia aplikacja nie może żądać zmian granic innych niż zmiana między trybem ograniczonym a trybem immersyjnym za pomocą xrRequestSpatialContainerBoundsModeEXT . W przyszłości mogą pojawić się inne rozszerzenia, które będą to umożliwiać.

Prawidłowe użycie (pośrednie)

Kody zwrotu

Sukces

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Błąd

  • 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

Struktura XrSpatialContainerBoundsGetInfoEXT to struktura wejściowa, która istnieje na potrzeby przyszłych rozszerzeń.

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

Opis członka

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur. W podstawowym interfejsie OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.

Prawidłowe użycie (pośrednie)

Wyliczenie XrSpatialContainerVolumeClippingEXT identyfikuje różne zachowania przycinania objętości w przypadku kontenera przestrzennego.

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;

Opis typu wyliczeniowego

XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_NONE_EXT

Żadna treść nie jest przycinana do objętości ograniczającej kontenera przestrzennego. Treści mogą być wyświetlane poza granicami kontenera przestrzennego.

XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_STRICT_EXT

Treści są ściśle przycinane do objętości ograniczającej kontenera przestrzennego.

To wyliczenie nie jest używane w tym rozszerzeniu. Jest zdefiniowany tak, aby umożliwić innym rozszerzeniom określenie pożądanego zachowania przycinania głośności. Na przykład aplikacja może chcieć narysować tło dla ograniczonego kontenera przestrzennego. Mapa sześcienna mono to wygodny sposób na określenie tła, ale koncepcyjnie jest ona umieszczona w nieskończoności, czyli poza kontenerem.

Możliwości systemu

Aplikacja może sprawdzać możliwości systemu, łącząc strukturę XrSystemSpatialContainerPropertiesEXT z XrSystemProperties podczas wywoływania xrGetSystemProperties .

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

Opis członka

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur. W podstawowym interfejsie OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.
  • maxSpatialContainerCount to maksymalna liczba kontenerów przestrzennych, które można utworzyć.
  • supportsBounded ma wartość „true”, jeśli kontenery przestrzenne mogą być ograniczone.
  • supportsImmersive ma wartość „true”, jeśli kontenery przestrzenne mogą być immersyjne.

Środowiska wykonawcze obsługujące to rozszerzenie powinny obsługiwać aplikację tworzącą wiele kontenerów przestrzennych, ograniczonych tylko przez alokację pamięci. Środowisko wykonawcze może mieć inny limit liczby jednocześnie wyświetlanych kontenerów przestrzennych. Nie można sprawdzić liczby jednocześnie wyświetlanych kontenerów w tym rozszerzeniu, ponieważ środowisko wykonawcze może ograniczać poszczególne aplikacje na podstawie stanu wszystkich uruchomionych aplikacji. Zakłada się, że urządzenia o dużych ograniczeniach i urządzenia o mniejszych ograniczeniach będą miały różne limity liczby jednocześnie wyświetlanych kontenerów. Urządzenia o dużych ograniczeniach mogą obsługiwać tylko 1 kontener przestrzenny wyświetlany jednocześnie, a urządzenia o mniejszych ograniczeniach mogą obsługiwać dużą liczbę kontenerów przestrzennych wyświetlanych jednocześnie, z uwzględnieniem limitów obliczeniowych renderowania.

Środowiska wykonawcze obsługujące to rozszerzenie muszą obsługiwać co najmniej 1 ograniczony kontener przestrzenny lub immersyjny kontener przestrzenny.

Prawidłowe użycie (pośrednie)

Funkcja xrEnumerateSupportedSpatialContainerGraphicsPresentationsEXT zwraca metody prezentacji grafiki obsługiwane w systemie.

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

Opisy parametrów

  • instance to XrInstance, z którego pobrano systemId.
  • systemId to XrSystemId, którego dotyczy zapytanie.
  • graphicsPresentationCapacityInput to pojemność tablicy graphicsPresentations lub 0, co oznacza prośbę o pobranie wymaganej pojemności.
  • graphicsPresentationCountOutput to wskaźnik do liczby zapisanych prezentacji graficznych lub wskaźnik do wymaganej pojemności, jeśli graphicsPresentationCapacityInput wynosi 0.
  • graphicsPresentations to wskaźnik do tablicy wartości XrSpatialContainerGraphicsPresentationEXT, ale może mieć wartość null, jeśli graphicsPresentationCapacityInput wynosi 0.
  • Szczegółowy opis pobierania wymaganego rozmiaru graphicsPresentations znajdziesz w sekcji Parametry rozmiaru bufora.

Środowiska wykonawcze muszą zawsze zwracać identyczną zawartość bufora z tego wyliczenia dla danego identyfikatora systemId i przez cały okres istnienia instancji.

Prawidłowe użycie (pośrednie)

Kody zwrotu

Sukces

  • XR_SUCCESS

Błąd

  • 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

Zmiany stanu sesji

Obsługa kontenerów przestrzennych jest włączana dla sesji przez połączenie XrSessionCreateInfoSpatialContainersEXT podczas wywoływania xrCreateSession .

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

Gdy włączona jest obsługa kontenerów przestrzennych, XrSession działa inaczej. Dzieje się tak, ponieważ podczas korzystania z kontenerów przestrzennych sesja nie wyświetla już treści obrazu na wyświetlaczach, tylko robią to kontenery przestrzenne. Dlatego po włączeniu tego rozszerzenia sesja jest „bezgłowa”. W przeciwieństwie do innych rozszerzeń bez interfejsu graficznego aplikacje mogą przesyłać dane obrazu za pomocą kontenerów przestrzennych.

Włączenie obsługi kontenera przestrzennego zmienia podstawowe interfejsy OpenXR API w następujący sposób.

runtime: losing system or device

runtime: losing system or device

xrDestroySession

xrDestroySession

IDLE
(uruchomiony)

BEZCZYNNY…

xrGetSystem
xrCreateSession

xrGetSystem...

xrCreateInstance

xrCreateIn...

xrDestroySession

xrDestroySession

LOSS_PENDING
(nieuruchomiony)

LOSS_PENDING...

xrDestroyInstance

xrDestroyInstance

aplikacji: opcjonalnie
uruchom ponownie XR

app: opcjonalnie…

Rysunek 19. Nowy automat stanu sesji

  • Sesja nigdy nie przechodzi w stan XR_SESSION_STATE_VISIBLE, XR_SESSION_STATE_FOCUSED ani XR_SESSION_STATE_EXITING . Środowiska wykonawcze nie mogą umieszczać zdarzeń w kolejce w przypadku tych stanów. Te stany są zastępowane przez zdarzenia kontenera przestrzennego: odpowiednio XrEventDataSpatialContainerVisibleChangedEXT, XrEventDataSpatialContainerInteractableChangedEXT i XrEventDataSpatialContainerClosedEXT.
  • Sesja nigdy nie przechodzi w stan XR_SESSION_STATE_READY, XR_SESSION_STATE_SYNCHRONIZED ani XR_SESSION_STATE_STOPPING . Środowiska wykonawcze nie mogą umieszczać zdarzeń w kolejce w przypadku tych stanów. Nie ma zamienników dla tych stanów.
  • Środowiska wykonawcze muszą traktować sesję jako uruchomioną, gdy jest ona w stanie XR_SESSION_STATE_IDLE .
  • Środowiska wykonawcze muszą traktować sesję jako aktywną, gdy jest ona w stanie XR_SESSION_STATE_IDLE i istnieje co najmniej 1 kontener przestrzenny, z którym można wejść w interakcję.
  • Funkcje xrBeginSession i xrEndSession nie są już potrzebne. Środowiska wykonawcze muszą zwracać XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT, gdy te funkcje są wywoływane. Inne rozszerzenia mogą udostępniać zamienniki tych funkcji.
  • Funkcja xrRequestExitSession również nie jest już potrzebna. Środowiska wykonawcze muszą zwracać XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT, gdy ta funkcja jest wywoływana. Aplikacje, które chcą zakończyć działającą sesję, mogą wywołać funkcję xrRequestSpatialContainerVisibleEXT, aby ukryć swoje kontenery, i zniszczyć sesję, gdy wszystkie kontenery przestaną być widoczne.

  • Rozszerzenia, które dodawałyby do kolejki dodatkowe zdarzenia po rozpoczęciu sesji, muszą teraz dodawać te zdarzenia do kolejki po utworzeniu sesji. Takie rozszerzenia są wymienione poniżej.

    Zdarzenie rozszerzenia

XR_EXT_user_presence

XrEventDataUserPresenceChangedEXT

XR_META_boundary_visibility

XrEventDataBoundaryVisibilityChangedMETA

  • Funkcji xrLocateViews nie można wywołać w sesji. Środowiska wykonawcze muszą zwracać XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT z xrLocateViews . Inne rozszerzenia mogą udostępniać sposoby lokalizowania widoków dla konkretnego kontenera przestrzennego.
  • Funkcja xrWaitFrame musi zawsze ustawiać wartość XrFrameState :: shouldRender na false. Inne rozszerzenia mogą udostępniać sposoby sprawdzania, czy dany kontener przestrzenny powinien aktualizować swoje warstwy kompozycji.
  • Funkcja xrEndFrame nie jest prawidłowym sposobem przesyłania warstw kompozycji. Jeśli aplikacja ustawia XrFrameEndInfo :: layerCount na wartość niezerową, środowiska wykonawcze muszą zwracać XR_ERROR_VALIDATION_FAILURE . Inne rozszerzenia mogą umożliwiać przesyłanie warstw kompozycji dla określonego kontenera przestrzennego.
  • Przejście do stanu XR_SESSION_STATE_LOSS_PENDING powoduje też zamknięcie wszystkich kontenerów przestrzennych. Środowiska wykonawcze muszą umieścić w kolejce zdarzenie XrEventDataSpatialContainerClosedEXT dla każdego aktywnego kontenera przestrzennego przed umieszczeniem w kolejce zmiany stanu sesji dla XR_SESSION_STATE_LOSS_PENDING .
  • Funkcja xrCreateSession nie wymaga już struktury powiązania interfejsu API grafiki. Inne rozszerzenia mogą wymagać powiązania graficznego, na przykład w celu renderowania kontenera przestrzennego za pomocą interfejsu API grafiki.

Powyższe zachowanie różni się nieco od zachowania w XR_MND_headless . Środowiska wykonawcze nie mogą włączać działania sesji bez interfejsu graficznego z XR_MND_headless, gdy w tej sesji jest włączona obsługa kontenera przestrzennego.

Uwaga

Gdy kontenery przestrzenne są włączone, sesja przechodzi tylko między 2 stanami: XR_SESSION_STATE_IDLE (uruchomiona) i XR_SESSION_STATE_LOSS_PENDING (nieuruchomiona). W rezultacie środowiska wykonawcze nie zwracają już wartości XR_ERROR_SESSION_RUNNING ani XR_ERROR_SESSION_NOT_RUNNING . Zamiast tego, gdy sesja nie jest uruchomiona, środowiska wykonawcze zwracają XR_ERROR_SESSION_LOST lub XR_SESSION_LOSS_PENDING zgodnie z regułami OpenXR Core. Ponadto funkcja xrBeginSession, która jako jedyna zwraca XR_ERROR_SESSION_RUNNING, będzie teraz zawsze zwracać XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT .

Prawidłowe użycie (pośrednie)

Wpisy w pliku manifestu Androida

Środowiska wykonawcze oparte na AOSP mogą mieć niestandardowe zachowanie na podstawie początkowego stanu kontenera przestrzennego, który jest uruchamiany przed uruchomieniem kodu aplikacji. Na przykład środowisko wykonawcze może zmienić zasoby przydzielone do aktywności, animacje uruchamiania lub wyświetlanie ekranu powitalnego. W tym celu udostępniamy te właściwości: Zastępują one tag <category android:name="org.khronos.openxr.intent.category.IMMERSIVE_HMD" />, którego aplikacje oparte na kontenerach przestrzennych nie powinny określać, z wyjątkiem sytuacji, gdy jest to konieczne do zapewnienia zgodności z wcześniejszymi środowiskami wykonawczymi opartymi na AOSP.

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

Ta właściwość wskazuje środowiskom wykonawczym tryby granic używane przez aktywność. Domyślnie jest to pusta lista, co oznacza brak wskazówek.

W przypadku tego atrybutu prawidłowe są te ciągi znaków. Wiele wartości jest rozdzielonych znakiem | , np. "bounded|immersive".

Wartość

Opis

"2d_panel"

Aktywność jest wyświetlana przy użyciu platformy widoku 2D Androida.

"bounded"

Aktywność korzysta z usługi XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT .

"immersive"

Aktywność korzysta z usługi XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT .

<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" />

Ta właściwość wskazuje środowiskom wykonawczym początkowy tryb XrSpatialContainerBoundsModeEXT aktywności podczas jej tworzenia. Domyślnie jest to ciąg znaków XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_UNDEFINED, który nie zawiera żadnych wskazówek.

Środowiska wykonawcze nie mogą wymagać, aby aplikacje miały te właściwości, aby zachowywały się zgodnie z tą specyfikacją. Środowiska wykonawcze nie mogą zmieniać widocznego zachowania aplikacji na podstawie tych właściwości. Wszystkie takie metadane muszą być możliwe do określenia na poziomie <activity> lub <application>. Jeśli jest określony na poziomie <application>, dotyczy wszystkich aktywności w aplikacji, które nie mają określonych własnych wartości.

Przykładowy kod

Poniższy kod pokazuje, jak używać tego rozszerzenia w przypadkach użycia związanych tylko z percepcją, bez renderowania.

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));

Nowe typy obiektów

Nowe polecenia

Nowe domy

Nowe wartości w polu enum

Nowe stałe typu wyliczeniowego

  • XR_EXT_SPATIAL_CONTAINER_EXTENSION_NAME
  • XR_EXT_spatial_container_SPEC_VERSION

  • Rozszerzanie XrObjectType :

    • XR_OBJECT_TYPE_SPATIAL_CONTAINER_EXT

  • Rozszerzenie 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

  • Rozszerzanie 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

Problemy

  • Jak postępujemy w przypadku wielu oczekujących widocznych żądań? Czy aplikacja powinna otrzymać jedną zmianę / odmowę czy kilka? Odpowiedź może być inna, jeśli wywołania są rozłożone na wiele klatek. Odpowiedź może być też inna, jeśli wiele żądań spowoduje brak operacji, np. żądanie, aby kontener przestrzenny był widoczny, a następnie niewidoczny, w przypadku kontenera, który na początku jest niewidoczny.

    • Rozwiązane. Różne opcje zdarzeń zmiany i odmowy. Żądania Noop nie powodują dodania zdarzenia zmiany do kolejki. Generują tylko szum dla dewelopera aplikacji i są łatwe do odfiltrowania przez środowiska wykonawcze. Jeśli kilka widocznych żądań zostanie odrzuconych, środowiska wykonawcze muszą wygenerować odpowiednie zdarzenie odrzucenia.

  • Jak należy zdefiniować rozszerzenie automatyzacji zgodności, aby cały opcjonalny tekst specyfikacji dotyczący zachowań zasad był nadal testowany przez CTS?

    • Rozwiązane. Oddzielne rozszerzenie testowe. Wprowadzimy środowiska wykonawcze rozszerzeń testowych tylko dla CTS, co pozwoli CTS kontrolować wszystkie zasady systemowe.

  • Do we need an event for when a spatial container’s position changes?

    • Rozwiązane. No. The spatial container space is non-world locked and other such spaces, like XR_REFERENCE_SPACE_TYPE_VIEW , do not have events when they change.

  • Jak działa xrSyncActions, jeśli jest wiele kontenerów przestrzennych?

    • Rozwiązane. Nie trzeba nic zmieniać. xrSyncActions będzie dotyczyć wszystkich kontenerów przestrzennych w sesji. Jeśli aplikacja chce skierować działania wejściowe do konkretnego kontenera przestrzennego, może sprawdzić stan interaktywności poszczególnych kontenerów, aby wybrać, które z nich są odpowiednimi celami. Jeśli aplikacja chce synchronizować stan działania wejściowego tylko w przypadku jednego kontenera przestrzennego, wymaga to dodatkowego rozszerzenia. Zamiast tego planujemy skupić się na rozszerzeniu, które umożliwia aplikacjom pełne działanie na podstawie zdarzeń i pozwala uniknąć konieczności wywoływania funkcji xrSyncActions w pętli klatek.

  • Jak aplikacje, które są rzadko aktualizowane, radzą sobie z danymi wejściowymi?

    • Rozwiązane. Nie musisz nic zmieniać. Chociaż jest to przydatne w przypadku EXT_spatial_container, jest też przydatne poza kontenerami przestrzennymi. Można to zrobić za pomocą rozszerzenia kanału zdarzeń, które działa w obu przypadkach. W przypadku kontenerów przestrzennych dodamy dodatkowe sposoby filtrowania zdarzeń w jednym kontenerze przestrzennym.

  • Czy w przypadku aplikacji z rozdzielonymi pętlami wejściowymi i renderowania musimy czekać na ograniczenie lub kontrolowanie czasu pętli wejściowej?

    • Rozwiązane. Nie musisz nic zmieniać. Powinno to być obsługiwane przez kanał zdarzeń i obecne rozszerzenia żądań. Rozszerzenie Present request umożliwia renderowanie oparte na zdarzeniach i niezależne od pętli klatek.

  • Czy kontener przestrzenny może uzyskać swoją pozycję względem innych kontenerów przestrzennych? Najważniejsze pytania: czy mamy przypadek użycia dla tej funkcji? Jeśli tak, jak przestrzenie kontenera przestrzennego łączą się z przestrzenią LOCAL?

    • Rozwiązane. Tak. Jest to już możliwe w przypadku kontenerów przestrzennych w tej samej sesji, gdy używasz XR_REFERENCE_SPACE_TYPE_VIEW, a obsługa treści zależnych od widoku jest pożądana. Aby udostępniać pozycje kontenera przestrzennego między sesjami (np. innemu procesowi), zalecamy korzystanie z XR_EXT_spatial_anchor oraz istniejących wzorców trwałości i udostępniania.

  • Czy przestrzeń kontenera przestrzennego można zlokalizować, jeśli nie jest widoczna?

    • Rozwiązane. Nie. Przestrzeń kontenera przestrzennego nie jest możliwa do zlokalizowania, gdy kontener przestrzenny nie jest widoczny. Oznacza to, że nie ma dźwięku przestrzennego, a aplikacja nie może „przygotować” treści zależnych od widoku, gdy element spatial_container nie jest widoczny. Oba te rozwiązania są prawidłowe, ponieważ gdy kontener przestrzenny nie jest widoczny, aplikacja powinna zatrzymać obciążenie procesora lub GPU, które jest używane na potrzeby tego kontenera.

  • Gdzie w kontenerze przestrzennym ma być umieszczona przestrzeń kontenera przestrzennego? Sugestie były środkiem lub punktem minimalnym (minX, minY, minZ).

    • Rozwiązane. Na środku. Nie ma lokalizacji, która nie zmienia się w większości przypadków, gdy oczekiwany jest interfejs zmiany rozmiaru kontenera przestrzennego (przesuwanie krawędzi). Środek jest powszechnie używany w innych częściach OpenXR. Nie dopasowaliśmy ich do okien w obliczeniach 2D, które używają minimalnej współrzędnej, ponieważ przeglądarki modeli 3D często nie stosują się do tej konwencji.

  • Kiedy środowisko wykonawcze powinno utworzyć zasoby leżące u podstaw kontenera przestrzennego? Czasami wiąże się to z komunikacją między procesami z usługami systemowymi.

    • Rozwiązane. Synchronously as part of xrCreateSpatialContainerEXT . Chociaż może to wymagać komunikacji między procesami, samo utworzenie kontenera powinno być zwykle tanie. Niektórzy dostawcy mają globalne muteksy do zarządzania kontenerami, ale zwykle nie trzeba długo czekać. Problemy z rywalizacją o mutex to błędy specyficzne dla dostawcy, które powinny zostać rozwiązane przez każdego dostawcę.

  • Czy potrzebujemy sygnału, że XrSession utworzy kontenery przestrzenne i w związku z tym nie będzie obsługiwać starszej ścieżki renderowania?

    • Rozwiązane. Tak. Zmieniamy maszynę stanu sesji w zasadniczy sposób.

Historia zmian

  • Wersja 1, 6 sierpnia 2026 r. (Jared Finder, Google)

    • Początkowy opis rozszerzenia