XR_ANDROID_scene_meshing

Chaîne de nom

XR_ANDROID_scene_meshing

Type d'extension

Extension d'instance

Numéro d'extension enregistré

719

Révision

3

État de ratification

Non ratifié

Dépendances des extensions et des versions

OpenXR 1.0

Date de dernière modification

2025-05-15

État de l'adresse IP

Aucune réclamation connue pour atteinte à la propriété intellectuelle.

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 les objets physiques, par exemple en cas de collision.

Les données du maillage de la scène sont générées par le moteur 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-mailles 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ènes sont des informations personnelles sensibles, étroitement liées à la confidentialité et à l'intégrité personnelles. Nous recommandons vivement aux applications qui stockent ou transfèrent des données de maillage de scène de toujours demander à l'utilisateur son accord actif et spécifique.

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 l'extension ni dans le cœur d'OpenXR.
  • 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 des scènes en chaînant une structure XrSystemSceneMeshingPropertiesANDROID à XrSystemProperties lors de l'appel de xrGetSystemProperties .

Si un moteur d'exécution renvoie XR_FALSE pour supportsSceneMeshing , le système ne prend pas en charge le maillage de scène. Par conséquent, must doit 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 , cela signifie que le système est compatible avec le maillage de scènes.

Utilisation valide (implicite)

L'énumération XrSceneMeshSemanticLabelSetANDROID décrit les ensembles de libellés sémantiques pour le maillage de scène. Chaque valeur de cette énumération représente une autre énumération contenant les libellés 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_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.

La fonction xrEnumerateSupportedSemanticLabelSetsANDROID est définie comme suit :

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

Descriptions des paramètres

  • instance est une XrInstance créée par l'application.
  • systemId est un XrSystemId réessayé à partir de xrGetSystem .
  • supportedSemanticLabelSetsInputCapacity correspond à 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 dans le cas où supportedSemanticLabelSetsInputCapacity est insuffisant.
  • supportedSemanticLabelSets est un pointeur vers un tableau de XrSceneMeshSemanticLabelSetANDROID . Elle peut être NULL si supportedSemanticLabelSetsInputCapacity est défini sur 0.
  • Consultez le chapitre Paramètres de la taille du 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 prendre en charge XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID, car cette valeur d'énumération ne représente aucun ensemble de libellés sémantiques et peut être utilisée si l'application n'a pas besoin de sémantique de vertex.

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 must être un pointeur vers une valeur uint32_t
  •  Si supportedSemanticLabelSetsInputCapacity n'est pas 0 , supportedSemanticLabelSets doit être un pointeur vers un tableau de valeurs XrSceneMeshSemanticLabelSetANDROID de supportedSemanticLabelSetsInputCapacity.

Codes de retour

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

Descriptions 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, le runtime doit renvoyer XR_ERROR_FEATURE_UNSUPPORTED à partir de xrCreateSceneMeshingTrackerANDROID . Dans ce cas, le runtime doit renvoyer XR_FALSE pour XrSystemSceneMeshingPropertiesANDROID :: supportsSceneMeshing lorsque la fonction xrGetSystemProperties est appelée, afin que l'application puisse éviter de créer un tracker de maillage de scène.

L'application doit uniquement utiliser les ensembles de libellés 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 de libellés sémantiques de vertex de maillage de scène non compatible, le runtime doit renvoyer XR_ERROR_FEATURE_UNSUPPORTED à partir de xrCreateSceneMeshingTrackerANDROID .

L'application peut énumérer la liste des ensembles de libellés 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 à l'aide de la fonction xrDestroySceneMeshingTrackerANDROID.

Utilisation valide (implicite)

Codes de retour

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 l'extension ni dans le cœur d'OpenXR.
  • semanticLabelSet est un XrSceneMeshSemanticLabelSetANDROID utilisé pour spécifier l'ensemble de libellés sémantiques à utiliser pour le maillage de la scène. Si cette valeur est définie sur XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID , le runtime ignore le champ de mémoire tampon vertexSemantics de XrSceneSubmeshDataANDROID.
  • enableNormals est un XrBool32 utilisé pour spécifier s'il faut inclure les normales des sommets pour les sommets du maillage dans le tampon de maillage de la scène lors de l'obtention des données du 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);

Descriptions des paramètres

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

Utilisation valide (implicite)

Sécurité des threads

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

Codes de retour

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é du maillage de la scène. Cet instantané est créé à l'aide de xrCreateSceneMeshSnapshotANDROID, qui prend un instantané des données du maillage de la scène au moment de l'appel de la fonction.

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

La fonction xrCreateSceneMeshSnapshotANDROID est définie comme suit :

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

Descriptions des paramètres

L'application peut utiliser la fonction xrCreateSceneMeshSnapshotANDROID pour créer un instantané du maillage de la scène à partir du suivi du maillage de la scène. Cette fonction renvoie un handle XrSceneMeshSnapshotANDROID ainsi que XrSceneMeshTrackingStateANDROID encapsulé dans une structure XrSceneMeshSnapshotCreationResultANDROID. Techniquement, le handle est un instantané des données du 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 de retour

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 l'extension ni dans le cœur d'OpenXR.
  • 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 le moment où le maillage de la scène sera traité ou affiché, généralement XrFrameState :: predictedDisplayTime .
  • boundingBox est une 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 l'extension ni dans le cœur d'OpenXR.
  • snapshot est un handle XrSceneMeshSnapshotANDROID créé par le moteur d'exécution.
  • trackingState est un XrSceneMeshTrackingStateANDROID qui décrit l'état du suivi de maillage de la 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 du suivi pour un outil de suivi de maillage de scène. Chaque valeur de cette énumération représente un état du suivi de maillage de la 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 wearable attend des mesures valides à intégrer depuis la dernière mise à jour du réseau maillé.

