docs/README-android.md
author Ozkan Sezer
Thu, 21 Nov 2019 11:50:50 +0300
changeset 13267 a8e016c00f2e
parent 13006 4a410f099040
permissions -rw-r--r--
ran gendynapi.pl after newly added SDL_string.c functions.
slouken@10486
     1
Android
gabomdq@9023
     2
================================================================================
gabomdq@9023
     3
slouken@11328
     4
Matt Styles wrote a tutorial on building SDL for Android with Visual Studio:
slouken@11328
     5
http://trederia.blogspot.de/2017/03/building-sdl2-for-android-with-visual.html
slouken@11328
     6
slouken@11659
     7
The rest of this README covers the Android gradle style build process.
slouken@11659
     8
slouken@11659
     9
If you are using the older ant build process, it is no longer officially
slouken@11659
    10
supported, but you can use the "android-project-ant" directory as a template.
slouken@11647
    11
slouken@11328
    12
slouken@11328
    13
================================================================================
slouken@11328
    14
 Requirements
slouken@11328
    15
================================================================================
gabomdq@9023
    16
slouken@12141
    17
Android SDK (version 26 or later)
icculus@10891
    18
https://developer.android.com/sdk/index.html
gabomdq@9023
    19
slouken@12141
    20
Android NDK r15c or later
icculus@10891
    21
https://developer.android.com/tools/sdk/ndk/index.html
gabomdq@9023
    22
slouken@12532
    23
Minimum API level supported by SDL: 16 (Android 4.1)
gabomdq@9023
    24
slouken@11647
    25
gabomdq@9023
    26
================================================================================
gabomdq@9023
    27
 How the port works
gabomdq@9023
    28
================================================================================
gabomdq@9023
    29
gabomdq@9023
    30
- Android applications are Java-based, optionally with parts written in C
gabomdq@9023
    31
- As SDL apps are C-based, we use a small Java shim that uses JNI to talk to 
philipp@9066
    32
  the SDL library
gabomdq@9023
    33
- This means that your application C code must be placed inside an Android 
philipp@9066
    34
  Java project, along with some C support code that communicates with Java
gabomdq@9023
    35
- This eventually produces a standard Android .apk package
gabomdq@9023
    36
gabomdq@9023
    37
The Android Java code implements an "Activity" and can be found in:
slouken@11647
    38
android-project/app/src/main/java/org/libsdl/app/SDLActivity.java
gabomdq@9023
    39
gabomdq@9023
    40
The Java code loads your game code, the SDL shared library, and
gabomdq@9023
    41
dispatches to native functions implemented in the SDL library:
gabomdq@9023
    42
src/core/android/SDL_android.c
gabomdq@9023
    43
gabomdq@9023
    44
gabomdq@9023
    45
================================================================================
gabomdq@9023
    46
 Building an app
gabomdq@9023
    47
================================================================================
gabomdq@9023
    48
gabomdq@9023
    49
For simple projects you can use the script located at build-scripts/androidbuild.sh
gabomdq@9023
    50
gabomdq@9023
    51
There's two ways of using it:
gabomdq@9023
    52
philipp@9066
    53
    androidbuild.sh com.yourcompany.yourapp < sources.list
philipp@9066
    54
    androidbuild.sh com.yourcompany.yourapp source1.c source2.c ...sourceN.c
gabomdq@9023
    55
gabomdq@9023
    56
sources.list should be a text file with a source file name in each line
gabomdq@9023
    57
Filenames should be specified relative to the current directory, for example if
gabomdq@9023
    58
you are in the build-scripts directory and want to create the testgles.c test, you'll
gabomdq@9023
    59
run:
philipp@9066
    60
philipp@9066
    61
    ./androidbuild.sh org.libsdl.testgles ../test/testgles.c
gabomdq@9023
    62
gabomdq@9023
    63
One limitation of this script is that all sources provided will be aggregated into
gabomdq@9023
    64
a single directory, thus all your source files should have a unique name.
gabomdq@9023
    65
gabomdq@9023
    66
Once the project is complete the script will tell you where the debug APK is located.
gabomdq@9023
    67
