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

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

يحتوي ملف العنوان في include/tuningfork/tuningfork.h على الواجهة الأساسية لمكتبة "الشوكة الرنانة" (Tunning Fork). يحتوي الملف الموجود في include/tuningfork/tuningfork_extra.h على وظائف أداة مساعدة.

هناك عدة دوال تأخذ تسلسلات من مخازن البروتوكولات الاحتياطية. لمزيد من المعلومات حول استخدام الموارد الاحتياطية للبروتوكولات داخل اللعبة، يُرجى الاطّلاع على المقالة لمحة عن الموارد الاحتياطية للبروتوكولات.

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

وظائف مراحل نشاط أداة Android Performance Tuner

استخدِم الدوال التالية للتحكّم في دورة حياة مثيل "الشوكة الرنانة" .

تهيئة

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 عند الإعداد، ستسجّل مكتبة "الشوكة الرنانة" تلقائيًا وقت عرض اللقطة بدون الحاجة إلى استدعاء دالة الدقات بنفسك بشكل صريح. يتم ذلك في التطبيق التجريبي:

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.

وجه متورّد

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

عليك استدعاء هذه الوظيفة من خلال اتّباع طرق دورة الحياة المناسبة في النشاط الرئيسي للعبتك، من خلال تمرير التعداد المناسب. من خلال تسجيل أحداث مراحل نشاط اللعبة، يمكن لخدمة 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 فارغة).

طلبات الويب

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

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

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

وإذا لم يكن هناك اتصال متاح عند التهيئة، تتم إعادة محاولة الطلب عدة مرات مع زيادة وقت التراجع.

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