Çerçeve zamanlama işlevleri ekleyin

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

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

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

void TuningFork_startFidelityParamDownloadThread(const CProtobufSerialization* defaultParams, ProtoCallback fidelity_params_callback);

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

TFErrorCode TuningFork_saveOrDeleteFidelityParamsFile(JNIEnv* env, jobject context, const CProtobufSerialization* fidelity_params);

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 ve dev_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.