If you want to create a signed release APK, you can use the project created by this
gabomdq@9023
    68
utility to generate it.
gabomdq@9023
    69
gabomdq@9023
    70
Finally, a word of caution: re running androidbuild.sh wipes any changes you may have
gabomdq@9023
    71
done in the build directory for the app!
gabomdq@9023
    72
gabomdq@9023
    73
gabomdq@9023
    74
For more complex projects, follow these instructions:
gabomdq@9023
    75
    
gabomdq@9023
    76
1. Copy the android-project directory wherever you want to keep your projects
gabomdq@9023
    77
   and rename it to the name of your project.
slouken@11647
    78
2. Move or symlink this SDL directory into the "<project>/app/jni" directory
slouken@11647
    79
3. Edit "<project>/app/jni/src/Android.mk" to include your source files
gabomdq@9023
    80
slouken@12364
    81
4a. If you want to use Android Studio, simply open your <project> directory and start building.
philipp@9066
    82
slouken@12364
    83
4b. If you want to build manually, run './gradlew installDebug' in the project directory. This compiles the .java, creates an .apk with the native code embedded, and installs it on any connected Android device
gabomdq@9023
    84
sylvain@13006
    85
sylvain@13006
    86
If you already have a project that uses CMake, the instructions change somewhat:
sylvain@13006
    87
sylvain@13006
    88
1. Do points 1 and 2 from the instruction above.
sylvain@13006
    89
2. Edit "<project>/app/build.gradle" to comment out or remove sections containing ndk-build
sylvain@13006
    90
   and uncomment the cmake sections. Add arguments to the CMake invocation as needed.
sylvain@13006
    91
3. Edit "<project>/app/jni/CMakeLists.txt" to include your project (it defaults to
sylvain@13006
    92
   adding the "src" subdirectory). Note that you'll have SDL2, SDL2main and SDL2-static
sylvain@13006
    93
   as targets in your project, so you should have "target_link_libraries(yourgame SDL2 SDL2main)"
sylvain@13006
    94
   in your CMakeLists.txt file. Also be aware that you should use add_library() instead of
sylvain@13006
    95
   add_executable() for the target containing your "main" function.
sylvain@13006
    96
sylvain@13006
    97
If you wish to use Android Studio, you can skip the last step.
sylvain@13006
    98
sylvain@13006
    99
4. Run './gradlew installDebug' or './gradlew installRelease' in the project directory. It will build and install your .apk on any
sylvain@13006
   100
   connected Android device
sylvain@13006
   101
gabomdq@9023
   102
Here's an explanation of the files in the Android project, so you can customize them:
gabomdq@9023
   103
slouken@11647
   104
    android-project/app
slouken@11647
   105
        build.gradle            - build info including the application version and SDK
slouken@12364
   106
        src/main/AndroidManifest.xml	- package manifest. Among others, it contains the class name of the main Activity and the package name of the application.
philipp@9055
   107
        jni/			- directory holding native code
slouken@11647
   108
        jni/Application.mk	- Application JNI settings, including target platform and STL library
slouken@11647
   109
        jni/Android.mk		- Android makefile that can call recursively the Android.mk files in all subdirectories
sylvain@13006
   110
        jni/CMakeLists.txt	- Top-level CMake project that adds SDL as a subproject
philipp@9055
   111
        jni/SDL/		- (symlink to) directory holding the SDL library files
philipp@9055
   112
        jni/SDL/Android.mk	- Android makefile for creating the SDL shared library
philipp@9055
   113
        jni/src/		- directory holding your C/C++ source
slouken@11647
   114
        jni/src/Android.mk	- Android makefile that you should customize to include your source code and any library references
sylvain@13006
   115
        jni/src/CMakeLists.txt	- CMake file that you may customize to include your source code and any library references
slouken@11647
   116
        src/main/assets/	- directory holding asset files for your application
slouken@11647
   117
        src/main/res/		- directory holding resources for your application
slouken@11647
   118
        src/main/res/mipmap-*	- directories holding icons for different phone hardware
