Tag Archives: sdl 2.0

EGSL and Pulsar2D

Short description

EGSL and Pulsar2D are LUA script interpreters to develop games in an easy, quick and convenient way.

EGSL: Showcase and Basic Data

Developer granted permission to use these screenshots.

  • Project name: Easy Game Scripting with LUA
  • Author: Cybermonkey
  • Latest version: 1.6.0
  • Release date: 30/12/2012
  • Compiler: >= FPC 2.6.0
  • SDL Version: SDL 1.2
  • Further libraries: Vampyre Imaging Library / Lua 5.1 / Lua 5.2
  • License: zlib
  • Open source: yes
  • Official website: http://www.egsl.retrogamecoding.org

Pulsar2D: Showcase and Basic Data

Developer granted permission to use these screenshots.

  • Project name: Pulsar2d
  • Author: Cybermonkey
  • Latest version: 0.6.2
  • Release date: 31/12/2015
  • Compiler: FPC 3.0.0
  • SDL Version: SDL2
  • Further libraries: Lua 5.2
  • License: zlib
  • Open source: yes
  • Official website: http://pulsar2d.org

Interview with Cybermonkey

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

Cybermonkey: EGSL (Easy Game Scripting with Lua) is a Lua interpreter which allows one to code 2D games in a simple way. I could say in a “classical way” because EGSL is inspired by old BASIC dialects. The main difference between EGSL and Pulsar2D is that Pulsar2D uses now the newer SDL2 libraries (which gives us the possibility to use multiple windows). It’s as easy as that: write 10 lines of Lua code and start the script and you’ll have already a small sprite moving example. Of course it is possible to use the framework with FreePascal. Apart from that I recently ported the Pulsar2D framework to FreeBASIC. So one can code Pulsar2D games/demos whatsoever in Lua, FreePascal or FreeBASIC.

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

Cybermonkey: I started programming back in the 1980s with the Commodore 64 and BASIC. I learned Turbo Pascal in school and started programming with FreePascal a few years ago. It’s the language I have the most experience with. Not to mention that the FreePascal compiler is well maintained. I chose SDL/SDL2 because of its cross platform capabilities.

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

Cybermonkey: Actually I don’t know of any other … But of course the most impressive Pascal project is Lazarus for me.

Are there any further steps for EGSL and/or Pulsar2D or any new projects planned? What will they be?

Cybermonkey: EGSL will not be developed any further. Pulsar2D wil be improved from time to time. My plans are to implement Box2D physics and easy handling of tiled based maps made with the Tiled editor. But this has no priority so it can take a long time…

At the moment I am developing a little BASIC interpreter called “AllegroBASIC”. It’s a C project, though. (The editor, however, is made with Lazarus…) Since I am using Allegro4 libs which are obsolete now, I am porting at the same time the project to SDL2 which will be named “RETROBASIC”. If there are people interested in AllegroBASIC, have a look at allegrobasic.pulsar2d.org.

 

Chapter 9 – Music and Sound

Last updated on November 21st, 2021

This chapter will introduce you on how to load music and sounds since these are key features of every game and many applications.

SDL_mixer 2.0 for easy music and sound support

Although SDL 2.0 supports music and sound handling natively, there is an easier way to play music and sound files. The official unit SDL_mixer 2.0 (unit’s name SDL2_mixer) has been created exactly for this purpose and is maintained by the same authors (Sam Lantinga, Stephane Peter, Ryan Gordon) as SDL 2.0 itself. The Pascal translation is fortunately available, too in Tim Blume’s header translations.

Supported music and sound file formats in SDL 2.0

According to the official SDL2_mixer documentation the following music and sound formats are supported:

  • WAVE/RIFF (.wav)
  • AIFF (.aiff)
  • VOC (.voc)
  • MOD (.mod .xm .s3m .669 .it .med and more) requiring libmikmod on system
  • MIDI (.mid) using timidity or native midi hardware
  • OggVorbis (.ogg) requiring ogg/vorbis libraries on system
  • MP3 (.mp3) requiring SMPEG or MAD library on system
  • FLAC (.flac) requiring the FLAC library on system

You’ll need these files:

Software
Version
File name
Link
Description
SDL2_mixer dynamic link library
2.0.1
SDL2_mixer-2.0.1-win32-x86.zip (32-bit Windows)
SDL2_mixer-2.0.1-win32-x64.zip (64-bit Windows)
https://www.libsdl.org/projects/SDL_mixer/
This is the corresponding dynamic link library file for the unit for Windows. Note: Mac OS X and Linux versions are also available.
dial.wav sound file dial.wav
dial.wav
A simple telephone dial sound. Source: pdsounds. License: Public domain.
In my mind.ogg music file In my mind.ogg
In my mind.ogg
A nice music sample. Source/Creator: First. License: CC BY-ND 3.0.
music-menu.bmp image file music-menu.bmp
music-menu.bmp
A simple bitmap image file which displays the menu options for the tutorial program.

You should extract the zip-file and get several files. These are four license text files and a readme text file, furthermore you have eight dll files including the important SDL2_mixer.dll. The other dll files are necessary to play the different sound and music formats. Copy all the files to the Windows system32-folder (or the corresponding place). If you forget this and run the examples below you will get an error with exitcode = 309.

Now that you are prepared, let’s have an overview of the code.

program SDL_MusicSound;
uses SDL2, SDL2_mixer;

var
  sdlWindow: PSDL_Window;
  sdlRenderer: PSDL_Renderer;
  sdlSurface: PSDL_Surface;
  sdlTexture: PSDL_Texture;
  sdlKeyboardState: PUInt8;
  Music: PMix_Music;
  Sound: PMix_Chunk;
  Run: Boolean = True;

begin
  if SDL_Init(SDL_INIT_VIDEO or SDL_INIT_AUDIO) < 0 then Exit;

  // Get window and renderer
  if SDL_CreateWindowAndRenderer(
    640, 640, SDL_WINDOW_SHOWN, @sdlWindow,@sdlRenderer) <> 0 then Exit;

  // Create and render menu texture
  sdlSurface := SDL_LoadBMP('music-menu.bmp');
  if sdlSurface = nil then Exit;
  sdlTexture := SDL_CreateTextureFromSurface(sdlRenderer, sdlSurface);
  if sdlTexture = nil then Exit;
  if SDL_RenderCopy(sdlRenderer, sdlTexture, nil, nil) <> 0 then Exit;
  SDL_RenderPresent(sdlRenderer);

  // Prepare mixer
  if Mix_OpenAudio(MIX_DEFAULT_FREQUENCY, MIX_DEFAULT_FORMAT,
    MIX_DEFAULT_CHANNELS, 4096) < 0 then Exit;

  // Load music
  Music := Mix_LoadMUS('In-my-mind-1.ogg');
  if Music = nil then Exit;
  Mix_VolumeMusic(MIX_MAX_VOLUME);

  // Load sound
  Sound := Mix_LoadWAV('dial-1.wav');
  if Sound = nil then Exit;
  Mix_VolumeChunk(Sound, MIX_MAX_VOLUME);

  while Run = True do
  begin

    SDL_PumpEvents;
    sdlKeyboardState := SDL_GetKeyboardState(nil);

    // ESC pressed
    if sdlKeyboardState[SDL_SCANCODE_ESCAPE] = 1 then
      Run := False;

    // Music effect keys
    if sdlKeyboardState[SDL_SCANCODE_1] = 1 then
      if Mix_PlayMusic(Music, 0) < 0 then Writeln(SDL_GetError);
    if sdlKeyboardState[SDL_SCANCODE_2] = 1 then Mix_PauseMusic;
    if sdlKeyboardState[SDL_SCANCODE_3] = 1 then Mix_ResumeMusic;
    if sdlKeyboardState[SDL_SCANCODE_4] = 1 then Mix_RewindMusic;
    if sdlKeyboardState[SDL_SCANCODE_5] = 1 then
      if Mix_FadeInMusic(Music, 10, 3000) = 0 then Writeln(SDL_GetError);
    if sdlKeyboardState[SDL_SCANCODE_6] = 1 then
      if Mix_FadeOutMusic(3000) = 0 then Writeln(SDL_GetError);

    // Sound effect keys
    if sdlKeyboardState[SDL_SCANCODE_7] = 1 then
      if Mix_PlayChannel(1, Sound, 0) < 0 then Writeln(SDL_GetError);
    if sdlKeyboardState[SDL_SCANCODE_8] = 1 then
      if Mix_PlayChannel(-1, Sound, 0) < 0 then Writeln(SDL_GetError);
    if sdlKeyboardState[SDL_SCANCODE_9] = 1 then Mix_Pause(-1);
    if sdlKeyboardState[SDL_SCANCODE_0] = 1 then Mix_Resume(-1);
    if sdlKeyboardState[SDL_SCANCODE_A] = 1 then
      if Mix_FadeInChannel(1, sound, 0, 2000) < 0 then Writeln(SDL_GetError);
    if sdlKeyboardState[SDL_SCANCODE_S] = 1 then
      if Mix_FadeOutChannel(1, 1000) < 0 then Writeln(SDL_GetError);

    // Channel effect keys
     if sdlKeyboardState[SDL_SCANCODE_G] = 1 then
       if Mix_SetPanning( 1, 255, 32 ) = 0 then Writeln(SDL_GetError);
     if sdlKeyboardState[SDL_SCANCODE_H] = 1 then
       if Mix_SetPanning( 1, 255, 255 ) = 0 then Writeln(SDL_GetError);
     if sdlKeyboardState[SDL_SCANCODE_J] = 1 then
       if Mix_SetDistance( 1, 223 ) = 0 then Writeln(SDL_GetError);
     if sdlKeyboardState[SDL_SCANCODE_K] = 1 then
       if Mix_SetDistance( 1, 0 ) = 0 then Writeln(SDL_GetError);
     if sdlKeyboardState[SDL_SCANCODE_L] = 1 then
       if Mix_SetPosition( 1, 45, 127 ) = 0 then Writeln(SDL_GetError);
     if sdlKeyboardState[SDL_SCANCODE_M] = 1 then
       if Mix_SetPosition( 1, 0, 0 ) = 0 then Writeln(SDL_GetError);

  end;

  // Clean up
  if Assigned(sdlSurface) then SDL_FreeSurface(sdlSurface);
  if Assigned(sdlTexture) then SDL_DestroyTexture(sdlTexture);
  if Assigned(sdlRenderer) then SDL_DestroyRenderer(sdlRenderer);
  if Assigned(sdlWindow) then SDL_DestroyWindow(sdlWindow);
  if Assigned(Music) then Mix_FreeMusic(Music);
  if Assigned(Sound) then Mix_FreeChunk(Sound);

  Mix_CloseAudio;
  SDL_Quit;
