เพิ่มฟังก์ชันการจับเวลาเฟรม

ใช้ฟังก์ชันในหัวข้อนี้เพื่อผสานรวมไลบรารี Tuning Fork ลงในโค้ดเกมของคุณ

ไฟล์ส่วนหัวที่ include/tuningfork/tuningfork.h มีอินเทอร์เฟซหลัก สำหรับห้องสมุด Tuning Fork ไฟล์ที่ include/tuningfork/tuningfork_extra.h มีฟังก์ชันยูทิลิตี

ฟังก์ชันหลายอย่างใช้การแปลงบัฟเฟอร์โปรโตคอลเป็นอนุกรม สำหรับข้อมูลเพิ่มเติมเกี่ยวกับการใช้ บัฟเฟอร์โปรโตคอลภายในเกมของคุณ โปรดดู เกี่ยวกับบัฟเฟอร์โปรโตคอล

พารามิเตอร์ฟังก์ชันและค่าที่ส่งกลับจะอธิบายอยู่ในส่วนหัวและ เอกสารประกอบของ API อ้างอิง

ฟังก์ชันวงจรของ Android Performance Tuner

ใช้ฟังก์ชันต่อไปนี้เพื่อควบคุมวงจรของ Tuning Fork อินสแตนซ์

เริ่มต้น

TFErrorCode TuningFork_init(const TFSettings* settings, JNIEnv* env, jobject context);

คุณต้องเรียกใช้ฟังก์ชันนี้ครั้งเดียวเมื่อเริ่มต้นใช้งาน ซึ่งโดยปกติจะจากภายในโค้ดแบบเนทีฟ เรียกใช้โดยเมธอด onCreate() ของแอป จัดสรรข้อมูลที่จำเป็นโดย คลัง Tuning Fork

คุณต้องมีไฟล์ tuningfork_settings.bin ใน assets/tuningfork ภายในแอป ซึ่งมีการตั้งค่าฮิสโตแกรมและคำอธิบายประกอบ ถึง แปลงไฟล์ข้อความเป็นไบนารี โปรดดู การแทนแบบข้อความกับแบบไบนารี

ฟิลด์ที่คุณกรอก settings จะกำหนดวิธีเริ่มต้นไลบรารี

/**
 * @brief Initialization settings
 *   Zero any values that are not being used.
 */
struct TFSettings {
  /**
   * Cache object to be used for upload data persistence.
   * If unset, data is persisted to /data/local/tmp/tuningfork
   */
  const TFCache* persistent_cache;
  /**
   * The address of the Swappy_injectTracers function.
   * If this is unset, you need to call TuningFork_tick explicitly.
   * If it is set, telemetry for 4 instrument keys is automatically recorded.
   */
  SwappyTracerFn swappy_tracer_fn;
  /**
   * Callback
   * If set, this is called with the fidelity parameters that are downloaded.
   * If unset, you need to call TuningFork_getFidelityParameters explicitly.
   */
  ProtoCallback fidelity_params_callback;
  /**
   * A serialized protobuf containing the fidelity parameters to be uploaded
   *  for training.
   * Set this to nullptr if you are not using training mode. Note that these
   *  are used instead of the default parameters loaded from the APK, if they
   *  are present and there are neither a successful download nor saved parameters.
   */
  const CProtobufSerialization* training_fidelity_params;
  /**
   * A null-terminated UTF-8 string containing the endpoint that Tuning Fork
   * will connect to for parameter, upload, and debug requests. This overrides
   * the value in base_uri in the settings proto and is intended for debugging
   * purposes only.
   */
  const char* endpoint_uri_override;
  /**
   * The version of Swappy that swappy_tracer_fn comes from.
   */
  uint32_t swappy_version;
  /**
   * The number of each metric that is allowed to be allocated at any given
   * time. If any element is zero, the default for that metric type is used.
   * Memory for all metrics is allocated up-front at initialization. When all
   * metrics of a given type are allocated, further requested metrics are not
   * added and data is lost.
   */
  TuningFork_MetricLimits max_num_metrics;
};

หากคุณสอบผ่านในฟังก์ชัน Swappy_injectTracer() (OpenGL, Vulkan) จาก Frame Pacing API ในการเริ่มต้น ไลบรารี Tuning Fork บันทึกเวลาที่ใช้ในการแสดงผลเฟรมโดยอัตโนมัติโดยที่คุณไม่ต้องเรียกเครื่องหมายถูกอย่างชัดแจ้ง ด้วยตัวคุณเอง โดยทำได้ในแอปเดโม ดังนี้

