Loading and Displaying Images

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

We’ll build upon the concepts we introduced in the previous chapters. Our main.cpp looks like below.

For this lesson, the key thing to note is that we have an Image object called Example, which is being asked to Render() onto the window surface every frame:

1// main.cpp
2#include <SDL.h>
3#include "Image.h" 
4
Window Class|Show
5class Window {/*...*/};
37
38int main(int argc, char** argv){
39  SDL_Init(SDL_INIT_VIDEO);
40
41  Window GameWindow;
42  Image Example;
43
44  SDL_Event Event;
45  bool shouldQuit{false};
46
47  while (!shouldQuit) {
48    while (SDL_PollEvent(&Event)) {
49      GameUI.HandleEvent(Event);
50      if (Event.type == SDL_QUIT) {
51        shouldQuit = true;
52      }
53    }
54    GameWindow.Render();
55    Example.Render(GameWindow.GetSurface());
56    GameWindow.Update();
57  }
58
59  SDL_Quit();
60  return 0;
61}

We’ll build out this Image class across the next two lessons. Our starting point is simply this:

1// Image.h
2#pragma once
3#include <SDL.h>
4
5class Image {
6public:
7  void Render(SDL_Surface* WindowSurface){
8    // ...
9  }
10};

Loading an Image

By default, SDL only supports the basic (.bmp) format. In the next lesson, we’ll introduce the SDL_image extension which understands many more image types, but we’ll stick with bitmaps for now to establish the basics.

To follow along, an example bitmap image is available here.

SDL_LoadBMP()

To load a bitmap image, we call the SDL_LoadBMP() function, passing the location of the file we want to load:

1SDL_LoadBMP("SomeFile.bmp");

This path is relative to the base path of our program. The base path is typically the directory containing our executable, such as MyProgram.exe.

In the previous example, we’re asking SDL to load a file called SomeFile.png, stored in the same location as our executable. If our image was in some subdirectory, /assets, for example, we would load it like this:

1SDL_LoadBMP("Assets/SomeFile.bmp");

Managing the Image Surface

The SDL_LoadBMP() function creates an SDL_Surface using the dimensions and colors of the file we loaded, and it returns a SDL_Surface* - that is, a pointer to the surface.

Let’s update our Image class to make use of this. We’ll add three things:

• An SDL_Surface* so we can remember what surface is associated with our Image object
• A constructor that creates this surface. We’ll accept the location of the image we want to load as a string
• A destructor that asks SDL to free the surface associated with an Image object when that object is destroyed

Our changes look like this:

1// Image.h
2#pragma once
3#include <string>
4#include <SDL.h>
5
6class Image {
7public:
8  Image(std::string File)
9    : ImageSurface{SDL_LoadBMP(File.c_str())} {}
10
11  void Render(SDL_Surface* DestinationSurface) {
12    // ...
13  }
14
15  ~Image() {
16    SDL_FreeSurface(ImageSurface);
17  }
18
19private:
20  SDL_Surface* ImageSurface{nullptr};
21};

Let’s update our main.cpp to pass the path of our example image to this new constructor:

1// main.cpp
2#include <SDL.h>
3#include "Image.h"
4
Window Class|Show
5class Window {/*...*/};
36
37int main(int argc, char** argv) {
38  SDL_Init(SDL_INIT_VIDEO);
39  SDL_Event Event;
40  bool shouldQuit{false};
41
42  Window GameWindow;
43  Image ExampleImg{"example.bmp"};
44
Application Loop|Show
45  while (!shouldQuit) {/*...*/}
56
57  SDL_Quit();
58  return 0;
59}

Handling Errors

The SDL_LoadBMP() function can fail, in which case it will return a nullptr and populate the SDL_CheckError() return value with an explanation. We won’t attempt to handle this scenario gracefully in this section, as it adds a lot of noise to our code examples and distracts from the key content.

