XR_ANDROID_scene_meshing

Stringa del nome

XR_ANDROID_scene_meshing

Tipo di estensione

Estensione dell'istanza

Numero di interno registrato

719

Revisione

3

Stato di ratifica

Non ratificato

Dipendenze da estensioni e versioni

OpenXR 1.0

Data ultima modifica

2025-05-15

Stato IP

Nessuna rivendicazione di proprietà intellettuale nota.

Collaboratori

Spencer Quin, Google
Jared Finder, Google
Antonio Fontan, Google
Cairn Overturf, Google
Nihav Jain, Google
Salar Khan, Google
Sebastian Klose, Google
Jürgen Sturm, Google
Vinny DaSilva, Google
Ricardo Campbell, Google

Panoramica

Questa estensione ha lo scopo di fornire mesh che rappresentano approssimativamente gli oggetti fisici nell'ambiente dell'utente.

Le applicazioni possono utilizzare questa estensione per visualizzare la scena e consentire agli oggetti virtuali di interagire con quelli fisici, ad esempio in caso di collisioni.

I dati della mesh della scena vengono generati dal runtime e condivisi con l'applicazione utilizzando XrSceneMeshingTrackerANDROID e XrSceneMeshSnapshotANDROID . Le applicazioni possono accedere ai valori nelle informazioni sulle submesh della scena tramite XrSceneSubmeshStateANDROID restituito da xrGetAllSubmeshStatesANDROID . Le applicazioni possono accedere ai valori nei dati delle submesh della scena tramite XrSceneSubmeshDataANDROID restituito da xrGetSubmeshDataANDROID .

I dati di mesh della scena sono informazioni personali sensibili e sono strettamente collegati alla privacy e all'integrità personali. È consigliabile che le applicazioni che archiviano o trasferiscono dati di mesh della scena chiedano sempre all'utente un'accettazione attiva e specifica.

Autorizzazioni

Le applicazioni Android devono avere l'autorizzazione android.permission.SCENE_UNDERSTANDING_FINE elencata nel manifest. L'autorizzazione android.permission.SCENE_UNDERSTANDING_FINE è considerata un'autorizzazione sensibile in quanto consente al runtime di studiare l'ambiente dell'utente.

L'applicazione deve richiedere l'autorizzazione in fase di runtime per utilizzare queste funzioni:

(livello di protezione: pericoloso)

Ispeziona la funzionalità del sistema

La struttura XrSystemSceneMeshingPropertiesANDROID è definita come:

typedef struct XrSystemSceneMeshingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsSceneMeshing;
} XrSystemSceneMeshingPropertiesANDROID;

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.
  • supportsSceneMeshing è un XrBool32 , che indica se il sistema supporta la creazione di mesh della scena.

Un'applicazione può verificare se il sistema è in grado di eseguire la mesh della scena concatenando una struttura XrSystemSceneMeshingPropertiesANDROID alla struttura XrSystemProperties quando chiama xrGetSystemProperties .

Se un runtime restituisce XR_FALSE per supportsSceneMeshing , il sistema non supporta la creazione di mesh della scena, pertanto deve restituire XR_ERROR_FEATURE_UNSUPPORTED da xrCreateSceneMeshingTrackerANDROID . L'applicazione deve evitare di utilizzare la funzionalità di mesh della scena quando supportsSceneMeshing è XR_FALSE .

Se un runtime restituisce XR_TRUE per supportsSceneMeshing , il sistema supporta la creazione di mesh delle scene.

Utilizzo valido (implicito)

L'enumerazione XrSceneMeshSemanticLabelSetANDROID descrive gli insiemi di etichette semantiche per la mesh della scena. Ogni valore in questa enumerazione rappresenta un'altra enumerazione che contiene le etichette semantiche. Ad esempio, il valore XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID rappresenta il set XrSceneMeshSemanticLabelANDROID .

typedef enum XrSceneMeshSemanticLabelSetANDROID {
    XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID = 0,
    XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID = 1,
    XR_SCENE_MESH_SEMANTIC_LABEL_SET_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSceneMeshSemanticLabelSetANDROID;

I valori di enumerazione hanno i seguenti significati:

Descrizione enum

XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID

Questo insieme di etichette semantiche rappresenta l'assenza di etichette semantiche.

XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID

Questo set di etichette semantiche rappresenta XrSceneMeshSemanticLabelANDROID.

La funzione xrEnumerateSupportedSemanticLabelSetsANDROID è definita come:

XrResult xrEnumerateSupportedSemanticLabelSetsANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    supportedSemanticLabelSetsInputCapacity,
    uint32_t*                                   supportedSemanticLabelSetsOutputCount,
    XrSceneMeshSemanticLabelSetANDROID*         supportedSemanticLabelSets);