slouken@11647
   119
        src/main/res/values/strings.xml	- strings used in your application, including the application name
slouken@11647
   120
        src/main/java/org/libsdl/app/SDLActivity.java - the Java class handling the initialization and binding to SDL. Be very careful changing this, as the SDL library relies on this implementation. You should instead subclass this for your application.
gabomdq@9023
   121
gabomdq@9023
   122
gabomdq@9023
   123
================================================================================
gabomdq@9023
   124
 Customizing your application name
gabomdq@9023
   125
================================================================================
gabomdq@9023
   126
gabomdq@9023
   127
To customize your application name, edit AndroidManifest.xml and replace
gabomdq@9023
   128
"org.libsdl.app" with an identifier for your product package.
gabomdq@9023
   129
gabomdq@9023
   130
Then create a Java class extending SDLActivity and place it in a directory
gabomdq@9023
   131
under src matching your package, e.g.
philipp@9055
   132
philipp@9066
   133
    src/com/gamemaker/game/MyGame.java
gabomdq@9023
   134
gabomdq@9023
   135
Here's an example of a minimal class file:
gabomdq@9023
   136
philipp@9050
   137
    --- MyGame.java --------------------------
philipp@9050
   138
    package com.gamemaker.game;
philipp@9050
   139
    
philipp@9050
   140
    import org.libsdl.app.SDLActivity; 
philipp@9050
   141
    
philipp@9065
   142
    /**
philipp@9050
   143
     * A sample wrapper class that just calls SDLActivity 
philipp@9050
   144
     */ 
philipp@9050
   145
    
philipp@9050
   146
    public class MyGame extends SDLActivity { }
philipp@9050
   147
    
philipp@9050
   148
    ------------------------------------------
gabomdq@9023
   149
gabomdq@9023
   150
Then replace "SDLActivity" in AndroidManifest.xml with the name of your
gabomdq@9023
   151
class, .e.g. "MyGame"
gabomdq@9023
   152
slouken@11647
   153
gabomdq@9023
   154
================================================================================
gabomdq@9023
   155
 Customizing your application icon
gabomdq@9023
   156
================================================================================
gabomdq@9023
   157
gabomdq@9023
   158
Conceptually changing your icon is just replacing the "ic_launcher.png" files in
slouken@11647
   159
the drawable directories under the res directory. There are several directories
slouken@11647
   160
for different screen sizes.
gabomdq@9023
   161
gabomdq@9023
   162
gabomdq@9023
   163
================================================================================
gabomdq@9023
   164
 Loading assets
gabomdq@9023
   165
================================================================================
gabomdq@9023
   166
slouken@11647
   167
Any files you put in the "app/src/main/assets" directory of your project
slouken@11647
   168
directory will get bundled into the application package and you can load
slouken@11647
   169
them using the standard functions in SDL_rwops.h.
gabomdq@9023
   170
gabomdq@9023
   171
There are also a few Android specific functions that allow you to get other
gabomdq@9023
   172
useful paths for saving and loading data:
philipp@9066
   173
* SDL_AndroidGetInternalStoragePath()
philipp@9066
   174
* SDL_AndroidGetExternalStorageState()
philipp@9066
   175
* SDL_AndroidGetExternalStoragePath()
gabomdq@9023
   176
gabomdq@9023
   177
See SDL_system.h for more details on these functions.
gabomdq@9023
   178
gabomdq@9023
   179
The asset packaging system will, by default, compress certain file extensions.
gabomdq@9023
   180
SDL includes two asset file access mechanisms, the preferred one is the so
gabomdq@9023
   181
called "File Descriptor" method, which is faster and doesn't involve the Dalvik
gabomdq@9023
   182
GC, but given this method does not work on compressed assets, there is also the
gabomdq@9023
   183
"Input Stream" method, which is automatically used as a fall back by SDL. You
gabomdq@9023
   184
may want to keep this fact in mind when building your APK, specially when large
gabomdq@9023
   185
files are involved.
gabomdq@9023
   186
For more information on which extensions get compressed by default and how to
gabomdq@9023
   187
disable this behaviour, see for example:
gabomdq@9023
   188
    
