Android XR SDK זמין עכשיו בתצוגה מקדימה למפתחים. אנו רוצים את המשוב שלך! אפשר לפנות אלינו דרך דף התמיכה.

דף זה תורגם על ידי Cloud Translation API.

תוסף OpenXR‏ XR_ANDROID_avatar_eyes

מחרוזת שם

XR_ANDROID_avatar_eyes

סוג התוסף

תוסף למכונה

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

457

גרסה

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

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

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, 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)
- תיאור ראשוני של התוסף