Anmerkungen, Parameter zur Grafikqualität und Einstellungen definieren

In diesem Dokument wird beschrieben, wie Sie Annotationen, Parameter zur Grafikqualität und Einstellungen in Ihrem Projekt festlegen.

Anmerkungen und Parameter zur Grafikqualität

Anmerkungen liefern Kontextinformationen dazu, was dein Spiel tut, wenn ein Tick aufgezeichnet wird. Die Parameter zur Grafikqualität spiegeln die Leistungs- und Grafikeinstellungen Ihres Spiels wider. Sie definieren diese mithilfe von Protokollzwischenspeichern, dem sprachneutralen, strukturierten Datenaustauschformat von Google. Weitere Informationen zur Verwendung von Protokollzwischenspeichern in Ihrem Spiel finden Sie unter Informationen zu Protokollzwischenspeichern.

Die möglichen Annotationen und Parameter zur Grafikqualität für Ihr Spiel werden in einer Datei namens dev_tuningfork.proto definiert, die sich im Verzeichnis assets/tuningfork Ihres Projekts befindet. Hier 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;
}

Wichtige Hinweise:

  • Das Paket muss com.google.tuningfork sein.
  • Die Nachrichtennamen müssen genau Annotation und FidelityParams lauten.
  • Sie können nur enums, die in dieser Datei definiert sind, als Teil von Annotationen verwenden.
  • Sie können nur enums, int32s oder floats in FidelityParams-Feldern verwenden.
  • Das Validierungstool erzwingt diese Konventionen.

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. Sie müssen nur die folgenden Felder angeben:

  • aggregation_strategy: Eine Nachricht mit folgendem Inhalt:

    • method: TIME_BASED, um alle n Millisekunden hochzuladen, oder TICK_BASED, um alle n Ticks hochzuladen.
    • intervalms_or_count: n für das Feld method.
    • max_instrumentation_keys: Anzahl der zu verwendenden Instrumentenschlüssel. Legen Sie 4 fest, wenn Sie die Android Frame Pacing Library verwenden.
    • annotation_enum_size: Ein optionales Feld, da die Größe beim Start aus dem Deskriptor berechnet wird.
  • api_key: Der API-Schlüssel des Cloud-Projekts Ihrer App, der zum Validieren von Anfragen an den Endpunkt verwendet wird. Informationen zum Generieren dieses Schlüssels finden Sie unter API aktivieren. Wenn in logcat Verbindungsfehler angezeigt werden, prüfen Sie, ob der API-Schlüssel korrekt ist.

  • default_fidelity_parameters_filename: Der bei der Initialisierung verwendete Satz von Parametern zur Grafikqualität (optional, wenn Sie training_fidelity_params in Ihrem Code festlegen).

  • level_annotation_index: (Optional) Der Index der Levelnummer in Ihren Annotationsfeldern.

Hier ist 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

Sie müssen während des Spiels manuell Annotationen festlegen. Ein Beispiel dafür finden Sie in der Demo-App, in der alle Spiellevel automatisch durchlaufen werden. Weitere Informationen finden Sie unter der Funktion SetAnnotations() in insightsdemo.cpp.

In diesem Fall wird in der Annotation nur die Nummer der Ebene angegeben.

message Annotation {
  Level level = 1;
}

Qualitätsstufen definieren

Verwenden Sie Qualitätsstufen, um Sitzungen zu annotieren, damit Sie feststellen können, ob Geräte mit einer zu hohen Qualitätsstufe (was zu einer geringeren Leistung führt) oder einer zu niedrigen Qualitätsstufe (was zu einer unnötig reduzierten Wiedergabetreue führt) ausgeführt werden.

Du musst mindestens eine, vorzugsweise mehrere Qualitätsstufen für dein Spiel definieren. Eine Qualitätsstufe entspricht einer Instanz Ihrer FidelityParams-Nachricht. Diese Ebenen müssen in aufsteigender Reihenfolge der Detailgenauigkeit mit dem folgenden Dateinamenformat angegeben werden:

dev_tuningfork_fidelityparams_i.txt

wobei i ein Index ist, der bei 1 beginnt und einen Maximalwert von 15 hat. 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/.

Protokollzwischenspeicher

Die Tuning Fork-Bibliothek verwendet das Protokollpufferformat von Google für Einstellungen, Annotationen 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 im Vergleich zu Proto3

Die Version des Protokollzwischenspeicher-Formats wird in der ersten Zeile der Datei festgelegt:

syntax="proto2";

Proto2 und Proto3 sind zwei häufig verwendete Versionen von Protokollzwischenspeichern. Beide verwenden dasselbe Wire-Format, aber die Definitionsdateien sind nicht kompatibel. Die wichtigsten Unterschiede zwischen den beiden Versionen sind:

  • Die Schlüsselwörter optional und required 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 in C# kompiliert werden können. Proto2 funktioniert auch mit dem eingeschränkten Funktionsumfang, der in der Tuning Fork-Bibliothek verwendet wird.

Text- und Binärdarstellungen

Das binäre Protobuf-Wire-Format ist klar definiert und über verschiedene Protobuf-Versionen hinweg 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 gut definiert, aber für die begrenzte Anzahl von Funktionen in der Tuning Fork-Bibliothek stabil. Mit dem protoc-Compiler können Sie zwischen Binär- und Textformaten konvertieren. Mit dem folgenden Befehl wird ein Text-Protobuf in ein Binärformat konvertiert:

protoc --encode com.google.tuningfork.Settings tuningfork.proto < tuningfork_settings.txt > tuningfork_settings.bin

Du musst Binärdateien anstelle von Textdateien in dein APK einfügen, da die vollständige Protobuf-Bibliothek mehrere MB groß ist. Wenn die Tuning Fork-Bibliothek davon abhängig wäre, würde sich die Größe deines Spiels um einen ähnlichen Betrag erhöhen.

Full, Lite und Nano im Vergleich

Neben der vollständigen Protobuf-Bibliothek gibt es eine Lite-Version, die den Codeumfang reduziert, indem einige Funktionen wie Reflexion, FileDescriptors und Streaming zu und von Textformaten entfernt werden. Diese Version erfordert immer noch mehrere MB zusätzlichen Code-Footprint. Daher verwendet die Tuning Fork-Bibliothek intern die nanopb-Bibliothek. Der Quellcode für diese Bibliothek ist im Open-Source-Projekt für Android in external/nanopb-c enthalten und Teil des gamesdk-Zweigs. Verwenden Sie diese Bibliothek in Ihrem Spiel, wenn die Codegröße ein Problem darstellt.

In gamesdk/src/protobuf gibt es CMake-Dateien, mit denen Sie alle drei Versionen von protobuf einbinden können. In den Beispielen wird eine Mischung aus nanopb und vollständigem protobuf verwendet.