Tag Archives: sdl 1.2

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.

Chapter 8a: Converting SDL image to OpenGL texture (JEDI-SDL)

This is an SDL 1.2 chapter. SDL 1.2 is obsolete since it has been replaced by SDL 2.0. Unless you have good reasons to stay here you may prefer to go for the modern SDL 2.0 :-).

It is highly recommended that you read the previous Chapter 8. The code from last chapter was used and modified to show how the conversion works. However, I won’t explain twice everything already introduced in Chapter 8. Also I’d like to express here that NeHe Productions’ OpenGL tutorial 06 “Texture Mapping” and the translated (by Dominique Louis) Jedi-SDL file was inspiring me a lot for this chapter.

You need this software:

Software Version Source Description
OpenGL driver Usually your graphic card provides the corresponding OpenGL driver and you don’t have to do anything. And if so it is very likely that version 1.1 is fully supported. However if you are one of the few poor people whose graphic card doesn’t support OpenGL, check the graphic card’s manufacturer’s homepage for OpenGL drivers.

Now following the whole code at once as usual. As you will notice many lines are exactly the same as in Chapter 8.

This code will again draw a tetrahedron which is spinning, as known from Chapter 8. However, this time one face is textured with the “Free Pascal meets SDL” image known from Chapter 3. Now lets go through the code step by step.

The program is called “chap8a”. Additionally to the variables defined in the previous chapter there are two new variables. The SDL surface “picture” which will store the SDL image before converting it to an OpenGL texture. ogl_texture is an integer pointer variable (provided by the OpenGL Uitility Library (GLU), so pGLUINT) which is needed to reference to the OpenGL texture we will create from the SDL image.

The code shown here is discussed in detail in Chapter 8. In short the tetrahedron parameters are calculated, some important OpenGL scene settings are applied and finally the SDL video subsystem is intilized.

First we should load a simple BMP image to a SDL surface as known from Chapter 3. There are some limitations about the height and length of images if used as OpenGL textures. Their pixel height and pixel length has to be power of 2. So whatever image you use, its height and lengths should fulfill the following equation: f(n) = 2n. So appropriate values are: 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024, 2048,… The height and length don’t have to be of the same size, so an image with height 64 px and width 32 px is perfectly acceptable. This means the image of Chapter 3 with height and length of 200 x 200 px is not acceptable. A new image with 256 x 256 dimensions is therefore provided now:

Free Pascal meets SDL images with 256x256 dimensions
Free Pascal meets SDL images with 256×256 dimensions

First the pointer “ogl_texture” gets some space. glGENTEXTURES(number of IDs, array of integer pointer) generates one or more OGL integer identifiers for textures. Anyway, we just have one texture, so we just need one texture identifier, therefore we request “1” and ogl_texture should point at it. If we need to identify the texture we just need to call ogl_texture from now on.

glBINDTEXTURE(target, texture) essentially creates a texture object of type: GL_TEXTURE_1D or GL_TEXTURE_2D. Usually textures in 2d and 3d games are two-dimensional, so GL_TEXTURE_2D is a good choice. Now it is clear, ogl_texture will be a 2d texture.

Briefly, glTEXIMAGE2D(target, mipmap level, internal image format, width, height, border, pixel format, pixel type, actual pixel data) creates the actual 2d texture. The target is GL_TEXTURE_2D again since we are looking for creating a 2d texture. The mipmap level should be set to 0 because we wouldn’t want to have a mipmap effect here. A higher number corresponds to the number’s mipmap level, anyway in the example for a number different from 0 there is no image at all finally. The internal image format is RGB because the image is a RGB image, anyway there is a large list of possibilities for this parameter, you should look it up in the internet if you’re interested. The width and height of the image in pixels is received from the SDL image. The border is off (values 0 and 1 are acceptable). The pixel format is RGB, too, so again SDL_RGB is the right choice here. The pixel explains how the pixel data is stored. The pixel data from the SDL image is stored as unsigned byte (GL_UNSIGNED_BYTE). Finally the pixel data pointer of the SDL image is needed. Essentially the SDL image is now transformed to an OGL texture!

Briefly, glTEXPARAMETERi(target, texture parameter, parameter value) allocates a certain value to a specific texture parameter. The possible parameters and values are OGL specific and won’t be treated here in more detail. Anyway, again we are concerned about our 2d texture, so the target is GL_TEXTURE_2D. The parameters to be set are GL_TEXTURE_MIN_FILTER and GL_TEXTURE_MAG_FILTER. They are used to define how to treat textures that have to be drawn to a smaller or larger scale. The routine used for this is specified by GL_LINEAR.

Since the SDL image isn’t needed anymore it can be omitted as known by SDL_FREESURFACE.

This part is completely described in Chapter 8. Nothing has changed for this part. In short, the viewport is set up so that the tetrahedron finally can be seen.

Now the REPEAT..UNTIL loop is entered which is delayed by 50 milliseconds by known SDL_DELAY. Each cycle the the scene gets rotated by 5 degrees around the y-axis by function glROTATEf. More details about this in Chapter 8.

The actual texturing of one of the four triangles of the tetrahedron is now described. Therefore 2d texturing has to be enabled by glENABLE(OGL capability). The capability we would like to enable is defined by GL_TEXTURE_2D.

Just as known from Chapter 8 the triangle mode is started by glBEGIN(geometric primitive type) with GL_TRIANGLES. Instead of a color we now define specific texture coordinates which should be allocated to specific vertices. glTEXCOORD2f(s coordinate, t coordinate) is used to define the coordinate of the texture we then allocate to a specific vertex. By the way, even though the official names of the texture coordinates are s and t, they can be considered as x and y values, which is more common for two-dimensional coordinate systems. The values for s and t are relative, so a value of 1 (= 100%) means the full width or height, independent of the actual width or height (32 x 32, 64 x 64, 128 x 256, …), a value of 2 (= 200%) then corresponds to two times the texture’s width or height. The coordinate (s, t) = (2, 2) is allocated to the vertex with the vertex coordinates (x, y, z) = (thh, 0.0, 0.0). Texture coordinate (0, 0) is allocated to vertex (thh, hh, 0.0). Texture coordinate (0, 2) is allocated to vertex (thh, hh, 0.5). Often this texturing process is compared to papering a wall, and indeed there are similarities. The vertex coordinates are exactly the same as for the first triangle in Chapter 8.

Finally the geometry definition and the texturing mode is finished by glEND and glDISABLE(OGL capability).

The remaining three areas of the triangle are kept as in Chapter 8. Finally the display buffer if swapped after each cycle and the REPEAT..UNTIL loop stopped if a key is pressed in the console.

Last but not least everything has to be free’s and closed as known. Anyway, the texture has to free’d by glDELETETEXTURES(number of textures, texture pointer). Then the pointer can be disposed as known and SDL can be quit.

Again, if you want to learn OpenGL and its capabilities to a more advaced extend you need to read more professional tutorials related to pure OpenGL programming. As a starting point I’d like to mention NeHe Productions’ OpenGL tutorials again, because they are professional and provide example code for JEDI-SDL for several lessons. 🙂

This file contains the source code: chap8a.pas (right click and “save as”)
This file is the executable: chap8a.exe (right click and “save as”)

The final result should look and behave like this: A tetrahedron consisting of three different coloured areas (cyan, magenta and white) and one textured area is spinning slowly around itself. When pressing a key in the console the show quits.

Result of JEDI-SDL Chapter 8a

Chapter 8: SDL and OpenGL – Entering the third dimension (JEDI-SDL)

This is an SDL 1.2 chapter. SDL 1.2 is obsolete since it has been replaced by SDL 2.0. Unless you have good reasons to stay here you may prefer to go for the modern SDL 2.0 :-).

This chapter will introduce you on how to combine the SDL library with the famous Open Graphics Library (OpenGL). OpenGL is the first choice when it comes to platform independent 2d and 3d graphic programming. As long as you just want to do 2d programming you can stay with SDL and there is no need to use OpenGL (even though OpenGL is also capable of doing 2d graphics). However, if your project needs 3d graphics you can set up your system for this quite easy using OpenGL in SDL. The main advantages of SDL here are that any other task except the graphics is further done by SDL (e.g. keyboard handling, sound,…) to keep the platform independence and ease. Further the setup of your SDL environment for the usage of OpenGL is very easy (compared to the setup without SDL) AND also is platform independent. Without SDL you would’ve to write different code to set up OpenGL for each operating system.

You need this software:

Software Version Source Description
OpenGL driver Usually your graphic card provides the corresponding OpenGL driver and you don’t have to do anything. And if so it is very likely that version 1.1 is fully supported. However if you are one of the few poor people whose graphic card doesn’t support OpenGL, check the graphic card’s manufacturer’s homepage for OpenGL drivers.

There is support for some others OpenGL related units, like GLUT (OpenGL Utility Toolkit) which provides a simple windowing application programming interface, GLX (OpenGL Extension to the X Window system) which provides a binding to use OpenGL in X Window windows (Linux), GLEXT (OpenGl Extensions) which provide additional functions since version 1.1 of OpenGL from 1996. I didn’t try out any of the latter mentioned units but if you progress in learning and using OpenGL especially GLEXT might get interesting to you since it provides the up-to-date functionality.

Now following the whole code at once as usual.

What this code will do is to switch to the OpenGL mode of SDL and draw a spinning tetrahedron. When you press a key the program aborts. However, some identifiers mentioned in the code are not related to SDL but OpenGL. Furthermore there are some functions which are related to OpenGL but are provided by SDL. Pure OpenGL identifiers begin with GL_ (e.g. GL_TRIANGLES) or gl (e.g. glCLEARCOLOR) whereas SDL provided OpenGL functions begin with SDL_GL_ (e.g. SDL_GL_SETATTRIBUTE).

The program is called “chap8”. We use CRT as known from many former chapters to provide an easy way to recognize if a key got pressed. We need SDL for SDL support. New are the OpenGL units GL and GLU which are both included uncompiled in the JEDI unit package as well as pre-compiled along with the FPC compiler.

