Google은 흑인 공동체를 위한 인종 간 평등을 진전시키기 위해 노력하고 있습니다. Google에서 어떤 노력을 하고 있는지 확인하세요.

주석, 충실도 매개변수 및 설정 정의

이 문서에서는 프로젝트에서 주석, 충실도 매개변수 및 설정을 지정하는 방법을 설명합니다.

주석 및 충실도 매개변수

주석은 틱이 기록될 때 게임이 어떤 작업을 하고 있는지에 관한 컨텍스트 정보를 제공합니다. 충실도 매개변수는 게임의 성능 및 그래픽 설정을 반영합니다. Google의 언어 중립적이며 구조화된 데이터 교환 형식인 프로토콜 버퍼를 사용하여 충실도 매개변수를 정의할 수 있습니다. 게임 내에서 프로토콜 버퍼를 사용하는 방법에 관한 자세한 내용은 프로토콜 버퍼 정보를 참고하세요.

게임에 사용할 수 있는 주석 및 충실도 매개변수는 프로젝트의 assets/tuningfork 디렉터리에 있는 dev_tuningfork.proto라는 파일에 정의되어 있습니다. 다음은 데모 앱의 예입니다.

syntax = "proto3";

package com.google.tuningfork;

enum InstrumentKey {
  CPU = 0;
  GPU = 1;
  SWAPPY_WAIT = 2;
  SWAPPY_SWAP = 3;
  CHOREOGRAPHER = 4;
}

enum LoadingState {
  LOADING_INVALID = 0;
  NOT_LOADING = 1;
  LOADING = 2;
}

enum Level {
  // 0 is not a valid value
  LEVEL_INVALID = 0;
  LEVEL_1 = 1;
  LEVEL_2 = 2;
  LEVEL_3 = 3;
};

message Annotation {
  LoadingState loading = 1;
  Level level = 2;
}

message FidelityParams {
  int32 num_spheres = 1;
  float tesselation_percent = 2;
}

다음 내용을 참고하세요.

  • 패키지는 com.google.tuningfork여야 합니다.
  • 메시지 이름은 정확하게 AnnotationFidelityParams여야 합니다.
  • 이 파일에 정의된 enums만 주석의 일부로 사용할 수 있습니다.
  • FidelityParams 필드에는 enums, int32s 또는 floats만 사용할 수 있습니다.
  • 유효성 검사 도구에서는 이러한 규칙을 적용합니다.

설정

Settings 메시지는 tuningfork.proto에 의해 정의됩니다. 다음 파일의 전체 예를 참고하세요.

gamesdk/samples/tuningfork/insightsdemo/app/src/main/assets/tuningfork/tuningfork_settings.txt

프로젝트의 assets/tuningfork 디렉터리에 있는 tuningfork_settings.txt라는 파일에서 게임 설정을 정의해야 합니다. 다음 필드만 지정하면 됩니다.

  • aggregation_strategy: 다음이 포함된 메시지:

    • method: n밀리초마다 업로드하려면 TIME_BASED 또는 n틱마다 업로드하려면 TICK_BASED를 선택합니다.
    • intervalms_or_count: method 필드의 n입니다.
    • max_instrumentation_keys: 사용할 계측 키의 수입니다. Android Frame Pacing 라이브러리를 사용하는 경우 4로 설정합니다.
    • annotation_enum_size: 시작 시 설명자에서 크기가 계산되므로 선택적 필드입니다.
  • api_key: 앱의 클라우드 프로젝트 API 키로, 엔드포인트에 대한 요청의 유효성을 검사하는 데 사용됩니다. 이 키를 생성하려면 API 사용 설정을 참고하세요. logcat에 연결 오류가 표시되면 API 키가 올바른지 확인합니다.

  • default_fidelity_parameters_filename: 초기화 시 사용된 충실도 매개변수 세트입니다(코드에서 training_fidelity_params를 설정하는 경우 선택사항).

  • loading_annotation_index: (선택사항) LoadingState 플래그의 주석 필드에 있는 색인입니다.

  • level_annotation_index: (선택사항) 레벨 번호의 주석 필드에 있는 색인입니다.

다음은 텍스트 표현의 예입니다.

aggregation_strategy: {method: TIME_BASED, intervalms_or_count: 10000,
  max_instrumentation_keys: 5, annotation_enum_size: [3,4]}
api_key: "API-KEY-FROM-GOOGLE-CLOUD-CONSOLE"
default_fidelity_parameters_filename: "dev_tuningfork_fidelityparams_3.bin"
loading_annotation_index: 1
level_annotation_index: 2

로드 주석

로드 주석은 레벨 로드 프로세스의 일부인 프레임을 표시합니다. 게임이 로드되는 동안 발생하는 느린 프레임이 전체 측정항목에 영향을 주지 않도록 로드 주석을 사용해야 합니다.

설정에서 loading_annotation_index 필드를 설정하면 이 색인이 있는 주석에 특별한 의미가 부여됩니다. 예를 들어 데모 앱에서 다음과 같은 주석이 사용됩니다.

message Annotation {
  LoadingState loading = 1;
  Level level = 2;
}

