إضافة XR_ANDROID_face_tracking OpenXR

Name String

XR_ANDROID_face_tracking

نوع الإضافة

إضافة مثيل

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

459

المراجعة

3

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

OpenXR 1.0

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

2025-06-04

حالة عنوان IP

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

المساهمون

سبنسر كوين، Google

Jared Finder، Google

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

نظرة عامة

تتيح هذه الإضافة للتطبيقات الحصول على أوزان أشكال المزج وعرض تعابير الوجه في تجارب الواقع الممتد.

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

أداة تتبُّع الوجه

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

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

• ستتلقّى التطبيقات القيمة XR_ERROR_PERMISSION_INSUFFICIENT عند إنشاء أداة تتبُّع نشطة للوجه إلى أن يُسمح للتطبيق بالوصول إلى أداة تتبُّع الوجه.
• عند الحصول على حالات الوجه باستخدام xrGetFaceStateANDROID، لن تعرض XrFaceStateANDROID::isValid القيمة XR_TRUE إلا إذا تم السماح للتطبيق بالوصول إلى بيانات الوجه.

فحص إمكانات النظام

يتم تعريف بنية XrSystemFaceTrackingPropertiesANDROID على النحو التالي:

typedef struct XrSystemFaceTrackingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsFaceTracking;
} XrSystemFaceTrackingPropertiesANDROID;

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

• ‫type هو XrStructureType لهذا الهيكل.
• next هو NULL أو مؤشر إلى البنية التالية في سلسلة البنية.
• ‫supportsFaceTracking هو XrBool32 يشير إلى ما إذا كان النظام الحالي يتيح تتبُّع الوجه.

يمكن لأحد التطبيقات التحقّق مما إذا كان النظام قادرًا على تتبُّع الوجه من خلال توسيع XrSystemProperties باستخدام بنية XrSystemFaceTrackingPropertiesANDROID عند استدعاء xrGetSystemProperties.

إذا كان وقت التشغيل يعرض XR_FALSE فقط عند استدعاء supportsFaceTracking، يجب أن يعرض وقت التشغيل XR_ERROR_FEATURE_UNSUPPORTED من xrCreateFaceTrackerANDROID.

إنشاء معرّف لتتبُّع الوجه

XR_DEFINE_HANDLE(XrFaceTrackerANDROID)

يمثّل معرّف XrFaceTrackerANDROID أداة تتبُّع للوجوه.

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

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

XrResult xrCreateFaceTrackerANDROID(
    XrSession                                   session,
    const XrFaceTrackerCreateInfoANDROID*       createInfo,
    XrFaceTrackerANDROID*                       faceTracker);

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

• session هو معرّف XrSession الذي سيكون فيه برنامج تتبُّع الوجه نشطًا.
• ‫createInfo هي XrFaceTrackerCreateInfoANDROID المستخدَمة لتحديد أداة تتبُّع الوجه.
• ‫faceTracker هو مقبض XrFaceTrackerANDROID المعروض.

يمكن لأي تطبيق إنشاء معرّف XrFaceTrackerANDROID باستخدام الدالة xrCreateFaceTrackerANDROID.

إذا كان النظام لا يتيح تتبُّع الوجوه، ستعرض الدالة xrCreateFaceTrackerANDROID القيمة XR_ERROR_FEATURE_UNSUPPORTED.

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

• يجب تفعيل إضافة XR_ANDROID_face_tracking قبل استدعاء xrCreateFaceTrackerANDROID
• يجب أن يكون session معرّف XrSession صالحًا
• يجب أن يكون createInfo مؤشرًا إلى بنية XrFaceTrackerCreateInfoANDROID صالحة
• يجب أن يكون faceTracker مؤشرًا إلى مقبض XrFaceTrackerANDROID

رموز الإرجاع

تم بنجاح

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Failure

• 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

يتم وصف بنية XrFaceTrackerCreateInfoANDROID على النحو التالي:

