Tuning Fork 기본 인터페이스

Tuning Fork를 사용하기 위한 기본 인터페이스입니다.

요약

열거

InstrumentKeys{
  TFTICK_RAW_FRAME_TIME = 64000,
  TFTICK_PACED_FRAME_TIME = 64001,
  TFTICK_CPU_TIME = 64002,
  TFTICK_GPU_TIME = 64003
}
enum
프레임 내의 기간을 나타내는 계측 키입니다.
TFErrorCode{
  TFERROR_OK = 0,
  TFERROR_NO_SETTINGS = 1,
  TFERROR_NO_SWAPPY = 2,
  TFERROR_INVALID_DEFAULT_FIDELITY_PARAMS = 3,
  TFERROR_NO_FIDELITY_PARAMS = 4,
  TFERROR_TUNINGFORK_NOT_INITIALIZED = 5,
  TFERROR_INVALID_ANNOTATION = 6,
  TFERROR_INVALID_INSTRUMENT_KEY = 7,
  TFERROR_INVALID_TRACE_HANDLE = 8,
  TFERROR_TIMEOUT = 9,
  TFERROR_BAD_PARAMETER = 10,
  TFERROR_B64_ENCODE_FAILED = 11,
  TFERROR_JNI_BAD_VERSION = 12,
  TFERROR_JNI_BAD_THREAD = 13,
  TFERROR_JNI_BAD_ENV = 14,
  TFERROR_JNI_EXCEPTION = 15,
  TFERROR_JNI_BAD_JVM = 16,
  TFERROR_NO_CLEARCUT = 17,
  TFERROR_NO_FIDELITY_PARAMS_IN_APK = 18,
  TFERROR_COULDNT_SAVE_OR_DELETE_FPS = 19,
  TFERROR_PREVIOUS_UPLOAD_PENDING = 20,
  TFERROR_UPLOAD_TOO_FREQUENT = 21,
  TFERROR_NO_SUCH_KEY = 22,
  TFERROR_BAD_FILE_OPERATION = 23,
  TFERROR_BAD_SETTINGS = 24,
  TFERROR_ALREADY_INITIALIZED = 25,
  TFERROR_NO_SETTINGS_ANNOTATION_ENUM_SIZES = 26,
  TFERROR_DOWNLOAD_THREAD_ALREADY_STARTED = 27,
  TFERROR_PLATFORM_NOT_SUPPORTED = 28,
  TFERROR_GENERATE_TUNING_PARAMETERS_ERROR = 29,
  TFERROR_GENERATE_TUNING_PARAMETERS_RESPONSE_NOT_SUCCESS = 30
}
enum
Tuning Fork 함수에서 반환할 수 있는 모든 오류 코드입니다.

Typedef

