Tuning Fork のメインインターフェース

Tuning Fork を使用するためのメインのインターフェース。

概要

列挙型
`InstrumentKeys{ TFTICK_RAW_FRAME_TIME = 64000, TFTICK_PACED_FRAME_TIME = 64001, TFTICK_CPU_TIME = 64002, TFTICK_GPU_TIME = 64003 }`	enum フレーム内の期間を示すインストゥルメントキー。
TFErrorCode{ TFERROR_OK = 0, TFERROR_NO_SETTINGS = 1, TFERROR_NO_SWAPPY = 2, TFERROR_INVALID_DEFAULT_FIDELITY_PARAMS = 3, TFERROR_NO_FIDELITY_PARAMS = 4, TFERROR_TUNINGFORK_NOT_INITIALIZED = 5, TFERROR_INVALID_ANNOTATION = 6, TFERROR_INVALID_INSTRUMENT_KEY = 7, TFERROR_INVALID_TRACE_HANDLE = 8, TFERROR_TIMEOUT = 9, TFERROR_BAD_PARAMETER = 10, TFERROR_B64_ENCODE_FAILED = 11, TFERROR_JNI_BAD_VERSION = 12, TFERROR_JNI_BAD_THREAD = 13, TFERROR_JNI_BAD_ENV = 14, TFERROR_JNI_EXCEPTION = 15, TFERROR_JNI_BAD_JVM = 16, TFERROR_NO_CLEARCUT = 17, TFERROR_NO_FIDELITY_PARAMS_IN_APK = 18, TFERROR_COULDNT_SAVE_OR_DELETE_FPS = 19, TFERROR_PREVIOUS_UPLOAD_PENDING = 20, TFERROR_UPLOAD_TOO_FREQUENT = 21, TFERROR_NO_SUCH_KEY = 22, TFERROR_BAD_FILE_OPERATION = 23, TFERROR_BAD_SETTINGS = 24, TFERROR_ALREADY_INITIALIZED = 25, TFERROR_NO_SETTINGS_ANNOTATION_ENUM_SIZES = 26, TFERROR_DOWNLOAD_THREAD_ALREADY_STARTED = 27, TFERROR_PLATFORM_NOT_SUPPORTED = 28, TFERROR_GENERATE_TUNING_PARAMETERS_ERROR = 29, TFERROR_GENERATE_TUNING_PARAMETERS_RESPONSE_NOT_SUCCESS = 30 }	enum Tuning Fork 関数によって返される可能性があるすべてのエラーコード。

列挙型

InstrumentKeys{
  TFTICK_RAW_FRAME_TIME =     64000,
  TFTICK_PACED_FRAME_TIME =   64001,
  TFTICK_CPU_TIME =           64002,
  TFTICK_GPU_TIME =           64003
}

enum

フレーム内の期間を示すインストゥルメントキー。

TFErrorCode{
  TFERROR_OK = 0,
  TFERROR_NO_SETTINGS =
      1,
  TFERROR_NO_SWAPPY = 2,
  TFERROR_INVALID_DEFAULT_FIDELITY_PARAMS =
      3,
  TFERROR_NO_FIDELITY_PARAMS =
      4,
  TFERROR_TUNINGFORK_NOT_INITIALIZED =
      5,
  TFERROR_INVALID_ANNOTATION =
      6,
  TFERROR_INVALID_INSTRUMENT_KEY =
      7,
  TFERROR_INVALID_TRACE_HANDLE =
      8,
  TFERROR_TIMEOUT = 9,
  TFERROR_BAD_PARAMETER = 10,
  TFERROR_B64_ENCODE_FAILED = 11,
  TFERROR_JNI_BAD_VERSION = 12,
  TFERROR_JNI_BAD_THREAD = 13,
  TFERROR_JNI_BAD_ENV = 14,
  TFERROR_JNI_EXCEPTION =
      15,
  TFERROR_JNI_BAD_JVM = 16,
  TFERROR_NO_CLEARCUT = 17,
  TFERROR_NO_FIDELITY_PARAMS_IN_APK =
      18,
  TFERROR_COULDNT_SAVE_OR_DELETE_FPS =
      19,
  TFERROR_PREVIOUS_UPLOAD_PENDING =
      20,
  TFERROR_UPLOAD_TOO_FREQUENT =
      21,
  TFERROR_NO_SUCH_KEY = 22,
  TFERROR_BAD_FILE_OPERATION = 23,
  TFERROR_BAD_SETTINGS = 24,
  TFERROR_ALREADY_INITIALIZED =
      25,
  TFERROR_NO_SETTINGS_ANNOTATION_ENUM_SIZES =
      26,
  TFERROR_DOWNLOAD_THREAD_ALREADY_STARTED =
      27,
  TFERROR_PLATFORM_NOT_SUPPORTED =
      28,
  TFERROR_GENERATE_TUNING_PARAMETERS_ERROR =
      29,
  TFERROR_GENERATE_TUNING_PARAMETERS_RESPONSE_NOT_SUCCESS =
      30
}

