Cette page a été traduite par l'API Cloud Translation.

Définir des annotations, des paramètres de fidélité et des paramètres

Ce document explique comment définir les annotations, les paramètres de fidélité et les paramètres dans votre projet.

Annotations et paramètres de fidélité

Les annotations fournissent des informations contextuelles sur ce que fait votre jeu lorsqu'un tick est enregistré. Les paramètres de fidélité représentent les paramètres de performances et les paramètres graphiques de votre jeu. Vous les définissez à l'aide de tampons de protocole, qui constituent le format d'échange de données structuré et indépendant du langage de Google. Pour en savoir plus sur l'utilisation des tampons de protocole dans votre jeu, consultez À propos des tampons de protocole.

Les annotations et les paramètres de fidélité possibles pour votre jeu sont définis dans un fichier nommé dev_tuningfork.proto, qui se trouve dans le répertoire assets/tuningfork de votre projet. Voici un exemple provenant de l'application de démonstration :

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;
}

Remarques :

Le package doit être com.google.tuningfork.
Les noms exacts des messages doivent être Annotation et FidelityParams.
Vous pouvez uniquement utiliser des enums définies dans ce fichier avec des annotations.
Vous ne pouvez utiliser que des éléments enums, int32s ou floats dans les champs FidelityParams.
L'outil de validation applique ces conventions.

Paramètres

Le message Settings est défini par tuningfork.proto. Vous trouverez un exemple complet dans le fichier suivant :

gamesdk/samples/tuningfork/insightsdemo/app/src/main/assets/tuningfork/tuningfork_settings.txt

Vous devez définir les paramètres de votre jeu dans un fichier nommé tuningfork_settings.txt situé dans le répertoire assets/tuningfork de votre projet. Seuls les champs suivants doivent être spécifiés :

aggregation_strategy : message contenant les éléments ci-dessous :
- method : TIME_BASED pour importer toutes les n millisecondes ou TICK_BASED pour importer tous les n ticks.
- intervalms_or_count : n pour le champ method.
- max_instrumentation_keys : nombre de clés d'instrumentation à utiliser. À définir sur 4 si vous utilisez la bibliothèque Android Frame Pacing.
- annotation_enum_size : champ facultatif, puisque la taille est calculée au démarrage à partir du descripteur.
api_key : clé API du projet sur le cloud de votre application, utilisée pour valider les requêtes adressées au point de terminaison. Pour générer cette clé, consultez Activer l'API. Si vous constatez des erreurs de connexion dans logcat, vérifiez que la clé API est correcte.
default_fidelity_parameters_filename : ensemble de paramètres de fidélité utilisé au moment de l'initialisation (facultatif si vous définissez training_fidelity_params dans votre code).
level_annotation_index (facultatif) : index figurant dans les champs d'annotation du numéro de niveau.

Voici un exemple de représentation textuelle :

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

Définir des annotations

Vous devez définir des annotations manuellement pendant votre jeu. Vous en trouverez un exemple dans l'application de démonstration, qui parcourt automatiquement tous les niveaux de jeu. Pour en savoir plus, consultez la fonction SetAnnotations() dans insightsdemo.cpp.

Dans ce cas, l'annotation ne spécifie que le numéro de niveau.

message Annotation {
  Level level = 1;
}

Définir des niveaux de qualité

Utilisez des niveaux de qualité pour annoter les sessions afin de déterminer si les appareils s'exécutent à un niveau de qualité trop élevé (ce qui entraîne une baisse des performances) ou trop faible (ce qui entraîne une réduction inutile de la fidélité).

Vous devez définir au moins un niveau de qualité pour votre jeu, et de préférence plusieurs. Un niveau de qualité correspond à une instance de votre message FidelityParams. Ces niveaux doivent être indiqués dans l'ordre croissant de fidélité avec le format de nom de fichier suivant :

dev_tuningfork_fidelityparams_i.txt

où i correspond à un index commençant par 1 et dont la valeur maximale est 15. Ces fichiers doivent se trouver dans le répertoire assets/tuningfork de votre projet. L'exemple de projet disponible dans le répertoire gamesdk/samples/tuningfork/insightsdemo/app/src/main/assets/tuningfork/ illustre une structure de ce type.

À propos des tampons de protocole

La bibliothèque Tuning Fork utilise le format de tampon de protocole de Google pour les paramètres, les annotations et les paramètres de fidélité. Il s'agit d'un protocole bien défini et multilangage destiné aux données extensibles et structurées. Pour en savoir plus, consultez la documentation consacrée aux tampons de protocole.

Proto2 et proto3

La version du format de tampon de protocole est définie sur la première ligne du fichier :

syntax="proto2";

Proto2 et proto3 sont deux versions de tampons de protocole couramment utilisées. Elles utilisent le même format filaire, mais les fichiers de définition ne sont pas compatibles. Les principales différences entre ces deux versions sont les suivantes :

Les mots clés optional et required ne sont plus autorisés dans proto3.
Tout est effectivement optional dans proto3.
Les extensions ne sont pas disponibles dans proto3.

Utilisez proto3 dans vos fichiers proto, car ceux-ci peuvent être compilés en C#. Proto2 fonctionne également avec l'ensemble de fonctionnalités limité utilisé dans la bibliothèque Tuning Fork.

Représentations textuelles et binaires

Le format de fil binaire des tampons de protocole est bien défini et stable sur différentes versions de tampons de protocole (le code généré ne l'est pas). Il existe également un format texte que la version complète de la bibliothèque de tampons de protocole peut générer et lire. Ce format n'est pas aussi bien défini, mais il est stable pour l'ensemble limité de fonctionnalités de la bibliothèque Tuning Fork. Vous pouvez convertir le format binaire en format texte, et inversement, à l'aide du compilateur protoc. La commande suivante convertit un tampon de protocole textuel au format binaire :

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

Vous devez inclure des fichiers binaires plutôt que des fichiers texte dans votre APK, car la version complète de la bibliothèque de tampons de protocole fait plusieurs Mo. Si la bibliothèque Tuning Fork en dépendait, la taille de votre jeu augmenterait d'autant.

Versions complète, allégée et nano

Outre la version complète de la bibliothèque de tampons de protocole, il existe une version allégée qui réduit l'empreinte du code en supprimant certaines fonctionnalités telles que la réflexion, FileDescriptors et le streaming vers et depuis les formats texte. Cette version représente encore plusieurs Mo en termes d'empreinte de code. Par conséquent, en interne, la bibliothèque Tuning Fork utilise la bibliothèque nanopb. Le code source de cette bibliothèque est inclus dans le projet Android Open Source, sous external/nanopb-c, et fait partie de la branche gamesdk. Utilisez cette bibliothèque dans votre jeu si la taille du code pose problème.

Vous trouverez sous gamesdk/src/protobuf des fichiers CMake qui vous aideront à intégrer les trois versions de tampons de protocole. Les exemples utilisent une combinaison des versions nanopb et complète des tampons de protocole.

Mettre à jour vos paramètres de compilation

Ajouter des fonctions de temps de rendu