Expanding the Image API

In this lesson, we’ll discuss some ways we can improve upon the Image class created in the previous lesson. We’ll cover three topics:

• Techniques for dealing with errors and unexpected situations
• Adding flexibility to our class, and working around some common problems that can occur when implementing a versatile API
• Using comments to document how our API works

The examples we use here are based on the Image class we created previously:

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, mImageSurface->w, mImageSurface->h };
50  }
51}
52
53Image::~Image() {
54  SDL_FreeSurface(mImageSurface);
55}
56
57void Image::LoadFile(const std::string& File) {
58  if (File == mFile) { return; }
59
60  SDL_FreeSurface(mImageSurface);
61  mFile = File;
62  mImageSurface = IMG_Load(File.c_str());
63}
64
65bool Image::ValidateRectangle(
66  const SDL_Rect&    Rect,
67  const SDL_Surface* Surface,
68  const std::string& Context) const {
69  if (SDL_RectEmpty(&Rect)) {
70    std::cout << "[ERROR] " << Context <<
71      ": Rectangle has no area\n";
72    return false;
73  }
74  if (Surface && !
75    RectangleWithinSurface(Rect, Surface)) {
76    std::cout << "[ERROR] " << Context <<
77      ": Rectangle not within target surface\n";
78    return false;
79  }
80  return true;
81}
82
83bool Image::RectangleWithinSurface(
84  const SDL_Rect& Rect,
85  const SDL_Surface* Surface
86) const {
87  if (Rect.x < 0)
88    return false;
89  if (Rect.x + Rect.w > Surface->w)
90    return false;
91  if (Rect.y < 0)
92    return false;
93  if (Rect.y + Rect.h > Surface->h)
94    return false;
95  return true;
96}
97
98SDL_Rect Image::MatchAspectRatio(
99  const SDL_Rect& Source,
100  const SDL_Rect& Target) const {
101  float TargetRatio{ Target.w
102    / static_cast<float>(Target.h) };
103  float SourceRatio{ Source.w
104    / static_cast<float>(Source.h) };
105
106  SDL_Rect ReturnValue = Source;
107
108  if (SourceRatio < TargetRatio) {
109    ReturnValue.h = static_cast<int>(
110      Source.w / TargetRatio);
111  } else {
112    ReturnValue.w = static_cast<int>(
113      Source.h * TargetRatio);
114  }
115
116  return ReturnValue;
117}

Error Handling

So far, our class is handling and recovering from errors involving invalid source and destination rectangles. However, there are some situations from which we can't recover, and we should implement ways to communicate these states.

For example, the user may provide an invalid file path, causing our LoadFile() function to fail. The SDL_Surface pointer returned from SDL’s IMG_Load() function is a nullptr when this happens, and we can retrieve the associated error message by calling SDL_GetError().

Let’s add a ValidateSurface() function to test a surface and log errors:

1// Image.h
2// ...
3
4class Image {
5  // ...
6private:
7  // ...
8  void ValidateSurface(
9    const SDL_Surface* Surface,
10    const std::string& Context) const;
11};

1// Image.cpp
2// ...
3
4void Image::ValidateSurface(
5  const SDL_Surface* Surface,
6  const std::string& Context) const {
7  if (!Surface) {
8    std::cout << "[ERROR] " << Context << ": "
9      << SDL_GetError() << '\n';
10  }
11}

We’ll call it at the end of our LoadFile() function to report if the IMG_Load() failed:

1// Image.cpp
2// ...
3
4void Image::LoadFile(const std::string& File) {
5  if (File == mFile) { return; }
6  SDL_FreeSurface(mImageSurface);
7  mFile = File;
8  mImageSurface = IMG_Load(File.c_str());
9  ValidateSurface(mImageSurface, "Loading File");
10}

Reacting to Errors Internally

This alerts users that an error has happened when they instantiate our class with an invalid path. However, our Image class can be updated to handle this scenario more gracefully.

For example, we can ensure an image load is successful before we get rid of our existing surface. Let’s update ValidateSurface() to return a bool - true if the surface is valid, and false otherwise:

1// Image.h
2// ...
3
4class Image {
5  // ...
6private:
7  // ...
8  bool ValidateSurface(
9    const SDL_Surface* Surface,
10    const std::string& Context) const;
11};

1// Image.cpp
2// ...
3
4bool Image::ValidateSurface(
5  const SDL_Surface* Surface,
6  const std::string& Context) const {
7  if (!Surface) {
8    std::cout << "[ERROR] " << Context << ": "
9      << SDL_GetError() << '\n';
10    return false;
11  }
12  return true;
13}

We can update our LoadFile() function to make use of this return value. We’ll attempt to create a new surface using IMG_Load() as before, but we’ll only update our existing surface if that operation is successful:

