Contoh

Contoh Android Game Development Extension menunjukkan cara menggunakan fitur utama ekstensi tersebut. Topik ini menjelaskan contoh tersebut dan setelan yang diperlukan untuk menjalankannya.

Contoh berikut tersedia di halaman download:

• HelloJNI: project pengantar.
• Endless-Tunnel: project khusus Android.
• Teapot: project lintas platform untuk Windows dan Android.
• AssemblyCode-Link-Objects: project template yang memiliki kode sumber assembly.

Sebelum memulai

• Instal Android Game Development Extension beserta contohnya. Lihat panduan memulai untuk mengetahui detailnya. Topik ini juga menjelaskan cara membuat dan menjalankan contoh, serta menggunakan contoh Teapot versi Android sebagai contohnya.

• Panduan konfigurasi project menjelaskan cara mengonfigurasi setelan untuk project yang menggunakan ekstensi tersebut, seperti menambahkan platform Android dan APK.

HelloJNI

Contoh HelloJNI adalah project sederhana yang menampilkan pesan "Hello From JNI" di jendela aplikasi. Project ini menggunakan kumpulan kode sumber yang berbeda untuk Windows dan Android.

• Kode sumber Android dan direktori skrip build Gradle: HelloJNI\AndroidPackaging
• Kode sumber Windows dan direktori project Visual Studio: HelloJNI

Saat Anda membuat project, Visual Studio akan meneruskan setelan berikut ini ke file build.gradle tingkat aplikasi. Anda dapat mengubah setelan ini dengan mengubah skrip build Gradle.

• MSBUILD_NDK_VERSION
• MSBUILD_MIN_SDK_VERSION
• MSBUILD_JNI_LIBS_SRC_DIR
• MSBUILD_ANDROID_OUTPUT_APK_NAME
• MSBUILD_ANDROID_GRADLE_BUILD_OUTPUT_DIR

Untuk menyiapkan dan menjalankan contoh:

Tampilkan/Sembunyikan Petunjuk

1. Di Visual Studio, buka dan buat contoh HelloJNI.
2. Tambahkan platform Android arm64-v8a. Untuk informasi selengkapnya, lihat Menambahkan Platform Android.
3. Tambahkan item APK Android ke platform baru.
4. Kompilasikan project.
5. Tambahkan platform Android berikut, lalu tambahkan item APK Android ke setiap platform tersebut: Android-armeabi-v7a, Android-x86, dan Android-x86_64.
6. Buat dan jalankan contoh.

Endless-Tunnel

Contoh Endless-Tunnel adalah game Android yang mengharuskan pemain mengumpulkan kubus putih saat mencoba mencapai akhir terowongan. Contoh ini telah ditransfer dari contoh OpenGL di repositori Android NDK di GitHub. Contoh ini tidak menyediakan game versi Windows.

Contoh ini sudah mengonfigurasi setelannya dan platform Android, sehingga Anda dapat membuat dan menjalankan project di Visual Studio tanpa modifikasi apa pun. Saat Anda membuka solusi, Solution Explorer akan menampilkan modul berikut:

• endless-tunnel: modul aplikasi yang menampilkan logika game.
• glm: snapshot repositori Matematika OpenGL yang dibuat sebagai library statis.
• native_app_glue: wrapper NDK yang berkomunikasi dengan objek NativeActivity.

Teapot

Contoh Teapot menampilkan teko klasik yang dirender dengan OpenGL ES dan ditransfer ke Android Game Development Extension untuk menunjukkan fitur berikut:

• Pengembangan project lintas platform: Anda dapat membuat contoh Teapot untuk Windows dan Android.
• Penggunaan paket Android kustom: skrip build Gradle dipindahkan ke direktori utama contoh, tempat file Teapot.sln berada.
• Konfigurasi Android kustom yang menunjukkan cara menggunakan Address Sanitizer (ASan) dan Hardware Address Sanitizer (HWASan).

Implementasi contoh Teapot dibagi menjadi beberapa bagian, yang umumnya untuk aplikasi dan game lintas platform berukuran besar:

• Modul GameApplication: menentukan tindakan pengguna dan status aplikasi, seperti pengguna memutar teko atau memperbarui statistik aplikasi.
• Modul GameEngine: mengimplementasikan modul rendering inti.

Untuk menyiapkan contoh dan menjalankannya di Android, lihat panduan memulai. Untuk menyiapkan contoh dan menjalankannya di Windows:

Tampilkan/Sembunyikan Petunjuk

1. Instal GLEW:
   1. Download dan ekstrak file GLEW.
   2. Salin file biner dari $your-glew-directory\bin\Release\x64 ke %SystemRoot%\system32.
2. Instal freeglut:
   1. Download dan ekstrak file freeglut.
   2. Salin $your-freeglut-directory\bin\x86\freeglut.dll ke %SystemRoot%\system32.
3. Tambahkan dependensi project freeglut:
   1. Buka Teapot.sln di Visual Studio.
   2. Di menu, klik Debug > x64 > Local Windows Debugger.
   3. Di Solution Explorer, klik kanan GameApplication, lalu pilih Properties > C/C++ > General > Additional Include Directories.
   4. Tambahkan $your-freeglut-dir\include ke jalur.
      
   5. Klik Ok.
   6. Pilih Linker > General > Additional Library Directories.
   7. Tambahkan $your-freeglut-dir\lib\x64 ke jalur.
   8. Klik Ok.
   9. Pilih Linker > General > Additional Library Directories.
   10. Tambahkan freeglut.lib ke jalur.
   11. Klik Ok.
4. Tambahkan dependensi project GLEW:
   1. Di panel Solution Explorer, klik kanan GameApplication, lalu pilih Properties > C/C++ > General > Additional Include Directories.
   2. Tambahkan $your-glew-dir\include ke jalur.
   3. Klik Ok.
   4. Pilih Linker > General > Additional Library Directories.
   5. Tambahkan $your-glew-dir\lib\Release\x86 ke jalur.
   6. Klik Ok.
   7. Pilih Linker > General > Additional Library Directories.
   8. Tambahkan glew32.lib ke jalur.
   9. Klik Ok.
5. Jalankan contoh di Windows:
   Catatan: Untuk meningkatkan waktu build, file sumber Android yang tidak dibagikan ke Windows akan dikecualikan saat Anda membuat contoh untuk Windows. Untuk mengecualikan file, gunakan perintah Exclude from Build dalam dialog Properties Pages untuk setiap file yang ingin dikecualikan dalam Solution Explorer.
   1. Di toolbar Visual Studio, klik tombol jalankan Local Windows Debugger.
   2. Contoh akan terlihat seperti berikut:
      

AssemblyCode-Link-Objects

Project ini adalah project template yang menunjukkan cara membuat library native Android dari assembly dan kode sumber C/C++. Berikut adalah komponen utamanya:

• AssemblyCode-Link-Objects: library native Android utama yang dibuat dari kode sumber assembly dan C++.
• StaticLib: library statis helper yang mengekspor fungsi from_static_lib_assembly_code_as.

Project ini mendukung beberapa arsitektur. Setiap arsitektur yang didukung memiliki file sumbernya sendiri yang mengimplementasikan fungsi yang diekspor dari StaticLib. Anda hanya boleh menyertakan file sumber assembly untuk platform yang sedang dibuat. Project ini menyertakan file assembly dalam build menggunakan alat build kustom.

Untuk menyiapkan dan membuat contoh:

Tampilkan/Sembunyikan Petunjuk

