README-android.txt
author David Ludwig <dludwig@pobox.com>
Wed, 25 Dec 2013 21:39:48 -0500
changeset 8563 c0e68f3b6bbb
parent 7944 f19c0aca56aa
child 8079 f8ef325265ed
permissions -rw-r--r--
WinRT: compiled the d3d11 renderer's shaders into SDL itself

Previously, the shaders would get compiled separately, the output of which would need to be packaged into the app. This change should make SDL's dll be the only binary needed to include SDL in a WinRT app.
slouken@7222
     1
================================================================================
slouken@7222
     2
Simple DirectMedia Layer for Android
slouken@7222
     3
================================================================================
slouken@7222
     4
slouken@7222
     5
Requirements:
slouken@7222
     6
gabomdq@7907
     7
Android SDK (version 12 or later)
slouken@7222
     8
http://developer.android.com/sdk/index.html
slouken@7222
     9
slouken@7222
    10
Android NDK r7 or later
slouken@7222
    11
http://developer.android.com/sdk/ndk/index.html
slouken@7222
    12
philipp@7241
    13
Minimum API level supported by SDL: 10 (Android 2.3.3)
gabomdq@7907
    14
Joystick support is available for API level >=12 devices.
slouken@7222
    15
slouken@7222
    16
================================================================================
slouken@7222
    17
 How the port works
slouken@7222
    18
================================================================================
slouken@7222
    19
slouken@7222
    20
- Android applications are Java-based, optionally with parts written in C
slouken@7222
    21
- As SDL apps are C-based, we use a small Java shim that uses JNI to talk to 
slouken@7222
    22
the SDL library
slouken@7222
    23
- This means that your application C code must be placed inside an Android 
slouken@7222
    24
Java project, along with some C support code that communicates with Java
slouken@7222
    25
- This eventually produces a standard Android .apk package
slouken@7222
    26
slouken@7222
    27
The Android Java code implements an "Activity" and can be found in:
slouken@7222
    28
android-project/src/org/libsdl/app/SDLActivity.java
slouken@7222
    29
slouken@7222
    30
The Java code loads your game code, the SDL shared library, and
slouken@7222
    31
dispatches to native functions implemented in the SDL library:
ewing@7501
    32
src/SDL_android.c
slouken@7222
    33
slouken@7222
    34
Your project must include some glue code that starts your main() routine:
ewing@7501
    35
src/main/android/SDL_android_main.c
slouken@7222
    36
slouken@7222
    37
slouken@7222
    38
================================================================================
slouken@7222
    39
 Building an app
slouken@7222
    40
================================================================================
slouken@7222
    41
gabomdq@7793
    42
For simple projects you can use the script located at build-scripts/androidbuild.sh
gabomdq@7793
    43
gabomdq@7793
    44
There's two ways of using it:
gabomdq@7793
    45
gabomdq@7793
    46
androidbuild.sh com.yourcompany.yourapp < sources.list
gabomdq@7793
    47
androidbuild.sh com.yourcompany.yourapp source1.c source2.c ...sourceN.c
gabomdq@7793
    48
gabomdq@7793
    49
sources.list should be a text file with a source file name in each line
gabomdq@7793
    50
Filenames should be specified relative to the current directory, for example if
gabomdq@7793
    51
you are in the build-scripts directory and want to create the testgles.c test, you'll
gabomdq@7793
    52
run:
gabomdq@7793
    53
    
gabomdq@7793
    54
./androidbuild.sh org.libsdl.testgles ../test/testgles.c
gabomdq@7793
    55
gabomdq@7793
    56
One limitation of this script is that all sources provided will be aggregated into
gabomdq@7793
    57
a single directory, thus all your source files should have a unique name.
gabomdq@7793
    58
gabomdq@7793
    59
Once the project is complete the script will tell you where the debug APK is located.
gabomdq@7793
    60
If you want to create a signed release APK, you can use the project created by this
gabomdq@7793
    61