gabomdq@9023
   189
http://ponystyle.com/blog/2010/03/26/dealing-with-asset-compression-in-android-apps/
gabomdq@9023
   190
slouken@11647
   191
gabomdq@9023
   192
================================================================================
gabomdq@9023
   193
 Pause / Resume behaviour
gabomdq@9023
   194
================================================================================
gabomdq@9023
   195
sylvain@12693
   196
If SDL_HINT_ANDROID_BLOCK_ON_PAUSE hint is set (the default),
gabomdq@9023
   197
the event loop will block itself when the app is paused (ie, when the user
gabomdq@9023
   198
returns to the main Android dashboard). Blocking is better in terms of battery
gabomdq@9023
   199
use, and it allows your app to spring back to life instantaneously after resume
gabomdq@9023
   200
(versus polling for a resume message).
gabomdq@9023
   201
gabomdq@9023
   202
Upon resume, SDL will attempt to restore the GL context automatically.
gabomdq@9023
   203
In modern devices (Android 3.0 and up) this will most likely succeed and your
gabomdq@9023
   204
app can continue to operate as it was.
gabomdq@9023
   205
gabomdq@9023
   206
However, there's a chance (on older hardware, or on systems under heavy load),
gabomdq@9023
   207
where the GL context can not be restored. In that case you have to listen for
gabomdq@9023
   208
a specific message, (which is not yet implemented!) and restore your textures
gabomdq@9023
   209
manually or quit the app (which is actually the kind of behaviour you'll see
gabomdq@9023
   210
under iOS, if the OS can not restore your GL context it will just kill your app)
gabomdq@9023
   211
slouken@11647
   212
gabomdq@9023
   213
================================================================================
gabomdq@9023
   214
 Threads and the Java VM
gabomdq@9023
   215
================================================================================
gabomdq@9023
   216
gabomdq@9023
   217
For a quick tour on how Linux native threads interoperate with the Java VM, take
icculus@10891
   218
a look here: https://developer.android.com/guide/practices/jni.html
philipp@9066
   219
gabomdq@9023
   220
If you want to use threads in your SDL app, it's strongly recommended that you
gabomdq@9023
   221
do so by creating them using SDL functions. This way, the required attach/detach
gabomdq@9023
   222
handling is managed by SDL automagically. If you have threads created by other
gabomdq@9023
   223
means and they make calls to SDL functions, make sure that you call
philipp@9065
   224
Android_JNI_SetupThread() before doing anything else otherwise SDL will attach
gabomdq@9023
   225
your thread automatically anyway (when you make an SDL call), but it'll never
gabomdq@9023
   226
detach it.
gabomdq@9023
   227
slouken@11647
   228
gabomdq@9023
   229
================================================================================
gabomdq@9023
   230
 Using STL
gabomdq@9023
   231
================================================================================
gabomdq@9023
   232
gabomdq@9023
   233
You can use STL in your project by creating an Application.mk file in the jni
gabomdq@9023
   234
folder and adding the following line:
philipp@9066
   235
slouken@12364
   236
    APP_STL := c++_shared
gabomdq@9023
   237
slouken@12364
   238
For more information go here:
slouken@12364
   239
	https://developer.android.com/ndk/guides/cpp-support
gabomdq@9023
   240
gabomdq@9023
   241
gabomdq@9023
   242
================================================================================
gabomdq@9023
   243
 Using the emulator
gabomdq@9023
   244
================================================================================
gabomdq@9023
   245
gabomdq@9023
   246
There are some good tips and tricks for getting the most out of the
icculus@10891
   247
emulator here: https://developer.android.com/tools/devices/emulator.html
gabomdq@9023
   248
gabomdq@9023
   249
Especially useful is the info on setting up OpenGL ES 2.0 emulation.
gabomdq@9023
   250
gabomdq@9023
   251
Notice that this software emulator is incredibly slow and needs a lot of disk space.
gabomdq@9023
   252
Using a real device works better.
gabomdq@9023
   253
slouken@11647
   254
gabomdq@9023
   255
================================================================================
gabomdq@9023
   256
 Troubleshooting
