Используйте функции из этого раздела для интеграции библиотеки 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 Frame Pacing, библиотека 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 при инициализации. Если собственный кэш не предоставлен, загрузки сохраняются в виде файлов во временном хранилище.