Esempi

Gli esempi per l'estensione Android Game Development mostrano come utilizzare le funzionalità chiave dell'estensione. Questo argomento descrive i sample e le impostazioni necessarie per eseguirli.

I seguenti esempi sono disponibili nella pagina dei download:

• HelloJNI: un progetto introduttivo.
• Endless-Tunnel: un progetto solo per Android.
• Teapot: un progetto multipiattaforma per Windows e Android.
• AssemblyCode-Link-Objects: un progetto modello con codice sorgente assembly.

Prima di iniziare

• Installa l'estensione Android Game Development e i sample. Per maggiori dettagli, consulta la guida rapida. L'argomento descrive anche come compilare e eseguire un sample e utilizza la versione per Android dell'esempio Teiera come esempio.

• La guida alla configurazione del progetto descrive come configurare le impostazioni per un progetto che utilizza l'estensione, ad esempio l'aggiunta di una piattaforma Android e di un APK.

HelloJNI

L'esempio HelloJNI è un progetto semplice che mostra il messaggio "Un saluto da JNI" in una finestra dell'app. Il progetto utilizza un insieme diverso di codice sorgente per Windows e Android.

• Directory del codice sorgente Android e degli script di compilazione Gradle: HelloJNI\AndroidPackaging
• Codice sorgente di Windows e directory del progetto Visual Studio: HelloJNI

Quando compili il progetto, Visual Studio passa le seguenti impostazioni al file build.gradle a livello di app. Puoi modificare queste impostazioni modificando gli script di compilazione di Gradle.

• MSBUILD_NDK_VERSION
• MSBUILD_MIN_SDK_VERSION
• MSBUILD_JNI_LIBS_SRC_DIR
• MSBUILD_ANDROID_OUTPUT_APK_NAME
• MSBUILD_ANDROID_GRADLE_BUILD_OUTPUT_DIR

Per configurare ed eseguire il sample:

Mostra / Nascondi istruzioni

1. In Visual Studio, apri ed esegui la compilazione dell'esempio HelloJNI.
2. Aggiungi una piattaforma Android arm64-v8a. Per maggiori informazioni, consulta Aggiungere una piattaforma Android.
3. Aggiungi un elemento APK Android alla nuova piattaforma.
4. Compila il progetto.
5. Aggiungi le seguenti piattaforme Android e poi un elemento APK Android a ciascuna di esse: Android-armeabi-v7a, Android-x86 e Android-x86_64.
6. Crea ed esegui il Sample.

Endless-Tunnel

Il sample Endless-Tunnel è un gioco per Android in cui il giocatore raccoglie cubetti bianchi mentre cerca di raggiungere la fine di un tunnel. È stato trasferito da un campione OpenGL nel repository Android NDK su GitHub. Il sample non fornisce una versione per Windows del gioco.

Il progetto di esempio ha già le impostazioni e le piattaforme Android configurate, quindi puoi compilare ed eseguire il progetto in Visual Studio senza alcuna modifica. Quando apri la soluzione, Esploratore di soluzioni mostra i seguenti moduli:

• endless-tunnel: il modulo dell'applicazione che mostra la logica di gioco.
• glm: uno snapshot del repo OpenGL Math che viene compilato come libreria statica.
• native_app_glue: un wrapper NDK che comunica con l'oggetto NativeActivity.

Teiera

L'esempio Teiera mostra una teiera classica visualizzata con OpenGL ES e trasferita all'Estensione per lo sviluppo di giochi Android per dimostrare le seguenti funzionalità:

• Sviluppo di progetti multipiattaforma: puoi creare l'esempio Teapot per Windows e Android.
• Utilizzo del pacchettizzazione Android personalizzata: gli script di compilazione di Gradle sono stati spostati nella directory principale del sample, dove si trova il file Teapot.sln.
• Configurazioni Android personalizzate che mostrano come utilizzare Address Sanitizer (ASan) e Hardware Address Sanitizer (HWASan).

