توابع زمان بندی فریم را اضافه کنید

از توابع موجود در این مبحث برای ادغام کتابخانه Tuning Fork در کد بازی خود استفاده کنید.

فایل هدر در include/tuningfork/tuningfork.h حاوی رابط اصلی برای کتابخانه Tuning Fork است. فایل در include/tuningfork/tuningfork_extra.h شامل توابع ابزار است.

چندین توابع از بافرهای پروتکل سریال سازی می کنند. برای اطلاعات بیشتر در مورد استفاده از بافرهای پروتکل در بازی خود، درباره بافرهای پروتکل را ببینید.

پارامترهای تابع و مقادیر بازگشتی در هدرها و مستندات API مرجع توضیح داده شده است.

عملکردهای چرخه عمر تیونر عملکرد Android

از توابع زیر برای کنترل چرخه عمر یک نمونه 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 به طور خودکار زمان فریم را بدون اینکه خودتان به طور واضح توابع تیک را فراخوانی کنید، ثبت می کند. این کار در برنامه آزمایشی انجام می شود:

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

این تابع را از متدهای چرخه حیات مناسب در 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 تهی باشد) فایل های ذخیره شده محلی را که در زمانی که سرور غیر قابل دسترسی است استفاده می شود.

درخواست های وب

کتابخانه انواع درخواست های زیر را به نقطه پایانی سرور ارسال می کند:

• یک درخواست generateTuningParameters هنگام مقداردهی اولیه ایجاد می شود.
• در طول گیم پلی، یک درخواست uploadTelemetry به صورت دوره ای برای ارسال داده ها به سرور ارسال می شود.
• APK‌های اشکال‌زدایی همچنین می‌توانند درخواست‌های debugInfo را ارسال کنند که به سرور اشکال‌زدایی تنظیمات، پارامترهای پیش‌فرض وفاداری و ساختار dev_tuningfork.proto را اطلاع می‌دهد.

بازیکنان آفلاین

اگر هیچ اتصالی در زمان اولیه وجود نداشته باشد، درخواست چندین بار با افزایش زمان بازگشت مجدد امتحان می شود.

اگر در زمان آپلود اتصال وجود نداشته باشد، آپلود در حافظه پنهان ذخیره می شود. شما می توانید مکانیسم کش خود را با ارسال یک شی TFCache در زمان اولیه ارائه دهید. اگر حافظه پنهان خود را ارائه نکنید، آپلودها به عنوان فایل در حافظه موقت ذخیره می شوند.