Rendering Text with SDL_ttf

In this lesson, we’ll see how we can render text within our programs. We’ll use the official SDL_ttf extension we installed earlier in the course.

We’ll build upon the concepts we introduced in the previous chapters. Our main.cpp looks like below.

The key thing to note is that we have created a Text class, and instantiated an object from it called TextExample. This object is being asked to Render() onto the window surface every frame:

1#include <iostream>
2#include <SDL.h>
3#include "Text.h"
4
Window Class|Show
5class Window {/*...*/};
35
36int main(int argc, char** argv) {
37  SDL_Init(SDL_INIT_VIDEO);
38  SDL_Event Event;
39  bool shouldQuit{false};
40
41  Window GameWindow;
42  Text TextExample{"Hello World"};
43
44  while (!shouldQuit) {
45    while (SDL_PollEvent(&Event)) {
46      if (Event.type == SDL_QUIT) {
47        shouldQuit = true;
48      }
49    }
50    GameWindow.Render();
51    TextExample.Render(GameWindow.GetSurface());
52    GameWindow.Update();
53  }
54
55  SDL_Quit();
56  return 0;
57}

Our Text class currently looks like this, but we’ll expand it throughout this lesson:

1#pragma once
2#include <SDL.h>
3#include <SDL_ttf.h>
4
5class Text {
6 public:
7  Text(std::string Content) {}
8
9  void Render(SDL_Surface* DestinationSurface) {
10    // ...
11  }
12};

We will also need a TrueType (.ttf) file stored in the same location as our executable. The code examples and screenshots in this lesson use Roboto-Medium.ttf, available from Google Fonts.

Initializing and Quitting SDL_ttf

To use SDL_ttf in our application, we #include the SDL_ttf.h header file. We then call TTF_Init() to initialize the library, and TTF_Quit() to close it down:

1#include <SDL.h>
2#include <SDL_ttf.h>
3#include "Text.h"
4
Window Class|Show
5class Window {/*...*/};
35
36int main(int argc, char** argv) {
37  SDL_Init(SDL_INIT_VIDEO);
38  TTF_Init();
39  SDL_Event Event;
40  bool shouldQuit{false};
41
42  Window GameWindow;
43  Text Example{"Hello World"};
44
Application Loop|Show
45  while (!shouldQuit) {/*...*/}
56
57  TTF_Quit();
58  SDL_Quit();
59  return 0;
60}

Error Checking

TTF_Init() returns 0 if it succeeds, and a negative error code if it fails. We can check for this error state, and call SDL_GetError() for an explanation:

1if (TTF_Init() < 0) {
2  std::cout << "Error initializing SDL_ttf: "
3    << SDL_GetError();
4}

Loading and Freeing Fonts

To create text in our application, we first need to load a font. To do this, we call TTF_OpenFont(), passing the path to our font file, and the font size we want to use:

1TTF_OpenFont("Roboto-Medium.ttf", 50);

This function creates a TTF_Font object and returns a pointer to it. To prevent memory leaks, we pass this pointer to TTF_CloseFont() when we no longer need it.

Let’s update our Text class:

1#pragma once
2#include <SDL.h>
3#include <SDL_ttf.h>
4
5class Text {
6 public:
7  Text(std::string Content) : Font {
8    TTF_OpenFont("Roboto-Medium.ttf", 50)
9  } {
10
11  }
12
13  void Render(SDL_Surface* DestinationSurface) {
14
15  }
16
17  ~Text() {
18    TTF_CloseFont(Font);
19  }
20
21private:
22  TTF_Font* Font;
23};

TTF_WasInit()

If we call TTF_CloseFont() when SDL_ttf is not initialized, our program can crash. Issues like this are most common during the "cleanup" phase of our application, where we’re trying to shut everything down cleanly.

In our example, the TextExample object’s destructor isn’t called until main() ends. However, before main() ends, we call TTF_Quit(), meaning by the time ~TextExample() calls TTF_CloseFont(), SDL_ttf has already been shut down.

We can test for this scenario using TTF_WasInit(). The TTF_WasInit() function returns a positive integer if SDL_ttf is currently initialized, so we can make our class more robust like this:

1// Text.h
2class Text {
3  // ...
4
5  ~Text() {
6    if (TTF_WasInit()) {
7      TTF_CloseFont(Font);
8    }
9  }
10  
11  // ...
12};

Error Checking

If TTF_OpenFont() failed, it will return a nullptr. We can check for this, and log out the error for an explanation:

1// Text.h
2class Text {
3 public:
4  Text(std::string Content) : Font {
5    TTF_OpenFont("Roboto-Medium.ttf", 50)
6  } {
7    if (!Font) {
8      std::cout << "Error loading font: "
9        << SDL_GetError();
10    }
11  }
12  
13  // ...
14};

Rendering Text

From a high level, the process of rendering text is very similar to rendering images:

• We generate an SDL_Surface containing the pixel data representing our text
• We blit that surface onto another surface, using functions like SDL_BlitSurface()

There are many options we can use to generate our surface. We’ll explain their differences in the next lesson. For now, we’ll use TTF_RenderUTF8_Blended(). This function requires three arguments:

• The font we want to use, as an SDL_Font pointer
• The text we want to render, as a C-style string
• The color we want to use, as an SDL_Color

For example:

1TTF_RenderUTF8_Blended(
2  Font,
3  "Hello World",
4  SDL_Color{255, 255, 255} // White
5)

SDL will render our text onto SDL_Surface, containing the pixel data we need to display the text. It will return a pointer to that surface, or a nullptr if the process failed. We can therefore check for errors in the usual way:

1SDL_Surface* TextSurface{
2  TTF_RenderUTF8_Blended(
3    Font, "Hello World", {255, 255, 255}
4  )
5};
6
7if (!TextSurface) {
8  std::cout << "Error creating TextSurface: "
9    << SDL_GetError();
10}

Let’s add this capability to our class as a private CreateSurface() method. We’ll additionally:

• Add a TextSurface member to store a pointer to the generated surface
• Call SDL_FreeSurface() from the destructor to release the surface when we no longer need it.
• Call SDL_FreeSurface() before we replace the existing TextSurface with a new one. This is not currently necessary as we’re only calling CreateSurface() once per object lifecycle, but we’ll expand our class later.
• Call CreateSurface() from our constructor to ensure our Text objects are initialized with a TextSurface

1// Text.h
2class Text {
3 public:
4  Text(std::string Content) : Font {
5    TTF_OpenFont("Roboto-Medium.ttf", 50)
6  } {
7    if (!Font) {
8      std::cout << "Error loading font: "
9        << SDL_GetError();
10    }
11    CreateSurface(Content);
12  }
13
14  void Render(SDL_Surface* DestinationSurface) {
15
16  }
17
18  ~Text() {
19    SDL_FreeSurface(TextSurface);
20    TTF_CloseFont(Font);
21  }
22
23private:
24  void CreateSurface(std::string Content) {
25    SDL_Surface* newSurface = TTF_RenderUTF8_Blended(
26      Font, Content.c_str(), {255, 255, 255}
27    );
28    if (newSurface) {
29      SDL_FreeSurface(TextSurface);
30      TextSurface = newSurface;
31    } else {
32      std::cout << "Error creating TextSurface: "
33        << SDL_GetError() << '\n';
34    }
35  }
36
37  TTF_Font* Font{nullptr};
38  SDL_Surface* TextSurface{nullptr};
39};

Surface Blitting

After creating an SDL_Surface containing our rendered text, we can display it on the screen using a process called blitting. Blitting involves copying the pixel data from one surface (our text surface) to another (the window surface).

We covered blitting in much more detail when working with images earlier in the chapter.

In our current setup, the Text::Render() method receives the window surface as a parameter. By blitting our TextSurface onto this window surface, we draw the text onto the window:

1// Text.h
2class Text {
3 public:
4  // ...
5
6  void Render(SDL_Surface* DestinationSurface) {
7    SDL_BlitSurface(
8      TextSurface, nullptr,
9      DestinationSurface, nullptr
10    );
11  }
12  
13  // ...
14};

Source Rectangle

As with any call to SDL_BlitSurface(), we can pass pointers to the 2nd and 4th arguments. These are pointers to SDL_Rect objects representing the source and destination rectangles respectively.

When working with text, it is fairly unusual that we would specify a source rectangle. The text we generated fills the entire SDL_Surface created by SDL_ttf. However, we can still crop it if we have some reason to:

1// Text.h
2class Text {
3 public:
4  // ...
5
6  void Render(SDL_Surface* DestinationSurface) {
7    SDL_BlitSurface(
8      TextSurface, &SourceRectangle,
9      DestinationSurface, nullptr
10    );
11  }
12  
13  // ...
14
15private:
16  void CreateSurface(std::string Content) {
17    SDL_Surface* newSurface = TTF_RenderUTF8_Blended(
18      Font, Content.c_str(), {255, 255, 255}
19    );
20    if (newSurface) {
21      SDL_FreeSurface(TextSurface);
22      TextSurface = newSurface;
23    } else {
24      std::cout << "Error creating TextSurface: "
25        << SDL_GetError() << '\n';
26    }
27    
28    SourceRectangle.w = TextSurface->w - 50;
29    SourceRectangle.h = TextSurface->h - 20;
30  }
31
32  TTF_Font* Font{nullptr};
33  SDL_Surface* TextSurface{nullptr};
34  SDL_Rect SourceRectangle{0, 0, 0, 0};
35};

