このページは Cloud Translation API によって翻訳されました。

フレーム時間関数の追加

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

初期化時に Frame Pacing API の Swappy_injectTracer() 関数（OpenGL、Vulkan）を渡すと、ティック関数を明示的に呼び出さなくても Tuning Fork ライブラリが自動的にフレーム時間を記録してくれます。これはデモアプリでは次のようになっています。

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

破棄

TFErrorCode TuningFork_destroy();

この関数はシャットダウン時に呼び出すことができます。この関数は、Tuning Fork ライブラリが使用しているメモリの割り当てを解除する前に、後でアップロードするために現在保存されているすべてのヒストグラムデータの送信を試みます。

フラッシュ

TFErrorCode TuningFork_flush();

この関数は、記録されたヒストグラムをフラッシュします（たとえば、ゲームがバックグラウンドまたはフォアグラウンドに送られたとき）。前のアップロードから最低限のアップロード期間（デフォルトは 1 分）が経過していない場合、データはフラッシュされません。

忠実度パラメータの設定

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

この関数は、関連付けられた TuningFork_startTrace() の呼び出しからの時間間隔を、使用された key と現在のアノテーションに関連付けられたヒストグラムに記録します。

アプリのライフサイクル関数

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

ゲームのメイン Activity の該当するライフサイクルメソッドからこの関数を呼び出し、該当する列挙型を渡します。ゲームのライフサイクルイベントを記録することで、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 が null の場合）します。

ウェブリクエスト

ライブラリは、次の種類のリクエストをサーバーエンドポイントに送信します。

generateTuningParameters リクエスト: 初期化時に送信されます。
uploadTelemetry リクエスト: ゲームプレイ中、サーバーにデータを送信するために定期的に送信されます。
debugInfo リクエスト: デバッグ APK で、デバッグサーバーに設定、デフォルトの忠実度パラメータ、dev_tuningfork.proto 構造体を知らせるために送信されます。

オフラインプレーヤー

初期化時に使用可能な接続がない場合、バックオフ時間を延ばしながらリクエストを数回再試行します。

アップロード時に接続がない場合、アップロードはキャッシュに保存されます。初期化時に TFCache オブジェクトを渡すことで、独自のキャッシュメカニズムを提供できます。独自のキャッシュを提供しない場合、アップロードは一時ストレージにファイルとして保存されます。

アノテーション、忠実度パラメータ、設定の定義

読み込み時間記録関数の追加