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

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

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

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

Прото2 против Прото3

Версия формата буфера протокола задается в первой строке файла:

syntax="proto2";

Proto2 и proto3 — две часто используемые версии буферов протокола. Они оба используют один и тот же формат проводов, но файлы определений несовместимы. Ключевые различия между двумя версиями заключаются в следующем:

  • optional и required ключевые слова больше не разрешены в proto3.
  • В proto3 все фактически optional .
  • Расширения не поддерживаются в proto3.

Используйте proto3 в своих файлах прототипов, поскольку их можно скомпилировать в 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 зависела от нее, размер вашей игры увеличился бы на такую ​​же величину.

Полный против Lite против Nano

Помимо полной библиотеки protobuf, существует облегченная версия, которая уменьшает объем кода за счет удаления некоторых функций, таких как отражение, FileDescriptors и потоковая передача в текстовые форматы и из них. Эта версия по-прежнему требует нескольких МБ дополнительного кода, поэтому библиотека Tuning Fork внутренне использует библиотеку nanopb . Исходный код этой библиотеки включен в проект Android Open Source Project в external/nanopb-c и является частью ветки gamesdk . Используйте эту библиотеку в своей игре, если размер кода является проблемой.

В gamesdk/src/protobuf есть файлы CMake, которые помогут вам интегрировать все три версии protobuf. В образцах используется смесь как nanopb, так и полного protobuf.

Назад
Обновите настройки сборки
Далее
Добавить функции синхронизации кадров