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

État de ratification

Non ratifié

Dépendances des extensions et des versions

OpenXR 1.0

Date de dernière modification

2025-01-17

État de l'adresse IP

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

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 du regard sont fournies selon deux modes : approximatif 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 de base de type avatar, tandis que le suivi précis est destiné aux applications plus précises.

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

Autorisations

Les applications Android doivent inclure l'autorisation android.permission.EYE_TRACKING_COARSE ou android.permission.EYE_TRACKING_FINE dans leur fichier manifeste. Ces autorisations sont considérées comme dangereuses. L'application doit demander l'autorisation au moment de l'exécution pour utiliser ces fonctions :

• xrCreateEyeTrackerANDROID (au moins une des autorisations)
• xrGetCoarseTrackingEyesInfoANDROID (android.permission.EYE_TRACKING_COARSE)
• xrGetFineTrackingEyesInfoANDROID (android.permission.EYE_TRACKING_FINE)

(niveau de protection : dangereux)

Inspecter les capacité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 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.
• supportsEyeTracking est une XrBool32 qui indique si le système actuel est compatible avec le suivi oculaire.

Une application peut inspecter si le système est capable de suivre les yeux en étendant XrSystemProperties avec la structure XrSystemEyeTrackingPropertiesANDROID lors de l'appel de xrGetSystemProperties .

Si et seulement si un environnement d'exécution renvoie XR_FALSE pour supportsEyeTracking , l'environnement d'exécution doit renvoyer XR_ERROR_FEATURE_UNSUPPORTED à partir de xrCreateEyeTrackerANDROID .

Utilisation valide (implicite)

•  L'extension XR_ANDROID_eye_tracking doit être activée avant d'utiliser XrSystemEyeTrackingPropertiesANDROID.
• type doit être XR_TYPE_SYSTEM_EYE_TRACKING_PROPERTIES_ANDROID.
• next doit être NULL ou un pointeur valide vers la structure suivante dans une chaîne de structures.

Créer un handle pour le dispositif de suivi du regard

XR_DEFINE_HANDLE(XrEyeTrackerANDROID)

Le handle XrEyeTrackerANDROID représente un eye tracker permettant de suivre les yeux et de cartographier précisément la direction du regard de l'utilisateur.

Les données de suivi du regard sont des informations personnelles sensibles, é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 du regard demandent toujours à l'utilisateur son acceptation active et spécifique.

L'application utilise ce handle pour accéder aux données de suivi oculaire à l'aide d'autres fonctions de cette extension.

Le suivi du regard fournit une représentation de la pose 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

• session est un handle XrSession dans lequel le suivi oculaire sera actif.
• createInfo est le XrEyeTrackerCreateInfoANDROID utilisé pour spécifier le suivi oculaire.
• eyeTracker est le handle XrEyeTrackerANDROID renvoyé.

Une application crée un handle XrEyeTrackerANDROID à l'aide de la fonction xrCreateEyeTrackerANDROID.

Si le système n'est pas compatible avec le suivi du regard, le runtime doit renvoyer XR_ERROR_FEATURE_UNSUPPORTED à partir de xrCreateEyeTrackerANDROID .

Utilisation valide (implicite)

•  L'extension XR_ANDROID_eye_tracking doit être activée avant d'appeler xrCreateEyeTrackerANDROID.
• session doit être un handle XrSession valide
• createInfo must être un pointeur vers une structure XrEyeTrackerCreateInfoANDROID valide
• eyeTracker must être un pointeur vers un handle XrEyeTrackerANDROID

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 XrEyeTrackerCreateInfoANDROID est définie comme suit :

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

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.

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

Utilisation valide (implicite)

•  L'extension XR_ANDROID_eye_tracking doit être activée avant d'utiliser XrEyeTrackerCreateInfoANDROID.
• type doit être XR_TYPE_EYE_TRACKER_CREATE_INFO_ANDROID.
• next doit être NULL ou un pointeur valide vers la structure suivante dans une chaîne de structures.

La fonction xrDestroyEyeTrackerANDROID est définie comme suit :

XrResult xrDestroyEyeTrackerANDROID(
    XrEyeTrackerANDROID                         eyeTracker);

Descriptions des paramètres

• eyeTracker est un XrEyeTrackerANDROID précédemment créé par xrCreateEyeTrackerANDROID .

