XR_EXT_spatial_entity

Name String

XR_EXT_spatial_entity

Typ rozszerzenia

Rozszerzenie instancji

Zarejestrowany numer wewnętrzny

741

Wersja

1

Stan ratyfikacji

Ratified

Zależności rozszerzeń i wersji

XR_EXT_future

Twórcy

Nihav Jain, Google
Jared Finder, Google
Natalie Fleury, Meta
Yuichi Taguchi, Meta
Ron Bessems, Meta
Yin Li, Microsoft
Karthik Kadappan, Magic Leap
Jimmy Alamparambil, ByteDance
Zhipeng Liu, ByteDance
Jun Yan, ByteDance

Przegląd

To rozszerzenie wprowadza koncepcje i podstawy rozpoznawania scen i rozumowania przestrzennego w OpenXR. Ujednolica to kilka powiązanych, ale odrębnych obszarów funkcjonalności, które są wyliczane, konfigurowane i używane w ogólnie jednolity sposób, zgodnie z definicją tego rozszerzenia. Ponieważ w tym rozszerzeniu brakuje konkretnych definicji któregokolwiek z tych obszarów funkcjonalnych, tekst formalnej specyfikacji jest nieco abstrakcyjny. Przykłady zawarte w tym tekście specyfikacji rozszerzenia odnoszą się czasami do funkcji zdefiniowanych w nadchodzącym lub hipotetycznym powiązanym rozszerzeniu w celu ilustracji, bez nieodłącznego ograniczania lub określania takich dodatkowych funkcji.

Główne elementy tego rozszerzenia to:

  • Elementy przestrzenne: funkcje są skoncentrowane wokół elementów , które same w sobie zapewniają bardzo ograniczoną funkcjonalność.
  • Komponenty przestrzenne: te elementy mają powiązane komponenty, które dostarczają dane i zachowania.
  • Typy komponentów przestrzennych: każdy komponent przestrzenny ma określony typ komponentu , a każdy element ma co najwyżej 1 komponent danego typu .
  • Kontekst przestrzenny: wszystkie interakcje z elementami przestrzennymi odbywają się w kontekście po fazie inicjowania i konfiguracji.
  • Funkcje przestrzenne: manipulowanie elementami przestrzennymi jest w dużej mierze możliwe dzięki funkcjom . Funkcja to jednostka funkcjonalności, np. (bez ograniczeń) kotwice zdefiniowane przez aplikację, wykrywanie płaszczyzny lub śledzenie obrazu. Każda funkcja jest zwykle definiowana w osobnym rozszerzeniu (włączanym podczas tworzenia instancji) i włączana dla określonego kontekstu w momencie tworzenia.
  • Każda funkcja jest powiązana z zestawem typów komponentów, dla których komponenty są obecne w każdym elemencie udostępnianym przez tę funkcję . Rozszerzenie definiujące funkcję określa, które typy komponentów są dla niej obowiązkowe („gwarantowane”), a to samo rozszerzenie lub inne mogą określać opcjonalne typy komponentów udostępniane przez niektóre potencjalne implementacje. Dowolna liczba funkcji może dostarczać encjom komponenty danego typu, które są jednolicie użyteczne niezależnie od funkcji, która je wygenerowała.
  • Funkcje możliwości przestrzennych : niektóre możliwości wymagają konfiguracji, dlatego są parametryzowane przez funkcje możliwości .

To rozszerzenie udostępnia mechanizm wyliczania komponentów dostarczanych przez każdą funkcję obsługiwaną w bieżącym systemie, zarówno obowiązkowych, jak i opcjonalnych komponentów .

Niektóre implementacje mogą wymagać różnych poziomów parametryzacji funkcji , dlatego to rozszerzenie udostępnia mechanizm wyliczania obsługiwanych funkcji powiązanych z daną funkcją w bieżącym systemie.

To rozszerzenie definiuje też kilka typowych komponentów, które powinny być używane w szerokim zakresie funkcji .

Podmiot przestrzenny

Encje przestrzenne to encje, które istnieją w jakiejś przestrzeni i mają różne powiązane dane uporządkowane w komponenty. Może to być dowolny z tych elementów:

  • fizyczne (np. płaskie powierzchnie, takie jak ściany i podłogi, obiekty, takie jak krzesła i regały itp.);
  • wirtualne (np. treści umieszczone i udostępnione przez inną aplikację lub innego użytkownika),
  • Zdefiniowane przez aplikację (np. aplikacja oznaczająca obszar jako „salon” lub „kuchnia” albo oznaczająca punkt jako lokalizację, w której ma zostać umieszczony telewizor itp.)

Elementy, które są udostępniane przez system działań, takie jak kontrolery czy spojrzenie, nie powinny być modelowane jako elementy przestrzenne.

Elementy przestrzenne w OpenXR są modelowane jako system Entity-Component . Każda encja przestrzenna ma zestaw komponentów, a każdy komponent zapewnia unikalny zestaw danych i zachowań dla tej encji.

Elementy przestrzenne są reprezentowane przez atom XrSpatialEntityIdEXT lub uchwyt XrSpatialEntityEXT, których szczegóły znajdziesz w sekcji Reprezentacje elementów przestrzennych.

Typy komponentów przestrzennych

Encja przestrzenna ma co najmniej 1 komponent, który dostarcza jej dane lub zachowania. Więcej informacji o niektórych typowych komponentach zdefiniowanych przez to rozszerzenie znajdziesz w sekcji Typowe komponenty.

typedef enum XrSpatialComponentTypeEXT {
    XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT = 1,
    XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT = 2,
    XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT = 3,
    XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT = 4,
    XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT = 1000741000,
    XR_SPATIAL_COMPONENT_TYPE_MESH_2D_EXT = 1000741001,
    XR_SPATIAL_COMPONENT_TYPE_POLYGON_2D_EXT = 1000741002,
    XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT = 1000741003,
    XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT = 1000743000,
    XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT = 1000744000,
    XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT = 1000744001,
    XR_SPATIAL_COMPONENT_TYPE_MOUSE_SEMANTIC_LABEL_EXT = 1000744002,
    XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT = 1000762000,
    XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT = 1000763000,
    XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT = 1000782000,
    XR_SPATIAL_COMPONENT_TYPE_MESH_3D_NORMALS_EXT = 1000783000,
    XR_SPATIAL_COMPONENT_TYPE_MESH_3D_VERTEX_SEMANTIC_LABELS_EXT = 1000783001,
    XR_SPATIAL_COMPONENT_TYPE_MESH_3D_TRIANGLE_SEMANTIC_LABELS_EXT = 1000783002,
    XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_ANDROID = 1000785000,
    XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID = 1000786000,
    XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID = 1000791000,
    XR_SPATIAL_COMPONENT_TYPE_ROOM_ANDROIDSYS = 1000792002,
    XR_SPATIAL_COMPONENT_TYPE_MATERIAL_TYPE_ANDROIDSYS = 1000792003,
    XR_SPATIAL_COMPONENT_TYPE_CONFIDENCE_ANDROIDSYS = 1000792004,
    XR_SPATIAL_COMPONENT_TYPE_ROOM_EMPTINESS_ANDROIDSYS = 1000792005,
    XR_SPATIAL_COMPONENT_TYPE_OCCUPANCY_GRID_ANDROIDX1 = 1000793000,
    XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID = 1000794000,
    XR_SPATIAL_COMPONENT_TYPE_STREETSCAPE_GEOMETRY_METADATA_ANDROIDX2 = 1000798000,
    XR_SPATIAL_COMPONENT_TYPE_GEOMETRY_POINT_ANDROID = 1000803000,
    XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_SCOPES_ANDROIDX1 = 1000808000,
    XR_SPATIAL_COMPONENT_TYPE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialComponentTypeEXT;

Wyliczenie XrSpatialComponentTypeEXT identyfikuje różne typy komponentów, które środowisko wykonawcze może obsługiwać.

Nie wszystkie wymienione typy komponentów są dostarczane przez to rozszerzenie: niektóre wymagają włączenia dodatkowych rozszerzeń podczas tworzenia instancji, zgodnie z dokumentacją.

Elementy wyliczenia mają te wartości:

Opis typu wyliczeniowego

XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

Komponent, który udostępnia granice 2D elementu przestrzennego. Odpowiednia struktura listy to XrSpatialComponentBounded2DListEXT, a odpowiednia struktura danych to XrSpatialBounded2DDataEXT.

XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT

Komponent, który zapewnia granice 3D dla encji przestrzennej. Odpowiednia struktura listy to XrSpatialComponentBounded3DListEXT, a odpowiednia struktura danych to XrBoxf.

XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT

Komponent, który podaje XrSpatialEntityIdEXT elementu nadrzędnego dla encji przestrzennej. Odpowiednia struktura listy to XrSpatialComponentParentListEXT. Odpowiednia struktura danych to XrSpatialEntityIdEXT

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT

Komponent, który udostępnia siatkę 3D dla encji przestrzennej. Odpowiednia struktura listy to XrSpatialComponentMesh3DListEXT, a odpowiednia struktura danych to XrSpatialMeshDataEXT.

XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT

Komponent, który udostępnia typ wyliczeniowy wyrównania płaszczyzny dla encji przestrzennej. Odpowiednia struktura listy to XrSpatialComponentPlaneAlignmentListEXT, a odpowiednia struktura danych to XrSpatialPlaneAlignmentEXT (dodana przez rozszerzenie XR_EXT_spatial_plane_tracking).

XR_SPATIAL_COMPONENT_TYPE_MESH_2D_EXT

Komponent, który udostępnia siatkę 2D dla encji przestrzennej. Odpowiednia struktura listy to XrSpatialComponentMesh2DListEXT, a odpowiednia struktura danych to XrSpatialMeshDataEXT (dodana przez rozszerzenie XR_EXT_spatial_plane_tracking).

XR_SPATIAL_COMPONENT_TYPE_POLYGON_2D_EXT

Komponent, który udostępnia wielokąt granicy 2D dla encji przestrzennej. Odpowiednia struktura listy to XrSpatialComponentPolygon2DListEXT. Odpowiednia struktura danych to XrSpatialPolygon2DDataEXT (dodana przez rozszerzenie XR_EXT_spatial_plane_tracking).

XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT

Komponent, który udostępnia etykietę semantyczną dla płaszczyzny. Odpowiednia struktura listy to XrSpatialComponentPlaneSemanticLabelListEXT, a odpowiednia struktura danych to XrSpatialPlaneSemanticLabelEXT (dodana przez rozszerzenie XR_EXT_spatial_plane_tracking).

XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT

Komponent opisujący typ, identyfikator i lokalizację znacznika. Odpowiednia struktura listy to XrSpatialComponentMarkerListEXT, a odpowiednia struktura danych to XrSpatialMarkerDataEXT (dodane przez rozszerzenie XR_EXT_spatial_marker_tracking).

XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT

Komponent, który udostępnia etykietę semantyczną sceny. Odpowiednia struktura listy to XrSpatialComponentObjectSemanticLabelListEXT. Odpowiednia struktura danych to XrSpatialObjectSemanticLabelEXT . (dodane przez rozszerzenie XR_EXT_spatial_object_tracking)

XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT

Komponent, który udostępnia etykietę semantyczną klawiatury. Odpowiednia struktura listy to XrSpatialComponentKeyboardSemanticLabelListEXT. Odpowiednia struktura danych to XrSpatialKeyboardSemanticLabelEXT (dodana przez rozszerzenie XR_EXT_spatial_object_tracking).

XR_SPATIAL_COMPONENT_TYPE_MOUSE_SEMANTIC_LABEL_EXT

Komponent, który udostępnia etykietę semantyczną myszy. Odpowiednia struktura listy to XrSpatialComponentMouseSemanticLabelListEXT. Odpowiednia struktura danych to XrSpatialMouseSemanticLabelEXT (dodana przez rozszerzenie XR_EXT_spatial_object_tracking).

XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT

Komponent, który podaje lokalizację kotwicy. Odpowiednia struktura listy to XrSpatialComponentAnchorListEXT, a odpowiednia struktura danych to XrPosef (dodana przez rozszerzenie XR_EXT_spatial_anchor).

XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT

Komponent, który udostępnia trwały identyfikator UUID encji przestrzennej. Odpowiednia struktura listy to XrSpatialComponentPersistenceListEXT, a odpowiednia struktura danych to XrSpatialPersistenceDataEXT (dodane przez rozszerzenie XR_EXT_spatial_persistence).

XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT

Komponent opisujący typ obrazu planarnego. Odpowiednia struktura listy to XrSpatialComponentImage2DListEXT, a odpowiednia struktura danych to XrSpatialImageSizeEXT . (dodane przez rozszerzenie XR_EXT_spatial_image_tracking)

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_NORMALS_EXT

Komponent, który dostarcza wektory normalne dla siatki 3D elementu przestrzennego. Odpowiednia struktura listy to XrSpatialComponentMesh3DNormalsListEXT, a odpowiednia struktura danych to XrSpatialBufferEXT (dodana przez rozszerzenie XR_EXT_spatial_mesh_tracking).

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_VERTEX_SEMANTIC_LABELS_EXT

Komponent, który dostarcza etykiety semantyczne dla każdego wierzchołka siatki 3D elementu przestrzennego. Odpowiednia struktura listy to XrSpatialComponentMesh3DVertexSemanticLabelsListEXT. Odpowiednia struktura danych to XrSpatialBufferEXT. Dane w buforze są mapowane na XrSpatialMeshSemanticLabelEXT (dodane przez rozszerzenie XR_EXT_spatial_mesh_tracking).

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_TRIANGLE_SEMANTIC_LABELS_EXT

Komponent, który dostarcza etykiety semantyczne dla każdej powierzchni trójkąta siatki 3D elementu przestrzennego. Odpowiednia struktura listy to XrSpatialComponentMesh3DTriangleSemanticLabelsListEXT. Odpowiednia struktura danych to XrSpatialBufferEXT. Dane w buforze są mapowane na XrSpatialMeshSemanticLabelEXT (dodane przez rozszerzenie XR_EXT_spatial_mesh_tracking).

XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_ANDROID

Komponent, który udostępnia etykietę semantyczną obiektu. Odpowiednia struktura listy to XrSpatialComponentObjectSemanticLabelListANDROID. Odpowiednia struktura danych to XrSpatialObjectSemanticLabelANDROID (dodana przez rozszerzenie XR_ANDROID_spatial_object_tracking).

XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID

Komponent, który podaje pozycję trafienia promienia w element. Odpowiednia struktura listy to XrSpatialComponentRaycastResultListANDROID, a odpowiednia struktura danych to XrSpatialRaycastResultDataANDROID (dodane przez rozszerzenie XR_ANDROID_spatial_discovery_raycast).

XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID

Komponent, który podaje identyfikator encji nadrzędnej względem dołączonej encji. Odpowiednia struktura listy to XrSpatialComponentSubsumedByListANDROID. Odpowiednia struktura danych to XrSpatialEntityIdEXT (dodana przez rozszerzenie XR_ANDROID_spatial_component_subsumed_by).

XR_SPATIAL_COMPONENT_TYPE_ROOM_ANDROIDSYS

Komponent, który podaje wymiary i typ pomieszczenia w przestrzeni; odpowiednia struktura listy to XrSpatialComponentRoomListANDROIDSYS, a odpowiednia struktura danych to XrSpatialRoomDataANDROIDSYS (dodane przez rozszerzenie XR_ANDROIDSYS_spatial_room_tracking).

XR_SPATIAL_COMPONENT_TYPE_MATERIAL_TYPE_ANDROIDSYS

Komponent, który udostępnia typ materiału powierzchni granicznej. Odpowiednia struktura listy to XrSpatialComponentMaterialTypeListANDROIDSYS, a odpowiednia struktura danych to XrSpatialMaterialTypeANDROIDSYS (dodane przez rozszerzenie XR_ANDROIDSYS_spatial_room_tracking).

XR_SPATIAL_COMPONENT_TYPE_CONFIDENCE_ANDROIDSYS

Komponent, który zapewnia pewność elementu możliwego do śledzenia. Odpowiednia struktura listy to XrSpatialComponentConfidenceListANDROIDSYS. Odpowiednia struktura danych to float (dodana przez rozszerzenie XR_ANDROIDSYS_spatial_room_tracking).

XR_SPATIAL_COMPONENT_TYPE_ROOM_EMPTINESS_ANDROIDSYS

Komponent, który określa, czy pomieszczenie jest puste. Odpowiednia struktura listy to XrSpatialComponentRoomEmptinessListANDROIDSYS. Odpowiednia struktura danych to float (dodana przez rozszerzenie XR_ANDROIDSYS_spatial_room_tracking).

XR_SPATIAL_COMPONENT_TYPE_OCCUPANCY_GRID_ANDROIDX1

Komponent, który dostarcza informacje o siatce zajętości dołączonego elementu. Odpowiednia struktura listy to XrSpatialComponentOccupancyGridListANDROIDX1. Odpowiednia struktura danych to XrSpatialOccupancyGridDataANDROIDX1 (dodana przez rozszerzenie XR_ANDROIDX1_spatial_occupancy_grid).

XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID

Komponent opisujący adnotację czworokątną. Odpowiednia struktura listy to XrSpatialComponentAnnotationQuadListANDROID. Odpowiednia struktura danych to XrSpatialAnnotationQuadDataANDROID (dodana przez rozszerzenie XR_ANDROID_spatial_annotation_tracking).

XR_SPATIAL_COMPONENT_TYPE_STREETSCAPE_GEOMETRY_METADATA_ANDROIDX2

Komponent, który dostarcza metadane geometrii widoku ulicy. Odpowiednia struktura listy to XrSpatialComponentStreetscapeGeometryMetadataListANDROIDX2, a odpowiednia struktura danych to XrSpatialStreetscapeGeometryMetadataANDROIDX2 (dodane przez rozszerzenie XR_ANDROIDX2_geospatial_streetscape).

XR_SPATIAL_COMPONENT_TYPE_GEOMETRY_POINT_ANDROID

Komponent, który identyfikuje encję jako punkt geometryczny. Nie ma odpowiedniej listy ani struktury danych dla tego typu komponentu. Obecność tego komponentu wskazuje jedynie, że dany element można dołączyć do kotwicy. (dodane przez rozszerzenie XR_ANDROID_spatial_geometry_point)

XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_SCOPES_ANDROIDX1

Komponent opisujący zakresy trwałości, w których element jest przechowywany. Jeśli środowisko wykonawcze obsługuje XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT, musi też obsługiwać ten komponent. Odpowiednia struktura danych to XrSpatialBufferEXT . Odpowiednia struktura listy to XrSpatialComponentPersistenceScopeDataListANDROIDX1 . (dodane przez rozszerzenie XR_ANDROIDX1_spatial_anchor_cloud_sharing)

Funkcje i konfiguracja przestrzenna

Funkcje przestrzenne określają możliwości środowiska wykonawczego w zakresie wykrywania elementów, które mają gwarantowany zestaw komponentów. Aplikacje włączają komponenty funkcji przestrzennej podczas tworzenia XrSpatialContextEXT, a środowisko wykonawcze musi udostępniać tylko włączone komponenty w wykrytych elementach. Jeśli na przykład środowisko wykonawcze zgłasza, że jednym z komponentów danej funkcji są „etykiety semantyczne”, oznacza to, że aplikacja może włączyć etykiety semantyczne za pomocą konfiguracji tej funkcji, a środowisko wykonawcze musi udostępniać komponent etykiety semantycznej tylko wtedy, gdy jest on skonfigurowany.

typedef enum XrSpatialCapabilityEXT {
    XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT = 1000741000,
    XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT = 1000743000,
    XR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT = 1000743001,
    XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT = 1000743002,
    XR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT = 1000743003,
    XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT = 1000744000,
    XR_SPATIAL_CAPABILITY_ANCHOR_EXT = 1000762000,
    XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT = 1000782000,
    XR_SPATIAL_CAPABILITY_MESH_TRACKING_EXT = 1000783000,
    XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_ANDROID = 1000785000,
    XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID = 1000786000,
    XR_SPATIAL_CAPABILITY_ROOM_TRACKING_ANDROIDSYS = 1000792000,
    XR_SPATIAL_CAPABILITY_ROOM_BOUNDARY_TRACKING_ANDROIDSYS = 1000792001,
    XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID = 1000794000,
    XR_SPATIAL_CAPABILITY_STREETSCAPE_GEOMETRY_ANDROIDX2 = 1000798000,
    XR_SPATIAL_CAPABILITY_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialCapabilityEXT;

Wyliczenie XrSpatialCapabilityEXT określa różne typy funkcji, które środowisko wykonawcze może obsługiwać.

Elementy wyliczenia mają te wartości:

Opis typu wyliczeniowego

XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT

Śledzenie samolotów (dodane przez rozszerzenie XR_EXT_spatial_plane_tracking)

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT

Możliwość wykrywania i śledzenia kodów QR. (dodane przez rozszerzenie XR_EXT_spatial_marker_tracking)

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT

Możliwość wykrywania i śledzenia kodów Micro QR. (dodane przez rozszerzenie XR_EXT_spatial_marker_tracking)

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT

Możliwość wykrywania i śledzenia znaczników Aruco. (dodane przez rozszerzenie XR_EXT_spatial_marker_tracking)

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT

Możliwość wykrywania i śledzenia AprilTagów. (dodane przez rozszerzenie XR_EXT_spatial_marker_tracking)

XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT

Śledzenie obiektów (dodane przez rozszerzenie XR_EXT_spatial_object_tracking)

XR_SPATIAL_CAPABILITY_ANCHOR_EXT

Możliwość tworzenia kotwic przestrzennych (dodana przez rozszerzenie XR_EXT_spatial_anchor)

XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT

Możliwość wykrywania i śledzenia płaskich obrazów referencyjnych. (dodane przez rozszerzenie XR_EXT_spatial_image_tracking)

XR_SPATIAL_CAPABILITY_MESH_TRACKING_EXT

Możliwość śledzenia siatki środowiska. (dodane przez rozszerzenie XR_EXT_spatial_mesh_tracking)

XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_ANDROID

Śledzenie obiektów (dodane przez rozszerzenie XR_ANDROID_spatial_object_tracking)

XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID

Rzutowanie promieni na bufor głębokości (dodane przez rozszerzenie XR_ANDROID_spatial_discovery_raycast)

XR_SPATIAL_CAPABILITY_ROOM_TRACKING_ANDROIDSYS

Możliwość śledzenia pokoju (dodana przez rozszerzenie XR_ANDROIDSYS_spatial_room_tracking)

XR_SPATIAL_CAPABILITY_ROOM_BOUNDARY_TRACKING_ANDROIDSYS

Możliwość śledzenia granic pomieszczenia (dodana przez rozszerzenie XR_ANDROIDSYS_spatial_room_tracking)

XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID

Śledzenie adnotacji (dodane przez rozszerzenie XR_ANDROID_spatial_annotation_tracking)

XR_SPATIAL_CAPABILITY_STREETSCAPE_GEOMETRY_ANDROIDX2

Geometria widoku ulicy (dodana przez rozszerzenie XR_ANDROIDX2_geospatial_streetscape)

Funkcja xrEnumerateSpatialCapabilitiesEXT jest zdefiniowana w ten sposób:

XrResult xrEnumerateSpatialCapabilitiesEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    capabilityCapacityInput,
    uint32_t*                                   capabilityCountOutput,
    XrSpatialCapabilityEXT*                     capabilities);

Opisy parametrów

  • instance to uchwyt do XrInstance .
  • systemId to XrSystemId, którego możliwości przestrzenne zostaną wyliczone.
  • capabilityCapacityInput to pojemność tablicy capabilities lub 0, co oznacza prośbę o pobranie wymaganej pojemności.
  • capabilityCountOutput to liczba funkcji lub wymagana pojemność, jeśli capabilityCapacityInput jest niewystarczająca.
  • capabilities to tablica XrSpatialCapabilityEXT . Może mieć wartość NULL, jeśli capabilityCapacityInput wynosi 0.
  • Szczegółowy opis pobierania wymaganego rozmiaru capabilities znajdziesz w sekcji Parametry rozmiaru bufora.

Aplikacja może wyświetlić listę funkcji przestrzennych obsługiwanych przez dany element XrSystemId za pomocą xrEnumerateSpatialCapabilitiesEXT .

Środowisko wykonawcze nie może wyliczać funkcji przestrzennych, których rozszerzenie nie jest włączone w przypadku instance .

Prawidłowe użycie (pośrednie)

  • Rozszerzenie XR_EXT_spatial_entity musi być włączone przed wywołaniem xrEnumerateSpatialCapabilitiesEXT.
  • instance musi być prawidłowym uchwytem XrInstance
  • capabilityCountOutput musi być wskaźnikiem do wartości uint32_t
  • Jeśli capabilityCapacityInput nie jest równe 0 , capabilities musi być wskaźnikiem do tablicy wartości capabilityCapacityInput XrSpatialCapabilityEXT.

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

Funkcja xrEnumerateSpatialCapabilityComponentTypesEXT jest zdefiniowana w ten sposób:

XrResult xrEnumerateSpatialCapabilityComponentTypesEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrSpatialCapabilityEXT                      capability,
    XrSpatialCapabilityComponentTypesEXT*       capabilityComponents);

