XR_ANDROID_scene_meshing

Name String

XR_ANDROID_scene_meshing

Type d'extension

Extension d'instance

Numéro d'extension enregistré

719

Révision

3

État de la ratification

Non ratifié

Dépendances d'extension et de version

OpenXR 1.0

Date de dernière modification

2025-05-15

État de l'adresse IP

Aucune réclamation de propriété intellectuelle connue.

Participants

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

Présentation

Cette extension est destinée à fournir des maillages qui représentent approximativement les objets physiques dans l'environnement de l'utilisateur.

Les applications peuvent utiliser cette extension pour visualiser la scène et permettre aux objets virtuels d'interagir avec des objets physiques, par exemple lors de collisions.

Les données de maillage de la scène sont générées par l'environnement d'exécution et partagées avec l'application à l'aide de XrSceneMeshingTrackerANDROID et XrSceneMeshSnapshotANDROID . Les applications peuvent accéder aux valeurs des informations sur les sous-maillages de la scène via XrSceneSubmeshStateANDROID renvoyé par xrGetAllSubmeshStatesANDROID . Les applications peuvent accéder aux valeurs des données de sous-maillage de scène via XrSceneSubmeshDataANDROID renvoyé par xrGetSubmeshDataANDROID .

Les données de maillage de scène sont des informations personnelles sensibles et sont étroitement liées à la confidentialité et à l'intégrité des données personnelles. Il est vivement recommandé que les applications qui stockent ou transfèrent des données de maillage de scène demandent toujours à l'utilisateur d'accepter activement et spécifiquement cette opération.

Autorisations

Les applications Android doivent inclure l'autorisation android.permission.SCENE_UNDERSTANDING_FINE dans leur fichier manifeste. L'autorisation android.permission.SCENE_UNDERSTANDING_FINE est considérée comme une autorisation sensible, car elle permet à l'environnement d'exécution d'étudier l'environnement de l'utilisateur.

L'application doit demander l'autorisation au moment de l'exécution pour utiliser ces fonctions :

(niveau de protection : dangereux)

Inspecter les capacités du système

La structure XrSystemSceneMeshingPropertiesANDROID est définie comme suit :

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

Descriptions des membres

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures. Aucune structure de ce type n'est définie dans OpenXR de base ou dans cette extension.
  • supportsSceneMeshing est un XrBool32 qui indique si le système est compatible avec le maillage de scène.

Une application peut vérifier si le système est capable de mailler une scène en associant une structure XrSystemSceneMeshingPropertiesANDROID à XrSystemProperties lors de l'appel de xrGetSystemProperties .

Si un environnement d'exécution renvoie XR_FALSE pour supportsSceneMeshing, le système n'est pas compatible avec le maillage de scène et doit donc renvoyer XR_ERROR_FEATURE_UNSUPPORTED à partir de xrCreateSceneMeshingTrackerANDROID . L'application doit éviter d'utiliser la fonctionnalité de maillage de scène lorsque supportsSceneMeshing est défini sur XR_FALSE .

Si un environnement d'exécution renvoie XR_TRUE pour supportsSceneMeshing , le système est compatible avec le maillage de scène.

Utilisation valide (implicite)

L'énumération XrSceneMeshSemanticLabelSetANDROID décrit les ensembles d'étiquettes sémantiques pour le maillage de scène. Chaque valeur de cette énumération représente une autre énumération contenant les étiquettes sémantiques. Par exemple, la valeur XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID représente l'ensemble 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;

Les valeurs d'énumération ont les significations suivantes :

Description de l'enum

XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID

Ce groupe de libellés sémantiques représente l'absence de libellés sémantiques.

XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID

Cet ensemble de libellés sémantiques représente XrSceneMeshSemanticLabelANDROID.

XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT2_ANDROID

