Rozszerzenie OpenXR XR_ANDROID_eye_tracking

Ciąg znaków nazwy

XR_ANDROID_eye_tracking

Typ rozszerzenia

Rozszerzenie instancji

Zarejestrowany numer wewnętrzny

457

Weryfikacja

1

Zależności rozszerzenia i wersji

OpenXR 1.0

Data ostatniej modyfikacji

2025-01-17

Stan adresu IP

Brak znanych roszczeń do praw autorskich do treści.

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 uzyskanie pozycji i orientacji oczu użytkownika, a także stanu śledzenia wzroku.

Dane śledzenia wzroku są udostępniane w 2 trybach: ogólnym i dokładnym. Śledzenie o niskiej rozdzielczości zapewnia przybliżony obraz oczu użytkownika, natomiast śledzenie o wysokiej rozdzielczości zapewnia bardziej dokładny obraz. Śledzenie ogólne jest przeznaczone do aplikacji, które chcą zapewnić podstawowe odwzorowanie awatara, a śledzenie precyzyjne – do bardziej precyzyjnych zastosowań.

W przypadku interakcji należy użyć wartości 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 tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktury. W podstawowym OpenXR ani w tym rozszerzeniu nie zdefiniowano żadnych takich struktur.
  • supportsEyeTracking to XrBool32, który wskazuje, czy bieżący system obsługuje śledzenie wzroku.

Aplikacja może sprawdzić, czy system jest w stanie śledzić ruch gałek ocznych, łącząc strukturę XrSystemEyeTrackingPropertiesANDROID z strukturą XrSystemProperties podczas wywoływania funkcji xrGetSystemProperties. Jeśli funkcja supportsEyeTracking zwróci wartość XR_FALSE, aplikacja otrzyma wartość XR_ERROR_FEATURE_UNSUPPORTED z xrCreateEyeTrackerANDROID.

Prawidłowe użycie (domyślne)

Tworzenie uchwytu śledzenia ruchów gałek ocznych

XR_DEFINE_HANDLE(XrEyeTrackerANDROID)

Uchwyt XrEyeTrackerANDROID reprezentuje śledzenie wzroku, które śledzi ruchy oczu i dokładnie odwzorowuje to, na co patrzy użytkownik.

Dane śledzenia ruchem gałek ocznych mogą zawierać wrażliwe dane osobowe i są ściśle związane z prywatnością i nienaruszającymi integralności osoby. Zdecydowanie zalecamy, aby aplikacje, które przechowują lub przesyłają dane śledzenia ruchem gałek ocznych, zawsze prosiły użytkownika o aktywne i szczególne zaakceptowanie.

Za pomocą tego uchwytu można uzyskać dostęp do danych śledzenia oczu za pomocą innych funkcji w tym rozszerzeniu.

Śledzenie oczu umożliwia wyświetlanie w scenie pozycji i stanu oczu.

Funkcja xrCreateEyeTrackerANDROID jest zdefiniowana w ten sposób: 

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

Opisy parametrów

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

Jeśli system nie obsługuje śledzenia wzroku, XR_ERROR_FEATURE_UNSUPPORTED zostanie zwrócone z xrCreateEyeTrackerANDROID.

Prawidłowe użycie (domyślne)

Kody zwrotu

Gotowe

  • 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 to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktury. W podstawowym OpenXR ani w tym rozszerzeniu nie zdefiniowano żadnych takich struktur.

Struktura XrEyeTrackerCreateInfoANDROID zawiera informacje potrzebne do utworzenia identyfikatora 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 podstawowe zasoby po zakończeniu śledzenia ruchem gałek ocznych.

Prawidłowe użycie (domyślne)

Bezpieczeństwo wątków

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

Kody zwrotu

Gotowe

  • XR_SUCCESS

Błąd

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

Pobieranie 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 pozycji oczu w sposób, który chroni prywatność użytkownika.

Jeśli aplikacja nie ma uprawnień android.permission.EYE_TRACKING_COARSE, środowisko uruchomieniowe musi zwrócić wartość XR_ERROR_PERMISSION_INSUFFICIENT.

Informacje o oczach są rozwiązywane i odnoszą się do przestrzeni bazowej w momencie wywołania funkcji xrGetCoarseTrackingEyesInfoANDROID za pomocą funkcji XrEyesGetInfoANDROID::time, XrEyesGetInfoANDROID::baseSpace.

