XR_ANDROID_eye_tracking

מחרוזת שם

XR_ANDROID_eye_tracking

סוג התוסף

הרחבת המכונה

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

457

Revision

1

סטטוס האישור

לא אושר

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

OpenXR 1.0

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

2025-01-17

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

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

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

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

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

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

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

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

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

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

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

קודי החזרה

הצלחה

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Failure

  • 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 מתאר את המידע ליצירת נקודת אחיזה 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);

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

  • 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

Failure

  • 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

Failure

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

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

  • כדי להשתמש ב-XrEyeANDROID, חובה להפעיל את התוסף XR_ANDROID_eye_tracking
  • הערך של 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;

המשמעויות של סוגי ה-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,
    XR_EYE_INDEX_MAX_ENUM_ANDROID = 0x7FFFFFFF
} 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,
    XR_EYE_TRACKING_MODE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} 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 Enums

New Enum Constants

  • 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, ‏2025-01-17 (Kenny Vercaemer)

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