Skip to content
Permalink
Browse files

Fixed markdown formatting in READMEs.

  • Loading branch information
philippwiesemann committed Aug 15, 2014
1 parent c5aa0d8 commit 6d9dbf5e1e1177a225b70600704af16970067369
@@ -18,9 +18,9 @@ Joystick support is available for API level >=12 devices.

- Android applications are Java-based, optionally with parts written in C
- As SDL apps are C-based, we use a small Java shim that uses JNI to talk to
the SDL library
the SDL library
- This means that your application C code must be placed inside an Android
Java project, along with some C support code that communicates with Java
Java project, along with some C support code that communicates with Java
- This eventually produces a standard Android .apk package

The Android Java code implements an "Activity" and can be found in:
@@ -42,15 +42,15 @@ For simple projects you can use the script located at build-scripts/androidbuild

There's two ways of using it:

androidbuild.sh com.yourcompany.yourapp < sources.list
androidbuild.sh com.yourcompany.yourapp source1.c source2.c ...sourceN.c
androidbuild.sh com.yourcompany.yourapp < sources.list
androidbuild.sh com.yourcompany.yourapp source1.c source2.c ...sourceN.c

sources.list should be a text file with a source file name in each line
Filenames should be specified relative to the current directory, for example if
you are in the build-scripts directory and want to create the testgles.c test, you'll
run:
./androidbuild.sh org.libsdl.testgles ../test/testgles.c

./androidbuild.sh org.libsdl.testgles ../test/testgles.c

One limitation of this script is that all sources provided will be aggregated into
a single directory, thus all your source files should have a unique name.
@@ -74,7 +74,9 @@ For more complex projects, follow these instructions:
If you want to use the Eclipse IDE, skip to the Eclipse section below.

5. Create <project>/local.properties and use that to point to the Android SDK directory, by writing a line with the following form:
sdk.dir=PATH_TO_ANDROID_SDK

sdk.dir=PATH_TO_ANDROID_SDK

6. Run 'ant debug' in android/project. This compiles the .java and eventually
creates a .apk with the native code embedded
7. 'ant debug install' will push the apk to the device or emulator (if connected)
@@ -125,7 +127,7 @@ Instructions:
4. create and export an environment variable named NDK_MODULE_PATH that points
to the parent directory of this SDL directory. e.g.:

export NDK_MODULE_PATH="$PWD"/..
export NDK_MODULE_PATH="$PWD"/..

5. Edit <project>/src/org/libsdl/app/SDLActivity.java and remove the call to
System.loadLibrary("SDL2").
@@ -142,7 +144,7 @@ To customize your application name, edit AndroidManifest.xml and replace
Then create a Java class extending SDLActivity and place it in a directory
under src matching your package, e.g.

src/com/gamemaker/game/MyGame.java
src/com/gamemaker/game/MyGame.java

Here's an example of a minimal class file:

@@ -184,9 +186,9 @@ standard functions in SDL_rwops.h.

There are also a few Android specific functions that allow you to get other
useful paths for saving and loading data:
SDL_AndroidGetInternalStoragePath()
SDL_AndroidGetExternalStorageState()
SDL_AndroidGetExternalStoragePath()
* SDL_AndroidGetInternalStoragePath()
* SDL_AndroidGetExternalStorageState()
* SDL_AndroidGetExternalStoragePath()

See SDL_system.h for more details on these functions.

@@ -228,6 +230,7 @@ under iOS, if the OS can not restore your GL context it will just kill your app)

For a quick tour on how Linux native threads interoperate with the Java VM, take
a look here: http://developer.android.com/guide/practices/jni.html

If you want to use threads in your SDL app, it's strongly recommended that you
do so by creating them using SDL functions. This way, the required attach/detach
handling is managed by SDL automagically. If you have threads created by other
@@ -242,7 +245,8 @@ detach it.

You can use STL in your project by creating an Application.mk file in the jni
folder and adding the following line:
APP_STL := stlport_static