L'implementazione del Sample Teapot è suddivisa in più parti, come accade per le applicazioni e i giochi cross-platform di grandi dimensioni:

• Modulo GameApplication: definisce le azioni utente e gli stati dell'applicazione, ad esempio un utente che ruota la teiera o aggiorna le statistiche dell'applicazione.
• Modulo GameEngine: implementa il modulo di rendering principale.

Per configurare l'esempio ed eseguirlo su Android, consulta la guida rapida. Per configurare l'esempio ed eseguirlo su Windows:

Mostra / Nascondi istruzioni

1. Installa GLEW:
   1. Scarica e decomprimi GLEW.
   2. Copia i file binari da $your-glew-directory\bin\Release\x64 a %SystemRoot%\system32.
2. Installa freeglut:
   1. Scarica e decomprimi freeglut.
   2. Copia $your-freeglut-directory\bin\x86\freeglut.dll in %SystemRoot%\system32.
3. Aggiungi le dipendenze del progetto freeglut:
   1. Apri Teapot.sln in Visual Studio.
   2. Nel menu, fai clic su Debug > x64 > Debuggee Windows locale.
   3. In Esplora soluzioni, fai clic con il tasto destro del mouse su GameApplication e scegli Proprietà > C/C++ > Generale > Directory di inclusione aggiuntive.
   4. Aggiungi $your-freeglut-dir\include al percorso.
      
   5. Fai clic su OK.
   6. Scegli Linker > Generale > Directory delle librerie aggiuntive.
   7. Aggiungi $your-freeglut-dir\lib\x64 al percorso.
   8. Fai clic su OK.
   9. Scegli Linker > Generale > Directory delle librerie aggiuntive.
   10. Aggiungi freeglut.lib al percorso.
   11. Fai clic su OK.
4. Aggiungi le dipendenze del progetto GLEW:
   1. Nel riquadro Esploratore di soluzioni, fai clic con il tasto destro del mouse su GameApplication e scegli Proprietà > C/C++ > Generale > Directory di inclusione aggiuntive.
   2. Aggiungi $your-glew-dir\include al percorso.
   3. Fai clic su OK.
   4. Scegli Linker > Generale > Directory delle librerie aggiuntive.
   5. Aggiungi $your-glew-dir\lib\Release\x86 al percorso.
   6. Fai clic su OK.
   7. Scegli Linker > Generale > Directory delle librerie aggiuntive.
   8. Aggiungi glew32.lib al percorso.
   9. Fai clic su OK.
5. Esegui il sample su Windows:
   1. Nella barra degli strumenti di Visual Studio, fai clic sul pulsante di esecuzione Debuggee Windows locale.
   2. Il campione dovrebbe avere il seguente aspetto:
      

AssemblyCode-Link-Objects

Questo è un progetto modello che mostra come generare una biblioteca nativa Android dal codice sorgente assembly e C/C++. Di seguito sono riportati i componenti principali:

• AssemblyCode-Link-Objects: la libreria nativa Android principale creata da codice sorgente C++ e assembly.
• StaticLib: una libreria statica di supporto che esporta la funzione from_static_lib_assembly_code_as.

Il progetto supporta più architetture. Ogni architettura supportata ha i propri file di origine che implementano le funzioni esportate da StaticLib. Devi includere solo i file di origine dell'assembly per le piattaforme che stai compilando. Questo progetto include i file di assembly nelle build utilizzando strumenti di compilazione personalizzati.

Per configurare e compilare il sample:

Mostra / Nascondi istruzioni

