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

Строка имени

XR_ANDROID_eye_tracking

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

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

Зарегистрированный внутренний номер

457

Редакция

1

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

ОпенXR 1.0

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

17.01.2025

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

Среда выполнения должна вернуть 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 вверх.

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

  • Расширение 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 января 2025 г. (Кенни Веркамер)
    • Первоначальное описание расширения