Images and Surface Blitting

In this lesson, we’ll see how we can load images into SDL, and then display them in our window.

By default, SDL only supports images in the bitmap (.bmp) format. Soon, we’ll install an extension that allows us to work with many more image types. But for now, we’ll stick with bitmaps.

Let's acquire a bitmap image. A good place to get bitmap images is Google Image Search, using the filetype:bmp prefix. For example: filetype:bmp birds.

It's generally permitted to use any images you find for personal projects. However, if you plan on releasing work using images made by other people, ensure you have appropriate permission.

In this lesson, I’ll be using this image, which I've saved as birds.bmp:

We should store our bitmap in the same folder as the executables we are creating, and use a filename that we will remember.

1std::cout << SDL_GetBasePath();

This code uses a Window class and main.cpp event loop using the techniques in previous lessons:

1#pragma once
2#include <SDL.h>
3
4class Window {
5public:
6  Window() {
7    SDL_Init(SDL_INIT_VIDEO);
8
9    SDLWindow = SDL_CreateWindow(
10      "Hello Window",
11      SDL_WINDOWPOS_UNDEFINED,
12      SDL_WINDOWPOS_UNDEFINED,
13      800, 300, 0
14    );
15
16    SDLWindowSurface = SDL_GetWindowSurface(SDLWindow);
17    Update();
18  }
19
20  void Update() {
21    SDL_FillRect(
22      SDLWindowSurface,
23      nullptr,
24      SDL_MapRGB(SDLWindowSurface->format, 40, 40, 40)
25    );
26  }
27
28  void RenderFrame() {
29    SDL_UpdateWindowSurface(SDLWindow);
30  }
31
32  SDL_Surface* GetSurface() {
33    return SDLWindowSurface;
34  }
35
36  ~Window() {
37    SDL_DestroyWindow(SDLWindow);
38  }
39
40private:
41  SDL_Window* SDLWindow { nullptr };
42  SDL_Surface* SDLWindowSurface { nullptr };
43};

1#include <SDL.h>
2#include "Window.h"
3
4int main() {
5  Window GameWindow;
6
7  SDL_Event Event;
8  while(true) {
9    while(SDL_PollEvent(&Event)) {
10      if (Event.type == SDL_QUIT) {
11        SDL_Quit();
12        return 0;
13      }
14    }
15    GameWindow.RenderFrame();
16  }
17}

Let's create a class to work with images. Our constructor will require the filename of the image we want to load:

1#pragma once
2#include <string>
3
4class Image {
5public:
6  Image(std::string Filename) {
7    
8  }
9}

To load bitmaps into SDL, we use the SDL_LoadBMP function, passing the path to our file as a c-style string. For example:

1SDL_LoadBMP("my-image.bmp");

This function loads our image into an SDL_Surface and returns a pointer to that surface.

Let's update our constructor to make use of it:

1#pragma once
2#include <STL.h>
3#include <string>
4
5class Image {
6public:
7  Image(std::string FileName) {
8    Surface = SDL_LoadBMP(FileName.c_str());
9  }
10private:
11  SDL_Surface* Surface;
12}

When the surface is no longer needed, we should tell SDL. This allows SDL to release the memory that it allocated for that surface. We can do that using SDL_FreeSurface, passing a pointer to the surface.

Let's call it in the destructor:

1#pragma once
2#include <STL.h>
3#include <string>
4
5class Image {
6public:
7  Image(std::string FileName) {
8    Surface = SDL_LoadBMP(FileName.c_str());
9  }
10
11  ~Image() {
12    SDL_FreeSurface(Surface);
13  }
14
15private:
16  SDL_Surface* Surface;
17}

Surface Blitting

We now have two surfaces - the surface associated with our window, and the surface created when we loaded our image.

We want to update the pixels values in our screen surface with pixel values from our image surface. Blitting is a computer graphics term that is used for this process.

The main way of blitting surfaces in SDL is through the SDL_BlitSurface function. This function takes 4 arguments:

• The surface we want to copy from (an SDL_Surface*)
• The area of that surface we want to copy (an SDL_Rect*)
• The surface we want to copy to (an SDL_Surface*)
• The area of that surface we want to copy to (an SDL_Rect*)

Both of the SDL_Rect* arguments can be null pointers.

If the first is a null pointer, that tells SDL we want to copy the entire source surface.

If the second rectangle is a null pointer, that means it will be placed at the top left of the destination surface, and continue blitting pixels until there's either no more pixels on the source, or no more room on the destination.

Let's test it out by updating our constructor. We’ll send it a pointer to the Window surface, and then call SDL_BlitSurface:

1public:
2  Image(
3    std::string FileName,
4    SDL_Surface* WindowSurface
5  ) {
6    Surface = SDL_LoadBMP(FileName.c_str());
7    SDL_BlitSurface(
8      Surface, nullptr, WindowSurface, nullptr
9    );
10  }

Over in main.cpp, let's connect everything together and verify it worked:

1#include <SDL.h>
2#include "Window.h"
3#include "Image.h"
4
5int main() {
6  Window GameWindow;
7  Image Birds { "birds.bmp", GameWindow.GetSurface()};
8
9  SDL_Event Event;
10  while(true) {
11    while(SDL_PollEvent(&Event)) {
12      if (Event.type == SDL_QUIT) {
13        SDL_Quit();
14        return 0;
15      }
16    }
17    GameWindow.RenderFrame();
18  }
19}

Image Cropping and Positioning

We can use the two SDL_Rect pointers passed to SDL_BlitSurface to crop and position our image.

The first rectangle lets us define a subset of the image we want to copy from.

The second rectangle lets us define the top left coordinates, and a maximum width and height we want to insert the image into.

1Image(
2  std::string Filename,
3  SDL_Surface* WindowSurface
4) {
5  Surface = SDL_LoadBMP(Filename.c_str());
6  SDL_Rect BirdCrop { 360, 80, 200, 200 };
7  SDL_Rect BirdPosition {
8    300, 50, BirdCrop.w, BirdCrop.h
9  };
10  SDL_BlitSurface(
11    Surface, &BirdCrop, WindowSurface, &BirdPosition
12  );
13}

Image Scaling

SDL_BlitSurface does not change the size of the image when doing the transfer. The SDL_Rectangle arguments give us the option to crop, but the underlying image will be the same size on the destination surface as it was on the source.

To rescale images when blitting them onto another surface, we have SDL_BlitScaled

The argument list is exactly the same as SDL_BlitSurface. The main difference is that if the destination rectangle has a different dimension to the source rectangle, the source will be scaled up or down to fill the area.

1Image(
2  std::string Filename,
3  SDL_Surface* WindowSurface
4) {
5  Surface = SDL_LoadBMP(Filename.c_str());
6  SDL_Rect BirdCrop { 360, 80, 200, 200 };
7  SDL_Rect BirdPosition {
8    200, 0, BirdCrop.w * 2, BirdCrop.h * 2
9  };
10  SDL_BlitScaled(
11    Surface, &BirdCrop, WindowSurface, &BirdPosition
12  );
13}

Given our destination rectangle is larger than our source, our image is now scaled up in the output:

SDL_BlitScaled will also squash or stretch the image, if the source and destinations have different aspect ratios.

To control the blitting behaviour, it is useful to know what the original dimensions of our image were.

That is available from the surface created for it, through the w and h variables:

1Image(
2  std::string Filename,
3  SDL_Surface* WindowSurface
4) {
5  Surface = SDL_LoadBMP(Filename.c_str());
6  SDL_Rect BirdPosition {
7    200, 25, Surface->w / 2, Surface->h / 2
8  };
9  SDL_BlitScaled(
10    Surface, nullptr, WindowSurface, &BirdPosition
11  );
12}

Now, our original image was uniformly scaled down to half its original size:

Optimize Surface Blitting Performance

Surfaces can have different ways to store each pixel. For example, the window surface might use more memory per pixel than the surface generated when we loaded in our image.

How a surface stores its data is called the pixel format of the surface. It is available as the format member variable of SDL_Surface objects.