Opisy parametrów

  • instance to uchwyt do XrInstance .
  • systemId to XrSystemId, którego komponenty funkcji przestrzennych zostaną wyliczone.
  • capability to XrSpatialCapabilityEXT, dla którego komponenty zostaną wyliczone.
  • capabilityComponents to wskaźnik do XrSpatialCapabilityComponentTypesEXT, czyli struktury wejściowej/wyjściowej, w której jest wypełniana tablica przydzielona przez aplikację.

Ta funkcja wylicza typy komponentów, które dana funkcja udostępnia w swoich encjach w systemie zgodnie z konfiguracją.

Aplikacja może używać typów komponentów wymienionych w XrSpatialCapabilityComponentTypesEXT :: componentTypes, aby poznać pełny zestaw komponentów, które systemId obsługuje w przypadku capability, i może użyć tej listy do określenia prawidłowej konfiguracji dla capability podczas tworzenia dla niego XrSpatialContextEXT.

Środowisko wykonawcze musi zwracać XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT, jeśli capability nie jest wyliczany przez xrEnumerateSpatialCapabilitiesEXT .

Środowisko wykonawcze nie może wyliczać typów komponentów przestrzennych, których rozszerzenie nie jest włączone w przypadku instance .

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_SPATIAL_CAPABILITY_UNSUPPORTED_EXT
  • XR_ERROR_SYSTEM_INVALID
  • XR_ERROR_VALIDATION_FAILURE

Struktura XrSpatialCapabilityComponentTypesEXT jest zdefiniowana w ten sposób:

typedef struct XrSpatialCapabilityComponentTypesEXT {
    XrStructureType               type;
    void*                         next;
    uint32_t                      componentTypeCapacityInput;
    uint32_t                      componentTypeCountOutput;
    XrSpatialComponentTypeEXT*    componentTypes;
} XrSpatialCapabilityComponentTypesEXT;

Opisy członków

  • 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.
  • componentTypeCapacityInput to pojemność tablicy lub 0, co oznacza prośbę o pobranie wymaganej pojemności.
  • componentTypeCountOutput to liczba typów komponentów lub wymagana pojemność, jeśli componentTypeCapacityInput jest niewystarczająca.
  • componentTypes to tablica XrSpatialComponentTypeEXT . Może mieć wartość NULL, jeśli componentTypeCapacityInput wynosi 0.
  • Szczegółowy opis pobierania wymaganego rozmiaru componentTypes znajdziesz w sekcji Parametry rozmiaru bufora.

Prawidłowe użycie (pośrednie)

Funkcje przestrzenne

typedef enum XrSpatialCapabilityFeatureEXT {
    XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_FIXED_SIZE_MARKERS_EXT = 1000743000,
    XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_STATIC_MARKERS_EXT = 1000743001,
    XR_SPATIAL_CAPABILITY_FEATURE_OBJECT_SEMANTIC_LABEL_SUBSET_EXT = 1000744000,
    XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID = 1000761000,
    XR_SPATIAL_CAPABILITY_FEATURE_BOX_BOUNDS_FILTER_ANDROID = 1000761001,
    XR_SPATIAL_CAPABILITY_FEATURE_FRUSTUM_BOUNDS_FILTER_ANDROID = 1000761002,
    XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT = 1000782000,
    XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT = 1000782001,
    XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT = 1000782002,
    XR_SPATIAL_CAPABILITY_FEATURE_TRACK_WATERTIGHT_MESH_EXT = 1000783000,
    XR_SPATIAL_CAPABILITY_FEATURE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialCapabilityFeatureEXT;

Niektóre funkcje mają parametry udostępniane aplikacji, które umożliwiają skonfigurowanie sposobu obliczania danych komponentu przez środowisko wykonawcze. Te wymiary parametryzacji/konfigurowalności są nazywane funkcjami możliwości. Na przykład w przypadku funkcji śledzenia obrazu środowisko wykonawcze może obsługiwać funkcję, która pozwala aplikacji określić, czy śledzone obrazy są nieruchome.

Przekazanie tych informacji do środowiska wykonawczego za pomocą struktury konfiguracji nie może zmienić zestawu typów komponentów obecnych w powiązanych elementach, np. w śledzonym obrazie. Środowisko wykonawcze może jednak zoptymalizować np. możliwości śledzenia obrazu i zapewnić lepsze działanie aplikacji.

Takie funkcje są reprezentowane przez XrSpatialCapabilityFeatureEXT, a aplikacja wylicza je za pomocą xrEnumerateSpatialCapabilityFeaturesEXT .

Każda funkcja ma odpowiednią strukturę konfiguracji, która umożliwia jej włączenie. Takie struktury konfiguracji muszą być połączone z XrSpatialCapabilityConfigurationBaseHeaderEXT :: next odpowiedniej funkcji.

Elementy wyliczenia mają te wartości:

Opis typu wyliczeniowego

XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_FIXED_SIZE_MARKERS_EXT

Funkcja umożliwiająca aplikacjom określanie rozmiaru znaczników. Odpowiednia struktura konfiguracji to XrSpatialMarkerSizeEXT (dodana przez rozszerzenie XR_EXT_spatial_marker_tracking).

XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_STATIC_MARKERS_EXT

Funkcja umożliwiająca aplikacjom określanie, czy znaczniki są statyczne. Odpowiednia struktura konfiguracji to XrSpatialMarkerStaticOptimizationEXT (dodana przez rozszerzenie XR_EXT_spatial_marker_tracking).

XR_SPATIAL_CAPABILITY_FEATURE_OBJECT_SEMANTIC_LABEL_SUBSET_EXT

Funkcja przestrzenna, która umożliwia aplikacjom określenie podzbioru etykiet z XrSpatialObjectSemanticLabelEXT do śledzenia przez środowisko wykonawcze. Odpowiednia struktura konfiguracji to XrSpatialFeatureObjectSemanticLabelSubsetEXT . (dodane przez rozszerzenie XR_EXT_spatial_object_tracking)

XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID

Środowisko wykonawcze obsługuje filtr XrSpatialBoundsSpherefANDROID dla XrSpatialDiscoverySnapshotCreateInfoEXT. Nie wymaga to uwzględniania żadnej struktury konfiguracji podczas tworzenia kontekstu przestrzennego. (dodane przez rozszerzenie XR_ANDROID_spatial_discovery_bounds)

XR_SPATIAL_CAPABILITY_FEATURE_BOX_BOUNDS_FILTER_ANDROID

Środowisko wykonawcze obsługuje filtr XrSpatialBoundsBoxfANDROID dla XrSpatialDiscoverySnapshotCreateInfoEXT. Nie wymaga to uwzględnienia żadnej struktury konfiguracji podczas tworzenia kontekstu przestrzennego. (dodane przez rozszerzenie XR_ANDROID_spatial_discovery_bounds)

XR_SPATIAL_CAPABILITY_FEATURE_FRUSTUM_BOUNDS_FILTER_ANDROID

Środowisko wykonawcze obsługuje filtr XrSpatialBoundsFrustumfANDROID dla XrSpatialDiscoverySnapshotCreateInfoEXT. Nie wymaga to uwzględnienia żadnej struktury konfiguracji podczas tworzenia kontekstu przestrzennego. (dodane przez rozszerzenie XR_ANDROID_spatial_discovery_bounds)

XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT

Środowisko wykonawcze obsługuje automatyczne określanie fizycznego rozmiaru wykrytych i śledzonych obrazów. Odpowiednia struktura konfiguracji to XrSpatialImageSizeEXT (dodana przez rozszerzenie XR_EXT_spatial_image_tracking).

XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT

Środowisko wykonawcze obsługuje XrSpatialImageStaticOptimizationEXT . Odpowiednia struktura konfiguracji to XrSpatialImageStaticOptimizationEXT . (dodane przez rozszerzenie XR_EXT_spatial_image_tracking)

XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT

Środowisko wykonawcze obsługuje XrSpatialImageSizeEXT . Odpowiednia struktura konfiguracji to XrSpatialImageSizeEXT (dodana przez rozszerzenie XR_EXT_spatial_image_tracking).

XR_SPATIAL_CAPABILITY_FEATURE_TRACK_WATERTIGHT_MESH_EXT

Funkcja umożliwiająca śledzenie wodoszczelnej siatki środowiska. Odpowiednia struktura konfiguracji to XrSpatialFeatureTrackWatertightMeshEXT . (dodane przez rozszerzenie XR_EXT_spatial_mesh_tracking)

Funkcja xrEnumerateSpatialCapabilityFeaturesEXT jest zdefiniowana w ten sposób:

XrResult xrEnumerateSpatialCapabilityFeaturesEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrSpatialCapabilityEXT                      capability,
    uint32_t                                    capabilityFeatureCapacityInput,
    uint32_t*                                   capabilityFeatureCountOutput,
    XrSpatialCapabilityFeatureEXT*              capabilityFeatures);

