O Google tem o compromisso de promover a igualdade racial para as comunidades negras. Saiba como.

Adicionar funções de tempo para a renderização do frame

Use as funções neste tópico para integrar a biblioteca Tuning Fork ao código do seu jogo.

O arquivo principal em include/tuningfork/tuningfork.h contém a interface principal da biblioteca Tuning Fork. O arquivo em include/tuningfork/tuningfork_extra.h contém funções de utilitário.

Diversas funções usam serializações de buffers de protocolo. Para saber mais sobre o uso de buffers de protocolo no jogo, consulte Sobre buffers de protocolo.

Parâmetros de função e valores de retorno são explicados nos cabeçalhos e na documentação da API de referência.

Funções do ciclo de vida

Use as seguintes funções para controlar o ciclo de vida de uma instância do Tuning Fork.

Initialize

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

Essa função precisa ser chamada uma vez na inicialização, normalmente a partir do código nativo executado pelo método onCreate() do app. Ela aloca os dados de que a biblioteca Tuning Fork precisa.

É necessário ter um arquivo tuningfork_settings.bin presente em assets/tuningfork no seu app, contendo as configurações de histograma e anotação. Para converter o arquivo de texto em binário, consulte Texto vs. representações binárias.

Os campos que você preenche nas settings determinam a forma como a biblioteca é inicializada.

/**
 * @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;
};

Se você transmitir a função Swappy_injectTracer() (OpenGL, Vulkan) da API Frame Pacing na inicialização, a biblioteca Tuning Fork registrará automaticamente o tempo para a renderização do frame, sem que você precise chamar explicitamente as funções de marcação. Isso é feito no app de demonstração:

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;
   }
...
}

Destroy

TFErrorCode TuningFork_destroy();

É possível chamar essa função ao desligar. Essa função tenta enviar todos os dados de histograma atualmente armazenados para upload posterior antes de desalocar qualquer memória usada pela biblioteca Tuning Fork.

Flush

TFErrorCode TuningFork_flush();

Essa função apaga os histogramas registrados (por exemplo, quando o jogo é enviado para o primeiro ou segundo plano). Os dados não serão apagados se o tempo de upload mínimo, um minuto por padrão, não tiver passado desde o upload anterior.

Definir parâmetros de fidelidade

TFErrorCode TuningFork_setFidelityParameters(const CProtobufSerialization* params);

Essa função substitui os parâmetros de fidelidade atuais a que os dados de frame estão associados. Chame essa função quando um jogador mudar manualmente as configurações de qualidade do jogo.

Anotações

TFErrorCode TuningFork_setCurrentAnnotation(const CProtobufSerialization* annotation);

Essa função define a anotação a ser associada a marcações posteriores. Ela retorna TFERROR_INVALID_ANNOTATION caso haja um erro na decodificação da anotação e TFERROR_OK caso não haja.

Funções por frame

TFErrorCode TuningFork_frameTick(TFInstrumentKey key);

Essa função registra o tempo entre a marcação anterior com a key especificada e o horário atual no histograma associado à key e à anotação atual.

TFErrorCode TuningFork_frameDeltaTimeNanos(TFInstrumentKey key, TFDuration dt);

Essa função registra a duração no histograma associado à key e à anotação atual.

TFErrorCode TuningFork_startTrace(TFInstrumentKey key, TraceHandle* handle);

Essa função define um identificador para um identificador de rastreamento associado à key determinada.

TFErrorCode TuningFork_endTrace(TraceHandle handle);

Essa função registra o intervalo de tempo desde a chamada TuningFork_startTrace() associada no histograma associado à key usada e à anotação atual.

Funções avançadas

As seguintes funções estão disponíveis em tuningfork_extra.h.

Encontrar e carregar arquivos em um APK

TFErrorCode TuningFork_findFidelityParamsInApk(JNIEnv* env, jobject context, const char* filename, CProtobufSerialization* fidelityParams);

Essa função carrega fidelityParams do diretório assets/tuningfork no APK com o nome de arquivo fornecido. fidelityParams precisa ser uma serialização de uma mensagem FidelityParams. Para ver mais informações, consulte Definir níveis de qualidade.

A propriedade da serialização é passada ao autor da chamada, que precisa chamar CProtobufSerialization_Free para desalocar qualquer memória.

Fazer o download de parâmetros de fidelidade em uma linha de execução separada

void TuningFork_startFidelityParamDownloadThread(const CProtobufSerialization* defaultParams, ProtoCallback fidelity_params_callback);

Ativa uma linha de execução de download para recuperar os parâmetros de fidelidade. A linha de execução tenta fazer a solicitação novamente, até que o download dos parâmetros seja concluído ou o tempo limite seja atingido. Os parâmetros salvos são armazenados localmente. Quando o app é reiniciado, ele usa esses parâmetros salvos em vez dos parâmetros padrão.

Salvar e excluir os parâmetros de fidelidade armazenados no dispositivo

TFErrorCode TuningFork_saveOrDeleteFidelityParamsFile(JNIEnv* env, jobject context, const CProtobufSerialization* fidelity_params);

Essa função só é necessária no modo Especialista, em que o download dos parâmetros de fidelidade é feito a partir de um servidor. Ela salva ou exclui (se fidelity_params for nulo) os arquivos armazenados localmente que são usados quando o servidor está inacessível.

Solicitações da Web

A biblioteca faz os seguintes tipos de solicitações para o endpoint do servidor:

  • Uma solicitação generateTuningParameters é feita na inicialização.
  • Durante o jogo, uma solicitação uploadTelemetry é feita periodicamente para enviar dados ao servidor.
  • Os APKs de depuração também podem enviar solicitações debugInfo, que informam as configurações, os parâmetros de fidelidade padrão e a estrutura dev_tuningfork.proto ao servidor de depuração.

Jogadores off-line

Caso não haja uma conexão disponível na inicialização, a solicitação é repetida várias vezes, com um tempo de espera crescente.

Se não houver conexão durante o upload, ele será armazenado em cache. Você pode fornecer seu próprio mecanismo de armazenamento em cache transmitindo um objeto TFCache na inicialização. Se você não fornecer seu próprio cache, os uploads serão armazenados como arquivos no armazenamento temporário.