رشته نام
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_ANDROID_eye_trackingباید قبل از استفاده ازXrSystemEyeTrackingPropertiesANDROIDفعال شود. -
typeبایدXR_TYPE_SYSTEM_EYE_TRACKING_PROPERTIES_ANDROIDباشد. -
nextبایدNULLیا یک اشارهگر معتبر به ساختار بعدی در یک زنجیره ساختار باشد.
یک دسته ردیاب چشم ایجاد کنید
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_ANDROID_eye_trackingباید قبل از فراخوانی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 -
XR_ERROR_FEATURE_UNSUPPORTED
ساختار XrEyeTrackerCreateInfoANDROID به صورت زیر تعریف شده است:
typedef struct XrEyeTrackerCreateInfoANDROID {
XrStructureType type;
void* next;
} XrEyeTrackerCreateInfoANDROID;
توضیحات اعضا
-
typeنوعXrStructureTypeاین ساختار است. -
nextباNULLیا اشارهگری به ساختار بعدی در یک زنجیره ساختار است. چنین ساختارهایی در هسته OpenXR یا این افزونه تعریف نشدهاند.
ساختار XrEyeTrackerCreateInfoANDROID اطلاعات لازم برای ایجاد یک هندل XrEyeTrackerANDROID را توصیف میکند.
کاربرد معتبر (ضمنی)
- افزونهی
XR_ANDROID_eye_trackingباید قبل از استفاده ازXrEyeTrackerCreateInfoANDROIDفعال باشد. -
typeبایدXR_TYPE_EYE_TRACKER_CREATE_INFO_ANDROIDباشد. -
nextبایدNULLیا یک اشارهگر معتبر به ساختار بعدی در یک زنجیره ساختار باشد.
تابع xrDestroyEyeTrackerANDROID به صورت زیر تعریف شده است:
XrResult xrDestroyEyeTrackerANDROID(
XrEyeTrackerANDROID eyeTracker);
توضیحات پارامتر
-
eyeTrackerیکXrEyeTrackerANDROIDاست که قبلاً توسطxrCreateEyeTrackerANDROIDساخته شده است.
تابع xrDestroyEyeTrackerANDROID پس از اتمام تجربیات ردیابی چشم eyeTracker و منابع زیرین را آزاد میکند.
کاربرد معتبر (ضمنی)
- افزونهی
XR_ANDROID_eye_trackingباید قبل از فراخوانیxrDestroyEyeTrackerANDROIDفعال شود. -
eyeTrackerباید یک شناسه معتبرXrEyeTrackerANDROIDباشد.
ایمنی رزوه
- دسترسی به
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_ANDROID_eye_trackingباید قبل از فراخوانیxrGetCoarseTrackingEyesInfoANDROIDفعال شود. -
eyeTrackerباید یک شناسه معتبرXrEyeTrackerANDROIDباشد. -
getInfoباید یک اشارهگر به ساختار معتبرXrEyesGetInfoANDROIDباشد. -
eyesOutputباید یک اشارهگر به ساختار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 -
XR_ERROR_PERMISSION_INSUFFICIENT
تابع xrGetFineTrackingEyesInfoANDROID به صورت زیر تعریف میشود:
XrResult xrGetFineTrackingEyesInfoANDROID(
XrEyeTrackerANDROID eyeTracker,
const XrEyesGetInfoANDROID* getInfo,
XrEyesANDROID* eyesOutput);
توضیحات پارامتر
-
eyeTrackerیکXrEyeTrackerANDROIDاست که قبلاً توسطxrCreateEyeTrackerANDROIDساخته شده است. -
getInfoیک اشارهگر بهXrEyesGetInfoANDROIDاست که برای تعیین خروجی مورد نیاز استفاده میشود. -
infoOutputیک اشارهگر بهXrEyesANDROIDاست که شامل اطلاعات برگشتی چشمها، شامل حالتها و وضعیتها، میباشد. تابعxrGetFineTrackingEyesInfoANDROIDاطلاعات مربوط به حالتها و وضعیتهای چشم را با دقت بالاتری نسبت بهxrGetCoarseTrackingEyesInfoANDROIDدریافت میکند.
اگر برنامه مجوز 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_ANDROID_eye_trackingباید قبل از فراخوانیxrGetFineTrackingEyesInfoANDROIDفعال شود. -
eyeTrackerباید یک شناسه معتبرXrEyeTrackerANDROIDباشد. -
getInfoباید یک اشارهگر به ساختار معتبرXrEyesGetInfoANDROIDباشد. -
eyesOutputباید یک اشارهگر به ساختار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 -
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خواهد بود.
کاربرد معتبر (ضمنی)
- افزونهی
XR_ANDROID_eye_trackingباید قبل از استفاده از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اندیسگذاری شده است. -
modeXrEyeTrackingModeANDROIDاست که نشان میدهد آیا چشمها ردیابی میکنند و کدام یک.
کاربرد معتبر (ضمنی)
- افزونهی
XR_ANDROID_eye_trackingباید قبل از استفاده ازXrEyesANDROIDفعال باشد. -
typeبایدXR_TYPE_EYES_ANDROIDباشد. -
nextبایدNULLیا یک اشارهگر معتبر به ساختار بعدی در یک زنجیره ساختار باشد. - هر عنصر داده شده از
eyesباید یک ساختار معتبرXrEyeANDROIDباشد. -
modeباید یک مقدار معتبرXrEyeTrackingModeANDROIDباشد.
ساختار XrEyeANDROID حالت، موقعیت و جهتگیری یک چشم را توصیف میکند.
typedef struct XrEyeANDROID {
XrEyeStateANDROID eyeState;
XrPosef eyePose;
} XrEyeANDROID;
توضیحات اعضا
-
eyeStateXrEyeStateANDROIDیک چشم است. -
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 ها معانی زیر را دارند:
شمارشی | توضیحات |
| نشان میدهد که چشم در حالت خطا قرار دارد یا وجود ندارد. |
| نشان میدهد که چشم خیره شده است. |
| نشان میدهد که چشم به دلیل چشمک زدن یا پلک زدن بسته شده است. |
شمارش XrEyeIndexANDROID شاخص چشم چپ یا راست را مشخص میکند.
typedef enum XrEyeIndexANDROID {
XR_EYE_INDEX_LEFT_ANDROID = 0,
XR_EYE_INDEX_RIGHT_ANDROID = 1
} XrEyeIndexANDROID;
enum ها معانی زیر را دارند:
شمارشی | توضیحات |
| چشم چپ. |
| چشم راست. |
شمارش 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 ها معانی زیر را دارند:
شمارشی | توضیحات |
| نشان میدهد که ردیابی چشم فعال نیست. |
| نشان میدهد که فقط چشم راست در حال ردیابی است. |
| نشان میدهد که فقط چشم چپ در حال ردیابی است. |
| نشان میدهد که هر دو چشم چپ و راست در حال ردیابی هستند. |
نمونه کد برای ردیابی چشم
کد مثال زیر نحوه دریافت اطلاعات چشم نسبت به فضای دید را نشان میدهد.
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 های جدید
سازههای جدید
-
XrEyeANDROID -
XrEyesANDROID -
XrEyesGetInfoANDROID -
XrEyeTrackerCreateInfoANDROID -
XrSystemEyeTrackingPropertiesANDROID
توابع جدید
-
xrCreateEyeTrackerANDROID -
xrDestroyEyeTrackerANDROID -
xrGetCoarseTrackingEyesInfoANDROID -
xrGetFineTrackingEyesInfoANDROID
مسائل
تاریخچه نسخه
- نسخه ۱، ۲۰۲۵-۰۱-۱۷ (کنی ورکامر)
- توضیحات اولیه افزونه
OpenXR™ و لوگوی OpenXR علائم تجاری متعلق به گروه Khronos هستند و به عنوان یک علامت تجاری در چین، اتحادیه اروپا، ژاپن و بریتانیا ثبت شدهاند.