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
5class Window {/*...*/};
45
46int main(int argc, char** argv) {
47  SDL_Init(SDL_INIT_VIDEO);
48  SDL_Event Event;
49  bool shouldQuit{false};
50
51  Window GameWindow;
52  Text TextExample{"Hello World"};
53
54  while (!shouldQuit) {
55    while (SDL_PollEvent(&Event)) {
56      if (Event.type == SDL_QUIT) {
57        shouldQuit = true;
58      }
59    }
60    GameWindow.Render();
61    TextExample.Render(GameWindow.GetSurface());
62    GameWindow.Update();
63  }
64
65  SDL_Quit();
66  return 0;
67}

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
5class Window {/*...*/};
37
38int main(int argc, char** argv) {
39  SDL_Init(SDL_INIT_VIDEO);
40  TTF_Init();
41  SDL_Event Event;
42  bool shouldQuit{false};
43
44  Window GameWindow;
45  Text Example{"Hello World"};
46
47  while (!shouldQuit) {/*...*/}
58
59  TTF_Quit();
60  SDL_Quit();
61  return 0;
62}

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.

To simplify memory management, we'll also prevent our Text objects from being copied by deleting their copy constructor and copy assignment operator. Our updated Text class looks like this:

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  Text(const Text&) = delete;
21  Text& operator=(const Text&) = delete;
22
23private:
24  TTF_Font* Font;
25};

Checking Initialization using `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};

Calling `TTF_Init()` and `TTF_Quit()` Multiple Times

As an aside, SDL_ttf keeps track of how many times TTF_Init() has been called, and will only shut down when the same number of calls to TTF_Quit() have been made.

This gives us an alternative approach to working with the library. Instead of calling TTF_Init() when our application starts, we can call it every time it is needed - for example, in the constructors of objects that use it.

We then ensure each of those initializations is matched with a TTF_Quit() call, such as in the destructors of those same objects.

The positive integer returned by TTF_WasInit() represents how many times TTF_Init() has been called, reduced by how many times TTF_Quit() has been called. If we manage the lifecycle of all our objects perfectly, the number will be 0 when our application closes.

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  Text(const Text&) = delete;
23  Text& operator=(const Text&) = delete;
24
25private:
26  void CreateSurface(std::string Content) {
27    SDL_Surface* newSurface = TTF_RenderUTF8_Blended(
28      Font, Content.c_str(), {255, 255, 255}
29    );
30    if (newSurface) {
31      SDL_FreeSurface(TextSurface);
32      TextSurface = newSurface;
33    } else {
34      std::cout << "Error creating TextSurface: "
35        << SDL_GetError() << '\n';
36    }
37  }
38
39  TTF_Font* Font{nullptr};
40  SDL_Surface* TextSurface{nullptr};
41};

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  Text(const Text&) = delete;
28  Text& operator=(const Text&) = delete;
29
30private:
31  void CreateSurface(std::string Content) {
32    SDL_Surface* newSurface = TTF_RenderUTF8_Blended(
33      Font, Content.c_str(), {255, 255, 255}
34    );
35    if (newSurface) {
36      SDL_FreeSurface(TextSurface);
37      TextSurface = newSurface;
38    } else {
39      std::cout << "Error creating TextSurface: "
40        << SDL_GetError() << '\n';
41    }
42    
43    DestinationRectangle.w = TextSurface->w * 4;
44    DestinationRectangle.h = TextSurface->h * 4;
45  }
46
47  TTF_Font* Font{nullptr};
48  SDL_Surface* TextSurface{nullptr};
49  SDL_Rect DestinationRectangle{50, 50, 0, 0};
50};

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
3class 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 TextExample{"Hello World", 100};
44
45  while (!shouldQuit) {/*...*/}
56
57  TTF_Quit();
58  SDL_Quit();
59  return 0;
60}

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

Rasters and Vectors

Font files, such as the .ttf format, store their characters in a vector format. These formats often involve a set of instructions on how to draw the lines and shapes of each character. A font's representation of a character is often called a glyph.

However, to store text in an SDL_Surface, and ultimately show it on our screen, the data needs to be in a raster format. This is the image format we're likely most familiar with - grids of small, rectangular pixels.

The process of converting vectors and other arbitrary data types to raster images is called rasterization.

The main advantage of a vector format is that it allows any algorithm that understands the format, such as TTF_RenderUTF8_Blended(), to generate raster data for a specific character by executing the instructions provided by the font.

And, like calling a function, that algorithm can include parameters such as the size we want the raster to be. This allows a font (or any other vector graphic) to be rendered at any size without losing quality.

Complete Code

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

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.

Rendering Text with `SDL_ttf`

Initializing and Quitting SDL_ttf

Error Checking

Loading and Freeing Fonts

Checking Initialization using `TTF_WasInit()`

Error Checking

Rendering Text

Surface Blitting

Source Rectangle

Destination Rectangle

Scaling Text

Complete Code

Summary

Text Performance, Fitting and Wrapping

Game Development with SDL2

Questions & Answers

Rendering Text with SDL_ttf

Initializing and Quitting SDL_ttf

Error Checking

Loading and Freeing Fonts

Checking Initialization using TTF_WasInit()

Error Checking

Rendering Text

Surface Blitting

Source Rectangle

Destination Rectangle

Scaling Text

Complete Code

Summary

Text Performance, Fitting and Wrapping

Questions & Answers

Rendering Text with `SDL_ttf`

Checking Initialization using `TTF_WasInit()`