XR_ANDROID_eye_tracking

Cadena de nombre

XR_ANDROID_eye_tracking

Tipo de extensión

Extensión de la instancia

Número de extensión registrado

457

Revisión

1

Estado de ratificación

No se ratificó

Dependencias de extensiones y versiones

OpenXR 1.0

Fecha de la última modificación

2025-01-17

Estado de la IP

No hay reclamos conocidos por IP.

Colaboradores

Spencer Quin, Google
Jared Finder, Google
Levana Chen, Google
Kenny Vercaemer, Google
Prasanthi Gurumurthy, Google
Nihav Jain, Google

Descripción general

Esta extensión permite que las aplicaciones obtengan la posición y la orientación de los ojos del usuario, así como el estado del seguimiento de ojos.

Los datos de seguimiento de ojos se proporcionan en dos modos: aproximado y preciso. El seguimiento grueso proporciona una estimación aproximada de los ojos del usuario, mientras que el seguimiento preciso proporciona una estimación más precisa. El seguimiento aproximado está diseñado para aplicaciones que desean proporcionar una representación básica similar a un avatar, mientras que el seguimiento preciso está diseñado para aplicaciones más exactas.

Para la interacción, se debe usar XR_EXT_eye_gaze_interaction.

Permisos

Las aplicaciones para Android deben tener el permiso android.permission.EYE_TRACKING_COARSE o android.permission.EYE_TRACKING_FINE en su manifiesto. Estos permisos se consideran peligrosos. La aplicación debe solicitar el permiso durante el tiempo de ejecución para usar estas funciones:

(nivel de protección: peligroso)

Inspecciona la capacidad del sistema

La estructura XrSystemEyeTrackingPropertiesANDROID se define de la siguiente manera:

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

Descripciones de los miembros

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.
  • supportsEyeTracking es un XrBool32 que indica si el sistema actual admite el seguimiento de ojos.

Una aplicación puede inspeccionar si el sistema es capaz de realizar el seguimiento de ojos extendiendo XrSystemProperties con la estructura XrSystemEyeTrackingPropertiesANDROID cuando llama a xrGetSystemProperties .

Si y solo si un tiempo de ejecución devuelve XR_FALSE para supportsEyeTracking , el tiempo de ejecución debe devolver XR_ERROR_FEATURE_UNSUPPORTED de xrCreateEyeTrackerANDROID .

Uso válido (implícito)

Cómo crear un identificador del dispositivo de seguimiento ocular

XR_DEFINE_HANDLE(XrEyeTrackerANDROID)

El identificador XrEyeTrackerANDROID representa un dispositivo de seguimiento ocular para rastrear los ojos y asignar con precisión dónde mira el usuario.

Los datos de seguimiento de ojos son información personal sensible y están estrechamente vinculados a la privacidad y la integridad personales. Se recomienda enfáticamente que las aplicaciones que almacenan o transfieren datos de seguimiento de ojos siempre soliciten al usuario que acepte de forma activa y específica hacerlo.

La aplicación usa este identificador para acceder a los datos de seguimiento de ojos con otras funciones de esta extensión.

El seguimiento de ojos proporciona la representación de la postura y el estado de los ojos en la escena.

La función xrCreateEyeTrackerANDROID se define de la siguiente manera:

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

Descripciones de los parámetros

Una aplicación crea un identificador XrEyeTrackerANDROID con la función xrCreateEyeTrackerANDROID.

Si el sistema no admite el seguimiento de ojos, el tiempo de ejecución debe devolver XR_ERROR_FEATURE_UNSUPPORTED desde xrCreateEyeTrackerANDROID .

Uso válido (implícito)

Códigos de retorno

Listo

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falla

  • 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 estructura XrEyeTrackerCreateInfoANDROID se define de la siguiente manera:

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

Descripciones de los miembros

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.

La estructura XrEyeTrackerCreateInfoANDROID describe la información para crear un identificador XrEyeTrackerANDROID.

Uso válido (implícito)

La función xrDestroyEyeTrackerANDROID se define de la siguiente manera:

XrResult xrDestroyEyeTrackerANDROID(
    XrEyeTrackerANDROID                         eyeTracker);

Descripciones de los parámetros

La función xrDestroyEyeTrackerANDROID libera el eyeTracker y los recursos subyacentes cuando finalizan las experiencias de seguimiento de ojos.

Uso válido (implícito)

Seguridad de subprocesos

  • El acceso a eyeTracker y a cualquier identificador secundario debe sincronizarse de forma externa.

Códigos de retorno

Listo

  • XR_SUCCESS

Falla

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

Cómo obtener información de los ojos

La función xrGetCoarseTrackingEyesInfoANDROID se define de la siguiente manera:

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

Descripciones de los parámetros

La función xrGetCoarseTrackingEyesInfoANDROID obtiene la información de los estados y las poses de los ojos de una manera que preserva la privacidad del usuario.

El tiempo de ejecución debe devolver XR_ERROR_PERMISSION_INSUFFICIENT si la aplicación no tiene el permiso android.permission.EYE_TRACKING_COARSE.

Las poses de los ojos se expresan en XrEyesGetInfoANDROID :: baseSpace en XrEyesGetInfoANDROID :: time .

En cualquier momento, se hace un seguimiento de la posición y la dirección de la pose del ojo, o no se hace. Esto significa que el tiempo de ejecución debe establecer XR_SPACE_LOCATION_POSITION_TRACKED_BIT y XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT o borrar ambos XR_SPACE_LOCATION_POSITION_TRACKED_BIT y XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT en el XrEyesANDROID :: eyes proporcionado , y establecer XrEyesANDROID :: mode para indicar los estados de seguimiento.

