XR_ANDROID_face_tracking_data_source

Name String

XR_ANDROID_face_tracking_data_source

Тип расширения

Расширение экземпляра

Зарегистрированный добавочный номер

707

Revision

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 . Может быть NULL, если supportedDataSourcesInputCapacity равно 0.
  • Подробное описание того, как получить нужный размер supportedDataSources, приведено в разделе Параметры размера буфера.

Приложение может перечислить список источников данных, поддерживаемых системой, вызвав функцию xrEnumerateFaceTrackingDataSourcesANDROID.

Если XrSystemFaceTrackingPropertiesANDROID :: supportsFaceTracking – это XR_TRUE, то среда выполнения должна также возвращать XR_FACE_TRACKING_DATA_SOURCE_IMAGE_ANDROID из xrEnumerateFaceTrackingDataSourcesANDROID .

Если среда выполнения возвращает нулевые источники данных, то она не поддерживает отслеживание лиц.

Среда выполнения должна возвращать источники данных в порядке от самого высокого качества к самому низкому.

Допустимое использование (неявное)

  • Расширение 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.

Приложение может передать структуру XrFaceTrackingDataSourceInfoANDROID в следующей цепочке структуры XrFaceTrackerCreateInfoANDROID, чтобы запросить один или несколько источников данных для отслеживания мимики при вызове 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 от наиболее предпочтительного к наименее предпочтительному для приложения. Среда выполнения должна генерировать данные отслеживания, используя первый запрошенный источник данных, который по-прежнему соответствует требуемым разрешениям. Если разрешение будет отозвано во время работы трекера, из-за чего источник данных станет недоступен, среда выполнения должна продолжить попытки использовать следующий по приоритету источник данных. Если ни один из запрошенных источников данных не доступен, среда выполнения должна задать для XrFaceStateANDROID :: isValid значение XR_FALSE в вызовах xrGetFaceStateANDROID, а другие поля будут считаться неопределенными.

Допустимое использование (неявное)

  • Расширение 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 со структурой XrFaceStateANDROID, переданной в xrGetFaceStateANDROID, чтобы запросить источник данных, используемый для создания данных отслеживания лица для этого вызова.

Допустимое использование (неявное)

Пример кода для отслеживания лица с источником данных.

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, 7 октября 2024 г. (Кенни Веркамер)

    • Описание расширения