Örnekler

Android Game Development Extension örnekleri, uzantının temel özelliklerinin nasıl kullanılacağını gösterir. Bu konuda, örnekler ve bunların çalıştırılması için gereken ayarlar açıklanmaktadır.

Aşağıdaki örnekler indirme sayfasında mevcuttur:

• HelloJNI: Giriş niteliğinde bir projedir.
• Endless-Tunnel: Yalnızca Android için bir projedir.
• Teapot: Windows ve Android için platformlar arası bir projedir.
• AssemblyCode-Link-Objects: derleme kaynak kodu içeren bir şablon projesi.

Başlamadan önce

• Android Game Development Extension'ı ve örnekleri yükleyin. Ayrıntılar için hızlı başlangıç kılavuzuna bakın. Bu konuda, örnek oluşturma ve çalıştırma da açıklanmaktadır. Örnek olarak Çaydanlık örneğinin Android sürümü kullanılmaktadır.

• Proje yapılandırma kılavuzunda, uzantıyı kullanan bir projenin ayarlarının nasıl yapılandırılacağı (ör. Android platformu ve APK ekleme) açıklanmaktadır.

MerhabaJNI

HelloJNI örneği, bir uygulama penceresinde "JNI'den Merhaba" mesajını gösteren basit bir projedir. Proje, Windows ve Android için farklı bir kaynak kodu grubu kullanır.

• Android kaynak kodu ve Gradle derleme komut dosyası dizini: HelloJNI\AndroidPackaging
• Windows kaynak kodu ve Visual Studio proje dizini: HelloJNI

Projeyi derlediğinizde Visual Studio aşağıdaki ayarları uygulama düzeyindeki build.gradle dosyasına iletir. Gradle derleme komut dosyalarınızı değiştirerek bu ayarları değiştirebilirsiniz.

• MSBUILD_NDK_VERSION
• MSBUILD_MIN_SDK_VERSION
• MSBUILD_JNI_LIBS_SRC_DIR
• MSBUILD_ANDROID_OUTPUT_APK_NAME
• MSBUILD_ANDROID_GRADLE_BUILD_OUTPUT_DIR

Sana Özel özelliğini ayarlamak ve çalıştırmak için:

Talimatları Göster / Gizle

1. Visual Studio'da HelloJNI örneğini açıp derleyin.
2. Android arm64-v8a platformu ekleyin. Daha fazla bilgi için Android platformu ekleme başlıklı makaleyi inceleyin.
3. Yeni platforma Android APK öğesi ekleyin.
4. Projeyi derleyin.
5. Aşağıdaki Android platformlarını ekleyin ve ardından her birine bir Android APK öğesi ekleyin: Android-armeabi-v7a, Android-x86 ve Android-x86_64.
6. Örneği derleyip çalıştırın.

Endless-Tunnel

Endless-Tunnel örneği, oyuncunun bir tünelin sonuna ulaşmaya çalışırken beyaz küpler topladığı bir Android oyunudur. Bu örnek, GitHub'daki Android NDK deposundaki bir OpenGL örneğinden aktarılmıştır. Örnekte oyunun Windows sürümü sağlanmıyor.

Örnekte ayarları ve Android platformları zaten yapılandırılmış olduğundan, projeyi herhangi bir değişiklik yapmadan Visual Studio'da derleyip çalıştırabilirsiniz. Çözümü açtığınızda Çözüm Gezgini aşağıdaki modülleri gösterir:

• endless-tunnel: Oyun mantığını gösteren uygulama modülü.
• glm: Statik kitaplık olarak oluşturulan OpenGL Math deposunun anlık görüntüsü.
• native_app_glue: NativeActivity nesnesi ile iletişim kuran bir NDK sarmalayıcısı.

Demlik

Çaydanlık örneğinde, OpenGL ES ile oluşturulan ve aşağıdaki özellikleri göstermek için Android Game Development Extension'a aktarılan klasik bir çaydanlık gösterilmektedir:

• Platformlar arası proje geliştirme: Çaydanlık örneğini Windows ve Android için derleyebilirsiniz.
• Özel Android paketleme kullanımı: Gradle derleme komut dosyaları, Teapot.sln dosyasının bulunduğu örneğin kök dizine taşındı.
• Address Sanitizer (ASan) ve Hardware Address Sanitizer (HWASan) özelliklerinin nasıl kullanılacağını gösteren özel Android yapılandırmaları.

Çaydanlık örneğinin uygulanması, büyük platformlar arası uygulamalar ve oyunlar için tipik olan birden fazla bölüme ayrılmıştır:

