XR_ANDROID_eye_tracking

מחרוזת שם

XR_ANDROID_eye_tracking

סוג התוסף

תוסף למכונה

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

457

גרסה

1

סטטוס האישור

לא אושר

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

OpenXR 1.0

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

2025-01-17

סטטוס IP

אין תלונות ידועות על הפרת קניין רוחני.

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

Spencer Quin, Google
Jared Finder, Google
Levana Chen, Google
Kenny Vercaemer, Google
Prasanthi Gurumurthy, Google
Nihav Jain, Google

סקירה כללית

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

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

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

הרשאות

אפליקציות ל-Android חייבות לכלול במניפסט את ההרשאה android.permission.EYE_TRACKING_COARSE או android.permission.EYE_TRACKING_FINE. ההרשאות האלה נחשבות להרשאות מסוכנות. האפליקציה חייבת לבקש את ההרשאה בזמן הריצה כדי להשתמש בפונקציות האלה:

(רמת הגנה: מסוכן)

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

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

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

תיאורי חברים

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

אפליקציה יכולה לבדוק אם המערכת מסוגלת לבצע מעקב עיניים על ידי הרחבת XrSystemProperties באמצעות המבנה XrSystemEyeTrackingPropertiesANDROID כשקוראים ל-xrGetSystemProperties .

אם ורק אם זמן ריצה מחזיר את הערך XR_FALSE עבור supportsEyeTracking , זמן הריצה חייב להחזיר את הערך XR_ERROR_FEATURE_UNSUPPORTED מ-xrCreateEyeTrackerANDROID .

שימוש תקין (משתמע)

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

XR_DEFINE_HANDLE(XrEyeTrackerANDROID)

ה-handle‏ XrEyeTrackerANDROID מייצג מעקב עיניים, וממפה במדויק את המקום שאליו המשתמש מסתכל.

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

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

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

הפונקציה 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_FEATURE_UNSUPPORTED
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

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

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

תיאורי חברים

  • ‫type הוא ה-XrStructureType של המבנה הזה.
  • ‫next הוא NULL או מצביע למבנה הבא בשרשרת מבנים. מבנים כאלה לא מוגדרים ב-OpenXR או בתוסף הזה.

המבנה XrEyeTrackerCreateInfoANDROID מתאר את המידע ליצירת נקודת אחיזה (handle) מסוג XrEyeTrackerANDROID.

שימוש תקין (משתמע)

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

XrResult xrDestroyEyeTrackerANDROID(
    XrEyeTrackerANDROID                         eyeTracker);

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

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

שימוש תקין (משתמע)

Thread Safety

  • הגישה אל eyeTracker , ואל כל נקודות האחיזה הצאצאות, חייבת להיות מסונכרנת באופן חיצוני

קודי החזרה

הצלחה

  • XR_SUCCESS

נכשל

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

מתבצעת קבלת מידע על העיניים

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

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

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

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

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

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

תנוחות העיניים מבוטאות ב-XrEyesGetInfoANDROID :: baseSpace ב-XrEyesGetInfoANDROID :: time .

בכל שלב, המיקום והכיוון של תנוחת העיניים נמצאים במעקב או לא. כלומר, זמן הריצה חייב להגדיר גם את XR_SPACE_LOCATION_POSITION_TRACKED_BIT וגם את XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT או לנקות גם את 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_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_PERMISSION_INSUFFICIENT
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

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

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

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

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

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

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

בכל שלב, המיקום והכיוון של תנוחת העיניים נמצאים במעקב או לא. כלומר, זמן הריצה חייב להגדיר גם את XR_SPACE_LOCATION_POSITION_TRACKED_BIT וגם את XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT או לנקות גם את 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_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_PERMISSION_INSUFFICIENT
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

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

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

תיאורי חברים

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

שימוש תקין (משתמע)

  • ‫ חובה להפעיל את התוסף 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 בגודל XR_EYE_MAX_ANDROID לעין שמאל ועין ימין, לפי האינדקס של XrEyeIndexANDROID .
  • ‫mode הוא XrEyeTrackingModeANDROID שמציין אחרי איזו מהעיניים מתבצע מעקב כרגע.

שימוש תקין (משתמע)

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

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

תיאורי חברים

  • ‫eyeState הוא ה-XrEyeStateANDROID של העין.
  • ‫eyePose הוא 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,
    XR_EYE_STATE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrEyeStateANDROID;

אלה המשמעויות של ה-enums:

תיאור הטיפוס בן המנייה (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,
    XR_EYE_INDEX_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrEyeIndexANDROID;

אלה המשמעויות של ה-enums:

תיאור הטיפוס בן המנייה (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,
    XR_EYE_TRACKING_MODE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrEyeTrackingModeANDROID;

אלה המשמעויות של ה-enums:

תיאור הטיפוס בן המנייה (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

מציין שגם העין השמאלית וגם העין הימנית עוקבות.

#define XR_EYE_MAX_ANDROID                2

‫XR_EYE_MAX_ANDROID הוא המספר המקסימלי של עיניים שעבורן מדווחים נתוני XrEyeANDROID.

קוד לדוגמה למעקב עיניים

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

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

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

פקודות חדשות

מבנים חדשים

ערכי Enums חדשים

קבועי Enum חדשים

  • XR_ANDROID_EYE_TRACKING_EXTENSION_NAME
  • XR_ANDROID_eye_tracking_SPEC_VERSION
  • XR_EYE_MAX_ANDROID

  • הרחבה של XrObjectType :

    • XR_OBJECT_TYPE_EYE_TRACKER_ANDROID

  • הרחבה של XrStructureType :

    • XR_TYPE_EYES_ANDROID
    • XR_TYPE_EYES_GET_INFO_ANDROID
    • XR_TYPE_EYE_TRACKER_CREATE_INFO_ANDROID
    • XR_TYPE_SYSTEM_EYE_TRACKING_PROPERTIES_ANDROID

בעיות

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

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

    • תיאור התוסף הראשוני