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

Имя Строка

XR_ANDROID_avatar_eyes (устарело) Внимание: XR_ANDROID_avatar_eyes устарело и будет удалено в будущей версии. Вместо этого используйте XR_ANDROID_eye_tracking .

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

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

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

457

Пересмотр

1

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

OpenXR 1.0

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

2024-09-30

Статус ИС

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

Участники

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

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

Левана Чен, Google

Обзор

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

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

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

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

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

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

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

  • Приложение будет получать 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 .

Если система не поддерживает отслеживание глаз, то из xrCreateEyeTrackerANDROID будет возвращено сообщение XR_ERROR_FEATURE_UNSUPPORTED .

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

  • Расширение XR_ANDROID_avatar_eyes должно быть включено перед вызовом 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

Структура 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_avatar_eyes должно быть включено перед вызовом xrDestroyEyeTrackerANDROID
  • eyeTracker должен быть действительным дескриптором XrEyeTrackerANDROID

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

  • Доступ к 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_ANDROID_avatar_eyes должно быть включено перед вызовом xrGetEyesInfoANDROID
  • eyeTracker должен быть действительным дескриптором XrEyeTrackerANDROID
  • getInfo должен быть указателем на допустимую структуру XrEyesGetInfoANDROID
  • infoOutput должен быть указателем на структуру 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

Структура 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_avatar_eyes
  • 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, 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 г. (Левана Чен)
    • Первоначальное описание расширения

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