เริ่มต้นใช้งาน Memory Advice API

คู่มือนี้จะอธิบายถึงวิธีผสานรวม การเปิดตัว Jetpack ของ Memory Advice API ใน โดยใช้ Android Studio

เกมควรใช้รุ่น Memory Advice API ที่ ที่แนะนำสำหรับสภาพแวดล้อมของบิลด์ สำหรับ Android Studio เราขอแนะนำ เปิดตัว Jetpack สำหรับข้อมูลเกี่ยวกับรุ่นสำหรับสภาพแวดล้อมของบิลด์อื่นๆ เช่น ส่วนขยายการพัฒนาเกม Android (AGDE) โปรดดูการกระจาย

เพิ่มไลบรารี

หัวข้อนี้จะอธิบายวิธีเพิ่มคลังลงใน Android Studio (Android ปลั๊กอิน Gradle)

เพิ่มทรัพยากร Dependency

หากต้องการเพิ่มไลบรารีลงในโปรเจ็กต์ Android Studio ให้ทำตามขั้นตอนต่อไปนี้

เปิดใช้ไลบรารี Android Jetpack ในระดับโปรเจ็กต์ gradle.properties) ซึ่งปกติไฟล์จะอยู่ในไดเรกทอรีราก ของโปรเจ็กต์ของคุณ:
```
  android.useAndroidX=true
```
เปิดไฟล์ระดับโมดูล build.gradle และเพิ่มรายการต่อไปนี้ implementation ไปยังบล็อกทรัพยากร Dependency ซึ่งเป็นการประกาศ API คำแนะนำด้านหน่วยความจำ ทรัพยากร Dependency ในแอป
```
 dependencies {
     implementation 'androidx.games:games-memory-advice:1.0.0-beta01'
 }
```
ระบุเวอร์ชัน NDK ภายในบล็อก android:
```
 ndkVersion "23.1.7779620"
```
ตรวจสอบว่าได้เลือกเวอร์ชันของ NDK ที่เข้ากันได้กับ Memory Advice API ดูรายการเวอร์ชัน NDK ที่รองรับได้ในหน้าการเผยแพร่ Jetpack ของ Android Games
ประกาศ Flag บิลด์เพิ่มเติมสำหรับ CMake โดยเพิ่มโค้ดต่อไปนี้ในส่วน defaultConfig ที่อยู่ภายในบล็อก android:
```
 externalNativeBuild {
     cmake {
         cppFlags '-std=c++14'
         // c++_shared flavor is the only supported STL type.
         arguments "-DANDROID_STL=c++_shared"
     }
 }
```
เปิดใช้ฟีเจอร์ Prefab สำหรับ Android Gradle Plugin(AGP) 4.1 ขึ้นไป ให้เพิ่มโค้ดต่อไปนี้ลงในส่วน บล็อก android:
```
 buildFeatures {
    prefab true
 }
```
หากคุณใช้ AGP 4.0 หรือเก่ากว่า โปรดดูที่ หน้า Prefab เพื่อดูวิธีการกำหนดค่า
บันทึกไฟล์ หากคุณเห็นข้อความต่อไปนี้ ให้คลิกซิงค์เดี๋ยวนี้ ปุ่มเพื่ออัปเดตโปรเจ็กต์ของคุณ:
```
  Gradle files have changed since last project sync. A project sync may be
  necessary for the IDE to work properly.
```

กำหนดค่า CMake สำหรับบิลด์ C/C++

วิธีเพิ่มไฟล์ส่วนหัวและไลบรารีรันไทม์สำหรับ Memory Advice API ลงในโปรเจ็กต์ ให้เปิดไฟล์ CMakeLists.txt หลักของโปรเจ็กต์ ใน แผงโปรเจ็กต์ ไฟล์อยู่ในแอป > src > หลัก > cpp หลังจากเปิด ให้ทำตามขั้นตอนต่อไปนี้