Descrizioni dei parametri

  • instance è un XrInstance creato dall'applicazione.
  • systemId è un XrSystemId riprovato da xrGetSystem .
  • supportedSemanticLabelSetsInputCapacity è la capacità di supportedSemanticLabelSets o 0 per recuperare la capacità richiesta.
  • supportedSemanticLabelSetsOutputCount è un puntatore al conteggio di supportedSemanticLabelSets scritti o un puntatore alla capacità richiesta nel caso in cui supportedSemanticLabelSetsInputCapacity sia insufficiente.
  • supportedSemanticLabelSets è un puntatore a un array di XrSceneMeshSemanticLabelSetANDROID . Può essere NULL se supportedSemanticLabelSetsInputCapacity è 0.
  • Consulta il capitolo Parametri delle dimensioni del buffer per una descrizione dettagliata del recupero delle dimensioni supportedSemanticLabelSets richieste.

L'applicazione può enumerare i set di etichette semantiche supportati dal sistema utilizzando la funzione xrEnumerateSupportedSemanticLabelSetsANDROID.

Ogni sistema deve supportare almeno XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID perché questo valore enum non rappresenta alcun insieme di etichette semantiche e può essere utilizzato nel caso in cui l'applicazione non abbia bisogno della semantica dei vertici.

Utilizzo valido (implicito)

  • L'estensione XR_ANDROID_scene_meshing deve essere attivata prima di chiamare xrEnumerateSupportedSemanticLabelSetsANDROID
  • instance deve essere un handle XrInstance valido
  • supportedSemanticLabelSetsOutputCount deve essere un puntatore a un valore uint32_t
  • Se supportedSemanticLabelSetsInputCapacity non è 0 , supportedSemanticLabelSets deve essere un puntatore a un array di valori supportedSemanticLabelSetsInputCapacity XrSceneMeshSemanticLabelSetANDROID

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

Crea un handle del tracker di fusione delle scene

XR_DEFINE_HANDLE(XrSceneMeshingTrackerANDROID)

L'handle XrSceneMeshingTrackerANDROID rappresenta un tracker di mesh della scena per la mesh della scena e la gestione delle risorse correlate.

Questo handle può essere utilizzato per creare uno snapshot della mesh della scena utilizzando xrCreateSceneMeshSnapshotANDROID in questa estensione.

La funzione xrCreateSceneMeshingTrackerANDROID è definita come:

XrResult xrCreateSceneMeshingTrackerANDROID(
    XrSession                                   session,
    const XrSceneMeshingTrackerCreateInfoANDROID* createInfo,
    XrSceneMeshingTrackerANDROID*               tracker);

Descrizioni dei parametri

Un'applicazione può creare un handle XrSceneMeshingTrackerANDROID utilizzando la funzione xrCreateSceneMeshingTrackerANDROID.

Se il sistema non supporta la mesh della scena, il runtime deve restituire XR_ERROR_FEATURE_UNSUPPORTED da xrCreateSceneMeshingTrackerANDROID . In questo caso, il runtime deve restituire XR_FALSE per XrSystemSceneMeshingPropertiesANDROID :: supportsSceneMeshing quando viene chiamata la funzione xrGetSystemProperties, in modo che l'applicazione possa evitare di creare un tracker di mesh della scena.

L'applicazione deve utilizzare solo i set di etichette semantiche supportati dal sistema in XrSceneMeshingTrackerCreateInfoANDROID :: semanticLabelSet quando crea un tracker di mesh della scena. Se l'applicazione utilizza un insieme di etichette semantiche dei vertici della mesh della scena non supportato, il runtime deve restituire XR_ERROR_FEATURE_UNSUPPORTED da xrCreateSceneMeshingTrackerANDROID .

L'applicazione può enumerare l'elenco dei set di etichette semantiche supportati con la funzione xrEnumerateSupportedSemanticLabelSetsANDROID.

L'handle xrCreateSceneMeshingTrackerANDROID possiede tutte le risorse per la mesh della scena. Al termine dell'esperienza di mesh della scena, l'applicazione deve eliminare l'handle tramite la funzione xrDestroySceneMeshingTrackerANDROID.

Utilizzo valido (implicito)

Codici di ritorno

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • XR_ERROR_FEATURE_UNSUPPORTED
  • 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_VALIDATION_FAILURE

La struttura XrSceneMeshingTrackerCreateInfoANDROID è definita come:

