Inizia a utilizzare l'API Memory Advice

Questa guida descrive come integrare Release Jetpack della API Memory Advice nel tuo utilizzando Android Studio.

I giochi devono utilizzare la release dell'API Memory Advice, consigliati per l'ambiente di build. Per Android Studio, è consigliabile Lancio del jetpack. Per informazioni sulle release per altri ambienti di build, ad esempio l'estensione Android Game Development. (AGDE), consulta la sezione Distribuzioni.

Aggiungi la raccolta

Questa sezione descrive come aggiungere la libreria ad Android Studio (Android Gradle).

Aggiungi le dipendenze

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

Attiva la libreria Android Jetpack a livello di progetto gradle.properties. Generalmente il file si trova nella directory principale del tuo progetto:
```
  android.useAndroidX=true
```
Apri il file build.gradle a livello di modulo e aggiungi quanto segue implementation al blocco delle dipendenze. Questo dichiara l'API memory Recommendations delle dipendenze nell'app.
```
 dependencies {
     implementation 'androidx.games:games-memory-advice:1.0.0-beta01'
 }
```
Specifica la versione 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 di NDK supportate è disponibile nella pagina delle release di Android Games Jetpack.

Dichiara flag di build aggiuntivi per CMake. Per farlo, aggiungi il seguente codice alla 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"
     }
 }

Attiva la funzionalità Prefab. Per Android Gradle Plugin(AGP) 4.1 o versioni successive, aggiungi il seguente codice alla Blocco android:
```
 buildFeatures {
    prefab true
 }
```
Se utilizzi AGP 4.0 o versioni precedenti, consulta le Pagina prefabbricata per istruzioni sulla configurazione.
Salva il file. Se viene visualizzato 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.
```

Configurazione di CMake per C/C++

Aggiungere i file di intestazione e la libreria di runtime per l'API Memory Advice. nel tuo progetto, apri il file CMakeLists.txt principale del progetto. Nella riquadro Progetto, il file si trova in app > src > principale > cpp. Dopo l'apertura segui questi passaggi:

Nella parte superiore del file, aggiungi la seguente riga dopo una qualsiasi Righe cmake_minimum_required e project:
```
 find_package(games-memory-advice REQUIRED CONFIG)
```
Nel comando target_link_libraries, aggiungi games-memory-advice::memory_advice. Questo rende l'API Memory Advice una dipendenza dalla libreria nativa del tuo progetto e la include 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. Si tratta di una dipendenza in compilazione C/C++ e viene caricata automaticamente quando l'app carica la propria libreria condivisa con la funzione System.loadlibrary().

Questo passaggio è facoltativo.

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

Aggiungi System.loadLibrary("memory_advice") in System.loadLibrary("your-native-lib"). L'aggiornamento dovrebbe essere simile a questo: le seguenti:

 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 il seguente file di intestazione della libreria nel tuo progetto:

    #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 disponibili nella libreria nativa. Ogni chiamata JNI al tuo indirizzo deve contenere queste variabili. Se utilizzi raccolta GameActivity assicurati di collega il thread di chiamata alla JavaVM prima di chiamare la funzione MemoryAdvice_init.

Sondaggio per lo stato della memoria

Puoi recuperare lo stato della memoria della tua app eseguendo il polling della libreria nella intervallo di tempo desiderato. Utilizza la MemoryAdvice_getMemoryState ogni volta che devi eseguire un polling nella 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;
    }

Configura uno smartwatch

Puoi anche configurare un osservatore e registri l'API Memory Advice e la tua funzione watcher verrà chiamata quando lo stato sta per raggiungere il limite o la soglia stato memoria (ma non per lo stato ok). Ad esempio, il seguente codice crea un watcher e richiede una notifica 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);

Passaggio successivo

Visualizza la panoramica per risorse aggiuntive e problemi relativi ai report.