Extensión OpenXR XR_ANDROID_avatar_eyes

Cadena de nombre

XR_ANDROID_avatar_eyes

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 última modificación

2024-09-30

Estado de la IP

No hay reclamos de IP conocidos.

Colaboradores

Spencer Quin, Google

Jared Finder, Google

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

El objetivo de esta extensión es hacer que la representación de la posición y el estado de los ojos de los avatares sea más realista. Para ello, sigue estos pasos:

  • Permite estados sin seguimiento, como el parpadeo.
  • Permite el seguimiento monocular o binocular.

Esta extensión no debe usarse para otros fines de seguimiento ocular. Para la interacción, XR_EXT_eye_gaze_interaction se debe usar.

Seguimiento ocular

Un dispositivo de seguimiento ocular es un dispositivo de detección que hace un seguimiento de los ojos y mapea con precisión hacia dónde está mirando el usuario. El objetivo principal de esta extensión es asignar las miradas de los usuarios a sus avatares en una escena virtual.

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.

  • Una aplicación recibirá XR_ERROR_PERMISSION_INSUFFICIENT cuando intente crear un dispositivo de seguimiento ocular activo hasta que se le permita el acceso al dispositivo.

Cómo inspeccionar la capacidad del sistema

Una aplicación puede inspeccionar si el sistema admite ojos de avatar encadenando una estructura XrSystemAvatarEyesPropertiesANDROID a XrSystemProperties cuando se llama a xrGetSystemProperties. Si supportsAvatarEyes muestra XR_FALSE, una aplicación recibirá XR_ERROR_FEATURE_UNSUPPORTED de xrCreateEyeTrackerANDROID.

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

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.
  • supportsAvatarEyes es un XrBool32, que indica si el sistema actual admite ojos de avatar.

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.

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 controlador 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

Correcto

  • 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

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 se terminan 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

Correcto

  • XR_SUCCESS

Error

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

Cómo obtener información de los ojos

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

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

Descripciones de los parámetros

La función xrGetEyesInfoANDROID obtiene la información de los estados y las poses de los ojos.

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

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

Uso válido (implícito)

Códigos de retorno

Correcto

  • 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

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 del ojo 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 hace 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 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 extensión XR_ANDROID_avatar_eyes debe estar habilitada antes de usar XrEyeANDROID.
  • eyeState debe ser un valor válido de XrEyeStateANDROID.

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

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_AVATAR_EYES_PROPERTIES_ANDROID

Enumeraciones nuevas

Nuevas estructuras

Funciones nuevas

Problemas

Historial de versiones

  • Revisión 1, 4 de septiembre de 2024 (Levana Chen)
    • Descripción inicial de la extensión