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 central da biblioteca Tuning Fork. O arquivo em include/tuningfork/tuningfork_extra.h contém funções utilitárias.

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 do Android Performance Tuner

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 pelo 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 com as configurações de histograma e anotação em assets/tuningfork no seu app. 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;
  /**
   * A null-terminated UTF-8 string containing the endpoint that Tuning Fork
   * will connect to for parameter, upload, and debug requests. This overrides
   * the value in base_uri in the settings proto and is intended for debugging
   * purposes only.
   */
  const char* endpoint_uri_override;
  /**
   * The version of Swappy that swappy_tracer_fn comes from.
   */
  uint32_t swappy_version;
  /**
   * The number of each metric that is allowed to be allocated at any given
   * time. If any element is zero, the default for that metric type is used.
   * Memory for all metrics is allocated up-front at initialization. When all
   * metrics of a given type are allocated, further requested metrics are not
   * added and data is lost.
   */
  TuningFork_MetricLimits max_num_metrics;
};

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;
       settings.swappy_version = Swappy_version();
   }
...
}

Observação: é essencial definir a versão do Swappy que você está usando no campo swappy_version de TFSettings. Isso garante que o TuningFork possa interpretar os dados retornados pelos callbacks do Swappy.

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 handle para um handle 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 do ciclo de vida do app

typedef enum TuningFork_LifecycleState {
    TUNINGFORK_STATE_UNINITIALIZED = 0,
    TUNINGFORK_STATE_ONCREATE = 1,
    TUNINGFORK_STATE_ONSTART = 2,
    TUNINGFORK_STATE_ONSTOP = 3,
    TUNINGFORK_STATE_ONDESTROY = 4,
} TuningFork_LifecycleState;

TFErrorCode TuningFork_reportLifecycleEvent(TuningForkLifecycleState state);

Chame essa função nos métodos de ciclo de vida corretos na atividade principal do jogo, transmitindo o tipo enumerado adequado. Ao registrar os eventos de ciclo de vida do jogo, o APT pode reconhecer melhor quando o jogo pode estar apresentando falhas ou quando os usuários estão saindo (por exemplo, durante eventos de carregamento longo).

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