Interfaz principal de Tuning Fork

Es la interfaz principal para usar Tuning Fork.

Resumen

Enumeraciones

InstrumentKeys{
  TFTICK_RAW_FRAME_TIME = 64000,
  TFTICK_PACED_FRAME_TIME = 64001,
  TFTICK_CPU_TIME = 64002,
  TFTICK_GPU_TIME = 64003
}
enum
Etiquetas de marca que indican los períodos de un fotograma.
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
Son todos los códigos de error que las funciones de Tuning Fork pueden mostrar.

Typedefs

ProtoCallback)(const CProtobufSerialization *) typedef
void(*
Es un puntero a una función que se puede adjuntar a TFSettings::fidelity_params_callback.
SwappyTracerFn)(const SwappyTracer *) typedef
void(*
Es un puntero a Swappy_injectTracers que se puede adjuntar a TFSettings::swappy_tracer_fn.
TFDuration typedef
uint64_t
Es la duración en nanosegundos.
TFInstrumentKey typedef
uint16_t
Es la etiqueta de marca identifica el punto en el que ocurre una marca en un fotograma o un segmento de seguimiento.
TFTimePoint typedef
uint64_t
Es la hora expresada en milisegundos transcurridos a partir de la época.
TFTraceHandle typedef
uint64_t
Es el controlador de seguimiento utilizado en TuningFork_startTrace.
UploadCallback)(const char *, size_t n) typedef
void(*
Es el puntero a una función que se puede pasar a TuningFork_setUploadCallback.

Funciones

CProtobufSerialization_Free(CProtobufSerialization *ser)
void
Anula la asignación de la memoria que pertenece a la serialización del búfer de protocolo.
TuningFork_destroy()
Limpia toda la memoria que pertenece a Tuning Fork y termina cualquier subproceso.
TuningFork_enableMemoryRecording(bool enable)
Habilita o inhabilita la grabación de telemetría en la memoria.
TuningFork_endTrace(TFTraceHandle handle)
Detiene y graba un segmento de seguimiento.
TuningFork_flush()
Fuerza la carga de los histogramas de ese momento.
TuningFork_frameDeltaTimeNanos(TFInstrumentKey key, TFDuration dt)
Graba una marca de fotograma usando una hora externa en lugar de la del sistema.
TuningFork_frameTick(TFInstrumentKey key)
Graba una marca de fotograma que se asociará a la etiqueta de marca y a la anotación actual.
TuningFork_getFidelityParameters(const CProtobufSerialization *defaultParams, CProtobufSerialization *params, uint32_t timeout_ms)
Es una llamada de bloqueo para obtener los parámetros de fidelidad del servidor.
TuningFork_init(const TFSettings *settings, JNIEnv *env, jobject context)
Inicializa Tuning Fork.
TuningFork_setCurrentAnnotation(const CProtobufSerialization *annotation)
Establece la anotación actual.
TuningFork_setFidelityParameters(const CProtobufSerialization *params)
Establece los parámetros de fidelidad actualmente activos.
TuningFork_setUploadCallback(UploadCallback cbk)
Configura una devolución de llamada para que tenga lugar en un subproceso independiente cada vez que Tuning Fork realice una carga.
TuningFork_startTrace(TFInstrumentKey key, TFTraceHandle *handle)
Inicia un segmento de seguimiento.

Structs

CProtobufSerialization

Es una serie de bytes que representan un búfer de protocolo serializado.

TFSettings

La configuración de inicialización asigna cero a los valores que no estén en uso.

Enumeraciones

InstrumentKeys

 InstrumentKeys

Etiquetas de marca que indican los períodos de un fotograma.

Las claves 64000 a 65535 están reservadas.

Propiedades
TFTICK_CPU_TIME

Es el tiempo que transcurre entre el inicio del fotograma y la llamada a Swappy_swap.

TFTICK_GPU_TIME

Es el tiempo que transcurre entre el intercambio de búfer y la activación de vallas de la GPU.

TFTICK_PACED_FRAME_TIME

Es la latencia de fotogramas entre los finales de las llamadas de eglSwapBuffers o la fila de presentación de Vulkan.

TFTICK_RAW_FRAME_TIME

Si el tiempo de espera de GPU está disponible, este valor será MAX(CPU_TIME,GPU_TIME). Si no lo está, el valor será igual a PACED_FRAME_TIME.

TFErrorCode

 TFErrorCode

Son todos los códigos de error que las funciones de Tuning Fork pueden mostrar.

Propiedades
TFERROR_ALREADY_INITIALIZED

Se llamó a TuningFork_init más de una vez.

TFERROR_B64_ENCODE_FAILED

No se pudo codificar un protobuf.

TFERROR_BAD_FILE_OPERATION

Corresponde a un error general de archivo.

TFERROR_BAD_PARAMETER

Corresponde a un parámetro incorrecto genérico.

TFERROR_BAD_SETTINGS

Corresponde a un archivo tuningfork_settings.bin no válido.

TFERROR_COULDNT_SAVE_OR_DELETE_FPS

Se produjo un error al llamar a TuningFork_saveOrDeleteFidelityParamsFile.

TFERROR_DOWNLOAD_THREAD_ALREADY_STARTED

Se llamó a TuningFork_startFidelityParamDownloadThread más de una vez, o se lo llamó cuando TuningFork_init ya había comenzado la descarga.

TFERROR_GENERATE_TUNING_PARAMETERS_ERROR

Se produjo un error al analizar la respuesta a generateTuningParameters.

TFERROR_GENERATE_TUNING_PARAMETERS_RESPONSE_NOT_SUCCESS

La respuesta de generateTuningParameters no fue un código correcto.

TFERROR_INVALID_ANNOTATION

Corresponde a un parámetro no válido para TuningFork_setCurrentAnnotation.

TFERROR_INVALID_DEFAULT_FIDELITY_PARAMS

fpDefaultFileNum está fuera del rango.

TFERROR_INVALID_INSTRUMENT_KEY

Se pasó una etiqueta de marca no válida a una función de marca.

TFERROR_INVALID_TRACE_HANDLE

Se pasó un controlador no válido a TuningFork_endTrace.

TFERROR_JNI_BAD_ENV

Es un error de Jni (obsoleto).

TFERROR_JNI_BAD_JVM

Es un error de Jni (obsoleto).

TFERROR_JNI_BAD_THREAD

Es un error de Jni (obsoleto).

TFERROR_JNI_BAD_VERSION

Es un error de Jni (obsoleto).

TFERROR_JNI_EXCEPTION

Error de Jni: se arrojó una excepción. Consulta el resultado de logcat.

TFERROR_NO_CLEARCUT

Obsoleto.

TFERROR_NO_FIDELITY_PARAMS

No se encontraron parámetros de fidelidad en la inicialización.

TFERROR_NO_FIDELITY_PARAMS_IN_APK

No se encontró dev_tuningfork_fidelityparams_#.bin en assets/tuningfork.

TFERROR_NO_SETTINGS

No se encontró tuningfork_settings.bin en assets/tuningfork.

TFERROR_NO_SETTINGS_ANNOTATION_ENUM_SIZES

Falta una parte de tuningfork_settings.bin.

TFERROR_NO_SUCH_KEY

No se encuentra la clave al acceder a la caché del archivo.

TFERROR_NO_SWAPPY

No se pueden encontrar las funciones Swappy requeridas.

TFERROR_OK

No hay errores.

TFERROR_PLATFORM_NOT_SUPPORTED

El juego o la app se ejecutan en una plataforma que no admite Tuning Fork.

Utilizada solo por el complemento de Unity.

TFERROR_PREVIOUS_UPLOAD_PENDING

No se pueden subir los videos porque hay otra solicitud pendiente.

TFERROR_TIMEOUT

Se agotó el tiempo de espera de la solicitud de parámetros de fidelidad.

TFERROR_TUNINGFORK_NOT_INITIALIZED

Se realizó una llamada antes de inicializar Tuning Fork.

TFERROR_UPLOAD_TOO_FREQUENT

Se produjeron llamadas demasiado frecuentes a TuningFork_flush.

Typedefs

ProtoCallback

void(* ProtoCallback)(const CProtobufSerialization *)

Es un puntero a una función que se puede adjuntar a TFSettings::fidelity_params_callback.

Es una función que se llamará con los parámetros de fidelidad que se descarguen. Consulta también:TFSettings

SwappyTracerFn

void(* SwappyTracerFn)(const SwappyTracer *)

Es un puntero a Swappy_injectTracers que se puede adjuntar a TFSettings::swappy_tracer_fn.

Consulta también: TFSettings

TFDuration

uint64_t TFDuration

Es la duración en nanosegundos.

TFInstrumentKey

uint16_t TFInstrumentKey

Es la etiqueta de marca identifica el punto en el que ocurre una marca en un fotograma o un segmento de seguimiento.

TFTimePoint

uint64_t TFTimePoint

Es la hora expresada en milisegundos transcurridos a partir de la época.

TFTraceHandle

uint64_t TFTraceHandle

Es el controlador de seguimiento utilizado en TuningFork_startTrace.

UploadCallback

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

Es el puntero a una función que se puede pasar a TuningFork_setUploadCallback.

Función que se llamará en un subproceso independiente cada vez que TuningFork realice una carga. Consulta también:TFSettings

Funciones

CProtobufSerialization_Free

void CProtobufSerialization_Free(
  CProtobufSerialization *ser
)

Anula la asignación de la memoria que pertenece a la serialización del búfer de protocolo.

Detalles
Parámetros
ser
Serialización del búfer de protocolo

TuningFork_destroy

TFErrorCode TuningFork_destroy()

Limpia toda la memoria que pertenece a Tuning Fork y termina cualquier subproceso.

Detalles
Resultado que se muestra
Será TFERROR_OK a menos que no se haya inicializado Tuning Fork.

TuningFork_enableMemoryRecording

TFErrorCode TuningFork_enableMemoryRecording(
  bool enable
)

Habilita o inhabilita la grabación de telemetría en la memoria.

De manera predeterminada, la grabación de telemetría en la memoria se activa en la inicialización.

Detalles
Parámetros
enable
Si es verdadero, se habilita la grabación en la memoria. Si es falso, se inhabilita.
Resultado que se muestra
Será TFERROR_OK a menos que no se haya inicializado Tuning Fork.

TuningFork_endTrace

TFErrorCode TuningFork_endTrace(
  TFTraceHandle handle
)

Detiene y graba un segmento de seguimiento.

Detalles
Parámetros
handle
Este es un controlador que TuningFork_startTrace mostró previamente.
Resultado que se muestra
Se mostrará TFERROR_INVALID_TRACE_HANDLE si el controlador no es válido y TFERROR_OK si la operación fue exitosa.

TuningFork_flush

TFErrorCode TuningFork_flush()

Fuerza la carga de los histogramas de ese momento.

Detalles
Resultado que se muestra
Se mostrará TFERROR_OK si se pudo iniciar la carga, TFERROR_PREVIOUS_UPLOAD_PENDING si hay una carga anterior que esté bloqueando esta y TFERROR_UPLOAD_TOO_FREQUENT si transcurrió menos de un minuto desde la carga anterior.

TuningFork_frameDeltaTimeNanos

TFErrorCode TuningFork_frameDeltaTimeNanos(
  TFInstrumentKey key,
  TFDuration dt
)

Graba una marca de fotograma usando una hora externa en lugar de la del sistema.

Consulta también:las etiquetas de marca reservadas anteriores

Detalles
Parámetros
key
Es una etiqueta de marca.
Parámetros
dt
la duración que deseas grabar (en nanosegundos)
Resultado que se muestra
Se mostrará TFERROR_INVALID_INSTRUMENT_KEY si la etiqueta de marca no es válida y TFERROR_OK si la operación fue exitosa.

TuningFork_frameTick

TFErrorCode TuningFork_frameTick(
  TFInstrumentKey key
)

Graba una marca de fotograma que se asociará a la etiqueta de marca y a la anotación actual.

Ten en cuenta que, aunque se permite llamar a las funciones de marca o de seguimiento desde diferentes subprocesos, una etiqueta de marca siempre debe marcarse desde el mismo subproceso. Consulta también:las etiquetas de marca reservadas anteriores

Detalles
Parámetros
key
Es una etiqueta de marca.
Resultado que se muestra
Se mostrará TFERROR_INVALID_INSTRUMENT_KEY si la etiqueta de marca no es válida y TFERROR_OK si la operación fue exitosa.

TuningFork_getFidelityParameters

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

Es una llamada de bloqueo para obtener los parámetros de fidelidad del servidor.

No es necesario que la llames si pasas un método fidelity_params_callback como parte de la configuración a TuningFork_init. Ten en cuenta que, una vez que se descarguen los parámetros de fidelidad, la información de latencia se grabará como la asociada con esos parámetros. Si luego llamas a GetFidelityParameters y se descarga un nuevo conjunto de parámetros, los datos que ya se hayan recopilado se enviarán al backend. La propiedad de "params" se transfiere al llamador, por lo que deben llamar a params->dealloc cuando finalicen el proceso. La solicitud de parámetros se envía a: ${url_base}+"applications/"+package_name+"/apks/"+version_number+":generateTuningParameters".

Detalles
Parámetros
defaultParams
Si no se pudieron descargar parámetros, se asume que estos son los actuales.
params
timeout_ms
Es el tiempo de espera antes de volver de esta llamada cuando no se puede establecer una conexión. Si es cero o negativo, se usa el valor en Settings.initial_request_timeout_ms.
Resultado que se muestra
Se mostrará TFERROR_TIMEOUT si se agotó el tiempo de espera antes de que se descargaran los parámetros y TFERROR_OK si la operación fue exitosa.

TuningFork_init

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

Inicializa Tuning Fork.

Se debe llamar antes que a cualquier otra función.

La biblioteca cargará la configuración de los histogramas y las anotaciones desde tu archivo tuningfork_settings.bin. Consulta también:TFSettings a fin de obtener la semántica de cómo otras configuraciones cambian el comportamiento de inicialización.

Detalles
Parámetros
settings
Es una estructura TFSettings
env
Es una JNIEnv
context
Es el contexto de la app.
Resultado que se muestra
Será TFERROR_OK si se ejecuta correctamente, TFERROR_NO_SETTINGS si no se pudo encontrar la configuración, TFERROR_BAD_SETTINGS si el archivo tuningfork_settings.bin no era válido y TFERROR_ALREADY_INITIALIZED si ya se inicializó tuningfork.

TuningFork_setCurrentAnnotation

TFErrorCode TuningFork_setCurrentAnnotation(
  const CProtobufSerialization *annotation
)

Establece la anotación actual.

Detalles
Parámetros
annotation
Es la serialización protobuf de la anotación actual.
Resultado que se muestra
Será TFERROR_INVALID_ANNOTATION si la anotación no se condice con la configuración.
Resultado que se muestra
Será TFERROR_OK si la operación fue exitosa.

TuningFork_setFidelityParameters

TFErrorCode TuningFork_setFidelityParameters(
  const CProtobufSerialization *params
)

Establece los parámetros de fidelidad actualmente activos.

Esta función anula los parámetros que se descargaron si está en el modo experimental. Úsala cuando, por ejemplo, el jugador haya cambiado manualmente la configuración de calidad del juego. Esto vacía (es decir, sube) todos los datos asociados con parámetros anteriores.

Detalles
Parámetros
params
Son los parámetros codificados del búfer de protocolo.
Resultado que se muestra
Será TFERROR_OK si se pudieron establecer los parámetros.

TuningFork_setUploadCallback

TFErrorCode TuningFork_setUploadCallback(
  UploadCallback cbk
)

Configura una devolución de llamada para que tenga lugar en un subproceso independiente cada vez que Tuning Fork realice una carga.

Detalles
Parámetros
cbk
Resultado que se muestra
Será TFERROR_OK a menos que no se haya inicializado Tuning Fork.

TuningFork_startTrace

TFErrorCode TuningFork_startTrace(
  TFInstrumentKey key,
  TFTraceHandle *handle
)

Inicia un segmento de seguimiento.

Consulta también:las etiquetas de marca reservadas anteriores

Detalles
Parámetros
key
Es una etiqueta de marca.
Parámetros
handle
Si la operación es exitosa, se completa con un nuevo controlador.
Resultado que se muestra
Se mostrará TFERROR_INVALID_INSTRUMENT_KEY si la etiqueta de marca no es válida y TFERROR_OK si la operación fue exitosa.