Ekstensi OpenXR XR_ANDROID_eye_tracking

String Nama

XR_ANDROID_eye_tracking

Jenis Ekstensi

Ekstensi instance

Registered Extension Number

457

Revisi

1

Dependensi Ekstensi dan Versi

OpenXR 1.0

Tanggal Terakhir Diubah

2025-01-17

Status IP

Tidak ada klaim IP yang diketahui.

Kontributor

Spencer Quin, Google

Jared Finder, Google

Levana Chen, Google

Kenny Vercaemer, Google

Prasanthi Gurumurthy, Google

Nihav Jain, Google

Ringkasan

Ekstensi ini memungkinkan aplikasi mendapatkan posisi dan orientasi mata pengguna, serta status pelacakan mata.

Data pelacakan mata disediakan dalam dua mode: kasar dan halus. Pelacakan kasar memberikan perkiraan kasar tentang mata pengguna, sedangkan pelacakan halus memberikan perkiraan yang lebih akurat. Pelacakan kasar ditujukan untuk aplikasi yang ingin memberikan representasi seperti avatar dasar, sedangkan pelacakan halus ditujukan untuk aplikasi yang lebih presisi.

Untuk interaksi, XR_EXT_eye_gaze_interaction harus digunakan.

Perhatian: <br <br="" /> Izin

Aplikasi Android harus memiliki izin android.permission.EYE_TRACKING_COARSE atau android.permission.EYE_TRACKING_FINE yang tercantum dalam manifesnya. Izin ini dianggap sebagai izin berbahaya. Aplikasi harus meminta izin saat runtime untuk menggunakan fungsi ini:

• xrCreateEyeTrackerANDROID(setidaknya salah satu izin)
• xrGetCoarseTrackingEyesInfoANDROID(android.permission.EYE_TRACKING_COARSE)
• xrGetFineTrackingEyesInfoANDROID(android.permission.EYE_TRACKING_FINE)

(tingkat perlindungan: berbahaya)

Memeriksa kemampuan sistem

Struktur XrSystemEyeTrackingPropertiesANDROID ditentukan sebagai:

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

Deskripsi Anggota

• type adalah XrStructureType dari struktur ini.
• next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur. Tidak ada struktur seperti itu yang ditentukan di OpenXR inti atau ekstensi ini.
• supportsEyeTracking adalah XrBool32, yang menunjukkan apakah sistem saat ini mendukung pelacakan mata.

Aplikasi dapat memeriksa apakah sistem mampu melakukan pelacakan mata dengan mengaitkan struktur XrSystemEyeTrackingPropertiesANDROID ke XrSystemProperties saat memanggil xrGetSystemProperties. Jika supportsEyeTracking menampilkan XR_FALSE, aplikasi akan menerima XR_ERROR_FEATURE_UNSUPPORTED dari xrCreateEyeTrackerANDROID.

Penggunaan yang Valid (Implisit)

• Ekstensi XR_ANDROID_eye_tracking harus diaktifkan sebelum menggunakan XrSystemEyeTrackingPropertiesANDROID
• type harus berupa XR_TYPE_SYSTEM_EYE_TRACKING_PROPERTIES_ANDROID
• next harus berupa NULL atau pointer yang valid ke struktur berikutnya dalam rantai struktur

Membuat nama sebutan channel pelacak mata

XR_DEFINE_HANDLE(XrEyeTrackerANDROID)

Nama sebutan XrEyeTrackerANDROID mewakili pelacak mata untuk melacak mata dan memetakan secara akurat apa yang dilihat pengguna.

Data pelacakan mata dapat berupa informasi pribadi yang sensitif dan terkait erat dengan privasi dan integritas pribadi. Sebaiknya aplikasi yang menyimpan atau mentransfer data pelacakan mata selalu meminta persetujuan aktif dan tertentu dari pengguna untuk melakukannya.

Nama sebutan ini dapat digunakan untuk mengakses data pelacakan mata menggunakan fungsi lain di ekstensi ini.

Pelacakan mata memberikan representasi status dan pose mata dalam tampilan.

Fungsi xrCreateEyeTrackerANDROID ditentukan sebagai:

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

Deskripsi Parameter

• session adalah handle XrSession tempat pelacakan mata akan aktif.
• createInfo adalah XrEyeTrackerCreateInfoANDROID yang digunakan untuk menentukan pelacakan mata.
• eyeTracker adalah nama sebutan XrEyeTrackerANDROID yang ditampilkan.

