Funktionen zur Aufzeichnung der Ladezeit hinzufügen

Es ist aus zwei Gründen wichtig, aufzuzeichnen, wann in Ihrem Spiel Ladevorgänge ausgeführt werden:

1. So vermeiden Sie, dass Ihre Daten zur Frame-Zeit während des Ladens verunreinigt werden.
2. Ladezeiten analysieren, um herauszufinden, wann und wo sie länger als akzeptabel sind.

Ein Ladevorgang kann mit Metadaten verknüpft sein:

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;

Alle Felder, die für Ihre Anforderungen nicht relevant sind, können null sein.

Ein Ladevorgang kann auch eine zugehörige Anmerkung haben. Sie wird auf dieselbe Weise wie Anmerkungen zur Frame-Zeit definiert, indem ein oder mehrere Felder in der Annotation-Nachricht in der dev_tuningfork.proto-Datei verwendet werden.

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

Mit dieser Funktion wird die Aufzeichnung eines Ladezeitereignisses gestartet, das mit den angegebenen Metadaten und der Annotation verknüpft ist. Außerdem wird ein handle ausgefüllt, das in der Funktion TuningFork_stopRecordingLoadingTime() verwendet werden kann.

TuningFork_ErrorCode TuningFork_stopRecordingLoadingTime( TuningFork_LoadingEventHandle handle);

Mit dieser Funktion wird die Aufzeichnung eines Ereignisses beendet, die zuvor mit TuningFork_startRecordingLoadingTime() gestartet wurde. Das Ereignis wird beim nächsten Session-Flush hochgeladen.

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

Wir empfehlen dringend, die oben beschriebenen Start- und Stoppfunktionen direkt zu verwenden. Wenn das nicht möglich ist, können Sie diese Funktion aufrufen, um eine Dauer und die zugehörigen Metadaten und Anmerkungen aufzuzeichnen.

Gruppenfunktionen werden geladen

In Ihrem Spiel können Sie mehrere Ladeereignisse für einen einzelnen Ladezeitraum aufzeichnen, der für den Nutzer sichtbar ist. Beispiele hierfür sind das Laden von Dateien, die Dekomprimierung und die Shader-Kompilierung.

Es ist wichtig, Tuning Fork darüber zu informieren, dass Ladeereignisse Teil einer solchen Gruppe sind, damit bessere Statistiken bereitgestellt werden können. Dazu müssen Sie die Ladevorgänge mit den folgenden Start- und Stoppfunktionen in Klammern setzen.

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

Mit dieser Funktion wird eine Ladegruppe gestartet, die mit den angegebenen Metadaten und Anmerkungen verknüpft ist, und ein handle wird ausgefüllt, das in der Funktion TuningFork_stopLoadingGroup() verwendet werden soll. Die Metadaten und Anmerkungen werden derzeit nicht vom Play-Backend verwendet und können auf nullptr gesetzt werden. Alle nachfolgenden Ladevorgänge werden mit einer eindeutigen Gruppen-ID getaggt.

TuningFork_ErrorCode TuningFork_stopLoadingGroup( TuningFork_LoadingEventHandle handle);

Mit dieser Funktion wird eine Ladegruppe beendet, die zuvor mit TuningFork_startLoadingGroup() gestartet wurde. Nachfolgende Ladeereignisse haben erst dann wieder eine Gruppen-ID, wenn TuningFork_startLoadingGroup() noch einmal aufgerufen wird.

Abbildung 1. Beispiel für die Ladegruppe