إضافة XR_ANDROID_avatar_eyes OpenXR

سلسلة الاسم

XR_ANDROID_avatar_eyes

نوع الإضافة

إضافة مثيل

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

457

المراجعة

1

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

OpenXR 1.0

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

2024-09-30

حالة عنوان IP

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

المساهمون

سبنسر كوين، Google

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

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

نظرة عامة

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

تهدف هذه الإضافة إلى جعل وضع العين وتمثيل الحالة فيаватارات أكثر واقعية. ولهذا الغرض:

  • ويسمح هذا الإجراء برصد حالات غير قابلة للتتبّع، مثل الغمز.
  • يتيح هذا الوضع التتبّع باستخدام عين واحدة أو عينَين.

يجب عدم استخدام هذه الإضافة لأغراض أخرى تتبُّع العين. بالنسبة إلى التفاعل، يجب استخدام XR_EXT_eye_gaze_interaction.

أداة تتبُّع حركة العين

أداة تتبُّع العين هي جهاز استشعار يتتبّع العينين ويحدِّد بدقة مكان نظر المستخدم. الغرض الرئيسي من هذا الملحق هو ربط نظرات المستخدمين بصورهم الرمزية في مشهد افتراضي.

يمكن أن تكون بيانات تتبُّع العين معلومات شخصية حسّاسة وترتبط ارتباطًا وثيقًا بالخصوصية الشخصية والنزاهة. ننصح بشدة بأن تطلب التطبيقات التي تخزِّن بيانات تتبُّع العين أو تنقلها من المستخدم دائمًا قبولًا نشطًا ومحددًا لإجراء ذلك.

  • سيتلقّى التطبيق الخطأ XR_ERROR_PERMISSION_INSUFFICIENT عند محاولة إنشاء أداة تتبُّع عين نشطة إلى أن يُسمح للتطبيق بالوصول إلى أداة تتبُّع العين.

فحص قدرة النظام

يمكن للتطبيق التحقّق مما إذا كان النظام يتيح استخدام عيون الصورة الرمزية من خلال ربط بنية XrSystemAvatarEyesPropertiesANDROID ببنية XrSystemProperties عند استدعاء xrGetSystemProperties. إذا كانت دالّة supportsAvatarEyes تعرِض XR_FALSE، سيتلقّى التطبيق قيمة XR_ERROR_FEATURE_UNSUPPORTED من xrCreateEyeTrackerANDROID.

typedef struct XrSystemAvatarEyesPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsAvatarEyes;
} XrSystemAvatarEyesPropertiesANDROID;

أوصاف الأعضاء

  • type هو XrStructureType لهذه البنية.
  • next هو NULL أو مؤشر إلى البنية التالية في سلسلة البنية. لا يتم تعريف مثل هذه الهياكل في OpenXR الأساسية أو هذه الإضافة.
  • supportsAvatarEyes هو XrBool32، ويشير إلى ما إذا كان النظام الحالي يتوافق مع عيون الصورة الرمزية.

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

إنشاء اسم معرِّف لجهاز تتبُّع حركة العين

XR_DEFINE_HANDLE(XrEyeTrackerANDROID)

يمثّل الاسم المعرِّف XrEyeTrackerANDROID أداة تتبُّع العينين لتتبُّع العينين وتعيين ما ينظر إليه المستخدم بدقة.

يمكن استخدام هذا المعرّف للوصول إلى بيانات تتبُّع العين باستخدام دوال أخرى في هذه الإضافة.

يوفّر تتبُّع العين وضع العين وتمثيل حالتها في المشهد.

يتم تعريف الدالة xrCreateEyeTrackerANDROID على النحو التالي: 

XrResult xrCreateEyeTrackerANDROID(
    XrSession                                   session,
    const XrEyeTrackerCreateInfoANDROID*        createInfo,
    XrEyeTrackerANDROID*                        eyeTracker);

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

يمكن للتطبيق إنشاء معرّف 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

يتم تعريف بنية 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

الحصول على معلومات عن العيون

يتم تعريف الدالة xrGetEyesInfoANDROID على النحو التالي:

XrResult xrGetEyesInfoANDROID(
    XrEyeTrackerANDROID                         eyeTracker,
    const XrEyesGetInfoANDROID*                 getInfo,
    XrEyesANDROID*                              infoOutput);

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

  • eyeTracker هو XrEyeTrackerANDROID تم إنشاؤه سابقًا باستخدام xrCreateEyeTrackerANDROID.
  • getInfo هو مؤشر إلى XrEyesGetInfoANDROID المستخدَم لتحديد المخرجات المطلوبة.
  • infoOutput هو مؤشر إلى XrEyesANDROID الذي يحتوي على معلومات العيون المعروضة، بما في ذلك الوضعيات والحالات.

تحصل الدالة xrGetEyesInfoANDROID على معلومات عن حالات العينين ووضعيهما.

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

يحتوي هيكل 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_avatar_eyes قبل استخدام 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, for example, 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_xrGetEyesInfoANDROID xrGetEyesInfoANDROID; // 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 eyesInfo{.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(xrGetEyesInfoANDROID(eyeTracker, &eyesGetInfo, &eyesInfo));

    // 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_AVATAR_EYES_PROPERTIES_ANDROID

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

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

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

المشاكل

سجلّ الإصدارات

  • المراجعة 1، ‎04-09-2024 (ليلى زين)
    • الوصف الأولي للإضافة