ใกล้กับด้านบนของไฟล์ ให้เพิ่มบรรทัดต่อไปนี้หลัง cmake_minimum_required และ project บรรทัด:
```
 find_package(games-memory-advice REQUIRED CONFIG)
```
ในคำสั่ง target_link_libraries ให้เพิ่ม games-memory-advice::memory_advice ทำให้ Memory Advice API ทรัพยากร Dependency สำหรับไลบรารีเนทีฟของโปรเจ็กต์และรวมไว้ในแพ็กเกจแอปพลิเคชันสุดท้าย การอัปเดตควรมีลักษณะคล้ายกับตัวอย่างต่อไปนี้
```
 target_link_libraries(
     your-native-lib

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

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

กำหนดค่าไฟล์ Java

ไลบรารีแบบเนทีฟที่รวมอยู่ใน Memory Advice API คือ libmemory_advice.so นี่เป็นทรัพยากร Dependency สำหรับคอมไพล์ของแอปของคุณเอง ไลบรารีที่ใช้ร่วมกันของ C/C++ และจะโหลดโดยอัตโนมัติเมื่อแอปของคุณโหลดขึ้นมาเอง ไลบรารีที่ใช้ร่วมกันด้วยฟังก์ชัน System.loadlibrary()

โดยคุณจะทำตามขั้นตอนนี้หรือไม่ก็ได้

ค้นหาโค้ด Java ในโปรเจ็กต์ที่โหลดไลบรารีแบบเนทีฟ หาก ไม่มีอยู่ โปรดเพิ่ม โค้ด ควรมีลักษณะคล้ายกับ System.loadLibrary("your-native-lib") และ อยู่ในบล็อก static
เพิ่ม System.loadLibrary("memory_advice") ใต้ System.loadLibrary("your-native-lib") การอัปเดตควรมีลักษณะคล้ายกับ ดังต่อไปนี้
```
 static {
     System.loadLibrary("your-native-lib");
     // Note: loading libmemory_advice.so is optional.
     System.loadLibrary("memory_advice");
 }
```

ใช้ไลบรารี

ส่วนนี้จะอธิบายวิธีใช้ไลบรารี

เพิ่มไฟล์ส่วนหัว

รวมไฟล์ส่วนหัวของไลบรารีต่อไปนี้ในโครงการ

    #include <memory_advice/memory_advice.h>

เริ่มต้นไลบรารี

คุณจะต้องเริ่มต้นไลบรารี 1 ครั้งเมื่อแอปเริ่มทำงาน โดยเพิ่ม รหัสลงในโครงการของคุณ:

    MemoryAdvice_init(env, activity);

พารามิเตอร์ env และ activity คือตัวแปร JNIEnv* และ jobject ที่ควรจะมีในไลบรารีเนทีฟของคุณ การโทร JNI ไปยังเนทีฟของคุณทุกครั้ง ควรมีตัวแปรเหล่านี้ด้วย หากคุณกำลังใช้ คลัง GameActivity อย่าลืม แนบเธรดการเรียกใช้ลงใน JavaVM ก่อนที่จะเรียกฟังก์ชัน MemoryAdvice_init

แบบสำรวจสำหรับสถานะหน่วยความจำ

คุณสามารถเรียกดูสถานะหน่วยความจำของแอปโดยการสำรวจไลบรารีที่ ช่วงเวลาที่คุณเลือก ใช้เมนู 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;
    }

ตั้งค่าผู้ดู

คุณยังสามารถตั้งค่า ผู้เฝ้าระวัง และลงทะเบียน Memory Advice API จากนั้นระบบจะเรียกใช้ฟังก์ชันผู้ดูของคุณ เมื่อสภาวะใกล้ถึงขีดจำกัดหรือสถานการณ์วิกฤต สถานะหน่วยความจำ (แต่ไม่ใช่สำหรับสถานะ Ok) ตัวอย่างเช่น โค้ดต่อไปนี้สร้างตัวเฝ้าดู และขอการแจ้งเตือน Memory Advice API ทุก 2 วินาที

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

ขั้นต่อไปคืออะไร

ดูภาพรวมสำหรับ แหล่งข้อมูลเพิ่มเติม และการรายงานปัญหา