Fixed bug 1748 - Patch for errors and mistakes in SDL 2 README files.
authorSam Lantinga <slouken@libsdl.org>
Sun, 10 Mar 2013 09:03:38 -0700
changeset 69877084af936d82
parent 6986 bc887debed9b
child 6988 2aed1beaf5bc
Fixed bug 1748 - Patch for errors and mistakes in SDL 2 README files.

Philipp Wiesemann

SDL's README files seem to contain multiple errors and mistakes. I attached a patch with changes and updates.

README:
* removed Windows CE because no more supported

README-SDL.txt:
* corrected spelling mistake

README.DirectFB:
* corrected spelling mistakes

README.MacOSX:
* corrected spelling mistakes

README.Platforms:
* changed Android version to match AndroidManifest.xml

README.Porting:
* added missing directories from list
* removed cdrom directories from list

README.android:
* updated required NDK revision
* add project.properties to list
* changed lower limit for to android-10 and removed upper
* added a statement why older devices not supported
* added correct dates to statements about OpenGL ES
* added info about Google's device numbers and date
* corrected spelling mistakes

README.gesture:
* corrected spelling mistakes

README.pandora:
* corrected spelling mistake

README.touch:
* changed that values are no in range 0..1
* updated the names of some functions
* updated the notes about usage
* corrected spelling mistakes
* added info that API changed near original author contact
README
README-SDL.txt
README.DirectFB
README.MacOSX
README.Platforms
README.Porting
README.android
README.gesture
README.pandora
README.touch
     1.1 --- a/README	Sat Mar 09 10:35:12 2013 -0800
     1.2 +++ b/README	Sun Mar 10 09:03:38 2013 -0700
     1.3 @@ -12,7 +12,7 @@
     1.4  level access to audio, keyboard, mouse, joystick, 3D hardware via OpenGL,
     1.5  and 2D framebuffer across multiple platforms.
     1.6  
     1.7 -The current version supports Windows, Windows CE, Mac OS X, Linux, FreeBSD,
     1.8 +The current version supports Windows, Mac OS X, Linux, FreeBSD,
     1.9  NetBSD, OpenBSD, BSD/OS, Solaris, iOS, and Android. The code contains
    1.10  support for other operating systems but those are not officially supported.
    1.11  
     2.1 --- a/README-SDL.txt	Sat Mar 09 10:35:12 2013 -0800
     2.2 +++ b/README-SDL.txt	Sun Mar 10 09:03:38 2013 -0700
     2.3 @@ -1,7 +1,7 @@
     2.4  
     2.5  Please distribute this file with the SDL runtime environment:
     2.6  
     2.7 -The Simple DirectMedia Layer (SDL for short) is a cross-platfrom library
     2.8 +The Simple DirectMedia Layer (SDL for short) is a cross-platform library
     2.9  designed to make it easy to write multi-media software, such as games and
    2.10  emulators.
    2.11  
     3.1 --- a/README.DirectFB	Sat Mar 09 10:35:12 2013 -0800
     3.2 +++ b/README.DirectFB	Sun Mar 10 09:03:38 2013 -0700
     3.3 @@ -53,7 +53,7 @@
     3.4  =====================
     3.5  
     3.6  The driver has support for a very, very basic window manager you may
     3.7 -want to use when runnning with "wm=default". Use
     3.8 +want to use when running with "wm=default". Use
     3.9  
    3.10  export SDL_DIRECTFB_WM=1
    3.11  
    3.12 @@ -62,10 +62,10 @@
    3.13  
    3.14  /usr/share/fonts/truetype/freefont/FreeSans.ttf
    3.15  
    3.16 -OPENGL Support
    3.17 +OpenGL Support
    3.18  ==============
    3.19  
    3.20 -The following instructions will give you *software* opengl. However this
    3.21 +The following instructions will give you *software* OpenGL. However this
    3.22  works at least on all directfb supported platforms.
    3.23  
    3.24  As of this writing 20100802 you need to pull Mesa from git and do the following:
     4.1 --- a/README.MacOSX	Sat Mar 09 10:35:12 2013 -0800
     4.2 +++ b/README.MacOSX	Sun Mar 10 09:03:38 2013 -0700
     4.3 @@ -56,7 +56,7 @@
     4.4  name as specified in your configure.in file.
     4.5  
     4.6  If your project builds more than one application, you will have to do a bit
     4.7 -more.  For each of your target applications, you need a seperate rule.
     4.8 +more. For each of your target applications, you need a separate rule.
     4.9  
    4.10  If you want the created bundles to be installed, you may want to add this
    4.11  rule to your Makefile.am:
    4.12 @@ -75,13 +75,13 @@
    4.13  
    4.14  But beware! That is only part of the story! With the above, you end up with
    4.15  a bare bone .app bundle, which is double clickable from the Finder. But
    4.16 -there are some  more things you should do before shipping yor product...
    4.17 +there are some more things you should do before shipping your product...
    4.18  
    4.19  1) The bundle right now probably is dynamically linked against SDL. That 
    4.20     means that when you copy it to another computer, *it will not run*,
    4.21     unless you also install SDL on that other computer. A good solution
    4.22     for this dilemma is to static link against SDL. On OS X, you can
    4.23 -   achieve that by linkinag against the libraries listed by
    4.24 +   achieve that by linking against the libraries listed by
    4.25       sdl-config --static-libs
    4.26     instead of those listed by
    4.27       sdl-config --libs
    4.28 @@ -120,7 +120,7 @@
    4.29  - Building the Framework
    4.30  
    4.31  The SDL Library is packaged as a framework bundle, an organized
    4.32 -relocatable folder heirarchy of executible code, interface headers, 
    4.33 +relocatable folder hierarchy of executable code, interface headers,
    4.34  and additional resources. For practical purposes, you can think of a 
    4.35  framework as a more user and system-friendly shared library, whose library
    4.36  file behaves more or less like a standard UNIX shared library.
    4.37 @@ -162,11 +162,11 @@
    4.38  
    4.39  - Building from command line
    4.40      Use pbxbuild in the same directory as your .pbproj file
    4.41 -         
    4.42 +
    4.43  - Running your app
    4.44      You can send command line args to your app by either invoking it from
    4.45      the command line (in *.app/Contents/MacOS) or by entering them in the
    4.46 -    "Executibles" panel of the target settings.
    4.47 +    "Executables" panel of the target settings.
    4.48      
    4.49  - Implementation Notes
    4.50      Some things that may be of interest about how it all works...
    4.51 @@ -181,6 +181,6 @@
    4.52          You are free to modify your Cocoa app with generally no consequence 
    4.53          to SDL. You cannot, however, easily change the SDL window itself.
    4.54          Functionality may be added in the future to help this.
    4.55 -	
    4.56 +
    4.57  
    4.58  Known bugs are listed in the file "BUGS"
     5.1 --- a/README.Platforms	Sat Mar 09 10:35:12 2013 -0800
     5.2 +++ b/README.Platforms	Sun Mar 10 09:03:38 2013 -0700
     5.3 @@ -11,7 +11,7 @@
     5.4  Mac OS X 10.4+
     5.5  Linux 2.6+
     5.6  iOS 3.1.3+
     5.7 -Android 2.1+
     5.8 +Android 2.3.3+
     5.9  
    5.10  Unofficially supported platforms
    5.11  ================================
     6.1 --- a/README.Porting	Sat Mar 09 10:35:12 2013 -0800
     6.2 +++ b/README.Porting	Sun Mar 10 09:03:38 2013 -0700
     6.3 @@ -26,12 +26,15 @@
     6.4     Add the top level include directory to the header search path, and then add
     6.5     the following sources to the project:
     6.6  	src/*.c
     6.7 +	src/atomic/*.c
     6.8  	src/audio/*.c
     6.9 -	src/cdrom/*.c
    6.10  	src/cpuinfo/*.c
    6.11  	src/events/*.c
    6.12  	src/file/*.c
    6.13 +	src/haptic/*.c
    6.14  	src/joystick/*.c
    6.15 +	src/power/*.c
    6.16 +	src/render/*.c
    6.17  	src/stdlib/*.c
    6.18  	src/thread/*.c
    6.19  	src/timer/*.c
    6.20 @@ -39,8 +42,9 @@
    6.21  	src/audio/disk/*.c
    6.22  	src/audio/dummy/*.c
    6.23  	src/video/dummy/*.c
    6.24 +	src/haptic/dummy/*.c
    6.25  	src/joystick/dummy/*.c
    6.26 -	src/cdrom/dummy/*.c
    6.27 +	src/main/dummy/*.c
    6.28  	src/thread/generic/*.c
    6.29  	src/timer/dummy/*.c
    6.30  	src/loadso/dummy/*.c
     7.1 --- a/README.android	Sat Mar 09 10:35:12 2013 -0800
     7.2 +++ b/README.android	Sun Mar 10 09:03:38 2013 -0700
     7.3 @@ -7,10 +7,10 @@
     7.4  Android SDK (version 10 or later)
     7.5  http://developer.android.com/sdk/index.html
     7.6  
     7.7 -Android NDK r4 or later
     7.8 +Android NDK r7 or later
     7.9  http://developer.android.com/sdk/ndk/index.html
    7.10  
    7.11 -Minimum API Level supported by SDL: 10 (Android 2.3.3)
    7.12 +Minimum API level supported by SDL: 10 (Android 2.3.3)
    7.13  
    7.14  ================================================================================
    7.15   How the port works
    7.16 @@ -19,7 +19,7 @@
    7.17  - Android applications are Java-based, optionally with parts written in C
    7.18  - As SDL apps are C-based, we use a small Java shim that uses JNI to talk to 
    7.19  the SDL library
    7.20 -- This means that your application C code must be placed inside an android 
    7.21 +- This means that your application C code must be placed inside an Android 
    7.22  Java project, along with some C support code that communicates with Java
    7.23  - This eventually produces a standard Android .apk package
    7.24  
    7.25 @@ -60,8 +60,8 @@
    7.26  	build.properties	- empty
    7.27  	build.xml		- build description file, used by ant. The actual application name
    7.28  				  is specified here.
    7.29 -	default.properties	- holds the target ABI for the application, can range between
    7.30 -				  android-5 and android-16
    7.31 +	default.properties	- holds the target ABI for the application, android-10 and up
    7.32 +	project.properties	- holds the target ABI for the application, android-10 and up
    7.33  	local.properties	- holds the SDK path, you should change this to the path to your SDK
    7.34  	jni/			- directory holding native code
    7.35  	jni/Android.mk		- Android makefile that can call recursively the Android.mk files
    7.36 @@ -172,10 +172,10 @@
    7.37  under iOS, if the OS can not restore your GL context it will just kill your app)
    7.38  
    7.39  ================================================================================
    7.40 - Threads and the JAVA VM
    7.41 + Threads and the Java VM
    7.42  ================================================================================
    7.43  
    7.44 -For a quick tour on how Linux native threads interoperate with the JAVA VM, take
    7.45 +For a quick tour on how Linux native threads interoperate with the Java VM, take
    7.46  a look here: http://developer.android.com/guide/practices/jni.html
    7.47  If you want to use threads in your SDL app, it's strongly recommended that you
    7.48  do so by creating them using SDL functions. This way, the required attach/detach
    7.49 @@ -347,11 +347,16 @@
    7.50   Why is API level 10 the minimum required?
    7.51  ================================================================================
    7.52  
    7.53 -Support for OpenGL ES/ES2 applications was introduced in the NDK for API level 9, 
    7.54 -which has since then been obsoleted, with the recommendation to developers to 
    7.55 -bump the required level to 10.
    7.56 +API level 10 is required because SDL requires some functionality for running not
    7.57 +available on older devices and some for building which is not in older NDK/SDKs.
    7.58 +
    7.59 +Support for native OpenGL ES and ES2 applications was introduced in the NDK for
    7.60 +API level 4 and 8. EGL was made a stable API in the NDK for API level 9, which
    7.61 +has since then been obsoleted, with the recommendation to developers to bump the
    7.62 +required API level to 10.
    7.63  As of this writing, according to http://developer.android.com/about/dashboards/index.html
    7.64 -about 90% of the existing Android devices support an API level 10 or higher.
    7.65 +about 90% of the Android devices accessing Google Play support API level 10 or
    7.66 +higher (March 2013).
    7.67  
    7.68  ================================================================================
    7.69   A note regarding the use of the "dirty rectangles" rendering technique
     8.1 --- a/README.gesture	Sat Mar 09 10:35:12 2013 -0800
     8.2 +++ b/README.gesture	Sun Mar 10 09:03:38 2013 -0700
     8.3 @@ -16,7 +16,7 @@
     8.4  A SDL_DOLLARRECORD event is a dgesture with the following fields:
     8.5  
     8.6  event.dgesture.touchId   - the Id of the touch used to record the gesture.
     8.7 -event.dgesture.gestureId - the unique id of the recoreded gesture.
     8.8 +event.dgesture.gestureId - the unique id of the recorded gesture.
     8.9  
    8.10  
    8.11  Performing:
    8.12 @@ -28,7 +28,7 @@
    8.13  event.dgesture.error      - the difference between the gesture template and the actual performed gesture. Lower error is a better match.
    8.14  event.dgesture.numFingers - the number of fingers used to draw the stroke.
    8.15  
    8.16 -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). 
    8.17 +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).
    8.18  
    8.19  
    8.20  
    8.21 @@ -38,14 +38,14 @@
    8.22  
    8.23  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.
    8.24  
    8.25 -Both functions return the number of gestures sucessfully saved.
    8.26 +Both functions return the number of gestures successfully saved.
    8.27  
    8.28  
    8.29  Loading:
    8.30  --------
    8.31  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. 
    8.32  
    8.33 -SDL_LoadDollarTemplates returns the number of templates sucessfully loaded. 
    8.34 +SDL_LoadDollarTemplates returns the number of templates successfully loaded.
    8.35  
    8.36  
    8.37  
    8.38 @@ -56,8 +56,8 @@
    8.39  Every time a finger is moved an SDL_MULTIGESTURE event is sent with the following fields:
    8.40  
    8.41  event.mgesture.touchId - the Id of the touch on which the gesture was performed.
    8.42 -event.mgesture.x       - the normalized x cooridinate of the gesture. (0..1)
    8.43 -event.mgesture.y       - the normalized y cooridinate of the gesture. (0..1)
    8.44 +event.mgesture.x       - the normalized x coordinate of the gesture. (0..1)
    8.45 +event.mgesture.y       - the normalized y coordinate of the gesture. (0..1)
    8.46  event.mgesture.dTheta  - the amount that the fingers rotated during this motion.
    8.47  event.mgesture.dDist   - the amount that the fingers pinched during this motion.
    8.48  event.mgesture.numFingers - the number of fingers used in the gesture.
     9.1 --- a/README.pandora	Sat Mar 09 10:35:12 2013 -0800
     9.2 +++ b/README.pandora	Sun Mar 10 09:03:38 2013 -0700
     9.3 @@ -1,7 +1,7 @@
     9.4  SDL 2.0 with open pandora console support ( http://openpandora.org/ )
     9.5  =====================================================================
     9.6  
     9.7 -- A pandora specific video driver was writed to allow SDL 2.0 with OpenGL ES
     9.8 +- A pandora specific video driver was written to allow SDL 2.0 with OpenGL ES
     9.9  support to work on the pandora under the framebuffer. This driver do not have
    9.10  input support for now, so if you use it you will have to add your own control code.
    9.11  The video driver name is "pandora" so if you have problem running it from
    10.1 --- a/README.touch	Sat Mar 09 10:35:12 2013 -0800
    10.2 +++ b/README.touch	Sun Mar 10 09:03:38 2013 -0700
    10.3 @@ -5,7 +5,7 @@
    10.4  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.
    10.5  
    10.6  Mac: 
    10.7 -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.
    10.8 +The Mac and iPhone APIs 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.
    10.9  
   10.10  iPhone: 
   10.11  Works out of box.
   10.12 @@ -21,18 +21,18 @@
   10.13  Fields:
   10.14  event.tfinger.touchId  - the Id of the touch device.
   10.15  event.tfinger.fingerId - the Id of the finger which just went down.
   10.16 -event.tfinger.x        - the x coordinate of the touch (0..touch.xres)
   10.17 -event.tfinger.y        - the y coordinate of the touch (0..touch.yres)
   10.18 -event.tfinger.pressure - the pressure of the touch (0..touch.pressureres)
   10.19 +event.tfinger.x        - the x coordinate of the touch (0..1)
   10.20 +event.tfinger.y        - the y coordinate of the touch (0..1)
   10.21 +event.tfinger.pressure - the pressure of the touch (0..1)
   10.22  
   10.23  SDL_FINGERMOTION:
   10.24  Sent when a finger (or stylus) is moved on the touch device.
   10.25  Fields:
   10.26  Same as FINGERDOWN but with additional:
   10.27 -event.tfginer.dx       - change in x coordinate during this motion event.
   10.28 -event.tfginer.dy       - change in y coordinate during this motion event.
   10.29 +event.tfinger.dx       - change in x coordinate during this motion event.
   10.30 +event.tfinger.dy       - change in y coordinate during this motion event.
   10.31  
   10.32 -SDL_FINGERMOTION:
   10.33 +SDL_FINGERUP:
   10.34  Sent when a finger (or stylus) is lifted from the touch device.
   10.35  Fields:
   10.36  Same as FINGERDOWN.
   10.37 @@ -41,56 +41,38 @@
   10.38  ===========================================================================
   10.39  Functions
   10.40  ===========================================================================
   10.41 -SDL provides the ability to access the underlying Touch and Finger structures.
   10.42 +SDL provides the ability to access the underlying Finger structures.
   10.43  These structures should _never_ be modified.
   10.44  
   10.45 -The following functions are included from SDL_Touch.h
   10.46 +The following functions are included from SDL_touch.h
   10.47  
   10.48 -To get a SDL_Touch device call SDL_GetTouch(touchId). 
   10.49 -This returns an SDL_Touch*. 
   10.50 -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!
   10.51 +To get a SDL_TouchID call SDL_GetTouchDevice(index).
   10.52 +This returns a SDL_TouchID.
   10.53 +IMPORTANT: If the touch has been removed, or there is no touch with the given ID, SDL_GetTouchID will return 0. Be sure to check for this!
   10.54  
   10.55 -An SDL_Touch has the following fields:
   10.56 ->xres,yres,pressures:
   10.57 -	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. 
   10.58 +The number of touch devices can be queried with SDL_GetNumTouchDevices().
   10.59  
   10.60 ->pressure_max, pressure_min, x_max, x_min, y_max, y_min
   10.61 -	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.
   10.62 -On Mac/iPhone systems _max will always be 0, and _min will always be 1. 
   10.63 +A SDL_Touch may be used to get pointers to SDL_Finger.
   10.64  
   10.65 ->native_xres,native_yres,native_pressureres:
   10.66 -	The native resolution of the touch device AS REPORTED BY THE OPERATING SYSTEM.
   10.67 -On Mac/iPhone systems these will always be 1.
   10.68 +SDL_GetNumTouchFingers(touchID) may be used to get the number of fingers currently down on the device.
   10.69  
   10.70 ->num_fingers:
   10.71 -	The number of fingers currently down on the device.
   10.72 +The most common reason to access SDL_Finger is to query the fingers outside the event. In most cases accessing the fingers is using the event. This would be accomplished by code like the following:
   10.73  
   10.74 ->fingers:
   10.75 -	An array of pointers to the fingers which are on the device.
   10.76 +      float x = event.tfinger.x;
   10.77 +      float y = event.tfinger.y;
   10.78  
   10.79  
   10.80 -The most common reason to access a touch device is to normalize inputs. This would be accomplished by code like the following:
   10.81  
   10.82 -      SDL_Touch* inTouch = SDL_GetTouch(event.tfinger.touchId);
   10.83 -      if(inTouch == NULL) continue; //The touch has been removed
   10.84 +To get a SDL_Finger, call SDL_GetTouchFinger(touchID,index), where touchID is a SDL_TouchID, and index is the requested finger.
   10.85 +This returns a SDL_Finger*, or NULL if the finger does not exist, or has been removed.
   10.86 +A 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.
   10.87 +As a result, be very careful to check for NULL return values.
   10.88  
   10.89 -      float x = ((float)event.tfinger.x)/inTouch->xres;
   10.90 -      float y = ((float)event.tfinger.y)/inTouch->yres;
   10.91 -
   10.92 -
   10.93 -
   10.94 -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.
   10.95 -This returns an SDL_Finger*, or null if the finger does not exist, or has been removed.
   10.96 -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. 
   10.97 -As a result, be very careful to check for null return values.
   10.98 -
   10.99 -An SDL_Finger has the following fields:
  10.100 +A SDL_Finger has the following fields:
  10.101  >x,y,pressure:
  10.102  	The current coordinates of the touch.
  10.103 ->xdelta,ydelta: 
  10.104 -	The change in position resulting from the last finger motion.
  10.105 ->last_x, last_y, last_pressure:
  10.106 -	 The previous coordinates of the touch.
  10.107 +>pressure:
  10.108 +	The pressure of the touch.
  10.109  
  10.110  ===========================================================================
  10.111  Notes
  10.112 @@ -99,3 +81,4 @@
  10.113  
  10.114  Please direct questions/comments to:
  10.115     jim.tla+sdl_touch@gmail.com
  10.116 +   (original author, API was changed since)