إضافة دوال توقيت الإطار

استخدِم الدوال الواردة في هذا الموضوع لدمج مكتبة Tuning Fork في رمز لعبتك.

يحتوي ملف العنوان في include/tuningfork/tuningfork.h على الواجهة الأساسية لمكتبة Tuning Fork. يحتوي الملف في include/tuningfork/tuningfork_extra.h على دوال مساعدة.

تتلقّى عدة دوال عمليات تسلسلية لمخازن البروتوكول. لمزيد من المعلومات حول استخدام مخازن البروتوكول في لعبتك، راجِع لمحة عن مخازن البروتوكول.

يتم توضيح مَعلمات الدالة والقيم التي تعرضها في العناوين ومستندات واجهة برمجة التطبيقات المرجعية.

وظائف دورة حياة أداة Android Performance Tuner

استخدِم الدوال التالية للتحكّم في دورة حياة مثيل Tuning Fork.

تهيئة

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

يجب استدعاء هذه الدالة مرة واحدة عند بدء التشغيل، وعادةً ما يتم ذلك من داخل الرمز البرمجي الأصلي الذي يتم تنفيذه بواسطة طريقة onCreate() في التطبيق. يخصّص هذا الإذن البيانات التي تحتاجها مكتبة Tuning Fork.

يجب أن يتوفّر ملف tuningfork_settings.bin في assets/tuningfork داخل تطبيقك، ويحتوي على إعدادات الرسم البياني الشريطي والتعليقات التوضيحية. لتحويل ملف نصي إلى ملف ثنائي، راجِع التمثيلات النصية مقابل الثنائية.

تحدّد الحقول التي تملأها 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) من واجهة برمجة التطبيقات Frame Pacing API عند بدء التشغيل، تسجّل مكتبة Tuning Fork وقت عرض اللقطة تلقائيًا بدون الحاجة إلى استدعاء دوال tick بنفسك. يتم ذلك في التطبيق التجريبي باتّباع الخطوات التالية:

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

ملاحظة: من المهم للغاية تحديد إصدار Swappy الذي تستخدمه في الحقل swappy_version من TFSettings. يضمن ذلك أن يتمكّن TuningFork من تفسير البيانات التي يتم تلقّيها من عمليات معاودة الاتصال في Swappy.

تدمير

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

تسجّل هذه الدالة الفاصل الزمني منذ استدعاء TuningFork_startTrace() المرتبط في المدرّج التكراري المرتبط بـ key الذي تم استخدامه والتعليق التوضيحي الحالي.

وظائف مراحل نشاط التطبيق

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

استدعِ هذه الدالة من طرق مراحل النشاط المناسبة في Activity الرئيسية للعبتك، مع تمرير التعداد المناسب. من خلال تسجيل أحداث مراحل نشاط اللعبة، يصبح APT أكثر قدرة على معرفة الوقت الذي قد تتعطّل فيه لعبتك أو الوقت الذي قد يغادر فيه المستخدمون (على سبيل المثال، أثناء أحداث التحميل الطويلة).

الدوال المتقدمة

تتوفّر الدوال التالية في tuningfork_extra.h.

العثور على الملفات وتحميلها في حزمة APK

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

تحمّل هذه الدالة fidelityParams من الدليل assets/tuningfork في حزمة APK التي تحمل اسم الملف المحدّد. يجب أن يكون 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 هي null).

طلبات الويب

تُرسِل المكتبة الأنواع التالية من الطلبات إلى نقطة نهاية الخادم:

• يتم إرسال طلب generateTuningParameters عند بدء عملية الإعداد.
• أثناء اللعب، يتم إرسال طلب uploadTelemetry بشكل دوري لإرسال البيانات إلى الخادم.
• يمكن لملفات APK المخصّصة لتصحيح الأخطاء إرسال طلبات debugInfo أيضًا، ما يتيح إبلاغ خادم تصحيح الأخطاء بالإعدادات ومعلمات الدقة التلقائية وبنية dev_tuningfork.proto.

اللاعبون بلا إنترنت

إذا لم يتوفّر اتصال عند بدء التشغيل، تتم إعادة محاولة الطلب عدة مرات مع زيادة وقت التراجع.

إذا لم يكن هناك اتصال بالإنترنت عند التحميل، يتم تخزين عملية التحميل مؤقتًا. يمكنك توفير آلية التخزين المؤقت الخاصة بك من خلال تمرير عنصر TFCache عند بدء التشغيل. في حال عدم توفير ذاكرة تخزين مؤقت خاصة بك، يتم تخزين عمليات التحميل كملفات في مساحة تخزين مؤقتة.