Определите аннотации, параметры точности и настройки.

В этом документе описывается, как устанавливать аннотации, параметры точности и настройки в вашем проекте.

Аннотации и параметры точности

Аннотации предоставляют контекстную информацию о том, что происходит в вашей игре в момент записи тика. Параметры точности отражают производительность и графические настройки вашей игры. Они определяются с помощью буферов протоколов — структурированного формата обмена данными 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 : количество используемых клавиш инструментирования. Установите значение 4 если используете библиотеку Android Frame Pacing.
  • 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 Wire-Form чётко определён и стабилен в различных версиях 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 . Используйте эту библиотеку в своей игре, если размер кода имеет значение.

Файлы CMake в gamesdk/src/protobuf помогут вам интегрировать все три версии Protobuf. В примерах используется смесь NanoPB и полного Protobuf.