Tuning Fork main interface

The main interface to use Tuning Fork.

Summary

Enumerations
LoadingSource enum
LoadingState enum
NetworkConnectivity enum
TuningFork_ErrorCode{
  TUNINGFORK_ERROR_OK = 0,
  TUNINGFORK_ERROR_NO_SETTINGS = 1,
  TUNINGFORK_ERROR_NO_SWAPPY = 2,
  TUNINGFORK_ERROR_INVALID_DEFAULT_FIDELITY_PARAMS = 3,
  TUNINGFORK_ERROR_NO_FIDELITY_PARAMS = 4,
  TUNINGFORK_ERROR_TUNINGFORK_NOT_INITIALIZED = 5,
  TUNINGFORK_ERROR_INVALID_ANNOTATION = 6,
  TUNINGFORK_ERROR_INVALID_INSTRUMENT_KEY = 7,
  TUNINGFORK_ERROR_INVALID_TRACE_HANDLE = 8,
  TUNINGFORK_ERROR_TIMEOUT = 9,
  TUNINGFORK_ERROR_BAD_PARAMETER = 10,
  TUNINGFORK_ERROR_B64_ENCODE_FAILED = 11,
  TUNINGFORK_ERROR_JNI_BAD_VERSION = 12,
  TUNINGFORK_ERROR_JNI_BAD_THREAD = 13,
  TUNINGFORK_ERROR_JNI_BAD_ENV = 14,
  TUNINGFORK_ERROR_JNI_EXCEPTION = 15,
  TUNINGFORK_ERROR_JNI_BAD_JVM = 16,
  TUNINGFORK_ERROR_NO_CLEARCUT = 17,
  TUNINGFORK_ERROR_NO_FIDELITY_PARAMS_IN_APK = 18,
  TUNINGFORK_ERROR_COULDNT_SAVE_OR_DELETE_FPS = 19,
  TUNINGFORK_ERROR_PREVIOUS_UPLOAD_PENDING = 20,
  TUNINGFORK_ERROR_UPLOAD_TOO_FREQUENT = 21,
  TUNINGFORK_ERROR_NO_SUCH_KEY = 22,
  TUNINGFORK_ERROR_BAD_FILE_OPERATION = 23,
  TUNINGFORK_ERROR_BAD_SETTINGS = 24,
  TUNINGFORK_ERROR_ALREADY_INITIALIZED = 25,
  TUNINGFORK_ERROR_NO_SETTINGS_ANNOTATION_ENUM_SIZES = 26,
  TUNINGFORK_ERROR_DOWNLOAD_THREAD_ALREADY_STARTED = 27,
  TUNINGFORK_ERROR_PLATFORM_NOT_SUPPORTED = 28,
  TUNINGFORK_ERROR_GENERATE_TUNING_PARAMETERS_ERROR = 29,
  TUNINGFORK_ERROR_GENERATE_TUNING_PARAMETERS_RESPONSE_NOT_SUCCESS = 30,
  TUNINGFORK_ERROR_NO_MORE_SPACE_FOR_LOADING_TIME_DATA = 31,
  TUNINGFORK_ERROR_NO_MORE_SPACE_FOR_FRAME_TIME_DATA = 32,
  TUNINGFORK_ERROR_INVALID_LOADING_HANDLE = 33,
  TUNINGFORK_ERROR_DUPLICATE_START_LOADING_EVENT = 34,
  TUNINGFORK_ERROR_METERED_CONNECTION_DISALLOWED = 35,
  TUNINGFORK_ERROR_INVALID_LOADING_STATE = 36,
  TUNINGFORK_ERROR_NO_ACTIVE_LOADING_GROUP = 37,
  TUNINGFORK_ERROR_FRAME_LOGGING_ALREADY_PAUSED = 38,
  TUNINGFORK_ERROR_FRAME_LOGGING_ALREADY_RUNNING = 39,
  TUNINGFORK_ERROR_PREDICT_QUALITY_LEVELS_PARSE_ERROR = 40,
  TUNINGFORK_ERROR_PREDICT_QUALITY_LEVELS_RESPONSE_ERROR = 41
} 		enum
All the error codes that can be returned by Tuning Fork functions.
TuningFork_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.
TuningFork_LifecycleState enum
The set of states that the TuningFork_reportLifecycleEvent method accepts.
TuningFork_Submission enum

