XR_ANDROID_eye_tracking

Строка имени

XR_ANDROID_eye_tracking

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

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

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

457

Пересмотр

1

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

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

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

OpenXR 1.0

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

2025-01-17

Статус IP

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

Авторы

Спенсер Куин, Google
Джаред Финдер, Google
Левана Чен, Google
Кенни Веркамер, Google
Прашанти Гурумурти, Google
Нихав Джайн, 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

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

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

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

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

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

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

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

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

В любой момент времени отслеживается или не отслеживается как положение, так и направление взгляда. Это означает, что среда выполнения должна установить значения XR_SPACE_LOCATION_POSITION_TRACKED_BIT и XR_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 .

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

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

В любой момент времени отслеживается или не отслеживается как положение, так и направление взгляда. Это означает, что среда выполнения должна установить значения XR_SPACE_LOCATION_POSITION_TRACKED_BIT и XR_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 необходимо включить перед вызовом функции 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 , относительно которого будут находиться положения глаз в time .

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

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

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

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

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

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
• Режим отслеживания взгляда (XrEyeTrackingMode) ANDROID

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

• 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.01.2025 (Кенни Веркамер)

  • Первоначальное описание расширения