Ekstensi OpenXR XR_ANDROID_eye_tracking

String Nama

XR_ANDROID_eye_tracking

Jenis Ekstensi

Ekstensi instance

Nomor Ekstensi Terdaftar

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

Data pelacakan mata disediakan dalam dua mode: kasar dan halus. Pelacakan kasar memberikan estimasi kasar mata pengguna, sedangkan pelacakan halus memberikan estimasi 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.

Memeriksa kemampuan sistem

Struktur XrSystemEyeTrackingPropertiesANDROID ditentukan sebagai:

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

Deskripsi Anggota

  • type adalah XrStructureType 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 menggabungkan struktur XrSystemEyeTrackingPropertiesANDROID ke XrSystemProperties saat memanggil xrGetSystemProperties. Jika supportsEyeTracking menampilkan XR_FALSE, maka aplikasi akan menerima XR_ERROR_FEATURE_UNSUPPORTED dari xrCreateEyeTrackerANDROID.

Penggunaan yang Valid (Implisit)

Membuat handle pelacak mata

XR_DEFINE_HANDLE(XrEyeTrackerANDROID)

Gagang XrEyeTrackerANDROID merepresentasikan 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. Sangat disarankan agar aplikasi yang menyimpan atau mentransfer data pelacakan mata selalu meminta persetujuan aktif dan spesifik dari pengguna untuk melakukannya.

Handle ini dapat digunakan 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

Aplikasi dapat membuat handle XrEyeTrackerANDROID menggunakan fungsi xrCreateEyeTrackerANDROID.

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

Penggunaan yang Valid (Implisit)

Kode yang Ditampilkan

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

Fungsi xrDestroyEyeTrackerANDROID ditentukan sebagai: 

XrResult xrDestroyEyeTrackerANDROID(
    XrEyeTrackerANDROID                         eyeTracker);

Deskripsi Parameter

Fungsi xrDestroyEyeTrackerANDROID melepaskan eyeTracker dan resource pokok saat selesai menggunakan pengalaman pelacakan mata.

Penggunaan yang Valid (Implisit)

Keamanan Thread

  • Akses ke eyeTracker, dan semua nama sebutan turunannya, harus disinkronkan secara eksternal

Kode yang Ditampilkan

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

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 diselesaikan dan relatif terhadap ruang dasar pada saat panggilan ke xrGetCoarseTrackingEyesInfoANDROID menggunakan XrEyesGetInfoANDROID::time, XrEyesGetInfoANDROID::baseSpace.

Setiap saat, 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 disetel atau dihapus pada XrEyesANDROID::eyes yang diberikan, dan XrEyesANDROID::mode akan menunjukkan status pelacakan.

Penggunaan yang Valid (Implisit)

Kode yang Ditampilkan

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 didefinisikan sebagai: 

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

Deskripsi Parameter

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.

Setiap saat, 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 disetel atau dihapus pada XrEyesANDROID::eyes yang diberikan, dan XrEyesANDROID::mode akan menunjukkan status pelacakan.

Penggunaan yang Valid (Implisit)

Kode yang Ditampilkan

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 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 pose mata akan relatif terhadap XrSpace ini pada time.

Penggunaan yang Valid (Implisit)

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 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 untuk mata kiri dan kanan yang diindeks oleh XrEyeIndexANDROID.
  • mode adalah XrEyeTrackingModeANDROID untuk menunjukkan apakah mata melacak dan mata mana yang melacak.

Penggunaan yang Valid (Implisit)

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 merepresentasikan sumbu koordinat dengan +Z ke mata pengguna, +X ke kanan, dan +Y ke atas.

Penggunaan yang Valid (Implisit)

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 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 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
} XrEyeIndexANDROID;

Enum memiliki arti berikut:

Enum

Deskripsi

XR_EYE_INDEX_LEFT_ANDROID

Mata kiri.

XR_EYE_INDEX_RIGHT_ANDROID

Mata kanan.

Pencacahan 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 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

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

Struktur Baru

Fungsi Baru

Masalah

Histori Versi

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

OpenXR™ dan logo OpenXR adalah merek dagang yang dimiliki oleh The Khronos Group Inc. dan terdaftar sebagai merek dagang di China, Uni Eropa, Jepang, dan Inggris Raya.