Aplikasi dapat membuat nama sebutan XrEyeTrackerANDROID menggunakan fungsi xrCreateEyeTrackerANDROID.

Jika sistem tidak mendukung pelacakan mata, XR_ERROR_FEATURE_UNSUPPORTED akan ditampilkan dari xrCreateEyeTrackerANDROID.

Penggunaan yang Valid (Implisit)

• Ekstensi XR_ANDROID_eye_tracking harus diaktifkan sebelum memanggil xrCreateEyeTrackerANDROID
• session harus berupa nama sebutan channel XrSession yang valid
• createInfo harus berupa pointer ke struktur XrEyeTrackerCreateInfoANDROID yang valid
• eyeTracker harus berupa pointer ke nama sebutan channel XrEyeTrackerANDROID

Kode Status

Berhasil

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Kegagalan

• 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

Struktur XrEyeTrackerCreateInfoANDROID ditentukan sebagai:

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

Deskripsi Anggota

• type adalah XrStructureType dari struktur ini.
• next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur. Tidak ada struktur seperti itu yang ditentukan di OpenXR inti atau ekstensi ini.

Struktur XrEyeTrackerCreateInfoANDROID menjelaskan informasi untuk membuat nama sebutan XrEyeTrackerANDROID.

Penggunaan yang Valid (Implisit)

• Ekstensi XR_ANDROID_eye_tracking harus diaktifkan sebelum menggunakan XrEyeTrackerCreateInfoANDROID
• type harus berupa XR_TYPE_EYE_TRACKER_CREATE_INFO_ANDROID
• next harus berupa NULL atau pointer yang valid ke struktur berikutnya dalam rantai struktur

Fungsi xrDestroyEyeTrackerANDROID ditentukan sebagai:

XrResult xrDestroyEyeTrackerANDROID(
    XrEyeTrackerANDROID                         eyeTracker);

Deskripsi Parameter

• eyeTracker adalah XrEyeTrackerANDROID yang sebelumnya dibuat oleh xrCreateEyeTrackerANDROID.

Fungsi xrDestroyEyeTrackerANDROID merilis eyeTracker dan resource yang mendasarinya setelah selesai dengan pengalaman pelacakan mata.

Penggunaan yang Valid (Implisit)

• Ekstensi XR_ANDROID_eye_tracking harus diaktifkan sebelum memanggil xrDestroyEyeTrackerANDROID
• eyeTracker harus berupa nama sebutan channel XrEyeTrackerANDROID yang valid.

Keamanan Thread

• Akses ke eyeTracker, dan setiap nama sebutan turunan, harus disinkronkan secara eksternal

Kode Status

Berhasil

• XR_SUCCESS

Kegagalan

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID

Mendapatkan informasi mata

Fungsi xrGetCoarseTrackingEyesInfoANDROID ditentukan sebagai:

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

Deskripsi Parameter

• eyeTracker adalah XrEyeTrackerANDROID yang sebelumnya dibuat oleh xrCreateEyeTrackerANDROID.
• getInfo adalah pointer ke XrEyesGetInfoANDROID yang digunakan untuk menentukan output yang diperlukan.
• infoOutput adalah pointer ke XrEyesANDROID yang berisi informasi mata yang ditampilkan, termasuk pose dan status.

Fungsi xrGetCoarseTrackingEyesInfoANDROID mendapatkan informasi untuk status dan pose mata dengan cara yang menjaga privasi pengguna.

Runtime harus menampilkan XR_ERROR_PERMISSION_INSUFFICIENT jika aplikasi tidak memiliki izin android.permission.EYE_TRACKING_COARSE.

Informasi mata di-resolve dan relatif terhadap ruang dasar pada saat panggilan ke xrGetCoarseTrackingEyesInfoANDROID menggunakan XrEyesGetInfoANDROID::time, XrEyesGetInfoANDROID::baseSpace.

Pada setiap waktu, posisi dan arah pose mata dilacak atau tidak dilacak. Artinya, aplikasi dapat mengharapkan bahwa XR_SPACE_LOCATION_POSITION_TRACKED_BIT dan XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT akan ditetapkan atau dihapus pada XrEyesANDROID::eyes yang disediakan, dan bahwa XrEyesANDROID::mode akan menunjukkan status pelacakan.

