Building a Versatile Image Class

In this lesson, we’ll combine the techniques we’ve covered so far in this chapter into a cohesive Image class. We’ll focus on creating a friendly API so external code can easily control how images are rendered onto their surfaces We’ll cover:

• Creating a flexible API for image handling
• Implementing file loading and error checking
• Setting up source and destination rectangles
• Adding different scaling modes for rendering
• Optimizing performance for game loops

As a starting point, we’ll be building upon a basic Window and application loop, built using topics we covered earlier in the course:

1#include <SDL_image.h>
2#include "Window.h"
3#include "Image.h"
4
5int main(int argc, char** argv) {
6  SDL_Init(SDL_INIT_VIDEO);
7  IMG_Init(IMG_INIT_PNG);
8
9  Window GameWindow;
10  Image ExampleImage{"example.png"};
11
12  SDL_Event Event;
13  bool shouldQuit{false};
14
15  while (!shouldQuit) {
16    while (SDL_PollEvent(&Event)) {
17      if (Event.type == SDL_QUIT) {
18        shouldQuit = true;
19      }
20    }
21    GameWindow.Render();
22    ExampleImage.Render(GameWindow.GetSurface());
23    GameWindow.Update();
24  }
25
26  SDL_Quit();
27  return 0;
28}

1#pragma once
2#include <SDL.h>
3
4class Window {
5public:
6  Window() {
7    SDLWindow =
8      SDL_CreateWindow("My Program",
9        SDL_WINDOWPOS_UNDEFINED,
10        SDL_WINDOWPOS_UNDEFINED,
11        600, 300, 0);
12  }
13
14  void Render() {
15    SDL_FillRect(GetSurface(), nullptr,
16      SDL_MapRGB(
17        GetSurface()->format, 50, 50, 50));
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};

The starting point for our Image class is this:

1#pragma once
2#include <SDL.h>
3#include <string>
4
5class Image {
6public:
7  Image(const std::string& File);
8  void Render(SDL_Surface* Surface);
9};

1#include "Image.h"
2
3Image::Image(const std::string& File) {}
4
5void Image::Render(SDL_Surface* Surface) {}

This program relies on an image called example.png being in the same location as our executable. The examples and screenshots from this lesson are using a .png file that is available by clicking here.

Our program currently renders the following window:

Principles

Let’s cover some goals we should have in mind for our API design

Friendly API

Our class should be as simple as possible to use. We should give consumers control of the key aspects they’ll want to change, whilst we take care of as much of the complexity as we can.

Performance

When working in real-time applications, we should always be mindful of performance, and this can influence our API design. For example, one possible design would be to expand the parameter list and body of our Render() function:

1// Image.h
2// ...
3class Image {
4public:
5  // ...
6  void Render(
7    SDL_Surface* Surface,
8    SDL_Rect SrcRect,
9    SDL_Rect DestRect,
10    SDL_PixelFormat Format
11  ) {
12    SomeCalculation(SrcRect, DestRect);
13    AdditionalExpensiveStuff(Format);
14    SDL_BlitSurface(
15      ImageSurface, nullptr,
16      Surface, nullptr);
17  }
18  // ...
19};

However, Render() is intended to be called every frame. We should be particularly mindful of the performance of functions that are called in areas like our application loop, or our event loop - colloquially referred to as hot loops.

Instead, the preference is typically to perform as much work as possible in other functions, so the code running in hot loops can be as efficient as possible.

Feedback

We should consider the expected inputs of our API. As a statically typed language, C++ takes care of part of this - for example, if a function parameter is SDL_Rect, the compiler will ensure an argument is an SDL_Rect, or implicitly convertable to one.

However, we also typically have requirements beyond the basic type. For example, we’d expect a rectangle used to selecting part of an image to overlap with that image. We’d also expect such a rectangle to have a positive area (that is, its w and h should both be greater than 0)

We need to establish what those expectations are, and how to deal with inputs that don’t meet those requirements. There are no correct decisions here - some options may include:

• Logging out an error and then rendering the image with some fallback configuration
• Logging out an error and then refusing to render the image
• Terminating the program

We’ll use the first option here, but other techniques are valid.

Breaking Changes and Extensibility

Code evolves over time - as we encounter new requirements, we’ll want to expand our class to accommodate them.

Preparing for this involves predicting the types of additions that may come in the future, and designing the class in such a way that those capabilities can be added without disruption to code that is using the existing API.

Changes to an API that forces changes in code that uses the API is referred to as a breaking change. Deleting a function is an obvious example of a breaking change - any code that was calling that function will no longer work.

Reacting to a breaking change in smaller programs is rarely a problem. This is especially true when it’s a program worked on by a single developer as that developer knows how their module is supposed to work, and therefore validate that it still works after updating it to a new API.

However, in larger programs, and particularly if we’re making libraries (such as SDL), we should design our API with the assumption that making breaking changes later could be expensive.

File Loading

Let’s start by enabling our class to create surfaces from image files. We’ll add a private LoadFile() method, as well as mImageSurface and mFile members to store the surface and file name.

We’ll also need to free surfaces when our objects are destroyed, so we’ll add a destructor.

To simplify memory management, we’ll delete our copy constructor and copy assignment operator for now. We’ll introduce techniques for copying objects that manage SDL_Surface objects later in the course

Our updated head file looks like this:

1// Image.h
2#pragma once
3#include <SDL.h>
4#include <string>
5
6class Image {
7public:
8  Image(const std::string& File);
9  void Render(SDL_Surface* Surface) const;
10  ~Image();
11  Image(const Image&) = delete;
12  Image& operator=(const Image&) = delete;
13
14private:
15  SDL_Surface* mImageSurface{ nullptr };
16  std::string  mFile;
17  void LoadFile(const std::string& File);
18};

In our implementation file, we’ll define the destructor and LoadFile() method.

We want our LoadFile() method to be callable multiple times within the lifecycle of the same object. We’ll support that by ensuring the file is different and freeing the existing surface to prevent memory leaks.

We’ll also call LoadFile() from the constructor:

1// Image.cpp
2#include "Image.h"
3
4Image::Image(const std::string& File) {
5  LoadFile(File);
6}
7
8Image::~Image() {
9  SDL_FreeSurface(mImageSurface);
10}
11
12void Image::LoadFile(const std::string& File) {
13  if (File == mFile) { return; }
14  SDL_FreeSurface(mImageSurface);
15  mFile = File;
16  mImageSurface = IMG_Load(File.c_str());
17}

Source Rectangle

Let’s allow users to define the source rectangle used in blitting. It will be important for the inner working of our Image objects that this source rectangle be valid, so we’ll split this across two member variables:

• mRequestedSrcRectangle is the rectangle the user provided, which may not be valid
• mAppliedSrcRectangle is the rectangle we’ll use for our blitting and calculations

Remembering the rectangle the user requested gives us more flexibility in our API. For example, the user might provide a rectangle that is invalid for the current image but later updates the image to one where that rectangle is valid.

To test the validity of a provided rectangle, we’ll use two private methods - ValidateRectangle() and RectangleWithinSurface():.

Checking whether a rectangle is within a surface isn’t just related to images., Therefore, in a larger application, this function would likely be defined elsewhere, but we’ll just add it to our Image class for now:

1// Image.h
2#pragma once
3#include <SDL_image.h>
4#include <string>
5#include <iostream>
6
7class Image {
8public:
9  void SetSourceRectangle(const SDL_Rect& Rect);
10  // ...
11
12private:
13  SDL_Rect mAppliedSrcRectangle;
14  SDL_Rect mRequestedSrcRectangle;
15
16  bool ValidateRectangle(
17    const SDL_Rect& Rect,
18    const SDL_Surface* Surface,
19    const std::string& Context) const;
20
21  bool RectangleWithinSurface(
22    const SDL_Rect& Rect,
23    const SDL_Surface* Surface) const;
24    
25  // ...
26};

Our setter’s main job is to update mAppliedSrcRectangle. If the rectangle the user requested is valid, we’ll use that. Otherwise, we’ll fall back to setting our rectangle to simply cover the entire area of the image surface:

1// Image.cpp
2// ...
3void Image::SetSourceRectangle(
4  const SDL_Rect& Rect) {
5  mRequestedSrcRectangle = Rect;
6  if (ValidateRectangle(
7    Rect, mImageSurface, "Source Rectangle")) {
8    mAppliedSrcRectangle = Rect;
9  } else {
10    mAppliedSrcRectangle = {
11      0, 0, mImageSurface->w, mImageSurface->h
12    };
13  }
14}

Our ValidateRectangle() function performs two checks. It ensures the requested rectangle has at least some area - that is, its w and h are both greater than 0.

SDL provides a helper for this in the form of SDL_RectEmpty().

Secondly, we want to ensure the entire bounds of the rectangle are within the bounds of the Surface if provided. We’ll create a RectangleWithinSurface() function for that.

If both conditions are met, ValidateRectangle returns true to SetSourceRectangle, causing our Image class to use that rectangle.

1// Image.cpp
2// ...
3bool Image::ValidateRectangle(
4  const SDL_Rect&    Rect,
5  const SDL_Surface* Surface,
6  const std::string& Context) const {
7  if (SDL_RectEmpty(&Rect)) {
8    std::cout << "[ERROR] " << Context <<
9      ": Rectangle has no area\n";
10    return false;
11  }
12  if (Surface && 
13      !RectangleWithinSurface(Rect, Surface)
14  ) {
15    std::cout << "[ERROR] " << Context <<
16      ": Rectangle not within target surface\n";
17    return false;
18  }
19  return true;
20}

Checking that the rectangle is within a surface could look like this:

1// Image.cpp
2// ...
3bool Image::RectangleWithinSurface(
4  const SDL_Rect&    Rect,
5  const SDL_Surface* Surface) const {
6  if (Rect.x < 0)
7    // Rect extends past left edge
8    return false;
9  if (Rect.x + Rect.w > Surface->w)
10    // Rect extends past right edge
11    return false;
12  if (Rect.y < 0)
13    // Rect extends past top edge
14    return false;
15  if (Rect.y + Rect.h > Surface->h)
16    // Rect extends past bottom edge
17    return false;
18  return true;
19}

Finally, let’s update our constructor to allow users to provide an initial source rectangle. For now, we’ll require consumers to provide this rectangle, but we’ll improve our API by making it optional later:

1// Image.h
2// ...
3class Image {
4public:
5  Image(
6    const std::string& File,
7    const SDL_Rect& SourceRect);
8  // ...
9};

1// Image.cpp
2// ...
3Image::Image(
4  const std::string& File,
5  const SDL_Rect& SourceRect
6) {
7  LoadFile(File);
8  SetSourceRectangle(SourceRect);
9}

Destination Rectangle

Setting a destination rectangle follows much the same process as setting a source rectangle. We’ll add a setter and two member variables:

1// Image.h
2// ...
3class Image {
4public:
5  void SetDestinationRectangle(const SDL_Rect& Rect);
6  // ...
7
8private:
9  SDL_Rect mAppliedDestRectangle;
10  SDL_Rect mRequestedDestRectangle;
11  // ...
12};

Our setter looks like below. In this case, we have no surface to compare the destination rectangle to, so we’ll skip that check by passing a nullptr to that parameter of ValidateRectangle():

If the destination rectangle is invalid (by having no area, in this case) we’ll fall back to setting it at the top left of the destination surface, with the same width and height as the source rectangle:

1// Image.cpp
2// ...
3void Image::SetDestinationRectangle(
4  const SDL_Rect& Rect) {
5  mRequestedDestRectangle = Rect;
6  if (ValidateRectangle(Rect, nullptr,
7        "Destination Rectangle")) {
8    mAppliedDestRectangle = Rect;
9  } else {
10    mAppliedDestRectangle = {
11      0, 0,
12      mAppliedSrcRectangle.w,
13      mAppliedSrcRectangle.h
14    };
15  }
16}

Let’s update our constructor to accept an initial destination rectangle. Again, we’ll make this required for now, but optional later:

1// Image.h
2// ...
3class Image {
4public:
5  Image(
6    const std::string& File,
7    const SDL_Rect& SourceRect,
8    const SDL_Rect& DestRect);
9  // ...
10};

1// Image.cpp
2// ...
3Image::Image(
4  const std::string& File,
5  const SDL_Rect& SourceRect,
6  const SDL_Rect& DestRect
7) {
8  LoadFile(File);
9  SetSourceRectangle(SourceRect);
10  SetDestinationRectangle(DestRect);
11}

Rendering and Scaling Mode

Let’s get our rendering working. We’ll let users choose between the three scaling modes, which we’ll present in an enum:

1// Image.h
2// ...
3
4enum class ScalingMode{None, Fill, Contain};
5
6// ...

These scaling modes represent the three techniques we covered earlier in the chapter:

• ScalingMode::None blits the source rectangle into the destination rectangle with no scaling - that is, using SDL_BlitSurface()
• ScalingMode::Fill blits the source rectangle into the destination rectangle, scaling and stretching to ensure the destination rectangle is filled using SDL_BlitScaled()
• ScalingMode::Contain uses SDL_BlitScaled() to fill as much of the destination rectangle as possible whilst respecting the aspect ratio of the source rectangle

Let’s add the option to the constructor, and add a member variable to keep track of it:

1// Image.h
2// ...
3
4class Image {
5public:
6  Image(
7    const std::string& File,
8    const SDL_Rect& SourceRect,
9    const SDL_Rect& DestRect,
10    ScalingMode ScalingMode
11  );
12  // ...
13
14private:
15  ScalingMode mScalingMode{ ScalingMode::None };
16  // ...
17};

1// Image.cpp
2// ...
3Image::Image(const std::string& File,
4  const SDL_Rect& SourceRectangle,
5  const SDL_Rect& DestinationRectangle,
6  ScalingMode ScalingMode
7): mRequestedSrcRectangle{SourceRectangle},
8   mRequestedDestRectangle{DestinationRectangle},
9   mScalingMode(ScalingMode)
10 {
11   LoadFile(File);
12 }

Let’s update our Render() function to make use of this. If our scaling mode is set to ScalingMode::None we use SDL_BlitSurface(), otherwise we use SDL_BlitScaled():

1// Image.cpp
2// ...
3void Image::Render(SDL_Surface* Surface) {
4  if (mScalingMode == ScalingMode::None) {
5    SDL_BlitSurface(mImageSurface,
6      &mAppliedSrcRectangle, Surface,
7      &mAppliedDestRectangle);
8  } else {
9    SDL_BlitScaled(mImageSurface,
10      &mAppliedSrcRectangle, Surface,
11      &mAppliedDestRectangle);
12  }
13}

With these changes, ScalingMode::None and ScalingMode::Fill should work as intended:

1// main.cpp
2// ...
3int main(int argc, char** argv) {
4  // ...
5  SDL_Rect Src{ 0, 0, 200, 200 };
6  SDL_Rect Dest{
7    0, 0,
8    GameWindow.GetSurface()->w,
9    GameWindow.GetSurface()->h
10  };
11  Image ExampleImage{
12    "example.png",
13    Src, Dest,
14    ScalingMode::None)
15  };
16  // ...
17}

