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

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

注释和保真度参数

注释用于提供有关记录到 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
  • 消息名称必须是 AnnotationFidelityParams,且不能有任何不同。
  • 您只能将此文件中定义的 enums 用作注释的一部分。
  • 您在 FidelityParams 字段中只能使用 enumsint32sfloats
  • 验证工具会强制执行这些惯例。

设置

Settings 消息由 tuningfork.proto 定义。在以下文件中查看完整示例:

gamesdk/samples/tuningfork/insightsdemo/app/src/main/assets/tuningfork/tuningfork_settings.txt

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

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

    • methodTIME_BASED(每 n 毫秒上传一次)或 TICK_BASED(每 n 个 tick 上传一次)。
    • intervalms_or_countmethod 字段的 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 中不再允许使用 optionalrequired 关键字。
  • 在 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 的组合。