end.

When running this program, you’ll get a window with a menue. For this to work, make sure to download the music-menu.bmp file and place it in the program folder.

Let’s start with the first part of the code.


program SDL_MusicSound;
uses SDL2, SDL2_mixer;

var
  sdlWindow: PSDL_Window;
  sdlRenderer: PSDL_Renderer;
  sdlSurface: PSDL_Surface;
  sdlTexture: PSDL_Texture;
  sdlKeyboardState: PUInt8;
  Music: PMix_Music;
  Sound: PMix_Chunk;
  Run: Boolean = True;

begin
  if SDL_Init(SDL_INIT_VIDEO or SDL_INIT_AUDIO) < 0 then Exit;

  // Get window and renderer
  if SDL_CreateWindowAndRenderer(
    640, 640, SDL_WINDOW_SHOWN, @sdlWindow,@sdlRenderer) <> 0 then Exit;

  // Create and render menu texture
  sdlSurface := SDL_LoadBMP('music-menu.bmp');
  if sdlSurface = nil then Exit;
  sdlTexture := SDL_CreateTextureFromSurface(sdlRenderer, sdlSurface);
  if sdlTexture = nil then Exit;
  if SDL_RenderCopy(sdlRenderer, sdlTexture, nil, nil) <> 0 then Exit;
  SDL_RenderPresent(sdlRenderer);

The program is called “SDL”. It uses the SDL2 and the new SDL2_mixer unit.

We’re going to use event handling as discussed in Chapter – Keyboard State and Key States to check what keys have been pressed. Consequently we need a variable “sdlWindow” for the SDL 2.0 window and a keyboard state variable “sdlKeyboardState”.

The pointer variable “Music” is of the new type PMix_Music and points at the loaded music file data later. The “Sound” pointer variable is of type PMix_Chunk and points at the loaded sound file data later. Note: Each song is referenced by an own PMix_Music pointer and each sound effect (e.g. explosions, shots, …) is referenced by an own PMix_Chunk pointer.

What is the difference between music and sound?

Music is associated with PMix_Music pointers and sounds are associated with PMix_Chunk pointers, but why distinguish them at all? – Well, it is convenient to have them separated since they have rather different properties. Music is usually several minutes long, sounds are usually just a few seconds short. It is usually just one song played at a time, sounds need to mix up if necessary. For music it usually doesn’t plays a role if it is sligthly delayed to when it should start, for sounds a larger delay usually means a strange feeling for the player. So, for music there is exactly one channel reserved where the music is played. For sounds eight sound channels are available to make it possible for them to mix up. Now let’s get back to the code.

The variable “Run” is a boolean variable to determine when the main loop of the program should be exited.

The program is initialized by SDL_Init as known. Note though that not only SDL_INIT_VIDEO but additionally SDL_INIT_AUDIO is set. They are combined by the or operator (not the and operator :-)!).  The window is set up afterwards by SDL_CreateWindow as known. Also the menu texture file is created and renderered as known. Check Chapter – Loading and rendering a Bitmap file as a reminder, in case.


  // Prepare mixer
  if Mix_OpenAudio(MIX_DEFAULT_FREQUENCY, MIX_DEFAULT_FORMAT,
    MIX_DEFAULT_CHANNELS, 4096) < 0 then Exit;

  // Load music
  Music := Mix_LoadMUS('In-my-mind-1.ogg');
  if Music = nil then Exit;
  Mix_VolumeMusic(MIX_MAX_VOLUME);

  // Load sound
  Sound := Mix_LoadWAV('dial-1.wav');
  if Sound = nil then Exit;
  Mix_VolumeChunk(Sound, MIX_MAX_VOLUME);

To initialize SDL2_mixer

function Mix_OpenAudio(frequency: cint; format: cuint16; channels: cint; chunksize: cint): cint

has to be called. It requests four parameters. These are the frequency, the audio format, the channels (mono or audio) and the chunksize. All these parameters are of Integer type. Function Mix_OpenAudio returns 0 on success and -1 on errors.

The frequency in Hertz (1/s) usually is 22050 Hz or MIX_DEFAULT_FREQUENCY in games but double as high for CD quality sound (44100 Hz). The higher the frequency, the more CPU power is needed.

Next we have to define the audio format. It determines how the audio data is stored. MIX_DEFAULT_FORMAT equals AUDIO_S16SYS. Different values are given in the following list (from official SDL2_mixer documentation):

  • Format constant name Description
  • AUDIO_U8 Unsigned 8-bit samples
  • AUDIO_S8 Signed 8-bit samples
  • AUDIO_U16LSB Unsigned 16-bit samples, in little-endian byte order
  • AUDIO_S16LSB Signed 16-bit samples, in little-endian byte order
  • AUDIO_U16MSB Unsigned 16-bit samples, in big-endian byte order
  • AUDIO_S16MSB Signed 16-bit samples, in big-endian byte order
  • AUDIO_U16 same as AUDIO_U16LSB (for backwards compatability probably)
  • AUDIO_S16 same as AUDIO_S16LSB (for backwards compatability probably)
  • AUDIO_U16SYS Unsigned 16-bit samples, in system byte order
  • AUDIO_S16SYS Signed 16-bit samples, in system byte order

Then we decide for a sound channel type, which means either stereo or mono. For stereo sound we choose 2 and for mono we choose 1 as value. MIX_DEFAULT_CHANNELS equals stereo output.

Finally the chunksize has to be set, where 4096 bytes per sample is a good and default value. Too low values may lead to skipping samples. Too high values may lead to delayed playing.

Loading music and sounds from files in SDL 2.0

We will load the music by

function Mix_LoadMUS(_file: PAnsiChar): PMix_Music.

_file can be the absolute path. If the Pascal file and the music file are in the same folder the file name is sufficient (as shown in the example). If the loading was unsuccessful, the function returns nil. The volume can be set by

function Mix_VolumeMusic(volume: cint): cint.

The volume can be set between 0 (silence) to 128 (maximum volume). The latter equals MIX_MAX_VOLUME. By the way, if you set -1 as argument, the return value corresponds to the set volume.

Quite similar sound files are loaded by

function Mix_LoadWAV(_file: PAnsiChar): PMix_Chunk.

Although the function’s name doesn’t indicate this, use this function to load the sound files of any format (Wave, Aiff, Riff, Ogg, Voc), not only for .wav sound files. It return nil on error. There is alittle difference when setting the volume by

function Mix_VolumeChunk(chunk: PMix_Chunk; volume: cint): cint.

Instead of just setting a general volume, the volume is bound to a certain sound. In the example case the sound is in variable “sound”. Just to mention it here, there is a third possibility, to set the volume for a certain channel:

function Mix_Volume(channel: cint; volume: cint): cint.

This can be quite handy, anyway, channels are discussed a little bit later below. If your argument is -1 the average volume will be returned.

Playing, pausing, resuming music and sounds


  while Run = True do
  begin

    SDL_PumpEvents;
    sdlKeyboardState := SDL_GetKeyboardState(nil);

    // ESC pressed
    if sdlKeyboardState[SDL_SCANCODE_ESCAPE] = 1 then
      Run := False;

    // Music effect keys
    if sdlKeyboardState[SDL_SCANCODE_1] = 1 then
      if Mix_PlayMusic(Music, 0) < 0 then Writeln(SDL_GetError);
    if sdlKeyboardState[SDL_SCANCODE_2] = 1 then Mix_PauseMusic;
    if sdlKeyboardState[SDL_SCANCODE_3] = 1 then Mix_ResumeMusic;
    if sdlKeyboardState[SDL_SCANCODE_4] = 1 then Mix_RewindMusic;
    if sdlKeyboardState[SDL_SCANCODE_5] = 1 then
      if Mix_FadeInMusic(Music, 10, 3000) = 0 then Writeln(SDL_GetError);
    if sdlKeyboardState[SDL_SCANCODE_6] = 1 then
      if Mix_FadeOutMusic(3000) = 0 then Writeln(SDL_GetError);

    // Sound effect keys
    if sdlKeyboardState[SDL_SCANCODE_7] = 1 then
      if Mix_PlayChannel(1, Sound, 0) < 0 then Writeln(SDL_GetError);
    if sdlKeyboardState[SDL_SCANCODE_8] = 1 then
      if Mix_PlayChannel(-1, Sound, 0) < 0 then Writeln(SDL_GetError);
    if sdlKeyboardState[SDL_SCANCODE_9] = 1 then Mix_Pause(-1);
    if sdlKeyboardState[SDL_SCANCODE_0] = 1 then Mix_Resume(-1);
    if sdlKeyboardState[SDL_SCANCODE_A] = 1 then
      if Mix_FadeInChannel(1, sound, 0, 2000) < 0 then Writeln(SDL_GetError);
    if sdlKeyboardState[SDL_SCANCODE_S] = 1 then
      if Mix_FadeOutChannel(1, 1000) < 0 then Writeln(SDL_GetError);

The main application loop is entered and should be left if variable “Run” is false which is achieved by pressing the ESCAPE key.

For each key state a different music or sound related function is used to do something. Let’s discuss them now in detail. We start with the functions triggered by the keys 1 – 4:

function Mix_PlayMusic(music: PMix_Music; loops: cint): cint 
procedure Mix_PauseMusic 
procedure Mix_ResumeMusic 
procedure Mix_RewindMusic

Mix_PlayMusic plays music. The first argument is the music itself which we previously got from the example .ogg music file and associated with the “Music” pointer of PMix_Music type. The second argument determines how often the music is played. Additionally -1 means infinite repetition. This function returns 0 on success and -1 on error.

The meaning of the three procedures Mix_PauseMusic, Mix_ResumeMusic and Mix_RewindMusic ist obvious from their names. They are used to pause, resume (if paused before) and rewind the played music.

The analogous function and procedures for sound channels triggered by the keys 7 – 9 and 0 are shown now:

function Mix_PlayChannel(channel: cint; chunk: PMix_Chunk; loops: cint): cint
procedure Mix_Pause(channel: cint) 
procedure Mix_Resume(channel: cint)

