Tuning Fork kitaplığını oyun kodunuza entegre etmek için bu konudaki işlevleri kullanın.
include/tuningfork/tuningfork.h adresindeki başlık dosyası, Tuning Fork kitaplığının temel arayüzünü içerir. include/tuningfork/tuningfork_extra.h adresindeki dosya yardımcı işlevler içeriyor.
Birkaç işlev, protokol arabelleklerinin serileştirilmiş biçimlerini alır. Oyununuzda protokol arabelleklerini kullanma hakkında daha fazla bilgi için Protokol arabellekleri hakkında başlıklı makaleyi inceleyin.
İşlev parametreleri ve dönüş değerleri, başlıklarda ve referans API belgelerinde açıklanmıştır.
Android Performance Tuner yaşam döngüsü işlevleri
Bir Tuning Fork örneğinin yaşam döngüsünü kontrol etmek için aşağıdaki işlevleri kullanın.
Başlat
TFErrorCode TuningFork_init(const TFSettings* settings, JNIEnv* env, jobject
context);
Bu işlevi, genellikle uygulamanın onCreate() yöntemi tarafından yürütülen yerel kodun içinden olmak üzere başlangıçta bir kez çağırmanız gerekir. Tuning Fork kitaplığı için gereken verileri ayırır.
Uygulamanızda, histogram ve açıklama ayarlarını içeren bir tuningfork_settings.bin dosyası bulunmalıdır.assets/tuningfork Metin dosyasını ikiliye dönüştürmek için Metin ve ikili gösterimler başlıklı makaleyi inceleyin.
Doldurduğunuz alanlar settings kitaplığın nasıl başlatılacağını belirler.
/**
* @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;
};
Başlatma sırasında Frame Pacing API'den Swappy_injectTracer() işlevini (OpenGL, Vulkan) iletirseniz Tuning Fork kitaplığı, tick işlevlerini kendiniz açıkça çağırmadan kare süresini otomatik olarak kaydeder. Bu işlem, demo uygulamasında yapılır:
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();
}
...
}
Kaldır
TFErrorCode TuningFork_destroy();
Bu işlevi kapatma sırasında çağırabilirsiniz. Bu işlev, Tuning Fork kitaplığı tarafından kullanılan herhangi bir bellek serbest bırakılmadan önce, şu anda depolanan tüm histogram verilerini daha sonra yüklemek üzere göndermeye çalışır.
Flush
TFErrorCode TuningFork_flush();
Bu işlev, kaydedilen histogramları temizler (örneğin, oyun arka plana veya ön plana gönderildiğinde). Önceki yüklemeden bu yana minimum yükleme süresi (varsayılan olarak bir dakika) geçmediyse verileri temizlemez.
Doğruluk parametrelerini ayarlama
TFErrorCode TuningFork_setFidelityParameters(const CProtobufSerialization*
params);
Bu işlev, kare verilerinin ilişkilendirildiği mevcut doğruluk parametrelerini geçersiz kılar. Bu işlevi, oyuncu oyunun kalite ayarlarını manuel olarak değiştirdiğinde çağırmanız gerekir.
Ek Açıklamalar
TFErrorCode TuningFork_setCurrentAnnotation(const CProtobufSerialization*
annotation);
Bu işlev, sonraki işaretlerle ilişkilendirilecek notu ayarlar. Açıklamanın kodu çözülürken hata oluştuysa TFERROR_INVALID_ANNOTATION, hata oluşmadıysa TFERROR_OK değerini döndürür.
Kare başına işlevler
TFErrorCode TuningFork_frameTick(TFInstrumentKey key);
Bu işlev, verilen key ile önceki işaret arasındaki süreyi key ve mevcut ek açıklamayla ilişkili histogramda kaydeder.
TFErrorCode TuningFork_frameDeltaTimeNanos(TFInstrumentKey key, TFDuration
dt);
Bu işlev, süreyi key ile ilişkili histograma ve mevcut ek açıklamaya kaydeder.
TFErrorCode TuningFork_startTrace(TFInstrumentKey key, TraceHandle* handle);
Bu işlev, belirtilen key ile ilişkili bir izleme işleyicisine işleyici ayarlar.
TFErrorCode TuningFork_endTrace(TraceHandle handle);
Bu işlev, kullanılan key ile ilişkili histogramda bulunan ilişkili TuningFork_startTrace() çağrısından bu yana geçen süreyi ve mevcut ek açıklamayı kaydeder.
Uygulama yaşam döngüsü işlevleri
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);
Bu işlevi, oyununuzun ana Etkinliğindeki uygun yaşam döngüsü yöntemlerinden çağırarak uygun enum'u iletin. APT, oyunun yaşam döngüsü etkinliklerini kaydederek oyununuzun ne zaman kilitlenebileceğini veya kullanıcıların ne zaman oyundan ayrılabileceğini (ör. uzun yükleme etkinlikleri sırasında) daha iyi anlayabilir.
Gelişmiş işlevler
Aşağıdaki işlevler tuningfork_extra.h içinde kullanılabilir.
APK'daki dosyaları bulma ve yükleme
Bu işlev, verilen dosya adına sahip APK'daki assets/tuningfork dizininden fidelityParams dosyasını yükler. fidelityParams, FidelityParams mesajının serileştirilmiş hali olmalıdır. Daha fazla bilgi için Kalite düzeylerini tanımlama başlıklı makaleyi inceleyin.
Serileştirmenin sahipliği, tutulan tüm belleğin serbest bırakılması için CProtobufSerialization_Free işlevini çağırması gereken arayana iletilir.
Doğruluk parametrelerini ayrı bir iş parçacığında indirme
Doğruluk parametrelerini almak için bir indirme iş parçacığını etkinleştirir. İş parçacığı, parametreler indirilene veya zaman aşımı gerçekleşene kadar isteği yeniden dener. İndirilen parametreler yerel olarak saklanır. Uygulama yeniden başlatıldığında varsayılan parametreler yerine indirilen bu parametreler kullanılır.
Cihazda depolanan doğruluk parametrelerini kaydetme ve silme
Bu işlev yalnızca doğruluk parametrelerinin bir sunucudan indirildiği uzman modunda gereklidir. Sunucuya ulaşılamadığında kullanılan yerel olarak depolanmış dosyaları ya üzerine kaydeder ya da siler (fidelity_params boşsa).
Web istekleri
Kitaplık, sunucu uç noktasına aşağıdaki türlerde istekler gönderir:
- Başlatma sırasında bir
generateTuningParametersisteği gönderilir. - Oyun sırasında, sunucuya veri göndermek için düzenli olarak
uploadTelemetryisteği gönderilir. - Hata ayıklama APK'ları, hata ayıklama sunucusunu ayarlarla, varsayılan doğruluk parametreleriyle ve
dev_tuningfork.protoyapısıyla ilgili bilgilendirendebugInfoistekleri de gönderebilir.
Çevrimdışı oyuncular
Başlatma sırasında bağlantı yoksa istek, artan bir geri çekilme süresiyle birkaç kez yeniden denenir.
Yükleme sırasında bağlantı yoksa yükleme önbelleğe alınır. Başlatma sırasında bir TFCache nesnesi ileterek kendi önbelleğe alma mekanizmanızı sağlayabilirsiniz. Kendi önbelleğinizi sağlamazsanız yüklemeler geçici depolama alanında dosya olarak saklanır.