utility to generate it.
gabomdq@7793
    62
gabomdq@7793
    63
Finally, a word of caution: re running androidbuild.sh wipes any changes you may have
gabomdq@7793
    64
done in the build directory for the app!
gabomdq@7793
    65
gabomdq@7793
    66
gabomdq@7793
    67
For more complex projects, follow these instructions:
gabomdq@7793
    68
    
slouken@7222
    69
1. Copy the android-project directory wherever you want to keep your projects
slouken@7222
    70
   and rename it to the name of your project.
slouken@7222
    71
2. Move or symlink this SDL directory into the <project>/jni directory
slouken@7222
    72
3. Edit <project>/jni/src/Android.mk to include your source files
slouken@7222
    73
4. Run 'ndk-build' (a script provided by the NDK). This compiles the C source
slouken@7222
    74
slouken@7222
    75
If you want to use the Eclipse IDE, skip to the Eclipse section below.
slouken@7222
    76
slouken@7222
    77
5. Create <project>/local.properties and use that to point to the Android SDK directory, by writing a line with the following form:
slouken@7222
    78
sdk.dir=PATH_TO_ANDROID_SDK
slouken@7222
    79
6. Run 'ant debug' in android/project. This compiles the .java and eventually 
slouken@7222
    80
   creates a .apk with the native code embedded
slouken@7222
    81
7. 'ant debug install' will push the apk to the device or emulator (if connected)
slouken@7222
    82
slouken@7222
    83
Here's an explanation of the files in the Android project, so you can customize them:
slouken@7222
    84
slouken@7222
    85
android-project/
slouken@7222
    86
	AndroidManifest.xml	- package manifest. Among others, it contains the class name
slouken@7222
    87
				  of the main Activity and the package name of the application.
slouken@7222
    88
	build.properties	- empty
slouken@7222
    89
	build.xml		- build description file, used by ant. The actual application name
slouken@7222
    90
				  is specified here.
slouken@7222
    91
	default.properties	- holds the target ABI for the application, android-10 and up
slouken@7222
    92
	project.properties	- holds the target ABI for the application, android-10 and up
slouken@7222
    93
	local.properties	- holds the SDK path, you should change this to the path to your SDK
slouken@7222
    94
	jni/			- directory holding native code
slouken@7222
    95
	jni/Android.mk		- Android makefile that can call recursively the Android.mk files
slouken@7222
    96
				  in all subdirectories
slouken@7222
    97
	jni/SDL/		- (symlink to) directory holding the SDL library files
slouken@7222
    98
	jni/SDL/Android.mk	- Android makefile for creating the SDL shared library
slouken@7222
    99
	jni/src/		- directory holding your C/C++ source
slouken@7222
   100
	jni/src/Android.mk	- Android makefile that you should customize to include your 
slouken@7222
   101
                                  source code and any library references
slouken@7222
   102
	res/			- directory holding resources for your application
slouken@7222
   103
	res/drawable-*		- directories holding icons for different phone hardware. Could be
slouken@7222
   104
				  one dir called "drawable".
slouken@7222
   105
	res/layout/main.xml	- Usually contains a file main.xml, which declares the screen layout.
slouken@7222
   106
				  We don't need it because we use the SDL video output.
slouken@7222
   107
	res/values/strings.xml	- strings used in your application, including the application name
slouken@7222
   108
				  shown on the phone.
slouken@7222
   109
	src/org/libsdl/app/SDLActivity.java - the Java class handling the initialization and binding
slouken@7222
   110
				  to SDL.  Be very careful changing this, as the SDL library relies
slouken@7222
   111
				  on this implementation.
slouken@7222
   112
slouken@7222
   113
slouken@7222
   114
================================================================================
slouken@7804
   115
 Build an app with static linking of libSDL
slouken@7804
   116
================================================================================
slouken@7804
   117
slouken@7804
   118
This build uses the Android NDK module system.
slouken@7804
   119
slouken@7804
   120
