XR_ANDROID_eye_tracking

Name String

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 الذي تم عرضه.

ينشئ التطبيق معرّف XrEyeTrackerANDROID باستخدام الدالة xrCreateEyeTrackerANDROID.

إذا كان النظام لا يتيح تتبّع العين، يجب أن تعرض بيئة التشغيل القيمة 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 على معلومات حول حالات العينين ووضعيتهما بطريقة تحافظ على خصوصية المستخدم.

يجب أن تعرض بيئة التشغيل XR_ERROR_PERMISSION_INSUFFICIENT إذا لم يكن لدى التطبيق الإذن android.permission.EYE_TRACKING_COARSE.

يتم التعبير عن وضعيات العين في XrEyesGetInfoANDROID :: baseSpace في XrEyesGetInfoANDROID :: time .

في أي وقت، يتم تتبُّع موضع العين واتجاهها أو عدم تتبُّعهما. وهذا يعني أنّه يجب أن يضبط وقت التشغيل كلاً من XR_SPACE_LOCATION_POSITION_TRACKED_BIT وXR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT أو يمحوهما في XrEyesANDROID :: eyes المقدَّم، وأن يضبط XrEyesANDROID :: mode للإشارة إلى حالات التتبُّع.XR_SPACE_LOCATION_POSITION_TRACKED_BITXR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT

الاستخدام الصالح (الضمني)

رموز الإرجاع

ناجحة

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

يجب أن تعرض بيئة التشغيل القيمة XR_ERROR_PERMISSION_INSUFFICIENT إذا لم يكن التطبيق لديه الإذن android.permission.EYE_TRACKING_FINE.

يتم تحديد معلومات العينين بالنسبة إلى المساحة الأساسية في وقت استدعاء xrGetFineTrackingEyesInfoANDROID باستخدام XrEyesGetInfoANDROID :: time وXrEyesGetInfoANDROID :: baseSpace . يجب أن يحلّ وقت التشغيل الموقع الجغرافي المحدّد بواسطة XrEyesGetInfoANDROID :: baseSpace في وقت المكالمة.

في أي وقت، يتم تتبُّع موضع العين واتجاهها أو عدم تتبُّعهما. وهذا يعني أنّه يجب أن يضبط وقت التشغيل كلاً من XR_SPACE_LOCATION_POSITION_TRACKED_BIT وXR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT أو يمحوهما في XrEyesANDROID :: eyes المقدَّم، وأن يضبط XrEyesANDROID :: mode للإشارة إلى حالات التتبُّع.XR_SPACE_LOCATION_POSITION_TRACKED_BITXR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT

الاستخدام الصالح (الضمني)

رموز الإرجاع

ناجحة

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

تحمل القيم المُعدّدة المعاني التالية:

وصف التعداد

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

تشير هذه الحالة إلى أنّ كلتا العينين اليسرى واليمنى يتم تتبُّعهما.

مثال على الرمز البرمجي لتتبّع العين

يوضّح نموذج الرمز البرمجي التالي كيفية الحصول على معلومات العينين بالنسبة إلى مساحة العرض.

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

المشاكل

سجلّ التعديلات

  • المراجعة 1، 17-01-2025 (Kenny Vercaemer)

    • الوصف الأوّلي للإضافة