Destination Rectangle

More commonly, we’ll want to provide a destination rectangle with x and y values, controlling where the text is placed within the destination surface:

1// Text.h
2class Text {
3 public:
4  // ...
5  void Render(SDL_Surface* DestinationSurface) {
6    SDL_BlitSurface(
7      TextSurface, nullptr,
8      DestinationSurface, &DestinationRectangle
9    );
10  }
11
12private:
13  // ...
14  SDL_Rect DestinationRectangle{50, 50, 0, 0}; 
15};

As we covered in our image rendering lessons, SDL_BlitSurface() will update the w and h values of this rectangle with the size of our output within the destination surface.

If these values are smaller than the width and height of our source surface (or source rectangle, if we’re using one) that indicates that our text did not fit within the destination surface at the location we specified:

1// Text.h
2class Text {
3 public:
4  Text(std::string Content) : Font {
5    TTF_OpenFont("Roboto-Medium.ttf", 150)
6  } {
7    if (!Font) {
8      std::cout << "Error loading font: "
9        << SDL_GetError();
10    }
11    CreateSurface(Content);
12  }
13
14  void Render(SDL_Surface* DestinationSurface) {
15    SDL_BlitSurface(
16      TextSurface, nullptr,
17      DestinationSurface, &DestinationRectangle
18    );
19    if (DestinationRectangle.w < TextSurface->w) {
20      std::cout << "Clipped horizontally\n";
21    }
22    if (DestinationRectangle.h < TextSurface->h) {
23      std::cout << "Clipped vertically\n";
24    }
25  }
26
27  // ...
28};

1Clipped horizontally
2Clipped horizontally
3Clipped horizontally
4...

Scaling Text

As with any surface, we can add scaling to the blitting process using SDL_BlitScaled(). However, we should avoid doing this where possible. Scaling an image causes a loss of quality, and this can be particularly noticeable with text.

Let’s temporarily update Render() and CreateSurface() to increase the size of our text using scaled blitting, and note the quality loss:

1// Text.h
2class Text {
3 public:
4  Text(std::string Content) : Font {
5    TTF_OpenFont("Roboto-Medium.ttf", 25)
6  } {
7    if (!Font) {
8      std::cout << "Error loading font: "
9        << SDL_GetError();
10    }
11    CreateSurface(Content);
12  }
13
14  void Render(SDL_Surface* DestinationSurface) {
15    SDL_BlitScaled(
16      TextSurface, nullptr,
17      DestinationSurface, &DestinationRectangle
18    );
19  }
20
21  ~Text() {
22    SDL_FreeSurface(TextSurface);
23    if (TTF_WasInit()) {
24      TTF_CloseFont(Font);
25    }
26  }
27
28private:
29  void CreateSurface(std::string Content) {
30    SDL_Surface* newSurface = TTF_RenderUTF8_Blended(
31      Font, Content.c_str(), {255, 255, 255}
32    );
33    if (newSurface) {
34      SDL_FreeSurface(TextSurface);
35      TextSurface = newSurface;
36    } else {
37      std::cout << "Error creating TextSurface: "
38        << SDL_GetError() << '\n';
39    }
40    
41    DestinationRectangle.w = TextSurface->w * 4;
42    DestinationRectangle.h = TextSurface->h * 4;
43  }
44
45  TTF_Font* Font{nullptr};
46  SDL_Surface* TextSurface{nullptr};
47  SDL_Rect DestinationRectangle{50, 50, 0, 0};
48};

Instead, we can just render the text at the correct size we want, by setting the font size. Our constructor is currently setting the font size to 20. Let’s change that to be a constructor argument:

1// Text.h
2class Text {
3 public:
4  Text(std::string Content, int Size = 25)
5  : Font {
6    TTF_OpenFont("Roboto-Medium.ttf", Size)
7  } {
8    if (!Font) {
9      std::cout << "Error loading font: "
10        << SDL_GetError();
11    }
12    CreateSurface(Content);
13  }
14  // ...
15};

The TTF_SetFontSize() function also lets us change the size of a font we’ve already loaded. Let’s use this in a new SetFontSize() method, allowing consumers to change the font size without needing to create an entirely new object:

1// Text.h
2class Text {
3 public:
4  // ...
5  void SetFontSize(int NewSize) {
6    TTF_SetFontSize(Font, NewSize);
7  }
8  // ...
9};

Let’s increase our font size, and notice the quality improvement over using SDL_BlitScaled():

1// main.cpp
2
Window Class|Show
3class Window {/*...*/};
33
34int main(int argc, char** argv) {
35  SDL_Init(SDL_INIT_VIDEO);
36  TTF_Init();
37  SDL_Event Event;
38  bool shouldQuit{false};
39
40  Window GameWindow;
41  Text TextExample{"Hello World", 100};
42
Application Loop|Show
43  while (!shouldQuit) {/*...*/}
54
55  TTF_Quit();
56  SDL_Quit();
57  return 0;
58}

We cover more techniques related to scaling in the next lesson.

Complete Code

Complete versions of the files we created in this lesson are available below:

1#include <iostream>
2#include <SDL.h>
3#include <SDL_ttf.h>
4#include "Text.h"
5
6class Window {
7public:
8  Window() {
9    SDLWindow = SDL_CreateWindow(
10      "My Program", SDL_WINDOWPOS_UNDEFINED,
11      SDL_WINDOWPOS_UNDEFINED, 600, 300, 0);
12  }
13
14  void Render() {
15    SDL_FillRect(
16      GetSurface(), nullptr, SDL_MapRGB(
17        GetSurface()->format, 50, 50, 50
18      )
19    );
20  }
21
22  void Update() {
23    SDL_UpdateWindowSurface(SDLWindow);
24  }
25
26  SDL_Surface* GetSurface() {
27    return SDL_GetWindowSurface(SDLWindow);
28  }
29
30  ~Window() { SDL_DestroyWindow(SDLWindow); }
31
32private:
33  SDL_Window* SDLWindow;
34};
35
36int main(int argc, char** argv) {
37  SDL_Init(SDL_INIT_VIDEO);
38  TTF_Init();
39  SDL_Event Event;
40  bool shouldQuit{false};
41
42  Window GameWindow;
43  Text TextExample{"Hello World", 100};
44
45  while (!shouldQuit) {
46    while (SDL_PollEvent(&Event)) {
47      if (Event.type == SDL_QUIT) {
48        shouldQuit = true;
49      }
50    }
51    GameWindow.Render();
52    TextExample.Render(GameWindow.GetSurface());
53    GameWindow.Update();
54  }
55
56  TTF_Quit();
57  SDL_Quit();
58  return 0;
59}

1#pragma once
2#include <SDL.h>
3#include <SDL_ttf.h>
4
5class Text {
6 public:
7  Text(std::string Content, int Size = 25)
8  : Font {
9    TTF_OpenFont("Roboto-Medium.ttf", Size)
10  } {
11    if (!Font) {
12      std::cout << "Error loading font: "
13        << SDL_GetError();
14    }
15    CreateSurface(Content);
16  }
17
18  void SetFontSize(int NewSize) {
19    TTF_SetFontSize(Font, NewSize);
20  }
21
22  void Render(SDL_Surface* DestinationSurface) {
23    SDL_BlitSurface(
24      TextSurface, nullptr,
25      DestinationSurface, &DestinationRectangle
26    );
27  }
28
29  ~Text() {
30    SDL_FreeSurface(TextSurface);
31    if (TTF_WasInit()) {
32      TTF_CloseFont(Font);
33    }
34  }
35
36private:
37  void CreateSurface(std::string Content) {
38    SDL_Surface* newSurface = TTF_RenderUTF8_Blended(
39      Font, Content.c_str(), {255, 255, 255}
40    );
41    if (newSurface) {
42      SDL_FreeSurface(TextSurface);
43      TextSurface = newSurface;
44    } else {
45      std::cout << "Error creating TextSurface: "
46        << SDL_GetError() << '\n';
47    }
48  }
49
50  TTF_Font* Font{nullptr};
51  SDL_Surface* TextSurface{nullptr};
52  SDL_Rect DestinationRectangle{0, 0, 0, 0};
53};

Summary

In this lesson, we've explored the fundamentals of rendering text in SDL2 using the SDL_ttf extension. We've covered:

• Initializing and quitting SDL_ttf
• Loading and freeing fonts
• Creating text surfaces
• Rendering text to the screen
• Handling potential errors in text rendering
• Basic text positioning and scaling

In the next lesson, we’ll expand on these concepts further, covering more advanced use cases.

Next Lesson

Text Performance, Fitting and Wrapping

Explore advanced techniques for optimizing and controlling text rendering when using SDL_ttf

ContinueView Course