Panoramica di Android Performance Tuner (nativo)

Questo documento descrive come integrare Android Performance Tuner, noto anche come libreria Tuning Fork, per registrare e caricare i dati sulla durata frame dai motori grafici nativi (C e C++).

Per il motore grafico Unity, consulta la guida per Unity.

Sfondo

Un componente chiave dell'esperienza di gioco sono le prestazioni di rendering. Le prestazioni di rendering sono il risultato dei seguenti due input:

  • Frequenza fotogrammi: la frequenza con cui viene disegnato un fotogramma.
  • Impostazioni di qualità grafica: livello di fedeltà con cui viene presentato un frame, inclusa la fedeltà della simulazione e della grafica.

Per i giochi, le buone prestazioni di rendering sono definite come segue:

  • Fornire una frequenza fotogrammi stabile e coerente (ovvero la percentuale di fotogrammi visualizzati alla frequenza desiderata).
  • Rendering dei frame alla frequenza più alta possibile mantenendo la stabilità, in genere 30 o 60 f/s a seconda del tipo di gioco.
  • Massimizzare il livello di dettaglio per un utente in base alle dimensioni e alla densità dello schermo, raggiungendo al contempo una frequenza fotogrammi stabile e desiderata.

La libreria Android Frame Pacing limita gran parte della variazione delle durate frame, fornendo una frequenza fotogrammi stabile per i giochi. La variazione rimanente nelle durate frame è dovuta al livello di dettaglio visualizzato durante determinate scene del gameplay e alle funzionalità grafiche del dispositivo. Utilizzando Android Performance Tuner, puoi individuare i momenti durante il gameplay in cui la durata frame è più lenta o più veloce del target e correlare questi problemi e opportunità a:

  • Impostazioni di qualità specifiche
  • Scene specifiche del gioco
  • Modelli di dispositivi o specifiche dei dispositivi specifici

Registra e carica i dati

La libreria Tuning Fork si basa su una delle sue funzioni tick chiamate per ogni frame dalla libreria Android Frame Pacing. All'interno della libreria, queste informazioni sui tick vengono aggregate in istogrammi che vengono poi caricati periodicamente su Google Play tramite un endpoint HTTP. Ogni tick viene registrato come associato a una chiave di instrumentazione e a un'annotazione, le cui definizioni vengono specificate in un file di buffer di protocollo.

Chiavi di instrumentazione

Una chiave di instrumentazione indica da dove proviene il tick nel frame ed è un numero intero che deve essere passato a ogni chiamata di funzione tick. La libreria Android Frame Pacing utilizza un insieme predefinito di chiavi di instrumentazione, definite in swappy_common.h. Puoi anche definire le tue chiavi di instrumentazione se non utilizzi la libreria Frame Pacing.

Annotazioni

Le annotazioni forniscono informazioni contestuali su ciò che sta facendo il gioco quando viene registrato un tick. Ad esempio, un'annotazione potrebbe identificare uno dei seguenti elementi:

  • Il livello di gioco attuale
  • Sullo schermo è presente un "boss"
  • Qualsiasi altra informazione pertinente sullo stato del gioco

Le annotazioni sono definite dal messaggio del buffer di protocollo com.google.tuningfork.Annotation. Per impostare l'annotazione corrente, passi una serializzazione del messaggio che hai definito a TuningFork_setCurrentAnnotation. Tutti i dati dei tick successivi vengono quindi associati a questa annotazione finché non ne viene impostata un'altra. Di seguito è riportato un esempio di definizione proto per le annotazioni:

import "tuningfork.proto"
enum Level {
  INVALID_LEVEL = 0;
  Level_1 = 1;
  Level_2 = 2;
  Level_3 = 3;
}
message Annotation {
  optional Level level = 1;
}

Parametri di fedeltà

I parametri di fedeltà influiscono sulle prestazioni e sulla fedeltà grafica del tuo gioco, ad esempio il livello di dettaglio della mesh, la risoluzione delle texture e il metodo di anti-aliasing. Come le annotazioni, i parametri di fedeltà vengono definiti utilizzando il messaggio del buffer di protocollo com.google.tuningfork.FidelityParams. Di seguito è riportato un esempio di definizione proto per i parametri di fedeltà:

import "tuningfork.proto"
message FidelityParams {
  int32 texture_quality_level = 1;
  int32 shadow_resolution = 2;
  float terrain_details_percent = 3;
  int32 post_processing_effects_level = 4;
}

Durante l'inizializzazione di Tuning Fork, passi una serializzazione dei parametri utilizzati dal gioco. Puoi modificare questi parametri se, ad esempio, l'utente modifica le impostazioni di rendering del gioco e i dati caricati successivamente vengono associati ai nuovi parametri.

Affinché Google Play possa comprendere le annotazioni e i parametri di fedeltà che definisci, il file del buffer di protocollo contenente queste definizioni deve essere incluso nell'APK del gioco, insieme alle impostazioni di inizializzazione. Devi anche fornire valori predefiniti per le combinazioni di parametri di fedeltà comuni nell'APK per fare in modo che i dati vengano segmentati in base a questi valori nell'interfaccia utente di Google Play. Per ulteriori informazioni, vedi Definisci i livelli di qualità.

Overhead di memoria e CPU

Tutta la memoria utilizzata dalla libreria Tuning Fork viene allocata durante l'inizializzazione per evitare sorprese durante il gameplay. La dimensione dei dati dipende dal numero di chiavi di instrumentazione, dal numero di possibili annotazioni e dal numero di bucket in ogni istogramma; è un multiplo di tutti questi valori per quattro byte per ogni bucket. Esistono anche due copie di tutti gli istogrammi per consentire l'invio in modalità con doppio buffer.

L'invio avviene su un thread separato e non blocca le chiamate tick. Se non è disponibile una connessione per il caricamento, l'invio viene messo in coda per il caricamento successivo.

L'overhead di elaborazione per la chiamata di una funzione tick è minimo: calcola semplicemente un indice nell'array di bucket dell'istogramma e incrementa un conteggio di numeri interi.

Integra la libreria Tuning Fork

Questa guida all'integrazione è divisa in due parti. La prima parte descrive come eseguire un test end-to-end utilizzando un'app demo e Google Play Console. La seconda parte descrive come integrare la libreria Tuning Fork nella tua toolchain e come utilizzare le funzioni fornite dalla libreria. Fai clic sul link Avanti di seguito per iniziare.