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 des extensions et des versions

XR_ANDROID_face_tracking

Date de dernière modification

2025-12-16

État de l'adresse IP

Aucune réclamation connue pour atteinte à la propriété intellectuelle.

Contributeurs

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

Descriptions des paramètres

  • instance est un handle vers une XrInstance .
  • systemId est le XrSystemId pour lequel les sources de données de suivi du visage seront énumérées.
  • supportedDataSourcesInputCapacity correspond à 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 acceptées ou à la capacité requise si supportedDataSourcesInputCapacity est insuffisant.
  • supportedDataSources est un tableau de XrFaceTrackingDataSourceANDROID . Elle peut être NULL si supportedDataSourcesInputCapacity est défini sur 0.
  • Pour obtenir une description détaillée de la récupération de la taille supportedDataSources requise, consultez la section Paramètres de taille du tampon.

L'application peut énumérer la liste des sources de données prises en charge par 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 le runtime renvoie zéro source de données, cela signifie qu'il n'accepte aucun type de suivi du visage.

Le runtime doit renvoyer les sources de données de la meilleure à la moins bonne qualité.

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 must ê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 de retour

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 l'extension ni dans le cœur d'OpenXR.
  • 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, le runtime 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, le runtime 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'exécution doit interpréter le tableau requestedDataSources XrFaceTrackingDataSourceInfoANDROID comme la préférence la plus élevée à la préférence la plus basse par l'application. L'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, ce qui rend une source de données inutilisable, le runtime 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, le runtime 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 prévoient 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 l'extension ni dans le cœur d'OpenXR.
  • dataSource est la XrFaceTrackingDataSourceANDROID utilisée pour produire les données de suivi du visage.

Une application peut chaî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

Historique des versions

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

    • Description initiale de l'extension