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คือแฮนเดิลของ XrInstancesystemIdคือ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 ไปยังอาร์เรย์ของค่าsupportedDataSourcesInputCapacityXrFaceTrackingDataSourceANDROID
Return Codes
XR_SUCCESS
XR_ERROR_FEATURE_UNSUPPORTEDXR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_RUNTIME_FAILUREXR_ERROR_SYSTEM_INVALIDXR_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_TRACKINGXR_FACE_TRACKING_DATA_SOURCE_AUDIO_ANDROIDต้องใช้สิทธิ์ android.permission.RECORD_AUDIOXR_FACE_TRACKING_DATA_SOURCE_MULTIMODAL_ANDROIDต้องใช้สิทธิ์ android.permission.FACE_TRACKING และ android.permission.RECORD_AUDIO
รันไทม์ต้อง ตีความอาร์เรย์ XrFaceTrackingDataSourceInfoANDROID : requestedDataSources เป็นค่ากำหนดจากสูงสุดไปต่ำสุดโดยแอปพลิเคชัน รันไทม์ต้อง สร้างข้อมูลการติดตามโดยใช้แหล่งข้อมูลแรกที่ขอซึ่งยังคงเป็นไปตามสิทธิ์ที่จำเป็น หากมีการเพิกถอนสิทธิ์ระหว่างอายุการใช้งานของตัวติดตาม ซึ่งทำให้แหล่งข้อมูลไม่สามารถใช้งานได้อีกต่อไป รันไทม์ต้อง พยายามใช้แหล่งข้อมูลที่มีค่ากำหนดสูงสุดถัดไปต่อไป หากไม่มีแหล่งข้อมูลที่ขอใดที่ใช้งานได้ รันไทม์ต้อง ตั้งค่า XrFaceStateANDROID :: isValid เป็น XR_FALSE ในการเรียก xrGetFaceStateANDROID และฟิลด์อื่นๆ จะถือว่าไม่ได้กำหนด
Valid Usage (Implicit)
- ต้องเปิดใช้ส่วนขยาย
XR_ANDROID_face_tracking_data_sourceก่อน ใช้ XrFaceTrackingDataSourceInfoANDROID -
typeต้อง เป็นXR_TYPE_FACE_TRACKING_DATA_SOURCE_INFO_ANDROID -
nextต้อง เป็นNULLหรือตัวชี้ที่ถูกต้องไปยังโครงสร้างถัดไปในเชนโครงสร้าง -
requestedDataSourcesต้อง เป็นตัวชี้ไปยังอาร์เรย์ของค่าrequestedDataSourceCountXrFaceTrackingDataSourceANDROID ที่ถูกต้อง - พารามิเตอร์
requestedDataSourceCountต้อง มากกว่า0
สิทธิ์
แอปพลิเคชัน 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)
- ต้องเปิดใช้ส่วนขยาย
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));
ปัญหา
ประวัติเวอร์ชัน
การแก้ไข 1, 2024-10-07 (Kenny Vercaemer)
- คำอธิบายส่วนขยายเริ่มต้น