定義註解、擬真度參數和設定

這份文件說明如何在專案中設定註解、擬真度參數和設定。

註解和擬真度參數

註解可提供背景資訊,說明系統記錄滴答當下的遊戲情境。擬真度參數會反映遊戲的效能和圖像設定。您可以使用通訊協定緩衝區,也就是 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」個滴答上傳一次)。
    • intervalms_or_countmethod 欄位的「n」
    • max_instrumentation_keys:要使用的檢測金鑰數量。如果使用 Android Frame Pacing 資料庫,請設為 4
    • annotation_enum_size:選用欄位,因為大小是在啟動時根據描述元計算得出的。
  • api_key:應用程式的 Google 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 不支援擴充功能。

因為這些檔案可以編譯為 C#,請在 proto 檔案中使用 proto3。Proto2 可與 Tuning Fork 程式庫中的有限特徵集搭配使用。

文字和二進位表示法的比較

二進位 protobuf 傳輸格式可在不同的 protobuf 版本中明確定義且保持穩定 (產生的程式碼則不是如此)。完整的 protobuf 程式庫還可以產生和讀取一種文字格式。這個格式並未明確定義,但對於 Tuning Fork 程式庫中的有限功能組合可穩定運行。您可以使用 protoc 編譯器在二進位和文字格式之間轉換。下列指令會將文字 protobuf 轉換為二進位格式:

protoc --encode com.google.tuningfork.Settings tuningfork.proto < tuningfork_settings.txt > tuningfork_settings.bin

完整的 protobuf 程式庫大小為數 MB,因此您必須在 APK 中加入二進位檔案,而非文字檔案。讓 Tuning Fork 程式庫依賴於這類檔案會增加遊戲大小,增加的大小與 protobuf 類似。

完整版、精簡版和 Nano 版

除了完整的 protobuf 程式庫,還有一個精簡版,其中移除了部分功能 (例如反射、FileDescriptors,以及串流傳出和傳入文字的格式),可減少程式碼量。這個版本需要數個 MB 的額外程式碼量,因此 Tuning Fork 程式庫內部使用的是 nanopb 程式庫。這個程式庫的原始碼包含在 external/nanopb-cAndroid 開放原始碼計畫中,且屬於 gamesdk 分支的一部分。如果程式碼大小出現問題,請在遊戲中使用這個程式庫。

gamesdk/src/protobuf 中的 CMake 檔案可協助您整合所有三個版本的 protobuf。這些範例混合使用 nanopb 和完整版 protobuf。