As you can see the function Mix_PlayChannel has three parameters. The first parameter asks for a channel with which the sound should be associated. SDL2_mixer provides eight sound channels. Usually you should use -1 which means the first free channel will be used to play the sound. Anyway, you could specifiy a certain channel here if you like. The second parameter asks for a sound pointer of PMix_Chunk type. The  third parameter is the same as for music, -1 means an infinite loop. Attention though for specific repetitions. The value for loops is increased by 1. So, if you want a sound to be played once, you need the argument to be 0. The return value corresponds to the sound channel the sound is played on, it is -1 on error.

The procedures Mix_Pause and Mix_Resume are self-explanatory. Use them to pause or resume a certain channel, which is the argument. If the argument is -1 (as in the example code) you pause or resume all channels. By the way, you may have noticed that there is not a rewind analogue, because sounds are not expected to be rewound.

Fading effects


...

    if sdlKeyboardState[SDL_SCANCODE_5] = 1 then
      if Mix_FadeInMusic(Music, 10, 3000) = 0 then Writeln(SDL_GetError);
    if sdlKeyboardState[SDL_SCANCODE_6] = 1 then
      if Mix_FadeOutMusic(3000) = 0 then Writeln(SDL_GetError);

    // Sound effect keys
    
...
    
    if sdlKeyboardState[SDL_SCANCODE_A] = 1 then
      if Mix_FadeInChannel(1, sound, 0, 2000) < 0 then Writeln(SDL_GetError);
    if sdlKeyboardState[SDL_SCANCODE_S] = 1 then
      if Mix_FadeOutChannel(1, 1000) < 0 then Writeln(SDL_GetError);

    // Channel effect keys
     if sdlKeyboardState[SDL_SCANCODE_G] = 1 then
       if Mix_SetPanning( 1, 255, 32 ) = 0 then Writeln(SDL_GetError);
     if sdlKeyboardState[SDL_SCANCODE_H] = 1 then
       if Mix_SetPanning( 1, 255, 255 ) = 0 then Writeln(SDL_GetError);
     if sdlKeyboardState[SDL_SCANCODE_J] = 1 then
       if Mix_SetDistance( 1, 223 ) = 0 then Writeln(SDL_GetError);
     if sdlKeyboardState[SDL_SCANCODE_K] = 1 then
       if Mix_SetDistance( 1, 0 ) = 0 then Writeln(SDL_GetError);
     if sdlKeyboardState[SDL_SCANCODE_L] = 1 then
       if Mix_SetPosition( 1, 45, 127 ) = 0 then Writeln(SDL_GetError);
     if sdlKeyboardState[SDL_SCANCODE_M] = 1 then
       if Mix_SetPosition( 1, 0, 0 ) = 0 then Writeln(SDL_GetError);

  end;

Important to know about effects like fading. They are performed on the fly to your data, so the more effects you use, the more computational power they require. It is important to unregister effects you don’t need anymore.

These are the four fade functions triggered by the keys 5, 6, A and S :

function Mix_FadeInMusic(music: PMix_Music; loops: cint; ms: cint): cint 
function Mix_FadeOutMusic(ms: cint): Integer 
function Mix_FadeInChannel(channel: cint; chunk: PMix_Chunk; loops: cint; ms: cint): cint
function Mix_FadeOutChannel(which: cint; ms: cint): cint

The function Mix_FadeInMusic works the very same way as Mix_PlayMusic above, but there is a further parameter which allows for a fade in effect in milliseconds. 3000 milliseconds equals 3 seconds. It returns 0 on success and -1 on error.

Mix_FadeOutMusic fades out the playing music within the given time in milliseconds in the moment the function is called (hence the key is pressed in the example program). Attention, it returns 1 on success and 0 on error.

Quite similar the functions Mix_FadeInChannel and Mix_FadeOutChannel work. Instead of the music pointer, the sound pointer and the channel has to be given. By the way, also here the number of times the sound is played is increased by 1, so if you want to play a sound with fade in effect once, the argument has to be 0. The fade effect applies only for the first run. Both functions return 0 on success and -1 on error.

Panning and distance effects

The functions triggered by the keys G – M are:

function Mix_SetPanning(channel: cint; left: cuint8; right: cuint8): cint

For setting the panning you need the channel to which panning should be applied and the volume values which may vary from 0 (quiet) to 255 (loudest). For a consistent panning effect you may substract the left value from the right value (left: volume, right: 255-volume). To unregister this effect, you should set both values to 255, which is recommended to be done if you don’t need panning anymore. The function returns 0 on errors.

function Mix_SetDistance(channel: cint; distance: cuint8): cint

The higher the distance, the quieter the sound appears. The value can range between 0 (near) and 255 (far). If distance is set to 0 the effect is unregistered. It returns 0 on errors.

function Mix_SetPosition(channel: cint; angle: cint16; distance: cuint8): cint

This function adjusts volumes according to an angle and a distance value, hence it combines the effects of the two functions discussed before for panning and distance. The distance value works the same way as discussed for Mix_SetDistance. Angle of 0 (degree) means in front of you, 90 means directly to the right, 180 means directly behind, 270 means directly to the left.

Closing the SDL2 mixer and clean up


  // Clean up
  if Assigned(sdlSurface) then SDL_FreeSurface(sdlSurface);
  if Assigned(sdlTexture) then SDL_DestroyTexture(sdlTexture);
  if Assigned(sdlRenderer) then SDL_DestroyRenderer(sdlRenderer);
  if Assigned(sdlWindow) then SDL_DestroyWindow(sdlWindow);
  if Assigned(Music) then Mix_FreeMusic(Music);
  if Assigned(Sound) then Mix_FreeChunk(Sound);

  Mix_CloseAudio;
  SDL_Quit;
end.

For the clean up the surface, textre renderer and the window are destroyed as known. New are the procedures Mix_FreeMusic and Mix_FreeChunk to free the music and sound data.

procedure Mix_FreeMusic(music: PMix_Music)
procedure Mix_FreeChunk(chunk: PMix_Chunk)

The arguments have to be the music and sound pointer respectively.

SDL_mixer 2.0 has to be closed by

procedure Mix_CloseAudio.

Finally SDL 2.0 and the application are shut down as known.

← previous Chapter | next Chapter →

Chapter 1 – Introduction

Last updated on July 22nd, 2020

The introduction is short.

What is SDL or rather SDL2?

SDL abbreviates Simple Direct Media Layer. In August 2013 the official successor of original SDL (SDL 1.2) has been released, simply called SDL2 (or SDL 2.0). It is a library to develop powerful applications for many different operating systems (platforms) by learning only one set of commands. This is called cross-platform development. The following platforms are officially supported by SDL2:

  • Windows
  • Mac OS X
  • Linux
  • iOS
  • Android.

Internally the SDL library layer translates your commands to the platform specific commands, which is reflected by the followig diagram.

SDL2 Layers Diagram
Image by Adriatikus at English Wikipedia [Public domain], Wikimedia
SDL2 Layer Diagram

It’s especially meaningful to use the SDL library if you plan to develop games or need fast paced rendering. Jump and run-, Role-playing-, Real time/turn based strategy-, side-scrolling-, arcade-, board-, card-, simulation-, multi-user dungeon-, puzzle-, shooter-, network games and so on are possible, and any combination of these ;-).

Licensing

The SDL2 library, as well as the units for translation, are licensed under the zlib license. This license grants a high degree of freedom. So even closed-source, commercial applications and games are possible with SDL2 and Free Pascal. As a sidenote, you are free to choose the MPL license for the units, if you like.

How to get SDL2 for Free Pascal or Object Pascal?

There are several SDL2 units out there (see comparison and discussion here) which translate SDL2 to Pascal, since originally it has been written in C. Over time it turned out that the PGD community SDL2 units are the best choice to use if you like to get into SDL2 development in Free Pascal or Object Pascal.

A detailed installation instruction to set your system up for SDL2 development under Pascal is found in Chapter 2 for Windows or Linux. If you did install SDL2 for Free Pascal or Object Pascal already, proceed to Chapter 3. Please choose:

Chapter 2 (Windows) → | Chapter 2 (Linux) → | Chapter 3 →

Chapter 2 – Installation and Configuration

Last updated on July 22nd, 2020

What is covered, what not?

  • installation guide for SDL 2.0 under Microsoft Windows
  • installation of Free Pascal Compiler (FPC)
  • installation of Free Pascal IDE and Lazarus IDE
  • installation of SDL 2.0
  • configuration of FP IDE and Lazarus IDE to work with SDL 2.0
  • after this you are ready to code awesome SDL 2.0 stuff 🙂

Free Pascal IDE or Lazarus IDE

IDE stands for integrated development environment. Although you could write your programs in a simple text editor, an IDE makes your life much easier. For example, it highlights keywords, makes it easier for you to set up the compiler, and much more. Now let’s have a look at these two IDEs:

You may notice that the native Free Pascal IDE (left) looks old, but it is shipped right along with the Free Pascal Compiler. In contrast to that the Lazarus IDE (right) looks up-to-date, but requires it to be installed additionally. My advise is nonetheless, use the Lazarus IDE.

The Free Pascal Compiler (FPC)

We need three different software packages. First of all we need the stand-alone Free Pascal Compiler or Lazaruse IDE (which already has a copy of the Free Pascal Compiler included). If you are not sure, I recommend to go with the Lazarus IDE package.

SDL Library and SDL 2.0 units

Additionaly we need the original SDL library files (.dll files). And finally we need units that connect our SDL 2.0 code written in Free Pascal to the SDL library files. The latter will be done by SDL 2.0 units.

This table provides all information and sources you need with respect to installation steps 1) – 3). Keep in mind, you have to download either the Lazarus IDE or the stand-alone Free Pascal Compiler, not both.