If the image fails to load, our application will likely crash. However, to help us debug, we can at least log out a message explaining why. Let’s update our Image class accordingly:

1// Image.h
2#pragma once
3#include <iostream>
4#include <SDL.h>
5#include <string>
6
7class Image {
8public:
9  Image(std::string File)
10  : ImageSurface{SDL_LoadBMP(File.c_str())} {
11    if (!ImageSurface) {
12      std::cout << "Failed to load image "
13        << File << ":\n  "  << SDL_GetError();
14    }
15  }
16
17  // ...
18};

With our Image class updates complete, let’s temporarily change the argument provided from main.cpp to see our error handling in action:

1// main.cpp
2
3// ...
4
5int main(int argc, char** argv) {
6  // ...
7  Image ExampleImg{"fake.bmp"};
8  // ...
9}

1Failed to load image fake.bmp:
2  Parameter 'src' is invalid

Surface Blitting

SDL_Surface objects manage an area of memory where they store the color information of each of their pixels. We won’t interact with that data directly in this lesson, but we can see where it is by accessing the pixels member of an SDL_Surface:

1// main.cpp
2int main(int argc, char** argv) {
3  SDL_Init(SDL_INIT_VIDEO);
4  Window GameWindow;
5
6  std::cout << "GameWindow Surface is storing "
7    "its pixel data at:"
8    << GameWindow.GetSurface()->pixels;
9
10  return 0;
11}

1GameWindow Surface is storing its pixel data at:
2  000002307E090000

To render the image within our program, we need to copy this pixel data to the area of memory where it will end up on our screen. In this context, that means copying data from the ImageSurface to the window surface.

In our main.cpp, we are already passing the window surface to our Image object’s Render() method:

1// main.cpp
2#include <SDL.h>
3#include "Image.h"
4
Window Class|Show
5class Window {/*...*/};
34
35int main(int argc, char** argv) {
Initialization|Show
41
42  while (!shouldQuit) {
Event Loop|Show
43    while (SDL_PollEvent(&Event)) {/*...*/}
49    GameWindow.Render();
50    ExampleImg.Render(GameWindow.GetSurface());
51    GameWindow.Update();
52  }
53
54  SDL_Quit();
55  return 0;
56}

So, within that Render() function, we have access to both of the surfaces we need - the ImageSurface member variable, and the DestinationSurface parameter which, in this program, will always be the the window surface:

1// Image.h
2#pragma once
3#include <iostream>
4#include <SDL.h>
5#include <string>
6
7class Image {
8public:
9  // ...
10  
11  void Render(SDL_Surface* DestinationSurface) {
12    std::cout << "\nDestinationSurface Surface Pixels: "
13      << DestinationSurface->pixels;
14    std::cout << "\nImage Surface Pixels: "
15      << ImageSurface->pixels;
16  }
17  // ...
18
19private:
20  SDL_Surface* ImageSurface;
21};

1DestinationSurface Pixels: 00007FF45DB30020
2WindowSurface Pixels: 00000292E26E0000

If the data we’re copying from one memory location to another represents pixels, that copying operation is often referred to as blitting. SDL provides the SDL_BlitSurface() function to make it easier to copy pixel data from one surface to another.

The function accepts 4 arguments:

1. Source: The surface we’re copying from
2. Source Rectangle: Which area of the source we’re copying from
3. Destination: The surface we’re copying to
4. Destination Rectangle: Which area of the destination we’re copying to

Both of the rectangles are optional, and we’ll explore them in more detail in the next lesson. For now, we’ll pass nullptr to those parameters:

1// Image.h
2#pragma once
3#include <iostream>
4#include <SDL.h>
5#include <string>
6
7class Image {
8public:
9  Image(std::string File)
10    : ImageSurface{SDL_LoadBMP(File.c_str())} {
11    if (!ImageSurface) {
12      std::cout << "Failed to load image: "
13        << File << ":\n" << SDL_GetError();
14    }
15  }
16
17  void Render(SDL_Surface* DestinationSurface) {
18    SDL_BlitSurface(
19      ImageSurface, nullptr,
20      DestinationSurface, nullptr
21    );
22  }
23
24  ~Image() {
25    if (ImageSurface) {
26      SDL_FreeSurface(ImageSurface);
27    }
28  }
29
30private:
31  SDL_Surface* ImageSurface;
32};

