Chapter 3 – First Steps

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.

How to get the source code of examples?

You can easily copy the example source code directly from the source code box for each chapter. It doesn’t even matter what code snippet is actually shown in the source code box, all boxes contain the full source code of the program, respectively.

Diagram how to get source code

  1. Hover into the source code box with your mouse cursor, a grey mini menu will show up at the top.
  2. Click on the button “Toggle Plain Code” (or just double click into the source code box anywhere). The source code box turns black and white.
  3. Copy the full source code (or parts of it) into your compiler’s IDE or a simple text file.

To reverse the effect, just again hover into the box and click “Toggle Plain Code” again. The source code is displayed as originally. Feel free to try it out further below, there is a source code box :-).

The SDL2 unit and the first application

Let’s start now. The most important rule to get ready for SDL 2.0 in your Pascal programs is:

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 the

SDL_Init(flags:UInt32):SInt32 function.

It will return 0 on success and a negative error code on failure. You may wonder about the variable types SInt32 and UInt32. Such integer types (which we will see in other chapters again) originate from the original C-language SDL 2.0 code. For an easier translation to Free Pascal they were kept. The S and U mean “signed” (negative values possible) and “unsigned” (values greater or equal zero only), the Int stands for “integer” and the number stands for the bit value. So UInt32 is an 32 bit unsigned integer (which corresponds to Free Pascal’s longword).

In the first example we want to initialize the SDL 2.0 video subsystem for screen handling. The following code example shows the frame of a typical SDL 2.0 application.

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. The table shows an overview of all the possible flags and their meaning:

Flag Description
SDL_INIT_TIMER Initilizes timer subsystem for handling of time related events.
SDL_INIT_AUDIO Initilizes audio subsystem for playing music or sound effects.
SDL_INIT_VIDEO Initilizes video subsystem for drawing/showing/manipulating of graphics, textures and screen, usually the most important subsystem.
SDL_INIT_JOYSTICK Initilizes joystick subsystem for handling of joysticks.
SDL_INIT_HAPTIC Initilizes haptic (force feedback) subsystem.
SDL_INIT_GAMECONTROLLER Initilizes game controller subsystem.
SDL_INIT_EVENTS Initilizes events subsystem for handling of mouse or keyboard input.
SDL_INIT_EVERYTHING Initilizes all the subsystems above.
SDL_INIT_NOPARACHUTE Ignores 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.

Of course you are allowed to combine several components 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

SDL_InitSubSystem(flags:UInt32):Integer

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

SDL 2.0 functions and errors

By the way, actually every SDL 2.0 function returns an error value for you to check if the function runs properly at runtime. The values returned can be of different type (e.g. Integer values, NIL pointer). There is no general rule what values correspond to which status. In SDL 2.0 usually a value of 0 means “function runs/ran succesfully”, values lower than 0 correspond to a status “function couldn’t be run, something is wrong”. However, in most cases I won’t do error checking to keep code examples 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 error code into a message (of type PAnsiChar) that can be read out and printed to the screen by the common Free Pascal 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).

Quitting your programs

Every SDL program has to be closed by

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

SDL_QuitSubSystem(flags:UInt32).

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.

Now you can try the example program. You will not see much but if you didn’t get an error message you was successful.

Well, we have initilized the video subsystem and released it afterwards. Simple Directmedia Layer deserves its name, isn’t it?

If you agree only, you may proceed to Chapter 4 ;-)!

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

6 thoughts on “Chapter 3 – First Steps

  1. Hello. It can’t work on Ubuntu 16.04 🙁
    All libraries installed. It’s compiled, but crashed with error:
    Runtime error 200 at $00007F859C697634
    $00007F859C697634

    I tried another version of Tim Blume’s SDL2 units (1.62-master) and this error repeated.

    1. I’m confused, did you use the example code as is shown in the chapter (above)?

      Runtime error 200 means “division by zero”.

        1. I cannot confirm this behavior. I tried it again on Linux Mint (x64, Ubuntu based).

          Do you use Lazarus as IDE? If so, try to start a completely new project (Simple Program).
          1) Then run the code (basically an empty Pascal program). Does it work?
          2) Add SDL2 to the uses clause and add the appropriate path to the project’s unit path. Run it. Does it work?
          3) Add the sample code again. Run it. Does it work?

Leave a Reply