XR_EXT_spatial_entity

Name String

XR_EXT_spatial_entity

Tipo di estensione

Estensione dell'istanza

Numero di interno registrato

741

Revisione

1

Stato della ratifica

Ratificato

Dipendenze di estensioni e versioni

XR_EXT_future

Collaboratori

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

Panoramica

Questa estensione introduce i concetti e i fondamenti per la comprensione delle scene e il ragionamento spaziale in OpenXR. In questo modo vengono unificate diverse aree di funzionalità correlate ma distinte, che vengono enumerate, configurate e utilizzate in modo ampiamente uniforme, come definito da questa estensione. Poiché questa estensione non contiene definizioni concrete di nessuna di queste aree funzionali, il testo della specifica formale tende a essere un po' astratto. Gli esempi inclusi nel testo di questa specifica dell'estensione si riferiscono a volte a funzionalità definite in un'estensione correlata imminente o ipotetica a scopo illustrativo, senza limitare o specificare intrinsecamente tale funzionalità aggiuntiva.

Le parti principali di questa estensione sono le seguenti:

  • Entità spaziali : la funzionalità è incentrata sulle entità , che di per sé offrono funzionalità molto limitate.
  • Componenti spaziali : a queste entità sono associati componenti che forniscono dati e comportamenti.
  • Tipi di componenti spaziali : ogni componente spaziale è di un tipo di componente specifico e ogni entità ha al massimo un singolo componente di un determinato tipo di componente .
  • Contesto spaziale : tutte le interazioni con le entità spaziali avvengono in un contesto dopo una fase di inizializzazione e configurazione.
  • Funzionalità spaziali : la manipolazione delle entità spaziali è ampiamente fornita dalle funzionalità . Una funzionalità è un'unità di funzionalità, ad esempio (senza alcuna limitazione) ancoraggi definiti dall'applicazione, rilevamento di piani o monitoraggio di immagini. Ogni funzionalità è in genere definita in un'estensione separata (attivata al momento della creazione dell'istanza, come di consueto) e viene attivata per un contesto specifico al momento della creazione.
  • Ogni funzionalità è associata a un insieme di tipi di componenti per i quali sono presenti componenti in ogni entità esposta da quella funzionalità . L'estensione che definisce una funzionalità specifica quali tipi di componenti sono obbligatori per la funzionalità ("garantiti"), mentre la stessa estensione o altre possono specificare tipi di componenti facoltativi forniti da alcune potenziali implementazioni. Un numero qualsiasi di funzionalità potrebbe fornire alle entità componenti di un determinato tipo di componente , che sono utilizzabili in modo uniforme indipendentemente dalla funzionalità che li ha prodotti.
  • Funzionalità delle funzionalità spaziali : inoltre, alcune funzionalità richiedono la configurazione e sono quindi parametrizzate dalle funzionalità delle funzionalità .

Questa estensione fornisce un meccanismo per enumerare i componenti forniti da ogni funzionalità supportata sul sistema corrente, sia i componenti obbligatori che quelli facoltativi.

Poiché alcune implementazioni potrebbero richiedere diversi gradi di parametrizzazione per le funzionalità , questa estensione fornisce un meccanismo per enumerare le funzionalità supportate associate a una determinata funzionalità nel sistema attuale.

Questa estensione definisce anche diversi componenti comuni che dovrebbero essere utilizzati in un'ampia gamma di funzionalità .

Entità spaziale

Le entità spaziali sono entità che esistono in uno spazio e hanno vari dati associati organizzati in componenti. Possono essere:

  • Fisico (ad es. superfici piane come pareti e pavimenti, oggetti come sedie e librerie e così via)
  • Virtuale (ad es. contenuti inseriti e condivisi da un'altra applicazione o un altro utente)
  • Definiti dall'app (ad es. l'applicazione contrassegna un'area come "salotto" o "cucina" oppure contrassegna un punto come la posizione in cui posizionare la TV e così via)

Gli elementi esposti tramite il sistema di azioni, come i controller o lo sguardo, non sono destinati a essere modellati come entità spaziali.

Le entità spaziali in OpenXR sono modellate come un sistema Entity-Component . Ogni entità spaziale ha un insieme di componenti e ogni componente fornisce un insieme univoco di dati e comportamenti per l'entità.

Le entità spaziali sono rappresentate da un atomo XrSpatialEntityIdEXT o da un handle XrSpatialEntityEXT, i cui dettagli sono forniti nella sezione Rappresentazioni delle entità spaziali.

Tipi di componenti spaziali

Un'entità spaziale ha uno o più componenti che forniscono dati o comportamenti per l'entità. Consulta la sezione Componenti comuni per alcuni componenti comuni definiti da questa estensione.

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

L'enumerazione XrSpatialComponentTypeEXT identifica i diversi tipi di componenti che il runtime potrebbe supportare.

Non tutti i tipi di componenti elencati sono forniti da questa estensione da sola: alcuni richiedono l'attivazione di estensioni aggiuntive al momento della creazione dell'istanza, come documentato.

Gli enumeratori hanno i seguenti valori:

Descrizione enum

XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

Componente che fornisce i limiti 2D per un'entità spaziale. La struttura dell'elenco corrispondente è XrSpatialComponentBounded2DListEXT; la struttura dei dati corrispondente è XrSpatialBounded2DDataEXT

XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT

Componente che fornisce i limiti 3D per un'entità spaziale. La struttura dell'elenco corrispondente è XrSpatialComponentBounded3DListEXT; la struttura dei dati corrispondente è XrBoxf

XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT

Componente che fornisce l'XrSpatialEntityIdEXT dell'entità padre per un'entità spaziale. La struttura dell'elenco corrispondente è XrSpatialComponentParentListEXT; la struttura dei dati corrispondente è XrSpatialEntityIdEXT

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT

Componente che fornisce una mesh 3D per un'entità spaziale. La struttura dell'elenco corrispondente è XrSpatialComponentMesh3DListEXT; la struttura dei dati corrispondente è XrSpatialMeshDataEXT

XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT

Componente che fornisce l'enum di allineamento del piano per un'entità spaziale. La struttura dell'elenco corrispondente è XrSpatialComponentPlaneAlignmentListEXT; la struttura dei dati corrispondente è XrSpatialPlaneAlignmentEXT (aggiunta dall'estensione XR_EXT_spatial_plane_tracking)

XR_SPATIAL_COMPONENT_TYPE_MESH_2D_EXT

