XR_ANDROID_eye_tracking

Name String

XR_ANDROID_eye_tracking

Тип расширения

Расширение экземпляра

Зарегистрированный добавочный номер

457

Revision

1

Статус ратификации

Не ратифицировано

Зависимости расширений и версий

OpenXR 1.0

Дата последнего изменения

2025-01-17

Статус IP-адреса

Нет известных претензий в отношении интеллектуальной собственности.

Авторы

Спенсер Куин (Spencer Quin), Google
Джаред Финдер (Jared Finder), Google
Леван Чен (Levana Chen), Google
Кенни Веркамер (Kenny Vercaemer), Google
Прасанти Гурумурти (Prasanthi Gurumurthy), Google
Нихав Джайн (Nihav Jain), Google

Обзор

Это расширение позволяет приложениям получать данные о положении и ориентации глаз пользователя, а также о статусе отслеживания взгляда.

Данные отслеживания взгляда предоставляются в двух режимах: приблизительном и точном. Приблизительное отслеживание дает приблизительную оценку положения глаз пользователя, а точное – более точную. Приблизительное отслеживание предназначено для приложений, в которых нужно создать базовое представление, похожее на аватар, а точное – для приложений, в которых требуется более высокая точность.

Для взаимодействия следует использовать XR_EXT_eye_gaze_interaction.

Разрешения

В манифесте приложений для Android должно быть указано разрешение android.permission.EYE_TRACKING_COARSE или android.permission.EYE_TRACKING_FINE. Такие разрешения считаются опасными. Приложение должно запрашивать разрешение на использование следующих функций:

• xrCreateEyeTrackerANDROID (хотя бы одно из разрешений)
• xrGetCoarseTrackingEyesInfoANDROID (android.permission.EYE_TRACKING_COARSE)
• xrGetFineTrackingEyesInfoANDROID (android.permission.EYE_TRACKING_FINE)

(уровень защиты: опасный)

Проверка возможностей системы

Структура XrSystemEyeTrackingPropertiesANDROID определяется следующим образом:

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

Описания участников

• type – это XrStructureType этой структуры.
• next – это NULL или указатель на следующую структуру в цепочке. Такие структуры не определены в ядре OpenXR или этом расширении.
• supportsEyeTracking – это XrBool32, указывающий, поддерживает ли текущая система отслеживание взгляда.

Приложение может проверить, поддерживает ли система отслеживание взгляда. Для этого нужно расширить XrSystemProperties с помощью структуры XrSystemEyeTrackingPropertiesANDROID при вызове xrGetSystemProperties.

Если и только если среда выполнения возвращает XR_FALSE для supportsEyeTracking , она должна возвращать XR_ERROR_FEATURE_UNSUPPORTED из xrCreateEyeTrackerANDROID .

Допустимое использование (неявное)

• Расширение XR_ANDROID_eye_tracking должно быть включено до использования XrSystemEyeTrackingPropertiesANDROID.
• type должно быть XR_TYPE_SYSTEM_EYE_TRACKING_PROPERTIES_ANDROID
• next должно быть NULL или действительным указателем на следующую структуру в цепочке структур.

Создание дескриптора отслеживания взгляда

XR_DEFINE_HANDLE(XrEyeTrackerANDROID)

Дескриптор XrEyeTrackerANDROID представляет собой трекер, который отслеживает взгляд пользователя и точно определяет, куда он смотрит.

Данные отслеживания взгляда – это конфиденциальная личная информация, которая тесно связана с конфиденциальностью и целостностью личности. Мы настоятельно рекомендуем, чтобы приложения, которые хранят или передают данные отслеживания взгляда, всегда запрашивали у пользователя активное и конкретное согласие на это.

Приложение использует этот дескриптор для доступа к данным отслеживания взгляда с помощью других функций в этом расширении.

Отслеживание взгляда позволяет определить положение и состояние глаз в сцене.

Функция xrCreateEyeTrackerANDROID определяется следующим образом:

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

Описание параметров

