Introdução à API Memory Advice

Este guia descreve como integrar a versão do Jetpack da API Memory Advice ao seu app usando o Android Studio.

Os jogos precisam usar a versão da API Memory Advice recomendada para o ambiente de build deles. Para o Android Studio, recomendamos a versão do Jetpack. Para mais informações sobre versões de outros ambientes de build, como a Android Game Development Extension (AGDE), consulte Distribuições.

Adicionar a biblioteca

Esta seção descreve como adicionar a biblioteca ao seu projeto do Android Studio (Plug-in do Android para Gradle).

Adicionar as dependências

Para adicionar a biblioteca ao seu projeto do Android Studio, siga estas etapas:

Ative a biblioteca do Android Jetpack no nível do projeto gradle.properties. O arquivo normalmente fica localizado no diretório raiz do projeto:
```
  android.useAndroidX=true
```
Abra o arquivo build.gradle no nível do módulo e a implementation abaixo ao bloco de dependências. Isso declara as dependências da API Memory Advice no app.
```
 dependencies {
     implementation 'androidx.games:games-memory-advice:1.0.0-beta01'
 }
```
Especifique a versão do NDK no bloco android:
```
 ndkVersion "23.1.7779620"
```
Escolha uma versão do NDK compatível com a API Memory Advice. Uma lista de versões do NDK com suporte está disponível na página de versões do Android Games Jetpack.

Declarar outras sinalizações de build do CMake. Para fazer isso, adicione o código abaixo ao bloco defaultConfig que está dentro do bloco android:

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

Ative o recurso Prefab. Para o Plug-in do Android para Gradle (AGP) 4.1 ou mais recente, adicione o código abaixo ao bloco android:
```
 buildFeatures {
    prefab true
 }
```
Se você estiver usando o AGP 4.0 ou uma versão mais antiga, consulte a página do Prefab para instruções de configuração.

Salve o arquivo. Se a mensagem de erro abaixo aparecer, clique no botão Sync now para atualizar o projeto:

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

Configurar o CMake para builds C/C++

Para adicionar os arquivos principais e a biblioteca de execução da API Memory Advice ao seu projeto, abra o arquivo CMakeLists.txt principal. No painel Project, o arquivo está em app > src > main > cpp. Depois de abrir o arquivo, siga estas etapas:

Próximo à parte de cima do arquivo, adicione a linha abaixo após qualquer linha cmake_minimum_required e project:
```
 find_package(games-memory-advice REQUIRED CONFIG)
```
No comando target_link_libraries, adicione games-memory-advice::memory_advice. Isso torna a API Memory Advice uma dependência na biblioteca nativa do projeto e a inclui no pacote final do aplicativo. A atualização vai ser semelhante a esta:
```
 target_link_libraries(
     your-native-lib

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

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

Configurar os arquivos Java

A biblioteca nativa incluída na API Memory Advice é libmemory_advice.so. Ela é uma dependência de compilação para a própria biblioteca compartilhada C/C++ do app e é carregada automaticamente quando o app carrega a própria biblioteca compartilhada com a função System.loadlibrary().

Esta etapa é opcional.

Encontre o código Java que carrega as bibliotecas nativas no projeto. Adicione-o se ele não existir. O código precisa ser semelhante a System.loadLibrary("your-native-lib") e está localizado em um bloco static.

Adicione System.loadLibrary("memory_advice") em System.loadLibrary("your-native-lib"). A atualização vai ser semelhante a esta:

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

Usar a biblioteca

Esta seção descreve como usar a biblioteca.

Adicionar os arquivos principais

Inclua este arquivo principal de biblioteca no projeto:

    #include <memory_advice/memory_advice.h>

Inicializar a biblioteca

É necessário inicializar a biblioteca quando o app for iniciado. Para fazer isso, adicione o código abaixo ao projeto:

    MemoryAdvice_init(env, activity);

Os parâmetros env e activity são as variáveis JNIEnv* e jobject que precisam estar disponíveis para a biblioteca nativa. Todas as chamadas JNI na biblioteca nativa devem conter essas variáveis. Se você usar a biblioteca GameActivity, lembre-se de anexar a linha de execução de chamada à JavaVM antes de chamar a função MemoryAdvice_init.

Pesquisar o estado da memória

É possível extrair o estado da memória do app pesquisando a biblioteca no intervalo de sua escolha. Use a função MemoryAdvice_getMemoryState sempre que precisar pesquisar a 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;
    }

Configurar um observador

Também é possível configurar um inspetor e registrar a API Memory Advice. A função de inspetor vai ser chamada quando o estado estiver se aproximando do limite ou do estado da memória crítico, mas não é chamada para o estado "ok". Por exemplo, o código abaixo cria um inspetor e solicita uma notificação da API Memory Advice a cada dois 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óxima etapa

Consulte a visão geral para saber mais sobre outros recursos e como informar problemas.