Cet ensemble de libellés sémantiques représente XrSceneMeshSemanticLabel2ANDROID. (Ajouté par l'extension XR_ANDROID_scene_meshing_semantic_label2)

La fonction xrEnumerateSupportedSemanticLabelSetsANDROID est définie comme suit :

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

Description des paramètres

  • instance est une XrInstance créée par l'application.
  • systemId est un XrSystemId relancé à partir de xrGetSystem .
  • supportedSemanticLabelSetsInputCapacity est la capacité de supportedSemanticLabelSets , ou 0 pour récupérer la capacité requise.
  • supportedSemanticLabelSetsOutputCount est un pointeur vers le nombre de supportedSemanticLabelSets écrits, ou un pointeur vers la capacité requise si supportedSemanticLabelSetsInputCapacity est insuffisant.
  • supportedSemanticLabelSets est un pointeur vers un tableau de XrSceneMeshSemanticLabelSetANDROID . Il peut être NULL si supportedSemanticLabelSetsInputCapacity est égal à 0.
  • Consultez le chapitre Paramètres de taille de la mémoire tampon pour obtenir une description détaillée de la récupération de la taille supportedSemanticLabelSets requise.

L'application peut énumérer les ensembles d'étiquettes sémantiques compatibles avec le système à l'aide de la fonction xrEnumerateSupportedSemanticLabelSetsANDROID.

Chaque système doit au moins accepter XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID, car cette valeur d'énumération ne représente aucun ensemble d'étiquettes sémantiques et peut être utilisée si l'application n'a pas besoin de sémantique de sommet.

Utilisation valide (implicite)

  • L'extension XR_ANDROID_scene_meshing doit être activée avant d'appeler xrEnumerateSupportedSemanticLabelSetsANDROID.
  • instance doit être un handle XrInstance valide
  • supportedSemanticLabelSetsOutputCount doit être un pointeur vers une valeur uint32_t
  • Si supportedSemanticLabelSetsInputCapacity n'est pas 0 , supportedSemanticLabelSets doit être un pointeur vers un tableau de valeurs supportedSemanticLabelSetsInputCapacity XrSceneMeshSemanticLabelSetANDROID.

Codes renvoyés

Opération réussie

  • XR_SUCCESS

Échec

  • 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

Créer un handle de suivi de maillage de scène

XR_DEFINE_HANDLE(XrSceneMeshingTrackerANDROID)

Le handle XrSceneMeshingTrackerANDROID représente un outil de suivi de maillage de scène pour le maillage de scène et la gestion des ressources associées.

Ce handle peut être utilisé pour créer un instantané de maillage de scène à l'aide de xrCreateSceneMeshSnapshotANDROID dans cette extension.

La fonction xrCreateSceneMeshingTrackerANDROID est définie comme suit :

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

Description des paramètres

Une application peut créer un handle XrSceneMeshingTrackerANDROID à l'aide de la fonction xrCreateSceneMeshingTrackerANDROID.

Si le système n'est pas compatible avec le maillage de scène, l'environnement d'exécution doit renvoyer XR_ERROR_FEATURE_UNSUPPORTED à partir de xrCreateSceneMeshingTrackerANDROID . Dans ce cas, l'environnement d'exécution doit renvoyer XR_FALSE pour XrSystemSceneMeshingPropertiesANDROID :: supportsSceneMeshing lorsque la fonction xrGetSystemProperties est appelée, afin que l'application puisse éviter de créer un outil de suivi du maillage de scène.

L'application doit utiliser uniquement les ensembles d'étiquettes sémantiques compatibles avec le système dans XrSceneMeshingTrackerCreateInfoANDROID :: semanticLabelSet lors de la création d'un outil de suivi de maillage de scène. Si l'application utilise un ensemble d'étiquettes sémantiques de sommet de maillage de scène non compatible, l'environnement d'exécution doit renvoyer XR_ERROR_FEATURE_UNSUPPORTED à partir de xrCreateSceneMeshingTrackerANDROID .

L'application peut énumérer la liste des ensembles d'étiquettes sémantiques compatibles avec la fonction xrEnumerateSupportedSemanticLabelSetsANDROID.

Le handle xrCreateSceneMeshingTrackerANDROID possède toutes les ressources pour le maillage de scène. Une fois l'expérience de maillage de scène terminée, l'application doit détruire le handle via la fonction xrDestroySceneMeshingTrackerANDROID.

Utilisation valide (implicite)

Codes renvoyés

Opération réussie

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Échec

  • 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 structure XrSceneMeshingTrackerCreateInfoANDROID est définie comme suit :

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

Descriptions des membres

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures. Aucune structure de ce type n'est définie dans OpenXR de base ou dans cette extension.
  • semanticLabelSet est un XrSceneMeshSemanticLabelSetANDROID utilisé pour spécifier l'ensemble d'étiquettes sémantiques à utiliser pour le maillage de la scène. Si ce champ est défini sur XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID , l'environnement d'exécution ignore le champ de tampon XrSceneSubmeshDataANDROID :: vertexSemantics.
  • enableNormals est un XrBool32 utilisé pour spécifier s'il faut inclure les normales de sommet pour les sommets du maillage dans le tampon de maillage de la scène lors de l'obtention des données de maillage de la scène.

La structure XrSceneMeshingTrackerCreateInfoANDROID décrit les informations permettant de créer un handle XrSceneMeshingTrackerANDROID.

Utilisation valide (implicite)

La fonction xrDestroySceneMeshingTrackerANDROID est définie comme suit :

XrResult xrDestroySceneMeshingTrackerANDROID(
    XrSceneMeshingTrackerANDROID                tracker);

Description des paramètres

La fonction xrDestroySceneMeshingTrackerANDROID libère le tracker et les ressources sous-jacentes une fois les expériences de maillage de scène terminées.

Utilisation valide (implicite)

Thread safety

  • L'accès à tracker et à tous les handles enfants doit être synchronisé en externe.

Codes renvoyés

Opération réussie

  • XR_SUCCESS

Échec

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Créer un handle d'instantané de maillage de scène

XR_DEFINE_HANDLE(XrSceneMeshSnapshotANDROID)

Le handle XrSceneMeshSnapshotANDROID représente un instantané de maillage de scène. Cet instantané est créé à l'aide de xrCreateSceneMeshSnapshotANDROID, qui prend un instantané des données de maillage de la scène au moment de l'appel de fonction.

Ce handle peut être utilisé pour récupérer des informations et des données sur les sous-maillages à l'aide de xrGetAllSubmeshStatesANDROID et xrGetSubmeshDataANDROID .

La fonction xrCreateSceneMeshSnapshotANDROID est définie comme suit :

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

Description des paramètres

L'application peut utiliser la fonction xrCreateSceneMeshSnapshotANDROID pour créer un instantané de maillage de scène à partir du tracker de maillage de scène. Cette fonction renvoie un handle XrSceneMeshSnapshotANDROID ainsi qu'un XrSceneMeshTrackingStateANDROID encapsulé dans une structure XrSceneMeshSnapshotCreationResultANDROID. Techniquement, le handle est un instantané des données de maillage de la scène au moment de la création. Ce handle peut être utilisé pour interroger les informations et les données du maillage de la scène à l'aide de xrGetAllSubmeshStatesANDROID et xrGetSubmeshDataANDROID respectivement.

Utilisation valide (implicite)

Codes renvoyés

Opération réussie

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Échec

  • 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 structure XrSceneMeshSnapshotCreateInfoANDROID est définie comme suit :

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

Descriptions des membres

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures. Aucune structure de ce type n'est définie dans OpenXR de base ou dans cette extension.
  • baseSpace est un XrSpace dans lequel les informations de pose du sous-maillage de la scène sont représentées.
  • time est le XrTime qui décrit l'heure à laquelle le maillage de la scène sera traité ou affiché, généralement XrFrameState :: predictedDisplayTime .
  • boundingBox est un XrBoxf décrivant le cadre de délimitation dans lequel acquérir le maillage de la scène.

La structure XrSceneMeshSnapshotCreateInfoANDROID décrit les informations permettant de créer un handle XrSceneMeshSnapshotANDROID.

Utilisation valide (implicite)

La structure XrSceneMeshSnapshotCreationResultANDROID est définie comme suit :

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

Descriptions des membres

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures. Aucune structure de ce type n'est définie dans OpenXR de base ou dans cette extension.
  • snapshot est un handle XrSceneMeshSnapshotANDROID créé par l'environnement d'exécution.
  • trackingState est un XrSceneMeshTrackingStateANDROID qui décrit l'état du tracker de maillage de scène au moment de la création de l'instantané.

La structure XrSceneMeshSnapshotCreationResultANDROID stocke le résultat de la création d'un instantané de maillage de scène renvoyé par xrCreateSceneMeshSnapshotANDROID .

Utilisation valide (implicite)

L'énumération XrSceneMeshTrackingStateANDROID décrit l'état de suivi d'un outil de suivi de maillage de scène. Chaque valeur de cette énumération représente un état du tracker de maillage de scène.

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;

Les valeurs d'énumération ont les significations suivantes :

Description de l'enum

XR_SCENE_MESH_TRACKING_STATE_INITIALIZING_ANDROID

Le traceur n'est pas encore prêt à fournir des données de maillage.

XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID

Le traceur est en cours de suivi.

XR_SCENE_MESH_TRACKING_STATE_WAITING_ANDROID

Le traceur attend des mesures valides à intégrer depuis la dernière mise à jour du maillage.

XR_SCENE_MESH_TRACKING_STATE_ERROR_ANDROID

Le tracker n'a pas reçu de mesures valides pendant plusieurs cycles et est en état d'erreur.

Cet état ne sert que d'information supplémentaire pour l'application. En l'absence d'autres sources d'erreurs, l'environnement d'exécution doit continuer à autoriser l'application à créer des instantanés et à en récupérer des données, quel que soit l'état XrSceneMeshTrackingStateANDROID actuel du traceur. Si l'état n'est pas XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID , les instantanés peuvent ne pas être à jour ou être vides.

Acquérir des données de maillage de scène à partir de l'instantané de maillage de scène

La fonction xrGetAllSubmeshStatesANDROID est définie comme suit :

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

Description des paramètres

  • snapshot est un handle XrSceneMeshSnapshotANDROID précédemment créé avec xrCreateSceneMeshSnapshotANDROID .
  • submeshStateCapacityInput est la capacité de submeshStates , ou 0 pour récupérer la capacité requise.
  • submeshStateCountOutput est un pointeur vers le nombre de submeshStates écrits, ou un pointeur vers la capacité requise si submeshStateCapacityInput est insuffisant.
  • submeshStates est un pointeur vers un tableau de structures XrSceneSubmeshStateANDROID dans lesquelles l'environnement d'exécution génère l'état de tous les sous-maillages du maillage de la scène. Il peut être NULL si submeshStateCapacityInput est égal à 0.
  • Consultez le chapitre Paramètres de taille de la mémoire tampon pour obtenir une description détaillée de la récupération de la taille submeshStates requise.

L'application peut utiliser la fonction xrGetAllSubmeshStatesANDROID pour obtenir l'état de tous les sous-maillages du maillage de la scène. Il contient des informations de base permettant à l'application de sélectionner les sous-maillages pour lesquels elle souhaite obtenir des données.

Utilisation valide (implicite)

  • L'extension XR_ANDROID_scene_meshing doit être activée avant d'appeler xrGetAllSubmeshStatesANDROID.
  • snapshot doit être un handle XrSceneMeshSnapshotANDROID valide
  • submeshStateCountOutput doit être un pointeur vers une valeur uint32_t
  • Si submeshStateCapacityInput n'est pas 0 , submeshStates doit être un pointeur vers un tableau de structures submeshStateCapacityInput XrSceneSubmeshStateANDROID.

Codes renvoyés

Opération réussie

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Échec

  • 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 structure XrSceneSubmeshStateANDROID est définie comme suit :

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

Descriptions des membres

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures. Aucune structure de ce type n'est définie dans OpenXR de base ou dans cette extension.
  • submeshId est un XrUuid identifiant le sous-maillage.
  • lastUpdatedTime est un XrTime représentant l'heure de la dernière mise à jour du sous-maillage.
  • submeshPoseInBaseSpace est un XrPosef représentant la pose du sous-maillage dans l'espace de base utilisé pour créer l'instantané du maillage de la scène. La pose est également le centre du cadre de délimitation du sous-maillage.
  • bounds est un XrExtent3Df décrivant les dimensions du cadre de délimitation qui englobe le sous-maillage. Cette limite est définie dans l'espace de base utilisé pour créer le handle du maillage de la scène.

L'environnement d'exécution s'efforce de mapper submeshId avec la région de l'espace physique occupé par le sous-maillage. Les environnements d'exécution peuvent à tout moment perdre ce mappage et attribuer un nouvel UUID à n'importe quel sous-ensemble des sous-maillages détectés. En particulier, les environnements d'exécution ne sont pas tenus de réutiliser les mêmes UUID pour les mêmes maillages dans les instances d'application ultérieures.

Utilisation valide (implicite)

La fonction xrGetSubmeshDataANDROID est définie comme suit :

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

Description des paramètres

L'application peut utiliser la fonction xrGetSubmeshDataANDROID pour obtenir des lots de sous-maillages ou tous les sous-maillages à la fois, en transmettant une liste de XrSceneSubmeshDataANDROID avec chaque XrSceneSubmeshDataANDROID :: submeshId défini sur l'ID respectif du sous-maillage à récupérer.

XrSceneSubmeshDataANDROID :: submeshId doit être unique pour chaque élément de inoutSubmeshData et récupérable par xrGetAllSubmeshStatesANDROID pour le même snapshot . Si l'ID du sous-maillage n'est pas valide ou si plusieurs éléments de inoutSubmeshData ont le même ID de sous-maillage, l'environnement d'exécution doit renvoyer XR_ERROR_VALIDATION_FAILURE .

submeshDataCount doit être inférieur ou égal à la valeur renvoyée par xrGetAllSubmeshStatesANDROID :: submeshStateCountOutput . Sinon, l'environnement d'exécution doit renvoyer XR_ERROR_VALIDATION_FAILURE .

Peut être utilisé dans un idiome à deux appels pour interroger le nombre de sommets et d'index de tous les sous-maillages sélectionnés.

Utilisation valide (implicite)

Codes renvoyés

Opération réussie

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Échec

  • 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 structure XrSceneSubmeshDataANDROID est définie comme suit :

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;

Descriptions des membres

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures. Aucune structure de ce type n'est définie dans OpenXR de base ou dans cette extension.
  • submeshId est un XrUuid identifiant le sous-maillage.
  • vertexCapacityInput est la capacité de vertexPositions , vertexNormals et vertexSemantics , ou 0 pour récupérer la capacité requise.
  • vertexCountOutput est un pointeur vers le nombre de vertexPositions, vertexNormals et vertexSemantics écrits, ou un pointeur vers la capacité requise si vertexCapacityInput est insuffisant.
  • vertexPositions est un tableau de XrVector3f dans lequel l'environnement d'exécution générera les positions des sommets du sous-maillage.
  • vertexNormals est un tableau de XrVector3f dans lequel l'environnement d'exécution génère les normales de sommet du sous-maillage. Ce champ peut être laissé NULL si l'application a créé un outil de suivi avec les normales désactivées.
  • vertexSemantics est un tableau de uint8_t dans lequel l'environnement d'exécution affichera la sémantique des sommets du sous-maillage. Ce champ peut être laissé NULL si l'application a créé un outil de suivi avec l'ensemble d'étiquettes sémantiques XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID.
  • indexCapacityInput est la capacité de indices , ou 0 pour récupérer la capacité requise.
  • indexCountOutput est un pointeur vers le nombre de indices écrits, ou un pointeur vers la capacité requise si vertexCapacityInput est insuffisant.
  • indices est un tableau de uint32_t dans lequel l'environnement d'exécution génère les indices du sous-maillage.
  • Consultez le chapitre Paramètres de taille de la mémoire tampon pour obtenir une description détaillée de la récupération de la taille requise pour vertexPositions, vertexNormals, vertexSemantics et indices.

Utilisation valide (implicite)

  • L'extension XR_ANDROID_scene_meshing doit être activée avant d'utiliser XrSceneSubmeshDataANDROID.
  • type doit être XR_TYPE_SCENE_SUBMESH_DATA_ANDROID
  • next doit être NULL ou un pointeur valide vers la structure suivante dans une chaîne de structures
  •  Si vertexCapacityInput n'est pas 0 , vertexPositions doit être un pointeur vers un tableau de structures vertexCapacityInput XrVector3f.
  •  Si vertexCapacityInput n'est pas 0 , vertexNormals doit être un pointeur vers un tableau de structures vertexCapacityInput XrVector3f.
  • Si vertexCapacityInput n'est pas 0 , vertexSemantics doit être un pointeur vers un tableau de valeurs vertexCapacityInput uint8_t.
  • Si indexCapacityInput n'est pas 0 , indices doit être un pointeur vers un tableau de valeurs indexCapacityInput uint32_t.

L'énumération XrSceneMeshSemanticLabelANDROID est l'ensemble par défaut d'étiquettes sémantiques qui peuvent être utilisées pour étiqueter les sommets de maillage afin de décrire la surface de l'environnement physique sur laquelle se trouve le sommet de maillage. Cet ensemble d'énumérations est représenté par la valeur XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID dans 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;

Les énumérations ont les significations suivantes :

Description de l'enum

XR_SCENE_MESH_SEMANTIC_LABEL_OTHER_ANDROID

Cette étiquette sémantique indique que l'élément de maillage correspondant représente un objet inconnu.

XR_SCENE_MESH_SEMANTIC_LABEL_FLOOR_ANDROID

Cette étiquette sémantique indique que l'élément de maillage correspondant représente un sol.

XR_SCENE_MESH_SEMANTIC_LABEL_CEILING_ANDROID

Cette étiquette sémantique indique que l'élément de maillage correspondant représente un plafond.

XR_SCENE_MESH_SEMANTIC_LABEL_WALL_ANDROID

Cette étiquette sémantique indique que l'élément de maillage correspondant représente un mur.

XR_SCENE_MESH_SEMANTIC_LABEL_TABLE_ANDROID

Cette étiquette sémantique indique que l'élément de maillage correspondant représente une table.

Supprimer un instantané de maillage de scène

La fonction xrDestroySceneMeshSnapshotANDROID est définie comme suit :

XrResult xrDestroySceneMeshSnapshotANDROID(
    XrSceneMeshSnapshotANDROID                  snapshot);

Description des paramètres

L'application peut utiliser la fonction xrDestroySceneMeshSnapshotANDROID pour détruire un instantané de maillage de scène. Une fois le handle détruit, l'application ne peut plus l'utiliser pour obtenir les informations ou les données du sous-maillage. Le handle est automatiquement détruit lorsque le tracker est détruit, car le handle du tracker est le parent du handle de l'instantané du maillage de la scène.

Utilisation valide (implicite)

Thread safety

  • L'accès à snapshot et à tous les handles enfants doit être synchronisé en externe.

Codes renvoyés

Opération réussie

  • XR_SUCCESS

Échec

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Exemple de code pour le maillage de scène

L'exemple de code suivant montre comment accéder aux données de maillage de scène pour le rendu.

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

Nouveaux types d'objets

Nouvelles commandes

Nouvelles structures

Nouvelles énumérations

Nouvelles constantes d'énumération

  • XR_ANDROID_SCENE_MESHING_EXTENSION_NAME
  • XR_ANDROID_scene_meshing_SPEC_VERSION

  • Extension de XrObjectType :

    • XR_OBJECT_TYPE_SCENE_MESHING_TRACKER_ANDROID
    • XR_OBJECT_TYPE_SCENE_MESH_SNAPSHOT_ANDROID

  • Extension de 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

Problèmes

Historique des versions

  • Révision 3, 15/05/2025 (Salar Khan)

    • Description initiale de l'extension