Definiowanie adnotacji, parametrów wierności i ustawień

Z tego dokumentu dowiesz się, jak ustawić adnotacje, parametry wierności i ustawienia w projekcie.

Adnotacje i parametry wierności

Adnotacje zawierają informacje kontekstowe o tym, co robi gra, gdy rejestrowany jest tick. Parametry wierności odzwierciedlają wydajność i ustawienia graficzne gry. Definiujesz je za pomocą buforów protokołu, które są niezależnym od języka, uporządkowanym formatem wymiany danych Google. Więcej informacji o używaniu buforów protokołów w grze znajdziesz w artykule Informacje o buforach protokołów.

Możliwe adnotacje i parametry wierności gry są zdefiniowane w pliku o nazwie dev_tuningfork.proto, który znajduje się w katalogu assets/tuningfork projektu. Oto przykład z aplikacji demonstracyjnej:

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

Uwaga:

  • Pakiet musi być com.google.tuningfork.
  • Nazwy wiadomości muszą być dokładnie takie: Annotation i FidelityParams.
  • W adnotacjach możesz używać tylko enums zdefiniowanych w tym pliku.
  • W polach FidelityParams możesz używać tylko wartości enums, int32s lub floats.
  • Narzędzie do walidacji wymusza te konwencje.

Ustawienia

Komunikat Settings jest zdefiniowany przez tuningfork.proto. Pełny przykład znajdziesz w tym pliku:

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

Ustawienia gry musisz zdefiniować w pliku o nazwie tuningfork_settings.txt znajdującym się w katalogu assets/tuningfork projektu. Musisz podać tylko te pola:

  • aggregation_strategy: wiadomość zawierająca te informacje:

    • method: TIME_BASED, aby przesyłać co n milisekund, lub TICK_BASED, aby przesyłać co n cykli.
    • intervalms_or_count: n w polu method.
    • max_instrumentation_keys: liczba kluczy instrumentacji do użycia. Jeśli używasz biblioteki Android Frame Pacing, ustaw wartość 4.
    • annotation_enum_size: pole opcjonalne, ponieważ rozmiar jest obliczany przy uruchamianiu na podstawie deskryptora.
  • api_key: klucz interfejsu API projektu w chmurze Twojej aplikacji, używany do sprawdzania poprawności żądań wysyłanych do punktu końcowego. Aby wygenerować ten klucz, zapoznaj się z sekcją Włączanie interfejsu API. Jeśli w logcat pojawią się błędy połączenia, sprawdź, czy klucz interfejsu API jest prawidłowy.

  • default_fidelity_parameters_filename: zestaw parametrów wierności używany podczas inicjowania (opcjonalny, jeśli w kodzie ustawisz training_fidelity_params).

  • level_annotation_index: (opcjonalnie) indeks numeru poziomu w polach adnotacji.

Oto przykładowa reprezentacja tekstowa:

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

Ustawianie adnotacji

Podczas gry musisz ręcznie ustawić adnotacje. Możesz zobaczyć przykład tego w aplikacji demonstracyjnej, która automatycznie przechodzi przez wszystkie poziomy gry. Więcej informacji znajdziesz w opisie funkcji SetAnnotations() w insightsdemo.cpp.

W takim przypadku adnotacja określa tylko numer poziomu.

message Annotation {
  Level level = 1;
}

Definiowanie poziomów jakości

Używaj poziomów jakości do dodawania adnotacji do sesji, aby określić, czy urządzenia działają na zbyt wysokim poziomie jakości (co powoduje obniżenie wydajności) czy na zbyt niskim (co powoduje niepotrzebne obniżenie wierności).

Musisz zdefiniować co najmniej 1, a najlepiej kilka poziomów jakości gry. Poziom jakości odpowiada instancji wiadomości FidelityParams. Poziomy te muszą być podane w kolejności rosnącej według wierności, a nazwy plików muszą mieć ten format:

dev_tuningfork_fidelityparams_i.txt

gdzie i to indeks zaczynający się od 1 i mający maksymalną wartość 15. Te pliki muszą znajdować się w katalogu assets/tuningfork projektu. Przykładowy projekt pokazuje przykład tej struktury w katalogu gamesdk/samples/tuningfork/insightsdemo/app/src/main/assets/tuningfork/.

Informacje o buforach protokołu

Biblioteka Tuning Fork używa formatu bufora protokołu Google do ustawień, adnotacji i parametrów wierności. Jest to dobrze zdefiniowany, wielojęzyczny protokół dla rozszerzalnych, ustrukturyzowanych danych. Więcej informacji znajdziesz w dokumentacji buforów protokołu.

Proto2 a proto3

Wersja formatu bufora protokołu jest ustawiona w pierwszym wierszu pliku:

syntax="proto2";

Proto2 i proto3 to 2 najczęściej używane wersje buforów protokołu. Oba używają tego samego formatu przesyłania, ale pliki definicji nie są zgodne. Najważniejsze różnice między tymi 2 wersjami:

  • Słowa kluczowe optional i required nie są już dozwolone w proto3.
  • W proto3 wszystko jest efektywnie optional.
  • Rozszerzenia nie są obsługiwane w proto3.

W plikach proto używaj proto3, ponieważ można je skompilować do C#. Proto2 działa równie dobrze z ograniczonym zestawem funkcji używanym w bibliotece Tuning Fork.

Reprezentacje tekstowe a binarne

Binarny format przesyłania protobuf jest dobrze zdefiniowany i stabilny w różnych wersjach protobuf (wygenerowany kod nie jest). Istnieje też format tekstowy, który może generować i odczytywać pełna wersja biblioteki protobuf. Ten format nie jest tak dobrze zdefiniowany, ale jest stabilny w przypadku ograniczonego zestawu funkcji w bibliotece Tuning Fork. Możesz konwertować formaty binarne i tekstowe za pomocą kompilatora protoc. To polecenie konwertuje tekstowy plik protobuf na binarny:

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

W pakiecie APK musisz uwzględnić pliki binarne, a nie tekstowe, ponieważ pełna biblioteka protobuf ma rozmiar kilku megabajtów. Gdyby biblioteka Tuning Fork była od niej zależna, rozmiar gry zwiększyłby się o podobną wartość.

Full, Lite i Nano

Oprócz pełnej biblioteki buforów protokołu dostępna jest też wersja uproszczona, która zmniejsza rozmiar kodu przez usunięcie niektórych funkcji, takich jak odbicie, FileDescriptors oraz strumieniowanie do i z formatów tekstowych. Ta wersja nadal wymaga kilku megabajtów dodatkowego kodu, dlatego biblioteka Tuning Fork wewnętrznie korzysta z biblioteki nanopb. Kod źródłowy tej biblioteki jest zawarty w projekcie Android Open Source Project w external/nanopb-c i jest częścią gałęzi gamesdk. Użyj tej biblioteki w grze, jeśli rozmiar kodu jest problemem.

W folderze gamesdk/src/protobuf znajdują się pliki CMake, które mogą pomóc w integracji wszystkich 3 wersji protobuf. Przykłady wykorzystują zarówno nanopb, jak i pełny protobuf.