로드 주석이 LOADING으로 설정되어 있는 동안 프레임 틱은 무시됩니다. 로드 주석이 NOT_LOADING으로 재설정되면 LOADING 상태에 소요된 시간이 해당 주석의 히스토그램에 기록됩니다. 이 주석을 사용하여 게임에서 레벨을 로드하는 데 걸리는 시간을 추적합니다. Level enum의 값으로 레벨 번호를 지정합니다.

위 설정에서 loading_annotation_index가 1이므로 첫 번째 주석은 게임에서 다음 장면을 로드하는지 여부를 지정합니다. level_annotation_index가 2이므로 두 번째 주석은 레벨 번호를 지정합니다.

게임 도중에 이러한 주석을 수동으로 설정해야 합니다. 데모 앱에서는 모든 게임 레벨이 자동으로 순환되므로 이러한 예를 볼 수 있습니다. 자세한 내용은 insightsdemo.cppSetAnnotations() 함수를 참고하세요.

품질 수준 정의

품질 수준을 사용하여 세션에 주석을 지정하면 기기가 너무 높은 품질 수준에서 실행 중인지(성능이 저하됨) 또는 너무 낮은 품질 수준에서 실행 중인지(충실도가 필요 이상으로 감소됨) 확인할 수 있습니다.

게임의 품질 수준을 하나 이상 정의해야 하며, 가급적이면 여러 품질 수준을 정의해야 합니다. 품질 수준은 FidelityParams 메시지의 인스턴스에 해당합니다. 이러한 수준은 다음 파일 이름 형식을 사용하여 충실도를 높이는 순서로 지정해야 합니다.

dev_tuningfork_fidelityparams_i.txt

여기서 i는 1부터 시작되는 색인으로 최댓값은 15입니다. 이러한 파일은 프로젝트의 assets/tuningfork 디렉터리에 있어야 합니다. 샘플 프로젝트는 gamesdk/samples/tuningfork/insightsdemo/app/src/main/assets/tuningfork/ 디렉터리에 있는 이 구조의 예를 보여줍니다.

프로토콜 버퍼 정보

Tuning Fork 라이브러리는 설정, 주석 및 충실도 매개변수에 Google의 프로토콜 버퍼 형식을 사용합니다. 프로토콜 버퍼는 확장 가능하고 구조화된 데이터를 위한 잘 정의된 다국어 프로토콜입니다. 자세한 내용은 프로토콜 버퍼 문서를 참고하세요.

proto2와 proto3 비교

프로토콜 버퍼 형식의 버전은 다음과 같이 파일의 첫 번째 줄에 설정됩니다.

syntax="proto2";

proto2 및 proto3는 일반적으로 사용되는 두 가지 프로토콜 버퍼 버전입니다. 둘 다 동일한 와이어 형식을 사용하지만 정의 파일은 호환되지 않습니다. 두 버전 간 주요 차이점에는 다음이 포함됩니다.

  • proto3에서는 optionalrequired 키워드가 더 이상 허용되지 않습니다.
  • proto3에서는 모든 것이 사실상 optional입니다.
  • proto3에서는 확장이 지원되지 않습니다.

proto3는 C#으로 컴파일할 수 있으므로 proto 파일에 proto3를 사용합니다. proto2는 Tuning Fork 라이브러리에서 사용되는 제한된 기능 세트와도 잘 작동합니다.

텍스트 표현과 바이너리 표현 비교

바이너리 protobuf 와이어 형식은 잘 정의되어 있으며 다양한 protobuf 버전에서 안정적입니다(생성된 코드는 그렇지 않음). 또한 protobuf 라이브러리의 전체 버전이 생성하여 읽을 수 있는 텍스트 형식도 있습니다. 이 형식은 잘 정의되어 있지는 않지만 Tuning Fork 라이브러리의 제한된 기능 세트에 대해 안정적입니다. protoc 컴파일러를 사용하여 바이너리 형식과 텍스트 형식 간에 변환할 수 있습니다. 다음 명령어는 텍스트 protobuf를 바이너리로 변환합니다.

protoc --encode com.google.tuningfork.Settings tuningfork.proto < tuningfork_settings.txt > tuningfork_settings.bin

전체 protobuf 라이브러리는 크기가 몇 MB이므로 APK에 텍스트 파일이 아닌 바이너리 파일을 포함해야 합니다. Tuning Fork 라이브러리가 바이너리 파일을 사용하도록 하면 비슷한 양만큼 게임의 크기가 증가합니다.

전체, 라이트, 나노 비교

전체 protobuf 라이브러리뿐만 아니라 리플렉션, FileDescriptors 및 텍스트 형식과의 스트리밍 같은 일부 기능을 삭제하여 코드 공간을 줄이는 라이트 버전이 있습니다. 이 버전에는 여전히 몇 MB의 추가 코드 공간이 필요하므로 Tuning Fork 라이브러리는 내부적으로 nanopb 라이브러리를 사용합니다. 이 라이브러리의 소스 코드는 external/nanopb-cAndroid 오픈소스 프로젝트에 포함되어 있으며 gamesdk 분기의 일부입니다. 코드 크기가 문제라면 게임에 이 라이브러리를 사용합니다.

gamesdk/src/protobuf에는 세 가지 버전의 protobuf를 모두 통합하는 데 도움이 되는 CMake 파일이 있습니다. 샘플은 nanopb와 전체 protobuf를 모두 혼합하여 사용합니다.