La fonction xrDestroyEyeTrackerANDROID libère eyeTracker et les ressources sous-jacentes lorsque les expériences de suivi du regard sont terminées.

Utilisation valide (implicite)

•  L'extension XR_ANDROID_eye_tracking doit être activée avant d'appeler xrDestroyEyeTrackerANDROID.
• eyeTracker must be a valid XrEyeTrackerANDROID handle

Sécurité des threads

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

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

• eyeTracker est un XrEyeTrackerANDROID précédemment créé par xrCreateEyeTrackerANDROID .
• getInfo est un pointeur vers XrEyesGetInfoANDROID utilisé pour fournir des informations permettant d'interroger les poses et les états des yeux.
• eyesOutput est un pointeur vers XrEyesANDROID qui contient les informations renvoyées sur les yeux, y compris les poses et les états.

La fonction xrGetCoarseTrackingEyesInfoANDROID permet d'obtenir des informations sur les états et les poses des yeux tout en préservant 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 poses des yeux sont exprimées dans XrEyesGetInfoANDROID :: baseSpace à XrEyesGetInfoANDROID :: time .

À tout moment, la position et la direction de la pose des yeux sont suivies ou non. Cela signifie que l'environnement d'exécution doit définir XR_SPACE_LOCATION_POSITION_TRACKED_BIT et XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT ou effacer XR_SPACE_LOCATION_POSITION_TRACKED_BIT et XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT sur le XrEyesANDROID fourni :: eyes , et définir XrEyesANDROID :: mode pour indiquer les états de suivi.

Utilisation valide (implicite)

•  L'extension XR_ANDROID_eye_tracking doit être activée avant d'appeler xrGetCoarseTrackingEyesInfoANDROID.
• eyeTracker must be a valid XrEyeTrackerANDROID handle
• getInfo doit être un pointeur vers une structure XrEyesGetInfoANDROID valide
• eyesOutput must être un pointeur vers une structure XrEyesANDROID

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_PERMISSION_INSUFFICIENT
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_SESSION_LOST
• XR_ERROR_TIME_INVALID
• XR_ERROR_VALIDATION_FAILURE

La fonction xrGetFineTrackingEyesInfoANDROID est définie comme suit :

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

Descriptions des paramètres

• eyeTracker est un XrEyeTrackerANDROID précédemment créé par xrCreateEyeTrackerANDROID .
• getInfo est un pointeur vers XrEyesGetInfoANDROID utilisé pour spécifier la sortie requise.
• eyesOutput est un pointeur vers XrEyesANDROID qui contient les informations renvoyées sur les yeux, y compris les poses et les états.

La fonction xrGetFineTrackingEyesInfoANDROID permet d'obtenir des informations sur les états et les poses des yeux avec une précision supérieure à celle de xrGetCoarseTrackingEyesInfoANDROID .

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 à xrGetFineTrackingEyesInfoANDROID à l'aide de XrEyesGetInfoANDROID :: time , XrEyesGetInfoANDROID :: baseSpace . L'environnement d'exécution doit résoudre l'emplacement défini par XrEyesGetInfoANDROID :: baseSpace au moment de l'appel.

À tout moment, la position et la direction de la pose des yeux sont suivies ou non. Cela signifie que l'environnement d'exécution doit définir XR_SPACE_LOCATION_POSITION_TRACKED_BIT et XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT ou effacer XR_SPACE_LOCATION_POSITION_TRACKED_BIT et XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT sur le XrEyesANDROID fourni :: eyes , et définir XrEyesANDROID :: mode pour indiquer les états de suivi.

Utilisation valide (implicite)

•  L'extension XR_ANDROID_eye_tracking doit être activée avant d'appeler xrGetFineTrackingEyesInfoANDROID.
• eyeTracker must be a valid XrEyeTrackerANDROID handle
• getInfo doit être un pointeur vers une structure XrEyesGetInfoANDROID valide
• eyesOutput must être un pointeur vers une structure XrEyesANDROID

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_PERMISSION_INSUFFICIENT
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_SESSION_LOST
• XR_ERROR_TIME_INVALID
• XR_ERROR_VALIDATION_FAILURE

La structure XrEyesGetInfoANDROID contient les informations nécessaires pour récupérer les poses et les états des yeux.

