Extension OpenXR XR_ANDROID_hand_mesh

Chaîne de nom

XR_ANDROID_hand_mesh

Type d'extension

Extension d'instance

Numéro d'extension enregistré

704

Révision

1

Dépendances d'extension et de version

OpenXR 1.0

Date de dernière modification

2024-09-10

État de l'adresse IP

Aucune revendication d'adresse IP connue.

Contributeurs

Nihav Jain, Google

Cairn Overturf, Google

Spencer Quin, Google

Levana Chen, Google

Présentation

Cette extension permet le suivi des mains représenté sous la forme d'un maillage dynamique des mains.

Cette extension est destinée à fournir des tampons de sommets et d'indices pour le maillage d'une représentation personnalisée des mains de l'utilisateur. Il peut être utilisé pour l'occlusion et la visualisation.

Cette extension ne doit pas être utilisée à d'autres fins de suivi des mains.

Les données de suivi des mains peuvent être des informations personnelles sensibles et sont étroitement liées à la confidentialité et à l'intégrité personnelles. Il est fortement recommandé que les applications qui stockent ou transfèrent des données de suivi des mains demandent toujours à l'utilisateur une acceptation active et spécifique.

Inspecter les fonctionnalités du système

Une application peut vérifier si le système est capable de suivre les mains en enchaînant une structure XrSystemHandMeshTrackingPropertiesANDROID à XrSystemProperties lors de l'appel de xrGetSystemProperties.

typedef struct XrSystemHandMeshTrackingPropertiesANDROID {
  XrStructureType    type;
  void*              next;
  XrBool32           supportsHandMeshTracking;
  XrBool32           supportsTextureUV;
  XrBool32           supportsVertexNormal;
} XrSystemHandMeshTrackingPropertiesANDROID;

Descriptions des membres

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante d'une chaîne de structures. Aucune de ces structures n'est définie dans OpenXR de base ni dans cette extension.
  • supportsHandMeshTracking est un XrBool32, qui indique si le XrSystemId sélectionné est compatible avec le suivi de la trame de la main.
  • supportsTextureUV est un XrBool32, qui indique si le XrSystemId sélectionné prend en charge les UV de texture pour les sommets du maillage.
  • supportsVertexNormal est un XrBool32, qui indique si le XrSystemId sélectionné est compatible avec les normales de sommet pour les sommets du maillage.

L'application doit éviter d'utiliser les fonctionnalités de maillage des mains lorsque supportsHandMeshTracking est XR_FALSE, car cela signifie que le système n'est pas compatible avec le suivi du maillage des mains. Dans ce cas, xrCreateHandMeshTrackerANDROID renvoie XR_ERROR_FEATURE_UNSUPPORTED.

Si supportsHandMeshTracking renvoie XR_TRUE, le système prend en charge le suivi de la trame de la main. Une application doit utiliser XrHandMeshANDROID::indexCount et XrHandMeshANDROID::vertexCount pour accéder aux tampons de maillage de la main et les réutiliser dans leur boucle de rendu lors de l'appel de xrGetHandMeshANDROID à chaque frame.

Si supportsTextureUV renvoie XR_FALSE, le système n'est pas compatible avec les UV de texture pour les sommets du maillage. Par conséquent, une application recevra XrHandMeshANDROID::textureUVs NULL lors de l'appel de xrGetHandMeshANDROID.

Si supportsVertexNormal renvoie XR_FALSE, le système n'est pas compatible avec les normales de vertex pour les sommets du maillage. Par conséquent, une application recevra XrHandMeshANDROID::normals NULL lors de l'appel de xrGetHandMeshANDROID.

Utilisation valide (implicite)

Créer un identifiant de traceur de réseau maillé

XR_DEFINE_HANDLE(XrHandMeshTrackerANDROID)

Le handle XrHandMeshTrackerANDROID représente un traceur de maillage de la main pour le suivi du maillage de la main et la gestion des ressources associées.

Ce gestionnaire peut être utilisé pour accéder aux tampons de maillage de la main à l'aide d'autres fonctions de cette extension.

