XR_ANDROID_eye_tracking

Ciąg znaków nazwy

XR_ANDROID_eye_tracking

Typ rozszerzenia

Rozszerzenie instancji

Zarejestrowany numer wewnętrzny

457

Wersja

1

Stan ratyfikacji

Nie ratyfikowano

Zależności rozszerzeń i wersji

OpenXR 1.0

Data ostatniej modyfikacji

2025-01-17

Stan adresu IP

Brak znanych roszczeń dotyczących własności intelektualnej.

Twórcy

Spencer Quin, Google
Jared Finder, Google
Levana Chen, Google
Kenny Vercaemer, Google
Prasanthi Gurumurthy, Google
Nihav Jain, Google

Omówienie

To rozszerzenie umożliwia aplikacjom uzyskiwanie informacji o pozycji i orientacji oczu użytkownika, a także o stanie śledzenia wzroku.

Dane śledzenia wzroku są udostępniane w 2 trybach: przybliżonym i dokładnym. Śledzenie zgrubne zapewnia przybliżone oszacowanie położenia oczu użytkownika, a śledzenie dokładne – dokładniejsze. Śledzenie przybliżone jest przeznaczone dla aplikacji, które chcą wyświetlać podstawową reprezentację w postaci awatara, a śledzenie dokładne – dla aplikacji wymagających większej precyzji.

Do interakcji należy używać XR_EXT_eye_gaze_interaction .

Uprawnienia

Aplikacje na Androida muszą mieć w pliku manifestu uprawnienie android.permission.EYE_TRACKING_COARSE lub android.permission.EYE_TRACKING_FINE. Są one uznawane za niebezpieczne. Aby korzystać z tych funkcji, aplikacja musi prosić o uprawnienia w czasie działania:

(poziom ochrony: niebezpieczny)

Sprawdzanie możliwości systemu

Struktura XrSystemEyeTrackingPropertiesANDROID jest zdefiniowana w ten sposób:

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

Opisy członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur. W podstawowej specyfikacji OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.
  • supportsEyeTracking to XrBool32 wskazujący, czy bieżący system obsługuje śledzenie wzroku.

Aplikacja może sprawdzić, czy system obsługuje śledzenie wzroku, rozszerzając strukturę XrSystemProperties o strukturę XrSystemEyeTrackingPropertiesANDROID podczas wywoływania funkcji xrGetSystemProperties .

Jeśli środowisko wykonawcze zwraca XR_FALSE dla supportsEyeTracking , musi zwrócić XR_ERROR_FEATURE_UNSUPPORTED z funkcji xrCreateEyeTrackerANDROID .

Prawidłowe użycie (domyślne)

Tworzenie uchwytu do śledzenia wzroku

XR_DEFINE_HANDLE(XrEyeTrackerANDROID)

Uchwyt XrEyeTrackerANDROID reprezentuje urządzenie do śledzenia wzroku, które dokładnie określa, na co patrzy użytkownik.

Dane śledzenia wzroku to wrażliwe dane osobowe, które są ściśle powiązane z prywatnością i integralnością osobistą. Zdecydowanie zalecamy, aby aplikacje, które przechowują lub przesyłają dane śledzenia wzroku, zawsze prosiły użytkownika o aktywną i konkretną zgodę na takie działanie.

Aplikacja używa tego uchwytu do uzyskiwania dostępu do danych śledzenia wzroku za pomocą innych funkcji tego rozszerzenia.

Śledzenie wzroku zapewnia reprezentację pozycji i stanu oczu w scenie.

Funkcja xrCreateEyeTrackerANDROID jest zdefiniowana w ten sposób:

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

Opisy parametrów

Aplikacja tworzy uchwyt XrEyeTrackerANDROID za pomocą funkcji xrCreateEyeTrackerANDROID.

Jeśli system nie obsługuje śledzenia wzroku, środowisko wykonawcze musi zwracać wartość XR_ERROR_FEATURE_UNSUPPORTED z funkcji xrCreateEyeTrackerANDROID .

Prawidłowe użycie (domyślne)

Kody zwrotne

Sukces

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Błąd

  • XR_ERROR_FEATURE_UNSUPPORTED
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

Struktura XrEyeTrackerCreateInfoANDROID jest zdefiniowana w ten sposób:

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

Opisy członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur. W podstawowej specyfikacji OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.

Struktura XrEyeTrackerCreateInfoANDROID zawiera informacje potrzebne do utworzenia uchwytu XrEyeTrackerANDROID.

