Örnekler

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

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

  • HelloJNI: Giriş projesi.
  • Endless-Tunnel: Yalnızca Android'e yönelik bir proje.
  • Teapot: Windows ve Android için platformlar arası bir proje.
  • AssemblyCode-Link-Objects: Assembly 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 ayrıca, bir örneğin nasıl derlenip çalıştırılacağı açıklanmakta ve örnek olarak Teapot örneğinin Android sürümü kullanılmaktadır.

  • Proje yapılandırması 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.

HelloJNI

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

  • Android kaynak kodu ve Gradle derleme komut dosyaları 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

Örneği ayarlamak ve çalıştırmak için:

  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 derleyin ve çalıştırın.

Endless-Tunnel

Endless-Tunnel örneği, oyuncunun bir tünelin sonuna ulaşmaya çalışırken beyaz küpleri topladığı bir Android oyunudur. Bu örnek, GitHub'daki Android NDK deposunda bulunan bir OpenGL örneğinden taşınmıştır. Örnekte oyunun Windows sürümü yoktur.

Örnekte ayarlar ve Android platformları zaten yapılandırılmış olduğundan projeyi Visual Studio'da herhangi bir değişiklik yapmadan derleyip çalıştırabilirsiniz. Çözümü açtığınızda Çözüm Gezgini şu 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 nesnesiyle iletişim kuran bir NDK sarmalayıcısı.

Demlik

Teapot örneği, OpenGL ES ile oluşturulmuş ve aşağıdaki özellikleri göstermek için Android Game Development Extension'a taşınmış klasik bir çaydanlığı gösterir:

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

Teapot örneğinin uygulanması birden fazla bölüme ayrılmıştır. Bu, büyük platformlar arası uygulamalar ve oyunlar için tipik bir durumdur:

  • GameApplication modülü: Kullanıcının çaydanlığı döndürmesi veya uygulama istatistiklerini güncellemesi gibi kullanıcı işlemlerini ve uygulama durumlarını 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:

  1. GLEW'i yükleyin:
    1. GLEW'u indirip ayıklayın.
    2. İkili program dosyalarını $your-glew-directory\bin\Release\x64 konumundan %SystemRoot%\system32 konumuna kopyalayın.
  2. freeglut'u yükleyin:
    1. freeglut'ı indirip ayıklayın.
    2. $your-freeglut-directory\bin\x86\freeglut.dll öğesini %SystemRoot%\system32 klasörüne kopyalayın.
  3. freeglut proje bağımlılıklarını ekleyin:
    1. Teapot.sln dosyasını Visual Studio'da açın.
    2. Menüde Debug > x64 > Local Windows Debugger'ı (Hata Ayıkla > x64 > Yerel Windows Hata Ayıklayıcısı) tıklayın.
    3. Solution Explorer'da (Çözüm Gezgini) GameApplication'ı sağ tıklayıp Properties > C/C++ > General > Additional Include Directories'ı (Özellikler > C/C++ > Genel > Ek Dahil Edilen Dizinler) seçin.
    4. Yola $your-freeglut-dir\include ekleyin.
      Visual Studio Ek Dahil Edilen Dizinler özellik sayfası iletişim kutusu.
    5. Ok'i (Tamam) tıklayın.
    6. Bağlayıcı > Genel > Ek Kitaplık Dizinleri'ni seçin.
    7. Yola $your-freeglut-dir\lib\x64 ekleyin. Visual Studio Ek Kitaplık Dizinleri özellik sayfası iletişim kutusu.
    8. Ok'i (Tamam) tıklayın.
    9. Bağlayıcı > Genel > Ek Kitaplık Dizinleri'ni seçin.
    10. Yola freeglut.lib ekleyin.
    11. Ok'i (Tamam) tıklayın.
  4. GLEW proje bağımlılıklarını ekleyin:
    1. Solution Explorer (Çözüm Gezgini) bölmesinde GameApplication'ı sağ tıklayın ve Properties > C/C++ > General > Additional Include Directories'ı (Özellikler > C/C++ > Genel > Ek Dahil Edilen Dizinler) seçin.
    2. Yola $your-glew-dir\include ekleyin.
    3. Ok'i (Tamam) tıklayın.
    4. Bağlayıcı > Genel > Ek Kitaplık Dizinleri'ni seçin.
    5. Yola $your-glew-dir\lib\Release\x86 ekleyin.
    6. Ok'i (Tamam) tıklayın.
    7. Bağlayıcı > Genel > Ek Kitaplık Dizinleri'ni seçin.
    8. Yola glew32.lib ekleyin.
    9. Ok'i (Tamam) tıklayın.
  5. Örneği Windows'da çalıştırın:
    1. Visual Studio araç çubuğunda Local Windows Debugger (Yerel Windows Hata Ayıklayıcısı) çalıştırma düğmesini tıklayın.
    2. Örnek aşağıdaki gibi görünmelidir:
      Windows penceresinde çalışan Teapot örnek uygulaması.

