תוסף OpenXR‏ XR_ANDROID_eye_tracking

מחרוזת שם

XR_ANDROID_eye_tracking

סוג התוסף

Instance extension

מספר שלוחה רשום

457

Revision

1

תלות בתוסף ובגרסה

OpenXR 1.0

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

2025-01-17

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

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

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

ספנסר קווין, 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)

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

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

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

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

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

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

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

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

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

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

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

קודי החזרה

הצלחה

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Failure

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

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

Thread Safety

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

קודי החזרה

הצלחה

  • XR_SUCCESS

Failure

  • 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

Failure

  • 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 מוגדרת כך: 

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

Failure

  • 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 שמציין אם העיניים עוקבות ואילו מהן.

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

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

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

New Enum Constants

  • 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

New Enums

מבנים חדשים

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

בעיות

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

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

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