Introduction to SDL_Image

In this lesson, we’ll start using the SDL_Image extension we installed earlier. We’ll cover 3 main topics:

• Initializing and closing SDL_Image
• Using the IMG_Load() function to load and render a wide variety of image types, rather than being restricted to the basic bitmap (.bmp) format.
• Using surface blending modes to use transparency and other techniques when blitting
• Creating image files from our surfaces using IMG_SaveJPG() and IMG_SavePNG()

We’ll be building upon the basic application loop and surface-blitting concepts we covered earlier in the course:

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  
30  Window(const Window&) = delete;
31  Window& operator=(const Window&) = delete;
32
33private:
34  SDL_Window* SDLWindow;
35};
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.png"};
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 <SDL.h>
3
4#include <iostream>
5#include <string>
6
7class Image {
8public:
9  Image(std::string File) : ImageSurface{
10    SDL_LoadBMP(File.c_str())} {
11    if (!ImageSurface) {
12      std::cout << "Failed to load image: " <<
13        File << ":\n" << SDL_GetError();
14    }
15    SourceRectangle.w = ImageSurface->w;
16    SourceRectangle.h = ImageSurface->h;
17  }
18
19  void Render(SDL_Surface* DestinationSurface) {
20    SDL_BlitSurface(ImageSurface,
21                    nullptr,
22                    DestinationSurface,
23                    &DestinationRectangle);
24  }
25
26  ~Image() { SDL_FreeSurface(ImageSurface); }
27  Image(const Image&) = delete;
28  Image& operator=(const Image&) = delete;
29
30private:
31  SDL_Surface* ImageSurface{nullptr};
32  SDL_Rect DestinationRectangle{0, 0, 0, 0};
33};

One notable change from the previous lesson is that our main function is now passing a .png image path to our Image constructor:

1Image ExampleImg{"example.png"};

This image should be located in the same directory that our executable file is created in. The examples and screenshots from this lesson are using a .png file that is available by clicking here.

However, our Image class does not currently support .png images. It’s using SDL_LoadBMP() to load image files and, as the name suggests, this function only supports .bmp images.

1// Image.h
2class Image {
3public:
4  Image(std::string File)
5  : ImageSurface{SDL_LoadBMP(File.c_str())} {
6    if (!ImageSurface) {
7      std::cout << "Failed to load image: " <<
8        File << ":\n" << SDL_GetError();
9    }
10    // ...
11  }
12  // ...
13};

As such, our program can’t render the image, and we have an error being reported in the terminal:

1Failed to load image: example.png:
2File is not a Windows BMP file

Initializing and Quitting SDL_Image

The SDL_Image extension allows us to load many more image formats. It includes the code that can understand formats like PNG and JPG, and load their pixels into an SDL_Surface that we can work with as before.

To use SDL_Image, we should first initialize it. This is done using the IMG_Init() function, available after including SDL_Image.h. We pass it initialization flags indicating what formats we need to support:

1// main.cpp
2#include <SDL.h>
3#include <SDL_image.h>
4
5int main(int argc, char** argv) {
6  SDL_Init(SDL_INIT_VIDEO);
7  IMG_Init(IMG_INIT_PNG);
8  // ...
9}

A list of the available IMG_Init flags is available here. We can initialize multiple libraries at once using the | operator:

1IMG_Init(IMG_INIT_PNG | IMG_INIT_JPG);

We should also call IMG_Quit() before our application ends, allowing the extension to clean up at the appropriate time. Let’s add both of these to our main() function:

1// main.cpp
2#include <SDL.h>
3#include <SDL_image.h>
4
5#include "Image.h"
6
Window Class|Show
7class Window {/*...*/};
38
39int main(int argc, char** argv) {
40  SDL_Init(SDL_INIT_VIDEO);
41  IMG_Init(IMG_INIT_PNG);
42  SDL_Event Event;
43  bool shouldQuit{false};
44
45  Window GameWindow;
46  Image ExampleImg{"example.png"};
47
Application Loop|Show
48  while (!shouldQuit) {/*...*/}
59
60  // Cleanup
61  IMG_Quit();
62  SDL_Quit();
63  return 0;
64}

Using IMG_Load()

Once we’ve initialized SDL_Image, we can replace SDL_LoadBMP() in our Image class with IMG_Load(). This function is a drop-in replacement - it has the same API.

It accepts the file we want to load as a c-string, and returns a pointer to the SDL_Surface where the image data was loaded:

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

Our program should now render our image:

