添加加载时间记录功能

记录游戏何时执行加载事件非常重要,原因有两个

  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()启动的加载组。后续加载事件将没有组 ID,直到再次调用TuningFork_startLoadingGroup()

图 1. 加载组的示例。