XR_ANDROID_eye_tracking

Name String

XR_ANDROID_eye_tracking

Type d'extension

Extension d'instance

Numéro d'extension enregistré

457

Révision

1

État de la ratification

Non ratifié

Dépendances d'extension et de version

OpenXR 1.0

Date de dernière modification

2025-01-17

État de l'adresse IP

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

Participants

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 oculaire sont fournies dans 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 doit ê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 :

(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 OpenXR de base ou dans cette extension.
  • supportsEyeTracking est un XrBool32 indiquant si le système actuel est compatible avec le suivi oculaire.

Une application peut vérifier si le système est capable d'effectuer un suivi oculaire 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)

Créer un handle de suivi oculaire

XR_DEFINE_HANDLE(XrEyeTrackerANDROID)

Le handle XrEyeTrackerANDROID représente un outil de suivi oculaire qui suit les yeux et cartographie précisément l'endroit où l'utilisateur regarde.

Les données de suivi oculaire 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 suivi oculaire demandent toujours à l'utilisateur d'accepter activement et spécifiquement cette opération.

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

Le suivi oculaire 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);

Description des paramètres

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

Si le système n'est pas compatible avec le suivi oculaire, l'environnement d'exécution doit renvoyer XR_ERROR_FEATURE_UNSUPPORTED à partir de xrCreateEyeTrackerANDROID .

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 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 OpenXR de base ou dans cette extension.

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

Utilisation valide (implicite)

La fonction xrDestroyEyeTrackerANDROID est définie comme suit :

XrResult xrDestroyEyeTrackerANDROID(
    XrEyeTrackerANDROID                         eyeTracker);

Description des paramètres

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

Utilisation valide (implicite)

Thread safety

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

Obtenir des informations sur les yeux

La fonction xrGetCoarseTrackingEyesInfoANDROID est définie comme suit :

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

Description des paramètres

La fonction xrGetCoarseTrackingEyesInfoANDROID obtient les informations sur l'état et la position des yeux d'une manière qui préserve la confidentialité de l'utilisateur.

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 à la fois XR_SPACE_LOCATION_POSITION_TRACKED_BIT et XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT ou effacer à la fois XR_SPACE_LOCATION_POSITION_TRACKED_BIT et XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT sur l'XrEyesANDROID :: eyes fourni, et définir XrEyesANDROID :: mode pour indiquer les états de suivi.

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

Description des paramètres

La fonction xrGetFineTrackingEyesInfoANDROID obtient des informations sur l'état et la position 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 à la fois XR_SPACE_LOCATION_POSITION_TRACKED_BIT et XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT ou effacer à la fois XR_SPACE_LOCATION_POSITION_TRACKED_BIT et XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT sur l'XrEyesANDROID :: eyes fourni, et définir XrEyesANDROID :: mode pour indiquer les états de suivi.

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

La structure XrEyesGetInfoANDROID contient les informations requises pour récupérer les positions 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 OpenXR de base ou dans cette extension.
  • time est l'XrTime auquel évaluer les coordonnées par rapport à l'baseSpace .
  • baseSpace est l'XrSpace dans lequel renvoyer les poses des yeux.

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 dans une chaîne de structures. Aucune structure de ce type n'est définie dans OpenXR de base ou dans cette extension.
  • eyes est un tableau de XrEyeANDROID, de taille XR_EYE_MAX_ANDROID, pour les yeux gauche et droit, indexé par XrEyeIndexANDROID .
  • mode est le XrEyeTrackingModeANDROID indiquant quel œil est actuellement suivi.

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 l'XrEyeStateANDROID d'un œil.
  • eyePose est un XrPosef définissant la position et l'orientation de la pupille d'un œil dans le cadre de référence du XrEyesGetInfoANDROID :: baseSpace correspondant. Une orientation d'identité représente ici un axe de coordonnées avec +Z dans les yeux de l'utilisateur, +X vers la 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,
    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 est actuellement en train de fixer un point.

XR_EYE_STATE_SHUT_ANDROID

Indique que l'œil est actuellement 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,
    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.

#define XR_EYE_MAX_ANDROID                2

XR_EYE_MAX_ANDROID est le nombre maximal d'yeux pour lesquels les données XrEyeANDROID sont signalées.

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

Nouvelles commandes

Nouvelles structures

Nouvelles énumérations

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