We need a variable “userkey” to recognize the user pressing a button. This is unrelated to SDL and OpenGL. The screen variable will display the scene later and is known from every former chapter. Four REAL variables are needed for some calculations regarding a tetrahedron.

The first four lines of code after BEGIN are needed to have some pre-calculated values at hand when it comes to constructing the tetrahedron later. h is the height of a equilateral triangle when each side has the length of one. hh corresponds to the half height meaning the value of h devided by two. th is the height of the tetrahedron (from any of the four possible bases to the corresponding peak) constructed of equilateral triangles. thh means the half value of th. These expressions result just from some geometry (Pythagorean theorem) and aren’t related directly to SDL or OpenGL.

First of all we initialize SDL as known. Attention now: Before setting up the video mode for OpenGL we have to set all needed attributes of the OpenGL environment. If you set them afterwards they won’t be recognized and default values are used by OpenGL. The function to do so is SDL_GL_SETATTRIBUTE(attribute, value). The function returns the integer 0 if setting was successful, -1 otherwise. The corresponding function to read out the set value of an attribute is SDL_GETATTRIBUTE(attribute, value) with the same error checking values. The attribute’s value is written to value. This last function is not used in the code.

The following table (Source: JEDI-SDL documentation) shows all possible attributes which can be set:

Attribute Description
SDL_GL_RED_SIZE Size of the framebuffer red component,
in bits
SDL_GL_GREEN_SIZE Size of the framebuffer green component,
in bits
SDL_GL_BLUE_SIZE Size of the framebuffer blue component,
in bits
SDL_GL_ALPHA_SIZE Size of the framebuffer alpha component,
in bits
SDL_GL_DOUBLEBUFFER 0 or 1, enable or disable double buffering
SDL_GL_BUFFER_SIZE Size of the framebuffer, in bits
SDL_GL_DEPTH_SIZE Size of the depth buffer, in bits
SDL_GL_STENCIL_SIZE Size of the stencil buffer, in bits
SDL_GL_ACCUM_RED_SIZE Size of the accumulation buffer red
component, in bits
SDL_GL_ACCUM_GREEN_SIZE Size of the accumulation buffer green
component, in bits
SDL_GL_ACCUM_BLUE_SIZE Size of the accumulation buffer blue
component, in bits
SDL_GL_ACCUM_ALPHA_SIZE Size of the accumulation buffer alpha
component, in bits
Source of table and content: JEDI-SDL documentation.

Each pixel of the screen contains three different colour components (red, green, blue). We want each pixel’s colour component’s size to be five bits. This is a default value for the colour components. The depth buffer (also called Z-buffer) will get 16 bits of size, also a default value. Finally we allow double buffering. Be careful here. The double buffering for an OpenGL scene is not enabled by the SDL flag SDL_DOUBLEBUF in the video set function but is set by SDL_GL_SETATTRIBUTE(SDL_GL_DOUBLEBUFFER, 1). For any other attributes, its meanings and its values refer to OpenGL tutorials which you find anywhere in the Internet.

The goal is to draw an OpenGL scene within a SDL environment to have access to all the advantages each library provides. So after setting all necessary attributes of the OpenGL scene you have to create a SDL window which is able to display an OpenGL scene. To set up such a window you use the common SDL_SETVIDEOMODE(parameters) function. The first two parameters determine the window’s size as known. The values for the width and the height should be consistent with the values for the OpenGL viewport which will be set later.

The third parameter determining the colour depth of a SDL scene should be ignored and set to 0 if you want to set up an OpenGL scene. The colour depth of an OpenGL scene is set up as shown before with SDL_GL_SETATTRIBUTES(parameters). However, any value different from 0 will not affect the OpenGL scene in any way.

To set up an OpenGL scene successfully you must add the SDL_OPENGL flag as shown. However, you can combine it with any other window appearance flag (e.g. fullscreen, without border, …) by using the logic operator OR as known.

The following descriptions regard to pure OpenGL programming. Detailed descriptions you’ll find in any OpenGL tutorial. However, I will give a brief overview over these functions.

glCLEARCOLOR(parameters) sets the background colour used if you call glCLEAR to reset the colour buffer. glCLEARCOLOR(parameters) expects four float point values corresponding the red, blue, green colour and the alpha channel (for transparency). Any value is a number between 0.0 and 1.0 where 0.0 means no addition of the corresponding colour component or transparency and 1.0 full addition of the corresponding colour component or complete transparency. In the example code we set up a completly blue background without transparency.

glVIEWPORT(parameters) sets the viewport of the OpenGL scene. The first two parameters are integer x- and y-values for the actual position in space, 0/0 is the default setting. The lower-left corner of the viewport is therefore at position 0/0 by default. The next two parameters define the width and height of the scene’s projection to the physical screen. Remeber please, these two values should be the same as has been used for the window width and height when using SDL_SETVIDEOMODE(parameters). However, it isn’t forbidden to use different values. We use a width of 640 and height of 480 pixels.

glMATRIXMODE(parameter) sets the matrix which you’d like to manipulate. It allows different parameters. Very common values are GL_PROJECTION and GL_MODELVIEW, further parameters are GL_TEXTURE and GL_COLOR. The following matrix operations (glTRANSLATEf, glROTATEf,…) are applied to the set matrix’ stack. Often this function is followed by glLOADIDENTITY. glLOADIDENTITY replaces the current matrix by the identity matrix. All elements of the identity matrix equal 0 except for the diagonal elements which are 1.

First we need to specify the projection transformation. Therefore we set the matrix mode by parameter GL_PROJECTION. Either we choose a perspective projection that reflects a 3d world, so objects with a great z value appear smaller than objects with a lower z value, or we choose an orthographic projection that reflects a 2d world, so objects will be drawn independently of their z value. The latter mode is usually used for text, menus, buttons, even complete side scrolling 2d games. Since we’d like to render a tetrahedron, we set up a persepctive projection matrix by gluPERSPECTIVE(parameters). The prefix “glu” indicates it’s a function from the OpenGL utilities unit. Instead we also could have used the glFRUSTUM(parameters) function which is part of the core OpenGL unit to generate such a matrix but gluPERSPECTIVE(parameters) makes it easy to get a matrix for distortionless display of the resulting projection. The first parameter is the field of view angle (fovy) in degrees. The second parameter is the aspect, usually the aspect ratio of the window dimensions width/height, here 640/480. The last two parameters are the (positive) z values for the near and far clipping plane of the generated viewing frustum. The generated perspective projection matrix corresponds to a viewing frustum.

Next we have to set up the viewing and modeling transformation. We switch to this matrix mode by GL_MODELVIEW as argument for GL_MATRIXMODE(parameter). We replace the matrix stack with the identity matrix. Now any subsequent matrix operations (glTRANSLATEf, glROTATEf,…) are applied to this matrix. It is replaced by the identity matrix and ready for further manipulations. This mode lets you manipulate the actual objects or models, e.g. a tetrahedron.

The color buffer gets cleared by glCLEAR(GL_COLOR_BUFFER_BIT). Then back-face culling is enabled by GL_ENABLE(GL_CULL_FACE). If you draw e.g. a triangle it has two faces. A front face and a back face. In a tetrahedron consisting of four triangles the inner faces are never seen. To avoid drawing them the back-face culling gets enabled so OpenGL isn’t drawing them. Finally the scene gets translated along the z-axis about -2.0 units by glTRANSLATEf(parameters) with x, y and z as parameters.

Don’t be worried. This piece of code looks big but this is just because of the definition of the actual tetrahedron. First the REPEAT loop is entered. Every cycle is delayed by 50 milliseconds by the known SDL_DELAY(time in ms) function. Next the scene gets rotated. This can be achieved by the OpenGL function glROTATEf(parameters). You’ve to pass four arguments. The degree of rotation first, then three values which define the orientation of the axis around which is rotated. A triple (1.0 / 0.0 / 0.0) or (0.0 / 1.0 / 0.0) or (0.0 / 0.0 / 1.0) corresponds to a rotation around a x- or y- or z-axis respectivly. However, by linear combination of all the three components you can orient the rotation axis completly free in 3d space. For the tutorial with each cycle of the loop the tetrahedron is rotated by 5 degrees around the y axis. The color buffer gets cleared so the tetrahedron from the previous cycle disappears before drawing a new one (rotated by 5 degrees).

Now we need to construct the tetrahedron. Such constructions of objects is always done between a glBEGIN and glEND clause. Yes, even C/C++ programmers have to use Pascal’s own best BEGIN/END clause here :). Well, the glBEGIN (geometric primitive type) command needs an argument which defines what type of primitive is drawn. In our case we want to draw triangles, so we use GL_TRIANGLES here. Further common arguments are GL_POINTS, GL_LINES, GL_QUADS and GL_POLYGON, for points, lines, quads and polygons. Depending of this setting the vertices given within the glBEGIN/glEND block are interpreted. If you chose GL_TRIANGLES, three vertices are interpreted to form one triangles. However, for GL_LINES, only two vertices are needed. The first and the second vertex from our example would form one line. The third vertex would be interpreted to be the starting point for a new line, the first vertex of the next triangle block would be used as second point to form the second line and so on. Note, for 3d games usually triangles are used since most graphic cards seem to be optimized to draw them.

A tetrahedron consists of four triangular areas. Each trianglular area has three corners, these corners are called vertices in OpenGL. Within the glBEGIN/glEND clause the code has four blocks, each containing three glVERTEX3f(coordinates) and one glCOLOR3f(RGB components) commands. Each block creates one triangular area of the tetrahedron consisting of 3 vertices. Every triangular area also gets its own colour. For glCOLOR3f(RGB components) you use the three normalized colour codes for the red, green and blue component. 1.0 corresponds to 255 and means full addition of this colour component, 0.0 corresponds to 0 and means no addition of this colour component. As you may have noticed in the example always two colour components are used, e.g. red and green leads to yellow. You may prefer other combinations.

