منبع داده ردیابی چهره XR_ANDROID

رشته نام

XR_ANDROID_face_tracking_data_source

نوع افزونه

افزونه نمونه

شماره داخلی ثبت شده

۷۰۷

بازنگری

۱

وضعیت تصویب

تصویب نشده

وابستگی‌های افزونه و نسخه

XR_ANDROID_face_tracking

آخرین تاریخ اصلاح

۲۰۲۵-۱۲-۱۶

وضعیت آی‌پی

هیچ ادعای مالکیت معنوی شناخته‌شده‌ای وجود ندارد.

مشارکت‌کنندگان

کنی ورکامر، گوگل
Yinglei Zhang، گوگل
نیهاو جین، گوگل
اسپنسر کوئین، گوگل

نمای کلی

این افزونه به برنامه‌ها امکان می‌دهد داده‌های ردیابی چهره را از منابع داده متعدد دریافت کنند.

منابع داده پشتیبانی شده توسط پرس و جو

برنامه‌ها باید 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 است. اگر supportedDataSourcesInputCapacity برابر با ۰ باشد، می‌تواند NULL باشد.
  • برای توضیحات مفصل در مورد بازیابی اندازه 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 توصیف می‌کند.

یک برنامه ممکن است هنگام فراخوانی xrCreateFaceTrackerANDROID، ساختار XrFaceTrackingDataSourceInfoANDROID را در زنجیره بعدی ساختار XrFaceTrackerCreateInfoANDROID ارسال کند تا یک یا چند منبع داده برای ردیابی چهره درخواست کند.

اگر برنامه هیچ منبع داده‌ای ارسال نکند، یا هیچ یک از منابع داده توسط 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 را در فراخوانی‌های xrGetFaceStateANDROID روی XR_FALSE تنظیم کند و سایر فیلدها تعریف نشده در نظر گرفته شوند.

کاربرد معتبر (ضمنی)

مجوزها

برنامه‌های اندروید باید مجوزهایی را که قصد درخواست آنها را دارند، در مانیفست خود ذکر کنند. مجوز 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));

مسائل

تاریخچه نسخه

  • نسخه ۱، ۲۰۲۴-۱۰-۰۷ (کنی ورکامر)

    • توضیحات اولیه افزونه