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 des extensions et des versions

OpenXR 1.0

Date de dernière modification

2025-01-17

État de la propriété intellectuelle

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 en deux modes : précis et approximatif. 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é.

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 un XrBool32, indiquant si le système actuel est compatible avec le suivi du regard.

Une application peut inspecter si le système est capable de suivre les yeux en chaînant une structure XrSystemEyeTrackingPropertiesANDROID à XrSystemProperties lors de l'appel de xrGetSystemProperties. Si supportsEyeTracking renvoie XR_FALSE, une application recevra XR_ERROR_FEATURE_UNSUPPORTED de xrCreateEyeTrackerANDROID.

Utilisation valide (implicite)

Créer un handle de l'eye-tracker

XR_DEFINE_HANDLE(XrEyeTrackerANDROID)

Le handle XrEyeTrackerANDROID représente un dispositif de suivi du regard qui permet de suivre les yeux et de cartographier précisément ce que l'utilisateur regarde.

Les données de suivi du regard peuvent être des informations personnelles sensibles et sont étroitement liées à la confidentialité et à l'intégrité personnelles. Il est fortement recommandé aux applications qui stockent ou transfèrent des données de suivi du regard de toujours demander à l'utilisateur son accord actif et spécifique pour le faire.

Ce handle peut être utilisé pour accéder aux données de suivi du regard à 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

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

Si le système n'est pas compatible avec le suivi du regard, XR_ERROR_FEATURE_UNSUPPORTED sera renvoyé par xrCreateEyeTrackerANDROID.

Utilisation valide (implicite)

Codes de retour

Opération réussie

  • 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 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)

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 lorsque vous avez terminé d'utiliser les expériences de suivi du regard.

Utilisation valide (implicite)

Sécurité des threads

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

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 à 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 le XrEyesANDROID::eyes fourni, et que XrEyesANDROID::mode indique les états de suivi.

Utilisation valide (implicite)

Codes de retour

Opération réussie

  • 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 : 

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 à 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 le XrEyesANDROID::eyes fourni, et que XrEyesANDROID::mode indique les états de suivi.

Utilisation valide (implicite)

Codes de retour

Opération réussie

  • 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 nécessaires pour récupérer les poses 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 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, la pose 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 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 pour les yeux gauche et droit, indexés par XrEyeIndexANDROID.
  • mode est le XrEyeTrackingModeANDROID qui indique si les yeux sont suivis 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 la 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 du XrEyesGetInfoANDROID::baseSpace correspondant. Ici, l'orientation de l'identité représente des axes 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 les significations suivantes :

Enum

Description

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 le regard est fixe.

XR_EYE_STATE_SHUT_ANDROID

Indique que l'œil est 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
} XrEyeIndexANDROID;

Les énumérations ont les significations suivantes :

Enum

Description

XR_EYE_INDEX_LEFT_ANDROID

Œil gauche.

XR_EYE_INDEX_RIGHT_ANDROID

Œil droit.

L'énumération XrEyeTrackingModeANDROID identifie les différents modes 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
} XrEyeTrackingModeANDROID;

Les énumérations ont les significations suivantes :

Enum

Description

XR_EYE_TRACKING_MODE_NOT_TRACKING_ANDROID

Indique que le suivi du regard 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 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

Nouvelles constantes d'énumération

  • XR_EYE_MAX_ANDROID

L'énumération XrObjectType est étendue avec les éléments suivants :

  • XR_OBJECT_TYPE_EYE_TRACKER_ANDROID

L'énumération XrStructureType est étendue avec les éléments suivants :

  • 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, 2025-01-17 (Kenny Vercaemer)
    • Description initiale de l'extension

OpenXR™ et le logo OpenXR sont des marques déposées appartenant à The Khronos Group Inc. et sont enregistrées en Chine, dans l'Union européenne, au Japon et au Royaume-Uni.