For the actual creation of a geometric primitive, like a triangle, just place the corresponding number of vertices in the 3d space and OpenGL will do the rest. It is important though to consider the order of placing the vertices. The order of placing the vertices determines what will be the front and back of the triangles. If you don’t consider this you may end up with curious results after doing back-face culling as described. Remeber: Back-face culling means, that the back of each primitive isn’t drawn. The way the triangles are created in the examples all areas have their front showing while their back is inside the tetrahedron. So without hestiation you can leave them undrawn. Imagine though what would be the result if one of the triangles would have been flipped because of placing the vertices in the wrong order. The undrawn back would show up. The impression of a rotating tetrahedron would be messed up. To get the front showing up instead of the back you have to place the vertices anticlockwise! The arguments for glVERTEX3f(x, y, z coordinate) are just the cartesian coordinates of the vertex you want to place.

Since I decided to give a rather complicated example for this tutorial (usually OpenGL tutorials explain this by cubes and six quads) I will examine the code here in more detail for the first triangle. If you’ve understood it, you’ll do cubes just by the way :). The coordinates for the first vertex are (thh / 0 / 0), the next vertex are (-thh / hh / 0) and the last vertex are (-thh / -hh / 0.5). The following image will show you how the vertices are placed in the cartesian space.

Coordinates in OpenGLAs you can check quickly, the vertices are indeed placed anticlockwise. The origin of the coordinate system (0 / 0 / 0) is approximately in the center of the triangle, actually it is in the center of the tetrahedron, when it is finished. The first vertex is placed onto the x axis at thh, the half height of the tetrahedron. The second vertex is placed on the opposite x position of the origin at -thh and has a y value of hh, the half height of an equilateral triangle. This point is still in the x/y-plane formed by the x and y axis. The last vertex has a x value of -tth and and y value of -hh, because of the z value of 0.5 this vertex doesn’t belong to the x/y-plane the other two vertices belong to. It is in front of this plane. You’ll notice a slight distorted appearance of the triangle for the third vertex, just as if it would bend towards you, that is because it actually is.

Now try to check if you understand the other vertices coordinates and if you understand why their front and not their back is showing. The loop’s last command is SDL_GL_SWAPBUFFERS which corresponds to SDL_FLIP for a pure SDL scene. It refreshes the scene. In case you have an OpenGL scene you never use SDL_FLIP or SDL_UPDATERECT to refresh the scene!

The loop quits if a key gets pressed. Then SDL and the Pascal program quit as known. If you want to learn OpenGL and its capabilities to a more advaced extend you need to read more professional tutorials related to pure OpenGL programming. As a starting point I’d like to mention NeHe Productions’ OpenGL tutorials, because they are professional and provide example code for JEDI-SDL for several lessons.

This file contains the source code: chap8.pas (right click and “save as”)
This file is the executable: chap8.exe (right click and “save as”)

The final result should look and behave like this: A tetrahedron consisting of four different coloured areas (yellow, cyan, magenta and white) is spinning slowly around itself. When pressing a key in the console the show quits.

Result of JEDI-SDL Chapter 8

Chapter 5: Text and font handling (JEDI-SDL)

This is an SDL 1.2 chapter. SDL 1.2 is obsolete since it has been replaced by SDL 2.0. Unless you have good reasons to stay here you may prefer to go for the modern SDL 2.0 :-).

This chapter will introduce you on how to load fonts and write to the screen. The ability for this is not implemented in the original SDL library itself but Sam Lantinga provides an add-on to SDL called SDL_TTF to work with texts based on the FreeType project and their FreeType 2.0 release. Fortunately the JEDI-SDL project also provides this unit for Free Pascal called SDL_TTF as well. So for preparation we have to do three things (sorry the following instructions are for Windows only but should be similar for Linux system as well. The examples after the three steps of installing should work for Linux, too.):

You need this .dll file:

Software Version Source Description
SDL_ttf-2.0.10-win32.zip 2.0.10 http://www.libsdl.org/projects/SDL_ttf/ This is the corresponding dynamic link library file.

You should extract the zip-file and get two files. A text file and the important SDL_ttf.dll. Analogous to SDL.dll in chapter 1 you have to copy them to the system32-folder. If you forget this and run the examples below you will get an error with exitcode = 309.

First of all we want to discuss the principle behind adding text to the screen within the SDL environment. Any text which is written to the screen is a simple surface itself which gets blit to the screen surface as done with graphics seen in previous chapters. In practice this means we need the screen surface again and a surface onto which can be written (here: “fontface”). The text content in the fontface surface will then be blitted to the screen surface. A simple diagram may illustrate this.

The concept of using fontsYou probably wondered already how to get the text to the “fontface” though. Exactly therefore we need the new SDL_TTF unit which has to be loaded by adding SDL_TTF to the uses clause. It provides the command TTF_RENDERTEXT_…(font, text, colour) which creates a surface with a given font, text and colour. This procedure is illustrated by the first arrow in the diagram. In fact there is not just one but many different TTF_RENDERTEXT_… modes which differ (hinted at by the three dots) in arguments list, quality, render speed and other properties. The following table will give you an overview. For dynamic ingame text or chats the solid mode is the best choice since it is the fastest rendering mode and also provides simple transparency. The following table will give you a brief overview of the modes and their properties.

Function Transparency Antialiasing Colour depth and format Quality Speed
TTF_RENDERTEXT_… in general creates surfaces with the given text (of type pChar) in ISO 8859-1 (Latin1) format; analogous you can use TTF_RENDERUTF8_… to get the the text in the corresponding UNICODE Transformation Format 8.
TTF_RENDERTEXT_SOLID(font, text, colour); yes (colorkey, 0 pixel) no 8-bit palettized (RGB) low very fast
TTF_RENDERTEXT_SHADED(font, text, colour1, colour2); no (0 pixel is background colour) yes 8-bit palettized (RGB) high fast
TTF_RENDERTEXT_BLENDED(font, text, colour); yes (alpha channel) yes 32-bit unpalettized (RGBA) very high slow
TTF_RENDERGLYPH_… in general creates surfaces with the corresponding UNICODE glyph letter (of type WORD); analogous you can use TTF_RENDERUNICODE_… to get the corresponding UNICODE letter but attention: you have to give the letter’s number as pointer, so number is of type ^WORD.
TTF_RENDERGLYPH_SOLID(font, number, colour); yes (colorkey) no 8-bit palettized (RGB) low very fast
TTF_RENDERGLYPH_SHADED(font, number, colour1, colour2); no (0 pixel is background colour) yes 8-bit palettized (RGB) high fast
TTF_RENDERGLYPH_BLENDED(font, number, colour); yes (alpha channel) yes 32-bit unpalettized (RGBA) very high slow

All of the given commands are functions and will return the NIL pointer (instead of the new surface) if the text or letter rendering failed. Let’s have a look at the code.

As always now we look at the code step by step.

The program is initilized with the name “chap5”. The unit SDL as well SDL_TTF has to be given in the uses clause! Remember please that the True Type Font system is an individual separate project and therefore you have to add this unit separately.

There are two pSDL_SURFACE variables. screen is for displaying at the physical screen as known, fontface will store the generated text by the True Type Font system before it is blitted to the screen finally. loaded_font will store font and is of pointer type. colour_font and colour_font2 are storing the text and background colour of the generated text later, they are of a specific SDL colour type which will be discussed in more detail later. i is a counting variable as known.

First the SDL system has to initilized as known from all the previous chapters. To initialize the TTF (True Type Font) system you have to use TTF_INIT which returns -1 if something failed. Notice again that the whole true type support is an own additional project (FreeType project) to the SDL library, so this cannot to be initilized by the SDL_INIT command.

To load a certain font you use TTF_OPENFONT(font,point size), or more specific TTF_OPENFONT(const filename:PCHAR; ptsize:INTEGER):pTTF_FONT. This command is a function that returns a usual pointer (which pTTF_FONT actually is)! The parameters are the absolute(!) path to the font (e.g. C:\WINDOWS\fonts\arial.ttf) and the point size which detemines the size of the letters. These font information are accessed by the loaded_font pointer initially defined.

So next we have to determine the colour of the letters and the message itself. The colour is determined by a pSDL_COLOR record, which is of course kind of pointer. In pSDL_COLOR record there are three elements (actually four, but the forth is unused) which can be accessed by .r,.g and .b and determine as common the shares of red, green and blue colour. You will agree that writing a function allocation of RGB triples can be senseful, especially if you have to handle many different colours but for our example we won’t do this though since we just have to define two colours. The fact that pSDL_COLOR is of pointer type needs us to set colour_font and colour_font2 up by NEW command and free it finally by DISPOSE. These commands you should be familiar with because they are usual Pascal commands.

Now we use TTF_RENDERTEXT_SHADED(font, text, colour1, colour2), or more specific TTF_RENDERTEXT_SHADED(font:pTTF_FONT; const text:PCHAR; fg:tSDL_COLOR; bg:tSDL_COLOR):pSDL_SURFACE, which we introduced recently (check the table). It returns a pSDL_SURFACE. We return it to fontface. The parameters are the used font as pointer (loaded_font), the message string and the colours (colour_font, colour_font2). colour_font will provide the foreground colour which should be red since we defined R=255, G=0, B=0. The background should get cyan since we defined R=0, G=255, B=255. If the rendering process works fine we have the text in the specified colours in fontface.

The fontface surface is a usual SDL surface so you can now do every manipulation you want or at least blit it to the screen surface and display the text after updating/flipping.

Finally all the variables and surfaces have to disposed as known. Like every SDL surface has to be free’d and SDL system has to be quit so has the TTF system. The procedures TTF_CLOSEFONT(font:pTTF_FONT) and TTF_QUIT have to be used to do this.

Now you are able to write ;).

This file contains the source code: chap5.pas (right click and “save as”)
This file is the executable: chap5.exe (right click and “save as”)

