Android XR SDK זמין עכשיו בתצוגה מקדימה למפתחים. אנו רוצים את המשוב שלך! אפשר לפנות אלינו דרך דף התמיכה.

דף זה תורגם על ידי Cloud Translation API.

תוסף OpenXR‏ XR_ANDROID_eye_tracking

Name String

XR_ANDROID_eye_tracking

סוג התוסף

תוסף למכונה

מספר תוסף רשום

457

גרסה

תלות בתוספים ובגרסאות

OpenXR 1.0

תאריך השינוי האחרון

2025-01-17

סטטוס כתובת ה-IP

לא ידוע על תלונות על הפרת זכויות יוצרים בנושא כתובת IP.

שותפים ביצירת התוכן

ספנסר קווין (Spencer Quin), Google

Jared Finder, ‏ Google

לבנון צ'ן, Google

Kenny Vercaemer, ‏ Google

Prasanthi Gurumurthy, ‏ Google

Nihav Jain, ‏ Google

סקירה כללית

התוסף הזה מאפשר לאפליקציות לקבל את המיקום והכיוון של העיניים של המשתמש, וגם את סטטוס מעקב העיניים.

נתוני מעקב אחר תנועות העיניים מוצגים בשני מצבים: גס ומדויק. מעקב גס מספק הערכה גסה של העיניים של המשתמש, בעוד שמעקב עדין מספק הערכה מדויקת יותר. מעקב גס מיועד לאפליקציות שרוצות לספק ייצוג בסיסי של דמויות, ואילו מעקב מדויק מיועד לאפליקציות מדויקות יותר.

לצורך אינטראקציה, צריך להשתמש ב-XR_EXT_eye_gaze_interaction.

בדיקת יכולות המערכת

המבנה XrSystemEyeTrackingPropertiesANDROID מוגדר כך:

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

תיאורי חברים

type הוא XrStructureType של המבנה הזה.
next הוא NULL או הפניה למבנה הבא בשרשרת המבנים. לא מוגדרים מבנים כאלה ב-OpenXR או בהרחבה הזו.
supportsEyeTracking הוא XrBool32, שמציין אם המערכת הנוכחית תומכת במעקב אחר תנועות העיניים.

אפליקציה יכולה לבדוק אם המערכת מסוגלת לעקוב אחר תנועות העיניים על ידי קישור של מבנה XrSystemEyeTrackingPropertiesANDROID ל-XrSystemProperties בזמן הקריאה ל-xrGetSystemProperties. אם הפונקציה supportsEyeTracking מחזירה את הערך XR_FALSE, האפליקציה תקבל את הערך XR_ERROR_FEATURE_UNSUPPORTED מ-xrCreateEyeTrackerANDROID.

שימוש תקין (מרומז)

חובה להפעיל את התוסף XR_ANDROID_eye_tracking לפני שמשתמשים ב-XrSystemEyeTrackingPropertiesANDROID
הערך של type חייב להיות XR_TYPE_SYSTEM_EYE_TRACKING_PROPERTIES_ANDROID
next חייב להיות NULL או מצביע תקין להמבנה הבא בשרשרת המבנים

יצירת כינוי למעקב אחר תנועות העיניים

XR_DEFINE_HANDLE(XrEyeTrackerANDROID)

הכינוי XrEyeTrackerANDROID מייצג מכשיר למעקב אחר תנועות העיניים (eye tracker) שמאפשר לעקוב אחרי העיניים ולמפות במדויק את מה שהמשתמש מסתכל עליו.

נתוני מעקב אחר עיניים יכולים להיות מידע אישי רגיש, והם קשורים באופן הדוק לפרטיות ולשלמות האישית. מומלץ מאוד שאפליקציות שמאחסנות או מעבירות נתוני מעקב אחר תנועות העיניים תמיד יבקשו מהמשתמשים אישור פעיל וספציפי לכך.

אפשר להשתמש בכינוי הזה כדי לגשת לנתוני מעקב אחר תנועות העיניים באמצעות פונקציות אחרות בתוסף הזה.

מעקב אחר תנועות העיניים מספק ייצוג של מיקום העיניים והסטטוס שלהן בסצנה.

