Add android-related example to existing SDL3 examples

examples/example_sdl3_opengl3/Makefile.android

@@ -0,0 +1,69 @@
+# Makefile to use with SDL+Android
+# See https://wiki.libsdl.org/SDL3/README/android
+# for details on how SDL interacts with Android.
+#
+# This Makefile assumes you have wget or curl and Python v3 installed.
+#
+# Running `make -f Makefile.android` will produce these files or directories:
+#  - SDL-main.zip
+#  - SDL-main
+#  - com.imgui.example
+#
+
+# Variables
+PACKAGE_NAME := com.imgui.sdl3opengl3
+VARIANT := copy
+VERSION := 0.1.0
+URL := https://github.com/libsdl-org/SDL/archive/refs/heads/main.zip
+ARCHIVE_NAME := SDL-main.zip
+SDL_ROOT := SDL-main
+CREATED_ANDROID_PROJECT := $(CURDIR)/$(PACKAGE_NAME)
+ANDROID_SRCS_DIR := $(CREATED_ANDROID_PROJECT)/app/jni/src
+SDL_PYTHON_SCRIPT := $(SDL_ROOT)/build-scripts/create-android-project.py
+IMGUI_ROOT := $(realpath $(dir $(lastword $(MAKEFILE_LIST)))../..)
+
+SOURCES := \
+	$(IMGUI_ROOT)/backends/imgui_impl_opengl3.cpp \
+	$(IMGUI_ROOT)/backends/imgui_impl_sdl3.cpp \
+	$(IMGUI_ROOT)/imgui.cpp \
+	$(IMGUI_ROOT)/imgui_draw.cpp \
+	$(IMGUI_ROOT)/imgui_widgets.cpp \
+	$(IMGUI_ROOT)/imgui_demo.cpp \
+	$(IMGUI_ROOT)/imgui_tables.cpp \
+	main.cpp
+
+HEADERS := $(IMGUI_ROOT)/imstb_rectpack.h \
+	$(IMGUI_ROOT)/imstb_textedit.h \
+	$(IMGUI_ROOT)/imstb_truetype.h \
+	$(IMGUI_ROOT)/imgui.h \
+	$(IMGUI_ROOT)/imgui_internal.h \
+	$(IMGUI_ROOT)/imconfig.h \
+	$(IMGUI_ROOT)/backends/imgui_impl_sdl3.h \
+	$(IMGUI_ROOT)/backends/imgui_impl_opengl3.h \
+    $(IMGUI_ROOT)/backends/imgui_impl_opengl3_loader.h
+
+# Targets
+.PHONY: all clean setup download extract run
+
+all: setup run
+
+clean:
+	rm -rf $(SDL_ROOT) $(ARCHIVE_NAME) $(CREATED_ANDROID_PROJECT)
+
+setup: download extract
+	@echo "Setting up the Android project..."
+	@which python3 > /dev/null || which python > /dev/null || { echo "Error: Python v3 is not installed."; exit 1;}
+
+download:
+	@echo "Downloading Android project..."
+	wget -O $(ARCHIVE_NAME) $(URL) || curl -L -o $(ARCHIVE_NAME) $(URL)
+
+extract:
+	@echo "Extracting Android project..."
+	mkdir -p $(SDL_ROOT)
+	unzip -o $(ARCHIVE_NAME) -d $(CURDIR)
+
+run:
+	@echo "Creating Android project..."
+	python3 $(SDL_PYTHON_SCRIPT) --variant $(VARIANT) --output $(CURDIR) $(PACKAGE_NAME) $(SOURCES)
+	cp -r $(HEADERS) $(ANDROID_SRCS_DIR)

examples/example_sdl3_opengl3/README.md

@@ -38,3 +38,65 @@ c++ `sdl3-config --cflags` -I .. -I ../.. -I ../../backends
 ## Emscripten
 
 As of 2023-05-30 Emscripten doesn't support SDL3 yet.
