|
| 1 | +# SFML and Android |
| 2 | + |
| 3 | +## Introduction |
| 4 | + |
| 5 | +This tutorial is the first one you should read if you're using SFML on Android. |
| 6 | +It will explain how to install SFML, and compile projects that use it. |
| 7 | + |
| 8 | +!!! note |
| 9 | + |
| 10 | + The [CMake template](cmake.md) is the recommended way to get started with SFML, use the `mobile` branch to support android |
| 11 | + |
| 12 | +## Installing SFML |
| 13 | + |
| 14 | +For the best experience it's generally preferable to include SFML as part of your cmake project, which means it's not necessary to install SFML and you can use the gradle cmake support to build your project without much extra setup. This is what the android SFML examples do (`examples/projects/android` in the SFML source tree) |
| 15 | + |
| 16 | +If you do instead want to install the SFML binaries and link them from your project instead, SFML will override the install prefix when building from source so that the binaries are installed to the SDK, and you can link them from your project. There is an example of this in the SFML source tree under `examples/android` |
| 17 | + |
| 18 | +## Compiling an SFML program |
| 19 | + |
| 20 | +While it is technically possible to build native-only binaries on Android, as SFML does for it's unit tests, you can't use any windowing/graphics and aren't able to handle any user input, so for the vast majority of cases you will want to build a proper android application, which is what this tutorial covers |
| 21 | + |
| 22 | +Again, it is technically possible to build an android app without gradle or android studio, but you have to do all the app packaging yourself and it generally makes things significantly more difficult than they need to be, so this tutorial covers the simplest approach using android studio to build an app (via gradle). This also gives you an IDE and debugging for developing your android app |
| 23 | + |
| 24 | +So first, download and install [Android Studio](https://developer.android.com/studio). The latest version with a default setup should give you all the tools you need to build an SFML app. |
| 25 | + |
| 26 | +Once installed, create a new project and select native c++ |
| 27 | + |
| 28 | + |
| 29 | +In most cases the default options are fine, so just give your app a name, click next, then finish |
| 30 | + |
| 31 | + |
| 32 | +This new project will have some files that aren't necessary, so you can delete the following: |
| 33 | + |
| 34 | +- `MainActivity.kt` |
| 35 | +- `androidTest` folder |
| 36 | +- `test` folder |
| 37 | +- `res` folder |
| 38 | + |
| 39 | +Once that's done, you can sync the gradle project (It will show a warning at the top that it needs syncing, with a button you can press) which should sync successfully |
| 40 | + |
| 41 | +This template will include a basic `native-lib.cpp` file and `CMakeLists.txt` which is your c++ SFML project code. If you are porting an existing SFML app to android then you can delete these files, if not, add this block to the CMakeLists to build and link SFML to your app |
| 42 | + |
| 43 | +``` |
| 44 | +include(FetchContent) |
| 45 | +FetchContent_Declare(SFML |
| 46 | + GIT_REPOSITORY https://github.com/SFML/SFML.git |
| 47 | + GIT_TAG 3.1.0 |
| 48 | + GIT_SHALLOW ON |
| 49 | + EXCLUDE_FROM_ALL |
| 50 | + SYSTEM) |
| 51 | +FetchContent_MakeAvailable(SFML) |
| 52 | +
|
| 53 | +target_link_libraries(${CMAKE_PROJECT_NAME} SFML::Graphics SFML::Main) |
| 54 | +``` |
| 55 | + |
| 56 | +You will also need to modify the `externalNativeBuild` block in the app's gradle file to use the higher version of cmake required by SFML. If you are porting an existing SFML project this is also where you would change the path to use your existing `CMakeLists.txt` instead of the one from the template |
| 57 | + |
| 58 | +```kotlin |
| 59 | +externalNativeBuild { |
| 60 | + cmake { |
| 61 | + path = file("src/main/cpp/CMakeLists.txt") |
| 62 | + version = "3.28.0+" |
| 63 | + } |
| 64 | +} |
| 65 | +``` |
| 66 | + |
| 67 | +Now if you sync the gradle project again, it will configure your cmake project including SFML, and pressing the build button will build run the cmake build step alongside the other parts of the android build process |
| 68 | + |
| 69 | +!!! note |
| 70 | + |
| 71 | + Android does not use executables, so where you would normally `add_executable(...)` in CMake on other platforms, you must instead do `add_library(... SHARED)` for android |
| 72 | + |
| 73 | +### Activity setup |
| 74 | + |
| 75 | +The final step to create a working android app is to set up the activity. All android apps require an activity, but there is a built-in Native activity class which is useful for projects that are primarily native c++ code, and that is what SFML will hook into. |
| 76 | + |
| 77 | +To use a native activity, open the `AndroidManifest.xml` in your project and replace it with the following contents: |
| 78 | + |
| 79 | +```xml |
| 80 | +<?xml version="1.0" encoding="utf-8"?> |
| 81 | +<manifest xmlns:android="http://schemas.android.com/apk/res/android"> |
| 82 | + |
| 83 | + <application |
| 84 | + android:allowBackup="true" |
| 85 | + android:label="mysfmlapp" |
| 86 | + android:supportsRtl="true"> |
| 87 | + <activity |
| 88 | + android:name="android.app.NativeActivity" |
| 89 | + android:exported="true"> |
| 90 | + <meta-data android:name="android.app.lib_name" |
| 91 | + android:value="mysfmlapp" /> |
| 92 | + <intent-filter> |
| 93 | + <action android:name="android.intent.action.MAIN" /> |
| 94 | + |
| 95 | + <category android:name="android.intent.category.LAUNCHER" /> |
| 96 | + </intent-filter> |
| 97 | + </activity> |
| 98 | + </application> |
| 99 | + |
| 100 | +</manifest> |
| 101 | +``` |
| 102 | + |
| 103 | +`mysfmlapp` above is generated from the project name when creating the tempalte (check the `CMakeLists.txt` if you are not sure), and if you are porting an existing SFML project it should be the name of your main SFML target library (which would be the executable for other platforms) |
| 104 | + |
| 105 | +If you are creating a new project, replace the contents of `native-lib.cpp` with the following code: |
| 106 | + |
| 107 | +```cpp |
| 108 | +#include <SFML/Graphics.hpp> |
| 109 | +#include <SFML/Main.hpp> |
| 110 | + |
| 111 | +int main() |
| 112 | +{ |
| 113 | + sf::RenderWindow window(sf::VideoMode({200, 200}), "SFML works!"); |
| 114 | + sf::CircleShape shape(100.f); |
| 115 | + shape.setFillColor(sf::Color::Green); |
| 116 | + |
| 117 | + while (window.isOpen()) |
| 118 | + { |
| 119 | + while (const std::optional event = window.pollEvent()) |
| 120 | + { |
| 121 | + if (event->is<sf::Event::Closed>()) |
| 122 | + window.close(); |
| 123 | + } |
| 124 | + |
| 125 | + window.clear(); |
| 126 | + window.draw(shape); |
| 127 | + window.display(); |
| 128 | + } |
| 129 | +} |
| 130 | +``` |
| 131 | + |
| 132 | +Now you should be able to launch or debug your app on an android device or simulator, and see the green circle |
0 commit comments