In diesem Dokument wird beschrieben, wie Sie Annotationen, Parameter zur Grafikqualität und Einstellungen in Ihrem Projekt festlegen.
Annotationen und Parameter zur Grafikqualität
Anmerkungen liefern Kontextinformationen zu den Aktionen Ihres Spiels, wenn ein Tick aufgezeichnet wird. Parameter zur Grafikqualität spiegeln die Leistung und die grafischen Einstellungen Ihres Spiels wider. Sie definieren diese mit Protokollpuffern, dem sprachneutralen, strukturierten Datenaustauschformat von Google. Weitere Informationen zur Verwendung von Protokollpuffern in Ihrem Spiel finden Sie unter Protokollpuffer.
Die möglichen Anmerkungen und Parameter zur Grafikqualität für Ihr Spiel werden in einer Datei namens dev_tuningfork.proto
definiert. Sie befindet sich im Verzeichnis assets/tuningfork
Ihres Projekts. Hier sehen Sie ein Beispiel aus der Demo-App:
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;
}
Beachten Sie Folgendes:
- Das Paket muss
com.google.tuningfork
sein. - Die Nachrichtennamen müssen genau
Annotation
undFidelityParams
lauten. - Sie können nur die in dieser Datei definierten
enums
als Teil von Anmerkungen verwenden. - Sie können in
FidelityParams
-Feldern nurenums
,int32s
oderfloats
verwenden. - Das Validierungstool setzt diese Konventionen um.
Einstellungen
Die Settings
-Nachricht wird durch tuningfork.proto
definiert. Ein vollständiges Beispiel finden Sie in der folgenden Datei:
gamesdk/samples/tuningfork/insightsdemo/app/src/main/assets/tuningfork/tuningfork_settings.txt
Sie müssen die Einstellungen für Ihr Spiel in einer Datei namens tuningfork_settings.txt
im Verzeichnis assets/tuningfork
Ihres Projekts definieren. Du musst nur die folgenden Felder angeben:
aggregation_strategy
: Eine Nachricht, die Folgendes enthält:method
:TIME_BASED
, um alle n Millisekunden hochzuladen, oderTICK_BASED
, um alle n Ticken hochzuladen.intervalms_or_count
: n für das Feldmethod
.max_instrumentation_keys
: Anzahl der zu verwendenden Instrumentierungsschlüssel. Legen Sie diesen Wert auf4
fest, wenn Sie die Android Frame Pacing Library verwenden.annotation_enum_size
: Ein optionales Feld, da die Größe beim Start aus dem Deskriptor aus berechnet wird.
api_key
: Der API-Schlüssel des Cloud-Projekts Ihrer Anwendung, der zum Validieren von Anfragen an den Endpunkt verwendet wird. Informationen zum Generieren dieses Schlüssels finden Sie unter API aktivieren. Wenn inlogcat
Verbindungsfehler angezeigt werden, prüfen Sie, ob der API-Schlüssel korrekt ist.default_fidelity_parameters_filename
: Der bei der Initialisierung verwendete Parameter zur Grafikqualität (optional, wenn Sietraining_fidelity_params
in Ihrem Code festgelegt haben).level_annotation_index
: (optional) Der Index in den Annotationsfeldern der Ebenennummer.
Hier ein Beispiel für eine Textdarstellung:
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
Anmerkungen festlegen
Du musst während des Spiels Anmerkungen manuell hinzufügen. Sie können sich ein Beispiel dafür in der Demo-App ansehen, während diese automatisch durch alle Levels des Spiels navigiert. Weitere Informationen finden Sie in der SetAnnotations()
-Funktion in insightsdemo.cpp
.
In diesem Fall gibt die Annotation nur die Stufennummer an.
message Annotation {
Level level = 1;
}
Qualitätsstufen definieren
Verwenden Sie Qualitätsstufen, um Sitzungen zu annotieren, damit Sie feststellen können, ob die Geräte auf einer zu hohen Qualitätsstufe (was zu einer geringeren Leistung führt) oder zu niedrig (was zu einer unnötigen Verschlechterung der Grafikqualität führt).
Sie müssen mindestens eine und besser mehrere Qualitätsstufen für Ihr Spiel definieren. Eine Qualitätsstufe entspricht einer Instanz Ihrer FidelityParams
-Nachricht. Diese Stufen müssen in ansteigender Fidelity-Reihenfolge im folgenden Dateinamenformat angegeben werden:
dev_tuningfork_fidelityparams_i.txt
Dabei ist i
ein Index, der bei 1 mit einem Höchstwert von 15 beginnt. Diese Dateien müssen sich im Verzeichnis assets/tuningfork
Ihres Projekts befinden. Das Beispielprojekt zeigt ein Beispiel für diese Struktur im Verzeichnis gamesdk/samples/tuningfork/insightsdemo/app/src/main/assets/tuningfork/
.
Protokollpuffer
Die Abstimmung Fork-Bibliothek verwendet das Protokollpufferformat von Google für Einstellungen, Anmerkungen und Parameter zur Grafikqualität. Dies ist ein klar definiertes, mehrsprachiges Protokoll für erweiterbare, strukturierte Daten. Weitere Informationen finden Sie in der Dokumentation zu Protokollzwischenspeichern.
Proto2 vs. proto3
Die Version des Protokollpufferformats wird in der ersten Zeile der Datei festgelegt:
syntax="proto2";
Proto2 und proto3 sind zwei häufig verwendete Versionen von Protokollpuffern. Beide verwenden dasselbe Wireformat, aber die Definitionsdateien sind nicht kompatibel. Zu den wichtigsten Unterschieden zwischen den beiden Versionen gehören:
- Die Keywords
optional
undrequired
sind in proto3 nicht mehr zulässig. - In proto3 ist alles effektiv
optional
. - Erweiterungen werden in proto3 nicht unterstützt.
Verwenden Sie proto3 in Ihren Proto-Dateien, da diese zu C# kompiliert werden können. Proto2 funktioniert auch mit dem eingeschränkten Feature-Set, das in der Abstimmung Fork-Bibliothek verwendet wird.
Text- und binäre Darstellungen im Vergleich
Das binäre protobuf-Drahtformat ist klar definiert und in verschiedenen Protobuf-Versionen stabil (der generierte Code ist es nicht). Es gibt auch ein Textformat, das die Vollversion der protobuf-Bibliothek generieren und lesen kann. Dieses Format ist nicht so genau definiert, aber für die begrenzte Anzahl von Features in der Feinabstimmungsbibliothek stabil. Mit dem Compiler protoc
können Sie zwischen Binär- und Textformaten konvertieren. Der folgende Befehl konvertiert einen Text-Protokollzwischenspeicher in Binärcode:
protoc --encode com.google.tuningfork.Settings tuningfork.proto < tuningfork_settings.txt > tuningfork_settings.bin
Du musst in dein APK anstelle von Textdateien Binärdateien verwenden, da die vollständige protobuf-Bibliothek mehrere MB groß ist. Wenn die Abstimmung Fork-Bibliothek davon abhängig ist, würde sich die Größe deines Spiels um einen ähnlichen Wert erhöhen.
Vollständig vs. Lite vs. Nano
Neben der vollständigen protobuf-Bibliothek gibt es eine Lite-Version, die den Codebedarf reduziert, indem einige Features wie Reflexion, FileDescriptors
und das Streaming in und aus Textformaten entfernt werden. Diese Version erfordert immer noch mehrere MB zusätzlichen Code-Fußabdruck. Daher verwendet die Abstimmung Fork-Bibliothek intern die nanopb-Bibliothek. Der Quellcode für diese Bibliothek ist im Android Open Source-Projekt in external/nanopb-c
enthalten und gehört zum gamesdk
-Zweig. Verwende diese Bibliothek in deinem Spiel, wenn die Codegröße ein Problem ist.
In gamesdk/src/protobuf
gibt es CMake-Dateien, mit denen Sie alle drei Versionen von protobuf einbinden können. Die Beispiele verwenden eine Mischung aus Nanopb und vollständigen Protokollpuffer.