README-android.md
1Android
2================================================================================
3
4Matt Styles wrote a tutorial on building SDL for Android with Visual Studio:
5http://trederia.blogspot.de/2017/03/building-sdl2-for-android-with-visual.html
6
7The rest of this README covers the Android gradle style build process.
8
9If you are using the older ant build process, it is no longer officially
10supported, but you can use the "android-project-ant" directory as a template.
11
12
13================================================================================
14 Requirements
15================================================================================
16
17Android SDK (version 26 or later)
18https://developer.android.com/sdk/index.html
19
20Android NDK r15c or later
21https://developer.android.com/tools/sdk/ndk/index.html
22
23Minimum API level supported by SDL: 16 (Android 4.1)
24
25
26================================================================================
27 How the port works
28================================================================================
29
30- Android applications are Java-based, optionally with parts written in C
31- As SDL apps are C-based, we use a small Java shim that uses JNI to talk to
32 the SDL library
33- This means that your application C code must be placed inside an Android
34 Java project, along with some C support code that communicates with Java
35- This eventually produces a standard Android .apk package
36
37The Android Java code implements an "Activity" and can be found in:
38android-project/app/src/main/java/org/libsdl/app/SDLActivity.java
39
40The Java code loads your game code, the SDL shared library, and
41dispatches to native functions implemented in the SDL library:
42src/core/android/SDL_android.c
43
44
45================================================================================
46 Building an app
47================================================================================
48
49For simple projects you can use the script located at build-scripts/androidbuild.sh
50
51There's two ways of using it:
52
53 androidbuild.sh com.yourcompany.yourapp < sources.list
54 androidbuild.sh com.yourcompany.yourapp source1.c source2.c ...sourceN.c
55
56sources.list should be a text file with a source file name in each line
57Filenames should be specified relative to the current directory, for example if
58you are in the build-scripts directory and want to create the testgles.c test, you'll
59run:
60
61 ./androidbuild.sh org.libsdl.testgles ../test/testgles.c
62
63One limitation of this script is that all sources provided will be aggregated into
64a single directory, thus all your source files should have a unique name.
65
66Once the project is complete the script will tell you where the debug APK is located.
67If you want to create a signed release APK, you can use the project created by this
68utility to generate it.
69
70Finally, a word of caution: re running androidbuild.sh wipes any changes you may have
71done in the build directory for the app!
72
73
74For more complex projects, follow these instructions:
75
761. Copy the android-project directory wherever you want to keep your projects
77 and rename it to the name of your project.
782. Move or symlink this SDL directory into the "<project>/app/jni" directory
793. Edit "<project>/app/jni/src/Android.mk" to include your source files
80
814a. If you want to use Android Studio, simply open your <project> directory and start building.
82
834b. If you want to build manually, run './gradlew installDebug' in the project directory. This compiles the .java, creates an .apk with the native code embedded, and installs it on any connected Android device
84
85
86If you already have a project that uses CMake, the instructions change somewhat:
87
881. Do points 1 and 2 from the instruction above.
892. Edit "<project>/app/build.gradle" to comment out or remove sections containing ndk-build
90 and uncomment the cmake sections. Add arguments to the CMake invocation as needed.
913. Edit "<project>/app/jni/CMakeLists.txt" to include your project (it defaults to
92 adding the "src" subdirectory). Note that you'll have SDL2, SDL2main and SDL2-static
93 as targets in your project, so you should have "target_link_libraries(yourgame SDL2 SDL2main)"
94 in your CMakeLists.txt file. Also be aware that you should use add_library() instead of
95 add_executable() for the target containing your "main" function.
96
97If you wish to use Android Studio, you can skip the last step.
98
994. Run './gradlew installDebug' or './gradlew installRelease' in the project directory. It will build and install your .apk on any
100 connected Android device
101
102Here's an explanation of the files in the Android project, so you can customize them:
103
104 android-project/app
105 build.gradle - build info including the application version and SDK
106 src/main/AndroidManifest.xml - package manifest. Among others, it contains the class name of the main Activity and the package name of the application.
107 jni/ - directory holding native code
108 jni/Application.mk - Application JNI settings, including target platform and STL library
109 jni/Android.mk - Android makefile that can call recursively the Android.mk files in all subdirectories
110 jni/CMakeLists.txt - Top-level CMake project that adds SDL as a subproject
111 jni/SDL/ - (symlink to) directory holding the SDL library files
112 jni/SDL/Android.mk - Android makefile for creating the SDL shared library
113 jni/src/ - directory holding your C/C++ source
114 jni/src/Android.mk - Android makefile that you should customize to include your source code and any library references
115 jni/src/CMakeLists.txt - CMake file that you may customize to include your source code and any library references
116 src/main/assets/ - directory holding asset files for your application
117 src/main/res/ - directory holding resources for your application
118 src/main/res/mipmap-* - directories holding icons for different phone hardware
119 src/main/res/values/strings.xml - strings used in your application, including the application name
120 src/main/java/org/libsdl/app/SDLActivity.java - the Java class handling the initialization and binding to SDL. Be very careful changing this, as the SDL library relies on this implementation. You should instead subclass this for your application.
121
122
123================================================================================
124 Customizing your application name
125================================================================================
126
127To customize your application name, edit AndroidManifest.xml and replace
128"org.libsdl.app" with an identifier for your product package.
129
130Then create a Java class extending SDLActivity and place it in a directory
131under src matching your package, e.g.
132
133 src/com/gamemaker/game/MyGame.java
134
135Here's an example of a minimal class file:
136
137 --- MyGame.java --------------------------
138 package com.gamemaker.game;
139
140 import org.libsdl.app.SDLActivity;
141
142 /**
143 * A sample wrapper class that just calls SDLActivity
144 */
145
146 public class MyGame extends SDLActivity { }
147
148 ------------------------------------------
149
150Then replace "SDLActivity" in AndroidManifest.xml with the name of your
151class, .e.g. "MyGame"
152
153
154================================================================================
155 Customizing your application icon
156================================================================================
157
158Conceptually changing your icon is just replacing the "ic_launcher.png" files in
159the drawable directories under the res directory. There are several directories
160for different screen sizes.
161
162
163================================================================================
164 Loading assets
165================================================================================
166
167Any files you put in the "app/src/main/assets" directory of your project
168directory will get bundled into the application package and you can load
169them using the standard functions in SDL_rwops.h.
170
171There are also a few Android specific functions that allow you to get other
172useful paths for saving and loading data:
173* SDL_AndroidGetInternalStoragePath()
174* SDL_AndroidGetExternalStorageState()
175* SDL_AndroidGetExternalStoragePath()
176
177See SDL_system.h for more details on these functions.
178
179The asset packaging system will, by default, compress certain file extensions.
180SDL includes two asset file access mechanisms, the preferred one is the so
181called "File Descriptor" method, which is faster and doesn't involve the Dalvik
182GC, but given this method does not work on compressed assets, there is also the
183"Input Stream" method, which is automatically used as a fall back by SDL. You
184may want to keep this fact in mind when building your APK, specially when large
185files are involved.
186For more information on which extensions get compressed by default and how to
187disable this behaviour, see for example:
188
189http://ponystyle.com/blog/2010/03/26/dealing-with-asset-compression-in-android-apps/
190
191
192================================================================================
193 Pause / Resume behaviour
194================================================================================
195
196If SDL_HINT_ANDROID_BLOCK_ON_PAUSE hint is set (the default),
197the event loop will block itself when the app is paused (ie, when the user
198returns to the main Android dashboard). Blocking is better in terms of battery
199use, and it allows your app to spring back to life instantaneously after resume
200(versus polling for a resume message).
201
202Upon resume, SDL will attempt to restore the GL context automatically.
203In modern devices (Android 3.0 and up) this will most likely succeed and your
204app can continue to operate as it was.
205
206However, there's a chance (on older hardware, or on systems under heavy load),
207where the GL context can not be restored. In that case you have to listen for
208a specific message, (which is not yet implemented!) and restore your textures
209manually or quit the app (which is actually the kind of behaviour you'll see
210under iOS, if the OS can not restore your GL context it will just kill your app)
211
212
213================================================================================
214 Threads and the Java VM
215================================================================================
216
217For a quick tour on how Linux native threads interoperate with the Java VM, take
218a look here: https://developer.android.com/guide/practices/jni.html
219
220If you want to use threads in your SDL app, it's strongly recommended that you
221do so by creating them using SDL functions. This way, the required attach/detach
222handling is managed by SDL automagically. If you have threads created by other
223means and they make calls to SDL functions, make sure that you call
224Android_JNI_SetupThread() before doing anything else otherwise SDL will attach
225your thread automatically anyway (when you make an SDL call), but it'll never
226detach it.
227
228
229================================================================================
230 Using STL
231================================================================================
232
233You can use STL in your project by creating an Application.mk file in the jni
234folder and adding the following line:
235
236 APP_STL := c++_shared
237
238For more information go here:
239 https://developer.android.com/ndk/guides/cpp-support
240
241
242================================================================================
243 Using the emulator
244================================================================================
245
246There are some good tips and tricks for getting the most out of the
247emulator here: https://developer.android.com/tools/devices/emulator.html
248
249Especially useful is the info on setting up OpenGL ES 2.0 emulation.
250
251Notice that this software emulator is incredibly slow and needs a lot of disk space.
252Using a real device works better.
253
254
255================================================================================
256 Troubleshooting
257================================================================================
258
259You can see if adb can see any devices with the following command:
260
261 adb devices
262
263You can see the output of log messages on the default device with:
264
265 adb logcat
266
267You can push files to the device with:
268
269 adb push local_file remote_path_and_file
270
271You can push files to the SD Card at /sdcard, for example:
272
273 adb push moose.dat /sdcard/moose.dat
274
275You can see the files on the SD card with a shell command:
276
277 adb shell ls /sdcard/
278
279You can start a command shell on the default device with:
280
281 adb shell
282
283You can remove the library files of your project (and not the SDL lib files) with:
284
285 ndk-build clean
286
287You can do a build with the following command:
288
289 ndk-build
290
291You can see the complete command line that ndk-build is using by passing V=1 on the command line:
292
293 ndk-build V=1
294
295If your application crashes in native code, you can use ndk-stack to get a symbolic stack trace:
296 https://developer.android.com/ndk/guides/ndk-stack
297
298If you want to go through the process manually, you can use addr2line to convert the
299addresses in the stack trace to lines in your code.
300
301For example, if your crash looks like this:
302
303 I/DEBUG ( 31): signal 11 (SIGSEGV), code 2 (SEGV_ACCERR), fault addr 400085d0
304 I/DEBUG ( 31): r0 00000000 r1 00001000 r2 00000003 r3 400085d4
305 I/DEBUG ( 31): r4 400085d0 r5 40008000 r6 afd41504 r7 436c6a7c
306 I/DEBUG ( 31): r8 436c6b30 r9 435c6fb0 10 435c6f9c fp 4168d82c
307 I/DEBUG ( 31): ip 8346aff0 sp 436c6a60 lr afd1c8ff pc afd1c902 cpsr 60000030
308 I/DEBUG ( 31): #00 pc 0001c902 /system/lib/libc.so
309 I/DEBUG ( 31): #01 pc 0001ccf6 /system/lib/libc.so
310 I/DEBUG ( 31): #02 pc 000014bc /data/data/org.libsdl.app/lib/libmain.so
311 I/DEBUG ( 31): #03 pc 00001506 /data/data/org.libsdl.app/lib/libmain.so
312
313You can see that there's a crash in the C library being called from the main code.
314I run addr2line with the debug version of my code:
315
316 arm-eabi-addr2line -C -f -e obj/local/armeabi/libmain.so
317
318and then paste in the number after "pc" in the call stack, from the line that I care about:
319000014bc
320
321I get output from addr2line showing that it's in the quit function, in testspriteminimal.c, on line 23.
322
323You can add logging to your code to help show what's happening:
324
325 #include <android/log.h>
326
327 __android_log_print(ANDROID_LOG_INFO, "foo", "Something happened! x = %d", x);
328
329If you need to build without optimization turned on, you can create a file called
330"Application.mk" in the jni directory, with the following line in it:
331
332 APP_OPTIM := debug
333
334
335================================================================================
336 Memory debugging
337================================================================================
338
339The best (and slowest) way to debug memory issues on Android is valgrind.
340Valgrind has support for Android out of the box, just grab code using:
341
342 svn co svn://svn.valgrind.org/valgrind/trunk valgrind
343
344... and follow the instructions in the file README.android to build it.
345
346One thing I needed to do on Mac OS X was change the path to the toolchain,
347and add ranlib to the environment variables:
348export RANLIB=$NDKROOT/toolchains/arm-linux-androideabi-4.4.3/prebuilt/darwin-x86/bin/arm-linux-androideabi-ranlib
349
350Once valgrind is built, you can create a wrapper script to launch your
351application with it, changing org.libsdl.app to your package identifier:
352
353 --- start_valgrind_app -------------------
354 #!/system/bin/sh
355 export TMPDIR=/data/data/org.libsdl.app
356 exec /data/local/Inst/bin/valgrind --log-file=/sdcard/valgrind.log --error-limit=no $*
357 ------------------------------------------
358
359Then push it to the device:
360
361 adb push start_valgrind_app /data/local
362
363and make it executable:
364
365 adb shell chmod 755 /data/local/start_valgrind_app
366
367and tell Android to use the script to launch your application:
368
369 adb shell setprop wrap.org.libsdl.app "logwrapper /data/local/start_valgrind_app"
370
371If the setprop command says "could not set property", it's likely that
372your package name is too long and you should make it shorter by changing
373AndroidManifest.xml and the path to your class file in android-project/src
374
375You can then launch your application normally and waaaaaaaiiittt for it.
376You can monitor the startup process with the logcat command above, and
377when it's done (or even while it's running) you can grab the valgrind
378output file:
379
380 adb pull /sdcard/valgrind.log
381
382When you're done instrumenting with valgrind, you can disable the wrapper:
383
384 adb shell setprop wrap.org.libsdl.app ""
385
386
387================================================================================
388 Graphics debugging
389================================================================================
390
391If you are developing on a compatible Tegra-based tablet, NVidia provides
392Tegra Graphics Debugger at their website. Because SDL2 dynamically loads EGL
393and GLES libraries, you must follow their instructions for installing the
394interposer library on a rooted device. The non-rooted instructions are not
395compatible with applications that use SDL2 for video.
396
397The Tegra Graphics Debugger is available from NVidia here:
398https://developer.nvidia.com/tegra-graphics-debugger
399
400
401================================================================================
402 Why is API level 16 the minimum required?
403================================================================================
404
405The latest NDK toolchain doesn't support targeting earlier than API level 16.
406As of this writing, according to https://developer.android.com/about/dashboards/index.html
407about 99% of the Android devices accessing Google Play support API level 16 or
408higher (January 2018).
409
410
411================================================================================
412 A note regarding the use of the "dirty rectangles" rendering technique
413================================================================================
414
415If your app uses a variation of the "dirty rectangles" rendering technique,
416where you only update a portion of the screen on each frame, you may notice a
417variety of visual glitches on Android, that are not present on other platforms.
418This is caused by SDL's use of EGL as the support system to handle OpenGL ES/ES2
419contexts, in particular the use of the eglSwapBuffers function. As stated in the
420documentation for the function "The contents of ancillary buffers are always
421undefined after calling eglSwapBuffers".
422Setting the EGL_SWAP_BEHAVIOR attribute of the surface to EGL_BUFFER_PRESERVED
423is not possible for SDL as it requires EGL 1.4, available only on the API level
42417+, so the only workaround available on this platform is to redraw the entire
425screen each frame.
426
427Reference: http://www.khronos.org/registry/egl/specs/EGLTechNote0001.html
428
429
430================================================================================
431 Ending your application
432================================================================================
433
434Two legitimate ways:
435
436- return from your main() function. Java side will automatically terminate the
437Activity by calling Activity.finish().
438
439- Android OS can decide to terminate your application by calling onDestroy()
440(see Activity life cycle). Your application will receive a SDL_QUIT event you
441can handle to save things and quit.
442
443Don't call exit() as it stops the activity badly.
444
445NB: "Back button" can be handled as a SDL_KEYDOWN/UP events, with Keycode
446SDLK_AC_BACK, for any purpose.
447
448================================================================================
449 Known issues
450================================================================================
451
452- The number of buttons reported for each joystick is hardcoded to be 36, which
453is the current maximum number of buttons Android can report.
454
455
README-cmake.md
1CMake
2================================================================================
3(www.cmake.org)
4
5SDL's build system was traditionally based on autotools. Over time, this
6approach has suffered from several issues across the different supported
7platforms.
8To solve these problems, a new build system based on CMake is under development.
9It works in parallel to the legacy system, so users can experiment with it
10without complication.
11While still experimental, the build system should be usable on the following
12platforms:
13
14* FreeBSD
15* Linux
16* VS.NET 2010
17* MinGW and Msys
18* macOS, iOS, and tvOS, with support for XCode
19
20
21================================================================================
22Usage
23================================================================================
24
25Assuming the source for SDL is located at ~/sdl
26
27 cd ~
28 mkdir build
29 cd build
30 cmake ../sdl
31
32This will build the static and dynamic versions of SDL in the ~/build directory.
33
34
35================================================================================
36Usage, iOS/tvOS
37================================================================================
38
39CMake 3.14+ natively includes support for iOS and tvOS. SDL binaries may be built
40using Xcode or Make, possibly among other build-systems.
41
42When using a recent version of CMake (3.14+), it should be possible to:
43
44- build SDL for iOS, both static and dynamic
45- build SDL test apps (as iOS/tvOS .app bundles)
46- generate a working SDL_config.h for iOS (using SDL_config.h.cmake as a basis)
47
48To use, set the following CMake variables when running CMake's configuration stage:
49
50- `CMAKE_SYSTEM_NAME=<OS>` (either `iOS` or `tvOS`)
51- `CMAKE_OSX_SYSROOT=<SDK>` (examples: `iphoneos`, `iphonesimulator`, `iphoneos12.4`, `/full/path/to/iPhoneOS.sdk`,
52 `appletvos`, `appletvsimulator`, `appletvos12.4`, `/full/path/to/AppleTVOS.sdk`, etc.)
53- `CMAKE_OSX_ARCHITECTURES=<semicolon-separated list of CPU architectures>` (example: "arm64;armv7s;x86_64")
54
55
56### Examples (for iOS/tvOS):
57
58- for iOS-Simulator, using the latest, installed SDK:
59
60 `cmake ~/sdl -DCMAKE_SYSTEM_NAME=iOS -DCMAKE_OSX_SYSROOT=iphonesimulator -DCMAKE_OSX_ARCHITECTURES=x86_64`
61
62- for iOS-Device, using the latest, installed SDK, 64-bit only
63
64 `cmake ~/sdl -DCMAKE_SYSTEM_NAME=iOS -DCMAKE_OSX_SYSROOT=iphoneos -DCMAKE_OSX_ARCHITECTURES=arm64`
65
66- for iOS-Device, using the latest, installed SDK, mixed 32/64 bit
67
68 `cmake ~/sdl -DCMAKE_SYSTEM_NAME=iOS -DCMAKE_OSX_SYSROOT=iphoneos -DCMAKE_OSX_ARCHITECTURES="arm64;armv7s"`
69
70- for iOS-Device, using a specific SDK revision (iOS 12.4, in this example):
71
72 `cmake ~/sdl -DCMAKE_SYSTEM_NAME=iOS -DCMAKE_OSX_SYSROOT=iphoneos12.4 -DCMAKE_OSX_ARCHITECTURES=arm64`
73
74- for iOS-Simulator, using the latest, installed SDK, and building SDL test apps (as .app bundles):
75
76 `cmake ~/sdl -DSDL_TEST=1 -DCMAKE_SYSTEM_NAME=iOS -DCMAKE_OSX_SYSROOT=iphonesimulator -DCMAKE_OSX_ARCHITECTURES=x86_64`
77
78- for tvOS-Simulator, using the latest, installed SDK:
79
80 `cmake ~/sdl -DCMAKE_SYSTEM_NAME=tvOS -DCMAKE_OSX_SYSROOT=appletvsimulator -DCMAKE_OSX_ARCHITECTURES=x86_64`
81
82- for tvOS-Device, using the latest, installed SDK:
83
84 `cmake ~/sdl -DCMAKE_SYSTEM_NAME=tvOS -DCMAKE_OSX_SYSROOT=appletvos -DCMAKE_OSX_ARCHITECTURES=arm64`
85
README-directfb.md
1DirectFB
2========
3
4Supports:
5
6- Hardware YUV overlays
7- OpenGL - software only
8- 2D/3D accelerations (depends on directfb driver)
9- multiple displays
10- windows
11
12What you need:
13
14* DirectFB 1.0.1, 1.2.x, 1.3.0
15* Kernel-Framebuffer support: required: vesafb, radeonfb ....
16* Mesa 7.0.x - optional for OpenGL
17
18/etc/directfbrc
19
20This file should contain the following lines to make
21your joystick work and avoid crashes:
22------------------------
23disable-module=joystick
24disable-module=cle266
25disable-module=cyber5k
26no-linux-input-grab
27------------------------
28
29To disable to use x11 backend when DISPLAY variable is found use
30
31export SDL_DIRECTFB_X11_CHECK=0
32
33To disable the use of linux input devices, i.e. multimice/multikeyboard support,
34use
35
36export SDL_DIRECTFB_LINUX_INPUT=0
37
38To use hardware accelerated YUV-overlays for YUV-textures, use:
39
40export SDL_DIRECTFB_YUV_DIRECT=1
41
42This is disabled by default. It will only support one
43YUV texture, namely the first. Every other YUV texture will be
44rendered in software.
45
46In addition, you may use (directfb-1.2.x)
47
48export SDL_DIRECTFB_YUV_UNDERLAY=1
49
50to make the YUV texture an underlay. This will make the cursor to
51be shown.
52
53Simple Window Manager
54=====================
55
56The driver has support for a very, very basic window manager you may
57want to use when running with "wm=default". Use
58
59export SDL_DIRECTFB_WM=1
60
61to enable basic window borders. In order to have the window title rendered,
62you need to have the following font installed:
63
64/usr/share/fonts/truetype/freefont/FreeSans.ttf
65
66OpenGL Support
67==============
68
69The following instructions will give you *software* OpenGL. However this
70works at least on all directfb supported platforms.
71
72As of this writing 20100802 you need to pull Mesa from git and do the following:
73
74------------------------
75git clone git://anongit.freedesktop.org/git/mesa/mesa
76cd mesa
77git checkout 2c9fdaf7292423c157fc79b5ce43f0f199dd753a
78------------------------
79
80Edit configs/linux-directfb so that the Directories-section looks like
81------------------------
82# Directories
83SRC_DIRS = mesa glu
84GLU_DIRS = sgi
85DRIVER_DIRS = directfb
86PROGRAM_DIRS =
87------------------------
88
89make linux-directfb
90make
91
92echo Installing - please enter sudo pw.
93
94sudo make install INSTALL_DIR=/usr/local/dfb_GL
95cd src/mesa/drivers/directfb
96make
97sudo make install INSTALL_DIR=/usr/local/dfb_GL
98------------------------
99
100To run the SDL - testprograms:
101
102export SDL_VIDEODRIVER=directfb
103export LD_LIBRARY_PATH=/usr/local/dfb_GL/lib
104export LD_PRELOAD=/usr/local/dfb_GL/libGL.so.7
105
106./testgl
107
108
README-dynapi.md
1Dynamic API
2================================================================================
3Originally posted by Ryan at:
4 https://plus.google.com/103391075724026391227/posts/TB8UfnDYu4U
5
6Background:
7
8- The Steam Runtime has (at least in theory) a really kick-ass build of SDL2,
9 but developers are shipping their own SDL2 with individual Steam games.
10 These games might stop getting updates, but a newer SDL2 might be needed later.
11 Certainly we'll always be fixing bugs in SDL, even if a new video target isn't
12 ever needed, and these fixes won't make it to a game shipping its own SDL.
13- Even if we replace the SDL2 in those games with a compatible one, that is to
14 say, edit a developer's Steam depot (yuck!), there are developers that are
15 statically linking SDL2 that we can't do this for. We can't even force the
16 dynamic loader to ignore their SDL2 in this case, of course.
17- If you don't ship an SDL2 with the game in some form, people that disabled the
18 Steam Runtime, or just tried to run the game from the command line instead of
19 Steam might find themselves unable to run the game, due to a missing dependency.
20- If you want to ship on non-Steam platforms like GOG or Humble Bundle, or target
21 generic Linux boxes that may or may not have SDL2 installed, you have to ship
22 the library or risk a total failure to launch. So now, you might have to have
23 a non-Steam build plus a Steam build (that is, one with and one without SDL2
24 included), which is inconvenient if you could have had one universal build
25 that works everywhere.
26- We like the zlib license, but the biggest complaint from the open source
27 community about the license change is the static linking. The LGPL forced this
28 as a legal, not technical issue, but zlib doesn't care. Even those that aren't
29 concerned about the GNU freedoms found themselves solving the same problems:
30 swapping in a newer SDL to an older game often times can save the day.
31 Static linking stops this dead.
32
33So here's what we did:
34
35SDL now has, internally, a table of function pointers. So, this is what SDL_Init
36now looks like:
37
38 UInt32 SDL_Init(Uint32 flags)
39 {
40 return jump_table.SDL_Init(flags);
41 }
42
43Except that is all done with a bunch of macro magic so we don't have to maintain
44every one of these.
45
46What is jump_table.SDL_init()? Eventually, that's a function pointer of the real
47SDL_Init() that you've been calling all this time. But at startup, it looks more
48like this:
49
50 Uint32 SDL_Init_DEFAULT(Uint32 flags)
51 {
52 SDL_InitDynamicAPI();
53 return jump_table.SDL_Init(flags);
54 }
55
56SDL_InitDynamicAPI() fills in jump_table with all the actual SDL function
57pointers, which means that this _DEFAULT function never gets called again.
58First call to any SDL function sets the whole thing up.
59
60So you might be asking, what was the value in that? Isn't this what the operating
61system's dynamic loader was supposed to do for us? Yes, but now we've got this
62level of indirection, we can do things like this:
63
64 export SDL_DYNAMIC_API=/my/actual/libSDL-2.0.so.0
65 ./MyGameThatIsStaticallyLinkedToSDL2
66
67And now, this game that is statically linked to SDL, can still be overridden
68with a newer, or better, SDL. The statically linked one will only be used as
69far as calling into the jump table in this case. But in cases where no override
70is desired, the statically linked version will provide its own jump table,
71and everyone is happy.
72
73So now:
74- Developers can statically link SDL, and users can still replace it.
75 (We'd still rather you ship a shared library, though!)
76- Developers can ship an SDL with their game, Valve can override it for, say,
77 new features on SteamOS, or distros can override it for their own needs,
78 but it'll also just work in the default case.
79- Developers can ship the same package to everyone (Humble Bundle, GOG, etc),
80 and it'll do the right thing.
81- End users (and Valve) can update a game's SDL in almost any case,
82 to keep abandoned games running on newer platforms.
83- Everyone develops with SDL exactly as they have been doing all along.
84 Same headers, same ABI. Just get the latest version to enable this magic.
85
86
87A little more about SDL_InitDynamicAPI():
88
89Internally, InitAPI does some locking to make sure everything waits until a
90single thread initializes everything (although even SDL_CreateThread() goes
91through here before spinning a thread, too), and then decides if it should use
92an external SDL library. If not, it sets up the jump table using the current
93SDL's function pointers (which might be statically linked into a program, or in
94a shared library of its own). If so, it loads that library and looks for and
95calls a single function:
96
97 SInt32 SDL_DYNAPI_entry(Uint32 version, void *table, Uint32 tablesize);
98
99That function takes a version number (more on that in a moment), the address of
100the jump table, and the size, in bytes, of the table.
101Now, we've got policy here: this table's layout never changes; new stuff gets
102added to the end. Therefore SDL_DYNAPI_entry() knows that it can provide all
103the needed functions if tablesize <= sizeof its own jump table. If tablesize is
104bigger (say, SDL 2.0.4 is trying to load SDL 2.0.3), then we know to abort, but
105if it's smaller, we know we can provide the entire API that the caller needs.
106
107The version variable is a failsafe switch.
108Right now it's always 1. This number changes when there are major API changes
109(so we know if the tablesize might be smaller, or entries in it have changed).
110Right now SDL_DYNAPI_entry gives up if the version doesn't match, but it's not
111inconceivable to have a small dispatch library that only supplies this one
112function and loads different, otherwise-incompatible SDL libraries and has the
113right one initialize the jump table based on the version. For something that
114must generically catch lots of different versions of SDL over time, like the
115Steam Client, this isn't a bad option.
116
117Finally, I'm sure some people are reading this and thinking,
118"I don't want that overhead in my project!"
119To which I would point out that the extra function call through the jump table
120probably wouldn't even show up in a profile, but lucky you: this can all be
121disabled. You can build SDL without this if you absolutely must, but we would
122encourage you not to do that. However, on heavily locked down platforms like
123iOS, or maybe when debugging, it makes sense to disable it. The way this is
124designed in SDL, you just have to change one #define, and the entire system
125vaporizes out, and SDL functions exactly like it always did. Most of it is
126macro magic, so the system is contained to one C file and a few headers.
127However, this is on by default and you have to edit a header file to turn it
128off. Our hopes is that if we make it easy to disable, but not too easy,
129everyone will ultimately be able to get what they want, but we've gently
130nudged everyone towards what we think is the best solution.
131
README-gesture.md
1Dollar Gestures
2===========================================================================
3SDL provides an implementation of the $1 gesture recognition system. This allows for recording, saving, loading, and performing single stroke gestures.
4
5Gestures 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.
6
7Dollar 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.
8
9Recording:
10----------
11To begin recording on a touch device call:
12SDL_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.
13
14Recording terminates as soon as a finger comes up. Recording is acknowledged by an SDL_DOLLARRECORD event.
15A SDL_DOLLARRECORD event is a dgesture with the following fields:
16
17* event.dgesture.touchId - the Id of the touch used to record the gesture.
18* event.dgesture.gestureId - the unique id of the recorded gesture.
19
20
21Performing:
22-----------
23As 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:
24
25* event.dgesture.touchId - the Id of the touch which performed the gesture.
26* event.dgesture.gestureId - the unique id of the closest gesture to the performed stroke.
27* event.dgesture.error - the difference between the gesture template and the actual performed gesture. Lower error is a better match.
28* event.dgesture.numFingers - the number of fingers used to draw the stroke.
29
30Most 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).
31
32
33
34Saving:
35-------
36To save a template, call SDL_SaveDollarTemplate(gestureId, dst) where gestureId is the id of the gesture you want to save, and dst is an SDL_RWops pointer to the file where the gesture will be stored.
37
38To save all currently loaded templates, call SDL_SaveAllDollarTemplates(dst) where dst is an SDL_RWops pointer to the file where the gesture will be stored.
39
40Both functions return the number of gestures successfully saved.
41
42
43Loading:
44--------
45To 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.
46
47SDL_LoadDollarTemplates returns the number of templates successfully loaded.
48
49
50
51===========================================================================
52Multi Gestures
53===========================================================================
54SDL provides simple support for pinch/rotate/swipe gestures.
55Every time a finger is moved an SDL_MULTIGESTURE event is sent with the following fields:
56
57* event.mgesture.touchId - the Id of the touch on which the gesture was performed.
58* event.mgesture.x - the normalized x coordinate of the gesture. (0..1)
59* event.mgesture.y - the normalized y coordinate of the gesture. (0..1)
60* event.mgesture.dTheta - the amount that the fingers rotated during this motion.
61* event.mgesture.dDist - the amount that the fingers pinched during this motion.
62* event.mgesture.numFingers - the number of fingers used in the gesture.
63
64
65===========================================================================
66Notes
67===========================================================================
68For a complete example see test/testgesture.c
69
70Please direct questions/comments to:
71 jim.tla+sdl_touch@gmail.com
72
README-hg.md
1Mercurial
2=========
3
4The latest development version of SDL is available via Mercurial.
5Mercurial allows you to get up-to-the-minute fixes and enhancements;
6as a developer works on a source tree, you can use "hg" to mirror that
7source tree instead of waiting for an official release. Please look
8at the Mercurial website ( https://www.mercurial-scm.org/ ) for more
9information on using hg, where you can also download software for
10Mac OS X, Windows, and Unix systems.
11
12 hg clone http://hg.libsdl.org/SDL
13
14If you are building SDL via configure, you will need to run autogen.sh
15before running configure.
16
17There is a web interface to the subversion repository at:
18 http://hg.libsdl.org/SDL/
19
20There is an RSS feed available at that URL, for those that want to
21track commits in real time.
22
23
README-ios.md
1iOS
2======
3
4==============================================================================
5Building the Simple DirectMedia Layer for iOS 5.1+
6==============================================================================
7
8Requirements: Mac OS X 10.8 or later and the iOS 7+ SDK.
9
10Instructions:
11
121. Open SDL.xcodeproj (located in Xcode-iOS/SDL) in Xcode.
132. Select your desired target, and hit build.
14
15There are three build targets:
16- libSDL.a:
17 Build SDL as a statically linked library
18- testsdl:
19 Build a test program (there are known test failures which are fine)
20- Template:
21 Package a project template together with the SDL for iPhone static libraries and copies of the SDL headers. The template includes proper references to the SDL library and headers, skeleton code for a basic SDL program, and placeholder graphics for the application icon and startup screen.
22
23
24==============================================================================
25Build SDL for iOS from the command line
26==============================================================================
27
281. cd (PATH WHERE THE SDL CODE IS)/build-scripts
292. ./iosbuild.sh
30
31If everything goes fine, you should see a build/ios directory, inside there's
32two directories "lib" and "include".
33"include" contains a copy of the SDL headers that you'll need for your project,
34make sure to configure XCode to look for headers there.
35"lib" contains find two files, libSDL2.a and libSDL2main.a, you have to add both
36to your XCode project. These libraries contain three architectures in them,
37armv6 for legacy devices, armv7, and i386 (for the simulator).
38By default, iosbuild.sh will autodetect the SDK version you have installed using
39xcodebuild -showsdks, and build for iOS >= 3.0, you can override this behaviour
40by setting the MIN_OS_VERSION variable, ie:
41
42MIN_OS_VERSION=4.2 ./iosbuild.sh
43
44==============================================================================
45Using the Simple DirectMedia Layer for iOS
46==============================================================================
47
48FIXME: This needs to be updated for the latest methods
49
50Here is the easiest method:
511. Build the SDL library (libSDL2.a) and the iPhone SDL Application template.
522. Install the iPhone SDL Application template by copying it to one of Xcode's template directories. I recommend creating a directory called "SDL" in "/Developer/Platforms/iOS.platform/Developer/Library/Xcode/Project Templates/" and placing it there.
533. Start a new project using the template. The project should be immediately ready for use with SDL.
54
55Here is a more manual method:
561. Create a new iOS view based application.
572. Build the SDL static library (libSDL2.a) for iOS and include them in your project. Xcode will ignore the library that is not currently of the correct architecture, hence your app will work both on iOS and in the iOS Simulator.
583. Include the SDL header files in your project.
594. Remove the ApplicationDelegate.h and ApplicationDelegate.m files -- SDL for iOS provides its own UIApplicationDelegate. Remove MainWindow.xib -- SDL for iOS produces its user interface programmatically.
605. 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.
61
62==============================================================================
63Notes -- Retina / High-DPI and window sizes
64==============================================================================
65
66Window and display mode sizes in SDL are in "screen coordinates" (or "points",
67in Apple's terminology) rather than in pixels. On iOS this means that a window
68created on an iPhone 6 will have a size in screen coordinates of 375 x 667,
69rather than a size in pixels of 750 x 1334. All iOS apps are expected to
70size their content based on screen coordinates / points rather than pixels,
71as this allows different iOS devices to have different pixel densities
72(Retina versus non-Retina screens, etc.) without apps caring too much.
73
74By default SDL will not use the full pixel density of the screen on
75Retina/high-dpi capable devices. Use the SDL_WINDOW_ALLOW_HIGHDPI flag when
76creating your window to enable high-dpi support.
77
78When high-dpi support is enabled, SDL_GetWindowSize() and display mode sizes
79will still be in "screen coordinates" rather than pixels, but the window will
80have a much greater pixel density when the device supports it, and the
81SDL_GL_GetDrawableSize() or SDL_GetRendererOutputSize() functions (depending on
82whether raw OpenGL or the SDL_Render API is used) can be queried to determine
83the size in pixels of the drawable screen framebuffer.
84
85Some OpenGL ES functions such as glViewport expect sizes in pixels rather than
86sizes in screen coordinates. When doing 2D rendering with OpenGL ES, an
87orthographic projection matrix using the size in screen coordinates
88(SDL_GetWindowSize()) can be used in order to display content at the same scale
89no matter whether a Retina device is used or not.
90
91==============================================================================
92Notes -- Application events
93==============================================================================
94
95On iOS the application goes through a fixed life cycle and you will get
96notifications of state changes via application events. When these events
97are delivered you must handle them in an event callback because the OS may
98not give you any processing time after the events are delivered.
99
100e.g.
101
102 int HandleAppEvents(void *userdata, SDL_Event *event)
103 {
104 switch (event->type)
105 {
106 case SDL_APP_TERMINATING:
107 /* Terminate the app.
108 Shut everything down before returning from this function.
109 */
110 return 0;
111 case SDL_APP_LOWMEMORY:
112 /* You will get this when your app is paused and iOS wants more memory.
113 Release as much memory as possible.
114 */
115 return 0;
116 case SDL_APP_WILLENTERBACKGROUND:
117 /* Prepare your app to go into the background. Stop loops, etc.
118 This gets called when the user hits the home button, or gets a call.
119 */
120 return 0;
121 case SDL_APP_DIDENTERBACKGROUND:
122 /* This will get called if the user accepted whatever sent your app to the background.
123 If the user got a phone call and canceled it, you'll instead get an SDL_APP_DIDENTERFOREGROUND event and restart your loops.
124 When you get this, you have 5 seconds to save all your state or the app will be terminated.
125 Your app is NOT active at this point.
126 */
127 return 0;
128 case SDL_APP_WILLENTERFOREGROUND:
129 /* This call happens when your app is coming back to the foreground.
130 Restore all your state here.
131 */
132 return 0;
133 case SDL_APP_DIDENTERFOREGROUND:
134 /* Restart your loops here.
135 Your app is interactive and getting CPU again.
136 */
137 return 0;
138 default:
139 /* No special processing, add it to the event queue */
140 return 1;
141 }
142 }
143
144 int main(int argc, char *argv[])
145 {
146 SDL_SetEventFilter(HandleAppEvents, NULL);
147
148 ... run your main loop
149
150 return 0;
151 }
152
153
154==============================================================================
155Notes -- Accelerometer as Joystick
156==============================================================================
157
158SDL for iPhone supports polling the built in accelerometer as a joystick device. For an example on how to do this, see the accelerometer.c in the demos directory.
159
160The main thing to note when using the accelerometer with SDL is that while the iPhone natively reports accelerometer as floating point values in units of g-force, SDL_JoystickGetAxis() reports joystick values as signed integers. Hence, in order to convert between the two, some clamping and scaling is necessary on the part of the iPhone SDL joystick driver. To convert SDL_JoystickGetAxis() reported values BACK to units of g-force, simply multiply the values by SDL_IPHONE_MAX_GFORCE / 0x7FFF.
161
162==============================================================================
163Notes -- OpenGL ES
164==============================================================================
165
166Your SDL application for iOS uses OpenGL ES for video by default.
167
168OpenGL ES for iOS 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().
169
170If your application doesn't use OpenGL's depth buffer, you may find significant performance improvement by setting SDL_GL_DEPTH_SIZE to 0.
171
172Finally, if your application completely redraws the screen each frame, you may find significant performance improvement by setting the attribute SDL_GL_RETAINED_BACKING to 0.
173
174OpenGL ES on iOS doesn't use the traditional system-framebuffer setup provided in other operating systems. Special care must be taken because of this:
175
176- The drawable Renderbuffer must be bound to the GL_RENDERBUFFER binding point when SDL_GL_SwapWindow() is called.
177- The drawable Framebuffer Object must be bound while rendering to the screen and when SDL_GL_SwapWindow() is called.
178- If multisample antialiasing (MSAA) is used and glReadPixels is used on the screen, the drawable framebuffer must be resolved to the MSAA resolve framebuffer (via glBlitFramebuffer or glResolveMultisampleFramebufferAPPLE), and the MSAA resolve framebuffer must be bound to the GL_READ_FRAMEBUFFER binding point, before glReadPixels is called.
179
180The above objects can be obtained via SDL_GetWindowWMInfo() (in SDL_syswm.h).
181
182==============================================================================
183Notes -- Keyboard
184==============================================================================
185
186The SDL keyboard API has been extended to support on-screen keyboards:
187
188void SDL_StartTextInput()
189 -- enables text events and reveals the onscreen keyboard.
190
191void SDL_StopTextInput()
192 -- disables text events and hides the onscreen keyboard.
193
194SDL_bool SDL_IsTextInputActive()
195 -- returns whether or not text events are enabled (and the onscreen keyboard is visible)
196
197
198==============================================================================
199Notes -- Reading and Writing files
200==============================================================================
201
202Each application installed on iPhone resides in a sandbox which includes its own Application Home directory. Your application may not access files outside this directory.
203
204Once your application is installed its directory tree looks like:
205
206 MySDLApp Home/
207 MySDLApp.app
208 Documents/
209 Library/
210 Preferences/
211 tmp/
212
213When your SDL based iPhone application starts up, it sets the working directory to the main bundle (MySDLApp Home/MySDLApp.app), where your application resources are stored. You cannot write to this directory. Instead, I advise you to write document files to "../Documents/" and preferences to "../Library/Preferences".
214
215More information on this subject is available here:
216http://developer.apple.com/library/ios/#documentation/iPhone/Conceptual/iPhoneOSProgrammingGuide/Introduction/Introduction.html
217
218==============================================================================
219Notes -- iPhone SDL limitations
220==============================================================================
221
222Windows:
223 Full-size, single window applications only. You cannot create multi-window SDL applications for iPhone OS. The application window will fill the display, though you have the option of turning on or off the menu-bar (pass SDL_CreateWindow() the flag SDL_WINDOW_BORDERLESS).
224
225Textures:
226 The optimal texture formats on iOS are SDL_PIXELFORMAT_ABGR8888, SDL_PIXELFORMAT_ABGR8888, SDL_PIXELFORMAT_BGR888, and SDL_PIXELFORMAT_RGB24 pixel formats.
227
228Loading Shared Objects:
229 This is disabled by default since it seems to break the terms of the iOS SDK agreement for iOS versions prior to iOS 8. It can be re-enabled in SDL_config_iphoneos.h.
230
231==============================================================================
232Notes -- CoreBluetooth.framework
233==============================================================================
234
235SDL_JOYSTICK_HIDAPI is disabled by default. It can give you access to a lot
236more game controller devices, but it requires permission from the user before
237your app will be able to talk to the Bluetooth hardware. "Made For iOS"
238branded controllers do not need this as we don't have to speak to them
239directly with raw bluetooth, so many apps can live without this.
240
241You'll need to link with CoreBluetooth.framework and add something like this
242to your Info.plist:
243
244<key>NSBluetoothPeripheralUsageDescription</key>
245<string>MyApp would like to remain connected to nearby bluetooth Game Controllers and Game Pads even when you're not using the app.</string>
246
247==============================================================================
248Game Center
249==============================================================================
250
251Game Center integration might require that you break up your main loop in order to yield control back to the system. In other words, instead of running an endless main loop, you run each frame in a callback function, using:
252
253 int SDL_iPhoneSetAnimationCallback(SDL_Window * window, int interval, void (*callback)(void*), void *callbackParam);
254
255This will set up the given function to be called back on the animation callback, and then you have to return from main() to let the Cocoa event loop run.
256
257e.g.
258
259 extern "C"
260 void ShowFrame(void*)
261 {
262 ... do event handling, frame logic and rendering ...
263 }
264
265 int main(int argc, char *argv[])
266 {
267 ... initialize game ...
268
269 #if __IPHONEOS__
270 // Initialize the Game Center for scoring and matchmaking
271 InitGameCenter();
272
273 // Set up the game to run in the window animation callback on iOS
274 // so that Game Center and so forth works correctly.
275 SDL_iPhoneSetAnimationCallback(window, 1, ShowFrame, NULL);
276 #else
277 while ( running ) {
278 ShowFrame(0);
279 DelayFrame();
280 }
281 #endif
282 return 0;
283 }
284
285==============================================================================
286Deploying to older versions of iOS
287==============================================================================
288
289SDL supports deploying to older versions of iOS than are supported by the latest version of Xcode, all the way back to iOS 6.1
290
291In order to do that you need to download an older version of Xcode:
292https://developer.apple.com/download/more/?name=Xcode
293
294Open the package contents of the older Xcode and your newer version of Xcode and copy over the folders in Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/DeviceSupport
295
296Then open the file Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/SDKSettings.plist and add the versions of iOS you want to deploy to the key Root/DefaultProperties/DEPLOYMENT_TARGET_SUGGESTED_VALUES
297
298Open your project and set your deployment target to the desired version of iOS
299
300Finally, remove GameController from the list of frameworks linked by your application and edit the build settings for "Other Linker Flags" and add -weak_framework GameController
301
README-linux.md
1Linux
2================================================================================
3
4By default SDL will only link against glibc, the rest of the features will be
5enabled dynamically at runtime depending on the available features on the target
6system. So, for example if you built SDL with Xinerama support and the target
7system does not have the Xinerama libraries installed, it will be disabled
8at runtime, and you won't get a missing library error, at least with the
9default configuration parameters.
10
11
12================================================================================
13Build Dependencies
14================================================================================
15
16Ubuntu 20.04, all available features enabled:
17
18sudo apt-get install build-essential mercurial make cmake autoconf automake \
19libtool libasound2-dev libpulse-dev libaudio-dev libx11-dev libxext-dev \
20libxrandr-dev libxcursor-dev libxi-dev libxinerama-dev libxxf86vm-dev \
21libxss-dev libgl1-mesa-dev libdbus-1-dev libudev-dev libgles2-mesa-dev \
22libegl1-mesa-dev libibus-1.0-dev fcitx-libs-dev libsamplerate0-dev \
23libsndio-dev libwayland-dev libxkbcommon-dev
24
25NOTES:
26- This includes all the audio targets except arts and esd, because Ubuntu
27 (and/or Debian) pulled their packages, but in theory SDL still supports them.
28- libsamplerate0-dev lets SDL optionally link to libresamplerate at runtime
29 for higher-quality audio resampling. SDL will work without it if the library
30 is missing, so it's safe to build in support even if the end user doesn't
31 have this library installed.
32- DirectFB isn't included because the configure script (currently) fails to find
33 it at all. You can do "sudo apt-get install libdirectfb-dev" and fix the
34 configure script to include DirectFB support. Send patches. :)
35
36
37================================================================================
38Joystick does not work
39================================================================================
40
41If you compiled or are using a version of SDL with udev support (and you should!)
42there's a few issues that may cause SDL to fail to detect your joystick. To
43debug this, start by installing the evtest utility. On Ubuntu/Debian:
44
45 sudo apt-get install evtest
46
47Then run:
48
49 sudo evtest
50
51You'll hopefully see your joystick listed along with a name like "/dev/input/eventXX"
52Now run:
53
54 cat /dev/input/event/XX
55
56If you get a permission error, you need to set a udev rule to change the mode of
57your device (see below)
58
59Also, try:
60
61 sudo udevadm info --query=all --name=input/eventXX
62
63If you see a line stating ID_INPUT_JOYSTICK=1, great, if you don't see it,
64you need to set up an udev rule to force this variable.
65
66A combined rule for the Saitek Pro Flight Rudder Pedals to fix both issues looks
67like:
68
69 SUBSYSTEM=="input", ATTRS{idProduct}=="0763", ATTRS{idVendor}=="06a3", MODE="0666", ENV{ID_INPUT_JOYSTICK}="1"
70 SUBSYSTEM=="input", ATTRS{idProduct}=="0764", ATTRS{idVendor}=="06a3", MODE="0666", ENV{ID_INPUT_JOYSTICK}="1"
71
72You can set up similar rules for your device by changing the values listed in
73idProduct and idVendor. To obtain these values, try:
74
75 sudo udevadm info -a --name=input/eventXX | grep idVendor
76 sudo udevadm info -a --name=input/eventXX | grep idProduct
77
78If multiple values come up for each of these, the one you want is the first one of each.
79
80On other systems which ship with an older udev (such as CentOS), you may need
81to set up a rule such as:
82
83 SUBSYSTEM=="input", ENV{ID_CLASS}=="joystick", ENV{ID_INPUT_JOYSTICK}="1"
84
85
README-macosx.md
1Mac OS X
2==============================================================================
3
4These instructions are for people using Apple's Mac OS X (pronounced
5"ten").
6
7From the developer's point of view, OS X is a sort of hybrid Mac and
8Unix system, and you have the option of using either traditional
9command line tools or Apple's IDE Xcode.
10
11Command Line Build
12==================
13
14To build SDL using the command line, use the standard configure and make
15process:
16
17 ./configure
18 make
19 sudo make install
20
21You can also build SDL as a Universal library (a single binary for both
2232-bit and 64-bit Intel architectures), on Mac OS X 10.7 and newer, by using
23the gcc-fat.sh script in build-scripts:
24
25 mkdir mybuild
26 cd mybuild
27 CC=$PWD/../build-scripts/gcc-fat.sh CXX=$PWD/../build-scripts/g++-fat.sh ../configure
28 make
29 sudo make install
30
31This script builds SDL with 10.5 ABI compatibility on i386 and 10.6
32ABI compatibility on x86_64 architectures. For best compatibility you
33should compile your application the same way.
34
35Please note that building SDL requires at least Xcode 4.6 and the 10.7 SDK
36(even if you target back to 10.5 systems). PowerPC support for Mac OS X has
37been officially dropped as of SDL 2.0.2.
38
39To use the library once it's built, you essential have two possibilities:
40use the traditional autoconf/automake/make method, or use Xcode.
41
42==============================================================================
43Caveats for using SDL with Mac OS X
44==============================================================================
45
46Some things you have to be aware of when using SDL on Mac OS X:
47
48- If you register your own NSApplicationDelegate (using [NSApp setDelegate:]),
49 SDL will not register its own. This means that SDL will not terminate using
50 SDL_Quit if it receives a termination request, it will terminate like a
51 normal app, and it will not send a SDL_DROPFILE when you request to open a
52 file with the app. To solve these issues, put the following code in your
53 NSApplicationDelegate implementation:
54
55
56 - (NSApplicationTerminateReply)applicationShouldTerminate:(NSApplication *)sender
57 {
58 if (SDL_GetEventState(SDL_QUIT) == SDL_ENABLE) {
59 SDL_Event event;
60 event.type = SDL_QUIT;
61 SDL_PushEvent(&event);
62 }
63
64 return NSTerminateCancel;
65 }
66
67 - (BOOL)application:(NSApplication *)theApplication openFile:(NSString *)filename
68 {
69 if (SDL_GetEventState(SDL_DROPFILE) == SDL_ENABLE) {
70 SDL_Event event;
71 event.type = SDL_DROPFILE;
72 event.drop.file = SDL_strdup([filename UTF8String]);
73 return (SDL_PushEvent(&event) > 0);
74 }
75
76 return NO;
77 }
78
79==============================================================================
80Using the Simple DirectMedia Layer with a traditional Makefile
81==============================================================================
82
83An existing autoconf/automake build system for your SDL app has good chances
84to work almost unchanged on OS X. However, to produce a "real" Mac OS X binary
85that you can distribute to users, you need to put the generated binary into a
86so called "bundle", which basically is a fancy folder with a name like
87"MyCoolGame.app".
88
89To get this build automatically, add something like the following rule to
90your Makefile.am:
91
92 bundle_contents = APP_NAME.app/Contents
93 APP_NAME_bundle: EXE_NAME
94 mkdir -p $(bundle_contents)/MacOS
95 mkdir -p $(bundle_contents)/Resources
96 echo "APPL????" > $(bundle_contents)/PkgInfo
97 $(INSTALL_PROGRAM) $< $(bundle_contents)/MacOS/
98
99You should replace EXE_NAME with the name of the executable. APP_NAME is what
100will be visible to the user in the Finder. Usually it will be the same
101as EXE_NAME but capitalized. E.g. if EXE_NAME is "testgame" then APP_NAME
102usually is "TestGame". You might also want to use `@PACKAGE@` to use the package
103name as specified in your configure.ac file.
104
105If your project builds more than one application, you will have to do a bit
106more. For each of your target applications, you need a separate rule.
107
108If you want the created bundles to be installed, you may want to add this
109rule to your Makefile.am:
110
111 install-exec-hook: APP_NAME_bundle
112 rm -rf $(DESTDIR)$(prefix)/Applications/APP_NAME.app
113 mkdir -p $(DESTDIR)$(prefix)/Applications/
114 cp -r $< /$(DESTDIR)$(prefix)Applications/
115
116This rule takes the Bundle created by the rule from step 3 and installs them
117into "$(DESTDIR)$(prefix)/Applications/".
118
119Again, if you want to install multiple applications, you will have to augment
120the make rule accordingly.
121
122
123But beware! That is only part of the story! With the above, you end up with
124a bare bone .app bundle, which is double clickable from the Finder. But
125there are some more things you should do before shipping your product...
126
1271) The bundle right now probably is dynamically linked against SDL. That
128 means that when you copy it to another computer, *it will not run*,
129 unless you also install SDL on that other computer. A good solution
130 for this dilemma is to static link against SDL. On OS X, you can
131 achieve that by linking against the libraries listed by
132
133 sdl-config --static-libs
134
135 instead of those listed by
136
137 sdl-config --libs
138
139 Depending on how exactly SDL is integrated into your build systems, the
140 way to achieve that varies, so I won't describe it here in detail
141
1422) Add an 'Info.plist' to your application. That is a special XML file which
143 contains some meta-information about your application (like some copyright
144 information, the version of your app, the name of an optional icon file,
145 and other things). Part of that information is displayed by the Finder
146 when you click on the .app, or if you look at the "Get Info" window.
147 More information about Info.plist files can be found on Apple's homepage.
148
149
150As a final remark, let me add that I use some of the techniques (and some
151variations of them) in Exult and ScummVM; both are available in source on
152the net, so feel free to take a peek at them for inspiration!
153
154
155==============================================================================
156Using the Simple DirectMedia Layer with Xcode
157==============================================================================
158
159These instructions are for using Apple's Xcode IDE to build SDL applications.
160
161- First steps
162
163The first thing to do is to unpack the Xcode.tar.gz archive in the
164top level SDL directory (where the Xcode.tar.gz archive resides).
165Because Stuffit Expander will unpack the archive into a subdirectory,
166you should unpack the archive manually from the command line:
167
168 cd [path_to_SDL_source]
169 tar zxf Xcode.tar.gz
170
171This will create a new folder called Xcode, which you can browse
172normally from the Finder.
173
174- Building the Framework
175
176The SDL Library is packaged as a framework bundle, an organized
177relocatable folder hierarchy of executable code, interface headers,
178and additional resources. For practical purposes, you can think of a
179framework as a more user and system-friendly shared library, whose library
180file behaves more or less like a standard UNIX shared library.
181
182To build the framework, simply open the framework project and build it.
183By default, the framework bundle "SDL.framework" is installed in
184/Library/Frameworks. Therefore, the testers and project stationary expect
185it to be located there. However, it will function the same in any of the
186following locations:
187
188 ~/Library/Frameworks
189 /Local/Library/Frameworks
190 /System/Library/Frameworks
191
192- Build Options
193 There are two "Build Styles" (See the "Targets" tab) for SDL.
194 "Deployment" should be used if you aren't tweaking the SDL library.
195 "Development" should be used to debug SDL apps or the library itself.
196
197- Building the Testers
198 Open the SDLTest project and build away!
199
200- Using the Project Stationary
201 Copy the stationary to the indicated folders to access it from
202 the "New Project" and "Add target" menus. What could be easier?
203
204- Setting up a new project by hand
205 Some of you won't want to use the Stationary so I'll give some tips:
206 * Create a new "Cocoa Application"
207 * Add src/main/macosx/SDLMain.m , .h and .nib to your project
208 * Remove "main.c" from your project
209 * Remove "MainMenu.nib" from your project
210 * Add "$(HOME)/Library/Frameworks/SDL.framework/Headers" to include path
211 * Add "$(HOME)/Library/Frameworks" to the frameworks search path
212 * Add "-framework SDL -framework Foundation -framework AppKit" to "OTHER_LDFLAGS"
213 * Set the "Main Nib File" under "Application Settings" to "SDLMain.nib"
214 * Add your files
215 * Clean and build
216
217- Building from command line
218 Use pbxbuild in the same directory as your .pbproj file
219
220- Running your app
221 You can send command line args to your app by either invoking it from
222 the command line (in *.app/Contents/MacOS) or by entering them in the
223 "Executables" panel of the target settings.
224
225- Implementation Notes
226 Some things that may be of interest about how it all works...
227 * Working directory
228 As defined in the SDL_main.m file, the working directory of your SDL app
229 is by default set to its parent. You may wish to change this to better
230 suit your needs.
231 * You have a Cocoa App!
232 Your SDL app is essentially a Cocoa application. When your app
233 starts up and the libraries finish loading, a Cocoa procedure is called,
234 which sets up the working directory and calls your main() method.
235 You are free to modify your Cocoa app with generally no consequence
236 to SDL. You cannot, however, easily change the SDL window itself.
237 Functionality may be added in the future to help this.
238
239
240Known bugs are listed in the file "BUGS.txt".
241
README-nacl.md
1Native Client
2================================================================================
3
4Requirements:
5
6* Native Client SDK (https://developer.chrome.com/native-client),
7 (tested with Pepper version 33 or higher).
8
9The SDL backend for Chrome's Native Client has been tested only with the PNaCl
10toolchain, which generates binaries designed to run on ARM and x86_32/64
11platforms. This does not mean it won't work with the other toolchains!
12
13================================================================================
14Building SDL for NaCl
15================================================================================
16
17Set up the right environment variables (see naclbuild.sh), then configure SDL with:
18
19 configure --host=pnacl --prefix some/install/destination
20
21Then "make".
22
23As an example of how to create a deployable app a Makefile project is provided
24in test/nacl/Makefile, which includes some monkey patching of the common.mk file
25provided by NaCl, without which linking properly to SDL won't work (the search
26path can't be modified externally, so the linker won't find SDL's binaries unless
27you dump them into the SDK path, which is inconvenient).
28Also provided in test/nacl is the required support file, such as index.html,
29manifest.json, etc.
30SDL apps for NaCl run on a worker thread using the ppapi_simple infrastructure.
31This allows for blocking calls on all the relevant systems (OpenGL ES, filesystem),
32hiding the asynchronous nature of the browser behind the scenes...which is not the
33same as making it disappear!
34
35
36================================================================================
37Running tests
38================================================================================
39
40Due to the nature of NaCl programs, building and running SDL tests is not as
41straightforward as one would hope. The script naclbuild.sh in build-scripts
42automates the process and should serve as a guide for users of SDL trying to build
43their own applications.
44
45Basic usage:
46
47 ./naclbuild.sh path/to/pepper/toolchain (i.e. ~/naclsdk/pepper_35)
48
49This will build testgles2.c by default.
50
51If you want to build a different test, for example testrendercopyex.c:
52
53 SOURCES=~/sdl/SDL/test/testrendercopyex.c ./naclbuild.sh ~/naclsdk/pepper_35
54
55Once the build finishes, you have to serve the contents with a web server (the
56script will give you instructions on how to do that with Python).
57
58================================================================================
59RWops and nacl_io
60================================================================================
61
62SDL_RWops work transparently with nacl_io. Two functions control the mount points:
63
64 int mount(const char* source, const char* target,
65 const char* filesystemtype,
66 unsigned long mountflags, const void *data);
67 int umount(const char *target);
68
69 For convenience, SDL will by default mount an httpfs tree at / before calling
70the app's main function. Such setting can be overridden by calling:
71
72 umount("/");
73
74And then mounting a different filesystem at /
75
76It's important to consider that the asynchronous nature of file operations on a
77browser is hidden from the application, effectively providing the developer with
78a set of blocking file operations just like you get in a regular desktop
79environment, which eases the job of porting to Native Client, but also introduces
80a set of challenges of its own, in particular when big file sizes and slow
81connections are involved.
82
83For more information on how nacl_io and mount points work, see:
84
85 https://developer.chrome.com/native-client/devguide/coding/nacl_io
86 https://src.chromium.org/chrome/trunk/src/native_client_sdk/src/libraries/nacl_io/nacl_io.h
87
88To be able to save into the directory "/save/" (like backup of game) :
89
90 mount("", "/save", "html5fs", 0, "type=PERSISTENT");
91
92And add to manifest.json :
93
94 "permissions": [
95 "unlimitedStorage"
96 ]
97
98================================================================================
99TODO - Known Issues
100================================================================================
101* Testing of all systems with a real application (something other than SDL's tests)
102* Key events don't seem to work properly
103
104
README-pandora.md
1Pandora
2=====================================================================
3
4( http://openpandora.org/ )
5- A pandora specific video driver was written to allow SDL 2.0 with OpenGL ES
6support to work on the pandora under the framebuffer. This driver do not have
7input support for now, so if you use it you will have to add your own control code.
8The video driver name is "pandora" so if you have problem running it from
9the framebuffer, try to set the following variable before starting your application :
10"export SDL_VIDEODRIVER=pandora"
11
12- OpenGL ES support was added to the x11 driver, so it's working like the normal
13x11 driver one with OpenGLX support, with SDL input event's etc..
14
15
16David Carré (Cpasjuste)
17cpasjuste@gmail.com
18
README-porting.md
1Porting
2=======
3
4* Porting To A New Platform
5
6 The first thing you have to do when porting to a new platform, is look at
7include/SDL_platform.h and create an entry there for your operating system.
8The standard format is "__PLATFORM__", where PLATFORM is the name of the OS.
9Ideally SDL_platform.h will be able to auto-detect the system it's building
10on based on C preprocessor symbols.
11
12There are two basic ways of building SDL at the moment:
13
141. The "UNIX" way: ./configure; make; make install
15
16 If you have a GNUish system, then you might try this. Edit configure.ac,
17 take a look at the large section labelled:
18
19 "Set up the configuration based on the host platform!"
20
21 Add a section for your platform, and then re-run autogen.sh and build!
22
232. Using an IDE:
24
25 If you're using an IDE or other non-configure build system, you'll probably
26 want to create a custom SDL_config.h for your platform. Edit SDL_config.h,
27 add a section for your platform, and create a custom SDL_config_{platform}.h,
28 based on SDL_config_minimal.h and SDL_config.h.in
29
30 Add the top level include directory to the header search path, and then add
31 the following sources to the project:
32
33 src/*.c
34 src/atomic/*.c
35 src/audio/*.c
36 src/cpuinfo/*.c
37 src/events/*.c
38 src/file/*.c
39 src/haptic/*.c
40 src/joystick/*.c
41 src/power/*.c
42 src/render/*.c
43 src/render/software/*.c
44 src/stdlib/*.c
45 src/thread/*.c
46 src/timer/*.c
47 src/video/*.c
48 src/audio/disk/*.c
49 src/audio/dummy/*.c
50 src/filesystem/dummy/*.c
51 src/video/dummy/*.c
52 src/haptic/dummy/*.c
53 src/joystick/dummy/*.c
54 src/main/dummy/*.c
55 src/thread/generic/*.c
56 src/timer/dummy/*.c
57 src/loadso/dummy/*.c
58
59
60Once you have a working library without any drivers, you can go back to each
61of the major subsystems and start implementing drivers for your platform.
62
63If you have any questions, don't hesitate to ask on the SDL mailing list:
64 http://www.libsdl.org/mailing-list.php
65
66Enjoy!
67 Sam Lantinga (slouken@libsdl.org)
68
69
README-psp.md
1PSP
2======
3SDL port for the Sony PSP contributed by
4 Captian Lex
5
6Credit to
7 Marcus R.Brown,Jim Paris,Matthew H for the original SDL 1.2 for PSP
8 Geecko for his PSP GU lib "Glib2d"
9
10Building
11--------
12To build for the PSP, make sure psp-config is in the path and run:
13 make -f Makefile.psp
14
15
16
17To Do
18------
19PSP Screen Keyboard
20
README-raspberrypi.md
1Raspberry Pi
2================================================================================
3
4Requirements:
5
6Raspbian (other Linux distros may work as well).
7
8================================================================================
9 Features
10================================================================================
11
12* Works without X11
13* Hardware accelerated OpenGL ES 2.x
14* Sound via ALSA
15* Input (mouse/keyboard/joystick) via EVDEV
16* Hotplugging of input devices via UDEV
17
18
19================================================================================
20 Raspbian Build Dependencies
21================================================================================
22
23sudo apt-get install libudev-dev libasound2-dev libdbus-1-dev
24
25You also need the VideoCore binary stuff that ships in /opt/vc for EGL and
26OpenGL ES 2.x, it usually comes pre-installed, but in any case:
27
28sudo apt-get install libraspberrypi0 libraspberrypi-bin libraspberrypi-dev
29
30
31================================================================================
32 NEON
33================================================================================
34
35If your Pi has NEON support, make sure you add -mfpu=neon to your CFLAGS so
36that SDL will select some otherwise-disabled highly-optimized code. The
37original Pi units don't have NEON, the Pi2 probably does, and the Pi3
38definitely does.
39
40================================================================================
41 Cross compiling from x86 Linux
42================================================================================
43
44To cross compile SDL for Raspbian from your desktop machine, you'll need a
45Raspbian system root and the cross compilation tools. We'll assume these tools
46will be placed in /opt/rpi-tools
47
48 sudo git clone --depth 1 https://github.com/raspberrypi/tools /opt/rpi-tools
49
50You'll also need a Raspbian binary image.
51Get it from: http://downloads.raspberrypi.org/raspbian_latest
52After unzipping, you'll get file with a name like: "<date>-wheezy-raspbian.img"
53Let's assume the sysroot will be built in /opt/rpi-sysroot.
54
55 export SYSROOT=/opt/rpi-sysroot
56 sudo kpartx -a -v <path_to_raspbian_image>.img
57 sudo mount -o loop /dev/mapper/loop0p2 /mnt
58 sudo cp -r /mnt $SYSROOT
59 sudo apt-get install qemu binfmt-support qemu-user-static
60 sudo cp /usr/bin/qemu-arm-static $SYSROOT/usr/bin
61 sudo mount --bind /dev $SYSROOT/dev
62 sudo mount --bind /proc $SYSROOT/proc
63 sudo mount --bind /sys $SYSROOT/sys
64
65Now, before chrooting into the ARM sysroot, you'll need to apply a workaround,
66edit $SYSROOT/etc/ld.so.preload and comment out all lines in it.
67
68 sudo chroot $SYSROOT
69 apt-get install libudev-dev libasound2-dev libdbus-1-dev libraspberrypi0 libraspberrypi-bin libraspberrypi-dev libx11-dev libxext-dev libxrandr-dev libxcursor-dev libxi-dev libxinerama-dev libxxf86vm-dev libxss-dev
70 exit
71 sudo umount $SYSROOT/dev
72 sudo umount $SYSROOT/proc
73 sudo umount $SYSROOT/sys
74 sudo umount /mnt
75
76There's one more fix required, as the libdl.so symlink uses an absolute path
77which doesn't quite work in our setup.
78
79 sudo rm -rf $SYSROOT/usr/lib/arm-linux-gnueabihf/libdl.so
80 sudo ln -s ../../../lib/arm-linux-gnueabihf/libdl.so.2 $SYSROOT/usr/lib/arm-linux-gnueabihf/libdl.so
81
82The final step is compiling SDL itself.
83
84 export CC="/opt/rpi-tools/arm-bcm2708/gcc-linaro-arm-linux-gnueabihf-raspbian/bin/arm-linux-gnueabihf-gcc --sysroot=$SYSROOT -I$SYSROOT/opt/vc/include -I$SYSROOT/usr/include -I$SYSROOT/opt/vc/include/interface/vcos/pthreads -I$SYSROOT/opt/vc/include/interface/vmcs_host/linux"
85 cd <SDL SOURCE>
86 mkdir -p build;cd build
87 LDFLAGS="-L$SYSROOT/opt/vc/lib" ../configure --with-sysroot=$SYSROOT --host=arm-raspberry-linux-gnueabihf --prefix=$PWD/rpi-sdl2-installed --disable-pulseaudio --disable-esd
88 make
89 make install
90
91To be able to deploy this to /usr/local in the Raspbian system you need to fix up a few paths:
92
93 perl -w -pi -e "s#$PWD/rpi-sdl2-installed#/usr/local#g;" ./rpi-sdl2-installed/lib/libSDL2.la ./rpi-sdl2-installed/lib/pkgconfig/sdl2.pc ./rpi-sdl2-installed/bin/sdl2-config
94
95================================================================================
96 Apps don't work or poor video/audio performance
97================================================================================
98
99If you get sound problems, buffer underruns, etc, run "sudo rpi-update" to
100update the RPi's firmware. Note that doing so will fix these problems, but it
101will also render the CMA - Dynamic Memory Split functionality useless.
102
103Also, by default the Raspbian distro configures the GPU RAM at 64MB, this is too
104low in general, specially if a 1080p TV is hooked up.
105
106See here how to configure this setting: http://elinux.org/RPiconfig
107
108Using a fixed gpu_mem=128 is the best option (specially if you updated the
109firmware, using CMA probably won't work, at least it's the current case).
110
111================================================================================
112 No input
113================================================================================
114
115Make sure you belong to the "input" group.
116
117 sudo usermod -aG input `whoami`
118
119================================================================================
120 No HDMI Audio
121================================================================================
122
123If you notice that ALSA works but there's no audio over HDMI, try adding:
124
125 hdmi_drive=2
126
127to your config.txt file and reboot.
128
129Reference: http://www.raspberrypi.org/phpBB3/viewtopic.php?t=5062
130
131================================================================================
132 Text Input API support
133================================================================================
134
135The Text Input API is supported, with translation of scan codes done via the
136kernel symbol tables. For this to work, SDL needs access to a valid console.
137If you notice there's no SDL_TEXTINPUT message being emitted, double check that
138your app has read access to one of the following:
139
140* /proc/self/fd/0
141* /dev/tty
142* /dev/tty[0...6]
143* /dev/vc/0
144* /dev/console
145
146This is usually not a problem if you run from the physical terminal (as opposed
147to running from a pseudo terminal, such as via SSH). If running from a PTS, a
148quick workaround is to run your app as root or add yourself to the tty group,
149then re-login to the system.
150
151 sudo usermod -aG tty `whoami`
152
153The keyboard layout used by SDL is the same as the one the kernel uses.
154To configure the layout on Raspbian:
155
156 sudo dpkg-reconfigure keyboard-configuration
157
158To configure the locale, which controls which keys are interpreted as letters,
159this determining the CAPS LOCK behavior:
160
161 sudo dpkg-reconfigure locales
162
163================================================================================
164 OpenGL problems
165================================================================================
166
167If you have desktop OpenGL headers installed at build time in your RPi or cross
168compilation environment, support for it will be built in. However, the chipset
169does not actually have support for it, which causes issues in certain SDL apps
170since the presence of OpenGL support supersedes the ES/ES2 variants.
171The workaround is to disable OpenGL at configuration time:
172
173 ./configure --disable-video-opengl
174
175Or if the application uses the Render functions, you can use the SDL_RENDER_DRIVER
176environment variable:
177
178 export SDL_RENDER_DRIVER=opengles2
179
180================================================================================
181 Notes
182================================================================================
183
184* When launching apps remotely (via SSH), SDL can prevent local keystrokes from
185 leaking into the console only if it has root privileges. Launching apps locally
186 does not suffer from this issue.
187
188
189
README-touch.md
1Touch
2===========================================================================
3System Specific Notes
4===========================================================================
5Linux:
6The 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.
7
8Mac:
9The 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
11iPhone:
12Works out of box.
13
14Windows:
15Unfortunately 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
16
17===========================================================================
18Events
19===========================================================================
20SDL_FINGERDOWN:
21Sent when a finger (or stylus) is placed on a touch device.
22Fields:
23* event.tfinger.touchId - the Id of the touch device.
24* event.tfinger.fingerId - the Id of the finger which just went down.
25* event.tfinger.x - the x coordinate of the touch (0..1)
26* event.tfinger.y - the y coordinate of the touch (0..1)
27* event.tfinger.pressure - the pressure of the touch (0..1)
28
29SDL_FINGERMOTION:
30Sent when a finger (or stylus) is moved on the touch device.
31Fields:
32Same as SDL_FINGERDOWN but with additional:
33* event.tfinger.dx - change in x coordinate during this motion event.
34* event.tfinger.dy - change in y coordinate during this motion event.
35
36SDL_FINGERUP:
37Sent when a finger (or stylus) is lifted from the touch device.
38Fields:
39Same as SDL_FINGERDOWN.
40
41
42===========================================================================
43Functions
44===========================================================================
45SDL provides the ability to access the underlying SDL_Finger structures.
46These structures should _never_ be modified.
47
48The following functions are included from SDL_touch.h
49
50To get a SDL_TouchID call SDL_GetTouchDevice(int index).
51This returns a SDL_TouchID.
52IMPORTANT: If the touch has been removed, or there is no touch with the given index, SDL_GetTouchDevice() will return 0. Be sure to check for this!
53
54The number of touch devices can be queried with SDL_GetNumTouchDevices().
55
56A SDL_TouchID may be used to get pointers to SDL_Finger.
57
58SDL_GetNumTouchFingers(touchID) may be used to get the number of fingers currently down on the device.
59
60The 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:
61
62 float x = event.tfinger.x;
63 float y = event.tfinger.y;
64
65
66
67To get a SDL_Finger, call SDL_GetTouchFinger(SDL_TouchID touchID, int index), where touchID is a SDL_TouchID, and index is the requested finger.
68This returns a SDL_Finger *, or NULL if the finger does not exist, or has been removed.
69A 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 SDL_FINGERUP event is polled.
70As a result, be very careful to check for NULL return values.
71
72A SDL_Finger has the following fields:
73* x, y:
74 The current coordinates of the touch.
75* pressure:
76 The pressure of the touch.
77
78
79===========================================================================
80Notes
81===========================================================================
82For a complete example see test/testgesture.c
83
84Please direct questions/comments to:
85 jim.tla+sdl_touch@gmail.com
86 (original author, API was changed since)
87
README-wince.md
1WinCE
2=====
3
4Windows CE is no longer supported by SDL.
5
6We have left the CE support in SDL 1.2 for those that must have it, and we
7have support for Windows Phone 8 and WinRT in SDL2, as of SDL 2.0.3.
8
9--ryan.
10
11
README-windows.md
1Windows
2================================================================================
3
4================================================================================
5OpenGL ES 2.x support
6================================================================================
7
8SDL has support for OpenGL ES 2.x under Windows via two alternative
9implementations.
10The most straightforward method consists in running your app in a system with
11a graphic card paired with a relatively recent (as of November of 2013) driver
12which supports the WGL_EXT_create_context_es2_profile extension. Vendors known
13to ship said extension on Windows currently include nVidia and Intel.
14
15The other method involves using the ANGLE library (https://code.google.com/p/angleproject/)
16If an OpenGL ES 2.x context is requested and no WGL_EXT_create_context_es2_profile
17extension is found, SDL will try to load the libEGL.dll library provided by
18ANGLE.
19To obtain the ANGLE binaries, you can either compile from source from
20https://chromium.googlesource.com/angle/angle or copy the relevant binaries from
21a recent Chrome/Chromium install for Windows. The files you need are:
22
23 * libEGL.dll
24 * libGLESv2.dll
25 * d3dcompiler_46.dll (supports Windows Vista or later, better shader compiler)
26 or...
27 * d3dcompiler_43.dll (supports Windows XP or later)
28
29If you compile ANGLE from source, you can configure it so it does not need the
30d3dcompiler_* DLL at all (for details on this, see their documentation).
31However, by default SDL will try to preload the d3dcompiler_46.dll to
32comply with ANGLE's requirements. If you wish SDL to preload d3dcompiler_43.dll (to
33support Windows XP) or to skip this step at all, you can use the
34SDL_HINT_VIDEO_WIN_D3DCOMPILER hint (see SDL_hints.h for more details).
35
36Known Bugs:
37
38 * SDL_GL_SetSwapInterval is currently a no op when using ANGLE. It appears
39 that there's a bug in the library which prevents the window contents from
40 refreshing if this is set to anything other than the default value.
41
42Vulkan Surface Support
43==============
44
45Support for creating Vulkan surfaces is configured on by default. To disable it change the value of `SDL_VIDEO_VULKAN` to 0 in `SDL_config_windows.h`. You must install the [Vulkan SDK](https://www.lunarg.com/vulkan-sdk/) in order to use Vulkan graphics in your application.
46
README-winrt.md
1WinRT
2=====
3
4This port allows SDL applications to run on Microsoft's platforms that require
5use of "Windows Runtime", aka. "WinRT", APIs. Microsoft may, in some cases,
6refer to them as either "Windows Store", or for Windows 10, "UWP" apps.
7
8Some of the operating systems that include WinRT, are:
9
10* Windows 10, via its Universal Windows Platform (UWP) APIs
11* Windows 8.x
12* Windows RT 8.x (aka. Windows 8.x for ARM processors)
13* Windows Phone 8.x
14
15
16Requirements
17------------
18
19* Microsoft Visual C++ (aka Visual Studio), either 2017, 2015, 2013, or 2012
20 - Free, "Community" or "Express" editions may be used, so long as they
21 include support for either "Windows Store" or "Windows Phone" apps.
22 "Express" versions marked as supporting "Windows Desktop" development
23 typically do not include support for creating WinRT apps, to note.
24 (The "Community" editions of Visual C++ do, however, support both
25 desktop/Win32 and WinRT development).
26 - Visual Studio 2017 can be used, however it is recommended that you install
27 the Visual C++ 2015 build tools. These build tools can be installed
28 using VS 2017's installer. Be sure to also install the workload for
29 "Universal Windows Platform development", its optional component, the
30 "C++ Universal Windows Platform tools", and for UWP / Windows 10
31 development, the "Windows 10 SDK (10.0.10240.0)". Please note that
32 targeting UWP / Windows 10 apps from development machine(s) running
33 earlier versions of Windows, such as Windows 7, is not always supported
34 by Visual Studio, and you may get error(s) when attempting to do so.
35 - Visual C++ 2012 can only build apps that target versions 8.0 of Windows,
36 or Windows Phone. 8.0-targeted apps will run on devices running 8.1
37 editions of Windows, however they will not be able to take advantage of
38 8.1-specific features.
39 - Visual C++ 2013 cannot create app projects that target Windows 8.0.
40 Visual C++ 2013 Update 4, can create app projects for Windows Phone 8.0,
41 Windows Phone 8.1, and Windows 8.1, but not Windows 8.0. An optional
42 Visual Studio add-in, "Tools for Maintaining Store apps for Windows 8",
43 allows Visual C++ 2013 to load and build Windows 8.0 projects that were
44 created with Visual C++ 2012, so long as Visual C++ 2012 is installed
45 on the same machine. More details on targeting different versions of
46 Windows can found at the following web pages:
47 - [Develop apps by using Visual Studio 2013](http://msdn.microsoft.com/en-us/library/windows/apps/br211384.aspx)
48 - [To add the Tools for Maintaining Store apps for Windows 8](http://msdn.microsoft.com/en-us/library/windows/apps/dn263114.aspx#AddMaintenanceTools)
49* A valid Microsoft account - This requirement is not imposed by SDL, but
50 rather by Microsoft's Visual C++ toolchain. This is required to launch or
51 debug apps.
52
53
54Status
55------
56
57Here is a rough list of what works, and what doesn't:
58
59* What works:
60 * compilation via Visual C++ 2012 through 2015
61 * compile-time platform detection for SDL programs. The C/C++ #define,
62 `__WINRT__`, will be set to 1 (by SDL) when compiling for WinRT.
63 * GPU-accelerated 2D rendering, via SDL_Renderer.
64 * OpenGL ES 2, via the ANGLE library (included separately from SDL)
65 * software rendering, via either SDL_Surface (optionally in conjunction with
66 SDL_GetWindowSurface() and SDL_UpdateWindowSurface()) or via the
67 SDL_Renderer APIs
68 * threads
69 * timers (via SDL_GetTicks(), SDL_AddTimer(), SDL_GetPerformanceCounter(),
70 SDL_GetPerformanceFrequency(), etc.)
71 * file I/O via SDL_RWops
72 * mouse input (unsupported on Windows Phone)
73 * audio, via SDL's WASAPI backend (if you want to record, your app must
74 have "Microphone" capabilities enabled in its manifest, and the user must
75 not have blocked access. Otherwise, capture devices will fail to work,
76 presenting as a device disconnect shortly after opening it.)
77 * .DLL file loading. Libraries *MUST* be packaged inside applications. Loading
78 anything outside of the app is not supported.
79 * system path retrieval via SDL's filesystem APIs
80 * game controllers. Support is provided via the SDL_Joystick and
81 SDL_GameController APIs, and is backed by Microsoft's XInput API. Please
82 note, however, that Windows limits game-controller support in UWP apps to,
83 "Xbox compatible controllers" (many controllers that work in Win32 apps,
84 do not work in UWP, due to restrictions in UWP itself.)
85 * multi-touch input
86 * app events. SDL_APP_WILLENTER* and SDL_APP_DIDENTER* events get sent out as
87 appropriate.
88 * window events
89 * using Direct3D 11.x APIs outside of SDL. Non-XAML / Direct3D-only apps can
90 choose to render content directly via Direct3D, using SDL to manage the
91 internal WinRT window, as well as input and audio. (Use
92 SDL_GetWindowWMInfo() to get the WinRT 'CoreWindow', and pass it into
93 IDXGIFactory2::CreateSwapChainForCoreWindow() as appropriate.)
94
95* What partially works:
96 * keyboard input. Most of WinRT's documented virtual keys are supported, as
97 well as many keys with documented hardware scancodes. Converting
98 SDL_Scancodes to or from SDL_Keycodes may not work, due to missing APIs
99 (MapVirtualKey()) in Microsoft's Windows Store / UWP APIs.
100 * SDLmain. WinRT uses a different signature for each app's main() function.
101 SDL-based apps that use this port must compile in SDL_winrt_main_NonXAML.cpp
102 (in `SDL\src\main\winrt\`) directly in order for their C-style main()
103 functions to be called.
104
105* What doesn't work:
106 * compilation with anything other than Visual C++
107 * programmatically-created custom cursors. These don't appear to be supported
108 by WinRT. Different OS-provided cursors can, however, be created via
109 SDL_CreateSystemCursor() (unsupported on Windows Phone)
110 * SDL_WarpMouseInWindow() or SDL_WarpMouseGlobal(). This are not currently
111 supported by WinRT itself.
112 * joysticks and game controllers that either are not supported by
113 Microsoft's XInput API, or are not supported within UWP apps (many
114 controllers that work in Win32, do not work in UWP, due to restrictions in
115 UWP itself).
116 * turning off VSync when rendering on Windows Phone. Attempts to turn VSync
117 off on Windows Phone result either in Direct3D not drawing anything, or it
118 forcing VSync back on. As such, SDL_RENDERER_PRESENTVSYNC will always get
119 turned-on on Windows Phone. This limitation is not present in non-Phone
120 WinRT (such as Windows 8.x), where turning off VSync appears to work.
121 * probably anything else that's not listed as supported
122
123
124
125Upgrade Notes
126-------------
127
128#### SDL_GetPrefPath() usage when upgrading WinRT apps from SDL 2.0.3
129
130SDL 2.0.4 fixes two bugs found in the WinRT version of SDL_GetPrefPath().
131The fixes may affect older, SDL 2.0.3-based apps' save data. Please note
132that these changes only apply to SDL-based WinRT apps, and not to apps for
133any other platform.
134
1351. SDL_GetPrefPath() would return an invalid path, one in which the path's
136 directory had not been created. Attempts to create files there
137 (via fopen(), for example), would fail, unless that directory was
138 explicitly created beforehand.
139
1402. SDL_GetPrefPath(), for non-WinPhone-based apps, would return a path inside
141 a WinRT 'Roaming' folder, the contents of which get automatically
142 synchronized across multiple devices. This process can occur while an
143 application runs, and can cause existing save-data to be overwritten
144 at unexpected times, with data from other devices. (Windows Phone apps
145 written with SDL 2.0.3 did not utilize a Roaming folder, due to API
146 restrictions in Windows Phone 8.0).
147
148
149SDL_GetPrefPath(), starting with SDL 2.0.4, addresses these by:
150
1511. making sure that SDL_GetPrefPath() returns a directory in which data
152 can be written to immediately, without first needing to create directories.
153
1542. basing SDL_GetPrefPath() off of a different, non-Roaming folder, the
155 contents of which do not automatically get synchronized across devices
156 (and which require less work to use safely, in terms of data integrity).
157
158Apps that wish to get their Roaming folder's path can do so either by using
159SDL_WinRTGetFSPathUTF8(), SDL_WinRTGetFSPathUNICODE() (which returns a
160UCS-2/wide-char string), or directly through the WinRT class,
161Windows.Storage.ApplicationData.
162
163
164
165Setup, High-Level Steps
166-----------------------
167
168The steps for setting up a project for an SDL/WinRT app looks like the
169following, at a high-level:
170
1711. create a new Visual C++ project using Microsoft's template for a,
172 "Direct3D App".
1732. remove most of the files from the project.
1743. make your app's project directly reference SDL/WinRT's own Visual C++
175 project file, via use of Visual C++'s "References" dialog. This will setup
176 the linker, and will copy SDL's .dll files to your app's final output.
1774. adjust your app's build settings, at minimum, telling it where to find SDL's
178 header files.
1795. add files that contains a WinRT-appropriate main function, along with some
180 data to make sure mouse-cursor-hiding (via SDL_ShowCursor(SDL_DISABLE) calls)
181 work properly.
1826. add SDL-specific app code.
1837. build and run your app.
184
185
186Setup, Detailed Steps
187---------------------
188
189### 1. Create a new project ###
190
191Create a new project using one of Visual C++'s templates for a plain, non-XAML,
192"Direct3D App" (XAML support for SDL/WinRT is not yet ready for use). If you
193don't see one of these templates, in Visual C++'s 'New Project' dialog, try
194using the textbox titled, 'Search Installed Templates' to look for one.
195
196
197### 2. Remove unneeded files from the project ###
198
199In the new project, delete any file that has one of the following extensions:
200
201- .cpp
202- .h
203- .hlsl
204
205When you are done, you should be left with a few files, each of which will be a
206necessary part of your app's project. These files will consist of:
207
208- an .appxmanifest file, which contains metadata on your WinRT app. This is
209 similar to an Info.plist file on iOS, or an AndroidManifest.xml on Android.
210- a few .png files, one of which is a splash screen (displayed when your app
211 launches), others are app icons.
212- a .pfx file, used for code signing purposes.
213
214
215### 3. Add references to SDL's project files ###
216
217SDL/WinRT can be built in multiple variations, spanning across three different
218CPU architectures (x86, x64, and ARM) and two different configurations
219(Debug and Release). WinRT and Visual C++ do not currently provide a means
220for combining multiple variations of one library into a single file.
221Furthermore, it does not provide an easy means for copying pre-built .dll files
222into your app's final output (via Post-Build steps, for example). It does,
223however, provide a system whereby an app can reference the MSVC projects of
224libraries such that, when the app is built:
225
2261. each library gets built for the appropriate CPU architecture(s) and WinRT
227 platform(s).
2282. each library's output, such as .dll files, get copied to the app's build
229 output.
230
231To set this up for SDL/WinRT, you'll need to run through the following steps:
232
2331. open up the Solution Explorer inside Visual C++ (under the "View" menu, then
234 "Solution Explorer")
2352. right click on your app's solution.
2363. navigate to "Add", then to "Existing Project..."
2374. find SDL/WinRT's Visual C++ project file and open it. Different project
238 files exist for different WinRT platforms. All of them are in SDL's
239 source distribution, in the following directories:
240 * `VisualC-WinRT/UWP_VS2015/` - for Windows 10 / UWP apps
241 * `VisualC-WinRT/WinPhone81_VS2013/` - for Windows Phone 8.1 apps
242 * `VisualC-WinRT/WinRT80_VS2012/` - for Windows 8.0 apps
243 * `VisualC-WinRT/WinRT81_VS2013/` - for Windows 8.1 apps
2445. once the project has been added, right-click on your app's project and
245 select, "References..."
2466. click on the button titled, "Add New Reference..."
2477. check the box next to SDL
2488. click OK to close the dialog
2499. SDL will now show up in the list of references. Click OK to close that
250 dialog.
251
252Your project is now linked to SDL's project, insofar that when the app is
253built, SDL will be built as well, with its build output getting included with
254your app.
255
256
257### 4. Adjust Your App's Build Settings ###
258
259Some build settings need to be changed in your app's project. This guide will
260outline the following:
261
262- making sure that the compiler knows where to find SDL's header files
263- **Optional for C++, but NECESSARY for compiling C code:** telling the
264 compiler not to use Microsoft's C++ extensions for WinRT development.
265- **Optional:** telling the compiler not generate errors due to missing
266 precompiled header files.
267
268To change these settings:
269
2701. right-click on the project
2712. choose "Properties"
2723. in the drop-down box next to "Configuration", choose, "All Configurations"
2734. in the drop-down box next to "Platform", choose, "All Platforms"
2745. in the left-hand list, expand the "C/C++" section
2756. select "General"
2767. edit the "Additional Include Directories" setting, and add a path to SDL's
277 "include" directory
2788. **Optional: to enable compilation of C code:** change the setting for
279 "Consume Windows Runtime Extension" from "Yes (/ZW)" to "No". If you're
280 working with a completely C++ based project, this step can usually be
281 omitted.
2829. **Optional: to disable precompiled headers (which can produce
283 'stdafx.h'-related build errors, if setup incorrectly:** in the left-hand
284 list, select "Precompiled Headers", then change the setting for "Precompiled
285 Header" from "Use (/Yu)" to "Not Using Precompiled Headers".
28610. close the dialog, saving settings, by clicking the "OK" button
287
288
289### 5. Add a WinRT-appropriate main function, and a blank-cursor image, to the app. ###
290
291A few files should be included directly in your app's MSVC project, specifically:
2921. a WinRT-appropriate main function (which is different than main() functions on
293 other platforms)
2942. a Win32-style cursor resource, used by SDL_ShowCursor() to hide the mouse cursor
295 (if and when the app needs to do so). *If this cursor resource is not
296 included, mouse-position reporting may fail if and when the cursor is
297 hidden, due to possible bugs/design-oddities in Windows itself.*
298
299To include these files for C/C++ projects:
300
3011. right-click on your project (again, in Visual C++'s Solution Explorer),
302 navigate to "Add", then choose "Existing Item...".
3032. navigate to the directory containing SDL's source code, then into its
304 subdirectory, 'src/main/winrt/'. Select, then add, the following files:
305 - `SDL_winrt_main_NonXAML.cpp`
306 - `SDL2-WinRTResources.rc`
307 - `SDL2-WinRTResource_BlankCursor.cur`
3083. right-click on the file `SDL_winrt_main_NonXAML.cpp` (as listed in your
309 project), then click on "Properties...".
3104. in the drop-down box next to "Configuration", choose, "All Configurations"
3115. in the drop-down box next to "Platform", choose, "All Platforms"
3126. in the left-hand list, click on "C/C++"
3137. change the setting for "Consume Windows Runtime Extension" to "Yes (/ZW)".
3148. click the OK button. This will close the dialog.
315
316**NOTE: C++/CX compilation is currently required in at least one file of your
317app's project. This is to make sure that Visual C++'s linker builds a 'Windows
318Metadata' file (.winmd) for your app. Not doing so can lead to build errors.**
319
320For non-C++ projects, you will need to call SDL_WinRTRunApp from your language's
321main function, and generate SDL2-WinRTResources.res manually by using `rc` via
322the Developer Command Prompt and including it as a <Win32Resource> within the
323first <PropertyGroup> block in your Visual Studio project file.
324
325### 6. Add app code and assets ###
326
327At this point, you can add in SDL-specific source code. Be sure to include a
328C-style main function (ie: `int main(int argc, char *argv[])`). From there you
329should be able to create a single `SDL_Window` (WinRT apps can only have one
330window, at present), as well as an `SDL_Renderer`. Direct3D will be used to
331draw content. Events are received via SDL's usual event functions
332(`SDL_PollEvent`, etc.) If you have a set of existing source files and assets,
333you can start adding them to the project now. If not, or if you would like to
334make sure that you're setup correctly, some short and simple sample code is
335provided below.
336
337
338#### 6.A. ... when creating a new app ####
339
340If you are creating a new app (rather than porting an existing SDL-based app),
341or if you would just like a simple app to test SDL/WinRT with before trying to
342get existing code working, some working SDL/WinRT code is provided below. To
343set this up:
344
3451. right click on your app's project
3462. select Add, then New Item. An "Add New Item" dialog will show up.
3473. from the left-hand list, choose "Visual C++"
3484. from the middle/main list, choose "C++ File (.cpp)"
3495. near the bottom of the dialog, next to "Name:", type in a name for your
350source file, such as, "main.cpp".
3516. click on the Add button. This will close the dialog, add the new file to
352your project, and open the file in Visual C++'s text editor.
3537. Copy and paste the following code into the new file, then save it.
354
355
356 #include <SDL.h>
357
358 int main(int argc, char **argv)
359 {
360 SDL_DisplayMode mode;
361 SDL_Window * window = NULL;
362 SDL_Renderer * renderer = NULL;
363 SDL_Event evt;
364
365 if (SDL_Init(SDL_INIT_VIDEO) != 0) {
366 return 1;
367 }
368
369 if (SDL_GetCurrentDisplayMode(0, &mode) != 0) {
370 return 1;
371 }
372
373 if (SDL_CreateWindowAndRenderer(mode.w, mode.h, SDL_WINDOW_FULLSCREEN, &window, &renderer) != 0) {
374 return 1;
375 }
376
377 while (1) {
378 while (SDL_PollEvent(&evt)) {
379 }
380
381 SDL_SetRenderDrawColor(renderer, 0, 255, 0, 255);
382 SDL_RenderClear(renderer);
383 SDL_RenderPresent(renderer);
384 }
385 }
386
387
388#### 6.B. Adding code and assets ####
389
390If you have existing code and assets that you'd like to add, you should be able
391to add them now. The process for adding a set of files is as such.
392
3931. right click on the app's project
3942. select Add, then click on "New Item..."
3953. open any source, header, or asset files as appropriate. Support for C and
396C++ is available.
397
398Do note that WinRT only supports a subset of the APIs that are available to
399Win32-based apps. Many portions of the Win32 API and the C runtime are not
400available.
401
402A list of unsupported C APIs can be found at
403<http://msdn.microsoft.com/en-us/library/windows/apps/jj606124.aspx>
404
405General information on using the C runtime in WinRT can be found at
406<https://msdn.microsoft.com/en-us/library/hh972425.aspx>
407
408A list of supported Win32 APIs for WinRT apps can be found at
409<http://msdn.microsoft.com/en-us/library/windows/apps/br205757.aspx>. To note,
410the list of supported Win32 APIs for Windows Phone 8.0 is different.
411That list can be found at
412<http://msdn.microsoft.com/en-us/library/windowsphone/develop/jj662956(v=vs.105).aspx>
413
414
415### 7. Build and run your app ###
416
417Your app project should now be setup, and you should be ready to build your app.
418To run it on the local machine, open the Debug menu and choose "Start
419Debugging". This will build your app, then run your app full-screen. To switch
420out of your app, press the Windows key. Alternatively, you can choose to run
421your app in a window. To do this, before building and running your app, find
422the drop-down menu in Visual C++'s toolbar that says, "Local Machine". Expand
423this by clicking on the arrow on the right side of the list, then click on
424Simulator. Once you do that, any time you build and run the app, the app will
425launch in window, rather than full-screen.
426
427
428#### 7.A. Running apps on older, ARM-based, "Windows RT" devices ####
429
430**These instructions do not include Windows Phone, despite Windows Phone
431typically running on ARM processors.** They are specifically for devices
432that use the "Windows RT" operating system, which was a modified version of
433Windows 8.x that ran primarily on ARM-based tablet computers.
434
435To build and run the app on ARM-based, "Windows RT" devices, you'll need to:
436
437- install Microsoft's "Remote Debugger" on the device. Visual C++ installs and
438 debugs ARM-based apps via IP networks.
439- change a few options on the development machine, both to make sure it builds
440 for ARM (rather than x86 or x64), and to make sure it knows how to find the
441 Windows RT device (on the network).
442
443Microsoft's Remote Debugger can be found at
444<https://msdn.microsoft.com/en-us/library/hh441469.aspx>. Please note
445that separate versions of this debugger exist for different versions of Visual
446C++, one each for MSVC 2015, 2013, and 2012.
447
448To setup Visual C++ to launch your app on an ARM device:
449
4501. make sure the Remote Debugger is running on your ARM device, and that it's on
451 the same IP network as your development machine.
4522. from Visual C++'s toolbar, find a drop-down menu that says, "Win32". Click
453 it, then change the value to "ARM".
4543. make sure Visual C++ knows the hostname or IP address of the ARM device. To
455 do this:
456 1. open the app project's properties
457 2. select "Debugging"
458 3. next to "Machine Name", enter the hostname or IP address of the ARM
459 device
460 4. if, and only if, you've turned off authentication in the Remote Debugger,
461 then change the setting for "Require Authentication" to No
462 5. click "OK"
4634. build and run the app (from Visual C++). The first time you do this, a
464 prompt will show up on the ARM device, asking for a Microsoft Account. You
465 do, unfortunately, need to log in here, and will need to follow the
466 subsequent registration steps in order to launch the app. After you do so,
467 if the app didn't already launch, try relaunching it again from within Visual
468 C++.
469
470
471Troubleshooting
472---------------
473
474#### Build fails with message, "error LNK2038: mismatch detected for 'vccorlib_lib_should_be_specified_before_msvcrt_lib_to_linker'"
475
476Try adding the following to your linker flags. In MSVC, this can be done by
477right-clicking on the app project, navigating to Configuration Properties ->
478Linker -> Command Line, then adding them to the Additional Options
479section.
480
481* For Release builds / MSVC-Configurations, add:
482
483 /nodefaultlib:vccorlib /nodefaultlib:msvcrt vccorlib.lib msvcrt.lib
484
485* For Debug builds / MSVC-Configurations, add:
486
487 /nodefaultlib:vccorlibd /nodefaultlib:msvcrtd vccorlibd.lib msvcrtd.lib
488
489
490#### Mouse-motion events fail to get sent, or SDL_GetMouseState() fails to return updated values
491
492This may be caused by a bug in Windows itself, whereby hiding the mouse
493cursor can cause mouse-position reporting to fail.
494
495SDL provides a workaround for this, but it requires that an app links to a
496set of Win32-style cursor image-resource files. A copy of suitable resource
497files can be found in `src/main/winrt/`. Adding them to an app's Visual C++
498project file should be sufficient to get the app to use them.
499
500
501#### SDL's Visual Studio project file fails to open, with message, "The system can't find the file specified."
502
503This can be caused for any one of a few reasons, which Visual Studio can
504report, but won't always do so in an up-front manner.
505
506To help determine why this error comes up:
507
5081. open a copy of Visual Studio without opening a project file. This can be
509 accomplished via Windows' Start Menu, among other means.
5102. show Visual Studio's Output window. This can be done by going to VS'
511 menu bar, then to View, and then to Output.
5123. try opening the SDL project file directly by going to VS' menu bar, then
513 to File, then to Open, then to Project/Solution. When a File-Open dialog
514 appears, open the SDL project (such as the one in SDL's source code, in its
515 directory, VisualC-WinRT/UWP_VS2015/).
5164. after attempting to open SDL's Visual Studio project file, additional error
517 information will be output to the Output window.
518
519If Visual Studio reports (via its Output window) that the project:
520
521"could not be loaded because it's missing install components. To fix this launch Visual Studio setup with the following selections:
522Microsoft.VisualStudio.ComponentGroup.UWP.VC"
523
524... then you will need to re-launch Visual Studio's installer, and make sure that
525the workflow for "Universal Windows Platform development" is checked, and that its
526optional component, "C++ Universal Windows Platform tools" is also checked. While
527you are there, if you are planning on targeting UWP / Windows 10, also make sure
528that you check the optional component, "Windows 10 SDK (10.0.10240.0)". After
529making sure these items are checked as-appropriate, install them.
530
531Once you install these components, try re-launching Visual Studio, and re-opening
532the SDL project file. If you still get the error dialog, try using the Output
533window, again, seeing what Visual Studio says about it.
534
535
536#### Game controllers / joysticks aren't working!
537
538Windows only permits certain game controllers and joysticks to work within
539WinRT / UWP apps. Even if a game controller or joystick works in a Win32
540app, that device is not guaranteed to work inside a WinRT / UWP app.
541
542According to Microsoft, "Xbox compatible controllers" should work inside
543UWP apps, potentially with more working in the future. This includes, but
544may not be limited to, Microsoft-made Xbox controllers and USB adapters.
545(Source: https://social.msdn.microsoft.com/Forums/en-US/9064838b-e8c3-4c18-8a83-19bf0dfe150d/xinput-fails-to-detect-game-controllers?forum=wpdevelop)
546
547
548
README.md
1Simple DirectMedia Layer {#mainpage}
2========================
3
4 (SDL)
5
6 Version 2.0
7
8---
9http://www.libsdl.org/
10
11Simple DirectMedia Layer is a cross-platform development library designed
12to provide low level access to audio, keyboard, mouse, joystick, and graphics
13hardware via OpenGL and Direct3D. It is used by video playback software,
14emulators, and popular games including Valve's award winning catalog
15and many Humble Bundle games.
16
17SDL officially supports Windows, Mac OS X, Linux, iOS, and Android.
18Support for other platforms may be found in the source code.
19
20SDL is written in C, works natively with C++, and there are bindings
21available for several other languages, including C# and Python.
22
23This library is distributed under the zlib license, which can be found
24in the file "COPYING.txt".
25
26The best way to learn how to use SDL is to check out the header files in
27the "include" subdirectory and the programs in the "test" subdirectory.
28The header files and test programs are well commented and always up to date.
29
30More documentation and FAQs are available online at [the wiki](http://wiki.libsdl.org/)
31
32- [Android](README-android.md)
33- [CMake](README-cmake.md)
34- [DirectFB](README-directfb.md)
35- [DynAPI](README-dynapi.md)
36- [Emscripten](README-emscripten.md)
37- [Gesture](README-gesture.md)
38- [Mercurial](README-hg.md)
39- [iOS](README-ios.md)
40- [Linux](README-linux.md)
41- [OS X](README-macosx.md)
42- [Native Client](README-nacl.md)
43- [Pandora](README-pandora.md)
44- [Supported Platforms](README-platforms.md)
45- [Porting information](README-porting.md)
46- [PSP](README-psp.md)
47- [Raspberry Pi](README-raspberrypi.md)
48- [Touch](README-touch.md)
49- [WinCE](README-wince.md)
50- [Windows](README-windows.md)
51- [WinRT](README-winrt.md)
52
53If you need help with the library, or just want to discuss SDL related
54issues, you can join the [developers mailing list](http://www.libsdl.org/mailing-list.php)
55
56If you want to report bugs or contribute patches, please submit them to
57[bugzilla](https://bugzilla.libsdl.org/)
58
59Enjoy!
60
61
62Sam Lantinga <mailto:slouken@libsdl.org>
63
64