Adicionar funções para gravação do tempo de carregamento

É importante registrar o momento em que seu jogo está carregando eventos por dois motivos:

1. Para evitar poluir os dados de tempo para a renderização do frame durante o carregamento.
2. Para analisar os tempos de carregamento e saber quando e onde eles são mais longos do que o aceitável.

Um evento de carregamento pode ter metadados associados:

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;

Todos os campos que não sejam relevantes para suas necessidades podem ser definidos como zero.

Um evento de carregamento também pode ter uma anotação associada. Isso é definido da mesma forma que as anotações do tempo para renderização do frame, usando um ou mais campos na mensagem Annotation no arquivo dev_tuningfork.proto.

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

Essa função inicia a gravação de um evento de tempo de carregamento associado aos metadados e anotações fornecidos e preenche um handle para ser usado na função TuningFork_stopRecordingLoadingTime().

TuningFork_ErrorCode TuningFork_stopRecordingLoadingTime( TuningFork_LoadingEventHandle handle);

Essa função interrompe a gravação de um evento iniciada anteriormente por TuningFork_startRecordingLoadingTime(). O upload do evento é feito na próxima limpeza de sessão.

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

Recomendamos que você use diretamente as funções de início e parada descritas anteriormente. Se isso não é possível, você pode chamar essa função para registrar uma duração e os metadados e anotações associados a ela.

Como carregar as funções de grupo

Aviso: todos os eventos de carregamento precisam fazer parte de um grupo de carregamento.

No seu jogo, você pode registrar vários eventos de carregamento para um único período de carregamento encontrado pelo usuário. Alguns exemplos incluem, entre outros, o carregamento de arquivos, a descompressão e compilação do sombreador.

É importante informar à biblioteca Tuning Fork que os eventos de carregamento fazem parte desse grupo para que ela possa fornecer insights melhores. Coloque os eventos de carregamento entre colchetes com as seguintes funções de início e parada para fazer isso.

Observação: apenas um grupo de carregamento pode estar ativo por vez.

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

Essa função inicia um grupo de carregamento associado aos metadados e anotações fornecidos e preenche um handle para ser usado na função TuningFork_stopLoadingGroup(). Os metadados e a anotação atualmente não são usados pelo back-end do Play e podem ser definidos como nullptr. Todos os eventos de carregamento subsequentes terão uma tag com um ID de grupo exclusivo.

TuningFork_ErrorCode TuningFork_stopLoadingGroup( TuningFork_LoadingEventHandle handle);

Essa função interrompe um grupo de carregamento iniciado anteriormente por TuningFork_startLoadingGroup(). Os próximos eventos de carregamento não vão ter um ID de grupo até que a função TuningFork_startLoadingGroup() seja chamada novamente.

Figura 1. Exemplo de grupo de carregamento.