gabomdq@9023
   257
================================================================================
gabomdq@9023
   258
gabomdq@9023
   259
You can see if adb can see any devices with the following command:
philipp@9055
   260
philipp@9066
   261
    adb devices
gabomdq@9023
   262
gabomdq@9023
   263
You can see the output of log messages on the default device with:
philipp@9055
   264
philipp@9066
   265
    adb logcat
gabomdq@9023
   266
gabomdq@9023
   267
You can push files to the device with:
philipp@9055
   268
philipp@9066
   269
    adb push local_file remote_path_and_file
gabomdq@9023
   270
gabomdq@9023
   271
You can push files to the SD Card at /sdcard, for example:
philipp@9055
   272
philipp@9066
   273
    adb push moose.dat /sdcard/moose.dat
gabomdq@9023
   274
gabomdq@9023
   275
You can see the files on the SD card with a shell command:
philipp@9055
   276
philipp@9066
   277
    adb shell ls /sdcard/
gabomdq@9023
   278
gabomdq@9023
   279
You can start a command shell on the default device with:
philipp@9055
   280
philipp@9066
   281
    adb shell
gabomdq@9023
   282
gabomdq@9023
   283
You can remove the library files of your project (and not the SDL lib files) with:
philipp@9055
   284
philipp@9066
   285
    ndk-build clean
gabomdq@9023
   286
gabomdq@9023
   287
You can do a build with the following command:
philipp@9055
   288
philipp@9066
   289
    ndk-build
gabomdq@9023
   290
gabomdq@9023
   291
You can see the complete command line that ndk-build is using by passing V=1 on the command line:
philipp@9055
   292
philipp@9066
   293
    ndk-build V=1
gabomdq@9023
   294
slouken@12364
   295
If your application crashes in native code, you can use ndk-stack to get a symbolic stack trace:
slouken@12364
   296
	https://developer.android.com/ndk/guides/ndk-stack
slouken@12364
   297
slouken@12364
   298
If you want to go through the process manually, you can use addr2line to convert the
gabomdq@9023
   299
addresses in the stack trace to lines in your code.
gabomdq@9023
   300
gabomdq@9023
   301
For example, if your crash looks like this:
philipp@9050
   302
philipp@9050
   303
    I/DEBUG   (   31): signal 11 (SIGSEGV), code 2 (SEGV_ACCERR), fault addr 400085d0
philipp@9050
   304
    I/DEBUG   (   31):  r0 00000000  r1 00001000  r2 00000003  r3 400085d4
philipp@9050
   305
    I/DEBUG   (   31):  r4 400085d0  r5 40008000  r6 afd41504  r7 436c6a7c
philipp@9050
   306
    I/DEBUG   (   31):  r8 436c6b30  r9 435c6fb0  10 435c6f9c  fp 4168d82c
philipp@9050
   307
    I/DEBUG   (   31):  ip 8346aff0  sp 436c6a60  lr afd1c8ff  pc afd1c902  cpsr 60000030
philipp@9050
   308
    I/DEBUG   (   31):          #00  pc 0001c902  /system/lib/libc.so
philipp@9050
   309
    I/DEBUG   (   31):          #01  pc 0001ccf6  /system/lib/libc.so
philipp@9050
   310
    I/DEBUG   (   31):          #02  pc 000014bc  /data/data/org.libsdl.app/lib/libmain.so
philipp@9050
   311
    I/DEBUG   (   31):          #03  pc 00001506  /data/data/org.libsdl.app/lib/libmain.so
gabomdq@9023
   312
gabomdq@9023
   313
You can see that there's a crash in the C library being called from the main code.
gabomdq@9023
   314
I run addr2line with the debug version of my code:
philipp@9055
   315
philipp@9066
   316
    arm-eabi-addr2line -C -f -e obj/local/armeabi/libmain.so
philipp@9055
   317
gabomdq@9023
   318
and then paste in the number after "pc" in the call stack, from the line that I care about:
gabomdq@9023
   319
000014bc
gabomdq@9023
   320
gabomdq@9023
   321
