Build an OpenGL ES application on Android and iOS

You can create Visual Studio solutions and projects for iOS apps and Android apps that share common code. This article guides you through a solution template that creates both a simple iOS app and an Android Native Activity app. The apps have C++ code in common that uses OpenGL ES to display the same animated rotating cube on each platform. OpenGL ES (OpenGL for Embedded Systems or GLES) is a 2D and 3D graphics API that is supported on many mobile devices.

Requirements

Before you can create an OpenGL ES app for iOS and Android, make sure you've met all system requirements. If you haven't already, install the Mobile Development with C++ workload in the Visual Studio Installer. To build for iOS, include the optional C++ iOS development tools. To build for Android, install the C++ Android development tools and the required third-party tools: Android NDK, Apache Ant, Google Android Emulator, and Intel Hardware Accelerated Execution Manager. Next, configure Intel HAXM and the Android Emulator to run on your system. For more information and detailed instructions, see Install Visual C++ for cross-platform mobile development. To build and test the iOS app, you'll need a Mac computer, set up according to the installation instructions. For more information about how to set up for iOS development, see Install and configure tools to build using iOS

Create a new OpenGLES Application project

In this tutorial, you first create a new OpenGL ES Application project and then build and run the default app in the Visual Studio Emulator for Android. Next you build the app for iOS and run the app on an iOS device.

  1. In Visual Studio, choose File > New > Project.

  2. In the New Project dialog box, under Templates, choose Visual C++ > Cross Platform, and then choose the OpenGLES Application (Android, iOS) template.

  3. Give the app a name like MyOpenGLESApp, and then choose OK.

    New OpenGLES Application project

    Visual Studio creates the new solution and opens Solution Explorer.

    MyOpenGLESApp in Solution Explorer

    The new OpenGL ES Application solution includes three library projects and two application projects. The Libraries folder includes a shared code project and two platform-specific projects that reference the shared code:

  • MyOpenGLESApp.Android.NativeActivity contains the references and glue code that implements your app as a Native Activity on Android. The entry points from the glue code are implemented in main.cpp, which includes the common shared code in MyOpenGLESApp.Shared. Precompiled headers are in pch.h. This Native Activity app project is compiled into a shared library (.so) file, which is picked up by the MyOpenGLESApp.Android.Packaging project.

  • MyOpenGLESApp.iOS.StaticLibrary creates an iOS static library (.a) file that contains the shared code in MyOpenGLESApp.Shared. It's linked to the app created by the MyOpenGLESApp.iOS.Application project.

  • MyOpenGLESApp.Shared contains the shared code that works across platforms. It uses preprocessor macros for conditional compilation of platform-specific code. The shared code is picked up by project reference in both MyOpenGLESApp.Android.NativeActivity and MyOpenGLESApp.iOS.StaticLibrary.

The solution has two projects to build the apps for the Android and iOS platforms:

  • MyOpenGLESApp.Android.Packaging creates the .apk file for deployment on an Android device or emulator. This file contains the resources and AndroidManifest.xml file where you set manifest properties. It also contains the build.xml file that controls the Ant build process. It's set as the startup project by default, so that it can be deployed and run directly from Visual Studio.

  • MyOpenGLESApp.iOS.Application contains the resources and Objective-C glue code to create an iOS app that links to the C++ static library code in MyOpenGLESApp.iOS.StaticLibrary. This project creates a build package that is transferred to your Mac by Visual Studio and the remote agent. When you build this project, Visual Studio sends the files and commands to build and deploy your app on the Mac.

Build and run the Android app

The solution created by the template sets the Android app as the default project. You can build and run this app to verify your installation and setup. For an initial test, run the app on one of the device profiles installed by the emulator for Android. If you prefer to test your app on another target, you can load the target emulator or connect the device to your computer.

