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
yFidelityParams
. - Solo puedes usar
enums
definidas en este archivo como parte de las anotaciones. - Solo puedes usar
enums
,int32s
ofloats
en los camposFidelityParams
. - 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 serTIME_BASED
para cargas cada n milisegundos oTICK_BASED
para cargas cada n marcas.intervalms_or_count
: corresponde al n del campomethod
.max_instrumentation_keys
: es la cantidad de etiquetas de marca que se usarán. Establécela en4
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 enlogcat
, 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 establecestraining_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
yrequired
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.