Chapter 5 – Drawing primitives

Displaying of images/sprites/textures as discussed in last chapter are sometimes accompanied by drawing operations. For some applications and games drawing operations are even essential.

When do you need drawing?

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

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

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

SDL2 drawing and images diagram

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

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

This is just one example where drawing is very helpful.

Drawing in SDL 2.0

Now lets jump right into the code:

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

Result screenshot for chapter 5

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

The program is called “Chapter5_SDL2”. Notice, in the uses clause we now just have SDL2 included, SDL2_image from last chapter is gone since all drawing operations presented are included in native SDL 2.0. We will need a counter variable “i” of native Pascal type integer later. We need a window and a renderer and call them “sdlWindow1” and “sdlRenderer” as known from the previous chapter. Next we declare a variable “sdlRect1” which is of type PSDL_Rect. You remember this one from last chapter? If we use this variable in the code later on, I will explain this type in detail. The same is true for “sdlPoints1” which is an array of 500 elements of type PSDL_Point. In short, PSDL_Rect describes rectangles and PSDL_Point describes points.

Nothing new here, we initilize SDL 2.0, create a window with 500 pixels width and 500 pixels height and associate the renderer with this window. But before proceeding something you should know.

Colours in computer graphics

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

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

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

Now let’s get back to the code.

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

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

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

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

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

Setting up a background in SDL 2.0

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

SDL_RenderClear(renderer: PSDL_Renderer): SInt32

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

Drawing lines and points in SDL 2.0

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

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

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

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

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

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

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

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

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

Rectangles and PSDL_Rect in SDL 2.0

What we do first here is to allocate some memory to “sdlRect1” which is of type PSDL_Rect. This is done by the Pascal command new, which is also used for other ordinary pointer types. Let’s have a look at the structure of the PSDL_Rect record:

This record describes a rectangle (obviously), hence the name. The variables x and y correspond to the x/y coordinates of the left upper corner of the rectangle, again related to the origin 0/0 which is the left upper corner of, e.g. a texture, window,… The variable w is the width and h the height of the rectangle. That’s it. The next step is to define the rectangle by assign some values for x, y, w and h. The drawing colour is set to green by SDL_SetRenderDrawColor() and the rectangle is drawn by SDL_RenderDrawRect().

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

It requires the renderer, which is “sdlRenderer” for us and a PSDL_Rect we just defined: “sdlRect1”. This function returns 0 on success and the negative error code on failure. Notice, we neither render the result to the screen now nor do we delay here. Anyway, we want a second rectangle! 🙂

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

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

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

The blend mode in SDL 2.0

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

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

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

dstRGBA = srcRGBA
SDL_BLENDMODE_BLEND alpha blending
dstRGB = (srcRGB * srcA) + (dstRGB * (1-srcA))
dstA = srcA + (dstA * (1-srcA))
SDL_BLENDMODE_ADD additive blending
dstRGB = (srcRGB * srcA) + dstRGB
dstA = dstA
SDL_BLENDMODE_MOD color modulate
dstRGB = srcRGB * dstRGB
dstA = dstA

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

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

Spread points randomly using PSDL_Point

randomize is a Free Pascal procedure to initilize the random number generator. Imagine this as shaking the dice.

Again we use the “i” counter variable for a for-loop. The loop allocates memory for the 500 points of type PSDL_Point in the “sdlPoints1” array by new. PSDL_Point is a record which is shown here:

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

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

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

This function returns 0 on success and the negative error code on failure. First you need to set the renderer, then just the first element of an array of PSDL_Point type and finally the number of points. Notice how we are not using a loop here to draw all 500 points by calling a certain function 500 times. Instead we just use an array of points and its first element. This way we save a lot of time at runtime, especially if you think of a real application where even more points have to be drawn. There are similar functions for lines, rectangles and filled rectangles. They are not used in the example but it may be interesting to know, so here they are:

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

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

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

As a hint, I had troubles using SDL_RenderDrawLines, I expected them to connect one point by another with lines to get kind of a polygon structure but instead the points just draw vertical lines to the bottom. Seems to me like a bug.

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

Congratulations, you just finished Chapter 5 :-). Let’s go for Chapter 6.

← Chapter 4 | Chapter 6 →

Leave a Reply