• session – дескриптор XrSession, в котором будет активно отслеживание взгляда.
• createInfo – это XrEyeTrackerCreateInfoANDROID, используемый для указания отслеживания взгляда.
• eyeTracker – возвращенный дескриптор XrEyeTrackerANDROID.

Приложение создает дескриптор XrEyeTrackerANDROID с помощью функции xrCreateEyeTrackerANDROID.

Если система не поддерживает отслеживание взгляда, среда выполнения должна возвращать XR_ERROR_FEATURE_UNSUPPORTED из xrCreateEyeTrackerANDROID .

Допустимое использование (неявное)

• Расширение XR_ANDROID_eye_tracking должно быть включено до вызова xrCreateEyeTrackerANDROID.
• session должен быть действительным дескриптором XrSession.
• createInfo должен быть указателем на действительную структуру XrEyeTrackerCreateInfoANDROID.
• eyeTracker должен быть указателем на дескриптор XrEyeTrackerANDROID.

Коды возврата

Выполнено

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Сбой

• 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

Структура XrEyeTrackerCreateInfoANDROID определяется следующим образом:

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

Описания участников

• type – это XrStructureType этой структуры.
• next – это NULL или указатель на следующую структуру в цепочке. Такие структуры не определены в ядре OpenXR или этом расширении.

Структура XrEyeTrackerCreateInfoANDROID описывает информацию, необходимую для создания дескриптора XrEyeTrackerANDROID.

Допустимое использование (неявное)

• Расширение XR_ANDROID_eye_tracking должно быть включено до использования XrEyeTrackerCreateInfoANDROID.
• type должно быть XR_TYPE_EYE_TRACKER_CREATE_INFO_ANDROID
• next должно быть NULL или действительным указателем на следующую структуру в цепочке структур.

Функция xrDestroyEyeTrackerANDROID определяется следующим образом:

XrResult xrDestroyEyeTrackerANDROID(
    XrEyeTrackerANDROID                         eyeTracker);

Описание параметров

• eyeTracker – это XrEyeTrackerANDROID, ранее созданный с помощью xrCreateEyeTrackerANDROID .

Функция xrDestroyEyeTrackerANDROID освобождает eyeTracker и базовые ресурсы после завершения отслеживания взгляда.

Допустимое использование (неявное)

• Расширение XR_ANDROID_eye_tracking должно быть включено до вызова xrDestroyEyeTrackerANDROID.
• eyeTracker должен быть действительным дескриптором XrEyeTrackerANDROID.

Потокобезопасность

• Доступ к eyeTracker и любым дочерним дескрипторам должен быть синхронизирован извне.

Коды возврата

Выполнено

• XR_SUCCESS

Сбой

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_RUNTIME_FAILURE

Получение информации о глазах

Функция xrGetCoarseTrackingEyesInfoANDROID определяется следующим образом:

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

Описание параметров

• eyeTracker – это XrEyeTrackerANDROID, ранее созданный с помощью xrCreateEyeTrackerANDROID .
• getInfo – указатель на XrEyesGetInfoANDROID, который используется для предоставления информации, необходимой для запроса положения и состояния глаз.
• eyesOutput – указатель на XrEyesANDROID, который содержит возвращенную информацию о глазах, включая позы и состояния.

Функция xrGetCoarseTrackingEyesInfoANDROID получает информацию о состоянии и положении глаз, не нарушая конфиденциальность пользователя.

Среда выполнения должна возвращать XR_ERROR_PERMISSION_INSUFFICIENT, если у приложения нет разрешения android.permission.EYE_TRACKING_COARSE.

Положения глаз выражаются в XrEyesGetInfoANDROID :: baseSpace в XrEyesGetInfoANDROID :: time .

В любой момент времени положение и направление взгляда либо отслеживаются, либо нет. Это означает, что среда выполнения должна задать XR_SPACE_LOCATION_POSITION_TRACKED_BITXR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT или очистить оба значения XR_SPACE_LOCATION_POSITION_TRACKED_BIT и XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT в предоставленном XrEyesANDROID :: eyes, а также задать XrEyesANDROID :: mode, чтобы указать состояния отслеживания.

