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 函数可能返回的所有错误代码。

类型定义符

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()
清理 Tuning Fork 拥有的所有内存并终止所有线程。
TuningFork_enableMemoryRecording(bool enable)
启用或停用内存遥测记录。
TuningFork_endTrace(TFTraceHandle handle)
停止并记录跟踪记录片段。
TuningFork_flush()
强制上传当前直方图。
TuningFork_frameDeltaTimeNanos(TFInstrumentKey key, TFDuration dt)
使用外部时间(而不是系统时间)记录 tick。
TuningFork_frameTick(TFInstrumentKey key)
记录将与插桩键和当前注释相关联的帧 tick。
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

初始化设置会将未使用的所有值设为零。

枚举

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(如果成功)。