Android + OpenGL ES 3 Example

[zmertens]

The goal of this PR is to build and run an implementation of "Dear ImGui" on Android using SDL bindings/impl and the the OpenGL3 impl.

Here are some important points I've learned since working on this:

• SDL already has an Android bootstrap project in it's repository
• In imgui/examples/example_android_sdl there is a setup script included that calls wget to get SDL2 tarball and copies necessary files into the directory (carefully using -rn not to clobber existing files)
• The existing files within the directory contain mostly Android makefiles, manifests, and Gradle build scripts which are necessary for distinguishing the "Dear ImGui" package and configurations.
• The most relevant file is the .../example_android_sdl_gles3/app/jni/src/DearImGuiDemo.cpp which is pretty much the same as all the other DearImGui examples.
• You can probably drop down to OpenGLES2 by just grabbing the imgui_impl_opengl2 file and changing the numbers; I say probably because there's always a gotcha somewhere!
• This example does not contain keyboard or voice input or any of that fancy stuff, but I can attest to using keyboard input by adding SDL_StartTextInput and updating AndroidManifest.xml
• I would love to hear some ideas on easily fitting the gui to a mobile device (emphasis on easy!)

Android Screenshot

[ocornut]

Thanks! Will look at it when I have time.

[sabotage3d]

Hi guys I cannot find the android example in the repository. Can someone share it please?

[ocornut]

Search for "Android" on github I believe there is (unsupported) example for it.

On 11 Aug 2016, at 15:15, sabotage3d notifications@github.com wrote:

Hi guys I cannot find the android example in the repository. Can someone share it please?

―
You are receiving this because you commented.
Reply to this email directly, view it on GitHub, or mute the thread.

[zmertens]

@sabotage3d here is the link to my branch. It's a very quick example, as the GUI itself is not tailored for mobile (meaning you won't really have much fun typing stuff in or selecting the widgets).

[kingofoz]

hello,
Is Android supported by imgui?

[ocornut]

@kingofoz dear imgui is completely system agnostic and works everywhere. You just need to wire inputs and render textures triangles, which all Android devices are able to.

[elect86]

If interested, I'm working on a jvm port

[ice1000]

What's the current status of this pr?

[ocornut]

