XR_ANDROID_face_tracking_data_source

String de nome

XR_ANDROID_face_tracking_data_source

Tipo de extensão

Extensão de instância

Número de extensão registrada

707

Revisão

1

Status de ratificação

Não ratificado

Dependências de extensão e versão

XR_ANDROID_face_tracking

Data da última modificação

2025-12-16

Status de IP

Nenhuma reivindicação de IP conhecida.

Colaboradores

Kenny Vercaemer, Google
Yinglei Zhang, Google
Nihav Jain, Google
Spencer Quin, Google

Visão geral

Essa extensão permite que os aplicativos recebam dados de captura de expressões faciais de várias fontes de dados.

Consultar fontes de dados compatíveis

Os aplicativos precisam chamar xrEnumerateFaceTrackingDataSourcesANDROID para receber a lista de fontes de dados de captura de expressões faciais compatíveis.

A função xrEnumerateFaceTrackingDataSourcesANDROID é definida como:

XrResult                                                                                 xrEnumerateFaceTrackingDataSourcesANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    supportedDataSourcesInputCapacity,
    uint32_t*                                   supportedDataSourcesOutputCount,
    XrFaceTrackingDataSourceANDROID*            supportedDataSources);

Descrições dos parâmetros

  • instance é um identificador para um XrInstance .
  • systemId é o XrSystemId para o qual as fontes de dados de captura de expressões faciais serão enumeradas.
  • supportedDataSourcesInputCapacity é a capacidade da matriz supportedDataSources ou 0 para indicar uma solicitação para recuperar a capacidade necessária.
  • supportedDataSourcesOutputCount é o número de fontes de dados compatíveis ou a capacidade necessária caso supportedDataSourcesInputCapacity seja insuficiente.
  • supportedDataSources é uma matriz de XrFaceTrackingDataSourceANDROID . Ela pode ser NULL se supportedDataSourcesInputCapacity for 0.
  • Consulte a seção Parâmetros de tamanho do buffer para uma descrição detalhada da recuperação do tamanho supportedDataSources necessário.

O aplicativo pode enumerar a lista de fontes de dados compatíveis com o sistema chamando a função xrEnumerateFaceTrackingDataSourcesANDROID.

Se XrSystemFaceTrackingPropertiesANDROID :: supportsFaceTracking for XR_TRUE, o ambiente de execução também precisará retornar XR_FACE_TRACKING_DATA_SOURCE_IMAGE_ANDROID de xrEnumerateFaceTrackingDataSourcesANDROID .

Se o ambiente de execução retornar zero fontes de dados, ele não vai oferecer suporte a nenhum tipo de captura de expressões faciais.

O ambiente de execução precisa retornar as fontes de dados em ordem de maior para menor qualidade.

Uso válido (implícito)

  • A extensão XR_ANDROID_face_tracking_data_source precisa ser ativada antes de chamar xrEnumerateFaceTrackingDataSourcesANDROID
  • instance precisa ser um identificador XrInstance válido.
  • supportedDataSourcesOutputCount precisa ser um ponteiro para um uint32_t valor
  • Se supportedDataSourcesInputCapacity não for 0 , supportedDataSources precisa ser um ponteiro para uma matriz de valores supportedDataSourcesInputCapacity XrFaceTrackingDataSourceANDROID.

Códigos de retorno

Sucesso

  • XR_SUCCESS

Falha

  • 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

A enumeração XrFaceTrackingDataSourceANDROID identifica as diferentes fontes de dados que um ambiente de execução pode oferecer suporte.

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;

Os enumeradores têm os seguintes significados:

Descrição da enumeração

XR_FACE_TRACKING_DATA_SOURCE_IMAGE_ANDROID

Indica que essa configuração usa dados de imagem

XR_FACE_TRACKING_DATA_SOURCE_AUDIO_ANDROID

Indica que essa configuração usa dados de áudio

XR_FACE_TRACKING_DATA_SOURCE_MULTIMODAL_ANDROID

Indica que essa configuração usa dados de imagem e áudio

Como configurar fontes de dados

A estrutura XrFaceTrackingDataSourceInfoANDROID é descrita da seguinte maneira:

typedef struct XrFaceTrackingDataSourceInfoANDROID {
    XrStructureType                           type;
    const void*                               next;
    uint32_t                                  requestedDataSourceCount;
    const XrFaceTrackingDataSourceANDROID*    requestedDataSources;
} XrFaceTrackingDataSourceInfoANDROID;

Descrições de membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma dessas estruturas é definida no OpenXR principal ou nessa extensão.
  • requestedDataSourceCount é o número de fontes de dados solicitadas pelo aplicativo.
  • requestedDataSources é uma matriz de valores XrFaceTrackingDataSourceANDROID, que especifica as fontes de dados solicitadas pelo aplicativo.

A estrutura XrFaceTrackingDataSourceInfoANDROID descreve as fontes de dados para criar um identificador XrFaceTrackerANDROID.

Um aplicativo pode transmitir uma estrutura XrFaceTrackingDataSourceInfoANDROID na próxima cadeia de uma estrutura XrFaceTrackerCreateInfoANDROID para solicitar uma ou mais fontes de dados para rastreamento facial ao chamar xrCreateFaceTrackerANDROID .

Se o aplicativo transmitir zero fontes de dados ou se alguma das fontes de dados não for enumerada por xrEnumerateFaceTrackingDataSourcesANDROID, o ambiente de execução precisará retornar XR_ERROR_VALIDATION_FAILURE .

Se o usuário não tiver concedido todas as permissões necessárias para todas as fontes de dados solicitadas, o ambiente de execução precisará retornar XR_ERROR_PERMISSION_INSUFFICIENT .

As permissões necessárias para cada fonte de dados são definidas da seguinte maneira:

  • XR_FACE_TRACKING_DATA_SOURCE_IMAGE_ANDROID requer a permissão android.permission.FACE_TRACKING.
  • XR_FACE_TRACKING_DATA_SOURCE_AUDIO_ANDROID requer a permissão android.permission.RECORD_AUDIO.
  • XR_FACE_TRACKING_DATA_SOURCE_MULTIMODAL_ANDROID requer as permissões android.permission.FACE_TRACKING e android.permission.RECORD_AUDIO.

O ambiente de execução precisa interpretar a matriz XrFaceTrackingDataSourceInfoANDROID : requestedDataSources como a maior preferência para a menor preferência pelo aplicativo. O ambiente de execução precisa produzir dados de rastreamento usando a primeira fonte de dados solicitada que ainda esteja em conformidade com as permissões necessárias. Se uma permissão for revogada durante o tempo de vida do rastreador, fazendo com que uma fonte de dados não possa mais ser usada, o ambiente de execução precisará continuar tentando usar a próxima fonte de dados de maior preferência. Se nenhuma das fontes de dados solicitadas puder ser usada, o ambiente de execução precisará definir XrFaceStateANDROID :: isValid como XR_FALSE em chamadas para xrGetFaceStateANDROID e outros campos serão considerados indefinidos.

Uso válido (implícito)

Permissões

Os aplicativos Android precisam ter as permissões que pretendem solicitar listadas no manifesto. A permissão android.permission.FACE_TRACKING é considerada perigosa. A permissão android.permission.RECORD_AUDIO é considerada perigosa. O aplicativo precisa solicitar as permissões no ambiente de execução para usar essas funções:

(nível de proteção: perigoso)

A estrutura XrFaceTrackingDataSourceStateANDROID é descrita da seguinte maneira:

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

Descrições de membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma dessas estruturas é definida no OpenXR principal ou nessa extensão.
  • dataSource é o XrFaceTrackingDataSourceANDROID usado para produzir os dados de captura de expressões faciais.

Um aplicativo pode encadear uma estrutura XrFaceTrackingDataSourceStateANDROID a uma estrutura XrFaceStateANDROID transmitida para xrGetFaceStateANDROID para consultar a fonte de dados usada para produzir os dados de captura de expressões faciais para essa chamada.

Uso válido (implícito)

Exemplo de código para captura de expressões faciais com fonte de dados.

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

Problemas

Histórico de versões

  • Revisão 1, 07/10/2024 (Kenny Vercaemer)

    • Descrição inicial da extensão