Frame-Timing-Funktionen hinzufügen

Verwenden Sie die Funktionen in diesem Thema, um die Tuning Fork-Bibliothek zu integrieren in deinen Spielcode einfügen.

Die Headerdatei unter include/tuningfork/tuningfork.h enthält die Kernschnittstelle für die Tuning Fork-Bibliothek. Die Datei unter include/tuningfork/tuningfork_extra.h enthält Dienstfunktionen.

Mehrere Funktionen verwenden die Serialisierung von Protokollpuffern. Weitere Informationen zur Verwendung Protokollpuffer in deinem Spiel, siehe Protokollzwischenspeicher

Funktionsparameter und Rückgabewerte werden in den Headern und Referenz-API-Dokumentation

Lebenszyklusfunktionen des Android Performance Tuner

Mit den folgenden Funktionen den Lebenszyklus einer Feinabstimmung steuern Instanz.

Initialisieren

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

Sie müssen diese Funktion einmal beim Start aufrufen, in der Regel aus dem nativen Code die mit der Methode onCreate() der App ausgeführt wird. Er ordnet die Daten zu, die von der Tuning Fork-Bibliothek.

In assets/tuningfork muss eine tuningfork_settings.bin-Datei vorhanden sein innerhalb Ihrer App, die die Einstellungen für das Histogramm und die Annotation enthält. Bis die Textdatei in ein Binärformat konvertieren, siehe Text im Vergleich zu binären Darstellungen

Die Felder, die Sie in settings ausfüllen, bestimmen, wie sich die Bibliothek initialisiert.

/**
 * @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;
};

Wenn Sie die Funktion Swappy_injectTracer() (OpenGL, Vulkan) Frame Pacing API bei der Initialisierung, die Tuning Fork-Bibliothek zeichnet automatisch Frame Time auf, ohne dass Sie das Tick explizit aufrufen Funktionen selbst ausführen. Dies erfolgt in der Demo-App:

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();
   }
...
}

Hinweis: Es ist wichtig, die von dir verwendete Swappy-Version festzulegen. im Feld swappy_version von TFSettings ein. Dadurch kann TuningFork die von den Swappy-Callbacks zurückgegebenen Daten interpretieren.

Vernichten

TFErrorCode TuningFork_destroy();

Sie können diese Funktion beim Herunterfahren aufrufen. Diese Funktion versucht, alle Derzeit gespeicherte Histogrammdaten für einen späteren Upload, bevor Speicher freigegeben wird von der Tuning Fork-Bibliothek verwendet.

Leeren

TFErrorCode TuningFork_flush();

Diese Funktion leert die aufgezeichneten Histogramme (z. B. wenn das Spiel in den Hintergrund oder Vordergrund gesendet werden. Es werden keine Daten geleert, wenn das Minimum Der Standardzeitraum für den Upload beträgt 1 Minute. Seit dem vorherigen Upload.

Parameter zur Grafikqualität festlegen

TFErrorCode TuningFork_setFidelityParameters(const CProtobufSerialization* params);

Diese Funktion überschreibt die aktuellen Parameter zur Grafikqualität, mit denen Frame-Daten verknüpft sind. Du solltest diese Funktion aufrufen, wenn ein Player Qualitätseinstellungen des Spiels zu ändern.

Anmerkungen

TFErrorCode TuningFork_setCurrentAnnotation(const CProtobufSerialization* annotation);

Diese Funktion legt die Anmerkung fest, die mit nachfolgenden Ticks verknüpft wird. Sie gibt zurück TFERROR_INVALID_ANNOTATION, wenn beim Decodieren der Annotation ein Fehler aufgetreten ist und TFERROR_OK, wenn kein Fehler aufgetreten ist.

Funktionen pro Frame

TFErrorCode TuningFork_frameTick(TFInstrumentKey key);

Diese Funktion erfasst die Zeit zwischen dem vorherigen Tick mit dem angegebenen key. und die aktuelle Uhrzeit im Histogramm zu key und dem aktuellen .

TFErrorCode TuningFork_frameDeltaTimeNanos(TFInstrumentKey key, TFDuration dt);

Diese Funktion erfasst die Dauer im Histogramm, die mit key verknüpft ist, und dem aktuelle Anmerkung.

TFErrorCode TuningFork_startTrace(TFInstrumentKey key, TraceHandle* handle);

Diese Funktion legt ein Handle für ein Trace-Handle fest, das mit dem angegebenen key verknüpft ist.

TFErrorCode TuningFork_endTrace(TraceHandle handle);

Diese Funktion erfasst das Zeitintervall seit dem zugehörigen TuningFork_startTrace() im Histogramm aufgerufen, das der verwendeten key und dem aktuellen .

Funktionen für den App-Lebenszyklus

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

Rufen Sie diese Funktion über die entsprechenden Lebenszyklusmethoden in Ihrem Haupt-Activity des Spiels: entsprechenden enum-Wert hinzu. Durch die Aufzeichnung der Lebenszyklus-Ereignisse des Spiels können Sie nachvollziehen, wann Ihr Spiel abstürzt oder wann Nutzer die App beenden. (z. B. bei langen Ladeereignissen).

Erweiterte Funktionen

Die folgenden Funktionen sind in tuningfork_extra.h verfügbar.

Dateien in einem APK suchen und laden

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

Diese Funktion lädt fidelityParams aus dem Verzeichnis assets/tuningfork in das APK mit dem angegebenen Dateinamen. fidelityParams muss eine Serialisierung einer FidelityParams-Nachricht. Weitere Informationen finden Sie unter Definieren Sie Qualitätsstufen.

Die Inhaberschaft der Serialisierung wird an den Aufrufer übergeben, der den Aufruf CProtobufSerialization_Free, um die Zuweisung des verfügbaren Arbeitsspeichers aufzuheben.

Parameter zur Grafikqualität in einem separaten Thread herunterladen

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

Aktiviert einen Download-Thread, um Parameter zur Grafiktreue abzurufen. Der Thread wiederholt bis der Parameter heruntergeladen wird oder eine Zeitüberschreitung auftritt. Heruntergeladene Parameter sind die lokal gespeichert sind. Wenn die App neu gestartet wird, werden diese heruntergeladenen Parameter und nicht auf die Standardparameter.

Parameter zur Grafikqualität auf dem Gerät speichern und löschen

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

Diese Funktion ist nur im Expertenmodus erforderlich, wenn Parameter zur Grafikqualität die von einem Server heruntergeladen wurden. Er wird entweder gespeichert oder gelöscht (wenn fidelity_params Null) sind die lokal gespeicherten Dateien, die verwendet werden, wenn der Server nicht erreichbar ist.

Webanfragen

Die Bibliothek stellt die folgenden Arten von Anfragen an den Serverendpunkt:

• Eine generateTuningParameters-Anfrage wird bei der Initialisierung gesendet.
• Während des Spiels wird regelmäßig eine uploadTelemetry-Anfrage zum Senden auf den Server übertragen.
• Fehlerbehebungs-APKs können auch debugInfo-Anfragen senden, die einen Debug-Server nutzen. der Einstellungen, Standardparameter zur Grafikqualität und dev_tuningfork.proto Struktur.

Offlineplayer

Wenn bei der Initialisierung keine Verbindung verfügbar ist, wird die Anfrage wiederholt mit zunehmender Backoff-Zeit.

Wenn beim Upload keine Verbindung besteht, wird der Upload im Cache gespeichert. Sie können Ihre eigenen Caching-Mechanismus durch TFCache bei der Initialisierung auf. Ohne eigenen Cache werden Uploads die als Dateien im temporären Speicher abgelegt werden.