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

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

注解和保真度参数

注解提供关于游戏在记录计时时正在做什么的上下文信息。保真度参数反映游戏的性能和图形设置。您可以使用协议缓冲区（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 个计时点上传一次。
- 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。

定义注解、保真度参数和设置 使用收藏夹保持井井有条 根据您的偏好保存和分类内容。