Tag Archives: sdl

Fairtris

The description of this project found on it’s Wiki page says it all, nothing to add other than that this project is really capable of spawning some good, nostalgic feelings (!):

Fairtris is a video game, a clone of the 32-year-old Tetris® game produced by Nintendo for the Famicom and NES consoles, designed for modern Windows and Linux systems. Fairtris is not an emulator — it is a full-fledged game, created from scratch in Free Pascal language (using the Lazarus IDE) and with Direct3D and OpenGL support via the SDL library. Thanks to this combination, it is super-fast and ultra-light.”

sdl2 news title image

SDL2 documentation

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”.

Updated Chapter 4 to reflect changes in the new PGD SDL2 units.

FFPlay4Laz2

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).

sdl2repo-music-sound

Many updates, everywhere

The news title says nothing and everything :-).

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.

Also, I changed some stylings.

SuperSakura

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 :-)!

Savage Vessels

Impressive rogue-like 2D space shooter with pixel-art, physics and hard survival.

Interview with developer KPas

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)?

My nomination for now: DoomRL (https://drl.chaosforge.org/)

Are there any further steps for Savage Vessels and/or are any new projects planned? What will they be?

Savage Vessels is in development and I want to release it on Steam end
of year 2019 or so. You can wishlist it on Steam by the way.

Window and Renderer

Last updated on November 20th, 2021

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.

program SDL_WindowAndRenderer;

uses SDL2;

var
  sdlWindow1: PSDL_Window;
  sdlRenderer: PSDL_Renderer;

begin

  //initilization of video subsystem
  if SDL_Init(SDL_INIT_VIDEO) < 0 then Halt;

  // full set up
  sdlWindow1 := SDL_CreateWindow('Window1', 50, 50, 500, 500, SDL_WINDOW_SHOWN);
  if sdlWindow1 = nil then Halt;

  sdlRenderer := SDL_CreateRenderer(sdlWindow1, -1, 0);
  if sdlRenderer = nil then Halt;

  // quick set up
  {
  if SDL_CreateWindowAndRenderer(500, 500, SDL_WINDOW_SHOWN, @sdlWindow1, @sdlRenderer) <> 0
    then Halt;
  }

  // render to window for 2 seconds
  SDL_RenderPresent(sdlRenderer);
  SDL_Delay(2000);

  // clear memory
  SDL_DestroyRenderer(sdlRenderer);
  SDL_DestroyWindow (sdlWindow1);

  //closing SDL2
  SDL_Quit;

end.  

Let’s have closer look at the var clause.

var
  sdlWindow1: PSDL_Window;
  sdlRenderer: PSDL_Renderer;

The SDL2 Window

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.

Creation of a Window

  // full set up
  sdlWindow1 := SDL_CreateWindow('Window1', 50, 50, 500, 500, SDL_WINDOW_SHOWN);
  if sdlWindow1 = nil then Halt;

The creation of a SDL2 window is simple as using the function SDL_CreateWindow(title, x, y, width, height, flags) or more specific:

SDL_CreateWindow(const title: PAnsiChar; x: SInt32; y: SInt32; w: SInt32; h: SInt32; flags: UInt32): PSDL_Window

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.

SDL2 window and coordinates diagram
Creative Commons License This image by https://www.freepascal-meets-sdl.net is licensed under a Creative Commons Attribution 4.0 International License.
The window is placed with respect to the left upper corner of the screen.

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.

Flag
Description
SDL_WINDOW_FULLSCREENfullscreen window
SDL_WINDOW_FULLSCREEN_DESKTOPfullscreen window at the current desktop resolution
SDL_WINDOW_OPENGLwindow usable with OpenGL context
SDL_WINDOW_SHOWNwindow is visible
SDL_WINDOW_HIDDENwindow is not visible
SDL_WINDOW_BORDERLESSno window decoration
SDL_WINDOW_RESIZABLEwindow can be resized
SDL_WINDOW_MINIMIZEDwindow is minimized
SDL_WINDOW_MAXIMIZEDwindow is maximized
SDL_WINDOW_INPUT_GRABBEDwindow has grabbed input focus
SDL_WINDOW_INPUT_FOCUSwindow has input focus
SDL_WINDOW_MOUSE_FOCUSwindow has mouse focus
SDL_WINDOW_FOREIGNwindow not created by SDL
SDL_WINDOW_ALLOW_HIGHDPIwindow 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

  sdlRenderer := SDL_CreateRenderer(sdlWindow1, -1, 0);
  if sdlRenderer = nil then Halt;

The creation of the renderer is as simple as one function call of SDL_CreateRenderer(window, index, flags) or

SDL_CreateRenderer(window: PSDL_Window; index: SInt32; flags: UInt32): PSDL_Renderer

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:

  1. SDL_RENDERER_SOFTWARE
  2. SDL_RENDERER_ACCELERATED
  3. SDL_RENDERER_PRESENTVSYNC
  4. SDL_RENDERER_TARGETTEXTURE

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.

Quick Creation of a Window and a Renderer

 // quick set up
  {
  if SDL_CreateWindowAndRenderer(500, 500, SDL_WINDOW_SHOWN, @sdlWindow1, @sdlRenderer) <> 0
    then Halt;
  }

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.

SDL_CreateWindowAndRenderer(width: SInt32; height: SInt32; window_flags: UInt32; window: PPSDL_Window; renderer: PPSDL_Renderer): SInt32

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().

SDL_RenderPresent(renderer: PSDL_Renderer)

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
  SDL_DestroyRenderer(sdlRenderer);
  SDL_DestroyWindow (sdlWindow1);

Do not forget to quit SDL2 finally (which we don’t).

That’s it. And now things are going to get really interesting :-).

