ana / a70b7ca
vendor stuff to own the libs haldean 1 year, 6 months ago
162 changed file(s) with 76564 addition(s) and 29 deletion(s). Raw diff Collapse all Expand all
0 re
1 build
2 *.o
3 *.d
0 re
1 build
2 *.o
3 *.d
0 [submodule "lib/glm"]
1 path = lib/glm
2 url =
3 [submodule "lib/imgui"]
4 path = lib/imgui
5 url =
0 cmake_minimum_required(VERSION 3.7 FATAL_ERROR)
1 cmake_policy(VERSION 3.7)
2 project(ana VERSION 0.1.0 LANGUAGES CXX)
4 find_package(SDL2 REQUIRED)
5 find_package(GLEW REQUIRED)
9 include_directories(lib/imgui lib/imgui/examples SDL2::SDL2 ${SDL2_INCLUDE_DIRS} lib/glm)
11 add_executable(ana
12 src/ana.cpp
13 src/node.cpp
14 src/shaders.cpp
15 src/ui.cpp
16 lib/imgui/imgui.cpp
17 lib/imgui/imgui_demo.cpp
18 lib/imgui/imgui_draw.cpp
19 lib/imgui/imgui_widgets.cpp
20 lib/imgui/examples/imgui_impl_sdl.cpp
21 lib/imgui/examples/imgui_impl_opengl3.cpp
22 )
24 target_link_libraries(ana SDL2::SDL2 ${SDL2_LIBRARIES} ${GLEW_LIBRARIES} GL)
0 cmake_minimum_required(VERSION 3.7 FATAL_ERROR)
1 cmake_policy(VERSION 3.7)
2 project(ana VERSION 0.1.0 LANGUAGES CXX)
4 find_package(SDL2 REQUIRED)
5 find_package(GLEW REQUIRED)
6 find_package(OpenGL REQUIRED)
10 include_directories(lib/imgui lib/imgui/examples ${SDL2_INCLUDE_DIRS} ${GLEW_INCLUDE_DIRS} lib/glm)
12 add_executable(ana
13 src/ana.cpp
14 src/node.cpp
15 src/shaders.cpp
16 src/ui.cpp
17 lib/imgui/imgui.cpp
18 lib/imgui/imgui_demo.cpp
19 lib/imgui/imgui_draw.cpp
20 lib/imgui/imgui_widgets.cpp
21 lib/imgui/examples/imgui_impl_sdl.cpp
22 lib/imgui/examples/imgui_impl_opengl3.cpp
23 )
25 target_link_libraries(ana ${SDL2_LIBRARIES} ${GLEW_LIBRARIES} ${OPENGL_LIBRARIES} -static)
1 Bugs are now managed in the SDL bug tracker, here:
5 You may report bugs there, and search to see if a given issue has already
6 been reported, discussed, and maybe even fixed.
9 You may also find help at the SDL forums/mailing list:
13 Bug reports are welcome here, but we really appreciate if you use Bugzilla, as
14 bugs discussed on the mailing list may be forgotten or missed.
1 Simple DirectMedia Layer
2 Copyright (C) 1997-2018 Sam Lantinga <>
4 This software is provided 'as-is', without any express or implied
5 warranty. In no event will the authors be held liable for any damages
6 arising from the use of this software.
8 Permission is granted to anyone to use this software for any purpose,
9 including commercial applications, and to alter it and redistribute it
10 freely, subject to the following restrictions:
12 1. The origin of this software must not be misrepresented; you must not
13 claim that you wrote the original software. If you use this software
14 in a product, an acknowledgment in the product documentation would be
15 appreciated but is not required.
16 2. Altered source versions must be plainly marked as such, and must not be
17 misrepresented as being the original software.
18 3. This notice may not be removed or altered from any source distribution.
1 Please distribute this file with the SDL runtime environment:
3 The Simple DirectMedia Layer (SDL for short) is a cross-platform library
4 designed to make it easy to write multi-media software, such as games
5 and emulators.
7 The Simple DirectMedia Layer library source code is available from:
10 This library is distributed under the terms of the zlib license:
1 Simple DirectMedia Layer
3 (SDL)
5 Version 2.0
7 ---
10 Simple DirectMedia Layer is a cross-platform development library designed
11 to provide low level access to audio, keyboard, mouse, joystick, and graphics
12 hardware via OpenGL and Direct3D. It is used by video playback software,
13 emulators, and popular games including Valve's award winning catalog
14 and many Humble Bundle games.
16 More extensive documentation is available in the docs directory, starting
17 with
19 Enjoy!
20 Sam Lantinga (
1 This is a list of major changes in SDL's version history.
3 ---------------------------------------------------------------------------
4 2.0.9:
5 ---------------------------------------------------------------------------
7 General:
8 * Added a new sensor API, initialized by passing SDL_INIT_SENSOR to SDL_Init(), and defined in SDL_sensor.h
9 * Added an event SDL_SENSORUPDATE which is sent when a sensor is updated
10 * Added SDL_GetDisplayOrientation() to return the current display orientation
11 * Added an event SDL_DISPLAYEVENT which is sent when the display orientation changes
12 * Added HIDAPI joystick drivers for more consistent support for Xbox, PS4 and Nintendo Switch Pro controller support across platforms. (Thanks to Valve for contributing the PS4 and Nintendo Switch Pro controller support)
13 * Added support for many other popular game controllers
14 * Added SDL_JoystickGetDevicePlayerIndex(), SDL_JoystickGetPlayerIndex(), and SDL_GameControllerGetPlayerIndex() to get the player index for a controller. For XInput controllers this returns the XInput index for the controller.
15 * Added SDL_GameControllerRumble() and SDL_JoystickRumble() which allow simple rumble without using the haptics API
16 * Added SDL_GameControllerMappingForDeviceIndex() to get the mapping for a controller before it's opened
17 * Added the hint SDL_HINT_MOUSE_DOUBLE_CLICK_TIME to control the mouse double-click time
18 * Added the hint SDL_HINT_MOUSE_DOUBLE_CLICK_RADIUS to control the mouse double-click radius, in pixels
19 * Added SDL_HasColorKey() to return whether a surface has a colorkey active
20 * Added SDL_HasAVX512F() to return whether the CPU has AVX-512F features
21 * Added SDL_IsTablet() to return whether the application is running on a tablet
22 * Added SDL_THREAD_PRIORITY_TIME_CRITICAL for threads that must run at the highest priority
24 Mac OS X:
25 * Fixed black screen at start on Mac OS X Mojave
27 Linux:
28 * Added SDL_LinuxSetThreadPriority() to allow adjusting the thread priority of native threads using RealtimeKit if available.
30 iOS:
31 * Fixed Asian IME input
33 Android:
34 * Updated required Android SDK to API 26, to match Google's new App Store requirements
35 * Added support for wired USB Xbox, PS4, and Nintendo Switch Pro controllers
36 * Added support for relative mouse mode on Android 7.0 and newer (except where it's broken, on Chromebooks and when in DeX mode with Samsung Experience 9.0)
37 * Added support for custom mouse cursors on Android 7.0 and newer
38 * Added the hint SDL_HINT_ANDROID_TRAP_BACK_BUTTON to control whether the back button will back out of the app (the default) or be passed to the application as SDL_SCANCODE_AC_BACK
39 * Added SDL_AndroidBackButton() to trigger the Android system back button behavior when handling the back button in the application
40 * Added SDL_IsChromebook() to return whether the app is running in the Chromebook Android runtime
41 * Added SDL_IsDeXMode() to return whether the app is running while docked in the Samsung DeX
44 ---------------------------------------------------------------------------
45 2.0.8:
46 ---------------------------------------------------------------------------
48 General:
49 * Added SDL_fmod() and SDL_log10()
50 * Each of the SDL math functions now has the corresponding float version
51 * Added SDL_SetYUVConversionMode() and SDL_GetYUVConversionMode() to control the formula used when converting to and from YUV colorspace. The options are JPEG, BT.601, and BT.709
53 Windows:
54 * Implemented WASAPI support on Windows UWP and removed the deprecated XAudio2 implementation
55 * Added resampling support on WASAPI on Windows 7 and above
57 Windows UWP:
58 * Added SDL_WinRTGetDeviceFamily() to find out what type of device your application is running on
60 Mac OS X:
61 * Added support for the Vulkan SDK for Mac:
63 * Added support for OpenGL ES using ANGLE when it's available
65 Mac OS X / iOS / tvOS:
66 * Added a Metal 2D render implementation
67 * Added SDL_RenderGetMetalLayer() and SDL_RenderGetMetalCommandEncoder() to insert your own drawing into SDL rendering when using the Metal implementation
69 iOS:
70 * Added the hint SDL_HINT_IOS_HIDE_HOME_INDICATOR to control whether the home indicator bar on iPhone X should be hidden. This defaults to dimming the indicator for fullscreen applications and showing the indicator for windowed applications.
72 iOS / Android:
73 * Added the hint SDL_HINT_RETURN_KEY_HIDES_IME to control whether the return key on the software keyboard should hide the keyboard or send a key event (the default)
75 Android:
76 * SDL now supports building with Android Studio and Gradle by default, and the old Ant project is available in android-project-ant
77 * SDL now requires the API 19 SDK to build, but can still target devices down to API 14 (Android 4.0.1)
78 * Added SDL_IsAndroidTV() to tell whether the application is running on Android TV
80 Android / tvOS:
81 * Added the hint SDL_HINT_TV_REMOTE_AS_JOYSTICK to control whether TV remotes should be listed as joystick devices (the default) or send keyboard events.
83 Linux:
84 * Added the hint SDL_HINT_VIDEO_X11_NET_WM_BYPASS_COMPOSITOR to control whether the X server should skip the compositor for the SDL application. This defaults to "1"
85 * Added the hint SDL_HINT_VIDEO_DOUBLE_BUFFER to control whether the Raspberry Pi and KMSDRM video drivers should use double or triple buffering (the default)
88 ---------------------------------------------------------------------------
89 2.0.7:
90 ---------------------------------------------------------------------------
92 General:
93 * Added audio stream conversion functions:
94 SDL_NewAudioStream
95 SDL_AudioStreamPut
96 SDL_AudioStreamGet
97 SDL_AudioStreamAvailable
98 SDL_AudioStreamFlush
99 SDL_AudioStreamClear
100 SDL_FreeAudioStream
101 * Added functions to query and set the SDL memory allocation functions:
102 SDL_GetMemoryFunctions()
103 SDL_SetMemoryFunctions()
104 SDL_GetNumAllocations()
105 * Added locking functions for multi-threaded access to the joystick and game controller APIs:
106 SDL_LockJoysticks()
107 SDL_UnlockJoysticks()
108 * The following functions are now thread-safe:
109 SDL_SetEventFilter()
110 SDL_GetEventFilter()
111 SDL_AddEventWatch()
112 SDL_DelEventWatch()
115 General:
116 ---------------------------------------------------------------------------
117 2.0.6:
118 ---------------------------------------------------------------------------
120 General:
121 * Added cross-platform Vulkan graphics support in SDL_vulkan.h
122 SDL_Vulkan_LoadLibrary()
123 SDL_Vulkan_GetVkGetInstanceProcAddr()
124 SDL_Vulkan_GetInstanceExtensions()
125 SDL_Vulkan_CreateSurface()
126 SDL_Vulkan_GetDrawableSize()
127 SDL_Vulkan_UnloadLibrary()
128 This is all the platform-specific code you need to bring up Vulkan on all SDL platforms. You can look at an example in test/testvulkan.c
129 * Added SDL_ComposeCustomBlendMode() to create custom blend modes for 2D rendering
130 * Added SDL_HasNEON() which returns whether the CPU has NEON instruction support
131 * Added support for many game controllers, including the Nintendo Switch Pro Controller
132 * Added support for inverted axes and separate axis directions in game controller mappings
133 * Added functions to return information about a joystick before it's opened:
134 SDL_JoystickGetDeviceVendor()
135 SDL_JoystickGetDeviceProduct()
136 SDL_JoystickGetDeviceProductVersion()
137 SDL_JoystickGetDeviceType()
138 SDL_JoystickGetDeviceInstanceID()
139 * Added functions to return information about an open joystick:
140 SDL_JoystickGetVendor()
141 SDL_JoystickGetProduct()
142 SDL_JoystickGetProductVersion()
143 SDL_JoystickGetType()
144 SDL_JoystickGetAxisInitialState()
145 * Added functions to return information about an open game controller:
146 SDL_GameControllerGetVendor()
147 SDL_GameControllerGetProduct()
148 SDL_GameControllerGetProductVersion()
149 * Added SDL_GameControllerNumMappings() and SDL_GameControllerMappingForIndex() to be able to enumerate the built-in game controller mappings
150 * Added SDL_LoadFile() and SDL_LoadFile_RW() to load a file into memory
151 * Added SDL_DuplicateSurface() to make a copy of a surface
152 * Added an experimental JACK audio driver
153 * Implemented non-power-of-two audio resampling, optionally using libsamplerate to perform the resampling
154 * Added the hint SDL_HINT_AUDIO_RESAMPLING_MODE to control the quality of resampling
155 * Added the hint SDL_HINT_RENDER_LOGICAL_SIZE_MODE to control the scaling policy for SDL_RenderSetLogicalSize():
156 "0" or "letterbox" - Uses letterbox/sidebars to fit the entire rendering on screen (the default)
157 "1" or "overscan" - Will zoom the rendering so it fills the entire screen, allowing edges to be drawn offscreen
158 * Added the hints SDL_HINT_MOUSE_NORMAL_SPEED_SCALE and SDL_HINT_MOUSE_RELATIVE_SPEED_SCALE to scale the mouse speed when being read from raw mouse input
159 * Added the hint SDL_HINT_TOUCH_MOUSE_EVENTS to control whether SDL will synthesize mouse events from touch events
161 Windows:
162 * The new default audio driver on Windows is WASAPI and supports hot-plugging devices and changing the default audio device
163 * The old XAudio2 audio driver is deprecated and will be removed in the next release
164 * Added hints SDL_HINT_WINDOWS_INTRESOURCE_ICON and SDL_HINT_WINDOWS_INTRESOURCE_ICON_SMALL to specify a custom icon resource ID for SDL windows
165 * The hint SDL_HINT_WINDOWS_DISABLE_THREAD_NAMING is now on by default for compatibility with .NET languages and various Windows debuggers
166 * Updated the GUID format for game controller mappings, older mappings will be automatically converted on load
167 * Implemented the SDL_WINDOW_ALWAYS_ON_TOP flag on Windows
169 Linux:
170 * Added an experimental KMS/DRM video driver for embedded development
172 iOS:
173 * Added a hint SDL_HINT_AUDIO_CATEGORY to control the audio category, determining whether the phone mute switch affects the audio
175 ---------------------------------------------------------------------------
176 2.0.5:
177 ---------------------------------------------------------------------------
179 General:
180 * Implemented audio capture support for some platforms
181 * Added SDL_DequeueAudio() to retrieve audio when buffer queuing is turned on for audio capture
182 * Added events for dragging and dropping text
183 * Added events for dragging and dropping multiple items
184 * By default the click raising a window will not be delivered to the SDL application. You can set the hint SDL_HINT_MOUSE_FOCUS_CLICKTHROUGH to "1" to allow that click through to the window.
185 * Saving a surface with an alpha channel as a BMP will use a newer BMP format that supports alpha information. You can set the hint SDL_HINT_BMP_SAVE_LEGACY_FORMAT to "1" to use the old format.
186 * Added SDL_GetHintBoolean() to get the boolean value of a hint
187 * Added SDL_RenderSetIntegerScale() to set whether to smoothly scale or use integral multiples of the viewport size when scaling the rendering output
188 * Added SDL_CreateRGBSurfaceWithFormat() and SDL_CreateRGBSurfaceWithFormatFrom() to create an SDL surface with a specific pixel format
189 * Added SDL_GetDisplayUsableBounds() which returns the area usable for windows. For example, on Mac OS X, this subtracts the area occupied by the menu bar and dock.
190 * Added SDL_GetWindowBordersSize() which returns the size of the window's borders around the client area
191 * Added a window event SDL_WINDOWEVENT_HIT_TEST when a window had a hit test that wasn't SDL_HITTEST_NORMAL (e.g. in the title bar or window frame)
192 * Added SDL_SetWindowResizable() to change whether a window is resizable
193 * Added SDL_SetWindowOpacity() and SDL_GetWindowOpacity() to affect the window transparency
194 * Added SDL_SetWindowModalFor() to set a window as modal for another window
195 * Added support for AUDIO_U16LSB and AUDIO_U16MSB to SDL_MixAudioFormat()
196 * Fixed flipped images when reading back from target textures when using the OpenGL renderer
197 * Fixed texture color modulation with SDL_BLENDMODE_NONE when using the OpenGL renderer
198 * Fixed bug where the alpha value of colorkeys was ignored when blitting in some cases
200 Windows:
201 * Added a hint SDL_HINT_WINDOWS_DISABLE_THREAD_NAMING to prevent SDL from raising a debugger exception to name threads. This exception can cause problems with .NET applications when running under a debugger.
202 * The hint SDL_HINT_THREAD_STACK_SIZE is now supported on Windows
203 * Fixed XBox controller triggers automatically being pulled at startup
204 * The first icon from the executable is used as the default window icon at runtime
205 * Fixed SDL log messages being printed twice if SDL was built with C library support
206 * Reset dead keys when the SDL window loses focus, so dead keys pressed in SDL applications don't affect text input into other applications.
208 Mac OS X:
209 * Fixed selecting the dummy video driver
210 * The caps lock key now generates a pressed event when pressed and a released event when released, instead of a press/release event pair when pressed.
211 * Fixed mouse wheel events on Mac OS X 10.12
212 * The audio driver has been updated to use AVFoundation for better compatibility with newer versions of Mac OS X
214 Linux:
215 * Added support for the Fcitx IME
216 * Added a window event SDL_WINDOWEVENT_TAKE_FOCUS when a window manager asks the SDL window whether it wants to take focus.
217 * Refresh rates are now rounded instead of truncated, e.g. 59.94 Hz is rounded up to 60 Hz instead of 59.
218 * Added initial support for touchscreens on Raspberry Pi
220 OpenBSD:
221 * SDL_GetBasePath() is now implemented on OpenBSD
223 iOS:
224 * Added support for dynamically loaded objects on iOS 8 and newer
226 tvOS:
227 * Added support for Apple TV
228 * Added a hint SDL_HINT_APPLE_TV_REMOTE_ALLOW_ROTATION to control whether he Apple TV remote's joystick axes will automatically match the rotation of the remote.
230 Android:
231 * Fixed SDL not resizing window when Android screen resolution changes
232 * Corrected the joystick Z axis reporting for the accelerometer
234 Emscripten (running in a web browser):
235 * Many bug fixes and improvements
238 ---------------------------------------------------------------------------
239 2.0.4:
240 ---------------------------------------------------------------------------
242 General:
243 * Added support for web applications using Emscripten, see docs/ for more information
244 * Added support for web applications using Native Client (NaCl), see docs/ for more information
245 * Added an API to queue audio instead of using the audio callback:
246 SDL_QueueAudio(), SDL_GetQueuedAudioSize(), SDL_ClearQueuedAudio()
247 * Added events for audio device hot plug support:
249 * Added SDL_PointInRect()
250 * Added SDL_HasAVX2() to detect CPUs with AVX2 support
251 * Added SDL_SetWindowHitTest() to let apps treat parts of their SDL window like traditional window decorations (drag areas, resize areas)
252 * Added SDL_GetGrabbedWindow() to get the window that currently has input grab, if any
253 * Added SDL_RenderIsClipEnabled() to tell whether clipping is currently enabled in a renderer
254 * Added SDL_CaptureMouse() to capture the mouse to get events while the mouse is not in your window
255 * Added SDL_WarpMouseGlobal() to warp the mouse cursor in global screen space
256 * Added SDL_GetGlobalMouseState() to get the current mouse state outside of an SDL window
257 * Added a direction field to mouse wheel events to tell whether they are flipped (natural) or not
258 * Added GL_CONTEXT_RELEASE_BEHAVIOR GL attribute (maps to [WGL|GLX]_ARB_context_flush_control extension)
259 * Added EGL_KHR_create_context support to allow OpenGL ES version selection on some platforms
260 * Added NV12 and NV21 YUV texture support for OpenGL and OpenGL ES 2.0 renderers
261 * Added a Vivante video driver that is used on various SoC platforms
262 * Added an event SDL_RENDER_DEVICE_RESET that is sent from the D3D renderers when the D3D device is lost, and from Android's event loop when the GLES context had to be recreated
263 * Added a hint SDL_HINT_NO_SIGNAL_HANDLERS to disable SDL's built in signal handling
264 * Added a hint SDL_HINT_THREAD_STACK_SIZE to set the stack size of SDL's threads
265 * Added SDL_sqrtf(), SDL_tan(), and SDL_tanf() to the stdlib routines
266 * Improved support for WAV and BMP files with unusual chunks in them
267 * Renamed SDL_assert_data to SDL_AssertData and SDL_assert_state to SDL_AssertState
268 * Added a hint SDL_HINT_WINDOW_FRAME_USABLE_WHILE_CURSOR_HIDDEN to prevent window interaction while cursor is hidden
269 * Added SDL_GetDisplayDPI() to get the DPI information for a display
270 * Added SDL_JoystickCurrentPowerLevel() to get the battery level of a joystick
271 * Added SDL_JoystickFromInstanceID(), as a helper function, to get the SDL_Joystick* that an event is referring to.
272 * Added SDL_GameControllerFromInstanceID(), as a helper function, to get the SDL_GameController* that an event is referring to.
274 Windows:
275 * Added support for Windows Phone 8.1 and Windows 10/UWP (Universal Windows Platform)
276 * Timer resolution is now 1 ms by default, adjustable with the SDL_HINT_TIMER_RESOLUTION hint
277 * SDLmain no longer depends on the C runtime, so you can use the same .lib in both Debug and Release builds
278 * Added SDL_SetWindowsMessageHook() to set a function to be called for every windows message before TranslateMessage()
279 * Added a hint SDL_HINT_WINDOWS_ENABLE_MESSAGELOOP to control whether SDL_PumpEvents() processes the Windows message loop
280 * You can distinguish between real mouse and touch events by looking for SDL_TOUCH_MOUSEID in the mouse event "which" field
281 * SDL_SysWMinfo now contains the window HDC
282 * Added support for Unicode command line options
283 * Prevent beeping when Alt-key combos are pressed
284 * SDL_SetTextInputRect() re-positions the OS-rendered IME
285 * Added a hint SDL_HINT_WINDOWS_NO_CLOSE_ON_ALT_F4 to prevent generating SDL_WINDOWEVENT_CLOSE events when Alt-F4 is pressed
286 * Added a hint SDL_HINT_XINPUT_USE_OLD_JOYSTICK_MAPPING to use the old axis and button mapping for XInput devices (deprecated)
288 Mac OS X:
289 * Implemented drag-and-drop support
290 * Improved joystick hot-plug detection
291 * The SDL_WINDOWEVENT_EXPOSED window event is triggered in the appropriate situations
292 * Fixed relative mouse mode when the application loses/regains focus
293 * Fixed bugs related to transitioning to and from Spaces-aware fullscreen-desktop mode
294 * Fixed the refresh rate of display modes
295 * SDL_SysWMInfo is now ARC-compatible
296 * Added a hint SDL_HINT_MAC_BACKGROUND_APP to prevent forcing the application to become a foreground process
298 Linux:
299 * Enabled building with Mir and Wayland support by default.
300 * Added IBus IME support
301 * Added a hint SDL_HINT_IME_INTERNAL_EDITING to control whether IBus should handle text editing internally instead of sending SDL_TEXTEDITING events
302 * Added a hint SDL_HINT_VIDEO_X11_NET_WM_PING to allow disabling _NET_WM_PING protocol handling in SDL_CreateWindow()
303 * Added support for multiple audio devices when using Pulseaudio
304 * Fixed duplicate mouse events when using relative mouse motion
306 iOS:
307 * Added support for iOS 8
308 * The SDL_WINDOW_ALLOW_HIGHDPI window flag now enables high-dpi support, and SDL_GL_GetDrawableSize() or SDL_GetRendererOutputSize() gets the window resolution in pixels
309 * SDL_GetWindowSize() and display mode sizes are in the "DPI-independent points" / "screen coordinates" coordinate space rather than pixels (matches OS X behavior)
310 * Added native resolution support for the iPhone 6 Plus
311 * Added support for MFi game controllers
312 * Added support for the hint SDL_HINT_ACCELEROMETER_AS_JOYSTICK
313 * Added sRGB OpenGL ES context support on iOS 7+
314 * Added support for SDL_DisableScreenSaver(), SDL_EnableScreenSaver() and the hint SDL_HINT_VIDEO_ALLOW_SCREENSAVER
315 * SDL_SysWMinfo now contains the OpenGL ES framebuffer and color renderbuffer objects used by the window's active GLES view
316 * Fixed various rotation and orientation issues
317 * Fixed memory leaks
319 Android:
320 * Added a hint SDL_HINT_ANDROID_SEPARATE_MOUSE_AND_TOUCH to prevent mouse events from being registered as touch events
322 * Added support for SDL_DisableScreenSaver(), SDL_EnableScreenSaver() and the hint SDL_HINT_VIDEO_ALLOW_SCREENSAVER
323 * Added support for SDL_ShowMessageBox() and SDL_ShowSimpleMessageBox()
325 Raspberry Pi:
326 * Added support for the Raspberry Pi 2
329 ---------------------------------------------------------------------------
330 2.0.3:
331 ---------------------------------------------------------------------------
333 Mac OS X:
334 * Fixed creating an OpenGL context by default on Mac OS X 10.6
337 ---------------------------------------------------------------------------
338 2.0.2:
339 ---------------------------------------------------------------------------
340 General:
341 * Added SDL_GL_ResetAttributes() to reset OpenGL attributes to default values
342 * Added an API to load a database of game controller mappings from a file:
343 SDL_GameControllerAddMappingsFromFile(), SDL_GameControllerAddMappingsFromRW()
344 * Added game controller mappings for the PS4 and OUYA controllers
345 * Added SDL_GetDefaultAssertionHandler() and SDL_GetAssertionHandler()
346 * Added SDL_DetachThread()
347 * Added SDL_HasAVX() to determine if the CPU has AVX features
348 * Added SDL_vsscanf(), SDL_acos(), and SDL_asin() to the stdlib routines
349 * EGL can now create/manage OpenGL and OpenGL ES 1.x/2.x contexts, and share
351 * Added a field "clicks" to the mouse button event which records whether the event is a single click, double click, etc.
352 * The screensaver is now disabled by default, and there is a hint SDL_HINT_VIDEO_ALLOW_SCREENSAVER that can change that behavior.
353 * Added a hint SDL_HINT_MOUSE_RELATIVE_MODE_WARP to specify whether mouse relative mode should be emulated using mouse warping.
354 * testgl2 does not need to link with libGL anymore
355 * Added testgles2 test program to demonstrate working with OpenGL ES 2.0
356 * Added controllermap test program to visually map a game controller
358 Windows:
359 * Support for OpenGL ES 2.x contexts using either WGL or EGL (natively via
360 the driver or emulated through ANGLE)
361 * Added a hint SDL_HINT_VIDEO_WIN_D3DCOMPILER to specify which D3D shader compiler to use for OpenGL ES 2 support through ANGLE
362 * Added a hint SDL_HINT_VIDEO_WINDOW_SHARE_PIXEL_FORMAT that is useful when creating multiple windows that should share the same OpenGL context.
363 * Added an event SDL_RENDER_TARGETS_RESET that is sent when D3D9 render targets are reset after the device has been restored.
365 Mac OS X:
366 * Added a hint SDL_HINT_MAC_CTRL_CLICK_EMULATE_RIGHT_CLICK to control whether Ctrl+click should be treated as a right click on Mac OS X. This is off by default.
368 Linux:
369 * Fixed fullscreen and focused behavior when receiving NotifyGrab events
370 * Added experimental Wayland and Mir support, disabled by default
372 Android:
373 * Joystick support (minimum SDK version required to build SDL is now 12,
374 the required runtime version remains at 10, but on such devices joystick
375 support won't be available).
376 * Hotplugging support for joysticks
377 * Added a hint SDL_HINT_ACCELEROMETER_AS_JOYSTICK to control whether the accelerometer should be listed as a 3 axis joystick, which it will by default.
380 ---------------------------------------------------------------------------
381 2.0.1:
382 ---------------------------------------------------------------------------
384 General:
385 * Added an API to get common filesystem paths in SDL_filesystem.h:
386 SDL_GetBasePath(), SDL_GetPrefPath()
387 * Added an API to do optimized YV12 and IYUV texture updates:
388 SDL_UpdateYUVTexture()
389 * Added an API to get the amount of RAM on the system:
390 SDL_GetSystemRAM()
391 * Added a macro to perform timestamp comparisons with SDL_GetTicks():
393 * Dramatically improved OpenGL ES 2.0 rendering performance
396 Windows:
397 * Created a static library configuration for the Visual Studio 2010 project
398 * Added a hint to create the Direct3D device with support for multi-threading:
400 * Added a function to get the D3D9 adapter index for a display:
401 SDL_Direct3D9GetAdapterIndex()
402 * Added a function to get the D3D9 device for a D3D9 renderer:
403 SDL_RenderGetD3D9Device()
404 * Fixed building SDL with the mingw32 toolchain (mingw-w64 is preferred)
405 * Fixed crash when using two XInput controllers at the same time
406 * Fixed detecting a mixture of XInput and DirectInput controllers
407 * Fixed clearing a D3D render target larger than the window
408 * Improved support for format specifiers in SDL_snprintf()
410 Mac OS X:
411 * Added support for retina displays:
412 Create your window with the SDL_WINDOW_ALLOW_HIGHDPI flag, and then use SDL_GL_GetDrawableSize() to find the actual drawable size. You are responsible for scaling mouse and drawing coordinates appropriately.
413 * Fixed mouse warping in fullscreen mode
414 * Right mouse click is emulated by holding the Ctrl key while left clicking
416 Linux:
417 * Fixed float audio support with the PulseAudio driver
418 * Fixed missing line endpoints in the OpenGL renderer on some drivers
419 * X11 symbols are no longer defined to avoid collisions when linking statically
421 iOS:
422 * Fixed status bar visibility on iOS 7
423 * Flipped the accelerometer Y axis to match expected values
425 Android:
426 IMPORTANT: You MUST get the updated to match C code
427 * Moved EGL initialization to native code
428 * Fixed the accelerometer axis rotation relative to the device rotation
429 * Fixed race conditions when handling the EGL context on pause/resume
430 * Touch devices are available for enumeration immediately after init
432 Raspberry Pi:
433 * Added support for the Raspberry Pi, see README-raspberrypi.txt for details
0 Android
1 ================================================================================
3 Matt Styles wrote a tutorial on building SDL for Android with Visual Studio:
6 The rest of this README covers the Android gradle style build process.
8 If you are using the older ant build process, it is no longer officially
9 supported, but you can use the "android-project-ant" directory as a template.
12 ================================================================================
13 Requirements
14 ================================================================================
16 Android SDK (version 26 or later)
19 Android NDK r15c or later
22 Minimum API level supported by SDL: 14 (Android 4.0.1)
25 ================================================================================
26 How the port works
27 ================================================================================
29 - Android applications are Java-based, optionally with parts written in C
30 - As SDL apps are C-based, we use a small Java shim that uses JNI to talk to
31 the SDL library
32 - This means that your application C code must be placed inside an Android
33 Java project, along with some C support code that communicates with Java
34 - This eventually produces a standard Android .apk package
36 The Android Java code implements an "Activity" and can be found in:
37 android-project/app/src/main/java/org/libsdl/app/
39 The Java code loads your game code, the SDL shared library, and
40 dispatches to native functions implemented in the SDL library:
41 src/core/android/SDL_android.c
44 ================================================================================
45 Building an app
46 ================================================================================
48 For simple projects you can use the script located at build-scripts/
50 There's two ways of using it:
52 com.yourcompany.yourapp < sources.list
53 com.yourcompany.yourapp source1.c source2.c ...sourceN.c
55 sources.list should be a text file with a source file name in each line
56 Filenames should be specified relative to the current directory, for example if
57 you are in the build-scripts directory and want to create the testgles.c test, you'll
58 run:
60 ./ org.libsdl.testgles ../test/testgles.c
62 One limitation of this script is that all sources provided will be aggregated into
63 a single directory, thus all your source files should have a unique name.
65 Once the project is complete the script will tell you where the debug APK is located.
66 If you want to create a signed release APK, you can use the project created by this
67 utility to generate it.
69 Finally, a word of caution: re running wipes any changes you may have
70 done in the build directory for the app!
73 For more complex projects, follow these instructions:
75 1. Copy the android-project directory wherever you want to keep your projects
76 and rename it to the name of your project.
77 2. Move or symlink this SDL directory into the "<project>/app/jni" directory
78 3. Edit "<project>/app/jni/src/" to include your source files
80 4a. If you want to use Android Studio, simply open your <project> directory and start building.
82 4b. 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 Here's an explanation of the files in the Android project, so you can customize them:
86 android-project/app
87 build.gradle - build info including the application version and SDK
88 src/main/AndroidManifest.xml - package manifest. Among others, it contains the class name of the main Activity and the package name of the application.
89 jni/ - directory holding native code
90 jni/ - Application JNI settings, including target platform and STL library
91 jni/ - Android makefile that can call recursively the files in all subdirectories
92 jni/SDL/ - (symlink to) directory holding the SDL library files
93 jni/SDL/ - Android makefile for creating the SDL shared library
94 jni/src/ - directory holding your C/C++ source
95 jni/src/ - Android makefile that you should customize to include your source code and any library references
96 src/main/assets/ - directory holding asset files for your application
97 src/main/res/ - directory holding resources for your application
98 src/main/res/mipmap-* - directories holding icons for different phone hardware
99 src/main/res/values/strings.xml - strings used in your application, including the application name
100 src/main/java/org/libsdl/app/ - 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.
103 ================================================================================
104 Customizing your application name
105 ================================================================================
107 To customize your application name, edit AndroidManifest.xml and replace
108 "" with an identifier for your product package.
110 Then create a Java class extending SDLActivity and place it in a directory
111 under src matching your package, e.g.
113 src/com/gamemaker/game/
115 Here's an example of a minimal class file:
117 --- --------------------------
118 package;
120 import;
122 /**
123 * A sample wrapper class that just calls SDLActivity
124 */
126 public class MyGame extends SDLActivity { }
128 ------------------------------------------
130 Then replace "SDLActivity" in AndroidManifest.xml with the name of your
131 class, .e.g. "MyGame"
134 ================================================================================
135 Customizing your application icon
136 ================================================================================
138 Conceptually changing your icon is just replacing the "ic_launcher.png" files in
139 the drawable directories under the res directory. There are several directories
140 for different screen sizes.
143 ================================================================================
144 Loading assets
145 ================================================================================
147 Any files you put in the "app/src/main/assets" directory of your project
148 directory will get bundled into the application package and you can load
149 them using the standard functions in SDL_rwops.h.
151 There are also a few Android specific functions that allow you to get other
152 useful paths for saving and loading data:
153 * SDL_AndroidGetInternalStoragePath()
154 * SDL_AndroidGetExternalStorageState()
155 * SDL_AndroidGetExternalStoragePath()
157 See SDL_system.h for more details on these functions.
159 The asset packaging system will, by default, compress certain file extensions.
160 SDL includes two asset file access mechanisms, the preferred one is the so
161 called "File Descriptor" method, which is faster and doesn't involve the Dalvik
162 GC, but given this method does not work on compressed assets, there is also the
163 "Input Stream" method, which is automatically used as a fall back by SDL. You
164 may want to keep this fact in mind when building your APK, specially when large
165 files are involved.
166 For more information on which extensions get compressed by default and how to
167 disable this behaviour, see for example:
172 ================================================================================
173 Pause / Resume behaviour
174 ================================================================================
176 If SDL is compiled with SDL_ANDROID_BLOCK_ON_PAUSE defined (the default),
177 the event loop will block itself when the app is paused (ie, when the user
178 returns to the main Android dashboard). Blocking is better in terms of battery
179 use, and it allows your app to spring back to life instantaneously after resume
180 (versus polling for a resume message).
182 Upon resume, SDL will attempt to restore the GL context automatically.
183 In modern devices (Android 3.0 and up) this will most likely succeed and your
184 app can continue to operate as it was.
186 However, there's a chance (on older hardware, or on systems under heavy load),
187 where the GL context can not be restored. In that case you have to listen for
188 a specific message, (which is not yet implemented!) and restore your textures
189 manually or quit the app (which is actually the kind of behaviour you'll see
190 under iOS, if the OS can not restore your GL context it will just kill your app)
193 ================================================================================
194 Threads and the Java VM
195 ================================================================================
197 For a quick tour on how Linux native threads interoperate with the Java VM, take
198 a look here:
200 If you want to use threads in your SDL app, it's strongly recommended that you
201 do so by creating them using SDL functions. This way, the required attach/detach
202 handling is managed by SDL automagically. If you have threads created by other
203 means and they make calls to SDL functions, make sure that you call
204 Android_JNI_SetupThread() before doing anything else otherwise SDL will attach
205 your thread automatically anyway (when you make an SDL call), but it'll never
206 detach it.
209 ================================================================================
210 Using STL
211 ================================================================================
213 You can use STL in your project by creating an file in the jni
214 folder and adding the following line:
216 APP_STL := c++_shared
218 For more information go here:
222 ================================================================================
223 Using the emulator
224 ================================================================================
226 There are some good tips and tricks for getting the most out of the
227 emulator here:
229 Especially useful is the info on setting up OpenGL ES 2.0 emulation.
231 Notice that this software emulator is incredibly slow and needs a lot of disk space.
232 Using a real device works better.
235 ================================================================================
236 Troubleshooting
237 ================================================================================
239 You can see if adb can see any devices with the following command:
241 adb devices
243 You can see the output of log messages on the default device with:
245 adb logcat
247 You can push files to the device with:
249 adb push local_file remote_path_and_file
251 You can push files to the SD Card at /sdcard, for example:
253 adb push moose.dat /sdcard/moose.dat
255 You can see the files on the SD card with a shell command:
257 adb shell ls /sdcard/
259 You can start a command shell on the default device with:
261 adb shell
263 You can remove the library files of your project (and not the SDL lib files) with:
265 ndk-build clean
267 You can do a build with the following command:
269 ndk-build
271 You can see the complete command line that ndk-build is using by passing V=1 on the command line:
273 ndk-build V=1
275 If your application crashes in native code, you can use ndk-stack to get a symbolic stack trace:
278 If you want to go through the process manually, you can use addr2line to convert the
279 addresses in the stack trace to lines in your code.
281 For example, if your crash looks like this:
283 I/DEBUG ( 31): signal 11 (SIGSEGV), code 2 (SEGV_ACCERR), fault addr 400085d0
284 I/DEBUG ( 31): r0 00000000 r1 00001000 r2 00000003 r3 400085d4
285 I/DEBUG ( 31): r4 400085d0 r5 40008000 r6 afd41504 r7 436c6a7c
286 I/DEBUG ( 31): r8 436c6b30 r9 435c6fb0 10 435c6f9c fp 4168d82c
287 I/DEBUG ( 31): ip 8346aff0 sp 436c6a60 lr afd1c8ff pc afd1c902 cpsr 60000030
288 I/DEBUG ( 31): #00 pc 0001c902 /system/lib/
289 I/DEBUG ( 31): #01 pc 0001ccf6 /system/lib/
290 I/DEBUG ( 31): #02 pc 000014bc /data/data/
291 I/DEBUG ( 31): #03 pc 00001506 /data/data/
293 You can see that there's a crash in the C library being called from the main code.
294 I run addr2line with the debug version of my code:
296 arm-eabi-addr2line -C -f -e obj/local/armeabi/
298 and then paste in the number after "pc" in the call stack, from the line that I care about:
299 000014bc
301 I get output from addr2line showing that it's in the quit function, in testspriteminimal.c, on line 23.
303 You can add logging to your code to help show what's happening:
305 #include <android/log.h>
307 __android_log_print(ANDROID_LOG_INFO, "foo", "Something happened! x = %d", x);
309 If you need to build without optimization turned on, you can create a file called
310 "" in the jni directory, with the following line in it:
312 APP_OPTIM := debug
315 ================================================================================
316 Memory debugging
317 ================================================================================
319 The best (and slowest) way to debug memory issues on Android is valgrind.
320 Valgrind has support for Android out of the box, just grab code using:
322 svn co svn:// valgrind
324 ... and follow the instructions in the file to build it.
326 One thing I needed to do on Mac OS X was change the path to the toolchain,
327 and add ranlib to the environment variables:
328 export RANLIB=$NDKROOT/toolchains/arm-linux-androideabi-4.4.3/prebuilt/darwin-x86/bin/arm-linux-androideabi-ranlib
330 Once valgrind is built, you can create a wrapper script to launch your
331 application with it, changing to your package identifier:
333 --- start_valgrind_app -------------------
334 #!/system/bin/sh
335 export TMPDIR=/data/data/
336 exec /data/local/Inst/bin/valgrind --log-file=/sdcard/valgrind.log --error-limit=no $*
337 ------------------------------------------
339 Then push it to the device:
341 adb push start_valgrind_app /data/local
343 and make it executable:
345 adb shell chmod 755 /data/local/start_valgrind_app
347 and tell Android to use the script to launch your application:
349 adb shell setprop "logwrapper /data/local/start_valgrind_app"
351 If the setprop command says "could not set property", it's likely that
352 your package name is too long and you should make it shorter by changing
353 AndroidManifest.xml and the path to your class file in android-project/src
355 You can then launch your application normally and waaaaaaaiiittt for it.
356 You can monitor the startup process with the logcat command above, and
357 when it's done (or even while it's running) you can grab the valgrind
358 output file:
360 adb pull /sdcard/valgrind.log
362 When you're done instrumenting with valgrind, you can disable the wrapper:
364 adb shell setprop ""
367 ================================================================================
368 Graphics debugging
369 ================================================================================
371 If you are developing on a compatible Tegra-based tablet, NVidia provides
372 Tegra Graphics Debugger at their website. Because SDL2 dynamically loads EGL
373 and GLES libraries, you must follow their instructions for installing the
374 interposer library on a rooted device. The non-rooted instructions are not
375 compatible with applications that use SDL2 for video.
377 The Tegra Graphics Debugger is available from NVidia here:
381 ================================================================================
382 Why is API level 14 the minimum required?
383 ================================================================================
385 The latest NDK toolchain doesn't support targeting earlier than API level 14.
386 As of this writing, according to
387 about 99% of the Android devices accessing Google Play support API level 14 or
388 higher (October 2017).
391 ================================================================================
392 A note regarding the use of the "dirty rectangles" rendering technique
393 ================================================================================
395 If your app uses a variation of the "dirty rectangles" rendering technique,
396 where you only update a portion of the screen on each frame, you may notice a
397 variety of visual glitches on Android, that are not present on other platforms.
398 This is caused by SDL's use of EGL as the support system to handle OpenGL ES/ES2
399 contexts, in particular the use of the eglSwapBuffers function. As stated in the
400 documentation for the function "The contents of ancillary buffers are always
401 undefined after calling eglSwapBuffers".
402 Setting the EGL_SWAP_BEHAVIOR attribute of the surface to EGL_BUFFER_PRESERVED
403 is not possible for SDL as it requires EGL 1.4, available only on the API level
404 17+, so the only workaround available on this platform is to redraw the entire
405 screen each frame.
407 Reference:
410 ================================================================================
411 Known issues
412 ================================================================================
414 - The number of buttons reported for each joystick is hardcoded to be 36, which
415 is the current maximum number of buttons Android can report.
0 CMake
1 ================================================================================
2 (
4 SDL's build system was traditionally based on autotools. Over time, this
5 approach has suffered from several issues across the different supported
6 platforms.
7 To solve these problems, a new build system based on CMake is under development.
8 It works in parallel to the legacy system, so users can experiment with it
9 without complication.
10 While still experimental, the build system should be usable on the following
11 platforms:
13 * FreeBSD
14 * Linux
15 * VS.NET 2010
16 * MinGW and Msys
17 * OS X with support for XCode
20 ================================================================================
21 Usage
22 ================================================================================
24 Assuming the source for SDL is located at ~/sdl
26 cd ~
27 mkdir build
28 cd build
29 cmake ../sdl
31 This will build the static and dynamic versions of SDL in the ~/build directory.
0 DirectFB
1 ========
3 Supports:
5 - Hardware YUV overlays
6 - OpenGL - software only
7 - 2D/3D accelerations (depends on directfb driver)
8 - multiple displays
9 - windows
11 What you need:
13 * DirectFB 1.0.1, 1.2.x, 1.3.0
14 * Kernel-Framebuffer support: required: vesafb, radeonfb ....
15 * Mesa 7.0.x - optional for OpenGL
17 /etc/directfbrc
19 This file should contain the following lines to make
20 your joystick work and avoid crashes:
21 ------------------------
22 disable-module=joystick
23 disable-module=cle266
24 disable-module=cyber5k
25 no-linux-input-grab
26 ------------------------
28 To disable to use x11 backend when DISPLAY variable is found use
30 export SDL_DIRECTFB_X11_CHECK=0
32 To disable the use of linux input devices, i.e. multimice/multikeyboard support,
33 use
37 To use hardware accelerated YUV-overlays for YUV-textures, use:
41 This is disabled by default. It will only support one
42 YUV texture, namely the first. Every other YUV texture will be
43 rendered in software.
45 In addition, you may use (directfb-1.2.x)
49 to make the YUV texture an underlay. This will make the cursor to
50 be shown.
52 Simple Window Manager
53 =====================
55 The driver has support for a very, very basic window manager you may
56 want to use when running with "wm=default". Use
58 export SDL_DIRECTFB_WM=1
60 to enable basic window borders. In order to have the window title rendered,
61 you need to have the following font installed:
63 /usr/share/fonts/truetype/freefont/FreeSans.ttf
65 OpenGL Support
66 ==============
68 The following instructions will give you *software* OpenGL. However this
69 works at least on all directfb supported platforms.
71 As of this writing 20100802 you need to pull Mesa from git and do the following:
73 ------------------------
74 git clone git://
75 cd mesa
76 git checkout 2c9fdaf7292423c157fc79b5ce43f0f199dd753a
77 ------------------------
79 Edit configs/linux-directfb so that the Directories-section looks like
80 ------------------------
81 # Directories
82 SRC_DIRS = mesa glu
83 GLU_DIRS = sgi
84 DRIVER_DIRS = directfb
86 ------------------------
88 make linux-directfb
89 make
91 echo Installing - please enter sudo pw.
93 sudo make install INSTALL_DIR=/usr/local/dfb_GL
94 cd src/mesa/drivers/directfb
95 make
96 sudo make install INSTALL_DIR=/usr/local/dfb_GL
97 ------------------------
99 To run the SDL - testprograms:
101 export SDL_VIDEODRIVER=directfb
102 export LD_LIBRARY_PATH=/usr/local/dfb_GL/lib
103 export LD_PRELOAD=/usr/local/dfb_GL/
105 ./testgl
0 Dynamic API
1 ================================================================================
2 Originally posted by Ryan at:
5 Background:
7 - The Steam Runtime has (at least in theory) a really kick-ass build of SDL2,
8 but developers are shipping their own SDL2 with individual Steam games.
9 These games might stop getting updates, but a newer SDL2 might be needed later.
10 Certainly we'll always be fixing bugs in SDL, even if a new video target isn't
11 ever needed, and these fixes won't make it to a game shipping its own SDL.
12 - Even if we replace the SDL2 in those games with a compatible one, that is to
13 say, edit a developer's Steam depot (yuck!), there are developers that are
14 statically linking SDL2 that we can't do this for. We can't even force the
15 dynamic loader to ignore their SDL2 in this case, of course.
16 - If you don't ship an SDL2 with the game in some form, people that disabled the
17 Steam Runtime, or just tried to run the game from the command line instead of
18 Steam might find themselves unable to run the game, due to a missing dependency.
19 - If you want to ship on non-Steam platforms like GOG or Humble Bundle, or target
20 generic Linux boxes that may or may not have SDL2 installed, you have to ship
21 the library or risk a total failure to launch. So now, you might have to have
22 a non-Steam build plus a Steam build (that is, one with and one without SDL2
23 included), which is inconvenient if you could have had one universal build
24 that works everywhere.
25 - We like the zlib license, but the biggest complaint from the open source
26 community about the license change is the static linking. The LGPL forced this
27 as a legal, not technical issue, but zlib doesn't care. Even those that aren't
28 concerned about the GNU freedoms found themselves solving the same problems:
29 swapping in a newer SDL to an older game often times can save the day.
30 Static linking stops this dead.
32 So here's what we did:
34 SDL now has, internally, a table of function pointers. So, this is what SDL_Init
35 now looks like:
37 UInt32 SDL_Init(Uint32 flags)
38 {
39 return jump_table.SDL_Init(flags);
40 }
42 Except that is all done with a bunch of macro magic so we don't have to maintain
43 every one of these.
45 What is jump_table.SDL_init()? Eventually, that's a function pointer of the real
46 SDL_Init() that you've been calling all this time. But at startup, it looks more
47 like this:
49 Uint32 SDL_Init_DEFAULT(Uint32 flags)
50 {
51 SDL_InitDynamicAPI();
52 return jump_table.SDL_Init(flags);
53 }
55 SDL_InitDynamicAPI() fills in jump_table with all the actual SDL function
56 pointers, which means that this _DEFAULT function never gets called again.
57 First call to any SDL function sets the whole thing up.
59 So you might be asking, what was the value in that? Isn't this what the operating
60 system's dynamic loader was supposed to do for us? Yes, but now we've got this
61 level of indirection, we can do things like this:
63 export SDL_DYNAMIC_API=/my/actual/
64 ./MyGameThatIsStaticallyLinkedToSDL2
66 And now, this game that is statically linked to SDL, can still be overridden
67 with a newer, or better, SDL. The statically linked one will only be used as
68 far as calling into the jump table in this case. But in cases where no override
69 is desired, the statically linked version will provide its own jump table,
70 and everyone is happy.
72 So now:
73 - Developers can statically link SDL, and users can still replace it.
74 (We'd still rather you ship a shared library, though!)
75 - Developers can ship an SDL with their game, Valve can override it for, say,
76 new features on SteamOS, or distros can override it for their own needs,
77 but it'll also just work in the default case.
78 - Developers can ship the same package to everyone (Humble Bundle, GOG, etc),
79 and it'll do the right thing.
80 - End users (and Valve) can update a game's SDL in almost any case,
81 to keep abandoned games running on newer platforms.
82 - Everyone develops with SDL exactly as they have been doing all along.
83 Same headers, same ABI. Just get the latest version to enable this magic.
86 A little more about SDL_InitDynamicAPI():
88 Internally, InitAPI does some locking to make sure everything waits until a
89 single thread initializes everything (although even SDL_CreateThread() goes
90 through here before spinning a thread, too), and then decides if it should use
91 an external SDL library. If not, it sets up the jump table using the current
92 SDL's function pointers (which might be statically linked into a program, or in
93 a shared library of its own). If so, it loads that library and looks for and
94 calls a single function:
96 SInt32 SDL_DYNAPI_entry(Uint32 version, void *table, Uint32 tablesize);
98 That function takes a version number (more on that in a moment), the address of
99 the jump table, and the size, in bytes, of the table.
100 Now, we've got policy here: this table's layout never changes; new stuff gets
101 added to the end. Therefore SDL_DYNAPI_entry() knows that it can provide all
102 the needed functions if tablesize <= sizeof its own jump table. If tablesize is
103 bigger (say, SDL 2.0.4 is trying to load SDL 2.0.3), then we know to abort, but
104 if it's smaller, we know we can provide the entire API that the caller needs.
106 The version variable is a failsafe switch.
107 Right now it's always 1. This number changes when there are major API changes
108 (so we know if the tablesize might be smaller, or entries in it have changed).
109 Right now SDL_DYNAPI_entry gives up if the version doesn't match, but it's not
110 inconceivable to have a small dispatch library that only supplies this one
111 function and loads different, otherwise-incompatible SDL libraries and has the
112 right one initialize the jump table based on the version. For something that
113 must generically catch lots of different versions of SDL over time, like the
114 Steam Client, this isn't a bad option.
116 Finally, I'm sure some people are reading this and thinking,
117 "I don't want that overhead in my project!"
118 To which I would point out that the extra function call through the jump table
119 probably wouldn't even show up in a profile, but lucky you: this can all be
120 disabled. You can build SDL without this if you absolutely must, but we would
121 encourage you not to do that. However, on heavily locked down platforms like
122 iOS, or maybe when debugging, it makes sense to disable it. The way this is
123 designed in SDL, you just have to change one #define, and the entire system
124 vaporizes out, and SDL functions exactly like it always did. Most of it is
125 macro magic, so the system is contained to one C file and a few headers.
126 However, this is on by default and you have to edit a header file to turn it
127 off. Our hopes is that if we make it easy to disable, but not too easy,
128 everyone will ultimately be able to get what they want, but we've gently
129 nudged everyone towards what we think is the best solution.
0 Emscripten
1 ================================================================================
3 Build:
5 $ mkdir build
6 $ cd build
7 $ emconfigure ../configure --host=asmjs-unknown-emscripten --disable-assembly --disable-threads --disable-cpuinfo CFLAGS="-O2"
8 $ emmake make
10 Or with cmake:
12 $ mkdir build
13 $ cd build
14 $ emcmake cmake ..
15 $ emmake make
17 To build one of the tests:
19 $ cd test/
20 $ emcc -O2 --js-opts 0 -g4 testdraw2.c -I../include ../build/.libs/libSDL2.a ../build/libSDL2_test.a -o a.html
22 Uses GLES2 renderer or software
24 Some other SDL2 libraries can be easily built (assuming SDL2 is installed somewhere):
26 SDL_mixer (
28 $ EMCONFIGURE_JS=1 emconfigure ../configure
29 build as usual...
31 SDL_gfx (
33 $ EMCONFIGURE_JS=1 emconfigure ../configure --disable-mmx
34 build as usual...
0 Dollar Gestures
1 ===========================================================================
2 SDL provides an implementation of the $1 gesture recognition system. This allows for recording, saving, loading, and performing single stroke gestures.
4 Gestures can be performed with any number of fingers (the centroid of the fingers must follow the path of the gesture), but the number of fingers must be constant (a finger cannot go down in the middle of a gesture). The path of a gesture is considered the path from the time when the final finger went down, to the first time any finger comes up.
6 Dollar gestures are assigned an Id based on a hash function. This is guaranteed to remain constant for a given gesture. There is a (small) chance that two different gestures will be assigned the same ID. In this case, simply re-recording one of the gestures should result in a different ID.
8 Recording:
9 ----------
10 To begin recording on a touch device call:
11 SDL_RecordGesture(SDL_TouchID touchId), where touchId is the id of the touch device you wish to record on, or -1 to record on all connected devices.
13 Recording terminates as soon as a finger comes up. Recording is acknowledged by an SDL_DOLLARRECORD event.
14 A SDL_DOLLARRECORD event is a dgesture with the following fields:
16 * event.dgesture.touchId - the Id of the touch used to record the gesture.
17 * event.dgesture.gestureId - the unique id of the recorded gesture.
20 Performing:
21 -----------
22 As long as there is a dollar gesture assigned to a touch, every finger-up event will also cause an SDL_DOLLARGESTURE event with the following fields:
24 * event.dgesture.touchId - the Id of the touch which performed the gesture.
25 * event.dgesture.gestureId - the unique id of the closest gesture to the performed stroke.
26 * event.dgesture.error - the difference between the gesture template and the actual performed gesture. Lower error is a better match.
27 * event.dgesture.numFingers - the number of fingers used to draw the stroke.
29 Most programs will want to define an appropriate error threshold and check to be sure that the error of a gesture is not abnormally high (an indicator that no gesture was performed).
33 Saving:
34 -------
35 To 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 To 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 Both functions return the number of gestures successfully saved.
42 Loading:
43 --------
44 To load templates from a file, call SDL_LoadDollarTemplates(touchId,src) where touchId is the id of the touch to load to (or -1 to load to all touch devices), and src is an SDL_RWops pointer to a gesture save file.
46 SDL_LoadDollarTemplates returns the number of templates successfully loaded.
50 ===========================================================================
51 Multi Gestures
52 ===========================================================================
53 SDL provides simple support for pinch/rotate/swipe gestures.
54 Every time a finger is moved an SDL_MULTIGESTURE event is sent with the following fields:
56 * event.mgesture.touchId - the Id of the touch on which the gesture was performed.
57 * event.mgesture.x - the normalized x coordinate of the gesture. (0..1)
58 * event.mgesture.y - the normalized y coordinate of the gesture. (0..1)
59 * event.mgesture.dTheta - the amount that the fingers rotated during this motion.
60 * event.mgesture.dDist - the amount that the fingers pinched during this motion.
61 * event.mgesture.numFingers - the number of fingers used in the gesture.
64 ===========================================================================
65 Notes
66 ===========================================================================
67 For a complete example see test/testgesture.c
69 Please direct questions/comments to:
0 Mercurial
1 =========
3 The latest development version of SDL is available via Mercurial.
4 Mercurial allows you to get up-to-the-minute fixes and enhancements;
5 as a developer works on a source tree, you can use "hg" to mirror that
6 source tree instead of waiting for an official release. Please look
7 at the Mercurial website ( ) for more
8 information on using hg, where you can also download software for
9 Mac OS X, Windows, and Unix systems.
11 hg clone
13 If you are building SDL via configure, you will need to run
14 before running configure.
16 There is a web interface to the subversion repository at:
19 There is an RSS feed available at that URL, for those that want to
20 track commits in real time.
0 iOS
1 ======
3 ==============================================================================
4 Building the Simple DirectMedia Layer for iOS 5.1+
5 ==============================================================================
7 Requirements: Mac OS X 10.8 or later and the iOS 7+ SDK.
9 Instructions:
11 1. Open SDL.xcodeproj (located in Xcode-iOS/SDL) in Xcode.
12 2. Select your desired target, and hit build.
14 There are three build targets:
15 - libSDL.a:
16 Build SDL as a statically linked library
17 - testsdl:
18 Build a test program (there are known test failures which are fine)
19 - Template:
20 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.
23 ==============================================================================
24 Build SDL for iOS from the command line
25 ==============================================================================
27 1. cd (PATH WHERE THE SDL CODE IS)/build-scripts
28 2. ./
30 If everything goes fine, you should see a build/ios directory, inside there's
31 two directories "lib" and "include".
32 "include" contains a copy of the SDL headers that you'll need for your project,
33 make sure to configure XCode to look for headers there.
34 "lib" contains find two files, libSDL2.a and libSDL2main.a, you have to add both
35 to your XCode project. These libraries contain three architectures in them,
36 armv6 for legacy devices, armv7, and i386 (for the simulator).
37 By default, will autodetect the SDK version you have installed using
38 xcodebuild -showsdks, and build for iOS >= 3.0, you can override this behaviour
39 by setting the MIN_OS_VERSION variable, ie:
41 MIN_OS_VERSION=4.2 ./
43 ==============================================================================
44 Using the Simple DirectMedia Layer for iOS
45 ==============================================================================
47 FIXME: This needs to be updated for the latest methods
49 Here is the easiest method:
50 1. Build the SDL library (libSDL2.a) and the iPhone SDL Application template.
51 2. 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.
52 3. Start a new project using the template. The project should be immediately ready for use with SDL.
54 Here is a more manual method:
55 1. Create a new iOS view based application.
56 2. 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.
57 3. Include the SDL header files in your project.
58 4. 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.
59 5. Delete the contents of main.m and program your app as a regular SDL program instead. You may replace main.m with your own main.c, but you must tell Xcode not to use the project prefix file, as it includes Objective-C code.
61 ==============================================================================
62 Notes -- Retina / High-DPI and window sizes
63 ==============================================================================
65 Window and display mode sizes in SDL are in "screen coordinates" (or "points",
66 in Apple's terminology) rather than in pixels. On iOS this means that a window
67 created on an iPhone 6 will have a size in screen coordinates of 375 x 667,
68 rather than a size in pixels of 750 x 1334. All iOS apps are expected to
69 size their content based on screen coordinates / points rather than pixels,
70 as this allows different iOS devices to have different pixel densities
71 (Retina versus non-Retina screens, etc.) without apps caring too much.
73 By default SDL will not use the full pixel density of the screen on
74 Retina/high-dpi capable devices. Use the SDL_WINDOW_ALLOW_HIGHDPI flag when
75 creating your window to enable high-dpi support.
77 When high-dpi support is enabled, SDL_GetWindowSize() and display mode sizes
78 will still be in "screen coordinates" rather than pixels, but the window will
79 have a much greater pixel density when the device supports it, and the
80 SDL_GL_GetDrawableSize() or SDL_GetRendererOutputSize() functions (depending on
81 whether raw OpenGL or the SDL_Render API is used) can be queried to determine
82 the size in pixels of the drawable screen framebuffer.
84 Some OpenGL ES functions such as glViewport expect sizes in pixels rather than
85 sizes in screen coordinates. When doing 2D rendering with OpenGL ES, an
86 orthographic projection matrix using the size in screen coordinates
87 (SDL_GetWindowSize()) can be used in order to display content at the same scale
88 no matter whether a Retina device is used or not.
90 ==============================================================================
91 Notes -- Application events
92 ==============================================================================
94 On iOS the application goes through a fixed life cycle and you will get
95 notifications of state changes via application events. When these events
96 are delivered you must handle them in an event callback because the OS may
97 not give you any processing time after the events are delivered.
99 e.g.
101 int HandleAppEvents(void *userdata, SDL_Event *event)
102 {
103 switch (event->type)
104 {
106 /* Terminate the app.
107 Shut everything down before returning from this function.
108 */
109 return 0;
111 /* You will get this when your app is paused and iOS wants more memory.
112 Release as much memory as possible.
113 */
114 return 0;
116 /* Prepare your app to go into the background. Stop loops, etc.
117 This gets called when the user hits the home button, or gets a call.
118 */
119 return 0;
121 /* This will get called if the user accepted whatever sent your app to the background.
122 If the user got a phone call and canceled it, you'll instead get an SDL_APP_DIDENTERFOREGROUND event and restart your loops.
123 When you get this, you have 5 seconds to save all your state or the app will be terminated.
124 Your app is NOT active at this point.
125 */
126 return 0;
128 /* This call happens when your app is coming back to the foreground.
129 Restore all your state here.
130 */
131 return 0;
133 /* Restart your loops here.
134 Your app is interactive and getting CPU again.
135 */
136 return 0;
137 default:
138 /* No special processing, add it to the event queue */
139 return 1;
140 }
141 }
143 int main(int argc, char *argv[])
144 {
145 SDL_SetEventFilter(HandleAppEvents, NULL);
147 ... run your main loop
149 return 0;
150 }
153 ==============================================================================
154 Notes -- Accelerometer as Joystick
155 ==============================================================================
157 SDL 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 The 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 Notes -- OpenGL ES
163 ==============================================================================
165 Your SDL application for iOS uses OpenGL ES for video by default.
167 OpenGL 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 If your application doesn't use OpenGL's depth buffer, you may find significant performance improvement by setting SDL_GL_DEPTH_SIZE to 0.
171 Finally, 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 OpenGL 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 - The drawable Renderbuffer must be bound to the GL_RENDERBUFFER binding point when SDL_GL_SwapWindow() is called.
176 - The drawable Framebuffer Object must be bound while rendering to the screen and when SDL_GL_SwapWindow() is called.
177 - 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 The above objects can be obtained via SDL_GetWindowWMInfo() (in SDL_syswm.h).
181 ==============================================================================
182 Notes -- Keyboard
183 ==============================================================================
185 The SDL keyboard API has been extended to support on-screen keyboards:
187 void SDL_StartTextInput()
188 -- enables text events and reveals the onscreen keyboard.
190 void SDL_StopTextInput()
191 -- disables text events and hides the onscreen keyboard.
193 SDL_bool SDL_IsTextInputActive()
194 -- returns whether or not text events are enabled (and the onscreen keyboard is visible)
197 ==============================================================================
198 Notes -- Reading and Writing files
199 ==============================================================================
201 Each 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 Once your application is installed its directory tree looks like:
205 MySDLApp Home/
207 Documents/
208 Library/
209 Preferences/
210 tmp/
212 When your SDL based iPhone application starts up, it sets the working directory to the main bundle (MySDLApp Home/, 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 More information on this subject is available here:
217 ==============================================================================
218 Notes -- iPhone SDL limitations
219 ==============================================================================
221 Windows:
222 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 Textures:
225 The optimal texture formats on iOS are SDL_PIXELFORMAT_ABGR8888, SDL_PIXELFORMAT_ABGR8888, SDL_PIXELFORMAT_BGR888, and SDL_PIXELFORMAT_RGB24 pixel formats.
227 Loading Shared Objects:
228 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 Game Center
232 ==============================================================================
234 Game 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:
236 int SDL_iPhoneSetAnimationCallback(SDL_Window * window, int interval, void (*callback)(void*), void *callbackParam);
238 This 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.
240 e.g.
242 extern "C"
243 void ShowFrame(void*)
244 {
245 ... do event handling, frame logic and rendering ...
246 }
248 int main(int argc, char *argv[])
249 {
250 ... initialize game ...
252 #if __IPHONEOS__
253 // Initialize the Game Center for scoring and matchmaking
254 InitGameCenter();
256 // Set up the game to run in the window animation callback on iOS
257 // so that Game Center and so forth works correctly.
258 SDL_iPhoneSetAnimationCallback(window, 1, ShowFrame, NULL);
259 #else
260 while ( running ) {
261 ShowFrame(0);
262 DelayFrame();
263 }
264 #endif
265 return 0;
266 }
268 ==============================================================================
269 Deploying to older versions of iOS
270 ==============================================================================
272 SDL supports deploying to older versions of iOS than are supported by the latest version of Xcode, all the way back to iOS 6.1
274 In order to do that you need to download an older version of Xcode:
277 Open the package contents of the older Xcode and your newer version of Xcode and copy over the folders in
279 Then open the file and add the versions of iOS you want to deploy to the key Root/DefaultProperties/DEPLOYMENT_TARGET_SUGGESTED_VALUES
281 Open your project and set your deployment target to the desired version of iOS
283 Finally, 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
0 Linux
1 ================================================================================
3 By default SDL will only link against glibc, the rest of the features will be
4 enabled dynamically at runtime depending on the available features on the target
5 system. So, for example if you built SDL with Xinerama support and the target
6 system does not have the Xinerama libraries installed, it will be disabled
7 at runtime, and you won't get a missing library error, at least with the
8 default configuration parameters.
11 ================================================================================
12 Build Dependencies
13 ================================================================================
15 Ubuntu 13.04, all available features enabled:
17 sudo apt-get install build-essential mercurial make cmake autoconf automake \
18 libtool libasound2-dev libpulse-dev libaudio-dev libx11-dev libxext-dev \
19 libxrandr-dev libxcursor-dev libxi-dev libxinerama-dev libxxf86vm-dev \
20 libxss-dev libgl1-mesa-dev libesd0-dev libdbus-1-dev libudev-dev \
21 libgles1-mesa-dev libgles2-mesa-dev libegl1-mesa-dev libibus-1.0-dev \
22 fcitx-libs-dev libsamplerate0-dev libsndio-dev
24 Ubuntu 16.04+ can also add "libwayland-dev libxkbcommon-dev wayland-protocols"
25 to that command line for Wayland support.
27 Ubuntu 16.10 can also add "libmirclient-dev libxkbcommon-dev" to that command
28 line for Mir support.
31 - This includes all the audio targets except arts, because Ubuntu pulled the
32 artsc0-dev package, but in theory SDL still supports it.
33 - libsamplerate0-dev lets SDL optionally link to libresamplerate at runtime
34 for higher-quality audio resampling. SDL will work without it if the library
35 is missing, so it's safe to build in support even if the end user doesn't
36 have this library installed.
37 - DirectFB isn't included because the configure script (currently) fails to find
38 it at all. You can do "sudo apt-get install libdirectfb-dev" and fix the
39 configure script to include DirectFB support. Send patches. :)
42 ================================================================================
43 Joystick does not work
44 ================================================================================
46 If you compiled or are using a version of SDL with udev support (and you should!)
47 there's a few issues that may cause SDL to fail to detect your joystick. To
48 debug this, start by installing the evtest utility. On Ubuntu/Debian:
50 sudo apt-get install evtest
52 Then run:
54 sudo evtest
56 You'll hopefully see your joystick listed along with a name like "/dev/input/eventXX"
57 Now run:
59 cat /dev/input/event/XX
61 If you get a permission error, you need to set a udev rule to change the mode of
62 your device (see below)
64 Also, try:
66 sudo udevadm info --query=all --name=input/eventXX
68 If you see a line stating ID_INPUT_JOYSTICK=1, great, if you don't see it,
69 you need to set up an udev rule to force this variable.
71 A combined rule for the Saitek Pro Flight Rudder Pedals to fix both issues looks
72 like:
74 SUBSYSTEM=="input", ATTRS{idProduct}=="0763", ATTRS{idVendor}=="06a3", MODE="0666", ENV{ID_INPUT_JOYSTICK}="1"
75 SUBSYSTEM=="input", ATTRS{idProduct}=="0764", ATTRS{idVendor}=="06a3", MODE="0666", ENV{ID_INPUT_JOYSTICK}="1"
77 You can set up similar rules for your device by changing the values listed in
78 idProduct and idVendor. To obtain these values, try:
80 sudo udevadm info -a --name=input/eventXX | grep idVendor
81 sudo udevadm info -a --name=input/eventXX | grep idProduct
83 If multiple values come up for each of these, the one you want is the first one of each.
85 On other systems which ship with an older udev (such as CentOS), you may need
86 to set up a rule such as:
88 SUBSYSTEM=="input", ENV{ID_CLASS}=="joystick", ENV{ID_INPUT_JOYSTICK}="1"
0 Mac OS X
1 ==============================================================================
3 These instructions are for people using Apple's Mac OS X (pronounced
4 "ten").
6 From the developer's point of view, OS X is a sort of hybrid Mac and
7 Unix system, and you have the option of using either traditional
8 command line tools or Apple's IDE Xcode.
10 Command Line Build
11 ==================
13 To build SDL using the command line, use the standard configure and make
14 process:
16 ./configure
17 make
18 sudo make install
20 You can also build SDL as a Universal library (a single binary for both
21 32-bit and 64-bit Intel architectures), on Mac OS X 10.7 and newer, by using
22 the script in build-scripts:
24 mkdir mybuild
25 cd mybuild
26 CC=$PWD/../build-scripts/ CXX=$PWD/../build-scripts/ ../configure
27 make
28 sudo make install
30 This script builds SDL with 10.5 ABI compatibility on i386 and 10.6
31 ABI compatibility on x86_64 architectures. For best compatibility you
32 should compile your application the same way.
34 Please note that building SDL requires at least Xcode 4.6 and the 10.7 SDK
35 (even if you target back to 10.5 systems). PowerPC support for Mac OS X has
36 been officially dropped as of SDL 2.0.2.
38 To use the library once it's built, you essential have two possibilities:
39 use the traditional autoconf/automake/make method, or use Xcode.
41 ==============================================================================
42 Caveats for using SDL with Mac OS X
43 ==============================================================================
45 Some things you have to be aware of when using SDL on Mac OS X:
47 - If you register your own NSApplicationDelegate (using [NSApp setDelegate:]),
48 SDL will not register its own. This means that SDL will not terminate using
49 SDL_Quit if it receives a termination request, it will terminate like a
50 normal app, and it will not send a SDL_DROPFILE when you request to open a
51 file with the app. To solve these issues, put the following code in your
52 NSApplicationDelegate implementation:
55 - (NSApplicationTerminateReply)applicationShouldTerminate:(NSApplication *)sender
56 {
57 if (SDL_GetEventState(SDL_QUIT) == SDL_ENABLE) {
58 SDL_Event event;
59 event.type = SDL_QUIT;
60 SDL_PushEvent(&event);
61 }
63 return NSTerminateCancel;
64 }
66 - (BOOL)application:(NSApplication *)theApplication openFile:(NSString *)filename
67 {
68 if (SDL_GetEventState(SDL_DROPFILE) == SDL_ENABLE) {
69 SDL_Event event;
70 event.type = SDL_DROPFILE;
71 event.drop.file = SDL_strdup([filename UTF8String]);
72 return (SDL_PushEvent(&event) > 0);
73 }
75 return NO;
76 }
78 ==============================================================================
79 Using the Simple DirectMedia Layer with a traditional Makefile
80 ==============================================================================
82 An existing autoconf/automake build system for your SDL app has good chances
83 to work almost unchanged on OS X. However, to produce a "real" Mac OS X binary
84 that you can distribute to users, you need to put the generated binary into a
85 so called "bundle", which basically is a fancy folder with a name like
86 "".
88 To get this build automatically, add something like the following rule to
89 your
91 bundle_contents =
92 APP_NAME_bundle: EXE_NAME
93 mkdir -p $(bundle_contents)/MacOS
94 mkdir -p $(bundle_contents)/Resources
95 echo "APPL????" > $(bundle_contents)/PkgInfo
96 $(INSTALL_PROGRAM) $< $(bundle_contents)/MacOS/
98 You should replace EXE_NAME with the name of the executable. APP_NAME is what
99 will be visible to the user in the Finder. Usually it will be the same
100 as EXE_NAME but capitalized. E.g. if EXE_NAME is "testgame" then APP_NAME
101 usually is "TestGame". You might also want to use `@PACKAGE@` to use the package
102 name as specified in your file.
104 If your project builds more than one application, you will have to do a bit
105 more. For each of your target applications, you need a separate rule.
107 If you want the created bundles to be installed, you may want to add this
108 rule to your
110 install-exec-hook: APP_NAME_bundle
111 rm -rf $(DESTDIR)$(prefix)/Applications/
112 mkdir -p $(DESTDIR)$(prefix)/Applications/
113 cp -r $< /$(DESTDIR)$(prefix)Applications/
115 This rule takes the Bundle created by the rule from step 3 and installs them
116 into "$(DESTDIR)$(prefix)/Applications/".
118 Again, if you want to install multiple applications, you will have to augment
119 the make rule accordingly.
122 But beware! That is only part of the story! With the above, you end up with
123 a bare bone .app bundle, which is double clickable from the Finder. But
124 there are some more things you should do before shipping your product...
126 1) The bundle right now probably is dynamically linked against SDL. That
127 means that when you copy it to another computer, *it will not run*,
128 unless you also install SDL on that other computer. A good solution
129 for this dilemma is to static link against SDL. On OS X, you can
130 achieve that by linking against the libraries listed by
132 sdl-config --static-libs
134 instead of those listed by
136 sdl-config --libs
138 Depending on how exactly SDL is integrated into your build systems, the
139 way to achieve that varies, so I won't describe it here in detail
141 2) Add an 'Info.plist' to your application. That is a special XML file which
142 contains some meta-information about your application (like some copyright
143 information, the version of your app, the name of an optional icon file,
144 and other things). Part of that information is displayed by the Finder
145 when you click on the .app, or if you look at the "Get Info" window.
146 More information about Info.plist files can be found on Apple's homepage.
149 As a final remark, let me add that I use some of the techniques (and some
150 variations of them) in Exult and ScummVM; both are available in source on
151 the net, so feel free to take a peek at them for inspiration!
154 ==============================================================================
155 Using the Simple DirectMedia Layer with Xcode
156 ==============================================================================
158 These instructions are for using Apple's Xcode IDE to build SDL applications.
160 - First steps
162 The first thing to do is to unpack the Xcode.tar.gz archive in the
163 top level SDL directory (where the Xcode.tar.gz archive resides).
164 Because Stuffit Expander will unpack the archive into a subdirectory,
165 you should unpack the archive manually from the command line:
167 cd [path_to_SDL_source]
168 tar zxf Xcode.tar.gz
170 This will create a new folder called Xcode, which you can browse
171 normally from the Finder.
173 - Building the Framework
175 The SDL Library is packaged as a framework bundle, an organized
176 relocatable folder hierarchy of executable code, interface headers,
177 and additional resources. For practical purposes, you can think of a
178 framework as a more user and system-friendly shared library, whose library
179 file behaves more or less like a standard UNIX shared library.
181 To build the framework, simply open the framework project and build it.
182 By default, the framework bundle "SDL.framework" is installed in
183 /Library/Frameworks. Therefore, the testers and project stationary expect
184 it to be located there. However, it will function the same in any of the
185 following locations:
187 ~/Library/Frameworks
188 /Local/Library/Frameworks
189 /System/Library/Frameworks
191 - Build Options
192 There are two "Build Styles" (See the "Targets" tab) for SDL.
193 "Deployment" should be used if you aren't tweaking the SDL library.
194 "Development" should be used to debug SDL apps or the library itself.
196 - Building the Testers
197 Open the SDLTest project and build away!
199 - Using the Project Stationary
200 Copy the stationary to the indicated folders to access it from
201 the "New Project" and "Add target" menus. What could be easier?
203 - Setting up a new project by hand
204 Some of you won't want to use the Stationary so I'll give some tips:
205 * Create a new "Cocoa Application"
206 * Add src/main/macosx/SDLMain.m , .h and .nib to your project
207 * Remove "main.c" from your project
208 * Remove "MainMenu.nib" from your project
209 * Add "$(HOME)/Library/Frameworks/SDL.framework/Headers" to include path
210 * Add "$(HOME)/Library/Frameworks" to the frameworks search path
211 * Add "-framework SDL -framework Foundation -framework AppKit" to "OTHER_LDFLAGS"
212 * Set the "Main Nib File" under "Application Settings" to "SDLMain.nib"
213 * Add your files
214 * Clean and build
216 - Building from command line
217 Use pbxbuild in the same directory as your .pbproj file
219 - Running your app
220 You can send command line args to your app by either invoking it from
221 the command line (in *.app/Contents/MacOS) or by entering them in the
222 "Executables" panel of the target settings.
224 - Implementation Notes
225 Some things that may be of interest about how it all works...
226 * Working directory
227 As defined in the SDL_main.m file, the working directory of your SDL app
228 is by default set to its parent. You may wish to change this to better
229 suit your needs.
230 * You have a Cocoa App!
231 Your SDL app is essentially a Cocoa application. When your app
232 starts up and the libraries finish loading, a Cocoa procedure is called,
233 which sets up the working directory and calls your main() method.
234 You are free to modify your Cocoa app with generally no consequence
235 to SDL. You cannot, however, easily change the SDL window itself.
236 Functionality may be added in the future to help this.
239 Known bugs are listed in the file "BUGS.txt".
0 Native Client
1 ================================================================================
3 Requirements:
5 * Native Client SDK (,
6 (tested with Pepper version 33 or higher).
8 The SDL backend for Chrome's Native Client has been tested only with the PNaCl
9 toolchain, which generates binaries designed to run on ARM and x86_32/64
10 platforms. This does not mean it won't work with the other toolchains!
12 ================================================================================
13 Building SDL for NaCl
14 ================================================================================
16 Set up the right environment variables (see, then configure SDL with:
18 configure --host=pnacl --prefix some/install/destination
20 Then "make".
22 As an example of how to create a deployable app a Makefile project is provided
23 in test/nacl/Makefile, which includes some monkey patching of the file
24 provided by NaCl, without which linking properly to SDL won't work (the search
25 path can't be modified externally, so the linker won't find SDL's binaries unless
26 you dump them into the SDK path, which is inconvenient).
27 Also provided in test/nacl is the required support file, such as index.html,
28 manifest.json, etc.
29 SDL apps for NaCl run on a worker thread using the ppapi_simple infrastructure.
30 This allows for blocking calls on all the relevant systems (OpenGL ES, filesystem),
31 hiding the asynchronous nature of the browser behind the scenes...which is not the
32 same as making it disappear!
35 ================================================================================
36 Running tests
37 ================================================================================
39 Due to the nature of NaCl programs, building and running SDL tests is not as
40 straightforward as one would hope. The script in build-scripts
41 automates the process and should serve as a guide for users of SDL trying to build
42 their own applications.
44 Basic usage:
46 ./ path/to/pepper/toolchain (i.e. ~/naclsdk/pepper_35)
48 This will build testgles2.c by default.
50 If you want to build a different test, for example testrendercopyex.c:
52 SOURCES=~/sdl/SDL/test/testrendercopyex.c ./ ~/naclsdk/pepper_35
54 Once the build finishes, you have to serve the contents with a web server (the
55 script will give you instructions on how to do that with Python).
57 ================================================================================
58 RWops and nacl_io
59 ================================================================================
61 SDL_RWops work transparently with nacl_io. Two functions control the mount points:
63 int mount(const char* source, const char* target,
64 const char* filesystemtype,
65 unsigned long mountflags, const void *data);
66 int umount(const char *target);
68 For convenience, SDL will by default mount an httpfs tree at / before calling
69 the app's main function. Such setting can be overridden by calling:
71 umount("/");
73 And then mounting a different filesystem at /
75 It's important to consider that the asynchronous nature of file operations on a
76 browser is hidden from the application, effectively providing the developer with
77 a set of blocking file operations just like you get in a regular desktop
78 environment, which eases the job of porting to Native Client, but also introduces
79 a set of challenges of its own, in particular when big file sizes and slow
80 connections are involved.
82 For more information on how nacl_io and mount points work, see:
87 To be able to save into the directory "/save/" (like backup of game) :
89 mount("", "/save", "html5fs", 0, "type=PERSISTENT");
91 And add to manifest.json :
93 "permissions": [
94 "unlimitedStorage"
95 ]
97 ================================================================================
98 TODO - Known Issues
99 ================================================================================
100 * Testing of all systems with a real application (something other than SDL's tests)
101 * Key events don't seem to work properly
0 Pandora
1 =====================================================================
3 ( )
4 - A pandora specific video driver was written to allow SDL 2.0 with OpenGL ES
5 support to work on the pandora under the framebuffer. This driver do not have
6 input support for now, so if you use it you will have to add your own control code.
7 The video driver name is "pandora" so if you have problem running it from
8 the framebuffer, try to set the following variable before starting your application :
9 "export SDL_VIDEODRIVER=pandora"
11 - OpenGL ES support was added to the x11 driver, so it's working like the normal
12 x11 driver one with OpenGLX support, with SDL input event's etc..
15 David Carré (Cpasjuste)
0 Platforms
1 =========
3 We maintain the list of supported platforms on our wiki now, and how to
4 build and install SDL for those platforms:
0 Porting
1 =======
3 * Porting To A New Platform
5 The first thing you have to do when porting to a new platform, is look at
6 include/SDL_platform.h and create an entry there for your operating system.
7 The standard format is "__PLATFORM__", where PLATFORM is the name of the OS.
8 Ideally SDL_platform.h will be able to auto-detect the system it's building
9 on based on C preprocessor symbols.
11 There are two basic ways of building SDL at the moment:
13 1. The "UNIX" way: ./configure; make; make install
15 If you have a GNUish system, then you might try this. Edit,
16 take a look at the large section labelled:
18 "Set up the configuration based on the host platform!"
20 Add a section for your platform, and then re-run and build!
22 2. Using an IDE:
24 If you're using an IDE or other non-configure build system, you'll probably
25 want to create a custom SDL_config.h for your platform. Edit SDL_config.h,
26 add a section for your platform, and create a custom SDL_config_{platform}.h,
27 based on SDL_config_minimal.h and
29 Add the top level include directory to the header search path, and then add
30 the following sources to the project:
32 src/*.c
33 src/atomic/*.c
34 src/audio/*.c
35 src/cpuinfo/*.c
36 src/events/*.c
37 src/file/*.c
38 src/haptic/*.c
39 src/joystick/*.c
40 src/power/*.c
41 src/render/*.c
42 src/render/software/*.c
43 src/stdlib/*.c
44 src/thread/*.c
45 src/timer/*.c
46 src/video/*.c
47 src/audio/disk/*.c
48 src/audio/dummy/*.c
49 src/filesystem/dummy/*.c
50 src/video/dummy/*.c
51 src/haptic/dummy/*.c
52 src/joystick/dummy/*.c
53 src/main/dummy/*.c
54 src/thread/generic/*.c
55 src/timer/dummy/*.c
56 src/loadso/dummy/*.c
59 Once you have a working library without any drivers, you can go back to each
60 of the major subsystems and start implementing drivers for your platform.
62 If you have any questions, don't hesitate to ask on the SDL mailing list:
65 Enjoy!
66 Sam Lantinga (
1 ======
2 SDL port for the Sony PSP contributed by
3 Captian Lex
5 Credit to
6 Marcus R.Brown,Jim Paris,Matthew H for the original SDL 1.2 for PSP
7 Geecko for his PSP GU lib "Glib2d"
9 Building
10 --------
11 To build for the PSP, make sure psp-config is in the path and run:
12 make -f Makefile.psp
16 To Do
17 ------
18 PSP Screen Keyboard
0 Raspberry Pi
1 ================================================================================
3 Requirements:
5 Raspbian (other Linux distros may work as well).
7 ================================================================================
8 Features
9 ================================================================================
11 * Works without X11
12 * Hardware accelerated OpenGL ES 2.x
13 * Sound via ALSA
14 * Input (mouse/keyboard/joystick) via EVDEV
15 * Hotplugging of input devices via UDEV
18 ================================================================================
19 Raspbian Build Dependencies
20 ================================================================================
22 sudo apt-get install libudev-dev libasound2-dev libdbus-1-dev
24 You also need the VideoCore binary stuff that ships in /opt/vc for EGL and
25 OpenGL ES 2.x, it usually comes pre-installed, but in any case:
27 sudo apt-get install libraspberrypi0 libraspberrypi-bin libraspberrypi-dev
30 ================================================================================
32 ================================================================================
34 If your Pi has NEON support, make sure you add -mfpu=neon to your CFLAGS so
35 that SDL will select some otherwise-disabled highly-optimized code. The
36 original Pi units don't have NEON, the Pi2 probably does, and the Pi3
37 definitely does.
39 ================================================================================
40 Cross compiling from x86 Linux
41 ================================================================================
43 To cross compile SDL for Raspbian from your desktop machine, you'll need a
44 Raspbian system root and the cross compilation tools. We'll assume these tools
45 will be placed in /opt/rpi-tools
47 sudo git clone --depth 1 /opt/rpi-tools
49 You'll also need a Raspbian binary image.
50 Get it from:
51 After unzipping, you'll get file with a name like: "<date>-wheezy-raspbian.img"
52 Let's assume the sysroot will be built in /opt/rpi-sysroot.
54 export SYSROOT=/opt/rpi-sysroot
55 sudo kpartx -a -v <path_to_raspbian_image>.img
56 sudo mount -o loop /dev/mapper/loop0p2 /mnt
57 sudo cp -r /mnt $SYSROOT
58 sudo apt-get install qemu binfmt-support qemu-user-static
59 sudo cp /usr/bin/qemu-arm-static $SYSROOT/usr/bin
60 sudo mount --bind /dev $SYSROOT/dev
61 sudo mount --bind /proc $SYSROOT/proc
62 sudo mount --bind /sys $SYSROOT/sys
64 Now, before chrooting into the ARM sysroot, you'll need to apply a workaround,
65 edit $SYSROOT/etc/ and comment out all lines in it.
67 sudo chroot $SYSROOT
68 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
69 exit
70 sudo umount $SYSROOT/dev
71 sudo umount $SYSROOT/proc
72 sudo umount $SYSROOT/sys
73 sudo umount /mnt
75 There's one more fix required, as the symlink uses an absolute path
76 which doesn't quite work in our setup.
78 sudo rm -rf $SYSROOT/usr/lib/arm-linux-gnueabihf/
79 sudo ln -s ../../../lib/arm-linux-gnueabihf/ $SYSROOT/usr/lib/arm-linux-gnueabihf/
81 The final step is compiling SDL itself.
83 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"
84 cd <SDL SOURCE>
85 mkdir -p build;cd build
86 LDFLAGS="-L$SYSROOT/opt/vc/lib" ../configure --with-sysroot=$SYSROOT --host=arm-raspberry-linux-gnueabihf --prefix=$PWD/rpi-sdl2-installed --disable-pulseaudio --disable-esd
87 make
88 make install
90 To be able to deploy this to /usr/local in the Raspbian system you need to fix up a few paths:
92 perl -w -pi -e "s#$PWD/rpi-sdl2-installed#/usr/local#g;" ./rpi-sdl2-installed/lib/ ./rpi-sdl2-installed/lib/pkgconfig/sdl2.pc ./rpi-sdl2-installed/bin/sdl2-config
94 ================================================================================
95 Apps don't work or poor video/audio performance
96 ================================================================================
98 If you get sound problems, buffer underruns, etc, run "sudo rpi-update" to
99 update the RPi's firmware. Note that doing so will fix these problems, but it
100 will also render the CMA - Dynamic Memory Split functionality useless.
102 Also, by default the Raspbian distro configures the GPU RAM at 64MB, this is too
103 low in general, specially if a 1080p TV is hooked up.
105 See here how to configure this setting:
107 Using a fixed gpu_mem=128 is the best option (specially if you updated the
108 firmware, using CMA probably won't work, at least it's the current case).
110 ================================================================================
111 No input
112 ================================================================================
114 Make sure you belong to the "input" group.
116 sudo usermod -aG input `whoami`
118 ================================================================================
119 No HDMI Audio
120 ================================================================================
122 If you notice that ALSA works but there's no audio over HDMI, try adding:
124 hdmi_drive=2
126 to your config.txt file and reboot.
128 Reference:
130 ================================================================================
131 Text Input API support
132 ================================================================================
134 The Text Input API is supported, with translation of scan codes done via the
135 kernel symbol tables. For this to work, SDL needs access to a valid console.
136 If you notice there's no SDL_TEXTINPUT message being emitted, double check that
137 your app has read access to one of the following:
139 * /proc/self/fd/0
140 * /dev/tty
141 * /dev/tty[0...6]
142 * /dev/vc/0
143 * /dev/console
145 This is usually not a problem if you run from the physical terminal (as opposed
146 to running from a pseudo terminal, such as via SSH). If running from a PTS, a
147 quick workaround is to run your app as root or add yourself to the tty group,
148 then re-login to the system.
150 sudo usermod -aG tty `whoami`
152 The keyboard layout used by SDL is the same as the one the kernel uses.
153 To configure the layout on Raspbian:
155 sudo dpkg-reconfigure keyboard-configuration
157 To configure the locale, which controls which keys are interpreted as letters,
158 this determining the CAPS LOCK behavior:
160 sudo dpkg-reconfigure locales
162 ================================================================================
163 OpenGL problems
164 ================================================================================
166 If you have desktop OpenGL headers installed at build time in your RPi or cross
167 compilation environment, support for it will be built in. However, the chipset
168 does not actually have support for it, which causes issues in certain SDL apps
169 since the presence of OpenGL support supersedes the ES/ES2 variants.
170 The workaround is to disable OpenGL at configuration time:
172 ./configure --disable-video-opengl
174 Or if the application uses the Render functions, you can use the SDL_RENDER_DRIVER
175 environment variable:
177 export SDL_RENDER_DRIVER=opengles2
179 ================================================================================
180 Notes
181 ================================================================================
183 * When launching apps remotely (via SSH), SDL can prevent local keystrokes from
184 leaking into the console only if it has root privileges. Launching apps locally
185 does not suffer from this issue.
0 Touch
1 ===========================================================================
2 System Specific Notes
3 ===========================================================================
4 Linux:
5 The linux touch system is currently based off event streams, and proc/bus/devices. The active user must be given permissions to read /dev/input/TOUCHDEVICE, where TOUCHDEVICE is the event stream for your device. Currently only Wacom tablets are supported. If you have an unsupported tablet contact me at and I will help you get support for it.
7 Mac:
8 The Mac and iPhone APIs are pretty. If your touch device supports them then you'll be fine. If it doesn't, then there isn't much we can do.
10 iPhone:
11 Works out of box.
13 Windows:
14 Unfortunately there is no windows support as of yet. Support for Windows 7 is planned, but we currently have no way to test. If you have a Windows 7 WM_TOUCH supported device, and are willing to help test please contact me at
16 ===========================================================================
17 Events
18 ===========================================================================
20 Sent when a finger (or stylus) is placed on a touch device.
21 Fields:
22 * event.tfinger.touchId - the Id of the touch device.
23 * event.tfinger.fingerId - the Id of the finger which just went down.
24 * event.tfinger.x - the x coordinate of the touch (0..1)
25 * event.tfinger.y - the y coordinate of the touch (0..1)
26 * event.tfinger.pressure - the pressure of the touch (0..1)
29 Sent when a finger (or stylus) is moved on the touch device.
30 Fields:
31 Same as SDL_FINGERDOWN but with additional:
32 * event.tfinger.dx - change in x coordinate during this motion event.
33 * event.tfinger.dy - change in y coordinate during this motion event.
36 Sent when a finger (or stylus) is lifted from the touch device.
37 Fields:
41 ===========================================================================
42 Functions
43 ===========================================================================
44 SDL provides the ability to access the underlying SDL_Finger structures.
45 These structures should _never_ be modified.
47 The following functions are included from SDL_touch.h
49 To get a SDL_TouchID call SDL_GetTouchDevice(int index).
50 This returns a SDL_TouchID.
51 IMPORTANT: 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 The number of touch devices can be queried with SDL_GetNumTouchDevices().
55 A SDL_TouchID may be used to get pointers to SDL_Finger.
57 SDL_GetNumTouchFingers(touchID) may be used to get the number of fingers currently down on the device.
59 The most common reason to access SDL_Finger is to query the fingers outside the event. In most cases accessing the fingers is using the event. This would be accomplished by code like the following:
61 float x = event.tfinger.x;
62 float y = event.tfinger.y;
66 To get a SDL_Finger, call SDL_GetTouchFinger(SDL_TouchID touchID, int index), where touchID is a SDL_TouchID, and index is the requested finger.
67 This returns a SDL_Finger *, or NULL if the finger does not exist, or has been removed.
68 A SDL_Finger is guaranteed to be persistent for the duration of a touch, but it will be de-allocated as soon as the finger is removed. This occurs when the SDL_FINGERUP event is _added_ to the event queue, and thus _before_ the SDL_FINGERUP event is polled.
69 As a result, be very careful to check for NULL return values.
71 A SDL_Finger has the following fields:
72 * x, y:
73 The current coordinates of the touch.
74 * pressure:
75 The pressure of the touch.
78 ===========================================================================
79 Notes
80 ===========================================================================
81 For a complete example see test/testgesture.c
83 Please direct questions/comments to:
85 (original author, API was changed since)
0 WinCE
1 =====
3 Windows CE is no longer supported by SDL.
5 We have left the CE support in SDL 1.2 for those that must have it, and we
6 have support for Windows Phone 8 and WinRT in SDL2, as of SDL 2.0.3.
8 --ryan.
0 Windows
1 ================================================================================
3 ================================================================================
4 OpenGL ES 2.x support
5 ================================================================================
7 SDL has support for OpenGL ES 2.x under Windows via two alternative
8 implementations.
9 The most straightforward method consists in running your app in a system with
10 a graphic card paired with a relatively recent (as of November of 2013) driver
11 which supports the WGL_EXT_create_context_es2_profile extension. Vendors known
12 to ship said extension on Windows currently include nVidia and Intel.
14 The other method involves using the ANGLE library (
15 If an OpenGL ES 2.x context is requested and no WGL_EXT_create_context_es2_profile
16 extension is found, SDL will try to load the libEGL.dll library provided by
18 To obtain the ANGLE binaries, you can either compile from source from
19 or copy the relevant binaries from
20 a recent Chrome/Chromium install for Windows. The files you need are:
22 * libEGL.dll
23 * libGLESv2.dll
24 * d3dcompiler_46.dll (supports Windows Vista or later, better shader compiler)
25 or...
26 * d3dcompiler_43.dll (supports Windows XP or later)
28 If you compile ANGLE from source, you can configure it so it does not need the
29 d3dcompiler_* DLL at all (for details on this, see their documentation).
30 However, by default SDL will try to preload the d3dcompiler_46.dll to
31 comply with ANGLE's requirements. If you wish SDL to preload d3dcompiler_43.dll (to
32 support Windows XP) or to skip this step at all, you can use the
33 SDL_HINT_VIDEO_WIN_D3DCOMPILER hint (see SDL_hints.h for more details).
35 Known Bugs:
37 * SDL_GL_SetSwapInterval is currently a no op when using ANGLE. It appears
38 that there's a bug in the library which prevents the window contents from
39 refreshing if this is set to anything other than the default value.
41 Vulkan Surface Support
42 ==============
44 Support 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]( in order to use Vulkan graphics in your application.
0 WinRT
1 =====
3 This port allows SDL applications to run on Microsoft's platforms that require
4 use of "Windows Runtime", aka. "WinRT", APIs. Microsoft may, in some cases,
5 refer to them as either "Windows Store", or for Windows 10, "UWP" apps.
7 Some of the operating systems that include WinRT, are:
9 * Windows 10, via its Universal Windows Platform (UWP) APIs
10 * Windows 8.x
11 * Windows RT 8.x (aka. Windows 8.x for ARM processors)
12 * Windows Phone 8.x
15 Requirements
16 ------------
18 * Microsoft Visual C++ (aka Visual Studio), either 2017, 2015, 2013, or 2012
19 - Free, "Community" or "Express" editions may be used, so long as they
20 include support for either "Windows Store" or "Windows Phone" apps.
21 "Express" versions marked as supporting "Windows Desktop" development
22 typically do not include support for creating WinRT apps, to note.
23 (The "Community" editions of Visual C++ do, however, support both
24 desktop/Win32 and WinRT development).
25 - Visual Studio 2017 can be used, however it is recommended that you install
26 the Visual C++ 2015 build tools. These build tools can be installed
27 using VS 2017's installer. Be sure to also install the workload for
28 "Universal Windows Platform development", its optional component, the
29 "C++ Universal Windows Platform tools", and for UWP / Windows 10
30 development, the "Windows 10 SDK (10.0.10240.0)". Please note that
31 targeting UWP / Windows 10 apps from development machine(s) running
32 earlier versions of Windows, such as Windows 7, is not always supported
33 by Visual Studio, and you may get error(s) when attempting to do so.
34 - Visual C++ 2012 can only build apps that target versions 8.0 of Windows,
35 or Windows Phone. 8.0-targeted apps will run on devices running 8.1
36 editions of Windows, however they will not be able to take advantage of
37 8.1-specific features.
38 - Visual C++ 2013 cannot create app projects that target Windows 8.0.
39 Visual C++ 2013 Update 4, can create app projects for Windows Phone 8.0,
40 Windows Phone 8.1, and Windows 8.1, but not Windows 8.0. An optional
41 Visual Studio add-in, "Tools for Maintaining Store apps for Windows 8",
42 allows Visual C++ 2013 to load and build Windows 8.0 projects that were
43 created with Visual C++ 2012, so long as Visual C++ 2012 is installed
44 on the same machine. More details on targeting different versions of
45 Windows can found at the following web pages:
46 - [Develop apps by using Visual Studio 2013](
47 - [To add the Tools for Maintaining Store apps for Windows 8](
48 * A valid Microsoft account - This requirement is not imposed by SDL, but
49 rather by Microsoft's Visual C++ toolchain. This is required to launch or
50 debug apps.
53 Status
54 ------
56 Here is a rough list of what works, and what doesn't:
58 * What works:
59 * compilation via Visual C++ 2012 through 2015
60 * compile-time platform detection for SDL programs. The C/C++ #define,
61 `__WINRT__`, will be set to 1 (by SDL) when compiling for WinRT.
62 * GPU-accelerated 2D rendering, via SDL_Renderer.
63 * OpenGL ES 2, via the ANGLE library (included separately from SDL)
64 * software rendering, via either SDL_Surface (optionally in conjunction with
65 SDL_GetWindowSurface() and SDL_UpdateWindowSurface()) or via the
66 SDL_Renderer APIs
67 * threads
68 * timers (via SDL_GetTicks(), SDL_AddTimer(), SDL_GetPerformanceCounter(),
69 SDL_GetPerformanceFrequency(), etc.)
70 * file I/O via SDL_RWops
71 * mouse input (unsupported on Windows Phone)
72 * audio, via SDL's WASAPI backend (if you want to record, your app must
73 have "Microphone" capabilities enabled in its manifest, and the user must
74 not have blocked access. Otherwise, capture devices will fail to work,
75 presenting as a device disconnect shortly after opening it.)
76 * .DLL file loading. Libraries *MUST* be packaged inside applications. Loading
77 anything outside of the app is not supported.
78 * system path retrieval via SDL's filesystem APIs
79 * game controllers. Support is provided via the SDL_Joystick and
80 SDL_GameController APIs, and is backed by Microsoft's XInput API. Please
81 note, however, that Windows limits game-controller support in UWP apps to,
82 "Xbox compatible controllers" (many controllers that work in Win32 apps,
83 do not work in UWP, due to restrictions in UWP itself.)
84 * multi-touch input
85 * app events. SDL_APP_WILLENTER* and SDL_APP_DIDENTER* events get sent out as
86 appropriate.
87 * window events
88 * using Direct3D 11.x APIs outside of SDL. Non-XAML / Direct3D-only apps can
89 choose to render content directly via Direct3D, using SDL to manage the
90 internal WinRT window, as well as input and audio. (Use
91 SDL_GetWindowWMInfo() to get the WinRT 'CoreWindow', and pass it into
92 IDXGIFactory2::CreateSwapChainForCoreWindow() as appropriate.)
94 * What partially works:
95 * keyboard input. Most of WinRT's documented virtual keys are supported, as
96 well as many keys with documented hardware scancodes. Converting
97 SDL_Scancodes to or from SDL_Keycodes may not work, due to missing APIs
98 (MapVirtualKey()) in Microsoft's Windows Store / UWP APIs.
99 * SDLmain. WinRT uses a different signature for each app's main() function.
100 SDL-based apps that use this port must compile in SDL_winrt_main_NonXAML.cpp
101 (in `SDL\src\main\winrt\`) directly in order for their C-style main()
102 functions to be called.
104 * What doesn't work:
105 * compilation with anything other than Visual C++
106 * programmatically-created custom cursors. These don't appear to be supported
107 by WinRT. Different OS-provided cursors can, however, be created via
108 SDL_CreateSystemCursor() (unsupported on Windows Phone)
109 * SDL_WarpMouseInWindow() or SDL_WarpMouseGlobal(). This are not currently
110 supported by WinRT itself.
111 * joysticks and game controllers that either are not supported by
112 Microsoft's XInput API, or are not supported within UWP apps (many
113 controllers that work in Win32, do not work in UWP, due to restrictions in
114 UWP itself).
115 * turning off VSync when rendering on Windows Phone. Attempts to turn VSync
116 off on Windows Phone result either in Direct3D not drawing anything, or it
117 forcing VSync back on. As such, SDL_RENDERER_PRESENTVSYNC will always get
118 turned-on on Windows Phone. This limitation is not present in non-Phone
119 WinRT (such as Windows 8.x), where turning off VSync appears to work.
120 * probably anything else that's not listed as supported
124 Upgrade Notes
125 -------------
127 #### SDL_GetPrefPath() usage when upgrading WinRT apps from SDL 2.0.3
129 SDL 2.0.4 fixes two bugs found in the WinRT version of SDL_GetPrefPath().
130 The fixes may affect older, SDL 2.0.3-based apps' save data. Please note
131 that these changes only apply to SDL-based WinRT apps, and not to apps for
132 any other platform.
134 1. SDL_GetPrefPath() would return an invalid path, one in which the path's
135 directory had not been created. Attempts to create files there
136 (via fopen(), for example), would fail, unless that directory was
137 explicitly created beforehand.
139 2. SDL_GetPrefPath(), for non-WinPhone-based apps, would return a path inside
140 a WinRT 'Roaming' folder, the contents of which get automatically
141 synchronized across multiple devices. This process can occur while an
142 application runs, and can cause existing save-data to be overwritten
143 at unexpected times, with data from other devices. (Windows Phone apps
144 written with SDL 2.0.3 did not utilize a Roaming folder, due to API
145 restrictions in Windows Phone 8.0).
148 SDL_GetPrefPath(), starting with SDL 2.0.4, addresses these by:
150 1. making sure that SDL_GetPrefPath() returns a directory in which data
151 can be written to immediately, without first needing to create directories.
153 2. basing SDL_GetPrefPath() off of a different, non-Roaming folder, the
154 contents of which do not automatically get synchronized across devices
155 (and which require less work to use safely, in terms of data integrity).
157 Apps that wish to get their Roaming folder's path can do so either by using
158 SDL_WinRTGetFSPathUTF8(), SDL_WinRTGetFSPathUNICODE() (which returns a
159 UCS-2/wide-char string), or directly through the WinRT class,
160 Windows.Storage.ApplicationData.
164 Setup, High-Level Steps
165 -----------------------
167 The steps for setting up a project for an SDL/WinRT app looks like the
168 following, at a high-level:
170 1. create a new Visual C++ project using Microsoft's template for a,
171 "Direct3D App".
172 2. remove most of the files from the project.
173 3. make your app's project directly reference SDL/WinRT's own Visual C++
174 project file, via use of Visual C++'s "References" dialog. This will setup
175 the linker, and will copy SDL's .dll files to your app's final output.
176 4. adjust your app's build settings, at minimum, telling it where to find SDL's
177 header files.
178 5. add files that contains a WinRT-appropriate main function, along with some
179 data to make sure mouse-cursor-hiding (via SDL_ShowCursor(SDL_DISABLE) calls)
180 work properly.
181 6. add SDL-specific app code.
182 7. build and run your app.
185 Setup, Detailed Steps
186 ---------------------
188 ### 1. Create a new project ###
190 Create a new project using one of Visual C++'s templates for a plain, non-XAML,
191 "Direct3D App" (XAML support for SDL/WinRT is not yet ready for use). If you
192 don't see one of these templates, in Visual C++'s 'New Project' dialog, try
193 using the textbox titled, 'Search Installed Templates' to look for one.
196 ### 2. Remove unneeded files from the project ###
198 In the new project, delete any file that has one of the following extensions:
200 - .cpp
201 - .h
202 - .hlsl
204 When you are done, you should be left with a few files, each of which will be a
205 necessary part of your app's project. These files will consist of:
207 - an .appxmanifest file, which contains metadata on your WinRT app. This is
208 similar to an Info.plist file on iOS, or an AndroidManifest.xml on Android.
209 - a few .png files, one of which is a splash screen (displayed when your app
210 launches), others are app icons.
211 - a .pfx file, used for code signing purposes.
214 ### 3. Add references to SDL's project files ###
216 SDL/WinRT can be built in multiple variations, spanning across three different
217 CPU architectures (x86, x64, and ARM) and two different configurations
218 (Debug and Release). WinRT and Visual C++ do not currently provide a means
219 for combining multiple variations of one library into a single file.
220 Furthermore, it does not provide an easy means for copying pre-built .dll files
221 into your app's final output (via Post-Build steps, for example). It does,
222 however, provide a system whereby an app can reference the MSVC projects of
223 libraries such that, when the app is built:
225 1. each library gets built for the appropriate CPU architecture(s) and WinRT
226 platform(s).
227 2. each library's output, such as .dll files, get copied to the app's build
228 output.
230 To set this up for SDL/WinRT, you'll need to run through the following steps:
232 1. open up the Solution Explorer inside Visual C++ (under the "View" menu, then
233 "Solution Explorer")
234 2. right click on your app's solution.
235 3. navigate to "Add", then to "Existing Project..."
236 4. find SDL/WinRT's Visual C++ project file and open it. Different project
237 files exist for different WinRT platforms. All of them are in SDL's
238 source distribution, in the following directories:
239 * `VisualC-WinRT/UWP_VS2015/` - for Windows 10 / UWP apps
240 * `VisualC-WinRT/WinPhone81_VS2013/` - for Windows Phone 8.1 apps
241 * `VisualC-WinRT/WinRT80_VS2012/` - for Windows 8.0 apps
242 * `VisualC-WinRT/WinRT81_VS2013/` - for Windows 8.1 apps
243 5. once the project has been added, right-click on your app's project and
244 select, "References..."
245 6. click on the button titled, "Add New Reference..."
246 7. check the box next to SDL
247 8. click OK to close the dialog
248 9. SDL will now show up in the list of references. Click OK to close that
249 dialog.
251 Your project is now linked to SDL's project, insofar that when the app is
252 built, SDL will be built as well, with its build output getting included with
253 your app.
256 ### 4. Adjust Your App's Build Settings ###
258 Some build settings need to be changed in your app's project. This guide will
259 outline the following:
261 - making sure that the compiler knows where to find SDL's header files
262 - **Optional for C++, but NECESSARY for compiling C code:** telling the
263 compiler not to use Microsoft's C++ extensions for WinRT development.
264 - **Optional:** telling the compiler not generate errors due to missing
265 precompiled header files.
267 To change these settings:
269 1. right-click on the project
270 2. choose "Properties"
271 3. in the drop-down box next to "Configuration", choose, "All Configurations"
272 4. in the drop-down box next to "Platform", choose, "All Platforms"
273 5. in the left-hand list, expand the "C/C++" section
274 6. select "General"
275 7. edit the "Additional Include Directories" setting, and add a path to SDL's
276 "include" directory
277 8. **Optional: to enable compilation of C code:** change the setting for
278 "Consume Windows Runtime Extension" from "Yes (/ZW)" to "No". If you're
279 working with a completely C++ based project, this step can usually be
280 omitted.
281 9. **Optional: to disable precompiled headers (which can produce
282 'stdafx.h'-related build errors, if setup incorrectly:** in the left-hand
283 list, select "Precompiled Headers", then change the setting for "Precompiled
284 Header" from "Use (/Yu)" to "Not Using Precompiled Headers".
285 10. close the dialog, saving settings, by clicking the "OK" button
288 ### 5. Add a WinRT-appropriate main function, and a blank-cursor image, to the app. ###
290 A few files should be included directly in your app's MSVC project, specifically:
291 1. a WinRT-appropriate main function (which is different than main() functions on
292 other platforms)
293 2. a Win32-style cursor resource, used by SDL_ShowCursor() to hide the mouse cursor
294 (if and when the app needs to do so). *If this cursor resource is not
295 included, mouse-position reporting may fail if and when the cursor is
296 hidden, due to possible bugs/design-oddities in Windows itself.*
298 To include these files:
300 1. right-click on your project (again, in Visual C++'s Solution Explorer),
301 navigate to "Add", then choose "Existing Item...".
302 2. navigate to the directory containing SDL's source code, then into its
303 subdirectory, 'src/main/winrt/'. Select, then add, the following files:
304 - `SDL_winrt_main_NonXAML.cpp`
305 - `SDL2-WinRTResources.rc`
306 - `SDL2-WinRTResource_BlankCursor.cur`
307 3. right-click on the file `SDL_winrt_main_NonXAML.cpp` (as listed in your
308 project), then click on "Properties...".
309 4. in the drop-down box next to "Configuration", choose, "All Configurations"
310 5. in the drop-down box next to "Platform", choose, "All Platforms"
311 6. in the left-hand list, click on "C/C++"
312 7. change the setting for "Consume Windows Runtime Extension" to "Yes (/ZW)".
313 8. click the OK button. This will close the dialog.
316 **NOTE: C++/CX compilation is currently required in at least one file of your
317 app's project. This is to make sure that Visual C++'s linker builds a 'Windows
318 Metadata' file (.winmd) for your app. Not doing so can lead to build errors.**
321 ### 6. Add app code and assets ###
323 At this point, you can add in SDL-specific source code. Be sure to include a
324 C-style main function (ie: `int main(int argc, char *argv[])`). From there you
325 should be able to create a single `SDL_Window` (WinRT apps can only have one
326 window, at present), as well as an `SDL_Renderer`. Direct3D will be used to
327 draw content. Events are received via SDL's usual event functions
328 (`SDL_PollEvent`, etc.) If you have a set of existing source files and assets,
329 you can start adding them to the project now. If not, or if you would like to
330 make sure that you're setup correctly, some short and simple sample code is
331 provided below.
334 #### 6.A. ... when creating a new app ####
336 If you are creating a new app (rather than porting an existing SDL-based app),
337 or if you would just like a simple app to test SDL/WinRT with before trying to
338 get existing code working, some working SDL/WinRT code is provided below. To
339 set this up:
341 1. right click on your app's project
342 2. select Add, then New Item. An "Add New Item" dialog will show up.
343 3. from the left-hand list, choose "Visual C++"
344 4. from the middle/main list, choose "C++ File (.cpp)"
345 5. near the bottom of the dialog, next to "Name:", type in a name for your
346 source file, such as, "main.cpp".
347 6. click on the Add button. This will close the dialog, add the new file to
348 your project, and open the file in Visual C++'s text editor.
349 7. Copy and paste the following code into the new file, then save it.
352 #include <SDL.h>
354 int main(int argc, char **argv)
355 {
356 SDL_DisplayMode mode;
357 SDL_Window * window = NULL;
358 SDL_Renderer * renderer = NULL;
359 SDL_Event evt;
361 if (SDL_Init(SDL_INIT_VIDEO) != 0) {
362 return 1;
363 }
365 if (SDL_GetCurrentDisplayMode(0, &mode) != 0) {
366 return 1;
367 }
369 if (SDL_CreateWindowAndRenderer(mode.w, mode.h, SDL_WINDOW_FULLSCREEN, &window, &renderer) != 0) {
370 return 1;
371 }
373 while (1) {
374 while (SDL_PollEvent(&evt)) {
375 }
377 SDL_SetRenderDrawColor(renderer, 0, 255, 0, 255);
378 SDL_RenderClear(renderer);
379 SDL_RenderPresent(renderer);
380 }
381 }
384 #### 6.B. Adding code and assets ####
386 If you have existing code and assets that you'd like to add, you should be able
387 to add them now. The process for adding a set of files is as such.
389 1. right click on the app's project
390 2. select Add, then click on "New Item..."
391 3. open any source, header, or asset files as appropriate. Support for C and
392 C++ is available.
394 Do note that WinRT only supports a subset of the APIs that are available to
395 Win32-based apps. Many portions of the Win32 API and the C runtime are not
396 available.
398 A list of unsupported C APIs can be found at
399 <>
401 General information on using the C runtime in WinRT can be found at
402 <>
404 A list of supported Win32 APIs for WinRT apps can be found at
405 <>. To note,
406 the list of supported Win32 APIs for Windows Phone 8.0 is different.
407 That list can be found at
408 <>
411 ### 7. Build and run your app ###
413 Your app project should now be setup, and you should be ready to build your app.
414 To run it on the local machine, open the Debug menu and choose "Start