XR_ANDROID_face_tracking_data_source

Name String

XR_ANDROID_face_tracking_data_source

Extension Type

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

Registered Extension Number

707

Revision

1

Ratification Status

ยังไม่อนุมัติ

Extension and Version Dependencies

XR_ANDROID_face_tracking

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

2025-12-16

IP Status

ไม่มีการอ้างสิทธิ์ IP ที่ทราบ

ผู้เขียน

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

ภาพรวม

ส่วนขยายนี้ช่วยให้แอปพลิเคชันรับข้อมูลการติดตามใบหน้าจากแหล่งข้อมูลหลายแหล่งได้

Query supported data sources

แอปพลิเคชันควร เรียก xrEnumerateFaceTrackingDataSourcesANDROID เพื่อรับรายการแหล่งข้อมูลการติดตามใบหน้าที่รองรับ

ฟังก์ชัน xrEnumerateFaceTrackingDataSourcesANDROID มีคำจำกัดความดังนี้

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

Parameter Descriptions

  • 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 แสดงว่ารันไทม์ไม่รองรับการติดตามใบหน้าทุกประเภท

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

Valid Usage (Implicit)

  • ต้องเปิดใช้ส่วนขยาย XR_ANDROID_face_tracking_data_source ก่อน เรียก xrEnumerateFaceTrackingDataSourcesANDROID
  • instance ต้อง เป็นแฮนเดิล XrInstance ที่ถูกต้อง
  • supportedDataSourcesOutputCount ต้อง เป็น Pointer ไปยังค่า uint32_t
  • หาก supportedDataSourcesInputCapacity ไม่ใช่ 0 , supportedDataSources ต้อง เป็น Pointer ไปยังอาร์เรย์ของค่า supportedDataSourcesInputCapacity XrFaceTrackingDataSourceANDROID

Return Codes

Success

  • XR_SUCCESS

Failure

  • 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 Description

XR_FACE_TRACKING_DATA_SOURCE_IMAGE_ANDROID

ระบุว่าการกำหนดค่านี้ใช้ข้อมูลรูปภาพ

XR_FACE_TRACKING_DATA_SOURCE_AUDIO_ANDROID

ระบุว่าการกำหนดค่านี้ใช้ข้อมูลเสียง

XR_FACE_TRACKING_DATA_SOURCE_MULTIMODAL_ANDROID

ระบุว่าการกำหนดค่านี้ใช้ข้อมูลรูปภาพและเสียง

Configuring data sources

โครงสร้าง XrFaceTrackingDataSourceInfoANDROID มีคำอธิบายดังนี้

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

Member Descriptions

  • type คือ XrStructureType ของโครงสร้างนี้
  • next คือ NULL หรือ Pointer ไปยังโครงสร้างถัดไปในเชนโครงสร้าง ไม่มีการกำหนดโครงสร้างดังกล่าวใน 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 และฟิลด์อื่นๆ จะถือว่าไม่ได้กำหนด

Valid Usage (Implicit)

สิทธิ์

แอปพลิเคชัน Android ต้อง มีสิทธิ์ที่ต้องการขอระบุไว้ในไฟล์ Manifest สิทธิ์ android.permission.FACE_TRACKING ถือเป็นสิทธิ์ที่อาจเป็นอันตราย สิทธิ์ android.permission.RECORD_AUDIO ถือเป็นสิทธิ์ที่อาจเป็นอันตราย แอปพลิเคชันต้อง ขอสิทธิ์ขณะรันไทม์เพื่อใช้ฟังก์ชันต่อไปนี้

(ระดับการปกป้อง: อาจเป็นอันตราย)

โครงสร้าง XrFaceTrackingDataSourceStateANDROID มีคำอธิบายดังนี้

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

Member Descriptions

  • type คือ XrStructureType ของโครงสร้างนี้
  • next คือ NULL หรือ Pointer ไปยังโครงสร้างถัดไปในเชนโครงสร้าง ไม่มีการกำหนดโครงสร้างดังกล่าวใน OpenXR หลักหรือส่วนขยายนี้
  • dataSource คือ XrFaceTrackingDataSourceANDROID ที่ใช้สร้างข้อมูลการติดตามใบหน้า

แอปพลิเคชัน อาจ เชื่อมโยงโครงสร้าง XrFaceTrackingDataSourceStateANDROID กับโครงสร้าง XrFaceStateANDROID ที่ส่งไปยัง xrGetFaceStateANDROID เพื่อค้นหาแหล่งข้อมูลที่ใช้สร้างข้อมูลการติดตามใบหน้าสำหรับการเรียกนั้น

Valid Usage (Implicit)

ตัวอย่างโค้ดสำหรับการติดตามใบหน้าด้วยแหล่งข้อมูล

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)

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