Prawidłowe użycie (domyślne)

Funkcja xrDestroyEyeTrackerANDROID jest zdefiniowana w ten sposób:

XrResult xrDestroyEyeTrackerANDROID(
    XrEyeTrackerANDROID                         eyeTracker);

Opisy parametrów

Funkcja xrDestroyEyeTrackerANDROID zwalnia eyeTracker i powiązane z nim zasoby po zakończeniu korzystania z funkcji śledzenia wzroku.

Prawidłowe użycie (domyślne)

Bezpieczeństwo wątków

  • Dostęp do eyeTracker i wszystkich uchwytów podrzędnych musi być synchronizowany zewnętrznie.

Kody zwrotne

Sukces

  • XR_SUCCESS

Błąd

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

Uzyskiwanie informacji o oczach

Funkcja xrGetCoarseTrackingEyesInfoANDROID jest zdefiniowana w ten sposób:

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

Opisy parametrów

Funkcja xrGetCoarseTrackingEyesInfoANDROID pobiera informacje o stanie i położeniu oczu w sposób, który chroni prywatność użytkownika.

Środowisko wykonawcze musi zwracać wartość XR_ERROR_PERMISSION_INSUFFICIENT, jeśli aplikacja nie ma uprawnienia android.permission.EYE_TRACKING_COARSE.

Pozycje oczu są wyrażane w XrEyesGetInfoANDROID :: baseSpace w XrEyesGetInfoANDROID :: time .

W każdym momencie śledzona jest pozycja i kierunek wzroku. Oznacza to, że środowisko wykonawcze musi ustawić zarówno XR_SPACE_LOCATION_POSITION_TRACKED_BIT, jak i XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT lub wyczyścić zarówno XR_SPACE_LOCATION_POSITION_TRACKED_BIT, jak i XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT w dostarczonym polu XrEyesANDROID :: eyes oraz ustawić XrEyesANDROID :: mode, aby wskazać stany śledzenia.

Prawidłowe użycie (domyślne)

Kody zwrotne

Sukces

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Błąd

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_PERMISSION_INSUFFICIENT
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

Funkcja xrGetFineTrackingEyesInfoANDROID jest zdefiniowana w ten sposób:

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

Opisy parametrów

Funkcja xrGetFineTrackingEyesInfoANDROID pobiera informacje o stanach i pozycjach oczu z większą precyzją niż funkcja xrGetCoarseTrackingEyesInfoANDROID .

Środowisko wykonawcze musi zwracać wartość XR_ERROR_PERMISSION_INSUFFICIENT, jeśli aplikacja nie ma uprawnień android.permission.EYE_TRACKING_FINE.

Informacje o oczach są określane względem przestrzeni bazowej w momencie wywołania funkcji xrGetFineTrackingEyesInfoANDROID za pomocą funkcji XrEyesGetInfoANDROID :: time i XrEyesGetInfoANDROID :: baseSpace . Środowisko wykonawcze musi określić lokalizację zdefiniowaną przez XrEyesGetInfoANDROID :: baseSpace w momencie wywołania.

W każdym momencie śledzona jest pozycja i kierunek wzroku. Oznacza to, że środowisko wykonawcze musi ustawić zarówno XR_SPACE_LOCATION_POSITION_TRACKED_BIT, jak i XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT lub wyczyścić zarówno XR_SPACE_LOCATION_POSITION_TRACKED_BIT, jak i XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT w dostarczonym polu XrEyesANDROID :: eyes oraz ustawić XrEyesANDROID :: mode, aby wskazać stany śledzenia.

Prawidłowe użycie (domyślne)

Kody zwrotne

Sukces

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Błąd

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_PERMISSION_INSUFFICIENT
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

Struktura XrEyesGetInfoANDROID zawiera informacje wymagane do pobrania pozycji i stanów oczu.

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

Opisy członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur. W podstawowej specyfikacji OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.
  • time to XrTime, w którym należy ocenić współrzędne względem baseSpace .
  • baseSpace to XrSpace, względem którego będą określane pozycje oczu w momencie time .

Prawidłowe użycie (domyślne)

Struktura XrEyesANDROID zawiera informacje o śledzonych oczach.

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

