Android XR for OpenXR | Android Developers

Hội nghị Nhà phát triển Android đã trở lại với một kênh chuyên biệt cho Android XR. Hãy theo dõi, dùng thử và gửi ý kiến phản hồi cho chúng tôi!

Google sử dụng công nghệ AI để dịch nội dung sang ngôn ngữ bạn ưu tiên. Bản dịch bằng AI có thể có lỗi.

XR_ANDROID_face_tracking_data_source

Name String

XR_ANDROID_face_tracking_data_source

Loại tiện ích

Phần mở rộng thực thể

Số máy lẻ đã đăng ký

707

Bản sửa đổi

Trạng thái phê chuẩn

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

Phần phụ thuộc của tiện ích và 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ó tuyên bố nào về tài sản 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ợ

Ứ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 định nghĩa 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 tay điều khiển 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 cần thiết 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ố dung lượng 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 cũng phải trả về XR_FACE_TRACKING_DATA_SOURCE_IMAGE_ANDROID từ xrEnumerateFaceTrackingDataSourcesANDROID .

Nếu thời gian chạy không trả về nguồn dữ liệu nào, 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 ẩn)

Phải bật tiện ích XR_ANDROID_face_tracking_data_source trước khi gọi xrEnumerateFaceTrackingDataSourcesANDROID
instance phải là một tên người dù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

Không thành công

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

Phép liệt kê XrFaceTrackingDataSourceANDROID xác định các nguồn dữ liệu khác nhau mà 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 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 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ả về thành viên

type là XrStructureType của cấu trúc này.
next là NULL hoặc con trỏ 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 tay điều khiển XrFaceTrackerANDROID.

Ứ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 không có nguồn dữ liệu nào 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ả 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 cần thiết cho mỗi nguồn dữ liệu được xác định như sau:

XR_FACE_TRACKING_DATA_SOURCE_IMAGE_ANDROID cần có 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 của ứ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 mà 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 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 ư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 ẩ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à một 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

Ứng dụng Android phải có các quyền mà ứng dụ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à quyền nguy hiểm. Quyền android.permission.RECORD_AUDIO được coi là quyền nguy hiểm. Ứng dụng phải yêu cầu quyền trong thời gian chạy để sử dụng các hàm sau:

xrCreateFaceTrackerANDROID

(mức độ 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ả về thành viên

type là XrStructureType của cấu trúc này.
next là NULL hoặc con trỏ 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ể liên kết 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 ẩn)

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ệ

Mã ví dụ về tính năng 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 về tiện ích