Dodaj funkcje rejestrowania czasu wczytywania

Pamiętaj, że rejestrowanie zdarzeń wczytywania gry jest ważne z 2 powodów:

1. Aby uniknąć zanieczyszczenia danych o czasie renderowania klatek podczas wczytywania.
2. Analizowanie czasów wczytywania w celu sprawdzenia, kiedy i gdzie czasy wczytywania są dłuższe niż dopuszczalne.

Zdarzenie wczytywania może mieć powiązane metadane:

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;

Wartości w polach, które nie mają związku z Twoimi potrzebami, mogą wynosić 0.

Zdarzenie wczytywania może też mieć powiązaną adnotację. Definiuje się to tak samo jak w przypadku adnotacji czasu renderowania klatki, używając co najmniej jednego pola w wiadomości Annotation w pliku dev_tuningfork.proto.

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

Ta funkcja rozpoczyna rejestrowanie zdarzenia czasu wczytywania powiązanego z podanymi metadanymi i adnotacją oraz wypełnia element handle, który ma być używany w funkcji TuningFork_stopRecordingLoadingTime().

TuningFork_ErrorCode TuningFork_stopRecordingLoadingTime( TuningFork_LoadingEventHandle handle);

Ta funkcja zatrzymuje rejestrowanie zdarzenia rozpoczętego wcześniej przez TuningFork_startRecordingLoadingTime(). Zdarzenie jest przesyłane przy opróżnieniu następnej sesji.

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

Zdecydowanie zalecamy bezpośrednie użycie opisanych powyżej funkcji uruchamiania i zatrzymywania. Jeśli jednak nie możesz tego zrobić, możesz wywołać tę funkcję, aby zarejestrować czas trwania oraz powiązane z nim metadane i adnotację.

Wczytuję funkcje grupy

Ostrzeżenie: wszystkie zdarzenia wczytywania muszą być częścią grupy wczytywania.

W swojej grze możesz zarejestrować kilka zdarzeń wczytywania w 1 okresie wczytywania dla użytkownika. Może to być między innymi wczytywanie plików, dekompresja i kompilacja programu do cieniowania.

Pamiętaj, żeby poinformować Tuning Fork, że zdarzenia wczytywania są częścią takiej grupy, ponieważ dzięki temu może ona dostarczać lepsze statystyki. Aby to zrobić, umieść zdarzenia wczytywania w zestawach z poniższymi funkcjami uruchamiania i zatrzymywania.

Uwaga: aktywna może być tylko jedna grupa ładowania naraz.

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

Ta funkcja uruchamia grupę wczytywania powiązaną z podanymi metadanymi i adnotacją oraz wypełnia element handle, który ma być użyty w funkcji TuningFork_stopLoadingGroup(). Metadane i adnotacja nie są obecnie używane przez backend Google Play i można je ustawić na nullptr. Wszystkie kolejne zdarzenia wczytywania będą otagowane unikalnym identyfikatorem grupy.

TuningFork_ErrorCode TuningFork_stopLoadingGroup( TuningFork_LoadingEventHandle handle);

Ta funkcja zatrzymuje grupę wczytywania, która została wcześniej uruchomiona przez TuningFork_startLoadingGroup(). Kolejne zdarzenia wczytywania nie będą miały identyfikatora grupy, dopóki nie zostanie ponownie wywołany element TuningFork_startLoadingGroup().

Rysunek 1. Przykład grupy wczytywania.