+
+## Android
+
+- You will need at least Java 9, preferably Java 17, to handle recent Gradle 8.9.x versions.
+
+- You need a way to install Android SDK and NDK and add their PATHS, and have access to a virtual device or real Android device to run the app.
+  - Android SDK version 21+
+  - Android NDK version 19+
+
+- Android Studio is an option for handling Java, Android SDK and NDK dependencies altogether: [https://developer.android.com/studio](https://developer.android.com/studio).
+
+- The provided Makefile will download SDL from the main Git branch and create an Android project using SDL's provided `create-android-project.py` script.
+
+- Run the Makefile using `make all`. It downloads and unpacks SDL, runs the included Python script, and generate a folder with the Android project in this directory. The project contains the Dear ImGui sources and SDL3 backends.
+
+- After the project is generated, the Gradle version can be automatically updated in Android Studio, or updated manually via setting the `classpath` and `distributionUrl` values.
+
+In `com.imgui.example/build.gradle`:
+```
+dependencies {
+    classpath 'com.android.tools.build:gradle:8.7.2'
+    ...
+}
+```
+
+In `com.imgui.example/gradle/wrapper/gradle-wrapper.properties`:
+```
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.9-bin.zip
+```
+
+In `com.imgui.example/app/build.grade`, update the min SDK version:
+```
+minSdkVersion 21
+```
+
+For this OpenGL3 example, add the `GLESv3` library links in `com.imgui.example/app/jni/src/Android.mk`
+```
+LOCAL_LDLIBS := -lGLESv1_CM -lGLESv2 -lGLESv3 -lOpenSLES -llog -landroid  # SDL
+```
+
+## How to Run
+
+To run on a local machine using Windows PowerShell:
+
+ 1. Run `make all` and change into the generated Android project folder, for example: `cd com.imgui.example/`
+ 2. Run `.\gradlew.bat build`  to start the Gradle Daemons and build the project. This requires the `JAVA_HOME`, `ANDROID_HOME`, and `ANDROID_NDK_HOME` environment variables if not done in Android Studio.
+     - Android Studio handles these environment variables itself
+ 3. Run `.\gradlew.bat installDebug` to install the APK package file onto an Android virtual device or a connected real device.
+
+
+## Some other notes
+
+On Windows, this variable may need to get set in the `com.imgui.sdlrenderer3/app/jni/SDL/Android.mk` file after variables are cleared.
+
+```
+include $(CLEAR_VARS)
+
+# Add this if there's Makefile error 87
+LOCAL_SHORT_COMMANDS := true
+
+LOCAL_MODULE := SDL3
+```

examples/example_sdl3_opengl3/main.cpp

@@ -23,6 +23,10 @@
 #include "../libs/emscripten/emscripten_mainloop_stub.h"
 #endif
 
+#if defined(__ANDROID__)
+#include <SDL3/SDL_main.h>
+#endif
+
 // Main code
 int main(int, char**)
 {

examples/example_android_sdlrenderer3/Makefile → examples/example_sdl3_sdlrenderer3/Makefile.android

@@ -1,13 +1,25 @@
+# Makefile to use with SDL+Android
+# See https://wiki.libsdl.org/SDL3/README/android
+# for details on how SDL interacts with Android.
+#
+# This Makefile assumes you have wget or curl and Python v3 installed.
+#
+# Running `make -f Makefile.android` will produce these files or directories:
+#  - SDL-main.zip
+#  - SDL-main
+#  - com.imgui.example
+#
+
 # Variables
-PACKAGE_NAME := com.imgui.example
+PACKAGE_NAME := com.imgui.sdl3renderer3
 VARIANT := copy
 VERSION := 0.1.0
 URL := https://github.com/libsdl-org/SDL/archive/refs/heads/main.zip
 ARCHIVE_NAME := SDL-main.zip
 SDL_ROOT := SDL-main
-SDL_ANDROID_PROJECT := $(CURDIR)/$(PACKAGE_NAME)
+CREATED_ANDROID_PROJECT := $(CURDIR)/$(PACKAGE_NAME)
+ANDROID_SRCS_DIR := $(CREATED_ANDROID_PROJECT)/app/jni/src
 SDL_PYTHON_SCRIPT := $(SDL_ROOT)/build-scripts/create-android-project.py
-SDL_JNI_DIR := $(SDL_ANDROID_PROJECT)/app/jni/src
 IMGUI_ROOT := $(realpath $(dir $(lastword $(MAKEFILE_LIST)))../..)
 
 SOURCES := \
@@ -35,7 +47,7 @@ HEADERS := $(IMGUI_ROOT)/imstb_rectpack.h \
 all: setup run
 
 clean:
-	rm -rf $(SDL_ROOT) $(ARCHIVE_NAME) $(SDL_ANDROID_PROJECT)
+	rm -rf $(SDL_ROOT) $(ARCHIVE_NAME) $(CREATED_ANDROID_PROJECT)
 
 setup: download extract
 	@echo "Setting up the Android project..."
@@ -49,9 +61,8 @@ extract:
 	@echo "Extracting Android project..."
 	mkdir -p $(SDL_ROOT)
 	unzip -o $(ARCHIVE_NAME) -d $(CURDIR)
-	cp -r $(HEADERS) $(SDL_JNI_DIR)
 
 run:
 	@echo "Creating Android project..."
 	python3 $(SDL_PYTHON_SCRIPT) --variant $(VARIANT) --output $(CURDIR) $(PACKAGE_NAME) $(SOURCES)
-
+	cp -r $(HEADERS) $(ANDROID_SRCS_DIR)