Software,
Version,
approx. Size [MB]
Filenames,
Source link
Details and remarks
Lazarus IDE (has FPC included)
1.4.4 or later
N/A
lazarus-1.4.4-fpc-2.6.4-win32.exe
http://www.lazarus-ide.org/index.php?page=downloads
Linux and Mac OS X versions are here: http://www.lazarus-ide.org (see Downloads).
Free Pascal Compiler (stand-alone)
3.0.0 or later
22-40
fpc-3.0.0.i386-win32.exe
Windows 32 bit version
fpc-3.0.0.i386-win32.cross.x86_64-win64.exe
Windows 64 bit version (needs 32 bit version)
If you need the Linux, Mac OS X or other versions, check them out here: http://www.FreePascal.org (see Download).
SDL 2.0 units
1.72* (see remark)
0.1
Pascal-SDL2-for-Pascal-master.zip
https://github.com/PascalGameDevelopment/SDL2-for-Pascal
On the right upper side is a button saying Download ZIP. Click on this button for the download of the latest release. *Better go with the latest availabe version (not version 1.72!) since some important bugfixes have been made lately.
SDL 2.0 dynamic link library
2.0.4
0.35
SDL2-2.0.4-win32-x86.zip
SDL2-2.0.4-win32-x64.zip
http://www.libsdl.org
SDL 2.0 > Download > Choose the download suitable for your system.

Download Lazarus or the stand-alone Free Pascal Compiler (FPC)

If you have Free Pascal or the Lazarus IDE installed already, you can skip the steps 1a) and 1b).

1a) For Lazarus IDE: Download the latest version of the Lazarus IDE. It has the Free Pascal Compiler accompanied. Remark: As of today (12/02/2016) the bundle doesn’t provide the most recent Free Pascal Compiler (3.0.0) but the version before (2.6.4). The tutorial examples will work with both versions though.

1b) For Free Pascal IDE: 32 bit Windows: Download the latest stable Free Pascal compiler, version 3.0.0 or higher. 64 bit Windows: You have two choices, 1) Simple way: Go with the 32 bit version of Free Pascal. (Recommended), 2) Install the 64 bit version of Free Pascal on top of the 32 bit version of Free Pascal. In this case you need both files. Hence, you need to download both Free Pascal installers shown above.

Download SDL 2.0 and Header translation

2) Download the latest version of Tim Blume’s SDL 2.0 units, better go with the latest branch (master branch), and do not use version 1.72 since it contains some bugs. Click on “Clone or download” and then on “Download ZIP” (see arrows in image below) of the page and make sure that Branch: master (not v1.72!) is chosen at the left side (see arrow in image below). This is important for any operating system: Windows, Linux, Mac OS X.

Download SDL2 units on GitHub
Choose the master branch (1), click on “Clone or download” (2) and click on Download ZIP (3).

3) Download the latest version of SDL 2.0 runtime library, version 2.0.4 or higher.

Install Lazarus or the Free Pascal Compiler

4a) For Lazarus: 32 and 64 bit Windows: Execute lazarus-1.4.4-fpc-2.6.4-win32.exe  to install Lazarus for a 32 bit or 64 bit Windows system and follow the self-installer. Let the self-installer create a shortcut on your desktop.

4b) For Free Pascal IDE: 32 and 64 bit Windows: Execute fpc-2.6.4.i386-win32.exe  to install Free Pascal for a 32 bit or 64 bit Windows system. Let the self-installer create a shortcut on your desktop. Don’t modify any checked options during installation process. The default path is: C:\FPC\[Compiler version]\. [Compiler version] should be 3.0.0 or higher numbers. 64 bit Windows only: After you installed the 32 bit Free Pascal, you may execute fpc-3.0.0.i386-win32.cross.x86_64-win64.exe optionally to add the 64 bit version on top.

Install SDL 2.0 and Header translation

5) Extract SDL2-2.0.4-win32-x86.zip or SDL2-2.0.4-win32-x64.zip to get the SDL runtime library. This leads to two extracted files. There is a text file and the very important SDL2.dll.

6) 32bit Windows: Copy those files (especially the SDL2.dll!) to your system32-folder, C:\WINDOWS\system32\. 64bit Windows:  Copy those 64bit files to your system32-folder (!), C:\WINDOWS\system32\, Windows is expecting you to do this. Do not use the SysWoW64-folder (Hint: 32 bit files on 64 bit Windows go here).

If it is not possible to copy the files into this folder (or you are unsure about its location) alternativly you can copy the SDL2.dll right into the same folder where the SDL 2.0 application (.exe) is located. That is because SDL 2.0 first  looks for the SDL2.dll in the folder from which it is executed and if it isn’t found there, in the corresponding system folder! Anyway, if it isn’t found anywhere, the program will raise an error.

Now you have installed Free Pascal and the SDL runtime library on your system. Finally SDL 2.0 units have to be installed.

7a) For Lazarus IDE: Extract the SDL2-for-Pascal-master.zip. The Free Pascal Compiler is located in a subfolder called “fpc”. I suggest to copy all the files to a folder with full path C:\Lazarus\fpc\[Compiler Version]\units\SDL2\. [Compiler version] should be 2.6.4 or higher numbers. Skip step 7b).

7b) For Free Pascal IDE: Extract the SDL2-for-Pascal-master.zip. I suggest to copy all the files to a folder with full path C:\FPC\[Compiler Version]\units\SDL2\. [Compiler version] should be 3.0.0 or higher numbers. All later chapters will assume you installed to this path.

Configuring the Lazarus IDE

Now the compiler has to be told where to find the new units.

8) Open the Free Pascal IDE (for example by clicking the shortcut on desktop).

Lazarus IDE Desktop Icon

9) In Lazarus the path to external units has to be set for each project. Create a project if no project is set up (Project > New Project …). In the menue choose the following item Project > Project Options …. Now a window should pop up.

10) Under “Compiler Options” choose “Paths” (see red mark). Choose the three dots button (see red mark on the right side) for the “Other units files (-Fu)” field (red mark). This makes the “Path Editor” pop up. In the area “Search paths:”, click on the yellow folder symbol in the right bottom corner. Choose the path to your SDL-units (e.g. C:\Lazarus\2.6.4\units\SDL2). Make sure the path leads to the folder, where the sdl2.pas file is located! This file contains all the basic features of SDL 2.0.

Lazarus IDE Include Paths

Confirm by clicking “OK” until all windows are closed. Your Lazarus IDE is now set up for SDL 2.0 application development :-)!

Configuring the Free Pascal IDE (skip if you use Lazarus)

Now the compiler has to be told where to find the new units.

8) Open the Free Pascal IDE (for example by clicking the shortcut on desktop).

Free Pascal IDE Desktop Icon

9) In the menue choose the following item Options > Directories…. Now a window should pop up.

10) The first tab whitin this new window is called “Units”. Here you add the full path to your SDL-units (e.g. C:\FPC\3.0.0\units\SDL2) right below the other paths. Leave the last backslash out. Make sure the path leads to the folder, where the sdl2.pas file is located! This file contains all the basic features of SDL 2.0.

SDL2 directories
Since the screenshot is old, the compiler version has been 2.6.2, which is reflected in the shown pathes. It should be 3.0.0 or higher numbers for you.

Confirm by clicking “OK”.

Finally

Congratulations! You have configured your system for developing SDL 2.0 applications with the Lazarus IDE or the Free Pascal IDE! Simple, isn’t it? 🙂

For those of you who try running a program and get an abortion together
with a messege saying “exitcode = 309”: You skipped step 6! Did you copy
the SDL2.dll to your system32- or system-folder respectively? If so and the
error still occurs you should copy the SDL2.dll into the folder
where the programs are placed. Now it should work.

← Chapter 1 | Chapter 3 →

First Steps

Last updated on November 21st, 2021

For this tutorial it is presumed, that you are familiar with procedures, functions, loops, pointers and usual commands of Free Pascal or its dialects. If this is not the case you may face problems because this tutorial deals with the features and usage of the SDL 2.0 library and will not explain basic concepts of Pascal programming. For a quick refresh on some Pascal basics, have a look into this (good) article Modern Object Pascal Introduction For Programmers by Michalis Kamburelis.

You can easily copy the example source code directly from the source code box for each chapter.

The SDL2 unit and the first application

program FirstSteps;

uses SDL2;

begin

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

    {your SDL2 application/game}

  //shutting down video subsystem
  SDL_Quit;

end. 

That’s it, your first SDL2 program. You may copy the code directly in your environment and run it. It should work without any errors if everything is set up correctly. The most important rule to get ready for SDL 2.0 in your Pascal programs is obviously:

Always include the SDL2 unit in the uses clause.

The SDL2 unit is the heart of every SDL 2.0 application! If you do so, you are perfectly prepared to start coding.

The different features of SDL 2.0 (screen/video handling, audio handling, keyboard handling, and so on) have to be initilized individually using this function:

function SDL_Init(flags: TSDL_Init): cint.

It will return 0 on success and a negative error code on failure. The return value is of integer type cint. What this means, we will discuss later.

In the first example we initialize the SDL 2.0 video subsystem for screen handling by using the flag SDL_INIT_VIDEO. Instead of SDL_INIT_VIDEO you could initilize the respective subsystem by using SDL_INIT_AUDIO for audio subsystem, SDL_EVENTS for event subsystem, and so on. What subssystem you need to initialize depends on what you want to do. The table shows an overview of all the possible flags and their meaning:

FlagDescription
SDL_INIT_TIMERInitilizes timer subsystem for handling of time related events.
SDL_INIT_AUDIOInitilizes audio subsystem for playing music or sound effects.
SDL_INIT_VIDEOInitilizes video subsystem for drawing/showing/manipulating of graphics, textures and screen, usually the most important subsystem.
SDL_INIT_JOYSTICKInitilizes joystick subsystem for handling of joysticks.
SDL_INIT_HAPTICInitilizes haptic (force feedback) subsystem.
SDL_INIT_GAMECONTROLLERInitilizes game controller subsystem.
SDL_INIT_EVENTSInitilizes events subsystem for handling of mouse or keyboard input.
SDL_INIT_EVERYTHINGInitilizes all the subsystems above.
SDL_INIT_NOPARACHUTEIgnores fatal signals. In SDL2 this is set by default and it isn’t possible to change this state. The explanation is given in the official migration guide I will cite here:There’s no SDL parachute anymore. What 1.2 called SDL_INIT_NOPARACHUTE is a default and only state now. This would cause problems if something other than the main thread crashed, and it would interfere with apps setting up their own signal/exception handlers. On the downside, some platforms don’t clean up fullscreen video well when crashing. You should install your own crash handler, or call SDL_Quit() in an atexit() function or whatnot if this is a concern. Note that on Unix platforms, SDL still catches SIGINT and maps it to an SDL_QUIT event.
List of subsystem flags.

