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 関数によって返される可能性があるすべてのエラーコード。

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

構造体

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(成功した場合)。