The final result should look and behave like this: The text “Hello World!” is displayed having red letters on cyan background.

Result of JEDI-SDL Chapter 5

Chapter 3a: Displaying different picture formats (JEDI-SDL)

This is an SDL 1.2 chapter. SDL 1.2 is obsolete since it has been replaced by SDL 2.0. Unless you have good reasons to stay here you may prefer to go for the modern SDL 2.0 :-).

In the previous chapter it was shown how to load bitmap images in the bitmap format. You may have wondered if there is a possibility to load other formats than bitmap images. The JEDI-SDL package provides a unit called SDL_IMAGE which exactly is created for this purpose. The following formats you can load according to the unit’s C/C++ documentation: TGA, BMP, PNM, XPM, XCF, PCX, GIF, JPG, TIF, LBM, PNG. I had troubles loading XCF images which is probably due to the fact this format is not standardized.

You need this .dll file to work successfully with the new unit:

Software Version Source Description
SDL_image-1.2.7-win32.zip 1.2.7 http://www.libsdl.org/projects/SDL_image/ This is the corresponding dynamic link library file for unit and image formats.

You should extract the zip-file and get six files. A text file, the important SDL_image.dll and several image format DLLs. Analogous to SDL.dll in chapter 1 you have to copy them to the system32-folder. If you forget this and run the examples below you will get an error with exitcode = 309.

After installation of the unit we now can proceed to the source code.

The code shows the same picture known from chapter 3 in three different formats: PNG, JPG and TIF. You should download them (right-click onto each image and save) and put them at a desired location of your hard drive. Don’t worry if the tif image isn’t shown properly in your web browser. Since it isn’t a native web image format most web browsers don’t support it. However you can still download it.

tif image - usually not shown
TIF image – usually not supported natively by browsers to be displayed
Free Pascal example image in different formats
JPEG images

fpsdl
PNG image

First we need to include the SDL unit, of course we need also the SDL_IMAGE unit. The STRINGS unit is needed to handle file pathes a simple and short way. The latter unit is not related to the SDL library.

Now we define a constant, which contains the absolute path to the image files. The path is C:\FPC\2.2.4\my_images\. Of course you are free to choose any other location. Each file is named “fpsdl.” and the corresponding extension, like “bmp” for bitmap image, “png” for portable network graphics image, and so on. They all lie in the folder my_images.

In the variables part we define the screen surface again and an array of picture surfaces, all of kind pSDL_SURFACE. The screen surface decides what is shown at the display and the picture surfaces will store the images from image files of different formats. Next two arrays for the file extensions of the different image formats (bmp, png,…) and the image file paths are defined and of kind PCHAR. Finally we define the counter variable i.

As usual we start by initating the SDL library, defining a 200 x 200 pixels window and check if it was successful. The next part defines the different file extensions we want to use. In this example we will show the ability of SDL_IMAGE to load png, jpg and tif images. Feel free to try out all the other common formats by extending this demo program. Again I’d like to mention that I experienced troubles loading GIMP’s images in XCF format.

The presented loop is the core of this demo program. It shows the preparation of the file locations and names, the creation of the image surfaces and the final blit to the screen surface to display them.

The loop will be cycled three times, once for each file. First we reseve some space on the heap and insert the constant file string by STRNEW. Next we concatenate the file path and the extension by STRCAT. For these operations we needed to include the STRINGS unit. Both commands aren’t related to the SDL library.

Then IMG_LOAD(absolute path/image file) function allows to load image data from image files with many different image formats to a surface. That is the key function of this demo program. However, be aware that the image data loaded to the surface is not compressed anymore and is stored in the usual RGBA format of SDL surfaces. The function returns NIL if it failed.

Since the example pictures have the same dimensions as the screen surface they can be blitted easily by SDL_BLITSURFACE as shown. The screen gets refreshed by SDL_FLIP. Both commands you know from the recent chapter. Finally we wait for the user to press enter after each cycle.

Now we have to clean up anything. The loop disposes the picture surfaces and the path strings. Finally the screen surface gets disposed and the SDL environment quit by SDL_QUIT. Except for STRDISPOSE you should remember any command from previous chapters. STRDISPOSE is a command from STRING unit, so again no SDL library related command.

This file contains the source code: chap3a.pas (right click and “save as”).
For this chapter no executable is provided.

Hope you are successful and have fun.

The final result should look and behave like this: First the “Free Pascal meets SDL” image appears in one of the the image formats (different of bitmap). Everytime you press return (or enter) in the console the same image with another format is displayed until the program quits.

Result of JEDI-SDL Chapter 3a

Chapter 1: Introduction, installation and configuration (JEDI-SDL)

This is an SDL 1.2 chapter. SDL 1.2 is obsolete since it has been replaced by SDL 2.0. Unless you have good reasons to stay here you may prefer to go for the modern SDL 2.0 :-).

The introduction is short. SDL library gives you the ability to develop powerful applications for many different operating systems (OS, e.g. Linux, Windows, MacOS) only by learning one set of commands. The SDL library takes on the assignment to translate your commands to the specific OS commands. It’s especially meaningful to use the SDL library if you plan to develop two-dimensional games or similar software. Role-playing-, Real time/turn based strategy-, side-scrolling-, arcade-, board-, card-, simulation-, multi-user dungeon-, puzzle games and so on are possible. SDL helps you to set up easily an SDL/OpenGL environment which allows for creation of 3d applications. This finally allows even for three-dimensional games.

Now something about the licensing: Both, Free Pascal and the SDL library are free and your created work can be used in commercial programs! The license of Free Pascal is: modified LGPL and the license of SDL: GNU LGPL.

By this the introduction to SDL is finished already. Before you accidently proceed reading the manual installation of the SDL units for the Free Pascal compiler (FPC) I’d like to express that since version 2.2.2 of FPC the pure, pre-compiled JEDI-SDL units are released along with the compiler so actually there is no need to install the SDL units manually anymore. Keep in mind though, many chapters assume you did the manual installation, so there are some envornment settings described you can skip. You don’t have to set individual pathes to the different unit files. However, what you always HAVE TO consider is the download and copy of the corresponding DLL files described in the chapters. If you already have installed Free Pascal (version 2.2.2 or later) just go on with Chapter 1a now.

If you decide to do the manual installation there are two different unit packages which allow the development of SDL applications with the Free Pascal environment. If you don’t know which to choose I recommend strongly to choose the package of the JEDI-SDL Project! It is more advanced and supports a greater variety of features. This is also the package which is included in FPC nowadays.

LINUX USERS: The following description of the configuration is related to the MS Windows OS. The further chapters (except chapter 1 and 1a) will work for Linux OS, too. (If you want to contribute a configuration tutorial for Linux OS let me know; you would be mentioned as author of course.)

Which package of SDL units you want to install (MS Windows OS)?

JEDI-SDL (recommended)

SDL4FP

Now this chapter concerns on the installation of all necessary software on your system for programming SDL applications with Free Pascal on Windows XP (probably this will work for other Windows systems as well; please report if you tried out; what about Vista?).

First of all, we have to consider which software is needed. We need three different software packages. We need the Free Pascal compiler of course. Furthermore we need the original SDL library files and finally we need something what translates our Pascal programs to the SDL library (written in C/C++). This will be done by a few units. These units come from the JEDI-SDL Project (Joint Endeavor of Delphi Innovators – Simple Direct Media Layer Project).

This table provides all information you need about the files you need to download with respect to installation steps 1) – 3).

Software Version Size, MB Source Description
fpc-2.2.4.i386-win32.exe 2.2.4 ~35 http://www.Free Pascal.org Download the latest stable Free Pascal compiler.
JEDI-SDLFullSetup.exe
(Full Installer!)
1.0 Final RC2 ~5 Main site:http://jedi-sdl.pascalgamedevelopment.com/
Downloads:http://sourceforge.net/forum/forum.php?forum_id=724777
Download the latest version of JEDI-SDL package.
SDL-1.2.13-win32.zip 1.2.13 ~0.1 http://www.libsdl.org (German readers may prefer: http://www.libsdl.de/) Download the latest stable runtime library of SDL.

1) Download the latest stable Free Pascal compiler, version 2.2.4 or higher.

2) Download the latest version of JEDI-SDL, version 1.0 Final or higher. Be sure it is the full installer (not headers only or demos only).

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

Of course, if you have installed Free Pascal already you haven’t to download it again and you can skip step 4.

4) Execute “fpc-2.2.4.i386-win32.exe” to install Free Pascal. 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\2.2.4\’.

5) Extract “SDL-1.2.13-win32.zip” to get the SDL runtime library. This leads to two extracted files. There is a text file and the very important SDL.dll.

6) Copy those files (especially the SDL.dll!) to your
system32-folder! Usually you find it at “C:\WINDOWS\system32\”.
Don’t confuse it with the similar system-folder. (This works for
WinXP, probably for NT-series and Win2000 as well; if you use Win9x
or WinME you should copy it to system-folder instead of system32-folder)

If it isn’t possible for any reason to copy the files into this folder you later have to copy that file into the same folder where the application is. Now you have installed Free Pascal and the SDL runtime library on your system. Finally JEDI-SDL has to be installed.

7) Execute the “JEDI-SDLFullSetup.exe” and follow the installer’s instructions. Since you should avoid a folder name like “JEDI-SDL Full” which is suggested by the install program when asking for the install path, I suggest as full path: “C:\FPC\2.2.4\units\JEDI\”. All later tutorials will assume you installed to this path.

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

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

9) In the menue choose the following item “Options”. From “Options” choose “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\2.2.0\units\JEDI\SDL\Pas) below the other pathes. Leave the last backslash out. Make sure the path leads to the folder, where the sdl.pas file is located! This file contains all the basic features of SDL.

JEDI-SDL Directories

The picture doesn’t show the correct path! It is old. We use “C:\FPC\2.2.4\units\JEDI\SDL\Pas” instead. Confirm by clicking “OK”.

