Use the functions in this topic to integrate the Tuning Fork library into your game code.
The header file at include/tuningfork/tuningfork.h
contains the core interface
for the Tuning Fork library. The file at
include/tuningfork/tuningfork_extra.h
contains utility functions.
Several functions take serializations of protocol buffers. For more on using protocol buffers within your game, see About protocol buffers.
Function parameters and return values are explained in the headers and reference API documentation.
Android Performance Tuner lifecycle functions
Use the following functions to control the lifecycle of a Tuning Fork instance.
Initialize
TFErrorCode TuningFork_init(const TFSettings* settings, JNIEnv* env, jobject
context);
You must call this function once at start-up, typically from within native code
executed by the app’s onCreate()
method. It allocates the data needed by the
Tuning Fork library.
You must have a tuningfork_settings.bin
file present in assets/tuningfork
within your app, which contains the histogram and annotation settings. To
convert the text file to binary, see
Text versus binary representations.
The fields you fill in settings
determine how the library initializes itself.
/**
* @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;
};
If you pass in the Swappy_injectTracer()
function
(OpenGL,
Vulkan)
from the Frame Pacing API at initialization, the Tuning Fork library
automatically records frame time without you explicitly calling the tick
functions yourself. This is done in the demo app:
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();
}
...
}
Destroy
TFErrorCode TuningFork_destroy();
You can call this function at shut-down. This function attempts to submit all currently stored-histogram data for later upload before deallocating any memory used by the Tuning Fork library.
Flush
TFErrorCode TuningFork_flush();
This function flushes the recorded histograms (for example, when the game is sent to the background or foreground). It doesn't flush data if the minimum upload period, which has a default of one minute, has not elapsed since the previous upload.
Set fidelity parameters
TFErrorCode TuningFork_setFidelityParameters(const CProtobufSerialization*
params);
This function overrides the current fidelity parameters with which frame data is associated. You should call this function when a player manually changes the quality settings of the game.
Annotations
TFErrorCode TuningFork_setCurrentAnnotation(const CProtobufSerialization*
annotation);
This function sets the annotation to associate with subsequent ticks. It returns
TFERROR_INVALID_ANNOTATION
if there was an error decoding the annotation and
TFERROR_OK
if there was no error.
Per-frame functions
TFErrorCode TuningFork_frameTick(TFInstrumentKey key);
This function records the time between the previous tick with the given key
and the current time in the histogram associated with key
and the current
annotation.
TFErrorCode TuningFork_frameDeltaTimeNanos(TFInstrumentKey key, TFDuration
dt);
This function records duration in the histogram associated with key
and the
current annotation.
TFErrorCode TuningFork_startTrace(TFInstrumentKey key, TraceHandle* handle);
This function sets a handle to a trace handle associated with the given key
.
TFErrorCode TuningFork_endTrace(TraceHandle handle);
This function records the time interval since the associated
TuningFork_startTrace()
call in the histogram associated with the key
that was used and the current
annotation.
App lifecycle functions
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);
Call this function from the appropriate lifecycle methods in your game's main Activity, passing the appropriate enum. By recording the game's lifecycle events, APT is better able to understand when your game may be crashing or when users may be quitting (for example, during long loading events).
Advanced functions
The following functions are available in tuningfork_extra.h
.
Find and load files in an APK
This function loads fidelityParams
from the assets/tuningfork
directory in
the APK with the given filename. fidelityParams
must be a serialization of a
FidelityParams
message. For more information, see
Define quality levels.
Ownership of the serialization is passed to the caller, which must call
CProtobufSerialization_Free
to deallocate any memory held.
Download fidelity parameters on a separate thread
Activates a download thread to retrieve fidelity params. The thread retries the request until the params download or a timeout occurs. Downloaded params are stored locally. When the app is restarted, it uses these downloaded params rather than the default params.
Save and delete fidelity parameters stored on device
This function is only needed in expert mode where fidelity parameters are
downloaded from a server. It either saves over or deletes (if fidelity_params
is null) the locally stored files that are used when the server is unreachable.
Web requests
The library makes the following kinds of requests to the server endpoint:
- A
generateTuningParameters
request is made at initialization. - During gameplay, an
uploadTelemetry
request is periodically made to send data to the server. - Debug APKs can also send
debugInfo
requests, which inform a debug server of the settings, default fidelity parameters, anddev_tuningfork.proto
structure.
Offline players
If there is no available connection at initialization, the request is retried several times with an increasing back-off time.
If there is no connection at upload, the upload is cached. You can provide your
own caching mechanism by passing a
TFCache
object at initialization. If you do not provide your own cache, uploads are
stored as files in temporary storage.