תוסף OpenXR‏ XR_ANDROID_eye_tracking

מחרוזת שם

XR_ANDROID_eye_tracking

סוג התוסף

תוסף למכונה

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

457

גרסה

1

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

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_DEFINE_HANDLE(XrEyeTrackerANDROID)

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

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

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

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

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

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

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

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

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

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

קודי החזרה

הצלחה

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

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

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

XrResult xrDestroyEyeTrackerANDROID(
    XrEyeTrackerANDROID                         eyeTracker);

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

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

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

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

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

קודי החזרה

הצלחה

  • XR_SUCCESS

כישלון

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

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

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

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

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

הפונקציה 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_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);

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

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

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

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

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

קודי החזרה

הצלחה

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

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

המבנה 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 כדי לציין אם העיניים עוקבות אחרי תנועה ואילו מהן.

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

המבנה 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));

סוגי אובייקטים חדשים

קבועים חדשים של Enum

  • XR_EYE_MAX_ANDROID

המניין XrObjectType מורחב עם:

  • XR_OBJECT_TYPE_EYE_TRACKER_ANDROID

המניין XrStructureType מורחב עם:

  • 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 חדשים

מבנים חדשים

פונקציות חדשות

בעיות

היסטוריית הגרסאות

  • גרסה 1, 17 בינואר 2025 (Kenny Vercaemer)
    • תיאור ראשוני של התוסף

OpenXR™‎ והלוגו של OpenXR הם סימנים מסחריים בבעלות The Khronos Group Inc., והם רשומים כסימנים מסחריים בסין, באיחוד האירופי, ביפן ובבריטניה.