SDL ttf:Tutorials:Basic Font Rendering

From GPWiki

Introduction

SDL_ttf is an addition to SDL that provides the capability to render TrueType (*.ttf) fonts to SDL surfaces. It is a wrapper around the widely used FreeType font rasterizer. SDL_ttf is capable of using TrueType outline fonts, providing the capability to incorporate a standard font format into SDL applications.

Getting Started!

Before we jump into the code for using SDL_ttf, there are a few things we need to cover.

Finding Fonts

Before we can render fonts, we need fonts to render. But where are we going to get fonts? "That's easy, we just copy and paste whatever font we want from the Windows font directory!" Hold on there... Doing that is a very bad idea. It is illegal to copy those fonts like that. To redistribute Windows' fonts, you have to download their font installation package and run it, in the process agreeing with their EULA. That EULA is probably not something you want to enter into as a game developer, especially one writing for multiple platforms. So, now that idea's out the door, what now? Just take a quick google for "free fonts." There are tons of them available on the net, usually for free. But "Free" isn't necessarily a good thing. Many of them bind you legally in ways you don't want or are low quality. I found a couple of very good sources for fonts.The UCS Free Outline Font Project. There are only three very bland families of fonts, but they are extremely high quality and most importantly are licensed under the GPL, which does not bind you beyond making you give the fonts and everything you receive with them to the end-user, even if you are distributing your program commercially. Most of us would be doing that normally no matter what fonts we used, so it isn't much of a problem. Another good source with an even less binding liscense are the Bitstream Vera Fonts. They are very high quality and their license is quite liberal. But just because I say you should use these doesn't mean you are limited to these fonts. Explore and you should be able to find lots more good fonts. Just read their licenses and don't do anything illegal.

Just another note before you start coding: Try to pick tasteful fonts. Not every artsy font that you'll find is suitable for use in a game. Many of them look frankly awful even in the places they were designed to be used, let alone in games. It is generally a good idea to stick with the basics: Serif, Sans Serif, and for old-school games, maybe a monospace font. Look at the UCS Free Outline Font Project I mentioned in the last paragraph to get an idea of what I'm talking about. This isn't restricting you to something like this... If you honestly think that your game is one of the few that could pull off a strange font without looking bad, by all means, go ahead.

Includes and Libraries

Of course, as with any library, you don't just start writing code for it. You have to include certain code and make your linker link your application with the proper libraries.

Download the applicable SDL_ttf development package from the SDL_ttf homepage

To use SDL_ttf, you will need to first have the SDL_ttf.h file inside your include directory, wherever your particular build method keeps it (See C:How_to_set_up_your_SDL_Build_Environment for more information). Then, at the top of your code with your other include statements, add:

#include "SDL/SDL_ttf.h" 

This code assumes that the SDL_ttf.h file is under the "SDL" directory in your include folder. Yours may be just under the main directory, in that case put:

#include "SDL_ttf.h" 

Of course, if your file is in some bizzare place, change this accordingly.

Then you have to put the file that, depending upon your OS and build method may be called something like "libSDL_ttf.a" in the linker directory

The next step would be to get your linker to recognize that it needs to link your program with the SDL_ttf libraries every time you compile your program. This varies a lot depending upon your build method. Again, see C:How_to_set_up_your_SDL_Build_Environment for more information. In most build methods, you'll have to add the command line argument "-lSDL_ttf" to the end of your linker arguments. This is the same place where you will have put "-lSDL" and "-lSDLmain" if you have an already working SDL program. Hopefully by this point you have everything in the correct place.

You can download SDL_ttf by simply typing it in Google.

Code

The first thing code-wise we need to do is initialize the library, of course.

#include <stdio>
 
using namespace std;
 
if (TTF_Init() == -1) 
 
{
  printf("Unable to initialize SDL_ttf: %s \n", TTF_GetError());
  //Put here however you want to do about the error. 
  //you could say:
  //return true;
  //Or:
  //exit(1);
}

This code makes a call to TTF_Init and if it returns an error, it is reported with TTF_GetError() and then what happens after that is up to you. In some cases, you might return true; to tell the calling routine that the initialization failed or you might just want to go ahead and say exit(1); to exit the program with an error. To use exit(); you need to have said #include <cstdlib>. Now that we have to library initialized, we need to load a font

TTF_Font* loadfont(char* file, int ptsize)
{
  TTF_Font* tmpfont;
  tmpfont = TTF_OpenFont(file, ptsize);
  if (tmpfont == NULL){
    printf("Unable to load font: %s %s \n", file, TTF_GetError());
    // Handle the error here.
  }
  return tmpfont;
}

This function takes two arguments, the first a pointer to a string containing the path to the font you want to load and the second taking the point size that the font should be rendered in when we get to that step. It is used like so: font = loadfont("path/to/font.ttf", 16). Now that we have a font loaded, we have to render it!

SDL_ttf provides three different functions for rendering text to a surface. Solid rendering is quick, but dirty. Use it if you need speed more than quality. Blended rendering is the opposite of solid. Good quality, but slow. The third, Shaded is different from the other two. Shaded rendering adds a background to the rendered text. Because of this, as we will see, the shaded font rendering function takes an extra color more than the other styles to be a background color. It is as fast as solid rendering and about as good quality as blended.

enum textquality {solid, shaded, blended};
 
SDL_Surface *drawtext(TTF_Font *fonttodraw, char fgR, char fgG, char fgB, char fgA, 
char bgR, char bgG, char bgB, char bgA, char text[], textquality quality)
{
  SDL_Color tmpfontcolor = {fgR,fgG,fgB,fgA};
  SDL_Color tmpfontbgcolor = {bgR, bgG, bgB, bgA};
  SDL_Surface *resulting_text;
 
  if (quality == solid) resultint_text = TTF_RenderText_Solid(fonttodraw, text, tmpfontcolor);
  else if (quality == shaded) resulting_text = TTF_RenderText_Shaded(fonttodraw, text, tmpfontcolor, tmpfontbgcolor);
  else if (quality == blended) resulting_text = TTF_RenderText_Blended(fonttodraw, text, tmpfontcolor);
 
  return resulting_text;
}

This void take lots and lots of parameters to determine how you want your font rendered. fonttodraw is a pointer to the font that we want to render with. destsurf is a pointer to the destination surface we want to render to. fgR - fgA are the foreground colors we are rendering the text in. They are in the form of RGBA, A being alpha transparency. bgR - bgA are just like their fg counterparts except they are representing the background. These values are only used when you are rendering in the shaded mode. text is, of course, the text that we want to render. quality is a value of the enumeration textquality that tells the function what style you want your text rendered in.

That's pretty much the basics, if all you want to do is the most basic rendering. It can get much more complicated when you want to determine the font's properties in order to position it on the screen and make sure it is the right size and such, but that's another tutorial. :)

Pitfalls

If your code compiles but then crashes, check for the following common pitfalls:

• Have you given the right path to the font you are trying to load when you run TTF_OpenFont?
• Have you called TTF_Init() first?