OpenXR-Erweiterung „XR_ANDROID_eye_tracking“

Name String

XR_ANDROID_eye_tracking

Erweiterungstyp

Instanzerweiterung

Registrierte Durchwahlnummer

457

Revision

1

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 Eye-Tracking-Status abrufen.

Eye-Tracking-Daten werden in zwei Modi bereitgestellt: grob und fein. Bei der groben Verfolgung wird eine grobe Schätzung der Augen des Nutzers vorgenommen, während bei der genauen Verfolgung 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 gedacht ist.

Für die Interaktion XR_EXT_eye_gaze_interaction sollte verwendet werden.

Systemfunktionen prüfen

Die Struktur XrSystemEyeTrackingPropertiesANDROID ist so definiert:

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

Mitgliederbeschreibungen

  • type ist die XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Im OpenXR-Kern oder in dieser Erweiterung sind keine solchen Strukturen definiert.
  • supportsEyeTracking ist ein XrBool32, der angibt, ob das aktuelle System Eye-Tracking unterstützt.

Eine Anwendung kann prüfen, ob das System Eye-Tracking unterstützt, indem sie beim Aufrufen von xrGetSystemProperties eine XrSystemEyeTrackingPropertiesANDROID-Struktur an die XrSystemProperties anhängt. Wenn supportsEyeTracking den Wert XR_FALSE zurückgibt, erhält eine Anwendung XR_ERROR_FEATURE_UNSUPPORTED von xrCreateEyeTrackerANDROID.

Gültige Nutzung (implizit)

Eye-Tracker-Handle erstellen

XR_DEFINE_HANDLE(XrEyeTrackerANDROID)

Der XrEyeTrackerANDROID-Handle steht für einen Eye-Tracker, mit dem die Augen verfolgt und genau abgebildet wird, worauf der Nutzer blickt.

Eye-Tracking-Daten können sensible personenbezogene Daten sein und sind eng mit dem Schutz der Privatsphäre und der Integrität verbunden. Es wird dringend empfohlen, dass Anwendungen, die Eye-Tracking-Daten speichern oder übertragen, den Nutzer immer um eine aktive und spezifische Zustimmung bitten.

Mit diesem Handle kann über andere Funktionen in dieser Erweiterung auf Eye-Tracking-Daten zugegriffen werden.

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 kann mit der Funktion xrCreateEyeTrackerANDROID ein XrEyeTrackerANDROID-Handle erstellen.

Wenn das System kein Eye-Tracking unterstützt, wird XR_ERROR_FEATURE_UNSUPPORTED von xrCreateEyeTrackerANDROID zurückgegeben.

Gültige Nutzung (implizit)

Rückgabecodes

Erfolg

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Fehler

  • 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

Die Struktur XrEyeTrackerCreateInfoANDROID ist so definiert: 

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

Mitgliederbeschreibungen

  • type ist die XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Im OpenXR-Kern oder in dieser Erweiterung sind keine solchen Strukturen definiert.

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

Gültige Nutzung (implizit)

Die Funktion xrDestroyEyeTrackerANDROID ist so definiert: 

XrResult xrDestroyEyeTrackerANDROID(
    XrEyeTrackerANDROID                         eyeTracker);

Parameterbeschreibungen

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

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 Informationen zu den Augen werden aufgelöst und sind relativ zum Basisraum zum Zeitpunkt des Aufrufs von xrGetCoarseTrackingEyesInfoANDROID mit XrEyesGetInfoANDROID::time, XrEyesGetInfoANDROID::baseSpace.

Sowohl die Position als auch die Richtung der Augenposition werden jederzeit erfasst oder nicht erfasst. Das bedeutet, dass Anwendungen davon ausgehen können, dass sowohl XR_SPACE_LOCATION_POSITION_TRACKED_BIT als auch XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT für die bereitgestellte XrEyesANDROID::eyes entweder festgelegt oder gelöscht werden und dass XrEyesANDROID::mode die Tracking-Status angibt.

Gültige Nutzung (implizit)

Rückgabecodes

Erfolg

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Fehler

  • 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

Die Funktion xrGetFineTrackingEyesInfoANDROID ist so definiert: 

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

Parameterbeschreibungen

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, XrEyesGetInfoANDROID::baseSpace.

Sowohl die Position als auch die Richtung der Augenposition werden jederzeit erfasst oder nicht erfasst. Das bedeutet, dass Anwendungen davon ausgehen können, dass sowohl XR_SPACE_LOCATION_POSITION_TRACKED_BIT als auch XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT für die bereitgestellte XrEyesANDROID::eyes entweder festgelegt oder gelöscht werden und dass XrEyesANDROID::mode die Tracking-Status angibt.

Gültige Nutzung (implizit)

Rückgabecodes

Erfolg

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Fehler

  • 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

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

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

Mitgliederbeschreibungen

  • type ist die XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Im OpenXR-Kern oder in dieser Erweiterung sind keine solchen Strukturen definiert.
  • time ist die XrTime, bei der die Koordinaten relativ zum baseSpace ausgewertet werden sollen.
  • baseSpace Die Augenposition wird relativ zu diesem XrSpace bei time angegeben.

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 die XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Im OpenXR-Kern oder in dieser Erweiterung sind keine solchen Strukturen definiert.
  • eyes ist ein Array von XrEyeANDROID für das linke und rechte Auge, das durch XrEyeIndexANDROID indexiert wird.
  • mode ist die XrEyeTrackingModeANDROID, um anzugeben, ob die Augen verfolgt werden und welche.

Gültige Nutzung (implizit)

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

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

Mitgliederbeschreibungen

  • eyeState ist die XrEyeStateANDROID eines Auges.
  • pose ist ein XrPosef, der die Position und Ausrichtung des Ursprungs 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 Erweiterung XR_ANDROID_eye_tracking muss aktiviert sein, bevor Sie XrEyeANDROID verwenden.
  • eyeState muss ein gültiger XrEyeStateANDROID-Wert sein

Die Enumeration XrEyeStateANDROID gibt die verschiedenen Zustände 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
} 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 blickt.

XR_EYE_STATE_SHUT_ANDROID

Gibt an, dass das Auge aufgrund eines Zwinkerns oder Blinzelns 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
} 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 Modi 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
} XrEyeTrackingModeANDROID;

Die Enums haben die folgenden Bedeutungen:

Enum

Beschreibung

XR_EYE_TRACKING_MODE_NOT_TRACKING_ANDROID

Gibt an, dass das Eye-Tracking 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 erfasst 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 Enum-Konstanten

  • XR_EYE_MAX_ANDROID

Die Aufzählung XrObjectType wird um Folgendes erweitert:

  • XR_OBJECT_TYPE_EYE_TRACKER_ANDROID

Die Aufzählung XrStructureType wird um Folgendes erweitert:

  • XR_TYPE_EYES_ANDROID
  • XR_TYPE_EYE_TRACKER_CREATE_INFO_ANDROID
  • XR_TYPE_EYES_GET_INFO_ANDROID
  • XR_TYPE_SYSTEM_EYE_TRACKING_PROPERTIES_ANDROID

Neue Enums

Neue Strukturen

Neue Funktionen

Probleme

Versionsverlauf

  • Version 1, 17.01.2025 (Kenny Vercaemer)
    • Erste Beschreibung der Erweiterung

OpenXR™ und das OpenXR-Logo sind Marken von The Khronos Group Inc. und sind in China, der Europäischen Union, Japan und dem Vereinigten Königreich als Marke eingetragen.