Cette page a été traduite par l'API Cloud Translation.

Premiers pas avec l'API Memory Advice

Ce guide explique comment intégrer la version Jetpack de l'API Memory Advice dans une application avec Android Studio.

Les jeux doivent utiliser la version de l'API Memory Advice qui est recommandée pour leur environnement de compilation. Pour Android Studio, nous vous recommandons la version Jetpack. Pour connaître les versions qui s'appliquent à d'autres environnements de compilation, comme l'extension Android Game Development (AGDE), consultez Distributions.

Ajouter la bibliothèque

Cette section explique comment ajouter la bibliothèque à votre projet Android Studio (plug-in Android Gradle).

Ajouter les dépendances

Pour ajouter la bibliothèque à votre projet Android Studio, procédez comme suit :

Activez la bibliothèque Android Jetpack au niveau du projet (gradle.properties). Le fichier se trouve normalement dans le répertoire racine de votre projet :
```
  android.useAndroidX=true
```
Ouvrez le fichier build.gradle au niveau du module et ajoutez l'implementation suivante au bloc de dépendances. Cette commande déclare les dépendances de l'API Memory Advice dans votre application.
```
 dependencies {
     implementation 'androidx.games:games-memory-advice:1.0.0-beta01'
 }
```
Spécifiez la version du NDK dans le bloc android :
```
 ndkVersion "23.1.7779620"
```
Veillez à choisir une version du NDK compatible avec l'API Memory Advice. La liste des versions compatibles du NDK est disponible sur la page consacrée à la version Android Jetpack pour jeux Android.

Déclarez des indicateurs de build supplémentaires pour CMake. Pour ce faire, ajoutez le code suivant au bloc defaultConfig qui se trouve à l'intérieur du bloc android :

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

Activez la fonctionnalité Prefab. Pour le plug-in Android Gradle (AGP) 4.1 ou version ultérieure, ajoutez le code suivant au bloc android :
```
 buildFeatures {
    prefab true
 }
```
Si vous utilisez AGP 4.0 ou version antérieure, consultez la page Prefab pour obtenir des instructions de configuration.
Enregistrez le fichier. Si le message suivant s'affiche, cliquez sur le bouton Sync Now (Synchroniser) pour mettre à jour votre projet :
```
  Gradle files have changed since last project sync. A project sync may be
  necessary for the IDE to work properly.
```

Configurer CMake pour la compilation C/C++

Pour ajouter les fichiers d'en-tête et la bibliothèque d'exécution de l'API Memory Advice à votre projet, ouvrez le fichier CMakeLists.txt principal de votre projet. Dans le volet Project (Projet), le fichier se trouve sous app > src > main > cpp. Après avoir ouvert le fichier, procédez comme suit :

En haut du fichier, ajoutez la ligne suivante après les lignes cmake_minimum_required et project :
```
 find_package(games-memory-advice REQUIRED CONFIG)
```
Dans la commande target_link_libraries, ajoutez games-memory-advice::memory_advice. L'API Memory Advice devient ainsi une dépendance de la bibliothèque native de votre projet et est incluse dans votre package d'application final. La modification doit se présenter comme suit :
```
 target_link_libraries(
     your-native-lib

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

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

Configurer les fichiers Java

La bibliothèque native incluse dans l'API Memory Advice est libmemory_advice.so. Il s'agit d'une dépendance de compilation pour la bibliothèque partagée C/C++ de votre application. Elle est automatiquement chargée lorsque votre application charge sa propre bibliothèque partagée avec la fonction System.loadlibrary().

Cette étape est facultative.

Recherchez dans votre projet le code Java qui charge les bibliothèques natives. S'il n'existe pas, ajoutez-le. Le code doit se présenter sous la forme System.loadLibrary("your-native-lib") et se trouver dans un bloc static.

Ajoutez System.loadLibrary("memory_advice") sous System.loadLibrary("your-native-lib"). La modification doit se présenter comme suit :

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

Utiliser la bibliothèque

Cette section explique comment utiliser la bibliothèque.

Ajouter les fichiers d'en-tête

Incluez le fichier d'en-tête de bibliothèque suivant dans votre projet :

    #include <memory_advice/memory_advice.h>

Initialiser la bibliothèque

Vous devez initialiser la bibliothèque au démarrage de l'application. Pour ce faire, ajoutez le code suivant à votre projet :

    MemoryAdvice_init(env, activity);

Les paramètres env et activity sont les variables JNIEnv* et jobject qui doivent être disponibles pour votre bibliothèque native. Chaque appel JNI vers votre bibliothèque native doit contenir ces variables. Si vous utilisez la bibliothèque GameActivity, veillez à joindre le thread d'appel à la JavaVM avant d'appeler la fonction MemoryAdvice_init.

Interroger la bibliothèque sur l'état de la mémoire

Vous pouvez récupérer l'état de la mémoire de votre application en interrogeant la bibliothèque à l'intervalle de votre choix. Pour interroger la bibliothèque, utilisez la fonction MemoryAdvice_getMemoryState :

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

Configurer un observateur

Vous pouvez également configurer un observateur et enregistrer l'API Memory Advice. Votre fonction d'observateur sera appelée lorsque l'état de la mémoire approchera de la limite ou atteindra l'état critique (mais pas pour l'état OK). Par exemple, le code suivant crée un observateur et demande une notification de l'API Memory Advice toutes les deux secondes :

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

Étapes suivantes

Consultez la présentation pour accéder à des ressources supplémentaires et découvrir comment signaler des problèmes.