Componente che fornisce una mesh 2D per un'entità spaziale. La struttura dell'elenco corrispondente è XrSpatialComponentMesh2DListEXT; la struttura dei dati corrispondente è XrSpatialMeshDataEXT (aggiunta dall'estensione XR_EXT_spatial_plane_tracking)

XR_SPATIAL_COMPONENT_TYPE_POLYGON_2D_EXT

Componente che fornisce un poligono di confine 2D per un'entità spaziale. La struttura dell'elenco corrispondente è XrSpatialComponentPolygon2DListEXT; la struttura dei dati corrispondente è XrSpatialPolygon2DDataEXT (aggiunta dall'estensione XR_EXT_spatial_plane_tracking)

XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT

Componente che fornisce un'etichetta semantica per un piano. La struttura dell'elenco corrispondente è XrSpatialComponentPlaneSemanticLabelListEXT; la struttura dei dati corrispondente è XrSpatialPlaneSemanticLabelEXT (aggiunta dall'estensione XR_EXT_spatial_plane_tracking)

XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT

Un componente che descrive il tipo, l'ID e la posizione dell'indicatore. La struttura dell'elenco corrispondente è XrSpatialComponentMarkerListEXT; la struttura dei dati corrispondente è XrSpatialMarkerDataEXT (aggiunta dall'estensione XR_EXT_spatial_marker_tracking)

XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT

Componente che fornisce un'etichetta semantica per una scena; la struttura dell'elenco corrispondente è XrSpatialComponentObjectSemanticLabelListEXT . La struttura dei dati corrispondente è XrSpatialObjectSemanticLabelEXT . (Aggiunto dall'estensione XR_EXT_spatial_object_tracking)

XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT

Componente che fornisce un'etichetta semantica per una tastiera; la struttura dell'elenco corrispondente è XrSpatialComponentKeyboardSemanticLabelListEXT . La struttura dei dati corrispondente è XrSpatialKeyboardSemanticLabelEXT (aggiunta dall'estensione XR_EXT_spatial_object_tracking)

XR_SPATIAL_COMPONENT_TYPE_MOUSE_SEMANTIC_LABEL_EXT

Componente che fornisce un'etichetta semantica per un mouse; la struttura dell'elenco corrispondente è XrSpatialComponentMouseSemanticLabelListEXT . La struttura dei dati corrispondente è XrSpatialMouseSemanticLabelEXT (aggiunta dall'estensione XR_EXT_spatial_object_tracking)

XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT

Componente che fornisce la posizione di un'ancora. La struttura dell'elenco corrispondente è XrSpatialComponentAnchorListEXT; la struttura dei dati corrispondente è XrPosef (aggiunta dall'estensione XR_EXT_spatial_anchor)

XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT

Componente che fornisce l'UUID persistente per un'entità spaziale. La struttura dell'elenco corrispondente è XrSpatialComponentPersistenceListEXT; la struttura dei dati corrispondente è XrSpatialPersistenceDataEXT (aggiunta dall'estensione XR_EXT_spatial_persistence)

XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT

Un componente che descrive il tipo di immagine planare. La struttura dell'elenco corrispondente è XrSpatialComponentImage2DListEXT; la struttura dei dati corrispondente è XrSpatialImageSizeEXT . (Aggiunto dall'estensione XR_EXT_spatial_image_tracking)

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_NORMALS_EXT

Componente che fornisce le normali per la mesh 3D di un'entità spaziale. La struttura dell'elenco corrispondente è XrSpatialComponentMesh3DNormalsListEXT; la struttura dei dati corrispondente è XrSpatialBufferEXT (aggiunta dall'estensione XR_EXT_spatial_mesh_tracking)

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_VERTEX_SEMANTIC_LABELS_EXT

Componente che fornisce le etichette semantiche per vertice per la mesh 3D di un'entità spaziale. La struttura dell'elenco corrispondente è XrSpatialComponentMesh3DVertexSemanticLabelsListEXT; la struttura dei dati corrispondente è XrSpatialBufferEXT; i dati all'interno del buffer vengono mappati a XrSpatialMeshSemanticLabelEXT (aggiunto dall'estensione XR_EXT_spatial_mesh_tracking)

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_TRIANGLE_SEMANTIC_LABELS_EXT

Componente che fornisce le etichette semantiche per ogni faccia triangolare della mesh 3D di un'entità spaziale. La struttura dell'elenco corrispondente è XrSpatialComponentMesh3DTriangleSemanticLabelsListEXT; la struttura dei dati corrispondente è XrSpatialBufferEXT; i dati all'interno del buffer vengono mappati a XrSpatialMeshSemanticLabelEXT (aggiunto dall'estensione XR_EXT_spatial_mesh_tracking)

XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_ANDROID

Componente che fornisce un'etichetta semantica per un oggetto; la struttura dell'elenco corrispondente è XrSpatialComponentObjectSemanticLabelListANDROID; la struttura dei dati corrispondente è XrSpatialObjectSemanticLabelANDROID (aggiunta dall'estensione XR_ANDROID_spatial_object_tracking)

XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID

Componente che fornisce la posa di un hit raycast su un'entità. La struttura dell'elenco corrispondente è XrSpatialComponentRaycastResultListANDROID; la struttura dei dati corrispondente è XrSpatialRaycastResultDataANDROID (aggiunta dall'estensione XR_ANDROID_spatial_discovery_raycast)

XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID

Componente che fornisce l'ID entità dell'entità che include l'entità collegata. La struttura dell'elenco corrispondente è XrSpatialComponentSubsumedByListANDROID; la struttura dei dati corrispondente è XrSpatialEntityIdEXT (aggiunta dall'estensione XR_ANDROID_spatial_component_subsumed_by)

XR_SPATIAL_COMPONENT_TYPE_ROOM_ANDROIDSYS

Componente che fornisce le dimensioni e il tipo di stanza di una shoebox; la struttura dell'elenco corrispondente è XrSpatialComponentRoomListANDROIDSYS; la struttura dei dati corrispondente è XrSpatialRoomDataANDROIDSYS (aggiunta dall'estensione XR_ANDROIDSYS_spatial_room_tracking)

XR_SPATIAL_COMPONENT_TYPE_MATERIAL_TYPE_ANDROIDSYS

Componente che fornisce il tipo di materiale di una superficie di confine; la struttura dell'elenco corrispondente è XrSpatialComponentMaterialTypeListANDROIDSYS; la struttura dei dati corrispondente è XrSpatialMaterialTypeANDROIDSYS (aggiunta dall'estensione XR_ANDROIDSYS_spatial_room_tracking)

XR_SPATIAL_COMPONENT_TYPE_CONFIDENCE_ANDROIDSYS

Componente che fornisce l'affidabilità di un elemento tracciabile; la struttura dell'elenco corrispondente è XrSpatialComponentConfidenceListANDROIDSYS; la struttura dei dati corrispondente è float (aggiunta dall'estensione XR_ANDROIDSYS_spatial_room_tracking)

XR_SPATIAL_COMPONENT_TYPE_ROOM_EMPTINESS_ANDROIDSYS

Componente che fornisce lo stato di vuoto di una stanza; la struttura dell'elenco corrispondente è XrSpatialComponentRoomEmptinessListANDROIDSYS; la struttura dei dati corrispondente è float (aggiunta dall'estensione XR_ANDROIDSYS_spatial_room_tracking)

XR_SPATIAL_COMPONENT_TYPE_OCCUPANCY_GRID_ANDROIDX1

Componente che fornisce informazioni sulla griglia di occupazione nell'entità collegata. La struttura dell'elenco corrispondente è XrSpatialComponentOccupancyGridListANDROIDX1; la struttura dei dati corrispondente è XrSpatialOccupancyGridDataANDROIDX1 (aggiunta dall'estensione XR_ANDROIDX1_spatial_occupancy_grid)

XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID

Un componente che descrive un'annotazione quadrilatera. La struttura dell'elenco corrispondente è XrSpatialComponentAnnotationQuadListANDROID; la struttura dei dati corrispondente è XrSpatialAnnotationQuadDataANDROID (aggiunta dall'estensione XR_ANDROID_spatial_annotation_tracking)

XR_SPATIAL_COMPONENT_TYPE_STREETSCAPE_GEOMETRY_METADATA_ANDROIDX2

Componente che fornisce i metadati per una geometria di Streetscape; la struttura dell'elenco corrispondente è XrSpatialComponentStreetscapeGeometryMetadataListANDROIDX2; la struttura dei dati corrispondente è XrSpatialStreetscapeGeometryMetadataANDROIDX2 (aggiunta dall'estensione XR_ANDROIDX2_geospatial_streetscape)

XR_SPATIAL_COMPONENT_TYPE_GEOMETRY_POINT_ANDROID

Componente che identifica un'entità come punto geometrico. Non esiste un elenco o una struttura di dati corrispondente per questo tipo di componente. La presenza di questo componente è semplicemente indicativa della capacità di un'entità di essere collegata a un ancoraggio. (Aggiunto dall'estensione XR_ANDROID_spatial_geometry_point)

XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_SCOPES_ANDROIDX1

Un componente che descrive gli ambiti di persistenza in cui l'entità viene resa persistente. Se il runtime supporta XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT, deve supportare anche questo componente. La struttura dei dati corrispondente è XrSpatialBufferEXT . La struttura dell'elenco corrispondente è XrSpatialComponentPersistenceScopeDataListANDROIDX1 . (Aggiunto dall'estensione XR_ANDROIDX1_spatial_anchor_cloud_sharing)

Funzionalità e configurazione spaziali

Le funzionalità spaziali definiscono le capacità di un runtime di rilevare entità che hanno un insieme garantito di componenti. Le applicazioni attivano i componenti di una funzionalità spaziale durante la creazione di XrSpatialContextEXT e il runtime, a sua volta, deve fornire solo i componenti attivati sulle entità rilevate. Ad esempio, se un runtime segnala che uno dei componenti per una determinata funzionalità è "etichette semantiche", significa che l'applicazione può attivare le etichette semantiche tramite la configurazione per quella funzionalità e il runtime deve fornire il componente dell'etichetta semantica solo se è configurato.

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;

L'enumerazione XrSpatialCapabilityEXT identifica i diversi tipi di funzionalità che il runtime può supportare.

Gli enumeratori hanno i seguenti valori:

Descrizione enum

XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT

Monitoraggio degli aerei (aggiunto dall'estensione XR_EXT_spatial_plane_tracking)

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT

Capacità di rilevare e monitorare i codici QR. (Aggiunto dall'estensione XR_EXT_spatial_marker_tracking)

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT

Capacità di rilevare e monitorare i codici QR Micro. (Aggiunto dall'estensione XR_EXT_spatial_marker_tracking)

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT

Capacità di rilevare e monitorare i marker ArUco. (Aggiunto dall'estensione XR_EXT_spatial_marker_tracking)

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT

Capacità di rilevare e monitorare gli AprilTag. (Aggiunto dall'estensione XR_EXT_spatial_marker_tracking)

XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT

Monitoraggio degli oggetti (aggiunto dall'estensione XR_EXT_spatial_object_tracking)

XR_SPATIAL_CAPABILITY_ANCHOR_EXT

Capacità di creare ancoraggi spaziali (aggiunta dall'estensione XR_EXT_spatial_anchor)

XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT

Capacità di rilevare e monitorare immagini di riferimento planari. (Aggiunto dall'estensione XR_EXT_spatial_image_tracking)

XR_SPATIAL_CAPABILITY_MESH_TRACKING_EXT

Capacità di monitorare la mesh di un ambiente. (Aggiunto dall'estensione XR_EXT_spatial_mesh_tracking)

XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_ANDROID

Monitoraggio degli oggetti (aggiunto dall'estensione XR_ANDROID_spatial_object_tracking)

XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID

Raycast rispetto al buffer di profondità (aggiunto dall'estensione XR_ANDROID_spatial_discovery_raycast)

XR_SPATIAL_CAPABILITY_ROOM_TRACKING_ANDROIDSYS

Funzionalità per monitorare una stanza (aggiunta dall'estensione XR_ANDROIDSYS_spatial_room_tracking)

XR_SPATIAL_CAPABILITY_ROOM_BOUNDARY_TRACKING_ANDROIDSYS

Possibilità di monitorare un confine della stanza (aggiunta dall'estensione XR_ANDROIDSYS_spatial_room_tracking)

XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID

Monitoraggio delle annotazioni (aggiunto dall'estensione XR_ANDROID_spatial_annotation_tracking)

XR_SPATIAL_CAPABILITY_STREETSCAPE_GEOMETRY_ANDROIDX2

Streetscape Geometry (aggiunta dall'estensione XR_ANDROIDX2_geospatial_streetscape)

La funzione xrEnumerateSpatialCapabilitiesEXT è definita come segue:

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

Descrizioni dei parametri

  • instance è un handle per un XrInstance .
  • systemId è il XrSystemId di cui verranno enumerate le funzionalità spaziali.
  • capabilityCapacityInput è la capacità dell'array capabilities o 0 per indicare una richiesta di recupero della capacità richiesta.
  • capabilityCountOutput è il numero di funzionalità o la capacità richiesta nel caso in cui capabilityCapacityInput non sia sufficiente.
  • capabilities è un array di XrSpatialCapabilityEXT . Può essere NULL se capabilityCapacityInput è 0.
  • Consulta la sezione Parametri della dimensione del buffer per una descrizione dettagliata del recupero della dimensione capabilities richiesta.

L'applicazione può enumerare l'elenco delle funzionalità spaziali supportate da un determinato XrSystemId utilizzando xrEnumerateSpatialCapabilitiesEXT .

Il runtime non deve enumerare le funzionalità spaziali la cui estensione non è abilitata per instance .

Utilizzo valido (implicito)

  • L'estensione XR_EXT_spatial_entity deve essere attivata prima di chiamare xrEnumerateSpatialCapabilitiesEXT
  • instance deve essere un handle XrInstance valido
  • capabilityCountOutput deve essere un puntatore a un valore uint32_t
  • Se capabilityCapacityInput non è 0 , capabilities deve essere un puntatore a un array di valori capabilityCapacityInput XrSpatialCapabilityEXT

Codici di risposta

Operazione riuscita

  • XR_SUCCESS

Errore

  • 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

La funzione xrEnumerateSpatialCapabilityComponentTypesEXT è definita come:

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

Descrizioni dei parametri

  • instance è un handle per un XrInstance .
  • systemId è il XrSystemId i cui componenti di funzionalità spaziale verranno enumerati.
  • capability è l'oggetto XrSpatialCapabilityEXT per cui verranno enumerati i componenti.
  • capabilityComponents è un puntatore a un XrSpatialCapabilityComponentTypesEXT , che è una struttura di input/output in cui viene compilato un array allocato dall'applicazione.

Questa funzione enumera i tipi di componenti che la funzionalità specificata fornisce alle sue entità nel sistema così come configurato.

L'applicazione può utilizzare i tipi di componenti elencati in XrSpatialCapabilityComponentTypesEXT :: componentTypes per comprendere l'insieme completo di componenti supportati da systemId per capability e può utilizzare questo elenco per determinare una configurazione valida per capability durante la creazione di un XrSpatialContextEXT per questo.

Il runtime deve restituire XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT se capability non è enumerato da xrEnumerateSpatialCapabilitiesEXT .

Il runtime non deve enumerare i tipi di componenti spaziali la cui estensione non è attivata per instance .

Utilizzo valido (implicito)

Codici di risposta

Operazione riuscita

  • XR_SUCCESS

Errore

  • 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

La struttura XrSpatialCapabilityComponentTypesEXT è definita come:

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

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Nessuna struttura di questo tipo è definita in OpenXR di base o in questa estensione.
  • componentTypeCapacityInput è la capacità dell'array o 0 per indicare una richiesta di recupero della capacità richiesta.
  • componentTypeCountOutput è il numero di tipi di componenti o la capacità richiesta nel caso in cui componentTypeCapacityInput non sia sufficiente.
  • componentTypes è un array di XrSpatialComponentTypeEXT . Può essere NULL se componentTypeCapacityInput è 0.
  • Consulta la sezione Parametri della dimensione del buffer per una descrizione dettagliata del recupero della dimensione componentTypes richiesta.

Utilizzo valido (implicito)

Funzionalità di calcolo spaziale

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;

Alcune funzionalità hanno parametri esposti all'applicazione per configurare il modo in cui i dati del componente vengono calcolati dal runtime. Queste dimensioni di parametrizzazione/configurabilità sono note come funzionalità di capacità. Ad esempio, per una funzionalità di monitoraggio delle immagini, un runtime può supportare una funzionalità che consente all'applicazione di specificare se le immagini monitorate sono fisse o meno.

La fornitura di queste informazioni al runtime tramite una struttura di configurazione non deve modificare l'insieme di tipi di componenti presenti sulle entità associate, ad esempio sull'immagine monitorata. Tuttavia, il runtime potrebbe essere in grado di ottimizzare, ad esempio, le capacità di tracciamento della funzionalità di tracciamento delle immagini e fornire un'esperienza migliore all'applicazione.

Queste funzionalità sono rappresentate da XrSpatialCapabilityFeatureEXT e l'applicazione le enumera utilizzando xrEnumerateSpatialCapabilityFeaturesEXT .

Ogni funzionalità ha una struttura di configurazione corrispondente per attivarla. Queste strutture di configurazione devono essere concatenate a XrSpatialCapabilityConfigurationBaseHeaderEXT :: next della funzionalità corrispondente.

Gli enumeratori hanno i seguenti valori:

Descrizione enum

XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_FIXED_SIZE_MARKERS_EXT

Funzionalità che consente alle applicazioni di specificare le dimensioni degli indicatori. La struttura di configurazione corrispondente è XrSpatialMarkerSizeEXT (aggiunta dall'estensione XR_EXT_spatial_marker_tracking)

XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_STATIC_MARKERS_EXT

Funzionalità che consente alle applicazioni di specificare se gli indicatori sono statici. La struttura di configurazione corrispondente è XrSpatialMarkerStaticOptimizationEXT (aggiunta dall'estensione XR_EXT_spatial_marker_tracking)

XR_SPATIAL_CAPABILITY_FEATURE_OBJECT_SEMANTIC_LABEL_SUBSET_EXT

Funzionalità spaziale che consente alle applicazioni di specificare un sottoinsieme di etichette da XrSpatialObjectSemanticLabelEXT per il monitoraggio del runtime. La struttura di configurazione corrispondente è XrSpatialFeatureObjectSemanticLabelSubsetEXT . (Aggiunto dall'estensione XR_EXT_spatial_object_tracking)

XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID

Il runtime supporta il filtro XrSpatialBoundsSpherefANDROID per XrSpatialDiscoverySnapshotCreateInfoEXT. Non è necessario includere alcuna struttura di configurazione durante la creazione del contesto spaziale. (Aggiunto dall'estensione XR_ANDROID_spatial_discovery_bounds)

XR_SPATIAL_CAPABILITY_FEATURE_BOX_BOUNDS_FILTER_ANDROID

Il runtime supporta il filtro XrSpatialBoundsBoxfANDROID per XrSpatialDiscoverySnapshotCreateInfoEXT. Non è necessario includere alcuna struttura di configurazione durante la creazione del contesto spaziale. (Aggiunto dall'estensione XR_ANDROID_spatial_discovery_bounds)

XR_SPATIAL_CAPABILITY_FEATURE_FRUSTUM_BOUNDS_FILTER_ANDROID

Il runtime supporta il filtro XrSpatialBoundsFrustumfANDROID per XrSpatialDiscoverySnapshotCreateInfoEXT. Non è necessario includere alcuna struttura di configurazione durante la creazione del contesto spaziale. (Aggiunto dall'estensione XR_ANDROID_spatial_discovery_bounds)

XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT

Il runtime supporta la deduzione automatica delle dimensioni fisiche delle immagini rilevate e monitorate. La struttura di configurazione corrispondente è XrSpatialImageSizeEXT (aggiunta dall'estensione XR_EXT_spatial_image_tracking)

XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT

Il runtime supporta XrSpatialImageStaticOptimizationEXT . La struttura di configurazione corrispondente è XrSpatialImageStaticOptimizationEXT . (Aggiunto dall'estensione XR_EXT_spatial_image_tracking)

XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT

Il runtime supporta XrSpatialImageSizeEXT . La struttura di configurazione corrispondente è XrSpatialImageSizeEXT (aggiunta dall'estensione XR_EXT_spatial_image_tracking)

XR_SPATIAL_CAPABILITY_FEATURE_TRACK_WATERTIGHT_MESH_EXT

Funzionalità per monitorare una mesh impermeabile dell'ambiente. La struttura di configurazione corrispondente è XrSpatialFeatureTrackWatertightMeshEXT . (Aggiunto dall'estensione XR_EXT_spatial_mesh_tracking)

La funzione xrEnumerateSpatialCapabilityFeaturesEXT è definita come segue:

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

Descrizioni dei parametri

  • instance è un handle per un XrInstance .
  • systemId è il XrSystemId di cui verranno enumerate le funzionalità di capacità spaziale.
  • capability è l'oggetto XrSpatialCapabilityEXT per cui verranno enumerate le funzionalità.
  • capabilityFeatureCapacityInput è la capacità dell'array o 0 per indicare una richiesta di recupero della capacità richiesta.
  • capabilityFeatureCountOutput è il numero di caratteristiche o la capacità richiesta nel caso in cui capabilityFeatureCapacityInput non sia sufficiente.
  • capabilityFeatures è un array di XrSpatialCapabilityFeatureEXT . Può essere NULL se capabilityFeatureCapacityInput è 0.
  • Consulta la sezione Parametri della dimensione del buffer per una descrizione dettagliata del recupero della dimensione capabilityFeatures richiesta.

L'applicazione rileva le funzionalità supportate da un determinato sistema per un XrSpatialCapabilityEXT utilizzando xrEnumerateSpatialCapabilityFeaturesEXT .

Per le funzionalità che hanno caratteristiche esposte, l'applicazione seleziona la caratteristica o le caratteristiche da attivare e fornisce la struttura di configurazione corrispondente nella catena successiva delle strutture di configurazione delle funzionalità in XrSpatialContextCreateInfoEXT :: capabilityConfigs .

Se capability non è una funzionalità enumerata da xrEnumerateSpatialCapabilitiesEXT , il runtime deve restituire XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT .

Il runtime non deve enumerare le funzionalità di capacità spaziale la cui estensione non è abilitata per instance .

Utilizzo valido (implicito)

Codici di risposta

Operazione riuscita

  • XR_SUCCESS

Errore

  • 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

Contesto spaziale

Crea un contesto spaziale

XR_DEFINE_HANDLE(XrSpatialContextEXT)

L'handle XrSpatialContextEXT rappresenta le risorse per rilevare e aggiornare un certo numero di entità spaziali nell'ambiente dell'utente. L'applicazione può utilizzare questo handle per rilevare e aggiornare le entità spaziali utilizzando altre funzioni di questa estensione.

La funzione xrCreateSpatialContextAsyncEXT è definita come:

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

Descrizioni dei parametri

  • session è un XrSession in cui il contesto spaziale sarà attivo.
  • createInfo è l'oggetto XrSpatialContextCreateInfoEXT utilizzato per specificare i parametri del contesto spaziale.
  • future è un puntatore a un XrFutureEXT .

L'applicazione può creare un handle XrSpatialContextEXT:

Il runtime deve restituire XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT se XrSpatialContextCreateInfoEXT ::capabilityConfigCount è 0. Un handle di contesto spaziale deve avere almeno una funzionalità.

Il runtime deve restituire XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT se una funzionalità nell'array XrSpatialContextCreateInfoEXT :: capabilityConfigs non è enumerata da xrEnumerateSpatialCapabilitiesEXT .

Il runtime deve restituire XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT se un qualsiasi XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponentCount in XrSpatialContextCreateInfoEXT :: capabilityConfigs è 0. Una configurazione della funzionalità è incompleta senza un elenco di tipi di componenti da attivare per quella funzionalità.

Il runtime deve restituire XR_ERROR_SPATIAL_COMPONENT_UNSUPPORTED_FOR_CAPABILITY_EXT se un tipo di componente elencato in XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents non è enumerato per XrSpatialCapabilityConfigurationBaseHeaderEXT :: capability in xrEnumerateSpatialCapabilityComponentTypesEXT .

Se una delle strutture nella catena successiva di XrSpatialContextCreateInfoEXT :: capabilityConfigs corrisponde a un XrSpatialCapabilityFeatureEXT che non è enumerato per quella funzionalità in xrEnumerateSpatialCapabilityFeaturesEXT , il runtime deve ignorare la struttura XrSpatialCapabilityFeatureEXT.

Il runtime deve restituire XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT se XrSpatialContextCreateInfoEXT :: capabilityConfigs contiene più strutture con lo stesso XrSpatialCapabilityConfigurationBaseHeaderEXT :: capability .

Per garantire un utilizzo ottimale delle risorse di sistema, il runtime può utilizzare le configurazioni fornite nell'array XrSpatialContextCreateInfoEXT per prepararsi alle richieste spaziali in arrivo. Ad esempio, un runtime che supporta la funzionalità di rilevamento dei piani potrebbe avviare la pipeline di rilevamento dei piani solo se l'applicazione crea un handle di contesto spaziale contenente la funzionalità di rilevamento dei piani. Se le funzionalità configurate hanno un tempo di riscaldamento lungo, le chiamate a xrCreateSpatialDiscoverySnapshotAsyncEXT potrebbero generare uno snapshot vuoto. L'applicazione può attendere XrEventDataSpatialDiscoveryRecommendedEXT prima di utilizzare xrCreateSpatialDiscoverySnapshotAsyncEXT per assicurarsi che i servizi di monitoraggio sottostanti siano stati avviati.

Se un runtime applica un sistema di autorizzazioni per controllare l'accesso dell'applicazione alle funzionalità spaziali configurate per XrSpatialContextEXT , il runtime deve restituire XR_ERROR_PERMISSION_INSUFFICIENT se queste autorizzazioni non sono state concesse all'applicazione.

Questa funzione avvia un'operazione asincrona e crea un XrFutureEXT corrispondente, utilizzabile con xrPollFutureEXT e le funzioni correlate. Il valore restituito da questa funzione indica solo se i parametri erano accettabili per pianificare l'operazione asincrona. La funzione di completamento corrispondente è xrCreateSpatialContextCompleteEXT , utilizzabile quando un future di questa funzione è nello stato READY, con gli output compilati da questa funzione nella struttura di completamento XrCreateSpatialContextCompletionEXT .

Utilizzo valido (implicito)

Codici di risposta

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_PERMISSION_INSUFFICIENT
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT
  • XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT
  • XR_ERROR_SPATIAL_COMPONENT_UNSUPPORTED_FOR_CAPABILITY_EXT
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_TIME_INVALID (se XR_ANDROID_spatial_annotation_tracking è abilitato)

La struttura XrSpatialContextCreateInfoEXT è definita come:

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

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Nessuna struttura di questo tipo è definita in OpenXR di base o in questa estensione.
  • capabilityConfigCount è un uint32_t che descrive il conteggio degli elementi nell'array capabilityConfigs.
  • capabilityConfigs è un puntatore a un array di puntatori XrSpatialCapabilityConfigurationBaseHeaderEXT.

La struttura XrSpatialContextCreateInfoEXT descrive le informazioni per creare un handle XrSpatialContextEXT.

Utilizzo valido (implicito)

La struttura XrSpatialCapabilityConfigurationBaseHeaderEXT è definita come:

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

Questa struttura non viene utilizzata direttamente nell'API, ma le sue strutture secondarie possono essere utilizzate con XrSpatialContextCreateInfoEXT per configurare le funzionalità spaziali.

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture.
  • capability è un XrSpatialCapabilityEXT .
  • enabledComponentCount è un uint32_t che descrive il conteggio degli elementi nell'array enabledComponents.
  • enabledComponents è un puntatore a un array di XrSpatialComponentTypeEXT .

Il runtime deve restituire XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT se capability non è enumerato da xrEnumerateSpatialCapabilitiesEXT . Il runtime deve restituire XR_ERROR_SPATIAL_COMPONENT_UNSUPPORTED_FOR_CAPABILITY_EXT se un tipo di componente elencato in enabledComponents non è enumerato per capability in xrEnumerateSpatialCapabilityComponentTypesEXT .

Utilizzo valido (implicito)

La funzione xrCreateSpatialContextCompleteEXT è definita come:

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

Descrizioni dei parametri

xrCreateSpatialContextCompleteEXT completa l'operazione asincrona avviata da xrCreateSpatialContextAsyncEXT . Il runtime deve restituire XR_ERROR_FUTURE_PENDING_EXT se future non è in stato Pronto. Il runtime deve restituire XR_ERROR_FUTURE_INVALID_EXT se future è già stato completato o annullato.

Utilizzo valido (implicito)

Codici di risposta

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • 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

La struttura XrCreateSpatialContextCompletionEXT è definita come:

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

Descrizioni dei membri

Codici di reso futuri

Valori futureResult:

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • 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

Se futureResult è un codice che ha superato il controllo, spatialContext deve essere valido. Se spatialContext è valido, rimane tale solo all'interno del ciclo di vita di xrCreateSpatialContextAsyncEXT :: session o finché l'applicazione non distrugge spatialContext con xrDestroySpatialContextEXT , a seconda di quale evento si verifica per primo.

Utilizzo valido (implicito)

Elimina il contesto spaziale

La funzione xrDestroySpatialContextEXT è definita come segue:

XrResult xrDestroySpatialContextEXT(
    XrSpatialContextEXT                         spatialContext);

Descrizioni dei parametri

L'applicazione può chiamare la funzione xrDestroySpatialContextEXT per rilasciare l'handle spatialContext e le risorse sottostanti al termine delle attività di rilevamento e aggiornamento delle entità spaziali. Se non esiste un altro XrSpatialContextEXT valido creato con le stesse funzionalità spaziali di spatialContext , questa chiamata funge da suggerimento al runtime per disattivare i servizi di monitoraggio richiesti per queste funzionalità al fine di risparmiare risorse di sistema.

Utilizzo valido (implicito)

Thread safety

  • L'accesso a spatialContext e a qualsiasi handle secondario deve essere sincronizzato esternamente

Codici di risposta

Operazione riuscita

  • XR_SUCCESS

Errore

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Rappresentazioni di entità spaziali

ID entità spaziale

XR_DEFINE_ATOM(XrSpatialEntityIdEXT)

XrSpatialEntityIdEXT viene utilizzato per rappresentare qualsiasi tipo di entità rilevata dal runtime nell'ambiente spaziale dell'utente. Un XrSpatialEntityIdEXT è valido per l'XrSpatialContextEXT in cui viene rilevato e il runtime non deve riutilizzare lo stesso XrSpatialEntityIdEXT per entità diverse all'interno dello stesso XrSpatialContextEXT . Inoltre, il runtime non deve riutilizzare lo stesso XrSpatialEntityIdEXT in più XrSpatialContextEXT all'interno dello stesso XrSession, indipendentemente dal fatto che rappresenti la stessa entità o entità diverse.

#define XR_NULL_SPATIAL_ENTITY_ID_EXT 0

XR_NULL_SPATIAL_ENTITY_ID_EXT è un valore riservato che rappresenta un XrSpatialEntityIdEXT non valido. Può essere passato alle funzioni API e restituito da queste solo se espressamente consentito.

Handle dell'entità spaziale

XR_DEFINE_HANDLE(XrSpatialEntityEXT)

L'handle XrSpatialEntityEXT rappresenta un'entità spaziale. Un'applicazione può creare un handle di questo tipo per esprimere il proprio interesse per un'entità specifica per il runtime.

Crea handle di entità spaziale dall'ID

La funzione xrCreateSpatialEntityFromIdEXT è definita come:

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

Descrizioni dei parametri

L'applicazione può utilizzare xrCreateSpatialEntityFromIdEXT per creare un handle XrSpatialEntityEXT che fa riferimento a un'entità esistente nell'ambiente dell'utente.

Il runtime deve restituire XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT se XrSpatialEntityFromIdCreateInfoEXT :: entityId non è un ID valido per spatialContext .

Utilizzo valido (implicito)

Codici di risposta

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • 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

La struttura XrSpatialEntityFromIdCreateInfoEXT è definita come:

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

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Nessuna struttura di questo tipo è definita in OpenXR di base o in questa estensione.
  • entityId è il XrSpatialEntityIdEXT dell'entità per cui l'applicazione vuole creare un handle.

Utilizzo valido (implicito)

Elimina handle entità spaziale

La funzione xrDestroySpatialEntityEXT è definita come segue:

XrResult xrDestroySpatialEntityEXT(
    XrSpatialEntityEXT                          spatialEntity);

Descrizioni dei parametri

L'applicazione può utilizzare xrDestroySpatialEntityEXT per rilasciare l'handle spatialEntity quando non è più interessata all'entità a cui fa riferimento questo handle.

Utilizzo valido (implicito)

Thread safety

  • L'accesso a spatialEntity e a qualsiasi handle secondario deve essere sincronizzato esternamente

Codici di risposta

Operazione riuscita

  • XR_SUCCESS

Errore

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Istantanea spaziale

XR_DEFINE_HANDLE(XrSpatialSnapshotEXT)

L'applicazione può creare snapshot spaziali allo scopo di rilevare entità spaziali o di aggiornare le informazioni sulle entità spaziali note. L'handle XrSpatialSnapshotEXT rappresenta i dati immutabili per le entità spaziali rilevate o aggiornate e un sottoinsieme dei relativi componenti selezionati dall'applicazione. L'istantanea spaziale rappresenta una visualizzazione coerente delle entità e dei relativi dati dei componenti. Una volta creato uno snapshot, i dati dello snapshot devono rimanere costanti per tutto il periodo di validità dello snapshot.

L'applicazione può creare un numero qualsiasi di snapshot, ma deve tenere conto della memoria allocata per ogni nuovo snapshot e deve eliminare gli snapshot quando non sono più necessari.

Crea snapshot di rilevamento

La funzione xrCreateSpatialDiscoverySnapshotAsyncEXT è definita come:

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

Descrizioni dei parametri

L'applicazione può rilevare entità spaziali creando uno snapshot di rilevamento utilizzando xrCreateSpatialDiscoverySnapshotAsyncEXT .

Questa funzione avvia un'operazione asincrona e crea un XrFutureEXT corrispondente, utilizzabile con xrPollFutureEXT e le funzioni correlate. Il valore restituito da questa funzione indica solo se i parametri erano accettabili per pianificare l'operazione asincrona. La funzione di completamento corrispondente è xrCreateSpatialDiscoverySnapshotCompleteEXT , utilizzabile quando un future di questa funzione è nello stato READY, con gli output compilati da questa funzione nella struttura di completamento XrCreateSpatialDiscoverySnapshotCompletionEXT .

L'applicazione può inviare più richieste di creazione di snapshot di rilevamento senza dover attendere il completamento della richiesta precedente. Il runtime può elaborare e completare la creazione degli snapshot in qualsiasi ordine. Il runtime potrebbe ritardare il completamento della creazione dello snapshot di rilevamento per limitare l'applicazione se deve ridurre l'utilizzo delle risorse di sistema a causa di norme relative all'alimentazione, alla temperatura o ad altri criteri del dispositivo.

L'applicazione può utilizzare XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes per filtrare l'elenco di entità e i componenti i cui dati il runtime deve includere nello snapshot. Se l'applicazione fornisce un elenco valido di tipi di componenti spaziali in XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes , il runtime deve includere nello snapshot solo le entità spaziali che hanno almeno uno dei componenti forniti in XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes . Inoltre, il runtime deve includere solo i dati relativi ai componenti nello snapshot.

Il runtime deve restituire XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT se uno dei XrSpatialComponentTypeEXT in XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes non è abilitato per le funzionalità spaziali passate a XrSpatialContextCreateInfoEXT :: capabilityConfigs durante la creazione di spatialContext .

Se l'applicazione non fornisce un elenco di tipi di componenti spaziali in XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes , il runtime deve includere nello snapshot tutte le entità spaziali che hanno l'insieme di componenti enumerati in XrSpatialCapabilityConfigurationBaseHeaderEXT ::enabledComponents per le funzionalità configurate per spatialContext . Il runtime deve includere i dati per tutti i componenti abilitati delle funzionalità configurate per spatialContext .

Se XrEventDataReferenceSpaceChangePending viene inserito in coda prima del completamento di future e XrEventDataReferenceSpaceChangePending :: poseValid è false, il runtime può creare un XrSpatialSnapshotEXT che non contiene entità o impostare XrSpatialEntityTrackingStateEXT delle entità che non sono più localizzabili in XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace in XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time su XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT o XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT . Il runtime non deve impostare XrCreateSpatialContextCompletionEXT :: futureResult su un codice di errore a causa di XrEventDataReferenceSpaceChangePending .

Utilizzo valido (implicito)

Codici di risposta

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • 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

La struttura XrSpatialDiscoverySnapshotCreateInfoEXT è definita come:

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

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Nessuna struttura di questo tipo è definita in OpenXR di base o in questa estensione.
  • componentTypeCount è un uint32_t che descrive il conteggio degli elementi nell'array componentTypes.
  • componentTypes è un array di XrSpatialComponentTypeEXT .

La struttura XrSpatialDiscoverySnapshotCreateInfoEXT descrive le informazioni per creare un handle XrSpatialSnapshotEXT durante il rilevamento di entità spaziali.

Utilizzo valido (implicito)

La funzione xrCreateSpatialDiscoverySnapshotCompleteEXT è definita come:

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

Descrizioni dei parametri

xrCreateSpatialDiscoverySnapshotCompleteEXT completa l'operazione asincrona avviata da xrCreateSpatialDiscoverySnapshotAsyncEXT . Il runtime deve restituire XR_ERROR_FUTURE_PENDING_EXT se XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: future non è in stato di pronto. Il runtime deve restituire XR_ERROR_FUTURE_INVALID_EXT se XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: future è già stato completato o annullato.

Utilizzo valido (implicito)

Codici di risposta

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • 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

La struttura XrCreateSpatialDiscoverySnapshotCompletionInfoEXT è definita come:

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

Descrizioni dei membri

Le località nei vari dati dei componenti inclusi nello snapshot creato verranno rappresentate in baseSpace , che si trova in time .

Utilizzo valido (implicito)

La struttura XrCreateSpatialDiscoverySnapshotCompletionEXT è definita come:

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

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture.
  • futureResult è l'XrResult dell'operazione di creazione dello snapshot di rilevamento spaziale.
  • snapshot è un XrSpatialSnapshotEXT che può essere utilizzato per eseguire query sui dati dei componenti delle entità spaziali rilevate.

Codici di reso futuri

Valori futureResult:

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED

Utilizzo valido (implicito)

Evento di suggerimento di Discovery

La struttura XrEventDataSpatialDiscoveryRecommendedEXT è definita come:

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

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture.
  • spatialContext è l'XrSpatialContextEXT per cui il runtime consiglia il rilevamento.

L'applicazione può recuperare questo evento utilizzando xrPollEvent . L'applicazione può evitare chiamate eccessive a xrCreateSpatialDiscoverySnapshotAsyncEXT per rilevare entità spaziali attendendo questo evento. Se l'applicazione crea più snapshot di rilevamento con lo stesso XrSpatialDiscoverySnapshotCreateInfoEXT tra due eventi XrEventDataSpatialDiscoveryRecommendedEXT, gli snapshot risultanti potrebbero contenere le stesse entità e, di conseguenza, la creazione di snapshot e le query di dati sarebbero inutili.

L'attesa di questo evento per creare un nuovo snapshot di rilevamento garantisce che l'applicazione non sovraccarichi il sistema con richieste di rilevamento per le quali il runtime potrebbe non restituire nuovi dati e aiuta a evitare il rischio di un utilizzo eccessivo delle risorse di sistema e di limitazioni dovute alle policy di alimentazione o termiche del dispositivo. In questo modo, si crea anche una parità tra i runtime che rilevano le entità spaziali in tempo reale con il monitoraggio in tempo reale e i runtime che forniscono le entità spaziali da uno stato registrato in precedenza (dove il runtime può mettere in coda l'evento di suggerimento di rilevamento solo una volta per ogni XrSpatialContextEXT).

Il runtime non deve mettere in coda questo evento per notificare all'applicazione le modifiche o gli aggiustamenti apportati ai dati dei componenti delle entità spaziali esistenti. L'applicazione può utilizzare xrCreateSpatialUpdateSnapshotEXT per monitorare gli aggiornamenti dei dati dei componenti per le entità spaziali di suo interesse.

Un runtime può mettere in coda un evento di suggerimento di rilevamento senza attendere che l'applicazione chiami prima xrCreateSpatialDiscoverySnapshotAsyncEXT . Ad esempio, un runtime può basare la decisione di mettere in coda l'evento di suggerimento di rilevamento sulla configurazione di XrSpatialContextEXT, sulla propria comprensione dell'ambiente intorno all'utente (rilevamento di nuove entità o perdita di quelle esistenti) o per suggerire all'applicazione una cadenza di richiesta di rilevamento appropriata in modo da non sovraccaricare le risorse di sistema. Il runtime può scegliere di non mettere mai in coda questo evento per un XrSpatialContextEXT se non vengono trovate entità nell'ambiente dell'utente per tutta la durata di quell'XrSpatialContextEXT .

Il runtime non deve mettere in coda questo evento per un determinato spatialContext finché l'applicazione non completa la sua creazione utilizzando xrCreateSpatialContextCompleteEXT .

Dopo che l'applicazione ha chiamato xrDestroySpatialContextEXT , il runtime deve non mettere in coda altri eventi di suggerimento di rilevamento per quel contesto spaziale né restituire eventi di questo tipo per quel contesto da xrPollEvent .

Utilizzo valido (implicito)

Esegui query sui dati dei componenti

La funzione xrQuerySpatialComponentDataEXT è definita come:

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

Descrizioni dei parametri

L'applicazione può utilizzare xrQuerySpatialComponentDataEXT per eseguire query sui dati dei componenti delle entità nello snapshot collegando una struttura di elenco a XrSpatialComponentDataQueryResultEXT :: next corrispondente a ogni XrSpatialComponentTypeEXT in XrSpatialComponentDataQueryConditionEXT :: componentTypes .

Se l'applicazione associa una struttura di elenco a XrSpatialComponentDataQueryResultEXT :: next che non corrisponde a nessuno dei componenti elencati in XrSpatialComponentDataQueryConditionEXT :: componentTypes , il runtime deve restituire XR_ERROR_VALIDATION_FAILURE .

L'applicazione può scegliere di allegare le strutture di elenco corrispondenti solo a un sottoinsieme di componenti elencati in XrSpatialComponentDataQueryConditionEXT :: componentTypes . L'applicazione può scegliere di omettere completamente le strutture degli elenchi se vuole solo conoscere gli ID e lo stato di monitoraggio delle entità spaziali che soddisfano queryCondition . Il runtime non deve considerare l'assenza di strutture di elenchi dalla catena XrSpatialComponentDataQueryResultEXT :: next come un errore.

Se XrEventDataReferenceSpaceChangePending è in coda e XrEventDataReferenceSpaceChangePending :: changeTime è trascorso mentre l'applicazione sta eseguendo query sui dati dei componenti da un XrSpatialSnapshotEXT , l'applicazione può utilizzare i dati sugli eventi per regolare le pose di conseguenza.

Il runtime deve compilare XrSpatialComponentDataQueryResultEXT :: entityIds solo con entità che hanno tutti i componenti specificati in XrSpatialComponentDataQueryConditionEXT :: componentTypes . Se XrSpatialComponentDataQueryConditionEXT :: componentTypeCount è 0, il runtime deve compilare queryResult con tutte le entità (e i relativi stati di monitoraggio) presenti nello snapshot. Se vengono aggiunte ulteriori condizioni di query a XrSpatialComponentDataQueryConditionEXT :: next, il runtime deve trattarle come un "AND" con la disponibilità dei tipi di componenti, ovvero il runtime deve compilare XrSpatialComponentDataQueryResultEXT ::entityIds solo con entità che soddisfano tutte le condizioni fornite. Il runtime deve compilare i dati dei componenti nelle strutture dell'elenco nello stesso ordine delle entità in XrSpatialComponentDataQueryResultEXT :: entityIds, ovvero i dati dei componenti in un determinato indice nell'array della struttura dell'elenco devono corrispondere all'entità nello stesso indice.

Se lo stato di monitoraggio di un'entità non è XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT , il runtime non deve modificare i dati nell'indice corrispondente a quell'entità nell'array contenuto nelle strutture di elenco associate a XrSpatialComponentDataQueryResultEXT .

Utilizzo valido (implicito)

Codici di risposta

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • 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

Ad esempio, l'applicazione crea un XrSpatialSnapshotEXT che contiene 5 entità, dove:

  • Le entità 1 e 2 hanno i componenti XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT e XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT
  • Le entità 3 e 4 hanno i componenti XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT e XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT
  • L'entità 5 ha i componenti XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT e XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT .

XrSpatialEntityIdEXT

XrSpatialEntityIdEXT

1

1

2

2

3

3

4

4

5

5

Bounded2D

Bounded2D

Sì

Sì

Sì

Sì

No

No

No

No

Sì

Sì

Genitore

Genitore

Sì

Sì

Sì

Sì

No

No

No

No

No

No

Mesh3D

Mesh3D

No

No

No

No

Sì

Sì

Sì

Sì

Sì

Sì

Bounded3D

Bounded3D

No

No

No

No

Sì

Sì

Sì

Sì

No

No Text is not SVG - cannot display

Figura 20. Snapshot di esempio

xrQuerySpatialComponentDataEXT nell'istantanea precedente con XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT elencato nella condizione della query restituirà le entità n. 1, n. 2 e n. 5 all'applicazione e l'applicazione può allegare un array di XrSpatialBounded2DDataEXT come parte della struttura XrSpatialComponentBounded2DListEXT alla catena successiva di XrSpatialComponentDataQueryResultEXT per ottenere i dati bounded2D.

XrSpatialEntityIdEXT

XrSpatialEntityIdEXT

1

1

2

2

5

5

Bounded2D

Bounded2D

Dati per entityId n. 1

Dati per entit…

Dati per entityId n. 2

Dati per entit…

Dati per entityId n. 5

Dati per entit…

entityIds

entityIds

avanti

avanti

XrSpatialComponent
DataQueryResultEXT

XrSpatialComponent
Dat…

bounds

bounds

XrSpatialComponent
Bounded2DListEXT

XrSpatialComponent
Bou… Il testo non è SVG, impossibile visualizzarlo

Figura 21. Esempio di risultato della query

xrQuerySpatialComponentDataEXT nell'istantanea precedente con i componenti XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT e XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT elencati nella condizione della query restituirà l'entità n. 3 e n. 4 all'applicazione e l'applicazione può collegare array di XrBoxf e XrSpatialMeshDataEXT rispettivamente come parte delle strutture XrSpatialComponentBounded3DListEXT e XrSpatialComponentMesh3DListEXT alla catena successiva di XrSpatialComponentDataQueryResultEXT per ottenere i dati dei componenti.

XrSpatialEntityIdEXT

XrSpatialEntityIdEXT

3

3

4

4

Bounded3D

Bounded3D

Dati per entityId n. 3

Dati per entit…

Dati per entityId n. 4

Dati per entit…

Mesh3D

Mesh3D

Dati per entityId n. 3

Dati per entit…

Dati per entityId n. 4

Dati per entit…

entityIds

entityIds

avanti

avanti

XrSpatialComponent
DataQueryResultEXT

XrSpatialComponent
Da…

bounds

bounds

avanti

avanti

XrSpatialComponent
Bounded3DListEXT

XrSpatialComponent
Bo…

XrSpatialComponent
Mesh3DListEXT

XrSpatialComponent
Me…

mesh

meshes Text is not SVG - cannot display

Figura 22. Esempio di risultato della query

La struttura XrSpatialComponentDataQueryConditionEXT è definita come:

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

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture.
  • componentTypeCount è un uint32_t che descrive il conteggio degli elementi nell'array componentTypes.
  • componentTypes è un array di XrSpatialComponentTypeEXT per cui ottenere i dati dallo snapshot.

Utilizzo valido (implicito)

La struttura XrSpatialComponentDataQueryResultEXT è definita come:

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

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture.
  • entityIdCapacityInput è la capacità dell'array entityIds o 0 per indicare una richiesta di recupero della capacità richiesta.
  • entityIdCountOutput è il numero di XrSpatialEntityIdEXT in entityIds o la capacità richiesta nel caso in cui entityIdCapacityInput non sia sufficiente.
  • entityIds è un array di XrSpatialEntityIdEXT . Può essere NULL se entityIdCapacityInput è 0.
  • entityStateCapacityInput è la capacità dell'array entityStates o 0 per indicare una richiesta di recupero della capacità richiesta.
  • entityStateCountOutput è il numero di XrSpatialEntityTrackingStateEXT in entityStates o la capacità richiesta nel caso in cui entityStateCapacityInput non sia sufficiente. Questo valore deve essere sempre uguale a entityIdCountOutput .
  • entityStates è un array di XrSpatialEntityTrackingStateEXT . Può essere NULL se entityStateCapacityInput è 0.
  • Consulta la sezione Parametri della dimensione del buffer per una descrizione dettagliata del recupero della dimensione entityIds richiesta.

Un'applicazione può utilizzare entityIds con xrCreateSpatialEntityFromIdEXT per creare handle XrSpatialEntityEXT per le entità per cui vuole ricevere aggiornamenti regolari. L'applicazione può quindi utilizzare questi handle XrSpatialEntityEXT con xrCreateSpatialUpdateSnapshotEXT per creare uno snapshot di aggiornamento che contenga i dati più recenti noti del runtime dei componenti per le entità fornite.

Utilizzo valido (implicito)

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

XrSpatialEntityTrackingStateEXT enumera i possibili stati di monitoraggio delle entità spaziali:

Gli enum hanno i seguenti significati:

Descrizione enum

XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT

Il runtime ha interrotto il monitoraggio di questa entità e non lo riprenderà mai.

XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT

Il runtime ha messo in pausa il monitoraggio di questa entità, ma potrebbe riprenderlo in futuro.

XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT

Il runtime sta attualmente monitorando questa entità e i dati dei suoi componenti sono validi.

MONITORAGGIO

IN PAUSA

INTERROTTO

Figura 23. XrSpatialEntityTrackingStateEXT

  • Il runtime può modificare lo stato dell'entità spaziale da XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT a XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT se sospende il monitoraggio dell'entità spaziale, ma ha la possibilità di riprenderlo in futuro. Alcuni esempi di casi in cui il runtime potrebbe farlo includono (ma non sono limitati a) se l'applicazione perde lo stato attivo dell'input, se l'entità spaziale specificata è troppo lontana dall'utente per essere monitorata con precisione o se sono presenti troppe entità monitorate e il runtime vuole ridurre il costo del monitoraggio. XrSpatialEntityTrackingStateEXT aiuta l'applicazione a isolarsi dalle diverse policy di tracciamento di ogni runtime.
  • Il runtime può modificare lo stato di un'entità da XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT a XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT o XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT .
  • Il runtime deve modificare lo stato dell'entità spaziale da XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT o XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT a XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT se l'entità spaziale viene persa e il relativo monitoraggio non verrà mai recuperato o ripreso. Un esempio di questo caso è se il dispositivo perde il tracciamento, riavvia la sessione di tracciamento, ma non è in grado di rilocarsi nel suo ambiente e, di conseguenza, tratta le entità scoperte di questa sessione di tracciamento come nuove entità.
  • Una volta impostato lo stato di monitoraggio di un'entità su XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT , il runtime non deve mai modificarlo in un altro stato.
  • Quando esegue una query sui dati dei componenti di un'entità spaziale utilizzando xrQuerySpatialComponentDataEXT , il runtime deve impostare dati validi nei contenuti dei buffer forniti dall'applicazione nella catena successiva di XrSpatialComponentDataQueryResultEXT se lo stato dell'entità è XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT . Se lo stato dell'entità è XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT o XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT , il runtime non deve modificare i contenuti dei buffer.

Idiom a due chiamate per i dati dei componenti

La struttura XrSpatialBufferEXT è definita come:

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

Descrizioni dei membri

  • bufferId XrSpatialBufferIdEXT dei dati del buffer.
  • bufferType è il XrSpatialBufferTypeEXT per indicare il tipo di dati in bufferId . L'applicazione può utilizzare bufferType per determinare quale funzione utilizzare per recuperare i dati effettivi del buffer.

Alcuni componenti spaziali hanno dati di dimensioni variabili e pertanto richiedono l'utilizzo dell'idioma a due chiamate per recuperare i dati. In questi casi, la struttura dei dati del componente spaziale fornisce un XrSpatialBufferEXT per ogni buffer di dimensioni variabili necessario nei dati del componente.

Per lo stesso bufferId , il runtime deve fornire gli stessi dati da una query sui dati dei componenti a un'altra, anche da uno snapshot all'altro. Un bufferId diverso tra le chiamate di query dei dati dei componenti indica all'applicazione che i dati di quel componente potrebbero essere cambiati.

Utilizzo valido (implicito)

XR_DEFINE_ATOM(XrSpatialBufferIdEXT)

XrSpatialBufferIdEXT viene utilizzato per rappresentare qualsiasi tipo di dati di dimensioni variabili per un componente spaziale.

Il runtime deve mantenere XrSpatialBufferIdEXT e i relativi dati in memoria almeno per il ciclo di vita di XrSpatialSnapshotEXT che lo contiene. Il runtime può conservare XrSpatialBufferIdEXT e i relativi dati in memoria per un periodo più lungo rispetto al ciclo di vita di XrSpatialSnapshotEXT per restituire lo stesso ID come parte degli snapshot creati in un secondo momento dall'applicazione. Per lo stesso XrSpatialBufferIdEXT , il runtime deve restituire sempre gli stessi dati tramite la funzione xrGetSpatialBuffer* appropriata.

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;

L'enumerazione XrSpatialBufferTypeEXT identifica i diversi tipi di dati del buffer rappresentato XrSpatialBufferIdEXT .

Descrizioni degli enumeranti

La funzione xrGetSpatialBufferStringEXT è definita come segue:

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

Descrizioni dei parametri

  • snapshot è un handle per un XrSpatialSnapshotEXT .
  • info contiene le informazioni sul buffer su cui eseguire la query.
  • bufferCapacityInput è la capacità dell'array o 0 per indicare una richiesta di recupero della capacità richiesta.
  • bufferCountOutput è il numero di caratteri o la capacità richiesta nel caso in cui bufferCapacityInput non sia sufficiente.
  • buffer è un array di char . Può essere NULL se bufferCapacityInput è 0.
  • Consulta la sezione Parametri della dimensione del buffer per una descrizione dettagliata del recupero della dimensione buffer richiesta.

L'applicazione può ottenere i dati per un XrSpatialBufferEXT fornito da un componente, dove XrSpatialBufferEXT :: bufferType è XR_SPATIAL_BUFFER_TYPE_STRING_EXT utilizzando xrGetSpatialBufferStringEXT .

Il runtime deve restituire XR_ERROR_VALIDATION_FAILURE se XrSpatialBufferTypeEXT per XrSpatialBufferGetInfoEXT :: bufferId non è XR_SPATIAL_BUFFER_TYPE_STRING_EXT .

Il runtime deve restituire XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT se XrSpatialBufferGetInfoEXT :: bufferId non appartiene a snapshot .

buffer compilato dal runtime deve essere una stringa UTF-8 con terminazione null.

Utilizzo valido (implicito)

  • L'estensione XR_EXT_spatial_entity deve essere attivata prima di chiamare xrGetSpatialBufferStringEXT
  • snapshot deve essere un handle XrSpatialSnapshotEXT valido
  • info deve essere un puntatore a una struttura XrSpatialBufferGetInfoEXT valida
  • bufferCountOutput deve essere un puntatore a un valore uint32_t
  • Se bufferCapacityInput non è 0 , buffer deve essere un puntatore a un array di valori char bufferCapacityInput

Codici di risposta

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • 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

La funzione xrGetSpatialBufferUint8EXT è definita come:

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

Descrizioni dei parametri

  • snapshot è un handle per un XrSpatialSnapshotEXT .
  • info contiene le informazioni sul buffer su cui eseguire la query.
  • bufferCapacityInput è la capacità dell'array o 0 per indicare una richiesta di recupero della capacità richiesta.
  • bufferCountOutput è il numero di elementi nell'array buffer o la capacità richiesta nel caso in cui bufferCapacityInput non sia sufficiente.
  • buffer è un array di uint8_t . Può essere NULL se bufferCapacityInput è 0.
  • Consulta la sezione Parametri della dimensione del buffer per una descrizione dettagliata del recupero della dimensione buffer richiesta.

L'applicazione può ottenere i dati per un XrSpatialBufferEXT fornito da un componente, dove XrSpatialBufferEXT :: bufferType è XR_SPATIAL_BUFFER_TYPE_UINT8_EXT utilizzando xrGetSpatialBufferUint8EXT .

Il runtime deve restituire XR_ERROR_VALIDATION_FAILURE se XrSpatialBufferTypeEXT per XrSpatialBufferGetInfoEXT :: bufferId non è XR_SPATIAL_BUFFER_TYPE_UINT8_EXT .

Il runtime deve restituire XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT se XrSpatialBufferGetInfoEXT :: bufferId non appartiene a snapshot .

Utilizzo valido (implicito)

  • L'estensione XR_EXT_spatial_entity deve essere abilitata prima di chiamare xrGetSpatialBufferUint8EXT
  • snapshot deve essere un handle XrSpatialSnapshotEXT valido
  • info deve essere un puntatore a una struttura XrSpatialBufferGetInfoEXT valida
  • bufferCountOutput deve essere un puntatore a un valore uint32_t
  • Se bufferCapacityInput non è 0 , buffer deve essere un puntatore a un array di valori bufferCapacityInput uint8_t

Codici di risposta

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • 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

La funzione xrGetSpatialBufferUint16EXT è definita come:

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

Descrizioni dei parametri

  • snapshot è un handle per un XrSpatialSnapshotEXT .
  • info contiene le informazioni sul buffer su cui eseguire la query.
  • bufferCapacityInput è la capacità dell'array o 0 per indicare una richiesta di recupero della capacità richiesta.
  • bufferCountOutput è il numero di elementi nell'array buffer o la capacità richiesta nel caso in cui bufferCapacityInput non sia sufficiente.
  • buffer è un array di uint16_t . Può essere NULL se bufferCapacityInput è 0.
  • Consulta la sezione Parametri della dimensione del buffer per una descrizione dettagliata del recupero della dimensione buffer richiesta.

L'applicazione può ottenere i dati per un XrSpatialBufferEXT fornito da un componente, dove XrSpatialBufferEXT :: bufferType è XR_SPATIAL_BUFFER_TYPE_UINT16_EXT utilizzando xrGetSpatialBufferUint16EXT .

Il runtime deve restituire XR_ERROR_VALIDATION_FAILURE se XrSpatialBufferTypeEXT per XrSpatialBufferGetInfoEXT :: bufferId non è XR_SPATIAL_BUFFER_TYPE_UINT16_EXT .

Il runtime deve restituire XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT se XrSpatialBufferGetInfoEXT :: bufferId non appartiene a snapshot .

Utilizzo valido (implicito)

  • L'estensione XR_EXT_spatial_entity deve essere attivata prima di chiamare xrGetSpatialBufferUint16EXT
  • snapshot deve essere un handle XrSpatialSnapshotEXT valido
  • info deve essere un puntatore a una struttura XrSpatialBufferGetInfoEXT valida
  • bufferCountOutput deve essere un puntatore a un valore uint32_t
  • Se bufferCapacityInput non è 0 , buffer deve essere un puntatore a un array di valori bufferCapacityInput uint16_t

Codici di risposta

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • 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

La funzione xrGetSpatialBufferUint32EXT è definita come:

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

Descrizioni dei parametri

  • snapshot è un handle per un XrSpatialSnapshotEXT .
  • info contiene le informazioni sul buffer su cui eseguire la query.
  • bufferCapacityInput è la capacità dell'array o 0 per indicare una richiesta di recupero della capacità richiesta.
  • bufferCountOutput è il numero di elementi nell'array buffer o la capacità richiesta nel caso in cui bufferCapacityInput non sia sufficiente.
  • buffer è un array di uint32_t . Può essere NULL se bufferCapacityInput è 0.
  • Consulta la sezione Parametri della dimensione del buffer per una descrizione dettagliata del recupero della dimensione buffer richiesta.

L'applicazione può ottenere i dati per un XrSpatialBufferEXT fornito da un componente, dove XrSpatialBufferEXT :: bufferType è XR_SPATIAL_BUFFER_TYPE_UINT32_EXT utilizzando xrGetSpatialBufferUint32EXT .

Il runtime deve restituire XR_ERROR_VALIDATION_FAILURE se XrSpatialBufferTypeEXT per XrSpatialBufferGetInfoEXT :: bufferId non è XR_SPATIAL_BUFFER_TYPE_UINT32_EXT .

Il runtime deve restituire XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT se XrSpatialBufferGetInfoEXT :: bufferId non appartiene a snapshot .

Utilizzo valido (implicito)

  • L'estensione XR_EXT_spatial_entity deve essere attivata prima di chiamare xrGetSpatialBufferUint32EXT
  • snapshot deve essere un handle XrSpatialSnapshotEXT valido
  • info deve essere un puntatore a una struttura XrSpatialBufferGetInfoEXT valida
  • bufferCountOutput deve essere un puntatore a un valore uint32_t
  • Se bufferCapacityInput non è 0 , buffer deve essere un puntatore a un array di valori bufferCapacityInput uint32_t

Codici di risposta

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • 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

La funzione xrGetSpatialBufferFloatEXT è definita come:

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

Descrizioni dei parametri

  • snapshot è un handle per un XrSpatialSnapshotEXT .
  • info contiene le informazioni sul buffer su cui eseguire la query.
  • bufferCapacityInput è la capacità dell'array o 0 per indicare una richiesta di recupero della capacità richiesta.
  • bufferCountOutput è il numero di elementi nell'array buffer o la capacità richiesta nel caso in cui bufferCapacityInput non sia sufficiente.
  • buffer è un array di float . Può essere NULL se bufferCapacityInput è 0.
  • Consulta la sezione Parametri della dimensione del buffer per una descrizione dettagliata del recupero della dimensione buffer richiesta.

L'applicazione può ottenere i dati per un XrSpatialBufferEXT fornito da un componente, dove XrSpatialBufferEXT :: bufferType è XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT utilizzando xrGetSpatialBufferFloatEXT .

Il runtime deve restituire XR_ERROR_VALIDATION_FAILURE se XrSpatialBufferTypeEXT per XrSpatialBufferGetInfoEXT :: bufferId non è XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT .

Il runtime deve restituire XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT se XrSpatialBufferGetInfoEXT :: bufferId non appartiene a snapshot .

Utilizzo valido (implicito)

  • L'estensione XR_EXT_spatial_entity deve essere attivata prima di chiamare xrGetSpatialBufferFloatEXT
  • snapshot deve essere un handle XrSpatialSnapshotEXT valido
  • info deve essere un puntatore a una struttura XrSpatialBufferGetInfoEXT valida
  • bufferCountOutput deve essere un puntatore a un valore uint32_t
  • Se bufferCapacityInput non è 0 , buffer deve essere un puntatore a un array di valori bufferCapacityInput float

Codici di risposta

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • 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

La funzione xrGetSpatialBufferVector2fEXT è definita come:

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

Descrizioni dei parametri

  • snapshot è un handle per un XrSpatialSnapshotEXT .
  • info contiene le informazioni sul buffer su cui eseguire la query.
  • bufferCapacityInput è la capacità dell'array o 0 per indicare una richiesta di recupero della capacità richiesta.
  • bufferCountOutput è il numero di elementi nell'array buffer o la capacità richiesta nel caso in cui bufferCapacityInput non sia sufficiente.
  • buffer è un array di XrVector2f . Può essere NULL se bufferCapacityInput è 0.
  • Consulta la sezione Parametri della dimensione del buffer per una descrizione dettagliata del recupero della dimensione buffer richiesta.

L'applicazione può ottenere i dati per un XrSpatialBufferEXT fornito da un componente, dove XrSpatialBufferEXT :: bufferType è XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT utilizzando xrGetSpatialBufferVector2fEXT .

Il runtime deve restituire XR_ERROR_VALIDATION_FAILURE se XrSpatialBufferTypeEXT per XrSpatialBufferGetInfoEXT :: bufferId non è XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT .

Il runtime deve restituire XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT se XrSpatialBufferGetInfoEXT :: bufferId non appartiene a snapshot .

Utilizzo valido (implicito)

  • L'estensione XR_EXT_spatial_entity deve essere abilitata prima di chiamare xrGetSpatialBufferVector2fEXT
  • snapshot deve essere un handle XrSpatialSnapshotEXT valido
  • info deve essere un puntatore a una struttura XrSpatialBufferGetInfoEXT valida
  • bufferCountOutput deve essere un puntatore a un valore uint32_t
  • Se bufferCapacityInput non è 0 , buffer deve essere un puntatore a un array di bufferCapacityInput strutture XrVector2f

Codici di risposta

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • 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

La funzione xrGetSpatialBufferVector3fEXT è definita come:

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

Descrizioni dei parametri

  • snapshot è un handle per un XrSpatialSnapshotEXT .
  • info contiene le informazioni sul buffer su cui eseguire la query.
  • bufferCapacityInput è la capacità dell'array o 0 per indicare una richiesta di recupero della capacità richiesta.
  • bufferCountOutput è il numero di elementi nell'array buffer o la capacità richiesta nel caso in cui bufferCapacityInput non sia sufficiente.
  • buffer è un array di XrVector3f . Può essere NULL se bufferCapacityInput è 0.
  • Consulta la sezione Parametri della dimensione del buffer per una descrizione dettagliata del recupero della dimensione buffer richiesta.

L'applicazione può ottenere i dati per un XrSpatialBufferEXT fornito da un componente, dove XrSpatialBufferEXT :: bufferType è XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT utilizzando xrGetSpatialBufferVector3fEXT .

Il runtime deve restituire XR_ERROR_VALIDATION_FAILURE se XrSpatialBufferTypeEXT per XrSpatialBufferGetInfoEXT :: bufferId non è XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT .

Il runtime deve restituire XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT se XrSpatialBufferGetInfoEXT :: bufferId non appartiene a snapshot .

Utilizzo valido (implicito)

  • L'estensione XR_EXT_spatial_entity deve essere attivata prima di chiamare xrGetSpatialBufferVector3fEXT
  • snapshot deve essere un handle XrSpatialSnapshotEXT valido
  • info deve essere un puntatore a una struttura XrSpatialBufferGetInfoEXT valida
  • bufferCountOutput deve essere un puntatore a un valore uint32_t
  • Se bufferCapacityInput non è 0 , buffer deve essere un puntatore a un array di strutture bufferCapacityInput XrVector3f

Codici di risposta

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • 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

La struttura XrSpatialBufferGetInfoEXT è definita come:

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

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture.
  • bufferId un XrSpatialBufferIdEXT per il buffer di cui recuperare i dati.

Utilizzo valido (implicito)

#define XR_NULL_SPATIAL_BUFFER_ID_EXT 0

XR_NULL_SPATIAL_BUFFER_ID_EXT è un valore riservato che rappresenta un XrSpatialBufferIdEXT non valido. Può essere passato alle funzioni API e restituito da queste solo se espressamente consentito.

Crea snapshot di aggiornamento

La funzione xrCreateSpatialUpdateSnapshotEXT è definita come:

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

Descrizioni dei parametri

L'applicazione può utilizzare xrCreateSpatialUpdateSnapshotEXT per creare uno snapshot e ottenere i dati dei componenti più recenti per entità specifiche, come noto al runtime. Le applicazioni possono fornire gli handle XrSpatialEntityEXT e i tipi di componenti di loro interesse durante la creazione dello snapshot.

L'applicazione può utilizzare XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes per filtrare l'elenco dei componenti i cui dati devono essere inclusi nello snapshot. Se l'applicazione fornisce un elenco valido di tipi di componenti spaziali in XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes , il runtime deve includere nello snapshot solo le entità spaziali che hanno almeno uno dei componenti forniti in XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes . Inoltre, il runtime deve includere solo i dati relativi ai componenti nello snapshot.

Il runtime deve restituire XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT se uno dei XrSpatialComponentTypeEXT in XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes non è abilitato per le funzionalità spaziali passate a XrSpatialContextCreateInfoEXT :: capabilityConfigs durante la creazione di spatialContext .

Se l'applicazione non fornisce un elenco di tipi di componenti spaziali in XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes , il runtime deve includere tutte le entità spaziali elencate in XrSpatialUpdateSnapshotCreateInfoEXT :: entities nello snapshot e deve includere i dati per tutti i componenti abilitati delle funzionalità configurate per spatialContext .

Il runtime non deve includere entità spaziali non elencate in XrSpatialUpdateSnapshotCreateInfoEXT :: entities in snapshot .

L'applicazione può creare un numero qualsiasi di snapshot, ma deve tenere conto della memoria allocata per ogni nuovo snapshot e deve eliminare gli snapshot quando non sono più necessari.

Utilizzo valido (implicito)

Codici di risposta

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • 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

La struttura XrSpatialUpdateSnapshotCreateInfoEXT è definita come:

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;

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Nessuna struttura di questo tipo è definita in OpenXR di base o in questa estensione.
  • entityCount è un uint32_t che descrive il conteggio degli elementi nell'array entities.
  • entities è un array di XrSpatialEntityEXT per cui il runtime deve includere i dati del componente nello snapshot.
  • componentTypeCount è un uint32_t che descrive il conteggio degli elementi nell'array componentTypes.
  • componentTypes è un array di XrSpatialComponentTypeEXT per cui il runtime deve includere i dati nello snapshot.
  • baseSpace è l'XrSpace rispetto al quale verranno posizionate tutte le posizioni dell'aggiornamento XrSpatialSnapshotEXT.
  • time è l'oggetto XrTime in cui si troveranno tutte le posizioni dell'aggiornamento XrSpatialSnapshotEXT.

Utilizzo valido (implicito)

  • L'estensione XR_EXT_spatial_entity deve essere attivata prima di utilizzare XrSpatialUpdateSnapshotCreateInfoEXT
  • type deve essere XR_TYPE_SPATIAL_UPDATE_SNAPSHOT_CREATE_INFO_EXT
  • next deve essere NULL o un puntatore valido alla struttura successiva in una catena di strutture
  • entities deve essere un puntatore a un array di entityCount handle XrSpatialEntityEXT validi
  • Se componentTypeCount non è 0 , componentTypes deve essere un puntatore a un array di componentTypeCount valori XrSpatialComponentTypeEXT validi
  • baseSpace deve essere un handle XrSpace valido
  • Il parametro entityCount deve essere maggiore di 0
  • Sia baseSpace che gli elementi di entities devono essere stati creati, allocati o recuperati dalla stessa XrSession

Elimina snapshot

La funzione xrDestroySpatialSnapshotEXT è definita come:

XrResult xrDestroySpatialSnapshotEXT(
    XrSpatialSnapshotEXT                        snapshot);

Descrizioni dei parametri

L'applicazione può chiamare xrDestroySpatialSnapshotEXT per eliminare l'handle XrSpatialSnapshotEXT e le risorse associate.

Utilizzo valido (implicito)

Thread safety

  • L'accesso a snapshot e a qualsiasi handle secondario deve essere sincronizzato esternamente

Codici di risposta

Operazione riuscita

  • XR_SUCCESS

Errore

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Componenti comuni

2D delimitato

Dati dei componenti

La struttura XrSpatialBounded2DDataEXT è definita come:

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

Descrizioni dei membri

  • center è un XrPosef che definisce il centro geometrico del componente 2D delimitato.
  • extents sono le estensioni del componente 2D delimitato lungo l'asse X (extents.width), l'asse Y (extents.height), centrato su center .

extents di XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT si riferiscono alle dimensioni dell'entità nel piano x-y del sistema di coordinate del piano. Un piano con una posizione di {0, 0, 0}, una rotazione di {0, 0, 0, 1} (nessuna rotazione) e un'estensione di {1, 1} si riferisce a un piano di 1 metro x 1 metro centrato su {0, 0, 0} con il vettore normale della superficie anteriore rivolto verso la direzione +Z nello spazio del componente.

X X Y Y Z Z Altezza Altezza Y Y Z Z X X Piano verticale Piano verticale Piano orizzontale Piano orizzontale Larghezza Larghezza Larghezza Larghezza Altezza Altezza

Figura 24. Sistema di coordinate dei componenti Bounded2D

Nota

OpenXR utilizza un piano X-Y con +Z come normale del piano, ma altre API potrebbero utilizzare un piano X-Z con +Y come normale del piano. Il piano X-Y può essere convertito in un piano X-Z ruotando di -π/2 radianti attorno all'asse +X.

Utilizzo valido (implicito)

Struttura dell'elenco dei componenti per eseguire query sui dati

La struttura XrSpatialComponentBounded2DListEXT è definita come:

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

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Nessuna struttura di questo tipo è definita in OpenXR di base o in questa estensione.
  • boundCount è un uint32_t che descrive il conteggio degli elementi nell'array bounds.
  • bounds è un array di XrSpatialBounded2DDataEXT .

Il runtime deve restituire XR_ERROR_VALIDATION_FAILURE da xrQuerySpatialComponentDataEXT se XrSpatialComponentBounded2DListEXT si trova nella catena successiva di XrSpatialComponentDataQueryResultEXT :: next, ma XrSpatialComponentDataQueryConditionEXT ::componentTypeCount non è zero e XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT non è incluso in XrSpatialComponentDataQueryConditionEXT :: componentTypes .

Il runtime deve restituire XR_ERROR_SIZE_INSUFFICIENT da xrQuerySpatialComponentDataEXT se boundCount è inferiore a XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

Se xrQuerySpatialComponentDataEXT :: snapshot è stato creato da xrCreateSpatialDiscoverySnapshotCompleteEXT , il runtime deve fornire XrSpatialBounded2DDataEXT :: center in XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace e XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time .

Se xrQuerySpatialComponentDataEXT :: snapshot è stato creato da xrCreateSpatialUpdateSnapshotEXT , il runtime deve fornire XrSpatialBounded2DDataEXT :: center in XrSpatialUpdateSnapshotCreateInfoEXT :: baseSpace e XrSpatialUpdateSnapshotCreateInfoEXT :: time .

Utilizzo valido (implicito)

Configurazione

Se XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT è enumerato in XrSpatialCapabilityComponentTypesEXT :: componentTypes per una funzionalità, l'applicazione può attivarla includendo il valore dell'enum nell'elenco XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents. Questo componente non richiede alcuna configurazione speciale per essere incluso nella catena successiva di XrSpatialCapabilityConfigurationBaseHeaderEXT .

3D delimitato

Dati dei componenti

XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT utilizza XrBoxf per i suoi dati.

Struttura dell'elenco dei componenti per eseguire query sui dati

La struttura XrSpatialComponentBounded3DListEXT è definita come:

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

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Nessuna struttura di questo tipo è definita in OpenXR di base o in questa estensione.
  • boundCount è un uint32_t che descrive il conteggio degli elementi nell'array bounds.
  • bounds è un array di XrBoxf .

Il runtime deve restituire XR_ERROR_VALIDATION_FAILURE da xrQuerySpatialComponentDataEXT se XrSpatialComponentBounded3DListEXT si trova nella catena successiva di XrSpatialComponentDataQueryResultEXT :: next, ma XrSpatialComponentDataQueryConditionEXT ::componentTypeCount non è zero e XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT non è incluso in XrSpatialComponentDataQueryConditionEXT :: componentTypes .

Il runtime deve restituire XR_ERROR_SIZE_INSUFFICIENT da xrQuerySpatialComponentDataEXT se boundCount è inferiore a XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

Se xrQuerySpatialComponentDataEXT :: snapshot è stato creato da xrCreateSpatialDiscoverySnapshotCompleteEXT , il runtime deve fornire XrBoxf :: center in XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace in XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time .

Se xrQuerySpatialComponentDataEXT :: snapshot è stato creato da xrCreateSpatialUpdateSnapshotEXT , il runtime deve fornire XrBoxf :: center in XrSpatialUpdateSnapshotCreateInfoEXT :: baseSpace in XrSpatialUpdateSnapshotCreateInfoEXT :: time .

Utilizzo valido (implicito)

Configurazione

Se XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT è enumerato in XrSpatialCapabilityComponentTypesEXT :: componentTypes per una funzionalità, l'applicazione può attivarla includendo l'enum nell'elenco XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents. Questo componente non richiede alcuna configurazione speciale per essere incluso nella catena successiva di XrSpatialCapabilityConfigurationBaseHeaderEXT .

Genitore

Dati dei componenti

XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT utilizza XrSpatialEntityIdEXT per i suoi dati.

Struttura dell'elenco dei componenti per eseguire query sui dati

La struttura XrSpatialComponentParentListEXT è definita come:

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

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Nessuna struttura di questo tipo è definita in OpenXR di base o in questa estensione.
  • parentCount è un uint32_t che descrive il conteggio degli elementi nell'array parents.
  • parents è un array di XrSpatialEntityIdEXT .

Il runtime deve restituire XR_ERROR_VALIDATION_FAILURE da xrQuerySpatialComponentDataEXT se XrSpatialComponentParentListEXT si trova nella catena successiva di XrSpatialComponentDataQueryResultEXT :: next, ma XrSpatialComponentDataQueryConditionEXT ::componentTypeCount non è zero e XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT non è incluso in XrSpatialComponentDataQueryConditionEXT :: componentTypes .

Il runtime deve restituire XR_ERROR_SIZE_INSUFFICIENT da xrQuerySpatialComponentDataEXT se parentCount è inferiore a XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

Utilizzo valido (implicito)

  • L'estensione XR_EXT_spatial_entity deve essere attivata prima di utilizzare XrSpatialComponentParentListEXT
  • type deve essere XR_TYPE_SPATIAL_COMPONENT_PARENT_LIST_EXT
  • next deve essere NULL o un puntatore valido alla struttura successiva in una catena di strutture
  • parents deve essere un puntatore a un array di valori parentCount XrSpatialEntityIdEXT
  • Il parametro parentCount deve essere maggiore di 0
Configurazione

Se XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT è enumerato in XrSpatialCapabilityComponentTypesEXT :: componentTypes per una funzionalità, l'applicazione può attivarla includendo l'enum nell'elenco XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents. Questo componente non richiede alcuna configurazione speciale per essere incluso nella catena successiva di XrSpatialCapabilityConfigurationBaseHeaderEXT .

Mesh 3D

Dati dei componenti

La struttura XrSpatialMeshDataEXT è definita come:

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

Descrizioni dei membri

  • origin è un XrPosef che definisce l'origine della mesh. Tutti i vertici della mesh devono essere relativi a questa origine.
  • vertexBuffer è un XrSpatialBufferEXT che fornisce l'ID di un buffer che rappresenta il buffer dei vertici dell'entità su cui si trova questo componente. La posizione dei vertici deve essere relativa a origin .
  • indexBuffer è un XrSpatialBufferEXT che fornisce l'ID di un buffer che rappresenta un array di indici di triangoli, specificando gli indici dei vertici della mesh in vertexBuffer . Gli indici dei triangoli devono essere restituiti in senso antiorario e tre indici indicano un triangolo.

Il tipo di componente che utilizza XrSpatialMeshDataEXT deve specificare XrSpatialBufferTypeEXT di vertexBuffer e indexBuffer .

Utilizzo valido (implicito)

Struttura dell'elenco dei componenti per eseguire query sui dati

La struttura XrSpatialComponentMesh3DListEXT è definita come:

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

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture.
  • meshCount è un uint32_t che descrive il conteggio degli elementi nell'array meshes.
  • meshes è un array di XrSpatialMeshDataEXT .

L'applicazione può eseguire query sul componente mesh 3D delle entità spaziali in un XrSpatialSnapshotEXT aggiungendo XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT in XrSpatialComponentDataQueryConditionEXT :: componentTypes e aggiungendo XrSpatialComponentMesh3DListEXT alla catena di puntatori successiva di XrSpatialComponentDataQueryResultEXT .

Il runtime deve restituire XR_ERROR_VALIDATION_FAILURE da xrQuerySpatialComponentDataEXT se XrSpatialComponentMesh3DListEXT si trova nella catena successiva di XrSpatialComponentDataQueryResultEXT :: next, ma XrSpatialComponentDataQueryConditionEXT ::componentTypeCount non è zero e XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT non è incluso in XrSpatialComponentDataQueryConditionEXT :: componentTypes .

Il runtime deve restituire XR_ERROR_SIZE_INSUFFICIENT da xrQuerySpatialComponentDataEXT se meshCount è inferiore a XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

Per XrSpatialMeshDataEXT compilato dal runtime nell'array meshes, XrSpatialBufferEXT :: bufferType per XrSpatialMeshDataEXT :: vertexBuffer deve essere XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT e XrSpatialBufferEXT :: bufferType per XrSpatialMeshDataEXT :: indexBuffer deve essere XR_SPATIAL_BUFFER_TYPE_UINT32_EXT .

Utilizzo valido (implicito)

Configurazione

Se XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT è enumerato in XrSpatialCapabilityComponentTypesEXT :: componentTypes per una funzionalità, l'applicazione può attivarla includendo l'enum nell'elenco XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents della struttura derivata XrSpatialCapabilityConfigurationBaseHeaderEXT della funzionalità che supporta questo componente.

Questo componente non richiede alcuna configurazione speciale per essere incluso nella catena successiva di XrSpatialCapabilityConfigurationBaseHeaderEXT .

Filtri dello stato di monitoraggio

La struttura XrSpatialFilterTrackingStateEXT è definita come:

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

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture.
  • trackingState è l'XrSpatialEntityTrackingStateEXT per cui l'applicazione vuole applicare il filtro.

L'applicazione può utilizzare XrSpatialFilterTrackingStateEXT nella catena successiva di XrSpatialDiscoverySnapshotCreateInfoEXT per limitare il rilevamento solo alle entità il cui stato di monitoraggio è trackingState .

L'applicazione può utilizzare XrSpatialFilterTrackingStateEXT nella catena successiva di XrSpatialComponentDataQueryConditionEXT per limitare l'ambito della query sui dati dei componenti da uno snapshot solo alle entità il cui stato di monitoraggio è trackingState .

Utilizzo valido (implicito)

Esempio di codice

Utilizzo delle applicazioni

Le applicazioni in genere utilizzano l'estensione dell'entità spaziale nel seguente pattern:

Scopri le entità spaziali ed esegui query sui dati dei componenti

Il seguente codice di esempio mostra come rilevare le entità spaziali per la funzionalità "Foo" ed eseguire query sui relativi dati dei componenti.

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

Esegui query sui dati del buffer

Il seguente codice di esempio mostra come ottenere i dati di un componente che fornisce un 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.
  }
}

Linee guida per le estensioni

  • Se un'estensione definisce un nuovo XrSpatialComponentTypeEXT che fornisce dati aggiuntivi su un'entità spaziale,

  • Le estensioni possono definire strutture che estendono XrSpatialDiscoverySnapshotCreateInfoEXT per fornire filtri aggiuntivi per il rilevamento. I filtri per la creazione dello snapshot non devono influire sulla configurazione del contesto spaziale, ma devono essere utilizzati per fornire suggerimenti al runtime su quali entità e dati devono essere inclusi nello snapshot, come monitorato dalla configurazione corrente del contesto spaziale (e quindi dalla configurazione corrente dei servizi sottostanti).

  • Se un'estensione definisce un nuovo XrSpatialCapabilityEXT ,

  • Se un'estensione definisce un nuovo XrSpatialCapabilityFeatureEXT, deve anche definire una struttura di configurazione corrispondente che può essere concatenata al puntatore successivo di XrSpatialCapabilityConfigurationBaseHeaderEXT , che l'applicazione può utilizzare per attivare la funzionalità durante la creazione di un XrSpatialContextEXT .

  • Un'estensione che definisce un nuovo XrSpatialCapabilityEXT deve seguire questo modello per la specifica:

    • Panoramica
    • Assistenza per i runtime
    • Configurazione
    • Componenti garantiti
    • Esempio di codice

  • Un'estensione che definisce un nuovo XrSpatialComponentTypeEXT deve seguire questo modello per la specifica:

    • Dati dei componenti
    • Struttura dell'elenco dei componenti per eseguire query sui dati
    • Configurazione

  • Quando scrivi un'API che fornisce all'applicazione un XrSpatialBufferIdEXT, deve essere accompagnata da un XrSpatialBufferTypeEXT per informare l'applicazione del tipo di dati del buffer e l'applicazione può utilizzare una funzione xrGetSpatialBuffer* appropriata per recuperare i contenuti effettivi del buffer.

Linee guida per la progettazione e l'estensione delle etichette semantiche

Sebbene questa estensione non definisca alcun componente per trasmettere le informazioni sull'etichetta semantica di un'entità, stabilisce le regole e le linee guida di progettazione per tutte le estensioni che definiscono un componente di questo tipo. Nel testo seguente, "dovrebbe" e "deve" vincolano gli autori di questa funzionalità, anziché vincolare un'implementazione di runtime o un'applicazione che utilizza l'API.

  • Se un'estensione definisce etichette semantiche per qualsiasi XrSpatialCapabilityEXT, deve farlo definendo un nuovo XrSpatialComponentTypeEXT e una nuova enumerazione con un insieme di etichette (un "insieme di etichette semantiche") che costituiranno i dati per quel componente.
  • Un'enumerazione che rappresenta un insieme di etichette semantiche deve avere un valore per indicare che l'entità non è classificata in nessuna delle etichette di questo insieme. Il nome di questo enumerante deve includere "UNCATEGORIZED", ad esempio XR_SPATIAL_PLANE_SEMANTIC_LABEL_UNCATEGORIZED_EXT. Questo valore indica alle applicazioni che il runtime riconosce questa entità, ma che esistono altri insiemi di etichette semantiche in cui questa entità è categorizzata.
  • L'enumerazione di questo XrSpatialComponentTypeEXT appena definito in xrEnumerateSpatialCapabilityComponentTypesEXT implica che il runtime supporta l'insieme di etichette semantiche (e quindi le etichette definite nell'insieme) corrispondente a quel tipo di componente.
  • Le applicazioni esprimono il desiderio di rilevare entità con etichette appartenenti a questo insieme di etichette semantiche includendo il XrSpatialComponentTypeEXT corrispondente nell'array XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents della struttura di configurazione per la funzionalità per cui è enumerato il tipo di componente.
  • È possibile che una singola entità spaziale abbia più componenti, ognuno dei quali fornisce un'etichetta dal proprio insieme di etichette semantiche. Considera il seguente esempio con alcuni set di etichette semantiche ipotetici: XrSpatialObjectSemanticLabel , che potrebbero avere valori come sedia, divano, tavolo e così via, XrSpatialSofaBrand, che potrebbe avere valori come IKEA, Wayfair e così via, e XrSpatialIkeaSofa, che potrebbe avere nomi di modelli di divani IKEA specifici. In questo scenario, la stessa entità divano ha tutti e tre i componenti (etichette di tutti e tre i set di etichette semantiche), ognuno dei quali fornisce un livello di granularità diverso delle informazioni sull'entità.
  • Se un'estensione definisce un nuovo XrSpatialComponentTypeEXT che fornisce un nuovo set di etichette semantiche contenente più etichette oltre all'etichetta UNCATEGORIZED, l'estensione dovrebbe prendere in considerazione la definizione di un XrSpatialCapabilityFeatureEXT che consenta alle applicazioni di attivare solo un sottoinsieme delle etichette definite nel set di etichette semantiche corrispondente a quel tipo di componente. Questo sottoinsieme, fornito nella catena successiva della configurazione delle funzionalità, funge da suggerimento per i runtime per ottimizzare le pipeline di monitoraggio e monitorare solo il sottoinsieme fornito. Un esempio di questa struttura di caratteristiche è fornito di seguito .
  • Le estensioni non devono aggiungere etichette all'enumerazione del set di etichette semantiche esistente. Devono invece definire una nuova enumerazione che contenga enumeranti equivalenti con semantica identica e con valori uguali a quelli dell'altro insieme, oltre agli enumeranti appena aggiunti. La specifica dell'insieme di etichette semantiche appena definito deve anche stabilire la mappatura tra l'insieme di etichette precedente e quello nuovo. Vedi l'esempio di seguito .
Esempio di definizione di una caratteristica spaziale per un sottoinsieme di etichette semantiche
// 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;
Esempio di estensione di etichetta semantica spaziale
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;

Considera l'esempio precedente in cui un'estensione definisce un'enumerazione XrSpatialExamplePlaneSemanticLabelExtensionEXT per estendere l'esistente XrSpatialPlaneSemanticLabelEXT con valori per rappresentare porte e finestre. La specifica per la nuova enumerazione deve includere il testo per il seguente modulo:

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
|====

Nuove macro

Nuovi tipi di base

  • XrSpatialBufferIdEXT
  • XrSpatialEntityIdEXT

Nuovi tipi di oggetti

Nuovi comandi

Nuove strutture

Nuovi enum

Nuove costanti enum

  • XR_EXT_SPATIAL_ENTITY_EXTENSION_NAME
  • XR_EXT_spatial_entity_SPEC_VERSION

  • Estensione di XrObjectType :

    • XR_OBJECT_TYPE_SPATIAL_CONTEXT_EXT
    • XR_OBJECT_TYPE_SPATIAL_ENTITY_EXT
    • XR_OBJECT_TYPE_SPATIAL_SNAPSHOT_EXT

  • Estensione di 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

  • Estensione di 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

Problemi

  • Una singola entità deriva sempre da una sola funzionalità?

    • Risolto
    • Risposta: No. Dipende completamente dal runtime in base alle sue capacità di monitoraggio e al modo in cui vuole rappresentare un'entità rilevata. La specifica non prescrive alcuna rappresentazione particolare dell'entità spaziale, ad eccezione dei componenti garantiti di una determinata funzionalità per impostare un'aspettativa minima. Un runtime può essere in grado di unire le entità rilevate da funzionalità separate e rappresentarle come un'unica entità con i componenti garantiti di tutte le funzionalità che hanno contribuito a identificarla. Un esempio potrebbe essere che i tavoli possono essere rilevati sia da una funzionalità di tracciamento dei piani sia da una funzionalità di tracciamento degli oggetti, con il tracciamento dei piani che fornisce il componente XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT sull'entità e il tracciamento degli oggetti che fornisce XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT . Un determinato runtime può fornire la tabella come due entità separate, ciascuna con il proprio insieme di componenti garantiti, mentre alcuni runtime possono fornire una sola entità per rappresentare la tabella e avere sia XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT sia XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT sulla stessa entità. È importante notare che una determinata entità spaziale può avere al massimo un singolo componente di un determinato tipo di componente . Pertanto, se i dati dei componenti prodotti dalle diverse funzionalità sono in conflitto per una determinata entità, il runtime deve rappresentarli come due entità separate.

Cronologia delle versioni

  • Revisione 1, 12/04/2024 (Nihav Jain, Google)

    • Descrizione iniziale dell'estensione