הפונקציה xrCreateEyeTrackerANDROID מוגדרת בתור:

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

תיאורי פרמטרים

session הוא הכינוי XrSession שבו מעקב העיניים יהיה פעיל.
createInfo הוא XrEyeTrackerCreateInfoANDROID שמשמש לציון מעקב העיניים.
eyeTracker הוא הכינוי XrEyeTrackerANDROID שהוחזר.

אפליקציה יכולה ליצור כינוי XrEyeTrackerANDROID באמצעות הפונקציה xrCreateEyeTrackerANDROID.

אם המערכת לא תומכת במעקב אחר תנועות העיניים, הערך XR_ERROR_FEATURE_UNSUPPORTED יוחזר מ-xrCreateEyeTrackerANDROID.

שימוש תקין (מרומז)

צריך להפעיל את התוסף XR_ANDROID_eye_tracking לפני שמפעילים את xrCreateEyeTrackerANDROID
session חייב להיות כינוי XrSession חוקי
createInfo חייב להיות הפניה למבנה XrEyeTrackerCreateInfoANDROID חוקי
eyeTracker חייב להיות הפניה לכינוי XrEyeTrackerANDROID

קודי החזרה

הצלחה

XR_SUCCESS
XR_SESSION_LOSS_PENDING

כישלון

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

המבנה XrEyeTrackerCreateInfoANDROID מוגדר כך:

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

תיאורי חברים

type הוא XrStructureType של המבנה הזה.
next הוא NULL או הפניה למבנה הבא בשרשרת המבנים. לא מוגדרים מבנים כאלה ב-OpenXR או בהרחבה הזו.

המבנה XrEyeTrackerCreateInfoANDROID מתאר את המידע הנדרש ליצירת כתובת XrEyeTrackerANDROID.

שימוש תקין (מרומז)

חובה להפעיל את התוסף XR_ANDROID_eye_tracking לפני שמשתמשים ב-XrEyeTrackerCreateInfoANDROID
הערך של type חייב להיות XR_TYPE_EYE_TRACKER_CREATE_INFO_ANDROID
next חייב להיות NULL או מצביע תקין להמבנה הבא בשרשרת המבנים

הפונקציה xrDestroyEyeTrackerANDROID מוגדרת כך:

XrResult xrDestroyEyeTrackerANDROID(
    XrEyeTrackerANDROID                         eyeTracker);

תיאורי פרמטרים

eyeTracker הוא XrEyeTrackerANDROID שנוצר בעבר על ידי xrCreateEyeTrackerANDROID.

הפונקציה xrDestroyEyeTrackerANDROID משחררת את eyeTracker ואת המשאבים הבסיסיים כשמסיימים את חוויית המעקב אחר העיניים.

שימוש תקין (מרומז)

צריך להפעיל את התוסף XR_ANDROID_eye_tracking לפני שמפעילים את xrDestroyEyeTrackerANDROID
eyeTracker חייב להיות כינוי XrEyeTrackerANDROID תקין.

בטיחות בשרשור

חובה לסנכרן באופן חיצוני את הגישה ל-eyeTracker ולכל כינויים משניים

קודי החזרה

הצלחה

XR_SUCCESS

כישלון

XR_ERROR_FUNCTION_UNSUPPORTED
XR_ERROR_HANDLE_INVALID

אחזור פרטי העיניים

הפונקציה xrGetCoarseTrackingEyesInfoANDROID מוגדרת כך:

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

תיאורי פרמטרים

eyeTracker הוא XrEyeTrackerANDROID שנוצר בעבר על ידי xrCreateEyeTrackerANDROID.
getInfo הוא הפניה ל-XrEyesGetInfoANDROID שמשמשת לציון הפלט הנדרש.
infoOutput הוא הפניה ל-XrEyesANDROID שמכיל את המידע על העיניים שהוחזר, כולל תנוחות ומצבים.

הפונקציה xrGetCoarseTrackingEyesInfoANDROID מקבלת את המידע על מצבי העיניים והתנוחות שלהם באופן שמגן על פרטיות המשתמשים.

