Questo documento descrive come impostare annotazioni, parametri di fedeltà e impostazioni nel tuo progetto.
Annotazioni e parametri di fedeltà
Le annotazioni forniscono informazioni contestuali sull'attività del gioco quando viene registrato un tick. I parametri di fedeltà riflettono le prestazioni e le impostazioni grafiche del gioco. Puoi definire questi valori mediante i buffer di protocollo, il formato di interscambio dati strutturato e indipendente dal linguaggio di Google. Per scoprire di più sull'utilizzo dei buffer di protocollo all'interno del gioco, consulta Informazioni sui buffer di protocollo.
Le possibili annotazioni e parametri di fedeltà per il tuo gioco vengono definiti in un
file chiamato dev_tuningfork.proto
, che si trova nella directory assets/tuningfork
del progetto. Di seguito è riportato un esempio dell'app demo:
syntax = "proto3";
package com.google.tuningfork;
enum InstrumentKey {
CPU = 0;
GPU = 1;
SWAPPY_WAIT = 2;
SWAPPY_SWAP = 3;
CHOREOGRAPHER = 4;
}
enum Level {
// 0 is not a valid value
LEVEL_INVALID = 0;
LEVEL_1 = 1;
LEVEL_2 = 2;
LEVEL_3 = 3;
};
message Annotation {
Level level = 1;
}
message FidelityParams {
int32 num_spheres = 1;
float tesselation_percent = 2;
}
Nota:
- Il pacchetto deve essere
com.google.tuningfork
. - I nomi dei messaggi devono essere esattamente
Annotation
eFidelityParams
. - Puoi utilizzare solo
enums
definito in questo file come parte delle annotazioni. - Puoi utilizzare solo
enums
,int32s
ofloats
nei campiFidelityParams
. - Queste convenzioni vengono applicate dallo strumento di convalida.
Impostazioni
Il messaggio Settings
è definito da tuningfork.proto
. Vedi un esempio completo nel file seguente:
gamesdk/samples/tuningfork/insightsdemo/app/src/main/assets/tuningfork/tuningfork_settings.txt
Devi definire le impostazioni del gioco in un file denominato tuningfork_settings.txt
che si trova nella directory assets/tuningfork
del progetto. Devi specificare solo i seguenti campi:
aggregation_strategy
: un messaggio contenente quanto segue:method
:TIME_BASED
per caricare ogni n millisecondi oTICK_BASED
per caricare ogni n tick.intervalms_or_count
: n per il campomethod
.max_instrumentation_keys
: numero di tasti di strumentazione da utilizzare. Impostalo su4
se usi la libreria di pacing dei frame Android.annotation_enum_size
: un campo facoltativo poiché le dimensioni vengono calcolate all'avvio dal descrittore.
api_key
: la chiave API del progetto Cloud dell'app, utilizzata per convalidare le richieste all'endpoint. Per generare questa chiave, consulta Abilitare l'API. Se vedi errori di connessione inlogcat
, verifica che la chiave API sia corretta.default_fidelity_parameters_filename
: il set di parametri di fedeltà utilizzato all'inizializzazione (facoltativo se impostitraining_fidelity_params
nel codice).level_annotation_index
: (facoltativo) l'indice nei campi di annotazione del numero del livello.
Di seguito è riportata una rappresentazione testuale di esempio:
aggregation_strategy: {method: TIME_BASED, intervalms_or_count: 10000,
max_instrumentation_keys: 5, annotation_enum_size: [3,4]}
api_key: "API-KEY-FROM-GOOGLE-CLOUD-CONSOLE"
default_fidelity_parameters_filename: "dev_tuningfork_fidelityparams_3.bin"
level_annotation_index: 1
Impostazione annotazioni
Devi impostare manualmente le annotazioni durante il gioco. Puoi vederne un esempio nell'app demo in quanto scorre automaticamente tutti i livelli del gioco. Per ulteriori informazioni, consulta la funzione SetAnnotations()
in
insightsdemo.cpp
.
In questo caso, l'annotazione specifica solo il numero del livello.
message Annotation {
Level level = 1;
}
Definire i livelli qualitativi
Utilizza i livelli qualitativi per annotare le sessioni in modo da poter determinare se i dispositivi funzionano a un livello qualitativo troppo alto (che comporta prestazioni inferiori) o troppo basso (con una conseguente riduzione inutilmente della fedeltà).
Devi definire almeno uno e preferibilmente più livelli qualitativi per il
gioco. Un livello qualitativo corrisponde a un'istanza del messaggio FidelityParams
. Questi livelli devono essere indicati in ordine di fedeltà crescente con il seguente formato di nome file:
dev_tuningfork_fidelityparams_i.txt
dove i
è un indice che inizia da 1 con un valore massimo di 15. Questi file devono trovarsi nella directory assets/tuningfork
del progetto. Il progetto di esempio mostra un esempio di questa struttura nella directory gamesdk/samples/tuningfork/insightsdemo/app/src/main/assets/tuningfork/
.
Informazioni sui buffer di protocollo
La libreria di Tuning Fork utilizza il formato di buffer del protocollo di Google per impostazioni, annotazioni e parametri di fedeltà. Si tratta di un protocollo multilingue ben definito per dati strutturati estensibili. Per ulteriori informazioni, consulta la documentazione sui buffer di protocollo.
Proto2 e proto3
La versione del formato del buffer del protocollo viene impostata nella prima riga del file:
syntax="proto2";
Proto2 e proto3 sono due versioni comunemente utilizzate dei buffer di protocollo. Utilizzano entrambi lo stesso formato di cablaggio, ma i file di definizione non sono compatibili. Le differenze chiave tra le due versioni includono:
- Le parole chiave
optional
erequired
non sono più consentite nel proto3. - Tutto è efficacemente
optional
in proto3. - Le estensioni non sono supportate in proto3.
Utilizza proto3 nei file proto perché possono essere compilati in C#. Proto2 funziona bene con il set limitato di funzionalità usato nella libreria di Tuning Diapason.
Confronto tra rappresentazioni di testo e binarie
Il formato binario protobuf filo è ben definito e stabile tra diverse versioni protobuf (il codice generato non lo è). Esiste anche un formato di testo che
la versione completa della libreria protobuf può generare e leggere. Questo formato non è molto ben definito, ma è stabile per l'insieme limitato di funzionalità nella libreria diapason. Puoi convertire tra formati binari e di testo
utilizzando il compilatore protoc
. Il seguente comando converte un testo protobuf in binario:
protoc --encode com.google.tuningfork.Settings tuningfork.proto < tuningfork_settings.txt > tuningfork_settings.bin
Devi includere file binari anziché file di testo nell'APK perché la libreria protobuf completa ha una dimensione di diversi MB; in questo modo la libreria di Tuning Fork dipende da quest'ultima aumenterà le dimensioni del tuo gioco di una quantità simile.
Confronto tra modalità Full, Lite e Nano
Oltre alla libreria protobuf completa, è disponibile una versione Lite che riduce l'impronta di codice rimuovendo alcune funzionalità come il riflesso, FileDescriptors
e lo streaming da e verso i formati di testo. Questa versione richiede ancora diversi MB di spazio di codice extra, pertanto la libreria Tuning Fork utilizza internamente la libreria nanopb. Il codice sorgente per questa libreria è incluso nel progetto open source Android in external/nanopb-c
e fa parte del ramo gamesdk
. Usa questa libreria nel tuo gioco se
le dimensioni del codice sono un problema.
In gamesdk/src/protobuf
sono presenti file CMake che possono aiutarti a integrare tutte e tre le versioni di protobuf. Gli esempi utilizzano una combinazione di nanopb e protobuf completo.