Opisy parametrów

  • instance to uchwyt do XrInstance .
  • systemId to XrSystemId, którego funkcje przestrzenne zostaną wyliczone.
  • capability to XrSpatialCapabilityEXT, dla którego funkcje zostaną wyliczone.
  • capabilityFeatureCapacityInput to pojemność tablicy lub 0, co oznacza prośbę o pobranie wymaganej pojemności.
  • capabilityFeatureCountOutput to liczba funkcji lub wymagana pojemność, jeśli capabilityFeatureCapacityInput jest niewystarczająca.
  • capabilityFeatures to tablica XrSpatialCapabilityFeatureEXT . Może mieć wartość NULL, jeśli capabilityFeatureCapacityInput wynosi 0.
  • Szczegółowy opis pobierania wymaganego rozmiaru capabilityFeatures znajdziesz w sekcji Parametry rozmiaru bufora.

Aplikacja wykrywa funkcje obsługiwane przez dany system dla XrSpatialCapabilityEXT za pomocą xrEnumerateSpatialCapabilityFeaturesEXT .

W przypadku funkcji, które mają udostępnione funkcje, aplikacja wybiera funkcję lub funkcje do włączenia i udostępnia odpowiednią strukturę konfiguracji w następnym łańcuchu struktur konfiguracji funkcji w XrSpatialContextCreateInfoEXT :: capabilityConfigs .

Jeśli capability nie jest funkcją wymienioną przez xrEnumerateSpatialCapabilitiesEXT , środowisko wykonawcze musi zwrócić XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT .

Środowisko wykonawcze nie może wyliczać funkcji przestrzennych, których rozszerzenie nie jest włączone w przypadku instance .

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_SPATIAL_CAPABILITY_UNSUPPORTED_EXT
  • XR_ERROR_SYSTEM_INVALID
  • XR_ERROR_VALIDATION_FAILURE

Kontekst przestrzenny

Tworzenie kontekstu przestrzennego

XR_DEFINE_HANDLE(XrSpatialContextEXT)

Uchwyt XrSpatialContextEXT reprezentuje zasoby do wykrywania i aktualizowania określonej liczby elementów przestrzennych w środowisku użytkownika. Aplikacja może używać tego uchwytu do wykrywania i aktualizowania elementów przestrzennych za pomocą innych funkcji tego rozszerzenia.

Funkcja xrCreateSpatialContextAsyncEXT jest zdefiniowana w ten sposób:

XrResult xrCreateSpatialContextAsyncEXT(
    XrSession                                   session,
    const XrSpatialContextCreateInfoEXT*        createInfo,
    XrFutureEXT*                                future);

Opisy parametrów

  • session to XrSession, w której kontekst przestrzenny będzie aktywny.
  • createInfo to XrSpatialContextCreateInfoEXT używany do określania parametrów kontekstu przestrzennego.
  • future to wskaźnik do XrFutureEXT .

Aplikacja może utworzyć uchwyt XrSpatialContextEXT przez:

Środowisko wykonawcze musi zwracać XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT, jeśli XrSpatialContextCreateInfoEXT ::capabilityConfigCount wynosi 0. Uchwyt kontekstu przestrzennego musi mieć co najmniej 1 funkcję.

Środowisko wykonawcze musi zwracać XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT, jeśli jakakolwiek funkcja w tablicy XrSpatialContextCreateInfoEXT :: capabilityConfigs nie jest wyliczana przez xrEnumerateSpatialCapabilitiesEXT .

Środowisko wykonawcze musi zwracać XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT, jeśli dowolny element XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponentCount w XrSpatialContextCreateInfoEXT :: capabilityConfigs ma wartość 0. Konfiguracja funkcji jest niekompletna bez listy typów komponentów, które mają być włączone dla tej funkcji.

Środowisko wykonawcze musi zwracać XR_ERROR_SPATIAL_COMPONENT_UNSUPPORTED_FOR_CAPABILITY_EXT, jeśli jakikolwiek typ komponentu wymieniony w XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents nie jest wyliczany dla XrSpatialCapabilityConfigurationBaseHeaderEXT :: capability w xrEnumerateSpatialCapabilityComponentTypesEXT .

Jeśli któraś ze struktur w następnym łańcuchu XrSpatialContextCreateInfoEXT :: capabilityConfigs odpowiada XrSpatialCapabilityFeatureEXT, która nie jest wymieniona dla tej funkcji w xrEnumerateSpatialCapabilityFeaturesEXT, środowisko wykonawcze musi zignorować tę strukturę XrSpatialCapabilityFeatureEXT.

Środowisko wykonawcze musi zwracać XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT, jeśli XrSpatialContextCreateInfoEXT :: capabilityConfigs zawiera wiele struktur z tym samym XrSpatialCapabilityConfigurationBaseHeaderEXT :: capability .

Aby zapewnić optymalne wykorzystanie zasobów systemowych, środowisko wykonawcze może używać konfiguracji podanych w tablicy XrSpatialContextCreateInfoEXT, aby przygotować się na nadchodzące żądania przestrzenne. Na przykład środowisko wykonawcze, które obsługuje funkcję śledzenia płaszczyzny, może rozpocząć potok śledzenia płaszczyzny tylko wtedy, gdy aplikacja utworzy uchwyt kontekstu przestrzennego zawierający funkcję śledzenia płaszczyzny. Jeśli skonfigurowane funkcje mają długi czas rozgrzewania, wywołania funkcji xrCreateSpatialDiscoverySnapshotAsyncEXT mogą zwracać pusty zrzut. Aplikacja może poczekać na XrEventDataSpatialDiscoveryRecommendedEXT, zanim użyje xrCreateSpatialDiscoverySnapshotAsyncEXT, aby mieć pewność, że usługi śledzenia są gotowe do działania.

Jeśli środowisko wykonawcze wymusza system uprawnień do kontrolowania dostępu aplikacji do funkcji przestrzennych konfigurowanych dla XrSpatialContextEXT, środowisko wykonawcze musi zwrócić XR_ERROR_PERMISSION_INSUFFICIENT, jeśli te uprawnienia nie zostały przyznane tej aplikacji.

Ta funkcja rozpoczyna operację asynchroniczną i tworzy odpowiedni obiekt XrFutureEXT , którego można używać z funkcją xrPollFutureEXT i powiązanymi funkcjami. Wartość zwracana przez tę funkcję wskazuje tylko, czy parametry były akceptowalne do zaplanowania operacji asynchronicznej. Odpowiednia funkcja uzupełniania to xrCreateSpatialContextCompleteEXT, której można używać, gdy przyszłość z tej funkcji jest w stanie READY, a dane wyjściowe są wypełniane przez tę funkcję w strukturze uzupełniania XrCreateSpatialContextCompletionEXT .

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_PERMISSION_INSUFFICIENT
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT
  • XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT
  • XR_ERROR_SPATIAL_COMPONENT_UNSUPPORTED_FOR_CAPABILITY_EXT
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_TIME_INVALID (jeśli włączona jest opcja XR_ANDROID_spatial_annotation_tracking)

Struktura XrSpatialContextCreateInfoEXT jest zdefiniowana w ten sposób:

typedef struct XrSpatialContextCreateInfoEXT {
    XrStructureType                                                type;
    const void*                                                    next;
    uint32_t                                                       capabilityConfigCount;
    const XrSpatialCapabilityConfigurationBaseHeaderEXT* const*    capabilityConfigs;
} XrSpatialContextCreateInfoEXT;

Opisy członków

  • 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.
  • capabilityConfigCount to uint32_t opisujący liczbę elementów w tablicy capabilityConfigs.
  • capabilityConfigs to wskaźnik do tablicy wskaźników XrSpatialCapabilityConfigurationBaseHeaderEXT.

Struktura XrSpatialContextCreateInfoEXT opisuje informacje potrzebne do utworzenia uchwytu XrSpatialContextEXT.

Prawidłowe użycie (pośrednie)

Struktura XrSpatialCapabilityConfigurationBaseHeaderEXT jest zdefiniowana w ten sposób:

typedef struct XrSpatialCapabilityConfigurationBaseHeaderEXT {
    XrStructureType                     type;
    const void*                         next;
    XrSpatialCapabilityEXT              capability;
    uint32_t                            enabledComponentCount;
    const XrSpatialComponentTypeEXT*    enabledComponents;
} XrSpatialCapabilityConfigurationBaseHeaderEXT;

Ta struktura nie jest używana bezpośrednio w interfejsie API, ale jej struktury podrzędne mogą być używane z XrSpatialContextCreateInfoEXT do konfigurowania funkcji przestrzennych.

Opisy członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur.
  • capability to XrSpatialCapabilityEXT .
  • enabledComponentCount to uint32_t opisujący liczbę elementów w tablicy enabledComponents.
  • enabledComponents to wskaźnik do tablicy XrSpatialComponentTypeEXT .

Środowisko wykonawcze musi zwracać XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT, jeśli capability nie jest wyliczany przez xrEnumerateSpatialCapabilitiesEXT . Środowisko wykonawcze musi zwracać XR_ERROR_SPATIAL_COMPONENT_UNSUPPORTED_FOR_CAPABILITY_EXT, jeśli jakikolwiek typ komponentu wymieniony w enabledComponents nie jest wyliczany dla capability w xrEnumerateSpatialCapabilityComponentTypesEXT .

Prawidłowe użycie (pośrednie)

Funkcja xrCreateSpatialContextCompleteEXT jest zdefiniowana w ten sposób:

XrResult xrCreateSpatialContextCompleteEXT(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrCreateSpatialContextCompletionEXT*        completion);

Opisy parametrów

xrCreateSpatialContextCompleteEXT kończy operację asynchroniczną rozpoczętą przez xrCreateSpatialContextAsyncEXT . Środowisko wykonawcze musi zwracać XR_ERROR_FUTURE_PENDING_EXT, jeśli future nie jest w stanie gotowości. Środowisko wykonawcze musi zwrócić XR_ERROR_FUTURE_INVALID_EXT, jeśli future zostało już ukończone lub anulowane.

Prawidłowe użycie (pośrednie)

Kody zwrotu

Sukces

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Błąd

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_FUTURE_INVALID_EXT
  • XR_ERROR_FUTURE_PENDING_EXT
  • 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_VALIDATION_FAILURE

Struktura XrCreateSpatialContextCompletionEXT jest zdefiniowana w ten sposób:

typedef struct XrCreateSpatialContextCompletionEXT {
    XrStructureType        type;
    void*                  next;
    XrResult               futureResult;
    XrSpatialContextEXT    spatialContext;
} XrCreateSpatialContextCompletionEXT;

Opisy członków

Kody zwrotu w przyszłości

Wartości futureResult:

Sukces

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Błąd

  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT

Jeśli futureResult jest kodem powodzenia, spatialContext musi być prawidłowy. Jeśli spatialContext jest prawidłowy, pozostaje taki tylko w cyklu życia xrCreateSpatialContextAsyncEXT :: session lub do momentu, gdy aplikacja zniszczy spatialContext za pomocą xrDestroySpatialContextEXT (w zależności od tego, co nastąpi wcześniej).

Prawidłowe użycie (pośrednie)

zniszczyć kontekst przestrzenny,

Funkcja xrDestroySpatialContextEXT jest zdefiniowana w ten sposób:

XrResult xrDestroySpatialContextEXT(
    XrSpatialContextEXT                         spatialContext);

Opisy parametrów

Aplikacja może wywołać funkcję xrDestroySpatialContextEXT, aby zwolnić uchwyt spatialContext i powiązane zasoby po zakończeniu wykrywania i aktualizowania elementów przestrzennych. Jeśli nie ma innego prawidłowego obiektu XrSpatialContextEXT, który został utworzony z tymi samymi funkcjami przestrzennymi co spatialContext, to wywołanie służy jako sugestia dla środowiska wykonawczego, aby wyłączyć usługi śledzenia wymagane przez te funkcje w celu oszczędzania zasobów systemowych.

Prawidłowe użycie (pośrednie)

Bezpieczeństwo wątków

  • Dostęp do spatialContext 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

Reprezentacje elementów przestrzennych

Identyfikator elementu przestrzennego

XR_DEFINE_ATOM(XrSpatialEntityIdEXT)

XrSpatialEntityIdEXT reprezentuje dowolny rodzaj elementu wykrytego przez środowisko wykonawcze w środowisku przestrzennym użytkownika. Identyfikator XrSpatialEntityIdEXT jest prawidłowy dla elementu XrSpatialContextEXT, w którym został wykryty, a środowisko wykonawcze nie może używać tego samego identyfikatora XrSpatialEntityIdEXT w przypadku różnych elementów w tym samym elemencie XrSpatialContextEXT . Środowisko wykonawcze nie może też używać tego samego identyfikatora XrSpatialEntityIdEXT w wielu elementach XrSpatialContextEXT w ramach tej samej sesji XrSession, niezależnie od tego, czy reprezentuje on ten sam element czy różne elementy.

#define XR_NULL_SPATIAL_ENTITY_ID_EXT 0

XR_NULL_SPATIAL_ENTITY_ID_EXT to zarezerwowana wartość reprezentująca nieprawidłowy identyfikator XrSpatialEntityIdEXT . Może być przekazywany do funkcji interfejsu API i zwracany przez nie tylko wtedy, gdy jest to wyraźnie dozwolone.

Uchwyt elementu przestrzennego

XR_DEFINE_HANDLE(XrSpatialEntityEXT)

Uchwyt XrSpatialEntityEXT reprezentuje element przestrzenny. Aplikacja może utworzyć taki uchwyt, aby poinformować środowisko wykonawcze o swoim zainteresowaniu konkretnym elementem.

Utwórz uchwyt elementu przestrzennego na podstawie identyfikatora

Funkcja xrCreateSpatialEntityFromIdEXT jest zdefiniowana w ten sposób:

XrResult xrCreateSpatialEntityFromIdEXT(
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialEntityFromIdCreateInfoEXT*   createInfo,
    XrSpatialEntityEXT*                         spatialEntity);

Opisy parametrów

Aplikacja może używać funkcji xrCreateSpatialEntityFromIdEXT do utworzenia uchwytu XrSpatialEntityEXT, który jest odwołaniem do encji istniejącej w środowisku użytkownika.

Środowisko wykonawcze musi zwracać XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT, jeśli XrSpatialEntityFromIdCreateInfoEXT :: entityId nie jest prawidłowym identyfikatorem dla spatialContext .

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_ENTITY_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

Struktura XrSpatialEntityFromIdCreateInfoEXT jest zdefiniowana w ten sposób:

typedef struct XrSpatialEntityFromIdCreateInfoEXT {
    XrStructureType         type;
    const void*             next;
    XrSpatialEntityIdEXT    entityId;
} XrSpatialEntityFromIdCreateInfoEXT;

Opisy członków

  • 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.
  • entityId to XrSpatialEntityIdEXT elementu, dla którego aplikacja chce utworzyć uchwyt.

Prawidłowe użycie (pośrednie)

Zniszcz uchwyt encji przestrzennej

Funkcja xrDestroySpatialEntityEXT jest zdefiniowana w ten sposób:

XrResult xrDestroySpatialEntityEXT(
    XrSpatialEntityEXT                          spatialEntity);

Opisy parametrów

Aplikacja może używać funkcji xrDestroySpatialEntityEXT, aby zwolnić uchwyt spatialEntity, gdy nie jest już zainteresowana elementem, do którego odwołuje się ten uchwyt.

Prawidłowe użycie (pośrednie)

Bezpieczeństwo wątków

  • Dostęp do spatialEntity 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

Zdjęcie przestrzenne

XR_DEFINE_HANDLE(XrSpatialSnapshotEXT)

Aplikacja może tworzyć migawki przestrzenne w celu wykrywania elementów przestrzennych lub aktualizowania informacji o znanych elementach przestrzennych. Uchwyt XrSpatialSnapshotEXT reprezentuje niezmienne dane wykrytych lub zaktualizowanych elementów przestrzennych oraz podzbiór ich komponentów wybranych przez aplikację. Zrzut przestrzenny przedstawia spójny widok encji i ich danych składowych. Po utworzeniu zrzutu jego dane muszą pozostać niezmienione przez cały okres jego ważności.

Aplikacja może utworzyć dowolną liczbę zrzutów, ale musi pamiętać o pamięci przydzielonej dla każdego nowego zrzutu i musi zniszczyć zrzuty, gdy nie są już potrzebne.

