Inizia a utilizzare l'API Memory Advice

Questa guida descrive come integrare la versione Jetpack dell'API Memory Advice nella tua app utilizzando Android Studio.

I giochi devono utilizzare la versione dell'API Memory Advice consigliata per il loro ambiente di build. Per Android Studio, ti consigliamo la versione Jetpack. Per informazioni sulle release per altri ambienti di build, come l'estensione per lo sviluppo di giochi Android (AGDE), consulta Distribuzioni.

Aggiungere la libreria

Questa sezione descrive come aggiungere la libreria al progetto Android Studio (plug-in Android per Gradle).

Aggiungi le dipendenze

Per aggiungere la libreria al tuo progetto Android Studio, completa i seguenti passaggi:

  1. Attiva la libreria Android Jetpack nel file gradle.properties a livello di progetto, che di solito si trova nella directory root del progetto:

      android.useAndroidX=true

  2. Apri il file build.gradle a livello di modulo e aggiungi il seguente implementation al blocco delle dipendenze. In questo modo vengono dichiarate le dipendenze dell'API Memory Advice nella tua app.

     dependencies {
     implementation 'androidx.games:games-memory-advice:1.0.0-beta01'
 }

  3. Specifica la versione dell'NDK all'interno del blocco android:

     ndkVersion "23.1.7779620"

    Assicurati di scegliere una versione dell'NDK compatibile con l'API Memory Advice. Un elenco delle versioni NDK supportate è disponibile nella pagina delle release di Android Games Jetpack.

  4. Dichiara flag di compilazione aggiuntivi per CMake. Per farlo, aggiungi il seguente codice al blocco defaultConfig all'interno del blocco android:

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

  5. Attiva la funzionalità Prefabbricato. Per il plug-in Android per Gradle(AGP) 4.1 o versioni successive, aggiungi il seguente codice al blocco android:

     buildFeatures {
    prefab true
 }

    Se utilizzi AGP 4.0 o versioni precedenti, consulta la pagina Prefab per le istruzioni di configurazione.

  6. Salva il file. Se visualizzi il seguente messaggio, fai clic sul pulsante Sincronizza ora per aggiornare il progetto:

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

Configura CMake per la build C/C++

Per aggiungere i file di intestazione e la libreria di runtime per l'API Memory Advice al tuo progetto, apri il file CMakeLists.txt principale del progetto. Nel riquadro Progetto, il file si trova in app > src > main > cpp. Dopo aver aperto il file, segui questi passaggi:

  1. Nella parte superiore del file, aggiungi la seguente riga dopo le righe cmake_minimum_required e project:

     find_package(games-memory-advice REQUIRED CONFIG)

  2. Nel comando target_link_libraries, aggiungi games-memory-advice::memory_advice. In questo modo, l'API Memory Advice diventa una dipendenza della libreria nativa del tuo progetto e viene inclusa nel pacchetto dell'applicazione finale. L'aggiornamento dovrebbe essere simile al seguente:

     target_link_libraries(
     your-native-lib

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

     #rest of the dependencies
     #...
 )

Configura i file Java

La libreria nativa inclusa nell'API Memory Advice è libmemory_advice.so. È una dipendenza di compilazione per la libreria condivisa C/C++ della tua app e viene caricata automaticamente quando la tua app carica la propria libreria condivisa con la funzione System.loadlibrary().

Questo passaggio è facoltativo.

  1. Trova nel tuo progetto il codice Java che carica le librerie native. Se non esiste, aggiungilo. Il codice dovrebbe essere simile a System.loadLibrary("your-native-lib") e si trova in un blocco static.

  2. Aggiungi System.loadLibrary("memory_advice") in System.loadLibrary("your-native-lib"). L'aggiornamento dovrebbe essere simile al seguente:

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

Utilizzare la libreria

Questa sezione descrive come utilizzare la libreria.

Aggiungi i file di intestazione

Includi nel progetto il seguente file di intestazione della libreria:

    #include <memory_advice/memory_advice.h>

Inizializzare la libreria

Devi inizializzare la libreria una volta all'avvio dell'app. Per farlo, aggiungi questo codice al tuo progetto:

    MemoryAdvice_init(env, activity);

I parametri env e activity sono le variabili JNIEnv* e jobject che devono essere disponibili per la tua libreria nativa. Ogni chiamata JNI alla tua libreria nativa deve contenere queste variabili. Se utilizzi la libreria GameActivity, assicurati di collegare il thread chiamante alla JavaVM prima di chiamare la funzione MemoryAdvice_init.

Esegui il polling dello stato della memoria

Puoi recuperare lo stato della memoria della tua app eseguendo il polling della libreria all'intervallo che preferisci. Utilizza la funzione MemoryAdvice_getMemoryState ogni volta che devi eseguire il polling della libreria:

    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;
    }

Configurare un osservatore

Puoi anche configurare un watcher e registrare l'API Memory Advice. La funzione watcher verrà chiamata quando lo stato si avvicina al limite o allo stato di memoria critico (ma non per lo stato ok). Ad esempio, il seguente codice crea un watcher e richiede una notifica dell'API Memory Advice ogni 2 secondi:

    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);

Passaggi successivi

Consulta la panoramica per risorse aggiuntive e segnalazione di problemi.