XR_ANDROID_face_tracking_data_source

سلسلة الاسم

XR_ANDROID_face_tracking_data_source

نوع الإضافة

إضافة مثيل

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

707

المراجعة

1

حالة التصديق

لم تتم المصادقة

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

XR_ANDROID_face_tracking

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

2025-12-16

حالة عنوان IP

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

المساهمون

"كيني فيركامير"، Google
"ينغلي تشانغ"، Google
"نيهاف جاين"، Google
"سبنسر كوين"، Google

نظرة عامة

يتيح هذا الامتداد للتطبيقات الحصول على بيانات تتبّع تعابير الوجه من مصادر بيانات متعددة.

مصادر البيانات المتوافقة مع طلبات البحث

يجب أن تستدعي التطبيقات الدالة xrEnumerateFaceTrackingDataSourcesANDROID للحصول على قائمة بمصادر بيانات تتبُّع حركات الوجه المتوافقة.

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

XrResult                                                                                 xrEnumerateFaceTrackingDataSourcesANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    supportedDataSourcesInputCapacity,
    uint32_t*                                   supportedDataSourcesOutputCount,
    XrFaceTrackingDataSourceANDROID*            supportedDataSources);

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

• ‫instance هو معرّف فريد لكائن XrInstance .
• ‫systemId هو XrSystemId الذي سيتم تعداد مصادر بيانات تتبُّع تعابير الوجه له.
• supportedDataSourcesInputCapacity هي سعة مصفوفة supportedDataSources، أو 0 للإشارة إلى طلب استرداد السعة المطلوبة.
• supportedDataSourcesOutputCount هو عدد مصادر البيانات المتوافقة، أو السعة المطلوبة في حال عدم كفاية supportedDataSourcesInputCapacity.
• ‫supportedDataSources هو صفيف من XrFaceTrackingDataSourceANDROID . يمكن أن تكون القيمة NULL إذا كانت القيمة supportedDataSourcesInputCapacity هي 0.
• راجِع قسم مَعلمات حجم المخزن المؤقت للحصول على وصف تفصيلي حول استرداد حجم supportedDataSources المطلوب.

يمكن للتطبيق تعداد قائمة مصادر البيانات التي يتيحها النظام من خلال استدعاء الدالة xrEnumerateFaceTrackingDataSourcesANDROID.

إذا كانت قيمة XrSystemFaceTrackingPropertiesANDROID :: supportsFaceTracking هي XR_TRUE، يجب أن تعرض بيئة التشغيل أيضًا القيمة XR_FACE_TRACKING_DATA_SOURCE_IMAGE_ANDROID من xrEnumerateFaceTrackingDataSourcesANDROID .

إذا عرض وقت التشغيل صفرًا من مصادر البيانات، يعني ذلك أنّه لا يتيح أي نوع من تتبّع تعابير الوجه.

يجب أن تعرض بيئة التشغيل مصادر البيانات بالترتيب من الأعلى جودةً إلى الأقل جودةً.

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

• يجب تفعيل الإضافة XR_ANDROID_face_tracking_data_source قبل استدعاء xrEnumerateFaceTrackingDataSourcesANDROID
• يجب أن يكون instance مقبض XrInstance صالحًا
• يجب أن يكون supportedDataSourcesOutputCount مؤشرًا إلى قيمة uint32_t
• إذا لم يكن supportedDataSourcesInputCapacity هو 0 ، supportedDataSources يجب أن يكون مؤشرًا إلى صفيف من قيم supportedDataSourcesInputCapacity XrFaceTrackingDataSourceANDROID

رموز الإرجاع

تم بنجاح

• XR_SUCCESS

تعذُّر

• XR_ERROR_FEATURE_UNSUPPORTED
• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_SYSTEM_INVALID
• XR_ERROR_VALIDATION_FAILURE

يحدّد التعداد XrFaceTrackingDataSourceANDROID مصادر البيانات المختلفة التي قد يتيحها وقت التشغيل.