enum

Tuning Fork 関数によって返される可能性があるすべてのエラーコード。

Typedef
`ProtoCallback)(const CProtobufSerialization *)`	typedef `void(*` TFSettings::fidelity_params_callback に付加できる関数へのポインタ。
`SwappyTracerFn)(const SwappyTracer *)`	typedef `void(*` TFSettings::swappy_tracer_fn に付加できる Swappy_injectTracers へのポインタ。
`TFDuration`	typedef `uint64_t` 期間（ナノ秒単位）。
`TFInstrumentKey`	typedef `uint16_t` インストルメンテーションキーは、フレーム内またはトレースセグメント内のティックポイントを識別するものです。
`TFTimePoint`	typedef `uint64_t` エポックからの経過時間（ミリ秒単位）。
`TFTraceHandle`	typedef `uint64_t` TuningFork_startTrace で使用するトレースハンドル。
`UploadCallback)(const char *, size_t n)`	typedef `void(*` TuningFork_setUploadCallback に渡すことができる関数へのポインタ。

関数
`CProtobufSerialization_Free(CProtobufSerialization *ser)`	`void` シリアル化されたプロトコルバッファが所有するメモリを破棄します。
`TuningFork_destroy()`	`TFErrorCode` Tuning Fork が所有するメモリをクリーンアップし、すべてのスレッドを強制終了します。
`TuningFork_enableMemoryRecording(bool enable)`	`TFErrorCode` メモリテレメトリーの記録を有効または無効にします。
`TuningFork_endTrace(TFTraceHandle handle)`	`TFErrorCode` トレースセグメントを停止し、それを記録します。
`TuningFork_flush()`	`TFErrorCode` 現在のヒストグラムを強制的にアップロードします。
`TuningFork_frameDeltaTimeNanos(TFInstrumentKey key, TFDuration dt)`	`TFErrorCode` フレームティックをシステム時刻ではなく、外部時刻を使用して記録します。
`TuningFork_frameTick(TFInstrumentKey key)`	`TFErrorCode` インストルメンテーションキーと現在のアノテーションに関連付けられるフレームティックを記録します。
`TuningFork_getFidelityParameters(const CProtobufSerialization defaultParams, CProtobufSerialization params, uint32_t timeout_ms)`	`TFErrorCode` サーバーから忠実度パラメータを取得するブロッキング呼び出し。
`TuningFork_init(const TFSettings settings, JNIEnv env, jobject context)`	`TFErrorCode` Tuning Fork を初期化します。
`TuningFork_setCurrentAnnotation(const CProtobufSerialization *annotation)`	`TFErrorCode` 現在のアノテーションを設定します。
`TuningFork_setFidelityParameters(const CProtobufSerialization *params)`	`TFErrorCode` 現在アクティブな忠実度パラメータを設定します。
`TuningFork_setUploadCallback(UploadCallback cbk)`	`TFErrorCode` コールバックを設定して、TuningFork がアップロードするたびに別のスレッドで呼び出されるようにします。
`TuningFork_startTrace(TFInstrumentKey key, TFTraceHandle *handle)`	`TFErrorCode` トレースセグメントを開始します。

構造体
CProtobufSerialization	シリアル化されたプロトコルバッファを表すバイト列。
TFSettings	初期化設定。使用しない値は 0 にしてください。

列挙型

InstrumentKeys

 InstrumentKeys

フレーム内の期間を示すインストゥルメントキー。

キー 64000～65535 は予約済みです

プロパティ
`TFTICK_CPU_TIME`	フレームの開始から Swappy_swap の呼び出しまでの時間。
`TFTICK_GPU_TIME`	バッファのスワップから GPU フェンスのトリガーまでの時間。
`TFTICK_PACED_FRAME_TIME`	eglSwapBuffers 呼び出しの終わりから次の終わりまでの、または Vulkan キューが提示するフレーム時間。
`TFTICK_RAW_FRAME_TIME`	GPU 時間がある場合は、MAX(CPU_TIME,GPU_TIME)、それ以外の場合は、PACED_FRAME_TIME と同じです。