סביבת זמן הריצה חייבת להחזיר את הערך XR_ERROR_PERMISSION_INSUFFICIENT אם לאפליקציה אין את ההרשאה android.permission.EYE_TRACKING_COARSE.

פרטי העיניים ממוינים ביחס למרחב הבסיס בזמן הקריאה ל-xrGetCoarseTrackingEyesInfoANDROID באמצעות XrEyesGetInfoANDROID::time, XrEyesGetInfoANDROID::baseSpace.

בכל שלב, מתבצע מעקב אחרי המיקום והכיוון של תנוחת העיניים, או שהמעקב אחריהם מופסק. המשמעות היא שאפליקציות יכולות לצפות שהערכי XR_SPACE_LOCATION_POSITION_TRACKED_BIT ו-XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT יוגדרו או יימחקו ב-XrEyesANDROID::eyes שסופק, ושהערך של XrEyesANDROID::mode יציין את מצבי המעקב.

שימוש תקין (מרומז)

צריך להפעיל את התוסף XR_ANDROID_eye_tracking לפני שמפעילים את xrGetCoarseTrackingEyesInfoANDROID
eyeTracker חייב להיות כינוי XrEyeTrackerANDROID חוקי
getInfo חייב להיות הפניה למבנה חוקי של XrEyesGetInfoANDROID
eyesOutput חייב להיות הפניה למבנה XrEyesANDROID

קודי החזרה

הצלחה

XR_SUCCESS
XR_SESSION_LOSS_PENDING

כישלון

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

