XR_ANDROID_face_tracking_data_source

Name String

XR_ANDROID_face_tracking_data_source

نوع الإضافة

إضافة مثيل

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

707

المراجعة

1

حالة التصديق

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

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

XR_ANDROID_face_tracking

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

2025-12-16

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

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

المساهمون

"كيني فيركايمر"، 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

رموز الإرجاع

Success

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

إذا لم يمنح المستخدم جميع الأذونات المطلوبة لجميع مصادر البيانات المطلوبة، يجب أن يعرض وقت التشغيل 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 يجب أن يكون مؤشرًا إلى مصفوفة من قيم requestedDataSourceCount صالحة لـ XrFaceTrackingDataSourceANDROID
• يجب أن تكون المَعلمة 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 (كيني فيركايمر)

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