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 için protokol arabelleklerinin serileştirilmesi işlemi uygulanı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öntemi tarafından çalıştırılan yerel kod içinden çağırmanız gerekir. Toning Fork kitaplığının ihtiyaç
duyduğu verileri ayırır.
Uygulamanızda assets/tuningfork
için histogram ve ek açıklama ayarlarını içeren bir tuningfork_settings.bin
dosyası bulunmalıdır. Metin dosyasını ikili biçimlere dönüştürmek için Metin ve ikili gösterimler karşılaştırması bölümünü inceleyin.
settings
doldurduğunuz alanlar, kitaplığın kendini nasıl başlatacağı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'sinden Swappy_injectTracer()
işlevini (OpenGL, Vulkan) geçirirseniz Tuning Fork kitaplığı, onay işlevlerini sizin açıkça çağırmanıza gerek kalmadan 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 kapanma sırasında çağırabilirsiniz. Bu işlev, Tuning Fork kitaplığı tarafından kullanılan belleğin yerini ayırmadan önce, hâlihazırda depolanmış olan tüm histogram verilerini daha sonra yüklenmek üzere göndermeye çalışır.
Sifonlu
TFErrorCode TuningFork_flush();
Bu işlev, kaydedilen histogramları boşaltır (örneğin, oyun arka plana veya ön plana gönderildiğinde). Varsayılan olarak bir dakika olan minimum yükleme süresi bir önceki yüklemenin ardından geçmediyse veriler temizlenmez.
Doğruluk parametrelerini ayarlama
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ğırmalısınız.
Ek Açıklamalar
TFErrorCode TuningFork_setCurrentAnnotation(const CProtobufSerialization*
annotation);
Bu işlev, ek açıklamayı, sonraki onay işaretleriyle ilişkilendirilecek ş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 bir ö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, key
ve geçerli ek açıklama ile ilişkili histogramda süreyi kaydeder.
TFErrorCode TuningFork_startTrace(TFInstrumentKey key, TraceHandle* handle);
Bu işlev, belirli bir key
ile ilişkilendirilmiş iz tutma 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 Etkinlikteki uygun yaşam döngüsü yöntemlerinden uygun enum'u ileterek çağırın. APT, oyunun yaşam döngüsü olaylarını kaydederek oyununuzun ne zaman kilitlenebileceğini veya kullanıcıların ne zaman kapatabileceğini (örneğin, uzun yükleme etkinlikleri sırasında) daha iyi anlayabilir.
Gelişmiş işlevler
Aşağıdaki işlevler tuningfork_extra.h
ürününde kullanılabilir.
Bir APK'da dosyaları bulma ve yükleme
Bu işlev, belirtilen dosya adıyla APK'daki assets/tuningfork
dizininden fidelityParams
öğesini yükler. fidelityParams
, bir FidelityParams
mesajının serileştirilmesi 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 kişinin, tutulan belleği dağıtmak için CProtobufSerialization_Free
yöntemini çağırması gerekir.
Doğruluk parametrelerini ayrı bir iş parçacığında indir
Doğruluk parametrelerini almak için bir indirme iş parçacığını etkinleştirir. İş parçacığı, parametreler indirilinceye veya zaman aşımına uğrayana 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 depolanan 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
generateTuningParameters
isteği yapılır. - Oyun sırasında sunucuya veri göndermek için düzenli aralıklarla
uploadTelemetry
isteği yapılır. - Hata ayıklama APK'ları
debugInfo
istekleri de gönderebilir. Bu istekler hata ayıklama sunucusuna ayarlar, varsayılan doğruluk parametreleri vedev_tuningfork.proto
yapısı hakkında bilgi verir.
Çevrimdışı oynatıcılar
Başlatma sırasında kullanılabilir 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.