Uso válido (implícito)

Códigos de retorno

Listo

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falla

  • 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 función xrGetFineTrackingEyesInfoANDROID se define de la siguiente manera:

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

Descripciones de los parámetros

La función xrGetFineTrackingEyesInfoANDROID obtiene información sobre los estados y las poses de los ojos con mayor precisión que xrGetCoarseTrackingEyesInfoANDROID .

El tiempo de ejecución debe devolver XR_ERROR_PERMISSION_INSUFFICIENT si la aplicación no tiene el permiso android.permission.EYE_TRACKING_FINE.

La información de los ojos se resuelve y es relativa al espacio base en el momento de la llamada a xrGetFineTrackingEyesInfoANDROID con XrEyesGetInfoANDROID :: time , XrEyesGetInfoANDROID :: baseSpace . El tiempo de ejecución debe resolver la ubicación definida por XrEyesGetInfoANDROID :: baseSpace en el momento de la llamada.

En cualquier momento, se hace un seguimiento de la posición y la dirección de la pose del ojo, o no se hace. Esto significa que el tiempo de ejecución debe establecer XR_SPACE_LOCATION_POSITION_TRACKED_BIT y XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT o borrar ambos XR_SPACE_LOCATION_POSITION_TRACKED_BIT y XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT en el XrEyesANDROID :: eyes proporcionado , y establecer XrEyesANDROID :: mode para indicar los estados de seguimiento.

Uso válido (implícito)

Códigos de retorno

Listo

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falla

  • 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 estructura XrEyesGetInfoANDROID contiene la información necesaria para recuperar las poses y los estados de los ojos.

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

Descripciones de los miembros

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.
  • time es el XrTime en el que se deben evaluar las coordenadas relativas al baseSpace .
  • baseSpace es el XrSpace con respecto al cual se ubicarán las poses de los ojos en time .

Uso válido (implícito)

La estructura XrEyesANDROID contiene información sobre los ojos rastreados.

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

Descripciones de los miembros

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.
  • eyes es un array de XrEyeANDROID, de tamaño XR_EYE_MAX_ANDROID, para los ojos izquierdo y derecho, indexados por XrEyeIndexANDROID .
  • mode es el XrEyeTrackingModeANDROID que indica cuál de los ojos se está rastreando en este momento.

Uso válido (implícito)

La estructura XrEyeANDROID describe el estado, la posición y la orientación de un ojo.

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

Descripciones de los miembros

  • eyeState es el XrEyeStateANDROID de un ojo.
  • eyePose es un XrPosef que define la posición y la orientación de la pupila de un ojo dentro del marco de referencia del XrEyesGetInfoANDROID correspondiente :: baseSpace . Aquí, la orientación de la identidad representa un sistema de coordenadas con el eje +Z hacia los ojos del usuario, el eje +X hacia la derecha y el eje +Y hacia arriba.

Uso válido (implícito)

La enumeración XrEyeStateANDROID identifica los diferentes estados de los ojos rastreados.

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;

Los enums tienen los siguientes significados:

Descripción de la enumeración

XR_EYE_STATE_INVALID_ANDROID

Indica que el ojo está en un estado de error o no está presente.

XR_EYE_STATE_GAZING_ANDROID

Indica que el ojo está mirando en este momento.

XR_EYE_STATE_SHUT_ANDROID

Indica que el ojo está cerrado debido a un guiño o un parpadeo.

La enumeración XrEyeIndexANDROID identifica el índice de los ojos izquierdo o derecho.

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

Los enums tienen los siguientes significados:

Descripción de la enumeración

XR_EYE_INDEX_LEFT_ANDROID

Ojo izquierdo.

XR_EYE_INDEX_RIGHT_ANDROID

Ojo derecho.

La enumeración XrEyeTrackingModeANDROID identifica los diferentes estados de los ojos rastreados.

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;

Los enums tienen los siguientes significados:

Descripción de la enumeración

XR_EYE_TRACKING_MODE_NOT_TRACKING_ANDROID

Indica que el seguimiento de ojos no está activo en este momento.

XR_EYE_TRACKING_MODE_RIGHT_ANDROID

Indica que solo se está haciendo el seguimiento del ojo derecho.

XR_EYE_TRACKING_MODE_LEFT_ANDROID

Indica que solo se está haciendo un seguimiento del ojo izquierdo.

XR_EYE_TRACKING_MODE_BOTH_ANDROID

Indica que se realiza el seguimiento de ambos ojos, el izquierdo y el derecho.

Ejemplo de código para el seguimiento de ojos

En el siguiente ejemplo de código, se muestra cómo obtener información de los ojos en relación con un espacio de visualización.

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

Nuevos tipos de objetos

Comandos nuevos

Nuevas estructuras

Nuevas enumeraciones

Nuevas constantes de enumeración

  • XR_ANDROID_EYE_TRACKING_EXTENSION_NAME
  • XR_ANDROID_eye_tracking_SPEC_VERSION
  • XR_EYE_MAX_ANDROID

  • Extensión de XrObjectType :

    • XR_OBJECT_TYPE_EYE_TRACKER_ANDROID

  • Extensión 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

Problemas

Historial de versiones

  • Revisión 1, 2025-01-17 (Kenny Vercaemer)

    • Descripción inicial de la extensión