Utwórz zrzut wykrywania

Funkcja xrCreateSpatialDiscoverySnapshotAsyncEXT jest zdefiniowana w ten sposób:

XrResult xrCreateSpatialDiscoverySnapshotAsyncEXT(
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialDiscoverySnapshotCreateInfoEXT* createInfo,
    XrFutureEXT*                                future);

Opisy parametrów

Aplikacja może wykrywać elementy przestrzenne, tworząc zdjęcie wykrywania za pomocą funkcji xrCreateSpatialDiscoverySnapshotAsyncEXT .

Ta funkcja rozpoczyna operację asynchroniczną i tworzy odpowiedni obiekt XrFutureEXT , którego można używać z funkcją xrPollFutureEXT i powiązanymi funkcjami. Wartość zwracana przez tę funkcję wskazuje tylko, czy parametry były akceptowalne do zaplanowania operacji asynchronicznej. Odpowiednia funkcja zakończenia to xrCreateSpatialDiscoverySnapshotCompleteEXT, której można użyć, gdy przyszłość z tej funkcji jest w stanie READY, a dane wyjściowe są wypełniane przez tę funkcję w strukturze zakończenia XrCreateSpatialDiscoverySnapshotCompletionEXT .

Aplikacja może przesłać wiele żądań utworzenia migawki wykrywania bez konieczności czekania na zakończenie poprzedniego. Środowisko wykonawcze może przetwarzać i tworzyć zrzuty w dowolnej kolejności. Środowisko wykonawcze może opóźnić zakończenie tworzenia migawki wykrywania, aby ograniczyć działanie aplikacji, jeśli musi zmniejszyć wykorzystanie zasobów systemowych ze względu na zasady dotyczące zasilania, temperatury lub inne zasady urządzenia.

Aplikacja może używać XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes do filtrowania listy elementów i komponentów, których dane środowisko wykonawcze musi uwzględnić w zdjęciu. Jeśli aplikacja udostępnia prawidłową listę typów komponentów przestrzennych w XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes, środowisko wykonawcze musi uwzględniać w migawce tylko te elementy przestrzenne, które mają co najmniej 1 z komponentów podanych w XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes . Środowisko wykonawcze musi też zawierać dane tylko o tych komponentach, które znajdują się w migawce.

Środowisko wykonawcze musi zwracać XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT, jeśli którykolwiek z parametrów XrSpatialComponentTypeEXT w XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes nie jest włączony dla funkcji przestrzennych przekazanych do XrSpatialContextCreateInfoEXT :: capabilityConfigs podczas tworzenia spatialContext .

Jeśli aplikacja nie udostępnia listy typów komponentów przestrzennych w XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes, środowisko wykonawcze musi uwzględnić w migawce wszystkie elementy przestrzenne, które mają zestaw komponentów wymienionych w XrSpatialCapabilityConfigurationBaseHeaderEXT ::enabledComponents dla funkcji skonfigurowanych dla spatialContext . Środowisko wykonawcze musi zawierać dane dotyczące wszystkich włączonych komponentów funkcji skonfigurowanych dla spatialContext .

Jeśli zdarzenie XrEventDataReferenceSpaceChangePending zostanie umieszczone w kolejce przed zakończeniem future, a XrEventDataReferenceSpaceChangePending :: poseValid ma wartość false, środowisko wykonawcze może utworzyć XrSpatialSnapshotEXT, który nie zawiera żadnych elementów, lub ustawić XrSpatialEntityTrackingStateEXT elementów, których nie można już zlokalizować w XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace w XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time na XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT lub XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT . Środowisko wykonawcze nie może ustawić XrCreateSpatialContextCompletionEXT :: futureResult na kod błędu z powodu XrEventDataReferenceSpaceChangePending .

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_COMPONENT_NOT_ENABLED_EXT
  • XR_ERROR_VALIDATION_FAILURE

Struktura XrSpatialDiscoverySnapshotCreateInfoEXT jest zdefiniowana w ten sposób:

typedef struct XrSpatialDiscoverySnapshotCreateInfoEXT {
    XrStructureType                     type;
    const void*                         next;
    uint32_t                            componentTypeCount;
    const XrSpatialComponentTypeEXT*    componentTypes;
} XrSpatialDiscoverySnapshotCreateInfoEXT;

Opisy członków

  • 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.
  • componentTypeCount to uint32_t opisujący liczbę elementów w tablicy componentTypes.
  • componentTypes to tablica XrSpatialComponentTypeEXT .

Struktura XrSpatialDiscoverySnapshotCreateInfoEXT opisuje informacje potrzebne do utworzenia uchwytu XrSpatialSnapshotEXT podczas wykrywania elementów przestrzennych.

Prawidłowe użycie (pośrednie)

Funkcja xrCreateSpatialDiscoverySnapshotCompleteEXT jest zdefiniowana w ten sposób:

XrResult xrCreateSpatialDiscoverySnapshotCompleteEXT(
    XrSpatialContextEXT                         spatialContext,
    const XrCreateSpatialDiscoverySnapshotCompletionInfoEXT* createSnapshotCompletionInfo,
    XrCreateSpatialDiscoverySnapshotCompletionEXT* completion);

Opisy parametrów

xrCreateSpatialDiscoverySnapshotCompleteEXT kończy operację asynchroniczną rozpoczętą przez xrCreateSpatialDiscoverySnapshotAsyncEXT . Środowisko wykonawcze musi zwracać XR_ERROR_FUTURE_PENDING_EXT, jeśli XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: future nie jest w stanie gotowości. Środowisko wykonawcze musi zwrócić XR_ERROR_FUTURE_INVALID_EXT, jeśli XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: future zostało już ukończone lub anulowane.

Prawidłowe użycie (pośrednie)

Kody zwrotu

Sukces

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Błąd

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_FUTURE_INVALID_EXT
  • XR_ERROR_FUTURE_PENDING_EXT
  • 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_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

Struktura XrCreateSpatialDiscoverySnapshotCompletionInfoEXT jest zdefiniowana w ten sposób:

typedef struct XrCreateSpatialDiscoverySnapshotCompletionInfoEXT {
    XrStructureType    type;
    const void*        next;
    XrSpace            baseSpace;
    XrTime             time;
    XrFutureEXT        future;
} XrCreateSpatialDiscoverySnapshotCompletionInfoEXT;

Opisy członków

Lokalizacje w różnych danych komponentów uwzględnionych w utworzonym zrzucie będą reprezentowane w baseSpace , który znajduje się w time .

Prawidłowe użycie (pośrednie)

Struktura XrCreateSpatialDiscoverySnapshotCompletionEXT jest zdefiniowana w ten sposób:

typedef struct XrCreateSpatialDiscoverySnapshotCompletionEXT {
    XrStructureType         type;
    void*                   next;
    XrResult                futureResult;
    XrSpatialSnapshotEXT    snapshot;
} XrCreateSpatialDiscoverySnapshotCompletionEXT;

Opisy członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur.
  • futureResult to XrResult operacji tworzenia zrzutu wykrywania przestrzennego.
  • snapshot to XrSpatialSnapshotEXT, który można wykorzystać do wysyłania zapytań o dane komponentów wykrytych encji przestrzennych.

Kody zwrotu w przyszłości

Wartości futureResult:

Sukces

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Błąd

  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED

Prawidłowe użycie (pośrednie)

Zdarzenie rekomendacji Discovery

Struktura XrEventDataSpatialDiscoveryRecommendedEXT jest zdefiniowana w ten sposób:

typedef struct XrEventDataSpatialDiscoveryRecommendedEXT {
    XrStructureType        type;
    const void*            next;
    XrSpatialContextEXT    spatialContext;
} XrEventDataSpatialDiscoveryRecommendedEXT;

Opisy członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur.
  • spatialContext to XrSpatialContextEXT, dla którego środowisko wykonawcze zaleca wykrywanie.

Aplikacja może pobrać to zdarzenie za pomocą xrPollEvent . Aplikacja może uniknąć nadmiernych wywołań funkcji xrCreateSpatialDiscoverySnapshotAsyncEXT w celu wykrywania elementów przestrzennych, czekając na to zdarzenie. Jeśli aplikacja utworzy wiele zrzutów wykrywania z tym samym XrSpatialDiscoverySnapshotCreateInfoEXT między 2 zdarzeniami XrEventDataSpatialDiscoveryRecommendedEXT, wynikowe zrzuty mogą zawierać te same elementy, co oznacza, że tworzenie zrzutów i zapytania o dane będą niepotrzebne.

Oczekiwanie na to zdarzenie w celu utworzenia nowego zdjęcia wykrywania gwarantuje, że aplikacja nie przeciąży systemu żądaniami wykrywania, w przypadku których środowisko wykonawcze może nie zwrócić żadnych nowych danych. Pomaga to też uniknąć ryzyka nadmiernego wykorzystania zasobów systemowych i ograniczenia przepustowości ze względu na zasady dotyczące zasilania lub temperatury urządzenia. Pomaga to również zachować równowagę między środowiskami wykonawczymi, które wykrywają elementy przestrzenne na bieżąco za pomocą śledzenia na żywo, a środowiskami wykonawczymi, które dostarczają elementy przestrzenne na podstawie wcześniej zarejestrowanego stanu (gdzie środowisko wykonawcze może umieścić zdarzenie rekomendacji wykrywania w kolejce tylko raz dla każdego elementu XrSpatialContextEXT).

Środowisko wykonawcze nie może umieszczać tego zdarzenia w kolejce, aby powiadomić aplikację o zmianach lub dostosowaniach wprowadzonych w danych komponentu istniejących elementów przestrzennych. Aplikacja może używać funkcji xrCreateSpatialUpdateSnapshotEXT do śledzenia aktualizacji danych komponentów w przypadku interesujących ją elementów przestrzennych.

Środowisko wykonawcze może dodać do kolejki zdarzenie rekomendacji wykrywania bez czekania, aż aplikacja najpierw wywoła funkcję xrCreateSpatialDiscoverySnapshotAsyncEXT . Na przykład środowisko wykonawcze może podjąć decyzję o dodaniu zdarzenia rekomendacji wykrywania do kolejki na podstawie konfiguracji XrSpatialContextEXT, własnego rozumienia środowiska wokół użytkownika (wykrywanie nowych elementów lub utrata istniejących) lub w celu zasugerowania aplikacji odpowiedniej częstotliwości żądań wykrywania, aby nie przeciążać zasobów systemowych. Środowisko wykonawcze może nigdy nie dodać tego zdarzenia do kolejki dla XrSpatialContextEXT, jeśli w środowisku użytkownika nie zostaną znalezione żadne elementy przez cały okres istnienia tego XrSpatialContextEXT .

Środowisko wykonawcze nie może umieszczać tego zdarzenia w kolejce dla danego elementu spatialContext, dopóki aplikacja nie zakończy tworzenia za pomocą funkcji xrCreateSpatialContextCompleteEXT .

Po wywołaniu przez aplikację funkcji xrDestroySpatialContextEXT środowisko wykonawcze nie może dodawać do kolejki żadnych zdarzeń rekomendacji dotyczących wykrywania dla tego kontekstu przestrzennego ani zwracać takich zdarzeń dla tego kontekstu z funkcji xrPollEvent .

Prawidłowe użycie (pośrednie)

Dane komponentu zapytania

Funkcja xrQuerySpatialComponentDataEXT jest zdefiniowana w ten sposób:

XrResult xrQuerySpatialComponentDataEXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialComponentDataQueryConditionEXT* queryCondition,
    XrSpatialComponentDataQueryResultEXT*       queryResult);

Opisy parametrów

Aplikacja może używać funkcji xrQuerySpatialComponentDataEXT do wysyłania zapytań o dane komponentów encji w zrzucie, dołączając strukturę listy do XrSpatialComponentDataQueryResultEXT :: next odpowiadającej każdemu XrSpatialComponentTypeEXT w XrSpatialComponentDataQueryConditionEXT :: componentTypes .

Jeśli aplikacja dołącza strukturę listy do XrSpatialComponentDataQueryResultEXT :: next, która nie odpowiada żadnemu z komponentów wymienionych w XrSpatialComponentDataQueryConditionEXT :: componentTypes, środowisko wykonawcze musi zwrócić XR_ERROR_VALIDATION_FAILURE .

Aplikacja może dołączyć struktury listy odpowiadające tylko podzbiorowi komponentów wymienionych w XrSpatialComponentDataQueryConditionEXT :: componentTypes . Aplikacja może całkowicie pominąć struktury listy, jeśli chce tylko poznać identyfikatory i stan śledzenia elementów przestrzennych, które spełniają warunek queryCondition . Środowisko wykonawcze nie może traktować braku struktur listy z łańcucha XrSpatialComponentDataQueryResultEXT :: next jako błędu.

Jeśli zdarzenie XrEventDataReferenceSpaceChangePending jest w kolejce i XrEventDataReferenceSpaceChangePending :: changeTime upłynęło, gdy aplikacja wysyła zapytanie o dane komponentu z XrSpatialSnapshotEXT, aplikacja może użyć danych zdarzenia, aby odpowiednio dostosować pozy.

Środowisko wykonawcze musi wypełniać XrSpatialComponentDataQueryResultEXT :: entityIds tylko encjami, które mają wszystkie komponenty określone w XrSpatialComponentDataQueryConditionEXT :: componentTypes . Jeśli XrSpatialComponentDataQueryConditionEXT :: componentTypeCount ma wartość 0, środowisko wykonawcze musi wypełnić queryResult wszystkimi encjami (i ich stanami śledzenia), które znajdują się w zrzucie. Jeśli do XrSpatialComponentDataQueryConditionEXT :: next zostaną dodane dodatkowe warunki zapytania, środowisko wykonawcze musi traktować je jako „ORAZ” z dostępnością typów komponentów, tzn. środowisko wykonawcze musi wypełnić XrSpatialComponentDataQueryResultEXT ::entityIds tylko encjami, które spełniają wszystkie podane warunki. Środowisko wykonawcze musi wypełniać dane komponentu w strukturach listy w tej samej kolejności co encje w XrSpatialComponentDataQueryResultEXT :: entityIds, tzn. dane komponentu o danym indeksie w tablicy struktury listy muszą odpowiadać encji o tym samym indeksie.

Jeśli stan śledzenia encji nie jest XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT , środowisko wykonawcze nie może zmieniać danych w indeksie odpowiadającym tej encji w tablicy zawartej w strukturach listy dołączonych do XrSpatialComponentDataQueryResultEXT .

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_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_VALIDATION_FAILURE

Na przykład aplikacja tworzy obiekt XrSpatialSnapshotEXT, który zawiera 5 elementów:

  • Encje 1 i 2 mają komponenty XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT i XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT
  • Jednostki 3 i 4 mają komponenty XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT i XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT
  • Encja 5 ma komponenty XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT i XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT .

XrSpatialEntityIdEXT

XrSpatialEntityIdEXT

1

1

2

2

3

3

4

4

5

5

Bounded2D

Bounded2D

Tak

Tak

Tak

Tak

Nie

Nie

Nie

Nie

Tak

Tak

Rodzic

Rodzic

Tak

Tak

Tak

Tak

Nie

Nie

Nie

Nie

Nie

Nie

Mesh3D

Mesh3D

Nie

Nie

Nie

Nie

Tak

Tak

Tak

Tak

Tak

Tak

Bounded3D

Bounded3D

Nie

Nie

Nie

Nie

Tak

Tak

Tak

Tak

Nie

Nie Tekst nie jest plikiem SVG – nie można wyświetlić

Rysunek 20. Przykładowy zrzut ekranu

Wywołanie funkcji xrQuerySpatialComponentDataEXT na powyższym zrzucie z XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT wymienionym w warunku zapytania spowoduje zwrócenie do aplikacji encji 1, 2 i 5. Aplikacja może dołączyć tablicę XrSpatialBounded2DDataEXT jako część struktury XrSpatialComponentBounded2DListEXT do następnego łańcucha XrSpatialComponentDataQueryResultEXT, aby uzyskać dane bounded2D.

XrSpatialEntityIdEXT

XrSpatialEntityIdEXT

1

1

2

2

5

5

Bounded2D

Bounded2D

Dane dla entityId #1

Dane dla podmi...

Dane dla entityId #2

Dane dla podmi...

Dane dla entityId #5

Dane dla podmi...

entityIds

entityIds

dalej

dalej

XrSpatialComponent
DataQueryResultEXT

XrSpatialComponent
Dat...

bounds

bounds

XrSpatialComponent
Bounded2DListEXT

XrSpatialComponent
Bou... Tekst nie jest w formacie SVG – nie można go wyświetlić

Rysunek 21. Przykładowy wynik zapytania