Bu, assembly ve C/C++ kaynak kodundan Android yerel kitaplığının nasıl oluşturulacağını gösteren bir şablon projedir. Ana 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ı bir 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 için assembly kaynak dosyalarını eklemeniz gerekir. Bu proje, özel derleme araçlarını kullanarak derlemelere assembly dosyaları ekler.

Örneği ayarlamak ve derlemek için:

  1. Visual Studio'da, derleme dosyaları için özel derleme araçlarının yapılandırıldığını doğrulayın:
    1. Solution Explorer'da (Çözüm Gezgini) derleme dosyasını sağ tıklayın ve Properties'i (Özellikler) tıklayın. Bu işlem, dosyanın Özellik 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 belirlendiğinden 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. Configuration Properties > Custom Build Tools > Command Line (Yapılandırma Özellikleri > Özel Derleme Araçları > Komut Satırı) ayarının $(AsToolExe) -o "$(IntDir)%(FileName).o" %(FullPath) olarak ayarlandığından emin olun. NDK, her CPU mimarisi için ayrı bir çevirici içerir ve $(AsToolExe) doğru çeviriciyle eşleşir. Bu örnekte, hem x86 hem de x86_64 Android projelerini derlemek için NDK araç zinciri kullanılır. x86_64 Android platformu için yasm kullanmak istiyorsanız bunun yerine $(YasmToolExe) kullanın.
    7. Configuration Properties > Custom Build Tools > Outputs (Yapılandırma Özellikleri > Özel Derleme Araçları > Çıkışlar) ayarının $(IntDir)%(FileName).o olarak ayarlandığından emin olun. Bu dize, Komut Satırı ayarına dahil edilmelidir.
    8. Configuration Properties > Custom Build Tools > Link Objects (Yapılandırma Özellikleri > Özel Derleme Araçları > Nesneleri Bağla) ayarı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:

    Özel Derleme Araçları için Visual Studio Özellik Sayfaları iletişim kutusu.
  2. Projeyi derleyin. Bu işlem, libAssmeblyCodeLinkObjects.so dosyasını oluşturur:
    1. AssemblyCode-Link-Objects.sln dosyasını açın.
    2. Menüde Build > Build Solution'ı (Derle > Çözümü Derle) tıklayın.
  3. İşlevlerin Android kitaplığına doğru şekilde aktarıldığını onaylamak 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 sembol 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

      Çıkışta, aşağıdakileri içeren bir simge listesi 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, havuza dayalı bir bellek ayırıcıya sahip bir Android uygulamasıdır.

Ayırıcı, başlatma sırasında mmap kullanarak tüm belleği önceden ayırır. Boş bloklar, bağlı bir liste kullanılarak izlenir. Bu durumda, bellek ayırma işlemi, bağlı listenin başını döndüren hızlı bir O(1) işlemidir. Bellek ayırmayı kaldırma işlemi de bloğu bağlı listenin sonuna eklediği için O(1) işlemidir.

Örnekte, HWASan'ı kullanmak için iki çözüm yapılandırması vardır.

  • HWASan: Bu yapılandırma, HWASan'ı özel bellek ayırmayla 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ı olabilir.

  • 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 için gereken 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ı belirlemenize yardımcı olabileceği için HWASan yapılandırmasını kullanın. HWASan'ın işleyiş şeklini anlamak veya HWASan'ı kullanırken bellek ayırıcınızın dahili semantiğini korumak istiyorsanız HWASan-Advanced yapılandırmasının uygulanmasını inceleyin.