Die Beispiele für die Android Game Development Extension zeigen, wie Sie die wichtigsten Funktionen der Erweiterung verwenden. In diesem Dokument werden die Beispiele und die Einstellungen beschrieben, die für die Ausführung erforderlich sind.
Die folgenden Beispiele sind auf der Downloadseite verfügbar:
- HelloJNI: ein Einführungsprojekt.
- Endless-Tunnel: ein reines Android-Projekt.
- Teapot: ein plattformübergreifendes Projekt für Windows und Android.
- AssemblyCode-Link-Objects: Ein Vorlagenprojekt mit Assembly-Quellcode.
Vorbereitung
Installieren Sie die Android Game Development Extension und die Beispiele. Einzelheiten finden Sie in dieser Kurzanleitung. Außerdem wird beschrieben, wie Sie ein Beispiel erstellen und ausführen. Als Beispiel wird die Android-Version des Teapot-Beispiels verwendet.
Im Leitfaden zur Projektkonfiguration wird beschrieben, wie Sie Einstellungen für ein Projekt konfigurieren, in dem die Erweiterung verwendet wird, z. B. wie Sie eine Android-Plattform und ein APK hinzufügen.
HelloJNI
Das HelloJNI-Beispiel ist ein Projekt, das in einem App-Fenster die Nachricht „Hello From JNI“ anzeigt. Das Projekt verwendet für Windows und Android unterschiedlichen Quellcode.
- Verzeichnis für Android-Quellcode und Gradle-Build-Skripts: HelloJNI\AndroidPackaging
- Windows-Quellcode und Visual Studio-Projektverzeichnis: HelloJNI
Wenn Sie das Projekt erstellen, übergibt Visual Studio die folgenden Einstellungen an die Datei build.gradle auf Anwendungsebene. Sie können diese Einstellungen ändern, indem Sie Ihre Gradle-Build-Skripts ändern.
MSBUILD_NDK_VERSIONMSBUILD_MIN_SDK_VERSIONMSBUILD_JNI_LIBS_SRC_DIRMSBUILD_ANDROID_OUTPUT_APK_NAMEMSBUILD_ANDROID_GRADLE_BUILD_OUTPUT_DIR
So richten Sie das Beispiel ein und führen es aus:
- Öffnen und erstellen Sie in Visual Studio das HelloJNI-Beispiel.
- Fügen Sie die Plattform Android arm64-v8a hinzu. Weitere Informationen finden Sie unter Android-Plattform hinzufügen.
- Fügen Sie der neuen Plattform ein Android-APK-Element hinzu.
- Kompilieren Sie das Projekt.
- Fügen Sie die folgenden Android-Plattformen hinzu und fügen Sie dann jeder ein Android-APK-Element hinzu: Android-armeabi-v7a, Android-x86 und Android-x86_64.
- Erstellen Sie das Beispiel und führen Sie es aus.
Endless-Tunnel
Das Beispiel „Endless-Tunnel“ ist ein Android-Spiel, bei dem der Spieler weiße Würfel sammelt und versucht, das Ende eines Tunnels zu erreichen. Sie wurde aus einem OpenGL-Beispiel im Android NDK-Repository auf GitHub portiert. Das Beispiel enthält keine Windows-Version des Spiels.
Die Einstellungen und Android-Plattformen sind im Beispiel bereits konfiguriert. Sie können das Projekt also ohne Änderungen in Visual Studio erstellen und ausführen. Wenn Sie die Lösung öffnen, werden im Solution Explorer die folgenden Module angezeigt:
- endless-tunnel: das Anwendungsmodul, das die Spiellogik anzeigt.
- glm: ein Snapshot des OpenGL Math-Repositorys, das als statische Bibliothek erstellt wird.
- native_app_glue: ein NDK-Wrapper, der mit dem
NativeActivity-Objekt kommuniziert.
Teekanne
Das Teapot-Beispiel zeigt eine klassische Teekanne, die mit OpenGL ES gerendert und auf die Android Game Development Extension portiert wurde, um die folgenden Funktionen zu demonstrieren:
- Plattformübergreifende Projektentwicklung: Sie können das Teapot-Beispiel für Windows und Android erstellen.
- Benutzerdefinierte Android-Paketnutzung: Die Gradle-Build-Skripts wurden in das Stammverzeichnis des Beispiels verschoben, in dem sich die Datei
Teapot.slnbefindet. - Benutzerdefinierte Android-Konfigurationen, die zeigen, wie Address Sanitizer (ASan) und Hardware Address Sanitizer (HWASan) verwendet werden.
Die Implementierung des Teapot-Beispiels ist in mehrere Teile aufgeteilt, was für große plattformübergreifende Anwendungen und Spiele typisch ist:
GameApplication-Modul: Definiert Nutzeraktionen und Anwendungsstatus, z. B. das Drehen der Teekanne durch einen Nutzer oder das Aktualisieren von Anwendungsstatistiken.GameEngine-Modul: Implementiert das Kernmodul für das Rendering.
Informationen zum Einrichten des Beispiels und zum Ausführen auf Android-Geräten finden Sie in der Kurzanleitung. So richten Sie das Beispiel ein und führen es unter Windows aus:
- Installieren Sie GLEW:
- Laden Sie GLEW herunter und extrahieren Sie es.
- Kopieren Sie die Binärdateien von
$your-glew-directory\bin\Release\x64nach%SystemRoot%\system32.
- Installieren Sie freeglut:
- Laden Sie freeglut herunter und extrahieren Sie es.
- Kopieren Sie
$your-freeglut-directory\bin\x86\freeglut.dllnach%SystemRoot%\system32.
- Fügen Sie die freeglut-Projektabhängigkeiten hinzu:
- Öffnen Sie
Teapot.slnin Visual Studio. - Klicken Sie im Menü auf Debug > x64 > Lokaler Windows-Debugger.
- Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf GameApplication und wählen Sie Eigenschaften > C/C++ > Allgemein > Zusätzliche Includeverzeichnisse aus.
- Fügen Sie
$your-freeglut-dir\includezum Pfad hinzu.
- Klicken Sie auf OK.
- Wählen Sie Linker > Allgemein > Zusätzliche Bibliotheksverzeichnisse aus.
- Fügen Sie
$your-freeglut-dir\lib\x64zum Pfad hinzu.
- Klicken Sie auf OK.
- Wählen Sie Linker > Allgemein > Zusätzliche Bibliotheksverzeichnisse aus.
- Fügen Sie
freeglut.libzum Pfad hinzu. - Klicken Sie auf OK.
- Öffnen Sie
- Fügen Sie die GLEW-Projektabhängigkeiten hinzu:
- Klicken Sie im Bereich Projektmappen-Explorer mit der rechten Maustaste auf GameApplication und wählen Sie Eigenschaften > C/C++ > Allgemein > Zusätzliche Includeverzeichnisse aus.
- Fügen Sie
$your-glew-dir\includezum Pfad hinzu. - Klicken Sie auf OK.
- Wählen Sie Linker > Allgemein > Zusätzliche Bibliotheksverzeichnisse aus.
- Fügen Sie
$your-glew-dir\lib\Release\x86zum Pfad hinzu. - Klicken Sie auf OK.
- Wählen Sie Linker > Allgemein > Zusätzliche Bibliotheksverzeichnisse aus.
- Fügen Sie
glew32.libzum Pfad hinzu. - Klicken Sie auf OK.
- Beispiel unter Windows ausführen:
- Klicken Sie in der Visual Studio-Symbolleiste auf die Schaltfläche Lokaler Windows-Debugger.
- Das Beispiel sollte so aussehen:
AssemblyCode-Link-Objects
Dies ist ein Vorlagenprojekt, das zeigt, wie eine native Android-Bibliothek aus Assembly- und C/C++-Quellcode generiert wird. Dies sind die Hauptkomponenten:
AssemblyCode-Link-Objects: die native Android-Hauptbibliothek, die aus C++- und Assembly-Quellcode erstellt wurde.StaticLib: eine statische Hilfsbibliothek, die die Funktionfrom_static_lib_assembly_code_asexportiert.
Das Projekt unterstützt mehrere Architekturen. Jede unterstützte Architektur hat eigene Quelldateien, die Funktionen implementieren, die aus StaticLib exportiert werden.
Sie sollten nur die Assembly-Quelldateien für die Plattformen einfügen, für die Sie erstellen. Dieses Projekt enthält Assembly-Dateien in Builds, die benutzerdefinierte Build-Tools verwenden.
So richten Sie das Beispiel ein und erstellen es:
- Prüfen Sie in Visual Studio, ob benutzerdefinierte Build-Tools für die Assembly-Dateien konfiguriert sind:
- Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf die Assembly-Datei und dann auf Eigenschaften. Dadurch wird das Dialogfeld Eigenschaftenseiten für die Datei geöffnet.
- Wählen Sie die Konfiguration und die Plattform aus, z. B. Alle Konfigurationen für Android-arm64-v8a.
- Achten Sie darauf, dass Allgemein > Vom Build ausschließen auf Nein festgelegt ist.
- Achten Sie darauf, dass Allgemein > Elementtyp auf Benutzerdefiniertes Build-Tool festgelegt ist.
- Klicken Sie auf Übernehmen, wenn Änderungen übernommen werden sollen.
- Achten Sie darauf, dass Konfigurationseigenschaften > Benutzerdefinierte Build-Tools > Befehlszeile auf
$(AsToolExe) -o "$(IntDir)%(FileName).o" %(FullPath)festgelegt ist. Das NDK enthält einen separaten Assembler für jede CPU-Architektur und$(AsToolExe)wird dem richtigen Assembler zugeordnet. In diesem Beispiel wird die NDK-Toolchain verwendet, um sowohl x86- als auch x86_64-Android-Projekte zu erstellen. Wenn Sie yasm für die x86_64-Android-Plattform verwenden möchten, verwenden Sie stattdessen$(YasmToolExe). - Achten Sie darauf, dass Konfigurationseigenschaften > Benutzerdefinierte Build-Tools > Ausgaben auf
$(IntDir)%(FileName).ofestgelegt ist. Dieser String muss in der Einstellung Befehlszeile enthalten sein. - Achten Sie darauf, dass Konfigurationseigenschaften > Benutzerdefinierte Build-Tools > Objekte verknüpfen auf
Yesfestgelegt ist.
Die Einstellungen für Android-arm64-v8a sollten beispielsweise in etwa wie im folgenden Screenshot aussehen:
- Erstellen Sie das Projekt: Dadurch wird die Datei
libAssmeblyCodeLinkObjects.soerstellt:- Öffnen Sie die Datei
AssemblyCode-Link-Objects.sln. - Klicken Sie im Menü auf Erstellen > Lösung erstellen.
- Öffnen Sie die Datei
- Mit dem NDK-Tool „nm.exe“ können Sie prüfen, ob die Funktionen korrekt in die Android-Bibliothek exportiert wurden:
- Rufen Sie in der Befehlszeile das Beispielverzeichnis auf.
- Rufen Sie den Speicherort der Android-Bibliothek auf, die durch Ihren Build generiert wurde. Der Standardspeicherort ist ähnlich wie
$sample_dir\$solution_configuration\$solution_platform\$platformund$sample_dir\Debug\Android-arm64-v8a\arm64-v8afür die Plattform arm64-v8a. - Prüfen Sie mit dem folgenden Befehl, ob der Abschnitt mit den exportierten Symbolen die Funktionen enthält:
…\ndk\toolschains\llvm\prebuilt\windows-x86_64\aarch64-linux-android\bin\nm.exe --defined-only …\Debug\Android-arm64-v8a\arm64-v8a\libAssmeblyCodeLinkObjects.soIn der Ausgabe sollte eine Liste von Symbolen angezeigt werden, die Folgendes enthält:
T from_shared_object_assembly_code_asT from_static_lib_assembly_code_as
PoolAllocator
Das PoolAllocator-Beispiel ist eine Android-App mit einem poolbasierten Arbeitsspeicherzuweiser, der Blöcke mit fester Größe sehr effizient bereitstellt.
Der Allocator weist den gesamten Arbeitsspeicher bei der Initialisierung mit mmap vorab zu. Unbelegte Blöcke werden mithilfe einer verknüpften Liste verfolgt. Dann ist eine Arbeitsspeicherzuweisung ein schneller O(1)-Vorgang, der den Kopf der verknüpften Liste zurückgibt. Die Freigabe ist ebenfalls ein O(1)-Vorgang, da der Block am Ende der verknüpften Liste hinzugefügt wird.
Das Beispiel enthält zwei Lösungskonfigurationen für die Verwendung von HWASan.
HWASan: Diese Konfiguration zeigt den einfachsten Ansatz für die Verwendung von HWASan mit benutzerdefinierten Arbeitsspeicherzuweisungen. Die interne Implementierung des Arbeitsspeicherzuweisers wird durchmalloc/free-Aufrufe ersetzt, die automatisch von HWASan erfasst werden. Der Arbeitsspeicherzuweiser funktioniert zwar nicht mehr als poolbasierter Zuweiser, aber HWASan kann Ihnen trotzdem helfen, wichtige Arbeitsspeicherfehler wie Use-After-Free zu identifizieren.HWASan-Advanced: Diese Konfiguration zeigt, wie HWASan vollständig in einen benutzerdefinierten Arbeitsspeicherzuweiser integriert werden kann, ohne den ursprünglichen Zuweisungsmechanismus des Zuweisers zu ändern. Sie verwendet HWASan-Tagging-Methoden, um die Speicherblöcke im vorab zugewiesenen Pool zu taggen, rundet die Blockgröße auf eine von HWASan erforderliche Mindestblockgröße auf und setzt die Tags zurück, wenn Blöcke an den Pool zurückgegeben werden.
Verwenden Sie die HWASan-Konfiguration, da sie einfacher ist und Ihnen helfen kann, häufige Speicherfehler zu identifizieren. Sehen Sie sich die Implementierung der HWASan-Advanced-Konfiguration an, wenn Sie verstehen möchten, wie HWASan funktioniert, oder wenn Sie die interne Semantik Ihres Arbeitsspeicherzuweisers beibehalten möchten, während Sie HWASan verwenden.