I get output from addr2line showing that it's in the quit function, in testspriteminimal.c, on line 23.
gabomdq@9023
   322
gabomdq@9023
   323
You can add logging to your code to help show what's happening:
gabomdq@9023
   324
philipp@9055
   325
    #include <android/log.h>
philipp@9055
   326
    
philipp@9055
   327
    __android_log_print(ANDROID_LOG_INFO, "foo", "Something happened! x = %d", x);
gabomdq@9023
   328
gabomdq@9023
   329
If you need to build without optimization turned on, you can create a file called
gabomdq@9023
   330
"Application.mk" in the jni directory, with the following line in it:
philipp@9066
   331
philipp@9066
   332
    APP_OPTIM := debug
gabomdq@9023
   333
gabomdq@9023
   334
gabomdq@9023
   335
================================================================================
gabomdq@9023
   336
 Memory debugging
gabomdq@9023
   337
================================================================================
gabomdq@9023
   338
gabomdq@9023
   339
The best (and slowest) way to debug memory issues on Android is valgrind.
gabomdq@9023
   340
Valgrind has support for Android out of the box, just grab code using:
philipp@9055
   341
philipp@9066
   342
    svn co svn://svn.valgrind.org/valgrind/trunk valgrind
philipp@9055
   343
gabomdq@9023
   344
... and follow the instructions in the file README.android to build it.
gabomdq@9023
   345
gabomdq@9023
   346
One thing I needed to do on Mac OS X was change the path to the toolchain,
gabomdq@9023
   347
and add ranlib to the environment variables:
gabomdq@9023
   348
export RANLIB=$NDKROOT/toolchains/arm-linux-androideabi-4.4.3/prebuilt/darwin-x86/bin/arm-linux-androideabi-ranlib
gabomdq@9023
   349
gabomdq@9023
   350
Once valgrind is built, you can create a wrapper script to launch your
gabomdq@9023
   351
application with it, changing org.libsdl.app to your package identifier:
philipp@9050
   352
philipp@9050
   353
    --- start_valgrind_app -------------------
philipp@9050
   354
    #!/system/bin/sh
philipp@9050
   355
    export TMPDIR=/data/data/org.libsdl.app
philipp@9050
   356
    exec /data/local/Inst/bin/valgrind --log-file=/sdcard/valgrind.log --error-limit=no $*
philipp@9050
   357
    ------------------------------------------
gabomdq@9023
   358
gabomdq@9023
   359
Then push it to the device:
philipp@9055
   360
philipp@9066
   361
    adb push start_valgrind_app /data/local
gabomdq@9023
   362
gabomdq@9023
   363
and make it executable:
philipp@9055
   364
philipp@9066
   365
    adb shell chmod 755 /data/local/start_valgrind_app
gabomdq@9023
   366
gabomdq@9023
   367
and tell Android to use the script to launch your application:
philipp@9055
   368
philipp@9066
   369
    adb shell setprop wrap.org.libsdl.app "logwrapper /data/local/start_valgrind_app"
gabomdq@9023
   370
gabomdq@9023
   371
If the setprop command says "could not set property", it's likely that
gabomdq@9023
   372
your package name is too long and you should make it shorter by changing
gabomdq@9023
   373
AndroidManifest.xml and the path to your class file in android-project/src
gabomdq@9023
   374
gabomdq@9023
   375
You can then launch your application normally and waaaaaaaiiittt for it.
gabomdq@9023
   376
You can monitor the startup process with the logcat command above, and
gabomdq@9023
   377
when it's done (or even while it's running) you can grab the valgrind
gabomdq@9023
   378
output file:
philipp@9055
   379
philipp@9066
   380
    adb pull /sdcard/valgrind.log
gabomdq@9023
   381
gabomdq@9023
   382
When you're done instrumenting with valgrind, you can disable the wrapper:
philipp@9055
   383
philipp@9066
   384
    adb shell setprop wrap.org.libsdl.app ""
gabomdq@9023
   385
slouken@11647
   386
gabomdq@9023
   387
================================================================================
slouken@10487
   388
 Graphics debugging
slouken@10487
   389
