Interface principal do Tuning Fork

Principal interface para usar o Tuning Fork.

Resumo

Enumerações

InstrumentKeys{
  TFTICK_RAW_FRAME_TIME = 64000,
  TFTICK_PACED_FRAME_TIME = 64001,
  TFTICK_CPU_TIME = 64002,
  TFTICK_GPU_TIME = 64003
}
enum
Chaves de instrumento que indicam períodos em um 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
Todos os códigos de erro que podem ser retornados pelas funções do Tuning Fork.

Typedefs

ProtoCallback)(const CProtobufSerialization *) typedef
void(*
Ponteiro para uma função que pode ser anexada a TFSettings::fidelity_params_callback.
SwappyTracerFn)(const SwappyTracer *) typedef
void(*
Ponteiro para Swapppy_injectTracers que pode ser anexado a TFSettings::swappy_tracer_fn.
TFDuration typedef
uint64_t
Duração em nanossegundos.
TFInstrumentKey typedef
uint16_t
Chave de instrumentação que identifica um ponto de marcação dentro de um frame ou segmento de rastreamento.
TFTimePoint typedef
uint64_t
Tempo em milissegundos após o período.
TFTraceHandle typedef
uint64_t
Identificador de rastreamento usado em TuningFork_startTrace.
UploadCallback)(const char *, size_t n) typedef
void(*
Ponteiro para uma função que pode ser transmitida para TuningFork_setUploadCallback.

Funções

CProtobufSerialization_Free(CProtobufSerialization *ser)
void
Desaloca qualquer memória de propriedade da serialização do buffer de protocolo.
TuningFork_destroy()
Limpa toda a memória pertencente ao Tuning Fork e elimina todas as linhas de execução.
TuningFork_enableMemoryRecording(bool enable)
Ativa ou desativa a gravação de telemetria de memória.
TuningFork_endTrace(TFTraceHandle handle)
Interrompe e registra um segmento de rastreamento.
TuningFork_flush()
Força o upload dos histogramas atuais.
TuningFork_frameDeltaTimeNanos(TFInstrumentKey key, TFDuration dt)
Grava uma marcação de frame usando a hora externa, em vez da hora do sistema.
TuningFork_frameTick(TFInstrumentKey key)
Registra uma marcação de frame que será associada à chave de instrumentação e à anotação atual.
TuningFork_getFidelityParameters(const CProtobufSerialization *defaultParams, CProtobufSerialization *params, uint32_t timeout_ms)
Chamada de bloqueio para receber parâmetros de fidelidade do servidor.
TuningFork_init(const TFSettings *settings, JNIEnv *env, jobject context)
Inicializa o Tuning Fork.
TuningFork_setCurrentAnnotation(const CProtobufSerialization *annotation)
Define a anotação atual.
TuningFork_setFidelityParameters(const CProtobufSerialization *params)
Define os parâmetros de fidelidade ativos no momento.
TuningFork_setUploadCallback(UploadCallback cbk)
Define um callback a ser chamado em uma linha de execução separada sempre que o TuningFork fizer um upload.
TuningFork_startTrace(TFInstrumentKey key, TFTraceHandle *handle)
Inicia um segmento de rastreamento.

Estruturas

CProtobufSerialization

Série de bytes que representa um buffer de protocolo serializado.

TFSettings

Configurações de inicialização zero para qualquer valor que não esteja sendo usado.

Enumerações

InstrumentKeys

 InstrumentKeys

Chaves de instrumento que indicam períodos em um frame.

As chaves 64000-65535 são reservadas

Propriedades
TFTICK_CPU_TIME

Tempo entre o início do frame e a chamada para Swappy_swap.

TFTICK_GPU_TIME

Tempo entre a troca de buffers e o acionamento de limite da GPU.

TFTICK_PACED_FRAME_TIME

Tempo para a renderização do frame entre as extremidades das chamadas de eglSwapBuffers ou da fila Vulkan presente.

TFTICK_RAW_FRAME_TIME

Se a hora da GPU estiver disponível, será MAX(CPU_TIME,GPU_TIME). Caso contrário, será igual a PACED_FRAME_TIME.

TFErrorCode

 TFErrorCode

Todos os códigos de erro que podem ser retornados pelas funções do Tuning Fork.

Propriedades
TFERROR_ALREADY_INITIALIZED

TuningFork_init foi chamado mais de uma vez.

TFERROR_B64_ENCODE_FAILED

Não foi possível codificar uma protobuf.

TFERROR_BAD_FILE_OPERATION

Erro geral do arquivo.

TFERROR_BAD_PARAMETER

Parâmetro genérico inválido.

TFERROR_BAD_SETTINGS

O arquivo tuningfork_settings.bin não é válido.

TFERROR_COULDNT_SAVE_OR_DELETE_FPS

Erro ao chamar TuningFork_saveOrDeleteFidelityParamsFile.

TFERROR_DOWNLOAD_THREAD_ALREADY_STARTED

TuningFork_startFidelityParamDownloadThread foi chamado mais de uma vez ou chamado quando o TuningFork_init já havia iniciado o download.

TFERROR_GENERATE_TUNING_PARAMETERS_ERROR

Ocorreu um erro ao analisar a resposta para generateTuningParameters.

TFERROR_GENERATE_TUNING_PARAMETERS_RESPONSE_NOT_SUCCESS

A resposta de generateTuningParameters não era um código correto.

TFERROR_INVALID_ANNOTATION

Parâmetro inválido para TuningFork_setCurrentAnnotation.

TFERROR_INVALID_DEFAULT_FIDELITY_PARAMS

fpDefaultFileNum está fora do intervalo.

TFERROR_INVALID_INSTRUMENT_KEY

Chave de instrumento inválida transmitida para uma função de marcação.

TFERROR_INVALID_TRACE_HANDLE

Identificador inválido transmitido para TuningFork_endTrace.

TFERROR_JNI_BAD_ENV

Erro jni: obsoleto.

TFERROR_JNI_BAD_JVM

Erro jni: obsoleto.

TFERROR_JNI_BAD_THREAD

Erro jni: obsoleto.

TFERROR_JNI_BAD_VERSION

Erro jni: obsoleto.

TFERROR_JNI_EXCEPTION

Erro jni: uma exceção foi lançada. Veja a saída do logcat.

TFERROR_NO_CLEARCUT

Obsoleto.

TFERROR_NO_FIDELITY_PARAMS

Nenhum parâmetro de fidelidade foi encontrado na inicialização.

TFERROR_NO_FIDELITY_PARAMS_IN_APK

Nenhum dev_tuningfork_fidelityparams_#.bin foi encontrado em assets/tuningfork.

TFERROR_NO_SETTINGS

Nenhum tuningfork_settings.bin foi encontrado em assets/tuningfork.

TFERROR_NO_SETTINGS_ANNOTATION_ENUM_SIZES

Parte ausente de tuningfork_settings.bin.

TFERROR_NO_SUCH_KEY

Essa chave não é válida para acessar o cache de arquivos.

TFERROR_NO_SWAPPY

Não foi possível encontrar as funções do Swappy necessárias.

TFERROR_OK

Nenhum erro.

TFERROR_PLATFORM_NOT_SUPPORTED

O jogo ou app é executado em uma plataforma que não é compatível com o Tuning Fork.

Usado apenas pelo plug-in do Unity.

TFERROR_PREVIOUS_UPLOAD_PENDING

Não é possível fazer upload porque outra solicitação está pendente.

TFERROR_TIMEOUT

Tempo limite em solicitação de parâmetros de fidelidade.

TFERROR_TUNINGFORK_NOT_INITIALIZED

Foi realizada uma chamada antes da inicialização do Tuning Fork.

TFERROR_UPLOAD_TOO_FREQUENT

Chamadas muito frequentes para TuningFork_flush.

Typedefs

ProtoCallback

void(* ProtoCallback)(const CProtobufSerialization *)

Ponteiro para uma função que pode ser anexada a TFSettings::fidelity_params_callback.

Função que será chamada com os parâmetros de fidelidade salvos. Consulte também:TFSettings

SwappyTracerFn

void(* SwappyTracerFn)(const SwappyTracer *)

Ponteiro para Swapppy_injectTracers que pode ser anexado a TFSettings::swappy_tracer_fn.

Consulte também: TFSettings

TFDuration

uint64_t TFDuration

Duração em nanossegundos.

TFInstrumentKey

uint16_t TFInstrumentKey

Chave de instrumentação que identifica um ponto de marcação dentro de um frame ou segmento de rastreamento.

TFTimePoint

uint64_t TFTimePoint

Tempo em milissegundos após o período.

TFTraceHandle

uint64_t TFTraceHandle

Identificador de rastreamento usado em TuningFork_startTrace.

UploadCallback

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

Ponteiro para uma função que pode ser transmitida para TuningFork_setUploadCallback.

Função que será chamada em uma linha de execução separada sempre que o Tuning Fork fizer um upload. Consulte também:TFSettings

Funções

CProtobufSerialization_Free

void CProtobufSerialization_Free(
  CProtobufSerialization *ser
)

Desaloca qualquer memória de propriedade da serialização do buffer de protocolo.

Detalhes
Parâmetros
ser
Serialização do buffer de protocolo

TuningFork_destroy

TFErrorCode TuningFork_destroy()

Limpa toda a memória pertencente ao Tuning Fork e elimina todas as linhas de execução.

Detalhes
Retornos
TFERROR_OK, a menos que o Tuning Fork não tenha sido inicializado.

TuningFork_enableMemoryRecording

TFErrorCode TuningFork_enableMemoryRecording(
  bool enable
)

Ativa ou desativa a gravação de telemetria de memória.

Por padrão, a gravação de telemetria de memória é ativada na inicialização.

Detalhes
Parâmetros
enable
Se "true", a gravação de memória será ativada. Se "false", ela será desativada.
Retornos
TFERROR_OK, a menos que o Tuning Fork não tenha sido inicializado.

TuningFork_endTrace

TFErrorCode TuningFork_endTrace(
  TFTraceHandle handle
)

Interrompe e registra um segmento de rastreamento.

Detalhes
Parâmetros
handle
identificador anteriormente retornado por TuneingFork_startTrace
Retornos
TFERROR_INVALID_TRACE_HANDLE se o identificador for inválido. TFERROR_OK caso a operação seja concluída.

TuningFork_flush

TFErrorCode TuningFork_flush()

Força o upload dos histogramas atuais.

Detalhes
Retornos
TFERROR_OK se for possível iniciar o upload. TFERROR_PREVIOUS_UPLOAD_PENDING se houver um upload anterior bloqueando o atual. TFERROR_UPLOAD_TOO_FREQUENT se menos de um minuto tiver passado desde o upload anterior.

TuningFork_frameDeltaTimeNanos

TFErrorCode TuningFork_frameDeltaTimeNanos(
  TFInstrumentKey key,
  TFDuration dt
)

Grava uma marcação de frame usando a hora externa, em vez da hora do sistema.

Consulte também: as chaves de instrumento reservadas acima

Detalhes
Parâmetros
key
uma chave de instrumento
Parâmetros
dt
a duração que você quer gravar (em nanossegundos)
Retornos
TFERROR_INVALID_INSTRUMENT_KEY se a chave de instrumento for inválida. TFERROR_OK caso a operação seja concluída.

TuningFork_frameTick

TFErrorCode TuningFork_frameTick(
  TFInstrumentKey key
)

Registra uma marcação de frame que será associada à chave de instrumentação e à anotação atual.

NB: é possível chamar as funções de rastreamento ou marcação em diferentes linhas de execução. Contudo, uma única chave de instrumento precisa ser sempre marcada a partir da mesma linha de execução. Consulte também: as chaves de instrumento reservadas acima

Detalhes
Parâmetros
key
uma chave de instrumento
Retornos
TFERROR_INVALID_INSTRUMENT_KEY se a chave de instrumento for inválida. TFERROR_OK caso a operação seja concluída.

TuningFork_getFidelityParameters

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

Chamada de bloqueio para receber parâmetros de fidelidade do servidor.

Você não precisará chamar isso se transmitir um fidelity_params_callback como parte das configurações do TuningFork_init. Após o download dos parâmetros de fidelidade, todas as informações de tempo são registradas como associadas a esses parâmetros. Se você chamar GetFidelityParameters posteriormente e o download de um novo conjunto de parâmetros for realizado, todos os dados que já foram coletados serão enviados ao back-end. A propriedade de "params" é transferida para o autor da chamada. Portanto, ele precisa chamar params->dealloc quando terminar de usá-la. A solicitação de parâmetro é enviada para: ${url_base}+'applications/'+package_name+'/apks/'+version_number+':generateTuningParameters'.

Detalhes
Parâmetros
defaultParams
serão considerados atuais se não for possível fazer o download de nenhum parâmetro.
params
timeout_ms
tempo de espera antes de retornar essa chamada quando não for possível estabelecer uma conexão. Se zero ou negativo, o valor em Settings.initial_request_timeout_ms será usado.
Retornos
TFERROR_TIMEOUT se o tempo limite acabar antes do download dos parâmetros. TFERROR_OK caso a operação seja concluída.

TuningFork_init

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

Inicializa o Tuning Fork.

Deve ser chamado antes de qualquer outra função.

A biblioteca carregará as configurações de histograma e anotação do arquivo tuningfork_settings.bin. Consulte também: TFSettings para ver a semântica de como outras configurações mudam o comportamento de inicialização.

Detalhes
Parâmetros
settings
uma estrutura TFSettings
env
um JNIEnv
context
o contexto do app
Retornos
TFERROR_OK se a operação ocorrer corretamente, TFERROR_NO_SETTINGS se nenhuma configuração for encontrada, TFERROR_BAD_SETTINGS se o arquivo tuningfork_settings.bin for inválido ou TFERROR_ALREADY_INITIALIZED se o tuningfork já tiver sido inicializado.

TuningFork_setCurrentAnnotation

TFErrorCode TuningFork_setCurrentAnnotation(
  const CProtobufSerialization *annotation
)

Define a anotação atual.

Detalhes
Parâmetros
annotation
serialização da protobuf da anotação atual.
Retornos
TFERROR_INVALID_ANNOTATION, caso a anotação esteja inconsistente com as configurações.
Retornos
TFERROR_OK caso a operação seja concluída.

TuningFork_setFidelityParameters

TFErrorCode TuningFork_setFidelityParameters(
  const CProtobufSerialization *params
)

Define os parâmetros de fidelidade ativos no momento.

Essa função substitui todos os parâmetros transferidos por download no modo de experimento. Use quando o jogador mudar manualmente as configurações de qualidade do jogo, por exemplo. Isso limpa (ou seja, faz upload de) todos os dados associados a qualquer parâmetro anterior.

Detalhes
Parâmetros
params
Parâmetros codificados para buffer de protocolo.
Retornos
TFERROR_OK se foi possível definir os parâmetros.

TuningFork_setUploadCallback

TFErrorCode TuningFork_setUploadCallback(
  UploadCallback cbk
)

Define um callback a ser chamado em uma linha de execução separada sempre que o TuningFork fizer um upload.

Detalhes
Parâmetros
cbk
Retornos
TFERROR_OK, a menos que o Tuning Fork não tenha sido inicializado.

TuningFork_startTrace

TFErrorCode TuningFork_startTrace(
  TFInstrumentKey key,
  TFTraceHandle *handle
)

Inicia um segmento de rastreamento.

Consulte também: as chaves de instrumento reservadas acima

Detalhes
Parâmetros
key
uma chave de instrumento
Parâmetros
handle
será preenchido com um novo identificador se for possível concluir a operação.
Retornos
TFERROR_INVALID_INSTRUMENT_KEY se a chave de instrumento for inválida. TFERROR_OK caso a operação seja concluída.