XR_ANDROID_eye_tracking

Name String

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

Przegląd

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 – bardziej precyzyjne. Śledzenie zgrubne jest przeznaczone dla aplikacji, które chcą zapewnić podstawową reprezentację podobną do awatara, natomiast śledzenie precyzyjne jest przeznaczone dla bardziej precyzyjnych aplikacji.

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. Te uprawnienia są uznawane za niebezpieczne. Aby korzystać z tych funkcji, aplikacja musi prosić o uprawnienia w czasie działania:

(poziom ochrony: niebezpieczne)

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 podstawowym interfejsie 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 jest w stanie śledzić wzrok, rozszerzając XrSystemProperties o strukturę XrSystemEyeTrackingPropertiesANDROID podczas wywoływania xrGetSystemProperties .

Jeśli i tylko wtedy, gdy środowisko wykonawcze zwraca XR_FALSE dla supportsEyeTracking, środowisko wykonawcze musi zwracać XR_ERROR_FEATURE_UNSUPPORTED z xrCreateEyeTrackerANDROID .

Prawidłowe użycie (pośrednie)

Tworzenie uchwytu śledzenia wzroku

XR_DEFINE_HANDLE(XrEyeTrackerANDROID)

Uchwyt XrEyeTrackerANDROID reprezentuje moduł śledzenia wzroku, który śledzi oczy i dokładnie mapuje miejsce, na które patrzy użytkownik.

Dane ze śledzenia wzroku to poufne dane osobowe, które są ściśle powiązane z prywatnością i integralnością użytkownika. Zdecydowanie zalecamy, aby aplikacje, które przechowują lub przesyłają dane ze śledzenia wzroku, zawsze prosiły użytkownika o aktywne i wyraźne wyrażenie zgody na takie działanie.

Aplikacja używa tego uchwytu, aby uzyskać dostęp do danych śledzenia wzroku za pomocą innych funkcji w tym rozszerzeniu.

Ś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ć XR_ERROR_FEATURE_UNSUPPORTED z xrCreateEyeTrackerANDROID .

Prawidłowe użycie (pośrednie)

Kody zwrotu

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 podstawowym interfejsie OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.

Struktura XrEyeTrackerCreateInfoANDROID opisuje informacje potrzebne do utworzenia uchwytu XrEyeTrackerANDROID.

Prawidłowe użycie (pośrednie)

Funkcja xrDestroyEyeTrackerANDROID jest zdefiniowana w ten sposób:

XrResult xrDestroyEyeTrackerANDROID(
    XrEyeTrackerANDROID                         eyeTracker);

Opisy parametrów

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

Prawidłowe użycie (pośrednie)

Bezpieczeństwo wątków

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

Kody zwrotu

Sukces

  • XR_SUCCESS

Błąd

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Pobieram informacje 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 stanach i pozycjach oczu w sposób, który chroni prywatność użytkownika.

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

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

W każdym momencie pozycja i kierunek ułożenia oczu są śledzone lub nieśledzone. 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 podanym XrEyesANDROID :: eyes oraz ustawić XrEyesANDROID :: mode, aby wskazać stany śledzenia.

Prawidłowe użycie (pośrednie)

Kody zwrotu

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ż xrGetCoarseTrackingEyesInfoANDROID .

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

Informacje o oczach są rozwiązywane i odnoszą się do przestrzeni podstawowej w momencie wywołania funkcji xrGetFineTrackingEyesInfoANDROID za pomocą XrEyesGetInfoANDROID :: time , XrEyesGetInfoANDROID :: baseSpace . Środowisko wykonawcze musi rozpoznać lokalizację zdefiniowaną przez XrEyesGetInfoANDROID :: baseSpace w momencie wywołania.

W każdym momencie pozycja i kierunek ułożenia oczu są śledzone lub nieśledzone. 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 podanym XrEyesANDROID :: eyes oraz ustawić XrEyesANDROID :: mode, aby wskazać stany śledzenia.

Prawidłowe użycie (pośrednie)

Kody zwrotu

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 pobierania 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 podstawowym interfejsie 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, w której mają być zwracane pozycje oczu.

Prawidłowe użycie (pośrednie)

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 podstawowym interfejsie 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, który wskazuje, które oko jest obecnie śledzone.

Prawidłowe użycie (pośrednie)

Struktura XrEyeANDROID opisuje stan, pozycję i orientację oka.

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

Opisy członków

  • eyeState to XrEyeStateANDROID oka.
  • eyePose to XrPosef, który określa pozycję i orientację źrenicy oka w ramce odniesienia odpowiedniego elementu XrEyesGetInfoANDROID :: baseSpace . Orientacja tożsamości reprezentuje osie współrzędnych, gdzie +Z to kierunek w stronę oczu użytkownika, +X to kierunek w prawo, a +Y to kierunek w górę.

Prawidłowe użycie (pośrednie)

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

Wyliczenie XrEyeStateANDROID identyfikuje 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;

Typy wyliczeniowe mają następujące znaczenie:

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 oko jest obecnie skupione na danym punkcie.

XR_EYE_STATE_SHUT_ANDROID

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

Wyliczenie XrEyeIndexANDROID identyfikuje 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;

Typy wyliczeniowe mają następujące znaczenie:

Opis typu wyliczeniowego

XR_EYE_INDEX_LEFT_ANDROID

Lewe oko.

XR_EYE_INDEX_RIGHT_ANDROID

Prawe oko.

Wyliczenie XrEyeTrackingModeANDROID identyfikuje 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;

Typy wyliczeniowe mają następujące znaczenie:

Opis typu wyliczeniowego

XR_EYE_TRACKING_MODE_NOT_TRACKING_ANDROID

Wskazuje, że śledzenie wzroku nie jest obecnie aktywne.

XR_EYE_TRACKING_MODE_RIGHT_ANDROID

Wskazuje, że śledzone jest tylko prawe oko.

XR_EYE_TRACKING_MODE_LEFT_ANDROID

Wskazuje, że śledzone jest tylko lewe oko.

XR_EYE_TRACKING_MODE_BOTH_ANDROID

Wskazuje, że śledzone są zarówno lewe, jak i prawe oko.

#define XR_EYE_MAX_ANDROID                2

XR_EYE_MAX_ANDROID to maksymalna liczba oczu, dla których są raportowane dane XrEyeANDROID.

Przykładowy kod śledzenia wzroku

Poniższy przykładowy kod pokazuje, jak uzyskać informacje o oczach względem 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 domy

Nowe wartości w polu enum

Nowe stałe typu wyliczeniowego

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

    • Początkowy opis rozszerzenia