إضافة XR_ANDROID_eye_tracking OpenXR

Name String

XR_ANDROID_eye_tracking

نوع الإضافة

إضافة مثيل

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

457

المراجعة

1

متطلبات الإضافة والإصدار

OpenXR 1.0

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

2025-01-17

حالة عنوان IP

ما مِن مطالبات معروفة بشأن الملكية الفكرية.

المساهمون

سبنسر كوين، Google

Jared Finder، 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 على النحو التالي: 

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 على المعلومات المطلوبة لاسترداد أوضاع العين وحالاتها. 

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

عمليات التعداد الجديدة

البُنى الجديدة

الدوال الجديدة

المشاكل

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

  • Revision 1, 2025-01-17 (Kenny Vercaemer)
    • الوصف الأوّلي للإضافة

‫OpenXR™ وشعار OpenXR هما علامتان تجاريتان مملوكتان لشركة The Khronos Group Inc. ومسجّلتان كعلامة تجارية في الصين والاتحاد الأوروبي واليابان والمملكة المتحدة.