新增影格時間函式

使用此主題中的函式，將 Tuning Fork 程式庫整合至您的遊戲程式碼。

include/tuningfork/tuningfork.h 的標頭檔案包含 Tuning Fork 程式庫的核心介面。include/tuningfork/tuningfork_extra.h 中的檔案包含公用程式函式。

部分函式會對通訊協定緩衝區序列化。如要進一步瞭解如何在遊戲中使用通訊協定緩衝區，請參閱關於通訊協定緩衝區一節。

標頭和參考資料 API 說明文件中說明了函式參數和傳回值。

Android Performance Tuner 生命週期函式

使用下列函式控管 Tuning Fork 的生命週期 執行個體。

初始化

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

啟動時，您須呼叫此函式一次，通常是在原生程式碼中 是由應用程式的 onCreate() 方法執行。這個操作會分配 Tuning Fork 程式庫所需的資料。

您必須在應用程式的 assets/tuningfork 中加入 tuningfork_settings.bin 檔案，其中包含直方圖和註解設定。如要將文字檔案轉換為二進位檔，請參閱文字與二進位檔表示法。

您在 settings 中填入的欄位決定了程式庫的初始化方式。

/**
 * @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;
};

如果傳入 Swappy_injectTracer() 函式 (OpenGL、 Vulkan) 啟用 Frame Pacing API 系統會自動記錄影格時間，你不必明確呼叫刻點 功能。您可以在試用版應用程式中完成這項操作：

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();
   }
...
}

注意： 請務必設定目前使用的 Swappy 版本 在 TFSettings 的 swappy_version 欄位中。確保 TuningFork 可以 也就是解讀 Swappy 回呼傳回的資料。

刪除

TFErrorCode TuningFork_destroy();

關機時可以呼叫此函式。這個函式會試圖提交目前儲存的所有直方圖資料，以供日後上傳，然後再處理 Tuning Fork 程式庫使用的任何記憶體。

清除

TFErrorCode TuningFork_flush();

這個函式會清除已記錄的直方圖 (例如， 或是傳送到背景或前景)。如果自上次上傳後未過完最短上傳期限 (預設為一分鐘)，則不會清除資料。

設定擬真度參數

TFErrorCode TuningFork_setFidelityParameters(const CProtobufSerialization* params);

這個函式會覆寫目前與影格資料關聯的目前擬真度參數。當玩家手動變更遊戲的品質設定時，您應呼叫此函式。

註解

TFErrorCode TuningFork_setCurrentAnnotation(const CProtobufSerialization* annotation);

這個函式會設定註解，以便與後續的刻點建立關聯。如果將註解解碼時發生錯誤，系統會傳回 TFERROR_INVALID_ANNOTATION；如果沒有任何錯誤，則會傳回 TFERROR_OK。

每頁框函式

TFErrorCode TuningFork_frameTick(TFInstrumentKey key);

這個函式會在與 key 及目前註解關聯的直方圖中，記錄具有指定 key 的上一個刻點與目前時間的間隔。

TFErrorCode TuningFork_frameDeltaTimeNanos(TFInstrumentKey key, TFDuration dt);

這個函式會在與 key 及目前註解關聯的直方圖中，記錄效期。

TFErrorCode TuningFork_startTrace(TFInstrumentKey key, TraceHandle* handle);

這個函式可以設定與指定 key 關聯的追蹤處理常式。

TFErrorCode TuningFork_endTrace(TraceHandle handle);

這個函式會在與所用 key 和目前註解關聯的直方圖中，建立關聯的 TuningFork_startTrace() 呼叫，藉此記錄時間間隔。

應用程式生命週期函式

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

透過遊戲主要活動中適當的生命週期方法呼叫這個函式，傳遞適當的列舉。記錄遊戲的生命週期事件，可讓 APT 更準確地瞭解遊戲何時當機或使用者何時退出 (例如長時間載入事件)。

進階功能

tuningfork_extra.h 提供下列函式。

在 APK 中尋找及載入檔案

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

這個函式會使用指定檔案名稱，從 APK 的 assets/tuningfork 目錄載入 fidelityParams。fidelityParams 必須是 FidelityParams 訊息的序列化。詳情請參閱定義品質等級。

序列化的擁有權會傳遞給呼叫者，而該呼叫者必須呼叫 CProtobufSerialization_Free 來釋放任何已保留的記憶體。

在單獨的執行緒中下載擬真度參數

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

啟用下載執行緒來擷取擬真度參數。執行緒會重試要求，直到參數下載或逾時為止。下載的參數會儲存在本機中。應用程式重新啟動時，將使用這些已下載的參數，而非預設參數。

儲存及刪除儲存在裝置上的擬真度參數

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

只有從伺服器下載擬真度參數的專家模式才需要這個函式。伺服器會在無法存取伺服器時使用的本機檔案上儲存或刪除檔案 (如果 fidelity_params 為空值)。

網路要求

程式庫會向伺服器端點發出以下類型的要求：

• 初始化時會發出 generateTuningParameters 要求。
• 在遊戲過程中，系統會定期傳送 uploadTelemetry 要求，以便將資料傳送至伺服器。
• 偵錯 APK 也可以傳送 debugInfo 要求，其將設定、預設擬真度參數和 dev_tuningfork.proto 結構告知偵錯伺服器。

離線玩家

如果初始化時沒有可用的連線，隨著撤回次數的增加，需要重試要求數次。

如果上傳時沒有任何連線，則系統會快取上傳。您可以在初始化時傳遞 TFCache 物件，以提供自己的快取機制。如未提供自己的快取，系統會將上傳資料以暫存檔案的形式儲存在暫存儲存空間中。