Typedefs
SwappyTracerFn)(const struct SwappyTracer *) typedef
void(*
Pointer to Swappy_injectTracers that can be attached to TuningFork_Settings::swappy_tracer_fn.
TuningFork_CProtobufArray typedef
A series of bytes representing an array of serialized protocol buffers.
TuningFork_CProtobufSerialization typedef
A series of bytes representing a serialized protocol buffer.
TuningFork_Duration typedef
uint64_t
A duration in nanoseconds.
TuningFork_ErrorCode typedef
All the error codes that can be returned by Tuning Fork functions.
TuningFork_FidelityParamsCallback)(const TuningFork_CProtobufSerialization *) typedef
void(*
Pointer to a function that can be attached to TuningFork_Settings::fidelity_params_callback.
TuningFork_InstrumentKey typedef
uint16_t
The instrumentation key identifies a tick point within a frame or a trace segment.
TuningFork_LifecycleState typedef
The set of states that the TuningFork_reportLifecycleEvent method accepts.
TuningFork_LoadingEventHandle typedef
uint64_t
A handle used in TuningFork_startRecordingLoadingTime.
TuningFork_LoadingGroupHandle typedef
uint64_t
A handle used in TuningFork_startLoadingGroup.
TuningFork_LoadingTimeMetadata typedef
Metadata recorded with a loading time event.
TuningFork_MetricLimits typedef
Limits on the number of metrics of each type.
TuningFork_Settings typedef
Initialization settings Zero any values that are not being used.
TuningFork_Submission typedef
enum TuningFork_Submission
TuningFork_TimePoint typedef
uint64_t
A time as milliseconds past the epoch.
TuningFork_TraceHandle typedef
uint64_t
A trace handle used in TuningFork_startTrace.
TuningFork_UploadCallback)(const char *message, size_t size) typedef
void(*
Pointer to a function that can be passed to TuningFork_setUploadCallback.

Functions
TuningFork_CProtobufArray_free(TuningFork_CProtobufArray *array)
void
Deallocate any memory owned by the given protobuf array.
TuningFork_CProtobufSerialization_free(TuningFork_CProtobufSerialization *ser)
void
Deallocate any memory owned by the protocol 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(TuningFork_TraceHandle handle)
Stop and record a trace segment.
TuningFork_flush()
Force upload of the current histograms.
TuningFork_frameDeltaTimeNanos(TuningFork_InstrumentKey key, TuningFork_Duration dt)
Record a frame tick using an external time, rather than system time.
TuningFork_frameTick(TuningFork_InstrumentKey key)
Record a frame tick that will be associated with the instrumentation key and the current annotation.
TuningFork_getFidelityParameters(const TuningFork_CProtobufSerialization *defaultParams, TuningFork_CProtobufSerialization *params, uint32_t timeout_ms)
A blocking call to get fidelity parameters from the server.
TuningFork_init(const TuningFork_Settings *settings, JNIEnv *env, jobject context)
Initialize Tuning Fork.
TuningFork_isFrameTimeLoggingPaused()
bool
Check if frame time logging is paused.
TuningFork_pauseFrameTimeLogging()
Pause the recording of frame times to the frame time histogram.
TuningFork_predictQualityLevels(TuningFork_CProtobufArray *qualityLevels, uint32_t target_frame_time_ms, uint32_t timeout_ms)
A blocking call to get quality level predictions from the server.
TuningFork_recordLoadingTime(uint64_t time_ns, const TuningFork_LoadingTimeMetadata *eventMetadata, uint32_t eventMetadataSize, const TuningFork_CProtobufSerialization *annotation)
Record a loading time event.
TuningFork_reportLifecycleEvent(TuningFork_LifecycleState state)
Record the state change of the app's lifecycle.
TuningFork_resumeFrameTimeLogging()
Resume the recording of frame times to the frame time histogram.
TuningFork_setAggregationStrategyInterval(TuningFork_Submission method, uint32_t interval_ms_or_count)
Set the interval between histogram uploads, overriding that in settings.
TuningFork_setCurrentAnnotation(const TuningFork_CProtobufSerialization *annotation)
Set the current annotation.
TuningFork_setFidelityParameters(const TuningFork_CProtobufSerialization *params)
Set the currently active fidelity parameters.
TuningFork_setUploadCallback(TuningFork_UploadCallback cbk)
Set a callback to be called on a separate thread every time TuningFork performs an upload.
TuningFork_startLoadingGroup(const TuningFork_LoadingTimeMetadata *eventMetadata, uint32_t eventMetadataSize, const TuningFork_CProtobufSerialization *annotation, TuningFork_LoadingGroupHandle *handle)
Start a loading group.
TuningFork_startRecordingLoadingTime(const TuningFork_LoadingTimeMetadata *eventMetadata, uint32_t eventMetadataSize, const TuningFork_CProtobufSerialization *annotation, TuningFork_LoadingEventHandle *handle)
Record the start of a loading event.
TuningFork_startTrace(TuningFork_InstrumentKey key, TuningFork_TraceHandle *handle)
Start a trace segment.
TuningFork_stopLoadingGroup(TuningFork_LoadingGroupHandle handle)
Stop recording events as belonging to a group and record a group event.
TuningFork_stopRecordingLoadingTime(TuningFork_LoadingEventHandle handle)
Record the end of a loading event.
Tuningfork_versionString()
const char *
Get the Tuning Fork API version as a null-terminated ASCII string.

Structs
TuningFork_CProtobufArray

A series of bytes representing an array of serialized protocol buffers.

TuningFork_CProtobufSerialization

A series of bytes representing a serialized protocol buffer.

TuningFork_LoadingTimeMetadata

Metadata recorded with a loading time event.

TuningFork_MetricLimits

Limits on the number of metrics of each type.

TuningFork_Settings

Initialization settings Zero any values that are not being used.

Enumerations

LoadingSource

 LoadingSource

LoadingState

 LoadingState

NetworkConnectivity

 NetworkConnectivity

TuningFork_ErrorCode

 TuningFork_ErrorCode

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

Properties
TUNINGFORK_ERROR_ALREADY_INITIALIZED

TuningFork_init was called more than once.

TUNINGFORK_ERROR_B64_ENCODE_FAILED

Could not encode a protobuf.

TUNINGFORK_ERROR_BAD_FILE_OPERATION

General file error.

TUNINGFORK_ERROR_BAD_PARAMETER

Generic bad parameter.

TUNINGFORK_ERROR_BAD_SETTINGS

Invalid tuningfork_settings.bin file.

TUNINGFORK_ERROR_COULDNT_SAVE_OR_DELETE_FPS

Error calling TuningFork_saveOrDeleteFidelityParamsFile.

TUNINGFORK_ERROR_DOWNLOAD_THREAD_ALREADY_STARTED

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

TUNINGFORK_ERROR_DUPLICATE_START_LOADING_EVENT

TuningFork_startRecordingLoadingTime was called with the same parameters twice without a stop function inbetween.

TUNINGFORK_ERROR_FRAME_LOGGING_ALREADY_PAUSED

Cannot pause frame time logging because it is already paused.

TUNINGFORK_ERROR_FRAME_LOGGING_ALREADY_RUNNING

Cannot resume frame time logging because it is already running.

TUNINGFORK_ERROR_GENERATE_TUNING_PARAMETERS_ERROR

An error occurred parsing the response to generateTuningParameters.

TUNINGFORK_ERROR_GENERATE_TUNING_PARAMETERS_RESPONSE_NOT_SUCCESS

The response from generateTuningParameters was not a success code.

TUNINGFORK_ERROR_INVALID_ANNOTATION

Invalid parameter to TuningFork_setCurrentAnnotation.

TUNINGFORK_ERROR_INVALID_DEFAULT_FIDELITY_PARAMS

fpDefaultFileNum is out of range.

TUNINGFORK_ERROR_INVALID_INSTRUMENT_KEY

Invalid instrument key passed to a tick function.

TUNINGFORK_ERROR_INVALID_LOADING_HANDLE

Invalid handle passed to TuningFork_startRecordingLoadingTime.

TUNINGFORK_ERROR_INVALID_LOADING_STATE

The loading state was not set as part of TuningFork_LoadingTimeMetadata when calling a loading function.

TUNINGFORK_ERROR_INVALID_TRACE_HANDLE

Invalid handle passed to TuningFork_startTrace.

TUNINGFORK_ERROR_JNI_BAD_ENV

Jni error - obsolete.

TUNINGFORK_ERROR_JNI_BAD_JVM

Jni error - obsolete.

TUNINGFORK_ERROR_JNI_BAD_THREAD

Jni error - obsolete.

TUNINGFORK_ERROR_JNI_BAD_VERSION

Jni error - obsolete.

TUNINGFORK_ERROR_JNI_EXCEPTION

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

TUNINGFORK_ERROR_METERED_CONNECTION_DISALLOWED

An HTTP request could not be made because there is no unmetered connection available.

TUNINGFORK_ERROR_NO_ACTIVE_LOADING_GROUP

There was no active loading group when TuningFork_stopLoadingGroup was called.

TUNINGFORK_ERROR_NO_CLEARCUT

Obsolete.

TUNINGFORK_ERROR_NO_FIDELITY_PARAMS

No fidelity parameters found at initialization.

TUNINGFORK_ERROR_NO_FIDELITY_PARAMS_IN_APK

No dev_tuningfork_fidelityparams_#.bin found in assets/tuningfork.

TUNINGFORK_ERROR_NO_MORE_SPACE_FOR_FRAME_TIME_DATA

Not enough space for metric data was allocated at start-up:

increase Settings.max_num_metrics.frame_time or check max_num_instrument_keys

TUNINGFORK_ERROR_NO_MORE_SPACE_FOR_LOADING_TIME_DATA

Not enough space for metric data was allocated at start-up: increase Settings.max_num_metrics.loading_time.

TUNINGFORK_ERROR_NO_SETTINGS

No tuningfork_settings.bin found in assets/tuningfork.

TUNINGFORK_ERROR_NO_SETTINGS_ANNOTATION_ENUM_SIZES

Missing part of tuningfork_settings.bin.

TUNINGFORK_ERROR_NO_SUCH_KEY

No such key when accessing file cache.

TUNINGFORK_ERROR_NO_SWAPPY

Not able to find the required Swappy functions.

TUNINGFORK_ERROR_OK

No error.

TUNINGFORK_ERROR_PLATFORM_NOT_SUPPORTED

Obsolete.

TUNINGFORK_ERROR_PREDICT_QUALITY_LEVELS_PARSE_ERROR

An error occurred parsing the response to predictQualityLevels.

TUNINGFORK_ERROR_PREDICT_QUALITY_LEVELS_RESPONSE_ERROR

The response from predictQualityLevels was not a success code.

TUNINGFORK_ERROR_PREVIOUS_UPLOAD_PENDING

Can't upload since another request is pending.

TUNINGFORK_ERROR_TIMEOUT

Timeout in request for fidelity parameters.

TUNINGFORK_ERROR_TUNINGFORK_NOT_INITIALIZED

A call was made before Tuning Fork was initialized.

TUNINGFORK_ERROR_UPLOAD_TOO_FREQUENT

Too frequent calls to TuningFork_flush.

TuningFork_InstrumentKeys

 TuningFork_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.

TuningFork_LifecycleState

 TuningFork_LifecycleState

The set of states that the TuningFork_reportLifecycleEvent method accepts.

TuningFork_Submission

 TuningFork_Submission

Typedefs

SwappyTracerFn

void(* SwappyTracerFn)(const struct SwappyTracer *)

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

See also: TuningFork_Settings

TuningFork_CProtobufArray

struct TuningFork_CProtobufArray TuningFork_CProtobufArray

A series of bytes representing an array of serialized protocol buffers.

See also:TuningFork_CProtobufArray_free for how to deallocate the memory once finished with the buffer.

TuningFork_CProtobufSerialization

struct TuningFork_CProtobufSerialization TuningFork_CProtobufSerialization

A series of bytes representing a serialized protocol buffer.

See also:TuningFork_CProtobufSerialization_free for how to deallocate the memory once finished with the buffer.

TuningFork_Duration

uint64_t TuningFork_Duration

A duration in nanoseconds.

TuningFork_ErrorCode

enum TuningFork_ErrorCode TuningFork_ErrorCode

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

TuningFork_FidelityParamsCallback

void(* TuningFork_FidelityParamsCallback)(const TuningFork_CProtobufSerialization *)

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

Function that will be called with the fidelity parameters that are downloaded. See also:TuningFork_Settings Fidelity parameters are serializations of FidelityParams messages defined in a game's dev_tuningfork.proto file. The structure of this message is completely up to the developer, with limitations outlined in the integration guide.

TuningFork_InstrumentKey

uint16_t TuningFork_InstrumentKey

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

TuningFork_LifecycleState

enum TuningFork_LifecycleState TuningFork_LifecycleState

The set of states that the TuningFork_reportLifecycleEvent method accepts.

TuningFork_LoadingEventHandle

uint64_t TuningFork_LoadingEventHandle

A handle used in TuningFork_startRecordingLoadingTime.

TuningFork_LoadingGroupHandle

uint64_t TuningFork_LoadingGroupHandle

A handle used in TuningFork_startLoadingGroup.

TuningFork_LoadingTimeMetadata

struct TuningFork_LoadingTimeMetadata TuningFork_LoadingTimeMetadata

Metadata recorded with a loading time event.

TuningFork_MetricLimits

struct TuningFork_MetricLimits TuningFork_MetricLimits

Limits on the number of metrics of each type.

Zero any values to get the default for that type:

Frame time: min(64, the maximum number of annotation combinations) * num_instrument_keys.

Loading time: 32.

Battery: 32.

Thermal: 32.

Memory: 15 possible memory metrics.

TuningFork_Settings

struct TuningFork_Settings TuningFork_Settings

Initialization settings Zero any values that are not being used.

TuningFork_Submission

enum TuningFork_Submission TuningFork_Submission

TuningFork_TimePoint

uint64_t TuningFork_TimePoint

A time as milliseconds past the epoch.

TuningFork_TraceHandle

uint64_t TuningFork_TraceHandle

A trace handle used in TuningFork_startTrace.

TuningFork_UploadCallback

void(* TuningFork_UploadCallback)(const char *message, size_t size)

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:TuningFork_Settings

Details
Parameters
message
UTF-8 string containing the JSON uploaded.
size
Number of bytes in message.

Functions

TuningFork_CProtobufArray_free

void TuningFork_CProtobufArray_free(
  TuningFork_CProtobufArray *array
)

Deallocate any memory owned by the given protobuf array.

Details
Parameters
array
A protocol buffer array

TuningFork_CProtobufSerialization_free

void TuningFork_CProtobufSerialization_free(
  TuningFork_CProtobufSerialization *ser
)

Deallocate any memory owned by the protocol buffer serialization.

Details
Parameters
ser
A protocol buffer serialization

TuningFork_destroy

TuningFork_ErrorCode TuningFork_destroy()

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

Details
Returns
TUNINGFORK_ERROR_OK on success.
Returns
TUNINGFORK_ERROR_TUNINGFORK_NOT_INITIALIZED if Tuning Fork wasn't initialized.

TuningFork_enableMemoryRecording

TuningFork_ErrorCode TuningFork_enableMemoryRecording(
  bool enable
)

Enable or disable memory telemetry recording.

By default, memory telemetry recording is turned on at initialization, however currently the memory statistics are not shown in the Play UI.

Details
Parameters
enable
If true, memory recording is enabled, if false it is disabled.
Returns
TUNINGFORK_ERROR_OK on success.
Returns
TUNINGFORK_ERROR_TUNINGFORK_NOT_INITIALIZED if Tuning Fork wasn't initialized.

TuningFork_endTrace

TuningFork_ErrorCode TuningFork_endTrace(
  TuningFork_TraceHandle handle
)

Stop and record a trace segment.

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

TuningFork_flush

TuningFork_ErrorCode TuningFork_flush()

Force upload of the current histograms.

Details
Returns
TUNINGFORK_ERROR_OK if the upload could be initiated.
Returns
TUNINGFORK_ERROR_PREVIOUS_UPLOAD_PENDING if there is a previous upload blocking this one.
Returns
TUNINGFORK_ERROR_UPLOAD_TOO_FREQUENT if less than a minute has elapsed since the previous upload.

TuningFork_frameDeltaTimeNanos

TuningFork_ErrorCode TuningFork_frameDeltaTimeNanos(
  TuningFork_InstrumentKey key,
  TuningFork_Duration 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
TUNINGFORK_ERROR_INVALID_INSTRUMENT_KEY if the instrument key is invalid.
Returns
TUNINGFORK_ERROR_OK on success.

TuningFork_frameTick

TuningFork_ErrorCode TuningFork_frameTick(
  TuningFork_InstrumentKey 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
TUNINGFORK_ERROR_INVALID_INSTRUMENT_KEY if the instrument key is invalid.
Returns
TUNINGFORK_ERROR_OK on success.

TuningFork_getFidelityParameters

TuningFork_ErrorCode TuningFork_getFidelityParameters(
  const TuningFork_CProtobufSerialization *defaultParams,
  TuningFork_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
TUNINGFORK_ERROR_TIMEOUT if there was a timeout before params could be downloaded.
Returns
TUNINGFORK_ERROR_TUNINGFORK_NOT_INITIALIZED if TuningFork_init has not been called.
Returns
TUNINGFORK_ERROR_OK on success.

TuningFork_init

TuningFork_ErrorCode TuningFork_init(
  const TuningFork_Settings *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:TuningFork_Settings for the semantics of how other settings change initialization behaviour.

Details
Parameters
settings
a TuningFork_Settings structure
env
a JNIEnv
context
the app context
Returns
TUNINGFORK_ERROR_OK if successful,
Returns
TUNINGFORK_ERROR_NO_SETTINGS if no settings could be found,
Returns
TUNINGFORK_ERROR_BAD_SETTINGS if your tuningfork_settings.bin file was invalid or
Returns
TUNINGFORK_ERROR_ALREADY_INITIALIZED if tuningfork was already initialized.

TuningFork_isFrameTimeLoggingPaused

bool TuningFork_isFrameTimeLoggingPaused()

Check if frame time logging is paused.

Details
Returns
true if frame time logging is paused. False otherwise.

TuningFork_pauseFrameTimeLogging

TuningFork_ErrorCode TuningFork_pauseFrameTimeLogging()

Pause the recording of frame times to the frame time histogram.

This can be useful for disabling frame time recording during menus or loading.

Details
Returns
TUNINGFORK_ERROR_OK on success.
Returns
TUNINGFORK_ERROR_FRAME_LOGGING_ALREADY_PAUSED if logging is already paused
Returns
TUNINGFORK_ERROR_TUNINGFORK_NOT_INITIALIZED if Tuning Fork wasn't initialized.

TuningFork_predictQualityLevels

TuningFork_ErrorCode TuningFork_predictQualityLevels(
  TuningFork_CProtobufArray *qualityLevels,
  uint32_t target_frame_time_ms,
  uint32_t timeout_ms
)

A blocking call to get quality level predictions from the server.

Details
Parameters
qualityLevels
quality levels returned as an array for serialized protocol buffers. Can be empty if quality levels for the apk are not defined.
target_frame_time_ms
the desired time per frame, in milliseconds
timeout_ms
time to wait before returning from this call when no connection can be made. If zero, the value in Settings.initial_request_timeout_ms is used.
Returns
TUNINGFORK_ERROR_OK on success.
Returns
TUNINGFORK_ERROR_TIMEOUT if there was a timeout before predictions could be returned.
Returns
TUNINGFORK_ERROR_PREDICT_QUALITY_LEVELS_RESPONSE_ERROR if the call to the server failed.
Returns
TUNINGFORK_ERROR_PREDICT_QUALITY_LEVELS_PARSE_ERROR if the response couldn't be parsed.

TuningFork_recordLoadingTime

TuningFork_ErrorCode TuningFork_recordLoadingTime(
  uint64_t time_ns,
  const TuningFork_LoadingTimeMetadata *eventMetadata,
  uint32_t eventMetadataSize,
  const TuningFork_CProtobufSerialization *annotation
)

Record a loading time event.

Details
Parameters
time_ns
The time taken for loading event in nanoseconds
eventMetadata
A LoadingTimeMetadata structure
eventMetadataSize
Size in bytes of the LoadingTimeMetadata structure
annotation
The annotation to use with this event.
Returns
TUNINGFORK_ERROR_OK on success.
Returns
TUNINGFORK_ERROR_INVALID_LOADING_STATE if state was not set in the metadata.

TuningFork_reportLifecycleEvent

TuningFork_ErrorCode TuningFork_reportLifecycleEvent(
  TuningFork_LifecycleState state
)

Record the state change of the app's lifecycle.

This method should be called every time the onCreate(), onStart(), onStop() and onDestroy() methods are triggered for the app. This will help tuning fork keep track of exactly when the app is on foreground or background.

Details
Parameters
state
The new lifecycle state of the app
Returns
TUNINGFORK_ERROR_OK on success.
Returns
TUNINGFORK_ERROR_TUNINGFORK_NOT_INITIALIZED if Tuning Fork wasn't initialized.

TuningFork_resumeFrameTimeLogging

TuningFork_ErrorCode TuningFork_resumeFrameTimeLogging()

Resume the recording of frame times to the frame time histogram.

Details
Returns
TUNINGFORK_ERROR_OK on success.
Returns
TUNINGFORK_ERROR_FRAME_LOGGING_ALREADY_RUNNING if logging isn't paused
Returns
TUNINGFORK_ERROR_TUNINGFORK_NOT_INITIALIZED if Tuning Fork wasn't initialized.

TuningFork_setAggregationStrategyInterval

TuningFork_ErrorCode TuningFork_setAggregationStrategyInterval(
  TuningFork_Submission method,
  uint32_t interval_ms_or_count
)

Set the interval between histogram uploads, overriding that in settings.

See also: TuningFork_frameTick

Details
Parameters
method
Whether to use time-based or tick-based strategy.
interval_ms_or_count
Millisecond or count-based interval.
Returns
TUNINGFORK_ERROR_OK on success.
Returns
TUNINGFORK_ERROR_TUNINGFORK_NOT_INITIALIZED if Tuning Fork wasn't initialized.
Returns
TUNINGFORK_ERROR_BAD_PARAMETER if method is not TIME_BASED or TICK_BASED or if interval_ms_or_count is 0 or greater than one day.

TuningFork_setCurrentAnnotation

TuningFork_ErrorCode TuningFork_setCurrentAnnotation(
  const TuningFork_CProtobufSerialization *annotation
)

Set the current annotation.

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

TuningFork_setFidelityParameters

TuningFork_ErrorCode TuningFork_setFidelityParameters(
  const TuningFork_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
TUNINGFORK_ERROR_OK on success.
Returns
TUNINGFORK_ERROR_TUNINGFORK_NOT_INITIALIZED if Tuning Fork wasn't initialized.

TuningFork_setUploadCallback

TuningFork_ErrorCode TuningFork_setUploadCallback(
  TuningFork_UploadCallback cbk
)

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

Details
Parameters
cbk
Returns
TUNINGFORK_ERROR_OK on success.
Returns
TUNINGFORK_ERROR_TUNINGFORK_NOT_INITIALIZED if Tuning Fork wasn't initialized.

TuningFork_startLoadingGroup

TuningFork_ErrorCode TuningFork_startLoadingGroup(
  const TuningFork_LoadingTimeMetadata *eventMetadata,
  uint32_t eventMetadataSize,
  const TuningFork_CProtobufSerialization *annotation,
  TuningFork_LoadingGroupHandle *handle
)

Start a loading group.

Subsequent loading times will be tagged with this group's id until startLoadingGroup is called again or stopLoadingGroup is called.

Details
Parameters
eventMetadata
A LoadingTimeMetadata structure.
eventMetadataSize
Size in bytes of the LoadingTimeMetadata structure (for versioning of the structure).
annotation
The annotation to use with this event.
handle
A handle for this event (currently is always null since there can only be one loading group active).
Returns
TUNINGFORK_ERROR_OK on success.
Returns
TUNINGFORK_ERROR_INVALID_LOADING_STATE if state was not set in the metadata.

TuningFork_startRecordingLoadingTime

TuningFork_ErrorCode TuningFork_startRecordingLoadingTime(
  const TuningFork_LoadingTimeMetadata *eventMetadata,
  uint32_t eventMetadataSize,
  const TuningFork_CProtobufSerialization *annotation,
  TuningFork_LoadingEventHandle *handle
)

Record the start of a loading event.

Details
Parameters
eventMetadata
A LoadingTimeMetadata structure.
eventMetadataSize
Size in bytes of the LoadingTimeMetadata structure (for versioning of the structure).
annotation
The annotation to use with this event.
handle
A handle for this event.
Returns
TUNINGFORK_ERROR_OK on success.
Returns
TUNINGFORK_ERROR_INVALID_LOADING_STATE if state was not set in the metadata.

TuningFork_startTrace

TuningFork_ErrorCode TuningFork_startTrace(
  TuningFork_InstrumentKey key,
  TuningFork_TraceHandle *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
TUNINGFORK_ERROR_INVALID_INSTRUMENT_KEY if the instrument key is invalid.
Returns
TUNINGFORK_ERROR_OK on success.

TuningFork_stopLoadingGroup

TuningFork_ErrorCode TuningFork_stopLoadingGroup(
  TuningFork_LoadingGroupHandle handle
)

Stop recording events as belonging to a group and record a group event.

Details
Parameters
handle
A handle generated by startLoadingGroup (currently should be 0).

TuningFork_stopRecordingLoadingTime

TuningFork_ErrorCode TuningFork_stopRecordingLoadingTime(
  TuningFork_LoadingEventHandle handle
)

Record the end of a loading event.

Details
Parameters
handle
A handle generated by startRecordingLoadingTime

Tuningfork_versionString

const char * Tuningfork_versionString()

Get the Tuning Fork API version as a null-terminated ASCII string.