We can treat the resulting surface in the same way we did before, such as blitting it onto other surfaces.

For example, let’s update our Render() function to use BlitScaled() instead, and update our DestinationRectangle to set the size and position of our image:

1// Image.h
2class Image {
3public:
4  // ...
5
6  void Render(SDL_Surface* DestinationSurface) {
7    SDL_BlitScaled(ImageSurface,
8                   nullptr,
9                   DestinationSurface,
10                   &DestinationRectangle);
11  }
12
13private:
14  SDL_Rect DestinationRectangle{200, 50, 200, 200};
15};

Transparency and Blend Modes

Our PNG image has transparent sections, and we see our program is respecting that by default. In areas where our PNG was transparent, the blitting operation skipped those pixels, keeping the existing color on the destination surface.

In this example, the Window::Render() method fills the window surface with a solid gray color. The Image::Render() method then blends our image on top of it.

This blending strategy to use when blitting is configured on the source surface, which is the ImageSurface created by IMG_Load() in our example.

The surface created by IMG_Load() has blending enabled by default if the image it loads includes transparency. However, we can also enable it explicitly using the SDL_SetSurfaceBlendMode() function.

We pass a pointer to the surface we’re configuring, and the blend mode we want to use. SDL_BLENDMODE_BLEND is the mode that uses transparency:

1// Image.h
2class Image {
3public:
4  Image(std::string File) : ImageSurface{
5    IMG_Load(File.c_str())} {
6    if (!ImageSurface) {
7      std::cout << "Failed to load image: " <<
8        File << ":\n" << SDL_GetError();
9    }
10    SDL_SetSurfaceBlendMode(
11      ImageSurface, SDL_BLENDMODE_BLEND
12    );
13  }
14  // ...
15};

We can disable blending and return to the basic blitting algorithm using SDL_BLENDMODE_NONE:

1// Image.h
2class Image {
3public:
4  Image(std::string File) : ImageSurface{
5    IMG_Load(File.c_str())} {
6    if (!ImageSurface) {
7      std::cout << "Failed to load image: " <<
8        File << ":\n" << SDL_GetError();
9    }
10    SDL_SetSurfaceBlendMode(
11      ImageSurface, SDL_BLENDMODE_NONE
12    );
13  }
14  // ...
15};

Transparency and Pixel Formats

For blending to work, our surface must also use a pixel format that includes transparency data. IMG_Load() uses an appropriate pixel format by default.

However, if we change it - using SDL_ConvertSurface() for example - we may lose the transparency data, and therefore lose the ability to blend our surface onto others.

We can check if a pixel format includes transparency (also called alpha) by passing it to the SDL_ISPIXELFORMAT_ALPHA() macro:

1// main.cpp
2
3// ...
4
5int main(int argc, char** argv) {
6  SDL_Init(SDL_INIT_VIDEO);
7  Window GameWindow;
8  SDL_Surface* Surface{
9    IMG_Load("example.png")};
10
11  if (SDL_ISPIXELFORMAT_ALPHA(
12    Surface->format->format)) {
13    std::cout << "Surface has alpha";
14  }
15
16  Surface = SDL_ConvertSurface(
17    Surface,
18    GameWindow.GetSurface()->format, 0
19  );
20
21  if (!SDL_ISPIXELFORMAT_ALPHA(
22    Surface->format->format)) {
23    std::cout << "...but not any more";
24  }
25
26  SDL_Quit();
27  return 0;
28}

1Surface has alpha...but not any more

Taking Screenshots

SDL_Image includes two functions that let us save a surface to an image file on our hard drive. To save a PNG file, we use IMG_SavePNG(), passing a pointer to the surface, and the location we want the file saved to.

The location where the file will be created is relative to the location of our executable:

1// Image.h
2class Image {
3public:
4  // ...
5  void SaveToFile(std::string Location) {
6    IMG_SavePNG(ImageSurface, Location.c_str());
7  }
8  // ...
9};

IMG_SaveJPG() works similarly but has an additional integer parameter. This integer ranges from 0 to 100 and affects the quality of the saved file. Higher values prioritize quality, while lower values prioritize compression, thereby reducing file size.

We can use either of these functions to take screenshots of our program. We simply pass our window surface as the first argument:

1// main.cpp
2class Window {
3public:
4  // ...
5  void TakeScreenshot() {
6    IMG_SaveJPG(
7      GetSurface(), "Screenshot.jpg", 90
8    );
9  }
10  // ...
11}
12
13// ...

