Thanks to suve a new documentation resource is available for the PGD SDL2 units at https://pascalgamedevelopment.github.io/SDL2-for-Pascal. The docs are generated directly from the source if new pull requests are merged into the master branch of the repository. Talking of the SDL2 units: They made good progress in 2022 and are still making good progress and soon the first official release will be available.
FFPlay4Laz2 has been added to the projects. It is a Free Pascal/Lazarus Media Player powered by the FFmpeg frame work and SDL2.
In the future I will not refer to SDL version 2 as “SDL 2.0” anymore as SDL’s version numbering scheme has changed with version 2.0.23 (now actually being 2.23.1). That means the minor version is not zero anymore and SDL 2.0 is misleading in that regard. I will update any reference by “SDL2”.
FFPlay4Laz2 is the SDL2 version of the older SDL 1.2 based (Win32 only) FFPlay4Laz FFmpeg Video and Media Player. FFPlay4Laz2 is extended to have more features than FFPlay4Laz and provide better performance. It is designed to be cross-platform by replacing Win-API calls by SDL2 calls. The project is open source and can be found on the official Lazarus forums.
Console menue of FFPlay4Laz2. (Image source: Captured from FFPlay4Laz2_Images.pdf, see link below; 28/12/2022)
This project has no official website and the author provides updates via the official Lazarus forums (see link below).
Project name: FFPlay4Laz2
Author: metis
Latest version: v2.5.2
First release date: Thread startet in Dec. 2014
Compiler and SDL version: Free Pascal / Lazarus / SDL2
After an PHP update the syntax plugin doesn’t work anymore. I added a better plugin and updated all chapters to display code in a reader friendly way. I also removed the description how to copy source code using the old plugin in the introductory chapter. I adapted code snippet length in some chapters (Chapter 4, Chapter 15). Updated Chapter 18 about music and sound.
I added a new SDL2 powered Free Pascal project: SuperSakura. It’s a nice visual novel engine to run retro-style Japanese games by Kirinn.
I updated some chapters (Introduction, Windows Installation, Linux Installation), mainly because of the repository change to the PGD Community SDL2 units. The units got a lot of updates lately, and help is needed to improve them even further. While this news post was waiting to be published, it appears Tim is back. Now, we have the unfortunate situation that there are two active repositories for the SDL2 headers and the situation has not been resolved, yet.
Menue screen of the engine. (Image: With permission of the author.)
Well, the introduction for this amazing project over at the Kirinn’s (developer) website says it all!
SuperSakura is a free, open-source visual novel engine that can run quite a few old games, mostly published by JAST, one of the first developers in the field. In addition to well-known localised titles, Japanese companies produced lots of fairly good games in the 90’s that were never translated.
And this project is fully written in Free Pascal and uses SDL2. Amazing work! I was happy to hear, the author got started with Free Pascal and SDL2 right here, with these tutorials :-)!
IMPORTANT: The repository to get the newest, up to date, SDL2 units has changed. It is found here: https://github.com/PascalGameDevelopment/SDL2-for-Pascal. It is now hosted by our Partner site Pascal Game Development, where you can find many resources if you are interested in game development with Delphi or Free Pascal.
Background: The old repository by Tim Blume has been an up to date source for these units for many years since its establishment (Thanks Tim!), but lately no more pull requests were integrated and so a new repository maintainer had to be found. Long time contributor to the units, Super Vegeta (suve), came up with the great idea to integrate it to the PGD repository, which is now reality (Thanks AthenaOfDelphi!).
In the next chapter we will see how so called events are processed to handle input of any kind (keyboard, mouse, joystick,…) Before that I’d like to introduce a simple, yet powerful way to handle keyboard input.
The keyboard state represents the state (pressed = 1 or unpressed = 0) of all the keyboard keys, hence the key states. By
function SDL_GetKeyboardState(numkeys: PInt): PUInt8
we have easy access to this array.
The red rectangle can be moved by the WASD keys by reading out their key states.
The following code example will draw a red rectangle which can be moved by the WASD keys. Therefore we read out their key states on every cycle of the program loop.
program SDL_KeyboardState;
uses SDL2;
var
sdlWindow1: PSDL_Window;
sdlRenderer: PSDL_Renderer;
sdlRectangle: TSDL_Rect;
sdlKeyboardState: PUInt8;
Running: Boolean = True;
begin
//initilization of video subsystem
if SDL_Init(SDL_INIT_VIDEO) < 0 then Halt;
if SDL_CreateWindowAndRenderer(500, 500, SDL_WINDOW_SHOWN, @sdlWindow1, @sdlRenderer) <> 0
then Halt;
// prepare rectangle
sdlRectangle.x := 250;
sdlRectangle.y := 250;
sdlRectangle.w := 10;
sdlRectangle.h := 10;
// program loop
while Running = True do
begin
SDL_PumpEvents;
sdlKeyboardState := SDL_GetKeyboardState(nil);
// ESC pressed
if sdlKeyboardState[SDL_SCANCODE_ESCAPE] = 1 then
Running := False;
// WASD keys pressed
if sdlKeyboardState[SDL_SCANCODE_W] = 1 then
sdlRectangle.y := sdlRectangle.y-1;
if sdlKeyboardState[SDL_SCANCODE_A] = 1 then
sdlRectangle.x := sdlRectangle.x-1;
if sdlKeyboardState[SDL_SCANCODE_S] = 1 then
sdlRectangle.y := sdlRectangle.y+1;
if sdlKeyboardState[SDL_SCANCODE_D] = 1 then
sdlRectangle.x := sdlRectangle.x+1;
// black background
SDL_SetRenderDrawColor(sdlRenderer, 0, 0, 0, SDL_ALPHA_OPAQUE);
SDL_RenderClear(sdlRenderer);
// draw red rectangle
SDL_SetRenderDrawColor(sdlRenderer, 255, 0, 0, SDL_ALPHA_OPAQUE);
SDL_RenderDrawRect(sdlRenderer, @sdlRectangle);
SDL_RenderPresent(sdlRenderer);
SDL_Delay(20);
end;
// clear memory
SDL_DestroyRenderer(sdlRenderer);
SDL_DestroyWindow (sdlWindow1);
//closing SDL2
SDL_Quit;
end.
To get the keyboard state, we define a unsigned 8 bit pointer variable sdlKeyboardState in the var clause. It points to the array of key states.
// program loop
while Running = True do
begin
SDL_PumpEvents;
sdlKeyboardState := SDL_GetKeyboardState(nil);
After setting up a SDL2 window and and preparing a SDL2 rectangle, the program loop is entered. Here we need to update the event queue by procedure SDL_PumpEvents. After that we can grab the keyboard state by the former mentioned function SDL_GetKeyboardState. The argument should be nil. These actions have to performed on every cycle.
// ESC pressed
if sdlKeyboardState[SDL_SCANCODE_ESCAPE] = 1 then
Running := False;
// WASD keys pressed
if sdlKeyboardState[SDL_SCANCODE_W] = 1 then
sdlRectangle.y := sdlRectangle.y-1;
if sdlKeyboardState[SDL_SCANCODE_A] = 1 then
sdlRectangle.x := sdlRectangle.x-1;
if sdlKeyboardState[SDL_SCANCODE_S] = 1 then
sdlRectangle.y := sdlRectangle.y+1;
if sdlKeyboardState[SDL_SCANCODE_D] = 1 then
sdlRectangle.x := sdlRectangle.x+1;
We now can check for the of any key in the array by sdlKeyboardState[SDL_SCANCODE_…] using its scancode as a handle (e.g. SDL_SCANCODE_ESCAPE for the escape key) and react as desired, e.g. exit the program loop or change the x/y coordinates of the rectangle. The scancode represents the position of the related key state in the array. A detailed description of scancodes in the next chapter. A list of all the scancodes shows all possible scancodes.
Could you please give a short description of Savage Vessels for those who have never heard of it?
Within fields of asteroids and fragmented freighters you scavenge and combat against robot vessels. At the same time you have to keep away from the surrounding void. With your carrier you got into this threatening area. In order to escape you have to determine your location repeatedly: leave the carrier, visit some navpoints, land again and move on. But the robots won’t let you. So you have to arm against them by gathering and crafting.
The visuals are based on top down pixel-art and a dynamic field of view. Modern physics provide inertia and collision. Sound fx creates an eerie atmosphere. It’s a spiritual successor to Teleglitch.
Why did you decide to choose Pascal as a programing language and SDL/SDL2 as a library for this project?
Pascal is my mother tongue. It’s capable of everything I need and I’m feeling comfortable with it.
SDL is versatile, platform-agnostic and plain.
What do you think is the most interesting Pascal/SDL/SDL2 project out there (besides of your own, of course :-D)?
This project is a program to load GoldSrc BSP files. The GoldSrc BSP file format has been derived from the id’s Quake 2 file format by Valve Software for their Half-Life game series.
It has been realized with
Lazarus, Free Pascal
SDL2, OpenGL.
The BSP Loader powered by Lazarus.Loading a WAD file and displaying a selected texture from it.Textured rendering of a scene (estate). The blue colorkey is not interpreted to be transparent yet.Scene: Oilrig.Scene: Assault.
02/08/2018, v0.1 alpha
Capabilities
Load BSP files and show contents of data lumps (exception: VIS Lump)
Load WAD files and render contained textures
Load BSP file and all WAD files which are necessary to render the fully textured scene
Navigate by simple camera through scene
To-Do’s
lightmapping from lightmap data
VIS Lump: treat it at all
collision detection
face culling
have spaces between textures in atlas texture to prevent bleeding-effect (esp. in tiled textures recognizable)
make blue colorkey transparent
sky cube
release the source code (if beta stadium reached)
Important Sources
BSP and WAD File Formats
I cannot state how important these documents were in understanding the structure of the BSP and WAD file formats. Without them, this project wouldn’t have been possible.
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.
program SDL_RectanglesScaling;
uses SDL2;
var
sdlWindow1: PSDL_Window;
sdlRenderer: PSDL_Renderer;
sdlSurface1: PSDL_Surface;
sdlTexture1: PSDL_Texture;
sdlRectangle: TSDL_Rect;
begin
//initilization of video subsystem
if SDL_Init(SDL_INIT_VIDEO) < 0 then Halt;
if SDL_CreateWindowAndRenderer(500, 500, SDL_WINDOW_SHOWN, @sdlWindow1, @sdlRenderer) <> 0
then Halt;
// set scaling quality
SDL_SetHint(SDL_HINT_RENDER_SCALE_QUALITY, 'nearest');
// create surface from file
sdlSurface1 := SDL_LoadBMP('fpsdl.bmp');
if sdlSurface1 = nil then
Halt;
// load image file
sdlTexture1 := SDL_CreateTextureFromSurface(sdlRenderer, sdlSurface1);
if sdlTexture1 = nil then
Halt;
// prepare rectangle
sdlRectangle.x := 12;
sdlRectangle.y := 25;
sdlRectangle.w := 178;
sdlRectangle.h := 116;
// render texture
SDL_RenderCopy(sdlRenderer, sdlTexture1, @sdlRectangle, nil);
SDL_RenderCopy(sdlRenderer, sdlTexture1, nil, @sdlRectangle);
// render to window for 2 seconds
SDL_RenderPresent(sdlRenderer);
SDL_Delay(2000);
// clear memory
SDL_DestroyTexture(sdlTexture1);
SDL_FreeSurface(sdlSurface1);
SDL_DestroyRenderer(sdlRenderer);
SDL_DestroyWindow (sdlWindow1);
//closing SDL2
SDL_Quit;
end.
After initializing SDL2 and setting up the window and renderer as known, the rectangle is getting some values. It just encloses the words “Free Pascal meets SDL” in the original image (see above).
Scaling in SDL2
Scaling Quality
Right before creating the surface and texture, there is this line in code.
// set scaling quality
SDL_SetHint(SDL_HINT_RENDER_SCALE_QUALITY, 'nearest');
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
linear filtering
support by OpenGL and Direct3D
best or 2
anisotropic filtering
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.
Nearest pixel sampling filter for scaling.
Linear filter for scaling.
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.
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.
And now let’s see how it is done in code.
program SDL_LoadingRenderingBMP;
uses SDL2;
var
sdlWindow1: PSDL_Window;
sdlRenderer: PSDL_Renderer;
sdlSurface1: PSDL_Surface;
sdlTexture1: PSDL_Texture;
begin
//initilization of video subsystem
if SDL_Init(SDL_INIT_VIDEO) < 0 then Halt;
if SDL_CreateWindowAndRenderer(500, 500, SDL_WINDOW_SHOWN, @sdlWindow1, @sdlRenderer) <> 0
then Halt;
// create surface from file
sdlSurface1 := SDL_LoadBMP('fpsdl.bmp');
if sdlSurface1 = nil then
Halt;
// create texture from surface
sdlTexture1 := SDL_CreateTextureFromSurface(sdlRenderer, sdlSurface1);
if sdlTexture1 = nil then
Halt;
// render texture
if SDL_RenderCopy(sdlRenderer, sdlTexture1, nil, nil) <> 0 then
Halt;
// render to window for 2 seconds
SDL_RenderPresent(sdlRenderer);
SDL_Delay(2000);
// clear memory
SDL_DestroyTexture(sdlTexture1);
SDL_FreeSurface(sdlSurface1);
SDL_DestroyRenderer(sdlRenderer);
SDL_DestroyWindow (sdlWindow1);
//closing SDL2
SDL_Quit;
end.
var
sdlWindow1: PSDL_Window;
sdlRenderer: PSDL_Renderer;
sdlSurface1: PSDL_Surface;
sdlTexture1: PSDL_Texture;
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
sdlSurface1 := SDL_LoadBMP('fpsdl.bmp');
if sdlSurface1 = nil then
Halt;
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
SDL_LoadBMP(_file: PAnsiChar): PSDL_Surface
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.
// create texture from surface
sdlTexture1 := SDL_CreateTextureFromSurface(sdlRenderer, sdlSurface1);
if sdlTexture1 = nil then
Halt;
The function to use is SDL_CreateTextureFromSurface(renderer, surface).
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)).
// render texture
if SDL_RenderCopy(sdlRenderer, sdlTexture1, nil, nil) <> 0 then
Halt;
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 will run without any problem, though SDL_CreateTextureFromSurface() will not free the surface created by SDL_LoadBMP(). And you have no handle to free this surface. This creates a memory leak.