برنامه افزودنی OpenXR XR_ANDROID_eye_tracking

رشته نام

XR_ANDROID_eye_tracking

نوع افزونه

افزونه نمونه

شماره داخلی ثبت شده

۴۵۷

بازنگری

۱

وابستگی‌های افزونه و نسخه

اوپن‌ایکس‌آر ۱.۰

آخرین تاریخ اصلاح

۲۰۲۵-۰۱-۱۷

وضعیت آی‌پی

هیچ ادعای مالکیت معنوی شناخته‌شده‌ای وجود ندارد.

مشارکت‌کنندگان

اسپنسر کوئین، گوگل

جارد فایندر، گوگل

لوانا چن، گوگل

کنی ورکامر، گوگل

پراشانتی گورومورتی، گوگل

نیهاو جین، گوگل

نمای کلی

این افزونه به برنامه‌ها امکان می‌دهد موقعیت و جهت چشمان کاربر و همچنین وضعیت ردیابی چشم را به دست آورند.

داده‌های ردیابی چشم در دو حالت ارائه می‌شوند: درشت و ریز. ردیابی درشت، تخمینی تقریبی از چشمان کاربر ارائه می‌دهد، در حالی که ردیابی ریز، تخمینی دقیق‌تر ارائه می‌دهد. ردیابی درشت برای برنامه‌هایی در نظر گرفته شده است که می‌خواهند یک نمایش اولیه شبیه به آواتار ارائه دهند، در حالی که ردیابی ریز برای برنامه‌های دقیق‌تر در نظر گرفته شده است.

برای تعامل، باید از 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)

دسته XrEyeTrackerANDROID یک ردیاب چشم برای ردیابی چشم‌ها است و به طور دقیق آنچه کاربر به آن نگاه می‌کند را نقشه‌برداری می‌کند.

داده‌های ردیابی چشم می‌توانند اطلاعات شخصی حساسی باشند و ارتباط نزدیکی با حریم خصوصی و یکپارچگی شخصی دارند. اکیداً توصیه می‌شود برنامه‌هایی که داده‌های ردیابی چشم را ذخیره یا منتقل می‌کنند، همیشه از کاربر اجازه فعال و خاص برای انجام این کار را بخواهند.

این دسته می‌تواند برای دسترسی به داده‌های ردیابی چشم با استفاده از سایر توابع این افزونه مورد استفاده قرار گیرد.

ردیابی چشم، نمایش ژست و وضعیت چشم را در صحنه فراهم می‌کند.

تابع xrCreateEyeTrackerANDROID به صورت زیر تعریف شده است:

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

توضیحات پارامتر

  • session یک دسته XrSession است که در آن ردیابی چشم فعال خواهد بود.
  • createInfo همان XrEyeTrackerCreateInfoANDROID است که برای تعیین ردیابی چشم استفاده می‌شود.
  • eyeTracker شناسه‌ی XrEyeTrackerANDROID برگردانده شده است.

یک برنامه می‌تواند با استفاده از تابع xrCreateEyeTrackerANDROID یک شناسه XrEyeTrackerANDROID ایجاد کند.

اگر سیستم از ردیابی چشم پشتیبانی نکند، مقدار XR_ERROR_FEATURE_UNSUPPORTED از xrCreateEyeTrackerANDROID برگردانده می‌شود.

کاربرد معتبر (ضمنی)

کدهای بازگشت

موفقیت

  • 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_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 و منابع زیرین را آزاد می‌کند.

کاربرد معتبر (ضمنی)

ایمنی رزوه

  • دسترسی به eyeTracker و هر گونه کنترل فرزند، باید به صورت خارجی هماهنگ‌سازی شود.

کدهای بازگشت

موفقیت

  • XR_SUCCESS

شکست

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

گرفتن اطلاعات چشم

تابع xrGetCoarseTrackingEyesInfoANDROID به صورت زیر تعریف شده است:

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

