Ek açıklamaları, doğruluk parametrelerini ve ayarları tanımlayın

Bu belgede, projenizde ek açıklamaları, doğruluk parametrelerini ve ayarları nasıl belirleyeceğiniz açıklanmaktadır.

Ek açıklamalar ve doğruluk parametreleri

Ek açıklamalar, bir onay işareti kaydedildiğinde oyununuzun ne yaptığına dair bağlamsal bilgiler verir. Doğruluk parametreleri, oyununuzun performansını ve grafik ayarlarını yansıtır. Bunları, Google'ın dilden bağımsız, yapılandırılmış, veri değişim biçimi olan protokol arabelleklerini kullanarak tanımlarsınız. Oyununuzda protokol arabelleklerini kullanma hakkında daha fazla bilgi için Protokol arabellekleri hakkında bölümüne bakın.

Oyununuz için olası ek açıklamalar ve doğruluk parametreleri, projenizin assets/tuningfork dizininde bulunan dev_tuningfork.proto adlı bir dosyada tanımlanır. Aşağıda, demo uygulamasından bir örnek verilmiştir:

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;
}

Aşağıdakileri göz önünde bulundurun:

• Paket, com.google.tuningfork olmalıdır.
• Mesaj adları tam olarak Annotation ve FidelityParams olmalıdır.
• Ek açıklamaların bir parçası olarak bu dosyada tanımlanan yalnızca enums öğesini kullanabilirsiniz.
• FidelityParams alanında yalnızca enums, int32s veya floats kullanabilirsiniz.
• Doğrulama aracı bu kuralları uygular.

Ayarlar

Settings mesajı tuningfork.proto tarafından tanımlanır. Tam örneği aşağıdaki dosyada bulabilirsiniz:

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

Oyununuzun ayarlarını, projenizin assets/tuningfork dizininde bulunan tuningfork_settings.txt adlı bir dosyada tanımlamanız gerekir. Yalnızca aşağıdaki alanları belirtmeniz gerekir:

• aggregation_strategy: Aşağıdakileri içeren bir ileti:

  • method: Her n milisaniyede bir yüklenecek TIME_BASED veya her n değerinde bir yükleme için TICK_BASED.
  • intervalms_or_count: method alanı için n.
  • max_instrumentation_keys: Kullanılacak araç anahtarı sayısı. Android Frame Pacing kitaplığını kullanıyorsanız 4 olarak ayarlayın.
  • annotation_enum_size: Boyut başlangıç sırasında açıklayıcıdan hesaplandığından isteğe bağlı bir alandır.

• api_key: Uygulamanızın uç noktaya gönderilen istekleri doğrulamak için kullanılan Cloud projesi API anahtarı. Bu anahtarı oluşturmak için API'yi etkinleştirme bölümüne bakın. logcat içinde bağlantı hataları görürseniz API anahtarının doğru olup olmadığını kontrol edin.

• default_fidelity_parameters_filename: İlk kullanıma hazırlama sırasında kullanılan doğruluk parametresi grubu (kodunuzda training_fidelity_params özelliğini ayarladıysanız isteğe bağlıdır).

• level_annotation_index: (İsteğe bağlı) Seviye numarasının ek açıklama alanlarınızdaki dizindir.

Aşağıda örnek bir metin temsili verilmiştir:

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

Ek açıklamalar ayarlama

Oyun sırasında ek açıklamaları manuel olarak ayarlamanız gerekir. Bunun bir örneğini, tüm oyun seviyelerinde otomatik olarak dolaşırken demo uygulamasında görebilirsiniz. Daha fazla bilgi için insightsdemo.cpp içindeki SetAnnotations() işlevine bakın.

Bu durumda, ek açıklama yalnızca seviye numarasını belirtir.

message Annotation {
  Level level = 1;
}

Kalite seviyelerini tanımlama

