Frame-Timing-Funktionen hinzufügen

Verwenden Sie die Funktionen in diesem Thema, um die Tuning Fork-Bibliothek in Ihren Spielcode einzubinden.

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 Dienstprogrammfunktionen.

Mehrere Funktionen akzeptieren Serialisierungen von Protocol Buffers. 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

Verwenden Sie die folgenden Funktionen, um den Lebenszyklus einer Tuning Fork-Instanz zu steuern.

Initialisieren

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

Diese Funktion muss einmal beim Start aufgerufen werden, in der Regel aus dem nativen Code, der von der Methode onCreate() der App ausgeführt wird. Sie weist die von der Tuning Fork-Bibliothek benötigten Daten zu.

Ihre App muss im Verzeichnis assets/tuningfork eine tuningfork_settings.bin-Datei mit den Histogramm- und Anmerkungseinstellungen enthalten. Informationen zum Konvertieren der Textdatei in Binär finden Sie unter Text- und Binärdarstellungen.

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

/**
 * @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) aus der Frame Pacing API bei der Initialisierung übergeben, zeichnet die Tuning Fork-Bibliothek automatisch die Frame-Zeit auf, ohne dass Sie die Tick-Funktionen explizit aufrufen müssen. So gehts 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();
   }
...
}

Zerstören

TFErrorCode TuningFork_destroy();

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

Flush

TFErrorCode TuningFork_flush();

Diese Funktion leert die aufgezeichneten Histogramme, z. B. wenn das Spiel in den Hintergrund oder Vordergrund verschoben wird. Daten werden nicht geleert, wenn seit dem letzten Upload noch nicht die Mindestuploadperiode verstrichen ist. Der Standardwert dafür ist eine Minute.

Parameter zur Grafikqualität festlegen

TFErrorCode TuningFork_setFidelityParameters(const CProtobufSerialization* params);

Mit dieser Funktion werden die aktuellen Treueparameter überschrieben, 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);

Mit dieser Funktion wird die Anmerkung festgelegt, die mit nachfolgenden Ticks verknüpft werden soll. TFERROR_INVALID_ANNOTATION wird zurückgegeben, wenn beim Decodieren der Anmerkung ein Fehler aufgetreten ist, und TFERROR_OK, wenn kein Fehler aufgetreten ist.

Funktionen pro Frame

TFErrorCode TuningFork_frameTick(TFInstrumentKey key);

Mit dieser Funktion wird die Zeit zwischen dem vorherigen Tick mit dem angegebenen key und der aktuellen Zeit im Histogramm aufgezeichnet, das mit key und der aktuellen Anmerkung verknüpft ist.

TFErrorCode TuningFork_frameDeltaTimeNanos(TFInstrumentKey key, TFDuration dt);

Diese Funktion erfasst die Dauer im Histogramm, das mit key und der aktuellen Anmerkung verknüpft ist.

TFErrorCode TuningFork_startTrace(TFInstrumentKey key, TraceHandle* handle);

Mit dieser Funktion wird ein Handle für ein Trace-Handle festgelegt, das dem angegebenen key zugeordnet ist.

TFErrorCode TuningFork_endTrace(TraceHandle handle);

Diese Funktion erfasst das Zeitintervall seit dem zugehörigen TuningFork_startTrace()-Aufruf im Histogramm, das mit dem verwendeten key und der aktuellen Anmerkung verknüpft ist.

App-Lebenszyklusfunktionen

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 der Hauptaktivität Ihres Spiels auf und übergeben Sie das entsprechende Enum. Durch die Aufzeichnung der Lebenszyklus-Ereignisse des Spiels kann APT besser nachvollziehen, wann das Spiel abstürzt oder wann Nutzer das Spiel beenden (z. B. während langer Ladevorgänge).

Erweiterte Funktionen

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

Dateien in einer APK finden 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 den belegten Speicher freizugeben.

Fidelity-Parameter in einem separaten Thread herunterladen

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

Aktiviert einen Download-Thread zum Abrufen von Treueparametern. Der Thread wiederholt die Anfrage, bis die Parameter heruntergeladen werden 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 Treueparameter speichern und löschen

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

Diese Funktion ist nur im Expertenmodus erforderlich, in dem Treueparameter 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 sendet die folgenden Arten von Anfragen an den Serverendpunkt:

• Bei der Initialisierung wird eine generateTuningParameters-Anfrage gestellt.
• Während des Spiels wird regelmäßig eine uploadTelemetry-Anfrage gesendet, um Daten an den Server zu senden.
• Mit Debug-APKs können auch debugInfo-Anfragen gesendet werden, die einen Debug-Server über die Einstellungen, Standardparameter für die Wiedergabetreue und die dev_tuningfork.proto-Struktur informieren.

Offline-Player

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

Wenn beim Hochladen 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 angeben, werden Uploads als Dateien im temporären Speicher abgelegt.