Of course you are allowed to combine several subsystem flags by OR, e.g. “SDL_Init(SDL_INIT_VIDEO OR SDL_INIT_AUDIO)” to initilize video and audio support. If you are running some subsystems already but need to load further ones you would use

function SDL_InitSubSystem(flags: TSDL_Init): cint

respectivly. Again 0 ist returned on success and the negativ error code in case of failure.

The flag SDL_INIT_EVERYTING will initialize all subsystems. Use this if you are unsure on what subsystem you should use, although it will need a little bit more resources.

Quitting your programs

Every SDL program has to be closed by

procedure SDL_Quit.

It cleans up your system. Never forget it! This procedure ensures that all subsystems initilized get unloaded. There is a corresponding procedure to unload specific subsystems defined as

procedure SDL_QuitSubSystem(flags: TSDL_Init).

You are allowed to quit two or more subsystems by this function by using OR operator. It is advised to always quit SDL 2.0 applications by SDL_Quit even if you quit all of them individually by SDL_QuitSubSystem before.

Try the example program. You will not see much but if you didn’t get an error message you are successful. Before proceeding, let’s have a quick look into error handling.

C variable types

You may wonder about the return value cint in the SDL_Init function declaration. This and other similar types (which we will see in other chapters again) originate from the original C-language in which SDL2 has been written. cint simply means a C integer variable. Similar to a Pascal integer, a C integer can be different in memory size depending on your system and that is why it is important to know exactly with which variable types you are working. Further examples: cuint8 is a C unsigned integer of 8 bit size, cint32 is a C signed integer of 32 bit size, cfloat is a C float point variable, and so on.

In Free Pascal they are correctly translated to the corresponding Pascal variable type by the ctypes unit. In Delphi this is done by a ctypes.inc file shipped with the units.

As a beginner working with the units, you don’t have to be too concerned with these details, but now you know why these variable types have these names.

SDL 2.0 functions and errors

Every SDL 2.0 function returns an error value for you to check if the function runs properly at runtime. The values returned are of integer or pointer type. There is no general rule what values correspond to which status. In SDL 2.0 usually an integer value of 0 means “function runs/ran succesfully”, values lower than 0 correspond to a status “function couldn’t be run, something is wrong”. For pointers nil means error and any non-nil pointer means success. However, in most cases I won’t do error checking in the examples to keep the code short. I will mention the error values to be expected though.

You should know that there is a function called

SDL_GetError: PAnsiChar

which translates the last error received into a message (of type PAnsiChar) that can be read out and printed to the screen by any function that can handle strings as well (e.g. the Pascal’s common write() function). Since SDL 2.0 is written in C originally, the PAnsiChar type is used in contrast to the String type (which is more common among Pascal programmers for message storage and handling).

A quick way to return the error message is to use the SDL2 message box feature:

function SDL_ShowSimpleMessageBox(flags: TSDL_MessageBoxFlags; title: PAnsiChar; _message: PAnsiChar; window: PSDL_Window): cint

The flags for the message box could be:

  • SDL_MESSAGEBOX_ERROR
  • SDL_MESSAGEBOX_WARNING
  • SDL_MESSAGEBOX_INFORMATION
  • SDL_MESSAGEBOX_BUTTONS_LEFT_TO_RIGHT
  • SDL_MESSAGEBOX_BUTTONS_RIGHT_TO_LEFT

While the flags indicate the reason for the message box, the title and the message argument are used to set a box title and a message. The window argument can be set to the nil pointer.

The following short code snippet demonstrates a convenient way of using the box for showing error messages in the case of SDL2 initialization as done above.

//initilization of video subsystem
if SDL_Init(SDL_INIT_VIDEO) < 0 then 
begin
  SDL_ShowSimpleMessageBox(SDL_MESSAGEBOX_ERROR, 'Error Box',  SDL_GetError, nil);
  Exit;
end;

Well, we have initilized the video subsystem and released it afterwards, and we learned about showing error messages in a simple message box. Simple Directmedia Layer deserves its name, doesn’t it?

Only if you agree, you may proceed to the next chapter ;-)!

← Chapter 2 (Windows) | ← Chapter 2 (Linux) | next Chapter →

What is SDL and SDL2?

SDL is the abbreviation of Simple DirectMedia Layer.

Originally when refering to SDL, SDL 1.2 was meant. It is the predecessor of modern SDL 2.0 (sometimes SDL2). Nowadays, when refering to SDL, it depends on context if you really mean the old SDL 1.2 or the modern SDL 2.0.

The  obsolete SDL 1.2 and the modern SDL 2.0 are a set of units which provide a free, easy and platform-independent access to features needed for developing high performance games and applications. This includes easy access to graphic, sound and input handling (keyboard, mouse, joystick) for Free Pascal and other Pascal dialects.

Who made SDL and SDL2?

SDL was developed between 1998 and 2001 by Sam Lantinga, the chief programmer of the software company Loki Games. In 2002 the company got bankrupt, but Lantinga went on developing SDL. So it got updated continuously  until today.

In August 2013 the successor SDL 2.0 has been released. SDL 2.0 introduces a lot of new features which allow development of high performance applications using up-to-date technologies.

Although the original library isn’t written in Pascal, fortunately the SDL 2.0 headers got translated to Pascal by Tim Blume and others, so the SDL 2.0 library is usable for Pascal developers as well.

What is this page about?

This page is made to help you to start with the SDL and/or SDL2 (Simple Directmedia Layer) library under Free Pascal (or other Pascal dialects) and to acquaint yourself with SDL’s concepts and commands.

Be aware though that my tutorials gives just a brief overview and introduction to the SDL and SDL2 library and are far from being all-embracing.

The tutorials aim at Pascal programmers knowing the basic concepts (loops, functions, pointers) of Pascal and now like to progress to SDL and/or SDL2.

Drawing Primitives

Last updated on November 20th, 2021

Displaying of textures as discussed in previous chapters are sometimes accompanied by drawing operations. For some applications and games drawing operations are even essential, e.g. you need to draw buttons of dynamic dimension in your application. Discussion of a more detailed case is found right after the code example.

Supported Primitives: Points, Lines, Rectangles

SDL2 supports natively the drawing of

  • Points
  • Lines
  • Rectangles (outline only)
  • Filled Rectangles.

Drawing in SDL 2.0

Now lets jump right into the code:

program Chapter5_SDL2;

uses SDL2;

var
  i: Integer;
  sdlWindow1: PSDL_Window;
  sdlRenderer: PSDL_Renderer;
  sdlRect1: TSDL_Rect;
  sdlPoints: array[0..499] of TSDL_Point;

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

  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;

  //render and show cleared window with background color
  SDL_SetRenderDrawColor(sdlRenderer, 0, 255, 255, 255);
  SDL_RenderClear(sdlRenderer);
  SDL_RenderPresent(sdlRenderer);
  SDL_Delay(1000);

  //render and show a line
  SDL_SetRenderDrawColor(sdlRenderer, 255, 0, 0, 255);
  SDL_RenderDrawLine(sdlRenderer, 10, 10, 490, 490);
  SDL_RenderPresent(sdlRenderer);
  SDL_Delay(1000);

  //render and draw points diagonally with distance between each other
  SDL_SetRenderDrawColor(sdlRenderer, 0, 0, 0, 255);
  for i := 0 to 47 do
    SDL_RenderDrawPoint(sdlRenderer, 490-i*10, 10+i*10);
  SDL_RenderPresent(sdlRenderer);
  SDL_Delay(1000);

  //prepare, render and draw a rectangle
  sdlRect1.x := 260;
  sdlRect1.y := 10;
  sdlRect1.w := 230;
  sdlRect1.h := 230;
  SDL_SetRenderDrawColor(sdlRenderer, 0, 255, 0, 255);
  SDL_RenderDrawRect(sdlRenderer, @sdlRect1);

  //relocate, render and draw the rectangle
  sdlRect1.x := 10;
  sdlRect1.y := 260;
  SDL_SetRenderDrawBlendMode(sdlRenderer, SDL_BLENDMODE_BLEND);
  SDL_SetRenderDrawColor(sdlRenderer, 0, 0, 255, 128);
  SDL_RenderFillRect(sdlRenderer, @sdlRect1);
  SDL_RenderPresent(sdlRenderer);
  SDL_Delay(1000);

  //prepare, render and draw 500 points with random x and y values
  Randomize;
  for i := 0 to 499 do
  begin
    sdlPoints[i].x := Random(500);
    sdlPoints[i].y := Random(500);
  end;
  SDL_SetRenderDrawColor(sdlRenderer, 128, 128, 128, 255);
  SDL_RenderDrawPoints(sdlRenderer, sdlPoints, 500);
  SDL_RenderPresent(sdlRenderer);
  SDL_Delay(3000);

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

  //shut down SDL2
  SDL_Quit;
end.

Wow, that looks like a big load of new functions, but I promise, drawing in SDL2 is very simple. What the executed program will look like is shown in the following screenshot.

Result screenshot for chapter 5

Now, let’s have a closer look to the first lines of code.

program Chapter5_SDL2;

uses SDL2;

var
  i: Integer;
  sdlWindow1: PSDL_Window;
  sdlRenderer: PSDL_Renderer;
  sdlRect1: TSDL_Rect;
  sdlPoints: array[0..499] of TSDL_Point;

The program is called “Chapter5_SDL2”. We will need a counter variable “i” of native Pascal type integer later. We need a window and a renderer and call them “sdlWindow1” and “sdlRenderer” as known from the previous chapters. Next we declare a variable “sdlRect1” which is of type TSDL_Rect. The same is true for “sdlPoints” which is an array of 500 elements of type TSDL_Point.

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

  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;

Nothing new here, we initilize SDL2, create a window with 500 pixels width and 500 pixels height and associate the renderer with this window.

Colours, alpha value and RGB(A) notation in SDL 2.0

  //render and show cleared window with background color
  SDL_SetRenderDrawColor(sdlRenderer, 0, 255, 255, 255);
  SDL_RenderClear(sdlRenderer);
  SDL_RenderPresent(sdlRenderer);
  SDL_Delay(1000);  

Now we have something new here, SDL_SetRenderDrawColor() sets a colour for drawing operations, just as if you choose for a pencil colour to draw something. This function doesn’t draw anything though. It returns 0 on success and the negative error code on failure.

SDL_SetRenderDrawColor(renderer: PSDL_Renderer; r: UInt8; g: UInt8; b: UInt8; a: UInt8): SInt32