1// main.cpp
2// ...
3int main(int argc, char** argv) {
4  // ...
5  Image ExampleImage{
6    "example.png",
7    Src, Dest,
8    ScalingMode::Fill)
9  };
10  // ...
11}

Implementing ScalingMode::Contain

In our SetDestinationRectangle() function, we’ll add additional logic when setting mAppliedDestRectangle. If the scaling mode is set to ScalingMode::Contain, we’ll pass the user’s requested rectangle to MatchAspectRatio() instead of using it directly.

MatchAspectRatio() will return a new SDL_Rect, derived from scaling down the user’s requested rectangle (if necessary) to match the aspect ratio of the source rectangle:

1// Image.cpp
2// ...
3void Image::SetDestinationRectangle(
4  const SDL_Rect& Rect) {
5  mRequestedDestRectangle = Rect;
6  if (ValidateRectangle(Rect, nullptr,
7    "Destination Rectangle")) {
8    mAppliedDestRectangle =
9      mScalingMode == ScalingMode::Contain
10        ? MatchAspectRatio(
11          Rect, mAppliedSrcRectangle
12        ) : Rect;
13  } else {
14    mAppliedDestRectangle = {
15      0, 0,
16      mAppliedSrcRectangle.w,
17      mAppliedSrcRectangle.h
18    };
19  }
20}

