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

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

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

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

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

פונקציות מחזור החיים של Android Performance Tur

אפשר להשתמש בפונקציות הבאות כדי לשלוט במחזור החיים של מזלג כוונון מכונה.

התחל

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

צריך לקרוא לפונקציה הזו פעם אחת בהפעלה, בדרך כלל מתוך קוד נייטיב מבוצעת באמצעות method 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 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 מפרשים את הנתונים שחוזרים מהקריאות החוזרות (callbacks) של 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);

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

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

שמירה ומחיקה של פרמטרים של דיוק ששמורים במכשיר

TFErrorCode TuningFork_saveOrDeleteFidelityParamsFile(JNIEnv* env, jobject context, const CProtobufSerialization* fidelity_params);

הפונקציה הזו נדרשת רק במצב מתקדם כאשר הפרמטרים של האיכות שהורד משרת. הוא שומר או נמחק (אם fidelity_params הוא null) הקבצים המאוחסנים באופן מקומי שבהם נעשה שימוש כאשר לא ניתן לגשת לשרת.

בקשות אינטרנט

הספרייה שולחת אל נקודת הקצה של השרת בקשות מהסוגים הבאים:

• נשלחת בקשת generateTuningParameters בזמן האתחול.
• במהלך המשחק, נשלחת מדי פעם בקשת uploadTelemetry לשליחה לשרת.
• חבילות APK לניפוי באגים יכולות לשלוח גם בקשות debugInfo, שמיידעות את שרת ניפוי הבאגים של ההגדרות, הפרמטרים של רמת הדיוק שמוגדרים כברירת מחדל ו-dev_tuningfork.proto שלנו.

שחקנים במצב אופליין

אם אין חיבור זמין בזמן האתחול, יש ניסיון חוזר של הבקשה מספר פעמים עם זמן השהיה הולך וגדל.

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