"softwarecyancut"
this is disabled by default, since some vanilla maps were designed around this
also costs a bit of performance (splat span drawers are slooooow)
instead of homremoval, we draw the fucking skyplane before everything lmao
there probably is a right way to fix this, but im too dumb for that
needs some performance testing, but since i could move the semaphores back, its even better in some instances
This fixes slightly raised fofs drawing on top of sprites that should be in
front of them. Previously would check that the bottom of the object was above
the plane. Now also uses sprite offsets like the fof seg sorting does.
software slopes finally are sane........
fixes certain maps like stardust speedway looking like complete butt
need to test ogl, not sure if theres any real change there
Note: need to check if we gotta readd portalcullsector for ogl portals, technically this is alot faster and fixes the occasional portal disappearing, but may introduce occasional visual bugs
move screens array to "vid" struct
remove a bunch of unused stuff
this speeds up 4 player splitscreen ever so slighty
mostly just alot cleaner than the mess it was before
since we dont use the toggle in spectatormode
might be useful to return to the mapstart fast or smth
this is mostly just copy pasted from P_ResetCamera, which should be fine hopefully since we dont move our spectators anymore
it will instead always take the players mobj color, this makes it indirectly support things like acrobatics and the colourized banana snipe
also just makes it a value for cv_gamepadled instead of its own cvar
attempts to first fill the screen horizontally, if the screen is not filled vertically like that, it will then change the scaling to fill the screen vertically
like this effectively every votebg fills up the screen and accomidates most bgs that added padding for the weird vanilla behaviour
TODO: make the behaviour switchable
also some slight cleanup
currently this scales vertically to fill out the screen vertically
not sure if horizontally would be preferred, but thatd most likely cut off alot of parts from some votebgs
"driftonly" will tone the lines completely instead of alternating between blue and driftcharge
"normal" will completely colourize speedlines in the player colour
"addskins" is an incredibly ambigous name since its main purpose was to add skins LOCALLY
just prints a notice for now since there may be ppl that still use it
kill unused adjustfeet code
add missing clamping
use malloc since stuff gets filled with 0xFF00 anyways
kill rotated sprite "type" since its unused too
simplify getpatchpixel a little
this is kinda horrid, but essentially, the number at the start of replay names is actually the time when the replay was recorded, so i can extract that and convert it to a readable format
this probably can be done alot cleaner lmao
below 640x400 the highres portraits become an absolute mess so itll now fallback to the lowres portraits
the statdisplay name text also became completely unreadable so itll use V_DrawThinString instead on low resolutions
also simplifies R_GetLinedefTransTable
it now just returns a normal translucency table in case of an invalid blendmode, similar to what vanilla got
not sure if this is 100% correct X)
before we unconditionally sent PT_WILLRESENDGAMESTATE to every connected node that didnt desynch before, in a big lobby this could mean having to send out alot of reliable packets to potentially clients that couldnt use it anyways, like this we just check if a client is saturn, which gets set the moment a saturn client v7.1 and onwards joins (it sends a special packet to the server during connect)
this makes sure we only even attempt the new resynch system with clients WE KNOW can use it anyways
this is backwards compatible until v7.1, v7 when this was introduced did not send the special packet on join and relied on the willreceivegamestate packet, so they wont benefit from the better resynching anymore
its not used for software renderer anymore and before you had to restart the game to be able to see a change in gl
8bits and 24bits options have been removed since they had no effect
and it also allowed me to unglobal things
instead of copieng the target mobjs rotation we just use its standingslope instead, this means shadows properly rotate according to which slope theire on
should make them visually more cohesive if a player or other mobj is rotated midair
too many ppl accidentally press right shift and end up putting things they didnt intend into their autoload file
which sometimes caused alot of issues in online play
makes things slightly cleaner and we can apply sloperoll dist to everything
should probably save some time esp with the trailing item z calc
+ P_MobjPitchAndRoll should be able to be called always since it also does stuff seperate from sloperoll
this cvar is meant to be only the toggle for the player slope rotation, however, spriterotation should still be usable in any case with this disabled. the global toggle "cv_spriteroll" has been removed
this cvar is meant to be only the toggle for the player slope rotation, however, spriterotation should still be usable in any case with this disabled. the global toggle "cv_spriteroll" has been removed
i kinda forgot to remove those when i did some refactoring ealier
- Sloperotation was weird, it now uses what we calculate in K_RollMobjsBySlopes
- in general uses srb2s newer system
- alot of cleanup of pointless variables
- sprinfo pivots should now work
- removed roillmodel since it was smth weird and broke rollangle
- puts all music stuff into a struct "music_t"
- should hopefully fix numerous issues with keepmusic and skipintromusic
- keepmusic can now "recover" from a few cases, like restarting the map from intermission
Regular blua does something similar to that, and it changes how large
numeric literals are parsed. It's very rare for those to be used but can
still in theory cause synch issues between blua and bluajit clients
for now since it doesent work that well on bright maps, yes there is a mapheader , but cant expect anyone to go trough all maps and add it
This reverts commit 323fbb4713.
if someone doesent provide a widescreen patch it now falls back to the replaced non widescreen one and vice versa instead of just falling back to what vanilla provides
how it was before, the game just fallback to the vanila widescreen patch if there was no animated widescreen bg provided, just fall back to the non widescreen anim patch instead if it exists
- Sloperotation was weird, it now uses what we calculate in K_RollMobjsBySlopes
- in general uses srb2s newer system
- alot of cleanup of pointless variables
- sprinfo pivots should now work
- removed roillmodel since it was smth weird and broke rollangle
if someone doesent provide a widescreen patch it now falls back to the replaced non widescreen one and vice versa instead of just falling back to what vanilla provides
how it was before, the game just fallback to the vanila widescreen patch if there was no animated widescreen bg provided, just fall back to the non widescreen anim patch instead if it exists
when serverplayer has mindelay active
this was supposed to show mindelay for serverplayers but that doesent work :chaosleep: so just do not mess with it
- now theres realoffsets aswell
- allows better control of changing things per lua and still do funky stuff in hardcode without conflicts
- spritescales and offsets now get reset centralised before any thinkers run
- now theres realoffsets aswell
- allows better control of changing things per lua and still do funky stuff in hardcode without conflicts
- spritescales and offsets now get reset centralised before any thinkers run
so you can record attack and it will also keep saving to statistics
also added a few things it now keeps track of
TODO: unfuck the statistics page and add a 2nd one perhaps? due to space reasons
menucode is hell
if there is no patch for it
its kinda dumb, since technically would allow to not load all of em
but im lazy and dont wanna change possiblevalues around
- gamepads now aim like they used to and at same speed as keyboard
- aim reset has been changed so it resets automatically, but also can be manually reset with centerview
- aiming is locked during cam reset
- now not changable over console anymore, bind only!
- it doesent save anymore so its always disabled at game start
- moving while in spec state will disable director when active so stand still
- disable it in splitscreen completely
- only adjust view when toggling it on
keeps intended behaviour since we now dont need to worry about player controls anymore
but keeps the rebindable buttons incase someone wants to do a crazy control setup for some reason
- also dont let water and heat be applied on top of each other since it does not look good (water postimg takes priority over heat)
- also save a little time in opengl splitscreen since it does not support heat or wöter effects
ok so, for whatever dumb reason, spectatormovement will desynch at random, even on localhost.
with this we just literally fucking ignore almost every button input locally and just wont move our spectator player at all.
but since we are indeed still runiing specatotr movement code, and this is localcmd shit, the server just thinks we dont want to move and thus is "synchsave".
sadly this does not fix desynchs from vanilla players
the only code we keep is for button inputs that do certain actions like "item" so we can still join from spec with it and other crap
cause kart weird, and we cant remove the spec movement due to synch reasons
and letting the cam move instantly instead of waiting, may put you in a weird cam position
- global function that updates variables with current display resolution
-smol boolean function that quickly checks if the game res matches the desktop res
- i_downsample has been simplyfied a bit
apparently, if the client doesent receive an ack back which may happen due to duplicate packets/bad net conditions, it may spam resend the packet until its netxcmd buffer is full and locks up
not quite sure why it made stuff die so much but uhhh
instead i just check in the cube initialistion function instead and only let it build when needed to not change how the game looks with raised gamma values
not quite sure why it made stuff die so much but uhhh
instead i just check in the cube initialistion function instead and only let it build when needed to not change how the game looks with raised gamma values
- Use Z_Malloc to allocate demobuffer
- Use Z_Free to free demobuffer
- Make functions for freeing and resseting demobuffer
- Always reset demobuffer when not saving
- Completely refactor player camera handling
- Refactor ALOT of gamepad code
- Refactor local cmds
- Refactor automap and add minimap generator ("minigen" command)
- Remove a bunch of unused netcode
- Remove ALOT of unused gametype code
- Remove alot of unused bot code
- Optimize some sectorspecial code slightly
- Remove a bunch of nights mode related stuff that was unused
- Bunch of smaller optimizations and code improvements
this actually works and makes em animate
apparently somehow on netjoin some hprev entries get mangled but are not null?
no clue why that happens since hoops arent even netsynched only their "spawnpoint" is
completely forgor in kart and srb2.1 cmd.angleturn needs to be bitshifted to accomidate localangle
using it again is better, since player mobj angle is not always suitable for localangle and may slightly mismatch where a player is steering
- make software and ogl use same variable names
- let papersprites also roll in ogl not just software
- throw pitchnroll calc into a function to reduce code dupe
- save some calcs when having sliptide roll disabled
- fix software not calculating camang when just player roll is enabled (did that ever work right before? oops)
- determine early if the sprite is supposed to rotate, and only if it really does, run the rotation stuff
its now its own function HWR_ApplyDispoffset
papersprites are now also unaffected by it, which caused some minor visual issues before (ex zfighting signposts)
also just check for papersprite once and put it into a bool so we dont have to recheck sprite frames and flags 10 times
tbh i dont think anyone even knows about this, never heard any complains, never had any issues, neither visually or performancewise.
its just clutter at this point
its only used for 2 rendering functions, so being potentially inaccurate is not that dangerous and the speedup in some instances might be worth the tradeoff
- Increase MINZ from 4 fracunits to 16
- R_StoreWallRange: do not render textures with holes
- fix off-by-one error in R_ProjectSprite
- Avoid rendering unused left/right edges of screen while rolling
- Clamp patch column post drawing bounds
- Vissprites: set dc.texheight
- Add null check for column in R_DrawMaskedColumn
we dont need to return everywhere but instead stuff can be mostly just set to 0
this also somewhat ensures stuff works after toggling without having to restart the game or map
keep sending PT_WILLRESENDGAMESTATE packets to everyone for now
saturnpak will still mark the right clients so they will use the right consistency check without having to desynch first
before the server always assumed every client cant receive the gamestate using the vanilla consistency check for everyone.
aswell as before the first resynch it tried to send the gamestate resend packets to everyone
- basic keepmusic implementation (currently checks for if the song changes instead of the map, idk if i keep this, since this allows certain maps to change the music on start, ex abstract avenue or wandering balls)
- Toggle to ignore any kind of music change during the level (includes intermission music, depends on how custom intermission music works)
-toggle to start map music instantly on levelload and skip the intro fanfare (also skips any linedef executed sound so some map intros dont interfere with this)
you can still toggle it in replays no issues
but you mostly want to watch yourself or a certain person during replays, so having to manually toggle it off always is weird
- dont reset cameras during gamestate resynch
- dont reinit director during gamesate resynch
- dont reset view interpolators aswell
- dont reset localaiming aswell
should make resynching less jarring visually hopefully
might reapply them some other time, but since we need to maintain vanilla compat as much as possible gonna revert crap
kinda sick of desynching stuffs and honestly most the mobj stuff rarely ever crashes
This reverts commit 94ddd01427.
may be readded in v7.1
since this is pretty sensitive code and i dont want to desynch or crap so this def needs more testing
-Add new Saturn Hud options menu to declutter normal saturn options
- If in any of the hud options the game will force display the kart hud and disable the fade background
- i hate m_menu
music_resync_powerups_only literally didnt do shit lol
removed some other unused crap
changed some conditions to better check for stuff
etc idk
i just rather remove this whole thing at this point but oh well
makes this whole ordeal alot less hacky tbh
player color always gets updated if it changes
still allows for directly setting led color elsewhere by using G_SetPlayerGamepadIndicatorColor directly
hoping crap doesent cost any perf but honestly shouldnt
itll now run at a similar place to postautoload
this may hopefully prevent some issuess with freeslotting lua
however sadly this makes menu replacements not work at startup anymore
removes old lerp variables that did nothing
properly interpolated viewroll
made it proper adjust to mobjscale
doesent roll view when spectating
general cleanup
so you can specify how often the game tries to resend gamestate to player in given time
so they dont get stuck in a synch loop
this is gamestateresendattempts value in the time of resynchcooldown *2
toggling director now resets cooldown so it switches players immediately
also consolidated condition to be active
and ensure DirectorFollowAttack doesent always run when it doesent need to be
-Fix a division by zero in BCZ2 Metal Sonic's routine
-Fix a bug where adding the same mod multiple times counted towards the mod limit
and other thigns
or if you dont use any colour correction stuff
basically checks if anything has changed and if the gamma is below 0
otherwise it will apply colour cubus
* Zero is now a valid tag for v.interpolate
* Reset lerp coordinates when v.interpString is called again
* Leaving string mode enabled on exit no longer breaks other scripts
* Fix fadeScreen having an uninitialized ID
$@"This should be run from a Makefile or from the directory of the build. If it is not, then change to that directory or specify that directory as an argument."
$@"If ROOT_DIR isn't SRB2's repository root, specify that as an argument too."
$@"Make must have built the program before you run this script."
$@""
$@"Make sure these Environment Variables are correct."
$@"If not, then enter: export PROGRAM_VARIABLE=value"
- [Following the style guide](#following-the-style-guide)
- [Running the tests](#running-the-tests)
- [Opening a pull request](#opening-a-pull-request)
- [Contributing to the documentation](#contributing-to-the-documentation)
- [Editing a function documentation](#editing-a-function-documentation)
- [Editing the wiki](#editing-the-wiki)
## Filing a GitHub issue
### Reporting a bug
If you think you have found a bug and would like to report it, here are the steps you should take:
- Before opening a new issue, ensure your bug has not already been reported on the [GitHub Issues page](https://github.com/libsdl-org/SDL/issues).
- On the issue tracker, click on [New Issue](https://github.com/libsdl-org/SDL/issues/new).
- Include details about your environment, such as your Operating System and SDL version.
- If possible, provide a small example that reproduces your bug.
### Suggesting enhancements
If you want to suggest changes for the project, here are the steps you should take:
- Check if the suggestion has already been made on:
- the [issue tracker](https://github.com/libsdl-org/SDL/issues);
- the [discourse forum](https://discourse.libsdl.org/);
- or if a [pull request](https://github.com/libsdl-org/SDL/pulls) already exists.
- On the issue tracker, click on [New Issue](https://github.com/libsdl-org/SDL/issues/new).
- Describe what change you would like to happen.
## Contributing code
This section will cover how the process of forking the project, making a change and opening a pull request.
### Forking the project
The first step consists in making a fork of the project, this is only necessary for the first contribution.
Head over to https://github.com/libsdl-org/SDL and click on the `Fork` button in the top right corner of your screen, you may leave the fields unchanged and click `Create Fork`.
You will be redirected to your fork of the repository, click the green `Code` button and copy the git clone link.
If you had already forked the repository, you may update it from the web page using the `Fetch upstream` button.
### Following the style guide
Code formatting is done using a custom `.clang-format` file, you can learn more about how to run it [here](https://clang.llvm.org/docs/ClangFormat.html).
Some legacy code may not be formatted, as such avoid formatting the whole file at once and only format around your changes.
For your commit message to be properly displayed on GitHub, it should contain:
- A short description of the commit of 50 characters or less on the first line.
- If necessary, add a blank line followed by a long description, each line should be 72 characters or less.
For example:
```
Fix crash in SDL_FooBar.
This addresses the issue #123456 by making sure Foo was successful
before calling Bar.
```
### Running the tests
Tests allow you to verify if your changes did not break any behaviour, here are the steps to follow:
- Before pushing, run the `testautomation` suite on your machine, there should be no more failing tests after your change than before.
- After pushing to your fork, Continuous Integration (GitHub Actions) will ensure compilation and tests still pass on other systems.
### Opening a pull request
- Head over to your fork's GitHub page.
- Click on the `Contribute` button and `Open Pull Request`.
- Fill out the pull request template.
- If any changes are requested, you can add new commits to your fork and they will be automatically added to the pull request.
## Contributing to the documentation
### Editing a function documentation
The wiki documentation for API functions is synchronised from the headers' doxygen comments. As such, all modifications to syntax; function parameters; return value; version; related functions should be done in the header directly.
### Editing the wiki
Other changes to the wiki should done directly from https://wiki.libsdl.org/
# Contributing to SDL
We appreciate your interest in contributing to SDL, this document will describe how to report bugs, contribute code or ideas or edit documentation.
- [Following the style guide](#following-the-style-guide)
- [Running the tests](#running-the-tests)
- [Opening a pull request](#opening-a-pull-request)
- [Contributing to the documentation](#contributing-to-the-documentation)
- [Editing a function documentation](#editing-a-function-documentation)
- [Editing the wiki](#editing-the-wiki)
## Filing a GitHub issue
### Reporting a bug
If you think you have found a bug and would like to report it, here are the steps you should take:
- Before opening a new issue, ensure your bug has not already been reported on the [GitHub Issues page](https://github.com/libsdl-org/SDL/issues).
- On the issue tracker, click on [New Issue](https://github.com/libsdl-org/SDL/issues/new).
- Include details about your environment, such as your Operating System and SDL version.
- If possible, provide a small example that reproduces your bug.
### Suggesting enhancements
If you want to suggest changes for the project, here are the steps you should take:
- Check if the suggestion has already been made on:
- the [issue tracker](https://github.com/libsdl-org/SDL/issues);
- the [discourse forum](https://discourse.libsdl.org/);
- or if a [pull request](https://github.com/libsdl-org/SDL/pulls) already exists.
- On the issue tracker, click on [New Issue](https://github.com/libsdl-org/SDL/issues/new).
- Describe what change you would like to happen.
## Contributing code
This section will cover how the process of forking the project, making a change and opening a pull request.
### Forking the project
The first step consists in making a fork of the project, this is only necessary for the first contribution.
Head over to https://github.com/libsdl-org/SDL and click on the `Fork` button in the top right corner of your screen, you may leave the fields unchanged and click `Create Fork`.
You will be redirected to your fork of the repository, click the green `Code` button and copy the git clone link.
If you had already forked the repository, you may update it from the web page using the `Fetch upstream` button.
### Following the style guide
Code formatting is done using a custom `.clang-format` file, you can learn more about how to run it [here](https://clang.llvm.org/docs/ClangFormat.html).
Some legacy code may not be formatted, as such avoid formatting the whole file at once and only format around your changes.
For your commit message to be properly displayed on GitHub, it should contain:
- A short description of the commit of 50 characters or less on the first line.
- If necessary, add a blank line followed by a long description, each line should be 72 characters or less.
For example:
```
Fix crash in SDL_FooBar.
This addresses the issue #123456 by making sure Foo was successful
before calling Bar.
```
### Running the tests
Tests allow you to verify if your changes did not break any behaviour, here are the steps to follow:
- Before pushing, run the `testautomation` suite on your machine, there should be no more failing tests after your change than before.
- After pushing to your fork, Continuous Integration (GitHub Actions) will ensure compilation and tests still pass on other systems.
### Opening a pull request
- Head over to your fork's GitHub page.
- Click on the `Contribute` button and `Open Pull Request`.
- Fill out the pull request template.
- If any changes are requested, you can add new commits to your fork and they will be automatically added to the pull request.
## Contributing to the documentation
### Editing a function documentation
The wiki documentation for API functions is synchronised from the headers' doxygen comments. As such, all modifications to syntax; function parameters; return value; version; related functions should be done in the header directly.
### Editing the wiki
Other changes to the wiki should done directly from https://wiki.libsdl.org/
One limitation of this script is that all sources provided will be aggregated into
a single directory, thus all your source files should have a unique name.
Once the project is complete the script will tell you where the debug APK is located.
If you want to create a signed release APK, you can use the project created by this
utility to generate it.
Finally, a word of caution: re running androidbuild.sh wipes any changes you may have
done in the build directory for the app!
For more complex projects, follow these instructions:
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
If you already have a project that uses CMake, the instructions change somewhat:
1. Do points 1 and 2 from the instruction above.
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.
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
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
add_executable() for the target containing your "main" function.
If you wish to use Android Studio, you can skip the last step.
4. Run './gradlew installDebug' or './gradlew installRelease' in the project directory. It will build and install your .apk on any
connected Android device
Here's an explanation of the files in the Android project, so you can customize them:
android-project/app
build.gradle - build info including the application version and SDK
src/main/AndroidManifest.xml - package manifest. Among others, it contains the class name of the main Activity and the package name of the application.
jni/ - directory holding native code
jni/Application.mk - Application JNI settings, including target platform and STL library
jni/Android.mk - Android makefile that can call recursively the Android.mk files in all subdirectories
jni/CMakeLists.txt - Top-level CMake project that adds SDL as a subproject
jni/SDL/ - (symlink to) directory holding the SDL library files
jni/SDL/Android.mk - Android makefile for creating the SDL shared library
jni/src/ - directory holding your C/C++ source
jni/src/Android.mk - Android makefile that you should customize to include your source code and any library references
jni/src/CMakeLists.txt - CMake file that you may customize to include your source code and any library references
src/main/assets/ - directory holding asset files for your application
src/main/res/ - directory holding resources for your application
src/main/res/mipmap-* - directories holding icons for different phone hardware
src/main/res/values/strings.xml - strings used in your application, including the application name
src/main/java/org/libsdl/app/SDLActivity.java - the Java class handling the initialization and binding to SDL. Be very careful changing this, as the SDL library relies on this implementation. You should instead subclass this for your application.
One limitation of this script is that all sources provided will be aggregated into
a single directory, thus all your source files should have a unique name.
Once the project is complete the script will tell you where the debug APK is located.
If you want to create a signed release APK, you can use the project created by this
utility to generate it.
Finally, a word of caution: re running androidbuild.sh wipes any changes you may have
done in the build directory for the app!
For more complex projects, follow these instructions:
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
If you already have a project that uses CMake, the instructions change somewhat:
1. Do points 1 and 2 from the instruction above.
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.
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
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
add_executable() for the target containing your "main" function.
If you wish to use Android Studio, you can skip the last step.
4. Run './gradlew installDebug' or './gradlew installRelease' in the project directory. It will build and install your .apk on any
connected Android device
Here's an explanation of the files in the Android project, so you can customize them:
android-project/app
build.gradle - build info including the application version and SDK
src/main/AndroidManifest.xml - package manifest. Among others, it contains the class name of the main Activity and the package name of the application.
jni/ - directory holding native code
jni/Application.mk - Application JNI settings, including target platform and STL library
jni/Android.mk - Android makefile that can call recursively the Android.mk files in all subdirectories
jni/CMakeLists.txt - Top-level CMake project that adds SDL as a subproject
jni/SDL/ - (symlink to) directory holding the SDL library files
jni/SDL/Android.mk - Android makefile for creating the SDL shared library
jni/src/ - directory holding your C/C++ source
jni/src/Android.mk - Android makefile that you should customize to include your source code and any library references
jni/src/CMakeLists.txt - CMake file that you may customize to include your source code and any library references
src/main/assets/ - directory holding asset files for your application
src/main/res/ - directory holding resources for your application
src/main/res/mipmap-* - directories holding icons for different phone hardware
src/main/res/values/strings.xml - strings used in your application, including the application name
src/main/java/org/libsdl/app/SDLActivity.java - the Java class handling the initialization and binding to SDL. Be very careful changing this, as the SDL library relies on this implementation. You should instead subclass this for your application.
# Link to the actual SDL2 library. SDL2::SDL2 is the shared SDL library, SDL2::SDL2-static is the static SDL libarary.
target_link_libraries(mygamePRIVATESDL2::SDL2)
```
### A system SDL library
For CMake to find SDL, it must be installed in [a default location CMake is looking for](https://cmake.org/cmake/help/latest/command/find_package.html#config-mode-search-procedure).
The following components are available, to be used as an argument of `find_package`.
# Link to the actual SDL2 library. SDL2::SDL2 is the shared SDL library, SDL2::SDL2-static is the static SDL libarary.
target_link_libraries(mygamePRIVATESDL2::SDL2)
```
### A system SDL library
For CMake to find SDL, it must be installed in [a default location CMake is looking for](https://cmake.org/cmake/help/latest/command/find_package.html#config-mode-search-procedure).
The following components are available, to be used as an argument of `find_package`.
This port allows SDL applications to run via Microsoft's Game Development Kit (GDK).
Windows (GDK) and Xbox One/Xbox Series (GDKX) are both supported and all the required code is included in this public SDL release. However, only licensed Xbox developers have access to the GDKX libraries which will allow you to build the Xbox targets.
Requirements
------------
* Microsoft Visual Studio 2022 (in theory, it should also work in 2017 or 2019, but this has not been tested)
* Microsoft GDK June 2022 or newer (public release [here](https://github.com/microsoft/GDK/releases/tag/June_2022))
*For Xbox, you will need the corresponding GDKX version (licensed developers only)
* To publish a package or successfully authenticate a user, you will need to create an app id/configure services in Partner Center. However, for local testing purposes (without authenticating on Xbox Live), the identifiers used by the GDK test programs in the included solution will work.
Windows GDK Status
------
The Windows GDK port supports the full set of Win32 APIs, renderers, controllers, input devices, etc., as the normal Windows x64 build of SDL.
*Additionally, the GDK port adds the following:
*Compile-time platform detection for SDL programs. The `__GDK__` is `#define`d on every GDK platform, and the `__WINGDK__` is `#define`d on Windows GDK, specifically. (This distinction exists because other GDK platforms support a smaller subset of functionality. This allows you to mark code for "any" GDK separate from Windows GDK.)
*GDK-specific setup:
*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.
*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`).
* 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).
*Single-player games have some additional features available:
* Call `SDL_GDKGetDefaultUser` to get the default XUserHandle pointer.
*`SDL_GetPrefPath` still works, but only for single-player titles.
These functions mostly wrap around async APIs, and thus should be treated as synchronous alternatives. Also note that the single-player functions return on any OS errors, so be sure to validate the return values!
*What doesn't work:
*Compilation with anything other than through the included Visual C++ solution file
## VisualC-GDK Solution
The included `VisualC-GDK/SDL.sln` solution includes the following targets for the Gaming.Desktop.x64 configuration:
* SDL2 (DLL) - This is the typical SDL2.dll, but for Gaming.Desktop.x64.
* SDL2main (lib) - This contains a drop-in implementation of `WinMain` that is used as the entry point for GDK programs.
* tests/testgamecontroller - Standard SDL test program demonstrating controller functionality.
* tests/testgdk - GDK-specific test program that demonstrates using the global task queue to login a user into Xbox Live.
*NOTE*: As of the June 2022 GDK, you cannot test user logins without a valid Title ID and MSAAppId. You will need to manually change the identifiers in the `MicrosoftGame.config` to your valid IDs from Partner Center if you wish to test this.
* tests/testsprite2 - Standard SDL test program demonstrating sprite drawing functionality.
If you set one of the test programs as a startup project, you can run it directly from Visual Studio.
Windows GDK Setup, Detailed Steps
---------------------
These steps assume you already have a game using SDL that runs on Windows x64 along with a corresponding Visual Studio solution file for the x64 version. If you don't have this, it's easiest to use one of the test program vcxproj files in the `VisualC-GDK` directory as a starting point, though you will still need to do most of the steps below.
### 1. Add a Gaming.Desktop.x64 Configuration ###
In your game's existing Visual Studio Solution, go to Build > Configuration Manager. From the "Active solution platform" drop-down select "New...". From the drop-down list, select Gaming.Desktop.x64 and copy the settings from the x64 configuration.
### 2. Build SDL2 and SDL2main for GDK ###
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.
### 3. Configuring Project Settings ###
While the Gaming.Desktop.x64 configuration sets most of the required settings, there are some additional items to configure for your game project under the Gaming.Desktop.x64 Configuration:
* Under C/C++ > General > Additional Include Directories, make sure the `SDL/include` path is referenced
* Under Linker > General > Additional Library Directories, make sure to reference the path where the newly-built SDL2.lib and SDL2main.lib are
* Under Linker > Input > Additional Dependencies, you need the following:
* Note that in general, the GDK libraries depend on the MSVC C/C++ runtime, so there is no way to remove this dependency from a GDK program that links against GDK.
### 4. Setting up SDL_main ###
Rather than using your own implementation of `WinMain`, it's recommended that you instead `#include "SDL_main.h"` and declare a standard main function. 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.
### 5. Required DLLs ###
The game will not launch in the debugger unless required DLLs are included in the directory that contains the game's .exe file. You need to make sure that the following files are copied into the directory:
You can either copy these in a post-build step, or you can add the dlls into the project and set its Configuration Properties > General > Item type to "Copy file," which will also copy them into the output directory.
### 6. Setting up MicrosoftGame.config ###
You can copy `VisualC-GDK/tests/testgdk/MicrosoftGame.config` and use that as a starting point in your project. Minimally, you will want to change the Executable Name attribute, the DefaultDisplayName, and the Description.
This file must be copied into the same directory as the game's .exe file. As with the DLLs, you can either use a post-build step or the "Copy file" item type.
For basic testing, you do not need to change anything else in `MicrosoftGame.config`. However, if you want to test any Xbox Live services (such as logging in users) _or_ publish a package, you will need to setup a Game app on Partner Center.
Then, you need to set the following values to the values from Partner Center:
* Identity tag - Name and Publisher attributes
* TitleId
* MSAAppId
### 7. Adding Required Logos
Several logo PNG files are required to be able to launch the game, even from the debugger. You can use the sample logos provided in `VisualC-GDK/logos`. As with the other files, they must be copied into the same directory as the game's .exe file.
### 8. Copying any Data Files ###
When debugging GDK games, there is no way to specify a working directory. Therefore, any required game data must also be copied into the output directory, likely in a post-build step.
### 9. Build and Run from Visual Studio ###
At this point, you should be able to build and run your game from the Visual Studio Debugger. If you get any linker errors, make sure you double-check that you referenced all the required libs.
If you are testing Xbox Live functionality, it's likely you will need to change to the Sandbox for your title. To do this:
1. Run "Desktop VS 2022 Gaming Command Prompt" from the Start Menu
2. Switch the sandbox name with:
`XblPCSandbox SANDBOX.#`
3. (To switch back to the retail sandbox):
`XblPCSandbox RETAIL`
### 10. Packaging and Installing Locally
You can use one of the test program's `PackageLayout.xml` as a starting point. Minimally, you will need to change the exe to the correct name and also reference any required game data. As with the other data files, it's easiest if you have this copy to the output directory, although it's not a requirement as you can specify relative paths to files.
To create the package:
1. Run "Desktop VS 2022 Gaming Command Prompt" from the Start Menu
2.`cd` to the directory containing the `PackageLayout.xml` with the correct paths (if you use the local path as in the sample package layout, this would be from your .exe output directory)
3.`mkdir Package` to create an output directory
4. To package the file into the `Package` directory, use:
6. Once the package is installed, you can run it from the start menu.
7. As with when running from Visual Studio, if you need to test any Xbox Live functionality you must switch to the correct sandbox.
Xbox GDKX Setup
---------------------
In general, the same process in the Windows GDK instructions work. There are just a few additional notes:
* For Xbox One consoles, use the Gaming.Xbox.XboxOne.x64 target
* For Xbox Series consoles, use the Gaming.Xbox.Scarlett.x64 target
* The Xbox One target sets the `__XBOXONE__` define and the Xbox Series target sets the `__XBOXSERIES__` define
* You don't need to link against the Xbox.Services Thunks lib nor include that dll in your package (it doesn't exist for Xbox)
* The shader blobs for Xbox are created in a pre-build step for the Xbox targets, rather than included in the source (due to NDA and version compatability reasons)
* For some reason, if you make changes that require SDL2.dll to build, and you are running through the debugger (instead of a package), you have to rebuild your .exe target for the debugger to recognize the dll has changed and needs to be transferred to the console again
* While there are successful releases of Xbox titles using this port, it is not as extensively tested as other targets
Troubleshooting
---------------
#### Xbox Live Login does not work
As of June 2022 GDK, you must have a valid Title Id and MSAAppId in order to test Xbox Live functionality such as user login. Make sure these are set correctly in the `MicrosoftGame.config`. This means that even testgdk will not let you login without setting these properties to valid values.
Furthermore, confirm that your PC is set to the correct sandbox.
#### "The current user has already installed an unpackaged version of this app. A packaged version cannot replace this." error when installing
Prior to June 2022 GDK, running from the Visual Studio debugger would still locally register the app (and it would appear on the start menu). To fix this, you have to uninstall it (it's simplest to right click on it from the start menu to uninstall it).
GDK
=====
This port allows SDL applications to run via Microsoft's Game Development Kit (GDK).
Windows (GDK) and Xbox One/Xbox Series (GDKX) are supported. Although most of the Xbox code is included in the public SDL source code, NDA access is required for a small number of source files. If you have access to GDKX, these required Xbox files are posted on the GDK forums [here](https://forums.xboxlive.com/questions/130003/).
Requirements
------------
* Microsoft Visual Studio 2022 (in theory, it should also work in 2017 or 2019, but this has not been tested)
* Microsoft GDK June 2022 or newer (public release [here](https://github.com/microsoft/GDK/releases/tag/June_2022))
*To publish a package or successfully authenticate a user, you will need to create an app id/configure services in Partner Center. However, for local testing purposes (without authenticating on Xbox Live), the identifiers used by the GDK test programs in the included solution will work.
Windows GDK Status
------
The Windows GDK port supports the full set of Win32 APIs, renderers, controllers, input devices, etc., as the normal Windows x64 build of SDL.
* Additionally, the GDK port adds the following:
*Compile-time platform detection for SDL programs. The `__GDK__` is `#define`d on every GDK platform, and the `__WINGDK__` is `#define`d on Windows GDK, specifically. (This distinction exists because other GDK platforms support a smaller subset of functionality. This allows you to mark code for "any" GDK separate from Windows GDK.)
*GDK-specific setup:
*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.
* 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`).
*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:
*Compilation with anything other than through the included Visual C++ solution file
## VisualC-GDK Solution
The included `VisualC-GDK/SDL.sln` solution includes the following targets for the Gaming.Desktop.x64 configuration:
*SDL2 (DLL) - This is the typical SDL2.dll, but for Gaming.Desktop.x64.
*SDL2main (lib) - This contains a drop-in implementation of `WinMain` that is used as the entry point for GDK programs.
* tests/testgamecontroller - Standard SDL test program demonstrating controller functionality.
* tests/testgdk - GDK-specific test program that demonstrates using the global task queue to login a user into Xbox Live.
*NOTE*: As of the June 2022 GDK, you cannot test user logins without a valid Title ID and MSAAppId. You will need to manually change the identifiers in the `MicrosoftGame.config` to your valid IDs from Partner Center if you wish to test this.
* tests/testsprite2 - Standard SDL test program demonstrating sprite drawing functionality.
If you set one of the test programs as a startup project, you can run it directly from Visual Studio.
Windows GDK Setup, Detailed Steps
---------------------
These steps assume you already have a game using SDL that runs on Windows x64 along with a corresponding Visual Studio solution file for the x64 version. If you don't have this, it's easiest to use one of the test program vcxproj files in the `VisualC-GDK` directory as a starting point, though you will still need to do most of the steps below.
### 1. Add a Gaming.Desktop.x64 Configuration ###
In your game's existing Visual Studio Solution, go to Build > Configuration Manager. From the "Active solution platform" drop-down select "New...". From the drop-down list, select Gaming.Desktop.x64 and copy the settings from the x64 configuration.
### 2. Build SDL2 and SDL2main for GDK ###
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.
### 3. Configuring Project Settings ###
While the Gaming.Desktop.x64 configuration sets most of the required settings, there are some additional items to configure for your game project under the Gaming.Desktop.x64 Configuration:
* Under C/C++ > General > Additional Include Directories, make sure the `SDL/include` path is referenced
* Under Linker > General > Additional Library Directories, make sure to reference the path where the newly-built SDL2.lib and SDL2main.lib are
* Under Linker > Input > Additional Dependencies, you need the following:
*Note that in general, the GDK libraries depend on the MSVC C/C++ runtime, so there is no way to remove this dependency from a GDK program that links against GDK.
### 4. Setting up SDL_main ###
Rather than using your own implementation of `WinMain`, it's recommended that you instead `#include "SDL_main.h"` and declare a standard main function. 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.
### 5. Required DLLs ###
The game will not launch in the debugger unless required DLLs are included in the directory that contains the game's .exe file. You need to make sure that the following files are copied into the directory:
You can either copy these in a post-build step, or you can add the dlls into the project and set its Configuration Properties > General > Item type to "Copy file," which will also copy them into the output directory.
### 6. Setting up MicrosoftGame.config ###
You can copy `VisualC-GDK/tests/testgdk/MicrosoftGame.config` and use that as a starting point in your project. Minimally, you will want to change the Executable Name attribute, the DefaultDisplayName, and the Description.
This file must be copied into the same directory as the game's .exe file. As with the DLLs, you can either use a post-build step or the "Copy file" item type.
For basic testing, you do not need to change anything else in `MicrosoftGame.config`. However, if you want to test any Xbox Live services (such as logging in users) _or_ publish a package, you will need to setup a Game app on Partner Center.
Then, you need to set the following values to the values from Partner Center:
* Identity tag - Name and Publisher attributes
* TitleId
* MSAAppId
### 7. Adding Required Logos
Several logo PNG files are required to be able to launch the game, even from the debugger. You can use the sample logos provided in `VisualC-GDK/logos`. As with the other files, they must be copied into the same directory as the game's .exe file.
### 8. Copying any Data Files ###
When debugging GDK games, there is no way to specify a working directory. Therefore, any required game data must also be copied into the output directory, likely in a post-build step.
### 9. Build and Run from Visual Studio ###
At this point, you should be able to build and run your game from the Visual Studio Debugger. If you get any linker errors, make sure you double-check that you referenced all the required libs.
If you are testing Xbox Live functionality, it's likely you will need to change to the Sandbox for your title. To do this:
1. Run "Desktop VS 2022 Gaming Command Prompt" from the Start Menu
2. Switch the sandbox name with:
`XblPCSandbox SANDBOX.#`
3. (To switch back to the retail sandbox):
`XblPCSandbox RETAIL`
### 10. Packaging and Installing Locally
You can use one of the test program's `PackageLayout.xml` as a starting point. Minimally, you will need to change the exe to the correct name and also reference any required game data. As with the other data files, it's easiest if you have this copy to the output directory, although it's not a requirement as you can specify relative paths to files.
To create the package:
1. Run "Desktop VS 2022 Gaming Command Prompt" from the Start Menu
2.`cd` to the directory containing the `PackageLayout.xml` with the correct paths (if you use the local path as in the sample package layout, this would be from your .exe output directory)
3.`mkdir Package` to create an output directory
4. To package the file into the `Package` directory, use:
6. Once the package is installed, you can run it from the start menu.
7. As with when running from Visual Studio, if you need to test any Xbox Live functionality you must switch to the correct sandbox.
Troubleshooting
---------------
#### Xbox Live Login does not work
As of June 2022 GDK, you must have a valid Title Id and MSAAppId in order to test Xbox Live functionality such as user login. Make sure these are set correctly in the `MicrosoftGame.config`. This means that even testgdk will not let you login without setting these properties to valid values.
Furthermore, confirm that your PC is set to the correct sandbox.
#### "The current user has already installed an unpackaged version of this app. A packaged version cannot replace this." error when installing
Prior to June 2022 GDK, running from the Visual Studio debugger would still locally register the app (and it would appear on the start menu). To fix this, you have to uninstall it (it's simplest to right click on it from the start menu to uninstall it).
SDL provides an implementation of the $1 gesture recognition system. This allows for recording, saving, loading, and performing single stroke gestures.
Gestures can be performed with any number of fingers (the centroid of the fingers must follow the path of the gesture), but the number of fingers must be constant (a finger cannot go down in the middle of a gesture). The path of a gesture is considered the path from the time when the final finger went down, to the first time any finger comes up.
Dollar gestures are assigned an Id based on a hash function. This is guaranteed to remain constant for a given gesture. There is a (small) chance that two different gestures will be assigned the same ID. In this case, simply re-recording one of the gestures should result in a different ID.
Recording:
----------
To begin recording on a touch device call:
SDL_RecordGesture(SDL_TouchID touchId), where touchId is the id of the touch device you wish to record on, or -1 to record on all connected devices.
Recording terminates as soon as a finger comes up. Recording is acknowledged by an SDL_DOLLARRECORD event.
A SDL_DOLLARRECORD event is a dgesture with the following fields:
* event.dgesture.touchId - the Id of the touch used to record the gesture.
* event.dgesture.gestureId - the unique id of the recorded gesture.
Performing:
-----------
As long as there is a dollar gesture assigned to a touch, every finger-up event will also cause an SDL_DOLLARGESTURE event with the following fields:
* event.dgesture.touchId - the Id of the touch which performed the gesture.
* event.dgesture.gestureId - the unique id of the closest gesture to the performed stroke.
* event.dgesture.error - the difference between the gesture template and the actual performed gesture. Lower error is a better match.
* event.dgesture.numFingers - the number of fingers used to draw the stroke.
Most programs will want to define an appropriate error threshold and check to be sure that the error of a gesture is not abnormally high (an indicator that no gesture was performed).
Saving:
-------
To save a template, call SDL_SaveDollarTemplate(gestureId, 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.
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.
Both functions return the number of gestures successfully saved.
Loading:
--------
To load templates from a file, call SDL_LoadDollarTemplates(touchId,src) where touchId is the id of the touch to load to (or -1 to load to all touch devices), and src is an SDL_RWops pointer to a gesture save file.
SDL_LoadDollarTemplates returns the number of templates successfully loaded.
SDL provides an implementation of the $1 gesture recognition system. This allows for recording, saving, loading, and performing single stroke gestures.
Gestures can be performed with any number of fingers (the centroid of the fingers must follow the path of the gesture), but the number of fingers must be constant (a finger cannot go down in the middle of a gesture). The path of a gesture is considered the path from the time when the final finger went down, to the first time any finger comes up.
Dollar gestures are assigned an Id based on a hash function. This is guaranteed to remain constant for a given gesture. There is a (small) chance that two different gestures will be assigned the same ID. In this case, simply re-recording one of the gestures should result in a different ID.
Recording:
----------
To begin recording on a touch device call:
SDL_RecordGesture(SDL_TouchID touchId), where touchId is the id of the touch device you wish to record on, or -1 to record on all connected devices.
Recording terminates as soon as a finger comes up. Recording is acknowledged by an SDL_DOLLARRECORD event.
A SDL_DOLLARRECORD event is a dgesture with the following fields:
* event.dgesture.touchId - the Id of the touch used to record the gesture.
* event.dgesture.gestureId - the unique id of the recorded gesture.
Performing:
-----------
As long as there is a dollar gesture assigned to a touch, every finger-up event will also cause an SDL_DOLLARGESTURE event with the following fields:
* event.dgesture.touchId - the Id of the touch which performed the gesture.
* event.dgesture.gestureId - the unique id of the closest gesture to the performed stroke.
* event.dgesture.error - the difference between the gesture template and the actual performed gesture. Lower error is a better match.
* event.dgesture.numFingers - the number of fingers used to draw the stroke.
Most programs will want to define an appropriate error threshold and check to be sure that the error of a gesture is not abnormally high (an indicator that no gesture was performed).
Saving:
-------
To save a template, call SDL_SaveDollarTemplate(gestureId, 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.
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.
Both functions return the number of gestures successfully saved.
Loading:
--------
To load templates from a file, call SDL_LoadDollarTemplates(touchId,src) where touchId is the id of the touch to load to (or -1 to load to all touch devices), and src is an SDL_RWops pointer to a gesture save file.
SDL_LoadDollarTemplates returns the number of templates successfully loaded.
1. Run Xcode and create a new project using the iOS Game template, selecting the Objective C language and Metal game technology.
2. In the main view, delete all files except for Assets and LaunchScreen
3. Right click the project in the main view, select "Add Files...", and add the SDL project, Xcode/SDL/SDL.xcodeproj
4. Select the project in the main view, go to the "Info" tab and under "Custom iOS Target Properties" remove the line "Main storyboard file base name"
5. Select the project in the main view, go to the "Build Settings" tab, select "All", and edit "Header Search Path" and drag over the SDL "Public Headers" folder from the left
6. Select the project in the main view, go to the "Build Phases" tab, select "Link Binary With Libraries", and add SDL2.framework from "Framework-iOS"
7. Select the project in the main view, go to the "General" tab, scroll down to "Frameworks, Libraries, and Embedded Content", and select "Embed & Sign" for the SDL library.
8. In the main view, expand SDL -> Library Source -> main -> uikit and drag SDL_uikit_main.c into your game files
9. Add the source files that you would normally have for an SDL program, making sure to have #include "SDL.h" at the top of the file containing your main() function.
10. Add any assets that your application needs.
11. Enjoy!
TODO: Add information regarding App Store requirements such as icons, etc.
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.
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.
Your SDL application for iOS uses OpenGL ES for video by default.
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().
If your application doesn't use OpenGL's depth buffer, you may find significant performance improvement by setting SDL_GL_DEPTH_SIZE to 0.
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.
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:
- The drawable Renderbuffer must be bound to the GL_RENDERBUFFER binding point when SDL_GL_SwapWindow() is called.
- The drawable Framebuffer Object must be bound while rendering to the screen and when SDL_GL_SwapWindow() is called.
- 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.
The above objects can be obtained via SDL_GetWindowWMInfo() (in SDL_syswm.h).
iOS now supports Bluetooth mice on iPad, but by default will provide the mouse input as touch. In order for SDL to see the real mouse events, you should set the key UIApplicationSupportsIndirectInputEvents to true in your Info.plist
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.
Once your application is installed its directory tree looks like:
MySDLApp Home/
MySDLApp.app
Documents/
Library/
Preferences/
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".
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.
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.
The xcframework target builds into a Products directory alongside the SDL.xcodeproj file, as SDL2.xcframework. This can be brought in to any iOS project and will function properly for both simulator and device, no matter their CPUs. Note that Intel Macs cannot cross-compile for Apple Silicon Macs. If you need AS compatibility, perform this build on an Apple Silicon Mac.
This target requires Xcode 11 or later. The target will simply fail to build if attempted on older Xcodes.
In addition, on Apple platforms, main() cannot be in a dynamically loaded library. This means that iOS apps which used the statically-linked libSDL2.lib and now link with the xcframwork will need to define their own main() to call SDL_UIKitRunApp(), like this:
#ifndef SDL_MAIN_HANDLED
#ifdef main
#undef main
#endif
int
main(int argc, char *argv[])
{
return SDL_UIKitRunApp(argc, argv, SDL_main);
}
#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:
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).
Textures:
The optimal texture formats on iOS are SDL_PIXELFORMAT_ABGR8888, SDL_PIXELFORMAT_ABGR8888, SDL_PIXELFORMAT_BGR888, and SDL_PIXELFORMAT_RGB24 pixel formats.
Loading Shared Objects:
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.
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:
int SDL_iPhoneSetAnimationCallback(SDL_Window * window, int interval, void (*callback)(void*), void *callbackParam);
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.
e.g.
extern "C"
void ShowFrame(void*)
{
... do event handling, frame logic and rendering ...
}
int main(int argc, char *argv[])
{
... initialize game ...
#ifdef__IPHONEOS__
// Initialize the Game Center for scoring and matchmaking
InitGameCenter();
// Set up the game to run in the window animation callback on iOS
// so that Game Center and so forth works correctly.
Open the package contents of the older Xcode and your newer version of Xcode and copy over the folders in Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/DeviceSupport
Then open the file Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/SDKSettings.plist and add the versions of iOS you want to deploy to the key Root/DefaultProperties/DEPLOYMENT_TARGET_SUGGESTED_VALUES
Open your project and set your deployment target to the desired version of iOS
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
iOS
======
Building the Simple DirectMedia Layer for iOS 9.0+
1. Run Xcode and create a new project using the iOS Game template, selecting the Objective C language and Metal game technology.
2. In the main view, delete all files except for Assets and LaunchScreen
3. Right click the project in the main view, select "Add Files...", and add the SDL project, Xcode/SDL/SDL.xcodeproj
4. Select the project in the main view, go to the "Info" tab and under "Custom iOS Target Properties" remove the line "Main storyboard file base name"
5. Select the project in the main view, go to the "Build Settings" tab, select "All", and edit "Header Search Path" and drag over the SDL "Public Headers" folder from the left
6. Select the project in the main view, go to the "Build Phases" tab, select "Link Binary With Libraries", and add SDL2.framework from "Framework-iOS"
7. Select the project in the main view, go to the "General" tab, scroll down to "Frameworks, Libraries, and Embedded Content", and select "Embed & Sign" for the SDL library.
8. In the main view, expand SDL -> Library Source -> main -> uikit and drag SDL_uikit_main.c into your game files
9. Add the source files that you would normally have for an SDL program, making sure to have #include "SDL.h" at the top of the file containing your main() function.
10. Add any assets that your application needs.
11. Enjoy!
TODO: Add information regarding App Store requirements such as icons, etc.
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.
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.
Your SDL application for iOS uses OpenGL ES for video by default.
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().
If your application doesn't use OpenGL's depth buffer, you may find significant performance improvement by setting SDL_GL_DEPTH_SIZE to 0.
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.
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:
- The drawable Renderbuffer must be bound to the GL_RENDERBUFFER binding point when SDL_GL_SwapWindow() is called.
- The drawable Framebuffer Object must be bound while rendering to the screen and when SDL_GL_SwapWindow() is called.
- 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.
The above objects can be obtained via SDL_GetWindowWMInfo() (in SDL_syswm.h).
iOS now supports Bluetooth mice on iPad, but by default will provide the mouse input as touch. In order for SDL to see the real mouse events, you should set the key UIApplicationSupportsIndirectInputEvents to true in your Info.plist
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.
Once your application is installed its directory tree looks like:
MySDLApp Home/
MySDLApp.app
Documents/
Library/
Preferences/
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".
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.
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.
The xcframework target builds into a Products directory alongside the SDL.xcodeproj file, as SDL2.xcframework. This can be brought in to any iOS project and will function properly for both simulator and device, no matter their CPUs. Note that Intel Macs cannot cross-compile for Apple Silicon Macs. If you need AS compatibility, perform this build on an Apple Silicon Mac.
This target requires Xcode 11 or later. The target will simply fail to build if attempted on older Xcodes.
In addition, on Apple platforms, main() cannot be in a dynamically loaded library. This means that iOS apps which used the statically-linked libSDL2.lib and now link with the xcframwork will need to define their own main() to call SDL_UIKitRunApp(), like this:
#ifndef SDL_MAIN_HANDLED
#ifdef main
#undef main
#endif
int
main(int argc, char *argv[])
{
return SDL_UIKitRunApp(argc, argv, SDL_main);
}
#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:
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).
Textures:
The optimal texture formats on iOS are SDL_PIXELFORMAT_ABGR8888, SDL_PIXELFORMAT_ABGR8888, SDL_PIXELFORMAT_BGR888, and SDL_PIXELFORMAT_RGB24 pixel formats.
Loading Shared Objects:
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.
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:
int SDL_iPhoneSetAnimationCallback(SDL_Window * window, int interval, void (*callback)(void*), void *callbackParam);
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.
e.g.
extern "C"
void ShowFrame(void*)
{
... do event handling, frame logic and rendering ...
}
int main(int argc, char *argv[])
{
... initialize game ...
#if__IPHONEOS__
// Initialize the Game Center for scoring and matchmaking
InitGameCenter();
// Set up the game to run in the window animation callback on iOS
// so that Game Center and so forth works correctly.
Open the package contents of the older Xcode and your newer version of Xcode and copy over the folders in Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/DeviceSupport
Then open the file Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/SDKSettings.plist and add the versions of iOS you want to deploy to the key Root/DefaultProperties/DEPLOYMENT_TARGET_SUGGESTED_VALUES
Open your project and set your deployment target to the desired version of iOS
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
KMSDRM is supported on FreeBSD and OpenBSD. DragonFlyBSD works but requires being a root user. NetBSD isn't supported yet because the application will crash when creating the KMSDRM screen.
WSCONS support has been brought back, but only as an input backend. It will not be brought back as a video backend to ease maintenance.
OpenBSD note: Note that the video backend assumes that the user has read/write permissions to the /dev/drm* devices.
The WSCONS input backend needs read/write access to the /dev/wskbd* devices, without which it will not work properly. /dev/wsmouse must also be read/write accessible, otherwise mouse input will not work.
The evdev devices are only accessible to the root user by default. Edit devfs rules to allow access to such devices. The /dev/kbd* devices are also only accessible to the root user by default. Edit devfs rules to allow access to such devices.
KMSDRM is supported on FreeBSD and OpenBSD. DragonFlyBSD works but requires being a root user. NetBSD isn't supported yet because the application will crash when creating the KMSDRM screen.
WSCONS support has been brought back, but only as an input backend. It will not be brought back as a video backend to ease maintenance.
OpenBSD note: Note that the video backend assumes that the user has read/write permissions to the /dev/drm* devices.
The WSCONS input backend needs read/write access to the /dev/wskbd* devices, without which it will not work properly. /dev/wsmouse must also be read/write accessible, otherwise mouse input will not work.
The evdev devices are only accessible to the root user by default. Edit devfs rules to allow access to such devices. The /dev/kbd* devices are also only accessible to the root user by default. Edit devfs rules to allow access to such devices.
- 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.
-`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.
# Nintendo 3DS
SDL port for the Nintendo 3DS [Homebrew toolchain](https://devkitpro.org/) contributed by:
- 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.
-`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.
The PS2 port has a special Hint for having a dynamic VSYNC. The Hint is `SDL_HINT_PS2_DYNAMIC_VSYNC`.
If you enabled the dynamic vsync having as well `SDL_RENDERER_PRESENTVSYNC` enabled, then if the app is not able to run at 60 FPS, automatically the `vsync` will be disabled having a better performance, instead of droping FPS to 30.
## Notes
If you trying to debug a SDL app through [ps2client](https://github.com/ps2dev/ps2client) you need to avoid the IOP reset, otherwise you will lose the conection with your computer.
So to avoid the reset of the IOP CPU, you need to call to the macro `SDL_PS2_SKIP_IOP_RESET();`.
It could be something similar as:
```c
.....
SDL_PS2_SKIP_IOP_RESET();
int main(int argc, char *argv[])
{
.....
```
For a release binary is recommendable to reset the IOP always.
Remember to do a clean compilation everytime you enable or disable the `SDL_PS2_SKIP_IOP_RESET` otherwise the change won't be reflected.
The PS2 port has a special Hint for having a dynamic VSYNC. The Hint is `SDL_HINT_PS2_DYNAMIC_VSYNC`.
If you enabled the dynamic vsync having as well `SDL_RENDERER_PRESENTVSYNC` enabled, then if the app is not able to run at 60 FPS, automatically the `vsync` will be disabled having a better performance, instead of droping FPS to 30.
## Notes
If you trying to debug a SDL app through [ps2client](https://github.com/ps2dev/ps2client) you need to avoid the IOP reset, otherwise you will lose the conection with your computer.
So to avoid the reset of the IOP CPU, you need to call to the macro `SDL_PS2_SKIP_IOP_RESET();`.
It could be something similar as:
```c
.....
SDL_PS2_SKIP_IOP_RESET();
int main(int argc, char *argv[])
{
.....
```
For a release binary is recommendable to reset the IOP always.
Remember to do a clean compilation everytime you enable or disable the `SDL_PS2_SKIP_IOP_RESET` otherwise the change won't be reflected.
The video driver currently provides full screen video support with keyboard and mouse input. Windowed mode is not yet supported, but is planned in the future. Only software rendering is supported.
The filesystem APIs return either Unix-style paths or RISC OS-style paths based on the value of the `__riscosify_control` symbol, as is standard for UnixLib functions.
The audio, loadso, thread and timer APIs are currently provided by UnixLib.
GCC atomics are currently broken on some platforms, meaning it's currently necessary to compile with `--disable-gcc-atomics` using autotools or `-DSDL_GCC_ATOMICS=OFF` using CMake.
The joystick, locale and power APIs are not yet implemented.
The video driver currently provides full screen video support with keyboard and mouse input. Windowed mode is not yet supported, but is planned in the future. Only software rendering is supported.
The filesystem APIs return either Unix-style paths or RISC OS-style paths based on the value of the `__riscosify_control` symbol, as is standard for UnixLib functions.
The audio, loadso, thread and timer APIs are currently provided by UnixLib.
GCC atomics are currently broken on some platforms, meaning it's currently necessary to compile with `--disable-gcc-atomics` using autotools or `-DSDL_GCC_ATOMICS=OFF` using CMake.
The joystick, locale and power APIs are not yet implemented.
The linux touch system is currently based off event streams, and proc/bus/devices. The active user must be given permissions to read /dev/input/TOUCHDEVICE, where TOUCHDEVICE is the event stream for your device. Currently only Wacom tablets are supported. If you have an unsupported tablet contact me at jim.tla+sdl_touch@gmail.com and I will help you get support for it.
Mac:
The Mac and iPhone 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.
iPhone:
Works out of box.
Windows:
Unfortunately there is no windows support as of yet. Support for Windows 7 is planned, but we currently have no way to test. If you have a Windows 7 WM_TOUCH supported device, and are willing to help test please contact me at jim.tla+sdl_touch@gmail.com
SDL provides the ability to access the underlying SDL_Finger structures.
These structures should _never_ be modified.
The following functions are included from SDL_touch.h
To get a SDL_TouchID call SDL_GetTouchDevice(int index).
This returns a SDL_TouchID.
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!
The number of touch devices can be queried with SDL_GetNumTouchDevices().
A SDL_TouchID may be used to get pointers to SDL_Finger.
SDL_GetNumTouchFingers(touchID) may be used to get the number of fingers currently down on the device.
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:
float x = event.tfinger.x;
float y = event.tfinger.y;
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.
This returns a SDL_Finger *, or NULL if the finger does not exist, or has been removed.
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.
As a result, be very careful to check for NULL return values.
The linux touch system is currently based off event streams, and proc/bus/devices. The active user must be given permissions to read /dev/input/TOUCHDEVICE, where TOUCHDEVICE is the event stream for your device. Currently only Wacom tablets are supported. If you have an unsupported tablet contact me at jim.tla+sdl_touch@gmail.com and I will help you get support for it.
Mac:
The Mac and iPhone 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.
iPhone:
Works out of box.
Windows:
Unfortunately there is no windows support as of yet. Support for Windows 7 is planned, but we currently have no way to test. If you have a Windows 7 WM_TOUCH supported device, and are willing to help test please contact me at jim.tla+sdl_touch@gmail.com
SDL provides the ability to access the underlying SDL_Finger structures.
These structures should _never_ be modified.
The following functions are included from SDL_touch.h
To get a SDL_TouchID call SDL_GetTouchDevice(int index).
This returns a SDL_TouchID.
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!
The number of touch devices can be queried with SDL_GetNumTouchDevices().
A SDL_TouchID may be used to get pointers to SDL_Finger.
SDL_GetNumTouchFingers(touchID) may be used to get the number of fingers currently down on the device.
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:
float x = event.tfinger.x;
float y = event.tfinger.y;
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.
This returns a SDL_Finger *, or NULL if the finger does not exist, or has been removed.
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.
As a result, be very careful to check for NULL return values.
You can either use the precompiled libraries from the [SDL](https://www.libsdl.org/download.php) web site, or you can build SDL
yourself.
### Building SDL
0. To build SDL, your machine must, at a minimum, have the DirectX9.0c SDK installed. It may or may not be retrievable from
the [Microsoft](https://www.microsoft.com) website, so you might need to locate it [online](https://duckduckgo.com/?q=directx9.0c+sdk+download&t=h_&ia=web).
_Editor's note: I've been able to successfully build SDL using Visual Studio 2019 **without** the DX9.0c SDK_
1. Open the Visual Studio solution file at `./VisualC/SDL.sln`.
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
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`.
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`.
You may get a few warnings, but you should not get any errors.
Later, we will refer to the following `.lib` and `.dll` files that have just been generated:
- `./VisualC/Win32/Debug/SDL2.dll` or `./VisualC/Win32/Release/SDL2.dll`
- `./VisualC/Win32/Debug/SDL2.lib` or `./VisualC/Win32/Release/SDL2.lib`
- `./VisualC/Win32/Debug/SDL2main.lib` or `./VisualC/Win32/Release/SDL2main.lib`
_Note for the `x64` versions, just replace `Win32` in the path with `x64`_
### Creating a Project with SDL
- Create a project as a `Win32 Application`.
- Create a C++ file for your project.
- Set the C runtime to `Multi-threaded DLL` in the menu:
I hope that this document has helped you get through the most difficult part of using the SDL: installing it.
Suggestions for improvements should be posted to the [Github Issues](https://github.com/libsdl-org/SDL/issues).
### Credits
Thanks to [Paulus Esterhazy](mailto:pesterhazy@gmx.net), for the work on VC++ port.
This document was originally called "VisualC.txt", and was written by [Sam Lantinga](mailto:slouken@libsdl.org).
Later, it was converted to HTML and expanded into the document that you see today by [Lion Kimbro](mailto:snowlion@sprynet.com).
Minor Fixes and Visual C++ 7 Information (In Green) was added by [James Turk](mailto:james@conceptofzero.net)
Using SDL with Microsoft Visual C++
===================================
### by Lion Kimbro with additions by James Turk
You can either use the precompiled libraries from the [SDL](https://www.libsdl.org/download.php) web site, or you can build SDL
yourself.
### Building SDL
0. To build SDL, your machine must, at a minimum, have the DirectX9.0c SDK installed. It may or may not be retrievable from
the [Microsoft](https://www.microsoft.com) website, so you might need to locate it [online](https://duckduckgo.com/?q=directx9.0c+sdk+download&t=h_&ia=web).
_Editor's note: I've been able to successfully build SDL using Visual Studio 2019 **without** the DX9.0c SDK_
1. Open the Visual Studio solution file at `./VisualC/SDL.sln`.
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
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`.
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`.
You may get a few warnings, but you should not get any errors.
Later, we will refer to the following `.lib` and `.dll` files that have just been generated:
- `./VisualC/Win32/Debug/SDL2.dll` or `./VisualC/Win32/Release/SDL2.dll`
- `./VisualC/Win32/Debug/SDL2.lib` or `./VisualC/Win32/Release/SDL2.lib`
- `./VisualC/Win32/Debug/SDL2main.lib` or `./VisualC/Win32/Release/SDL2main.lib`
_Note for the `x64` versions, just replace `Win32` in the path with `x64`_
### Creating a Project with SDL
- Create a project as a `Win32 Application`.
- Create a C++ file for your project.
- Set the C runtime to `Multi-threaded DLL` in the menu:
* 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:
`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.
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.
* 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.
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:
`SDL_setenv("VITA_DISABLE_TOUCH_FRONT", "1", 1);` and `SDL_setenv("VITA_DISABLE_TOUCH_BACK", "1", 1);`
* Support for L2/R2/R3/R3 buttons, haptic feedback and gamepad led only available on PSTV, or when using external ds4 gamepad on vita.
PS Vita
=======
SDL port for the Sony Playstation Vita and Sony Playstation TV
Credit to
* xerpi, cpasjuste and rsn8887 for initial (vita2d) port
* vitasdk/dolcesdk devs
* CBPS discord (Namely Graphene and SonicMastr)
Building
--------
To build for the PSVita, make sure you have vitasdk and cmake installed and run:
* 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:
`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.
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.
* 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.
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:
`SDL_setenv("VITA_DISABLE_TOUCH_FRONT", "1", 1);` and `SDL_setenv("VITA_DISABLE_TOUCH_BACK", "1", 1);`
* Support for L2/R2/R3/R3 buttons, haptic feedback and gamepad led only available on PSTV, or when using external ds4 gamepad on vita.
Loaded 100 of 707 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
indev
Alug
Gustaf Alhäll
Alug
chromaticpipe
PAS
Eidolon
James R.
Chearii
GenericHeroGuy
Anonimus
themixedupstuff
NepDisk
riomccloud