xrQuerySpatialComponentDataEXT na powyższym zrzucie ekranu z komponentami XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT i XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT wymienionymi w warunku zapytania spowoduje zwrócenie do aplikacji encji 3 i 4, a aplikacja będzie mogła dołączyć tablice XrBoxf i XrSpatialMeshDataEXT odpowiednio jako część struktur XrSpatialComponentBounded3DListEXT i XrSpatialComponentMesh3DListEXT do następnego łańcucha XrSpatialComponentDataQueryResultEXT, aby uzyskać dane komponentu.

XrSpatialEntityIdEXT

XrSpatialEntityIdEXT

3

3

4

4

Bounded3D

Bounded3D

Dane dla entityId #3

Dane dla podmi...

Dane dla identyfikatora entityId #4

Dane dla podmi...

Mesh3D

Mesh3D

Dane dla entityId #3

Dane dla podmi...

Dane dla identyfikatora entityId #4

Dane dla podmi...

entityIds

entityIds

dalej

dalej

XrSpatialComponent
DataQueryResultEXT

XrSpatialComponent
Da...

bounds

bounds

dalej

dalej

XrSpatialComponent
Bounded3DListEXT

XrSpatialComponent
Bo...

XrSpatialComponent
Mesh3DListEXT

XrSpatialComponent
Me...

siatki,

siatki Tekst nie jest w formacie SVG – nie można wyświetlić

Rysunek 22. Przykładowy wynik zapytania

Struktura XrSpatialComponentDataQueryConditionEXT jest zdefiniowana w ten sposób:

typedef struct XrSpatialComponentDataQueryConditionEXT {
    XrStructureType                     type;
    const void*                         next;
    uint32_t                            componentTypeCount;
    const XrSpatialComponentTypeEXT*    componentTypes;
} XrSpatialComponentDataQueryConditionEXT;

Opisy członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur.
  • componentTypeCount to uint32_t opisujący liczbę elementów w tablicy componentTypes.
  • componentTypes to tablica XrSpatialComponentTypeEXT, z której można pobrać dane z migawki.

Prawidłowe użycie (pośrednie)

Struktura XrSpatialComponentDataQueryResultEXT jest zdefiniowana w ten sposób:

typedef struct XrSpatialComponentDataQueryResultEXT {
    XrStructureType                     type;
    void*                               next;
    uint32_t                            entityIdCapacityInput;
    uint32_t                            entityIdCountOutput;
    XrSpatialEntityIdEXT*               entityIds;
    uint32_t                            entityStateCapacityInput;
    uint32_t                            entityStateCountOutput;
    XrSpatialEntityTrackingStateEXT*    entityStates;
} XrSpatialComponentDataQueryResultEXT;

Opisy członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur.
  • entityIdCapacityInput to pojemność tablicy entityIds lub 0, co oznacza prośbę o pobranie wymaganej pojemności.
  • entityIdCountOutput to liczba XrSpatialEntityIdEXT w entityIds lub wymagana pojemność, jeśli entityIdCapacityInput jest niewystarczająca.
  • entityIds to tablica obiektów XrSpatialEntityIdEXT . Może mieć wartość NULL, jeśli entityIdCapacityInput wynosi 0.
  • entityStateCapacityInput to pojemność tablicy entityStates lub 0, co oznacza prośbę o pobranie wymaganej pojemności.
  • entityStateCountOutput to liczba XrSpatialEntityTrackingStateEXT w entityStates lub wymagana pojemność, jeśli entityStateCapacityInput jest niewystarczająca. Ta wartość musi być zawsze taka sama jak entityIdCountOutput .
  • entityStates to tablica XrSpatialEntityTrackingStateEXT . Może mieć wartość NULL, jeśli entityStateCapacityInput wynosi 0.
  • Szczegółowy opis pobierania wymaganego rozmiaru entityIds znajdziesz w sekcji Parametry rozmiaru bufora.

Aplikacja może używać entityIds z xrCreateSpatialEntityFromIdEXT, aby tworzyć uchwyty XrSpatialEntityEXT dla elementów, w przypadku których chce otrzymywać regularne aktualizacje. Aplikacja może następnie użyć tych uchwytów XrSpatialEntityEXT z xrCreateSpatialUpdateSnapshotEXT, aby utworzyć zrzut aktualizacji, który zawiera najnowsze znane dane środowiska wykonawczego dotyczące komponentów podanych elementów.

Prawidłowe użycie (pośrednie)

typedef enum XrSpatialEntityTrackingStateEXT {
    XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT = 1,
    XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT = 2,
    XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT = 3,
    XR_SPATIAL_ENTITY_TRACKING_STATE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialEntityTrackingStateEXT;

XrSpatialEntityTrackingStateEXT wylicza możliwe stany śledzenia elementów przestrzennych:

Typy wyliczeniowe mają następujące znaczenie:

Opis typu wyliczeniowego

XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT

Środowisko wykonawcze przestało śledzić tę encję i nigdy nie wznowi jej śledzenia.

XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT

Środowisko wykonawcze wstrzymało śledzenie tego elementu, ale może je wznowić w przyszłości.

XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT

Środowisko wykonawcze śledzi obecnie ten element, a dane jego komponentu są prawidłowe.

ŚLEDZENIE

WSTRZYMANE

ZATRZYMANO

Rysunek 23. XrSpatialEntityTrackingStateEXT

  • Środowisko wykonawcze może zmienić stan elementu przestrzennego z XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT na XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT, jeśli zawiesi śledzenie tego elementu, ale będzie mieć możliwość wznowienia śledzenia w przyszłości. Środowisko wykonawcze może to zrobić na przykład wtedy, gdy aplikacja utraci fokus, dany element przestrzenny jest zbyt daleko od użytkownika, aby można go było dokładnie śledzić, lub gdy śledzonych jest zbyt wiele elementów i środowisko wykonawcze chce zmniejszyć koszt śledzenia. XrSpatialEntityTrackingStateEXT pomaga aplikacji odizolować się od różnych zasad monitorowania w poszczególnych środowiskach wykonawczych.
  • Środowisko wykonawcze może zmienić stan encji z XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT na XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT lub XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT .
  • Środowisko wykonawcze musi zmienić stan elementu przestrzennego z XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT lub XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT na XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT, jeśli element przestrzenny zostanie utracony, a jego śledzenie nie zostanie przywrócone ani wznowione. Przykładem takiej sytuacji może być utrata śledzenia przez urządzenie, ponowne uruchomienie sesji śledzenia, ale brak możliwości ponownej lokalizacji w środowisku, co powoduje, że wykryte elementy tej sesji śledzenia są traktowane jako nowe.
  • Gdy stan śledzenia encji zostanie ustawiony na XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT , środowisko wykonawcze nie może zmienić go na żaden inny stan.
  • Podczas wysyłania zapytania o dane komponentu elementu przestrzennego za pomocą xrQuerySpatialComponentDataEXT środowisko wykonawcze musi ustawić prawidłowe dane w zawartości buforów dostarczonych przez aplikację w następnym łańcuchu XrSpatialComponentDataQueryResultEXT, jeśli stan elementu to XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT . Jeśli stan encji to XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT lub XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT , środowisko wykonawcze nie może zmieniać zawartości buforów.

Idiom z 2 wywołaniami dla danych komponentu

Struktura XrSpatialBufferEXT jest zdefiniowana w ten sposób:

typedef struct XrSpatialBufferEXT {
    XrSpatialBufferIdEXT      bufferId;
    XrSpatialBufferTypeEXT    bufferType;
} XrSpatialBufferEXT;

Opisy członków

  • bufferId XrSpatialBufferIdEXT danych bufora.
  • bufferType to XrSpatialBufferTypeEXT, który wskazuje typ danych w bufferId . Aplikacja może używać bufferType, aby określić, której funkcji użyć do pobrania rzeczywistych danych bufora.

Niektóre komponenty przestrzenne mają dane o zmiennej wielkości, dlatego do pobierania danych wymagają użycia idiomu dwóch wywołań. W takich przypadkach struktura danych komponentu przestrzennego udostępnia XrSpatialBufferEXT dla każdego bufora o zmiennym rozmiarze, który jest potrzebny w danych tego komponentu.

W przypadku tego samego elementu bufferId środowisko wykonawcze musi dostarczać te same dane z jednego zapytania o dane komponentu do drugiego, nawet między różnymi zrzutami. Inna wartość bufferId między wywołaniami zapytania o dane komponentu wskazuje aplikacji, że dane tego komponentu mogły ulec zmianie.

Prawidłowe użycie (pośrednie)

XR_DEFINE_ATOM(XrSpatialBufferIdEXT)

XrSpatialBufferIdEXT służy do reprezentowania dowolnego rodzaju danych o zmiennym rozmiarze dla komponentu przestrzennego.

Środowisko wykonawcze musi przechowywać XrSpatialBufferIdEXT i jego dane w pamięci przez co najmniej cykl życia elementu XrSpatialSnapshotEXT, który go zawiera. Środowisko wykonawcze może przechowywać XrSpatialBufferIdEXT i jego dane w pamięci dłużej niż cykl życia XrSpatialSnapshotEXT, aby zwracać ten sam identyfikator w ramach zrzutów utworzonych później przez aplikację. W przypadku tego samego XrSpatialBufferIdEXT środowisko wykonawcze musi zawsze zwracać te same dane za pomocą odpowiedniej funkcji xrGetSpatialBuffer*.

typedef enum XrSpatialBufferTypeEXT {
    XR_SPATIAL_BUFFER_TYPE_UNKNOWN_EXT = 0,
    XR_SPATIAL_BUFFER_TYPE_STRING_EXT = 1,
    XR_SPATIAL_BUFFER_TYPE_UINT8_EXT = 2,
    XR_SPATIAL_BUFFER_TYPE_UINT16_EXT = 3,
    XR_SPATIAL_BUFFER_TYPE_UINT32_EXT = 4,
    XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT = 5,
    XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT = 6,
    XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT = 7,
    XR_SPATIAL_BUFFER_TYPE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialBufferTypeEXT;

Wyliczenie XrSpatialBufferTypeEXT identyfikuje różne typy danych reprezentowanego bufora XrSpatialBufferIdEXT .

Opisy elementów wyliczenia

Funkcja xrGetSpatialBufferStringEXT jest zdefiniowana w ten sposób:

XrResult xrGetSpatialBufferStringEXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    char*                                       buffer);

Opisy parametrów

  • snapshot to uchwyt do XrSpatialSnapshotEXT .
  • info zawiera informacje o buforze, który ma zostać odpytany.
  • bufferCapacityInput to pojemność tablicy lub 0, co oznacza prośbę o pobranie wymaganej pojemności.
  • bufferCountOutput to liczba znaków lub wymagana pojemność, jeśli bufferCapacityInput jest niewystarczająca.
  • buffer to tablica obiektów char . Może mieć wartość NULL, jeśli bufferCapacityInput wynosi 0.
  • Szczegółowy opis pobierania wymaganego rozmiaru buffer znajdziesz w sekcji Parametry rozmiaru bufora.

Aplikacja może pobrać dane dla XrSpatialBufferEXT dostarczone przez komponent, gdzie XrSpatialBufferEXT :: bufferType to XR_SPATIAL_BUFFER_TYPE_STRING_EXT, za pomocą xrGetSpatialBufferStringEXT .

Środowisko wykonawcze musi zwracać XR_ERROR_VALIDATION_FAILURE, jeśli XrSpatialBufferTypeEXT dla XrSpatialBufferGetInfoEXT :: bufferId nie jest XR_SPATIAL_BUFFER_TYPE_STRING_EXT .

Środowisko wykonawcze musi zwracać XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT, jeśli XrSpatialBufferGetInfoEXT :: bufferId nie należy do snapshot .

Wartość buffer wypełniona przez środowisko wykonawcze musi być ciągiem znaków UTF-8 zakończonym znakiem null.

Prawidłowe użycie (pośrednie)

  • Rozszerzenie XR_EXT_spatial_entity musi być włączone przed wywołaniem xrGetSpatialBufferStringEXT.
  • snapshot musi być prawidłowym uchwytem XrSpatialSnapshotEXT
  • info musi być wskaźnikiem do prawidłowej struktury XrSpatialBufferGetInfoEXT
  • bufferCountOutput musi być wskaźnikiem do wartości uint32_t
  • Jeśli bufferCapacityInput nie jest 0 , buffer musi być wskaźnikiem do tablicy wartości char bufferCapacityInput

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_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

Funkcja xrGetSpatialBufferUint8EXT jest zdefiniowana w ten sposób:

XrResult xrGetSpatialBufferUint8EXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    uint8_t*                                    buffer);

Opisy parametrów

  • snapshot to uchwyt do XrSpatialSnapshotEXT .
  • info zawiera informacje o buforze, który ma zostać odpytany.
  • bufferCapacityInput to pojemność tablicy lub 0, co oznacza prośbę o pobranie wymaganej pojemności.
  • bufferCountOutput to liczba elementów w tablicy buffer lub wymagana pojemność, jeśli bufferCapacityInput jest niewystarczająca.
  • buffer to tablica obiektów uint8_t . Może mieć wartość NULL, jeśli bufferCapacityInput wynosi 0.
  • Szczegółowy opis pobierania wymaganego rozmiaru buffer znajdziesz w sekcji Parametry rozmiaru bufora.

Aplikacja może pobrać dane dla XrSpatialBufferEXT dostarczonego przez komponent, gdzie XrSpatialBufferEXT :: bufferType to XR_SPATIAL_BUFFER_TYPE_UINT8_EXT, używając xrGetSpatialBufferUint8EXT .

Środowisko wykonawcze musi zwracać XR_ERROR_VALIDATION_FAILURE, jeśli XrSpatialBufferTypeEXT dla XrSpatialBufferGetInfoEXT :: bufferId nie jest XR_SPATIAL_BUFFER_TYPE_UINT8_EXT .

Środowisko wykonawcze musi zwracać XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT, jeśli XrSpatialBufferGetInfoEXT :: bufferId nie należy do snapshot .

Prawidłowe użycie (pośrednie)

  • Rozszerzenie XR_EXT_spatial_entity musi być włączone przed wywołaniem xrGetSpatialBufferUint8EXT.
  • snapshot musi być prawidłowym uchwytem XrSpatialSnapshotEXT
  • info musi być wskaźnikiem do prawidłowej struktury XrSpatialBufferGetInfoEXT
  • bufferCountOutput musi być wskaźnikiem do wartości uint32_t
  • Jeśli bufferCapacityInput nie jest 0 , buffer musi być wskaźnikiem do tablicy wartości bufferCapacityInput uint8_t

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_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

Funkcja xrGetSpatialBufferUint16EXT jest zdefiniowana w ten sposób:

XrResult xrGetSpatialBufferUint16EXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    uint16_t*                                   buffer);

Opisy parametrów

  • snapshot to uchwyt do XrSpatialSnapshotEXT .
  • info zawiera informacje o buforze, który ma zostać odpytany.
  • bufferCapacityInput to pojemność tablicy lub 0, co oznacza prośbę o pobranie wymaganej pojemności.
  • bufferCountOutput to liczba elementów w tablicy buffer lub wymagana pojemność, jeśli bufferCapacityInput jest niewystarczająca.
  • buffer to tablica obiektów uint16_t . Może mieć wartość NULL, jeśli bufferCapacityInput wynosi 0.
  • Szczegółowy opis pobierania wymaganego rozmiaru buffer znajdziesz w sekcji Parametry rozmiaru bufora.

Aplikacja może pobrać dane dla XrSpatialBufferEXT dostarczone przez komponent, gdzie XrSpatialBufferEXT :: bufferType to XR_SPATIAL_BUFFER_TYPE_UINT16_EXT, używając xrGetSpatialBufferUint16EXT .

Środowisko wykonawcze musi zwracać XR_ERROR_VALIDATION_FAILURE, jeśli XrSpatialBufferTypeEXT dla XrSpatialBufferGetInfoEXT :: bufferId nie jest XR_SPATIAL_BUFFER_TYPE_UINT16_EXT .

Środowisko wykonawcze musi zwracać XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT, jeśli XrSpatialBufferGetInfoEXT :: bufferId nie należy do snapshot .

Prawidłowe użycie (pośrednie)

  • Rozszerzenie XR_EXT_spatial_entity musi być włączone przed wywołaniem xrGetSpatialBufferUint16EXT.
  • snapshot musi być prawidłowym uchwytem XrSpatialSnapshotEXT
  • info musi być wskaźnikiem do prawidłowej struktury XrSpatialBufferGetInfoEXT
  • bufferCountOutput musi być wskaźnikiem do wartości uint32_t
  • Jeśli bufferCapacityInput nie jest 0 , buffer musi być wskaźnikiem do tablicy wartości bufferCapacityInput uint16_t

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_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

Funkcja xrGetSpatialBufferUint32EXT jest zdefiniowana w ten sposób:

