Getting started with openFrameworks on Android

10 min readSep 14, 2017

Note: instructions recently updated to reference a new NDK version r15c.

openFrameworks is a powerful, fun creative toolkit to work with, but it can be notoriously difficult to setup your development environment just right so you can get started with actual coding, especially on mobile. Some great resources can be found here and here for Android, but I think they can still be difficult for newcomers to the toolkit. Here’s a more detailed set of instructions for other beginner mobile tinkerers out there.

We’ll be using:
1) Android Studio 2, Google’s official Integrated Development Environment (IDE) for Android,
2) openFrameworks version 0.10.0 for Android,
3) and an Android device to run the example apps. Unfortunately these demos don’t run on virtual devices just yet.

Do keep in mind that since openFrameworks is constantly changing and improving, these instructions might only be fresh for a few months. I’ll try to update them if something major changes. Finally, these instructions are for Mac users and assume that you know some basic terminal commands. Sorry Windows and Linux users! I’ve only got one machine at home, but most of the guide should apply you as well.

Part 1: General setup you’ll only have to do once

Install openFrameworks

Currently there are different openFramework (OF) builds for different platforms, so if you go to the openFrameworks download page you’ll see there’s a build for Android. Nevertheless the one currently on the OF website is version 0.9.8. We want to snatch version 0.10.0 which has some improvements on the Android side. Instead, let’s download OF directly from Github.

1. I like to keep my openFrameworks folder in my “Documents” folder, but that’s just a personal preference. You can download the folder to any place on your hard drive. Assuming you have git setup in your system, clone the master branch by running:

$ git clone --recursive https://github.com/openframeworks/openFrameworks.git

2. Not all the library dependencies we need are in the folder we just downloaded, so from within the main “openFrameworks” folder you’ll have to run a script to download missing dependencies. Each platform has a different script, so if you need to grab OSX dependencies you’d run ‘./scripts/osx/download_libs.sh’. In this case we want the Android dependencies, so navigate to the OF folder from the terminal and run a download script:

$ cd openFrameworks/
$ ./scripts/android/download_libs.sh

Note: if you get a “wget command not found”, it means you’re missing the wget program. I recommend you install Brew and then use it to install wget using brew install wget.

In the end, my OF folder looks like this

Set up the openFrameworks project generator

OF comes with a Project Generator application that helps you include add-ons in your applications and build for different platforms. It can be a little complicated to build the Project Generator from the command line, so we’ll download a release version of OF (currently 0.9.8) from the website and copy the project generator folder into our working OF directory.

1. Go to the openFrameworks download page and get the main OSX release version. Direct link: http://openframeworks.cc/versions/v0.9.8/of_v0.9.8_osx_release.zip

2. Unzip the folder and copy paste only the “projectGenerator-osx” folder into the OF directory we setup in the previous section. In fact you could save the project generator anywhere you’d like — in the “Applications” folder for example. I’m keeping it in the OF folder we downloaded from Github so it mimics the structure of the release version:

3. Inside the “projectGenerator-osx” folder you’ll find the “projectGenerator” app. Launch it open. You’ll get warning like the one below:

A warning you’ll get the first time you open the Project Generator

This means we have to set our “openFrameworks path” to the location on our hard drive where the OF folder lives. Click on the magnifying glass and find the right location. Also check “Verbose output” and “Advanced options”.

4. You can quit or keep open the “projectGenerator”. We’ll be using it later.

Install Android Studio

Now we need to get Google’s official IDE for developing Android applications.

1. Go to the Android Studio page and download the latest version (at the time of writing, that’s 2.3.3 for mac)

2. Install Android Studio. Once you get to the installation options, a “standard” installation should be fine.

Download the Android NDK

The Android NDK is a toolset that lets you make use of native code written in C/C++ for Android applications. Think of it as the C/C++ compiler, headers, and libraries for Android.

1. OF has been compiled against NDK version r15c, so go ahead and download that here: https://dl.google.com/android/repository/android-ndk-r15c-darwin-x86_64.zip. Here are the windows and linux versions.

2. Unzip that folder and also store it somewhere more permanent.

Phew that’s a lot of setup. Hopefully you’ll only have to do this once. The next couple of steps will be the ones to recreate when setting up new applications.

Part 2: Compile an example Android application

The “androidPolygonExample” app we’ll build and deploy

openFrameworks comes with a collection of examples that can be found in the “openFrameworks/examples/android/” folder. We’ll go through the necessary steps to run the “androidPolygonExample”, which is just a simple demo of a variety of shapes you can display and manipulate.

Al the android examples that come with openFrameworks

Generate Android Studio project files

1. We’re going to use the “projectGenerator” app to create the necessary files for Android Studio so first launch the project generator.

2. Click on the “import” button and navigate to the “openFrameworks/examples/android/androidPolygonExample” folder. Upon adding the folder, the “Project name” and “Project path” sections should update accordingly.

3. If the “Platforms” section is greyed out, click on the gear/settings icon on the top right and make sure “Advanced options” is checked.

Once you return to the “create/update” tab, you should be able to replace the “OSX (Xcode)” platform for “Android (Android Studio)”.

4. Click “Update” and wait for the Success screen. You can click “Close” and exit from the project generator.

Compile the app on Android Studio

