XR_ANDROID_face_tracking_data_source

Name String

XR_ANDROID_face_tracking_data_source

Tipo di estensione

Estensione dell'istanza

Numero di interno registrato

707

Revisione

1

Stato della ratifica

Non ratificato

Dipendenze di estensioni e versioni

XR_ANDROID_face_tracking

Data ultima modifica

2025-12-16

Stato IP

Nessuna rivendicazione di PI nota.

Collaboratori

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

Panoramica

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

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

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 non sia sufficiente.
  • supportedDataSources è un array di XrFaceTrackingDataSourceANDROID . Può essere NULL se supportedDataSourcesInputCapacity è 0.
  • Consulta la sezione Parametri della dimensione del buffer per una descrizione dettagliata del recupero della dimensione supportedDataSources richiesta.

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

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

Se il runtime non restituisce 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 attivata 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 di risposta

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 enum

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 dati audio

XR_FACE_TRACKING_DATA_SOURCE_MULTIMODAL_ANDROID

Indica che questa configurazione utilizza dati di immagini e audio

Configurazione delle origini dati

La struttura XrFaceTrackingDataSourceInfoANDROID è descritta di seguito:

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. Nessuna struttura di questo tipo è definita in OpenXR di base 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 facciale quando chiama xrCreateFaceTrackerANDROID .

Se l'applicazione non passa 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 entrambe le autorizzazioni android.permission.FACE_TRACKING e android.permission.RECORD_AUDIO.

Il runtime deve interpretare l'array XrFaceTrackingDataSourceInfoANDROID : requestedDataSources come preferenza più alta a quella più bassa dell'applicazione. Il runtime deve produrre dati di monitoraggio utilizzando la prima origine dati richiesta che rispetta ancora le autorizzazioni richieste. Se un'autorizzazione viene revocata durante il ciclo di vita del tracker, rendendo un'origine dati non più utilizzabile, il runtime deve continuare a tentare di utilizzare l'origine dati con la preferenza più alta successiva. 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 app per Android devono avere le autorizzazioni che intendono richiedere elencate nel loro 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 di seguito:

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. Nessuna struttura di questo tipo è definita in OpenXR di base o in questa estensione.
  • dataSource è l'oggetto 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