XR_ANDROID_face_tracking_data_source

String Nama

XR_ANDROID_face_tracking_data_source

Jenis Ekstensi

Ekstensi instance

Nomor Ekstensi Terdaftar

707

Revisi

1

Status Ratifikasi

Tidak diratifikasi

Dependensi Ekstensi dan Versi

XR_ANDROID_face_tracking

Tanggal Terakhir Diubah

2025-12-16

Status IP

Tidak ada klaim IP yang diketahui.

Kontributor

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

Ringkasan

Ekstensi ini memungkinkan aplikasi mendapatkan data pelacakan wajah dari beberapa sumber data.

Membuat kueri sumber data yang didukung

Aplikasi harus memanggil xrEnumerateFaceTrackingDataSourcesANDROID untuk mendapatkan daftar sumber data pelacakan wajah yang didukung.

Fungsi xrEnumerateFaceTrackingDataSourcesANDROID ditentukan sebagai:

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

Deskripsi Parameter

  • instance adalah tuas untuk XrInstance .
  • systemId adalah XrSystemId yang sumber data pelacakan wajahnya akan dihitung.
  • supportedDataSourcesInputCapacity adalah kapasitas array supportedDataSources, atau 0 untuk menunjukkan permintaan guna mengambil kapasitas yang diperlukan.
  • supportedDataSourcesOutputCount adalah jumlah sumber data yang didukung, atau kapasitas yang diperlukan jika supportedDataSourcesInputCapacity tidak mencukupi.
  • supportedDataSources adalah array XrFaceTrackingDataSourceANDROID . Nilainya dapat berupa NULL jika supportedDataSourcesInputCapacity adalah 0.
  • Lihat bagian Parameter Ukuran Buffer untuk mengetahui deskripsi mendetail tentang pengambilan ukuran supportedDataSources yang diperlukan.

Aplikasi dapat menghitung daftar sumber data yang didukung oleh sistem dengan memanggil fungsi xrEnumerateFaceTrackingDataSourcesANDROID.

Jika XrSystemFaceTrackingPropertiesANDROID :: supportsFaceTracking adalah XR_TRUE, maka runtime harus juga menampilkan XR_FACE_TRACKING_DATA_SOURCE_IMAGE_ANDROID dari xrEnumerateFaceTrackingDataSourcesANDROID .

Jika runtime menampilkan nol sumber data, berarti runtime tidak mendukung jenis pelacakan wajah apa pun.

Runtime harus menampilkan sumber data dalam urutan kualitas tertinggi hingga kualitas terendah.

Penggunaan yang Valid (Implisit)

  • Ekstensi XR_ANDROID_face_tracking_data_source harus diaktifkan sebelum memanggil xrEnumerateFaceTrackingDataSourcesANDROID
  • instance harus berupa handle XrInstance yang valid
  • supportedDataSourcesOutputCount harus berupa pointer ke nilai uint32_t
  • Jika supportedDataSourcesInputCapacity bukan 0 , supportedDataSources harus berupa pointer ke array nilai supportedDataSourcesInputCapacity XrFaceTrackingDataSourceANDROID

Kode Status

Berhasil

  • XR_SUCCESS

Kegagalan

  • 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

Enumerasi XrFaceTrackingDataSourceANDROID mengidentifikasi berbagai sumber data yang mungkin didukung oleh runtime.

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;

Enumeran memiliki arti berikut:

Deskripsi Enum

XR_FACE_TRACKING_DATA_SOURCE_IMAGE_ANDROID

Menunjukkan bahwa konfigurasi ini menggunakan data gambar

XR_FACE_TRACKING_DATA_SOURCE_AUDIO_ANDROID

Menunjukkan bahwa konfigurasi ini menggunakan data audio

XR_FACE_TRACKING_DATA_SOURCE_MULTIMODAL_ANDROID

Menunjukkan bahwa konfigurasi ini menggunakan data gambar dan audio

Mengonfigurasi sumber data