typedef struct XrFaceTrackerCreateInfoANDROID {
    XrStructureType    type;
    void*              next;
} XrFaceTrackerCreateInfoANDROID;

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

• ‫type هو XrStructureType لهذا الهيكل.
• next هو NULL أو مؤشر إلى البنية التالية في سلسلة البنية. لم يتم تحديد أي بنى من هذا النوع في OpenXR الأساسية أو في هذه الإضافة.

يصف بنية XrFaceTrackerCreateInfoANDROID المعلومات اللازمة لإنشاء معرّف XrFaceTrackerANDROID.

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

• يجب تفعيل إضافة XR_ANDROID_face_tracking قبل استخدام XrFaceTrackerCreateInfoANDROID
• يجب أن يكون type XR_TYPE_FACE_TRACKER_CREATE_INFO_ANDROID
• يجب أن تكون قيمة next NULL أو مؤشرًا صالحًا إلى البنية التالية في سلسلة البِنى

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

XrResult xrDestroyFaceTrackerANDROID(
    XrFaceTrackerANDROID                        faceTracker);

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

• ‫faceTracker هو XrFaceTrackerANDROID تم إنشاؤه سابقًا باستخدام xrCreateFaceTrackerANDROID.

تؤدي الدالة xrDestroyFaceTrackerANDROID إلى تحرير faceTracker والموارد الأساسية عند انتهاء تجربة تتبُّع الوجه.

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

• يجب تفعيل إضافة XR_ANDROID_face_tracking قبل استدعاء xrDestroyFaceTrackerANDROID
• يجب أن يكون faceTracker معرّف XrFaceTrackerANDROID صالحًا

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

• يجب مزامنة faceTracker وأي أسماء معرّفات للأطفال خارجيًا

رموز الإرجاع

تم بنجاح

• XR_SUCCESS

Failure

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID

التحقّق من معايرة الوجه

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

XrResult xrGetFaceCalibrationStateANDROID(
    XrFaceTrackerANDROID                        faceTracker,
    XrBool32*                                   faceIsCalibratedOutput);

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

• ‫faceTracker هو XrFaceTrackerANDROID تم إنشاؤه سابقًا باستخدام xrCreateFaceTrackerANDROID.
• يشير faceIsCalibratedOutput إلى ما إذا تمّت معايرة أداة تتبُّع الوجه أم لا.

يمكن للتطبيق التحقّق من حالة معايرة الوجه باستخدام الدالة xrGetFaceCalibrationStateANDROID.

عندما تكون خدمة التتبُّع لا تزال قيد التهيئة، قد تعرض وقت التشغيل القيمة XR_ERROR_SERVICE_NOT_READY_ANDROID من xrGetFaceCalibrationStateANDROID للإشارة إلى أنّ التطبيق يمكنه إعادة المحاولة لاحقًا.

إذا كان النظام لا يتيح معايرة الوجه، ستعرض الدالة xrGetFaceCalibrationStateANDROID القيمة XR_ERROR_FEATURE_UNSUPPORTED. بخلاف ذلك، يمكن ضبط faceIsCalibratedOutput على XR_TRUE لعكس حالة معايرة الوجه.

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

• يجب تفعيل الإضافة XR_ANDROID_face_tracking قبل استدعاء xrGetFaceCalibrationStateANDROID
• يجب أن يكون faceTracker معرّف XrFaceTrackerANDROID صالحًا
• يجب أن يكون faceIsCalibratedOutput مؤشرًا إلى قيمة XrBool32

رموز الإرجاع

تم بنجاح

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Failure

• 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_SERVICE_NOT_READY_ANDROID

الحصول على تعابير الوجه

تعرض الدالة xrGetFaceStateANDROID أشكال المزج الخاصة بتعبيرات الوجه في وقت معيّن.

XrResult xrGetFaceStateANDROID(
    XrFaceTrackerANDROID                        faceTracker,
    const XrFaceStateGetInfoANDROID*            getInfo,
    XrFaceStateANDROID*                         faceStateOutput);

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

