XR_ANDROID_face_tracking_data_source

名稱字串

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);

參數說明

  • instanceXrInstance 的控制代碼。
  • systemId 是指要列舉臉部追蹤資料來源的 XrSystemId
  • supportedDataSourcesInputCapacitysupportedDataSources 陣列的容量,或 0 (表示要求擷取必要容量)。
  • supportedDataSourcesOutputCount 是支援的資料來源數量,或在 supportedDataSourcesInputCapacity 不足時的必要容量。
  • supportedDataSourcesXrFaceTrackingDataSourceANDROID 的陣列。如果 supportedDataSourcesInputCapacity 為 0,則 可以NULL
  • 如要詳細瞭解如何擷取必要的 supportedDataSources 大小,請參閱「緩衝區大小參數」一節。

應用程式可以呼叫 xrEnumerateFaceTrackingDataSourcesANDROID 函式,列舉系統支援的資料來源清單。

如果 XrSystemFaceTrackingPropertiesANDROID :: supportsFaceTrackingXR_TRUE,則執行階段必須也從 xrEnumerateFaceTrackingDataSourcesANDROID 傳回 XR_FACE_TRACKING_DATA_SOURCE_IMAGE_ANDROID

如果執行階段傳回零個資料來源,則表示不支援任何臉部追蹤功能。

執行階段必須依資料來源品質由高至低的順序傳回資料來源。

有效用量 (隱含)

  • 呼叫 xrEnumerateFaceTrackingDataSourcesANDROID 前,XR_ANDROID_face_tracking_data_source 擴充功能必須啟用
  • instance 必須是有效的 XrInstance 控制代碼
  • supportedDataSourcesOutputCount 必須是指向 uint32_t 值的指標
  • 如果 supportedDataSourcesInputCapacity 不是 0,則 supportedDataSources 必須是指向 supportedDataSourcesInputCapacityXrFaceTrackingDataSourceANDROID 值的陣列的指標

傳回代碼

成功

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

列舉值具有下列意義:

列舉說明

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
  • nextNULL,或是指向結構鏈中下一個結構的指標。核心 OpenXR 或這個擴充功能中未定義這類結構。
  • requestedDataSourceCount 是指應用程式要求的資料來源數量。
  • requestedDataSourcesXrFaceTrackingDataSourceANDROID 值的陣列,用於指定應用程式要求的資料來源。

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 必須是指向有效 XrFaceTrackingDataSourceANDROID 值陣列的指標requestedDataSourceCount
  • requestedDataSourceCount 參數必須大於 0

權限

Android 應用程式必須在資訊清單中列出打算要求的權限。android.permission.FACE_TRACKING 權限視為危險權限。android.permission.RECORD_AUDIO 權限視為危險權限。應用程式必須在執行階段要求權限,才能使用下列函式:

(防護等級:危險)

XrFaceTrackingDataSourceStateANDROID 結構體說明如下:

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

成員說明

  • type 是這個結構的 XrStructureType
  • nextNULL,或是指向結構鏈中下一個結構的指標。核心 OpenXR 或這個擴充功能中未定義這類結構。
  • dataSource 是用於產生臉部追蹤資料的 XrFaceTrackingDataSourceANDROID

應用程式可以XrFaceTrackingDataSourceStateANDROID 結構體鏈結至傳遞至 xrGetFaceStateANDROIDXrFaceStateANDROID 結構體,查詢用於產生該呼叫臉部追蹤資料的資料來源。

有效用量 (隱含)

使用資料來源進行臉部追蹤的程式碼範例。

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)

    • 擴充功能初始說明