Congratulations! You have configured your system for developing SDL applications with Free Pascal! Now let’s check if it really was that easy…

11) To check if you installed your system successfully download the file demo02.pp (right click and “save as”) into demo-folder (C:\FPC\2.2.4\demo\) or anywhere else.

12) Open this file and run it.

If you see some cool colourful red and blue lines you have done everything as it has to be done :)! Have fun with your configured system!

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

VERY IMPORTANT

Since most users will not install FPC/SDL manually I removed the information about setting up the unit pathes in the compiler settings part of each individual chapter. However for you, without setting the unit pathes in your IDE you will get errors. Next is a list of the settings for each chapter where necessary IF you do the manual installation.

Chapter 3a

1) Make sure your compiler finds the new unit. (IDE: Options –> Directories… –> Units)

JEDI-SDL Directories for font handling2) Copy the file “jedi-sdl.inc” from the “../SDL/Pas”-folder into the “../SDL_image/Pas/”-folder. Both folders are located in the JEDI-SDL project folder (e.g. C:\FPC\2.2.4\units\JEDI\). If you forget this you will get an error on compiling saying SDL_IMAGE is not finding jedi-sdl.inc.

3) You need this .dll file:

Software Version Source Description
SDL_image-1.2.7-win32.zip 1.2.7 http://www.libsdl.org/projects/SDL_image/ This is the corresponding dynamic link library file for unit and image formats.

Chapter 5

1) Make sure your compiler finds the new unit. (IDE: Options –> Directories… –> Units)

JEDI-SDL Directories for font handling2) Copy the file “jedi-sdl.inc” from the “../SDL/Pas”-folder into the “../SDL_tff/Pas/”-folder. Both folders are located in the JEDI-SDL project folder (e.g. C:\FPC\2.0.4\units\JEDI\). If you forget this you will get an error on compiling saying SDL_TFF is not finding jedi-sdl.inc.

3) You need this .dll file:

Software Version Source Description
SDL_ttf-2.0.10-win32.zip 2.0.10 http://www.libsdl.org/projects/SDL_ttf/ This is the corresponding dynamic link library file.

Chapter 7

1) Make sure your compiler finds the new units. (IDE: Options –> Directories… –> Units) For the usage of SDL_MIXER you have to include both, the SDL_MIXER itself and the SMPEG unit (which is used by SDL_MIXER unit). The SMPEG unit actually is only used for mp3 support but your programs will fail to run even if you don’t use mp3 files.

JEDI-SDL Directories for sound handling2) Copy the file “jedi-sdl.inc” from the “../SDL/Pas”-folder into the “../SDL_Mixer/Pas/”-folder and “../smpeg/Pas/”-folder. All folders are located in the JEDI-SDL project folder (e.g. C:\FPC\2.0.4\units\JEDI-SDLv1.0\). If you forget this you will get an error on compiling saying SDL_Mixer or smpeg is not finding jedi-sdl.inc.

3) You need this .dll file and a music and sound file:

Software Version Source Description
SDL_mixer-1.2.8-win32.zip 1.2.8 http://www.libsdl.org/projects/SDL_mixer/ This is the corresponding dynamic link library file.
In my mind.ogg In-my-mind.ogg A music file. “In my mind” by First. Of course you could also use any other music file you desire.
dial.wav dial.wav Public domain sounds: http://www.pdsounds.org. Of course you could also use any other sound file you desire.

Chapter 8

1) Make sure your compiler finds the new units. (IDE: Options –> Directories… –> Units) You will need to add the path to the OpenGL units GL and GLU. GL provides the whole basic OpenGL functionality and GLU (OpenGL Utilities) provides some additional functions which are very useful but not provided as basic functions of OpenGL (version 1.1).

JEDI-SDL Directories for OpenGL support2) Copy the file “jedi-sdl.inc” from the “../SDL/Pas”-folder into the “../OpenGL/Pas/”-folder. All folders are located in the JEDI-SDL project folder (e.g. C:\FPC\2.2.4\units\JEDI\). If you forget this you will get an error on compiling saying GL or GLU is not finding jedi-sdl.inc.

3) You need this software:

Software Version Source Description
OpenGL driver Usually your graphic card provides the corresponding OpenGL driver and you don’t have to do anything. And if so it is very likely that version 1.1 is fully supported. However if you are one of the few poor people whose graphic card doesn’t support OpenGL, check the graphic card’s manufacturer’s homepage for OpenGL drivers.

Chapter 7: Sound and Music (JEDI-SDL)

This is an SDL 1.2 chapter. SDL 1.2 is obsolete since it has been replaced by SDL 2.0. Unless you have good reasons to stay here you may prefer to go for the modern SDL 2.0 :-).

This chapter will introduce you on how to load music and sounds since these are key features of every game and many applications. An easy way to play music (.wav, .mod, .mid, .ogg, .mp3) and sound files (.wav, .aif, .ogg, .voc) is the usage of an additional unit called SDL_MIXER. This unit is maintained by the same author which also provides the core SDL library, Sam Lantinga and the co-authors Stephane Peter and Ryan Gordon. Fortunately the JEDI-SDL team translated this unit so it is available for Pascal programmers.

You need this .dll file and a music and sound file:

Software Version Source Description
SDL_mixer-1.2.8-win32.zip 1.2.8 http://www.libsdl.org/projects/SDL_mixer/ This is the corresponding dynamic link library file.
In my mind.ogg In-my-mind.ogg A music file. “In my mind” by First. Of course you could also use any other music file you desire.
dial.wav dial.wav Public domain sounds: http://www.pdsounds.org. Of course you could also use any other sound file you desire.

You should extract the zip-file (SDL_mixer-1.2.8-win32.zip) and get six files. A readme text file, the important SDL_mixer.dll and several further .dll files. Copy all of them to the system32-folder. If you forget this and run the examples below you will get an error with exitcode = 309.

Here we go now, the complete code at once. Go through it an look if you get what the program will do when you run it.

ATTENTION: I experience a strange runtime error (216: General Protection Fault) with some curious symbols in popup window when trying this example program from IDE. The compiled program runs well though. In other projects I don’t get this behaviour. Probably it has to do with the call of MIX_VOLUMECHUNK and you may comment it out. The music and sound can’t be heard when run from IDE. You have to compile the program and execute the compiled program. This by the way isn’t needed for other projects. Not sure on the reasons for this strange behaviour here.

Probabably you looked through the code now. Now we can go step by step through the code from top to bottom.

The program is called “chap7” (quite imaginative, isn’t it?). Now we include three units. The common SDL unit already known. The CRT unit is known from chapters 3 and 4 where we needed it to check when the user pressed a key. We need it here for the very same purpose. New is the SDL_MIXER unit which is needed to allow us to use the sound subsystem in an easy way.

You may ask why we didn’t use the event handling structure we know from chapter 6 to recognize when the user presses a key instead of the keypresed command from CRT unit. Well, I think it isn’t of an advantage if you mix up the different parts of SDL for learning purposes. Furthermore this “raw” way the source code stays tighter and therefore more readable.

Next we define some constants which will be used to intilize the sound system. Of course you also can add the different values directly when inilizing the sound system. We need the sample frequency in Hertz (1/s) which usually is 22050 Hz or MIX_DEFAULT_FREQUENCY in games but double as high for CD quality sound (44100 Hz).

Next we have to define the audio format. It determines how the audio data is stored. Different values are given in the following table (from official SDL Mixer documentation):

audio format 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
AUDIO_S16 same as AUDIO_S16LSB
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 type, which means either stereo or mono. For stereo sound we choose 2 and for mono we choose 1 as value. Finally the chunksize has to be set, where 4096 bytes per sample is a default value. The lower this value the worse the quality.

Now we define some variables. First we define a CHAR varibale which later reads the keyboard input of the user. This variable is just for this purpose and has no direct connection to the sound system or SDL. Variable music which is a pMIX_MUSIC pointer is very important. It points at the loaded music file later! Same applies for sound which is a pMIX_CHUNK pointer. Both pointers are initilized as NIL pointers here. Note: Each music 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.

In this demo we just want to demonstrate the music/sound abilities of SDL so we only initialize the audio subsystem by SDL_INIT_AUDIO. Similar to the initilization of the graphic system we then have to set up the audio system by the function MIX_OPENAUDIO(parameters). The four paramteters needed we already defined and discussed above. The function will return 0 on error.

We will load the music to the music pointer by MIX_LOADMUS(absolute path to music file). If the Pascal file and the music file are in the same folder you can give the music file’s name without a path (as shown in the example). The same way you load up sound files with MIX_LOADWAV function. The same function is used to load other file formats instead of .wav sound files even though the function’s name doesn’t indicate this. Both functions return NIL on error (which we don’t check in the example though). The functions MIX_VOLUMEMUSIC(integer) and MIX_VOLUMECHUNK(sound pointer, integer) set the volume for the music sound file. Note: If you have more than one music and sound file you have to set the volume for each sound file individually but the music volume is set for all music files together. The volume values are integers between 0 (silence) and 128 (highest volume). The constant MIX_MAX_VOLUME corresponds to 128.

The writeln commands for displaying text at the shell should be known. The MIX_PLAYMUSIC(music pointer, integer) is used to play music files. Therefore we give the music pointer which we called “music” and we give the number of loops this music file should be played. As the comment states -1 means the music is replayed infinitly, 0 means the music is played once, 1 means the music is played twice and so on. The function returns -1 on error and 0 on success (which we don’t check in the example).

Similarly sounds are played. Contrary to music which has its own seperated channel, sounds have up to eight channels (channel numbers 0 to 7) where they can be played at. This means you can have up to eight sounds that play at the same time and can be heard at the same time! As for music files you have to say which sound you want to play and how often but additionally you have to say at which channel you want it to play. The function is MIX_PLAYCHANNEL(paramters) which returns the channel number the sound is played on or -1 on error. The first parameter is the channel you want the music to be played. -1 means the first free channel will be chosen automatically. What will happen when all channels are used but a further sound is going to be played? One playing sound will be stopped and the new sound will be played on this channel. The next two parameters are the same as for music, the sound pointer and the integer how often the sound will be played.

