Cómo agregar funciones de registro de los tiempos de carga

Es importante grabar cuando el juego realiza operaciones de carga por dos motivos:

1. Para evitar contaminar los datos de la latencia de fotogramas durante la carga
2. Para analizar los tiempos de carga a fin de verificar cuándo y dónde son más largos de lo aceptable

Un evento de carga puede tener metadatos asociados:

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;

Los campos que no sean relevantes para tus necesidades pueden ser cero.

Un evento de carga también puede tener una anotación asociada. Se define de la misma manera que las anotaciones de la latencia de fotogramas, mediante uno o más campos en el mensaje Annotation, en el archivo dev_tuningfork.proto.

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

Esta función comienza a registrar un evento de tiempo de carga asociado con la anotación y los metadatos determinados, y completa un elemento handle para usar en la función TuningFork_stopRecordingLoadingTime().

TuningFork_ErrorCode TuningFork_stopRecordingLoadingTime( TuningFork_LoadingEventHandle handle);

Esta función deja de registrar un evento que TuningFork_startRecordingLoadingTime() inició previamente. El evento se carga en la próxima limpieza de la sesión.

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

Te recomendamos encarecidamente que uses, de manera directa, las funciones de inicio y finalización que se describieron antes. Sin embargo, si no puedes hacerlo, puedes llamar a esta función para registrar una duración y sus metadatos y anotación asociados.

Cómo cargar funciones de grupo

Advertencia: Todos los eventos de carga deben ser parte de un grupo de carga.

En tu juego, puedes grabar varios eventos de carga durante un período único de carga que ve el usuario. Algunos ejemplos son, entre otros, la carga de archivos, la descompresión y la compilación de sombreadores.

Es importante informar a Tuning Fork que los eventos de carga son parte de ese grupo para que pueda brindar mejores estadísticas. Para ello, agrupa tus eventos de carga con las siguientes funciones de inicio y finalización.

Nota: Solo un grupo de carga puede estar activo a la vez.

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

Esta función inicia un grupo de carga asociado con la anotación y los metadatos determinados, y completa un elemento handle para usar en la función TuningFork_stopLoadingGroup(). En este momento, el backend de Play no usa los metadatos ni la anotación, y se pueden establecer como nullptr. Todos los eventos de carga posteriores se etiquetarán con un ID de grupo único.

TuningFork_ErrorCode TuningFork_stopLoadingGroup( TuningFork_LoadingEventHandle handle);

Esta función detiene un grupo de carga que TuningFork_startLoadingGroup() inició previamente. Los eventos de carga posteriores no tendrán un ID de grupo hasta que se vuelva a llamar a TuningFork_startLoadingGroup().

Figura 1: Ejemplo del grupo de carga.