1std::cout << SDL_LoadBMP("birds.bmp")->format
2                << std::endl
3                << WindowSurface->format;

10x60000071fec0
20x60000071c340

When we blit a surface onto one with a different format, every pixel needs to be converted. That can require significant work and, in real applications, we’ll typically be blitting things together very frequently.

Therefore, it’s generally better for performance to do the conversion only once, rather than on every blit.

We do that using the SDL_ConvertSurface function, passing in a pointer to our surface, and the format we want to convert to. For legacy reasons, we also need to pass the number 0 as the third argument to this function.

To convert the surface containing our image to match the format of the window surface we are blitting it onto, our function call would look like this:

1SDL_ConvertSurface(Surface, WindowSurface->format, 0)

This function returns a pointer to a new surface, which we can use from that point on for blitting.

We can also get rid of our initial surface, using FreeSurface:

1Image(
2  std::string Filename,
3  SDL_Surface* WindowSurface
4) {
5  // Create a temporary surface from our image
6  SDL_Surface* Temp {
7    SDL_LoadBMP(Filename.c_str())
8  };
9
10  // Create a new surface with the same format
11  // as the window surface
12  Surface = SDL_ConvertSurface(
13    Temp, WindowSurface->format, 0
14  );
15
16  // Release the temporary surface
17  SDL_FreeSurface(Temp);
18
19  // Blit our optimized surface onto the window surface
20  SDL_BlitSurface(
21    Surface, nullptr, WindowSurface, nullptr
22  );
23}

Complete Code

The final code is available here:

1#include <SDL.h>
2#include "Window.h"
3#include "Image.h"
4
5int main() {
6  Window GameWindow;
7  Image Birds { "birds.bmp", GameWindow.GetSurface()};
8
9  SDL_Event Event;
10  while(true) {
11    while(SDL_PollEvent(&Event)) {
12      if (Event.type == SDL_QUIT) {
13        SDL_Quit();
14        return 0;
15      }
16    }
17    GameWindow.RenderFrame();
18  }
19}

1#pragma once
2#include <SDL.h>
3
4class Window {
5public:
6  Window() {
7    SDL_Init(SDL_INIT_VIDEO);
8
9    SDLWindow = SDL_CreateWindow(
10      "Hello Window",
11      SDL_WINDOWPOS_UNDEFINED,
12      SDL_WINDOWPOS_UNDEFINED,
13      800, 300, 0
14    );
15
16    SDLWindowSurface = SDL_GetWindowSurface(SDLWindow);
17    Update();
18  }
19
20  void Update() {
21    SDL_FillRect(
22      SDLWindowSurface,
23      nullptr,
24      SDL_MapRGB(SDLWindowSurface->format, 40, 40, 40)
25    );
26  }
27
28  void RenderFrame() {
29    SDL_UpdateWindowSurface(SDLWindow);
30  }
31
32  SDL_Surface* GetSurface() {
33    return SDLWindowSurface;
34  }
35
36  ~Window() {
37    SDL_DestroyWindow(SDLWindow);
38  }
39
40private:
41  SDL_Window* SDLWindow { nullptr };
42  SDL_Surface* SDLWindowSurface { nullptr };
43};

1#pragma once
2#include <SDL.h>
3#include <string>
4
5class Image {
6public:
7  Image(
8    std::string Filename,
9    SDL_Surface* WindowSurface
10  ) {
11    SDL_Surface* Temp {
12      SDL_LoadBMP(Filename.c_str())
13    };
14    Surface = SDL_ConvertSurface(
15      Temp, WindowSurface->format, 0
16    );
17    SDL_FreeSurface(Temp);
18    SDL_BlitSurface(
19      Surface, nullptr, WindowSurface, nullptr
20    );
21  }
22
23  ~Image() {
24    SDL_FreeSurface(Surface);
25  }
26
27private:
28  SDL_Surface* Surface;
29};

Next Lesson

Introduction to SDL_Image

Introduction to SDL_Image - add support for different image types. Convert .png and .jpeg files into SDL surfaces, and vice versa

ContinueView Course