Google berkomitmen untuk mendorong terwujudnya keadilan ras bagi komunitas Kulit Hitam. Lihat caranya.

Menambahkan fungsi pengaturan waktu render frame

Gunakan fungsi dalam topik ini untuk mengintegrasikan library Tuning Fork ke dalam kode game Anda.

File header di include/tuningfork/tuningfork.h berisi antarmuka inti untuk library Tuning Fork. File di include/tuningfork/tuningfork_extra.h berisi fungsi utilitas.

Beberapa fungsi mengambil serialisasi buffering protokol. Untuk informasi selengkapnya cara menggunakan buffering protokol dalam game, lihat Tentang buffering protokol.

Parameter fungsi dan nilai hasil dijelaskan dalam header dan dokumentasi API referensi.

Fungsi siklus proses

Gunakan fungsi berikut untuk mengontrol siklus proses instance Tuning Fork.

Lakukan inisialiasi

TFErrorCode TuningFork_init(const TFSettings* settings, JNIEnv* env, jobject context);

Anda harus memanggil fungsi ini satu kali saat memulai, biasanya dari dalam kode native yang dijalankan oleh metode onCreate() aplikasi. Langkah ini mengalokasikan data yang dibutuhkan oleh library Tuning Fork.

Anda harus memiliki file tuningfork_settings.bin di assets/tuningfork dalam aplikasi Anda, yang berisi setelan histogram dan anotasi. Untuk mengonversi file teks ke biner, lihat Teks dengan representasi biner.

Kolom yang Anda isi di settings menentukan cara library menginisialisasi sendiri.

/**
 * @brief Initialization settings
 *   Zero any values that are not being used.
 */
struct TFSettings {
  /**
   * Cache object to be used for upload data persistence.
   * If unset, data is persisted to /data/local/tmp/tuningfork
   */
  const TFCache* persistent_cache;
  /**
   * The address of the Swappy_injectTracers function.
   * If this is unset, you need to call TuningFork_tick explicitly.
   * If it is set, telemetry for 4 instrument keys is automatically recorded.
   */
  SwappyTracerFn swappy_tracer_fn;
  /**
   * Callback
   * If set, this is called with the fidelity parameters that are downloaded.
   * If unset, you need to call TuningFork_getFidelityParameters explicitly.
   */
  ProtoCallback fidelity_params_callback;
  /**
   * A serialized protobuf containing the fidelity parameters to be uploaded
   *  for training.
   * Set this to nullptr if you are not using training mode. Note that these
   *  are used instead of the default parameters loaded from the APK, if they
   *  are present and there are neither a successful download nor saved parameters.
   */
  const CProtobufSerialization* training_fidelity_params;
};

Jika Anda meneruskan fungsi Swappy_injectTracer() (OpenGL, Vulkan) dari Frame Pacing API saat inisialisasi, library Tuning Fork secara otomatis merekam waktu frame tanpa Anda memanggil titik skala berfungsi sendiri secara eksplisit. Hal ini dilakukan di aplikasi demo:

void InitTf(JNIEnv* env, jobject activity) {
   SwappyGL_init(env, activity);
   swappy_enabled = SwappyGL_isEnabled();
   TFSettings settings {};
   if (swappy_enabled) {
       settings.swappy_tracer_fn = &SwappyGL_injectTracer;
   }
...
}

Memusnahkan

TFErrorCode TuningFork_destroy();

Anda dapat memanggil fungsi ini saat dimatikan. Fungsi ini mencoba mengirimkan semua data histogram yang disimpan saat ini untuk diupload kemudian, sebelum membatalkan semua memori yang digunakan oleh library Tuning Fork.

Flush

TFErrorCode TuningFork_flush();

Fungsi ini membersihkan histogram yang direkam (misalnya, saat game dikirim ke latar belakang atau latar depan). Fitur ini tidak akan menghapus data jika periode upload minimum, yang memiliki durasi default satu menit, tidak berlalu sejak upload sebelumnya.

Menyetel parameter fidelitas

TFErrorCode TuningFork_setFidelityParameters(const CProtobufSerialization* params);

