Introduction to SDL3_image

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 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// ...
2class Image {
3public:
4  Image(const std::string& File)
5  : ImageSurface{IMG_Load(File.c_str())} {
6    if (!ImageSurface) {
7      std::cout << "Failed to load image: "
8        << File << ":\n  " << SDL_GetError() << '\n';
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// ...
2class Image {
3public:
4  Image(const std::string& File)
5  : ImageSurface{IMG_Load(File.c_str())} {
6    if (!ImageSurface) {
7      std::cout << "Failed to load image: "
8        << File << ":\n  " << SDL_GetError() << '\n';
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, the ability to blend our surface onto others.

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

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

1Surface has alpha...but not any more

SDL3_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 where we want the file saved.

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

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

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#pragma once
2#include <SDL3/SDL.h>
3#include <SDL3_image/SDL_image.h>
4
5class Window {
6public:
7  //...
8  void TakeScreenshot() const {
9    IMG_SaveJPG(
10      GetSurface(), "Screenshot.jpg", 90
11    );
12  }
13  //...
14};

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() 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_DestroySurface() function in the Image destructor:

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

Allowing Image objects to be copied using the default copy constructor and operator would be problematic. 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. 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 second Image is later destroyed, its destructor will call SDL_DestroySurface() again with that same address, causing a double-free error.

To allow our Image objects to be copied without creating these memory issues, we need to ensure that when an Image is copied, both the original and the new object gets their own copy of the underlying SDL_Surface data, each in a distinct memory address.

Using SDL_ConvertSurface()

To create a copy of a surface, including all of its pixel data, we can use the SDL_ConvertSurface() function again. As a reminder, it requires two 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.

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

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

Implementing Copy Semantics

To implement copy semantics, let's first update our header file to declare a copy constructor and a copy assignment operator, instead of deleting them. This will let us define them in a new Image.cpp file.

1// ...
2
3class Image {
4public:
5  Image(const std::string& File);
6  // ...
7  ~Image();
8  Image(const Image&);
9  Image& operator=(const Image&);
10  // ...
11};

Next, let's create Image.cpp and move our constructor and destructor logic there.

1#include "Image.h"
2
3Image::Image(const std::string& File)
4: ImageSurface{IMG_Load(File.c_str())} {
5  if (!ImageSurface) {
6    std::cout << "Failed to load image: "
7      << File << ":\n  " << SDL_GetError() << '\n';
8  }
9}
10
11Image::~Image() {
12  if (ImageSurface) {
13    SDL_DestroySurface(ImageSurface);
14  }
15}

1#pragma once
2#include <SDL3/SDL.h>
3#include <SDL3_image/SDL_image.h>
4#include <iostream>
5#include <string>
6
7class Image {
8public:
9  Image(const std::string& File);
10  : ImageSurface{IMG_Load(File.c_str())} {
11    if (!ImageSurface) {
12      std::cout << "Failed to load image: "
13        << File << ":\n  " << SDL_GetError() << '\n';
14    }
15  }
16
17  Image(const std::string& File); 
18
19  void Render(SDL_Surface* DestinationSurface);
20
21  ~Image();
22  // ...
23};

Now, in Image.cpp, we can implement the copy constructor to duplicate the SDL_Surface from the source object using SDL_ConvertSurface(). We also need to copy our other member variables.

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

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 first.

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

With these changes, we can now safely copy our Image instances as needed. Managing external resources like images is an important topic, so we'll revisit it several times throughout the course with increasingly advanced techniques.

If this section didn't entirely make sense, I'd recommend reviewing our introductory lesson on the topic, where we walk through this process in more detail.

Here is the complete code after all the changes in this lesson. We've added the SDL3_image header, switched to IMG_Load, and implemented proper memory management for our Image class.

In this lesson, we've introduced the SDL3_image extension, 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. Finally, we implemented safe copy semantics for our Image class, making it more flexible.

In the next lesson, we'll move on to SDL3_ttf, another extension library that allows us to load font files and render text.