XR_ANDROID_eye_tracking

Stringa del nome

XR_ANDROID_eye_tracking

Tipo di estensione

Estensione dell'istanza

Numero di interno registrato

457

Revisione

1

Stato di ratifica

Non ratificato

Dipendenze da estensioni e versioni

OpenXR 1.0

Data ultima modifica

2025-01-17

Stato IP

Nessuna rivendicazione di proprietà intellettuale nota.

Collaboratori

Spencer Quin, Google
Jared Finder, Google
Levana Chen, Google
Kenny Vercaemer, Google
Prasanthi Gurumurthy, Google
Nihav Jain, Google

Panoramica

Questa estensione consente alle applicazioni di ottenere la posizione e l'orientamento degli occhi dell'utente, nonché lo stato dell'eye tracking.

I dati di eye tracking vengono forniti in due modalità: grossolana e precisa. Il tracciamento approssimativo fornisce una stima approssimativa degli occhi dell'utente, mentre il tracciamento preciso fornisce una stima più accurata. Il monitoraggio approssimativo è destinato alle applicazioni che vogliono fornire una rappresentazione di base simile a un avatar, mentre il monitoraggio preciso è destinato alle applicazioni più precise.

Per l'interazione, XR_EXT_eye_gaze_interaction deve essere utilizzato.

Autorizzazioni

Le applicazioni Android devono avere l'autorizzazione android.permission.EYE_TRACKING_COARSE o android.permission.EYE_TRACKING_FINE elencata nel manifest. Queste autorizzazioni sono considerate pericolose. L'applicazione deve richiedere l'autorizzazione in fase di runtime per utilizzare queste funzioni:

(livello di protezione: pericoloso)

Ispezionare la funzionalità del sistema

La struttura XrSystemEyeTrackingPropertiesANDROID è definita come:

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

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Nessuna struttura di questo tipo è definita in OpenXR di base o in questa estensione.
  • supportsEyeTracking è un XrBool32 che indica se il sistema attuale supporta l'eye tracking.

Un'applicazione può verificare se il sistema è in grado di eye tracking estendendo XrSystemProperties con la struttura XrSystemEyeTrackingPropertiesANDROID quando chiama xrGetSystemProperties .

Se e solo se un runtime restituisce XR_FALSE per supportsEyeTracking , il runtime deve restituire XR_ERROR_FEATURE_UNSUPPORTED da xrCreateEyeTrackerANDROID .

Utilizzo valido (implicito)

Creare un handle per il sistema di tracciamento oculare

XR_DEFINE_HANDLE(XrEyeTrackerANDROID)

L'handle XrEyeTrackerANDROID rappresenta un eye tracker per il monitoraggio degli occhi e mappa con precisione dove guarda l'utente.

I dati di eye tracking sono informazioni personali sensibili e sono strettamente collegati alla privacy e all'integrità personali. È vivamente consigliabile che le applicazioni che memorizzano o trasferiscono dati di eye tracking chiedano sempre all'utente un'accettazione attiva e specifica.

L'applicazione utilizza questo handle per accedere ai dati di eye tracking utilizzando altre funzioni di questa estensione.

L'eye tracking fornisce la rappresentazione della postura e dello stato degli occhi nella scena.

La funzione xrCreateEyeTrackerANDROID è definita come:

XrResult xrCreateEyeTrackerANDROID(
    XrSession                                   session,
    const XrEyeTrackerCreateInfoANDROID*        createInfo,
    XrEyeTrackerANDROID*                        eyeTracker);

Descrizioni dei parametri

Un'applicazione crea un handle XrEyeTrackerANDROID utilizzando la funzione xrCreateEyeTrackerANDROID.

Se il sistema non supporta il monitoraggio oculare, il runtime deve restituire XR_ERROR_FEATURE_UNSUPPORTED da xrCreateEyeTrackerANDROID .

Utilizzo valido (implicito)

Codici di ritorno

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • 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

