Aggiungi funzioni di sincronizzazione dei frame

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

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

Diverse funzioni accettano serializzazioni di protocol buffer. Per saperne di più sull'utilizzo dei buffer di protocollo nel gioco, consulta Informazioni sui buffer di protocollo.

I parametri e i valori restituiti delle funzioni sono spiegati nelle intestazioni e nella documentazione di riferimento dell'API.

Funzioni del ciclo di vita di Android Performance Tuner

Utilizza le seguenti funzioni per controllare il ciclo di vita di un'istanza Tuning Fork.

Inizializza

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

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

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

I campi che compili settings determinano la modalità di inizializzazione della libreria.

/**
 * @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 trasmetti la funzione Swappy_injectTracer() (OpenGL, Vulkan) dall'API Frame Pacing all'inizializzazione, la libreria Tuning Fork registra automaticamente il tempo del frame senza che tu chiami esplicitamente le funzioni tick. Questa operazione viene eseguita 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();
   }
...
}

Distruggi

TFErrorCode TuningFork_destroy();

Puoi chiamare questa funzione all'arresto. Questa funzione tenta di inviare tutti i dati dell'istogramma attualmente archiviati per il caricamento successivo prima di deallocare la memoria utilizzata dalla libreria Tuning Fork.

Scarico

TFErrorCode TuningFork_flush();

Questa funzione svuota gli istogrammi registrati (ad esempio, quando il gioco viene inviato in background o in primo piano). Non svuota i dati se non è trascorso il periodo minimo di caricamento, che per impostazione predefinita è di un minuto, dall'ultimo caricamento.

Impostare i parametri di fedeltà

TFErrorCode TuningFork_setFidelityParameters(const CProtobufSerialization* params);

Questa funzione esegue l'override dei parametri di fedeltà correnti a cui sono associati i dati dei frame. Devi chiamare questa funzione quando un giocatore 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 spunta successivi. Restituisce TFERROR_INVALID_ANNOTATION se si è verificato un errore durante la decodifica dell'annotazione e TFERROR_OK se non si è verificato alcun errore.

Funzioni per frame

TFErrorCode TuningFork_frameTick(TFInstrumentKey key);

Questa funzione registra il tempo trascorso tra il tick precedente con il valore key e l'ora corrente nell'istogramma associato a key e all'annotazione corrente.

TFErrorCode TuningFork_frameDeltaTimeNanos(TFInstrumentKey key, TFDuration dt);

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

TFErrorCode TuningFork_startTrace(TFInstrumentKey key, TraceHandle* handle);

Questa funzione imposta un handle su un handle di traccia associato al key specificato.

TFErrorCode TuningFork_endTrace(TraceHandle handle);

Questa funzione registra l'intervallo di tempo trascorso dall'ultima chiamata TuningFork_startTrace() nell'istogramma associato a key utilizzato e all'annotazione corrente.

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

Chiama questa funzione dai metodi del ciclo di vita appropriati nell'attività principale del gioco, passando l'enum appropriato. Registrando gli eventi del ciclo di vita del gioco, APT è in grado di comprendere meglio quando il gioco potrebbe bloccarsi o quando gli utenti potrebbero abbandonarlo (ad esempio, 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 nell'APK con il nome file specificato. fidelityParams deve essere una serializzazione di un messaggio FidelityParams. Per maggiori informazioni, consulta la sezione Definire i livelli di qualità.

La proprietà della serializzazione viene passata al chiamante, che deve chiamare CProtobufSerialization_Free per deallocare la memoria mantenuta.

Scaricare i parametri di fedeltà su 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 riprova la richiesta finché non viene scaricato il parametro o si verifica un timeout. I parametri scaricati vengono memorizzati localmente. Quando l'app viene riavviata, utilizza questi parametri scaricati anziché quelli predefiniti.

Salvare ed eliminare i parametri di fedeltà memorizzati sul dispositivo

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

Questa funzione è necessaria solo in modalità esperto, in cui i parametri di fedeltà vengono scaricati da un server. Salva o elimina (se fidelity_params è null) i file archiviati localmente che vengono utilizzati quando il server non è raggiungibile.

Richieste web

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

• Viene effettuata una richiesta generateTuningParameters durante l'inizializzazione.
• Durante il gioco, viene effettuata periodicamente una richiesta uploadTelemetry per inviare dati al server.
• Gli APK di debug possono anche inviare richieste debugInfo, che informano un server di debug delle impostazioni, dei parametri di fedeltà predefiniti e della struttura dev_tuningfork.proto.

Giocatori offline

Se non è disponibile alcuna connessione all'inizializzazione, la richiesta viene ritentata più volte con un tempo di backoff crescente.

Se non è presente una connessione al momento del caricamento, quest'ultimo viene memorizzato nella cache. Puoi fornire il tuo meccanismo di memorizzazione nella cache passando un oggetto TFCache durante l'inizializzazione. Se non fornisci una cache, i caricamenti vengono memorizzati come file in uno spazio di archiviazione temporaneo.