XR_SCENE_MESH_TRACKING_STATE_ERROR_ANDROID

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

Cet état sert uniquement d'informations supplémentaires 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 à récupérer des données à partir de ceux-ci, quel que soit l'état XrSceneMeshTrackingStateANDROID actuel du suivi. 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);

Descriptions des paramètres

  • snapshot est un handle XrSceneMeshSnapshotANDROID précédemment créé avec xrCreateSceneMeshSnapshotANDROID .
  • submeshStateCapacityInput correspond à 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 dans le cas où submeshStateCapacityInput est insuffisant.
  • submeshStates est un pointeur vers un tableau de structures XrSceneSubmeshStateANDROID dans lequel le moteur d'exécution génère l'état de tous les sous-maillages du maillage de la scène. Elle peut être NULL si submeshStateCapacityInput est défini sur 0.
  • Consultez le chapitre Paramètres de la taille du 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 must be a valid XrSceneMeshSnapshotANDROID handle
  • submeshStateCountOutput must être un pointeur vers une valeur uint32_t
  •  Si submeshStateCapacityInput n'est pas 0 , submeshStates doit être un pointeur vers un tableau de structures XrSceneSubmeshStateANDROID submeshStateCapacityInput.

Codes de retour

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 l'extension ni dans le cœur d'OpenXR.
  • submeshId est un XrUuid identifiant le sous-maillage.
  • lastUpdatedTime est un XrTime représentant l'heure à laquelle le sous-maillage a été mis à jour pour la dernière fois.
  • 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. Ces limites sont définies dans l'espace de base utilisé pour créer le handle du maillage de la scène.

Le runtime s'efforce de mapper submeshId avec la région de l'espace physique occupé par le sous-maillage. Les runtimes peuvent à tout moment perdre ce mappage et attribuer un nouvel UUID à un sous-ensemble des sous-maillages détectés. En particulier, les runtimes 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);

Descriptions 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 must be unique for every element in inoutSubmeshData and retrievable by xrGetAllSubmeshStatesANDROID for the same snapshot . Si l'ID de sous-maillage n'est pas valide ou si plusieurs éléments de inoutSubmeshData ont le même ID de sous-maillage, le runtime doit renvoyer XR_ERROR_VALIDATION_FAILURE .

submeshDataCount doit être inférieur ou égal à la valeur renvoyée par xrGetAllSubmeshStatesANDROID :: submeshStateCountOutput , sinon le runtime doit renvoyer XR_ERROR_VALIDATION_FAILURE .

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

Utilisation valide (implicite)

Codes de retour

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 l'extension ni dans le cœur d'OpenXR.
  • submeshId est un XrUuid identifiant le sous-maillage.
  • vertexCapacityInput correspond à 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 dans le cas où vertexCapacityInput est insuffisant.
  • vertexPositions est un tableau XrVector3f dans lequel le runtime génère les positions des sommets du sous-maillage.
  • vertexNormals est un tableau XrVector3f dans lequel le runtime génère les normales de vertex du sous-maillage. Ce champ peut être laissé NULL si l'application a créé un tracker avec les normales désactivées.
  • vertexSemantics est un tableau de uint8_t dans lequel l'environnement d'exécution génère la sémantique des sommets du sous-maillage. Ce champ peut être laissé NULL si l'application a créé un tracker avec un ensemble de libellés sémantiques XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID.
  • indexCapacityInput correspond à 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 dans le cas où vertexCapacityInput est insuffisant.
  • indices est un tableau de uint32_t dans lequel le runtime génère les index du sous-maillage.
  • Consultez le chapitre Paramètres de taille de 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 XrVector3f de vertexCapacityInput.
  •  Si vertexCapacityInput n'est pas 0 , vertexNormals doit être un pointeur vers un tableau de structures XrVector3f de vertexCapacityInput.
  •  Si vertexCapacityInput n'est pas 0 , vertexSemantics doit être un pointeur vers un tableau de valeurs uint8_t de type vertexCapacityInput.
  •  Si indexCapacityInput n'est pas 0 , indices doit être un pointeur vers un tableau de valeurs uint32_t de type indexCapacityInput.

L'énumération XrSceneMeshSemanticLabelANDROID est l'ensemble par défaut de libellés sémantiques qui peuvent être utilisés pour libeller 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

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

XR_SCENE_MESH_SEMANTIC_LABEL_FLOOR_ANDROID

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

XR_SCENE_MESH_SEMANTIC_LABEL_CEILING_ANDROID

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

XR_SCENE_MESH_SEMANTIC_LABEL_WALL_ANDROID

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

XR_SCENE_MESH_SEMANTIC_LABEL_TABLE_ANDROID

Ce libellé sémantique indique que l'élément de maillage correspondant représente un tableau.

Détruire un instantané de maillage de scène

La fonction xrDestroySceneMeshSnapshotANDROID est définie comme suit :

XrResult xrDestroySceneMeshSnapshotANDROID(
    XrSceneMeshSnapshotANDROID                  snapshot);

Descriptions 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 du snapshot du maillage de la scène.

Utilisation valide (implicite)

Sécurité des threads

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

Codes de retour

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 du maillage de la 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

Nouveaux enums

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