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

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

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

ننصح بشدة باستخدام دالتَي البدء والإيقاف مباشرةً التي وصفناها سابقًا. إذا لم تتمكن من إجراء ذلك، يمكنك استدعاء هذه الدالة لتسجيل مدة والبيانات الوصفية والتعليقات التوضيحية المرتبطة بها.

جارٍ تحميل دوال المجموعة

تحذير: يجب أن تكون جميع أحداث التحميل جزءًا من مجموعة تحميل.

يمكنك في لعبتك تسجيل عدة أحداث تحميل لفترة تحميل واحدة. رؤيتها من قبل المستخدم. تتضمّن بعض الأمثلة (على سبيل المثال لا الحصر) تحميل الملفات وفك الضغط وتجميع أدوات التظليل.

من المهم إعلام "الشوكة الرنانة" بأنّ أحداث التحميل جزء من هذه المجموعة حتى تتمكن من تقديم رؤى أفضل. تحية تحميل الأحداث مع دالتي البدء والإيقاف التالية للقيام بذلك.

ملاحظة: يمكن أن تكون مجموعة تحميل واحدة فقط نشطة في كل مرة.

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