Как задать аннотации, параметры изображения и настройки

В этом документе описывается, как задать аннотации, параметры изображения и настройки в проекте.

Аннотации и параметры изображения

Аннотации предоставляют контекстную информацию о том, что происходит в игре во время записи тика. Параметры изображения отражают производительность и графические настройки игры. Они определяются с помощью буферов протокола – разработанного 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.