XR_ANDROID_face_tracking_data_source

Name String

XR_ANDROID_face_tracking_data_source

Typ rozszerzenia

Rozszerzenie instancji

Zarejestrowany numer wewnętrzny

707

Wersja

1

Stan ratyfikacji

Nie ratyfikowano

Zależności rozszerzeń i wersji

XR_ANDROID_face_tracking

Data ostatniej modyfikacji

2025-12-16

Stan IP

Brak znanych roszczeń dotyczących własności intelektualnej.

Twórcy

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

Przegląd

To rozszerzenie umożliwia aplikacjom uzyskiwanie danych śledzenia twarzy z wielu źródeł.

Wykonywanie zapytań na obsługiwanych źródłach danych

Aplikacje powinny wywoływać funkcję xrEnumerateFaceTrackingDataSourcesANDROID, aby uzyskać listę obsługiwanych źródeł danych śledzenia twarzy.

Funkcja xrEnumerateFaceTrackingDataSourcesANDROID jest zdefiniowana w ten sposób:

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

Opisy parametrów

  • instance to uchwyt do XrInstance .
  • systemId to XrSystemId, dla którego zostaną wyliczone źródła danych śledzenia twarzy.
  • supportedDataSourcesInputCapacity to pojemność tablicy supportedDataSources lub 0, co oznacza prośbę o pobranie wymaganej pojemności.
  • supportedDataSourcesOutputCount to liczba obsługiwanych źródeł danych lub wymagana pojemność, jeśli supportedDataSourcesInputCapacity jest niewystarczająca.
  • supportedDataSources to tablica XrFaceTrackingDataSourceANDROID . Może mieć wartość NULL, jeśli supportedDataSourcesInputCapacity wynosi 0.
  • Szczegółowy opis pobierania wymaganego rozmiaru supportedDataSources znajdziesz w sekcji Parametry rozmiaru bufora.

Aplikacja może wyświetlić listę źródeł danych obsługiwanych przez system, wywołując funkcję xrEnumerateFaceTrackingDataSourcesANDROID.

Jeśli XrSystemFaceTrackingPropertiesANDROID :: supportsFaceTracking to XR_TRUE, środowisko wykonawcze musi też zwracać XR_FACE_TRACKING_DATA_SOURCE_IMAGE_ANDROID z xrEnumerateFaceTrackingDataSourcesANDROID .

Jeśli środowisko wykonawcze nie zwraca żadnych źródeł danych, nie obsługuje żadnego rodzaju śledzenia twarzy.

Środowisko wykonawcze musi zwracać źródła danych w kolejności od najwyższej do najniższej jakości.

Prawidłowe użycie (pośrednie)

  • Rozszerzenie XR_ANDROID_face_tracking_data_source musi być włączone przed wywołaniem xrEnumerateFaceTrackingDataSourcesANDROID.
  • instance musi być prawidłowym uchwytem XrInstance
  • supportedDataSourcesOutputCount musi być wskaźnikiem do wartości uint32_t
  • Jeśli supportedDataSourcesInputCapacity nie jest równe 0 , supportedDataSources musi być wskaźnikiem do tablicy wartości supportedDataSourcesInputCapacity XrFaceTrackingDataSourceANDROID

Kody zwrotu

Sukces

  • XR_SUCCESS

Błąd

  • 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

Wyliczenie XrFaceTrackingDataSourceANDROID identyfikuje różne źródła danych, które środowisko wykonawcze może obsługiwać.

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;

Elementy wyliczenia mają następujące znaczenie:

Opis typu wyliczeniowego

XR_FACE_TRACKING_DATA_SOURCE_IMAGE_ANDROID

Wskazuje, że ta konfiguracja używa danych obrazu

XR_FACE_TRACKING_DATA_SOURCE_AUDIO_ANDROID

Wskazuje, że ta konfiguracja używa danych audio

XR_FACE_TRACKING_DATA_SOURCE_MULTIMODAL_ANDROID

Wskazuje, że ta konfiguracja używa danych obrazu i dźwięku

Konfigurowanie źródeł danych

Struktura XrFaceTrackingDataSourceInfoANDROID jest opisana w ten sposób:

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

