Aggiungi funzioni di registrazione del tempo di caricamento

È importante registrare quando il gioco esegue eventi di caricamento per due motivi:

  1. Per evitare di alterare i dati sulla durata frame durante il caricamento.
  2. Per analizzare i tempi di caricamento e vedere quando e dove sono più lunghi del previsto.

A un evento di caricamento possono essere associati metadati:

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;

I campi non pertinenti alle tue esigenze possono essere impostati su zero.

A un evento di caricamento può anche essere associata un'annotazione. Questo viene definito nello stesso modo delle annotazioni della durata frame, utilizzando uno o più campi nel messaggio Annotation nel file dev_tuningfork.proto.

TuningFork_ErrorCode TuningFork_startRecordingLoadingTime( const TuningFork_LoadingTimeMetadata* eventMetadata, uint32_t eventMetadataSize, const TuningFork_CProtobufSerialization* annotation, TuningFork_LoadingEventHandle* handle);

Questa funzione avvia la registrazione di un evento di tempo di caricamento associato ai metadati e all'annotazione specificati e compila un handle da utilizzare nella funzione TuningFork_stopRecordingLoadingTime().

TuningFork_ErrorCode TuningFork_stopRecordingLoadingTime( TuningFork_LoadingEventHandle handle);

Questa funzione interrompe la registrazione di un evento avviato in precedenza da TuningFork_startRecordingLoadingTime(). L'evento viene caricato al successivo svuotamento della sessione.

TuningFork_ErrorCode TuningFork_recordLoadingTime( uint64_t time_ns, const TuningFork_LoadingTimeMetadata* eventMetadata, uint32_t eventMetadataSize, const TuningFork_CProtobufSerialization* annotation);

Ti consigliamo vivamente di utilizzare direttamente le funzioni di avvio e arresto descritte in precedenza. Se non puoi farlo, puoi chiamare questa funzione per registrare una durata e i relativi metadati e annotazioni.

Caricamento delle funzioni di gruppo in corso…

Nel tuo gioco, potresti registrare diversi eventi di caricamento per un singolo periodo di caricamento visualizzato dall'utente. Alcuni esempi includono, a titolo esemplificativo, il caricamento di file, la decompressione e la compilazione di shader.

È importante informare Tuning Fork che gli eventi di caricamento fanno parte di un gruppo di questo tipo, in modo che possa fornire insight migliori. Per farlo, racchiudi gli eventi di caricamento tra le seguenti funzioni di avvio e interruzione.

TuningFork_ErrorCode TuningFork_startLoadingGroup( const TuningFork_LoadingTimeMetadata* eventMetadata, uint32_t eventMetadataSize, const TuningFork_CProtobufSerialization* annotation, TuningFork_LoadingEventHandle* handle);

Questa funzione avvia un gruppo di caricamento associato ai metadati e all'annotazione specificati e compila un handle da utilizzare nella funzione TuningFork_stopLoadingGroup. I metadati e l'annotazione non vengono utilizzati dal backend di Play e possono essere impostati su nullptr. Tutti gli eventi di caricamento successivi sono contrassegnati da un ID gruppo univoco.

TuningFork_ErrorCode TuningFork_stopLoadingGroup( TuningFork_LoadingEventHandle handle);

Questa funzione interrompe un gruppo di caricamento avviato in precedenza da TuningFork_startLoadingGroup(). Gli eventi di caricamento successivi non avranno un ID gruppo finché non viene richiamato di nuovo TuningFork_startLoadingGroup().

Diagramma di flusso che mostra TuningFork_startLoadingGroup e TuningFork_stopLoadingGroup che racchiudono le chiamate di caricamento degli asset
Figura 1. Esempio di gruppo di caricamento.