XrResult xrGetSpatialBufferUint32EXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    uint32_t*                                   buffer);

Opisy parametrów

  • snapshot to uchwyt do XrSpatialSnapshotEXT .
  • info zawiera informacje o buforze, który ma zostać odpytany.
  • bufferCapacityInput to pojemność tablicy lub 0, co oznacza prośbę o pobranie wymaganej pojemności.
  • bufferCountOutput to liczba elementów w tablicy buffer lub wymagana pojemność, jeśli bufferCapacityInput jest niewystarczająca.
  • buffer to tablica obiektów uint32_t . Może mieć wartość NULL, jeśli bufferCapacityInput wynosi 0.
  • Szczegółowy opis pobierania wymaganego rozmiaru buffer znajdziesz w sekcji Parametry rozmiaru bufora.

Aplikacja może pobrać dane dla XrSpatialBufferEXT dostarczone przez komponent, gdzie XrSpatialBufferEXT :: bufferType to XR_SPATIAL_BUFFER_TYPE_UINT32_EXT, za pomocą xrGetSpatialBufferUint32EXT .

Środowisko wykonawcze musi zwracać XR_ERROR_VALIDATION_FAILURE, jeśli XrSpatialBufferTypeEXT dla XrSpatialBufferGetInfoEXT :: bufferId nie jest XR_SPATIAL_BUFFER_TYPE_UINT32_EXT .

Środowisko wykonawcze musi zwracać XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT, jeśli XrSpatialBufferGetInfoEXT :: bufferId nie należy do snapshot .

Prawidłowe użycie (pośrednie)

  • Rozszerzenie XR_EXT_spatial_entity musi być włączone przed wywołaniem xrGetSpatialBufferUint32EXT.
  • snapshot musi być prawidłowym uchwytem XrSpatialSnapshotEXT
  • info musi być wskaźnikiem do prawidłowej struktury XrSpatialBufferGetInfoEXT
  • bufferCountOutput musi być wskaźnikiem do wartości uint32_t
  • Jeśli bufferCapacityInput nie jest 0 , buffer musi być wskaźnikiem do tablicy wartości bufferCapacityInput uint32_t

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_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

Funkcja xrGetSpatialBufferFloatEXT jest zdefiniowana w ten sposób:

XrResult xrGetSpatialBufferFloatEXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    float*                                      buffer);

Opisy parametrów

  • snapshot to uchwyt do XrSpatialSnapshotEXT .
  • info zawiera informacje o buforze, który ma zostać odpytany.
  • bufferCapacityInput to pojemność tablicy lub 0, co oznacza prośbę o pobranie wymaganej pojemności.
  • bufferCountOutput to liczba elementów w tablicy buffer lub wymagana pojemność, jeśli bufferCapacityInput jest niewystarczająca.
  • buffer to tablica obiektów float . Może mieć wartość NULL, jeśli bufferCapacityInput wynosi 0.
  • Szczegółowy opis pobierania wymaganego rozmiaru buffer znajdziesz w sekcji Parametry rozmiaru bufora.

Aplikacja może pobrać dane dla XrSpatialBufferEXT dostarczone przez komponent, gdzie XrSpatialBufferEXT :: bufferType to XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT, za pomocą xrGetSpatialBufferFloatEXT .

Środowisko wykonawcze musi zwracać XR_ERROR_VALIDATION_FAILURE, jeśli XrSpatialBufferTypeEXT dla XrSpatialBufferGetInfoEXT :: bufferId nie jest XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT .

Środowisko wykonawcze musi zwracać XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT, jeśli XrSpatialBufferGetInfoEXT :: bufferId nie należy do snapshot .

Prawidłowe użycie (pośrednie)

  • Rozszerzenie XR_EXT_spatial_entity musi być włączone przed wywołaniem xrGetSpatialBufferFloatEXT.
  • snapshot musi być prawidłowym uchwytem XrSpatialSnapshotEXT
  • info musi być wskaźnikiem do prawidłowej struktury XrSpatialBufferGetInfoEXT
  • bufferCountOutput musi być wskaźnikiem do wartości uint32_t
  • Jeśli bufferCapacityInput nie jest 0 , buffer musi być wskaźnikiem do tablicy wartości bufferCapacityInput float

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_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

Funkcja xrGetSpatialBufferVector2fEXT jest zdefiniowana w ten sposób:

XrResult xrGetSpatialBufferVector2fEXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    XrVector2f*                                 buffer);

Opisy parametrów

  • snapshot to uchwyt do XrSpatialSnapshotEXT .
  • info zawiera informacje o buforze, który ma zostać odpytany.
  • bufferCapacityInput to pojemność tablicy lub 0, co oznacza prośbę o pobranie wymaganej pojemności.
  • bufferCountOutput to liczba elementów w tablicy buffer lub wymagana pojemność, jeśli bufferCapacityInput jest niewystarczająca.
  • buffer to tablica obiektów XrVector2f . Może mieć wartość NULL, jeśli bufferCapacityInput wynosi 0.
  • Szczegółowy opis pobierania wymaganego rozmiaru buffer znajdziesz w sekcji Parametry rozmiaru bufora.

Aplikacja może pobrać dane dla XrSpatialBufferEXT dostarczonego przez komponent, gdzie XrSpatialBufferEXT :: bufferType to XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT, używając xrGetSpatialBufferVector2fEXT .

Środowisko wykonawcze musi zwracać XR_ERROR_VALIDATION_FAILURE, jeśli XrSpatialBufferTypeEXT dla XrSpatialBufferGetInfoEXT :: bufferId nie jest XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT .

Środowisko wykonawcze musi zwracać XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT, jeśli XrSpatialBufferGetInfoEXT :: bufferId nie należy do snapshot .

Prawidłowe użycie (pośrednie)

  • Rozszerzenie XR_EXT_spatial_entity musi być włączone przed wywołaniem xrGetSpatialBufferVector2fEXT.
  • snapshot musi być prawidłowym uchwytem XrSpatialSnapshotEXT
  • info musi być wskaźnikiem do prawidłowej struktury XrSpatialBufferGetInfoEXT
  • bufferCountOutput musi być wskaźnikiem do wartości uint32_t
  • Jeśli bufferCapacityInput nie jest równe 0 , buffer musi być wskaźnikiem do tablicy struktur bufferCapacityInput XrVector2f

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_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

Funkcja xrGetSpatialBufferVector3fEXT jest zdefiniowana w ten sposób:

XrResult xrGetSpatialBufferVector3fEXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    XrVector3f*                                 buffer);

Opisy parametrów

  • snapshot to uchwyt do XrSpatialSnapshotEXT .
  • info zawiera informacje o buforze, który ma zostać odpytany.
  • bufferCapacityInput to pojemność tablicy lub 0, co oznacza prośbę o pobranie wymaganej pojemności.
  • bufferCountOutput to liczba elementów w tablicy buffer lub wymagana pojemność, jeśli bufferCapacityInput jest niewystarczająca.
  • buffer to tablica XrVector3f . Może mieć wartość NULL, jeśli bufferCapacityInput wynosi 0.
  • Szczegółowy opis pobierania wymaganego rozmiaru buffer znajdziesz w sekcji Parametry rozmiaru bufora.

Aplikacja może pobrać dane dla XrSpatialBufferEXT dostarczonego przez komponent, gdzie XrSpatialBufferEXT :: bufferType to XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT, używając xrGetSpatialBufferVector3fEXT .

Środowisko wykonawcze musi zwracać XR_ERROR_VALIDATION_FAILURE, jeśli XrSpatialBufferTypeEXT dla XrSpatialBufferGetInfoEXT :: bufferId nie jest XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT .

Środowisko wykonawcze musi zwracać XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT, jeśli XrSpatialBufferGetInfoEXT :: bufferId nie należy do snapshot .

Prawidłowe użycie (pośrednie)

  • Rozszerzenie XR_EXT_spatial_entity musi być włączone przed wywołaniem xrGetSpatialBufferVector3fEXT.
  • snapshot musi być prawidłowym uchwytem XrSpatialSnapshotEXT
  • info musi być wskaźnikiem do prawidłowej struktury XrSpatialBufferGetInfoEXT
  • bufferCountOutput musi być wskaźnikiem do wartości uint32_t
  • Jeśli bufferCapacityInput nie jest 0 , buffer musi być wskaźnikiem do tablicy struktur bufferCapacityInput XrVector3f

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_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

Struktura XrSpatialBufferGetInfoEXT jest zdefiniowana w ten sposób:

typedef struct XrSpatialBufferGetInfoEXT {
    XrStructureType         type;
    const void*             next;
    XrSpatialBufferIdEXT    bufferId;
} XrSpatialBufferGetInfoEXT;

Opisy członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur.
  • bufferId XrSpatialBufferIdEXT bufora, którego dane chcesz pobrać.

Prawidłowe użycie (pośrednie)

#define XR_NULL_SPATIAL_BUFFER_ID_EXT 0

XR_NULL_SPATIAL_BUFFER_ID_EXT to zarezerwowana wartość reprezentująca nieprawidłowy identyfikator XrSpatialBufferIdEXT . Może być przekazywany do funkcji interfejsu API i zwracany przez nie tylko wtedy, gdy jest to wyraźnie dozwolone.

Utwórz zrzut aktualizacji

Funkcja xrCreateSpatialUpdateSnapshotEXT jest zdefiniowana w ten sposób:

XrResult xrCreateSpatialUpdateSnapshotEXT(
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialUpdateSnapshotCreateInfoEXT* createInfo,
    XrSpatialSnapshotEXT*                       snapshot);

Opisy parametrów

Aplikacja może używać funkcji xrCreateSpatialUpdateSnapshotEXT do tworzenia migawki i pobierania najnowszych danych komponentów dla określonych encji znanych środowisku wykonawczemu. Podczas tworzenia migawki aplikacje mogą podawać uchwyty XrSpatialEntityEXT i typy komponentów, które ich interesują.

Aplikacja może używać XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes do filtrowania listy komponentów, których dane muszą być uwzględnione w zdjęciu. Jeśli aplikacja udostępnia prawidłową listę typów komponentów przestrzennych w XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes, środowisko wykonawcze musi uwzględniać w migawce tylko te elementy przestrzenne, które mają co najmniej 1 z komponentów podanych w XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes . Środowisko wykonawcze musi też zawierać tylko dane dotyczące tych komponentów w zrzucie.

Środowisko wykonawcze musi zwracać XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT, jeśli którykolwiek z parametrów XrSpatialComponentTypeEXT w XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes nie jest włączony dla funkcji przestrzennych przekazanych do XrSpatialContextCreateInfoEXT :: capabilityConfigs podczas tworzenia spatialContext .

Jeśli aplikacja nie udostępnia listy typów komponentów przestrzennych w XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes , środowisko wykonawcze musi uwzględnić w migawce wszystkie elementy przestrzenne wymienione w XrSpatialUpdateSnapshotCreateInfoEXT :: entities i musi uwzględnić dane wszystkich włączonych komponentów funkcji skonfigurowanych dla spatialContext .

Środowisko wykonawcze nie może zawierać elementów przestrzennych, które nie są wymienione w XrSpatialUpdateSnapshotCreateInfoEXT :: entities w snapshot .

Aplikacja może utworzyć dowolną liczbę zrzutów, ale musi pamiętać o pamięci przydzielonej dla każdego nowego zrzutu i musi zniszczyć zrzuty, gdy nie są już potrzebne.

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_COMPONENT_NOT_ENABLED_EXT
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

Struktura XrSpatialUpdateSnapshotCreateInfoEXT jest zdefiniowana w ten sposób:

typedef struct XrSpatialUpdateSnapshotCreateInfoEXT {
    XrStructureType                     type;
    const void*                         next;
    uint32_t                            entityCount;
    const XrSpatialEntityEXT*           entities;
    uint32_t                            componentTypeCount;
    const XrSpatialComponentTypeEXT*    componentTypes;
    XrSpace                             baseSpace;
    XrTime                              time;
} XrSpatialUpdateSnapshotCreateInfoEXT;

Opisy członków

  • 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.
  • entityCount to uint32_t opisujący liczbę elementów w tablicy entities.
  • entities to tablica XrSpatialEntityEXT, dla której środowisko wykonawcze musi uwzględnić dane komponentu w zrzucie.
  • componentTypeCount to uint32_t opisujący liczbę elementów w tablicy componentTypes.
  • componentTypes to tablica XrSpatialComponentTypeEXT, dla której środowisko wykonawcze musi uwzględnić dane w migawce.
  • baseSpace to XrSpace, względem którego będą znajdować się wszystkie lokalizacje aktualizacji XrSpatialSnapshotEXT.
  • time to XrTime, w której będą znajdować się wszystkie lokalizacje aktualizacji XrSpatialSnapshotEXT.

Prawidłowe użycie (pośrednie)

  • Rozszerzenie XR_EXT_spatial_entity musi być włączone przed użyciem XrSpatialUpdateSnapshotCreateInfoEXT.
  • type musi mieć wartość XR_TYPE_SPATIAL_UPDATE_SNAPSHOT_CREATE_INFO_EXT
  • next musi mieć wartość NULL lub być prawidłowym wskaźnikiem do następnej struktury w łańcuchu struktur
  • entities musi być wskaźnikiem do tablicy entityCount prawidłowych uchwytów XrSpatialEntityEXT.
  • Jeśli componentTypeCount nie jest równe 0 , componentTypes musi być wskaźnikiem do tablicy prawidłowych wartości componentTypeCount XrSpatialComponentTypeEXT.
  • baseSpace musi być prawidłowym nickiem XrSpace
  • Parametr entityCount musi być większy niż 0
  • Zarówno baseSpace, jak i elementy entities muszą zostać utworzone, przydzielone lub pobrane z tej samej sesji XrSession.

Zniszcz zrzut

Funkcja xrDestroySpatialSnapshotEXT jest zdefiniowana w ten sposób:

XrResult xrDestroySpatialSnapshotEXT(
    XrSpatialSnapshotEXT                        snapshot);

Opisy parametrów

Aplikacja może wywołać funkcję xrDestroySpatialSnapshotEXT, aby zniszczyć uchwyt XrSpatialSnapshotEXT i powiązane z nim zasoby.

Prawidłowe użycie (pośrednie)

Bezpieczeństwo wątków

  • Dostęp do snapshot 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

Typowe komponenty

Ograniczony 2D

Dane komponentu

Struktura XrSpatialBounded2DDataEXT jest zdefiniowana w ten sposób:

typedef struct XrSpatialBounded2DDataEXT {
    XrPosef        center;
    XrExtent2Df    extents;
} XrSpatialBounded2DDataEXT;

Opisy członków

  • center to XrPosef określający geometryczny środek ograniczonego komponentu 2D.
  • extents to zakresy ograniczonego komponentu 2D wzdłuż osi X (extents.width) i osi Y (extents.height) wyśrodkowane na center .

extents i XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT odnoszą się do rozmiaru elementu na płaszczyźnie x-y układu współrzędnych płaszczyzny. Płaszczyzna o pozycji {0, 0, 0}, obrocie {0, 0, 0, 1} (brak obrotu) i rozmiarze {1, 1} odnosi się do płaszczyzny o wymiarach 1 m x 1 m wyśrodkowanej w punkcie {0, 0, 0} z wektorem normalnym przedniej powierzchni skierowanym w kierunku +Z w przestrzeni komponentu.

X X Y Y Z Z Wysokość Wysokość Y Y Z Z X X Płaszczyzna pionowa Płaszczyzna pionowa Płaszczyzna pozioma Płaszczyzna pozioma Szerokość Szerokość Szerokość Szerokość Wysokość Wysokość

Rysunek 24. Układ współrzędnych komponentu Bounded2D

Uwaga

OpenXR używa płaszczyzny X-Y z +Z jako wektorem normalnym, ale inne interfejsy API mogą używać płaszczyzny X-Z z +Y jako wektorem normalnym. Płaszczyznę X-Y można przekształcić w płaszczyznę X-Z, obracając ją o -π/2 radianów wokół osi +X.

Prawidłowe użycie (pośrednie)

Struktura listy komponentów do wysyłania zapytań o dane

Struktura XrSpatialComponentBounded2DListEXT jest zdefiniowana w ten sposób:

typedef struct XrSpatialComponentBounded2DListEXT {
    XrStructureType               type;
    void*                         next;
    uint32_t                      boundCount;
    XrSpatialBounded2DDataEXT*    bounds;
} XrSpatialComponentBounded2DListEXT;

Opisy członków

  • 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.
  • boundCount to uint32_t opisujący liczbę elementów w tablicy bounds.
  • bounds to tablica XrSpatialBounded2DDataEXT .

