XR_ANDROID_eye_tracking

Name String

XR_ANDROID_eye_tracking

Tipo de extensión

Extensión de instancia

Número de extensión registrado

457

Revisión

1

Estado de ratificación

No ratificado

Dependencias de extensiones y versiones

OpenXR 1.0

Fecha de la última modificación

2025-01-17

Estado de la IP

No hay reclamos de IP conocidos.

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 aproximado proporciona una estimación aproximada de los ojos del usuario, mientras que el seguimiento preciso proporciona una estimación más exacta. El seguimiento aproximado está pensado para aplicaciones que quieren proporcionar una representación básica similar a un avatar, mientras que el seguimiento preciso está pensado para aplicaciones más precisas.

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 un seguimiento de ojos extendiendo XrSystemProperties con la estructura XrSystemEyeTrackingPropertiesANDROID cuando se llama a xrGetSystemProperties .

Solo si un entorno de ejecución devuelve XR_FALSE para supportsEyeTracking , el entorno de ejecución debe devolver XR_ERROR_FEATURE_UNSUPPORTED desde xrCreateEyeTrackerANDROID .

Uso válido (implícito)

Cómo crear un controlador de seguimiento de ojos

XR_DEFINE_HANDLE(XrEyeTrackerANDROID)

El handle XrEyeTrackerANDROID representa un seguidor de ojos para el seguimiento de ojos y mapear con precisión hacia 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 de las personas. Se recomienda encarecidamente que las aplicaciones que almacenan o transfieren datos de seguimiento de ojos siempre soliciten al usuario una aceptación activa y específica para hacerlo.

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

El seguimiento de ojos proporciona una 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 controlador XrEyeTrackerANDROID con la función xrCreateEyeTrackerANDROID.

Si el sistema no admite el seguimiento de ojos, el entorno 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 controlador 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 controlador secundario debe sincronizarse de forma externa.

Códigos de retorno

Listo

  • XR_SUCCESS

Falla

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Obteniendo 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 entorno 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 realiza o no un seguimiento de la posición y la dirección de la pose de los ojos. Esto significa que el entorno de ejecución debe establecer XR_SPACE_LOCATION_POSITION_TRACKED_BIT y XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT, o borrar 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 la información de los estados y las poses de los ojos con mayor precisión que xrGetCoarseTrackingEyesInfoANDROID .

El entorno 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 entorno de ejecución debe resolver la ubicación definida por XrEyesGetInfoANDROID :: baseSpace en el momento de la llamada.

En cualquier momento, se realiza o no un seguimiento de la posición y la dirección de la pose de los ojos. Esto significa que el entorno de ejecución debe establecer XR_SPACE_LOCATION_POSITION_TRACKED_BIT y XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT, o borrar 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 evalúan las coordenadas en relación con el baseSpace .
  • baseSpace es el XrSpace en el que se devolverán las poses de los ojos.

Uso válido (implícito)

La estructura XrEyesANDROID contiene información sobre los ojos que se siguen.

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, según lo indexado por XrEyeIndexANDROID .
  • mode es el XrEyeTrackingModeANDROID que indica cuál de los ojos se está siguiendo 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 :: baseSpace correspondiente. Aquí, una orientación de identidad representa un eje de coordenadas con +Z hacia los ojos del usuario, +X hacia la derecha y +Y hacia arriba.

Uso válido (implícito)

La enumeración XrEyeStateANDROID identifica los diferentes estados de los ojos que se siguen.

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;

Las enumeraciones tienen los siguientes significados:

Descripción de enum

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;

Las enumeraciones tienen los siguientes significados:

Descripción de enum

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 que se siguen.

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;

Las enumeraciones tienen los siguientes significados:

Descripción de enum

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 un 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 están siguiendo ambos ojos, el izquierdo y el derecho.

#define XR_EYE_MAX_ANDROID                2

XR_EYE_MAX_ANDROID es la cantidad máxima de ojos para los que se informan los datos de XrEyeANDROID.

Código de ejemplo para el seguimiento de ojos

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

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

Estructuras nuevas

Enums nuevas

Nuevas constantes de enum

  • XR_ANDROID_EYE_TRACKING_EXTENSION_NAME
  • XR_ANDROID_eye_tracking_SPEC_VERSION
  • XR_EYE_MAX_ANDROID

  • Extiende XrObjectType :

    • XR_OBJECT_TYPE_EYE_TRACKER_ANDROID

  • Extiende 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, 17 de enero de 2025 (Kenny Vercaemer)

    • Descripción inicial de la extensión