تتوفّر حزمة تطوير البرامج (SDK) لنظام Android XR الآن في "معاينة المطوّر". يهمّنا معرفة ملاحظاتك. يُرجى الانتقال إلى صفحة الدعم للتواصل معنا.

تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

إضافة XR_ANDROID_avatar_eyes OpenXR

سلسلة الاسم

XR_ANDROID_avatar_eyes

نوع الإضافة

إضافة مثيل

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

457

المراجعة

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

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_ANDROID_avatar_eyes قبل استخدام XrSystemAvatarEyesPropertiesANDROID.
type يجب أن يكون XR_TYPE_SYSTEM_AVATAR_EYES_PROPERTIES_ANDROID
next يجب أن يكون NULL أو مؤشرًا صالحًا إلى الهيكل التالي في سلسلة الهياكل

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

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_ANDROID_avatar_eyes قبل استدعاء xrCreateEyeTrackerANDROID.
session يجب أن يكون معرّف XrSession صالحًا
createInfo يجب أن يكون مؤشرًا إلى هيكل XrEyeTrackerCreateInfoANDROID صالح
eyeTracker يجب أن يكون مؤشرًا إلى معرّف XrEyeTrackerANDROID.

رموز الإرجاع

تم بنجاح

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.

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

يجب تفعيل امتداد XR_ANDROID_avatar_eyes قبل استخدام XrEyeTrackerCreateInfoANDROID.
type يجب أن يكون XR_TYPE_EYE_TRACKER_CREATE_INFO_ANDROID
next يجب أن يكون NULL أو مؤشرًا صالحًا إلى الهيكل التالي في سلسلة الهياكل

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

XrResult xrDestroyEyeTrackerANDROID(
    XrEyeTrackerANDROID                         eyeTracker);

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

eyeTracker هو XrEyeTrackerANDROID تم إنشاؤه سابقًا باستخدام xrCreateEyeTrackerANDROID.

تُطلق الدالة xrDestroyEyeTrackerANDROID eyeTracker والموارد الأساسية عند الانتهاء من تجارب تتبُّع العين.

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

يجب تفعيل إضافة XR_ANDROID_avatar_eyes قبل استدعاء xrDestroyEyeTrackerANDROID.
eyeTracker يجب أن يكون اسم معرِّف XrEyeTrackerANDROID صالحًا

أمان سلسلة المحادثات

يجب أن تتم معالجة الوصول إلى 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_ANDROID_avatar_eyes قبل استدعاء xrGetEyesInfoANDROID.
eyeTracker يجب أن يكون اسم معرِّف XrEyeTrackerANDROID صالحًا
getInfo يجب أن يكون مؤشرًا إلى XrEyesGetInfoANDROID بنية صالحة
infoOutput يجب أن يكون مؤشرًا إلى بنية XrEyesANDROID

رموز الإرجاع

تم بنجاح

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.

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

يجب تفعيل إضافة XR_ANDROID_avatar_eyes قبل استخدام XrEyesGetInfoANDROID.
type يجب أن يكون XR_TYPE_EYES_GET_INFO_ANDROID
next يجب أن يكون NULL أو مؤشرًا صالحًا إلى الهيكل التالي في سلسلة الهياكل
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 للعينين اليسرى واليمنى مع ترميزها باستخدام XrEyeIndexANDROID.
‫mode هو XrEyeTrackingModeANDROID للإشارة إلى ما إذا كانت العينان تتمتّعان بميزة التتبّع، وتحديد العينين المعنيّتين.

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

يجب تفعيل إضافة XR_ANDROID_avatar_eyes قبل استخدام XrEyesANDROID.
type يجب أن يكون XR_TYPE_EYES_ANDROID
next يجب أن يكون NULL أو مؤشرًا صالحًا إلى الهيكل التالي في سلسلة الهياكل
يجب أن يكون أي عنصر معيّن من eyes بنية XrEyeANDROID صالحة.
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));

أنواع العناصر الجديدة

XrEyeTrackerANDROID

ثوابت قائمة التعداد الجديدة

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

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

XrEyeIndexANDROID
XrEyeStateANDROID
XrEyeTrackingModeANDROID

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

XrEyeANDROID
XrEyesANDROID
XrEyesGetInfoANDROID
XrEyeTrackerCreateInfoANDROID
XrSystemAvatarEyesPropertiesANDROID

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

xrCreateEyeTrackerANDROID
xrDestroyEyeTrackerANDROID
xrGetEyesInfoANDROID

المشاكل

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

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