Ajouter des fonctions de temps de rendu

Utilisez les fonctions de cet article pour intégrer la bibliothèque Tuning Fork dans le code de votre jeu.

Le fichier d'en-tête include/tuningfork/tuningfork.h contient l'interface principale de la bibliothèque Tuning Fork. Le fichier include/tuningfork/tuningfork_extra.h contient des fonctions utilitaires.

Certaines fonctions utilisent des sérialisations de tampons de protocole. Pour en savoir plus sur l'utilisation de tampons de protocole dans votre jeu, consultez À propos des tampons de protocole.

Les paramètres de fonction et les valeurs renvoyées sont décrits dans les en-têtes ainsi que dans la documentation de référence de l'API.

Fonctions de cycle de vie d'Android Performance Tuner

Utilisez les fonctions suivantes pour contrôler le cycle de vie d'une instance de Tuning Fork.

Initialiser

TFErrorCode TuningFork_init(const TFSettings* settings, JNIEnv* env, jobject context);

Vous devez appeler cette fonction au démarrage, généralement à partir du code natif exécuté par la méthode onCreate() de l'application. Elle alloue les données nécessaires à la bibliothèque Tuning Fork.

Un fichier tuningfork_settings.bin contenant les paramètres d'histogramme et d'annotation doit figurer dans le répertoire assets/tuningfork de votre application. Consultez la section Représentations textuelles et binaires pour savoir comment convertir le fichier texte en binaire.

Les champs que vous renseignez dans settings déterminent la façon dont la bibliothèque s'initialise.

/**
 * @brief Initialization settings
 *   Zero any values that are not being used.
 */
struct TFSettings {
  /**
   * Cache object to be used for upload data persistence.
   * If unset, data is persisted to /data/local/tmp/tuningfork
   */
  const TFCache* persistent_cache;
  /**
   * The address of the Swappy_injectTracers function.
   * If this is unset, you need to call TuningFork_tick explicitly.
   * If it is set, telemetry for 4 instrument keys is automatically recorded.
   */
  SwappyTracerFn swappy_tracer_fn;
  /**
   * Callback
   * If set, this is called with the fidelity parameters that are downloaded.
   * If unset, you need to call TuningFork_getFidelityParameters explicitly.
   */
  ProtoCallback fidelity_params_callback;
  /**
   * A serialized protobuf containing the fidelity parameters to be uploaded
   *  for training.
   * Set this to nullptr if you are not using training mode. Note that these
   *  are used instead of the default parameters loaded from the APK, if they
   *  are present and there are neither a successful download nor saved parameters.
   */
  const CProtobufSerialization* training_fidelity_params;
  /**
   * A null-terminated UTF-8 string containing the endpoint that Tuning Fork
   * will connect to for parameter, upload, and debug requests. This overrides
   * the value in base_uri in the settings proto and is intended for debugging
   * purposes only.
   */
  const char* endpoint_uri_override;
  /**
   * The version of Swappy that swappy_tracer_fn comes from.
   */
  uint32_t swappy_version;
  /**
   * The number of each metric that is allowed to be allocated at any given
   * time. If any element is zero, the default for that metric type is used.
   * Memory for all metrics is allocated up-front at initialization. When all
   * metrics of a given type are allocated, further requested metrics are not
   * added and data is lost.
   */
  TuningFork_MetricLimits max_num_metrics;
};

Si vous transmettez la fonction Swappy_injectTracer() (OpenGL, Vulkan) à partir de l'API Frame Pacing au moment de l'initialisation, la bibliothèque Tuning Fork enregistre automatiquement le temps de rendu sans que vous ayez à appeler explicitement les fonctions tick vous-même. Ceci est illustré dans l'application de démonstration :

void InitTf(JNIEnv* env, jobject activity) {
   SwappyGL_init(env, activity);
   swappy_enabled = SwappyGL_isEnabled();
   TFSettings settings {};
   if (swappy_enabled) {
       settings.swappy_tracer_fn = &SwappyGL_injectTracer;
       settings.swappy_version = Swappy_version();
   }
...
}

Détruire

TFErrorCode TuningFork_destroy();

Vous pouvez appeler cette fonction au moment de l'arrêt. Elle tente d'envoyer toutes les données d'histogramme stockées pour une importation ultérieure avant de libérer la mémoire utilisée par la bibliothèque Tuning Fork.

Vider

TFErrorCode TuningFork_flush();