First you need to set the renderer for which this drawing colour is meant. After that you have to set the colours red, green, blue and the alpha value. They can range from 0 to 255 (integer values only). Think in terms of 255 being 100% and 0 being 0% of that colour or the alpha value. As a start let’s neglect the alpha value.

If you like to have a red colour, you need to set the value for the red colour high, e.g. 100%, the maximum value is 255, and since you don’t want to mix in green and blue, they get the minimum value of 0 (hence 0%). Setting up red therefore corresponds to 255/0/0 in terms of r/g/b. For comparision, 0/255/0 will lead to green, 255/255/255 is white and 0/0/0 is black, and so on. In the example code we used 0/255/255 which leads to cyan (mixing up green and blue additively). With these three values you can generate every colour possible.

So what is the meaning of the alpha value then? Well, it determines the transparency. 255 means fully opaque and 0 means full transparency. This is very important for blend effects in computer graphics and will be demonstrated later on in the code. By the way, instead of 255 you could use SDL_ALPHA_OPAQUE. If you count the alpha value also as colour variation you have 4.29 billion different possibilities.

Setting up a background in SDL2

The function SDL_RenderClear() is for clearing the screen with the drawing colour. As argument you just need to tell the renderer. It is simple as that :-). Since we set the drawing colour to cyan before, the screen will be cleared with a cyan colour.

SDL_RenderClear(renderer: PSDL_Renderer): SInt32

This function will return 0 on success and a negative error code on failure. The cleared screen will be shown for one second by SDL_RenderPresent() and SDL_Delay(). These two procedures are known from the previous chapter.

Drawing Lines and Points in SDL2

  //render and show a line
  SDL_SetRenderDrawColor(sdlRenderer, 255, 0, 0, 255);
  SDL_RenderDrawLine(sdlRenderer, 10, 10, 490, 490);
  SDL_RenderPresent(sdlRenderer);
  SDL_Delay(1000);  

Now we change the drawing colour by SDL_SetRenderDrawColor() to red and use SDL_RenderDrawLine() to draw a simple line.

SDL_RenderDrawLine(renderer: PSDL_Renderer; x1: SInt32; y1: SInt32; x2: SInt32; y2: SInt32): SInt32

Again you need the renderer, which is “sdlRenderer” in our case. After that you specify the x/y coordinates where the line should begin and then the x/y coordinates where the line should end. Remember that the origin 0/0 is at the top left corner of the window. The coordinates 10/10 mean to start at the point ten pixels to the right and ten pixel to the bottom relative to the origin. Thus, the coordinates 490/490 for the second point will lead to a diagonal line across the window. This diagonal line will be 10 pixels short with respect to the window edge. This function returns 0 on success and a negative error code on failure.

After that again we ask to render this line to the screen by SDL_RenderPresent() and wait one second by SDL_Delay().

  //render and draw points diagonally with distance between each other
  SDL_SetRenderDrawColor(sdlRenderer, 0, 0, 0, 255);
  for i := 0 to 47 do
    SDL_RenderDrawPoint(sdlRenderer, 490-i*10, 10+i*10);
  SDL_RenderPresent(sdlRenderer);
  SDL_Delay(1000); 

Now we change the colour to black and draw some points by the function SDL_RenderDrawPoint(). It is nearly identical to SDL_RenderDrawLine() but instead of four coordinates you need just two coordinates where the point should be drawn.

SDL_RenderDrawPoint(renderer: PSDL_Renderer; x: SInt32; y: SInt32): SInt32

This function returns 0 on success and the negative error code on failure.

I thought it would be nice to have more than just one point to be drawn, so the function is used in a for-loop to draw altogether 48 points. Here we need the counter variable “i”. Maybe you can guess from the code where the points are and how they are arranged, if not, just run the code ;-). Finally the result is rendered to the screen by SDL_RenderPresent() and the program waits one second by SDL_Delay().

Let’s proceed to the next chunk of code now.

  //prepare, render and draw a rectangle
  sdlRect1.x := 260;
  sdlRect1.y := 10;
  sdlRect1.w := 230;
  sdlRect1.h := 230;
  SDL_SetRenderDrawColor(sdlRenderer, 0, 255, 0, 255);
  SDL_RenderDrawRect(sdlRenderer, @sdlRect1);

The drawing colour is set to green by SDL_SetRenderDrawColor() and the rectangle is drawn by SDL_RenderDrawRect().

SDL_RenderDrawRect(renderer: PSDL_Renderer; rect: PSDL_Rect): SInt32

It requires the renderer, which is “sdlRenderer” for us and a PSDL_Rect , thus we use the @ operator for the declared rectangle of TSDL_Rect type to get its pointer value. This function returns 0 on success and the negative error code on failure. Notice, we neither render the result to the screen now nor do we delay here. Anyway, we want a second rectangle! 🙂

  //relocate, render and draw the rectangle
  sdlRect1.x := 10;
  sdlRect1.y := 260;
  SDL_SetRenderDrawBlendMode(sdlRenderer, SDL_BLENDMODE_BLEND);
  SDL_SetRenderDrawColor(sdlRenderer, 0, 0, 255, 128);
  SDL_RenderFillRect(sdlRenderer, @sdlRect1);
  SDL_RenderPresent(sdlRenderer);
  SDL_Delay(1000); 

We change the rectangles x/y coordinates for the second rectangle but keep its width and height. What we are looking for is a filled rectangle that has some transparency. Until now we always used 255 (opaque) as alpha value. We set the colour to draw the second rectangle to blue by SDL_SetRenderDrawColor(). Notice that the fourth value is 128 (half-transparent) instead of 255 (opaque). So everything behind the blue rectangle, e.g. the cyan background, should therefore shine through. To generate a filled rectangle SDL_RenderFillRect() is used:

SDL_RenderFillRect(renderer: PSDL_Renderer; rect: PSDL_Rect): SInt32

The renderer and the rectangle of type PSDL_Rect are the parameters of this function. So we use “sdlRenderer” and “sdlRect1” (with the @ operator) again to draw the rectangle. This function returns 0 on success and the negative error code on failure.

The Blend Mode in SDL 2.0

But to be honest, even if you change the alpha value it will be opaque. This is because the blend mode is set to SDL_BLENDMODE_NONE by default. We need to change this to be able to use the alpha value as desired. SDL_SetRenderDrawBlendMode() is what we are looking for:

SDL_SetRenderDrawBlendMode(renderer: PSDL_Renderer; blendMode: TSDL_BlendMode): SInt32

First the renderer for which the blend mode has to be set is chosen. In our case it is “sdlRenderer” again. Then there are four blend modes available. Their description is taken from the official SDL2 Wiki.

  1. SDL_BLENDMODE_NONE
    • no blending
    • dstRGBA = srcRGBA
  2. SDL_BLENDMODE_BLEND
    • alpha blending
    • dstRGB = (srcRGB * srcA) + (dstRGB * (1-srcA))
    • dstA = srcA + (dstA * (1-srcA))
  3. SDL_BLENDMODE_ADD
    • additive blending
    • dstRGB = (srcRGB * srcA) + dstRGB
    • dstA = dstA
  4. SDL_BLENDMODE_MOD
    • color modulate
    • dstRGB = srcRGB * dstRGB
    • dstA = dstA

We are looking for alpha blending, so we use SDL_BLENDMODE_BLEND as argument for the blend mode. This function returns 0 on success and the negative error code on failure.

After doing so the result is rendered to the screen by SDL_RenderPresent() and shown for one second by SDL_Delay(). Both rectangles, the green one and the half-transparent blue one appear at the same time.

Spread Points Randomly using PSDL_Point

  //prepare, render and draw 500 points with random x and y values
  Randomize;
  for i := 0 to 499 do
  begin
    sdlPoints[i].x := Random(500);
    sdlPoints[i].y := Random(500);
  end; 

Randomize is a Free Pascal procedure (from system unit) to initilize the random number generator. Imagine this as shaking the dice.

Let’s have a look at TSDL_Point. It is just a record of this structure:

PSDL_Point = ^TSDL_Point;
TSDL_Point = record
  x: SInt32;
  y: SInt32;
end;

As expected, the TSDL_Point record has two values, the x/y coordinates of the point. Notice how PSDL_Point is just a pointer to it. Free Pascal’s Random() function generates random numbers between 0 and the number which is used as argument substracted by one. So we generate 500 times a random x and y value between 0 and 499 and save them into the 500 SDL_Point records.

  SDL_SetRenderDrawColor(sdlRenderer, 128, 128, 128, 255);
  SDL_RenderDrawPoints(sdlRenderer, sdlPoints, 500);
  SDL_RenderPresent(sdlRenderer);
  SDL_Delay(3000);

A grey colour is set by SDL_SetRenderDrawColor() for the points. To draw the points in the array “sdlPoints” we use SDL_RenderDrawPoints().

SDL_RenderDrawPoints(renderer: PSDL_Renderer; points: PSDL_Point; count: SInt32): SInt32

This function returns 0 on success and the negative error code on failure. First you need to set the renderer, then just a pointer to an array of TSDL_Point (returned by simply passing the array’s name) and finally the number of points. The latter should be consistent with the array. So, if your array has 500 elements, the count should be 500 at maximum. Notice how we are not using a loop here to draw all 500 points by calling a certain function 500 times. Instead we just pass an array of points once. This way we save a lot of time at runtime, especially if you think of a real application where even more points have to be drawn. There are similar functions for lines, rectangles and filled rectangles. They are not used in the example but it may be interesting to know, so here they are:

SDL_RenderDrawLines(renderer: PSDL_Renderer; points: PSDL_Point; count: SInt32): SInt32

SDL_RenderDrawRects(renderer: PSDL_Renderer; rects: PSDL_Rect; count: SInt32): SInt32

SDL_RenderFillRects(renderer: PSDL_Renderer; rects: PSDL_Rect; count: SInt32): SInt32

As a hint, try replacing SDL_RenderDrawPoints by SDL_RenderDrawLines, and changing the count to 499. You will be rewarded with a beautiful pattern. 🙂

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

  //shut down SDL2
  SDL_Quit;
end.   

Finally all the memory reserved for points, the rectangle, the renderer and the window is free’d and SDL2 shut down by SDL_Quit.

Congratulations, you just finished this chapter :-).