1// Image.cpp
2// ...
3
4void Image::LoadFile(const std::string& File) {
5  if (File == mFile) { return; }
6
7  SDL_Surface* NextSurface{ IMG_Load(
8    File.c_str()) };
9
10  if (ValidateSurface(
11    NextSurface, "Loading File")) {
12    SDL_FreeSurface(mImageSurface);
13    mFile = File;
14    mImageSurface = NextSurface;
15  }
16}

Reacting to Errors Externally

We should also consider whether our public functions should give external users the ability to react to errors. Whilst logging an error is helpful, it’s difficult for external code to react to logs.

SDL functions often return an integer representing whether the requested action succeeded. They generally return 0 on success and a negative number on failure.

We could use that same technique in our API. For example, let’s update SetSourceRectangle() to return 0 if the provided rectangle was valid, and -1 if it wasn’t:

1// Image.h
2// ...
3
4class Image {
5 public:
6  int SetSourceRectangle(const SDL_Rect& Rect);
7  // ...
8};

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

This makes it easier for external code to understand if their operation succeeded, and implement corrections if it didn’t.

Using Preprocessor Directives

Error checking can often have a performance cost, so it’s typically a good practice to disable it in our final release builds. We can use preprocessor directives to help us here.

For example, let’s update our Render() method to determine if our destination rectangle has been clipped. Render() is called in a hot loop, so we should be particularly mindful of performance here.

Accordingly, we’ll only perform these checks if the DEBUG preprocessor directive is defined:

1// Image.cpp
2// ...
3
4void Image::Render(SDL_Surface* Surface) {
5  #ifdef DEBUG
6  int InitialWidth = mAppliedDestRectangle.w;
7  int InitialHeight = mAppliedDestRectangle.h;
8  #endif
9
10  if (mScalingMode == ScalingMode::None) {
11    SDL_BlitSurface(
12      mImageSurface, &mAppliedSrcRectangle,
13      Surface, &mAppliedDestRectangle);
14  } else {
15    SDL_BlitScaled(
16      mImageSurface, &mAppliedSrcRectangle,
17      Surface, &mAppliedDestRectangle);
18  }
19
20  #ifdef DEBUG
21  if (InitialWidth != mAppliedDestRectangle.w) {
22    std::cout << "Horizontal clipping\n";
23  }
24  if (InitialHeight != mAppliedDestRectangle.h) {
25    std::cout << "Vertical clipping\n";
26  }
27  #endif
28}

Adding Constructors

Currently, our class has a single constructor, and that constructor requires the user to provide all the key settings:

• The file name
• The source rectangle
• The destination rectangle
• The scaling mode

There are some sensible defaults we can choose here, so let’s make our class more flexible. We’ll make the source rectangle, destination rectangle, and scaling mode optional.

When designing APIs, it can be helpful to write the code that uses the API first. For example, if I wanted to create an Image with a source rectangle, what would I like that expression to look like?

It might be something like this:

1Image Example{"img.png", {0, 0, 200, 200}};

One challenge we’ll have is that the source and destination rectangles have the same type - SDL_Rect. As such, the friendliest API will be ambiguous. The previous example could be defining a source rectangle, but it could just as easily be defining a destination rectangle.

One way to disambiguate this is to introduce new types to support our API. These types can typically be extremely simple:

1struct SourceRect : SDL_Rect {};
2struct DestRect : SDL_Rect {};

Our API can then look like this:

1Image A{"A.png", SourceRect{0, 0, 200, 200}};

Let’s add some constructors to support this:

1// Image.h
2// ...
3
4struct SourceRect : SDL_Rect {};
5struct DestRect : SDL_Rect {};
6
7class Image {
8public:
9  Image(
10    const std::string& File,
11    ScalingMode ScalingMode = ScalingMode::None
12  );
13
14  Image(
15    const std::string& File,
16    const SourceRect& SourceRect,
17    ScalingMode ScalingMode = ScalingMode::None
18  );
19
20  Image(
21    const std::string& File,
22    const DestRect& DestRect,
23    ScalingMode ScalingMode = ScalingMode::None
24  );
25
26  Image(
27    const std::string& File,
28    const SourceRect& SourceRect,
29    const DestRect& DestRect,
30    ScalingMode ScalingMode = ScalingMode::None
31  );
32
33  // ...
34};

Let’s implement these constructors. We’ll use the following behavior:

• If the user doesn’t provide a source rectangle, we’ll default it to cover the entire image.
• If the user doesn’t provide a destination rectangle, we’ll default it to the same values as the source rectangle.