Penggunaan yang Valid (Implisit)

• Ekstensi XR_ANDROID_eye_tracking harus diaktifkan sebelum memanggil xrGetCoarseTrackingEyesInfoANDROID
• eyeTracker harus berupa nama sebutan channel XrEyeTrackerANDROID yang valid
• getInfo harus berupa pointer ke struktur XrEyesGetInfoANDROID yang valid
• eyesOutput harus berupa pointer ke struktur XrEyesANDROID

Kode Status

Berhasil

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Kegagalan

• 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

Fungsi xrGetFineTrackingEyesInfoANDROID ditentukan sebagai: {:#xrGetFineTrackingEyesInfoANDROID} C++ XrResult xrGetFineTrackingEyesInfoANDROID( XrEyeTrackerANDROID eyeTracker, const XrEyesGetInfoANDROID* getInfo, XrEyesANDROID* eyesOutput);

Deskripsi Parameter

• eyeTracker adalah XrEyeTrackerANDROID yang sebelumnya dibuat oleh xrCreateEyeTrackerANDROID.
• getInfo adalah pointer ke XrEyesGetInfoANDROID yang digunakan untuk menentukan output yang diperlukan.
• infoOutput adalah pointer ke XrEyesANDROID yang berisi informasi mata yang ditampilkan, termasuk pose dan status. Fungsi xrGetFineTrackingEyesInfoANDROID mendapatkan informasi untuk status dan pose mata dengan presisi yang lebih tinggi daripada xrGetCoarseTrackingEyesInfoANDROID.

Runtime harus menampilkan XR_ERROR_PERMISSION_INSUFFICIENT jika aplikasi tidak memiliki izin android.permission.EYE_TRACKING_FINE.

Informasi mata di-resolve dan relatif terhadap ruang dasar pada saat panggilan ke xrGetFineTrackingEyesInfoANDROID menggunakan XrEyesGetInfoANDROID::time, XrEyesGetInfoANDROID::baseSpace.

Pada setiap waktu, posisi dan arah pose mata dilacak atau tidak dilacak. Artinya, aplikasi dapat mengharapkan bahwa XR_SPACE_LOCATION_POSITION_TRACKED_BIT dan XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT akan ditetapkan atau dihapus pada XrEyesANDROID::eyes yang disediakan, dan bahwa XrEyesANDROID::mode akan menunjukkan status pelacakan.

Penggunaan yang Valid (Implisit)

• Ekstensi XR_ANDROID_eye_tracking harus diaktifkan sebelum memanggil xrGetFineTrackingEyesInfoANDROID
• eyeTracker harus berupa nama sebutan channel XrEyeTrackerANDROID yang valid
• getInfo harus berupa pointer ke struktur XrEyesGetInfoANDROID yang valid
• eyesOutput harus berupa pointer ke struktur XrEyesANDROID

Kode Status

Berhasil

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Kegagalan

• 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

Struktur XrEyesGetInfoANDROID berisi informasi yang diperlukan untuk mengambil pose dan status mata.

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

Deskripsi Anggota

• type adalah XrStructureType dari struktur ini.
• next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur. Tidak ada struktur seperti itu yang ditentukan di OpenXR inti atau ekstensi ini.
• time adalah XrTime tempat mengevaluasi koordinat relatif terhadap baseSpace.
• baseSpace pose mata akan relatif terhadap XrSpace ini di time.

Penggunaan yang Valid (Implisit)

• Ekstensi XR_ANDROID_eye_tracking harus diaktifkan sebelum menggunakan XrEyesGetInfoANDROID
• type harus berupa XR_TYPE_EYES_GET_INFO_ANDROID
• next harus berupa NULL atau pointer yang valid ke struktur berikutnya dalam rantai struktur
• baseSpace harus berupa nama sebutan channel XrSpace yang valid

Struktur XrEyesANDROID berisi informasi tentang mata yang dilacak.

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

Deskripsi Anggota

• type adalah XrStructureType dari struktur ini.
• next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur. Tidak ada struktur seperti itu yang ditentukan di OpenXR inti atau ekstensi ini.
• eyes adalah array XrEyeANDROID untuk mata kiri dan kanan seperti yang diindeks oleh XrEyeIndexANDROID.
• mode adalah XrEyeTrackingModeANDROID untuk menunjukkan apakah mata melacak dan yang mana.

Penggunaan yang Valid (Implisit)

• Ekstensi XR_ANDROID_eye_tracking harus diaktifkan sebelum menggunakan XrEyesANDROID
• type harus berupa XR_TYPE_EYES_ANDROID
• next harus berupa NULL atau pointer yang valid ke struktur berikutnya dalam rantai struktur
• Setiap elemen eyes harus berupa struktur XrEyeANDROID yang valid
• mode harus berupa nilai XrEyeTrackingModeANDROID yang valid

Struktur XrEyeANDROID menjelaskan status, posisi, dan orientasi mata.

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

Deskripsi Anggota

• eyeState adalah XrEyeStateANDROID mata.
• pose adalah XrPosef yang menentukan posisi dan orientasi asal mata dalam frame referensi XrEyesGetInfoANDROID::baseSpace yang sesuai. Orientasi identitas di sini mewakili sumbu koordinat dengan +Z ke mata pengguna, +X ke kanan, dan +Y ke atas.

Penggunaan yang Valid (Implisit)

• Ekstensi XR_ANDROID_eye_tracking harus diaktifkan sebelum menggunakan XrEyeANDROID
• eyeState harus berupa nilai XrEyeStateANDROID yang valid

Enumerasi XrEyeStateANDROID mengidentifikasi berbagai status mata yang dilacak.

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

Enum memiliki arti berikut:

Enum	Deskripsi
XR_EYE_STATE_INVALID_ANDROID	Menunjukkan bahwa mata berada dalam status error atau tidak ada.
XR_EYE_STATE_GAZING_ANDROID	Menunjukkan bahwa mata sedang menatap.
XR_EYE_STATE_SHUT_ANDROID	Menunjukkan bahwa mata tertutup karena kedipan atau berkedip.

Enumerasi XrEyeIndexANDROID mengidentifikasi indeks mata kiri atau kanan.

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

Enum memiliki arti berikut:

Enum	Deskripsi
XR_EYE_INDEX_LEFT_ANDROID	Mata kiri.
XR_EYE_INDEX_RIGHT_ANDROID	Mata kanan.

Enumerasi XrEyeTrackingModeANDROID mengidentifikasi berbagai mode mata yang dilacak.

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;

Enum memiliki arti berikut:

Enum	Deskripsi
XR_EYE_TRACKING_MODE_NOT_TRACKING_ANDROID	Menunjukkan bahwa pelacakan mata tidak aktif.
XR_EYE_TRACKING_MODE_RIGHT_ANDROID	Menunjukkan bahwa hanya mata kanan yang melacak.
XR_EYE_TRACKING_MODE_LEFT_ANDROID	Menunjukkan bahwa hanya mata kiri yang melacak.
XR_EYE_TRACKING_MODE_BOTH_ANDROID	Menunjukkan bahwa mata kiri dan kanan sedang melacak.

Contoh kode untuk pelacakan mata

Kode contoh berikut menunjukkan cara mendapatkan informasi mata yang relatif terhadap ruang tampilan.

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

Jenis Objek Baru

• XrEyeTrackerANDROID

Konstanta Enum Baru

• XR_EYE_MAX_ANDROID

Enumerasi XrObjectType diperluas dengan:

• XR_OBJECT_TYPE_EYE_TRACKER_ANDROID

Enumerasi XrStructureType diperluas dengan:

• XR_TYPE_EYES_ANDROID
• XR_TYPE_EYE_TRACKER_CREATE_INFO_ANDROID
• XR_TYPE_EYES_GET_INFO_ANDROID
• XR_TYPE_SYSTEM_EYE_TRACKING_PROPERTIES_ANDROID

Enum Baru

• XrEyeIndexANDROID
• XrEyeStateANDROID
• XrEyeTrackingModeANDROID

Struktur Baru

• XrEyeANDROID
• XrEyesANDROID
• XrEyesGetInfoANDROID
• XrEyeTrackerCreateInfoANDROID
• XrSystemEyeTrackingPropertiesANDROID

Fungsi Baru

• xrCreateEyeTrackerANDROID
• xrDestroyEyeTrackerANDROID
• xrGetCoarseTrackingEyesInfoANDROID
• xrGetFineTrackingEyesInfoANDROID

Masalah

Histori Versi

• Revisi 1, 17-01-2025 (Kenny Vercaemer)
  • Deskripsi ekstensi awal