• ‫faceTracker هو XrFaceTrackerANDROID تم إنشاؤه سابقًا باستخدام xrCreateFaceTrackerANDROID.
• ‫getInfo هو مؤشر إلى XrFaceStateGetInfoANDROID يصف المعلومات المطلوب الحصول عليها بشأن تعابير الوجه.
• ‫faceStateOutput هو مؤشر إلى XrFaceStateANDROID يتلقّى حالة تتبُّع الوجه وتعبيرات الوجه التي تم عرضها.

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

• يجب تفعيل الإضافة XR_ANDROID_face_tracking قبل استدعاء xrGetFaceStateANDROID
• يجب أن يكون faceTracker معرّف XrFaceTrackerANDROID صالحًا
• يجب أن يكون getInfo مؤشرًا إلى بنية XrFaceStateGetInfoANDROID صالحة
• يجب أن يكون faceStateOutput مؤشرًا إلى بنية XrFaceStateANDROID.

رموز الإرجاع

تم بنجاح

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Failure

• 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

يصف البنية XrFaceStateGetInfoANDROID المعلومات التي يجب الحصول عليها بشأن تعابير الوجه.

typedef struct XrFaceStateGetInfoANDROID {
    XrStructureType    type;
    void*              next;
    XrTime             time;
} XrFaceStateGetInfoANDROID;

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

• ‫type هو XrStructureType لهذا الهيكل.
• next هو NULL أو مؤشر إلى البنية التالية في سلسلة البنية. لم يتم تحديد أي بنى من هذا النوع في OpenXR الأساسية أو في هذه الإضافة.
• ‫time هو XrTime يتم فيه طلب تعابير الوجه.

يجب أن تطلب التطبيقات وقتًا مساويًا لوقت العرض المتوقّع للإطار المعروض.

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

• يجب تفعيل الإضافة XR_ANDROID_face_tracking قبل استخدام XrFaceStateGetInfoANDROID
• يجب أن يكون type XR_TYPE_FACE_STATE_GET_INFO_ANDROID
• يجب أن تكون قيمة next NULL أو مؤشرًا صالحًا إلى البنية التالية في سلسلة البِنى

تعرض بنية XrFaceStateANDROID حالة تتبُّع الوجه وتعبيرات الوجه.

typedef struct XrFaceStateANDROID {
    XrStructureType               type;
    void*                         next;
    uint32_t                      parametersCapacityInput;
    uint32_t                      parametersCountOutput;
    float*                        parameters;
    XrFaceTrackingStateANDROID    faceTrackingState;
    XrTime                        sampleTime;
    XrBool32                      isValid;
    uint32_t                      regionConfidencesCapacityInput;
    uint32_t                      regionConfidencesCountOutput;
    float*                        regionConfidences;
} XrFaceStateANDROID;

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

• ‫type هو XrStructureType لهذا الهيكل.
• next هو NULL أو مؤشر إلى البنية التالية في سلسلة البنية. لم يتم تحديد أي بنى من هذا النوع في OpenXR الأساسية أو في هذه الإضافة.
• ‫parametersCapacityInput هي uint32_t تصف سعة مصفوفة parameters، أو 0 للإشارة إلى طلب استرداد السعة المطلوبة.
• ‫parametersCountOutput هو uint32_t يصف عدد parameters، أو السعة المطلوبة في حال عدم كفاية parametersCapacityInput.
• parameters هو مؤشر إلى مصفوفة float تم تخصيصها بواسطة التطبيق وسيتم ملؤها بأوزان أشكال المزج الخاصة بتعبيرات الوجه.
• ‫faceTrackingState هي XrFaceTrackingStateANDROID لحالة صلاحية ميزة تتبُّع الوجه.
• sampleTime هو وقت XrTime يتم فيه تتبُّع التعبيرات التي تم عرضها أو استقراؤها. وهي تساوي الوقت الذي تم فيه طلب أوزان التعبير إذا كان الاستقراء في ذلك الوقت ناجحًا.
• يشير isValid إلى ما إذا كانت البيانات صالحة حتى لو لم تكن من الإطار الحالي.
• ‫regionConfidencesCapacityInput هي uint32_t تصف سعة مصفوفة regionConfidences، أو 0 للإشارة إلى طلب استرداد السعة المطلوبة.
• ‫regionConfidencesCountOutput هو uint32_t يصف عدد regionConfidences، أو السعة المطلوبة في حال عدم كفاية regionConfidencesCapacityInput.
• regionConfidences هو مؤشر إلى صفيف float تم تخصيصه للتطبيق، وسيتم ملؤه بقيم الثقة لكل منطقة من الوجه.
• راجِع قسم مَعلمات حجم المخزن المؤقت للحصول على وصف تفصيلي حول كيفية استرداد حجم parameters وregionConfidences المطلوبَين.

