กำหนดคำอธิบายประกอบ พารามิเตอร์ความแม่นยำ และการตั้งค่า

เอกสารนี้อธิบายวิธีตั้งค่าคำอธิบายประกอบ พารามิเตอร์ความแม่นยำ และการตั้งค่าในโปรเจ็กต์

คำอธิบายประกอบและพารามิเตอร์ความแม่นยำ

คำอธิบายประกอบจะให้ข้อมูลตามบริบทเกี่ยวกับสิ่งที่เกมกำลังทำเมื่อมีการบันทึกขีด พารามิเตอร์ความแม่นยำจะแสดงประสิทธิภาพและการตั้งค่ากราฟิกของเกม คุณกำหนดสิ่งเหล่านี้โดยใช้บัฟเฟอร์โปรโตคอล ซึ่งเป็นรูปแบบการแลกเปลี่ยนข้อมูลที่มีโครงสร้างและไม่ขึ้นอยู่กับภาษาของ 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 ที่กำหนดไว้ในไฟล์นี้เป็นส่วนหนึ่งของคำอธิบายประกอบ
  • คุณใช้ได้เฉพาะ 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: จำนวนคีย์ระบุตำแหน่งของ Tick ที่จะใช้ ตั้งค่าเป็น 4 หากใช้ไลบรารี Android Frame Pacing
    • annotation_enum_size: ฟิลด์ตัวเลือกเนื่องจากระบบจะคำนวณขนาดเมื่อเริ่มต้นจากข้อบ่งชี้
  • api_key: คีย์ 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

การตั้งค่าคำอธิบายประกอบ

คุณต้องตั้งค่าคำอธิบายประกอบด้วยตนเองระหว่างเล่นเกม คุณดูตัวอย่างได้ในแอปสาธิตขณะที่แอปหมุนเวียนผ่านระดับเกมทั้งหมดโดยอัตโนมัติ ดูข้อมูลเพิ่มเติมได้ที่ฟังก์ชัน SetAnnotations() ใน insightsdemo.cpp

ในกรณีนี้ คำอธิบายประกอบจะระบุเฉพาะหมายเลขระดับเท่านั้น

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 เวอร์ชันใช้รูปแบบ Wire เดียวกัน แต่ไฟล์คำจำกัดความเข้ากันไม่ได้ ความแตกต่างที่สำคัญระหว่างทั้ง 2 เวอร์ชันมีดังนี้

  • ไม่อนุญาตให้ใช้คีย์เวิร์ด optional และ required ใน proto3 อีกต่อไป
  • ทุกอย่างเป็น optional ใน proto3 อย่างมีประสิทธิภาพ
  • 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 แบบเต็มมีขนาดหลาย MB การทำให้ไลบรารี Tuning Fork ขึ้นอยู่กับไลบรารีดังกล่าวจะทำให้เกมมีขนาดเพิ่มขึ้นในปริมาณที่ใกล้เคียงกัน

Full เทียบกับ Lite เทียบกับ Nano

นอกจากไลบรารี protobuf แบบเต็มแล้ว ยังมีเวอร์ชัน Lite ที่ลดขนาดโค้ดด้วยการนำฟีเจอร์บางอย่างออก เช่น การสะท้อน, FileDescriptors และการสตรีมไปยังและจากรูปแบบข้อความ เวอร์ชันนี้ยังคงต้องใช้โค้ดเพิ่มเติมหลาย MB ดังนั้นไลบรารี Tuning Fork จึงใช้ไลบรารี nanopb เป็นการภายใน ซอร์สโค้ดสำหรับไลบรารีนี้รวมอยู่ในโครงการโอเพนซอร์ส Android ใน external/nanopb-c และเป็นส่วนหนึ่งของสาขา gamesdk ใช้ไลบรารีนี้ในเกมหากขนาดโค้ดเป็นปัญหา

มีไฟล์ CMake ใน gamesdk/src/protobuf ที่ช่วยให้คุณผสานรวม protobuf ทั้ง 3 เวอร์ชันได้ ตัวอย่างจะใช้ทั้ง nanopb และ protobuf แบบเต็ม