Ekstensi OpenXR XR_ANDROID_avatar_eyes

String Nama

XR_ANDROID_avatar_eyes

Jenis Ekstensi

Ekstensi instance

Registered Extension Number

457

Revisi

1

Dependensi Ekstensi dan Versi

OpenXR 1.0

Tanggal Terakhir Diubah

2024-09-30

Status IP

Tidak ada klaim IP yang diketahui.

Kontributor

Spencer Quin, Google

Jared Finder, Google

Levana Chen, Google

Ringkasan

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

Ekstensi ini dimaksudkan untuk membuat pose mata dan representasi status untuk avatar lebih realistis. Untuk tujuan tersebut:

  • Hal ini memungkinkan status yang tidak dilacak seperti berkedip.
  • Hal ini memungkinkan pelacakan monokular atau binokular.

Ekstensi ini tidak boleh digunakan untuk tujuan pelacakan mata lainnya. Untuk interaksi, XR_EXT_eye_gaze_interaction harus digunakan.

Pelacak Mata

Pelacak mata adalah perangkat penginderaan yang melacak mata dan memetakan secara akurat tempat pengguna melihat. Tujuan utama ekstensi ini adalah memetakan tatapan pengguna ke avatar mereka dalam tampilan virtual.

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.

  • Aplikasi akan menerima XR_ERROR_PERMISSION_INSUFFICIENT saat mencoba membuat pelacak pandangan mata aktif hingga aplikasi diizinkan mengakses pelacak pandangan mata.

Memeriksa kemampuan sistem

Aplikasi dapat memeriksa apakah sistem mendukung mata avatar dengan mengaitkan struktur XrSystemAvatarEyesPropertiesANDROID ke XrSystemProperties saat memanggil xrGetSystemProperties. Jika supportsAvatarEyes menampilkan XR_FALSE, aplikasi akan menerima XR_ERROR_FEATURE_UNSUPPORTED dari xrCreateEyeTrackerANDROID.

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

Deskripsi Anggota

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

Penggunaan yang Valid (Implisit)

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.

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

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

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 semacam itu yang ditentukan di 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 merilis eyeTracker dan resource yang mendasarinya setelah selesai dengan pengalaman pelacakan mata.

Penggunaan yang Valid (Implisit)

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 xrGetEyesInfoANDROID ditentukan sebagai:

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

Deskripsi Parameter

Fungsi xrGetEyesInfoANDROID mendapatkan informasi untuk status dan pose mata.

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

Pada setiap waktu, posisi dan arah pose mata dilacak atau tidak dilacak. Ini berarti 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)

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

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

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 semacam 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 sedang melacak dan yang mana.

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

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

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_AVATAR_EYES_PROPERTIES_ANDROID

Enum Baru

Struktur Baru

Fungsi Baru

Masalah

Histori Versi

  • Revisi 1, 04-09-2024 (Levana Chen)
    • Deskripsi ekstensi awal