XR_ANDROID_face_tracking_data_source

Ciąg znaków nazwy

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 adresu IP

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

Twórcy

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

Omówienie

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

Wykonywanie zapytań dotyczących obsługiwanych źródeł 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, aby wskazać żądanie pobrania wymaganej pojemności.
• supportedDataSourcesOutputCount to liczba obsługiwanych źródeł danych lub wymagana pojemność w przypadku, gdy supportedDataSourcesInputCapacity jest niewystarczająca.
• supportedDataSources to tablica obiektów XrFaceTrackingDataSourceANDROID . Może to być NULL, jeśli supportedDataSourcesInputCapacity wynosi 0.
• Szczegółowy opis pobierania wymaganego rozmiaru supportedDataSources znajdziesz w sekcji Parametry rozmiaru bufora.

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

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

Jeśli środowisko wykonawcze zwróci zero źródeł danych, oznacza to, że 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 (domyślne)

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

Kody zwrotne

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 określa 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;

Wartości wyliczeniowe mają następujące znaczenia:

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 korzysta z danych audio.

XR_FACE_TRACKING_DATA_SOURCE_MULTIMODAL_ANDROID

Wskazuje, że ta konfiguracja korzysta z danych obrazów 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 podstawowej specyfikacji 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 wymagane przez aplikację.

Struktura XrFaceTrackingDataSourceInfoANDROID opisuje źródła danych do utworzenia uchwytu XrFaceTrackerANDROID.

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

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

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

Wymagane uprawnienia dla poszczególnych źródeł danych są zdefiniowane w ten 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 od najwyższych do najniższych. Środowisko wykonawcze musi generować dane śledzenia przy użyciu pierwszego źródła danych, które nadal spełnia wymagane uprawnienia. Jeśli uprawnienie zostanie cofnięte w trakcie działania trackera, co spowoduje, że źródło danych nie będzie już użyteczne, środowisko wykonawcze musi nadal próbować używać kolejnego źródła danych o najwyższym priorytecie. Jeśli żadne z żądanych źródeł danych nie są użyteczne, środowisko wykonawcze musi ustawić XrFaceStateANDROID :: isValid na XR_FALSE w wywołaniach funkcji xrGetFaceStateANDROID, a inne pola są uznawane za niezdefiniowane.

Prawidłowe użycie (domyślne)

•  Rozszerzenie XR_ANDROID_face_tracking_data_source musi być włączone przed użyciem XrFaceTrackingDataSourceInfoANDROID.
• type musi mieć wartość XR_TYPE_FACE_TRACKING_DATA_SOURCE_INFO_ANDROID
• next musi mieć wartość NULL lub być prawidłowym wskaźnikiem do następnej struktury w łańcuchu struktur.
• requestedDataSources musi być wskaźnikiem do tablicy requestedDataSourceCount prawidłowych wartości XrFaceTrackingDataSourceANDROID
•  Parametr requestedDataSourceCount musi być większy niż 0.

Uprawnienia

Aplikacje na Androida muszą mieć uprawnienia, o które chcą poprosić, wymienione w pliku manifestu. 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:

• xrCreateFaceTrackerANDROID

(poziom ochrony: niebezpieczny)

Struktura XrFaceTrackingDataSourceStateANDROID jest opisana w ten 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 podstawowej specyfikacji OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.
• dataSource to XrFaceTrackingDataSourceANDROID używane do generowania danych śledzenia twarzy.

Aplikacja może połączyć strukturę XrFaceTrackingDataSourceStateANDROID ze strukturą XrFaceStateANDROID przekazaną do funkcji xrGetFaceStateANDROID, aby wysłać zapytanie o źródło danych użyte do wygenerowania danych śledzenia twarzy dla tego wywołania.

Prawidłowe użycie (domyślne)

•  Rozszerzenie XR_ANDROID_face_tracking_data_source musi być włączone przed użyciem XrFaceTrackingDataSourceStateANDROID.
• type musi mieć wartość XR_TYPE_FACE_TRACKING_DATA_SOURCE_STATE_ANDROID
• next musi mieć wartość NULL lub być prawidłowym wskaźnikiem do następnej struktury w łańcuchu struktur.
• dataSource musi być prawidłową wartością XrFaceTrackingDataSourceANDROID

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 wersji

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

  • Wstępny opis rozszerzenia