Une application peut créer un gestionnaire XrHandMeshTrackerANDROID à l'aide de la fonction xrCreateHandMeshTrackerANDROID. 

XrResult xrCreateHandMeshTrackerANDROID(
    XrSession                                   session,
    const XrHandMeshTrackerCreateInfoANDROID*   createInfo,
    XrHandMeshTrackerANDROID*                   handMeshTracker);

Descriptions des paramètres

Si le système n'est pas compatible avec le suivi de la trame de la main, xrCreateHandMeshTrackerANDROID renvoie XR_ERROR_FEATURE_UNSUPPORTED.

La poignée XrHandMeshTrackerANDROID est propriétaire de toutes les ressources de suivi de la trame de la main. Une fois les expériences de suivi de la trame de la main terminées, l'application doit détruire la poignée à l'aide de la fonction xrDestroyHandMeshTrackerANDROID.

Utilisation valide (implicite)

Codes de retour

Réussite

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Échec

  • XR_ERROR_FEATURE_UNSUPPORTED
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_LIMIT_REACHED

La structure XrHandMeshTrackerCreateInfoANDROID décrit les informations permettant de créer un gestionnaire XrHandMeshTrackerANDROID. 

typedef struct XrHandMeshTrackerCreateInfoANDROID {
    XrStructureType    type;
    const void*        next;
} XrHandMeshTrackerCreateInfoANDROID;

Descriptions des membres

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante d'une chaîne de structures. Aucune de ces structures n'est définie dans OpenXR de base ni dans cette extension.

Utilisation valide (implicite)

La fonction xrDestroyHandMeshTrackerANDROID libère handMeshTracker et les ressources sous-jacentes une fois les expériences de suivi de la trame de la main terminées. 

XrResult xrDestroyHandMeshTrackerANDROID(
    XrHandMeshTrackerANDROID handMeshTracker);

Descriptions des paramètres

Utilisation valide (implicite)

Sécurité des threads

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

Codes de retour

Réussite

  • XR_SUCCESS

Échec

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

Localiser les maillages de la main

L'application peut utiliser la fonction xrGetHandMeshANDROID pour récupérer le maillage de la main à un code temporel donné. La position et la normale des sommets du maillage de la main sont représentées dans l'espace spécifié par XrHandMeshGetInfoANDROID::baseSpace lors de l'appel de xrGetHandMeshANDROID.

XrResult xrGetHandMeshANDROID(
    XrHandMeshTrackerANDROID                    handMeshTracker,
    const XrHandMeshGetInfoANDROID*             getInfo,
    XrHandTrackingMeshesANDROID*                handMeshes);

Descriptions des paramètres

L'application peut utiliser la fonction xrGetHandMeshANDROID pour accéder aux tampons de maillage de la main générés par l'environnement d'exécution.

L'application doit appeler xrBeginFrame au moins une fois pendant la session avant le premier appel de xrGetHandMeshANDROID.

Une application doit utiliser XrHandMeshANDROID::indexCount et XrHandMeshANDROID::vertexCount pour accéder aux tampons de maillage de la main et les réutiliser dans leur boucle de rendu lors de l'appel de xrGetHandMeshANDROID à chaque frame.

Utilisation valide (implicite)

Codes de retour

Réussite

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Échec

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_TIME_INVALID

Un XrHandMeshGetInfoANDROID décrit les informations requises pour obtenir des données de maillage de la main. 

typedef struct XrHandMeshGetInfoANDROID {
    XrStructureType    type;
    const void*        next;
    XrSpace            baseSpace;
    XrTime             time;
} XrHandMeshGetInfoANDROID;

Descriptions des membres

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante d'une chaîne de structures. Aucune de ces structures n'est définie dans OpenXR de base ni dans cette extension.
  • baseSpace est un XrSpace qui définit l'espace de référence dans lequel localiser la transformation des sommets à time.
  • time est le XrTime qui décrit l'heure à laquelle l'application souhaite interroger le maillage de la main.

Utilisation valide (implicite)

