Google は、黒人コミュニティに対する人種平等の促進に取り組んでいます。取り組みを見る

フレーム時間関数を追加する

Tuning Fork ライブラリをゲームコードに統合するには、このトピックの関数を使用します。

include/tuningfork/tuningfork.h にあるヘッダー ファイルには、Tuning Fork ライブラリのコア インターフェースが含まれています。include/tuningfork/tuningfork_extra.h にあるファイルには、ユーティリティ関数が含まれています。

一部の関数は、シリアル化されたプロトコル バッファを受け取ります。ゲーム内でのプロトコル バッファの使用について詳しくは、プロトコル バッファについてをご覧ください。

関数のパラメータと戻り値の説明は、ヘッダーとリファレンス API ドキュメントに記載されています。

ライフサイクル関数

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

初期化時に Frame Pacing API の Swappy_injectTracer() 関数(OpenGLVulkan)を渡すと、ティック関数を明示的に呼び出さなくても 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;
   }
...
}

破棄

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 と現在のアノテーションに関連付けられたヒストグラムに記録します。

高度な関数

以下の関数は 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 オブジェクトを渡すことで、独自のキャッシュ メカニズムを提供できます。独自のキャッシュを提供しない場合、アップロードは一時ストレージにファイルとして保存されます。