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

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

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