這份文件說明如何在專案中設定註解、擬真度參數和設定。
註解和擬真度參數
註解可提供遊戲記錄到滴答時的情境資訊。擬真度參數會反映遊戲的效能和圖像設定。您可以使用通訊協定緩衝區，也就是 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 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 中不再允許使用
optional和required關鍵字。 - 在 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-c 的 Android 開放原始碼計畫中，且屬於 gamesdk 分支的一部分。如果程式碼大小出現問題，請在遊戲中使用這個程式庫。
gamesdk/src/protobuf 中的 CMake 檔案可協助您整合所有三個版本的 protobuf。這些範例混合使用 nanopb 和完整版 protobuf。