使用本主题中的函数将 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;
};
如果您在初始化时传入帧同步 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();
}
...
}
销毁
TFErrorCode TuningFork_destroy();
您可以在关机时调用此函数。此函数会尝试提交所有当前存储的直方图数据,以便稍后上传,然后再解除分配 Tuning Fork 库使用的所有内存。
刷新
TFErrorCode TuningFork_flush();
此函数会刷新已记录的直方图(例如,当游戏进入后台或前台时)。如果自上次上传以来未达到最短上传周期(默认值为一分钟),则不会刷新数据。
设置保真参数
TFErrorCode TuningFork_setFidelityParameters(const CProtobufSerialization* params);
此函数会覆盖与帧数据关联的当前保真参数。当玩家手动更改游戏质量设置时,您应该调用此函数。
注解
TFErrorCode TuningFork_setCurrentAnnotation(const CProtobufSerialization* annotation);
此函数设置要与后续滴答关联的注解。如果解码注解时出错,则返回 TFERROR_INVALID_ANNOTATION
;如果没有错误,则返回 TFERROR_OK
。
每帧函数
TFErrorCode TuningFork_frameTick(TFInstrumentKey key);
此函数将给定 key
的上一个滴答与当前时间之间的时间记录在与 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 中查找并加载文件
此函数从 APK 的 assets/tuningfork
目录中加载具有给定文件名的 fidelityParams
。fidelityParams
必须是 FidelityParams
消息的序列化。如需了解详情,请参阅定义质量等级。
序列化的所有权已传递给调用者,调用者必须调用 CProtobufSerialization_Free
来解除分配所有已占用的内存。
在单独的线程中下载保真参数
激活下载线程以检索保真参数。该线程会重试请求,直到参数下载完成或发生超时。下载的参数会存储在本地。应用重新启动时,它会使用这些下载的参数而不是默认参数。
保存和删除设备上存储的保真参数
仅当在专家模式下从服务器下载保真参数时才需要此函数。它会覆盖或删除(如果 fidelity_params
为 null)在服务器无法访问时使用的本地存储文件。
Web 请求
该库向服务器端点发出以下类型的请求
- 在初始化时会发出一个
generateTuningParameters
请求。 - 在游戏过程中,会定期发出
uploadTelemetry
请求,将数据发送到服务器。 - 调试 APK 还可以发送
debugInfo
请求,这会告知调试服务器设置、默认保真参数和dev_tuningfork.proto
结构。
离线玩家
如果初始化时没有可用连接,请求会重试几次,退避时间会逐渐增加。
如果上传时没有连接,则上传会被缓存。您可以通过在初始化时传递 TFCache
对象来提供自己的缓存机制。如果您不提供自己的缓存,上传将作为文件存储在临时存储中。