mirror of
https://github.com/libsdl-org/SDL.git
synced 2026-02-06 10:22:17 +08:00
Converted README documentation to DOS text format
This commit is contained in:
Sam Lantinga
@@ -1,4 +1,4 @@
|
||||
Android
|
||||
Android
|
||||
================================================================================
|
||||
|
||||
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
|
||||
approach has suffered from several issues across the different supported
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
DirectFB
|
||||
========
|
||||
========
|
||||
|
||||
Supports:
|
||||
|
||||
|
||||
@@ -1,130 +1,130 @@
|
||||
Dynamic API
|
||||
================================================================================
|
||||
Originally posted by Ryan at:
|
||||
https://plus.google.com/103391075724026391227/posts/TB8UfnDYu4U
|
||||
|
||||
Background:
|
||||
|
||||
- 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.
|
||||
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
|
||||
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
|
||||
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
|
||||
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
|
||||
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.
|
||||
- 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
|
||||
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
|
||||
included), which is inconvenient if you could have had one universal build
|
||||
that works everywhere.
|
||||
- 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
|
||||
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:
|
||||
swapping in a newer SDL to an older game often times can save the day.
|
||||
Static linking stops this dead.
|
||||
|
||||
So here's what we did:
|
||||
|
||||
SDL now has, internally, a table of function pointers. So, this is what SDL_Init
|
||||
now looks like:
|
||||
|
||||
UInt32 SDL_Init(Uint32 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
|
||||
every one of these.
|
||||
|
||||
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
|
||||
like this:
|
||||
|
||||
Uint32 SDL_Init_DEFAULT(Uint32 flags)
|
||||
{
|
||||
SDL_InitDynamicAPI();
|
||||
return jump_table.SDL_Init(flags);
|
||||
}
|
||||
|
||||
SDL_InitDynamicAPI() fills in jump_table with all the actual SDL function
|
||||
pointers, which means that this _DEFAULT function never gets called again.
|
||||
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
|
||||
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:
|
||||
|
||||
export SDL_DYNAMIC_API=/my/actual/libSDL-2.0.so.0
|
||||
./MyGameThatIsStaticallyLinkedToSDL2
|
||||
|
||||
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
|
||||
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,
|
||||
and everyone is happy.
|
||||
|
||||
So now:
|
||||
- Developers can statically link SDL, and users can still replace it.
|
||||
(We'd still rather you ship a shared library, though!)
|
||||
- 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,
|
||||
but it'll also just work in the default case.
|
||||
- Developers can ship the same package to everyone (Humble Bundle, GOG, etc),
|
||||
and it'll do the right thing.
|
||||
- End users (and Valve) can update a game's SDL in almost any case,
|
||||
to keep abandoned games running on newer platforms.
|
||||
- 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.
|
||||
|
||||
|
||||
A little more about SDL_InitDynamicAPI():
|
||||
|
||||
Internally, InitAPI does some locking to make sure everything waits until a
|
||||
single thread initializes everything (although even SDL_CreateThread() goes
|
||||
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
|
||||
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
|
||||
calls a single function:
|
||||
|
||||
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
|
||||
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
|
||||
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
|
||||
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.
|
||||
|
||||
The version variable is a failsafe switch.
|
||||
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).
|
||||
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
|
||||
function and loads different, otherwise-incompatible SDL libraries and has the
|
||||
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
|
||||
Steam Client, this isn't a bad option.
|
||||
|
||||
Finally, I'm sure some people are reading this and thinking,
|
||||
"I don't want that overhead in my project!"
|
||||
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
|
||||
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
|
||||
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
|
||||
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.
|
||||
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,
|
||||
everyone will ultimately be able to get what they want, but we've gently
|
||||
nudged everyone towards what we think is the best solution.
|
||||
Dynamic API
|
||||
================================================================================
|
||||
Originally posted by Ryan at:
|
||||
https://plus.google.com/103391075724026391227/posts/TB8UfnDYu4U
|
||||
|
||||
Background:
|
||||
|
||||
- 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.
|
||||
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
|
||||
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
|
||||
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
|
||||
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
|
||||
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.
|
||||
- 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
|
||||
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
|
||||
included), which is inconvenient if you could have had one universal build
|
||||
that works everywhere.
|
||||
- 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
|
||||
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:
|
||||
swapping in a newer SDL to an older game often times can save the day.
|
||||
Static linking stops this dead.
|
||||
|
||||
So here's what we did:
|
||||
|
||||
SDL now has, internally, a table of function pointers. So, this is what SDL_Init
|
||||
now looks like:
|
||||
|
||||
UInt32 SDL_Init(Uint32 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
|
||||
every one of these.
|
||||
|
||||
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
|
||||
like this:
|
||||
|
||||
Uint32 SDL_Init_DEFAULT(Uint32 flags)
|
||||
{
|
||||
SDL_InitDynamicAPI();
|
||||
return jump_table.SDL_Init(flags);
|
||||
}
|
||||
|
||||
SDL_InitDynamicAPI() fills in jump_table with all the actual SDL function
|
||||
pointers, which means that this _DEFAULT function never gets called again.
|
||||
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
|
||||
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:
|
||||
|
||||
export SDL_DYNAMIC_API=/my/actual/libSDL-2.0.so.0
|
||||
./MyGameThatIsStaticallyLinkedToSDL2
|
||||
|
||||
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
|
||||
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,
|
||||
and everyone is happy.
|
||||
|
||||
So now:
|
||||
- Developers can statically link SDL, and users can still replace it.
|
||||
(We'd still rather you ship a shared library, though!)
|
||||
- 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,
|
||||
but it'll also just work in the default case.
|
||||
- Developers can ship the same package to everyone (Humble Bundle, GOG, etc),
|
||||
and it'll do the right thing.
|
||||
- End users (and Valve) can update a game's SDL in almost any case,
|
||||
to keep abandoned games running on newer platforms.
|
||||
- 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.
|
||||
|
||||
|
||||
A little more about SDL_InitDynamicAPI():
|
||||
|
||||
Internally, InitAPI does some locking to make sure everything waits until a
|
||||
single thread initializes everything (although even SDL_CreateThread() goes
|
||||
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
|
||||
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
|
||||
calls a single function:
|
||||
|
||||
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
|
||||
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
|
||||
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
|
||||
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.
|
||||
|
||||
The version variable is a failsafe switch.
|
||||
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).
|
||||
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
|
||||
function and loads different, otherwise-incompatible SDL libraries and has the
|
||||
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
|
||||
Steam Client, this isn't a bad option.
|
||||
|
||||
Finally, I'm sure some people are reading this and thinking,
|
||||
"I don't want that overhead in my project!"
|
||||
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
|
||||
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
|
||||
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
|
||||
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.
|
||||
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,
|
||||
everyone will ultimately be able to get what they want, but we've gently
|
||||
nudged everyone towards what we think is the best solution.
|
||||
|
||||
@@ -1,37 +1,37 @@
|
||||
Emscripten
|
||||
================================================================================
|
||||
|
||||
Build:
|
||||
|
||||
$ mkdir build
|
||||
$ cd build
|
||||
$ emconfigure ../configure --host=asmjs-unknown-emscripten --disable-assembly --disable-threads --enable-cpuinfo=false CFLAGS="-O2"
|
||||
$ emmake make
|
||||
|
||||
Or with cmake:
|
||||
|
||||
$ mkdir build
|
||||
$ cd build
|
||||
$ emcmake cmake ..
|
||||
$ emmake make
|
||||
|
||||
To build one of the tests:
|
||||
|
||||
$ cd test/
|
||||
$ 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
|
||||
|
||||
tests: https://dl.dropboxusercontent.com/u/17360362/SDL2-em/index.html
|
||||
|
||||
Some other SDL2 libraries can be easily built (assuming SDL2 is installed somewhere):
|
||||
|
||||
SDL_mixer (http://www.libsdl.org/projects/SDL_mixer/):
|
||||
|
||||
$ EMCONFIGURE_JS=1 emconfigure ../configure
|
||||
build as usual...
|
||||
|
||||
SDL_gfx (http://cms.ferzkopp.net/index.php/software/13-sdl-gfx):
|
||||
|
||||
$ EMCONFIGURE_JS=1 emconfigure ../configure --disable-mmx
|
||||
build as usual...
|
||||
Emscripten
|
||||
================================================================================
|
||||
|
||||
Build:
|
||||
|
||||
$ mkdir build
|
||||
$ cd build
|
||||
$ emconfigure ../configure --host=asmjs-unknown-emscripten --disable-assembly --disable-threads --enable-cpuinfo=false CFLAGS="-O2"
|
||||
$ emmake make
|
||||
|
||||
Or with cmake:
|
||||
|
||||
$ mkdir build
|
||||
$ cd build
|
||||
$ emcmake cmake ..
|
||||
$ emmake make
|
||||
|
||||
To build one of the tests:
|
||||
|
||||
$ cd test/
|
||||
$ 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
|
||||
|
||||
tests: https://dl.dropboxusercontent.com/u/17360362/SDL2-em/index.html
|
||||
|
||||
Some other SDL2 libraries can be easily built (assuming SDL2 is installed somewhere):
|
||||
|
||||
SDL_mixer (http://www.libsdl.org/projects/SDL_mixer/):
|
||||
|
||||
$ EMCONFIGURE_JS=1 emconfigure ../configure
|
||||
build as usual...
|
||||
|
||||
SDL_gfx (http://cms.ferzkopp.net/index.php/software/13-sdl-gfx):
|
||||
|
||||
$ EMCONFIGURE_JS=1 emconfigure ../configure --disable-mmx
|
||||
build as usual...
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
Mercurial
|
||||
=========
|
||||
|
||||
Mercurial
|
||||
=========
|
||||
|
||||
The latest development version of SDL is available via Mercurial.
|
||||
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
|
||||
|
||||
@@ -1,85 +1,85 @@
|
||||
Linux
|
||||
================================================================================
|
||||
|
||||
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
|
||||
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
|
||||
at runtime, and you won't get a missing library error, at least with the
|
||||
default configuration parameters.
|
||||
|
||||
|
||||
================================================================================
|
||||
Build Dependencies
|
||||
================================================================================
|
||||
|
||||
Ubuntu 13.04, all available features enabled:
|
||||
|
||||
sudo apt-get install build-essential mercurial make cmake autoconf automake \
|
||||
libtool libasound2-dev libpulse-dev libaudio-dev libx11-dev libxext-dev \
|
||||
libxrandr-dev libxcursor-dev libxi-dev libxinerama-dev libxxf86vm-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
|
||||
|
||||
Ubuntu 16.04 can also add "libwayland-dev libxkbcommon-dev wayland-protocols"
|
||||
to that command line for Wayland support.
|
||||
|
||||
Ubuntu 16.10 can also add "libmirclient-dev libxkbcommon-dev" to that command
|
||||
line for Mir support.
|
||||
|
||||
NOTES:
|
||||
- This includes all the audio targets except arts, because Ubuntu pulled the
|
||||
artsc0-dev package, but in theory SDL still supports it.
|
||||
- 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
|
||||
configure script to include DirectFB support. Send patches. :)
|
||||
|
||||
|
||||
================================================================================
|
||||
Joystick does not work
|
||||
================================================================================
|
||||
|
||||
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
|
||||
debug this, start by installing the evtest utility. On Ubuntu/Debian:
|
||||
|
||||
sudo apt-get install evtest
|
||||
|
||||
Then run:
|
||||
|
||||
sudo evtest
|
||||
|
||||
You'll hopefully see your joystick listed along with a name like "/dev/input/eventXX"
|
||||
Now run:
|
||||
|
||||
cat /dev/input/event/XX
|
||||
|
||||
If you get a permission error, you need to set a udev rule to change the mode of
|
||||
your device (see below)
|
||||
|
||||
Also, try:
|
||||
|
||||
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,
|
||||
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
|
||||
like:
|
||||
|
||||
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"
|
||||
|
||||
You can set up similar rules for your device by changing the values listed in
|
||||
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 idProduct
|
||||
|
||||
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
|
||||
to set up a rule such as:
|
||||
|
||||
SUBSYSTEM=="input", ENV{ID_CLASS}=="joystick", ENV{ID_INPUT_JOYSTICK}="1"
|
||||
|
||||
Linux
|
||||
================================================================================
|
||||
|
||||
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
|
||||
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
|
||||
at runtime, and you won't get a missing library error, at least with the
|
||||
default configuration parameters.
|
||||
|
||||
|
||||
================================================================================
|
||||
Build Dependencies
|
||||
================================================================================
|
||||
|
||||
Ubuntu 13.04, all available features enabled:
|
||||
|
||||
sudo apt-get install build-essential mercurial make cmake autoconf automake \
|
||||
libtool libasound2-dev libpulse-dev libaudio-dev libx11-dev libxext-dev \
|
||||
libxrandr-dev libxcursor-dev libxi-dev libxinerama-dev libxxf86vm-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
|
||||
|
||||
Ubuntu 16.04 can also add "libwayland-dev libxkbcommon-dev wayland-protocols"
|
||||
to that command line for Wayland support.
|
||||
|
||||
Ubuntu 16.10 can also add "libmirclient-dev libxkbcommon-dev" to that command
|
||||
line for Mir support.
|
||||
|
||||
NOTES:
|
||||
- This includes all the audio targets except arts, because Ubuntu pulled the
|
||||
artsc0-dev package, but in theory SDL still supports it.
|
||||
- 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
|
||||
configure script to include DirectFB support. Send patches. :)
|
||||
|
||||
|
||||
================================================================================
|
||||
Joystick does not work
|
||||
================================================================================
|
||||
|
||||
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
|
||||
debug this, start by installing the evtest utility. On Ubuntu/Debian:
|
||||
|
||||
sudo apt-get install evtest
|
||||
|
||||
Then run:
|
||||
|
||||
sudo evtest
|
||||
|
||||
You'll hopefully see your joystick listed along with a name like "/dev/input/eventXX"
|
||||
Now run:
|
||||
|
||||
cat /dev/input/event/XX
|
||||
|
||||
If you get a permission error, you need to set a udev rule to change the mode of
|
||||
your device (see below)
|
||||
|
||||
Also, try:
|
||||
|
||||
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,
|
||||
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
|
||||
like:
|
||||
|
||||
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"
|
||||
|
||||
You can set up similar rules for your device by changing the values listed in
|
||||
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 idProduct
|
||||
|
||||
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
|
||||
to set up a rule such as:
|
||||
|
||||
SUBSYSTEM=="input", ENV{ID_CLASS}=="joystick", ENV{ID_INPUT_JOYSTICK}="1"
|
||||
|
||||
|
||||
@@ -1,103 +1,103 @@
|
||||
Native Client
|
||||
================================================================================
|
||||
|
||||
Requirements:
|
||||
|
||||
* Native Client SDK (https://developer.chrome.com/native-client),
|
||||
(tested with Pepper version 33 or higher).
|
||||
|
||||
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
|
||||
platforms. This does not mean it won't work with the other toolchains!
|
||||
|
||||
================================================================================
|
||||
Building SDL for NaCl
|
||||
================================================================================
|
||||
|
||||
Set up the right environment variables (see naclbuild.sh), then configure SDL with:
|
||||
|
||||
configure --host=pnacl --prefix some/install/destination
|
||||
|
||||
Then "make".
|
||||
|
||||
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
|
||||
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
|
||||
you dump them into the SDK path, which is inconvenient).
|
||||
Also provided in test/nacl is the required support file, such as index.html,
|
||||
manifest.json, etc.
|
||||
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),
|
||||
hiding the asynchronous nature of the browser behind the scenes...which is not the
|
||||
same as making it disappear!
|
||||
|
||||
|
||||
================================================================================
|
||||
Running tests
|
||||
================================================================================
|
||||
|
||||
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
|
||||
automates the process and should serve as a guide for users of SDL trying to build
|
||||
their own applications.
|
||||
|
||||
Basic usage:
|
||||
|
||||
./naclbuild.sh path/to/pepper/toolchain (i.e. ~/naclsdk/pepper_35)
|
||||
|
||||
This will build testgles2.c by default.
|
||||
|
||||
If you want to build a different test, for example testrendercopyex.c:
|
||||
|
||||
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
|
||||
script will give you instructions on how to do that with Python).
|
||||
|
||||
================================================================================
|
||||
RWops and nacl_io
|
||||
================================================================================
|
||||
|
||||
SDL_RWops work transparently with nacl_io. Two functions control the mount points:
|
||||
|
||||
int mount(const char* source, const char* target,
|
||||
const char* filesystemtype,
|
||||
unsigned long mountflags, const void *data);
|
||||
int umount(const char *target);
|
||||
|
||||
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:
|
||||
|
||||
umount("/");
|
||||
|
||||
And then mounting a different filesystem at /
|
||||
|
||||
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
|
||||
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
|
||||
a set of challenges of its own, in particular when big file sizes and slow
|
||||
connections are involved.
|
||||
|
||||
For more information on how nacl_io and mount points work, see:
|
||||
|
||||
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
|
||||
|
||||
To be able to save into the directory "/save/" (like backup of game) :
|
||||
|
||||
mount("", "/save", "html5fs", 0, "type=PERSISTENT");
|
||||
|
||||
And add to manifest.json :
|
||||
|
||||
"permissions": [
|
||||
"unlimitedStorage"
|
||||
]
|
||||
|
||||
================================================================================
|
||||
TODO - Known Issues
|
||||
================================================================================
|
||||
* Testing of all systems with a real application (something other than SDL's tests)
|
||||
* Key events don't seem to work properly
|
||||
|
||||
Native Client
|
||||
================================================================================
|
||||
|
||||
Requirements:
|
||||
|
||||
* Native Client SDK (https://developer.chrome.com/native-client),
|
||||
(tested with Pepper version 33 or higher).
|
||||
|
||||
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
|
||||
platforms. This does not mean it won't work with the other toolchains!
|
||||
|
||||
================================================================================
|
||||
Building SDL for NaCl
|
||||
================================================================================
|
||||
|
||||
Set up the right environment variables (see naclbuild.sh), then configure SDL with:
|
||||
|
||||
configure --host=pnacl --prefix some/install/destination
|
||||
|
||||
Then "make".
|
||||
|
||||
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
|
||||
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
|
||||
you dump them into the SDK path, which is inconvenient).
|
||||
Also provided in test/nacl is the required support file, such as index.html,
|
||||
manifest.json, etc.
|
||||
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),
|
||||
hiding the asynchronous nature of the browser behind the scenes...which is not the
|
||||
same as making it disappear!
|
||||
|
||||
|
||||
================================================================================
|
||||
Running tests
|
||||
================================================================================
|
||||
|
||||
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
|
||||
automates the process and should serve as a guide for users of SDL trying to build
|
||||
their own applications.
|
||||
|
||||
Basic usage:
|
||||
|
||||
./naclbuild.sh path/to/pepper/toolchain (i.e. ~/naclsdk/pepper_35)
|
||||
|
||||
This will build testgles2.c by default.
|
||||
|
||||
If you want to build a different test, for example testrendercopyex.c:
|
||||
|
||||
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
|
||||
script will give you instructions on how to do that with Python).
|
||||
|
||||
================================================================================
|
||||
RWops and nacl_io
|
||||
================================================================================
|
||||
|
||||
SDL_RWops work transparently with nacl_io. Two functions control the mount points:
|
||||
|
||||
int mount(const char* source, const char* target,
|
||||
const char* filesystemtype,
|
||||
unsigned long mountflags, const void *data);
|
||||
int umount(const char *target);
|
||||
|
||||
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:
|
||||
|
||||
umount("/");
|
||||
|
||||
And then mounting a different filesystem at /
|
||||
|
||||
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
|
||||
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
|
||||
a set of challenges of its own, in particular when big file sizes and slow
|
||||
connections are involved.
|
||||
|
||||
For more information on how nacl_io and mount points work, see:
|
||||
|
||||
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
|
||||
|
||||
To be able to save into the directory "/save/" (like backup of game) :
|
||||
|
||||
mount("", "/save", "html5fs", 0, "type=PERSISTENT");
|
||||
|
||||
And add to manifest.json :
|
||||
|
||||
"permissions": [
|
||||
"unlimitedStorage"
|
||||
]
|
||||
|
||||
================================================================================
|
||||
TODO - Known Issues
|
||||
================================================================================
|
||||
* Testing of all systems with a real application (something other than SDL's tests)
|
||||
* 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
|
||||
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.
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
Platforms
|
||||
=========
|
||||
|
||||
We maintain the list of supported platforms on our wiki now, and how to
|
||||
build and install SDL for those platforms:
|
||||
|
||||
https://wiki.libsdl.org/Installation
|
||||
|
||||
Platforms
|
||||
=========
|
||||
|
||||
We maintain the list of supported platforms on our wiki now, and how to
|
||||
build and install SDL for those platforms:
|
||||
|
||||
https://wiki.libsdl.org/Installation
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
PSP
|
||||
======
|
||||
PSP
|
||||
======
|
||||
SDL port for the Sony PSP contributed by
|
||||
Captian Lex
|
||||
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
Touch
|
||||
Touch
|
||||
===========================================================================
|
||||
System Specific Notes
|
||||
===========================================================================
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
WinCE
|
||||
=====
|
||||
WinCE
|
||||
=====
|
||||
|
||||
Windows CE is no longer supported by SDL.
|
||||
|
||||
|
||||
@@ -1,41 +1,41 @@
|
||||
Windows
|
||||
================================================================================
|
||||
|
||||
================================================================================
|
||||
OpenGL ES 2.x support
|
||||
================================================================================
|
||||
|
||||
SDL has support for OpenGL ES 2.x under Windows via two alternative
|
||||
implementations.
|
||||
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
|
||||
which supports the WGL_EXT_create_context_es2_profile extension. Vendors known
|
||||
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/)
|
||||
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
|
||||
ANGLE.
|
||||
To obtain the ANGLE binaries, you can either compile from source 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:
|
||||
|
||||
* libEGL.dll
|
||||
* libGLESv2.dll
|
||||
* d3dcompiler_46.dll (supports Windows Vista or later, better shader compiler)
|
||||
or...
|
||||
* d3dcompiler_43.dll (supports Windows XP or later)
|
||||
|
||||
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).
|
||||
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
|
||||
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).
|
||||
|
||||
Known Bugs:
|
||||
|
||||
* 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
|
||||
refreshing if this is set to anything other than the default value.
|
||||
|
||||
Windows
|
||||
================================================================================
|
||||
|
||||
================================================================================
|
||||
OpenGL ES 2.x support
|
||||
================================================================================
|
||||
|
||||
SDL has support for OpenGL ES 2.x under Windows via two alternative
|
||||
implementations.
|
||||
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
|
||||
which supports the WGL_EXT_create_context_es2_profile extension. Vendors known
|
||||
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/)
|
||||
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
|
||||
ANGLE.
|
||||
To obtain the ANGLE binaries, you can either compile from source 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:
|
||||
|
||||
* libEGL.dll
|
||||
* libGLESv2.dll
|
||||
* d3dcompiler_46.dll (supports Windows Vista or later, better shader compiler)
|
||||
or...
|
||||
* d3dcompiler_43.dll (supports Windows XP or later)
|
||||
|
||||
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).
|
||||
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
|
||||
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).
|
||||
|
||||
Known Bugs:
|
||||
|
||||
* 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
|
||||
refreshing if this is set to anything other than the default value.
|
||||
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
126
docs/README.md
126
docs/README.md
@@ -1,63 +1,63 @@
|
||||
Simple DirectMedia Layer {#mainpage}
|
||||
========================
|
||||
|
||||
(SDL)
|
||||
|
||||
Version 2.0
|
||||
|
||||
---
|
||||
http://www.libsdl.org/
|
||||
|
||||
Simple DirectMedia Layer is a cross-platform development library designed
|
||||
to provide low level access to audio, keyboard, mouse, joystick, and graphics
|
||||
hardware via OpenGL and Direct3D. It is used by video playback software,
|
||||
emulators, and popular games including Valve's award winning catalog
|
||||
and many Humble Bundle games.
|
||||
|
||||
SDL officially supports Windows, Mac OS X, Linux, iOS, and Android.
|
||||
Support for other platforms may be found in the source code.
|
||||
|
||||
SDL is written in C, works natively with C++, and there are bindings
|
||||
available for several other languages, including C# and Python.
|
||||
|
||||
This library is distributed under the zlib license, which can be found
|
||||
in the file "COPYING.txt".
|
||||
|
||||
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 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/)
|
||||
|
||||
- [Android](README-android.md)
|
||||
- [CMake](README-cmake.md)
|
||||
- [DirectFB](README-directfb.md)
|
||||
- [DynAPI](README-dynapi.md)
|
||||
- [Emscripten](README-emscripten.md)
|
||||
- [Gesture](README-gesture.md)
|
||||
- [Mercurial](README-hg.md)
|
||||
- [iOS](README-ios.md)
|
||||
- [Linux](README-linux.md)
|
||||
- [OS X](README-macosx.md)
|
||||
- [Native Client](README-nacl.md)
|
||||
- [Pandora](README-pandora.md)
|
||||
- [Supported Platforms](README-platforms.md)
|
||||
- [Porting information](README-porting.md)
|
||||
- [PSP](README-psp.md)
|
||||
- [Raspberry Pi](README-raspberrypi.md)
|
||||
- [Touch](README-touch.md)
|
||||
- [WinCE](README-wince.md)
|
||||
- [Windows](README-windows.md)
|
||||
- [WinRT](README-winrt.md)
|
||||
|
||||
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)
|
||||
|
||||
If you want to report bugs or contribute patches, please submit them to
|
||||
[bugzilla](http://bugzilla.libsdl.org/)
|
||||
|
||||
Enjoy!
|
||||
|
||||
|
||||
Sam Lantinga <mailto:slouken@libsdl.org>
|
||||
|
||||
Simple DirectMedia Layer {#mainpage}
|
||||
========================
|
||||
|
||||
(SDL)
|
||||
|
||||
Version 2.0
|
||||
|
||||
---
|
||||
http://www.libsdl.org/
|
||||
|
||||
Simple DirectMedia Layer is a cross-platform development library designed
|
||||
to provide low level access to audio, keyboard, mouse, joystick, and graphics
|
||||
hardware via OpenGL and Direct3D. It is used by video playback software,
|
||||
emulators, and popular games including Valve's award winning catalog
|
||||
and many Humble Bundle games.
|
||||
|
||||
SDL officially supports Windows, Mac OS X, Linux, iOS, and Android.
|
||||
Support for other platforms may be found in the source code.
|
||||
|
||||
SDL is written in C, works natively with C++, and there are bindings
|
||||
available for several other languages, including C# and Python.
|
||||
|
||||
This library is distributed under the zlib license, which can be found
|
||||
in the file "COPYING.txt".
|
||||
|
||||
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 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/)
|
||||
|
||||
- [Android](README-android.md)
|
||||
- [CMake](README-cmake.md)
|
||||
- [DirectFB](README-directfb.md)
|
||||
- [DynAPI](README-dynapi.md)
|
||||
- [Emscripten](README-emscripten.md)
|
||||
- [Gesture](README-gesture.md)
|
||||
- [Mercurial](README-hg.md)
|
||||
- [iOS](README-ios.md)
|
||||
- [Linux](README-linux.md)
|
||||
- [OS X](README-macosx.md)
|
||||
- [Native Client](README-nacl.md)
|
||||
- [Pandora](README-pandora.md)
|
||||
- [Supported Platforms](README-platforms.md)
|
||||
- [Porting information](README-porting.md)
|
||||
- [PSP](README-psp.md)
|
||||
- [Raspberry Pi](README-raspberrypi.md)
|
||||
- [Touch](README-touch.md)
|
||||
- [WinCE](README-wince.md)
|
||||
- [Windows](README-windows.md)
|
||||
- [WinRT](README-winrt.md)
|
||||
|
||||
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)
|
||||
|
||||
If you want to report bugs or contribute patches, please submit them to
|
||||
[bugzilla](http://bugzilla.libsdl.org/)
|
||||
|
||||
Enjoy!
|
||||
|
||||
|
||||
Sam Lantinga <mailto:slouken@libsdl.org>
|
||||
|
||||
|
||||
Reference in New Issue
Block a user