Instructions:
slouken@7804
   121
1. Copy the android-project directory wherever you want to keep your projects
slouken@7804
   122
   and rename it to the name of your project.
slouken@7804
   123
2. Rename <project>/jni/src/Android_static.mk to <project>/jni/src/Android.mk
slouken@7804
   124
   (overwrite the existing one)
slouken@7804
   125
3. Edit <project>/jni/src/Android.mk to include your source files
slouken@7804
   126
4. create and export an environment variable named NDK_MODULE_PATH that points
slouken@7804
   127
   to the parent directory of this SDL directory. e.g.:
slouken@7804
   128
slouken@7804
   129
   export NDK_MODULE_PATH="$PWD"/..
slouken@7804
   130
slouken@7804
   131
5. Edit <project>/src/org/libsdl/app/SDLActivity.java and remove the call to
slouken@7804
   132
   System.loadLibrary("SDL2") line 42.
slouken@7804
   133
6. Run 'ndk-build' (a script provided by the NDK). This compiles the C source
slouken@7804
   134
slouken@7804
   135
slouken@7804
   136
================================================================================
slouken@7222
   137
 Customizing your application name
slouken@7222
   138
================================================================================
slouken@7222
   139
slouken@7222
   140
To customize your application name, edit AndroidManifest.xml and replace
slouken@7222
   141
"org.libsdl.app" with an identifier for your product package.
slouken@7222
   142
slouken@7222
   143
Then create a Java class extending SDLActivity and place it in a directory
slouken@7222
   144
under src matching your package, e.g.
slouken@7222
   145
	src/com/gamemaker/game/MyGame.java
slouken@7222
   146
slouken@7222
   147
Here's an example of a minimal class file:
slouken@7222
   148
--- MyGame.java --------------------------
slouken@7222
   149
package com.gamemaker.game;
slouken@7222
   150
slouken@7222
   151
import org.libsdl.app.SDLActivity; 
slouken@7222
   152
slouken@7222
   153
/* 
slouken@7222
   154
 * A sample wrapper class that just calls SDLActivity 
slouken@7222
   155
 */ 
slouken@7222
   156
slouken@7222
   157
public class MyGame extends SDLActivity { }
slouken@7222
   158
slouken@7222
   159
------------------------------------------
slouken@7222
   160
slouken@7222
   161
Then replace "SDLActivity" in AndroidManifest.xml with the name of your
slouken@7222
   162
class, .e.g. "MyGame"
slouken@7222
   163
slouken@7222
   164
================================================================================
slouken@7222
   165
 Customizing your application icon
slouken@7222
   166
================================================================================
slouken@7222
   167
slouken@7222
   168
Conceptually changing your icon is just replacing the "ic_launcher.png" files in
slouken@7222
   169
the drawable directories under the res directory. There are four directories for
slouken@7222
   170
different screen sizes. These can be replaced with one dir called "drawable",
slouken@7222
   171
containing an icon file "ic_launcher.png" with dimensions 48x48 or 72x72.
slouken@7222
   172
slouken@7222
   173
You may need to change the name of your icon in AndroidManifest.xml to match
slouken@7222
   174
this icon filename.
slouken@7222
   175
slouken@7222
   176
================================================================================
slouken@7222
   177
 Loading assets
slouken@7222
   178
================================================================================
slouken@7222
   179
slouken@7222
   180
Any files you put in the "assets" directory of your android-project directory
slouken@7222
   181
will get bundled into the application package and you can load them using the
slouken@7222
   182
standard functions in SDL_rwops.h.
slouken@7222
   183
slouken@7222
   184
There are also a few Android specific functions that allow you to get other
slouken@7222
   185
useful paths for saving and loading data:
slouken@7222
   186
SDL_AndroidGetInternalStoragePath()
slouken@7222
   187
SDL_AndroidGetExternalStorageState()
slouken@7222
   188
SDL_AndroidGetExternalStoragePath()
slouken@7222
   189
