ตัวอย่าง

ตัวอย่างสำหรับ Android Game Development Extension จะสาธิตวิธีใช้ฟีเจอร์หลักของส่วนขยาย หัวข้อนี้จะอธิบายตัวอย่างและการตั้งค่าที่จําเป็นต่อการเรียกใช้

ตัวอย่างต่อไปนี้มีอยู่ในหน้าดาวน์โหลด

• HelloJNI: โปรเจ็กต์เบื้องต้น
• Endless-Tunnel: โปรเจ็กต์ Android เท่านั้น
• Teapot: โปรเจ็กต์ข้ามแพลตฟอร์มสำหรับ Windows และ Android
• AssemblyCode-Link-Objects: โปรเจ็กต์เทมเพลตที่มีซอร์สโค้ดแอสเซมบลี

ก่อนจะเริ่มต้น

• ติดตั้ง Android Game Development Extension และตัวอย่าง ดูรายละเอียดได้ในการเริ่มต้นใช้งานอย่างรวดเร็ว หัวข้อนี้ยังอธิบายวิธีสร้างและเรียกใช้ตัวอย่าง รวมถึงใช้ตัวอย่าง Teapot เวอร์ชัน Android เป็นตัวอย่าง

• คู่มือการกำหนดค่าโปรเจ็กต์จะอธิบายวิธีกำหนดการตั้งค่าสำหรับโปรเจ็กต์ที่ใช้ส่วนขยาย เช่น การเพิ่มแพลตฟอร์ม Android และ APK

HelloJNI

ตัวอย่าง HelloJNI เป็นโปรเจ็กต์ง่ายๆ ที่แสดงข้อความ "Hello From JNI" ในหน้าต่างแอป โปรเจ็กต์ใช้ซอร์สโค้ดชุดอื่นสำหรับ Windows และ Android

• ไดเรกทอรีสคริปต์บิลด์ Gradle และซอร์สโค้ด Android: HelloJNI\AndroidPackaging
• โค้ดต้นฉบับของ Windows และไดเรกทอรีโปรเจ็กต์ Visual Studio: HelloJNI

เมื่อคุณสร้างโปรเจ็กต์ Visual Studio จะส่งการตั้งค่าต่อไปนี้ไปยังไฟล์ build.gradle ระดับแอป คุณเปลี่ยนการตั้งค่าเหล่านี้ได้โดยแก้ไขสคริปต์บิลด์ Gradle

• MSBUILD_NDK_VERSION
• MSBUILD_MIN_SDK_VERSION
• MSBUILD_JNI_LIBS_SRC_DIR
• MSBUILD_ANDROID_OUTPUT_APK_NAME
• MSBUILD_ANDROID_GRADLE_BUILD_OUTPUT_DIR

วิธีตั้งค่าและเรียกใช้ตัวอย่าง

แสดง / ซ่อนวิธีการ

1. ใน Visual Studio ให้เปิดและสร้างตัวอย่าง HelloJNI
2. เพิ่มแพลตฟอร์ม Android arm64-v8a ดูข้อมูลเพิ่มเติมได้ที่การเพิ่มแพลตฟอร์ม Android
3. เพิ่มรายการ Android APK ลงในแพลตฟอร์มใหม่
4. คอมไพล์โปรเจ็กต์
5. เพิ่มแพลตฟอร์ม Android ต่อไปนี้ แล้วเพิ่มรายการ APK ของ Android ลงในแพลตฟอร์มแต่ละรายการ Android-armeabi-v7a, Android-x86 และ Android-x86_64
6. สร้างและเรียกใช้ตัวอย่าง

Endless-Tunnel

ตัวอย่าง Endless-Tunnel เป็นเกม Android ที่ผู้เล่นต้องเก็บลูกบาศก์สีขาวขณะพยายามไปถึงปลายอุโมงค์ โดยพอร์ตมาจากตัวอย่าง OpenGL ในที่เก็บ Android NDK ใน GitHub ฟีเจอร์ลองฟังไม่มีเกมเวอร์ชัน Windows

ตัวอย่างนี้มีการกําหนดการตั้งค่าและแพลตฟอร์ม Android ไว้แล้ว คุณจึงสามารถคอมไพล์และเรียกใช้โปรเจ็กต์ใน Visual Studio ได้โดยไม่ต้องแก้ไข เมื่อคุณเปิดโซลูชัน Solution Explorer จะแสดงโมดูลต่อไปนี้

