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

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

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

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

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

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

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

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

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

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

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

TuningFork_ErrorCode TuningFork_stopLoadingGroup( TuningFork_LoadingEventHandle handle);

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

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