Usa le funzioni in questo argomento per integrare la raccolta di diapason nel codice del gioco.
Il file di intestazione in include/tuningfork/tuningfork.h
contiene l'interfaccia di base
per la libreria di Tuning Fork. Il file in include/tuningfork/tuningfork_extra.h
contiene funzioni di utilità.
Diverse funzioni prendono la serializzazione dei buffer di protocollo. Per scoprire di più sull'utilizzo dei buffer di protocollo all'interno del gioco, consulta Informazioni sui buffer di protocollo.
I parametri delle funzioni e i valori restituiti sono illustrati nelle intestazioni e nella documentazione relativa all'API di riferimento.
Funzioni del ciclo di vita di Android Performance Tuner
Utilizza le seguenti funzioni per controllare il ciclo di vita di un'istanza di Tuning Fork.
Inizializza
TFErrorCode TuningFork_init(const TFSettings* settings, JNIEnv* env, jobject
context);
Devi chiamare questa funzione una volta all'avvio, in genere dall'interno del codice nativo eseguito dal metodo onCreate()
dell'app. Alloca i dati necessari
dalla libreria Tuning Fork.
All'interno dell'app deve essere presente un file tuningfork_settings.bin
, che contiene l'istogramma e le impostazioni di annotazione.assets/tuningfork
Per convertire il file di testo in binario, consulta Confronto tra rappresentazioni di testo e binari.
I campi che compili settings
determinano il modo in cui la libreria si inizializza automaticamente.
/**
* @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)
dell'API Frame Pacing al momento dell'inizializzazione, la libreria Tuning Fork registra automaticamente la durata frame senza che tu chiami esplicitamente
le funzioni di spunta. 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();
}
...
}
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 di individuare la memoria utilizzata dalla libreria di Tuning Fork.
Flush
TFErrorCode TuningFork_flush();
Questa funzione elimina gli istogrammi registrati (ad esempio quando il gioco viene inviato in background o in primo piano). I dati non vengono eliminati se il periodo di caricamento minimo, con un valore predefinito di un minuto, non è trascorso dal caricamento precedente.
Imposta parametri di fedeltà
TFErrorCode TuningFork_setFidelityParameters(const CProtobufSerialization*
params);
Questa funzione sostituisce gli attuali parametri di fedeltà a cui sono associati i dati del frame. Dovresti chiamare questa funzione quando un giocatore modifica manualmente le impostazioni della qualità del gioco.
Annotazioni
TFErrorCode TuningFork_setCurrentAnnotation(const CProtobufSerialization*
annotation);
Questa funzione imposta l'annotazione da associare ai segni di graduazione 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 tra il segno di spunta precedente con il valore key
specificato
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
nell'annotazione corrente.
TFErrorCode TuningFork_startTrace(TFInstrumentKey key, TraceHandle* handle);
Questa funzione imposta un handle su un handle di traccia associato al valore key
specificato.
TFErrorCode TuningFork_endTrace(TraceHandle handle);
Questa funzione registra l'intervallo di tempo a partire dalla chiamata di TuningFork_startTrace()
associata nell'istogramma associato all'elemento key
che è stato utilizzato e all'annotazione corrente.
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 appropriati del ciclo di vita nell'Attività principale del tuo gioco, passando l'enum appropriato. Registrando gli eventi del ciclo di vita del gioco, APT è meglio in grado di capire quando il tuo gioco potrebbe arrestarsi in modo anomalo o quando gli utenti potrebbero uscire (ad esempio durante eventi di caricamento lunghi).
Funzioni avanzate
In tuningfork_extra.h
sono disponibili le seguenti funzioni.
Trovare e caricare file in un APK
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 ulteriori informazioni, consulta
Definire i livelli qualitativi.
La proprietà della serializzazione viene passata al chiamante, che deve chiamare
CProtobufSerialization_Free
per distribuire la memoria memorizzata.
Scarica i parametri di fedeltà in un thread separato
Attiva un thread di download per recuperare i parametri di fedeltà. Il thread riprova la richiesta fino al download dei parametri o fino a un timeout. I parametri scaricati vengono archiviati localmente. Al riavvio, l'app utilizza questi parametri scaricati anziché quelli predefiniti.
Salva ed elimina i parametri di fedeltà memorizzati sul dispositivo
Questa funzione è necessaria solo in modalità Esperto, in cui i parametri di fedeltà vengono scaricati da un server. Salva o elimina (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:
- Viene effettuata una richiesta
generateTuningParameters
al momento dell'inizializzazione. - Durante il gameplay, 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 strutturadev_tuningfork.proto
.
Player offline
Se non è disponibile una connessione al momento dell'inizializzazione, la richiesta viene riprovata più volte con un tempo di backoff crescente.
Se non esiste una connessione al momento del caricamento, il caricamento viene memorizzato nella cache. Puoi fornire il tuo meccanismo di memorizzazione nella cache passando un oggetto TFCache
al momento dell'inizializzazione. Se non fornisci la tua cache, i caricamenti vengono archiviati come file nello spazio di archiviazione temporaneo.