You may read

  • Trouble: Using Array of PSDL_Point
  • Case: Drawing for Dynamic Colouring
  • Understanding Colours in Computer Graphics

below, or you may directly skip to the next chapter .

← previous Chapter | next Chapter →

Trouble: Using Array of PSDL_Point

To put your array in the heap, you would want to use an array of PSDL_Point instead of an array of TSDL_Point. For some reason it doesn’t seem to work well with the SDL_RenderDrawPoints() function. This means, instead of, let’s say 500 points just a quarter of all points (125 in the example) is shown unless you specifiy the count as being four times greater (2000 in the example). The reason behind this, is not clear to me.

Case: Drawing for Dynamic Colouring

SDL2 drawing and images diagram

As an example when drawing can be very helpful, think of the following situation. You create a game, let’s say a racing game. There are different players. Of course, each player’s car has to have a different colour. There are generally two ways to achieve this:

1) You create several images with differently coloured cars and store them on your harddrive.

This is perfectly okay if you have a small number of cars (and colours) to be chosen. But what if you want the player to choose from a large variety of colours, 100 colours or more, or what if you want to let the player to choose the colour of his car by himself? Notice, in case of 16 bit colouring that means 65536 possibilities after all! Would you want to create that many images? In case of 32 bit colouring you have fantastic 4.29 billion colours!! Amazing, but you will never be able to create so many images in just one human being’s life. Furthermore, this would take up a lot of hard drive memory (4.29 billion times the file size of the car image) for just a simple car racing game. Look at the following image. It contains the discussed method from left to the middle. On the right to the middle is the solution :-).

Instead of having each car coloured as an image file, why not using just one image file of a car without colouring? It is kind of a template. Now you can easily ask the player what colour he prefers (and he may pick from 4.29 billion colours if necessary), and then you simply colour the car on the fly. This is the second way:

2) You create one template image on your harddrive and colour it during runtime of the program.

This is just one example where drawing is very helpful.

Understanding Colours in Computer Graphics

The colour is composed of four components, RGBA, that is red, green, blue and the alpha value. The physical screen consists of many small units. Every unit itself consists of three different coloured lights. These colours are red, green and blue. If you mix them up, you can get every other colour. These colours are mixed up additively. For example if you mix red and green you get yellow. For three colours that can be mixed with each other, there are eight combinations possible which lead to different colours (RGB, RG, RB, R, GB, G, B, all lights off). If you mix red, green and blue (all lights on, RGB), you get white, and if all lights are off, you get black. Some may say, white and black are no colours at all. Well, that is right but doesn’t matter here and to keep simpliness I will talk of colours even if I talk of black and white.

Your screen definitvly has more than eight colours, doesn’t it? The reason is, your screen isn’t just able to switch lights on or off. Besides it is able to differ the intensities of the lights. The more intensity levels you have the more colours you can display. The case that you have eight colours as discussed before means that you just have one intensity level, on or off. If your screen is in 8 bit mode every pixel on the screen has the possibility to display 2 power 8 colours. That are 256 different colours. Every of the three lights has therefore a certain amount of different light intensity levels. If you have 16 bit mode you have 2 power 16 and that are 65536 colours. Each light therefore has the appropriate amount of intensity levels. Since we prefer 32 bit mode, we have 4.29 billion different colours!

Event handling Pt. 2, Mouse handling

Last updated on November 20th, 2021

This is part 2 of the chapter about event handling. Mouse and window handling is treated here.

Let’s start with the full example code:

program Chapter8_SDL2;

uses SDL2;

var
sdlWindow1: PSDL_Window;
sdlEvent: PSDL_Event;
exitloop: boolean = false;
text1: string = '';

begin

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

  sdlWindow1 := SDL_CreateWindow( 'Window1', 50, 50, 500, 500, SDL_WINDOW_SHOWN );
  if sdlWindow1 = nil then HALT;

  new( sdlEvent );

  while exitloop = false do
  begin
    while SDL_PollEvent( sdlEvent ) = 1 do
    begin
      write( 'Event detected: ' );
      case sdlEvent^.type_ of

        //keyboard events
        SDL_KEYDOWN: begin
                       writeln( 'Key pressed:');
                       writeln( '  Key code: ', sdlEvent^.key.keysym.sym );
                       writeln( '  Key name: "', SDL_GetKeyName( sdlEvent^.key.keysym.sym ), '"' );
                       writeln( '  Scancode: ', sdlEvent^.key.keysym.scancode );
                       writeln( '  Scancode name: "', SDL_GetScancodeName( sdlEvent^.key.keysym.scancode ), '"' );
                       writeln( '  Key modifiers: ', sdlEvent^.key.keysym._mod );
                       case sdlEvent^.key.keysym.sym of
                         27: exitloop := true;  // exit on pressing ESC key

                         //switching text input mode on/off
                         SDLK_F1: begin
                                    if SDL_IsTextInputActive = SDL_True then SDL_StopTextInput
                                    else SDL_StartTextInput;
                                    writeln(' Text Input Mode switched' );
                                  end;
                       end;
                     end;
        SDL_KEYUP: writeln( 'Key released ' );
        SDL_TEXTINPUT: begin
                         writeln( 'Text input: "', sdlEvent^.text.text, '"' );
                         text1 := text1 + sdlEvent^.text.text;
                         writeln( 'Full string: ' + text1 );
                       end;

        //mouse events
        SDL_MOUSEMOTION: begin
                           writeln( 'X: ', sdlEvent^.motion.x, '   Y: ', sdlEvent^.motion.y,
                                    '   dX: ', sdlEvent^.motion.xrel, '   dY: ', sdlEvent^.motion.yrel );
                         end;
        SDL_MOUSEBUTTONDOWN: writeln( 'Mouse button pressed: Button index: ', sdlEvent^.button.button );
        SDL_MOUSEBUTTONUP: writeln( 'Mouse button released' );
        SDL_MOUSEWHEEL: begin
                          write( 'Mouse wheel scrolled: ' );
                          if sdlEvent^.wheel.y > 0 then writeln( 'Scroll forward, Y: ', sdlEvent^.wheel.y )
                          else writeln( 'Scroll backward, Y: ', sdlEvent^.wheel.y );
                        end;

        //window events
        SDL_WINDOWEVENT: begin
                           write( 'Window event: ' );
                           case sdlEvent^.window.event of
                             SDL_WINDOWEVENT_SHOWN: writeln( 'Window shown' );
                             SDL_WINDOWEVENT_MOVED: writeln( 'Window moved' );
                             SDL_WINDOWEVENT_MINIMIZED: writeln( 'Window minimized' );
                             SDL_WINDOWEVENT_MAXIMIZED: writeln( 'Window maximized' );
                             SDL_WINDOWEVENT_ENTER: writeln( 'Window got mouse focus' );
                             SDL_WINDOWEVENT_LEAVE: writeln( 'Window lost mouse focus' );
                           end;
                         end;
      end;
    end;
    SDL_Delay( 20 );
  end;

  dispose( sdlEvent );
  SDL_DestroyWindow ( sdlWindow1 );

  //shutting down video subsystem
  SDL_Quit;

end.

Mouse handling in SDL 2.0

If you got the basic concept of event handling, you will find that mouse handling and keyboard handling have a lot in common.

        //mouse events
        SDL_MOUSEMOTION: begin
                           writeln( 'X: ', sdlEvent^.motion.x, '   Y: ', sdlEvent^.motion.y,
                                    '   dX: ', sdlEvent^.motion.xrel, '   dY: ', sdlEvent^.motion.yrel );
                         end;

For mouse motions, mouse buttons and the mouse wheel there are three different mouse event structures: SDL_MouseMotionEvent, SDL_MouseButtonEvent and SDL_MouseWheelEvent.

Mouse motion handling in SDL 2.0

If you are moving the mouse, the SDL_MOUSEMOTION event is triggered. The record structure of the SDL_MouseMotionEvent is shown below:

TSDL_MouseMotionEvent = record
    type_: UInt32;       // SDL_MOUSEMOTION
    timestamp: UInt32;
    windowID: UInt32;    // The window with mouse focus, if any
    which: UInt32;       // The mouse instance id, or SDL_TOUCH_MOUSEID
    state: UInt8;        // The current button state 
    padding1: UInt8;
    padding2: UInt8;
    padding3: UInt8;
    x: SInt32;           // X coordinate, relative to window
    y: SInt32;           // Y coordinate, relative to window
    xrel: SInt32;        // The relative motion in the X direction 
    yrel: SInt32;        // The relative motion in the Y direction
  end;

Again there are the type_, the timestamp and the windowID fields. Nothing new here. The field which contains the mouse id. This is important if you have more than one mouse device attached to your computer. Think for example of a laptop with a touchpad area to move the mouse cursor and at the same time there is an usb mouse attached to the laptop. To distinguish between the two, you may retrieve their id’s.

The state field is known from the SDL_KeyBoardEvent structure. It may be a difference if you have a mouse button pressed and move the mouse or if you don’t have a button pressed. The most famous example is if you want to select a bunch of files on your desktop or in a folder. By the way, the state field encodes a number which is different depending on which buttons you pressed actually. This works similar to the key modifiers, if you keep two mousebuttons pressed while moving, the state is the sum of each individual mouse button state value. As an example for my mouse: No mouse button 0, left mouse button 1, right mouse button 4, middle mouse button 2, thumb button 8. If I keep pressed left and right mouse button 5 (sum 1 + 4).

The x and y fields contain the coordinate of the mouse cursor in pixels. These coordinates are relative to the window of the SDL 2.0 application. Keep in mind, the coordinates (0/0) correspond to the left upper corner. Positive x values are counted from left to right and positive y values are counted from top to bottom.

The fields xrel and yrel are used to determine how fast the mouse has been moved from one point to another. Let’s assume you move the mouse surcor from left to right in your application’s window. The first time you do it slowly, xrel might be 1, means, you just moved pixel from left to right between two mouse motion events. If you move fast, xrel might be 50, meaning that this time you moved by 50 pixels between two mouse motion events. Especially for game programming this can be a extremely important information. E.g., think of first person shooter, if the movement speed of the first person view would be independent of the actual movement of the mouse, this game wouldn’t make much sense.

To access these fields the event’s motion field has to be read out. In the example code the (x/y) coordinates and the relative positions xrel and yrel are read out by

sdlEvent^.motion.x

sdlEvent^.motion.y