1// Image.cpp
2// ...
3
4Image::Image(
5  const std::string& File,
6  ScalingMode Mode
7) : mScalingMode{Mode} {
8  LoadFile(File);
9  SetSourceRectangle({
10    0, 0, mImageSurface->w, mImageSurface->h
11  });
12  SetDestinationRectangle(mAppliedSrcRectangle);
13}
14
15Image::Image(
16  const std::string& File,
17  const SourceRect& SourceRectangle,
18  ScalingMode Mode
19) : mScalingMode(Mode) {
20  LoadFile(File);
21  SetSourceRectangle(SourceRectangle);
22  SetDestinationRectangle(mAppliedSrcRectangle);
23}
24
25Image::Image(
26  const std::string& File,
27  const DestRect& DestRectangle,
28  ScalingMode Mode
29) : mScalingMode(ScalingMode) {
30  LoadFile(File);
31  SetSourceRectangle({
32    0, 0, mImageSurface->w, mImageSurface->h
33  });
34  SetDestinationRectangle(DestRectangle);
35}
36
37Image::Image(
38  const std::string& File,
39  const SourceRect& SourceRectangle,
40  const DestRect& DestRectangle,
41  ScalingMode Mode
42) : mScalingMode(Mode) {
43  LoadFile(File);
44  SetSourceRectangle(SourceRectangle);
45  SetDestinationRectangle(DestRectangle);
46}

In situations where initialization is more complex, it can be helpful to add a private initialization function, which many constructors can defer to. For example:

1// Image.cpp
2// ...
3
4Image::Image(
5  const std::string& File,
6  ScalingMode Mode
7): mScalingMode{Mode} {
8  Initialize(
9    File,
10    {0, 0, mImageSurface->w, mImageSurface->h },
11    mAppliedSrcRectangle
12  );
13}
14
15Image::Image(
16  const std::string& File,
17  const SourceRect& SourceRectangle,
18  ScalingMode Mode
19) : mScalingMode{Mode} {
20  Initialize(
21    File,
22    SourceRectangle,
23    mAppliedSrcRectangle
24  );
25}
26
27// ...
28
29void Image::Initialize(
30  const std::string& File,
31  const SourceRect& SourceRectangle,
32  const DestRect&   DestRectangle
33) {
34  LoadFile(File);
35  SetSourceRectangle(SourceRectangle);
36  SetDestinationRectangle(DestRectangle);
37  // ... additional initialization work
38}

With these changes, consumers have a flexible and intuitive way to construct objects using our class:

1using enum ScalingMode;
2Image A{"A.png"};
3Image B{"B.png", Contain};
4Image C{"C.png", SourceRect{1,2,3,4}};
5Image D{"D.png", SourceRect{1,2,3,4}, Fill};
6Image E{"E.png", DestRect{1,2,3,4}};
7Image F{"F.png", {1,2,3,4}, {5,6,7,8}};
8Image G{"G.png", {1,2,3,4}, {5,6,7,8}, None};

1struct WithSourceRect_t{};
2WithSourceRect_t WithSourceRect;

1// Image.h
2// ...
3
4struct WithSourceRect_t{};
5WithSourceRect_t WithSourceRect;
6
7class Image{
8public:
9  Image(
10    const SDL_Rect& DestinationRectangle,
11  );
12
13  Image(
14    WithSourceRect_t,
15    const SDL_Rect& SourceRectangle,
16  );
17}

1// Providing destination rectangle
2Image A{{1, 2, 3, 4}};
3
4// Providing source rectangle
5Image B{WithSourceRect, {1, 2, 3, 4}};

Adding Setters

So far, our class offers fairly limited flexibility once it has been constructed. It can be helpful to give users the ability to change various things in an existing image.

For this, we’ll add some public setter methods. When working with more complex objects, setters typically go beyond simply updating a member variable.

They often need to do additional work to ensure the overall state of our object remains valid. Let’s see some examples with our Image class.

Setting File

The source rectangle and image surface of our objects are intrinsically linked. The source rectangle needs to overlap the image surface so, when our image surface changes, our source rectangle may need to change, too.

However, users may or may not want to provide a source rectangle. As with our constructors, we can overload a setter to provide both options:

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

If the user doesn’t provide a source rectangle, we’ll default to setting one that covers the entire image surface. Our implementation might look like this:

1// Image.cpp
2// ...
3
4void Image::SetFile(const std::string& File) {
5  LoadFile(File);
6  mRequestedSrcRectangle = {
7    0, 0, mImageSurface->w, mImageSurface->h
8  }
9  SetSourceRectangle(mRequestedSrcRectangle);
10}
11
12void Image::SetFile(
13  const std::string& File,
14  const SDL_Rect& SourceRectangle
15) {
16  LoadFile(File);
17  mRequestedSrcRectangle = SourceRectangle;
18  SetSourceRectangle(SourceRectangle);
19}

Setting Scaling Mode

Similarly, the scaling mode and destination rectangle are closely related in our class design. Again, we can give them two options to change the scaling mode - one that uses the existing destination rectangle, and one that uses a new one that they provide:

1// Image.h
2// ...
3
4class Image {
5public:
6  // ...
7  void SetScalingMode(ScalingMode Mode);
8  void SetScalingMode(ScalingMode Mode,
9    const SDL_Rect& DestinationRectangle);
10};

1// Image.cpp
2// ...
3
4void Image::SetScalingMode(ScalingMode Mode) {
5  mScalingMode = Mode;
6  SetDestinationRectangle(mAppliedSrcRectangle);
7}
8
9void Image::SetScalingMode(
10  ScalingMode Mode,
11  const SDL_Rect& DestinationRectangle
12) {
13  mScalingMode = Mode;
14  SetDestinationRectangle(DestinationRectangle);
15};

Setting Pixel Format

As a final example, let’s allow our Image objects to receive a preferred pixel format. We’ll add a setter and the associated member variable.

We’ll also add a private ConvertSurface() function, which will update our image surface to match the preferred format:

1// Image.h
2// ...
3
4class Image {
5public:
6  // ...
7  void SetPreferredFormat(
8    SDL_PixelFormat* Format);
9  
10private:
11  void ConvertSurface();
12  SDL_PixelFormat* mPreferredFormat{nullptr};
13  // ...
14};

When a preferred format is set, we’d want to convert our existing image surface to that format:

1// Image.cpp
2// ...
3
4void Image::ConvertSurface() {
5  SDL_Surface* Converted{
6    SDL_ConvertSurface(
7      mImageSurface, Format, 0)};
8  if (ValidateSurface(
9    Converted, "Converting Surface"
10  )) {
11    SDL_FreeSurface(mImageSurface);
12    mImageSurface = Converted;
13  }
14}
15
16void Image::SetPreferredFormat(
17  SDL_PixelFormat* Format) {
18  mPreferredFormat = Format;
19  ConvertSurface();
20};

Additionally, when a new image is loaded, we want to convert it to the preferred format. Let’s add that to the end of our LoadFile() function:

1// Image.cpp
2// ...
3
4void Image::LoadFile(const std::string& File) {
5  if (File == mFile) { return; }
6
7  SDL_Surface* NextSurface{ IMG_Load(
8    File.c_str()) };
9
10  if (ValidateSurface(
11    NextSurface, "Loading File")) {
12    SDL_FreeSurface(mImageSurface);
13    mFile = File;
14    mImageSurface = NextSurface;
15  }
16  
17  if (mPreferredFormat) {
18    ConvertSurface();
19  }
20}

A pixel format is often something a user would want to specify at object creation, so we’d likely want to it as a parameter on our constructors:

1// Image.h
2// ...
3
4class Image {
5public:
6  Image(
7    const std::string& File,
8    ScalingMode ScalingMode = ScalingMode::None,
9    SDL_PixelFormat* PreferredFormat = nullptr
10  );
11  // ...
12};

Adding Getters

External code would likely benefit from having access to read the current state of the object, so we’ll often add a collection of getters to our class.

Given their only purpose is to return a value - if a caller discards that return value, they’ve made a mistake. So, we’d also mark them as [[nodiscard]] so the compiler will generate warnings in that scenario:

1// Image.h
2// ...
3
4class Image {
5public:
6  [[nodiscard]]
7  int GetWidth() const {
8    return ImageSurface->w;
9  }
10
11  [[nodiscard]]
12  int GetHeight() const {
13    return ImageSurface->h;
14  }
15  
16  [[nodiscard]]
17  ScalingMode GetScalingMode() const {
18    return mScalingMode;
19  }
20  
21  // ...
22}

1// Image.h
2// ...
3
4class Image {
5public:
6  [[nodiscard]]
7  const SDL_Surface* GetSurface() {
8    return mImageSurface;
9  }
10  // ...
11}

Documentation

As a final step, we can add documentation in the form of comments to explain how our methods behave. In the introductory course, we introduced the JSDoc format:

1// Image.h
2// ...
3
4class Image {
5public:
6  /**
7   * @brief Sets the image file and source
8   * rectangle used for this object.
9   *
10   * @param File The file path to use.
11   * @param SourceRectangle The source rectangle
12   * to use when blitting.
13   * @returns 0 if successful, or a negative
14   * integer otherwise. Call SDL_GetError() for
15   * error details.
16   */
17  int SetFile(const std::string& File,
18    const SDL_Rect& SourceRectangle);
19    
20    // ...
21 }

Comments in this format can be understood by external tools, such as IDEs, making our class easier to use:

Summary

In this lesson, we've covered a range of techniques for improving our API, using examples from our Image class. We covered:

• Techniques for dealing with errors, including using preprocessor directives to minimize performance impact
• Creating constructors and setters in the context of a more complex class
• Practical examples of using comments as documentation

Remember, good class design is an iterative process - always look for ways to improve your code!

Next Lesson

Rendering Text with SDL_ttf

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

ContinueView Course