typedef struct XrSceneMeshingTrackerCreateInfoANDROID {
    XrStructureType                       type;
    const void*                           next;
    XrSceneMeshSemanticLabelSetANDROID    semanticLabelSet;
    XrBool32                              enableNormals;
} XrSceneMeshingTrackerCreateInfoANDROID;

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.
  • semanticLabelSet è un XrSceneMeshSemanticLabelSetANDROID utilizzato per specificare il set di etichette semantiche da utilizzare per la creazione della mesh della scena. Se questo valore è impostato su XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID , il runtime ignorerà il campo buffer vertexSemantics di XrSceneSubmeshDataANDROID.
  • enableNormals è un XrBool32 utilizzato per specificare se includere le normali dei vertici per i vertici della mesh nel buffer della mesh della scena quando si recuperano i dati della mesh della scena.

La struttura XrSceneMeshingTrackerCreateInfoANDROID descrive le informazioni per creare un handle XrSceneMeshingTrackerANDROID.

Utilizzo valido (implicito)

La funzione xrDestroySceneMeshingTrackerANDROID è definita come:

XrResult xrDestroySceneMeshingTrackerANDROID(
    XrSceneMeshingTrackerANDROID                tracker);

Descrizioni dei parametri

La funzione xrDestroySceneMeshingTrackerANDROID rilascia tracker e le risorse sottostanti al termine delle esperienze di mesh della scena.

Utilizzo valido (implicito)

Thread Safety

  • L'accesso a tracker 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

Crea un handle dello snapshot della mesh della scena

XR_DEFINE_HANDLE(XrSceneMeshSnapshotANDROID)

L'handle XrSceneMeshSnapshotANDROID rappresenta uno snapshot della mesh della scena. Questo snapshot viene creato utilizzando xrCreateSceneMeshSnapshotANDROID, che acquisisce uno snapshot dei dati della mesh della scena al momento della chiamata di funzione.

Questo handle può essere utilizzato per recuperare informazioni e dati sulle submesh utilizzando xrGetAllSubmeshStatesANDROID e xrGetSubmeshDataANDROID .

La funzione xrCreateSceneMeshSnapshotANDROID è definita come:

XrResult xrCreateSceneMeshSnapshotANDROID(
    XrSceneMeshingTrackerANDROID                tracker,
    const XrSceneMeshSnapshotCreateInfoANDROID* createInfo,
    XrSceneMeshSnapshotCreationResultANDROID*   outSnapshotCreationResult);

Descrizioni dei parametri

L'applicazione può utilizzare la funzione xrCreateSceneMeshSnapshotANDROID per creare uno snapshot della mesh della scena dal tracker di mesh della scena. Questa funzione restituisce un handle XrSceneMeshSnapshotANDROID insieme a XrSceneMeshTrackingStateANDROID racchiuso in una struttura XrSceneMeshSnapshotCreationResultANDROID. L'handle è tecnicamente uno snapshot dei dati della mesh della scena al momento della creazione. Questo handle può essere utilizzato per eseguire query sulle informazioni e sui dati della mesh della scena utilizzando rispettivamente xrGetAllSubmeshStatesANDROID e xrGetSubmeshDataANDROID.

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_POSE_INVALID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID

La struttura XrSceneMeshSnapshotCreateInfoANDROID è definita come:

typedef struct XrSceneMeshSnapshotCreateInfoANDROID {
    XrStructureType    type;
    const void*        next;
    XrSpace            baseSpace;
    XrTime             time;
    XrBoxf             boundingBox;
} XrSceneMeshSnapshotCreateInfoANDROID;

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Non sono definite strutture di questo tipo in OpenXR di base o in questa estensione.
  • baseSpace è uno spazio XrSpace in cui sono rappresentate le informazioni sulla posa della mesh secondaria della scena.
  • time è il XrTime che descrive il momento in cui la mesh della scena verrà elaborata o visualizzata, in genere XrFrameState :: predictedDisplayTime .
  • boundingBox è un XrBoxf che descrive il riquadro di delimitazione all'interno del quale acquisire la mesh della scena.

La struttura XrSceneMeshSnapshotCreateInfoANDROID descrive le informazioni per creare un handle XrSceneMeshSnapshotANDROID

Utilizzo valido (implicito)

La struttura XrSceneMeshSnapshotCreationResultANDROID è definita come:

typedef struct XrSceneMeshSnapshotCreationResultANDROID {
    XrStructureType                    type;
    const void*                        next;
    XrSceneMeshSnapshotANDROID         snapshot;
    XrSceneMeshTrackingStateANDROID    trackingState;
} XrSceneMeshSnapshotCreationResultANDROID;

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.
  • snapshot è un handle XrSceneMeshSnapshotANDROID creato dal runtime.
  • trackingState è un XrSceneMeshTrackingStateANDROID che descrive lo stato del tracker di meshing della scena al momento della creazione dello snapshot.