APP_STL := stlport_static

For more information check out CPLUSPLUS-SUPPORT.html in the NDK documentation.

@@ -293,39 +297,39 @@ You can create and run an emulator from the Eclipse IDE:

You can see if adb can see any devices with the following command:

adb devices
adb devices

You can see the output of log messages on the default device with:

adb logcat
adb logcat

You can push files to the device with:

adb push local_file remote_path_and_file
adb push local_file remote_path_and_file

You can push files to the SD Card at /sdcard, for example:

adb push moose.dat /sdcard/moose.dat
adb push moose.dat /sdcard/moose.dat

You can see the files on the SD card with a shell command:

adb shell ls /sdcard/
adb shell ls /sdcard/

You can start a command shell on the default device with:

adb shell
adb shell

You can remove the library files of your project (and not the SDL lib files) with:

ndk-build clean
ndk-build clean

You can do a build with the following command:

ndk-build
ndk-build

You can see the complete command line that ndk-build is using by passing V=1 on the command line:

ndk-build V=1
ndk-build V=1

If your application crashes in native code, you can use addr2line to convert the
addresses in the stack trace to lines in your code.
@@ -345,7 +349,7 @@ For example, if your crash looks like this:
You can see that there's a crash in the C library being called from the main code.
I run addr2line with the debug version of my code:

arm-eabi-addr2line -C -f -e obj/local/armeabi/libmain.so
arm-eabi-addr2line -C -f -e obj/local/armeabi/libmain.so

and then paste in the number after "pc" in the call stack, from the line that I care about:
000014bc
@@ -360,7 +364,8 @@ You can add logging to your code to help show what's happening:

If you need to build without optimization turned on, you can create a file called
"Application.mk" in the jni directory, with the following line in it:
APP_OPTIM := debug

APP_OPTIM := debug


================================================================================
@@ -370,7 +375,7 @@ APP_OPTIM := debug
The best (and slowest) way to debug memory issues on Android is valgrind.
Valgrind has support for Android out of the box, just grab code using:

svn co svn://svn.valgrind.org/valgrind/trunk valgrind
svn co svn://svn.valgrind.org/valgrind/trunk valgrind

... and follow the instructions in the file README.android to build it.

@@ -389,15 +394,15 @@ application with it, changing org.libsdl.app to your package identifier:

Then push it to the device:

adb push start_valgrind_app /data/local
adb push start_valgrind_app /data/local

and make it executable:

adb shell chmod 755 /data/local/start_valgrind_app
adb shell chmod 755 /data/local/start_valgrind_app

and tell Android to use the script to launch your application:

adb shell setprop wrap.org.libsdl.app "logwrapper /data/local/start_valgrind_app"
adb shell setprop wrap.org.libsdl.app "logwrapper /data/local/start_valgrind_app"

If the setprop command says "could not set property", it's likely that
your package name is too long and you should make it shorter by changing
@@ -408,11 +413,11 @@ You can monitor the startup process with the logcat command above, and
when it's done (or even while it's running) you can grab the valgrind
output file:

adb pull /sdcard/valgrind.log
adb pull /sdcard/valgrind.log

When you're done instrumenting with valgrind, you can disable the wrapper:

adb shell setprop wrap.org.libsdl.app ""
adb shell setprop wrap.org.libsdl.app ""

================================================================================
Why is API level 10 the minimum required?
@@ -10,22 +10,23 @@ It works in parallel to the legacy system, so users can experiment with it
without complication.
While still experimental, the build system should be usable on the following
platforms:

* FreeBSD
* Linux
* VS.NET 2010
* MinGW and Msys
* OS X with support for XCode


* FreeBSD
* Linux
* VS.NET 2010
* MinGW and Msys
* OS X with support for XCode


================================================================================
Usage
================================================================================

Assuming the source for SDL is located at ~/sdl

cd ~
mkdir build
cd build
cmake ../sdl
cd ~
mkdir build
cd build
cmake ../sdl