@ice1000 This is too old, has too many unrelated and unjustified files*, and would need to be rewritten for the refactored examples. Essentially the core of it is just SDL + OpenGL so we could adapt the existing example e.g. example_sdl_opengl3 and finish adapting the renderer (#1941,#1900,#336), or create a new project example_android_sdl_opengl3/main.cpp using existing bindings if needed.

* things like that and other files which probably have no reason to be here.

[ocornut]

People coming to this link in 2018:
Note with the current examples/ infrastructure you should be able to use imgui_impl_opengl3.cpp directly. Minor patches may be welcome to support GL ES 2.

An actual Android example will minimum cruft/bloat would be nice.

[zmertens]

An actual Android example will minimum cruft/bloat would be nice.

I'm going to play around and see if I can come up with something that works better on mobile and doesn't have to rely on Android Studio if that's possible.

Update: I'm having some trouble minimizing the project structure. Right now it relies on using Android Studio to build the APK file, and the SDL library for the foundation. My problem at the moment is that I don't know how to shrink the size of the Android Studio project or how to build an APK file without Android Studio and export it to the device. I was thinking of trying to run a script that pulls down a project template from the web and pasting in the ImGui/Main.cpp files but I don't know if that's the right approach or where to find a project template.

Another idea I had, is creating a JS module using Emscripten and then using React Native to load the module and pass over the GL context or something, but I think that may be even more complicated and unnecessary.

[ice1000]

@zmertens Tests and Android Studio config files can be removed. Resources can be removed, icons can be removed.
After that you'll get less than 10 files left, which is probably acceptable.

[ice1000]

.gradle is also unnecessary.

[zmertens]

@ice1000 Good idea. I really would miss the launcher icon but it's no biggy.

I figured out that with the recent SDL2-2.0.9 that you can just use the command line to build the Android project, so Android Studio isn't even required but it does make things easier.
I updated the examples/README.txt with guidelines on how to set up your environment to build and run on a device.

I started to put together a BASH script which pulls down SDL into the android_sdl_example directory and then copies the nested android-project into the examples directory. I held off on finishing it because it started getting too complex and messy, but the basic idea is copy/replace/update what's in the SDL android-project with only the salient files and code.

I updated the sdl2 and opengl3 impl files from the sdl2_gles2 impl which doesn't appear to even be in the examples anymore. In doing so I can no longer receive touch input when I run it on Android. I need to start debugging that.

The last thing I think to make it a minimal and complete example is to make it more mobile friendly. I figure I can look at the ios example but that doesn't appear to be here anymore.

[ice1000]

the ios example is inside metal one

[zmertens]

I think I have minimized the project structure without making it too complicated. Here are some important notes on the progress:

• The example for the android project is example_android_sdl_gles3
• It uses a BASH script examples/build_android.sh which pulls down the SDL2 tarball and copies the bloat files into example_android_sdl_gles3, creates a symbolic link to the SDL project.
• I updated examples/README.txt for the important part about download Android SDK/NDK/Studio
• I updated the examples/.gitignore to keep the updated android project files and ignore SDL

The example itself is coming along nicely I think. I'm adapting a Julia fractal example from OpenGL Superbible. Right now there's no touch input though, and I'm not sure why, so I'm working on that. Once I have that I'll update the GUI itself. It will probably be a simple overlay that can be minimized in some way.

[ocornut]

The Julia Fractal code is also unnecessary. It is best to model this as close as possible to the existing example (down to the filenames/commments)

[zmertens]

I have updated the code and it's now working like the original PR with minimal files, current imgui and impl files (on my device: MotoG3, Android 6.0 (Nougat). I haven't done any testing on iOS.

• Add 2 preprocessor checks for __ANDROID__ in imgui_impl_sdl.cpp This has already been addressed

• SDL reports an error "SDL/ERROR: That operation is not supported" during SDL_Init , but it doesn't seem to cause any major issues

• Still working on playing with the styling flags to try and get the GUI fit within mobile

• Important note: the android project taken from the SDL library uses a org.libsdl.app as default package. This means if you install this demo it could overwrite any other app with that package name (an SDL2 android demo, for instance).

@ice1000 Do you know if its possible to change the position of the demo window? It looks hardcoded in the imgui_demo.cpp file:

    // We specify a default position/size in case there's no data in the .ini file. Typically this isn't required! We only do it to make the Demo applications a little more welcoming.
    ImGui::SetNextWindowPos(ImVec2(650, 20), ImGuiCond_FirstUseEver);
    ImGui::SetNextWindowSize(ImVec2(550, 680), ImGuiCond_FirstUseEver);

[ocornut]

First off, sincere apologies for not investigating this PR further when you made and updated it. Android being unknown territory for me doesn't help but shouldn't be an excuse, especially as you made the effort to vastly improve it from the first draft.

Through #3446 we added a native Android backend and an example accordingly.
I think I prefer to direct people to be using SDL so it's both more portable and give us less maintenance, so I think there's value in this PR compared to using a native Android thing.

If you think there's value in this PR in light to #3446, may I suggest you squash and force-push it into a single commit (rather than the current 69 commits) so at least it becomes a reference for other users. It is already pretty self contained since you refactored it so I don't imagine there will be any conflict involved. I would also take the occasion to rename the folder to example_android_sdl_opengl3 even though the gles3 is correct-er we stay consistent with other folders.

One thing to consider that may be interestingly healthier is, can we come up with a path where the existing examples that use Android-friendly tech (such as example_sdl_opengl3 or even example_sdl_vulkan) be made to work with Android?

• What are the required differences between example_sdl_opengl3/main.cpp and your main.cpp ? I would assume very little, if any, and so first we could considering merge a few Android change (under ifdef) in the existing examples?
• The io.WantSaveIniSettings = false; statement is incorrect (that's a read-only flag to allow app to save ini from memory data), the correct change to achieve desired behavior is io.IniFilename = NULL.
• Then outside of the existing main.cpp the rest is Android build cruft, which we can consider adding under that example (in a sub folder?), so the gradle etc and instructions would potentially be in example_sdl_opengl3/android/ ?

Thank you for the amazing show of patience (I'm absolutely certain this PR has been useful to other as it has been linked from the wiki for a long time)

[ocornut]

Hello @zmertens, nice to see this branch being updated :)

AFAIK your commit using regular backend would be the preferred solution nowadays (tho you can keep them in backends/ and not make local copies in example). With the current state of it your attempt to use SDL3+GL on Android may ideally be reduced into a build script for the existing example_sdl3_opengl3/ example? If you move your stuff there we can potentially better visualize the changes (if any) required to provide this build script. This is essentially same as suggested in #421 (comment) right now we every files being copy of an existing file we can't easily tell the difference. If you move them back to existing files and folder we would be able to.

[zmertens]

Hi @ocornut , thanks for the recent review, I did some squashing and reduced the repo to 3 files and the SDL3 submodule. I kept the SDL3 submodule because it has the androidbuild.sh script which is very nice and easy to generate the project and reduce footprint in the example repo.

There aren't many differences between example_sdl_opengl3/main.cpp and this, so I'll see if I can maybe borrow or steal from that and bring it over to the Android project with the setup.sh script.

Please let me know if this direction looks good or not :).

[ocornut]

The direction that would be good is not creating a new example and adding build scripts to an existing one, if that makes sense and is not an overly complicated build script.
Pulling a new library via a submodule isn’t acceptable.
We don’t really need this is very much anymore since in theory the existing backends should function on Android, but making sure the small details are functioning would be great.

[zmertens]

I did some hacking and I think I got the current Android example working with SDL3 after changing CMakeLists.txt with a flag CONFIGURE_WITH_SDL3.. These changes don't require a new example, build script, or adding new dependencies to the repo:

• Download SDL3, unzip, and copy relevant files to Gradle/Android project
• Update gitignore to ignore the unnecessary build or source files
• Add a README

[zmertens]

I think this can work as a single Makefile, similar to most of the other ImGui examples here. I can explain the new updates here:

Get SDL latest from the main branch and unpack it and then prepare the build script bundled with SDL.

        URL=https://github.com/libsdl-org/SDL/archive/refs/heads/main.zip
        ARCHIVE_NAME := SDL-main.zip
	wget -O $(ARCHIVE_NAME) $(URL) || curl -L -o $(ARCHIVE_NAME) $(URL)

This step requires Python3 and it does all the heavy lifting for generating the Android project.

	python3 $(SDL_PYTHON_SCRIPT) --variant $(VARIANT) --output $(CURDIR) $(PACKAGE_NAME) $(SOURCES)

I added the rest of the instructions in the README, but with Android Studio it's really easy to open the generated Android project from the steps above, and then update Gradle within Android Studio. The build process is 1-click after the Gradle update.

I also tested from the command-line using .\gradlew.bat installDebug and that works provided the environment variables are set and valid: JAVA_HOME, ANDROID_HOME, and ANDROID_NDK_HOME.