typedef struct XrEyesGetInfoANDROID {
    XrStructureType    type;
    const 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 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.
• time est le XrTime auquel évaluer les coordonnées par rapport à baseSpace .
• baseSpace est l'XrSpace par rapport auquel les poses des yeux seront relatives à time .

Utilisation valide (implicite)

•  L'extension XR_ANDROID_eye_tracking doit être activée avant d'utiliser XrEyesGetInfoANDROID.
• type doit être XR_TYPE_EYES_GET_INFO_ANDROID.
• next doit être NULL ou un pointeur valide vers la structure suivante dans une chaîne de structures.
• baseSpace must être un handle XrSpace valide

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 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.
• eyes est un tableau de XrEyeANDROID, de taille XR_EYE_MAX_ANDROID, pour les yeux gauche et droit, indexés par XrEyeIndexANDROID .
• mode est XrEyeTrackingModeANDROID, qui indique l'œil actuellement suivi.

Utilisation valide (implicite)

•  L'extension XR_ANDROID_eye_tracking doit être activée avant d'utiliser XrEyesANDROID.
• type doit être XR_TYPE_EYES_ANDROID.
• next doit être NULL ou un pointeur valide vers la structure suivante dans une chaîne de structures.
•  Chaque élément de eyes doit être une structure XrEyeANDROID valide.
• mode must doit être une valeur XrEyeTrackingModeANDROID valide.

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.
• eyePose est un XrPosef qui définit la position et l'orientation de la pupille d'un œil dans le cadre de référence du XrEyesGetInfoANDROID correspondant : baseSpace . Ici, l'orientation de l'identité représente des axes de coordonnées avec +Z vers les yeux de l'utilisateur, +X vers la droite et +Y vers le haut.

Utilisation valide (implicite)

•  L'extension XR_ANDROID_eye_tracking doit être activée avant d'utiliser XrEyeANDROID.
• eyeState must être une valeur XrEyeStateANDROID valide

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,
    XR_EYE_STATE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrEyeStateANDROID;

Les énumérations ont les significations suivantes :

Description de l'enum

XR_EYE_STATE_INVALID_ANDROID

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

XR_EYE_STATE_GAZING_ANDROID

Indique que l'œil regarde actuellement.

XR_EYE_STATE_SHUT_ANDROID

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

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,
    XR_EYE_INDEX_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrEyeIndexANDROID;

Les énumérations ont les significations suivantes :

Description de l'enum

XR_EYE_INDEX_LEFT_ANDROID

Œil gauche.

XR_EYE_INDEX_RIGHT_ANDROID

Œil droit.

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

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,
    XR_EYE_TRACKING_MODE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrEyeTrackingModeANDROID;

Les énumérations ont les significations suivantes :

Description de l'enum

XR_EYE_TRACKING_MODE_NOT_TRACKING_ANDROID

Indique que le suivi oculaire n'est pas actif actuellement.

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 sont suivis.

Exemple de code pour le suivi oculaire

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

• XrEyeTrackerANDROID

Nouvelles commandes

• xrCreateEyeTrackerANDROID
• xrDestroyEyeTrackerANDROID
• xrGetCoarseTrackingEyesInfoANDROID
• xrGetFineTrackingEyesInfoANDROID

Nouvelles structures

• XrEyeANDROID
• XrEyeTrackerCreateInfoANDROID
• XrEyesANDROID
• XrEyesGetInfoANDROID

• Étendre XrSystemProperties :

  • XrSystemEyeTrackingPropertiesANDROID

Nouveaux enums

• XrEyeIndexANDROID
• XrEyeStateANDROID
• XrEyeTrackingModeANDROID

Nouvelles constantes d'énumération

• XR_ANDROID_EYE_TRACKING_EXTENSION_NAME
• XR_ANDROID_eye_tracking_SPEC_VERSION
• XR_EYE_MAX_ANDROID

• Extension de XrObjectType :

  • XR_OBJECT_TYPE_EYE_TRACKER_ANDROID

• Extension de XrStructureType :

  • XR_TYPE_EYES_ANDROID
  • XR_TYPE_EYES_GET_INFO_ANDROID
  • XR_TYPE_EYE_TRACKER_CREATE_INFO_ANDROID
  • XR_TYPE_SYSTEM_EYE_TRACKING_PROPERTIES_ANDROID

Problèmes

Historique des versions

• Révision 1, 17/01/2025 (Kenny Vercaemer)

  • Description initiale de l'extension