1Raspberry Pi
2================================================================================
3
4Requirements:
5
6Raspbian (other Linux distros may work as well).
7
8================================================================================
9 Features
10================================================================================
11
12* Works without X11
13* Hardware accelerated OpenGL ES 2.x
14* Sound via ALSA
15* Input (mouse/keyboard/joystick) via EVDEV
16* Hotplugging of input devices via UDEV
17
18
19================================================================================
20 Raspbian Build Dependencies
21================================================================================
22
23sudo apt-get install libudev-dev libasound2-dev libdbus-1-dev
24
25You also need the VideoCore binary stuff that ships in /opt/vc for EGL and
26OpenGL ES 2.x, it usually comes pre-installed, but in any case:
27
28sudo apt-get install libraspberrypi0 libraspberrypi-bin libraspberrypi-dev
29
30
31================================================================================
32 NEON
33================================================================================
34
35If your Pi has NEON support, make sure you add -mfpu=neon to your CFLAGS so
36that SDL will select some otherwise-disabled highly-optimized code. The
37original Pi units don't have NEON, the Pi2 probably does, and the Pi3
38definitely does.
39
40================================================================================
41 Cross compiling from x86 Linux
42================================================================================
43
44To cross compile SDL for Raspbian from your desktop machine, you'll need a
45Raspbian system root and the cross compilation tools. We'll assume these tools
46will be placed in /opt/rpi-tools
47
48    sudo git clone --depth 1 https://github.com/raspberrypi/tools /opt/rpi-tools
49
50You'll also need a Raspbian binary image.
51Get it from: http://downloads.raspberrypi.org/raspbian_latest
52After unzipping, you'll get file with a name like: "<date>-wheezy-raspbian.img"
53Let's assume the sysroot will be built in /opt/rpi-sysroot.
54
55    export SYSROOT=/opt/rpi-sysroot
56    sudo kpartx -a -v <path_to_raspbian_image>.img
57    sudo mount -o loop /dev/mapper/loop0p2 /mnt
58    sudo cp -r /mnt $SYSROOT
59    sudo apt-get install qemu binfmt-support qemu-user-static
60    sudo cp /usr/bin/qemu-arm-static $SYSROOT/usr/bin
61    sudo mount --bind /dev $SYSROOT/dev
62    sudo mount --bind /proc $SYSROOT/proc
63    sudo mount --bind /sys $SYSROOT/sys
64
65Now, before chrooting into the ARM sysroot, you'll need to apply a workaround,
66edit $SYSROOT/etc/ld.so.preload and comment out all lines in it.
67
68    sudo chroot $SYSROOT
69    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 libxinerama-dev libxxf86vm-dev libxss-dev
70    exit
71    sudo umount $SYSROOT/dev
72    sudo umount $SYSROOT/proc
73    sudo umount $SYSROOT/sys
74    sudo umount /mnt
75
76There's one more fix required, as the libdl.so symlink uses an absolute path
77which doesn't quite work in our setup.
78
79    sudo rm -rf $SYSROOT/usr/lib/arm-linux-gnueabihf/libdl.so
80    sudo ln -s ../../../lib/arm-linux-gnueabihf/libdl.so.2 $SYSROOT/usr/lib/arm-linux-gnueabihf/libdl.so
81
82The final step is compiling SDL itself.
83
84    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"
85    cd <SDL SOURCE>
86    mkdir -p build;cd build
87    LDFLAGS="-L$SYSROOT/opt/vc/lib" ../configure --with-sysroot=$SYSROOT --host=arm-raspberry-linux-gnueabihf --prefix=$PWD/rpi-sdl2-installed --disable-pulseaudio --disable-esd
88    make
89    make install
90
91To be able to deploy this to /usr/local in the Raspbian system you need to fix up a few paths:
92
93    perl -w -pi -e "s#$PWD/rpi-sdl2-installed#/usr/local#g;" ./rpi-sdl2-installed/lib/libSDL2.la ./rpi-sdl2-installed/lib/pkgconfig/sdl2.pc ./rpi-sdl2-installed/bin/sdl2-config
94
95================================================================================
96 Apps don't work or poor video/audio performance
97================================================================================
98
99If you get sound problems, buffer underruns, etc, run "sudo rpi-update" to
100update the RPi's firmware. Note that doing so will fix these problems, but it
101will also render the CMA - Dynamic Memory Split functionality useless.
102
103Also, by default the Raspbian distro configures the GPU RAM at 64MB, this is too
104low in general, specially if a 1080p TV is hooked up.
105
106See here how to configure this setting: http://elinux.org/RPiconfig
107
108Using a fixed gpu_mem=128 is the best option (specially if you updated the
109firmware, using CMA probably won't work, at least it's the current case).
110
111================================================================================
112 No input
113================================================================================
114
115Make sure you belong to the "input" group.
116
117    sudo usermod -aG input `whoami`
118
119================================================================================
120 No HDMI Audio
121================================================================================
122
123If you notice that ALSA works but there's no audio over HDMI, try adding:
124
125    hdmi_drive=2
126
127to your config.txt file and reboot.
128
129Reference: http://www.raspberrypi.org/phpBB3/viewtopic.php?t=5062
130
131================================================================================
132 Text Input API support
133================================================================================
134
135The Text Input API is supported, with translation of scan codes done via the
136kernel symbol tables. For this to work, SDL needs access to a valid console.
137If you notice there's no SDL_TEXTINPUT message being emitted, double check that
138your app has read access to one of the following:
139
140* /proc/self/fd/0
141* /dev/tty
142* /dev/tty[0...6]
143* /dev/vc/0
144* /dev/console
145
146This is usually not a problem if you run from the physical terminal (as opposed
147to running from a pseudo terminal, such as via SSH). If running from a PTS, a
148quick workaround is to run your app as root or add yourself to the tty group,
149then re-login to the system.
150
151    sudo usermod -aG tty `whoami`
152
153The keyboard layout used by SDL is the same as the one the kernel uses.
154To configure the layout on Raspbian:
155
156    sudo dpkg-reconfigure keyboard-configuration
157
158To configure the locale, which controls which keys are interpreted as letters,
159this determining the CAPS LOCK behavior:
160
161    sudo dpkg-reconfigure locales
162
163================================================================================
164 OpenGL problems
165================================================================================
166
167If you have desktop OpenGL headers installed at build time in your RPi or cross
168compilation environment, support for it will be built in. However, the chipset
169does not actually have support for it, which causes issues in certain SDL apps
170since the presence of OpenGL support supersedes the ES/ES2 variants.
171The workaround is to disable OpenGL at configuration time:
172
173    ./configure --disable-video-opengl
174
175Or if the application uses the Render functions, you can use the SDL_RENDER_DRIVER
176environment variable:
177
178    export SDL_RENDER_DRIVER=opengles2
179
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
189