Cómo comenzar a usar la API de Memory Advice

En esta guía, se describe cómo integrar la versión de Jetpack de la API de Memory Advice en tu app mediante Android Studio.

Los juegos deben usar la versión de la API de Memory Advice que se recomienda para su entorno de compilación. Para Android Studio, recomendamos la versión de Jetpack. Si deseas obtener información sobre versiones para otros entornos de compilación, como Android Game Development Extension (AGDE), consulta Distribuciones.

Cómo agregar la biblioteca

En esta sección, se describe cómo agregar la biblioteca a tu proyecto de Android Studio (complemento de Android para Gradle).

Cómo agregar las dependencias

Para agregar la biblioteca a tu proyecto de Android Studio, sigue estos pasos:

Habilita la biblioteca de Android Jetpack en el nivel de proyecto gradle.properties. Por lo general, el archivo se encuentra en el directorio raíz de tu proyecto:
```
  android.useAndroidX=true
```
Abre el archivo build.gradle del nivel del modelo y agrega el siguiente elemento implementation al bloque de dependencias. De esta manera, se declaran las dependencias de la API de Memory Advice en tu app.
```
 dependencies {
     implementation 'androidx.games:games-memory-advice:1.0.0-beta01'
 }
```
Especifica la versión del NDK dentro del bloque android:
```
 ndkVersion "23.1.7779620"
```
Asegúrate de elegir una versión del NDK compatible con la API de Memory Advice. Puedes consultar una lista de las versiones compatibles del NDK en la página de versiones de Jetpack de Android Games.

Declara marcas adicionales de compilación para CMake. Para hacerlo, agrega el siguiente código al bloque defaultConfig que se encuentra dentro del bloque android:

 externalNativeBuild {
     cmake {
         cppFlags '-std=c++14'
         // c++_shared flavor is the only supported STL type.
         arguments "-DANDROID_STL=c++_shared"
     }
 }

Habilita la función Prefab. Para el complemento de Android para Gradle (AGP) 4.1 o versiones posteriores, agrega el siguiente código en el bloque android:
```
 buildFeatures {
    prefab true
 }
```
Si usas AGP 4.0 o versiones anteriores, consulta la página de Prefab para obtener instrucciones de configuración.

Guarda el archivo. Si ves el siguiente mensaje, haz clic en el botón Sync Now para actualizar tu proyecto:

  Gradle files have changed since last project sync. A project sync may be
  necessary for the IDE to work properly.

Cómo configurar CMake para compilaciones de C/C++

Para agregar los archivos de encabezado y la biblioteca del entorno de ejecución de la API de Memory Advice a tu proyecto, abre el archivo CMakeLists.txt principal del proyecto. En el panel Project, el archivo se encuentra en app > src > main > cpp. Después de abrir el archivo, sigue estos pasos:

Cerca de la parte superior del archivo, agrega la siguiente línea después de cualquier línea cmake_minimum_required y project:
```
 find_package(games-memory-advice REQUIRED CONFIG)
```
En el comando target_link_libraries, agrega games-memory-advice::memory_advice. Esto hace que la API de Memory Advice dependa de la biblioteca nativa de tu proyecto y la incluya en el paquete final de tu aplicación. La actualización debería ser similar a la siguiente:
```
 target_link_libraries(
     your-native-lib

     #link memory advice to the project
     games-memory-advice::memory_advice

     #rest of the dependencies
     #...
 )
```

Cómo configurar los archivos Java

La biblioteca nativa que se incluye con la API de Memory Advice es libmemory_advice.so. Es una dependencia de compilación para la biblioteca compartida de C/C++ de tu app y se carga automáticamente cuando esta carga su propia biblioteca compartida con la función System.loadlibrary().

Este paso es opcional.

Busca el código Java en tu proyecto que carga las bibliotecas nativas. Si no existe, agrégalo. El código debe ser similar a System.loadLibrary("your-native-lib") y se ubica en un bloque static.

Agrega System.loadLibrary("memory_advice") bajo System.loadLibrary("your-native-lib"). La actualización debería ser similar a la siguiente:

 static {
     System.loadLibrary("your-native-lib");
     // Note: loading libmemory_advice.so is optional.
     System.loadLibrary("memory_advice");
 }

Cómo usar la biblioteca

En esta sección, se describe cómo usar la biblioteca.

Cómo agregar los archivos de encabezado

Incluye el siguiente archivo de encabezado de biblioteca en tu proyecto:

    #include <memory_advice/memory_advice.h>

Cómo inicializar la biblioteca

Deberás inicializar la biblioteca una vez cuando se inicie la app. Para ello, agrega este código a tu proyecto:

    MemoryAdvice_init(env, activity);

Los parámetros env y activity son las variables JNIEnv* y jobject que deben estar disponibles para tu biblioteca nativa. Cada llamada de JNI a tu biblioteca nativa debe contener estas variables. Si usas la biblioteca de GameActivity, asegúrate de adjuntar el subproceso de llamada a JavaVM antes de llamar a la función MemoryAdvice_init.

Cómo hacer un sondeo para el estado de la memoria

Para recuperar el estado de la memoria de tu app, sondea la biblioteca en el intervalo que elijas. Usa la función MemoryAdvice_getMemoryState siempre que necesites sondear la biblioteca:

    MemoryAdvice_MemoryState state = MemoryAdvice_getMemoryState();
    switch (state) {
      case MEMORYADVICE_STATE_OK:
        // The application can safely allocate significant memory.
        break;
      case MEMORYADVICE_STATE_APPROACHING_LIMIT:
        //The application should minimize memory allocation.
        break;
      case MEMORYADVICE_STATE_CRITICAL:
        // The application should free memory as soon as possible,
        // until the memory state changes.
        break;
    }

Cómo configurar un observador

También puedes configurar un observador y registrar la API de Memory Advice. Se llamará a tu función de observador cuando el estado se acerque al límite o al estado crítico de la memoria (pero no para el estado correcto). Por ejemplo, el siguiente código crea un observador y solicita una notificación de la API de Memory Advice cada 2 segundos:

    static int USER_DATA;
    constexpr int callback_waittime_ms = 2000;

    void callback(MemoryAdvice_MemoryState state, void* context) {
        switch (state) {
          case MEMORYADVICE_STATE_APPROACHING_LIMIT:
            //The application should minimize memory allocation.
            break;
          case MEMORYADVICE_STATE_CRITICAL:
            // The application should free memory as soon as possible,
            // until the memory state changes.
            break;
        }
    }

    MemoryAdvice_registerWatcher(callback_waittime_ms, callback, &USER_DATA);

Próximo paso

Consulta la descripción general para obtener más recursos e informar problemas.