Tuning Fork main interface

The main interface to use Tuning Fork.

Summary

Enumerations

InstrumentKeys{
  TFTICK_RAW_FRAME_TIME = 64000,
  TFTICK_PACED_FRAME_TIME = 64001,
  TFTICK_CPU_TIME = 64002,
  TFTICK_GPU_TIME = 64003
}
enum
Instrument keys indicating time periods within a frame.
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
}
enum
All the error codes that can be returned by Tuning Fork functions.

Typedefs

ProtoCallback)(const CProtobufSerialization *) typedef
void(*
Pointer to a function that can be attached to TFSettings::fidelity_params_callback.
SwappyTracerFn)(const SwappyTracer *) typedef
void(*
Pointer to Swappy_injectTracers that can be attached to TFSettings::swappy_tracer_fn.
TFDuration typedef
uint64_t
A duration in nanoseconds.
TFInstrumentKey typedef
uint16_t
The instrumentation key identifies a tick point within a frame or a trace segment.
TFTimePoint typedef
uint64_t
A time as milliseconds past the epoch.
TFTraceHandle typedef
uint64_t
A trace handle used in TuningFork_startTrace.
UploadCallback)(const char *, size_t n) typedef
void(*
Pointer to a function that can be passed to TuningFork_setUploadCallback.

Functions

CProtobufSerialization_Free(CProtobufSerialization *ser)
void
Deallocate any memory owned by the procol buffer serialization.
TuningFork_destroy()
Clean up all memory owned by Tuning Fork and kill any threads.
TuningFork_enableMemoryRecording(bool enable)
Enable or disable memory telemetry recording.
TuningFork_endTrace(TFTraceHandle handle)
Stop and record a trace segment.
TuningFork_flush()
Force upload of the current histograms.
TuningFork_frameDeltaTimeNanos(TFInstrumentKey key, TFDuration dt)
Record a frame tick using an external time, rather than system time.
TuningFork_frameTick(TFInstrumentKey key)
Record a frame tick that will be associated with the instrumentation key and the current annotation.
TuningFork_getFidelityParameters(const CProtobufSerialization *defaultParams, CProtobufSerialization *params, uint32_t timeout_ms)
A blocking call to get fidelity parameters from the server.
TuningFork_init(const TFSettings *settings, JNIEnv *env, jobject context)
Initialize Tuning Fork.
TuningFork_setCurrentAnnotation(const CProtobufSerialization *annotation)
Set the current annotation.
TuningFork_setFidelityParameters(const CProtobufSerialization *params)
Set the currently active fidelity parameters.
TuningFork_setUploadCallback(UploadCallback cbk)
Set a callback to be called on a separate thread every time TuningFork performs an upload.
TuningFork_startTrace(TFInstrumentKey key, TFTraceHandle *handle)
Start a trace segment.

Structs

CProtobufSerialization

A series of bytes representing a serialized protocol buffer.

TFSettings

Initialization settings Zero any values that are not being used.

Enumerations

InstrumentKeys

 InstrumentKeys

Instrument keys indicating time periods within a frame.

Keys 64000-65535 are reserved

Properties
TFTICK_CPU_TIME

The time between frame start and the call to Swappy_swap.

TFTICK_GPU_TIME

The time between buffer swap and GPU fence triggering.

TFTICK_PACED_FRAME_TIME

Frame time between ends of eglSwapBuffers calls or Vulkan queue present.

TFTICK_RAW_FRAME_TIME

If GPU time is available, thisis MAX(CPU_TIME,GPU_TIME) If not, this is the same as PACED_FRAME_TIME.

TFErrorCode

 TFErrorCode

All the error codes that can be returned by Tuning Fork functions.

Properties
TFERROR_ALREADY_INITIALIZED

TuningFork_init was called more than once.

TFERROR_B64_ENCODE_FAILED

Could not encode a protobuf.

TFERROR_BAD_FILE_OPERATION

General file error.

TFERROR_BAD_PARAMETER

Generic bad parameter.

TFERROR_BAD_SETTINGS

Invalid tuningfork_settings.bin file.

TFERROR_COULDNT_SAVE_OR_DELETE_FPS

Error calling TuningFork_saveOrDeleteFidelityParamsFile.

TFERROR_DOWNLOAD_THREAD_ALREADY_STARTED

TuningFork_startFidelityParamDownloadThread was called more than once, or called when TuningFork_init has already started download.

TFERROR_GENERATE_TUNING_PARAMETERS_ERROR

An error occurred parsing the response to generateTuningParameters.

TFERROR_GENERATE_TUNING_PARAMETERS_RESPONSE_NOT_SUCCESS

The response from generateTuningParameters was not a success code.

TFERROR_INVALID_ANNOTATION

Invalid parameter to TuningFork_setCurrentAnnotation.

TFERROR_INVALID_DEFAULT_FIDELITY_PARAMS

fpDefaultFileNum is out of range.

TFERROR_INVALID_INSTRUMENT_KEY

Invalid instrument key passed to a tick function.

TFERROR_INVALID_TRACE_HANDLE

Invalid handle passed to TuningFork_endTrace.

TFERROR_JNI_BAD_ENV

Jni error - obsolete.

TFERROR_JNI_BAD_JVM

Jni error - obsolete.

TFERROR_JNI_BAD_THREAD

Jni error - obsolete.

TFERROR_JNI_BAD_VERSION

Jni error - obsolete.

TFERROR_JNI_EXCEPTION

Jni error - an exception was thrown. See logcat output.

TFERROR_NO_CLEARCUT

Obsolete.

TFERROR_NO_FIDELITY_PARAMS

No fidelity parameters found at initialization.

TFERROR_NO_FIDELITY_PARAMS_IN_APK

No dev_tuningfork_fidelityparams_#.bin found in assets/tuningfork.

TFERROR_NO_SETTINGS

No tuningfork_settings.bin found in assets/tuningfork.

TFERROR_NO_SETTINGS_ANNOTATION_ENUM_SIZES

Missing part of tuningfork_settings.bin.

TFERROR_NO_SUCH_KEY

No such key when accessing file cache.

TFERROR_NO_SWAPPY

Not able to find the required Swappy functions.

TFERROR_OK

No error.

TFERROR_PLATFORM_NOT_SUPPORTED

The game or app is run on a platform not supporting Tuning fork.

Only used by Unity plugin.

TFERROR_PREVIOUS_UPLOAD_PENDING

Can't upload since another request is pending.

TFERROR_TIMEOUT

Timeout in request for fidelity parameters.

TFERROR_TUNINGFORK_NOT_INITIALIZED

A call was made before Tuning Fork was initialized.

TFERROR_UPLOAD_TOO_FREQUENT

Too frequent calls to TuningFork_flush.

Typedefs

ProtoCallback

void(* ProtoCallback)(const CProtobufSerialization *)

Pointer to a function that can be attached to TFSettings::fidelity_params_callback.

Function that will be called with the fidelity parameters that are downloaded. See also:TFSettings

SwappyTracerFn

void(* SwappyTracerFn)(const SwappyTracer *)

Pointer to Swappy_injectTracers that can be attached to TFSettings::swappy_tracer_fn.

See also: TFSettings

TFDuration

uint64_t TFDuration

A duration in nanoseconds.

TFInstrumentKey

uint16_t TFInstrumentKey

The instrumentation key identifies a tick point within a frame or a trace segment.

TFTimePoint

uint64_t TFTimePoint

A time as milliseconds past the epoch.

TFTraceHandle

uint64_t TFTraceHandle

A trace handle used in TuningFork_startTrace.

UploadCallback

void(* UploadCallback)(const char *, size_t n)

Pointer to a function that can be passed to TuningFork_setUploadCallback.

Function that will be called on a separate thread every time TuningFork performs an upload. See also:TFSettings

Functions

CProtobufSerialization_Free

void CProtobufSerialization_Free(
  CProtobufSerialization *ser
)

Deallocate any memory owned by the procol buffer serialization.

Details
Parameters
ser
A protocol buffer serialization

TuningFork_destroy

TFErrorCode TuningFork_destroy()

Clean up all memory owned by Tuning Fork and kill any threads.

Details
Returns
TFERROR_OK unless Tuning Fork wasn't initialized.

TuningFork_enableMemoryRecording

TFErrorCode TuningFork_enableMemoryRecording(
  bool enable
)

Enable or disable memory telemetry recording.

By default, memory telemetry recording is turned on at initialization.

Details
Parameters
enable
If true, memory recording is enabled, if false it is disabled.
Returns
TFERROR_OK unless Tuning Fork wasn't initialized.

TuningFork_endTrace

TFErrorCode TuningFork_endTrace(
  TFTraceHandle handle
)

Stop and record a trace segment.

Details
Parameters
handle
this is a handle previously returned by TuningFork_startTrace
Returns
TFERROR_INVALID_TRACE_HANDLE if the handle is invalid. TFERROR_OK on success.

TuningFork_flush

TFErrorCode TuningFork_flush()

Force upload of the current histograms.

Details
Returns
TFERROR_OK if the upload could be initiated. TFERROR_PREVIOUS_UPLOAD_PENDING if there is a previous upload blocking this one. TFERROR_UPLOAD_TOO_FREQUENT if less than a minute has elapsed since the previous upload.

TuningFork_frameDeltaTimeNanos

TFErrorCode TuningFork_frameDeltaTimeNanos(
  TFInstrumentKey key,
  TFDuration dt
)

Record a frame tick using an external time, rather than system time.

See also:the reserved instrument keys above

Details
Parameters
key
an instrument key
Parameters
dt
the duration you wish to record (in nanoseconds)
Returns
TFERROR_INVALID_INSTRUMENT_KEY if the instrument key is invalid. TFERROR_OK on success.

TuningFork_frameTick

TFErrorCode TuningFork_frameTick(
  TFInstrumentKey key
)

Record a frame tick that will be associated with the instrumentation key and the current annotation.

NB: calling the tick or trace functions from different threads is allowed, but a single instrument key should always be ticked from the same thread. See also:the reserved instrument keys above

Details
Parameters
key
an instrument key
Returns
TFERROR_INVALID_INSTRUMENT_KEY if the instrument key is invalid. TFERROR_OK on success.

TuningFork_getFidelityParameters

TFErrorCode TuningFork_getFidelityParameters(
  const CProtobufSerialization *defaultParams,
  CProtobufSerialization *params,
  uint32_t timeout_ms
)

A blocking call to get fidelity parameters from the server.

You do not need to call this if you pass in a fidelity_params_callback as part of the settings to TuningFork_init. Note that once fidelity parameters are downloaded, any timing information is recorded as being associated with those parameters. If you subsequently call GetFidelityParameters and a new set of parameters is downloaded, any data that is already collected will be submitted to the backend. Ownership of 'params' is transferred to the caller, so they must call params->dealloc when they are done with it. The parameter request is sent to: ${url_base}+'applications/'+package_name+'/apks/'+version_number+':generateTuningParameters'.

Details
Parameters
defaultParams
these will be assumed current if no parameters could be downloaded.
params
timeout_ms
time to wait before returning from this call when no connection can be made. If zero or negative, the value in Settings.initial_request_timeout_ms is used.
Returns
TFERROR_TIMEOUT if there was a timeout before params could be downloaded. TFERROR_OK on success.

TuningFork_init

TFErrorCode TuningFork_init(
  const TFSettings *settings,
  JNIEnv *env,
  jobject context
)

Initialize Tuning Fork.

This must be called before any other functions.

The library will load histogram and annotation settings from your tuningfork_settings.bin file. See also:TFSettings for the semantics of how other settings change initialization behaviour.

Details
Parameters
settings
a TFSettings structure
env
a JNIEnv
context
the app context
Returns
TFERROR_OK if successful, TFERROR_NO_SETTINGS if no settings could be found, TFERROR_BAD_SETTINGS if your tuningfork_settings.bin file was invalid or TFERROR_ALREADY_INITIALIZED if tuningfork was already initialized.

TuningFork_setCurrentAnnotation

TFErrorCode TuningFork_setCurrentAnnotation(
  const CProtobufSerialization *annotation
)

Set the current annotation.

Details
Parameters
annotation
the protobuf serialization of the current annotation.
Returns
TFERROR_INVALID_ANNOTATION if annotation is inconsistent with the settings.
Returns
TFERROR_OK on success.

TuningFork_setFidelityParameters

TFErrorCode TuningFork_setFidelityParameters(
  const CProtobufSerialization *params
)

Set the currently active fidelity parameters.

This function overrides any parameters that have been downloaded if in experiment mode. Use when, for instance, the player has manually changed game quality settings. This flushes (i.e. uploads) any data associated with any previous parameters.

Details
Parameters
params
The protocol buffer encoded parameters.
Returns
TFERROR_OK if the parameters could be set.

TuningFork_setUploadCallback

TFErrorCode TuningFork_setUploadCallback(
  UploadCallback cbk
)

Set a callback to be called on a separate thread every time TuningFork performs an upload.

Details
Parameters
cbk
Returns
TFERROR_OK unless Tuning Fork wasn't initialized.

TuningFork_startTrace

TFErrorCode TuningFork_startTrace(
  TFInstrumentKey key,
  TFTraceHandle *handle
)

Start a trace segment.

See also:the reserved instrument keys above

Details
Parameters
key
an instrument key
Parameters
handle
this is filled with a new handle on success.
Returns
TFERROR_INVALID_INSTRUMENT_KEY if the instrument key is invalid. TFERROR_OK on success.