Допустимое использование (неявное)

• Расширение XR_ANDROID_eye_tracking должно быть включено до вызова xrGetCoarseTrackingEyesInfoANDROID.
• eyeTracker должен быть действительным дескриптором XrEyeTrackerANDROID.
• getInfo должен быть указателем на действительную структуру XrEyesGetInfoANDROID.
• eyesOutput должен быть указателем на структуру XrEyesANDROID.

Коды возврата

Выполнено

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Сбой

• 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

Функция xrGetFineTrackingEyesInfoANDROID определяется следующим образом:

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

Описание параметров

• eyeTracker – это XrEyeTrackerANDROID, ранее созданный с помощью xrCreateEyeTrackerANDROID .
• getInfo – указатель на XrEyesGetInfoANDROID, который используется для указания того, какие выходные данные требуются.
• eyesOutput – указатель на XrEyesANDROID, который содержит возвращенную информацию о глазах, включая позы и состояния.

Функция xrGetFineTrackingEyesInfoANDROID получает информацию о состояниях и позах глаз с более высокой точностью, чем xrGetCoarseTrackingEyesInfoANDROID .

Среда выполнения должна возвращать XR_ERROR_PERMISSION_INSUFFICIENT, если у приложения нет разрешения android.permission.EYE_TRACKING_FINE.

Информация о глазах разрешается и соотносится с базовым пространством во время вызова xrGetFineTrackingEyesInfoANDROID с использованием XrEyesGetInfoANDROID :: time , XrEyesGetInfoANDROID :: baseSpace . Среда выполнения должна определить местоположение, заданное в XrEyesGetInfoANDROID :: baseSpace, во время вызова.

В любой момент времени положение и направление взгляда либо отслеживаются, либо нет. Это значит, что среда выполнения должна задать или очистить оба значения XR_SPACE_LOCATION_POSITION_TRACKED_BIT и XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT в предоставленном XrEyesANDROID :: eyes, а также задать XrEyesANDROID :: mode, чтобы указать состояния отслеживания.XR_SPACE_LOCATION_POSITION_TRACKED_BITXR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT

Допустимое использование (неявное)

• Расширение XR_ANDROID_eye_tracking должно быть включено до вызова xrGetFineTrackingEyesInfoANDROID.
• eyeTracker должен быть действительным дескриптором XrEyeTrackerANDROID.
• getInfo должен быть указателем на действительную структуру XrEyesGetInfoANDROID.
• eyesOutput должен быть указателем на структуру XrEyesANDROID.

Коды возврата

Выполнено

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Сбой

• 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

Структура XrEyesGetInfoANDROID содержит информацию, необходимую для получения положения и состояния глаз.

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

Описания участников

• type – это XrStructureType этой структуры.
• next – это NULL или указатель на следующую структуру в цепочке. Такие структуры не определены в ядре OpenXR или этом расширении.
• time – XrTime, в которой нужно оценить координаты относительно baseSpace .
• baseSpace – XrSpace, в котором возвращаются положения глаз.

Допустимое использование (неявное)

• Расширение XR_ANDROID_eye_tracking должно быть включено до использования XrEyesGetInfoANDROID.
• type должно быть XR_TYPE_EYES_GET_INFO_ANDROID
• next должно быть NULL или действительным указателем на следующую структуру в цепочке структур.
• baseSpace должен быть действительным идентификатором XrSpace.

Структура XrEyesANDROID содержит информацию об отслеживаемых глазах.

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

Описания участников

• type – это XrStructureType этой структуры.
• next – это NULL или указатель на следующую структуру в цепочке. Такие структуры не определены в ядре OpenXR или этом расширении.
• eyes – это массив XrEyeANDROID размером XR_EYE_MAX_ANDROID для левого и правого глаза, индексируемый по XrEyeIndexANDROID .
• mode – XrEyeTrackingModeANDROID, указывающий, за какими глазами сейчас ведется слежение.

