Extension OpenXR XR_ANDROID_eye_tracking

Chaîne de nom

XR_ANDROID_eye_tracking

Type d'extension

Extension d'instance

Numéro d'extension enregistré

457

Révision

1

Dépendances d'extension et de version

OpenXR 1.0

Date de dernière modification

2025-01-17

État de l'adresse IP

Aucune revendication d'adresse IP connue.

Contributeurs

Spencer Quin, Google

Jared Finder, Google

Levana Chen, Google

Kenny Vercaemer, Google

Prasanthi Gurumurthy, Google

Nihav Jain, Google

Présentation

Cette extension permet aux applications d'obtenir la position et l'orientation des yeux de l'utilisateur, ainsi que l'état du suivi oculaire.

Les données de suivi visuel sont fournies en deux modes: grossier et précis. Le suivi approximatif fournit une estimation approximative des yeux de l'utilisateur, tandis que le suivi précis fournit une estimation plus précise. Le suivi approximatif est destiné aux applications qui souhaitent fournir une représentation basique semblable à un avatar, tandis que le suivi précis est destiné aux applications plus précises.

Pour l'interaction, devrait être utilisé XR_EXT_eye_gaze_interaction.

Inspecter les fonctionnalités du système

La structure XrSystemEyeTrackingPropertiesANDROID est définie comme suit:

typedef struct XrSystemEyeTrackingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsEyeTracking;
} XrSystemEyeTrackingPropertiesANDROID;

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.
  • supportsEyeTracking est un XrBool32, qui indique si le système actuel est compatible avec le suivi visuel.

Une application peut vérifier si le système est capable de suivre les mouvements des yeux en enchaînant une structure XrSystemEyeTrackingPropertiesANDROID à XrSystemProperties lors de l'appel de xrGetSystemProperties. Si supportsEyeTracking renvoie XR_FALSE, une application reçoit XR_ERROR_FEATURE_UNSUPPORTED de xrCreateEyeTrackerANDROID.

Utilisation valide (implicite)

Créer un gestionnaire de suivi visuel

XR_DEFINE_HANDLE(XrEyeTrackerANDROID)

La poignée XrEyeTrackerANDROID représente un système de suivi des yeux qui permet de suivre les yeux et de cartographier avec précision ce que l'utilisateur regarde.

Les données de suivi visuel peuvent être des informations personnelles sensibles et sont étroitement liées à la confidentialité et à l'intégrité personnelles. Nous recommandons vivement aux applications qui stockent ou transfèrent des données de suivi visuel de demander toujours à l'utilisateur une acceptation active et spécifique.

Ce gestionnaire peut être utilisé pour accéder aux données de suivi visuel à l'aide d'autres fonctions de cette extension.

Le suivi visuel fournit une représentation de la position et de l'état des yeux dans la scène.

La fonction xrCreateEyeTrackerANDROID est définie comme suit: 

XrResult xrCreateEyeTrackerANDROID(
    XrSession                                   session,
    const XrEyeTrackerCreateInfoANDROID*        createInfo,
    XrEyeTrackerANDROID*                        eyeTracker);

Descriptions des paramètres

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

Si le système n'est pas compatible avec le suivi visuel, XR_ERROR_FEATURE_UNSUPPORTED est renvoyé à partir de xrCreateEyeTrackerANDROID.

Utilisation valide (implicite)

Codes de retour

Réussite

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Échec

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

La structure XrEyeTrackerCreateInfoANDROID est définie comme suit: 

typedef struct XrEyeTrackerCreateInfoANDROID {
    XrStructureType    type;
    void*              next;
} XrEyeTrackerCreateInfoANDROID;

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.

La structure XrEyeTrackerCreateInfoANDROID décrit les informations permettant de créer un gestionnaire XrEyeTrackerANDROID.

Utilisation valide (implicite)

La fonction xrDestroyEyeTrackerANDROID est définie comme suit: 

XrResult xrDestroyEyeTrackerANDROID(
    XrEyeTrackerANDROID                         eyeTracker);

Descriptions des paramètres

La fonction xrDestroyEyeTrackerANDROID libère eyeTracker et les ressources sous-jacentes une fois les expériences de suivi visuel terminées.

Utilisation valide (implicite)

Sécurité des threads

  • L'accès à eyeTracker 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

Obtenir des informations sur les yeux

La fonction xrGetCoarseTrackingEyesInfoANDROID est définie comme suit:

XrResult xrGetCoarseTrackingEyesInfoANDROID(
    XrEyeTrackerANDROID                         eyeTracker,
    const XrEyesGetInfoANDROID*                 getInfo,
    XrEyesANDROID*                              eyesOutput);

Descriptions des paramètres

La fonction xrGetCoarseTrackingEyesInfoANDROID obtient les informations sur les états et les poses des yeux de manière à préserver la confidentialité des utilisateurs.