يمكن للتطبيق تعيين parametersCapacityInput على XR_FACE_PARAMETER_COUNT_ANDROID للحصول على تعابير الوجه التي يتم فهرستها حسب XrFaceParameterIndicesANDROID.

تمثّل القيم المعروضة parameters أوزان أشكال المزج الخاصة بتعبيرات الوجه الحالية.

سيتم ترتيب عمليات تعديل مصفوفة parameters بحيث يمكن للتطبيق فهرسة العناصر باستخدام تعداد تعابير الوجه المقابل (مثل XrFaceParameterIndicesANDROID).

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

• يجب تفعيل إضافة XR_ANDROID_face_tracking قبل استخدام XrFaceStateANDROID
• يجب أن يكون type XR_TYPE_FACE_STATE_ANDROID
• يجب أن تكون قيمة next NULL أو مؤشرًا صالحًا إلى البنية التالية في سلسلة البِنى
• إذا لم يكن parametersCapacityInput 0, parameters، يجب أن يكون مؤشرًا إلى مصفوفة من قيم parametersCapacityInput float
• إذا لم يكن regionConfidencesCapacityInput 0, regionConfidences، يجب أن يكون مؤشرًا إلى مصفوفة من قيم regionConfidencesCapacityInput float
• يجب أن تكون faceTrackingState قيمة صالحة لـ XrFaceTrackingStateANDROID

يحدّد التعداد XrFaceTrackingStateANDROID الحالات المختلفة لأداة تتبُّع الوجه.

typedef enum XrFaceTrackingStateANDROID {
    XR_FACE_TRACKING_STATE_PAUSED_ANDROID = 0,
    XR_FACE_TRACKING_STATE_STOPPED_ANDROID = 1,
    XR_FACE_TRACKING_STATE_TRACKING_ANDROID = 2
} XrFaceTrackingStateANDROID;

تحمل القيم المُعدّدة المعاني التالية:

مناطق الثقة

تقدّم إضافة XR_ANDROID_face_tracking أيضًا قيم ثقة لثلاث مناطق في الوجه: العين اليسرى والعين اليمنى والجزء السفلي من الوجه. تشير هذه القيم، التي تتراوح بين 0 (لا توجد ثقة) و1 (أعلى ثقة)، إلى دقة تتبُّع الوجه لكل منطقة.

يمكنك استخدام قيم الثقة هذه لإيقاف أشكال المزج تدريجيًا أو تطبيق فلاتر مرئية (مثل التمويه) على منطقة الوجه المقابلة. للحصول على تحكّم أساسي في التفعيل والإيقاف، ننصحك باستخدام حدّ 0.3 لإيقاف أشكال المزج بالكامل في منطقة الوجه المعنية.

يمثّل الجزء "أسفل الوجه" كل ما يقع تحت العينين، بما في ذلك الفم والذقن والخد والأنف. تشمل منطقة العينين العينين ومنطقة الحاجبين.

يوضّح الجدول التالي أشكال المزج المرتبطة بكل منطقة ثقة:

اتفاقيات أشكال المزج