Cihazların çok yüksek (daha düşük performansa neden olur) veya çok düşük (gereksiz bir şekilde düşük kaliteye neden olur) kalite seviyesinde çalıştığını belirleyebilmek için kalite seviyelerini kullanarak oturumlara ek açıklama ekleyin.

Oyununuz için en az bir, tercihen birkaç kalite seviyesi tanımlamalısınız. Kalite seviyesi, FidelityParams mesajınızın bir örneğine karşılık gelir. Bu seviyeler, aşağıdaki dosya adı biçimiyle artan kalite sırasına göre verilmelidir:

dev_tuningfork_fidelityparams_i.txt

Burada i, 1 ile başlayan ve maksimum 15 olan bir dizindir. Bu dosyalar, projenizin assets/tuningfork dizininde bulunmalıdır. Örnek proje, gamesdk/samples/tuningfork/insightsdemo/app/src/main/assets/tuningfork/ dizininde bu yapının bir örneğini göstermektedir.

Protokol arabellekleri hakkında

Tuning Fork kitaplığı ayarlar, ek açıklamalar ve doğruluk parametreleri için Google'ın protokol arabelleği biçimini kullanır. Bu, genişletilebilir ve yapılandırılmış veriler için iyi tanımlanmış, çok dilli bir protokoldür. Daha fazla bilgi için Protokol Arabelleği belgelerine bakın.

Proto2 ve proto3 karşılaştırması

Protokol arabelleği biçiminin sürümü, dosyanın ilk satırında ayarlanır:

syntax="proto2";

Proto2 ve proto3, protokol arabelleklerinin yaygın olarak kullanılan iki sürümüdür. İkisi de aynı kablo biçimini kullanır ancak tanım dosyaları uyumlu değildir. İki sürüm arasındaki temel farklar şunlardır:

• proto3'te optional ve required anahtar kelimelerine artık izin verilmiyor.
• proto3'te her şey etkili bir şekilde optional.
• proto3'te uzantılar desteklenmez.

C# için derlenebileceğinden proto dosyalarınızda proto3 kullanın. Proto2, Tuning Fork kitaplığında kullanılan sınırlı özellik grubuyla da iyi çalışır.

Metin ve ikili gösterimler

İkili protobuf kablosu, farklı protokol arabelleği sürümlerinde iyi tanımlanmıştır ve sabittir (oluşturulan kod değildir). Ayrıca protobuf kitaplığının tam sürümünün oluşturup okuyabileceği bir metin biçimi de vardır. Bu biçim çok iyi tanımlanmış olmasa da Tuing Fork kitaplığındaki sınırlı özellik grubu için stabildir. protoc derleyicisini kullanarak ikili program ve metin biçimleri arasında dönüştürme yapabilirsiniz. Aşağıdaki komut, metin protobuf'unu ikili koda dönüştürür:

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

Tam protobuf kitaplığının boyutu birkaç MB olduğundan, APK'nıza metin dosyaları yerine ikili dosyalar eklemeniz gerekir. Tuning Fork kitaplığının buna bağımlı hale gelmesi, oyununuzun boyutunu benzer miktarda artırır.

Tam mı, Hafif mi, Nano mu?

Tam protobuf kitaplığının yanı sıra yansıma, FileDescriptors ve metin biçimleri arasında akış yapma gibi bazı özellikleri kaldırarak kod ayak izini azaltan hafif bir sürüm bulunur. Bu sürüm hâlâ birkaç MB'lık ek kod alanı gerektirdiğinden Tuning Fork kitaplığı dahili olarak nanopb kitaplığını kullanmaktadır. Bu kitaplığın kaynak kodu, external/nanopb-c bölgesinde bulunan Android Açık Kaynak Projesi'ne dahil edilmiştir ve gamesdk şubesinde yer alır. Kod boyutu sorun teşkil ediyorsa oyununuzda bu kitaplığı kullanın.

gamesdk/src/protobuf içinde protobuf'un üç sürümünü de entegre etmenize yardımcı olabilecek CMake dosyaları vardır. Örnekler hem nanopb hem de tam protobuf karışımı kullanır.