• GameApplication modülü: Kullanıcı işlemlerini ve uygulama durumlarını (ör. kullanıcının çaydanlığı döndürmesi veya uygulama istatistiklerini güncellemesi) tanımlar.
• GameEngine modülü: Temel oluşturma modülünü uygular.

Örneği ayarlamak ve Android'de çalıştırmak için hızlı başlangıç bölümüne bakın. Örneği ayarlamak ve Windows'da çalıştırmak için:

Talimatları Göster / Gizle

1. GLEW'yi yükleme:
   1. GLEW'yi indirip sıkıştırmasını açın.
   2. İkili dosyaları $your-glew-directory\bin\Release\x64'ten %SystemRoot%\system32'a kopyalayın.
2. freeglut'ü yükleyin:
   1. freeglut'u indirip arşivden çıkarın.
   2. $your-freeglut-directory\bin\x86\freeglut.dll dosyasını %SystemRoot%\system32 klasörüne kopyalayın.
3. freeglut proje bağımlılıkları ekleyin:
   1. Visual Studio'da Teapot.sln dosyasını açın.
   2. Menüden Hata ayıklama > x64 > Yerel Windows Hata Ayıklama Aracı'nı tıklayın.
   3. Çözüm Gezgini'nde GameApplication'ı sağ tıklayın ve Özellikler > C/C++ > Genel > Ek Dahil Dizinleri'ni seçin.
   4. $your-freeglut-dir\include dosyasını yola ekleyin.
      
   5. Tamam'ı tıklayın.
   6. Bağlayıcı > Genel > Ek Kitaplık Dizinleri'ni seçin.
   7. $your-freeglut-dir\lib\x64 dosyasını yola ekleyin.
   8. Tamam'ı tıklayın.
   9. Bağlayıcı > Genel > Ek Kitaplık Dizinleri'ni seçin.
   10. freeglut.lib dosyasını yola ekleyin.
   11. Tamam'ı tıklayın.
4. GLEW proje bağımlılıkları ekleyin:
   1. Çözüm Gezgini bölmesinde GameApplication'ı sağ tıklayın ve Özellikler > C/C++ > Genel > Ek Dahil Dizinleri'ni seçin.
   2. $your-glew-dir\include dosyasını yola ekleyin.
   3. Tamam'ı tıklayın.
   4. Bağlayıcı > Genel > Ek Kitaplık Dizinleri'ni seçin.
   5. $your-glew-dir\lib\Release\x86 dosyasını yola ekleyin.
   6. Tamam'ı tıklayın.
   7. Bağlayıcı > Genel > Ek Kitaplık Dizinleri'ni seçin.
   8. glew32.lib dosyasını yola ekleyin.
   9. Tamam'ı tıklayın.
5. Örneği Windows'ta çalıştırma:
   Not: Derleme sürelerini iyileştirmek için, Windows ile paylaşılmayan Android kaynak dosyaları, örneği Windows için derlediğinizde hariç tutulmalıdır. Dosyaları hariç tutmak için Çözüm Gezgini'nde hariç tutmak istediğiniz her dosya için Özellikler Sayfaları iletişim kutusunda Derlemeden Hariç Tut komutunu kullanın.
   1. Visual Studio araç çubuğunda Yerel Windows Hata Ayıklama Aracı çalıştırma düğmesini tıklayın.
   2. Örnek şu şekilde görünmelidir:
      

AssemblyCode-Link-Objects

Bu, assembly ve C/C++ kaynak kodundan Android yerel kitaplığının nasıl oluşturulacağını gösteren bir şablon projedir. Temel bileşenler şunlardır:

• AssemblyCode-Link-Objects: C++ ve assembly kaynak kodundan oluşturulan ana Android yerel kitaplığı.
• StaticLib: from_static_lib_assembly_code_as işlevini dışa aktaran yardımcı statik kitaplık.

Proje birden fazla mimariyi destekler. Desteklenen her mimarinin, StaticLib'ten dışa aktarılan işlevleri uygulayan kendi kaynak dosyaları vardır. Yalnızca derlediğiniz platformların derleme kaynak dosyalarını eklemeniz gerekir. Bu proje, özel derleme araçları kullanarak derlemelere montaj dosyaları ekler.

Örneği ayarlamak ve oluşturmak için:

Talimatları Göster / Gizle