To build and run the Android Native Activity app

  1. If it isn't already selected, choose x86 from the Solution Platforms drop-down list.

    Set the Solution Platform to x86

    Use x86 to target the emulator. To target a device, choose the solution platform based on the device processor. If the Solution Platforms list isn't displayed, choose Solution Platforms from the Add/Remove Buttons list, and then choose your platform.

  2. In Solution Explorer, open the shortcut menu for MyOpenGLESApp.Android.Packaging project and then choose Build.

    Build Android Packaging Project

    The Output window displays the output of the build process for the Android shared library and the Android app.

    Build Output for Android projects

  3. Choose one of the emulated Android device profiles as your deployment target.

    Choose deployment target

    If you have installed other emulators or connected an Android device, you can choose them in the deployment target drop-down list. To run the app, the built Solution Platform must match the platform of the target device.

  4. Press F5 to start debugging, or Shift+F5 to start without debugging.

    Visual Studio starts the emulator, which takes several seconds to load and deploy your code. Here's how the app appears in the emulator:

    App running in Android Emulator

    Once your app has started, you can set breakpoints and use the debugger to step through code, examine locals, and watch values.

  5. Press Shift+F5 to stop debugging.

    The emulator is a separate process that continues to run. You can edit, compile, and deploy your code multiple times to the same emulator. Your app appears in the app collection on the emulator, and it can be started from there directly.

    The generated Android Native Activity app and library projects put the C++ shared code in a dynamic library that includes "glue" code to interface with the Android platform. Most of the app code is in the library, and the manifest, resources, and build instructions are in the packaging project. The shared code is called from main.cpp in the NativeActivity project. For more information about how to program an Android Native Activity, see the Android Developer NDK Concepts page.

    Visual Studio builds Android Native Activity projects by using the Android NDK, which uses Clang as the platform toolset. Visual Studio maps the properties in the NativeActivity project to the options used to compile, link, and debug on the target platform. For details, open the Property Pages dialog for the MyOpenGLESApp.Android.NativeActivity project. For more information about the command-line switches, see the Clang Compiler User's Manual.

Build and run the iOS app on an iOS device

The iOS app project is created and edited in Visual Studio, but because of licensing restrictions, it must be built and deployed from a Mac. Visual Studio communicates with a remote agent running on the Mac to transfer project files and execute build, deployment, and debugging commands. Set up and configure your Mac and Visual Studio to communicate before you can build the iOS app. For detailed instructions, see Install and configure tools to build using iOS. Once the remote agent is running on your Mac and paired with Visual Studio, you can build and run the iOS app to verify your installation and setup.

To deploy an iOS app to an iOS device, you must also set up automatic signing on Xcode on the Mac. Automatic signing automatically manages app signing, and creates a provisioning profile to sign a build of the app.

To set up automatic signing on Xcode

  1. If you haven't already, install Xcode version 10.2.1 or later on your Mac.

  2. Open the Xcode app on your Mac.

  3. Create a new Single View Application Xcode project. Fill in the required fields during project creation. The values can be arbitrary, as the project is only used to create a provisioning profile that's used later to sign a build of the app.

  4. Add your Apple ID that's enrolled in an Apple Developer Program account to Xcode. Your Apple ID is used as a signing identity to sign apps. To add your signing identity in Xcode, open the Xcode menu and choose Preferences. Select Accounts and click the Add button (+) to add your Apple ID. For detailed instructions, see Add your Apple ID account.

  5. From the Xcode project's "General" settings, change the value of Bundle Identifier to com.<NameOfVSProject>, where <NameOfVSProject> is the same name as the Visual Studio solution project you created. For example, if you created a project called MyOpenGLESApp on Visual Studio, then set Bundle Identifier to com.MyOpenGLESApp.

    Xcode bundle identifier

  6. To enable automatic signing, check. Automatically manage signing**.

    Xcode automatic signing

  7. Select the team name of the Apple ID you added as the development Team.

    Xcode team

