XR_ANDROID_eye_tracking

رشته نام

XR_ANDROID_eye_tracking

نوع افزونه

افزونه نمونه

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

457

بازبینی

1

وضعیت تصویب

تصویب‌نشده

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

OpenXR 1.0

تاریخ آخرین تغییر

2025-01-17

وضعیت 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)

دستگیره 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
  • XR_ERROR_RUNTIME_FAILURE

درحال دریافت اطلاعات چشم‌ها

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

استفاده معتبر (ضمنی)

کدهای برگشتی

موفقیت‌آمیز بود

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

استفاده معتبر (ضمنی)

کدهای برگشتی

موفقیت‌آمیز بود

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

استفاده معتبر (ضمنی)

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

مقادیر شمارشی معانی زیر را دارند:

شرح شمارشی

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;

مقادیر شمارشی معانی زیر را دارند:

شرح شمارشی

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;

مقادیر شمارشی معانی زیر را دارند:

شرح شمارشی

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

نشان می‌دهد که هر دو چشم چپ و راست درحال ردیابی هستند.

#define XR_EYE_MAX_ANDROID                2

XR_EYE_MAX_ANDROID حداکثر تعداد چشم‌هایی است که داده‌های XrEyeANDROID برای آن‌ها گزارش می‌شود.

کد نمونه برای ردگیری چشم

کد نمونه زیر نشان می‌دهد که چگونه اطلاعات چشم‌ها را نسبت به فضای نمای دریافت کنید.

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

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

فرمان‌های جدید

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

Enums جدید

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

  • 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

مشکلات

سابقه نسخه

  • بازبینی ۱، ۲۰۲۵/۰۱/۱۷ (Kenny Vercaemer)

    • شرح اولیه افزونه