הגדרת הערות, פרמטרים של איכות והגדרות

במאמר הזה מוסבר איך להגדיר הערות, פרמטרים של דיוק והגדרות בפרויקט.

הערות ופרמטרים של אמינות

ההערות מספקות מידע הקשרי על הפעולות שהמשחק מבצע כשמתועד טיק. פרמטרים של איכות משקפים את הביצועים וההגדרות הגרפיות של המשחק. אתם מגדירים את הנתונים האלה באמצעות מאגרי פרוטוקולים, שהם פורמט חילופי נתונים מובְנה של Google, שאינו תלוי בשפה. למידע נוסף על השימוש ב-protocol buffers במשחק, אפשר לעיין במאמר מידע על protocol buffers.

ההערות האפשריות והפרמטרים של רמת הדיוק של המשחק מוגדרים בקובץ בשם 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 שמוגדרים בקובץ הזה כחלק מההערות.
• אפשר להשתמש רק בערכים enums, int32s או floats בשדות FidelityParams.
• כלי האימות אוכף את המוסכמות האלה.

הגדרות

ההודעה Settings מוגדרת על ידי tuningfork.proto. דוגמה מלאה מופיעה בקובץ הבא:

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

צריך להגדיר את ההגדרות של המשחק בקובץ בשם tuningfork_settings.txt שנמצא בספרייה assets/tuningfork של הפרויקט. צריך לציין רק את השדות הבאים:

• ‫aggregation_strategy: הודעה שמכילה את הפרטים הבאים:

  • ‫method: TIME_BASED להעלאה כל n אלפיות שנייה או TICK_BASED להעלאה כל n טיקים.
  • ‫intervalms_or_count: n בשדה method.
  • ‫max_instrumentation_keys: מספר מפתחות המדידה לשימוש. מגדירים את הערך ל-4 אם משתמשים בספרייה Android Frame Pacing.
  • ‫annotation_enum_size: שדה אופציונלי, כי הגודל מחושב בהפעלה מתוך המתאר.

• ‫api_key: מפתח ה-API של פרויקט Cloud של האפליקציה, שמשמש לאימות בקשות לנקודת הקצה. במאמר הפעלת ה-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

הגדרת הערות

צריך להגדיר את ההערות באופן ידני במהלך המשחק. אפשר לראות דוגמה לכך באפליקציית ההדגמה, שבה כל השלבים במשחק מוצגים ברצף באופן אוטומטי. מידע נוסף זמין על הפונקציה SetAnnotations() בinsightsdemo.cpp.

במקרה הזה, ההערה מציינת רק את מספר הרמה.

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 להגדרות, להערות ולפרמטרים של איכות. זהו פרוטוקול מוגדר היטב, רב-לשוני, לנתונים מובְנים שניתנים להרחבה. מידע נוסף זמין במסמכי התיעוד בנושא Protocol Buffers.

‫Proto2 לעומת proto3

הגרסה של פורמט מאגר הפרוטוקולים מוגדרת בשורה הראשונה של הקובץ:

syntax="proto2";

‫Proto2 ו-proto3 הן שתי גרסאות נפוצות של פרוטוקול באפרס. שניהם משתמשים באותו פורמט קווי, אבל קובצי ההגדרה לא תואמים. ההבדלים העיקריים בין שתי הגרסאות כוללים:

• מילות המפתח optional ו-required כבר לא מותרות ב-proto3.
• הכל נמצא למעשה ב-proto3.optional
• אין תמיכה בתוספים ב-proto3.

משתמשים ב-proto3 בקובצי ה-proto כי אפשר לקמפל אותם ל-C#. ‫Proto2 פועל גם עם קבוצת התכונות המוגבלת שמשמשת בספריית Tuning Fork.

טקסט לעומת ייצוגים בינאריים

פורמט ה-protobuf הבינארי מוגדר היטב ויציב בגרסאות שונות של protobuf (הקוד שנוצר לא יציב). יש גם פורמט טקסט שניתן ליצור ולקרוא באמצעות הגרסה המלאה של ספריית ה-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 וסטרימינג אל פורמטים של טקסט ומפורמטים של טקסט. הגרסה הזו עדיין דורשת כמה מגה-בייט של קוד נוסף, ולכן ספריית Tuning Fork משתמשת באופן פנימי בספריית nanopb. קוד המקור של הספרייה הזו נכלל בפרויקט הקוד הפתוח של Android ב-external/nanopb-c והוא חלק מהענף gamesdk. כדאי להשתמש בספרייה הזו במשחק אם גודל הקוד הוא בעיה.

יש קובצי CMake ב-gamesdk/src/protobuf שיכולים לעזור לכם לשלב את כל שלוש הגרסאות של protobuf. בדוגמאות נעשה שימוש גם ב-nanopb וגם ב-protobuf מלא.