Frame-Timing-Funktionen hinzufügen

In diesem Artikel erfahren Sie, wie Sie die „Abstimmung Fork“-Bibliothek in Ihren Spielcode einbinden.

Die Headerdatei unter include/tuningfork/tuningfork.h enthält die zentrale Schnittstelle für die „Abstimmung Fork“-Bibliothek. Die Datei unter include/tuningfork/tuningfork_extra.h enthält Dienstfunktionen.

Mehrere Funktionen verwenden Serialisierungen von Protokollpuffern. Weitere Informationen zur Verwendung von Protokollpuffern in Ihrem Spiel finden Sie unter Protokollpuffer.

Funktionsparameter und Rückgabewerte werden in den Headern und der API-Referenzdokumentation erläutert.

Lebenszyklusfunktionen des Android Performance Tuner

Mit den folgenden Funktionen können Sie den Lebenszyklus einer „Abstimmung Fork“-Instanz steuern.

Initialisieren

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

Sie müssen diese Funktion einmal beim Start aufrufen, in der Regel innerhalb des nativen Codes, der von der Methode onCreate() der App ausgeführt wird. Sie ordnet die Daten zu, die von der Feinabstimmungsgabelbibliothek benötigt werden.

In Ihrer Anwendung muss in assets/tuningfork eine tuningfork_settings.bin-Datei vorhanden sein, die das Histogramm und die Annotationseinstellungen enthält. Informationen zum Konvertieren der Textdatei in das Binärformat finden Sie unter Text- und Binärdarstellungen im Vergleich.

Die Felder, die du für settings ausfüllst, bestimmen, wie die Bibliothek sich selbst 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 Swappy_injectTracer()-Funktion (OpenGL, Vulkan) bei der Initialisierung aus der Frame Pacing API übergeben, zeichnet die Abstimmung Fork-Bibliothek die Frame Time automatisch auf, ohne dass Sie die Tick-Funktionen explizit selbst aufrufen. Dies geschieht 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 verwendete Swappy-Version im Feld swappy_version von TFSettings festzulegen. Dadurch kann AbstimmungFork die Daten interpretieren, die von den Swappy-Callbacks zurückgegeben werden.

Löschen

TFErrorCode TuningFork_destroy();

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

Leeren

TFErrorCode TuningFork_flush();

Diese Funktion leert die aufgezeichneten Histogramme, z. B. wenn das Spiel in den Hintergrund oder Vordergrund gesendet wird. Die Daten werden nicht geleert, wenn der minimale Uploadzeitraum (standardmäßig eine Minute) seit dem vorherigen Upload nicht verstrichen ist.

Parameter zur Grafikqualität festlegen

TFErrorCode TuningFork_setFidelityParameters(const CProtobufSerialization* params);

Diese Funktion überschreibt die aktuellen Parameter zur Grafikqualität, mit denen Framedaten verknüpft sind. Sie sollten diese Funktion aufrufen, wenn ein Spieler die Qualitätseinstellungen des Spiels manuell ändert.

Anmerkungen

TFErrorCode TuningFork_setCurrentAnnotation(const CProtobufSerialization* annotation);

Diese Funktion legt fest, dass die Annotation mit nachfolgenden Teilstrichen verknüpft wird. Wenn beim Decodieren der Annotation ein Fehler aufgetreten ist, wird TFERROR_INVALID_ANNOTATION zurückgegeben, andernfalls TFERROR_OK.

Funktionen pro Frame

TFErrorCode TuningFork_frameTick(TFInstrumentKey key);

Diese Funktion erfasst die Zeit zwischen dem vorherigen Tick mit dem angegebenen key und der aktuellen Zeit im Histogramm, das key und der aktuellen Annotation zugeordnet ist.

TFErrorCode TuningFork_frameDeltaTimeNanos(TFInstrumentKey key, TFDuration dt);

Diese Funktion zeichnet die Dauer in dem Histogramm auf, das key und der aktuellen Annotation zugeordnet ist.

TFErrorCode TuningFork_startTrace(TFInstrumentKey key, TraceHandle* handle);

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

TFErrorCode TuningFork_endTrace(TraceHandle handle);

Diese Funktion zeichnet das Zeitintervall seit dem zugehörigen TuningFork_startTrace()-Aufruf im Histogramm auf, das dem verwendeten key und der aktuellen Annotation zugeordnet ist.

Lebenszyklusfunktionen von Apps

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 im Haupt-Activity-Objekt des Spiels auf und übergeben Sie die entsprechende Aufzählung. Durch das Aufzeichnen der Lebenszyklusereignisse des Spiels kann APT besser nachvollziehen, wann Ihr Spiel möglicherweise abstürzt oder wann Nutzer es 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 im APK mit dem angegebenen Dateinamen. fidelityParams muss eine Serialisierung einer FidelityParams-Nachricht sein. Weitere Informationen finden Sie unter Qualitätsstufen definieren.

Die Eigentümerschaft der Serialisierung wird an den Aufrufer übergeben, der CProtobufSerialization_Free aufrufen muss, um die Zuweisung von Arbeitsspeicher aufzuheben.

Parameter zur Grafikqualität in einem separaten Thread herunterladen

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

Aktiviert einen Download-Thread zum Abrufen von Fidelity-Parametern. Der Thread wiederholt die Anfrage so lange, bis die Parameter heruntergeladen wurden oder eine Zeitüberschreitung auftritt. Heruntergeladene Parameter werden lokal gespeichert. Wenn die App neu gestartet wird, werden diese heruntergeladenen Parameter anstelle der Standardparameter verwendet.

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

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

Diese Funktion wird nur im Modus für Fortgeschrittene benötigt, in dem Parameter zur Grafikqualität von einem Server heruntergeladen werden. Die lokal gespeicherten Dateien, die verwendet werden, wenn der Server nicht erreichbar ist, werden entweder überschrieben oder gelöscht (wenn fidelity_params null ist).

Webanfragen

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

• Eine generateTuningParameters-Anfrage wird bei der Initialisierung gestellt.
• Während des Spiels wird regelmäßig eine uploadTelemetry-Anfrage gesendet, um Daten an den Server zu senden.
• APKs zur Fehlerbehebung können auch debugInfo-Anfragen senden, die einen Debug-Server über die Einstellungen, die Standardparameter zur Grafikqualität und die dev_tuningfork.proto-Struktur informieren.

Offline-Spieler

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

Wenn beim Upload keine Verbindung besteht, wird der Upload im Cache gespeichert. Sie können Ihren eigenen Caching-Mechanismus bereitstellen, indem Sie bei der Initialisierung ein TFCache-Objekt übergeben. Wenn Sie keinen eigenen Cache bereitstellen, werden Uploads als Dateien im temporären Speicher gespeichert.