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

Строка имени

XR_ANDROID_avatar_eyes

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

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

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

457

Редакция

1

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

ОпенXR 1.0

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

2024-09-30

IP-статус

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

Авторы

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

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

Левана Чен, Google

Обзор

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

Это расширение предназначено для того, чтобы сделать позу глаз и представление статуса аватаров более реалистичными. Для этой цели:

  • Он допускает неотслеживаемые состояния, такие как мигание.
  • Это позволяет осуществлять монокулярное или бинокулярное отслеживание.

Это расширение не следует использовать для других целей отслеживания взгляда. Для взаимодействия следует использовать XR_EXT_eye_gaze_interaction .

Eye Tracker

Айт-трекер — это сенсорное устройство, которое отслеживает взгляд пользователя и точно отображает, куда смотрит пользователь. Основная цель этого расширения — сопоставить взгляды пользователей с их аватарами в виртуальной сцене.

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

  • Приложение получит XR_ERROR_PERMISSION_INSUFFICIENT при попытке создать активный айтрекер до тех пор, пока приложению не будет разрешен доступ к айтрекеру.

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

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

typedef struct XrSystemAvatarEyesPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsAvatarEyes;
} XrSystemAvatarEyesPropertiesANDROID;

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

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

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

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

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_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

Структура XrEyeTrackerCreateInfoANDROID определяется как:

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

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

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

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

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

Функция xrDestroyEyeTrackerANDROID определяется как:

XrResult xrDestroyEyeTrackerANDROID(
    XrEyeTrackerANDROID                         eyeTracker);

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

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

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

Безопасность потоков

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

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

Успех

  • XR_SUCCESS

Отказ

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

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

Функция xrGetEyesInfoANDROID определяется как:

XrResult xrGetEyesInfoANDROID(
    XrEyeTrackerANDROID                         eyeTracker,
    const XrEyesGetInfoANDROID*                 getInfo,
    XrEyesANDROID*                              infoOutput);

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

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

Функция xrGetEyesInfoANDROID получает информацию о состояниях и позах глаз.

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

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

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

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

Успех

  • 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

Структура 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 вверх.

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

Перечисление 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, for example, 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_xrGetEyesInfoANDROID xrGetEyesInfoANDROID; // 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 eyesInfo{.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(xrGetEyesInfoANDROID(eyeTracker, &eyesGetInfo, &eyesInfo));

    // 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_AVATAR_EYES_PROPERTIES_ANDROID

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

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

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

Проблемы

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

  • Редакция 1, 04 сентября 2024 г. (Левана Чен)
    • Первоначальное описание расширения