XR_ANDROID_eye_tracking

Name String

XR_ANDROID_eye_tracking

نوع الإضافة

إضافة مثيل

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

457

المراجعة

1

حالة التصديق

لم تتم المصادقة عليها

الاعتماد على الإضافات والإصدارات

OpenXR 1.0

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

2025-01-17

حالة الملكية الفكرية

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

المساهمون

سبنسر كوين، Google
جاريد فايندر، Google
ليفانا تشن، Google
كيني فيركايمر، Google
براسانثي غورومورثي، Google
نيهاف جاين، 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 .

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

رموز الإرجاع

Success

  • 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 والموارد الأساسية عند الانتهاء من تجارب تتبُّع العين.

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

أمان Thread

  • يجب مزامنة الوصول إلى eyeTracker وأي معرّفات فرعية خارجيًا

رموز الإرجاع

Success

  • XR_SUCCESS

تعذّر الإجراء

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

جارٍ الحصول على معلومات عن العينَين

يتم تعريف الدالة 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 أو يمحو كلاً من XR_SPACE_LOCATION_POSITION_TRACKED_BIT وXR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT في XrEyesANDROID :: eyes المقدَّم، ويضبط XrEyesANDROID :: mode للإشارة إلى حالات التتبُّع.

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

رموز الإرجاع

Success

  • 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 أو يمحو كلاً من XR_SPACE_LOCATION_POSITION_TRACKED_BIT وXR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT في XrEyesANDROID :: eyes المقدَّم، ويضبط XrEyesANDROID :: mode للإشارة إلى حالات التتبُّع.

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

رموز الإرجاع

Success

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

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

تحتوي بنية 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

يشير إلى أنّ كلاً من العينين اليسرى واليمنى تتبعان.

#define XR_EYE_MAX_ANDROID                2

‫XR_EYE_MAX_ANDROID هو الحدّ الأقصى لعدد العيون التي يتم تسجيل بيانات XrEyeANDROID لها.

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

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

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 (كيني فيركايمر)

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