XR_ANDROID_scene_meshing

Name String

XR_ANDROID_scene_meshing

Tipo di estensione

Estensione dell'istanza

Numero di interno registrato

719

Revisione

3

Stato della ratifica

Non ratificato

Dipendenze di estensioni e versioni

OpenXR 1.0

Data ultima modifica

2025-05-15

Stato IP

Nessuna rivendicazione di PI 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 gli oggetti fisici, ad esempio le 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 mesh secondarie della scena tramite XrSceneSubmeshStateANDROID restituito da xrGetAllSubmeshStatesANDROID . Le applicazioni possono accedere ai valori nei dati della mesh secondaria della scena tramite XrSceneSubmeshDataANDROID restituito da xrGetSubmeshDataANDROID .

I dati di meshing della scena sono informazioni personali sensibili e sono strettamente legati alla privacy e all'integrità personali. Consigliamo vivamente alle applicazioni che archiviano o trasferiscono dati di mesh della scena di chiedere sempre all'utente l'accettazione attiva e specifica per farlo.

Autorizzazioni

Le app per Android devono disporre dell'autorizzazione android.permission.SCENE_UNDERSTANDING_FINE elencata nel loro 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. Nessuna struttura di questo tipo è definita in OpenXR di base o in questa estensione.
  • supportsSceneMeshing è un XrBool32 che indica se il sistema supporta la mesh della scena.

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

Se un runtime restituisce XR_FALSE per supportsSceneMeshing, il sistema non supporta la mesh della scena e pertanto deve restituire XR_ERROR_FEATURE_UNSUPPORTED da xrCreateSceneMeshingTrackerANDROID . L'applicazione dovrebbe 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 mesh della scena.

Utilizzo valido (implicito)

L'enumerazione XrSceneMeshSemanticLabelSetANDROID descrive gli insiemi di etichette semantiche per la mesh della scena. Ogni valore in questo enum rappresenta un altro enum che contiene le etichette semantiche. Ad esempio, il valore XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID rappresenta l'insieme 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_DEFAULT2_ANDROID = 1000801000,
    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.

XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT2_ANDROID

