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 ramal registrado

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 do IP

Nenhuma reivindicação de PI 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.

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 uma 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 de recuperação da 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 . Pode ser NULL se supportedDataSourcesInputCapacity for 0.
  • Consulte a seção Parâmetros de tamanho do buffer para uma descrição detalhada de como recuperar o tamanho de 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 precisa retornar XR_FACE_TRACKING_DATA_SOURCE_IMAGE_ANDROID de xrEnumerateFaceTrackingDataSourcesANDROID .

Se o ambiente de execução retornar zero fontes de dados, ele não será compatível com nenhum tipo de captura de expressões faciais.

O ambiente de execução precisa retornar as fontes de dados em ordem de qualidade, da mais alta para a mais baixa.

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 valor uint32_t
  • 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 aceitar.

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 enumerantes têm os seguintes significados:

Descrição do tipo enumerado

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 forma:

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

Descrições dos membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma estrutura desse tipo é definida no OpenXR principal ou nesta 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 captura de expressões faciais ao chamar xrCreateFaceTrackerANDROID .

Se o aplicativo não transmitir fontes de dados ou se alguma delas não tiver sido 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 forma:

  • 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 preferência mais alta para a mais baixa 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 ciclo de vida do rastreador, fazendo com que uma fonte de dados não possa mais ser usada, o ambiente de execução precisa continuar tentando usar a próxima fonte de dados de preferência mais alta. Se nenhuma das fontes de dados solicitadas for utilizável, o ambiente de execução precisa 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 apps Android precisam listar as permissões que pretendem solicitar 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 momento da execução para usar estas 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 dos membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma estrutura desse tipo é definida no OpenXR principal ou nesta 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