Estensione OpenXR XR_ANDROID_eye_tracking

Stringa del nome

XR_ANDROID_eye_tracking

Tipo di estensione

Estensione dell'istanza

Numero di estensione registrato

457

Revisione

1

Dipendenze di estensioni e versioni

OpenXR 1.0

Data ultima modifica

2025-01-17

Stato IP

Nessuna rivendicazione IP 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 del monitoraggio oculare.

I dati del monitoraggio degli occhi sono forniti in due modalità: approssimativa e precisa. Il monitoraggio approssimativo fornisce una stima approssimativa degli occhi dell'utente, mentre il monitoraggio accurato fornisce una stima più precisa. Il monitoraggio approssimativo è pensato per le applicazioni che vogliono fornire una rappresentazione di base simile ad avatar, mentre il monitoraggio accurato è pensato per applicazioni più precise.

Per l'interazione, XR_EXT_eye_gaze_interaction deve essere utilizzato.

Controlla la funzionalità del sistema

La struttura XrSystemEyeTrackingPropertiesANDROID è definita come:

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

Descrizioni dei membri

  • type è il XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Queste strutture non sono definite in OpenXR di base o in questa estensione.
  • supportsEyeTracking è un XrBool32, che indica se il sistema corrente supporta il monitoraggio oculare.

Un'applicazione può verificare se il sistema è in grado di rilevare i movimenti degli occhi concatenando una struttura XrSystemEyeTrackingPropertiesANDROID a XrSystemProperties quando chiama xrGetSystemProperties. Se supportsEyeTracking restituisce XR_FALSE, un'applicazione riceverà XR_ERROR_FEATURE_UNSUPPORTED da xrCreateEyeTrackerANDROID.

Utilizzo valido (implicito)

Creare un handle per il tracker oculare

XR_DEFINE_HANDLE(XrEyeTrackerANDROID)

L'handle XrEyeTrackerANDROID rappresenta un tracker oculare per il monitoraggio degli occhi e mappa con precisione ciò che l'utente sta guardando.

I dati di monitoraggio degli occhi possono essere informazioni personali sensibili e sono strettamente correlati alla privacy e all'integrità personali. È vivamente consigliato che le applicazioni che archiviano o trasferiscono dati di monitoraggio oculare chiedano sempre all'utente un'accettazione attiva e specifica per farlo.

Questo handle può essere utilizzato per accedere ai dati del monitoraggio oculare utilizzando altre funzioni di questa estensione.

Il monitoraggio degli occhi fornisce la rappresentazione della posizione 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 può creare un handle XrEyeTrackerANDROID utilizzando la funzione xrCreateEyeTrackerANDROID.

Se il sistema non supporta il monitoraggio degli occhi, XR_ERROR_FEATURE_UNSUPPORTED viene restituito da xrCreateEyeTrackerANDROID.

Utilizzo valido (implicito)

Codici di ritorno

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • 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

La struttura XrEyeTrackerCreateInfoANDROID è definita come: 

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

Descrizioni dei membri

  • type è il XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Queste strutture non sono definite 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 di base al termine delle esperienze di monitoraggio degli occhi.

Utilizzo valido (implicito)

Coerenza di thread

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

Codici di ritorno

Operazione riuscita

  • XR_SUCCESS

Errore

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

Visualizzazione 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 relative agli stati e alle 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 informazioni sugli occhi vengono risolte e sono relative allo spazio di base al momento della chiamata a xrGetCoarseTrackingEyesInfoANDROID utilizzando XrEyesGetInfoANDROID::time, XrEyesGetInfoANDROID::baseSpace.

In qualsiasi momento, sia la posizione sia la direzione della posa degli occhi vengono monitorate o meno. Ciò significa che le applicazioni possono prevedere che sia XR_SPACE_LOCATION_POSITION_TRACKED_BIT sia XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT vengano impostati o cancellati sul XrEyesANDROID::eyes fornito e che XrEyesANDROID::mode indichi 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_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

