Funkcje omówione w tym temacie pozwolą Ci zintegrować bibliotekę Tuning Fork z kodem gry.
Plik nagłówkowy pod adresem include/tuningfork/tuningfork.h zawiera podstawowy interfejs biblioteki Tuning Fork. Plik include/tuningfork/tuningfork_extra.h zawiera funkcje narzędziowe.
Kilka funkcji przyjmuje serializację buforów protokołów. Więcej o używaniu buforów protokołów w grze znajdziesz w artykule Informacje o buforach protokołów.
Parametry funkcji i zwracane wartości zostały objaśnione w nagłówkach i dokumentacji interfejsu API.
Funkcje cyklu życia narzędzia Android Performance Tuner
Użyj poniższych funkcji, aby kontrolować cykl życia instancji Tuning Fork.
Zainicjuj
TFErrorCode TuningFork_init(const TFSettings* settings, JNIEnv* env, jobject
context);
Funkcję tę należy wywołać raz przy uruchomieniu, zwykle z poziomu kodu natywnego wykonywanego w aplikacji za pomocą metody onCreate(). Alokuje dane potrzebne
przez bibliotekę Tuing Fork.
W Twojej aplikacji musi byćtuningfork_settings.bin plik zawierający ustawienia histogramu i adnotacji.assets/tuningfork Aby przekonwertować plik tekstowy na plik binarny, przeczytaj sekcję Reprezentacje tekstowe i binarne.
Pola, które wypełnisz w settings, określają, jak biblioteka się inicjuje.
/**
* @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 przekazujesz funkcję Swappy_injectTracer() (OpenGL, Vulkan) z interfejsu Frame Pacing API, biblioteka Tuning Fork automatycznie rejestruje czas renderowania klatki bez konieczności samodzielnego wywoływania tych funkcji. 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();
Tę funkcję możesz wywołać przy wyłączeniu. Ta funkcja próbuje przesłać wszystkie aktualnie przechowywane dane histogramu do późniejszego przesłania przed zwolnieniem pamięci wykorzystywanej przez bibliotekę Tuning Fork.
Strumień
TFErrorCode TuningFork_flush();
Ta funkcja usuwa zarejestrowane histogramy (np. gdy gra jest wysyłana na tło lub na pierwszy plan). Dane nie są usuwane, jeśli od ostatniego przesłania nie upłynął minimalny okres przesyłania, który jest domyślnie ustawiony na minutę.
Ustaw parametry wierności
TFErrorCode TuningFork_setFidelityParameters(const CProtobufSerialization*
params);
Ta funkcja zastępuje bieżące parametry wierności, z którymi są powiązane dane ramki. Funkcję tę należy wywoływać, gdy gracz ręcznie zmieni ustawienia jakości gry.
Adnotacje
TFErrorCode TuningFork_setCurrentAnnotation(const CProtobufSerialization*
annotation);
Ta funkcja powoduje powiązanie adnotacji z kolejnymi znacznikami. Zwraca TFERROR_INVALID_ANNOTATION, jeśli dekodowanie adnotacji wystąpił błąd, lub TFERROR_OK, jeśli nie wystąpił błąd.
Funkcje na ramkę
TFErrorCode TuningFork_frameTick(TFInstrumentKey key);
Ta funkcja rejestruje czas między poprzednim znacznikiem z podanym key a bieżącą godziną w histogramie powiązanym z key a bieżącą adnotacją.
TFErrorCode TuningFork_frameDeltaTimeNanos(TFInstrumentKey key, TFDuration
dt);
Ta funkcja rejestruje czas trwania na histogramie powiązanym z parametrem key i bieżącą adnotacją.
TFErrorCode TuningFork_startTrace(TFInstrumentKey key, TraceHandle* handle);
Ta funkcja ustawia nick dla uchwytu śledzenia powiązanego z danym elementem key.
TFErrorCode TuningFork_endTrace(TraceHandle handle);
Ta funkcja rejestruje przedział czasu od powiązanego wywołania TuningFork_startTrace() na histogramie powiązanym z używanym key oraz 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łaj tę funkcję z odpowiednich metod cyklu życia w głównej aktywności gry, przekazując odpowiednią wartość wyliczeniową. Rejestrując zdarzenia cyklu życia gry, APT może lepiej zrozumieć, kiedy gra może ulegać awariom lub kiedy użytkownicy ją wychodzą (np. podczas długiego wczytywania).
Funkcje zaawansowane
Poniższe funkcje są dostępne w tuningfork_extra.h.
Znajdowanie i wczytywanie plików w pakiecie APK
Ta funkcja wczytuje fidelityParams z katalogu assets/tuningfork w pliku APK o podanej nazwie. fidelityParams musi być zserializacją
wiadomości FidelityParams. Więcej informacji znajdziesz w artykule Definiowanie poziomów jakości.
Własność serializacji jest przekazywana do elementu wywołującego, który musi wywołać CProtobufSerialization_Free, aby zwolnić zatrzymaną pamięć.
Pobierz parametry wierności w osobnym wątku
Aktywuje wątek pobierania w celu pobrania parametrów wierności. Wątek ponawia żądanie, aż do pobrania parametrów lub upłynięcia czasu oczekiwania. Pobrane parametry są przechowywane lokalnie. Po ponownym uruchomieniu aplikacja będzie używać tych pobranych parametrów zamiast domyślnych.
Zapisz i usuń parametry wierności przechowywane na urządzeniu
Ta funkcja jest potrzebna tylko w trybie eksperta, w którym parametry wierności są pobierane z serwera. Spowoduje to zapisanie lub usunięcie (jeśli fidelity_params ma wartość null) plików przechowywanych lokalnie, które są używane, gdy serwer jest nieosiągalny.
Żądania sieciowe
Biblioteka wysyła do punktu końcowego serwera te rodzaje żądań:
- Podczas inicjowania jest wysyłane żądanie
generateTuningParameters. - Podczas rozgrywki okresowo wysyłane jest żądanie
uploadTelemetry, aby wysłać dane na serwer. - Pliki APK debugowania mogą też wysyłać żądania
debugInfo, które przekazują serwerowi debugowania informacje o ustawieniach, domyślnych parametrach wierności i strukturzedev_tuningfork.proto.
Odtwarzacze offline
Jeśli podczas inicjowania nie ma dostępnego połączenia, żądanie jest ponawiane kilka razy z dłuższym czasem ponowienia.
Jeśli podczas przesyłania nie uda się nawiązać połączenia, przesyłanie zostanie zapisane w pamięci podręcznej. Możesz udostępnić własny mechanizm buforowania, przekazując podczas inicjowania obiekt TFCache. Jeśli nie udostępnisz własnej pamięci podręcznej, przesłane pliki będą przechowywane jako pliki w pamięci tymczasowej.