The Android XR SDK is now available in Developer Preview. We want your feedback! Visit our support page to reach out.

Halaman ini diterjemahkan oleh Cloud Translation API.

Ekstensi OpenXR XR_ANDROID_avatar_eyes

String Nama

XR_ANDROID_avatar_eyes

Jenis Ekstensi

Ekstensi instance

Registered Extension Number

457

Revisi

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)

Ekstensi XR_ANDROID_avatar_eyes harus diaktifkan sebelum menggunakan XrSystemAvatarEyesPropertiesANDROID
type harus berupa XR_TYPE_SYSTEM_AVATAR_EYES_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.

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 handle XrEyeTrackerANDROID yang ditampilkan.

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)

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

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 handle XrEyeTrackerANDROID.

Penggunaan yang Valid (Implisit)

Ekstensi XR_ANDROID_avatar_eyes 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_avatar_eyes harus diaktifkan sebelum memanggil xrDestroyEyeTrackerANDROID
eyeTracker harus berupa handle 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 xrGetEyesInfoANDROID ditentukan sebagai:

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

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

Ekstensi XR_ANDROID_avatar_eyes harus diaktifkan sebelum memanggil xrGetEyesInfoANDROID
eyeTracker harus berupa handle XrEyeTrackerANDROID yang valid
getInfo harus berupa pointer ke struktur XrEyesGetInfoANDROID yang valid
infoOutput 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

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)

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

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

Ekstensi XR_ANDROID_avatar_eyes 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, 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

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_AVATAR_EYES_PROPERTIES_ANDROID

Enum Baru

XrEyeIndexANDROID
XrEyeStateANDROID
XrEyeTrackingModeANDROID

Struktur Baru

XrEyeANDROID
XrEyesANDROID
XrEyesGetInfoANDROID
XrEyeTrackerCreateInfoANDROID
XrSystemAvatarEyesPropertiesANDROID

Fungsi Baru

xrCreateEyeTrackerANDROID
xrDestroyEyeTrackerANDROID
xrGetEyesInfoANDROID

Masalah

Histori Versi

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