Примеры

Примеры для 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_VERSION
  • MSBUILD_MIN_SDK_VERSION
  • MSBUILD_JNI_LIBS_SRC_DIR
  • MSBUILD_ANDROID_OUTPUT_APK_NAME
  • MSBUILD_ANDROID_GRADLE_BUILD_OUTPUT_DIR

Чтобы настроить и запустить пример, выполните следующие действия:

  1. Откройте и соберите пример HelloJNI в Visual Studio.
  2. Добавьте платформу Android arm64-v8a. Подробнее о том, как добавить платформу Android…
  3. Добавьте объект APK для Android на новую платформу.
  4. Скомпилируйте проект.
  5. Добавьте следующие платформы Android, а затем добавьте в каждую из них элемент APK для Android: Android-armeabi-v7a, Android-x86 и Android-x86_64.
  6. Соберите и запустите пример.

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, выполните следующие действия:

  1. Установите GLEW:
    1. Скачайте и распакуйте GLEW.
    2. Скопируйте двоичные файлы из $your-glew-directory\bin\Release\x64 в %SystemRoot%\system32.
  2. Установите freeglut:
    1. Скачайте и распакуйте freeglut.
    2. Скопируйте $your-freeglut-directory\bin\x86\freeglut.dll в %SystemRoot%\system32.
  3. Добавьте зависимости проекта freeglut:
    1. Откройте файл Teapot.sln в Visual Studio.
    2. В меню выберите Debug (Отладка) > x64 > Local Windows Debugger (Локальный отладчик Windows).
    3. В окне Solution Explorer (Обозреватель решений) нажмите правой кнопкой мыши на GameApplication и выберите Properties (Свойства) > C/C++ > General (Общие) > Additional Include Directories (Дополнительные каталоги включаемых файлов).
    4. Добавьте $your-freeglut-dir\include в путь.
      Диалоговое окно страницы свойств Additional Include Directories (Дополнительные каталоги включаемых файлов) в Visual Studio.
    5. Нажмите ОК.
    6. Выберите Linker (Компоновщик) > General (Общие) > Additional Library Directories (Дополнительные каталоги библиотек).
    7. Добавьте $your-freeglut-dir\lib\x64 в путь. Диалоговое окно страницы свойств дополнительных каталогов библиотек Visual Studio.
    8. Нажмите ОК.
    9. Выберите Linker (Компоновщик) > General (Общие) > Additional Library Directories (Дополнительные каталоги библиотек).
    10. Добавьте freeglut.lib в путь.
    11. Нажмите ОК.
  4. Добавьте зависимости проекта GLEW:
    1. На панели Обозреватель решений нажмите правой кнопкой мыши на GameApplication и выберите Свойства > C/C++ > Общие > Дополнительные каталоги включаемых файлов.
    2. Добавьте $your-glew-dir\include в путь.
    3. Нажмите ОК.
    4. Выберите Linker (Компоновщик) > General (Общие) > Additional Library Directories (Дополнительные каталоги библиотек).
    5. Добавьте $your-glew-dir\lib\Release\x86 в путь.
    6. Нажмите ОК.
    7. Выберите Linker (Компоновщик) > General (Общие) > Additional Library Directories (Дополнительные каталоги библиотек).
    8. Добавьте glew32.lib в путь.
    9. Нажмите ОК.
  5. Запустите пример на Windows:
    1. На панели инструментов Visual Studio нажмите кнопку Локальный отладчик Windows.
    2. Пример:
      Пример приложения Teapot, запущенного в окне Windows.

Это шаблон проекта, который демонстрирует, как создать нативную библиотеку Android из ассемблерного кода и исходного кода C/C++. Вот основные компоненты:

  • AssemblyCode-Link-Objects – основная нативная библиотека Android, созданная на основе исходного кода C++ и ассемблера.
  • StaticLib – вспомогательная статическая библиотека, которая экспортирует функцию from_static_lib_assembly_code_as.

Проект поддерживает несколько архитектур. Для каждой поддерживаемой архитектуры есть свои исходные файлы, в которых реализованы функции, экспортируемые из StaticLib. Включайте только исходные файлы ассемблера для платформ, для которых вы выполняете сборку. В этом проекте файлы сборки включаются в сборки с помощью пользовательских инструментов сборки.

Чтобы настроить и собрать пример, выполните следующие действия:

  1. В Visual Studio убедитесь, что для файлов сборки настроены специальные инструменты сборки:
    1. В Solution Explorer (Обозревателе решений) нажмите правой кнопкой мыши на файл сборки и выберите Properties (Свойства). Откроется диалоговое окно Страницы свойств.
    2. Выберите конфигурацию и платформу, например All configurations (Все конфигурации) для Android-arm64-v8a.
    3. Убедитесь, что для параметра General (Общие) > Exclude from Build (Исключить из сборки) задано значение No (Нет).
    4. Убедитесь, что в разделе General (Общие) > Item Type (Тип элемента) выбран вариант Custom Build Tool (Пользовательский инструмент сборки).
    5. Если вы внесли изменения, нажмите Применить.
    6. Убедитесь, что для параметра 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).
    7. Убедитесь, что для параметра Configuration Properties (Свойства конфигурации) > Custom Build Tools (Пользовательские инструменты сборки) > Outputs (Выходные данные) задано значение $(IntDir)%(FileName).o. Эту строку необходимо включить в параметр Командная строка.
    8. Убедитесь, что для параметра Configuration Properties (Свойства конфигурации) > Custom Build Tools (Пользовательские инструменты сборки) > Link Objects (Связать объекты) задано значение Yes.

    Например, настройки Android-arm64-v8a должны выглядеть примерно так, как показано на скриншоте ниже.

    Диалоговое окно "Страницы свойств" в Visual Studio для настраиваемых инструментов сборки.
  2. Соберите проект. Будет создан файл libAssmeblyCodeLinkObjects.so:
    1. Откройте файл AssemblyCode-Link-Objects.sln.
    2. В меню выберите Build (Сборка) > Build Solution (Собрать решение).
  3. Чтобы убедиться, что функции экспортируются в библиотеку Android правильно, используйте инструмент nm.exe NDK:
    1. В командной строке перейдите в каталог с примером.
    2. Перейдите в каталог библиотеки Android, созданный при сборке. Местоположение по умолчанию похоже на $sample_dir\$solution_configuration\$solution_platform\$platform и $sample_dir\Debug\Android-arm64-v8a\arm64-v8a для платформы arm64-v8a.
    3. Убедитесь, что раздел экспортированных символов содержит функции, выполнив следующую команду:
        …\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_as
         T 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.