เพิ่มฟังก์ชันการบันทึกเวลาที่ใช้ในการโหลด

คุณควรบันทึกเมื่อเกมแสดงเหตุการณ์การโหลดด้วยเหตุผล 2 ประการต่อไปนี้

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;

ฟิลด์ใดก็ตามที่ไม่เกี่ยวข้องกับความต้องการของคุณสามารถเป็น 0 ได้

เหตุการณ์การโหลดอาจมีคำอธิบายประกอบที่เชื่อมโยงด้วย ซึ่งกำหนดในลักษณะเดียวกับคำอธิบายประกอบเวลาเฟรม โดยใช้ฟิลด์อย่างน้อย 1 รายการในข้อความ 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);

เราขอแนะนำเป็นอย่างยิ่งให้ใช้ฟังก์ชันเริ่มและหยุด ที่อธิบายไว้ก่อนหน้านี้โดยตรง แต่หากทำไม่ได้ คุณสามารถเรียกใช้ฟังก์ชันนี้ เพื่อบันทึกระยะเวลาและข้อมูลเมตาและคำอธิบายประกอบที่เกี่ยวข้อง

กำลังโหลดฟังก์ชันกลุ่ม

ในเกม คุณอาจบันทึกเหตุการณ์การโหลดหลายรายการสำหรับระยะเวลาการโหลดเดียว ที่ผู้ใช้เห็น ตัวอย่างบางส่วน ได้แก่ (แต่ไม่จำกัดเพียง) การโหลดไฟล์ การคลายการบีบอัด และการคอมไพล์ Shader

คุณควรแจ้งให้ Tuning Fork ทราบว่าเหตุการณ์การโหลดเป็นส่วนหนึ่งของกลุ่มดังกล่าวเพื่อให้ 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 ตัวอย่างกลุ่มการโหลด