XR_EXT_spatial_entity

Stringa del nome

XR_EXT_spatial_entity

Tipo di estensione

Estensione dell'istanza

Numero di interno registrato

741

Revisione

1

Stato di ratifica

Ratificato

Dipendenze da 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 le basi per la comprensione della scena e il ragionamento spaziale in OpenXR. In questo modo vengono unificate diverse aree di funzionalità correlate ma distinte, che vengono enumerate, configurate e con cui si interagisce in modo ampiamente uniforme, come definito da questa estensione. Poiché questa estensione non dispone di definizioni concrete di nessuna di queste aree funzionali, il testo delle specifiche formali tende a essere piuttosto astratto. Gli esempi inclusi nel testo delle specifiche di questa estensione si riferiscono a volte a funzionalità definite in un'estensione correlata futura o ipotetica a scopo illustrativo, senza limitare o specificare intrinsecamente tali funzionalità aggiuntive.

I componenti principali di questa estensione sono i seguenti:

  • Entità spaziali : la funzionalità è incentrata sulle entità , che offrono funzionalità molto limitate da sole.
  • Componenti spaziali : queste entità hanno componenti associati 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 : tutta l'interazione con le entità spaziali avviene 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) ancore definite dall'applicazione, rilevamento di piani o monitoraggio di immagini. Ogni funzionalità viene in genere definita in un'estensione separata (attivata al momento della creazione dell'istanza come di consueto) ed è abilitata per un contesto specifico al momento della creazione.
  • Ogni funzionalità è associata a un insieme di tipi di componenti per i quali i componenti sono presenti 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à può fornire alle entità componenti di un determinato tipo di componente , che sono utilizzabili in modo uniforme indipendentemente dalla funzionalità che li ha prodotti.
  • Funzionalità di rilevamento spaziale : inoltre, alcune funzionalità richiedono la configurazione e sono quindi parametrizzate dalle funzionalità di rilevamento .

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

Poiché alcune implementazioni potrebbero richiedere diversi gradi di parametrizzazione per le funzionalità , questa estensione fornisce un meccanismo per enumerare le funzionalità di capacità supportate associate a una determinata capacità 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 che hanno vari dati associati organizzati in componenti. Possono essere:

  • Fisici (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 da un altro utente),
  • Definito dall'app (ad es. un'applicazione che contrassegna un'area come "soggiorno" o "cucina" o un punto come 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 pensati per essere modellati come entità spaziali.

Le entità spaziali in OpenXR sono modellate come un sistema entità-componente . Ogni entità spaziale ha un insieme di componenti e ogni componente fornisce un insieme unico 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 di entità spaziali.

Tipi di componenti spaziali

Un'entità spaziale ha uno o più componenti che forniscono dati o comportamenti per l'entità. Consulta 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_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 vengono forniti da questa estensione da sola: alcuni richiedono l'attivazione di estensioni aggiuntive al momento della creazione dell'istanza, come documentato.

Gli enumeranti 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'elemento 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'enumerazione dell'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 aereo. 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 del marcatore. 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 ancoraggio. 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 triangolo per la 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 raycast che ha colpito 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à allegata. 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 camera di una scatola di scarpe; 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 dell'entità allegata. 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 quadrata. 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 streetscape; la struttura dell'elenco corrispondente è XrSpatialComponentStreetscapeGeometryMetadataListANDROIDX2; la struttura dei dati corrispondente è XrSpatialStreetscapeGeometryMetadataANDROIDX2 (aggiunta dall'estensione XR_ANDROIDX2_geospatial_streetscape)

Funzionalità spaziali e configurazione

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 abilitati sulle entità rilevate. Ad esempio , se un runtime segnala che uno dei componenti di una determinata funzionalità è "etichette semantiche", significa che l'applicazione può abilitare le etichette semantiche tramite la configurazione di questa funzionalità e il runtime deve fornire il componente 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 potrebbe supportare.

Gli enumeranti hanno i seguenti valori:

Descrizione enum

XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT

