XR_ANDROID_eye_tracking

Name String

XR_ANDROID_eye_tracking

Erweiterungstyp

Instanzerweiterung

Registrierte Durchwahlnummer

457

Revision

1

Ratifikationsstatus

Nicht ratifiziert

Abhängigkeiten von Erweiterungen und Versionen

OpenXR 1.0

Datum der letzten Änderung

2025-01-17

IP-Status

Es sind keine Ansprüche wegen geistigen Eigentums bekannt.

Mitwirkende

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

Übersicht

Mit dieser Erweiterung können Anwendungen die Position und Ausrichtung der Augen des Nutzers sowie den Status der Blickrichtungserkennung abrufen.

Eye-Tracking-Daten werden in zwei Modi bereitgestellt: grob und fein. Beim groben Tracking wird eine grobe Schätzung der Augen des Nutzers vorgenommen, während beim feinen Tracking eine genauere Schätzung erfolgt. Die grobe Nachverfolgung ist für Anwendungen gedacht, die eine einfache avatarähnliche Darstellung bieten möchten, während die genaue Nachverfolgung für präzisere Anwendungen vorgesehen ist.

Für die Interaktion XR_EXT_eye_gaze_interaction sollte verwendet werden.

Berechtigungen

Android-Anwendungen müssen die Berechtigung „android.permission.EYE_TRACKING_COARSE“ oder „android.permission.EYE_TRACKING_FINE“ in ihrem Manifest enthalten. Diese Berechtigungen gelten als gefährliche Berechtigungen. Die App muss die Berechtigung zur Laufzeit anfordern, um diese Funktionen zu verwenden:

(Schutzebene: gefährlich)

Systemfunktionen prüfen

Die Struktur XrSystemEyeTrackingPropertiesANDROID ist so definiert:

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

Mitgliederbeschreibungen

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind in OpenXR Core oder dieser Erweiterung nicht definiert.
  • supportsEyeTracking ist ein XrBool32, das angibt, ob das aktuelle System die Augensteuerung unterstützt.

Eine Anwendung kann prüfen, ob das System Eye-Tracking unterstützt, indem sie die XrSystemProperties beim Aufrufen von xrGetSystemProperties mit der Struktur XrSystemEyeTrackingPropertiesANDROID erweitert .

Wenn und nur wenn eine Laufzeit XR_FALSE für supportsEyeTracking zurückgibt , muss die Laufzeit XR_ERROR_FEATURE_UNSUPPORTED von xrCreateEyeTrackerANDROID zurückgeben .

Gültige Nutzung (implizit)

Eye-Tracker-Handle erstellen

XR_DEFINE_HANDLE(XrEyeTrackerANDROID)

Das Handle XrEyeTrackerANDROID stellt einen Eye-Tracker zum Verfolgen der Augen dar und bildet genau ab, wohin der Nutzer blickt.

Eye-Tracking-Daten sind sensible personenbezogene Daten und eng mit der Privatsphäre und Integrität von Personen verknüpft. Es wird dringend empfohlen, dass Anwendungen, die Eye-Tracking-Daten speichern oder übertragen, den Nutzer immer um eine aktive und spezifische Zustimmung bitten.

Die Anwendung verwendet diesen Handle, um mit anderen Funktionen in dieser Erweiterung auf Eye-Tracking-Daten zuzugreifen.

Eye-Tracking bietet eine Darstellung der Augenposition und des Augenstatus in der Szene.

Die Funktion xrCreateEyeTrackerANDROID ist so definiert:

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

Parameterbeschreibungen

Eine Anwendung erstellt mit der Funktion xrCreateEyeTrackerANDROID ein XrEyeTrackerANDROID-Handle.

Wenn das System kein Eye-Tracking unterstützt, muss die Laufzeit XR_ERROR_FEATURE_UNSUPPORTED von xrCreateEyeTrackerANDROID zurückgeben .

Gültige Nutzung (implizit)

Rückgabecodes

Erfolg

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Fehler

  • 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

Die Struktur XrEyeTrackerCreateInfoANDROID ist so definiert:

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

Mitgliederbeschreibungen

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind in OpenXR Core oder dieser Erweiterung nicht definiert.

