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

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

注释和保真度参数

注释提供有关记录滴答时游戏正在做什么的上下文信息。保真度参数反映了游戏的性能和图形设置。您可以使用协议缓冲区定义这些参数，协议缓冲区是 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：method字段的 n。
  • max_instrumentation_keys：要使用的检测键数量。如果使用 Android 帧步进库，则设置为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 库依赖于它，会使游戏的大小增加类似的数量。

完整版与精简版与 Nano 版

除了完整的 protobuf 库，还有一个精简版，它通过移除一些功能（例如反射、FileDescriptors 以及文本格式的流式传输）来减小代码占用空间。这个版本仍然需要几 MB 的额外代码占用空间，因此，Tuning Fork 库在内部使用 nanopb 库。该库的源代码包含在 Android 开源项目 的 external/nanopb-c 中，它是 gamesdk 分支的一部分。如果代码大小是一个问题，请在您的游戏中使用此库。

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