Skip to content

Commit f731741

Browse files
SDLWikiBotSDLWikiBot
committed
Sync SDL3 wiki -> header
[ci skip]
1 parent 0eaa8c6 commit f731741

File tree

3 files changed

+317
-0
lines changed

3 files changed

+317
-0
lines changed

‎docs/README-git.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
git
2+
=========
3+
4+
The latest development version of SDL is available via git.
5+
Git allows you to get up-to-the-minute fixes and enhancements;
6+
as a developer works on a source tree, you can use "git" to mirror that
7+
source tree instead of waiting for an official release. Please look
8+
at the Git website ( https://git-scm.com/ ) for more
9+
information on using git, where you can also download software for
10+
macOS, Windows, and Unix systems.
11+
12+
git clone https://github.com/libsdl-org/SDL
13+
14+
There is a web interface to the Git repository at:
15+
http://github.com/libsdl-org/SDL/
16+

‎docs/README-raspberrypi.md

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
Raspberry Pi
2+
============
3+
4+
Requirements:
5+
6+
Raspberry Pi OS (other Linux distros may work as well).
7+
8+
In modern times, the Raspberry Pi works mostly like any other Linux device:
9+
for video, you can use X11, Wayland, or KMSDRM. For audio, you can use ALSA,
10+
PulseAudio, or PipeWire, etc. OpenGL, OpenGL ES, and Vulkan are known to work.
11+
12+
There is a video backend in SDL called "rpi" that uses a deprecated Broadcom
13+
interface (named "dispmanx") to draw directly to the console without X11.
14+
Newer Raspberry Pi OS releases don't support this (and work fine with our
15+
"kmsdrm" backend for the same purposes, a standard Linux interface). Don't
16+
panic if you can't use this backend, or CMake says it can't find libraries it
17+
needs for this.
18+
19+
SDL has, in past times, worked on the original Raspberry Pi and the RPi 2, but
20+
these devices are no longer targets we actively test; if they broke, please
21+
report bugs or send patches!
22+
23+
The Raspberry Pi 3 and later (in 32-bit and 64-bit mode) are still known to
24+
work well at the time of this writing. The Raspberry Pi Zero and Zero 2 are
25+
also known to work well.
26+
27+
28+
## Documentation Out Of Date
29+
30+
The rest of this document is likely out of date; a lot has changed in recent
31+
years in both SDL and the Raspberry Pi universe, and this document has not
32+
been updated to reflect those details. Take the rest of this information with
33+
a grain of salt!
34+
35+
36+
37+
NEON
38+
----
39+
40+
If your Pi has NEON support, make sure you add -mfpu=neon to your CFLAGS so
41+
that SDL will select some otherwise-disabled highly-optimized code. The
42+
original Pi and Pi Zero units don't have NEON; everything from the Pi2/PiZero2
43+
and later do.
44+
45+
46+
Cross compiling from x86 Linux
47+
------------------------------
48+
49+
To cross compile SDL for Raspbian from your desktop machine, you'll need a
50+
Raspbian system root and the cross compilation tools. We'll assume these tools
51+
will be placed in /opt/rpi-tools
52+
53+
sudo git clone --depth 1 https://github.com/raspberrypi/tools /opt/rpi-tools
54+
55+
You'll also need a Raspbian binary image.
56+
Get it from: http://downloads.raspberrypi.org/raspbian_latest
57+
After unzipping, you'll get file with a name like: "<date>-wheezy-raspbian.img"
58+
Let's assume the sysroot will be built in /opt/rpi-sysroot.
59+
60+
export SYSROOT=/opt/rpi-sysroot
61+
sudo kpartx -a -v <path_to_raspbian_image>.img
62+
sudo mount -o loop /dev/mapper/loop0p2 /mnt
63+
sudo cp -r /mnt $SYSROOT
64+
sudo apt-get install qemu binfmt-support qemu-user-static
65+
sudo cp /usr/bin/qemu-arm-static $SYSROOT/usr/bin
66+
sudo mount --bind /dev $SYSROOT/dev
67+
sudo mount --bind /proc $SYSROOT/proc
68+
sudo mount --bind /sys $SYSROOT/sys
69+
70+
Now, before chrooting into the ARM sysroot, you'll need to apply a workaround,
71+
edit $SYSROOT/etc/ld.so.preload and comment out all lines in it.
72+
73+
sudo chroot $SYSROOT
74+
apt-get install libudev-dev libasound2-dev libdbus-1-dev libraspberrypi0 libraspberrypi-bin libraspberrypi-dev libx11-dev libxext-dev libxrandr-dev libxcursor-dev libxi-dev libxss-dev
75+
exit
76+
sudo umount $SYSROOT/dev
77+
sudo umount $SYSROOT/proc
78+
sudo umount $SYSROOT/sys
79+
sudo umount /mnt
80+
81+
There's one more fix required, as the libdl.so symlink uses an absolute path
82+
which doesn't quite work in our setup.
83+
84+
sudo rm -rf $SYSROOT/usr/lib/arm-linux-gnueabihf/libdl.so
85+
sudo ln -s ../../../lib/arm-linux-gnueabihf/libdl.so.2 $SYSROOT/usr/lib/arm-linux-gnueabihf/libdl.so
86+
87+
The final step is compiling SDL itself.
88+
89+
export CC="/opt/rpi-tools/arm-bcm2708/gcc-linaro-arm-linux-gnueabihf-raspbian/bin/arm-linux-gnueabihf-gcc --sysroot=$SYSROOT -I$SYSROOT/opt/vc/include -I$SYSROOT/usr/include -I$SYSROOT/opt/vc/include/interface/vcos/pthreads -I$SYSROOT/opt/vc/include/interface/vmcs_host/linux"
90+
cd <SDL SOURCE>
91+
mkdir -p build;cd build
92+
LDFLAGS="-L$SYSROOT/opt/vc/lib" ../configure --with-sysroot=$SYSROOT --host=arm-raspberry-linux-gnueabihf --prefix=$PWD/rpi-sdl3-installed --disable-pulseaudio --disable-esd
93+
make
94+
make install
95+
96+
To be able to deploy this to /usr/local in the Raspbian system you need to fix up a few paths:
97+
98+
perl -w -pi -e "s#$PWD/rpi-sdl3-installed#/usr/local#g;" ./rpi-sdl3-installed/lib/libSDL3.la ./rpi-sdl3-installed/lib/pkgconfig/sdl3.pc
99+
100+
Apps don't work or poor video/audio performance
101+
-----------------------------------------------
102+
103+
If you get sound problems, buffer underruns, etc, run "sudo rpi-update" to
104+
update the RPi's firmware. Note that doing so will fix these problems, but it
105+
will also render the CMA - Dynamic Memory Split functionality useless.
106+
107+
Also, by default the Raspbian distro configures the GPU RAM at 64MB, this is too
108+
low in general, specially if a 1080p TV is hooked up.
109+
110+
See here how to configure this setting: http://elinux.org/RPiconfig
111+
112+
Using a fixed gpu_mem=128 is the best option (specially if you updated the
113+
firmware, using CMA probably won't work, at least it's the current case).
114+
115+
No input
116+
--------
117+
118+
Make sure you belong to the "input" group.
119+
120+
sudo usermod -aG input `whoami`
121+
122+
No HDMI Audio
123+
-------------
124+
125+
If you notice that ALSA works but there's no audio over HDMI, try adding:
126+
127+
hdmi_drive=2
128+
129+
to your config.txt file and reboot.
130+
131+
Reference: http://www.raspberrypi.org/phpBB3/viewtopic.php?t=5062
132+
133+
Text Input API support
134+
----------------------
135+
136+
The Text Input API is supported, with translation of scan codes done via the
137+
kernel symbol tables. For this to work, SDL needs access to a valid console.
138+
If you notice there's no SDL_EVENT_TEXT_INPUT message being emitted, double check that
139+
your app has read access to one of the following:
140+
141+
* /proc/self/fd/0
142+
* /dev/tty
143+
* /dev/tty[0...6]
144+
* /dev/vc/0
145+
* /dev/console
146+
147+
This is usually not a problem if you run from the physical terminal (as opposed
148+
to running from a pseudo terminal, such as via SSH). If running from a PTS, a
149+
quick workaround is to run your app as root or add yourself to the tty group,
150+
then re-login to the system.
151+
152+
sudo usermod -aG tty `whoami`
153+
154+
The keyboard layout used by SDL is the same as the one the kernel uses.
155+
To configure the layout on Raspbian:
156+
157+
sudo dpkg-reconfigure keyboard-configuration
158+
159+
To configure the locale, which controls which keys are interpreted as letters,
160+
this determining the CAPS LOCK behavior:
161+
162+
sudo dpkg-reconfigure locales
163+
164+
165+
OpenGL problems
166+
---------------
167+
168+
If you have desktop OpenGL headers installed at build time in your RPi or cross
169+
compilation environment, support for it will be built in. However, the chipset
170+
does not actually have support for it, which causes issues in certain SDL apps
171+
since the presence of OpenGL support supersedes the ES/ES2 variants.
172+
The workaround is to disable OpenGL at configuration time:
173+
174+
./configure --disable-video-opengl
175+
176+
Or if the application uses the Render functions, you can use the SDL_RENDER_DRIVER
177+
environment variable:
178+
179+
export SDL_RENDER_DRIVER=opengles2
180+
181+
Notes
182+
-----
183+
184+
* When launching apps remotely (via SSH), SDL can prevent local keystrokes from
185+
leaking into the console only if it has root privileges. Launching apps locally
186+
does not suffer from this issue.
187+
188+

