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 des Abrufs 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. In OpenXR Core oder dieser Erweiterung sind keine solchen Strukturen 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 zum Erstellen eines XrFaceTrackerANDROID-Handles.

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 die Mimikerkennung 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:

  • 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 XrFaceTrackingDataSourceInfoANDROID : requestedDataSources Array als höchste bis niedrigste Präferenz der Anwendung interpretieren. Die Laufzeit muss Trackingdaten mit der ersten angeforderten Datenquelle erstellen, die die erforderlichen Berechtigungen erfüllt. 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 nächsthöhere bevorzugte Datenquelle 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. In OpenXR Core oder dieser Erweiterung sind keine solchen Strukturen 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