Estensione OpenXR XR_ANDROID_avatar_eyes

Eye tracker

Un eye tracker è un dispositivo di rilevamento che monitora gli occhi e mappa con precisione la direzione in cui l'utente sta guardando. Lo scopo principale di questa estensione è mappare gli sguardi degli utenti ai loro avatar in una scena virtuale.

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

• Un'applicazione riceverà XR_ERROR_PERMISSION_INSUFFICIENT quando tenta di creare un tracciatore oculare attivo finché non le viene consentito l'accesso al tracciatore oculare.

Controlla la funzionalità del sistema

Un'applicazione può verificare se il sistema supporta gli occhi dell'avatar concatenando una struttura XrSystemAvatarEyesPropertiesANDROID a XrSystemProperties quando chiama xrGetSystemProperties. Se supportsAvatarEyes restituisce XR_FALSE, un'applicazione riceverà XR_ERROR_FEATURE_UNSUPPORTED da xrCreateEyeTrackerANDROID.

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

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.
• supportsAvatarEyes è un XrBool32 che indica se il sistema attuale supporta gli occhi degli avatar.

Utilizzo valido (implicito)

• L'estensione XR_ANDROID_avatar_eyes deve essere attivata prima di utilizzare XrSystemAvatarEyesPropertiesANDROID
• type deve essere XR_TYPE_SYSTEM_AVATAR_EYES_PROPERTIES_ANDROID
• next deve essere NULL o un puntatore valido alla struttura successiva in una catena di strutture

Creare un handle per il tracker degli occhi

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.

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

Il monitoraggio degli occhi fornisce una 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

• session è un handle XrSession in cui sarà attivo il monitoraggio degli occhi.
• createInfo è il XrEyeTrackerCreateInfoANDROID utilizzato per specificare il monitoraggio degli occhi.
• eyeTracker è l'handle XrEyeTrackerANDROID restituito.

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)

• L'estensione XR_ANDROID_avatar_eyes deve essere attivata prima di chiamare xrCreateEyeTrackerANDROID
• session deve essere un handle XrSession valido
• createInfo deve essere un puntatore a una struttura XrEyeTrackerCreateInfoANDROID valida
• eyeTracker deve essere un puntatore a un handle XrEyeTrackerANDROID

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

La struttura XrEyeTrackerCreateInfoANDROID è definita come segue:

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)

• L'estensione XR_ANDROID_avatar_eyes deve essere attivata prima di utilizzare XrEyeTrackerCreateInfoANDROID
• type deve essere XR_TYPE_EYE_TRACKER_CREATE_INFO_ANDROID
• next deve essere NULL o un puntatore valido alla struttura successiva in una catena di strutture

La funzione xrDestroyEyeTrackerANDROID è definita come:

XrResult xrDestroyEyeTrackerANDROID(
    XrEyeTrackerANDROID                         eyeTracker);

Descrizioni dei parametri

• eyeTracker è un XrEyeTrackerANDROID creato in precedenza con xrCreateEyeTrackerANDROID.

La funzione xrDestroyEyeTrackerANDROID rilascia eyeTracker e le risorse di base al termine delle esperienze di monitoraggio degli occhi.

Utilizzo valido (implicito)

• L'estensione XR_ANDROID_avatar_eyes deve essere attivata prima di chiamare xrDestroyEyeTrackerANDROID
• eyeTracker deve essere un handle XrEyeTrackerANDROID valido

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

Ottenere informazioni sugli occhi

La funzione xrGetEyesInfoANDROID è definita come:

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

Descrizioni dei parametri

• eyeTracker è un XrEyeTrackerANDROID creato in precedenza con xrCreateEyeTrackerANDROID.
• getInfo è un puntatore a XrEyesGetInfoANDROID utilizzato per specificare quale output è richiesto.
• infoOutput è un puntatore a XrEyesANDROID che contiene le informazioni sugli occhi restituite, tra cui pose e stati.

La funzione xrGetEyesInfoANDROID recupera le informazioni relative agli stati e alle pose degli occhi.

Le informazioni sugli occhi vengono risolte e sono relative allo spazio di base al momento della chiamata a xrGetEyesInfoANDROID utilizzando XrEyesGetInfoANDROID::time, XrEyesGetInfoANDROID::baseSpace.

In qualsiasi momento, la posizione e 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 su XrEyesANDROID::eyes fornito e che XrEyesANDROID::mode indichi gli stati di monitoraggio.

Utilizzo valido (implicito)

• L'estensione XR_ANDROID_avatar_eyes deve essere attivata prima di chiamare xrGetEyesInfoANDROID
• eyeTracker deve essere un handle XrEyeTrackerANDROID valido
• getInfo deve essere un puntatore a una struttura XrEyesGetInfoANDROID valida
• infoOutput deve essere un puntatore a una struttura XrEyesANDROID

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

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 relative al baseSpace.
• baseSpace la posizione degli occhi sarà relativa a questo XrSpace in time.

Utilizzo valido (implicito)

• L'estensione XR_ANDROID_avatar_eyes deve essere attivata prima di utilizzare XrEyesGetInfoANDROID
• type deve essere XR_TYPE_EYES_GET_INFO_ANDROID
• next deve essere NULL o un puntatore valido alla struttura successiva in una catena di strutture
• baseSpace deve essere un handle XrSpace valido

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 l'occhio sinistro e destro come indicato da XrEyeIndexANDROID.
• mode è il valore XrEyeTrackingModeANDROID per indicare se gli occhi sono monitorati e quali.

Utilizzo valido (implicito)

• L'estensione XR_ANDROID_avatar_eyes deve essere attivata prima di utilizzare XrEyesANDROID
• type deve essere XR_TYPE_EYES_ANDROID
• next deve essere NULL o un puntatore valido alla struttura successiva in una catena di strutture
• Qualsiasi elemento di eyes deve essere una struttura XrEyeANDROID valida
• mode deve essere un valore XrEyeTrackingModeANDROID valido

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 è l'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_avatar_eyes 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:

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:

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:

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

Nuovi tipi di oggetti

• XrEyeTrackerANDROID

Nuove costanti enum

• XR_EYE_MAX_ANDROID

L'enumerazione XrObjectType è 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_AVATAR_EYES_PROPERTIES_ANDROID

Nuovi enum

• XrEyeIndexANDROID
• XrEyeStateANDROID
• XrEyeTrackingModeANDROID

Nuove strutture

• XrEyeANDROID
• XrEyesANDROID
• XrEyesGetInfoANDROID
• XrEyeTrackerCreateInfoANDROID
• XrSystemAvatarEyesPropertiesANDROID

Nuove funzioni

• xrCreateEyeTrackerANDROID
• xrDestroyEyeTrackerANDROID
• xrGetEyesInfoANDROID

Problemi

Cronologia delle versioni

• Revisione 1, 4 settembre 2024 (Levana Chen)
  • Descrizione iniziale dell'estensione