Środowisko wykonawcze musi zwrócić XR_ERROR_VALIDATION_FAILURE z xrQuerySpatialComponentDataEXT, jeśli XrSpatialComponentBounded2DListEXT znajduje się w następnym łańcuchu XrSpatialComponentDataQueryResultEXT :: next, ale XrSpatialComponentDataQueryConditionEXT ::componentTypeCount nie jest równe zero, a XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT nie jest uwzględnione w XrSpatialComponentDataQueryConditionEXT :: componentTypes .

Środowisko wykonawcze musi zwracać XR_ERROR_SIZE_INSUFFICIENT z xrQuerySpatialComponentDataEXT, jeśli boundCount jest mniejsze niż XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

Jeśli funkcja xrQuerySpatialComponentDataEXT :: snapshot została utworzona za pomocą funkcji xrCreateSpatialDiscoverySnapshotCompleteEXT , środowisko wykonawcze musi podać XrSpatialBounded2DDataEXT :: center w XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace i XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time .

Jeśli funkcja xrQuerySpatialComponentDataEXT :: snapshot została utworzona za pomocą funkcji xrCreateSpatialUpdateSnapshotEXT , środowisko wykonawcze musi podać XrSpatialBounded2DDataEXT :: center w XrSpatialUpdateSnapshotCreateInfoEXT :: baseSpace i XrSpatialUpdateSnapshotCreateInfoEXT :: time .

Prawidłowe użycie (pośrednie)

Konfiguracja

Jeśli XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT jest wymieniony w XrSpatialCapabilityComponentTypesEXT :: componentTypes dla danej funkcji, aplikacja może ją włączyć, dodając wartość wyliczeniową do listy XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents. Ten komponent nie wymaga żadnej specjalnej konfiguracji, aby można go było uwzględnić w następnym łańcuchu XrSpatialCapabilityConfigurationBaseHeaderEXT .

Ograniczony 3D

Dane komponentu

XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT używa XrBoxf do przechowywania danych.

Struktura listy komponentów do wysyłania zapytań o dane

Struktura XrSpatialComponentBounded3DListEXT jest zdefiniowana w ten sposób:

typedef struct XrSpatialComponentBounded3DListEXT {
    XrStructureType    type;
    void*              next;
    uint32_t           boundCount;
    XrBoxf*            bounds;
} XrSpatialComponentBounded3DListEXT;

Opisy członków

  • 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.
  • boundCount to uint32_t opisujący liczbę elementów w tablicy bounds.
  • bounds to tablica obiektów XrBoxf .

Środowisko wykonawcze musi zwracać XR_ERROR_VALIDATION_FAILURE z xrQuerySpatialComponentDataEXT, jeśli XrSpatialComponentBounded3DListEXT znajduje się w następnym łańcuchu XrSpatialComponentDataQueryResultEXT :: next, ale XrSpatialComponentDataQueryConditionEXT ::componentTypeCount nie jest równe zero, a XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT nie jest uwzględnione w XrSpatialComponentDataQueryConditionEXT :: componentTypes .

Środowisko wykonawcze musi zwracać XR_ERROR_SIZE_INSUFFICIENT z xrQuerySpatialComponentDataEXT, jeśli boundCount jest mniejsze niż XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

Jeśli funkcja xrQuerySpatialComponentDataEXT :: snapshot została utworzona z funkcji xrCreateSpatialDiscoverySnapshotCompleteEXT , środowisko wykonawcze musi udostępnić XrBoxf :: center w XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace w XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time .

Jeśli funkcja xrQuerySpatialComponentDataEXT :: snapshot została utworzona za pomocą funkcji xrCreateSpatialUpdateSnapshotEXT , środowisko wykonawcze musi udostępnić XrBoxf :: center w XrSpatialUpdateSnapshotCreateInfoEXT :: baseSpace w XrSpatialUpdateSnapshotCreateInfoEXT :: time .

Prawidłowe użycie (pośrednie)

Konfiguracja

Jeśli XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT jest wymieniony w XrSpatialCapabilityComponentTypesEXT :: componentTypes dla danej funkcji, aplikacja może ją włączyć, dodając enum do listy XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents. Ten komponent nie wymaga żadnej specjalnej konfiguracji, aby można go było uwzględnić w następnym łańcuchu XrSpatialCapabilityConfigurationBaseHeaderEXT .

Rodzic

Dane komponentu

XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT używa XrSpatialEntityIdEXT do przechowywania danych.

Struktura listy komponentów do wysyłania zapytań o dane

Struktura XrSpatialComponentParentListEXT jest zdefiniowana w ten sposób:

typedef struct XrSpatialComponentParentListEXT {
    XrStructureType          type;
    void*                    next;
    uint32_t                 parentCount;
    XrSpatialEntityIdEXT*    parents;
} XrSpatialComponentParentListEXT;

Opisy członków

  • 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.
  • parentCount to uint32_t opisujący liczbę elementów w tablicy parents.
  • parents to tablica obiektów XrSpatialEntityIdEXT .

Środowisko wykonawcze musi zwracać XR_ERROR_VALIDATION_FAILURE z xrQuerySpatialComponentDataEXT, jeśli XrSpatialComponentParentListEXT znajduje się w następnym łańcuchu XrSpatialComponentDataQueryResultEXT :: next, ale XrSpatialComponentDataQueryConditionEXT ::componentTypeCount nie jest równe 0, a XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT nie jest uwzględnione w XrSpatialComponentDataQueryConditionEXT :: componentTypes .

Środowisko wykonawcze musi zwracać XR_ERROR_SIZE_INSUFFICIENT z xrQuerySpatialComponentDataEXT, jeśli parentCount jest mniejsze niż XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

Prawidłowe użycie (pośrednie)

  • Rozszerzenie XR_EXT_spatial_entity musi być włączone przed użyciem XrSpatialComponentParentListEXT.
  • type musi mieć wartość XR_TYPE_SPATIAL_COMPONENT_PARENT_LIST_EXT
  • next musi mieć wartość NULL lub być prawidłowym wskaźnikiem do następnej struktury w łańcuchu struktur
  • parents musi być wskaźnikiem do tablicy wartości parentCount XrSpatialEntityIdEXT
  • Parametr parentCount musi być większy niż 0
Konfiguracja

Jeśli XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT jest wymieniony w XrSpatialCapabilityComponentTypesEXT :: componentTypes dla danej funkcji, aplikacja może ją włączyć, dodając enum do listy XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents. Ten komponent nie wymaga żadnej specjalnej konfiguracji, aby można go było uwzględnić w następnym łańcuchu XrSpatialCapabilityConfigurationBaseHeaderEXT .

Siatka 3D

Dane komponentu

Struktura XrSpatialMeshDataEXT jest zdefiniowana w ten sposób:

typedef struct XrSpatialMeshDataEXT {
    XrPosef               origin;
    XrSpatialBufferEXT    vertexBuffer;
    XrSpatialBufferEXT    indexBuffer;
} XrSpatialMeshDataEXT;

Opisy członków

  • origin to XrPosef określający punkt początkowy siatki. Wszystkie wierzchołki siatki muszą być określone względem tego punktu początkowego.
  • vertexBuffer to XrSpatialBufferEXT, który podaje identyfikator bufora reprezentującego bufor wierzchołków encji, na której znajduje się ten komponent. Pozycja wierzchołków musi być względna do origin .
  • indexBuffer to XrSpatialBufferEXT, który podaje identyfikator bufora reprezentującego tablicę indeksów trójkątów, określając indeksy wierzchołków siatki w vertexBuffer . Indeksy trójkątów muszą być zwracane w kolejności w lewo, a 3 indeksy oznaczają 1 trójkąt.

Typ komponentu używający XrSpatialMeshDataEXT musi określać XrSpatialBufferTypeEXT dla vertexBuffer i indexBuffer .

Prawidłowe użycie (pośrednie)

Struktura listy komponentów do wysyłania zapytań o dane

Struktura XrSpatialComponentMesh3DListEXT jest zdefiniowana w ten sposób:

typedef struct XrSpatialComponentMesh3DListEXT {
    XrStructureType          type;
    void*                    next;
    uint32_t                 meshCount;
    XrSpatialMeshDataEXT*    meshes;
} XrSpatialComponentMesh3DListEXT;

Opisy członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur.
  • meshCount to uint32_t opisujący liczbę elementów w tablicy meshes.
  • meshes to tablica XrSpatialMeshDataEXT .

Aplikacja może wysyłać zapytania do komponentu siatki 3D elementów przestrzennych w XrSpatialSnapshotEXT, dodając XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT w XrSpatialComponentDataQueryConditionEXT :: componentTypes i dodając XrSpatialComponentMesh3DListEXT do następnego łańcucha wskaźników XrSpatialComponentDataQueryResultEXT .

Środowisko wykonawcze musi zwracać XR_ERROR_VALIDATION_FAILURE z xrQuerySpatialComponentDataEXT, jeśli XrSpatialComponentMesh3DListEXT znajduje się w następnym łańcuchu XrSpatialComponentDataQueryResultEXT :: next, ale XrSpatialComponentDataQueryConditionEXT ::componentTypeCount nie jest równe zero, a XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT nie jest uwzględnione w XrSpatialComponentDataQueryConditionEXT :: componentTypes .

Środowisko wykonawcze musi zwracać XR_ERROR_SIZE_INSUFFICIENT z xrQuerySpatialComponentDataEXT, jeśli meshCount jest mniejsze niż XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

W przypadku XrSpatialMeshDataEXT wypełnionego przez środowisko wykonawcze w tablicy meshes, XrSpatialBufferEXT :: bufferType dla XrSpatialMeshDataEXT :: vertexBuffer musi być XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT, a XrSpatialBufferEXT :: bufferType dla XrSpatialMeshDataEXT :: indexBuffer musi być XR_SPATIAL_BUFFER_TYPE_UINT32_EXT .

Prawidłowe użycie (pośrednie)

Konfiguracja

Jeśli XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT jest wymieniony w XrSpatialCapabilityComponentTypesEXT :: componentTypes dla danej funkcji, aplikacja może go włączyć, dodając enum do listy XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents struktury pochodnej XrSpatialCapabilityConfigurationBaseHeaderEXT funkcji, która obsługuje ten komponent.

Ten komponent nie wymaga żadnej specjalnej konfiguracji, aby można go było uwzględnić w następnym łańcuchu XrSpatialCapabilityConfigurationBaseHeaderEXT .

Filtry stanu śledzenia

Struktura XrSpatialFilterTrackingStateEXT jest zdefiniowana w ten sposób:

typedef struct XrSpatialFilterTrackingStateEXT {
    XrStructureType                    type;
    const void*                        next;
    XrSpatialEntityTrackingStateEXT    trackingState;
} XrSpatialFilterTrackingStateEXT;

Opisy członków

Aplikacja może używać XrSpatialFilterTrackingStateEXT w następnym łańcuchu XrSpatialDiscoverySnapshotCreateInfoEXT, aby ograniczyć wykrywanie tylko do tych elementów, których stan śledzenia to trackingState .

Aplikacja może używać XrSpatialFilterTrackingStateEXT w następnym łańcuchu XrSpatialComponentDataQueryConditionEXT, aby ograniczyć zakres zapytania o dane komponentu z migawki tylko do encji, których stan śledzenia to trackingState .

Prawidłowe użycie (pośrednie)

Przykładowy kod

Korzystanie z aplikacji

Aplikacje zwykle używają rozszerzenia elementu przestrzennego w następujący sposób:

Odkrywanie elementów przestrzennych i wykonywanie zapytań o dane komponentów

Poniższy przykładowy kod pokazuje, jak wykrywać elementy przestrzenne dla funkcji „Foo” i odpytywać dane komponentu.

/****************************/
/* Capability definition    */
/****************************/
// Foo capability has the following components -
// - XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT
#define XR_SPATIAL_CAPABILITY_FOO ((XrSpatialCapabilityEXT)1000740000U)

#define XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_FOO_EXT ((XrStructureType)1000740000U)
// Derives from XrSpatialCapabilityConfigurationBaseHeaderEXT
typedef struct XrSpatialCapabilityConfigurationFooEXT {
  XrStructureType                     type;
  const void* XR_MAY_ALIAS            next;
  XrSpatialCapabilityEXT              capability;
  uint32_t                            enabledComponentCount;
  const XrSpatialComponentTypeEXT*    enabledComponents;
} XrSpatialCapabilityConfigurationFooEXT;

/******************************/
/* End capability definition  */
/******************************/

auto waitUntilReady = [](XrFutureEXT future) {
  XrFuturePollInfoEXT pollInfo{XR_TYPE_FUTURE_POLL_INFO_EXT};
  XrFuturePollResultEXT pollResult{XR_TYPE_FUTURE_POLL_RESULT_EXT};
  pollInfo.future = future;
  do {
    // sleep(1);
    CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));
  } while (pollResult.state != XR_FUTURE_STATE_READY_EXT);
};

// Create a spatial spatial context
XrSpatialContextEXT spatialContext{};
{
  const std::array<XrSpatialComponentTypeEXT, 1> enabledComponents = {
    XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT,
  };

  // Configure Foo capability for the spatial context
  XrSpatialCapabilityConfigurationFooEXT fooConfig{XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_FOO_EXT};
  fooConfig.capability = XR_SPATIAL_CAPABILITY_FOO;
  fooConfig.enabledComponentCount = enabledComponents.size();
  fooConfig.enabledComponents = enabledComponents.data();

  std::vector<XrSpatialCapabilityConfigurationBaseHeaderEXT*> capabilityConfigs;
  capabilityConfigs.push_back(reinterpret_cast<XrSpatialCapabilityConfigurationBaseHeaderEXT*>(&fooConfig));

  XrSpatialContextCreateInfoEXT spatialContextCreateInfo{XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT};
  spatialContextCreateInfo.capabilityConfigCount = capabilityConfigs.size();
  spatialContextCreateInfo.capabilityConfigs = capabilityConfigs.data();
  XrFutureEXT createContextFuture;
  CHK_XR(xrCreateSpatialContextAsyncEXT(session, &spatialContextCreateInfo, &createContextFuture));

  waitUntilReady(createContextFuture);

  XrCreateSpatialContextCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialContextCompleteEXT(session, createContextFuture, &completion));
  if (completion.futureResult != XR_SUCCESS) {
    return;
  }

  spatialContext = completion.spatialContext;
}

auto discoverSpatialEntities = [&](XrSpatialContextEXT spatialContext, XrTime time) {
  // We want to look for entities that have the following components.
  std::array<XrSpatialComponentTypeEXT, 1> snapshotComponents {XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT};

  XrSpatialDiscoverySnapshotCreateInfoEXT snapshotCreateInfo{XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT};
  snapshotCreateInfo.componentTypeCount = snapshotComponents.size();
  snapshotCreateInfo.componentTypes = snapshotComponents.data();
  XrFutureEXT future = XR_NULL_FUTURE_EXT;
  CHK_XR(xrCreateSpatialDiscoverySnapshotAsyncEXT(spatialContext, &snapshotCreateInfo, &future));

  waitUntilReady(future);

  XrCreateSpatialDiscoverySnapshotCompletionInfoEXT completionInfo{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT};
  completionInfo.baseSpace = localSpace;
  completionInfo.time = time;
  completionInfo.future = future;

  XrCreateSpatialDiscoverySnapshotCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialDiscoverySnapshotCompleteEXT(spatialContext, &completionInfo, &completion));
  if (completion.futureResult == XR_SUCCESS) {
    // Query for the bounded2d component data
    XrSpatialComponentTypeEXT componentToQuery = XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT;
    XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
    queryCond.componentTypes = &componentToQuery;

    XrSpatialComponentDataQueryResultEXT queryResult{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT};
    queryResult.entityIdCapacityInput = 0;
    queryResult.entityIds = nullptr;
    queryResult.entityStateCapacityInput = 0;
    queryResult.entityStates = nullptr;
    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    std::vector<XrSpatialEntityIdEXT> entityIds(queryResult.entityIdCountOutput);
    std::vector<XrSpatialEntityTrackingStateEXT> entityStates(queryResult.entityStateCountOutput);
    queryResult.entityIdCapacityInput = entityIds.size();
    queryResult.entityIds = entityIds.data();
    queryResult.entityStateCapacityInput = entityStates.size();
    queryResult.entityStates = entityStates.data();

    std::vector<XrSpatialBounded2DDataEXT> bounded2d(queryResult.entityIdCountOutput);
    XrSpatialComponentBounded2DListEXT boundsList{XR_TYPE_SPATIAL_COMPONENT_BOUNDED_2D_LIST_EXT};
    boundsList.boundCount = bounded2d.size();
    boundsList.bounds = bounded2d.data();
    queryResult.next = &boundsList;

    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
      if (entityStates[i] == XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT) {
        // 2D extents for entity entityIds[i] is bounded2d[i].extents.
      }
    }

    CHK_XR(xrDestroySpatialSnapshotEXT(completion.snapshot));
  }
};

