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

Имя Строка

XR_ANDROID_eye_tracking

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

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

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

457

Пересмотр

1

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

OpenXR 1.0

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

2025-01-17

Статус ИС

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

Участники

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

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

Информация о глазах разрешается и соотносится с базовым пространством во время вызова 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 определяется следующим образом: {:#xrGetFineTrackingEyesInfoANDROID} C++ XrResult xrGetFineTrackingEyesInfoANDROID( XrEyeTrackerANDROID eyeTracker, const XrEyesGetInfoANDROID* getInfo, XrEyesANDROID* eyesOutput);

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

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

Информация о глазах разрешается и соотносится с базовым пространством во время вызова 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 вверх.

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

  • Перед использованием XrEyeANDROID необходимо включить расширение XR_ANDROID_eye_tracking
  • 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, 2025-01-17 (Кенни Веркемер)
    • Первоначальное описание расширения

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