Questo set di etichette semantiche rappresenta XrSceneMeshSemanticLabel2ANDROID. (Aggiunto dall'estensione XR_ANDROID_scene_meshing_semantic_label2)

La funzione xrEnumerateSupportedSemanticLabelSetsANDROID è definita come segue:

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 ritentato 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 non sia sufficiente.
  • 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 della dimensione supportedSemanticLabelSets richiesta.

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 richieda la semantica dei vertici.

Utilizzo valido (implicito)

  • L'estensione XR_ANDROID_scene_meshing deve essere abilitata 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 risposta

Operazione riuscita

  • XR_SUCCESS

Errore

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SYSTEM_INVALID
  • XR_ERROR_VALIDATION_FAILURE

Crea un handle del tracker di meshing della scena

XR_DEFINE_HANDLE(XrSceneMeshingTrackerANDROID)

L'handle XrSceneMeshingTrackerANDROID rappresenta un tracker di meshing della scena per il meshing 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 meshing della scena.

L'applicazione deve utilizzare solo i set di etichette semantiche supportati dal sistema in XrSceneMeshingTrackerCreateInfoANDROID :: semanticLabelSet durante la creazione di un tracker di meshing 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 meshing della scena, l'applicazione deve eliminare l'handle tramite la funzione xrDestroySceneMeshingTrackerANDROID.

Utilizzo valido (implicito)

Codici di risposta

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. Nessuna struttura di questo tipo è definita in OpenXR di base o in questa estensione.
  • semanticLabelSet è un XrSceneMeshSemanticLabelSetANDROID utilizzato per specificare l'insieme di etichette semantiche da utilizzare per la mesh della scena. Se questo valore è impostato su XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID , il runtime ignorerà il campo buffer XrSceneSubmeshDataANDROID :: vertexSemantics.
  • 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 segue:

XrResult xrDestroySceneMeshingTrackerANDROID(
    XrSceneMeshingTrackerANDROID                tracker);

Descrizioni dei parametri

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

Utilizzo valido (implicito)

Thread safety

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

Codici di risposta

Operazione riuscita

  • XR_SUCCESS

Errore

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Crea un handle di 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 sulla mesh secondaria utilizzando xrGetAllSubmeshStatesANDROID e xrGetSubmeshDataANDROID .

La funzione xrCreateSceneMeshSnapshotANDROID è definita come segue:

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 della 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 risposta

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_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. Nessuna struttura di questo tipo è definita in OpenXR di base o in questa estensione.
  • baseSpace è un XrSpace all'interno del quale vengono 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. Nessuna struttura di questo tipo è definita 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 di un tracker di mesh della scena. Ogni valore di questo enum 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 misurazioni 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 ed è in stato di errore.

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

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

La funzione xrGetAllSubmeshStatesANDROID è definita come segue:

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 non sia sufficiente.
  • submeshStates è un puntatore a un array di strutture XrSceneSubmeshStateANDROID in cui il runtime restituirà lo stato di tutte le mesh secondarie nella mesh della scena. Può essere NULL se submeshStateCapacityInput è 0.
  • Consulta il capitolo Parametri delle dimensioni del buffer per una descrizione dettagliata del recupero della dimensione submeshStates richiesta.

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

Utilizzo valido (implicito)

Codici di risposta

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_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. Nessuna struttura di questo tipo è definita in OpenXR di base o in questa estensione.
  • submeshId è un XrUuid che identifica la mesh secondaria.
  • lastUpdatedTime è un XrTime che rappresenta l'ora dell'ultimo aggiornamento della mesh secondaria.
  • submeshPoseInBaseSpace è un XrPosef che rappresenta la posa della mesh secondaria nello spazio di base utilizzato per creare lo snapshot della mesh della scena. La posa è anche il centro del riquadro di delimitazione della mesh secondaria.
  • bounds è un XrExtent3Df che descrive le dimensioni del riquadro di delimitazione che racchiude la mesh secondaria. 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 mesh secondaria. I runtime possono perdere questa mappatura in qualsiasi momento e assegnare un nuovo UUID a qualsiasi sottoinsieme delle mesh secondarie 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 gruppi di mesh secondarie o tutte le mesh secondarie contemporaneamente, passando un elenco di XrSceneSubmeshDataANDROID con ogni XrSceneSubmeshDataANDROID :: submeshId impostato sull'ID rispettivo della mesh secondaria da recuperare.

XrSceneSubmeshDataANDROID :: submeshId deve essere univoco per ogni elemento in inoutSubmeshData e recuperabile da xrGetAllSubmeshStatesANDROID per lo stesso snapshot . Se l'ID della mesh secondaria non è valido o più elementi in inoutSubmeshData hanno lo stesso ID della mesh secondaria, il runtime deve restituire XR_ERROR_VALIDATION_FAILURE .

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

Questo può essere utilizzato in un idioma a 2 chiamate per eseguire query sul numero di vertici e indici per tutte le mesh secondarie selezionate.

Utilizzo valido (implicito)

Codici di risposta

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_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. Nessuna struttura di questo tipo è definita in OpenXR di base o in questa estensione.
  • submeshId è un XrUuid che identifica la mesh secondaria.
  • 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 o 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 mesh secondaria.
  • vertexNormals è un array di XrVector3f in cui il runtime restituirà le normali dei vertici della mesh secondaria. 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 mesh secondaria. Questo campo può essere lasciato NULL se l'applicazione ha creato un tracker con l'etichetta semantica XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID impostata.
  • 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 non sia sufficiente.
  • indices è un array di uint32_t in cui il runtime restituirà gli indici della mesh secondaria.
  • Consulta il capitolo Parametri delle dimensioni del buffer per una descrizione dettagliata del recupero delle dimensioni richieste per vertexPositions, vertexNormals, vertexSemantics e indices.

Utilizzo valido (implicito)

  • L'estensione XR_ANDROID_scene_meshing deve essere abilitata 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 la superficie dell'ambiente fisico su cui 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 un muro.

XR_SCENE_MESH_SEMANTIC_LABEL_TABLE_ANDROID

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

Elimina 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 eliminato l'handle, l'applicazione non può più utilizzarlo per ottenere informazioni o dati sulla mesh secondaria. L'handle viene eliminato automaticamente quando viene eliminato il tracker, perché l'handle del tracker è l'elemento principale dell'handle dello snapshot della mesh della scena.

Utilizzo valido (implicito)

Thread safety

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

Codici di risposta

Operazione riuscita

  • XR_SUCCESS

Errore

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Codice di esempio per la 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 maggio 2025 (Salar Khan)

    • Descrizione iniziale dell'estensione