La structure XrHandTrackingMeshesANDROID contient des données de maillage pour les deux mains. 

typedef struct XrHandTrackingMeshesANDROID {
    XrStructureType      type;
    void*                next;
    XrHandMeshANDROID    leftHandMesh;
    XrHandMeshANDROID    rightHandMesh;
} XrHandTrackingMeshesANDROID;

Descriptions des membres

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante d'une chaîne de structures. Aucune de ces structures n'est définie dans OpenXR de base ni dans cette extension.
  • leftHandMesh correspond à XrHandMeshANDROID pour la main gauche.
  • rightHandMesh correspond à XrHandMeshANDROID pour la main droite.

Utilisation valide (implicite)

Une structure XrHandMeshANDROID contient des données et des tampons pour recevoir les données de suivi du maillage de la main à partir de la fonction xrGetHandMeshANDROID pour une main.

typedef struct XrHandMeshANDROID {
    XrBool32             isActive;
    XrTime               dynamicLastUpdateTime;
    uint32_t             indexCount;
    uint32_t             vertexCount;
    const uint32_t*      indices;
    const XrVector2f*    textureUVs;
    const XrVector3f*    positions;
    const XrVector3f*    normals;
    XrPosef              baseSpaceFromVertexSpace;
} XrHandMeshANDROID;

Descriptions des membres

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante d'une chaîne de structures. Aucune de ces structures n'est définie dans OpenXR de base ni dans cette extension.
  • isActive est un XrBool32 qui indique si le traceur de maillage de la main actuel est actif et si les données de maillage sont valides.
  • dynamicLastUpdateTime est le XrTime spécifiant l'heure à laquelle les tampons dynamiques ont été mis à jour pour la dernière fois.
  • indexCount est un uint32_t servant de nombre de indices de la maille de la main.
  • vertexCount est un uint32_t servant de nombre de positions du maillage de la main. Il peut également être utilisé pour textureUVs ou normals lorsqu'ils sont compatibles avec le système.
  • indices est un tableau de uint32_t représentant les indices de maillage des triangles dans l'ordre de déroulement antihoraire. Le nombre de valeurs pointées est indexCount.
  • textureUVs est NULL ou un tableau de XrVector2f représentant les coordonnées de texture des sommets. Le nombre de valeurs pointées est vertexCount.
  • positions est un tableau de XrVector3f représentant les positions des sommets dans baseSpaceFromVertexSpace. Le nombre de valeurs pointées est vertexCount.
  • normals est un NULL ou un tableau de XrVector3f représentant les normales des sommets dans baseSpaceFromVertexSpace. Le nombre de valeurs pointées est vertexCount.
  • baseSpaceFromVertexSpace est le sommet XrSpace situé dans XrHandMeshGetInfoANDROID::baseSpace lors de l'appel de xrGetHandMeshANDROID. Les applications peuvent l'utiliser pour transformer l'espace de coordonnées des sommets et des normales du maillage lors du rendu.

Le maillage de la main est représenté dans des listes de triangles, et les sommets de chaque triangle sont dans l'ordre antihoraire lorsqu'on regarde la main de l'extérieur.

Lorsque la valeur isActive renvoyée est XR_FALSE, cela signifie que la main n'est pas activement suivie. Par exemple, la main se trouve en dehors de la portée du capteur, le focus de saisie est retiré de l'application ou l'application n'a pas les autorisations nécessaires pour accéder aux données de suivi de la main.

Lorsque la valeur isActive renvoyée est XR_TRUE, le maillage de suivi des mains représenté dans indices et positions, y compris textureUVs et normals s'ils sont compatibles avec le système, est mis à jour avec les dernières données de XrHandMeshGetInfoANDROID::time fournies à la fonction xrGetHandMeshANDROID.

