ردیابی چشم XR_ANDROID

رشته نام

XR_ANDROID_eye_tracking

نوع افزونه

افزونه نمونه

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

۴۵۷

بازنگری

۱

وضعیت تصویب

تصویب نشده

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

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

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

۲۰۲۵-۰۱-۱۷

وضعیت آی‌پی

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

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

اسپنسر کوئین، گوگل
جارد فایندر، گوگل
لوانا چن، گوگل
کنی ورکامر، گوگل
پراشانتی گورومورتی، گوگل
نیهاو جین، گوگل

نمای کلی

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

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

برای تعامل، باید از XR_EXT_eye_gaze_interaction استفاده شود.

مجوزها

برنامه‌های اندروید باید مجوزهای 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)

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

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

ایمنی رزوه

  • دسترسی به 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 است که برای ارائه اطلاعات جهت پرس‌وجو از حالت‌ها و وضعیت‌های چشم استفاده می‌شود.
  • eyesOutput یک اشاره‌گر به XrEyesANDROID است که شامل اطلاعات برگشتی چشم‌ها، شامل حالت‌ها و وضعیت‌ها، می‌باشد.

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

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

حالت‌های چشم در 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 ارائه شده، و mode XrEyesANDROID :: را برای نشان دادن حالت‌های ردیابی تنظیم کند.

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

کدهای بازگشت

موفقیت

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

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

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

تابع xrGetFineTrackingEyesInfoANDROID اطلاعات مربوط به حالت‌ها و ژست‌های چشم را با دقت بالاتری نسبت به xrGetCoarseTrackingEyesInfoANDROID دریافت می‌کند.

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

اطلاعات چشم‌ها در زمان فراخوانی 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 ارائه شده، و mode XrEyesANDROID :: را برای نشان دادن حالت‌های ردیابی تنظیم کند.

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

کدهای بازگشت

موفقیت

  • 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 است که حالت‌های چشم نسبت به آن در time تعیین می‌شوند.

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

ساختار 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;

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

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

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

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

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

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

دستورات جدید

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

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

مسائل

تاریخچه نسخه

  • نسخه ۱، ۲۰۲۵-۰۱-۱۷ (کنی ورکامر)

    • توضیحات اولیه افزونه