添加帧时序功能

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

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

一些函数采用协议缓冲区的序列化形式。有关在游戏中使用协议缓冲区的更多信息,请参阅关于协议缓冲区

函数参数和返回值在头文件和参考API文档中进行了说明。

Android性能调优器生命周期函数

使用以下函数控制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;
};

如果您在初始化时传入来自帧速率调整API的Swappy_injectTracer()函数(OpenGLVulkan),则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();
   }
...
}

销毁

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);

此函数记录自关联的TuningFork_startTrace()调用以来的时间间隔,并将其记录在与使用的key和当前注释关联的直方图中。

应用程序生命周期函数

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目录加载fidelityParamsfidelityParams必须是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 为空)本地存储的文件,这些文件在服务器无法访问时使用。

网络请求

库对服务器端点执行以下类型的请求

  • 在初始化时会发出 generateTuningParameters 请求。
  • 在游戏过程中,会定期发出 uploadTelemetry 请求以将数据发送到服务器。
  • 调试 APK 还可以发送 debugInfo 请求,这些请求会通知调试服务器设置、默认保真度参数和 dev_tuningfork.proto 结构。

离线玩家

如果在初始化时没有可用的连接,则会使用递增的回退时间重试该请求几次。

如果在上传时没有连接,则会缓存上传。您可以通过在初始化时传递 TFCache 对象来提供您自己的缓存机制。如果您没有提供自己的缓存,则上传将作为文件存储在临时存储中。