• endless-tunnel: โมดูลแอปพลิเคชันที่แสดงตรรกะเกม
• glm: สแนปชอตของที่เก็บข้อมูลคณิตศาสตร์ OpenGL ที่สร้างขึ้นเป็นไลบรารีแบบคงที่
• native_app_glue: ตัวแฝง NDK ที่สื่อสารกับออบเจ็กต์ NativeActivity

กาน้ำชา

ตัวอย่างกาน้ำชาแสดงกาน้ำชาแบบคลาสสิกที่ผ่านการจัดการแสดงผลด้วย OpenGL ES และพอร์ตไปยังส่วนขยายการพัฒนาเกม Android เพื่อสาธิตฟีเจอร์ต่อไปนี้

• การพัฒนาโปรเจ็กต์ข้ามแพลตฟอร์ม: คุณสามารถสร้างตัวอย่าง Teapot สำหรับ Windows และ Android ได้
• การใช้การบรรจุ Android ที่กําหนดเอง: สคริปต์บิลด์ Gradle ย้ายไปยังไดเรกทอรีรูทของตัวอย่างซึ่งมีไฟล์ Teapot.sln
• การกําหนดค่า Android ที่กําหนดเองซึ่งสาธิตวิธีใช้ Address Sanitizer (ASan) และ Hardware Address Sanitizer (HWASan)

การใช้งาน Teapot แบ่งออกเป็นหลายส่วน ซึ่งเป็นเรื่องปกติสำหรับแอปพลิเคชันและเกมข้ามแพลตฟอร์มขนาดใหญ่

• GameApplication โมดูล: กําหนดการดําเนินการของผู้ใช้และสถานะแอปพลิเคชัน เช่น ผู้ใช้หมุนกาต้มน้ำหรืออัปเดตสถิติแอปพลิเคชัน
• โมดูล GameEngine: ใช้โมดูลการแสดงผลหลัก

หากต้องการตั้งค่าตัวอย่างและเรียกใช้บน Android โปรดดูคู่มือเริ่มต้นใช้งานฉบับย่อ วิธีตั้งค่าตัวอย่างและเรียกใช้ใน Windows

แสดง / ซ่อนวิธีการ

1. ติดตั้ง GLEW
   1. ดาวน์โหลดและแตกไฟล์ GLEW
   2. คัดลอกไฟล์ไบนารีจาก $your-glew-directory\bin\Release\x64 ไปยัง %SystemRoot%\system32
2. ติดตั้ง freeglut
   1. ดาวน์โหลดและแตกไฟล์ freeglut
   2. คัดลอก $your-freeglut-directory\bin\x86\freeglut.dll ไปยัง %SystemRoot%\system32
3. เพิ่มทรัพยากร Dependency ของโปรเจ็กต์ freeglut โดยทำดังนี้
   1. เปิด Teapot.sln ใน Visual Studio
   2. ในเมนู ให้คลิกแก้ไขข้อบกพร่อง > x64 > โปรแกรมแก้ไขข้อบกพร่อง Windows ในพื้นที่
   3. ใน Solution Explorer ให้คลิกขวาที่ GameApplication แล้วเลือก Properties > C/C++ > General > Additional Include Directories
   4. เพิ่ม $your-freeglut-dir\include ลงในเส้นทาง
      
   5. คลิกตกลง
   6. เลือกตัวลิงก์ > ทั่วไป > ไดเรกทอรีไลบรารีเพิ่มเติม
   7. เพิ่ม $your-freeglut-dir\lib\x64 ลงในเส้นทาง
   8. คลิกตกลง
   9. เลือกตัวลิงก์ > ทั่วไป > ไดเรกทอรีไลบรารีเพิ่มเติม
   10. เพิ่ม freeglut.lib ลงในเส้นทาง
   11. คลิกตกลง
4. เพิ่มทรัพยากร Dependency ของโปรเจ็กต์ GLEW โดยทำดังนี้
   1. ในแผงเครื่องมือแก้ไขโซลูชัน ให้คลิกขวาที่ GameApplication แล้วเลือกคุณสมบัติ > C/C++ > ทั่วไป > ไดเรกทอรีรวมเพิ่มเติม
   2. เพิ่ม $your-glew-dir\include ลงในเส้นทาง
   3. คลิกตกลง
   4. เลือกตัวลิงก์ > ทั่วไป > ไดเรกทอรีไลบรารีเพิ่มเติม
   5. เพิ่ม $your-glew-dir\lib\Release\x86 ลงในเส้นทาง
   6. คลิกตกลง
   7. เลือกตัวลิงก์ > ทั่วไป > ไดเรกทอรีไลบรารีเพิ่มเติม
   8. เพิ่ม glew32.lib ลงในเส้นทาง
   9. คลิกตกลง
