Sign in Join
Wiki copytemporary

FPC and SDL: what changed

Revision 2 to 3. Removed lines have a minus sign; added lines have a plus sign.

OldNewLine
1-**Simple DirectMedia Layer** or **SDL** 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.
1+**Simple DirectMedia Layer** or **SDL** 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.
22
33## Introduction
44
5-For general information and documentation about SDL, visit the [Official SDL Website](https://www.libsdl.org/index.php). This page is going to explain how to use SDL with Free Pascal and where to obtain the Pascal headers, etc. More information is available at the [LibSDL Wiki](https://wiki.libsdl.org/SDL2/FrontPage).
5+For general information and documentation about SDL, visit the [Official SDL Website](<https://www.libsdl.org/index.php>). This page is going to explain how to use SDL with Free Pascal and where to obtain the Pascal headers, etc. More information is available at the [LibSDL Wiki](<https://wiki.libsdl.org/SDL2/FrontPage>).
66
77## Obtaining FPC headers for SDL2
88
9-After installing the SDL library itself on your system, you'll need the Pascal headers for it to be able to use SDL with FPC. Since version 2.2.2, most SDL units are included with FPC. You can, of course, also download them from SDL2-for-Pascal, in case you need some bug fix or a unit that's not in the version shipped with FPC.
9+After installing the SDL library itself on your system, you'll need the Pascal headers for it to be able to use SDL with FPC. Since version 2.2.2, most SDL units are included with FPC. You can, of course, also download them from SDL2-for-Pascal, in case you need some bug fix or a unit that's not in the version shipped with FPC.
1010
1111### SDL2-for-Pascal
1212
13-  **See:** [The SDL2-for-Pascal GitHub Repository](https://github.com/PascalGameDevelopment/SDL2-for-Pascal).
14-
15-You can download the latest release from the [Releases page](https://github.com/PascalGameDevelopment/SDL2-for-Pascal/releases).
13+**See:** [The SDL2-for-Pascal GitHub Repository](<https://github.com/PascalGameDevelopment/SDL2-for-Pascal>).
1614
17-You can also download and browse the current source code using Git, see [GitHub's "About Remote Repositories" page](https://docs.github.com/en/get-started/getting-started-with-git/about-remote-repositories) for instructions. In short, just do:
15+You can download the latest release from the [Releases page](<https://github.com/PascalGameDevelopment/SDL2-for-Pascal/releases>).
1816
19-```shell
17+You can also download and browse the current source code using Git, see [GitHub's "About Remote Repositories" page](<https://docs.github.com/en/get-started/getting-started-with-git/about-remote-repositories>) for instructions. In short, just do:
18+```
2019git clone https://github.com/PascalGameDevelopment/SDL2-for-Pascal.git
2120```
2221
23-After you download the SDL2-for-Pascal sources, you want to be able to use these units in your programs. For the simplest scenario, just add the following lines to your `fpc.cfg` file:
24-
25-```shell
22+After you download the SDL2-for-Pascal sources, you want to be able to use these units in your programs. For the simplest scenario, just add the following lines to your `fpc.cfg` file:
23+```
2624-Fi<jedi-sdl-path>/units/sdl2.pas
27--Fu<jedi-sdl-path>/units/sdl2.pas
28--Fu<jedi-sdl-path>/units/sdl2_gfx.pas
29--Fu<jedi-sdl-path>/units/sdl2_image.pas
30--Fu<jedi-sdl-path>/units/sdl2_mixer.pas
31--Fu<jedi-sdl-path>/units/sdl2_net.pas
32--Fu<jedi-sdl-path>/units/sdl2_ttf.pas
25+ -Fu<jedi-sdl-path>/units/sdl2.pas
26+ -Fu<jedi-sdl-path>/units/sdl2_gfx.pas
27+ -Fu<jedi-sdl-path>/units/sdl2_image.pas
28+ -Fu<jedi-sdl-path>/units/sdl2_mixer.pas
29+ -Fu<jedi-sdl-path>/units/sdl2_net.pas
30+ -Fu<jedi-sdl-path>/units/sdl2_ttf.pas
3331```
3432
35-…where `<jedi-sdl-path>` is the path where you placed the SDL2-for-Pascal sources.
36-
37-Alternatively, you can copy all `*.pas` and `*.inc` files from these directories to one chosen directory, and add only this chosen directory to your `fpc.cfg`.
38-
39-### SDL headers from Free Pascal SVN (deprecated)
33+…where <jedi-sdl-path> is the path where you placed the SDL2-for-Pascal sources.
4034
41-The code can be downloaded with: \<syntaxhighlight lang="shell\> svn co <http://svn.freepascal.org/svn/fpcprojects/contrib/sdl/> fpc-sdl
35+Alternatively, you can copy all `*.pas` and `*.inc` files from these directories to one chosen directory, and add only this chosen directory to your `fpc.cfg`.
4236
4337## Tips and tricks
4438
4539### SDL_mixer library
4640
47-When using SDL_mixer, the call to Mix_OpenAudio MUST happen before the call to SDL_SetVideoMode, otherwise you will get a (sometimes loud) audible pop.
41+When using SDL_mixer, the call to Mix_OpenAudio MUST happen before the call to SDL_SetVideoMode, otherwise you will get a (sometimes loud) audible pop.
4842
4943### SMPEG Library
5044
51-If you use sdl2_mixer, you'll notice that it's dependent on the [SMPEG Library](https://github.com/icculus/smpeg). For modern Linux distributions this is not a problem, because smpeg is distributed with many of them, but it can be more troublesome for FreeBSD and Windows:
45+If you use sdl2_mixer, you'll notice that it's dependent on the [SMPEG Library](<https://github.com/icculus/smpeg>). For modern Linux distributions this is not a problem, because smpeg is distributed with many of them, but it can be more troublesome for FreeBSD and Windows:
5246
53-- You can install smpeg for FreeBSD from ports: `/usr/ports/multimedia/smpeg`.
54-- You can get smpeg.dll for Windows from [SMPEG for Visual C sources](https://github.com/icculus/smpeg/blob/main/VisualC.zip).
47+ * You can install smpeg for FreeBSD from ports: `/usr/ports/multimedia/smpeg`.
48+ * You can get smpeg.dll for Windows from [SMPEG for Visual C sources](<https://github.com/icculus/smpeg/blob/main/VisualC.zip>).
5549
56-Alternatively, you can simply modify the source of SDL_mixer.pas to remove smpeg from it's uses clause and comment out one line in the sources mentioning mp3s (it's a case near the end). Remember that you will also need to have an `sdl2_mixer.dll`/`sdl2_mixer.so` that is *not* linked to smpeg—otherwise the sdl2_mixer library will depend on smpeg anyway.
50+Alternatively, you can simply modify the source of SDL_mixer.pas to remove smpeg from it's uses clause and comment out one line in the sources mentioning mp3s (it's a case near the end). Remember that you will also need to have an `sdl2_mixer.dll`/`sdl2_mixer.so` that is _not_ linked to smpeg—otherwise the sdl2_mixer library will depend on smpeg anyway.
5751
52+### Floating point exceptions
53+
54+The SDL2 code may raise floating point exceptions, such as dividing by zero, overflow or underflow. Whereas C compilers usually mask these exceptions, fpc does not do this in its default setting and the program may crash with hard to understand errors (for example see: <https://forum.lazarus.freepascal.org/index.php/topic,69852.0.html>). All this may depend on your CPU and your OS.
55+
56+The solution is to mask the floating point exceptions:
57+```
58+uses
59+ math;
60+
61+ var
62+ SavedMask: TFPUExceptionMask;
63+
64+ begin
65+ SavedMask := Math.GetExceptionMask();
66+ Math.SetExceptionMask(SavedMask + [exOverflow, exZeroDivide, exInvalidOp]);
67+
68+ ... code using SDL2 ...
69+
70+ Math.SetExceptionMask(SavedMask);
71+ end.
72+```
73+
74+Find available fpu exceptions here: <https://lazarus-ccr.sourceforge.io/docs/rtl/system/tfpuexception.html>
75+
5876## macOS specific issues
5977
6078### SDL Framework and SDL libraries
6179
62-On macOS, SDL2 uses Cocoa to setup the drawing window and to handle all events (such as keypresses). This is done using a small piece of code that is automatically called when the program starts up, and which subsequently calls a function with the name *SDLmain*.
80+On macOS, SDL2 uses Cocoa to setup the drawing window and to handle all events (such as keypresses). This is done using a small piece of code that is automatically called when the program starts up, and which subsequently calls a function with the name _SDLmain_.
6381
64-There are however two different ways to package/distribute SDL for macOS, and depending on which version you use, the procedure to get this startup code into your program is slightly different.
82+There are however two different ways to package/distribute SDL for macOS, and depending on which version you use, the procedure to get this startup code into your program is slightly different.
6583
6684### The framework version
6785
68-This the version that you get when you download the macOS version of SDL from [libsdl.org](https://libsdl.org/). In this case, the startup code is only available in source form. It is located on the installation disk image, in the folder `devel-lite`. After copying the `SDL.framework` from the disk image to `/Library/Frameworks` and copying the `devel-lite` folder anywhere on your hard drive (e.g., in your home directory), you can compile it into libSDLMain.a by opening a Terminal session, navigating to the copied `devel-lite` folder, and executing the following commands:
69-
70-```shell
86+This the version that you get when you download the macOS version of SDL from [libsdl.org](<https://libsdl.org/>). In this case, the startup code is only available in source form. It is located on the installation disk image, in the folder `devel-lite`. After copying the `SDL.framework` from the disk image to `/Library/Frameworks` and copying the `devel-lite` folder anywhere on your hard drive (e.g., in your home directory), you can compile it into libSDLMain.a by opening a Terminal session, navigating to the copied `devel-lite` folder, and executing the following commands:
87+```
7188gcc -c -o SDLMain.o SDLMain.m -I/Library/Frameworks/SDL.framework/Headers
72-ar r libSDLMain.a SDLMain.o
73-ranlib libSDLMain.a
89+ ar r libSDLMain.a SDLMain.o
90+ ranlib libSDLMain.a
7491```
7592
76-You can then move the generated `libSDLMain.a` library anywhere you want. To make sure the linker can find it when you compile SDL applications, pass the `-Fl``/full/path/to/folder/containing/libSDLMain.a` command line parameter to the compiler.
93+You can then move the generated `libSDLMain.a` library anywhere you want. To make sure the linker can find it when you compile SDL applications, pass the `-Fl/full/path/to/folder/containing/libSDLMain.a` command line parameter to the compiler.
7794
7895### The Unix library version
7996
80-There is also a "classic Unix" version of SDL for macOS (no framework, just a bunch of separate libraries), which you get if you compile SDL from sources, or if you install SDL using Fink or MacPorts. In this case, `libSDLmain.a` is already included in a compiled form. You just have to use the compiler's `-Fl` parameter, as explained in the previous section, to make sure that the linker can find this library.
97+There is also a "classic Unix" version of SDL for macOS (no framework, just a bunch of separate libraries), which you get if you compile SDL from sources, or if you install SDL using Fink or MacPorts. In this case, `libSDLmain.a` is already included in a compiled form. You just have to use the compiler's `-Fl` parameter, as explained in the previous section, to make sure that the linker can find this library.
8198
8299## For FPC 2.2.2 and later
83100
84-The SDL unit included with FPC includes all necessary framework, library and main procedure name renaming statements, so you no longer have to do anything special. Just add the sdl unit to your program and everything will be taken care of. However, the remarks about libSDLMain in the above section still hold (libSDLMain.a is required by the SDL unit included with FPC).
101+The SDL unit included with FPC includes all necessary framework, library and main procedure name renaming statements, so you no longer have to do anything special. Just add the sdl unit to your program and everything will be taken care of. However, the remarks about libSDLMain in the above section still hold (libSDLMain.a is required by the SDL unit included with FPC).
85102
86-Note that if you use the original units as distributed by the JEDI team, you may still need to follow the instructions in the section below.
103+Note that if you use the original units as distributed by the JEDI team, you may still need to follow the instructions in the section below.
87104
88105## For FPC 2.0.2–2.2.0
89106
90-With FPC v2.0.2 to v2.2.0, and possibly also when using the original SDL units as distributed by the JEDI team, you have to use the `-XMSDL_main` command line option and tell the linker to include some frameworks:
91-
92-1. Install sdl, for example using fink.
93-2. Add the following to your program:
94- *
95-
96-{\$linklib gcc} {\$linklib SDLmain} uses sdl;
107+With FPC v2.0.2 to v2.2.0, and possibly also when using the original SDL units as distributed by the JEDI team, you have to use the `-XMSDL_main` command line option and tell the linker to include some frameworks:
97108
98-1. Then, this command line does it:
99- *
109+ 1. Install sdl, for example using fink.
110+ 2. Add the following to your program:
111+ *
112+```
113+{$linklib gcc}
114+ {$linklib SDLmain}
115+ uses sdl;
116+```
100117
101-fpc -XMSDL_main -k-L/sw/lib -k-lSDL -k-framework -kOpenGL -k-framework -kCocoa -Fu\<pathtosdl.pas files\> -Fi\<pathtosdl.inc files\> YourProgram.pas
118+ 3. Then, this command line does it:
119+ *
120+```
121+fpc -XMSDL_main -k-L/sw/lib -k-lSDL -k-framework -kOpenGL -k-framework -kCocoa -Fu<pathtosdl.pas files> -Fi<pathtosdl.inc files> YourProgram.pas
122+```
102123
103-If you installed the SDL libraries using fink, also add `-k-L/sw/lib -k-lSDL` to your fpc command.
124+If you installed the SDL libraries using fink, also add `-k-L/sw/lib -k-lSDL` to your fpc command.
104125
105-If `sdl.pas` and `jedi-sdl.inc` are in the directory of your program, you can omit `-Fu<pathtosdl.pas files> -Fi<pathtosdl.inc files>`.
126+If `sdl.pas` and `jedi-sdl.inc` are in the directory of your program, you can omit `-Fu<pathtosdl.pas files> -Fi<pathtosdl.inc files>`.
106127
107128## Examples
108129
109-Creating an empty SDL window:
110-
111-``` pascal
130+Creating an empty SDL window:
131+```
112132program sdltest;
113-{$linklib gcc}
114-{$linklib SDLmain}
115-uses sdl;
116-var
117- scr: PSDL_Surface; // Our main screen
118-begin
119- SDL_Init(SDL_INIT_VIDEO); // Initialize the video SDL subsystem
120- scr := SDL_SetVideoMode(640, 480, 8, SDL_SWSURFACE); // Create a software window of 640x480x8 and assign to scr
121- SDL_Quit; // close the subsystems and SDL
122-end.
133+ {$linklib gcc}
134+ {$linklib SDLmain}
135+ uses sdl;
136+ var
137+ scr: PSDL_Surface; // Our main screen
138+ begin
139+ SDL_Init(SDL_INIT_VIDEO); // Initialize the video SDL subsystem
140+ scr := SDL_SetVideoMode(640, 480, 8, SDL_SWSURFACE); // Create a software window of 640x480x8 and assign to scr
141+ SDL_Quit; // close the subsystems and SDL
142+ end.
123143```
124144
125145You can then compile this code with: `fpc -Fu<pathtosdl.pas files> -Fi<pathtosdl.inc files> example.pas`
126146
127-If you use Lazarus, make sure you fill in the "other unit files" and "include files" properly.
147+If you use Lazarus, make sure you fill in the "other unit files" and "include files" properly.
128148
129149## Ubuntu
130150
131151With Ubuntu, you can install the following, which saves you having to manually install the SDK packages… `sudo apt install libsdl1.2-dev` …and possibly also… `sudo apt install libsdl2-dev`
132152
133-FPC knows SDL from home.
153+FPC knows SDL from home.
134154
135155## SDL2 Units
136156
137157### Tutorials
138158
139-See the [Free Pascal meets SDL](https://www.freepascal-meets-sdl.net/sdl-tutorials/) website for tutorials on using Free Pascal and SDL.
159+See the [Free Pascal meets SDL](<https://www.freepascal-meets-sdl.net/sdl-tutorials/>) website for tutorials on using Free Pascal and SDL.
140160
161+## SDL3 Units
162+
163+[Pascal SDL3 Bindings](<https://github.com/sechshelme/Lazarus-SDL3.0-Packages_and_Examples>)
164+
141165---
142-*From the Free Pascal wiki, page "FPC and SDL", as it stood on 2023-09-21 after a change by RogueScholar, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).*
143-Category: Audio
144-Category: FPC
145-Category: Headers and Bindings
146-Category: Multimedia
147-Category: Tutorials
148-Category: Video
166+*From the Free Pascal wiki, page "FPC and SDL", as the Internet Archive kept it on 2026-06-05, last changed on 2025-01-21. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).*

Back to history