To build and run the iOS app on an iOS device

  1. Run the remote agent on your Mac, and verify that Visual Studio is paired to the remote agent. To start the remote agent, open a Terminal app window and enter vcremote. For more information, see Configure the remote agent in Visual Studio.

    Mac Terminal window running vcremote

  2. Attach an iOS device to your Mac. When you attach your device to a computer for the first time, an alert asks whether you trust the computer to access your device. Enable the device to trust the Mac computer.

  3. On Visual Studio, if it isn't already selected, choose the solution platform from the Solution Platforms drop-down list based on your device processor. In this example, it's an ARM64 processor.

    Set the Solution Platform to ARM64

  4. In Solution Explorer, open the shortcut menu for the MyOpenGLESApp.iOS.Application project and choose Unload Project to unload the project.

  5. Again, open the shortcut menu for the unloaded MyOpenGLESApp.iOS.Application project and choose Edit project.pbxproj to edit the project file. In the project.pbxproj file, look for the buildSettings attribute and add DEVELOPMENT_TEAM using your Apple Team ID. The screenshot below shows an example value of 123456ABC for the Apple Team ID. You can find the value of your Apple Team ID from Xcode. Go to Build Settings and hover over your development team name to show a tooltip. The tooltip shows your team ID.

    Set development team

  6. Close the project.pbxproj file, then open the shortcut menu for the unloaded MyOpenGLESApp.iOS.Application project and choose Reload Project to reload the project.

  7. Now build the MyOpenGLESApp.iOS.Application project by opening the shortcut menu for the project and choosing Build.

    Build iOS Application project

    The Output window displays the output of the build process for the iOS static library and the iOS app. On the Mac, the Terminal window running the remote agent shows the command and file transfer activity.

    On your Mac computer, you may be prompted to allow codesign to access your keychain. Choose Allow to continue.

  8. Choose your iOS device on the toolbar to run the app on your device attached to your Mac. If the app doesn't start, verify that the device gives permission for your deployed application to execute on the device. This permission can be set by going to Settings > General > Device Management on the device. Select your Developer App account, trust your account, and verify the app. Try to run the app again from Visual Studio.

    iOS app on iOS device

    Once your app has started, you can set breakpoints and use the Visual Studio debugger to examine locals, see the call stack, and watch values.

    Debugger at breakpoint in iOS app

  9. Press Shift+F5 to stop debugging.

    The generated iOS app and library projects put the C++ code in a static library that implements only the shared code. Most of the application code is in the Application project. The calls to the shared library code in this template project are made in the GameViewController.m file. To build your iOS app, Visual Studio uses the Xcode platform toolset, which requires communication with a remote client that is running on a Mac.

    Visual Studio transfers the project files and sends commands to the remote client to build the app using Xcode. The remote client sends build status information back to Visual Studio. When the app has built successfully, you can use Visual Studio to send commands to run and debug the app. The debugger in Visual Studio controls the app running on your iOS device attached to your Mac. Visual Studio maps the properties in the StaticLibrary project to the options used to compile, link, and debug on the target iOS platform. For compiler command-line option details, open the Property Pages dialog for the MyOpenGLESApp.iOS.StaticLibrary project.

Customize your apps

You can modify the shared C++ code to add or change common functionality. You must change the calls to the shared code in the MyOpenGLESApp.Android.NativeActivity and MyOpenGLESApp.iOS.Application projects to match. You can use preprocessor macros to specify platform-specific sections in your common code. The preprocessor macro __ANDROID__ is predefined when you build for Android. The preprocessor macro __APPLE__ is predefined when you build for iOS.

To see the IntelliSense for a particular project platform, choose the project in the context switcher dropdown in the Navigation bar at the top of the editor window.

Project Context Switcher dropdown in Editor

IntelliSense issues in code that's used by the current project are marked with a red wavy line. Issues in other projects are marked with a purple wavy line. Visual Studio doesn't support code colorization or IntelliSense for Java or Objective-C files. However, you can still modify the source files and change the resources to set your application name, icon, and other implementation details.