תוסף OpenXR‏ XR_ANDROID_avatar_eyes

Name String

XR_ANDROID_avatar_eyes

סוג התוסף

תוסף למכונה

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

457

גרסה

1

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

OpenXR 1.0

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

2024-09-30

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

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

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

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

Jared Finder, ‏ Google

לבנה צ'ן, Google

סקירה כללית

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

התוסף הזה נועד לשפר את המראה הריאליסטי של העיניים והסטטוס של הדמויות ב-Avatars. לשם כך:

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

אסור להשתמש בתוסף הזה למטרות אחרות של מעקב אחר תנועות עיניים. לצורך אינטראקציה, צריך להשתמש ב-XR_EXT_eye_gaze_interaction.

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

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

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

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

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

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

typedef struct XrSystemAvatarEyesPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsAvatarEyes;
} XrSystemAvatarEyesPropertiesANDROID;

תיאורי חברים

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

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

• חובה להפעיל את התוסף XR_ANDROID_avatar_eyes לפני שמשתמשים ב-XrSystemAvatarEyesPropertiesANDROID
• הערך של type חייב להיות XR_TYPE_SYSTEM_AVATAR_EYES_PROPERTIES_ANDROID
• next חייב להיות NULL או מצביע תקין להמבנה הבא בשרשרת המבנים

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

XR_DEFINE_HANDLE(XrEyeTrackerANDROID)

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

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

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

הפונקציה 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_ANDROID_avatar_eyes לפני שמפעילים את 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

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

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

תיאורי חברים

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

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

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

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

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

XrResult xrDestroyEyeTrackerANDROID(
    XrEyeTrackerANDROID                         eyeTracker);

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

• eyeTracker הוא XrEyeTrackerANDROID שנוצר קודם לכן באמצעות xrCreateEyeTrackerANDROID.

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

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

• חובה להפעיל את התוסף XR_ANDROID_avatar_eyes לפני שמפעילים את xrDestroyEyeTrackerANDROID
• eyeTracker חייב להיות מזהה XrEyeTrackerANDROID חוקי

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

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

קודי החזרה

הצלחה

• XR_SUCCESS

כישלון

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID

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

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

XrResult xrGetEyesInfoANDROID(
    XrEyeTrackerANDROID                         eyeTracker,
    const XrEyesGetInfoANDROID*                 getInfo,
    XrEyesANDROID*                              infoOutput);

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

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

הפונקציה xrGetEyesInfoANDROID מקבלת את המידע על מצבי העיניים ועל תנוחות העיניים.

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

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

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

• חובה להפעיל את התוסף XR_ANDROID_avatar_eyes לפני שמפעילים את xrGetEyesInfoANDROID.
• eyeTracker חייב להיות מזהה XrEyeTrackerANDROID חוקי
• getInfo חייב להיות הפניה למבנה תקין של XrEyesGetInfoANDROID
• infoOutput חייב להיות הפניה למבנה 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

המבנה 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_avatar_eyes לפני שמשתמשים ב-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_avatar_eyes לפני שמשתמשים ב-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_avatar_eyes לפני שמשתמשים ב-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 יש את המשמעויות הבאות:

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

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

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

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

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

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

XrSession session; // previously initialized, for example, 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_xrGetEyesInfoANDROID xrGetEyesInfoANDROID; // 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 eyesInfo{.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(xrGetEyesInfoANDROID(eyeTracker, &eyesGetInfo, &eyesInfo));

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

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

• XrEyeTrackerANDROID

קבועים חדשים של 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_AVATAR_EYES_PROPERTIES_ANDROID

משתני Enum חדשים

• XrEyeIndexANDROID
• XrEyeStateANDROID
• XrEyeTrackingModeANDROID

מבנים חדשים

• XrEyeANDROID
• XrEyesANDROID
• XrEyesGetInfoANDROID
• XrEyeTrackerCreateInfoANDROID
• XrSystemAvatarEyesPropertiesANDROID

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

• xrCreateEyeTrackerANDROID
• xrDestroyEyeTrackerANDROID
• xrGetEyesInfoANDROID

בעיות

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

• גרסה 1, 4 בספטמבר 2024 (Levana Chen)
  • תיאור ראשוני של התוסף