Memory Management

Currently, our Image class does not allow its instances to be copied in a memory-safe way, so we’ve deleted the copy constructor and copy assignment operator:

1// Image.h
2// ...
3
4class Image {
5public:
6  // ...
7  Image(const Image&) = delete;
8  Image& operator=(const Image&) = delete;
9  // ...
10};

Let’s finally address this. The root cause is that IMG_Load() (and SDL_LoadBMP() previously) is one of the cases where SDL allocates dynamic memory, and requires us to tell it when that memory is safe to deallocate. We’ve been doing this through the SDL_FreeSurface() function in the Image destructor:

1// Image.h
2// ...
3
4class Image {
5public:
6  // ...
7  ~Image() {
8    SDL_FreeSurface(ImageSurface);
9  }
10  // ...
11};

Allowing Image objects to be copied using the default copy constructor and operator would be problematic when we have this destructor. If we copy one of our Image objects, the ImageSurface variable in both the original object and the copy will point to the same underlying SDL_Surface.

When one of our Image copies is destroyed, its destructor will delete that surface using the SDL_FreeSurface() function. This leaves the other copy with a dangling pointer, which will cause a use-after-free memory issue the next time the Image tries to use it. Also, when that Image later gets destroyed, it’s destructor will call SDL_FreeSurface() again with that same address. This introduces a second memory problem called a double-free error.

To allow our Image objects to be copied without creating these memory issues, we need to intervene in the copying process. Specifically, we need to ensure that, when an Image is copied, each copy gets its own copy of the underlying SDL_Surface data, in a distinct memory address.

SDL_ConvertSurface()

To create a copy of a surface, including all of its pixel data, we can use the SDL_ConvertSurface() function. It requires three arguments:

1. A pointer to the surface to copy
2. The format to use for the copy. If we want to use the same format as the source, we can retrieve it from the format member variable
3. The integer value 0, which is required for legacy backward compatibility reasons

Below, we create an SDL_Surface called Copy, based on data from an SDL_Surface called Source:

1SDL_Surface* Copy{SDL_ConvertSurface(
2  Source.ImageSurface,
3  Source.ImageSurface->format,
4  0
5)};

Implementing Copy Semantics

Let’s implement a copy constructor for our Image class that duplicates the SDL_Surface from the source object using SDL_ConvertSurface(). Our Image objects have a DestinationRectangle member variable, so we copy that in our constructor too:

1// Image.cpp
2// ...
3
4Image::Image(const Image& Source)
5  : DestinationRectangle(Source.DestinationRectangle)
6{
7  // Copy the SDL_Surface using SDL_ConvertSurface
8  if (Source.ImageSurface) {
9    ImageSurface = SDL_ConvertSurface(
10      Source.ImageSurface,
11      Source.ImageSurface->format,
12      0
13    );
14  }
15}

The copy assignment operator is similar but, in this scenario, we’re updating an existing Image instance. That instance might already have an SDL_Surface, so we need to free it:

1// Image.cpp
2// ...
3
4Image& Image::operator=(const Image& Source) {
5  // Early return for self-assignment
6  if (this == &Source) {
7    return *this;
8  }
9  
10  // Free current resources
11  SDL_FreeSurface(mImageSurface);
12  
13  // Copy the SDL_Surface using SDL_ConvertSurface
14  if (Source.mImageSurface) {
15    mImageSurface = SDL_ConvertSurface(
16      Source.mImageSurface,
17      Source.mImageSurface->format,
18      0
19    );
20  } else {
21    ImageSurface = nullptr;
22  }
23  
24  // Copy the other member variables too
25  DestinationRectangle = Source.DestinationRectangle;
26  
27  return *this;
28}

We covered copy operations and the rule of three in more detail in our introductory course:

Copy Constructors and Operators

Explore advanced techniques for managing object copying and resource allocation

Summary

In this lesson, we’ve introduced the SDL_Image extension, greatly expanding the range of image formats our application can support.

We also saw how some formats include transparency, allowing us to blend surfaces whilst blitting.

In the next lesson, we’ll combine the topics we’ve covered so far in this lesson into a cohesive Image class. We’ll focus on how to provide the capabilities we learned to external code using a friendly public interface.

We’ll also see how to manage the complexities involved within our class in a way that keeps everything organized and easy to maintain.

Free and Unlimited Access

Professional C++

Unlock the true power of C++ by mastering complex features, optimizing performance, and learning expert workflows used in professional development

View Course