Cómo definir anotaciones, parámetros de fidelidad y opciones de configuración

En este documento, se describe cómo establecer anotaciones, parámetros de fidelidad y opciones de configuración en tu proyecto.

Anotaciones y parámetros de fidelidad

Las anotaciones proporcionan información contextual sobre lo que hace tu juego cuando se registra una marca. Los parámetros de fidelidad reflejan el rendimiento y la configuración gráfica del juego. Estos se definen mediante búferes de protocolo, que son el formato estructurado e independiente del lenguaje para el intercambio de datos de Google. A fin de obtener más información sobre el uso de búferes de protocolo en tu juego, consulta Acerca de los búferes de protocolo.

Las anotaciones y los parámetros de fidelidad posibles para el juego se definen en un archivo llamado dev_tuningfork.proto, que se encuentra en el directorio assets/tuningfork de tu proyecto. El siguiente es un ejemplo tomado de la app de demostración:

syntax = "proto3";

package com.google.tuningfork;

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

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

message Annotation {
  Level level = 1;
}

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

Ten en cuenta lo siguiente:

• El paquete debe ser com.google.tuningfork.
• Los nombres de los mensajes deben ser exactamente Annotation y FidelityParams.
• Solo puedes usar enums definidas en este archivo como parte de las anotaciones.
• Solo puedes usar enums, int32s o floats en los campos FidelityParams.
• La herramienta de validación aplica estas convenciones.

Configuración

El mensaje Settings se define mediante tuningfork.proto. Consulta un ejemplo completo en el siguiente archivo:

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

Debes definir la configuración del juego en un archivo llamado tuningfork_settings.txt ubicado en el directorio assets/tuningfork del proyecto. Solo debes especificar los siguientes campos:

• aggregation_strategy: es un mensaje que contiene lo siguiente:

  • method: puede ser TIME_BASED para cargas cada n milisegundos o TICK_BASED para cargas cada n marcas.
  • intervalms_or_count: corresponde al n del campo method.
  • max_instrumentation_keys: es la cantidad de etiquetas de marca que se usarán. Establécela en 4 si usas la biblioteca de Android Frame Pacing.
  • annotation_enum_size: es un campo opcional, ya que el tamaño se calcula durante el inicio del descriptor.

• api_key: es la clave de API del proyecto en la nube correspondiente a tu app, que se usa para validar solicitudes al extremo. Consulta Cómo habilitar la API a fin de generar esta clave. Si ves errores de conexión en logcat, verifica que la clave de API sea correcta.

• default_fidelity_parameters_filename: Es un conjunto de parámetros de fidelidad utilizados en la inicialización (es opcional si estableces training_fidelity_params en tu código).

• level_annotation_index: Es el índice en los campos de anotación del número de nivel (opcional).

A continuación, se muestra un ejemplo de representación de texto:

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"
level_annotation_index: 1

Cómo configurar anotaciones

Debes configurar anotaciones manualmente durante el juego. Puedes ver un ejemplo en la app de demostración, ya que avanza automáticamente por todos los niveles del juego. Para obtener más información, consulta la función SetAnnotations() en insightsdemo.cpp.

En este caso, la anotación solo especifica el número de nivel.

message Annotation {
  Level level = 1;
}

Cómo definir niveles de calidad

Usa los niveles de calidad para anotar las sesiones, de modo que puedas determinar si los dispositivos se están ejecutando en un nivel de calidad demasiado alto (lo que disminuye el rendimiento) o demasiado bajo (lo que reduce la fidelidad de manera innecesaria).

Debes definir al menos un nivel de calidad para tu juego, aunque es preferible que tengas varios. Un nivel de calidad corresponde a una instancia del mensaje FidelityParams. Se deben proporcionar estos niveles en orden creciente de fidelidad y con el siguiente formato de nombre de archivo:

dev_tuningfork_fidelityparams_i.txt

donde i es un índice que tiene un valor mínimo de 1 y un valor máximo de 15. Estos archivos deben estar ubicados en el directorio assets/tuningfork del proyecto. El proyecto de muestra presenta un ejemplo de esta estructura en el directorio gamesdk/samples/tuningfork/insightsdemo/app/src/main/assets/tuningfork/.

Acerca de los búferes de protocolo

La biblioteca de Tuning Fork usa el formato del búfer de protocolo de Google para la configuración, las anotaciones y los parámetros de fidelidad. Este es un protocolo bien definido, que admite varios idiomas y que se aplica a los datos estructurados extensibles. Para obtener más información, consulta la documentación sobre búferes de protocolo.

Diferencias entre proto2 y proto3

En la primera línea del archivo, se establece la versión del formato de búfer de protocolo:

syntax="proto2";

Proto2 y proto3 son dos versiones de los búferes de protocolo que se usan con frecuencia. Ambas usan el mismo formato de transferencia, pero los archivos de definición no son compatibles. Algunas diferencias fundamentales entre las dos versiones son las siguientes:

• Las palabras clave optional y required ya no se permiten en proto3.
• Todo es efectivamente optional en proto3.
• No se admiten extensiones en proto3.

Usa proto3 en tus archivos proto, ya que se pueden compilar en C#. Proto2 también funciona con el conjunto de atributos limitados que se usan en la biblioteca de Tuning Fork.

Diferencias entre las representaciones de texto y las binarias

El formato de transferencia binario protobuf está bien definido y resulta estable en diferentes versiones de protobuf (el código generado no lo es). También hay un formato de texto que la versión completa de la biblioteca de protobuf puede generar y leer. Este formato no está tan bien definido, pero es estable para el conjunto limitado de atributos de la biblioteca de Tuning Fork. Puedes convertir entre formatos binarios y de texto por medio del compilador protoc. El siguiente comando convierte un protobuf de texto en binario:

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

Debes incluir archivos binarios en lugar de archivos de texto en tu APK, ya que el tamaño de la biblioteca completa de protobuf es de varios MB. Hacer que la biblioteca de Tuning Fork dependa de ella hará que aumente el tamaño de tu juego en una cantidad similar.

Diferencias entre Full, Lite y Nano

Además de la biblioteca completa de protobuf, existe una versión lite que reduce la huella del código mediante la eliminación de algunas funciones, como la reflexión, los FileDescriptors y el flujo desde y hacia formatos de texto. Dado que esta versión aún requiere varios MB de huella de código adicional, la biblioteca de Tuning Fork utiliza la biblioteca nanopb de forma interna. El código fuente de esta biblioteca se incluye en el Proyecto de código abierto de Android, en external/nanopb-c, y es parte de la rama gamesdk. Usa esta biblioteca en tu juego si el tamaño del código es un problema.

Hay archivos CMake en gamesdk/src/protobuf que pueden ayudarte a integrar las tres versiones de protobuf. Las muestras contienen una combinación de nanopb y protobuf completo.