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

مهم است که زمان اجرای رویدادهای بار کردن بازی را به‌دو دلیل ثبت کنید:

  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 پر می‌کند. فراداده و حاشیه‌نویسی توسط باطن Play استفاده نمی‌شود و می‌توان آن را روی nullptr تنظیم کرد. همه رویدادهای بارگیری بعدی با شناسه گروه یکتایی برچسب‌گذاری می‌شوند.

TuningFork_ErrorCode TuningFork_stopLoadingGroup( TuningFork_LoadingEventHandle handle);

این تابع گروه بارگیری را که قبلاً توسط TuningFork_startLoadingGroup() شروع شده است متوقف می‌کند. رویدادهای بارگیری بعدی تا زمانی که TuningFork_startLoadingGroup() دوباره فراخوانی نشود، شناسه گروه نخواهند داشت.

روندنمایی که TuningFork_startLoadingGroup و TuningFork_stopLoadingGroup را نشان می‌دهد که تماس‌های بار کردن دارایی را دربرمی‌گیرد
شکل ۱. نمونه‌ای از گروه بارگیری.