La struttura XrSceneMeshSnapshotCreationResultANDROID memorizza il risultato della creazione di uno snapshot della mesh della scena restituito da xrCreateSceneMeshSnapshotANDROID .

Utilizzo valido (implicito)

L'enumerazione XrSceneMeshTrackingStateANDROID descrive lo stato di monitoraggio per un tracker di mesh della scena. Ogni valore di questa enumerazione rappresenta uno stato del tracker di meshing della scena.

typedef enum XrSceneMeshTrackingStateANDROID {
    XR_SCENE_MESH_TRACKING_STATE_INITIALIZING_ANDROID = 0,
    XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID = 1,
    XR_SCENE_MESH_TRACKING_STATE_WAITING_ANDROID = 2,
    XR_SCENE_MESH_TRACKING_STATE_ERROR_ANDROID = 3,
    XR_SCENE_MESH_TRACKING_STATE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSceneMeshTrackingStateANDROID;

I valori di enumerazione hanno i seguenti significati:

Descrizione enum

XR_SCENE_MESH_TRACKING_STATE_INITIALIZING_ANDROID

Il tracker non è ancora pronto per fornire i dati della mesh.

XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID

Il tracker sta monitorando attivamente.

XR_SCENE_MESH_TRACKING_STATE_WAITING_ANDROID

Il tracker è in attesa di misure valide da integrare dall'ultimo aggiornamento della mesh.

XR_SCENE_MESH_TRACKING_STATE_ERROR_ANDROID

Il tracker non ha ricevuto misurazioni valide per più cicli e si trova in stato di errore.

Questo stato funge solo da informazione aggiuntiva per la richiesta. In assenza di altre fonti di errori, il runtime deve continuare a consentire all'applicazione di creare snapshot e recuperare dati da questi indipendentemente dall'attuale XrSceneMeshTrackingStateANDROID del tracker. Se lo stato non è XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID , gli snapshot potrebbero non essere aggiornati o essere vuoti.

Acquisizione dei dati della mesh della scena dallo snapshot della mesh della scena

La funzione xrGetAllSubmeshStatesANDROID è definita come:

XrResult xrGetAllSubmeshStatesANDROID(
    XrSceneMeshSnapshotANDROID                  snapshot,
    uint32_t                                    submeshStateCapacityInput,
    uint32_t*                                   submeshStateCountOutput,
    XrSceneSubmeshStateANDROID*                 submeshStates);

Descrizioni dei parametri

  • snapshot è un handle XrSceneMeshSnapshotANDROID creato in precedenza con xrCreateSceneMeshSnapshotANDROID .
  • submeshStateCapacityInput è la capacità di submeshStates o 0 per recuperare la capacità richiesta.
  • submeshStateCountOutput è un puntatore al conteggio di submeshStates scritti o un puntatore alla capacità richiesta nel caso in cui submeshStateCapacityInput sia insufficiente.
  • submeshStates è un puntatore a un array di strutture XrSceneSubmeshStateANDROID a cui il runtime restituirà lo stato di tutte le submesh nella mesh della scena. Può essere NULL se submeshStateCapacityInput è 0.
  • Consulta il capitolo Parametri delle dimensioni del buffer per una descrizione dettagliata del recupero delle dimensioni submeshStates richieste.

L'applicazione può utilizzare la funzione xrGetAllSubmeshStatesANDROID per ottenere lo stato di tutte le submesh nella mesh della scena. Contiene informazioni di base per consentire all'applicazione di selezionare le mesh secondarie per le quali vuole i dati.

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

La struttura XrSceneSubmeshStateANDROID è definita come:

typedef struct XrSceneSubmeshStateANDROID {
    XrStructureType    type;
    void*              next;
    XrUuid             submeshId;
    XrTime             lastUpdatedTime;
    XrPosef            submeshPoseInBaseSpace;
    XrExtent3Df        bounds;
} XrSceneSubmeshStateANDROID;

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.
  • submeshId è un XrUuid che identifica la submesh.
  • lastUpdatedTime è un XrTime che rappresenta l'ora dell'ultimo aggiornamento della submesh.
  • submeshPoseInBaseSpace è un XrPosef che rappresenta la posa della submesh nello spazio di base utilizzato per creare lo snapshot della mesh della scena. La posa è anche il centro del riquadro di delimitazione della submesh.
  • bounds è un XrExtent3Df che descrive le dimensioni del riquadro di delimitazione che racchiude la submesh. Questi limiti sono definiti nello spazio di base utilizzato per creare l'handle della mesh della scena.

Il runtime fa del suo meglio per mappare submeshId con la regione dello spazio fisico occupato dalla submesh. I runtime potrebbero perdere questa mappatura in qualsiasi momento e assegnare un nuovo UUID a qualsiasi sottoinsieme delle submesh rilevate. In particolare, i runtime non sono tenuti a riutilizzare gli stessi UUID per le stesse mesh nelle istanze dell'applicazione successive.

Utilizzo valido (implicito)

La funzione xrGetSubmeshDataANDROID è definita come:

XrResult xrGetSubmeshDataANDROID(
    XrSceneMeshSnapshotANDROID                  snapshot,
    uint32_t                                    submeshDataCount,
    XrSceneSubmeshDataANDROID*                  inoutSubmeshData);

Descrizioni dei parametri

L'applicazione può utilizzare la funzione xrGetSubmeshDataANDROID per ottenere batch di submesh o tutte le submesh contemporaneamente, passando un elenco di XrSceneSubmeshDataANDROID con ogni XrSceneSubmeshDataANDROID :: submeshId impostato sull'ID rispettivo della submesh da recuperare.

XrSceneSubmeshDataANDROID :: submeshId must be unique for every element in inoutSubmeshData and retrievable by xrGetAllSubmeshStatesANDROID for the same snapshot . Se l'ID submesh non è valido o più elementi in inoutSubmeshData hanno lo stesso ID submesh, il runtime deve restituire XR_ERROR_VALIDATION_FAILURE .

submeshDataCount deve essere uguale o inferiore al valore restituito da xrGetAllSubmeshStatesANDROID :: submeshStateCountOutput , altrimenti il runtime deve restituire XR_ERROR_VALIDATION_FAILURE .

Questo può essere utilizzato in un idioma a due chiamate per eseguire query sul conteggio di vertici e indici per tutte le submesh selezionate.

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

La struttura XrSceneSubmeshDataANDROID è definita come:

typedef struct XrSceneSubmeshDataANDROID {
    XrStructureType    type;
    const void*        next;
    XrUuid             submeshId;
    uint32_t           vertexCapacityInput;
    uint32_t           vertexCountOutput;
    XrVector3f*        vertexPositions;
    XrVector3f*        vertexNormals;
    uint8_t*           vertexSemantics;
    uint32_t           indexCapacityInput;
    uint32_t           indexCountOutput;
    uint32_t*          indices;
} XrSceneSubmeshDataANDROID;

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.
  • submeshId è un XrUuid che identifica la submesh.
  • vertexCapacityInput è la capacità di vertexPositions, vertexNormals e vertexSemantics o 0 per recuperare la capacità richiesta.
  • vertexCountOutput è un puntatore al conteggio di vertexPositions, vertexNormals e vertexSemantics scritti oppure un puntatore alla capacità richiesta nel caso in cui vertexCapacityInput sia insufficiente.
  • vertexPositions è un array di XrVector3f in cui il runtime restituirà le posizioni dei vertici della submesh.
  • vertexNormals è un array di XrVector3f in cui il runtime restituirà le normali dei vertici della submesh. Questo campo può essere lasciato NULL se l'applicazione ha creato un tracker con le normali disattivate.
  • vertexSemantics è un array di uint8_t in cui il runtime restituirà la semantica dei vertici della submesh. Questo campo può essere lasciato NULL se l'applicazione ha creato un tracker con un set di etichette semantiche XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID.
  • indexCapacityInput è la capacità di indices o 0 per recuperare la capacità richiesta.
  • indexCountOutput è un puntatore al conteggio di indices scritti o un puntatore alla capacità richiesta nel caso in cui vertexCapacityInput sia insufficiente.
  • indices è un array di uint32_t in cui il runtime restituirà gli indici della submesh.
  • Consulta il capitolo Parametri delle dimensioni del buffer per una descrizione dettagliata del recupero delle dimensioni richieste di vertexPositions, vertexNormals, vertexSemantics e indices.

Utilizzo valido (implicito)

  • L'estensione XR_ANDROID_scene_meshing deve essere attivata prima di utilizzare XrSceneSubmeshDataANDROID
  • type deve essere XR_TYPE_SCENE_SUBMESH_DATA_ANDROID
  • next deve essere NULL o un puntatore valido alla struttura successiva in una catena di strutture
  • Se vertexCapacityInput non è 0 , vertexPositions deve essere un puntatore a un array di strutture vertexCapacityInput XrVector3f
  • Se vertexCapacityInput non è 0 , vertexNormals deve essere un puntatore a un array di strutture vertexCapacityInput XrVector3f
  • Se vertexCapacityInput non è 0 , vertexSemantics deve essere un puntatore a un array di valori vertexCapacityInput uint8_t
  • Se indexCapacityInput non è 0 , indices deve essere un puntatore a un array di valori indexCapacityInput uint32_t

L'enumerazione XrSceneMeshSemanticLabelANDROID è l'insieme predefinito di etichette semantiche che possono essere utilizzate per etichettare i vertici della mesh per descrivere su quale superficie dell'ambiente fisico si trova il vertice della mesh. Questo set di enum è rappresentato dal valore XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID in XrSceneMeshSemanticLabelSetANDROID .

typedef enum XrSceneMeshSemanticLabelANDROID {
    XR_SCENE_MESH_SEMANTIC_LABEL_OTHER_ANDROID = 0,
    XR_SCENE_MESH_SEMANTIC_LABEL_FLOOR_ANDROID = 1,
    XR_SCENE_MESH_SEMANTIC_LABEL_CEILING_ANDROID = 2,
    XR_SCENE_MESH_SEMANTIC_LABEL_WALL_ANDROID = 3,
    XR_SCENE_MESH_SEMANTIC_LABEL_TABLE_ANDROID = 4,
    XR_SCENE_MESH_SEMANTIC_LABEL_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSceneMeshSemanticLabelANDROID;

Gli enum hanno i seguenti significati:

Descrizione enum

XR_SCENE_MESH_SEMANTIC_LABEL_OTHER_ANDROID

Questa etichetta semantica indica che l'elemento mesh corrispondente rappresenta un oggetto sconosciuto.

XR_SCENE_MESH_SEMANTIC_LABEL_FLOOR_ANDROID

Questa etichetta semantica indica che l'elemento mesh corrispondente rappresenta un pavimento.

XR_SCENE_MESH_SEMANTIC_LABEL_CEILING_ANDROID

Questa etichetta semantica indica che l'elemento mesh corrispondente rappresenta un soffitto.

XR_SCENE_MESH_SEMANTIC_LABEL_WALL_ANDROID

Questa etichetta semantica indica che l'elemento mesh corrispondente rappresenta una parete.

XR_SCENE_MESH_SEMANTIC_LABEL_TABLE_ANDROID

Questa etichetta semantica indica che l'elemento mesh corrispondente rappresenta una tabella.

Eliminare uno snapshot della mesh della scena

La funzione xrDestroySceneMeshSnapshotANDROID è definita come:

XrResult xrDestroySceneMeshSnapshotANDROID(
    XrSceneMeshSnapshotANDROID                  snapshot);

Descrizioni dei parametri

L'applicazione può utilizzare la funzione xrDestroySceneMeshSnapshotANDROID per eliminare uno snapshot della mesh della scena. Una volta distrutto l'handle, l'applicazione non può più utilizzarlo per ottenere informazioni o dati sulla submesh. L'handle viene eliminato automaticamente quando viene eliminato il tracker perché l'handle del tracker è il genitore dell'handle dello snapshot della mesh della scena.

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

Codice di esempio per la creazione di mesh della scena

Il seguente codice di esempio mostra come accedere ai dati della mesh della scena per il rendering.

XrInstance instance;  // Created at app startup
XrSystemId systemId;  // Received from xrGetSystem() at app startup
XrSession session;    // Created at app startup
XrSpace appPlaySpace; // Created at app startup

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrCreateSceneMeshingTrackerANDROID xrCreateSceneMeshingTrackerANDROID;
PFN_xrDestroySceneMeshingTrackerANDROID xrDestroySceneMeshingTrackerANDROID;
PFN_xrEnumerateSupportedSemanticLabelSetsANDROID xrEnumerateSupportedSemanticLabelSetsANDROID;
PFN_xrCreateSceneMeshSnapshotANDROID xrCreateSceneMeshSnapshotANDROID;
PFN_xrDestroySceneMeshSnapshotANDROID xrDestroySceneMeshSnapshotANDROID;
PFN_xrGetAllSubmeshStatesANDROID xrGetAllSubmeshStatesANDROID;
PFN_xrGetSubmeshDataANDROID xrGetSubmeshDataANDROID;

// Inspect system capability
XrSystemSceneMeshingPropertiesANDROID sceneMeshingProps = {
  .type = XR_TYPE_SYSTEM_SCENE_MESHING_PROPERTIES_ANDROID,
};
XrSystemProperties sysProps = {
  .type = XR_TYPE_SYSTEM_PROPERTIES,
  .next = &sceneMeshingProps
};
CHK_XR(xrGetSystemProperties(instance, systemId, &sysProps));
if (!sceneMeshingProps.supportsSceneMeshing) {
    // scene meshing is not supported.
    return;
}

uint32_t supportedsemanticLabelSetsCount = 0;
xrEnumerateSupportedSemanticLabelSetsANDROID(
  instance, systemId, 0, &supportedsemanticLabelSetsCount, nullptr);
std::vector<XrSceneMeshSemanticLabelSetANDROID> supportedSemanticLabelSets(
  supportedsemanticLabelSetsCount);
xrEnumerateSupportedSemanticLabelSetsANDROID(
  instance, systemId, supportedsemanticLabelSetsCount,
  &supportedsemanticLabelSetsCount, supportedSemanticLabelSets.data());

XrSceneMeshSemanticLabelSetANDROID semanticLabelSet = XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID;
// Check if system supports XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID
if (std::find(supportedSemanticLabelSets.begin(), supportedSemanticLabelSets.end(),
              XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID) !=
    supportedSemanticLabelSets.end()) {
  semanticLabelSet = XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID;
}

XrSceneMeshingTrackerCreateInfoANDROID trackerCreateInfo = {
  .type = XR_TYPE_SCENE_MESHING_TRACKER_CREATE_INFO_ANDROID,
  .semanticLabelSet = semanticLabelSet,
  .enableNormals = XR_TRUE
};

XrSceneMeshingTrackerANDROID tracker = XR_NULL_HANDLE;
CHK_XR(xrCreateSceneMeshingTrackerANDROID(session, &trackerCreateInfo, &tracker));

XrSceneMeshSnapshotCreationResultANDROID snapshotResult {
  .type = XR_TYPE_SCENE_MESH_SNAPSHOT_CREATION_RESULT_ANDROID,
  .snapshot = XR_NULL_HANDLE
};
XrSceneMeshSnapshotANDROID& snapshot = snapshotResult.snapshot;
XrSceneMeshSnapshotCreateInfoANDROID createInfo {
  .type = XR_TYPE_SCENE_MESH_SNAPSHOT_CREATE_INFO_ANDROID
};

// app update loop
while (true) {
  // ...
  // For every frame in frame loop
  // ...

  XrFrameState frameState; // previously returned from xrWaitFrame
  const XrTime time = frameState.predictedDisplayTime;
  XrBoxf box; // populated with the bounding box of the camera frustum

  // ...

  createInfo.baseSpace = appPlaySpace;
  createInfo.time = time;
  createInfo.boundingBox = box;

  // Grab the scene mesh snapshot. This way the app can: know all of the submesh infos,
  // choose the appropriate submeshes for which to get data, allocate the necessary
  // buffer for those submeshes, and then get the data.
  CHK_XR(xrCreateSceneMeshSnapshotANDROID(tracker, &createInfo, &snapshotResult));

  // check the tracking state
  if (snapshotResult.trackingState == XR_SCENE_MESH_TRACKING_STATE_ERROR_ANDROID) {
    // unrecoverable error. Exit the app.
    if (snapshot != XR_NULL_HANDLE) {
      CHK_XR(xrDestroySceneMeshSnapshotANDROID(snapshot));
      snapshot = XR_NULL_HANDLE;
    }
    break;
  } else if (snapshotResult.trackingState != XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID) {
    // The tracker is not tracking. Try again later.
    if (snapshot != XR_NULL_HANDLE) {
      CHK_XR(xrDestroySceneMeshSnapshotANDROID(snapshot));
      snapshot = XR_NULL_HANDLE;
    }
    continue;
  }

  // 2-call idiom for getting submesh states
  uint32_t submeshCount = 0;
  CHK_XR(xrGetAllSubmeshStatesANDROID(snapshot, 0, &submeshCount, nullptr));
  std::vector<XrSceneSubmeshStateANDROID> states(submeshCount, {
    .type = XR_TYPE_SCENE_SUBMESH_STATE_ANDROID,
  });
  CHK_XR(xrGetAllSubmeshStatesANDROID(snapshot, submeshCount, &submeshCount, states.data()));

  // To store the poses for the selected submeshes
  std::vector<XrPosef> submeshesPoses;
  submeshesPoses.reserve(submeshCount);

  std::vector<XrSceneSubmeshDataANDROID> submeshes;
  submeshes.reserve(submeshCount);
  // Iterate the states and determine which submeshes the app wants data for
  for (XrSceneSubmeshStateANDROID& state : states) {
    // Modify this bool as necessary by looking at states. Maybe state.lastUpdatedTime
    // is below a threshold or maybe the bounding box does not intersect with camera view
    // frustum (The submesh will be culled).
    bool needed;
    if (needed) {
      // Add the selected submesh to the submeshes list. Set the capacity
      // zero for now since the size of the buffer will be determined later.
      XrSceneSubmeshDataANDROID submesh {
        .type = XR_TYPE_SCENE_SUBMESH_DATA_ANDROID,
        .submeshId = state.submeshId,
        .vertexCapacityInput = 0,
        .vertexCountOutput = 0,
        .vertexPositions = nullptr,
        .vertexNormals = nullptr,
        .vertexSemantics = nullptr,
        .indexCapacityInput = 0,
        .indexCountOutput = 0,
        .indices = nullptr,
      };
      submeshes.push_back(submesh);
      submeshesPoses.push_back(state.submeshPoseInBaseSpace);
    }
  }

  // Grab the data for the selected submeshes using the 2-call idiom.
  CHK_XR(xrGetSubmeshDataANDROID(snapshot, submeshes.size(), submeshes.data()));
  for (XrSceneSubmeshDataANDROID& submesh : submeshes) {
    submesh.vertexCapacityInput = submesh.vertexCountOutput;
    submesh.vertexCountOutput = 0;
    submesh.vertexPositions = new XrVector3f[submesh.vertexCapacityInput];
    submesh.vertexNormals = new XrVector3f[submesh.vertexCapacityInput];
    submesh.vertexSemantics = new uint8_t[submesh.vertexCapacityInput];
    submesh.indexCapacityInput = submesh.indexCountOutput;
    submesh.indexCountOutput = 0;
    submesh.indices = new uint32_t[submesh.indexCapacityInput];
  }
  CHK_XR(xrGetSubmeshDataANDROID(snapshot, submeshes.size(), submeshes.data()));

  // Destroy the scene mesh snapshot since we have finally grabbed the submeshes data. In
  // next iteration app can: create a new one to get latest mesh data
  CHK_XR(xrDestroySceneMeshSnapshotANDROID(snapshot));
  snapshot = XR_NULL_HANDLE;

  // Iterate the submeshes and get the vertex positions, vertex normals and
  // vertex semantics data for the selected submeshes
  for (uint32_t i = 0; i < submeshes.size(); i++) {
    XrSceneSubmeshDataANDROID& data = submeshes[i];
    XrVector3f* vertexPositions = data.vertexPositions;
    XrVector3f* vertexNormals = data.vertexNormals;
    XrSceneMeshSemanticLabelANDROID* vertexSemantics =
      new XrSceneMeshSemanticLabelANDROID[data.vertexCountOutput];
    for (uint32_t j = 0; j < data.vertexCountOutput; j++) {
      vertexSemantics[j] =
        static_cast<XrSceneMeshSemanticLabelANDROID>(data.vertexSemantics[j]);
    }
    XrPosef pose = submeshesPoses[i];

    // *** Use the data as per needs ***

    // Release the allocated memory for the data buffers when done using
    delete [] vertexSemantics;
    delete [] data.vertexPositions;
    delete [] data.vertexNormals;
    delete [] data.vertexSemantics;
    delete [] data.indices;
  }

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

CHK_XR(xrDestroySceneMeshingTrackerANDROID(tracker));

Nuovi tipi di oggetti

Nuovi comandi

Nuove strutture

Nuovi enum

Nuove costanti enum

  • XR_ANDROID_SCENE_MESHING_EXTENSION_NAME
  • XR_ANDROID_scene_meshing_SPEC_VERSION

  • Estensione di XrObjectType :

    • XR_OBJECT_TYPE_SCENE_MESHING_TRACKER_ANDROID
    • XR_OBJECT_TYPE_SCENE_MESH_SNAPSHOT_ANDROID

  • Estensione di XrStructureType :

    • XR_TYPE_SCENE_MESHING_TRACKER_CREATE_INFO_ANDROID
    • XR_TYPE_SCENE_MESH_SNAPSHOT_CREATE_INFO_ANDROID
    • XR_TYPE_SCENE_MESH_SNAPSHOT_CREATION_RESULT_ANDROID
    • XR_TYPE_SCENE_SUBMESH_DATA_ANDROID
    • XR_TYPE_SCENE_SUBMESH_STATE_ANDROID
    • XR_TYPE_SYSTEM_SCENE_MESHING_PROPERTIES_ANDROID

Problemi

Cronologia delle versioni

  • Revisione 3, 15/05/2025 (Salar Khan)

    • Descrizione iniziale dell'estensione