XR_ANDROID_face_tracking_data_source

מחרוזת שם

XR_ANDROID_face_tracking_data_source

סוג התוסף

תוסף למכונה

מספר השלוחה הרשום

707

גרסה

1

סטטוס האישור

לא אושר

תלויות של תוספים וגרסאות

XR_ANDROID_face_tracking

תאריך השינוי האחרון

2025-12-16

סטטוס IP

אין תלונות ידועות על הפרת קניין רוחני.

שותפים ביצירת התוכן

Kenny Vercaemer, Google
Yinglei Zhang, Google
Nihav Jain, Google
Spencer Quin, 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;

אלה המשמעויות של הערכים:

תיאור הטיפוס בן המנייה (enum)

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 מתאר את מקורות הנתונים ליצירת נקודת אחיזה (handle) של 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 חייב להיות מצביע למערך של ערכי XrFaceTrackingDataSourceANDROID תקינים מסוג requestedDataSourceCount
  • ‫ הפרמטר requestedDataSourceCount חייב להיות גדול מ-0

הרשאות

אפליקציות ל-Android חייבות לכלול במניפסט שלהן את ההרשאות שהן מתכוונות לבקש. ההרשאה android.permission.FACE_TRACKING נחשבת להרשאה מסוכנת. ההרשאה android.permission.RECORD_AUDIO נחשבת להרשאה מסוכנת. האפליקציה חייבת לבקש את ההרשאות בזמן הריצה כדי להשתמש בפונקציות האלה:

(רמת הגנה: מסוכן)

המבנה של XrFaceTrackingDataSourceStateANDROID מתואר כך:

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

תיאורי חברים

  • ‫type הוא ה-XrStructureType של המבנה הזה.
  • ‫next הוא NULL או מצביע למבנה הבא בשרשרת מבנים. מבנים כאלה לא מוגדרים ב-OpenXR או בתוסף הזה.
  • ‫dataSource הוא XrFaceTrackingDataSourceANDROID שמשמש ליצירת נתוני המעקב אחרי הבעות הפנים.

אפליקציה יכולה לשרשר מבנה XrFaceTrackingDataSourceStateANDROID למבנה XrFaceStateANDROID שמועבר אל xrGetFaceStateANDROID כדי לשלוח שאילתה למקור הנתונים שמשמש ליצירת נתוני המעקב אחרי הבעות הפנים של הקריאה הזו.

שימוש תקין (משתמע)

קוד לדוגמה למעקב אחרי הבעות הפנים עם מקור נתונים.

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, 2024-10-07 (Kenny Vercaemer)

    • תיאור התוסף הראשוני