slouken@7222
   190
See SDL_system.h for more details on these functions.
slouken@7222
   191
slouken@7222
   192
The asset packaging system will, by default, compress certain file extensions.
slouken@7222
   193
SDL includes two asset file access mechanisms, the preferred one is the so
slouken@7222
   194
called "File Descriptor" method, which is faster and doesn't involve the Dalvik
slouken@7222
   195
GC, but given this method does not work on compressed assets, there is also the
slouken@7222
   196
"Input Stream" method, which is automatically used as a fall back by SDL. You
slouken@7222
   197
may want to keep this fact in mind when building your APK, specially when large
slouken@7222
   198
files are involved.
slouken@7222
   199
For more information on which extensions get compressed by default and how to
slouken@7222
   200
disable this behaviour, see for example:
slouken@7222
   201
    
slouken@7222
   202
http://ponystyle.com/blog/2010/03/26/dealing-with-asset-compression-in-android-apps/
slouken@7222
   203
slouken@7222
   204
================================================================================
slouken@7222
   205
 Pause / Resume behaviour
slouken@7222
   206
================================================================================
slouken@7222
   207
slouken@7222
   208
If SDL is compiled with SDL_ANDROID_BLOCK_ON_PAUSE defined (the default),
slouken@7222
   209
the event loop will block itself when the app is paused (ie, when the user
slouken@7222
   210
returns to the main Android dashboard). Blocking is better in terms of battery
slouken@7222
   211
use, and it allows your app to spring back to life instantaneously after resume
slouken@7222
   212
(versus polling for a resume message).
slouken@7222
   213
slouken@7222
   214
Upon resume, SDL will attempt to restore the GL context automatically.
slouken@7222
   215
In modern devices (Android 3.0 and up) this will most likely succeed and your
slouken@7222
   216
app can continue to operate as it was.
slouken@7222
   217
slouken@7222
   218
However, there's a chance (on older hardware, or on systems under heavy load),
slouken@7222
   219
where the GL context can not be restored. In that case you have to listen for
slouken@7222
   220
a specific message, (which is not yet implemented!) and restore your textures
slouken@7222
   221
manually or quit the app (which is actually the kind of behaviour you'll see
slouken@7222
   222
under iOS, if the OS can not restore your GL context it will just kill your app)
slouken@7222
   223
slouken@7222
   224
================================================================================
slouken@7222
   225
 Threads and the Java VM
slouken@7222
   226
================================================================================
slouken@7222
   227
slouken@7222
   228
For a quick tour on how Linux native threads interoperate with the Java VM, take
slouken@7222
   229
a look here: http://developer.android.com/guide/practices/jni.html
slouken@7222
   230
If you want to use threads in your SDL app, it's strongly recommended that you
slouken@7222
   231
do so by creating them using SDL functions. This way, the required attach/detach
slouken@7222
   232
handling is managed by SDL automagically. If you have threads created by other
slouken@7222
   233
means and they make calls to SDL functions, make sure that you call
slouken@7222
   234
Android_JNI_SetupThread before doing anything else otherwise SDL will attach
slouken@7222
   235
your thread automatically anyway (when you make an SDL call), but it'll never
slouken@7222
   236
detach it.
slouken@7222
   237
slouken@7222
   238
================================================================================
slouken@7222
   239
 Using STL
slouken@7222
   240
================================================================================
slouken@7222
   241
slouken@7222
   242
You can use STL in your project by creating an Application.mk file in the jni
slouken@7222
   243
folder and adding the following line:
slouken@7222
   244
APP_STL := stlport_static
slouken@7222
   245
slouken@7222
   246
For more information check out CPLUSPLUS-SUPPORT.html in the NDK documentation.
slouken@7222
   247
slouken@7222
   248
================================================================================
slouken@7222
   249
 Additional documentation
slouken@7222
   250
================================================================================
slouken@7222
   251
slouken@7222
   252
