Merged Daniel's Google Summer of Code work from SDL-gsoc2010_IME

libsdl-org · Aug 22, 2010 · 9e717f1 · 9e717f1
2 parents 818c8da + 6169c31
commit 9e717f1
Show file tree

Hide file tree

Showing 116 changed files with 12,544 additions and 3,238 deletions.
diff --git a/.hgignore b/.hgignore
@@ -90,5 +90,6 @@ test/testime
 test/testatomic
 test/testspriteminimal
 test/testfill
+test/testgesture
 test/*.exe
 test/*.dSYM
diff --git a/Makefile.android b/Makefile.android
@@ -0,0 +1,52 @@
+# Makefile to build the SDL library
+
+include ./android/config.cfg #get ANDROID_NDK
+
+TOOLS_PATH=$(ANDROID_NDK)/build/prebuilt/linux-x86/arm-eabi-4.2.1/bin
+ANDROID_INCLUDES = 	-I$(ANDROID_NDK)/build/platforms/android-4/common/include \
+					-I$(ANDROID_NDK)/build/platforms/android-4/arch-arm/usr/include 
+INCLUDE = -I./include
+CFLAGS  = -g -O2 $(INCLUDE) $(ANDROID_INCLUDES) -DANDROID -DANDROID_NDK -static
+
+AR	= $(TOOLS_PATH)/arm-eabi-ar
+RANLIB	= $(TOOLS_PATH)/arm-eabi-ranlib
+CC = $(TOOLS_PATH)/arm-eabi-gcc
+
+
+CONFIG_H = include/SDL_config.h
+TARGET  = libSDL.a
+SOURCES = \
+	src/*.c \
+	src/audio/*.c \
+	src/cpuinfo/*.c \
+	src/events/*.c \
+	src/file/*.c \
+	src/joystick/*.c \
+	src/haptic/*.c \
+	src/stdlib/*.c \
+	src/thread/*.c \
+	src/timer/*.c \
+	src/video/*.c \
+	src/power/*.c \
+	src/audio/android/*.c \
+	src/video/android/*.c \
+	src/joystick/android/*.c \
+	src/haptic/dummy/*.c \
+	src/atomic/dummy/*.c \
+	src/thread/pthread/*.c \
+	src/timer/unix/*.c \
+	src/loadso/dummy/*.c \
+
+OBJECTS = $(shell echo $(SOURCES) | sed -e 's,\.c,\.o,g')
+
+all: $(TARGET)
+
+$(TARGET): $(CONFIG_H) $(OBJECTS)
+	$(AR) crv $@ $^
+	$(RANLIB) $@
+
+$(CONFIG_H):
+	cp $(CONFIG_H).default $(CONFIG_H)
+
+clean:
+	rm -f $(TARGET) $(OBJECTS)
diff --git a/Makefile.in b/Makefile.in
@@ -44,7 +44,7 @@ EMBEDSPU = @EMBEDSPU@
 
 DIST = acinclude autogen.sh Borland.html Borland.zip BUGS build-scripts configure configure.in COPYING CREDITS include INSTALL Makefile.minimal Makefile.in README* sdl-config.in sdl.m4 sdl.pc.in SDL.spec SDL.spec.in src test TODO VisualC.html VisualC VisualCE Watcom-Win32.zip WhatsNew Xcode Xcode-iPhoneOS
 
-HDRS = SDL.h SDL_assert.h SDL_atomic.h SDL_audio.h SDL_clipboard.h SDL_compat.h SDL_cpuinfo.h SDL_endian.h SDL_error.h SDL_events.h SDL_haptic.h SDL_input.h SDL_joystick.h SDL_keyboard.h SDL_keysym.h SDL_loadso.h SDL_main.h SDL_mouse.h SDL_mutex.h SDL_name.h SDL_opengl.h SDL_opengles.h SDL_pixels.h SDL_platform.h SDL_power.h SDL_quit.h SDL_rect.h SDL_revision.h SDL_rwops.h SDL_scancode.h SDL_stdinc.h SDL_surface.h SDL_syswm.h SDL_thread.h SDL_timer.h SDL_types.h SDL_version.h SDL_video.h begin_code.h close_code.h
+HDRS = SDL.h SDL_assert.h SDL_atomic.h SDL_audio.h SDL_clipboard.h SDL_compat.h SDL_cpuinfo.h SDL_endian.h SDL_error.h SDL_events.h SDL_gesture.h SDL_haptic.h SDL_input.h SDL_joystick.h SDL_keyboard.h SDL_keysym.h SDL_loadso.h SDL_main.h SDL_mouse.h SDL_mutex.h SDL_name.h SDL_opengl.h SDL_opengles.h SDL_pixels.h SDL_platform.h SDL_power.h SDL_quit.h SDL_rect.h SDL_revision.h SDL_rwops.h SDL_scancode.h SDL_stdinc.h SDL_surface.h SDL_syswm.h SDL_thread.h SDL_timer.h SDL_touch.h SDL_types.h SDL_version.h SDL_video.h begin_code.h close_code.h
 
 LT_AGE      = @LT_AGE@
 LT_CURRENT  = @LT_CURRENT@

diff --git a/README.DirectFB b/README.DirectFB
@@ -65,10 +65,26 @@ you need to have the following font installed:
 OPENGL Support
 ==============
 
-As of this writing 20070810 you need to pull Mesa from git and do the following:
+The following instructions will give you *software* opengl. However this
+works at least on all directfb supported platforms.
+
+As of this writing 20100802 you need to pull Mesa from git and do the following:
 
 ------------------------
+git checkout 2c9fdaf7292423c157fc79b5ce43f0f199dd753a
 cd mesa 
+git clone git://anongit.freedesktop.org/git/mesa/mesa
+------------------------
+
+Edit configs/linux-directfb so that the Directories-section looks like
+------------------------
+# Directories
+SRC_DIRS     = mesa glu 
+GLU_DIRS     = sgi
+DRIVER_DIRS  = directfb
+PROGRAM_DIRS = 
+------------------------
+
 make linux-directfb
 make
 
@@ -87,3 +103,4 @@ export LD_LIBRARY_PATH=/usr/local/dfb_GL/lib
 export LD_PRELOAD=/usr/local/dfb_GL/libGL.so.7
 
 ./testgl
+
diff --git a/README.android b/README.android
@@ -0,0 +1,45 @@
+================================================================================
+Simple DirectMedia Layer for Android
+================================================================================
+
+Requirements: Android NDK r4 or later
+
+================================================================================
+ How the port works
+================================================================================
+
+- 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
+- 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
+- This eventually produces a standard Android .apk package
+
+
+
+
+
+
+================================================================================
+ Building an app
+================================================================================
+
+Instructions:
+1. Edit android/config.cfg to point to the location of the NDK
+2. Run 'make -f Makefile.android'. If all goes well, libsdl.a should be created
+3. Place your application source files in android/project/jni
+4. Edit the Android.mk to include your source files
+5. Run 'ndk-build' (a script provided by the NDK). This compiles the C source
+6. Run 'ant' in android/testproject. This compiles the .java and eventually 
+creates a .apk with the C source embedded
+7. 'ant install' will push the apk to the device or emulator (if connected)
+
+
+
+
+================================================================================
+ Known issues
+================================================================================
+
+- SDL audio (although it's mostly written, just not working properly yet)
+- TODO. I'm sure there's a bunch more stuff I haven't thought of 
diff --git a/README.gesture b/README.gesture
@@ -0,0 +1,72 @@
+===========================================================================
+Dollar Gestures
+===========================================================================
+SDL Provides an implementation of the $1 gesture recognition system. This allows for recording, saving, loading, and performing single stroke gestures.
+
+Gestures can be performed with any number of fingers (the centroid of the fingers must follow the path of the gesture), but the number of fingers must be constant (a finger cannot go down in the middle of a gesture). The path of a gesture is considered the path from the time when the final finger went down, to the first time any finger comes up. 
+
+Dollar gestures are assigned an Id based on a hash function. This is guaranteed to remain constant for a given gesture. There is a (small) chance that two different gestures will be assigned the same ID. In this case, simply re-recording one of the gestures should result in a different ID.
+
+Recording:
+----------
+To begin recording on a touch device call:
+SDL_RecordGesture(SDL_TouchID touchId), where touchId is the id of the touch device you wish to record on, or -1 to record on all connected devices.
+
+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 recoreded 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.
+
+Most programs will want to define an appropriate error threshold and check to be sure taht the error of a gesture is not abnormally high (an indicator that no gesture was performed). 
+
+
+
+Saving:
+-------
+To save a template, call SDL_SaveDollarTemplate(gestureId, src) where gestureId is the id of the gesture you want to save, and src is an SDL_RWops pointer to the file where the gesture will be stored.
+
+To save all currently loaded templates, call SDL_SaveAllDollarTemplates(src) where source is an SDL_RWops pointer to the file where the gesture will be stored.
+
+Both functions return the number of gestures sucessfully saved.
+
+
+Loading:
+--------
+To load templates from a file, call SDL_LoadDollarTemplates(touchId,src) where touchId is the id of the touch to load to (or -1 to load to all touch devices), and src is an SDL_RWops pointer to a gesture save file. 
+
+SDL_LoadDollarTemplates returns the number of templates sucessfully loaded. 
+
+
+
+===========================================================================
+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 cooridinate of the gesture. (0..1)
+event.mgesture.y       - the normalized y cooridinate 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.
+
+
+===========================================================================
+Notes
+===========================================================================
+For a complete example see test/testgesture.c
+
+Please direct questions/comments to:
+   jim.tla+sdl_touch@gmail.com
diff --git a/README.iphoneos b/README.iphoneos
@@ -33,14 +33,6 @@ Here is a more manual method:
 4.  Remove the ApplicationDelegate.h and ApplicationDelegate.m files -- SDL for iPhone provides its own UIApplicationDelegate.  Remove MainWindow.xib -- SDL for iPhone produces its user interface programmatically.
 5.  Delete the contents of main.m and program your app as a regular SDL program instead.  You may replace main.m with your own main.c, but you must tell XCode not to use the project prefix file, as it includes Objective-C code.
 
-==============================================================================
-Notes -- Touch Input
-==============================================================================
-
-Touch input in SDL for iPhone OS is presently exposed through SDL's mouse input API.  Multi-touch input is reported as multiple mice, with each touch associated with a specific mouse.  This association stays coherent from the time the touch starts to the time a touch ends.
-
-By default, multi-touch is turned ON.  This requires some care, because if you simply respond to mouse events without checking which mouse caused the event, you may end up fetching data from the wrong mouse, ie, from an incorrect or invalid touch.  To turn multi-touch OFF, you can recompile SDL for iPhone with the macro SDL_IPHONE_MULTIPLE_MICE (found in SDL_config_iphoneos.h) set to 0.
-
 ==============================================================================
 Notes -- Accelerometer as Joystick
 ==============================================================================
@@ -55,7 +47,7 @@ Notes -- OpenGL ES
 
 Your SDL application for iPhone uses OpenGL ES for video by default.
 
-OpenGL ES for iPhone supports two display pixel formats, RGBA8 and RGB565, which provide a 32 bit and 16 bit color buffer respectively.  By default, the implementation uses RGB565, but you may use RGBA8 by setting each color component to 8 bits in SDL_GL_SetAttribute.
+OpenGL ES for iPhone supports several display pixel formats, such as RGBA8 and RGB565, which provide a 32 bit and 16 bit color buffer respectively.  By default, the implementation uses RGB565, but you may use RGBA8 by setting each color component to 8 bits in SDL_GL_SetAttribute.
 
 If your application doesn't use OpenGL's depth buffer, you may find significant performance improvement by setting SDL_GL_DEPTH_SIZE to 0.
 

diff --git a/README.touch b/README.touch
@@ -0,0 +1,101 @@
+===========================================================================
+System Specific Notes
+===========================================================================
+Linux:
+The linux touch system is currently based off event streams, and proc/bus/devices. The active user must be given permissions to read /dev/input/TOUCHDEVICE, where TOUCHDEVICE is the event stream for your device. Currently only Wacom tablets are supported. If you have an unsupported tablet contact me at jim.tla+sdl_touch@gmail.com and I will help you get support for it.
+
+Mac: 
+The Mac and Iphone API's are pretty. If your touch device supports them then you'll be fine. If it doesn't, then there isn't much we can do.
+
+iPhone: 
+Works out of box.
+
+Windows:
+Unfortunately there is no windows support as of yet. Support for Windows 7 is planned, but we currently have no way to test. If you have a Windows 7 WM_TOUCH supported device, and are willing to help test please contact me at jim.tla+sdl_touch@gmail.com
+
+===========================================================================
+Events
+===========================================================================
+SDL_FINGERDOWN:
+Sent when a finger (or stylus) is placed on a touch device.
+Fields:
+event.tfinger.touchId  - the Id of the touch device.
+event.tfinger.fingerId - the Id of the finger which just went down.
+event.tfinger.x        - the x coordinate of the touch (0..touch.xres)
+event.tfinger.y        - the y coordinate of the touch (0..touch.yres)
+event.tfinger.pressure - the pressure of the touch (0..touch.pressureres)
+
+SDL_FINGERMOTION:
+Sent when a finger (or stylus) is moved on the touch device.
+Fields:
+Same as FINGERDOWN but with additional:
+event.tfginer.dx       - change in x coordinate during this motion event.
+event.tfginer.dy       - change in y coordinate during this motion event.
+
+SDL_FINGERMOTION:
+Sent when a finger (or stylus) is lifted from the touch device.
+Fields:
+Same as FINGERDOWN.
+
+
+===========================================================================
+Functions
+===========================================================================
+SDL provides the ability to access the underlying Touch and Finger structures.
+These structures should _never_ be modified.
+
+The following functions are included from SDL_Touch.h
+
+To get a SDL_Touch device call SDL_GetTouch(touchId). 
+This returns an SDL_Touch*. 
+IMPORTANT: If the touch has been removed, or there is no touch with the given ID, SDL_GetTouch will return null. Be sure to check for this!
+
+An SDL_Touch has the following fields:
+>xres,yres,pressures:
+	The resolution at which x,y, and pressure values are reported. Currently these will always be equal to 2^15, but this may not always be the case. 
+
+>pressure_max, pressure_min, x_max, x_min, y_max, y_min
+	Which give, respectively, the maximum and minumum values that the touch digitizer can return for pressure, x coordiniate, and y coordinate AS REPORTED BY THE OPERATING SYSTEM.
+On Mac/iPhone systems _max will always be 0, and _min will always be 1. 
+
+>native_xres,native_yres,native_pressureres:
+	The native resolution of the touch device AS REPORTED BY THE OPERATING SYSTEM.
+On Mac/iPhone systems these will always be 1.
+
+>num_fingers:
+	The number of fingers currently down on the device.
+
+>fingers:
+	An array of pointers to the fingers which are on the device.
+
+
+The most common reason to access a touch device is to normalize inputs. This would be accomplished by code like the following:
+
+      SDL_Touch* inTouch = SDL_GetTouch(event.tfinger.touchId);
+      if(inTouch == NULL) continue; //The touch has been removed
+
+      float x = ((float)event.tfinger.x)/inTouch->xres;
+      float y = ((float)event.tfinger.y)/inTouch->yres;
+
+
+
+To get an SDL_Finger, call SDL_GetFinger(touch,fingerId), where touch is a pointer to an SDL_Touch device, and fingerId is the id of the requested finger.
+This returns an SDL_Finger*, or null if the finger does not exist, or has been removed.
+An SDL_Finger is guaranteed to be persistent for the duration of a touch, but it will be de-allocated as soon as the finger is removed. This occurs when the SDL_FINGERUP event is _added_ to the event queue, and thus _before_ the FINGERUP event is polled. 
+As a result, be very careful to check for null return values.
+
+An SDL_Finger has the following fields:
+>x,y,pressure:
+	The current coordinates of the touch.
+>xdelta,ydelta: 
+	The change in position resulting from the last finger motion.
+>last_x, last_y, last_pressure:
+	 The previous coordinates of the touch.
+
+===========================================================================
+Notes
+===========================================================================
+For a complete example see test/testgesture.c
+
+Please direct questions/comments to:
+   jim.tla+sdl_touch@gmail.com