Google 致力于为黑人社区推动种族平等。查看具体举措

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

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

注释和保真度参数

注释可以提供有关记录到 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 LoadingState {
  LOADING_INVALID = 0;
  NOT_LOADING = 1;
  LOADING = 2;
}

enum Level {
  // 0 is not a valid value
  LEVEL_INVALID = 0;
  LEVEL_1 = 1;
  LEVEL_2 = 2;
  LEVEL_3 = 3;
};

message Annotation {
  LoadingState loading = 1;
  Level level = 2;
}

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,则为可选)。

  • loading_annotation_index:(可选)LoadingState 标记注释字段中的索引。

  • 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"
loading_annotation_index: 1
level_annotation_index: 2

加载注释

加载注释标记了作为关卡加载进程一部分的帧。您应使用加载注释,以免游戏加载时出现较慢的帧影响您的总体指标。

在设置中设置 loading_annotation_index 字段时,系统会为使用该索引的注释指定一个特殊含义。例如,在演示版应用中,会使用以下注释:

message Annotation {
  LoadingState loading = 1;
  Level level = 2;
}

当加载注释设置为 LOADING 时,系统会忽略帧 tick。当加载注释重置为 NOT_LOADING 时,在 LOADING 状态下花费的时间会记录在该注释的直方图中。使用此注释可跟踪加载游戏关卡所需的时间。您可以将关卡序号指定为来自 Level 枚举的值。

在上述设置中,由于 loading_annotation_index 为 1,因此第一个注释用于指定游戏是否在加载下一个场景。由于 level_annotation_index 是 2,因此第二个注释指定关卡数字。

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

定义质量级别

使用质量级别为会话添加注释,以便您可以确定设备运行的质量级别是否过高(会导致性能降低)或过低(导致不必要的保真度下降)。

您必须为游戏至少指定一个质量级别,最好指定多个质量级别。质量级别对应于 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 的组合。