XR_ANDROID_face_tracking_data_source

Name String

XR_ANDROID_face_tracking_data_source

Erweiterungstyp

Instanzerweiterung

Registrierte Durchwahl

707

Revision

1

Ratification Status

Nicht ratifiziert

Erweiterungs- und Versionsabhängigkeiten

XR_ANDROID_face_tracking

Datum der letzten Änderung

2025-12-16

IP-Status

Keine bekannten Ansprüche auf geistiges Eigentum.

Mitwirkende

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

Übersicht

Mit dieser Erweiterung können Anwendungen Daten zur Mimik-Erkennung aus mehreren Datenquellen abrufen.

Unterstützte Datenquellen abfragen

Anwendungen sollten xrEnumerateFaceTrackingDataSourcesANDROID aufrufen, um die Liste der unterstützten Datenquellen für die Mimik-Erkennung abzurufen.

Die Funktion xrEnumerateFaceTrackingDataSourcesANDROID ist so definiert:

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

Parameterbeschreibungen

  • instance ist ein Handle für eine XrInstance .
  • systemId ist die XrSystemId, für die die Datenquellen für die Mimik-Erkennung aufgezählt werden.
  • supportedDataSourcesInputCapacity ist die Kapazität des supportedDataSources-Arrays oder 0, um eine Anfrage zum Abrufen der erforderlichen Kapazität anzugeben.
  • supportedDataSourcesOutputCount ist die Anzahl der unterstützten Datenquellen oder die erforderliche Kapazität, falls supportedDataSourcesInputCapacity nicht ausreicht.
  • supportedDataSources ist ein Array von XrFaceTrackingDataSourceANDROID . Er kann NULL sein, wenn supportedDataSourcesInputCapacity 0 ist.
  • Eine detaillierte Beschreibung zum Abrufen der erforderlichen supportedDataSources-Größe finden Sie im Abschnitt Parameter für die Puffergröße.

Die Anwendung kann die Liste der vom System unterstützten Datenquellen aufzählen, indem sie die Funktion xrEnumerateFaceTrackingDataSourcesANDROID aufruft.

Wenn XrSystemFaceTrackingPropertiesANDROID :: supportsFaceTracking XR_TRUE ist, muss die Laufzeit auch XR_FACE_TRACKING_DATA_SOURCE_IMAGE_ANDROID von xrEnumerateFaceTrackingDataSourcesANDROID zurückgeben.

Wenn die Laufzeit keine Datenquellen zurückgibt, wird keine Art von Mimik-Erkennung unterstützt.

Die Laufzeit muss die Datenquellen in der Reihenfolge von der höchsten zur niedrigsten Qualität zurückgeben.

Gültige Verwendung (implizit)

  • Die Erweiterung XR_ANDROID_face_tracking_data_source muss aktiviert werden, bevor xrEnumerateFaceTrackingDataSourcesANDROID aufgerufen wird.
  • instance muss ein gültiges XrInstance-Handle sein
  • supportedDataSourcesOutputCount muss ein Zeiger auf einen uint32_t-Wert sein
  • Wenn supportedDataSourcesInputCapacity nicht 0 ist, supportedDataSources muss ein Zeiger auf ein Array von supportedDataSourcesInputCapacity XrFaceTrackingDataSourceANDROID-Werten sein.

Rückgabecodes

Erfolg

  • XR_SUCCESS

Fehler

  • 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

Die Aufzählung XrFaceTrackingDataSourceANDROID gibt die verschiedenen Datenquellen an, die eine Laufzeit möglicherweise unterstützt.

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;

Die Enumeranten haben die folgenden Bedeutungen:

Enum-Beschreibung

XR_FACE_TRACKING_DATA_SOURCE_IMAGE_ANDROID

Gibt an, dass diese Konfiguration Bilddaten verwendet

XR_FACE_TRACKING_DATA_SOURCE_AUDIO_ANDROID

Gibt an, dass diese Konfiguration Audiodaten verwendet

XR_FACE_TRACKING_DATA_SOURCE_MULTIMODAL_ANDROID

Gibt an, dass diese Konfiguration Bild- und Audiodaten verwendet

Datenquellen konfigurieren

Die Struktur XrFaceTrackingDataSourceInfoANDROID wird so beschrieben:

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

