Android XR for OpenXR | Android Developers

Android XR SDK telah mencapai Pratinjau Developer 3, dan kami ingin mendengar masukan Anda. Coba fitur-fitur yang ada, dan buka halaman dukungan kami untuk menghubungi kami.

XR_ANDROID_eye_tracking

String Nama

XR_ANDROID_eye_tracking

Jenis Ekstensi

Ekstensi instance

Nomor Ekstensi Terdaftar

457

Revisi

Status Ratifikasi

Tidak diratifikasi

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 gerak mata.

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

Untuk interaksi, XR_EXT_eye_gaze_interaction harus digunakan.

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 dalam 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 memperluas XrSystemProperties dengan struktur XrSystemEyeTrackingPropertiesANDROID saat memanggil xrGetSystemProperties .

Jika dan hanya jika runtime menampilkan XR_FALSE untuk supportsEyeTracking , runtime harus menampilkan XR_ERROR_FEATURE_UNSUPPORTED dari xrCreateEyeTrackerANDROID .

Penggunaan yang Valid (Implisit)

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

Membuat handle pelacak mata

XR_DEFINE_HANDLE(XrEyeTrackerANDROID)

Handler XrEyeTrackerANDROID merepresentasikan pelacak mata untuk melacak mata dan memetakan secara akurat ke mana pengguna melihat.

Data pelacakan mata adalah informasi pribadi yang sensitif dan terkait erat dengan privasi dan integritas pribadi. Sangat disarankan agar aplikasi yang menyimpan atau mentransfer data pelacakan mata selalu meminta persetujuan aktif dan spesifik dari pengguna untuk melakukannya.

Aplikasi menggunakan handle ini untuk mengakses data pelacakan mata menggunakan fungsi lain dalam ekstensi ini.

Pelacakan mata memberikan representasi pose dan status mata dalam adegan.

Fungsi xrCreateEyeTrackerANDROID ditentukan sebagai:

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

Deskripsi Parameter

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

Aplikasi membuat handle XrEyeTrackerANDROID menggunakan fungsi xrCreateEyeTrackerANDROID.

Jika sistem tidak mendukung pelacakan mata, runtime harus menampilkan XR_ERROR_FEATURE_UNSUPPORTED dari xrCreateEyeTrackerANDROID .

Penggunaan yang Valid (Implisit)

Ekstensi XR_ANDROID_eye_tracking harus diaktifkan sebelum memanggil xrCreateEyeTrackerANDROID
session harus berupa handle XrSession yang valid
createInfo harus berupa pointer ke struktur XrEyeTrackerCreateInfoANDROID yang valid
eyeTracker harus berupa pointer ke handle XrEyeTrackerANDROID

Kode Status

Berhasil

XR_SUCCESS
XR_SESSION_LOSS_PENDING

Kegagalan

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

Struktur XrEyeTrackerCreateInfoANDROID ditentukan sebagai:

typedef struct XrEyeTrackerCreateInfoANDROID {
    XrStructureType    type;
    const 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 dalam OpenXR inti atau ekstensi ini.

Struktur XrEyeTrackerCreateInfoANDROID menjelaskan informasi untuk membuat handle XrEyeTrackerANDROID.

Penggunaan yang Valid (Implisit)

Ekstensi XR_ANDROID_eye_tracking harus diaktifkan sebelum menggunakan XrEyeTrackerCreateInfoANDROID
type harus 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 melepaskan eyeTracker dan resource pokok saat selesai menggunakan pengalaman pelacakan mata.

Penggunaan yang Valid (Implisit)

Ekstensi XR_ANDROID_eye_tracking harus diaktifkan sebelum memanggil xrDestroyEyeTrackerANDROID
eyeTracker harus berupa handle XrEyeTrackerANDROID yang valid

Keamanan Thread

Akses ke eyeTracker , dan semua handle turunannya, 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 memberikan info guna mengkueri pose dan status mata.
eyesOutput adalah pointer ke XrEyesANDROID yang berisi informasi mata yang ditampilkan, termasuk pose dan status.

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

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

Pose mata dinyatakan dalam XrEyesGetInfoANDROID :: baseSpace di XrEyesGetInfoANDROID :: time .

Setiap saat, posisi dan arah pose mata dilacak atau tidak dilacak. Artinya, runtime harus menetapkan XR_SPACE_LOCATION_POSITION_TRACKED_BIT dan XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT atau menghapus XR_SPACE_LOCATION_POSITION_TRACKED_BIT dan XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT pada XrEyesANDROID :: eyes yang diberikan, serta menetapkan XrEyesANDROID :: mode untuk menunjukkan status pelacakan.

Penggunaan yang Valid (Implisit)

Ekstensi XR_ANDROID_eye_tracking harus diaktifkan sebelum memanggil xrGetCoarseTrackingEyesInfoANDROID
eyeTracker harus berupa handle 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_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

Fungsi xrGetFineTrackingEyesInfoANDROID ditentukan sebagai:

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.
eyesOutput adalah pointer ke XrEyesANDROID yang berisi informasi mata yang ditampilkan, termasuk pose dan status.

Fungsi xrGetFineTrackingEyesInfoANDROID mendapatkan informasi untuk pose dan status 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 diselesaikan dan relatif terhadap ruang dasar pada saat panggilan ke xrGetFineTrackingEyesInfoANDROID menggunakan XrEyesGetInfoANDROID :: time , XrEyesGetInfoANDROID :: baseSpace . Runtime harus menyelesaikan lokasi yang ditentukan oleh XrEyesGetInfoANDROID :: baseSpace pada saat panggilan.

Penggunaan yang Valid (Implisit)

Ekstensi XR_ANDROID_eye_tracking harus diaktifkan sebelum memanggil xrGetFineTrackingEyesInfoANDROID
eyeTracker harus berupa handle 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_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

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

typedef struct XrEyesGetInfoANDROID {
    XrStructureType    type;
    const 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 dalam OpenXR inti atau ekstensi ini.
time adalah XrTime untuk mengevaluasi koordinat relatif terhadap baseSpace .
baseSpace adalah XrSpace yang menjadi acuan pose mata pada time .

Penggunaan yang Valid (Implisit)

Ekstensi XR_ANDROID_eye_tracking harus diaktifkan sebelum menggunakan XrEyesGetInfoANDROID
type harus XR_TYPE_EYES_GET_INFO_ANDROID
next harus berupa NULL atau pointer yang valid ke struktur berikutnya dalam rantai struktur
baseSpace harus berupa handle 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 dalam OpenXR inti atau ekstensi ini.
eyes adalah array XrEyeANDROID , berukuran XR_EYE_MAX_ANDROID , untuk mata kiri dan kanan yang diindeks oleh XrEyeIndexANDROID .
mode adalah XrEyeTrackingModeANDROID yang menunjukkan mata mana yang saat ini dilacak.

Penggunaan yang Valid (Implisit)

Ekstensi XR_ANDROID_eye_tracking harus diaktifkan sebelum menggunakan XrEyesANDROID
type harus XR_TYPE_EYES_ANDROID
next harus berupa NULL atau pointer yang valid ke struktur berikutnya dalam rantai struktur
Setiap elemen tertentu dari 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.
eyePose adalah XrPosef yang menentukan posisi dan orientasi pupil mata dalam frame referensi XrEyesGetInfoANDROID yang sesuai :: baseSpace . Orientasi identitas di sini merepresentasikan 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,
    XR_EYE_STATE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrEyeStateANDROID;

Enum memiliki arti berikut:

Deskripsi Enum

XR_EYE_STATE_INVALID_ANDROID

Menunjukkan bahwa mata dalam status error atau tidak ada.

XR_EYE_STATE_GAZING_ANDROID

Menunjukkan bahwa mata sedang melihat.

XR_EYE_STATE_SHUT_ANDROID

Menunjukkan bahwa mata saat ini tertutup karena berkedip atau mengedipkan mata.

Enumerasi XrEyeIndexANDROID mengidentifikasi indeks mata kiri atau kanan.

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

Enum memiliki arti berikut:

Deskripsi Enum

XR_EYE_INDEX_LEFT_ANDROID

Mata kiri.

XR_EYE_INDEX_RIGHT_ANDROID

Mata kanan.

Enumerasi XrEyeTrackingModeANDROID mengidentifikasi berbagai status 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,
    XR_EYE_TRACKING_MODE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrEyeTrackingModeANDROID;

Enum memiliki arti berikut:

Deskripsi Enum

XR_EYE_TRACKING_MODE_NOT_TRACKING_ANDROID

Menunjukkan bahwa pelacakan gerak mata saat ini tidak aktif.

XR_EYE_TRACKING_MODE_RIGHT_ANDROID

Menunjukkan bahwa hanya mata kanan yang dilacak.

XR_EYE_TRACKING_MODE_LEFT_ANDROID

Menunjukkan bahwa hanya mata kiri yang dilacak.

XR_EYE_TRACKING_MODE_BOTH_ANDROID

Menunjukkan bahwa mata kiri dan kanan sedang melacak.

Contoh kode untuk pelacakan mata

Contoh kode berikut menunjukkan cara mendapatkan informasi mata 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

Struktur Baru

XrEyeANDROID
XrEyeTrackerCreateInfoANDROID
XrEyesANDROID
XrEyesGetInfoANDROID
Memperluas XrSystemProperties :
- XrSystemEyeTrackingPropertiesANDROID

Enum Baru

XrEyeIndexANDROID
XrEyeStateANDROID
XrEyeTrackingModeANDROID

Konstanta Enum Baru

XR_ANDROID_EYE_TRACKING_EXTENSION_NAME
XR_ANDROID_eye_tracking_SPEC_VERSION
XR_EYE_MAX_ANDROID
Memperluas XrObjectType :
- XR_OBJECT_TYPE_EYE_TRACKER_ANDROID
Memperluas 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

Masalah

Histori Versi

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