Das Android XR SDK ist jetzt in der Entwicklervorschau verfügbar. Wir freuen uns über Ihr Feedback! Auf unserer Supportseite können Sie sich an uns wenden.

Diese Seite wurde von der Cloud Translation API übersetzt.

OpenXR-Erweiterung „XR_ANDROID_eye_tracking“

Namensstring

XR_ANDROID_eye_tracking

Erweiterungstyp

Instanzerweiterung

Registrierte Erweiterungsnummer

457

Revision

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

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 einfache, 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 dieser Struktur.
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)

Die XR_ANDROID_eye_tracking-Erweiterung muss aktiviert sein, bevor Sie XrSystemEyeTrackingPropertiesANDROID verwenden können.
type muss XR_TYPE_SYSTEM_EYE_TRACKING_PROPERTIES_ANDROID sein.
next muss NULL oder ein gültiger Verweis auf die nächste Struktur in einer Strukturkette sein.

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 Eye-Tracking-Daten 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

session ist ein XrSession-Handle, für den das Eye-Tracking aktiv ist.
createInfo ist die XrEyeTrackerCreateInfoANDROID, mit der das Augen-Tracking angegeben wird.
eyeTracker ist der zurückgegebene XrEyeTrackerANDROID-Handle.

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)

Die XR_ANDROID_eye_tracking-Erweiterung muss aktiviert sein, bevor xrCreateEyeTrackerANDROID aufgerufen wird.
session muss ein gültiger XrSession-Alias sein.
createInfo muss ein Verweis auf eine gültige XrEyeTrackerCreateInfoANDROID-Struktur sein.
eyeTracker muss ein Verweis auf einen XrEyeTrackerANDROID-Handle sein

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 dieser Struktur.
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 XR_ANDROID_eye_tracking-Erweiterung muss aktiviert sein, bevor Sie XrEyeTrackerCreateInfoANDROID verwenden können.
type muss XR_TYPE_EYE_TRACKER_CREATE_INFO_ANDROID sein.
next muss NULL oder ein gültiger Verweis auf die nächste Struktur in einer Strukturkette sein.

Die Funktion xrDestroyEyeTrackerANDROID ist so definiert:

XrResult xrDestroyEyeTrackerANDROID(
    XrEyeTrackerANDROID                         eyeTracker);

Parameterbeschreibungen

eyeTracker ist eine XrEyeTrackerANDROID, die zuvor von xrCreateEyeTrackerANDROID erstellt wurde.

Die Funktion xrDestroyEyeTrackerANDROID gibt eyeTracker und die zugrunde liegenden Ressourcen frei, wenn die Tests abgeschlossen sind.

Gültige Verwendung (implizit)

Die XR_ANDROID_eye_tracking-Erweiterung muss aktiviert sein, bevor xrDestroyEyeTrackerANDROID aufgerufen wird.
eyeTracker muss ein gültiger XrEyeTrackerANDROID-Alias sein.

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

eyeTracker ist eine XrEyeTrackerANDROID, die zuvor von xrCreateEyeTrackerANDROID erstellt wurde.
getInfo ist ein Verweis auf XrEyesGetInfoANDROID, mit dem angegeben wird, welche Ausgabe erforderlich ist.
infoOutput ist ein Verweis auf XrEyesANDROID, der die zurückgegebenen Informationen zu den Augen enthält, einschließlich Posen und Status.

Die Funktion xrGetCoarseTrackingEyesInfoANDROID ruft die 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 Augenbewegung 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)

Die XR_ANDROID_eye_tracking-Erweiterung muss aktiviert sein, bevor xrGetCoarseTrackingEyesInfoANDROID aufgerufen wird.
eyeTracker muss ein gültiger XrEyeTrackerANDROID-Alias sein.
getInfo muss ein Verweis auf eine gültige XrEyesGetInfoANDROID-Struktur sein.
eyesOutput muss ein Zeiger auf eine XrEyesANDROID-Struktur sein

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: {:#xrGetFineTrackingEyesInfoANDROID} C++ XrResult xrGetFineTrackingEyesInfoANDROID( XrEyeTrackerANDROID eyeTracker, const XrEyesGetInfoANDROID* getInfo, XrEyesANDROID* eyesOutput);

Parameterbeschreibungen

eyeTracker ist eine XrEyeTrackerANDROID, die zuvor von xrCreateEyeTrackerANDROID erstellt wurde.
getInfo ist ein Verweis auf XrEyesGetInfoANDROID, mit dem angegeben wird, welche Ausgabe erforderlich ist.
infoOutput ist ein Verweis auf XrEyesANDROID, der die zurückgegebenen Informationen zu den Augen enthält, einschließlich Posen und Status. Mit der Funktion xrGetFineTrackingEyesInfoANDROID werden die Informationen zu Augenzuständen und -posen genauer als mit xrGetCoarseTrackingEyesInfoANDROID abgerufen.

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

Gültige Verwendung (implizit)

Die XR_ANDROID_eye_tracking-Erweiterung muss aktiviert sein, bevor xrGetFineTrackingEyesInfoANDROID aufgerufen wird.
eyeTracker muss ein gültiger XrEyeTrackerANDROID-Alias sein.
getInfo muss ein Verweis auf eine gültige XrEyesGetInfoANDROID-Struktur sein.
eyesOutput muss ein Zeiger auf eine XrEyesANDROID-Struktur sein

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 dieser Struktur.
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 XR_ANDROID_eye_tracking-Erweiterung muss aktiviert sein, bevor Sie XrEyesGetInfoANDROID verwenden können.
type muss XR_TYPE_EYES_GET_INFO_ANDROID sein.
next muss NULL oder ein gültiger Verweis auf die nächste Struktur in einer Strukturkette sein.
baseSpace muss ein gültiger XrSpace-Alias sein.

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 dieser Struktur.
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 XR_ANDROID_eye_tracking-Erweiterung muss aktiviert sein, bevor Sie XrEyesANDROID verwenden können.
type muss XR_TYPE_EYES_ANDROID sein.
next muss NULL oder ein gültiger Verweis auf die nächste Struktur in einer Strukturkette sein.
Jedes Element von eyes muss eine gültige XrEyeANDROID-Struktur sein.
mode muss ein gültiger XrEyeTrackingModeANDROID-Wert sein

Die XrEyeANDROID-Struktur beschreibt den Status, 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 Koordinatenaxes 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 wird.

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