يحدّد هذا الامتداد 68 شكلًا مختلطًا من خلال XR_FACE_PARAMETER_COUNT_ANDROID، لتنسيق G-Nome المخفّض. كل مَعلمة في هذا النوع المحدود هي فهرس في مصفوفة أشكال الدمج التي تكون قيمها من النوع float ويتم تطبيع وقت التشغيل إلى 1 - 0.

typedef enum XrFaceParameterIndicesANDROID {
    XR_FACE_PARAMETER_INDICES_BROW_LOWERER_L_ANDROID = 0,
    XR_FACE_PARAMETER_INDICES_BROW_LOWERER_R_ANDROID = 1,
    XR_FACE_PARAMETER_INDICES_CHEEK_PUFF_L_ANDROID = 2,
    XR_FACE_PARAMETER_INDICES_CHEEK_PUFF_R_ANDROID = 3,
    XR_FACE_PARAMETER_INDICES_CHEEK_RAISER_L_ANDROID = 4,
    XR_FACE_PARAMETER_INDICES_CHEEK_RAISER_R_ANDROID = 5,
    XR_FACE_PARAMETER_INDICES_CHEEK_SUCK_L_ANDROID = 6,
    XR_FACE_PARAMETER_INDICES_CHEEK_SUCK_R_ANDROID = 7,
    XR_FACE_PARAMETER_INDICES_CHIN_RAISER_B_ANDROID = 8,
    XR_FACE_PARAMETER_INDICES_CHIN_RAISER_T_ANDROID = 9,
    XR_FACE_PARAMETER_INDICES_DIMPLER_L_ANDROID = 10,
    XR_FACE_PARAMETER_INDICES_DIMPLER_R_ANDROID = 11,
    XR_FACE_PARAMETER_INDICES_EYES_CLOSED_L_ANDROID = 12,
    XR_FACE_PARAMETER_INDICES_EYES_CLOSED_R_ANDROID = 13,
    XR_FACE_PARAMETER_INDICES_EYES_LOOK_DOWN_L_ANDROID = 14,
    XR_FACE_PARAMETER_INDICES_EYES_LOOK_DOWN_R_ANDROID = 15,
    XR_FACE_PARAMETER_INDICES_EYES_LOOK_LEFT_L_ANDROID = 16,
    XR_FACE_PARAMETER_INDICES_EYES_LOOK_LEFT_R_ANDROID = 17,
    XR_FACE_PARAMETER_INDICES_EYES_LOOK_RIGHT_L_ANDROID = 18,
    XR_FACE_PARAMETER_INDICES_EYES_LOOK_RIGHT_R_ANDROID = 19,
    XR_FACE_PARAMETER_INDICES_EYES_LOOK_UP_L_ANDROID = 20,
    XR_FACE_PARAMETER_INDICES_EYES_LOOK_UP_R_ANDROID = 21,
    XR_FACE_PARAMETER_INDICES_INNER_BROW_RAISER_L_ANDROID = 22,
    XR_FACE_PARAMETER_INDICES_INNER_BROW_RAISER_R_ANDROID = 23,
    XR_FACE_PARAMETER_INDICES_JAW_DROP_ANDROID = 24,
    XR_FACE_PARAMETER_INDICES_JAW_SIDEWAYS_LEFT_ANDROID = 25,
    XR_FACE_PARAMETER_INDICES_JAW_SIDEWAYS_RIGHT_ANDROID = 26,
    XR_FACE_PARAMETER_INDICES_JAW_THRUST_ANDROID = 27,
    XR_FACE_PARAMETER_INDICES_LID_TIGHTENER_L_ANDROID = 28,
    XR_FACE_PARAMETER_INDICES_LID_TIGHTENER_R_ANDROID = 29,
    XR_FACE_PARAMETER_INDICES_LIP_CORNER_DEPRESSOR_L_ANDROID = 30,
    XR_FACE_PARAMETER_INDICES_LIP_CORNER_DEPRESSOR_R_ANDROID = 31,
    XR_FACE_PARAMETER_INDICES_LIP_CORNER_PULLER_L_ANDROID = 32,
    XR_FACE_PARAMETER_INDICES_LIP_CORNER_PULLER_R_ANDROID = 33,
    XR_FACE_PARAMETER_INDICES_LIP_FUNNELER_LB_ANDROID = 34,
    XR_FACE_PARAMETER_INDICES_LIP_FUNNELER_LT_ANDROID = 35,
    XR_FACE_PARAMETER_INDICES_LIP_FUNNELER_RB_ANDROID = 36,
    XR_FACE_PARAMETER_INDICES_LIP_FUNNELER_RT_ANDROID = 37,
    XR_FACE_PARAMETER_INDICES_LIP_PRESSOR_L_ANDROID = 38,
    XR_FACE_PARAMETER_INDICES_LIP_PRESSOR_R_ANDROID = 39,
    XR_FACE_PARAMETER_INDICES_LIP_PUCKER_L_ANDROID = 40,
    XR_FACE_PARAMETER_INDICES_LIP_PUCKER_R_ANDROID = 41,
    XR_FACE_PARAMETER_INDICES_LIP_STRETCHER_L_ANDROID = 42,
    XR_FACE_PARAMETER_INDICES_LIP_STRETCHER_R_ANDROID = 43,
    XR_FACE_PARAMETER_INDICES_LIP_SUCK_LB_ANDROID = 44,
    XR_FACE_PARAMETER_INDICES_LIP_SUCK_LT_ANDROID = 45,
    XR_FACE_PARAMETER_INDICES_LIP_SUCK_RB_ANDROID = 46,
    XR_FACE_PARAMETER_INDICES_LIP_SUCK_RT_ANDROID = 47,
    XR_FACE_PARAMETER_INDICES_LIP_TIGHTENER_L_ANDROID = 48,
    XR_FACE_PARAMETER_INDICES_LIP_TIGHTENER_R_ANDROID = 49,
    XR_FACE_PARAMETER_INDICES_LIPS_TOWARD_ANDROID = 50,
    XR_FACE_PARAMETER_INDICES_LOWER_LIP_DEPRESSOR_L_ANDROID = 51,
    XR_FACE_PARAMETER_INDICES_LOWER_LIP_DEPRESSOR_R_ANDROID = 52,
    XR_FACE_PARAMETER_INDICES_MOUTH_LEFT_ANDROID = 53,
    XR_FACE_PARAMETER_INDICES_MOUTH_RIGHT_ANDROID = 54,
    XR_FACE_PARAMETER_INDICES_NOSE_WRINKLER_L_ANDROID = 55,
    XR_FACE_PARAMETER_INDICES_NOSE_WRINKLER_R_ANDROID = 56,
    XR_FACE_PARAMETER_INDICES_OUTER_BROW_RAISER_L_ANDROID = 57,
    XR_FACE_PARAMETER_INDICES_OUTER_BROW_RAISER_R_ANDROID = 58,
    XR_FACE_PARAMETER_INDICES_UPPER_LID_RAISER_L_ANDROID = 59,
    XR_FACE_PARAMETER_INDICES_UPPER_LID_RAISER_R_ANDROID = 60,
    XR_FACE_PARAMETER_INDICES_UPPER_LIP_RAISER_L_ANDROID = 61,
    XR_FACE_PARAMETER_INDICES_UPPER_LIP_RAISER_R_ANDROID = 62,
    XR_FACE_PARAMETER_INDICES_TONGUE_OUT_ANDROID = 63,
    XR_FACE_PARAMETER_INDICES_TONGUE_LEFT_ANDROID = 64,
    XR_FACE_PARAMETER_INDICES_TONGUE_RIGHT_ANDROID = 65,
    XR_FACE_PARAMETER_INDICES_TONGUE_UP_ANDROID = 66,
    XR_FACE_PARAMETER_INDICES_TONGUE_DOWN_ANDROID = 67
} XrFaceParameterIndicesANDROID;

