示例

Android 游戏开发扩展的示例演示了如何使用扩展的关键功能。本主题介绍了示例以及运行它们所需的设置。

以下示例可在 下载页面 上找到

  • HelloJNI：一个入门项目。
  • Endless-Tunnel：一个仅限 Android 的项目。
  • Teapot：一个适用于 Windows 和 Android 的跨平台项目。
  • AssemblyCode-Link-Objects：一个包含汇编源代码的模板项目。

开始之前

  • 安装 Android 游戏开发扩展和示例。有关详细信息，请参阅 快速入门。本主题还介绍了如何构建和运行示例，并使用 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. 在 Visual Studio 中，打开并构建 HelloJNI 示例。
  2. 添加一个 Android arm64-v8a 平台。有关详细信息，请参阅 添加 Android 平台。
  3. 在新建的平台上 添加一个 Android APK 项目。
  4. 编译项目。
  5. 添加以下 Android 平台，然后在每个平台上添加一个 Android APK 项目：Android-armeabi-v7a、Android-x86 和 Android-x86_64。
  6. 构建和运行 示例。

Endless-Tunnel

Endless-Tunnel 示例是一款 Android 游戏，玩家在其中收集白色立方体，同时试图到达隧道的尽头。它改编自 Github 上的 Android NDK 仓库 中的 OpenGL 示例。该示例没有提供 Windows 版本的游戏。

该示例已配置了其设置和 Android 平台，因此你可以在 Visual Studio 中构建和运行项目，无需任何修改。打开解决方案时，解决方案资源管理器将显示以下模块

  • endless-tunnel：显示游戏逻辑的应用程序模块。
  • glm：OpenGL Math 仓库 的快照，构建为静态库。
  • native_app_glue：一个 NDK 包装器，与 NativeActivity 对象通信。

Teapot

Teapot 示例显示了一个经典的茶壶，使用 OpenGL ES 渲染，并移植到 Android 游戏开发扩展以演示以下功能

  • 跨平台项目开发：你可以在 Windows 和 Android 上构建 Teapot 示例。
  • 自定义 Android 打包使用：Gradle 构建脚本已移动到示例的根目录，Teapot.sln 文件位于该目录。
  • 演示如何使用 Address Sanitizer (ASan) 和 Hardware Address Sanitizer (HWAsan) 的自定义 Android 配置。

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. 在 Visual Studio 中打开 Teapot.sln。
    2. 在菜单中，单击 调试 > x64 > 本地 Windows 调试器。
    3. 在 解决方案资源管理器 中，右键单击 GameApplication 并选择 属性 > C/C++ > 常规 > 附加包含目录。
    4. 将 $your-freeglut-dir\include 添加到路径。
      Screenshot of the Additional Include Directories dialog.
    5. 单击 确定。
    6. 选择 链接器 > 常规 > 附加库目录。
    7. 将 $your-freeglut-dir\lib\x64 添加到路径。 附加库目录对话框的屏幕截图。
    8. 单击 确定。
    9. 选择 链接器 > 常规 > 附加库目录。
    10. 将 freeglut.lib 添加到路径。
    11. 单击 确定。
  4. 添加 GLEW 项目依赖项
    1. 在 解决方案资源管理器 窗格中，右键单击 GameApplication 并选择 属性 > C/C++ > 常规 > 附加包含目录。
    2. 将 $your-glew-dir\include 添加到路径。
    3. 单击 确定。
    4. 选择 链接器 > 常规 > 附加库目录。
    5. 将 $your-glew-dir\lib\Release\x86 添加到路径。
    6. 单击 确定。
    7. 选择 链接器 > 常规 > 附加库目录。
    8. 将 glew32.lib 添加到路径。
    9. 单击 确定。
  5. 在 Windows 上运行示例
    1. 在 Visual Studio 工具栏上，单击 本地 Windows 调试器 运行按钮。
    2. 示例应如下所示
      Screenshot of the Teapot sample running on Windows.

这是一个模板项目，演示了如何从汇编和 C/C++ 源代码生成 Android 本地库。以下是主要组件

  • AssemblyCode-Link-Objects：从 C++ 和汇编源代码构建的主要 Android 本地库。
  • StaticLib：一个辅助静态库，导出 from_static_lib_assembly_code_as 函数。

该项目支持多种架构。每个支持的架构都有自己的源文件，这些文件实现从 StaticLib 导出的函数。你应该只包含要构建的平台的汇编源文件。该项目通过使用 自定义构建工具 在构建中包含汇编文件。

设置和构建示例

  1. 在 Visual Studio 中，验证是否为程序集文件配置了自定义生成工具。
    1. 在**解决方案资源管理器**中，右键单击程序集文件，然后单击**属性**。这将打开该文件的**属性页**对话框。
    2. 选择配置和平台，例如，对于**Android-arm64-v8a**，选择**所有配置**。
    3. 确保**常规 > 从生成中排除**设置为**否**。
    4. 确保**常规 > 项目类型**设置为**自定义生成工具**。
    5. 如果存在要应用的更改，请单击**应用**。
    6. 确保**配置属性 > 自定义生成工具 > 命令行**：设置为$(AsToolExe) -o "$(IntDir)%(FileName).o" %(FullPath)。NDK 包含针对每个 CPU 架构的独立汇编器，而$(AsToolExe)会映射到正确的汇编器。本示例使用 NDK 工具链来构建 x86 和 x86_64 Android 项目。如果您想对 x86_64 Android 平台使用 yasm，请使用$(YasmToolExe)。
    7. 确保**配置属性 > 自定义生成工具 > 输出**：设置为$(IntDir)%(FileName).o。此字符串必须包含在**命令行**设置中。
    8. 确保**配置属性 > 自定义生成工具 > 链接对象**：设置为是。

    例如，**Android-arm64-v8a**设置应类似于以下屏幕截图。

    Screenshot of the Property Page for Custom Build Tools.
  2. 构建项目。这将构建libAssmeblyCodeLinkObjects.so文件。
    1. 打开AssemblyCode-Link-Objects.sln文件。
    2. 在菜单中，单击**生成 > 生成解决方案**。
  3. 要确认函数是否已正确导出到 Android 库，请使用 nm.exe NDK 工具。
    1. 在命令行中，转到示例目录。
    2. 转到由构建生成的 Android 库位置。默认位置类似于$sample_dir\$solution_configuration\$solution_platform\$platform，对于**arm64-v8a**平台，则为$sample_dir\Debug\Android-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