Tuning Fork 主界面

使用 Tuning Fork 的主界面。

摘要

枚举
`InstrumentKeys{ TFTICK_RAW_FRAME_TIME = 64000, TFTICK_PACED_FRAME_TIME = 64001, TFTICK_CPU_TIME = 64002, TFTICK_GPU_TIME = 64003 }`	枚举表示帧中时间段的插桩键。
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 }	枚举 Tuning Fork 函数可能返回的所有错误代码。

枚举

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

枚举

表示帧中时间段的插桩键。

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
}

枚举

Tuning Fork 函数可能返回的所有错误代码。

类型定义符
`ProtoCallback)(const CProtobufSerialization *)`	typedef `void(*` 指向可附加至 TFSettings::fidelity_params_callback 的函数的指针。
`SwappyTracerFn)(const SwappyTracer *)`	typedef `void(*` 指向可附加至 TFSettings::swappy_tracer_fn 的 Swappy_injectTracer 的指针。
`TFDuration`	typedef `uint64_t` 持续时间（以纳秒为单位）。
`TFInstrumentKey`	typedef `uint16_t` 插桩键标识帧或跟踪记录片段中的 tick 点。
`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` 取消分配 Procol 缓冲区序列化所拥有的任何内存。
`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` 使用外部时间（而不是系统时间）记录 tick。
`TuningFork_frameTick(TFInstrumentKey key)`	`TFErrorCode` 记录将与插桩键和当前注释相关联的帧 tick。
`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	初始化设置会将未使用的所有值设为零。

枚举

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`	传递给 tick 函数的插桩键无效。
`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`	初始化 Tune Fork 之前进行了调用。
`TFERROR_UPLOAD_TOO_FREQUENT`	对 `TuningFork_flush` 的调用过于频繁。

类型定义符

ProtoCallback

void(* ProtoCallback)(const CProtobufSerialization *)

指向可附加至 TFSettings::fidelity_params_callback 的函数的指针。

将使用已下载的保真度参数进行调用的函数。另请参阅：TFSettings

SwappyTracerFn

void(* SwappyTracerFn)(const SwappyTracer *)

指向可附加至 TFSettings::swappy_tracer_fn 的 Swappy_injectTracer 的指针。

另请参阅： TFSettings

TFDuration

uint64_t TFDuration

持续时间（以纳秒为单位）。

TFInstrumentKey

uint16_t TFInstrumentKey

插桩键标识帧或跟踪记录片段中的 tick 点。

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
)

取消分配 Procol 缓冲区序列化所拥有的任何内存。

详细信息

参数

ser

协议缓冲区序列化

TuningFork_destroy

TFErrorCode TuningFork_destroy()

清理 Tuning Fork 拥有的所有内存并终止所有线程。

详细信息
返回值	TFERROR_OK，除非未初始化 Tuning Fork。

TuningFork_enableMemoryRecording

TFErrorCode TuningFork_enableMemoryRecording(
  bool enable
)

启用或停用内存遥测记录。

默认情况下，内存遥测记录在初始化时会开启。

详细信息

参数

enable

如果为 true，内存记录启用，如果为 false，则停用。

返回值

TFERROR_OK，除非未初始化 Tuning Fork。

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（如果距离上次上传的时间尚未超过一分钟）。

TuningFork_frameDeltaTimeNanos

TFErrorCode TuningFork_frameDeltaTimeNanos(
  TFInstrumentKey key,
  TFDuration dt
)

使用外部时间（而不是系统时间）记录 tick。

另请参阅：上述预留的插桩键

详细信息

参数

key

插桩键

参数

`dt`	需记录的时长（以纳秒为单位）

返回值

TFERROR_INVALID_INSTRUMENT_KEY（如果插桩键无效）。TFERROR_OK（如果成功）。

TuningFork_frameTick

TFErrorCode TuningFork_frameTick(
  TFInstrumentKey key
)

记录将与插桩键和当前注释相关联的帧 tick。

注释：允许从不同线程调用 tick 或跟踪函数，但始终必须从同一线程对单独的插桩键实施 tick 操作。另请参阅：上述预留的插桩键

详细信息

参数

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_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

返回值

TFERROR_OK，除非未初始化 Tuning Fork。

TuningFork_startTrace

TFErrorCode TuningFork_startTrace(
  TFInstrumentKey key,
  TFTraceHandle *handle
)

启动跟踪记录片段。

另请参阅：上述预留的插桩键

详细信息

参数

key

插桩键

参数

handle

在成功时填充新句柄。

返回值

TFERROR_INVALID_INSTRUMENT_KEY（如果插桩键无效）。TFERROR_OK（如果成功）。

Tuning Fork 主界面

摘要

枚举

类型定义符

函数

结构体

枚举

InstrumentKeys

TFErrorCode

类型定义符

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