المؤشر	الاسم	الصورة المرجعية
0	BROW_LOWERER_L
1	BROW_LOWERER_R
2	CHEEK_PUFF_L
3	CHEEK_PUFF_R
4	CHEEK_RAISER_L
5	CHEEK_RAISER_R
6	CHEEK_SUCK_L
7	CHEEK_SUCK_R
8	CHIN_RAISER_B
9	CHIN_RAISER_T
10	DIMPLER_L
11	DIMPLER_R
12	EYES_CLOSED_L
13	EYES_CLOSED_R
14	EYES_LOOK_DOWN_L
15	EYES_LOOK_DOWN_R
16	EYES_LOOK_LEFT_L
17	EYES_LOOK_LEFT_R
18	EYES_LOOK_RIGHT_L
19	EYES_LOOK_RIGHT_R
20	EYES_LOOK_UP_L
21	EYES_LOOK_UP_R
22	INNER_BROW_RAISER_L
23	INNER_BROW_RAISER_R
24	JAW_DROP
25	JAW_SIDEWAYS_LEFT
26	JAW_SIDEWAYS_RIGHT
27	JAW_THRUST
28	LID_TIGHTENER_L
29	LID_TIGHTENER_R
30	LIP_CORNER_DEPRESSOR_L
31	LIP_CORNER_DEPRESSOR_R
32	LIP_CORNER_PULLER_L
33	LIP_CORNER_PULLER_R
34	LIP_FUNNELER_LB
35	LIP_FUNNELER_LT
36	LIP_FUNNELER_RB
37	LIP_FUNNELER_RT
38	LIP_PRESSOR_L
39	LIP_PRESSOR_R
40	LIP_PUCKER_L
41	LIP_PUCKER_R
42	LIP_STRETCHER_L
43	LIP_STRETCHER_R
44	LIP_SUCK_LB
45	LIP_SUCK_LT
46	LIP_SUCK_RB
47	LIP_SUCK_RT
48	LIP_TIGHTENER_L
49	LIP_TIGHTENER_R
50	LIPS_TOWARD
51	LOWER_LIP_DEPRESSOR_L
52	LOWER_LIP_DEPRESSOR_R
53	MOUTH_LEFT
54	MOUTH_RIGHT
55	NOSE_WRINKLER_L
56	NOSE_WRINKLER_R
57	OUTER_BROW_RAISER_L
58	OUTER_BROW_RAISER_R
59	UPPER_LID_RAISER_L
60	UPPER_LID_RAISER_R
61	UPPER_LIP_RAISER_L
62	UPPER_LIP_RAISER_R
63	TONGUE_OUT
64	TONGUE_LEFT
65	TONGUE_RIGHT
66	TONGUE_UP
67	TONGUE_DOWN

