OpenXR-Erweiterung „XR_ANDROID_avatar_eyes“

Namensstring

XR_ANDROID_avatar_eyes

Erweiterungstyp

Instanzerweiterung

Registrierte Durchwahlnummer

457

Revision

1

Erweiterungs- und Versionsabhängigkeiten

OpenXR 1.0

Datum der letzten Änderung

2024-09-30

IP-Status

Es sind keine Ansprüche aufgrund von Urheberrechten bekannt.

Mitwirkende

Spencer Quin, Google

Jared Finder, Google

Levana Chen, Google

Übersicht

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

Mit dieser Erweiterung soll die Darstellung der Augenposition und des Status von Avataren realistischer werden. Zu diesem Zweck:

  • Es ermöglicht nicht erfasste Status wie Blinken.
  • Es ermöglicht monokulares oder binokulares Tracking.

Diese Erweiterung darf nicht für andere Zwecke des Blicktrackings verwendet werden. Für die Interaktion sollte XR_EXT_eye_gaze_interaction verwendet werden.

Eye-Tracker

Ein Eye-Tracker ist ein Sensor, der die Augen verfolgt und genau erfasst, worauf der Nutzer schaut. Der Hauptzweck dieser Erweiterung besteht darin, den Blick von Nutzern auf ihre Avatare in einer virtuellen Szene abzubilden.

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.

  • Eine Anwendung erhält XR_ERROR_PERMISSION_INSUFFICIENT, wenn versucht wird, einen aktiven Eyetracker zu erstellen, bis der Anwendung Zugriff auf den Eyetracker gewährt wurde.

Systemkapazität prüfen

Eine Anwendung kann prüfen, ob das System Avataraugen unterstützt, indem sie beim Aufruf von xrGetSystemProperties eine XrSystemAvatarEyesPropertiesANDROID-Struktur an die XrSystemProperties-Struktur anhängt. Wenn supportsAvatarEyes XR_FALSE zurückgibt, erhält eine Anwendung XR_ERROR_FEATURE_UNSUPPORTED von xrCreateEyeTrackerANDROID.

typedef struct XrSystemAvatarEyesPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsAvatarEyes;
} XrSystemAvatarEyesPropertiesANDROID;

Beschreibungen von Mitgliedern

  • 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 oder dieser Erweiterung nicht definiert.
  • supportsAvatarEyes ist ein XrBool32, das angibt, ob das aktuelle System Avataraugen unterstützt.

Gültige Verwendung (implizit)

Eye-Tracker-Handle erstellen

XR_DEFINE_HANDLE(XrEyeTrackerANDROID)

Der Handle XrEyeTrackerANDROID stellt einen Eye-Tracker dar, der die Augen verfolgt und genau erfasst, worauf sich der Nutzer gerade konzentriert.

Ü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 Augenerkennung 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

Die Struktur XrEyeTrackerCreateInfoANDROID ist so definiert: 

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

Beschreibungen von Mitgliedern

  • 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 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 die eyeTracker und die zugrunde liegenden Ressourcen frei, wenn die Eye-Tracking-Funktionen nicht mehr verwendet 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

Informationen zu Augen abrufen

Die Funktion xrGetEyesInfoANDROID ist so definiert:

XrResult xrGetEyesInfoANDROID(
    XrEyeTrackerANDROID                         eyeTracker,
    const XrEyesGetInfoANDROID*                 getInfo,
    XrEyesANDROID*                              infoOutput);

Parameterbeschreibungen

Die Funktion xrGetEyesInfoANDROID ruft die Informationen zu den Augenzuständen und -posen ab.

Die Informationen zu den Augen werden mithilfe von XrEyesGetInfoANDROID::time, XrEyesGetInfoANDROID::baseSpace aufgelöst und relativ zum Basisbereich zum Zeitpunkt des Aufrufs von xrGetEyesInfoANDROID angegeben.

Zu jedem Zeitpunkt werden sowohl die Position als auch die Richtung der Augenbewegung 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 entweder für das bereitgestellte XrEyesANDROID::eyes 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

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 der 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 ist relativ zu diesem XrSpace bei time.

Gültige Verwendung (implizit)

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

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

Beschreibungen von Mitgliedern

  • 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 oder dieser Erweiterung nicht definiert.
  • eyes ist ein Array von XrEyeANDROID für das linke und rechte Auge, wie durch XrEyeIndexANDROID indiziert.
  • mode ist der XrEyeTrackingModeANDROID, der angibt, ob die Augen verfolgt werden und welche.

Gültige Verwendung (implizit)

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

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

Beschreibungen von Mitgliedern

  • eyeState ist der 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_avatar_eyes-Erweiterung muss aktiviert sein, bevor XrEyeANDROID verwendet werden kann.
  • eyeState muss ein gültiger Wert für XrEyeStateANDROID sein

Die Aufzählung XrEyeStateANDROID gibt die verschiedenen Status der getrackten 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 getrackte 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, for example, 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_xrGetEyesInfoANDROID xrGetEyesInfoANDROID; // 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 eyesInfo{.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(xrGetEyesInfoANDROID(eyeTracker, &eyesGetInfo, &eyesInfo));

    // 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 wurde um Folgendes erweitert:

  • XR_OBJECT_TYPE_EYE_TRACKER_ANDROID

Die Aufzählung XrStructureType wurde um folgende Elemente erweitert:

  • XR_TYPE_EYES_ANDROID
  • XR_TYPE_EYE_TRACKER_CREATE_INFO_ANDROID
  • XR_TYPE_EYES_GET_INFO_ANDROID
  • XR_TYPE_SYSTEM_AVATAR_EYES_PROPERTIES_ANDROID

Neue Enums

Neue Strukturen

Neue Funktionen

Probleme

Versionsverlauf

  • Revision 1, 04.09.2024 (Levana Chen)
    • Erste Beschreibung der Erweiterung