XR_ANDROID_face_tracking_data_source

Name String

XR_ANDROID_face_tracking_data_source

Type d'extension

Extension d'instance

Numéro d'extension enregistré

707

Révision

1

État de la ratification

Non ratifié

Dépendances d'extension et de version

XR_ANDROID_face_tracking

Date de dernière modification

2025-12-16

État de l'adresse IP

Aucune réclamation de propriété intellectuelle connue.

Participants

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

Présentation

Cette extension permet aux applications d'obtenir des données de suivi du visage à partir de plusieurs sources de données.

Interroger des sources de données compatibles

Les applications doivent appeler xrEnumerateFaceTrackingDataSourcesANDROID pour obtenir la liste des sources de données de suivi du visage compatibles.

La fonction xrEnumerateFaceTrackingDataSourcesANDROID est définie comme suit :

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

Description des paramètres

  • instance est un handle vers un XrInstance .
  • systemId est l'XrSystemId pour lequel les sources de données de suivi du visage seront énumérées.
  • supportedDataSourcesInputCapacity est la capacité du tableau supportedDataSources, ou 0 pour indiquer une requête de récupération de la capacité requise.
  • supportedDataSourcesOutputCount est le nombre de sources de données compatibles ou la capacité requise si supportedDataSourcesInputCapacity est insuffisant.
  • supportedDataSources est un tableau de XrFaceTrackingDataSourceANDROID . Il peut être NULL si supportedDataSourcesInputCapacity est égal à 0.
  • Consultez la section Paramètres de taille de la mémoire tampon pour obtenir une description détaillée de la récupération de la taille supportedDataSources requise.

L'application peut énumérer la liste des sources de données compatibles avec le système en appelant la fonction xrEnumerateFaceTrackingDataSourcesANDROID.

Si XrSystemFaceTrackingPropertiesANDROID :: supportsFaceTracking est XR_TRUE, l'environnement d'exécution doit également renvoyer XR_FACE_TRACKING_DATA_SOURCE_IMAGE_ANDROID à partir de xrEnumerateFaceTrackingDataSourcesANDROID .

Si l'environnement d'exécution ne renvoie aucune source de données, cela signifie qu'il n'est pas compatible avec le suivi du visage.

L'environnement d'exécution doit renvoyer les sources de données par ordre de qualité décroissante.

Utilisation valide (implicite)

  • L'extension XR_ANDROID_face_tracking_data_source doit être activée avant d'appeler xrEnumerateFaceTrackingDataSourcesANDROID.
  • instance doit être un handle XrInstance valide
  • supportedDataSourcesOutputCount doit être un pointeur vers une valeur uint32_t
  • Si supportedDataSourcesInputCapacity n'est pas 0 , supportedDataSources doit être un pointeur vers un tableau de valeurs supportedDataSourcesInputCapacity XrFaceTrackingDataSourceANDROID.

Codes renvoyés

Opération réussie

  • XR_SUCCESS

Échec

  • 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

L'énumération XrFaceTrackingDataSourceANDROID identifie les différentes sources de données qu'un environnement d'exécution peut prendre en charge.

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;

Les énumérants ont les significations suivantes :

Description de l'enum

XR_FACE_TRACKING_DATA_SOURCE_IMAGE_ANDROID

Indique que cette configuration utilise des données d'image

XR_FACE_TRACKING_DATA_SOURCE_AUDIO_ANDROID

Indique que cette configuration utilise des données audio

XR_FACE_TRACKING_DATA_SOURCE_MULTIMODAL_ANDROID

Indique que cette configuration utilise des données d'image et audio.

Configurer des sources de données

La structure XrFaceTrackingDataSourceInfoANDROID est décrite comme suit :

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

Descriptions des membres

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures. Aucune structure de ce type n'est définie dans OpenXR de base ou dans cette extension.
  • requestedDataSourceCount est le nombre de sources de données demandées par l'application.
  • requestedDataSources est un tableau de valeurs XrFaceTrackingDataSourceANDROID, qui spécifie les sources de données demandées par l'application.

La structure XrFaceTrackingDataSourceInfoANDROID décrit les sources de données permettant de créer un handle XrFaceTrackerANDROID.

Une application peut transmettre une structure XrFaceTrackingDataSourceInfoANDROID dans la chaîne suivante d'une structure XrFaceTrackerCreateInfoANDROID pour demander une ou plusieurs sources de données pour le suivi du visage lors de l'appel de xrCreateFaceTrackerANDROID .

Si l'application ne transmet aucune source de données ou si l'une des sources de données n'a pas été énumérée par xrEnumerateFaceTrackingDataSourcesANDROID, l'environnement d'exécution doit renvoyer XR_ERROR_VALIDATION_FAILURE .

Si l'utilisateur n'a pas accordé toutes les autorisations requises pour toutes les sources de données demandées, l'environnement d'exécution doit renvoyer XR_ERROR_PERMISSION_INSUFFICIENT .

Les autorisations requises pour chaque source de données sont définies comme suit :

  • XR_FACE_TRACKING_DATA_SOURCE_IMAGE_ANDROID nécessite l'autorisation android.permission.FACE_TRACKING.
  • XR_FACE_TRACKING_DATA_SOURCE_AUDIO_ANDROID nécessite l'autorisation android.permission.RECORD_AUDIO.
  • XR_FACE_TRACKING_DATA_SOURCE_MULTIMODAL_ANDROID nécessite les autorisations android.permission.FACE_TRACKING et android.permission.RECORD_AUDIO.

L'environnement d'exécution doit interpréter le tableau XrFaceTrackingDataSourceInfoANDROID : requestedDataSources de la préférence la plus élevée à la préférence la plus faible par l'application. L'environnement d'exécution doit produire des données de suivi à l'aide de la première source de données demandée qui respecte toujours les autorisations requises. Si une autorisation est révoquée pendant la durée de vie du traceur, rendant une source de données inutilisable, l'environnement d'exécution doit continuer à essayer d'utiliser la source de données de préférence suivante. Si aucune des sources de données demandées n'est utilisable, l'environnement d'exécution doit définir XrFaceStateANDROID :: isValid sur XR_FALSE dans les appels à xrGetFaceStateANDROID, et les autres champs sont considérés comme non définis.

Utilisation valide (implicite)

Autorisations

Les applications Android doivent lister les autorisations qu'elles ont l'intention de demander dans leur fichier manifeste. L'autorisation android.permission.FACE_TRACKING est considérée comme dangereuse. L'autorisation android.permission.RECORD_AUDIO est considérée comme dangereuse. L'application doit demander les autorisations au moment de l'exécution pour utiliser ces fonctions :

(niveau de protection : dangereux)

La structure XrFaceTrackingDataSourceStateANDROID est décrite comme suit :

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

Descriptions des membres

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures. Aucune structure de ce type n'est définie dans OpenXR de base ou dans cette extension.
  • dataSource est l'élément XrFaceTrackingDataSourceANDROID utilisé pour produire les données de suivi du visage.

Une application peut associer une structure XrFaceTrackingDataSourceStateANDROID à une structure XrFaceStateANDROID transmise à xrGetFaceStateANDROID pour interroger la source de données utilisée pour produire les données de suivi du visage pour cet appel.

Utilisation valide (implicite)

Exemple de code pour le suivi du visage avec une source de données.

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

Problèmes

L'historique des versions

  • Révision 1, 07/10/2024 (Kenny Vercaemer)

    • Description initiale de l'extension