XR_ANDROID_face_tracking_data_source

Nazwa ciągu znaków

XR_ANDROID_face_tracking_data_source

Typ rozszerzenia

Rozszerzenie instancji

Zarejestrowany numer rozszerzenia

707

Wersja

1

Stan ratyfikacji

Niezatwierdzone

Zależności rozszerzenia 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ł danych.

Wysyłanie zapytań do obsługiwanych źródeł danych

Aplikacje powinny wywoływać 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ć prośbę o pobranie wymaganej pojemności.
  • supportedDataSourcesOutputCount to liczba obsługiwanych źródeł danych lub wymagana pojemność w przypadku, gdy supportedDataSourcesInputCapacity jest niewystarczająca.
  • supportedDataSources to tablica XrFaceTrackingDataSourceANDROID . Jeśli supportedDataSourcesInputCapacity ma wartość 0, może mieć wartość NULL.
  • 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ż zwrócić XR_FACE_TRACKING_DATA_SOURCE_IMAGE_ANDROID z xrEnumerateFaceTrackingDataSourcesANDROID .

Jeśli środowisko wykonawcze zwraca 0 ź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 (pośrednie)

  • Przed wywołaniem xrEnumerateFaceTrackingDataSourcesANDROID musi być włączone rozszerzenie XR_ANDROID_face_tracking_data_source.
  • 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 powrotu

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 mogą być obsługiwane przez środowisko wykonawcze.

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;

Wyliczenia mają te znaczenia:

Opis wyliczenia

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 elementów

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur. W podstawowym OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.
  • requestedDataSourceCount to liczba źródeł danych wymaganych przez aplikację.
  • requestedDataSources to tablica wartości XrFaceTrackingDataSourceANDROID określająca źródła danych wymagane przez aplikację.

Struktura XrFaceTrackingDataSourceInfoANDROID opisuje źródła danych, które mają utworzyć uchwyt 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 xrCreateFaceTrackerANDROID .

Jeśli aplikacja przekaże 0 ź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 wymaganych źródeł danych, środowisko wykonawcze musi zwrócić XR_ERROR_PERMISSION_INSUFFICIENT .

Wymagane uprawnienia dla każdego źródła 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 aplikacji od najwyższych do najniższych. Środowisko wykonawcze musi generować dane śledzenia za pomocą pierwszego wymaganego źródła danych, które nadal spełnia wymagane uprawnienia. Jeśli uprawnienie zostanie cofnięte podczas działania trackera, co spowoduje, że źródło danych nie będzie już używane, środowisko wykonawcze musi nadal próbować używać następnego źródła danych o najwyższych preferencjach. Jeśli żadne z wymaganych źródeł danych nie jest używane, ś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ć uprawnienia, o które chcą poprosić, wymienione w pliku manifestu. Uprawnienie android.permission.FACE_TRACKING jest uważane za niebezpieczne. Uprawnienie android.permission.RECORD_AUDIO jest uważane za niebezpieczne. Aby używać tych funkcji, aplikacja musi poprosić o uprawnienia w czasie działania:

(poziom ochrony: niebezpieczny)

Struktura XrFaceTrackingDataSourceStateANDROID jest opisana w ten sposób:

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

Opisy elementów

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur. W podstawowym 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 xrGetFaceStateANDROID, aby wysłać zapytanie o źródło danych używane 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 wersji

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

    • Początkowy opis rozszerzenia