while (1) {
  // ...
  // For every frame in frame loop
  // ...

  XrFrameState frameState;  // previously returned from xrWaitFrame
  const XrTime time = frameState.predictedDisplayTime;

  // Poll for the XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT event
  XrEventDataBuffer event = {XR_TYPE_EVENT_DATA_BUFFER};
  XrResult result = xrPollEvent(instance, &event);
  if (result == XR_SUCCESS) {
      switch (event.type) {
          case XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT: {
              const XrEventDataSpatialDiscoveryRecommendedEXT& eventdata =
                  *reinterpret_cast<XrEventDataSpatialDiscoveryRecommendedEXT*>(&event);
              // Discover spatial entities for the context that we received the "discovery
              // recommended" event for.
              discoverSpatialEntities(eventdata.spatialContext, time);
              break;
          }
      }
  }

  // ...
  // Finish frame loop
  // ...
}

CHK_XR(xrDestroySpatialContextEXT(spatialContext));

Dane bufora zapytań

Poniższy przykładowy kod pokazuje, jak uzyskać dane komponentu, który udostępnia XrSpatialBufferEXT .

/****************************/
/* Component definition     */
/****************************/
// Foo component that provides an XrVector3f buffer
#define XR_SPATIAL_COMPONENT_TYPE_FOO_EXT ((XrSpatialComponentTypeEXT)1000740000U)

#define XR_TYPE_SPATIAL_COMPONENT_FOO_LIST_EXT ((XrStructureType)1000740000U)

// XrSpatialComponentFooListEXT extends XrSpatialComponentDataQueryResultEXT
typedef struct XrSpatialComponentFooListEXT {
    XrStructureType                   type;
    void* XR_MAY_ALIAS                next;
    uint32_t                          fooCount;
    XrSpatialBufferEXT*               foo;
} XrSpatialComponentFooListEXT;

/******************************/
/* End Component definition  */
/******************************/

// Query for the foo component data
XrSpatialComponentTypeEXT componentToQuery = XR_SPATIAL_COMPONENT_TYPE_FOO_EXT;
XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
queryCond.componentTypeCount = 1;
queryCond.componentTypes = &componentToQuery;

XrSpatialComponentDataQueryResultEXT queryResult{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT};
CHK_XR(xrQuerySpatialComponentDataEXT(snapshot, &queryCond, &queryResult));

std::vector<XrSpatialEntityIdEXT> entityIds(queryResult.entityIdCountOutput);
queryResult.entityIdCapacityInput = entityIds.size();
queryResult.entityIds = entityIds.data();

std::vector<XrSpatialBufferEXT> fooBuffers(queryResult.entityIdCountOutput);
XrSpatialComponentFooListEXT fooList{XR_TYPE_SPATIAL_COMPONENT_FOO_LIST_EXT};
fooList.fooCount = fooBuffers.size();
fooList.foo = fooBuffers.data();
queryResult.next = &fooList;

CHK_XR(xrQuerySpatialComponentDataEXT(snapshot, &queryCond, &queryResult));

for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
  // foo component data for entity entityIds[i]
  if (fooBuffers[i].bufferType == XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT) {
    XrSpatialBufferGetInfoEXT getInfo{XR_TYPE_SPATIAL_BUFFER_GET_INFO_EXT};
    getInfo.bufferId = fooBuffers[i].bufferId;
    uint32_t bufferCountOutput;
    CHK_XR(xrGetSpatialBufferVector3fEXT(snapshot, &getInfo, 0, &bufferCountOutput, nullptr));
    std::vector<XrVector3f> vertexBuffer(bufferCountOutput);
    CHK_XR(xrGetSpatialBufferVector3fEXT(snapshot, &getInfo, bufferCountOutput, &bufferCountOutput, vertexBuffer.data()));

    // XrVertex3f buffer for entity entityIds[i] is now available in vertexBuffer vector.
  }
}

Wytyczne dotyczące rozszerzeń

  • Jeśli rozszerzenie definiuje nowy element XrSpatialComponentTypeEXT, który dostarcza dodatkowe dane o obiekcie przestrzennym,

  • Rozszerzenia mogą definiować struktury, które rozszerzają XrSpatialDiscoverySnapshotCreateInfoEXT, aby udostępniać dodatkowe filtry do wykrywania. Filtry do tworzenia zrzutu nie mogą wpływać na konfigurację kontekstu przestrzennego, ale mają służyć do dostarczania środowisku wykonawczemu wskazówek dotyczących tego, jakie encje i dane mają być uwzględnione w zrzucie zgodnie z bieżącą konfiguracją kontekstu przestrzennego (a tym samym bieżącą konfiguracją usług podstawowych).

  • Jeśli rozszerzenie definiuje nowy element XrSpatialCapabilityEXT ,

  • Jeśli rozszerzenie definiuje nową funkcję XrSpatialCapabilityFeatureEXT, musi też definiować odpowiednią strukturę konfiguracji, którą można połączyć z następnym wskaźnikiem XrSpatialCapabilityConfigurationBaseHeaderEXT, którego aplikacja może użyć do włączenia tej funkcji podczas tworzenia XrSpatialContextEXT .

  • Rozszerzenie definiujące nowy element XrSpatialCapabilityEXT powinno być zgodne z tym szablonem specyfikacji:

    • Przegląd
    • Obsługa środowiska wykonawczego
    • Konfiguracja
    • Komponenty gwarantowane
    • Przykładowy kod

  • Rozszerzenie definiujące nowy element XrSpatialComponentTypeEXT powinno być zgodne z tym szablonem specyfikacji:

    • Dane komponentu
    • Struktura listy komponentów do wysyłania zapytań o dane
    • Konfiguracja

  • Podczas pisania interfejsu API, który udostępnia aplikacji XrSpatialBufferIdEXT, musi mu towarzyszyć XrSpatialBufferTypeEXT, aby poinformować aplikację, jaki jest typ danych bufora, a aplikacja może użyć odpowiedniej funkcji xrGetSpatialBuffer*, aby pobrać rzeczywistą zawartość bufora.

Wytyczne dotyczące projektowania i rozszerzania etykiet semantycznych

Chociaż to rozszerzenie nie definiuje żadnego komponentu do przekazywania informacji o etykiecie semantycznej elementu, określa ono reguły i wytyczne dotyczące projektowania dla wszystkich rozszerzeń, które definiują taki komponent. W poniższym tekście słowa „powinien” i „musi” ograniczają autorów takich funkcji, a nie implementację środowiska wykonawczego lub aplikację korzystającą z interfejsu API.

  • Jeśli rozszerzenie definiuje etykiety semantyczne dla dowolnego elementu XrSpatialCapabilityEXT, powinno to zrobić, definiując nowy element XrSpatialComponentTypeEXT oraz nowe wyliczenie ze zbiorem etykiet („zbiór etykiet semantycznych”), które będą danymi dla tego komponentu.
  • Wyliczenie reprezentujące zbiór etykiet semantycznych musi mieć wartość wskazującą, że encja nie jest sklasyfikowana w żadnej z etykiet tego zbioru. Nazwa tego elementu wyliczeniowego musi zawierać ciąg „UNCATEGORIZED”, np. XR_SPATIAL_PLANE_SEMANTIC_LABEL_UNCATEGORIZED_EXT. Ta wartość wskazuje aplikacjom, że środowisko wykonawcze rozpoznaje ten element, ale istnieją inne zestawy etykiet semantycznych, w których ten element jest skategoryzowany.
  • Wyliczenie nowo zdefiniowanego typu XrSpatialComponentTypeEXT w xrEnumerateSpatialCapabilityComponentTypesEXT oznacza, że środowisko wykonawcze obsługuje zestaw etykiet semantycznych (a tym samym etykiety zdefiniowane w zestawie) odpowiadający temu typowi komponentu.
  • Aplikacje wyrażają chęć wykrywania elementów, które mają etykiety należące do tego zbioru etykiet semantycznych, przez uwzględnienie odpowiedniego elementu XrSpatialComponentTypeEXT w tablicy XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents struktury konfiguracji funkcji, dla której typ komponentu jest wyliczany.
  • Możliwe, że pojedynczy element przestrzenny ma wiele komponentów, z których każdy ma etykietę z własnego zestawu etykiet semantycznych. Rozważmy ten przykład z hipotetycznymi zestawami etykiet semantycznych – XrSpatialObjectSemanticLabel, które mogą mieć wartości takie jak krzesło, sofa, stół itp. XrSpatialSofaBrand, który może mieć wartości takie jak IKEA, Wayfair itp., oraz XrSpatialIkeaSofa, który może zawierać nazwy konkretnych modeli sof IKEA. W tym scenariuszu ta sama encja „sofa” ma wszystkie 3 komponenty (etykiety ze wszystkich 3 zestawów etykiet semantycznych), z których każdy dostarcza informacji o encji o różnym stopniu szczegółowości.
  • Jeśli rozszerzenie definiuje nowy element XrSpatialComponentTypeEXT, który udostępnia nowy zestaw etykiet semantycznych zawierający wiele etykiet oprócz etykiety UNCATEGORIZED, rozszerzenie powinno rozważyć zdefiniowanie elementu XrSpatialCapabilityFeatureEXT, który umożliwia aplikacjom aktywowanie tylko podzbioru etykiet zdefiniowanych w zestawie etykiet semantycznych odpowiadających temu typowi komponentu. Ten podzbiór, podany w następnym łańcuchu konfiguracji funkcji, działa jako wskazówka dla środowisk wykonawczych, aby zoptymalizować potoki śledzenia i śledzić tylko podany podzbiór. Przykład takiej struktury funkcji znajdziesz poniżej .
  • Rozszerzenia nie mogą dodawać etykiet do istniejącego zbioru etykiet semantycznych. Muszą zamiast tego zdefiniować nowy typ wyliczeniowy, który zawiera równoważne elementy wyliczeniowe o identycznej semantyce i wartościach równych wartościom z drugiego zbioru, a także nowo dodane elementy wyliczeniowe. Specyfikacja nowo zdefiniowanego zestawu etykiet semantycznych musi też określać mapowanie między starym a nowym zestawem etykiet. Zobacz przykład poniżej .
Przykładowa definicja cechy przestrzennej dla podzbioru etykiet semantycznych
// New example semantic label set.
typedef enum XrSpatialExampleSemanticLabelEXT {
  // ... label values
} XrSpatialExampleSemanticLabelEXT;

/*
typedef enum XrSpatialCapabilityFeatureEXT {
  // .. existing values

  // new spatial feature value
  XR_SPATIAL_CAPABILITY_FEATURE_EXAMPLE_SEMANTIC_LABEL_SUBSET_EXT

  // .. existing values
} XrSpatialCapabilityFeatureEXT;
*/

// New spatial feaure configuration structure
typedef struct XrSpatialFeatureExampleSemanticLabelSubsetEXT {
    XrStructureType                             type;
    const void* XR_MAY_ALIAS                    next;
    uint32_t                                    semanticLabelCount;
    const XrSpatialExampleSemanticLabelEXT*     semanticLabels;
} XrSpatialFeatureExampleSemanticLabelSubsetEXT;
Przykładowe rozszerzenie etykiety semantycznej przestrzeni
typedef enum XrSpatialExamplePlaneSemanticLabelExtensionEXT {
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_UNCATEGORIZED_EXT = 1,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_FLOOR_EXT = 2,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_WALL_EXT = 3,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_CEILING_EXT = 4,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_TABLE_EXT = 5,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_DOOR_EXT = 6,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_WINDOW_EXT = 7,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialExamplePlaneSemanticLabelExtensionEXT;

Weźmy pod uwagę powyższy przykład, w którym rozszerzenie definiuje wyliczenie XrSpatialExamplePlaneSemanticLabelExtensionEXT, aby rozszerzyć istniejący element XrSpatialPlaneSemanticLabelEXT o wartości reprezentujące drzwi i okna. Specyfikacja nowego wyliczenia musi zawierać tekst w następującej postaci:

For all non-UNCATEGORIZED label enumerants in elink:XrSpatialPlaneSemanticLabelEXT,
the runtime must: return that enumerant if and only if it returns the corresponding
label enumerant from elink:XrSpatialExamplePlaneSemanticLabelExtensionEXT with the same value
i.e.
the ename:XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT value for that entity must:
correspond with the ename:XR_SPATIAL_COMPONENT_TYPE_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_EXT values
according to the following table -

[width="100%",options="header"]
|====
| XrSpatialExamplePlaneSemanticLabelExtensionEXT                | XrSpatialPlaneSemanticLabelEXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_FLOOR_EXT   | XR_SPATIAL_PLANE_SEMANTIC_LABEL_FLOOR_EXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_WALL_EXT    | XR_SPATIAL_PLANE_SEMANTIC_LABEL_WALL_EXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_CEILING_EXT | XR_SPATIAL_PLANE_SEMANTIC_LABEL_CEILING_EXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_TABLE_EXT   | XR_SPATIAL_PLANE_SEMANTIC_LABEL_TABLE_EXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_DOOR_EXT    | XR_SPATIAL_PLANE_SEMANTIC_LABEL_UNCATEGORIZED_EXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_WINDOW_EXT  | XR_SPATIAL_PLANE_SEMANTIC_LABEL_UNCATEGORIZED_EXT
|====

Nowe makra

Nowe typy gwintów

  • XrSpatialBufferIdEXT
  • XrSpatialEntityIdEXT

Nowe typy obiektów

Nowe polecenia

Nowe domy

Nowe wartości w polu enum

Nowe stałe typu wyliczeniowego

  • XR_EXT_SPATIAL_ENTITY_EXTENSION_NAME
  • XR_EXT_spatial_entity_SPEC_VERSION

  • Rozszerzanie XrObjectType :

    • XR_OBJECT_TYPE_SPATIAL_CONTEXT_EXT
    • XR_OBJECT_TYPE_SPATIAL_ENTITY_EXT
    • XR_OBJECT_TYPE_SPATIAL_SNAPSHOT_EXT

  • Rozszerzenie XrResult :

    • XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
    • XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT
    • XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT
    • XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT
    • XR_ERROR_SPATIAL_COMPONENT_UNSUPPORTED_FOR_CAPABILITY_EXT
    • XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT

  • Rozszerzanie XrStructureType :

    • XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT
    • XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT
    • XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT
    • XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT
    • XR_TYPE_SPATIAL_BUFFER_GET_INFO_EXT
    • XR_TYPE_SPATIAL_CAPABILITY_COMPONENT_TYPES_EXT
    • XR_TYPE_SPATIAL_COMPONENT_BOUNDED_2D_LIST_EXT
    • XR_TYPE_SPATIAL_COMPONENT_BOUNDED_3D_LIST_EXT
    • XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT
    • XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT
    • XR_TYPE_SPATIAL_COMPONENT_MESH_3D_LIST_EXT
    • XR_TYPE_SPATIAL_COMPONENT_PARENT_LIST_EXT
    • XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT
    • XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT
    • XR_TYPE_SPATIAL_ENTITY_FROM_ID_CREATE_INFO_EXT
    • XR_TYPE_SPATIAL_FILTER_TRACKING_STATE_EXT
    • XR_TYPE_SPATIAL_UPDATE_SNAPSHOT_CREATE_INFO_EXT

Problemy

  • Does a single entity always derive from solely a single capability?

    • Rozwiązane
    • Odpowiedź: Nie. Zależy to całkowicie od środowiska wykonawczego, jego możliwości śledzenia i sposobu, w jaki chce reprezentować wykryty element. Specyfikacja nie określa żadnej konkretnej reprezentacji elementu przestrzennego, z wyjątkiem gwarantowanych komponentów danej funkcji, które mają spełniać minimalne oczekiwania. Środowisko wykonawcze może scalać elementy wykryte przez osobne funkcje i reprezentować je jako pojedynczy element z gwarantowanymi komponentami wszystkich funkcji, które pomogły go zidentyfikować. Przykładem może być sytuacja, w której stoły mogą być wykrywane zarówno przez funkcję śledzenia płaszczyzny, jak i funkcję śledzenia obiektów, przy czym śledzenie płaszczyzny zapewnia komponent XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT w encji, a śledzenie obiektów zapewnia XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT . Niektóre środowiska wykonawcze mogą udostępniać tabelę jako 2 osobne elementy, z których każdy ma własny zestaw gwarantowanych komponentów, podczas gdy inne środowiska wykonawcze mogą udostępniać tylko 1 element reprezentujący tabelę i zawierający zarówno XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT, jak i XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT. Ważne jest, aby pamiętać, że dany element przestrzenny może mieć co najwyżej 1 komponent danego typu . Dlatego jeśli dane komponentu wygenerowane przez różne funkcje są sprzeczne w przypadku określonego elementu, środowisko wykonawcze musi przedstawić je jako 2 osobne elementy.

Historia zmian

  • Wersja 1, 12 kwietnia 2024 r. (Nihav Jain, Google)

    • Początkowy opis rozszerzenia