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

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

注释和保真度参数

注释提供有关记录刻度时游戏正在执行的操作的上下文信息。保真度参数反映了游戏的性能和图形设置。您可以使用协议缓冲区定义这些参数，协议缓冲区是 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 的混合。