Die Struktur XrEyeTrackerCreateInfoANDROID beschreibt die Informationen zum Erstellen eines XrEyeTrackerANDROID-Handles.

Gültige Nutzung (implizit)

Die Funktion xrDestroyEyeTrackerANDROID ist so definiert:

XrResult xrDestroyEyeTrackerANDROID(
    XrEyeTrackerANDROID                         eyeTracker);

Parameterbeschreibungen

Die Funktion xrDestroyEyeTrackerANDROID gibt das eyeTracker und die zugrunde liegenden Ressourcen frei, wenn die Eye-Tracking-Funktionen abgeschlossen sind.

Gültige Nutzung (implizit)

Threadsicherheit

  • Der Zugriff auf eyeTracker und alle untergeordneten Handles muss extern synchronisiert werden.

Rückgabecodes

Erfolg

  • XR_SUCCESS

Fehler

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

Informationen zu den Augen abrufen

Die Funktion xrGetCoarseTrackingEyesInfoANDROID ist so definiert:

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

Parameterbeschreibungen

Die Funktion xrGetCoarseTrackingEyesInfoANDROID ruft die Informationen zu Augenstatus und Posen auf eine Weise ab, die die Privatsphäre der Nutzer schützt.

Die Laufzeit muss XR_ERROR_PERMISSION_INSUFFICIENT zurückgeben, wenn die Anwendung nicht die Berechtigung „android.permission.EYE_TRACKING_COARSE“ hat.

Die Augenpositionen werden in XrEyesGetInfoANDROID :: baseSpace bei XrEyesGetInfoANDROID :: time ausgedrückt .

Sowohl die Position als auch die Richtung der Augenposition werden zu jedem Zeitpunkt entweder erfasst oder nicht. Das bedeutet, dass die Laufzeit sowohl XR_SPACE_LOCATION_POSITION_TRACKED_BIT als auch XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT für die bereitgestellte XrEyesANDROID :: eyes festlegen oder löschen muss und XrEyesANDROID :: mode festlegen muss, um die Tracking-Status anzugeben.XR_SPACE_LOCATION_POSITION_TRACKED_BITXR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT

Gültige Nutzung (implizit)

Rückgabecodes

Erfolg

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Fehler

  • 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

Die Funktion xrGetFineTrackingEyesInfoANDROID ist so definiert:

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

Parameterbeschreibungen

Die Funktion xrGetFineTrackingEyesInfoANDROID ruft Informationen zu Augenstatus und Posen mit höherer Genauigkeit ab als xrGetCoarseTrackingEyesInfoANDROID .

Die Laufzeit muss XR_ERROR_PERMISSION_INSUFFICIENT zurückgeben, wenn die Anwendung nicht die Berechtigung „android.permission.EYE_TRACKING_FINE“ hat.

Die Informationen zu den Augen werden aufgelöst und sind relativ zum Basisraum zum Zeitpunkt des Aufrufs von xrGetFineTrackingEyesInfoANDROID mit XrEyesGetInfoANDROID :: time und XrEyesGetInfoANDROID :: baseSpace . Die Laufzeit muss den durch XrEyesGetInfoANDROID :: baseSpace definierten Speicherort zum Zeitpunkt des Aufrufs auflösen.

Sowohl die Position als auch die Richtung der Augenposition werden zu jedem Zeitpunkt entweder erfasst oder nicht. Das bedeutet, dass die Laufzeit sowohl XR_SPACE_LOCATION_POSITION_TRACKED_BIT als auch XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT für die bereitgestellte XrEyesANDROID :: eyes festlegen oder löschen muss und XrEyesANDROID :: mode festlegen muss, um die Tracking-Status anzugeben.XR_SPACE_LOCATION_POSITION_TRACKED_BITXR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT

Gültige Nutzung (implizit)

Rückgabecodes

Erfolg

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Fehler

  • 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

Die Struktur XrEyesGetInfoANDROID enthält die Informationen, die zum Abrufen von Augenpositionen und ‑status erforderlich sind.

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