The MatchAspectRatio() function uses the same logic we walked through in our earlier lesson on aspect ratios:

1// Image.cpp
2// ...
3SDL_Rect Image::MatchAspectRatio(
4  const SDL_Rect& Source,
5  const SDL_Rect& Target) const {
6  float TargetRatio{ Target.w
7    / static_cast<float>(Target.h) };
8  float SourceRatio{ Source.w
9    / static_cast<float>(Source.h) };
10
11  SDL_Rect ReturnValue = Source;
12
13  if (SourceRatio < TargetRatio) {
14    ReturnValue.h = static_cast<int>(
15      Source.w / TargetRatio);
16  } else {
17    ReturnValue.w = static_cast<int>(
18      Source.h * TargetRatio);
19  }
20
21  return ReturnValue;
22}

There are two key points to note here:

• If the rectangle the user requested is invalid, Image::SetDestinationRectangle() will fall back to using a destination rectangle with the same width and height as the source rectangle. By definition, this means the rectangles will have the same aspect ratio, so this naturally satisfies our ScalingMode::Contain scenario.
• If the user’s requested rectangle was fully within the destination surface, the rectangle returned by MatchAspectRatio() will also be within the surface. This is because MatchAspectRatio() only ever returns a rectangle of the same size or smaller.

With these changes, our ScalingMode::Contain rendering should now be working:

