XR_ANDROID_eye_tracking

Name String

XR_ANDROID_eye_tracking

Erweiterungstyp

Instanzerweiterung

Registrierte Durchwahl

457

Revision

1

Ratification Status

Nicht ratifiziert

Erweiterungs- und Versionsabhängigkeiten

OpenXR 1.0

Datum der letzten Änderung

2025-01-17

IP-Status

Keine bekannten Ansprüche auf geistiges Eigentum.

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 des Eye-Trackings abrufen.

Eye-Tracking-Daten werden in zwei Modi bereitgestellt: grob und fein. Das grobe Tracking liefert eine grobe Schätzung der Augen des Nutzers, während das feine Tracking eine genauere Schätzung liefert. Das grobe Tracking ist für Anwendungen gedacht, die eine einfache avatarähnliche Darstellung bieten möchten, während das feine Tracking für präzisere Anwendungen gedacht ist.

Für die Interaktion sollte XR_EXT_eye_gaze_interaction verwendet werden.

Berechtigungen

Android-Apps 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 Anwendung muss die Berechtigung zur Laufzeit anfordern, um diese Funktionen zu verwenden:

(Schutzebene: gefährlich)

Systemkapazität 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 weder in OpenXR noch in dieser Erweiterung definiert.
  • supportsEyeTracking ist ein XrBool32, das angibt, ob das aktuelle System Eye-Tracking unterstützt.

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

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

Gültige Verwendung (implizit)

Eye-Tracking-Handle erstellen

XR_DEFINE_HANDLE(XrEyeTrackerANDROID)

Das XrEyeTrackerANDROID-Handle stellt einen Eye-Tracker dar, der die Augenbewegungen verfolgt und genau erfasst, wohin der Nutzer blickt.

Eye-Tracking-Daten sind sensible personenbezogene Daten und eng mit dem Datenschutz und der Integrität von Personen verbunden. 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 dieses Handle, um über andere Funktionen in dieser Erweiterung auf Eye-Tracking-Daten zuzugreifen.

Das Eye-Tracking liefert die Augenposition und den Status 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 Verwendung (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 weder in OpenXR noch in dieser Erweiterung definiert.

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

Gültige Verwendung (implizit)

Die Funktion xrDestroyEyeTrackerANDROID ist so definiert:

XrResult xrDestroyEyeTrackerANDROID(
    XrEyeTrackerANDROID                         eyeTracker);

Parameterbeschreibungen

Die Funktion xrDestroyEyeTrackerANDROID gibt den eyeTracker und die zugrunde liegenden Ressourcen frei, wenn die Eye-Tracking-Funktionen nicht mehr benötigt werden.

Gültige Verwendung (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
  • XR_ERROR_RUNTIME_FAILURE

Informationen zu Augen werden abgerufen

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 ‑positionen so ab, dass der Datenschutz der Nutzer gewahrt bleibt.

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 Augenhaltung werden jederzeit erfasst oder nicht erfasst. Das bedeutet, dass die Laufzeit sowohl XR_SPACE_LOCATION_POSITION_TRACKED_BIT als auch XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT festlegen oder sowohl XR_SPACE_LOCATION_POSITION_TRACKED_BIT als auch XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT im bereitgestellten XrEyesANDROID :: eyes löschen und XrEyesANDROID :: mode festlegen muss, um die Tracking-Status anzugeben.

Gültige Verwendung (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 ‑positionen 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 Augeninformationen werden aufgelöst und sind relativ zum Basisraum zum Zeitpunkt des Aufrufs von xrGetFineTrackingEyesInfoANDROID mit XrEyesGetInfoANDROID :: time , XrEyesGetInfoANDROID :: baseSpace . Die Laufzeit muss die Position, die durch XrEyesGetInfoANDROID :: baseSpace definiert ist, zum Zeitpunkt des Aufrufs auflösen.

Sowohl die Position als auch die Richtung der Augenhaltung werden jederzeit erfasst oder nicht erfasst. Das bedeutet, dass die Laufzeit sowohl XR_SPACE_LOCATION_POSITION_TRACKED_BIT als auch XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT festlegen oder sowohl XR_SPACE_LOCATION_POSITION_TRACKED_BIT als auch XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT im bereitgestellten XrEyesANDROID :: eyes löschen und XrEyesANDROID :: mode festlegen muss, um die Tracking-Status anzugeben.

Gültige Verwendung (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 ‑zuständen 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 weder in OpenXR noch in dieser Erweiterung definiert.
  • time ist der XrTime, an dem die Koordinaten relativ zum baseSpace ausgewertet werden sollen.
  • baseSpace ist der XrSpace, in dem die Augenpositionen zurückgegeben werden sollen.

Gültige Verwendung (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 weder in OpenXR noch in dieser Erweiterung definiert.
  • eyes ist ein Array von XrEyeANDROID der Größe XR_EYE_MAX_ANDROID für das linke und rechte Auge, wie durch XrEyeIndexANDROID indexiert.
  • mode ist der XrEyeTrackingModeANDROID, der angibt, welche Augen gerade getrackt werden.

Gültige Verwendung (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 dar, wobei +Z in die Augen des Nutzers, +X nach rechts und +Y nach oben zeigt.

Gültige Verwendung (implizit)

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

Die Aufzählung XrEyeStateANDROID gibt den 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 blickt.

XR_EYE_STATE_SHUT_ANDROID

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

Die Aufzählung 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 Aufzählung XrEyeTrackingModeANDROID gibt die verschiedenen Zustände der getrackten 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 verfolgt wird.

XR_EYE_TRACKING_MODE_LEFT_ANDROID

Gibt an, dass nur das linke Auge verfolgt wird.

XR_EYE_TRACKING_MODE_BOTH_ANDROID

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

#define XR_EYE_MAX_ANDROID                2

XR_EYE_MAX_ANDROID ist die maximale Anzahl von Augen, für die XrEyeANDROID-Daten gemeldet 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 Gebäude

Neue Enums

Neue Enum-Konstanten

  • XR_ANDROID_EYE_TRACKING_EXTENSION_NAME
  • XR_ANDROID_eye_tracking_SPEC_VERSION
  • XR_EYE_MAX_ANDROID

  • Erweiterung von XrObjectType :

    • XR_OBJECT_TYPE_EYE_TRACKER_ANDROID

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

    • Anfängliche Beschreibung der Erweiterung