फ़्रेम टाइमिंग से जुड़े फ़ंक्शन जोड़ें

इस विषय में दिए गए फ़ंक्शन का इस्तेमाल करके, Tuning Fork लाइब्रेरी को अपने गेम कोड में इंटिग्रेट करें.

include/tuningfork/tuningfork.h पर मौजूद हेडर फ़ाइल में, Tuning Fork लाइब्रेरी के लिए मुख्य इंटरफ़ेस शामिल होता है. include/tuningfork/tuningfork_extra.h पर मौजूद फ़ाइल में यूटिलिटी फ़ंक्शन शामिल हैं.

कई फ़ंक्शन, प्रोटोकॉल बफ़र के सीरियलाइज़ेशन का इस्तेमाल करते हैं. अपने गेम में प्रोटोकॉल बफ़र का इस्तेमाल करने के बारे में ज़्यादा जानने के लिए, प्रोटोकॉल बफ़र के बारे में जानकारी लेख पढ़ें.

फ़ंक्शन के पैरामीटर और दिखाई गई वैल्यू के बारे में हेडर और रेफ़रंस एपीआई दस्तावेज़ में बताया गया है.

Android Performance Tuner के लाइफ़साइकल फ़ंक्शन

TuningFork इंस्टेंस के लाइफ़साइकल को कंट्रोल करने के लिए, इन फ़ंक्शन का इस्तेमाल करें.

शुरू करें

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

आपको इस फ़ंक्शन को स्टार्टअप के दौरान एक बार कॉल करना होगा. आम तौर पर, इसे ऐप्लिकेशन के onCreate() तरीके से लागू किए गए नेटिव कोड से कॉल किया जाता है. यह Tuning Fork लाइब्रेरी के लिए ज़रूरी डेटा को असाइन करता है.

आपके ऐप्लिकेशन में assets/tuningfork फ़ोल्डर में tuningfork_settings.bin फ़ाइल मौजूद होनी चाहिए. इसमें हिस्टोग्राम और एनोटेशन की सेटिंग शामिल होती हैं. टेक्स्ट फ़ाइल को बाइनरी में बदलने के लिए, टेक्स्ट बनाम बाइनरी फ़ॉर्मैट लेख पढ़ें.

settings में भरी गई वैल्यू से यह तय होता है कि लाइब्रेरी खुद को कैसे शुरू करेगी.