← previous Chapter | next Chapter →

Viewports

Last updated on November 20th, 2021

SDL2 allows for viewports. Have a look at the following screenshot of a SDL2 game (Battle for Wesnoth).

Modified screenshot of Battle of Wesnoth. (Original source image, as found in the Wesnoth Wiki by Wesnoth developers. Image license: GFDL.)

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.

Modified screenshot of Battle of Wesnoth. (Original source image, as found in the Wesnoth Wiki by Wesnoth developers. Image license: GFDL.)

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.

SDL2 window and viewport coordinates diagram
The relation of your screen, a SDL2 window and a viewport within this window are outlined here.

Let’s have a look at the code.

program SDL2_Viewport;

uses SDL2;

const
  Viewport1: TSDL_Rect = (x: 0;   y:   0; w: 400; h: 500);
  Viewport2: TSDL_Rect = (x: 400; y:   0; w: 100; h: 300);
  Viewport3: TSDL_Rect = (x: 400; y: 300; w: 100; h: 200);

  BlackDot:  TSDL_Rect = (x: 10;  y:  10; w:   3; h:   3);

var
  sdlWindow1: PSDL_Window;
  sdlRenderer: PSDL_Renderer;

begin

  //initilization of video subsystem
  if SDL_Init(SDL_INIT_VIDEO) < 0 then Halt;

  SDL_CreateWindowAndRenderer(500, 500, SDL_WINDOW_SHOWN, @sdlWindow1, @sdlRenderer);
  if (sdlWindow1 = nil) or (sdlRenderer = nil) then Halt;

  // fill every viewport with background color and draw a black dot into it
  SDL_RenderSetViewport(sdlRenderer, @Viewport1);
  SDL_SetRenderDrawColor(sdlRenderer, 255, 0, 0, SDL_ALPHA_OPAQUE);
  SDL_RenderFillRect(sdlRenderer, nil);
  SDL_SetRenderDrawColor(sdlRenderer, 0, 0, 0, SDL_ALPHA_OPAQUE);
  SDL_RenderFillRect(sdlRenderer, @BlackDot);

  SDL_RenderSetViewport(sdlRenderer, @Viewport2);
  SDL_SetRenderDrawColor(sdlRenderer, 255, 255, 0, SDL_ALPHA_OPAQUE);
  SDL_RenderFillRect(sdlRenderer, nil);
  SDL_SetRenderDrawColor(sdlRenderer, 0, 0, 0, SDL_ALPHA_OPAQUE);
  SDL_RenderFillRect(sdlRenderer, @BlackDot);

  SDL_RenderSetViewport(sdlRenderer, @Viewport3);
  SDL_SetRenderDrawColor(sdlRenderer, 0, 255, 0, SDL_ALPHA_OPAQUE);
  SDL_RenderFillRect(sdlRenderer, nil);
  SDL_SetRenderDrawColor(sdlRenderer, 0, 0, 0, SDL_ALPHA_OPAQUE);
  SDL_RenderFillRect(sdlRenderer, @BlackDot);

  // render to window for 2 seconds
  SDL_RenderPresent(sdlRenderer);
  SDL_Delay(2000);

  // clear memory
  SDL_DestroyRenderer(sdlRenderer);
  SDL_DestroyWindow (sdlWindow1);

  //shutting down video subsystem
  SDL_Quit;

end.  

The result will look like this:

Creative Commons License This image by https://www.freepascal-meets-sdl.net is licensed under a Creative Commons Attribution 4.0 International License.
There are three viewports with different background colors and a black dot in the left upper corner.

First we set up some SDL2 rectangles by

const
  Viewport1: TSDL_Rect = (x: 0;   y:   0; w: 400; h: 500);
  Viewport2: TSDL_Rect = (x: 400; y:   0; w: 100; h: 300);
  Viewport3: TSDL_Rect = (x: 400; y: 300; w: 100; h: 200);

  BlackDot:  TSDL_Rect = (x: 10;  y:  10; w:   3; h:   3);

