Aggiungi funzioni di sincronizzazione dei frame

Usa le funzioni in questo argomento per integrare la libreria Tuning Fork nel codice del gioco.

Il file di intestazione all'indirizzo include/tuningfork/tuningfork.h contiene l'interfaccia principale per la libreria Tuning Fork. Il file all'indirizzo include/tuningfork/tuningfork_extra.h contiene funzioni di utilità.

Diverse funzioni prendono la serializzazione dei buffer di protocollo. Per ulteriori informazioni sull'utilizzo buffer di protocollo all'interno del gioco, consulta Informazioni sui buffer di protocollo.

I parametri delle funzioni e i valori restituiti sono descritti nelle intestazioni e documentazione relativa all'API di riferimento.

Funzioni del ciclo di vita di Android Performance Tuner

Usa le seguenti funzioni per controllare il ciclo di vita di un diapason in esecuzione in un'istanza Compute Engine.

Inizializza

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

Devi chiamare questa funzione una volta all'avvio, in genere all'interno del codice nativo eseguiti dal metodo onCreate() dell'app. Alloca i dati necessari nella libreria di Tuning Fork.

Devi avere un file tuningfork_settings.bin presente in assets/tuningfork all'interno dell'app, che contiene le impostazioni di istogramma e annotazione. A convertire il file di testo in binario, vedi Rappresentazioni di testo e binarie.

I campi da compilare settings determinano il modo in cui la libreria viene inizializzata.

/**
 * @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 passi la funzione Swappy_injectTracer() (OpenGL, Vulkan) dall'API Frame Pacing durante l'inizializzazione, la libreria Tuning Fork registra automaticamente la durata frame senza che tu chiami esplicitamente il segno di spunta autonomamente le funzioni. Puoi farlo nell'app demo:

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

Elimina

TFErrorCode TuningFork_destroy();

Puoi chiamare questa funzione all'arresto. Questa funzione tenta di inviare tutti i dati degli istogrammi attualmente archiviati per caricarli in un secondo momento prima del deallocare usata dalla libreria Tuning Fork.

Plafoniera

TFErrorCode TuningFork_flush();

Questa funzione scarica gli istogrammi registrati (ad esempio, quando il gioco viene inviati in background o in primo piano). Non esegue il flush dei dati se il minimo di caricamento, che per impostazione predefinita è di un minuto, non è trascorso dal un caricamento precedente.

Imposta parametri di fedeltà

TFErrorCode TuningFork_setFidelityParameters(const CProtobufSerialization* params);

Questa funzione sostituisce gli attuali parametri di fedeltà con cui i dati del frame vengono associati. Devi richiamare questa funzione quando un player modifica manualmente le impostazioni di qualità del gioco.

Annotazioni

TFErrorCode TuningFork_setCurrentAnnotation(const CProtobufSerialization* annotation);

Questa funzione imposta l'annotazione da associare ai segni di graduazione successivi. Ritorna TFERROR_INVALID_ANNOTATION se si è verificato un errore durante la decodifica dell'annotazione e TFERROR_OK se non ci sono errori.

Funzioni per frame

TFErrorCode TuningFork_frameTick(TFInstrumentKey key);

Questa funzione registra il tempo che intercorre tra il segno di spunta precedente con il valore key specificato e l'ora corrente nell'istogramma associato a key e la annotazione.

TFErrorCode TuningFork_frameDeltaTimeNanos(TFInstrumentKey key, TFDuration dt);

Questa funzione registra la durata nell'istogramma associato a key e la annotazione corrente.

TFErrorCode TuningFork_startTrace(TFInstrumentKey key, TraceHandle* handle);

Questa funzione imposta un handle su un handle di traccia associato all'oggetto key specificato.

TFErrorCode TuningFork_endTrace(TraceHandle handle);

Questa funzione registra l'intervallo di tempo a partire dall'intervallo TuningFork_startTrace() nell'istogramma associato a key utilizzato e alla annotazione.

Funzioni del ciclo di vita delle 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);

Richiama questa funzione dai metodi del ciclo di vita appropriati nel tuo L'Attività principale del gioco, superato l'enumerazione appropriata. Registrando gli eventi del ciclo di vita del gioco, APT è migliore in grado di capire quando il gioco potrebbe arrestarsi in modo anomalo o quando gli utenti potrebbero uscire (ad es. durante eventi di caricamento lunghi).

Funzioni avanzate

Le seguenti funzioni sono disponibili in tuningfork_extra.h.

Trovare e caricare file in un APK

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

Questa funzione carica fidelityParams dalla directory assets/tuningfork in l'APK con il nome file specificato. fidelityParams deve essere una serializzazione di un FidelityParams messaggio. Per ulteriori informazioni, vedi Definisci i livelli qualitativi.

La proprietà della serializzazione viene passata al chiamante, che deve chiamare CProtobufSerialization_Free per deallocizzare eventuali ricordi trattenuti.

Scarica i parametri di fedeltà in un thread separato

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

Attiva un thread di download per recuperare i parametri di fedeltà. Il thread ritenta richiesta fino al download dei parametri o fino al timeout. I parametri scaricati sono archiviati localmente. Quando viene riavviata, l'app utilizza questi parametri scaricati anziché quelli predefiniti.

Salva ed elimina i parametri di fedeltà memorizzati sul dispositivo

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

Questa funzione è necessaria solo nella modalità esperto in cui i parametri di fedeltà sono scaricate da un server. Viene salvato o eliminato (se fidelity_params è nullo) i file archiviati localmente utilizzati quando il server non è raggiungibile.

Richieste web

La libreria effettua i seguenti tipi di richieste all'endpoint del server:

• Al momento dell'inizializzazione viene effettuata una richiesta generateTuningParameters.
• Durante il gameplay, viene effettuata periodicamente una richiesta uploadTelemetry per l'invio al server.
• Gli APK di debug possono anche inviare richieste debugInfo, che informano un server di debug delle impostazioni, i parametri di fedeltà predefiniti e dev_tuningfork.proto alla struttura del centro di costo.

Player offline

Se non è disponibile alcuna connessione all'inizializzazione, viene effettuato un nuovo tentativo della richiesta. più volte con un tempo di backoff crescente.

Se non c'è alcuna connessione al momento del caricamento, il caricamento viene memorizzato nella cache. Puoi fornire il tuo il proprio meccanismo di memorizzazione nella cache, passando TFCache durante l'inizializzazione. Se non fornisci la tua cache, i caricamenti vengono archiviati come file nello spazio di archiviazione temporaneo.