Примеры для Android Game Development Extension демонстрируют, как использовать основные функции расширения. В этом документе описаны примеры и настройки, необходимые для их запуска.
На странице скачивания доступны следующие примеры:
- HelloJNI – вводный проект.
- Endless-Tunnel – проект только для Android.
- Teapot – кросс-платформенный проект для Windows и Android.
- AssemblyCode-Link-Objects – шаблон проекта с исходным кодом на ассемблере.
Подготовка
Установите Android Game Development Extension и примеры. Подробную информацию можно найти в кратком руководстве. В этой статье также описывается, как создать и запустить пример, используя версию примера Teapot для Android.
В руководстве по настройке проекта описано, как задать настройки для проекта, в котором используется расширение, например как добавить платформу Android и APK.
HelloJNI
Пример HelloJNI – это проект, который показывает сообщение "Hello From JNI" в окне приложения. В проекте используются разные наборы исходного кода для Windows и Android.
- Каталог с исходным кодом Android и скриптами сборки Gradle: HelloJNI\AndroidPackaging.
- Исходный код Windows и каталог проекта Visual Studio: HelloJNI.
При сборке проекта Visual Studio передает следующие настройки в файл build.gradle на уровне приложения. Вы можете изменить эти настройки, отредактировав скрипты сборки Gradle.
MSBUILD_NDK_VERSIONMSBUILD_MIN_SDK_VERSIONMSBUILD_JNI_LIBS_SRC_DIRMSBUILD_ANDROID_OUTPUT_APK_NAMEMSBUILD_ANDROID_GRADLE_BUILD_OUTPUT_DIR
Чтобы настроить и запустить пример, выполните следующие действия:
- Откройте и соберите пример HelloJNI в Visual Studio.
- Добавьте платформу Android arm64-v8a. Подробнее о том, как добавить платформу Android…
- Добавьте объект APK для Android на новую платформу.
- Скомпилируйте проект.
- Добавьте следующие платформы Android, а затем добавьте в каждую из них элемент APK для Android: Android-armeabi-v7a, Android-x86 и Android-x86_64.
- Соберите и запустите пример.
Endless-Tunnel
Endless-Tunnel – это игра для Android, в которой игрок собирает белые кубы, пытаясь добраться до конца туннеля. Он был перенесен из примера OpenGL в репозитории Android NDK на GitHub. В примере нет версии игры для Windows.
В примере уже заданы настройки и платформы Android, поэтому вы можете собрать и запустить проект в Visual Studio без каких-либо изменений. Когда вы откроете решение, в Solution Explorer (Обозревателе решений) появятся следующие модули:
- endless-tunnel – модуль приложения, который отображает логику игры.
- glm – снимок репозитория OpenGL Math, созданный как статическая библиотека.
- native_app_glue – оболочка NDK, которая взаимодействует с объектом
NativeActivity.
Чайник
В примере Teapot показан классический чайник, отрисованный с помощью OpenGL ES и перенесенный в Android Game Development Extension для демонстрации следующих функций:
- Разработка кроссплатформенных проектов: вы можете создать пример Teapot для Windows и Android.
- Использование пользовательской упаковки Android: скрипты сборки Gradle были перемещены в корневой каталог примера, где находится файл
Teapot.sln. - Специальные конфигурации Android, демонстрирующие использование Address Sanitizer (ASan) и Hardware Address Sanitizer (HWASan).
Реализация примера Teapot разделена на несколько частей, что типично для крупных кросс-платформенных приложений и игр:
- Модуль
GameApplicationопределяет действия пользователя и состояния приложения, например поворот чайника или обновление статистики приложения. - Модуль
GameEngineреализует основной модуль отрисовки.
Инструкции по настройке и запуску примера на Android приведены в кратком руководстве. Чтобы настроить и запустить пример в Windows, выполните следующие действия:
- Установите GLEW:
- Скачайте и распакуйте GLEW.
- Скопируйте двоичные файлы из
$your-glew-directory\bin\Release\x64в%SystemRoot%\system32.
- Установите freeglut:
- Скачайте и распакуйте freeglut.
- Скопируйте
$your-freeglut-directory\bin\x86\freeglut.dllв%SystemRoot%\system32.
- Добавьте зависимости проекта freeglut:
- Откройте файл
Teapot.slnв Visual Studio. - В меню выберите Debug (Отладка) > x64 > Local Windows Debugger (Локальный отладчик Windows).
- В окне Solution Explorer (Обозреватель решений) нажмите правой кнопкой мыши на GameApplication и выберите Properties (Свойства) > C/C++ > General (Общие) > Additional Include Directories (Дополнительные каталоги включаемых файлов).
- Добавьте
$your-freeglut-dir\includeв путь.
- Нажмите ОК.
- Выберите Linker (Компоновщик) > General (Общие) > Additional Library Directories (Дополнительные каталоги библиотек).
- Добавьте
$your-freeglut-dir\lib\x64в путь.
- Нажмите ОК.
- Выберите Linker (Компоновщик) > General (Общие) > Additional Library Directories (Дополнительные каталоги библиотек).
- Добавьте
freeglut.libв путь. - Нажмите ОК.
- Откройте файл
- Добавьте зависимости проекта GLEW:
- На панели Обозреватель решений нажмите правой кнопкой мыши на GameApplication и выберите Свойства > C/C++ > Общие > Дополнительные каталоги включаемых файлов.
- Добавьте
$your-glew-dir\includeв путь. - Нажмите ОК.
- Выберите Linker (Компоновщик) > General (Общие) > Additional Library Directories (Дополнительные каталоги библиотек).
- Добавьте
$your-glew-dir\lib\Release\x86в путь. - Нажмите ОК.
- Выберите Linker (Компоновщик) > General (Общие) > Additional Library Directories (Дополнительные каталоги библиотек).
- Добавьте
glew32.libв путь. - Нажмите ОК.
- Запустите пример на Windows:
- На панели инструментов Visual Studio нажмите кнопку Локальный отладчик Windows.
- Пример:
AssemblyCode-Link-Objects
Это шаблон проекта, который демонстрирует, как создать нативную библиотеку Android из ассемблерного кода и исходного кода C/C++. Вот основные компоненты:
AssemblyCode-Link-Objects– основная нативная библиотека Android, созданная на основе исходного кода C++ и ассемблера.StaticLib– вспомогательная статическая библиотека, которая экспортирует функциюfrom_static_lib_assembly_code_as.
Проект поддерживает несколько архитектур. Для каждой поддерживаемой архитектуры есть свои исходные файлы, в которых реализованы функции, экспортируемые из StaticLib.
Включайте только исходные файлы ассемблера для платформ, для которых вы выполняете сборку. В этом проекте файлы сборки включаются в сборки с помощью пользовательских инструментов сборки.
Чтобы настроить и собрать пример, выполните следующие действия:
- В Visual Studio убедитесь, что для файлов сборки настроены специальные инструменты сборки:
- В Solution Explorer (Обозревателе решений) нажмите правой кнопкой мыши на файл сборки и выберите Properties (Свойства). Откроется диалоговое окно Страницы свойств.
- Выберите конфигурацию и платформу, например All configurations (Все конфигурации) для Android-arm64-v8a.
- Убедитесь, что для параметра General (Общие) > Exclude from Build (Исключить из сборки) задано значение No (Нет).
- Убедитесь, что в разделе General (Общие) > Item Type (Тип элемента) выбран вариант Custom Build Tool (Пользовательский инструмент сборки).
- Если вы внесли изменения, нажмите Применить.
- Убедитесь, что для параметра Configuration Properties (Свойства конфигурации) > Custom Build Tools (Пользовательские инструменты сборки) > Command Line (Командная строка) задано значение
$(AsToolExe) -o "$(IntDir)%(FileName).o" %(FullPath). NDK включает отдельный ассемблер для каждой архитектуры ЦП, а$(AsToolExe)сопоставляется с правильным ассемблером. В этом примере используется набор инструментов NDK для создания проектов Android x86 и x86_64. Если вы хотите использовать yasm для платформы Android x86_64, используйте$(YasmToolExe). - Убедитесь, что для параметра Configuration Properties (Свойства конфигурации) > Custom Build Tools (Пользовательские инструменты сборки) > Outputs (Выходные данные) задано значение
$(IntDir)%(FileName).o. Эту строку необходимо включить в параметр Командная строка. - Убедитесь, что для параметра Configuration Properties (Свойства конфигурации) > Custom Build Tools (Пользовательские инструменты сборки) > Link Objects (Связать объекты) задано значение
Yes.
Например, настройки Android-arm64-v8a должны выглядеть примерно так, как показано на скриншоте ниже.
- Соберите проект. Будет создан файл
libAssmeblyCodeLinkObjects.so:- Откройте файл
AssemblyCode-Link-Objects.sln. - В меню выберите Build (Сборка) > Build Solution (Собрать решение).
- Откройте файл
- Чтобы убедиться, что функции экспортируются в библиотеку Android правильно, используйте инструмент nm.exe NDK:
- В командной строке перейдите в каталог с примером.
- Перейдите в каталог библиотеки Android, созданный при сборке. Местоположение по умолчанию похоже на
$sample_dir\$solution_configuration\$solution_platform\$platformи$sample_dir\Debug\Android-arm64-v8a\arm64-v8aдля платформы arm64-v8a. - Убедитесь, что раздел экспортированных символов содержит функции, выполнив следующую команду:
…\ndk\toolschains\llvm\prebuilt\windows-x86_64\aarch64-linux-android\bin\nm.exe --defined-only …\Debug\Android-arm64-v8a\arm64-v8a\libAssmeblyCodeLinkObjects.soВ выходных данных вы должны увидеть список символов, включающий следующие:
T from_shared_object_assembly_code_asT from_static_lib_assembly_code_as
PoolAllocator
PoolAllocator – это приложение для Android, в котором есть распределитель памяти на основе пула, эффективно предоставляющий блоки фиксированного размера.
Аллокатор предварительно выделяет всю память во время инициализации с помощью mmap. Свободные блоки отслеживаются с помощью связанного списка. В этом случае выделение памяти – это быстрая операция O(1), которая возвращает начало связанного списка, а освобождение памяти – это также операция O(1), поскольку она добавляет блок в конец связанного списка.
В примере есть две конфигурации решения для использования HWASan.
HWASan– эта конфигурация демонстрирует самый простой подход к использованию HWASan с пользовательскими распределителями памяти. Внутренняя реализация распределителя памяти заменяется вызовамиmalloc/free, которые автоматически отслеживаются HWASan. Хотя распределитель памяти больше не работает как распределитель на основе пула, HWASan по-прежнему может помочь вам выявить важные ошибки памяти, такие как использование после освобождения.HWASan-Advanced. Эта конфигурация демонстрирует, как полностью интегрировать HWASan в пользовательский распределитель памяти, не меняя исходный механизм распределения, используемый распределителем. Он использует методы тегирования HWASan для тегирования блоков памяти в предварительно выделенном пуле, округляет размер блока до минимального размера блока, требуемого HWASan, и сбрасывает теги, когда блоки возвращаются обратно в пул.
Используйте конфигурацию HWASan, так как она проще и может помочь вам выявить распространенные ошибки памяти. Изучите реализацию конфигурации HWASan-Advanced, если вы хотите понять, как работает HWASan, или сохранить внутреннюю семантику распределителя памяти при использовании HWASan.