إضافة دوال تسجيل مدة التحميل

من المهم تسجيل عندما تنفِّذ لعبتك أحداث تحميل لسببَين:

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() مرة أخرى.

الشكل 1. مثال على مجموعة التحميل