В этом документе описывается, как задать аннотации, параметры изображения и настройки в проекте.
Аннотации и параметры изображения
Аннотации предоставляют контекстную информацию о том, что происходит в игре во время записи тика. Параметры изображения отражают производительность и графические настройки игры. Они определяются с помощью буферов протокола – разработанного Google формата обмена структурированными данными, который не зависит от языка программирования. Подробнее о буферах протокола в играх…
Возможные аннотации и параметры изображения для игры определяются в файле dev_tuningfork.proto, который находится в каталоге assets/tuningfork вашего проекта. Ниже приведен пример из демонстрационного приложения.
syntax = "proto3";
package com.google.tuningfork;
enum InstrumentKey {
CPU = 0;
GPU = 1;
SWAPPY_WAIT = 2;
SWAPPY_SWAP = 3;
CHOREOGRAPHER = 4;
}
enum Level {
// 0 is not a valid value
LEVEL_INVALID = 0;
LEVEL_1 = 1;
LEVEL_2 = 2;
LEVEL_3 = 3;
};
message Annotation {
Level level = 1;
}
message FidelityParams {
int32 num_spheres = 1;
float tesselation_percent = 2;
}
объявлений.
- Пакет должен быть
com.google.tuningfork. - Названия сообщений должны быть именно такими:
AnnotationиFidelityParams. - В аннотациях можно использовать только
enums, определенные в этом файле. - В полях
FidelityParamsможно использовать толькоenums,int32sилиfloats. - Инструмент проверки обеспечивает соблюдение этих правил.
Настройки
Сообщение Settings определяется в tuningfork.proto. Полный пример приведен в следующем файле:
gamesdk/samples/tuningfork/insightsdemo/app/src/main/assets/tuningfork/tuningfork_settings.txt
Настройки игры должны быть заданы в файле tuningfork_settings.txt, который находится в каталоге assets/tuningfork вашего проекта. Вам нужно указать только следующие поля:
aggregation_strategy: сообщение, содержащее следующее:method:TIME_BASEDдля загрузки каждые n миллисекунд илиTICK_BASEDдля загрузки каждые n тактов.intervalms_or_count: n для поляmethod.max_instrumentation_keys– количество тегов тиков. Если вы используете библиотеку Android Frame Pacing, задайте для параметра значение4.annotation_enum_size– необязательное поле, поскольку размер вычисляется при запуске из дескриптора.
api_key– ключ API облачного проекта приложения, который используется для проверки запросов к конечной точке. Чтобы сгенерировать этот ключ, ознакомьтесь с разделом Включение API. Если вlogcatпоявляются ошибки подключения, проверьте правильность ключа API.default_fidelity_parameters_filename– набор параметров изображения, используемый при инициализации (необязательно, если вы задалиtraining_fidelity_paramsв коде).level_annotation_index– индекс номера уровня в полях аннотации (необязательно).
Ниже приведен пример текстового представления.
aggregation_strategy: {method: TIME_BASED, intervalms_or_count: 10000,
max_instrumentation_keys: 5, annotation_enum_size: [3,4]}
api_key: "API-KEY-FROM-GOOGLE-CLOUD-CONSOLE"
default_fidelity_parameters_filename: "dev_tuningfork_fidelityparams_3.bin"
level_annotation_index: 1
Как настроить заметки
Вам нужно вручную добавлять аннотации во время игры. Вы можете увидеть пример этого в демонстрационном приложении, поскольку оно автоматически проходит все уровни игры. Дополнительную информацию вы найдете в описании функции SetAnnotations() в insightsdemo.cpp.
В этом случае в аннотации указывается только номер уровня.
message Annotation {
Level level = 1;
}
Определите уровни качества
Используйте уровни качества, чтобы аннотировать сеансы. Это позволит вам определить, не слишком ли высок уровень качества на устройствах (что приводит к снижению производительности) или не слишком ли он низок (что приводит к неоправданному снижению точности).
Вам нужно определить хотя бы один уровень качества для игры, но лучше несколько. Уровень качества соответствует экземпляру сообщения FidelityParams. Уровни должны быть указаны в порядке повышения качества изображения. Названия файлов должны иметь следующий формат:
dev_tuningfork_fidelityparams_i.txt
где i – индекс, начинающийся с 1 и имеющий максимальное значение 15. Эти файлы должны находиться в каталоге assets/tuningfork вашего проекта. Пример такой структуры можно найти в каталоге gamesdk/samples/tuningfork/insightsdemo/app/src/main/assets/tuningfork/.
О буферах протоколов
Библиотека Tuning Fork использует формат буфера протокола Google для настроек, аннотаций и параметров изображения. Это четко определенный многоязычный протокол для расширяемых структурированных данных. Дополнительную информацию можно найти в документации по буферам протокола.
Proto2 и proto3
Версия формата буфера протокола указывается в первой строке файла:
syntax="proto2";
Proto2 и proto3 – это две часто используемые версии буферов протокола. Оба используют один и тот же формат передачи, но файлы определений несовместимы. Основные различия между двумя версиями перечислены ниже.
- Ключевые слова
optionalиrequiredбольше не поддерживаются в proto3. - В proto3 все поля фактически являются
optional. - Расширения не поддерживаются в proto3.
Используйте proto3 в файлах proto, поскольку их можно компилировать в C#. Proto2 также работает с ограниченным набором функций, используемых в библиотеке Tuning Fork.
Текстовое и двоичное представление
Двоичный формат передачи protobuf четко определен и стабилен в разных версиях protobuf (в отличие от сгенерированного кода). Также существует текстовый формат, который может генерировать и читать полная версия библиотеки protobuf. Этот формат не так четко определен, но он стабилен для ограниченного набора функций в библиотеке Tuning Fork. Для преобразования двоичного формата в текстовый и наоборот можно использовать компилятор protoc. Следующая команда преобразует текстовый protobuf в двоичный:
protoc --encode com.google.tuningfork.Settings tuningfork.proto < tuningfork_settings.txt > tuningfork_settings.bin
В APK-файл необходимо включить двоичные, а не текстовые файлы, поскольку размер полной библиотеки protobuf составляет несколько мегабайт. Если библиотека Tuning Fork будет зависеть от нее, размер игры увеличится примерно на столько же.
Full, Lite и Nano
Помимо полной библиотеки protobuf, существует облегченная версия, которая уменьшает объем кода за счет удаления некоторых функций, таких как отражение, FileDescriptors и потоковая передача в текстовые форматы и из них. Для этой версии по-прежнему требуется несколько МБ дополнительного кода, поэтому библиотека Tuning Fork использует библиотеку nanopb. Исходный код этой библиотеки включен в Android Open Source Project в external/nanopb-c и является частью ветви gamesdk. Используйте эту библиотеку в своей игре, если размер кода имеет значение.
В gamesdk/src/protobuf есть файлы CMake, которые помогут вам интегрировать все три версии protobuf. В примерах используется сочетание nanopb и полного protobuf.