mirror of https://github.com/encounter/SDL.git
Converted README documentation to DOS text format
This commit is contained in:
Sam Lantinga
parent
bf076c22ad
commit
104c9541d9
|
|
@ -1,4 +1,4 @@
|
||||||
Android
|
Android
|
||||||
================================================================================
|
================================================================================
|
||||||
|
|
||||||
Requirements:
|
Requirements:
|
||||||
|
|
|
||||||
|
|
@ -1,6 +1,6 @@
|
||||||
CMake
|
CMake
|
||||||
================================================================================
|
================================================================================
|
||||||
(www.cmake.org)
|
(www.cmake.org)
|
||||||
|
|
||||||
SDL's build system was traditionally based on autotools. Over time, this
|
SDL's build system was traditionally based on autotools. Over time, this
|
||||||
approach has suffered from several issues across the different supported
|
approach has suffered from several issues across the different supported
|
||||||
|
|
|
||||||
|
|
@ -1,5 +1,5 @@
|
||||||
DirectFB
|
DirectFB
|
||||||
========
|
========
|
||||||
|
|
||||||
Supports:
|
Supports:
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -1,130 +1,130 @@
|
||||||
Dynamic API
|
Dynamic API
|
||||||
================================================================================
|
================================================================================
|
||||||
Originally posted by Ryan at:
|
Originally posted by Ryan at:
|
||||||
https://plus.google.com/103391075724026391227/posts/TB8UfnDYu4U
|
https://plus.google.com/103391075724026391227/posts/TB8UfnDYu4U
|
||||||
|
|
||||||
Background:
|
Background:
|
||||||
|
|
||||||
- The Steam Runtime has (at least in theory) a really kick-ass build of SDL2,
|
- The Steam Runtime has (at least in theory) a really kick-ass build of SDL2,
|
||||||
but developers are shipping their own SDL2 with individual Steam games.
|
but developers are shipping their own SDL2 with individual Steam games.
|
||||||
These games might stop getting updates, but a newer SDL2 might be needed later.
|
These games might stop getting updates, but a newer SDL2 might be needed later.
|
||||||
Certainly we'll always be fixing bugs in SDL, even if a new video target isn't
|
Certainly we'll always be fixing bugs in SDL, even if a new video target isn't
|
||||||
ever needed, and these fixes won't make it to a game shipping its own SDL.
|
ever needed, and these fixes won't make it to a game shipping its own SDL.
|
||||||
- Even if we replace the SDL2 in those games with a compatible one, that is to
|
- Even if we replace the SDL2 in those games with a compatible one, that is to
|
||||||
say, edit a developer's Steam depot (yuck!), there are developers that are
|
say, edit a developer's Steam depot (yuck!), there are developers that are
|
||||||
statically linking SDL2 that we can't do this for. We can't even force the
|
statically linking SDL2 that we can't do this for. We can't even force the
|
||||||
dynamic loader to ignore their SDL2 in this case, of course.
|
dynamic loader to ignore their SDL2 in this case, of course.
|
||||||
- If you don't ship an SDL2 with the game in some form, people that disabled the
|
- If you don't ship an SDL2 with the game in some form, people that disabled the
|
||||||
Steam Runtime, or just tried to run the game from the command line instead of
|
Steam Runtime, or just tried to run the game from the command line instead of
|
||||||
Steam might find themselves unable to run the game, due to a missing dependency.
|
Steam might find themselves unable to run the game, due to a missing dependency.
|
||||||
- If you want to ship on non-Steam platforms like GOG or Humble Bundle, or target
|
- If you want to ship on non-Steam platforms like GOG or Humble Bundle, or target
|
||||||
generic Linux boxes that may or may not have SDL2 installed, you have to ship
|
generic Linux boxes that may or may not have SDL2 installed, you have to ship
|
||||||
the library or risk a total failure to launch. So now, you might have to have
|
the library or risk a total failure to launch. So now, you might have to have
|
||||||
a non-Steam build plus a Steam build (that is, one with and one without SDL2
|
a non-Steam build plus a Steam build (that is, one with and one without SDL2
|
||||||
included), which is inconvenient if you could have had one universal build
|
included), which is inconvenient if you could have had one universal build
|
||||||
that works everywhere.
|
that works everywhere.
|
||||||
- We like the zlib license, but the biggest complaint from the open source
|
- We like the zlib license, but the biggest complaint from the open source
|
||||||
community about the license change is the static linking. The LGPL forced this
|
community about the license change is the static linking. The LGPL forced this
|
||||||
as a legal, not technical issue, but zlib doesn't care. Even those that aren't
|
as a legal, not technical issue, but zlib doesn't care. Even those that aren't
|
||||||
concerned about the GNU freedoms found themselves solving the same problems:
|
concerned about the GNU freedoms found themselves solving the same problems:
|
||||||
swapping in a newer SDL to an older game often times can save the day.
|
swapping in a newer SDL to an older game often times can save the day.
|
||||||
Static linking stops this dead.
|
Static linking stops this dead.
|
||||||
|
|
||||||
So here's what we did:
|
So here's what we did:
|
||||||
|
|
||||||
SDL now has, internally, a table of function pointers. So, this is what SDL_Init
|
SDL now has, internally, a table of function pointers. So, this is what SDL_Init
|
||||||
now looks like:
|
now looks like:
|
||||||
|
|
||||||
UInt32 SDL_Init(Uint32 flags)
|
UInt32 SDL_Init(Uint32 flags)
|
||||||
{
|
{
|
||||||
return jump_table.SDL_Init(flags);
|
return jump_table.SDL_Init(flags);
|
||||||
}
|
}
|
||||||
|
|
||||||
Except that is all done with a bunch of macro magic so we don't have to maintain
|
Except that is all done with a bunch of macro magic so we don't have to maintain
|
||||||
every one of these.
|
every one of these.
|
||||||
|
|
||||||
What is jump_table.SDL_init()? Eventually, that's a function pointer of the real
|
What is jump_table.SDL_init()? Eventually, that's a function pointer of the real
|
||||||
SDL_Init() that you've been calling all this time. But at startup, it looks more
|
SDL_Init() that you've been calling all this time. But at startup, it looks more
|
||||||
like this:
|
like this:
|
||||||
|
|
||||||
Uint32 SDL_Init_DEFAULT(Uint32 flags)
|
Uint32 SDL_Init_DEFAULT(Uint32 flags)
|
||||||
{
|
{
|
||||||
SDL_InitDynamicAPI();
|
SDL_InitDynamicAPI();
|
||||||
return jump_table.SDL_Init(flags);
|
return jump_table.SDL_Init(flags);
|
||||||
}
|
}
|
||||||
|
|
||||||
SDL_InitDynamicAPI() fills in jump_table with all the actual SDL function
|
SDL_InitDynamicAPI() fills in jump_table with all the actual SDL function
|
||||||
pointers, which means that this _DEFAULT function never gets called again.
|
pointers, which means that this _DEFAULT function never gets called again.
|
||||||
First call to any SDL function sets the whole thing up.
|
First call to any SDL function sets the whole thing up.
|
||||||
|
|
||||||
So you might be asking, what was the value in that? Isn't this what the operating
|
So you might be asking, what was the value in that? Isn't this what the operating
|
||||||
system's dynamic loader was supposed to do for us? Yes, but now we've got this
|
system's dynamic loader was supposed to do for us? Yes, but now we've got this
|
||||||
level of indirection, we can do things like this:
|
level of indirection, we can do things like this:
|
||||||
|
|
||||||
export SDL_DYNAMIC_API=/my/actual/libSDL-2.0.so.0
|
export SDL_DYNAMIC_API=/my/actual/libSDL-2.0.so.0
|
||||||
./MyGameThatIsStaticallyLinkedToSDL2
|
./MyGameThatIsStaticallyLinkedToSDL2
|
||||||
|
|
||||||
And now, this game that is staticallly linked to SDL, can still be overridden
|
And now, this game that is staticallly linked to SDL, can still be overridden
|
||||||
with a newer, or better, SDL. The statically linked one will only be used as
|
with a newer, or better, SDL. The statically linked one will only be used as
|
||||||
far as calling into the jump table in this case. But in cases where no override
|
far as calling into the jump table in this case. But in cases where no override
|
||||||
is desired, the statically linked version will provide its own jump table,
|
is desired, the statically linked version will provide its own jump table,
|
||||||
and everyone is happy.
|
and everyone is happy.
|
||||||
|
|
||||||
So now:
|
So now:
|
||||||
- Developers can statically link SDL, and users can still replace it.
|
- Developers can statically link SDL, and users can still replace it.
|
||||||
(We'd still rather you ship a shared library, though!)
|
(We'd still rather you ship a shared library, though!)
|
||||||
- Developers can ship an SDL with their game, Valve can override it for, say,
|
- Developers can ship an SDL with their game, Valve can override it for, say,
|
||||||
new features on SteamOS, or distros can override it for their own needs,
|
new features on SteamOS, or distros can override it for their own needs,
|
||||||
but it'll also just work in the default case.
|
but it'll also just work in the default case.
|
||||||
- Developers can ship the same package to everyone (Humble Bundle, GOG, etc),
|
- Developers can ship the same package to everyone (Humble Bundle, GOG, etc),
|
||||||
and it'll do the right thing.
|
and it'll do the right thing.
|
||||||
- End users (and Valve) can update a game's SDL in almost any case,
|
- End users (and Valve) can update a game's SDL in almost any case,
|
||||||
to keep abandoned games running on newer platforms.
|
to keep abandoned games running on newer platforms.
|
||||||
- Everyone develops with SDL exactly as they have been doing all along.
|
- Everyone develops with SDL exactly as they have been doing all along.
|
||||||
Same headers, same ABI. Just get the latest version to enable this magic.
|
Same headers, same ABI. Just get the latest version to enable this magic.
|
||||||
|
|
||||||
|
|
||||||
A little more about SDL_InitDynamicAPI():
|
A little more about SDL_InitDynamicAPI():
|
||||||
|
|
||||||
Internally, InitAPI does some locking to make sure everything waits until a
|
Internally, InitAPI does some locking to make sure everything waits until a
|
||||||
single thread initializes everything (although even SDL_CreateThread() goes
|
single thread initializes everything (although even SDL_CreateThread() goes
|
||||||
through here before spinning a thread, too), and then decides if it should use
|
through here before spinning a thread, too), and then decides if it should use
|
||||||
an external SDL library. If not, it sets up the jump table using the current
|
an external SDL library. If not, it sets up the jump table using the current
|
||||||
SDL's function pointers (which might be statically linked into a program, or in
|
SDL's function pointers (which might be statically linked into a program, or in
|
||||||
a shared library of its own). If so, it loads that library and looks for and
|
a shared library of its own). If so, it loads that library and looks for and
|
||||||
calls a single function:
|
calls a single function:
|
||||||
|
|
||||||
SInt32 SDL_DYNAPI_entry(Uint32 version, void *table, Uint32 tablesize);
|
SInt32 SDL_DYNAPI_entry(Uint32 version, void *table, Uint32 tablesize);
|
||||||
|
|
||||||
That function takes a version number (more on that in a moment), the address of
|
That function takes a version number (more on that in a moment), the address of
|
||||||
the jump table, and the size, in bytes, of the table.
|
the jump table, and the size, in bytes, of the table.
|
||||||
Now, we've got policy here: this table's layout never changes; new stuff gets
|
Now, we've got policy here: this table's layout never changes; new stuff gets
|
||||||
added to the end. Therefore SDL_DYNAPI_entry() knows that it can provide all
|
added to the end. Therefore SDL_DYNAPI_entry() knows that it can provide all
|
||||||
the needed functions if tablesize <= sizeof its own jump table. If tablesize is
|
the needed functions if tablesize <= sizeof its own jump table. If tablesize is
|
||||||
bigger (say, SDL 2.0.4 is trying to load SDL 2.0.3), then we know to abort, but
|
bigger (say, SDL 2.0.4 is trying to load SDL 2.0.3), then we know to abort, but
|
||||||
if it's smaller, we know we can provide the entire API that the caller needs.
|
if it's smaller, we know we can provide the entire API that the caller needs.
|
||||||
|
|
||||||
The version variable is a failsafe switch.
|
The version variable is a failsafe switch.
|
||||||
Right now it's always 1. This number changes when there are major API changes
|
Right now it's always 1. This number changes when there are major API changes
|
||||||
(so we know if the tablesize might be smaller, or entries in it have changed).
|
(so we know if the tablesize might be smaller, or entries in it have changed).
|
||||||
Right now SDL_DYNAPI_entry gives up if the version doesn't match, but it's not
|
Right now SDL_DYNAPI_entry gives up if the version doesn't match, but it's not
|
||||||
inconceivable to have a small dispatch library that only supplies this one
|
inconceivable to have a small dispatch library that only supplies this one
|
||||||
function and loads different, otherwise-incompatible SDL libraries and has the
|
function and loads different, otherwise-incompatible SDL libraries and has the
|
||||||
right one initialize the jump table based on the version. For something that
|
right one initialize the jump table based on the version. For something that
|
||||||
must generically catch lots of different versions of SDL over time, like the
|
must generically catch lots of different versions of SDL over time, like the
|
||||||
Steam Client, this isn't a bad option.
|
Steam Client, this isn't a bad option.
|
||||||
|
|
||||||
Finally, I'm sure some people are reading this and thinking,
|
Finally, I'm sure some people are reading this and thinking,
|
||||||
"I don't want that overhead in my project!"
|
"I don't want that overhead in my project!"
|
||||||
To which I would point out that the extra function call through the jump table
|
To which I would point out that the extra function call through the jump table
|
||||||
probably wouldn't even show up in a profile, but lucky you: this can all be
|
probably wouldn't even show up in a profile, but lucky you: this can all be
|
||||||
disabled. You can build SDL without this if you absolutely must, but we would
|
disabled. You can build SDL without this if you absolutely must, but we would
|
||||||
encourage you not to do that. However, on heavily locked down platforms like
|
encourage you not to do that. However, on heavily locked down platforms like
|
||||||
iOS, or maybe when debugging, it makes sense to disable it. The way this is
|
iOS, or maybe when debugging, it makes sense to disable it. The way this is
|
||||||
designed in SDL, you just have to change one #define, and the entire system
|
designed in SDL, you just have to change one #define, and the entire system
|
||||||
vaporizes out, and SDL functions exactly like it always did. Most of it is
|
vaporizes out, and SDL functions exactly like it always did. Most of it is
|
||||||
macro magic, so the system is contained to one C file and a few headers.
|
macro magic, so the system is contained to one C file and a few headers.
|
||||||
However, this is on by default and you have to edit a header file to turn it
|
However, this is on by default and you have to edit a header file to turn it
|
||||||
off. Our hopes is that if we make it easy to disable, but not too easy,
|
off. Our hopes is that if we make it easy to disable, but not too easy,
|
||||||
everyone will ultimately be able to get what they want, but we've gently
|
everyone will ultimately be able to get what they want, but we've gently
|
||||||
nudged everyone towards what we think is the best solution.
|
nudged everyone towards what we think is the best solution.
|
||||||
|
|
|
||||||
|
|
@ -1,37 +1,37 @@
|
||||||
Emscripten
|
Emscripten
|
||||||
================================================================================
|
================================================================================
|
||||||
|
|
||||||
Build:
|
Build:
|
||||||
|
|
||||||
$ mkdir build
|
$ mkdir build
|
||||||
$ cd build
|
$ cd build
|
||||||
$ emconfigure ../configure --host=asmjs-unknown-emscripten --disable-assembly --disable-threads --enable-cpuinfo=false CFLAGS="-O2"
|
$ emconfigure ../configure --host=asmjs-unknown-emscripten --disable-assembly --disable-threads --enable-cpuinfo=false CFLAGS="-O2"
|
||||||
$ emmake make
|
$ emmake make
|
||||||
|
|
||||||
Or with cmake:
|
Or with cmake:
|
||||||
|
|
||||||
$ mkdir build
|
$ mkdir build
|
||||||
$ cd build
|
$ cd build
|
||||||
$ emcmake cmake ..
|
$ emcmake cmake ..
|
||||||
$ emmake make
|
$ emmake make
|
||||||
|
|
||||||
To build one of the tests:
|
To build one of the tests:
|
||||||
|
|
||||||
$ cd test/
|
$ cd test/
|
||||||
$ emcc -O2 --js-opts 0 -g4 testdraw2.c -I../include ../build/.libs/libSDL2.a ../build/libSDL2_test.a -o a.html
|
$ emcc -O2 --js-opts 0 -g4 testdraw2.c -I../include ../build/.libs/libSDL2.a ../build/libSDL2_test.a -o a.html
|
||||||
|
|
||||||
Uses GLES2 renderer or software
|
Uses GLES2 renderer or software
|
||||||
|
|
||||||
tests: https://dl.dropboxusercontent.com/u/17360362/SDL2-em/index.html
|
tests: https://dl.dropboxusercontent.com/u/17360362/SDL2-em/index.html
|
||||||
|
|
||||||
Some other SDL2 libraries can be easily built (assuming SDL2 is installed somewhere):
|
Some other SDL2 libraries can be easily built (assuming SDL2 is installed somewhere):
|
||||||
|
|
||||||
SDL_mixer (http://www.libsdl.org/projects/SDL_mixer/):
|
SDL_mixer (http://www.libsdl.org/projects/SDL_mixer/):
|
||||||
|
|
||||||
$ EMCONFIGURE_JS=1 emconfigure ../configure
|
$ EMCONFIGURE_JS=1 emconfigure ../configure
|
||||||
build as usual...
|
build as usual...
|
||||||
|
|
||||||
SDL_gfx (http://cms.ferzkopp.net/index.php/software/13-sdl-gfx):
|
SDL_gfx (http://cms.ferzkopp.net/index.php/software/13-sdl-gfx):
|
||||||
|
|
||||||
$ EMCONFIGURE_JS=1 emconfigure ../configure --disable-mmx
|
$ EMCONFIGURE_JS=1 emconfigure ../configure --disable-mmx
|
||||||
build as usual...
|
build as usual...
|
||||||
|
|
|
||||||
|
|
@ -1,6 +1,6 @@
|
||||||
Mercurial
|
Mercurial
|
||||||
=========
|
=========
|
||||||
|
|
||||||
The latest development version of SDL is available via Mercurial.
|
The latest development version of SDL is available via Mercurial.
|
||||||
Mercurial allows you to get up-to-the-minute fixes and enhancements;
|
Mercurial allows you to get up-to-the-minute fixes and enhancements;
|
||||||
as a developer works on a source tree, you can use "hg" to mirror that
|
as a developer works on a source tree, you can use "hg" to mirror that
|
||||||
|
|
|
||||||
|
|
@ -1,85 +1,85 @@
|
||||||
Linux
|
Linux
|
||||||
================================================================================
|
================================================================================
|
||||||
|
|
||||||
By default SDL will only link against glibc, the rest of the features will be
|
By default SDL will only link against glibc, the rest of the features will be
|
||||||
enabled dynamically at runtime depending on the available features on the target
|
enabled dynamically at runtime depending on the available features on the target
|
||||||
system. So, for example if you built SDL with Xinerama support and the target
|
system. So, for example if you built SDL with Xinerama support and the target
|
||||||
system does not have the Xinerama libraries installed, it will be disabled
|
system does not have the Xinerama libraries installed, it will be disabled
|
||||||
at runtime, and you won't get a missing library error, at least with the
|
at runtime, and you won't get a missing library error, at least with the
|
||||||
default configuration parameters.
|
default configuration parameters.
|
||||||
|
|
||||||
|
|
||||||
================================================================================
|
================================================================================
|
||||||
Build Dependencies
|
Build Dependencies
|
||||||
================================================================================
|
================================================================================
|
||||||
|
|
||||||
Ubuntu 13.04, all available features enabled:
|
Ubuntu 13.04, all available features enabled:
|
||||||
|
|
||||||
sudo apt-get install build-essential mercurial make cmake autoconf automake \
|
sudo apt-get install build-essential mercurial make cmake autoconf automake \
|
||||||
libtool libasound2-dev libpulse-dev libaudio-dev libx11-dev libxext-dev \
|
libtool libasound2-dev libpulse-dev libaudio-dev libx11-dev libxext-dev \
|
||||||
libxrandr-dev libxcursor-dev libxi-dev libxinerama-dev libxxf86vm-dev \
|
libxrandr-dev libxcursor-dev libxi-dev libxinerama-dev libxxf86vm-dev \
|
||||||
libxss-dev libgl1-mesa-dev libesd0-dev libdbus-1-dev libudev-dev \
|
libxss-dev libgl1-mesa-dev libesd0-dev libdbus-1-dev libudev-dev \
|
||||||
libgles1-mesa-dev libgles2-mesa-dev libegl1-mesa-dev libibus-1.0-dev
|
libgles1-mesa-dev libgles2-mesa-dev libegl1-mesa-dev libibus-1.0-dev
|
||||||
|
|
||||||
Ubuntu 16.04 can also add "libwayland-dev libxkbcommon-dev wayland-protocols"
|
Ubuntu 16.04 can also add "libwayland-dev libxkbcommon-dev wayland-protocols"
|
||||||
to that command line for Wayland support.
|
to that command line for Wayland support.
|
||||||
|
|
||||||
Ubuntu 16.10 can also add "libmirclient-dev libxkbcommon-dev" to that command
|
Ubuntu 16.10 can also add "libmirclient-dev libxkbcommon-dev" to that command
|
||||||
line for Mir support.
|
line for Mir support.
|
||||||
|
|
||||||
NOTES:
|
NOTES:
|
||||||
- This includes all the audio targets except arts, because Ubuntu pulled the
|
- This includes all the audio targets except arts, because Ubuntu pulled the
|
||||||
artsc0-dev package, but in theory SDL still supports it.
|
artsc0-dev package, but in theory SDL still supports it.
|
||||||
- DirectFB isn't included because the configure script (currently) fails to find
|
- DirectFB isn't included because the configure script (currently) fails to find
|
||||||
it at all. You can do "sudo apt-get install libdirectfb-dev" and fix the
|
it at all. You can do "sudo apt-get install libdirectfb-dev" and fix the
|
||||||
configure script to include DirectFB support. Send patches. :)
|
configure script to include DirectFB support. Send patches. :)
|
||||||
|
|
||||||
|
|
||||||
================================================================================
|
================================================================================
|
||||||
Joystick does not work
|
Joystick does not work
|
||||||
================================================================================
|
================================================================================
|
||||||
|
|
||||||
If you compiled or are using a version of SDL with udev support (and you should!)
|
If you compiled or are using a version of SDL with udev support (and you should!)
|
||||||
there's a few issues that may cause SDL to fail to detect your joystick. To
|
there's a few issues that may cause SDL to fail to detect your joystick. To
|
||||||
debug this, start by installing the evtest utility. On Ubuntu/Debian:
|
debug this, start by installing the evtest utility. On Ubuntu/Debian:
|
||||||
|
|
||||||
sudo apt-get install evtest
|
sudo apt-get install evtest
|
||||||
|
|
||||||
Then run:
|
Then run:
|
||||||
|
|
||||||
sudo evtest
|
sudo evtest
|
||||||
|
|
||||||
You'll hopefully see your joystick listed along with a name like "/dev/input/eventXX"
|
You'll hopefully see your joystick listed along with a name like "/dev/input/eventXX"
|
||||||
Now run:
|
Now run:
|
||||||
|
|
||||||
cat /dev/input/event/XX
|
cat /dev/input/event/XX
|
||||||
|
|
||||||
If you get a permission error, you need to set a udev rule to change the mode of
|
If you get a permission error, you need to set a udev rule to change the mode of
|
||||||
your device (see below)
|
your device (see below)
|
||||||
|
|
||||||
Also, try:
|
Also, try:
|
||||||
|
|
||||||
sudo udevadm info --query=all --name=input/eventXX
|
sudo udevadm info --query=all --name=input/eventXX
|
||||||
|
|
||||||
If you see a line stating ID_INPUT_JOYSTICK=1, great, if you don't see it,
|
If you see a line stating ID_INPUT_JOYSTICK=1, great, if you don't see it,
|
||||||
you need to set up an udev rule to force this variable.
|
you need to set up an udev rule to force this variable.
|
||||||
|
|
||||||
A combined rule for the Saitek Pro Flight Rudder Pedals to fix both issues looks
|
A combined rule for the Saitek Pro Flight Rudder Pedals to fix both issues looks
|
||||||
like:
|
like:
|
||||||
|
|
||||||
SUBSYSTEM=="input", ATTRS{idProduct}=="0763", ATTRS{idVendor}=="06a3", MODE="0666", ENV{ID_INPUT_JOYSTICK}="1"
|
SUBSYSTEM=="input", ATTRS{idProduct}=="0763", ATTRS{idVendor}=="06a3", MODE="0666", ENV{ID_INPUT_JOYSTICK}="1"
|
||||||
SUBSYSTEM=="input", ATTRS{idProduct}=="0764", ATTRS{idVendor}=="06a3", MODE="0666", ENV{ID_INPUT_JOYSTICK}="1"
|
SUBSYSTEM=="input", ATTRS{idProduct}=="0764", ATTRS{idVendor}=="06a3", MODE="0666", ENV{ID_INPUT_JOYSTICK}="1"
|
||||||
|
|
||||||
You can set up similar rules for your device by changing the values listed in
|
You can set up similar rules for your device by changing the values listed in
|
||||||
idProduct and idVendor. To obtain these values, try:
|
idProduct and idVendor. To obtain these values, try:
|
||||||
|
|
||||||
sudo udevadm info -a --name=input/eventXX | grep idVendor
|
sudo udevadm info -a --name=input/eventXX | grep idVendor
|
||||||
sudo udevadm info -a --name=input/eventXX | grep idProduct
|
sudo udevadm info -a --name=input/eventXX | grep idProduct
|
||||||
|
|
||||||
If multiple values come up for each of these, the one you want is the first one of each.
|
If multiple values come up for each of these, the one you want is the first one of each.
|
||||||
|
|
||||||
On other systems which ship with an older udev (such as CentOS), you may need
|
On other systems which ship with an older udev (such as CentOS), you may need
|
||||||
to set up a rule such as:
|
to set up a rule such as:
|
||||||
|
|
||||||
SUBSYSTEM=="input", ENV{ID_CLASS}=="joystick", ENV{ID_INPUT_JOYSTICK}="1"
|
SUBSYSTEM=="input", ENV{ID_CLASS}=="joystick", ENV{ID_INPUT_JOYSTICK}="1"
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -1,103 +1,103 @@
|
||||||
Native Client
|
Native Client
|
||||||
================================================================================
|
================================================================================
|
||||||
|
|
||||||
Requirements:
|
Requirements:
|
||||||
|
|
||||||
* Native Client SDK (https://developer.chrome.com/native-client),
|
* Native Client SDK (https://developer.chrome.com/native-client),
|
||||||
(tested with Pepper version 33 or higher).
|
(tested with Pepper version 33 or higher).
|
||||||
|
|
||||||
The SDL backend for Chrome's Native Client has been tested only with the PNaCl
|
The SDL backend for Chrome's Native Client has been tested only with the PNaCl
|
||||||
toolchain, which generates binaries designed to run on ARM and x86_32/64
|
toolchain, which generates binaries designed to run on ARM and x86_32/64
|
||||||
platforms. This does not mean it won't work with the other toolchains!
|
platforms. This does not mean it won't work with the other toolchains!
|
||||||
|
|
||||||
================================================================================
|
================================================================================
|
||||||
Building SDL for NaCl
|
Building SDL for NaCl
|
||||||
================================================================================
|
================================================================================
|
||||||
|
|
||||||
Set up the right environment variables (see naclbuild.sh), then configure SDL with:
|
Set up the right environment variables (see naclbuild.sh), then configure SDL with:
|
||||||
|
|
||||||
configure --host=pnacl --prefix some/install/destination
|
configure --host=pnacl --prefix some/install/destination
|
||||||
|
|
||||||
Then "make".
|
Then "make".
|
||||||
|
|
||||||
As an example of how to create a deployable app a Makefile project is provided
|
As an example of how to create a deployable app a Makefile project is provided
|
||||||
in test/nacl/Makefile, which includes some monkey patching of the common.mk file
|
in test/nacl/Makefile, which includes some monkey patching of the common.mk file
|
||||||
provided by NaCl, without which linking properly to SDL won't work (the search
|
provided by NaCl, without which linking properly to SDL won't work (the search
|
||||||
path can't be modified externally, so the linker won't find SDL's binaries unless
|
path can't be modified externally, so the linker won't find SDL's binaries unless
|
||||||
you dump them into the SDK path, which is inconvenient).
|
you dump them into the SDK path, which is inconvenient).
|
||||||
Also provided in test/nacl is the required support file, such as index.html,
|
Also provided in test/nacl is the required support file, such as index.html,
|
||||||
manifest.json, etc.
|
manifest.json, etc.
|
||||||
SDL apps for NaCl run on a worker thread using the ppapi_simple infrastructure.
|
SDL apps for NaCl run on a worker thread using the ppapi_simple infrastructure.
|
||||||
This allows for blocking calls on all the relevant systems (OpenGL ES, filesystem),
|
This allows for blocking calls on all the relevant systems (OpenGL ES, filesystem),
|
||||||
hiding the asynchronous nature of the browser behind the scenes...which is not the
|
hiding the asynchronous nature of the browser behind the scenes...which is not the
|
||||||
same as making it disappear!
|
same as making it disappear!
|
||||||
|
|
||||||
|
|
||||||
================================================================================
|
================================================================================
|
||||||
Running tests
|
Running tests
|
||||||
================================================================================
|
================================================================================
|
||||||
|
|
||||||
Due to the nature of NaCl programs, building and running SDL tests is not as
|
Due to the nature of NaCl programs, building and running SDL tests is not as
|
||||||
straightforward as one would hope. The script naclbuild.sh in build-scripts
|
straightforward as one would hope. The script naclbuild.sh in build-scripts
|
||||||
automates the process and should serve as a guide for users of SDL trying to build
|
automates the process and should serve as a guide for users of SDL trying to build
|
||||||
their own applications.
|
their own applications.
|
||||||
|
|
||||||
Basic usage:
|
Basic usage:
|
||||||
|
|
||||||
./naclbuild.sh path/to/pepper/toolchain (i.e. ~/naclsdk/pepper_35)
|
./naclbuild.sh path/to/pepper/toolchain (i.e. ~/naclsdk/pepper_35)
|
||||||
|
|
||||||
This will build testgles2.c by default.
|
This will build testgles2.c by default.
|
||||||
|
|
||||||
If you want to build a different test, for example testrendercopyex.c:
|
If you want to build a different test, for example testrendercopyex.c:
|
||||||
|
|
||||||
SOURCES=~/sdl/SDL/test/testrendercopyex.c ./naclbuild.sh ~/naclsdk/pepper_35
|
SOURCES=~/sdl/SDL/test/testrendercopyex.c ./naclbuild.sh ~/naclsdk/pepper_35
|
||||||
|
|
||||||
Once the build finishes, you have to serve the contents with a web server (the
|
Once the build finishes, you have to serve the contents with a web server (the
|
||||||
script will give you instructions on how to do that with Python).
|
script will give you instructions on how to do that with Python).
|
||||||
|
|
||||||
================================================================================
|
================================================================================
|
||||||
RWops and nacl_io
|
RWops and nacl_io
|
||||||
================================================================================
|
================================================================================
|
||||||
|
|
||||||
SDL_RWops work transparently with nacl_io. Two functions control the mount points:
|
SDL_RWops work transparently with nacl_io. Two functions control the mount points:
|
||||||
|
|
||||||
int mount(const char* source, const char* target,
|
int mount(const char* source, const char* target,
|
||||||
const char* filesystemtype,
|
const char* filesystemtype,
|
||||||
unsigned long mountflags, const void *data);
|
unsigned long mountflags, const void *data);
|
||||||
int umount(const char *target);
|
int umount(const char *target);
|
||||||
|
|
||||||
For convenience, SDL will by default mount an httpfs tree at / before calling
|
For convenience, SDL will by default mount an httpfs tree at / before calling
|
||||||
the app's main function. Such setting can be overridden by calling:
|
the app's main function. Such setting can be overridden by calling:
|
||||||
|
|
||||||
umount("/");
|
umount("/");
|
||||||
|
|
||||||
And then mounting a different filesystem at /
|
And then mounting a different filesystem at /
|
||||||
|
|
||||||
It's important to consider that the asynchronous nature of file operations on a
|
It's important to consider that the asynchronous nature of file operations on a
|
||||||
browser is hidden from the application, effectively providing the developer with
|
browser is hidden from the application, effectively providing the developer with
|
||||||
a set of blocking file operations just like you get in a regular desktop
|
a set of blocking file operations just like you get in a regular desktop
|
||||||
environment, which eases the job of porting to Native Client, but also introduces
|
environment, which eases the job of porting to Native Client, but also introduces
|
||||||
a set of challenges of its own, in particular when big file sizes and slow
|
a set of challenges of its own, in particular when big file sizes and slow
|
||||||
connections are involved.
|
connections are involved.
|
||||||
|
|
||||||
For more information on how nacl_io and mount points work, see:
|
For more information on how nacl_io and mount points work, see:
|
||||||
|
|
||||||
https://developer.chrome.com/native-client/devguide/coding/nacl_io
|
https://developer.chrome.com/native-client/devguide/coding/nacl_io
|
||||||
https://src.chromium.org/chrome/trunk/src/native_client_sdk/src/libraries/nacl_io/nacl_io.h
|
https://src.chromium.org/chrome/trunk/src/native_client_sdk/src/libraries/nacl_io/nacl_io.h
|
||||||
|
|
||||||
To be able to save into the directory "/save/" (like backup of game) :
|
To be able to save into the directory "/save/" (like backup of game) :
|
||||||
|
|
||||||
mount("", "/save", "html5fs", 0, "type=PERSISTENT");
|
mount("", "/save", "html5fs", 0, "type=PERSISTENT");
|
||||||
|
|
||||||
And add to manifest.json :
|
And add to manifest.json :
|
||||||
|
|
||||||
"permissions": [
|
"permissions": [
|
||||||
"unlimitedStorage"
|
"unlimitedStorage"
|
||||||
]
|
]
|
||||||
|
|
||||||
================================================================================
|
================================================================================
|
||||||
TODO - Known Issues
|
TODO - Known Issues
|
||||||
================================================================================
|
================================================================================
|
||||||
* Testing of all systems with a real application (something other than SDL's tests)
|
* Testing of all systems with a real application (something other than SDL's tests)
|
||||||
* Key events don't seem to work properly
|
* Key events don't seem to work properly
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -1,7 +1,7 @@
|
||||||
Pandora
|
Pandora
|
||||||
=====================================================================
|
=====================================================================
|
||||||
|
|
||||||
( http://openpandora.org/ )
|
( http://openpandora.org/ )
|
||||||
- A pandora specific video driver was written to allow SDL 2.0 with OpenGL ES
|
- A pandora specific video driver was written to allow SDL 2.0 with OpenGL ES
|
||||||
support to work on the pandora under the framebuffer. This driver do not have
|
support to work on the pandora under the framebuffer. This driver do not have
|
||||||
input support for now, so if you use it you will have to add your own control code.
|
input support for now, so if you use it you will have to add your own control code.
|
||||||
|
|
|
||||||
|
|
@ -1,8 +1,8 @@
|
||||||
Platforms
|
Platforms
|
||||||
=========
|
=========
|
||||||
|
|
||||||
We maintain the list of supported platforms on our wiki now, and how to
|
We maintain the list of supported platforms on our wiki now, and how to
|
||||||
build and install SDL for those platforms:
|
build and install SDL for those platforms:
|
||||||
|
|
||||||
https://wiki.libsdl.org/Installation
|
https://wiki.libsdl.org/Installation
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -1,5 +1,5 @@
|
||||||
PSP
|
PSP
|
||||||
======
|
======
|
||||||
SDL port for the Sony PSP contributed by
|
SDL port for the Sony PSP contributed by
|
||||||
Captian Lex
|
Captian Lex
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -1,4 +1,4 @@
|
||||||
Touch
|
Touch
|
||||||
===========================================================================
|
===========================================================================
|
||||||
System Specific Notes
|
System Specific Notes
|
||||||
===========================================================================
|
===========================================================================
|
||||||
|
|
|
||||||
|
|
@ -1,5 +1,5 @@
|
||||||
WinCE
|
WinCE
|
||||||
=====
|
=====
|
||||||
|
|
||||||
Windows CE is no longer supported by SDL.
|
Windows CE is no longer supported by SDL.
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -1,41 +1,41 @@
|
||||||
Windows
|
Windows
|
||||||
================================================================================
|
================================================================================
|
||||||
|
|
||||||
================================================================================
|
================================================================================
|
||||||
OpenGL ES 2.x support
|
OpenGL ES 2.x support
|
||||||
================================================================================
|
================================================================================
|
||||||
|
|
||||||
SDL has support for OpenGL ES 2.x under Windows via two alternative
|
SDL has support for OpenGL ES 2.x under Windows via two alternative
|
||||||
implementations.
|
implementations.
|
||||||
The most straightforward method consists in running your app in a system with
|
The most straightforward method consists in running your app in a system with
|
||||||
a graphic card paired with a relatively recent (as of November of 2013) driver
|
a graphic card paired with a relatively recent (as of November of 2013) driver
|
||||||
which supports the WGL_EXT_create_context_es2_profile extension. Vendors known
|
which supports the WGL_EXT_create_context_es2_profile extension. Vendors known
|
||||||
to ship said extension on Windows currently include nVidia and Intel.
|
to ship said extension on Windows currently include nVidia and Intel.
|
||||||
|
|
||||||
The other method involves using the ANGLE library (https://code.google.com/p/angleproject/)
|
The other method involves using the ANGLE library (https://code.google.com/p/angleproject/)
|
||||||
If an OpenGL ES 2.x context is requested and no WGL_EXT_create_context_es2_profile
|
If an OpenGL ES 2.x context is requested and no WGL_EXT_create_context_es2_profile
|
||||||
extension is found, SDL will try to load the libEGL.dll library provided by
|
extension is found, SDL will try to load the libEGL.dll library provided by
|
||||||
ANGLE.
|
ANGLE.
|
||||||
To obtain the ANGLE binaries, you can either compile from source from
|
To obtain the ANGLE binaries, you can either compile from source from
|
||||||
https://chromium.googlesource.com/angle/angle or copy the relevant binaries from
|
https://chromium.googlesource.com/angle/angle or copy the relevant binaries from
|
||||||
a recent Chrome/Chromium install for Windows. The files you need are:
|
a recent Chrome/Chromium install for Windows. The files you need are:
|
||||||
|
|
||||||
* libEGL.dll
|
* libEGL.dll
|
||||||
* libGLESv2.dll
|
* libGLESv2.dll
|
||||||
* d3dcompiler_46.dll (supports Windows Vista or later, better shader compiler)
|
* d3dcompiler_46.dll (supports Windows Vista or later, better shader compiler)
|
||||||
or...
|
or...
|
||||||
* d3dcompiler_43.dll (supports Windows XP or later)
|
* d3dcompiler_43.dll (supports Windows XP or later)
|
||||||
|
|
||||||
If you compile ANGLE from source, you can configure it so it does not need the
|
If you compile ANGLE from source, you can configure it so it does not need the
|
||||||
d3dcompiler_* DLL at all (for details on this, see their documentation).
|
d3dcompiler_* DLL at all (for details on this, see their documentation).
|
||||||
However, by default SDL will try to preload the d3dcompiler_46.dll to
|
However, by default SDL will try to preload the d3dcompiler_46.dll to
|
||||||
comply with ANGLE's requirements. If you wish SDL to preload d3dcompiler_43.dll (to
|
comply with ANGLE's requirements. If you wish SDL to preload d3dcompiler_43.dll (to
|
||||||
support Windows XP) or to skip this step at all, you can use the
|
support Windows XP) or to skip this step at all, you can use the
|
||||||
SDL_HINT_VIDEO_WIN_D3DCOMPILER hint (see SDL_hints.h for more details).
|
SDL_HINT_VIDEO_WIN_D3DCOMPILER hint (see SDL_hints.h for more details).
|
||||||
|
|
||||||
Known Bugs:
|
Known Bugs:
|
||||||
|
|
||||||
* SDL_GL_SetSwapInterval is currently a no op when using ANGLE. It appears
|
* SDL_GL_SetSwapInterval is currently a no op when using ANGLE. It appears
|
||||||
that there's a bug in the library which prevents the window contents from
|
that there's a bug in the library which prevents the window contents from
|
||||||
refreshing if this is set to anything other than the default value.
|
refreshing if this is set to anything other than the default value.
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -1,478 +1,478 @@
|
||||||
WinRT
|
WinRT
|
||||||
=====
|
=====
|
||||||
|
|
||||||
This port allows SDL applications to run on Microsoft's platforms that require
|
This port allows SDL applications to run on Microsoft's platforms that require
|
||||||
use of "Windows Runtime", aka. "WinRT", APIs. Microsoft may, in some cases,
|
use of "Windows Runtime", aka. "WinRT", APIs. Microsoft may, in some cases,
|
||||||
refer to them as either "Windows Store", or for Windows 10, "UWP" apps.
|
refer to them as either "Windows Store", or for Windows 10, "UWP" apps.
|
||||||
|
|
||||||
Some of the operating systems that include WinRT, are:
|
Some of the operating systems that include WinRT, are:
|
||||||
|
|
||||||
* Windows 10, via its Universal Windows Platform (UWP) APIs
|
* Windows 10, via its Universal Windows Platform (UWP) APIs
|
||||||
* Windows 8.x
|
* Windows 8.x
|
||||||
* Windows RT 8.x (aka. Windows 8.x for ARM processors)
|
* Windows RT 8.x (aka. Windows 8.x for ARM processors)
|
||||||
* Windows Phone 8.x
|
* Windows Phone 8.x
|
||||||
|
|
||||||
|
|
||||||
Requirements
|
Requirements
|
||||||
------------
|
------------
|
||||||
|
|
||||||
* Microsoft Visual C++ (aka Visual Studio), either 2015, 2013, or 2012
|
* Microsoft Visual C++ (aka Visual Studio), either 2015, 2013, or 2012
|
||||||
- Free, "Community" or "Express" editions may be used, so long as they
|
- Free, "Community" or "Express" editions may be used, so long as they
|
||||||
include support for either "Windows Store" or "Windows Phone" apps.
|
include support for either "Windows Store" or "Windows Phone" apps.
|
||||||
"Express" versions marked as supporting "Windows Desktop" development
|
"Express" versions marked as supporting "Windows Desktop" development
|
||||||
typically do not include support for creating WinRT apps, to note.
|
typically do not include support for creating WinRT apps, to note.
|
||||||
(The "Community" editions of Visual C++ do, however, support both
|
(The "Community" editions of Visual C++ do, however, support both
|
||||||
desktop/Win32 and WinRT development).
|
desktop/Win32 and WinRT development).
|
||||||
- Visual C++ 2012 can only build apps that target versions 8.0 of Windows,
|
- Visual C++ 2012 can only build apps that target versions 8.0 of Windows,
|
||||||
or Windows Phone. 8.0-targetted apps will run on devices running 8.1
|
or Windows Phone. 8.0-targetted apps will run on devices running 8.1
|
||||||
editions of Windows, however they will not be able to take advantage of
|
editions of Windows, however they will not be able to take advantage of
|
||||||
8.1-specific features.
|
8.1-specific features.
|
||||||
- Visual C++ 2013 cannot create app projects that target Windows 8.0.
|
- Visual C++ 2013 cannot create app projects that target Windows 8.0.
|
||||||
Visual C++ 2013 Update 4, can create app projects for Windows Phone 8.0,
|
Visual C++ 2013 Update 4, can create app projects for Windows Phone 8.0,
|
||||||
Windows Phone 8.1, and Windows 8.1, but not Windows 8.0. An optional
|
Windows Phone 8.1, and Windows 8.1, but not Windows 8.0. An optional
|
||||||
Visual Studio add-in, "Tools for Maintaining Store apps for Windows 8",
|
Visual Studio add-in, "Tools for Maintaining Store apps for Windows 8",
|
||||||
allows Visual C++ 2013 to load and build Windows 8.0 projects that were
|
allows Visual C++ 2013 to load and build Windows 8.0 projects that were
|
||||||
created with Visual C++ 2012, so long as Visual C++ 2012 is installed
|
created with Visual C++ 2012, so long as Visual C++ 2012 is installed
|
||||||
on the same machine. More details on targeting different versions of
|
on the same machine. More details on targeting different versions of
|
||||||
Windows can found at the following web pages:
|
Windows can found at the following web pages:
|
||||||
- [Develop apps by using Visual Studio 2013](http://msdn.microsoft.com/en-us/library/windows/apps/br211384.aspx)
|
- [Develop apps by using Visual Studio 2013](http://msdn.microsoft.com/en-us/library/windows/apps/br211384.aspx)
|
||||||
- [To add the Tools for Maintaining Store apps for Windows 8](http://msdn.microsoft.com/en-us/library/windows/apps/dn263114.aspx#AddMaintenanceTools)
|
- [To add the Tools for Maintaining Store apps for Windows 8](http://msdn.microsoft.com/en-us/library/windows/apps/dn263114.aspx#AddMaintenanceTools)
|
||||||
* A valid Microsoft account - This requirement is not imposed by SDL, but
|
* A valid Microsoft account - This requirement is not imposed by SDL, but
|
||||||
rather by Microsoft's Visual C++ toolchain. This is required to launch or
|
rather by Microsoft's Visual C++ toolchain. This is required to launch or
|
||||||
debug apps.
|
debug apps.
|
||||||
|
|
||||||
|
|
||||||
Status
|
Status
|
||||||
------
|
------
|
||||||
|
|
||||||
Here is a rough list of what works, and what doens't:
|
Here is a rough list of what works, and what doens't:
|
||||||
|
|
||||||
* What works:
|
* What works:
|
||||||
* compilation via Visual C++ 2012 through 2015
|
* compilation via Visual C++ 2012 through 2015
|
||||||
* compile-time platform detection for SDL programs. The C/C++ #define,
|
* compile-time platform detection for SDL programs. The C/C++ #define,
|
||||||
`__WINRT__`, will be set to 1 (by SDL) when compiling for WinRT.
|
`__WINRT__`, will be set to 1 (by SDL) when compiling for WinRT.
|
||||||
* GPU-accelerated 2D rendering, via SDL_Renderer.
|
* GPU-accelerated 2D rendering, via SDL_Renderer.
|
||||||
* OpenGL ES 2, via the ANGLE library (included separately from SDL)
|
* OpenGL ES 2, via the ANGLE library (included separately from SDL)
|
||||||
* software rendering, via either SDL_Surface (optionally in conjunction with
|
* software rendering, via either SDL_Surface (optionally in conjunction with
|
||||||
SDL_GetWindowSurface() and SDL_UpdateWindowSurface()) or via the
|
SDL_GetWindowSurface() and SDL_UpdateWindowSurface()) or via the
|
||||||
SDL_Renderer APIs
|
SDL_Renderer APIs
|
||||||
* threads
|
* threads
|
||||||
* timers (via SDL_GetTicks(), SDL_AddTimer(), SDL_GetPerformanceCounter(),
|
* timers (via SDL_GetTicks(), SDL_AddTimer(), SDL_GetPerformanceCounter(),
|
||||||
SDL_GetPerformanceFrequency(), etc.)
|
SDL_GetPerformanceFrequency(), etc.)
|
||||||
* file I/O via SDL_RWops
|
* file I/O via SDL_RWops
|
||||||
* mouse input (unsupported on Windows Phone)
|
* mouse input (unsupported on Windows Phone)
|
||||||
* audio, via a modified version of SDL's XAudio2 backend
|
* audio, via a modified version of SDL's XAudio2 backend
|
||||||
* .DLL file loading. Libraries *MUST* be packaged inside applications. Loading
|
* .DLL file loading. Libraries *MUST* be packaged inside applications. Loading
|
||||||
anything outside of the app is not supported.
|
anything outside of the app is not supported.
|
||||||
* system path retrieval via SDL's filesystem APIs
|
* system path retrieval via SDL's filesystem APIs
|
||||||
* game controllers. Support is provided via the SDL_Joystick and
|
* game controllers. Support is provided via the SDL_Joystick and
|
||||||
SDL_GameController APIs, and is backed by Microsoft's XInput API.
|
SDL_GameController APIs, and is backed by Microsoft's XInput API.
|
||||||
* multi-touch input
|
* multi-touch input
|
||||||
* app events. SDL_APP_WILLENTER* and SDL_APP_DIDENTER* events get sent out as
|
* app events. SDL_APP_WILLENTER* and SDL_APP_DIDENTER* events get sent out as
|
||||||
appropriate.
|
appropriate.
|
||||||
* window events
|
* window events
|
||||||
* using Direct3D 11.x APIs outside of SDL. Non-XAML / Direct3D-only apps can
|
* using Direct3D 11.x APIs outside of SDL. Non-XAML / Direct3D-only apps can
|
||||||
choose to render content directly via Direct3D, using SDL to manage the
|
choose to render content directly via Direct3D, using SDL to manage the
|
||||||
internal WinRT window, as well as input and audio. (Use
|
internal WinRT window, as well as input and audio. (Use
|
||||||
SDL_GetWindowWMInfo() to get the WinRT 'CoreWindow', and pass it into
|
SDL_GetWindowWMInfo() to get the WinRT 'CoreWindow', and pass it into
|
||||||
IDXGIFactory2::CreateSwapChainForCoreWindow() as appropriate.)
|
IDXGIFactory2::CreateSwapChainForCoreWindow() as appropriate.)
|
||||||
|
|
||||||
* What partially works:
|
* What partially works:
|
||||||
* keyboard input. Most of WinRT's documented virtual keys are supported, as
|
* keyboard input. Most of WinRT's documented virtual keys are supported, as
|
||||||
well as many keys with documented hardware scancodes. Converting
|
well as many keys with documented hardware scancodes. Converting
|
||||||
SDL_Scancodes to or from SDL_Keycodes may not work, due to missing APIs
|
SDL_Scancodes to or from SDL_Keycodes may not work, due to missing APIs
|
||||||
(MapVirualKey()) in Microsoft's Windows Store / UWP APIs.
|
(MapVirualKey()) in Microsoft's Windows Store / UWP APIs.
|
||||||
* SDLmain. WinRT uses a different signature for each app's main() function.
|
* SDLmain. WinRT uses a different signature for each app's main() function.
|
||||||
SDL-based apps that use this port must compile in SDL_winrt_main_NonXAML.cpp
|
SDL-based apps that use this port must compile in SDL_winrt_main_NonXAML.cpp
|
||||||
(in `SDL\src\main\winrt\`) directly in order for their C-style main()
|
(in `SDL\src\main\winrt\`) directly in order for their C-style main()
|
||||||
functions to be called.
|
functions to be called.
|
||||||
|
|
||||||
* What doesn't work:
|
* What doesn't work:
|
||||||
* compilation with anything other than Visual C++
|
* compilation with anything other than Visual C++
|
||||||
* programmatically-created custom cursors. These don't appear to be supported
|
* programmatically-created custom cursors. These don't appear to be supported
|
||||||
by WinRT. Different OS-provided cursors can, however, be created via
|
by WinRT. Different OS-provided cursors can, however, be created via
|
||||||
SDL_CreateSystemCursor() (unsupported on Windows Phone)
|
SDL_CreateSystemCursor() (unsupported on Windows Phone)
|
||||||
* SDL_WarpMouseInWindow() or SDL_WarpMouseGlobal(). This are not currently
|
* SDL_WarpMouseInWindow() or SDL_WarpMouseGlobal(). This are not currently
|
||||||
supported by WinRT itself.
|
supported by WinRT itself.
|
||||||
* joysticks and game controllers that aren't supported by Microsoft's XInput
|
* joysticks and game controllers that aren't supported by Microsoft's XInput
|
||||||
API.
|
API.
|
||||||
* turning off VSync when rendering on Windows Phone. Attempts to turn VSync
|
* turning off VSync when rendering on Windows Phone. Attempts to turn VSync
|
||||||
off on Windows Phone result either in Direct3D not drawing anything, or it
|
off on Windows Phone result either in Direct3D not drawing anything, or it
|
||||||
forcing VSync back on. As such, SDL_RENDERER_PRESENTVSYNC will always get
|
forcing VSync back on. As such, SDL_RENDERER_PRESENTVSYNC will always get
|
||||||
turned-on on Windows Phone. This limitation is not present in non-Phone
|
turned-on on Windows Phone. This limitation is not present in non-Phone
|
||||||
WinRT (such as Windows 8.x), where turning off VSync appears to work.
|
WinRT (such as Windows 8.x), where turning off VSync appears to work.
|
||||||
* probably anything else that's not listed as supported
|
* probably anything else that's not listed as supported
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
Upgrade Notes
|
Upgrade Notes
|
||||||
-------------
|
-------------
|
||||||
|
|
||||||
#### SDL_GetPrefPath() usage when upgrading WinRT apps from SDL 2.0.3
|
#### SDL_GetPrefPath() usage when upgrading WinRT apps from SDL 2.0.3
|
||||||
|
|
||||||
SDL 2.0.4 fixes two bugs found in the WinRT version of SDL_GetPrefPath().
|
SDL 2.0.4 fixes two bugs found in the WinRT version of SDL_GetPrefPath().
|
||||||
The fixes may affect older, SDL 2.0.3-based apps' save data. Please note
|
The fixes may affect older, SDL 2.0.3-based apps' save data. Please note
|
||||||
that these changes only apply to SDL-based WinRT apps, and not to apps for
|
that these changes only apply to SDL-based WinRT apps, and not to apps for
|
||||||
any other platform.
|
any other platform.
|
||||||
|
|
||||||
1. SDL_GetPrefPath() would return an invalid path, one in which the path's
|
1. SDL_GetPrefPath() would return an invalid path, one in which the path's
|
||||||
directory had not been created. Attempts to create files there
|
directory had not been created. Attempts to create files there
|
||||||
(via fopen(), for example), would fail, unless that directory was
|
(via fopen(), for example), would fail, unless that directory was
|
||||||
explicitly created beforehand.
|
explicitly created beforehand.
|
||||||
|
|
||||||
2. SDL_GetPrefPath(), for non-WinPhone-based apps, would return a path inside
|
2. SDL_GetPrefPath(), for non-WinPhone-based apps, would return a path inside
|
||||||
a WinRT 'Roaming' folder, the contents of which get automatically
|
a WinRT 'Roaming' folder, the contents of which get automatically
|
||||||
synchronized across multiple devices. This process can occur while an
|
synchronized across multiple devices. This process can occur while an
|
||||||
application runs, and can cause existing save-data to be overwritten
|
application runs, and can cause existing save-data to be overwritten
|
||||||
at unexpected times, with data from other devices. (Windows Phone apps
|
at unexpected times, with data from other devices. (Windows Phone apps
|
||||||
written with SDL 2.0.3 did not utilize a Roaming folder, due to API
|
written with SDL 2.0.3 did not utilize a Roaming folder, due to API
|
||||||
restrictions in Windows Phone 8.0).
|
restrictions in Windows Phone 8.0).
|
||||||
|
|
||||||
|
|
||||||
SDL_GetPrefPath(), starting with SDL 2.0.4, addresses these by:
|
SDL_GetPrefPath(), starting with SDL 2.0.4, addresses these by:
|
||||||
|
|
||||||
1. making sure that SDL_GetPrefPath() returns a directory in which data
|
1. making sure that SDL_GetPrefPath() returns a directory in which data
|
||||||
can be written to immediately, without first needing to create directories.
|
can be written to immediately, without first needing to create directories.
|
||||||
|
|
||||||
2. basing SDL_GetPrefPath() off of a different, non-Roaming folder, the
|
2. basing SDL_GetPrefPath() off of a different, non-Roaming folder, the
|
||||||
contents of which do not automatically get synchronized across devices
|
contents of which do not automatically get synchronized across devices
|
||||||
(and which require less work to use safely, in terms of data integrity).
|
(and which require less work to use safely, in terms of data integrity).
|
||||||
|
|
||||||
Apps that wish to get their Roaming folder's path can do so either by using
|
Apps that wish to get their Roaming folder's path can do so either by using
|
||||||
SDL_WinRTGetFSPathUTF8(), SDL_WinRTGetFSPathUNICODE() (which returns a
|
SDL_WinRTGetFSPathUTF8(), SDL_WinRTGetFSPathUNICODE() (which returns a
|
||||||
UCS-2/wide-char string), or directly through the WinRT class,
|
UCS-2/wide-char string), or directly through the WinRT class,
|
||||||
Windows.Storage.ApplicationData.
|
Windows.Storage.ApplicationData.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
Setup, High-Level Steps
|
Setup, High-Level Steps
|
||||||
-----------------------
|
-----------------------
|
||||||
|
|
||||||
The steps for setting up a project for an SDL/WinRT app looks like the
|
The steps for setting up a project for an SDL/WinRT app looks like the
|
||||||
following, at a high-level:
|
following, at a high-level:
|
||||||
|
|
||||||
1. create a new Visual C++ project using Microsoft's template for a,
|
1. create a new Visual C++ project using Microsoft's template for a,
|
||||||
"Direct3D App".
|
"Direct3D App".
|
||||||
2. remove most of the files from the project.
|
2. remove most of the files from the project.
|
||||||
3. make your app's project directly reference SDL/WinRT's own Visual C++
|
3. make your app's project directly reference SDL/WinRT's own Visual C++
|
||||||
project file, via use of Visual C++'s "References" dialog. This will setup
|
project file, via use of Visual C++'s "References" dialog. This will setup
|
||||||
the linker, and will copy SDL's .dll files to your app's final output.
|
the linker, and will copy SDL's .dll files to your app's final output.
|
||||||
4. adjust your app's build settings, at minimum, telling it where to find SDL's
|
4. adjust your app's build settings, at minimum, telling it where to find SDL's
|
||||||
header files.
|
header files.
|
||||||
5. add files that contains a WinRT-appropriate main function, along with some
|
5. add files that contains a WinRT-appropriate main function, along with some
|
||||||
data to make sure mouse-cursor-hiding (via SDL_ShowCursor(SDL_DISABLE) calls)
|
data to make sure mouse-cursor-hiding (via SDL_ShowCursor(SDL_DISABLE) calls)
|
||||||
work properly.
|
work properly.
|
||||||
6. add SDL-specific app code.
|
6. add SDL-specific app code.
|
||||||
7. build and run your app.
|
7. build and run your app.
|
||||||
|
|
||||||
|
|
||||||
Setup, Detailed Steps
|
Setup, Detailed Steps
|
||||||
---------------------
|
---------------------
|
||||||
|
|
||||||
### 1. Create a new project ###
|
### 1. Create a new project ###
|
||||||
|
|
||||||
Create a new project using one of Visual C++'s templates for a plain, non-XAML,
|
Create a new project using one of Visual C++'s templates for a plain, non-XAML,
|
||||||
"Direct3D App" (XAML support for SDL/WinRT is not yet ready for use). If you
|
"Direct3D App" (XAML support for SDL/WinRT is not yet ready for use). If you
|
||||||
don't see one of these templates, in Visual C++'s 'New Project' dialog, try
|
don't see one of these templates, in Visual C++'s 'New Project' dialog, try
|
||||||
using the textbox titled, 'Search Installed Templates' to look for one.
|
using the textbox titled, 'Search Installed Templates' to look for one.
|
||||||
|
|
||||||
|
|
||||||
### 2. Remove unneeded files from the project ###
|
### 2. Remove unneeded files from the project ###
|
||||||
|
|
||||||
In the new project, delete any file that has one of the following extensions:
|
In the new project, delete any file that has one of the following extensions:
|
||||||
|
|
||||||
- .cpp
|
- .cpp
|
||||||
- .h
|
- .h
|
||||||
- .hlsl
|
- .hlsl
|
||||||
|
|
||||||
When you are done, you should be left with a few files, each of which will be a
|
When you are done, you should be left with a few files, each of which will be a
|
||||||
necessary part of your app's project. These files will consist of:
|
necessary part of your app's project. These files will consist of:
|
||||||
|
|
||||||
- an .appxmanifest file, which contains metadata on your WinRT app. This is
|
- an .appxmanifest file, which contains metadata on your WinRT app. This is
|
||||||
similar to an Info.plist file on iOS, or an AndroidManifest.xml on Android.
|
similar to an Info.plist file on iOS, or an AndroidManifest.xml on Android.
|
||||||
- a few .png files, one of which is a splash screen (displayed when your app
|
- a few .png files, one of which is a splash screen (displayed when your app
|
||||||
launches), others are app icons.
|
launches), others are app icons.
|
||||||
- a .pfx file, used for code signing purposes.
|
- a .pfx file, used for code signing purposes.
|
||||||
|
|
||||||
|
|
||||||
### 3. Add references to SDL's project files ###
|
### 3. Add references to SDL's project files ###
|
||||||
|
|
||||||
SDL/WinRT can be built in multiple variations, spanning across three different
|
SDL/WinRT can be built in multiple variations, spanning across three different
|
||||||
CPU architectures (x86, x64, and ARM) and two different configurations
|
CPU architectures (x86, x64, and ARM) and two different configurations
|
||||||
(Debug and Release). WinRT and Visual C++ do not currently provide a means
|
(Debug and Release). WinRT and Visual C++ do not currently provide a means
|
||||||
for combining multiple variations of one library into a single file.
|
for combining multiple variations of one library into a single file.
|
||||||
Furthermore, it does not provide an easy means for copying pre-built .dll files
|
Furthermore, it does not provide an easy means for copying pre-built .dll files
|
||||||
into your app's final output (via Post-Build steps, for example). It does,
|
into your app's final output (via Post-Build steps, for example). It does,
|
||||||
however, provide a system whereby an app can reference the MSVC projects of
|
however, provide a system whereby an app can reference the MSVC projects of
|
||||||
libraries such that, when the app is built:
|
libraries such that, when the app is built:
|
||||||
|
|
||||||
1. each library gets built for the appropriate CPU architecture(s) and WinRT
|
1. each library gets built for the appropriate CPU architecture(s) and WinRT
|
||||||
platform(s).
|
platform(s).
|
||||||
2. each library's output, such as .dll files, get copied to the app's build
|
2. each library's output, such as .dll files, get copied to the app's build
|
||||||
output.
|
output.
|
||||||
|
|
||||||
To set this up for SDL/WinRT, you'll need to run through the following steps:
|
To set this up for SDL/WinRT, you'll need to run through the following steps:
|
||||||
|
|
||||||
1. open up the Solution Explorer inside Visual C++ (under the "View" menu, then
|
1. open up the Solution Explorer inside Visual C++ (under the "View" menu, then
|
||||||
"Solution Explorer")
|
"Solution Explorer")
|
||||||
2. right click on your app's solution.
|
2. right click on your app's solution.
|
||||||
3. navigate to "Add", then to "Existing Project..."
|
3. navigate to "Add", then to "Existing Project..."
|
||||||
4. find SDL/WinRT's Visual C++ project file and open it. Different project
|
4. find SDL/WinRT's Visual C++ project file and open it. Different project
|
||||||
files exist for different WinRT platforms. All of them are in SDL's
|
files exist for different WinRT platforms. All of them are in SDL's
|
||||||
source distribution, in the following directories:
|
source distribution, in the following directories:
|
||||||
* `VisualC-WinRT/UWP_VS2015/` - for Windows 10 / UWP apps
|
* `VisualC-WinRT/UWP_VS2015/` - for Windows 10 / UWP apps
|
||||||
* `VisualC-WinRT/WinPhone81_VS2013/` - for Windows Phone 8.1 apps
|
* `VisualC-WinRT/WinPhone81_VS2013/` - for Windows Phone 8.1 apps
|
||||||
* `VisualC-WinRT/WinRT80_VS2012/` - for Windows 8.0 apps
|
* `VisualC-WinRT/WinRT80_VS2012/` - for Windows 8.0 apps
|
||||||
* `VisualC-WinRT/WinRT81_VS2013/` - for Windows 8.1 apps
|
* `VisualC-WinRT/WinRT81_VS2013/` - for Windows 8.1 apps
|
||||||
5. once the project has been added, right-click on your app's project and
|
5. once the project has been added, right-click on your app's project and
|
||||||
select, "References..."
|
select, "References..."
|
||||||
6. click on the button titled, "Add New Reference..."
|
6. click on the button titled, "Add New Reference..."
|
||||||
7. check the box next to SDL
|
7. check the box next to SDL
|
||||||
8. click OK to close the dialog
|
8. click OK to close the dialog
|
||||||
9. SDL will now show up in the list of references. Click OK to close that
|
9. SDL will now show up in the list of references. Click OK to close that
|
||||||
dialog.
|
dialog.
|
||||||
|
|
||||||
Your project is now linked to SDL's project, insofar that when the app is
|
Your project is now linked to SDL's project, insofar that when the app is
|
||||||
built, SDL will be built as well, with its build output getting included with
|
built, SDL will be built as well, with its build output getting included with
|
||||||
your app.
|
your app.
|
||||||
|
|
||||||
|
|
||||||
### 4. Adjust Your App's Build Settings ###
|
### 4. Adjust Your App's Build Settings ###
|
||||||
|
|
||||||
Some build settings need to be changed in your app's project. This guide will
|
Some build settings need to be changed in your app's project. This guide will
|
||||||
outline the following:
|
outline the following:
|
||||||
|
|
||||||
- making sure that the compiler knows where to find SDL's header files
|
- making sure that the compiler knows where to find SDL's header files
|
||||||
- **Optional for C++, but NECESSARY for compiling C code:** telling the
|
- **Optional for C++, but NECESSARY for compiling C code:** telling the
|
||||||
compiler not to use Microsoft's C++ extensions for WinRT development.
|
compiler not to use Microsoft's C++ extensions for WinRT development.
|
||||||
- **Optional:** telling the compiler not generate errors due to missing
|
- **Optional:** telling the compiler not generate errors due to missing
|
||||||
precompiled header files.
|
precompiled header files.
|
||||||
|
|
||||||
To change these settings:
|
To change these settings:
|
||||||
|
|
||||||
1. right-click on the project
|
1. right-click on the project
|
||||||
2. choose "Properties"
|
2. choose "Properties"
|
||||||
3. in the drop-down box next to "Configuration", choose, "All Configurations"
|
3. in the drop-down box next to "Configuration", choose, "All Configurations"
|
||||||
4. in the drop-down box next to "Platform", choose, "All Platforms"
|
4. in the drop-down box next to "Platform", choose, "All Platforms"
|
||||||
5. in the left-hand list, expand the "C/C++" section
|
5. in the left-hand list, expand the "C/C++" section
|
||||||
6. select "General"
|
6. select "General"
|
||||||
7. edit the "Additional Include Directories" setting, and add a path to SDL's
|
7. edit the "Additional Include Directories" setting, and add a path to SDL's
|
||||||
"include" directory
|
"include" directory
|
||||||
8. **Optional: to enable compilation of C code:** change the setting for
|
8. **Optional: to enable compilation of C code:** change the setting for
|
||||||
"Consume Windows Runtime Extension" from "Yes (/ZW)" to "No". If you're
|
"Consume Windows Runtime Extension" from "Yes (/ZW)" to "No". If you're
|
||||||
working with a completely C++ based project, this step can usually be
|
working with a completely C++ based project, this step can usually be
|
||||||
omitted.
|
omitted.
|
||||||
9. **Optional: to disable precompiled headers (which can produce
|
9. **Optional: to disable precompiled headers (which can produce
|
||||||
'stdafx.h'-related build errors, if setup incorrectly:** in the left-hand
|
'stdafx.h'-related build errors, if setup incorrectly:** in the left-hand
|
||||||
list, select "Precompiled Headers", then change the setting for "Precompiled
|
list, select "Precompiled Headers", then change the setting for "Precompiled
|
||||||
Header" from "Use (/Yu)" to "Not Using Precompiled Headers".
|
Header" from "Use (/Yu)" to "Not Using Precompiled Headers".
|
||||||
10. close the dialog, saving settings, by clicking the "OK" button
|
10. close the dialog, saving settings, by clicking the "OK" button
|
||||||
|
|
||||||
|
|
||||||
### 5. Add a WinRT-appropriate main function, and a blank-cursor image, to the app. ###
|
### 5. Add a WinRT-appropriate main function, and a blank-cursor image, to the app. ###
|
||||||
|
|
||||||
A few files should be included directly in your app's MSVC project, specifically:
|
A few files should be included directly in your app's MSVC project, specifically:
|
||||||
1. a WinRT-appropriate main function (which is different than main() functions on
|
1. a WinRT-appropriate main function (which is different than main() functions on
|
||||||
other platforms)
|
other platforms)
|
||||||
2. a Win32-style cursor resource, used by SDL_ShowCursor() to hide the mouse cursor
|
2. a Win32-style cursor resource, used by SDL_ShowCursor() to hide the mouse cursor
|
||||||
(if and when the app needs to do so). *If this cursor resource is not
|
(if and when the app needs to do so). *If this cursor resource is not
|
||||||
included, mouse-position reporting may fail if and when the cursor is
|
included, mouse-position reporting may fail if and when the cursor is
|
||||||
hidden, due to possible bugs/design-oddities in Windows itself.*
|
hidden, due to possible bugs/design-oddities in Windows itself.*
|
||||||
|
|
||||||
To include these files:
|
To include these files:
|
||||||
|
|
||||||
1. right-click on your project (again, in Visual C++'s Solution Explorer),
|
1. right-click on your project (again, in Visual C++'s Solution Explorer),
|
||||||
navigate to "Add", then choose "Existing Item...".
|
navigate to "Add", then choose "Existing Item...".
|
||||||
2. navigate to the directory containing SDL's source code, then into its
|
2. navigate to the directory containing SDL's source code, then into its
|
||||||
subdirectory, 'src/main/winrt/'. Select, then add, the following files:
|
subdirectory, 'src/main/winrt/'. Select, then add, the following files:
|
||||||
- `SDL_winrt_main_NonXAML.cpp`
|
- `SDL_winrt_main_NonXAML.cpp`
|
||||||
- `SDL2-WinRTResources.rc`
|
- `SDL2-WinRTResources.rc`
|
||||||
- `SDL2-WinRTResource_BlankCursor.cur`
|
- `SDL2-WinRTResource_BlankCursor.cur`
|
||||||
3. right-click on the file `SDL_winrt_main_NonXAML.cpp` (as listed in your
|
3. right-click on the file `SDL_winrt_main_NonXAML.cpp` (as listed in your
|
||||||
project), then click on "Properties...".
|
project), then click on "Properties...".
|
||||||
4. in the drop-down box next to "Configuration", choose, "All Configurations"
|
4. in the drop-down box next to "Configuration", choose, "All Configurations"
|
||||||
5. in the drop-down box next to "Platform", choose, "All Platforms"
|
5. in the drop-down box next to "Platform", choose, "All Platforms"
|
||||||
6. in the left-hand list, click on "C/C++"
|
6. in the left-hand list, click on "C/C++"
|
||||||
7. change the setting for "Consume Windows Runtime Extension" to "Yes (/ZW)".
|
7. change the setting for "Consume Windows Runtime Extension" to "Yes (/ZW)".
|
||||||
8. click the OK button. This will close the dialog.
|
8. click the OK button. This will close the dialog.
|
||||||
|
|
||||||
|
|
||||||
**NOTE: C++/CX compilation is currently required in at least one file of your
|
**NOTE: C++/CX compilation is currently required in at least one file of your
|
||||||
app's project. This is to make sure that Visual C++'s linker builds a 'Windows
|
app's project. This is to make sure that Visual C++'s linker builds a 'Windows
|
||||||
Metadata' file (.winmd) for your app. Not doing so can lead to build errors.**
|
Metadata' file (.winmd) for your app. Not doing so can lead to build errors.**
|
||||||
|
|
||||||
|
|
||||||
### 6. Add app code and assets ###
|
### 6. Add app code and assets ###
|
||||||
|
|
||||||
At this point, you can add in SDL-specific source code. Be sure to include a
|
At this point, you can add in SDL-specific source code. Be sure to include a
|
||||||
C-style main function (ie: `int main(int argc, char *argv[])`). From there you
|
C-style main function (ie: `int main(int argc, char *argv[])`). From there you
|
||||||
should be able to create a single `SDL_Window` (WinRT apps can only have one
|
should be able to create a single `SDL_Window` (WinRT apps can only have one
|
||||||
window, at present), as well as an `SDL_Renderer`. Direct3D will be used to
|
window, at present), as well as an `SDL_Renderer`. Direct3D will be used to
|
||||||
draw content. Events are received via SDL's usual event functions
|
draw content. Events are received via SDL's usual event functions
|
||||||
(`SDL_PollEvent`, etc.) If you have a set of existing source files and assets,
|
(`SDL_PollEvent`, etc.) If you have a set of existing source files and assets,
|
||||||
you can start adding them to the project now. If not, or if you would like to
|
you can start adding them to the project now. If not, or if you would like to
|
||||||
make sure that you're setup correctly, some short and simple sample code is
|
make sure that you're setup correctly, some short and simple sample code is
|
||||||
provided below.
|
provided below.
|
||||||
|
|
||||||
|
|
||||||
#### 6.A. ... when creating a new app ####
|
#### 6.A. ... when creating a new app ####
|
||||||
|
|
||||||
If you are creating a new app (rather than porting an existing SDL-based app),
|
If you are creating a new app (rather than porting an existing SDL-based app),
|
||||||
or if you would just like a simple app to test SDL/WinRT with before trying to
|
or if you would just like a simple app to test SDL/WinRT with before trying to
|
||||||
get existing code working, some working SDL/WinRT code is provided below. To
|
get existing code working, some working SDL/WinRT code is provided below. To
|
||||||
set this up:
|
set this up:
|
||||||
|
|
||||||
1. right click on your app's project
|
1. right click on your app's project
|
||||||
2. select Add, then New Item. An "Add New Item" dialog will show up.
|
2. select Add, then New Item. An "Add New Item" dialog will show up.
|
||||||
3. from the left-hand list, choose "Visual C++"
|
3. from the left-hand list, choose "Visual C++"
|
||||||
4. from the middle/main list, choose "C++ File (.cpp)"
|
4. from the middle/main list, choose "C++ File (.cpp)"
|
||||||
5. near the bottom of the dialog, next to "Name:", type in a name for your
|
5. near the bottom of the dialog, next to "Name:", type in a name for your
|
||||||
source file, such as, "main.cpp".
|
source file, such as, "main.cpp".
|
||||||
6. click on the Add button. This will close the dialog, add the new file to
|
6. click on the Add button. This will close the dialog, add the new file to
|
||||||
your project, and open the file in Visual C++'s text editor.
|
your project, and open the file in Visual C++'s text editor.
|
||||||
7. Copy and paste the following code into the new file, then save it.
|
7. Copy and paste the following code into the new file, then save it.
|
||||||
|
|
||||||
|
|
||||||
#include <SDL.h>
|
#include <SDL.h>
|
||||||
|
|
||||||
int main(int argc, char **argv)
|
int main(int argc, char **argv)
|
||||||
{
|
{
|
||||||
SDL_DisplayMode mode;
|
SDL_DisplayMode mode;
|
||||||
SDL_Window * window = NULL;
|
SDL_Window * window = NULL;
|
||||||
SDL_Renderer * renderer = NULL;
|
SDL_Renderer * renderer = NULL;
|
||||||
SDL_Event evt;
|
SDL_Event evt;
|
||||||
|
|
||||||
if (SDL_Init(SDL_INIT_VIDEO) != 0) {
|
if (SDL_Init(SDL_INIT_VIDEO) != 0) {
|
||||||
return 1;
|
return 1;
|
||||||
}
|
}
|
||||||
|
|
||||||
if (SDL_GetCurrentDisplayMode(0, &mode) != 0) {
|
if (SDL_GetCurrentDisplayMode(0, &mode) != 0) {
|
||||||
return 1;
|
return 1;
|
||||||
}
|
}
|
||||||
|
|
||||||
if (SDL_CreateWindowAndRenderer(mode.w, mode.h, SDL_WINDOW_FULLSCREEN, &window, &renderer) != 0) {
|
if (SDL_CreateWindowAndRenderer(mode.w, mode.h, SDL_WINDOW_FULLSCREEN, &window, &renderer) != 0) {
|
||||||
return 1;
|
return 1;
|
||||||
}
|
}
|
||||||
|
|
||||||
while (1) {
|
while (1) {
|
||||||
while (SDL_PollEvent(&evt)) {
|
while (SDL_PollEvent(&evt)) {
|
||||||
}
|
}
|
||||||
|
|
||||||
SDL_SetRenderDrawColor(renderer, 0, 255, 0, 255);
|
SDL_SetRenderDrawColor(renderer, 0, 255, 0, 255);
|
||||||
SDL_RenderClear(renderer);
|
SDL_RenderClear(renderer);
|
||||||
SDL_RenderPresent(renderer);
|
SDL_RenderPresent(renderer);
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|
||||||
#### 6.B. Adding code and assets ####
|
#### 6.B. Adding code and assets ####
|
||||||
|
|
||||||
If you have existing code and assets that you'd like to add, you should be able
|
If you have existing code and assets that you'd like to add, you should be able
|
||||||
to add them now. The process for adding a set of files is as such.
|
to add them now. The process for adding a set of files is as such.
|
||||||
|
|
||||||
1. right click on the app's project
|
1. right click on the app's project
|
||||||
2. select Add, then click on "New Item..."
|
2. select Add, then click on "New Item..."
|
||||||
3. open any source, header, or asset files as appropriate. Support for C and
|
3. open any source, header, or asset files as appropriate. Support for C and
|
||||||
C++ is available.
|
C++ is available.
|
||||||
|
|
||||||
Do note that WinRT only supports a subset of the APIs that are available to
|
Do note that WinRT only supports a subset of the APIs that are available to
|
||||||
Win32-based apps. Many portions of the Win32 API and the C runtime are not
|
Win32-based apps. Many portions of the Win32 API and the C runtime are not
|
||||||
available.
|
available.
|
||||||
|
|
||||||
A list of unsupported C APIs can be found at
|
A list of unsupported C APIs can be found at
|
||||||
<http://msdn.microsoft.com/en-us/library/windows/apps/jj606124.aspx>
|
<http://msdn.microsoft.com/en-us/library/windows/apps/jj606124.aspx>
|
||||||
|
|
||||||
General information on using the C runtime in WinRT can be found at
|
General information on using the C runtime in WinRT can be found at
|
||||||
<https://msdn.microsoft.com/en-us/library/hh972425.aspx>
|
<https://msdn.microsoft.com/en-us/library/hh972425.aspx>
|
||||||
|
|
||||||
A list of supported Win32 APIs for WinRT apps can be found at
|
A list of supported Win32 APIs for WinRT apps can be found at
|
||||||
<http://msdn.microsoft.com/en-us/library/windows/apps/br205757.aspx>. To note,
|
<http://msdn.microsoft.com/en-us/library/windows/apps/br205757.aspx>. To note,
|
||||||
the list of supported Win32 APIs for Windows Phone 8.0 is different.
|
the list of supported Win32 APIs for Windows Phone 8.0 is different.
|
||||||
That list can be found at
|
That list can be found at
|
||||||
<http://msdn.microsoft.com/en-us/library/windowsphone/develop/jj662956(v=vs.105).aspx>
|
<http://msdn.microsoft.com/en-us/library/windowsphone/develop/jj662956(v=vs.105).aspx>
|
||||||
|
|
||||||
|
|
||||||
### 7. Build and run your app ###
|
### 7. Build and run your app ###
|
||||||
|
|
||||||
Your app project should now be setup, and you should be ready to build your app.
|
Your app project should now be setup, and you should be ready to build your app.
|
||||||
To run it on the local machine, open the Debug menu and choose "Start
|
To run it on the local machine, open the Debug menu and choose "Start
|
||||||
Debugging". This will build your app, then run your app full-screen. To switch
|
Debugging". This will build your app, then run your app full-screen. To switch
|
||||||
out of your app, press the Windows key. Alternatively, you can choose to run
|
out of your app, press the Windows key. Alternatively, you can choose to run
|
||||||
your app in a window. To do this, before building and running your app, find
|
your app in a window. To do this, before building and running your app, find
|
||||||
the drop-down menu in Visual C++'s toolbar that says, "Local Machine". Expand
|
the drop-down menu in Visual C++'s toolbar that says, "Local Machine". Expand
|
||||||
this by clicking on the arrow on the right side of the list, then click on
|
this by clicking on the arrow on the right side of the list, then click on
|
||||||
Simulator. Once you do that, any time you build and run the app, the app will
|
Simulator. Once you do that, any time you build and run the app, the app will
|
||||||
launch in window, rather than full-screen.
|
launch in window, rather than full-screen.
|
||||||
|
|
||||||
|
|
||||||
#### 7.A. Running apps on older, ARM-based, "Windows RT" devices ####
|
#### 7.A. Running apps on older, ARM-based, "Windows RT" devices ####
|
||||||
|
|
||||||
**These instructions do not include Windows Phone, despite Windows Phone
|
**These instructions do not include Windows Phone, despite Windows Phone
|
||||||
typically running on ARM processors.** They are specifically for devices
|
typically running on ARM processors.** They are specifically for devices
|
||||||
that use the "Windows RT" operating system, which was a modified version of
|
that use the "Windows RT" operating system, which was a modified version of
|
||||||
Windows 8.x that ran primarily on ARM-based tablet computers.
|
Windows 8.x that ran primarily on ARM-based tablet computers.
|
||||||
|
|
||||||
To build and run the app on ARM-based, "Windows RT" devices, you'll need to:
|
To build and run the app on ARM-based, "Windows RT" devices, you'll need to:
|
||||||
|
|
||||||
- install Microsoft's "Remote Debugger" on the device. Visual C++ installs and
|
- install Microsoft's "Remote Debugger" on the device. Visual C++ installs and
|
||||||
debugs ARM-based apps via IP networks.
|
debugs ARM-based apps via IP networks.
|
||||||
- change a few options on the development machine, both to make sure it builds
|
- change a few options on the development machine, both to make sure it builds
|
||||||
for ARM (rather than x86 or x64), and to make sure it knows how to find the
|
for ARM (rather than x86 or x64), and to make sure it knows how to find the
|
||||||
Windows RT device (on the network).
|
Windows RT device (on the network).
|
||||||
|
|
||||||
Microsoft's Remote Debugger can be found at
|
Microsoft's Remote Debugger can be found at
|
||||||
<https://msdn.microsoft.com/en-us/library/hh441469.aspx>. Please note
|
<https://msdn.microsoft.com/en-us/library/hh441469.aspx>. Please note
|
||||||
that separate versions of this debugger exist for different versions of Visual
|
that separate versions of this debugger exist for different versions of Visual
|
||||||
C++, one each for MSVC 2015, 2013, and 2012.
|
C++, one each for MSVC 2015, 2013, and 2012.
|
||||||
|
|
||||||
To setup Visual C++ to launch your app on an ARM device:
|
To setup Visual C++ to launch your app on an ARM device:
|
||||||
|
|
||||||
1. make sure the Remote Debugger is running on your ARM device, and that it's on
|
1. make sure the Remote Debugger is running on your ARM device, and that it's on
|
||||||
the same IP network as your development machine.
|
the same IP network as your development machine.
|
||||||
2. from Visual C++'s toolbar, find a drop-down menu that says, "Win32". Click
|
2. from Visual C++'s toolbar, find a drop-down menu that says, "Win32". Click
|
||||||
it, then change the value to "ARM".
|
it, then change the value to "ARM".
|
||||||
3. make sure Visual C++ knows the hostname or IP address of the ARM device. To
|
3. make sure Visual C++ knows the hostname or IP address of the ARM device. To
|
||||||
do this:
|
do this:
|
||||||
1. open the app project's properties
|
1. open the app project's properties
|
||||||
2. select "Debugging"
|
2. select "Debugging"
|
||||||
3. next to "Machine Name", enter the hostname or IP address of the ARM
|
3. next to "Machine Name", enter the hostname or IP address of the ARM
|
||||||
device
|
device
|
||||||
4. if, and only if, you've turned off authentication in the Remote Debugger,
|
4. if, and only if, you've turned off authentication in the Remote Debugger,
|
||||||
then change the setting for "Require Authentication" to No
|
then change the setting for "Require Authentication" to No
|
||||||
5. click "OK"
|
5. click "OK"
|
||||||
4. build and run the app (from Visual C++). The first time you do this, a
|
4. build and run the app (from Visual C++). The first time you do this, a
|
||||||
prompt will show up on the ARM device, asking for a Microsoft Account. You
|
prompt will show up on the ARM device, asking for a Microsoft Account. You
|
||||||
do, unfortunately, need to log in here, and will need to follow the
|
do, unfortunately, need to log in here, and will need to follow the
|
||||||
subsequent registration steps in order to launch the app. After you do so,
|
subsequent registration steps in order to launch the app. After you do so,
|
||||||
if the app didn't already launch, try relaunching it again from within Visual
|
if the app didn't already launch, try relaunching it again from within Visual
|
||||||
C++.
|
C++.
|
||||||
|
|
||||||
|
|
||||||
Troubleshooting
|
Troubleshooting
|
||||||
---------------
|
---------------
|
||||||
|
|
||||||
#### Build fails with message, "error LNK2038: mismatch detected for 'vccorlib_lib_should_be_specified_before_msvcrt_lib_to_linker'"
|
#### Build fails with message, "error LNK2038: mismatch detected for 'vccorlib_lib_should_be_specified_before_msvcrt_lib_to_linker'"
|
||||||
|
|
||||||
Try adding the following to your linker flags. In MSVC, this can be done by
|
Try adding the following to your linker flags. In MSVC, this can be done by
|
||||||
right-clicking on the app project, navigating to Configuration Properties ->
|
right-clicking on the app project, navigating to Configuration Properties ->
|
||||||
Linker -> Command Line, then adding them to the Additional Options
|
Linker -> Command Line, then adding them to the Additional Options
|
||||||
section.
|
section.
|
||||||
|
|
||||||
* For Release builds / MSVC-Configurations, add:
|
* For Release builds / MSVC-Configurations, add:
|
||||||
|
|
||||||
/nodefaultlib:vccorlib /nodefaultlib:msvcrt vccorlib.lib msvcrt.lib
|
/nodefaultlib:vccorlib /nodefaultlib:msvcrt vccorlib.lib msvcrt.lib
|
||||||
|
|
||||||
* For Debug builds / MSVC-Configurations, add:
|
* For Debug builds / MSVC-Configurations, add:
|
||||||
|
|
||||||
/nodefaultlib:vccorlibd /nodefaultlib:msvcrtd vccorlibd.lib msvcrtd.lib
|
/nodefaultlib:vccorlibd /nodefaultlib:msvcrtd vccorlibd.lib msvcrtd.lib
|
||||||
|
|
||||||
|
|
||||||
#### Mouse-motion events fail to get sent, or SDL_GetMouseState() fails to return updated values
|
#### Mouse-motion events fail to get sent, or SDL_GetMouseState() fails to return updated values
|
||||||
|
|
||||||
This may be caused by a bug in Windows itself, whereby hiding the mouse
|
This may be caused by a bug in Windows itself, whereby hiding the mouse
|
||||||
cursor can cause mouse-position reporting to fail.
|
cursor can cause mouse-position reporting to fail.
|
||||||
|
|
||||||
SDL provides a workaround for this, but it requires that an app links to a
|
SDL provides a workaround for this, but it requires that an app links to a
|
||||||
set of Win32-style cursor image-resource files. A copy of suitable resource
|
set of Win32-style cursor image-resource files. A copy of suitable resource
|
||||||
files can be found in `src/main/winrt/`. Adding them to an app's Visual C++
|
files can be found in `src/main/winrt/`. Adding them to an app's Visual C++
|
||||||
project file should be sufficient to get the app to use them.
|
project file should be sufficient to get the app to use them.
|
||||||
|
|
|
||||||
126
docs/README.md
126
docs/README.md
|
|
@ -1,63 +1,63 @@
|
||||||
Simple DirectMedia Layer {#mainpage}
|
Simple DirectMedia Layer {#mainpage}
|
||||||
========================
|
========================
|
||||||
|
|
||||||
(SDL)
|
(SDL)
|
||||||
|
|
||||||
Version 2.0
|
Version 2.0
|
||||||
|
|
||||||
---
|
---
|
||||||
http://www.libsdl.org/
|
http://www.libsdl.org/
|
||||||
|
|
||||||
Simple DirectMedia Layer is a cross-platform development library designed
|
Simple DirectMedia Layer is a cross-platform development library designed
|
||||||
to provide low level access to audio, keyboard, mouse, joystick, and graphics
|
to provide low level access to audio, keyboard, mouse, joystick, and graphics
|
||||||
hardware via OpenGL and Direct3D. It is used by video playback software,
|
hardware via OpenGL and Direct3D. It is used by video playback software,
|
||||||
emulators, and popular games including Valve's award winning catalog
|
emulators, and popular games including Valve's award winning catalog
|
||||||
and many Humble Bundle games.
|
and many Humble Bundle games.
|
||||||
|
|
||||||
SDL officially supports Windows, Mac OS X, Linux, iOS, and Android.
|
SDL officially supports Windows, Mac OS X, Linux, iOS, and Android.
|
||||||
Support for other platforms may be found in the source code.
|
Support for other platforms may be found in the source code.
|
||||||
|
|
||||||
SDL is written in C, works natively with C++, and there are bindings
|
SDL is written in C, works natively with C++, and there are bindings
|
||||||
available for several other languages, including C# and Python.
|
available for several other languages, including C# and Python.
|
||||||
|
|
||||||
This library is distributed under the zlib license, which can be found
|
This library is distributed under the zlib license, which can be found
|
||||||
in the file "COPYING.txt".
|
in the file "COPYING.txt".
|
||||||
|
|
||||||
The best way to learn how to use SDL is to check out the header files in
|
The best way to learn how to use SDL is to check out the header files in
|
||||||
the "include" subdirectory and the programs in the "test" subdirectory.
|
the "include" subdirectory and the programs in the "test" subdirectory.
|
||||||
The header files and test programs are well commented and always up to date.
|
The header files and test programs are well commented and always up to date.
|
||||||
|
|
||||||
More documentation and FAQs are available online at [the wiki](http://wiki.libsdl.org/)
|
More documentation and FAQs are available online at [the wiki](http://wiki.libsdl.org/)
|
||||||
|
|
||||||
- [Android](README-android.md)
|
- [Android](README-android.md)
|
||||||
- [CMake](README-cmake.md)
|
- [CMake](README-cmake.md)
|
||||||
- [DirectFB](README-directfb.md)
|
- [DirectFB](README-directfb.md)
|
||||||
- [DynAPI](README-dynapi.md)
|
- [DynAPI](README-dynapi.md)
|
||||||
- [Emscripten](README-emscripten.md)
|
- [Emscripten](README-emscripten.md)
|
||||||
- [Gesture](README-gesture.md)
|
- [Gesture](README-gesture.md)
|
||||||
- [Mercurial](README-hg.md)
|
- [Mercurial](README-hg.md)
|
||||||
- [iOS](README-ios.md)
|
- [iOS](README-ios.md)
|
||||||
- [Linux](README-linux.md)
|
- [Linux](README-linux.md)
|
||||||
- [OS X](README-macosx.md)
|
- [OS X](README-macosx.md)
|
||||||
- [Native Client](README-nacl.md)
|
- [Native Client](README-nacl.md)
|
||||||
- [Pandora](README-pandora.md)
|
- [Pandora](README-pandora.md)
|
||||||
- [Supported Platforms](README-platforms.md)
|
- [Supported Platforms](README-platforms.md)
|
||||||
- [Porting information](README-porting.md)
|
- [Porting information](README-porting.md)
|
||||||
- [PSP](README-psp.md)
|
- [PSP](README-psp.md)
|
||||||
- [Raspberry Pi](README-raspberrypi.md)
|
- [Raspberry Pi](README-raspberrypi.md)
|
||||||
- [Touch](README-touch.md)
|
- [Touch](README-touch.md)
|
||||||
- [WinCE](README-wince.md)
|
- [WinCE](README-wince.md)
|
||||||
- [Windows](README-windows.md)
|
- [Windows](README-windows.md)
|
||||||
- [WinRT](README-winrt.md)
|
- [WinRT](README-winrt.md)
|
||||||
|
|
||||||
If you need help with the library, or just want to discuss SDL related
|
If you need help with the library, or just want to discuss SDL related
|
||||||
issues, you can join the [developers mailing list](http://www.libsdl.org/mailing-list.php)
|
issues, you can join the [developers mailing list](http://www.libsdl.org/mailing-list.php)
|
||||||
|
|
||||||
If you want to report bugs or contribute patches, please submit them to
|
If you want to report bugs or contribute patches, please submit them to
|
||||||
[bugzilla](http://bugzilla.libsdl.org/)
|
[bugzilla](http://bugzilla.libsdl.org/)
|
||||||
|
|
||||||
Enjoy!
|
Enjoy!
|
||||||
|
|
||||||
|
|
||||||
Sam Lantinga <mailto:slouken@libsdl.org>
|
Sam Lantinga <mailto:slouken@libsdl.org>
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue