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

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 ocular.

Los datos del seguimiento ocular se proporcionan en dos modos: detallado y general. El seguimiento aproximado 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 precisas.

Para la interacción, XR_EXT_eye_gaze_interaction se debe usar.

Cómo inspeccionar 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 ocular.

Una aplicación puede inspeccionar si el sistema es capaz de realizar el seguimiento ocular encadenando una estructura XrSystemEyeTrackingPropertiesANDROID a XrSystemProperties cuando se llama a xrGetSystemProperties. Si supportsEyeTracking muestra XR_FALSE, una aplicación recibirá XR_ERROR_FEATURE_UNSUPPORTED de xrCreateEyeTrackerANDROID.

Uso válido (implícito)

Crea un controlador de rastreador ocular

XR_DEFINE_HANDLE(XrEyeTrackerANDROID)

El control XrEyeTrackerANDROID representa un dispositivo de seguimiento ocular para hacer un seguimiento de los ojos y asignar con precisión lo que el usuario está mirando.

Los datos del seguimiento ocular pueden ser información personal sensible y están estrechamente vinculados con la privacidad y la integridad personal. Se recomienda que las aplicaciones que almacenan o transfieren datos de seguimiento ocular siempre soliciten al usuario una aceptación activa y específica para hacerlo.

Este identificador se puede usar para acceder a los datos del seguimiento ocular con otras funciones de esta extensión.

El seguimiento ocular proporciona la representación de la posición 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 puede crear un control XrEyeTrackerANDROID con la función xrCreateEyeTrackerANDROID.

Si el sistema no admite el seguimiento ocular, se mostrará XR_ERROR_FEATURE_UNSUPPORTED desde xrCreateEyeTrackerANDROID.

Uso válido (implícito)

Códigos de retorno

Éxito

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Error

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

typedef struct XrEyeTrackerCreateInfoANDROID {
    XrStructureType    type;
    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 control 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 finaliza con las experiencias de seguimiento ocular.

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

Éxito

  • XR_SUCCESS

Error

  • 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 entorno de ejecución debe mostrar XR_ERROR_PERMISSION_INSUFFICIENT si la aplicación no tiene el permiso android.permission.EYE_TRACKING_COARSE.

La información de los ojos se resuelve y se relaciona con el espacio base en el momento de la llamada a xrGetCoarseTrackingEyesInfoANDROID con XrEyesGetInfoANDROID::time, XrEyesGetInfoANDROID::baseSpace.

En cualquier momento, se puede hacer un seguimiento de la posición y la dirección de la posición de los ojos o no. Esto significa que las aplicaciones pueden esperar que XR_SPACE_LOCATION_POSITION_TRACKED_BIT y XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT se establezcan o se borren en el XrEyesANDROID::eyes proporcionado y que XrEyesANDROID::mode indique los estados de seguimiento.

Uso válido (implícito)

Códigos de retorno

Éxito

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Error

  • 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 función xrGetFineTrackingEyesInfoANDROID se define de la siguiente manera: {:#xrGetFineTrackingEyesInfoANDROID} C++ XrResult xrGetFineTrackingEyesInfoANDROID( XrEyeTrackerANDROID eyeTracker, const XrEyesGetInfoANDROID* getInfo, XrEyesANDROID* eyesOutput);

Descripciones de los parámetros

El entorno de ejecución debe mostrar 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 se relaciona con el espacio base en el momento de la llamada a xrGetFineTrackingEyesInfoANDROID con XrEyesGetInfoANDROID::time, XrEyesGetInfoANDROID::baseSpace.

En cualquier momento, se puede hacer un seguimiento de la posición y la dirección de la posición de los ojos o no. Esto significa que las aplicaciones pueden esperar que XR_SPACE_LOCATION_POSITION_TRACKED_BIT y XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT se establezcan o se borren en el XrEyesANDROID::eyes proporcionado y que XrEyesANDROID::mode indique los estados de seguimiento.

Uso válido (implícito)

Códigos de retorno

Éxito

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Error

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

typedef struct XrEyesGetInfoANDROID {
    XrStructureType    type;
    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 en relación con baseSpace.
  • baseSpace La posición de los ojos será relativa a este XrSpace en time.

Uso válido (implícito)

La estructura XrEyesANDROID contiene información sobre los ojos a los que se les hizo un seguimiento. 

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 para el ojo izquierdo y derecho, como lo indexa XrEyeIndexANDROID.
  • mode es el XrEyeTrackingModeANDROID para indicar si los ojos están realizando el seguimiento y cuáles.

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.
  • pose es un XrPosef que define la posición y la orientación del origen 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 en los ojos del usuario, +X a la derecha y +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
} XrEyeStateANDROID;

Las enumeraciones tienen los siguientes significados:

Enum

Descripció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.

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 del ojo izquierdo o derecho. 

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

Las enumeraciones tienen los siguientes significados:

Enum

Descripción

XR_EYE_INDEX_LEFT_ANDROID

Ojo izquierdo.

XR_EYE_INDEX_RIGHT_ANDROID

Ojo derecho.

La enumeración XrEyeTrackingModeANDROID identifica los diferentes modos de 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
} XrEyeTrackingModeANDROID;

Las enumeraciones tienen los siguientes significados:

Enum

Descripción

XR_EYE_TRACKING_MODE_NOT_TRACKING_ANDROID

Indica que el seguimiento ocular no está activo.

XR_EYE_TRACKING_MODE_RIGHT_ANDROID

Indica que solo se realiza el seguimiento del ojo derecho.

XR_EYE_TRACKING_MODE_LEFT_ANDROID

Indica que solo el ojo izquierdo realiza el seguimiento.

XR_EYE_TRACKING_MODE_BOTH_ANDROID

Indica que los ojos izquierdo y derecho están realizando el seguimiento.

Ejemplo de código para el seguimiento ocular

En el siguiente ejemplo de código, se muestra cómo obtener información sobre el ojo 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

Nuevas constantes de enum

  • XR_EYE_MAX_ANDROID

La enumeración XrObjectType se extiende con lo siguiente:

  • XR_OBJECT_TYPE_EYE_TRACKER_ANDROID

La enumeración XrStructureType se extiende con lo siguiente:

  • XR_TYPE_EYES_ANDROID
  • XR_TYPE_EYE_TRACKER_CREATE_INFO_ANDROID
  • XR_TYPE_EYES_GET_INFO_ANDROID
  • XR_TYPE_SYSTEM_EYE_TRACKING_PROPERTIES_ANDROID

Enumeraciones nuevas

Nuevas estructuras

Funciones nuevas

Problemas

Historial de versiones

  • Revisión 1, 17/01/2025 (Kenny Vercaemer)
    • Descripción inicial de la extensión