添加帧时间函数

使用本主题中的函数，将 Tuning Fork 库集成到您的游戏代码中。

include/tuningfork/tuningfork.h 的头文件包含 Tuning Fork 库的核心接口。include/tuningfork/tuningfork_extra.h 中的文件包含实用函数。

有几个函数可处理协议缓冲区的序列化。如需详细了解如何在游戏中使用协议缓冲区，请参阅协议缓冲区简介。

如需了解函数参数和返回值，请参阅头文件和参考 API 文档。

Android Performance Tuner 生命周期函数

使用以下函数控制 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;
  /**
   * A null-terminated UTF-8 string containing the endpoint that Tuning Fork
   * will connect to for parameter, upload, and debug requests. This overrides
   * the value in base_uri in the settings proto and is intended for debugging
   * purposes only.
   */
  const char* endpoint_uri_override;
  /**
   * The version of Swappy that swappy_tracer_fn comes from.
   */
  uint32_t swappy_version;
  /**
   * The number of each metric that is allowed to be allocated at any given
   * time. If any element is zero, the default for that metric type is used.
   * Memory for all metrics is allocated up-front at initialization. When all
   * metrics of a given type are allocated, further requested metrics are not
   * added and data is lost.
   */
  TuningFork_MetricLimits max_num_metrics;
};

如果您在初始化时从 Frame Pacing API 传入 Swappy_injectTracer() 函数（OpenGL、Vulkan），Tuning Fork 库会自动记录帧时间，而无需您显式调用 tick 函数。此操作在演示版应用中完成：

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;
       settings.swappy_version = Swappy_version();
   }
...
}

注意： 请务必设置您所使用的 Swappy 版本 在 TFSettings 的 swappy_version 字段中。这样可确保 TuningFork 解读从 Swappy 回调返回的数据。

销毁

TFErrorCode TuningFork_destroy();

您可以在关闭时调用此函数。此函数会尝试提交当前存储的所有直方图数据以供稍后上传，然后再取消分配 Tuning Fork 库使用的任何内存。

清空

TFErrorCode TuningFork_flush();

此函数会清空记录的直方图（例如，游戏被发送到后台或前台时）。如果距离上次上传的时间未达到最短上传期限（默认为一分钟），那么它不会清空数据。

设置保真度参数

TFErrorCode TuningFork_setFidelityParameters(const CProtobufSerialization* params);

此函数会覆盖与帧数据相关联的当前保真度参数。当玩家手动更改游戏的质量设置时，您应调用此方法。

注释

TFErrorCode TuningFork_setCurrentAnnotation(const CProtobufSerialization* annotation);

此函数设置需与后续 tick 相关联的注释。如果对注释进行解码时出现错误，返回 TFERROR_INVALID_ANNOTATION，如果未出现错误，返回 TFERROR_OK。

每帧函数

TFErrorCode TuningFork_frameTick(TFInstrumentKey key);

此函数将记录具有给定 key 的前一个 tick 和与 key 和当前注释关联的直方图中的当前时间之间的间隔时间。

TFErrorCode TuningFork_frameDeltaTimeNanos(TFInstrumentKey key, TFDuration dt);

此函数将在与 key 和当前注解关联的直方图中记录时长。

TFErrorCode TuningFork_startTrace(TFInstrumentKey key, TraceHandle* handle);

此函数将句柄设置为与给定 key 关联的跟踪句柄。

TFErrorCode TuningFork_endTrace(TraceHandle handle);

此函数将记录与所使用的 key 相关联的直方图中相关 TuningFork_startTrace() 调用与当前注释之间的时间间隔。

应用生命周期函数

typedef enum TuningFork_LifecycleState {
    TUNINGFORK_STATE_UNINITIALIZED = 0,
    TUNINGFORK_STATE_ONCREATE = 1,
    TUNINGFORK_STATE_ONSTART = 2,
    TUNINGFORK_STATE_ONSTOP = 3,
    TUNINGFORK_STATE_ONDESTROY = 4,
} TuningFork_LifecycleState;

TFErrorCode TuningFork_reportLifecycleEvent(TuningForkLifecycleState state);

在游戏的主 activity 中从适当的生命周期方法调用此函数，并传递适当的枚举。通过记录游戏的生命周期事件，APT 能够更好地了解您的游戏何时发生崩溃或用户何时退出（例如，在较长的加载事件期间）。

高级函数

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 请求以将数据发送到服务器。
• 调试 APK 还可以发送 debugInfo 请求，用于告知调试服务器关于设置、默认保真度参数和 dev_tuningfork.proto 结构的信息。

离线玩家

如果在初始化时没有可用的连接，请求会重试多次，而且退避时间会有所增加。

如果上传时没有连接，上传会被缓存。您可以通过在初始化时传递 TFCache 对象提供自己的缓存机制。如果您未提供自己的缓存，上传的内容会作为文件存储在临时存储空间中。