एनोटेशन, फ़िडेलिटी पैरामीटर, और सेटिंग तय करें

इस दस्तावेज़ में, अपने प्रोजेक्ट में एनोटेशन, फ़िडेलिटी के पैरामीटर, और सेटिंग सेट करने का तरीका बताया गया है.

एनोटेशन और फ़िडेलिटी के पैरामीटर

एनोटेशन से इस बारे में ज़रूरी जानकारी मिलती है कि टिक रिकॉर्ड होने पर, आपके गेम में क्या चल रहा है. फ़िडेलिटी के पैरामीटर से, आपके गेम की परफ़ॉर्मेंस और ग्राफ़िक सेटिंग के बारे में पता चलता है. इन्हें प्रोटोकॉल बफ़र का इस्तेमाल करके तय किया जाता है. ये 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

आपको अपने गेम की सेटिंग, tuningfork_settings.txt नाम की फ़ाइल में तय करनी होंगी. यह फ़ाइल आपके प्रोजेक्ट की assets/tuningfork डायरेक्ट्री में मौजूद होती है. आपको सिर्फ़ इन फ़ील्ड में जानकारी देनी होगी:

  • 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: आपके ऐप्लिकेशन के क्लाउड प्रोजेक्ट का एपीआई पासकोड. इसका इस्तेमाल, एंडपॉइंट को भेजे गए अनुरोधों की पुष्टि करने के लिए किया जाता है. इस पासकोड को जनरेट करने के लिए, एपीआई को चालू करें लेख पढ़ें. अगर आपको logcat में कनेक्शन से जुड़ी गड़बड़ियां दिखती हैं, तो जांच करें कि एपीआई पासकोड सही है या नहीं.

  • 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/ डायरेक्ट्री में मौजूद है.

प्रोटोकॉल बफ़र के बारे में जानकारी

ट्यूनिंग फ़ोर्क लाइब्रेरी, सेटिंग, एनोटेशन, और फ़िडेलिटी के पैरामीटर के लिए, Google के प्रोटोकॉल बफ़र फ़ॉर्मैट का इस्तेमाल करती है. यह एक्सटेंसिबल और स्ट्रक्चर्ड डेटा के लिए, अच्छी तरह से तय किया गया और कई भाषाओं में उपलब्ध प्रोटोकॉल है. ज़्यादा जानकारी के लिए, प्रोटोकॉल बफ़र का दस्तावेज़ देखें.

Proto2 बनाम proto3

प्रोटोकॉल बफ़र फ़ॉर्मैट का वर्शन, फ़ाइल की पहली लाइन में सेट किया जाता है:

syntax="proto2";

Proto2 और proto3, प्रोटोकॉल बफ़र के दो आम तौर पर इस्तेमाल होने वाले वर्शन हैं. दोनों एक ही वायर फ़ॉर्मैट का इस्तेमाल करते हैं, लेकिन डेफ़िनिशन फ़ाइलें साथ काम नहीं करतीं. दोनों वर्शन के बीच के मुख्य अंतर ये हैं:

  • optional और required कीवर्ड, अब proto3 में इस्तेमाल नहीं किए जा सकते.
  • proto3 में, हर फ़ील्ड को optional के तौर पर माना जाता है.
  • proto3 में एक्सटेंशन काम नहीं करते.

अपनी प्रोटो फ़ाइलों में proto3 का इस्तेमाल करें, क्योंकि इन्हें C# में कंपाइल किया जा सकता है. Proto2, ट्यूनिंग फ़ोर्क लाइब्रेरी में इस्तेमाल किए गए सीमित सुविधाओं के सेट के साथ भी काम करता है.

टेक्स्ट बनाम बाइनरी रिप्रज़ेंटेशन

बाइनरी प्रोटोबफ़ वायर-फ़ॉर्मैट को अच्छी तरह से तय किया गया है. साथ ही, यह प्रोटोबफ़ के अलग-अलग वर्शन में काम करता है. हालांकि, जनरेट किया गया कोड ऐसा नहीं होता. एक टेक्स्ट फ़ॉर्मैट भी होता है, जिसे protobuf लाइब्रेरी का पूरा वर्शन जनरेट और पढ़ सकता है. यह फ़ॉर्मैट अच्छी तरह से तय नहीं किया गया है. हालांकि, यह Tuning Fork लाइब्रेरी में मौजूद सुविधाओं के सीमित सेट के लिए स्टेबल है. protoc कंपाइलर का इस्तेमाल करके, बाइनरी और टेक्स्ट फ़ॉर्मैट के बीच कन्वर्ज़न किया जा सकता है. यह कमांड, टेक्स्ट protobuf को बाइनरी में बदलता है:

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

आपको अपने APK में टेक्स्ट फ़ाइलों के बजाय बाइनरी फ़ाइलें शामिल करनी होंगी, क्योंकि पूरी protobuf लाइब्रेरी का साइज़ कई एमबी होता है. Tuning Fork लाइब्रेरी को इस पर निर्भर बनाने से, आपके गेम का साइज़ भी उतना ही बढ़ जाएगा.

Full, Lite, और Nano वर्शन में अंतर

पूरी protobuf लाइब्रेरी के साथ-साथ, इसका एक लाइट वर्शन भी है. यह रिफ़्लेक्शन, FileDescriptors, और टेक्स्ट फ़ॉर्मैट में और उससे स्ट्रीमिंग जैसी कुछ सुविधाओं को हटाकर, कोड फ़ुटप्रिंट को कम करता है. इस वर्शन को अब भी कई एमबी के अतिरिक्त कोड फ़ुटप्रिंट की ज़रूरत होती है. इसलिए, ट्यूनिंग फ़ोर्क लाइब्रेरी, अंदरूनी तौर पर nanopb लाइब्रेरी का इस्तेमाल करती है. इस लाइब्रेरी का सोर्स कोड, external/nanopb-c में Android ओपन सोर्स प्रोजेक्ट में शामिल है. साथ ही, यह gamesdk ब्रांच का हिस्सा है. अगर कोड का साइज़ एक समस्या है, तो अपने गेम में इस लाइब्रेरी का इस्तेमाल करें.

gamesdk/src/protobuf में CMake फ़ाइलें मौजूद हैं. इनकी मदद से, protobuf के तीनों वर्शन को इंटिग्रेट किया जा सकता है. सैंपल में, nanopb और फ़ुल protobuf, दोनों का इस्तेमाल किया जाता है.