Используйте функции из этого раздела, чтобы интегрировать библиотеку Tuning Fork в код игры.
Заголовочный файл include/tuningfork/tuningfork.h содержит основной интерфейс библиотеки Tuning Fork. Файл include/tuningfork/tuningfork_extra.h содержит служебные функции.
Некоторые функции выполняют сериализацию буферов протокола. Дополнительную информацию об использовании буферов протокола в игре см. в разделе «О буферах протокола» .
Параметры функции и возвращаемые значения описаны в заголовках и справочной документации API .
Функции жизненного цикла Android Performance Tuner
Используйте следующие функции для управления жизненным циклом экземпляра Tuning Fork.
Инициализировать
TFErrorCode TuningFork_init(const TFSettings* settings, JNIEnv* env, jobject context);
Вы должны вызвать эту функцию один раз при запуске, обычно из собственного кода, выполняемого методом onCreate() приложения. Он выделяет данные, необходимые библиотеке Tuning Fork.
У вас должен быть файл tuningfork_settings.bin в assets/tuningfork вашего приложения, который содержит настройки гистограммы и аннотаций. Чтобы преобразовать текстовый файл в двоичный, см. раздел Текст и двоичные представления .
Поля, которые вы заполняете в settings определяют, как библиотека инициализирует себя.
/**
* @brief Initialization settings
* Zero any values that are not being used.
*/
struct TFSettings {
/**
* Cache object to be used for upload data persistence.
* If unset, data is persisted to /data/local/tmp/tuningfork
*/
const TFCache* persistent_cache;
/**
* The address of the Swappy_injectTracers function.
* If this is unset, you need to call TuningFork_tick explicitly.
* If it is set, telemetry for 4 instrument keys is automatically recorded.
*/
SwappyTracerFn swappy_tracer_fn;
/**
* Callback
* If set, this is called with the fidelity parameters that are downloaded.
* If unset, you need to call TuningFork_getFidelityParameters explicitly.
*/
ProtoCallback fidelity_params_callback;
/**
* A serialized protobuf containing the fidelity parameters to be uploaded
* for training.
* Set this to nullptr if you are not using training mode. Note that these
* are used instead of the default parameters loaded from the APK, if they
* are present and there are neither a successful download nor saved parameters.
*/
const CProtobufSerialization* training_fidelity_params;
/**
* A null-terminated UTF-8 string containing the endpoint that Tuning Fork
* will connect to for parameter, upload, and debug requests. This overrides
* the value in base_uri in the settings proto and is intended for debugging
* purposes only.
*/
const char* endpoint_uri_override;
/**
* The version of Swappy that swappy_tracer_fn comes from.
*/
uint32_t swappy_version;
/**
* The number of each metric that is allowed to be allocated at any given
* time. If any element is zero, the default for that metric type is used.
* Memory for all metrics is allocated up-front at initialization. When all
* metrics of a given type are allocated, further requested metrics are not
* added and data is lost.
*/
TuningFork_MetricLimits max_num_metrics;
};
Если вы передаете функцию Swappy_injectTracer() ( OpenGL , Vulkan ) из API кадровой синхронизации при инициализации, библиотека Tuning Fork автоматически записывает время кадра без вашего явного вызова функций тика. Это делается в демо-приложении:
void InitTf(JNIEnv* env, jobject activity) {
SwappyGL_init(env, activity);
swappy_enabled = SwappyGL_isEnabled();
TFSettings settings {};
if (swappy_enabled) {
settings.swappy_tracer_fn = &SwappyGL_injectTracer;
settings.swappy_version = Swappy_version();
}
...
}
Разрушать
TFErrorCode TuningFork_destroy();
Вы можете вызвать эту функцию при выключении. Эта функция пытается отправить все сохраненные на данный момент данные гистограммы для последующей загрузки перед освобождением памяти, используемой библиотекой Tuning Fork.
Румянец
TFErrorCode TuningFork_flush();
Эта функция сбрасывает записанные гистограммы (например, когда игра отправляется на задний или передний план). Данные не сбрасываются, если минимальный период загрузки, по умолчанию равный одной минуте, не истек с момента предыдущей загрузки.
Установите параметры точности
TFErrorCode TuningFork_setFidelityParameters(const CProtobufSerialization* params);
Эта функция переопределяет текущие параметры точности, с которыми связаны данные кадра. Эту функцию следует вызывать, когда игрок вручную меняет настройки качества игры.
Аннотации
TFErrorCode TuningFork_setCurrentAnnotation(const CProtobufSerialization* annotation);
Эта функция устанавливает аннотацию, которая будет связана с последующими тиками. Он возвращает TFERROR_INVALID_ANNOTATION , если произошла ошибка при декодировании аннотации, и TFERROR_OK если ошибки не было.
Покадровые функции
TFErrorCode TuningFork_frameTick(TFInstrumentKey key);
Эта функция записывает время между предыдущим тактом с данным key и текущим временем на гистограмме, связанной с key и текущей аннотацией.
TFErrorCode TuningFork_frameDeltaTimeNanos(TFInstrumentKey key, TFDuration dt);
Эта функция записывает длительность в гистограмму, связанную с key и текущей аннотацией.
TFErrorCode TuningFork_startTrace(TFInstrumentKey key, TraceHandle* handle);
Эта функция устанавливает дескриптор дескриптора трассировки, связанного с данным key .
TFErrorCode TuningFork_endTrace(TraceHandle handle);
Эта функция записывает интервал времени с момента соответствующего вызова TuningFork_startTrace() в гистограмме, связанной с использованным key и текущей аннотацией.
Функции жизненного цикла приложения
typedef enum TuningFork_LifecycleState {
TUNINGFORK_STATE_UNINITIALIZED = 0,
TUNINGFORK_STATE_ONCREATE = 1,
TUNINGFORK_STATE_ONSTART = 2,
TUNINGFORK_STATE_ONSTOP = 3,
TUNINGFORK_STATE_ONDESTROY = 4,
} TuningFork_LifecycleState;
TFErrorCode TuningFork_reportLifecycleEvent(TuningForkLifecycleState state);
Вызовите эту функцию из соответствующих методов жизненного цикла в основной Activity вашей игры, передав соответствующее перечисление. Записывая события жизненного цикла игры, APT может лучше понять, когда ваша игра может давать сбой или когда пользователи могут выйти из нее (например, во время длительной загрузки).
Расширенные функции
Следующие функции доступны в tuningfork_extra.h .
Найдите и загрузите файлы в APK
Эта функция загружает fidelityParams из каталога assets/tuningfork APK с заданным именем файла. fidelityParams должен быть сериализацией сообщения FidelityParams . Дополнительные сведения см. в разделе Определение уровней качества .
Право собственности на сериализацию передается вызывающему объекту, который должен вызвать CProtobufSerialization_Free , чтобы освободить всю удерживаемую память.
Параметры верности скачивайте в отдельной теме.
Активирует поток загрузки для получения параметров точности. Поток повторяет запрос до тех пор, пока не загрузятся параметры или не истечет таймаут. Загруженные параметры хранятся локально. Когда приложение перезапускается, оно использует эти загруженные параметры, а не параметры по умолчанию.
Сохранение и удаление параметров точности, хранящихся на устройстве.
Эта функция необходима только в экспертном режиме, когда параметры точности загружаются с сервера. Он либо сохраняет, либо удаляет (если fidelity_params имеет значение null) локально хранящиеся файлы, которые используются, когда сервер недоступен.
Веб-запросы
Библиотека отправляет следующие виды запросов к конечной точке сервера:
-
generateTuningParametersделается при инициализации. - Во время игры периодически выполняется запрос
uploadTelemetryдля отправки данных на сервер. - APK-файлы отладки также могут отправлять запросы
debugInfo, которые информируют сервер отладки о настройках, параметрах точности по умолчанию и структуреdev_tuningfork.proto.
Оффлайн игроки
Если при инициализации доступное соединение отсутствует, запрос повторяется несколько раз с увеличением времени задержки.
Если при загрузке нет соединения, загрузка кэшируется. Вы можете предоставить свой собственный механизм кэширования, передав объект TFCache при инициализации. Если вы не предоставляете собственный кеш, загрузки сохраняются в виде файлов во временном хранилище.