XR_ANDROID_face_tracking_data_source

מחרוזת שם

XR_ANDROID_face_tracking_data_source

סוג התוסף

הרחבת המכונה

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

707

Revision

1

סטטוס האישור

לא אושר

תלות בתוסף ובגרסה

XR_ANDROID_face_tracking

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

2025-12-16

סטטוס כתובת ה-IP

לא ידוע על תלונות על הפרת זכויות יוצרים שקשורות לכתובות 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

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

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.
  • נדרשת הרשאת android.permission.RECORD_AUDIO לאפליקציה XR_FACE_TRACKING_DATA_SOURCE_AUDIO_ANDROID.
  • ‫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 must be a pointer to an array of requestedDataSourceCount valid XrFaceTrackingDataSourceANDROID values
  • ‫ הפרמטר 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, ‏ 07.10.2024 (קני ורקאמר)

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