Opisy członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur. W podstawowym interfejsie OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.
  • requestedDataSourceCount to liczba źródeł danych, o które prosi aplikacja.
  • requestedDataSources to tablica wartości XrFaceTrackingDataSourceANDROID, która określa źródła danych żądane przez aplikację.

Struktura XrFaceTrackingDataSourceInfoANDROID opisuje źródła danych, które umożliwiają utworzenie uchwytu XrFaceTrackerANDROID.

Aplikacja może przekazać strukturę XrFaceTrackingDataSourceInfoANDROID w następnym łańcuchu struktury XrFaceTrackerCreateInfoANDROID, aby zażądać co najmniej 1 źródła danych do śledzenia twarzy podczas wywoływania funkcji xrCreateFaceTrackerANDROID .

Jeśli aplikacja nie przekazuje żadnych źródeł danych lub którekolwiek ze źródeł danych nie zostało wyliczone przez xrEnumerateFaceTrackingDataSourcesANDROID, środowisko wykonawcze musi zwrócić XR_ERROR_VALIDATION_FAILURE .

Jeśli użytkownik nie przyznał wszystkich wymaganych uprawnień do wszystkich żądanych źródeł danych, środowisko wykonawcze musi zwrócić błąd XR_ERROR_PERMISSION_INSUFFICIENT .

Wymagane uprawnienia dla każdego źródła danych są zdefiniowane w następujący sposób:

  • XR_FACE_TRACKING_DATA_SOURCE_IMAGE_ANDROID wymaga uprawnienia android.permission.FACE_TRACKING.
  • XR_FACE_TRACKING_DATA_SOURCE_AUDIO_ANDROID wymaga uprawnienia android.permission.RECORD_AUDIO.
  • XR_FACE_TRACKING_DATA_SOURCE_MULTIMODAL_ANDROID wymaga uprawnień android.permission.FACE_TRACKING i android.permission.RECORD_AUDIO.

Środowisko wykonawcze musi interpretować tablicę XrFaceTrackingDataSourceInfoANDROID : requestedDataSources jako preferencje aplikacji od najwyższych do najniższych. Środowisko wykonawcze musi generować dane śledzenia, korzystając z pierwszego żądanego źródła danych, które nadal jest zgodne z wymaganymi uprawnieniami. Jeśli uprawnienie zostanie cofnięte w czasie działania modułu śledzącego, co spowoduje, że źródło danych nie będzie już możliwe do użycia, środowisko wykonawcze musi nadal próbować używać źródła danych o następnym najwyższym priorytecie. Jeśli żadne z żądanych źródeł danych nie nadaje się do użytku, środowisko wykonawcze musi ustawić XrFaceStateANDROID :: isValid na XR_FALSE w wywołaniach xrGetFaceStateANDROID, a inne pola są uznawane za niezdefiniowane.

Prawidłowe użycie (pośrednie)

Uprawnienia

Aplikacje na Androida muszą mieć w pliku manifestu listę uprawnień, o które chcą prosić. Uprawnienie android.permission.FACE_TRACKING jest uznawane za niebezpieczne. Uprawnienie android.permission.RECORD_AUDIO jest uznawane za niebezpieczne. Aby korzystać z tych funkcji, aplikacja musi prosić o uprawnienia w czasie działania:

(poziom ochrony: niebezpieczne)

Struktura XrFaceTrackingDataSourceStateANDROID jest opisana w następujący sposób:

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

Opisy członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur. W podstawowym interfejsie OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.
  • dataSource to XrFaceTrackingDataSourceANDROID używany do generowania danych śledzenia twarzy.

Aplikacja może połączyć strukturę XrFaceTrackingDataSourceStateANDROID ze strukturą XrFaceStateANDROID przekazaną do xrGetFaceStateANDROID, aby wysłać zapytanie do źródła danych używanego do generowania danych śledzenia twarzy na potrzeby tego wywołania.

Prawidłowe użycie (pośrednie)

Przykładowy kod śledzenia twarzy ze źródłem danych.

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

Problemy

Historia zmian

  • Wersja 1, 7 października 2024 r. (Kenny Vercaemer)

    • Początkowy opis rozszerzenia