Rozszerzenie OpenXR XR_ANDROID_eye_tracking

Ciąg znaków z nazwą

XR_ANDROID_eye_tracking

Typ rozszerzenia

Rozszerzenie instancji

Zarejestrowany numer wewnętrzny

457

Wersja

1

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 precyzyjne – dokładniejsze oszacowanie. Śledzenie zgrubne jest przeznaczone dla aplikacji, które chcą zapewnić podstawową reprezentację w postaci awatara, a śledzenie dokładne – dla aplikacji wymagających większej precyzji.

W przypadku interakcji należy używać XR_EXT_eye_gaze_interaction .

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 tego obiektu.
  • 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, które wskazuje, czy bieżący system obsługuje śledzenie wzroku.

Aplikacja może sprawdzić, czy system obsługuje śledzenie wzroku, przez połączenie struktury XrSystemEyeTrackingPropertiesANDROID ze strukturą XrSystemProperties podczas wywoływania funkcji xrGetSystemProperties. Jeśli usługa supportsEyeTracking zwróci wartość XR_FALSE, aplikacja otrzyma wartość XR_ERROR_FEATURE_UNSUPPORTED z usługi 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 śledzi oczy i dokładnie określa, na co patrzy użytkownik.

Dane śledzenia wzroku mogą być wrażliwymi danymi osobowymi i 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.

Ten uchwyt może być używany do uzyskiwania dostępu 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 jako: 

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

Opisy parametrów

Aplikacja może utworzyć uchwyt XrEyeTrackerANDROID za pomocą funkcji xrCreateEyeTrackerANDROID.

Jeśli system nie obsługuje śledzenia wzroku, funkcja xrCreateEyeTrackerANDROID zwróci wartość XR_ERROR_FEATURE_UNSUPPORTED.

Prawidłowe użycie (domyślne)

Kody zwrotne

Sukces

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Błąd

  • 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

Struktura XrEyeTrackerCreateInfoANDROID jest zdefiniowana w ten sposób: 

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

Opisy członków

  • type jest XrStructureType tego obiektu.
  • 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 opisuje 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 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 oczu i ich położeniu w sposób, który chroni prywatność użytkownika.

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

Informacje o oczach są określane względem przestrzeni bazowej w momencie wywołania funkcji xrGetCoarseTrackingEyesInfoANDROID za pomocą funkcji XrEyesGetInfoANDROID::time, XrEyesGetInfoANDROID::baseSpace.

W każdym momencie śledzona lub nieśledzona jest zarówno pozycja, jak i kierunek ustawienia oczu. Oznacza to, że aplikacje mogą oczekiwać, że w przypadku podanego parametru XrEyesANDROID::eyes ustawienia XR_SPACE_LOCATION_POSITION_TRACKED_BIT i XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT będą ustawione lub wyczyszczone, a parametr XrEyesANDROID::mode będzie wskazywać 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_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

Funkcja xrGetFineTrackingEyesInfoANDROID jest zdefiniowana w ten sposób: 

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

Opisy parametrów

Środowisko wykonawcze musi zwrócić wartość XR_ERROR_PERMISSION_INSUFFICIENT, jeśli aplikacja nie ma uprawnienia 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, XrEyesGetInfoANDROID::baseSpace.

W każdym momencie śledzona lub nieśledzona jest zarówno pozycja, jak i kierunek ustawienia oczu. Oznacza to, że aplikacje mogą oczekiwać, że w przypadku podanego parametru XrEyesANDROID::eyes ustawienia XR_SPACE_LOCATION_POSITION_TRACKED_BIT i XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT będą ustawione lub wyczyszczone, a parametr XrEyesANDROID::mode będzie wskazywać 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_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

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

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

Opisy członków

  • type to XrStructureType tego obiektu.
  • 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 pozycja oka będzie względna w stosunku do tego XrSpace o godzinie 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 jest XrStructureType tego obiektu.
  • 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 dla lewego i prawego oka indeksowana przez XrEyeIndexANDROID.
  • mode to XrEyeTrackingModeANDROID, który wskazuje, czy oczy śledzą ruch i które z nich.

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.
  • pose to XrPosef określający położenie i orientację początku układu współrzędnych oka w ramach odniesienia odpowiedniego XrEyesGetInfoANDROID::baseSpace. Orientacja tożsamości 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)

  • Przed użyciem XrEyeANDROID musisz włączyć rozszerzenie XR_ANDROID_eye_tracking.
  • 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
} XrEyeStateANDROID;

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

Enum

Opis

XR_EYE_STATE_INVALID_ANDROID

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

XR_EYE_STATE_GAZING_ANDROID

Wskazuje, że wzrok jest skierowany w określonym kierunku.

XR_EYE_STATE_SHUT_ANDROID

Wskazuje, że oko jest 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
} XrEyeIndexANDROID;

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

Enum

Opis

XR_EYE_INDEX_LEFT_ANDROID

Lewe oko.

XR_EYE_INDEX_RIGHT_ANDROID

Prawe oko.

Wyliczenie XrEyeTrackingModeANDROID określa różne tryby śledzenia 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
} XrEyeTrackingModeANDROID;

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

Enum

Opis

XR_EYE_TRACKING_MODE_NOT_TRACKING_ANDROID

Wskazuje, że śledzenie wzroku nie jest aktywne.

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

Informuje, że śledzone są oba oczy.

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 stałe wyliczeniowe

  • XR_EYE_MAX_ANDROID

Wyliczenie XrObjectType zostało rozszerzone o:

  • XR_OBJECT_TYPE_EYE_TRACKER_ANDROID

Wyliczenie XrStructureType zostało rozszerzone o:

  • XR_TYPE_EYES_ANDROID
  • XR_TYPE_EYE_TRACKER_CREATE_INFO_ANDROID
  • XR_TYPE_EYES_GET_INFO_ANDROID
  • XR_TYPE_SYSTEM_EYE_TRACKING_PROPERTIES_ANDROID

Nowe wartości w polu enum

Nowe struktury

Nowe funkcje

Problemy

Historia wersji

  • Wersja 1, 17 stycznia 2025 r. (Kenny Vercaemer)
    • Wstępny opis rozszerzenia

OpenXR™ i logo OpenXR są znakami towarowymi należącymi do The Khronos Group Inc. i są zarejestrowane jako znaki towarowe w Chinach, Unii Europejskiej, Japonii i Wielkiej Brytanii.