Introduction to SDL_Image

In this lesson, we’ll introduce SDL_Image, a popular, official SDL extension that allows us to use many different image types - png files, jpg files, and many more.

Additionally, we’ll see how we can convert our surfaces to images, and save them on our hard drive.

Note, this lesson assumes you already have SDL_Image installed. The installation guide at the start of this chapter walked through the setup of everything we’ll need:

Setting up SDL2 in macOS (Xcode or CMake)

This step-by-step guide shows you how to set up SDL2 in an Xcode or CMake project on macOS

This lesson also follows immediately from our previous lesson on Images and Surface Blitting. We’ll be expanding the ideas and code we created there:

Images and Surface Blitting

Learn how to load images into our SDL2 application. Then, learn how to crop, resize, position and render them into our window.

Including SDL Image

The first part of accessing SDL_Image is including its header file in any location we want to use it:

1#include <SDL_image.h>

IMG_Load

The ability to load images of different formats is typically the main reason we want to use SDL Image. The function we need for that is IMG_Load.

We pass in a C-style string representing the path to our image (relative to our executable):

1IMG_Load("birds.png");

As with SDL_LoadBMP, this loads our image onto an SDL_Surface, and returns a pointer to that surface.

1SDL_Surface* MySurface { IMG_Load("birds.png") };

IMG_Load supports .bmp files so, as long as we’re using the library, there’s limited need to use SDL_LoadBMP anymore. We could update our Image class from the previous lesson to use SDL_Image instead, allowing it to support many different types of images:

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

Creating Screenshots with IMG_SavePNG

SDL_Image gives us the ability to save the contents of any of our surfaces to an image file.

We just need to provide a pointer to the surface we want to capture, and the file path we want to save the image as:

1IMG_SavePNG(GameWindow.GetSurface(), "screenshot.png");

The file will be stored in the same location as our executable. If it already exists, it will be overwritten.

Here, we save a screenshot of our Window surface before quitting:

1while(SDL_PollEvent(&Event)) {
2  if (Event.type == SDL_QUIT) {
3    IMG_SavePNG(GameWindow.GetSurface(), "screenshot.png");
4    SDL_Quit();
5    IMG_Quit();
6    return 0;
7  }
8}

Creating Screenshots with IMG_SaveJPG

We can also save our images using the JPG format, if preferred.

The first two function arguments are the same. However, IMG_SaveJPG accepts a third argument - an integer for the quality of the saved image. This can range from 0 to 100. A higher number yields a higher quality image, but larger file size.

1IMG_SaveJPG(GameWindow.GetSurface(), "screenshot.jpg", 70);

IMG_Init

The IMG_Init function lets us control the initialization of SDL_Image. It’s not strictly necessary to call this - SDL_Image will automatically initialize components as needed. For example, the first time we call IMG_Load with a .png file, the codec for PNGs will be intiialised at that point.

However, in a serious project, we’d likely want to take control of this. We don't want to risk it happening at a time where we really need the resources working on something else.

So, we can call SDL_Init at a suitable time, passing in the codecs we will be using. SDL has provided helper aliases for these codecs. They all which start with IMG_INIT, for example, IMG_INIT_PNG:

1IMG_Init(IMG_INIT_PNG);

Multiple codecs can be combined using the bitwise OR operator:

1IMG_Init(IMG_INIT_PNG | IMG_INIT_JPG);

Bitwise Operators and Bit Flags

Unravel the fundamentals of bitwise operators and bit flags in this practical lesson

IMG_Quit

When we no longer need SDL_Image, we should call SDL_Quit so it can clean up some resources:

1while(true) {
2  while(SDL_PollEvent(&Event)) {
3    if (Event.type == SDL_QUIT) {
4      SDL_Quit();
5      IMG_Quit();
6      return 0;
7    }
8  }
9  GameWindow.RenderFrame();
10}

The official documentation for SDL_Image is available here: https://wiki.libsdl.org/SDL_image/CategoryAPI