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ı program işlevleri içerir.
Bazı işlevler, protokol arabelleklerinin serileştirilmesini alır. Oyununuzda protokol arabellekleri kullanma hakkında daha fazla bilgi için Protokol arabellekleri hakkında bölümüne bakın.
İş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 başlangıçta bir kez, genellikle uygulamanın onCreate() yöntemiyle yürütülen yerel koddan çağırmanız gerekir. Toning Fork kitaplığının
ihtiyaç duyduğu verileri dağıtır.
Uygulamanızdaki assets/tuningfork içinde, histogram ve ek açıklama ayarlarını içeren bir tuningfork_settings.bin dosyası bulunmalıdır. Metin dosyasını ikili biçime dönüştürmek için Metin ve ikili temsillerin karşılaştırılması bölümünü inceleyin.
settings doldurduğunuz alanlar 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) geçirirseniz Tuning Fork kitaplığı, siz onay işlevini açıkça çağırmadan kare süresini otomatik olarak kaydeder. Bu işlem, demo uygulamasında gerçekleştirilir:
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();
}
...
}
Yok etme
TFErrorCode TuningFork_destroy();
Bu işlevi kapatıldığında çağırabilirsiniz. Bu işlev, Tuning Fork kitaplığı tarafından kullanılan herhangi bir belleğin yerini bulmadan önce, şu anda depolanmış olan tüm histogram verilerini daha sonra yükleme için göndermeyi dener.
Sifon
TFErrorCode TuningFork_flush();
Bu işlev, kaydedilen histogramları temizler (örneğin, oyun arka plana veya ön plana gönderildiğinde). Varsayılan olarak bir dakika olan minimum yükleme süresi önceki yüklemeden beri geçmediyse verileri temizlemez.
Doğruluk parametrelerini ayarlayın
TFErrorCode TuningFork_setFidelityParameters(const CProtobufSerialization*
params);
Bu işlev, çerçeve verilerinin ilişkilendirildiği mevcut doğruluk parametrelerini geçersiz kılar. Bir oyuncu oyunun kalite ayarlarını manuel olarak değiştirdiğinde bu işlevi çağırmanız gerekir.
Ek Açıklamalar
TFErrorCode TuningFork_setCurrentAnnotation(const CProtobufSerialization*
annotation);
Bu işlev, ek açıklamayı sonraki değer çizgileriyle ilişkilendirecek şekilde ayarlar. Ek açıklamanın kodu çözülürken hata oluştuysa TFERROR_INVALID_ANNOTATION, hata yoksa TFERROR_OK değerini döndürür.
Kare başına işlevler
TFErrorCode TuningFork_frameTick(TFInstrumentKey key);
Bu işlev, belirtilen key değerine sahip önceki onay işareti ile histogramdaki key ile ilişkilendirilmiş geçerli saat ve geçerli ek açıklama arasındaki süreyi kaydeder.
TFErrorCode TuningFork_frameDeltaTimeNanos(TFInstrumentKey key, TFDuration
dt);
Bu işlev, süreyi key ve geçerli ek açıklamayla ilişkili histograma kaydeder.
TFErrorCode TuningFork_startTrace(TFInstrumentKey key, TraceHandle* handle);
Bu işlev, belirli bir key ile ilişkili izleme yerine bir herkese açık kullanıcı adı ayarlar.
TFErrorCode TuningFork_endTrace(TraceHandle handle);
Bu işlev, kullanılan key ve geçerli ek açıklamayla ilişkilendirilmiş histogramdaki ilişkili TuningFork_startTrace() çağrısından bu yana geçen zaman aralığını 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 Activity'sindeki uygun yaşam döngüsü yöntemlerinden uygun enum'u ileterek çağırın. Oyunun yaşam döngüsü olaylarının kaydedilmesi, APT'nin oyununuzun ne zaman çöktüğünü veya kullanıcıların ne zaman bırakabileceğini (örneğin, uzun yükleme etkinlikleri sırasında) daha iyi anlamasını sağlar.
Gelişmiş işlevler
Aşağıdaki işlevler tuningfork_extra.h ürününde kullanılabilir.
Bir APK'da dosya bulma ve yükleme
Bu işlev, fidelityParams'yi belirtilen dosya adıyla APK'daki assets/tuningfork dizininden yükler. fidelityParams, FidelityParams mesajının seri işlemi olmalıdır. Daha fazla bilgi için Kalite seviyelerini tanımlama bölümüne bakın.
Serileştirmenin sahipliği, arayana iletilir. Arayanın, bekletilen belleği dağıtması için CProtobufSerialization_Free yöntemini çağırması gerekir.
Doğruluk parametrelerini ayrı bir iş parçacığında indir
Kalite parametrelerini almak için bir indirme iş parçacığını etkinleştirir. İş parçacığı, parametre indirilinceye veya bir zaman aşımı meydana gelene kadar isteği yeniden dener. İndirilen parametreler yerel olarak depolanır. Uygulama yeniden başlatıldığında varsayılan parametreler yerine indirilen bu parametreleri kullanır.
Cihazda depolanan doğruluk parametrelerini kaydedip silin
Bu işlev, yalnızca doğruluk parametrelerinin bir sunucudan indirildiği uzman modunda gereklidir. Sunucuya erişilemediğinde kullanılan ve yerel olarak depolanmış dosyaları kaydeder veya siler (fidelity_params boşsa).
Web istekleri
Kitaplık, sunucu uç noktasına şu türden istekler yapar:
- İlk kullanıma hazırlama sırasında bir
generateTuningParametersisteği yapılır. - Oyun sırasında sunucuya veri göndermek için düzenli aralıklarla
uploadTelemetryisteği yapılır. - Hata ayıklama APK'ları
debugInfoistekleri de gönderebilir. Bu istekler hata ayıklama sunucusuna ayarlar, varsayılan doğruluk parametreleri vedev_tuningfork.protoyapısı hakkında bilgi verir.
Çevrimdışı oynatıcılar
Başlatma sırasında bağlantı yoksa istek, artan geri yükleme 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ındaki dosyalar olarak depolanır.