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
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{"example.png"};
41
42  while (!shouldQuit) {
43    while (SDL_PollEvent(&Event)) {
44      if (Event.type == SDL_QUIT) {
45        shouldQuit = true;
46      }
47    }
48    GameWindow.Render();
49    ExampleImg.Render(GameWindow.GetSurface());
50    GameWindow.Update();
51  }
52
53  SDL_Quit();
54  return 0;
55}

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
28private:
29  SDL_Surface* ImageSurface{nullptr};
30  SDL_Rect DestinationRectangle{0, 0, 0, 0};
31};

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 {/*...*/};
36
37int main(int argc, char** argv) {
38  SDL_Init(SDL_INIT_VIDEO);
39  IMG_Init(IMG_INIT_PNG);
40  SDL_Event Event;
41  bool shouldQuit{false};
42
43  Window GameWindow;
44  Image ExampleImg{"example.png"};
45
Application Loop|Show
46  while (!shouldQuit) {/*...*/}
57
58  // Cleanup
59  IMG_Quit();
60  SDL_Quit();
61  return 0;
62}

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

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.

Next Lesson

Rendering Text with SDL_ttf

Learn to render and manipulate text in SDL2 applications using the official SDL_ttf extension

ContinueView Course