Dodawanie funkcji czasu renderowania klatki

Skorzystaj z funkcji opisanych w tym artykule, aby zintegrować bibliotekę Tuning Fork z kodem gry.

Plik nagłówkowy w include/tuningfork/tuningfork.h zawiera podstawowy interfejs biblioteki Tuning Fork. Plik w lokalizacji include/tuningfork/tuningfork_extra.h zawiera funkcje narzędziowe.

Kilka funkcji przyjmuje serializacje buforów protokołu. Więcej informacji o używaniu buforów protokołów w grze znajdziesz w artykule Informacje o buforach protokołów.

Parametry funkcji i wartości zwracane są wyjaśnione w nagłówkach i dokumentacji referencyjnej interfejsu API.

Funkcje cyklu życia wtyczki Android Performance Tuner

Do kontrolowania cyklu życia instancji Tuning Fork służą te funkcje.

Zainicjuj

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

Tę funkcję musisz wywołać raz podczas uruchamiania, zwykle z kodu natywnego wykonywanego przez metodę onCreate() aplikacji. Przydziela dane potrzebne bibliotece Tuning Fork.

W aplikacji musi znajdować się plik tuningfork_settings.bin w folderze assets/tuningfork, który zawiera histogram i ustawienia adnotacji. Aby przekonwertować plik tekstowy na binarny, zapoznaj się z sekcją Tekstowe i binarne reprezentacje danych.

Pola, które wypełnisz settings, określają sposób inicjowania biblioteki.

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

Jeśli podczas inicjowania przekażesz funkcję Swappy_injectTracer()(OpenGL, Vulkan) z interfejsu Frame Pacing API, biblioteka Tuning Fork automatycznie rejestruje czas klatki bez konieczności jawnego wywoływania funkcji tick. Możesz to zrobić w aplikacji demonstracyjnej:

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

Zniszcz

TFErrorCode TuningFork_destroy();

Możesz wywołać tę funkcję podczas zamykania. Ta funkcja próbuje przesłać wszystkie aktualnie przechowywane dane histogramu do późniejszego przesłania przed zwolnieniem pamięci używanej przez bibliotekę Tuning Fork.

Bezpośrednio do sufitu

TFErrorCode TuningFork_flush();

Ta funkcja czyści zarejestrowane histogramy (np. gdy gra jest wysyłana w tle lub na pierwszym planie). Nie opróżnia danych, jeśli od poprzedniego przesłania nie minął minimalny okres przesyłania, który domyślnie wynosi minutę.

Ustawianie parametrów wierności

TFErrorCode TuningFork_setFidelityParameters(const CProtobufSerialization* params);

Ta funkcja zastępuje bieżące parametry wierności, z którymi powiązane są dane klatki. Tę funkcję należy wywołać, gdy gracz ręcznie zmieni ustawienia jakości gry.

Adnotacje

TFErrorCode TuningFork_setCurrentAnnotation(const CProtobufSerialization* annotation);

Ta funkcja ustawia adnotację, która ma być powiązana z kolejnymi znacznikami. Zwraca wartość TFERROR_INVALID_ANNOTATION, jeśli podczas dekodowania adnotacji wystąpił błąd, a wartość TFERROR_OK, jeśli nie wystąpił żaden błąd.

Funkcje na klatkę

TFErrorCode TuningFork_frameTick(TFInstrumentKey key);

Ta funkcja rejestruje czas między poprzednim a bieżącym taktem z podanym parametrem key oraz bieżący czas w histogramie powiązanym z parametrem key i bieżącą adnotacją.

TFErrorCode TuningFork_frameDeltaTimeNanos(TFInstrumentKey key, TFDuration dt);

Ta funkcja rejestruje czas trwania w histogramie powiązanym z key i bieżącą adnotacją.

TFErrorCode TuningFork_startTrace(TFInstrumentKey key, TraceHandle* handle);

Ta funkcja ustawia uchwyt na uchwyt śledzenia powiązany z podanym key.

TFErrorCode TuningFork_endTrace(TraceHandle handle);

Ta funkcja rejestruje przedział czasu od wywołania powiązanego z nią wywołania TuningFork_startTrace() w histogramie powiązanym z użytym elementem key i bieżącą adnotacją.

Funkcje cyklu życia aplikacji

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

Wywołuj tę funkcję z odpowiednich metod cyklu życia w głównym działaniu gry, przekazując odpowiedni wyliczenie. Rejestrując zdarzenia cyklu życia gry, APT może lepiej zrozumieć, kiedy gra może się zawieszać lub kiedy użytkownicy mogą ją opuszczać (np. podczas długich zdarzeń ładowania).

Funkcje zaawansowane

W tuningfork_extra.h dostępne są te funkcje:

Znajdowanie i wczytywanie plików w pliku APK

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

Ta funkcja wczytuje fidelityParams z katalogu assets/tuningfork w pliku APK o podanej nazwie. fidelityParams musi być serializacją wiadomości FidelityParams. Więcej informacji znajdziesz w artykule Określanie poziomów jakości.

Własność serializacji jest przekazywana do wywołującego, który musi wywołać funkcję CProtobufSerialization_Free, aby zwolnić pamięć.

Pobieranie parametrów wierności w osobnym wątku

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

Aktywuje wątek pobierania, aby pobrać parametry wierności. Wątek ponawia żądanie, dopóki nie zostaną pobrane parametry lub nie upłynie limit czasu. Pobrane parametry są przechowywane lokalnie. Po ponownym uruchomieniu aplikacja używa pobranych parametrów zamiast domyślnych.

Zapisywanie i usuwanie parametrów wierności przechowywanych na urządzeniu

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

Ta funkcja jest potrzebna tylko w trybie eksperta, w którym parametry wierności są pobierane z serwera. Zapisuje on pliki przechowywane lokalnie, które są używane, gdy serwer jest niedostępny, lub usuwa je (jeśli fidelity_params ma wartość null).

Żądania sieciowe

Biblioteka wysyła do punktu końcowego serwera te rodzaje żądań:

• Podczas inicjowania wysyłane jest żądanie generateTuningParameters.
• Podczas rozgrywki okresowo wysyłane jest uploadTelemetry żądanie przesłania danych na serwer.
• Pliki APK do debugowania mogą też wysyłać żądania debugInfo, które informują serwer debugowania o ustawieniach, domyślnych parametrach wierności i strukturze dev_tuningfork.proto.

Gracze offline

Jeśli podczas inicjowania nie ma dostępnego połączenia, żądanie jest ponawiane kilka razy z coraz dłuższym czasem oczekiwania.

Jeśli podczas przesyłania nie ma połączenia, przesyłanie jest buforowane. Możesz udostępnić własny mechanizm buforowania, przekazując obiekt TFCache podczas inicjowania. Jeśli nie podasz własnej pamięci podręcznej, przesłane pliki będą przechowywane w pamięci tymczasowej.