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

رشته نام

XR_ANDROID_eye_tracking

نوع پسوند

پسوند نمونه

شماره برنامه افزودنی ثبت شده

457

تجدید نظر

1

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

OpenXR 1.0

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

17-01-2025

وضعیت IP

هیچ ادعای IP شناخته شده ای وجود ندارد.

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

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

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

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

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

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

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

نمای کلی

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

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

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

قابلیت سیستم را بررسی کنید

ساختار XrSystemEyeTrackingPropertiesANDROID به صورت زیر تعریف می شود:

typedef struct XrSystemEyeTrackingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsEyeTracking;
} XrSystemEyeTrackingPropertiesANDROID;

توضیحات اعضا

  • type XrStructureType این ساختار است.
  • next NULL یا اشاره گر به ساختار بعدی در زنجیره ساختار است. چنین ساختاری در هسته OpenXR یا این پسوند تعریف نشده است.
  • supportsEyeTracking یک XrBool32 است که نشان می‌دهد آیا سیستم فعلی از ردیابی چشم پشتیبانی می‌کند یا خیر.

هنگام فراخوانی xrGetSystemProperties XrSystemEyeTrackingPropertiesANDROID برنامه کاربردی می تواند بررسی کند که آیا سیستم قادر به ردیابی چشم است یا خیر. اگر supportsEyeTracking XR_FALSE را برگرداند، برنامه XR_ERROR_FEATURE_UNSUPPORTED از xrCreateEyeTrackerANDROID دریافت خواهد کرد.

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

یک دسته ردیاب چشم ایجاد کنید 

XR_DEFINE_HANDLE(XrEyeTrackerANDROID)

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

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

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

ردیابی چشم وضعیت و وضعیت چشم را در صحنه نمایش می دهد.

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

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

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

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

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

کدهای بازگشت

موفقیت

  • 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 به صورت زیر تعریف می‌شود: {:#xrGetFineTrackingEyesInfoANDROID} C++ 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 وضعیت ردیابی را نشان می‌دهد.

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

کدهای بازگشت

موفقیت

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

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, 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_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

فهرست های جدید

ساختارهای جدید

توابع جدید

مسائل

تاریخچه نسخه

  • بازبینی 1، 17/01/2025 (کنی ورکامر)
    • توضیحات پسوند اولیه