This will build the static and dynamic versions of SDL in the ~/build directory.
@@ -11,9 +11,9 @@ Supports:

What you need:

DirectFB 1.0.1, 1.2.x, 1.3.0
Kernel-Framebuffer support: required: vesafb, radeonfb ....
Mesa 7.0.x - optional for OpenGL
* DirectFB 1.0.1, 1.2.x, 1.3.0
* Kernel-Framebuffer support: required: vesafb, radeonfb ....
* Mesa 7.0.x - optional for OpenGL

/etc/directfbrc

@@ -14,18 +14,18 @@ SDL_RecordGesture(SDL_TouchID touchId), where touchId is the id of the touch dev
Recording terminates as soon as a finger comes up. Recording is acknowledged by an SDL_DOLLARRECORD event.
A SDL_DOLLARRECORD event is a dgesture with the following fields:

event.dgesture.touchId - the Id of the touch used to record the gesture.
event.dgesture.gestureId - the unique id of the recorded gesture.
* event.dgesture.touchId - the Id of the touch used to record the gesture.
* event.dgesture.gestureId - the unique id of the recorded gesture.


Performing:
-----------
As long as there is a dollar gesture assigned to a touch, every finger-up event will also cause an SDL_DOLLARGESTURE event with the following fields:

event.dgesture.touchId - the Id of the touch which performed the gesture.
event.dgesture.gestureId - the unique id of the closest gesture to the performed stroke.
event.dgesture.error - the difference between the gesture template and the actual performed gesture. Lower error is a better match.
event.dgesture.numFingers - the number of fingers used to draw the stroke.
* event.dgesture.touchId - the Id of the touch which performed the gesture.
* event.dgesture.gestureId - the unique id of the closest gesture to the performed stroke.
* event.dgesture.error - the difference between the gesture template and the actual performed gesture. Lower error is a better match.
* event.dgesture.numFingers - the number of fingers used to draw the stroke.

Most programs will want to define an appropriate error threshold and check to be sure that the error of a gesture is not abnormally high (an indicator that no gesture was performed).

@@ -54,12 +54,12 @@ Multi Gestures
SDL provides simple support for pinch/rotate/swipe gestures.
Every time a finger is moved an SDL_MULTIGESTURE event is sent with the following fields:

event.mgesture.touchId - the Id of the touch on which the gesture was performed.
event.mgesture.x - the normalized x coordinate of the gesture. (0..1)
event.mgesture.y - the normalized y coordinate of the gesture. (0..1)
event.mgesture.dTheta - the amount that the fingers rotated during this motion.
event.mgesture.dDist - the amount that the fingers pinched during this motion.
event.mgesture.numFingers - the number of fingers used in the gesture.
* event.mgesture.touchId - the Id of the touch on which the gesture was performed.
* event.mgesture.x - the normalized x coordinate of the gesture. (0..1)
* event.mgesture.y - the normalized y coordinate of the gesture. (0..1)
* event.mgesture.dTheta - the amount that the fingers rotated during this motion.
* event.mgesture.dDist - the amount that the fingers pinched during this motion.
* event.mgesture.numFingers - the number of fingers used in the gesture.


===========================================================================
@@ -9,7 +9,7 @@ at the Mercurial website ( http://mercurial.selenic.com/ ) for more
information on using hg, where you can also download software for
Mac OS X, Windows, and Unix systems.

hg clone http://hg.libsdl.org/SDL
hg clone http://hg.libsdl.org/SDL

If you are building SDL with an IDE, you will need to copy the file
include/SDL_config.h.default to include/SDL_config.h before building.
@@ -18,7 +18,6 @@ If you are building SDL via configure, you will need to run autogen.sh
before running configure.

There is a web interface to the subversion repository at:

http://hg.libsdl.org/SDL/

There is an RSS feed available at that URL, for those that want to

0 comments on commit 6d9dbf5

Please sign in to comment.