================================================================================
slouken@10487
   390
philipp@10543
   391
If you are developing on a compatible Tegra-based tablet, NVidia provides
slouken@11647
   392
Tegra Graphics Debugger at their website. Because SDL2 dynamically loads EGL
philipp@10543
   393
and GLES libraries, you must follow their instructions for installing the
slouken@11647
   394
interposer library on a rooted device. The non-rooted instructions are not
philipp@10543
   395
compatible with applications that use SDL2 for video.
slouken@10487
   396
slouken@10487
   397
The Tegra Graphics Debugger is available from NVidia here:
slouken@10487
   398
https://developer.nvidia.com/tegra-graphics-debugger
slouken@10487
   399
slouken@11647
   400
slouken@10487
   401
================================================================================
slouken@12532
   402
 Why is API level 16 the minimum required?
gabomdq@9023
   403
================================================================================
gabomdq@9023
   404
slouken@12532
   405
The latest NDK toolchain doesn't support targeting earlier than API level 16.
icculus@10891
   406
As of this writing, according to https://developer.android.com/about/dashboards/index.html
slouken@12532
   407
about 99% of the Android devices accessing Google Play support API level 16 or
slouken@12532
   408
higher (January 2018).
gabomdq@9023
   409
slouken@11647
   410
gabomdq@9023
   411
================================================================================
gabomdq@9023
   412
 A note regarding the use of the "dirty rectangles" rendering technique
gabomdq@9023
   413
================================================================================
gabomdq@9023
   414
gabomdq@9023
   415
If your app uses a variation of the "dirty rectangles" rendering technique,
gabomdq@9023
   416
where you only update a portion of the screen on each frame, you may notice a
gabomdq@9023
   417
variety of visual glitches on Android, that are not present on other platforms.
gabomdq@9023
   418
This is caused by SDL's use of EGL as the support system to handle OpenGL ES/ES2
gabomdq@9023
   419
contexts, in particular the use of the eglSwapBuffers function. As stated in the
gabomdq@9023
   420
documentation for the function "The contents of ancillary buffers are always 
gabomdq@9023
   421
undefined after calling eglSwapBuffers".
gabomdq@9023
   422
Setting the EGL_SWAP_BEHAVIOR attribute of the surface to EGL_BUFFER_PRESERVED
gabomdq@9023
   423
is not possible for SDL as it requires EGL 1.4, available only on the API level
gabomdq@9023
   424
17+, so the only workaround available on this platform is to redraw the entire
gabomdq@9023
   425
screen each frame.
gabomdq@9023
   426
gabomdq@9023
   427
Reference: http://www.khronos.org/registry/egl/specs/EGLTechNote0001.html
gabomdq@9023
   428
slouken@11647
   429
gabomdq@9023
   430
================================================================================
sylvain@12487
   431
 Ending your application
sylvain@12487
   432
================================================================================
sylvain@12487
   433
sylvain@12487
   434
Two legitimate ways:
sylvain@12487
   435
sylvain@12487
   436
- return from your main() function. Java side will automatically terminate the
sylvain@12487
   437
Activity by calling Activity.finish().
sylvain@12487
   438
sylvain@12487
   439
- Android OS can decide to terminate your application by calling onDestroy()
sylvain@12487
   440
(see Activity life cycle). Your application will receive a SDL_QUIT event you 
sylvain@12487
   441
can handle to save things and quit.
sylvain@12487
   442
sylvain@12487
   443
Don't call exit() as it stops the activity badly.
sylvain@12487
   444
sylvain@12487
   445
NB: "Back button" can be handled as a SDL_KEYDOWN/UP events, with Keycode
sylvain@12487
   446
SDLK_AC_BACK, for any purpose.
sylvain@12487
   447
sylvain@12487
   448
================================================================================
gabomdq@9023
   449
 Known issues
gabomdq@9023
   450
================================================================================
gabomdq@9023
   451
gabomdq@9023
   452
- The number of buttons reported for each joystick is hardcoded to be 36, which
gabomdq@9023
   453
is the current maximum number of buttons Android can report.
gabomdq@9023
   454