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

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

يحتوي ملف الرأس في include/tuningfork/tuningfork.h على الواجهة الأساسية لمكتبة Toning 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 عند الإعداد، ستسجّل مكتبة 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();
   }
...
}

ملاحظة: من المهم تحديد إصدار 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 عند الإعداد. إذا لم توفر ذاكرة التخزين المؤقت الخاصة بك، سيتم تخزين التحميلات كملفات في مساحة التخزين المؤقتة.