1// main.cpp
2// ...
3int main(int argc, char** argv) {
4  // ...
5  Image ExampleImage{
6    "example.png",
7    Src, Dest,
8    ScalingMode::Contain)
9  };
10  // ...
11}

Complete Files

The completed files from this lesson are available here:

1#pragma once
2#include <SDL_image.h>
3#include <string>
4#include <iostream>
5
6enum class ScalingMode { None, Fill, Contain };
7
8class Image {
9public:
10  Image(
11    const std::string& File,
12    const SDL_Rect& SourceRect,
13    const SDL_Rect& DestRect,
14    ScalingMode ScalingMode = ScalingMode::None
15  );
16
17  void Render(SDL_Surface* Surface);
18  void SetSourceRectangle(const SDL_Rect& Rect);
19  void SetDestinationRectangle(
20    const SDL_Rect& Rect);
21  ~Image();
22  Image(const Image&) = delete;
23  Image& operator=(const Image&) = delete;
24
25private:
26  SDL_Surface* mImageSurface{ nullptr };
27  std::string mFile;
28  SDL_Rect mAppliedSrcRectangle;
29  SDL_Rect mRequestedSrcRectangle;
30  SDL_Rect mAppliedDestRectangle;
31  SDL_Rect mRequestedDestRectangle;
32  ScalingMode mScalingMode{ ScalingMode::None };
33
34  void LoadFile(const std::string& File);
35
36  SDL_Rect MatchAspectRatio(
37    const SDL_Rect& Source,
38    const SDL_Rect& Target) const;
39
40  bool ValidateRectangle(
41    const SDL_Rect&    Rect,
42    const SDL_Surface* Surface,
43    const std::string& Context) const;
44
45  bool RectangleWithinSurface(
46    const SDL_Rect&    Rect,
47    const SDL_Surface* Surface) const;
48};