void InitTf(JNIEnv* env, jobject activity) {
   SwappyGL_init(env, activity);
   swappy_enabled = SwappyGL_isEnabled();
   TFSettings settings {};
   if (swappy_enabled) {
       settings.swappy_tracer_fn = &SwappyGL_injectTracer;
       settings.swappy_version = Swappy_version();
   }
...
}

หมายเหตุ: คุณจำเป็นต้องตั้งค่าเวอร์ชันของ "การสลับ" ที่คุณใช้อยู่ ในช่อง swappy_version ของ TFSettings ซึ่งทำให้ TuningFork สามารถ ตีความข้อมูลที่กลับมาจาก Callback ที่เป็นการสลับ

ทำลาย

TFErrorCode TuningFork_destroy();

คุณสามารถเรียกใช้ฟังก์ชันนี้ได้เมื่อปิดเครื่อง ฟังก์ชันนี้จะพยายามส่ง ข้อมูลฮิสโตแกรมที่จัดเก็บไว้ในปัจจุบันเพื่อการอัปโหลดในภายหลังก่อนที่จะแจกจ่ายหน่วยความจำ ที่ใช้โดยไลบรารี Tuning Fork

แบบยึดเพดานด้วยฐาน

TFErrorCode TuningFork_flush();

ฟังก์ชันนี้จะล้างฮิสโตแกรมที่บันทึกไว้ (ตัวอย่างเช่น เมื่อเกม ไปยังพื้นหลังหรือเบื้องหน้า) แต่จะไม่ล้างข้อมูลหากมีจำนวนขั้นต่ำ ระยะเวลาการอัปโหลดซึ่งมีค่าเริ่มต้น 1 นาที ยังไม่ผ่านไปนับตั้งแต่ อัปโหลดก่อนหน้า

ตั้งค่าพารามิเตอร์ความแม่นยำ

TFErrorCode TuningFork_setFidelityParameters(const CProtobufSerialization* params);

ฟังก์ชันนี้จะลบล้างพารามิเตอร์ความแม่นยำปัจจุบันที่มีข้อมูลเฟรม ที่เกี่ยวข้อง คุณควรเรียกใช้ฟังก์ชันนี้เมื่อโปรแกรมเล่นเปลี่ยน การตั้งค่าคุณภาพของเกม

คำอธิบายประกอบ

TFErrorCode TuningFork_setCurrentAnnotation(const CProtobufSerialization* annotation);

ฟังก์ชันนี้ตั้งค่าคำอธิบายประกอบให้เชื่อมโยงกับขีดที่ตามมา ผลลัพธ์ TFERROR_INVALID_ANNOTATION ถ้าเกิดข้อผิดพลาดในการถอดรหัสคำอธิบายประกอบและ TFERROR_OKหากไม่มีข้อผิดพลาด

ฟังก์ชันต่อเฟรม

TFErrorCode TuningFork_frameTick(TFInstrumentKey key);

ฟังก์ชันนี้จะบันทึกเวลาระหว่างเครื่องหมายถูกก่อนด้วย key ที่ระบุ และเวลาปัจจุบันในฮิสโตแกรมที่เกี่ยวข้องกับ key และเวลาปัจจุบัน หมายเหตุ

TFErrorCode TuningFork_frameDeltaTimeNanos(TFInstrumentKey key, TFDuration dt);

ฟังก์ชันนี้จะบันทึกระยะเวลาในฮิสโตแกรมที่เกี่ยวข้องกับ key และ หมายเหตุปัจจุบัน

TFErrorCode TuningFork_startTrace(TFInstrumentKey key, TraceHandle* handle);

ฟังก์ชันนี้จะกำหนดแฮนเดิลเป็นแฮนเดิลการติดตามที่เชื่อมโยงกับ key ที่ระบุ

TFErrorCode TuningFork_endTrace(TraceHandle handle);

ฟังก์ชันนี้จะบันทึกช่วงเวลาตั้งแต่ TuningFork_startTrace() ในฮิสโตแกรมที่เกี่ยวข้องกับ key ที่ใช้และ หมายเหตุ

ฟังก์ชันวงจรของแอป

typedef enum TuningFork_LifecycleState {
    TUNINGFORK_STATE_UNINITIALIZED = 0,
    TUNINGFORK_STATE_ONCREATE = 1,
    TUNINGFORK_STATE_ONSTART = 2,
    TUNINGFORK_STATE_ONSTOP = 3,
    TUNINGFORK_STATE_ONDESTROY = 4,
} TuningFork_LifecycleState;

TFErrorCode TuningFork_reportLifecycleEvent(TuningForkLifecycleState state);

