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

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

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

تأخذ العديد من الدوال تسلسلات المخازن المؤقتة للبروتوكولات. لمزيد من المعلومات حول استخدام الموارد الاحتياطية للبروتوكول في لعبتك، راجِع لمحة عن المخازن المؤقتة للبروتوكولات

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

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

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

تهيئة

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

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

يجب أن يكون لديك ملف 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 عند التهيئة، مكتبة 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();
   }
...
}

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

التدمير

TFErrorCode TuningFork_destroy();

يمكنك استدعاء هذه الدالة عند إيقاف التشغيل. تحاول هذه الدالة إرسال جميع بيانات المدرّج التكراري المخزنة حاليًا لتحميلها لاحقًا قبل توزيع أي ذاكرة التي تستخدمها مكتبة الشوكة الرنانة.

وجه محمّر الخدود

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