The documentation in the NDK docs directory is very helpful in understanding the
slouken@7222
   253
build process and how to work with native code on the Android platform.
slouken@7222
   254
slouken@7222
   255
The best place to start is with docs/OVERVIEW.TXT
slouken@7222
   256
slouken@7222
   257
slouken@7222
   258
================================================================================
slouken@7222
   259
 Using Eclipse
slouken@7222
   260
================================================================================
slouken@7222
   261
slouken@7222
   262
First make sure that you've installed Eclipse and the Android extensions as described here:
slouken@7222
   263
	http://developer.android.com/sdk/eclipse-adt.html
slouken@7222
   264
slouken@7222
   265
Once you've copied the SDL android project and customized it, you can create an Eclipse project from it:
slouken@7222
   266
 * File -> New -> Other
slouken@7222
   267
 * Select the Android -> Android Project wizard and click Next
slouken@7222
   268
 * Enter the name you'd like your project to have
slouken@7222
   269
 * Select "Create project from existing source" and browse for your project directory
slouken@7222
   270
 * Make sure the Build Target is set to Android 2.0
slouken@7222
   271
 * Click Finish
slouken@7222
   272
slouken@7222
   273
slouken@7222
   274
================================================================================
slouken@7222
   275
 Using the emulator
slouken@7222
   276
================================================================================
slouken@7222
   277
slouken@7222
   278
There are some good tips and tricks for getting the most out of the
slouken@7222
   279
emulator here: http://developer.android.com/tools/devices/emulator.html
slouken@7222
   280
slouken@7222
   281
Especially useful is the info on setting up OpenGL ES 2.0 emulation.
slouken@7222
   282
slouken@7222
   283
Notice that this software emulator is incredibly slow and needs a lot of disk space.
slouken@7222
   284
Using a real device works better.
slouken@7222
   285
slouken@7222
   286
================================================================================
slouken@7222
   287
 Troubleshooting
slouken@7222
   288
================================================================================
slouken@7222
   289
slouken@7222
   290
You can create and run an emulator from the Eclipse IDE:
slouken@7222
   291
 * Window -> Android SDK and AVD Manager
slouken@7222
   292
slouken@7222
   293
You can see if adb can see any devices with the following command:
slouken@7222
   294
	adb devices
slouken@7222
   295
slouken@7222
   296
You can see the output of log messages on the default device with:
slouken@7222
   297
	adb logcat
slouken@7222
   298
slouken@7222
   299
You can push files to the device with:
slouken@7222
   300
	adb push local_file remote_path_and_file
slouken@7222
   301
slouken@7222
   302
You can push files to the SD Card at /sdcard, for example:
slouken@7222
   303
	adb push moose.dat /sdcard/moose.dat
slouken@7222
   304
slouken@7222
   305
You can see the files on the SD card with a shell command:
slouken@7222
   306
	adb shell ls /sdcard/
slouken@7222
   307
slouken@7222
   308
You can start a command shell on the default device with:
slouken@7222
   309
	adb shell
slouken@7222
   310
slouken@7222
   311
You can remove the library files of your project (and not the SDL lib files) with:
slouken@7222
   312
	ndk-build clean
slouken@7222
   313
slouken@7222
   314
You can do a build with the following command:
slouken@7222
   315
	ndk-build
slouken@7222
   316
slouken@7222
   317
You can see the complete command line that ndk-build is using by passing V=1 on the command line:
slouken@7222
   318
	ndk-build V=1
slouken@7222
   319
slouken@7222
   320
If your application crashes in native code, you can use addr2line to convert the
slouken@7222
   321
addresses in the stack trace to lines in your code.
slouken@7222
   322
slouken@7222
   323
For example, if your crash looks like this:
slouken@7222
   324
I/DEBUG   (   31): signal 11 (SIGSEGV), code 2 (SEGV_ACCERR), fault addr 400085d0
slouken@7222
   325
I/DEBUG   (   31):  r0 00000000  r1 00001000  r2 00000003  r3 400085d4
slouken@7222
   326
