Thêm hàm thời gian kết xuất khung hình

Sử dụng các hàm trong chủ đề này để tích hợp thư viện Tuning Fork vào mã trò chơi.

Tệp tiêu đề tại include/tuningfork/tuningfork.h chứa giao diện cốt lõi cho thư viện Tuning Fork. Tệp tại include/tuningfork/tuningfork_extra.h chứa các hàm hiệu dụng.

Một số hàm nhận chuỗi tuần tự của các vùng đệm giao thức. Để tìm hiểu thêm về cách sử dụng vùng đệm giao thức trong trò chơi, hãy xem nội dung Giới thiệu về vùng đệm giao thức.

Thông số hàm và giá trị trả về được giải thích trong tiêu đề và tài liệu về API tham chiếu.

Hàm trong vòng đời của Android Performance Tuner

Sử dụng các hàm sau để kiểm soát vòng đời của một phiên bản Tuning Fork.

Khởi chạy

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

Bạn phải gọi hàm này một lần khi khởi động, thường là trong mã gốc được thực thi bằng phương thức onCreate() của ứng dụng. Công cụ này phân bổ dữ liệu mà thư viện Forking Fork cần đến.

assets/tuningfork trong ứng dụng của bạn phải có tệp tuningfork_settings.bin chứa chế độ cài đặt biểu đồ và chú giải. Để chuyển đổi tệp văn bản thành tệp nhị phân, hãy xem nội dung Biểu diễn văn bản so với biểu diễn nhị phân.

Các trường mà bạn điền vào settings sẽ xác định cách thư viện tự khởi chạy.