Monitoraggio aerei (aggiunto dall'estensione XR_EXT_spatial_plane_tracking)

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT

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

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT

Possibilità di rilevare e monitorare i micro codici QR. (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 oggetti (aggiunto dall'estensione XR_EXT_spatial_object_tracking)

XR_SPATIAL_CAPABILITY_ANCHOR_EXT

Possibilità di creare ancore spaziali (aggiunta dall'estensione XR_EXT_spatial_anchor)

XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT

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

XR_SPATIAL_CAPABILITY_MESH_TRACKING_EXT

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

XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_ANDROID

Monitoraggio 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

Possibilità di monitorare una stanza (aggiunta dall'estensione XR_ANDROIDSYS_spatial_room_tracking)

XR_SPATIAL_CAPABILITY_ROOM_BOUNDARY_TRACKING_ANDROIDSYS

Possibilità di tracciare il confine di una 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

Geometria di Streetscape (aggiunta dall'estensione XR_ANDROIDX2_geospatial_streetscape)

La funzione xrEnumerateSpatialCapabilitiesEXT è definita come:

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 le cui funzionalità spaziali verranno elencate.
  • 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 sia insufficiente.
  • capabilities è un array di XrSpatialCapabilityEXT . Può essere NULL se capabilityCapacityInput è 0.
  • Consulta la sezione Parametri delle dimensioni del buffer per una descrizione dettagliata del recupero delle dimensioni capabilities richieste.

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 ritorno

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'XrSpatialCapabilityEXT per cui verranno enumerati i componenti.
  • capabilityComponents è un puntatore a un XrSpatialCapabilityComponentTypesEXT , ovvero 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 sulle sue entità nel sistema così come configurato.

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

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 è abilitata per instance .

Utilizzo valido (implicito)

Codici di ritorno

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. Queste strutture non sono definite 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 delle dimensioni del buffer per una descrizione dettagliata del recupero delle dimensioni componentTypes richieste.

Utilizzo valido (implicito)

Funzionalità di capacità 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 dei componenti 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 potrebbe supportare una funzionalità che consente all'applicazione di specificare se le immagini monitorate sono statiche o meno.

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

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

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

Gli enumeranti 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 dei marcatori. 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 i marcatori 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 da monitorare in fase di 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à di rilevamento per tracciare una mesh a tenuta stagna dell'ambiente. La struttura di configurazione corrispondente è XrSpatialFeatureTrackWatertightMeshEXT . (Aggiunto dall'estensione XR_EXT_spatial_mesh_tracking)

La funzione xrEnumerateSpatialCapabilityFeaturesEXT è definita come:

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 le cui funzionalità spaziali verranno elencate.
  • capability è XrSpatialCapabilityEXT per cui verranno elencate le funzionalità.
  • capabilityFeatureCapacityInput è la capacità dell'array o 0 per indicare una richiesta di recupero della capacità richiesta.
  • capabilityFeatureCountOutput è il numero di funzionalità 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 delle dimensioni del buffer per una descrizione dettagliata del recupero delle dimensioni capabilityFeatures richieste.

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

Per le funzionalità che hanno funzionalità esposte, l'applicazione seleziona la funzionalità o le funzionalità 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 ritorno

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

Creare un contesto spaziale

XR_DEFINE_HANDLE(XrSpatialContextEXT)

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

La funzione xrCreateSpatialContextAsyncEXT è definita come:

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

Descrizioni dei parametri

  • session è una XrSession in cui il contesto spaziale sarà attivo.
  • createInfo è 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 richiede 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 XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponentCount in XrSpatialContextCreateInfoEXT :: capabilityConfigs è 0. Una configurazione delle 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 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 potrebbe utilizzare le configurazioni fornite nell'array XrSpatialContextCreateInfoEXT per prepararsi a ricevere richieste spaziali. 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 lungo periodo di riscaldamento, 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 inizializzati.

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 a questa applicazione.

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

Utilizzo valido (implicito)

Codici di ritorno

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

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. Queste strutture non sono definite 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 relative 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 ritorno

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 durante il 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)

Eliminare il contesto spaziale

La funzione xrDestroySpatialContextEXT è definita come:

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 per il runtime per disattivare i servizi di monitoraggio richiesti per queste funzionalità per risparmiare risorse di sistema.

Utilizzo valido (implicito)

Thread Safety

  • L'accesso a spatialContext e a tutti gli handle secondari deve essere sincronizzato esternamente

Codici di ritorno

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 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 della stessa 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 e restituito dalle funzioni API solo se specificamente 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 al runtime il proprio interesse per una determinata entità.

Crea un 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, ovvero un 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 ritorno

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. Queste strutture non sono definite in OpenXR di base o in questa estensione.
  • entityId è l'XrSpatialEntityIdEXT dell'entità per cui l'applicazione vuole creare un handle.

Utilizzo valido (implicito)

Destroy Spatial Entity Handle

La funzione xrDestroySpatialEntityEXT è definita come:

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 tutti gli handle secondari deve essere sincronizzato esternamente

Codici di ritorno

Operazione riuscita

  • XR_SUCCESS

Errore

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Snapshot spaziale

XR_DEFINE_HANDLE(XrSpatialSnapshotEXT)

L'applicazione può creare snapshot spaziali allo scopo di scoprire entità spaziali o per 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. Lo snapshot spaziale rappresenta una visione coerente delle entità e dei relativi dati dei componenti. Una volta creato uno snapshot, i relativi dati devono rimanere costanti per tutta la durata della validità dello snapshot.

L'applicazione può creare il numero di snapshot che vuole, ma deve tenere conto della memoria allocata per ogni nuovo snapshot e deve eliminare gli snapshot quando non ne ha più bisogno.

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 funzioni correlate. Il valore restituito di questa funzione indica solo se i parametri erano accettabili per pianificare l'operazione asincrona. La funzione di completamento corrispondente è xrCreateSpatialDiscoverySnapshotCompleteEXT , utilizzabile quando un futuro 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 precedente. Il runtime potrebbe elaborare e completare la creazione dello 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 politiche di alimentazione, termiche o di altro tipo del dispositivo.

L'applicazione può utilizzare XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes per filtrare l'elenco delle entità e i componenti i cui dati devono essere inclusi nello snapshot dal runtime. 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 a questi componenti nello snapshot.

Il runtime deve restituire XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT se uno qualsiasi 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 tutte le entità spaziali nello snapshot che hanno il set 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 messo in coda prima del completamento di future e XrEventDataReferenceSpaceChangePending :: poseValid è false, il runtime potrebbe creare un XrSpatialSnapshotEXT senza entità o impostare XrSpatialEntityTrackingStateEXT delle entità non 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 ritorno

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. Queste strutture non sono definite 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 l'individuazione 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 è nello stato Pronto. Il runtime deve restituire XR_ERROR_FUTURE_INVALID_EXT se XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: future è già stato completato o annullato.

Utilizzo valido (implicito)

Codici di ritorno

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 posizioni nei vari dati dei componenti inclusi nello snapshot creato saranno 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 raccomandazione di scoperta

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 è 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 scoprire le entità spaziali aspettando 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 pertanto la creazione di snapshot e le query sui 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 contribuisce a evitare il rischio di un utilizzo eccessivo delle risorse di sistema e di limitazione a causa delle policy di alimentazione o termiche del dispositivo. Ciò contribuisce anche a creare parità tra i runtime che rilevano entità spaziali al volo con il monitoraggio in tempo reale e i runtime che forniscono entità spaziali da uno stato registrato in precedenza (in cui il runtime potrebbe accodare 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 tenere traccia degli aggiornamenti dei dati dei componenti per le entità spaziali a cui è interessata.

Un runtime potrebbe mettere in coda un evento di suggerimento di scoperta senza attendere che l'applicazione chiami prima xrCreateSpatialDiscoverySnapshotAsyncEXT . Ad esempio, un runtime potrebbe basare la decisione di mettere in coda l'evento di suggerimento di scoperta sulla configurazione di XrSpatialContextEXT, sulla propria comprensione dell'ambiente circostante l'utente (scoperta di nuove entità o perdita di quelle esistenti) o per suggerire una cadenza di richiesta di scoperta appropriata all'applicazione in modo da non sovraccaricare le risorse di sistema. L'ambiente di runtime potrebbe 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 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 chiama xrDestroySpatialContextEXT , il runtime non deve mettere in coda altri eventi di suggerimento di scoperta per quel contesto spaziale né restituire tali eventi per quel contesto da xrPollEvent .

Utilizzo valido (implicito)

Eseguire 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 del tutto le strutture di elenco se vuole conoscere solo gli ID e lo stato di monitoraggio delle entità spaziali che soddisfano queryCondition . Il runtime non deve considerare l'assenza di strutture di elenco dalla catena XrSpatialComponentDataQueryResultEXT :: next come un errore.

Se XrEventDataReferenceSpaceChangePending è in coda e XrEventDataReferenceSpaceChangePending :: changeTime è trascorso mentre l'applicazione esegue query sui dati dei componenti da un XrSpatialSnapshotEXT , l'applicazione potrebbe utilizzare i dati degli eventi per modificare 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 condizioni di query aggiuntive a XrSpatialComponentDataQueryConditionEXT :: next, il runtime deve trattarle come un "AND" con la disponibilità dei tipi di componenti, ovvero il runtime deve popolare XrSpatialComponentDataQueryResultEXT ::entityIds solo con le entità che soddisfano tutte le condizioni fornite. Il runtime deve compilare i dati dei componenti nelle strutture di elenco nello stesso ordine delle entità in XrSpatialComponentDataQueryResultEXT :: entityIds ovvero i dati dei componenti in un determinato indice nell'array della struttura di elenco devono corrispondere all'entità nello stesso indice.

Se lo stato del monitoraggio per 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 allegate a XrSpatialComponentDataQueryResultEXT .

Utilizzo valido (implicito)

Codici di ritorno

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. Istantanea di esempio

xrQuerySpatialComponentDataEXT nello snapshot precedente con XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT elencato nella condizione di query restituirà le entità n. 1, 2 e 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 #1

Dati per entit...

Dati per entityId #2

Dati per entit...

Dati per entityId #5

Dati per entit...

entityIds

entityIds

avanti

avanti

XrSpatialComponent
DataQueryResultEXT

XrSpatialComponent
Dat...

limiti

limiti

XrSpatialComponent
Bounded2DListEXT

XrSpatialComponent
Bou... Il testo non è SVG e non può essere visualizzato

Figura 21. Risultato della query di esempio

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

XrSpatialEntityIdEXT

XrSpatialEntityIdEXT

3

3

4

4

Bounded3D

Bounded3D

Data for entityId #3

Dati per entit...

Dati per entityId #4

Dati per entit...

Mesh3D

Mesh3D

Data for entityId #3

Dati per entit...

Dati per entityId #4

Dati per entit...

entityIds

entityIds

avanti

avanti

XrSpatialComponent
DataQueryResultEXT

XrSpatialComponent
Da...

limiti

limiti

avanti

avanti

XrSpatialComponent
Bounded3DListEXT

XrSpatialComponent
Bo...

XrSpatialComponent
Mesh3DListEXT

XrSpatialComponent
Me...

meshes

mesh Il testo non è SVG e non può essere visualizzato

Figura 22. Risultato della query di esempio

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 sia insufficiente.
  • 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 sia insufficiente. Questo valore deve sempre corrispondere a entityIdCountOutput .
  • entityStates è un array di XrSpatialEntityTrackingStateEXT . Può essere NULL se entityStateCapacityInput è 0.
  • Consulta la sezione Parametri delle dimensioni del buffer per una descrizione dettagliata del recupero delle dimensioni entityIds richieste.

Un'applicazione può utilizzare entityIds con xrCreateSpatialEntityFromIdEXT per creare handle XrSpatialEntityEXT per le entità per cui è interessata a ricevere aggiornamenti regolari. L'applicazione può quindi utilizzare questi handle XrSpatialEntityEXT con xrCreateSpatialUpdateSnapshotEXT per creare uno snapshot di aggiornamento contenente i dati più recenti noti al 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;

L'enumerazione XrSpatialEntityTrackingStateEXT elenca i possibili stati di tracciamento 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 relativi componenti sono validi.

MONITORAGGIO

IN PAUSA

INTERROTTO

Figura 23. XrSpatialEntityTrackingStateEXT

  • Il runtime potrebbe 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 di questa entità spaziale, ma ha la possibilità di riprenderlo in futuro. Alcuni esempi di quando il runtime potrebbe farlo includono (ma non sono limitati a) se l'applicazione perde la messa a fuoco dell'input; se l'entità spaziale specificata è troppo lontana dall'utente per essere tracciata con precisione; o se vengono tracciate troppe entità e il runtime vuole ridurre il costo del tracciamento. XrSpatialEntityTrackingStateEXT aiuta l'applicazione a isolarsi dalle diverse norme di monitoraggio di ogni runtime.
  • Il runtime potrebbe 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 suo monitoraggio non verrà mai recuperato o ripreso. Un esempio di questo caso si verifica se il dispositivo perde il monitoraggio, riavvia la sessione di monitoraggio, ma non è in grado di localizzarsi nuovamente nel suo ambiente e quindi tratta le entità rilevate di questa sessione di monitoraggio 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 esegui 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 il contenuto dei buffer.

Idioma 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 il XrSpatialBufferIdEXT dei dati del buffer.
  • bufferType è 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 di dati dei componenti all'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 per 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 per almeno il ciclo di vita di XrSpatialSnapshotEXT che lo contiene. Il runtime potrebbe mantenere XrSpatialBufferIdEXT e i relativi dati in memoria per un periodo più lungo del 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 sempre restituire 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 dell'enumerante

La funzione xrGetSpatialBufferStringEXT è definita come:

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 da interrogare.
  • 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 delle dimensioni del buffer per una descrizione dettagliata del recupero delle dimensioni buffer richieste.

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 terminata con il carattere 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 ritorno

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 da interrogare.
  • 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 sia insufficiente.
  • buffer è un array di uint8_t . Può essere NULL se bufferCapacityInput è 0.
  • Consulta la sezione Parametri delle dimensioni del buffer per una descrizione dettagliata del recupero delle dimensioni buffer richieste.

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 ritorno

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 da interrogare.
  • 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 sia insufficiente.
  • buffer è un array di uint16_t . Può essere NULL se bufferCapacityInput è 0.
  • Consulta la sezione Parametri delle dimensioni del buffer per una descrizione dettagliata del recupero delle dimensioni buffer richieste.

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 ritorno

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 da interrogare.
  • 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 sia insufficiente.
  • buffer è un array di uint32_t . Può essere NULL se bufferCapacityInput è 0.
  • Consulta la sezione Parametri delle dimensioni del buffer per una descrizione dettagliata del recupero delle dimensioni buffer richieste.

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 ritorno

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 da interrogare.
  • 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 sia insufficiente.
  • buffer è un array di float . Può essere NULL se bufferCapacityInput è 0.
  • Consulta la sezione Parametri delle dimensioni del buffer per una descrizione dettagliata del recupero delle dimensioni buffer richieste.

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 ritorno

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 da interrogare.
  • 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 sia insufficiente.
  • buffer è un array di XrVector2f . Può essere NULL se bufferCapacityInput è 0.
  • Consulta la sezione Parametri delle dimensioni del buffer per una descrizione dettagliata del recupero delle dimensioni buffer richieste.

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 attivata 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 strutture bufferCapacityInput XrVector2f

Codici di ritorno

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 da interrogare.
  • 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 sia insufficiente.
  • buffer è un array di XrVector3f . Può essere NULL se bufferCapacityInput è 0.
  • Consulta la sezione Parametri delle dimensioni del buffer per una descrizione dettagliata del recupero delle dimensioni buffer richieste.

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 ritorno

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 e restituito dalle funzioni API solo se specificamente 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 note al runtime. Le applicazioni possono fornire gli handle XrSpatialEntityEXT e i tipi di componenti a cui sono interessate 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 di questi componenti nello snapshot.

Il runtime deve restituire XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT se uno qualsiasi 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 di 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 il numero di snapshot che vuole, ma deve tenere conto della memoria allocata per ogni nuovo snapshot e deve eliminare gli snapshot quando non ne ha più bisogno.

Utilizzo valido (implicito)

Codici di ritorno

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. Queste strutture non sono definite 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 dei componenti 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 è XrSpace rispetto al quale si troveranno tutte le posizioni dell'aggiornamento XrSpatialSnapshotEXT.
  • time è il 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 handle entityCount validi XrSpatialEntityEXT
  • Se componentTypeCount non è 0 , componentTypes deve essere un puntatore a un array di valori XrSpatialComponentTypeEXT validi di componentTypeCount
  • baseSpace deve essere un handle XrSpace valido
  • Il parametro entityCount deve essere maggiore di 0
  • Sia baseSpace sia 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 tutti gli handle secondari deve essere sincronizzato esternamente

Codici di ritorno

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) e l'asse Y (extents.height), centrate su center .

Il extents del XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT si riferisce alle dimensioni dell'entità nel piano x-y del sistema di coordinate del piano. Un piano con posizione {0, 0, 0}, rotazione {0, 0, 0, 1} (nessuna rotazione) ed estensione {1, 1} si riferisce a un piano di 1 metro x 1 metro centrato su {0, 0, 0} con il vettore normale della faccia anteriore che punta 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 del componente 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 -π/2 radianti intorno 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. Queste strutture non sono definite 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 determinata funzionalità, l'applicazione può attivarla includendo il valore 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. Queste strutture non sono definite 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 determinata funzionalità, l'applicazione può attivarla includendo l'enumerazione 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. Queste strutture non sono definite 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 determinata funzionalità, l'applicazione può attivarla includendo l'enumerazione 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 determinata funzionalità, l'applicazione può attivarla includendo l'enumerazione 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 del monitoraggio

La struttura XrSpatialFilterTrackingStateEXT è definita come:

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

Descrizioni dei membri

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

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

Utilizzo valido (implicito)

Esempio di codice

Utilizzo dell'applicazione

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

Scopri le entità spaziali e i dati dei componenti delle query

Il seguente codice di esempio mostra come scoprire le entità spaziali per la funzionalità "Foo" e interrogare i 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));

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 in base alla configurazione corrente del contesto spaziale (e quindi alla configurazione corrente dei servizi sottostanti).

  • Se un'estensione definisce una nuova XrSpatialCapabilityEXT ,

  • Se un'estensione definisce una nuova XrSpatialCapabilityFeatureEXT , deve anche definire una struttura di configurazione corrispondente che possa 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 una nuova 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 comunicare all'applicazione il 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 di progettazione e le linee guida per qualsiasi estensione che definisca un componente di questo tipo. Nel testo seguente, " deve " e " deve " vincolano gli autori di questa funzionalità, anziché 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, nonché una nuova enumerazione con un insieme di etichette (un "insieme di etichette semantiche") da utilizzare come dati per il 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 enumeratore 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 set di etichette semantiche in cui è classificata.
  • L'enumerazione di questo XrSpatialComponentTypeEXT appena definito in xrEnumerateSpatialCapabilityComponentTypesEXT implica che il runtime supporta il set di etichette semantiche (e quindi le etichette definite nel set) corrispondente a quel tipo di componente.
  • Le applicazioni esprimono il loro desiderio di scoprire entità con etichette appartenenti a questo insieme di etichette semantiche includendo il valore XrSpatialComponentTypeEXT corrispondente nell'array XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents dello struct 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 set di etichette semantiche. Considera l'esempio seguente 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 IKEA specifici di divani. 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 insieme di etichette semantiche contenente più etichette oltre all'etichetta UNCATEGORIZED, l'estensione deve prendere in considerazione la definizione di un XrSpatialCapabilityFeatureEXT che consenta alle applicazioni di attivare solo un sottoinsieme delle etichette definite nell'insieme 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 questo struct di funzionalità è riportato di seguito .
  • Le estensioni non devono aggiungere etichette all'enumerazione del set di etichette semantiche esistente. Devono invece definire una nuova enumerazione che contenga enumeratori equivalenti con semantica identica e con valori uguali a quelli dell'altro insieme, oltre agli enumeratori appena aggiunti. La specifica del nuovo insieme di etichette semantiche definito deve anche stabilire la mappatura tra il vecchio insieme di etichette e quello nuovo. Vedi l'esempio di seguito .
Esempio di definizione della funzionalità spaziale per il 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 dell'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 potrebbe essere in grado di unire le entità rilevate da funzionalità separate e rappresentarle come una singola 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 monitoraggio del piano sia da una di monitoraggio degli oggetti. Il monitoraggio del piano fornisce il componente XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT sull'entità, mentre il monitoraggio degli oggetti fornisce XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT. Un determinato runtime potrebbe fornire la tabella come due entità separate, ognuna con il proprio insieme di componenti garantiti, mentre alcuni runtime potrebbero fornire una sola entità per rappresentare la tabella e avere sia XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT che XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT nella stessa entità. Ciò che è importante notare qui è 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