FPC and SDL
Introduction
For general information and documentation about SDL visit the SDL homepage. This page is going to explain how to use SDL with Free Pascal, where to obtain the pascal headers etc.
Obtaining FPC headers for SDL
After installing SDL itself on your system you'll need pascal headers to be able to use SDL with FPC. Since version 2.2.2, most SDL units are included with FPC itself. You can of course also download them from JEDI-SDL in case you need some bug fix or a unit not in the version shipped with FPC.
SDL headers from JEDI-SDL
See JEDI-SDL Home Page.
You can download JEDI-SDLv1.0 Beta..
You can also download and browse current CVS sources, see JEDI-SDL SourceForge CVS for instructions. In short, just do
cvs -d:pserver:anonymous@jedi-sdl.cvs.sourceforge.net:/cvsroot/jedi-sdl login
(when prompted for a password, simply press the Enter key)
cvs -z3 -d:pserver:anonymous@jedi-sdl.cvs.sourceforge.net:/cvsroot/jedi-sdl co JEDI-SDLv1.0
After you downloaded (and eventually unpacked) JEDI-SDL 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:
-Fi<jedi-sdl-path>/JEDI-SDLv1.0/SDL/Pas -Fu<jedi-sdl-path>/JEDI-SDLv1.0/SDL/Pas -Fu<jedi-sdl-path>/JEDI-SDLv1.0/SDL_Mixer/Pas -Fu<jedi-sdl-path>/JEDI-SDLv1.0/SDL_Image/Pas -Fu<jedi-sdl-path>/JEDI-SDLv1.0/SDL_Net/Pas -Fu<jedi-sdl-path>/JEDI-SDLv1.0/SDL_ttf/Pas -Fu<jedi-sdl-path>/JEDI-SDLv1.0/smpeg/Pas -Fu<jedi-sdl-path>/JEDI-SDLv1.0/SFont/Pas -Fu<jedi-sdl-path>/JEDI-SDLv1.0/SDL_Sound/Pas -Fu<jedi-sdl-path>/JEDI-SDLv1.0/SDLMonoFonts/Pas -Fu<jedi-sdl-path>/JEDI-SDLv1.0/SDLSpriteEngine/Pas -Fu<jedi-sdl-path>/JEDI-SDLv1.0/Cal3D/Pas -Fu<jedi-sdl-path>/JEDI-SDLv1.0/ODE/Pas -Fu<jedi-sdl-path>/JEDI-SDLv1.0/SDLCtrls/Pas -Fu<jedi-sdl-path>/JEDI-SDLv1.0/SDL_flic/Pas
(where <jedi-sdl-path> is the path where you placed jedi-sdl sources).
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.
To test that everything works, you can compile and run one of numerous demo programs included, e.g.
cd <jedi-sdl-path>/JEDI-SDLv1.0/SDLSpriteEngine/Demos/Oxygene/ fpc -Sd Oxygene.dpr ./Oxygene
Note that all jedi-sdl code should be compiled in Delphi-compatible mode. Most jedi-sdl units include jedi-sdl.inc that already has the line {$mode delphi} added, but some example programs don't include jedi-sdl.inc. So be sure to compiled them with -Sd command-line option (or add {$mode delphi} directive).
SDL headers from FreePascal CVS (deprecated)
Get them using CVS:
cvs -d :pserver:cvs@cvs.freepascal.org:/FPC/CVS login
(password is 'cvs')
cvs -d :pserver:cvs@cvs.freepascal.org:/FPC/CVS -z3 co projects/contrib/sdl
Tips and tricks
SDL_mixer library
When using SDL_mixer, the call to Mix_OpenAudio MUST happen before the call to SDL_SetVideoMode, otherwise you will get a ( sometimes load ) audible pop.
SMPEG library
If you use SDL_mixer you'll notice that it's dependent on smpeg library. For modern Linux distros and FreeBSD this is not a problem (because smpeg is distributed with them), but it can be troublesome e.g. for Windows. You can get smpeg.dll for Windows from SDL_sound for Visual C sources.
Alternatively, you can simply modify the source of SDL_mixer.pas: 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 SDL_mixer dll/so that is not linked to smpeg -- otherwise SDL_mixer library will depend on smpeg anyway.
Mac OS X specific issues
SDL Framework and SDL lib
There are two different versions of SDL for Mac OS X.
On the one hand there is the framework version, which is available for download from libsdl.org
On the other hand, there is also a "classic unix" version (no framework, just a bunch of separate libraries) which you get by default if you compile SDL from sources (or if you install it using Fink, and possibly also if you install it using MacPorts).
In this case, libSDLmain.a is always available in pre-compiled form (it's automatically compiled along with the rest of the sources). That's also why the FPC SDL unit always links against against that library (so that it works without having to add anything extra in the main program.).
Jedi-sdl headers, as well as headers available with fpc-package are using SDL library.
For FPC 2.2.2 and later
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. 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.
For FPC 2.0.2 to 2.2.0
With fpc 2.0.2 to 2.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:
1) install sdl, for example using fink.
2) Add the following to your program:
{$linklib gcc}
{$linklib SDLmain}
uses sdl;
3) Then, this command line does it:
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
If you installed the SDL libraries using fink, also add -k-L/sw/lib -k-lSDL to your fpc command.
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>.
Examples
Creating an empty SDL window:
program sdltest;
{$linklib gcc} {$linklib SDLmain}
uses sdl;
var scr: PSDL_Surface; // Our main screen
begin SDL_Init(SDL_INIT_VIDEO); // Initialize the video SDL subsystem scr:=SDL_SetVideoMode(640, 480, 8, SDL_SWSURFACE); // Create a software window of 640x480x8 and assign to scr SDL_Quit; // close the subsystems and SDL end.
You can then compile this code with
fpc -Fu<pathtosdl.pas files> -Fi<pathtosdl.inc files> example.pas
If you use lazarus, make sure you fill the "other unit files" and "include files" properly.
