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