W dowolnym momencie można śledzić lub nie śledzić pozycję i kierunek spojrzenia. Oznacza to, że aplikacje mogą oczekiwać, że zarówno XR_SPACE_LOCATION_POSITION_TRACKED_BIT, jak i XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT będą ustawione lub wyczyszczone w XrEyesANDROID::eyes, a XrEyesANDROID::mode będzie wskazywać stan śledzenia.

Prawidłowe użycie (domyślne)

Kody zwrotu

Gotowe

  • 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 jako: {:#xrGetFineTrackingEyesInfoANDROID} C++ XrResult xrGetFineTrackingEyesInfoANDROID( XrEyeTrackerANDROID eyeTracker, const XrEyesGetInfoANDROID* getInfo, XrEyesANDROID* eyesOutput);

Opisy parametrów

Środowisko uruchomieniowe musi zwrócić 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 bazowej w momencie wywołania funkcji xrGetFineTrackingEyesInfoANDROID za pomocą funkcji XrEyesGetInfoANDROID::time, XrEyesGetInfoANDROID::baseSpace.

W dowolnym momencie można śledzić lub nie śledzić pozycję i kierunek spojrzenia. Oznacza to, że aplikacje mogą oczekiwać, że zarówno XR_SPACE_LOCATION_POSITION_TRACKED_BIT, jak i XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT będą ustawione lub wyczyszczone w XrEyesANDROID::eyes, a XrEyesANDROID::mode będzie wskazywać stan śledzenia.

Prawidłowe użycie (domyślne)

Kody zwrotu

Gotowe

  • 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 pobrania pozycji i stanów oczu. 

typedef struct XrEyesGetInfoANDROID {
    XrStructureType    type;
    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 struktury. W podstawowym OpenXR ani w tym rozszerzeniu nie zdefiniowano żadnych takich struktur.
  • time to XrTime, w której mają być obliczane współrzędne względem baseSpace.
  • baseSpace pozycja oczu będzie określana względem tego XrSpace w miejscu 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 struktury. W podstawowym OpenXR ani w tym rozszerzeniu nie zdefiniowano żadnych takich struktur.
  • eyes to tablica XrEyeANDROID dla lewego i prawego oka posortowana według XrEyeIndexANDROID.
  • mode to XrEyeTrackingModeANDROID, aby wskazać, czy oczy śledzą obiekt i które.

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 oka w układzie odniesienia odpowiadającego XrEyesGetInfoANDROID::baseSpace. Orientacja tożsamości reprezentuje układ współrzędnych z dodatnią osią Z skierowaną w kierunku oczu użytkownika, dodatnią osią X skierowaną w prawo i dodatnią osią Y skierowaną w górę.

Prawidłowe użycie (domyślne)

  • Zanim zaczniesz korzystać z XrEyeANDROID, musisz włączyć rozszerzenie XR_ANDROID_eye_tracking.
  • eyeState musi mieć prawidłową wartość XrEyeStateANDROID.

Wyliczenie XrEyeStateANDROID identyfikuje różne stany śledzenia oczu. 

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

Wykazy te mają następujące znaczenia:

Wyliczenie

Opis

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

XR_EYE_STATE_SHUT_ANDROID

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

Wyliczenie XrEyeIndexANDROID identyfikuje indeks lewego lub prawego oka. 

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

Wykazy te mają następujące znaczenia:

Wyliczenie

Opis

XR_EYE_INDEX_LEFT_ANDROID

Lewe oko.

XR_EYE_INDEX_RIGHT_ANDROID

Prawe oko.

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

Wykazy te mają następujące znaczenia:

Wyliczenie

Opis

XR_EYE_TRACKING_MODE_NOT_TRACKING_ANDROID

Wskazuje, że śledzenie wzroku jest nieaktywne.

XR_EYE_TRACKING_MODE_RIGHT_ANDROID

Wskazuje, że śledzenie odbywa się tylko w przypadku prawego oka.

XR_EYE_TRACKING_MODE_LEFT_ANDROID

Wskazuje, że śledzenie odbywa się tylko z użyciem lewego oka.

XR_EYE_TRACKING_MODE_BOTH_ANDROID

Wskazuje, że śledzenie odbywa się zarówno lewym, jak i prawym okiem.

Przykładowy kod do śledzenia ruchem gałek ocznych

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 stałe typu wyliczeniowego

  • 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.01.2025 (Kenny Vercaemer)
    • Wstępny opis rozszerzenia