添加加载时间记录功能

记录游戏执行加载事件的时间很重要，原因有两个

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;

任何与您的需求无关的字段都可以为零。

加载事件还可以具有关联的批注。这与帧时间批注的定义方式相同，使用 dev_tuningfork.proto 文件中的 Annotation 消息中的一个或多个字段。

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。所有后续加载事件都将由唯一的组 ID 进行标记。

TuningFork_ErrorCode TuningFork_stopLoadingGroup( TuningFork_LoadingEventHandle handle);

此函数停止以前由 TuningFork_startLoadingGroup() 启动的加载组。在再次调用 TuningFork_startLoadingGroup() 之前，后续加载事件将没有组 ID。

图 1. 加载组的示例。