The repeat-until loops, the commands KEYPRESSED, READKEY and the variable userkey aren’t SDL specific but common Pascal commands and they will hold the user in the loop until he decides to leave it by pressing the “q” button. This will not be explained here in detail.

The different cases in the case block show the usage of playing a sound (which is discussed already) and different functions to pause/resume music and sounds. The procedures MIX_PAUSEMUSIC and MIX_RESUMEMUSIC pause and resume the actively playing music. Similar for sounds but you actually don’t pause/resume the sounds themselves but the channels they are played on. This channel we don’t know because we said MIX_PLAYCHANNEL should find the first free channel automatically but we returned the channel number in variable “soundchannel”. MIX_PAUSE(channel number) and MIX_RESUME(channel number) will pause and resume the desired channel when using “soundchannel” as parameter.

The commands MIX_HALTMUSIC and MIX_HALTCHANNEL(channel number) are used to stop playing the music/sound immediatly. As for surfaces the msuic/sound files have to be freed when they are not used anymore. The functions MIX_FREEMUSIC(music pointer) and MIX_FREECHUNK(sound pointer) are used for this. Finally the audiosystem and SDL have to be shut down by MIX_CLOSEAUDIO and SDL_QUIT.

This file contains the source code: chap7.pas (right click and “save as”)
This file is the executable: chap7.exe (right click and “save as”)

Chapter 4a: Primitives, Image rotation/zooming, Framerate (JEDI-SDL)

This is an SDL 1.2 chapter. SDL 1.2 is obsolete since it has been replaced by SDL 2.0. Unless you have good reasons to stay here you may prefer to go for the modern SDL 2.0 :-).

In the previous chapter it was shown how to draw one pixel to the screen. Of course you could now develop routines to draw primitives from this single pixel manipulation but to make life easier someone (Andreas Schiffler) did this already for you. And furthermore the JEDI project already translated it for you to use it in Free Pascal :).

Maybe you remember the Turbo Pascal GRAPH unit which allowed to draw simple primitives like lines, squares, rectangles, circles, polygons and so on. Exactly this part is now fulfilled by the SDL_GFX unit in a SDL environment. So from now on you can also draw sprites directly to the surfaces and don’t have to draw them externally in a painting program. If you choose to draw sprites directly with this set of primitives or create them externally depends on your needs and preferences. Of course you can combine both features, load up an image first, then manipulate it further by the features shown in this chapter.

As an example you could imagine a game where you have game objects of the same type for each player which only differ by the same coloured elements. You now could create several object images with the possible different colours externally. However, if you want to provide 100 different colours you have to load up the object’s image 100 hundred times into your painting program, colour it, save it. You need 100 times the colour images space on hard disk. – With the provided functions you could just create ONE image of the units with a “wild card colour”, let’s say white. Now you just have to write a function which recognizes white areas on the image and colour it in 100 different colours, save it to hard disk (same space usage as first method) or in heap (no further hard disk space is needed!). Especially useful is the SDL_GFX unit if the white areas are of shape rectangle, circle, polygon or just a single pixel.

Before starting with SDL_GFX be aware that it is distributed by a third party developer, Andreas Schiffler. Unfortunately he is not distributing the pre-compiled shared library (DLL file) but instead he provides the source code only. So you are in need of compiling this file yourself or download the compiled SDL_gfx.dll file (zipped) (version 2.0.19) I compiled for you. The source code is written in C++ so you can’t use the Free Pascal compiler to do the compilation yourself. In the first part of this chapter I will deal with the compilation of your own DLL. The provided a pre-compiled SDL_gfx.dll (zipped) was compiled by me under 32 Bit Windows XP Professional on an AMD processor and usage might cause problems for 64 Bit systems and differing operating systems and processors. Furthermore it might be outdated, it’s version 2.0.19. In all these cases you should really consider to compile your own DLL file if the provided file isn’t working for you. If you use the pre-compiled DLL file you can skip the compilation procedure, just go on reading after the 15 step procedure for compilation below.

For compilation we need several things. We need a free C++ compiler to compile the DLL file from the source code. Of course we need the source code of SDL_GFX itself. Furthermore we need the SDL Development Library for Windows. The following table shows the names of the most recent files and their location.

Software Version Source Description
MinGW C++ Compiler 5.1.4 http://www.mingw.org/ The mainpage of the MinGW C++ Compiler, there look for “downloads” and get the most recent version, preferably with autoinstaller.
SDL_gfx-2.0.22.tar.gz 2.0.22 http://www.ferzkopp.net/ SDL_gfx C++ source code from Andreas Schiffler’s homepage. Look for “Software”, there for “SDL_gfx”.
SDL-devel-1.2.14-mingw32.tar.gz 1.2.14 http://www.libsdl.org/ SDL development library. Look for “SDL 1.2” in the menu, then for the development libraries.

1) First of all, get the MinGW C++ compiler installed. Make sure you check the g++ compiler, which is actually the C++ compiler we are looking for! The other compilers you can leave unchecked. See the picture below.

MinGW Install window

2) Extract the Development Library of SDL (SDL-devel-1.2.14-mingw32.tar.gz or newer).

3) Among other things there should be one folder called “lib” within the newly created folder of step 2. Copy the complete content of folder “lib” (3 files) into a folder also named “lib” in the MinGW directory. Make sure only to copy these three files, not the folder “lib” itself.

4) There is also a folder “include” in the extracted SDL Development Library folder. It contains one further folder called “SDL” (contains 34 files). This time copy this folder “SDL” as a whole into the “include” folder of the MinGW installation.

5) Now MinGW is fully prepared for the compiling of SDL_GFX.

6) Extract now the source code of SDL_GFX (SDL_gfx-2.0.22.tar.gz or newer).

7) Within the newly created folder you find a folder called “Other Builds”. Enter this folder. Within this folder you will find several zip files.

8) Extract file “mingw.zip”. This creates a new folder “mingw” and contains exact two files, “Makefile” and “README”.

9) Copy “Makefile” into the root folder of SDL_gfx.

10) Before using this makefile some changes have to be applied. The following script shows the first few lines of the makefile. The bold red printed parts have to be changed according to your needs. [REMARK: Now the lines are marked.]

11) “c:/dev/local” has to be the path to the MinGW root folder [Line 5]. Remove flag “-DWIN32” [Line 10] and change the include flag/path to the corresponding (MinGW root folder)/include/SDL [Line 10, “-I(your path)/include/SDL”]. By the way, make sure to use slashes “/” instead of backslashes “\” to separate folders. Also give the library path as (MinGW root folder)/lib [Line 11, “-L(your path)/lib”]. Now save this makefile.

12) To compile the DLL file now, open the command window of Windows by using Start–>Run…, there type “cmd” and the n “OK”. A new “DOS-like” window will pop up.

12) Change the directory to the SDL_GFX root folder by using the DOS commands “cd (foldername)” and “cd..” to enter or leave a folder.

13) Now just give the full path to the MinGW make program located at “(MinGW root folder)\bin\mingw32-make”. Now press enter and see how your DLL file gets compiled.

14) If everything worked well you find a brand new SDL_gfx.dll in your SDL_GFX root folder.

15) Copy this file to your WINDOWS\system32 folder or to the folder where the application is located which is using SDL_GFX.

Now, since compilation is finished (or you skipped the compilation procedure) just a short hint about the licensing, SDL_GFX is licensed under the LGPL, which essentially means you can also use it in proprietary software.

Before proceeding make sure Free Pascal finds the SDL and SDL_GFX units (Options–>Directories…), however, if you installed a recent binary Free Pascal package you don’t have to care about this. Free Pascal then is already well configured to work with SDL and SDL_GFX.

Now we can proceed to the source code. Here is the full source code of the example program. It will rotate and at the same time zoom an image constantly and additionally draw some primitives to the screen.

Now that you know the whole code, let’s discuss it step by step.

The program is called “chap4a” and uses the known units SDL and CRT (CRT for easy recognition of user pressing a key on the keyboard). Additionally the new unit SDL_GFX has to be included here. The latter unit provides the functionality described below.

There is a constant block defining two constant arrays “x_array” and “y_array” containing six elements of SINT16 (16 bit signed integer) corresponding to six x and y values. These will be needed later to define a polygon and a Bézier curve.

Three surface variables are defined. The “screen” variable represents the screen surface. The “original_image” surface stores an image, which then is manipulated (rotation and zooming) and the result is stored in the “modified_image” surface. The float number variables “angle_value” and “zoom_value” are storing a certain rotation angle and a zoom factor. Finally variable “framerate” is defined as a framerate manager variable pFPSMANAGER which is new and provided by SDL_GFX. This helpful tool is discussed in much detail later. Finally two variables “calc_width” and “calc_height” are defined and have to be of type LONGINT. They will store the estimated new size of the surface after rotation and zooming.

The “screen” surface is initialized as known from previous chapters with 400 x 400 px. The “Free Pascal-meets-SDL” bitmap image from Chapter 3 is loaded to the surface variable “original_image”. For those who don’t remember the image, here it is again:

Free Pascal meets SDL sample image bmp format
download (right click and “save as”)

Notice, this image has 200 x 200 dimension. The “original_surface” surface will be the source for any manipulation. The second surface “modified_image” gets some space allocated and is ready for usage. However until now it stays empty. The rotation angle and the zoom factor are set to zero.

The framerate manager “framerate” gets some space and is initialized by PROCEDURE SDL_INITFRAMERATE(manager:PFPSmanager). Then the framerate is set in Hz (Hertz) by FUNCTION SDL_SETFRAMERATE(manager:PFPSmanager; rate:INTEGER):INTEGER which returns 0 on success and -1 if something is wrong. The default value is 30 Hz. It is also stored in flag FPS_DEFAULT. Additionally there are FPS_UPPER_LIMIT and FPS_LOWER_LIMIT which correspond to 200 and 1 Hz. Not shown in the example code is FUNCTION SDL_GETFRAMERATE(manager:PFPSMANAGER):INTEGER which will just return the set FPS value, however it will not return the real framerate. Even if the framerate dropped to 1 Hz it will return 30 Hz since this is the set value.