‎docs/README-visualc.md

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
Using SDL with Microsoft Visual C++
2+
===================================
3+
4+
#### by Lion Kimbro with additions by James Turk
5+
6+
You can either use the precompiled libraries from the [SDL](https://www.libsdl.org/download.php) web site, or you can build SDL
7+
yourself.
8+
9+
### Building SDL
10+
11+
0. To build SDL, your machine must, at a minimum, have the DirectX9.0c SDK installed. It may or may not be retrievable from
12+
the [Microsoft](https://www.microsoft.com) website, so you might need to locate it [online](https://duckduckgo.com/?q=directx9.0c+sdk+download&t=h_&ia=web).
13+
_Editor's note: I've been able to successfully build SDL using Visual Studio 2019 **without** the DX9.0c SDK_
14+
15+
1. Open the Visual Studio solution file at `./VisualC/SDL.sln`.
16+
17+
2. Your IDE will likely prompt you to upgrade this solution file to whatever later version of the IDE you're using. In the `Retarget Projects` dialog,
18+
all of the affected project files should be checked allowing you to use the latest `Windows SDK Version` you have installed, along with
19+
the `Platform Toolset`.
20+
21+
If you choose *NOT* to upgrade to use the latest `Windows SDK Version` or `Platform Toolset`, then you'll need the `Visual Studio 2010 Platform Toolset`.
22+
23+
3. Build the `.dll` and `.lib` files by right clicking on each project in turn (Projects are listed in the _Workspace_
24+
panel in the _FileView_ tab), and selecting `Build`.
25+
26+
You may get a few warnings, but you should not get any errors.
27+
28+
Later, we will refer to the following `.lib` and `.dll` files that have just been generated:
29+
30+
- `./VisualC/Win32/Debug/SDL3.dll` or `./VisualC/Win32/Release/SDL3.dll`
31+
- `./VisualC/Win32/Debug/SDL3.lib` or `./VisualC/Win32/Release/SDL3.lib`
32+
33+
_Note for the `x64` versions, just replace `Win32` in the path with `x64`_
34+
35+
### Creating a Project with SDL
36+
37+
- Create a project as a `Win32 Application`.
38+
39+
- Create a C++ file for your project.
40+
41+
- Set the C runtime to `Multi-threaded DLL` in the menu:
42+
`Project|Settings|C/C++ tab|Code Generation|Runtime Library `.
43+
44+
- Add the SDL `include` directory to your list of includes in the menu:
45+
`Project|Settings|C/C++ tab|Preprocessor|Additional include directories `
46+
47+
*VC7 Specific: Instead of doing this, I find it easier to add the
48+
include and library directories to the list that VC7 keeps. Do this by
49+
selecting Tools|Options|Projects|VC++ Directories and under the "Show
50+
Directories For:" dropbox select "Include Files", and click the "New
51+
Directory Icon" and add the [SDLROOT]\\include directory (e.g. If you
52+
installed to c:\\SDL\\ add c:\\SDL\\include). Proceed to change the
53+
dropbox selection to "Library Files" and add [SDLROOT]\\lib.*
54+
55+
The "include directory" I am referring to is the `./include` folder.
56+
57+
Now we're going to use the files that we had created earlier in the *Build SDL* step.
58+
59+
Copy the following file into your Project directory:
60+
61+
- `SDL3.dll`
62+
63+
Add the following file to your project (It is not necessary to copy it to your project directory):
64+
65+
- `SDL3.lib`
66+
67+
To add them to your project, right click on your project, and select
68+
`Add files to project`.
69+
70+
**Instead of adding the files to your project, it is more desirable to add them to the linker options: Project|Properties|Linker|Command Line
71+
and type the names of the libraries to link with in the "Additional Options:" box. Note: This must be done for each build configuration
72+
(e.g. Release,Debug).**
73+
74+
### Hello SDL
75+
76+
Here's a sample SDL snippet to verify everything is setup in your IDE:
77+
78+
```c
79+
#include <SDL3/SDL.h>
80+
#include <SDL3/SDL_main.h> // only include this one in the source file with main()!
81+
82+
int main( int argc, char* argv[] )
83+
{
84+
const int WIDTH = 640;
85+
const int HEIGHT = 480;
86+
SDL_Window* window = NULL;
87+
SDL_Renderer* renderer = NULL;
88+
89+
SDL_Init(SDL_INIT_VIDEO);
90+
window = SDL_CreateWindow("Hello SDL", WIDTH, HEIGHT, 0);
91+
renderer = SDL_CreateRenderer(window, NULL);
92+
93+
SDL_DestroyRenderer(renderer);
94+
SDL_DestroyWindow(window);
95+
SDL_Quit();
96+
return 0;
97+
}
98+
```
99+
100+
### That's it!
101+
102+
I hope that this document has helped you get through the most difficult part of using the SDL: installing it.
103+
Suggestions for improvements should be posted to the [Github Issues](https://github.com/libsdl-org/SDL/issues).
104+
105+
### Credits
106+
107+
Thanks to [Paulus Esterhazy](mailto:[email protected]), for the work on VC++ port.
108+
109+
This document was originally called "VisualC.txt", and was written by [Sam Lantinga](mailto:[email protected]).
110+
111+
Later, it was converted to HTML and expanded into the document that you see today by [Lion Kimbro](mailto:[email protected]).
112+
113+
Minor Fixes and Visual C++ 7 Information (in italic) was added by [James Turk](mailto:[email protected])

0 commit comments

Comments
 (0)