読み込み時間記録関数の追加

次の 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;

ニーズに関連のないフィールドは、ゼロにできます。

読み込みイベントには、アノテーションを関連付けることもできます。これは、フレーム時間にアノテーションを付けるのと同じ方法で、dev_tuningfork.proto ファイルの Annotation メッセージで 1 つ以上のフィールドを使用して定義されます。

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

上記の開始関数と停止関数を直接使用することを強くおすすめします。これらの関数を使用できない場合でも、この関数を呼び出して、期間とそれに関連するメタデータおよびアノテーションを記録できます。

グループ関数を読み込む

警告: 読み込みイベントはすべて、読み込みグループの一部である必要があります。

ゲームでは、ユーザーが確認する 1 つの読み込み期間に複数の読み込みイベントを記録することがあります。例として、ファイルの読み込み、解凍、シェーダー コンパイルなどが挙げられますが、これらに限定されません。

より適切な分析情報が得られるよう、読み込みイベントがこのようなグループの一部であることを、Tuning Fork に通知することが重要です。これを行うには、読み込みイベントを次の開始関数と停止関数で囲みます。

注: 読み込みグループは一度に 1 つのみ有効にできます。

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() によって開始された読み込みグループを停止します。TuningFork_startLoadingGroup() を再度呼び出すまで、後続の読み込みイベントはグループ ID を持ちません。

図 1. 読み込みグループの例