添加加载时间记录函数

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

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

此函数开始记录与给定的元数据和注释关联的加载时间事件，并填充要在 TuningFork_stopRecordingLoadingTime() 函数中使用的 handle。

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

此函数开始与给定的元数据和注释关联的加载组，并填充要在 TuningFork_stopLoadingGroup() 函数中使用的 handle。Play 后端当前不使用元数据和注释，您可以将其设置为 nullptr。所有后续加载事件都将由唯一的组 ID 来标记。

TuningFork_ErrorCode TuningFork_stopLoadingGroup( TuningFork_LoadingEventHandle handle);

此函数停止之前由 TuningFork_startLoadingGroup() 开始的加载组。后续加载事件将没有组 ID，直到再次调用 TuningFork_startLoadingGroup()。

图 1. 加载组的示例。