typedef enum XrFaceTrackingDataSourceANDROID {
    XR_FACE_TRACKING_DATA_SOURCE_IMAGE_ANDROID = 1,
    XR_FACE_TRACKING_DATA_SOURCE_AUDIO_ANDROID = 2,
    XR_FACE_TRACKING_DATA_SOURCE_MULTIMODAL_ANDROID = 3,
    XR_FACE_TRACKING_DATA_SOURCE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrFaceTrackingDataSourceANDROID;

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

وصف التعداد

XR_FACE_TRACKING_DATA_SOURCE_IMAGE_ANDROID

تشير إلى أنّ هذا الإعداد يستخدم بيانات الصور

XR_FACE_TRACKING_DATA_SOURCE_AUDIO_ANDROID

تشير إلى أنّ هذا الإعداد يستخدم بيانات صوتية

XR_FACE_TRACKING_DATA_SOURCE_MULTIMODAL_ANDROID

تشير إلى أنّ هذا الإعداد يستخدم بيانات الصور والصوت

إعداد مصادر البيانات

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

typedef struct XrFaceTrackingDataSourceInfoANDROID {
    XrStructureType                           type;
    const void*                               next;
    uint32_t                                  requestedDataSourceCount;
    const XrFaceTrackingDataSourceANDROID*    requestedDataSources;
} XrFaceTrackingDataSourceInfoANDROID;

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

• type هو XrStructureType لهذه البنية.
• next هي NULL أو مؤشر إلى البنية التالية في سلسلة البنية. لم يتم تحديد أي بنى من هذا النوع في OpenXR الأساسية أو هذه الإضافة.
• requestedDataSourceCount هو عدد مصادر البيانات التي يطلبها التطبيق.
• ‫requestedDataSources هو صفيف من قيم XrFaceTrackingDataSourceANDROID، يحدّد مصادر البيانات التي يطلبها التطبيق.

يصف البنية XrFaceTrackingDataSourceInfoANDROID مصادر البيانات لإنشاء معرّف XrFaceTrackerANDROID.

يمكن لأحد التطبيقات تمرير بنية XrFaceTrackingDataSourceInfoANDROID في السلسلة التالية من بنية XrFaceTrackerCreateInfoANDROID لطلب مصدر بيانات واحد أو أكثر لتتبُّع الوجه عند استدعاء xrCreateFaceTrackerANDROID .

إذا كان التطبيق يمرّر صفرًا من مصادر البيانات، أو إذا لم يتم تعداد أي من مصادر البيانات بواسطة xrEnumerateFaceTrackingDataSourcesANDROID، يجب أن يعرض وقت التشغيل XR_ERROR_VALIDATION_FAILURE .

إذا لم يمنح المستخدم جميع الأذونات المطلوبة لجميع مصادر البيانات المطلوبة، يجب أن يعرض وقت التشغيل القيمة MUST XR_ERROR_PERMISSION_INSUFFICIENT .

يتم تحديد الأذونات المطلوبة لكل مصدر بيانات على النحو التالي:

• يتطلّب تطبيق "XR_FACE_TRACKING_DATA_SOURCE_IMAGE_ANDROID" الإذن android.permission.FACE_TRACKING.
• يتطلّب تطبيق XR_FACE_TRACKING_DATA_SOURCE_AUDIO_ANDROID الحصول على إذن android.permission.RECORD_AUDIO.
• يتطلّب XR_FACE_TRACKING_DATA_SOURCE_MULTIMODAL_ANDROID الإذنَين android.permission.FACE_TRACKING وandroid.permission.RECORD_AUDIO.

يجب أن يفسّر وقت التشغيل مصفوفة XrFaceTrackingDataSourceInfoANDROID : requestedDataSources كأعلى أولوية إلى أدنى أولوية حسب التطبيق. يجب أن ينتج وقت التشغيل بيانات التتبُّع باستخدام مصدر البيانات الأول المطلوب الذي لا يزال يلتزم بالأذونات المطلوبة. إذا تم إبطال إذن أثناء مدة صلاحية أداة التتبُّع، ما أدّى إلى عدم إمكانية استخدام مصدر البيانات، يجب أن يستمر وقت التشغيل في محاولة استخدام مصدر البيانات التالي ذي الأولوية الأعلى. إذا لم يكن أي من مصادر البيانات المطلوبة قابلاً للاستخدام، يجب أن يضبط وقت التشغيل XrFaceStateANDROID :: isValid على XR_FALSE في طلبات xrGetFaceStateANDROID، ويتم اعتبار الحقول الأخرى غير محدّدة.

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

• يجب تفعيل إضافة XR_ANDROID_face_tracking_data_source قبل استخدام XrFaceTrackingDataSourceInfoANDROID
• يجب أن يكون type XR_TYPE_FACE_TRACKING_DATA_SOURCE_INFO_ANDROID
• يجب أن تكون قيمة next هي NULL أو مؤشرًا صالحًا إلى البنية التالية في سلسلة البِنى
• يجب أن يكون requestedDataSources مؤشرًا إلى مجموعة من قيم XrFaceTrackingDataSourceANDROID الصالحة requestedDataSourceCount
• يجب أن تكون قيمة المَعلمة requestedDataSourceCount أكبر من 0

الأذونات

يجب أن تتضمّن تطبيقات Android الأذونات التي تنوي طلبها في ملف البيان. يُعدّ الإذن android.permission.FACE_TRACKING إذنًا خطيرًا. يُعدّ الإذن android.permission.RECORD_AUDIO إذنًا خطيرًا. يجب أن يطلب التطبيق الأذونات في وقت التشغيل لاستخدام الوظائف التالية:

• xrCreateFaceTrackerANDROID

(مستوى الحماية: خطير)

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

typedef struct XrFaceTrackingDataSourceStateANDROID {
    XrStructureType                    type;
    void*                              next;
    XrFaceTrackingDataSourceANDROID    dataSource;
} XrFaceTrackingDataSourceStateANDROID;

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

• type هو XrStructureType لهذه البنية.
• next هي NULL أو مؤشر إلى البنية التالية في سلسلة البنية. لم يتم تحديد أي بنى من هذا النوع في OpenXR الأساسية أو هذه الإضافة.
• ‫dataSource هو XrFaceTrackingDataSourceANDROID المستخدَم لإنتاج بيانات تتبُّع تعابير الوجه.

يمكن للتطبيق ربط بنية XrFaceTrackingDataSourceStateANDROID ببنية XrFaceStateANDROID يتم تمريرها إلى xrGetFaceStateANDROID للاستعلام عن مصدر البيانات المستخدَم لإنتاج بيانات تتبُّع الوجه لعملية الاستدعاء هذه.

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

• يجب تفعيل إضافة XR_ANDROID_face_tracking_data_source قبل استخدام XrFaceTrackingDataSourceStateANDROID
• يجب أن يكون type XR_TYPE_FACE_TRACKING_DATA_SOURCE_STATE_ANDROID
• يجب أن تكون قيمة next هي NULL أو مؤشرًا صالحًا إلى البنية التالية في سلسلة البِنى
• يجب أن تكون قيمة dataSource صالحة XrFaceTrackingDataSourceANDROID

مثال على رمز تتبُّع تعابير الوجه باستخدام مصدر بيانات

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_xrEnumerateFaceTrackingDataSourcesANDROID xrEnumerateFaceTrackingDataSourcesANDROID; // previously initialized
bool (*requestPermission)(const char* permission);

// Inspect data sources supported by the system.
uint32_t dataSourcesCount = 0;
CHK_XR(xrEnumerateFaceTrackingDataSourcesANDROID(instance, systemId, dataSourcesCount,
       &dataSourcesCount, nullptr));
std::vector<XrFaceTrackingDataSourceANDROID> dataSources(dataSourcesCount);
CHK_XR(xrEnumerateFaceTrackingDataSourcesANDROID(instance, systemId, dataSourcesCount,
       &dataSourcesCount, dataSources.data()));

if (dataSources.size() == 0) {
  // System does not support face tracking at all ...
  return;
}

auto requestDataSourcePermissions = [requestPermission](XrFaceTrackingDataSourceANDROID dataSource) {
  switch (dataSource) {
    case XR_FACE_TRACKING_DATA_SOURCE_IMAGE_ANDROID:
      return requestPermission("android.permission.FACE_TRACKING");
    case XR_FACE_TRACKING_DATA_SOURCE_AUDIO_ANDROID:
      return requestPermission("android.permission.RECORD_AUDIO");
    case XR_FACE_TRACKING_DATA_SOURCE_MULTIMODAL_ANDROID:
      return requestPermission("android.permission.FACE_TRACKING") &&
             requestPermission("android.permission.RECORD_AUDIO");
    default:
      return false;
  }
};

// Request permissions and remove data sources that are not granted.
for (uint32_t i = 0; i < dataSources.size();) {
  if (requestDataSourcePermissions(dataSources[i])) {
    ++i;
    continue;
  }

  dataSources.erase(dataSources.begin() + i);
}

if (dataSources.size() == 0) {
  // User denied all permissions, cannot create face tracker.
  return;
}

// Create face tracker with requested data sources.
XrFaceTrackerANDROID faceTracker;
XrFaceTrackingDataSourceInfoANDROID
        faceTrackerModeInfo{.type = XR_TYPE_FACE_TRACKING_DATA_SOURCE_INFO_ANDROID,
                       .next = nullptr,
                       .requestedDataSourceCount = static_cast<uint32_t>(
                           dataSources.size()),
                       .requestedDataSources = dataSources.data()};
XrFaceTrackerCreateInfoANDROID
        createInfo{.type = XR_TYPE_FACE_TRACKER_CREATE_INFO_ANDROID,
                    .next = &faceTrackerModeInfo};
CHK_XR(xrCreateFaceTrackerANDROID(session, &createInfo, &faceTracker));

XrFaceTrackingDataSourceStateANDROID dataSourceState{
  .type = XR_TYPE_FACE_TRACKING_DATA_SOURCE_STATE_ANDROID,
  .next = nullptr};
XrFaceStateANDROID faceState;
float faceExpressionParameters[XR_FACE_PARAMETER_COUNT_ANDROID];
faceState.type = XR_TYPE_FACE_STATE_ANDROID;
faceState.next = &dataSourceState;
faceState.parametersCapacityInput = XR_FACE_PARAMETER_COUNT_ANDROID;
faceState.parameters = faceExpressionParameters;

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
        }

        // If the system changes data source because of permission changes,
        // handle the new data source ...
        switch (dataSourceState.dataSource) {
          default:
            break;
        }
    }
}

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

المشاكل

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

• المراجعة 1، ‎07-10-2024 (Kenny Vercaemer)

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