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

ใช้ฟังก์ชันในหัวข้อนี้เพื่อผสานรวมไลบรารี 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);

คุณต้องเรียกใช้ฟังก์ชันนี้ 1 ครั้งเมื่อเริ่มต้น โดยปกติจะมาจากภายในโค้ดเนทีฟ ที่แอปเรียกใช้ด้วยเมธอด 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 จะบันทึกเวลาเฟรมโดยอัตโนมัติโดยที่คุณไม่ต้องเรียกฟังก์ชัน Tick ด้วยตนเอง ซึ่งทำได้ในแอปเดโมดังนี้

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();
   }
...
}

ทำลาย

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

เรียกใช้ฟังก์ชันนี้จากเมธอดวงจรที่เหมาะสมในActivity หลักของเกม โดยส่งผ่าน 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 เป็น null) ไฟล์ที่จัดเก็บไว้ในเครื่องซึ่งใช้เมื่อเซิร์ฟเวอร์เข้าถึงไม่ได้

คำขอเว็บ

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

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

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

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

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