XR_ANDROID_face_tracking_data_source

Chaîne de nom

XR_ANDROID_face_tracking_data_source

Type d'extension

Extension d'instance

Numéro d'extension enregistré

707

Révision

1

État de ratification

Non ratifié

Dépendances d'extension et de version

XR_ANDROID_face_tracking

Date de dernière modification

2025-12-16

État de la propriété intellectuelle

Aucune revendication 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 les 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 visant à récupérer la capacité requise.
  • supportedDataSourcesOutputCount correspond au 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.
  • Pour obtenir une description détaillée de la récupération de la taille requise supportedDataSources, consultez la section Paramètres de taille du tampon.

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 renvoie zéro source de données, cela signifie qu'il n'est compatible avec aucun type de 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érateurs 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 les 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;

Description 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 le cœur d'OpenXR ni dans cette extension.
  • requestedDataSourceCount correspond au 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 transmet zéro 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 XrFaceTrackingDataSourceInfoANDROID : requestedDataSources tableau comme la préférence la plus élevée à la plus basse par l'application. L'environnement d'exécution doit générer 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 suivi, ce qui rend une source de données inutilisable, l'environnement d'exécution doit continuer à tenter d'utiliser la source de données de préférence la plus élevée 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 disposer des 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;

Description 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 le cœur d'OpenXR ni dans cette extension.
  • dataSource est le XrFaceTrackingDataSourceANDROID utilisé pour générer les données de suivi du visage.

Une application peut enchaîner une structure XrFaceTrackingDataSourceStateANDROID à une structure XrFaceStateANDROID transmise à xrGetFaceStateANDROID pour interroger la source de données utilisée pour générer 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