定义注解、保真度参数和设置

本文档介绍如何在项目中设置注释、保真度参数和设置。

注释和保真度参数

注释用于提供有关记录到 tick 时游戏在进行何种操作的背景信息。保真度参数反映了游戏的性能和图形设置。您可以使用协议缓冲区定义它们，协议缓冲区是 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

您必须在项目的 assets/tuningfork 目录下名为 tuningfork_settings.txt 的文件中定义游戏的设置。您只需指定以下字段：

• aggregation_strategy：包含以下内容的消息：

  • method：TIME_BASED（每 n 毫秒上传一次）或 TICK_BASED（每 n 个 tick 上传一次）。
  • intervalms_or_count：method 字段的 n。
  • max_instrumentation_keys：需使用的插桩键的数量。如果使用 Android Frame Pacing 库，则设置为 4。
  • annotation_enum_size：选填字段，因为大小是在启动时根据描述符计算得出的。

• api_key：应用的 Cloud 项目 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

设置注释

您需要在游戏过程中手动设置注释。您可以在演示版应用中看到此操作的示例，它会自动遍历所有游戏关卡。如需了解详情，请参阅 insightsdemo.cpp 中的 SetAnnotations() 函数。

在此示例中，注释仅指定关卡序号。

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 是两个常用的协议缓冲区版本。这两个版本使用同一传输格式，但定义文件不兼容。两个版本的主要区别包含以下方面：

• proto3 中不再允许使用 optional 和 required 关键字。
• 在 proto3 中，所有内容都是 optional，以提高效率。
• proto3 不支持扩展。

在 proto 文件中使用 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 库大小为数 MB；让 Tuning Fork 库依赖于它会增加游戏的大小，增加的大小与 protobuf 库大小类似。

完整版、精简版与 Nano 版

除了完整的 protobuf 库之外，还有一个精简版。精简版中移除了一些特征（例如反射、FileDescriptors 以及流式传入和流式传出文字的格式），从而减少了代码占用的空间。此版本仍然需要数 MB 的额外代码占用空间，因此，Tuning Fork 库在内部使用 nanopb 库。此库的源代码包含在 external/nanopb-c 中的 Android 开源项目中，并且是 gamesdk 分支的一部分。如果代码大小出现问题，请在游戏中使用此库。

gamesdk/src/protobuf 中有 CMake 文件，可帮助您集成所有三个版本的 protobuf。这些示例使用 nanopb 和完整版 protobuf 的组合。