1. In Visual Studio, verifica che gli strumenti di compilazione personalizzati siano configurati per i file di assembly:
   1. In Esplora soluzioni, fai clic con il tasto destro del mouse sul file dell'assembly e poi su Proprietà. Viene visualizzata la finestra di dialogo Pagine delle proprietà per il file.
   2. Seleziona la configurazione e la piattaforma, ad esempio Tutte le configurazioni per Android-arm64-v8a.
   3. Assicurati che l'opzione Generali > Escludi dalla compilazione sia impostata su No.
   4. Assicurati che Generale > Tipo di elemento sia impostato su Strumento di creazione personalizzata.
   5. Fai clic su Applica se ci sono modifiche da applicare.
   6. Assicurati che Proprietà di configurazione > Strumenti di compilazione personalizzati > Riga di comando: sia impostato su $(AsToolExe) -o "$(IntDir)%(FileName).o" %(FullPath). L'NDK include un assemblatore separato per ogni architettura della CPU e $(AsToolExe) viene mappato all'assemblatore corretto. Questo sample utilizza la toolchain NDK per compilare progetti Android sia x86 sia x86_64. Se vuoi utilizzare yasm per la piattaforma Android x86_64, utilizza invece $(YasmToolExe).
   7. Assicurati che Proprietà di configurazione > Strumenti di compilazione personalizzati > Uscite: sia impostato su $(IntDir)%(FileName).o. Questa stringa deve essere inclusa nell'impostazione Riga di comando.
   8. Assicurati che Proprietà di configurazione > Strumenti di compilazione personalizzati > Collega oggetti: sia impostato su Yes.

   Ad esempio, le impostazioni Android-arm64-v8a dovrebbero essere simili allo screenshot seguente:

   
2. Compila il progetto. Viene creato il file libAssmeblyCodeLinkObjects.so:
   1. Apri il file AssemblyCode-Link-Objects.sln.
   2. Nel menu, fai clic su Build > Build Solution.
3. Per verificare che le funzioni vengano esportate correttamente nella biblioteca Android, utilizza lo strumento NDK nm.exe:
   1. Nella riga di comando, vai alla directory di esempio.
   2. Vai alla posizione della libreria Android generata dalla compilation. La posizione predefinita è simile a $sample_dir\$solution_configuration\$solution_platform\$platform e $sample_dir\Debug\Android-arm64-v8a\arm64-v8a per la piattaforma arm64-v8a.
   3. Verifica che la sezione dei simboli esportati contenga le funzioni eseguendo il seguente comando:

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

      Nell'output dovresti vedere un elenco di simboli che include quanto segue:

         T from_shared_object_assembly_code_as
         T from_static_lib_assembly_code_as

PoolAllocator

L'esempio PoolAllocator è un'app per Android che dispone di un allocatore di memoria basato su pool che fornisce blocchi di dimensioni fisse in modo molto efficiente.

L'allocatore prealloca l'intera memoria al momento dell'inizializzazione utilizzando mmap. I blocchi liberi vengono monitorati utilizzando una lista con link. Inoltre, un'allocazione di memoria è un'operazione O(1) rapida che restituisce l'elemento iniziale della lista connessa e anche la deallocazione è un'operazione O(1) perché aggiunge il blocco alla fine della lista connessa.

Il sample ha due configurazioni di soluzioni per l'utilizzo di HWASan.

• HWASan: questa configurazione mostra l'approccio più semplice per utilizzare HWASan con allocatori di memoria personalizzati. L'implementazione interna dell'allocatore di memoria viene sostituita con chiamate malloc/free che vengono monitorate automaticamente da HWASan. Sebbene l'allocatore di memoria non funzioni più come allocatore basato su pool, HWASan può comunque aiutarti a identificare bug di memoria importanti, come use-after-free.

• HWASan-Advanced: questa configurazione mostra come integrare completamente HWASan in un allocatore di memoria personalizzato senza modificare il meccanismo di allocazione originale utilizzato dall'allocatore. Utilizza i metodi di tagging HWASan per taggare i blocchi di memoria nel pool preallocato, arrotonda la dimensione del blocco a una dimensione minima del blocco richiesta da HWASan e reimposta i tag quando i blocchi vengono restituiti al pool.

Utilizza la configurazione HWASan perché è più semplice e può aiutarti a identificare i bug di memoria comuni. Esplora l'implementazione della configurazione HWASan-Advanced se vuoi capire come funziona HWASan o se vuoi preservare la semantica interna dell'allocatore di memoria durante l'utilizzo di HWASan.