Struktur XrFaceTrackingDataSourceInfoANDROID dijelaskan sebagai berikut:

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

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur. Tidak ada struktur seperti itu yang ditentukan dalam OpenXR inti atau ekstensi ini.
  • requestedDataSourceCount adalah jumlah sumber data yang diminta oleh aplikasi.
  • requestedDataSources adalah array nilai XrFaceTrackingDataSourceANDROID, yang menentukan sumber data yang diminta oleh aplikasi.

Struktur XrFaceTrackingDataSourceInfoANDROID menjelaskan sumber data untuk membuat handle XrFaceTrackerANDROID.

Aplikasi dapat meneruskan struktur XrFaceTrackingDataSourceInfoANDROID dalam rantai berikutnya dari struktur XrFaceTrackerCreateInfoANDROID untuk meminta satu atau beberapa sumber data untuk pelacakan wajah saat memanggil xrCreateFaceTrackerANDROID .

Jika aplikasi meneruskan nol sumber data, atau salah satu sumber data tidak di-enumerasi oleh xrEnumerateFaceTrackingDataSourcesANDROID , maka runtime harus menampilkan XR_ERROR_VALIDATION_FAILURE .

Jika pengguna belum memberikan semua izin yang diperlukan untuk semua sumber data yang diminta, maka runtime harus menampilkan XR_ERROR_PERMISSION_INSUFFICIENT .

Izin yang diperlukan untuk setiap sumber data ditentukan sebagai berikut:

  • XR_FACE_TRACKING_DATA_SOURCE_IMAGE_ANDROID memerlukan izin android.permission.FACE_TRACKING.
  • XR_FACE_TRACKING_DATA_SOURCE_AUDIO_ANDROID memerlukan izin android.permission.RECORD_AUDIO.
  • XR_FACE_TRACKING_DATA_SOURCE_MULTIMODAL_ANDROID memerlukan izin android.permission.FACE_TRACKING dan android.permission.RECORD_AUDIO.

Runtime harus menafsirkan array XrFaceTrackingDataSourceInfoANDROID : requestedDataSources sebagai preferensi tertinggi hingga terendah oleh aplikasi. Runtime harus menghasilkan data pelacakan menggunakan sumber data pertama yang diminta yang masih mematuhi izin yang diperlukan. Jika izin dicabut selama masa aktif pelacak, sehingga sumber data tidak dapat digunakan lagi, runtime harus terus mencoba menggunakan sumber data dengan preferensi tertinggi berikutnya. Jika tidak ada sumber data yang diminta yang dapat digunakan, runtime harus menyetel XrFaceStateANDROID :: isValid ke XR_FALSE dalam panggilan ke xrGetFaceStateANDROID dan kolom lainnya dianggap tidak ditentukan.

Penggunaan yang Valid (Implisit)

Izin

Aplikasi Android harus mencantumkan izin yang ingin diminta dalam manifesnya. Izin android.permission.FACE_TRACKING dianggap sebagai izin berbahaya. Izin android.permission.RECORD_AUDIO dianggap sebagai izin berbahaya. Aplikasi harus meminta izin saat runtime untuk menggunakan fungsi ini:

(tingkat perlindungan: berbahaya)

Struktur XrFaceTrackingDataSourceStateANDROID dijelaskan sebagai berikut:

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

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur. Tidak ada struktur seperti itu yang ditentukan dalam OpenXR inti atau ekstensi ini.
  • dataSource adalah XrFaceTrackingDataSourceANDROID yang digunakan untuk menghasilkan data pelacakan wajah.

Aplikasi dapat merangkai struktur XrFaceTrackingDataSourceStateANDROID ke struktur XrFaceStateANDROID yang diteruskan ke xrGetFaceStateANDROID untuk mengkueri sumber data yang digunakan untuk menghasilkan data pelacakan wajah untuk panggilan tersebut.

Penggunaan yang Valid (Implisit)

Contoh kode untuk pelacakan wajah dengan sumber data.

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

Masalah

Histori Versi

  • Revisi 1, 07-10-2024 (Kenny Vercaemer)

    • Deskripsi ekstensi awal