Mitgliederbeschreibungen

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind in OpenXR Core oder dieser Erweiterung nicht definiert.
  • time ist die XrTime, bei der die Koordinaten relativ zum baseSpace ausgewertet werden sollen .
  • baseSpace ist der XrSpace, auf den sich die Augenpositionen bei time beziehen .

Gültige Nutzung (implizit)

Die Struktur XrEyesANDROID enthält Informationen zu den erfassten Augen.

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

Mitgliederbeschreibungen

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind in OpenXR Core oder dieser Erweiterung nicht definiert.
  • eyes ist ein Array von XrEyeANDROID mit der Größe XR_EYE_MAX_ANDROID für das linke und rechte Auge, das durch XrEyeIndexANDROID indexiert wird .
  • mode ist der XrEyeTrackingModeANDROID, der angibt, welche Augen derzeit verfolgt werden.

Gültige Nutzung (implizit)

Die Struktur XrEyeANDROID beschreibt den Zustand, die Position und die Ausrichtung eines Auges.

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

Mitgliederbeschreibungen

  • eyeState ist der XrEyeStateANDROID eines Auges.
  • eyePose ist ein XrPosef, das die Position und Ausrichtung der Pupille eines Auges im Referenzrahmen des entsprechenden XrEyesGetInfoANDROID :: baseSpace definiert . Eine Identitätsausrichtung stellt hier eine Koordinatenachse mit +Z in Richtung der Augen des Nutzers, +X nach rechts und +Y nach oben dar.

Gültige Nutzung (implizit)

  •  Die XR_ANDROID_eye_tracking-Erweiterung muss aktiviert werden, bevor XrEyeANDROID verwendet werden kann.
  • eyeState muss ein gültiger XrEyeStateANDROID-Wert sein

Die Enumeration XrEyeStateANDROID gibt die verschiedenen Status der erfassten Augen an.

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;

Die Enums haben die folgenden Bedeutungen:

Enum-Beschreibung

XR_EYE_STATE_INVALID_ANDROID

Gibt an, dass sich das Auge in einem Fehlerstatus befindet oder nicht vorhanden ist.

XR_EYE_STATE_GAZING_ANDROID

Gibt an, dass das Auge gerade fixiert.

XR_EYE_STATE_SHUT_ANDROID

Gibt an, dass das Auge aufgrund eines Zwinkerns oder Blinzelns derzeit geschlossen ist.

Die Enumeration XrEyeIndexANDROID gibt den Index des linken oder rechten Auges an.

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

Die Enums haben die folgenden Bedeutungen:

Enum-Beschreibung

XR_EYE_INDEX_LEFT_ANDROID

Linkes Auge

XR_EYE_INDEX_RIGHT_ANDROID

Rechtes Auge

Die Enumeration XrEyeTrackingModeANDROID gibt die verschiedenen Status der erfassten Augen an.

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;

Die Enums haben die folgenden Bedeutungen:

Enum-Beschreibung

XR_EYE_TRACKING_MODE_NOT_TRACKING_ANDROID

Gibt an, dass die Augensteuerung derzeit nicht aktiv ist.

XR_EYE_TRACKING_MODE_RIGHT_ANDROID

Gibt an, dass nur das rechte Auge erfasst wird.

XR_EYE_TRACKING_MODE_LEFT_ANDROID

Gibt an, dass nur das linke Auge erkannt wird.

XR_EYE_TRACKING_MODE_BOTH_ANDROID

Gibt an, dass sowohl das linke als auch das rechte Auge erfasst werden.

Beispielcode für Eye-Tracking

Im folgenden Beispielcode wird gezeigt, wie Sie Informationen zu den Augen relativ zu einem Ansichtsbereich abrufen.

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

Neue Objekttypen

Neue Befehle

Neue Strukturen

Neue Enums

Neue Enum-Konstanten

  • XR_ANDROID_EYE_TRACKING_EXTENSION_NAME
  • XR_ANDROID_eye_tracking_SPEC_VERSION
  • XR_EYE_MAX_ANDROID

  • XrObjectType erweitern :

    • XR_OBJECT_TYPE_EYE_TRACKER_ANDROID

  • Erweitern von 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

Probleme

Versionsverlauf

  • Version 1, 17.01.2025 (Kenny Vercaemer)

    • Erste Beschreibung der Erweiterung