Mitgliederbeschreibungen

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind weder in OpenXR noch in dieser Erweiterung definiert.
  • requestedDataSourceCount ist die Anzahl der von der Anwendung angeforderten Datenquellen.
  • requestedDataSources ist ein Array von XrFaceTrackingDataSourceANDROID-Werten, die die von der Anwendung angeforderten Datenquellen angeben.

Die Struktur XrFaceTrackingDataSourceInfoANDROID beschreibt die Datenquellen, die zum Erstellen eines XrFaceTrackerANDROID-Handles verwendet werden.

Eine Anwendung kann eine XrFaceTrackingDataSourceInfoANDROID-Struktur in der nächsten Kette einer XrFaceTrackerCreateInfoANDROID-Struktur übergeben, um beim Aufruf von xrCreateFaceTrackerANDROID eine oder mehrere Datenquellen für die Mimik-Erkennung anzufordern.

Wenn die Anwendung keine Datenquellen übergibt oder eine der Datenquellen nicht von xrEnumerateFaceTrackingDataSourcesANDROID aufgezählt wurde, muss die Laufzeit XR_ERROR_VALIDATION_FAILURE zurückgeben.

Wenn der Nutzer nicht alle erforderlichen Berechtigungen für alle angeforderten Datenquellen erteilt hat, muss die Laufzeit XR_ERROR_PERMISSION_INSUFFICIENT zurückgeben.

Die erforderlichen Berechtigungen für die einzelnen Datenquellen sind so definiert:

  • Für XR_FACE_TRACKING_DATA_SOURCE_IMAGE_ANDROID ist die Berechtigung „android.permission.FACE_TRACKING“ erforderlich.
  • Für XR_FACE_TRACKING_DATA_SOURCE_AUDIO_ANDROID ist die Berechtigung „android.permission.RECORD_AUDIO“ erforderlich.
  • Für XR_FACE_TRACKING_DATA_SOURCE_MULTIMODAL_ANDROID sind die Berechtigungen „android.permission.FACE_TRACKING“ und „android.permission.RECORD_AUDIO“ erforderlich.

Die Laufzeit muss das Array XrFaceTrackingDataSourceInfoANDROID : requestedDataSources von der höchsten zur niedrigsten Präferenz der Anwendung interpretieren. Die Laufzeit muss Tracking-Daten mit der ersten angeforderten Datenquelle erzeugen, die noch den erforderlichen Berechtigungen entspricht. Wenn eine Berechtigung während der Lebensdauer des Trackers widerrufen wird, sodass eine Datenquelle nicht mehr verwendet werden kann, muss die Laufzeit weiterhin versuchen, die Datenquelle mit der nächsthöheren Präferenz zu verwenden. Wenn keine der angeforderten Datenquellen verwendet werden kann, muss die Laufzeit XrFaceStateANDROID :: isValid in Aufrufen von xrGetFaceStateANDROID auf XR_FALSE setzen. Andere Felder gelten als nicht definiert.

Gültige Verwendung (implizit)

Berechtigungen

Android-Apps müssen die Berechtigungen, die sie anfordern möchten, in ihrem Manifest auflisten. Die Berechtigung „android.permission.FACE_TRACKING“ gilt als gefährliche Berechtigung. Die Berechtigung „android.permission.RECORD_AUDIO“ gilt als gefährliche Berechtigung. Die Anwendung muss die Berechtigungen zur Laufzeit anfordern, um diese Funktionen zu verwenden:

(Schutzebene: gefährlich)

Die Struktur XrFaceTrackingDataSourceStateANDROID wird so beschrieben:

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

Mitgliederbeschreibungen

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind weder in OpenXR noch in dieser Erweiterung definiert.
  • dataSource ist die XrFaceTrackingDataSourceANDROID, die zum Erstellen der Daten zur Mimik-Erkennung verwendet wird.

Eine Anwendung kann eine XrFaceTrackingDataSourceStateANDROID-Struktur mit einer XrFaceStateANDROID-Struktur verketten, die an xrGetFaceStateANDROID übergeben wird, um die Datenquelle abzufragen, die zum Erstellen der Mimik-Erkennungsdaten für diesen Aufruf verwendet wurde.

Gültige Verwendung (implizit)

Beispielcode für die Mimik-Erkennung mit Datenquelle.

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

Probleme

Versionsverlauf

  • Version 1, 07.10.2024 (Kenny Vercaemer)

    • Anfängliche Beschreibung der Erweiterung