Cette fonction vide les histogrammes enregistrés (par exemple, lorsque le jeu est envoyé à l'arrière-plan ou au premier plan). Elle ne vide pas les données si la période d'importation minimale, qui est d'une minute par défaut, n'est pas écoulée depuis l'importation précédente.

Définir les paramètres de fidélité

TFErrorCode TuningFork_setFidelityParameters(const CProtobufSerialization* params);

Cette fonction ignore les paramètres de fidélité actuels auxquels les données d'image sont associées. Vous devez l'appeler lorsqu'un joueur modifie manuellement les paramètres de qualité du jeu.

Annotations

TFErrorCode TuningFork_setCurrentAnnotation(const CProtobufSerialization* annotation);

Cette fonction définit l'annotation à associer aux ticks ultérieurs. Elle renvoie TFERROR_INVALID_ANNOTATION en cas d'erreur lors du décodage de l'annotation et TFERROR_OK en l'absence d'erreur.

Fonctions par image

TFErrorCode TuningFork_frameTick(TFInstrumentKey key);

Cette fonction enregistre le temps écoulé entre le tick précédent associé à la valeur key donnée et l'heure actuelle figurant dans l'histogramme associé à key et à l'annotation actuelle.

TFErrorCode TuningFork_frameDeltaTimeNanos(TFInstrumentKey key, TFDuration dt);

Cette fonction enregistre la durée figurant dans l'histogramme associé à key et à l'annotation actuelle.

TFErrorCode TuningFork_startTrace(TFInstrumentKey key, TraceHandle* handle);

Cette fonction définit un handle sur un handle de trace associé à l'élément key donné.

TFErrorCode TuningFork_endTrace(TraceHandle handle);

Cette fonction enregistre l'intervalle de temps depuis l'appel TuningFork_startTrace() figurant dans l'histogramme associé à l'élément key utilisé et à l'annotation actuelle.

Fonctions de cycle de vie de l'application

typedef enum TuningFork_LifecycleState {
    TUNINGFORK_STATE_UNINITIALIZED = 0,
    TUNINGFORK_STATE_ONCREATE = 1,
    TUNINGFORK_STATE_ONSTART = 2,
    TUNINGFORK_STATE_ONSTOP = 3,
    TUNINGFORK_STATE_ONDESTROY = 4,
} TuningFork_LifecycleState;

TFErrorCode TuningFork_reportLifecycleEvent(TuningForkLifecycleState state);

Appelez cette fonction à partir des méthodes de cycle de vie appropriées dans l'élément Activity principal de votre jeu, en transmettant l'énumération appropriée. En enregistrant les événements de cycle de vie du jeu, APT est mieux à même de déterminer quand votre jeu risque de planter ou quand les utilisateurs risquent de quitter le jeu (par exemple, lors de longs événements de chargement).

Fonctions avancées

Les fonctions suivantes sont disponibles dans tuningfork_extra.h.

Rechercher et charger des fichiers dans un APK

TFErrorCode TuningFork_findFidelityParamsInApk(JNIEnv* env, jobject context, const char* filename, CProtobufSerialization* fidelityParams);

Cette fonction charge fidelityParams à partir du répertoire assets/tuningfork de l'APK avec le nom de fichier donné. fidelityParams doit être une sérialisation d'un message FidelityParams. Pour en savoir plus, consultez Définir des niveaux de qualité.

La propriété de la sérialisation est transmise à l'appelant, qui doit appeler CProtobufSerialization_Free pour libérer toute mémoire détenue.

Télécharger les paramètres de fidélité sur un thread distinct

void TuningFork_startFidelityParamDownloadThread(const CProtobufSerialization* defaultParams, ProtoCallback fidelity_params_callback);

Active un thread de téléchargement pour récupérer les paramètres de fidélité. Le thread relance la requête jusqu'à ce que les paramètres soient téléchargés ou qu'une expiration pour dépassement du délai d'attente se produise. Les paramètres téléchargés sont stockés localement. Lorsque l'application redémarre, elle utilise les paramètres téléchargés au lieu des paramètres par défaut.

Enregistrer et supprimer les paramètres de fidélité stockés sur l'appareil

TFErrorCode TuningFork_saveOrDeleteFidelityParamsFile(JNIEnv* env, jobject context, const CProtobufSerialization* fidelity_params);

Cette fonction n'est nécessaire qu'en mode Expert, où les paramètres de fidélité sont téléchargés à partir d'un serveur. Elle remplace ou supprime (si la valeur fidelity_params est nulle) les fichiers stockés localement qui sont utilisés lorsque le serveur est inaccessible.

Requêtes Web

La bibliothèque envoie les types de requêtes suivants au point de terminaison du serveur :

• Une requête generateTuningParameters est envoyée au moment de l'initialisation.
• Pendant le jeu, une requête uploadTelemetry est régulièrement envoyée afin de transmettre des données au serveur.
• Les APK de débogage peuvent également envoyer des requêtes debugInfo, qui informent un serveur de débogage des paramètres, des paramètres de fidélité par défaut et de la structure dev_tuningfork.proto.

Joueurs hors ligne

En l'absence de connexion disponible au moment de l'initialisation, la requête est relancée plusieurs fois avec un temps d'attente croissant.

En l'absence de connexion au moment de l'importation, celle-ci est mise en cache. Vous pouvez fournir votre propre mécanisme de mise en cache en transmettant un objet TFCache au moment de l'initialisation. Si vous ne fournissez pas votre propre cache, les importations sont stockées sous forme de fichiers dans un espace de stockage temporaire.