I did a major update to the whole SDL2 tutorial, added some new, restructed and split up many old chapters to have a better learning experience. Instead of ten big learning chunks, there are now 18 smaller chunks which are dedicated to clearly outlined topics. I’m looking forward to do a lot of fine tuning and extending the SDL2 tutorial. If you find errors, just drop me a line.
Every article now shows a date of the last update. This makes it easier to estimate how up to date the article’s information are.
I decided to change the basic font size from 18 to 24 points since the text appears too small on common high resolution displays. I adapted point sizes for other elements accordingly. Also, I made license information available for many images (CC-BY 4.0).
The drop-down menu is gone since it got too long and it has been hard to reach all entries on some devices.
Thanks to MattCash Chapter 6 got some necessary updates.
Screens and Images are rectangular, so this shape has a special importance to SDL2 and graphics programming in particular.
Rectangles: TSDL_Rect and PSDL_Rect in SDL 2.0
Often functions require an argument of PSDL_Rect type. This is the pointer counterpart to TSDL_Rect. It is declared as follows.
Simply, this record describes a rectangle, hence the name. The variables x and y correspond to the x/y coordinates of the left upper corner of the rectangle, related to the origin 0/0 which is the left upper corner of, e.g. a texture, window,… The variable w is the width and h the height of the rectangle. That’s it. The next step is to define the rectangle by assign some values for x, y, w and h.
If you use PSDL_Rect, you free the required memory by Pascal’s new procedure as you would for any simple record pointer.
Using Rectangles for Movement and Scaling
The following code demonstrates the basic principle how to achieve the impression of movement of images (sprites) and how scaling works. You will be impressed how simple it actually is.
It sets the render quality. It has to be set before creating the texture. The SDL_SetHint(hint name, hint value) function is no specific function for setting scaling quality, but here we use it for exactly that. Possible values are
nearest or 0
nearest pixel sampling
linear or 1
support by OpenGL and Direct3D
best or 2
support by Direct3D.
All of the values have to be set as string values, so ‘nearest’ or ‘0’. Here is a comparision of the nearest- and the linear filter.
The anisotropic filter doesn’t do anything for me, even if I used Direct3D.
At this point happens the magic that leads to the resulting image. By the way, since the SDL_RenderCopy() function requires the rectangle arguments to be of PSDL_Rect, we use the @-operator (pointer operator) here.
This means, copy the area described by “sdlRectangle” from the source (“sdlTexture1” here) to the whole area (because of nil value) of the destination, hence the window.
Since the window has a width and height of 500 px each, the source rectangle just a width of 178 px and a height of 116 px, SDL2 automatically scales the image to fit into the larger (or smaller) dimensions of the destination.
This means, copy the whole source (because of nil value) to the area described by “sdlRectangle”. The source is the 200×200 px image, which has to squeezed to the 178×116 px rectangle at position (12/25). This is just what you see in the resulting image (above) where the whole image is squeezed into this area.
Movement of Images (Sprites)
Although not covered directly by this code example, you get the picture how movement works. Every frame you adjust the (x/y) coordinates of the rectangle for the destination to bring the sprite about to move.
After cleaning up the memory the program finishes.
Loading of bitmap image files (BMP files) is natively supported by SDL2. The way to go is as follows (from the flow diagram).
Let’s start on the left in the diagram. The easiest way to get a bitmap (BMP) image file for a game or application ready for usage is to create one in a drawing application. Or use the example bitmap “fpsdl.bmp” we used in the code.
The bmp image file is stored on your hard drive and can be loaded by SDL_LoadBMP function to a SDL2 surface. This SDL2 surface is then transformed into a SDL2 texture by SDL_CreateTextureFromSurface function (whose name is just explaining what is does). And finally this texture is rendered by SDL_RenderPresent, this function we know already.
contains two new variables, namely “sdlSurface1” and “sdlTexture1” of the pointer types PSDL_Surface and PSDL_Texture, respecitvely.
After setting up SDL2, a window and a renderer as known, we find this.
Step 1: Loading the BMP file to a SDL2 Surface
// create surface from file
SDL_LoadBMP(name of bmp image file) does what you expect, it loads the image file and generates a SDL2 surface from it. Attention though, if you just give a file name, it is assumed that the file is found in the same folder as the executing application. Optionally you can also give a full file path, e.g. in Windows something like ‘C:\MyImages\fpsdl.bmp’. The function is declared as
and return nil on error, e.g. if the file is not found.
Step 2: Creating a SDL2 Texture from the SDL2 Surface
The next step is to get a SDL2 texture. That’s achieve as follows.
It just does what you expect and transforms the SDL2 surface into a SDL2 texture with the help of the given renderer.
Step 3: Prepare the SDL2 Texture to be Rendered
Before actually rendering the texture, we need to copy it to the rendering target (our window) by SDL_RenderCopy(renderer, texture, source rectangle (texture), destination rectangle (rendering target)).
So the texture is copied to the rendering target (which is the window). The first nil argument means that we want to copy the whole rectangle. The second nil means that we want to copy to the whole dimensions of the rendering target. Let’s have a closer look at the function.
This chapter treats some basics you should know to understand the way SDL2 works.
Briefly: The Basics of Graphics Programming
Loading and the movement of images in a game (or other applications) is a major concept in (game) programming. These images are then refered to as sprites, usually. Let’s have a look at a simple example:
Here are two screenshots from a simple game. The player has to move the yellow-green paddle up- and downwards to prevent the blue ball from getting through to the right side. The game uses two sprites, the blue ball sprite and the yellow-green paddle sprite (see left screenshot). The background color is set to black. The left screenshot is how the game usually appears to the player, here between each frame that got drawn, the former frame has been cleared. The right screenshot demonstrates what happens if the former frame hasn’t been erased before the next one is drawn. – Now it is clearly visible that the sprites are redrawn again and again with sligthly different coordinates, and that is how (game) graphics work (even for the most sophisticated 3d games):
Draw the frame
Show the frame (in a window on screen)
Clear the frame (and go back to step 1)
Briefly: The Relation between Graphic Objects (e.g. Sprites) and Hardware
Actually there are just three locations where these images are stored in your computer system. All images (photo images, drawings, sprites for 2d games, textures for 3d games) are stored on your harddrive somewhere. If you start a photo viewer, a paint program, a 2d game or a 3d game, in all cases the corresponding images need to be loaded from your harddrive to RAM (Random-Access Memory) since displaying and manipulation (e.g. rotation of a photo image by 90°) of images loaded to RAM is much, much faster. Especially for games a fast access to the image data is highly important! And finally there isn’t just one RAM but two, a CPU controlled one located on the motherboard used by every program/application that needs some RAM. The second RAM is located right at your graphic board and controlled by the so-called GPU (graphics processing unit). This is what we want to use if we develop games since it is dedicated, optimized and just hungry for tasks related to fast image processing.
Many games and applications do not only target at common computer systems, but for mobile devices, e.g. smart phones. The principles described are also true for these devices even though there may be differences in detail.
The SDL2 Surface
The SDL2 surface allows you to represent graphic objects like sprites. Every SDL2 surface has a width and height, a pixel format and other properties. Nevertheless, it is a concept which originates from the outdated SDL 1.2 and therefore should not be used anymore. Still, there are reasons why we need to introduce it here. This will be clear soon.
The SDL2 Texture
The SDL2 texture allows you to represent graphic objects just like the SDL2 surface does, although there is a major difference: It is hardware accalerated. So the graphic object is stored in the graphic board’s RAM and any manipulation is done by the graphic board’s GPU.
So as a rule,
always use SDL2 Textures to store your graphic objects (sprites) for SDL 2.0,
then you go for high performance!
Three ways to SDL_Texture
So, how to get a SDL_Texture? In principle there are three ways to create SDL2 textures. For way 2 and 3 the flow diagram may illustrate how it works.
Way 1: From Scratch
You create a SDL_Texture from scratch, so you set a pixel format and texture access format and have to fill in your texture data manually. This is the most sophisticated way and is usually not necessary, unless you work with raw pixel data.
Way 2: From SDL2 Surface
2) You have or create a SDL_Surface from an image file first and then you create the SDL_Texture from the SDL_Surface. This way is shown in the diagram but it means two steps.
Way 3: Directly from Image File
3) You create a SDL_Texture from and image file directly. This is shown in the diagram, too. This is the simplest way to create a SDL_Texture.
Every SDL2 program that shall show some graphic output has to have at least one SDL2 window and a SDL2 renderer. The window is the entity that is showing the graphic output and the renderer is the “machine” that is generating the output to be shown in the window. The code to set up a window and a renderer is as follows.
In SDL 2.0 you can create as many windows as you like, and each window is adressed by its PSDL_Window variable. We just need one window for now, let’s call it “sdlWindow1”. It defines the window’s properties, e.g. size, appearance, border, title name and so on. And it holds the content it shows.
In our example the window is titled “Window1”, it is located at position x = 50 and y = 50 pixels (relative to your screen). It has a width and height of 500 pixels respecitvly. And we have used the flag SDL_WINDOW_SHOWN. More about these flags later. First let’s get an understanding of the coordinate system in SDL2.
The Coordinate System in SDL 2.0
This rule applies:
The origin from where to count to place a window is always the left upper corner of your screen.
So if you choose (0/0) as coordinates the window’s left upper corner will be placed right at the left upper corner of your screen. The diagram below may help to understand this. You may try SDL_WINDOWPOS_CENTERED for each or both coordinates which will lead to a centered window with respect of the screen. If you choose SDL_WINDOWPOS_UNDEFINED you don’t care for the window’s position.
SDL 2.0 windows and their properties
Now let’s talk about the flags. They decide for the properties of the window. Look at the following table (source) of possible flags and you may get an idea what they do.
fullscreen window at the current desktop resolution
window usable with OpenGL context
window is visible
window is not visible
no window decoration
window can be resized
window is minimized
window is maximized
window has grabbed input focus
window has input focus
window has mouse focus
window not created by SDL
window should be created in high-DPI mode if supported (available since SDL 2.0.1)
As you can see, these flags determine different properties of the window. E.g. SDL_WINDOW_FULLSCREEN will create a fullscreen window and SDL_WINDOW_BORDERLESS will create a borderless window. You may combine several flags by OR (if appropriate). For our purpose SDL_WINDOW_SHOWN is a good choice because we just create a shown window without any further restrictions.
The SDL2 Renderer
In computer graphics rendering means the process of synthesizing the final image on your screen from the individual basic data structures. To draw some content to the window, we need therefore a renderer. The PSDL_Renderer (which we declared in the var clause) is responsible for synthesizing all the content in a window, be it some lines, a flat background, a texture, a 3d object, or whatever. We call our PSDL_Renderer “sdlRenderer”.
Creation of a Renderer
The creation of the renderer is as simple as one function call of SDL_CreateRenderer(window, index, flags) or
First we need the renderer to know where to render the finished/rendered output. That will be “Window1” in our case. Next the shown function asks for a cryptic “index”. Well, each driver which is capable of rendering (e.g. OpenGL, Direct3d, Software,…) is indexed in SDL 2.0. In principle you could choose one specific driver here by choosing the corresponding index. Since we don’t know too much about the drivers at the moment the best choice is -1. -1 means that the first driver which is supporting the chosen flag(s) is chosen. Talking about flags, there are four flags you may choose:
You should always prefer SDL_RENDERER_ACCELERATED because this means the graphics board is responsible for rendering, SDL_RENDERER_SOFTWARE in contrast means, the CPU has to do the rendering. As discussed before for best performance the graphic board is the best choice for rendering/graphic related tasks. SDL_RENDERER_PRESENTVSYNC allows for so called vertical synchronization which means that the display of the rendered image is synchronized with the refresh rate of the monitor. SDL_RENDERER_TARGETTEXTURE allows for rendering to a texture. You may have noticed that none of these flags but 0 was used in the example code. This automatically gives priority to hardware accelerated renderers.
Instead of creating the window and the renderer separately as demonstrated, you may use SDL_CreateWindowAndRenderer(width, height, window flags, window pointer pointer, renderer pointer pointer). This has the advantage that you just need one line to set up a window and a renderer, though setting a window title, a window position or specific renderer flags have to be done afterwards if necessary.
Just remove the curly brackets and enclose the “full set up” -part to try it.
This function returns 0 on success and -1 on failure.
Rendering a SDL2 Scene
The actual rendering is achieved by SDL_RenderPresent(renderer). As a sidenote for people coming from SDL 1.2, this is what formerly has been achieved by SDL_Flip().
Freezing (delaying) a running program in SDL 2.0
SDL_Delay(time in milliseconds) is a simple, yet powerful and important procedure to stop the program running for a certain time in milliseconds. 2000 milliseconds are two seconds. This is kind of a twin of Pascal’s Delay procedure.
Clean up the memory in SDL 2.0
Now the final lines of code are discussed. One of the most important rules for sophisticated programming is followed here:
Always clean up the memory on program finish.
For nearly any pointer type generated by SDL 2.0, there is a destroy procedure to remove it from memory. These procedures are comparable to Pascal’s dispose procedure to remove pointer types from memory. Make sure to destroy the objects in the opposite sequence of their generation. We first created a window, then a renderer. So now we go the opposite way, first destroy the renderer and then the window by the procedures SDL_DestroyRenderer(renderer) and SDL_DestroyWindow(window) respectively.
Here we go:
// clear memory
Do not forget to quit SDL2 finally (which we don’t).
That’s it. And now things are going to get really interesting :-).
SDL2 allows for viewports. Have a look at the following screenshot of a SDL2 game (Battle for Wesnoth).
This is a classical situation to use viewports. The game screen is clearly parted into three distinguished areas. The main screen is the large part left with the mountains and the castles. Then there is the minimap in the right-upper corner. And a statistics overview under the minimap. These areas and the corresponding viewports are highlightened in the following screenshot.
The advantage of viewports is that each of them behaves like an own window, so if you draw to the right outside of viewport 1 in the screenshot above, the texture will just be clipped and there is no overlap into viewport 2 oder 3.
After we set up the viewport, we set the draw color by SDL_SetRenderDrawColor(renderer, red, green, blue, alpha) to red (255/0/0/no transparency). Then we use SDL_RenderFillRect(renderer, rectangle pointer) to fill the whole viewport by not specifying a rectangle (nil). Both functions are known from a previous chapter.
Then the color is set to black and a tiny 3×3 rectangle is drawn at location (10/10).
This procedure is repeated for the other two viewports. Notice again, how we use the same rectangle for the black dot though and where it is shown in the result image. The black dot is always drawn at location (10/10) relative to the respective viewport’s location!
As general rule it applies:
The coordinates are always relative to the currently set viewport.
Well, the remaining parts of the code provides nothing new, just the rendering for 2 seconds and some clean up.
Let’s close with some helpful remarks.
No SDL_RenderClear for Viewports!
Do not use SDL_RenderClear(renderer). It will ignore the viewports and clear the whole window with the set drawing color.
Resetting the Viewport
The resetting is done simple by SDL_RenderSetViewport(renderer, nil) as one would expect.
Any good game has a custom mouse cursor. You may think it would be a good idea to have a SDL2 surface or SDL2 texture and render it as any other sprite right at the mouse position to simulate a mouse cursor. DO NOT do this! The mouse cursor is handled separatly from the other rendering to have it smooth and working in critical situations.
The following code shows how to set up a custom mouse cursor with SDL2 the correct way.
This is the interesting part of the code with regard to creating a custom mouse cursor. The cursor’s image is defined by a SDL surface. We create the SDL surface as known from a previous chapter from a png image file to “sdlSurface1” here.
The custom mouse cursor is created by the following function, which returns nil on error.
It needs the surface to use as cursor image and two coordinates (hot_x/hot_y) as arguments. They determine where the actual hitting point for this cursor is. Since the example cursor image is of dimensions 16×16 px and represents a cross, the “hot” (hitting) coordiates are (8/8), hence the cross’ center is used for hitting a button or something. In contrast you may imagine a typical arrow shaped mouse cursor, where the hitting point has to be adjusted to be right on the tip of the arrow in the arrow’s image.
If the cursor creation has been successful, it is necessary to set it to be the actual cursor. You may have created many different cursors, so tell SDL which one to use by the following procedure.
The remaining part of the code is just rendering a 500 by 500 pixels window with a grey (128, 128, 128) background that is updated as long as no mouse button has been pressed.
Finally do not forget to free the mouse cursor by SDL_FreeCursor(mouse cursor) as shown.
A new Chapter 2 has been added. In contrast to the classical Chapter 2 which explains the installation of SDL2 and Free Pascal for the Windows operating system, the new Chapter 2 explains the installation and configuration of SDL2 and Free Pascal/Lazarus in Linux. Initially I was trying to check for some troubles which got mentioned. Finally I ended up with a short, new installation chapter. A few minor changes have been added to the other chapters which are basically hints for Linux users.
This chapter illustrates quickly how to get an environment for Free Pascal/SDL2 development running under Linux. Attention: The following instruction may work for many Debian and Ubuntu based Linux distributions, others probably need different installation procedures.
In contrast to the Windows, in Linux there are so many variables according to the operation system (thousands of different distributions) that there can’t be a more or less generalized way how to install it. Anyway I’d like to demonstrate how it worked for me and give some hints which may help you to install it to your favorite distribution of Linux.
The distribution and software I used:
Linux Distribution: Linux Mint 17.2 (Ubuntu/Debian based)
Desktop: Cinnamon Desktop
Lazarus 1.6 (installed from .deb file)
FPC 3.0.0 (installed from .deb file)
FPC 3.0.0 Source Code (installed from .deb file)
Tim Blume’s SDL2 units (header translation)
SDL2, SDL2_image, SDL2_ttf dynamic library files (Linux has .so files instead of .dll files)
Download and install FPC, FPC sourc code and Lazarus
The first step is to install the Free Pascal compiler (version 3.0.0 or higher), the Compiler’s source code (same version as the compiler) and the Lazarurs IDE (version 1.6 or higher). First check if your package manager provides this software in these (or higher) versions! It is likely that you find the software but the versions may lack behind. If that is the case, download and execute these three .deb files in the shown sequence.
Again Careful: These files are right for many Debian and Ubuntu based distributions (like Linux Mint) but may be wrong for others. Try to find out the right ones for your Linux.
If everything went right, Lazarus can be started up by typing “startlazarus” in the terminal or by finding the program here: /usr/bin/startlazarus which is a symbolic link to the actual executable here: /usr/share/lazarus/1.6/startlazarus. On your system it may be located at a different location but these are rather standard location.
Start up Lazarus
On start up of Lazarus the directories for FPC and the FPC source code were found and set already. As a hint I show where these are located on my system are:
FPC Source code: /usr/share/fpcsrc/3.0.0 (because $(FPCVER) equals the version number, see screenshot)
Before proceeding, my suggestion is to start a new project (simple program) and try out if you are able to do a simple compilation of a very simple program. E.g. a simple writeln-statement.
As a tip you should open up Lazarus’ Console to see the output of your program and writeln commands. You can find the Console at Window > Console.
Get the SDL2 units
Get the latest version of the translated SDL2 units.
Make sure you have the master branch chosen and then click on “Clone or download”, then “Download ZIP”.
After extracting the ZIP file I suggest to rename the new folder into “sdl2” or “SDL2” and place it at this location:
SDL2 units are then here: /usr/local/share/sdl2
To copy the folder to /usr/local/share/ you usually need root permission. Also make sure the new folder allows for access to its files. In my case I had to make sure that the “root group” has access to files.
Get the SDL2 dynamic library
If you are looking for the most recent pre-compiled SDL2 dynamic link library files (e.g. libSDL2.so) on the official SDL2 website, you just find a remark that reads like this:
Please contact your distribution maintainer for updates.
Since SDL2 is very widespread it is very likely that you distribution maintainer already included the files.
Find SDL2 and all necessary libraries in your distribution’s package manager. Perhaps you have a search field as shown (upper right arrow). The screenshot shows what could come up then:
As you can see, for me at this moment the SDL2 dynamic link library, version 2.0.0 (libsdl2-2.0.0) was already installed (the small green check mark indicates this in Linux Mint). Anyway, SDL2_gfx (libsdl2-gfx-1.0.0) and SDL2_image (libsdl2-image-2.0.0) weren’t installed.
Find all necessary libraries and install them. These you should install:
At least for my tutorials SDL2_gfx is not necessary but you may try it out.
The version of these libraries does not necessarily need to be the most recent unfortunately. If you really need the most recent versions here, you may try to contact the maintainer to ask to update the version.
That’s it :-)!…. – Unfortunately I ran into troubles…
The linker doesn’t find libSDL2.so
So, what I got when I tried to run the basic SDL2 code from Chapter 3:
/usr/bin/ld: cannot find -lSDL2
Although I installed the SDL2 dynamic link library I get the linker saying it cannot find it. When looking for sdl2 in /usr/lib and its sub-folders where dynamic link libraries are placed usually, I got these two files:
libSDL2-2.0.so.0 (which is a symbolic link to the file below)
libSDL2-2.0.so.0.2.0 (this is the correct file!)
Anyway, the linker expects libSDL2.so, so what can you do? – Create a symbolic link with that name. This is done in the Terminal by:
locate SDL2: shows where SDL2 is located and how it is named (for me they were in /usr/lib/x86_64-linux-gnu)
sudo ln -s [destination of symbolic link] [name of the symbolic link]
sudo requires to enter the root permission password
Repeat the same for all libraries (SDL2_image, … and so on) you want to use.
Congratulation! After that, everything should run smoothly :-)! I tried chapter 3-9 and all worked well for me.
Linux specific experiences
Launching application invalid
On opening up a Lazarus project (.lpi file) and try to re-run it, I get an error window titled “Launching application invalid” which said “The launching application “”[full path including the execution file of the project]”” does not exist or is not executable.” and further “See Run -> Run parameters -> Local“.
Not sure why this is. Anyway, deleting the executable from the project folder or compiling the project before running it, fixes this issue.