הוספת פונקציות של תזמון פריימים

אפשר להשתמש בפונקציות שבנושא הזה כדי לשלב את ספריית Tuning Fork בקוד של המשחק.

קובץ הכותרת בכתובת include/tuningfork/tuningfork.h מכיל את ממשק הליבה של ספריית Tuning Fork. הקובץ בכתובת include/tuningfork/tuningfork_extra.h מכיל פונקציות בסיסיות.

כמה פונקציות מקבלות סריאליזציות של מאגרי פרוטוקולים. למידע נוסף על השימוש ב-protocol buffers במשחק, אפשר לעיין במאמר מידע על protocol buffers.

פרמטרים של פונקציות וערכי החזרה מוסברים בכותרות ובמסמכי העזר של ה-API.

פונקציות של מחזור החיים ב-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();
   }
...
}

מחיקה

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

מפעילים את הפונקציה הזו משיטות מחזור החיים המתאימות בפעילות הראשית של המשחק, ומעבירים את ה-enum המתאים. הקלטה של אירועים במחזור החיים של המשחק מאפשרת ל-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 בזמן האתחול. אם לא מספקים מטמון משלכם, ההעלאות נשמרות כקבצים באחסון זמני.