“Viewport1” represents the red viewport (left), “Viewport2” the yellow (upper-right) and “Viewport3” the green (lower-right) viewport in the result image.

Notice how we just prepare one “BlackDot” rectangle for a black dot of 3×3 px dimension at location (10/10).

After setting up SDL2, a renderer and a window as known, we start to set up the first (red, left) viewport.

  // fill every viewport with background color and draw a black dot into it
  SDL_RenderSetViewport(sdlRenderer, @Viewport1);
  SDL_SetRenderDrawColor(sdlRenderer, 255, 0, 0, SDL_ALPHA_OPAQUE);
  SDL_RenderFillRect(sdlRenderer, nil);
  SDL_SetRenderDrawColor(sdlRenderer, 0, 0, 0, SDL_ALPHA_OPAQUE);
  SDL_RenderFillRect(sdlRenderer, @BlackDot);

It is simple as that. Use the function SDL_RenderSetViewport(renderer, rectangle pointer) to set up a viewport. This function returns 0 on success or -1 on failure.

SDL_RenderSetViewport(renderer: PSDL_Renderer; const rect: PSDL_Rect)

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.

← previous Chapter | next Chapter →

DoomRL

Short description

DoomRL is based on ID’s famous Doom game. The RL means roguelike.

Showcase and Basic Data

Developer granted permission to use these screenshots.

  • Project name: DoomRL (a.k.a Doom, the Roguelike)
  • Author: Kornel Kisielewicz (Code/Design), Derek Yu (art)
  • Latest version: 0.9.9.7
  • Release date: 2001 (initial version), 19 March 2013 (latest version)
  • Pascal compiler: FPC 3.0
  • SDL Version: 1.2
  • Further libraries: Lua, OpenGL, FMOD
  • License: Donationware
  • Open source: no
  • Official website: http://doom.chaosforge.org

Interview with Kornel Kisielewicz

Why did you decide to choose Pascal as a programming language and SDL as a library for your projects?

Kornel Kisielewicz: Pascal was my first language, and in those days C++ was quite messy. I liked the clean syntax of Pascal and it’s default strong type system. SDL was a no brainer, we wanted a platform independent layer for OpenGL context creation and Input handling, and SDL was the only reasonable choice in that regard at the time.

What do you think is the most interesting Pascal/SDL/SDL2 project out there (besides your own, of course :-D)?

Kornel Kisielewicz: I have been out of touch with the Pascal scene for a long time now.

Are there any new projects planned?

Kornel Kisielewicz: We’re currently working on Jupiter Hell, a spiritual successor to DoomRL, but it’s in full 3d, and written in C++.

Monsterland

Short description

A commercial action shooter with appealing DOS-like appearance by developer Second Variety Games.

Showcase and Basic Data

Developer granted permission to use these screenshots.

  • Project name: Monsterland
  • Author: Second Variety Games
  • Latest version: 1.15
  • Release date: 12/14/2015
  • Pascal compiler: Free Pascal 3.0.0
  • SDL Version: 1.2
  • Further libraries: sdl_image, sdl_mixer
  • License: commercial product
  • Open source: no
  • Official website: none except Steam page: http://store.steampowered.com/app/406920

Interview with Aleksey from Second Variety Games

Could you please give a short description of Monsterland for those who have never heard of it?

Aleksey: Monsterland is a 2D realtime shooter portrayed entirely through ASCII characters. This includes blood, lighting, particles, etc. Its only gameplay mode is a 3-hour story campaign, which has voiceovers, triggers and scripted sequences. The gameplay of Monsterland was heavily influenced by original Doom games (1 and 2).

Why did you decide to choose Pascal as a programming language and SDL as a library for your projects?

Aleksey: Pascal is an underrated, well-rounded programming language. It has good diagnostics and strict syntax, which removes ambiguity from error messages. It also helps that I was first introduced to it in 1992.

SDL was chosen because I’ve also been writing an engine tied to DirectX, and given where Windows is heading, it was a mistake I didn’t want to repeat. SDL 1.2 didn’t have accelerated 2D though, so I had to do it via OpenGL manually.

What do you think is the most interesting Pascal/SDL/SDL2 project out there (besides your own, of course :-D)?

Aleksey: If Dwarf Fortress still used Pascal, I’d name that. Otherwise, DoomRL I guess.

Are there any further steps planned for the Monsterland series? What will they be?

Aleksey: Aw, you flatter, but Monsterland will not be continued.

Are there any new projects planned?

Aleksey: I’m starting to work on a new type of IF (interactive fiction) game. I clearly have an obsession with text visuals.

There’s also the ambitious isometric RPG I’ve been writing in C for years, the “magnum opus”, but it’s too ambitious at the moment, even though a lot of work has been done. I wish I wrote it in Pascal instead – it would’ve been easier to debug.