הפונקציה xrGetFineTrackingEyesInfoANDROID מוגדרת כך: {:#xrGetFineTrackingEyesInfoANDROID} C++ XrResult xrGetFineTrackingEyesInfoANDROID( XrEyeTrackerANDROID eyeTracker, const XrEyesGetInfoANDROID* getInfo, XrEyesANDROID* eyesOutput);

תיאורי פרמטרים

eyeTracker הוא XrEyeTrackerANDROID שנוצר בעבר על ידי xrCreateEyeTrackerANDROID.
getInfo הוא הפניה ל-XrEyesGetInfoANDROID שמשמשת לציון הפלט הנדרש.
infoOutput הוא הפניה ל-XrEyesANDROID שמכיל את המידע על העיניים שהוחזר, כולל תנוחות ומצבים. הפונקציה xrGetFineTrackingEyesInfoANDROID מקבלת את המידע על מצבי העיניים והתנוחות שלהם בדיוק גבוה יותר מאשר xrGetCoarseTrackingEyesInfoANDROID.

סביבת זמן הריצה חייבת להחזיר את הערך XR_ERROR_PERMISSION_INSUFFICIENT אם לאפליקציה אין את ההרשאה android.permission.EYE_TRACKING_FINE.

פרטי העיניים ממוינים ביחס למרחב הבסיס בזמן הקריאה ל-xrGetFineTrackingEyesInfoANDROID באמצעות XrEyesGetInfoANDROID::time, XrEyesGetInfoANDROID::baseSpace.

שימוש תקין (מרומז)

צריך להפעיל את התוסף XR_ANDROID_eye_tracking לפני שמפעילים את xrGetFineTrackingEyesInfoANDROID
eyeTracker חייב להיות כינוי XrEyeTrackerANDROID חוקי
getInfo חייב להיות הפניה למבנה חוקי של XrEyesGetInfoANDROID
eyesOutput חייב להיות הפניה למבנה XrEyesANDROID

קודי החזרה

הצלחה

XR_SUCCESS
XR_SESSION_LOSS_PENDING

כישלון

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

המבנה XrEyesGetInfoANDROID מכיל את המידע הנדרש כדי לאחזר את המצבים והתנוחות של העיניים.

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

תיאורי חברים

type הוא XrStructureType של המבנה הזה.
next הוא NULL או הפניה למבנה הבא בשרשרת המבנים. לא מוגדרים מבנים כאלה ב-OpenXR או בהרחבה הזו.
time הוא XrTime שבו צריך להעריך את הקואורדינטות ביחס ל-baseSpace.
baseSpace תנוחת העין תהיה ביחס ל-XrSpace הזה ב-time.

שימוש תקין (מרומז)

צריך להפעיל את התוסף XR_ANDROID_eye_tracking לפני שמשתמשים ב-XrEyesGetInfoANDROID
הערך של type חייב להיות XR_TYPE_EYES_GET_INFO_ANDROID
next חייב להיות NULL או מצביע תקין להמבנה הבא בשרשרת המבנים
baseSpace חייב להיות כינוי XrSpace חוקי

המבנה XrEyesANDROID מכיל מידע על העיניים שבמעקב.

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

תיאורי חברים

type הוא XrStructureType של המבנה הזה.
next הוא NULL או הפניה למבנה הבא בשרשרת המבנים. לא מוגדרים מבנים כאלה ב-OpenXR או בהרחבה הזו.
eyes הוא מערך של XrEyeANDROID עבור העיניים השמאלית והימנית, כפי שמסומנים ב-XrEyeIndexANDROID.
mode הוא XrEyeTrackingModeANDROID כדי לציין אם העיניים עוקבות אחרי עצם מסוים ואילו עיניים עוקבות.

שימוש תקין (מרומז)

חובה להפעיל את התוסף XR_ANDROID_eye_tracking לפני שמשתמשים ב-XrEyesANDROID
הערך של type חייב להיות XR_TYPE_EYES_ANDROID
הערך של next חייב להיות NULL או מצביע תקין להמבנה הבא בשרשרת המבנים
כל אלמנט של eyes חייב להיות מבנה חוקי של XrEyeANDROID
הערך של mode חייב להיות ערך חוקי של XrEyeTrackingModeANDROID

המבנה XrEyeANDROID מתאר את המצב, המיקום והכיוון של עין.

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

תיאורי חברים

eyeState הוא XrEyeStateANDROID של עין.
pose הוא XrPosef שמגדיר את המיקום והכיוון של המקור של עין בתוך מסגרת העזר של XrEyesGetInfoANDROID::baseSpace התואם. כאן, כיוון הזהות מייצג צירי קואורדינטות עם +Z לכיוון העיניים של המשתמש, +X לימין ו-+Y למעלה.

שימוש תקין (מרומז)

חובה להפעיל את התוסף XR_ANDROID_eye_tracking לפני שמשתמשים ב-XrEyeANDROID
הערך של eyeState חייב להיות ערך חוקי של XrEyeStateANDROID

המספרה XrEyeStateANDROID מזהה את המצבים השונים של העיניים במעקב.

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

למאפייני enum יש את המשמעויות הבאות:

Enum	תיאור
`XR_EYE_STATE_INVALID_ANDROID`	מציין שהעין נמצאת במצב שגיאה או לא קיימת.
`XR_EYE_STATE_GAZING_ANDROID`	מציין שהעין מביטה.
`XR_EYE_STATE_SHUT_ANDROID`	מציין שהעין סגורה בגלל מצמוץ או קריצה.

המספר XrEyeIndexANDROID מזהה את האינדקס של העין השמאלית או הימנית.

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

למאפייני enum יש את המשמעויות הבאות:

Enum	תיאור
`XR_EYE_INDEX_LEFT_ANDROID`	העין השמאלית.
`XR_EYE_INDEX_RIGHT_ANDROID`	העין הימנית.

המספר XrEyeTrackingModeANDROID מאפשר לזהות את המצבים השונים של מעקב העיניים.

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 יש את המשמעויות הבאות:

Enum	תיאור
`XR_EYE_TRACKING_MODE_NOT_TRACKING_ANDROID`	מציין שמעקב העיניים לא פעיל.
`XR_EYE_TRACKING_MODE_RIGHT_ANDROID`	מציין שרק העין הימנית עוקבת.
`XR_EYE_TRACKING_MODE_LEFT_ANDROID`	מציין שרק העין הימנית עוקבת.
`XR_EYE_TRACKING_MODE_BOTH_ANDROID`	מציין שגם העין השמאלית וגם העין הימנית עוקבות.

קוד לדוגמה למעקב אחר תנועות עיניים

דוגמת הקוד הבאה מראה איך לקבל מידע על העיניים ביחס למרחב התצוגה.

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