sdlEvent^.motion.xrel

sdlEvent^.motion.yrel

and simply printed out to the screen. Let’s go for the next chunk of code.

        SDL_MOUSEBUTTONDOWN: writeln( 'Mouse button pressed: Button index: ', sdlEvent^.button.button );
        SDL_MOUSEBUTTONUP: writeln( 'Mouse button released' );
        SDL_MOUSEWHEEL: begin
                          write( 'Mouse wheel scrolled: ' );
                          if sdlEvent^.wheel.y > 0 then writeln( 'Scroll forward, Y: ', sdlEvent^.wheel.y )
                          else writeln( 'Scroll backward, Y: ', sdlEvent^.wheel.y );
                        end;

Pressing a mouse button in SDL 2.0

As for the SDL_KeyBoardEvent, you would want to know if a mouse button and which one is pressed or released. If a mouse button is pressed, a SDL_MOUSEBUTTONDOWN event is triggered. On releasing a mouse button a SDL_MOUSEBUTTONUP event is triggered. It has SDL_MouseButtonEvent structure. Let’s have a look into the structure:

TSDL_MouseButtonEvent = record
    type_: UInt32;       // SDL_MOUSEBUTTONDOWN or SDL_MOUSEBUTTONUP 
    timestamp: UInt32;
    windowID: UInt32;    // The window with mouse focus, if any
    which: UInt32;       // The mouse instance id, or SDL_TOUCH_MOUSEID 
    button: UInt8;       // The mouse button index
    state: UInt8;        // SDL_PRESSED or SDL_RELEASED
    padding1: UInt8;
    padding2: UInt8;
    x: SInt32;           // X coordinate, relative to window
    y: SInt32;           // Y coordinate, relative to window 
  end;

If you compare this structure to the structure of the SDL_MouseMotionEvent, you will find, only the two field xrel and yrel are gone and a new field, a crucial one to be clear, is new, which is button of 8 bit unsigned integer type.

I won’t discuss all the fields again we discussed for the SDL_MouseMotionEvent structure. Attention, if you compare the state field of the SDL_MouseButtonEvent, it works another way. It allows just for two values, SDL_PRESSED or SDL_RELEASED, as known from SDL_KeyBoardEvent. As a reminder: For the SDL_MouseMotionEvent, it represented that full state of all the buttons being pressed while mouse motion.

The button field allows to recognize which button has triggered the SDL_MouseButtonEvent. Each button of the mouse has its own index. As an example for my mouse they are as follows: Left mouse button 1, right mouse button 3, middle mouse button 2, thumb mouse button 4. Do not confuse these index numbers with the mouse button state values of the SDL_MouseMotionEvent structure. There can only be one button which triggered this event! Combinations as for the motion event are not possible. In the example code this value is just printed to the screen using

sdlEvent^.button.button.

You see, to access the fields of this record you need to address the event’s button field. This mustn’t be confused with SDL_MouseButtonEvent’s button field discussed above.

The x and y fields contain the (x/y) coordinates when the mouse button (whose index is stored in field button) has been pressed (or released). This is crucial to know. What would an application be worth if you could recognized that a certain button has been pressed but you don’t know where exactly? Not shown in the code but you could access these fields by

sdlEvent^.button.x

sdlEvent^.button.y.

The mouse wheel in SDL 2.0

If the mouse wheel is used a SDL_MOUSEWHEEL event is triggered. Let’s look into the corresponding SDL_MouseWheelEvent structure.

TSDL_MouseWheelEvent = record
    type_: UInt32;        // SDL_MOUSEWHEEL
    timestamp: UInt32;
    windowID: UInt32;    // The window with mouse focus, if any
    which: UInt32;       // The mouse instance id, or SDL_TOUCH_MOUSEID
    x: SInt32;           // The amount scrolled horizontally 
    y: SInt32;           // The amount scrolled vertically
  end;

New fields here are the x and y field which do not correspond to the mouse cursor position this time. Instead of that they refer to the direction of the mouse wheel being scrolled. If you scroll the mouse wheel upwards or forward it will return 1, and if you scroll it backwards it will return -1. If you have a mouse wheel which can be scrolled horizontally, it will be similar. By the way scrolling a mouse wheel can be considered as pressing a button very quickly for that direction.

In the code, if a SDL_MOUSEWHEEL event is triggered, the y value is checked to be positive or negative. This decides if an upward or downward scrolling has happened and the corresponding value (1 or -1) will be returned and printed out. Anyway, could you guess what happens if anyone would use a mouse wheel that is scrolling horizontally? – The same block will be executed since a SDL_MOUSEWHEEL event is triggered. Instead of y being 1 or -1, it will be 0 but the x value will be 1 or -1. Nevertheless, the else-block will be executed since y is not greater than 0. So for the example program it will print out wrongly that an backward scroll has happened. Anyway, you get the idea.

Window handling in SDL 2.0

Modern applications are always run in windows. The famous operation system “Windows” by Microsoft even derived it’s name from this. The first task for most of SDL 2.0 applications is the creation of a window. The example code creates a window of width 500 pixels and height 500 pixels. It may be important to know if the user interacts with the application window. Whenever this happens a SDL_WINDOWEVENT is triggered.

        //window events
        SDL_WINDOWEVENT: begin
                           write( 'Window event: ' );
                           case sdlEvent^.window.event of
                             SDL_WINDOWEVENT_SHOWN: writeln( 'Window shown' );
                             SDL_WINDOWEVENT_MOVED: writeln( 'Window moved' );
                             SDL_WINDOWEVENT_MINIMIZED: writeln( 'Window minimized' );
                             SDL_WINDOWEVENT_MAXIMIZED: writeln( 'Window maximized' );
                             SDL_WINDOWEVENT_ENTER: writeln( 'Window got mouse focus' );
                             SDL_WINDOWEVENT_LEAVE: writeln( 'Window lost mouse focus' );
                           end;

If the an event of type SDL_WINDOWEVENT is triggered, the text message “Window event: ” is printed out.

To access the window event fields, you need to access the event’s window field. The field event contains the window event’s type information, hence what window event has been triggered.

sdlEvent^.window.event

In contrast to the keyboard and the mouse event we discussed before, the different event types are not distinguished by the type_ field but by an additional field event.

In the example code six different window event types are checked: SDL_WINDOWEVENT_SHOWN, SDL_WINDOWEVENT_MOVED, SDL_WINDOWEVENT_MINIMIZED, SDL_WINDOWEVENT_MAXIMIZED, SDL_WINDOWEVENT_ENTER and SDL_WINDOWEVENT_LEAVE. From the texts printed out you can guess when they get triggered. I think no further explanation is needed here.

By the way, there are more window event types which are shown a little bit later. Sometimes if one of these is triggered, only the text that a window event has been triggered is shown but without any further details since the example code doesn’t covers further treatment. Feel free to extent the code yourself.

Let’s have a look at the event structure of SDL_WindowEvent.

TSDL_WindowEvent = record
    type_: UInt32;       // SDL_WINDOWEVENT
    timestamp: UInt32;
    windowID: UInt32;    // The associated window
    event: UInt8;        // SDL_WindowEventID
    padding1: UInt8;
    padding2: UInt8;
    padding3: UInt8;
    data1: SInt32;       // event dependent data
    data2: SInt32;       // event dependent data 
  end;

The fields type_, timestamp and windowID are known and have the same meaning as discussed before.

The field event stores an identifier (SDL_WindowEventID) to distinguish between different window events. Here they are listed and in brackets you find the window related action which has triggered them:

  1. SDL_WINDOWEVENT_SHOWN (window has been shown)
  2. SDL_WINDOWEVENT_HIDDEN (window has been hidden)
  3. SDL_WINDOWEVENT_EXPOSED (window has been exposed and should be redrawn)
  4. SDL_WINDOWEVENT_MOVED (window has been moved to data1, data2)
  5. SDL_WINDOWEVENT_RESIZED (window has been resized to data1xdata2; this is event is always preceded by SDL_WINDOWEVENT_SIZE_CHANGED)
  6. SDL_WINDOWEVENT_SIZE_CHANGED (window size has changed, either as a result of an API call or through the system or user changing the window size; this event is followed by SDL_WINDOWEVENT_RESIZED if the size was changed by an external event, i.e. the user or the window manager)
  7. SDL_WINDOWEVENT_MINIMIZED (window has been minimized)
  8. SDL_WINDOWEVENT_MAXIMIZED (window has been maximized)
  9. SDL_WINDOWEVENT_RESTORED (window has been restored to normal size and position)
  10. SDL_WINDOWEVENT_ENTER (window has gained mouse focus)
  11. SDL_WINDOWEVENT_LEAVE (window has lost mouse focus)
  12. SDL_WINDOWEVENT_FOCUS_GAINED (window has gained keyboard focus)
  13. SDL_WINDOWEVENT_FOCUS_LOST (window has lost keyboard focus)
  14. SDL_WINDOWEVENT_CLOSE (the window manager requests that the window be closed)

This list is based upon information found at the SDL 2.0 wiki.

If you read through the list carefully you will notice the mention of data1 and data2 which rather explains their occurance in the event structure :-)! They need to be read out for SDL_WINDOWEVENT_MOVED and SDL_WINDOWEVENT_RESIZED to get the new window position or dimensions.

At the moment I’m not sure why for window events the distinction between the individual window events (e.g. SDL_WINDOWEVENT_MOVED, SDL_WINDOWEVENT_RESIZED, and so on) is not done by the type_ field as for keyboard, mouse and other events, but rather by the additional event field.

                         end;
      end;
    end;
    SDL_Delay( 20 );
  end;

  dispose( sdlEvent );
  SDL_DestroyWindow ( sdlWindow1 );

  //shutting down video subsystem
  SDL_Quit;

end.

Not much to learn in the final part. The loop is delayed by 20 milliseconds for better recognizability of the text output.

If the loop is left, the event pointer gets free’d, the SDL 2.0 window gets destroyed and SDL 2.0 quit. That’s it :-)!

Touchscreen events, Joystick events and many more!

This chapter covered keyboard, mouse and window events in some detail. Keep in mind, SDL 2.0 has much more to show! – There are many more events you can use for application development. They basically cover any modern type of interaction you could wish for. This includes touchscreen events (important for smartphone development), joystick events (game console development), and even a dropfile event (drag and drop files) and more.

← previous Chapter | next Chapter →