Ajouter des fonctions d'enregistrement du temps de chargement

Il est important d'enregistrer les périodes où votre jeu effectue des chargements pour deux raisons :

1. Pour éviter de contaminer vos données de temps de rendu pendant les chargements
2. Pour analyser les temps de chargement et déterminer dans quels cas ils dépassent les limites acceptables

Un événement de chargement peut être associé à différentes métadonnées :

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;

Vous pouvez affecter une valeur nulle à tous les champs qui ne sont pas adaptés à vos besoins.

Un événement de chargement peut également être associé à une annotation. Il se définit de la même manière que les annotations de temps de rendu, à l'aide d'un ou de plusieurs champs dans le message Annotation du fichier dev_tuningfork.proto.

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

Cette fonction enregistre un événement de temps de chargement associé aux métadonnées et annotations données, puis remplit le paramètre handle à utiliser dans la fonction TuningFork_stopRecordingLoadingTime().

TuningFork_ErrorCode TuningFork_stopRecordingLoadingTime( TuningFork_LoadingEventHandle handle);

Cette fonction met fin à l'enregistrement d'un événement démarré par TuningFork_startRecordingLoadingTime(). L'événement est importé lors du vidage provoqué par la session suivante.

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

Nous vous recommandons vivement d'utiliser directement les fonctions de démarrage et d'arrêt décrites précédemment. Toutefois, si cela s'avère impossible, vous pouvez appeler cette fonction pour enregistrer une durée ainsi que les métadonnées et annotations associées.

Fonctions pour les groupes de chargement

Avertissement : Tous les événements de chargement doivent faire partie d'un groupe de chargement.

Dans votre jeu, vous pouvez enregistrer plusieurs événements de chargement pour une seule période de chargement visible par l'utilisateur. Voici quelques exemples (liste non exhaustive) : chargement de fichiers, décompression et compilation de nuanceurs.

Il est important d'informer Tuning Fork que les événements de chargement font partie d'un tel groupe afin de permettre à cet outil d'offrir des insights plus pertinents. Pour ce faire, mettez entre crochets les événements de chargement à l'aide des fonctions de démarrage et d'arrêt ci-dessous.

Remarque : Un seul groupe de chargement peut être actif à la fois.

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

Cette fonction lance un groupe de chargement associé aux métadonnées et annotations fournies, et renseigne le champ handle à utiliser dans la fonction TuningFork_stopLoadingGroup(). Les métadonnées et les annotations ne sont actuellement pas utilisées par le backend Play et peuvent être définies sur nullptr. Tous les événements de chargement ultérieurs sont associés à un même identifiant de groupe.

TuningFork_ErrorCode TuningFork_stopLoadingGroup( TuningFork_LoadingEventHandle handle);

Cette fonction arrête un groupe de chargement précédemment démarré par TuningFork_startLoadingGroup(). Les événements de chargement ultérieurs n'auront pas d'identifiant de groupe tant que TuningFork_startLoadingGroup() ne sera pas rappelé.

Figure 1. Exemple de groupe de chargement.