مثال على الرمز البرمجي لتتبُّع الوجه

يوضّح رمز المثال التالي كيفية الحصول على جميع أوزان أشكال المزج الخاصة بتعبيرات الوجه.

XrInstance instance; // previously initialized
XrSystemId systemId; // previously initialized
XrSession session; // previously initialized, e.g. created at app startup.

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrCreateFaceTrackerANDROID xrCreateFaceTrackerANDROID; // previously initialized
PFN_xrDestroyFaceTrackerANDROID xrDestroyFaceTrackerANDROID; // previously initialized
PFN_xrGetFaceStateANDROID xrGetFaceStateANDROID; // previously initialized
PFN_xrGetFaceCalibrationStateANDROID xrGetFaceCalibrationStateANDROID; // previously initialized

// Inspect system capability
XrSystemProperties properties{XR_TYPE_SYSTEM_PROPERTIES};
XrSystemFaceTrackingPropertiesANDROID faceTrackingProperties{XR_TYPE_SYSTEM_FACE_TRACKING_PROPERTIES_ANDROID};
properties.next = &faceTrackingProperties;
CHK_XR(xrGetSystemProperties(instance, systemId, &properties));
if (!faceTrackingProperties.supportsFaceTracking) {
  // face tracking is not supported.
  return;
}