Well, some notes about the framerate: The framerate is usually a value indicating how many frames per second are drawn and shown at the screen. 30 Hz means there are 30 frames drawn to the screen within one second. Often the frequency if abbreviated by FPS meaning Frames Per Second, thus 30 FPS is the same as 30 Hz. If you perform many drawing operation or costly drawing operations (especially 3d applications know this) then it might be that the framerate drops because the system (processor and/or graphic hardware) isn’t capable of drawing fast enough to keep 30 frames per second.

So what about the framerate manager, how does it help? In simple programs the SDL_DELAY(delay in milli seconds) function is used to control the framerate if placed in the rendering loop (the loop which flips the scene to the screen surface). Assuming you set is to 33, so SDL_DELAY(33) it means every 33 ms one frame is drawn, this means approximately 30 frames are drawn within one second! Thus the framerate is 30 Hz here as well. However this only applies if you assume that the drawing itself doesn’t need time, which is a good approximation for simple applications and simple scenes. When drawing more complex scenes the drawing itself will take some milli seconds or even more time, the SDL_DELAY function will just add its delay time, so this leads to a remarkable delay. In contrast a framerate manager recognizes that the framerate dropped and will skip the delay time to keep the framerate at 30 Hz (or whatever value is set). Additionally the framerate manager is keeping the actual framerate more accurately at the framerate, in the contrary SDL_DELAY is quite inaccurate.

Now the rendering loop is entered. Every cycle the rotation angle is increased by 1.0 degree. Also the zoom factor is increased by 0.05 every cycle. A zoom factor of 1.0 means no change of the picture. Values smaller than 1.0 mean shrinkage of the image, values larger than 1.0 mean enlargement of the image. A value of 0.5 and 2.0 mean half the size and double the size of the original image respectively. The two IF clauses ensure that the value of “angle_value” is restored to 0 (equals 360) degree (no rotation), if the image is rotated by 259 degree. If the image got zoomed to twice its original size, “zoom_value” gets restored to 0.0.

PROCEDURE ROTOZOOMSURFACESIZE(width:INTEGER; height:INTEGER; angle:DOUBLE; zoom:DOUBLE; VAR dstwidth:INTEGER; VAR dstheight:INTEGER) calculates the new surface size after rotation and zooming. The first two parameters are the width and height of the initial surface (in our example the image/surface has 200 x 200 dimension). The next two parameters expect the rotation and zoom values (in our example they are stored in “rotation_angle” and “zoom_angle”). The last two parameters store the return values. The results will be returned to “calc_width” and “calc_height” in our example. They are written to the screen. Now one of the most amazing functions of the SDL_GFX unit is introduced. It allows the rotation and zooming of an image. In FUNCTION ROTOZOOMSURFACE(src:pSDL_SURFACE; angle:DOUBLE; zoom:DOUBLE; smooth:INTEGER):pSDL_SURFACE you give the source surface first, which is the surface with the original image in our case, then the angle and zoom factor which we discussed right before and finally if antialiasing should be performed. Antialiasing means to smooth edges. 0 means no antialiasing, 1 means antialiasing, well, also two flags you could use, SMOOTHING_OFF and SMOOTHING_ON. (However I experienced that antialiasing didn’t work out even though a 32 bit surface is used which is necessary to perform antialiasing as the author stated.)

There are some accompied functions not demonstrated in the example code which should be mentioned now. FUNCTION ZOOMSURFACE(src:pSDL_SURFACE; zoomx:DOUBLE; zoomy:DOUBLE; smooth:INTEGER):pSDL_SURFACE zooms only without rotation but zooming in x direction and y direction can be set independently. FUNCTION ROTOZOOMSURFACEXY(src:pSDL_SURFACE; angle:DOUBLE; zoomx:DOUBLE; zoomy:DOUBLE; smooth:INTEGER):pSDL_SURFACE is the same function as before but with rotation additionally. For both of these functions also corresponding procedures exist which return the size of the newly created surfaces. Thay are PROCEDURE ZOOMSURFACESIZE(width:INTEGER; height:INTEGER; zoomx:DOUBLE; zoomy:DOUBLE; VAR dstwidth:INTEGER; VAR dstheight:INTEGER) and PROCEDURE ROTOZOOMSURFACEXYSIZE(width:INTEGER; height:INTEGER; angle:DOUBLE; zoomx:DOUBLE; zoomy:DOUBLE; VAR dstwidth:INTEGER; VAR dstheight:INTEGER). They work the very same way as demonstrated in the example code.

It is very important to keep in mind that every manipulating procedure (rotation and zooming) is distorting the image information. So the number of manipulations should be keep as small as possible. In the example every cycle of the loop the original image gets manipulated exactly two times. It gets rotated once and zoomed once. Instead of this you could also implement a recursive solution, namely rotating the original image in the first cycle by one degree, take the resulting image and rotate it in the second cycle again by one degree, and so on. Let’s check for the result after 25 cycles, in fact both methods rotated the image by 25 degree, but well, the quality is remarkable different. And this neglecting the zooming which has an even worse impact on quality if implemented recursively. The following drawing will illustrate what the results will look like. On the left the rotation of the original image by 25 degree once, on the right the rotation of the same image 25 times by one degree.

Results of different rotation implementations
Left: Rotation once by 25 degree; Right: 25 Rotations by one degree

The loss of information with each cycle will add up for each manipulation leading to ugly results like the right one. Compare this to the left image where no loss of information is noticable.

As promised SDL_GFX is able to draw a lot of primitives. The primitives shown in the example code are just a few of them. The principle of implementing them is demonstrated anyway. The table below gives the complete list of primitives you can use. Most of the functions are intuitive, so a circle is defined by its position (x/y values), its radius r and its colour. The same applies for a filled circle. An ellipse is defined by its position (x/y values), its horizontal and vertical axes rx and ry, and its colour.

Especially polygon and Bézier curve calls may be not so intuitive. The polygon function is function POLYGONCOLOR(dst:pSDL_SURFACE; const vx:pSINT16; const vy:pSINT16; n:INTEGER; color:UINT32):INTEGER and the Bézier curve function is function BEZIERCOLOR(dst:pSDL_SURFACE; const vx:pSINT16; const vy :pSINT16; n:INTEGER; s:INTEGER; color:UINT32):INTEGER. As for all the other functions you define the surface first onto which you would like to draw these primitives. The next parameters expect a pointer (pSINT16) to an array of x values of type SINT16 (16 bit unsigned integer) and an array of y values of the same type. This is achieved by the @ operator at the first and fourth element of the arrays respectivly. These vectors were defined initially in the constant block, you should remember. The next parameter n is the number of points the polygon has or the number of reference points the Bézier curve has. If the arrays contain six elements, n should be six as well. Since in the case of the Bézier curve only the last three elements are of interest (at least in our example), n has to be three and the resulting curve is of order four (quadratic Bézier curve). The s value defines the smoothness of the curve. The higher s the higher the smoothness.

Some general information about these primitive functions: All functions presented here have the same suffix …COLOR. This means that the last parameter expects the colour you desire in hexadecimal form, $RRGGBBAA. The hexadecimal digit 00 corresponds to decimal digit 0, and hexadecimal digit FF corresponds to decimal digit 255. All of these function are accompanied by a function with the suffix …RGBA instead of …COLOR. Here, all parameters are the same except from the colour parameter, instead of ONE colour code in hexadecimal form, you enter four parameters r, g, b, a (red, green, blue, alpha/transparency). For example instead of $FF0000FF you put 255, 0, 0, 255. All functions return 0 as INTEGER value on success.

In many cases there are further accompanied functions with the prefix aa. This means the very same function with the same parameter list but the result is antialiased. For many functions furthermore the prefix filled is possible as shown for the circle in the example code. Also here the parameter list is completely the same but the resulting primitive is filled with the given colour.

SDL_BLITSURFACE(modified_image,NIL,screen,NIL); SDL_FLIP(screen); SDL_FRAMERATEDELAY(framerate); UNTIL keypressed;