La funzione xrGetFineTrackingEyesInfoANDROID è definita come: {:#xrGetFineTrackingEyesInfoANDROID} C++ XrResult xrGetFineTrackingEyesInfoANDROID( XrEyeTrackerANDROID eyeTracker, const XrEyesGetInfoANDROID* getInfo, XrEyesANDROID* eyesOutput);

Descrizioni dei parametri

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.

In qualsiasi momento, sia la posizione sia la direzione della posa degli occhi vengono monitorate o meno. Ciò significa che le applicazioni possono prevedere che sia XR_SPACE_LOCATION_POSITION_TRACKED_BIT sia XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT vengano impostati o cancellati sul XrEyesANDROID::eyes fornito e che XrEyesANDROID::mode indichi 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_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

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

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

Descrizioni dei membri

  • type è il XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Queste strutture non sono definite in OpenXR di base o in questa estensione.
  • time è il XrTime in cui valutare le coordinate rispetto al baseSpace.
  • baseSpace la posa degli occhi sarà relativa a questo XrSpace alle ore time.

Utilizzo valido (implicito)

La struttura XrEyesANDROID contiene informazioni sugli occhi monitorati. 

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

Descrizioni dei membri

  • type è il XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Queste strutture non sono definite in OpenXR di base o in questa estensione.
  • eyes è un array di XrEyeANDROID per gli occhi sinistro e destro come indicizzato da XrEyeIndexANDROID.
  • mode è il XrEyeTrackingModeANDROID per indicare se gli occhi sono monitorati e quali.

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 è la XrEyeStateANDROID di un occhio.
  • pose è un XrPosef che definisce la posizione e l'orientamento dell'origine di un occhio all'interno del sistema di riferimento del corrispondente XrEyesGetInfoANDROID::baseSpace. Un orientamento dell'identità rappresenta qui un asse di coordinate con +Z verso gli occhi dell'utente, +X a destra e +Y verso l'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 monitorati. 

typedef enum XrEyeStateANDROID {
    XR_EYE_STATE_INVALID_ANDROID = 0,
    XR_EYE_STATE_GAZING_ANDROID = 1,
    XR_EYE_STATE_SHUT_ANDROID = 2
} XrEyeStateANDROID;

Gli enum hanno i seguenti significati:

Enum

Descrizione

XR_EYE_STATE_INVALID_ANDROID

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

XR_EYE_STATE_GAZING_ANDROID

Indica che l'occhio è fisso.

XR_EYE_STATE_SHUT_ANDROID

Indica che l'occhio è 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
} XrEyeIndexANDROID;

Gli enum hanno i seguenti significati:

Enum

Descrizione

XR_EYE_INDEX_LEFT_ANDROID

Occhio sinistro.

XR_EYE_INDEX_RIGHT_ANDROID

Occhio destro.

L'enumerazione XrEyeTrackingModeANDROID identifica le diverse modalità degli occhi monitorati. 

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;

Gli enum hanno i seguenti significati:

Enum

Descrizione

XR_EYE_TRACKING_MODE_NOT_TRACKING_ANDROID

Indica che il monitoraggio degli occhi non è 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 sia l'occhio sinistro che quello destro sono in monitoraggio.

Codice di esempio per il monitoraggio oculare

Il seguente codice di esempio mostra come ottenere informazioni sugli occhi relative a un spazio visivo.

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

Nuove costanti enum

  • XR_EYE_MAX_ANDROID

L'enumerazione XrObjectType è stata estesa con:

  • XR_OBJECT_TYPE_EYE_TRACKER_ANDROID

L'enumerazione XrStructureType è stata estesa con:

  • XR_TYPE_EYES_ANDROID
  • XR_TYPE_EYE_TRACKER_CREATE_INFO_ANDROID
  • XR_TYPE_EYES_GET_INFO_ANDROID
  • XR_TYPE_SYSTEM_EYE_TRACKING_PROPERTIES_ANDROID

Nuovi enum

Nuove strutture

Nuove funzioni

Problemi

Cronologia delle versioni

  • Revisione 1, 17/01/2025 (Kenny Vercaemer)
    • Descrizione iniziale dell'estensione

OpenXR™ e il logo OpenXR sono marchi di proprietà di The Khronos Group Inc. e sono registrati come marchi in Cina, nell'Unione Europea, in Giappone e nel Regno Unito.