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

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

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

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

ส่วนนี้จะอธิบายวิธีเพิ่มไลบรารีลงในโปรเจ็กต์ Android Studio (ปลั๊กอิน Android Gradle)

เพิ่มการอ้างอิง

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

เปิดใช้ไลบรารี Android Jetpack ในระดับโปรเจ็กต์ gradle.properties) โดยปกติไฟล์จะอยู่ในไดเรกทอรีราก ของโปรเจ็กต์
```
  android.useAndroidX=true
```
เปิดไฟล์ build.gradle ระดับโมดูล แล้วเพิ่มข้อความต่อไปนี้ implementation ลงในบล็อกทรัพยากร Dependency ซึ่งจะประกาศการขึ้นต่อกันของ Memory Advice API ในแอป
```
 dependencies {
     implementation 'androidx.games:games-memory-advice:1.0.0-beta01'
 }
```
ระบุเวอร์ชัน NDK ภายในบล็อก android ดังนี้
```
 ndkVersion "23.1.7779620"
```
โปรดเลือก NDK เวอร์ชันที่เข้ากันได้กับ Memory Advice API ดูรายการเวอร์ชัน NDK ที่รองรับได้ในหน้าการเปิดตัว Android Games Jetpack
ประกาศ 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 หลักของโปรเจ็กต์ ในแผงโปรเจ็กต์ ไฟล์จะอยู่ใน app > src > main > 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 ได้ด้วย และระบบจะเรียกใช้ฟังก์ชันโปรแกรมตรวจสอบ เมื่อสถานะใกล้ถึงขีดจำกัดหรืออยู่ในสถานะหน่วยความจำวิกฤต (แต่จะไม่เรียกใช้สำหรับสถานะปกติ) ตัวอย่างเช่น โค้ดต่อไปนี้จะสร้าง Watcher และขอรับการแจ้งเตือนจาก 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);

ขั้นตอนถัดไป

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