Dodawanie funkcji czasu renderowania klatki

Użyj funkcji opisanych w tym temacie, aby zintegrować bibliotekę Tuning Fork do kodu gry.

Plik nagłówka pod adresem include/tuningfork/tuningfork.h zawiera główny interfejs dla biblioteki Tuning Fork. Plik pod adresem include/tuningfork/tuningfork_extra.h zawiera funkcje użytkowe.

Kilka funkcji wymaga serializacji buforów protokołów. Więcej informacji o korzystaniu bufory protokołów w grze, zobacz Informacje o buforach protokołów

Parametry funkcji i zwracane wartości zostały objaśnione w nagłówkach i referencyjną dokumentację interfejsu API.

Funkcje cyklu życia narzędzia Android Performance Tuner

Użyj poniższych funkcji do sterowania cyklem życia kamerdynera instancji.

Zainicjuj

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

Musisz wywołać tę funkcję raz przy uruchamianiu, zwykle w obrębie kodu natywnego. wykonywane przez metodę onCreate() aplikacji. Alokuje dane potrzebne Biblioteka Tuning Fork.

Musisz mieć plik tuningfork_settings.bin dostępny w: assets/tuningfork która zawiera ustawienia histogramu i adnotacji. Do przekonwertować plik tekstowy na binarny, patrz Reprezentacje tekstowe a reprezentacje binarne.

Pola, które wypełnisz w polu 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 przekażesz funkcję Swappy_injectTracer() (OpenGL, Vulkan) z interfejsu Frame Pacing API przy inicjowaniu, z biblioteki Tuning Fork automatycznie rejestruje czas renderowania klatki bez wyraźnego wywoływania znacznika z różnych funkcji. Możesz to zrobić w aplikacji w wersji 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łączaniu. Ta funkcja próbuje przesłać wszystkie aktualnie zapisane dane histogramu do późniejszego przesłania przed zwolnieniem dowolnej pamięci używane przez bibliotekę Tuning Fork.

Opróżnij

TFErrorCode TuningFork_flush();

Ta funkcja opróżnia zarejestrowane histogramy (na przykład gdy gra jest (wysyłane w tle lub na pierwszy plan). Nie usuwa danych, jeśli minimalna wartość okres przesyłania, który domyślnie wynosi jedną minutę, jeszcze nie minął od z poprzedniej wersji.

Ustawianie parametrów wierności

TFErrorCode TuningFork_setFidelityParameters(const CProtobufSerialization* params);

Ta funkcja zastępuje bieżące parametry wierności, z którymi dane ramki są powiązane treści. Należy wywołać tę funkcję, gdy odtwarzacz ręcznie zmieni ustawieniach jakości gry.

Adnotacje

TFErrorCode TuningFork_setCurrentAnnotation(const CProtobufSerialization* annotation);

Ta funkcja ustawia adnotację do powiązania z kolejnymi znacznikami. Zwraca TFERROR_INVALID_ANNOTATION, jeśli wystąpił błąd z dekodowaniem adnotacji i TFERROR_OK, jeśli nie wystąpił błąd.

Funkcje dla poszczególnych klatek

TFErrorCode TuningFork_frameTick(TFInstrumentKey key);

Ta funkcja rejestruje czas między poprzednim taktem określonym key oraz bieżącą godzinę na histogramie powiązanym z parametrem key i bieżącym adnotacja.

TFErrorCode TuningFork_frameDeltaTimeNanos(TFInstrumentKey key, TFDuration dt);

Ta funkcja rejestruje czas trwania na histogramie powiązanym z parametrem key i parametrem bieżącej adnotacji.

TFErrorCode TuningFork_startTrace(TFInstrumentKey key, TraceHandle* handle);

Ta funkcja ustawia uchwyt do śledzenia powiązanego z danym elementem key.

TFErrorCode TuningFork_endTrace(TraceHandle handle);

Ta funkcja rejestruje przedział czasu od momentu TuningFork_startTrace() na histogramie powiązanym z użytym key i bieżącym adnotacja.

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łówna Aktywność gry, zaliczanie odpowiednią wyliczanie. Rejestrując zdarzenia cyklu życia gry, narzędzie APT Zrozumienie, kiedy gra może się zawieszać lub kiedy użytkownicy mogą wyjść z gry (np. podczas zdarzeń długotrwałego wczytywania).

Funkcje zaawansowane

Poniższe funkcje są dostępne w tuningfork_extra.h.

Znajdowanie i wczytywanie plików w pakiecie APK

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

Ta funkcja wczytuje fidelityParams z katalogu assets/tuningfork w pakiet APK o podanej nazwie. fidelityParams musi być serializacją elementu FidelityParams wiadomość. Więcej informacji: Określ poziomy jakości.

Własność serializacji jest przekazywana do elementu wywołującego, który musi wywołać CProtobufSerialization_Free w celu przydzielenia zablokowanej pamięci.

Pobierz parametry 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 próbę do momentu pobrania parametrów lub upłynięcia czasu oczekiwania. Pobrane parametry są przechowywanych lokalnie. Po ponownym uruchomieniu aplikacja używa tych pobranych parametrów a nie domyślnych.

Zapisywanie i usuwanie parametrów wierności zapisanych 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 pobrane z serwera. Zapisuje się lub usuwa (jeśli fidelity_params wynosi null) lokalnie przechowywane pliki, które są używane, gdy serwer jest nieosiągalny.

Żądania sieciowe

Biblioteka wysyła do punktu końcowego serwera następujące rodzaje żądań:

• Żądanie generateTuningParameters jest wysyłane podczas inicjowania.
• Podczas gry co jakiś czas wysyłane jest żądanie uploadTelemetry, aby wysłać przesyłać dane do serwera.
• Pliki APK debugowania mogą też wysyłać żądania debugInfo, które informują serwer debugowania ustawień, domyślnych parametrów wierności oraz dev_tuningfork.proto do jego struktury.

Gracze offline

Jeśli w momencie inicjowania nie ma dostępnego połączenia, żądanie jest wykonywane ponownie z coraz dłuższym czasem do ponowienia.

Jeśli w momencie przesyłania nie ma połączenia, przesyłanie jest zapisywane w pamięci podręcznej. Możesz podać własny mechanizm buforowania, przekazując TFCache obiektu podczas inicjowania. Jeśli nie podasz własnej pamięci podręcznej, przesyłanie będzie jako pliki w pamięci tymczasowej.