Running our program, we should now see our program rendering the image:

Overview

It’s important to understand exactly what is going on here, as this architecture is foundational for a lot of more advanced concepts. Let’s review what is happening.

In our main.cpp, we’re creating a Window and an Image:

1// main.cpp
2int main(int argc, char** argv) {
3  SDL_Init(SDL_INIT_VIDEO);
4  SDL_Event Event;
5  bool shouldQuit{false};
6  Window GameWindow; 
7  Image ExampleImg; 
8
Application Loop|Show
9  while (!shouldQuit) {/*...*/}
20
21  // Cleanup
22  SDL_Quit();
23  return 0;
24}

The constructors for both of these classes result in an SDL_Surface being created. The GameWindow surface is created automatically as a side effect of the SDL_CreateWindow() function, whilst the ExampleImg surface is created by the call to SDL_LoadBMP().

Later, in our application loop, we’re performing three actions after all of our events are processed:

1// main.cpp
2int main(int argc, char** argv) {
Initialization|Show
8
9  // Application Loop
10  while (!shouldQuit) {
Event Loop|Show
11    while (SDL_PollEvent(&Event)) {/*...*/}
17    GameWindow.Render();
18    ExampleImg.Render(GameWindow.GetSurface()); 
19    GameWindow.Update();
20  }
21
22  // Cleanup
23  SDL_Quit();
24  return 0;
25}

• GameWindow.Render() fills our window surface with a solid gray color. This is done through SDL_FillRect().
• ExampleImg.Render() fills a portion of our window surface with data from our image surface. This overwrites most of the gray pixels with colors from our image. In this case, our image surface is slightly smaller than the window surface, so not all of the gray pixels are overwritten.
• We call GameWindow.Update(). This calls SDL_UpdateWindowSurface(), telling SDL we’ve completed rendering our frame, and it can be shown on the screen. This triggers the buffer swap we described in our earlier lesson on double buffering.

There are two additional things to note about these three actions.

Firstly, the order is important. If we call GameWindow.Render() after blitting our image onto the window surface, we’d never see the image. This is because the gray color from SDL_FillRect() would overwrite everything we blitted.

This is perhaps obvious in this case but, as our programs become more complex, we should be mindful of the order our blits happen. We can imagine later blits as "painting over" previous ones.

Secondly, as we’re calling these functions within the application loop, they’re being performed on every frame. It’s particularly important to understand GameWindow.Render() in this context.

On every iteration of our application loop, the window surface still has the content of the previous frame. By kicking off the render process with GameWindow.Render(), we’re effectively clearing out that content by replacing it all with a solid color. This gives us a fresh canvas, ensuring artifacts from the previous frame don’t stick around.

Optimizing Blit Performance

Behind the scenes, surfaces can represent their pixel data in different ways in memory. This makes blitting slower, as we can no longer just copy the pixel data from the source to the destination. We additionally need to transform the data to match the format used by the destination.

SDL functions like SDL_BlitSurface() perform this transformation for us, so we don’t need to implement it. However, we still incur the performance cost every time it happens.

We cover pixel formats in much more detail later but, for now, we can note that the format an SDL_Surface uses is available from the format member variable:

1// Image.h
2#pragma once
3#include <iostream>
4#include <SDL.h>
5#include <string>
6
7class Image {
8public:
9
10  // ...
11
12  void Render(SDL_Surface* DestinationSurface) {
13    if (DestinationSurface->format == 
14        ImageSurface->format
15    ) {
16      std::cout << "Matched Format Blit\n";
17    } else {
18      std::cout << "Reformat Required\n";
19    }
20    SDL_BlitSurface(
21      ImageSurface, nullptr,
22      DestinationSurface, nullptr
23    );
24  }
25  
26  // ...
27};

