README-android.txt
author Gabriel Jacobo <gabomdq@gmail.com>
Tue, 05 Nov 2013 20:07:39 -0300
changeset 7907 24b4e98c6010
parent 7804 1f85fb33694b
child 7944 f19c0aca56aa
permissions -rw-r--r--
Adds Joystick support for Android

This bumps the build SDK level to 12 (up from 10). Runtime requirements remain
the same (at API level < 12 joystick support is disabled).

Also enables building SDL for armv7 and x86.
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
slouken@7222
   436
- TODO. I'm sure there's a bunch more stuff I haven't thought of