Android XR for OpenXR | Android Developers

Android XR SDK đã đạt đến Bản dùng thử 3 cho nhà phát triển và chúng tôi rất mong nhận được ý kiến phản hồi của bạn! Hãy thử và truy cập vào trang hỗ trợ của chúng tôi để liên hệ.

XR_ANDROID_face_tracking_data_source

Name String

XR_ANDROID_face_tracking_data_source

Loại tiện ích

Tiện ích phiên bản

Số máy nhánh đã đăng ký

707

Bản sửa đổi

Trạng thái phê chuẩn

Chưa được phê chuẩn

Phần mở rộng và các phần phụ thuộc vào phiên bản

XR_ANDROID_face_tracking

Ngày sửa đổi gần đây nhất

2025-12-16

Trạng thái IP

Không có thông báo xác nhận quyền sở hữu nào đã biết về quyền sở hữu trí tuệ.

Cộng tác viên

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

Tổng quan

Tiện ích này cho phép các ứng dụng lấy dữ liệu theo dõi khuôn mặt từ nhiều nguồn dữ liệu.

Truy vấn các nguồn dữ liệu được hỗ trợ

Các ứng dụng nên gọi xrEnumerateFaceTrackingDataSourcesANDROID để lấy danh sách các nguồn dữ liệu theo dõi khuôn mặt được hỗ trợ.

Hàm xrEnumerateFaceTrackingDataSourcesANDROID được xác định như sau:

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

Nội dung mô tả về tham số

instance là một handle cho XrInstance .
systemId là XrSystemId mà các nguồn dữ liệu theo dõi khuôn mặt sẽ được liệt kê.
supportedDataSourcesInputCapacity là dung lượng của mảng supportedDataSources hoặc 0 để cho biết yêu cầu truy xuất dung lượng cần thiết.
supportedDataSourcesOutputCount là số lượng nguồn dữ liệu được hỗ trợ hoặc dung lượng bắt buộc trong trường hợp supportedDataSourcesInputCapacity không đủ.
supportedDataSources là một mảng XrFaceTrackingDataSourceANDROID . Giá trị này có thể là NULL nếu supportedDataSourcesInputCapacity là 0.
Hãy xem phần Tham số kích thước bộ nhớ đệm để biết nội dung mô tả chi tiết về cách truy xuất kích thước supportedDataSources cần thiết.

Ứng dụng có thể liệt kê danh sách các nguồn dữ liệu mà hệ thống hỗ trợ bằng cách gọi hàm xrEnumerateFaceTrackingDataSourcesANDROID.

Nếu XrSystemFaceTrackingPropertiesANDROID :: supportsFaceTracking là XR_TRUE thì thời gian chạy phải cũng trả về XR_FACE_TRACKING_DATA_SOURCE_IMAGE_ANDROID từ xrEnumerateFaceTrackingDataSourcesANDROID .

Nếu thời gian chạy trả về 0 nguồn dữ liệu, thì tức là thời gian chạy đó không hỗ trợ bất kỳ loại tính năng theo dõi khuôn mặt nào.

Thời gian chạy phải trả về các nguồn dữ liệu theo thứ tự từ chất lượng cao nhất đến chất lượng thấp nhất.

Cách sử dụng hợp lệ (ngầm)

Tiện ích XR_ANDROID_face_tracking_data_source phải được bật trước khi gọi xrEnumerateFaceTrackingDataSourcesANDROID
instance phải là một đối tượng XrInstance hợp lệ
supportedDataSourcesOutputCount phải là con trỏ đến giá trị uint32_t
Nếu supportedDataSourcesInputCapacity không phải là 0 , thì supportedDataSources phải là con trỏ đến một mảng gồm các giá trị supportedDataSourcesInputCapacity XrFaceTrackingDataSourceANDROID

Mã trả về

Thành công

XR_SUCCESS

Thất bại

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

Liệt kê XrFaceTrackingDataSourceANDROID để xác định các nguồn dữ liệu mà một thời gian chạy có thể hỗ trợ.

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;

Các giá trị liệt kê có ý nghĩa như sau:

Nội dung mô tả enum

XR_FACE_TRACKING_DATA_SOURCE_IMAGE_ANDROID

Cho biết rằng cấu hình này sử dụng dữ liệu hình ảnh

XR_FACE_TRACKING_DATA_SOURCE_AUDIO_ANDROID

Cho biết rằng cấu hình này sử dụng dữ liệu âm thanh

XR_FACE_TRACKING_DATA_SOURCE_MULTIMODAL_ANDROID

Cho biết rằng cấu hình này sử dụng dữ liệu hình ảnh và âm thanh

Định cấu hình nguồn dữ liệu

Cấu trúc XrFaceTrackingDataSourceInfoANDROID được mô tả như sau:

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

Nội dung mô tả thành viên

type là XrStructureType của cấu trúc này.
next là NULL hoặc con trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc. Không có cấu trúc nào như vậy được xác định trong OpenXR cốt lõi hoặc tiện ích này.
requestedDataSourceCount là số lượng nguồn dữ liệu mà ứng dụng yêu cầu.
requestedDataSources là một mảng các giá trị XrFaceTrackingDataSourceANDROID, chỉ định các nguồn dữ liệu mà ứng dụng yêu cầu.