Opisy członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur. W podstawowej specyfikacji OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.
  • eyes to tablica XrEyeANDROID o rozmiarze XR_EYE_MAX_ANDROID dla lewego i prawego oka, indeksowana przez XrEyeIndexANDROID .
  • mode to XrEyeTrackingModeANDROID wskazujący, które oczy są obecnie śledzone.

Prawidłowe użycie (domyślne)

Struktura XrEyeANDROID opisuje stan, położenie i orientację oka.

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

Opisy członków

  • eyeState to XrEyeStateANDROID oka.
  • eyePose to XrPosef określający położenie i orientację źrenicy w ramach odniesienia odpowiedniego XrEyesGetInfoANDROID :: baseSpace . Orientacja to układ osi współrzędnych, w którym oś Z jest skierowana w stronę oczu użytkownika, oś X w prawo, a oś Y w górę.

Prawidłowe użycie (domyślne)

  •  Rozszerzenie XR_ANDROID_eye_tracking musi być włączone przed użyciem XrEyeANDROID.
  • eyeState musi być prawidłową wartością XrEyeStateANDROID

Wyliczenie XrEyeStateANDROID określa różne stany śledzonych oczu.

typedef enum XrEyeStateANDROID {
    XR_EYE_STATE_INVALID_ANDROID = 0,
    XR_EYE_STATE_GAZING_ANDROID = 1,
    XR_EYE_STATE_SHUT_ANDROID = 2,
    XR_EYE_STATE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrEyeStateANDROID;

Wartości wyliczeniowe mają następujące znaczenia:

Opis typu wyliczeniowego

XR_EYE_STATE_INVALID_ANDROID

Wskazuje, że oko jest w stanie błędu lub nie jest obecne.

XR_EYE_STATE_GAZING_ANDROID

Wskazuje, że wzrok jest obecnie skierowany w danym kierunku.

XR_EYE_STATE_SHUT_ANDROID

Wskazuje, że oko jest obecnie zamknięte z powodu mrugnięcia.

Wyliczenie XrEyeIndexANDROID określa indeks lewego lub prawego oka.

typedef enum XrEyeIndexANDROID {
    XR_EYE_INDEX_LEFT_ANDROID = 0,
    XR_EYE_INDEX_RIGHT_ANDROID = 1,
    XR_EYE_INDEX_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrEyeIndexANDROID;

Wartości wyliczeniowe mają następujące znaczenia:

Opis typu wyliczeniowego

XR_EYE_INDEX_LEFT_ANDROID

Lewe oko.

XR_EYE_INDEX_RIGHT_ANDROID

Prawe oko.

Wyliczenie XrEyeTrackingModeANDROID określa różne stany śledzonych oczu.

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,
    XR_EYE_TRACKING_MODE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrEyeTrackingModeANDROID;

Wartości wyliczeniowe mają następujące znaczenia:

Opis typu wyliczeniowego

XR_EYE_TRACKING_MODE_NOT_TRACKING_ANDROID

Wskazuje, że śledzenie wzroku jest obecnie nieaktywne.

XR_EYE_TRACKING_MODE_RIGHT_ANDROID

Oznacza, że śledzone jest tylko prawe oko.

XR_EYE_TRACKING_MODE_LEFT_ANDROID

Oznacza, że śledzone jest tylko lewe oko.

XR_EYE_TRACKING_MODE_BOTH_ANDROID

Oznacza, że śledzone są oba oczy.

Przykładowy kod śledzenia wzroku

Poniższy przykładowy kod pokazuje, jak uzyskać informacje o oczach w odniesieniu do przestrzeni widoku.

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));

Nowe typy obiektów

Nowe polecenia

Nowe struktury

Nowe wartości w polu enum

Nowe stałe wyliczeniowe

  • XR_ANDROID_EYE_TRACKING_EXTENSION_NAME
  • XR_ANDROID_eye_tracking_SPEC_VERSION
  • XR_EYE_MAX_ANDROID

  • Rozszerzanie XrObjectType :

    • XR_OBJECT_TYPE_EYE_TRACKER_ANDROID

  • Rozszerzanie XrStructureType :

    • XR_TYPE_EYES_ANDROID
    • XR_TYPE_EYES_GET_INFO_ANDROID
    • XR_TYPE_EYE_TRACKER_CREATE_INFO_ANDROID
    • XR_TYPE_SYSTEM_EYE_TRACKING_PROPERTIES_ANDROID

Problemy

Historia zmian

  • Wersja 1, 17 stycznia 2025 r. (Kenny Vercaemer)

    • Wstępny opis rozszerzenia