I/DEBUG   (   31):  r4 400085d0  r5 40008000  r6 afd41504  r7 436c6a7c
slouken@7222
   327
I/DEBUG   (   31):  r8 436c6b30  r9 435c6fb0  10 435c6f9c  fp 4168d82c
slouken@7222
   328
I/DEBUG   (   31):  ip 8346aff0  sp 436c6a60  lr afd1c8ff  pc afd1c902  cpsr 60000030
slouken@7222
   329
I/DEBUG   (   31):          #00  pc 0001c902  /system/lib/libc.so
slouken@7222
   330
I/DEBUG   (   31):          #01  pc 0001ccf6  /system/lib/libc.so
slouken@7222
   331
I/DEBUG   (   31):          #02  pc 000014bc  /data/data/org.libsdl.app/lib/libmain.so
slouken@7222
   332
I/DEBUG   (   31):          #03  pc 00001506  /data/data/org.libsdl.app/lib/libmain.so
slouken@7222
   333
slouken@7222
   334
You can see that there's a crash in the C library being called from the main code.
slouken@7222
   335
I run addr2line with the debug version of my code:
slouken@7222
   336
	arm-eabi-addr2line -C -f -e obj/local/armeabi/libmain.so
slouken@7222
   337
and then paste in the number after "pc" in the call stack, from the line that I care about:
slouken@7222
   338
000014bc
slouken@7222
   339
slouken@7222
   340
I get output from addr2line showing that it's in the quit function, in testspriteminimal.c, on line 23.
slouken@7222
   341
slouken@7222
   342
You can add logging to your code to help show what's happening:
slouken@7222
   343
slouken@7222
   344
#include <android/log.h>
slouken@7222
   345
slouken@7222
   346
	__android_log_print(ANDROID_LOG_INFO, "foo", "Something happened! x = %d", x);
slouken@7222
   347
slouken@7222
   348
If you need to build without optimization turned on, you can create a file called
slouken@7222
   349
"Application.mk" in the jni directory, with the following line in it:
slouken@7222
   350
APP_OPTIM := debug
slouken@7222
   351
slouken@7222
   352
slouken@7222
   353
================================================================================
slouken@7222
   354
 Memory debugging
slouken@7222
   355
================================================================================
slouken@7222
   356
slouken@7222
   357
The best (and slowest) way to debug memory issues on Android is valgrind.
slouken@7222
   358
Valgrind has support for Android out of the box, just grab code using:
slouken@7222
   359
	svn co svn://svn.valgrind.org/valgrind/trunk valgrind
slouken@7222
   360
... and follow the instructions in the file README.android to build it.
slouken@7222
   361
slouken@7222
   362
One thing I needed to do on Mac OS X was change the path to the toolchain,
slouken@7222
   363
and add ranlib to the environment variables:
slouken@7222
   364
export RANLIB=$NDKROOT/toolchains/arm-linux-androideabi-4.4.3/prebuilt/darwin-x86/bin/arm-linux-androideabi-ranlib
slouken@7222
   365
slouken@7222
   366
Once valgrind is built, you can create a wrapper script to launch your
slouken@7222
   367
application with it, changing org.libsdl.app to your package identifier:
slouken@7222
   368
--- start_valgrind_app -------------------
slouken@7222
   369
#!/system/bin/sh
slouken@7222
   370
export TMPDIR=/data/data/org.libsdl.app
slouken@7222
   371
exec /data/local/Inst/bin/valgrind --log-file=/sdcard/valgrind.log --error-limit=no $*
slouken@7222
   372
------------------------------------------
slouken@7222
   373
slouken@7222
   374
Then push it to the device:
slouken@7222
   375
	adb push start_valgrind_app /data/local
slouken@7222
   376
slouken@7222
   377
and make it executable:
slouken@7222
   378
	adb shell chmod 755 /data/local/start_valgrind_app
slouken@7222
   379