1#include "Image.h"
2
3Image::Image(const std::string& File,
4  const SDL_Rect& SourceRectangle,
5  const SDL_Rect& DestinationRectangle,
6  ScalingMode ScalingMode)
7  : mScalingMode(ScalingMode) {
8  LoadFile(File);
9  SetSourceRectangle(SourceRectangle);
10  SetDestinationRectangle(DestinationRectangle);
11}
12
13void Image::Render(SDL_Surface* Surface) {
14  if (mScalingMode == ScalingMode::None) {
15    SDL_BlitSurface(mImageSurface,
16      &mAppliedSrcRectangle, Surface,
17      &mAppliedDestRectangle);
18  } else {
19    SDL_BlitScaled(mImageSurface,
20      &mAppliedSrcRectangle, Surface,
21      &mAppliedDestRectangle);
22  }
23}
24
25void Image::SetSourceRectangle(
26  const SDL_Rect& Rect) {
27  mRequestedSrcRectangle = Rect;
28  if (ValidateRectangle(
29    Rect, mImageSurface, "Source Rectangle")) {
30    mAppliedSrcRectangle = Rect;
31  } else {
32    mAppliedSrcRectangle = {
33      0, 0, mImageSurface->w, mImageSurface->h };
34  }
35}
36
37void Image::SetDestinationRectangle(
38  const SDL_Rect& Rect) {
39  mRequestedDestRectangle = Rect;
40  if (ValidateRectangle(Rect, nullptr,
41    "Destination Rectangle")) {
42    mAppliedDestRectangle =
43      mScalingMode == ScalingMode::Contain
44      ? MatchAspectRatio(Rect,
45        mAppliedSrcRectangle)
46      : Rect;
47  } else {
48    mAppliedDestRectangle = {
49      0, 0,
50      mAppliedSrcRectangle.w,
51      mAppliedSrcRectangle.h
52    };
53  }
54}
55
56Image::~Image() {
57  SDL_FreeSurface(mImageSurface);
58}
59
60void Image::LoadFile(const std::string& File) {
61  if (File == mFile) { return; }
62
63  SDL_FreeSurface(mImageSurface);
64  mFile = File;
65  mImageSurface = IMG_Load(File.c_str());
66}
67
68bool Image::ValidateRectangle(
69  const SDL_Rect&    Rect,
70  const SDL_Surface* Surface,
71  const std::string& Context) const {
72  if (SDL_RectEmpty(&Rect)) {
73    std::cout << "[ERROR] " << Context <<
74      ": Rectangle has no area\n";
75    return false;
76  }
77  if (Surface && !
78    RectangleWithinSurface(Rect, Surface)) {
79    std::cout << "[ERROR] " << Context <<
80      ": Rectangle not within target surface\n";
81    return false;
82  }
83  return true;
84}
85
86bool Image::RectangleWithinSurface(
87  const SDL_Rect&    Rect,
88  const SDL_Surface* Surface) const {
89  if (Rect.x < 0)
90    return false;
91  if (Rect.x + Rect.w > Surface->w)
92    return false;
93  if (Rect.y < 0)
94    return false;
95  if (Rect.y + Rect.h > Surface->h)
96    return false;
97  return true;
98}
99
100SDL_Rect Image::MatchAspectRatio(
101  const SDL_Rect& Source,
102  const SDL_Rect& Target) const {
103  float TargetRatio{ Target.w
104    / static_cast<float>(Target.h) };
105  float SourceRatio{ Source.w
106    / static_cast<float>(Source.h) };
107
108  SDL_Rect ReturnValue = Source;
109
110  if (SourceRatio < TargetRatio) {
111    ReturnValue.h = static_cast<int>(
112      Source.w / TargetRatio);
113  } else {
114    ReturnValue.w = static_cast<int>(
115      Source.h * TargetRatio);
116  }
117
118  return ReturnValue;
119}

Summary

In this lesson, we've built a comprehensive Image class for SDL-based development. We've covered file loading, rectangle manipulation, and different scaling modes.

Our class now provides a user-friendly API for rendering images with various options.

In the next lesson, we’ll cover suggestions on how this component could be expanded further. We’ll suggest improvements for how the API can be made more flexible and also cover techniques we may want to consider for error handling.

Next Lesson

Expanding the Image API

Key techniques for implementing class designs in more complex scenarios

ContinueView Course