Android XR for OpenXR | Android Developers

Android XR SDK 已达到开发者预览版 3，我们希望收到您的反馈！您可以尝试一下，然后访问我们的支持页面与我们联系。

XR_ANDROID_face_tracking_data_source

名称字符串

XR_ANDROID_face_tracking_data_source

扩展类型

实例扩展程序

已注册的扩展程序编号

707

修订版本

批准状态

未批准

扩展程序和版本依赖项

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 的数组。如果 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 必须是指向 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;

枚举数的含义如下：

枚举说明

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 权限被视为危险权限。应用必须在运行时请求权限才能使用以下函数：

xrCreateFaceTrackerANDROID

（保护级别：危险）

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)
- 初始扩展程序说明