توضیحات پارامتر

  • eyeTracker یک XrEyeTrackerANDROID است که قبلاً توسط xrCreateEyeTrackerANDROID ساخته شده است.
  • getInfo یک اشاره‌گر به XrEyesGetInfoANDROID است که برای تعیین خروجی مورد نیاز استفاده می‌شود.
  • infoOutput یک اشاره‌گر به XrEyesANDROID است که شامل اطلاعات برگشتی چشم‌ها، شامل حالت‌ها و وضعیت‌ها، می‌باشد.

تابع xrGetCoarseTrackingEyesInfoANDROID اطلاعات مربوط به حالت‌ها و ژست‌های چشم را به گونه‌ای دریافت می‌کند که حریم خصوصی کاربر حفظ شود.

اگر برنامه مجوز android.permission.EYE_TRACKING_COARSE را نداشته باشد، زمان اجرا باید XR_ERROR_PERMISSION_INSUFFICIENT برگرداند.

اطلاعات چشم‌ها در زمان فراخوانی xrGetCoarseTrackingEyesInfoANDROID با استفاده از XrEyesGetInfoANDROID::time و XrEyesGetInfoANDROID::baseSpace ، تفکیک و نسبت به فضای پایه محاسبه می‌شوند.

در هر نقطه از زمان، موقعیت و جهت حالت چشم ردیابی شده یا ردیابی نشده است. این بدان معناست که برنامه‌ها می‌توانند انتظار داشته باشند که هر دو پارامتر XR_SPACE_LOCATION_POSITION_TRACKED_BIT و XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT در XrEyesANDROID::eyes ارائه شده تنظیم یا پاک شوند و XrEyesANDROID::mode eyes حالت‌های ردیابی را نشان دهد.

کاربرد معتبر (ضمنی)

کدهای بازگشت

موفقیت

  • 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
  • XR_ERROR_PERMISSION_INSUFFICIENT

تابع xrGetFineTrackingEyesInfoANDROID به صورت زیر تعریف می‌شود:

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

توضیحات پارامتر

اگر برنامه مجوز android.permission.EYE_TRACKING_FINE را نداشته باشد، زمان اجرا باید XR_ERROR_PERMISSION_INSUFFICIENT برگرداند.

اطلاعات چشم‌ها در زمان فراخوانی xrGetFineTrackingEyesInfoANDROID با استفاده از XrEyesGetInfoANDROID::time و XrEyesGetInfoANDROID::baseSpace ، تفکیک و نسبت به فضای پایه محاسبه می‌شوند.

در هر نقطه از زمان، موقعیت و جهت حالت چشم ردیابی شده یا ردیابی نشده است. این بدان معناست که برنامه‌ها می‌توانند انتظار داشته باشند که هر دو پارامتر XR_SPACE_LOCATION_POSITION_TRACKED_BIT و XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT در XrEyesANDROID::eyes ارائه شده تنظیم یا پاک شوند و XrEyesANDROID::mode eyes حالت‌های ردیابی را نشان دهد.

کاربرد معتبر (ضمنی)

کدهای بازگشت

موفقیت

  • 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
  • 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 حالت چشم در time نسبت به این 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 ها معانی زیر را دارند:

شمارشی

توضیحات

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 ها معانی زیر را دارند:

شمارشی

توضیحات

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 ها معانی زیر را دارند:

شمارشی

توضیحات

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

انواع شیء جدید

ثابت‌های شمارشی جدید

  • 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

Enum های جدید

سازه‌های جدید

توابع جدید

مسائل

تاریخچه نسخه

  • نسخه ۱، ۲۰۲۵-۰۱-۱۷ (کنی ورکامر)
    • توضیحات اولیه افزونه

OpenXR™ و لوگوی OpenXR علائم تجاری متعلق به گروه Khronos هستند و به عنوان یک علامت تجاری در چین، اتحادیه اروپا، ژاپن و بریتانیا ثبت شده‌اند.