TFErrorCode

 TFErrorCode

Tuning Fork 関数によって返される可能性があるすべてのエラーコード。

プロパティ
`TFERROR_ALREADY_INITIALIZED`	TuningFork_init が複数回呼び出されました。
`TFERROR_B64_ENCODE_FAILED`	protobuf をエンコードできませんでした。
`TFERROR_BAD_FILE_OPERATION`	一般的なファイルエラー。
`TFERROR_BAD_PARAMETER`	一般的な不正パラメータ。
`TFERROR_BAD_SETTINGS`	tuningfork_settings.bin ファイルが無効です。
`TFERROR_COULDNT_SAVE_OR_DELETE_FPS`	`TuningFork_saveOrDeleteFidelityParamsFile` の呼び出し中にエラーが発生しました。
`TFERROR_DOWNLOAD_THREAD_ALREADY_STARTED`	`TuningFork_startFidelityParamDownloadThread` が複数回呼び出されたか、呼び出されたときに TuningFork_init がすでにダウンロードを開始していました。
`TFERROR_GENERATE_TUNING_PARAMETERS_ERROR`	generateTuningParameters に対するレスポンスの解析中にエラーが発生しました。
`TFERROR_GENERATE_TUNING_PARAMETERS_RESPONSE_NOT_SUCCESS`	generateTuningParameters からのレスポンスが成功コードではありませんでした。
`TFERROR_INVALID_ANNOTATION`	`TuningFork_setCurrentAnnotation` に渡されたパラメータが無効です。
`TFERROR_INVALID_DEFAULT_FIDELITY_PARAMS`	`fpDefaultFileNum` が範囲外です。
`TFERROR_INVALID_INSTRUMENT_KEY`	ティック関数に渡されたインストゥルメントキーが無効です。
`TFERROR_INVALID_TRACE_HANDLE`	`TuningFork_endTrace` に渡されたハンドルが無効です。
`TFERROR_JNI_BAD_ENV`	JNI エラー - 廃止
`TFERROR_JNI_BAD_JVM`	JNI エラー - 廃止
`TFERROR_JNI_BAD_THREAD`	JNI エラー - 廃止
`TFERROR_JNI_BAD_VERSION`	JNI エラー - 廃止
`TFERROR_JNI_EXCEPTION`	JNI エラー - 例外がスローされました。logcat の出力を参照してください。
`TFERROR_NO_CLEARCUT`	廃止
`TFERROR_NO_FIDELITY_PARAMS`	初期化時に忠実度パラメータが見つかりませんでした。
`TFERROR_NO_FIDELITY_PARAMS_IN_APK`	assets/tuningfork に dev_tuningfork_fidelityparams_#.bin が見つかりませんでした。
`TFERROR_NO_SETTINGS`	assets/tuningfork に tuningfork_settings.bin が見つかりませんでした。
`TFERROR_NO_SETTINGS_ANNOTATION_ENUM_SIZES`	tuningfork_settings.bin の一部が欠けています。
`TFERROR_NO_SUCH_KEY`	ファイルキャッシュにアクセスする際のキーがありませんでした。
`TFERROR_NO_SWAPPY`	必要な Swappy 関数が見つかりませんでした。
`TFERROR_OK`	エラーはありません。
`TFERROR_PLATFORM_NOT_SUPPORTED`	Tuning Fork をサポートしていないプラットフォームでゲームまたはアプリが実行されています。 Unity プラグインでのみ使用されます。
`TFERROR_PREVIOUS_UPLOAD_PENDING`	別のリクエストが保留中のため、アップロードできません。
`TFERROR_TIMEOUT`	忠実度パラメータのリクエストでタイムアウトが発生しました。
`TFERROR_TUNINGFORK_NOT_INITIALIZED`	Tuning Fork が初期化される前に呼び出しが行われました。
`TFERROR_UPLOAD_TOO_FREQUENT`	`TuningFork_flush` への呼び出しの頻度が高すぎます。

Typedef

ProtoCallback

void(* ProtoCallback)(const CProtobufSerialization *)

TFSettings::fidelity_params_callback に付加できる関数へのポインタ。

ダウンロードされた忠実度パラメータとともに呼び出される関数。関連情報: TFSettings