เรียกใช้ฟังก์ชันนี้จากเมธอดวงจรที่เหมาะสมใน กิจกรรมหลักของเกม, การส่งผ่าน Enum ที่เหมาะสม การบันทึกเหตุการณ์ในวงจรของเกมทำให้ APT มีประสิทธิภาพดีขึ้น เข้าใจได้ว่าเกมของคุณอาจขัดข้องเมื่อใดหรือผู้ใช้จะออกจากเกมเมื่อใด (เช่น ระหว่างการโหลดที่ใช้เวลานาน)

ฟังก์ชันขั้นสูง

ฟังก์ชันต่อไปนี้พร้อมใช้งานใน tuningfork_extra.h

ค้นหาและโหลดไฟล์ใน APK

TFErrorCode TuningFork_findFidelityParamsInApk(JNIEnv* env, jobject context, const char* filename, CProtobufSerialization* fidelityParams);

ฟังก์ชันนี้จะโหลด fidelityParams จากไดเรกทอรี assets/tuningfork ใน APK ที่มีชื่อไฟล์ที่ระบุ fidelityParams ต้องเป็นการทำให้เป็นอนุกรมของ FidelityParams ข้อความ สำหรับข้อมูลเพิ่มเติม โปรดดู กำหนดระดับคุณภาพ

ระบบจะส่งการเป็นเจ้าของการเรียงลำดับให้กับผู้เรียกใช้ ซึ่งต้องเรียกใช้ CProtobufSerialization_Free เพื่อจัดการหน่วยความจำที่คงไว้อยู่

ดาวน์โหลดพารามิเตอร์ความแม่นยำในชุดข้อความแยกต่างหาก

void TuningFork_startFidelityParamDownloadThread(const CProtobufSerialization* defaultParams, ProtoCallback fidelity_params_callback);

เปิดใช้งานชุดข้อความดาวน์โหลดเพื่อเรียกข้อมูลพารามิเตอร์ความแม่นยำ ชุดข้อความจะพยายาม จนกว่าจะมีการดาวน์โหลดพารามิเตอร์หรือหมดเวลา พารามิเตอร์ที่ดาวน์โหลดคือ ที่จัดเก็บไว้ในเครื่อง เมื่อรีสตาร์ทแอป จะใช้พารามิเตอร์ที่ดาวน์โหลดมาเหล่านี้ แทนที่จะเป็นพารามิเตอร์เริ่มต้น

บันทึกและลบพารามิเตอร์ความแม่นยำที่จัดเก็บไว้ในอุปกรณ์

TFErrorCode TuningFork_saveOrDeleteFidelityParamsFile(JNIEnv* env, jobject context, const CProtobufSerialization* fidelity_params);

ฟังก์ชันนี้จำเป็นเฉพาะในโหมดผู้เชี่ยวชาญที่มีพารามิเตอร์ความแม่นยำ ดาวน์โหลดจากเซิร์ฟเวอร์ ระบบจะบันทึกเป็นการบันทึกหรือลบ (หากเป็น fidelity_params เป็นค่าว่าง) ไฟล์ที่จัดเก็บในเครื่องซึ่งใช้เมื่อเข้าถึงเซิร์ฟเวอร์ไม่ได้

คำขอเว็บ

ไลบรารีจะส่งคำขอประเภทต่อไปนี้ไปยังปลายทางเซิร์ฟเวอร์

• ระบบจะสร้างคําขอ generateTuningParameters ตั้งแต่เริ่มต้น
• ระหว่างการเล่นเกม ระบบจะส่งคำขอ uploadTelemetry เป็นระยะๆ เพื่อส่ง ไปยังเซิร์ฟเวอร์
• APK การแก้ไขข้อบกพร่องยังส่งคำขอ debugInfo ได้ด้วย ซึ่งจะแจ้งให้เซิร์ฟเวอร์แก้ไขข้อบกพร่องทราบ การตั้งค่า พารามิเตอร์ความแม่นยำเริ่มต้น และdev_tuningfork.proto ใหม่

ผู้เล่นออฟไลน์

หากไม่มีการเชื่อมต่อที่พร้อมใช้งานในช่วงเริ่มต้น ระบบจะลองส่งคำขออีกครั้ง หลายครั้งโดยมีเวลาหยุดชั่วคราวที่นานขึ้น

หากไม่มีการเชื่อมต่อในขณะอัปโหลด ระบบจะแคชการอัปโหลดนั้นไว้ คุณสามารถระบุ ของตัวเองด้วยการส่ง TFCache ตั้งแต่เริ่มต้น หากคุณไม่ระบุแคชของคุณเอง การอัปโหลดจะ จัดเก็บเป็นไฟล์ในพื้นที่เก็บข้อมูลชั่วคราว