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

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

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. مثال على مجموعة التحميل