XrFaceTrackerANDROID faceTracker;
XrFaceTrackerCreateInfoANDROID
        createInfo{.type = XR_TYPE_FACE_TRACKER_CREATE_INFO_ANDROID,
                    .next = nullptr};
CHK_XR(xrCreateFaceTrackerANDROID(session, &createInfo, &faceTracker));

// If the system supports face calibration:
XrBool32 isCalibrated;
CHK_XR(xrGetFaceCalibrationStateANDROID(faceTracker, &isCalibrated));
if (!isCalibrated) {
    // Redirect the user to system calibration setting.
}

XrFaceStateANDROID faceState;
float faceExpressionParameters[XR_FACE_PARAMETER_COUNT_ANDROID];
faceState.type = XR_TYPE_FACE_STATE_ANDROID;
faceState.next = nullptr;
faceState.parametersCapacityInput = XR_FACE_PARAMETER_COUNT_ANDROID;
faceState.parameters = faceExpressionParameters;
float regionConfidences[XR_FACE_REGION_CONFIDENCE_COUNT_ANDROID];
faceState.regionConfidencesCapacityInput = XR_FACE_REGION_CONFIDENCE_COUNT_ANDROID;
faceState.regionConfidences = regionConfidences;

while (1) {
    // ...
    // For every frame in the frame loop
    // ...
    XrFrameState frameState; // previously returned from xrWaitFrame

    XrFaceStateGetInfoANDROID faceGetInfo{
            .type = XR_TYPE_FACE_STATE_GET_INFO_ANDROID,
            .next = nullptr,
            .time = frameState.predictedDisplayTime,
    };

    CHK_XR(xrGetFaceStateANDROID(faceTracker, &faceGetInfo, &faceState));
    if (faceState.isValid) {
        for (uint32_t i = 0; i < XR_FACE_PARAMETER_COUNT_ANDROID; ++i) {
            // parameters[i] contains a weight of specific blend shape
        }
        for (uint32_t i = 0; i < XR_FACE_REGION_CONFIDENCE_COUNT_ANDROID; ++i) {
            // regionConfidences[i] contains a confidence value of a specific region
        }
    }
}

// after usage
CHK_XR(xrDestroyFaceTrackerANDROID(faceTracker));

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

• XrFaceTrackerANDROID

ثوابت التعداد الجديدة

• XR_FACE_PARAMETER_COUNT_ANDROID

تمت إضافة ما يلي إلى تعداد XrObjectType:

• XR_OBJECT_TYPE_FACE_TRACKER_ANDROID

تمت إضافة ما يلي إلى تعداد XrStructureType:

• XR_TYPE_FACE_TRACKER_CREATE_INFO_ANDROID
• XR_TYPE_FACE_STATE_GET_INFO_ANDROID
• XR_TYPE_FACE_STATE_ANDROID
• XR_TYPE_SYSTEM_FACE_TRACKING_PROPERTIES_ANDROID

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

• XrFaceParameterIndicesANDROID
• XrFaceTrackingStateANDROID

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

• XrFaceTrackerCreateInfoANDROID
• XrFaceStateGetInfoANDROID
• XrFaceStateANDROID
• XrSystemFaceTrackingPropertiesANDROID

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

• xrCreateFaceTrackerANDROID
• xrDestroyFaceTrackerANDROID
• xrGetFaceStateANDROID
• xrGetFaceCalibrationStateANDROID

المشاكل

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

• المراجعة 1، 05-09-2024 (ليڤانا تشين)
  • الوصف الأوّلي للإضافة
• Revision 2, 2025-04-01 (Kenny Vercaemer)
  • تمت إضافة مناطق ثقة الوجه
• المراجعة 3، 2025-06-04 (Levana Chen)
  • تمت إضافة رمز خطأ جديد.

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