XR_ANDROID_face_tracking_data_source

Stringa del nome

XR_ANDROID_face_tracking_data_source

Tipo di estensione

Estensione dell'istanza

Numero di estensione registrata

707

Revisione

1

Stato di ratifica

Non ratificato

Dipendenze di estensione e versione

XR_ANDROID_face_tracking

Data dell'ultima modifica

2025-12-16

Stato IP

Nessuna rivendicazione IP nota.

Collaboratori

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

Panoramica

Questa estensione consente alle applicazioni di ottenere i dati di tracciamento facciale da più origini dati.

Eseguire query sulle origini dati supportate

Le applicazioni devono chiamare xrEnumerateFaceTrackingDataSourcesANDROID per ottenere l'elenco delle origini dati di tracciamento facciale supportate.

La funzione xrEnumerateFaceTrackingDataSourcesANDROID è definita come segue:

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

Descrizioni dei parametri

  • instance è un handle per un XrInstance .
  • systemId è l'XrSystemId per cui verranno enumerate le origini dati di tracciamento facciale.
  • supportedDataSourcesInputCapacity è la capacità dell'array supportedDataSources o 0 per indicare una richiesta di recupero della capacità richiesta.
  • supportedDataSourcesOutputCount è il numero di origini dati supportate o la capacità richiesta nel caso in cui supportedDataSourcesInputCapacity sia insufficiente.
  • supportedDataSources è un array di XrFaceTrackingDataSourceANDROID . Può essere NULL se supportedDataSourcesInputCapacity è 0.
  • Per una descrizione dettagliata del recupero delle dimensioni supportedDataSources richieste, consulta la sezione Parametri delle dimensioni del buffer.

L'applicazione può enumerare l'elenco delle origini dati supportate dal sistema chiamando la funzione xrEnumerateFaceTrackingDataSourcesANDROID.

Se XrSystemFaceTrackingPropertiesANDROID :: supportsFaceTracking è XR_TRUE , il runtime deve restituire anche XR_FACE_TRACKING_DATA_SOURCE_IMAGE_ANDROID da xrEnumerateFaceTrackingDataSourcesANDROID .

Se il runtime restituisce zero origini dati, non supporta alcun tipo di tracciamento facciale.

Il runtime deve restituire le origini dati in ordine di qualità, dalla più alta alla più bassa.

Utilizzo valido (implicito)

  • L'estensione XR_ANDROID_face_tracking_data_source deve essere abilitata prima di chiamare xrEnumerateFaceTrackingDataSourcesANDROID
  • instance deve essere un handle XrInstance valido
  • supportedDataSourcesOutputCount deve essere un puntatore a un valore uint32_t
  • Se supportedDataSourcesInputCapacity non è 0 , supportedDataSources deve essere un puntatore a un array di valori supportedDataSourcesInputCapacity XrFaceTrackingDataSourceANDROID

Codici restituiti

Operazione riuscita

  • XR_SUCCESS

Errore

  • 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'enumerazione XrFaceTrackingDataSourceANDROID identifica le diverse origini dati che un runtime può supportare.

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;

Gli enumeranti hanno i seguenti significati:

Descrizione dell'enumerazione

XR_FACE_TRACKING_DATA_SOURCE_IMAGE_ANDROID

Indica che questa configurazione utilizza i dati delle immagini

XR_FACE_TRACKING_DATA_SOURCE_AUDIO_ANDROID

Indica che questa configurazione utilizza i dati audio

XR_FACE_TRACKING_DATA_SOURCE_MULTIMODAL_ANDROID

Indica che questa configurazione utilizza i dati di immagini e audio

Configurare le origini dati

La struttura XrFaceTrackingDataSourceInfoANDROID è descritta come segue:

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

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Non sono definite strutture di questo tipo in OpenXR core o in questa estensione.
  • requestedDataSourceCount è il numero di origini dati richieste dall'applicazione.
  • requestedDataSources è un array di valori XrFaceTrackingDataSourceANDROID che specifica le origini dati richieste dall'applicazione.

La struttura XrFaceTrackingDataSourceInfoANDROID descrive le origini dati per creare un handle XrFaceTrackerANDROID.

Un'applicazione può passare una struttura XrFaceTrackingDataSourceInfoANDROID nella catena successiva di una struttura XrFaceTrackerCreateInfoANDROID per richiedere una o più origini dati per il tracciamento del viso quando chiama xrCreateFaceTrackerANDROID .

Se l'applicazione passa zero origini dati o se una delle origini dati non è stata enumerata da xrEnumerateFaceTrackingDataSourcesANDROID , il runtime deve restituire XR_ERROR_VALIDATION_FAILURE .

Se l'utente non ha concesso tutte le autorizzazioni richieste per tutte le origini dati richieste, il runtime deve restituire XR_ERROR_PERMISSION_INSUFFICIENT .

Le autorizzazioni richieste per ogni origine dati sono definite come segue:

  • XR_FACE_TRACKING_DATA_SOURCE_IMAGE_ANDROID richiede l'autorizzazione android.permission.FACE_TRACKING.
  • XR_FACE_TRACKING_DATA_SOURCE_AUDIO_ANDROID richiede l'autorizzazione android.permission.RECORD_AUDIO.
  • XR_FACE_TRACKING_DATA_SOURCE_MULTIMODAL_ANDROID richiede le autorizzazioni android.permission.FACE_TRACKING e android.permission.RECORD_AUDIO.

Il runtime deve interpretare l'array XrFaceTrackingDataSourceInfoANDROID : requestedDataSources come preferenza più alta rispetto alla preferenza più bassa dell'applicazione. Il runtime deve produrre dati di tracciamento utilizzando la prima origine dati richiesta che sia ancora conforme alle autorizzazioni richieste. Se un'autorizzazione viene revocata durante la durata del tracker, rendendo inutilizzabile un'origine dati, il runtime deve continuare a tentare di utilizzare l'origine dati con la preferenza successiva più alta. Se nessuna delle origini dati richieste è utilizzabile, il runtime deve impostare XrFaceStateANDROID :: isValid su XR_FALSE nelle chiamate a xrGetFaceStateANDROID e gli altri campi sono considerati non definiti.

Utilizzo valido (implicito)

Autorizzazioni

Le applicazioni Android devono avere le autorizzazioni che intendono richiedere elencate nel file manifest. L'autorizzazione android.permission.FACE_TRACKING è considerata pericolosa. L'autorizzazione android.permission.RECORD_AUDIO è considerata pericolosa. L'applicazione deve richiedere le autorizzazioni in fase di runtime per utilizzare queste funzioni:

(livello di protezione: pericoloso)

La struttura XrFaceTrackingDataSourceStateANDROID è descritta come segue:

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

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Non sono definite strutture di questo tipo in OpenXR core o in questa estensione.
  • dataSource è l'XrFaceTrackingDataSourceANDROID utilizzato per produrre i dati di tracciamento facciale.

Un'applicazione può concatenare una struttura XrFaceTrackingDataSourceStateANDROID a una struttura XrFaceStateANDROID passata a xrGetFaceStateANDROID per eseguire una query sull'origine dati utilizzata per produrre i dati di tracciamento facciale per quella chiamata.

Utilizzo valido (implicito)

Esempio di codice per il tracciamento facciale con l'origine dati.

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

Problemi

Cronologia delle versioni

  • Revisione 1, 07/10/2024 (Kenny Vercaemer)

    • Descrizione iniziale dell'estensione