SwappyTracerFn

void(* SwappyTracerFn)(const SwappyTracer *)

TFSettings::swappy_tracer_fn に付加できる Swappy_injectTracers へのポインタ。

関連情報: TFSettings

TFDuration

uint64_t TFDuration

期間（ナノ秒単位）。

TFInstrumentKey

uint16_t TFInstrumentKey

インストルメンテーションキーは、フレーム内またはトレースセグメント内のティックポイントを識別するものです。

TFTimePoint

uint64_t TFTimePoint

エポックからの経過時間（ミリ秒単位）。

TFTraceHandle

uint64_t TFTraceHandle

TuningFork_startTrace で使用するトレースハンドル。

UploadCallback

void(* UploadCallback)(const char *, size_t n)

TuningFork_setUploadCallback に渡すことができる関数へのポインタ。

TuningFork がアップロードするたびに別のスレッドで呼び出される関数。関連情報: TFSettings

関数

CProtobufSerialization_Free

void CProtobufSerialization_Free(
  CProtobufSerialization *ser
)

シリアル化されたプロトコルバッファが所有するメモリを破棄します。

詳細

パラメータ

ser

シリアル化されたプロトコルバッファ

TuningFork_destroy

TFErrorCode TuningFork_destroy()

Tuning Fork が所有するメモリをクリーンアップし、すべてのスレッドを強制終了します。

詳細
戻り値	Tuning Fork が初期化されていなかった場合を除いて、TFERROR_OK。

TuningFork_enableMemoryRecording

TFErrorCode TuningFork_enableMemoryRecording(
  bool enable
)

メモリテレメトリーの記録を有効または無効にします。

デフォルトでは、初期化時にメモリテレメトリーの記録は有効になります。

詳細

パラメータ

enable

true の場合はメモリの記録が有効になり、false の場合は無効になります。

戻り値

Tuning Fork が初期化されていなかった場合を除いて、TFERROR_OK。

TuningFork_endTrace

TFErrorCode TuningFork_endTrace(
  TFTraceHandle handle
)

トレースセグメントを停止し、それを記録します。

詳細

パラメータ

handle

TuningFork_startTrace が返したハンドルです。

戻り値

TFERROR_INVALID_TRACE_HANDLE（ハンドルが無効な場合）。TFERROR_OK（成功した場合）。

TuningFork_flush

TFErrorCode TuningFork_flush()

現在のヒストグラムを強制的にアップロードします。

詳細
戻り値	TFERROR_OK（アップロードを開始できた場合）。TFERROR_PREVIOUS_UPLOAD_PENDING（前回のアップロードにブロックされている場合）。TFERROR_UPLOAD_TOO_FREQUENT（前回のアップロードから 1 分未満の場合）。

TuningFork_frameDeltaTimeNanos

TFErrorCode TuningFork_frameDeltaTimeNanos(
  TFInstrumentKey key,
  TFDuration dt
)

フレームティックをシステム時刻ではなく、外部時刻を使用して記録します。

関連情報: 上記の予約済みインストゥルメントキー

詳細

パラメータ

key

インストゥルメントキー

パラメータ

`dt`	記録する期間（ナノ秒単位）

戻り値

TFERROR_INVALID_INSTRUMENT_KEY（インストゥルメントキーが無効な場合）。TFERROR_OK（成功した場合）。

TuningFork_frameTick

TFErrorCode TuningFork_frameTick(
  TFInstrumentKey key
)

インストルメンテーションキーと現在のアノテーションに関連付けられるフレームティックを記録します。

注: 異なるスレッドからティック関数またはトレース関数を呼び出すことはできますが、常に同じスレッドから 1 つのインストゥルメントキーをティックする必要があります。関連情報: 上記の予約済みインストゥルメントキー

詳細

パラメータ

key

インストゥルメントキー

戻り値

TFERROR_INVALID_INSTRUMENT_KEY（インストゥルメントキーが無効な場合）。TFERROR_OK（成功した場合）。

TuningFork_getFidelityParameters

TFErrorCode TuningFork_getFidelityParameters(
  const CProtobufSerialization *defaultParams,
  CProtobufSerialization *params,
  uint32_t timeout_ms
)

サーバーから忠実度パラメータを取得するブロッキング呼び出し。

