Questa guida descrive come integrare la release Jetpack dell'API Memory Advice nella tua app utilizzando Android Studio.
I giochi dovrebbero usare la release dell'API Memory Advice consigliata per il loro ambiente di build. Per Android Studio, consigliamo la release Jetpack. Per informazioni sulle release di altri ambienti di build, ad esempio l'estensione per lo sviluppo di giochi Android (AGDE), consulta la sezione Distribuzioni.
Aggiungi la raccolta
Questa sezione descrive come aggiungere la libreria al tuo progetto Android Studio (plug-in Android Gradle).
Aggiungi le dipendenze
Per aggiungere la libreria al tuo progetto Android Studio, svolgi i seguenti passaggi:
Abilita la libreria Android Jetpack a livello di progetto
gradle.properties
), il file normalmente si trova nella directory root del progetto:android.useAndroidX=true
Apri il file
build.gradle
a livello di modulo e aggiungi quanto segueimplementation
al blocco delle dipendenze. Questo dichiara le dipendenze dell'API per i suggerimenti sulla memoria nella tua 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 NDK supportate è disponibile nella pagina della release Jetpack dei giochi Android.
Dichiara flag di build aggiuntivi per CMake. Per farlo, aggiungi il seguente codice al blocco
defaultConfig
che si trova all'interno del bloccoandroid
:externalNativeBuild { cmake { cppFlags '-std=c++14' // c++_shared flavor is the only supported STL type. arguments "-DANDROID_STL=c++_shared" } }
Attiva la funzionalità Prefabbricato. Per il plug-in Android 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 di prefabbrica per le istruzioni di configurazione.
Salva il file. Se viene visualizzato il seguente messaggio, fai clic sul pulsante Sync Now (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.
Configurare CMake per la build C/C++
Per aggiungere al progetto i file di intestazione e la libreria di runtime per l'API Memory Advice, 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:
Nella parte superiore del file, aggiungi la seguente riga dopo ogni riga
cmake_minimum_required
eproject
:find_package(games-memory-advice REQUIRED CONFIG)
Nel comando
target_link_libraries
, aggiungigames-memory-advice::memory_advice
. Questo rende l'API Memory Advice una dipendenza dalla libreria nativa del 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 di compilazione della libreria condivisa C/C++
dell'app che viene caricata automaticamente quando l'app carica la propria
libreria condivisa con la funzione System.loadlibrary()
.
Questo passaggio è facoltativo.
Individua nel progetto il codice Java che carica le librerie native. Se non esiste, aggiungilo. Il codice dovrebbe avere un aspetto simile a
System.loadLibrary("your-native-lib")
e trovarsi in un bloccostatic
.Aggiungi
System.loadLibrary("memory_advice")
inSystem.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
In questa sezione viene descritto 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 raccolta 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 dovrebbero essere disponibili nella libreria nativa. Ogni chiamata JNI alla tua libreria
native deve contenere queste variabili. Se utilizzi la
libreria GameActivity,
assicurati di
collegare il thread di chiamata a 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 all'intervallo a tua scelta. 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 Watcher
Puoi anche configurare un watcher e registrare l'API Memory Advice: la funzione di watcher verrà chiamata quando lo stato sta per raggiungere il limite o lo stato di memoria critico (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
Consulta la panoramica per risorse aggiuntive e problemi relativi ai report.