إضافة XR_ANDROID_eye_tracking OpenXR

سلسلة الاسم

XR_ANDROID_eye_tracking

نوع الإضافة

إضافة مثيل

رقم الإضافة المسجَّل

457

المراجعة

1

التبعيات المتعلّقة بالإصدارات والإضافات

OpenXR 1.0

تاريخ آخر تعديل

2025-01-17

حالة عنوان IP

ما مِن مطالبات معروفة بعناوين IP.

المساهمون

سبنسر كوين، Google

"جيرد فايندر"، Google

ليفانا تشين، من Google

"كيني فيركامر"، Google

براسانتي غورومورثي، Google

نيهاف جاين، Google

نظرة عامة

تتيح هذه الإضافة للتطبيقات الحصول على موضع عيون المستخدِم واتجاهها، بالإضافة إلى حالة تتبُّع العين.

يتم تقديم بيانات تتبُّع العينَين بطريقتَين: دقيقة وغير دقيقة. يقدّم التتبّع التقريبي تقديرًا تقريبيًا لعيون المستخدم، في حين يقدّم التتبّع الدقيق تقديرًا أكثر دقة. يُستخدَم التتبُّع التقريبي للتطبيقات التي تريد تقديم تمثيل أساسي يشبه الصورة الرمزية، في حين يُستخدَم التتبُّع الدقيق للتطبيقات التي تريد تقديم تمثيل أكثر دقة.

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

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

يتم حلّ معلومات العيون وربطها بالمساحة الأساسية في وقت الاستدعاء إلى 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);

أوصاف المَعلمات

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

يتم حلّ معلومات العيون وربطها بالمساحة الأساسية في وقت الاستدعاء إلى 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 على المعلومات المطلوبة ل retrieving eye poses and states. 

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

الوصف

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

الوصف

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

الوصف

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_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 (كيني فيركمير)
    • الوصف الأولي للإضافة