XR_ANDROID_face_tracking_data_source

Stringa del nome

XR_ANDROID_face_tracking_data_source

Tipo di estensione

Estensione dell'istanza

Numero di interno registrato

707

Revisione

1

Stato di ratifica

Non ratificato

Dipendenze da estensioni e versioni

XR_ANDROID_face_tracking

Data ultima modifica

2025-12-16

Stato IP

Nessuna rivendicazione di proprietà intellettuale 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.

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:

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

Descrizioni dei parametri

  • instance è un handle per un XrInstance .
  • systemId è il XrSystemId per cui verranno elencate 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 delle dimensioni del buffer per una descrizione dettagliata del recupero delle dimensioni supportedDataSources richieste.

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à decrescente.

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 ritorno

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 potrebbe 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 dati immagine

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

Configurare le origini dati

La struttura XrFaceTrackingDataSourceInfoANDROID è descritta nel seguente modo:

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 rilevamento del volto quando chiama xrCreateFaceTrackerANDROID .

Se l'applicazione supera 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.

L'ambiente di runtime deve interpretare l'array XrFaceTrackingDataSourceInfoANDROID : requestedDataSources come preferenza più alta a preferenza più bassa per l'applicazione. Il runtime deve produrre dati di monitoraggio utilizzando la prima origine dati richiesta che sia ancora conforme alle autorizzazioni richieste. Se un'autorizzazione viene revocata durante la durata del tracker, causando la mancata utilizzabilità di un'origine dati, il runtime deve continuare a tentare di utilizzare l'origine dati con la priorità 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 vengono considerati non definiti.

Utilizzo valido (implicito)

Autorizzazioni

Le applicazioni Android devono avere le autorizzazioni che intendono richiedere elencate nel 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 nel seguente modo:

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 è 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 query sull'origine dati utilizzata per produrre i dati di tracciamento facciale per quella chiamata.

Utilizzo valido (implicito)

Codice di esempio 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