XR_ANDROID_face_tracking_data_source
Name String
XR_ANDROID_face_tracking_data_source
擴充功能類型
執行個體擴充功能
擴充功能註冊編號
707
修訂版本
1
批准狀態
未批准
擴充功能和版本依附元件
XR_ANDROID_face_tracking
上次修改日期
2025-12-16
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 的陣列。如果supportedDataSourcesInputCapacity為 0，則可以是NULL。- 如要進一步瞭解如何擷取必要的
supportedDataSources大小，請參閱「緩衝區大小參數」一節。
應用程式可以呼叫 xrEnumerateFaceTrackingDataSourcesANDROID 函式，列舉系統支援的資料來源清單。
如果 XrSystemFaceTrackingPropertiesANDROID :: supportsFaceTracking 為 XR_TRUE，則執行階段必須也從 xrEnumerateFaceTrackingDataSourcesANDROID 傳回 XR_FACE_TRACKING_DATA_SOURCE_IMAGE_ANDROID。
如果執行階段傳回零個資料來源，表示不支援任何臉部追蹤。
執行階段必須按照品質由高到低的順序傳回資料來源。
有效用途 (隱含)
- 必須先啟用
XR_ANDROID_face_tracking_data_source擴充功能，才能呼叫 xrEnumerateFaceTrackingDataSourcesANDROID -
instance「必須」是有效的 XrInstance 控制代碼 -
supportedDataSourcesOutputCount「必須」是指向uint32_t值的指標 - 如果
supportedDataSourcesInputCapacity不是0，supportedDataSources必須是指向supportedDataSourcesInputCapacityXrFaceTrackingDataSourceANDROID 值陣列的指標
傳回代碼
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;
列舉值的意義如下：
列舉說明
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 控制代碼的資料來源。
應用程式可以在 XrFaceTrackerCreateInfoANDROID 結構的下一個鏈結中傳遞 XrFaceTrackingDataSourceInfoANDROID 結構，以便在呼叫 xrCreateFaceTrackerANDROID 時，要求一或多個臉部追蹤資料來源。
如果應用程式傳遞零個資料來源，或任何資料來源未由 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 陣列解讀為應用程式的偏好設定，由高至低排列。執行階段必須使用第一個要求的資料來源產生追蹤資料，且該資料來源仍符合必要權限。如果在追蹤器生命週期內撤銷權限，導致資料來源無法再使用，執行階段「必須」繼續嘗試使用偏好設定次高的資料來源。如果要求的資料來源都無法使用，執行階段必須在呼叫 xrGetFaceStateANDROID 時，將 XrFaceStateANDROID :: isValid 設為 XR_FALSE，其他欄位則視為未定義。
有效用途 (隱含)
- 必須先啟用
XR_ANDROID_face_tracking_data_source擴充功能，才能使用 XrFaceTrackingDataSourceInfoANDROID -
type「必須」為XR_TYPE_FACE_TRACKING_DATA_SOURCE_INFO_ANDROID -
next「必須」為NULL，或指向結構鏈中下一個結構的有效指標 -
requestedDataSources「必須」是指向requestedDataSourceCount個有效 XrFaceTrackingDataSourceANDROID 值陣列的指標 -
requestedDataSourceCount參數必須大於0
權限
Android 應用程式必須在資訊清單中列出要要求的權限。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 結構鏈結至傳遞至 xrGetFaceStateANDROID 的 XrFaceStateANDROID 結構，以查詢用於產生該呼叫臉部追蹤資料的資料來源。
有效用途 (隱含)
- 必須先啟用
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 月 7 日 (Kenny Vercaemer)
- 初始擴充功能說明