Cấu trúc XrFaceTrackingDataSourceInfoANDROID mô tả các nguồn dữ liệu để tạo một đối tượng XrFaceTrackerANDROID.

Một ứng dụng có thể truyền cấu trúc XrFaceTrackingDataSourceInfoANDROID trong chuỗi tiếp theo của cấu trúc XrFaceTrackerCreateInfoANDROID để yêu cầu một hoặc nhiều nguồn dữ liệu cho tính năng theo dõi khuôn mặt khi gọi xrCreateFaceTrackerANDROID .

Nếu ứng dụng truyền 0 nguồn dữ liệu hoặc bất kỳ nguồn dữ liệu nào không được xrEnumerateFaceTrackingDataSourcesANDROID liệt kê, thì thời gian chạy phải trả về XR_ERROR_VALIDATION_FAILURE .

Nếu người dùng chưa cấp tất cả các quyền cần thiết cho tất cả các nguồn dữ liệu được yêu cầu, thì thời gian chạy phải trả về XR_ERROR_PERMISSION_INSUFFICIENT .

Các quyền bắt buộc đối với từng nguồn dữ liệu được xác định như sau:

XR_FACE_TRACKING_DATA_SOURCE_IMAGE_ANDROID yêu cầu quyền android.permission.FACE_TRACKING.
XR_FACE_TRACKING_DATA_SOURCE_AUDIO_ANDROID yêu cầu quyền android.permission.RECORD_AUDIO.
XR_FACE_TRACKING_DATA_SOURCE_MULTIMODAL_ANDROID yêu cầu cả quyền android.permission.FACE_TRACKING và android.permission.RECORD_AUDIO.

Thời gian chạy phải diễn giải mảng XrFaceTrackingDataSourceInfoANDROID : requestedDataSources theo thứ tự ưu tiên từ cao nhất đến thấp nhất theo ứng dụng. Thời gian chạy phải tạo dữ liệu theo dõi bằng nguồn dữ liệu được yêu cầu đầu tiên vẫn tuân thủ các quyền bắt buộc. Nếu một quyền bị thu hồi trong thời gian hoạt động của trình theo dõi, khiến một nguồn dữ liệu không còn sử dụng được nữa, thì thời gian chạy phải tiếp tục cố gắng sử dụng nguồn dữ liệu có mức ưu tiên cao nhất tiếp theo. Nếu không có nguồn dữ liệu nào được yêu cầu có thể sử dụng, thì thời gian chạy phải đặt XrFaceStateANDROID :: isValid thành XR_FALSE trong các lệnh gọi đến xrGetFaceStateANDROID và các trường khác được coi là không xác định.

Cách sử dụng hợp lệ (ngầm)

Bạn phải bật tiện ích XR_ANDROID_face_tracking_data_source trước khi sử dụng XrFaceTrackingDataSourceInfoANDROID
type phải là XR_TYPE_FACE_TRACKING_DATA_SOURCE_INFO_ANDROID
next phải là NULL hoặc một con trỏ hợp lệ đến cấu trúc tiếp theo trong chuỗi cấu trúc
requestedDataSources phải là con trỏ đến một mảng gồm requestedDataSourceCount giá trị XrFaceTrackingDataSourceANDROID hợp lệ
Tham số requestedDataSourceCount phải lớn hơn 0

Quyền

Các ứng dụng Android phải có các quyền mà chúng dự định yêu cầu được liệt kê trong tệp kê khai. Quyền android.permission.FACE_TRACKING được coi là một quyền nguy hiểm. Quyền android.permission.RECORD_AUDIO được coi là một quyền nguy hiểm. Ứng dụng phải yêu cầu các quyền trong thời gian chạy để sử dụng những chức năng này:

xrCreateFaceTrackerANDROID

(cấp độ bảo vệ: nguy hiểm)

Cấu trúc XrFaceTrackingDataSourceStateANDROID được mô tả như sau:

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

Nội dung mô tả thành viên

type là XrStructureType của cấu trúc này.
next là NULL hoặc con trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc. Không có cấu trúc nào như vậy được xác định trong OpenXR cốt lõi hoặc tiện ích này.
dataSource là XrFaceTrackingDataSourceANDROID dùng để tạo dữ liệu theo dõi khuôn mặt.

Một ứng dụng có thể xâu chuỗi cấu trúc XrFaceTrackingDataSourceStateANDROID với cấu trúc XrFaceStateANDROID được truyền đến xrGetFaceStateANDROID để truy vấn nguồn dữ liệu dùng để tạo dữ liệu theo dõi khuôn mặt cho lệnh gọi đó.

Cách sử dụng hợp lệ (ngầm)

Bạn phải bật tiện ích XR_ANDROID_face_tracking_data_source trước khi sử dụng XrFaceTrackingDataSourceStateANDROID
type phải là XR_TYPE_FACE_TRACKING_DATA_SOURCE_STATE_ANDROID
next phải là NULL hoặc một con trỏ hợp lệ đến cấu trúc tiếp theo trong chuỗi cấu trúc
dataSource phải là một giá trị XrFaceTrackingDataSourceANDROID hợp lệ

Đoạn mã mẫu để theo dõi khuôn mặt bằng nguồn dữ liệu.

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

Vấn đề

Nhật ký phiên bản

Bản sửa đổi 1, ngày 7 tháng 10 năm 2024 (Kenny Vercaemer)
- Nội dung mô tả ban đầu của tiện ích