Primitive Definition Description
Of all functions two types exist: …Color and …RGBA. They are in fact equal and differ only in the way you put in the colour information. For …Color functions there is the color:Uint32 argument where you put in the colour code in hexadecimal form, e.g. $FF0000FF for red without transparency. For …RGBA functions there are four arguments r:Uint8; g:Uint8; b:Uint8; a:Uint8 where you enter 255; 0; 0; 255 for red without transparency.
Functions with the prefix aa are equal to the functions without this prefix but are printing antialiased primitives. Functions with the prefix filled are equal to the functions without this prefix but the enclosed area of the primitive is filled with the given colour. Antialiased primitives are never filled and vice versa.
All functions return 0 as INTEGER on success.
Pixel (Dot) function pixelColor( dst : PSDL_Surface; x : Sint16; y : Sint16; color : Uint32 ) : integer Draws one pixel at position (x/y) in the given colour.
function pixelRGBA( dst : PSDL_Surface; x : Sint16; y : Sint16; r : Uint8; g : Uint8; b : Uint8; a : Uint8 ) : integer
Line function hlineColor( dst : PSDL_Surface; x1: Sint16; x2 : Sint16; y : Sint16; color : Uint32 ) : integer Draws a horizontal line from x1 to x2 at height y in the given colour.
function hlineRGBA( dst : PSDL_Surface; x1: Sint16; x2 : Sint16; y : Sint16; r : Uint8; g : Uint8; b : Uint8; a : Uint8 ) : integer
function vlineColor( dst : PSDL_Surface; x : Sint16; y1 : Sint16; y2 : Sint16; color : Uint32 ) : integer Draws a vertical line at position x from y1 to y2 in the given colour.
function vlineRGBA( dst : PSDL_Surface; x : Sint16; y1 : Sint16; y2 : Sint16; r : Uint8; g : Uint8; b : Uint8; a : Uint8 ) : integer
function lineColor( dst : PSDL_Surface; x1 : Sint16; y1 : Sint16; x2 : Sint16; y2 : Sint16; color : Uint32 ) : integer Draws a free line from position (x1/y1) to (x2/y2) in the given colour.
function lineRGBA( dst : PSDL_Surface; x1 : Sint16; y1 : Sint16;
x2 : Sint16; y2 : Sint16; r : Uint8; g : Uint8; b : Uint8; a : Uint8 ) : integer
function aalineColor( dst : PSDL_Surface; x1 : Sint16; y1 : Sint16; x2 : Sint16; y2 : Sint16; color : Uint32 ) : integer
function aalineRGBA( dst : PSDL_Surface; x1 : Sint16; y1 : Sint16;
x2 : Sint16; y2 : Sint16; r : Uint8; g : Uint8; b : Uint8; a : Uint8 ) : integer
Rectangle (Box) function rectangleColor( dst : PSDL_Surface; x1 : Sint16; y1 : Sint16; x2 : Sint16; y2 : Sint16; color : Uint32 ) : integer Draws a rectangle from position (x1/y1) to (x2/y2) in the given colour.
function rectangleRGBA( dst : PSDL_Surface; x1 : Sint16; y1 : Sint16;
x2 : Sint16; y2 : Sint16; r : Uint8; g : Uint8; b : Uint8; a : Uint8 ) : integer
function boxColor( dst : PSDL_Surface; x1 : Sint16; y1 : Sint16; x2 : Sint16; y2 : Sint16; color : Uint32 ) : integer
function boxRGBA( dst : PSDL_Surface; x1 : Sint16; y1 : Sint16; x2 : Sint16;
y2 : Sint16; r : Uint8; g : Uint8; b : Uint8; a : Uint8 ) : integer
Circle function circleColor( dst : PSDL_Surface; x : Sint16; y : Sint16; r : Sint16; color : Uint32 ) : integer Draws a circle with the center at position (x/y) and the radius r in the given colour.
function circleRGBA( dst : PSDL_Surface; x : Sint16; y : Sint16; rad : Sint16; r : Uint8; g : Uint8; b : Uint8; a : Uint8 ) : integer
function aacircleColor( dst : PSDL_Surface; x : Sint16; y : Sint16; r : Sint16; color : Uint32 ) : integer
function aacircleRGBA( dst : PSDL_Surface; x : Sint16; y : Sint16;
rad : Sint16; r : Uint8; g : Uint8; b : Uint8; a : Uint8 ) : integer
function filledCircleColor( dst : PSDL_Surface; x : Sint16; y : Sint16; r : Sint16; color : Uint32 ) : integer
function filledCircleRGBA( dst : PSDL_Surface; x : Sint16; y : Sint16;
rad : Sint16; r : Uint8; g : Uint8; b : Uint8; a : Uint8 ) : integer
Pie function pieColor( dst : PSDL_Surface; x : Sint16; y : Sint16; rad : Sint16;
start : Sint16; finish : Sint16; color : Uint32 ) : integer
Draws a pie chart with the pie’s edge being at position (x/y) with the radius rad. “start” and “finish” define the arc length of the pie in degree. If “start” is 0 then the pie starts at the right (east) side of a circle. To start at the top, “start” should be 270 or -90. If “start” is 0 and “finish” is 90, you get one quarter of a circle.
function pieRGBA( dst : PSDL_Surface; x : Sint16; y : Sint16; rad : Sint16;
start : Sint16; finish : Sint16; r : Uint8; g : Uint8; b : Uint8; a : Uint8 ) : integer
function filledPieColor( dst : PSDL_Surface; x : Sint16; y : Sint16; rad : Sint16;
start : Sint16; finish : Sint16; color : Uint32 ) : integer
function filledPieRGBA( dst : PSDL_Surface; x : Sint16; y : Sint16; rad : Sint16;
start : Sint16; finish : Sint16; r : Uint8; g : Uint8; b : Uint8; a : Uint8 ) : integer
Ellipse function ellipseColor( dst : PSDL_Surface; x : Sint16; y : Sint16; rx : Sint16; ry : Sint16; color : Uint32 ) : integer Draws an ellipse with its center at position (x/y) and the two radii rx and ry for its horizontal and vertical axes in the given colour.
function ellipseRGBA( dst : PSDL_Surface; x : Sint16; y : Sint16;
rx : Sint16; ry : Sint16; r : Uint8; g : Uint8; b : Uint8; a : Uint8 ) : integer
function aaellipseColor( dst : PSDL_Surface; xc : Sint16; yc : Sint16; rx : Sint16; ry : Sint16; color : Uint32 ) : integer
function aaellipseRGBA( dst : PSDL_Surface; x : Sint16; y : Sint16;
rx : Sint16; ry : Sint16; r : Uint8; g : Uint8; b : Uint8; a : Uint8 ) : integer
function filledEllipseColor( dst : PSDL_Surface; x : Sint16; y : Sint16; rx : Sint16; ry : Sint16; color : Uint32 ) : integer
function filledEllipseRGBA( dst : PSDL_Surface; x : Sint16; y : Sint16;
rx : Sint16; ry : Sint16; r : Uint8; g : Uint8; b : Uint8; a : Uint8 ) : integer
Polygon function trigonColor( dst : PSDL_Surface; x1 : Sint16; y1 : Sint16; x2 : Sint16; y2 : Sint16; x3 : Sint16; y3 : Sint16; color : Uint32 ) : integer Draws a trigon with its edges at (x1/y1), (x2/y2) and (x3/y3) in the given colour.
function trigonRGBA( dst : PSDL_Surface; x1 : Sint16; y1 : Sint16; x2 : Sint16; y2 : Sint16; x3 : Sint16; y3 : Sint16;
r : Uint8; g : Uint8; b : Uint8; a : Uint8 ) : integer
function aatrigonColor( dst : PSDL_Surface; x1 : Sint16; y1 : Sint16; x2 : Sint16; y2 : Sint16; x3 : Sint16; y3 : Sint16; color : Uint32 ) : integer
function aatrigonRGBA( dst : PSDL_Surface; x1 : Sint16; y1 : Sint16; x2 : Sint16; y2 : Sint16; x3 : Sint16; y3 : Sint16;
r : Uint8; g : Uint8; b : Uint8; a : Uint8 ) : integer
function filledTrigonColor( dst : PSDL_Surface; x1 : Sint16; y1 : Sint16; x2 : Sint16; y2 : Sint16; x3 : Sint16; y3 : Sint16; color : Uint32 ) : integer
function filledTrigonRGBA( dst : PSDL_Surface; x1 : Sint16; y1 : Sint16; x2 : Sint16; y2 : Sint16; x3 : Sint16; y3 : Sint16;
r : Uint8; g : Uint8; b : Uint8; a : Uint8 ) : integer
function polygonColor( dst : PSDL_Surface; const vx : PSint16; const vy : PSint16; n : integer; color : Uint32 ) : integer Draws a polygon with x values from array of SINT16 in vx. y values are from array of SINT16 in vy. n is the number of edges/points the polygon has.
function polygonRGBA( dst : PSDL_Surface; const vx : PSint16; const vy : PSint16;
n : integer; r : Uint8; g : Uint8; b : Uint8; a : Uint8 ) : integer
function aapolygonColor( dst : PSDL_Surface; const vx : PSint16; const vy : PSint16; n : integer; color : Uint32 ) : integer
function aapolygonRGBA( dst : PSDL_Surface; const vx : PSint16; const vy : PSint16;
n : integer; r : Uint8; g : Uint8; b : Uint8; a : Uint8 ) : integer
function filledPolygonColor( dst : PSDL_Surface; const vx : PSint16; const vy : PSint16; n : integer; color : Uint32 ) : integer
function filledPolygonRGBA( dst : PSDL_Surface; const vx : PSint16;
const vy : PSint16; n : integer; r : Uint8; g : Uint8; b : Uint8; a : Uint8 ) : integer
Bézier curve function bezierColor( dst : PSDL_Surface; const vx : PSint16; const vy : PSint16; n : integer; s : integer; color : Uint32 ) : integer Draws a Bézier curve of any order. n is the number of points, well n+1 is the order of the curve then. The x and y values are from arrays of SINT16. The higher value s the smoother the curve gets. s should be 2 at least.
function bezierRGBA( dst : PSDL_Surface; const vx : PSint16; const vy : PSint16;
n : integer; s : integer; r : Uint8; g : Uint8; b : Uint8; a : Uint8 ) : integer

 

Nothing really new here. The “modified_image” surface with the rotated, zoomed image and the primitives is blitted to the screen surface. The result is flipped to the screen. Then the extensivly discussed framerate manager decides by procedure SDL_FRAMERATEDELAY(manager:PFPSMANAGER) how long actually to wait until the loop is repeated. This procedure replaces the common SDL_DELAY command. The loop is stopped when the user presses any key.

Finally all the used surfaces are free’d and the framerate manager is disposed. SDL is quit and the program finished.

This file contains the source code: chap4a.pas (right click and “save as”)
This file is the executable: chap4a.exe (right click and “save as”)

The final result should look and behave like this: The image fpsdl.bmp is rotated and zoomed continouisly and some primitives (circle, filled circle, ellipse, pie, hexagon, Bézier curve) are drawn onto the image. If you use the pre-compiled exe file make sure to have the image copied to c:\.

Result of JEDI-SDL Chapter 4a

[Downloads transferred from old website]

SDL_gfx.dll; The pre-compiled SDL_gfx.dll (Version 2.0.19) for chapter 4a.

SDL_gfx-2.0.19.tar.gz; For license reasons here you can download the source code to compile the SDL_gfx.dll for chapter 4a. However, the most recent version for compilation you will find on the authour’s page.