XR_EXT_spatial_entity

Ciąg znaków nazwy

XR_EXT_spatial_entity

Typ rozszerzenia

Rozszerzenie instancji

Zarejestrowany numer wewnętrzny

741

Wersja

1

Stan ratyfikacji

Ratyfikacja

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 dotyczące rozumienia sceny i rozumowania przestrzennego w OpenXR. Ujednolica to kilka powiązanych, ale odrębnych obszarów funkcjonalności, które są wyliczane, konfigurowane i z którymi można wchodzić w interakcje w sposób w dużej mierze jednolity, zgodnie z definicją tego rozszerzenia. Ponieważ to rozszerzenie nie zawiera konkretnych definicji żadnego z tych obszarów funkcjonalnych, tekst formalnej specyfikacji jest zwykle dość abstrakcyjny. Przykłady zawarte w tekście specyfikacji tego rozszerzenia czasami odnoszą się do funkcji zdefiniowanych w nadchodzącym lub hipotetycznym powiązanym rozszerzeniu w celu ilustracyjnym, bez ograniczania lub określania takich dodatkowych funkcji.

Główne elementy tego rozszerzenia to:

  • Obiekty przestrzenne : funkcjonalność opiera się na obiektach , które same w sobie mają bardzo małą funkcjonalność.
  • Komponenty przestrzenne : te jednostki mają powiązane z nimi 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 komponentu .
  • Kontekst przestrzenny : wszystkie interakcje z obiektami przestrzennymi odbywają się w kontekście po fazie inicjowania i konfiguracji.
  • Funkcje przestrzenne : manipulowanie obiektami przestrzennymi jest w dużej mierze zapewniane przez funkcje . Funkcja to jednostka funkcjonalności, np. (bez ograniczeń) zdefiniowane przez aplikację punkty zakotwiczenia, wykrywanie płaszczyzn lub śledzenie obrazów. Każda funkcja jest zwykle zdefiniowana w osobnym rozszerzeniu (włączanym jak zwykle podczas tworzenia instancji) i jest 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 występują w każdym elemencie udostępnianym przez tę funkcję . Rozszerzenie definiujące możliwość określa, które typy komponentów są obowiązkowe w przypadku tej możliwości („gwarantowane”), a to samo rozszerzenie lub inne rozszerzenia mogą określać opcjonalne typy komponentów udostępniane przez niektóre potencjalne implementacje. Dowolna liczba możliwości może dostarczać encjom komponenty danego typu komponentu, które są jednolicie użyteczne niezależnie od możliwości, która je wygenerowała.
  • Funkcje związane z przestrzennością : niektóre funkcje wymagają konfiguracji, dlatego są parametryzowane przez funkcje związane z przestrzennością .

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

Ponieważ niektóre implementacje mogą wymagać różnego stopnia parametryzacji możliwości , to rozszerzenie zapewnia mechanizm wyliczania obsługiwanych funkcji związanych z daną możliwością w bieżącym systemie.

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

Obiekt przestrzenny

Obiekty przestrzenne to obiekty, które istnieją w jakiejś przestrzeni i mają różne powiązane dane uporządkowane w komponenty. Mogą to być:

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

Elementy udostępniane przez system działań, takie jak kontrolery czy śledzenie wzroku, nie są przeznaczone do modelowania jako obiekty przestrzenne.

Obiekty przestrzenne w OpenXR są modelowane jako system komponentów encji . Każdy obiekt przestrzenny ma zestaw komponentów, a każdy komponent zapewnia unikalny zestaw danych i zachowań dla tego obiektu.

Obiekty przestrzenne są reprezentowane przez XrSpatialEntityIdEXT atom lub uchwyt XrSpatialEntityEXT, którego szczegóły znajdziesz w sekcji Reprezentacje obiektów przestrzennych.

Typy komponentów przestrzennych

Obiekt przestrzenny ma co najmniej 1 komponent, który dostarcza dane lub zachowania tego obiektu. Więcej informacji o niektórych typowych komponentach zdefiniowanych przez to rozszerzenie znajdziesz w artykule 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_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialComponentTypeEXT;

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

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

Wartości wyliczeniowe to:

Opis typu wyliczeniowego

XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

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

XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT

Komponent, który udostępnia granice 3D dla obiektu przestrzennego. Odpowiednia struktura listy to XrSpatialComponentBounded3DListEXT, a odpowiednia struktura danych to XrBoxf.

XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT

Komponent, który udostępnia XrSpatialEntityIdEXT elementu nadrzędnego dla obiektu przestrzennego. Odpowiednia struktura listy to XrSpatialComponentParentListEXT, a odpowiednia struktura danych to XrSpatialEntityIdEXT.

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT

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

XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT

Komponent, który udostępnia wyliczenie wyrównania płaszczyzny dla obiektu przestrzennego. 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 obiektu przestrzennego. 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 graniczny 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 zapewnia etykietę semantyczną dla płaszczyzny. Odpowiednia struktura listy to XrSpatialComponentPlaneSemanticLabelListEXT; 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; odpowiednia struktura danych to XrSpatialMarkerDataEXT (dodana 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 zapewnia etykietę semantyczną dla 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 zapewnia etykietę semantyczną dla 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 określa lokalizację kotwicy. Odpowiednia struktura listy to XrSpatialComponentAnchorListEXT, a 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 dla obiektu przestrzennego. Odpowiednia struktura listy to XrSpatialComponentPersistenceListEXT, a odpowiednia struktura danych to XrSpatialPersistenceDataEXT (dodana przez rozszerzenie XR_EXT_spatial_persistence).

XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT

Komponent opisujący typ obrazu płaskiego. 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 udostępnia wektory normalne siatki 3D obiektu przestrzennego. Odpowiednia struktura listy to XrSpatialComponentMesh3DNormalsListEXT; 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 udostępnia etykiety semantyczne dla każdego wierzchołka siatki 3D obiektu 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 zawiera etykiety semantyczne dla każdej trójkątnej powierzchni siatki 3D obiektu 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 zapewnia etykietę semantyczną dla 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 określa pozycję trafienia raycastem w element. Odpowiednia struktura listy to XrSpatialComponentRaycastResultListANDROID, a struktura danych to XrSpatialRaycastResultDataANDROID (dodana przez rozszerzenie XR_ANDROID_spatial_discovery_raycast).

XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID

Komponent, który podaje identyfikator elementu nadrzędnego dołączonego elementu. Odpowiednia struktura listy to XrSpatialComponentSubsumedByListANDROID, a odpowiednia struktura danych to XrSpatialEntityIdEXT (dodana przez rozszerzenie XR_ANDROID_spatial_component_subsumed_by).

XR_SPATIAL_COMPONENT_TYPE_ROOM_ANDROIDSYS

Komponent, który zawiera wymiary i typ pomieszczenia w budynku. Odpowiednia struktura listy to XrSpatialComponentRoomListANDROIDSYS, a odpowiednia struktura danych to XrSpatialRoomDataANDROIDSYS (dodana przez rozszerzenie XR_ANDROIDSYS_spatial_room_tracking).

XR_SPATIAL_COMPONENT_TYPE_MATERIAL_TYPE_ANDROIDSYS

Komponent, który określa typ materiału powierzchni granicznej. Odpowiednia struktura listy to XrSpatialComponentMaterialTypeListANDROIDSYS, a odpowiednia struktura danych to XrSpatialMaterialTypeANDROIDSYS (dodana przez rozszerzenie XR_ANDROIDSYS_spatial_room_tracking).

XR_SPATIAL_COMPONENT_TYPE_CONFIDENCE_ANDROIDSYS

Komponent, który określa poziom ufności śledzonego obiektu. 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, a 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 podmiotu. Odpowiednia struktura listy to XrSpatialComponentOccupancyGridListANDROIDX1, a odpowiednia struktura danych to XrSpatialOccupancyGridDataANDROIDX1 (dodana przez rozszerzenie XR_ANDROIDX1_spatial_occupancy_grid).

XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID

Komponent opisujący adnotację w postaci czworokąta. Odpowiednia struktura listy to XrSpatialComponentAnnotationQuadListANDROID, a struktura danych to XrSpatialAnnotationQuadDataANDROID (dodana przez rozszerzenie XR_ANDROID_spatial_annotation_tracking).

XR_SPATIAL_COMPONENT_TYPE_STREETSCAPE_GEOMETRY_METADATA_ANDROIDX2

Komponent, który zawiera metadane geometrii krajobrazu miejskiego; odpowiednia struktura listy to XrSpatialComponentStreetscapeGeometryMetadataListANDROIDX2; odpowiednia struktura danych to XrSpatialStreetscapeGeometryMetadataANDROIDX2 (dodana przez rozszerzenie XR_ANDROIDX2_geospatial_streetscape).

Możliwości przestrzenne i konfiguracja

Funkcje przestrzenne określają możliwości środowiska wykonawczego w zakresie wykrywania obiektów, które mają gwarantowany zestaw komponentów. Aplikacje włączają komponenty funkcji przestrzennych podczas tworzenia interfejsu XrSpatialContextEXT, a środowisko wykonawcze musi z kolei udostępniać tylko włączone komponenty w wykrytych obiektach. Jeśli np. środowisko wykonawcze zgłosi, ż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ć.

Wartości wyliczeniowe to:

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 mikrokodów 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 tagów AprilTag. (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

Raycast against depth buffer (Added by the XR_ANDROID_spatial_discovery_raycast extension)

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ą wymienione.
  • capabilityCapacityInput to pojemność tablicy capabilities lub 0, aby wskazać żądanie pobrania wymaganej pojemności.
  • capabilityCountOutput to liczba funkcji lub wymagana pojemność w przypadku, gdy capabilityCapacityInput jest niewystarczająca.
  • capabilities to tablica elementów XrSpatialCapabilityEXT . Może to być NULL, jeśli capabilityCapacityInput wynosi 0.
  • Szczegółowy opis pobierania wymaganego rozmiaru capabilities znajdziesz w sekcji Parametry rozmiaru bufora.

Aplikacja może wyliczyć listę funkcji przestrzennych obsługiwanych przez dany XrSystemId, korzystając z funkcji xrEnumerateSpatialCapabilitiesEXT .

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

Prawidłowe użycie (domyślne)

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

Kody zwrotne

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 zostaną wyliczone komponenty.
  • capabilityComponents to wskaźnik do XrSpatialCapabilityComponentTypesEXT, czyli struktury wejścia/wyjścia, w której wypełniana jest tablica przydzielona przez aplikację.

Ta funkcja wylicza typy komponentów, które dana funkcja udostępnia w swoich jednostkach 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żywać tej listy do określania, jaka jest prawidłowa konfiguracja capability podczas tworzenia dla niego XrSpatialContextEXT.

Środowisko wykonawcze musi zwrócić wartość XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT, jeśli wartość capability nie jest wyliczana przez funkcję 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 (domyślne)

Kody zwrotne

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 podstawowej specyfikacji OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.
  • componentTypeCapacityInput to pojemność tablicy lub 0, aby wskazać żądanie pobrania wymaganej pojemności.
  • componentTypeCountOutput to liczba typów komponentów lub wymagana pojemność w przypadku, gdy componentTypeCapacityInput jest niewystarczająca.
  • componentTypes to tablica elementów XrSpatialComponentTypeEXT . Może to być NULL, jeśli componentTypeCapacityInput wynosi 0.
  • Szczegółowy opis pobierania wymaganego rozmiaru componentTypes znajdziesz w sekcji Parametry rozmiaru bufora.

Prawidłowe użycie (domyślne)

Funkcje związane z możliwościami przestrzennymi

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, aby skonfigurować sposób obliczania danych komponentu przez środowisko wykonawcze. Te wymiary parametryzacji i konfigurowalności są nazywane funkcjami. Na przykład w przypadku funkcji śledzenia obrazów środowisko wykonawcze może obsługiwać funkcję, która pozwala aplikacji określić, czy śledzone obrazy są nieruchome.

Przekazywanie tych informacji do środowiska wykonawczego za pomocą struktury konfiguracji nie może zmieniać zestawu typów komponentów obecnych w powiązanych elementach, np. na śledzonym obrazie. Środowisko wykonawcze może jednak optymalizować np. możliwości śledzenia obrazu i zapewniać lepsze wrażenia w aplikacji.

Takie funkcje są reprezentowane przez XrSpatialCapabilityFeatureEXT, a aplikacja wylicza je za pomocą funkcji 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.

Wartości wyliczeniowe to:

Opis typu wyliczeniowego

XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_FIXED_SIZE_MARKERS_EXT

Funkcja umożliwiająca aplikacjom określanie rozmiaru markeró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 markery 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 umożliwiająca aplikacjom określenie podzbioru etykiet z XrSpatialObjectSemanticLabelEXT, które środowisko wykonawcze ma śledzić. 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 w przypadku 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_FRUSTUM_BOUNDS_FILTER_ANDROID

Środowisko wykonawcze obsługuje filtr XrSpatialBoundsFrustumfANDROID 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_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ą wymienione.
  • capability to XrSpatialCapabilityEXT, dla którego zostaną wyliczone funkcje.
  • capabilityFeatureCapacityInput to pojemność tablicy lub 0, aby wskazać żądanie pobrania wymaganej pojemności.
  • capabilityFeatureCountOutput to liczba funkcji lub wymagana pojemność w przypadku, gdy capabilityFeatureCapacityInput jest niewystarczająca.
  • capabilityFeatures to tablica elementów XrSpatialCapabilityFeatureEXT . Może to być 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ą funkcji xrEnumerateSpatialCapabilityFeaturesEXT .

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

Jeśli capability nie jest możliwością wyliczoną przez xrEnumerateSpatialCapabilitiesEXT , środowisko wykonawcze musi zwrócić XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT .

Środowisko wykonawcze nie może wyliczać funkcji związanych z możliwościami przestrzennymi, których rozszerzenie nie jest włączone w przypadku instance .

Prawidłowe użycie (domyślne)

  •  Rozszerzenie XR_EXT_spatial_entity musi być włączone przed wywołaniem funkcji xrEnumerateSpatialCapabilityFeaturesEXT.
  • instance musi być prawidłowym uchwytem XrInstance
  • capability musi być prawidłową wartością XrSpatialCapabilityEXT.
  • capabilityFeatureCountOutput musi być wskaźnikiem wartości uint32_t.
  •  Jeśli wartość capabilityFeatureCapacityInput nie jest równa 0 , capabilityFeatures musi być wskaźnikiem do tablicy capabilityFeatureCapacityInput wartości XrSpatialCapabilityFeatureEXT.

Kody zwrotne

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 pewnej liczby obiektów przestrzennych w środowisku użytkownika. Aplikacja może używać tego uchwytu do wykrywania i aktualizowania obiektó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 struktura XrSpatialContextCreateInfoEXT używana do określania parametrów kontekstu przestrzennego.
  • future to wskaźnik do XrFutureEXT .

Aplikacja może utworzyć uchwyt XrSpatialContextEXT, wykonując te czynności:

Środowisko wykonawcze musi zwracać wartość XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT, jeśli XrSpatialContextCreateInfoEXT ::capabilityConfigCount ma wartość 0. Uchwyt kontekstu przestrzennego musi mieć co najmniej 1 możliwość.

Środowisko wykonawcze musi zwrócić XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT, jeśli żadna funkcja w tablicy XrSpatialContextCreateInfoEXT :: capabilityConfigs nie jest wyliczana przez xrEnumerateSpatialCapabilitiesEXT .

Środowisko wykonawcze musi zwracać wartość XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT, jeśli którykolwiek element XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponentCount w strukturze 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 zwrócić XR_ERROR_SPATIAL_COMPONENT_UNSUPPORTED_FOR_CAPABILITY_EXT, jeśli jakikolwiek typ komponentu wymieniony w XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents nie jest wyliczony dla XrSpatialCapabilityConfigurationBaseHeaderEXT :: capability w xrEnumerateSpatialCapabilityComponentTypesEXT .

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

Środowisko wykonawcze musi zwrócić 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 obsługujące śledzenie płaszczyzny może rozpocząć proces ś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ą skutkować pustym zrzutem. Aplikacja może poczekać na zdarzenie XrEventDataSpatialDiscoveryRecommendedEXT, zanim użyje funkcji xrCreateSpatialDiscoverySnapshotAsyncEXT, aby mieć pewność, że podstawowe 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 interfejsu XrSpatialContextEXT, musi zwrócić wartość 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óry można wykorzystać z funkcją xrPollFutureEXT i funkcjami powiązanymi. Wartość zwracana przez tę funkcję wskazuje tylko, czy parametry były akceptowalne do zaplanowania operacji asynchronicznej. Odpowiednią funkcją zakończenia jest 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 zakończenia XrCreateSpatialContextCompletionEXT .

Prawidłowe użycie (domyślne)

Kody zwrotne

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

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 podstawowej specyfikacji 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 zawiera informacje potrzebne do utworzenia uchwytu XrSpatialContextEXT.

Prawidłowe użycie (domyślne)

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 parametrem 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 tablicy elementów XrSpatialComponentTypeEXT .

Środowisko wykonawcze musi zwrócić wartość XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT, jeśli wartość capability nie jest wyliczana przez funkcję xrEnumerateSpatialCapabilitiesEXT . Środowisko wykonawcze musi zwrócić wartość XR_ERROR_SPATIAL_COMPONENT_UNSUPPORTED_FOR_CAPABILITY_EXT, jeśli jakikolwiek typ komponentu wymieniony w enabledComponents nie jest wyliczony dla capability w funkcji xrEnumerateSpatialCapabilityComponentTypesEXT .

Prawidłowe użycie (domyślne)

Funkcja xrCreateSpatialContextCompleteEXT jest zdefiniowana w ten sposób:

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

Opisy parametrów

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

Prawidłowe użycie (domyślne)

Kody zwrotne

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 pola 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 okresie istnienia 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 (domyślne)

Zniszczenie kontekstu przestrzennego

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 z nim zasoby po zakończeniu zadań związanych z wykrywaniem i aktualizowaniem jednostek przestrzennych. Jeśli nie ma innego prawidłowego elementu XrSpatialContextEXT utworzonego z tymi samymi możliwościami przestrzennymi co spatialContext, to wywołanie służy jako sugestia dla środowiska wykonawczego, aby wyłączyć usługi śledzenia wymagane do obsługi tych możliwości w celu zaoszczędzenia zasobów systemowych.

Prawidłowe użycie (domyślne)

Bezpieczeństwo wątków

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

Kody zwrotne

Sukces

  • XR_SUCCESS

Błąd

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Reprezentacje encji przestrzennych

Identyfikator jednostki przestrzennej

XR_DEFINE_ATOM(XrSpatialEntityIdEXT)

XrSpatialEntityIdEXT reprezentuje dowolny rodzaj obiektu wykrytego przez środowisko wykonawcze w przestrzeni użytkownika. Wartość XrSpatialEntityIdEXT jest ważna w przypadku elementu XrSpatialContextEXT, w którym została wykryta, a środowisko wykonawcze nie może ponownie używać tej samej wartości XrSpatialEntityIdEXT w przypadku różnych elementów w tym samym elemencie XrSpatialContextEXT . Ponadto środowisko wykonawcze nie może ponownie używać tego samego XrSpatialEntityIdEXT w wielu obiektach XrSpatialContextEXT w ramach tej samej sesji XrSession, niezależnie od tego, czy reprezentuje on ten sam czy różne podmioty.

#define XR_NULL_SPATIAL_ENTITY_ID_EXT 0

XR_NULL_SPATIAL_ENTITY_ID_EXT to wartość zarezerwowana reprezentująca nieprawidłowy identyfikator XrSpatialEntityIdEXT . Można go przekazywać do funkcji interfejsu API i z nich zwracać tylko wtedy, gdy jest to wyraźnie dozwolone.

Uchwyt obiektu przestrzennego

XR_DEFINE_HANDLE(XrSpatialEntityEXT)

Uchwyt XrSpatialEntityEXT reprezentuje jednostkę przestrzenną. Aplikacja może utworzyć taki uchwyt, aby poinformować środowisko wykonawcze o swoim zainteresowaniu konkretnym elementem.

Tworzenie uchwytu encji przestrzennej 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 tworzenia uchwytu XrSpatialEntityEXT, który jest odwołaniem do obiektu istniejącego w środowisku użytkownika.

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

Prawidłowe użycie (domyślne)

Kody zwrotne

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 podstawowej specyfikacji OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.
  • entityId to XrSpatialEntityIdEXT jednostki, dla której aplikacja chce utworzyć uchwyt.

Prawidłowe użycie (domyślne)

Destroy Spatial Entity Handle

Funkcja xrDestroySpatialEntityEXT jest zdefiniowana w ten sposób:

XrResult xrDestroySpatialEntityEXT(
    XrSpatialEntityEXT                          spatialEntity);

Opisy parametrów

Aplikacja może użyć funkcji xrDestroySpatialEntityEXT, aby zwolnić uchwyt spatialEntity, gdy nie będzie już zainteresowana obiektem, do którego odnosi się ten uchwyt.

Prawidłowe użycie (domyślne)

Bezpieczeństwo wątków

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

Kody zwrotne

Sukces

  • XR_SUCCESS

Błąd

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Zrzut przestrzenny

XR_DEFINE_HANDLE(XrSpatialSnapshotEXT)

Aplikacja może tworzyć migawki przestrzenne w celu wykrywania obiektów przestrzennych lub aktualizowania informacji o znanych obiektach przestrzennych. Uchwyt XrSpatialSnapshotEXT reprezentuje niezmienne dane wykrytych lub zaktualizowanych obiektó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 dane zrzutu muszą pozostać stałe, dopóki zrzut jest ważny.

Aplikacja może tworzyć dowolną liczbę zrzutów, ale musi pamiętać o pamięci przydzielanej do każdego nowego zrzutu i musi usuwać zrzuty, gdy nie są już potrzebne.

Tworzenie zrzutu 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ć obiekty przestrzenne, tworząc migawkę wykrywania za pomocą funkcji xrCreateSpatialDiscoverySnapshotAsyncEXT .

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

Aplikacja może przesyłać wiele żądań utworzenia migawki wykrywania bez konieczności czekania na zakończenie poprzedniego żądania. Ś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 ona zmniejszyć wykorzystanie zasobów systemowych ze względu na zasilanie, temperaturę lub inne zasady urządzenia.

Aplikacja może używać XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes do filtrowania listy podmiotów i komponentów, których dane środowisko wykonawcze musi uwzględnić w migawce. Jeśli aplikacja podaje prawidłową listę typów komponentów przestrzennych w strukturze XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes , środowisko wykonawcze musi uwzględniać w migawce tylko te jednostki przestrzenne, które mają co najmniej 1 komponent podany w strukturze XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes . Poza tym środowisko wykonawcze musi zawierać tylko dane tych komponentów w zrzucie.

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

Jeśli aplikacja nie podaje listy typów komponentów przestrzennych w XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes , środowisko wykonawcze musi uwzględnić w migawce wszystkie obiekty przestrzenne, które mają zestaw komponentów wymienionych w XrSpatialCapabilityConfigurationBaseHeaderEXT ::enabledComponents dla funkcji skonfigurowanych dla spatialContext . Czas działania musi obejmować dane wszystkich włączonych komponentów funkcji skonfigurowanych dla spatialContext .

Jeśli zdarzenie XrEventDataReferenceSpaceChangePending zostanie umieszczone w kolejce przed zakończeniem działania funkcji future, a wartość XrEventDataReferenceSpaceChangePending :: poseValid będzie fałszywa, środowisko wykonawcze może utworzyć obiekt XrSpatialSnapshotEXT, który nie zawiera żadnych elementów, lub ustawić wartość XrSpatialEntityTrackingStateEXT elementów, których nie można już zlokalizować w obiekcie XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace w obiekcie 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 (domyślne)

Kody zwrotne

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 podstawowej specyfikacji OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.
  • componentTypeCount to uint32_t opisujący liczbę elementów w tablicy componentTypes.
  • componentTypes to tablica elementów XrSpatialComponentTypeEXT .

Struktura XrSpatialDiscoverySnapshotCreateInfoEXT opisuje informacje potrzebne do utworzenia uchwytu XrSpatialSnapshotEXT podczas wykrywania jednostek przestrzennych.

Prawidłowe użycie (domyślne)

Funkcja xrCreateSpatialDiscoverySnapshotCompleteEXT jest zdefiniowana w ten sposób:

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

Opisy parametrów

Funkcja xrCreateSpatialDiscoverySnapshotCompleteEXT kończy operację asynchroniczną rozpoczętą przez funkcję xrCreateSpatialDiscoverySnapshotAsyncEXT . Środowisko wykonawcze musi zwrócić 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 (domyślne)

Kody zwrotne

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 , znajdującym się w time .

Prawidłowe użycie (domyślne)

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órego można używać do wysyłania zapytań o dane komponentów wykrytych encji przestrzennych.

Kody zwrotu w przyszłości

Wartości pola 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 (domyślne)

Zdarzenie rekomendacji w sekcji Odkrywaj

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 odkrywanie.

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

Oczekiwanie na to zdarzenie w celu utworzenia nowego zrzutu wykrywania zapewnia, że aplikacja nie przeciąża systemu żądaniami wykrywania, dla których środowisko wykonawcze może nie zwracać żadnych nowych danych. Pomaga to uniknąć ryzyka nadmiernego wykorzystania zasobów systemowych i ograniczenia przepustowości z powodu zasad zasilania lub termicznych urządzenia. Pomaga to również w zapewnieniu równości między środowiskami wykonawczymi, które wykrywają jednostki przestrzenne na bieżąco za pomocą śledzenia na żywo, a środowiskami wykonawczymi, które udostępniają jednostki przestrzenne na podstawie wcześniej zarejestrowanego stanu (w którym środowisko wykonawcze może umieszczać w kolejce zdarzenie rekomendacji wykrywania tylko raz dla każdego XrSpatialContextEXT).

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

Środowisko wykonawcze może umieścić w kolejce zdarzenie rekomendacji wykrywania bez czekania, aż aplikacja najpierw wywoła funkcję xrCreateSpatialDiscoverySnapshotAsyncEXT . Na przykład środowisko wykonawcze może podejmować decyzję o umieszczeniu w kolejce zdarzenia rekomendacji dotyczącej wykrywania na podstawie konfiguracji XrSpatialContextEXT, własnej wiedzy o otoczeniu użytkownika (wykrywanie nowych obiektów lub utrata istniejących) lub w celu podpowiedzi aplikacji odpowiedniej częstotliwości żądań wykrywania, aby nie przeciążać zasobów systemu. Środowisko wykonawcze może nigdy nie umieścić tego zdarzenia w kolejce dla XrSpatialContextEXT, jeśli w środowisku użytkownika nie zostaną znalezione żadne obiekty przez cały okres istnienia tego XrSpatialContextEXT .

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

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

Prawidłowe użycie (domyślne)

Wykonywanie zapytań o dane komponentu

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 jednostek w migawce przez dołączenie struktury listy do XrSpatialComponentDataQueryResultEXT :: next odpowiadającej każdemu XrSpatialComponentTypeEXT w XrSpatialComponentDataQueryConditionEXT :: componentTypes .

Jeśli aplikacja dołącza do XrSpatialComponentDataQueryResultEXT :: next strukturę listy, 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 list odpowiadające tylko podzbiorowi komponentów wymienionych w XrSpatialComponentDataQueryConditionEXT :: componentTypes . Aplikacja może całkowicie pominąć struktury list, jeśli chce tylko poznać identyfikatory i stan śledzenia obiektów przestrzennych, które spełniają warunek queryCondition . Środowisko wykonawcze nie może traktować braku struktur list w łańcuchu 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 do odpowiedniego dostosowania pozycji.

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

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 (domyślne)

Kody zwrotne

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, gdzie:

  • Encje 1 i 2 mają komponenty XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT i XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT
  • Encje 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

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

Rysunek 20. Przykładowy zrzut

Wywołanie funkcji xrQuerySpatialComponentDataEXT na powyższym zrzucie z wartością XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT wymienioną w warunku zapytania spowoduje zwrócenie do aplikacji jednostek 1, 2 i 5, a 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 identyfikatora jednostki 1

Dane dotyczące podmiotu...

Dane dla identyfikatora encji 2

Dane dotyczące podmiotu...

Dane dla identyfikatora encji 5

Dane dotyczące podmiotu...

entityIds

entityIds

dalej

dalej

XrSpatialComponent
DataQueryResultEXT

XrSpatialComponent
Dat...

granice,

granice,

XrSpatialComponent
Bounded2DListEXT

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

Ilustracja 21. Przykładowy wynik zapytania

Wywołanie funkcji xrQuerySpatialComponentDataEXT na powyższym zrzucie z komponentami XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT i XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT wymienionymi w warunku zapytania spowoduje, że do aplikacji zostaną zwrócone jednostki 3 i 4, a aplikacja może dołączyć tablice XrBoxf i XrSpatialMeshDataEXT w ramach struktur XrSpatialComponentBounded3DListEXT i XrSpatialComponentMesh3DListEXT do następnego łańcucha XrSpatialComponentDataQueryResultEXT, aby uzyskać dane komponentu.

XrSpatialEntityIdEXT

XrSpatialEntityIdEXT

3

3

4

4

Bounded3D

Bounded3D

Dane dla identyfikatora jednostki 3

Dane dotyczące podmiotu...

Dane dla identyfikatora encji 4

Dane dotyczące podmiotu...

Mesh3D

Mesh3D

Dane dla identyfikatora jednostki 3

Dane dotyczące podmiotu...

Dane dla identyfikatora encji 4

Dane dotyczące podmiotu...

entityIds

entityIds

dalej

dalej

XrSpatialComponent
DataQueryResultEXT

XrSpatialComponent
Da...

granice,

granice,

dalej

dalej

XrSpatialComponent
Bounded3DListEXT

XrSpatialComponent
Bo...

XrSpatialComponent
Mesh3DListEXT

XrSpatialComponent
Me...

siatki,

siatki Tekst nie jest w formacie SVG – nie można go 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 elementów XrSpatialComponentTypeEXT, dla których mają zostać pobrane dane z migawki.

Prawidłowe użycie (domyślne)

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, aby wskazać żądanie pobrania wymaganej pojemności.
  • entityIdCountOutput to liczba XrSpatialEntityIdEXT w entityIds lub wymagana pojemność w przypadku , gdy entityIdCapacityInput jest niewystarczająca.
  • entityIds to tablica elementów XrSpatialEntityIdEXT . Może to być NULL, jeśli entityIdCapacityInput wynosi 0.
  • entityStateCapacityInput to pojemność tablicy entityStates lub 0, aby wskazać żądanie pobrania wymaganej pojemności.
  • entityStateCountOutput to liczba elementów XrSpatialEntityTrackingStateEXT w entityStates lub wymagana pojemność w przypadku , gdy entityStateCapacityInput jest niewystarczająca. Ta wartość musi być zawsze taka sama jak wartość entityIdCountOutput .
  • entityStates to tablica elementów XrSpatialEntityTrackingStateEXT . Może to być 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 funkcją xrCreateSpatialEntityFromIdEXT do tworzenia uchwytów XrSpatialEntityEXT dla jednostek, w przypadku których chce otrzymywać regularne aktualizacje. Aplikacja może następnie używać tych uchwytów XrSpatialEntityEXT z funkcją xrCreateSpatialUpdateSnapshotEXT, aby utworzyć zrzut aktualizacji zawierający najnowsze znane dane komponentów dla podanych elementów.

Prawidłowe użycie (domyślne)

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;

Wyliczenie XrSpatialEntityTrackingStateEXT zawiera możliwe stany śledzenia jednostki przestrzennej:

Wartości wyliczeniowe mają następujące znaczenia:

Opis typu wyliczeniowego

XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT

Środowisko wykonawcze przestało śledzić ten podmiot i nigdy nie wznowi jego śledzenia.

XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT

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

XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT

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

ŚLEDZENIE

WSTRZYMANE

ZATRZYMANO

Ilustracja 23. XrSpatialEntityTrackingStateEXT

  • Środowisko wykonawcze może zmienić stan obiektu przestrzennego z XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT na XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT, jeśli wstrzyma śledzenie tego obiektu, ale będzie miało możliwość wznowienia go w przyszłości. Przykłady sytuacji, w których środowisko wykonawcze może to zrobić, obejmują (ale nie tylko): utratę przez aplikację fokusu wejściowego, zbyt dużą odległość danego obiektu przestrzennego od użytkownika, która uniemożliwia dokładne śledzenie, lub zbyt dużą liczbę śledzonych obiektów, co powoduje, że środowisko wykonawcze chce zmniejszyć koszt śledzenia. XrSpatialEntityTrackingStateEXT pomaga aplikacji odizolować się od różnych zasad śledzenia w poszczególnych środowiskach wykonawczych.
  • Środowisko wykonawcze może zmienić stan elementu 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 obiektu 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 obiekt przestrzenny zostanie utracony i jego śledzenie nigdy 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 w tej sesji śledzenia są traktowane jako nowe elementy.
  • Gdy stan śledzenia elementu zostanie ustawiony na XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT , środowisko wykonawcze nie może nigdy zmienić go na żaden inny stan.
  • Podczas wysyłania zapytania o dane komponentu obiektu przestrzennego za pomocą funkcji 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 obiektu to XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT . Jeśli stan elementu 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 dwukrotnego wywołania w przypadku 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, aby wskazać typ danych w bufferId . Aplikacja może używać bufferType do określania, której funkcji użyć do pobrania rzeczywistych danych z bufora.

Niektóre komponenty przestrzenne mają dane o zmiennej wielkości, dlatego do ich pobrania trzeba użyć idiomu dwukrotnego wywołania. W takich przypadkach struktura danych komponentu przestrzennego udostępnia XrSpatialBufferEXT dla każdego bufora o zmiennej wielkości potrzebnego w danych tego komponentu.

W przypadku tego samego bufferId środowisko wykonawcze musi dostarczać te same dane z jednego zapytania o dane komponentu do drugiego, nawet w przypadku różnych zrzutów. Różne wartości bufferId w wywołaniach zapytań o dane komponentu wskazują aplikacji, że dane tego komponentu mogły ulec zmianie.

Prawidłowe użycie (domyślne)

XR_DEFINE_ATOM(XrSpatialBufferIdEXT)

XrSpatialBufferIdEXT służy do przedstawiania dowolnego rodzaju danych o zmiennej wielkości dla komponentu przestrzennego.

Środowisko wykonawcze musi przechowywać XrSpatialBufferIdEXT i jego dane w pamięci co najmniej przez cały cykl życia obiektu XrSpatialSnapshotEXT, który go zawiera. Środowisko wykonawcze może przechowywać XrSpatialBufferIdEXT i jego dane w pamięci dłużej niż przez cały cykl życia XrSpatialSnapshotEXT, aby zwracać ten sam identyfikator w zrzutach 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 określa różne typy danych bufora reprezentowanego przez XrSpatialBufferIdEXT .

Opisy elementów wyliczenia

  • XR_SPATIAL_BUFFER_TYPE_STRING_EXT. Wartość XrSpatialBufferIdEXT can można przekazać do funkcji xrGetSpatialBufferStringEXT, aby pobrać bufor ciągów tekstowych.
  • XR_SPATIAL_BUFFER_TYPE_UINT8_EXT. Wartość XrSpatialBufferIdEXT can można przekazać do funkcji xrGetSpatialBufferUint8EXT, aby pobrać bufor uint8_t.
  • XR_SPATIAL_BUFFER_TYPE_UINT16_EXT. Wartość XrSpatialBufferIdEXT can można przekazać do funkcji xrGetSpatialBufferUint16EXT, aby pobrać bufor uint16_t.
  • XR_SPATIAL_BUFFER_TYPE_UINT32_EXT. Wartość XrSpatialBufferIdEXT can można przekazać do funkcji xrGetSpatialBufferUint32EXT, aby pobrać bufor uint32_t.
  • XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT. Wartość XrSpatialBufferIdEXT can można przekazać do funkcji xrGetSpatialBufferFloatEXT, aby pobrać bufor float.
  • XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT. Wartość XrSpatialBufferIdEXT can można przekazać do funkcji xrGetSpatialBufferVector2fEXT, aby pobrać bufor XrVector2f.
  • XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT. Wartość XrSpatialBufferIdEXT może zostać przekazana do funkcji xrGetSpatialBufferVector3fEXT, aby pobrać bufor XrVector3f.

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, do którego można wysyłać zapytania.
  • bufferCapacityInput to pojemność tablicy lub 0, aby wskazać żądanie pobrania wymaganej pojemności.
  • bufferCountOutput to liczba znaków lub wymagana pojemność w przypadku, gdy bufferCapacityInput jest niewystarczająca.
  • buffer to tablica elementów char . Może to być NULL, jeśli bufferCapacityInput wynosi 0.
  • Szczegółowy opis pobierania wymaganego rozmiaru buffer znajdziesz w sekcji Parametry rozmiaru bufora.

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

Środowisko wykonawcze musi zwrócić XR_ERROR_VALIDATION_FAILURE, jeśli wartość XrSpatialBufferTypeEXT dla XrSpatialBufferGetInfoEXT :: bufferId nie jest równa XR_SPATIAL_BUFFER_TYPE_STRING_EXT .

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

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

Prawidłowe użycie (domyślne)

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

Kody zwrotne

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, do którego można wysyłać zapytania.
  • bufferCapacityInput to pojemność tablicy lub 0, aby wskazać żądanie pobrania wymaganej pojemności.
  • bufferCountOutput to liczba elementów w tablicy buffer lub wymagana pojemność w przypadku, gdy bufferCapacityInput jest niewystarczająca.
  • buffer to tablica elementów uint8_t . Może to być NULL, jeśli bufferCapacityInput wynosi 0.
  • Szczegółowy opis pobierania wymaganego rozmiaru buffer znajdziesz w sekcji Parametry rozmiaru bufora.

Aplikacja może pobierać dane z obiektu XrSpatialBufferEXT dostarczonego przez komponent, gdzie XrSpatialBufferEXT :: bufferType to XR_SPATIAL_BUFFER_TYPE_UINT8_EXT, za pomocą funkcji xrGetSpatialBufferUint8EXT .

Środowisko wykonawcze musi zwrócić XR_ERROR_VALIDATION_FAILURE, jeśli wartość XrSpatialBufferTypeEXT dla XrSpatialBufferGetInfoEXT :: bufferId nie jest równa XR_SPATIAL_BUFFER_TYPE_UINT8_EXT .

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

Prawidłowe użycie (domyślne)

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

Kody zwrotne

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, do którego można wysyłać zapytania.
  • bufferCapacityInput to pojemność tablicy lub 0, aby wskazać żądanie pobrania wymaganej pojemności.
  • bufferCountOutput to liczba elementów w tablicy buffer lub wymagana pojemność w przypadku, gdy bufferCapacityInput jest niewystarczająca.
  • buffer to tablica elementów uint16_t . Może to być NULL, jeśli bufferCapacityInput wynosi 0.
  • Szczegółowy opis pobierania wymaganego rozmiaru buffer znajdziesz w sekcji Parametry rozmiaru bufora.

Aplikacja może pobierać dane z obiektu XrSpatialBufferEXT dostarczonego przez komponent, gdzie XrSpatialBufferEXT :: bufferType to XR_SPATIAL_BUFFER_TYPE_UINT16_EXT, za pomocą funkcji xrGetSpatialBufferUint16EXT .

Środowisko wykonawcze musi zwrócić XR_ERROR_VALIDATION_FAILURE, jeśli wartość XrSpatialBufferTypeEXT dla XrSpatialBufferGetInfoEXT :: bufferId nie jest równa XR_SPATIAL_BUFFER_TYPE_UINT16_EXT .

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

Prawidłowe użycie (domyślne)

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

Kody zwrotne

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, do którego można wysyłać zapytania.
  • bufferCapacityInput to pojemność tablicy lub 0, aby wskazać żądanie pobrania wymaganej pojemności.
  • bufferCountOutput to liczba elementów w tablicy buffer lub wymagana pojemność w przypadku, gdy bufferCapacityInput jest niewystarczająca.
  • buffer to tablica elementów uint32_t . Może to być NULL, jeśli bufferCapacityInput wynosi 0.
  • Szczegółowy opis pobierania wymaganego rozmiaru buffer znajdziesz w sekcji Parametry rozmiaru bufora.

Aplikacja może pobierać dane z XrSpatialBufferEXT dostarczonego przez komponent, gdzie XrSpatialBufferEXT :: bufferType to XR_SPATIAL_BUFFER_TYPE_UINT32_EXT, za pomocą funkcji xrGetSpatialBufferUint32EXT .

Środowisko wykonawcze musi zwrócić XR_ERROR_VALIDATION_FAILURE, jeśli wartość XrSpatialBufferTypeEXT dla XrSpatialBufferGetInfoEXT :: bufferId nie jest równa XR_SPATIAL_BUFFER_TYPE_UINT32_EXT .

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

Prawidłowe użycie (domyślne)

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

Kody zwrotne

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, do którego można wysyłać zapytania.
  • bufferCapacityInput to pojemność tablicy lub 0, aby wskazać żądanie pobrania wymaganej pojemności.
  • bufferCountOutput to liczba elementów w tablicy buffer lub wymagana pojemność w przypadku, gdy bufferCapacityInput jest niewystarczająca.
  • buffer to tablica elementów float . Może to być NULL, jeśli bufferCapacityInput wynosi 0.
  • Szczegółowy opis pobierania wymaganego rozmiaru buffer znajdziesz w sekcji Parametry rozmiaru bufora.

Aplikacja może pobierać dane z obiektu XrSpatialBufferEXT dostarczonego przez komponent, gdzie XrSpatialBufferEXT :: bufferType to XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT, za pomocą funkcji xrGetSpatialBufferFloatEXT .

Środowisko wykonawcze musi zwrócić XR_ERROR_VALIDATION_FAILURE, jeśli wartość XrSpatialBufferTypeEXT dla XrSpatialBufferGetInfoEXT :: bufferId nie jest równa XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT .

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

Prawidłowe użycie (domyślne)

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

Kody zwrotne

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, do którego można wysyłać zapytania.
  • bufferCapacityInput to pojemność tablicy lub 0, aby wskazać żądanie pobrania wymaganej pojemności.
  • bufferCountOutput to liczba elementów w tablicy buffer lub wymagana pojemność w przypadku, gdy bufferCapacityInput jest niewystarczająca.
  • buffer to tablica typu XrVector2f . Może to być NULL, jeśli bufferCapacityInput wynosi 0.
  • Szczegółowy opis pobierania wymaganego rozmiaru buffer znajdziesz w sekcji Parametry rozmiaru bufora.

Aplikacja może pobrać dane z XrSpatialBufferEXT dostarczonego przez komponent, gdzie XrSpatialBufferEXT :: bufferType to XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT, za pomocą funkcji xrGetSpatialBufferVector2fEXT .

Środowisko wykonawcze musi zwrócić XR_ERROR_VALIDATION_FAILURE, jeśli wartość XrSpatialBufferTypeEXT dla XrSpatialBufferGetInfoEXT :: bufferId nie jest równa XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT .

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

Prawidłowe użycie (domyślne)

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

Kody zwrotne

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, do którego można wysyłać zapytania.
  • bufferCapacityInput to pojemność tablicy lub 0, aby wskazać żądanie pobrania wymaganej pojemności.
  • bufferCountOutput to liczba elementów w tablicy buffer lub wymagana pojemność w przypadku, gdy bufferCapacityInput jest niewystarczająca.
  • buffer to tablica elementów XrVector3f . Może to być NULL, jeśli bufferCapacityInput wynosi 0.
  • Szczegółowy opis pobierania wymaganego rozmiaru buffer znajdziesz w sekcji Parametry rozmiaru bufora.

Aplikacja może pobierać dane z obiektu XrSpatialBufferEXT dostarczonego przez komponent, gdzie XrSpatialBufferEXT :: bufferType to XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT, za pomocą funkcji xrGetSpatialBufferVector3fEXT .

Środowisko wykonawcze musi zwrócić XR_ERROR_VALIDATION_FAILURE, jeśli wartość XrSpatialBufferTypeEXT dla XrSpatialBufferGetInfoEXT :: bufferId nie jest równa XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT .

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

Prawidłowe użycie (domyślne)

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

Kody zwrotne

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 dla bufora, z którego mają zostać pobrane dane.

Prawidłowe użycie (domyślne)

#define XR_NULL_SPATIAL_BUFFER_ID_EXT 0

XR_NULL_SPATIAL_BUFFER_ID_EXT to zarezerwowana wartość reprezentująca nieprawidłowy XrSpatialBufferIdEXT . Można go przekazywać do funkcji interfejsu API i z nich zwracać 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 zrzutu i pobierania najnowszych danych komponentów dla określonych jednostek znanych środowisku wykonawczemu. Aplikacje mogą podawać uchwyty XrSpatialEntityEXT i typy komponentów, które je interesują, podczas tworzenia zrzutu.

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

Środowisko wykonawcze musi zwrócić XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT, jeśli którekolwiek z elementów XrSpatialComponentTypeEXT w strukturze XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes nie są włączone w przypadku funkcji przestrzennych przekazanych do struktury XrSpatialContextCreateInfoEXT :: capabilityConfigs podczas tworzenia struktury spatialContext .

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

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

Aplikacja może tworzyć dowolną liczbę zrzutów, ale musi pamiętać o pamięci przydzielanej do każdego nowego zrzutu i musi usuwać zrzuty, gdy nie są już potrzebne.

Prawidłowe użycie (domyślne)

Kody zwrotne

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 podstawowej specyfikacji OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.
  • entityCount to uint32_t opisujący liczbę elementów w tablicy entities.
  • entities to tablica obiektów XrSpatialEntityEXT, dla których środowisko wykonawcze musi uwzględnić dane komponentu w zrzucie.
  • componentTypeCount to uint32_t opisujący liczbę elementów w tablicy componentTypes.
  • componentTypes to tablica elementów XrSpatialComponentTypeEXT, dla których środowisko wykonawcze musi uwzględniać dane w zrzucie.
  • baseSpace to XrSpace, względem którego będą znajdować się wszystkie lokalizacje aktualizacji XrSpatialSnapshotEXT.
  • time to XrTime, w którym będą znajdować się wszystkie lokalizacje aktualizacji XrSpatialSnapshotEXT.

Prawidłowe użycie (domyślne)

  •  Rozszerzenie XR_EXT_spatial_entity musi być włączone przed użyciem struktury 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 componentTypeCount prawidłowych wartości XrSpatialComponentTypeEXT.
  • baseSpace musi być prawidłowym uchwytem 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 XrSession.

Usuwanie zrzutu

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 (domyślne)

Bezpieczeństwo wątków

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

Kody zwrotne

Sukces

  • XR_SUCCESS

Błąd

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Typowe komponenty

Bounded 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 y (extents.height) wyśrodkowane na center .

Wartości extents i XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT odnoszą się do rozmiaru jednostki na płaszczyźnie xy układu współrzędnych płaszczyzny. Płaszczyzna o pozycji {0, 0, 0}, obrocie {0, 0, 0, 1} (bez obrotu) i rozmiarze {1, 1} to płaszczyzna o wymiarach 1 m × 1 m wyśrodkowana w punkcie {0, 0, 0}, której wektor normalny przedniej ściany jest skierowany w kierunku +Z w przestrzeni komponentu.

X X Y Y Z Z Height Height Y Y Z Z X X Vertical plane Vertical plane Horizontal Plane Horizontal Plane Width Width Width Width Height Height

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

Uwaga

OpenXR używa płaszczyzny XY, w której wektor normalny to +Z, ale inne interfejsy API mogą używać płaszczyzny XZ, w której wektor normalny to +Y. Płaszczyznę XY można przekształcić w płaszczyznę XZ, obracając ją o –π/2 rad wokół osi +X.

Prawidłowe użycie (domyślne)

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 podstawowej specyfikacji OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.
  • boundCount to uint32_t opisujący liczbę elementów w tablicy bounds.
  • bounds to tablica elementów XrSpatialBounded2DDataEXT .

Środowisko wykonawcze musi zwracać XR_ERROR_VALIDATION_FAILURE z funkcji xrQuerySpatialComponentDataEXT, jeśli XrSpatialComponentBounded2DListEXT znajduje się w następnym łańcuchu XrSpatialComponentDataQueryResultEXT :: next, ale XrSpatialComponentDataQueryConditionEXT ::componentTypeCount nie jest zerem i XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT nie jest uwzględniony w XrSpatialComponentDataQueryConditionEXT :: componentTypes .

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

Jeśli xrQuerySpatialComponentDataEXT :: snapshot został utworzony na podstawie xrCreateSpatialDiscoverySnapshotCompleteEXT , środowisko wykonawcze musi udostępnić XrSpatialBounded2DDataEXT :: center w XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace i XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time .

Jeśli xrQuerySpatialComponentDataEXT :: snapshot został utworzony na podstawie xrCreateSpatialUpdateSnapshotEXT , środowisko wykonawcze musi udostępnić XrSpatialBounded2DDataEXT :: center w XrSpatialUpdateSnapshotCreateInfoEXT :: baseSpace i XrSpatialUpdateSnapshotCreateInfoEXT :: time .

Prawidłowe użycie (domyślne)

Konfiguracja

Jeśli XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT jest wymieniony w XrSpatialCapabilityComponentTypesEXT :: componentTypes dla pewnej 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 .

Ograniczone 3D

Dane komponentu

XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT używa do przechowywania danych XrBoxf.

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 podstawowej specyfikacji OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.
  • boundCount to uint32_t opisujący liczbę elementów w tablicy bounds.
  • bounds to tablica typu XrBoxf .

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

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

Jeśli xrQuerySpatialComponentDataEXT :: snapshot został utworzony na podstawie xrCreateSpatialDiscoverySnapshotCompleteEXT , środowisko wykonawcze musi udostępnić XrBoxf :: center w XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace w XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time .

Jeśli xrQuerySpatialComponentDataEXT :: snapshot został utworzony na podstawie xrCreateSpatialUpdateSnapshotEXT , środowisko wykonawcze musi udostępnić XrBoxf :: center w XrSpatialUpdateSnapshotCreateInfoEXT :: baseSpace w XrSpatialUpdateSnapshotCreateInfoEXT :: time .

Prawidłowe użycie (domyślne)

Konfiguracja

Jeśli w przypadku jakiejś funkcji w wyliczeniu XrSpatialCapabilityComponentTypesEXT :: componentTypes występuje wartość XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT, aplikacja może ją włączyć, dodając wyliczenie 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 korzysta z XrSpatialEntityIdEXT w przypadku swoich 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 podstawowej specyfikacji OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.
  • parentCount to uint32_t opisujący liczbę elementów w tablicy parents.
  • parents to tablica elementów XrSpatialEntityIdEXT .

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

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

Prawidłowe użycie (domyślne)

  •  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 tablicy wartości parentCount XrSpatialEntityIdEXT.
  •  Parametr parentCount musi być większy niż 0.
Konfiguracja

Jeśli w przypadku jakiejś funkcji w wyliczeniu XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT znajduje się element XrSpatialCapabilityComponentTypesEXT :: componentTypes, aplikacja może włączyć tę funkcję, dodając wyliczenie 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 .

Mesh 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 pochodzenie siatki. Wszystkie wierzchołki siatki muszą być względne w stosunku do tego punktu początkowego.
  • vertexBuffer to XrSpatialBufferEXT, który zawiera identyfikator bufora reprezentującego bufor wierzchołków jednostki, do której należy ten komponent. Położenie wierzchołków musi być względne względem origin .
  • indexBuffer to XrSpatialBufferEXT, który zawiera identyfikator bufora reprezentującego tablicę indeksów trójkątów określających indeksy wierzchołków siatki w vertexBuffer . Indeksy trójkątów muszą być zwracane w kolejności przeciwnej do ruchu wskazówek zegara, a 3 indeksy oznaczają 1 trójkąt.

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

Prawidłowe użycie (domyślne)

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 elementów XrSpatialMeshDataEXT .

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

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

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

W przypadku struktury XrSpatialMeshDataEXT wypełnionej przez środowisko wykonawcze w tablicy meshes pole XrSpatialBufferEXT :: bufferType dla XrSpatialMeshDataEXT :: vertexBuffer musi mieć wartość XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT, a pole XrSpatialBufferEXT :: bufferType dla XrSpatialMeshDataEXT :: indexBuffer musi mieć wartość XR_SPATIAL_BUFFER_TYPE_UINT32_EXT .

Prawidłowe użycie (domyślne)

Konfiguracja

Jeśli XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT jest wyliczony w XrSpatialCapabilityComponentTypesEXT :: componentTypes dla pewnej funkcji, aplikacja może ją włączyć, dodając wyliczenie do listy XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents w strukturze 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żyć 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żyć XrSpatialFilterTrackingStateEXT w następnym łańcuchu XrSpatialComponentDataQueryConditionEXT, aby ograniczyć zapytanie o dane komponentu z migawki tylko do podmiotów, których stan śledzenia to trackingState .

Prawidłowe użycie (domyślne)

Przykładowy kod

Korzystanie z aplikacji

Aplikacje zwykle używają rozszerzenia obiektu przestrzennego w ten sposób:

Odkrywanie obiektów przestrzennych i wykonywanie zapytań dotyczących danych komponentów

Poniższy przykładowy kod pokazuje, jak wykrywać encje przestrzenne dla zapytania o możliwość „Foo” i wykonywać zapytania o dane komponentów.

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

Wykonywanie zapytań o dane bufora

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 typ XrSpatialComponentTypeEXT, który dostarcza dodatkowe dane o obiekcie przestrzennym,

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

  • Jeśli rozszerzenie definiuje nowy element XrSpatialCapabilityEXT ,

  • Jeśli rozszerzenie definiuje nową funkcję XrSpatialCapabilityFeatureEXT, musi też zdefiniować odpowiednią strukturę konfiguracji, którą można połączyć z następnym wskaźnikiem XrSpatialCapabilityConfigurationBaseHeaderEXT. Aplikacja może użyć tej struktury, aby włączyć funkcję podczas tworzenia elementu XrSpatialContextEXT.

  • Rozszerzenie definiujące nową funkcję XrSpatialCapabilityEXT powinno być zgodne z tym szablonem specyfikacji:

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

  • Rozszerzenie definiujące nowy typ 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ć element XrSpatialBufferTypeEXT, aby poinformować aplikację o typie danych w buforze. 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 podmiotu, określa zasady projektowania i wytyczne dla wszystkich rozszerzeń, które definiują taki komponent. W poniższym tekście słowa „ powinien ” i „ musi ” odnoszą się do autorów takich funkcji, a nie do implementacji w czasie działania ani do aplikacji korzystającej z interfejsu API.

  • Jeśli rozszerzenie definiuje etykiety semantyczne dla dowolnego elementu XrSpatialCapabilityEXT, powinno to zrobić, definiując nowy element XrSpatialComponentTypeEXT, a także nowe wyliczenie z zestawem etykiet („zestaw 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ść informuje aplikacje, że środowisko wykonawcze rozpoznaje ten element, ale istnieją inne zestawy etykiet semantycznych, w których ten element jest sklasyfikowany.
  • Wyliczenie nowo zdefiniowanego typu XrSpatialComponentTypeEXT w funkcji xrEnumerateSpatialCapabilityComponentTypesEXT oznacza, że środowisko wykonawcze obsługuje zestaw etykiet semantycznych (a tym samym etykiety zdefiniowane w tym zestawie) odpowiadający danemu typowi komponentu.
  • Aplikacje wyrażają chęć wykrywania obiektów, które mają etykiety należące do tego zbioru etykiet semantycznych, poprzez umieszczenie odpowiedniego elementu XrSpatialComponentTypeEXT w tablicy XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents struktury konfiguracji funkcji, dla której wyliczany jest typ komponentu.
  • Możliwe, że pojedynczy obiekt przestrzenny ma wiele komponentów, z których każdy przypisuje mu etykietę z własnego zestawu etykiet semantycznych. Rozważmy ten przykład z hipotetycznymi zbiorami etykiet semantycznych – XrSpatialObjectSemanticLabel, które mogą mieć wartości takie jak krzesło, sofa, stół itp. XrSpatialSofaBrand, które może mieć wartości takie jak IKEA, Wayfair itp., oraz XrSpatialIkeaSofa, które może zawierać konkretne nazwy modeli sof IKEA. W tym scenariuszu ta sama jednostka sofy ma wszystkie 3 komponenty (etykiety ze wszystkich 3 zestawów etykiet semantycznych), z których każdy zawiera informacje o różnym poziomie szczegółowości.
  • Jeśli rozszerzenie definiuje nowy typ XrSpatialComponentTypeEXT, który udostępnia nowy zestaw etykiet semantycznych zawierający wiele etykiet oprócz etykiety UNCATEGORIZED, rozszerzenie powinno rozważyć zdefiniowanie typu XrSpatialCapabilityFeatureEXT, który umożliwia aplikacjom aktywowanie tylko podzbioru etykiet zdefiniowanych w zestawie etykiet semantycznych odpowiadającym danemu typowi komponentu. Ten podzbiór, podany w następnym łańcuchu konfiguracji funkcji, służy jako wskazówka dla środowisk wykonawczych, aby zoptymalizować ścieżki śledzenia i śledzić tylko podany podzbiór. Przykład takiej struktury funkcji znajdziesz poniżej .
  • Rozszerzenia nie mogą dodawać etykiet do istniejącego wyliczenia zbioru etykiet semantycznych. Zamiast tego muszą zdefiniować nowe wyliczenie, które zawiera równoważne elementy wyliczeniowe o identycznej semantyce i wartościach równych wartościom z innego 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 funkcji 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ład rozszerzenia etykiety semantycznej przestrzennej
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;

Rozważmy powyższy przykład, w którym rozszerzenie definiuje wyliczenie XrSpatialExamplePlaneSemanticLabelExtensionEXT, aby rozszerzyć istniejącą strukturę XrSpatialPlaneSemanticLabelEXT o wartości reprezentujące drzwi i okna. Specyfikacja nowego wyliczenia musi zawierać tekst w tej formie:

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 podstaw

  • XrSpatialBufferIdEXT
  • XrSpatialEntityIdEXT

Nowe typy obiektów

Nowe polecenia

Nowe struktury

Nowe wartości w polu enum

Nowe stałe wyliczeniowe

  • 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

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

  • Czy pojedynczy podmiot zawsze wywodzi się tylko z jednej funkcji?

    • Rozwiązane
    • Odpowiedź: Nie. Zależy to całkowicie od środowiska wykonawczego, które na podstawie własnych możliwości śledzenia decyduje, jak przedstawić wykryty element. Specyfikacja nie określa żadnej konkretnej reprezentacji obiektu przestrzennego, z wyjątkiem gwarantowanych komponentów danej funkcji, aby ustalić minimalne oczekiwania. Środowisko wykonawcze może łączyć jednostki wykryte przez różne funkcje i przedstawiać je jako jedną jednostkę z gwarantowanymi komponentami wszystkich funkcji, które pomogły ją zidentyfikować. Przykładem może być wykrywanie stołów zarówno przez funkcję śledzenia płaszczyzny, jak i funkcję śledzenia obiektu. W tym przypadku śledzenie płaszczyzny dostarcza komponent XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT w encji, a śledzenie obiektu dostarcza komponent XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT. Niektóre środowiska wykonawcze mogą udostępniać tabelę jako 2 oddzielne elementy, z których każdy ma własny zestaw gwarantowanych komponentów, a niektóre środowiska wykonawcze mogą udostępniać tylko 1 element reprezentujący tabelę, w którym zarówno XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT, jak i XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT znajdują się w tym samym elemencie. Warto zauważyć, że dana jednostka przestrzenna może mieć co najwyżej 1 komponent dowolnego typu komponentu . Dlatego jeśli dane komponentu wygenerowane przez różne funkcje są sprzeczne w przypadku określonego podmiotu, środowisko wykonawcze musi przedstawić je jako 2 osobne podmioty.

Historia zmian

  • Wersja 1, 12.04.2024 (Nihav Jain, Google)

    • Wstępny opis rozszerzenia