XR_ANDROID_eye_tracking Расширение OpenXR

Строка имени

XR_ANDROID_eye_tracking

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

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

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

457

Пересмотр

1

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

OpenXR 1.0

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

2025-01-17

Статус IP

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

Авторы

Спенсер Куин, Google

Джаред Финдер, Google

Левана Чен, Google

Кенни Веркамер, Google

Прашанти Гурумурти, Google

Нихав Джайн, Google

Обзор

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

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

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

Проверьте возможности системы.

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

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

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

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

Приложение может проверить, способна ли система отслеживать взгляд, добавив структуру XrSystemEyeTrackingPropertiesANDROID к структуре XrSystemProperties при вызове функции xrGetSystemProperties . Если supportsEyeTracking возвращает XR_FALSE , то приложение получит XR_ERROR_FEATURE_UNSUPPORTED от xrCreateEyeTrackerANDROID .

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

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

XR_DEFINE_HANDLE(XrEyeTrackerANDROID)

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

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

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

Отслеживание взгляда обеспечивает отображение положения и состояния глаз в кадре.

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

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

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

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

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

Если система не поддерживает отслеживание взгляда, то функция xrCreateEyeTrackerANDROID вернет XR_ERROR_FEATURE_UNSUPPORTED .

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

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

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

Успех

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Отказ

  • 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

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

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

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

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

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

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

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

XrResult xrDestroyEyeTrackerANDROID(
    XrEyeTrackerANDROID                         eyeTracker);

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

Функция 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 используемый для указания требуемого выходного значения.
  • infoOutput — это указатель на XrEyesANDROID , содержащий информацию о возвращенных глазах, включая их позы и состояния.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  • eyeState — это XrEyeStateANDROID глаза.
  • pose — это объект 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
} 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
} 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
} 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));

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

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

  • XR_EYE_MAX_ANDROID

Перечисление XrObjectType расширено следующим образом:

  • XR_OBJECT_TYPE_EYE_TRACKER_ANDROID

Перечисление XrStructureType расширено следующим образом:

  • XR_TYPE_EYES_ANDROID
  • XR_TYPE_EYE_TRACKER_CREATE_INFO_ANDROID
  • XR_TYPE_EYES_GET_INFO_ANDROID
  • XR_TYPE_SYSTEM_EYE_TRACKING_PROPERTIES_ANDROID

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

Новые сооружения

Новые функции

Проблемы

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

  • Редакция 1, 17.01.2025 (Кенни Веркамер)
    • Первоначальное описание расширения

OpenXR™ и логотип OpenXR являются товарными знаками, принадлежащими компании The Khronos Group Inc. и зарегистрированными в качестве товарных знаков в Китае, Европейском Союзе, Японии и Соединенном Королевстве.