Допустимое использование (неявное)

• Расширение XR_ANDROID_eye_tracking должно быть включено до использования XrEyesANDROID.
• type должно быть XR_TYPE_EYES_ANDROID
• next должно быть NULL или действительным указателем на следующую структуру в цепочке структур.
• Любой элемент eyes должен быть допустимой структурой XrEyeANDROID.
• mode должно быть действительным значением XrEyeTrackingModeANDROID.

Структура XrEyeANDROID описывает состояние, положение и ориентацию глаза.

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

Описания участников

• eyeState – это XrEyeStateANDROID глаза.
• eyePose – это XrPosef, определяющий положение и ориентацию зрачка глаза в системе отсчета соответствующего XrEyesGetInfoANDROID :: baseSpace . Ориентация идентичности представляет собой оси координат, где +Z направлена в глаза пользователя, +X – вправо, а +Y – вверх.

Допустимое использование (неявное)

• Расширение XR_ANDROID_eye_tracking должно быть включено до использования XrEyeANDROID.
• eyeState должно быть допустимым значением XrEyeStateANDROID.

Перечисление XrEyeStateANDROID определяет разные состояния отслеживаемых глаз.

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;

Перечисления имеют следующие значения:

Описание перечисления

XR_EYE_STATE_INVALID_ANDROID

Указывает, что глаз находится в состоянии ошибки или отсутствует.

XR_EYE_STATE_GAZING_ANDROID

Указывает, что взгляд зафиксирован.

XR_EYE_STATE_SHUT_ANDROID

Указывает, что глаз закрыт (человек моргает или подмигивает).

Перечисление XrEyeIndexANDROID определяет индекс левого или правого глаза.

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

Перечисления имеют следующие значения:

Описание перечисления

XR_EYE_INDEX_LEFT_ANDROID

Левый глаз.

XR_EYE_INDEX_RIGHT_ANDROID

Правый глаз.

Перечисление XrEyeTrackingModeANDROID определяет разные состояния отслеживаемых глаз.

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;

Перечисления имеют следующие значения:

Описание перечисления

XR_EYE_TRACKING_MODE_NOT_TRACKING_ANDROID

Указывает, что отслеживание взгляда сейчас неактивно.

XR_EYE_TRACKING_MODE_RIGHT_ANDROID

Указывает, что отслеживается только правый глаз.

XR_EYE_TRACKING_MODE_LEFT_ANDROID

Указывает, что отслеживается только левый глаз.

XR_EYE_TRACKING_MODE_BOTH_ANDROID

Указывает, что отслеживаются оба глаза.

#define XR_EYE_MAX_ANDROID                2

XR_EYE_MAX_ANDROID – максимальное количество глаз, для которых передаются данные XrEyeANDROID.

Пример кода для отслеживания взгляда

В примере кода ниже показано, как получить информацию о глазах относительно области просмотра.

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

Новые типы объектов

• XrEyeTrackerANDROID

Новые команды

• xrCreateEyeTrackerANDROID
• xrDestroyEyeTrackerANDROID
• xrGetCoarseTrackingEyesInfoANDROID
• xrGetFineTrackingEyesInfoANDROID

Новые структуры

• XrEyeANDROID
• XrEyeTrackerCreateInfoANDROID
• XrEyesANDROID
• XrEyesGetInfoANDROID

• Расширение XrSystemProperties :

  • XrSystemEyeTrackingPropertiesANDROID

Новые перечисления

• XrEyeIndexANDROID
• XrEyeStateANDROID
• XrEyeTrackingModeANDROID

Новые константы перечисления

• XR_ANDROID_EYE_TRACKING_EXTENSION_NAME
• XR_ANDROID_eye_tracking_SPEC_VERSION
• XR_EYE_MAX_ANDROID

• Расширение XrObjectType :

  • XR_OBJECT_TYPE_EYE_TRACKER_ANDROID

• Расширение 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

Проблемы

История версий

• Версия 1, 17 января 2025 г. (Кенни Веркамер)

  • Описание расширения