La struttura XrEyeTrackerCreateInfoANDROID è definita come:

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

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Nessuna struttura di questo tipo è definita in OpenXR di base o in questa estensione.

La struttura XrEyeTrackerCreateInfoANDROID descrive le informazioni per creare un handle XrEyeTrackerANDROID.

Utilizzo valido (implicito)

La funzione xrDestroyEyeTrackerANDROID è definita come:

XrResult xrDestroyEyeTrackerANDROID(
    XrEyeTrackerANDROID                         eyeTracker);

Descrizioni dei parametri

La funzione xrDestroyEyeTrackerANDROID rilascia eyeTracker e le risorse sottostanti al termine delle esperienze di eye tracking.

Utilizzo valido (implicito)

Thread Safety

  • L'accesso a eyeTracker e a tutti gli handle secondari deve essere sincronizzato esternamente

Codici di ritorno

Operazione riuscita

  • XR_SUCCESS

Errore

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

Recupero delle informazioni sugli occhi

La funzione xrGetCoarseTrackingEyesInfoANDROID è definita come:

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

Descrizioni dei parametri

La funzione xrGetCoarseTrackingEyesInfoANDROID recupera le informazioni sugli stati e sulle pose degli occhi in modo da preservare la privacy dell'utente.

Il runtime deve restituire XR_ERROR_PERMISSION_INSUFFICIENT se l'applicazione non dispone dell'autorizzazione android.permission.EYE_TRACKING_COARSE.

Le pose degli occhi sono espresse in XrEyesGetInfoANDROID :: baseSpace in XrEyesGetInfoANDROID :: time .

In qualsiasi momento, la posizione e la direzione della posa dell'occhio vengono tracciate o non tracciate. Ciò significa che il runtime deve impostare sia XR_SPACE_LOCATION_POSITION_TRACKED_BIT che XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT o cancellare sia XR_SPACE_LOCATION_POSITION_TRACKED_BIT che XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT nell'elemento XrEyesANDROID :: eyes fornito e impostare XrEyesANDROID :: mode per indicare gli stati di monitoraggio.

Utilizzo valido (implicito)

Codici di ritorno

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • 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

La funzione xrGetFineTrackingEyesInfoANDROID è definita come:

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

Descrizioni dei parametri

La funzione xrGetFineTrackingEyesInfoANDROID recupera le informazioni sugli stati e sulle pose degli occhi con una precisione maggiore rispetto a xrGetCoarseTrackingEyesInfoANDROID .

Il runtime deve restituire XR_ERROR_PERMISSION_INSUFFICIENT se l'applicazione non dispone dell'autorizzazione android.permission.EYE_TRACKING_FINE.

Le informazioni sugli occhi vengono risolte e sono relative allo spazio di base al momento della chiamata a xrGetFineTrackingEyesInfoANDROID utilizzando XrEyesGetInfoANDROID :: time , XrEyesGetInfoANDROID :: baseSpace . Il runtime deve risolvere la posizione definita da XrEyesGetInfoANDROID :: baseSpace al momento della chiamata.

In qualsiasi momento, la posizione e la direzione della posa dell'occhio vengono tracciate o non tracciate. Ciò significa che il runtime deve impostare sia XR_SPACE_LOCATION_POSITION_TRACKED_BIT che XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT o cancellare sia XR_SPACE_LOCATION_POSITION_TRACKED_BIT che XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT nell'elemento XrEyesANDROID :: eyes fornito e impostare XrEyesANDROID :: mode per indicare gli stati di monitoraggio.

Utilizzo valido (implicito)

Codici di ritorno

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • 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

La struttura XrEyesGetInfoANDROID contiene le informazioni necessarie per recuperare le pose e gli stati degli occhi.

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

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Nessuna struttura di questo tipo è definita in OpenXR di base o in questa estensione.
  • time è il XrTime in cui valutare le coordinate rispetto a baseSpace .
  • baseSpace è l'XrSpace rispetto al quale le pose degli occhi saranno relative a time .

