Android XR for OpenXR | Android Developers

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

XR_ANDROID_face_tracking_data_source

Name String

XR_ANDROID_face_tracking_data_source

Extension Type

Instance extension

Registered Extension Number

707

Revision

Ratification Status

Not ratified

Extension and Version Dependencies

XR_ANDROID_face_tracking

Last Modified Date

2025-12-16

IP Status

No known IP claims.

المساهمون

Kenny Vercaemer, Google
Yinglei Zhang, Google
Nihav Jain, Google
Spencer Quin, Google

نظرة عامة

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

Query supported data sources

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

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

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

Parameter Descriptions

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 .

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

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

Valid Usage (Implicit)

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

Return Codes

Success

XR_SUCCESS

Failure

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;

للمعدِّدات المعاني التالية:

Enum Description

XR_FACE_TRACKING_DATA_SOURCE_IMAGE_ANDROID

Indicates that this config uses image data

XR_FACE_TRACKING_DATA_SOURCE_AUDIO_ANDROID

Indicates that this config uses audio data

XR_FACE_TRACKING_DATA_SOURCE_MULTIMODAL_ANDROID

Indicates that this config uses image and audio data

Configuring data sources

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

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

Member Descriptions

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.

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

Valid Usage (Implicit)

يجب تفعيل الإضافة 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;

Member Descriptions

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

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

Valid Usage (Implicit)

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

Example code for face tracking with data source.

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));

المشاكل

Version History

Revision 1, 2024-10-07 (Kenny Vercaemer)
- Initial extension description