La mémoire pointée par les tampons de maillage de la main renvoyés dans XrHandMeshANDROID appartient à l'environnement d'exécution et est partagée avec l'application. Vous pouvez accéder à la mémoire en toute sécurité depuis n'importe quel thread jusqu'au prochain appel de xrBeginFrame tant que le gestionnaire XrHandMeshTrackerANDROID est valide.

  • Les valeurs pointées par indices et textureUVs ne sont pas dynamiques.
  • Le pointeur et les valeurs pointées par positions et normals sont dynamiques et peuvent changer entre les appels de xrBeginFrame. L'application peut utiliser dynamicLastUpdateTime pour vérifier si les valeurs ont changé depuis le dernier frame et éviter le traitement de données inutile en l'absence de modifications.

Utilisation valide (implicite)

  • L'extension XR_ANDROID_hand_mesh doit être activée avant d'utiliser XrHandMeshANDROID.
  • indices doit être un pointeur vers une valeur uint32_t valide.
  • textureUVs doit être un pointeur vers une structure XrVector2f valide.
  • positions doit être un pointeur vers une structure XrVector3f valide.
  • normals doit être un pointeur vers une structure XrVector3f valide.

Exemple de code pour le suivi de la trame de la main

L'exemple de code suivant montre comment accéder aux tampons de maillage de la main 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_xrCreateHandMeshTrackerANDROID xrCreateHandMeshTrackerANDROID; // previously initialized
PFN_xrDestroyHandMeshTrackerANDROID xrDestroyHandMeshTrackerANDROID; // previously initialized
PFN_xrGetHandMeshANDROID xrGetHandMeshANDROID; // previously initialized

// Inspect system capability
XrSystemHandMeshTrackingPropertiesANDROID handMeshTrackingProps = {
  .type = XR_TYPE_SYSTEM_HAND_MESH_TRACKING_PROPERTIES_ANDROID,
};
XrSystemProperties sysProps = {
  .type = XR_TYPE_SYSTEM_PROPERTIES,
  .next = &handMeshTrackingProps
};
CHK_XR(xrGetSystemProperties(instance, systemId, &sysProps));
if (!handMeshTrackingProps.supportsHandMeshTracking) {
  // hand mesh tracking is not supported.
  return;
}

XrHandMeshTrackerCreateInfoANDROID trackerCreateInfo = {
  .type = XR_TYPE_HAND_MESH_TRACKER_CREATE_INFO_ANDROID
};
XrHandMeshTrackerANDROID handMeshTracker = XR_NULL_HANDLE;
CHK_XR(xrCreateHandMeshTrackerANDROID(
    session, &trackerCreateInfo, &handMeshTracker));
// app update loop
while (true) {
    // ...
    // For every frame in frame loop
    // ...

    XrFrameState frameState;  // previously returned from xrWaitFrame
    const XrTime time = frameState.predictedDisplayTime;

    // ...
    XrHandMeshGetInfoANDROID getInfo = {
        .type = XR_TYPE_HAND_MESH_GET_INFO_ANDROID,
        .baseSpace = appPlaySpace,
        .time = time,
    };
    XrHandTrackingMeshesANDROID handMeshes = {
        .type = XR_TYPE_HAND_TRACKING_MESHES_ANDROID
    };
    CHK_XR(xrGetHandMeshANDROID(handMeshTracker, &getInfo, &handMeshes));

    if (handMeshes.leftHandMesh.isActive) {
        // access vertex/index buffers for rendering.
    }

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

CHECK_XR(xrDestroyHandMeshTracker(handMeshTracker));

Nouveaux types d'objets

Nouvelles constantes d'énumération

L'énumération XrObjectType est étendue avec:

  • XR_OBJECT_TYPE_HAND_MESH_TRACKER_ANDROID

L'énumération XrStructureType est étendue avec:

  • XR_TYPE_SYSTEM_HAND_MESH_TRACKING_PROPERTIES_ANDROID
  • XR_TYPE_HAND_MESH_TRACKER_CREATE_INFO_ANDROID
  • XR_TYPE_HAND_MESH_GET_INFO_ANDROID
  • XR_TYPE_HAND_TRACKING_MESHES_ANDROID

Nouvelles énumérations

Nouvelles structures

Nouvelles fonctions

Problèmes

Historique des versions

  • Révision 1, 10/09/2024 (Levana Chen)
    • Description initiale de l'extension