このページは Cloud Translation API によって翻訳されました。

アノテーション、忠実度パラメータ、設定の定義

このドキュメントでは、プロジェクトにアノテーション、忠実度パラメータ、設定を定義する方法について説明します。

アノテーションと忠実度パラメータ

アノテーションは、記録されたティックでのゲームの動作に関するコンテキスト情報を提供するものです。忠実度パラメータは、ゲームのパフォーマンスとグラフィックの設定を反映します。これらは、プロトコルバッファという、Google が開発した言語に依存しない構造化されたデータ交換形式を使用して定義します。ゲーム内でのプロトコルバッファの使用について詳しくは、プロトコルバッファについてをご覧ください。

ゲームで使用できるアノテーションと忠実度パラメータは、プロジェクトの assets/tuningfork ディレクトリにある dev_tuningfork.proto というファイルで定義されます。次のデモアプリの例をご覧ください。

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: n ミリ秒ごとにアップロードする場合は TIME_BASED、n ティックごとにアップロードする場合は TICK_BASED。
- intervalms_or_count: method フィールドの 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;
}

品質レベルを定義する

品質レベルを使用してセッションにアノテーションを付けると、デバイスが高すぎる品質レベルで動作しているか（その結果パフォーマンスが低下する）、または低すぎる品質レベルで動作しているか（その結果不必要に忠実度が低下する）を判断できます。

ゲームの品質レベルは、少なくとも 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 の 2 つのバージョンが一般的に使用されています。どちらも同じワイヤ形式を使用しますが、定義ファイルには互換性がありません。2 つのバージョンの主な違いは次のとおりです。

proto3 では、optional キーワードと required キーワードが使用できなくなりました。
proto3 では、実質的にすべてが optional です。
proto3 では、拡張機能がサポートされません。

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 ライブラリに加えて、リフレクション、FileDescriptors、テキスト形式との間のストリーミングなどの機能を削除してコード量を減らした軽量版も用意されています。このバージョンでも数 MB のコード量が追加となるため、Tuning Fork ライブラリは内部で nanopb ライブラリを使用しています。このライブラリのソースコードは、external/nanopb-c の Android オープンソースプロジェクトに含まれており、gamesdk ブランチの一部となっています。コードサイズが問題になる場合は、このライブラリをゲームで使用してください。

gamesdk/src/protobuf には、3 つのバージョンの protobuf の組み込みに使用できる CMake ファイルがあります。このサンプルでは、nanopb と完全版の protobuf の両方を組み合わせて使用しています。

ビルド設定の更新

フレーム時間関数の追加