XR_ANDROID_face_tracking_data_source

Строка имени

XR_ANDROID_face_tracking_data_source

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

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

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

707

Пересмотр

1

Статус ратификации

Не ратифицировано

Зависимости расширений и версий

XR_ANDROID_face_tracking

Дата последнего изменения

2025-12-16

Статус IP

Известных претензий на интеллектуальную собственность нет.

Авторы

Кенни Веркамер, Google
Инлэй Чжан, Google
Нихав Джайн, Google
Спенсер Куин, 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 , а другие поля считаются неопределенными.

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

Разрешения

В манифесте 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, 07.10.2024 (Кенни Веркамер)

    • Первоначальное описание расширения