1. Let’s launch Android Studio. You should see a welcome screen with a few different options. Click on the one that says “Open an existing Android Studio project”.

2. Now navigate to the “openFrameworks/examples/android/androidPolygonExample” and click on “OK”.

3. If you get a “Gradle Sync” warning just click “OK”.

4. Once the project window loads, you’ll be confronted with an error message like the one below complaining about an NDK.

We’ve got this, just click on the “Project structure” button on our toolbar which will open up the Project Structure settings.

Click on the “Project Structure” button in the toolbar

5. Click on the “…” button in the “Android NDK location” section and locate the folder where you stored the r15c NDK.

Notice the new path for the Android NDK location. Your version should point to NDK r15c.

6. Click “OK” to close the Project Structure settings. The gradle warning should have disappeared.

7. Instead, you might start getting some missing SDK errors. Android Studio should help you install these. Just click on “Install missing platform(s) and sync project”. In my case I had to install the Android SDK Platform 19 and Android SDK Build-Tools 25.0.2.

Note: as an aside, these two buttons on the bottom right of Android Studio are useful for checking errors and logs.

Two panels that will prove useful as you code and debug.

You can also go through your project files by clicking on “Project” on the left toolbar and then change “Android” to “Project” from the dropdown. This will allow you to see all the files in the project including the C++ source code.

Click on “Project” on the left hand toolbar first. Then use the dropdown to navigate to Project.

8. Now we’re going to build the application. You can either click on the hammer icon in the toolbar or go to Build > Make project.

9. If that compiled without any errors we can finally export to our Android phone! If this is the first time you’re building an Android app on your phone, you might need to do a bit of setup that is outside the scope of this tutorial.

Follow these instructions to configure on-device developer options: https://developer.android.com/studio/debug/dev-options.html

Then follow these to setup your device for development: https://developer.android.com/studio/run/device.htm

Assuming your device is connected to your computer, you can check that it is recognized by going to the Terminal and running:

$ adb devices

10. To deploy to our device, click on the play icon in the Android Studio toolbar or select Run > Run ‘androidPolygonExample’ from the menu bar. A deployment window should open up and you should see the name of your connected device highlighted. Click “OK” to deploy.

With any luck you should see something like this on your phone:

But wait what’s going on? The resolution is all messed up. The next section clarifies how to change a few basic parameters to get the resolution just right on your device.

Note: The ins and outs of Android Studio are also outside of the scope of this tutorial. But if you’d like to understand how the build process works and what Gradle is read: https://developer.android.com/studio/build/index.html

Fixing the screen resolution

Unfortunately there’s no automatic fix for dealing with different mobile screen sizes in OF just yet. Many of the current Android examples are a few years old and they were coded for smaller phone screens.You’ll have to do some individual tweaking to get your app to display correctly on your phone.

The first thing to keep in mind is that the following line within your “main.cpp” file has no effect on the app resolution:

ofSetupOpenGL(1024,768, OF_WINDOW); // Don't be fooled, this won't solve anything

Instead we’ll go for a quick fix that will scale our app to be a bit larger and fill up the screen. If you go to the “ofApp.cpp” file, and take a look at line #8 you’ll see:

appIphoneScale = 0.5; // Just ignore that it says iPhone :)

Change that to something that works on your device. It might take some experimentation. In my case, with a Pixel 1.5 is a good scaling factor when I lay out my phone horizontally.

appIphoneScale = 1.5; // Works on my Pixel in landscape mode

Apart from this quick and dirty trick, you’d actually have to make your fonts, shapes, lines, etc. larger and place them further apart to accommodate a larger screen.

Bonus section: debugging your app

Since we can’t deploy a virtual device to test OF Android applications, how should we debug our projects? One solution is to use Google’s Logcat command line tool. An in-depth look at Logcat is also outside the scope of this tutorial, but you can learn more about it here: https://developer.android.com/studio/command-line/logcat.html

I’ll share a few commands to get you started.

1. To find the name of your application package, connect your device to your computer and run:

$ adb shell 'pm list packages -f openframeworks'

In my case, I have several openFrameworks apps installed. The androidPolygonExample is highlighted above.

2. To show only errors on Logcat run:

$ adb logcat *:E

If you then open any application, only the errors will be displayed as logs.

3. Finally, if you use the “ofLogNotice()” command in openFrameworks you can log specific messages to Logcat. Use this function in your openFrameworks application files (you can replace “testApp.cpp” with whatever you’d like):

ofLogNotice("testApp.cpp") << "I'm outputting a test message";

And then use the following command within the Terminal to only log the messages from your app:

$ adb -d logcat testApp.cpp:I *:S

Hope you found these instructions helpful in getting you going with openFrameworks on Android. If you got stuck somewhere or found anything confusing please leave a comment below. Happy coding!

Many thanks to Jonas Jongejan for proofreading and editing this tutorial.

Note 1: Unfortunately three of the Android examples in the OF folder won’t currently work for you given a problem with the OF build. androidOpenCVExample, androidOpenCVFaceExample, and androidAssimpExample will be fixed soon

Note 2: When creating new projects you might have issues compiling if your project name has dashes or hyphens (i.e. a package name of “cc.openframeworks.example-android” will not compile). The project generator should prevent you from creating projects with dashes/hyphens but if that’s not the case try tweaking the name and see if it solves your issue.