OpenXR-Erweiterung „XR_ANDROID_eye_tracking“

Namensstring

XR_ANDROID_eye_tracking

Erweiterungstyp

Instanzerweiterung

Registrierte Erweiterungsnummer

457

Revision

1

Erweiterungs- und Versionsabhängigkeiten

OpenXR 1.0

Datum der letzten Änderung

2025-01-17

IP-Status

Es sind keine Ansprüche aufgrund von Urheberrechten 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 Blickverfolgung abrufen.

Es gibt zwei Modi für die Erfassung von Eye-Tracking-Daten: grob und fein. Bei der groben Verfolgung wird eine grobe Schätzung der Augen des Nutzers ermittelt, während bei der detaillierten Verfolgung eine genauere Schätzung erfolgt. Grobes Tracking eignet sich für Anwendungen, die eine grundlegende, avatarähnliche Darstellung bieten möchten, während sich das genaue Tracking für präzisere Anwendungen eignet.

Für die Interaktion sollte XR_EXT_eye_gaze_interaction verwendet werden.

Systemkapazität prüfen

Die Struktur XrSystemEyeTrackingPropertiesANDROID ist so definiert:

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

Beschreibungen von Mitgliedern

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

Eine Anwendung kann prüfen, ob das System in der Lage ist, das Blickverhalten zu erfassen, indem sie beim Aufruf 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 Verwendung (implizit)

Eye-Tracker-Handle erstellen

XR_DEFINE_HANDLE(XrEyeTrackerANDROID)

Der XrEyeTrackerANDROID-Cursor stellt einen Eye-Tracker dar, der die Augenbewegungen verfolgt und genau aufzeichnet, worauf sich der Nutzer gerade konzentriert.

Eye-Tracking-Daten können sensible personenbezogene Daten sein und stehen in engem Zusammenhang mit dem Datenschutz und der Integrität von Personen. Bei Anwendungen, die Daten aus dem Blicktracking speichern oder übertragen, wird dringend empfohlen, den Nutzer immer um eine aktive und spezifische Einwilligung zu bitten.

Über diesen Handle kann mit anderen Funktionen in dieser Erweiterung auf Eye-Tracking-Daten zugegriffen werden.

Eye-Tracking liefert Informationen zur Augenposition und zum Status 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 einen XrEyeTrackerANDROID-Handle erstellen.

Wenn das System keine Augenbewegungserkennung unterstützt, wird XR_ERROR_FEATURE_UNSUPPORTED von xrCreateEyeTrackerANDROID zurückgegeben.

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

Beschreibungen von Mitgliedern

  • type ist die XrStructureType dieses Elements.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind in OpenXR oder dieser Erweiterung nicht 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 eyeTracker und die zugrunde liegenden Ressourcen frei, wenn die Tests mit dem Eye-Tracking abgeschlossen sind.

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

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 Informationen zu Augenzuständen 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 mithilfe von XrEyesGetInfoANDROID::time, XrEyesGetInfoANDROID::baseSpace aufgelöst und sind relativ zum Basisbereich zum Zeitpunkt des Aufrufs von xrGetCoarseTrackingEyesInfoANDROID.

Zu jedem Zeitpunkt werden sowohl die Position als auch die Richtung der Augenposition erfasst oder nicht erfasst. Das bedeutet, dass in Apps davon ausgegangen werden kann, dass sowohl XR_SPACE_LOCATION_POSITION_TRACKED_BIT als auch XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT für die angegebene XrEyesANDROID::eyes entweder festgelegt oder gelöscht werden und dass XrEyesANDROID::mode die Tracking-Status angibt.

Gültige Verwendung (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 xrGetFineTrackingEyesInfoANDROID-Funktion ist so definiert: {:#xrGetFineTrackingEyesInfoANDROID} C++ 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 mithilfe von XrEyesGetInfoANDROID::time, XrEyesGetInfoANDROID::baseSpace aufgelöst und sind relativ zum Basisbereich zum Zeitpunkt des Aufrufs von xrGetFineTrackingEyesInfoANDROID.

Zu jedem Zeitpunkt werden sowohl die Position als auch die Richtung der Augenposition erfasst oder nicht erfasst. Das bedeutet, dass in Apps davon ausgegangen werden kann, dass sowohl XR_SPACE_LOCATION_POSITION_TRACKED_BIT als auch XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT für die angegebene XrEyesANDROID::eyes entweder festgelegt oder gelöscht werden und dass XrEyesANDROID::mode die Tracking-Status angibt.

Gültige Verwendung (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 Struktur XrEyesGetInfoANDROID enthält die Informationen, die zum Abrufen von Augenpositionen und -zuständen erforderlich sind. 

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

Beschreibungen von Mitgliedern

  • type ist die XrStructureType dieses Elements.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind in OpenXR oder dieser Erweiterung nicht definiert.
  • time ist die XrTime, an der die Koordinaten relativ zur baseSpace ausgewertet werden sollen.
  • baseSpace Die Augenpose bezieht sich auf diese XrSpace bei time.

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;

Beschreibungen von Mitgliedern

  • type ist die XrStructureType dieses Elements.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind in OpenXR oder dieser Erweiterung nicht definiert.
  • eyes ist ein Array von XrEyeANDROID für das linke und rechte Auge, indexiert durch XrEyeIndexANDROID.
  • mode ist die XrEyeTrackingModeANDROID, die angibt, ob die Augen verfolgen und welche.

Gültige Verwendung (implizit)

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

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

Beschreibungen von Mitgliedern

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

Gültige Verwendung (implizit)

  • Die XR_ANDROID_eye_tracking-Erweiterung muss aktiviert sein, bevor Sie XrEyeANDROID verwenden können.
  • eyeState muss ein gültiger XrEyeStateANDROID-Wert sein

Die Aufzählung 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
} XrEyeStateANDROID;

Die Enumerationen haben folgende Bedeutungen:

Enum

Beschreibung

XR_EYE_STATE_INVALID_ANDROID

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

XR_EYE_STATE_GAZING_ANDROID

Gibt an, dass das Auge geradeaus schaut.

XR_EYE_STATE_SHUT_ANDROID

Gibt an, dass das Auge durch ein Winken oder Blinzeln 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
} XrEyeIndexANDROID;

Die Enumerationen haben folgende Bedeutungen:

Enum

Beschreibung

XR_EYE_INDEX_LEFT_ANDROID

Linkes Auge

XR_EYE_INDEX_RIGHT_ANDROID

Rechtes Auge

Die Aufzählung XrEyeTrackingModeANDROID gibt die verschiedenen Modi für die 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
} XrEyeTrackingModeANDROID;

Die Enumerationen haben folgende Bedeutungen:

Enum

Beschreibung

XR_EYE_TRACKING_MODE_NOT_TRACKING_ANDROID

Gibt an, dass die Funktion „Echtzeit-Blickerfassung“ 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 verfolgt wird.

XR_EYE_TRACKING_MODE_BOTH_ANDROID

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

Beispielcode für die Erfassung von Blickbewegungen

Im folgenden Beispielcode wird gezeigt, wie Sie Informationen zu den Augen relativ zu einem Blickfeld 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

  • Revision 1, 17. Januar 2025 (Kenny Vercaemer)
    • Erste Beschreibung der Erweiterung

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