프레임 시간 함수 추가

이 주제의 함수를 사용하여 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 라이브러리에 필요한 데이터를 할당합니다.

히스토그램 및 주석 설정이 포함된 앱 내의 assets/tuningfork에 tuningfork_settings.bin 파일이 있어야 합니다. 텍스트 파일을 바이너리로 변환하려면 텍스트 표현과 바이너리 표현 비교를 참고하세요.

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

초기화 시 Frame Pacing API에서 Swappy_injectTracer() 함수(OpenGL, Vulkan)를 전달하면 틱 함수를 직접 명시적으로 호출하지 않고도 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();
   }
...
}

소멸

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

이 함수는 사용된 key 및 현재 주석과 연결된 히스토그램의 관련 TuningFork_startTrace() 호출 이후의 시간 간격을 기록합니다.

앱 수명 주기 함수

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

이 함수는 지정된 파일 이름이 있는 APK의 assets/tuningfork 디렉터리에서 fidelityParams를 로드합니다. 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는 디버그 서버에 설정, 기본 충실도 매개변수 및 dev_tuningfork.proto 구조를 알리는 debugInfo 요청을 보낼 수도 있습니다.

오프라인 플레이어

초기화 시 사용 가능한 연결이 없다면 백오프 시간이 증가하면서 요청이 여러 번 다시 시도됩니다.

업로드 시 연결이 없다면 업로드가 캐시됩니다. 초기화 시 TFCache 객체를 전달하여 자체 캐싱 메커니즘을 제공할 수 있습니다. 자체 캐시를 제공하지 않으면 업로드가 임시 저장소에 파일로 저장됩니다.