ProtoCallback)(const CProtobufSerialization *) typedef
void(*
TFSettings::fidelity_params_callback에 연결할 수 있는 함수에 대한 포인터입니다.
SwappyTracerFn)(const SwappyTracer *) typedef
void(*
TFSettings::swappy_tracer_fn에 연결할 수 있는 Swappy_injectTracers에 대한 포인터입니다.
TFDuration typedef
uint64_t
지속 기간(나노초)입니다.
TFInstrumentKey typedef
uint16_t
계측 키는 프레임 또는 트레이스 세그먼트 내의 틱 포인트를 식별합니다.
TFTimePoint typedef
uint64_t
에포크 이후의 시간(밀리초)입니다.
TFTraceHandle typedef
uint64_t
TuningFork_startTrace에 사용된 트레이스 핸들입니다.
UploadCallback)(const char *, size_t n) typedef
void(*
TuningFork_setUploadCallback에 전달할 수 있는 함수에 대한 포인터입니다.

함수

CProtobufSerialization_Free(CProtobufSerialization *ser)
void
프로토콜 버퍼 직렬화에서 소유한 메모리를 할당 해제합니다.
TuningFork_destroy()
Tuning Fork에서 소유한 모든 메모리를 정리하고 스레드를 종료합니다.
TuningFork_enableMemoryRecording(bool enable)
메모리 원격 분석 기록을 사용 설정 또는 중지합니다.
TuningFork_endTrace(TFTraceHandle handle)
트레이스 세그먼트를 중지하고 기록합니다.
TuningFork_flush()
현재 히스토그램을 강제로 업로드합니다.
TuningFork_frameDeltaTimeNanos(TFInstrumentKey key, TFDuration dt)
시스템 시간이 아닌 외부 시간을 사용하여 프레임 틱을 기록합니다.
TuningFork_frameTick(TFInstrumentKey key)
계측 키 및 현재 주석과 연결될 프레임 틱을 기록합니다.
TuningFork_getFidelityParameters(const CProtobufSerialization *defaultParams, CProtobufSerialization *params, uint32_t timeout_ms)
서버에서 충실도 매개변수를 가져오는 차단 호출입니다.
TuningFork_init(const TFSettings *settings, JNIEnv *env, jobject context)
Tuning Fork를 초기화합니다.
TuningFork_setCurrentAnnotation(const CProtobufSerialization *annotation)
현재 주석을 설정합니다.
TuningFork_setFidelityParameters(const CProtobufSerialization *params)
현재 활성 충실도 매개변수를 설정합니다.
TuningFork_setUploadCallback(UploadCallback cbk)
TuningFork가 업로드를 실행할 때마다 별도의 스레드에 호출되는 콜백을 설정합니다.
TuningFork_startTrace(TFInstrumentKey key, TFTraceHandle *handle)
트레이스 세그먼트를 시작합니다.

구조체

CProtobufSerialization

직렬화된 프로토콜 버퍼를 나타내는 일련의 바이트입니다.

TFSettings

초기화 설정에서는 사용되지 않는 값을 0으로 맞춥니다.

열거

InstrumentKeys

 InstrumentKeys

프레임 내의 기간을 나타내는 계측 키입니다.

64000~65535 키는 예약되어 있습니다.

속성
TFTICK_CPU_TIME

프레임 시작과 Swappy_swap 호출 사이의 시간입니다.

TFTICK_GPU_TIME

버퍼 스왑과 GPU 펜스 트리거 사이의 시간입니다.

TFTICK_PACED_FRAME_TIME

eglSwapBuffers 호출 또는 Vulkan 큐 표시 종료 사이의 프레임 시간입니다.

TFTICK_RAW_FRAME_TIME

GPU 시간을 사용할 수 있으면 이 속성은 MAX(CPU_TIME,GPU_TIME)입니다. 그렇지 않으면 이 속성은 PACED_FRAME_TIME과 동일합니다.

TFErrorCode

 TFErrorCode

Tuning Fork 함수에서 반환할 수 있는 모든 오류 코드입니다.

속성
TFERROR_ALREADY_INITIALIZED

TuningFork_init가 두 번 이상 호출되었습니다.

TFERROR_B64_ENCODE_FAILED

protobuf를 인코딩할 수 없습니다.

TFERROR_BAD_FILE_OPERATION

일반 파일 오류입니다.

TFERROR_BAD_PARAMETER

잘못된 제네릭 매개변수입니다.

TFERROR_BAD_SETTINGS

잘못된 tuningfork_settings.bin 파일입니다.

TFERROR_COULDNT_SAVE_OR_DELETE_FPS

TuningFork_saveOrDeleteFidelityParamsFile을 호출하는 동안에 오류가 발생했습니다.

TFERROR_DOWNLOAD_THREAD_ALREADY_STARTED

TuningFork_startFidelityParamDownloadThread가 두 번 이상 호출되었거나 TuningFork_init가 이미 다운로드를 시작했을 때 호출되었습니다.

TFERROR_GENERATE_TUNING_PARAMETERS_ERROR

generateTuningParameters에 대한 응답을 파싱하는 동안에 오류가 발생했습니다.

TFERROR_GENERATE_TUNING_PARAMETERS_RESPONSE_NOT_SUCCESS

generateTuningParameters의 응답이 성공 코드가 아니었습니다.

TFERROR_INVALID_ANNOTATION

TuningFork_setCurrentAnnotation 매개변수가 잘못되었습니다.

TFERROR_INVALID_DEFAULT_FIDELITY_PARAMS

fpDefaultFileNum이 범위를 벗어났습니다.

TFERROR_INVALID_INSTRUMENT_KEY

틱 함수에 전달된 계측 키가 잘못되었습니다.

TFERROR_INVALID_TRACE_HANDLE

TuningFork_endTrace에 전달된 핸들이 잘못되었습니다.

TFERROR_JNI_BAD_ENV

Jni 오류 - 더 이상 사용되지 않습니다.

TFERROR_JNI_BAD_JVM

Jni 오류 - 더 이상 사용되지 않습니다.

TFERROR_JNI_BAD_THREAD

Jni 오류 - 더 이상 사용되지 않습니다.

TFERROR_JNI_BAD_VERSION

Jni 오류 - 더 이상 사용되지 않습니다.

TFERROR_JNI_EXCEPTION

Jni 오류 - 예외가 발생했습니다. logcat 출력을 참고하세요.

TFERROR_NO_CLEARCUT

더 이상 사용되지 않습니다.

TFERROR_NO_FIDELITY_PARAMS

초기화 시 충실도 매개변수를 찾을 수 없습니다.

TFERROR_NO_FIDELITY_PARAMS_IN_APK

assets/tuningfork에서 dev_tuningfork_fidelityparams_#.bin을 찾을 수 없습니다.

TFERROR_NO_SETTINGS

assets/tuningfork에서 tuningfork_settings.bin을 찾을 수 없습니다.

TFERROR_NO_SETTINGS_ANNOTATION_ENUM_SIZES

tuningfork_settings.bin의 일부가 누락되었습니다.

TFERROR_NO_SUCH_KEY

파일 캐시에 액세스할 때 해당 키가 없습니다.

TFERROR_NO_SWAPPY

필요한 Swappy 함수를 찾을 수 없습니다.

TFERROR_OK

오류가 없습니다.

TFERROR_PLATFORM_NOT_SUPPORTED

게임 또는 앱이 Tuning Fork를 지원하지 않는 플랫폼에서 실행됩니다.

Unity 플러그인에서만 사용됩니다.

TFERROR_PREVIOUS_UPLOAD_PENDING

다른 요청이 대기 중이므로 업로드할 수 없습니다.

TFERROR_TIMEOUT

충실도 매개변수 요청 시간이 초과되었습니다.

TFERROR_TUNINGFORK_NOT_INITIALIZED

Tuning Fork가 초기화되기 전에 호출되었습니다.

TFERROR_UPLOAD_TOO_FREQUENT

TuningFork_flush 호출이 너무 자주 실행됩니다.

Typedef

ProtoCallback

void(* ProtoCallback)(const CProtobufSerialization *)

TFSettings::fidelity_params_callback에 연결할 수 있는 함수에 대한 포인터입니다.

다운로드된 충실도 매개변수를 사용하여 호출될 함수입니다. 참고 항목: TFSettings

SwappyTracerFn

void(* SwappyTracerFn)(const SwappyTracer *)

TFSettings::swappy_tracer_fn에 연결할 수 있는 Swappy_injectTracers에 대한 포인터입니다.

참고 항목: TFSettings

TFDuration

uint64_t TFDuration

지속 기간(나노초)입니다.

TFInstrumentKey

uint16_t TFInstrumentKey

계측 키는 프레임 또는 트레이스 세그먼트 내의 틱 포인트를 식별합니다.

TFTimePoint

uint64_t TFTimePoint

에포크 이후의 시간(밀리초)입니다.

TFTraceHandle

uint64_t TFTraceHandle

TuningFork_startTrace에 사용된 트레이스 핸들입니다.

UploadCallback

void(* UploadCallback)(const char *, size_t n)

TuningFork_setUploadCallback에 전달할 수 있는 함수에 대한 포인터입니다.

TuningFork가 업로드를 실행할 때마다 별도의 스레드에 호출될 함수입니다. 참고 항목: TFSettings

함수

CProtobufSerialization_Free

void CProtobufSerialization_Free(
  CProtobufSerialization *ser
)

프로토콜 버퍼 직렬화에서 소유한 메모리를 할당 해제합니다.

세부정보
매개변수
ser
프로토콜 버퍼 직렬화

TuningFork_destroy

TFErrorCode TuningFork_destroy()

Tuning Fork에서 소유한 모든 메모리를 정리하고 스레드를 종료합니다.

세부정보
반환
Tuning Fork가 초기화되지 않은 경우 외에는 TFERROR_OK를 반환합니다.

TuningFork_enableMemoryRecording

TFErrorCode TuningFork_enableMemoryRecording(
  bool enable
)

메모리 원격 분석 기록을 사용 설정 또는 중지합니다.

기본적으로 초기화 시 메모리 원격 분석 기록이 사용 설정됩니다.

세부정보
매개변수
enable
true이면 메모리 기록이 사용 설정되며, false이면 메모리 기록이 사용 중지됩니다.
반환
Tuning Fork가 초기화되지 않은 경우 외에는 TFERROR_OK를 반환합니다.

TuningFork_endTrace

TFErrorCode TuningFork_endTrace(
  TFTraceHandle handle
)

트레이스 세그먼트를 중지하고 기록합니다.

세부정보
매개변수
handle
TuningFork_startTrace에서 이전에 반환한 핸들입니다.
반환
핸들이 잘못된 경우 TFERROR_INVALID_TRACE_HANDLE을 반환합니다. 성공 시 TFERROR_OK를 반환합니다.

TuningFork_flush

TFErrorCode TuningFork_flush()

현재 히스토그램을 강제로 업로드합니다.

세부정보
반환
업로드가 시작될 수 있는 경우 TFERROR_OK를 반환합니다. 이 업로드를 차단하는 이전 업로드가 있는 경우 TFERROR_PREVIOUS_UPLOAD_PENDING을 반환합니다. 이전 업로드 이후 1분 미만이 경과한 경우 TFERROR_UPLOAD_TOO_FREQUENT를 반환합니다.

TuningFork_frameDeltaTimeNanos

TFErrorCode TuningFork_frameDeltaTimeNanos(
  TFInstrumentKey key,
  TFDuration dt
)

시스템 시간이 아닌 외부 시간을 사용하여 프레임 틱을 기록합니다.

참고 항목: 위의 예약된 계측 키

세부정보
매개변수
key
계측 키
매개변수
dt
기록하려는 기간(나노초)
반환
계측 키가 잘못된 경우 TFERROR_INVALID_INSTRUMENT_KEY를 반환합니다. 성공 시 TFERROR_OK를 반환합니다.

TuningFork_frameTick

TFErrorCode TuningFork_frameTick(
  TFInstrumentKey key
)

계측 키 및 현재 주석과 연결될 프레임 틱을 기록합니다.

NB: 다른 스레드에서 틱 또는 트레이스 함수를 호출하는 것은 허용되지만 단일 계측 키는 항상 동일한 스레드에서 틱해야 합니다. 참고 항목: 위의 예약된 계측 키

세부정보
매개변수
key
계측 키
반환
계측 키가 잘못된 경우 TFERROR_INVALID_INSTRUMENT_KEY를 반환합니다. 성공 시 TFERROR_OK를 반환합니다.

TuningFork_getFidelityParameters

TFErrorCode TuningFork_getFidelityParameters(
  const CProtobufSerialization *defaultParams,
  CProtobufSerialization *params,
  uint32_t timeout_ms
)

서버에서 충실도 매개변수를 가져오는 차단 호출입니다.

TuningFork_init에 설정의 일부로 fidelity_params_callback을 전달한다면 이 함수를 호출할 필요가 없습니다. 충실도 매개변수가 다운로드되면 타이밍 정보가 이러한 매개변수와 연결된 것으로 기록됩니다. 이후에 GetFidelityParameters를 호출하고 새 매개변수 집합을 다운로드하면 이미 수집된 모든 데이터가 백엔드에 제출됩니다. 'params'의 소유권은 호출자에게 이전되므로 작업이 완료되면 params->dealloc을 호출해야 합니다. 매개변수 요청은 ${url_base}+'applications/'+package_name+'/apks/'+version_number+':generateTuningParameters'에 전송됩니다.

세부정보
매개변수
defaultParams
다운로드할 수 있는 매개변수가 없다면 이 매개변수는 현재 상태로 간주됩니다.
params
timeout_ms
연결할 수 없을 때 이 호출에서 반환하기 전에 대기할 시간입니다. 0이거나 음수이면 Settings.initial_request_timeout_ms의 값이 사용됩니다.
반환
매개변수를 다운로드하기 전에 먼저 시간 초과가 발생하면 TFERROR_TIMEOUT을 반환합니다. 성공 시 TFERROR_OK를 반환합니다.

TuningFork_init

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

Tuning Fork를 초기화합니다.

이 함수는 다른 함수보다 먼저 호출해야 합니다.

라이브러리는 tuningfork_settings.bin 파일에서 히스토그램 및 주석 설정을 로드합니다. 참고 항목: 다른 설정이 초기화 동작을 변경하는 방식에 관한 의미 체계는 TFSettings를 참고하세요.

세부정보
매개변수
settings
TFSettings 구조
env
JNIEnv
context
앱 컨텍스트
반환
성공하면 TFERROR_OK, 설정을 찾을 수 없다면 TFERROR_NO_SETTINGS, tuningfork_settings.bin 파일이 유효하지 않다면 TFERROR_BAD_SETTINGS, tuningfork가 이미 초기화되었다면 TFERROR_ALREADY_INITIALIZED를 반환합니다.

TuningFork_setCurrentAnnotation

TFErrorCode TuningFork_setCurrentAnnotation(
  const CProtobufSerialization *annotation
)

현재 주석을 설정합니다.

세부정보
매개변수
annotation
현재 주석의 protobuf 직렬화입니다.
반환
주석이 설정과 일치하지 않으면 TFERROR_INVALID_ANNOTATION을 반환합니다.
반환
성공 시 TFERROR_OK를 반환합니다.

TuningFork_setFidelityParameters

TFErrorCode TuningFork_setFidelityParameters(
  const CProtobufSerialization *params
)

현재 활성 충실도 매개변수를 설정합니다.

이 함수는 실험 모드에서 다운로드된 모든 매개변수를 재정의합니다. 예를 들어 플레이어가 게임 품질 설정을 수동으로 변경한 때에 사용합니다. 이 함수는 이전 매개변수와 관련된 모든 데이터를 플러시(즉, 업로드)합니다.

세부정보
매개변수
params
프로토콜 버퍼에서 인코딩한 매개변수입니다.
반환
매개변수를 설정할 수 있다면 TFERROR_OK를 반환합니다.

TuningFork_setUploadCallback

TFErrorCode TuningFork_setUploadCallback(
  UploadCallback cbk
)

TuningFork가 업로드를 실행할 때마다 별도의 스레드에 호출되는 콜백을 설정합니다.

세부정보
매개변수
cbk
반환
Tuning Fork가 초기화되지 않은 경우 외에는 TFERROR_OK를 반환합니다.

TuningFork_startTrace

TFErrorCode TuningFork_startTrace(
  TFInstrumentKey key,
  TFTraceHandle *handle
)

트레이스 세그먼트를 시작합니다.

참고 항목: 위의 예약된 계측 키

세부정보
매개변수
key
계측 키
매개변수
handle
성공 시 새 핸들로 채워져 있습니다.
반환
계측 키가 잘못된 경우 TFERROR_INVALID_INSTRUMENT_KEY를 반환합니다. 성공 시 TFERROR_OK를 반환합니다.