wikipreamble = (This is the legacy documentation for stable SDL2, the current stable version; [SDL3](https://wiki.libsdl.org/SDL3/) is the current development version.)
message(FATAL_ERROR"Prevented in-tree build. Please create a build directory outside of the SDL source code and run \"cmake-S${CMAKE_SOURCE_DIR}-B.\" from there")
message(FATAL_ERROR"Prevented in-tree build. Please create a build directory outside of the SDL source code and run \"cmake-S${CMAKE_SOURCE_DIR}-B.\" from there")
* Added access to the individual left and right gyro sensors of the combined Joy-Cons controller
* Added access to the individual left and right gyro sensors of the combined Joy-Cons controller
* Added a microsecond timestamp to SDL_SensorEvent and SDL_ControllerSensorEvent, when the hardware provides that information
* Added a microsecond timestamp to SDL_SensorEvent and SDL_ControllerSensorEvent, when the hardware provides that information
* Added SDL_SensorGetDataWithTimestamp() and SDL_GameControllerGetSensorDataWithTimestamp() to retrieve the last sensor data with the associated microsecond timestamp
* Added SDL_SensorGetDataWithTimestamp() and SDL_GameControllerGetSensorDataWithTimestamp() to retrieve the last sensor data with the associated microsecond timestamp
* Added the hint SDL_HINT_HIDAPI_IGNORE_DEVICES to have the SDL HID API ignore specific devices
* Added the hint SDL_HINT_HIDAPI_IGNORE_DEVICES to have the SDL HID API ignore specific devices
* SDL_GetRevision() now includes more information about the SDL build, including the git commit hash if available
* SDL_GetRevision() now includes more information about the SDL build, including the git commit hash if available
Windows:
Windows:
@ -645,7 +662,7 @@ iOS:
tvOS:
tvOS:
* Added support for Apple TV
* Added support for Apple TV
* 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.
* 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.
Android:
Android:
* Fixed SDL not resizing window when Android screen resolution changes
* Fixed SDL not resizing window when Android screen resolution changes
@ -790,8 +807,8 @@ Linux:
* Added experimental Wayland and Mir support, disabled by default
* Added experimental Wayland and Mir support, disabled by default
Android:
Android:
* Joystick support (minimum SDK version required to build SDL is now 12,
the required runtime version remains at 10, but on such devices joystick
* Joystick support (minimum SDK version required to build SDL is now 12,
the required runtime version remains at 10, but on such devices joystick
support won't be available).
support won't be available).
* Hotplugging support for joysticks
* Hotplugging support for joysticks
* 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.
* 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.
@ -844,7 +861,7 @@ iOS:
Android:
Android:
IMPORTANT: You MUST get the updated SDLActivity.java to match C code
IMPORTANT: You MUST get the updated SDLActivity.java to match C code
* Moved EGL initialization to native code
* Moved EGL initialization to native code
* Fixed the accelerometer axis rotation relative to the device rotation
* Fixed the accelerometer axis rotation relative to the device rotation
* Fixed race conditions when handling the EGL context on pause/resume
* Fixed race conditions when handling the EGL context on pause/resume
* Touch devices are available for enumeration immediately after init
* Touch devices are available for enumeration immediately after init
nextifnot$dent=~ /$selectheaderregex/;# just selected headers.
nextifnot$dent=~ /$selectheaderregex/;# just selected headers.
open(FH,'<',"$incpath/$dent")ordie("Can't open '$incpath/$dent': $!\n");
open(FH,'<',"$incpath/$dent")ordie("Can't open '$incpath/$dent': $!\n");
@ -588,8 +669,8 @@ my %wikitypes = (); # contains string of wiki page extension, like $wikitypes{"
my%wikifuncs=();# contains references to hash of strings, each string being the full contents of a section of a wiki page, like $wikifuncs{"SDL_OpenAudio"}{"Remarks"}.
my%wikifuncs=();# contains references to hash of strings, each string being the full contents of a section of a wiki page, like $wikifuncs{"SDL_OpenAudio"}{"Remarks"}.
my%wikisectionorder=();# contains references to array, each array item being a key to a wikipage section in the correct order, like $wikisectionorder{"SDL_OpenAudio"}[2] == 'Remarks'
my%wikisectionorder=();# contains references to array, each array item being a key to a wikipage section in the correct order, like $wikisectionorder{"SDL_OpenAudio"}[2] == 'Remarks'
- Android applications are Java-based, optionally with parts written in C
- Android applications are Java-based, optionally with parts written in C
- As SDL apps are C-based, we use a small Java shim that uses JNI to talk to
- As SDL apps are C-based, we use a small Java shim that uses JNI to talk to
the SDL library
the SDL library
- This means that your application C code must be placed inside an Android
- This means that your application C code must be placed inside an Android
Java project, along with some C support code that communicates with Java
Java project, along with some C support code that communicates with Java
- This eventually produces a standard Android .apk package
- This eventually produces a standard Android .apk package
@ -68,14 +68,22 @@ Finally, a word of caution: re running androidbuild.sh wipes any changes you may
done in the build directory for the app!
done in the build directory for the app!
For more complex projects, follow these instructions:
For more complex projects, follow these instructions:
1. Copy the android-project directory wherever you want to keep your projects
and rename it to the name of your project.
2. Move or symlink this SDL directory into the "<project>/app/jni" directory
3. Edit "<project>/app/jni/src/Android.mk" to include your source files
4a. If you want to use Android Studio, simply open your <project> directory and start building.
1. Get the source code for SDL and copy the 'android-project' directory located at SDL/android-project to a suitable location. Also make sure to rename it to your project name (In these examples: YOURPROJECT).
(The 'android-project' directory can basically be seen as a sort of starting point for the android-port of your project. It contains the glue code between the Android Java 'frontend' and the SDL code 'backend'. It also contains some standard behaviour, like how events should be handled, which you will be able to change.)
2. Move or [symlink](https://en.wikipedia.org/wiki/Symbolic_link) the SDL directory into the "YOURPROJECT/app/jni" directory
(This is needed as the source of SDL has to be compiled by the Android compiler)
3. Edit "YOURPROJECT/app/jni/src/Android.mk" to include your source files.
(They should be separated by spaces after the "LOCAL_SRC_FILES := " declaration)
4a. If you want to use Android Studio, simply open your 'YOURPROJECT' directory and start building.
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
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
@ -83,9 +91,9 @@ For more complex projects, follow these instructions:
If you already have a project that uses CMake, the instructions change somewhat:
If you already have a project that uses CMake, the instructions change somewhat:
1. Do points 1 and 2 from the instruction above.
1. Do points 1 and 2 from the instruction above.
2. Edit "<project>/app/build.gradle" to comment out or remove sections containing ndk-build
2. Edit "YOURPROJECT/app/build.gradle" to comment out or remove sections containing ndk-build
and uncomment the cmake sections. Add arguments to the CMake invocation as needed.
and uncomment the cmake sections. Add arguments to the CMake invocation as needed.
3. Edit "<project>/app/jni/CMakeLists.txt" to include your project (it defaults to
3. Edit "YOURPROJECT/app/jni/CMakeLists.txt" to include your project (it defaults to
adding the "src" subdirectory). Note that you'll have SDL2, SDL2main and SDL2-static
adding the "src" subdirectory). Note that you'll have SDL2, SDL2main and SDL2-static
as targets in your project, so you should have "target_link_libraries(yourgame SDL2 SDL2main)"
as targets in your project, so you should have "target_link_libraries(yourgame SDL2 SDL2main)"
in your CMakeLists.txt file. Also be aware that you should use add_library() instead of
in your CMakeLists.txt file. Also be aware that you should use add_library() instead of
@ -132,15 +140,15 @@ Here's an example of a minimal class file:
--- MyGame.java --------------------------
--- MyGame.java --------------------------
package com.gamemaker.game;
package com.gamemaker.game;
import org.libsdl.app.SDLActivity;
import org.libsdl.app.SDLActivity;
/**
/**
* A sample wrapper class that just calls SDLActivity
*/
* A sample wrapper class that just calls SDLActivity
*/
public class MyGame extends SDLActivity { }
public class MyGame extends SDLActivity { }
------------------------------------------
------------------------------------------
Then replace "SDLActivity" in AndroidManifest.xml with the name of your
Then replace "SDLActivity" in AndroidManifest.xml with the name of your
@ -179,7 +187,7 @@ may want to keep this fact in mind when building your APK, specially when large
files are involved.
files are involved.
For more information on which extensions get compressed by default and how to
For more information on which extensions get compressed by default and how to
@ -24,11 +24,11 @@ The Windows GDK port supports the full set of Win32 APIs, renderers, controllers
* GDK-specific setup:
* GDK-specific setup:
* Initializing/uninitializing the game runtime, and initializing Xbox Live services
* Initializing/uninitializing the game runtime, and initializing Xbox Live services
* Creating a global task queue and setting it as the default for the process. When running any async operations, passing in `NULL` as the task queue will make the task get added to the global task queue.
* Creating a global task queue and setting it as the default for the process. When running any async operations, passing in `NULL` as the task queue will make the task get added to the global task queue.
* An implementation on `WinMain` that performs the above GDK setup (you should link against SDL2main.lib, as in Windows x64). If you are unable to do this, you can instead manually call `SDL_GDKRunApp` from your entry point, passing in your `SDL_main` function and `NULL` as the parameters.
* An implementation on `WinMain` that performs the above GDK setup (you should link against SDL2main.lib, as in Windows x64). If you are unable to do this, you can instead manually call `SDL_GDKRunApp` from your entry point, passing in your `SDL_main` function and `NULL` as the parameters.
* Global task queue callbacks are dispatched during `SDL_PumpEvents` (which is also called internally if using `SDL_PollEvent`).
* Global task queue callbacks are dispatched during `SDL_PumpEvents` (which is also called internally if using `SDL_PollEvent`).
* You can get the handle of the global task queue through `SDL_GDKGetTaskQueue`, if needed. When done with the queue, be sure to use `XTaskQueueCloseHandle` to decrement the reference count (otherwise it will cause a resource leak).
* You can get the handle of the global task queue through `SDL_GDKGetTaskQueue`, if needed. When done with the queue, be sure to use `XTaskQueueCloseHandle` to decrement the reference count (otherwise it will cause a resource leak).
* What doesn't work:
* What doesn't work:
* Compilation with anything other than through the included Visual C++ solution file
* Compilation with anything other than through the included Visual C++ solution file
@ -58,7 +58,7 @@ In your game's existing Visual Studio Solution, go to Build > Configuration Mana
Open `VisualC-GDK/SDL.sln` in Visual Studio, you need to build the SDL2 and SDL2main targets for the Gaming.Desktop.x64 platform (Release is recommended). You will need to copy/keep track of the `SDL2.dll`, `XCurl.dll` (which is output by Gaming.Desktop.x64), `SDL2.lib`, and `SDL2main.lib` output files for your game project.
Open `VisualC-GDK/SDL.sln` in Visual Studio, you need to build the SDL2 and SDL2main targets for the Gaming.Desktop.x64 platform (Release is recommended). You will need to copy/keep track of the `SDL2.dll`, `XCurl.dll` (which is output by Gaming.Desktop.x64), `SDL2.lib`, and `SDL2main.lib` output files for your game project.
*Alternatively*, you could setup your solution file to instead reference the SDL2/SDL2main project file targets from the SDL source, and add those projects as a dependency. This would mean that SDL2 and SDL2main would both be built when your game is built.
*Alternatively*, you could setup your solution file to instead reference the SDL2/SDL2main project file targets from the SDL source, and add those projects as a dependency. This would mean that SDL2 and SDL2main would both be built when your game is built.
SDL provides an implementation of the $1 gesture recognition system. This allows for recording, saving, loading, and performing single stroke gestures.
SDL provides an implementation of the $1 gesture recognition system. This allows for recording, saving, loading, and performing single stroke gestures.
Gestures can be performed with any number of fingers (the centroid of the fingers must follow the path of the gesture), but the number of fingers must be constant (a finger cannot go down in the middle of a gesture). The path of a gesture is considered the path from the time when the final finger went down, to the first time any finger comes up.
Gestures can be performed with any number of fingers (the centroid of the fingers must follow the path of the gesture), but the number of fingers must be constant (a finger cannot go down in the middle of a gesture). The path of a gesture is considered the path from the time when the final finger went down, to the first time any finger comes up.
Dollar gestures are assigned an Id based on a hash function. This is guaranteed to remain constant for a given gesture. There is a (small) chance that two different gestures will be assigned the same ID. In this case, simply re-recording one of the gestures should result in a different ID.
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.
@ -42,7 +42,7 @@ Both functions return the number of gestures successfully saved.
Loading:
Loading:
--------
--------
To load templates from a file, call SDL_LoadDollarTemplates(touchId,src) where touchId is the id of the touch to load to (or -1 to load to all touch devices), and src is an SDL_RWops pointer to a gesture save file.
To load templates from a file, call SDL_LoadDollarTemplates(touchId,src) where touchId is the id of the touch to load to (or -1 to load to all touch devices), and src is an SDL_RWops pointer to a gesture save file.
SDL_LoadDollarTemplates returns the number of templates successfully loaded.
SDL_LoadDollarTemplates returns the number of templates successfully loaded.
@ -51,7 +51,7 @@ SDL_LoadDollarTemplates returns the number of templates successfully loaded.
@ -185,7 +185,7 @@ Once your application is installed its directory tree looks like:
Preferences/
Preferences/
tmp/
tmp/
When your SDL based iPhone application starts up, it sets the working directory to the main bundle (MySDLApp Home/MySDLApp.app), where your application resources are stored. You cannot write to this directory. Instead, I advise you to write document files to "../Documents/" and preferences to "../Library/Preferences".
When your SDL based iPhone application starts up, it sets the working directory to the main bundle (MySDLApp Home/MySDLApp.app), where your application resources are stored. You cannot write to this directory. Instead, I advise you to write document files to "../Documents/" and preferences to "../Library/Preferences".
More information on this subject is available here:
More information on this subject is available here:
The SDL.xcodeproj file now includes a target to build SDL2.xcframework. An xcframework is a new (Xcode 11) uber-framework which can handle any combination of processor type and target OS platform.
The SDL.xcodeproj file now includes a target to build SDL2.xcframework. An xcframework is a new (Xcode 11) uber-framework which can handle any combination of processor type and target OS platform.
In the past, iOS devices were always an ARM variant processor, and the simulator was always i386 or x86_64, and thus libraries could be combined into a single framework for both simulator and device. With the introduction of the Apple Silicon ARM-based machines, regular frameworks would collide as CPU type was no longer sufficient to differentiate the platform. So Apple created the new xcframework library package.
In the past, iOS devices were always an ARM variant processor, and the simulator was always i386 or x86_64, and thus libraries could be combined into a single framework for both simulator and device. With the introduction of the Apple Silicon ARM-based machines, regular frameworks would collide as CPU type was no longer sufficient to differentiate the platform. So Apple created the new xcframework library package.
@ -216,7 +216,7 @@ main(int argc, char *argv[])
}
}
#endif /* !SDL_MAIN_HANDLED */
#endif /* !SDL_MAIN_HANDLED */
Using an xcFramework is similar to using a regular framework. However, issues have been seen with the build system not seeing the headers in the xcFramework. To remedy this, add the path to the xcFramework in your app's target ==> Build Settings ==> Framework Search Paths and mark it recursive (this is critical). Also critical is to remove "*.framework" from Build Settings ==> Sub-Directories to Exclude in Recursive Searches. Clean the build folder, and on your next build the build system should be able to see any of these in your code, as expected:
Using an xcFramework is similar to using a regular framework. However, issues have been seen with the build system not seeing the headers in the xcFramework. To remedy this, add the path to the xcFramework in your app's target ==> Build Settings ==> Framework Search Paths and mark it recursive (this is critical). Also critical is to remove "*.framework" from Build Settings ==> Sub-Directories to Exclude in Recursive Searches. Clean the build folder, and on your next build the build system should be able to see any of these in your code, as expected:
#include "SDL_main.h"
#include "SDL_main.h"
#include<SDL.h>
#include<SDL.h>
@ -252,7 +252,7 @@ to your Info.plist:
<string>MyApp would like to remain connected to nearby bluetooth Game Controllers and Game Pads even when you're not using the app.</string>
<string>MyApp would like to remain connected to nearby bluetooth Game Controllers and Game Pads even when you're not using the app.</string>
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:
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:
@ -268,15 +268,15 @@ e.g.
{
{
... do event handling, frame logic and rendering ...
... do event handling, frame logic and rendering ...
}
}
int main(int argc, char *argv[])
int main(int argc, char *argv[])
{
{
... initialize game ...
... initialize game ...
#if __IPHONEOS__
#if __IPHONEOS__
// Initialize the Game Center for scoring and matchmaking
// Initialize the Game Center for scoring and matchmaking
InitGameCenter();
InitGameCenter();
// Set up the game to run in the window animation callback on iOS
// Set up the game to run in the window animation callback on iOS
// so that Game Center and so forth works correctly.
// so that Game Center and so forth works correctly.
- SDL2main should be used to ensure ROMFS is enabled.
- SDL2main should be used to ensure ROMFS is enabled.
- By default, the extra L2 cache and higher clock speeds of the New 2/3DS lineup are enabled. If you wish to turn it off, use `osSetSpeedupEnable(false)` in your main function.
- By default, the extra L2 cache and higher clock speeds of the New 2/3DS lineup are enabled. If you wish to turn it off, use `osSetSpeedupEnable(false)` in your main function.
- `SDL_GetBasePath` returns the romfs root instead of the executable's directory.
- `SDL_GetBasePath` returns the romfs root instead of the executable's directory.
- The Nintendo 3DS uses a cooperative threading model on a single core, meaning a thread will never yield unless done manually through the `SDL_Delay` functions, or blocking waits (`SDL_LockMutex`, `SDL_SemWait`, `SDL_CondWait`, `SDL_WaitThread`). To avoid starving other threads, `SDL_SemTryWait` and `SDL_SemWaitTimeout` will yield if they fail to acquire the semaphore, see https://github.com/libsdl-org/SDL/pull/6776 for more information.
@ -17,10 +17,10 @@ _Editor's note: I've been able to successfully build SDL using Visual Studio 201
2. Your IDE will likely prompt you to upgrade this solution file to whatever later version of the IDE you're using. In the `Retarget Projects` dialog,
2. Your IDE will likely prompt you to upgrade this solution file to whatever later version of the IDE you're using. In the `Retarget Projects` dialog,
all of the affected project files should be checked allowing you to use the latest `Windows SDK Version` you have installed, along with
all of the affected project files should be checked allowing you to use the latest `Windows SDK Version` you have installed, along with
the `Platform Toolset`.
the `Platform Toolset`.
If you choose *NOT* to upgrade to use the latest `Windows SDK Version` or `Platform Toolset`, then you'll need the `Visual Studio 2010 Platform Toolset`.
If you choose *NOT* to upgrade to use the latest `Windows SDK Version` or `Platform Toolset`, then you'll need the `Visual Studio 2010 Platform Toolset`.
3. Build the `.dll` and `.lib` files by right clicking on each project in turn (Projects are listed in the _Workspace_
3. Build the `.dll` and `.lib` files by right clicking on each project in turn (Projects are listed in the _Workspace_
panel in the _FileView_ tab), and selecting `Build`.
panel in the _FileView_ tab), and selecting `Build`.
You may get a few warnings, but you should not get any errors.
You may get a few warnings, but you should not get any errors.
@ -90,17 +90,17 @@ Here's a sample SDL snippet to verify everything is setup in your IDE:
@ -20,13 +20,13 @@ To build for the PSVita, make sure you have vitasdk and cmake installed and run:
Notes
Notes
-----
-----
* gles1/gles2 support and renderers are disabled by default and can be enabled by configuring with `-DVIDEO_VITA_PVR=ON`
* gles1/gles2 support and renderers are disabled by default and can be enabled by configuring with `-DVIDEO_VITA_PVR=ON`
These renderers support 720p and 1080i resolutions. These can be specified with:
These renderers support 720p and 1080i resolutions. These can be specified with:
`SDL_setenv("VITA_RESOLUTION", "720", 1);` and `SDL_setenv("VITA_RESOLUTION", "1080", 1);`
`SDL_setenv("VITA_RESOLUTION", "720", 1);` and `SDL_setenv("VITA_RESOLUTION", "1080", 1);`
* Desktop GL 1.X and 2.X support and renderers are also disabled by default and also can be enabled with `-DVIDEO_VITA_PVR=ON` as long as gl4es4vita is present in your SDK.
* Desktop GL 1.X and 2.X support and renderers are also disabled by default and also can be enabled with `-DVIDEO_VITA_PVR=ON` as long as gl4es4vita is present in your SDK.
They support the same resolutions as the gles1/gles2 backends and require specifying `SDL_setenv("VITA_PVR_OGL", "1", 1);`
They support the same resolutions as the gles1/gles2 backends and require specifying `SDL_setenv("VITA_PVR_OGL", "1", 1);`
anytime before video subsystem initialization.
anytime before video subsystem initialization.
* gles2 support via PIB is disabled by default and can be enabled by configuring with `-DVIDEO_VITA_PIB=ON`
* gles2 support via PIB is disabled by default and can be enabled by configuring with `-DVIDEO_VITA_PIB=ON`
* By default SDL emits mouse events for touch events on every touchscreen.
* By default SDL emits mouse events for touch events on every touchscreen.
Vita has two touchscreens, so it's recommended to use `SDL_SetHint(SDL_HINT_TOUCH_MOUSE_EVENTS, "0");` and handle touch events instead.
Vita has two touchscreens, so it's recommended to use `SDL_SetHint(SDL_HINT_TOUCH_MOUSE_EVENTS, "0");` and handle touch events instead.
Individual touchscreens can be disabled with:
Individual touchscreens can be disabled with:
`SDL_setenv("VITA_DISABLE_TOUCH_FRONT", "1", 1);` and `SDL_setenv("VITA_DISABLE_TOUCH_BACK", "1", 1);`
`SDL_setenv("VITA_DISABLE_TOUCH_FRONT", "1", 1);` and `SDL_setenv("VITA_DISABLE_TOUCH_BACK", "1", 1);`
#elif ( defined(__APPLE__) && (defined(__arm64__) || defined(__aarch64__)) ) /* this might work on other ARM targets, but this is a known quantity... */
#elif ( defined(__APPLE__) && (defined(__arm64__) || defined(__aarch64__)) ) /* this might work on other ARM targets, but this is a known quantity... */