1Reformat Required
2Reformat Required
3Reformat Required
4...

If one of our surfaces is frequently used to blit onto surfaces that use a different format, we should consider doing that transformation only once, rather than on every blit. We can do that using the SDL_ConvertSurface() function. It accepts a pointer to the surface we want to convert, and a pointer to the SDL_PixelFormat we want to convert it to.

There is an additional, unused third parameter that exists for backward compatibility. We can simply pass 0 there:

1SDL_ConvertSurface(Surface, Format, 0)

This function returns a pointer to a new surface with the pixel data in the correct format, or a nullptr if the conversion failed.

Let’s add this format as an optional parameter to our Image constructor. If provided, our ImageSurface will use that format:

1// Image.h
2#pragma once
3#include <iostream>
4#include <SDL.h>
5#include <string>
6
7class Image {
8public:
9  Image(
10    std::string File,
11    SDL_PixelFormat* PreferredFormat = nullptr
12  ) : ImageSurface{SDL_LoadBMP(File.c_str())} {
13    if (!ImageSurface) {
14      std::cout << "Failed to load image: "
15        << File << ":\n" << SDL_GetError();
16    }
17    if (PreferredFormat) {
18      SDL_Surface* Converted{
19        SDL_ConvertSurface(
20          ImageSurface, PreferredFormat, 0
21        )
22      };
23      if (Converted) {
24        SDL_FreeSurface(ImageSurface);
25        ImageSurface = Converted;
26      } else {
27        std::cout << "Error converting surface: "
28          << SDL_GetError();
29      }
30    }
31  }
32  
33  // ...
34};

Performance Profiling

Before we update our main.cpp to provide this PreferredFormat argument, let’s establish a baseline so we can ensure our changes are improving the performance.

Let’s profile how long our image is currently taking to render. We can do this using SDL_GetPerformanceCounter(), which returns a high-accuracy timer. By calling this function before and after the thing we’re profiling, we can get a platform-specific representation of how long it is taking:

1// main.cpp
2#include <SDL.h>
3#include "Image.h"
4
Window Class|Show
5class Window {/*...*/};
34
35int main(int argc, char** argv) {
Initialization|Show
42
43  while (!shouldQuit) {
Event Loop|Show
44    while (SDL_PollEvent(&Event) {/*...*/}
50    GameWindow.Render();
51    
52    Uint64 Start{SDL_GetPerformanceCounter()};
53    ExampleImg.Render(GameWindow.GetSurface());
54    Uint64 Delta{SDL_GetPerformanceCounter() - Start};
55    std::cout << "\nTime to Render Image: " << Delta;
56    
57    GameWindow.Update();
58  }
59
60  // Cleanup
61  SDL_Quit();
62  return 0;
63}

Running our program, we can now get some indication of how long the image is taking to render on each frame. On my system, it is taking approximately 4,900 units of time:

1Time to Render Image: 4874
2Time to Render Image: 4977
3Time to Render Image: 4922
4...

Note that the "units" here are not well defined. SDL_GetPerformanceCounter() is intended to compare the performance of different implementations, so this 4,900 result is only useful if we have something to compare it against.

Let’s update our main.cpp to provide the PreferredFormat argument, so we can confirm our updated Image constructor is making a positive difference:

1// main.cpp
2#include <SDL.h>
3#include "Image.h"
4
Window Class|Show
5class Window {/*...*/};
34
35int main(int argc, char** argv) {
36  SDL_Init(SDL_INIT_VIDEO);
37  SDL_Event Event;
38  bool shouldQuit{false};
39
40  Window GameWindow;
41  Image ExampleImg{
42    "example.bmp",
43    GameWindow.GetSurface()->format
44  };
45
Application Loop|Show
46  while (!shouldQuit) {/*...*/}
57
58  // Cleanup
59  SDL_Quit();
60  return 0;
61}

Now, our pixel format conversion happens only once - in the Image constructor. The Render() function that is called every frame has less work to do, and that is reflected in our profiling. On my machine, the image blitting is approximately 10 times faster:

1Time to Render Image: 498
2Time to Render Image: 479
3Time to Render Image: 585
4...

Complete Code

Complete versions of the files we created in this lesson are available below:

1#include <SDL.h>
2#include "Image.h"
3
4class Window {
5public:
6  Window() {
7    SDLWindow = SDL_CreateWindow(
8      "My Program", SDL_WINDOWPOS_UNDEFINED,
9      SDL_WINDOWPOS_UNDEFINED, 600, 300, 0);
10  }
11
12  void Render() {
13    SDL_FillRect(
14      GetSurface(), nullptr, SDL_MapRGB(
15        GetSurface()->format, 50, 50, 50
16      )
17    );
18  }
19
20  void Update() {
21    SDL_UpdateWindowSurface(SDLWindow);
22  }
23
24  SDL_Surface* GetSurface() {
25    return SDL_GetWindowSurface(SDLWindow);
26  }
27
28  ~Window() { SDL_DestroyWindow(SDLWindow); }
29
30private:
31  SDL_Window* SDLWindow;
32};
33
34int main(int argc, char** argv) {
35  SDL_Init(SDL_INIT_VIDEO);
36  SDL_Event Event;
37  bool shouldQuit{false};
38
39  Window GameWindow;
40  Image ExampleImg{
41    "example.bmp",
42    GameWindow.GetSurface()->format
43  };
44
45  while (!shouldQuit) {
46    while (SDL_PollEvent(&Event)) {
47      if (Event.type == SDL_QUIT) {
48        shouldQuit = true;
49      }
50    }
51    GameWindow.Render();
52    ExampleImg.Render(GameWindow.GetSurface());
53    GameWindow.Update();
54  }
55
56  SDL_Quit();
57  return 0;
58}

1#pragma once
2#include <iostream>
3#include <SDL.h>
4#include <string>
5
6class Image {
7public:
8  Image(
9    std::string File,
10    SDL_PixelFormat* PreferredFormat = nullptr
11  ) : ImageSurface{SDL_LoadBMP(File.c_str())} {
12    if (!ImageSurface) {
13      std::cout << "Failed to load image: "
14        << File << ":\n" << SDL_GetError();
15    }
16    if (PreferredFormat) {
17      SDL_Surface* Converted{
18        SDL_ConvertSurface(
19          ImageSurface, PreferredFormat, 0
20        )
21      };
22      if (Converted) {
23        SDL_FreeSurface(ImageSurface);
24        ImageSurface = Converted;
25      } else {
26        std::cout << "Error converting surface: "
27          << SDL_GetError();
28      }
29    }
30  }
31
32  void Render(SDL_Surface* DestinationSurface) {
33    SDL_BlitSurface(
34      ImageSurface, nullptr,
35      DestinationSurface, nullptr
36    );
37  }
38
39  ~Image() {
40    if (ImageSurface) {
41      SDL_FreeSurface(ImageSurface);
42    }
43  }
44
45private:
46  SDL_Surface* ImageSurface{nullptr};
47};

Summary

Throughout this lesson, we covered the key techniques for working with images in C++ and SDL2. We learned how to:

• Load bitmap images into SDL surfaces
• Render images on the screen using blitting
• Optimize performance through pixel format conversion
• Profile and measure rendering performance

These skills form a solid foundation that we’ll build on through the rest of this section.

In the next lesson, we’ll see how we can replace the nullptr arguments we’re currently passing to SDL_BlitSurface(). This will allow us to select which part of the image to copy, and which position to copy it to.

Next Lesson

Cropping and Positioning Images

Learn to precisely control image display using source and destination rectangles.

ContinueView Course