XR_ANDROID_face_tracking_data_source

Name String

XR_ANDROID_face_tracking_data_source

Erweiterungstyp

Instanzerweiterung

Registrierte Erweiterungsnummer

707

Revision

1

Ratifizierungsstatus

Nicht ratifiziert

Abhängigkeiten von Erweiterungen und Versionen

XR_ANDROID_face_tracking

Datum der letzten Änderung

2025-12-16

IP-Status

Keine bekannten IP-Ansprüche.

Mitwirkende

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

Übersicht

Mit dieser Erweiterung können Anwendungen Daten zur Mimikerkennung aus mehreren Datenquellen abrufen.

Unterstützte Datenquellen abfragen

Anwendungen sollten xrEnumerateFaceTrackingDataSourcesANDROID aufrufen, um die Liste der unterstützten Datenquellen für die Mimikerkennung 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 Mimikerkennung 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 . Es 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 ist, XR_TRUE die Laufzeit muss auch XR_FACE_TRACKING_DATA_SOURCE_IMAGE_ANDROID von xrEnumerateFaceTrackingDataSourcesANDROID zurückgeben .

Wenn die Laufzeit keine Datenquellen zurückgibt, unterstützt sie keine Mimik-Erkennung.

Die Laufzeit muss die Datenquellen in der Reihenfolge von höchster zu niedrigster Qualität zurückgeben.

Gültige Verwendung (implizit)

  • Die Erweiterung XR_ANDROID_face_tracking_data_source muss aktiviert sein, 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“ identifiziert die verschiedenen Datenquellen, die eine Laufzeit unterstützen kann.

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 Aufzählungselemente haben folgende Bedeutung:

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 in OpenXR Core oder dieser Erweiterung nicht definiert.
  • requestedDataSourceCount ist die Anzahl der von der Anwendung angeforderten Datenquellen.
  • requestedDataSources ist ein Array von XrFaceTrackingDataSourceANDROID-Werten, das die von der Anwendung angeforderten Datenquellen angibt.

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 Aufrufen von „xrCreateFaceTrackerANDROID“ eine oder mehrere Datenquellen für das Face-Tracking 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 jede Datenquelle sind so definiert:

  • XR_FACE_TRACKING_DATA_SOURCE_IMAGE_ANDROID erfordert die Berechtigung „android.permission.FACE_TRACKING“.
  • XR_FACE_TRACKING_DATA_SOURCE_AUDIO_ANDROID erfordert die Berechtigung „android.permission.RECORD_AUDIO“.
  • XR_FACE_TRACKING_DATA_SOURCE_MULTIMODAL_ANDROID erfordert die Berechtigungen „android.permission.FACE_TRACKING“ und „android.permission.RECORD_AUDIO“.

Die Laufzeit muss das XrFaceTrackingDataSourceInfoANDROID : requestedDataSources Array als höchste bis niedrigste Präferenz der Anwendung interpretieren. Die Laufzeit muss Trackingdaten mit der ersten angeforderten Datenquelle erstellen, die weiterhin 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 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-Anwendungen 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:

(Schutzstufe: 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 in OpenXR Core oder dieser Erweiterung nicht definiert.
  • dataSource ist die XrFaceTrackingDataSourceANDROID, die zum Erstellen der Daten zur Mimikerkennung 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 Daten zur Mimikerkennung 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

  • Revision 1, 07.10.2024 (Kenny Vercaemer)

    • Erste Beschreibung der Erweiterung