slouken@7222
   380
and tell Android to use the script to launch your application:
slouken@7222
   381
	adb shell setprop wrap.org.libsdl.app "logwrapper /data/local/start_valgrind_app"
slouken@7222
   382
slouken@7222
   383
If the setprop command says "could not set property", it's likely that
slouken@7222
   384
your package name is too long and you should make it shorter by changing
slouken@7222
   385
AndroidManifest.xml and the path to your class file in android-project/src
slouken@7222
   386
slouken@7222
   387
You can then launch your application normally and waaaaaaaiiittt for it.
slouken@7222
   388
You can monitor the startup process with the logcat command above, and
slouken@7222
   389
when it's done (or even while it's running) you can grab the valgrind
slouken@7222
   390
output file:
slouken@7222
   391
	adb pull /sdcard/valgrind.log
slouken@7222
   392
slouken@7222
   393
When you're done instrumenting with valgrind, you can disable the wrapper:
slouken@7222
   394
	adb shell setprop wrap.org.libsdl.app ""
slouken@7222
   395
slouken@7222
   396
================================================================================
slouken@7222
   397
 Why is API level 10 the minimum required?
slouken@7222
   398
================================================================================
slouken@7222
   399
gabomdq@7907
   400
API level 10 is the minimum required level at runtime (that is, on the device) 
gabomdq@7907
   401
because SDL requires some functionality for running not
gabomdq@7907
   402
available on older devices. Since the incorporation of joystick support into SDL,
gabomdq@7907
   403
the minimum SDK required to *build* SDL is version 12. Devices running API levels
gabomdq@7907
   404
10-11 are still supported, only with the joystick functionality disabled.
slouken@7222
   405
slouken@7222
   406
Support for native OpenGL ES and ES2 applications was introduced in the NDK for
slouken@7222
   407
API level 4 and 8. EGL was made a stable API in the NDK for API level 9, which
slouken@7222
   408
has since then been obsoleted, with the recommendation to developers to bump the
slouken@7222
   409
required API level to 10.
slouken@7222
   410
As of this writing, according to http://developer.android.com/about/dashboards/index.html
slouken@7222
   411
about 90% of the Android devices accessing Google Play support API level 10 or
slouken@7222
   412
higher (March 2013).
slouken@7222
   413
slouken@7222
   414
================================================================================
slouken@7222
   415
 A note regarding the use of the "dirty rectangles" rendering technique
slouken@7222
   416
================================================================================
slouken@7222
   417
slouken@7222
   418
If your app uses a variation of the "dirty rectangles" rendering technique,
slouken@7222
   419
where you only update a portion of the screen on each frame, you may notice a
slouken@7222
   420
variety of visual glitches on Android, that are not present on other platforms.
slouken@7222
   421
This is caused by SDL's use of EGL as the support system to handle OpenGL ES/ES2
slouken@7222
   422
contexts, in particular the use of the eglSwapBuffers function. As stated in the
slouken@7222
   423
documentation for the function "The contents of ancillary buffers are always 
slouken@7222
   424
undefined after calling eglSwapBuffers".
slouken@7222
   425
Setting the EGL_SWAP_BEHAVIOR attribute of the surface to EGL_BUFFER_PRESERVED
slouken@7222
   426
is not possible for SDL as it requires EGL 1.4, available only on the API level
slouken@7222
   427
17+, so the only workaround available on this platform is to redraw the entire
slouken@7222
   428
screen each frame.
slouken@7222
   429
slouken@7222
   430
Reference: http://www.khronos.org/registry/egl/specs/EGLTechNote0001.html
slouken@7222
   431
slouken@7222
   432
================================================================================
slouken@7222
   433
 Known issues
slouken@7222
   434
================================================================================
slouken@7222
   435
gabomdq@7944
   436
- The number of buttons reported for each joystick is hardcoded to be 36, which
gabomdq@7944
   437
is the current maximum number of buttons Android can report.
gabomdq@7944
   438