/**
 * @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;
};

Nếu bạn truyền hàm Swappy_injectTracer() (OpenGL, Vulkan) từ API Frame Pacing khi khởi chạy, thư viện Tuning Fork sẽ tự động ghi lại thời gian kết xuất khung hình mà bạn không cần phải tự gọi các hàm đánh dấu nhịp độ khung hình. Thao tác này được thực hiện trong ứng dụng minh hoạ:

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

Lưu ý: điều quan trọng là bạn phải đặt phiên bản Swappy mà bạn đang sử dụng trong trường swappy_version của TFSettings. Điều này đảm bảo rằng TuningFork có thể diễn giải dữ liệu thu về từ các lệnh gọi lại Swappy.

Huỷ bỏ

TFErrorCode TuningFork_destroy();

Bạn có thể gọi hàm này khi tắt. Hàm này cố gắng gửi tất cả dữ liệu biểu đồ hiện đang được lưu trữ để tải lên sau này trước khi phân bổ mọi không gian bộ nhớ mà thư viện Tuning Fork sử dụng.

Xả

TFErrorCode TuningFork_flush();

Hàm này xả biểu đồ được ghi lại (ví dụ: khi trò chơi được chuyển xuống dưới nền hoặc chuyển lên nền trước). Hàm này sẽ không xả dữ liệu nếu chưa qua thời gian tải lên tối thiểu (mặc định là một phút) kể từ lần tải lên trước đó.

Đặt thông số về độ chân thực

TFErrorCode TuningFork_setFidelityParameters(const CProtobufSerialization* params);

Hàm này ghi đè các thông số về độ chân thực hiện tại bằng thông số liên kết với dữ liệu khung. Bạn nên gọi hàm này khi người chơi thay đổi chế độ cài đặt chất lượng của trò chơi theo cách thủ công.

Chú giải

TFErrorCode TuningFork_setCurrentAnnotation(const CProtobufSerialization* annotation);

Hàm này đặt chú giải liên kết với các kim đánh dấu nhịp độ khung hình tiếp theo. Hàm này trả về TFERROR_INVALID_ANNOTATION nếu đã xảy ra lỗi khi giải mã chú giải và TFERROR_OK nếu không có lỗi.

Hàm trên mỗi khung hình

TFErrorCode TuningFork_frameTick(TFInstrumentKey key);

Hàm này ghi lại thời gian kể từ kim đánh dấu nhịp độ khung hình trước đó có key đã cho đến thời gian hiện tại trong biểu đồ được liên kết với key và chú giải hiện tại.

TFErrorCode TuningFork_frameDeltaTimeNanos(TFInstrumentKey key, TFDuration dt);

Hàm này ghi lại thời lượng trong biểu đồ liên kết với key và chú giải hiện tại.

TFErrorCode TuningFork_startTrace(TFInstrumentKey key, TraceHandle* handle);

Hàm này đặt một handle thành một handle dấu vết liên kết với key đã cho.

TFErrorCode TuningFork_endTrace(TraceHandle handle);

Hàm này ghi lại khoảng thời gian kể từ lệnh gọi liên kết TuningFork_startTrace() trong biểu đồ được liên kết với key đã được sử dụng và chú giải hiện tại.

Hàm trong vòng đời ứng dụng

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

Hãy gọi hàm này từ các phương thức thích hợp của vòng đời trong Hoạt động chính của trò chơi, truyền enum phù hợp. Bằng cách ghi lại các sự kiện trong vòng đời của trò chơi, APT sẽ có thể hiểu dễ hơn khi nào trò chơi có thể gặp lỗi hoặc khi nào người dùng có thể thoát khỏi trò chơi (ví dụ: trong các sự kiện tải lâu).

Hàm nâng cao

Các hàm sau đây có trong tuningfork_extra.h.

Tìm và tải tệp trong APK

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

Hàm này tải fidelityParams từ thư mục assets/tuningfork trong APK với tên tệp đã cho. fidelityParams phải là một chuỗi tuần tự của thông báo FidelityParams. Để biết thêm thông tin, hãy xem nội dung Xác định mức chất lượng.

Quyền sở hữu chuỗi tuần sự được chuyển cho phương thức gọi và phương thức này phải gọi CProtobufSerialization_Free để phân bổ mọi không gian bộ nhớ đang giữ.

Tải thông số về độ chân thực xuống qua một luồng riêng

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

Kích hoạt luồng tải xuống để truy xuất thông số về độ chân thực. Luồng này sẽ thử lại yêu cầu cho đến khi thông số được tải xuống hoặc hết thời gian chờ. Thông số đã tải xuống được lưu trữ cục bộ. Khi khởi động lại, ứng dụng sẽ sử dụng các thông số đã tải xuống này thay vì các thông số mặc định.

Lưu và xoá các thông số về độ chân thực được lưu trữ trên thiết bị

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

Hàm này chỉ cần thiết ở chế độ chuyên gia, khi các thông số về độ chân thực được tải xuống từ máy chủ. Hàm này lưu đè hoặc xoá (nếu fidelity_params rỗng) các tệp lưu trữ cục bộ được dùng khi không truy cập được máy chủ.

Yêu cầu web

Thư viện đưa ra những loại yêu cầu sau đây đối với điểm cuối máy chủ:

• Yêu cầu generateTuningParameters được thực hiện khi khởi chạy.
• Trong quá trình chơi, yêu cầu uploadTelemetry được gửi định kỳ để gửi dữ liệu đến máy chủ.
• Các APK gỡ lỗi cũng có thể gửi yêu cầu debugInfo thông báo cho máy chủ gỡ lỗi về chế độ cài đặt, thông số về độ chân thực mặc định và cấu trúc dev_tuningfork.proto.

Người chơi ngoại tuyến

Nếu không có sẵn kết nối khi khởi động, yêu cầu sẽ được thử lại nhiều lần với thời gian đợi tăng lên.

Nếu không có kết nối khi tải lên, quá trình tải lên sẽ được lưu vào bộ nhớ đệm. Bạn có thể cung cấp cơ chế lưu vào bộ nhớ đệm của riêng mình bằng cách truyền một đối tượng TFCache khi khởi chạy. Nếu bạn không cung cấp bộ nhớ đệm riêng, nội dung tải lên sẽ được lưu trữ dưới dạng tệp trong bộ nhớ tạm thời.