Rozszerzenie OpenXR XR_ANDROID_avatar_eyes

Ciąg znaków nazwy

XR_ANDROID_avatar_eyes

Typ rozszerzenia

Rozszerzenie instancji

Zarejestrowany numer wewnętrzny

457

Weryfikacja

1

Zależności rozszerzenia i wersji

OpenXR 1.0

Data ostatniej modyfikacji

2024-09-30

Stan adresu IP

Brak znanych roszczeń dotyczących adresu IP.

Twórcy

Spencer Quin, Google

Jared Finder, Google

Levana Chen, Google

Omówienie

To rozszerzenie umożliwia aplikacjom uzyskanie pozycji i orientacji oczu użytkownika, a także stanu śledzenia wzroku.

Rozszerzenie ma na celu realistyczne odwzorowanie pozycji oczu i stanu awatara. W tym celu:

  • Umożliwia to tworzenie stanów niemonitorowanych, takich jak mruganie.
  • Umożliwia śledzenie monokularne lub binokularne.

Tego rozszerzenia nie należy używać do śledzenia ruchem oczu. W przypadku interakcji należy użyć wartości XR_EXT_eye_gaze_interaction.

Śledzenie wzroku

Śledzenie wzroku to urządzenie, które śledzi ruchy oczu i z dużą dokładnością określa, na co patrzy użytkownik. Głównym celem tego rozszerzenia jest mapowanie spojrzeń użytkowników na ich awatary w wirtualnej scenie.

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

  • Aplikacja otrzyma wartość XR_ERROR_PERMISSION_INSUFFICIENT, gdy spróbuje utworzyć aktywne urządzenie śledzące wzrok, dopóki nie uzyska ona dostępu do tego urządzenia.

Sprawdzanie możliwości systemu

Aplikacja może sprawdzić, czy system obsługuje oczy awatara, łącząc strukturę XrSystemAvatarEyesPropertiesANDROID ze strukturą XrSystemProperties podczas wywoływania funkcji xrGetSystemProperties. Jeśli supportsAvatarEyes zwraca wartość XR_FALSE, aplikacja otrzyma wartość XR_ERROR_FEATURE_UNSUPPORTED z xrCreateEyeTrackerANDROID.

typedef struct XrSystemAvatarEyesPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsAvatarEyes;
} XrSystemAvatarEyesPropertiesANDROID;

Opisy członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktury. Nie ma żadnych takich struktur zdefiniowanych w podstawowym OpenXR ani w tym rozszerzeniu.
  • supportsAvatarEyes to XrBool32, który wskazuje, czy bieżący system obsługuje oczy awatara.

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 precyzyjnie mapuje to, na co patrzy użytkownik.

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

Śledzenie oczu zapewnia informacje o pozycji i stanie oczu w scenie.

Funkcja xrCreateEyeTrackerANDROID jest zdefiniowana w ten sposób: 

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

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. Nie ma żadnych takich struktur zdefiniowanych w podstawowym OpenXR ani w tym rozszerzeniu.

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 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 xrGetEyesInfoANDROID jest zdefiniowana jako:

XrResult xrGetEyesInfoANDROID(
    XrEyeTrackerANDROID                         eyeTracker,
    const XrEyesGetInfoANDROID*                 getInfo,
    XrEyesANDROID*                              infoOutput);

Opisy parametrów

Funkcja xrGetEyesInfoANDROID pobiera informacje o stanie oczu i ich położeniu.

Informacje o oczach są rozwiązywane i odnoszą się do przestrzeni podstawowej w momencie wywołania funkcji xrGetEyesInfoANDROID 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 podanych XrEyesANDROID::eyes, a XrEyesANDROID::mode będzie wskazywać stany ś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

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. Nie ma żadnych takich struktur zdefiniowanych w podstawowym OpenXR ani w tym rozszerzeniu.
  • 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. Nie ma żadnych takich struktur zdefiniowanych w podstawowym OpenXR ani w tym rozszerzeniu.
  • eyes to tablica XrEyeANDROID dla lewego i prawego oka powiązana z XrEyeIndexANDROID.
  • mode to XrEyeTrackingModeANDROID, który wskazuje, czy oczy są śledzone 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 pozycję 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 stronę użytkownika, dodatnią osią X skierowaną w prawo i dodatnią osią Y skierowaną w górę.

Prawidłowe użycie (domyślne)

  • Przed użyciem XrEyeANDROID musi być włączone rozszerzenie XR_ANDROID_avatar_eyes.
  • eyeState musi być prawidłową wartością 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.

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

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_AVATAR_EYES_PROPERTIES_ANDROID

Nowe wartości w polu enum

Nowe struktury

Nowe funkcje

Problemy

Historia wersji

  • Wersja 1, 4 września 2024 r. (Levana Chen)
    • Początkowy opis rozszerzenia