L'environnement d'exécution doit renvoyer XR_ERROR_PERMISSION_INSUFFICIENT si l'application ne dispose pas de l'autorisation android.permission.EYE_TRACKING_COARSE.

Les informations sur les yeux sont résolues et relatives à l'espace de base au moment de l'appel de xrGetCoarseTrackingEyesInfoANDROID à l'aide de XrEyesGetInfoANDROID::time, XrEyesGetInfoANDROID::baseSpace.

À tout moment, la position et la direction de la pose des yeux sont suivies ou non. Cela signifie que les applications peuvent s'attendre à ce que XR_SPACE_LOCATION_POSITION_TRACKED_BIT et XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT soient définis ou effacés sur l'XrEyesANDROID::eyes fourni, et que XrEyesANDROID::mode indique les états de suivi.

Utilisation valide (implicite)

Codes de retour

Réussite

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Échec

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_PERMISSION_INSUFFICIENT

La fonction xrGetFineTrackingEyesInfoANDROID est définie comme suit : {:#xrGetFineTrackingEyesInfoANDROID} C++ XrResult xrGetFineTrackingEyesInfoANDROID( XrEyeTrackerANDROID eyeTracker, const XrEyesGetInfoANDROID* getInfo, XrEyesANDROID* eyesOutput);

Descriptions des paramètres

L'environnement d'exécution doit renvoyer XR_ERROR_PERMISSION_INSUFFICIENT si l'application ne dispose pas de l'autorisation android.permission.EYE_TRACKING_FINE.

Les informations sur les yeux sont résolues et relatives à l'espace de base au moment de l'appel de xrGetFineTrackingEyesInfoANDROID à l'aide de XrEyesGetInfoANDROID::time, XrEyesGetInfoANDROID::baseSpace.

À tout moment, la position et la direction de la pose des yeux sont suivies ou non. Cela signifie que les applications peuvent s'attendre à ce que XR_SPACE_LOCATION_POSITION_TRACKED_BIT et XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT soient définis ou effacés sur l'XrEyesANDROID::eyes fourni, et que XrEyesANDROID::mode indique les états de suivi.

Utilisation valide (implicite)

Codes de retour

Réussite

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Échec

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_PERMISSION_INSUFFICIENT

La structure XrEyesGetInfoANDROID contient les informations requises pour récupérer les positions et les états des yeux. 

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

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.
  • time est l'XrTime à partir duquel évaluer les coordonnées par rapport à baseSpace.
  • baseSpace La position des yeux sera relative à ce XrSpace à time.

Utilisation valide (implicite)

La structure XrEyesANDROID contient des informations sur les yeux suivis. 

typedef struct XrEyesANDROID {
    XrStructureType             type;
    void*                       next;
    XrEyeANDROID                eyes[XR_EYE_MAX_ANDROID];
    XrEyeTrackingModeANDROID    mode;
} XrEyesANDROID;

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.
  • eyes est un tableau de XrEyeANDROID pour les yeux gauche et droit, indexés par XrEyeIndexANDROID.
  • mode est le XrEyeTrackingModeANDROID pour indiquer si les yeux suivent et lesquels.

Utilisation valide (implicite)

La structure XrEyeANDROID décrit l'état, la position et l'orientation d'un œil. 

typedef struct XrEyeANDROID {
    XrEyeStateANDROID    eyeState;
    XrPosef              eyePose;
} XrEyeANDROID;

Descriptions des membres

  • eyeState est le XrEyeStateANDROID d'un œil.
  • pose est un XrPosef qui définit la position et l'orientation de l'origine d'un œil dans le repère de référence de l'XrEyesGetInfoANDROID::baseSpace correspondant. Ici, une orientation d'identité représente un axe de coordonnées avec +Z dans les yeux de l'utilisateur, +X à droite et +Y vers le haut.

Utilisation valide (implicite)

L'énumération XrEyeStateANDROID identifie les différents états des yeux suivis. 

typedef enum XrEyeStateANDROID {
    XR_EYE_STATE_INVALID_ANDROID = 0,
    XR_EYE_STATE_GAZING_ANDROID = 1,
    XR_EYE_STATE_SHUT_ANDROID = 2
} XrEyeStateANDROID;

Les énumérations ont la signification suivante:

Énumération

Description

XR_EYE_STATE_INVALID_ANDROID

Indique que l'œil est dans un état d'erreur ou qu'il n'est pas présent.

XR_EYE_STATE_GAZING_ANDROID

Indique que l'œil est fixe.

XR_EYE_STATE_SHUT_ANDROID

Indique que l'œil est fermé en raison d'un clin d'œil ou d'un clignement.

L'énumération XrEyeIndexANDROID identifie l'index de l'œil gauche ou droit. 

typedef enum XrEyeIndexANDROID {
    XR_EYE_INDEX_LEFT_ANDROID = 0,
    XR_EYE_INDEX_RIGHT_ANDROID = 1
} XrEyeIndexANDROID;

Les énumérations ont la signification suivante:

Énumération

Description

XR_EYE_INDEX_LEFT_ANDROID

Œil gauche.

XR_EYE_INDEX_RIGHT_ANDROID

Œil droit.

L'énumération XrEyeTrackingModeANDROID identifie les différents modes de suivi des yeux. 

typedef enum XrEyeTrackingModeANDROID {
    XR_EYE_TRACKING_MODE_NOT_TRACKING_ANDROID = 0,
    XR_EYE_TRACKING_MODE_RIGHT_ANDROID = 1,
    XR_EYE_TRACKING_MODE_LEFT_ANDROID = 2,
    XR_EYE_TRACKING_MODE_BOTH_ANDROID = 3
} XrEyeTrackingModeANDROID;

Les énumérations ont la signification suivante:

Énumération

Description

XR_EYE_TRACKING_MODE_NOT_TRACKING_ANDROID

Indique que le suivi visuel n'est pas actif.

XR_EYE_TRACKING_MODE_RIGHT_ANDROID

Indique que seul l'œil droit est suivi.

XR_EYE_TRACKING_MODE_LEFT_ANDROID

Indique que seul l'œil gauche est suivi.

XR_EYE_TRACKING_MODE_BOTH_ANDROID

Indique que les yeux gauche et droit suivent le mouvement.

Exemple de code pour le suivi visuel

L'exemple de code suivant montre comment obtenir des informations sur les yeux par rapport à un espace de vue.

XrSession session; // previously initialized, e.g. created at app startup.
XrSpace viewSpace; // space created for XR_REFERENCE_SPACE_TYPE_VIEW.

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrCreateEyeTrackerANDROID xrCreateEyeTrackerANDROID; // previously initialized
PFN_xrDestroyEyeTrackerANDROID xrDestroyEyeTrackerANDROID; // previously initialized
PFN_xrGetCoarseTrackingEyesInfoANDROID xrGetCoarseTrackingEyesInfoANDROID; // previously initialized
PFN_xrGetFineTrackingEyesInfoANDROID xrGetFineTrackingEyesInfoANDROID; // previously initialized

// This will use the XrSession that is bound to the eye tracker done at time of creation.
XrEyeTrackerANDROID eyeTracker;
XrEyeTrackerCreateInfoANDROID createInfo{
    .type = XR_TYPE_EYE_TRACKER_CREATE_INFO_ANDROID,
    .next = nullptr};
CHK_XR(xrCreateEyeTrackerANDROID(session, &createInfo, &eyeTracker));

while (1) {
    // ...
    // For every frame in frame loop
    // ...

    XrFrameState frameState;  // previously returned from xrWaitFrame
    const XrTime time = frameState.predictedDisplayTime;
    XrEyesANDROID fineEyesInfo{.type = XR_TYPE_EYES_ANDROID,
                               .next = nullptr,
                               .mode = XR_EYE_TRACKING_MODE_BOTH_ANDROID};
    XrEyesANDROID coarseEyesInfo{.type = XR_TYPE_EYES_ANDROID,
                                 .next = nullptr,
                                 .mode = XR_EYE_TRACKING_MODE_BOTH_ANDROID};
    XrEyesGetInfoANDROID eyesGetInfo{.type = XR_TYPE_EYES_GET_INFO_ANDROID,
                                     .next = nullptr,
                                     .time = time,
                                     .baseSpace = viewSpace};
    CHK_XR(xrGetCoarseTrackingEyesInfoANDROID(eyeTracker, &eyesGetInfo, &coarseEyesInfo));
    CHK_XR(xrGetFineTrackingEyesInfoANDROID(eyeTracker, &eyesGetInfo, &fineEyesInfo));

    // eyes tracking information is now available:
    // drawLeftEye(eyesInfo.eyes[XR_EYE_INDEX_LEFT_ANDROID].eyePose);
    // drawRightEye(eyesInfo.eyes[XR_EYE_INDEX_RIGHT_ANDROID].eyePose);

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

// after usage
CHK_XR(xrDestroyEyeTrackerANDROID(eyeTracker));

Nouveaux types d'objets

Nouvelles constantes d'énumération

  • XR_EYE_MAX_ANDROID

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

  • XR_OBJECT_TYPE_EYE_TRACKER_ANDROID

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

  • XR_TYPE_EYES_ANDROID
  • XR_TYPE_EYE_TRACKER_CREATE_INFO_ANDROID
  • XR_TYPE_EYES_GET_INFO_ANDROID
  • XR_TYPE_SYSTEM_EYE_TRACKING_PROPERTIES_ANDROID

Nouvelles énumérations

Nouvelles structures

Nouvelles fonctions

Problèmes

Historique des versions

  • Révision 1, 17/01/2025 (Kenny Vercaemer)
    • Description initiale de l'extension