XR_ANDROID_face_tracking_data_source

名称字符串

XR_ANDROID_face_tracking_data_source

扩展程序类型

实例扩展程序

已注册的扩展程序编号

707

修订版本

1

批准状态

未批准

扩展程序和版本依赖项

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

参数说明

  • instanceXrInstance 的句柄。
  • systemId 是将枚举面部追踪数据源的 XrSystemId
  • supportedDataSourcesInputCapacitysupportedDataSources 数组的容量,或设为 0 以请求获取所需的容量。
  • supportedDataSourcesOutputCount 是支持的数据源的数量;若 supportedDataSourcesInputCapacity 容量不足,则为所需的容量。
  • supportedDataSourcesXrFaceTrackingDataSourceANDROID 的数组。如果 supportedDataSourcesInputCapacity 为 0,则可以NULL
  • 如需详细了解如何检索所需的 supportedDataSources 大小,请参阅 缓冲区大小参数 部分。

应用可以 通过调用 xrEnumerateFaceTrackingDataSourcesANDROID 函数来枚举系统支持的数据源列表。

如果 XrSystemFaceTrackingPropertiesANDROID :: supportsFaceTrackingXR_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
  • 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,并且其他字段被视为未定义。

有效用法(隐式)

权限

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)

    • 初始扩展程序说明