Fungsi ini mengganti parameter fidelitas saat ini yang terkait dengan data frame. Anda harus memanggil fungsi ini saat pemain mengubah setelan kualitas game secara manual.

Anotasi

TFErrorCode TuningFork_setCurrentAnnotation(const CProtobufSerialization* annotation);

Fungsi ini menyetel anotasi untuk dikaitkan dengan titik skala berikutnya. Menampilkan TFERROR_INVALID_ANNOTATION jika terjadi error saat mendekode anotasi dan TFERROR_OK jika tidak ada error.

Fungsi per frame

TFErrorCode TuningFork_frameTick(TFInstrumentKey key);

Fungsi ini merekam waktu antara titik skala sebelumnya dengan key yang diberikan dan waktu saat ini dalam histogram yang terkait dengan key dan anotasi saat ini.

TFErrorCode TuningFork_frameDeltaTimeNanos(TFInstrumentKey key, TFDuration dt);

Fungsi ini merekam durasi dalam histogram yang terkait dengan key dan anotasi saat ini.

TFErrorCode TuningFork_startTrace(TFInstrumentKey key, TraceHandle* handle);

Fungsi ini menyetel handle ke handle trace yang terkait dengan key yang diberikan.

TFErrorCode TuningFork_endTrace(TraceHandle handle);

Fungsi ini merekam interval waktu sejak panggilan TuningFork_startTrace() terkait dalam histogram yang terkait dengan key yang digunakan dan anotasi saat ini.

Fungsi lanjutan

Fungsi berikut tersedia di tuningfork_extra.h.

Menemukan dan memuat file dalam APK

TFErrorCode TuningFork_findFidelityParamsInApk(JNIEnv* env, jobject context, const char* filename, CProtobufSerialization* fidelityParams);

Fungsi ini memuat fidelityParams dari direktori assets/tuningfork di APK dengan nama file yang diberikan. fidelityParams harus berupa serialisasi pesan FidelityParams. Untuk informasi selengkapnya, lihat Menentukan tingkat kualitas.

Kepemilikan serialisasi diteruskan ke pemanggil, yang harus memanggil CProtobufSerialization_Free untuk membatalkan semua memori yang ditahan.

Mendownload parameter fidelitas pada thread terpisah

void TuningFork_startFidelityParamDownloadThread(const CProtobufSerialization* defaultParams, ProtoCallback fidelity_params_callback);

Mengaktifkan thread download untuk mengambil parameter fidelitas. Thread akan mengulangi permintaan hingga terjadi download parameter atau waktu tunggu. Parameter yang didownload disimpan secara lokal. Saat dimulai ulang, aplikasi akan menggunakan parameter yang didownload ini, bukan parameter default.

Menyimpan dan menghapus parameter fidelitas yang disimpan di perangkat

TFErrorCode TuningFork_saveOrDeleteFidelityParamsFile(JNIEnv* env, jobject context, const CProtobufSerialization* fidelity_params);

Fungsi ini hanya diperlukan dalam mode ahli dengan parameter fidelitas yang didownload dari server. Ini akan menyimpan atau menghapus (jika fidelity_params adalah null) file yang disimpan secara lokal yang digunakan saat server tidak dapat dijangkau.

Permintaan web

Library membuat jenis permintaan berikut ke endpoint server:

  • Permintaan generateTuningParameters dibuat saat inisialisasi.
  • Selama alur game, permintaan uploadTelemetry secara berkala dibuat untuk mengirim data ke server.
  • APK Debug juga dapat mengirim permintaan debugInfo, yang menginformasikan server debug tentang setelan, parameter fidelitas default, dan struktur dev_tuningfork.proto.

Pemain offline

Jika tidak ada koneksi yang tersedia saat inisialisasi, permintaan akan dicoba lagi beberapa kali dengan waktu back-off yang meningkat.

Jika tidak ada koneksi saat diupload, upload akan di-cache. Anda dapat menyediakan mekanisme caching sendiri dengan meneruskan objek TFCache saat inisialisasi. Jika Anda tidak menyediakan cache sendiri, upload akan disimpan sebagai file dalam penyimpanan sementara.