Android XR for OpenXR | Android Developers

«نشست توسعه‌دهندگان Android» با یک بخش اختصاصی برای Android XR بازگشته است. با ما همراه باشید، چیزهای جدید را امتحان کنید، و بازخوردتان را برای ما ارسال کنید!

‫Google برای ترجمه محتوا به زبان ترجیحی شما از فناوری هوشواره استفاده می‌کند. ترجمه‌های هوشواره‌ای ممکن است اشتباه داشته باشند.

XR_ANDROID_face_tracking_data_source

رشته نام

XR_ANDROID_face_tracking_data_source

نوع افزونه

افزونه نمونه

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

707

بازبینی

وضعیت تصویب

تصویب‌نشده

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

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 است، یا ۰ برای نشان دادن درخواست بازیابی ظرفیت موردنیاز.
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 توصیف می‌کند.

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

استفاده معتبر (ضمنی)

افزونه 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));

مشکلات

سابقه نسخه

بازبینی ۱،‏ ۲۰۲۴/۱۰/۰۷ (Kenny Vercaemer)
- شرح اولیه افزونه