5. เรียกใช้ตัวอย่างใน Windows โดยทำดังนี้
   1. ในแถบเครื่องมือของ Visual Studio ให้คลิกปุ่มเรียกใช้โปรแกรมแก้ไขข้อบกพร่อง Windows ในพื้นที่
   2. ตัวอย่างควรมีลักษณะดังนี้
      

AssemblyCode-Link-Objects

นี่เป็นโปรเจ็กต์เทมเพลตที่แสดงวิธีสร้างไลบรารีแบบเนทีฟของ Android จากซอร์สโค้ดแอสเซมบลีและ C/C++ องค์ประกอบหลักมีดังนี้

• AssemblyCode-Link-Objects: ไลบรารีเนทีฟหลักของ Android ที่สร้างขึ้นจากซอร์สโค้ด C++ และ Assembly
• StaticLib: ไลบรารีแบบคงที่ของตัวช่วยซึ่งส่งออกฟังก์ชัน from_static_lib_assembly_code_as

โปรเจ็กต์รองรับสถาปัตยกรรมหลายรูปแบบ สถาปัตยกรรมที่รองรับแต่ละรายการจะมีไฟล์ต้นฉบับของตัวเองที่ใช้ฟังก์ชันที่ส่งออกจาก StaticLib คุณควรรวมเฉพาะไฟล์ต้นทางของ Assembly สำหรับแพลตฟอร์มที่คุณกำลังสร้าง โปรเจ็กต์นี้รวมไฟล์ประกอบไว้ในบิลด์โดยใช้เครื่องมือบิลด์ที่กำหนดเอง

วิธีตั้งค่าและสร้างตัวอย่าง

แสดง / ซ่อนวิธีการ

1. ใน Visual Studio ให้ตรวจสอบว่าได้กําหนดค่าเครื่องมือบิลด์ที่กําหนดเองสําหรับไฟล์ประกอบแล้ว โดยทําดังนี้
   1. ใน Solution Explorer ให้คลิกขวาที่ไฟล์แอสเซมบลี แล้วคลิกพร็อพเพอร์ตี้ ซึ่งจะเปิดกล่องโต้ตอบหน้าคุณสมบัติของไฟล์
   2. เลือกการกําหนดค่าและแพลตฟอร์ม เช่น การกําหนดค่าทั้งหมดสําหรับ Android-arm64-v8a
   3. ตรวจสอบว่าได้ตั้งค่าทั่วไป > ยกเว้นจากบิลด์เป็นไม่
   4. ตรวจสอบว่าได้ตั้งค่าทั่วไป > ประเภทรายการเป็นเครื่องมือสร้างที่กำหนดเอง
   5. คลิกใช้หากมีการเปลี่ยนแปลงที่จะใช้
   6. ตรวจสอบว่าพร็อพเพอร์ตี้การกําหนดค่า > เครื่องมือสร้างที่กําหนดเอง > บรรทัดคําสั่ง: มีการตั้งค่าเป็น$(AsToolExe) -o "$(IntDir)%(FileName).o" %(FullPath) NDK มีโปรแกรมประกอบแยกต่างหากสำหรับสถาปัตยกรรม CPU แต่ละแบบ และ$(AsToolExe)จะแมปกับโปรแกรมประกอบที่ถูกต้อง ตัวอย่างนี้ใช้ชุดเครื่องมือ NDK เพื่อสร้างโปรเจ็กต์ Android ทั้ง x86 และ x86_64 หากต้องการใช้ yasm สำหรับแพลตฟอร์ม Android x86_64 ให้ใช้ $(YasmToolExe) แทน
   7. ตรวจสอบว่าได้ตั้งค่าพร็อพเพอร์ตี้การกําหนดค่า > เครื่องมือบิลด์ที่กําหนดเอง > เอาต์พุตเป็น$(IntDir)%(FileName).o สตริงนี้ต้องรวมอยู่ในการตั้งค่าบรรทัดคำสั่ง
   8. ตรวจสอบว่าพร็อพเพอร์ตี้การกําหนดค่า > เครื่องมือบิลด์ที่กําหนดเอง > ลิงก์ออบเจ็กต์มีการตั้งค่าเป็นYes

   เช่น การตั้งค่า Android-arm64-v8a ควรมีลักษณะคล้ายกับภาพหน้าจอต่อไปนี้

   