1. Visual Studio'da, özel derleme araçlarının derleme dosyaları için yapılandırıldığından emin olun:
   1. Çözüm Gezgini'nde derleme dosyasını sağ tıklayıp Özellikler'i tıklayın. Bu işlem, dosyanın Özellikler Sayfaları iletişim kutusunu açar.
   2. Yapılandırmayı ve platformu seçin (ör. Android-arm64-v8a için Tüm yapılandırmalar).
   3. Genel > Derlemeden hariç tut ayarının Hayır olarak ayarlandığından emin olun.
   4. Genel > Öğe Türü'nün Özel Derleme Aracı olarak ayarlandığından emin olun.
   5. Uygulanacak değişiklikler varsa Uygula'yı tıklayın.
   6. Yapılandırma Özellikleri > Özel Derleme Araçları > Komut Satırı'nın $(AsToolExe) -o "$(IntDir)%(FileName).o" %(FullPath) olarak ayarlandığından emin olun. NDK, her CPU mimarisi için ayrı bir derleyici içerir ve $(AsToolExe) doğru derleyiciyle eşlenir. Bu örnekte, hem x86 hem de x86_64 Android projeleri oluşturmak için NDK araç zinciri kullanılır. x86_64 Android platformu için yasm kullanmak istiyorsanız bunun yerine $(YasmToolExe) kullanın.
   7. Yapılandırma Özellikleri > Özel Derleme Araçları > Çıkışlar'ın $(IntDir)%(FileName).o olarak ayarlandığından emin olun. Bu dize, Komut Satırı ayarına eklenmelidir.
   8. Yapılandırma Özellikleri > Özel Derleme Araçları > Nesneleri Bağla'nın Yes olarak ayarlandığından emin olun.

   Örneğin, Android-arm64-v8a ayarları aşağıdaki ekran görüntüsüne benzer şekilde görünmelidir:

   
2. Projeyi oluşturun. Bu işlem, şu libAssmeblyCodeLinkObjects.so dosyasını oluşturur:
   1. AssemblyCode-Link-Objects.sln dosyasını açın.
   2. Menüden Derle > Çözüm Derle'yi tıklayın.
3. İşlevlerin Android kitaplığına doğru şekilde aktarıldığını doğrulamak için nm.exe NDK aracını kullanın:
   1. Komut satırında örnek dizine gidin.
   2. Derlemeniz tarafından oluşturulan Android kitaplığı konumuna gidin. Varsayılan konum, arm64-v8a platformu için $sample_dir\$solution_configuration\$solution_platform\$platform ve $sample_dir\Debug\Android-arm64-v8a\arm64-v8a ile benzerdir.
   3. Aşağıdaki komutu çalıştırarak dışa aktarılan simge bölümünün işlevleri içerdiğini doğrulayın:

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

      Çıktıda, aşağıdakileri içeren sembollerin bir listesini görürsünüz:

         T from_shared_object_assembly_code_as
         T from_static_lib_assembly_code_as

PoolAllocator

PoolAllocator örneği, sabit boyutlu blokları çok verimli bir şekilde sağlayan havuz tabanlı bir bellek ayırıcıya sahip bir Android uygulamasıdır.

Ayıraç, belleğin tamamını başlatma sırasında mmap kullanarak önceden ayırır. Ücretsiz bloklar, bağlı liste kullanılarak izlenir. Ardından, bellek ayırma, bağlı listenin başını döndüren hızlı bir O(1) işlemidir ve ayırma işlemi de bloğu bağlı listenin arkasına eklediği için O(1) işlemidir.

Örnekte, HWASan'ı kullanmaya yönelik iki çözüm yapılandırması vardır.

• HWASan: Bu yapılandırma, özel bellek ayırıcılarla HWASan'ı kullanmanın en basit yaklaşımını gösterir. Bellek ayırıcının dahili uygulaması, HWASan tarafından otomatik olarak izlenen malloc/free çağrılarıyla değiştirilir. Bellek ayırıcı artık havuz tabanlı bir ayırıcı olarak çalışmasa da HWASan, boşaltıldıktan sonra kullanım gibi önemli bellek hatalarını tespit etmenize yardımcı olmaya devam edebilir.

• HWASan-Advanced: Bu yapılandırma, ayırıcı tarafından kullanılan orijinal ayırma mekanizmasını değiştirmeden HWASan'ın özel bir bellek ayırıcıya nasıl tam olarak entegre edileceğini gösterir. Önceden ayrılmış havuzdaki bellek bloklarını etiketlemek için HWASan etiketleme yöntemlerini kullanır, blok boyutunu HWASan tarafından istenen minimum blok boyutuna yuvarlar ve bloklar havuza geri döndürüldüğünde etiketleri sıfırlar.

Daha basit olduğu ve yaygın bellek hatalarını tespit etmenize yardımcı olabileceği için HWASan yapılandırmasını kullanın. HWASan'ın nasıl çalıştığını anlamak veya HWASan'ı kullanırken bellek ayırıcınızın iç anlamlarını korumak istiyorsanız HWASan-Advanced yapılandırmasının uygulanmasını inceleyin.