1. Di Visual Studio, pastikan alat build kustom dikonfigurasi untuk file assembly:
   1. Di Solution Explorer, klik kanan file assembly, lalu klik Properties. Tindakan ini akan membuka dialog Properties Pages untuk file tersebut.
   2. Pilih konfigurasi dan platform, seperti All configurations untuk Android-arm64-v8a.
   3. Pastikan General > Exclude from Build disetel ke No.
   4. Pastikan General > Item Type disetel ke Custom Build Tool.
   5. Klik Apply jika ada perubahan yang akan diterapkan.
   6. Pastikan Configuration Properties > Custom Build Tools > Command Line: disetel ke $(AsToolExe) -o "$(IntDir)%(FileName).o" %(FullPath). NDK menyertakan assembler terpisah untuk setiap arsitektur CPU dan $(AsToolExe) memetakan ke assembler yang tepat. Contoh ini menggunakan toolchain NDK untuk membuat project Android x86 dan x86_64. Jika Anda ingin menggunakan yasm untuk platform Android x86_64, gunakan $(YasmToolExe) sebagai gantinya.
   7. Pastikan Configuration Properties > Custom Build Tools > Outputs: disetel ke $(IntDir)%(FileName).o. String ini harus disertakan dalam setelan Command Line.
   8. Pastikan Configuration Properties > Custom Build Tools > Link Objects: disetel ke Yes.

   Misalnya, setelan Android-arm64-v8a akan terlihat seperti screenshot berikut:

   
2. Buat project. Tindakan ini akan mem-build file libAssmeblyCodeLinkObjects.so:
   1. Buka file AssemblyCode-Link-Objects.sln.
   2. Di menu, klik Build > Build Solution.
3. Untuk mengonfirmasi bahwa fungsi tersebut diekspor dengan benar ke library Android, gunakan alat NDK nm.exe:
   1. Pada command line, buka direktori contoh.
   2. Buka lokasi library Android yang dihasilkan oleh build Anda. Lokasi default mirip dengan $sample_dir\$solution_configuration\$solution_platform\$platform dan $sample_dir\Debug\Android-arm64-v8a\arm64-v8a untuk platform arm64-v8a.
   3. Pastikan bagian simbol yang diekspor berisi fungsi dengan menjalankan perintah berikut:

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

      Dalam output, Anda akan melihat daftar simbol yang menyertakan kode berikut:

         T from_shared_object_assembly_code_as
         T from_static_lib_assembly_code_as

PoolAllocator

Contoh PoolAllocator adalah aplikasi Android yang memiliki alokator memori berbasis kumpulan yang menyediakan blok berukuran tetap secara sangat efisien.

Alokator mengalokasikan seluruh memori terlebih dahulu pada waktu inisialisasi menggunakan mmap. Blok kosong dilacak menggunakan linked list. Kemudian, alokasi memori adalah operasi O(1) cepat yang menampilkan head linked list, dan dealokasi juga merupakan operasi O(1) karena menambahkan blok ke bagian belakang linked list.

Contoh ini memiliki dua konfigurasi solusi untuk menggunakan HWASan.

• HWASan: Konfigurasi ini menunjukkan pendekatan paling sederhana untuk menggunakan HWASan dengan alokator memori kustom. Implementasi internal allocator memori diganti dengan panggilan malloc/free yang otomatis dilacak oleh HWASan. Meskipun pengalokasi memori tidak lagi berfungsi sebagai pengalokasi berbasis kumpulan, HWASan masih dapat membantu Anda mengidentifikasi bug memori penting, seperti use-after-free.

• HWASan-Advanced: Konfigurasi ini menunjukkan cara mengintegrasikan HWASan sepenuhnya ke dalam alokator memori kustom tanpa mengubah mekanisme alokasi asli yang digunakan oleh alokator. Metode ini menggunakan metode pemberian tag HWASan untuk memberi tag pada blok memori dalam kumpulan yang dialokasikan sebelumnya, membulatkan ukuran blok hingga ukuran blok minimum yang diperlukan oleh HWASan, dan mereset tag saat blok dikembalikan kembali ke kumpulan.

Gunakan konfigurasi HWASan karena lebih sederhana dan dapat membantu Anda mengidentifikasi bug memori umum. Pelajari penerapan konfigurasi HWASan-Advanced jika Anda ingin memahami cara kerja HWASan atau ingin mempertahankan semantik internal alokator memori saat menggunakan HWASan.