FPC and SDL: what changed

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

Old	New		Line
1	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.
2	2
3	3		## Introduction
4	4
5	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).
6	6
7	7		## Obtaining FPC headers for SDL2
8	8
9	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.
10	10
11	11		### SDL2-for-Pascal
12	12
13	13		See: [The SDL2-for-Pascal GitHub Repository](https://github.com/PascalGameDevelopment/SDL2-for-Pascal).
14	14
15	15		You can download the latest release from the [Releases page](https://github.com/PascalGameDevelopment/SDL2-for-Pascal/releases).
16	16
17	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	18
19	19		```shell
20	20		git clone https://github.com/PascalGameDevelopment/SDL2-for-Pascal.git
21	21		```
22	22
23	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	24
25	25		```shell
26	26		-Fi<jedi-sdl-path>/units/sdl2.pas
27	27		-Fu<jedi-sdl-path>/units/sdl2.pas
28	28		-Fu<jedi-sdl-path>/units/sdl2_gfx.pas
29	29		-Fu<jedi-sdl-path>/units/sdl2_image.pas
30	30		-Fu<jedi-sdl-path>/units/sdl2_mixer.pas
31	31		-Fu<jedi-sdl-path>/units/sdl2_net.pas
32	32		-Fu<jedi-sdl-path>/units/sdl2_ttf.pas
33	33		```
34	34
35	35		…where `<jedi-sdl-path>` is the path where you placed the SDL2-for-Pascal sources.
36	36
37	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	38
39	39		### SDL headers from Free Pascal SVN (deprecated)
40	40
41	41		The code can be downloaded with: \<syntaxhighlight lang="shell\> svn co <http://svn.freepascal.org/svn/fpcprojects/contrib/sdl/> fpc-sdl
42	42
43		-	~~</syntaxhighlight>~~
44		-
45	43		## Tips and tricks
46	44
47	45		### SDL_mixer library
48	46
49	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.
50	48
51	49		### SMPEG Library
52	50
53	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:
54	52
55	53		- You can install smpeg for FreeBSD from ports: `/usr/ports/multimedia/smpeg`.
56	54		- You can get smpeg.dll for Windows from [SMPEG for Visual C sources](https://github.com/icculus/smpeg/blob/main/VisualC.zip).
57	55
58	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.
59	57
60	58		## macOS specific issues
61	59
62	60		### SDL Framework and SDL libraries
63	61
64	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.
65	63
66	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.
67	65
68	66		### The framework version
69	67
70	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:
71	69
72	70		```shell
73	71		gcc -c -o SDLMain.o SDLMain.m -I/Library/Frameworks/SDL.framework/Headers
74	72		ar r libSDLMain.a SDLMain.o
75	73		ranlib libSDLMain.a
76	74		```
77	75
78	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.
79	77
80	78		### The Unix library version
81	79
82	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.
83	81
84	82		## For FPC 2.2.2 and later
85	83
86	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).
87	85
88	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.
89	87
90	88		## For FPC 2.0.2–2.2.0
91	89
92	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:
93	91
94	92		1. Install sdl, for example using fink.
95	93		2. Add the following to your program:
96	94		*
97	95
98	96		{\$linklib gcc} {\$linklib SDLmain} uses sdl;
99	97
100		-	~~</syntaxhighlight>~~
101		-
102	98		1. Then, this command line does it:
103	99		*
104	100
105	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
106		-
107		-	~~</syntaxhighlight>~~
108	102
109	103		If you installed the SDL libraries using fink, also add `-k-L/sw/lib -k-lSDL` to your fpc command.
110	104
111	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>`.
112	106
113	107		## Examples
114	108
115	109		Creating an empty SDL window:
116	110
117	111		``` pascal
118	112		program sdltest;
119	113		{$linklib gcc}
120	114		{$linklib SDLmain}
121	115		uses sdl;
122	116		var
123	117		scr: PSDL_Surface; // Our main screen
124	118		begin
125	119		SDL_Init(SDL_INIT_VIDEO); // Initialize the video SDL subsystem
126	120		scr := SDL_SetVideoMode(640, 480, 8, SDL_SWSURFACE); // Create a software window of 640x480x8 and assign to scr
127	121		SDL_Quit; // close the subsystems and SDL
128	122		end.
129	123		```
130	124
131	125		You can then compile this code with: `fpc -Fu<pathtosdl.pas files> -Fi<pathtosdl.inc files> example.pas`
132	126
133	127		If you use Lazarus, make sure you fill in the "other unit files" and "include files" properly.
134	128
135	129		## Ubuntu
136	130
137	131		With 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`
138	132
139	133		FPC knows SDL from home.
140	134
141	135		## SDL2 Units
142	136
143	137		### Tutorials
144	138
145	139		See the [Free Pascal meets SDL](https://www.freepascal-meets-sdl.net/sdl-tutorials/) website for tutorials on using Free Pascal and SDL.
146	140
147	141		---
148	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).
149	143		Category: Audio
150	144		Category: FPC
151	145		Category: Headers and Bindings
152	146		Category: Multimedia
153	147		Category: Tutorials
154	148		Category: Video

Back to history