Utilizzo valido (implicito)

La struttura XrEyesANDROID contiene informazioni sugli occhi tracciati.

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

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Nessuna struttura di questo tipo è definita in OpenXR di base o in questa estensione.
  • eyes è un array di XrEyeANDROID, di dimensione XR_EYE_MAX_ANDROID, per l'occhio sinistro e destro, indicizzato da XrEyeIndexANDROID .
  • mode è XrEyeTrackingModeANDROID che indica quali occhi vengono tracciati al momento.

Utilizzo valido (implicito)

La struttura XrEyeANDROID descrive lo stato, la posizione e l'orientamento di un occhio.

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

Descrizioni dei membri

  • eyeState è XrEyeStateANDROID di un occhio.
  • eyePose è un XrPosef che definisce la posizione e l'orientamento della pupilla di un occhio all'interno del sistema di riferimento del corrispondente XrEyesGetInfoANDROID :: baseSpace . L'orientamento di un'identità qui rappresenta un sistema di coordinate con +Z verso gli occhi dell'utente, +X a destra e +Y in alto.

Utilizzo valido (implicito)

  • L'estensione XR_ANDROID_eye_tracking deve essere attivata prima di utilizzare XrEyeANDROID
  • eyeState deve essere un valore XrEyeStateANDROID valido

L'enumerazione XrEyeStateANDROID identifica i diversi stati degli occhi tracciati.

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;

Gli enum hanno i seguenti significati:

Descrizione enum

XR_EYE_STATE_INVALID_ANDROID

Indica che l'occhio è in stato di errore o non è presente.

XR_EYE_STATE_GAZING_ANDROID

Indica che l'occhio sta attualmente guardando.

XR_EYE_STATE_SHUT_ANDROID

Indica che l'occhio è attualmente chiuso a causa di un'occhiolino o di un battito di ciglia.

L'enumerazione XrEyeIndexANDROID identifica l'indice dell'occhio sinistro o destro.

typedef enum XrEyeIndexANDROID {
    XR_EYE_INDEX_LEFT_ANDROID = 0,
    XR_EYE_INDEX_RIGHT_ANDROID = 1,
    XR_EYE_INDEX_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrEyeIndexANDROID;

Gli enum hanno i seguenti significati:

Descrizione enum

XR_EYE_INDEX_LEFT_ANDROID

Occhio sinistro.

XR_EYE_INDEX_RIGHT_ANDROID

Occhio destro.

L'enumerazione XrEyeTrackingModeANDROID identifica i diversi stati degli occhi tracciati.

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;

Gli enum hanno i seguenti significati:

Descrizione enum

XR_EYE_TRACKING_MODE_NOT_TRACKING_ANDROID

Indica che l'eye tracking non è attualmente attivo.

XR_EYE_TRACKING_MODE_RIGHT_ANDROID

Indica che viene monitorato solo l'occhio destro.

XR_EYE_TRACKING_MODE_LEFT_ANDROID

Indica che viene monitorato solo l'occhio sinistro.

XR_EYE_TRACKING_MODE_BOTH_ANDROID

Indica che entrambi gli occhi, il sinistro e il destro, vengono tracciati.

Codice di esempio per l'eye tracking

Il seguente codice di esempio mostra come ottenere informazioni sugli occhi rispetto a uno spazio di visualizzazione.

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

Nuovi tipi di oggetti

Nuovi comandi

Nuove strutture

Nuovi enum

Nuove costanti enum

  • XR_ANDROID_EYE_TRACKING_EXTENSION_NAME
  • XR_ANDROID_eye_tracking_SPEC_VERSION
  • XR_EYE_MAX_ANDROID

  • Estensione di XrObjectType :

    • XR_OBJECT_TYPE_EYE_TRACKER_ANDROID

  • Estensione di 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

Problemi

Cronologia delle versioni

  • Revisione 1, 17/01/2025 (Kenny Vercaemer)

    • Descrizione iniziale dell'estensione