XR_ANDROID_face_tracking_data_source

Name String

XR_ANDROID_face_tracking_data_source

ประเภทส่วนขยาย

ส่วนขยายอินสแตนซ์

หมายเลขต่อที่ลงทะเบียนไว้

707

การแก้ไข

1

สถานะการให้สัตยาบัน

ไม่ได้รับการให้สัตยาบัน

ทรัพยากร Dependency ของส่วนขยายและเวอร์ชัน

XR_ANDROID_face_tracking

วันที่แก้ไขล่าสุด

2025-12-16

สถานะ IP

ไม่มีการอ้างสิทธิ์ 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 หรือ 0 เพื่อระบุคำขอให้ดึงข้อมูลความจุที่จำเป็น
  • supportedDataSourcesOutputCount คือจำนวนแหล่งข้อมูลที่รองรับ หรือความจุที่จำเป็นในกรณีที่ supportedDataSourcesInputCapacity ไม่เพียงพอ
  • supportedDataSources คืออาร์เรย์ของ XrFaceTrackingDataSourceANDROID สามารถเป็น NULL ได้หาก supportedDataSourcesInputCapacity เป็น 0
  • ดูคำอธิบายโดยละเอียดเกี่ยวกับการดึงข้อมูลขนาด supportedDataSources ที่จำเป็นได้ที่ส่วนพารามิเตอร์ขนาดบัฟเฟอร์

แอปพลิเคชันสามารถแจกแจงรายการแหล่งข้อมูลที่ระบบรองรับได้โดยเรียกใช้ฟังก์ชัน xrEnumerateFaceTrackingDataSourcesANDROID

หาก XrSystemFaceTrackingPropertiesANDROID :: supportsFaceTracking เป็น XR_TRUE รันไทม์ต้องแสดงผล XR_FACE_TRACKING_DATA_SOURCE_IMAGE_ANDROID จาก xrEnumerateFaceTrackingDataSourcesANDROID ด้วย

หากรันไทม์แสดงแหล่งข้อมูลเป็น 0 แสดงว่าไม่รองรับการติดตามใบหน้าทุกประเภท

รันไทม์ต้องแสดงแหล่งข้อมูลตามลำดับคุณภาพสูงสุดไปต่ำสุด

การใช้งานที่ถูกต้อง (โดยนัย)

  • ต้องเปิดใช้ส่วนขยาย 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;

ค่าแจงนับมีความหมายดังนี้

คำอธิบาย 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 เพื่อขอแหล่งข้อมูลอย่างน้อย 1 แหล่งสำหรับการติดตามใบหน้าเมื่อเรียกใช้ xrCreateFaceTrackerANDROID

หากแอปพลิเคชันส่งแหล่งข้อมูลเป็น 0 หรือ 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 เป็น XR_FALSE ในการเรียกใช้ xrGetFaceStateANDROID และระบบจะถือว่าช่องอื่นๆ ไม่ได้กำหนดไว้

การใช้งานที่ถูกต้อง (โดยนัย)

  • ต้องเปิดใช้ส่วนขยาย XR_ANDROID_face_tracking_data_source ก่อนใช้ XrFaceTrackingDataSourceInfoANDROID
  • type ต้องเป็น XR_TYPE_FACE_TRACKING_DATA_SOURCE_INFO_ANDROID
  • next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในเชนโครงสร้าง
  • requestedDataSources ต้องเป็นตัวชี้ไปยังอาร์เรย์ของค่า XrFaceTrackingDataSourceANDROID ที่ถูกต้อง requestedDataSourceCount ค่า
  • พารามิเตอร์ requestedDataSourceCount ต้องมากกว่า 0

สิทธิ์

แอปพลิเคชัน Android ต้องมีสิทธิ์ที่ต้องการขอแสดงอยู่ในไฟล์ Manifest สิทธิ์ 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, 2024-10-07 (Kenny Vercaemer)

    • คำอธิบายส่วนขยายเริ่มต้น