Extension OpenXR XR_ANDROID_avatar_eyes

Chaîne de nom

XR_ANDROID_avatar_eyes

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

2024-09-30

État de l'adresse IP

Aucune revendication d'adresse IP connue.

Contributeurs

Spencer Quin, Google

Jared Finder, Google

Levana Chen, 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.

Cette extension vise à rendre la position des yeux et la représentation de l'état des avatars plus réalistes. À cette fin:

  • Il permet d'utiliser des états non suivis, tels que le clignotement.
  • Il permet un suivi monoculaire ou binoculaire.

Cette extension ne doit pas être utilisée à d'autres fins de suivi visuel. Pour l'interaction, devrait être utilisé XR_EXT_eye_gaze_interaction.

Outil de suivi oculaire

Un eye-tracker est un appareil de détection qui suit les yeux et cartographie avec précision l'endroit où l'utilisateur regarde. L'objectif principal de cette extension est de mapper les regards des utilisateurs sur leurs avatars dans une scène virtuelle.

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.

  • Une application reçoit XR_ERROR_PERMISSION_INSUFFICIENT lorsqu'elle tente de créer un traceur oculaire actif jusqu'à ce qu'elle soit autorisée à y accéder.

Inspecter les fonctionnalités du système

Une application peut vérifier si le système est compatible avec les yeux d'avatar en enchaînant une structure XrSystemAvatarEyesPropertiesANDROID à la XrSystemProperties lors de l'appel de xrGetSystemProperties. Si supportsAvatarEyes renvoie XR_FALSE, une application recevra XR_ERROR_FEATURE_UNSUPPORTED de xrCreateEyeTrackerANDROID.

typedef struct XrSystemAvatarEyesPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsAvatarEyes;
} XrSystemAvatarEyesPropertiesANDROID;

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.
  • supportsAvatarEyes est un XrBool32, qui indique si le système actuel est compatible avec les yeux d'avatar.

Utilisation valide (implicite)

Créer un gestionnaire de suivi visuel

XR_DEFINE_HANDLE(XrEyeTrackerANDROID)

La poignée XrEyeTrackerANDROID représente un eye-tracker pour suivre les yeux et cartographie précisément ce que l'utilisateur regarde.

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

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

XrResult xrGetEyesInfoANDROID(
    XrEyeTrackerANDROID                         eyeTracker,
    const XrEyesGetInfoANDROID*                 getInfo,
    XrEyesANDROID*                              infoOutput);

Descriptions des paramètres

La fonction xrGetEyesInfoANDROID obtient les informations sur les états et les poses des yeux.

Les informations sur les yeux sont résolues et relatives à l'espace de base au moment de l'appel de xrGetEyesInfoANDROID à 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

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 à cet espace XR à 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 le suivi des yeux est activé 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 l'XrEyeStateANDROID d'un œil.
  • pose est un XrPosef qui définit la position et l'orientation de l'origine d'un œil dans le cadre 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, for example, 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_xrGetEyesInfoANDROID xrGetEyesInfoANDROID; // 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 eyesInfo{.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(xrGetEyesInfoANDROID(eyeTracker, &eyesGetInfo, &eyesInfo));

    // 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_AVATAR_EYES_PROPERTIES_ANDROID

Nouvelles énumérations

Nouvelles structures

Nouvelles fonctions

Problèmes

Historique des versions

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