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 melakukan serialisasi buffering protokol. Untuk informasi selengkapnya cara menggunakan buffering protokol dalam game, lihat Tentang buffering protokol.

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

Fungsi siklus proses Android Performance Tuner

Gunakan fungsi berikut untuk mengontrol siklus proses instance Tuning Fork.

Lakukan inisialisasi

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 dieksekusi 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 Representasi teks versus biner.

Kolom yang Anda isi di settings menentukan cara library melakukan inisialisasi 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;
  /**
   * A null-terminated UTF-8 string containing the endpoint that Tuning Fork
   * will connect to for parameter, upload, and debug requests. This overrides
   * the value in base_uri in the settings proto and is intended for debugging
   * purposes only.
   */
  const char* endpoint_uri_override;
  /**
   * The version of Swappy that swappy_tracer_fn comes from.
   */
  uint32_t swappy_version;
  /**
   * The number of each metric that is allowed to be allocated at any given
   * time. If any element is zero, the default for that metric type is used.
   * Memory for all metrics is allocated up-front at initialization. When all
   * metrics of a given type are allocated, further requested metrics are not
   * added and data is lost.
   */
  TuningFork_MetricLimits max_num_metrics;
};

Jika Anda meneruskan fungsi Swappy_injectTracer() (OpenGL, Vulkan) dari Frame Pacing API saat inisialisasi, library Tuning Fork akan otomatis merekam waktu render frame tanpa Anda memanggil fungsi tick 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;
       settings.swappy_version = Swappy_version();
   }
...
}

Hancurkan

TFErrorCode TuningFork_destroy();

Anda dapat memanggil fungsi ini saat mematikan. Fungsi ini mencoba mengirimkan semua data histogram yang disimpan saat ini untuk diupload kemudian, sebelum membatalkan alokasi 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 yang dikaitkan. 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 tick berikutnya. Fungsi ini 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 tick sebelumnya dengan key yang ditentukan 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 rekaman aktivitas yang terkait dengan key yang ditentukan.

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 siklus proses aplikasi

typedef enum TuningFork_LifecycleState {
    TUNINGFORK_STATE_UNINITIALIZED = 0,
    TUNINGFORK_STATE_ONCREATE = 1,
    TUNINGFORK_STATE_ONSTART = 2,
    TUNINGFORK_STATE_ONSTOP = 3,
    TUNINGFORK_STATE_ONDESTROY = 4,
} TuningFork_LifecycleState;

TFErrorCode TuningFork_reportLifecycleEvent(TuningForkLifecycleState state);

Panggil fungsi ini dari metode siklus proses yang sesuai dalam Aktivitas utama game Anda, dengan meneruskan enum yang sesuai. Dengan merekam peristiwa siklus proses game, APT dapat lebih memahami kapan game Anda mungkin mengalami error atau kapan pengguna berhenti (misalnya, saat peristiwa pemuatan yang lama).

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 ditentukan. 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 pakar 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 gameplay, 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 upload dilakukan, 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.