TuningFork_init への設定の中で fidelity_params_callback を渡していた場合、これを呼び出す必要はありません。忠実度パラメータをダウンロードすると、タイミング情報はそれらのパラメータと関連付けられているものとして記録されます。その後で GetFidelityParameters を呼び出し、新しいパラメータセットがダウンロードされると、すでに収集されているデータがすべてバックエンドに送信されます。「params」の所有権は呼び出し元に渡されるため、呼び出し元は使用が終わったら params->dealloc を呼び出す必要があります。パラメータリクエストは次の URL に送信されます: ${url_base}+'applications/'+package_name+'/apks/'+version_number+':generateTuningParameters'

詳細

パラメータ

`defaultParams`	どのパラメータもダウンロードできなかった場合、これが最新だとみなされます。
`params`
`timeout_ms`	接続できない場合に、この呼び出しから戻るまでの待機時間。ゼロまたは負の場合は、Settings.initial_request_timeout_ms の値が使用されます。

戻り値

TFERROR_TIMEOUT（パラメータをダウンロードする前にタイムアウトした場合）。TFERROR_OK（成功した場合）。

TuningFork_init

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

Tuning Fork を初期化します。

この関数は、他の関数よりも前に呼び出す必要があります。

ライブラリは、tuningfork_settings.bin ファイルからヒストグラムとアノテーションの設定を読み込みます。関連情報: TFSettings で、他の設定で初期化動作がどのように変わるかのセマンティクスを説明しています。

詳細

パラメータ

`settings`	TFSettings 構造体
`env`	JNIEnv
`context`	アプリコンテキスト

戻り値

TFERROR_OK（成功した場合）、TFERROR_NO_SETTINGS（設定が見つからなかった場合）、TFERROR_BAD_SETTINGS（tuningfork_settings.bin ファイルが無効な場合）、TFERROR_ALREADY_INITIALIZED（tuningfork がすでに初期化されていた場合）。

TuningFork_setCurrentAnnotation

TFErrorCode TuningFork_setCurrentAnnotation(
  const CProtobufSerialization *annotation
)

現在のアノテーションを設定します。

詳細

パラメータ

annotation

現在のアノテーションを protobuf にシリアル化したもの。

戻り値

TFERROR_INVALID_ANNOTATION（アノテーションが設定と一致していない場合）。

戻り値

TFERROR_OK（成功した場合）。

TuningFork_setFidelityParameters

TFErrorCode TuningFork_setFidelityParameters(
  const CProtobufSerialization *params
)

現在アクティブな忠実度パラメータを設定します。

テストモードでは、ダウンロードされたパラメータをこの関数がオーバーライドします。たとえば、プレーヤーが手動でゲームの品質設定を変更した場合に使用します。これにより、以前のパラメータに関連付けられたデータがフラッシュ（つまりアップロード）されます。

詳細

パラメータ

params

プロトコルバッファにエンコードされたパラメータ。

戻り値

TFERROR_OK（パラメータを設定できた場合）。

TuningFork_setUploadCallback

TFErrorCode TuningFork_setUploadCallback(
  UploadCallback cbk
)

コールバックを設定して、TuningFork がアップロードするたびに別のスレッドで呼び出されるようにします。

詳細

パラメータ

cbk

戻り値

Tuning Fork が初期化されていなかった場合を除いて、TFERROR_OK。

TuningFork_startTrace

TFErrorCode TuningFork_startTrace(
  TFInstrumentKey key,
  TFTraceHandle *handle
)

トレースセグメントを開始します。

関連情報: 上記の予約済みインストゥルメントキー

詳細

パラメータ

key

インストゥルメントキー

パラメータ

handle

成功した場合に新しいハンドルが書き込まれます。

戻り値

TFERROR_INVALID_INSTRUMENT_KEY（インストゥルメントキーが無効な場合）。TFERROR_OK（成功した場合）。

Tuning Fork のメイン インターフェース

概要

列挙型

Typedef

関数

構造体

列挙型

InstrumentKeys

TFErrorCode

Typedef

ProtoCallback

SwappyTracerFn

TFDuration

TFInstrumentKey

TFTimePoint

TFTraceHandle

UploadCallback

関数

CProtobufSerialization_Free

TuningFork_destroy

TuningFork_enableMemoryRecording

TuningFork_endTrace

TuningFork_flush

TuningFork_frameDeltaTimeNanos

TuningFork_frameTick

TuningFork_getFidelityParameters

TuningFork_init

TuningFork_setCurrentAnnotation

TuningFork_setFidelityParameters

TuningFork_setUploadCallback

TuningFork_startTrace

Tuning Fork のメインインターフェース