הוספת פונקציות של הקלטת זמן הטעינה

חשוב לתעד מתי המשחק מבצע אירועי טעינה, משתי סיבות:

1. כדי למנוע זיהום של נתוני זמן המסגרת במהלך הטעינה.
2. כדי לנתח את זמני הטעינה ולראות מתי והיכן זמני הטעינה ארוכים יותר מהזמן המקובל.

לאירוע טעינה יכולים להיות משויכים מטא-נתונים:

typedef struct TuningFork_LoadingTimeMetadata {
    enum LoadingState {
        UNKNOWN_STATE = 0,
        // The first time the game is run
        FIRST_RUN = 1,
        // App is not backgrounded
        COLD_START = 2,
        // App is backgrounded
        WARM_START = 3,
        // App is backgrounded, least work needed
        HOT_START = 4,
        // Asset loading between levels
        INTER_LEVEL = 5
    } state;
    enum LoadingSource {
        UNKNOWN_SOURCE = 0,
        // Uncompressing data.
        MEMORY = 1,
        // Reading assets from APK bundle.
        APK = 2,
        // Reading assets from device storage.
        DEVICE_STORAGE = 3,
        // Reading assets from external storage, e.g. SD card.
        EXTERNAL_STORAGE = 4,
        // Loading assets from the network.
        NETWORK = 5,
        // Shader compilation.
        SHADER_COMPILATION = 6,
        // Time spent between process starting and onCreate.
        PRE_ACTIVITY = 7,
        // Total time spent between process starting and first render frame.
        FIRST_TOUCH_TO_FIRST_FRAME = 8
    } source;
    int32_t compression_level;  // 0 = no compression, 100 = max compression
    enum NetworkConnectivity {
        UNKNOWN = 0,
        WIFI = 1,
        CELLULAR_NETWORK = 2
    } network_connectivity;
    uint64_t network_transfer_speed_bps;  // bandwidth in bits per second
    uint64_t network_latency_ns;          // latency in nanoseconds
} TuningFork_LoadingTimeMetadata;

אם יש שדות שלא רלוונטיים לצרכים שלכם, אפשר להזין בהם אפס.

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

TuningFork_ErrorCode TuningFork_startRecordingLoadingTime( const TuningFork_LoadingTimeMetadata* eventMetadata, uint32_t eventMetadataSize, const TuningFork_CProtobufSerialization* annotation, TuningFork_LoadingEventHandle* handle);

הפונקציה הזו מתחילה להקליט אירוע של זמן טעינה שמשויך למטא-נתונים ולהערה שצוינו, וממלאת את הערך handle לשימוש בפונקציה TuningFork_stopRecordingLoadingTime().

TuningFork_ErrorCode TuningFork_stopRecordingLoadingTime( TuningFork_LoadingEventHandle handle);

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

TuningFork_ErrorCode TuningFork_recordLoadingTime( uint64_t time_ns, const TuningFork_LoadingTimeMetadata* eventMetadata, uint32_t eventMetadataSize, const TuningFork_CProtobufSerialization* annotation);

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

טעינת פונקציות של קבוצות

אזהרה: כל אירועי הטעינה צריכים להיות חלק מקבוצת טעינה.

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

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

הערה: אפשר להפעיל רק קבוצה אחת של טעינה בכל פעם.

TuningFork_ErrorCode TuningFork_startLoadingGroup( const TuningFork_LoadingTimeMetadata* eventMetadata, uint32_t eventMetadataSize, const TuningFork_CProtobufSerialization* annotation, TuningFork_LoadingEventHandle* handle);

הפונקציה הזו מתחילה קבוצת טעינה שמשויכת למטא-נתונים ולהערה שצוינו, וממלאת את handle כדי להשתמש בה בפונקציה TuningFork_stopLoadingGroup(). בשלב הזה, ה-backend של Play לא משתמש במטא-נתונים ובאנוטציות, ואפשר להגדיר אותם ל-nullptr. כל אירועי הטעינה הבאים יתויגו באמצעות מזהה קבוצה ייחודי.

TuningFork_ErrorCode TuningFork_stopLoadingGroup( TuningFork_LoadingEventHandle handle);

הפונקציה הזו מפסיקה קבוצת טעינה שהופעלה קודם על ידי TuningFork_startLoadingGroup(). לאירועי טעינה הבאים לא יהיה מזהה קבוצה עד שתתבצע קריאה נוספת אל TuningFork_startLoadingGroup().

איור 1. דוגמה לקבוצת הטעינה.