/**
 * @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;
};

अगर आपने शुरू करने के दौरान, फ़्रेम पेसिंग एपीआई से Swappy_injectTracer() फ़ंक्शन (OpenGL, Vulkan) पास किया है, तो Tuning Fork लाइब्रेरी फ़्रेम के समय को अपने-आप रिकॉर्ड करती है. इसके लिए, आपको खुद से टिक फ़ंक्शन को कॉल करने की ज़रूरत नहीं होती. यह डेमो ऐप्लिकेशन में किया जाता है:

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();
   }
...
}

नष्ट करें

TFErrorCode TuningFork_destroy();

इस फ़ंक्शन को शट-डाउन के समय कॉल किया जा सकता है. यह फ़ंक्शन, फ़िलहाल सेव किए गए सभी हिस्टोग्राम डेटा को बाद में अपलोड करने के लिए सबमिट करता है. ऐसा, Tuning Fork लाइब्रेरी की ओर से इस्तेमाल की गई किसी भी मेमोरी को डीऐलोकेट करने से पहले किया जाता है.

Flush

TFErrorCode TuningFork_flush();

यह फ़ंक्शन, रिकॉर्ड किए गए हिस्टोग्राम को फ़्लश करता है. उदाहरण के लिए, जब गेम को बैकग्राउंड या फ़ोरग्राउंड में भेजा जाता है. अगर पिछले अपलोड के बाद से, अपलोड करने की कम से कम अवधि (डिफ़ॉल्ट रूप से एक मिनट) पूरी नहीं हुई है, तो यह डेटा को फ़्लश नहीं करता है.

फ़िडेलिटी पैरामीटर सेट करना

TFErrorCode TuningFork_setFidelityParameters(const CProtobufSerialization* params);

यह फ़ंक्शन, फ़्रेम डेटा से जुड़े मौजूदा फ़िडेलिटी पैरामीटर को बदल देता है. जब कोई खिलाड़ी मैन्युअल तरीके से गेम की क्वालिटी सेटिंग बदलता है, तब आपको इस फ़ंक्शन को कॉल करना चाहिए.

एनोटेशन

TFErrorCode TuningFork_setCurrentAnnotation(const CProtobufSerialization* annotation);

यह फ़ंक्शन, बाद के टिक से जोड़ने के लिए एनोटेशन सेट करता है. अगर एनोटेशन को डीकोड करने में कोई गड़बड़ी हुई है, तो यह TFERROR_INVALID_ANNOTATION दिखाता है. अगर कोई गड़बड़ी नहीं हुई है, तो यह TFERROR_OK दिखाता है.

हर फ़्रेम के हिसाब से फ़ंक्शन

TFErrorCode TuningFork_frameTick(TFInstrumentKey key);

यह फ़ंक्शन, दिए गए key के साथ पिछले टिक और मौजूदा समय के बीच के समय को रिकॉर्ड करता है. यह समय, key और मौजूदा एनोटेशन से जुड़े हिस्टोग्राम में रिकॉर्ड किया जाता है.

TFErrorCode TuningFork_frameDeltaTimeNanos(TFInstrumentKey key, TFDuration dt);

यह फ़ंक्शन, key और मौजूदा एनोटेशन से जुड़े हिस्टोग्राम में अवधि रिकॉर्ड करता है.

TFErrorCode TuningFork_startTrace(TFInstrumentKey key, TraceHandle* handle);

यह फ़ंक्शन, दिए गए key से जुड़े ट्रेस हैंडल के लिए एक हैंडल सेट करता है.

TFErrorCode TuningFork_endTrace(TraceHandle handle);

यह फ़ंक्शन, key से जुड़े हिस्टोग्राम में TuningFork_startTrace() कॉल के बाद से लेकर मौजूदा एनोटेशन तक के समय अंतराल को रिकॉर्ड करता है.

ऐप्लिकेशन के लाइफ़साइकल फ़ंक्शन

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);

अपने गेम की मुख्य ऐक्टिविटी में, लाइफ़साइकल के सही तरीकों से इस फ़ंक्शन को कॉल करें. साथ ही, सही enum पास करें. गेम के लाइफ़साइकल इवेंट रिकॉर्ड करके, APT को यह बेहतर तरीके से पता चल पाता है कि आपका गेम कब क्रैश हो सकता है या उपयोगकर्ता कब गेम छोड़ सकते हैं. उदाहरण के लिए, लंबे समय तक लोड होने वाले इवेंट के दौरान.

उन्‍नत फ़ंक्‍शन

tuningfork_extra.h में ये फ़ंक्शन उपलब्ध हैं.

किसी APK में फ़ाइलें ढूंढना और लोड करना

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

यह फ़ंक्शन, दिए गए फ़ाइल नाम वाले APK में मौजूद assets/tuningfork डायरेक्ट्री से fidelityParams लोड करता है. fidelityParams, FidelityParams मैसेज का सीरियलाइज़ेशन होना चाहिए. ज़्यादा जानकारी के लिए, क्वालिटी लेवल तय करना लेख पढ़ें.

सीरियलाइज़ेशन का मालिकाना हक, कॉल करने वाले को ट्रांसफ़र कर दिया जाता है. इसे CProtobufSerialization_Free को कॉल करना होगा, ताकि मेमोरी को डी-एलॉकेट किया जा सके.

फ़िडेलिटी पैरामीटर को अलग थ्रेड पर डाउनलोड करना

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

यह कुकी, फ़िडेलिटी पैरामीटर पाने के लिए डाउनलोड थ्रेड को चालू करती है. थ्रेड, पैरामीटर डाउनलोड होने या टाइम आउट होने तक अनुरोध को फिर से भेजती है. डाउनलोड किए गए पैरामीटर, डिवाइस में सेव किए जाते हैं. ऐप्लिकेशन को फिर से शुरू करने पर, यह डिफ़ॉल्ट पैरामीटर के बजाय डाउनलोड किए गए इन पैरामीटर का इस्तेमाल करता है.

डिवाइस पर सेव किए गए फ़िडेलिटी पैरामीटर सेव करना और मिटाना

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

इस फ़ंक्शन की ज़रूरत सिर्फ़ एक्सपर्ट मोड में होती है. इसमें फ़िडेलिटी पैरामीटर, सर्वर से डाउनलोड किए जाते हैं. यह सर्वर से कनेक्ट न हो पाने पर इस्तेमाल की जाने वाली, स्थानीय तौर पर सेव की गई फ़ाइलों को सेव करता है या मिटाता है (अगर fidelity_params शून्य है).

वेब अनुरोध

यह लाइब्रेरी, सर्वर एंडपॉइंट को इस तरह के अनुरोध भेजती है:

• शुरुआत में, generateTuningParameters का अनुरोध किया जाता है.
• गेमप्ले के दौरान, सर्वर को डेटा भेजने के लिए समय-समय पर uploadTelemetry अनुरोध किया जाता है.
• डीबग किए जा सकने वाले APK भी debugInfo अनुरोध भेज सकते हैं. इनसे डीबग सर्वर को सेटिंग, डिफ़ॉल्ट फ़िडेलिटी पैरामीटर, और debugInfo स्ट्रक्चर के बारे में जानकारी मिलती है.dev_tuningfork.proto

ऑफ़लाइन प्लेयर

अगर शुरुआत में कोई कनेक्शन उपलब्ध नहीं है, तो अनुरोध को कई बार फिर से भेजा जाता है. साथ ही, हर बार अनुरोध भेजने के बीच का समय बढ़ता जाता है.

अगर अपलोड करते समय कोई कनेक्शन नहीं है, तो अपलोड किए गए डेटा को कैश मेमोरी में सेव कर लिया जाता है. शुरुआत में TFCache ऑब्जेक्ट पास करके, अपना खुद का कैश मेमोरी सिस्टम उपलब्ध कराया जा सकता है. अगर आपने अपना कैश नहीं दिया है, तो अपलोड की गई फ़ाइलें कुछ समय के लिए सेव की जाती हैं.