2. สร้างโปรเจ็กต์ ซึ่งจะสร้างไฟล์ libAssmeblyCodeLinkObjects.so ดังนี้
   1. เปิดไฟล์ AssemblyCode-Link-Objects.sln
   2. ในเมนู ให้คลิกสร้าง > สร้างโซลูชัน
3. หากต้องการยืนยันว่ามีการส่งออกฟังก์ชันไปยังไลบรารี Android อย่างถูกต้อง ให้ใช้เครื่องมือ NDK ของ nm.exe โดยทำดังนี้
   1. ในบรรทัดคำสั่ง ให้ไปที่ไดเรกทอรีตัวอย่าง
   2. ไปที่ตำแหน่งไลบรารี Android ที่บิลด์สร้างขึ้น ตำแหน่งเริ่มต้นจะคล้ายกับ $sample_dir\$solution_configuration\$solution_platform\$platform และ $sample_dir\Debug\Android-arm64-v8a\arm64-v8a สำหรับแพลตฟอร์ม arm64-v8a
   3. ตรวจสอบว่าส่วนสัญลักษณ์ที่ส่งออกมีฟังก์ชันโดยเรียกใช้คำสั่งต่อไปนี้

        …\ndk\toolschains\llvm\prebuilt\windows-x86_64\aarch64-linux-android\bin\nm.exe --defined-only …\Debug\Android-arm64-v8a\arm64-v8a\libAssmeblyCodeLinkObjects.so

      ในเอาต์พุต คุณควรเห็นรายการสัญลักษณ์ต่อไปนี้

         T from_shared_object_assembly_code_as
         T from_static_lib_assembly_code_as

PoolAllocator

ตัวอย่าง PoolAllocator เป็นแอป Android ที่มีตัวจัดสรรหน่วยความจำที่อิงตามพูลซึ่งจัดสรรบล็อกขนาดคงที่ได้อย่างมีประสิทธิภาพ

ตัวแอลล็อกจะจัดสรรหน่วยความจําทั้งหมดไว้ล่วงหน้า ณ เวลาเริ่มต้นโดยใช้ mmap ระบบจะติดตามบล็อกว่างโดยใช้ลิงค์ลิสต์ จากนั้น การจัดสรรหน่วยความจำเป็นการดำเนินการ O(1) ที่รวดเร็วซึ่งแสดงผลส่วนหัวของลิงค์ลิสต์ และการจัดสรรหน่วยความจำยังเป็นการดำเนินการ O(1) เช่นกันเนื่องจากจะเพิ่มบล็อกไว้ที่ด้านหลังของลิงค์ลิสต์

ตัวอย่างนี้มีการกำหนดค่าโซลูชัน 2 รายการสําหรับการใช้ HWASan

• HWASan: การกําหนดค่านี้แสดงแนวทางที่ง่ายที่สุดในการใช้ HWASan กับตัวจัดสรรหน่วยความจําที่กําหนดเอง การใช้ตัวจัดสรรหน่วยความจำภายในจะแทนที่ด้วยการเรียกใช้ malloc/free ซึ่ง HWASan จะติดตามโดยอัตโนมัติ แม้ว่าตัวจัดสรรหน่วยความจำจะไม่ทำงานเป็นตัวจัดสรรตามพูลอีกต่อไป แต่ HWASan ยังคงช่วยคุณระบุข้อบกพร่องด้านหน่วยความจำที่สำคัญได้ เช่น การใช้งานหลังช่วงใช้ฟรี

• HWASan-Advanced: การกําหนดค่านี้แสดงวิธีผสานรวม HWASan เข้ากับตัวจัดสรรหน่วยความจําที่กําหนดเองโดยสมบูรณ์ โดยไม่เปลี่ยนกลไกการจัดสรรเดิมที่ใช้โดยตัวจัดสรร โดยจะใช้วิธีการติดแท็ก HWASan เพื่อติดแท็กบล็อกหน่วยความจำในพูลที่จัดสรรไว้ล่วงหน้า ปัดเศษขนาดบล็อกเป็นขนาดบล็อกขั้นต่ำที่ HWASan กำหนด และรีเซ็ตแท็กเมื่อมีการคืนบล็อกกลับไปยังพูล

ใช้การกําหนดค่า HWASan เนื่องจากง่ายกว่าและช่วยระบุข้อบกพร่องเกี่ยวกับหน่วยความจําที่พบได้ทั่วไป สํารวจการใช้งานการกําหนดค่า HWASan-Advanced หากต้องการทําความเข้าใจวิธีการทํางานของ HWASan หรือต้องการเก็บรักษาความหมายเชิงภายในของตัวจัดสรรหน่วยความจําขณะใช้ HWASan